pi-crew 0.9.68 → 0.10.2

package/src/prompt/worker-events-channel.ts

@@ -0,0 +1,173 @@
+/**
+ * worker-events-channel.ts — bounded worker self-reporting channel
+ * (WP-9 / R9, T5).
+ *
+ * The ONE worker-side primitive for appending self-reported, schema-tagged
+ * `worker.*` events to the run's events.jsonl (PI_CREW_EVENTS_PATH —
+ * unconditional since WP-9; previously scratchpad-gated, which excluded
+ * read-only roles by design and left them with no reporting path).
+ *
+ * Bounds (a worker must never be able to flood the shared event log):
+ * - SCHEMA: event types MUST match /^worker\.[a-z0-9_.-]{1,63}$/ — anything
+ *   else is dropped (return false). Worker events never impersonate
+ *   orchestrator namespaces (task.*, run.*, spec.*, …).
+ * - RATE LIMIT: sliding window, `maxEventsPerWindow` (default 30) per
+ *   `windowMs` (default 60s). Dropped events are counted; the next ACCEPTED
+ *   event carries `droppedSinceLast` so the operator sees suppression.
+ * - FIFO BUFFER CAP: failed appends (throwing writer, e.g. transient EBUSY)
+ *   queue for retry; the queue holds at most `bufferCap` (default 64) —
+ *   overflow drops the OLDEST pending (FIFO), never grows unboundedly.
+ * - CRASH SAFETY: each append is a single O_APPEND write of one JSONL line.
+ *   A crash mid-write leaves at most a trailing PARTIAL line — the
+ *   orchestrator-side reader (parseJsonlEvents) already skips corrupt lines,
+ *   so complete events before/after the partial stay readable (recoverable).
+ *
+ * Heartbeats remain the liveness corroboration source; worker.* events are
+ * informational only — the scheduler never derives liveness from them.
+ */
+
+import { appendFileSync, readFileSync } from "node:fs";
+
+export const WORKER_EVENT_TYPE_PATTERN = /^worker\.[a-z0-9_.-]{1,63}$/;
+
+export interface WorkerEventsChannelOptions {
+	/** Default: process.env (worker context). */
+	env?: NodeJS.ProcessEnv;
+	/** Append function — default: appendEventFireAndForget from state. */
+	appendEvent?: (eventsPath: string, event: Record<string, unknown>) => void;
+	now?: () => number;
+	/** Sliding-window rate limit: max accepted events per windowMs. */
+	maxEventsPerWindow?: number;
+	windowMs?: number;
+	/** FIFO cap for queued (failed) appends. */
+	bufferCap?: number;
+}
+
+export interface WorkerEventsChannel {
+	/** Emit a worker.* event. false = dropped (schema/rate/buffer reasons). */
+	emit(type: string, data: Record<string, unknown>): boolean;
+	/** Retry queued appends (called on the next emit internally). */
+	flush(): void;
+	/** Test introspection. */
+	stats(): { accepted: number; droppedSchema: number; droppedRate: number; droppedBuffer: number; queued: number };
+}
+
+export function createWorkerEventsChannel(options: WorkerEventsChannelOptions = {}): WorkerEventsChannel {
+	const env = options.env ?? process.env;
+	const now = options.now ?? Date.now;
+	const appendEvent =
+		options.appendEvent ??
+		((eventsPath: string, event: Record<string, unknown>) => {
+			// Single O_APPEND write of one JSONL line — the crash-safety contract.
+			// A previous crash may have left a trailing PARTIAL line (no newline):
+			// appending without a separator would fuse both lines into ONE corrupt
+			// line, destroying the complete event too. Guard: if the file is
+			// non-empty and does not end with \n, prepend the separator (1-byte
+			// read of the tail — the partial line stays quarantined on its own line,
+			// which the orchestrator reader skips).
+			let prefix = "";
+			try {
+				const buf = readFileSync(eventsPath);
+				if (buf.length > 0 && buf[buf.length - 1] !== 0x0a) prefix = "\n";
+			} catch {
+				/* absent file — nothing to separate */
+			}
+			appendFileSync(eventsPath, `${prefix}${JSON.stringify(event)}\n`, "utf-8");
+		});
+	const maxPerWindow = options.maxEventsPerWindow ?? 30;
+	const windowMs = options.windowMs ?? 60_000;
+	const bufferCap = options.bufferCap ?? 64;
+
+	const eventsPath = env.PI_CREW_EVENTS_PATH;
+	const runId = env.PI_CREW_BROKER_RUN_ID;
+	const taskId = env.PI_CREW_TASK_ID;
+
+	const windowStarts: number[] = [];
+	const pending: { type: string; data: Record<string, unknown>; droppedSinceLast: number }[] = [];
+	const counters = { accepted: 0, droppedSchema: 0, droppedRate: 0, droppedBuffer: 0 };
+	// Dropped-due-to-rate counter surfaced on the next ACCEPTED event (the
+	// operator sees suppression without a flood of drop events).
+	let suppressedSinceLast = 0;
+
+	const write = (item: { type: string; data: Record<string, unknown>; droppedSinceLast: number }): boolean => {
+		try {
+			appendEvent(eventsPath as string, {
+				type: item.type,
+				runId,
+				taskId,
+				data: item.droppedSinceLast > 0 ? { ...item.data, droppedSinceLast: item.droppedSinceLast } : item.data,
+			});
+			return true;
+		} catch {
+			return false;
+		}
+	};
+
+	const flushInternal = (currentDropped: number): number => {
+		let droppedCarry = currentDropped;
+		while (pending.length > 0) {
+			const item = pending[0]!;
+			if (write(item)) {
+				pending.shift();
+				counters.accepted++;
+				droppedCarry = 0;
+			} else {
+				// Writer still failing — keep the queue (bounded), stop here.
+				return droppedCarry;
+			}
+		}
+		return droppedCarry;
+	};
+
+	return {
+		emit(type: string, data: Record<string, unknown>): boolean {
+			if (!eventsPath || !runId) return false; // non-team context — no-op
+			if (!WORKER_EVENT_TYPE_PATTERN.test(type)) {
+				counters.droppedSchema++;
+				return false;
+			}
+			// Sliding-window rate limit.
+			const t = now();
+			while (windowStarts.length > 0 && t - windowStarts[0]! >= windowMs) windowStarts.shift();
+			if (windowStarts.length >= maxPerWindow) {
+				counters.droppedRate++;
+				suppressedSinceLast++;
+				return false;
+			}
+			windowStarts.push(t);
+			// Drain any queued items first (FIFO — oldest first), then the new one.
+			// The new event carries the suppression count (queue drops are already
+			// counted on their own accepted re-write).
+			if (pending.length > 0) {
+				const carry = flushInternal(0);
+				if (carry > 0) {
+					// Writer failing: queue the new item under the FIFO cap.
+					if (pending.length >= bufferCap) {
+						pending.shift();
+						counters.droppedBuffer++;
+					}
+					pending.push({ type, data, droppedSinceLast: 0 });
+					return true; // accepted (queued)
+				}
+			}
+			if (write({ type, data, droppedSinceLast: suppressedSinceLast })) {
+				counters.accepted++;
+				suppressedSinceLast = 0;
+				return true;
+			}
+			if (pending.length >= bufferCap) {
+				pending.shift();
+				counters.droppedBuffer++;
+			}
+			pending.push({ type, data, droppedSinceLast: suppressedSinceLast });
+			suppressedSinceLast = 0;
+			return true;
+		},
+		flush(): void {
+			flushInternal(0);
+		},
+		stats(): { accepted: number; droppedSchema: number; droppedRate: number; droppedBuffer: number; queued: number } {
+			return { ...counters, queued: pending.length };
+		},
+	};
+}

