pi-crew 0.10.3 → 0.10.4

package/src/config/migration-validator.ts

@@ -0,0 +1,113 @@
+/**
+ * migration-validator.ts — WI-5.6 (M5 spec §5).
+ *
+ * Validates a parsed config against deprecated/removed env keys and
+ * returns an advisory list (not a failure). Per spec acceptance:
+ *   "Migration validator: test case cũ config + key deprecated →
+ *    warning không fail."
+ *
+ * Key principles (additive-only, READ-ONLY — the validator never mutates
+ * env or config):
+ *   - Deprecated: emit warning (severity "deprecated"), keep the value,
+ *     do not fail.
+ *   - Removed/dead/reverted: emit warning (severity "removed"), do not
+ *     fail, do NOT delete the key (cleanup is a separate concern).
+ *   - Keys not in the registry are not scanned (registry-driven scan).
+ *
+ * Returns an advisory list; never throws.
+ */
+
+import { CREW_ENV_VARS } from "./env-vars.ts";
+
+export interface ValidationWarning {
+	scope: "env-var" | "config-key";
+	name: string;
+	severity: "deprecated" | "removed";
+	message: string;
+	/** Optional policy note from the registry entry. */
+	policy?: string;
+}
+
+export interface EnvValidationResult {
+	warnings: ValidationWarning[];
+	/** Fast-bool for callers that don't need detail. */
+	hasWarnings: boolean;
+}
+
+/** Validate `process.env` against the registry. Returns warnings; never
+ *  throws. */
+export function validateEnv(env: NodeJS.ProcessEnv = process.env): EnvValidationResult {
+	const warnings: ValidationWarning[] = [];
+	if (!env || typeof env !== "object") return { warnings, hasWarnings: false };
+	for (const [name, spec] of Object.entries(CREW_ENV_VARS)) {
+		let value: string | undefined;
+		try {
+			value = (env as Record<string, string | undefined>)[name];
+		} catch {
+			value = undefined;
+		}
+		if (value === undefined) continue;
+		if (spec.deprecated !== undefined) {
+			// Distinguish DEAD/REMOVED vs DEPRECATED-but-working.
+			const lower = spec.deprecated.toLowerCase();
+			if (lower === "dead" || lower === "removed" || lower.startsWith("reverted")) {
+				warnings.push({
+					scope: "env-var",
+					name,
+					severity: "removed",
+					message: `${name} is ${spec.deprecated}; setting it has no effect`,
+					policy: spec.deprecated,
+				});
+				// Note: we DO NOT delete env[name] here; that's a separate
+				// cleanup concern. The validator is read-only.
+			} else {
+				warnings.push({
+					scope: "env-var",
+					name,
+					severity: "deprecated",
+					message: `${name} is deprecated (${spec.deprecated}); prefer the canonical name`,
+					policy: spec.deprecated,
+				});
+			}
+		}
+	}
+	return { warnings, hasWarnings: warnings.length > 0 };
+}
+
+/** Validate a parsed config object against the env-var registry.
+ *  Useful for: a config file that hardcodes a removed key. */
+export function validateConfigAgainstEnvRegistry(config: Record<string, unknown>): EnvValidationResult {
+	const warnings: ValidationWarning[] = [];
+	if (!config || typeof config !== "object") return { warnings, hasWarnings: false };
+	for (const [name, spec] of Object.entries(CREW_ENV_VARS)) {
+		let present = false;
+		try {
+			present = name in config;
+		} catch {
+			present = false;
+		}
+		if (present) {
+			if (spec.deprecated !== undefined) {
+				const lower = spec.deprecated.toLowerCase();
+				if (lower === "dead" || lower === "removed" || lower.startsWith("reverted")) {
+					warnings.push({
+						scope: "config-key",
+						name,
+						severity: "removed",
+						message: `${name} config key is ${spec.deprecated}`,
+						policy: spec.deprecated,
+					});
+				} else {
+					warnings.push({
+						scope: "config-key",
+						name,
+						severity: "deprecated",
+						message: `${name} config key is deprecated (${spec.deprecated})`,
+						policy: spec.deprecated,
+					});
+				}
+			}
+		}
+	}
+	return { warnings, hasWarnings: warnings.length > 0 };
+}

