@llblab/pi-kit 0.11.1 → 0.11.3

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.11.3 - 2026-09-14
+
+- `Telegram Rich Sections And Queue Continuation`: Advances the exact Telegram pin to `0.45.9`, adding callback-targeted Native Rich Messages for companion sections and binding `/next` notices to the exact dispatchable queue item across concurrent readiness, admission, mutation, reordering, clearing, and transport changes.
+- `State Flow Inspection`: Advances the exact State Flow pin to `0.11.0`, adding read-only Global, CWD, Session, and Effective state inspection through the Telegram submenu with bounded collapsible Native Rich Message rendering. The package set, resource inventory, and explicit load order remain unchanged.
+
+## 0.11.2 - 2026-09-13
+
+- `State Flow Compaction And Resilience`: Advances the exact State Flow pin to `0.10.2`, replacing byte-based early-compaction readiness with public context-token usage, retaining the complete latest accepted iteration after shortening, accepting unambiguous non-terminal `final:false`, and strengthening bounded memory stewardship. The package set, resource inventory, and explicit load order remain unchanged.
+
 ## 0.11.1 - 2026-09-13
 
 - `State Flow Filesystem Recovery`: Advances the exact State Flow pin to `0.10.1`, adding transactional self-healing when a complete live global or CWD checkpoint pair disappears, exact private-session reconstruction from retained Git evidence, and precise fail-closed handling for partial or unsafe storage loss. The package set, resource inventory, and explicit load order remain unchanged.

package/README.md

