pi-crew 0.9.68 → 0.10.2

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 } : {}) };
+}

package/src/runtime/stale-reconciler.ts

@@ -3,8 +3,10 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { errors } from "../errors.ts";
 import { atomicWriteFile, atomicWriteJson } from "../state/atomic-write.ts";
+import { getCurrentPlanRecord } from "../state/stores/plan-store.ts";
 import { loadManifestWithRecovery, loadTasksWithRecovery, saveRunManifest } from "../state/stores/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { logInternalError } from "../utils/internal-error.ts";
 import { recordFromTask, upsertCrewAgent } from "./crew-agent-records.ts";
 import { checkProcessLiveness } from "./process-status.ts";
 
@@ -23,7 +25,7 @@ const ORPHAN_TEMP_SCAN_BATCH_SIZE = 50;
 export interface ReconcileResult {
 	runId: string;
 	/** What was found and what action was taken */
-	verdict: "healthy" | "blocked_awaiting_approval" | "result_exists" | "pid_dead" | "pid_alive_stale" | "no_status";
+	verdict: "healthy" | "blocked_awaiting_approval" | "waiting_answer" | "result_exists" | "pid_dead" | "pid_alive_stale" | "no_status";
 	/** Whether repair was applied */
 	repaired: boolean;
 	/** Human-readable detail */
@@ -45,6 +47,50 @@ export function isPlanApprovalPending(manifest: TeamRunManifest): boolean {
 	return manifest.status === "blocked" && manifest.planApproval?.required === true && manifest.planApproval.status === "pending";
 }
 
+/** T2/R4 (ADR-4 §2 reader migration): plan-record-first variant — the current
+ *  PlanRecord's approval (when present) is authoritative; pre-v2 runs fall
+ *  back to the manifest gate above. The `blocked + pending → protected`
+ *  invariant is preserved on BOTH paths. */
+export function isPlanApprovalPendingEffective(manifest: TeamRunManifest): boolean {
+	if (isPlanApprovalPending(manifest)) return true;
+	if (manifest.status !== "blocked") return false;
+	return getCurrentPlanRecord(manifest)?.approval?.status === "pending";
+}
+
+/** WP-2/R2 (ADR-0 item 9, docs/decisions/2026-08-17-waiting-producer-ask.md):
+ * waiting TTL — a manifest.waitState.askedAt younger than this marks an
+ * intentional ask-wait; older marks a leaked park marker (worker died without
+ * resolving the ask) and the run loses reconciler protection. Leak guard. */
+const WAITING_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Is this run parked in the ask tool awaiting a human answer (WP-2/R2)?
+ *
+ * True when waitState is set and its askedAt is within waitingTtl. The parked
+ * worker is blocked polling the mailbox for a response — not crashed — and it
+ * typically stops heartbeating while parked, so the run must be protected at
+ * run level (before the no-PID/heartbeat staleness phases) exactly like
+ * plan-approval runs. askedAt exactly at the TTL boundary still counts as
+ * pending (<=, fail-safe toward preservation); a future askedAt (clock skew)
+ * also passes. TTL-EXPIRED waitState returns false — the marker leaked and the
+ * normal staleness repair paths apply (leak guard).
+ */
+export function isWaitAnswerPending(manifest: TeamRunManifest, now = Date.now()): boolean {
+	const askedAtMs = manifest.waitState?.askedAt ? new Date(manifest.waitState.askedAt).getTime() : Number.NaN;
+	return Number.isFinite(askedAtMs) && now - askedAtMs <= WAITING_TTL_MS;
+}
+
+/**
+ * Generalized intentional-wait predicate (ADR-0 item 9, extended by ADR-4 §2):
+ * the run is blocked on a human decision — plan approval (record-first with
+ * manifest fallback — pre-v2 semantics preserved on the fallback path) or a
+ * pending ask answer within waitingTtl. Such runs are not crashes and must not
+ * be stale-repaired or cancelled by reconciliation.
+ */
+export function isIntentionalWait(manifest: TeamRunManifest, now = Date.now()): boolean {
+	return isPlanApprovalPendingEffective(manifest) || isWaitAnswerPending(manifest, now);
+}
+
 const STALE_ALIVE_PID_MS = 24 * 60 * 60 * 1000; // 24 hours
 const ACTIVE_EVIDENCE_TTL_MS = 5 * 60 * 1000;
 /** For no-PID runs, repair when ALL running tasks have heartbeat stale beyond this threshold. */
@@ -315,7 +361,9 @@ export function reconcileStaleRun(manifest: TeamRunManifest, tasks: TeamTaskStat
 	// Preserve runs intentionally blocked on human plan approval. These are not
 	// crashes even if the owning PID is gone — they are waiting for a decision.
 	// Must short-circuit before Phase 1 (result check) and Phase 2 (PID liveness).
-	if (isPlanApprovalPending(manifest)) {
+	// ADR-4 §2: record-first predicate — a PlanRecord approval is authoritative,
+	// the manifest field remains the pre-v2 fallback (never dropped).
+	if (isPlanApprovalPendingEffective(manifest)) {
 		return {
 			runId,
 			verdict: "blocked_awaiting_approval",
@@ -324,6 +372,22 @@ export function reconcileStaleRun(manifest: TeamRunManifest, tasks: TeamTaskStat
 		};
 	}
 
+	// WP-2/R2 (ADR-0 item 9): a run parked in the ask tool with a fresh
+	// waitState.askedAt is intentionally waiting on a human answer — not stale.
+	// Short-circuits before Phase 1/2 like plan-approval above: a parked worker
+	// does not heartbeat, so the no-PID/heartbeat staleness phases would
+	// otherwise cancel it long before its (server-clamped <=1h) ask deadline.
+	// TTL-expired waitState (>24h) falls through — the park marker leaked
+	// (worker died without resolving) and normal staleness repair applies.
+	if (isWaitAnswerPending(manifest, now)) {
+		return {
+			runId,
+			verdict: "waiting_answer",
+			repaired: false,
+			detail: "Ask answer pending (manifest.waitState.askedAt within waiting TTL); run is intentionally waiting and must not be stale-repaired",
+		};
+	}
+
 	// Phase 1: Check if results already exist
 	const phase1 = checkResultFile(manifest, tasks);
 	if (phase1.found) {
@@ -538,7 +602,14 @@ export function reconcileOrphanedTempWorkspaces(
 							}
 						}
 						// If still running after reconciliation attempt, mark for dir-preserving
-						if (result.verdict === "healthy" || (result.verdict === "no_status" && !result.repaired)) {
+						if (
+							result.verdict === "healthy" ||
+							// WP-2/R2: a run intentionally waiting on an ask answer keeps the
+							// temp workspace alive (its stateRoot + mailbox must survive for
+							// the parked worker to receive the answer).
+							result.verdict === "waiting_answer" ||
+							(result.verdict === "no_status" && !result.repaired)
+						) {
 							hasRunning = true;
 						}
 					} catch (err) {
@@ -546,14 +617,19 @@ export function reconcileOrphanedTempWorkspaces(
 						// Note: manifestPath here refers to the variable defined in the
 						// for loop at line 442 (outer scope of this catch block).
 						const scanManifestPath = manifestPath;
-						console.warn(`[stale-reconciler] Skipping manifest due to parse error: ${scanManifestPath}: ${err}`);
+						logInternalError(
+							"stale-reconciler",
+							new Error(`Skipping manifest due to parse error: ${scanManifestPath}: ${err}`),
+							undefined,
+							"warn",
+						);
 					}
 				}
 			} catch (err) {
 				// Cannot determine running state — treat as if running to prevent
 				// premature cleanup of a potentially active workspace.
 				hasRunning = true;
-				console.warn(`[stale-reconciler] Skipping unreadable runs dir: ${stateRunsDir}: ${err}`);
+				logInternalError("stale-reconciler", new Error(`Skipping unreadable runs dir: ${stateRunsDir}: ${err}`), undefined, "warn");
 			}
 
 			// Post-loop: check if this workspace dir can be cleaned up.
@@ -617,7 +693,12 @@ export function reconcileOrphanedTempWorkspaces(
 							}
 						}
 					} catch (err) {
-						console.warn(`[stale-reconciler] Skipping unreadable runs dir: ${stateRunsDir}: ${err}`);
+						logInternalError(
+							"stale-reconciler",
+							new Error(`Skipping unreadable runs dir: ${stateRunsDir}: ${err}`),
+							undefined,
+							"warn",
+						);
 					}
 				}
 			}