@llblab/pi-kit 0.6.0 → 0.7.1

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

@@ -1,16 +1,139 @@
-import { applyPatch, containsNull, isJsonValue, isObject, type JsonObject } from "./json.ts";
-import { emptyState, isStateDocument, type StateDocument } from "./state.ts";
+import { resolve } from "node:path";
+import { RECENT_TRANSITION_LIMIT } from "./history.ts";
+import { parseRemotePublicationPolicyDocument, serializeRemotePublicationPolicyDocument, type RemotePublicationPolicyDocument } from "./publication.ts";
+import { applyPatch, canonicalJson, containsNull, isJsonValue, isObject, type JsonObject } from "./json.ts";
+import { validateTemporalLineage, type TransitionBoundary } from "./temporal.ts";
+import { migrateLegacySkillCompilations } from "./skills.ts";
+import { isMaterializedState, type MaterializedState } from "./state.ts";
 import { MAX_VALIDATION_RETRIES, type ValidationFeedback } from "./validation.ts";
 
 const MAX_RESTORED_STEP = Number.MAX_SAFE_INTEGER - 1;
 
-export interface Snapshot {
+/** Missing operational capability is not evidence that a checkpoint target is invalid. */
+export class RevisionUnavailableError extends Error {}
+
+export interface SnapshotConfig {
 	enabled: boolean;
-	specification?: string;
-	state: StateDocument;
+	transitionWindow: number;
+}
+
+export interface PendingPublicationState {
+	commit: string;
+	error: string;
+}
+
+export interface SnapshotMeta {
+	durableBase?: string;
+	pendingPublication?: PendingPublicationState;
 	step: number;
+	specification?: string;
 	validation?: ValidationFeedback;
 	bootstrap?: boolean;
+	remotePublication?: RemotePublicationPolicyDocument;
+}
+
+export interface LegacySessionMigration {
+	state: MaterializedState;
+}
+
+/** In-memory runtime config/provenance; durable config/meta and scope files own restoration. */
+export interface StateFlowSnapshot {
+	config: SnapshotConfig;
+	meta: SnapshotMeta;
+	/** Ephemeral one-way migration payload. persistSnapshot() never writes it to Pi checkpoints. */
+	legacySession?: LegacySessionMigration;
+}
+
+export type Snapshot = StateFlowSnapshot;
+
+export interface SessionRuntime {
+	config: SnapshotConfig;
+	meta: Omit<SnapshotMeta, "durableBase" | "pendingPublication"> & {
+		version: 1;
+		identity: { cwd: string; sessionId: string };
+		lineage: TransitionBoundary[];
+		/** Resolved against the commit that last wrote this runtime record, not arbitrary HEAD. */
+		revision: "self";
+		temporalRevision?: "self" | string;
+		/** Durable intent survives a crash before the push result can be observed. */
+		publication: "unconfirmed" | "files";
+	};
+}
+
+export function validateSessionRuntime(value: unknown, cwd: string, sessionId: string): asserts value is SessionRuntime {
+	if (!isJsonValue(value) || !isObject(value) || Object.keys(value).sort().join(",") !== "config,meta"
+		|| !isObject(value.config) || !isObject(value.meta)) throw new Error("Invalid State Flow session runtime envelope");
+	const { version, identity, lineage, revision, temporalRevision, publication, ...fields } = value.meta;
+	if (temporalRevision !== undefined && temporalRevision !== "self"
+		&& !isExactRevision(temporalRevision)) throw new Error("Invalid temporal revision reference");
+	if (version !== 1 || revision !== "self" || (publication !== "unconfirmed" && publication !== "files")) throw new Error("Unsupported State Flow runtime provenance format");
+	if (publication === "files" && temporalRevision !== undefined && temporalRevision !== "self") throw new Error("File runtime cannot select a historical temporal revision");
+	if (!isObject(identity) || Object.keys(identity).sort().join(",") !== "cwd,sessionId"
+		|| identity.cwd !== resolve(cwd) || identity.sessionId !== sessionId || sessionId.trim().length === 0 || sessionId !== sessionId.trim()) {
+		throw new Error("State Flow runtime scope identity mismatch");
+	}
+	validateTemporalLineage(lineage);
+	const allowed = new Set(["step", "specification", "validation", "bootstrap", "remotePublication"]);
+	if (Object.keys(fields).some((key) => !allowed.has(key))) throw new Error("Unexpected State Flow runtime metadata field");
+	const normalized = migrateSnapshot({ config: value.config, meta: fields });
+	if (fields.bootstrap === false) normalized.meta.bootstrap = false;
+	if (fields.step === Number.MAX_SAFE_INTEGER) normalized.meta.step = Number.MAX_SAFE_INTEGER;
+	if (canonicalJson({ config: normalized.config, meta: normalized.meta }) !== canonicalJson({ config: value.config, meta: fields })) {
+		throw new Error("Invalid State Flow runtime configuration or counters");
+	}
+}
+
+export function createSessionRuntime(snapshot: Snapshot, cwd: string, sessionId: string, lineage: readonly TransitionBoundary[], publication: SessionRuntime["meta"]["publication"] = "unconfirmed"): SessionRuntime {
+	const { durableBase: _base, pendingPublication: _publication, ...fields } = snapshot.meta;
+	const runtime: SessionRuntime = {
+		config: structuredClone(snapshot.config),
+		meta: {
+			...Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined)) as Omit<SnapshotMeta, "durableBase" | "pendingPublication">,
+			version: 1,
+			identity: { cwd: resolve(cwd), sessionId },
+			lineage: structuredClone([...lineage]),
+			revision: "self",
+			publication,
+		},
+	};
+	validateSessionRuntime(runtime, cwd, sessionId);
+	return runtime;
+}
+
+export function serializeSessionRuntime(runtime: SessionRuntime, cwd: string, sessionId: string): { config: string; meta: string } {
+	validateSessionRuntime(runtime, cwd, sessionId);
+	return { config: `${canonicalJson(runtime.config)}\n`, meta: `${canonicalJson(runtime.meta)}\n` };
+}
+
+export function parseSessionRuntime(config: string | undefined, meta: string | undefined, cwd: string, sessionId: string): SessionRuntime | undefined {
+	if (config === undefined && meta === undefined) return undefined;
+	if (config === undefined || meta === undefined) throw new Error("Incomplete State Flow config/meta pair");
+	let runtime: unknown;
+	try {
+		runtime = { config: JSON.parse(config), meta: JSON.parse(meta) };
+	} catch {
+		throw new Error("State Flow session runtime contains invalid JSON");
+	}
+	validateSessionRuntime(runtime, cwd, sessionId);
+	return runtime;
+}
+
+export function resolveSessionRuntime(runtime: SessionRuntime, revision: string): { snapshot: Snapshot; lineage: TransitionBoundary[]; publicationTarget: string } {
+	validateSessionRuntime(runtime, runtime.meta.identity.cwd, runtime.meta.identity.sessionId);
+	if (!isExactRevision(revision) || runtime.meta.publication !== "unconfirmed") throw new Error("Runtime self reference requires its exact Git revision and Git publication provenance");
+	const { version: _version, identity: _identity, lineage, revision: _self, temporalRevision: _temporal, publication: _intent, ...fields } = runtime.meta;
+	return {
+		snapshot: { config: structuredClone(runtime.config), meta: { ...structuredClone(fields), durableBase: revision } },
+		lineage: structuredClone(lineage),
+		publicationTarget: revision,
+	};
+}
+
+export function resolveFileSessionRuntime(runtime: SessionRuntime, revision: string): Snapshot {
+	validateSessionRuntime(runtime, runtime.meta.identity.cwd, runtime.meta.identity.sessionId);
+	if (!isFileRevision(revision) || runtime.meta.publication !== "files") throw new Error("File runtime requires its exact file revision and file publication provenance");
+	const { version: _version, identity: _identity, lineage: _lineage, revision: _self, temporalRevision: _temporal, publication: _intent, ...fields } = runtime.meta;
+	return { config: structuredClone(runtime.config), meta: { ...structuredClone(fields), durableBase: revision } };
 }
 
 function isLegacyTwoPartState(value: unknown): value is { contract: JsonObject; working: JsonObject } {
@@ -20,6 +143,14 @@ function isLegacyTwoPartState(value: unknown): value is { contract: JsonObject;
 		&& Object.keys(value).every((key) => key === "contract" || key === "working");
 }
 
+function isLegacyThreePartState(value: unknown): value is { contract: JsonObject; working: JsonObject; response: string } {
+	return isObject(value)
+		&& isObject(value.contract)
+		&& isObject(value.working)
+		&& typeof value.response === "string"
+		&& Object.keys(value).every((key) => key === "contract" || key === "working" || key === "response");
+}
+
 function restoredStep(value: unknown): number {
 	return typeof value === "number"
 		&& Number.isSafeInteger(value)
@@ -43,61 +174,187 @@ function restoredValidation(value: unknown): ValidationFeedback | undefined {
 	};
 }
 
-export function migrationFailure(data: JsonObject, error: string): Snapshot {
+function restoredTransitionWindow(value: unknown): number {
+	return Number.isSafeInteger(value)
+		&& (value as number) >= 0
+		&& (value as number) <= RECENT_TRANSITION_LIMIT
+		? value as number
+		: RECENT_TRANSITION_LIMIT;
+}
+
+function restoredPendingPublication(value: unknown): PendingPublicationState | undefined {
+	if (!isObject(value)
+		|| typeof value.commit !== "string"
+		|| !/^[0-9a-f]{40,64}$/.test(value.commit)
+		|| typeof value.error !== "string"
+		|| value.error.trim().length === 0) return undefined;
+	return { commit: value.commit, error: value.error };
+}
+
+function restoredMeta(value: unknown, legacy: JsonObject = {}): SnapshotMeta {
+	const meta = isObject(value) ? value : legacy;
+	const pendingPublication = restoredPendingPublication(meta.pendingPublication);
+	const validation = restoredValidation(meta.validation);
+	let remotePublication: RemotePublicationPolicyDocument | undefined;
+	try {
+		if (meta.remotePublication !== undefined) remotePublication = serializeRemotePublicationPolicyDocument(
+			parseRemotePublicationPolicyDocument(meta.remotePublication, { legacyRuntime: false }),
+		);
+	} catch {
+		remotePublication = undefined;
+	}
 	return {
-		enabled: false,
-		specification: typeof data.specification === "string" ? data.specification : undefined,
-		state: emptyState(),
-		step: restoredStep(data.step),
-		validation: {
-			attempt: 0,
-			error,
-			instruction: "Start a fresh State Flow episode; null is reserved for patch deletion.",
-		},
+		...(isDurableRevision(meta.durableBase)
+			? { durableBase: meta.durableBase }
+			: {}),
+		...(pendingPublication === undefined ? {} : { pendingPublication }),
+		step: restoredStep(meta.step),
+		...(typeof meta.specification === "string" ? { specification: meta.specification } : {}),
+		...(validation === undefined ? {} : { validation }),
+		...(meta.bootstrap === true ? { bootstrap: true } : {}),
+		...(remotePublication === undefined ? {} : { remotePublication }),
 	};
 }
 
-export function migrateSnapshot(value: unknown): Snapshot {
-	if (!isObject(value)) return { enabled: false, state: emptyState(), step: 0 };
-	const base = {
-		enabled: value.enabled === true,
-		specification: typeof value.specification === "string" ? value.specification : undefined,
-		step: restoredStep(value.step),
-		validation: restoredValidation(value.validation),
-		bootstrap: value.bootstrap === true,
+function envelope(
+	enabled: boolean,
+	meta: SnapshotMeta,
+	transitionWindow = RECENT_TRANSITION_LIMIT,
+	legacySession?: LegacySessionMigration,
+): Snapshot {
+	return {
+		config: { enabled, transitionWindow },
+		meta,
+		...(legacySession === undefined ? {} : { legacySession }),
+	};
+}
+
+export function emptySnapshot(enabled = false): Snapshot {
+	return envelope(enabled, { step: 0 });
+}
+
+export type PiCheckpoint = { revision: string } | { disabled: true };
+export type FileRevision = `file:${string}`;
+
+export function isFileRevision(value: unknown): value is FileRevision {
+	return typeof value === "string" && /^file:[0-9a-f]{64}$/.test(value);
+}
+
+export function isDurableRevision(value: unknown): value is string {
+	return isExactRevision(value) || isFileRevision(value);
+}
+
+export function isExactRevision(value: unknown): value is string {
+	return typeof value === "string" && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(value);
+}
+
+export function persistableSnapshot(snapshot: Snapshot): PiCheckpoint {
+	if (snapshot.meta.durableBase !== undefined) {
+		if (!isDurableRevision(snapshot.meta.durableBase)) throw new Error("Checkpoint requires an exact Git revision or file reference");
+		return { revision: snapshot.meta.durableBase };
+	}
+	if (snapshot.legacySession) throw new Error("Legacy semantic state requires migration before checkpoint publication");
+	if (snapshot.config.enabled) throw new Error("Enabled checkpoint requires a durable runtime revision");
+	return { disabled: true };
+}
+
+/** New wire shapes are strict; predecessor envelopes remain one-way migration input. */
+export function parsePiCheckpoint(value: unknown): PiCheckpoint | Snapshot {
+	if (!isObject(value)) throw new Error("Invalid State Flow checkpoint");
+	if (Object.hasOwn(value, "revision") || Object.hasOwn(value, "disabled")) {
+		if (Object.keys(value).length === 1) {
+			if (isDurableRevision(value.revision)) return { revision: value.revision };
+			if (value.disabled === true) return { disabled: true };
+		}
+		throw new Error("Invalid State Flow checkpoint pointer or disabled marker");
+	}
+	if (!Object.hasOwn(value, "config") && !Object.hasOwn(value, "enabled")) throw new Error("Unrecognized State Flow checkpoint");
+	const config = Object.hasOwn(value, "config") ? value.config : value;
+	if (!isObject(config) || typeof config.enabled !== "boolean") throw new Error("Invalid legacy State Flow configuration");
+	if (Object.hasOwn(value, "meta") && !isObject(value.meta)) throw new Error("Invalid legacy State Flow metadata");
+	const meta = isObject(value.meta) ? value.meta : value;
+	if (Object.hasOwn(meta, "durableBase") && !isDurableRevision(meta.durableBase)) throw new Error("Invalid legacy State Flow revision");
+	return migrateSnapshot(value);
+}
+
+export function migrationFailure(data: JsonObject, error: string): Snapshot {
+	const meta = restoredMeta(data.meta, data);
+	meta.validation = {
+		attempt: 0,
+		error,
+		instruction: "Start a fresh State Flow episode; null is reserved for patch deletion.",
 	};
-	if (isStateDocument(value.state)) {
+	const config = isObject(data.config) ? data.config : data;
+	return envelope(false, meta, restoredTransitionWindow(config.transitionWindow));
+}
+
+function migratedSnapshot(
+	enabled: boolean,
+	meta: SnapshotMeta,
+	transitionWindow: number,
+	state: MaterializedState,
+): Snapshot {
+	return envelope(enabled, meta, transitionWindow, {
+		state: migrateLegacySkillCompilations(state),
+	});
+}
+
+export function migrateSnapshot(value: unknown): Snapshot {
+	if (!isObject(value)) return emptySnapshot();
+	const isEnvelope = Object.hasOwn(value, "config") || Object.hasOwn(value, "meta");
+	const config = isEnvelope && isObject(value.config) ? value.config : value;
+	const meta = restoredMeta(isEnvelope ? value.meta : undefined, value);
+	const enabled = config.enabled === true;
+	const transitionWindow = restoredTransitionWindow(config.transitionWindow);
+	if (isMaterializedState(value.state)) {
+		if (!isJsonValue(value.state)) return migrationFailure(value, "Restored state contains non-JSON data");
+		if (containsNull(value.state)) return migrationFailure(value, "Restored state contains null data");
+		return migratedSnapshot(enabled, meta, transitionWindow, structuredClone(value.state));
+	}
+	if (isLegacyThreePartState(value.state)) {
 		if (!isJsonValue(value.state)) return migrationFailure(value, "Restored state contains non-JSON data");
 		if (containsNull(value.state)) return migrationFailure(value, "Restored state contains null data");
-		return { ...base, state: structuredClone(value.state) };
+		return migratedSnapshot(enabled, meta, transitionWindow, {
+			artifacts: {},
+			...structuredClone(value.state),
+		});
 	}
 	if (isLegacyTwoPartState(value.state)) {
 		if (!isJsonValue(value.state)) return migrationFailure(value, "Restored state contains non-JSON data");
 		if (containsNull(value.state)) return migrationFailure(value, "Restored state contains null data");
-		return {
-			...base,
-			state: {
-				contract: structuredClone(value.state.contract),
-				working: structuredClone(value.state.working),
-				response: "",
-			},
-		};
+		return migratedSnapshot(enabled, meta, transitionWindow, {
+			artifacts: {},
+			contract: structuredClone(value.state.contract),
+			working: structuredClone(value.state.working),
+			response: "",
+		});
 	}
-	if (isObject(value.state)
-		&& (Object.hasOwn(value.state, "response")
-			|| (Object.hasOwn(value.state, "contract") && Object.hasOwn(value.state, "working")))) {
-		return migrationFailure(value, "Restored state has an invalid materialized-state schema");
+	if (Object.hasOwn(value, "state")) {
+		if (isObject(value.state)
+			&& (Object.hasOwn(value.state, "response")
+				|| Object.hasOwn(value.state, "artifacts")
+				|| (Object.hasOwn(value.state, "contract") && Object.hasOwn(value.state, "working")))) {
+			return migrationFailure(value, "Restored state has an invalid materialized-state schema");
+		}
+		if (value.state !== undefined && !isObject(value.state)) {
+			return migrationFailure(value, "Restored state has an invalid materialized-state schema");
+		}
 	}
-	const legacyBasis = isObject(value.stateBasis)
-		? value.stateBasis
-		: isObject(value.state)
-			? value.state
-			: {};
-	const legacyPatch = isObject(value.previousStatePatch) ? value.previousStatePatch : undefined;
-	if (!isJsonValue(legacyBasis) || (legacyPatch !== undefined && !isJsonValue(legacyPatch))) {
-		return migrationFailure(value, "Legacy state contains non-JSON data");
+	if (Object.hasOwn(value, "stateBasis") || Object.hasOwn(value, "previousStatePatch")) {
+		const legacyBasis = isObject(value.stateBasis)
+			? value.stateBasis
+			: isObject(value.state)
+				? value.state
+				: {};
+		const legacyPatch = isObject(value.previousStatePatch) ? value.previousStatePatch : undefined;
+		if (!isJsonValue(legacyBasis) || (legacyPatch !== undefined && !isJsonValue(legacyPatch))) {
+			return migrationFailure(value, "Legacy state contains non-JSON data");
+		}
+		const legacyState = legacyPatch === undefined ? legacyBasis : applyPatch(legacyBasis, legacyPatch);
+		if (containsNull(legacyState)) return migrationFailure(value, "Legacy state contains null data");
+		return migratedSnapshot(enabled, meta, transitionWindow, {
+			artifacts: {}, contract: {}, working: structuredClone(legacyState), response: "",
+		});
 	}
-	const legacyState = legacyPatch === undefined ? legacyBasis : applyPatch(legacyBasis, legacyPatch);
-	if (containsNull(legacyState)) return migrationFailure(value, "Legacy state contains null data");
-	return { ...base, state: { contract: {}, working: structuredClone(legacyState), response: "" } };
+	return envelope(enabled, meta, transitionWindow);
 }

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

@@ -1,20 +1,87 @@
-import { isObject, type JsonObject } from "./json.ts";
+import {
+	isArtifactRegistry,
+	updateArtifactRegistry,
+	type ArtifactCompilationUpdate,
+	type ArtifactRegistry,
+} from "./artifact.ts";
+import { applyPatch, isObject, type JsonObject } from "./json.ts";
 
-/** The only materialized memory shape persisted between State Flow runs. */
-export interface StateDocument extends JsonObject {
+/** The canonical semantic state shape shared by global, CWD, and session scopes. */
+export interface MaterializedState extends JsonObject {
+	artifacts: ArtifactRegistry;
 	contract: JsonObject;
 	working: JsonObject;
 	response: string;
 }
 
-export function emptyState(): StateDocument {
-	return { contract: {}, working: {}, response: "" };
+/** Compatibility name for callers that still treat materialized state as a document. */
+export type StateDocument = MaterializedState;
+
+/** Model patch shape; artifact entries may be compiler outputs before trusted metadata is attached. */
+export interface StatePatch extends JsonObject {
+	artifacts: JsonObject;
+	contract: JsonObject;
+	working: JsonObject;
+	response: string;
+}
+
+export type StateScope = "global" | "cwd" | "session";
+
+/** A model-authored patch for one scope. Response is captured by the runtime in session state. */
+export interface ScopePatch {
+	artifacts?: JsonObject;
+	contract?: JsonObject;
+	working?: JsonObject;
+}
+
+export interface ScopedPatch {
+	scope: StateScope;
+	patch: ScopePatch;
 }
 
-export function isStateDocument(value: unknown): value is StateDocument {
+export interface SemanticTransition {
+	transitions: ScopedPatch[];
+}
+
+export interface TerminalTransition extends SemanticTransition {
+	response: string;
+}
+
+export interface ScopedStates {
+	global: MaterializedState;
+	cwd: MaterializedState;
+	session: MaterializedState;
+}
+
+export function emptyState(): MaterializedState {
+	return { artifacts: {}, contract: {}, working: {}, response: "" };
+}
+
+export function isMaterializedState(value: unknown): value is MaterializedState {
 	return isObject(value)
+		&& isArtifactRegistry(value.artifacts)
 		&& isObject(value.contract)
 		&& isObject(value.working)
 		&& typeof value.response === "string"
-		&& Object.keys(value).every((key) => key === "contract" || key === "working" || key === "response");
+		&& Object.keys(value).every((key) => key === "artifacts" || key === "contract" || key === "working" || key === "response");
+}
+
+export const isStateDocument = isMaterializedState;
+
+/** Atomically replace compiled and removed artifacts inside one materialized scope. */
+export function updateMaterializedArtifacts(
+	state: MaterializedState,
+	updates: readonly ArtifactCompilationUpdate[],
+	removed: readonly string[] = [],
+): MaterializedState {
+	if (!isMaterializedState(state)) throw new Error("Cannot update artifacts in an invalid materialized state");
+	const artifacts = updateArtifactRegistry(state.artifacts, updates, removed);
+	return { ...structuredClone(state), artifacts };
+}
+
+/** Overlay lower-to-higher scopes without mutating any scope document. */
+export function overlayStates(...scopes: readonly MaterializedState[]): MaterializedState {
+	return scopes.reduce<MaterializedState>((effective, scope) => {
+		return applyPatch(effective, scope) as MaterializedState;
+	}, emptyState());
 }

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

@@ -1,16 +1,135 @@
+import type { ArtifactInvalidationReason } from "./artifact.ts";
+import { projectRecentTransitionsWithLimit, type RecentTransitionWindow } from "./history.ts";
+import { inspectMemoryPromotions, retainedMemoryScopes } from "./memory.ts";
+import type { PublicationQueueState } from "./publication.ts";
 import type { Snapshot } from "./snapshot.ts";
+import { overlayStates, type ScopedStates, type StateScope } from "./state.ts";
+import type { TransitionBoundary } from "./temporal.ts";
 
 export const STATUS_KEY = "state-flow";
 
 export type Colorize = (color: "accent" | "dim", text: string) => string;
 
+export type StaleArtifactReason = ArtifactInvalidationReason | "source-removed";
+
+export interface StaleArtifactDiagnostic {
+	scope: StateScope;
+	path: string;
+	reason: StaleArtifactReason;
+}
+
+export interface PendingPublicationDiagnostic {
+	commit: string;
+	error: string;
+}
+
+export interface StatusDiagnostics {
+	repositoryRoot: string;
+	cwdScopeKey: string;
+	sessionScopeKey: string;
+	scopeStates: ScopedStates;
+	recent: RecentTransitionWindow;
+	temporal?: { head: TransitionBoundary; historyDepth: number; tailCounts: Record<StateScope, number> };
+	staleArtifacts: readonly StaleArtifactDiagnostic[];
+	artifactFreshnessError?: string;
+	durableStateError?: string;
+	pendingPublication?: PendingPublicationDiagnostic;
+	retryQueued: boolean;
+	publicationQueue?: PublicationQueueState;
+	publicationQueueError?: string;
+}
+
 export function compactStatus(snapshot: Snapshot, colorize: Colorize): string | undefined {
-	if (!snapshot.enabled) return undefined;
-	return `${colorize("accent", "state-flow")} ${colorize("dim", `#${snapshot.step}`)}`;
+	if (!snapshot.config.enabled) return undefined;
+	return `${colorize("accent", "state-flow")} ${colorize("dim", `#${snapshot.meta.step}`)}`;
+}
+
+function countArtifacts(states: ScopedStates, scope: StateScope): number {
+	return Object.keys(states[scope].artifacts).length;
 }
 
-export function detailedStatus(snapshot: Snapshot): string {
-	const stateJson = JSON.stringify(snapshot.state, null, 2);
-	const stateBytes = Buffer.byteLength(stateJson, "utf8");
-	return `State Flow ${snapshot.enabled ? "enabled" : "disabled"}; iteration #${snapshot.step}; state ${stateBytes} bytes; validation attempts ${snapshot.validation?.attempt ?? 0}.\n\n${stateJson}`;
+function abbreviatedCommit(commit: string): string {
+	return commit.length > 12 ? commit.slice(0, 12) : commit;
+}
+
+export function detailedStatus(snapshot: Snapshot, diagnostics: StatusDiagnostics): string {
+	const projectedRecent = projectRecentTransitionsWithLimit(
+		snapshot.config.transitionWindow,
+		diagnostics.recent,
+	);
+	const available = diagnostics.temporal !== undefined && diagnostics.durableStateError === undefined;
+	const materialized = !available ? undefined : {
+		global: diagnostics.scopeStates.global,
+		cwd: diagnostics.scopeStates.cwd,
+		session: diagnostics.scopeStates.session,
+		effective: overlayStates(
+			diagnostics.scopeStates.global,
+			diagnostics.scopeStates.cwd,
+			diagnostics.scopeStates.session,
+		),
+	};
+	const stateJson = materialized === undefined ? undefined : JSON.stringify(materialized, null, 2);
+	const freshnessError = diagnostics.artifactFreshnessError ?? (available ? undefined : "temporal global artifact registry is unavailable");
+	const stale = freshnessError === undefined
+		? String(diagnostics.staleArtifacts.length)
+		: "unknown";
+	const publication = diagnostics.pendingPublication === undefined
+		? "idle"
+		: `pending ${abbreviatedCommit(diagnostics.pendingPublication.commit)} — ${diagnostics.pendingPublication.error}`;
+	const retry = diagnostics.retryQueued
+		? `queued (attempt ${snapshot.meta.validation?.attempt ?? 0})`
+		: "idle";
+	const staleLines = freshnessError !== undefined
+		? [`Artifact freshness unavailable: ${freshnessError}`]
+		: diagnostics.staleArtifacts.length === 0
+			? ["Stale artifacts: none"]
+			: [
+				"Stale artifacts:",
+				...diagnostics.staleArtifacts.map(({ scope, path, reason }) => `- [${scope}] ${path} — ${reason}`),
+			];
+	const temporal = available ? diagnostics.temporal : undefined;
+	const temporalLines = temporal === undefined
+		? [`Temporal materialization unavailable: ${diagnostics.durableStateError ?? "no selected branch runtime"}`,
+			"Hot history: unavailable; offsets beyond 7 require explicit cold Git inspection",
+			"Retained patch tails: unavailable"]
+		: [`Temporal head: ${JSON.stringify(temporal.head.id)}; branch-local position ${temporal.head.position}`,
+			`Hot history: offsets 0..${temporal.historyDepth}; maximum depth 7`,
+			`Retained patch tails: global ${temporal.tailCounts.global}; CWD ${temporal.tailCounts.cwd}; session ${temporal.tailCounts.session}`];
+	const artifacts = (scope: StateScope) => available ? countArtifacts(diagnostics.scopeStates, scope) : "unknown";
+	const promotions = available ? inspectMemoryPromotions(diagnostics.scopeStates.global) : [];
+	const promotionCounts = Object.fromEntries(["pending", "accepted", "failed", "unknown", "invalid"].map((status) => [status, promotions.filter((entry) => entry.status === status).length]));
+	const memoryScopes = available ? retainedMemoryScopes(diagnostics.scopeStates) : undefined;
+	const oneLine = (value: string) => value.replace(/\s+/g, " ").slice(0, 240);
+	const promotionLines = !available || promotions.length === 0 ? [] : [
+		"Memory promotions:",
+		...promotions.map((entry) => `- ${oneLine(entry.id)} — ${entry.status}; owner ${oneLine(entry.owner ?? "unavailable")}${entry.pointer ? `; pointer ${oneLine(entry.pointer)}` : ""}${entry.revision ? `; revision ${oneLine(entry.revision)}` : ""}${entry.error ? `; error ${oneLine(entry.error)}` : ""}`),
+	];
+
+	return [
+		`State Flow diagnostics — config.enabled=${snapshot.config.enabled}; config.transitionWindow=${snapshot.config.transitionWindow}; branch mode=${snapshot.config.enabled ? "active" : "inactive"}`,
+		`Repository: ${diagnostics.repositoryRoot}`,
+		`Scope keys: CWD ${diagnostics.cwdScopeKey}; session ${diagnostics.sessionScopeKey}`,
+		"Session files: config.json owns behavior; meta.json owns lineage and provenance",
+		`Runtime metadata: step #${snapshot.meta.step}; active revision ${snapshot.meta.durableBase ?? "none"}; bootstrap ${snapshot.meta.bootstrap === true}; validation attempts ${snapshot.meta.validation?.attempt ?? 0}`,
+		`Remote publication policy: ${snapshot.meta.remotePublication?.mode ?? "legacy-transition"}`,
+		diagnostics.publicationQueueError !== undefined
+			? `Remote queue: unavailable; error ${diagnostics.publicationQueueError}`
+			: diagnostics.publicationQueue === undefined
+			? "Remote queue: idle"
+			: `Remote queue: ${diagnostics.publicationQueue.status}; target ${abbreviatedCommit(diagnostics.publicationQueue.target)}; confirmed ${diagnostics.publicationQueue.confirmed ? abbreviatedCommit(diagnostics.publicationQueue.confirmed) : "none"}; attempt ${diagnostics.publicationQueue.attempt}${diagnostics.publicationQueue.error ? `; error ${diagnostics.publicationQueue.error}` : ""}`,
+		"Memory: owner state-flow; global retention enabled; global fallback active",
+		`Memory-bearing scopes: global ${memoryScopes?.global ?? "unknown"}; CWD ${memoryScopes?.cwd ?? "unknown"}; session ${memoryScopes?.session ?? "unknown"}`,
+		`Promotion status: pending ${promotionCounts.pending}; accepted ${promotionCounts.accepted}; failed ${promotionCounts.failed}; unknown ${promotionCounts.unknown}; invalid ${promotionCounts.invalid}`,
+		...promotionLines,
+		...temporalLines,
+		`Artifacts: global ${artifacts("global")}; CWD ${artifacts("cwd")}; session ${artifacts("session")}; stale ${stale}`,
+		available ? `Recent transitions: global ${diagnostics.recent.filter(({ transitions }) => transitions.some(({ scope }) => scope === "global")).length}; CWD ${diagnostics.recent.filter(({ transitions }) => transitions.some(({ scope }) => scope === "cwd")).length}; session ${diagnostics.recent.filter(({ transitions }) => transitions.some(({ scope }) => scope === "session")).length}; active ${projectedRecent.length}` : "Recent transitions: unavailable",
+		`Publication policy: ${snapshot.meta.remotePublication?.mode ?? "legacy-unresolved"}`,
+		`Publication: ${publication}`,
+		`Terminal retry: ${retry}`,
+		...staleLines,
+		...(stateJson === undefined
+			? ["Materialized states: unavailable (global/CWD/session/effective)"]
+			: [`Materialized states (${Buffer.byteLength(stateJson, "utf8")} bytes; global/CWD/session Git-backed, effective overlay):`, "", stateJson]),
+	].join("\n");
 }