pi-crew 0.9.67 → 0.10.1

package/src/extension/registration/lifecycle-handlers.ts

@@ -19,13 +19,15 @@ import * as path from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { loadConfig } from "../../config/config.ts";
 import { DEFAULT_UI } from "../../config/defaults.ts";
+import { getCrewEnv } from "../../config/env-vars.ts";
 import { pruneFinishedRuns, pruneUserLevelRuns } from "../../extension/run-maintenance.ts";
 import { type BrokerSpawnCredentials, setActiveBrokerIssuer } from "../../runtime/broker/broker-issuer.ts";
 import { CrewBroker } from "../../runtime/broker/crew-broker.ts";
 import { terminateActiveChildPiProcesses } from "../../runtime/child-pi/child-pi.ts";
 import { listLiveAgents } from "../../runtime/live-session/live-agent-manager.ts";
 import type { createManifestCache } from "../../runtime/manifest-cache.ts";
-import { cleanupLegacyOrphanTempDirs, cleanupOrphanTempDirs, currentCrewDepth } from "../../runtime/model/pi-args.ts";
+import { configuredModelInfosFromPiConfig } from "../../runtime/model/model-fallback.ts";
+import { cleanupLegacyOrphanTempDirs, cleanupOrphanTempDirs, currentCrewDepth, resolveCrewMaxDepth } from "../../runtime/model/pi-args.ts";
 import { clearProviderQuotaCache, noteProviderResponse } from "../../runtime/model/provider-quota.ts";
 import { noteSessionModel, noteSessionThinking, resolveProviderForResponse } from "../../runtime/model/session-model.ts";
 import { cleanupOrphanWorkers } from "../../runtime/orphan-worker-registry.ts";
@@ -33,7 +35,7 @@ import { reconcileAllStaleRuns } from "../../runtime/recovery/crash-recovery.ts"
 import { CrewScheduler, type ScheduledJob } from "../../runtime/scheduling/scheduler.ts";
 import { tryRegisterSessionCleanup } from "../../runtime/session-resources.ts";
 import { createSessionSnapshot } from "../../runtime/session-snapshot.ts";
-import { applyCrewSettingsToConfig, loadCrewSettings } from "../../runtime/settings-store.ts";
+import { applyCrewSettingsTiersToConfig, loadCrewSettingsTiers } from "../../runtime/settings-store.ts";
 import { loadRunManifestById } from "../../state/stores/state-store.ts";
 import type { TeamRunManifest } from "../../state/types.ts";
 import { summarizeHeartbeats } from "../../ui/heartbeat-aggregator.ts";
@@ -215,8 +217,18 @@ function installSessionStartHandler(pi: ExtensionAPI, ctx: RegistrationContext):
 		}, 0);
 
 		const loadedConfig = loadConfig(extensionCtx.cwd);
-		const crewSettings = loadCrewSettings(extensionCtx.cwd);
-		applyCrewSettingsToConfig(loadedConfig.config, crewSettings);
+		// Wave 2B (P1 security): crew settings load as TIERS — the project-tier
+		// <cwd>/.pi/crew-settings.json is untrusted (a cloned repo can ship it)
+		// and now goes through sanitizeProjectConfig + tighten-only guard
+		// tiering instead of being applied raw over the sanitized config (the
+		// pre-2B `loadCrewSettings` + `applyCrewSettingsToConfig` bypass).
+		// See src/runtime/settings-store.ts for the tier pipeline + the
+		// scheduledJobs/schedulingEnabled boundary decision.
+		const crewSettingsTiers = loadCrewSettingsTiers(extensionCtx.cwd);
+		const settingsWarnings = applyCrewSettingsTiersToConfig(loadedConfig.config, crewSettingsTiers);
+		if (settingsWarnings.length > 0) {
+			(loadedConfig.warnings ??= []).push(...settingsWarnings);
+		}
 
 		// Start scheduler with event-based executor
 		const sessionId =
@@ -229,14 +241,20 @@ function installSessionStartHandler(pi: ExtensionAPI, ctx: RegistrationContext):
 		// Wire scheduler into handle-schedule.ts so handlers can add/list jobs.
 		// EXT-9: module-scoped setter (was globalThis[Symbol.for(...)]).
 		registerCrewScheduler(ctx.crewScheduler);