package/src/extension/cross-extension-rpc.ts

@@ -5,17 +5,13 @@ import { withHmacVerification } from "./rpc-hmac.ts";
 // Lazy-loaded to avoid pulling team-tool.ts (and its entire runtime chain) into module load.
 import type { handleTeamTool as HandleTeamToolFn } from "./team-tool.ts";
 
-let _cachedHandleTeamTool: typeof HandleTeamToolFn | undefined;
 async function handleTeamTool(
 	params: Parameters<typeof HandleTeamToolFn>[0],
 	ctx: Parameters<typeof HandleTeamToolFn>[1],
 ): Promise<Awaited<ReturnType<typeof HandleTeamToolFn>>> {
-	if (!_cachedHandleTeamTool) {
-		// LAZY: avoid pulling team-tool.ts (and its entire runtime chain) into module load.
-		const mod = await import("./team-tool.ts");
-		_cachedHandleTeamTool = mod.handleTeamTool;
-	}
-	return _cachedHandleTeamTool(params, ctx);
+	// LAZY: avoid pulling team-tool.ts (and its entire runtime chain) into module load.
+	const mod = await import("./team-tool.ts");
+	return mod.handleTeamTool(params, ctx);
 }
 
 import { parseLiveControlRealtimeMessage, publishLiveControlRealtime } from "../runtime/live-session/live-control-realtime.ts";

package/src/extension/register.ts

@@ -18,6 +18,7 @@
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { loadConfig } from "../config/config.ts";
+import { validateEnv } from "../config/migration-validator.ts";
 import { startRuntimeWarmup } from "../runtime/model/runtime-warmup.ts";
 import { primePeerDep } from "../runtime/peer-dep.ts";
 import { deployBundledThemes } from "../ui/deploy-bundled-themes.ts";
@@ -60,6 +61,18 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 	// full crash chain — /crew-view mid-run crash).
 	installChildProcessAbortShield();
 
+	// WI-5.6 wiring (review remediation 2026-09-10): surface deprecated /
+	// removed / reverted PI_CREW_* env keys as ONE consolidated startup
+	// warning — warn, never fail (spec M5 acceptance). validateEnv is a pure
+	// scanner over the env-registry (env-vars.ts) and never throws.
+	const envWarnings = validateEnv(process.env);
+	if (envWarnings.warnings.length > 0) {
+		console.warn(
+			`[pi-crew] ${envWarnings.warnings.length} deprecated env var(s) in use:\n` +
+				envWarnings.warnings.map((w) => `  ${w.name}: ${w.message}`).join("\n"),
+		);
+	}
+
 	startRuntimeWarmup();
 	primePeerDep().catch(() => undefined);
 	deployBundledThemes();

package/src/extension/registration/observability.ts

@@ -75,14 +75,10 @@ export interface ObservabilityDeps {
 	}>;
 }
 
