@llblab/pi-kit 0.20.0 → 0.21.1

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

@@ -2,7 +2,7 @@ import type { ArtifactInvalidationReason } from "./artifact.ts";
 import { type RecentTransitionWindow } from "./history.ts";
 import type { Snapshot } from "./snapshot.ts";
 import { type ScopedStates, type StateScope } from "./state.ts";
-import type { TransitionBoundary } from "./temporal.ts";
+import type { ScopeRevisions, TransitionBoundary } from "./temporal.ts";
 export declare const STATUS_KEY = "state-flow";
 export type Colorize = (color: "accent" | "dim", text: string) => string;
 export type StaleArtifactReason = ArtifactInvalidationReason | "source-removed";
@@ -22,9 +22,11 @@ export interface StatusDiagnostics {
         head: TransitionBoundary;
         historyDepth: number;
         tailCounts: Record<StateScope, number>;
+        revisions: ScopeRevisions;
     };
     staleArtifacts: readonly StaleArtifactDiagnostic[];
     durableStateError?: string;
 }
-export declare function compactStatus(snapshot: Snapshot, colorize: Colorize): string;
+export declare function formatScopeRevisionVector(revisions: ScopeRevisions): string;
+export declare function compactStatus(snapshot: Snapshot, revisions: ScopeRevisions, colorize: Colorize): string | undefined;
 export declare function detailedStatus(snapshot: Snapshot, diagnostics: StatusDiagnostics): string;

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

@@ -2,8 +2,13 @@ import { projectRecentTransitionsWithLimit } from "./history.js";
 import { retainedMemoryScopes } from "./memory.js";
 import { overlayStates } from "./state.js";
 export const STATUS_KEY = "state-flow";
