@llblab/pi-kit 0.6.0 → 0.7.0

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

@@ -0,0 +1,273 @@
+import { createHash } from "node:crypto";
+import { containsNull, isJsonValue, isObject, type JsonObject } from "./json.ts";
+
+const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
+
+/** Current compiler protocol for ordinary source artifacts such as Knowledge Markdown. */
+export const ORDINARY_ARTIFACT_COMPILER = "artifact-v1";
+
+/** Source-addressed metadata retained after artifact compilation. */
+export type ArtifactMetadata = JsonObject & {
+	description: string;
+	hash: string;
+	compiler: string;
+	compiled_at?: string;
+	compilation?: JsonObject;
+	kind?: string;
+	tags?: string[];
+};
+
+/** Artifact source paths are the canonical registry keys. */
+export type ArtifactRegistry = JsonObject & Record<string, ArtifactMetadata>;
+
+/** Source identity is sufficient for freshness decisions; it never contains the source body. */
+export interface ArtifactSourceIdentity {
+	path: string;
+	hash: string;
+}
+
+export type ArtifactInvalidationReason =
+	| "new"
+	| "source-changed"
+	| "compiler-changed"
+	| "invalid-metadata"
+	| "explicit-refresh";
+
+export type ArtifactFreshness =
+	| { kind: "fresh" }
+	| { kind: "requires-compilation"; reason: ArtifactInvalidationReason };
+
+export interface ArtifactInvalidationRequest extends ArtifactSourceIdentity {
+	reason: ArtifactInvalidationReason;
+}
+
+export interface ArtifactInvalidationPlan {
+	fresh: ArtifactSourceIdentity[];
+	requiresCompilation: ArtifactInvalidationRequest[];
+	removed: string[];
+}
+
+export interface ArtifactInvalidationOptions {
+	/** Refresh every source, or only paths in the supplied set. */
+	explicitRefresh?: boolean | ReadonlySet<string>;
+}
+
+/** Compiler-owned fields before State Flow attaches trusted source freshness metadata. */
+export type ArtifactCompilerOutput = JsonObject & {
+	description: string;
+	compiled_at?: string;
+	compilation?: JsonObject;
+	kind?: string;
+	tags?: string[];
+};
+
+export interface ArtifactCompilationUpdate {
+	source: ArtifactSourceIdentity;
+	compiler: string;
+	output: ArtifactCompilerOutput;
+}
+
+export function hashArtifactSource(source: string | Uint8Array): string {
+	return `sha256:${createHash("sha256").update(source).digest("hex")}`;
+}
+
+export function isArtifactHash(value: unknown): value is string {
+	return typeof value === "string" && SHA256_PATTERN.test(value);
+}
+
+export function validateArtifactMetadata(value: unknown, path = "<unknown>"): asserts value is ArtifactMetadata {
+	if (!isObject(value) || !isJsonValue(value)) {
+		throw new Error(`Artifact metadata at ${path} must be finite, acyclic JSON data`);
+	}
+	if (containsNull(value)) throw new Error(`Artifact metadata at ${path} cannot contain null`);
+	if (typeof value.description !== "string" || value.description.trim().length === 0) {
+		throw new Error(`Artifact metadata at ${path} must have a non-empty description`);
+	}
+	if (!isArtifactHash(value.hash)) {
+		throw new Error(`Artifact metadata at ${path} must have a sha256:<64 lowercase hex characters> hash`);
+	}
+	if (typeof value.compiler !== "string" || value.compiler.trim().length === 0) {
+		throw new Error(`Artifact metadata at ${path} must have a non-empty compiler revision`);
+	}
+	if (Object.hasOwn(value, "compiled_at") && typeof value.compiled_at !== "string") {
+		throw new Error(`Artifact metadata at ${path} compiled_at must be a string`);
+	}
+	if (Object.hasOwn(value, "compilation") && !isObject(value.compilation)) {
+		throw new Error(`Artifact metadata at ${path} compilation must be an object`);
+	}
+	if (Object.hasOwn(value, "kind")
+		&& (typeof value.kind !== "string" || value.kind.trim().length === 0)) {
+		throw new Error(`Artifact metadata at ${path} kind must be a non-empty string`);
+	}
+	if (Object.hasOwn(value, "tags") && (!Array.isArray(value.tags)
+		|| value.tags.some((tag) => typeof tag !== "string" || tag.trim().length === 0 || tag !== tag.trim())
+		|| new Set(value.tags).size !== value.tags.length)) {
+		throw new Error(`Artifact metadata at ${path} tags must be unique non-empty trimmed strings`);
+	}
+}
+
+export function isArtifactMetadata(value: unknown): value is ArtifactMetadata {
+	try {
+		validateArtifactMetadata(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export function validateArtifactRegistry(value: unknown): asserts value is ArtifactRegistry {
+	if (!isObject(value)) throw new Error("Artifacts must be a path-keyed JSON object");
+	for (const [path, metadata] of Object.entries(value)) {
+		if (path.trim().length === 0) throw new Error("Artifact path keys must be non-empty");
+		validateArtifactMetadata(metadata, path);
+	}
+}
+
+export function selectArtifactsByTags(
+	registry: ArtifactRegistry,
+	tags: readonly string[],
+	match: "all" | "any" = "all",
+): string[] {
+	validateArtifactRegistry(registry);
+	if (tags.length === 0 || tags.some((tag) => typeof tag !== "string" || tag.trim().length === 0 || tag !== tag.trim())) {
+		throw new Error("Artifact tag query requires one or more non-empty trimmed strings");
+	}
+	const requested = new Set(tags);
+	return Object.entries(registry)
+		.filter(([, metadata]) => {
+			const available = new Set(metadata.tags ?? []);
+			return match === "all"
+				? [...requested].every((tag) => available.has(tag))
+				: [...requested].some((tag) => available.has(tag));
+		})
+		.map(([path]) => path)
+		.sort();
+}
+
+export function isArtifactRegistry(value: unknown): value is ArtifactRegistry {
+	try {
+		validateArtifactRegistry(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function validateSourceIdentity(source: ArtifactSourceIdentity): void {
+	if (typeof source.path !== "string" || source.path.trim().length === 0) {
+		throw new Error("Artifact source path must be non-empty");
+	}
+	if (!isArtifactHash(source.hash)) {
+		throw new Error(`Artifact source at ${source.path} must have a sha256:<64 lowercase hex characters> hash`);
+	}
+}
+
+function validateCompilerRevision(compiler: string, path?: string): void {
+	if (typeof compiler !== "string" || compiler.trim().length === 0) {
+		throw new Error(path === undefined
+			? "Artifact compiler revision must be non-empty"
+			: `Artifact compiler revision at ${path} must be non-empty`);
+	}
+}
+
+function refreshRequested(path: string, explicitRefresh: boolean | ReadonlySet<string> | undefined): boolean {
+	if (explicitRefresh === true) return true;
+	if (!explicitRefresh || typeof explicitRefresh !== "object" || typeof explicitRefresh.has !== "function") return false;
+	return explicitRefresh.has(path);
+}
+
+/** Classify freshness from source identity and metadata without acquiring the source body. */
+export function classifyArtifactFreshness(
+	source: ArtifactSourceIdentity,
+	metadata: unknown,
+	compiler: string,
+	explicitRefresh = false,
+): ArtifactFreshness {
+	validateSourceIdentity(source);
+	validateCompilerRevision(compiler);
+	if (metadata === undefined) return { kind: "requires-compilation", reason: "new" };
+	if (!isArtifactMetadata(metadata)) return { kind: "requires-compilation", reason: "invalid-metadata" };
+	if (metadata.hash !== source.hash) return { kind: "requires-compilation", reason: "source-changed" };
+	if (metadata.compiler !== compiler) return { kind: "requires-compilation", reason: "compiler-changed" };
+	if (explicitRefresh) return { kind: "requires-compilation", reason: "explicit-refresh" };
+	return { kind: "fresh" };
+}
+
+/** Produce a deterministic acquisition plan from path/hash candidates alone. */
+export function planArtifactInvalidation(
+	sources: readonly ArtifactSourceIdentity[],
+	registry: Readonly<Record<string, unknown>>,
+	compiler: string,
+	options: ArtifactInvalidationOptions = {},
+): ArtifactInvalidationPlan {
+	if (!isObject(registry)) throw new Error("Artifacts must be a path-keyed JSON object");
+	validateCompilerRevision(compiler);
+	const ordered = [...sources].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+	const seen = new Set<string>();
+	const fresh: ArtifactSourceIdentity[] = [];
+	const requiresCompilation: ArtifactInvalidationRequest[] = [];
+	for (const source of ordered) {
+		if (seen.has(source.path)) throw new Error(`Duplicate artifact source path: ${source.path}`);
+		seen.add(source.path);
+		const metadata = Object.hasOwn(registry, source.path) ? registry[source.path] : undefined;
+		const freshness = classifyArtifactFreshness(
+			source,
+			metadata,
+			compiler,
+			refreshRequested(source.path, options.explicitRefresh),
+		);
+		const identity = { path: source.path, hash: source.hash };
+		if (freshness.kind === "fresh") fresh.push(identity);
+		else requiresCompilation.push({ ...identity, reason: freshness.reason });
+	}
+	const removed = Object.keys(registry).filter((path) => !seen.has(path)).sort();
+	return { fresh, requiresCompilation, removed };
+}
+
+function compilationMetadata(update: ArtifactCompilationUpdate): ArtifactMetadata {
+	validateSourceIdentity(update.source);
+	validateCompilerRevision(update.compiler, update.source.path);
+	if (!isObject(update.output) || Object.hasOwn(update.output, "hash") || Object.hasOwn(update.output, "compiler")) {
+		throw new Error(`Artifact compiler output at ${update.source.path} cannot set runtime-owned hash or compiler fields`);
+	}
+	const metadata = {
+		...structuredClone(update.output),
+		hash: update.source.hash,
+		compiler: update.compiler,
+	};
+	validateArtifactMetadata(metadata, update.source.path);
+	return metadata;
+}
+
+/** Validate and apply a whole compilation/removal cohort without mutating the prior registry. */
+export function updateArtifactRegistry(
+	registry: ArtifactRegistry,
+	updates: readonly ArtifactCompilationUpdate[],
+	removed: readonly string[] = [],
+): ArtifactRegistry {
+	validateArtifactRegistry(registry);
+	const compiled = new Map<string, ArtifactMetadata>();
+	for (const update of updates) {
+		if (compiled.has(update.source.path)) throw new Error(`Duplicate artifact compilation: ${update.source.path}`);
+		compiled.set(update.source.path, compilationMetadata(update));
+	}
+	const removals = new Set<string>();
+	for (const path of removed) {
+		if (typeof path !== "string" || path.trim().length === 0) throw new Error("Removed artifact paths must be non-empty");
+		if (removals.has(path)) throw new Error(`Duplicate artifact removal: ${path}`);
+		if (compiled.has(path)) throw new Error(`Artifact cannot be compiled and removed atomically: ${path}`);
+		removals.add(path);
+	}
+
+	const next = structuredClone(registry);
+	for (const path of removals) delete next[path];
+	for (const [path, metadata] of compiled) {
+		Object.defineProperty(next, path, {
+			value: metadata,
+			enumerable: true,
+			configurable: true,
+			writable: true,
+		});
+	}
+	return next;
+}

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

@@ -0,0 +1,48 @@
+// Domain: agent-level State Flow configuration, independent of session runtime and semantic state.
+import { lstatSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { getDurableRepositoryRoot } from "./durable.ts";
+import { isObject } from "./json.ts";
+
+export interface StateFlowConfig {
+	directory: string;
+	autoStart: boolean;
+	remotePublication?: "off" | "turn-end" | "transition";
+}
+
+/** Read once at extension load/reload. Missing config uses defaults; invalid config never falls back. */
+export function loadStateFlowConfig(agentDir = getAgentDir()): StateFlowConfig {
+	const path = resolve(agentDir, "state-flow.json");
+	const defaults: StateFlowConfig = {
+		directory: getDurableRepositoryRoot(agentDir),
+		autoStart: false,
+	};
+	let value: unknown;
+	try {
+		if (!lstatSync(path, { throwIfNoEntry: false })) return defaults;
+		value = JSON.parse(readFileSync(path, "utf8"));
+	} catch (error) {
+		throw new Error(`Cannot read State Flow configuration: ${path}`, { cause: error });
+	}
+	const allowed = new Set(["directory", "autoStart", "remotePublication"]);
+	if (!isObject(value) || Object.keys(value).some((key) => !allowed.has(key))) {
+		throw new Error(`State Flow configuration contains unknown settings: ${path}`);
+	}
+	if (Object.hasOwn(value, "autoStart") && typeof value.autoStart !== "boolean") throw new Error(`State Flow autoStart must be a boolean: ${path}`);
+	if (Object.hasOwn(value, "remotePublication") && value.remotePublication !== "off" && value.remotePublication !== "turn-end" && value.remotePublication !== "transition") {
+		throw new Error(`State Flow remotePublication must be off, turn-end, or transition: ${path}`);
+	}
+	if (Object.hasOwn(value, "directory") && (typeof value.directory !== "string" || !value.directory.trim() || value.directory.includes("\0"))) {
+		throw new Error(`State Flow directory must be a non-empty path: ${path}`);
+	}
+	const directory = value.directory as string | undefined;
+	if (directory?.startsWith("~") && directory !== "~" && !directory.startsWith("~/")) throw new Error(`State Flow directory supports ~ or ~/ paths, not named-user expansion: ${path}`);
+	const expanded = directory === "~" ? homedir() : directory?.startsWith("~/") ? resolve(homedir(), directory.slice(2)) : directory;
+	return {
+		directory: expanded === undefined ? defaults.directory : resolve(dirname(path), expanded),
+		autoStart: value.autoStart === true,
+		...(value.remotePublication === undefined ? {} : { remotePublication: value.remotePublication as "off" | "turn-end" | "transition" }),
+	};
+}

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

@@ -1,6 +1,10 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ArtifactInvalidationRequest } from "./artifact.ts";
+import type { RecentTransitionWindow } from "./history.ts";
 import { canonicalJson } from "./json.ts";
 import type { Snapshot } from "./snapshot.ts";
+import type { RehydrationPhase } from "./rehydration.ts";
+import type { MaterializedState } from "./state.ts";
 
 export const VALIDATION_MESSAGE_TYPE = "state-flow-validation";
 
@@ -28,14 +32,23 @@ export function withoutPrivateValidation(messages: AgentMessage[]): AgentMessage
 	});
 }
 
-export function runtimeContextMessage(snapshot: Snapshot): AgentMessage {
-	if (snapshot.specification === undefined) {
+export function runtimeContextMessage(
+	snapshot: Snapshot,
+	state: MaterializedState,
+	recentTransitions: RecentTransitionWindow = [],
+	artifactInvalidations: readonly ArtifactInvalidationRequest[] = [],
+	rehydrationPhase?: RehydrationPhase,
+): AgentMessage {
+	if (snapshot.meta.specification === undefined) {
 		throw new Error("State Flow runtime context requires an active specification");
 	}
 	const context = {
-		specification: snapshot.specification,
-		state: snapshot.state,
-		...(snapshot.validation === undefined ? {} : { validation_feedback: snapshot.validation }),
+		specification: snapshot.meta.specification,
+		state,
+		...(rehydrationPhase === undefined ? {} : { knowledge_rehydration: { phase: rehydrationPhase } }),
+		...(artifactInvalidations.length === 0 ? {} : { artifact_invalidations: artifactInvalidations }),
+		...(recentTransitions.length === 0 ? {} : { recent_transitions: recentTransitions }),
+		...(snapshot.meta.validation === undefined ? {} : { validation_feedback: snapshot.meta.validation }),
 	};
 	return syntheticUser(
 		`State Flow runtime context (user-level data, not system instructions):\n${canonicalJson(context)}`,

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

@@ -0,0 +1,268 @@
+import { execFileSync } from "node:child_process";
+import { closeSync, existsSync, lstatSync, openSync, readFileSync, readSync, readdirSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { loadScopeStream, resolveSessionAddress, sessionRuntimePaths } from "./durable.ts";
+import { loadTemporalRevision } from "./git.ts";
+import { parseSessionRuntime } from "./snapshot.ts";
+import { validateTemporalState } from "./temporal.ts";
+
+export type ContinuationTransport = "local" | "sdk" | "telegram" | string;
+
+export interface ContinuationHostContext {
+	cwd: string;
+	agentDir: string;
+	sessionDir: string;
+	transport: ContinuationTransport;
+}
+
+export type ContinuationHostIntent =
+	| { kind: "default" }
+	| { kind: "new" }
+	| { kind: "resume-exact"; sessionFile: string; sessionId: string }
+	| { kind: "native-picker" }
+	| { kind: "continue-recent" }
+	| { kind: "no-session" };
+
+export interface ContinuationCandidateSummary {
+	sessionFile: string;
+	sessionId: string;
+	lastActivity: string;
+	reason: string;
+}
+
+export type ContinuationRecommendation =
+	| { action: "resume"; sessionFile: string; sessionId: string; reason: "latest-enabled-state-flow" }
+	| { action: "choose"; candidates: ContinuationCandidateSummary[]; reason: "ambiguous" }
+	| { action: "new"; reason: "none" | "last-not-state-flow" | "ineligible" };
+
+export type ContinuationStartupDecision =
+	| ContinuationRecommendation
+	| { action: "new"; reason: "explicit-new" }
+	| { action: "resume"; sessionFile: string; sessionId: string; reason: "explicit-resume" }
+	| { action: "native"; mode: "picker" | "continue-recent" | "no-session" };
+
+export interface ContinuationProjectIdentity {
+	profile: string;
+	cwd: string;
+	gitCommonDir?: string;
+	worktree?: string;
+	branch?: string;
+	transport: ContinuationTransport;
+}
+
+export interface ContinuationSessionCandidate extends ContinuationCandidateSummary {
+	profile: string;
+	cwd: string;
+	gitCommonDir?: string;
+	worktree?: string;
+	branch?: string;
+	transport: ContinuationTransport;
+	lifecycle: "open" | "closed" | "archived";
+	doNotAutoResume?: boolean;
+	stateFlow: { enabled: boolean; restorable: boolean };
+}
+
+export type ContinuationRecommender = (
+	context: Readonly<ContinuationHostContext>,
+) => ContinuationRecommendation | Promise<ContinuationRecommendation>;
+
+/**
+ * Preserve host-owned explicit session intent and consult State Flow only for
+ * an ordinary default launch. The recommender is a read-only advisory port;
+ * opening or claiming a native session remains the host's responsibility.
+ */
+function sameOptionalIdentity(current: string | undefined, candidate: string | undefined): boolean {
+	return current === undefined ? candidate === undefined : candidate === current;
+}
+
+function structurallyRelevant(identity: ContinuationProjectIdentity, candidate: ContinuationSessionCandidate): boolean {
+	return candidate.profile === identity.profile
+		&& candidate.cwd === identity.cwd
+		&& candidate.transport === identity.transport
+		&& candidate.lifecycle === "open"
+		&& candidate.doNotAutoResume !== true
+		&& sameOptionalIdentity(identity.gitCommonDir, candidate.gitCommonDir)
+		&& sameOptionalIdentity(identity.worktree, candidate.worktree)
+		&& sameOptionalIdentity(identity.branch, candidate.branch)
+		&& Number.isFinite(Date.parse(candidate.lastActivity));
+}
+
+/** Rank already header/provenance-only candidates without transcript content or I/O. */
+export function recommendContinuationFromProvenance(
+	identity: ContinuationProjectIdentity,
+	candidates: readonly ContinuationSessionCandidate[],
+): ContinuationRecommendation {
+	const relevant = candidates.filter((candidate) => structurallyRelevant(identity, candidate));
+	if (relevant.length === 0) return { action: "new", reason: "none" };
+	const latestTime = Math.max(...relevant.map(({ lastActivity }) => Date.parse(lastActivity)));
+	const latest = relevant.filter(({ lastActivity }) => Date.parse(lastActivity) === latestTime)
+		.sort((left, right) => left.sessionFile.localeCompare(right.sessionFile));
+	if (latest.length > 1) {
+		const resumable = latest.filter(({ stateFlow }) => stateFlow.enabled && stateFlow.restorable);
+		if (resumable.length > 1) return { action: "choose", reason: "ambiguous", candidates: resumable.map(({ sessionFile, sessionId, lastActivity }) => ({ sessionFile, sessionId, lastActivity, reason: "equally recent enabled State Flow session" })) };
+		if (resumable.length === 1 && latest.every(({ stateFlow }) => stateFlow.enabled && stateFlow.restorable)) {
+			const candidate = resumable[0];
+			return { action: "resume", sessionFile: candidate.sessionFile, sessionId: candidate.sessionId, reason: "latest-enabled-state-flow" };
+		}
+		return { action: "new", reason: "ineligible" };
+	}
+	const candidate = latest[0];
+	if (!candidate.stateFlow.enabled) return { action: "new", reason: "last-not-state-flow" };
+	if (!candidate.stateFlow.restorable) return { action: "new", reason: "ineligible" };
+	return { action: "resume", sessionFile: candidate.sessionFile, sessionId: candidate.sessionId, reason: "latest-enabled-state-flow" };
+}
+
+export async function resolveContinuationStartup(
+	context: ContinuationHostContext,
+	intent: ContinuationHostIntent,
+	recommend: ContinuationRecommender,
+): Promise<ContinuationStartupDecision> {
+	switch (intent.kind) {
+		case "new":
+			return { action: "new", reason: "explicit-new" };
+		case "resume-exact":
+			return { action: "resume", sessionFile: intent.sessionFile, sessionId: intent.sessionId, reason: "explicit-resume" };
+		case "native-picker":
+			return { action: "native", mode: "picker" };
+		case "continue-recent":
+			return { action: "native", mode: "continue-recent" };
+		case "no-session":
+			return { action: "native", mode: "no-session" };
+		case "default":
+			return recommend(Object.freeze({ ...context }));
+	}
+}
+
+const MAX_SESSION_HEADER_BYTES = 64 * 1024;
+
+export interface NativeSessionHeader {
+	file: string;
+	id: string;
+	cwd: string;
+	timestamp: string;
+	lastActivity: string;
+}
+
+export interface ContinuationCandidateProvenance {
+	profile: string;
+	gitCommonDir?: string;
+	worktree?: string;
+	branch?: string;
+	transport: ContinuationTransport;
+	lifecycle: "open" | "closed" | "archived";
+	doNotAutoResume?: boolean;
+	stateFlow: { enabled: boolean; restorable: boolean };
+	reason: string;
+}
+
+function readFirstLine(path: string): string {
+	const fd = openSync(path, "r");
+	try {
+		const bytes: number[] = [];
+		const byte = Buffer.allocUnsafe(1);
+		while (bytes.length <= MAX_SESSION_HEADER_BYTES) {
+			const count = readSync(fd, byte, 0, 1, null);
+			if (count === 0 || byte[0] === 0x0a) break;
+			bytes.push(byte[0]);
+		}
+		if (bytes.length > MAX_SESSION_HEADER_BYTES) throw new Error("Native Pi session header exceeds the safe discovery limit");
+		return Buffer.from(bytes).toString("utf8").replace(/\r$/, "");
+	} finally {
+		closeSync(fd);
+	}
+}
+
+export function readNativeSessionHeader(path: string): NativeSessionHeader {
+	const file = resolve(path);
+	let value: unknown;
+	try {
+		value = JSON.parse(readFirstLine(file));
+	} catch (error) {
+		throw new Error(`Cannot read native Pi session header: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("Invalid native Pi session header");
+	const header = value as Record<string, unknown>;
+	if (header.type !== "session" || typeof header.id !== "string" || header.id.trim().length === 0
+		|| typeof header.cwd !== "string" || header.cwd.trim().length === 0
+		|| typeof header.timestamp !== "string" || !Number.isFinite(Date.parse(header.timestamp))) {
+		throw new Error("Invalid native Pi session header");
+	}
+	const stats = statSync(file);
+	return { file, id: header.id, cwd: resolve(header.cwd), timestamp: header.timestamp, lastActivity: stats.mtime.toISOString() };
+}
+
+export function discoverNativeSessionHeaders(sessionDir: string): { headers: NativeSessionHeader[]; invalid: Array<{ file: string; error: string }> } {
+	const headers: NativeSessionHeader[] = [];
+	const invalid: Array<{ file: string; error: string }> = [];
+	for (const entry of readdirSync(sessionDir, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+		if (!entry.isFile() || !entry.name.endsWith(".jsonl")) continue;
+		const file = join(sessionDir, entry.name);
+		try {
+			headers.push(readNativeSessionHeader(file));
+		} catch (error) {
+			invalid.push({ file: resolve(file), error: error instanceof Error ? error.message : String(error) });
+		}
+	}
+	return { headers, invalid };
+}
+
+function readRegular(path: string): string | undefined {
+	if (!existsSync(path)) return undefined;
+	if (!lstatSync(path).isFile()) throw new Error("State Flow continuation provenance must be a regular file");
+	return readFileSync(path, "utf8");
+}
+
+/** Inspect only exact current runtime provenance; never initialize, migrate, lock, checkout, or publish. */
+export function inspectStateFlowContinuationProvenance(
+	header: NativeSessionHeader,
+	repositoryRoot: string,
+): Pick<ContinuationCandidateProvenance, "stateFlow" | "reason"> {
+	const sessionKey = resolveSessionAddress(header.file, header.id, header.timestamp).key;
+	const paths = sessionRuntimePaths(header.cwd, header.id, repositoryRoot, sessionKey);
+	try {
+		const config = readRegular(paths.config);
+		const meta = readRegular(paths.meta);
+		if (config === undefined && meta === undefined) {
+			return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
+		}
+		const runtime = parseSessionRuntime(config, meta, header.cwd, header.id);
+		if (!runtime) return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
+		if (!runtime.config.enabled) return { stateFlow: { enabled: false, restorable: true }, reason: "State Flow stopped on selected runtime" };
+		if (runtime.meta.publication === "files") {
+			const global = loadScopeStream(header.cwd, header.id, "global", repositoryRoot, sessionKey);
+			const cwd = loadScopeStream(header.cwd, header.id, "cwd", repositoryRoot, sessionKey);
+			const session = loadScopeStream(header.cwd, header.id, "session", repositoryRoot, sessionKey);
+			if (!global || !cwd || !session) throw new Error("incomplete file-only temporal cohort");
+			validateTemporalState({ lineage: runtime.meta.lineage, scopes: { global, cwd, session } });
+			return { stateFlow: { enabled: true, restorable: true }, reason: "exact file-only runtime cohort is restorable" };
+		}
+		const runtimePath = relative(resolve(repositoryRoot), paths.meta);
+		if (runtimePath.startsWith("..")) throw new Error("runtime provenance escapes repository");
+		const owner = execFileSync("git", ["-C", repositoryRoot, "log", "-1", "--format=%H", "--", runtimePath], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+		if (!owner) throw new Error("runtime owner commit is unavailable");
+		const restored = loadTemporalRevision(header.cwd, header.id, repositoryRoot, owner, sessionKey);
+		if (!restored.runtime || !restored.runtime.document.config.enabled) throw new Error("selected Git runtime is not enabled");
+		return { stateFlow: { enabled: true, restorable: true }, reason: `exact Git runtime ${owner.slice(0, 12)} is restorable` };
+	} catch (error) {
+		return { stateFlow: { enabled: true, restorable: false }, reason: `State Flow runtime is ineligible: ${error instanceof Error ? error.message : String(error)}` };
+	}
+}
+
+export function buildContinuationCandidates(
+	headers: readonly NativeSessionHeader[],
+	inspect: (header: Readonly<NativeSessionHeader>) => ContinuationCandidateProvenance | undefined,
+): ContinuationSessionCandidate[] {
+	const candidates: ContinuationSessionCandidate[] = [];
+	for (const header of headers) {
+		const provenance = inspect(Object.freeze({ ...header }));
+		if (!provenance) continue;
+		candidates.push({
+			sessionFile: header.file,
+			sessionId: header.id,
+			lastActivity: header.lastActivity,
+			cwd: header.cwd,
+			...provenance,
+		});
+	}
+	return candidates;
+}