package/src/runtime/README.md

@@ -10,26 +10,26 @@ clusters are extracted into subdirectories; the remaining files stay at the root
 | [`child-pi/`](./child-pi/) | B-1 | child Pi worker spawn/lifecycle/steering/transcript | `child-pi.ts`, `child-pi-spawn.ts`, `child-pi-kill.ts`, `child-pi-constants.ts`, `child-pi-steering.ts`, `child-pi-streams.ts`, `child-pi-transcript.ts` |
 | [`broker/`](./broker/) | B-2 | crew broker server/client/auth (child-pi ↔ parent IPC) | `crew-broker.ts`, `crew-broker-client.ts`, `crew-broker-child.ts`, `crew-broker-tokens.ts`, `broker-issuer.ts` |
 | [`task-runner/`](./task-runner/) | (pre-existing) | per-task execution (pre-execution, child-executor) | `child-executor.ts`, `pre-execution.ts`, ... |
-| [`live-session/`](./live-session/) | 3 | live agent control/manager, session runtime, IRC, health, extension bridge | `live-session-runtime.ts`, `live-agent-manager.ts`, `live-agent-control.ts`, `live-control-realtime.ts`, `live-irc.ts`, `live-session-health.ts`, `live-extension-bridge.ts`, `intercom-bridge.ts` |
-| [`recovery/`](./recovery/) | 4 | crash recovery, retry, checkpoint | `crash-recovery.ts`, `crash-classification.ts`, `recovery-recipes.ts`, `overflow-recovery.ts`, `retry-executor.ts`, `retry-runner.ts`, `checkpoint.ts` |
+| [`live-session/`](./live-session/) | 3 | live agent control/manager, session runtime, IRC, health, extension bridge | `live-session-runtime.ts`, `live-agent-manager.ts`, `live-agent-control.ts`, `live-control-realtime.ts`, `live-irc.ts`, `live-session-health.ts`, `live-extension-bridge.ts` |
+| [`recovery/`](./recovery/) | 4 | crash recovery, retry, checkpoint | `crash-recovery.ts`, `crash-classification.ts`, `recovery-recipes.ts`, `overflow-recovery.ts`, `retry-executor.ts`, `checkpoint.ts` |
 | [`scheduling/`](./scheduling/) | 5 | scheduler, concurrency, task-graph, batch-barrier, parallel utils | `scheduler.ts`, `semaphore.ts`, `concurrency.ts`, `task-graph.ts`, `task-graph-scheduler.ts`, `batch-barrier.ts`, `coalesce-tasks.ts`, `run-coalesced-task-group.ts`, `global-worker-cap.ts`, `parallel-research.ts`, `parallel-utils.ts` |