-let _cachedOTLPExporter: OTLPExporterCtor | undefined;
 async function importOTLPExporter(): Promise<OTLPExporterCtor> {
-	if (!_cachedOTLPExporter) {
-		// LAZY: opt-in OTLP metric export — load only when otlp.enabled=true.
-		const mod = await import("../../observability/exporters/otlp-exporter.ts");
-		_cachedOTLPExporter = mod.OTLPExporter as unknown as OTLPExporterCtor;
-	}
-	return _cachedOTLPExporter;
+	// LAZY: opt-in OTLP metric export — load only when otlp.enabled=true.
+	const mod = await import("../../observability/exporters/otlp-exporter.ts");
+	return mod.OTLPExporter as unknown as OTLPExporterCtor;
 }
 
 /**

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

@@ -6,17 +6,13 @@ import { withSessionId } from "../team-tool/context.ts";
 // Lazy-loaded: team-tool.ts pulls in entire runtime chain.
 import type { handleTeamTool as HandleTeamToolFn } from "../team-tool.ts";
 
-let _cachedHandleTeamTool: typeof HandleTeamToolFn | undefined;
 async function handleTeamTool(
 	params: Parameters<typeof HandleTeamToolFn>[0],
 	ctx: Parameters<typeof HandleTeamToolFn>[1],
 ): Promise<Awaited<ReturnType<typeof HandleTeamToolFn>>> {
-	if (!_cachedHandleTeamTool) {
-		// LAZY: team-tool.ts pulls in entire runtime chain.
-		const mod = await import("../team-tool.ts");
-		_cachedHandleTeamTool = mod.handleTeamTool;
-	}
-	return _cachedHandleTeamTool(params, ctx);
+	// LAZY: team-tool.ts pulls in entire runtime chain.
+	const mod = await import("../team-tool.ts");
+	return mod.handleTeamTool(params, ctx);
 }
 
 import { Text } from "@earendil-works/pi-tui";

package/src/extension/registration/team-tool.ts

@@ -18,17 +18,13 @@ 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";
 
-let _cachedHandleTeamTool: typeof HandleTeamToolFn | undefined;
 async function handleTeamTool(
 	params: Parameters<typeof HandleTeamToolFn>[0],
 	ctx: Parameters<typeof HandleTeamToolFn>[1],
 ): Promise<ReturnType<typeof HandleTeamToolFn>> {
-	if (!_cachedHandleTeamTool) {
-		// LAZY: team-tool.ts imports many modules — defer until first use.
-		const mod = await import("../team-tool.ts");
-		_cachedHandleTeamTool = mod.handleTeamTool;
-	}
-	return _cachedHandleTeamTool(params, ctx);
+	// LAZY: team-tool.ts imports many modules — defer until first use.
+	const mod = await import("../team-tool.ts");
+	return mod.handleTeamTool(params, ctx);
 }
 
 import { readCrewAgents } from "../../runtime/crew-agent-records.ts";

package/src/extension/registration/ui.ts

@@ -27,15 +27,10 @@ import type { CrewWidgetState } from "../../ui/widget/index.ts";
 import { stopCrewWidget, updateCrewWidget } from "../../ui/widget/index.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 
-/** Cached live-run-sidebar constructor (lazy-loaded on first overlay open). */
-let _cachedLiveRunSidebar: typeof LiveRunSidebarType | undefined;
 async function importLiveRunSidebar(): Promise<typeof LiveRunSidebarType> {
-	if (!_cachedLiveRunSidebar) {
-		// LAZY: defer LiveRunSidebar import until the user opens a sidebar overlay.
-		const mod = await import("../../ui/live-run-sidebar.ts");
-		_cachedLiveRunSidebar = mod.LiveRunSidebar;
-	}
-	return _cachedLiveRunSidebar;
+	// LAZY: defer LiveRunSidebar import until the user opens a sidebar overlay.
+	const mod = await import("../../ui/live-run-sidebar.ts");
+	return mod.LiveRunSidebar;
 }
 
 /** Mutable state owned by register.ts. */

package/src/extension/registration/viewers.ts

@@ -8,17 +8,10 @@ import { asCrewTheme } from "../../ui/theme-adapter.ts";
 // Lazy-loaded: DurableTranscriptViewer is 658ms — only needed for /crew transcript command
 import type { DurableTranscriptViewer as DurableTranscriptViewerType } from "../../ui/transcript-viewer.ts";
 
