@llblab/pi-kit 0.7.0 → 0.8.0

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

@@ -14,6 +14,7 @@ import {
 	legacyTemporalScopePaths,
 	durablePaths,
 	isStateFlowOwnedPath,
+	parseScopeProvenance,
 	parseScopeStream,
 	parseStateSource,
 	serializeScopeStream,
@@ -25,6 +26,7 @@ import {
 	type DurableFileBase,
 	type OwnedFileUpdate,
 } from "./durable.ts";
+import { parseArtifactProvenanceRegistry, type ArtifactProvenanceRegistry } from "./artifact.ts";
 import { planLegacyStorageMigration } from "./migration.ts";
 import { sameJson } from "./json.ts";
 import { validateTemporalState, type ScopeStream, type TemporalState } from "./temporal.ts";
@@ -176,6 +178,8 @@ export interface TemporalRevisionLoad {
 	base: TemporalGitBase;
 	scopes: Record<StateScope, ScopeStream | undefined>;
 	runtime?: { document: SessionRuntime; revision: string };
+	/** Runtime-owned artifact provenance retained at this revision. */
+	provenance: Record<StateScope, ArtifactProvenanceRegistry>;
 	/** True only when this revision directly selected pre-0.4 hashed paths. */
 	legacyLayout?: true;
 }
@@ -194,6 +198,7 @@ function revisionScopeFiles(root: string, revision: string, cwd: string, session
 		checkpoint: revisionFile(root, revision, paths.checkpoint),
 		patches: revisionFile(root, revision, paths.patches),
 		legacy: revisionFile(root, revision, resolve(paths.directory, "state.json")),
+		meta: revisionFile(root, revision, paths.meta),
 	});
 	const canonical = read(temporalScopePaths(cwd, sessionId, scope, root, sessionKey));
 	if (scope === "global" || [canonical.checkpoint, canonical.patches, canonical.legacy].some(({ identity }) => identity !== "missing")) return { ...canonical, legacyLayout: false };
