@selesai/code 0.8.4 → 0.8.6

package/dist/extensions/inline-skills.ts

@@ -22,6 +22,9 @@ function getSkillName(command: SkillCommand): string {
 
 function getInlineSkillToken(textBeforeCursor: string): string | undefined {
 	const match = textBeforeCursor.match(/(?:^|[^a-z0-9_-])\$([a-z0-9-]*)$/i);
+	// Group 1 is always present when the regex matches (it can be empty but
+	// never undefined), so the ?? fallback is unreachable.
+	/* v8 ignore next 1 */
 	return match ? match[1] ?? "" : undefined;
 }
 

package/dist/extensions/pi-subagents/CHANGELOG.md

@@ -2,9 +2,9 @@
 
 ## [Unreleased]
 
-## Selesai fork (0.47.1)
+## Selesai fork (0.48.0)
 
-Selesai vendors pi-subagents 0.47.1 and layers its own branding and additions on top:
+Selesai vendors pi-subagents 0.48.0 and layers its own branding and additions on top:
 
 ### Branding
 - Host package renamed from `@earendil-works/pi-coding-agent` to `@selesai/code`.
@@ -12,7 +12,7 @@ Selesai vendors pi-subagents 0.47.1 and layers its own branding and additions on
 - Extension env vars renamed `PI_SUBAGENT*` → `SELESAI_SUBAGENT*` (legacy `PI_SUBAGENT*` values still honored via `src/shared/env.ts`).
 - Home directory is never treated as a project root for subagent config resolution.
 
-### Selesai additions (upstream 0.47.1 features are all preserved)
+### Selesai additions (upstream 0.48.0 features are all preserved)
 - Agent roster extended with Selesai personas: `architect`, `builder`, `commentator`, `explorer`, `recapper` (upstream `worker`, `reviewer`, `scout`, `oracle`, `delegate`, `researcher` remain). `researcher` is the Selesai host-compatible brief generator.
 - Declarative `chain` / `tasks` execution and saved `.chain.md` / `.chain.json` workflows promoted to first-class documented surfaces (machinery ships in 0.47.1).
 - New slash commands: `/chain`, `/parallel`, `/run-chain`, `/chain-prompts`.
@@ -22,6 +22,29 @@ Selesai vendors pi-subagents 0.47.1 and layers its own branding and additions on
 - Prompt templates: `parallel-context-build`, `parallel-handoff-plan`.
 - `chatProgress` extended with `terminal` / `milestones` projections.
 
+## [0.48.0] - 2026-08-13
+
+### Added
+- Add a durable per-run child fan-out budget with a default cap of 64 across static, dynamic, workflow, and nested child admissions. Thanks to @asjer for #1031.
+- Add an opt-in per-session cap for concurrently active top-level async runs, with atomic admission, resume transfer, status/Fleet/RPC/doctor visibility, and release gated by the verified process-terminal behavior from #1030. Thanks to @asjer for #1029.
+- Add a live Prompt Audit drawer to Fleet for current-session foreground children. Prompt text is visible in the drawer, kept outside serializable Fleet state, and redacted from foreground input, transcript, metadata, result, progress, and run-history artifacts (#1021).
+- Add a global `timeoutMs` config option that sets the default run deadline for single, parallel, and chain launches (foreground, plus plain single-agent async) when neither the call nor the selected agent provides a timeout. It reaches parallel (`tasks: [...]`) and chain launches, which never adopt an agent's frontmatter `timeoutMs` (that default applies to single-agent launches only), so a long fan-out no longer falls back to the built-in 30-minute default and gets killed mid-run. Explicit call `timeoutMs`/`maxRuntimeMs` and agent frontmatter defaults still win; composite async runs stay unbounded at the top level by design. Thanks to @shaharmor for #1018.
+- Add a `SELESAI_SUBAGENT_TASK_DELIVERY` environment setting (`auto` | `file`, default `auto`) controlling how the task text reaches child Pi processes. `file` writes the task to a temp `task.md` referenced as `@<path>` instead of embedding it in argv, for hosts where endpoint protection (EDR) pre-execution command-line scanning denies children whose argv embeds a long natural-language task. Thanks to @yanqianglu for #1028.
+- Escalate startup retries to file task delivery after an unexplained zero-activity `SIGKILL` child exit, so EDR-denied launches self-heal on retry in both foreground and background runs. Thanks to @yanqianglu for #1028.
+
+### Fixed
+- Open Fleet Prompt Audit with the authored task visible by default and show a short live task summary in the normal Fleet detail pane (#1021).
+- Use full task-text hashes for LLM intent arbiter memoization so same-prefix review and implementation tasks cannot share a cached verdict.
+- Terminate async Pi writers as owned POSIX process groups on stop and timeout, and keep terminal process proof unknown until process-tree exit is verified. Thanks to @asjer for #1030.
+- Explain when a requested mission is scoped to another worktree by naming the current project root and mission directory (#1024).
+- Preserve the configured output reference when explicit acceptance rejects an otherwise completed foreground child, so useful reports remain available (#1023).
+- Reject configured worktree base directories inside the agent extensions directory, including symlink aliases (#1014).
+- Align unnamed intercom fallback orchestrator targets with pi-intercom's 18-character registered presence names so subagents without an explicit session name can reach their orchestrator. Thanks to @mystery4f for #1017.
+- Stop reading hyphenated adjectives like "must-fix items" or "should-fix tests" as implementation intent, which made the completion mutation guard hard-fail read-only review runs with a false "completed without making edits" error. Severity compounds (must|should|needs + dash + verb) are stripped before verb matching across every mutation pattern (incl. update/add/apply/make/do siblings), the acceptance-level write-capability check, and the patch-scope pattern, while CLI flags ("eslint --fix", "prettier --write") and clause-level dashes ("branch—fix it") keep their write intent. Thanks to @MarcusNeufeldt for #1020.
+- Add an optional LLM intent arbiter: when the completion guard is about to hard-fail a run that made no edits, a model decides — from the task text alone, never the child's own report — whether the task actually instructed file changes; only a confident read-only verdict rescues the run, before any failure state is published. Covers single, parallel, and chain foreground runs; enabled by default; set `SELESAI_SUBAGENTS_LLM_INTENT_ARBITER=0` to disable. Thanks to @MarcusNeufeldt for #1020.
+- Tolerate empty-string entries in acceptance-report string-array fields instead of rejecting the whole report. Thanks to @hjiang for #1015.
+- Let single external-cli workflow children ignore inherited Pi models so model-less external runners start instead of failing preflight. Thanks to @twosunnus for #1016.
+
 ## [0.47.1] - 2026-08-12
 
 ### Fixed

package/dist/extensions/pi-subagents/README.md

@@ -99,6 +99,8 @@ In the TUI, a persistent FleetView below the editor keeps active work visible. `
 
 Details, keybindings, and the machine-readable run artifacts are in [Observability](https://github.com/nicobailon/pi-subagents/blob/main/docs/observability.md).
 
+For bounded orchestration, `maxSubagentSpawnsPerRun` limits cumulative logical children in one run tree. It defaults to 64 and stays separate from active concurrency and the session-wide cumulative spawn budget. See [Configuration](https://github.com/nicobailon/pi-subagents/blob/main/docs/configuration.md#maxsubagentspawnsperrun).
+
 ## If something feels off
 
 ```text

package/dist/extensions/pi-subagents/agents/builder.md

@@ -21,12 +21,15 @@ Rules:
 - If a required product, architecture, or scope decision is not approved: when the injected bridge instructions make `contact_supervisor` available, use it with `reason: "need_decision"` and wait; otherwise stop, do not guess, and report the exact blocking decision in your final response.
 - Do not launch subagents. Do not send routine completion handoffs.
 - Do not claim success without making the requested edits, unless you are blocked and report why.
+- If the task specifies a progress file path, append a `## Round N` entry to that file before finishing (use the round number from the task; if none is given, count existing `## Round` entries and add one). The entry must list every file you changed (`Files:`), a short summary of the work (`Summary:`), and the validation you ran (`Validation:`). If the task names no progress file, skip this.
 
 Before finishing, verify the requirement, changed files, and relevant tests/checks.
 
 Final response:
 
 Implemented: ...
-Changed files: ...
-Validation: ...
+Progress:
+Files: ... (every file changed)
+Summary: ... (one or two lines on what was done)
+Validation: ... (checks run and outcome)
 Open risks/questions: ...

package/dist/extensions/pi-subagents/agents/commentator.md

@@ -14,7 +14,7 @@ acceptanceRole: read-only
 
 You are a review-only subagent. Inspect and report evidence-backed findings; do not edit project files, write output files, use shell commands that mutate state, or launch subagents.
 
-Review the supplied target directly. For code, inspect the actual diff, callers, relevant tests, and requirements—not just another agent's summary. Use `bash` only for read-only inspection or test commands.
+Review the supplied target directly. If the task names a progress file, read it first and scope your review to its latest round entry: inspect the diff restricted to the files that entry lists (`git diff -- <files>`). Older entries are already reviewed—re-inspect only files the latest entry repeats. If no progress file is named, or it is missing or empty, review the full uncommitted diff. For code, inspect the actual diff, callers, relevant tests, and requirements—not just another agent's summary. Use `bash` only for read-only inspection or test commands.
 
 Check:
 - correctness, regressions, edge cases, and plan/requirement adherence;

package/dist/extensions/pi-subagents/docs/configuration.md

@@ -115,6 +115,18 @@ This is different from `waitTool.enabled=false`, which returns immediately witho
 
 Forces depth-0 internal single, parallel, and chain runs into background mode and bypasses launch UI by forcing `clarify: false`. Nested calls keep their own inherited settings.
 
+## `timeoutMs`
+
+```json
+{ "timeoutMs": 3600000 }
+```
+
+Global default runtime deadline, in milliseconds, for subagent runs. It replaces the built-in 30-minute backstop for foreground launches (single, parallel, chain, and workflowScript) and plain single-agent async runs whenever no call-level `timeoutMs`/`maxRuntimeMs` applies. For single-agent launches, selected agent frontmatter `timeoutMs` still wins. This only moves the *default*.
+
+Use it when foreground orchestration or plain async single-agent runs need a longer default than 30 minutes. It does not set async composite top-level deadlines, and it does not replace async fan-out child deadlines.
+
+Composite async runs (async chains, parallel tasks, and scripted workflows) stay unbounded at the top level by design. Their runner children are bounded individually by their own agent or runner defaults, so this value does not cap them. Must be a positive integer no greater than `2147483647` (the largest delay a Node.js timer can honor, roughly 24.8 days); invalid or out-of-range values are ignored and the built-in defaults apply.
+
 ## `globalConcurrencyLimit`
 
 ```json
@@ -131,9 +143,39 @@ Caps simultaneously running children inside existing durable legacy multi-child
 
 Optionally caps the total number of child subagent launches during one parent session, including completed and failed children, parallel task counts, static chain steps, and bounded dynamic fanout children. Sessions are unlimited by default. Set this value to `0` to disable a configured cap. `SELESAI_SUBAGENT_MAX_SPAWNS_PER_SESSION` overrides the config for a process and follows the same positive-cap/zero-unlimited semantics.
 
-`subagent({ action: "status" })`, fleet status, and `subagent({ action: "doctor" })` expose used, effective limit, remaining capacity, grants, and the remaining grant allowance. Static chains and parallel calls fail before creating run artifacts or starting partial work when their declared capacity cannot fit. Later retries or unbounded dynamic work are not guaranteed by that preflight.
+`subagent({ action: "status" })`, fleet status, and `subagent({ action: "doctor" })` expose used, effective limit, remaining capacity, grants, and the remaining grant allowance for this budget. A user may explicitly call `subagent({ action: "grant-spawn-budget", additional: 10 })` from the root interactive parent after all children settle and confirm the native prompt. Grants are additive: they never erase cumulative usage, are rejected for unlimited sessions and child/headless callers, and total granted capacity cannot exceed the original configured cap. Compaction remains part of the same logical parent session and does not reset usage or grants; starting a new parent session does.
+
+## `maxSubagentSpawnsPerRun`
 
-A user may explicitly call `subagent({ action: "grant-spawn-budget", additional: 10 })` from the root interactive parent after all children settle and confirm the native prompt. Grants are additive: they never erase cumulative usage, are rejected for unlimited sessions and child/headless callers, and total granted capacity cannot exceed the original configured cap. Compaction remains part of the same logical parent session and does not reset usage or grants; starting a new parent session does.
+```json
+{ "maxSubagentSpawnsPerRun": 64 }
+```
+
+Caps cumulative logical child admissions in one top-level run tree. The default is `64`. `SELESAI_SUBAGENT_MAX_SPAWNS_PER_RUN` overrides the config when it is a positive integer. Invalid, zero, or missing values fall back to the configured positive value or `64`.
+
+The budget counts single launches, expanded `tasks`/`count`, static chain steps and parallel groups, actual dynamic `expand` items, appended chain steps, workflow children, and nested child calls. Static and materialized dynamic groups are admitted atomically. Startup retries, model fallback, and retained-child resume reuse the original logical child claim. Claims are never released or refunded. This cap is independent from the session-wide cumulative spawn budget and `globalConcurrencyLimit`.
+
+## `maxWorkflowAutoRelaunches`
+
+```json
+{ "maxWorkflowAutoRelaunches": 12 }
+```
+
+Maximum automatic relaunches when an async scripted workflow ends with a fan-out `budget` result before the goal is clean. Each relaunch re-runs the same `workflowScript` as a fresh top-level run with a new fan-out budget, the same mission, and the same progress file, so the loop keeps building until the commentator reports clean. Defaults to 12; `0` means unlimited. When the cap is reached, the workflow completes as `failed` with a note to raise the cap or relaunch manually. Foreground workflows are unaffected — their budget results surface to the parent inline.
+
+## `maxActiveAsyncRunsPerSession`
+
+```json
+{ "maxActiveAsyncRunsPerSession": 4 }
+```
+
+Optionally caps concurrently active top-level async runs owned by one parent session. Unset or `0` keeps the existing unlimited behavior. A positive integer reserves one slot before an async single, parallel, chain, or workflow creates run artifacts or starts children. Foreground runs and nested/workflow children do not reserve another slot.
+
+Queued, running, paused, and needs-attention runs retain capacity. Runner-backed slots release only after terminal logical state and matching observed process-terminal proof from #1030. Missing, malformed, or unknown cleanup proof retains the slot. A terminal async workflow releases after its controller is gone and every launched child is accounted for: awaited foreground children are covered by workflow settlement, while actual background children still require observed process-terminal proof. Resume transfers the source slot without a second charge. Dismissal and history cleanup do not release capacity.
+
+This limit bounds current top-level async load. It is separate from cumulative `maxSubagentSpawnsPerSession`, `maxSubagentSpawnsPerRun`, and `globalConcurrencyLimit`.
+
+`subagent({ action: "status" })`, fleet status, and `subagent({ action: "doctor" })` expose used, effective limit, and remaining active capacity. Static chains and parallel calls fail before creating run artifacts or starting partial work when their declared capacity cannot fit. Later retries or unbounded dynamic work are not guaranteed by that preflight.
 
 ## `scheduledRuns`
 
@@ -196,6 +238,16 @@ export SELESAI_SUBAGENT_PI_BINARY=/path/to/pi-or-wrapper
 
 Overrides the command used to launch child Selesai processes. Package wrappers can set this to their own `pi`/agent binary so subagents inherit wrapper flags, environment setup, and bundled resources without relying on `PATH` ordering. Empty or whitespace-only values are ignored.
 
+## `SELESAI_SUBAGENT_TASK_DELIVERY`
+
+```bash
+export SELESAI_SUBAGENT_TASK_DELIVERY=file   # auto | file (default: auto)
+```
+
+Controls how the task text reaches the child Pi process. `auto` (default) passes short tasks as an inline argv token and writes tasks longer than 8000 characters to a temp `task.md` referenced as `@<path>`. `file` always uses a temp file, keeping the task out of argv entirely.
+
+Use `file` on hosts where endpoint protection (EDR) pre-execution scanning denies child processes whose command line embeds a long natural-language task — that denial surfaces as an immediate zero-activity `SIGKILL`. Independently of this setting, startup retries automatically escalate to file delivery after an unexplained zero-activity `SIGKILL`. Empty, whitespace-only, or unrecognized values fall back to `auto`.
+
 ## `intercomBridge`
 
 ```json

package/dist/extensions/pi-subagents/docs/observability.md

@@ -4,7 +4,7 @@ Where running subagents show up, how to inspect them, and the files and events t
 
 ## Foreground runs
 
-Foreground runs stream progress in the conversation while they run. They default to a generous 30-minute wall-clock timeout when neither the call nor the selected agent provides a timeout; explicit `timeoutMs`/`maxRuntimeMs` and agent defaults win.
+Foreground runs stream progress in the conversation while they run. They default to a generous 30-minute wall-clock timeout when neither the call nor the selected agent provides a timeout; a global [`timeoutMs`](configuration.md#timeoutms) config replaces that default, and explicit `timeoutMs`/`maxRuntimeMs` and agent defaults win.
 
 Live progress shows compact detail for single, chain, and parallel modes: current tool, recent output, token counts, aggregate cost, duration, activity freshness, current-tool duration, and chain graph metadata when available.
 

package/dist/extensions/pi-subagents/docs/tool-reference.md

@@ -43,7 +43,7 @@ Parameters and actions for the `subagent` tool. These are what the LLM passes wh
 | `agentScope` | `user \| project \| both` | `both` | Agent discovery scope. Project wins on collisions. |
 | `async` | boolean | default-on | Background execution. Workflows default to background and accept `async:false` as an explicit foreground escape hatch. |
 | `chatProgress` | `auto \| off \| live-card` | `auto` | WorkflowScript chat projection. `auto` renders a live in-chat card only for watched foreground workflows in the same Git repository, including managed worktrees; it is off otherwise. Explicit `live-card` requires `async:false` and the same Git repository. |
-| `timeoutMs` / `maxRuntimeMs` | number | 30 min foreground; none async | Optional run-level max runtime in milliseconds. Foreground uses 30 minutes when omitted. Async runs have no default timeout, including async workflows. |
+| `timeoutMs` / `maxRuntimeMs` | number | config `timeoutMs`, else 30 min foreground / single-agent async | Optional run-level max runtime in milliseconds. When omitted, the global [`timeoutMs`](configuration.md#timeoutms) config provides the default; absent that, foreground and plain single-agent async runs fall back to 30 minutes, while composite async runs (chains, parallel tasks, workflows) stay unbounded at the top level. |
 | `turnBudget` | object | none | Optional assistant-turn budget `{ maxTurns, graceTurns }`. At `maxTurns` the child is warned to wrap up. After the grace window (default 1), termination occurs at the next assistant boundary; a response that starts tool work records `termination-deferred` until a later boundary. Partial output is returned on abort. |
 | `toolBudget` | object | none | Optional child tool-call budget `{ soft?, hard, block? }`. At `soft` the child is nudged to finalize. After `hard`, configured tools are blocked; `block` defaults to `read`, `grep`, `find`, and `ls`, while `"*"` blocks every tool call. Final assistant text is never blocked. |
 | `usageBudget` | object | none | Optional root-only reported-usage budget `{ tokens?: { soft?, hard }, costUsd?: { soft?, hard } }`. Soft limits are status-only. Hard limits prevent later child launches after reported usage is reconciled; already-running children are not stopped and no reservations are made. |

package/dist/extensions/pi-subagents/docs/workflows.md

@@ -62,7 +62,7 @@ return runs.run("test", { agent: "worker", task });
 
 A plain workflow creates one enclosing mission by default. Its children do not create separate missions. The result exposes the id as `details.missionId`, and human-readable output ends with `Mission: <id> (<status>)`. Pass `mission:false` for an ephemeral workflow with no mission or durable `state` global.
 
-For watched same-repo workflows, pass `async:false` to show the live in-chat workflow card. `chatProgress` can force `off` or `live-card` when the automatic policy is not what you want. Foreground workflows default to a 30-minute timeout; async workflows have no default timeout. See the [tool reference](tool-reference.md) for the full parameter list.
+For watched same-repo workflows, pass `async:false` to show the live in-chat workflow card. `chatProgress` can force `off` or `live-card` when the automatic policy is not what you want. Foreground workflows default to a 30-minute timeout; async workflows have no default timeout. Async workflows that end with a fan-out `budget` result auto-relaunch as a fresh top-level run (new fan-out budget, same mission and progress file) until the commentator reports clean or the `maxWorkflowAutoRelaunches` cap is reached (default 12; 0 = unlimited). See the [tool reference](tool-reference.md) for the full parameter list.
 
 The legacy `/chain`, `/parallel`, and `/run-chain` commands are not registered.
 

package/dist/extensions/pi-subagents/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-subagents",
-  "version": "0.47.1",
+  "version": "0.48.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-subagents",
-      "version": "0.47.1",
+      "version": "0.48.0",
       "license": "MIT",
       "dependencies": {
         "jiti": "2.7.0",

package/dist/extensions/pi-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.47.1",
+  "version": "0.48.0",
   "description": "Selesai extension for single-agent delegation, chains, parallel groups, and scripted multi-agent workflows",
   "author": "Nico Bailon",
   "license": "MIT",

package/dist/extensions/pi-subagents/skills/pi-subagents/references/execution-controls.md

@@ -55,7 +55,7 @@ its resolved launch context as `[fresh]` or `[fork]`. Aggregate headers show
 
 `workflowScript` is the scripted orchestration surface. Use `runs.run(key, { agent, task, ... })` for one child, `runs.all([...])` for parallel children, and ordinary JavaScript for sequence, branching, filtering, retries, and aggregation. Scripts are ordinary JavaScript statement bodies, so use an explicit return such as `workflowScript: "return runs.run('main', { agent: 'worker', task: '...' })"` for a useful one-child result. Prefer a single scripted workflow whenever the parent is starting a coordinated wave, such as multiple reviews, review plus gate monitor, worker then monitor setup, cross-repo prep lanes, or a fanout that the parent will consume together; use the declarative `chain` / `tasks` modes when the shape is known up front.
 
-**Workflow modes as `workflowScript` auto-loops.** The bundled `workflow` extension ships its four mode shapes (task, prototype, quicktype, loop) as `workflowScript` auto-loops launched via `/workflow-*`. Each mode runs its phases as `runs.run` steps and loops the build↔review round until the commentator reports clean. There are no checkpoints (one-shot-and-sleep); durable state is the auto-created mission per launch; recover via `mission.list`/`status`.
+**Workflow modes as `workflowScript` auto-loops.** The bundled `workflow` extension ships its four mode shapes (task, prototype, quicktype, loop) as `workflowScript` auto-loops launched via `/workflow-*`. Each mode runs its phases as `runs.run` steps and loops the build → review → fix round (a blocking review triggers a fix round that addresses only the findings) until the commentator reports clean. There are no checkpoints (one-shot-and-sleep); durable state is the auto-created mission per launch; recover via `mission.list`/`status`.
 
 ```js
 subagent({

package/dist/extensions/pi-subagents/src/agents/agents.ts

@@ -1024,7 +1024,10 @@ function applyBuiltinOverride(
 	};
 
 	if (override.description !== undefined) next.description = override.description;
-	if (override.model !== undefined) { if (override.model === false) delete next.model; else next.model = override.model; }
+	if (override.model !== undefined) {
+		if (override.model === false) delete next.model; else next.model = override.model;
+		delete next.modelSource;
+	}
 	if (override.fallbackModels !== undefined) { if (override.fallbackModels === false) delete next.fallbackModels; else next.fallbackModels = [...override.fallbackModels]; }
 	if (override.thinking !== undefined) { if (override.thinking === false) delete next.thinking; else next.thinking = override.thinking; }
 	if (override.systemPromptMode !== undefined) next.systemPromptMode = override.systemPromptMode;
@@ -1142,8 +1145,11 @@ function applyCustomAgentOverride(
 		mutable().description = override.description;
 		anyFilled = true;
 	}
-	if (override.model !== undefined) {
-		fill("model", ["model"], override.model === false ? undefined : override.model);
+	if (override.model !== undefined && !agentHasFrontmatterField(agent, "model")) {
+		const target = mutable();
+		if (override.model === false) delete target.model; else target.model = override.model;
+		delete target.modelSource;
+		anyFilled = true;
 	}
 	if (override.fallbackModels !== undefined) {
 		fill(

package/dist/extensions/pi-subagents/src/extension/config.ts

@@ -53,6 +53,18 @@ function validateConfig(config: Record<string, unknown>): void {
 	if (config.legacyChainControls !== undefined && typeof config.legacyChainControls !== "boolean") {
 		throw new Error("config.legacyChainControls must be a boolean");
 	}
+	if (config.maxActiveAsyncRunsPerSession !== undefined
+		&& (typeof config.maxActiveAsyncRunsPerSession !== "number"
+			|| !Number.isInteger(config.maxActiveAsyncRunsPerSession)
+			|| config.maxActiveAsyncRunsPerSession < 0)) {
+		throw new Error("config.maxActiveAsyncRunsPerSession must be a non-negative integer");
+	}
+	if (config.maxWorkflowAutoRelaunches !== undefined
+		&& (typeof config.maxWorkflowAutoRelaunches !== "number"
+			|| !Number.isInteger(config.maxWorkflowAutoRelaunches)
+			|| config.maxWorkflowAutoRelaunches < 0)) {
+		throw new Error("config.maxWorkflowAutoRelaunches must be a non-negative integer");
+	}
 	validateMissionStoreConfig(config.missions);
 	validateAuthorityPolicy(config.authorityPolicy);
 	validatePermissionConfig(config.permissions);

package/dist/extensions/pi-subagents/src/extension/doctor.ts

@@ -3,6 +3,8 @@ import * as path from "node:path";
 import { discoverAgentsAll, type AgentSource } from "../agents/agents.ts";
 import { isAsyncAvailable } from "../runs/background/async-execution.ts";
 import { formatSpawnBudgetSummary, getSpawnBudgetSnapshot } from "../runs/shared/spawn-budget.ts";
+import { getActiveAsyncCapacitySnapshot, resolveMaxActiveAsyncRunsPerSession } from "../runs/background/active-async-capacity.ts";
+import { decodeRunFanoutBudgetDescriptor, formatRunFanoutBudget, getRunFanoutBudgetSnapshot, RUN_FANOUT_BUDGET_ENV } from "../runs/shared/run-fanout-budget.ts";
 import { diagnoseIntercomBridge, type IntercomBridgeDiagnostic } from "../intercom/intercom-bridge.ts";
 import { discoverAvailableSkills, type SkillSource } from "../agents/skills.ts";
 import {
@@ -11,6 +13,8 @@ import {
 	TEMP_ROOT_DIR,
 	type ExtensionConfig,
 	type SubagentState,
+	normalizeMaxSubagentSpawnsPerRun,
+	resolveMaxSubagentSpawnsPerRun,
 } from "../shared/types.ts";
 
 interface DoctorPaths {
@@ -175,6 +179,36 @@ function formatSpawnBudgetSection(input: DoctorReportInput): string[] {
 	];
 }
 
+function formatRunFanoutSection(input: DoctorReportInput): string[] {
+	try {
+		const inherited = decodeRunFanoutBudgetDescriptor(process.env[RUN_FANOUT_BUDGET_ENV]);
+		if (inherited) {
+			return [`- usage: ${formatRunFanoutBudget(getRunFanoutBudgetSnapshot(inherited)).replace(/^Run fan-out: /, "")}`, `- root run: ${inherited.rootRunId}`, "- reset boundary: cumulative claims are never released; a new top-level run creates a new budget"];
+		}
+	} catch (error) {
+		return [`- inherited budget: invalid — ${errorText(error)}`];
+	}
+	const configured = resolveMaxSubagentSpawnsPerRun(input.config.maxSubagentSpawnsPerRun);
+	const source = normalizeMaxSubagentSpawnsPerRun(process.env.SELESAI_SUBAGENT_MAX_SPAWNS_PER_RUN) !== undefined
+		? "environment"
+		: normalizeMaxSubagentSpawnsPerRun(input.config.maxSubagentSpawnsPerRun) !== undefined ? "config" : "default";
+	return [`- configured limit: ${configured} (${source})`, "- usage: available after a run starts", "- reset boundary: cumulative claims are never released; a new top-level run creates a new budget"];
+}
+
+function formatActiveAsyncCapacitySection(input: DoctorReportInput): string[] {
+	const limit = resolveMaxActiveAsyncRunsPerSession(input.config.maxActiveAsyncRunsPerSession);
+	const sessionId = input.currentSessionId ?? input.state.currentSessionId;
+	const snapshot = sessionId
+		? getActiveAsyncCapacitySnapshot(sessionId, limit, { liveWorkflowRunIds: new Set(input.state.workflowControllers?.keys() ?? []) })
+		: { used: 0, limit: limit ?? 0 };
+	input.state.activeAsyncCapacity = snapshot;
+	return [
+		`- usage: ${snapshot.used}/${snapshot.limit || "unlimited"} used`,
+		"- scope: top-level async runs in the current parent session; foreground and nested workflow children are not charged again",
+		"- release: terminal logical state plus verified process exit; missing or unknown cleanup proof retains capacity",
+	];
+}
+
 function formatPermissionSystemSection(): string[] {
 	const lines: string[] = [];
 	const parentSession = process.env["SELESAI_SUBAGENT_PARENT_SESSION"] ?? "";
@@ -215,6 +249,12 @@ export function buildDoctorReport(input: DoctorReportInput): string {
 		"Spawn budget",
 		...formatSpawnBudgetSection(input),
 		"",
+		"Run fan-out budget",
+		...formatRunFanoutSection(input),
+		"",
+		"Active async capacity",
+		...formatActiveAsyncCapacitySection(input),
+		"",
 		"Permission system",
 		...formatPermissionSystemSection(),
 		"",

package/dist/extensions/pi-subagents/src/extension/index.ts

@@ -16,6 +16,7 @@ import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { keyText, type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@selesai/code";
 import { Box, Container, Spacer, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component } from "@earendil-works/pi-tui";
@@ -23,6 +24,7 @@ import { discoverAgents } from "../agents/agents.ts";
 import { ensureAccessibleDir } from "../shared/accessible-dir.ts";
 import { cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir } from "../shared/artifacts.ts";
 import { resolveCurrentSessionId } from "../shared/session-identity.ts";
+import { resolveSessionLineage } from "../shared/session-lineage.ts";
 import { cleanupOldChainDirs } from "../shared/settings.ts";
 import { clearLegacyResultAnimationTimer, renderSubagentResult, renderSubagentSummary } from "../tui/render.ts";
 import { openSubagentFleet } from "../tui/fleet.ts";
@@ -31,6 +33,7 @@ import { createSubagentParamsSchema } from "./schemas.ts";
 import { validateChainInput } from "./chain-validation.ts";
 import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
 import { createAsyncJobTracker } from "../runs/background/async-job-tracker.ts";
+import { getActiveAsyncCapacitySnapshot, resolveMaxActiveAsyncRunsPerSession } from "../runs/background/active-async-capacity.ts";
 import { createResultWatcher } from "../runs/background/result-watcher.ts";
 import { createScheduledRunManager } from "../runs/background/scheduled-runs.ts";
 import { registerSlashCommands } from "../slash/slash-commands.ts";
@@ -66,6 +69,7 @@ import {
 	SLASH_TEXT_RESULT_TYPE,
 	SUBAGENT_ASYNC_COMPLETE_EVENT,
 	SUBAGENT_ASYNC_STARTED_EVENT,
+	SUBAGENT_PROCESS_TERMINAL_EVENT,
 	SUBAGENT_CONTROL_EVENT,
 	SUBAGENT_STEERING_NOTICE_EVENT,
 	WIDGET_KEY,
@@ -374,6 +378,12 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const artifactCleanupDays = config.artifactConfig?.cleanupDays ?? DEFAULT_ARTIFACT_CONFIG.cleanupDays;
 	cleanupAllArtifactDirs(artifactCleanupDays);
 
+	// Replay guard for lineage result adoption: accept result files written at
+	// most this long before the adoption window opened (covers completions that
+	// raced the session switch). Older files were left behind by a dead watcher
+	// and are ignored until their owning session is resumed.
+	const ADOPTED_RESULT_SLACK_MS = 60_000;
+
 	const state: SubagentState = {
 		baseCwd: "",
 		currentSessionId: null,
@@ -389,6 +399,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			granted: 0,
 			grantHistory: [],
 		},
+		activeAsyncCapacity: { used: 0, limit: resolveMaxActiveAsyncRunsPerSession(config.maxActiveAsyncRunsPerSession) ?? 0 },
 		asyncJobs: new Map(),
 		fleetJobs: new Map(),
 		foregroundRuns: new Map(),
@@ -627,19 +638,26 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 
 	pi.on("agent_end", async (_event, ctx) => {
 		if (!ctx.hasUI) await drainOutstandingWork({ state, events: pi.events });
-		const ownerSessionId = state.currentSessionId;
-		if (!ownerSessionId) return;
+		const ownerSessionIds = state.sessionLineage?.length
+			? state.sessionLineage
+			: state.currentSessionId ? [state.currentSessionId] : [];
+		if (ownerSessionIds.length === 0) return;
 		goalTurnId += 1;
 		try {
 			const location = resolveMissionStoreLocation({ projectRoot: state.baseCwd, ...(config.missions ? { config: config.missions } : {}) });
-			const retainedChildren = listRetainedChildren(DIRS.async, ownerSessionId);
-			for (const notice of collectGoalContinuationNotices({ location, ownerSessionId, retainedChildren, turnId: goalTurnId })) {
-				handleSubagentControlNotice({
-					pi,
-					state,
-					visibleControlNotices: new Set(),
-					details: { source: "goal", event: notice.event, noticeText: notice.message },
-				});
+			const retainedChildren = listRetainedChildren(DIRS.async, ownerSessionIds);
+			const emittedMissions = new Set<string>();
+			for (const ownerSessionId of ownerSessionIds) {
+				for (const notice of collectGoalContinuationNotices({ location, ownerSessionId, retainedChildren, turnId: goalTurnId })) {
+					if (emittedMissions.has(notice.missionId)) continue;
+					emittedMissions.add(notice.missionId);
+					handleSubagentControlNotice({
+						pi,
+						state,
+						visibleControlNotices: new Set(),
+						details: { source: "goal", event: notice.event, noticeText: notice.message },
+					});
+				}
 			}
 		} catch (error) {
 			console.error("Failed to evaluate goal missions:", error);
@@ -647,6 +665,11 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	});
 
 	registerSlashCommands(pi, state, { fleetKeybindings: config.fleetKeybindings });
+	pi.on("resources_discover", () => {
+		return {
+			promptPaths: [fileURLToPath(new URL("../../prompts", import.meta.url))],
+		};
+	});
 
 	const eventUnsubscribeStoreKey = "__piSubagentEventUnsubscribes";
 	const controlNoticeSeenStoreKey = "__piSubagentVisibleControlNotices";
@@ -689,12 +712,17 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	};
 	const asyncCompleteHandler = (payload: unknown) => {
 		handleComplete(payload);
+		refreshActiveAsyncCapacity();
 		scheduledRunManager.handleAsyncCompletion(payload);
 		fleetStatus?.refresh();
 	};
 	const eventUnsubscribes = [
 		pi.events.on(SUBAGENT_ASYNC_STARTED_EVENT, asyncStartedHandler),
 		pi.events.on(SUBAGENT_ASYNC_COMPLETE_EVENT, asyncCompleteHandler),
+		pi.events.on(SUBAGENT_PROCESS_TERMINAL_EVENT, () => {
+			refreshActiveAsyncCapacity();
+			fleetStatus?.refresh();
+		}),
 		pi.events.on(SUBAGENT_CONTROL_EVENT, controlEventHandler),
 		pi.events.on(SUBAGENT_STEERING_NOTICE_EVENT, steeringNoticeHandler),
 		herdrStatusBridge.dispose,
@@ -740,12 +768,57 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		fleetStatus?.refresh();
 	};
 
-	const resetSessionState = (ctx: ExtensionContext, recovering: boolean) => {
+	const refreshActiveAsyncCapacity = () => {
+		if (!state.currentSessionId) {
+			state.activeAsyncCapacity = { used: 0, limit: resolveMaxActiveAsyncRunsPerSession(config.maxActiveAsyncRunsPerSession) ?? 0 };
+			return;
+		}
+		state.activeAsyncCapacity = getActiveAsyncCapacitySnapshot(
+			state.currentSessionId,
+			resolveMaxActiveAsyncRunsPerSession(config.maxActiveAsyncRunsPerSession),
+			{ liveWorkflowRunIds: new Set(state.workflowControllers?.keys() ?? []) },
+		);
+		const adoptedActive = [...state.asyncJobs.values()].filter((job) => job.adopted && (job.status === "queued" || job.status === "running")).length;
+		if (adoptedActive > 0) {
+			state.activeAsyncCapacity = {
+				...state.activeAsyncCapacity,
+				used: state.activeAsyncCapacity.used + adoptedActive,
+			};
+		}
+	};
+
+	const formatActiveWorkflowSummary = (target: SubagentState, intro: string): string => {
+		const active = [...target.asyncJobs.values()]
+			.filter((job) => job.status === "queued" || job.status === "running")
+			.sort((left, right) => (left.startedAt ?? 0) - (right.startedAt ?? 0));
+		const lines = active.map((job) => {
+			const label = job.mode === "workflow"
+				? `workflow[${job.workflowKey ?? "script"}]`
+				: `${job.mode ?? "run"}${job.agents?.length ? ` ${job.agents.join(", ")}` : ""}`;
+			const step = job.currentStep !== undefined
+				? ` · step ${job.currentStep + 1}/${job.chainStepCount ?? job.stepsTotal ?? "?"}`
+				: "";
+			const activity = job.currentTool ? ` · last: ${job.currentTool}` : "";
+			const adopted = job.adopted ? " (carried over from a previous session)" : "";
+			return `- ${job.asyncId} ${label}${step}${activity}${adopted}`;
+		});
+		return [
+			intro,
+			...lines,
+			"Monitor with subagent status <id>; interrupt/resume/steer by run id; children.list lists completed steps. Results arrive automatically.",
+		].join("\n");
+	};
+
+	const resetSessionState = (ctx: ExtensionContext, recovering: boolean, previousSessionFile?: string | null) => {
 		state.widgetsSuspended = false;
 		state.baseCwd = ctx.cwd;
 		goalTurnId = 0;
 		state.currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
 		state.parentSessionFile = ctx.sessionManager.getSessionFile();
+		state.sessionLineage = resolveSessionLineage({ sessionManager: ctx.sessionManager }, { parentHint: previousSessionFile ?? null });
+		state.handoffResumePending = false;
+		if (state.sessionLineage.length > 1) state.adoptedResultWindowStart = Date.now() - ADOPTED_RESULT_SLACK_MS;
+		else state.adoptedResultWindowStart = undefined;
 		state.subagentSpawns = {
 			sessionId: state.currentSessionId,
 			count: 0,
@@ -765,12 +838,14 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			}
 		}
 		state.lastUiContext = ctx;
+		refreshActiveAsyncCapacity();
 		cleanupSessionArtifacts(ctx);
 		state.foregroundControls.clear();
 		state.lastForegroundControlId = null;
 		resetJobs(ctx);
 		restoreForegroundRunHistory(state, { resultsDir: DIRS.results });
-		restoreActiveJobs(ctx);
+		const adoptedJobs = restoreActiveJobs(ctx);
+		state.handoffResumePending = adoptedJobs > 0 && state.lastUiContext?.hasUI === true;
 		scheduledRunManager.bindSession(ctx);
 		restoreSlashFinalSnapshots(ctx.sessionManager.getEntries());
 		waitSubscriptionManager.restore();
@@ -786,6 +861,17 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 
 	pi.on("agent_settled", () => {
 		resumeWidgetsAfterCompaction();
+		if (state.handoffResumePending && state.lastUiContext?.hasUI === true) {
+			state.handoffResumePending = false;
+			pi.sendMessage(
+				{
+					customType: "subagent-handoff-resume",
+					content: formatActiveWorkflowSummary(state, "Session handoff detected. The previous session's background workflows were carried over:"),
+					display: false,
+				},
+				{ triggerTurn: true },
+			);
+		}
 	});
 
 	pi.on("session_before_compact", (event) => {
@@ -798,7 +884,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		pi.sendMessage(
 			{
 				customType: "subagent-compaction-resume",
-				content: "Compaction is complete. Resume the parent task now; background subagent results will arrive separately when ready.",
+				content: formatActiveWorkflowSummary(state, "Compaction is complete. Resume the parent task now; results for the runs below arrive separately when ready:"),
 				display: false,
 			},
 			{ triggerTurn: true },
@@ -807,7 +893,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 
 	pi.on("session_start", (event, ctx) => {
 		const recovering = event.reason === "startup" || event.reason === "reload" || event.reason === "resume";
-		resetSessionState(ctx, recovering);
+		const previousSessionFile = event.reason === "new" || event.reason === "fork" ? event.previousSessionFile : null;
+		resetSessionState(ctx, recovering, previousSessionFile);
 		herdrStatusBridge.sessionStarted({
 			hasUI: ctx.hasUI === true,
 			runs: activeHerdrRuns(),
@@ -821,6 +908,9 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		stopResultWatcher();
 		state.currentSessionId = null;
 		state.parentSessionFile = null;
+		state.sessionLineage = undefined;
+		state.adoptedResultWindowStart = undefined;
+		state.handoffResumePending = false;
 		completionNotifier.dispose();
 		delete process.env[SUBAGENT_PARENT_SESSION_ENV];
 		for (const unsubscribe of eventUnsubscribes) {

package/dist/extensions/pi-subagents/src/extension/public-execution.ts

@@ -11,6 +11,8 @@ export interface PublicSubagentExecutionParams {
 	workflowScript?: unknown;
 	resume?: unknown;
 	clarify?: unknown;
+	runFanoutBudget?: unknown;
+	runFanoutAdmitted?: unknown;
 }
 
 export type PublicSubagentExecutionMode = "workflow" | "management";
@@ -26,6 +28,9 @@ export type PublicSubagentExecutionNormalization<T> =
  * children and structured owned delegation bypass this boundary.
  */
 export function normalizePublicSubagentExecution<T extends PublicSubagentExecutionParams>(params: T): PublicSubagentExecutionNormalization<T> {
+	if (params.runFanoutBudget !== undefined || params.runFanoutAdmitted !== undefined) {
+		return { ok: false, error: "Public execution does not accept internal run fan-out fields.", mode: params.workflowScript !== undefined ? "workflow" : "management" };
+	}
 	const action = params.action;
 	if (action !== undefined && (typeof action !== "string" || !action.trim())) {
 		return { ok: false, error: "action must be a non-empty management/control action, or omit action and execute directly.", mode: "management" };