@sayknow-cli/coding-agent 0.3.6 → 0.3.7

package/src/session/session-manager.ts

@@ -1461,9 +1461,25 @@ function materializeResidentEntrySync<T extends FileEntry | SessionEntry>(
 function materializeResidentEntriesSync<T extends FileEntry | SessionEntry>(
 	entries: T[],
 	stores: ResidentBlobStores,
+	missingPolicy: ResidentBlobMissingPolicy = "throw",
 ): T[] {
 	const cache = new Map<string, string>();
-	return entries.map(entry => materializeResidentEntrySync(entry, stores, cache));
+	return entries.map(entry => materializeResidentEntrySync(entry, stores, cache, missingPolicy));
+}
+
+function materializeResidentEntryForReadSync<T extends FileEntry | SessionEntry>(
+	entry: T,
+	stores: ResidentBlobStores,
+	cache: Map<string, string>,
+): T {
+	return materializeResidentEntrySync(entry, stores, cache, "placeholder");
+}
+
+function materializeResidentEntriesForReadSync<T extends FileEntry | SessionEntry>(
+	entries: T[],
+	stores: ResidentBlobStores,
+): T[] {
+	return materializeResidentEntriesSync(entries, stores, "placeholder");
 }
 
 function materializeResidentEntryForPersistenceSync<T extends FileEntry | SessionEntry>(
@@ -1520,12 +1536,24 @@ function cloneSessionEntry(entry: SessionEntry): SessionEntry {
 function materializeProviderVisibleEntrySync(entry: SessionEntry, stores: ResidentBlobStores): SessionEntry {
 	if (entry.type === "compaction") {
 		const cache = new Map<string, string>();
-		const summary = materializeResidentValueSync(entry.summary, stores, "summary", cache);
-		const shortSummary = materializeResidentValueSync(entry.shortSummary, stores, "shortSummary", cache);
+		const summary = materializeResidentValueSync(entry.summary, stores, "summary", cache, "placeholder");
+		const shortSummary = materializeResidentValueSync(
+			entry.shortSummary,
+			stores,
+			"shortSummary",
+			cache,
+			"placeholder",
+		);
 		const remote = entry.preserveData?.openaiRemoteCompaction;
 		const remoteRecord = isRecord(remote) ? remote : undefined;
 		const replacementHistory = remoteRecord
-			? materializeResidentValueSync(remoteRecord.replacementHistory, stores, "replacementHistory", cache)
+			? materializeResidentValueSync(
+					remoteRecord.replacementHistory,
+					stores,
+					"replacementHistory",
+					cache,
+					"placeholder",
+				)
 			: undefined;
 		const preserveData =
 			remoteRecord && replacementHistory !== undefined && replacementHistory !== remoteRecord.replacementHistory
@@ -1545,7 +1573,13 @@ function materializeProviderVisibleEntrySync(entry: SessionEntry, stores: Reside
 		};
 	}
 	if (entry.type === "branch_summary") {
-		const summary = materializeResidentValueSync(entry.summary, stores, "summary", new Map<string, string>());
+		const summary = materializeResidentValueSync(
+			entry.summary,
+			stores,
+			"summary",
+			new Map<string, string>(),
+			"placeholder",
+		);
 		return typeof summary === "string" ? { ...entry, summary } : { ...entry };
 	}
 	return cloneSessionEntry(entry);
@@ -2751,7 +2785,10 @@ export class SessionManager {
 	}
 
 	captureState(): SessionManagerStateSnapshot {
-		const materializedFileEntries = materializeResidentEntriesSync(this.#fileEntries, this.#residentBlobStores());
+		const materializedFileEntries = materializeResidentEntriesForReadSync(
+			this.#fileEntries,
+			this.#residentBlobStores(),
+		);
 		return {
 			sessionId: this.#sessionId,
 			sessionName: this.#sessionName,
@@ -2875,7 +2912,7 @@ export class SessionManager {
 
 		const oldSessionFile = this.#sessionFile;
 		const oldSessionId = this.#sessionId;
-		const materializedEntries = materializeResidentEntriesSync(this.#fileEntries, this.#residentBlobStores());
+		const materializedEntries = materializeResidentEntriesForReadSync(this.#fileEntries, this.#residentBlobStores());
 
 		// Close the current writer
 		await this.#closePersistWriter();
@@ -2947,7 +2984,10 @@ export class SessionManager {
 			hadSessionFile = this.storage.existsSync(oldSessionFile);
 			let movedSessionFile = false;
 			let movedArtifactDir = false;
-			const materializedEntries = materializeResidentEntriesSync(this.#fileEntries, this.#residentBlobStores());
+			const materializedEntries = materializeResidentEntriesForReadSync(
+				this.#fileEntries,
+				this.#residentBlobStores(),
+			);
 			const restoreResidentStateAfterFailure = (): void => {
 				this.#fileEntries = materializedEntries;
 				this.#resetResidentTextBlobStore();
@@ -4006,7 +4046,7 @@ export class SessionManager {
 	getLeafEntry(): SessionEntry | undefined {
 		if (!this.#leafId) return undefined;
 		const entry = this.#byId.get(this.#leafId);
-		return entry ? materializeResidentEntrySync(entry, this.#residentBlobStores(), new Map()) : undefined;
+		return entry ? materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), new Map()) : undefined;
 	}
 
 	/**
@@ -4176,7 +4216,7 @@ export class SessionManager {
 		const entry = this.#byId.get(id);
 		return entry
 			? rehydrateColdSpillEntry(
-					materializeResidentEntrySync(entry, this.#residentBlobStores(), new Map()),
+					materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), new Map()),
 					this.#blobStore,
 					this.#residentBlobStoresForColdRehydrate(),
 				)
@@ -4193,7 +4233,7 @@ export class SessionManager {
 			visited.add(current.id);
 			path.push(
 				rehydrateColdSpillEntry(
-					materializeResidentEntrySync(current, this.#residentBlobStores(), cache),
+					materializeResidentEntryForReadSync(current, this.#residentBlobStores(), cache),
 					this.#blobStore,
 					this.#residentBlobStoresForColdRehydrate(),
 				),
@@ -4233,7 +4273,7 @@ export class SessionManager {
 			.filter((entry): entry is SessionEntry => entry.type !== "session")
 			.map(entry =>
 				rehydrateColdSpillEntry(
-					materializeResidentEntrySync(entry, this.#residentBlobStores(), cache),
+					materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), cache),
 					this.#blobStore,
 					this.#residentBlobStoresForColdRehydrate(),
 				),
@@ -4244,7 +4284,7 @@ export class SessionManager {
 		this.#publicMaterializerCallCount++;
 		this.#getEntryMaterializerCallCount++;
 		const entry = this.#byId.get(id);
-		return entry ? materializeResidentEntrySync(entry, this.#residentBlobStores(), new Map()) : undefined;
+		return entry ? materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), new Map()) : undefined;
 	}
 
 	/**
@@ -4255,7 +4295,7 @@ export class SessionManager {
 		const children: SessionEntry[] = [];
 		for (const entry of this.#byId.values()) {
 			if (entry.parentId === parentId) {
-				children.push(materializeResidentEntrySync(entry, this.#residentBlobStores(), cache));
+				children.push(materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), cache));
 			}
 		}
 		return children;
@@ -4310,7 +4350,7 @@ export class SessionManager {
 		while (current) {
 			if (visited.has(current.id)) break;
 			visited.add(current.id);
-			path.push(materializeResidentEntrySync(current, this.#residentBlobStores(), cache));
+			path.push(materializeResidentEntryForReadSync(current, this.#residentBlobStores(), cache));
 			current = current.parentId ? this.#byId.get(current.parentId) : undefined;
 		}
 		path.reverse();
@@ -4375,7 +4415,7 @@ export class SessionManager {
 		}
 		if (entry.type !== "message" && entry.type !== "custom_message")
 			return materializeProviderVisibleEntrySync(entry, this.#residentBlobStores());
-		const materialized = materializeResidentEntrySync(entry, this.#residentBlobStores(), new Map());
+		const materialized = materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), new Map());
 		const rehydrated = rehydrateColdSpillEntry(
 			materialized,
 			this.#blobStore,
@@ -4434,7 +4474,7 @@ export class SessionManager {
 		const resolvedTextBlobCache = new Map<string, string>();
 		const materializedEntries = this.#fileEntries
 			.filter((e): e is SessionEntry => e.type !== "session")
-			.map(entry => materializeResidentEntrySync(entry, this.#residentBlobStores(), resolvedTextBlobCache));
+			.map(entry => materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), resolvedTextBlobCache));
 		this.#materializedEntriesCache = materializedEntries;
 		this.#materializedEntriesRevision = this.#entryRevision;
 		return materializedEntries;
@@ -4591,7 +4631,7 @@ export class SessionManager {
 
 		// Filter out LabelEntry from path - we'll recreate them from the resolved map
 		const pathWithoutLabels = branchPath.filter(e => e.type !== "label");
-		const materializedPathWithoutLabels = materializeResidentEntriesSync(
+		const materializedPathWithoutLabels = materializeResidentEntriesForReadSync(
 			pathWithoutLabels,
 			this.#residentBlobStores(),
 		);

package/src/skc-runtime/ralplan-runtime.ts

@@ -11,7 +11,7 @@ import {
 	type RalplanIndexRow,
 	summarizeRalplanIndex,
 } from "./ledger-event-renderer";
-import { isRestrictedRoleAgentBash } from "./restricted-role-agent-bash";
+import { isRestrictedRoleAgentBash, SKC_RALPLAN_ARTIFACT_ENV } from "./restricted-role-agent-bash";
 import { modeStatePath, sessionPlansDir } from "./session-layout";
 import { resolveSkcSessionForWrite, writeSessionActivityMarker } from "./session-resolution";
 import { migrateWorkflowState } from "./state-migrations";
@@ -35,8 +35,9 @@ import {
  *    that lives in the bundled `/skill:ralplan` skill — but it accepts every documented flag so
  *    scripted users see a useful response and the active run is visible to the TUI.
  *
- * 2. **Artifact write**: `skc ralplan --write --stage <type> --stage_n <N> --artifact
- *    <path-or-string> [--run-id <id>] [--session-id <id>] [--json]` persists Planner / Architect
+ * 2. **Artifact write**: `skc ralplan --write --stage <type> --stage_n <N>
+ *    (--artifact <path-or-string> | --artifact-env SKC_RALPLAN_ARTIFACT)
+ *    [--run-id <id>] [--session-id <id>] [--json]` persists Planner / Architect
  *    / Critic / revision / post-interview / ADR / final markdown under `.skc/plans/ralplan/<run-id>/`, maintains
  *    an `index.jsonl` audit log, copies `final` stages to `pending-approval.md`, and advances
  *    the HUD chip to reflect the latest persisted stage.
@@ -81,6 +82,7 @@ const VALUE_FLAGS = new Set([
 	"--stage",
 	"--stage_n",
 	"--artifact",
+	"--artifact-env",
 	"--run-id",
 	"--session-id",
 	"--architect",
@@ -409,8 +411,16 @@ async function resolveArtifactArgs(args: readonly string[], cwd: string): Promis
 	const stageN = parseStageN(flagValue(args, "--stage_n"));
 
 	const rawArtifact = flagValue(args, "--artifact");
-	if (rawArtifact === undefined || rawArtifact === "") {
-		throw new RalplanCommandError(2, "--artifact is required for ralplan --write");
+	const artifactEnvName = flagValue(args, "--artifact-env");
+	const artifactSources = [rawArtifact, artifactEnvName].filter(value => value !== undefined);
+	if (artifactSources.length === 0 || artifactSources.some(value => value === "")) {
+		throw new RalplanCommandError(2, "--artifact or --artifact-env is required for ralplan --write");
+	}
+	if (artifactSources.length > 1) {
+		throw new RalplanCommandError(2, "--artifact and --artifact-env are mutually exclusive");
+	}
+	if (artifactEnvName !== undefined && artifactEnvName !== SKC_RALPLAN_ARTIFACT_ENV) {
+		throw new RalplanCommandError(2, `--artifact-env must be ${SKC_RALPLAN_ARTIFACT_ENV}`);
 	}
 
 	const session = resolveSkcSessionForWrite(cwd, {
@@ -430,7 +440,13 @@ async function resolveArtifactArgs(args: readonly string[], cwd: string): Promis
 	const runId = explicitRunId || (await readActiveRunId(cwd, sessionId)) || sessionIdRaw || defaultRunId();
 	assertSafePathComponent(runId, "run-id");
 
-	const artifact = await resolveArtifactContent(rawArtifact, cwd);
+	const artifact =
+		artifactEnvName !== undefined
+			? (process.env[SKC_RALPLAN_ARTIFACT_ENV] ?? "")
+			: await resolveArtifactContent(rawArtifact!, cwd);
+	if (artifact === "") {
+		throw new RalplanCommandError(2, "artifact content is empty");
+	}
 	return { stage: stage as RalplanStage, stageN, runId, artifact, sessionId, json: hasFlag(args, "--json") };
 }
 

package/src/skc-runtime/restricted-role-agent-bash.ts

@@ -1,4 +1,5 @@
 export const SKC_RESTRICTED_ROLE_AGENT_BASH_ENV = "SKC_RESTRICTED_ROLE_AGENT_BASH";
+export const SKC_RALPLAN_ARTIFACT_ENV = "SKC_RALPLAN_ARTIFACT";
 
 export function isRestrictedRoleAgentBash(): boolean {
 	return process.env[SKC_RESTRICTED_ROLE_AGENT_BASH_ENV] === "1";

package/src/skc-runtime/session-state-sidecar.ts

@@ -1,13 +1,18 @@
+import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { AssistantMessage } from "@sayknow-cli/ai";
-import { logger } from "@sayknow-cli/utils";
+import { logger, postmortem } from "@sayknow-cli/utils";
 
 export const SKC_COORDINATOR_SESSION_STATE_FILE_ENV = "SKC_COORDINATOR_SESSION_STATE_FILE";
 export const SKC_COORDINATOR_SESSION_ID_ENV = "SKC_COORDINATOR_SESSION_ID";
+export const SKC_COORDINATOR_SESSION_BRANCH_ENV = "SKC_COORDINATOR_SESSION_BRANCH";
 
 export type RuntimeState = "ready_for_input" | "running" | "needs_user_input" | "completed" | "errored";
 
+type FinalResponseSource = "agent_end" | "launch_error";
+const MAX_PUBLIC_ERROR_MESSAGE_LENGTH = 2000;
+
 interface RuntimeStateEvent {
 	type: string;
 	messages?: unknown[];
@@ -17,6 +22,7 @@ interface RuntimeStateContext {
 	sessionId: string;
 	cwd: string;
 	sessionFile?: string | null;
+	branch?: string | null;
 }
 
 interface RuntimeStateSidecarPayload {
@@ -26,6 +32,7 @@ interface RuntimeStateSidecarPayload {
 	ready_for_input?: unknown;
 	cwd?: unknown;
 	session_file?: unknown;
+	final_response?: { source?: unknown };
 }
 
 export type TerminalRuntimeStateStatus =
@@ -103,7 +110,7 @@ function assistantText(assistant: AssistantMessage | undefined): string | null {
 function finalResponseForEvent(event: RuntimeStateEvent): {
 	text: string | null;
 	format: "markdown";
-	source: "agent_end";
+	source: FinalResponseSource;
 	artifact_path: null;
 	truncated: false;
 } | null {
@@ -127,6 +134,118 @@ function stateForEvent(event: RuntimeStateEvent): RuntimeState | null {
 	return null;
 }
 
+function readPreviousPayload(stateFile: string): Record<string, unknown> {
+	try {
+		return JSON.parse(fsSync.readFileSync(stateFile, "utf8")) as Record<string, unknown>;
+	} catch {
+		return {};
+	}
+}
+
+function shouldPreserveTerminalPayload(previous: RuntimeStateSidecarPayload): boolean {
+	if (previous.state !== "completed" && previous.state !== "errored") return false;
+	const source = previous.final_response?.source;
+	return source === "agent_end" || source === "launch_error";
+}
+
+function branchForContext(context: RuntimeStateContext): string | null {
+	return context.branch ?? (process.env[SKC_COORDINATOR_SESSION_BRANCH_ENV]?.trim() || null);
+}
+
+function basePayload(input: {
+	context: RuntimeStateContext;
+	previous: Record<string, unknown>;
+	state: RuntimeState;
+	now: string;
+	source: string;
+	event: string;
+	reason: string | null;
+}): Record<string, unknown> {
+	return {
+		schema_version: 1,
+		session_id: process.env[SKC_COORDINATOR_SESSION_ID_ENV]?.trim() || input.context.sessionId,
+		state: input.state,
+		ready_for_input: input.state === "completed" || input.state === "ready_for_input",
+		updated_at: input.now,
+		current_turn_id: typeof input.previous.current_turn_id === "string" ? input.previous.current_turn_id : null,
+		last_turn_id: typeof input.previous.last_turn_id === "string" ? input.previous.last_turn_id : null,
+		live: input.state === "running",
+		reason: input.reason,
+		source: input.source,
+		event: input.event,
+		cwd: input.context.cwd,
+		workdir: input.context.cwd,
+		branch: branchForContext(input.context),
+		session_file: input.context.sessionFile ?? null,
+	};
+}
+function publicSafeErrorMessage(message: string): string {
+	const normalized = message.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ").trim();
+	if (normalized.length <= MAX_PUBLIC_ERROR_MESSAGE_LENGTH) return normalized;
+	return `${normalized.slice(0, MAX_PUBLIC_ERROR_MESSAGE_LENGTH)}…`;
+}
+
+function errorMessageForPostmortem(reason: postmortem.Reason): string {
+	return publicSafeErrorMessage(`SKC process cleanup ran for ${reason}`);
+}
+
+function numericProcessExitCode(defaultCode: number | null): number | null {
+	return typeof process.exitCode === "number" ? process.exitCode : defaultCode;
+}
+
+function postmortemExitDetails(reason: postmortem.Reason): {
+	state: RuntimeState;
+	reason: string;
+	exitKind: string;
+	exitCode: number | null;
+	signal: string | null;
+	error?: { code: string; message: string; recoverable: true };
+} {
+	if (reason === postmortem.Reason.EXIT || reason === postmortem.Reason.MANUAL) {
+		const exitCode = numericProcessExitCode(0) ?? 0;
+		const state: RuntimeState = exitCode === 0 ? "completed" : "errored";
+		return {
+			state,
+			reason: reason === postmortem.Reason.EXIT ? "process_exit" : "manual_cleanup",
+			exitKind: reason,
+			exitCode,
+			signal: null,
+			...(state === "errored"
+				? {
+						error: {
+							code: "process_exit",
+							message: publicSafeErrorMessage(`SKC process exited with code ${exitCode}`),
+							recoverable: true,
+						},
+					}
+				: {}),
+		};
+	}
+	const signalByReason: Partial<Record<postmortem.Reason, string>> = {
+		[postmortem.Reason.SIGINT]: "SIGINT",
+		[postmortem.Reason.SIGTERM]: "SIGTERM",
+		[postmortem.Reason.SIGHUP]: "SIGHUP",
+	};
+	return {
+		state: "errored",
+		reason,
+		exitKind: reason,
+		exitCode: numericProcessExitCode(null),
+		signal: signalByReason[reason] ?? null,
+		error: { code: reason, message: errorMessageForPostmortem(reason), recoverable: true },
+	};
+}
+
+function writeStateFileSync(stateFile: string, payload: Record<string, unknown>): void {
+	fsSync.mkdirSync(path.dirname(stateFile), { recursive: true });
+	fsSync.writeFileSync(stateFile, `${JSON.stringify(payload, null, 2)}\n`);
+}
+
+async function writeStateFile(stateFile: string, payload: Record<string, unknown>): Promise<void> {
+	await fs.mkdir(path.dirname(stateFile), { recursive: true });
+	await Bun.write(stateFile, `${JSON.stringify(payload, null, 2)}\n`);
+}
+
 export async function persistCoordinatorRuntimeStateFromEvent(
 	event: RuntimeStateEvent,
 	context: RuntimeStateContext,
@@ -136,42 +255,66 @@ export async function persistCoordinatorRuntimeStateFromEvent(
 	const state = stateForEvent(event);
 	if (!state) return;
 	const now = new Date().toISOString();
-	let previous: Record<string, unknown> = {};
-	try {
-		previous = JSON.parse(await Bun.file(stateFile).text()) as Record<string, unknown>;
-	} catch {
-		previous = {};
-	}
+	const previous = readPreviousPayload(stateFile);
 	const finalResponse = finalResponseForEvent(event);
 	const payload = {
-		schema_version: 1,
-		session_id: process.env[SKC_COORDINATOR_SESSION_ID_ENV]?.trim() || context.sessionId,
-		state,
-		ready_for_input: state === "completed" || state === "ready_for_input",
-		updated_at: now,
-		current_turn_id: typeof previous.current_turn_id === "string" ? previous.current_turn_id : null,
-		last_turn_id: typeof previous.last_turn_id === "string" ? previous.last_turn_id : null,
-		live: typeof previous.live === "boolean" ? previous.live : null,
-		reason: null,
-		source: "agent_session_event",
-		event: event.type,
-		cwd: context.cwd,
-		session_file: context.sessionFile ?? null,
+		...basePayload({ context, previous, state, now, source: "agent_session_event", event: event.type, reason: null }),
+		...(state === "completed" || state === "errored" ? { ended_at: now } : {}),
 		...(finalResponse ? { final_response: finalResponse } : {}),
 		...(state === "errored"
 			? {
 					error: {
 						code: "agent_error",
-						message: lastAssistant(event.messages)?.errorMessage ?? "agent_error",
+						message: publicSafeErrorMessage(lastAssistant(event.messages)?.errorMessage ?? "agent_error"),
 						recoverable: true,
 					},
 				}
 			: {}),
 	};
 	try {
-		await fs.mkdir(path.dirname(stateFile), { recursive: true });
-		await Bun.write(stateFile, `${JSON.stringify(payload, null, 2)}\n`);
+		await writeStateFile(stateFile, payload);
 	} catch (error) {
 		logger.warn("Failed to persist coordinator runtime state", { error: String(error), stateFile });
 	}
 }
+
+export function persistCoordinatorRuntimeStateFromPostmortem(
+	reason: postmortem.Reason,
+	context: RuntimeStateContext,
+): void {
+	const stateFile = process.env[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim();
+	if (!stateFile) return;
+	const previous = readPreviousPayload(stateFile);
+	if (shouldPreserveTerminalPayload(previous as RuntimeStateSidecarPayload)) return;
+	const now = new Date().toISOString();
+	const details = postmortemExitDetails(reason);
+	const payload = {
+		...basePayload({
+			context,
+			previous,
+			state: details.state,
+			now,
+			source: "process_postmortem",
+			event: "process_exit",
+			reason: details.reason,
+		}),
+		ended_at: now,
+		detected_at: now,
+		exit_kind: details.exitKind,
+		exit_code: details.exitCode,
+		signal: details.signal,
+		...(details.error ? { error: details.error } : {}),
+	};
+	try {
+		writeStateFileSync(stateFile, payload);
+	} catch (error) {
+		logger.warn("Failed to persist coordinator runtime state during postmortem", { error: String(error), stateFile });
+	}
+}
+
+export function registerCoordinatorRuntimeStateFinalizer(context: RuntimeStateContext): () => void {
+	if (!process.env[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim()) return () => {};
+	return postmortem.register("coordinator-runtime-state", reason => {
+		persistCoordinatorRuntimeStateFromPostmortem(reason, context);
+	});
+}

package/src/skc-runtime/state-runtime.ts

@@ -847,11 +847,14 @@ async function writeJsonAtomic(
 			forced: options?.force ?? false,
 		},
 	});
-	// `writeResult.revision` is computed inside the writer lock, so it is the revision this
-	// write actually owns. Prefer it over a post-lock file re-read, which a concurrent writer
-	// could have advanced before the read — that race could otherwise let this payload be
-	// published with another writer's newer revision.
-	return { warning, stamped: (await readJsonFile(filePath)) ?? {}, revision: writeResult.revision };
+	// `writeResult.stamped` and `.revision` are computed inside the writer lock, so they are
+	// the envelope/revision this write actually owns. Never post-lock re-read here: a concurrent
+	// writer could advance the file before that read and make this payload publish another
+	// writer's newer revision into the derived active-state cache.
+	if (!writeResult.written || !isPlainObject(writeResult.stamped)) {
+		throw new Error(`state writer did not return a stamped workflow envelope for ${filePath}`);
+	}
+	return { warning, stamped: writeResult.stamped, revision: writeResult.revision };
 }
 
 function parseFieldsFlag(args: readonly string[]): StateProjectionField[] | undefined {

package/src/skc-runtime/state-writer.ts

@@ -99,7 +99,7 @@ export interface GuardedStateWriterOptions extends StateWriterOptions {
 }
 
 export type GuardedWriteResult =
-	| { path: string; written: true; revision: number }
+	| { path: string; written: true; revision: number; stamped: unknown }
 	| { path: string; written: false; reason: "stale-skip"; revision: number };
 
 export interface StateWriterOptions {
@@ -511,7 +511,7 @@ async function writeGuardedResolvedJsonAtomic(
 				const next = stampStateRevision(withWorkflowReceipt(value, buildReceipt(options)), currentRevision + 1);
 				await atomicWrite(filePath, jsonText(next));
 				await maybeAudit(filePath, options);
-				return { path: filePath, written: true, revision: currentRevision + 1 };
+				return { path: filePath, written: true, revision: currentRevision + 1, stamped: next };
 			}
 
 			const incomingSourceRevision =
@@ -526,7 +526,7 @@ async function writeGuardedResolvedJsonAtomic(
 			);
 			await atomicWrite(filePath, jsonText(next));
 			await maybeAudit(filePath, options);
-			return { path: filePath, written: true, revision: currentRevision + 1 };
+			return { path: filePath, written: true, revision: currentRevision + 1, stamped: next };
 		},
 		options.lock,
 	);
@@ -574,7 +574,7 @@ export async function writeGuardedWorkflowEnvelopeAtomic(
 				}
 				await atomicWrite(filePath, jsonText(next));
 				await maybeAudit(filePath, options);
-				return { path: filePath, written: true, revision: currentRevision + 1 };
+				return { path: filePath, written: true, revision: currentRevision + 1, stamped: next };
 			}
 
 			const incomingSourceRevision =
@@ -599,7 +599,7 @@ export async function writeGuardedWorkflowEnvelopeAtomic(
 			}
 			await atomicWrite(filePath, jsonText(next));
 			await maybeAudit(filePath, options);
-			return { path: filePath, written: true, revision: currentRevision + 1 };
+			return { path: filePath, written: true, revision: currentRevision + 1, stamped: next };
 		},
 		options.lock,
 	);