@llblab/pi-kit 0.16.0 → 0.17.0

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

@@ -23,3 +23,21 @@ export declare function projectDiagnosticContent(content: unknown): StateFlowDia
 /** Diagnostic JSONL lives beneath the active Pi agent directory, never inside the state repository. */
 export declare function stateFlowLogPath(agentDir: string): string;
 export declare function appendStateFlowDiagnostic(path: string, record: StateFlowDiagnosticRecord): void;
+export interface DiagnosticExtras {
+    content?: unknown;
+    input?: unknown;
+    tool?: string;
+    toolCallId?: string;
+    resolutionAttempt?: number;
+    terminalEligible?: boolean;
+}
+/** Own diagnostic path safety, projection, persistence, and one-shot failure reporting. */
+export declare class StateFlowDiagnosticWriter {
+    private warningReported;
+    private readonly enabled;
+    private readonly path;
+    private readonly repositoryRoot;
+    private readonly notify;
+    constructor(enabled: boolean, path: string, repositoryRoot: string, notify: (message: string) => void);
+    record(sessionId: string, cwd: string, error: string, category: StateFlowDiagnosticCategory, extras?: DiagnosticExtras): void;
+}

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

@@ -1,6 +1,6 @@
 // Domain: opt-in diagnostic capture for rejected State Flow resolutions.
 import { appendFileSync, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { isObject } from "./json.js";
 /** Preserve exact text blocks and block boundaries; reasoning bodies are never duplicated. */
 export function projectDiagnosticContent(content) {
@@ -22,3 +22,46 @@ export function appendStateFlowDiagnostic(path, record) {
     mkdirSync(dirname(path), { recursive: true });
     appendFileSync(path, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
 }
+/** Own diagnostic path safety, projection, persistence, and one-shot failure reporting. */
+export class StateFlowDiagnosticWriter {
+    warningReported = false;
+    enabled;
+    path;
+    repositoryRoot;
+    notify;
+    constructor(enabled, path, repositoryRoot, notify) {
+        this.enabled = enabled;
+        this.path = path;
+        this.repositoryRoot = repositoryRoot;
+        this.notify = notify;
+    }
+    record(sessionId, cwd, error, category, extras = {}) {
+        if (!this.enabled)
+            return;
+        try {
+            const fromRepository = relative(this.repositoryRoot, this.path);
+            if (fromRepository === "" || (!isAbsolute(fromRepository) && fromRepository !== ".." && !fromRepository.startsWith(`..${sep}`))) {
+                throw new Error("diagnostic path overlaps the State Flow repository");
+            }
+            appendStateFlowDiagnostic(this.path, {
+                at: new Date().toISOString(),
+                sessionId,
+                cwd: resolve(cwd),
+                category,
+                error,
+                ...(extras.content === undefined ? {} : { content: projectDiagnosticContent(extras.content) }),
+                ...(extras.input === undefined ? {} : { input: extras.input }),
+                ...(extras.tool === undefined ? {} : { tool: extras.tool }),
+                ...(extras.toolCallId === undefined ? {} : { toolCallId: extras.toolCallId }),
+                ...(extras.resolutionAttempt === undefined ? {} : { resolutionAttempt: extras.resolutionAttempt }),
+                ...(extras.terminalEligible === undefined ? {} : { terminalEligible: extras.terminalEligible }),
+            });
+        }
+        catch (failure) {
+            if (this.warningReported)
+                return;
+            this.warningReported = true;
+            this.notify(`State Flow could not write diagnostics: ${failure instanceof Error ? failure.message : String(failure)}`);
+        }
+    }
+}

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

@@ -1,5 +1,5 @@
 import { type DurableFileBase, type OwnedFileUpdate } from "./durable.ts";
-import type { StateScope } from "./state.ts";
+import { type StateScope } from "./state.ts";
 export interface LegacyStorageMigration {
     bases: DurableFileBase[];
     updates: OwnedFileUpdate[];
@@ -7,7 +7,7 @@ export interface LegacyStorageMigration {
 }
 /** Read-only activation eligibility, before global migration or any repository publication. */
 export declare function hasCwdMaterialization(cwd: string, repositoryRoot: string): boolean;
-/** Detect predecessor snapshots or temporal envelopes without mutating the store. */
+/** Detect predecessor snapshots, temporal envelopes, or pre-intents semantic states without mutating the store. */
 export declare function hasLegacyStateSources(cwd: string, sessionId: string, repositoryRoot: string, sessionKey?: string): boolean;
 /** Plan from current scope snapshots only; old explanatory journals are never replay input. */
 export declare function planLegacyStorageMigration(cwd: string, sessionId: string, repositoryRoot: string, _origin?: string, sessionKey?: string): LegacyStorageMigration;

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

@@ -3,6 +3,7 @@ import { lstatSync, readFileSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { captureOwnedFileBases, cwdScopePaths, parseScopeStream, serializeScopeMetadata, serializeScopeStream, sessionScopeKey, sessionScopePaths, } from "./durable.js";
 import { parseSessionRuntime, serializeSessionRuntime } from "./snapshot.js";
+import { migratePreIntentState } from "./state.js";
 /** Discover every owner-proven CWD and session cohort beneath the configured store. */
 function migrationDirectories(cwd, sessionId, root, sessionKey) {
     const selectedCwd = cwdScopePaths(cwd, root).directory;
@@ -48,13 +49,20 @@ function migrationDirectories(cwd, sessionId, root, sessionKey) {
             }
             const directory = join(cwdDirectory, entry.name);
             let meta;
+            let runtime;
             try {
                 meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8"));
             }
             catch {
                 continue;
             }
-            const identity = meta && typeof meta === "object" && !Array.isArray(meta) ? meta.identity : undefined;
+            try {
+                runtime = JSON.parse(readFileSync(join(directory, "runtime.json"), "utf8"));
+            }
+            catch { /* predecessor sessions keep identity in meta.json */ }
+            const identity = meta && typeof meta === "object" && !Array.isArray(meta) && meta.identity !== undefined
+                ? meta.identity
+                : runtime && typeof runtime === "object" && !Array.isArray(runtime) ? runtime.identity : undefined;
             if (!identity || typeof identity !== "object" || Array.isArray(identity))
                 continue;
             const owner = identity;
@@ -81,13 +89,23 @@ export function hasCwdMaterialization(cwd, repositoryRoot) {
         throw new Error(`State Flow tail has no provable checkpoint: ${directory}`);
     return false;
 }
-/** Detect predecessor snapshots or temporal envelopes without mutating the store. */
+function checkpointNeedsIntentMigration(source) {
+    const checkpoint = JSON.parse(source);
+    if (migratePreIntentState(checkpoint) !== undefined)
+        return true;
+    return checkpoint !== null && typeof checkpoint === "object" && !Array.isArray(checkpoint)
+        && migratePreIntentState(checkpoint.state) !== undefined;
+}
+/** Detect predecessor snapshots, temporal envelopes, or pre-intents semantic states without mutating the store. */
 export function hasLegacyStateSources(cwd, sessionId, repositoryRoot, sessionKey = sessionId) {
     const root = resolve(repositoryRoot);
     return migrationDirectories(cwd, sessionId, root, sessionKey).some(({ directory, scope }) => {
-        if (lstatSync(join(directory, "checkpoint.json"), { throwIfNoEntry: false }) === undefined)
+        const checkpointPath = join(directory, "checkpoint.json");
+        if (lstatSync(checkpointPath, { throwIfNoEntry: false }) === undefined)
             return false;
         try {
+            if (checkpointNeedsIntentMigration(readFileSync(checkpointPath, "utf8")))
+                return true;
             const meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8"));
             if (meta === null || typeof meta !== "object" || !("temporal" in meta))
                 return true;

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

@@ -1,5 +1,12 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 export type { StateDocument } from "./state.ts";
+/** Keep successful patch JSON valid while separating adjacent scopes and memory sections visually. */
+export declare function formatPatchStateArguments(args: unknown): string;
+/** Normalize a bounded compatibility superset without advertising aliases in the model-facing contract. */
+export declare function normalizePatchStateArguments(args: unknown): any;
+/** Keep visible tool output separated from its heading without changing semantics. */
+export declare function separatedOutput(text: string): string;
+export declare function separatedFailure(error: unknown): Error;
 /** The compact model-facing contract. Semantic writes never travel through terminal prose. */
 export declare function stateFlowProtocol(bootstrap: boolean): string;
 export declare function assistantToolCallCount(content: unknown): number;

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

@@ -1,3 +1,50 @@
+import { isObject } from "./json.js";
+const PATCH_DISPLAY_SECTION_KEYS = new Set(["global", "cwd", "session", "artifacts", "contract", "working", "response", "final"]);
+/** Keep successful patch JSON valid while separating adjacent scopes and memory sections visually. */
+export function formatPatchStateArguments(args) {
+    const seenAtIndent = new Set();
+    return JSON.stringify(args, null, 2).split("\n").flatMap((line) => {
+        const indent = line.length - line.trimStart().length;
+        const match = /^(\s+)"([^"]+)":/.exec(line);
+        if (match === null || !PATCH_DISPLAY_SECTION_KEYS.has(match[2])) {
+            for (const seenIndent of seenAtIndent)
+                if (seenIndent > indent)
+                    seenAtIndent.delete(seenIndent);
+            return [line];
+        }
+        const separator = seenAtIndent.has(indent) ? [""] : [];
+        seenAtIndent.add(indent);
+        return [...separator, line];
+    }).join("\n");
+}
+/** Normalize a bounded compatibility superset without advertising aliases in the model-facing contract. */
+export function normalizePatchStateArguments(args) {
+    if (!isObject(args) || !Object.hasOwn(args, "final"))
+        return args;
+    const value = args.final;
+    let final;
+    if (typeof value === "boolean")
+        final = value;
+    else if (value === 1)
+        final = true;
+    else if (value === 0)
+        final = false;
+    else if (typeof value === "string" && value.trim().toLowerCase() === "true")
+        final = true;
+    else if (typeof value === "string" && value.trim().toLowerCase() === "false")
+        final = false;
+    else
+        return args;
+    return { ...args, final };
+}
+/** Keep visible tool output separated from its heading without changing semantics. */
+export function separatedOutput(text) {
+    return `\n${text.replace(/^\n+/, "")}`;
+}
+export function separatedFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return new Error(separatedOutput(message), error instanceof Error ? { cause: error } : undefined);
+}
 function baselineMemoryProtocol() {
     return "MEMORY: State Flow owns durable memory while enabled. Put established cross-project/user/environment knowledge in global, reusable project truth in cwd, and branch/run continuation in session. Treat every patch as reconciliation rather than append-only notes: use the narrowest scope; merge superseded fragments; remove obsolete progress. Exclude secrets, raw history, transient progress, speculation, and unsupported claims; retain uncertainty only when decision-relevant.";
 }
@@ -8,25 +55,28 @@ export function stateFlowProtocol(bootstrap) {
         : "";
     return `State Flow is enabled.
 ${bootstrapProtocol}
-STATE: {"artifacts":{},"contract":{},"working":{},"response":"latest complete answer"}
+STATE: {"artifacts":{},"contract":{},"working":{},"intents":{},"response":"latest complete answer"}
 - artifacts: source-path routing metadata; descriptions do not imply body acquisition.
 - contract: durable requirements, decisions, rejections, interfaces, compiled knowledge.
 - working: facts, validation, failures, domain state, unresolved work, continuation.
+- intents: active commitments; remove when fulfilled, abandoned, superseded, or impossible.
 - response: previous complete answer; runtime-owned.
 
-READ: Use read_state only for a concrete historical/scope gap. lazy_navigation gives the effective lazy root and bounded key kinds, never bodies or a partial catalog. Unscoped paths alias effective; effective/global/cwd/session select overlay or owner. Paths read cached values; arrays support zero-based indices and half-open [start..end]. keys returns minimal structure; patch returns the path-intersected change.
+READ: Use read_state for concrete scope/history gaps. lazy_navigation exposes the effective lazy root's bounded key kinds, not bodies. Unscoped paths alias effective; effective/global/cwd/session select overlay or owner. Arrays support indices and [start..end]; keys gives structure and patch the intersected change.
 
 WRITE: patch_state is the sole model-authored semantic mutation mechanism. Supply global/cwd/session patches in any combination; all supplied scopes are validated and durably accepted as one atomic transition. Call it alone in an assistant response, then continue only after its acknowledgement.
 
-FINAL: Every enabled iteration starts terminal-ineligible. A successful patch_state with final:true permits a later turn_end but does not stop reasoning, tools, or later patches. Use {"final":true} if state needs no change. Without eligibility, runtime preserves the terminal answer and starts at most two fallback turns solely for a final:true patch; never restate or replace that answer. Exhaustion closes with the preserved answer/current state. A final-only call creates no semantic transition. Never patch response; runtime records the delivered answer.
+FINAL: Every enabled iteration starts terminal-ineligible. Successful patch_state final:true permits a later turn_end without stopping later work; use {"final":true} when no state change is needed. Otherwise runtime preserves the answer and allows at most two fallback turns only for final:true; never restate it. A final-only call creates no transition. Runtime owns response.
+
+INTENTS: Keep chosen actions; detail may stay lazy. State refs use {"$ref":"cwd.lazy.plan"} or \`$cwd.lazy.plan\` in text. Resolve only when needed; infer no authority, hydration, execution, or completion. If that resolution proves a dangling state ref, fix/drop it in owning text; never scan for broken refs.
 
 SCOPES: global=cross-project; cwd=project and Skills; session=branch/run. Deleting an override may reveal its parent.
 
 ${baselineMemoryProtocol()}
 
-PATCH: Optional global/cwd/session object patches plus optional final:true; require at least one. Omit empty/materially no-op scopes. Semantic fields are object-valued artifacts/contract/working and ordinary-JSON lazy; 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.
+PATCH: Optional global/cwd/session object patches plus optional final:true; require at least one. Omit empty/materially no-op scopes. Semantic fields are object-valued artifacts/contract/working/intents and ordinary-JSON lazy; 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.
 
-HANDOFF: Preserve active commitments, unresolved questions, consequential results, and exact continuation. Distinguish requirements, decisions, observations, conclusions, and hypotheses. Before final handoff curate touched and obviously stale/mis-scoped state. On feature/release/campaign or project/version completion, do one bounded reconciliation: remove obsolete work, retain operative consequences, and use targeted read_state plus destination-verify-source-delete for ownership moves. Never invent memory changes or restyle unrelated state.
+HANDOFF: Preserve active commitments, open questions, consequential results, and exact continuation; distinguish requirements, decisions, observations, conclusions, and hypotheses. Curate touched and obviously stale/mis-scoped state. At feature/release/campaign or project/version completion, reconcile once: remove obsolete work, retain consequences, and use targeted read_state plus destination-verify-source-delete for moves. Never invent memory changes.
 
 ACQUISITION: Start materialized. Read only for a compilation gap, exact source/edit, invalidation, contradiction/failure, or explicit request; changed hashes require rereading.
 ARTIFACTS: For each acquired new/invalidated ordinary artifact, patch global.artifacts[exact path] with a compact non-empty description. Runtime owns provenance.

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

@@ -67,3 +67,20 @@ export interface PublicationWorkerResult {
 }
 /** Execute one immutable target attempt; persistence/CAS remains the caller's responsibility. */
 export declare function runPublicationWorker(state: PublicationQueueState, push: PublicationPush, current: () => PublicationQueueState, isAncestor: CommitAncestor): Promise<PublicationWorkerResult>;
+export interface PublicationWorkerControllerPorts {
+    resolveDestination(): RemotePublicationDestination | undefined;
+    isAncestor(ancestor: string, descendant: string): boolean;
+    push(destination: RemotePublicationDestination, target: string, signal: AbortSignal): Promise<void>;
+    onDiverged(previous: PublicationQueueState, target: string): void;
+}
+/** Own durable queue coalescing, worker leases, retries, generation fencing, and bounded shutdown. */
+export declare class PublicationWorkerController {
+    private readonly active;
+    private readonly ports;
+    private stopped;
+    private shutdownPromise;
+    constructor(ports: PublicationWorkerControllerPorts);
+    enqueue(target: string): void;
+    launch(): void;
+    shutdown(waitMs: number): Promise<boolean>;
+}

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

@@ -333,3 +333,105 @@ export async function runPublicationWorker(state, push, current, isAncestor) {
         };
     }
 }
+/** Own durable queue coalescing, worker leases, retries, generation fencing, and bounded shutdown. */
+export class PublicationWorkerController {
+    active = new Map();
+    ports;
+    stopped = false;
+    shutdownPromise;
+    constructor(ports) {
+        this.ports = ports;
+    }
+    enqueue(target) {
+        const destination = this.ports.resolveDestination();
+        if (!destination)
+            return;
+        const path = publicationQueuePath(destination);
+        const previous = loadPublicationQueue(path);
+        const next = previous
+            ? coalescePublicationTarget(previous, destination, target, this.ports.isAncestor, {
+                onDivergedLineage: (dropped) => this.ports.onDiverged(dropped, target),
+            })
+            : createPublicationQueue(destination, target);
+        savePublicationQueue(path, next, previous);
+    }
+    launch() {
+        if (this.stopped)
+            return;
+        let destination;
+        try {
+            destination = this.ports.resolveDestination();
+        }
+        catch (error) {
+            if (error instanceof Error && /ENOENT/.test(error.message))
+                return;
+            throw error;
+        }
+        if (!destination)
+            return;
+        const path = publicationQueuePath(destination);
+        if (this.active.has(path))
+            return;
+        let queued;
+        let lease;
+        try {
+            queued = loadPublicationQueue(path);
+            if (!queued)
+                return;
+            lease = acquirePublicationWorkerLease(path);
+        }
+        catch {
+            return;
+        }
+        if (!lease)
+            return;
+        const controller = new AbortController();
+        const done = runPublicationWorker(queued, ({ target }) => this.ports.push(destination, target, controller.signal), () => loadPublicationQueue(path) ?? queued, this.ports.isAncestor).then((result) => {
+            if (this.stopped)
+                return;
+            const current = loadPublicationQueue(path);
+            if (!current)
+                return;
+            if (result.next === undefined) {
+                if (current.target === result.attempted.target)
+                    removePublicationQueue(path, current);
+                return;
+            }
+            if (current.target === result.attempted.target || result.next.target === current.target)
+                savePublicationQueue(path, result.next, current);
+        }).catch(() => {
+            // Queue/CAS truth remains durable; status and a later activation expose retry.
+        }).finally(() => {
+            this.active.delete(path);
+            try {
+                lease.release();
+                if (!this.stopped && loadPublicationQueue(path)?.status === "pending")
+                    this.launch();
+            }
+            catch {
+                // Failed lease cleanup or malformed persistence stays inert until retry or repair.
+            }
+        });
+        this.active.set(path, { controller, done });
+    }
+    shutdown(waitMs) {
+        this.stopped = true;
+        return this.shutdownPromise ??= (async () => {
+            const workers = [...this.active.values()];
+            for (const { controller } of workers)
+                controller.abort();
+            if (workers.length === 0)
+                return true;
+            let timeout;
+            try {
+                return await Promise.race([
+                    Promise.all(workers.map(({ done }) => done)).then(() => true),
+                    new Promise((resolve) => { timeout = setTimeout(() => resolve(false), waitMs); }),
+                ]);
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        })();
+    }
+}

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

@@ -37,17 +37,33 @@ type StateReadMeta = {
     type: "number" | "boolean";
 };
 type StateReadKeys = Record<string, string> | [];
+export interface StateReadHint {
+    type: "dangling-reference";
+    message: string;
+    paths: string[];
+}
 export type ProjectedStateRead = {
     value: JsonValue | JsonValue[];
+    hint?: StateReadHint[];
 } | {
     meta: StateReadMeta | StateReadMeta[];
     keys: StateReadKeys | StateReadKeys[];
 } | {
     patch: JsonValue | JsonValue[];
 };
+export interface StateReferenceSource {
+    scope: StateScope;
+    path: string;
+    form: "structured" | "text";
+}
 /** Resolve a projection root without repeating the tool name in every path. */
 export declare function parseStateReadPath(path: string): StateReadQuery;
 export declare function readStatePath(view: TemporalState, path: string): StateReadResult;
+/** Reactively locate exact durable sources for one failed state-path resolution. */
+export declare function findStateReferenceSources(view: TemporalState, path: string): {
+    sources: StateReferenceSource[];
+    truncated: boolean;
+};
 /** Project exact current/historical state paths without exposing temporal metadata. */
 export declare function readProjectedState(view: TemporalState, paths: readonly string[], projection?: StateReadProjection): ProjectedStateRead;
 export {};

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

@@ -1,6 +1,8 @@
 import { isObject, sameJson } from "./json.js";
 import { projectStateForModel } from "./state.js";
 import { readTemporalState } from "./temporal.js";
+const MAX_REFERENCE_SOURCES = 3;
+const MAX_REFERENCE_SCAN_NODES = 10_000;
 const PATH_PATTERN = /^(effective|global|cwd|session)(?:\[(\d+)\])?(?:\.patches(?:\[(\d+)\])?)?$/;
 /** Resolve a projection root without repeating the tool name in every path. */
 export function parseStateReadPath(path) {
@@ -35,7 +37,7 @@ export function readStatePath(view, path) {
 }
 function parseValuePath(path) {
     const explicitRoot = /^(?:effective|global|cwd|session)(?:\[\d+\])?(?=\.|$)/.exec(path)?.[0];
-    const implicitRoot = /^(?:artifacts|contract|working|response|lazy)(?=\.|\[|$)/.exec(path)?.[0];
+    const implicitRoot = /^(?:artifacts|contract|working|intents|response|lazy)(?=\.|\[|$)/.exec(path)?.[0];
     if (explicitRoot === undefined && implicitRoot === undefined) {
         throw new Error("State Flow read path requires a semantic path or an effective, global, cwd, or session root");
     }
@@ -95,6 +97,80 @@ function valueKind(value) {
         return "object";
     return typeof value;
 }
+function referenceCandidates(path) {
+    if (/^(?:artifacts|contract|working|intents|response|lazy)(?=\.|\[|$)/.test(path))
+        return [path, `effective.${path}`];
+    return [path];
+}
+function inlineReferencePattern(path) {
+    const escaped = path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(?:^|[^A-Za-z0-9_$.[\\]:-])\\$${escaped}(?=$|[^A-Za-z0-9_$.[\\]:-])`, "u");
+}
+/** Reactively locate exact durable sources for one failed state-path resolution. */
+export function findStateReferenceSources(view, path) {
+    const candidates = referenceCandidates(path);
+    const patterns = candidates.map(inlineReferencePattern);
+    const sources = [];
+    let visited = 0;
+    let truncated = false;
+    const visit = (value, owner, ownerPath) => {
+        if (sources.length >= MAX_REFERENCE_SOURCES || visited >= MAX_REFERENCE_SCAN_NODES) {
+            truncated = true;
+            return;
+        }
+        visited += 1;
+        if (typeof value === "string") {
+            if (patterns.some((pattern) => pattern.test(value)))
+                sources.push({ scope: owner, path: ownerPath, form: "text" });
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (let index = 0; index < value.length && !truncated; index++)
+                visit(value[index], owner, `${ownerPath}[${index}]`);
+            return;
+        }
+        if (!isObject(value))
+            return;
+        if (typeof value.$ref === "string" && candidates.includes(value.$ref)) {
+            sources.push({ scope: owner, path: ownerPath, form: "structured" });
+            if (sources.length >= MAX_REFERENCE_SOURCES) {
+                truncated = true;
+                return;
+            }
+        }
+        for (const key of Object.keys(value).sort()) {
+            if (key === "response" || (key === "$ref" && typeof value[key] === "string"))
+                continue;
+            visit(value[key], owner, ownerPath ? `${ownerPath}.${key}` : `${owner}.${key}`);
+            if (truncated)
+                return;
+        }
+    };
+    for (const scope of ["global", "cwd", "session"]) {
+        const state = readTemporalState(view, 0, scope);
+        for (const plane of ["artifacts", "contract", "working", "intents", "lazy"]) {
+            const value = state[plane];
+            if (value !== undefined)
+                visit(value, scope, `${scope}.${plane}`);
+            if (truncated)
+                break;
+        }
+        if (truncated)
+            break;
+    }
+    sources.sort((left, right) => (left.form === right.form ? left.path.localeCompare(right.path) : left.form === "structured" ? -1 : 1));
+    return { sources, truncated };
+}
+function missingReferenceHint(view, path) {
+    const { sources, truncated } = findStateReferenceSources(view, path);
+    if (sources.length === 0)
+        return undefined;
+    return [{
+            type: "dangling-reference",
+            message: `Reconcile the verified current values that reference this path${truncated ? "; additional sources may exist beyond the bounded scan" : ""}.`,
+            paths: sources.map(({ path: sourcePath }) => sourcePath),
+        }];
+}
 function projectValue(value, projection) {
     if (projection === "value")
         return { value: structuredClone(value) };
@@ -184,17 +260,27 @@ export function readProjectedState(view, paths, projection = "value") {
         return { patch: patches.length === 1 ? patches[0] : patches };
     }
     const projected = paths.map((path) => {
-        const { root, selectors } = parseValuePath(path);
-        const query = parseStateReadPath(root);
-        if (query.kind !== "state")
-            throw new Error("Value and keys projections require a state path");
-        const readsLazy = selectors[0]?.kind === "key" && selectors[0].key === "lazy";
-        const state = readsLazy
-            ? readTemporalState(view, query.offset, query.scope)
-            : projectStateForModel(readTemporalState(view, query.offset, query.scope));
-        if (readsLazy && !Object.hasOwn(state, "lazy"))
-            state.lazy = {};
-        return projectValue(selectValue(state, selectors, path), projection);
+        try {
+            const { root, selectors } = parseValuePath(path);
+            const query = parseStateReadPath(root);
+            if (query.kind !== "state")
+                throw new Error("Value and keys projections require a state path");
+            const readsLazy = selectors[0]?.kind === "key" && selectors[0].key === "lazy";
+            const state = readsLazy
+                ? readTemporalState(view, query.offset, query.scope)
+                : projectStateForModel(readTemporalState(view, query.offset, query.scope));
+            if (readsLazy && !Object.hasOwn(state, "lazy"))
+                state.lazy = {};
+            return projectValue(selectValue(state, selectors, path), projection);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const missing = /does not exist| is outside /.test(message);
+            const hint = missing && projection === "value" && paths.length === 1 ? missingReferenceHint(view, path) : undefined;
+            if (hint)
+                return { value: null, hint };
+            throw new Error(message, error instanceof Error ? { cause: error } : undefined);
+        }
     });
     if (projected.length === 1)
         return projected[0];

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

@@ -7,6 +7,20 @@ interface BranchEntry {
         role?: unknown;
     };
 }
+export interface SessionEntryLookup {
+    getLeafEntry(): (BranchEntry & {
+        id?: string;
+        parentId?: string | null;
+    }) | undefined;
+    getEntry(id: string): (BranchEntry & {
+        id?: string;
+        parentId?: string | null;
+    }) | undefined;
+}
+export interface PassiveStopBoundary {
+    at: number;
+    from?: number;
+}
 export interface SnapshotDiscovery {
     candidates: unknown[];
     errors: string[];
@@ -18,4 +32,7 @@ export declare function latestSnapshotData(branch: readonly BranchEntry[]): unkn
 export declare function hasPriorConversation(branch: readonly BranchEntry[]): boolean;
 /** Auto-start eligibility is session identity/lifecycle, not the presence of CWD materialization. */
 export declare function isNewSession(reason: unknown, branch: readonly BranchEntry[]): boolean;
+export declare function findAssistantToolBatch(session: SessionEntryLookup, toolCallId: string): string[] | undefined;
+export declare function findPassiveStopBoundary(branch: readonly BranchEntry[], sessionId: string, entryType: string): PassiveStopBoundary | undefined;
+export declare function retainsPhysicalSessionProjection(reason: unknown): boolean;
 export {};

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

@@ -42,3 +42,41 @@ export function isNewSession(reason, branch) {
         return true;
     return reason === "startup" && !hasPriorConversation(branch);
 }
+export function findAssistantToolBatch(session, toolCallId) {
+    for (let cursor = session.getLeafEntry(); cursor; cursor = cursor.parentId ? session.getEntry(cursor.parentId) : undefined) {
+        if (cursor.type !== "message" || cursor.message?.role !== "assistant" || !Array.isArray(cursor.message.content))
+            continue;
+        const calls = cursor.message.content.filter((block) => {
+            return typeof block === "object" && block !== null
+                && block.type === "toolCall"
+                && typeof block.id === "string"
+                && typeof block.name === "string";
+        });
+        if (calls.some(({ id }) => id === toolCallId))
+            return calls.map(({ name }) => name);
+    }
+    return undefined;
+}
+export function findPassiveStopBoundary(branch, sessionId, entryType) {
+    for (const entry of [...branch].reverse()) {
+        try {
+            if (entry?.type !== "custom" || entry.customType !== entryType)
+                continue;
+            const { at, from, reset, owner } = entry.data ?? {};
+            if (reset === true && owner === sessionId)
+                return undefined;
+            if (typeof at === "number" && Number.isSafeInteger(at) && at >= 0)
+                return {
+                    at,
+                    ...(typeof from === "number" && Number.isSafeInteger(from) && from >= 0 ? { from } : {}),
+                };
+        }
+        catch {
+            // A hostile unrelated branch entry cannot manufacture or suppress a valid marker.
+        }
+    }
+    return undefined;
+}
+export function retainsPhysicalSessionProjection(reason) {
+    return reason === undefined || reason === "startup" || reason === "reload" || reason === "resume";
+}