@llblab/pi-kit 0.11.0 → 0.11.1

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.11.1 - 2026-09-13
+
+- `State Flow Filesystem Recovery`: Advances the exact State Flow pin to `0.10.1`, adding transactional self-healing when a complete live global or CWD checkpoint pair disappears, exact private-session reconstruction from retained Git evidence, and precise fail-closed handling for partial or unsafe storage loss. The package set, resource inventory, and explicit load order remain unchanged.
+
 ## 0.11.0 - 2026-09-13
 
 - `State Flow Maturation`: Advances the exact State Flow pin to `0.10.0`, adding safe native compaction of sufficiently large completed histories, effective-memory-only status JSON, stronger fork/recovery and concurrent publication guarantees, and lower repeated Git/session restoration work while preserving full Pi session traces and exact state lineage. The package set, resource inventory, and explicit load order remain unchanged.

package/README.md

@@ -14,7 +14,7 @@ Package links lead to the owning repositories for usage, documentation, issues,
 | [`@llblab/pi-clean-room`](https://github.com/llblab/pi-clean-room) | `0.1.1` | Isolated nested Pi TUI with explicitly selected extensions |
 | [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.9.4` | Compact Codex/Spark subscription-limit status |
 | [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.8.1` | Visible continuation scheduling and bounded worker Skills |
-| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.10.0` | Durable scoped state with native session compaction and exact publication |
+| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.10.1` | Durable scoped state with native session compaction and exact publication |
 | [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.45.8` | Telegram companion, queues, files, voice, controls, and Generative Apps guidance |
 | [`@llblab/skills`](https://github.com/llblab/skills) | `1.15.0` | Portable workflows for engineering, review, design, context maintenance, and other focused tasks |
 

package/node_modules/@llblab/pi-state-flow/AGENTS.md

@@ -18,6 +18,7 @@
 - Define `state[n]` and `state.global[n]`, `state.cwd[n]`, `state.session[n]` at the same nth previous accepted transition boundary in the active lineage, never the nth local patch of each scope. Guarantee offsets zero through seven once the lineage has seven proven transitions; report earlier-than-origin history as unavailable for new/migrated lineages and reject offsets beyond seven on the hot interface. Reconstruct scopes at one target before overlaying them.
 - Keep historical reads lazy through the smallest runtime/model read interface. Normal inference gets only current effective state and useful bounded compact transition context, never eight full snapshots. `patch_state` is the sole semantic mutation tool. `read_state` exposes one cached effective/global/CWD/session projection at offset 0–7, defaulting to effective/0; it returns the exact boundary with semantic state and never publishes, appends a checkpoint, or advances history. Both tools follow branch enablement and host tool restrictions; the patch barrier blocks reader siblings too. Live/cached checkpoint plus tails own the hot path; use Git for branch restoration and explicit cold inspection, not to rebuild current state on every inference.
 - Store runtime state in its own directory with optional Git durability, defaulting to `state-flow/` beneath Pi's configured agent directory (`~/.pi/agent/state-flow/` normally), independently from the Knowledge Markdown source root. Use exactly these owned paths: `checkpoint.json`, `patches.jsonl`, and `meta.json` for global; `<cwd-key>/checkpoint.json`, `<cwd-key>/patches.jsonl`, and `<cwd-key>/meta.json` for CWD; `<cwd-key>/<session-key>/checkpoint.json`, `patches.jsonl`, `config.json`, and `meta.json` for session. Do not create `.state-flow`, `scopes`, or another storage/history namespace. Mirror Pi's native CWD session-directory encoding and JSONL-basename session key (deriving `<header timestamp>_<UUID>` for in-memory sessions), while retaining separately verifiable canonical identity provenance in owned state. Keep the UUID authoritative, reject unsafe segments and mismatches rather than selecting another scope, and use CWD checkpoint ownership to fail closed on Pi-name collisions.
+- Classify every filesystem cohort before recovery: complete valid evidence is usable; total absence is recoverable only from an explicit semantic default or exact surviving authority; partial, malformed, contradictory, or authority-losing evidence fails closed at the smallest dependent capability. A wholly absent untouched global/CWD checkpoint-tail pair is current empty shared reality and must not resurrect selected cold values; a patch targeting that disappeared scope is stale and must fail for reinference. Missing provenance means unavailable freshness, not semantic corruption. Perform every repair through normal locked/CAS publication, never ad-hoc writes.
 - Migrate legacy current `state.json` losslessly into an initial anchored checkpoint with an empty tail; current snapshots are the sole semantic recovery basis, independent of the presence or validity of explanatory journals, including historical revision reads. Preserve only proven history, remove obsolete files within the successful scoped migration, and never retain two authoritative formats. Exercise migrations in temporary repositories rather than modifying the user's active Knowledge data during development.
 - Read and write only regular non-symlink State Flow-owned files at those exact paths, publish each file by same-directory atomic rename, preserve arbitrary repository contents, and classify ownership exactly. Git acceptance follows the complete-delta isolated-index contract below. Retain opaque source bytes for file identity and rollback, not decoded-text reconstructions. Use validated structural JSON equality for in-process semantic comparisons; reserve cryptographic hashes for compact identities that cross inference, persistence, process, or source-freshness boundaries. Serialize cooperating Git publications through a common-Git-directory publication lock; low-level file helpers require caller exclusion. Recheck prepared bases before each replacement/deletion and restore only bytes still matching the publisher's own output. Preserve detected concurrent changes and report unresolved rollback conflicts; do not claim kernel-atomic multi-file CAS against nonparticipating writers. Markdown discovery uses its independently configured source root, defaulting to `knowledge/` beneath Pi's agent directory; a storage-root override must not redirect source discovery.
 - At instance initialization resolve the repository, CWD key, and session key; load each scope's anchored checkpoint and tail, materialize at the selected temporal boundary, then overlay `global → cwd → session`. Install cached view and publication basis atomically only after successful restoration/initialization; unavailable publication is an error, not a semantic no-op. Branch recovery may reuse one owner-bound, single-use inspection of the exact selected immutable Git revision, with a detached inspection snapshot and a freshly acquired live publication basis at installation. Revalidate mutable file cohorts, legacy snapshot fallbacks, and redirected runtime owners; never turn inspection into a long-lived revision or publication-basis cache. Preserve the selected revision across transient restore failure so an explicit start can retry it. A genuinely new session gets an empty session layer and inherits only global/CWD values; it must never reuse another same-CWD session layer. Explicit native fork adoption instead follows the [session-copy contract](docs/fork-contract.md): copy the proven source session checkpoint/tail and provenance into a distinct owner over current shared streams, without pruning shared provenance or modifying the parent. Use a fresh origin, preserve copied replay records, reject occupied live/HEAD targets, and publish/checkpoint the child only after CAS acceptance. Inherited parent pointers never authorize an empty reset; fence parent passive Stop projection across child reload.

package/node_modules/@llblab/pi-state-flow/BACKLOG.md

@@ -2,19 +2,12 @@
 
 Completed release work belongs in [CHANGELOG.md](CHANGELOG.md).
 
-## 0.10.0: Session performance and reliability
+## 0.10.1: Filesystem self-healing and graceful degradation
 
-- **Outcome:** Make State Flow complement Pi's native session lifecycle reliably and efficiently after long histories and while independent instances publish to the same store. The operator reports slowdown after resuming a large session with roughly 200 patches; concurrency is a hypothesis, not an established cause.
-- **Evolution:** Treat 0.10.0 as a maturation milestone: deepen reliability, usability, performance, consistency, and explanation of the existing concept. Admit adjacent maintenance only from concrete evidence; do not add features or change the product's core model.
-- **Execution:** Prefer inline implementation and review. If subagent delegation becomes necessary, use only the operator-requested "GPT-5.6 Luna" after verifying its exact available identity; no silent substitution. The coordinator owns review and integration. Existing deterministic benchmark processes may finish without launching more model actors.
-- **Convergence:** Reproduce and measure first, implement only evidenced corrections, validate each owned slice, then separately review the integrated candidate. Stop when the regressions below pass, before/after workload evidence explains the performance changes, and remaining host or environment limits are explicit. Preserve semantic history, source/runtime ownership, native trace, branch selection, and exact publication/CAS guarantees.
-- **Non-goals:** No new semantic mode, state-size cap, database, hidden session replacement, bulk migration, production-store repair, read-only global bootstrap, or Telegram analyzer. Preserve ordinary abort: accepted patches remain available for same-session continuation, with no new immediate remote-enqueue requirement. Test on synthetic sessions and temporary stores; do not inspect or mutate production conversation bodies or state repositories for this work. Publication remains outside preparation scope.
-
-### Release gate
-
-The [nine-invocation measurement series and interpretation](docs/performance.md#measurement-closure) are complete; no measurement is active. `/tmp/state-flow-final-controls-CzaHqM/final-series-receipts.json` binds the actual exits and complete captures. Preserve this evidence and refresh only claims invalidated by an admitted correction; source/workload changes must not silently inherit old timings. Original production slowdown attribution remains unproven, and production-store inspection is not authorized.
-
-The 0.10.0 candidate now includes native completed-history compaction and effective-only status JSON. Full 0.84.4 validation passes 426/426; affected policy/status/native lifecycle tests and typecheck pass on 0.85.1. The operator intentionally aligned package/lock versions to 0.10.0 and explicitly authorized commit, push and release. Release automation/remote CI and published artifacts remain the external acceptance gates.
+- **Outcome:** Treat safely interpretable absence as recoverable or optional while keeping partial, malformed, contradictory, and authority-losing evidence fail-closed at the smallest affected capability. [`docs/filesystem-recovery.md`](docs/filesystem-recovery.md) owns the durable cohort classification.
+- **Accepted candidate:** Shared Git/file repair, exact session authority, provenance/external degradation, operational persistence, concurrent CAS and native Pi response/reload/resume witnesses are complete. A focused release review found and corrected repeated stale-target refusal; the runtime now refreshes the empty basis after one conflict and accepts a later patch through ordinary publication.
+- **Validation:** The complete 0.84.4 repository profile passes 442/442 with typecheck/import-check. On the supported 0.85.1 stack, all 16 affected codec/runtime witnesses, the real Pi lifecycle witness and typecheck pass. Package 0.10.1 contains 46 files including the recovery guide and excludes tests/benchmarks; context/DAG validation report zero errors.
+- [ ] **Release gate:** Commit, push, tag, npm/GitHub publication, and any Pi Kit pin update require separate explicit release authorization.
 
 ## Candidate evolution
 
@@ -22,7 +15,7 @@ The 0.10.0 candidate now includes native completed-history compaction and effect
   - Boundary: project the existing durable global materialization only. No writes, transitions, patches, barriers, session/CWD initialization, or temporal-history changes. Model tools and the full protocol remain opt-in behind explicit start, and the bootstrap adds no second semantic mode.
   - Open questions: whether deferred Markdown freshness discovery must run ahead of the first inference, token cost of a stable global prefix, behavior under untrusted project contexts, and naming distinct from the existing bootstrap-run concept.
   - Status: candidate, not scheduled. Do not start without a dedicated release contract.
-- [ ] **Telegram submenu state analyzer:** Extend the State Flow Telegram section with a read-only analyzer view over the same diagnostics `/state-flow-status` already reports (branch mode, temporal head and hot depth, scope keys, retained tails, artifact freshness, publication). The operator deliberately deferred this beyond the 0.9.0 control surface.
+- [ ] **Pi Telegram submenu state analyzer:** Extend the State Flow Telegram section with a read-only analyzer view over the same diagnostics `/state-flow-status` already reports (branch mode, temporal head and hot depth, scope keys, retained tails, artifact freshness, publication). The operator deliberately deferred this beyond the 0.9.0 control surface.
   - Boundary: presentation only. Reuse existing status diagnostics; no new semantic mode, and never mutate state from the analyzer view.
   - Status: candidate, not scheduled. Do not start without a dedicated release contract.
 

package/node_modules/@llblab/pi-state-flow/CHANGELOG.md

@@ -4,6 +4,12 @@
 
 ## Unreleased
 
+## 0.10.1: Filesystem self-healing and graceful degradation
+
+- `Shared scopes`: A wholly absent live global/CWD checkpoint-tail pair is now distinct from partial storage. Untouched publication adopts empty current reality at a fresh origin and transactionally materializes the canonical pair without resurrecting selected values; a patch targeting the disappeared scope fails precisely for reinference. Git/file backends retain publication locks, CAS, full cold history and concurrent-writer exclusion.
+- `Authority and locality`: Exact selected Git revisions can reconstruct missing private session files, while file-only loss without a retained cohort and partial session semantic/runtime pairs remain fail-closed. Missing provenance degrades freshness without invalidating semantic artifacts; malformed provenance bytes remain untouched. Existing optional config, Knowledge discovery, queue, lease, lock and external-source absence keeps its local graceful behavior.
+- `Recovery evidence`: Native Pi now reconciles an ordinary answer after complete live CWD-pair deletion, then accepts another session patch and reloads/resumes the repaired state. Regression coverage also proves no shared-value resurrection, stale-target refusal, partial-pair preservation, one-owner concurrent repair, stale-capture CAS loss, exact session reconstruction, and absent/malformed operational or external-resource behavior.
+
 ## 0.10.0: Native session memory and reliability
 
 - `Git work`: Single-use restoration, exact-path tree reads and NUL-safe index batching cut steady Git calls 120→87 and resume 63→21 without caching live bases or weakening exact-byte/CAS guards. Selected state/runtime blobs now bypass Node's implicit 1 MiB output limit, preserving large-state answers and cold restoration. Legacy/file-cohort, mode/owner and rollback checks remain. Call savings do not establish universal latency gains.

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

@@ -2,6 +2,7 @@
 
 - [Usage and recovery](usage.md): Configuration, new/resumed sessions, Start/Stop, diagnostics, privacy, and storage recovery.
 - [Architecture](architecture.md): Semantic state, temporal algebra, Pi lifecycle, storage, publication, artifacts, and embedding contracts.
+- [Filesystem recovery](filesystem-recovery.md): Cohort-wide absence, partial-presence, malformed-evidence, repair-authority, and transaction rules.
 - [Temporal acceptance](temporal-acceptance.md): The twenty required temporal properties and their executable witnesses.
 - [SDK compatibility](compatibility.md): Tested dependency stacks, public lifecycle seams, isolated validation, and host limits.
 - [Physical fork contract](fork-contract.md): Session-stream copying, unchanged shared memory, child ownership/origin, and tested support boundaries.

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

@@ -0,0 +1,35 @@
+# Filesystem recovery contract
+
+State Flow classifies absence separately from partial or malformed evidence. Recovery may derive bytes only from an authoritative surviving cohort or from a semantic default that the owner explicitly permits. It never invents history, ownership, provenance, or external success.
+
+| Resource or cohort | Owner / authority | Total absence | Partial or malformed presence | Allowed repair and writes |
+| --- | --- | --- | --- | --- |
+| Global `checkpoint.json` + `patches.jsonl` | State Flow; authoritative shared semantics | Untouched publication adopts a fresh empty scope; a targeted patch conflicts | Either half missing, malformed replay, or invalid envelope fails closed | Normal CAS publication may materialize the complete empty pair |
+| CWD `checkpoint.json` + `patches.jsonl` | State Flow; authoritative shared semantics with CWD identity | Same as global; selected values are not resurrected | Same as global; owner mismatch also fails closed | Normal CAS publication may materialize the complete empty pair |
+| Session `checkpoint.json` + `patches.jsonl` | State Flow; authoritative private semantics | Fresh lifecycle origin may initialize; an existing selected session requires exact retained authority | Partial or malformed pair fails closed | Fresh initialization or exact selected-revision recovery only |
+| Global/CWD `meta.json` | State Flow; derived artifact provenance | Provenance unavailable (`{}`); semantics remain usable | Malformed present evidence disables the dependent provenance operation | Rebuild only from fresh trusted acquisition evidence through publication |
+| Session `config.json` + `meta.json` | State Flow; authoritative runtime identity, lineage and session provenance | Fresh origin may initialize; selected sessions recover only from exact authority | Partial, malformed, contradictory identity, lineage, or revision fails closed | Canonical runtime publication from proven lifecycle/selected state |
+| Legacy `state.json` and legacy tails | State Flow migration input; authoritative only after codec validation | No migration input | Mixed legacy/canonical, orphan tail, malformed bytes, or identity ambiguity fails closed | Existing one-way migration machinery only |
+| Selected Git revision blobs/modes | Git object database; immutable cold authority | A required blob/revision is unavailable | Mode, owner, hash, or cohort contradiction fails closed | Read-only reconstruction; never checkout/reset the live worktree |
+| File-only revision pointer/cohort | State Flow/Pi entry; current exact authority only | No cold history can be invented | Any identity mismatch or incomplete retained cohort fails closed | Exact current cohort only; normal locked publication writes repairs |
+| Publication queue | State Flow; operational effect intent | Empty queue / no pending publication | Malformed or contradictory bytes are preserved and publication fails locally | CAS save/remove and atomic temporary rename only |
+| Worker lease | State Flow; operational ownership | Unclaimed | Malformed/foreign live evidence is preserved; live owner excludes peers | Existing dead-process reclamation protocol only |
+| Publication locks | State Flow; mutual exclusion | Unlocked | Present lock excludes publishers, including interrupted owners | Current owner releases; no opportunistic deletion |
+| Temporary queue files / isolated Git index | Creating State Flow operation; transient | No pending preparation | Unknown surviving files grant no authority | Creating operation cleans its own temporary path; fatal residue is not adopted |
+| Extension `state-flow.json` | Operator; optional external configuration | Built-in defaults | Present unreadable/malformed/unknown settings fail extension configuration | State Flow never creates or rewrites it |
+| Knowledge root and Markdown | External Knowledge owner | Freshness unavailable; durable semantic state remains | Unsafe paths or malformed/unreadable sources disable acquisition locally | Never create; semantic removal only under existing confirmed ownership rules |
+| Skill and external artifact sources | External package/user owner | Freshness unavailable unless ownership proves removal semantics | Unsafe/non-regular/unreadable sources disable acquisition locally | Never create or fabricate source/provenance |
+| Pi State Flow entries and diagnostics | Pi session log / State Flow entry owner | Missing optional diagnostics provide no evidence; missing required selected pointer blocks that restore | Malformed or contradictory owner/version/pointer fails the dependent restore | Append through Pi entry APIs only; no standalone diagnostics file exists |
+
+## Transaction rule
+
+Every semantic repair follows the ordinary transaction path:
+
+1. Capture the live Git or file basis under the existing publication lock.
+2. Classify each cohort as present, absent, partial, or malformed.
+3. Derive only an authorized replacement.
+4. Stage the complete canonical cohort.
+5. Recheck CAS and ownership.
+6. Atomically publish and install the resulting runtime state.
+
+A current wholly absent shared scope is newer live reality for an untouched transition dependency. Its replacement begins empty at a fresh reconciliation origin. If the accepted transition targets that missing scope, publication refuses the stale target and requires a later inference against the refreshed basis. Cold Git history remains inspectable but is never silently promoted back into current shared memory.

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

@@ -79,6 +79,14 @@ Use a dedicated directory. State storage and Knowledge Markdown have separate re
 
 Each scope materializes an anchored `checkpoint.json` plus `patches.jsonl`. Scope `meta.json` holds runtime-owned artifact evidence; the session also has `config.json` and temporal/runtime metadata. CWD/session directories mirror Pi's native naming while validating canonical identities separately. See the [storage contract](architecture.md#storage-and-identity) for the exact layout.
 
+### Missing, partial, and malformed storage
+
+A checkpoint and tail are one semantic pair. If both live files for an untouched global or CWD scope disappear, State Flow treats that complete absence as current empty shared reality during the next accepted publication. It creates a fresh canonical pair through the normal publication lock and CAS path; selected values remain only in cold Git history and are not silently resurrected. A patch targeting the disappeared scope is rejected once as stale so a later inference can work from the actual empty basis.
+
+Exactly one surviving pair member is corruption and fails closed. Present malformed JSON, invalid envelopes, identity contradictions, and partial session `config.json`/`meta.json` also remain fail-closed and are not replaced. A selected Git revision may reconstruct a missing private session cohort exactly; file-only mode refuses when its exact current cohort is gone because it has no cold history to invent.
+
+Missing shared provenance means freshness evidence is unavailable while semantic state remains usable. A missing whole Knowledge root does not prove that durable artifact routing was deleted, and external files are never created. Queue, worker lease, and lock absence keep their existing meanings—empty, unclaimed, and unlocked—while malformed or foreign present evidence is preserved. See the complete [filesystem recovery contract](filesystem-recovery.md).
+
 ### With Git
 
 Start initializes an exact-root repository when needed, preserving existing contents. Git must have a configured commit identity. A containing ancestor repository is not a substitute. Manual-mode startup/status/restore do not initialize Git; explicit Start and automatic activation of genuinely new sessions may do so.

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

@@ -55,14 +55,18 @@ export function serializeScopeStream(stream: ScopeStream, scope: StateScope, cwd
 	};
 }
 
-/** Decode the entire bounded replay input before accepting any materialized state. */
-export function parseScopeStream(
+export type ScopeStreamPresence =
+	| { kind: "absent" }
+	| { kind: "present"; stream: ScopeStream };
+
+/** Distinguish a wholly absent semantic cohort from partial or malformed surviving authority. */
+export function classifyScopeStream(
 	checkpointSource: string | undefined,
 	patchesSource: string | undefined,
 	scope: StateScope,
 	expectedCwd?: string,
-): ScopeStream | undefined {
-	if (checkpointSource === undefined && patchesSource === undefined) return undefined;
+): ScopeStreamPresence {
+	if (checkpointSource === undefined && patchesSource === undefined) return { kind: "absent" };
 	if (checkpointSource === undefined || patchesSource === undefined) {
 		throw new Error(`State Flow ${scope} scope has an incomplete checkpoint/tail pair`);
 	}
@@ -94,7 +98,18 @@ export function parseScopeStream(
 	}
 	const stream = { checkpoint, patches };
 	validateScopeStream(stream, scope);
-	return stream;
+	return { kind: "present", stream };
+}
+
+/** Decode the entire bounded replay input before accepting any materialized state. */
+export function parseScopeStream(
+	checkpointSource: string | undefined,
+	patchesSource: string | undefined,
+	scope: StateScope,
+	expectedCwd?: string,
+): ScopeStream | undefined {
+	const presence = classifyScopeStream(checkpointSource, patchesSource, scope, expectedCwd);
+	return presence.kind === "present" ? presence.stream : undefined;
 }
 
 export interface TemporalScopePaths {

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

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { lstatSync } from "node:fs";
 import { join } from "node:path";
-import { parseScopeProvenance, parseScopeStream, sessionRuntimePaths, temporalScopePaths, type SessionAddress } from "./durable.ts";
+import { classifyScopeStream, 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, type TemporalFileBase } from "./storage.ts";
@@ -39,6 +39,19 @@ function targetScopeConflict(scopes: readonly StateScope[]): Error {
 	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.`);
 }
 
+/** Disappearance invalidates a selected write target even though untouched scopes can adopt empty reality. */
+function removedTargetScopeConflict(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]} scope was removed 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 ")} scopes were removed after this transition's selected basis. Refresh or reconcile the target scopes before retrying.`);
+}
+
+function freshEmptyScopeStream(scope: StateScope, origin: string): ScopeStream {
+	return createTemporalState({ global: emptyState(), cwd: emptyState(), session: emptyState() }, origin).scopes[scope];
+}
+
 export class MissingSessionRuntimeError extends Error {
 	constructor() { super("Linked State Flow revision has no session runtime"); }
 }
