@llblab/pi-kit 0.14.1 → 0.16.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.16.0 - 2026-09-17
+
+- `Canonical Knowledge Memory`: Advances the exact State Flow pin to `0.14.0`, making Global Lazy the sole canonical Knowledge store and removing the former Markdown Knowledge layer while preserving scoped semantic compilation and recovery.
+- `Telegram Fresh Sessions`: Advances the exact Telegram pin to `0.49.0`, adding lifecycle-safe `/new` session replacement with durable update settlement, same-chat or same-Thread continuity, and terminal result notifications.
+- `Package Cohort`: Confirms every other bundled package already matches its latest published npm version; the package set, resource inventory, and explicit load order remain unchanged.
+
+## 0.15.0 - 2026-09-16
+
+- `Business Credit Usage`: Advances the exact Codex Usage pin to `0.10.0`, adding Business-account credit usage with normalized display, precise reset countdown updates, and cache reuse.
+- `State Flow Recovery Delivery`: Advances the exact Telegram pin to `0.48.3`, suppressing duplicate preserved-answer recovery only when matching intermediate text was admitted in the same Telegram turn while preserving equal answers in later turns. Thread restore and reclaim also use the current Workspace display title.
+
 ## 0.14.1 - 2026-09-16
 
 - `State Flow Telegram Discovery Hotfix`: Advances the exact State Flow pin to `0.13.3`, restoring its Telegram main-menu control when Pi loads the compiled sibling extension layout while retaining package-export discovery and optional fail-open behavior. The package set and explicit load order remain unchanged.

package/README.md