-| [`verification/`](./verification/) | 6a | verification gates, green-contract, post-checks, completion-guard | `verification-gates.ts`, `verification-integrity.ts`, `verification-worktree.ts`, `green-contract.ts`, `post-checks.ts`, `completion-guard.ts` |
+| [`verification/`](./verification/) | 6a | verification gates, green-contract, completion-guard | `verification-gates.ts`, `verification-integrity.ts`, `verification-worktree.ts`, `green-contract.ts`, `completion-guard.ts` |
 | [`model/`](./model/) | 6b | model fallback/resolver/scope, pi-args, runtime policy/resolver/warmup | `model-fallback.ts`, `model-resolver.ts`, `model-scope.ts`, `pi-args.ts`, `runtime-policy.ts`, `runtime-resolver.ts`, `runtime-warmup.ts` |
-| [`output/`](./output/) | 6c | streaming output, progress tracking, sidechain, result extraction | `streaming-output.ts`, `stream-preview.ts`, `output-validator.ts`, `pi-json-output.ts`, `tool-progress.ts`, `progress-event-coalescer.ts`, `progress-tracker.ts`, `result-extractor.ts`, `sidechain-output.ts` |
+| [`output/`](./output/) | 6c | streaming output, progress tracking, sidechain, result extraction | `streaming-output.ts`, `output-validator.ts`, `pi-json-output.ts`, `progress-event-coalescer.ts`, `progress-tracker.ts`, `result-extractor.ts`, `sidechain-output.ts` |
 | [`heartbeat/`](./heartbeat/) | 6d | heartbeat gradient/watcher, worker heartbeat/startup | `heartbeat-gradient.ts`, `heartbeat-watcher.ts`, `worker-heartbeat.ts`, `worker-startup.ts` |
-| [`process/`](./process/) | 6e | cancellation, process lifecycle, zombie scanner, stdio guard | `cancellation-token.ts`, `cancellation.ts`, `process-lifecycle.ts`, `zombie-scanner.ts`, `post-exit-stdio-guard.ts` |
+| [`process/`](./process/) | 6e | cancellation, zombie scanner, stdio guard | `cancellation-token.ts`, `cancellation.ts`, `zombie-scanner.ts`, `post-exit-stdio-guard.ts` |
 | [`goal-workflow/`](./goal-workflow/) | 6f | goal achievement/evaluation/loop, dynamic-workflow, adaptive plan | `goal-achievement.ts`, `goal-evaluator.ts`, `goal-loop-runner.ts`, `goal-state-store.ts`, `dynamic-workflow-context.ts`, `dynamic-workflow-runner.ts`, `adaptive-plan.ts`, `plan-templates.ts` |
