pi-crew 0.9.68 → 0.10.2

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/registration/team-tool.ts

@@ -13,6 +13,7 @@ import type { createRunSnapshotCache } from "../../ui/run-snapshot-cache.ts";
 import { statusIcon, type ToolRenderContext, teamToolRenderer } from "../../ui/tool-renderers/index.ts";
 import type { CrewWidgetState } from "../../ui/widget/index.ts";
 import { updateCrewWidget } from "../../ui/widget/index.ts";
+import { safeAbort } from "../../utils/safe-abort.ts";
 import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
 // Team tool handler — lazy-loaded because team-tool.ts imports many modules
 import type { handleTeamTool as HandleTeamToolFn } from "../team-tool.ts";
@@ -174,7 +175,10 @@ export function registerTeamTool(pi: ExtensionAPI, deps: RegisterTeamToolDeps):
 			const controller = new AbortController();
 			const toolKey = Symbol();
 			deps.foregroundControllers.set(toolKey, controller);
-			const abort = (): void => controller.abort();
+			// safe-abort: pi's tool-call abort can race a completed run whose
+			// spawned children already exited — Node's child_process signal
+			// listener throws AbortError out of abort() and kills the host.
+			const abort = (): void => safeAbort(controller, "team-tool.caller-abort");
 			signal?.addEventListener("abort", abort, { once: true });
 			const stopProgress = startTeamToolProgressBinder(onUpdate as OnUpdate | undefined);
 			try {

package/src/extension/registration/ui.ts

@@ -15,7 +15,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { loadConfig } from "../../config/config.ts";
 import { DEFAULT_UI } from "../../config/defaults.ts";
 import type { LiveRunSidebar as LiveRunSidebarType } from "../../ui/live-run-sidebar.ts";
-import { requestRender, setExtensionWidget, showCustom } from "../../ui/pi-ui-compat.ts";
+import { requestRender, setExtensionWidget, showCustom, toPiWidgetPlacement } from "../../ui/pi-ui-compat.ts";
 import {
 	clearPiCrewPowerbar,
 	registerPiCrewPowerbarSegments,
@@ -76,10 +76,11 @@ export async function installLiveSidebar(ctx: ExtensionContext, runId: string, s
 	state.liveSidebarRunId = runId;
 	state.dashboardOpened = true;
 	const widgetPlacement = uiConfig?.widgetPlacement ?? DEFAULT_UI.widgetPlacement;
-	setExtensionWidget(ctx, "pi-crew", undefined, { placement: widgetPlacement });
-	setExtensionWidget(ctx, "pi-crew-active", undefined, { placement: widgetPlacement });
+	const placement = toPiWidgetPlacement(widgetPlacement);
+	setExtensionWidget(ctx, "pi-crew", undefined, { placement });
+	setExtensionWidget(ctx, "pi-crew-active", undefined, { placement });
 	deps.widgetState.lastVisibility = "hidden";
-	deps.widgetState.lastPlacement = widgetPlacement;
+	deps.widgetState.lastPlacement = placement;
 	deps.widgetState.lastKey = "pi-crew-active";
 	deps.widgetState.model = undefined;
 	const width = Math.min(90, Math.max(40, uiConfig?.dashboardWidth ?? DEFAULT_UI.dashboardWidth));

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",