@llblab/pi-kit 0.16.0 → 0.17.1

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

@@ -34,24 +34,33 @@ The model-facing surface remains small:
 
 ## Semantic model
 
-Each scope may contain five semantic planes:
+Each scope may contain six semantic planes:
 
 ```text
 global | CWD | session
 ├── artifacts
 ├── contract
 ├── working
+├── intents
 ├── response (session-owned where applicable)
 └── lazy
 ```
 
-`artifacts`, `contract`, `working`, and `response` remain hot. `lazy` differs only in projection policy:
+`artifacts`, `contract`, `working`, `intents`, and `response` remain hot. `intents` may keep compact active direction while referring to large supporting detail in `lazy`. `lazy` differs only in projection policy:
 
 - It is canonical semantic JSON, validated and versioned with its owning scope.
 - It is excluded from the ordinary baseline effective-state body.
 - It becomes model-visible only through bounded baseline navigation hints or explicit `read_state` output.
 - Reading it does not mutate state, freshness, usage metadata, history, or future context.
 
+### Semantic references
+
+A reference is semantic content, not a runtime type. The optional `{"$ref":"cwd.lazy.plan"}` object provides the structured state-reference form. Inside any ordinary string or paragraph, a semantic-state reference uses `$` immediately followed by one valid `read_state` path, for example `$effective.lazy.memory[7]`. The prefix separates a deliberate reference from incidental path-like text and provides a deterministic seam if code-based parsing is ever justified. File paths, document sections, URIs, artifact locators, Skill identities, and agent identities retain their native syntax.
+
+State Flow preserves all forms exactly as ordinary JSON. It does not scan prose, index targets, validate existence, rewrite relative locators, or infer authority, dependency, hydration, execution, or completion. When a reference matters, the agent resolves it explicitly with `read_state` for semantic paths or the appropriate external read/tool for other resources. A locator supports retrieval but does not replace content required for the current decision.
+
+Reference repair is reactive, not a maintenance scan. The agent does not enumerate, audit, or resolve references merely to test them. Only after one requested `read_state` value path is missing does State Flow perform one bounded reverse lookup over current model-patchable semantic planes for exact structured `$ref` and `$path` matches. If found, the tool returns `{value:null, hint:[{type:"dangling-reference", message, paths}]}`. `hint` is explicit top-level metadata rather than state data; its action message asks for reconciliation and its path array contains at most three runtime-verified current owners. The null sentinel is never returned alone for this case. Keys, patch, and multi-path reads keep ordinary all-or-error semantics; no durable match retains the missing-path error and does not prove the agent invented the path. The agent may then reconcile a proven stale owning value while preserving surrounding meaning. This applies equally to `$ref` objects and contextual references in prose. Effective-state absence alone does not identify the owner, and unavailable history, inaccessible external resources, or transient read failure do not prove that a durable reference is broken.
+
 Valid lazy values include:
 
 ```json
@@ -105,7 +114,7 @@ Active obligations, current constraints, unresolved next actions, and facts requ
 
 `projection` defaults to `value`. A batch uses one projection for every path, evaluates every path against one captured state view, and returns results in request order. Duplicate paths remain duplicate results. If any path is invalid, the whole read fails; there is no mixed partial result.
 
-The legacy single `path` form remains first-class rather than mere compatibility syntax. Existing `offset`/`scope` input may remain temporarily during migration but cannot combine with `path` or `paths`.
+The single `path` form is first-class. The retired top-level `offset` and `scope` inputs are rejected; history and ownership belong in the semantic path itself, such as `cwd[1].lazy.memory`.
 
 ### Response shape
 
@@ -117,13 +126,13 @@ There are three projections:
 | `keys` | `{ "meta": ..., "keys": ... }` | Minimal structural facts followed by immediate keys |
 | `patch` | `{ "patch": ... }` | Historical semantic patch at the selected boundary |
 
-A single-path request returns one payload. A multi-path request returns positionally aligned arrays under the same projection fields.
+A single-path request returns one payload. A multi-path request returns positionally aligned arrays under the same projection fields. One missing value path with exact current durable references instead returns `{ "value": null, "hint": [{ "type": "dangling-reference", "message": "Reconcile the verified current values that reference this path.", "paths": ["cwd.working.note"] }] }`; this explicit sentinel is diagnostic metadata, not semantic state.
 
-`value` deliberately mirrors the effective-state snapshot injected at iteration start: it is semantic state without revision, provenance, range, transport, or storage fields. `patch` likewise contains only the selected semantic patch. Only structural discovery earns `meta`, and `keys` remains the final and most valuable field in that response.
+`value` otherwise deliberately mirrors the effective-state snapshot injected at iteration start: it is semantic state without revision, provenance, range, transport, or storage fields. `patch` likewise contains only the selected semantic patch. Only structural discovery earns `meta`, and `keys` remains the final and most valuable field in that response.
 
 The response does not repeat the requested path or projection and does not return an internal revision. Runtime owns revision selection, locking, CAS, and publication; the model cannot improve correctness by echoing that machinery.
 
-Errors use the normal tool-error channel rather than successful JSON containing an `error` field.
+Errors use the normal tool-error channel rather than successful JSON containing an `error` field. The explicit dangling-reference sentinel above is the sole missing-path exception; keys, patch, multi-path, and unmatched value reads still fail.
 
 ### Path and range model
 

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 {
@@ -977,8 +782,11 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				);
 			}
 			branchHasSnapshot = true;
+			// Activation reasserts the selected session stream as a complete cohort. A resumed
+			// branch may have no reusable temporal revision after an extension upgrade; a
+			// runtime-only write would then reject its selected session as an omitted change.
 			const publication = runtime.view
-				? runtime.promote(snapshot) ?? runtime.publish(snapshot)
+				? runtime.promote(snapshot) ?? runtime.publish(snapshot, true)
 				: runtime.initialize(snapshot, true, undefined, branchStartsWithoutRuntime);
 			recordPolicyPublication(publication, ctx);
 			installScopeStates();
@@ -1193,7 +1001,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 +1072,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 +1100,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 +1122,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"