@@ -81,6 +94,8 @@ export class TemporalRuntime {
 	private savedRuntime: string | undefined;
 	private backend: "git" | "files" | undefined;
 	private provenanceByScope: Record<StateScope, ArtifactProvenanceRegistry> = emptyProvenance();
+	/** Shared scopes whose wholly absent live basis was accepted after one stale-target refusal. */
+	private readonly absentSharedScopes = new Set<StateScope>();
 	readonly cwd: string;
 	private readonly session: SessionAddress;
 	readonly root: string;
@@ -119,6 +134,7 @@ export class TemporalRuntime {
 		this.backend = "git";
 		this.semanticRevision = result.revision;
 		this.savedRuntime = savedRuntime;
+		this.absentSharedScopes.clear();
 		return result;
 	}
 
@@ -216,6 +232,7 @@ export class TemporalRuntime {
 			this.provenanceByScope = structuredClone(inspected.file.provenance);
 			this.semanticRevision = revision;
 			this.savedRuntime = savedRuntime;
+			this.absentSharedScopes.clear();
 			return inspected.snapshot;
 		}
 		if (!inspected.temporal) {
@@ -269,6 +286,7 @@ export class TemporalRuntime {
 		this.provenanceByScope = structuredClone(loaded.provenance);
 		this.semanticRevision = semanticRevision;
 		this.savedRuntime = savedRuntime;
+		this.absentSharedScopes.clear();
 		return resolved.snapshot;
 	}
 
@@ -347,6 +365,7 @@ export class TemporalRuntime {
 		this.provenanceByScope = structuredClone(candidate.provenanceByScope);
 		this.semanticRevision = candidate.semanticRevision;
 		this.savedRuntime = candidate.savedRuntime;
+		this.absentSharedScopes.clear();
 		return publication;
 	}
 
@@ -397,10 +416,23 @@ export class TemporalRuntime {
 		const provenance = structuredClone(this.provenanceByScope);
 		const adopted = new Map<StateScope, ScopeStream>();
 		const targets: StateScope[] = [];
+		const removedTargets: StateScope[] = [];
+		const absentScopes: StateScope[] = [];
+		const head = "head" in captured ? captured.head : undefined;
+		const reconciliation = `${head ?? "files"}:reconcile:${randomUUID()}`;
 		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 presence = classifyScopeStream(liveFiles.get(paths.checkpoint)?.content, liveFiles.get(paths.patches)?.content, scope, scope === "cwd" ? this.cwd : undefined);
+			if (presence.kind === "absent") {
+				absentScopes.push(scope);
+				provenance[scope] = {};
+				if (changedScopes.has(scope) && !this.absentSharedScopes.has(scope)) removedTargets.push(scope);
+				if (!this.absentSharedScopes.has(scope)) {
+					adopted.set(scope, freshEmptyScopeStream(scope, `${reconciliation}:${scope}:absent`));
+				}
+				continue;
+			}
+			const stream = presence.stream;
 			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]);
@@ -412,19 +444,20 @@ export class TemporalRuntime {
 			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 = {
+		const reconciledView = () => adopted.size === 0 ? this.view! : adoptTemporalStreams({
 			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,
-		};
+		}, reconciliation);
+		if (removedTargets.length > 0) {
+			this.view = reconciledView();
+			this.base = captured;
+			this.provenanceByScope = provenance;
+			for (const scope of absentScopes) this.absentSharedScopes.add(scope);
+			throw removedTargetScopeConflict(removedTargets);
+		}
+		if (targets.length > 0) throw targetScopeConflict(targets);
+		return { view: reconciledView(), base: captured, provenance };
 	}
 
 	publish(
@@ -474,6 +507,7 @@ export class TemporalRuntime {
 			this.provenanceByScope = nextProvenance;
 			this.savedRuntime = fingerprint;
 			this.semanticRevision = result.revision;
+			if (semantic) this.absentSharedScopes.clear();
 			return { base: result.base, revision: result.revision };
 		}
 		if (!scopedWrite) {
@@ -497,6 +531,7 @@ export class TemporalRuntime {
 		this.provenanceByScope = nextProvenance;
 		this.savedRuntime = fingerprint;
 		if (scopedWrite && result.commit) this.semanticRevision = result.commit;
+		if (semantic) this.absentSharedScopes.clear();
 		return result;
 	}
 }

package/node_modules/@llblab/pi-state-flow/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-state-flow",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "private": false,
   "description": "Incremental scoped state/context compiler for Pi, inspired by SKILL.state",
   "keywords": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -44,7 +44,7 @@
     "@llblab/pi-clean-room": "0.1.1",
     "@llblab/pi-codex-usage": "0.9.4",
     "@llblab/pi-grow-loop": "0.8.1",
-    "@llblab/pi-state-flow": "0.10.0",
+    "@llblab/pi-state-flow": "0.10.1",
     "@llblab/pi-telegram": "0.45.8",
     "@llblab/skills": "1.15.0"
   },