pi-ptc-subagents 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.2] - 2026-09-23
+
+### Fixed
+
+- **`pi.dispatch` is registered in production again.** The injection check compared the
+  binding-name array by reference against `DEFAULT_BINDING_NAMES`; production resolves
+  names through a `.filter()` that always returns a fresh array, so the comparison never
+  held and shipped sessions had no `pi.dispatch` at all. Injection now keys off a new
+  `includeDispatch` option (defaulting to "the caller passed no explicit `names`"), and
+  both shipped tools pass it explicitly. ADR-0016.
+- **The dispatch concurrency cap honours `dispatchConcurrency` (default 8) and rejects
+  immediately instead of queueing.** The dispatcher used to read `maxParallelSubCalls`
+  (default 10) and FIFO-queue the overflow; per ADR-0016 §2 the N+1th concurrent
+  `pi.dispatch` now resolves at once with `{ status: "rejected", errorMessage:
+"dispatch concurrency limit reached" }`. The cap applies to `pi.dispatch` only and
+  has its own counter; builtin binding fan-out keeps DSH's `maxParallelSubCalls` (10)
+  FIFO-queueing semantics (ADR-0004), so in-flight builtin calls never consume
+  dispatch slots.
+- **The depth-limit rejection message is verbatim again.** The program receives
+  exactly `dispatch depth limit reached`, matching what the child's
+  `<pi-ptc-context>` hint promises — the diagnostic suffix is gone.
+- **`maxDispatchDepth` bounds recursion again.** Every run reported depth 0 and
+  children never inherited it, so the depth check could never fire. `dispatch()` now
+  stamps `PI_PTC_DEPTH` on the child subprocess's environment, the extension
+  entrypoint reads it back, and `runPtcProgram()` accepts a `depth` baseline that
+  reaches the binding context. ADR-0016 Recursive section.
+
 ## [0.1.1] - 2026-09-23
 
 PTC runs inside one agent turn no longer pay a cold start each. Nothing changes in

package/dist/index.d.ts

