@llblab/pi-kit 0.25.0 → 0.27.0

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

@@ -1,12 +1,41 @@
 /** Await a coherent capture; hosts without cancellation may refuse contention instead of hanging Abort. */
 export declare function backupCurrentStateFlowFiles(repositoryRoot: string, signal?: AbortSignal, waitForLock?: boolean): Promise<string | undefined>;
 /** Skip overlapping pushes; the next accepted turn can push the latest HEAD. */
-export declare function startStateFlowBackupPush(repositoryRoot: string, onFailure: (error: unknown) => void, onSuccess?: () => void): boolean;
+export declare function startStateFlowBackupPush(repositoryRoot: string, onFailure: (error: unknown) => void, onSuccess?: () => void, signal?: AbortSignal): boolean;
 /** Resolve only after the push process has closed (including timeout termination). */
 export declare function awaitInFlightBackupPushes(repositoryRoot: string): Promise<void>;
 /** Push the current backup commit to its explicitly configured branch remote without blocking settlement. */
-export declare function pushCurrentStateFlowBackup(repositoryRoot: string): Promise<{
+export declare function pushCurrentStateFlowBackup(repositoryRoot: string, signal?: AbortSignal): Promise<{
     commit: string;
     remote: string;
     ref: string;
 } | undefined>;
+/**
+ * Settled-turn backup obligation owned by one extension instance: an accepted
+ * publication makes a backup due, an accepted turn permits it at settlement,
+ * and one lifetime cancels owned captures/pushes without touching accepted state.
+ */
+export declare class SettledTurnBackup {
+    #private;
+    /** An accepted canonical publication makes the next settled-turn backup due. */
+    markPublished(): void;
+    /** An accepted turn permits the due backup at its settlement. */
+    markTurnAccepted(): void;
+    /** Forget the current turn's permission without dropping a due backup. */
+    clearTurn(): void;
+    /** Consume the accepted-turn permission; true only when a backup is also due. */
+    takeSettledTurn(): boolean;
+    /** Lifetime signal for owned captures and pushes. */
+    get lifetime(): AbortSignal;
+    /** Cancel owned work and the due backup, then open a fresh lifetime. */
+    cancel(): void;
+    /** Cancel owned work for shutdown without opening a new lifetime. */
+    abort(): void;
+    /** Track one owned capture until it settles. */
+    track<T>(operation: Promise<T>): Promise<T>;
+    /** Owned captures still in flight. */
+    get operations(): Promise<unknown>[];
+    /** True once per failure streak; a successful push resets it. */
+    claimPushFailureNotice(): boolean;
+    resetPushFailureNotice(): void;
+}

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

@@ -204,18 +204,20 @@ export function backupCurrentStateFlowFiles(repositoryRoot, signal, waitForLock
     return withBackupLock(repositoryRoot, (root) => commitCurrentOwnedFiles(root, currentHead(root), signal, waitForLock), signal, waitForLock);
 }
 /** Skip overlapping pushes; the next accepted turn can push the latest HEAD. */
-export function startStateFlowBackupPush(repositoryRoot, onFailure, onSuccess) {
+export function startStateFlowBackupPush(repositoryRoot, onFailure, onSuccess, signal) {
     const root = resolve(repositoryRoot);
-    if (activePushes.has(root))
+    if (signal?.aborted || activePushes.has(root))
         return false;
-    const push = pushCurrentStateFlowBackup(root).then((result) => {
-        if (result) {
+    const push = pushCurrentStateFlowBackup(root, signal).then((result) => {
+        if (result && !signal?.aborted) {
             try {
                 onSuccess?.();
             }
             catch { /* Reporting cannot change push acceptance. */ }
         }
     }, (error) => {
+        if (signal?.aborted)
+            return;
         try {
             onFailure(error);
         }
@@ -231,15 +233,17 @@ export async function awaitInFlightBackupPushes(repositoryRoot) {
         await push;
 }
 /** Push the current backup commit to its explicitly configured branch remote without blocking settlement. */
-export function pushCurrentStateFlowBackup(repositoryRoot) {
+export function pushCurrentStateFlowBackup(repositoryRoot, signal) {
     return new Promise((resolvePush, rejectPush) => {
         let root;
         let commit;
         let destination;
         try {
+            signal?.throwIfAborted();
             root = assertRepositoryRoot(repositoryRoot);
             commit = currentHead(root);
             destination = configuredPushDestination(root);
+            signal?.throwIfAborted();
         }
         catch (error) {
             rejectPush(new Error(redactGitDiagnostic(error instanceof Error ? error.message : String(error))));
@@ -282,6 +286,7 @@ export function pushCurrentStateFlowBackup(repositoryRoot) {
                 return;
             settled = true;
             clearTimeout(timeout);
+            signal?.removeEventListener("abort", cancelled);
             if (error)
                 rejectPush(error);
             else
@@ -297,5 +302,69 @@ export function pushCurrentStateFlowBackup(repositoryRoot) {
             child.stderr?.destroy(); });
         child.once("close", (code, endedBy) => finish(failure ?? (code === 0 ? undefined
             : new Error(`Git backup push failed (${endedBy ?? code}): ${redactGitDiagnostic(stderr.trim()) || "no diagnostic output"}`))));
+        function cancelled() {
+            terminate(signal?.reason instanceof Error ? signal.reason : new Error("Git backup push cancelled"));
+        }
+        signal?.addEventListener("abort", cancelled, { once: true });
+        if (signal?.aborted)
+            cancelled();
     });
 }
+/**
+ * Settled-turn backup obligation owned by one extension instance: an accepted
+ * publication makes a backup due, an accepted turn permits it at settlement,
+ * and one lifetime cancels owned captures/pushes without touching accepted state.
+ */
+export class SettledTurnBackup {
+    #turnAccepted = false;
+    #pending = false;
+    #lifetime = new AbortController();
+    #pushFailureNotified = false;
+    #operations = new Set();
+    /** An accepted canonical publication makes the next settled-turn backup due. */
+    markPublished() { this.#pending = true; }
+    /** An accepted turn permits the due backup at its settlement. */
+    markTurnAccepted() { this.#turnAccepted = true; }
+    /** Forget the current turn's permission without dropping a due backup. */
+    clearTurn() { this.#turnAccepted = false; }
+    /** Consume the accepted-turn permission; true only when a backup is also due. */
+    takeSettledTurn() {
+        if (!this.#turnAccepted)
+            return false;
+        this.#turnAccepted = false;
+        if (!this.#pending)
+            return false;
+        this.#pending = false;
+        return true;
+    }
+    /** Lifetime signal for owned captures and pushes. */
+    get lifetime() { return this.#lifetime.signal; }
+    /** Cancel owned work and the due backup, then open a fresh lifetime. */
+    cancel() {
+        this.#lifetime.abort();
+        this.#lifetime = new AbortController();
+        this.#pending = false;
+    }
+    /** Cancel owned work for shutdown without opening a new lifetime. */
+    abort() { this.#lifetime.abort(); }
+    /** Track one owned capture until it settles. */
+    async track(operation) {
+        this.#operations.add(operation);
+        try {
+            return await operation;
+        }
+        finally {
+            this.#operations.delete(operation);
+        }
+    }
+    /** Owned captures still in flight. */
+    get operations() { return [...this.#operations]; }
+    /** True once per failure streak; a successful push resets it. */
+    claimPushFailureNotice() {
+        if (this.#pushFailureNotified)
+            return false;
+        this.#pushFailureNotified = true;
+        return true;
+    }
+    resetPushFailureNotice() { this.#pushFailureNotified = false; }
+}

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

@@ -0,0 +1,37 @@
+/** Minimal shape of a cancellable owned lifecycle operation. */
+export interface OwnedOperation {
+    readonly controller: AbortController;
+    operation?: Promise<unknown>;
+}
+/**
+ * At most one current owner per lifecycle concern. A newer claim supersedes by
+ * explicit cancellation, and identity-guarded release prevents a late
+ * completion from clearing newer work.
+ */
+export declare class OwnedOperationSlot<E extends OwnedOperation> {
+    #private;
+    /** The current owner, if any. */
+    get current(): E | undefined;
+    /** True while `entry` still owns the slot. */
+    owns(entry: E): boolean;
+    /** Install a new owner; callers cancel a previous owner explicitly when supersession requires it. */
+    claim(entry: E): E;
+    /** Abort and forget the current owner; returns its operation for optional awaiting. */
+    cancel(): E["operation"] | undefined;
+    /** Forget `entry` only if it still owns the slot. */
+    release(entry: E): void;
+    /** Attach `operation` to `entry` and remember it until it settles, optionally releasing ownership then. */
+    track<P extends NonNullable<E["operation"]>>(entry: E, operation: P, releaseOnSettle?: boolean): P;
+    /** Tracked operations not yet settled, including superseded ones. */
+    get inflight(): Promise<unknown>[];
+}
+/** A renewable cancellation lifetime: ending it aborts every holder of the current signal. */
+export declare class RenewableLifetime {
+    #private;
+    /** Signal of the current lifetime. */
+    get signal(): AbortSignal;
+    /** Abort current holders and open a fresh lifetime. */
+    renew(reason?: unknown): void;
+    /** Abort current holders without opening a new lifetime (shutdown). */
+    end(reason?: unknown): void;
+}

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

@@ -0,0 +1,59 @@
+// Domain: one cancellable lifecycle owner slot shared by Start, inactive-mode persistence,
+// branch restoration, inference preparation and response reconciliation.
+/**
+ * At most one current owner per lifecycle concern. A newer claim supersedes by
+ * explicit cancellation, and identity-guarded release prevents a late
+ * completion from clearing newer work.
+ */
+export class OwnedOperationSlot {
+    #current;
+    #inflight = new Set();
+    /** The current owner, if any. */
+    get current() { return this.#current; }
+    /** True while `entry` still owns the slot. */
+    owns(entry) { return this.#current === entry; }
+    /** Install a new owner; callers cancel a previous owner explicitly when supersession requires it. */
+    claim(entry) {
+        this.#current = entry;
+        return entry;
+    }
+    /** Abort and forget the current owner; returns its operation for optional awaiting. */
+    cancel() {
+        const entry = this.#current;
+        entry?.controller.abort();
+        this.#current = undefined;
+        return entry?.operation;
+    }
+    /** Forget `entry` only if it still owns the slot. */
+    release(entry) {
+        if (this.#current === entry)
+            this.#current = undefined;
+    }
+    /** Attach `operation` to `entry` and remember it until it settles, optionally releasing ownership then. */
+    track(entry, operation, releaseOnSettle = true) {
+        entry.operation = operation;
+        this.#inflight.add(operation);
+        const settle = () => {
+            this.#inflight.delete(operation);
+            if (releaseOnSettle)
+                this.release(entry);
+        };
+        void operation.then(settle, settle);
+        return operation;
+    }
+    /** Tracked operations not yet settled, including superseded ones. */
+    get inflight() { return [...this.#inflight]; }
+}
+/** A renewable cancellation lifetime: ending it aborts every holder of the current signal. */
+export class RenewableLifetime {
+    #controller = new AbortController();
+    /** Signal of the current lifetime. */
+    get signal() { return this.#controller.signal; }
+    /** Abort current holders and open a fresh lifetime. */
+    renew(reason) {
+        this.#controller.abort(reason);
+        this.#controller = new AbortController();
+    }
+    /** Abort current holders without opening a new lifetime (shutdown). */
+    end(reason) { this.#controller.abort(reason); }
+}

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

@@ -0,0 +1,31 @@
+import { type JsonObject, type JsonValue } from "./json.ts";
+import type { SemanticState, StateScope } from "./state.ts";
+/** Planes whose object keys an intent may own by structured reference. */
+export type OwnedPlane = "working" | "lazy";
+/** One same-scope object-key target of an intent ownership reference. */
+export interface OwnedPath {
+    plane: OwnedPlane;
+    keys: string[];
+}
+/**
+ * Parse one structured `$ref` target as an ownership path of `scope`.
+ * Cross-scope, unscoped, `effective`, historical, plane-root, array-element
+ * and non-`working`/`lazy` targets are not ownership targets.
+ */
+export declare function parseOwnedPath(scope: StateScope, ref: string): OwnedPath | undefined;
+/** Extract unique ownership targets from structured references anywhere inside one intent value. */
+export declare function extractOwnedPaths(scope: StateScope, value: JsonValue): OwnedPath[];
+/**
+ * Compute the same-scope ownership cascade for intent keys removed between
+ * `before` and `after` (the state after authored operations). A target is
+ * kept while any remaining intent references it, an ancestor or a descendant;
+ * missing targets are skipped. The result is minimal (no target below
+ * another) and deterministically ordered.
+ */
+export declare function computeIntentCascade(scope: StateScope, before: SemanticState, after: SemanticState): OwnedPath[];
+/** Express cascade targets as explicit nested object-key deletions. */
+export declare function cascadeDeletionPatch(paths: readonly OwnedPath[]): JsonObject;
+/** Render an ownership target as its scoped `read_state` path. */
+export declare function formatOwnedPath(scope: StateScope, path: OwnedPath): string;
+/** Top-level `working`/`lazy` keys that at least one current intent of `scope` owns. */
+export declare function ownedTopLevelKeys(scope: StateScope, state: SemanticState): Record<OwnedPlane, Set<string>>;

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

@@ -0,0 +1,117 @@
+import { isObject } from "./json.js";
+const OWNED_PLANES = new Set(["working", "lazy"]);
+// Same key grammar as read_state value paths; array selectors never parse.
+const OBJECT_KEY = /^[A-Za-z_$][A-Za-z0-9_$-]*$/;
+/**
+ * Parse one structured `$ref` target as an ownership path of `scope`.
+ * Cross-scope, unscoped, `effective`, historical, plane-root, array-element
+ * and non-`working`/`lazy` targets are not ownership targets.
+ */
+export function parseOwnedPath(scope, ref) {
+    const parts = ref.split(".");
+    if (parts.length < 3 || parts[0] !== scope || !OWNED_PLANES.has(parts[1]))
+        return undefined;
+    const keys = parts.slice(2);
+    if (!keys.every((key) => OBJECT_KEY.test(key)))
+        return undefined;
+    return { plane: parts[1], keys };
+}
+function pathId(path) {
+    return JSON.stringify([path.plane, ...path.keys]);
+}
+/** Extract unique ownership targets from structured references anywhere inside one intent value. */
+export function extractOwnedPaths(scope, value) {
+    const found = new Map();
+    const visit = (node) => {
+        if (Array.isArray(node)) {
+            for (const item of node)
+                visit(item);
+            return;
+        }
+        if (!isObject(node))
+            return;
+        if (typeof node.$ref === "string") {
+            const path = parseOwnedPath(scope, node.$ref);
+            if (path)
+                found.set(pathId(path), path);
+        }
+        for (const key of Object.keys(node))
+            if (key !== "$ref" || typeof node[key] !== "string")
+                visit(node[key]);
+    };
+    visit(value);
+    return [...found.values()];
+}
+function related(left, right) {
+    if (left.plane !== right.plane)
+        return false;
+    const length = Math.min(left.keys.length, right.keys.length);
+    for (let index = 0; index < length; index++)
+        if (left.keys[index] !== right.keys[index])
+            return false;
+    return true;
+}
+function exists(state, path) {
+    let node = state[path.plane];
+    for (const key of path.keys) {
+        if (!isObject(node) || !Object.hasOwn(node, key))
+            return false;
+        node = node[key];
+    }
+    return true;
+}
+/**
+ * Compute the same-scope ownership cascade for intent keys removed between
+ * `before` and `after` (the state after authored operations). A target is
+ * kept while any remaining intent references it, an ancestor or a descendant;
+ * missing targets are skipped. The result is minimal (no target below
+ * another) and deterministically ordered.
+ */
+export function computeIntentCascade(scope, before, after) {
+    const previous = isObject(before.intents) ? before.intents : {};
+    const remaining = isObject(after.intents) ? after.intents : {};
+    const deleted = Object.keys(previous).filter((key) => !Object.hasOwn(remaining, key));
+    if (deleted.length === 0)
+        return [];
+    const candidates = new Map();
+    for (const key of deleted)
+        for (const path of extractOwnedPaths(scope, previous[key]))
+            candidates.set(pathId(path), path);
+    if (candidates.size === 0)
+        return [];
+    const retained = Object.values(remaining).flatMap((value) => extractOwnedPaths(scope, value));
+    const owned = [...candidates.values()].filter((path) => !retained.some((other) => related(path, other)) && exists(after, path));
+    return owned
+        .filter((path) => !owned.some((other) => other.keys.length < path.keys.length && related(path, other)))
+        .sort((left, right) => pathId(left).localeCompare(pathId(right)));
+}
+/** Express cascade targets as explicit nested object-key deletions. */
+export function cascadeDeletionPatch(paths) {
+    const patch = {};
+    const define = (target, key, value) => Object.defineProperty(target, key, { value, enumerable: true, configurable: true, writable: true });
+    for (const path of paths) {
+        if (!Object.hasOwn(patch, path.plane))
+            define(patch, path.plane, {});
+        let node = patch[path.plane];
+        for (const key of path.keys.slice(0, -1)) {
+            if (!Object.hasOwn(node, key))
+                define(node, key, {});
+            node = node[key];
+        }
+        define(node, path.keys.at(-1), null);
+    }
+    return patch;
+}
+/** Render an ownership target as its scoped `read_state` path. */
+export function formatOwnedPath(scope, path) {
+    return [scope, path.plane, ...path.keys].join(".");
+}
+/** Top-level `working`/`lazy` keys that at least one current intent of `scope` owns. */
+export function ownedTopLevelKeys(scope, state) {
+    const owned = { working: new Set(), lazy: new Set() };
+    const intents = isObject(state.intents) ? state.intents : {};
+    for (const value of Object.values(intents))
+        for (const path of extractOwnedPaths(scope, value))
+            owned[path.plane].add(path.keys[0]);
+    return owned;
+}

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

@@ -84,24 +84,24 @@ export function stateFlowProtocol(bootstrap) {
     return `State Flow is enabled. It owns durable memory.
 
 ${bootstrapProtocol}STATE:
-- intents: chosen active commitments; detail may stay lazy; remove when fulfilled, abandoned, superseded, or impossible.
-- contract: durable requirements, decisions, rejections, interfaces, compiled knowledge.
-- working: facts, validation, failures, domain state, unresolved work, continuation.
+- intents: queue of chosen actions; work from them; remove when fulfilled, abandoned, superseded, or impossible.
+- contract: durable requirements, decisions, rejections, interfaces.
+- working: temporary context of intents: facts, validation, failures, domain state.
 - artifacts: source-path routing metadata; descriptions do not imply body acquisition.
-- response: previous answer; runtime stores the exact accepted answer at turn_end (empty=""). Ordinary assistant completion needs no finalization patch.
+- response: previous answer; runtime stores the exact accepted answer at turn_end (empty="").
 - lazy: retrieve explicitly.
 
 SCOPES: Use the narrowest scope: session=branch/run continuation by default; cwd=reusable project truth; global=established cross-project/user/environment knowledge.
 
-READ: Use read_state for concrete scope/retained-history gaps. lazy_navigation lists bounded effective lazy keys, not bodies. Unscoped=effective; effective/global/cwd/session select overlay or owner. Arrays use indices or [start..end]; keys gives structure, patch the intersected change. ${TASK_DRIVEN_HISTORY}
+READ: Use read_state for concrete scope/retained-history gaps. lazy_navigation lists bounded effective lazy keys, not bodies. ${TASK_DRIVEN_HISTORY}
 
-WRITE: patch_state is the sole model-authored semantic mutation mechanism; all supplied scopes are validated and durably accepted as one atomic transition. Call alone in an assistant response; await acceptance. Global/CWD use current canonical values after cancelable lock waiting. Correct repeats succeed without new revisions. ${PATCH_RESULT_PROTOCOL}
+WRITE: patch_state is the sole model-authored semantic mutation mechanism; all supplied scopes are validated and durably accepted as one atomic transition. Global/CWD use current canonical values after cancelable lock waiting. Correct repeats succeed without new revisions. ${PATCH_RESULT_PROTOCOL}
 
 PATCH: Use global/cwd/session object patches for material updates, not acknowledgments. Omit empty scopes. artifacts/contract/working/intents are objects; lazy is ordinary JSON. Omitted fields persist. Never patch runtime config/meta/response. Objects merge recursively; arrays/primitives replace. An object containing only canonical "[N]" keys recursively patches array elements. Indexed deletion is forbidden; nested object null deletes; materialized null is forbidden.
 
 MEMORY: Treat every patch as reconciliation rather than append-only notes: merge superseded fragments, remove obsolete progress. Preserve commitments, open questions, consequential results and exact continuation; distinguish requirements, decisions, observations, conclusions and hypotheses. Exclude secrets, raw history, transient progress, speculation and unsupported claims; retain decision-relevant uncertainty. Curate touched state; cleanup and scope reviews require an explicit user request. Proven moves use targeted read_state and one atomic multi-scope patch, then verify both owners. External transfers need verified acceptance before deletion. Never invent memory changes.
 
-REFS: State refs use {"$ref":"cwd.lazy.plan"} or \`$cwd.lazy.plan\` in text. Resolve only when needed; infer no authority, hydration, execution, or completion. Hint paths are current reference owners, not relocated targets or proof of staleness. Fix proven stale refs only as needed; never scan refs or history offsets.
+REFS: State refs use {"$ref":"cwd.lazy.plan"} or \`$cwd.lazy.plan\` in text. In an intent, $ref owns a same-scope working/lazy key; deleting the intent deletes keys no other intent refs (supersede in one patch). Text refs only use. Before deleting, save survivors unowned: results to working/contract/broader scope, abandonment reasons to contract. Unowned entries are fine. Resolve only when needed; infer no authority, hydration, execution, or completion. Hint paths are current reference owners, not relocated targets or proof of staleness. Fix proven stale refs only as needed; never scan refs or history offsets.
 
 ACQUISITION: Read only for a concrete gap, exact source/edit, invalidation, contradiction/failure, or explicit request; changed source fingerprints require rereading.
 ARTIFACTS: Compile acquired invalidated artifacts at artifacts[exact path] in the reported scope (global/cwd/session), with a description; never relocate or invent global copies. Runtime owns all artifact/Skill provenance.

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

@@ -67,7 +67,7 @@ function parseValuePath(path) {
             rest = rest.slice(index[0].length);
             continue;
         }
-        throw new Error("Invalid State Flow read path selector");
+        throw new Error("Invalid State Flow read path selector; object keys must match [A-Za-z_$][A-Za-z0-9_$-]* (ASCII), array selectors use [N] or [start..end]");
     }
     return { root, selectors };
 }

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

@@ -1,4 +1,4 @@
-import { type InactiveMode } from "./snapshot.ts";
+import { type InactiveMode, type StateFlowMode } from "./snapshot.ts";
 export declare const SNAPSHOT_ENTRY_TYPE = "state-flow-snapshot";
 interface BranchEntry {
     type?: unknown;
@@ -26,6 +26,8 @@ export interface PassiveStopBoundary {
     persistenceError?: string;
     /** The inactive mode selected by that failed change; legacy markers omit it. */
     mode?: InactiveMode;
+    /** Native-only Off choice; canonical runtime mode is deliberately not updated. */
+    memoryDeferred?: true;
 }
 export interface SnapshotDiscovery {
     candidates: unknown[];
@@ -33,6 +35,13 @@ export interface SnapshotDiscovery {
 }
 /** Enumerate active-branch snapshots newest-first while containing hostile entries. */
 export declare function discoverSnapshotData(branch: readonly BranchEntry[]): SnapshotDiscovery;
+/** Read native mode policy only; semantic checkpoint validity remains the recovery owner's concern. */
+export declare function findBranchPolicy(branch: readonly BranchEntry[], sessionId: string | undefined, stopEntryType: string | undefined, inactiveMode: InactiveMode): {
+    mode: StateFlowMode;
+    persistenceError?: string;
+} | undefined;
+/** Native policy bookkeeping retains an unacquired fork across extension reloads. */
+export declare function hasPendingFork(branch: readonly BranchEntry[], sessionId: string, entryType: string): boolean;
 export declare function snapshotDataNewestFirst(branch: readonly BranchEntry[]): unknown[];
 export declare function latestSnapshotData(branch: readonly BranchEntry[]): unknown;
 export declare function hasPriorConversation(branch: readonly BranchEntry[]): boolean;

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

@@ -1,4 +1,4 @@
-import { parseRetainedPiCheckpoint } from "./snapshot.js";
+import { parseRetainedPiCheckpoint, readCheckpointMode } from "./snapshot.js";
 export const SNAPSHOT_ENTRY_TYPE = "state-flow-snapshot";
 /** Enumerate active-branch snapshots newest-first while containing hostile entries. */
 export function discoverSnapshotData(branch) {
@@ -16,6 +16,65 @@ export function discoverSnapshotData(branch) {
     }
     return { candidates, errors };
 }
+/** Read native mode policy only; semantic checkpoint validity remains the recovery owner's concern. */
+export function findBranchPolicy(branch, sessionId, stopEntryType, inactiveMode) {
+    let stopReset = false;
+    for (let index = branch.length - 1; index >= 0; index--) {
+        try {
+            const entry = branch[index];
+            if (entry?.type !== "custom")
+                continue;
+            if (entry.customType === SNAPSHOT_ENTRY_TYPE) {
+                const mode = readCheckpointMode(entry.data, inactiveMode);
+                if (mode !== undefined)
+                    return { mode };
+                const data = entry.data;
+                if (data?.disabled === true && !Object.hasOwn(data, "mode") && !Object.hasOwn(data, "enabled"))
+                    return { mode: inactiveMode };
+            }
+            else if (stopEntryType !== undefined && entry.customType === stopEntryType) {
+                const data = entry.data;
+                if (!data || stopReset || (sessionId === undefined ? typeof data.owner !== "string" || !data.owner.trim() : data.owner !== sessionId))
+                    continue;
+                if (data.reset === true) {
+                    stopReset = true;
+                    continue;
+                }
+                if (Number.isSafeInteger(data.at) && data.at >= 0 && data.memoryDeferred === true && data.mode === "off") {
+                    return { mode: "off", ...(typeof data.persistenceError === "string" && data.persistenceError.trim() ? { persistenceError: data.persistenceError } : {}) };
+                }
+                if (Number.isSafeInteger(data.at) && data.at >= 0 && typeof data.persistenceError === "string" && data.persistenceError.trim()) {
+                    return { mode: data.mode === "off" || data.mode === "passive" ? data.mode : inactiveMode, persistenceError: data.persistenceError };
+                }
+            }
+        }
+        catch {
+            // Malformed native policy cannot prevent another explicit retained choice from being read.
+        }
+    }
+    return undefined;
+}
+/** Native policy bookkeeping retains an unacquired fork across extension reloads. */
+export function hasPendingFork(branch, sessionId, entryType) {
+    for (let index = branch.length - 1; index >= 0; index--) {
+        try {
+            const entry = branch[index];
+            if (entry?.type !== "custom" || entry.customType !== entryType)
+                continue;
+            const data = entry.data;
+            if (data?.owner !== sessionId)
+                continue;
+            if (data.reset === true)
+                return false;
+            if (data.forkPending === true)
+                return true;
+        }
+        catch {
+            // Unrelated native entries grant no fork authority.
+        }
+    }
+    return false;
+}
 export function snapshotDataNewestFirst(branch) {
     return discoverSnapshotData(branch).candidates;
 }

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

@@ -14,6 +14,12 @@ export declare function isStateFlowMode(value: unknown): value is StateFlowMode;
 export interface SnapshotConfig {
     mode: StateFlowMode;
 }
+/**
+ * Read only mode policy, without validating or accessing semantic checkpoint metadata.
+ * Missing/invalid policy stays undecided; callers must not treat this as restoration proof.
+ * Legacy `enabled:false` follows the caller's inactive policy.
+ */
+export declare function readCheckpointMode(value: unknown, inactiveMode?: InactiveMode): StateFlowMode | undefined;
 interface LegacyValidationFeedback {
     attempt: number;
     error: string;

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

@@ -15,10 +15,13 @@ export function isStateFlowMode(value) {
     return value === "active" || value === "passive" || value === "off";
 }
 /**
- * Read-only compatibility for session config and native checkpoints written before `mode`:
- * `enabled:true` stays active; `enabled:false` stays the caller's inactive policy.
+ * Read only mode policy, without validating or accessing semantic checkpoint metadata.
+ * Missing/invalid policy stays undecided; callers must not treat this as restoration proof.
+ * Legacy `enabled:false` follows the caller's inactive policy.
  */
-function decodeLegacyMode(value, inactiveMode) {
+export function readCheckpointMode(value, inactiveMode = "passive") {
+    if (!isObject(value))
+        return undefined;
     if (Object.hasOwn(value, "mode"))
         return Object.hasOwn(value, "enabled") || !isStateFlowMode(value.mode) ? undefined : value.mode;
     return typeof value.enabled === "boolean" ? value.enabled ? "active" : inactiveMode : undefined;
@@ -82,7 +85,7 @@ export function parseSessionRuntime(config, runtimeSource, cwd, sessionId) {
     let runtime;
     try {
         const settings = JSON.parse(config);
-        const mode = isObject(settings) && Object.keys(settings).length === 1 ? decodeLegacyMode(settings, "passive") : undefined;
+        const mode = isObject(settings) && Object.keys(settings).length === 1 ? readCheckpointMode(settings, "passive") : undefined;
         if (mode === undefined)
             throw new Error("Invalid State Flow runtime configuration or counters");
         runtime = { config: { mode }, meta: JSON.parse(runtimeSource) };
@@ -166,7 +169,7 @@ export function parseRetainedPiCheckpoint(value, inactiveMode = "passive") {
     if (keys.length === 1 && (value.mode === "passive" || value.mode === "off"))
         return { mode: value.mode };
     const allowed = new Set(["boundary", "mode", "enabled", "step", "bootstrap", "specification"]);
-    const mode = decodeLegacyMode(value, inactiveMode);
+    const mode = readCheckpointMode(value, inactiveMode);
     if (keys.some((key) => !allowed.has(key))
         || typeof value.boundary !== "string" || value.boundary.trim().length === 0
         || mode === undefined

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

@@ -32,4 +32,6 @@ export interface StatusDiagnostics {
 }
 export declare function formatScopeRevisionVector(revisions: ScopeRevisions): string;
 export declare function compactStatus(snapshot: Snapshot, _revisions: ScopeRevisions, colorize: Colorize): string | undefined;
+/** Operator-only footprint: serialized plane sizes and intent-owned share of top-level working/lazy entries. */
+export declare function scopeMemoryLines(states: ScopedStates): string[];
 export declare function detailedStatus(snapshot: Snapshot, diagnostics: StatusDiagnostics): string;