Release v2.0.48 to lock planning durability contracts

This release records the planning-session hardening now verified in the working tree: post-save artifact rendering failures surface as structured partial success, and strict planning payload validation is proven through actual OpenCode tool execution paths.

Constraint: Preserve persistence-first planning semantics without widening Flow's public command/tool surface or dependency boundary.
Rejected: Broaden the release into new workflow surfaces or dependency updates | the verified change is a scoped planning contract and release note update.
Rejected: Treat schema-only coverage as sufficient | execution-path tests now guard the adapter wrapper boundary that OpenCode actually calls.
Confidence: high
Scope-risk: moderate
Directive: Keep future planning schema strictness scoped to documented adapter-facing boundaries and keep artifact rendering failures distinguishable from unsaved state failures.
Tested: bun test tests/config/tool-schemas.test.ts; bun run typecheck; bunx biome check tests/config/tool-schemas.test.ts; bun run check; bun run smoke:release; bun run check:fresh-surfaces && bun run check:pack-invariants.
Not-tested: Live OpenCode UI runtime interaction; live GitHub-hosted release workflow run for tag v2.0.48 before push.

Author: vriesdcrv

CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [2.0.48] - 2026-05-14
+
+Lock planning validation and post-save artifact recovery
+
+Flow 2.0.48 closes the release-review gaps around planning-session durability and OpenCode planning payload validation. `flow_plan_start` now preserves the saved source-of-truth session when artifact rendering fails after persistence, returning a structured `partial_success` response with artifact-sync failure metadata instead of throwing after the mutation was already durable.
+
+Planning payload strictness is now enforced at the adapter-facing runtime parse boundaries for `flow_plan_apply` and `flow_plan_context_record`. The outer `flow_plan_apply` payload, nested `plan`, nested optional `planning`, and `flow_plan_context_record` planning context reject unknown keys, while simple status/history tools remain intentionally tolerant. New execution-path tests call the actual OpenCode tool `execute()` wrappers to prove validation failures short-circuit through structured JSON errors, not only direct schema `safeParse()` checks.
+
+The release deliberately does not add slash commands, runtime tools, prompt modes, state paths, package exports, installer behavior, dependencies, persisted schema migrations, or live OpenCode UI automation. It preserves the existing `@opencode-ai/plugin` and `zod` compatibility boundary.
+
+Constraint: Preserve persistence-first planning semantics while making stale artifact rendering an explicit repair signal after saved state
+Constraint: Tighten only the adapter-facing planning payload boundaries; simple read/status tool payloads remain tolerant by contract
+Constraint: Keep `@opencode-ai/plugin` at `1.14.48` and `zod` at `4.1.8`; this release changes no dependency compatibility boundary
+Rejected: Treat post-save artifact rendering failure as a total `flow_plan_start` failure | callers need to know the session was saved and only derived artifacts need repair
+Rejected: Make every tool schema strict | the strictness contract is scoped to planning payload boundaries and preserves tolerant simple tool behavior
+Rejected: Add a new workspace result-kind hierarchy in this release | the current structured `partial_success` response covers callers without widening the runtime action API
+Confidence: high
+Scope-risk: moderate
+Reversibility: clean
+Directive: Keep planning payload strictness scoped to documented adapter-facing boundaries, and keep post-persistence artifact failures distinguishable from unsaved mutation failures
+Tested: `bun test tests/config/tool-schemas.test.ts` (18 pass, 0 fail, 515 expect() calls); `bun run typecheck`; `bunx biome check tests/config/tool-schemas.test.ts`; `bun run check` (release gate passed: dependency contract OK with project/plugin/root `zod=4.1.8`, architecture seams OK, fresh surfaces OK, pack invariants OK for version `2.0.48`, bundle sanity OK, full suite 663 pass/0 fail, lint passed, bench smoke and bench gate passed); `bun run smoke:release` (passed for package `2.0.48`, wrote release-smoke evidence under `prompt-exports/release-smoke/`, real OpenCode CLI not invoked); RepoPrompt Oracle architect review of the execution-path strictness follow-up returned APPROVE
+Not-tested: Live OpenCode UI runtime interaction; live GitHub-hosted release workflow run for tag `v2.0.48` before push
+
 ## [2.0.47] - 2026-05-14
 
 Make release smoke safe for reusable evidence directories