@@ -206,12 +211,14 @@ export function loadTemporalRevision(cwd: string, sessionId: string, repositoryR
 	assertReadableRevision(root, revision);
 	const files: DurableFileBase[] = [];
 	const scopes = {} as Record<StateScope, ScopeStream | undefined>;
+	const provenance: Record<StateScope, ArtifactProvenanceRegistry> = { global: {}, cwd: {}, session: {} };
 	let legacyLayout = false;
 	for (const scope of ["global", "cwd", "session"] as const) {
 		const selected = revisionScopeFiles(root, revision, cwd, sessionId, sessionKey, scope);
 		if (selected.legacy.identity !== "missing") throw new Error("Historical legacy storage requires explicit migration interpretation");
 		legacyLayout ||= selected.legacyLayout;
-		files.push(selected.checkpoint, selected.patches, selected.legacy);
+		files.push(selected.checkpoint, selected.patches, selected.legacy, ...(scope === "session" ? [] : [selected.meta]));
+		if (scope !== "session") provenance[scope] = parseScopeProvenance(selected.meta.content, selected.meta.path);
 		scopes[scope] = parseScopeStream(selected.checkpoint.content, selected.patches.content, scope,
 			scope === "cwd" && !selected.legacyLayout ? cwd : undefined);
 	}
@@ -226,7 +233,8 @@ export function loadTemporalRevision(cwd: string, sessionId: string, repositoryR
 	const { paths: runtimePaths, config, meta } = selectedRuntime;
 	files.push(config, meta);
 	const document = parseSessionRuntime(config.content, meta.content, cwd, sessionId);
-	if (document === undefined) return { base: { head: revision, files }, scopes, ...(legacyLayout ? { legacyLayout: true as const } : {}) };
+	if (document === undefined) return { base: { head: revision, files }, scopes, provenance, ...(legacyLayout ? { legacyLayout: true as const } : {}) };
+	provenance.session = parseArtifactProvenanceRegistry(document.meta.artifacts, "State Flow session artifact provenance");
 	const owner = git(root, ["log", "-1", "--format=%H", revision, "--",
 		relativeOwnedPath(runtimePaths.config, root), relativeOwnedPath(runtimePaths.meta, root),
 	]).stdout.trim();
@@ -244,7 +252,7 @@ export function loadTemporalRevision(cwd: string, sessionId: string, repositoryR
 		throw new Error("Session runtime has incomplete temporal scope storage");
 	}
 	validateTemporalState({ lineage: document.meta.lineage, scopes: { global: scopes.global, cwd: scopes.cwd, session: scopes.session } });
-	return { base: { head: revision, files }, scopes, runtime: { document, revision: owner }, ...(legacyLayout ? { legacyLayout: true as const } : {}) };
+	return { base: { head: revision, files }, scopes, runtime: { document, revision: owner }, provenance, ...(legacyLayout ? { legacyLayout: true as const } : {}) };
 }
 
 /** Legacy state.json is already current; explanatory journals are irrelevant to semantic recovery. */
@@ -418,16 +426,17 @@ function commitOwnedFiles(
 	try {
 		if (expectedHead === undefined) git(repositoryRoot, ["read-tree", "--empty"], { env });
 		else git(repositoryRoot, ["read-tree", expectedHead], { env });
-		const entries: Array<{ relativePath: string; blob?: string }> = [];
+		// A State Flow commit carries the complete non-ignored worktree delta, including user edits
+		// and manual deletions, while `.gitignore` stays authoritative for untracked files. The
+		// transient publication lock is ours, not repository content.
+		git(repositoryRoot, ["add", "-A", "--", ".", ":(exclude).state-flow-publication.lock"], { env });
 		for (const update of updates) {
 			const relativePath = relativeOwnedPath(update.path, repositoryRoot);
 			if (update.content === undefined) {
-				entries.push({ relativePath });
 				git(repositoryRoot, ["update-index", "--force-remove", "--", relativePath], { env });
 				continue;
 			}
 			const blob = git(repositoryRoot, ["hash-object", "-w", "--stdin"], { input: update.content }).stdout.trim();
-			entries.push({ relativePath, blob });
 			git(repositoryRoot, ["update-index", "--add", "--cacheinfo", `100644,${blob},${relativePath}`], { env });
 		}
 		const tree = git(repositoryRoot, ["write-tree"], { env }).stdout.trim();
@@ -443,10 +452,9 @@ function commitOwnedFiles(
 		assertOwnedFileUpdates(updates, repositoryRoot);
 		git(repositoryRoot, ["update-ref", branchRef, commit, expectedHead ?? zero]);
 		try {
-			const indexInfo = entries.map(({ relativePath, blob }) => blob === undefined
-				? `0 ${zero}\t${relativePath}\n`
-				: `100644 ${blob}\t${relativePath}\n`).join("");
-			git(repositoryRoot, ["update-index", "--index-info"], { input: indexInfo });
+			// Align the caller-visible index with the committed tree so advancing HEAD through the
+			// isolated index leaves no artificial staged/unstaged status entries behind.
+			git(repositoryRoot, ["read-tree", commit]);
 		} catch (error) {
 			git(repositoryRoot, ["update-ref", branchRef, expectedHead ?? zero, commit]);
 			throw error;
@@ -512,10 +520,10 @@ function publishOwnedCohort(
 }
 
 /** Explicit current-file adoption, not reconstruction or invention of pre-Git history. */
-export function adoptFileStateToGit(cwd: string, sessionId: string, repositoryRoot: string, revision: string, snapshot: Snapshot, sessionKey = sessionId) {
+export function adoptFileStateToGit(cwd: string, sessionId: string, repositoryRoot: string, revision: string, snapshot: Snapshot, sessionKey = sessionId, push = true) {
 	const selected = loadTemporalFileRevision(cwd, sessionId, repositoryRoot, revision, sessionKey);
 	if (snapshot.meta.step !== selected.runtime.meta.step) throw new Error("Git adoption must preserve the semantic step");
-	const runtime = createSessionRuntime(snapshot, cwd, sessionId, selected.view.lineage);
+	const runtime = createSessionRuntime(snapshot, cwd, sessionId, selected.view.lineage, "unconfirmed", selected.provenance.session);
 	runtime.meta.temporalRevision = "self";
 	const sources = serializeSessionRuntime(runtime, cwd, sessionId);
 	initializeGitRepository(repositoryRoot);
@@ -523,8 +531,14 @@ export function adoptFileStateToGit(cwd: string, sessionId: string, repositoryRo
 		const current = captureTemporalBaseUnderLock(cwd, sessionId, root, sessionKey);
 		assertTemporalFileBase(selected.base, current);
 		const paths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
+		const provenancePaths = new Set([
+			temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta,
+			temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta,
+		]);
 		// Preserve exact valid scope bytes; only runtime provenance changes representation.
-		const updates = current.files.filter(({ path }) => path.endsWith("checkpoint.json") || path.endsWith("patches.jsonl"))
+		const updates = current.files.filter(({ path, identity }) => path.endsWith("checkpoint.json")
+			|| path.endsWith("patches.jsonl")
+			|| (provenancePaths.has(path) && identity !== "missing"))
 			.map(({ path, content }) => ({ path, content: content! }));
 		updates.push({ path: paths.config, content: sources.config }, { path: paths.meta, content: sources.meta });
 		const existing = current.head && updates.every(({ path, content }) => revisionFile(root, current.head!, path).content === content)
@@ -532,9 +546,10 @@ export function adoptFileStateToGit(cwd: string, sessionId: string, repositoryRo
 		if (existing && (!existing.runtime || !sameJson({ lineage: existing.runtime.document.meta.lineage, scopes: existing.scopes }, selected.view))) {
 			throw new Error("Existing Git runtime does not anchor the selected file cohort");
 		}
-		const publication = publishOwnedCohort(root, updates, current.files, current.head, [], "persist");
+		const publication = publishOwnedCohort(root, updates, current.files, current.head, [], "persist", push);
 		const target = publication.commit ?? existing!.runtime!.revision;
-		return { ...publication, revision: target, push: publication.push ?? pushGitCommit(root, target), view: selected.view,
+		const remote = push ? publication.push ?? pushGitCommit(root, target) : undefined;
+		return { ...publication, revision: target, ...(remote === undefined ? {} : { push: remote }), view: selected.view, provenance: selected.provenance,
 			base: { head: publication.commit ?? current.head, files: temporalFileReceipts(current, updates) } };
 	});
 }
@@ -572,6 +587,7 @@ export function publishTemporalStateToGit(
 	runtime?: SessionRuntime,
 	sessionKey = sessionId,
 	push = true,
+	provenance?: Readonly<Record<StateScope, ArtifactProvenanceRegistry>>,
 ): { base: TemporalGitBase; commit?: string; push?: GitPushResult } {
 	return withPublicationLock(repositoryRoot, (root) => {
 		const current = captureTemporalBaseUnderLock(cwd, sessionId, root, sessionKey);
@@ -587,7 +603,7 @@ export function publishTemporalStateToGit(
 			const selected = loadTemporalRevision(cwd, sessionId, root, runtime!.meta.temporalRevision!, sessionKey);
 			if (!sameJson(selected.scopes, view.scopes)) throw new Error("Runtime temporal reference does not match selected streams");
 		}
-		const { updates, changedScopes } = planTemporalPublication(cwd, sessionId, view, scopes, current, root, runtime, runtimeOnly, sessionKey);
+		const { updates, changedScopes } = planTemporalPublication(cwd, sessionId, view, scopes, current, root, runtime, runtimeOnly, sessionKey, provenance);
 		if (!runtimeOnly) includeUncommittedCohort(cwd, sessionId, root, current, updates, changedScopes, scopes, runtime !== undefined, sessionKey);
 		if (updates.length === 0) return { base: current };
 		const publication = publishOwnedCohort(root, updates, current.files, current.head, changedScopes, "persist", push);

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

@@ -0,0 +1,41 @@
+// Domain: opt-in diagnostic capture for rejected State Flow resolutions.
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isObject } from "./json.ts";
+
+export type StateFlowDiagnosticCategory = "invalid-patch" | "publication-conflict" | "terminal-pending" | "finalization";
+
+/** Minimal structural block; only ordinary text keeps its exact content. */
+export interface StateFlowDiagnosticBlock {
+	type: string;
+	text?: string;
+}
+
+export interface StateFlowDiagnosticRecord {
+	at: string;
+	sessionId: string;
+	cwd: string;
+	category: StateFlowDiagnosticCategory;
+	error: string;
+	content?: StateFlowDiagnosticBlock[];
+}
+
+/** Preserve exact text blocks and block boundaries; reasoning bodies are never duplicated. */
+export function projectDiagnosticContent(content: unknown): StateFlowDiagnosticBlock[] {
+	if (!Array.isArray(content)) return [];
+	return content.map((block) => {
+		if (!isObject(block) || typeof block.type !== "string") return { type: "unknown" };
+		if (block.type === "text" && typeof block.text === "string") return { type: "text", text: block.text };
+		return { type: block.type };
+	});
+}
+
+/** Diagnostic JSONL lives beneath the active Pi agent directory, never inside the state repository. */
+export function stateFlowLogPath(agentDir: string): string {
+	return join(agentDir, "tmp", "state-flow", "logs.jsonl");
+}
+
+export function appendStateFlowDiagnostic(path: string, record: StateFlowDiagnosticRecord): void {
+	mkdirSync(dirname(path), { recursive: true });
+	appendFileSync(path, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
+}

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

@@ -1,6 +1,7 @@
 import {
 	classifyArtifactFreshness,
 	type ArtifactMetadata,
+	type ArtifactProvenance,
 	type ArtifactRegistry,
 	type ArtifactSourceIdentity,
 } from "./artifact.ts";
@@ -55,10 +56,13 @@ function cycleTime(value: Date | number | string | undefined): number {
 	return timestamp;
 }
 
-function compiledTime(metadata: ArtifactMetadata): number {
-	if (typeof metadata.compiled_at !== "string") return Number.NEGATIVE_INFINITY;
-	const timestamp = Date.parse(metadata.compiled_at);
-	return Number.isFinite(timestamp) ? timestamp : Number.NEGATIVE_INFINITY;
+function compiledTime(entry: ArtifactProvenance | undefined, legacy: unknown): number {
+	const timestamp = entry?.malformed === true ? undefined
+		: entry !== undefined && Object.hasOwn(entry, "compiledAt") ? entry.compiledAt
+			: legacy;
+	if (typeof timestamp !== "string") return Number.NEGATIVE_INFINITY;
+	const parsed = Date.parse(timestamp);
+	return Number.isFinite(parsed) ? parsed : Number.NEGATIVE_INFINITY;
 }
 
 function request(source: ArtifactSourceCandidate): ArtifactMaintenanceRequest {
@@ -81,6 +85,7 @@ export function planArtifactMaintenance(
 	registry: Readonly<Record<string, unknown>>,
 	compiler: string,
 	options: ArtifactMaintenanceOptions = {},
+	provenance: Readonly<Record<string, ArtifactProvenance>> = {},
 ): ArtifactMaintenancePlan {
 	if (!isObject(registry)) throw new Error("Artifacts must be a path-keyed JSON object");
 	const now = cycleTime(options.now);
@@ -104,9 +109,10 @@ export function planArtifactMaintenance(
 		seen.add(source.path);
 		nonNegativeSafeInteger(source.bytes, `Artifact source bytes at ${source.path}`);
 		const metadata = Object.hasOwn(registry, source.path) ? registry[source.path] : undefined;
-		const freshness = classifyArtifactFreshness(source, metadata, compiler);
+		const entry = Object.hasOwn(provenance, source.path) ? provenance[source.path] : undefined;
+		const freshness = classifyArtifactFreshness(source, metadata, compiler, false, entry);
 		if (freshness.kind !== "fresh") continue;
-		const compiledAt = compiledTime(metadata as ArtifactMetadata);
+		const compiledAt = compiledTime(entry, isObject(metadata) ? (metadata as ArtifactMetadata).compiled_at : undefined);
 		if (compiledAt !== Number.NEGATIVE_INFINITY && now - compiledAt < minimumAgeMs) continue;
 		eligible.push({ source, compiledAt });
 	}

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

@@ -1,5 +1,6 @@
 // Domain: conservative current-snapshot migration planning; Git owns publication and rollback.
 import { randomUUID } from "node:crypto";
+import { lstatSync } from "node:fs";
 import { join, resolve } from "node:path";
 import {
 	captureOwnedFileBases,
@@ -36,6 +37,21 @@ export function hasCwdMaterialization(cwd: string, repositoryRoot: string): bool
 	return false;
 }
 
+/** Cheap canonical-layout fast path: inspect only the three predecessor snapshot names. */
+export function hasLegacyStateSources(
+	cwd: string,
+	sessionId: string,
+	repositoryRoot: string,
+	sessionKey = sessionId,
+): boolean {
+	const root = resolve(repositoryRoot);
+	return [
+		join(root, "state.json"),
+		join(cwdScopePaths(cwd, root).directory, "state.json"),
+		join(sessionScopePaths(cwd, sessionId, root, sessionKey).directory, "state.json"),
+	].some((path) => lstatSync(path, { throwIfNoEntry: false }) !== undefined);
+}
+
 /** Plan from current scope snapshots only; old explanatory journals are never replay input. */
 export function planLegacyStorageMigration(
 	cwd: string,

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

@@ -12,6 +12,8 @@ export interface RehydrationRoute {
 	scope: StateScope;
 	source: ArtifactSourceIdentity;
 	metadata: unknown;
+	/** Runtime-owned freshness evidence retained beside the semantic artifact. */
+	provenance?: unknown;
 	compiler: string;
 	intent: ArtifactAcquisitionIntent;
 	materializedSufficient?: boolean;
@@ -58,6 +60,7 @@ export function planKnowledgeRehydration(
 			intent: route.intent,
 			...(route.materializedSufficient === undefined ? {} : { materializedSufficient: route.materializedSufficient }),
 			...(route.explicitRefresh === undefined ? {} : { explicitRefresh: route.explicitRefresh }),
+			...(route.provenance === undefined ? {} : { provenance: route.provenance }),
 		});
 		if (decision.kind === "use-materialized") {
 			materialized.push(route.source.path);

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

@@ -1,19 +1,38 @@
 import { randomUUID } from "node:crypto";
 import { lstatSync } from "node:fs";
 import { join } from "node:path";
-import { parseScopeStream, sessionRuntimePaths, temporalScopePaths, type SessionAddress } from "./durable.ts";
+import { parseScopeProvenance, parseScopeStream, sessionRuntimePaths, temporalScopePaths, type SessionAddress } from "./durable.ts";
+import { parseArtifactProvenanceRegistry, pruneArtifactProvenance, type ArtifactProvenance, type ArtifactProvenanceRegistry } from "./artifact.ts";
 import { adoptFileStateToGit, initializeGitRepository, isLocalGitRepository, captureTemporalGitBase, loadLegacyStatesAtRevision, loadTemporalRevision, migrateHashedCwdAtHead, migrateHashedLayoutAtHead, migrateLegacyStorageToGit, publishTemporalStateToGit, type TemporalGitBase } from "./git.ts";
-import { captureTemporalFileBase, detectGitCapability, initializeFileStore, loadTemporalFileRevision, migrateLegacyStorageToFiles, publishTemporalStateToFiles } from "./storage.ts";
+import { captureTemporalFileBase, detectGitCapability, initializeFileStore, loadTemporalFileRevision, migrateLegacyStorageToFiles, publishTemporalStateToFiles, type TemporalFileBase } from "./storage.ts";
 import { type AcceptedTransition, type RecentTransitionWindow } from "./history.ts";
 import { hashJson, sameJson } from "./json.ts";
-import { hasCwdMaterialization } from "./migration.ts";
+import { hasCwdMaterialization, hasLegacyStateSources } from "./migration.ts";
 import { RevisionUnavailableError, createSessionRuntime, isFileRevision, parseSessionRuntime, resolveFileSessionRuntime, resolveSessionRuntime, type Snapshot } from "./snapshot.ts";
 import { emptyState, type MaterializedState, type ScopedStates, type StateScope } from "./state.ts";
-import { adoptTemporalStreams, advanceTemporalState, createTemporalState, readTemporalState, validateTemporalState, type TemporalState } from "./temporal.ts";
+import { adoptTemporalStreams, advanceTemporalState, createTemporalState, readTemporalState, validateTemporalState, type ScopeStream, type TemporalState } from "./temporal.ts";
 
 const SCOPES = ["global", "cwd", "session"] as const;
+const SHARED_SCOPES = ["global", "cwd"] as const;
 export type RuntimePublication = ReturnType<typeof publishTemporalStateToGit> & { revision?: string };
 
+function emptyProvenance(): Record<StateScope, ArtifactProvenanceRegistry> {
+	return { global: {}, cwd: {}, session: {} };
+}
+
+function scopeLabel(scope: StateScope): string {
+	return scope === "cwd" ? "CWD" : scope;
+}
+
+/** Precise fail-closed conflict for a shared scope this transition actually overwrites. */
+function targetScopeConflict(scopes: readonly StateScope[]): Error {
+	const labels = scopes.map(scopeLabel);
+	if (labels.length === 1) {
+		return new Error(`State Flow cannot publish the ${labels[0]} patch because the live ${labels[0]} state advanced after this transition's selected basis. Refresh or reconcile the target scope before retrying.`);
+	}
+	return new Error(`State Flow cannot publish the ${labels.join(" and ")} patches because the live ${labels.join(" and ")} states advanced after this transition's selected basis. Refresh or reconcile the target scopes before retrying.`);
+}
+
 /** Immutable target validation is independent of acquiring the live publication basis. */
 export function inspectRuntimeRevision(cwd: string, sessionId: string, root: string, revision: string, sessionKey = sessionId) {
 	const loaded = loadTemporalRevision(cwd, sessionId, root, revision, sessionKey);
@@ -22,7 +41,7 @@ export function inspectRuntimeRevision(cwd: string, sessionId: string, root: str
 	if (!loaded.scopes.global || !loaded.scopes.cwd || !loaded.scopes.session) throw new Error("Incomplete temporal scope cohort");
 	const view = { lineage: resolved.lineage, scopes: { global: loaded.scopes.global, cwd: loaded.scopes.cwd, session: loaded.scopes.session } };
 	validateTemporalState(view);
-	return { runtime: loaded.runtime, resolved, view, ...(loaded.legacyLayout ? { legacyLayout: true as const } : {}) };
+	return { runtime: loaded.runtime, resolved, view, provenance: loaded.provenance, ...(loaded.legacyLayout ? { legacyLayout: true as const } : {}) };
 }
 
 /** Both checkpoint generations validate their immutable target before any live migration/publication. */
@@ -51,6 +70,7 @@ export class TemporalRuntime {
 	private semanticRevision: string | undefined;
 	private savedRuntime: string | undefined;
 	private backend: "git" | "files" | undefined;
+	private provenanceByScope: Record<StateScope, ArtifactProvenanceRegistry> = emptyProvenance();
 	readonly cwd: string;
 	private readonly session: SessionAddress;
 	readonly root: string;
@@ -63,6 +83,11 @@ export class TemporalRuntime {
 	get sessionId(): string { return this.session.id; }
 	get sessionKey(): string { return this.session.key; }
 
+	/** Runtime-owned artifact freshness evidence for one scope; never model-visible state. */
+	artifactProvenance(scope: StateScope): ArtifactProvenanceRegistry {
+		return structuredClone(this.provenanceByScope[scope]);
+	}
+
 	/** Explicit start owns directory/repository creation; reads never call this. */
 	prepare(): void {
 		const backend = detectGitCapability();
@@ -75,8 +100,10 @@ export class TemporalRuntime {
 	promote(snapshot: Snapshot): RuntimePublication | undefined {
 		if (this.backend !== "files" || !this.view || detectGitCapability() === "files") return undefined;
 		if (!snapshot.meta.durableBase || snapshot.meta.durableBase !== this.semanticRevision) throw new Error("Git adoption requires the selected file revision");
-		const result = adoptFileStateToGit(this.cwd, this.sessionId, this.root, snapshot.meta.durableBase, snapshot, this.sessionKey);
-		const savedRuntime = hashJson(createSessionRuntime(snapshot, this.cwd, this.sessionId, result.view.lineage));
+		const pushRemote = (snapshot.meta.remotePublication?.mode ?? "transition") === "transition";
+		const result = adoptFileStateToGit(this.cwd, this.sessionId, this.root, snapshot.meta.durableBase, snapshot, this.sessionKey, pushRemote);
+		this.provenanceByScope = structuredClone(result.provenance);
+		const savedRuntime = hashJson(createSessionRuntime(snapshot, this.cwd, this.sessionId, result.view.lineage, "unconfirmed", this.provenanceByScope.session));
 		this.view = result.view;
 		this.base = result.base;
 		this.backend = "git";
@@ -114,10 +141,11 @@ export class TemporalRuntime {
 	restore(revision: string, legacySnapshot?: Snapshot): Snapshot {
 		const inspected = inspectSnapshotRevision(this.cwd, this.sessionId, this.root, revision, legacySnapshot, this.sessionKey);
 		if (inspected.file) {
-			const savedRuntime = hashJson(createSessionRuntime(inspected.snapshot, this.cwd, this.sessionId, inspected.file.view.lineage, "files"));
+			const savedRuntime = hashJson(createSessionRuntime(inspected.snapshot, this.cwd, this.sessionId, inspected.file.view.lineage, "files", inspected.file.provenance.session));
 			this.view = inspected.file.view;
 			this.base = inspected.file.base;
 			this.backend = "files";
+			this.provenanceByScope = structuredClone(inspected.file.provenance);
 			this.semanticRevision = revision;
 			this.savedRuntime = savedRuntime;
 			return inspected.snapshot;
@@ -170,6 +198,7 @@ export class TemporalRuntime {
 		this.view = view;
 		this.base = base;
 		this.backend = "git";
+		this.provenanceByScope = structuredClone(loaded.provenance);
 		this.semanticRevision = semanticRevision;
 		this.savedRuntime = savedRuntime;
 		return resolved.snapshot;
@@ -181,14 +210,22 @@ export class TemporalRuntime {
 		const backend = this.backend ?? (detectGitCapability() === "git" && lstatSync(join(this.root, ".git"), { throwIfNoEntry: false }) ? "git" : "files");
 		if (backend === "git") {
 			if (!hasCwd) migrateHashedCwdAtHead(this.cwd, this.root);
-			migrateLegacyStorageToGit(this.cwd, this.sessionId, this.root, this.sessionKey);
+			if (hasLegacyStateSources(this.cwd, this.sessionId, this.root, this.sessionKey)) {
+				migrateLegacyStorageToGit(this.cwd, this.sessionId, this.root, this.sessionKey);
+			}
 		}
 		else {
 			if (allowCreateCwd) initializeFileStore(this.root);
-			migrateLegacyStorageToFiles(this.cwd, this.sessionId, this.root, this.sessionKey);
+			if (hasLegacyStateSources(this.cwd, this.sessionId, this.root, this.sessionKey)) {
+				migrateLegacyStorageToFiles(this.cwd, this.sessionId, this.root, this.sessionKey);
+			}
 		}
 		const base: TemporalGitBase = backend === "git" ? captureTemporalGitBase(this.cwd, this.sessionId, this.root, this.sessionKey) : captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey);
 		const files = new Map(base.files.map((file) => [file.path, file.content]));
+		if (SCOPES.some((scope) => {
+			const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
+			return files.get(join(paths.directory, "state.json")) !== undefined;
+		})) throw new Error("Legacy State Flow storage changed during initialization; retry migration from a fresh basis");
 		const streams = Object.fromEntries(SCOPES.map((scope) => {
 			const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
 			return [scope, parseScopeStream(files.get(paths.checkpoint), files.get(paths.patches), scope, scope === "cwd" ? this.cwd : undefined)];
@@ -204,6 +241,13 @@ export class TemporalRuntime {
 		candidate.backend = backend;
 		candidate.base = base;
 		candidate.view = adoptTemporalStreams({ global: streams.global ?? fresh.scopes.global, cwd: streams.cwd ?? fresh.scopes.cwd, session: streams.session ?? fresh.scopes.session }, `${base.head ?? "unborn"}:${randomUUID()}`);
+		const globalMeta = temporalScopePaths(this.cwd, this.sessionId, "global", this.root, this.sessionKey).meta;
+		const cwdMeta = temporalScopePaths(this.cwd, this.sessionId, "cwd", this.root, this.sessionKey).meta;
+		candidate.provenanceByScope = {
+			global: parseScopeProvenance(files.get(globalMeta), globalMeta),
+			cwd: parseScopeProvenance(files.get(cwdMeta), cwdMeta),
+			session: streams.session === undefined ? {} : parseArtifactProvenanceRegistry(existingRuntime?.meta.artifacts, "State Flow session artifact provenance"),
+		};
 		if (expectedShared && (["global", "cwd"] as const).some((scope) => !sameJson(candidate.read(0, scope), expectedShared[scope]))) {
 			throw new Error("Legacy branch shared scopes diverged from the selected revision; migration cannot overwrite them");
 		}
@@ -211,54 +255,146 @@ export class TemporalRuntime {
 		this.view = candidate.view;
 		this.base = candidate.base;
 		this.backend = backend;
+		this.provenanceByScope = structuredClone(candidate.provenanceByScope);
 		this.semanticRevision = candidate.semanticRevision;
 		this.savedRuntime = candidate.savedRuntime;
 		return publication;
 	}
 
-	publish(snapshot: Snapshot, semantic = false, accepted?: AcceptedTransition, options: { pushRemote?: boolean } = {}): RuntimePublication | undefined {
-		if (!this.view || !this.base) throw new Error("State Flow temporal publication is unavailable; restore or initialize before accepting a transition");
-		const next = accepted ? advanceTemporalState(this.view, accepted.transitions, accepted.id) : this.view;
-		const runtime = createSessionRuntime(snapshot, this.cwd, this.sessionId, next.lineage, this.backend === "files" ? "files" : "unconfirmed");
-		const fingerprint = hashJson(runtime);
-		if (!semantic && fingerprint === this.savedRuntime) return undefined;
-		if (semantic && this.semanticRevision) {
-			// Session files may branch; shared scopes may not be silently merged or rewound.
-			const live = new Map(this.base.files.map((file) => [file.path, file.content]));
-			for (const scope of ["global", "cwd"] as const) {
-				const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
-				const stream = parseScopeStream(live.get(paths.checkpoint), live.get(paths.patches), scope, scope === "cwd" ? this.cwd : undefined);
-				if (!sameJson(stream, this.view.scopes[scope])) throw new Error("State Flow cannot publish this restored branch because its global or CWD scope changed concurrently after the linked revision");
+	/**
+	 * Reconcile untouched shared-scope drift against the current proven live basis.
+	 *
+	 * A restored branch can lag behind live global/CWD state. Untouched shared scopes adopt
+	 * the current live streams at a fresh origin; a shared scope the accepted transition
+	 * actually changes remains a fail-closed write conflict. Divergence in non-adoptable
+	 * session or runtime files also fails closed under the existing race rule.
+	 */
+	private reconcileSharedDrift(changedScopes: ReadonlySet<StateScope>): {
+		view: TemporalState;
+		base: TemporalGitBase | TemporalFileBase;
+		provenance: Record<StateScope, ArtifactProvenanceRegistry>;
+	} {
+		const captured = this.backend === "files"
+			? captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey)
+			: captureTemporalGitBase(this.cwd, this.sessionId, this.root, this.sessionKey);
+		const liveFiles = new Map(captured.files.map((file) => [file.path, file]));
+		const adoptable = new Set<string>();
+		for (const scope of SHARED_SCOPES) {
+			const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
+			adoptable.add(paths.checkpoint);
+			adoptable.add(paths.patches);
+			adoptable.add(paths.meta);
+		}
+		for (const file of this.base!.files) {
+			if (adoptable.has(file.path)) continue;
+			const current = liveFiles.get(file.path);
+			if (current === undefined || current.identity !== file.identity) {
+				throw new Error("Temporal State Flow base or scope identity changed concurrently");
 			}
 		}
+		const provenance = structuredClone(this.provenanceByScope);
+		const adopted = new Map<StateScope, ScopeStream>();
+		const targets: StateScope[] = [];
+		for (const scope of SHARED_SCOPES) {
+			const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
+			const stream = parseScopeStream(liveFiles.get(paths.checkpoint)?.content, liveFiles.get(paths.patches)?.content, scope, scope === "cwd" ? this.cwd : undefined);
+			if (stream === undefined) throw new Error(`Live State Flow ${scope} scope storage is incomplete`);
+			const liveProvenance = parseScopeProvenance(liveFiles.get(paths.meta)?.content, paths.meta);
+			const streamDrifted = !sameJson(stream, this.view!.scopes[scope]);
+			const provenanceDrifted = !sameJson(liveProvenance, this.provenanceByScope[scope]);
+			if (!streamDrifted && !provenanceDrifted) continue;
+			if (changedScopes.has(scope)) {
+				targets.push(scope);
+				continue;
+			}
+			provenance[scope] = liveProvenance;
+			if (streamDrifted) adopted.set(scope, stream);
+		}
+		if (targets.length > 0) throw targetScopeConflict(targets);
+		if (adopted.size === 0) return { view: this.view!, base: captured, provenance };
+		const streams = {
+			global: adopted.get("global") ?? structuredClone(this.view!.scopes.global),
+			cwd: adopted.get("cwd") ?? structuredClone(this.view!.scopes.cwd),
+			session: structuredClone(this.view!.scopes.session),
+		};
+		const head = "head" in captured ? captured.head : undefined;
+		return {
+			view: adoptTemporalStreams(streams, `${head ?? "unborn"}:reconcile:${randomUUID()}`),
+			base: captured,
+			provenance,
+		};
+	}
+
+	publish(
+		snapshot: Snapshot,
+		semantic = false,
+		accepted?: AcceptedTransition,
+		options: { pushRemote?: boolean; provenance?: Partial<Record<StateScope, Record<string, ArtifactProvenance>>> } = {},
+	): RuntimePublication | undefined {
+		if (!this.view || !this.base) throw new Error("State Flow temporal publication is unavailable; restore or initialize before accepting a transition");
+		// Activation and terminal policy: only the legacy transition mode publishes synchronously.
+		const pushRemote = options.pushRemote ?? (snapshot.meta.remotePublication?.mode ?? "transition") === "transition";
+		const provenanceScopes = SCOPES.filter((scope) => Object.entries(options.provenance?.[scope] ?? {})
+			.some(([path, entry]) => this.provenanceByScope[scope][path] === undefined
+				|| !sameJson(this.provenanceByScope[scope][path], entry)));
+		let basis = this.view;
+		let base: TemporalGitBase | TemporalFileBase = this.base;
+		let basisProvenance = this.provenanceByScope;
+		if ((semantic || provenanceScopes.length > 0) && this.semanticRevision) {
+			const changedScopes = new Set<StateScope>([
+				...(accepted?.transitions ?? []).map(({ scope }) => scope),
+				...provenanceScopes,
+			]);
+			const reconciled = this.reconcileSharedDrift(changedScopes);
+			basis = reconciled.view;
+			base = reconciled.base;
+			basisProvenance = reconciled.provenance;
+		}
+		const next = accepted ? advanceTemporalState(basis, accepted.transitions, accepted.id) : basis;
+		const nextProvenance = structuredClone(basisProvenance);
+		for (const scope of SCOPES) {
+			const updates = options.provenance?.[scope];
+			if (updates) for (const [path, entry] of Object.entries(updates)) nextProvenance[scope][path] = structuredClone(entry);
+		}
+		for (const scope of SCOPES) {
+			nextProvenance[scope] = pruneArtifactProvenance(nextProvenance[scope], readTemporalState(next, 0, scope).artifacts);
+		}
+		const provenanceChanged = !sameJson(nextProvenance, this.provenanceByScope);
+		const scopedWrite = semantic || provenanceChanged;
+		const runtime = createSessionRuntime(snapshot, this.cwd, this.sessionId, next.lineage, this.backend === "files" ? "files" : "unconfirmed", nextProvenance.session);
+		const fingerprint = hashJson(runtime);
+		if (!semantic && fingerprint === this.savedRuntime && !provenanceChanged) return undefined;
 		if (this.backend === "files") {
 			runtime.meta.temporalRevision = "self";
-			const result = publishTemporalStateToFiles(this.cwd, this.sessionId, next, semantic ? SCOPES : [], this.base, this.root, runtime, this.sessionKey);
+			const result = publishTemporalStateToFiles(this.cwd, this.sessionId, next, semantic ? SCOPES : [], base, this.root, runtime, this.sessionKey, nextProvenance);
 			this.base = result.base;
 			this.view = next;
+			this.provenanceByScope = nextProvenance;
 			this.savedRuntime = fingerprint;
 			this.semanticRevision = result.revision;
 			return { base: result.base, revision: result.revision };
 		}
-		if (!semantic) {
+		if (!scopedWrite) {
 			const current = captureTemporalGitBase(this.cwd, this.sessionId, this.root, this.sessionKey);
 			const paths = sessionRuntimePaths(this.cwd, this.sessionId, this.root, this.sessionKey);
 			for (const path of [paths.config, paths.meta]) {
-				if (current.files.find((file) => file.path === path)?.identity !== this.base.files.find((file) => file.path === path)?.identity) {
+				if (current.files.find((file) => file.path === path)?.identity !== base.files.find((file) => file.path === path)?.identity) {
 					throw new Error("Temporal State Flow runtime changed concurrently");
 				}
 			}
-			this.base = current;
+			base = current;
 		}
-		runtime.meta.temporalRevision = semantic ? "self" : this.semanticRevision!;
+		runtime.meta.temporalRevision = scopedWrite ? "self" : this.semanticRevision!;
 		const result = publishTemporalStateToGit(
-			this.cwd, this.sessionId, next, semantic ? SCOPES : [], this.base, this.root, runtime, this.sessionKey,
-			options.pushRemote !== false,
+			this.cwd, this.sessionId, next, semantic ? SCOPES : provenanceChanged ? provenanceScopes : [], base, this.root, runtime, this.sessionKey,
+			pushRemote,
+			nextProvenance,
 		);
 		this.base = result.base;
 		this.view = next;
+		this.provenanceByScope = nextProvenance;
 		this.savedRuntime = fingerprint;
-		if (semantic && result.commit) this.semanticRevision = result.commit;
+		if (scopedWrite && result.commit) this.semanticRevision = result.commit;
 		return result;
 	}
 }

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

@@ -3,6 +3,7 @@ import {
 	hashArtifactSource,
 	isArtifactHash,
 	type ArtifactMetadata,
+	type ArtifactProvenance,
 	type ArtifactRegistry,
 } from "./artifact.ts";
 import { canonicalJson, isObject, type JsonObject, type JsonValue } from "./json.ts";
@@ -19,16 +20,24 @@ function hasContent(value: unknown): boolean {
 
 export function hasCompiledSkillArtifact(
 	artifacts: ArtifactRegistry,
+	provenance: ArtifactProvenance | undefined,
 	source: string,
 	expectedHash?: string,
 ): boolean {
 	const metadata = artifacts[source];
-	return isObject(metadata)
-		&& metadata.kind === "skill"
-		&& metadata.compiler === SKILL_ARTIFACT_COMPILER
-		&& (expectedHash === undefined || metadata.hash === expectedHash)
-		&& isObject(metadata.compilation)
-		&& hasContent(metadata.compilation);
+	if (!isObject(metadata)
+		|| metadata.kind !== "skill"
+		|| !isObject(metadata.compilation)
+		|| !hasContent(metadata.compilation)
+		|| provenance?.malformed === true) return false;
+	const compilerRevision = provenance !== undefined && Object.hasOwn(provenance, "compilerRevision")
+		? provenance.compilerRevision
+		: metadata.compiler;
+	const sourceHash = provenance !== undefined && Object.hasOwn(provenance, "sourceHash")
+		? provenance.sourceHash
+		: metadata.hash;
+	return compilerRevision === SKILL_ARTIFACT_COMPILER
+		&& (expectedHash === undefined || sourceHash === expectedHash);
 }
 
 export type SkillSourceHasher = (source: string) => string;