@@ -14,8 +14,8 @@ Package links lead to the owning repositories for usage, documentation, issues,
 | [`@llblab/pi-clean-room`](https://github.com/llblab/pi-clean-room) | `0.1.1` | Isolated nested Pi TUI with explicitly selected extensions |
 | [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.9.4` | Compact Codex/Spark subscription-limit status |
 | [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.8.1` | Visible continuation scheduling and bounded worker Skills |
-| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.10.1` | Durable scoped state with native session compaction and exact publication |
-| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.45.8` | Telegram companion, queues, files, voice, controls, and Generative Apps guidance |
+| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.11.0` | Durable scoped state with native session compaction, exact publication, and read-only Telegram inspection |
+| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.45.9` | Telegram companion with exact queues, Rich section messages, 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-state-flow/AGENTS.md

@@ -25,14 +25,14 @@
 - 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.
 - Every accepted semantic change, including session-only and response-only changes, atomically updates affected checkpoint/tail pairs and temporal metadata and creates one immediate local Git commit when Git is available; each commit stages the complete non-ignored worktree delta (`git add -A` semantics, including manual deletions) before overlaying exact prepared State Flow outputs, respects `.gitignore`, keeps State Flow-owned active files under compare-and-swap protection, and synchronizes the caller-visible index to the committed tree. `remotePublication` is branch runtime policy: `turn-end` queues only the newest accepted target for asynchronous non-interactive push, `off` remains local-only, and `transition` preserves synchronous legacy behavior. Queue state is operational metadata beneath the Git common directory, not semantic history; require exact scalar-string commit targets/confirmations without coercion, destination identity, symlink-safe atomic CAS, descendant coalescing with lineage-rewrite recovery that retargets the live commit, cross-process worker leases, restart recovery, and truthful failure diagnostics. Revalidate dead lease ownership under the existing queue writer lock before removal; fresh exclusive creation and live self-PID/token release remain independent of that gate. Preserve malformed and non-regular lease records. Remote failure never rolls back accepted state or regenerates an answer. A repository with no remote is intentionally local-only; only Git executable `ENOENT` authorizes file-only mode.
 - Own asynchronous pushes per extension generation with a 15-second attempt budget and at most two seconds of shutdown waiting. On `session_shutdown`, cancel owned children and permanently fence old-generation queue writes and relaunch. Cancellation or elapsed waiting is not child-exit evidence: keep the lease until exit or proven spawn failure, and warn when cleanup remains unconfirmed. These deadlines govern asynchronous replication, not semantic acceptance or the compatibility synchronous mode.
-- Register `patch_state` as the sole model-authored semantic mutation protocol. It accepts optional fixed `global`, `cwd`, and `session` semantic patches plus optional `final:true`; require at least one scope or `final:true`, reject unknown fields, `final:false`, empty supplied scopes, material no-ops, and the retired `{scope, patch}` / `unchanged` grammar. Validate every supplied scope against one causal basis and publish it all-or-nothing with one identity, temporal boundary, and durable cohort. Never accept model-authored `response`.
+- Register `patch_state` as the sole model-authored semantic mutation protocol. Its canonical model-facing grammar accepts optional fixed `global`, `cwd`, and `session` semantic patches plus optional `final:true`; require at least one scope or `final:true`, reject unknown fields, empty supplied scopes, material no-ops, and the retired `{scope, patch}` / `unchanged` grammar. As an unadvertised graceful-degradation layer, normalize only unambiguous Boolean-like `final` primitives before schema validation, treat false-like values as non-terminal intent, and accept a false-only call as an inert no-op without a transition or diagnostic; never apply raw JavaScript truthiness. Validate every supplied scope against one causal basis and publish it all-or-nothing with one identity, temporal boundary, and durable cohort. Never accept model-authored `response`.
 - Treat every semantic `patch_state` as a strict inference barrier. Give it sequential execution mode; find the matching synchronized assistant through public parent traversal from the selected leaf without constructing a full branch during tool preflight; require exactly one `patch_state` call in that response and block every sibling tool call before execution. Every enabled iteration begins terminal-ineligible; only a successful call containing `final:true` latches eligibility for the next accepted `turn_end`, without stopping later reasoning, tools, or patches. If a terminal draft ends before eligibility, preserve it as the runtime-owned response at that `turn_end` and start at most two same-run fallback turns whose only purpose is the `final:true` patch; an eligible draft whose final validation fails after a later acquisition follows the same path. Fallback turns never enter `response`, and their only instruction is to apply `patch_state` with any durable changes and `final:true`, or `{final:true}` alone. A successful fallback closes resolution with the preserved answer intact; two failed fallbacks close the iteration with the preserved answer and current state plus one bounded warning and a finalization diagnostic. Failed patch calls do not consume fallback turns. A subsequent legal patch remains possible, and only an accepted ordinary answer is reconciled.
 - Reconcile `response` only from the actually accepted ordinary assistant answer at `turn_end`; it remains runtime-owned. State Flow has no terminal HTML-comment mutation protocol and does not parse generic service comments. The first terminal draft that cannot be reconciled is preserved as the iteration response rather than discarded; fallback turns during pending resolution never reach `response`. Other extensions retain ownership of their own comments and output handling.
 - Treat terminal state as a decision-relevant handoff, not narration: retain source-addressed reusable operational knowledge in `artifacts`; compile stable requirements, confirmed decisions, rejected approaches, and interface commitments into `contract`; retain observations, validation, failures, current domain state, unresolved work, interaction consequences, and exact continuation in `working`. Preserve relevant completed prerequisites and verified outcomes while removing obsolete progress narration; reconcile only information affected by the run and relevant existing commitments, not every scope or repository surface.
 - Preserve active constraints, unresolved questions, consequential negative results, and the next discriminating check before compression. Distinguish observations, user requirements, assistant decisions, and hypotheses; do not promote assistant conclusions to user requirements. Retain useful source locators and validity conditions for consequential facts without mandatory per-value metadata. Keep rejection reasons and reconsideration conditions. Reconcile contradictions through evidence or user clarification instead of silently overwriting established constraints or observations; retain unresolved conflicts and decision-relevant hypotheses as uncertain. These are protocol obligations, not deterministic semantic validation gates.
 - Treat `working` as last observations, not a live workspace. Revalidate volatile facts before consequential actions; after interruption or branch navigation inspect relevant external effects before repeating operations. Failed state commits and restored memory do not undo tool effects. Missing evidence proves neither success nor absence of effects: retain uncertainty and the next check. Keep revalidation targeted, without action ledgers or runtime freshness/rollback guarantees.
 - Treat each successful `SKILL.md` read as CWD artifact acquisition using the finalized tool-execution arguments after mutable interception: require a non-empty compiler output in the next `patch_state` call under `cwd.artifacts[exactReadPath]` with `description`, `kind: "skill"`, and a flexible non-empty `compilation` object; hash the executed source bytes and record runtime-owned `sourceHash` plus `skill-artifact-v1` `compilerRevision` in the CWD provenance registry; reject missing, unhashable, malformed, or forged freshness data; replace the complete prior Skill artifact and its provenance entry on refresh so obsolete evidence cannot survive. `contract.compiled_skills` is retired and rejected; migrate useful legacy entries into artifacts while preserving behavior and marking fallback hashes unverified when the source is unavailable.
-- Make the model audit and optimize complete state at every handoff: reorganize inefficient structure, merge fragmented facts, compress history into conclusions, and delete stale, completed, redundant, or low-value keys while preserving active commitments and evidence.
+- Make state stewardship an ordinary model responsibility without a background loop or gratuitous full-state rewrite. Every handoff curates touched and obviously stale or mis-scoped visible branches: place new knowledge at the narrowest valid scope, merge fragmented facts, compress history into conclusions, and delete stale, completed, redundant, or low-value keys while preserving active commitments and evidence. At a completed feature/release/campaign, project switch, or active-version change, require one bounded scoped reconciliation before terminal completion; use targeted `read_state` when ownership is not visible, then write and verify the destination before deleting and verifying the source. Global is only established cross-project/user/environment knowledge, CWD is reusable project truth, and session is branch/run continuation.
 - Accept omitted semantic fields inside each supplied scope patch, but reject empty supplied scopes; when no state change is needed require explicit `{final:true}` without inventing bookkeeping. This final-only call changes only ephemeral terminal eligibility and creates no semantic transition, identity, temporal step, or Git commit. Always require an accepted non-empty answer, which runtime owns as session `response`. A changed response is a semantic transition; identical complete semantic state finalizes lifecycle without a patch, identity, or temporal step. Semantic usefulness and optimization remain protocol-owned because deterministic validation cannot prove them.
 - 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.
@@ -43,7 +43,7 @@
 - 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.
-- After a sufficiently large accepted non-bootstrap run settles with no pending input, State Flow may request native manual compaction under a generation-private marker. Keep the final accepted assistant entry, store only revision/step identity in details, and never duplicate state in the summary. 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.
+- 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.

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

@@ -2,13 +2,6 @@
 
 Completed release work belongs in [CHANGELOG.md](CHANGELOG.md).
 
-## 0.10.1: Filesystem self-healing and graceful degradation
-
-- **Outcome:** Treat safely interpretable absence as recoverable or optional while keeping partial, malformed, contradictory, and authority-losing evidence fail-closed at the smallest affected capability. [`docs/filesystem-recovery.md`](docs/filesystem-recovery.md) owns the durable cohort classification.
-- **Accepted candidate:** Shared Git/file repair, exact session authority, provenance/external degradation, operational persistence, concurrent CAS and native Pi response/reload/resume witnesses are complete. A focused release review found and corrected repeated stale-target refusal; the runtime now refreshes the empty basis after one conflict and accepts a later patch through ordinary publication.
-- **Validation:** The complete 0.84.4 repository profile passes 442/442 with typecheck/import-check. On the supported 0.85.1 stack, all 16 affected codec/runtime witnesses, the real Pi lifecycle witness and typecheck pass. Package 0.10.1 contains 46 files including the recovery guide and excludes tests/benchmarks; context/DAG validation report zero errors.
-- [ ] **Release gate:** Commit, push, tag, npm/GitHub publication, and any Pi Kit pin update require separate explicit release authorization.
-
 ## Candidate evolution
 
 - [ ] **Read-only global bootstrap layer:** Project the existing global materialization into enabled and non-enabled sessions by default, so even one-shot work starts carrying established cross-project facts, preferences, routing, and conventions. The global scope is the highest-value, lowest-cost half of the memory, while writing carries the protocol and curation tax; making the read side unconditional gives continuity without enabling mutation.

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

@@ -4,6 +4,16 @@
 
 ## Unreleased
 
+## 0.11.0: Telegram state inspection
+
+- `Telegram inspection`: The State Flow submenu now offers `👁 Show state` with Global, CWD, Session, and Effective choices. Selecting one scope sends exactly that projected materialized slice as a standalone Telegram Native Rich Message whose semantic fields use collapsible `details` and JSON `pre` blocks; inspection is read-only and the optional adapter remains fail-open without a compatible pi-telegram membrane.
+
+## 0.10.2: Token-guided compaction and patch resilience
+
+- `Compaction readiness`: Early State Flow compaction now uses Pi's public context-token estimate with a 24,000-token floor instead of serialized-entry bytes, skipping unknown or short contexts without invoking native compaction. Successful shortening retains the complete latest accepted user iteration rather than only its final answer, while durable state and append-only session history remain intact.
+- `Patch resilience`: `patch_state` now quietly normalizes a bounded Boolean-like compatibility set for `final`. Explicit false can accompany an atomic semantic patch or stand alone as an inert non-terminal no-op without clearing eligibility, creating history, or producing an invalid-patch diagnostic; model-facing guidance still teaches only omission and `final:true`, and ambiguous values remain invalid.
+- `Memory stewardship`: Runtime guidance, tool prompts, project protocol, architecture/usage docs, and the bundled memory Skill now require narrowest-scope placement and touched-branch cleanup on ordinary handoffs, plus one bounded ownership/obsolescence reconciliation when a feature, release, campaign, project, or active version changes. Scope migration remains targeted, verified, non-background, and destination-first.
+
 ## 0.10.1: Filesystem self-healing and graceful degradation
 
 - `Shared scopes`: A wholly absent live global/CWD checkpoint-tail pair is now distinct from partial storage. Untouched publication adopts empty current reality at a fresh origin and transactionally materializes the canonical pair without resurrecting selected values; a patch targeting the disappeared scope fails precisely for reinference. Git/file backends retain publication locks, CAS, full cold history and concurrent-writer exclusion.

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

@@ -53,7 +53,7 @@ Continue working normally. The agent receives the state protocol and uses `patch
 
 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).
 
-With `pi-telegram` installed, its main menu also exposes the same Start/Stop controls.
+With a compatible `pi-telegram` installed, its main menu also exposes the same Start/Stop controls and a `👁 Show state` chooser for Global, CWD, Session, or Effective memory. Selecting one scope sends exactly that materialized slice as a standalone native Rich Message with collapsible semantic fields; inspection is read-only and does not create a State Flow transition.
 
 ## What carries forward
 

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

@@ -89,7 +89,7 @@ The existing native passive-stop marker stores the stop timestamp and an optiona
 
 The current user specification stays at user authority and appears only in synthetic user runtime context. State is fallible assistant-produced data. Completed trajectories leave model context at user-run boundaries, while Pi's full JSONL trace remains inspectable.
 
-After a sufficiently large accepted non-bootstrap run settles with no queued input, State Flow may request a native manual compaction under a generation-private marker. Pi still owns preparation and admits the boundary only when its configured `keepRecentTokens` leaves compactable history. The extension supplies no model-generated summary or state body: it keeps the final accepted assistant entry and records the exact durable revision/step in compaction details. `buildContextEntries()` then omits the older completed prefix for active context and resume rendering while the append-only JSONL/tree remains intact. Small histories, foreign custom context in the proposed prefix, stale selection, Stop/bootstrap/fallback/error/abort and pending input do not produce this boundary. User manual and native threshold/overflow compaction remain unmodified; in-progress work not yet accepted into State Flow stays under Pi's native compaction contract.
+After an accepted non-bootstrap run settles with no queued input, State Flow may request native manual compaction under a generation-private marker when public `getContextUsage()` reports at least 24,000 tokens. This token signal replaces the former serialized-byte proxy and provides a modest margin above Pi's default 20,000-token retained suffix; Pi still owns preparation and may benignly decline when custom settings leave no compactable prefix. The extension supplies no model-generated summary or state body: it keeps the complete latest accepted user iteration and records the exact durable revision/step in compaction details. `buildContextEntries()` then omits the older completed prefix for active context and resume rendering while the append-only JSONL/tree remains intact. Unknown or smaller usage, foreign custom context in the removed prefix, stale selection, Stop/bootstrap/fallback/error/abort and pending input do not produce this boundary. User manual and native threshold/overflow compaction remain unmodified; in-progress work not yet accepted into State Flow stays under Pi's native compaction contract.
 
 The Pi adapter passes its raw cached scope overlay to `runtimeContextMessage`, which owns model sanitization of the current state. It does not pre-project that input. After anchor selection, `currentRunTrajectory` selects retained messages into one array without copying discarded ordinary prefixes: foreign custom messages survive at any position, while ordinary messages survive only from the selected run anchor and State Flow's private feedback is excluded. The necessary foreign-context scan and Pi's earlier native-message clone remain history-dependent. See [context-cost evidence](performance.md#context-projection-and-trajectory-selection).
 
@@ -196,7 +196,7 @@ Both [tested Pi SDKs](compatibility.md) choose or create `SessionManager` before
 
 ### Model tools
 
-`patch_state` accepts optional fixed `global`, `cwd`, and `session` semantic patches plus optional `final:true`. At least one scope or `final:true` is required. Supplied scopes contain only object-valued `artifacts`, `contract`, and `working`; omitted fields preserve their values, recursive object merge updates them, arrays/primitives replace, and nested object-key `null` deletes. Materialized null, empty supplied scopes, material no-ops, unknown top-level fields, model-authored `response`, and retired grammars are rejected. A final-only call changes ephemeral eligibility, not semantic history.
+`patch_state` accepts optional fixed `global`, `cwd`, and `session` semantic patches plus optional `final:true`. At least one scope or `final:true` is required in the canonical model contract. Supplied scopes contain only object-valued `artifacts`, `contract`, and `working`; omitted fields preserve their values, recursive object merge updates them, arrays/primitives replace, and nested object-key `null` deletes. Materialized null, empty supplied scopes, material no-ops, unknown top-level fields, model-authored `response`, and retired grammars are rejected. A final-only true call changes ephemeral eligibility, not semantic history. Runtime quietly accepts unambiguous false-like `final` input as non-terminal intent, including an inert false-only call, but this compatibility layer is deliberately absent from model guidance.
 
 ```json
 {"session":{"working":{"next":"Verify the corrected behavior"}},"final":true}
@@ -208,7 +208,7 @@ Both [tested Pi SDKs](compatibility.md) choose or create `SessionManager` before
 {"offset":1,"scope":"cwd"}
 ```
 
-Both tools follow branch enablement and host restrictions. The patch barrier also blocks reader siblings. These tools do not impose project schemas or state-size caps; semantic usefulness, scope choice, and compression remain model responsibilities.
+Both tools follow branch enablement and host restrictions. The patch barrier also blocks reader siblings. These tools do not impose project schemas or state-size caps; semantic usefulness, scope choice, and compression remain model responsibilities. Every ordinary handoff reconciles touched and obviously stale visible state. Feature/release/campaign completion, project switches, and active-version changes additionally require one bounded scoped ownership and obsolescence pass: global retains only established cross-project/user/environment knowledge, CWD owns reusable project truth, and session owns branch/run continuation. Scope movement uses targeted reads and destination verification before source deletion rather than an automatic maintenance loop.
 
 ### Embedding
 

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

@@ -12,7 +12,7 @@ For the concept and installation, start with the [README](../README.md). This gu
 - **Abort inference:** Stops generation while already accepted patches remain durable for continued work and corrected direction in the same session. It does not roll back memory or require immediate remote replication.
 - **Stop:** Disables semantic tools and updates immediately on the selected branch; ordinary prompt composition resumes with the next user run. It preserves state and does not create a semantic transition or change automatic-start policy for future new sessions.
 - **Continue after Stop:** The same physical session retains a frozen state handoff, any interrupted current request and tool trajectory (including late results), and post-stop conversation. Completed earlier conversation stays excluded, while other extensions' custom context survives. Reload/resume/tree preserve this projection; new/forked physical sessions do not inherit it. Active restart uses it for one bootstrap run.
-- **Completed-history compaction:** After a sufficiently large accepted run settles without queued input, State Flow asks Pi for a native compaction boundary. No extra model summary is requested; Pi keeps the final accepted answer in active history and retains the complete append-only JSONL/tree. On resume, native `buildContextEntries()` and TUI rendering omit the older completed prefix. Pi may decline small histories. Foreign custom context, bootstrap/fallback/abort/error, Stop and pending input prevent State Flow-owned shortening; ordinary manual/threshold/overflow compaction remains native and may preserve unfinished work not yet patched into memory.
+- **Completed-history compaction:** After an accepted run settles without queued input, State Flow asks Pi for a native compaction boundary only when public context usage reaches 24,000 tokens. No extra model summary is requested; Pi keeps the complete latest user iteration—from its request through tools and final answer—in active history and retains the complete append-only JSONL/tree. On resume, native `buildContextEntries()` and TUI rendering omit the older completed prefix. Unknown or smaller usage skips the request, and custom Pi retention settings may still decline it benignly. Foreign custom context in the removed prefix, bootstrap/fallback/abort/error, Stop and pending input prevent State Flow-owned shortening; ordinary manual/threshold/overflow compaction remains native and may preserve unfinished work not yet patched into memory.
 
 State Flow does not undo tool effects. After interruption or returning to an older branch, check the relevant workspace or external system before repeating consequential operations. Restored memory is not restored reality.
 
@@ -139,4 +139,4 @@ The agent should use sufficient materialized knowledge before rereading files. R
 
 Knowledge discovery finds regular lowercase `*.md` beneath its configured root, hashes opaque bytes, and skips symlinks. Only confirmed missing Markdown paths within an available root are pruned; external/non-Markdown artifacts and state under a missing whole root are preserved. An unavailable root makes freshness unknown in status. Successful reads of stale ordinary candidates require same-path global compilation; Skill reads require CWD compilation. The runtime owns provenance: model patches cannot write or delete individual freshness fields, including legacy spellings. Existing legacy entries remain readable and semantically editable. Missing freshness evidence means unknown-but-usable, not proof that a source was acquired.
 
-The optional `state-flow-memory` Skill handles explicit bounded curation and external promotion. It is not a background maintenance loop. Promotion must verify the destination before removing the only accepted source copy. Artifact/compiler details and model-tool contracts belong in the [architecture](architecture.md#artifact-routing).
+The optional `state-flow-memory` Skill handles explicit bounded curation, required feature/release/project phase-boundary reconciliation, and external promotion. Ordinary handoffs clean only touched and obviously stale visible branches; the Skill supplies the fuller scoped migration procedure when a phase boundary or explicit request earns it. It is not a background maintenance loop. Promotion must verify the destination before removing the only accepted source copy. Artifact/compiler details and model-tool contracts belong in the [architecture](architecture.md#artifact-routing).

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

@@ -1,7 +1,8 @@
 import type { CompactionResult } from "@earendil-works/pi-coding-agent";
 
 export const STATE_FLOW_COMPACTION_SUMMARY = "State Flow accepted the completed work before this boundary. Current memory is restored from its durable revision and projected separately; use the retained native entries for subsequent work.";
-export const STATE_FLOW_COMPACTION_MIN_ACTIVE_BYTES = 80_000;
+/** A modest margin above Pi's default 20k retained suffix absorbs estimation drift. */
+export const STATE_FLOW_COMPACTION_MIN_CONTEXT_TOKENS = 24_000;
 
 export interface StateFlowCompactionDetails {
 	version: 1;
@@ -29,7 +30,13 @@ function stateFlowEntry(entry: ActiveEntry): boolean {
 		&& entry.customType.startsWith("state-flow-");
 }
 
-/** Select one completed native boundary without hiding foreign extension context. */
+export function shouldRequestStateFlowCompaction(usage: { tokens: number | null } | undefined): boolean {
+	return typeof usage?.tokens === "number"
+		&& Number.isFinite(usage.tokens)
+		&& usage.tokens >= STATE_FLOW_COMPACTION_MIN_CONTEXT_TOKENS;
+}
+
+/** Retain the complete latest accepted user iteration without hiding foreign extension context. */
 export function planStateFlowCompaction(
 	entries: readonly ActiveEntry[],
 	revision: string,
@@ -37,12 +44,12 @@ export function planStateFlowCompaction(
 ): StateFlowCompactionPlan | undefined {
 	if (!/^[0-9a-f]{40,64}$/.test(revision) && !/^file:[0-9a-f]{64}$/.test(revision)) return undefined;
 	if (!Number.isSafeInteger(step) || step < 0 || entries.length === 0) return undefined;
-	if (Buffer.byteLength(JSON.stringify(entries), "utf8") < STATE_FLOW_COMPACTION_MIN_ACTIVE_BYTES) return undefined;
-	const keep = entries.findLastIndex((entry) => entry.type === "message"
-		&& entry.message?.role === "assistant"
-		&& entry.message.stopReason !== "aborted"
-		&& entry.message.stopReason !== "error"
-		&& entry.message.stopReason !== "length");
+	const terminal = entries.findLastIndex((entry) => entry.type === "message" && entry.message?.role === "assistant");
+	if (terminal < 0 || entries[terminal]?.message?.stopReason === "aborted"
+		|| entries[terminal]?.message?.stopReason === "error"
+		|| entries[terminal]?.message?.stopReason === "length") return undefined;
+	let keep = terminal;
+	while (keep >= 0 && !(entries[keep]?.type === "message" && entries[keep]?.message?.role === "user")) keep--;
 	if (keep < 0) return undefined;
 	if (entries.slice(0, keep).some((entry) => entry.type === "custom" && !stateFlowEntry(entry))) return undefined;
 	const firstKeptEntryId = entries[keep]?.id;

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

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import { StringEnum, Type } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { assistantToolCallCount, finalizedAssistantResponse, stateFlowProtocol } from "./terminal.ts";
+import { assistantToolCallCount, finalizedAssistantResponse, stateFlowProtocol } from "./protocol.ts";
 import { createPassiveContinuation, currentRunTrajectory, passiveContinuationMessages, runtimeContextMessage, VALIDATION_MESSAGE_TYPE, withoutPrivateValidation, type PassiveContinuation } from "./context.ts";
 import { ArtifactReadTracker } from "./acquisition.ts";
 import { loadStateFlowConfig } from "./config.ts";
@@ -12,7 +12,7 @@ import { isAbsolute, relative, resolve, sep } from "node:path";
 import { SkillReadTracker } from "./skills.ts";
 import { emptySnapshot, migrationFailure, persistableSnapshot, RevisionUnavailableError, type Snapshot } from "./snapshot.ts";
 import { readNativeSessionHeader } from "./continuation.ts";
-import { MissingSessionRuntimeError, TemporalRuntime, type RuntimePublication } from "./runtime.ts";
+import { MissingSessionRuntimeError, SharedScopeRemovalConflictError, TemporalRuntime, type RuntimePublication } from "./runtime.ts";
 import { emptyState, overlayStates, projectStateForModel, type AtomicScopePatches, type MaterializedState, type ScopedStates, type StateScope } from "./state.ts";
 import { commitScopedTransition, stageAtomicScopePatches, stageScopedTransition, validateFinalEligibility, type StagedScopedTransition } from "./transition.ts";
 import { discoverSnapshotData, hasPriorConversation, isNewSession, SNAPSHOT_ENTRY_TYPE } from "./session.ts";
@@ -40,7 +40,7 @@ import {
 	planArtifactInvalidation,
 	type ArtifactInvalidationRequest,
 } from "./artifact.ts";
-import { planStateFlowCompaction, stateFlowCompactionResult, type StateFlowCompactionPlan } from "./compaction.ts";
+import { planStateFlowCompaction, shouldRequestStateFlowCompaction, stateFlowCompactionResult, type StateFlowCompactionPlan } from "./compaction.ts";
 
 export interface StateFlowExtensionOptions {
 	agentDir?: string;
@@ -56,6 +56,20 @@ export const MAX_FALLBACK_ATTEMPTS: number = 2;
 const PASSIVE_STOP_ENTRY_TYPE = "state-flow-passive-stop";
 const PUBLICATION_SHUTDOWN_WAIT_MS = 2_000;
 
+/** Normalize a bounded compatibility superset without advertising aliases in the model-facing contract. */
+export function normalizePatchStateArguments(args: unknown): any {
+	if (!isObject(args) || !Object.hasOwn(args, "final")) return args;
+	const value = args.final;
+	let final: boolean;
+	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 a failed tool invocation visually separated from its rendered error without changing error semantics. */
 function separatedFailure(error: unknown): Error {
 	const message = error instanceof Error ? error.message : String(error);
@@ -281,16 +295,22 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 
 	function commitStage(stage: StagedScopedTransition, ctx: ExtensionContext, finalizeRun: boolean): boolean {
 		const acquiredArtifactPaths = new Set(artifactReads.successful.keys());
-		const committed = commitScopedTransition(snapshot, scopeStates, stage, (accepted, nextSnapshot) => {
-			if (!runtime?.view) throw new Error("Temporal State Flow runtime is unavailable; reload before publishing");
-			const mode = nextSnapshot.meta.remotePublication?.mode ?? "transition";
-			const publication = runtime.publish(nextSnapshot, accepted !== undefined, accepted, {
-				pushRemote: mode === "transition",
-				provenance: stage.provenanceUpdates,
-			});
-			if (publication?.commit && mode === "turn-end") turnPublicationTarget = publication.commit;
-			if (publication) recordPublication(publication, ctx);
-		}, runtime!.causalBasis(), { finalizeRun });
+		let committed: boolean;
+		try {
+			committed = commitScopedTransition(snapshot, scopeStates, stage, (accepted, nextSnapshot) => {
+				if (!runtime?.view) throw new Error("Temporal State Flow runtime is unavailable; reload before publishing");
+				const mode = nextSnapshot.meta.remotePublication?.mode ?? "transition";
+				const publication = runtime.publish(nextSnapshot, accepted !== undefined, accepted, {
+					pushRemote: mode === "transition",
+					provenance: stage.provenanceUpdates,
+				});
+				if (publication?.commit && mode === "turn-end") turnPublicationTarget = publication.commit;
+				if (publication) recordPublication(publication, ctx);
+			}, runtime!.causalBasis(), { finalizeRun });
+		} catch (error) {
+			if (error instanceof SharedScopeRemovalConflictError) installScopeStates();
+			throw error;
+		}
 		if (!committed) return false;
 		installScopeStates();
 		// A preserved primary response commits mid-run; pending acquisition obligations must
@@ -773,6 +793,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		promptSnippet: "Atomically patch global/cwd/session; final:true permits a later turn_end",
 		promptGuidelines: [
 			"Use patch_state for durable semantic changes. Before a final answer, make the iteration terminal-eligible with final:true, optionally alongside atomic global/cwd/session patches.",
+			"Use patch_state as reconciliation, not append-only notes: place new knowledge at the narrowest valid scope and remove superseded or completed state from touched branches.",
 			"Call patch_state alone in an assistant response; after its acknowledgement, further reasoning, tools, and later patch_state calls remain allowed.",
 		],
 		executionMode: "sequential",
@@ -782,6 +803,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			session: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Optional session semantic patch" })),
 			final: Type.Optional(Type.Boolean({ description: "Set exactly true to permit this iteration to finish at a later turn_end" })),
 		}, { additionalProperties: false }),
+		prepareArguments: normalizePatchStateArguments,
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {
 			try {
 				if (!snapshot.config.enabled) throw new Error("State Flow is disabled on this session branch");
@@ -791,7 +813,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				for (const key of Object.keys(params)) {
 					if (!allowed.has(key)) throw new Error(`patch_state does not accept field ${key}`);
 				}
-				if (Object.hasOwn(params, "final") && params.final !== true) throw new Error("patch_state final must be exactly true when supplied");
+				if (Object.hasOwn(params, "final") && typeof params.final !== "boolean") throw new Error("patch_state final must be a Boolean when supplied");
 				const patches: AtomicScopePatches = {};
 				for (const scope of ["global", "cwd", "session"] as const) {
 					if (!Object.hasOwn(params, scope)) continue;
@@ -802,6 +824,9 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				}
 				const scopes = Object.keys(patches) as StateScope[];
 				if (scopes.length === 0) {
+					if (params.final === false) {
+						return { content: [{ type: "text", text: "\nState unchanged; iteration remains non-terminal." }], details: { final: false } };
+					}
 					if (params.final !== true) throw new Error('patch_state requires at least one scope patch or {"final":true}');
 					validateFinalEligibility(scopeStates, skillReads.successful.values(), runtime!.causalBasis(), artifactReads.successful.values());
 					terminalEligible = true;
@@ -976,6 +1001,11 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				bootstrap: snapshot.meta.bootstrap === true,
 				startPending: telegramStartPending,
 			}),
+			state: (scope) => projectStateForModel(
+				scope === "effective"
+					? overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)
+					: scopeStates[scope],
+			),
 			canStartNow: () => activeContext === undefined || activeContext.isIdle(),
 			start: () => {
 				if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
@@ -1162,7 +1192,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		}
 		if (snapshot.meta.remotePublication?.mode === "turn-end") launchPublicationWorker();
 		if (!completedRunAccepted || compactionStopped || !snapshot.config.enabled || snapshot.meta.bootstrap || resolutionPending
-			|| compactionInFlight || !ctx.isIdle() || ctx.hasPendingMessages() || !snapshot.meta.durableBase) return;
+			|| compactionInFlight || !ctx.isIdle() || ctx.hasPendingMessages() || !snapshot.meta.durableBase
+			|| !shouldRequestStateFlowCompaction(ctx.getContextUsage())) return;
 		completedRunAccepted = false;
 		const plan = planStateFlowCompaction(ctx.sessionManager.buildContextEntries(), snapshot.meta.durableBase, snapshot.meta.step);
 		if (!plan) return;

package/node_modules/@llblab/pi-state-flow/lib/{terminal.ts → protocol.ts}

@@ -3,7 +3,7 @@ import type { AgentMessage } from "@earendil-works/pi-agent-core";
 export type { StateDocument } from "./state.ts";
 
 function baselineMemoryProtocol(): string {
-	return "BASELINE MEMORY: State Flow owns durable memory while enabled. Global is always available for established cross-project/user/environment knowledge; preserve information at the narrowest correct scope. Exclude secrets, raw history, transient progress, speculative clutter, and unsupported assertions; retain explicitly uncertain hypotheses only when they affect an open decision.";
+	return "BASELINE MEMORY: State Flow owns durable memory while enabled. Global is only for established cross-project/user/environment knowledge, cwd for reusable project truth, and session for branch/run continuation. Treat every patch as reconciliation rather than append-only notes: place new knowledge at the narrowest valid scope, reconsider touched branches, merge superseded fragments, and remove obsolete progress. Exclude secrets, raw history, transient progress, speculative clutter, and unsupported assertions; retain explicitly uncertain hypotheses only when they affect an open decision.";
 }
 
 /** The compact model-facing contract. Semantic writes never travel through terminal prose. */
@@ -31,7 +31,7 @@ ${baselineMemoryProtocol()}
 
 PATCH: Fields are optional global, cwd, session semantic patches and optional final:true. At least one scope or final:true is required. Supplied scopes commit atomically; empty or materially no-op scopes must be omitted. Patches use only object-valued artifacts, contract, and working; omitted fields preserve. Never patch runtime config/meta/response. Recursive merge; arrays/primitives replace; nested null deletes. Materialized null is forbidden.
 
-HANDOFF: Preserve active commitments, unresolved questions, consequential results, and exact continuation. Distinguish user requirements, confirmed decisions, observations, assistant conclusions, and hypotheses. Remove stale narration and never invent memory changes.
+HANDOFF: Preserve active commitments, unresolved questions, consequential results, and exact continuation. Distinguish user requirements, confirmed decisions, observations, assistant conclusions, and hypotheses. Curate touched and obviously stale or mis-scoped visible state before every final handoff. When a feature/release/campaign closes or the active project/version changes, perform one bounded scoped reconciliation: remove obsolete prior-work state, retain only still-operative consequences, and use targeted read_state plus destination-verify-source-delete when ownership must move. Never invent memory changes or rewrite unrelated state for style.
 
 ACQUISITION: Start from materialized state. Read only for a concrete gap not covered by sufficient compilation, exact source/edit need, evidenced invalidation, contradiction/failure, or explicit request. Changed hashes require rereading.
 

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

@@ -39,13 +39,22 @@ function targetScopeConflict(scopes: readonly StateScope[]): Error {
 	return new Error(`State Flow cannot publish the ${labels.join(" and ")} patches because the live ${labels.join(" and ")} states advanced after this transition's selected basis. Refresh or reconcile the target scopes before retrying.`);
 }
 
+/** A targeted removed scope was deliberately adopted as empty before refusing the stale semantic patch. */
+export class SharedScopeRemovalConflictError extends Error {
+	readonly scopes: readonly StateScope[];
+	constructor(scopes: readonly StateScope[]) {
+		const labels = scopes.map(scopeLabel);
+		super(labels.length === 1
+			? `State Flow cannot publish the ${labels[0]} patch because the live ${labels[0]} scope was removed after this transition's selected basis. Refresh or reconcile the target scope before retrying.`
+			: `State Flow cannot publish the ${labels.join(" and ")} patches because the live ${labels.join(" and ")} scopes were removed after this transition's selected basis. Refresh or reconcile the target scopes before retrying.`);
+		this.name = "SharedScopeRemovalConflictError";
+		this.scopes = Object.freeze([...scopes]);
+	}
+}
+
 /** Disappearance invalidates a selected write target even though untouched scopes can adopt empty reality. */
 function removedTargetScopeConflict(scopes: readonly StateScope[]): Error {
-	const labels = scopes.map(scopeLabel);
-	if (labels.length === 1) {
-		return new Error(`State Flow cannot publish the ${labels[0]} patch because the live ${labels[0]} scope was removed after this transition's selected basis. Refresh or reconcile the target scope before retrying.`);
-	}
-	return new Error(`State Flow cannot publish the ${labels.join(" and ")} patches because the live ${labels.join(" and ")} scopes were removed after this transition's selected basis. Refresh or reconcile the target scopes before retrying.`);
+	return new SharedScopeRemovalConflictError(scopes);
 }
 
 function freshEmptyScopeStream(scope: StateScope, origin: string): ScopeStream {

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

@@ -16,6 +16,24 @@ export interface StateFlowTelegramSnapshot {
 	startPending: boolean;
 }
 
+export type StateFlowTelegramScope = "global" | "cwd" | "session" | "effective";
+
+export interface StateFlowTelegramState {
+	artifacts: Record<string, unknown>;
+	contract: Record<string, unknown>;
+	working: Record<string, unknown>;
+	response: string;
+}
+
+export type StateFlowTelegramRichBlock =
+	| { type: "pre"; text: string; language?: string }
+	| { type: "details"; summary: string | { type: "bold" | "code"; text: string }; blocks: StateFlowTelegramRichBlock[]; is_open?: true };
+
+export interface StateFlowTelegramRichMessage {
+	blocks: StateFlowTelegramRichBlock[];
+	skip_entity_detection?: boolean;
+}
+
 export interface StateFlowTelegramButton {
 	text: string;
 	callback_data: string;
@@ -30,6 +48,7 @@ export interface StateFlowTelegramView {
 export interface StateFlowTelegramSectionContext {
 	callbackData(action: string, payload?: string): string;
 	edit(view: StateFlowTelegramView): Promise<void>;
+	openRich(message: StateFlowTelegramRichMessage): Promise<void>;
 	answerCallback(text?: string): Promise<void>;
 }
 
@@ -61,6 +80,7 @@ export interface StateFlowTelegramControlResult {
 
 export interface StateFlowTelegramPort {
 	snapshot(): StateFlowTelegramSnapshot;
+	state(scope: StateFlowTelegramScope): StateFlowTelegramState;
 	canStartNow(): boolean;
 	start(): StateFlowTelegramControlResult;
 	stop(): StateFlowTelegramControlResult;
@@ -103,10 +123,72 @@ export function buildStateFlowSectionView(
 	return {
 		text: [formatStateFlowSectionHeader(snapshot), "", STATE_FLOW_SECTION_HELP].join("\n"),
 		parseMode: "html",
-		replyMarkup: { inline_keyboard: [[action]] },
+		replyMarkup: { inline_keyboard: [
+			[{ text: "👁 Show state", callback_data: callbackData("show-state") }],
+			[action],
+		] },
+	};
+}
+
+export function buildStateFlowScopeChooser(callbackData: (action: string, payload?: string) => string): StateFlowTelegramView {
+	return {
+		text: "<b>👁 Show state:</b>",
+		parseMode: "html",
+		replyMarkup: { inline_keyboard: [
+			["global", "cwd"].map((scope) => ({ text: scope === "global" ? "Global" : "CWD", callback_data: callbackData("inspect", scope) })),
+			["session", "effective"].map((scope) => ({ text: scope === "session" ? "Session" : "Effective", callback_data: callbackData("inspect", scope) })),
+		] },
+	};
+}
+
+// The complete message serializes each preformatted field one additional time;
+// 3,000 leaves safe headroom for worst-case JSON escaping across all four fields.
+const STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS = 3_000;
+
+function renderStateFlowTelegramField(value: unknown): string {
+	const json = JSON.stringify(value, null, 2);
+	if (json.length <= STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS) return json;
+	let low = 0;
+	let high = json.length;
+	let rendered = "";
+	while (low <= high) {
+		const length = Math.floor((low + high) / 2);
+		const candidate = JSON.stringify({
+			truncated: true,
+			preview: json.slice(0, length),
+			omittedChars: json.length - length,
+		}, null, 2);
+		if (candidate.length <= STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS) {
+			rendered = candidate;
+			low = length + 1;
+		} else {
+			high = length - 1;
+		}
+	}
+	return rendered;
+}
+
+export function renderStateFlowRichState(scope: StateFlowTelegramScope, state: StateFlowTelegramState): StateFlowTelegramRichMessage {
+	const title = scope === "cwd" ? "CWD" : `${scope[0].toUpperCase()}${scope.slice(1)}`;
+	const fields = ["artifacts", "contract", "working", "response"] as const;
+	return {
+		blocks: [{
+			type: "details",
+			summary: { type: "bold", text: title },
+			blocks: fields.map((field) => ({
+				type: "details",
+				summary: { type: "code", text: field },
+				blocks: [{ type: "pre", language: "json", text: renderStateFlowTelegramField(state[field]) }],
+			})),
+		}],
+		skip_entity_detection: true,
 	};
 }
 
+function isStateFlowTelegramScope(value: string): value is StateFlowTelegramScope {
+	return value === "global" || value === "cwd" || value === "session" || value === "effective";
+}
+
 function buildStateFlowTelegramSection(port: StateFlowTelegramPort) {
 	return {
 		id: STATE_FLOW_TELEGRAM_ID,
@@ -115,10 +197,21 @@ function buildStateFlowTelegramSection(port: StateFlowTelegramPort) {
 		render: (ctx: StateFlowTelegramSectionContext) =>
 			buildStateFlowSectionView(port.snapshot(), (action) => ctx.callbackData(action)),
 		handleCallback: async (ctx: StateFlowTelegramCallbackContext) => {
-			// cancel/refresh remain routable for keyboards sent by earlier versions; 0.9.4 presents only the state action.
-			if (ctx.action !== "start" && ctx.action !== "stop" && ctx.action !== "cancel" && ctx.action !== "refresh") return "pass" as const;
+			// cancel/refresh remain routable for keyboards sent by earlier versions.
+			if (ctx.action !== "start" && ctx.action !== "stop" && ctx.action !== "cancel" && ctx.action !== "refresh" && ctx.action !== "show-state" && ctx.action !== "inspect") return "pass" as const;
 			let notice: string | undefined;
 			try {
+				if (ctx.action === "show-state") {
+					await ctx.answerCallback();
+					await ctx.edit(buildStateFlowScopeChooser((action, payload) => ctx.callbackData(action, payload)));
+					return "handled" as const;
+				}
+				if (ctx.action === "inspect") {
+					if (!isStateFlowTelegramScope(ctx.payload)) throw new Error("Unknown State Flow scope");
+					await ctx.openRich(renderStateFlowRichState(ctx.payload, port.state(ctx.payload)));
+					await ctx.answerCallback();
+					return "handled" as const;
+				}
 				if (ctx.action === "start") {
 					if (port.canStartNow()) notice = port.start().message;
 					else {

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

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