docs/architecture/strictness-contract.md

@@ -15,7 +15,8 @@ Scope: `src/adapters/opencode/tool-surface/schemas.ts`, `src/adapters/opencode/t
 A change is strictness-preserving only if **all** clauses hold:
 
 1. **Required fields and unions do not widen at the bridge.**
-   - `flow_plan_apply` remains `{ plan: PlanArgsSchema.strict(), planning?: PlanningContextArgsSchema.strict() }` at the adapter boundary.
+   - Adapter-facing planning payloads reject unknown keys at these object boundaries: outer `flow_plan_apply`, `flow_plan_apply.plan` (`PlanArgsSchema.strict()`), optional `flow_plan_apply.planning` (`PlanningContextArgsSchema.strict()`), and outer `flow_plan_context_record`.
+   - This planning strictness is scoped; it is not a global all-tools policy, and intentionally tolerant simple tool schemas remain covered by their own tests.
    - Worker completion continues to be parsed by `WorkerResultArgsSchema`, exported from `src/runtime/schema.ts` and owned internally by `src/runtime/schema-worker-result.ts`, before transition calls.
 
 2. **Runtime parse/validation path is never bypassed.**

docs/releases/v2.0.48.md

@@ -0,0 +1,22 @@
+# v2.0.48
+
+Lock planning validation and post-save artifact recovery
+
+Flow 2.0.48 closes the release-review gaps around planning-session durability and OpenCode planning payload validation. `flow_plan_start` now preserves the saved source-of-truth session when artifact rendering fails after persistence, returning a structured `partial_success` response with artifact-sync failure metadata instead of throwing after the mutation was already durable.
+
+Planning payload strictness is now enforced at the adapter-facing runtime parse boundaries for `flow_plan_apply` and `flow_plan_context_record`. The outer `flow_plan_apply` payload, nested `plan`, nested optional `planning`, and `flow_plan_context_record` planning context reject unknown keys, while simple status/history tools remain intentionally tolerant. New execution-path tests call the actual OpenCode tool `execute()` wrappers to prove validation failures short-circuit through structured JSON errors, not only direct schema `safeParse()` checks.
+
+The release deliberately does not add slash commands, runtime tools, prompt modes, state paths, package exports, installer behavior, dependencies, persisted schema migrations, or live OpenCode UI automation. It preserves the existing `@opencode-ai/plugin` and `zod` compatibility boundary.
+
+Constraint: Preserve persistence-first planning semantics while making stale artifact rendering an explicit repair signal after saved state
+Constraint: Tighten only the adapter-facing planning payload boundaries; simple read/status tool payloads remain tolerant by contract
+Constraint: Keep `@opencode-ai/plugin` at `1.14.48` and `zod` at `4.1.8`; this release changes no dependency compatibility boundary
+Rejected: Treat post-save artifact rendering failure as a total `flow_plan_start` failure | callers need to know the session was saved and only derived artifacts need repair
+Rejected: Make every tool schema strict | the strictness contract is scoped to planning payload boundaries and preserves tolerant simple tool behavior
+Rejected: Add a new workspace result-kind hierarchy in this release | the current structured `partial_success` response covers callers without widening the runtime action API
+Confidence: high
+Scope-risk: moderate
+Reversibility: clean
+Directive: Keep planning payload strictness scoped to documented adapter-facing boundaries, and keep post-persistence artifact failures distinguishable from unsaved mutation failures
+Tested: `bun test tests/config/tool-schemas.test.ts` (18 pass, 0 fail, 515 expect() calls); `bun run typecheck`; `bunx biome check tests/config/tool-schemas.test.ts`; `bun run check` (release gate passed: dependency contract OK with project/plugin/root `zod=4.1.8`, architecture seams OK, fresh surfaces OK, pack invariants OK for version `2.0.48`, bundle sanity OK, full suite 663 pass/0 fail, lint passed, bench smoke and bench gate passed); `bun run smoke:release` (passed for package `2.0.48`, wrote release-smoke evidence under `prompt-exports/release-smoke/`, real OpenCode CLI not invoked); RepoPrompt Oracle architect review of the execution-path strictness follow-up returned APPROVE
+Not-tested: Live OpenCode UI runtime interaction; live GitHub-hosted release workflow run for tag `v2.0.48` before push

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-plugin-flow",
-	"version": "2.0.47",
+	"version": "2.0.48",
 	"description": "Stateful planning and execution workflow plugin for OpenCode",
 	"type": "module",
 	"main": "dist/index.js",

src/adapters/opencode/tool-surface/schemas.ts

@@ -83,10 +83,10 @@ export const FlowPlanStartArgsShape = {
 	goal: z.string().trim().min(1).optional(),
 	repoProfile: z.array(z.string().min(1)).optional(),
 };
-export const FlowPlanContextRecordArgsSchema = z.object(
-	FlowPlanContextRecordArgsShape,
-);
-export const FlowPlanApplyArgsSchema = z.object(FlowPlanApplyArgsShape);
+export const FlowPlanContextRecordArgsSchema = RuntimePlanningContextArgsSchema;
+export const FlowPlanApplyArgsSchema = z
+	.object(FlowPlanApplyArgsShape)
+	.strict();
 export const FlowPlanApproveArgsShape = {
 	featureIds: z.array(featureIdSchema).optional(),
 };

src/runtime/application/session-workspace-actions.ts

@@ -12,6 +12,7 @@ import {
 	type SessionWorkspaceResult,
 	type SessionWorkspaceRuntimePort,
 } from "./session-engine";
+import type { SessionArtifactSyncFailure } from "./session-mutation-finalization";
 import { mergePlanningContext } from "./session-planning-context";
 import { detectStackAndStandardsProfile } from "./stack-standards-profile";
 import {
@@ -29,8 +30,17 @@ type PlannedSessionResult =
 	| {
 			status: "ok";
 			session: Session;
+			artifactSync?: SessionArtifactSyncFailure;
 	  };
 
+function artifactSyncFailure(error: unknown): SessionArtifactSyncFailure {
+	return {
+		status: "failed",
+		error:
+			error instanceof Error && error.message ? error.message : String(error),
+	};
+}
+
 function buildPlannedSession(
 	existing: Session | null,
 	goal: string,
@@ -135,8 +145,16 @@ export const SESSION_WORKSPACE_ACTION_HANDLERS: SessionWorkspaceActionHandlerMap
 							...detectedProfiles,
 						}),
 					);
-					await runtime.syncSessionArtifacts(worktree, session);
-					return { status: "ok", session };
+					try {
+						await runtime.syncSessionArtifacts(worktree, session);
+						return { status: "ok", session };
+					} catch (error) {
+						return {
+							status: "ok",
+							session,
+							artifactSync: artifactSyncFailure(error),
+						};
+					}
 				},
 				onSuccess: (value) =>
 					value.status === "missing_goal"
@@ -146,8 +164,14 @@ export const SESSION_WORKSPACE_ACTION_HANDLERS: SessionWorkspaceActionHandlerMap
 								nextCommand: value.nextCommand,
 							}
 						: {
-								status: "ok",
+								status: value.artifactSync ? "partial_success" : "ok",
 								summary: `Planning session ready for goal: ${value.session.goal}`,
+								...(value.artifactSync
+									? {
+											persistedMutation: true,
+											artifactSync: value.artifactSync,
+										}
+									: {}),
 								session: summarizeSession(value.session).session,
 							},
 			};

src/runtime/schema-plan.ts

@@ -119,9 +119,12 @@ export const PlanningContextSchema = z.object({
 export const PlanArgsSchema = PlanSchema.omit({
 	goalMode: true,
 	decompositionPolicy: true,
-}).extend({
-	goalMode: GoalModeSchema.optional(),
-	decompositionPolicy: DecompositionPolicySchema.optional(),
-});
+})
+	.extend({
+		goalMode: GoalModeSchema.optional(),
+		decompositionPolicy: DecompositionPolicySchema.optional(),
+	})
+	.strict();
 
-export const PlanningContextArgsSchema = PlanningContextSchema.partial();
+export const PlanningContextArgsSchema =
+	PlanningContextSchema.partial().strict();

tests/config/tool-schemas.test.ts

@@ -1,6 +1,6 @@
 // Owns OpenCode tool arg-shape, zod/plugin alignment, and raw-schema
 // contract coverage previously grouped in tests/config.test.ts.
-import { describe, expect, test } from "bun:test";
+import { afterEach, describe, expect, test } from "bun:test";
 import { existsSync } from "node:fs";
 import type { ToolContext as OpenCodeToolContext } from "@opencode-ai/plugin/tool";
 import { z } from "zod";
@@ -22,6 +22,12 @@ import {
 	WorkerResultArgsSchema,
 	WorkerResultSchema,
 } from "../../src/runtime/schema";
+import {
+	createTempDirRegistry,
+	createTestTools,
+	samplePlan,
+	toolContext,
+} from "../runtime-test-helpers";
 import { asJson, getToolSchemas, projectPath, readJson } from "./helpers";
 
 type IsRequired<T, K extends keyof T> =
@@ -36,6 +42,12 @@ type OpenCodeToolContextRequiredAssertions = [
 	Assert<IsRequired<OpenCodeToolContext, "ask">>,
 ];
 
+const { makeTempDir, cleanupTempDirs } = createTempDirRegistry();
+
+afterEach(() => {
+	cleanupTempDirs();
+});
+
 describe("tool schema config contracts", () => {
 	test("installed OpenCode ToolContext keeps required execution fields", () => {
 		const requiredAssertions: OpenCodeToolContextRequiredAssertions = [
@@ -225,10 +237,12 @@ describe("tool schema config contracts", () => {
 
 	test("runtime-owned OpenCode payload schemas document adapter/runtime parity intent", () => {
 		const { schemas } = getToolSchemas();
-		const RuntimeFlowPlanApplyArgsSchema = z.object({
-			plan: PlanArgsSchema,
-			planning: PlanningContextArgsSchema.optional(),
-		});
+		const RuntimeFlowPlanApplyArgsSchema = z
+			.object({
+				plan: PlanArgsSchema,
+				planning: PlanningContextArgsSchema.optional(),
+			})
+			.strict();
 		const runtimeOwnedTools = [
 			"flow_plan_context_record",
 			"flow_plan_apply",
@@ -269,7 +283,6 @@ describe("tool schema config contracts", () => {
 			{ ...validPlanningContext, packageManager: "cargo" },
 			false,
 		);
-
 		const validPlanApply = {
 			plan: {
 				summary: "Implement a workflow.",
@@ -304,7 +317,6 @@ describe("tool schema config contracts", () => {
 			},
 			false,
 		);
-
 		const validWorkerResult = {
 			contractVersion: "1",
 			status: "ok",
@@ -397,6 +409,138 @@ describe("tool schema config contracts", () => {
 		);
 	});
 
+	test("planning runtime parse schemas reject unknown adapter-facing keys narrowly", () => {
+		const adapterSchema = (
+			toolName: "flow_plan_apply" | "flow_plan_context_record",
+		) =>
+			FLOW_TOOL_PAYLOAD_SCHEMA_REGISTRY[toolName].argsSchema as {
+				safeParse: (payload: unknown) => { success: boolean };
+			};
+		const validPlanningContext = {
+			repoProfile: ["TypeScript"],
+			packageManager: "bun",
+			research: ["Use local schema contracts as source of truth."],
+		};
+		const validPlan = {
+			summary: "Implement a workflow.",
+			overview: "Create one feature.",
+			features: [
+				{
+					id: "setup-runtime",
+					title: "Create runtime helpers",
+					summary: "Add runtime helpers.",
+					fileTargets: ["src/runtime/session.ts"],
+					verification: ["bun test"],
+				},
+			],
+		};
+		const validPlanApply = {
+			plan: validPlan,
+			planning: validPlanningContext,
+		};
+
+		expect(
+			PlanArgsSchema.safeParse({ ...validPlan, unexpected: true }).success,
+		).toBe(false);
+		expect(
+			PlanningContextArgsSchema.safeParse({
+				...validPlanningContext,
+				unexpected: true,
+			}).success,
+		).toBe(false);
+		expect(
+			adapterSchema("flow_plan_apply").safeParse({
+				...validPlanApply,
+				unexpected: true,
+			}).success,
+		).toBe(false);
+		expect(
+			adapterSchema("flow_plan_apply").safeParse({
+				...validPlanApply,
+				plan: { ...validPlan, unexpected: true },
+			}).success,
+		).toBe(false);
+		expect(
+			adapterSchema("flow_plan_apply").safeParse({
+				...validPlanApply,
+				planning: { ...validPlanningContext, unexpected: true },
+			}).success,
+		).toBe(false);
+		expect(
+			adapterSchema("flow_plan_context_record").safeParse({
+				...validPlanningContext,
+				unexpected: true,
+			}).success,
+		).toBe(false);
+
+		const { schemas } = getToolSchemas();
+		expect(schemas.flow_status.safeParse({ extra: true }).success).toBe(true);
+		expect(schemas.flow_history.safeParse({ extra: true }).success).toBe(true);
+	});
+
+	test("planning tools reject unknown keys through execute validation path", async () => {
+		const tools = createTestTools();
+		const worktree = makeTempDir();
+		const validPlanningContext = {
+			repoProfile: ["TypeScript"],
+			packageManager: "bun",
+			research: ["Use local schema contracts as source of truth."],
+		};
+		const validPlanApply = {
+			plan: samplePlan(),
+			planning: validPlanningContext,
+		};
+		const cases = [
+			{
+				name: "context top-level",
+				toolName: "flow_plan_context_record",
+				payload: { ...validPlanningContext, unexpectedPlanningKey: true },
+				expectedFragments: ["unexpectedPlanningKey"],
+			},
+			{
+				name: "apply outer",
+				toolName: "flow_plan_apply",
+				payload: { ...validPlanApply, unexpectedOuterKey: true },
+				expectedFragments: ["unexpectedOuterKey"],
+			},
+			{
+				name: "apply nested plan",
+				toolName: "flow_plan_apply",
+				payload: {
+					...validPlanApply,
+					plan: { ...validPlanApply.plan, unexpectedPlanKey: true },
+				},
+				expectedFragments: ["plan", "unexpectedPlanKey"],
+			},
+			{
+				name: "apply nested planning",
+				toolName: "flow_plan_apply",
+				payload: {
+					...validPlanApply,
+					planning: { ...validPlanningContext, unexpectedPlanningKey: true },
+				},
+				expectedFragments: ["planning", "unexpectedPlanningKey"],
+			},
+		] as const;
+
+		for (const testCase of cases) {
+			const response = await tools[testCase.toolName].execute(
+				testCase.payload,
+				toolContext(worktree),
+			);
+			const parsed = JSON.parse(response);
+			const responseText = JSON.stringify(parsed);
+
+			expect(parsed.status, testCase.name).toBe("error");
+			expect(String(parsed.summary), testCase.name).toContain(
+				"Tool argument validation failed",
+			);
+			for (const fragment of testCase.expectedFragments) {
+				expect(responseText, testCase.name).toContain(fragment);
+			}
+		}
+	});
+
 	test("final review reviewContextPack raw schemas match runtime structured schema", () => {
 		const { schemas } = getToolSchemas();
 		const structuredReviewContextPack = {