@@ -12,10 +12,10 @@ Package links lead to the owning repositories for usage, documentation, issues,
 | --- | ---: | --- |
 | [`@llblab/pi-actors`](https://github.com/llblab/pi-actors) | `0.53.0` | Inspectable local Runs, reusable Recipes, persistent tools, and delegation Skills |
 | [`@llblab/pi-clean-room`](https://github.com/llblab/pi-clean-room) | `0.1.1` | Isolated nested Pi TUI with explicitly selected extensions |
-| [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.9.4` | Compact Codex/Spark subscription-limit status |
+| [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.10.0` | Compact Codex/Spark subscription-limit and Business credit-usage status |
 | [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.8.1` | Visible continuation scheduling and bounded worker Skills |
-| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.13.3` | Incremental scoped state, context, and memory with semantic storage, compiled runtime delivery, safe compaction, exact publication, and reliable Telegram section discovery |
-| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.48.2` | Telegram companion with built runtime delivery, resilient follower promotion, truthful terminal queue counts, adaptive Thread display, exact queues, files, voice, controls, and Generative Apps guidance |
+| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.14.0` | Incremental scoped state/context/memory compiler with Global Lazy as the canonical Knowledge store, compiled runtime delivery, safe compaction, and exact publication |
+| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.49.0` | Telegram companion with native fresh-session replacement, adaptive Thread continuity, exact queues, files, voice, controls, and Generative Apps guidance |
 | [`@llblab/skills`](https://github.com/llblab/skills) | `1.15.0` | Portable workflows for engineering, review, design, context maintenance, and other focused tasks |
 
 Versions are exact by design. An upstream release does not change an installed kit until this repository explicitly advances the dependency and publishes a new kit version. Runtime defects and package-specific feature requests belong in the linked repository; package selection and kit installation issues belong here.

package/node_modules/@llblab/pi-codex-usage/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.10.0: Business Credit Usage
+
+- Added Business-account credit usage support for responses that do not expose Codex rate-limit windows. Impact: the statusline now shows rounded remaining credit percentage and an optional reset countdown while preserving existing rate-limit displays when both forms are available.
+- Scheduled credit reset countdown redraws at their exact display boundaries and retained credits-only reports in the active cache. Impact: credit status remains locally responsive between API refreshes without displacing model-specific quota windows.
+
 ## 0.9.4: Responsive Quota Polling
 
 - Increased the automatic Codex quota refresh interval from 30 to 60 seconds. Impact: status values remain responsive down to the locally rendered seconds countdown while reducing repeated OpenAI requests, especially when several Pi instances are open.

package/node_modules/@llblab/pi-codex-usage/README.md

@@ -68,6 +68,12 @@ Before the first usable report for the active quota bucket arrives, two half-hei
 
 When the weekly reset time is available, it follows either the single-window percentage or the dual-window bar. More than a day remains is shown in 144-minute day-tenth steps such as `7d`, `6.9d`, `6.6d`, `5.1d`, `5d`, `3.7d`, `3d`, `2d`, `1.9d`, `1.5d`, and `1.1d`, rounded upward to the next tenth. At 24 hours and below it switches to upward-rounded 6-minute hour-tenth steps such as `24h`, `23.7h`, `20.1h`, `20h`, `19.9h`, `1.4h`, `1.3h`, `1.2h`, `1.1h`, and `1h`. Under an hour it switches to floored minutes, and under a minute to seconds. After the reset timestamp passes, `0s` is held until the next successful quota refresh reports the new weekly window.
 
+Business accounts that return credits instead of Codex rate-limit windows show the rounded remaining percentage. When the response includes a credit reset cycle, its countdown is shown after the percentage:
+
+```text
+codex 81% 2.8d
+```
+
 When the 5-hour window is exhausted and exposes its own reset time, the statusline adds the 5-hour reset before the weekly reset:
 
 ```text

package/node_modules/@llblab/pi-codex-usage/index.ts

@@ -90,6 +90,12 @@ export type UsageQueryError = {
 
 export type CodexUsageReport = {
   snapshots: NormalizedRateLimitSnapshot[];
+  credits?: NormalizedCreditUsage;
+};
+
+export type NormalizedCreditUsage = {
+  remainingPercent: number;
+  resetAt?: number;
 };
 
 export type NormalizedRateLimitSnapshot = {
@@ -106,6 +112,8 @@ export type NormalizedRateLimitWindow = {
 type RateLimitStatusPayload = {
   rate_limit?: unknown;
   additional_rate_limits?: unknown;
+  credits?: unknown;
+  spend_control?: unknown;
 };
 
 type BackendAdditionalRateLimit = {
@@ -593,7 +601,10 @@ async function queryUsage(
         source === "pi-auth"
           ? await queryViaPiAuth(ctx, options.timeoutMs)
           : await queryViaCodexAppServer(options.timeoutMs);
-      if (selectUsageSnapshot(report, activeUsageLimitId(model))) {
+      if (
+        selectUsageSnapshot(report, activeUsageLimitId(model)) ||
+        report.credits
+      ) {
         return { ok: true, report };
       }
       errors.push({
@@ -920,12 +931,56 @@ export function normalizeBackendPayload(
     }
   }
 
-  if (snapshots.length === 0) {
+  const credits = normalizeBackendCredits(payload, _capturedAt);
+  if (snapshots.length === 0 && !credits) {
     throw new Error(
-      "Codex usage endpoint returned no displayable rate-limit windows.",
+      "Codex usage endpoint returned no displayable rate-limit windows or credits.",
     );
   }
-  return { snapshots };
+  return credits ? { snapshots, credits } : { snapshots };
+}
+
+function normalizeBackendCredits(
+  payload: RateLimitStatusPayload,
+  capturedAt: number,
+): NormalizedCreditUsage | undefined {
+  const spendControl = payload.spend_control as
+    | Record<string, unknown>
+    | undefined;
+  const individualLimit = spendControl?.individual_limit as
+    | Record<string, unknown>
+    | undefined;
+  const credits = payload.credits as Record<string, unknown> | undefined;
+  const limit = asNumber(individualLimit?.limit);
+  const used = asNumber(individualLimit?.used);
+  const remaining = asNumber(individualLimit?.remaining);
+  const resetAt = asResetTime(
+    [
+      individualLimit?.reset_at,
+      individualLimit?.resets_at,
+      individualLimit?.reset_time,
+      spendControl?.reset_at,
+      spendControl?.resets_at,
+      credits?.reset_at,
+      credits?.resets_at,
+    ],
+    individualLimit?.reset_after_seconds ?? spendControl?.reset_after_seconds,
+    capturedAt,
+  );
+  if (
+    limit === undefined ||
+    used === undefined ||
+    remaining === undefined ||
+    limit <= 0
+  )
+    return undefined;
+  const remainingPercent = Math.min(
+    100,
+    Math.max(0, (remaining / limit) * 100),
+  );
+  return resetAt === undefined
+    ? { remainingPercent }
+    : { remainingPercent, resetAt };
 }
 
 function backendAdditionalLimitId(limit: BackendAdditionalRateLimit): string {
@@ -1103,7 +1158,9 @@ export function formatCodexUsageStatusValue(
   const model = typeof modelOrNow === "number" ? undefined : modelOrNow;
   const capturedNow = typeof modelOrNow === "number" ? modelOrNow : now;
   const snapshot = selectActiveUsageSnapshot(report, model);
-  if (!snapshot || (!snapshot.primary && !snapshot.secondary)) return undefined;
+  if (!snapshot || (!snapshot.primary && !snapshot.secondary)) {
+    return formatCreditUsage(report.credits, capturedNow);
+  }
   if (!snapshot.primary || !snapshot.secondary) {
     const window = snapshot.primary ?? snapshot.secondary;
     if (!window) return undefined;
@@ -1130,6 +1187,17 @@ export function formatCodexUsageStatusValue(
   return countdown ? `${bar} ${countdown}` : bar;
 }
 
+function formatCreditUsage(
+  credits: NormalizedCreditUsage | undefined,
+  now: number,
+): string | undefined {
+  if (!credits) return undefined;
+  const percentage = `${Math.round(credits.remainingPercent)}%`;
+  return credits.resetAt
+    ? `${percentage} ${formatResetCountdown(credits.resetAt, now)}`
+    : percentage;
+}
+
 export function formatWeeklyResetCountdown(
   report: CodexUsageReport,
   modelOrNow?: CodexUsageModel | number,
@@ -1167,7 +1235,10 @@ export function nextResetCountdownDelayMs(
   model?: CodexUsageModel,
 ): number | undefined {
   const snapshot = selectActiveUsageSnapshot(report, model);
-  const resetTimes = [weeklyWindow(snapshot)?.resetAt];
+  const hasRateLimitWindow = Boolean(snapshot?.primary || snapshot?.secondary);
+  const resetTimes = [
+    hasRateLimitWindow ? weeklyWindow(snapshot)?.resetAt : report.credits?.resetAt,
+  ];
   if (snapshot?.secondary && isQuotaWindowExhausted(snapshot.primary)) {
     resetTimes.push(snapshot.primary?.resetAt);
   }
@@ -1391,7 +1462,10 @@ export function canReuseCachedReport(
   report: CodexUsageReport,
   model: CodexUsageModel | undefined,
 ): boolean {
-  return selectActiveUsageSnapshot(report, model) !== undefined;
+  return (
+    selectActiveUsageSnapshot(report, model) !== undefined ||
+    report.credits !== undefined
+  );
 }
 
 export function isFullyAvailableReport(

package/node_modules/@llblab/pi-codex-usage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-codex-usage",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "private": false,
   "description": "Minimal Pi extension that shows primary Codex ChatGPT subscription usage limits",
   "keywords": [

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

@@ -10,16 +10,16 @@
 - Correlate successful exact-path reads with the current ordinary global invalidation plan. Require each acquired stale source to have a compact compiler output at the same path in a global transition, reject model-authored provenance fields, and record the runtime-observed source hash plus current ordinary compiler revision in the global provenance registry. Compile routing descriptions by default, never raw Markdown or a full-file summary; preserve uncertainty and reserve richer compilations for reusable operational semantics.
 - Apply one materialized-first acquisition policy to every source: read only for a concrete relevant gap not covered by a sufficient compilation, an exact-source operation including edits, evidenced invalidation, contradiction/failure reconciliation, explicit request, or selection by bounded maintenance. New sessions, routine recall or activation, reassurance, and an index or description alone are not reasons to read. Changed hashes require rereading; prefer the smallest sufficient read.
 - Keep artifact maintenance opt-in, low-frequency, and side-effect free until a selected source is acquired. Select only otherwise-fresh artifacts old enough for maintenance, rank missing/unparseable `compiled_at` first then oldest timestamp and path, and enforce strict per-cycle read-count and source-byte ceilings. Treat source bytes as the conservative source-token upper bound. Never let maintenance displace correctness invalidation; use explicit invalidation refresh for full rebuilds and never mutate source files.
-- Load optional agent-level `state-flow.json` once per extension load/reload. Its `directory` selects the state store, `autoStart` defaults false for genuinely new sessions, `showSuccessfulPatches` defaults true for interactive successful-call JSON rendering, and `remotePublication` selects `off`, `turn-end`, or compatibility `transition`. State Flow always owns durable memory while enabled and global semantic memory is always available; these are invariants, not configuration switches. Keep runtime configuration and provenance outside model-patchable semantic state.
-- Keep runtime configuration and provenance separate from model-patchable semantic state. Persist session `config.json` for enablement/projection settings and `meta.json` for lineage, counters, branch identity, durable base, publication, migration metadata, and session-scope artifact provenance; global and CWD scopes own their artifact provenance in scope `meta.json`. Neither participates in scope overlay. New Pi checkpoints contain only a durable revision pointer, or `{disabled:true}` when no durable runtime exists on that branch. Preserve exact Git hashes for Git-backed revisions and give file-only current-cohort references an unambiguous distinct identity; file references use `file:<64 lowercase hex>`, bind the store root and complete scoped/runtime cohort, and must not pretend to provide arbitrary cold or branch history. Operationally unavailable references (including expired file cohorts, missing Git, and publication exclusion) retain selection rather than falling through to older disabled markers; malformed immutable targets remain a distinct recovery case; they are not a parallel authoritative semantic or config/meta store. Emit a disabled marker only from proven pre-runtime branch provenance; missing/invalid revisions and failed restoration do not establish that permission. Predecessor checkpoint/tail envelopes are read-only migration input, recognized only by their complete exact structure and converted explicitly through the normal lock/CAS publication path. Validate immutable pointer targets before acquiring the live publication basis; transient publication failures preserve the selected retry reference rather than choosing older semantic state. In Git mode, runtime `revision: "self"` resolves to the commit owning the config/meta pair, not an unrelated later repository commit. File publication uses explicit `publication: "files"` provenance and resolves the exact complete live cohort instead of claiming a Git owner. Use a distinct `meta.temporalRevision` when a runtime-only write selects older semantic scopes; restore their artifact provenance from that same revision and preserve live shared checkpoints, tails, and provenance during session config/meta writes. Persist publication intent as unconfirmed before pushing; reconcile that exact existing commit after restart rather than embedding an impossible self-hash or inventing semantic history.
+- Load optional repository-global `config.json` from the canonical `<agentDir>/state-flow/` root once per extension load/reload. `autoStart` defaults false for genuinely new sessions, `passiveBootstrap` and `passiveTools` default true and remain independent of episode lifecycle, `showSuccessfulPatches` defaults true for interactive successful-call JSON rendering, and `remotePublication` selects `off`, `turn-end`, or compatibility `transition`; SDK embeddings may explicitly override the repository. State Flow always owns durable memory while enabled and global semantic memory is always available; these are invariants, not configuration switches. Keep global operator configuration, runtime configuration, and provenance outside model-patchable semantic state.
+- Keep runtime configuration and provenance separate from model-patchable semantic state. Persist session `config.json` for enablement/projection settings, session `runtime.json` for lineage, counters, branch identity, durable base, publication, and migration metadata, and every scope's adjacent `meta.json` for temporal boundaries, ownership where applicable, and artifact provenance. None participates in scope overlay. Read the predecessor combined session `meta.json` only as migration input; the next normal CAS publication must write `runtime.json` and clean known runtime fields from semantic metadata. New Pi checkpoints contain only a durable revision pointer, or `{disabled:true}` when no durable runtime exists on that branch. Preserve exact Git hashes for Git-backed revisions and give file-only current-cohort references an unambiguous distinct identity; file references use `file:<64 lowercase hex>`, bind the store root and complete scoped/runtime cohort, and must not pretend to provide arbitrary cold or branch history. Operationally unavailable references (including expired file cohorts, missing Git, and publication exclusion) retain selection rather than falling through to older disabled markers; malformed immutable targets remain a distinct recovery case; they are not a parallel authoritative semantic or config/meta store. Emit a disabled marker only from proven pre-runtime branch provenance; missing/invalid revisions and failed restoration do not establish that permission. Predecessor checkpoint/tail envelopes are read-only migration input, recognized only by their complete exact structure and converted explicitly through the normal lock/CAS publication path. Validate immutable pointer targets before acquiring the live publication basis; transient publication failures preserve the selected retry reference rather than choosing older semantic state. In Git mode, runtime `revision: "self"` resolves to the commit owning the config/meta pair, not an unrelated later repository commit. File publication uses explicit `publication: "files"` provenance and resolves the exact complete live cohort instead of claiming a Git owner. Use a distinct `meta.temporalRevision` when a runtime-only write selects older semantic scopes; restore their artifact provenance from that same revision and preserve live shared checkpoints, tails, and provenance during session config/meta writes. Persist publication intent as unconfirmed before pushing; reconcile that exact existing commit after restart rather than embedding an impossible self-hash or inventing semantic history.
 - Overlay materialized state recursively in `global → cwd → session` order. Scope-local deletion removes only that scope's key so a lower-scope value becomes visible again; scope never changes instruction authority. Route branch/run-local continuation to session, project-local reusable state and Skill artifacts to CWD, and cross-project reusable state to global.
 - Reserve `state` for the runtime materialized semantic view. `checkpoint.json` contains only the canonical materialized semantic state, each nonblank `patches.jsonl` line contains only one semantic patch, and adjacent `meta.json` owns their checkpoint/tail boundaries plus CWD identity. For each scope, current state is exactly `materialize(checkpoint.json, patches.jsonl, meta.json)`: an older anchored checkpoint plus its ordered tail of at most seven materially effective semantic patches. On overflow, apply the oldest patch into the checkpoint, advance its `through` boundary, remove it, and append the new patch. Never truncate unapplied replay records or replay patches over an already-current snapshot.
 - Give every accepted semantic transition one opaque identity shared by all affected scope records, with explicit active causal lineage. A branch-local position can order identities but never acts as a global counter, substitutes for identity, or merges forks. Unchanged scopes contribute no record and remain unchanged at that boundary. Adopt revision-proven inherited streams at a new session origin without rewriting their checkpoints/tails; pre-origin coordinates are not one shared clock. A restored branch adopts current proven live shared streams it does not modify at a fresh origin while preserving its selected session layer; a shared scope the accepted transition actually changes must still match its selected basis or fail closed naming that scope. Reconciliation adoption is not a fabricated semantic transition, parent link, or retry loop. True semantic no-ops and origin adoption do not advance semantic history.
-- Define `state[n]` and `state.global[n]`, `state.cwd[n]`, `state.session[n]` at the same nth previous accepted transition boundary in the active lineage, never the nth local patch of each scope. Guarantee offsets zero through seven once the lineage has seven proven transitions; report earlier-than-origin history as unavailable for new/migrated lineages and reject offsets beyond seven on the hot interface. Reconstruct scopes at one target before overlaying them.
-- Keep historical reads lazy through the smallest runtime/model read interface. Normal inference gets only current effective state and useful bounded compact transition context, never eight full snapshots. `patch_state` is the sole semantic mutation tool. `read_state` resolves current-as-index-zero aliases for effective/scoped materializations and scope-local retained accepted patches; materialization indices share the composed causal lineage while `patches[n]` walks the selected scope's retained patch tail. The prior offset/scope form remains a compatibility input and cannot combine with `path`. Reads return the exact boundary and never publish, append a checkpoint, or advance history. Both tools follow branch enablement and host tool restrictions; the patch barrier blocks reader siblings too. Live/cached checkpoint plus tails own the hot path; use Git for branch restoration and explicit cold inspection, not to rebuild current state on every inference.
-- Store runtime state in its own directory with optional Git durability, defaulting to `state-flow/` beneath Pi's configured agent directory (`~/.pi/agent/state-flow/` normally), independently from the Knowledge Markdown source root. Use exactly these owned paths: `checkpoint.json`, `patches.jsonl`, and `meta.json` for global; `<cwd-key>/checkpoint.json`, `<cwd-key>/patches.jsonl`, and `<cwd-key>/meta.json` for CWD; `<cwd-key>/<session-key>/checkpoint.json`, `patches.jsonl`, `config.json`, and `meta.json` for session. Do not create `.state-flow`, `scopes`, or another storage/history namespace. Mirror Pi's native CWD session-directory encoding and JSONL-basename session key (deriving `<header timestamp>_<UUID>` for in-memory sessions), while retaining separately verifiable canonical identity provenance in owned state. Keep the UUID authoritative, reject unsafe segments and mismatches rather than selecting another scope, and use CWD `meta.json` ownership to fail closed on Pi-name collisions.
+- Define `effective[n]`, `global[n]`, `cwd[n]`, and `session[n]` at the same nth previous accepted transition boundary in the active lineage, never the nth local patch of each scope. Guarantee offsets zero through seven once the lineage has seven proven transitions; report earlier-than-origin history as unavailable for new/migrated lineages and reject offsets beyond seven on the hot interface. Reconstruct scopes at one target before overlaying them.
+- Keep historical reads lazy through the smallest runtime/model read interface. Normal inference gets only current effective state and useful bounded compact transition context, never eight full snapshots. `patch_state` is the sole semantic mutation tool. `read_state` treats unscoped semantic paths as current effective aliases, accepts explicit effective/scoped materializations and scope-local retained accepted patches, and rejects the retired top-level `state` segment; materialization indices share the composed causal lineage while `patches[n]` walks the selected scope's retained patch tail. The public reader accepts only `path` or `paths`; temporal offsets and scope selection are expressed in path syntax. Reads return the exact boundary and never publish, append a checkpoint, or advance history. Both tools follow branch enablement and host tool restrictions; the patch barrier blocks reader siblings too. Live/cached checkpoint plus tails own the hot path; use Git for branch restoration and explicit cold inspection, not to rebuild current state on every inference.
+- Store runtime state in its own directory with optional Git durability, defaulting to `state-flow/` beneath Pi's configured agent directory (`~/.pi/agent/state-flow/` normally), independently from the Knowledge Markdown source root. Use exactly these owned paths: `checkpoint.json`, `patches.jsonl`, and `meta.json` for global; `<cwd-key>/checkpoint.json`, `<cwd-key>/patches.jsonl`, and `<cwd-key>/meta.json` for CWD; `<cwd-key>/<session-key>/checkpoint.json`, `patches.jsonl`, `meta.json`, `config.json`, and `runtime.json` for session. Do not create `.state-flow`, `scopes`, or another storage/history namespace. Mirror Pi's native CWD session-directory encoding and JSONL-basename session key (deriving `<header timestamp>_<UUID>` for in-memory sessions), while retaining separately verifiable canonical identity provenance in owned state. Keep the UUID authoritative, reject unsafe segments and mismatches rather than selecting another scope, and use CWD `meta.json` ownership to fail closed on Pi-name collisions.
 - Classify every filesystem cohort before recovery: complete valid evidence is usable; total absence is recoverable only from an explicit semantic default or exact surviving authority; partial, malformed, contradictory, or authority-losing evidence fails closed at the smallest dependent capability. A wholly absent untouched global/CWD checkpoint-tail pair is current empty shared reality and must not resurrect selected cold values; a patch targeting that disappeared scope is stale and must fail for reinference. Missing provenance means unavailable freshness, not semantic corruption. Perform every repair through normal locked/CAS publication, never ad-hoc writes.
-- Support exactly one storage migration: complete predecessor checkpoint/tail envelopes across every owner-proven session in the configured store convert into semantic-only checkpoint/tail files plus temporal `meta.json` through one normal locked/CAS publication. Replace a Git-backed store's history with one new root commit for the complete migrated tree; apply the same cohort without Git in file-only mode. `state.json`, pre-0.4 hashed layouts, and semantic Pi checkpoint envelopes are unsupported and never become recovery authority. Exercise migrations in temporary repositories rather than modifying the user's active data during development.
+- Support the release-owned storage migration chain through the migration domain: complete predecessor checkpoint/tail envelopes convert into semantic-only checkpoint/tail files plus temporal `meta.json`, and the 0.13 → 0.14 step splits every owner-proven session's combined `meta.json` into scope-only `meta.json` plus branch/run `runtime.json`. Execute the applicable steps through one normal locked/CAS publication. Replace a Git-backed semantic-envelope store's history with one new root commit for the complete migrated tree; apply the same cohort without Git in file-only mode. `state.json`, pre-0.4 hashed layouts, and semantic Pi checkpoint envelopes are unsupported and never become recovery authority. Exercise migrations in temporary repositories rather than modifying the user's active data during development.
 - Read and write only regular non-symlink State Flow-owned files at those exact paths, publish each file by same-directory atomic rename, preserve arbitrary repository contents, and classify ownership exactly. Git acceptance follows the complete-delta isolated-index contract below. Retain opaque source bytes for file identity and rollback, not decoded-text reconstructions. Use validated structural JSON equality for in-process semantic comparisons; reserve cryptographic hashes for compact identities that cross inference, persistence, process, or source-freshness boundaries. Serialize cooperating Git publications through a common-Git-directory publication lock; low-level file helpers require caller exclusion. Recheck prepared bases before each replacement/deletion and restore only bytes still matching the publisher's own output. Preserve detected concurrent changes and report unresolved rollback conflicts; do not claim kernel-atomic multi-file CAS against nonparticipating writers. Markdown discovery uses its independently configured source root, defaulting to `knowledge/` beneath Pi's agent directory; a storage-root override must not redirect source discovery.
 - At instance initialization resolve the repository, CWD key, and session key; load each scope's anchored checkpoint and tail, materialize at the selected temporal boundary, then overlay `global → cwd → session`. Install cached view and publication basis atomically only after successful restoration/initialization; unavailable publication is an error, not a semantic no-op. Branch recovery may reuse one owner-bound, single-use inspection of the exact selected immutable Git revision, with a detached inspection snapshot and a freshly acquired live publication basis at installation. Revalidate mutable file cohorts, legacy snapshot fallbacks, and redirected runtime owners; never turn inspection into a long-lived revision or publication-basis cache. Preserve the selected revision across transient restore failure so an explicit start can retry it. A genuinely new session gets an empty session layer and inherits only global/CWD values; it must never reuse another same-CWD session layer. Explicit native fork adoption instead follows the [session-copy contract](docs/fork-contract.md): copy the proven source session checkpoint/tail and provenance into a distinct owner over current shared streams, without pruning shared provenance or modifying the parent. Use a fresh origin, preserve copied replay records, reject occupied live/HEAD targets, and publish/checkpoint the child only after CAS acceptance. Inherited parent pointers never authorize an empty reset; fence parent passive Stop projection across child reload.
 - Bind every loaded scope and active Pi branch/checkpoint to the corresponding State Flow Git revision. Resume and tree restoration must recover branch-correct runtime config and semantic layers from that revision without blindly importing Git `HEAD`; reading an older revision must use object-level Git reads and never reset or check out the shared repository worktree.
@@ -37,17 +37,17 @@
 - Agent-level opt-in `logging` appends local JSONL diagnostics for rejected `patch_state` attempts and preserved drafts plus fallback turns while turn resolution remains pending. Every rejected call retains its exact attempted arguments plus the precise error and, when available, tool identity, call id, resolution attempt, and terminal-eligibility state; successful patches are never logged. Preserve exact text blocks only where useful, reduce other blocks to structural identity, never duplicate reasoning bodies, and keep logging outside semantic state, scope metadata, checkpoints, and publication. Logging failure emits at most one warning and never changes resolution, enablement, or accepted state.
 - Recursively materialize patches immediately; empty objects preserve, nested object-key `null` deletes, and `null` anywhere in semantic state including arrays is invalid. This prohibition does not apply to runtime envelopes such as an origin's null parent. Persist runtime-normalized replay patches that exactly reproduce accepted state, including complete artifact replacement; runtime-owned provenance is stored in scope `meta.json` and is not part of semantic replay.
 - Do not impose project schemas, state or patch byte caps, dynamic growth pressure, observation envelopes, action authorization, action ledgers, or state-size limits.
-- Rotate the turn-stable specification on every user-initiated run, while runtime-triggered turn-resolution continuation remains inside that same run. Keep user-controlled specification text at user authority: never interpolate it into the system prompt; repeat it only in synthetic user runtime context. Treat materialized state in that message as fallible assistant-produced data whose transport role does not elevate it into user instructions.
+- Rotate the turn-stable specification on every user-initiated run, while runtime-triggered turn-resolution continuation remains inside that same run. Persist the full specification only while that run is unfinished, then remove it atomically with accepted terminal response reconciliation. Keep user-controlled specification text at user authority: never interpolate it into the system prompt; repeat it only in synthetic user runtime context. Treat materialized state in that message as fallible assistant-produced data whose transport role does not elevate it into user instructions.
 - When enabled inside an existing session, retain Pi's active context for exactly one complete bootstrap run and require its `patch_state` resolution to migrate all future-relevant context.
 - Restore extension state from the active Pi session branch's checkpoint and recorded State Flow revision, not the full session entry list or current Git `HEAD`, on both startup and successful in-session tree navigation.
 - Render compact status as accent `state-flow` plus dim `#<step>`. `/state-flow-status` must distinguish session config/meta from semantic temporal materialization; show the CWD and session keys, step, active temporal head and State Flow revision, available hot-history depth, per-scope artifact/tail counts, discovered global Markdown stale reasons, and pending publication; and render only the effective global → CWD → session materialization as semantic JSON, without reading or dumping source bodies beyond path/hash discovery needed for freshness diagnostics. Distinguish selected retained tail counts from active history depth; inherited tails may predate the origin. When temporal materialization is unavailable, report unknown counts/freshness and unavailable state rather than inventing empty projections.
 - Explicit `/state-flow-start` creates the State Flow directory when missing and returns after locally usable runtime acceptance for normal `turn-end`/`off` policy. If Git is installed, initialize an exact-root Git repository when needed, including a populated file-only store, preserving all existing bytes and unrelated files; an ancestor repository is not a valid substitute. Skip full predecessor-format migration planning only when all exact legacy snapshot names are absent, and defer Markdown freshness discovery until before the next enabled inference. If Git is absent, use file persistence. Manual-mode startup/status/restore do not initialize Git; configured automatic start of a genuinely new session uses the same initialization as explicit start. Never create external accounts, remote repositories, credentials, or remote configuration; those remain operator-owned. Never auto-import, delete, or reset files/history in a previous Knowledge-backed store; old branch revisions require their original Git history to remain available in the selected store. `/state-flow-start` must initialize missing global, CWD, and current-session checkpoint/tail pairs plus session config/meta through compare-and-swap publication when required, enable only the current session branch, and bootstrap prior conversation when needed. Explicit start on a proven pre-runtime branch (no checkpoint or an ordinary-disabled marker) establishes an empty session origin rather than importing a later same-session layer; validate existing runtime identity, retain shared streams unchanged, and preserve later branch data in cold Git history. Ordinary new sessions remain manual unless agent-level `autoStart` is true; CWD materialization alone grants no automatic activation. Configured new sessions may initialize missing CWD state and receive distinct empty session layers while inheriting global/CWD values. Resumed and tree-selected branches restore their own config and temporal lineage, regardless of the global flag.
-- `/state-flow-stop` must persist only the current session/branch's `config.enabled = false` and necessary runtime provenance, preserving all semantic checkpoints/tails and creating no semantic transition. Retain a frozen handoff plus the active user-run trajectory (including later tool results), post-stop conversation, and foreign context-bearing custom messages across same-physical-session reload/resume/tree. Exclude completed pre-run conversation and private State Flow validation feedback; idle Stop does not retain the completed run. Active restart replaces passive mode but uses that bounded boundary for its one migration run; new and forked physical sessions inherit neither projection. It does not rewrite agent-level `autoStart` or change its policy for future new sessions.
+- `/state-flow-stop` returns to the configured passive bootstrap/tool combination and must persist only the current session/branch's `config.enabled = false` and necessary runtime provenance, preserving all semantic checkpoints/tails and creating no semantic transition. Retain a frozen handoff plus the active user-run trajectory (including later tool results), post-stop conversation, and foreign context-bearing custom messages across same-physical-session reload/resume/tree. Exclude completed pre-run conversation and private State Flow validation feedback; idle Stop does not retain the completed run. Active restart replaces passive mode but uses that bounded boundary for its one migration run; new and forked physical sessions inherit neither projection. It does not rewrite agent-level `autoStart` or change its policy for future new sessions.
 - After an accepted non-bootstrap run settles with no pending input, State Flow may request native manual compaction under a generation-private marker only when public `getContextUsage()` reports at least 24,000 tokens. Keep the complete latest accepted user iteration, store only revision/step identity in details, and never duplicate state in the summary. Unknown or smaller usage skips compaction; a benign native refusal releases the attempt for later work. Skip prefixes containing foreign custom context. Never customize user manual or native threshold/overflow compaction, discard unfinished pre-patch work, create a State Flow origin, or rewrite Pi's append-only JSONL/tree.
 - Keep the injected runtime protocol compact and normative; put rationale and extended explanation in README rather than the model prompt. Never parse or strip State Flow HTML comments; they are ordinary historical text, while foreign comment handling remains owned by other extensions.
 - Do not claim strict boundedness for state, the current run trajectory, the turn specification, or the external full trace.
 - Remain extension-agnostic in core semantics, storage, and inference: core modules never import, name, special-case, or encode policy for another extension or transport. One optional leaf presentation adapter (`lib/telegram.ts`) may import public `pi-telegram` membranes to mirror the live status on exactly one main-menu section button and expose the same start/stop affordances already owned by `state-flow-start` and `state-flow-stop`; it must fail open when the transport is absent or its registry is unready and must never alter core behavior.
-- Activate State Flow model tools only while enabled on the selected branch; preserve every unrelated active tool when toggling them. Keep mutation confined to `patch_state` and historical observation read-only.
+- Activate State Flow model tools while an episode is enabled or passive tools are configured; preserve every unrelated active tool when toggling them. Passive reads never initialize storage, while an explicit passive patch may initialize or migrate storage without enabling episode barriers, continuation, or compaction. Keep mutation confined to `patch_state` and historical observation read-only.
 - Keep `.github/workflows/release.yml` as the sole version-tag release owner: it validates immutable tag identity, publishes through npm Trusted Publisher with provenance, verifies the public package, and only then creates the GitHub Release. Keep package, lockfile, tag, and changelog versions aligned; never add a long-lived npm token fallback.
 - Keep opt-in performance executables and workers in top-level `benchmarks/`; their correctness regressions stay in `tests/`. Benchmark workloads may reuse synthetic test fixtures, remain excluded from runtime packaging, and retain source-bound measurement identities across relocations.
 - Run `npm run validate` after retained code changes, then run the canonical ABCd context validator after context edits.

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

@@ -1,16 +1,3 @@
 # BACKLOG
 
 Completed release work belongs in [CHANGELOG.md](CHANGELOG.md).
-
-## Candidate evolution
-
-- [ ] `Default passive memory access`: Separate memory availability from the active State Flow episode lifecycle. A normal installation defaults to both passive state bootstrap and `read_state`/`patch_state` tools, while automatic terminal compaction, iteration continuation, and active episode semantics remain gated behind `/state-flow-start`.
-  - Configuration: control passive bootstrap and passive tools independently, yielding all four supported combinations: both off, bootstrap only, tools only, or both on (default). Fully off must add no state projection or tools to model context.
-  - Passive bootstrap: project existing effective durable state without creating scopes, migrating storage, publishing changes, starting an episode, or promising automatic continuation. Name this separately from active episode/bootstrap semantics.
-  - Passive tools: `read_state` remains read-only; an explicit `patch_state` may initialize or migrate the required durable runtime and publish only the requested semantic change, but must not activate terminal compaction or future automatic iterations.
-  - Lifecycle: `/state-flow-start` promotes passive access into the existing active episode behavior. `/state-flow-stop` returns to the configured passive combination rather than overriding it globally.
-  - Acceptance: cover all four configuration combinations, fresh and existing stores, explicit passive patch publication, unsupported-storage failure, start/stop transitions, tool/context visibility, and proof that passive turns never run terminal compaction.
-  - Status: accepted direction, not implemented. Requires a dedicated release contract.
-- [ ] `Pi Telegram submenu state analyzer`: Extend the State Flow Telegram section with a read-only analyzer view over the same diagnostics `/state-flow-status` already reports (branch mode, temporal head and hot depth, scope keys, retained tails, artifact freshness, publication). The operator deliberately deferred this beyond the 0.9.0 control surface.
-  - Boundary: presentation only. Reuse existing status diagnostics; no new semantic mode, and never mutate state from the analyzer view.
-  - Status: candidate, not scheduled. Do not start without a dedicated release contract.

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

@@ -4,6 +4,21 @@
 
 ## Unreleased
 
+## 0.14.0: Passive and progressive memory
+
+- `Default passive memory`: Repository-root configuration now adds independently configurable passive bootstrap and `read_state`/`patch_state` access, both enabled by default. Passive reads project durable memory without mutation; explicit patches may materialize storage while episode barriers, continuation, response reconciliation, and compaction remain inactive. Start promotes to active semantics and Stop returns to passive mode.
+- `Bounded array ranges`: Added strict half-open `[start:end]` selectors to `read_state` value and patch paths, with `[start..end]` accepted as a forgiving fallback spelling. Ranges are zero-based, must fit fully within the selected array, preserve ordered batch semantics, and never truncate silently.
+- `Direct read paths`: Removed the redundant top-level `state` segment and legacy public `offset`/`scope` inputs. `read_state` now accepts only `path` or `paths`; unscoped semantic paths read the current effective overlay, while `effective`, `global`, `cwd`, and `session` select overlay or ownership. The injected model protocol is 25% shorter while retaining its normative contract.
+- `Lazy semantic plane`: Added scope-local ordinary-JSON `lazy` state under the existing atomic temporal lineage. Ordinary projections omit lazy bodies but expose a bounded root hint; explicit scoped, effective, historical, value, and keys reads resolve lazy data through `read_state`. Telegram inspection now exposes `lazy` and represents the state step with native rich-text code rather than visible Markdown delimiters.
+- `Lazy durability`: Preserved lazy values through predecessor-envelope migration, exact Git and file-only restoration, and native session forks. Invalid lazy state and stale-basis hot-plus-lazy publication now fail before changing retained hot or lazy semantics. Local incompressible-payload measurements found roughly linear current-layout growth and sub-0.5-second publication/restoration through 1 MiB, so this release keeps lazy data co-located with canonical scope semantics rather than adding speculative sharding.
+- `Indexed array patches`: Extended recursive `patch_state` semantics so canonical `"[N]"` selectors update existing array elements, including nested object and array elements, while invalid indices or indexed deletion reject the complete atomic cohort.
+- `Progressive historical reads`: Extended `read_state` with arbitrary path-intersected semantic `patch` projection, including ordered all-or-error batches and effective-state change projection without exposing temporal metadata.
+- `Session storage ownership`: Split branch/run recovery into session `runtime.json`, leaving every scope's `meta.json` symmetric around temporal boundaries and artifact provenance. The migration domain now explicitly detects and atomically upgrades every owner-proven 0.13 session to the 0.14 contract through normal CAS publication; full specifications are removed after accepted terminal reconciliation.
+
+## 0.13.4: Concurrent publication hotfix
+
+- `Publication contention`: A publisher now waits briefly for a cooperating live State Flow process to release the storage or shared Git lock, preventing transient concurrent `patch_state` calls from failing while preserving explicit errors for interrupted, malformed, reentrant, or prolonged lock ownership.
+
 ## 0.13.3: Telegram section discovery hotfix
 
 - `Telegram section discovery`: The compiled extension now resolves the sibling pi-telegram public sections membrane from its compiled layout as well as the package export, restoring the State Flow control in the Telegram main menu without making Telegram a core dependency.

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

@@ -2,9 +2,9 @@
 
 ![pi-state-flow banner](https://raw.githubusercontent.com/llblab/pi-state-flow/main/banner.jpg)
 
-**Working memory for Pi, carried with the session.**
+**Incremental scoped context/memory compiler for Pi.**
 
-Keep decisions, constraints, verified findings, and next steps without sending every completed tool exchange back to the model. State Flow lets the agent maintain explicit state; Pi still owns the conversation, the native tool loop, and the complete inspectable trace.
+Keep decisions, constraints, verified findings, and next steps without sending every completed tool exchange back to the model. State Flow compiles curated context and memory into explicit state; Pi still owns the conversation, the native tool loop, and the complete inspectable trace.
 
 > Inspired by [SKILL.state](https://arxiv.org/html/2608.26263v2).
 
@@ -51,22 +51,23 @@ Continue working normally. The agent receives the state protocol and uses `patch
 - `/state-flow-status`: Inspect the selected state, history, artifact freshness, and publication status.
 - `/state-flow-stop`: Disable updates on this branch without deleting retained state.
 
-State Flow is **opt-in**. Starting in an existing conversation keeps its active context for one migration run. To enable genuinely new sessions automatically, set `"autoStart": true` in the optional [configuration](docs/usage.md#configuration).
+Active State Flow episodes remain **opt-in**, while passive durable memory bootstrap and tools are available by default. Passive turns never require `final:true`, continue automatically, or trigger State Flow compaction. Starting an active episode in an existing conversation keeps its context for one migration run; set `"autoStart": true` to promote genuinely new sessions automatically. See [configuration](docs/usage.md#configuration).
 
 ## What carries forward
 
-The same four fields exist at every scope:
+The same semantic planes exist at every scope:
 
 - `contract`: Requirements, decisions, constraints, and interface commitments.
 - `working`: Observations, results, unresolved questions, and what to do next.
 - `artifacts`: Source-addressed descriptions and reusable compiled knowledge.
 - `response`: The latest complete answer, captured by the runtime.
+- `lazy`: Durable, versioned memory omitted from ordinary context until explicitly read.
 
-Memory overlays **global → project CWD → session**. Put reusable cross-project knowledge in global, project knowledge in CWD, and private task continuation in session.
+Memory overlays **global → project CWD → session**. Put reusable cross-project knowledge in global, project knowledge in CWD, and private task continuation in session. Hot planes carry what must matter now; `lazy` retains what may matter later without hydrating its body into every prompt.
 
 **Resuming an existing Pi session restores its selected State Flow state and enablement.** A genuinely new session starts with an empty session layer and inherits only shared global/CWD memory; it does not resume another session's private work. Tree navigation follows the selected branch, not whichever state happens to be at Git `HEAD`.
 
-The agent can inspect `state`/`state[0]` through `state[7]`: now and up to seven prior accepted transitions. Scoped paths such as `state.cwd[1]` use the same causal boundary; `state.global.patches[0]` reads the latest retained accepted patch for that scope. Git-backed stores retain older committed history separately.
+The agent uses `read_state` for exact current or historical paths. Unscoped paths read the effective overlay; `global`, `cwd`, and `session` address ownership directly; `[n]` selects one of up to seven prior accepted transition boundaries. Bounded array ranges and `value`, `keys`, or `patch` projections support progressive reads without hydrating whole lazy collections. Git-backed stores retain older committed history separately.
 
 ## Boundaries worth knowing
 

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

@@ -1,11 +1,14 @@
 export interface StateFlowConfig {
+    /** Canonical State Flow repository. SDK callers may still override it explicitly. */
     directory: string;
     autoStart: boolean;
+    passiveBootstrap: boolean;
+    passiveTools: boolean;
     /** Opt-in local capture of rejected patch attempts and unresolved terminal drafts. */
     logging: boolean;
     /** Show successful patch_state arguments in the interactive tool row. */
     showSuccessfulPatches: boolean;
     remotePublication?: "off" | "turn-end" | "transition";
 }
-/** Read once at extension load/reload. Missing config uses defaults; invalid config never falls back. */
-export declare function loadStateFlowConfig(agentDir?: string): StateFlowConfig;
+/** Read the repository-global config once at extension load/reload. Missing config uses defaults; invalid config never falls back. */
+export declare function loadStateFlowConfig(agentDir?: string, repositoryRoot?: string): StateFlowConfig;

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

@@ -1,16 +1,18 @@
-// Domain: agent-level State Flow configuration, independent of session runtime and semantic state.
+// Domain: repository-global State Flow configuration, independent of session runtime and semantic state.
 import { lstatSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, resolve } from "node:path";
+import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getDurableRepositoryRoot } from "./durable.js";
 import { isObject } from "./json.js";
-/** Read once at extension load/reload. Missing config uses defaults; invalid config never falls back. */
-export function loadStateFlowConfig(agentDir = getAgentDir()) {
-    const path = resolve(agentDir, "state-flow.json");
+/** Read the repository-global config once at extension load/reload. Missing config uses defaults; invalid config never falls back. */
+export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = getDurableRepositoryRoot(agentDir)) {
+    const directory = repositoryRoot;
+    const path = join(directory, "config.json");
     const defaults = {
-        directory: getDurableRepositoryRoot(agentDir),
+        directory,
         autoStart: false,
+        passiveBootstrap: true,
+        passiveTools: true,
         logging: false,
         showSuccessfulPatches: true,
     };
@@ -23,12 +25,16 @@ export function loadStateFlowConfig(agentDir = getAgentDir()) {
     catch (error) {
         throw new Error(`Cannot read State Flow configuration: ${path}`, { cause: error });
     }
-    const allowed = new Set(["directory", "autoStart", "logging", "showSuccessfulPatches", "remotePublication"]);
+    const allowed = new Set(["autoStart", "passiveBootstrap", "passiveTools", "logging", "showSuccessfulPatches", "remotePublication"]);
     if (!isObject(value) || Object.keys(value).some((key) => !allowed.has(key))) {
         throw new Error(`State Flow configuration contains unknown settings: ${path}`);
     }
     if (Object.hasOwn(value, "autoStart") && typeof value.autoStart !== "boolean")
         throw new Error(`State Flow autoStart must be a boolean: ${path}`);
+    if (Object.hasOwn(value, "passiveBootstrap") && typeof value.passiveBootstrap !== "boolean")
+        throw new Error(`State Flow passiveBootstrap must be a boolean: ${path}`);
+    if (Object.hasOwn(value, "passiveTools") && typeof value.passiveTools !== "boolean")
+        throw new Error(`State Flow passiveTools must be a boolean: ${path}`);
     if (Object.hasOwn(value, "logging") && typeof value.logging !== "boolean")
         throw new Error(`State Flow logging must be a boolean: ${path}`);
     if (Object.hasOwn(value, "showSuccessfulPatches") && typeof value.showSuccessfulPatches !== "boolean")
@@ -36,16 +42,11 @@ export function loadStateFlowConfig(agentDir = getAgentDir()) {
     if (Object.hasOwn(value, "remotePublication") && value.remotePublication !== "off" && value.remotePublication !== "turn-end" && value.remotePublication !== "transition") {
         throw new Error(`State Flow remotePublication must be off, turn-end, or transition: ${path}`);
     }
-    if (Object.hasOwn(value, "directory") && (typeof value.directory !== "string" || !value.directory.trim() || value.directory.includes("\0"))) {
-        throw new Error(`State Flow directory must be a non-empty path: ${path}`);
-    }
-    const directory = value.directory;
-    if (directory?.startsWith("~") && directory !== "~" && !directory.startsWith("~/"))
-        throw new Error(`State Flow directory supports ~ or ~/ paths, not named-user expansion: ${path}`);
-    const expanded = directory === "~" ? homedir() : directory?.startsWith("~/") ? resolve(homedir(), directory.slice(2)) : directory;
     return {
-        directory: expanded === undefined ? defaults.directory : resolve(dirname(path), expanded),
+        directory,
         autoStart: value.autoStart === true,
+        passiveBootstrap: value.passiveBootstrap !== false,
+        passiveTools: value.passiveTools !== false,
         logging: value.logging === true,
         showSuccessfulPatches: value.showSuccessfulPatches !== false,
         ...(value.remotePublication === undefined ? {} : { remotePublication: value.remotePublication }),

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

@@ -5,6 +5,13 @@ import type { Snapshot } from "./snapshot.ts";
 import type { RehydrationPhase } from "./rehydration.ts";
 import { type MaterializedState } from "./state.ts";
 export declare const VALIDATION_MESSAGE_TYPE = "state-flow-validation";
+type LazyValueKind = "array" | "boolean" | "null" | "number" | "object" | "string";
+/** Fixed-budget navigation only: never place lazy bodies or partial key catalogs in baseline context. */
+export declare function lazyNavigationHint(state: MaterializedState): {
+    available: boolean;
+    path: string;
+    keys?: Record<string, LazyValueKind>;
+};
 /** Bounded context retained after semantic State Flow is stopped in this physical session. */
 export interface PassiveContinuation {
     startedAt: number;
@@ -21,3 +28,4 @@ export declare function currentRunTrajectory(messages: AgentMessage[], specifica
     messages: AgentMessage[];
     anchorTimestamp?: number;
 };
+export {};

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

@@ -2,6 +2,29 @@ import { projectArtifactForModel } from "./artifact.js";
 import { canonicalJson } from "./json.js";
 import { projectStateForModel } from "./state.js";
 export const VALIDATION_MESSAGE_TYPE = "state-flow-validation";
+const LAZY_HINT_PATH = "effective.lazy";
+const LAZY_HINT_MAX_KEYS = 32;
+const LAZY_HINT_MAX_JSON_CHARS = 1024;
+function lazyValueKind(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    if (typeof value === "object")
+        return "object";
+    return typeof value;
+}
+/** Fixed-budget navigation only: never place lazy bodies or partial key catalogs in baseline context. */
+export function lazyNavigationHint(state) {
+    const base = { available: Object.hasOwn(state, "lazy"), path: LAZY_HINT_PATH };
+    if (!base.available || typeof state.lazy !== "object" || state.lazy === null || Array.isArray(state.lazy))
+        return base;
+    const entries = Object.entries(state.lazy);
+    if (entries.length > LAZY_HINT_MAX_KEYS)
+        return base;
+    const keys = Object.fromEntries(entries.map(([key, value]) => [key, lazyValueKind(value)]));
+    return JSON.stringify(keys).length <= LAZY_HINT_MAX_JSON_CHARS ? { ...base, keys } : base;
+}
 export function syntheticUser(text) {
     return { role: "user", content: [{ type: "text", text }], timestamp: Date.now() };
 }
@@ -63,6 +86,7 @@ export function runtimeContextMessage(snapshot, state, recentTransitions = [], a
     const context = {
         specification: snapshot.meta.specification,
         state: projectStateForModel(state),
+        lazy_navigation: lazyNavigationHint(state),
         ...(rehydrationPhase === undefined ? {} : { knowledge_rehydration: { phase: rehydrationPhase } }),
         ...(artifactInvalidations.length === 0 ? {} : { artifact_invalidations: artifactInvalidations.map(({ path, reason }) => ({ path, reason })) }),
         ...(recentTransitions.length === 0 ? {} : { recent_transitions: projectRecentForModel(recentTransitions) }),

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

@@ -138,11 +138,12 @@ export function inspectStateFlowContinuationProvenance(header, repositoryRoot) {
     const paths = sessionRuntimePaths(header.cwd, header.id, repositoryRoot, sessionKey);
     try {
         const config = readRegular(paths.config);
+        const runtimeSource = readRegular(paths.runtime);
         const meta = readRegular(paths.meta);
-        if (config === undefined && meta === undefined) {
+        if (config === undefined && runtimeSource === undefined && meta === undefined) {
             return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
         }
-        const runtime = parseSessionRuntime(config, meta, header.cwd, header.id);
+        const runtime = parseSessionRuntime(config, runtimeSource, header.cwd, header.id, meta);
         if (!runtime)
             return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
         if (!runtime.config.enabled)
@@ -156,7 +157,7 @@ export function inspectStateFlowContinuationProvenance(header, repositoryRoot) {
             validateTemporalState({ lineage: runtime.meta.lineage, scopes: { global, cwd, session } });
             return { stateFlow: { enabled: true, restorable: true }, reason: "exact file-only runtime cohort is restorable" };
         }
-        const runtimePath = relative(resolve(repositoryRoot), paths.meta);
+        const runtimePath = relative(resolve(repositoryRoot), runtimeSource === undefined ? paths.meta : paths.runtime);
         if (runtimePath.startsWith(".."))
             throw new Error("runtime provenance escapes repository");
         const owner = execFileSync("git", ["-C", repositoryRoot, "log", "-1", "--format=%H", "--", runtimePath], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();

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

@@ -37,6 +37,7 @@ export interface TemporalScopePaths {
 export declare function temporalScopePaths(cwd: string, sessionId: string, scope: StateScope, repositoryRoot: string, sessionKey?: string): TemporalScopePaths;
 export declare function sessionRuntimePaths(cwd: string, sessionId: string, repositoryRoot: string, sessionKey?: string): {
     config: string;
+    runtime: string;
     meta: string;
 };
 /** Unsupported state.json presence never becomes an anchored checkpoint. */