@llblab/pi-kit 0.22.1 → 0.23.0

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

@@ -1,7 +1,9 @@
 # Backlog
 
-No open implementation tasks.
+No open implementation items for the 0.19.0 release scope.
 
-Completed outcomes are recorded in [CHANGELOG.md](CHANGELOG.md). Maintained contracts and acceptance evidence belong to [docs](docs/README.md).
+Release publication is owned by the version-tag workflow in `.github/workflows/release.yml`; a tag alone is not completion. Verify successful automation, the matching published GitHub Release and npm package before reporting the release complete.
 
-Live-host, provider and platform verification limits are documented in [SDK compatibility](docs/compatibility.md). Production-store conversion and installed-host activation remain separate operator decisions; see [usage and recovery](docs/usage.md).
+Completed outcomes are recorded in [CHANGELOG.md](CHANGELOG.md). Maintained contracts and acceptance evidence belong to [docs](docs/README.md), including the accepted [persistence limitation](docs/filesystem-recovery.md#power-loss-durability) and [library API compatibility](docs/compatibility.md#state-flow-library-api-compatibility).
+
+Live-host, provider and platform verification limits remain documented in [SDK compatibility](docs/compatibility.md). Production-store conversion and installed-host activation remain separate operator decisions; see [usage and recovery](docs/usage.md).

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

@@ -2,6 +2,17 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.19.0: Awaited Memory and Lossless Mode Changes
+
+- `Lossless context toggles`: Stop retains uncompiled conversation through Start/Stop, reload and restart without resurrecting compiled history. Interrupted runs keep their native anchor or conservatively retain available context. Uncheckpointed requests and interrupted boundary continuations survive idle Stop/reload even without a specification; successful bootstrap releases the extra context. Completed idle Stop stays bounded.
+- `Awaited activation and restoration`: Startup/tree/fork/auto-start and fenced reload await owned selection. Start activates current same-session memory without claiming expired history. Restoration, auto-start initialization and fork copying survive Stop and cancelled Start waiters; their acceptance applies passive policy and permits configured passive patching. Selection/shutdown still revoke stale work. Acceptance installs memory; late failures never roll it back. Active Start is inert.
+- `Awaited fail-operational Stop`: Local policy and passive context switch before cancelable publication waiting. Runtime-only acceptance preserves semantic/provenance files; repeats share the wait. Selection/shutdown/successful Start cancel obsolete work. Failed writes retain cached memory/context and a native fence until accepted Start. Telegram acknowledges early, drops stale results and keeps legacy ports. Forks inherit policy, not fences; fenced reload stays read-only.
+- `Compact protocol and diagnostics`: Deduplicates injected plane, scope, response, stewardship and provenance rules without changing tools or memory semantics. Short errors retain operation, scope/path suffix and cause across tools, lifecycle, status and Telegram. Nested/aggregate causes survive transport; operand-first elision preserves Unicode and apostrophes. Opt-in logs retain full targets/input; failed Start emits one notice and tool headings keep a blank line.
+- `Awaited memory transactions`: Patches preserve independent shared fields and acceptance order; repeats add no revisions. Setup/cards/evidence accept together under cancelable exclusion/CAS. Preparation/maintenance accept at native `context` or abort inference; runtime-only writes preserve history/provenance. Restore/fork await exact private authority over live shared streams; duplicate/competing Skill writes preserve ownership. Rejected drafts never install; private/selection fences remain.
+- `Awaited response acceptance`: Final answers wait cancelably for current shared memory and publish response plus completed-run lifecycle together. Failed publication installs no draft or shared adoption. Native Abort, Stop, selection/run changes, shutdown and superseding answers withdraw obsolete waits without erasing newer work or write fences. Independent-process Pi tests prove waits beyond two seconds, private isolation, next-provider visibility and retained unfinished runs on cancellation.
+- `Awaited inspection`: Telegram and continuation readers await coherent cohorts without publication or private substitution. Telegram pairs state/revisions, revokes stale receipts and keeps legacy ports; callbacks acknowledge early and escape late errors. Library inspection APIs now return Promises: callers must await results. Six legacy runtime adapters remain. Read-only current-memory recovery preserves private authority without enabling writes. Missing/invalid evidence never initializes memory.
+- `Awaited backup capture`: Backup and canonical mutexes wait cancelably, capture one cohort and preserve replacement owners. Git runs outside canonical exclusion; branch/head drift is rechecked. Settlement awaits completion and shutdown cancels pending reads. Pi 0.87 lacks a settlement Abort signal, so contended backup explicitly defers instead of waiting uninterruptibly. Accepted memory/Stop fences survive; native and independent-writer tests cover ownership, cancellation and coherent commits.
+
 ## 0.18.1: Backup Reliability
 
 - `Push lifecycle`: Bounds backup replication to one in-flight push per repository, skips overlap until a later accepted turn, and awaits process closure at session shutdown under the existing push timeout. Suppresses failure reporting after shutdown starts; test fixtures settle pushes before cleanup. Canonical acceptance stays independent of Git replication.

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

@@ -52,11 +52,19 @@ Enable active State Flow on the current branch:
 
 Starting in an existing conversation retains its context for one complete bootstrap run so the agent can compile what matters.
 
-- `/state-flow-start`: Enable active state updates and memory-based context projection.
+- `/state-flow-start`: Enable the active, state-driven iteration workflow and memory-based context projection; passive mode can already save explicit patches.
 - `/state-flow-status`: Inspect effective state, retained history and known recovery issues without scanning sources or changing state.
-- `/state-flow-stop`: End active episode semantics without deleting memory; an interrupted run retains its frozen handoff and available trajectory.
+- `/state-flow-stop`: End active episode semantics without deleting memory, even when canonical persistence fails. Interrupted work and uncompiled conversation remain available across toggles and reload; a failed write stays fenced until explicit Start safely reactivates current memory.
 
-Active mode is **opt-in**. Passive memory projection and the memory tools are enabled by default: existing state can be read or explicitly patched without an active episode or State Flow compaction. Every materially changed owner advances its independent scope revision even in passive mode, without displaying an active-mode status. When active, terminal and Telegram status render the Effective revision vector as `G15/C8/S31`; passive Telegram shows `State Flow: off`. Requested Global, CWD and Session snapshots show their own `#revision`, while Effective shows the vector. Inspection can refresh live shared revisions from other instances without publishing state or advancing a counter. Stop returns to the configured passive behavior. `autoStart` can enable active mode for genuinely new sessions; resumed branches restore their own enablement. See [configuration](docs/usage.md#configuration).
+Active mode is **opt-in**. Passive memory projection and the memory tools are enabled by default: existing state can be read or explicitly patched without an active episode or State Flow compaction. Every materially changed owner advances its independent scope revision even in passive mode, without displaying an active-mode status. When active, terminal and Telegram status render the Effective revision vector as `G15/C8/S31`; passive Telegram shows `State Flow: off`. Requested Global, CWD and Session snapshots show their own `#revision`, while Effective shows the vector. Inspection waits cancelably for a coherent shared view, with matching data and revisions, without publishing state or advancing a counter. Stop returns to the configured passive behavior. `autoStart` can enable active mode for genuinely new sessions; resumed branches restore their own enablement. See [configuration](docs/usage.md#configuration).
+
+### Active, passive, off
+
+- **Active:** Memory tools are available; the agent consolidates necessary final state changes before completing an iteration. Subsequent iterations use accepted state and new input rather than completed prior reasoning.
+- **Passive:** Memory tools and existing-state projection remain available by default. Patching is on demand, and ordinary conversation context continues without State Flow's active iteration reset.
+- **Configured off:** With the branch inactive and both `passiveTools` and `passiveBootstrap` false, neither memory tool nor bootstrap/state projection is exposed to the model. `autoStart: false` alone does not turn memory off.
+
+Modes select agent behavior, not a different disk persistence or fork-copy mechanism. Final consolidation does not require an empty ceremonial patch, and context projection does not delete native history. See [mode semantics and bootstrap terminology](docs/usage.md#active-passive-and-configured-off).
 
 ## State model
 
@@ -89,7 +97,7 @@ Registered Pi Skills may be compiled into source-addressed artifacts when durabl
 
 ## Incremental updates and history
 
-`patch_state` updates one or more named scopes atomically. Unmentioned values remain unchanged; object patches merge recursively, and `null` deletes an object key rather than becoming stored data.
+`patch_state` updates one or more named scopes atomically. It waits cancelably for the store lock, then applies authored Global/CWD patches to current canonical values, preserving other writers' untouched fields. Overlapping assignments follow successful acceptance order; correct repeats succeed without new semantic revisions. Session remains private. Object patches merge recursively, and `null` deletes an object key rather than becoming stored data.
 
 ```json
 {
@@ -124,9 +132,13 @@ Array ranges, structural `keys` reads and path-intersected `patch` projections s
 
 The default store is `~/.pi/agent/state-flow/`, independent of registered source files. Canonical `checkpoint.json`, `patches.jsonl` and `meta.json` files hold each scope's state, retained changes and metadata; session configuration and runtime identity are stored separately.
 
-**Git backups are optional.** When the store is a configured Git repository, accepted active turns may create versioned backups of State Flow-owned files. If the attached branch has an explicitly configured remote, State Flow then pushes the exact current backup commit there asynchronously and without force. Within one Pi process, only one push per repository can run at a time; overlapping attempts are skipped and a later accepted turn pushes the latest backup. Session shutdown waits for that repository's active push to close or time out. Commit failures warn locally; repeated push failures produce one concise warning until a successful push, with redacted Git detail kept in the local diagnostic log. Neither failure rejects or rolls back accepted memory. Backup needs a Git commit identity, but accepting and persisting state does not. Git history can be inspected separately, but it is not the authority for `read_state` or automatic restoration of expired semantic boundaries.
+**Persistence is optimistic across abrupt shutdown.** Short publication exclusion preserves independent shared fields between cooperating writers; the last accepted write wins on overlap. Per-file atomic replacement does not guarantee power-loss survival or crash-atomic recovery. That [accepted limitation](docs/filesystem-recovery.md#power-loss-durability) is not a release gate; no additional recovery journal or storage format is planned.
+
+**Git backups are optional.** When the store is a configured Git repository, accepted active turns may create versioned backups of State Flow-owned files. A busy store explicitly defers backup when Pi provides no cancellable settlement wait (including SDK 0.87); a later accepted turn retries without changing memory or blocking native Abort. If the attached branch has an explicitly configured remote, State Flow then pushes the exact current backup commit there asynchronously and without force. Within one Pi process, only one push per repository can run at a time; overlapping attempts are skipped and a later accepted turn pushes the latest backup. Session shutdown waits for that repository's active push to close or time out. Commit failures warn locally; repeated push failures produce one concise warning until a successful push, with redacted Git detail kept in the local diagnostic log. Neither failure rejects or rolls back accepted memory. Backup needs a Git commit identity, but accepting and persisting state does not. Git history can be inspected separately, but it is not the authority for `read_state` or automatic restoration of expired semantic boundaries.
+
+Resume and tree navigation restore the selected retained session boundary over current shared global/CWD memory. A new session gets its own session layer. Supported native forks copy selected session state into a new owner without changing the parent's private data. Expired, incomplete or contradictory boundaries never silently substitute newer private state during restoration. Explicit Start is a mode change, not historical restoration: it activates validated **current** memory of that same session, including private state, even after expired active/passive, interrupted or pre-runtime selections. Available aligned history and revisions survive; unavailable history is not recreated. Malformed storage, unsafe fork copying and concurrent writes remain fenced. See [fork support](docs/usage.md#fork-support-and-limits) and [storage recovery](docs/usage.md#storage-and-recovery).
 
-Resume and tree navigation restore the selected retained session boundary over current shared global/CWD memory. A new session gets its own session layer. Supported native forks copy selected session state into a new owner without changing the parent's private data. Expired, incomplete or contradictory boundaries fail closed rather than silently substituting newer state. See [fork support](docs/usage.md#fork-support-and-limits) and [storage recovery](docs/usage.md#storage-and-recovery).
+SDK/launcher integrations can use [advisory continuation APIs](docs/architecture.md#session-continuation). Provenance inspection and candidate building are now asynchronous and accept host cancellation; they neither open native sessions nor install automatic resume. Run preparation and missing-artifact maintenance now wait cancelably before inference; embeddings can also use the [transaction APIs](docs/architecture.md#asynchronous-storage-transaction). Accepted-runtime Stop switches local policy/context immediately and awaits runtime-only persistence. Current-head Start also awaits coherent capture/acceptance before enabling mode; Stop or selection can cancel its wait. Telegram acknowledges controls early. Startup/recovery and exact restoration/fork still require migration, including Start's initial-attachment and unaccepted-fork paths.
 
 The canonical storage-format boundary introduced in 0.17 still applies: current versions accept only the canonical store contract and provide no in-place predecessor converter. Preserve existing data and check the [format boundary](docs/usage.md#moving-a-store-and-the-017-format-boundary) before changing versions or moving a store.
 

package/node_modules/@llblab/pi-state-flow/dist/index.d.ts

@@ -13,6 +13,7 @@ export { planKnowledgeRehydration, type RehydrationOptions, type RehydrationPhas
 export { TemporalRuntime } from "./lib/runtime.ts";
 export { hasCompiledSkillArtifact, hashSkillSource, SKILL_ARTIFACT_COMPILER, type SuccessfulSkillRead } from "./lib/skills.ts";
 export { emptyState, isMaterializedState, isStateDocument, overlayStates, projectStateForModel, updateMaterializedArtifacts, type AtomicScopePatches, type MaterializedState, type ScopedPatch, type ScopedStates, type ScopePatch, type SemanticTransition, type StateDocument, type StatePatch, type StateScope, type TerminalTransition } from "./lib/state.ts";
-export { buildStateFlowSectionView, createStateFlowTelegramAdapter, formatStateFlowSectionLabel, loadStateFlowTelegramModules, STATE_FLOW_TELEGRAM_ID, type StateFlowTelegramAdapter, type StateFlowTelegramButton, type StateFlowTelegramCallbackContext, type StateFlowTelegramControlResult, type StateFlowTelegramLoader, type StateFlowTelegramModules, type StateFlowTelegramPort, type StateFlowTelegramSectionContext, type StateFlowTelegramSectionModule, type StateFlowTelegramSnapshot, type StateFlowTelegramView } from "./lib/telegram.ts";
+export { PublicationBusyError } from "./lib/storage.ts";
+export { buildStateFlowSectionView, createStateFlowTelegramAdapter, formatStateFlowSectionLabel, loadStateFlowTelegramModules, STATE_FLOW_TELEGRAM_ID, type StateFlowTelegramAdapter, type StateFlowTelegramButton, type StateFlowTelegramCallbackContext, type StateFlowTelegramControlResult, type StateFlowTelegramInspection, type StateFlowTelegramInspectionPort, type StateFlowTelegramLoader, type StateFlowTelegramModules, type StateFlowTelegramPort, type StateFlowTelegramSectionContext, type StateFlowTelegramSectionModule, type StateFlowTelegramSnapshot, type StateFlowTelegramView } from "./lib/telegram.ts";
 export { advanceTemporalState, readTemporalState, temporalScopeRevisions, type ScopeRevisions, type TemporalState } from "./lib/temporal.ts";
 export { parseStateReadPath, readStatePath, type StateReadQuery, type StateReadResult } from "./lib/query.ts";

package/node_modules/@llblab/pi-state-flow/dist/index.js

@@ -12,6 +12,7 @@ export { planKnowledgeRehydration } from "./lib/rehydration.js";
 export { TemporalRuntime } from "./lib/runtime.js";
 export { hasCompiledSkillArtifact, hashSkillSource, SKILL_ARTIFACT_COMPILER } from "./lib/skills.js";
 export { emptyState, isMaterializedState, isStateDocument, overlayStates, projectStateForModel, updateMaterializedArtifacts } from "./lib/state.js";
+export { PublicationBusyError } from "./lib/storage.js";
 export { buildStateFlowSectionView, createStateFlowTelegramAdapter, formatStateFlowSectionLabel, loadStateFlowTelegramModules, STATE_FLOW_TELEGRAM_ID } from "./lib/telegram.js";
 export { advanceTemporalState, readTemporalState, temporalScopeRevisions } from "./lib/temporal.js";
 export { parseStateReadPath, readStatePath } from "./lib/query.js";

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

@@ -100,7 +100,7 @@ export declare function hashArtifactSource(source: string | Uint8Array): string;
 export declare function isArtifactHash(value: unknown): value is string;
 export declare function validateArtifactMetadata(value: unknown, path?: string): asserts value is ArtifactMetadata;
 export declare function isArtifactMetadata(value: unknown): value is ArtifactMetadata;
-export declare function validateArtifactRegistry(value: unknown): asserts value is ArtifactRegistry;
+export declare function validateArtifactRegistry(value: unknown, context?: string): asserts value is ArtifactRegistry;
 export declare function selectArtifactsByTags(registry: ArtifactRegistry, tags: readonly string[], match?: "all" | "any"): string[];
 export declare function isArtifactRegistry(value: unknown): value is ArtifactRegistry;
 /** Parse one scope `meta.json` provenance registry; missing input means no recorded evidence. */
@@ -118,7 +118,7 @@ export declare function pruneArtifactProvenance(registry: Readonly<ArtifactProve
 /** Validate and apply a whole compilation/removal cohort of model-visible artifacts. */
 export declare function updateArtifactRegistry(registry: ArtifactRegistry, updates: readonly ArtifactCompilationUpdate[], removed?: readonly string[]): ArtifactRegistry;
 /** Validate authored fields only: legacy retained evidence stays readable but cannot be model-edited. */
-export declare function validateModelArtifactPatch(patch: JsonObject): void;
+export declare function validateModelArtifactPatch(patch: JsonObject, context?: string): void;
 /** Strip retained runtime bookkeeping from one model-visible artifact entry. */
 export declare function projectArtifactForModel(entry: unknown): unknown;
 export type ArtifactModelHints = Readonly<Record<string, string | readonly string[]>>;

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

@@ -99,13 +99,13 @@ export function isArtifactMetadata(value) {
         return false;
     }
 }
-export function validateArtifactRegistry(value) {
+export function validateArtifactRegistry(value, context = "artifacts") {
     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);
+        validateArtifactMetadata(metadata, `${context}[${JSON.stringify(path)}]`);
     }
 }
 export function selectArtifactsByTags(registry, tags, match = "all") {
@@ -261,7 +261,7 @@ export function compileArtifact(update) {
     // Timestamps are runtime evidence; the model-visible entry never retains them.
     const semantic = structuredClone(update.output);
     delete semantic.compiled_at;
-    validateArtifactMetadata(semantic, update.source.path);
+    validateArtifactMetadata(semantic, `${update.source.scope ? `${update.source.scope}.` : ""}artifacts[${JSON.stringify(update.source.path)}]`);
     return {
         semantic,
         provenance: {
@@ -325,13 +325,13 @@ export function updateArtifactRegistry(registry, updates, removed = []) {
 /** Runtime-owned artifact fields that never belong in ordinary model context. */
 const RUNTIME_ARTIFACT_FIELDS = [...MODEL_FORBIDDEN_PROVENANCE_FIELDS, "compiled_at", "hint"];
 /** Validate authored fields only: legacy retained evidence stays readable but cannot be model-edited. */
-export function validateModelArtifactPatch(patch) {
+export function validateModelArtifactPatch(patch, context = "artifacts") {
     for (const [path, entry] of Object.entries(patch)) {
         if (!isObject(entry))
             continue; // Whole-artifact deletion and materialized shape belong to the transition owner.
         const field = RUNTIME_ARTIFACT_FIELDS.find((field) => Object.hasOwn(entry, field));
         if (field !== undefined)
-            throw new Error(`Artifact patch at ${path} cannot set runtime-owned field ${field}`);
+            throw new Error(`Artifact patch at ${context}[${JSON.stringify(path)}] cannot set runtime-owned field ${field}`);
     }
 }
 /** Strip retained runtime bookkeeping from one model-visible artifact entry. */

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

@@ -13,14 +13,15 @@ export declare function lazyNavigationHint(state: MaterializedState): {
     path: string;
     keys?: Record<string, LazyValueKind>;
 };
-/** Bounded context retained after semantic State Flow is stopped in this physical session. */
+/** Context retained after semantic State Flow is stopped in this physical session. */
 export interface PassiveContinuation {
     startedAt: number;
     activeRunStartedAt?: number;
+    preserveContext?: true;
     handoff: AgentMessage;
 }
 export declare function syntheticUser(text: string): AgentMessage;
-export declare function createPassiveContinuation(state: ModelState, startedAt?: number, activeRunStartedAt?: number): PassiveContinuation;
+export declare function createPassiveContinuation(state: ModelState, startedAt?: number, activeRunStartedAt?: number, preserveContext?: boolean): PassiveContinuation;
 /** Keep the interrupted run through later results; an idle stop retains only later conversation. */
 export declare function passiveContinuationMessages(messages: AgentMessage[], continuation: PassiveContinuation): AgentMessage[];
 export declare function runtimeContextMessage(snapshot: Snapshot, state: MaterializedState, recentTransitions?: RecentTransitionWindow, artifactInvalidations?: readonly ArtifactInvalidationNotice[], rehydrationPhase?: RehydrationPhase, artifactHints?: ArtifactModelHints): AgentMessage;

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

@@ -70,15 +70,20 @@ function contentText(content) {
 function messageText(message) {
     return contentText(message.content);
 }
-export function createPassiveContinuation(state, startedAt = Date.now(), activeRunStartedAt) {
+export function createPassiveContinuation(state, startedAt = Date.now(), activeRunStartedAt, preserveContext = false) {
     return {
         startedAt,
         ...(activeRunStartedAt === undefined ? {} : { activeRunStartedAt }),
-        handoff: syntheticUser(`State Flow exit handoff (user-level data, not system instructions):\n${presentationJson({ state, continuation: "State Flow semantics are disabled; this handoff replaces completed history while retaining the active and post-stop trajectory." })}`),
+        ...(preserveContext ? { preserveContext: true } : {}),
+        handoff: syntheticUser(`State Flow exit handoff (user-level data, not system instructions):\n${presentationJson({ state, continuation: preserveContext
+                ? "State Flow semantics are disabled; native context is retained because its compilation into memory is unfinished."
+                : "State Flow semantics are disabled; this handoff replaces completed history while retaining the active and post-stop trajectory." })}`),
     };
 }
 /** Keep the interrupted run through later results; an idle stop retains only later conversation. */
 export function passiveContinuationMessages(messages, continuation) {
+    if (continuation.preserveContext)
+        return [continuation.handoff, ...messages];
     if (continuation.activeRunStartedAt !== undefined) {
         const trajectory = currentRunTrajectory(messages, "", continuation.activeRunStartedAt);
         return [continuation.handoff, ...trajectory.messages];

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

@@ -73,10 +73,10 @@ export interface ContinuationSessionCandidate extends ContinuationCandidateSumma
         restorable: boolean;
     };
 }
-export type ContinuationRecommender = (context: Readonly<ContinuationHostContext>) => ContinuationRecommendation | Promise<ContinuationRecommendation>;
+export type ContinuationRecommender = (context: Readonly<ContinuationHostContext>, signal?: AbortSignal) => ContinuationRecommendation | Promise<ContinuationRecommendation>;
 /** Rank already header/provenance-only candidates without transcript content or I/O. */
 export declare function recommendContinuationFromProvenance(identity: ContinuationProjectIdentity, candidates: readonly ContinuationSessionCandidate[]): ContinuationRecommendation;
-export declare function resolveContinuationStartup(context: ContinuationHostContext, intent: ContinuationHostIntent, recommend: ContinuationRecommender): Promise<ContinuationStartupDecision>;
+export declare function resolveContinuationStartup(context: ContinuationHostContext, intent: ContinuationHostIntent, recommend: ContinuationRecommender, signal?: AbortSignal): Promise<ContinuationStartupDecision>;
 export interface NativeSessionHeader {
     file: string;
     id: string;
@@ -106,6 +106,6 @@ export declare function discoverNativeSessionHeaders(sessionDir: string): {
         error: string;
     }>;
 };
-/** Inspect only exact current runtime provenance; never initialize, migrate, lock, checkout, or publish. */
-export declare function inspectStateFlowContinuationProvenance(header: NativeSessionHeader, repositoryRoot: string): Pick<ContinuationCandidateProvenance, "stateFlow" | "reason">;
-export declare function buildContinuationCandidates(headers: readonly NativeSessionHeader[], inspect: (header: Readonly<NativeSessionHeader>) => ContinuationCandidateProvenance | undefined): ContinuationSessionCandidate[];
+/** Await one exact canonical cohort; never read transcript bodies, initialize, or publish. */
+export declare function inspectStateFlowContinuationProvenance(header: Readonly<NativeSessionHeader>, repositoryRoot: string, signal?: AbortSignal): Promise<Pick<ContinuationCandidateProvenance, "stateFlow" | "reason">>;
+export declare function buildContinuationCandidates(headers: readonly NativeSessionHeader[], inspect: (header: Readonly<NativeSessionHeader>, signal?: AbortSignal) => ContinuationCandidateProvenance | undefined | Promise<ContinuationCandidateProvenance | undefined>, signal?: AbortSignal): Promise<ContinuationSessionCandidate[]>;

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

@@ -1,8 +1,10 @@
-import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { loadScopeStream, resolveSessionAddress, sessionRuntimePaths } from "./durable.js";
+import { parseScopeStream, resolveSessionAddress, sessionRuntimePaths, temporalScopePaths } from "./durable.js";
 import { MAX_HISTORY_LIMIT } from "./history.js";
+import { diagnosticText } from "./protocol.js";
 import { parseSessionRuntime } from "./snapshot.js";
+import { withStorageTransaction } from "./storage.js";
 import { validateScopeLineage } from "./temporal.js";
 /**
  * Preserve host-owned explicit session intent and consult State Flow only for
@@ -48,7 +50,8 @@ export function recommendContinuationFromProvenance(identity, candidates) {
         return { action: "new", reason: "ineligible" };
     return { action: "resume", sessionFile: candidate.sessionFile, sessionId: candidate.sessionId, reason: "latest-enabled-state-flow" };
 }
-export async function resolveContinuationStartup(context, intent, recommend) {
+export async function resolveContinuationStartup(context, intent, recommend, signal) {
+    signal?.throwIfAborted();
     switch (intent.kind) {
         case "new":
             return { action: "new", reason: "explicit-new" };
@@ -60,8 +63,11 @@ export async function resolveContinuationStartup(context, intent, recommend) {
             return { action: "native", mode: "continue-recent" };
         case "no-session":
             return { action: "native", mode: "no-session" };
-        case "default":
-            return recommend(Object.freeze({ ...context }));
+        case "default": {
+            const recommendation = await recommend(Object.freeze({ ...context }), signal);
+            signal?.throwIfAborted();
+            return recommendation;
+        }
     }
 }
 const MAX_SESSION_HEADER_BYTES = 64 * 1024;
@@ -124,54 +130,62 @@ export function discoverNativeSessionHeaders(sessionDir) {
     }
     return { headers, invalid };
 }
-function readRegular(path) {
-    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, repositoryRoot) {
-    const sessionKey = resolveSessionAddress(header.file, header.id, header.timestamp).key;
-    const paths = sessionRuntimePaths(header.cwd, header.id, repositoryRoot, sessionKey);
+/** Await one exact canonical cohort; never read transcript bodies, initialize, or publish. */
+export async function inspectStateFlowContinuationProvenance(header, repositoryRoot, signal) {
+    signal?.throwIfAborted();
+    const selected = { ...header };
+    const root = resolve(repositoryRoot);
+    const sessionKey = resolveSessionAddress(selected.file, selected.id, selected.timestamp).key;
+    const paths = sessionRuntimePaths(selected.cwd, selected.id, root, sessionKey);
+    const absent = { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
     try {
-        const config = readRegular(paths.config);
-        const runtimeSource = readRegular(paths.runtime);
-        const meta = readRegular(paths.meta);
-        if (config === undefined && runtimeSource === undefined && meta === undefined) {
-            return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
-        }
-        const runtime = parseSessionRuntime(config, runtimeSource, 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" };
-        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 canonical temporal cohort");
-        // Shared streams are current, independently validated by their codecs, not frozen to this session's history.
-        validateScopeLineage(session, "session", runtime.meta.lineage, MAX_HISTORY_LIMIT);
-        return { stateFlow: { enabled: true, restorable: true }, reason: "canonical session lineage is valid beside current shared streams" };
+        if (!lstatSync(root, { throwIfNoEntry: false }))
+            return absent;
+        const result = await withStorageTransaction(root, (tx) => {
+            const files = new Map(tx.capture(selected.cwd, selected.id, root, sessionKey).files.map((file) => [file.path, file.content]));
+            const privatePaths = temporalScopePaths(selected.cwd, selected.id, "session", root, sessionKey);
+            if ([paths.config, paths.runtime, privatePaths.meta, privatePaths.checkpoint, privatePaths.patches].every((path) => files.get(path) === undefined))
+                return absent;
+            const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), selected.cwd, selected.id);
+            if (!runtime)
+                throw new Error("incomplete canonical session runtime");
+            if (!runtime.config.enabled)
+                return { stateFlow: { enabled: false, restorable: true }, reason: "State Flow stopped on selected runtime" };
+            const streams = ["global", "cwd", "session"].map((scope) => {
+                const owned = temporalScopePaths(selected.cwd, selected.id, scope, root, sessionKey);
+                return parseScopeStream(files.get(owned.checkpoint), files.get(owned.patches), scope, scope === "cwd" ? selected.cwd : undefined, files.get(owned.meta));
+            });
+            if (streams.some((stream) => stream === undefined))
+                throw new Error("incomplete canonical temporal cohort");
+            // Shared streams remain current and independently valid; only the private stream binds to this lineage.
+            validateScopeLineage(streams[2], "session", runtime.meta.lineage, MAX_HISTORY_LIMIT);
+            return { stateFlow: { enabled: true, restorable: true }, reason: "canonical session lineage is valid beside current shared streams" };
+        }, signal);
+        signal?.throwIfAborted();
+        return result;
     }
     catch (error) {
-        return { stateFlow: { enabled: true, restorable: false }, reason: `State Flow runtime is ineligible: ${error instanceof Error ? error.message : String(error)}` };
+        signal?.throwIfAborted();
+        return { stateFlow: { enabled: true, restorable: false }, reason: `State Flow runtime is ineligible: ${diagnosticText(error)}` };
     }
 }
-export function buildContinuationCandidates(headers, inspect) {
+export async function buildContinuationCandidates(headers, inspect, signal) {
+    signal?.throwIfAborted();
+    const selected = headers.map((header) => Object.freeze({ ...header }));
     const candidates = [];
-    for (const header of headers) {
-        const provenance = inspect(Object.freeze({ ...header }));
+    for (const header of selected) {
+        signal?.throwIfAborted();
+        const provenance = await inspect(header, signal);
+        signal?.throwIfAborted();
         if (!provenance)
             continue;
         candidates.push({
+            ...provenance,
+            stateFlow: { ...provenance.stateFlow },
             sessionFile: header.file,
             sessionId: header.id,
             lastActivity: header.lastActivity,
             cwd: header.cwd,
-            ...provenance,
         });
     }
     return candidates;

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

@@ -22,7 +22,7 @@ export function hasCwdMaterialization(cwd, repositoryRoot) {
     if (checkpoint.content !== undefined)
         return parseScopeStream(checkpoint.content, patches.content, "cwd", cwd, meta.content) !== undefined;
     if (patches.content !== undefined)
-        throw new Error(`State Flow tail has no provable checkpoint: ${directory}`);
+        throw new Error(`State Flow tail has no provable checkpoint: ${JSON.stringify(directory)}`);
     return false;
 }
 /** Semantic files contain no runtime envelope; temporal boundaries and CWD ownership live in meta.json. */
@@ -124,7 +124,7 @@ export function sessionRuntimePaths(cwd, sessionId, repositoryRoot, sessionKey =
 export function loadScopeStream(cwd, sessionId, scope, repositoryRoot, sessionKey = sessionId) {
     const paths = temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessionKey);
     if (readRegularBytes(join(paths.directory, STATE_FILE), repositoryRoot) !== undefined) {
-        throw new Error(`Unsupported State Flow storage format: ${paths.directory}`);
+        throw new Error(`Unsupported State Flow storage format: ${JSON.stringify(paths.directory)}`);
     }
     return parseScopeStream(readRegularFile(paths.checkpoint, repositoryRoot), readRegularFile(paths.patches, repositoryRoot), scope, scope === "cwd" ? cwd : undefined, readRegularFile(paths.meta, repositoryRoot));
 }
@@ -147,7 +147,7 @@ export function temporalStateFileUpdates(cwd, sessionId, view, scopes, repositor
         seen.add(scope);
         const paths = temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessionKey);
         if (readRegularBytes(join(paths.directory, STATE_FILE), repositoryRoot) !== undefined) {
-            throw new Error(`Unsupported State Flow storage format: ${paths.directory}`);
+            throw new Error(`Unsupported State Flow storage format: ${JSON.stringify(paths.directory)}`);
         }
         const sources = serializeScopeStream(view.scopes[scope], scope, scope === "cwd" ? cwd : undefined);
         return [{ path: paths.checkpoint, content: sources.checkpoint }, { path: paths.patches, content: sources.patches }];
@@ -190,14 +190,14 @@ function parseMetadataDocument(source, label) {
 }
 /** Missing provenance is unavailable evidence, never corrupt state. Unknown metadata is preserved by writers. */
 export function parseScopeProvenance(source, path) {
-    const value = parseMetadataDocument(source, `State Flow provenance file: ${path}`);
+    const value = parseMetadataDocument(source, `State Flow provenance file: ${JSON.stringify(path)}`);
     if (Object.keys(value).length === 0)
         return {};
     if (value.version !== 1 && value.version !== 2)
-        throw new Error(`Invalid State Flow provenance document: ${path}`);
+        throw new Error(`Invalid State Flow provenance document: ${JSON.stringify(path)}`);
     if (!Object.hasOwn(value, "artifacts"))
         return {};
-    return parseArtifactProvenanceRegistry(value.artifacts, `State Flow provenance at ${path}`);
+    return parseArtifactProvenanceRegistry(value.artifacts, `State Flow provenance at ${JSON.stringify(path)}`);
 }
 /** Dedicated runtime storage, independent from Markdown source discovery. */
 export function getDurableRepositoryRoot(agentDir = getAgentDir()) {
@@ -273,7 +273,7 @@ function missing(error) {
 function assertWithinRepository(path, repositoryRoot) {
     const child = relative(repositoryRoot, path);
     if (child === "" || child === ".." || child.startsWith(`..${sep}`)) {
-        throw new Error(`Durable State Flow path escapes its repository: ${path}`);
+        throw new Error(`Durable State Flow path escapes its repository: ${JSON.stringify(path)}`);
     }
 }
 /** Reject symlinked directory components instead of following them during reads or writes. */
@@ -295,7 +295,7 @@ function assertDirectoryChain(repositoryRoot, directory, create) {
         try {
             const metadata = lstatSync(current);
             if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
-                throw new Error(`Durable State Flow directory is not a regular directory: ${current}`);
+                throw new Error(`Durable State Flow directory is not a regular directory: ${JSON.stringify(current)}`);
             }
         }
         catch (error) {
@@ -315,7 +315,7 @@ function readRegularBytes(path, repositoryRoot) {
     try {
         descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
         if (!fstatSync(descriptor).isFile()) {
-            throw new Error(`Durable State Flow path is not a regular file: ${path}`);
+            throw new Error(`Durable State Flow path is not a regular file: ${JSON.stringify(path)}`);
         }
         return readFileSync(descriptor);
     }
@@ -325,7 +325,7 @@ function readRegularBytes(path, repositoryRoot) {
         if (error instanceof Error
             && "code" in error
             && error.code === "ELOOP") {
-            throw new Error(`Durable State Flow path is not a regular file: ${path}`);
+            throw new Error(`Durable State Flow path is not a regular file: ${JSON.stringify(path)}`);
         }
         throw error;
     }
@@ -348,7 +348,7 @@ function fileBase(path, repositoryRoot) {
 }
 function assertCurrentBytes(path, root, expected) {
     if (byteIdentity(readRegularBytes(path, root)) !== byteIdentity(expected)) {
-        throw new Error(`State Flow file conflict at ${path}; preserve concurrent bytes and reconcile before retrying`);
+        throw new Error(`State Flow file conflict at ${JSON.stringify(path)}; concurrent bytes preserved`);
     }
 }
 /** Capture exact owned bytes for one compare-and-swap publication cohort. */
@@ -356,7 +356,7 @@ export function captureOwnedFileBases(paths, repositoryRoot) {
     const root = resolve(repositoryRoot);
     return paths.map((path) => {
         if (!isStateFlowOwnedPath(path, root))
-            throw new Error(`Cannot capture a non-State Flow path: ${path}`);
+            throw new Error(`Cannot capture a non-State Flow path: ${JSON.stringify(path)}`);
         return fileBase(resolve(path), root);
     });
 }
@@ -365,7 +365,7 @@ function prepareFile(path, repositoryRoot, content, expected) {
     assertDirectoryChain(repositoryRoot, dirname(path), true);
     const original = readRegularBytes(path, repositoryRoot);
     if (expected !== undefined && byteIdentity(original) !== expected.identity) {
-        throw new Error(`State Flow file conflict during preparation: ${path}`);
+        throw new Error(`State Flow file conflict during preparation: ${JSON.stringify(path)}`);
     }
     const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
     const next = content === undefined ? undefined : Buffer.from(content);
@@ -425,7 +425,7 @@ export function assertOwnedFileUpdates(updates, repositoryRoot) {
     const root = resolve(repositoryRoot);
     for (const update of updates) {
         if (!isStateFlowOwnedPath(update.path, root))
-            throw new Error(`Cannot inspect a non-State Flow path: ${update.path}`);
+            throw new Error(`Cannot inspect a non-State Flow path: ${JSON.stringify(update.path)}`);
         assertCurrentBytes(update.path, root, update.content === undefined ? undefined : Buffer.from(update.content));
     }
 }
@@ -439,13 +439,13 @@ export function writeOwnedFileUpdates(updates, bases, repositoryRoot) {
         for (const update of updates) {
             const path = resolve(update.path);
             if (!isStateFlowOwnedPath(path, root))
-                throw new Error(`Cannot update a non-State Flow path: ${path}`);
+                throw new Error(`Cannot update a non-State Flow path: ${JSON.stringify(path)}`);
             if (seen.has(path))
-                throw new Error(`Duplicate State Flow file update: ${path}`);
+                throw new Error(`Duplicate State Flow file update: ${JSON.stringify(path)}`);
             seen.add(path);
             const base = byPath.get(path);
             if (base === undefined)
-                throw new Error(`State Flow file update has no captured base: ${path}`);
+                throw new Error(`State Flow file update has no captured base: ${JSON.stringify(path)}`);
             prepared.push(prepareFile(path, root, update.content, base));
         }
     }
@@ -464,13 +464,13 @@ export function restoreDurableFileBases(bases, repositoryRoot, expectedCurrent)
     for (const base of bases) {
         assertWithinRepository(base.path, root);
         if (!isStateFlowOwnedPath(base.path, root)) {
-            throw new Error(`Cannot restore a non-State Flow path: ${base.path}`);
+            throw new Error(`Cannot restore a non-State Flow path: ${JSON.stringify(base.path)}`);
         }
     }
     for (const base of bases) {
         const update = expected.get(resolve(base.path));
         if (update === undefined)
-            throw new Error(`Rollback has no published basis: ${base.path}`);
+            throw new Error(`Rollback has no published basis: ${JSON.stringify(base.path)}`);
         assertCurrentBytes(base.path, root, update.content === undefined ? undefined : Buffer.from(update.content));
         if (base.identity === "missing") {
             rmSync(base.path, { force: true });
@@ -478,7 +478,7 @@ export function restoreDurableFileBases(bases, repositoryRoot, expectedCurrent)
         }
         const original = base.bytes ?? (base.content === undefined ? undefined : Buffer.from(base.content));
         if (original === undefined)
-            throw new Error(`Durable State Flow base content is missing: ${base.path}`);
+            throw new Error(`Durable State Flow base content is missing: ${JSON.stringify(base.path)}`);
         assertDirectoryChain(root, dirname(base.path), true);
         const temporary = join(dirname(base.path), `.${basename(base.path)}.${process.pid}.${randomUUID()}.restore`);
         try {