-		// Load scheduled jobs from settings if present
-		if (Array.isArray(crewSettings.scheduledJobs)) {
-			for (const job of crewSettings.scheduledJobs) {
-				try {
-					ctx.crewScheduler.add(job as ScheduledJob);
-				} catch {
-					/* skip invalid */
-				}
+		// Load scheduled jobs from settings if present.
+		// BOUNDARY (Wave B2): project-tier scheduledJobs are OPT-IN GATED — the
+		// registration loop reads the gated `effectiveScheduledJobs` view (user
+		// jobs always; project jobs ONLY when the user-tier global file has BOTH
+		// schedulingEnabled:true AND allowProjectScheduledJobs:true).
+		// <cwd>/.pi/crew-settings.json remains the persistence store for the
+		// user's own `crew schedule add/update/remove` commands (handle-schedule.ts),
+		// so crew-schedule users must set both flags in ~/.pi/crew-settings.json.
+		// `schedulingEnabled` is user-tier-only (project values always dropped).
+		for (const job of crewSettingsTiers.effectiveScheduledJobs) {
+			try {
+				ctx.crewScheduler.add(job as ScheduledJob);
+			} catch {
+				/* skip invalid */
 			}
 		}
 		ctx.autoRecoveryLast.clear();
@@ -540,6 +558,44 @@ export function filterManifestsForHealthNotifications(
 	return manifests.filter((run) => !run.ownerSessionId || run.ownerSessionId === currentSessionId);
 }
 
+/**
+ * bug-026 sub-issue C: runEventBus event types that mark a run TERMINAL,
+ * across BOTH type namespaces seen on the bus — dotted `run.*` strings (kept
+ * for parity with classifyEventChannel's WORKER_LIFECYCLE_TYPES, see
+ * src/ui/run-event-bus.ts:31-44) and underscore `run_*` (the native
+ * RunEventType namespace actually emitted by team-runner, e.g.
+ * `run_completed`). Exported for unit testing.
+ */
+export const TERMINAL_RUN_EVENT_TYPES: ReadonlySet<string> = new Set([
+	"run.completed",
+	"run.failed",
+	"run.cancelled",
+	"run_completed",
+	"run_failed",
+	"run_cancelled",
+]);
+
+/** True when a runEventBus event type marks the run terminal (either namespace). */
+export function isTerminalRunEventType(type: string): boolean {
+	return TERMINAL_RUN_EVENT_TYPES.has(type);
+}
+
+/** Pure filter: drop `runId` from a preloaded-manifest frame (bug-026 sub-issue C eviction). */
+export function evictRunFromManifests(manifests: TeamRunManifest[], runId: string): TeamRunManifest[] {
+	return manifests.filter((m) => m.runId !== runId);
+}
+
+/**
+ * Apply a runEventBus payload to a preloaded-manifest frame: evict the run on
+ * terminal events, pass through unchanged otherwise. This is the exact logic
+ * wired into the setupRenderLoop `runEventBus.onAny` subscription (bug-026
+ * sub-issue C); exported so tests can exercise it end-to-end against the
+ * real bus without spinning up the full render loop.
+ */
+export function applyTerminalRunEventToManifests(manifests: TeamRunManifest[], event: { type: string; runId: string }): TeamRunManifest[] {
+	return isTerminalRunEventType(event.type) ? evictRunFromManifests(manifests, event.runId) : manifests;
+}
+
 function setupRenderLoop(
 	pi: ExtensionAPI,
 	ctx: RegistrationContext,
@@ -803,6 +859,12 @@ function setupRenderLoop(
 	// re-renders within debounceMs of any agent lifecycle event.
 	const sched = ctx.renderScheduler;
 	const unsubscribeRunEvents = runEventBus.onAny((event) => {
+		// bug-026 sub-issue C: evict terminal runs from the preloaded manifest
+		// frame so a stale "running" entry cannot persist for the session
+		// lifetime. Additive to the renderTick GATE 1 / FIX #1 / GATE 2 snapshot
+		// purges (which invalidate the snapshot cache) — those gates do not
+		// touch lastPreloadedManifests itself.
+		lastPreloadedManifests = applyTerminalRunEventToManifests(lastPreloadedManifests, event);
 		sched.schedule({
 			runId: event.runId,
 			source: "runEventBus",
@@ -905,7 +967,7 @@ export function installCrewBrokerLifecycleController(_pi: ExtensionAPI, _ctx: Re
 
 	function effectiveEnabled(): boolean {
 		// Env wins over config. PI_CREW_BROKER=1 forces on, =0 forces off.
-		const envOverride = process.env.PI_CREW_BROKER;
+		const envOverride = getCrewEnv("PI_CREW_BROKER");
 		if (envOverride === "0") return false;
 		// Config block: read fresh so a runtime config update takes effect.
 		try {
@@ -934,7 +996,23 @@ export function installCrewBrokerLifecycleController(_pi: ExtensionAPI, _ctx: Re
 			starting = (async () => {
 				const cfg = (() => {
 					try {
-						return loadConfig().config.broker;
+						// B1 battery 2026-08-18 (third config-layer bug): loadConfig()
+						// WITHOUT cwd reads only the user config — the workspace
+						// .crew/config.json (where broker.waitMethodsEnabled:true would
+						// live) was never merged, so the flag stayed default-false even
+						// after the parser + merge fixes. Pass the SAME cwd the broker
+						// itself uses below.
+						return loadConfig(process.cwd()).config.broker;
+					} catch {
+						return undefined;
+					}
+				})();
+				// T3/R5 (ADR-5 §10): governed-nesting + limits config for the delegate
+				// surface — same cwd discipline as the broker block above.
+				const nestingCfg = (() => {
+					try {
+						const c = loadConfig(process.cwd()).config;
+						return { nesting: c.nesting, limits: c.limits };
 					} catch {
 						return undefined;
 					}
@@ -944,6 +1022,32 @@ export function installCrewBrokerLifecycleController(_pi: ExtensionAPI, _ctx: Re
 					socketPath: getBrokerSocketPath(sessionId),
 					maxFrameBytes: cfg?.maxFrameBytes ?? 262144,
 					outboundQueueCap: cfg?.outboundQueueCap ?? 256,
+					// WP-2 review round 1 (P1): thread the capability gate into the
+					// PRODUCTION broker — the constructor default (false) made
+					// config.broker.waitMethodsEnabled a dead knob and the ADR-0
+					// "then true" flip a silent no-op. Fail-closed when unset.
+					waitMethodsEnabled: cfg?.waitMethodsEnabled ?? false,
+					// T3/R5 (ADR-5 §10): governed-nesting capability gate — fail-closed
+					// default; production threads config.nesting (sensitive: user config
+					// only). Nested-slot sizing + admission-time model catalog (ADR-5 §7 —
+					// the production wiring MUST supply it) + workspace gate mirror.
+					nestingEnabled: nestingCfg?.nesting?.enabled ?? false,
+					...(nestingCfg?.nesting?.maxSlots !== undefined ? { nestingMaxSlots: nestingCfg.nesting.maxSlots } : {}),
+					...(nestingCfg?.nesting?.maxDepth !== undefined ? { nestingMaxDepth: nestingCfg.nesting.maxDepth } : {}),
+					// ADR-5 §12: enabling the sensitive USER-config-only flag IS the manual
+					// trust decision for the escalation surface.
+					nestingTrustedEscalation: nestingCfg?.nesting?.enabled === true,
+					...(nestingCfg?.limits?.maxConcurrentWorkers !== undefined
+						? { globalWorkerSemaphore: nestingCfg.limits.maxConcurrentWorkers }
+						: {}),
+					serializeOnPathOverlap: nestingCfg?.limits?.serializeOnPathOverlap ?? false,
+					modelCatalog: () => {
+						try {
+							return configuredModelInfosFromPiConfig(process.cwd()).map((info) => info.fullId);
+						} catch {
+							return undefined;
+						}
+					},
 					enabled: true,
 					cwd: process.cwd(),
 				});
@@ -960,10 +1064,17 @@ export function installCrewBrokerLifecycleController(_pi: ExtensionAPI, _ctx: Re
 		return starting!;
 	}
 
-	const issueForChild = async (runId: string, taskId?: string): Promise<BrokerSpawnCredentials | undefined> => {
+	const issueForChild = async (runId: string, taskId?: string, childDepth?: number): Promise<BrokerSpawnCredentials | undefined> => {
 		if (!runId || typeof runId !== "string") return undefined;
 		if (!isRootSession(process.env)) return undefined;
 		if (!effectiveEnabled()) return undefined;
+		// ADR-5 §4 (governed nesting): tokens are minted ONLY for children that
+		// may themselves delegate — childDepth < resolved maxDepth. At the default
+		// maxDepth=2 a delegate-spawned depth-2 grandchild gets NO credentials
+		// (env containment: no PI_CREW_BROKER_SOCKET/TOKEN at depth 2; identity
+		// routing via PI_CREW_BROKER_RUN_ID/TASK_ID is threaded unconditionally
+		// elsewhere). Undefined childDepth = legacy worker spawn (depth 1).
+		if (childDepth !== undefined && childDepth >= resolveCrewMaxDepth(undefined)) return undefined;
 		const sessionId = cachedSessionId;
 		if (!sessionId) return undefined;
 		try {

package/src/extension/registration/subagent-tools.ts

@@ -1,3 +1,4 @@
+import * as fs from "node:fs";
 import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
@@ -28,14 +29,18 @@ import type { BatchBarrier } from "../../runtime/scheduling/batch-barrier.ts";
 import {
 	readPersistedSubagentRecord,
 	type SubagentManager,
+	type SubagentRecord,
 	type SubagentSpawnOptions,
 	savePersistedSubagentRecord,
 } from "../../runtime/subagent-manager.ts";
+import { TEAM_TERMINAL_TASK_STATUSES } from "../../state/contracts.ts";
+import { resolveEntryBySubagentId, upsertOwnershipEntry } from "../../state/stores/ownership-map.ts";
 import { loadRunManifestById } from "../../state/stores/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
 import { formatCompactToolProgress } from "../../ui/tool-progress-formatter.ts";
 import { agentToolRenderer, type ToolRenderContext } from "../../ui/tool-renderers/index.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
+import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
 import {
 	__test__subagentSpawnParams,
 	formatSubagentRecord,
@@ -140,8 +145,55 @@ export function registerSubagentTools(
 			// by the Agent tool have proper session ownership for isolation.
 			const ctxWithSession = withSessionId(ctx);
 			spawnOptions.ownerSessionId = ctxWithSession.sessionId;
-			const runner = async (currentOptions: SubagentSpawnOptions, childSignal?: AbortSignal) =>
-				handleTeamTool(
+			// WP-1/R1 (H6): the one-shot identity link. taskId is NOT knowable at
+			// spawn() time — handleTeamTool(action:"run") resolves only after the
+			// run is dispatched (scaffold/mock returns immediately; real runs at
+			// completion), and runId comes from the result details. So the link is
+			// written in the runner wrapper once the manifest resolves: the record
+			// gains taskId/depth, the persisted copy is refreshed, and the
+			// ownership-map entry (task ⇄ subagentId ⇄ artifactsDir) is upserted
+			// under the run lock. Best-effort: a failure logs but never throws
+			// into the spawn path. `spawnedRecord` is assigned right after spawn()
+			// returns; the runner's continuation runs on a later microtask, so the
+			// assignment is always visible when the identity-link block executes.
+			let spawnedRecord: SubagentRecord | undefined;
+			const runner = async (currentOptions: SubagentSpawnOptions, childSignal?: AbortSignal) => {
+				// WP-1/R1 (H6 fix, review round): mid-run steer requires the identity
+				// link AT DISPATCH TIME, not after completion. `handleTeamTool` awaits
+				// the full run; the only mid-run signal we have is `onRunStarted`
+				// (fired in run.ts with updatedManifest.runId as the run starts). Hook
+				// it so the subagentId leg of the ownership map lands while the worker
+				// is live — steer_subagent can then resolve taskId mid-run instead of
+				// saying "not linked". The completion-time block below remains as a
+				// fallback for runs that complete between dispatch and this hook.
+				const linkAtDispatch = (runId?: string): void => {
+					if (typeof runId !== "string" || !spawnedRecord || spawnedRecord.taskId) return;
+					try {
+						const loaded = loadRunManifestById(currentOptions.cwd, runId);
+						const taskId = loaded?.tasks[0]?.id;
+						if (taskId && loaded) {
+							spawnedRecord.taskId = taskId;
+							// runId too: the manager only back-fills record.runId from the
+							// awaited result (waitForRun — i.e. at COMPLETION for background
+							// runs). Linking it here keeps taskId+runId landing together at
+							// dispatch so mid-run consumers (steer) resolve both immediately.
+							spawnedRecord.runId = runId;
+							spawnedRecord.depth = currentOptions.depth ?? 0;
+							savePersistedSubagentRecord(currentOptions.cwd, spawnedRecord);
+							upsertOwnershipEntry(loaded.manifest, {
+								taskId,
+								runId,
+								subagentId: spawnedRecord.id,
+								artifactsDir: loaded.manifest.artifactsRoot,
+								depth: spawnedRecord.depth,
+								updatedAt: new Date().toISOString(),
+							});
+						}
+					} catch (err) {
+						logInternalError("subagent-tools.identity-dispatch", err, `runId=${runId ?? "(unknown)"}`);
+					}
+				};
+				const result = await handleTeamTool(
 					{
 						action: "run",
 						agent: currentOptions.type,
@@ -153,6 +205,7 @@ export function registerSubagentTools(
 					} as TeamToolParamsValue,
 					{
 						...ctxWithSession,
+						onRunStarted: (runId: string) => linkAtDispatch(runId), // mid-run capture (FIX)
 						signal: childSignal,
 						...(options.startForegroundRun
 							? {
@@ -162,7 +215,64 @@ export function registerSubagentTools(
 							: {}),
 					},
 				);
+				// WP-1/R1 (H6): identity link — record taskId/depth + ownership entry
+				// once the run manifest resolves. Direct-agent one-shot runs have
+				// exactly one task (direct-agent workflow); resolve from the manifest
+				// rather than hardcoding the id. The ownership upsert is verified and
+				// retried: a concurrently-completing run holds the run lock during its
+				// terminal writes, so a single upsert can lose the lock race
+				// (acquireLockWithRetry throws on a fresh foreign lock) and the
+				// store swallows that best-effort. taskId is already on the record at
+				// that point, so steer still resolves — but the map's subagentId leg
+				// would be missing for widget/status attribution. Ride out the
+				// contention window, then verify; still never throw.
+				let runId: string | undefined;
+				try {
+					const detailsRunId = (result.details as { runId?: unknown } | undefined)?.runId;
+					runId = typeof detailsRunId === "string" ? detailsRunId : undefined;
+					if (typeof runId === "string" && spawnedRecord) {
+						const loaded = loadRunManifestById(currentOptions.cwd, runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
+						const taskId = loaded?.tasks[0]?.id;
+						// P3 hardening (T1 review round 1): base the completion-time retry on
+						// the MAP LEG, not on record.taskId. A dispatch-time upsert
+						// (linkAtDispatch) that lost the lock race would leave the map's
+						// subagentId leg missing; the old `!spawnedRecord.taskId` guard then
+						// skipped the verify+retry entirely. Now: write record fields once
+						// (idempotent), then verify+retry the MAP until the subagentId leg
+						// is present or budget exhausted. Upsert is merge-idempotent, so
+						// double-writing is safe.
+						if (taskId && loaded) {
+							if (!spawnedRecord.taskId) {
+								spawnedRecord.taskId = taskId;
+								spawnedRecord.depth = currentOptions.depth ?? 0;
+								savePersistedSubagentRecord(currentOptions.cwd, spawnedRecord);
+							}
+							const entry = {
+								taskId,
+								runId,
+								subagentId: spawnedRecord.id,
+								artifactsDir: loaded.manifest.artifactsRoot,
+								depth: spawnedRecord.depth,
+								updatedAt: new Date().toISOString(),
+							};
+							for (let attempt = 0; attempt < 5; attempt++) {
+								try {
+									upsertOwnershipEntry(loaded.manifest, entry);
+								} catch (err) {
+									logInternalError("subagent-tools.identity-link", err, `taskId=${taskId}, attempt=${attempt}`);
+								}
+								if (resolveEntryBySubagentId(loaded.manifest, spawnedRecord.id)?.taskId === taskId) break;
+								if (attempt < 4) await new Promise((resolve) => setTimeout(resolve, 50 * (attempt + 1)));
+							}
+						}
+					}
+				} catch (err) {
+					logInternalError("subagent-tools.identity-link", err, `runId=${runId ?? "(unknown)"}`);
+				}
+				return result;
+			};
 			const record = subagentManager.spawn(spawnOptions, runner, spawnOptions.background ? undefined : signal);
+			spawnedRecord = record;
 			// Rule 1: register batch membership so completions can be coalesced.
 			if (spawnOptions.batchId && spawnOptions.background) {
 				options.batchBarrier?.register(spawnOptions.batchId, record.id, { description: record.description, type: record.type });
@@ -365,28 +475,127 @@ export function registerSubagentTools(
 		name: "steer_subagent",
 		label: "Steer Agent",
 		description:
-			"Send a steering note to a running pi-crew subagent. Live-session steering is planned; child-process runs expose durable status and can be cancelled if needed.",
+			"Send a steering note to a running pi-crew subagent. Resolves the subagent record → ownership map → appends artifacts/steering/<taskId>.jsonl, which the child worker polls at its next turn boundary. Use team action=steer (runId+taskId+message) for run-level steering, or team cancel for interruption.",
 		parameters: Type.Object({
 			agent_id: Type.String(),
 			message: Type.String(),
 		}) as never,
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			const p = params as { agent_id?: string; message?: string };
+			if (!p.message?.trim()) return subagentToolResult(t("agent.requiresPrompt"), {}, true);
 			const record = p.agent_id
 				? (subagentManager.getRecord(p.agent_id) ?? readPersistedSubagentRecord(ctx.cwd, p.agent_id))
 				: undefined;
 			if (!record) return subagentToolResult(t("result.notFound", { id: p.agent_id ?? "" }), {}, true);
+			// P2.3: Cross-session ownership check — refuse to steer a record owned by
+			// a different session. Legacy records (no ownerSessionId) still pass.
+			const currentSessionId = withSessionId(ctx).sessionId;
+			if (record.ownerSessionId && record.ownerSessionId !== currentSessionId) {
+				return subagentToolResult("Agent belongs to another session.", {}, true);
+			}
+			// Resolve the live run's taskId + artifactsRoot: prefer the record's
+			// taskId link (set by the Agent-tool spawn route), falling back to the
+			// per-run ownership map (resolve by subagentId) when the record predates
+			// the link.
+			let taskId = record.taskId;
+			let artifactsRoot: string | undefined;
+			let loaded: ReturnType<typeof loadRunManifestById> | undefined;
+			if (record.runId) {
+				loaded = loadRunManifestById(ctx.cwd, record.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
+				if (loaded) {
+					artifactsRoot = loaded.manifest.artifactsRoot;
+					taskId ??= resolveEntryBySubagentId(loaded.manifest, record.id)?.taskId;
+				}
+			}
+			// Back-compat: no taskId/link (legacy record or run never dispatched) →
+			// the existing "not linked" structured message, NO throw, NO file write.
+			if (!taskId || !artifactsRoot) {
+				return subagentToolResult(
+					[t("steer.unavailable"), record.runId ? t("steer.cancelHint", { runId: record.runId }) : undefined]
+						.filter((line): line is string => Boolean(line))
+						.join("\n"),
+					{
+						agentId: record.id,
+						runId: record.runId,
+						status: record.status,
+					},
+				);
+			}
+			// Real steer — append to artifacts/steering/<taskId>.jsonl, same writer util
+			// + JSONL schema as `team steer` (handleSteer, team-tool.ts):
+			// {type:"steer", message, ts}. The child worker polls this file every
+			// 500ms and picks the message up at its next turn boundary.
+			// Security review (T1/WP-1 round 1, security 1-3): mirror handleSteer's
+			// hardening — (a) T-S1 terminal-task refusal + taskId-belongs-to-manifest
+			// validation; (b) cap steering-file growth (unbounded files force a
+			// Buffer.alloc(fileSize) on the next worker's first poll and re-deliver
+			// every line to each incarnation — see P2 replay finding); (c) no throw.
+			if (!loaded) return subagentToolResult("Run manifest unavailable for steer.", {}, true);
+			const manifestTask = loaded.tasks.find((t) => t.id === taskId);
+			if (!manifestTask) {
+				return subagentToolResult(
+					`Task '${taskId}' not found in the owning run; cannot steer.`,
+					{ agentId: record.id, runId: record.runId, taskId, status: record.status },
+					true,
+				);
+			}
+			if (TEAM_TERMINAL_TASK_STATUSES.has(manifestTask.status)) {
+				return subagentToolResult(
+					`Task '${taskId}' is ${manifestTask.status}; cannot steer.`,
+					{ agentId: record.id, runId: record.runId, taskId, status: record.status },
+					true,
+				);
+			}
+			try {
+				const steeringDir = `${artifactsRoot}/steering`;
+				fs.mkdirSync(steeringDir, { recursive: true });
+				const safeSteeringPath = resolveRealContainedPath(steeringDir, `${taskId}.jsonl`);
+				// Security 3: cap file growth — refuse when the file exceeds a byte
+				// threshold (drop-oldest semantics are not feasible for a plain JSONL
+				// append; refuse loudly instead of poisoning the next incarnation).
+				const MAX_STEERING_BYTES = 256 * 1024;
+				let existingBytes = 0;
+				try {
+					existingBytes = fs.statSync(safeSteeringPath).size;
+				} catch (error) {
+					if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+				}
+				const line = JSON.stringify({ type: "steer", message: p.message, ts: new Date().toISOString() }) + "\n";
+				if (existingBytes + Buffer.byteLength(line) > MAX_STEERING_BYTES) {
+					return subagentToolResult(
+						`Steering file for task '${taskId}' has reached its size cap (${(MAX_STEERING_BYTES / 1024).toFixed(0)}KiB); steer refused.`,
+						{ agentId: record.id, runId: record.runId, taskId, status: record.status },
+						true,
+					);
+				}
+				fs.appendFileSync(safeSteeringPath, line);
+			} catch (err) {
+				// B1 battery 2026-08-18 (F7): this catch previously logged at DEBUG
+				// level (invisible unless PI_TEAMS_DEBUG) and then STILL returned the
+				// success message — a live probe showed "Steer delivered to task …"
+				// while the steering file stayed 0 bytes, undiagnosable from the
+				// outside. Fail LOUD: error-level log + isError result.
+				logInternalError(
+					"subagent-tools.steer-write-failed",
+					err instanceof Error ? err : new Error(String(err)),
+					`taskId=${taskId} runId=${record.runId} artifactsRoot=${artifactsRoot}`,
+					"error",
+				);
+				return subagentToolResult(
+					`Steer write failed for task '${taskId}': ${err instanceof Error ? err.message : String(err)} (see pi-crew error log)`,
+					{ agentId: record.id, runId: record.runId, taskId, status: record.status },
+					true,
+				);
+			}
 			return subagentToolResult(
 				[
 					t("steer.noted", { id: record.id }),
-					t("steer.unavailable"),
-					record.runId ? t("steer.cancelHint", { runId: record.runId }) : undefined,
-				]
-					.filter((line): line is string => Boolean(line))
-					.join("\n"),
+					`Steer delivered to task '${taskId}'; it will be picked up at the next turn boundary.`,
+				].join("\n"),
 				{
 					agentId: record.id,
 					runId: record.runId,
+					taskId,
 					status: record.status,
 				},
 			);
@@ -410,7 +619,7 @@ export function registerSubagentTools(
 		...steerSubagentTool,
 		name: "crew_agent_steer",
 		label: "Steer Crew Agent",
-		description: "Send a steering note to a pi-crew subagent using the conflict-safe tool name.",
+		description: "Send a steering note to a pi-crew subagent using the conflict-safe tool name (same behavior as steer_subagent).",
 	};
 	const toolConfig = loadConfig(process.cwd()).config.tools;
 	const enableSteer = toolConfig?.enableSteer !== false;

package/src/extension/rpc-hmac.ts

@@ -1,4 +1,5 @@
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { getCrewEnv } from "../config/env-vars.ts";
 
 /**
  * HMAC-based origin signing for cross-extension RPC.
@@ -23,7 +24,7 @@ const SIGNATURE_VALIDITY_MS = 10 * 60 * 1000; // 10 min
 
 /** Get the shared secret. Returns undefined if not configured. */
 export function getRpcSecret(): string | undefined {
-	return process.env[SECRET_ENV_VAR];
+	return getCrewEnv(SECRET_ENV_VAR);
 }
 
 /** Set the shared secret (for testing or programmatic setup). */
@@ -38,7 +39,8 @@ export function clearRpcSecret(): void {
 
 /** Whether HMAC authentication is currently enabled. */
 export function isHmacEnabled(): boolean {
-	return typeof process.env[SECRET_ENV_VAR] === "string" && process.env[SECRET_ENV_VAR].length > 0;
+	const secret = getCrewEnv(SECRET_ENV_VAR);
+	return typeof secret === "string" && secret.length > 0;
 }
 
 // --- Types -------------------------------------------------------------------
@@ -142,7 +144,7 @@ export function withHmacVerification<P extends { requestId: string }>(
 			// Emit a soft info note (once per process) only when an actual RPC
 			// request is being processed — the prior registration-time warning
 			// was too noisy for users who never wire cross-extension RPC.
-			if (process.env.PI_CREW_SUPPRESS_RPC_WARNING !== "1") {
+			if (getCrewEnv("PI_CREW_SUPPRESS_RPC_WARNING") !== "1") {
 				rpcHmacSoftInfoOnce();
 			}
 			return handler(params);

package/src/extension/team-tool/api/heartbeat.ts

@@ -6,9 +6,11 @@
  */
 
 import { touchWorkerHeartbeat } from "../../../runtime/heartbeat/worker-heartbeat.ts";
+import { isTerminalTaskStatus } from "../../../state/contracts.ts";
 import { withRunLockSync } from "../../../state/coordination/locks.ts";
 import { appendEvent } from "../../../state/event-log/event-log.ts";
-import { saveRunTasks } from "../../../state/stores/state-store.ts";
+import { loadRunManifestById, saveRunTasks } from "../../../state/stores/state-store.ts";
+import { RUN_NOT_FOUND_HINT } from "../run-not-found.ts";
 import type { ApiOperationHandler } from "./handler-context.ts";
 
 export const handleWriteHeartbeat: ApiOperationHandler = (hctx) => {
@@ -31,28 +33,63 @@ export const handleWriteHeartbeat: ApiOperationHandler = (hctx) => {
 		);
 	try {
 		return withRunLockSync(loaded.manifest, () => {
+			// R13-S1: fresh re-read INSIDE the lock (respond.ts:43 canonical pattern).
+			const fresh = loadRunManifestById(loaded.manifest.cwd, loaded.manifest.runId);
+			if (!fresh)
+				return result(
+					`Run '${loaded.manifest.runId}' not found.${RUN_NOT_FOUND_HINT}`,
+					{
+						action: "api",
+						status: "error",
+						runId: loaded.manifest.runId,
+					},
+					true,
+				);
+			const freshTask = fresh.tasks.find((item) => item.id === taskId || item.stepId === taskId);
+			if (!freshTask)
+				return result(
+					`Task '${taskId}' not found in run '${fresh.manifest.runId}'.`,
+					{
+						action: "api",
+						status: "error",
+						runId: fresh.manifest.runId,
+					},
+					true,
+				);
+			// R13-S1: never resurrect a task that became terminal on disk — a completed/
+			// failed task must not be flipped back to running by a stale heartbeat.
+			if (isTerminalTaskStatus(freshTask.status))
+				return result(
+					`Cannot write heartbeat for task '${freshTask.id}': task is in terminal state '${freshTask.status}'.`,
+					{
+						action: "api",
+						status: "error",
+						runId: fresh.manifest.runId,
+					},
+					true,
+				);
 			const heartbeat = touchWorkerHeartbeat(
-				task.heartbeat ?? {
-					workerId: task.id,
+				freshTask.heartbeat ?? {
+					workerId: freshTask.id,
 					lastSeenAt: new Date().toISOString(),
 				},
 				{
 					alive: typeof cfg.alive === "boolean" ? cfg.alive : undefined,
 				},
 			);
-			const tasks = loaded.tasks.map((item) => (item.id === task.id ? { ...item, heartbeat } : item));
-			saveRunTasks(loaded.manifest, tasks);
-			appendEvent(loaded.manifest.eventsPath, {
+			const tasks = fresh.tasks.map((item) => (item.id === freshTask.id ? { ...item, heartbeat } : item));
+			saveRunTasks(fresh.manifest, tasks);
+			appendEvent(fresh.manifest.eventsPath, {
 				type: "worker.heartbeat",
-				runId: loaded.manifest.runId,
-				taskId: task.id,
+				runId: fresh.manifest.runId,
+				taskId: freshTask.id,
 				data: { ...heartbeat },
 			});
 			return result(JSON.stringify(heartbeat, null, 2), {
 				action: "api",
 				status: "ok",
-				runId: loaded.manifest.runId,
-				artifactsRoot: loaded.manifest.artifactsRoot,
+				runId: fresh.manifest.runId,
+				artifactsRoot: fresh.manifest.artifactsRoot,
 			});
 		});
 	} catch (error) {

package/src/extension/team-tool/api/plan-approval.ts

@@ -9,6 +9,7 @@ import { terminateLiveAgentsForRun } from "../../../runtime/live-session/live-ag
 import { currentCrewRole, permissionForRole } from "../../../runtime/role-permission.ts";
 import { withRunLock } from "../../../state/coordination/locks.ts";
 import { appendEvent } from "../../../state/event-log/event-log.ts";
+import { getCurrentPlanRecord, setPlanApproval } from "../../../state/stores/plan-store.ts";
 import { loadRunManifestById, saveRunManifestAsync, saveRunTasks, updateRunStatus } from "../../../state/stores/state-store.ts";
 import { logInternalError } from "../../../utils/internal-error.ts";
 import type { ApiOperationHandler } from "./handler-context.ts";
@@ -63,6 +64,10 @@ export const handleApprovePlan: ApiOperationHandler = async (hctx) => {
 				},
 			};
 			await saveRunManifestAsync(manifest);
+			// T2/R4 (ADR-4 §8): dual-write the record side — approval names the
+			// plan id+version. Pre-v2 runs without a PlanRecord skip silently.
+			const currentRecord = getCurrentPlanRecord(manifest);
+			if (currentRecord) setPlanApproval(manifest, { status: "approved", planVersion: currentRecord.version, by: "api" });
 			appendEvent(manifest.eventsPath, {
 				type: "plan.approved",
 				runId: manifest.runId,
@@ -140,6 +145,10 @@ export const handleCancelPlan: ApiOperationHandler = async (hctx) => {
 				},
 			};
 			await saveRunManifestAsync(manifest);
+			// T2/R4 (ADR-4 §8 vocabulary mapping): manifest gets "cancelled", the
+			// record side gets "rejected" (isPlanApprovalDenied accepts both).
+			const denyRecord = getCurrentPlanRecord(manifest);
+			if (denyRecord) setPlanApproval(manifest, { status: "rejected", planVersion: denyRecord.version, by: "api" });
 			saveRunTasks(manifest, tasks);
 			appendEvent(manifest.eventsPath, {
 				type: "plan.cancelled",