pi-crew 0.9.68 → 0.10.1

package/src/runtime/scheduling/run-coalesced-task-group.ts

@@ -2,7 +2,7 @@ import type { AgentConfig } from "../../agents/agent-config.ts";
 import type { CrewReliabilityConfig, CrewRuntimeConfig } from "../../config/types.ts";
 import { appendEventAsync } from "../../state/event-log/event-log.ts";
 import { writeArtifact } from "../../state/stores/artifact-store.ts";
-import { saveRunTasksAsync, updateRunStatus } from "../../state/stores/state-store.ts";
+import { loadRunManifestById, saveRunTasksAsync, updateRunStatus } from "../../state/stores/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
 import type { WorkflowStep } from "../../workflows/workflow-config.ts";
 import { createWorkerHeartbeat, touchWorkerHeartbeat } from "../heartbeat/worker-heartbeat.ts";
@@ -115,17 +115,12 @@ export async function runCoalescedTaskGroup(input: CoalescedTaskGroupInput): Pro
 			heartbeatInFlight = true;
 			heartbeatPromise = (async () => {
 				try {
-					updatedTasks = updatedTasks.map((t) => {
-						if (!taskIds.includes(t.id)) return t;
-						// FIND-06 belt-and-suspenders: never replace terminal state or its
-						// resultArtifact with a heartbeat-only snapshot.
-						if (t.status === "completed" || t.status === "failed" || t.status === "cancelled") return t;
-						return {
-							...t,
-							heartbeat: touchWorkerHeartbeat(t.heartbeat ?? createWorkerHeartbeat(t.id), { alive: true }),
-						};
-					});
-					await saveRunTasksAsync(manifest, updatedTasks);
+					// R15-3: persist heartbeats for ONLY this group's tasks via a fresh
+					// disk read. The old closure `updatedTasks` is a dispatch-time
+					// snapshot of the FULL task array — a sibling cancelled on disk after
+					// dispatch could be un-cancelled by a late heartbeat save (the map
+					// only mutated group tasks, but the SAVE wrote the whole stale array).
+					await persistGroupHeartbeats(manifest, taskIds);
 				} catch {
 					// Run may have been pruned mid-dispatch — best-effort only.
 				} finally {
@@ -134,9 +129,12 @@ export async function runCoalescedTaskGroup(input: CoalescedTaskGroupInput): Pro
 					// save was in flight, re-write the (now-terminal) updatedTasks so
 					// our late snapshot cannot leave stale pre-terminal state on disk.
 					// Runs after our own save resolves, so it always lands last.
+					// R15-3: the repair now fresh-reads disk and re-applies ONLY the
+					// group's terminal state — the old full-array write could resurrect
+					// a sibling cancelled on disk (same flaw as the heartbeat save).
 					if (finalWriteStarted) {
 						try {
-							await saveRunTasksAsync(manifest, updatedTasks);
+							await repairGroupTerminalWrite(manifest, taskIds, updatedTasks);
 						} catch {
 							// best-effort repair — same swallow policy as the heartbeat.
 						}
@@ -298,6 +296,59 @@ export async function runCoalescedTaskGroup(input: CoalescedTaskGroupInput): Pro
 	return { manifest: updatedManifest, tasks: updatedTasks, taskIds, rawOutput, success };
 }
 
+/**
+ * R15-3: heartbeat save scoped to this coalesced group only.
+ *
+ * Previously the heartbeat wrote the dispatch-time closure `updatedTasks` —
+ * the FULL task array including sibling tasks outside this group. A sibling
+ * cancelled on disk after dispatch (external cancel / reconciler) could be
+ * un-cancelled ("resurrected") by a late heartbeat save, because the map only
+ * mutated group tasks but the SAVE wrote the whole stale array. Fix: fresh
+ * re-read tasks from disk (loadRunManifestById — the established fresh-read
+ * pattern used by team-runner) and write back ONLY the group's own task ids
+ * with heartbeats touched; sibling tasks are preserved untouched from the
+ * fresh disk read. Keeps the FIND-06 'never replace terminal state' guard.
+ */
+async function persistGroupHeartbeats(manifest: TeamRunManifest, taskIds: string[]): Promise<void> {
+	const fresh = loadRunManifestById(manifest.cwd, manifest.runId);
+	if (!fresh) return; // run pruned mid-dispatch — best-effort only.
+	const merged = fresh.tasks.map((t) => {
+		if (!taskIds.includes(t.id)) return t; // sibling tasks: preserved untouched.
+		// FIND-06 belt-and-suspenders: never replace terminal state or its
+		// resultArtifact with a heartbeat-only snapshot.
+		if (t.status === "completed" || t.status === "failed" || t.status === "cancelled") return t;
+		return {
+			...t,
+			heartbeat: touchWorkerHeartbeat(t.heartbeat ?? createWorkerHeartbeat(t.id), { alive: true }),
+		};
+	});
+	await saveRunTasksAsync(manifest, merged);
+}
+
+/**
+ * R15-3: FIND-06 P1 repair — re-apply the group's terminal state after a late
+ * heartbeat save may have landed last. Fresh-reads disk so sibling tasks are
+ * preserved untouched; only the group's own terminal state from `updatedTasks`
+ * is re-applied, and a disk-terminal group task is never flipped (same
+ * belt-and-suspenders guard as the heartbeat).
+ */
+async function repairGroupTerminalWrite(manifest: TeamRunManifest, taskIds: string[], updatedTasks: TeamTaskState[]): Promise<void> {
+	const fresh = loadRunManifestById(manifest.cwd, manifest.runId);
+	if (!fresh) return; // run pruned mid-dispatch — best-effort only.
+	const groupById = new Map(updatedTasks.map((t) => [t.id, t] as const));
+	const merged = fresh.tasks.map((t) => {
+		if (!taskIds.includes(t.id)) return t; // sibling tasks: preserved untouched.
+		if (t.status === "completed" || t.status === "failed" || t.status === "cancelled") return t;
+		return groupById.get(t.id) ?? t;
+	});
+	await saveRunTasksAsync(manifest, merged);
+}
+
+/** @internal 3.5 R15-3 test export — exercise the heartbeat/repair writes directly. */
+export const __test__persistGroupHeartbeats = persistGroupHeartbeats;
+/** @internal 3.5 R15-3 test export — exercise the terminal repair write directly. */
+export const __test__repairGroupTerminalWrite = repairGroupTerminalWrite;
+
 async function buildCoalescedPrompt(
 	manifest: TeamRunManifest,
 	step: WorkflowStep,

package/src/runtime/scheduling/task-graph-scheduler.ts

@@ -48,16 +48,6 @@ export function buildTaskGraphIndex(tasks: TeamTaskState[]): TaskGraphIndex {
 	return fresh;
 }
 
-/** Test/diagnostic helper — invalidate the WeakMap-backed index cache. Not
- *  used by production code paths; the WeakMap self-invalidates when a tasks
- *  array goes out of scope. Provided for parity with `clearStablePrefixCache`. */
-export function clearTaskGraphIndexCache(): void {
-	// WeakMap has no `.clear()`; rely on GC. Exposed as a no-op stub so callers
-	// that import `clearStablePrefixCache` (also a no-op stub for symmetry) can
-	// adopt a parallel API if needed in the future. Documented as no-op rather
-	// than removed so the API stays discoverable.
-}
-
 function taskById(tasks: TeamTaskState[]): Map<string, TeamTaskState> {
 	return new Map(tasks.map((task) => [task.id, task]));
 }

package/src/runtime/settings-store.ts

@@ -1,6 +1,8 @@
 import * as fs from "node:fs";
 import { homedir } from "node:os";
 import * as path from "node:path";
+import { projectOverrideWarning, sanitizeProjectConfig } from "../config/sanitize-project-config.ts";
+import type { PiTeamsConfig } from "../config/types.ts";
 import { atomicWriteJson } from "../state/atomic-write.ts";
 import { withFileLockSync } from "../state/coordination/locks.ts";
 import { logInternalError } from "../utils/internal-error.ts";
@@ -12,6 +14,11 @@ export interface CrewSettings {
 	graceTurns?: number;
 	defaultJoinMode?: JoinMode;
 	schedulingEnabled?: boolean;
+	/** Wave B2: user-tier-only opt-in for project-tier scheduledJobs. Semantics
+	 *  are enforced at the tiers layer (loadCrewSettingsTiers), NOT here — the
+	 *  flat sanitizeSettings allowlist must merely preserve the flag so the
+	 *  opt-in survives the read of the user-tier global file. */
+	allowProjectScheduledJobs?: boolean;
 	notifierIntervalMs?: number;
 	/** Scheduled jobs loaded from settings — opaque, passed to crewScheduler */
 	scheduledJobs?: unknown[];
@@ -61,6 +68,9 @@ function sanitizeSettings(raw: unknown): CrewSettings {
 	if (typeof r.schedulingEnabled === "boolean") {
 		out.schedulingEnabled = r.schedulingEnabled;
 	}
+	if (typeof r.allowProjectScheduledJobs === "boolean") {
+		out.allowProjectScheduledJobs = r.allowProjectScheduledJobs;
+	}
 	if (typeof r.notifierIntervalMs === "number" && r.notifierIntervalMs >= 1000) {
 		out.notifierIntervalMs = r.notifierIntervalMs;
 	}
@@ -89,6 +99,21 @@ function readSettingsFile(filePath: string): CrewSettings {
 	}
 }
 
+/**
+ * LEGACY merged view — USER-TIER-ONLY ingestion path (P1 fix follow-up, bug-026 adjacent).
+ *
+ * Merges the user-tier global file OVER the project file into one flat object.
+ * This view is trusted and MUST NOT be applied to live config anymore: the
+ * project fragment bypasses `sanitizeProjectConfig`. The current consumer
+ * path is `loadCrewSettingsTiers()` + `applyCrewSettingsTiersToConfig()`
+ * (project fragment routed through the schema-driven tiering, Wave 2B).
+ *
+ * If you need to read crew settings for CONFIG APPLICATION, use the tiers
+ * API — never this function. Kept exported for back-compat reads/tests;
+ * adding a new consumer that writes into loadedConfig re-introduces the
+ * fixed P1 bypass (see docs/decisions/2026-08-15-schema-driven-sanitize.md
+ * and the Wave 2B execution log in docs/refactor-plan.md).
+ */
 export function loadCrewSettings(cwd: string = process.cwd()): CrewSettings {
 	return {
 		...readSettingsFile(globalPath()),
@@ -135,6 +160,21 @@ export function updateCrewSettings(cwd: string, mutator: (settings: CrewSettings
 	});
 }
 
+/**
+ * LEGACY direct-apply — USER-TIER-ONLY (P1 fix follow-up).
+ *
+ * Writes settings straight into a config object with NO sanitize tiering.
+ * Applying a merged (user+project) `CrewSettings` through this function is
+ * exactly the P1 bypass fixed in Wave 2B: project-tier values would land in
+ * guard fields (`limits.maxConcurrentWorkers`, `runtime.maxTurns`, ...) with
+ * no conditional drops. The tiered replacement is
+ * `applyCrewSettingsTiersToConfig()` which routes the project fragment
+ * through `sanitizeProjectConfig` + tighten-only comparison.
+ *
+ * Do NOT add new call sites that pass a merged/project-influenced settings
+ * object. Acceptable use: tests, and user-tier-only tooling that has already
+ * separated tiers.
+ */
 export function applyCrewSettingsToConfig(
 	config: {
 		limits?: { maxConcurrentWorkers?: number };
@@ -153,3 +193,182 @@ export function applyCrewSettingsToConfig(
 	if (settings.defaultJoinMode != null && config.runtime) config.runtime.groupJoin = settings.defaultJoinMode;
 	if (settings.notifierIntervalMs != null) config.notifierIntervalMs = settings.notifierIntervalMs;
 }
+
+// ---------------------------------------------------------------------------
+// Wave 2B (ITEM 1, P1 security): tiered loading + guarded apply.
+//
+// `<cwd>/.pi/crew-settings.json` is PROJECT-tier state — a cloned repository
+// can ship it. `loadCrewSettings()` historically merged it OVER the user-tier
+// `~/.pi/crew-settings.json` with only the type/range allowlist
+// (`sanitizeSettings`), and `applyCrewSettingsToConfig` then wrote the merged
+// result into guard fields (limits.maxConcurrentWorkers,
+// runtime.maxTurns/graceTurns) AFTER `loadConfig()` had already sanitized the
+// regular project config files — a full bypass of `sanitizeProjectConfig`.
+// The functions below close that hole.
+// ---------------------------------------------------------------------------
+
+/** Tiered view of crew settings (see `loadCrewSettingsTiers`). */
+export interface CrewSettingsTiers {
+	/** User-tier `~/.pi/crew-settings.json` — fully trusted. */
+	user: CrewSettings;
+	/** Project-tier `<cwd>/.pi/crew-settings.json` — UNTRUSTED input. */
+	project: CrewSettings;
+	/** Historical merge view (project wins over user). Kept for the write-path
+	 *  round-trip (`updateCrewSettings`). NOT the registration source for
+	 *  scheduledJobs anymore — use `effectiveScheduledJobs` (Wave B2 gate). */
+	merged: CrewSettings;
+	/** Wave B2 GATE — what consumers register: user-tier scheduledJobs plus
+	 *  project-tier scheduledJobs ONLY when the user tier explicitly opted in
+	 *  (user.schedulingEnabled === true && user.allowProjectScheduledJobs ===
+	 *  true). User-first concat order. */
+	effectiveScheduledJobs: unknown[];
+	/** Absolute path of the project-tier file (used in warnings). */
+	projectPath: string;
+}
+
+/** Wave B2 gate predicate: the user tier opts in to project-tier scheduledJobs
+ *  only when BOTH flags are explicitly `true` in the user-tier global file.
+ *  Any other combination (flags absent, either false) opts OUT. */
+function projectScheduledJobsOptIn(user: CrewSettings): boolean {
+	return user.schedulingEnabled === true && user.allowProjectScheduledJobs === true;
+}
+
+/**
+ * Load crew settings keeping the trust tiers distinguishable. The optional
+ * `globalFile` parameter defaults to `~/.pi/crew-settings.json` and exists so
+ * callers/tests can pin a hermetic user-tier file.
+ */
+export function loadCrewSettingsTiers(cwd: string = process.cwd(), globalFile: string = globalPath()): CrewSettingsTiers {
+	const user = readSettingsFile(globalFile);
+	const projectFilePath = projectPath(cwd);
+	const project = readSettingsFile(projectFilePath);
+	const effectiveScheduledJobs: unknown[] = [
+		...(user.scheduledJobs ?? []),
+		...(projectScheduledJobsOptIn(user) ? (project.scheduledJobs ?? []) : []),
+	];
+	return { user, project, merged: { ...user, ...project }, effectiveScheduledJobs, projectPath: projectFilePath };
+}
+
+/**
+ * Apply crew settings to a config with correct trust tiering. Returns the
+ * list of drop warnings (standard project-override format).
+ *
+ * Pipeline for the PROJECT tier (the user tier is fully trusted and applied
+ * exactly like the legacy merged semantics):
+ *  1. CHOKE POINT — the fragment is mapped into `PiTeamsConfig` shape and run
+ *     through `sanitizeProjectConfig`, the same schema-driven sanitize every
+ *     other project-scoped config ingestion passes through (config.ts applies
+ *     it to pi-teams.json and .pi/pi-crew.json). Today none of the mapped
+ *     fields are sensitive-marked, so this is behavior-preserving — but any
+ *     future `sensitive: true` mark or CONDITIONAL_PROJECT_DROPS entry on
+ *     these paths automatically applies to crew-settings too.
+ *  2. TIGHTEN-ONLY TIERING — `limits.maxConcurrentWorkers`,
+ *     `runtime.maxTurns` and `runtime.graceTurns` are resource guards: a
+ *     project-tier value that RAISES the effective value (baseline = config
+ *     after the trusted user tier was applied) is dropped with the standard
+ *     warning; lowering/equal survives. A value with NO baseline is also
+ *     dropped: introducing a limit the user never set cannot be verified as
+ *     tightening, and the only legitimate writer (updateCrewSettings
+ *     spreading merged settings into the project file) always mirrors a
+ *     user-tier value, so the equal case survives. This comparison lives HERE
+ *     and not in CONDITIONAL_PROJECT_DROPS: that table is a fixed value
+ *     predicate with no access to the effective-config baseline (Wave 2B
+ *     decision — predicate signature intentionally unchanged).
+ *  3. Survivors are applied over the user tier — safe by construction since
+ *     survivors can only be equal-or-lower guard values.
+ *
+ * BOUNDARY (Wave B2 — was ITEM 1.4): scheduling is a USER-TIER decision.
+ * `schedulingEnabled` is never honored from the project tier — a project file
+ * can neither enable nor disable scheduling (no consumer reads it in src/
+ * today; if one is added it MUST read only the user tier). Project-tier
+ * `scheduledJobs` are DROPPED (warning emitted below + left out of the gated
+ * `effectiveScheduledJobs` view that the scheduler registration consumer
+ * loops) unless the user-tier global file explicitly opts in with BOTH
+ * `schedulingEnabled: true` AND `allowProjectScheduledJobs: true`. The
+ * tighten-only philosophy is intentionally NOT applied here: jobs are not
+ * numeric bounds — allowing them is an availability decision the human user
+ * makes in their global file. UX consequence (accepted): `crew schedule
+ * add/update/remove` persists jobs into the PROJECT file (handle-schedule.ts),
+ * so crew-schedule users must set both flags in ~/.pi/crew-settings.json or
+ * their own jobs stop registering on session_start.
+ *
+ * `notifierIntervalMs` (UI poll cadence) and `runtime.groupJoin` (join
+ * semantics) are not guard fields and ride the choke point only.
+ */
+export function applyCrewSettingsTiersToConfig(config: PiTeamsConfig, tiers: CrewSettingsTiers): string[] {
+	const warnings: string[] = [];
+	// User tier: fully trusted, identical to the legacy merged semantics.
+	applyCrewSettingsToConfig(config, tiers.user);
+
+	const project = tiers.project;
+	// Wave B2 scheduling gate — MUST run BEFORE the empty-fragment early return
+	// below: a project file containing ONLY scheduling fields would otherwise
+	// skip the warnings entirely. Both warnings are warning-only: neither field
+	// maps into PiTeamsConfig; registration consumers read the gated
+	// `effectiveScheduledJobs` view instead.
+	if (project.schedulingEnabled !== undefined) {
+		// Project can neither enable nor disable scheduling — always dropped.
+		warnings.push(projectOverrideWarning(tiers.projectPath, "schedulingEnabled"));
+	}
+	if (!projectScheduledJobsOptIn(tiers.user) && Array.isArray(project.scheduledJobs) && project.scheduledJobs.length > 0) {
+		warnings.push(projectOverrideWarning(tiers.projectPath, "scheduledJobs"));
+	}
+	if (
+		project.maxConcurrent == null &&
+		project.defaultMaxTurns == null &&
+		project.graceTurns == null &&
+		project.defaultJoinMode == null &&
+		project.notifierIntervalMs == null
+	) {
+		return warnings;
+	}
+
+	const fragment: PiTeamsConfig = {};
+	if (project.maxConcurrent != null) fragment.limits = { maxConcurrentWorkers: project.maxConcurrent };
+	if (project.defaultMaxTurns != null || project.graceTurns != null || project.defaultJoinMode != null) {
+		const runtime: NonNullable<PiTeamsConfig["runtime"]> = {};
+		if (project.defaultMaxTurns != null) runtime.maxTurns = project.defaultMaxTurns;
+		if (project.graceTurns != null) runtime.graceTurns = project.graceTurns;
+		// Legacy quirk (kept for behavior parity): crew-settings JoinMode allows
+		// "async", which is not part of runtime.groupJoin's union — the old
+		// structural param type let this through implicitly.
+		if (project.defaultJoinMode != null)
+			runtime.groupJoin = project.defaultJoinMode as NonNullable<PiTeamsConfig["runtime"]>["groupJoin"];
+		fragment.runtime = runtime;
+	}
+	if (project.notifierIntervalMs != null) fragment.notifierIntervalMs = project.notifierIntervalMs;
+
+	const sanitized = sanitizeProjectConfig(tiers.projectPath, config, fragment);
+	warnings.push(...sanitized.warnings);
+
+	const guards: Array<{ dotted: string; value: number | undefined; baseline: number | undefined }> = [
+		{
+			dotted: "limits.maxConcurrentWorkers",
+			value: sanitized.config.limits?.maxConcurrentWorkers,
+			baseline: config.limits?.maxConcurrentWorkers,
+		},
+		{ dotted: "runtime.maxTurns", value: sanitized.config.runtime?.maxTurns, baseline: config.runtime?.maxTurns },
+		{ dotted: "runtime.graceTurns", value: sanitized.config.runtime?.graceTurns, baseline: config.runtime?.graceTurns },
+	];
+	const dropped = new Set<string>();
+	for (const guard of guards) {
+		if (guard.value === undefined) continue;
+		if (guard.baseline === undefined || guard.value > guard.baseline) {
+			dropped.add(guard.dotted);
+			warnings.push(projectOverrideWarning(tiers.projectPath, guard.dotted));
+		}
+	}
+
+	if (!dropped.has("limits.maxConcurrentWorkers") && sanitized.config.limits?.maxConcurrentWorkers != null && config.limits) {
+		config.limits.maxConcurrentWorkers = sanitized.config.limits.maxConcurrentWorkers;
+	}
+	if (sanitized.config.runtime != null && config.runtime) {
+		if (!dropped.has("runtime.maxTurns") && sanitized.config.runtime.maxTurns != null)
+			config.runtime.maxTurns = sanitized.config.runtime.maxTurns;
+		if (!dropped.has("runtime.graceTurns") && sanitized.config.runtime.graceTurns != null)
+			config.runtime.graceTurns = sanitized.config.runtime.graceTurns;
+		if (sanitized.config.runtime.groupJoin != null) config.runtime.groupJoin = sanitized.config.runtime.groupJoin;
+	}
+	if (sanitized.config.notifierIntervalMs != null) config.notifierIntervalMs = sanitized.config.notifierIntervalMs;
+	return warnings;
+}

package/src/runtime/spawn-policy.ts

@@ -0,0 +1,217 @@
+/**
+ * Spawn policy for delegate-driven grandchild admission (ADR-5, WP-5 step 3).
+ *
+ * Pure evaluation — no I/O, no state mutation. The root-side delegate handler
+ * (broker `delegate` method, WP-5 step 5) gathers the inputs and calls
+ * `evaluateDelegateAdmission`; on denial it returns the fail-fast message to
+ * the worker and logs `delegate.rejected` to events.jsonl (never silent).
+ *
+ * Gate dimensions (each with a distinct machine-readable reason + fail-fast
+ * message; evaluated in this order — cheapest/most-global first):
+ *   1. nesting-disabled   — `nesting.enabled` is false (DEFAULT; fail-closed)
+ *   2. role-denied        — the PARENT task's role is not executor-class
+ *                           (read-only roles cannot raise spawn privileges),
+ *                           or the requested grandchild role is not one of
+ *                           the delegate-tool's allowed roles
+ *   3. trust-denied       — untrusted escalation context (manual-only trust
+ *                           gate; the handler resolves trust, policy enforces)
+ *   4. depth-exceeded     — child depth (parent.depth + 1) exceeds the
+ *                           resolved maxDepth (default 2). Depth comes from
+ *                           the parent task RECORD, never worker env
+ *                           (design §7 rev-2 P0-2)
+ *   5. slots-exhausted    — nested-slot budget exhausted ("N/M in flight");
+ *                           fail-fast, never queue
+ *   6. budget-insufficient— requested budgetTokens exceed the parent task's
+ *                           remaining allocation (tokensGranted - tokensSpent)
+ *   7. model-invalid      — requested model is not in the resolved model
+ *                           catalog (the unvalidated provider/model
+ *                           pass-through — model-fallback.ts:282, the
+ *                           429-cascade root — must not be reachable here)
+ *   8. timeout-invalid    — timeoutSec outside 1..MAX (default 900)
+ */
+
+import { modelRefToString } from "./model/model-fallback.ts";
+import type { NestedSlotSnapshot } from "./scheduling/nested-slots.ts";
+
+/** Delegate tool's allowed grandchild roles (design §7 surface). */
+export const DELEGATE_ALLOWED_ROLES = ["explorer", "analyst", "executor"] as const;
+export type DelegateRole = (typeof DELEGATE_ALLOWED_ROLES)[number];
+
+/**
+ * Roles permitted to CALL delegate (executor-class). Read-only/review roles
+ * (explorer, analyst, planner, critic, reviewer, verifier, writer,
+ * security-reviewer) are denied — delegation is a spawn privilege.
+ */
+export const EXECUTOR_CLASS_ROLES = ["executor", "test-engineer"] as const;
+
+export const DEFAULT_DELEGATE_TIMEOUT_SEC = 900;
+export const MAX_DELEGATE_TIMEOUT_SEC = 86_400;
+
+export type SpawnPolicyDenyReason =
+	| "nesting-disabled"
+	| "role-denied"
+	| "trust-denied"
+	| "depth-exceeded"
+	| "slots-exhausted"
+	| "budget-insufficient"
+	| "model-invalid"
+	| "timeout-invalid"
+	| "workspace-conflict";
+
+export interface DelegateAdmissionInput {
+	/** Resolved `nesting.enabled` config (DEFAULT false — fail-closed, ADR-5 §10). */
+	nestingEnabled: boolean;
+	/** Resolved max depth (nesting.maxDepth default 2; env clamp mirrors PI_CREW_MAX_DEPTH 1..10). */
+	maxDepth: number;
+	/** Parent task record fields the policy is allowed to trust. */
+	parentTask: {
+		taskId: string;
+		role: string;
+		/** Absent on pre-v2 records — treated as depth 1 (a worker). */
+		depth?: number;
+		allocation?: { tokensGranted?: number; tokensSpent?: number };
+	};
+	/** Untrusted escalation context — the delegate handler resolves trust. */
+	untrusted?: boolean;
+	/** Nested-slot budget snapshot (used/max). */
+	slots: NestedSlotSnapshot;
+	/** Requested grandchild parameters (all optional in the tool surface). */
+	requested?: {
+		role?: string;
+		model?: string;
+		budgetTokens?: number;
+		timeoutSec?: number;
+	};
+	/**
+	 * Resolved model catalog as canonical `provider/id` strings. When omitted
+	 * (catalog unavailable at the call-site) model validation is SKIPPED —
+	 * flag this in review; the broker handler must always supply it.
+	 */
+	modelCatalog?: readonly string[];
+	/** ADR-5 §9 workspace interaction: when the requested grandchild role is
+	 * write-capable (executor-class), an overlapping in-flight executor can
+	 * only be tolerated when serialization is established. `serializeEnabled`
+	 * mirrors config `limits.serializeOnPathOverlap`; `overlappingInFlightExecutors`
+	 * counts OTHER running executor-class tasks sharing the parent task's cwd. */
+	workspace?: {
+		serializeEnabled?: boolean;
+		overlappingInFlightExecutors?: number;
+	};
+}
+
+export interface SpawnPolicyDecision {
+	allowed: boolean;
+	/** Machine-readable deny reason (undefined when allowed). */
+	reason?: SpawnPolicyDenyReason;
+	/** Fail-fast human message (undefined when allowed). */
+	message?: string;
+	/** The grandchild's depth (parent depth + 1) on success. */
+	childDepth?: number;
+	/** Effective timeout in seconds (requested or default 900) on success. */
+	timeoutSec?: number;
+	/** Effective model (normalized) on success. */
+	model?: string;
+}
+
+export function isExecutorClassRole(role: string): boolean {
+	return (EXECUTOR_CLASS_ROLES as readonly string[]).includes(role);
+}
+
+function deny(reason: SpawnPolicyDenyReason, message: string): SpawnPolicyDecision {
+	return { allowed: false, reason, message };
+}
+
+export function evaluateDelegateAdmission(input: DelegateAdmissionInput): SpawnPolicyDecision {
+	const { nestingEnabled, maxDepth, parentTask, requested } = input;
+	const parentDepth = parentTask.depth ?? 1; // pre-v2 records: workers are depth 1
+	const childDepth = parentDepth + 1;
+
+	// 1. Flag gate — fail-closed default (ADR-5 §10).
+	if (!nestingEnabled) {
+		return deny(
+			"nesting-disabled",
+			"delegate rejected: governed nesting is disabled (nesting.enabled=false, the fail-closed default; enable it in USER config)",
+		);
+	}
+
+	// 2. Role gate — parent must be executor-class; requested role must be in
+	// the tool's allowed set.
+	if (!isExecutorClassRole(parentTask.role)) {
+		return deny(
+			"role-denied",
+			`delegate rejected: role '${parentTask.role}' is not executor-class (${EXECUTOR_CLASS_ROLES.join("/")}) — read-only roles cannot delegate`,
+		);
+	}
+	const requestedRole = requested?.role;
+	if (requestedRole !== undefined && !(DELEGATE_ALLOWED_ROLES as readonly string[]).includes(requestedRole)) {
+		return deny(
+			"role-denied",
+			`delegate rejected: requested grandchild role '${requestedRole}' is not one of ${DELEGATE_ALLOWED_ROLES.join("/")}`,
+		);
+	}
+
+	// 3. Trust gate — untrusted escalation context never spawns.
+	if (input.untrusted) {
+		return deny("trust-denied", "delegate rejected: untrusted escalation context (trust gate is manual-only)");
+	}
+
+	// 4. Depth gate — computed from the parent RECORD (never worker env).
+	if (childDepth > maxDepth) {
+		return deny(
+			"depth-exceeded",
+			`delegate rejected: spawn depth ${childDepth} exceeds maxDepth ${maxDepth} (parent task '${parentTask.taskId}' is at depth ${parentDepth})`,
+		);
+	}
+
+	// 5. Nested-slot budget — fail-fast, never queue.
+	if (input.slots.used >= input.slots.max) {
+		return deny(
+			"slots-exhausted",
+			`delegate rejected: nested spawn budget exhausted; ${input.slots.used}/${input.slots.max} in flight`,
+		);
+	}
+
+	// 6. Parent allocation sufficiency — reserve up-front or reject.
+	if (requested?.budgetTokens !== undefined) {
+		const granted = parentTask.allocation?.tokensGranted ?? 0;
+		const spent = parentTask.allocation?.tokensSpent ?? 0;
+		const remaining = granted - spent;
+		if (requested.budgetTokens > remaining) {
+			return deny(
+				"budget-insufficient",
+				`delegate rejected: requested budget ${requested.budgetTokens} tokens exceeds parent task '${parentTask.taskId}' remaining allocation ${remaining} (${granted} granted - ${spent} spent)`,
+			);
+		}
+	}
+
+	// 7. Model validation against the resolved catalog.
+	const normalizedModel = requested?.model !== undefined ? modelRefToString(requested.model) : undefined;
+	if (normalizedModel !== undefined && input.modelCatalog !== undefined) {
+		if (!input.modelCatalog.includes(normalizedModel)) {
+			return deny("model-invalid", `delegate rejected: model '${requested?.model}' is not in the resolved model catalog`);
+		}
+	}
+
+	// 8. Timeout validation (mandatory default 900).
+	const timeoutSec = requested?.timeoutSec ?? DEFAULT_DELEGATE_TIMEOUT_SEC;
+	if (!Number.isFinite(timeoutSec) || timeoutSec < 1 || timeoutSec > MAX_DELEGATE_TIMEOUT_SEC) {
+		return deny(
+			"timeout-invalid",
+			`delegate rejected: timeoutSec ${String(requested?.timeoutSec)} is outside 1..${MAX_DELEGATE_TIMEOUT_SEC} (default ${DEFAULT_DELEGATE_TIMEOUT_SEC})`,
+		);
+	}
+
+	// 9. Workspace interaction (ADR-5 §9): a write-capable grandchild sharing
+	// the parent's cwd with ANOTHER in-flight executor is only admitted when
+	// serialization is established (limits.serializeOnPathOverlap) — otherwise
+	// reject; read-only grandchild roles (explorer/analyst) never conflict.
+	const requestedIsWriteCapable = requestedRole !== undefined && (EXECUTOR_CLASS_ROLES as readonly string[]).includes(requestedRole);
+	if (requestedIsWriteCapable && !input.workspace?.serializeEnabled && (input.workspace?.overlappingInFlightExecutors ?? 0) > 0) {
+		return deny(
+			"workspace-conflict",
+			`delegate rejected: parent task '${parentTask.taskId}' cwd overlaps ${input.workspace?.overlappingInFlightExecutors} in-flight executor(s) and limits.serializeOnPathOverlap is off — use a read-only grandchild role (explorer/analyst) or enable serialization`,
+		);
+	}
+
+	return { allowed: true, childDepth, timeoutSec, ...(normalizedModel !== undefined ? { model: normalizedModel } : {}) };
+}