@llblab/pi-kit 0.16.0 → 0.17.0

package/node_modules/@llblab/pi-state-flow/docs/usage.md

@@ -20,7 +20,7 @@ State Flow does not undo tool effects. After interruption or returning to an old
 
 Native fork replacement copies the source session checkpoint, retained patch tail and matching provenance into the new session's own storage. Global/CWD streams and provenance stay current and unchanged. An earlier fork selection copies that point's private state, not the parent's later private work. Parent data/history remain intact; selected enablement is retained, so a stopped source does not become enabled automatically.
 
-The child starts at step zero and a new temporal origin. Its copied tail is preserved, but pre-origin records are not seven past aligned `state[n]` boundaries. The child's own transitions build its hot window; owned checkpoints support normal reload/resume. Parent Stop projection is not inherited, including after child reload.
+The child starts at step zero and a new temporal origin. Its copied tail is preserved, but pre-origin records are not seven past aligned causal boundaries addressable through `effective[n]` or scoped paths. The child's own transitions build its hot window; owned checkpoints support normal reload/resume. Parent Stop projection is not inherited, including after child reload.
 
 Initial copying requires a native fork start event, a regular canonical direct-parent session file, matching CWD/identity, a readable temporal source and an unused child namespace. Missing/unsafe evidence or CAS conflicts leave the copy unavailable rather than importing unrelated or newer private state. Explicit Start can retry an unaccepted copy in the same loaded fork after the cause is corrected.
 
@@ -144,4 +144,4 @@ The agent should use sufficient materialized knowledge before rereading files. R
 
 Knowledge discovery finds regular lowercase `*.md` beneath its configured root, hashes opaque bytes, and skips symlinks. Only confirmed missing Markdown paths within an available root are pruned; external/non-Markdown artifacts and state under a missing whole root are preserved. An unavailable root makes freshness unknown in status. Successful reads of stale ordinary candidates require same-path global compilation; Skill reads require CWD compilation. The runtime owns provenance: model patches cannot write or delete individual freshness fields, including legacy spellings. Existing legacy entries remain readable and semantically editable. Missing freshness evidence means unknown-but-usable, not proof that a source was acquired.
 