-export function compactStatus(snapshot, colorize) {
-    return `${colorize("accent", "state-flow")} ${colorize("dim", `#${snapshot.meta.step}`)}`;
+export function formatScopeRevisionVector(revisions) {
+    return `G${revisions.global}/C${revisions.cwd}/S${revisions.session}`;
+}
+export function compactStatus(snapshot, revisions, colorize) {
+    if (!snapshot.config.enabled)
+        return undefined;
+    return `${colorize("accent", "state-flow")} ${colorize("dim", formatScopeRevisionVector(revisions))}`;
 }
 function countArtifacts(states, scope) {
     return Object.keys(states[scope].artifacts).length;
@@ -26,6 +31,7 @@ export function detailedStatus(snapshot, diagnostics) {
             `Hot history: unavailable; configured maximum depth ${diagnostics.historyLimit}`,
             "Retained patch tails: unavailable"]
         : [`Temporal head: ${JSON.stringify(temporal.head.id)}; branch-local position ${temporal.head.position}`,
+            `Scope revisions: global #${temporal.revisions.global}; CWD #${temporal.revisions.cwd}; session #${temporal.revisions.session}; effective ${formatScopeRevisionVector(temporal.revisions)}`,
             `Hot history: offsets 0..${temporal.historyDepth}; maximum depth ${diagnostics.historyLimit}`,
             `Retained patch tails: global ${temporal.tailCounts.global}; CWD ${temporal.tailCounts.cwd}; session ${temporal.tailCounts.session}`];
     const artifacts = (scope) => available ? countArtifacts(diagnostics.scopeStates, scope) : "unknown";

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

@@ -1,9 +1,12 @@
+import type { ScopeRevisions } from "./temporal.ts";
 export declare const STATE_FLOW_TELEGRAM_ID = "@llblab/pi-state-flow";
 /** Resolve the package export or the compiled sibling-extension layout used in local development. */
 export declare function stateFlowTelegramSectionSpecifiers(moduleUrl?: string): string[];
 export interface StateFlowTelegramSnapshot {
     enabled: boolean;
+    /** Legacy branch step retained for existing adapter ports; current runtime ports also supply owner revisions. */
     step: number;
+    revisions?: ScopeRevisions;
     bootstrap: boolean;
     startPending: boolean;
 }
@@ -79,6 +82,8 @@ export interface StateFlowTelegramControlResult {
 export interface StateFlowTelegramPort {
     snapshot(): StateFlowTelegramSnapshot;
     state(scope: StateFlowTelegramScope): StateFlowTelegramState;
+    /** Optional additive capability; absent legacy ports retain their branch-step presentation. */
+    revisions?(): ScopeRevisions;
     canStartNow(): boolean;
     start(): StateFlowTelegramControlResult;
     stop(): StateFlowTelegramControlResult;
@@ -94,7 +99,7 @@ export declare function formatStateFlowSectionLabel(snapshot: StateFlowTelegramS
 /** The submenu header repeats the button's state line; the single action matches the current state. */
 export declare function buildStateFlowSectionView(snapshot: StateFlowTelegramSnapshot, callbackData: (action: string) => string): StateFlowTelegramView;
 export declare function buildStateFlowScopeChooser(callbackData: (action: string, payload?: string) => string): StateFlowTelegramView;
-export declare function renderStateFlowRichState(scope: StateFlowTelegramScope, step: number, state: StateFlowTelegramState): StateFlowTelegramRichMessage;
+export declare function renderStateFlowRichState(scope: StateFlowTelegramScope, revisions: ScopeRevisions, state: StateFlowTelegramState): StateFlowTelegramRichMessage;
 /** Default loader; injectable so tests and embedded hosts can control transport presence. */
 export declare function loadStateFlowTelegramModules(): Promise<StateFlowTelegramModules>;
 export declare function createStateFlowTelegramAdapter(options: {

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

@@ -10,6 +10,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+import { formatScopeRevisionVector } from "./status.js";
 export const STATE_FLOW_TELEGRAM_ID = "@llblab/pi-state-flow";
 /** Resolve the package export or the compiled sibling-extension layout used in local development. */
 export function stateFlowTelegramSectionSpecifiers(moduleUrl = import.meta.url) {
@@ -20,11 +21,15 @@ export function stateFlowTelegramSectionSpecifiers(moduleUrl = import.meta.url)
 }
 /** Main-menu section label doubles as the live status value: the spiral identity is constant, the value is not. */
 export function formatStateFlowSectionLabel(snapshot) {
-    return `🌀 State Flow: ${stateFlowLabelValue(snapshot)}`;
+    if (!snapshot.enabled)
+        return "🌀 State Flow: off";
+    return `🌀 State Flow: ${snapshot.revisions ? formatScopeRevisionVector(snapshot.revisions) : `#${snapshot.step}`}`;
 }
 /** Shared live value: plain in the button label, monospaced in the submenu state line. */
 function stateFlowLabelValue(snapshot) {
-    return `#${snapshot.step}`;
+    if (!snapshot.enabled)
+        return "off";
+    return snapshot.revisions ? formatScopeRevisionVector(snapshot.revisions) : `#${snapshot.step}`;
 }
 /** Submenu state line: the same identity as the button label, with the live value in monospace. */
 function formatStateFlowSectionHeader(snapshot) {
@@ -93,13 +98,18 @@ function renderStateFlowTelegramField(value) {
     }
     return rendered;
 }
-export function renderStateFlowRichState(scope, step, state) {
-    const fields = ["intents", "contract", "working", "artifacts", "response", "lazy"];
+export function renderStateFlowRichState(scope, revisions, state) {
+    const fields = scope === "global" || scope === "cwd"
+        ? ["intents", "contract", "working", "artifacts", "lazy"]
+        : ["intents", "contract", "working", "artifacts", "response", "lazy"];
+    const revision = scope === "effective"
+        ? formatScopeRevisionVector(revisions)
+        : `#${revisions[scope]}`;
     return {
         blocks: [
             {
                 type: "heading",
-                text: [`${STATE_FLOW_SCOPE_LABELS[scope]}: `, { type: "code", text: `#${step}` }],
+                text: [`${STATE_FLOW_SCOPE_LABELS[scope]}: `, { type: "code", text: revision }],
                 size: 3,
             },
             ...fields.map((field) => ({
@@ -134,7 +144,10 @@ function buildStateFlowTelegramSection(port) {
                 if (ctx.action === "inspect") {
                     if (!isStateFlowTelegramScope(ctx.payload))
                         throw new Error("Unknown State Flow scope");
-                    await ctx.openRich(renderStateFlowRichState(ctx.payload, port.snapshot().step, port.state(ctx.payload)));
+                    const state = port.state(ctx.payload);
+                    const live = port.snapshot();
+                    const revisions = port.revisions?.() ?? live.revisions ?? { global: live.step, cwd: live.step, session: live.step };
+                    await ctx.openRich(renderStateFlowRichState(ctx.payload, revisions, state));
                     await ctx.answerCallback();
                     return "handled";
                 }

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

@@ -16,6 +16,8 @@ export interface TemporalPatch {
     patch: RecentScopePatch["patch"];
 }
 export interface ScopeStream {
+    /** Monotonic semantic revision owned by this scope; independent of branch-local boundary positions. */
+    revision: number;
     checkpoint: ScopeCheckpoint;
     patches: TemporalPatch[];
 }
@@ -24,6 +26,7 @@ export interface TemporalState {
     lineage: TransitionBoundary[];
     scopes: Record<StateScope, ScopeStream>;
 }
+export type ScopeRevisions = Record<StateScope, number>;
 /** Replay validation is shared by disk codecs and active-lineage materialization. */
 export declare function validateScopeStream(value: unknown, scope: StateScope, historyLimit?: number): asserts value is ScopeStream;
 export declare function validateTemporalLineage(value: unknown, historyLimit?: number): asserts value is TransitionBoundary[];
@@ -41,6 +44,8 @@ export declare function constrainTemporalState(view: TemporalState, historyLimit
 export declare function selectScopeStreamAtBoundary(stream: ScopeStream, scope: StateScope, boundary: TransitionBoundary, historyLimit?: number): ScopeStream;
 /** Select one still-retained causal boundary without consulting an external history store. */
 export declare function selectTemporalStateBoundary(view: TemporalState, boundaryId: string, historyLimit?: number): TemporalState;
+/** Current independent scope revisions; Effective uses this vector rather than inventing a scalar owner. */
+export declare function temporalScopeRevisions(view: TemporalState): ScopeRevisions;
 /** Lazy scope/effective read at one shared transition boundary, never by local patch count. */
 export declare function readTemporalState(view: TemporalState, offset?: number, scope?: StateScope, historyLimit?: number): MaterializedState;
 /** Allocate the identity outside this algebra; only materially effective patches accept it. */

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

@@ -34,7 +34,8 @@ export function validateScopeStream(value, scope, historyLimit = DEFAULT_HISTORY
     validateHistoryLimit(historyLimit);
     if (!SCOPES.includes(scope))
         throw new Error("Unknown temporal scope");
-    if (!isJsonValue(value) || !isObject(value) || Object.keys(value).sort().join(",") !== "checkpoint,patches"
+    if (!isJsonValue(value) || !isObject(value) || Object.keys(value).sort().join(",") !== "checkpoint,patches,revision"
+        || !Number.isSafeInteger(value.revision) || value.revision < 0
         || !isObject(value.checkpoint) || Object.keys(value.checkpoint).sort().join(",") !== "state,through"
         || !Array.isArray(value.patches)) {
         throw new Error("Invalid temporal checkpoint/tail envelope");
@@ -44,6 +45,8 @@ export function validateScopeStream(value, scope, historyLimit = DEFAULT_HISTORY
     validateState(stream.checkpoint.state);
     if (stream.patches.length > historyLimit)
         throw new Error(`Temporal scope tail exceeds configured history limit ${historyLimit}`);
+    if (stream.revision < stream.patches.length)
+        throw new Error("Temporal scope revision predates its retained patch tail");
     let previous = stream.checkpoint.through;
     let state = stream.checkpoint.state;
     const identities = new Set([previous.id]);
@@ -160,6 +163,7 @@ export function adoptTemporalStreams(scopes, id, historyLimit = DEFAULT_HISTORY_
 export function createTemporalState(states, id, historyLimit = DEFAULT_HISTORY_LIMIT) {
     const through = { id, position: 0, parent: null };
     const stream = (scope) => ({
+        revision: 0,
         checkpoint: { through: structuredClone(through), state: structuredClone(states[scope]) },
         patches: [],
     });
@@ -201,7 +205,9 @@ export function selectScopeStreamAtBoundary(stream, scope, boundary, historyLimi
         throw new Error("Selected State Flow history boundary predates the retained scope checkpoint");
     }
     const selected = structuredClone(stream);
-    selected.patches = selected.patches.filter(({ transition }) => transition.position <= boundary.position);
+    const retained = selected.patches.filter(({ transition }) => transition.position <= boundary.position);
+    selected.revision -= selected.patches.length - retained.length;
+    selected.patches = retained;
     validateScopeStream(selected, scope, historyLimit);
     return selected;
 }
@@ -218,11 +224,26 @@ export function selectTemporalStateBoundary(view, boundaryId, historyLimit = DEF
     const selected = structuredClone(view);
     selected.lineage = selected.lineage.slice(0, index + 1);
     for (const scope of SCOPES) {
-        selected.scopes[scope].patches = selected.scopes[scope].patches.filter(({ transition }) => transition.position <= target.position);
+        const stream = selected.scopes[scope];
+        const retained = stream.patches.filter(({ transition }) => transition.position <= target.position);
+        stream.revision -= stream.patches.length - retained.length;
+        stream.patches = retained;
     }
     validateTemporalState(selected, historyLimit);
     return selected;
 }
+/** Current independent scope revisions; Effective uses this vector rather than inventing a scalar owner. */
+export function temporalScopeRevisions(view) {
+    const revisions = {
+        global: view.scopes.global.revision,
+        cwd: view.scopes.cwd.revision,
+        session: view.scopes.session.revision,
+    };
+    if (Object.values(revisions).some((revision) => !Number.isSafeInteger(revision) || revision < 0)) {
+        throw new Error("Invalid State Flow scope revision vector");
+    }
+    return revisions;
+}
 /** Lazy scope/effective read at one shared transition boundary, never by local patch count. */
 export function readTemporalState(view, offset = 0, scope, historyLimit = DEFAULT_HISTORY_LIMIT) {
     validateHistoryLimit(historyLimit);
@@ -266,6 +287,9 @@ export function advanceTemporalState(view, transitions, id, historyLimit = DEFAU
     const next = structuredClone(view);
     for (const { scope, patch } of changes) {
         const stream = next.scopes[scope];
+        if (stream.revision >= Number.MAX_SAFE_INTEGER)
+            throw new Error(`State Flow ${scope} scope revision is exhausted`);
+        stream.revision += 1;
         if (historyLimit === 0) {
             stream.checkpoint = { through: structuredClone(boundary), state: apply(scopeAt(stream, head), patch) };
             stream.patches = [];

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

@@ -184,8 +184,8 @@ export function stageAtomicScopePatches(currentStates, patches, successfulSkillR
     return stageScopedSemanticTransition(currentStates, { transitions }, successfulSkillReads, causalBasis, successfulArtifactReads);
 }
 export function stageScopedTransition(currentStates, transition, successfulSkillReads, causalBasis, successfulArtifactReads = []) {
-    if (typeof transition.response !== "string" || transition.response.trim().length === 0) {
-        throw new Error("Accepted State Flow response body must be non-empty");
+    if (typeof transition.response !== "string") {
+        throw new Error("Accepted State Flow response body must be a string");
     }
     return stageScopedSemanticTransition(currentStates, transition, successfulSkillReads, causalBasis, successfulArtifactReads, transition.response);
 }

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

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

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

@@ -40,7 +40,7 @@ Every materialized scope has exactly this shape:
 - `contract` retains durable requirements, decisions, interfaces and rejected approaches.
 - `working` retains verified current facts, unresolved work and exact continuation.
 - `artifacts` maps exact source paths to compiled routing metadata.
-- `response` is the latest complete user-facing answer for the session scope.
+- `response` is owned only by the session scope and stores the exact latest accepted assistant answer, including the empty string. Global and CWD retain the required key as an empty structural placeholder so canonical scopes keep one shape; the effective overlay receives `response` only from Session.
 - `lazy` is a required object root for ordinary JSON detail, omitted from baseline model state and read explicitly.
 
 Effective state recursively overlays:
@@ -67,9 +67,9 @@ The checkpoint is an older anchored materialization. The tail contains at most t
 
 Persisted streams and lineage are validated against the format maximum before applying a newly configured lower limit. Restore/reload/fork accepts only boundaries inside the configured window, then folds excess scope tails during canonical origin acceptance. That representation-only folding preserves selected private state and current shared values/provenance; a fork never rewrites parent-private files. Zero keeps only current checkpoints, and a later increase does not reconstruct discarded records or lineage.
 
-`effective[n]`, `global[n]`, `cwd[n]`, and `session[n]` resolve the same nth previous causal boundary. They are not independent per-scope patch counters. The retired top-level `state` segment is rejected; pre-origin history is unavailable rather than empty.
+`effective[n]`, `global[n]`, `cwd[n]`, and `session[n]` resolve the same nth previous causal boundary; the history index remains a composed-lineage offset, not a scope revision. Separately, each materially changed owner advances its persisted semantic revision once. Global and CWD counters remain shared across their canonical writers, Session remains private, and Effective is identified by the current `G#/C#/S#` revision vector. The retired top-level `state` segment is rejected; pre-origin history is unavailable rather than empty.
 
-A changed accepted response is runtime-owned semantic state and advances history. Ordinary completion requires no `patch_state` call when durable semantic state is already correct.
+A changed accepted response is runtime-owned, session-only semantic state and advances history. An accepted empty answer becomes `""` and finalizes normally rather than producing a recovery error. Ordinary completion requires no `patch_state` call when durable semantic state is already correct.
 
 ## Pi lifecycle
 
@@ -79,7 +79,7 @@ Tool preflight follows Pi's public `getLeafEntry()` / `getEntry(parentId)` links
 
 `read_state` reads one cached effective or scoped projection at current index zero or a retained causal index through the configured `historyLimit`. It never publishes or advances history.
 
-Before answering, the model uses `patch_state` only when future-relevant durable state must change. An accepted ordinary answer is reconciled directly into runtime-owned `response` at `turn_end`; no terminal eligibility latch, finalization patch, repair inference, or fallback budget exists. If required ordinary-artifact compilation prevents reconciliation, State Flow reports the failure without generating another inference. Optional Skill acquisition never blocks unrelated reconciliation. State Flow does not parse `state_flow` or generic HTML comments; historical comments are ordinary text and other extensions retain their own comment handling.
+Before answering, the model uses `patch_state` only when future-relevant durable state must change. The exact accepted ordinary answer is reconciled directly into runtime-owned `response` at `turn_end`, including `""` when the accepted answer is empty; no terminal eligibility latch, finalization patch, repair inference, or fallback budget exists. If required ordinary-artifact compilation prevents reconciliation, State Flow reports the failure without generating another inference. Optional Skill acquisition never blocks unrelated reconciliation. State Flow does not parse `state_flow` or generic HTML comments; historical comments are ordinary text and other extensions retain their own comment handling.
 
 ## Lifecycle planes
 
@@ -93,7 +93,7 @@ Stopping State Flow ends active episode semantics, restores the configured passi
 
 A proven pre-runtime branch has no accepted runtime to persist: Stop appends State Flow's existing `{disabled:true}` checkpoint in Pi without creating canonical files. Its cached passive view remains readable under the configured policy, but is not runtime authority. Accepted canonical publication, including a later Start or passive patch, ends this pre-runtime condition; failed selected-boundary recovery never qualifies for it.
 
-Lifecycle-only persistence for accepted runtimes reconciles valid live global/CWD drift before publishing the current session's config/runtime pair. Changed shared streams establish a fresh proven origin, not a semantic transition; counters, semantic files, and all provenance files remain unchanged. Cached reads may constrain wider tails left by another writer without rewriting them. Same-session file races and explicitly requested stale provenance writes still fail closed under CAS. The host refreshes its scope cache after adoption: Stop freezes the accepted view, and new-run registered-artifact maintenance runs against that view before inference.
+Lifecycle-only persistence for accepted runtimes reconciles valid live global/CWD drift before publishing the current session's config/runtime pair. Changed shared streams establish a fresh proven origin, not a semantic transition; the runtime adopts their already-advanced owner revisions without incrementing them, while semantic files and all provenance files remain unchanged. Cached reads may constrain wider tails left by another writer without rewriting them. Same-session file races and explicitly requested stale provenance writes still fail closed under CAS. The host refreshes its scope cache after adoption: Stop freezes the accepted view, and new-run registered-artifact maintenance runs against that view before inference.
 
 The existing native passive-stop marker stores the stop timestamp and an optional `from` timestamp identifying the active run's first user message. Native user events are observed independently of State Flow enablement, so starting mid-tool and repeated Start/Stop retain the actual first-user timestamp. Native user-run preparation and session-start/tree events reset capture; semantic mode changes do not. No new marker field, stored format or projection-derived lifecycle authority is introduced. Transcript bodies remain in Pi's trace rather than being copied into another state store. A recorded active anchor uses the same conservative selector as active inference: if native compaction removed it, or matching is ambiguous/nonfinite, retain the available native summary and tool trajectory without guessing a post-stop boundary or rereading discarded raw entries. Idle and legacy markers without an active anchor still retain only post-stop conversation plus foreign custom context. The initial system prompt is composed at `before_agent_start`; Stop does not rewrite an already-issued request, while the next provider request receives the current owned protocol section as described below.
 
@@ -128,7 +128,7 @@ meta.json
 
 CWD and session keys mirror Pi's native encoding. The Pi UUID remains authoritative; readable directory keys never replace identity validation.
 
-Root `config.json` is the read-only operator configuration shared by every session in the repository; it never participates in semantic overlay or State Flow-owned staging. Include operator configuration in operator-managed copies/versioning. `checkpoint.json` is only the canonical materialized semantic state, and each nonblank `patches.jsonl` line is only one semantic patch. Every scope's `meta.json` symmetrically owns checkpoint/tail boundaries and artifact provenance, with CWD ownership added where applicable. Session `config.json` owns behavior; session `runtime.json` asymmetrically owns lineage, counters, session identity, and the full specification only while a run is unfinished. Predecessor combined session metadata is unsupported; session `meta.json`, `config.json`, and `runtime.json` must already satisfy their canonical ownership contracts. Metadata writers replace only their owned leaves and preserve JSON-safe unknown siblings. Pi checkpoints retain only a semantic boundary plus lifecycle fields, or a proven ordinary-disabled marker. Revision-pointer checkpoints are unsupported and fail closed without Git restoration.
+Root `config.json` is the read-only operator configuration shared by every session in the repository; it never participates in semantic overlay or State Flow-owned staging. Include operator configuration in operator-managed copies/versioning. `checkpoint.json` is only the canonical materialized semantic state, and each nonblank `patches.jsonl` line is only one semantic patch. Every scope's `meta.json` symmetrically owns its independent semantic revision, checkpoint/tail boundaries and artifact provenance, with CWD ownership added where applicable. Session `config.json` owns behavior; session `runtime.json` asymmetrically owns lineage, the internal branch step, session identity, and the full specification only while a run is unfinished. Predecessor combined session metadata is unsupported; session `meta.json`, `config.json`, and `runtime.json` must already satisfy their canonical ownership contracts. Metadata writers replace only their owned leaves and preserve JSON-safe unknown siblings. A pre-revision 0.17 scope initializes its counter from the still-retained semantic tail and persists that baseline on its next owned write; folded ancestry is not guessed. Revision-aware writes emit scope metadata version 2 while continuing to read version 1. The version fence makes an older writer refuse a scope after its first revision-aware write instead of silently dropping the counter; all cooperating instances should still upgrade together. Pi checkpoints retain only a semantic boundary plus lifecycle fields, or a proven ordinary-disabled marker. Revision-pointer checkpoints are unsupported and fail closed without Git restoration.
 
 In-memory patching detaches one basis at its public boundary, then privately path-copies changed object/array containers while sharing untouched nodes only inside that owned draft. Incoming replacement values remain detached; staging no longer makes redundant cohort/per-scope pre-clones. Mutable staged responses and artifact registries stay isolated from accepted scopes, and commit/public temporal reads retain their detachment boundaries. This is not cross-version mutable sharing or a new disk generation format; see [copy-work evidence](performance.md#memory-only-owned-draft-cow).
 
@@ -144,7 +144,9 @@ After response reconciliation and Pi's retry/queue processing, `agent_before_set
 
 Only exact backed-up owned paths are synchronized in the caller's index, preserving unrelated staged additions, modifications, deletions, index-only content, and worktree edits. HEAD-owned paths remain candidates when their deletion is already staged. Unchanged trees and unowned-only initial backups are skipped; failed index synchronization rolls back only the backup ref, never canonical files. Failure cannot suppress the answer or trigger another inference. Notification-only `agent_settled` does not perform backup writes.
 
-Durable push queues, publication workers, leases, retries, queue filesystem state, and publication-policy metadata have been deleted. Git revision restore, immutable-revision fork APIs, and the legacy semantic Git backend have been removed from `TemporalRuntime`; all initialization, passive loading, model patches, runtime-only persistence, retained-boundary restoration, and retained-boundary forks use canonical files only.
+After a successful backup attempt, State Flow resolves only the attached branch's explicitly configured remote and destination ref, snapshots the exact current commit, and starts one non-interactive, non-force push outside all backup and canonical locks. Settlement does not await network completion. Failure is diagnostic-only; no queue is persisted, and the next accepted settled turn attempts the latest current backup again. A repository without an explicitly configured branch remote remains local-only.
+
+Durable push queues, publication workers, leases, retry generations, queue filesystem state, and publication-policy metadata remain absent. Git revision restore, immutable-revision fork APIs, and the legacy semantic Git backend have been removed from `TemporalRuntime`; all initialization, passive loading, model patches, runtime-only persistence, retained-boundary restoration, and retained-boundary forks use canonical files only.
 
 Predecessor checkpoint envelopes, combined session metadata, pre-intents checkpoints, `state.json`, hashed layouts, and semantic Pi checkpoints are unsupported and remain untouched.
 
@@ -232,7 +234,7 @@ Agent configuration is read once per extension load; session runtime configurati
 
 ## Observability
 
-Status is a projection of the selected runtime and semantic view, not a second store. Its transition counter remains visible and advances for accepted patches in active or passive mode. Missing evidence stays unavailable instead of appearing empty. The optional Telegram leaf adapter reads the same snapshot and calls the same Start/Stop owners. Its global/CWD/session/effective inspectors remain available in either mode; if model-facing passive access is disabled, inspection may lazily read existing canonical shared state without initializing or mutating it. Registration is fail-open and disposal belongs to session shutdown. Local diagnostics stay outside semantic state, scope metadata, checkpoints, and publication, and failures cannot change accepted state. Operator-facing fields and privacy boundaries are in [usage](usage.md#status-and-controls).
+Status is a projection of the selected runtime and semantic view, not a second store. Compact terminal and Telegram main-menu status render `G#/C#/S#` only while active; passive Telegram renders `State Flow: off`. Requested Global, CWD and Session Rich snapshots show their independent `#revision`, while Effective shows the vector. Global/CWD Rich views omit the empty structural response placeholder; Session and Effective expose the Session-owned response. Missing evidence stays unavailable instead of appearing empty. The optional Telegram leaf adapter calls the same Start/Stop owners, and its inspectors remain available in either mode. Inspection may refresh live Global/CWD streams in memory so foreign accepted revisions become visible, but never publishes or increments a revision. If model-facing passive access is disabled and no runtime is selected, inspection may lazily load existing canonical shared state under the same read-only rule. Registration is fail-open and disposal belongs to session shutdown. Local diagnostics stay outside semantic state and cannot change accepted state. Operator-facing fields and privacy boundaries are in [usage](usage.md#status-and-controls).
 
 ## Validation boundaries
 

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

@@ -42,11 +42,11 @@ global | CWD | session
 ├── contract
 ├── working
 ├── artifacts
-├── response (session-owned where applicable)
+├── response (session-owned; empty structural slot in Global/CWD)
 └── lazy
 ```
 
-`intents`, `contract`, `working`, `artifacts`, and `response` remain hot. `intents` may keep compact active direction while referring to large supporting detail in `lazy`. `lazy` differs only in projection policy:
+`intents`, `contract`, `working`, and `artifacts` remain hot in every scope. Session-owned `response` is also hot; Global and CWD keep only its required empty structural slot, and Effective inherits the Session value. `intents` may keep compact active direction while referring to large supporting detail in `lazy`. `lazy` differs only in projection policy:
 
 - It is canonical semantic JSON, validated and versioned with its owning scope.
 - It is excluded from the ordinary baseline effective-state body.

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

@@ -17,13 +17,14 @@ This is a maintained property-to-test map for the current canonical-file contrac
 11. **Barrier shifts current to offset 1:** `tests/integration.test.ts` — “real Pi patch_state barriers rematerialize every scope before the next inference” observes the predecessor immediately after a barrier.
 12. **Next inference sees new current state:** The same real-Pi test inspects actual model-input projections after session, CWD, and global barriers. “real Pi reads prior scoped state lazily after a barrier and rejects path offset eight without a transition” adds model-tool access to the predecessor.
 13. **No automatic old full-state duplication:** `tests/context.test.ts` — “projects only the latest seven compact accepted transitions” rejects full-state records in transition context. The real-Pi barrier test requires exactly one current runtime projection per inference. Explicitly requested history remains ordinary tool-result trajectory, not eager snapshot injection.
-14. **Accepted response changes are transitions:** `tests/extension.test.ts` — “accepts only canonical materially changing atomic scope patches” verifies that an ordinary accepted answer becomes runtime-owned `response` without a finalization patch or fallback inference.
-15. **No-op mutation signals are rejected:** The same extension test rejects empty and obsolete finalization-shaped calls, while a changed accepted response remains a runtime-owned transition.
+14. **Accepted response changes are transitions:** `tests/extension.test.ts` verifies that an ordinary accepted answer becomes runtime-owned `response` without a finalization patch or fallback inference, and “an empty accepted answer finalizes the run and stores an empty response” proves `""` is accepted after an earlier barrier. `tests/transition.test.ts` proves the empty value is an ordinary Session-owned semantic change when it replaces prior text.
+15. **No-op mutation signals are rejected:** “accepts only canonical materially changing atomic scope patches” rejects empty scope patches and obsolete finalization-shaped calls, while a changed accepted response remains a runtime-owned transition.
 16. **Configured hot-history bounds:** `tests/temporal.test.ts` verifies hot-range and unavailable pre-origin boundaries; the real-Pi history-reader test rejects offset eight at the default limit seven without a transition. `tests/config.test.ts` exercises materialized and scope patch-history paths at limits 0, 1, 7, and 12, including single-path/one-item batch reads above seven and distinct configured versus actually retained boundaries.
 17. **Selected history fails closed:** `tests/recovery.test.ts` proves every failure resolving a selected retained boundary refuses without falling through to older boundaries or disabled markers. `tests/extension.test.ts` covers all passive bootstrap/tool combinations; the native “real Pi expired selection cannot reset private state through passive Start, Stop, patch, or reload” witness preserves exact canonical bytes and Pi checkpoints while allowing shared reads. Fork identity/CWD repair witnesses retry the original source with passive access both enabled and disabled.
 18. **Tree/resume select the correct lineage:** `tests/integration.test.ts` — “real Pi preserves branch-local state through compaction and rejects an expired sibling after fresh-origin navigation” and “real Pi old tree branch stop and resume preserve selected semantics without rewinding shared files”.
 19. **Stop changes config, not semantic history:** `tests/runtime.test.ts` lifecycle-only witnesses use a separate process to advance global/CWD semantics or provenance, including wider foreign retention, then prove exact semantic/sidecar preservation, unchanged steps, idempotent Stop, and same-session/stale-evidence refusal. Native Stop/new-request witnesses verify the accepted shared view reaches handoff/inference without a lifecycle semantic write, while a shared write racing after inference still fails closed. Mid-tool Stop tests preserve ordinary/bootstrap trajectories through tree, reload, resume, and restart. The native “real Pi retains a native split-turn continuation through late tools” Stop/no-Stop controls actually remove the original user with native threshold compaction, then require summary, paired reads and foreign context in model input. The Stop case also checks frozen semantics/step, unchanged trace prefix, tree/reload/cold resume/bootstrap restart, no resurrection of discarded input, and persistent foreign context after the next active run. Pure passive-selector tests cover missing, colliding and nonfinite recorded active anchors without changing idle/legacy cutoffs. `tests/storage.test.ts` fences lifecycle-only writes to config/runtime files; `tests/extension.test.ts` covers idle/legacy cutoffs and new/fork boundaries.
-20. **Passive observability keeps one counter and state surface:** `tests/status.test.ts` proves an accepted passive patch advances `#N` while active mode remains disabled. `tests/telegram.test.ts` drives the real extension port after Stop, verifies global and effective Rich-state controls expose the passive patch at the same `#N`, and separately proves Telegram can lazily observe existing shared canonical state when passive model tools are disabled without initializing or mutating storage.
+20. **Passive observability omits active status without hiding owner revisions:** `tests/status.test.ts` proves an accepted passive patch advances semantic history while compact terminal status stays absent. `tests/telegram.test.ts` drives the real extension port after Stop, requires the passive main-menu identity to render `State Flow: off`, verifies an owner Rich-state heading uses its independent `#revision` and Effective uses `G#/C#/S#`, and separately proves Telegram can lazily observe existing shared canonical state when passive model tools are disabled without initializing or mutating storage.
+21. **Independent revisions survive folding and foreign writers:** `tests/temporal.test.ts` proves each materially changed scope advances once for sparse and multi-scope cohorts, response-only transitions advance only Session, no-ops advance none, selected retained history restores the matching revision, and folding never resets it. `tests/durable.test.ts` covers revision serialization plus the pre-revision 0.17 retained-tail baseline. `tests/runtime.test.ts` uses an independent file-backed writer to advance Global, then refreshes the first runtime without file mutation and proves `G1/C0/S1` becomes `G1/C0/S2` after one private Session patch.
 
 ## Additional preservation boundaries
 

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

@@ -64,14 +64,14 @@ Logs remain local unless you move them; rotation/deletion is operator-owned. Tre
 
 `/state-flow-status` separates runtime configuration/metadata from semantic state. It reports:
 
-- Selected CWD/session keys, step, temporal head, recovery failures, and available hot history.
+- Selected CWD/session keys, internal step, independent scope revisions, temporal head, recovery failures, and available hot history.
 - Per-scope retained patch tails and artifact counts, plus one JSON representation of effective global → CWD → session memory. Individual scope JSON is available through `read_state`, not duplicated in status.
 - Already-known runtime hints or pending artifact invalidations; status does not discover or validate sources.
 - Memory-bearing scopes. Promotion-shaped values receive no special interpretation.
 
 Tail counts are not history depth: inherited records may predate the active origin. Failed inspection reports unavailable evidence, not invented empty state. Status is observational: it does not read source files, calculate fingerprints, create invalidations, or mutate semantic state.
 
-The terminal indicator is `state-flow #N` in active and passive modes; accepted passive patches advance the same counter. When `pi-telegram` is available, one main-menu section mirrors `#N`, opens Start/Stop controls, and can inspect global, CWD, session or effective state in either mode. Telegram may lazily read existing shared state even when passive model tools are disabled; this observation does not initialize or mutate storage. Start requested during a run waits for settlement; Stop currently applies immediately. The adapter is optional and the Pi commands remain available without it. Open implementation work is tracked in [BACKLOG.md](../BACKLOG.md).
+The terminal indicator is `state-flow G15/C8/S31` only in active mode. Global, CWD and Session own independent semantic revisions; one atomic transition advances each materially changed scope once, including session-only response reconciliation. Effective has no scalar counter and uses the `G#/C#/S#` revision vector. When `pi-telegram` is available, its main-menu section shows that vector only while active and `State Flow: off` while passive. Requested owner-scope Rich snapshots show `#revision`; Effective shows the vector. Telegram inspection may lazily load or refresh live shared state from other instances even when passive model tools are disabled, but it does not initialize, publish, or advance storage. Start requested during a run waits for settlement; Stop currently applies immediately. The adapter is optional and the Pi commands remain available without it. Open implementation work is tracked in [BACKLOG.md](../BACKLOG.md).
 
 ## Storage and recovery
 
@@ -92,19 +92,19 @@ Exactly one surviving pair member is corruption and fails closed. Present malfor
 
 After a selected-boundary failure, configured passive access may still expose current global/CWD memory, but it never grants access to the unavailable session layer or permission to publish an empty replacement. Session reads, every `patch_state`, and Stop refuse without changing canonical files or appending substitute checkpoints. Status retains the restoration error even when shared reads work. Start retries the original selection; repair its missing or invalid evidence, select a still-retained boundary, or use a genuinely new Pi session instead of forcing a reset.
 
-Missing artifact provenance inside an otherwise complete scope `meta.json` means compilation evidence is unavailable while semantic state remains usable; removing the whole metadata file also removes temporal authority and fails closed. An unavailable registered source path does not prove that durable artifact routing was deleted, and external files are never created. State Flow has no durable push queue or publication-worker lease. See the complete [filesystem recovery contract](filesystem-recovery.md).
+Missing artifact provenance inside an otherwise complete scope `meta.json` means compilation evidence is unavailable while semantic state remains usable; removing the whole metadata file also removes temporal authority and fails closed. An unavailable registered source path does not prove that durable artifact routing was deleted, and external files are never created. State Flow has no durable push queue or publication-worker lease; failed replication is attempted again only after a later accepted turn. See the complete [filesystem recovery contract](filesystem-recovery.md).
 
 ### Canonical files and optional Git backup
 
 Canonical scope/runtime files own current materialization and retained hot history regardless of Git availability. Pi checkpoints identify a retained semantic boundary, not a Git commit or arbitrary historical snapshot. Restart and branch restoration fail closed when the selected boundary has expired rather than substituting newer files as the selected past.
 
-After an accepted turn has reconciled its response, Pi 0.87's final actionable `agent_before_settle` boundary may create one best-effort backup commit when Git is available. Backup failure is diagnostic-only. Git availability never changes semantic authority, step, or retained lineage.
+After an accepted turn has reconciled its response, Pi 0.87's final actionable `agent_before_settle` boundary may create one best-effort backup commit when Git is available. If the attached branch has an explicitly configured remote/ref, State Flow starts a non-interactive asynchronous push of the exact current commit without force. Settlement does not wait for the network. Commit or push failure is diagnostic-only, and the next accepted turn retries the latest backup without a durable queue. Git availability never changes semantic authority, step, or retained lineage.
 
 ### Moving a store and the 0.17 format boundary
 
 An SDK `repositoryRoot` override or a different `PI_CODING_AGENT_DIR` selects a location; it does not relocate existing state or retained history. Copy the complete canonical store while all writers are quiescent, or use a genuinely new Pi session for an independent store. Copying only current checkpoints without their tails and metadata cannot preserve retained boundaries.
 
-State Flow 0.17 accepts only its canonical checkpoint/tail, temporal metadata, and separate session config/runtime contract. Predecessor checkpoint envelopes, combined session metadata, pre-intents checkpoints, `state.json`, hashed layouts, and semantic Pi checkpoint envelopes fail as unsupported without rewriting existing bytes. State Flow does not provide an in-place converter; external conversion or a fresh store is operator-owned.
+State Flow 0.17 accepts only its canonical checkpoint/tail, temporal metadata, and separate session config/runtime contract. A canonical 0.17 scope written before independent revisions remains readable: its initial counter uses only the retained semantic tail and is persisted in metadata version 2 on the next owned write, without inventing folded ancestry. Version 1 remains readable; older writers refuse version 2 through the existing provenance-version fence, so cooperating instances should upgrade together. Predecessor checkpoint envelopes, combined session metadata, pre-intents checkpoints, `state.json`, hashed layouts, and semantic Pi checkpoint envelopes fail as unsupported without rewriting existing bytes. State Flow does not provide an in-place converter; external conversion or a fresh store is operator-owned.
 
 ### Conflicts and interrupted publication
 

package/node_modules/@llblab/pi-state-flow/index.ts

@@ -71,7 +71,7 @@ export {
   temporalStateFileUpdates, type ScopeStreamSources, type TemporalScopePaths
 } from "./lib/durable.ts";
 export { default, PATCH_STATE_TOOL_NAME, READ_STATE_TOOL_NAME, type StateFlowExtensionOptions } from "./lib/extension.ts";
-export { backupCurrentStateFlowFiles } from "./lib/git.ts";
+export { backupCurrentStateFlowFiles, pushCurrentStateFlowBackup } from "./lib/git.ts";
 export {
   createAcceptedTransition,
   DEFAULT_HISTORY_LIMIT,
@@ -139,5 +139,5 @@ export {
   type StateFlowTelegramSnapshot,
   type StateFlowTelegramView
 } from "./lib/telegram.ts";
-export { advanceTemporalState, readTemporalState, type TemporalState } from "./lib/temporal.ts";
+export { advanceTemporalState, readTemporalState, temporalScopeRevisions, type ScopeRevisions, type TemporalState } from "./lib/temporal.ts";
 export { parseStateReadPath, readStatePath, type StateReadQuery, type StateReadResult } from "./lib/query.ts";

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

@@ -50,6 +50,7 @@ export function hasCwdMaterialization(cwd: string, repositoryRoot: string): bool
 }
 
 export interface ScopeTemporalMetadata {
+	revision: number;
 	checkpoint: ScopeStream["checkpoint"]["through"];
 	patches: ScopeStream["patches"][number]["transition"][];
 }
@@ -68,6 +69,7 @@ export function serializeScopeStream(stream: ScopeStream, scope: StateScope, cwd
 		checkpoint: `${canonicalJson(stream.checkpoint.state)}\n`,
 		patches: stream.patches.map((record) => `${canonicalJson(record.patch)}\n`).join(""),
 		temporal: {
+			revision: stream.revision,
 			checkpoint: structuredClone(stream.checkpoint.through),
 			patches: stream.patches.map((record) => structuredClone(record.transition)),
 		},
@@ -124,6 +126,9 @@ export function classifyScopeStream(
 	const boundaries = temporal.patches;
 	if (boundaries.length !== patches.length) throw new Error(`State Flow ${scope} temporal metadata does not match its semantic tail`);
 	const stream = {
+		// 0.17.4 and earlier did not persist scope revisions. Credit only their still-retained
+		// semantic tail; discarded ancestry cannot be reconstructed without inventing history.
+		revision: temporal.revision === undefined ? patches.length : temporal.revision,
 		checkpoint: { through: temporal.checkpoint, state: checkpoint },
 		patches: patches.map((patch, index) => ({ transition: boundaries[index], patch })),
 	};
@@ -219,7 +224,7 @@ export function serializeScopeMetadata(
 	const sources = serializeScopeStream(stream, scope, cwdIdentity);
 	const value = {
 		...existing,
-		version: 1,
+		version: 2,
 		...(registry === undefined ? {} : { artifacts: serializeArtifactProvenanceRegistry(registry) }),
 		temporal: sources.temporal,
 		...(scope === "cwd" ? { owner: { cwd: resolve(cwdIdentity!) } } : {}),
@@ -229,7 +234,7 @@ export function serializeScopeMetadata(
 
 /** Compatibility serializer retained for metadata-only callers. */
 export function serializeScopeProvenance(registry: Readonly<ArtifactProvenanceRegistry>): string {
-	return `${canonicalJson({ version: 1, artifacts: serializeArtifactProvenanceRegistry(registry) })}\n`;
+	return `${canonicalJson({ version: 2, artifacts: serializeArtifactProvenanceRegistry(registry) })}\n`;
 }
 
 function parseMetadataDocument(source: string | undefined, label: string): Record<string, unknown> {
@@ -245,7 +250,7 @@ function parseMetadataDocument(source: string | undefined, label: string): Recor
 export function parseScopeProvenance(source: string | undefined, path: string): ArtifactProvenanceRegistry {
 	const value = parseMetadataDocument(source, `State Flow provenance file: ${path}`);
 	if (Object.keys(value).length === 0) return {};
-	if (value.version !== 1) throw new Error(`Invalid State Flow provenance document: ${path}`);
+	if (value.version !== 1 && value.version !== 2) throw new Error(`Invalid State Flow provenance document: ${path}`);
 	if (!Object.hasOwn(value, "artifacts")) return {};
 	return parseArtifactProvenanceRegistry(value.artifacts, `State Flow provenance at ${path}`);
 }