@@ -201,16 +201,24 @@ interface PtcConfig {
   maxMessageBytes: number;
   /** Admission control for simultaneously in-flight worker→host binding calls (ADR-0004). */
   maxPendingCalls: number;
-  /** Concurrent binding dispatches; DSH's `maxParallelSubCalls` (ADR-0004 consequence).
-   *  Renamed in spirit by ADR-0016 section 2: the cap that really matters for
-   *  resource safety is the per-run `dispatchConcurrency` below. This field
-   *  is kept for backward compatibility (and for the in-process builtin
-   *  binding fan-out) but is no longer the authoritative limit on the
-   *  parallel binding `pi.dispatch`. */
+  /**
+   * Concurrent builtin binding dispatches; DSH's `maxParallelSubCalls`
+   * (ADR-0004 consequence), mirrored verbatim (10). The overflow
+   * FIFO-queues for a slot instead of failing. This is the authoritative
+   * cap for the builtin fan-out path — independent of
+   * `dispatchConcurrency`, with its own counter: neither cap throttles
+   * the other.
+   */
   maxParallelSubCalls: number;
-  /** Per-run hard cap on concurrently in-flight `pi.dispatch(...)` calls.
-   *  Default 8, matches pi's `subagent` extension `MAX_PARALLEL_TASKS`.
-   *  ADR-0016 section 2. */
+  /**
+   * Per-run hard cap on concurrently in-flight `pi.dispatch(...)` calls,
+   * enforced by the dispatcher: the next concurrent call resolves
+   * immediately with `{ status: "rejected", errorMessage: "dispatch
+   * concurrency limit reached" }` — never queued, never spawned.
+   * Default 8, matches pi's `subagent` extension `MAX_PARALLEL_TASKS`.
+   * ADR-0016 section 2. Independent of `maxParallelSubCalls`: builtin
+   * calls never consume a dispatch slot and vice versa.
+   */
   dispatchConcurrency: number;
   /** Maximum recursion depth for `pi.dispatch`. The child PTC run spawned by
    *  the (depth+1)-th dispatch is allowed only when childDepth <= maxDispatchDepth.
@@ -227,9 +235,10 @@ interface PtcConfig {
   /** V8 young-generation cap handed to `new Worker({ resourceLimits })` (F2). */
   maxYoungGenerationSizeMb: number;
   /**
-   * Per-turn worker pool capacity (ADR-0017 §3). Decoupled from `maxParallelSubCalls`
-   * because pool capacity is "resident workers" while `maxParallelSubCalls` is
-   * "in-flight calls" — two different ceilings. Default 4.
+   * Per-turn worker pool capacity (ADR-0017 §3). Decoupled from
+   * `dispatchConcurrency` because pool capacity is "resident workers" while
+   * `dispatchConcurrency` is "in-flight calls" — two different ceilings.
+   * Default 4.
    */
   poolSize: number;
   /**
@@ -361,6 +370,15 @@ export declare function renderModelValue(value: PtcJsonValue): string;
 /** pi's built-in tools that can be exposed as bindings, in native order. */
 export declare const BUILTIN_BINDING_NAMES: readonly ["read", "bash", "edit", "write", "grep", "find", "ls"];
 type BuiltinBindingName = (typeof BUILTIN_BINDING_NAMES)[number];
+/**
+ * Bindings exposed when the caller does not pass an explicit name list.
+ *
+ * `bash` is included on purpose: DSH's PTC preset still mounts `tool-bash`/`tool-pwsh`
+ * (R1 §2 — PTC mode hides the tools from the wire list and re-exposes the same registry
+ * as bindings), so a PTC program written against DSH may run shell commands. Leaving it
+ * out would silently shrink the surface relative to DSH. Callers that want a read-only
+ * PTC surface pass an explicit subset.
+ */
 export declare const DEFAULT_BINDING_NAMES: readonly BuiltinBindingName[];
 interface BindingContext {
   /** Aborted when the run is cancelled, times out, or settles. */
@@ -382,6 +400,16 @@ interface CreateBuiltinBindingsOptions {
   cwd: string;
   /** Subset of {@link BUILTIN_BINDING_NAMES}; defaults to all of them (bash included). */
   names?: readonly string[];
+  /**
+   * Whether the parallel binding `pi.dispatch` (ADR-0016) joins the table. Defaults to
+   * "did the caller curate the surface": `true` when `names` is omitted, `false` when an
+   * explicit list is passed (R3's read-only PTC surface pattern). Deciding on whether
+   * `names` was provided — not on array identity with {@link DEFAULT_BINDING_NAMES} —
+   * matters because production callers resolve names through a `.filter()` that always
+   * returns a fresh array. The two shipped tools pass `true` explicitly: the dispatch
+   * binding is part of every production surface.
+   */
+  includeDispatch?: boolean;
 }
 /**
  * Build the binding table for one run.
@@ -483,6 +511,14 @@ interface RunPtcProgramOptions {
   config?: Partial<PtcConfig>;
   /** Cancels the run; the worker gets a cooperative cancel window before termination. */
   signal?: AbortSignal;
+  /**
+   * Depth of this run in the `pi.dispatch` recursion chain (ADR-0016 Recursive section):
+   * 0 for the parent turn's run, 1+ for a run inside a child spawned by `pi.dispatch`.
+   * Handed to the binding context so the dispatch binding can bound recursion. The
+   * extension entrypoint derives it from `PI_PTC_DEPTH`; direct library use defaults
+   * to 0.
+   */
+  depth?: number;
   /** Identifier carried to the worker; generated when omitted. */
   runId?: string;
   /**

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/mode/ptc-mode.ts","../src/mode/skills-section.ts","../src/runtime/limits.ts","../src/runtime/protocol.ts","../src/tools/text.ts","../src/runtime/bindings.ts","../src/runtime/worker-pool.ts","../src/runtime/dispatcher.ts","../src/runtime/turn-pools.ts","../src/index.ts"],"mappings":";;;;qBA2Ca;;;;;;;;;;qBAWA;;qBAGA;;qBAGA;;qBAGA;;KAGD;;;;;;;;;;;;;qBAcC,uBAAuB;;UAGnB;EACf;;EAEA;;EAEA;;;wBAIc,oBAAoB;;;;;UAQnB;EACf;EACA;;;UAQe;EACf;EACA;EACA;;;;;;;;;wBAUc,sBAAsB,mBAAmB;;KAwC7C;;KAGA;EACN;EAAa;EAAyB;;EACtC;EAAc,QAAQ;;;UAGX;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA,OAAO;;;wBASO,YAAY,sBAAsB;;;;;;;;wBAclC,YAAY,2BAA2B,MAAM;;;;;;;;;;;;;;;wBAqB7C,gBAAgB,OAAO,iBAAiB;;;;;;;wBA4BxC,cAAc,OAAO,cAAc;;;;;wBAQnC,4BACd,OAAO,cACP;;;;;;;;;;;wBAgBc,mBACd,WAAW,gCACX;EACG;EAAyB;;;;;;;;;wBAoBd,qBAAqB,6BAA6B,MAAM;;;;qBCvR3D;;qBAOA;;;;;;;wBASG,qBAAqB;;;;;;;;;;wBAarB,sBACd,iBAAiB,SACjB,UAAS,QAAQ,SAAS;;;;;;;;;;;;;;;;;;KCtChB;UAEK;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;EAOA;;;;EAIA;;;;;EAKA;;;EAGA;;EAEA;;EAEA;;EAEA;;;;;;EAMA;;;;;;;EAOA;;;;;;;;;EASA;;qBAGW,gBAAgB,SAAS;;;;;;;qBAwBzB;;;;;;;wBAeG,gBAAgB,SAAQ,OAAO,aAA2B;;;;;;;wBAe1D,cAAc,YAAW,QAAQ,aAAkB;;;;;;;wBAmBnD,mBACd,+BACA,SAAQ;;;;cCvIJ;WACJ;WACA;WACA;WACA;;qBAEW,wBAAwB;;cAG/B;WACJ;WACA;WACA;WACA;WACA;WACA;WACA;;qBAEW,0BAA0B;cAGjC;WACJ;WACA;WACA;WACA;WACA;;qBAEW,sBAAsB;cAG7B;;WAEJ;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;qBAEW,uBAAuB;KACxB,uBAAuB,6BAA6B;;UAK/C;GACA,cAAA;;KAEL,kDAAkD,iBAAiB;UAE9D;EACf,MAAM;EACN;EACA;;;;;qBCvDW;;wBAwBG,UAAU;;;;;;;;;wBAgBV,aAAa;;;;;;wBA6Ib,iBAAiB,OAAO;;;;qBC7K3B;KASD,6BAA6B;qBAiB5B,gCAAgC;UAE5B;;EAEf,SAAS;;EAET;;EAEA;;EAEA;;UAGe;WACN;EACT,QAAQ,eAAe,SAAS,iBAAiB;;KAGvC,eAAe,oBAAoB;UAkC9B;;EAEf;;EAEA;;;;;;;;;wBAUc,sBAAsB,SAAS,+BAA+B;;;;KCjFlE,0BAA0B,6BAA6B;UAiClD;;;;;;EAMf,sBAAsB;;EAEtB;;EAEA;;;;;;EAMA;;EAEA,eAAe;;UAqCA;EACf;EACA;EACA;EACA;EACA;;;;;;;;qBASW;;EAyBX,YAAY,SAAS;;;;;;EA4CrB,WAAiB,QAAQ;;;;;;EA4DzB,QAAQ,QAAQ;;;;;;;EAuChB,cAAc,QAAQ;;;;;;;;;;;;EAetB,SAAe;;EA4Bf,SAAS;;;;UC7SM;;EAEf;EACA,SAAS;;EAET;;EAEA,UAAU;;EAEV;;EAEA;;EAEA,SAAS,QAAQ;;EAEjB,SAAS;;EAET;;;;;;;;EAQA,OAAO;;;;;;;;;;;;;;UAeQ;EACf;EACA;;UAGe;;EAEf;;EAEA;;EAEA;;EAEA,QAAQ;;;;;;;;;;;EAWR,SAAS;;EAET,QAAQ;;;;;;;;;wBAgGY,cAAc,SAAS,uBAAuB,QAAQ;;;UCtM3D;;EAEf,SAAS,QAAQ;;qBAGN;;EAIX,YAAY,UAAS;;;;;;EASrB,IAAI,SAAS,aAAa;;;;;EAuC1B,SAAe;;;;wBCyDO,aAAa,IAAI"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/mode/ptc-mode.ts","../src/mode/skills-section.ts","../src/runtime/limits.ts","../src/runtime/protocol.ts","../src/tools/text.ts","../src/runtime/bindings.ts","../src/runtime/worker-pool.ts","../src/runtime/dispatcher.ts","../src/runtime/turn-pools.ts","../src/index.ts"],"mappings":"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"}

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as isPtcHostFrame, i as WORKER_FRAME_KIND, n as PTC_ERROR_KIND, o as isPtcWorkerFrame, r as PTC_LOG_LEVEL, t as HOST_FRAME_KIND } from "./protocol-DLR50XxW.js";
+import { a as describeValue, i as WORKER_FRAME_KIND, n as PTC_ERROR_KIND, o as isPtcHostFrame, r as PTC_LOG_LEVEL, s as isPtcWorkerFrame, t as HOST_FRAME_KIND } from "./protocol-DUnAP1Ro.js";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, createBashTool, createEditTool, createFindTool, createGrepTool, createLsTool, createReadTool, createWriteTool, defineTool, formatSize, formatSkillsForPrompt, getAgentDir, truncateTail } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { validateToolArguments } from "@earendil-works/pi-ai";
@@ -16,14 +16,15 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 //#region src/runtime/dispatch.ts
 /**
-* pi.dispatch: a parallel binding that spawns a fresh pi subprocess per call.
+* pi.dispatch: the parallel binding that spawns a fresh pi subprocess per call.
 *
-* ADR-0016 (2026-09-23) is the contract. This file is the type surface and the spawn
-* skeleton; the actual subprocess plumbing (agent-md resolution, JSON-line parser,
-* usage accumulator, signal propagation across worker_threads / child_process) is a
-* follow-up. The stubs here are typed against the contract so call sites can land
-* before the spawn path is finalised, and so a wrong shape is a compile error rather
-* than a runtime one.
+* ADR-0016 (2026-09-23) is the contract, and this file is the whole implementation:
+* agent-markdown discovery (`discoverAgent`, with the agentScope user/project split),
+* the recursion-depth hint appended to the child's system prompt (`appendDepthHint`),
+* the argv the child pi is launched with (`buildArgv`), and `dispatch()` itself —
+* spawn, JSON-line event parsing, usage accumulation, the close-outcome decision
+* (`decideCloseOutcome`), and SIGTERM → SIGKILL signal propagation when the run that
+* issued the dispatch is cancelled.
 *
 * Behaviourally compatible with pi's examples/extensions/subagent/index.ts reference
 * (--mode json, -p, --no-session, --append-system-prompt <tmpfile>), but not cooperative:
@@ -63,15 +64,32 @@ function appendDepthHint(systemPrompt, depth, maxDepth) {
 	].join("\n");
 	return systemPrompt.length === 0 ? hint : systemPrompt + "\n\n" + hint;
 }
-/** Default error returned when the depth limit is exceeded. */
-function dispatchDepthLimitReached(currentDepth) {
+/** Result returned when the depth limit is exceeded. */
+function dispatchDepthLimitReached() {
 	return {
 		text: "",
 		status: "rejected",
 		agentName: "unknown",
 		durationMs: 0,
 		exitCode: -1,
-		errorMessage: "dispatch depth limit reached (current depth " + currentDepth + ", max-depth exceeded)"
+		errorMessage: "dispatch depth limit reached"
+	};
+}
+/**
+* Verbatim ADR-0016 §2 message for the per-run dispatch concurrency cap. Exported as a
+* named constant so the contract string has one definition and cannot drift (tests pin
+* it character for character).
+*/
+const DISPATCH_CONCURRENCY_LIMIT_MESSAGE = "dispatch concurrency limit reached";
+/** Result returned when the per-run dispatch concurrency cap is exceeded (ADR-0016 §2). */
+function dispatchConcurrencyLimitReached() {
+	return {
+		text: "",
+		status: "rejected",
+		agentName: "unknown",
+		durationMs: 0,
+		exitCode: -1,
+		errorMessage: DISPATCH_CONCURRENCY_LIMIT_MESSAGE
 	};
 }
 /**
@@ -281,7 +299,7 @@ function cleanupTmp(tmp) {
 */
 async function dispatch(input, ctx) {
 	const childDepth = ctx.depth + 1;
-	if (childDepth > ctx.maxDepth) return dispatchDepthLimitReached(ctx.depth);
+	if (childDepth > ctx.maxDispatchDepth) return dispatchDepthLimitReached();
 	const cwd = input.cwd ?? ctx.cwd;
 	const agentScope = input.agentScope ?? "user";
 	const start = Date.now();
@@ -294,7 +312,7 @@ async function dispatch(input, ctx) {
 		exitCode: 1,
 		errorMessage: "unknown agent: " + input.agent + " (agentScope=" + agentScope + ", cwd=" + cwd + ")"
 	};
-	const fullPrompt = appendDepthHint(agent.systemPrompt, childDepth, ctx.maxDepth);
+	const fullPrompt = appendDepthHint(agent.systemPrompt, childDepth, ctx.maxDispatchDepth);
 	const tmp = await writePromptToTempFile(agent.name, fullPrompt);
 	const argv = buildArgv(input, agent, tmp.filePath);
 	return await new Promise((resolve) => {
@@ -341,7 +359,11 @@ async function dispatch(input, ctx) {
 					"ignore",
 					"pipe",
 					"pipe"
-				]
+				],
+				env: {
+					...process.env,
+					PI_PTC_DEPTH: String(childDepth)
+				}
 			});
 		} catch (err) {
 			finalize("rejected", "failed to spawn pi: " + (err instanceof Error ? err.message : String(err)));
@@ -439,6 +461,8 @@ const BUILTIN_BINDING_NAMES = [
 	"find",
 	"ls"
 ];
+/** Parallel binding name (ADR-0016). */
+const DISPATCH_BINDING_NAME = "pi.dispatch";
 /**
 * Bindings exposed when the caller does not pass an explicit name list.
 *
@@ -448,11 +472,6 @@ const BUILTIN_BINDING_NAMES = [
 * out would silently shrink the surface relative to DSH. Callers that want a read-only
 * PTC surface pass an explicit subset.
 */
-/** Parallel binding name (ADR-0016). Always bound alongside the builtin set;
-* opt-out is the callers responsibility via an explicit subset to
-* createBuiltinBindings (today the subset is restricted to builtin names,
-* so opt-out is effectively use a future flag). */
-const DISPATCH_BINDING_NAME = "pi.dispatch";
 const DEFAULT_BINDING_NAMES = BUILTIN_BINDING_NAMES;
 const BUILTIN_TOOL_FACTORIES = {
 	read: createReadTool,
@@ -472,6 +491,7 @@ const BUILTIN_TOOL_FACTORIES = {
 */
 function createBuiltinBindings(options) {
 	const names = options.names ?? DEFAULT_BINDING_NAMES;
+	const includeDispatch = options.includeDispatch ?? options.names === void 0;
 	const table = /* @__PURE__ */ new Map();
 	for (const name of names) {
 		const factory = BUILTIN_TOOL_FACTORIES[name];
@@ -496,7 +516,7 @@ function createBuiltinBindings(options) {
 			}
 		});
 	}
-	if (names === DEFAULT_BINDING_NAMES) table.set(DISPATCH_BINDING_NAME, {
+	if (includeDispatch) table.set(DISPATCH_BINDING_NAME, {
 		name: DISPATCH_BINDING_NAME,
 		execute: async (args, context) => {
 			return dispatch(args, {
@@ -504,7 +524,7 @@ function createBuiltinBindings(options) {
 				callId: context.callId,
 				cwd: options.cwd,
 				depth: context.depth,
-				maxDepth: context.maxDispatchDepth
+				maxDispatchDepth: context.maxDispatchDepth
 			});
 		}
 	});
@@ -912,7 +932,12 @@ function buildWorkerUrl() {
 *   hardening itself is defined once, in `workerSpawnOptions` (`worker-pool.ts`),
 * - complete the `MessageChannel` handshake and send the `init` frame,
 * - route `tools.*` calls to the binding table — concurrently, with DSH's
-*   `maxParallelSubCalls` forwarding cap and `maxPendingCalls` admission control,
+*   `maxPendingCalls` admission control, the `maxParallelSubCalls` builtin
+*   forwarding cap (ADR-0004 consequence: the overflow FIFO-queues for a
+*   slot), and the per-run `dispatchConcurrency` hard cap on in-flight
+*   `pi.dispatch` calls (ADR-0016 §2: the overflow resolves immediately as
+*   rejected, it is never queued). The two caps have independent counters:
+*   neither throttles the other.
 * - collect logs / narration / phases and enforce the joint output budget,
 * - enforce the deadline, honour caller cancellation, and settle the run: hand the worker
 *   back (pooled) or tear it down (cold).
@@ -1054,9 +1079,22 @@ async function runPtcProgram(options) {
 		let workerReady = false;
 		let pendingCalls = 0;
 		let outputBytes = 0;
+		/**
+		* Concurrently in-flight `pi.dispatch` calls, counted so the per-run hard cap
+		* (ADR-0016 §2) can reject the overflow immediately. There is deliberately no
+		* waiter queue behind this counter: the N+1th concurrent call resolves as
+		* rejected instead of waiting for a slot. Independent of `activeBuiltinCalls`.
+		*/
 		let activeDispatches = 0;
-		const dispatchWaiters = [];
-		const runDepth = 0;
+		/**
+		* Concurrently in-flight builtin binding calls, counted against
+		* `maxParallelSubCalls` (ADR-0004 consequence). Unlike the dispatch cap,
+		* the overflow FIFO-queues for a slot — DSH's semantics for builtin fan-out.
+		* Independent of `activeDispatches`.
+		*/
+		let activeBuiltinCalls = 0;
+		const builtinWaiters = [];
+		const runDepth = options.depth ?? 0;
 		/** Deadline timer: fires `timeoutMs` after the run started. A cancel does not disarm it. */
 		let runTimer;
 		/** The cancel's cooperative window: armed and re-armed by `armGraceTimer` only. */
@@ -1159,22 +1197,22 @@ async function runPtcProgram(options) {
 			fail(PTC_ERROR_KIND.outputLimit, `${source} exceeded the output budget: logs + result reached ${outputBytes} bytes (maxOutputBytes=${config.maxOutputBytes}); ${logs.length} log line(s) retained`);
 			return false;
 		};
-		const acquireDispatchSlot = async () => {
-			if (activeDispatches < config.maxParallelSubCalls) {
-				activeDispatches += 1;
+		const acquireBuiltinSlot = async () => {
+			if (activeBuiltinCalls < config.maxParallelSubCalls) {
+				activeBuiltinCalls += 1;
 				return;
 			}
 			await new Promise((slot) => {
-				dispatchWaiters.push(slot);
+				builtinWaiters.push(slot);
 			});
 		};
-		const releaseDispatchSlot = () => {
-			const next = dispatchWaiters.shift();
+		const releaseBuiltinSlot = () => {
+			const next = builtinWaiters.shift();
 			if (next) {
 				next();
 				return;
 			}
-			activeDispatches -= 1;
+			activeBuiltinCalls -= 1;
 		};
 		const handleCall = (frame) => {
 			pendingCalls += 1;
@@ -1198,10 +1236,25 @@ async function runPtcProgram(options) {
 				});
 				return;
 			}
-			await acquireDispatchSlot();
-			if (settled) {
-				releaseDispatchSlot();
-				return;
+			const isDispatch = frame.tool === DISPATCH_BINDING_NAME;
+			if (isDispatch) {
+				if (activeDispatches >= config.dispatchConcurrency) {
+					postCallResult({
+						kind: HOST_FRAME_KIND.callResult,
+						callId: frame.callId,
+						tool: frame.tool,
+						ok: true,
+						value: dispatchConcurrencyLimitReached()
+					});
+					return;
+				}
+				activeDispatches += 1;
+			} else {
+				await acquireBuiltinSlot();
+				if (settled) {
+					releaseBuiltinSlot();
+					return;
+				}
 			}
 			try {
 				const value = await binding.execute(frame.args, {
@@ -1236,7 +1289,8 @@ async function runPtcProgram(options) {
 					message: messageOf(error)
 				});
 			} finally {
-				releaseDispatchSlot();
+				if (isDispatch) activeDispatches -= 1;
+				else releaseBuiltinSlot();
 			}
 		};
 		/** `true` when the worker actually received the result (see the hoist at the call site). */
@@ -1569,6 +1623,20 @@ function renderModelValue(value) {
 * `details` stays raw for the TUI. See ADR-0012.
 */
 /**
+* Read the depth baseline pi-ptc was started with inside a child pi process.
+*
+* `dispatch()` stamps `PI_PTC_DEPTH` (the child's own depth) onto the spawned subprocess's
+* environment, and the extension entrypoint reads it back here so a child PTC run's binding
+* context starts at the dispatched depth instead of at 0 — otherwise the recursion bound in
+* `dispatch()` could never bite below the first level. Only a pure non-negative integer is
+* accepted; a missing or malformed value means "not a dispatched child" and yields 0.
+*/
+function resolveDepthFromEnv(source = process.env) {
+	const raw = source.PI_PTC_DEPTH;
+	if (raw === void 0 || !/^\d+$/.test(raw)) return 0;
+	return Number.parseInt(raw, 10);
+}
+/**
 * Binding names for one run: the built-ins this session actually has enabled (T7, #21).
 *
 * A PTC program must never reach further than the session it runs in — a session started
@@ -2262,8 +2330,10 @@ function createPtcRunCodeTool(options = {}) {
 				cwd,
 				bindings: createBuiltinBindings({
 					cwd,
-					names
+					names,
+					includeDispatch: true
 				}),
+				...options.depth === void 0 ? {} : { depth: options.depth },
 				...params.timeoutMs === void 0 ? {} : { timeoutMs: params.timeoutMs },
 				...signal === void 0 ? {} : { signal },
 				...options.config === void 0 ? {} : { config: options.config },
@@ -2337,11 +2407,6 @@ const PARAMETERS = Type.Object({
 	script: Type.String({ description: "The program: the body of an async TypeScript function." }),
 	args: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Plain-JSON input bound to the program's `args` global. No functions, symbols, undefined values or cycles." }))
 });
-function describeValue(value) {
-	if (value === null) return "null";
-	if (Array.isArray(value)) return "an array";
-	return `a ${typeof value}`;
-}
 /**
 * Reject anything that is not plain JSON, with a path-qualified reason.
 *
@@ -2434,9 +2499,11 @@ function createPtcWorkflowTool(options = {}) {
 				cwd,
 				bindings: createBuiltinBindings({
 					cwd,
-					names
+					names,
+					includeDispatch: true
 				}),
 				...params.args === void 0 ? {} : { args: params.args },
+				...options.depth === void 0 ? {} : { depth: options.depth },
 				...signal === void 0 ? {} : { signal },
 				...options.config === void 0 ? {} : { config: options.config },
 				...pool === void 0 ? {} : { pool }
@@ -2880,13 +2947,21 @@ function ptcSubagents(pi) {
 	* `tools.<name>(...)` call fail.
 	*/
 	const getBindingSourceNames = () => bindingSource(mode, pi.getActiveTools());
+	/**
+	* Depth baseline for PTC runs this pi process starts (ADR-0016 Recursive section).
+	* Inside a pi process spawned by `pi.dispatch`, the env carries `PI_PTC_DEPTH`; a
+	* normal pi session has none, and the parent turn's runs stay at depth 0.
+	*/
+	const ptcDepth = resolveDepthFromEnv();
 	pi.registerTool(createPtcRunCodeTool({
 		getBindingSourceNames,
-		getPool: () => turnPools.get("run_code")
+		getPool: () => turnPools.get("run_code"),
+		depth: ptcDepth
 	}));
 	pi.registerTool(createPtcWorkflowTool({
 		getBindingSourceNames,
-		getPool: () => turnPools.get("workflow")
+		getPool: () => turnPools.get("workflow"),
+		depth: ptcDepth
 	}));
 	/**
 	* Retire the turn's pools. `drain()` terminates the warm workers, so nothing outlives the