@llblab/pi-kit 0.10.2 → 0.10.3

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.10.3 - 2026-09-11
+
+- `State Flow Telegram Surface`: Advances the exact State Flow pin to `0.9.4`, so the pre-Settings section button always carries the spiral identity and the live value (`🌀 State Flow: off`, `🌀 State Flow: #N`), and its submenu repeats that state line, follows it with a short explanation of what State Flow is, and exposes one wide `Start` or `Stop` action instead of Start, Refresh, and Cancel start. The package set, resource inventory, and explicit load order remain unchanged.
+
 ## 0.10.2 - 2026-09-11
 
 - `State Flow Publication`: Advances the exact State Flow pin to `0.9.3`, syncing the publication-queue lineage-rewrite hotfix. A queued target orphaned by a reset or re-initialized journal now retargets the live lineage instead of failing every `turn_end`, and deferred remote publication is reported accurately. The package set, resource inventory, and explicit load order remain unchanged.

package/README.md

@@ -14,7 +14,7 @@ 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.9.3` | Atomic scoped state cohorts with final-eligibility resolution |
+| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.9.4` | Atomic scoped state cohorts with final-eligibility resolution |
 | [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.45.5` | Telegram companion, 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 |
 

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

@@ -2,6 +2,11 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.9.4: Telegram submenu mirrors the status line
+
+- `Interop`: The section button always carries the spiral identity and the live value — `🌀 State Flow: off` while disabled, `🌀 State Flow: #N` while enabled; the black-circle variant is gone.
+- `Interop`: The submenu header repeats that same state line and follows it with a short explanation of what State Flow is; the only action is one wide `Start` or `Stop` button, with the transport's `⬆️ Main menu` row above it. Refresh and Cancel start are no longer presented, the verbose status block was removed, and their callbacks stay routable for keyboards from earlier versions.
+
 ## 0.9.3: Publication queue lineage-rewrite hotfix
 
 - `Publication`: Retarget a queued target orphaned by a journal reset or re-initialization to the live lineage and keep publishing, instead of failing every `turn_end` with "Publication queue targets diverge"; the retired commit stays in local Git history.

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

@@ -66,7 +66,7 @@ Stopping changes the current session/branch configuration, preserves semantic ch
 
 The compact status is an accent `state-flow` and dim `#<step>`. Detailed status distinguishes runtime config/meta from semantic materialization, reports scope keys, the selected temporal head and runtime revision, available hot offsets, per-scope retained patch tails, artifact counts, stale Markdown reasons, and pending publication. Retained tails may include inherited pre-origin records, so their counts are not active history depth. It labels global/CWD/session/effective state without dumping source bodies. Failed inspection means unavailable evidence, never a falsely clean count.
 
-When the optional `pi-telegram` extension is installed, State Flow appears exactly once in Telegram: the inline main menu places a `🌀 State Flow: #N` or `⚫️ State Flow` section button directly before Settings, and that button's label carries the live status. The button opens a compact control submenu for the current session branch: `Start` or `Stop`, `Refresh`, and `Cancel start` while a start deferred behind an active run is pending. Starting while a run is active waits for that run to settle; stopping applies immediately. Registration fails open when the transport is absent, retries when the section registry becomes ready, and disposes on session shutdown; the `/state-flow-*` commands remain the authority and nothing changes for hosts without `pi-telegram`.
+When the optional `pi-telegram` extension is installed, State Flow appears exactly once in Telegram: the inline main menu places a `🌀 State Flow: #N` or `🌀 State Flow: off` section button directly before Settings, and that button's label carries the live status. The button opens a compact submenu whose header repeats the same state line, followed by a short explanation of what State Flow is; the only action is `Start` (or `Stop` while enabled), with the transport-owned `⬆️ Main menu` row above it. Starting while a run is active waits for that run to settle; stopping applies immediately. Registration fails open when the transport is absent, retries when the section registry becomes ready, and disposes on session shutdown; the `/state-flow-*` commands remain the authority and nothing changes for hosts without `pi-telegram`.
 
 ## State, scope, and time
 

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

@@ -199,7 +199,7 @@ Unknown keys fail loading. State Flow memory ownership and global availability a
 
 `/state-flow-status` reports branch mode, runtime revision, temporal head/history depth, scope keys, patch tails, artifact freshness, memory-bearing scopes, external-promotion summaries, remote policy/queue state, and pending publication. Unavailable materialization is reported as unavailable, never fabricated as empty. Artifact source bodies are not read for status.
 
-With `pi-telegram` installed, the optional `telegram` adapter mirrors the same identity in Telegram: the main-menu section button before Settings carries the live `🌀 State Flow: #N` or `⚫️ State Flow` label and opens the branch start/stop submenu. Registration is fail-open and retried on session start, disposal happens on session shutdown, the adapter reads the same snapshot as the compact terminal status, and its start/stop actions call the same functions as the commands.
+With `pi-telegram` installed, the optional `telegram` adapter mirrors the same identity in Telegram: the main-menu section button before Settings carries the live `🌀 State Flow: #N` or `🌀 State Flow: off` label and opens the branch start/stop view, whose header repeats that state line, follows it with a short explanation of what State Flow is, and exposes one wide `Start` or `Stop` action under the transport-owned `⬆️ Main menu` row. Registration is fail-open and retried on session start, disposal happens on session shutdown, the adapter reads the same snapshot as the compact terminal status, and its start/stop actions call the same functions as the commands.
 
 Opt-in `logging` appends local JSONL diagnostics for rejected `patch_state` calls and preserved drafts plus fallback turns while turn resolution is pending. A rejected call retains its exact attempted arguments, the precise error, and, when available, tool identity, call id, resolution attempt, and terminal-eligibility state; accepted patches are never logged. Records preserve useful exact text blocks and reduce other blocks to structural identity without duplicating reasoning. They are never semantic state, scope `meta.json`, Pi checkpoints, or repository input. Write failure changes no resolution, enablement, or accepted state and reports at most one bounded local warning.
 

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

@@ -73,34 +73,28 @@ export interface StateFlowTelegramAdapter {
 	dispose(): void;
 }
 
-/** Main-menu section label doubles as the live status value; the disabled row carries no status text. */
+/** Main-menu section label doubles as the live status value: the spiral identity is constant, the value is not. */
 export function formatStateFlowSectionLabel(snapshot: StateFlowTelegramSnapshot): string {
-	return snapshot.enabled ? `🌀 State Flow: #${snapshot.step}` : "⚫️ State Flow";
+	return snapshot.enabled ? `🌀 State Flow: #${snapshot.step}` : "🌀 State Flow: off";
 }
 
+/** Short help under the state line: what State Flow is and why its action button exists. */
+const STATE_FLOW_SECTION_HELP =
+	"Durable memory for this conversation: State Flow records the latest accepted state after every turn, so a new session resumes from the last committed point. Start it to keep memory live on this branch, stop it to pause.";
+
+/** The submenu header repeats the button's state line; the single action matches the current state. */
 export function buildStateFlowSectionView(
 	snapshot: StateFlowTelegramSnapshot,
 	callbackData: (action: string) => string,
 ): StateFlowTelegramView {
-	const lines = ["<b>🌀 State Flow</b>", ""];
-	if (snapshot.enabled) {
-		lines.push("Status: <b>enabled</b>", `State iteration: <code>#${snapshot.step}</code>`);
-		if (snapshot.bootstrap) lines.push("Bootstrap run: the next completed run migrates active context into state.");
-	} else if (snapshot.startPending) {
-		lines.push("Status: <b>off</b>", "Start is pending until the current turn settles.");
-	} else {
-		lines.push("Status: <b>off</b>", "State Flow is disabled on this session branch.");
-	}
-	const buttons: StateFlowTelegramButton[] = [];
-	if (snapshot.startPending) {
-		buttons.push({ text: "✖️ Cancel start", callback_data: callbackData("cancel") });
-	} else if (snapshot.enabled) {
-		buttons.push({ text: "⏹ Stop", callback_data: callbackData("stop") });
-	} else {
-		buttons.push({ text: "▶️ Start", callback_data: callbackData("start") });
-	}
-	buttons.push({ text: "🔄 Refresh", callback_data: callbackData("refresh") });
-	return { text: lines.join("\n"), parseMode: "html", replyMarkup: { inline_keyboard: [buttons] } };
+	const action: StateFlowTelegramButton = snapshot.enabled
+		? { text: "⏹ Stop", callback_data: callbackData("stop") }
+		: { text: "▶️ Start", callback_data: callbackData("start") };
+	return {
+		text: [`<b>${formatStateFlowSectionLabel(snapshot)}</b>`, "", STATE_FLOW_SECTION_HELP].join("\n"),
+		parseMode: "html",
+		replyMarkup: { inline_keyboard: [[action]] },
+	};
 }
 
 function buildStateFlowTelegramSection(port: StateFlowTelegramPort) {
@@ -111,6 +105,7 @@ 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;
 			let notice: string | undefined;
 			try {

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -44,7 +44,7 @@
     "@llblab/pi-clean-room": "0.1.1",
     "@llblab/pi-codex-usage": "0.9.4",
     "@llblab/pi-grow-loop": "0.8.1",
-    "@llblab/pi-state-flow": "0.9.3",
+    "@llblab/pi-state-flow": "0.9.4",
     "@llblab/pi-telegram": "0.45.5",
     "@llblab/skills": "1.15.0"
   },