-| [`compaction/`](./compaction/) | 6g | compaction pipeline, tool-output-pruner, important-line-classifier, compact-stages | `compact-pipeline.ts`, `compaction-summary.ts`, `tool-output-pruner.ts`, `important-line-classifier.ts`, [`compact-stages/`](./compaction/compact-stages/) |
+| [`compaction/`](./compaction/) | 6g | compaction pipeline, tool-output-pruner, important-line-classifier, compact-stages | `compact-pipeline.ts`, `tool-output-pruner.ts`, `important-line-classifier.ts`, [`compact-stages/`](./compaction/compact-stages/) |
 | [`custom-tools/`](./custom-tools/) | (pre-existing) | custom tool definitions | `irc-tool.ts`, `submit-result-tool.ts`, ... |
 | [`errors/`](./errors/) | (pre-existing) | error types | ... |
 
 ## Remaining flat files at root (~77)
 
 - **team-runner** — `team-runner.ts` (the orchestrator) + `run-worker.ts`, `run-tracker.ts`
-- **chain/pipeline runners** — `chain-parser.ts`, `chain-runner.ts`, `pipeline-runner.ts`, `direct-run.ts`
+- **chain runners** — `chain-parser.ts`, `chain-runner.ts`, `direct-run.ts`
 - **foreground/background runners** — `foreground-control.ts`, `foreground-watchdog.ts`, `async-runner.ts`, `background-runner.ts`
 - **crew agent** — `crew-agent-records.ts`, `crew-agent-runtime.ts`, `crew-hooks.ts`, `single-agent-compose.ts`
-- **observability** — `effectiveness.ts`, `agent-observability.ts`, `command-trace.ts`, `metric-parser.ts`
+- **observability** — `effectiveness.ts`, `agent-observability.ts`, `command-trace.ts`
 - **misc** — `stale-reconciler.ts`, `parent-guard.ts`, `manifest-cache.ts`, `event-stream-bridge.ts`, `policy-engine.ts`, `role-permission.ts`, `workspace-lock.ts`, `workspace-tree.ts`, `session-*.ts`, ...
 
 See `docs/COVERAGE-ASSESSMENT-2026-08-01.md` § "Source reorganization" for the reorg history + remaining-cluster plan.

package/src/runtime/async-runner.ts

@@ -3,6 +3,7 @@ import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { getCrewEnv } from "../config/env-vars.ts";
 import { appendEventAsync } from "../state/event-log/event-log.ts";
 import type { TeamRunManifest } from "../state/types.ts";
 import { WINDOWS_ESSENTIAL_ENV_VARS } from "../utils/env-allowlist.ts";
@@ -54,8 +55,11 @@ export function resolveJitiRegisterPath(packageRoot = packageRootFromRuntime(),
 			path.join(path.dirname(pkgPath), "dist", "register.mjs"),
 		];
 		for (const c of candidates) if (exists(c)) return c;
-	} catch {
-		// Fall through.
+	} catch (error) {
+		// R17-B4 (LOW): fall-through is benign (undefined → next loader
+		// strategy), but keep the require.resolve root cause visible under
+		// PI_TEAMS_DEBUG instead of a bare catch.
+		logInternalError("async-runner.jiti-resolve", error, "require.resolve('jiti/package.json') fallback failed", "debug");
 	}
 	return undefined;
 }