-The optional `state-flow-memory` Skill handles explicit bounded curation, required feature/release/project phase-boundary reconciliation, and external promotion. Ordinary handoffs clean only touched and obviously stale visible branches; the Skill supplies the fuller scoped migration procedure when a phase boundary or explicit request earns it. It is not a background maintenance loop. Promotion must verify the destination before removing the only accepted source copy. Artifact/compiler details and model-tool contracts belong in the [architecture](architecture.md#artifact-routing).
+The packaged `state-flow-guide` Skill answers concrete operational questions about reads, patches, inheritance, acquisition, finalization, and recovery without initiating cleanup. The separate `state-flow-memory` Skill handles explicit bounded curation, feature/release/project phase-boundary reconciliation, and external promotion. Ordinary handoffs clean only touched and obviously stale visible branches; neither Skill is a background maintenance loop. Promotion must verify the destination before removing the only accepted source copy. Artifact/compiler details and model-tool contracts belong in the [architecture](architecture.md#artifact-routing).

package/node_modules/@llblab/pi-state-flow/lib/durable.ts

@@ -20,7 +20,7 @@ import {
 } from "./artifact.ts";
 import { canonicalJson, isJsonValue, isObject } from "./json.ts";
 import { validateScopeStream, validateTemporalState, type ScopeStream, type TemporalState } from "./temporal.ts";
-import type { StateScope } from "./state.ts";
+import { migratePreIntentState, type StateScope } from "./state.ts";
 
 const SESSION_KEY_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
 const STATE_FILE = "state.json";
@@ -100,6 +100,7 @@ export function classifyScopeStream(
 	}
 	const temporal = meta?.temporal;
 	if (isObject(temporal) && Object.hasOwn(temporal, "checkpoint") && Array.isArray(temporal.patches)) {
+		checkpoint = migratePreIntentState(checkpoint) ?? checkpoint;
 		const owner = meta?.owner;
 		if (scope === "cwd" && expectedCwd !== undefined
 			&& (!isObject(owner) || Object.keys(owner).join(",") !== "cwd" || owner.cwd !== resolve(expectedCwd))) {
@@ -126,6 +127,10 @@ export function classifyScopeStream(
 	} else if (scope === "cwd" && expectedCwd !== undefined) {
 		throw new Error("State Flow CWD scope identity is missing");
 	}
+	if (isObject(legacyCheckpoint) && isObject(legacyCheckpoint.state)) {
+		const migrated = migratePreIntentState(legacyCheckpoint.state);
+		if (migrated) legacyCheckpoint = { ...legacyCheckpoint, state: migrated };
+	}
 	const stream = { checkpoint: legacyCheckpoint, patches };
 	validateScopeStream(stream, scope);
 	return { kind: "present", stream };

package/node_modules/@llblab/pi-state-flow/lib/extension.ts

@@ -4,27 +4,24 @@ import { StringEnum, Type } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import { assistantToolCallCount, finalizedAssistantResponse, stateFlowProtocol } from "./protocol.ts";
+import { assistantToolCallCount, finalizedAssistantResponse, formatPatchStateArguments, normalizePatchStateArguments, separatedFailure, separatedOutput, stateFlowProtocol } from "./protocol.ts";
 import { createPassiveContinuation, currentRunTrajectory, lazyNavigationHint, passiveContinuationMessages, runtimeContextMessage, syntheticUser, VALIDATION_MESSAGE_TYPE, withoutPrivateValidation, type PassiveContinuation } from "./context.ts";
 import { ArtifactReadTracker } from "./acquisition.ts";
 import { loadStateFlowConfig } from "./config.ts";
 import { createStateFlowTelegramAdapter, type StateFlowTelegramControlResult, type StateFlowTelegramLoader } from "./telegram.ts";
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { isAbsolute, resolve } from "node:path";
 import { SkillReadTracker } from "./skills.ts";
 import { emptySnapshot, migrationFailure, persistableSnapshot, RevisionUnavailableError, type Snapshot } from "./snapshot.ts";
 import { readNativeSessionHeader } from "./continuation.ts";
 import { MissingSessionRuntimeError, SharedScopeRemovalConflictError, TemporalRuntime, type RuntimePublication } from "./runtime.ts";
 import { emptyState, overlayStates, projectStateForModel, type AtomicScopePatches, type MaterializedState, type ScopedStates, type StateScope } from "./state.ts";
 import { commitScopedTransition, stageAtomicScopePatches, stageScopedTransition, validateFinalEligibility, type StagedScopedTransition } from "./transition.ts";
-import { discoverSnapshotData, hasPriorConversation, isNewSession, SNAPSHOT_ENTRY_TYPE } from "./session.ts";
+import { discoverSnapshotData, findAssistantToolBatch, findPassiveStopBoundary, hasPriorConversation, isNewSession, retainsPhysicalSessionProjection, SNAPSHOT_ENTRY_TYPE } from "./session.ts";
 import { compactStatus, detailedStatus, STATUS_KEY, type PendingPublicationDiagnostic, type StatusDiagnostics } from "./status.ts";
 import { completeRun, prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.ts";
 import { recoverSnapshot } from "./recovery.ts";
 import type { RehydrationPhase } from "./rehydration.ts";
-import { resolveRemotePublicationPolicy, serializeRemotePublicationPolicyDocument } from "./publication.ts";
-import { coalescePublicationTarget, createPublicationQueue, type PublicationQueueState } from "./publication.ts";
-import { acquirePublicationWorkerLease, loadPublicationQueue, publicationQueuePath, removePublicationQueue, savePublicationQueue } from "./publication.ts";
-import { runPublicationWorker } from "./publication.ts";
+import { loadPublicationQueue, publicationQueuePath, PublicationWorkerController, resolveRemotePublicationPolicy, serializeRemotePublicationPolicyDocument, type PublicationQueueState } from "./publication.ts";
 import { getKnowledgeRoot, GlobalMarkdownDiscovery } from "./discovery.ts";
 import { canonicalJson, isObject, sameJson } from "./json.ts";
 import { readProjectedState, readStatePath } from "./query.ts";
@@ -35,7 +32,7 @@ import {
 	type SessionAddress,
 } from "./durable.ts";
 import { projectRecentTransitionsWithLimit, RECENT_TRANSITION_LIMIT } from "./history.ts";
-import { appendStateFlowDiagnostic, projectDiagnosticContent, stateFlowLogPath, type StateFlowDiagnosticCategory } from "./logging.ts";
+import { StateFlowDiagnosticWriter, stateFlowLogPath, type DiagnosticExtras, type StateFlowDiagnosticCategory } from "./logging.ts";
 import { isGitCommitAncestor, pushGitCommit, pushGitTarget, resolveGitPushDestination } from "./git.ts";
 import {
 	ORDINARY_ARTIFACT_COMPILER,
@@ -54,64 +51,13 @@ export interface StateFlowExtensionOptions {
 	passive?: { bootstrap?: boolean; tools?: boolean };
 }
 
+export { formatPatchStateArguments, normalizePatchStateArguments };
+
 export const PATCH_STATE_TOOL_NAME = "patch_state";
 export const READ_STATE_TOOL_NAME = "read_state";
 export const MAX_FALLBACK_ATTEMPTS: number = 2;
 const PASSIVE_STOP_ENTRY_TYPE = "state-flow-passive-stop";
 const PUBLICATION_SHUTDOWN_WAIT_MS = 2_000;
-const PATCH_DISPLAY_SECTION_KEYS = new Set([
-	"global",
-	"cwd",
-	"session",
-	"artifacts",
-	"contract",
-	"working",
-	"response",
-	"final",
-]);
-
-/** Keep successful patch JSON valid while separating adjacent scopes and memory sections visually. */
-export function formatPatchStateArguments(args: unknown): string {
-	const seenAtIndent = new Set<number>();
-	return JSON.stringify(args, null, 2).split("\n").flatMap((line) => {
-		const indent = line.length - line.trimStart().length;
-		const match = /^(\s+)"([^"]+)":/.exec(line);
-		if (match === null || !PATCH_DISPLAY_SECTION_KEYS.has(match[2])) {
-			for (const seenIndent of seenAtIndent) {
-				if (seenIndent > indent) seenAtIndent.delete(seenIndent);
-			}
-			return [line];
-		}
-		const separator = seenAtIndent.has(indent) ? [""] : [];
-		seenAtIndent.add(indent);
-		return [...separator, line];
-	}).join("\n");
-}
-
-/** Normalize a bounded compatibility superset without advertising aliases in the model-facing contract. */
-export function normalizePatchStateArguments(args: unknown): any {
-	if (!isObject(args) || !Object.hasOwn(args, "final")) return args;
-	const value = args.final;
-	let final: boolean;
-	if (typeof value === "boolean") final = value;
-	else if (value === 1) final = true;
-	else if (value === 0) final = false;
-	else if (typeof value === "string" && value.trim().toLowerCase() === "true") final = true;
-	else if (typeof value === "string" && value.trim().toLowerCase() === "false") final = false;
-	else return args;
-	return { ...args, final };
-}
-
-/** Keep tool output visually separated from its heading with exactly one leading newline. */
-function separatedOutput(text: string): string {
-	return `\n${text.replace(/^\n+/, "")}`;
-}
-
-/** Keep a failed tool invocation visually separated from its rendered error without changing error semantics. */
-function separatedFailure(error: unknown): Error {
-	const message = error instanceof Error ? error.message : String(error);
-	return new Error(separatedOutput(message), error instanceof Error ? { cause: error } : undefined);
-}
 
 export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowExtensionOptions = {}): void {
 	const agentDir = options.agentDir ?? getAgentDir();
@@ -145,15 +91,22 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	let pendingPublication: PendingPublicationDiagnostic | undefined;
 	let rehydrationPhase: RehydrationPhase | undefined;
 	let turnPublicationTarget: string | undefined;
-	const activePublicationWorkers = new Map<string, { controller: AbortController; done: Promise<void> }>();
-	let publicationStopped = false;
 	let publicationShutdown: Promise<void> | undefined;
 	const repositoryRoot = resolve(options.repositoryRoot ?? config.directory);
+	const diagnosticWriter = new StateFlowDiagnosticWriter(config.logging, stateFlowLogPath(agentDir), repositoryRoot, (message) => activeContext?.ui.notify(message, "warning"));
+	const publicationWorker = new PublicationWorkerController({
+		resolveDestination: () => resolveGitPushDestination(repositoryRoot),
+		isAncestor: (ancestor, descendant) => isGitCommitAncestor(repositoryRoot, ancestor, descendant),
+		push: (destination, target, signal) => pushGitTarget(repositoryRoot, destination, target, signal),
+		onDiverged: (dropped, target) => activeContext && recordDiagnostic(
+			`Retired publication queue target ${dropped.target} after a journal lineage rewrite; retargeting to ${target}`,
+			"publication-conflict", activeContext,
+		),
+	});
 	const skillReads = new SkillReadTracker();
 	const artifactReads = new ArtifactReadTracker();
 	const globalMarkdown = new GlobalMarkdownDiscovery(options.knowledgeRoot ?? getKnowledgeRoot(agentDir));
 	let artifactInvalidations: ArtifactInvalidationRequest[] = [];
-	let loggingWarningReported = false;
 	let telegramStartPending = false;
 
 	function sessionAddress(ctx: ExtensionContext): SessionAddress {
@@ -206,27 +159,6 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		artifactReads.clear();
 	}
 
-	function passiveStopBoundary(ctx: ExtensionContext): { at: number; from?: number } | undefined {
-		for (const entry of [...ctx.sessionManager.getBranch()].reverse()) {
-			try {
-				if (entry?.type !== "custom" || entry.customType !== PASSIVE_STOP_ENTRY_TYPE) continue;
-				const { at, from, reset, owner } = (entry.data as { at?: unknown; from?: unknown; reset?: unknown; owner?: unknown } | undefined) ?? {};
-				if (reset === true && owner === ctx.sessionManager.getSessionId()) return undefined;
-				if (typeof at === "number" && Number.isSafeInteger(at) && at >= 0) return {
-					at,
-					...(typeof from === "number" && Number.isSafeInteger(from) && from >= 0 ? { from } : {}),
-				};
-			} catch {
-				// A hostile unrelated branch entry cannot manufacture or suppress a valid marker.
-			}
-		}
-		return undefined;
-	}
-
-	function retainsPhysicalSessionProjection(reason: unknown): boolean {
-		return reason === undefined || reason === "startup" || reason === "reload" || reason === "resume";
-	}
-
 	function deferArtifactRefresh(): void {
 		artifactInvalidations = [];
 		artifactReads.setCandidates([]);
@@ -289,21 +221,6 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			: active.filter((name) => !owned.includes(name)));
 	}
 
-	function assistantToolBatch(ctx: ExtensionContext, toolCallId: string): string[] | undefined {
-		for (let cursor = ctx.sessionManager.getLeafEntry(); cursor; cursor = cursor.parentId ? ctx.sessionManager.getEntry(cursor.parentId) : undefined) {
-			const entry = cursor as { type?: unknown; message?: { role?: unknown; content?: unknown } };
-			if (entry.type !== "message" || entry.message?.role !== "assistant" || !Array.isArray(entry.message.content)) continue;
-			const calls = entry.message.content.filter((block): block is { type: "toolCall"; id: string; name: string } => {
-				return typeof block === "object" && block !== null
-					&& (block as { type?: unknown }).type === "toolCall"
-					&& typeof (block as { id?: unknown }).id === "string"
-					&& typeof (block as { name?: unknown }).name === "string";
-			});
-			if (calls.some(({ id }) => id === toolCallId)) return calls.map(({ name }) => name);
-		}
-		return undefined;
-	}
-
 	function recordPublication(publication: RuntimePublication, ctx: ExtensionContext): void {
 		const revision = publication.revision ?? publication.commit;
 		if (revision !== undefined) snapshot.meta.durableBase = revision;
@@ -330,8 +247,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		if (mode !== "turn-end" || target === undefined || !/^[0-9a-f]{40,64}$/.test(target)) return;
 		turnPublicationTarget = target;
 		try {
-			enqueueTurnPublication(ctx);
-			launchPublicationWorker();
+			enqueueTurnPublication();
+			publicationWorker.launch();
 		} catch (error) {
 			ctx.ui.notify(
 				`State Flow accepted the local commit; remote publication is deferred: ${error instanceof Error ? error.message : String(error)}`,
@@ -372,95 +289,16 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		return true;
 	}
 
-	function enqueueTurnPublication(ctx: ExtensionContext): void {
+	function enqueueTurnPublication(): void {
 		const target = turnPublicationTarget;
 		turnPublicationTarget = undefined;
-		if (!target) return;
-		const destination = resolveGitPushDestination(repositoryRoot);
-		if (!destination) return;
-		const path = publicationQueuePath(destination);
-		const previous = loadPublicationQueue(path);
-		const next = previous
-			? coalescePublicationTarget(previous, destination, target, (ancestor, descendant) => isGitCommitAncestor(repositoryRoot, ancestor, descendant), {
-				onDivergedLineage: (dropped) => recordDiagnostic(
-					`Retired publication queue target ${dropped.target} after a journal lineage rewrite; retargeting to ${target}`,
-					"publication-conflict", ctx,
-				),
-			})
-			: createPublicationQueue(destination, target);
-		savePublicationQueue(path, next, previous);
-	}
-
-	function launchPublicationWorker(): void {
-		if (publicationStopped) return;
-		let destination: ReturnType<typeof resolveGitPushDestination>;
-		try {
-			destination = resolveGitPushDestination(repositoryRoot);
-		} catch (error) {
-			if (error instanceof Error && /ENOENT/.test(error.message)) return;
-			throw error;
-		}
-		if (!destination) return;
-		const path = publicationQueuePath(destination);
-		if (activePublicationWorkers.has(path)) return;
-		let queued: PublicationQueueState | undefined;
-		let lease: ReturnType<typeof acquirePublicationWorkerLease>;
-		try {
-			queued = loadPublicationQueue(path);
-			if (!queued) return;
-			lease = acquirePublicationWorkerLease(path);
-		} catch {
-			return;
-		}
-		if (!lease) return;
-		const controller = new AbortController();
-		const done = runPublicationWorker(
-			queued,
-			({ target }) => pushGitTarget(repositoryRoot, destination, target, controller.signal),
-			() => loadPublicationQueue(path) ?? queued,
-			(ancestor, descendant) => isGitCommitAncestor(repositoryRoot, ancestor, descendant),
-		).then((result) => {
-			if (publicationStopped) return; // Late outcomes belong to an unconfirmed queue, not the replacement generation.
-			const current = loadPublicationQueue(path);
-			if (!current) return;
-			if (result.next === undefined) {
-				if (current.target === result.attempted.target) removePublicationQueue(path, current);
-				return;
-			}
-			if (current.target === result.attempted.target || result.next.target === current.target) {
-				savePublicationQueue(path, result.next, current);
-			}
-		}).catch(() => {
-			// Queue/CAS truth remains durable; status and a later activation expose retry.
-		}).finally(() => {
-			activePublicationWorkers.delete(path);
-			try {
-				lease.release();
-				if (!publicationStopped && loadPublicationQueue(path)?.status === "pending") launchPublicationWorker();
-			} catch {
-				// Failed lease cleanup or malformed persistence stays inert until retry or repair.
-			}
-		});
-		activePublicationWorkers.set(path, { controller, done });
+		if (target) publicationWorker.enqueue(target);
 	}
 
 	function shutdownPublicationWorkers(ctx: ExtensionContext): Promise<void> {
-		publicationStopped = true;
-		return publicationShutdown ??= (async () => {
-			const workers = [...activePublicationWorkers.values()];
-			for (const { controller } of workers) controller.abort();
-			if (workers.length === 0) return;
-			let timeout: ReturnType<typeof setTimeout> | undefined;
-			try {
-				const completed = await Promise.race([
-					Promise.all(workers.map(({ done }) => done)).then(() => true),
-					new Promise<false>((resolve) => { timeout = setTimeout(() => resolve(false), PUBLICATION_SHUTDOWN_WAIT_MS); }),
-				]);
-				if (!completed) ctx.ui.notify(`State Flow push cleanup is unconfirmed after ${PUBLICATION_SHUTDOWN_WAIT_MS}ms; worker leases remain held until child exit.`, "warning");
-			} finally {
-				clearTimeout(timeout);
-			}
-		})();
+		return publicationShutdown ??= publicationWorker.shutdown(PUBLICATION_SHUTDOWN_WAIT_MS).then((completed) => {
+			if (!completed) ctx.ui.notify(`State Flow push cleanup is unconfirmed after ${PUBLICATION_SHUTDOWN_WAIT_MS}ms; worker leases remain held until child exit.`, "warning");
+		});
 	}
 
 	function retryPendingPush(ctx: ExtensionContext): void {
@@ -472,8 +310,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			if (mode === "turn-end") {
 				turnPublicationTarget = target;
 				try {
-					enqueueTurnPublication(ctx);
-					launchPublicationWorker();
+					enqueueTurnPublication();
+					publicationWorker.launch();
 				} catch (error) {
 					ctx.ui.notify(`State Flow retained local state; asynchronous publication recovery is deferred: ${error instanceof Error ? error.message : String(error)}`, "warning");
 				}
@@ -681,7 +519,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			ctx.ui.notify(`State Flow restored disabled: ${snapshot.meta.validation.error}`, "error");
 		}
 		if (retainsPhysicalSessionProjection(sessionStartReason) && runtime?.view) {
-			const boundary = passiveStopBoundary(ctx);
+			const boundary = findPassiveStopBoundary(ctx.sessionManager.getBranch(), ctx.sessionManager.getSessionId(), PASSIVE_STOP_ENTRY_TYPE);
 			if (boundary !== undefined) {
 				const continuation = createPassiveContinuation(
 					projectStateForModel(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)),
@@ -705,41 +543,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		updateUi(ctx);
 	}
 
-	interface DiagnosticExtras {
-		content?: unknown;
-		input?: unknown;
-		tool?: string;
-		toolCallId?: string;
-		resolutionAttempt?: number;
-		terminalEligible?: boolean;
-	}
-
 	function recordDiagnostic(error: string, category: StateFlowDiagnosticCategory, ctx: ExtensionContext, extras: DiagnosticExtras = {}): void {
-		if (!config.logging) return;
-		try {
-			const path = stateFlowLogPath(agentDir);
-			const fromRepository = relative(repositoryRoot, path);
-			if (fromRepository === "" || (!isAbsolute(fromRepository) && fromRepository !== ".." && !fromRepository.startsWith(`..${sep}`))) {
-				throw new Error("diagnostic path overlaps the State Flow repository");
-			}
-			appendStateFlowDiagnostic(path, {
-				at: new Date().toISOString(),
-				sessionId: sessionAddress(ctx).id,
-				cwd: resolve(ctx.cwd),
-				category,
-				error,
-				...(extras.content === undefined ? {} : { content: projectDiagnosticContent(extras.content) }),
-				...(extras.input === undefined ? {} : { input: extras.input }),
-				...(extras.tool === undefined ? {} : { tool: extras.tool }),
-				...(extras.toolCallId === undefined ? {} : { toolCallId: extras.toolCallId }),
-				...(extras.resolutionAttempt === undefined ? {} : { resolutionAttempt: extras.resolutionAttempt }),
-				...(extras.terminalEligible === undefined ? {} : { terminalEligible: extras.terminalEligible }),
-			});
-		} catch (failure) {
-			if (loggingWarningReported) return;
-			loggingWarningReported = true;
-			ctx.ui.notify(`State Flow could not write diagnostics: ${failure instanceof Error ? failure.message : String(failure)}`, "warning");
-		}
+		diagnosticWriter.record(sessionAddress(ctx).id, ctx.cwd, error, category, extras);
 	}
 
 	function continueFallbackResolution(lastWarning: boolean): void {
@@ -1193,7 +998,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 
 	pi.on("tool_call", (event, ctx) => {
 		if (!snapshot.config.enabled) return;
-		const batch = assistantToolBatch(ctx, event.toolCallId);
+		const batch = findAssistantToolBatch(ctx.sessionManager, event.toolCallId);
 		const patchCalls = batch?.filter((name) => name === PATCH_STATE_TOOL_NAME).length ?? 0;
 		if (patchCalls > 0) {
 			if (patchCalls !== 1) {
@@ -1264,8 +1069,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			responseCommitted = true;
 			bootstrapContinuation = undefined;
 			rehydrationPhase = "step";
-			enqueueTurnPublication(ctx);
-			if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
+			enqueueTurnPublication();
+			if (snapshot.meta.remotePublication?.mode === "turn-end") publicationWorker.launch();
 			completedRunAccepted = !wasBootstrap;
 		} catch (error) {
 			if (!responseCommitted && specification !== undefined) snapshot.meta.specification = specification;
@@ -1292,7 +1097,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			telegramStartPending = false;
 			startStateFlow(ctx);
 		}
-		if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
+		if (snapshot.meta.remotePublication?.mode === "turn-end") publicationWorker.launch();
 		if (!completedRunAccepted || compactionStopped || !snapshot.config.enabled || snapshot.meta.bootstrap || resolutionPending
 			|| compactionInFlight || !ctx.isIdle() || ctx.hasPendingMessages() || !snapshot.meta.durableBase
 			|| !shouldRequestStateFlowCompaction(ctx.getContextUsage())) return;
@@ -1314,7 +1119,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		rehydrationPhase = event.reason === "resume" ? "resume-bootstrap" : "new-bootstrap";
 		restoreActiveBranch(ctx, event.reason);
 		retryPendingPush(ctx);
-		if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
+		if (snapshot.meta.remotePublication?.mode === "turn-end") publicationWorker.launch();
 		updateUi(ctx);
 		void telegram.ensure();
 	});

package/node_modules/@llblab/pi-state-flow/lib/history.ts

@@ -22,7 +22,7 @@ export interface RecentTransition extends AcceptedTransition {
 
 export type RecentTransitionWindow = RecentTransition[];
 const SCOPES = new Set<StateScope>(["global", "cwd", "session"]);
-const PATCH_KEYS = new Set(["artifacts", "contract", "working", "response", "lazy"]);
+const PATCH_KEYS = new Set(["artifacts", "contract", "working", "intents", "response", "lazy"]);
 
 /** Normalize accepted replacements into recursive-merge replay, including removals. */
 function replayPatch(before: JsonObject, after: JsonObject): JsonObject {

package/node_modules/@llblab/pi-state-flow/lib/logging.ts

@@ -1,6 +1,6 @@
 // Domain: opt-in diagnostic capture for rejected State Flow resolutions.
 import { appendFileSync, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { isObject } from "./json.ts";
 
 export type StateFlowDiagnosticCategory = "invalid-patch" | "publication-conflict" | "terminal-pending" | "finalization";
@@ -45,3 +45,55 @@ export function appendStateFlowDiagnostic(path: string, record: StateFlowDiagnos
 	mkdirSync(dirname(path), { recursive: true });
 	appendFileSync(path, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
 }
+
+export interface DiagnosticExtras {
+	content?: unknown;
+	input?: unknown;
+	tool?: string;
+	toolCallId?: string;
+	resolutionAttempt?: number;
+	terminalEligible?: boolean;
+}
+
+/** Own diagnostic path safety, projection, persistence, and one-shot failure reporting. */
+export class StateFlowDiagnosticWriter {
+	private warningReported = false;
+	private readonly enabled: boolean;
+	private readonly path: string;
+	private readonly repositoryRoot: string;
+	private readonly notify: (message: string) => void;
+
+	constructor(enabled: boolean, path: string, repositoryRoot: string, notify: (message: string) => void) {
+		this.enabled = enabled;
+		this.path = path;
+		this.repositoryRoot = repositoryRoot;
+		this.notify = notify;
+	}
+
+	record(sessionId: string, cwd: string, error: string, category: StateFlowDiagnosticCategory, extras: DiagnosticExtras = {}): void {
+		if (!this.enabled) return;
+		try {
+			const fromRepository = relative(this.repositoryRoot, this.path);
+			if (fromRepository === "" || (!isAbsolute(fromRepository) && fromRepository !== ".." && !fromRepository.startsWith(`..${sep}`))) {
+				throw new Error("diagnostic path overlaps the State Flow repository");
+			}
+			appendStateFlowDiagnostic(this.path, {
+				at: new Date().toISOString(),
+				sessionId,
+				cwd: resolve(cwd),
+				category,
+				error,
+				...(extras.content === undefined ? {} : { content: projectDiagnosticContent(extras.content) }),
+				...(extras.input === undefined ? {} : { input: extras.input }),
+				...(extras.tool === undefined ? {} : { tool: extras.tool }),
+				...(extras.toolCallId === undefined ? {} : { toolCallId: extras.toolCallId }),
+				...(extras.resolutionAttempt === undefined ? {} : { resolutionAttempt: extras.resolutionAttempt }),
+				...(extras.terminalEligible === undefined ? {} : { terminalEligible: extras.terminalEligible }),
+			});
+		} catch (failure) {
+			if (this.warningReported) return;
+			this.warningReported = true;
+			this.notify(`State Flow could not write diagnostics: ${failure instanceof Error ? failure.message : String(failure)}`);
+		}
+	}
+}

package/node_modules/@llblab/pi-state-flow/lib/migration.ts

@@ -13,7 +13,7 @@ import {
 	type OwnedFileUpdate,
 } from "./durable.ts";
 import { parseSessionRuntime, serializeSessionRuntime } from "./snapshot.ts";
-import type { StateScope } from "./state.ts";
+import { migratePreIntentState, type StateScope } from "./state.ts";
 
 export interface LegacyStorageMigration {
 	bases: DurableFileBase[];
@@ -57,9 +57,14 @@ function migrationDirectories(cwd: string, sessionId: string, root: string, sess
 			try { sessionScopeKey(entry.name); } catch { continue; }
 			const directory = join(cwdDirectory, entry.name);
 			let meta: unknown;
+			let runtime: unknown;
 			try { meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8")); }
 			catch { continue; }
-			const identity = meta && typeof meta === "object" && !Array.isArray(meta) ? (meta as { identity?: unknown }).identity : undefined;
+			try { runtime = JSON.parse(readFileSync(join(directory, "runtime.json"), "utf8")); }
+			catch { /* predecessor sessions keep identity in meta.json */ }
+			const identity = meta && typeof meta === "object" && !Array.isArray(meta) && (meta as { identity?: unknown }).identity !== undefined
+				? (meta as { identity?: unknown }).identity
+				: runtime && typeof runtime === "object" && !Array.isArray(runtime) ? (runtime as { identity?: unknown }).identity : undefined;
 			if (!identity || typeof identity !== "object" || Array.isArray(identity)) continue;
 			const owner = identity as { cwd?: unknown; sessionId?: unknown };
 			if (owner.cwd === cwdOwner && typeof owner.sessionId === "string" && owner.sessionId.length > 0) {
@@ -85,7 +90,14 @@ export function hasCwdMaterialization(cwd: string, repositoryRoot: string): bool
 	return false;
 }
 
-/** Detect predecessor snapshots or temporal envelopes without mutating the store. */
+function checkpointNeedsIntentMigration(source: string): boolean {
+	const checkpoint = JSON.parse(source) as unknown;
+	if (migratePreIntentState(checkpoint) !== undefined) return true;
+	return checkpoint !== null && typeof checkpoint === "object" && !Array.isArray(checkpoint)
+		&& migratePreIntentState((checkpoint as { state?: unknown }).state) !== undefined;
+}
+
+/** Detect predecessor snapshots, temporal envelopes, or pre-intents semantic states without mutating the store. */
 export function hasLegacyStateSources(
 	cwd: string,
 	sessionId: string,
@@ -94,8 +106,10 @@ export function hasLegacyStateSources(
 ): boolean {
 	const root = resolve(repositoryRoot);
 	return migrationDirectories(cwd, sessionId, root, sessionKey).some(({ directory, scope }) => {
-		if (lstatSync(join(directory, "checkpoint.json"), { throwIfNoEntry: false }) === undefined) return false;
+		const checkpointPath = join(directory, "checkpoint.json");
+		if (lstatSync(checkpointPath, { throwIfNoEntry: false }) === undefined) return false;
 		try {
+			if (checkpointNeedsIntentMigration(readFileSync(checkpointPath, "utf8"))) return true;
 			const meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8"));
 			if (meta === null || typeof meta !== "object" || !("temporal" in meta)) return true;
 			return scope === "session"