@sayknow-cli/coding-agent 0.3.11 → 0.3.12

package/src/session/agent-session.ts

@@ -26,6 +26,7 @@ import {
 	type AgentMessage,
 	type AgentState,
 	type AgentTool,
+	assertImagePlaceholdersHavePayload,
 	resolveTelemetry,
 	type StablePrefixSnapshot,
 	ThinkingLevel,
@@ -151,6 +152,7 @@ import { onAppendOnlyModeChanged } from "../config/settings";
 import { RawSseDebugBuffer } from "../debug/raw-sse-buffer";
 import { loadCapability } from "../discovery";
 import { expandApplyPatchToEntries, normalizeDiff, normalizeToLF, ParseError, previewPatch, stripBom } from "../edit";
+import { MAX_EDIT_FILE_BYTES } from "../edit/read-file";
 import { disposeVmContextsByOwner } from "../eval/js/context-manager";
 import {
 	disposeKernelSessionsByOwner,
@@ -360,6 +362,11 @@ export interface AsyncJobSnapshot {
 // Types
 // ============================================================================
 
+export interface RetainedMemorySample {
+	tuiChatChildren?: number;
+	tuiCachedRenderBytes?: number;
+}
+
 export interface AgentSessionConfig {
 	agent: Agent;
 	sessionManager: SessionManager;
@@ -439,6 +446,8 @@ export interface AgentSessionConfig {
 	 * **MUST NOT** dispose it on their own teardown.
 	 */
 	ownedAsyncJobManager?: AsyncJobManager;
+	/** Cheap TUI retained-memory counters; absent for headless sessions. */
+	retainedMemorySampler?: () => RetainedMemorySample;
 	/**
 	 * MCPManager whose lifecycle this session owns (top-level sessions that
 	 * connected plugin-bundle MCP servers). Only the owned manager is
@@ -1084,6 +1093,68 @@ export function buildContextInjectionSignature(kind: string, parts: readonly str
 	}
 	return hash.digest("base64url");
 }
+
+const STREAMING_EDIT_FILE_CACHE_MAX_ENTRIES = 16;
+const STREAMING_EDIT_FILE_CACHE_MAX_TOTAL_BYTES = 32 * 1024 * 1024;
+
+type StreamingEditFileCacheEntry = {
+	content: string;
+	bytes: number;
+};
+
+export class StreamingEditFileCache {
+	#entries = new Map<string, StreamingEditFileCacheEntry>();
+	#totalBytes = 0;
+
+	get(path: string): string | undefined {
+		const entry = this.#entries.get(path);
+		if (entry === undefined) return undefined;
+		this.#entries.delete(path);
+		this.#entries.set(path, entry);
+		return entry.content;
+	}
+
+	set(path: string, content: string): void {
+		const bytes = Buffer.byteLength(content, "utf8");
+		if (bytes > MAX_EDIT_FILE_BYTES || bytes > STREAMING_EDIT_FILE_CACHE_MAX_TOTAL_BYTES) {
+			this.delete(path);
+			return;
+		}
+
+		this.delete(path);
+		while (
+			this.#entries.size >= STREAMING_EDIT_FILE_CACHE_MAX_ENTRIES ||
+			this.#totalBytes + bytes > STREAMING_EDIT_FILE_CACHE_MAX_TOTAL_BYTES
+		) {
+			const oldestPath = this.#entries.keys().next().value;
+			if (oldestPath === undefined) break;
+			this.delete(oldestPath);
+		}
+
+		this.#entries.set(path, { content, bytes });
+		this.#totalBytes += bytes;
+	}
+
+	delete(path: string): void {
+		const entry = this.#entries.get(path);
+		if (entry === undefined) return;
+		this.#entries.delete(path);
+		this.#totalBytes -= entry.bytes;
+	}
+
+	clear(): void {
+		this.#entries.clear();
+		this.#totalBytes = 0;
+	}
+
+	has(path: string): boolean {
+		return this.#entries.has(path);
+	}
+
+	get totalBytes(): number {
+		return this.#totalBytes;
+	}
+}
 export class AgentSession {
 	readonly agent: Agent;
 	readonly sessionManager: SessionManager;
@@ -1148,6 +1219,7 @@ export class AgentSession {
 	#compactionAbortController: AbortController | undefined = undefined;
 	#autoCompactionAbortController: AbortController | undefined = undefined;
 	#resourceSampler: () => EmergencyCompactionSample = () => this.#defaultResourceSample();
+	#retainedMemorySampler: (() => RetainedMemorySample) | undefined;
 	#prePromptContextCheckPromise: Promise<void> | undefined = undefined;
 
 	// Branch summarization state
@@ -1321,7 +1393,7 @@ export class AgentSession {
 
 	#streamingEditPrecheckedToolCallIds = new Set<string>();
 
-	#streamingEditFileCache = new Map<string, string>();
+	#streamingEditFileCache = new StreamingEditFileCache();
 	readonly streamingEditDebugCounters = {
 		guardRuns: 0,
 		processedChars: 0,
@@ -1447,6 +1519,7 @@ export class AgentSession {
 		// Power assertions are taken per turn (see #beginInFlight); nothing acquired here.
 		this.#evalKernelOwnerId = config.evalKernelOwnerId ?? `agent-session:${Snowflake.next()}`;
 		this.#ownedAsyncJobManager = config.ownedAsyncJobManager;
+		this.#retainedMemorySampler = config.retainedMemorySampler;
 		this.#ownedMcpManager = config.ownedMcpManager;
 		this.#scopedModels = config.scopedModels ?? [];
 		this.#thinkingLevel = config.thinkingLevel;
@@ -3170,7 +3243,31 @@ export class AgentSession {
 		// which is the optional patch-preview verification gated by
 		// edit.streamingAbort. Skip the read when the setting is off.
 		if (this.settings.get("edit.streamingAbort")) {
-			this.#ensureFileCache(streamingEdit.resolvedPath);
+			// Fire-and-forget async priming: toolcall deltas arrive on the hot
+			// stream path, so never block it on filesystem I/O. The abort-check
+			// path (#maybeAbortStreamingEdit) still falls back to the sync read
+			// if priming hasn't completed by the time removed lines appear.
+			void this.#preCacheFileAsync(streamingEdit.resolvedPath);
+		}
+	}
+
+	#streamingEditPrecachePending = new Set<string>();
+	async #preCacheFileAsync(resolvedPath: string): Promise<void> {
+		if (this.#streamingEditFileCache.has(resolvedPath)) return;
+		if (this.#streamingEditPrecachePending.has(resolvedPath)) return;
+		this.#streamingEditPrecachePending.add(resolvedPath);
+		try {
+			const stat = await fs.promises.stat(resolvedPath);
+			if (stat.size > MAX_EDIT_FILE_BYTES) return;
+
+			const rawText = await fs.promises.readFile(resolvedPath, "utf-8");
+			if (this.#streamingEditFileCache.has(resolvedPath)) return;
+			const { text } = stripBom(rawText);
+			this.#streamingEditFileCache.set(resolvedPath, normalizeToLF(text));
+		} catch {
+			// Don't cache on read errors (including ENOENT) - let the edit tool handle them
+		} finally {
+			this.#streamingEditPrecachePending.delete(resolvedPath);
 		}
 	}
 
@@ -3178,6 +3275,9 @@ export class AgentSession {
 		if (this.#streamingEditFileCache.has(resolvedPath)) return;
 
 		try {
+			const stat = fs.statSync(resolvedPath);
+			if (stat.size > MAX_EDIT_FILE_BYTES) return;
+
 			const rawText = fs.readFileSync(resolvedPath, "utf-8");
 			const { text } = stripBom(rawText);
 			this.#streamingEditFileCache.set(resolvedPath, normalizeToLF(text));
@@ -5298,6 +5398,7 @@ export class AgentSession {
 
 		// Expand file-based prompt templates if requested
 		const expandedText = expandPromptTemplates ? expandPromptTemplate(text, [...this.#promptTemplates]) : text;
+		assertImagePlaceholdersHavePayload(expandedText, options?.images);
 		const workflowIntentDiff = options?.synthetic ? null : buildWorkflowIntentDiff(expandedText);
 
 		// If streaming, queue via steer() or followUp() based on option
@@ -5784,6 +5885,7 @@ export class AgentSession {
 		}
 
 		const expandedText = expandPromptTemplate(text, [...this.#promptTemplates]);
+		assertImagePlaceholdersHavePayload(expandedText, images);
 		await this.#queueSteer(expandedText, images);
 	}
 
@@ -5800,6 +5902,7 @@ export class AgentSession {
 		}
 
 		const expandedText = expandPromptTemplate(text, [...this.#promptTemplates]);
+		assertImagePlaceholdersHavePayload(expandedText, images);
 		await this.#queueFollowUp(expandedText, images, {
 			forceOneAtATime: options?.followUpQueuePolicy === "sequential",
 		});
@@ -5809,6 +5912,7 @@ export class AgentSession {
 	 * Internal: Queue a steering message (already expanded, no extension command check).
 	 */
 	async #queueSteer(text: string, images?: ImageContent[]): Promise<void> {
+		assertImagePlaceholdersHavePayload(text, images);
 		const displayText = text || (images && images.length > 0 ? "[Image]" : "");
 		this.#steeringMessages.push(this.#createQueuedDisplayEntry(displayText));
 		const content: (TextContent | ImageContent)[] = [{ type: "text", text }];
@@ -5840,6 +5944,7 @@ export class AgentSession {
 	 * Internal: Queue a follow-up message (already expanded, no extension command check).
 	 */
 	async #queueFollowUp(text: string, images?: ImageContent[], options?: { forceOneAtATime?: boolean }): Promise<void> {
+		assertImagePlaceholdersHavePayload(text, images);
 		const displayText = text || (images && images.length > 0 ? "[Image]" : "");
 		this.#followUpMessages.push(this.#createQueuedDisplayEntry(displayText));
 		const content: (TextContent | ImageContent)[] = [{ type: "text", text }];
@@ -7732,9 +7837,14 @@ export class AgentSession {
 		this.#resourceSampler = sampler;
 	}
 
+	setRetainedMemorySampler(sampler: (() => RetainedMemorySample) | undefined): void {
+		this.#retainedMemorySampler = sampler;
+	}
+
 	#defaultResourceSample(): EmergencyCompactionSample {
 		let providerBytes = 0;
 		let imageBytes = 0;
+		const retainedMemory = this.#retainedMemorySampler?.() ?? {};
 		for (const message of this.state.messages) {
 			const content = (message as { content?: unknown }).content;
 			if (typeof content === "string") {
@@ -7756,6 +7866,10 @@ export class AgentSession {
 			providerBytes,
 			messageCount: this.state.messages.length,
 			imageBytes,
+			sessionResidentImageBytes: this.sessionManager.getResidentImageBytes(),
+			materializedResidentBytes: this.#streamingEditFileCache.totalBytes,
+			tuiChatChildren: retainedMemory.tuiChatChildren ?? 0,
+			tuiCachedRenderBytes: retainedMemory.tuiCachedRenderBytes ?? 0,
 		};
 	}
 
@@ -8071,7 +8185,7 @@ export class AgentSession {
 			attribution: "agent",
 			timestamp: Date.now(),
 		});
-		this.#scheduleAgentContinue({ generation: this.#promptGeneration });
+		this.#scheduleAgentContinue({ skipCompactionCheck: true });
 	}
 
 	/**

package/src/session/session-manager.ts

@@ -45,8 +45,6 @@ import {
 	MemoryBlobStore,
 	parseBlobRef,
 	ResidentBlobMissingError,
-	resolveImageData,
-	resolveImageDataUrl,
 	resolveResidentImageDataSync,
 	resolveResidentImageDataUrlSync,
 	resolveTextBlobSync,
@@ -973,47 +971,46 @@ export async function loadEntriesFromFile(
 }
 
 /**
- * Resolve blob references in loaded entries, restoring both session image blocks and persisted
- * provider image URLs back to the inline data expected by downstream transports. Mutates entries in place.
+ * Convert legacy persisted blob references in loaded entries into resident sentinels.
+ * Images then materialize lazily at provider/display/export chokepoints instead of
+ * pinning every historical base64 string for the lifetime of a resumed session.
  */
 function hasImageUrl(value: unknown): value is { image_url: string | { url?: string } } {
 	return typeof value === "object" && value !== null && "image_url" in value;
 }
 
-async function resolvePersistedBlobRefs(value: unknown, blobStore: BlobStore, key?: string): Promise<void> {
+function residentizePersistedBlobRefs(value: unknown, key?: string): void {
 	if (Array.isArray(value)) {
-		await Promise.all(value.map(item => resolvePersistedBlobRefs(item, blobStore, key)));
+		for (const item of value) residentizePersistedBlobRefs(item, key);
 		return;
 	}
 
 	if (typeof value !== "object" || value === null) return;
 
 	if (isImageBlock(value) && isBlobRef(value.data)) {
-		value.data = await resolveImageData(blobStore, value.data);
+		value.data = residentBlobSentinel("imageData", value.data) as unknown as string;
 	}
 
 	if (hasImageUrl(value)) {
 		if (typeof value.image_url === "string" && isBlobRef(value.image_url)) {
-			value.image_url = await resolveImageDataUrl(blobStore, value.image_url);
+			value.image_url = residentBlobSentinel("imageUrl", value.image_url) as unknown as string;
 		} else if (
 			typeof value.image_url === "object" &&
 			value.image_url !== null &&
 			typeof value.image_url.url === "string" &&
 			isBlobRef(value.image_url.url)
 		) {
-			value.image_url.url = await resolveImageDataUrl(blobStore, value.image_url.url);
+			value.image_url.url = residentBlobSentinel("imageUrl", value.image_url.url) as unknown as string;
 		}
 	}
 
-	await Promise.all(
-		Object.entries(value).map(async ([childKey, item]) => {
-			if (childKey === "data" && typeof item === "string" && isBlobRef(item) && key !== TEXT_CONTENT_KEY) {
-				(value as Record<string, unknown>)[childKey] = await resolveImageDataUrl(blobStore, item);
-				return;
-			}
-			await resolvePersistedBlobRefs(item, blobStore, childKey);
-		}),
-	);
+	for (const [childKey, item] of Object.entries(value)) {
+		if (childKey === "data" && typeof item === "string" && isBlobRef(item) && key !== TEXT_CONTENT_KEY) {
+			(value as Record<string, unknown>)[childKey] = residentBlobSentinel("imageUrl", item);
+			continue;
+		}
+		residentizePersistedBlobRefs(item, childKey);
+	}
 }
 
 /**
@@ -1035,28 +1032,13 @@ async function runWithConcurrency(tasks: Array<() => Promise<void>>, limit: numb
 	await Promise.all(Array.from({ length: workerCount }, () => worker()));
 }
 
-async function resolveBlobRefsInEntries(entries: FileEntry[], blobStore: BlobStore): Promise<void> {
+async function resolveBlobRefsInEntries(entries: FileEntry[], _blobStore: BlobStore): Promise<void> {
 	const tasks: Array<() => Promise<void>> = [];
 
 	for (const entry of entries) {
 		if (entry.type === "session") continue;
-
-		let contentArray: unknown[] | undefined;
-		if (entry.type === "message" && "content" in entry.message && Array.isArray(entry.message.content)) {
-			contentArray = entry.message.content;
-		} else if (entry.type === "custom_message" && Array.isArray(entry.content)) {
-			contentArray = entry.content;
-		}
-
 		tasks.push(async () => {
-			if (contentArray) {
-				for (const block of contentArray) {
-					if (isImageBlock(block) && isBlobRef(block.data)) {
-						block.data = await resolveImageData(blobStore, block.data);
-					}
-				}
-			}
-			await resolvePersistedBlobRefs(entry, blobStore);
+			residentizePersistedBlobRefs(entry);
 		});
 	}
 
@@ -1314,6 +1296,33 @@ function containsResidentSentinel(value: unknown, seen = new WeakSet<object>()):
 	return false;
 }
 
+function containsResidentImageSentinel(value: unknown, seen = new WeakSet<object>()): boolean {
+	if (value === null || value === undefined || typeof value !== "object") return false;
+	if (isResidentBlobSentinel(value)) return value.kind === "imageUrl" || value.kind === "imageData";
+	if (seen.has(value)) return false;
+	seen.add(value);
+	if (Array.isArray(value)) return value.some(item => containsResidentImageSentinel(item, seen));
+	for (const child of Object.values(value)) {
+		if (containsResidentImageSentinel(child, seen)) return true;
+	}
+	return false;
+}
+
+function collectResidentImageRefs(value: unknown, refs: Set<string>, seen = new WeakSet<object>()): void {
+	if (value === null || value === undefined || typeof value !== "object") return;
+	if (isResidentBlobSentinel(value)) {
+		if (value.kind === "imageUrl" || value.kind === "imageData") refs.add(value.ref);
+		return;
+	}
+	if (seen.has(value)) return;
+	seen.add(value);
+	if (Array.isArray(value)) {
+		for (const item of value) collectResidentImageRefs(item, refs, seen);
+		return;
+	}
+	for (const child of Object.values(value)) collectResidentImageRefs(child, refs, seen);
+}
+
 /**
  * Recursively truncate large strings in an object for session persistence.
  * - Truncates any oversized string fields (key-agnostic)
@@ -4148,6 +4157,22 @@ export class SessionManager {
 		return entry ? materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), new Map()) : undefined;
 	}
 
+	getResidentImageBytes(): number {
+		const refs = new Set<string>();
+		for (const entry of this.#fileEntries) collectResidentImageRefs(entry, refs);
+		let bytes = 0;
+		for (const ref of refs) {
+			const hash = parseBlobRef(ref);
+			if (!hash) continue;
+			try {
+				bytes += fs.statSync(path.join(this.#residentImageBlobStore.dir, hash)).size;
+			} catch (err) {
+				if (!isEnoent(err)) throw err;
+			}
+		}
+		return bytes;
+	}
+
 	/**
 	 * Get the most recent model role from the current session path.
 	 * Returns undefined if no model change has been recorded.
@@ -4571,11 +4596,14 @@ export class SessionManager {
 		}
 		this.#materializedEntriesCachePopulateCount++;
 		const resolvedTextBlobCache = new Map<string, string>();
-		const materializedEntries = this.#fileEntries
-			.filter((e): e is SessionEntry => e.type !== "session")
-			.map(entry => materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), resolvedTextBlobCache));
-		this.#materializedEntriesCache = materializedEntries;
-		this.#materializedEntriesRevision = this.#entryRevision;
+		const sourceEntries = this.#fileEntries.filter((e): e is SessionEntry => e.type !== "session");
+		const materializedEntries = sourceEntries.map(entry =>
+			materializeResidentEntryForReadSync(entry, this.#residentBlobStores(), resolvedTextBlobCache),
+		);
+		if (!sourceEntries.some(entry => containsResidentImageSentinel(entry))) {
+			this.#materializedEntriesCache = materializedEntries;
+			this.#materializedEntriesRevision = this.#entryRevision;
+		}
 		return materializedEntries;
 	}
 

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

@@ -242,9 +242,12 @@ function assertSafePathComponent(value: string, label: string): void {
 		throw new StateCommandError(2, `invalid path component for --${label}: ${value}`);
 	}
 }
+function isKnownMode(mode: string): mode is CanonicalSkcWorkflowSkill {
+	return KNOWN_MODES.includes(mode);
+}
 
 function assertKnownMode(mode: string): asserts mode is CanonicalSkcWorkflowSkill {
-	if (!KNOWN_MODES.includes(mode)) {
+	if (!isKnownMode(mode)) {
 		throw new StateCommandError(2, `unknown --mode: ${mode}. Expected one of: ${KNOWN_MODES.join(", ")}.`);
 	}
 }
@@ -1580,14 +1583,15 @@ async function handleHandoff(
 	if (!calleeRaw) {
 		throw new StateCommandError(2, "skc state handoff requires --to <callee>");
 	}
-	assertKnownMode(calleeRaw);
-	const callee = calleeRaw as CanonicalSkcWorkflowSkill;
+	assertSafePathComponent(calleeRaw, "to");
+	const callee = calleeRaw;
+	const calleeIsWorkflow = isKnownMode(callee);
 	if (callee === caller) {
 		throw new StateCommandError(2, `skc state handoff: --to must differ from caller (both are "${caller}")`);
 	}
 
 	const callerPath = modeStateFile(cwd, caller, sessionId);
-	const calleePath = modeStateFile(cwd, callee, sessionId);
+	const calleePath = calleeIsWorkflow ? modeStateFile(cwd, callee, sessionId) : undefined;
 	const forced = hasFlag(args, "--force");
 	const callerRead = await readExistingStateForMutation(callerPath);
 	if (callerRead.kind === "corrupt" && !forced) {
@@ -1602,15 +1606,7 @@ async function handleHandoff(
 			`skc state ${caller} handoff: caller is not active (no mode-state file at ${callerPath})`,
 		);
 	}
-	const calleeRead = await readExistingStateForMutation(calleePath);
-	if (calleeRead.kind === "corrupt" && !forced) {
-		throw new StateCommandError(
-			2,
-			`existing state for ${callee} is corrupt or tampered (${calleeRead.error}); use --force to overwrite`,
-		);
-	}
 	const existingCaller = callerRead.kind === "valid" ? callerRead.value : {};
-	const existingCallee = calleeRead.kind === "valid" ? calleeRead.value : {};
 
 	const handoffAt = nowIso();
 	const mutationId = `${caller}:handoff:${callee}:${handoffAt}`;
@@ -1623,6 +1619,103 @@ async function handleHandoff(
 		nowIso: handoffAt,
 		mutationId,
 	});
+
+	// Runtime callees have no native mode-state to clear later, so do not
+	// persist them as active-state entries; the prompt observer tracks them
+	// in memory the same way direct `/skill:<runtime>` invocation does.
+	if (!calleeIsWorkflow) {
+		const normalizedCaller =
+			caller === "deep-interview"
+				? (normalizeDeepInterviewEnvelope(migrateWorkflowState(existingCaller, caller).state) as Record<
+						string,
+						unknown
+					>)
+				: migrateWorkflowState(existingCaller, caller).state;
+		const mergedCallerState: Record<string, unknown> = {
+			...normalizedCaller,
+			skill: caller,
+			version: WORKFLOW_STATE_VERSION,
+			active: false,
+			current_phase: "handoff",
+			handoff_to: callee,
+			handoff_at: handoffAt,
+			updated_at: handoffAt,
+			receipt: callerReceipt,
+		};
+		const force = hasFlag(args, "--force");
+		await beginWorkflowTransactionJournal({
+			cwd,
+			sessionId,
+			mutationId,
+			caller,
+			paths: [callerPath, activeStateFile(cwd, sessionId)],
+		});
+		const callerWrite = await writeJsonAtomic(cwd, callerPath, mergedCallerState, "handoff", {
+			sessionId,
+			skill: caller,
+			mutationId,
+			force,
+			fromPhase: typeof existingCaller.current_phase === "string" ? existingCaller.current_phase : undefined,
+			toPhase: "handoff",
+		});
+		await updateWorkflowTransactionJournal(cwd, sessionId, mutationId, { steps: ["caller-mode-state"] });
+		if (callerWrite.warning) process.stderr.write(`${callerWrite.warning}\n`);
+		const stampedCallerReceipt = isPlainObject(callerWrite.stamped.receipt) ? callerWrite.stamped.receipt : {};
+		await syncSkillActiveState({
+			cwd,
+			skill: caller,
+			active: false,
+			phase: "handoff",
+			sessionId,
+			threadId,
+			turnId,
+			source: "skc-state-cli",
+			hud: buildHudForMode(caller, mergedCallerState),
+			handoff_to: callee,
+			handoff_at: handoffAt,
+			receipt: callerReceipt,
+		});
+		await updateWorkflowTransactionJournal(cwd, sessionId, mutationId, {
+			steps: ["caller-mode-state", "active-state"],
+		});
+		await completeWorkflowTransactionJournal(cwd, sessionId, mutationId);
+		await touchStateActivityMarker(cwd, sessionId, callerPath);
+		return {
+			status: 0,
+			stdout: renderCliWriteReceipt({
+				ok: true,
+				from: caller,
+				to: callee,
+				handoff_at: handoffAt,
+				phases: {
+					from: mergedCallerState.current_phase,
+				},
+				receipts: {
+					from: {
+						mutation_id: stampedCallerReceipt.mutation_id,
+						status: stampedCallerReceipt.status,
+						content_sha256: stampedCallerReceipt.content_sha256,
+					},
+				},
+				paths: {
+					from: callerPath,
+					active_state: activeStateFile(cwd, sessionId),
+				},
+			}),
+		};
+	}
+
+	if (!calleePath) {
+		throw new StateCommandError(2, `skc state handoff failed to resolve workflow callee path for ${callee}`);
+	}
+	const calleeRead = await readExistingStateForMutation(calleePath);
+	if (calleeRead.kind === "corrupt" && !forced) {
+		throw new StateCommandError(
+			2,
+			`existing state for ${callee} is corrupt or tampered (${calleeRead.error}); use --force to overwrite`,
+		);
+	}
+	const existingCallee = calleeRead.kind === "valid" ? calleeRead.value : {};
 	const calleeReceipt = buildWorkflowStateReceipt({
 		cwd,
 		skill: callee,

package/src/skc-runtime/workflow-manifest.generated.json

@@ -127,15 +127,9 @@
         "appliesToVerbs": [
           "handoff"
         ],
-        "enumValues": [
-          "deep-interview",
-          "ralplan",
-          "ultragoal",
-          "team"
-        ],
         "name": "to",
         "required": true,
-        "type": "enum"
+        "type": "string"
       },
       {
         "appliesToVerbs": [
@@ -529,15 +523,9 @@
         "appliesToVerbs": [
           "handoff"
         ],
-        "enumValues": [
-          "deep-interview",
-          "ralplan",
-          "ultragoal",
-          "team"
-        ],
         "name": "to",
         "required": true,
-        "type": "enum"
+        "type": "string"
       },
       {
         "appliesToVerbs": [
@@ -913,15 +901,9 @@
         "appliesToVerbs": [
           "handoff"
         ],
-        "enumValues": [
-          "deep-interview",
-          "ralplan",
-          "ultragoal",
-          "team"
-        ],
         "name": "to",
         "required": true,
-        "type": "enum"
+        "type": "string"
       },
       {
         "appliesToVerbs": [
@@ -1357,15 +1339,9 @@
         "appliesToVerbs": [
           "handoff"
         ],
-        "enumValues": [
-          "deep-interview",
-          "ralplan",
-          "ultragoal",
-          "team"
-        ],
         "name": "to",
         "required": true,
-        "type": "enum"
+        "type": "string"
       },
       {
         "appliesToVerbs": [

package/src/skc-runtime/workflow-manifest.ts

@@ -72,13 +72,7 @@ const COMMON_TYPED_ARGS: TypedArgSpec[] = [
 	{ name: "session-id", type: "string", appliesToVerbs: [...STATE_VERBS, "kickoff", "write-spec", "write-artifact"] },
 	{ name: "thread-id", type: "string", appliesToVerbs: ["write", "clear", "handoff"] },
 	{ name: "turn-id", type: "string", appliesToVerbs: ["write", "clear", "handoff"] },
-	{
-		name: "to",
-		type: "enum",
-		enumValues: [...CANONICAL_SKC_WORKFLOW_SKILLS],
-		required: true,
-		appliesToVerbs: ["handoff"],
-	},
+	{ name: "to", type: "string", required: true, appliesToVerbs: ["handoff"] },
 	{ name: "replace", type: "boolean", appliesToVerbs: ["write"] },
 	{ name: "force", type: "boolean", appliesToVerbs: ["write", "clear", "handoff"] },
 	{ name: "skill", type: "enum", enumValues: [...CANONICAL_SKC_WORKFLOW_SKILLS], appliesToVerbs: ["doctor"] },