@@ -124,7 +128,7 @@ export function getBackgroundRunnerCommand(
 	// default precisely so silent runner deaths (like the explore→code-review
 	// transition crash) leave a native stack/heap/environment trace. Users who
 	// don't want report files can opt out with PI_CREW_BG_REPORT_ON_FATAL=0.
-	const reportOn = !(process.env.PI_CREW_BG_REPORT_ON_FATAL === "0" || process.env.PI_TEAMS_BG_REPORT_ON_FATAL === "0");
+	const reportOn = !(getCrewEnv("PI_CREW_BG_REPORT_ON_FATAL") === "0" || getCrewEnv("PI_TEAMS_BG_REPORT_ON_FATAL") === "0");
 	const reportDir = reportDirectory ?? path.dirname(runnerPath);
 	const reportFlags = reportOn ? ["--report-on-fatalerror", "--report-compact", `--report-directory=${reportDir}`] : [];
 	if (loader.kind === "jiti") {

package/src/runtime/background-runner.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { allAgents, discoverAgents } from "../agents/discover-agents.ts";
 import { loadConfig } from "../config/config.ts";
+import { getCrewEnv } from "../config/env-vars.ts";
 import { atomicWriteFile } from "../state/atomic-write.ts";
 import { withRunLockSync } from "../state/coordination/locks.ts";
 import { appendEvent, appendEventFireAndForget } from "../state/event-log/event-log.ts";
@@ -10,6 +11,7 @@ import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { allTeams, discoverTeams } from "../teams/discover-teams.ts";
 import { errorMessage } from "../utils/guards.ts";
 import { projectCrewRoot } from "../utils/paths.ts";
+import { assertSafePathId } from "../utils/safe-paths.ts";
 import { allWorkflows, discoverWorkflows } from "../workflows/discover-workflows.ts";
 // Heavy runtime — lazy-loaded to avoid pulling team-runner into background-runner
 // at module load time. Only needed when a background run actually starts.
@@ -27,7 +29,7 @@ let _cachedExecuteTeamRun: typeof ExecuteTeamRunFn | undefined;
  *  aborts via the shared AbortController, then force-exits after a grace
  *  period in case the abort signal does not propagate to all execution paths. */
 const MAX_BACKGROUND_RUN_MS = (() => {
-	const env = Number.parseInt(process.env.PI_CREW_MAX_RUN_MS ?? "", 10);
+	const env = Number.parseInt(getCrewEnv("PI_CREW_MAX_RUN_MS") ?? "", 10);
 	return Number.isFinite(env) && env > 0 ? env : 2 * 60 * 60 * 1000;
 })();
 async function executeTeamRun(...args: Parameters<typeof ExecuteTeamRunFn>): Promise<Awaited<ReturnType<typeof ExecuteTeamRunFn>>> {
@@ -59,7 +61,7 @@ import { expandParallelResearchWorkflow } from "./scheduling/parallel-research.t
  * while keeping diagnostics available when explicitly enabled.
  */
 function debugLog(message: string): void {
-	if (process.env.PI_CREW_DEBUG) console.log(message);
+	if (getCrewEnv("PI_CREW_DEBUG")) console.log(message);
 }
 
 /**
@@ -213,7 +215,7 @@ export function startInterruptGuard(
 	const controlPath = path.join(manifest.stateRoot, "foreground-control.json");
 	// FIX: Made configurable via PI_CREW_INTERRUPT_GUARD_INTERVAL_MS env var.
 	// Default 250ms balances fast SIGINT response against filesystem overhead.
-	const interruptGuardInterval = Number(process.env.PI_CREW_INTERRUPT_GUARD_INTERVAL_MS) || 250;
+	const interruptGuardInterval = Number(getCrewEnv("PI_CREW_INTERRUPT_GUARD_INTERVAL_MS")) || 250;
 	// RT-4 FIX: Module-local gate so the interrupt body runs only once per
 	// interrupt request. Without this, the guard re-fires every
 	// interruptGuardInterval (250ms) — each tick does a full
@@ -410,6 +412,13 @@ async function main(): Promise<void> {
 	const _cwd = argValue("--cwd");
 	const _runId = argValue("--run-id");
 	if (_cwd && _runId) {
+		// R11-2 (LOW, §ROUND 11 security hardening): assert the argv-supplied
+		// runId at the argValue boundary BEFORE any path construction — the
+		// background.log join would otherwise embed an untrusted runId (future
+		// user-supplied --resume) → path traversal outside the run root. Throws
+		// at startup for unsafe ids (intended fail-fast; placed OUTSIDE the
+		// best-effort try/catch so the hardening is never silently swallowed).
+		assertSafePathId("runId", _runId);
 		try {
 			// Use projectCrewRoot() so the background log lives next to the
 			// manifest in either .crew/state/runs/ or .pi/teams/state/runs/
@@ -464,6 +473,10 @@ async function main(): Promise<void> {
 		const cwd = argValue("--cwd");
 		const runId = argValue("--run-id");
 		if (!cwd || !runId) return undefined;
+		// R11-2 (LOW, §ROUND 11): same argv boundary hardening as main() — this
+		// IIFE runs at MODULE LOAD, so an unsafe runId throws before the runner
+		// starts (intended fail-fast, matching run-import.ts:105 pattern).
+		assertSafePathId("runId", runId);
 		// Use projectCrewRoot() to honour the .pi/teams/ fallback (issue #29).
 		return path.join(projectCrewRoot(cwd), "state", "runs", runId, "exit-code.txt");
 	})();
@@ -611,7 +624,7 @@ async function main(): Promise<void> {
 	setupUnhandledRejectionGuard(rejectionGuardState, abortController, setExitFlag);
 
 	// Start parent guard — if parent is already dead, exit immediately
-	const parentPid = Number(process.env.PI_CREW_PARENT_PID);
+	const parentPid = Number(getCrewEnv("PI_CREW_PARENT_PID"));
 	if (parentPid > 0) startParentGuard(parentPid);
 	// NOTE: intentionally no unref() — the guard keeps the event loop alive
 	// to prevent premature worker exit. See parent-guard.ts:86 for rationale.
@@ -880,10 +893,32 @@ async function main(): Promise<void> {
 		if (manifest.status === "failed" || manifest.status === "cancelled" || manifest.status === "blocked") process.exitCode = 1;
 	} catch (error) {
 		// Terminate live agents on failure too — agents are done when the run fails
+		const message = errorMessage(error);
 		try {
-			const loaded = withRunLockSync(manifest, () => loadRunManifestById(cwd, runId), { staleMs: 30_000 }); // Use withRunLockSync to prevent race with concurrent writers (e.g., stale reconciler)
-			// between the read and the subsequent save.
-			const manifestToUse = loaded?.manifest ?? manifest;
+			// R14-2: re-read INSIDE the lock and derive the failed-status write from the
+			// FRESH manifest. The outer `manifest` is a pre-throw snapshot — using it
+			// here could flip a concurrently completed/cancelled run back to "failed"
+			// (updateRunStatus validates against the fresh on-disk status; an illegal
+			// flip throws and is swallowed by the best-effort catch below). Keeping the
+			// write inside withRunLockSync prevents race with concurrent writers
+			// (e.g., stale reconciler) between the read and the subsequent save.
+			const manifestToUse = withRunLockSync(
+				manifest,
+				() => {
+					const loaded = loadRunManifestById(cwd, runId);
+					const fresh = loaded?.manifest ?? manifest;
+					if (fresh) {
+						manifest = updateRunStatus(fresh, "failed", message);
+						appendEvent(manifest.eventsPath, {
+							type: "async.failed",
+							runId: manifest.runId,
+							message,
+						});
+					}
+					return fresh;
+				},
+				{ staleMs: 30_000 },
+			);
 			if (manifestToUse) {
 				// LAZY: live-agent-manager only needed on failure cleanup path; avoid module load at hot path.
 				const { terminateLiveAgentsForRun } = await import("./live-session/live-agent-manager.ts");
@@ -894,13 +929,6 @@ async function main(): Promise<void> {
 		} catch {
 			/* best-effort */
 		}
-		const message = errorMessage(error);
-		manifest = updateRunStatus(manifest, "failed", message);
-		appendEvent(manifest.eventsPath, {
-			type: "async.failed",
-			runId: manifest.runId,
-			message,
-		});
 		process.exitCode = 1;
 		console.log(`[background-runner] catch block, error=${errorMessage(error)}`);
 	} finally {

package/src/runtime/broker/broker-issuer.ts

@@ -23,8 +23,15 @@ export interface BrokerSpawnCredentials {
 /** Issuer signature: given a runId (+optional taskId for per-task tokens),
  *  return credentials or undefined when the broker is disabled / this process
  *  is not the root session. taskId is optional for backward compat — callers
- *  that still pass only runId receive the legacy per-run token. */
-export type BrokerIssuer = (runId: string, taskId?: string) => Promise<BrokerSpawnCredentials | undefined>;
+ *  that still pass only runId receive the legacy per-run token.
+ *
+ *  ADR-5 §4 (governed nesting): `childDepth` carries the DEPTH-2+ grandchild's
+ *  depth when the root-side delegate handler spawns it. The issuer mints only
+ *  for children that may themselves delegate (childDepth < resolved
+ *  PI_CREW_MAX_DEPTH) — at the default maxDepth=2 a depth-2 grandchild gets NO
+ *  credentials (env containment AC: no PI_CREW_BROKER_SOCKET/TOKEN at depth 2).
+ *  Undefined childDepth = legacy worker spawn (depth 1) — unchanged behavior. */
+export type BrokerIssuer = (runId: string, taskId?: string, childDepth?: number) => Promise<BrokerSpawnCredentials | undefined>;
 
 let activeIssuer: BrokerIssuer | undefined;
 

package/src/runtime/broker/crew-broker-tokens.ts

@@ -123,17 +123,54 @@ export class BrokerTokenRegistry {
 	 *  if the candidate matches the run's orchestrator token, "worker" if it
 	 *  matches a per-task/per-run token, or null if neither. Orchestrator key
 	 *  is checked FIRST so an orchestrator token can never be confused with a
-	 *  task token (the two are cryptographically distinct by construction). */
+	 *  task token (the two are cryptographically distinct by construction).
+	 *  Semantics unchanged since extraction; now delegates to
+	 *  tokenRoleWithMatchKind() so both share one compare path. */
 	tokenRole(runId: string, taskId: string | undefined, candidate: unknown): "orchestrator" | "worker" | null {
+		const resolved = this.tokenRoleWithMatchKind(runId, taskId, candidate);
+		return resolved === null ? null : resolved.role;
+	}
+
+	/** Same resolution as tokenRole() but also reports HOW the token matched:
+	 *  `"compound"` (task-scoped `${runId}:${taskId}` key — or the
+	 *  orchestrator key, which is runId-prefixed by construction and can
+	 *  never be reached via the fallback) vs `"runId-fallback"` (legacy
+	 *  bare-runId key matched because no compound key was issued).
+	 *
+	 *  WP-2/R2 (ADR-0 2026-08-17-waiting-producer-ask item 6): the broker's
+	 *  `wait.*` methods authenticate via task-scoped tokens ONLY — a
+	 *  `"runId-fallback"` match is rejected at the dispatch site with a
+	 *  migrate hint. Legacy methods keep using tokenRole()/matches() and
+	 *  therefore keep accepting the fallback (backward compat preserved).
+	 *
+	 *  Match semantics mirror tokenRole() exactly: the bare-runId fallback is
+	 *  consulted ONLY when no compound key exists for (runId, taskId) — a
+	 *  candidate matching the bare key while a DIFFERENT compound key exists
+	 *  still returns null (no accidental fallback activation). */
+	tokenRoleWithMatchKind(
+		runId: string,
+		taskId: string | undefined,
+		candidate: unknown,
+	): { role: "orchestrator" | "worker"; matchKind: "compound" | "runId-fallback" } | null {
 		if (BrokerTokenRegistry.equalConstTime(this.map.get(this.orchestratorKey(runId)), candidate)) {
-			return "orchestrator";
+			return { role: "orchestrator", matchKind: "compound" };
+		}
+		// No taskId → the key degenerates to bare runId; there is no task
+		// scoping at all, so an honest matchKind is "runId-fallback".
+		if (taskId === undefined) {
+			return BrokerTokenRegistry.equalConstTime(this.map.get(runId), candidate)
+				? { role: "worker", matchKind: "runId-fallback" }
+				: null;
+		}
+		const compound = this.map.get(this.key(runId, taskId));
+		if (compound !== undefined) {
+			return BrokerTokenRegistry.equalConstTime(compound, candidate) ? { role: "worker", matchKind: "compound" } : null;
 		}
-		let expected = this.map.get(this.key(runId, taskId));
 		// Backward-compat: per-run token issued without taskId.
-		if (expected === undefined && taskId) {
-			expected = this.map.get(runId);
+		if (BrokerTokenRegistry.equalConstTime(this.map.get(runId), candidate)) {
+			return { role: "worker", matchKind: "runId-fallback" };
 		}
-		return BrokerTokenRegistry.equalConstTime(expected, candidate) ? "worker" : null;
+		return null;
 	}
 
 	/** Remove the token for `runId` (+optional `taskId`).