-let _cachedViewer: typeof DurableTranscriptViewerType | undefined;
-let _viewerPromise: Promise<typeof DurableTranscriptViewerType> | undefined;
 async function getViewer(): Promise<typeof DurableTranscriptViewerType> {
-	if (_cachedViewer) return _cachedViewer;
-	if (!_viewerPromise) {
-		_viewerPromise = import("../../ui/transcript-viewer.ts").then((mod) => {
-			_cachedViewer = mod.DurableTranscriptViewer;
-			return mod.DurableTranscriptViewer;
-		});
-	}
-	return _viewerPromise;
+	// LAZY: DurableTranscriptViewer is 658ms — only needed for /crew transcript.
+	const mod = await import("../../ui/transcript-viewer.ts");
+	return mod.DurableTranscriptViewer;
 }
 
 export async function selectAgentTask(

package/src/extension/team-manager-command.ts

@@ -3,17 +3,13 @@ import { listRuns } from "./run-index.ts";
 // Lazy-loaded: team-tool.ts pulls in entire runtime chain.
 import type { handleTeamTool as HandleTeamToolFn } from "./team-tool.ts";
 
-let _cachedHandleTeamTool: typeof HandleTeamToolFn | undefined;
 async function handleTeamTool(
 	params: Parameters<typeof HandleTeamToolFn>[0],
 	ctx: Parameters<typeof HandleTeamToolFn>[1],
 ): Promise<Awaited<ReturnType<typeof HandleTeamToolFn>>> {
-	if (!_cachedHandleTeamTool) {
-		// LAZY: team-tool.ts pulls in the entire runtime chain.
-		const mod = await import("./team-tool.ts");
-		_cachedHandleTeamTool = mod.handleTeamTool;
-	}
-	return _cachedHandleTeamTool(params, ctx);
+	// LAZY: team-tool.ts pulls in the entire runtime chain.
+	const mod = await import("./team-tool.ts");
+	return mod.handleTeamTool(params, ctx);
 }
 
 import { isToolError, textFromToolResult } from "./tool-result.ts";

package/src/extension/team-tool/api/agent-control.ts

@@ -22,7 +22,8 @@ import {
 	appendSteeringMessage,
 	appendSteeringMessageAsync,
 } from "../../../state/coordination/mailbox.ts";
-import { appendEvent } from "../../../state/event-log/event-log.ts";
+import { appendEvent, appendEventBuffered } from "../../../state/event-log/event-log.ts";
+import { logInternalError } from "../../../utils/internal-error.ts";
 import type { ApiOperationHandler } from "./handler-context.ts";
 
 export const handleNudgeAgent: ApiOperationHandler = (hctx) => {
@@ -54,13 +55,19 @@ export const handleNudgeAgent: ApiOperationHandler = (hctx) => {
 		priority: "normal",
 		data: { source: "nudge-agent" },
 	});
-	appendEvent(loaded.manifest.eventsPath, {
-		type: "agent.nudged",
-		runId: loaded.manifest.runId,
-		taskId: agent.taskId,
-		message: messageText,
-		data: { agentId: agent.id, mailboxMessageId: message.id },
-	});
+	// Read-your-writes (CI 2026-09-11, phase8 integration): the nudge caller
+	// reads events.jsonl synchronously right after dispatch — sync appendEvent.
+	try {
+		appendEvent(loaded.manifest.eventsPath, {
+			type: "agent.nudged",
+			runId: loaded.manifest.runId,
+			taskId: agent.taskId,
+			message: messageText,
+			data: { agentId: agent.id, mailboxMessageId: message.id },
+		});
+	} catch (e) {
+		logInternalError("api.agent-control.append", e, "type=agent.nudged");
+	}
 	ctx.events?.emit?.("crew.mailbox.message", {
 		runId: loaded.manifest.runId,
 		id: message.id,
@@ -314,7 +321,7 @@ export const handleLiveAgentControl: ApiOperationHandler = async (hctx) => {
 						: undefined;
 			publishLiveControlRealtime(request);
 			ctx.events?.emit?.("pi-crew:live-control", liveControlRealtimeMessage(request));
-			appendEvent(loaded.manifest.eventsPath, {
+			appendEventBuffered(loaded.manifest.eventsPath, {
 				type: "agent.control.queued",
 				runId: loaded.manifest.runId,
 				taskId: agent.taskId,
@@ -324,7 +331,7 @@ export const handleLiveAgentControl: ApiOperationHandler = async (hctx) => {
 					mailboxMessageId: mailboxMessage?.id,
 					realtime: true,
 				},
-			});
+			}).catch((e) => logInternalError("api.agent-control.buffered", e, "type=agent.control.queued"));
 			return result(JSON.stringify({ queued: true, request, mailboxMessage }, null, 2), {
 				action: "api",
 				status: "ok",

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

@@ -8,8 +8,9 @@
 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 { appendEventBuffered } from "../../../state/event-log/event-log.ts";
 import { loadRunManifestById, saveRunTasks } from "../../../state/stores/state-store.ts";
+import { logInternalError } from "../../../utils/internal-error.ts";
 import { RUN_NOT_FOUND_HINT } from "../run-not-found.ts";
 import type { ApiOperationHandler } from "./handler-context.ts";
 
@@ -79,12 +80,12 @@ export const handleWriteHeartbeat: ApiOperationHandler = (hctx) => {
 			);
 			const tasks = fresh.tasks.map((item) => (item.id === freshTask.id ? { ...item, heartbeat } : item));
 			saveRunTasks(fresh.manifest, tasks);
-			appendEvent(fresh.manifest.eventsPath, {
+			appendEventBuffered(fresh.manifest.eventsPath, {
 				type: "worker.heartbeat",
 				runId: fresh.manifest.runId,
 				taskId: freshTask.id,
 				data: { ...heartbeat },
-			});
+			}).catch((e) => logInternalError("api.heartbeat.buffered", e, "type=worker.heartbeat"));
 			return result(JSON.stringify(heartbeat, null, 2), {
 				action: "api",
 				status: "ok",

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

@@ -16,7 +16,8 @@ import {
 	readMailboxMessage,
 	validateMailbox,
 } from "../../../state/coordination/mailbox.ts";
-import { appendEvent } from "../../../state/event-log/event-log.ts";
+import { appendEvent, appendEventBuffered } from "../../../state/event-log/event-log.ts";
+import { logInternalError } from "../../../utils/internal-error.ts";
 import type { ApiOperationHandler } from "./handler-context.ts";
 
 export const handleReadMailbox: ApiOperationHandler = (hctx) => {
@@ -129,11 +130,11 @@ export const handleSendMessage: ApiOperationHandler = (hctx) => {
 			// run-lock callback. Sync append (byte-identical to pre-extract
 			// api.ts) so consumers reading eventsPath immediately after the
 			// call see the event — async fire-and-forget would race.
-			appendEvent(loaded.manifest.eventsPath, {
+			appendEventBuffered(loaded.manifest.eventsPath, {
 				type: "mailbox.message",
 				runId: loaded.manifest.runId,
 				data: { id: message.id, direction, from, to },
-			});
+			}).catch((e) => logInternalError("api.mailbox.buffered", e, "type=mailbox.message"));
 			ctx.events?.emit?.("crew.mailbox.message", {
 				runId: loaded.manifest.runId,
 				id: message.id,
@@ -185,26 +186,38 @@ export const handleAckMessage: ApiOperationHandler = (hctx) => {
 		return withRunLockSync(loaded.manifest, () => {
 			const message = readMailboxMessage(loaded.manifest, messageId);
 			const delivery = acknowledgeMailboxMessage(loaded.manifest, messageId);
-			appendEvent(loaded.manifest.eventsPath, {
-				type: "mailbox.acknowledged",
-				runId: loaded.manifest.runId,
-				data: { messageId },
-			});
-			if (message?.data?.kind === "group_join" && typeof message.data.requestId === "string") {
+			// Read-your-writes (CI 2026-09-11, phase4 integration): the ack API
+			// returns and callers/tests read events.jsonl synchronously right after —
+			// buffered append flushes later (bufferMs window), so the events were
+			// missing at read. Sync appendEvent (base behavior, b6eba80f pattern).
+			try {
 				appendEvent(loaded.manifest.eventsPath, {
-					type: "agent.group_join.acknowledged",
+					type: "mailbox.acknowledged",
 					runId: loaded.manifest.runId,
-					message: "Group join delivery acknowledged via mailbox ack.",
-					data: {
-						requestId: message.data.requestId,
-						messageId,
-						batchId: message.data.batchId,
-						partial: message.data.partial,
-						acknowledgedAt: delivery.updatedAt,
-						acknowledgedBy: "leader",
-					},
-					metadata: { provenance: "api" },
+					data: { messageId },
 				});
+			} catch (e) {
+				logInternalError("api.mailbox.append", e, "type=mailbox.acknowledged");
+			}
+			if (message?.data?.kind === "group_join" && typeof message.data.requestId === "string") {
+				try {
+					appendEvent(loaded.manifest.eventsPath, {
+						type: "agent.group_join.acknowledged",
+						runId: loaded.manifest.runId,
+						message: "Group join delivery acknowledged via mailbox ack.",
+						data: {
+							requestId: message.data.requestId,
+							messageId,
+							batchId: message.data.batchId,
+							partial: message.data.partial,
+							acknowledgedAt: delivery.updatedAt,
+							acknowledgedBy: "leader",
+						},
+						metadata: { provenance: "api" },
+					});
+				} catch (e) {
+					logInternalError("api.mailbox.append", e, "type=agent.group_join.acknowledged");
+				}
 			}
 			ctx.events?.emit?.("crew.mailbox.acknowledged", {
 				runId: loaded.manifest.runId,

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

@@ -8,7 +8,7 @@
 import { terminateLiveAgentsForRun } from "../../../runtime/live-session/live-agent-manager.ts";
 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 { appendEvent, appendEventBuffered } 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";
@@ -68,13 +68,13 @@ export const handleApprovePlan: ApiOperationHandler = async (hctx) => {
 			// 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, {
+			appendEventBuffered(manifest.eventsPath, {
 				type: "plan.approved",
 				runId: manifest.runId,
 				taskId: approval.planTaskId,
 				message: "Adaptive implementation plan approved; resume the run to execute mutating tasks.",
 				metadata: { provenance: "api" },
-			});
+			}).catch((e) => logInternalError("api.plan-approval.buffered", e, "type=plan.approved"));
 			return result(JSON.stringify(manifest.planApproval, null, 2), {
 				action: "api",
 				status: "ok",
@@ -150,13 +150,13 @@ export const handleCancelPlan: ApiOperationHandler = async (hctx) => {
 			const denyRecord = getCurrentPlanRecord(manifest);
 			if (denyRecord) setPlanApproval(manifest, { status: "rejected", planVersion: denyRecord.version, by: "api" });
 			saveRunTasks(manifest, tasks);
-			appendEvent(manifest.eventsPath, {
+			appendEventBuffered(manifest.eventsPath, {
 				type: "plan.cancelled",
 				runId: manifest.runId,
 				taskId: approval.planTaskId,
 				message: "Adaptive implementation plan was cancelled.",
 				metadata: { provenance: "api" },
-			});
+			}).catch((e) => logInternalError("api.plan-approval.buffered", e, "type=plan.cancelled"));
 			manifest = updateRunStatus(manifest, "cancelled", "Plan approval was cancelled.");
 			void terminateLiveAgentsForRun(manifest.runId, "cancelled", appendEvent, manifest.eventsPath).catch((error) =>
 				logInternalError("team-tool.cancel-plan.terminate", error, `runId=${manifest.runId}`),

package/src/extension/team-tool/api/task-claims.ts

@@ -16,9 +16,10 @@
 import { canTransitionTaskStatus, isTeamTaskStatus } from "../../../state/contracts.ts";
 import { withRunLockSync } from "../../../state/coordination/locks.ts";
 import { claimTask, releaseTaskClaim, transitionClaimedTaskStatus } from "../../../state/coordination/task-claims.ts";
-import { appendEvent } from "../../../state/event-log/event-log.ts";
+import { appendEventBuffered } from "../../../state/event-log/event-log.ts";
 import { loadRunManifestById, saveRunTasks } from "../../../state/stores/state-store.ts";
 import type { TeamTaskState } from "../../../state/types.ts";
+import { logInternalError } from "../../../utils/internal-error.ts";
 import { RUN_NOT_FOUND_HINT } from "../run-not-found.ts";
 import type { ApiHandlerContext, ApiOperationHandler } from "./handler-context.ts";
 
@@ -92,7 +93,7 @@ export const handleClaimTask: ApiOperationHandler = (ctx) => {
 			const updatedTask = claimTask(freshTask, owner);
 			const tasks = fresh.tasks.map((item) => (item.id === freshTask.id ? updatedTask : item));
 			saveRunTasks(fresh.manifest, tasks);
-			appendEvent(fresh.manifest.eventsPath, {
+			appendEventBuffered(fresh.manifest.eventsPath, {
 				type: "task.claimed",
 				runId: fresh.manifest.runId,
 				taskId: freshTask.id,
@@ -101,7 +102,7 @@ export const handleClaimTask: ApiOperationHandler = (ctx) => {
 					token: "[REDACTED]",
 					leasedUntil: updatedTask.claim?.leasedUntil,
 				},
-			});
+			}).catch((e) => logInternalError("api.task-claims.buffered", e, "type=task.claimed"));
 			return result(JSON.stringify(updatedTask.claim, null, 2), {
 				action: "api",
 				status: "ok",
@@ -162,12 +163,12 @@ export const handleReleaseTaskClaim: ApiOperationHandler = (ctx) => {
 			const updatedTask = releaseTaskClaim(freshTask, owner, token);
 			const tasks = fresh.tasks.map((item) => (item.id === freshTask.id ? updatedTask : item));
 			saveRunTasks(fresh.manifest, tasks);
-			appendEvent(fresh.manifest.eventsPath, {
+			appendEventBuffered(fresh.manifest.eventsPath, {
 				type: "task.claim_released",
 				runId: fresh.manifest.runId,
 				taskId: freshTask.id,
 				data: { owner },
-			});
+			}).catch((e) => logInternalError("api.task-claims.buffered", e, "type=task.claim_released"));
 			return result(JSON.stringify(updatedTask, null, 2), {
 				action: "api",
 				status: "ok",
@@ -241,12 +242,12 @@ export const handleTransitionTaskStatus: ApiOperationHandler = (ctx) => {
 			const updatedTask = transitionClaimedTaskStatus(freshTask, owner, token, to);
 			const tasks = fresh.tasks.map((item) => (item.id === freshTask.id ? updatedTask : item));
 			saveRunTasks(fresh.manifest, tasks);
-			appendEvent(fresh.manifest.eventsPath, {
+			appendEventBuffered(fresh.manifest.eventsPath, {
 				type: "task.status_transitioned",
 				runId: fresh.manifest.runId,
 				taskId: freshTask.id,
 				data: { owner, status: to },
-			});
+			}).catch((e) => logInternalError("api.task-claims.buffered", e, "type=task.status_transitioned"));
 			return result(JSON.stringify(updatedTask, null, 2), {
 				action: "api",
 				status: "ok",

package/src/extension/team-tool/cancel.ts

@@ -392,6 +392,12 @@ export async function handleCancel(params: TeamToolParamsValue, ctx: TeamContext
 		}
 		ctx.abortForegroundRun?.(fresh.manifest.runId);
 		for (const taskId of abortResult.abortedIds) {
+			// REVIEW FIX (2026-09-10): reverted M2b buffered conversion. Although
+			// task.cancelled is a TERMINAL type (buffered terminal path bypasses
+			// the 20ms buffer), that path still resolves via a microtask chain
+			// (flushPromise.then(appendEvent)) — NOT same-tick. Cancel tests and
+			// the immediately-following updateRunStatus reader need same-tick
+			// durability, so plain sync appendEvent (base behavior).
 			appendEvent(fresh.manifest.eventsPath, {
 				type: "task.cancelled",
 				runId: fresh.manifest.runId,

package/src/extension/team-tool/handle-settings.ts

@@ -37,7 +37,10 @@ const EFFECTIVE_DEFAULTS: Record<string, unknown> = {
 	"ui.dashboardPlacement": "center",
 	"ui.dashboardWidth": 72,
 	"ui.autoOpenDashboard": false,
-	"ui.widgetPlacement": "aboveEditor",
+	// G17 sync (2026-09-10 review): canonical DEFAULT_UI.widgetPlacement =
+	// "bottom" (defaults.ts / install.mjs / project-init) — was drifted
+	// "aboveEditor" in this duplicated EFFECTIVE_DEFAULTS map.
+	"ui.widgetPlacement": "bottom",
 	"autonomous.enabled": true,
 	"autonomous.injectPolicy": true,
 	"autonomous.preferAsyncForLongTasks": false,

package/src/extension/team-tool/run.ts

@@ -18,14 +18,10 @@ import { logInternalError } from "../../utils/internal-error.ts";
 import { safeAbort } from "../../utils/safe-abort.ts";
 import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
 
-let _cachedExecuteTeamRun: typeof ExecuteTeamRunFn | undefined;
 async function executeTeamRun(...args: Parameters<typeof ExecuteTeamRunFn>): Promise<Awaited<ReturnType<typeof ExecuteTeamRunFn>>> {
-	if (!_cachedExecuteTeamRun) {
-		// LAZY: heavy runtime — defer 1.4s import cost until team run actually executes.
-		const mod = await import("../../runtime/team-runner.ts");
-		_cachedExecuteTeamRun = mod.executeTeamRun;
-	}
-	return _cachedExecuteTeamRun(...args);
+	// LAZY: heavy runtime — defer 1.4s import cost until team run actually executes.
+	const mod = await import("../../runtime/team-runner.ts");
+	return mod.executeTeamRun(...args);
 }
 
 import { spawnBackgroundTeamRun } from "../../runtime/async-runner.ts";

package/src/extension/team-tool/status.ts

@@ -93,6 +93,8 @@ export function transitionStaleAsyncUnderLock(
 		// async.stale (2026-08-10): sync append (byte-identical to pre-extract
 		// api.ts) so callers reading eventsPath immediately after status see
 		// the event — async fire-and-forget would race.
+		// REVIEW FIX (2026-09-10): reverted the M2b buffered conversion — the
+		// same-poll read-back contract below requires same-tick durability.
 		appendEvent(failed.eventsPath, {
 			type: "async.stale",
 			runId: failed.runId,
@@ -192,6 +194,9 @@ export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiT
 		const timedOut = ack === "pending" && ackTimeoutMs !== undefined && Number.isFinite(ageMs) && ageMs > ackTimeoutMs;
 		if (timedOut && !ackTimeoutRequestIds.has(requestId)) {
 			// ack_timeout: sync append (byte-identical to pre-extract api.ts).
+			// REVIEW FIX (2026-09-10): reverted the M2b buffered conversion — the
+			// dedupe set below is rebuilt from readEventsCursor in THIS invocation,
+			// so a buffered write would re-emit duplicates on sub-20ms re-polls.
 			appendEvent(manifest.eventsPath, {
 				type: "agent.group_join.ack_timeout",
 				runId: manifest.runId,