@llblab/pi-kit 0.21.0 → 0.21.2

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.21.2 - 2026-09-23
+
+- `Backup Push Reliability`: Advances the exact State Flow pin to `0.18.1`. Backup replication permits one in-flight push per repository; overlapping attempts are skipped until a later accepted turn, while session shutdown waits for the active process to close. Canonical state acceptance remains independent of Git replication.
+- `Failure Diagnostics`: Push failures warn once per streak and retain redacted Git detail in the local diagnostic log even when general logging is off; a successful push resets warning suppression. If logging fails, the warning includes the available detail instead.
+- `Prompt-Prefix Evidence`: The State Flow v3 synthetic benchmark now measures serialized per-inference context and within-run shared prefixes, including isolated resume probes. It does not change model projection or claim provider cache gains.
+
+## 0.21.1 - 2026-09-23
+
+- `Queue Transition Reliability`: Advances the exact Telegram pin to `0.51.1`. Busy `/next` now reports the interrupted turn and exact selected queued prompt in order, preserves one reply-header owner through agent start, keeps rapid ordinary messages separate, and lets `/abort` or `/stop` cancel stale notices without allowing notice failures to block dispatch.
+- `Follower Heartbeat Stability`: Uses a dedicated eight-second follower heartbeat response deadline aligned with leader stale-liveness policy, preventing ordinary multi-second Pi/TUI event-loop stalls from destroying a healthy socket, producing leader `EPIPE` noise, or cycling registration status.
+- `Package Cohort`: Keeps every other bundled package at its current exact version. Package membership, resource paths, load order, Pi minimum, and bundled Skill ownership remain unchanged.
+
 ## 0.21.0 - 2026-09-23
 
 - `Independent Scope Revisions`: Advances the exact State Flow pin to `0.18.0`. Global, CWD, and Session now persist independent semantic revision counters, Effective displays the truthful `G#/C#/S#` vector, and Session exclusively owns response state while Global and CWD retain only their structural placeholders.

package/README.md

@@ -14,15 +14,15 @@ 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.10.0` | Compact Codex/Spark subscription-limit and Business credit-usage status |
 | [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.8.1` | Visible continuation scheduling and bounded worker Skills |
-| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.18.0` | Incremental scoped context/memory compiler with independent scope revisions, canonical file persistence, optional replicated Git backups, native working context within each run, and targeted historical reads |
-| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.51.0` | Telegram companion with pressure-safe Workspace slot rotation, fenced follower readiness, adaptive Thread continuity, exact queues, files, voice, controls, and bundled Telegram interaction Skills |
+| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.18.1` | Incremental scoped context/memory compiler with independent scope revisions, canonical file persistence, bounded and diagnosable Git backup replication, native working context within each run, and targeted historical reads |
+| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.51.1` | Telegram companion with stable follower heartbeats, exact queue-transition notices, pressure-safe Workspace rotation, adaptive Thread continuity, files, voice, controls, and bundled Telegram interaction Skills |
 | [`@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.
 
 ## Install
 
-Requires **Pi 0.87.0+** and **Node.js 22.19.0+**. State Flow 0.17 introduces a breaking storage-format boundary with no in-place predecessor converter. Preserve existing State Flow stores and review the [owning package's storage guidance](https://github.com/llblab/pi-state-flow/blob/v0.18.0/docs/usage.md#moving-a-store-and-the-017-format-boundary) before upgrading from an earlier kit.
+Requires **Pi 0.87.0+** and **Node.js 22.19.0+**. State Flow 0.17 introduces a breaking storage-format boundary with no in-place predecessor converter. Preserve existing State Flow stores and review the [owning package's storage guidance](https://github.com/llblab/pi-state-flow/blob/v0.18.1/docs/usage.md#moving-a-store-and-the-017-format-boundary) before upgrading from an earlier kit.
 
 From npm:
 

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

@@ -21,7 +21,7 @@
 - Read and write only regular non-symlink State Flow-owned files at those exact paths, publish each file by same-directory atomic rename, preserve arbitrary repository contents, and classify ownership exactly. Retain opaque source bytes for file identity and rollback, not decoded-text reconstructions. Use validated structural JSON equality for in-process semantic comparisons; reserve cryptographic hashes for compact identities that cross persistence/process boundaries. Serialize cooperating canonical-file writers through file-cohort exclusion and CAS. Recheck prepared bases before each replacement/deletion and restore only bytes still matching the publisher's own output. Preserve detected concurrent changes and report unresolved rollback conflicts; do not claim kernel-atomic multi-file CAS against nonparticipating writers. Inspect only exact already-registered artifact paths; do not discover or own a Knowledge directory.
 - At instance initialization resolve the repository, CWD key, and session key; load each scope's anchored canonical checkpoint and tail, materialize at the selected retained boundary, then overlay `global → cwd → session`. Install cached view and file publication basis atomically only after successful restoration/initialization. Revalidate mutable file cohorts; never turn inspection into a long-lived publication-basis cache. Preserve selected retained-boundary evidence across transient restore failure so explicit Start can retry it. A genuinely new session gets an empty session layer and inherits only global/CWD values; it must never reuse another same-CWD session layer. Explicit native fork adoption follows the [session-copy contract](docs/fork-contract.md): copy the proven retained source-session stream and provenance into a distinct fresh canonical origin over current shared streams, without modifying parent-private files. Reject occupied targets and checkpoint the child only after CAS acceptance. Inherited parent pointers never authorize an empty reset; fence parent passive Stop projection across child reload.
 - Bind active Pi checkpoints to retained semantic boundaries in the current canonical lineage. Resume and tree restoration select only retained private session history while global/CWD scopes remain live; every failure resolving a selected boundary fails closed without falling through to older checkpoints, disabled markers, Git revisions, or unrelated newer private state. Passive shared-memory availability does not prove the selected private layer: preserve the recovery failure, reject session reads and all publication until it is resolved, and let explicit Start retry the exact selection. Never checkpoint a passive substitute over failed branch recovery.
-- Every accepted semantic change, including session-only and response-only changes, atomically updates affected canonical checkpoint/tail pairs and temporal metadata without creating a Git commit. Each materially changed scope advances its own persisted revision exactly once; Global and CWD revisions are shared across their writers, Session is private, and Effective is represented by the `G#/C#/S#` revision vector rather than an invented scalar owner. After an accepted turn reconciles its response and reaches `agent_before_settle`, one best-effort backup may commit only State Flow-owned already-written files. Acquire the backup mutex before briefly locking canonical storage for bounded root/CWD/session namespace inventory and regular-file byte capture; canonical writers never acquire the backup mutex. Release the canonical lock before every Git command, filter, staging write, ref update, or index synchronization. Stage only the captured snapshot through a private temporary worktree/index, preserve Git ignore/filter policy, and never inventory artifact sources or unrelated directory trees. Keep unrelated staged/index-only content and worktree edits intact; synchronize only exact owned index paths, include HEAD-owned deletions even when already absent from the caller index, and never create an unowned-only initial backup. Backup failure is diagnostic-only and never rolls back state, suppresses an answer, requests continuation, or blocks a later turn. After each successful backup attempt, asynchronously push the exact current commit to the attached branch's explicitly configured remote/ref without force. Push failure is visible but has no semantic effect; a later accepted turn retries the latest backup. Durable push queues, publication workers, worker leases, and remote retry generations do not exist.
+- Every accepted semantic change, including session-only and response-only changes, atomically updates affected canonical checkpoint/tail pairs and temporal metadata without creating a Git commit. Each materially changed scope advances its own persisted revision exactly once; Global and CWD revisions are shared across their writers, Session is private, and Effective is represented by the `G#/C#/S#` revision vector rather than an invented scalar owner. After an accepted turn reconciles its response and reaches `agent_before_settle`, one best-effort backup may commit only State Flow-owned already-written files. Acquire the backup mutex before briefly locking canonical storage for bounded root/CWD/session namespace inventory and regular-file byte capture; canonical writers never acquire the backup mutex. Release the canonical lock before every Git command, filter, staging write, ref update, or index synchronization. Stage only the captured snapshot through a private temporary worktree/index, preserve Git ignore/filter policy, and never inventory artifact sources or unrelated directory trees. Keep unrelated staged/index-only content and worktree edits intact; synchronize only exact owned index paths, include HEAD-owned deletions even when already absent from the caller index, and never create an unowned-only initial backup. Backup failure is diagnostic-only and never rolls back state, suppresses an answer, requests continuation, or blocks a later turn. After each successful backup attempt, asynchronously push the exact current commit to the attached branch's explicitly configured remote/ref without force. Permit at most one in-flight push per repository root in process; skip overlapping attempts, leaving a later accepted turn to push the latest HEAD. Session shutdown waits for the in-flight process to close, within the existing Git push timeout and termination behavior; suppress push-failure reporting after shutdown begins. Push failure has no semantic effect; while active, warn once per failure streak with a concise message and reset suppression after successful replication. Record the available redacted Git failure detail in the local diagnostic log even when general logging is off; if local recording fails, warn once with the available detail. A later accepted turn retries the latest backup. Durable push queues, publication workers, worker leases, and remote retry generations do not exist.
 - Register `patch_state` as the sole model-authored semantic mutation protocol. Its canonical grammar accepts one or more fixed `global`, `cwd`, and `session` semantic patches; reject unknown fields, empty supplied scopes, material no-ops, and retired finalization or `{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`.
 - 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. The next inference sees rematerialized state. Ordinary accepted answers require no finalization patch or fallback inference.
 - Reconcile `response` only from the actually accepted ordinary assistant answer at `turn_end`; it remains runtime-owned, and an accepted empty answer reconciles to `""` rather than causing a finalization failure. State Flow has no terminal HTML-comment mutation protocol and does not parse generic service comments. Other extensions retain ownership of their own comments and output handling.
@@ -31,7 +31,7 @@
 - Recognize Skill acquisition only when a successful finalized `read` path exactly matches a registered Pi Skill exposed by the public `getCommands()` resource metadata. Map `sourceInfo.scope` deterministically as user → global, project → CWD, and temporary → session; never infer ownership from path shape. Hash the executed source bytes. Matching current provenance creates no acquisition request. Otherwise append a concise tool-result hint naming the exact target, but keep the read volatile unless the model supplies durable compiler output; pending acquisition never blocks an unrelated semantic patch or ordinary completion. Validate an attempted compilation at the reported scope/path with non-empty `description`, `kind: "skill"`, and flexible non-empty `compilation`, then record runtime-owned `sourceHash` plus `skill-artifact-v1` `compilerRevision` in that scope's provenance. Replace the complete prior Skill artifact and provenance on refresh so obsolete evidence cannot survive. Unregistered `SKILL.md` reads have no acquisition semantics. `contract.compiled_skills` is retired and rejected; never fabricate hashes or bypass explicit source acquisition.
 - 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. Dedicated cleanup and scope audits require an explicit user request; a feature/release/project boundary may motivate a recommendation, not an automatic audit. For a proven move within one store, inspect both owners, resolve conflicts, apply destination/source changes through one atomic multi-scope patch, and verify both owners plus the effective overlay. External transfers require destination-native acceptance verification before source deletion. 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 and require at least one material semantic or provenance change. When no state change is needed, do not call `patch_state`. Accept the exact ordinary answer, including an empty string, 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 response-finalization failures. Every rejected call retains its exact attempted arguments plus the precise error and, when available, tool identity and call id; successful patches and accepted answers 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 enablement or accepted state.
+- Agent-level opt-in `logging` appends local JSONL diagnostics for rejected `patch_state` attempts and response-finalization failures; asynchronous Git push failures are logged there even without opt-in so terse interactive warnings retain local detail. Every rejected call retains its exact attempted arguments plus the precise error and, when available, tool identity and call id; successful patches and accepted answers 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 enablement or accepted state.
 - Keep `applyPatch` results and staged mutable drafts detached from caller patches and accepted scopes. Detach once at the public patch boundary; private owned-draft COW may share untouched paths only within that isolated basis. Clone incoming replacements, detach inherited objects before preserving their merge behavior, and retain late-response/artifact mutation isolation. Do not trade CAS, publication rollback or public/historical read isolation for cross-boundary sharing.
 - Recursively materialize patches immediately; empty objects preserve, nested object-key `null` deletes, and `null` anywhere in semantic state including arrays is invalid. This prohibition does not apply to runtime envelopes such as an origin's null parent. Persist runtime-normalized replay patches that exactly reproduce accepted state, including complete artifact replacement; runtime-owned provenance is stored in scope `meta.json` and is not part of semantic replay.
 - Do not impose project schemas, state or patch byte caps, dynamic growth pressure, observation envelopes, action authorization, action ledgers, or state-size limits.

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

@@ -2,6 +2,12 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.18.1: Backup Reliability
+
+- `Push lifecycle`: Bounds backup replication to one in-flight push per repository, skips overlap until a later accepted turn, and awaits process closure at session shutdown under the existing push timeout. Suppresses failure reporting after shutdown starts; test fixtures settle pushes before cleanup. Canonical acceptance stays independent of Git replication.
+- `Push diagnostics`: Repeated asynchronous push failures produce one concise warning per failure streak until a successful push. Available redacted Git errors are recorded locally even without general logging; an unavailable diagnostic log falls back to one warning with the failure detail. Canonical acceptance and later-turn retry are unchanged.
+- `Prompt-prefix evidence`: Version 3 synthetic benchmark reports each inference's serialized context size and within-run shared byte prefix, accepted patch barriers, and matching native user/specification value sizes for State Flow and native Pi, including isolated resume probes. A source-bound local sample and regression coverage inform a later projection decision without changing 0.18.1 model behavior.
+
 ## 0.18.0: Independent Revisions and Replicated Backups
 
 - `Independent scope revisions`: Persists independent Global, CWD and Session semantic counters. Each materially changed scope advances once per atomic cohort; no-ops advance none, Session owns response changes, folding preserves counts, and pre-revision 0.17 stores start from retained-tail evidence. Effective uses the truthful `G#/C#/S#` vector rather than a scalar observer count. Metadata v2 keeps v1 readable and fences older writers after a revision-aware scope write.

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

@@ -124,11 +124,11 @@ Array ranges, structural `keys` reads and path-intersected `patch` projections s
 
 The default store is `~/.pi/agent/state-flow/`, independent of registered source files. Canonical `checkpoint.json`, `patches.jsonl` and `meta.json` files hold each scope's state, retained changes and metadata; session configuration and runtime identity are stored separately.
 
-**Git backups are optional.** When the store is a configured Git repository, accepted active turns may create versioned backups of State Flow-owned files. If the attached branch has an explicitly configured remote, State Flow then pushes the exact current backup commit there asynchronously and without force. Commit or push failure produces a warning without rejecting or rolling back accepted memory; a later accepted turn tries the latest backup again. Backup needs a Git commit identity, but accepting and persisting state does not. Git history can be inspected separately, but it is not the authority for `read_state` or automatic restoration of expired semantic boundaries.
+**Git backups are optional.** When the store is a configured Git repository, accepted active turns may create versioned backups of State Flow-owned files. If the attached branch has an explicitly configured remote, State Flow then pushes the exact current backup commit there asynchronously and without force. Within one Pi process, only one push per repository can run at a time; overlapping attempts are skipped and a later accepted turn pushes the latest backup. Session shutdown waits for that repository's active push to close or time out. Commit failures warn locally; repeated push failures produce one concise warning until a successful push, with redacted Git detail kept in the local diagnostic log. Neither failure rejects or rolls back accepted memory. Backup needs a Git commit identity, but accepting and persisting state does not. Git history can be inspected separately, but it is not the authority for `read_state` or automatic restoration of expired semantic boundaries.
 
 Resume and tree navigation restore the selected retained session boundary over current shared global/CWD memory. A new session gets its own session layer. Supported native forks copy selected session state into a new owner without changing the parent's private data. Expired, incomplete or contradictory boundaries fail closed rather than silently substituting newer state. See [fork support](docs/usage.md#fork-support-and-limits) and [storage recovery](docs/usage.md#storage-and-recovery).
 
-Version 0.17 accepts only the current canonical storage contract and has no in-place predecessor converter. Preserve existing data and check the [format boundary](docs/usage.md#moving-a-store-and-the-017-format-boundary) before changing versions or moving a store.
+The canonical storage-format boundary introduced in 0.17 still applies: current versions accept only the canonical store contract and provide no in-place predecessor converter. Preserve existing data and check the [format boundary](docs/usage.md#moving-a-store-and-the-017-format-boundary) before changing versions or moving a store.
 
 ## Operational boundaries
 

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

@@ -12,7 +12,7 @@ import { createPassiveContinuation, currentRunTrajectory, lazyNavigationHint, pa
 import { readNativeSessionHeader } from "./continuation.js";
 import { cwdScopeKey, resolveSessionAddress, sessionScopeKey, } from "./durable.js";
 import { completeRun, prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.js";
-import { backupCurrentStateFlowFiles, pushCurrentStateFlowBackup } from "./git.js";
+import { awaitInFlightBackupPushes, backupCurrentStateFlowFiles, startStateFlowBackupPush } from "./git.js";
 import { projectRecentTransitionsWithLimit } from "./history.js";
 import { isObject, presentationJson, sameJson } from "./json.js";
 import { StateFlowDiagnosticWriter, stateFlowLogPath } from "./logging.js";
@@ -62,6 +62,8 @@ export default function stateFlowExtension(pi, options = {}) {
     const repositoryRoot = resolve(options.repositoryRoot ?? config.directory);
     const diagnosticWriter = new StateFlowDiagnosticWriter(config.logging, stateFlowLogPath(agentDir), repositoryRoot, (message) => notifyActiveContext(message));
     let backupPending = false;
+    let shuttingDown = false;
+    let pushFailureNotified = false;
     const skillReads = new SkillReadTracker(hashSkillSource, (path) => activeContext
         ? registeredSkillResolver(activeContext.cwd, pi.getCommands())(path)
         : undefined);
@@ -932,11 +934,18 @@ export default function stateFlowExtension(pi, options = {}) {
                 backupCurrentStateFlowFiles(repositoryRoot);
                 const pushSessionId = sessionAddress(ctx).id;
                 const pushCwd = ctx.cwd;
-                void pushCurrentStateFlowBackup(repositoryRoot).catch((error) => {
+                startStateFlowBackupPush(repositoryRoot, (error) => {
+                    if (shuttingDown)
+                        return;
                     const message = error instanceof Error ? error.message : String(error);
-                    diagnosticWriter.record(pushSessionId, pushCwd, message, "publication-conflict");
-                    notifyActiveContext(`State Flow accepted canonical state; Git backup push failed: ${message}`);
-                });
+                    const recorded = diagnosticWriter.recordBackupPushFailure(pushSessionId, pushCwd, message);
+                    if (pushFailureNotified)
+                        return;
+                    pushFailureNotified = true;
+                    notifyActiveContext(recorded
+                        ? `State Flow Git backup push failed; state is saved locally. Details: ${stateFlowLogPath(agentDir)}. A later accepted turn retries.`
+                        : `State Flow Git backup push failed; local diagnostics unavailable: ${message}`);
+                }, () => { pushFailureNotified = false; });
             }
         }
         catch (error) {
@@ -980,11 +989,13 @@ export default function stateFlowExtension(pi, options = {}) {
         runAnchorTimestamp = undefined;
         restoreActiveBranch(ctx);
     });
-    pi.on("session_shutdown", (_event, _ctx) => {
+    pi.on("session_shutdown", async (_event, _ctx) => {
+        shuttingDown = true;
         telegramStartPending = false;
         compactionStopped = true;
         completedRunAccepted = false;
         activeContext = undefined;
         telegram.dispose();
+        await awaitInFlightBackupPushes(repositoryRoot);
     });
 }

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

@@ -1,5 +1,9 @@
 /** Commit only current State Flow-owned files; never changes canonical acceptance. */
 export declare function backupCurrentStateFlowFiles(repositoryRoot: string): string | undefined;
+/** Skip overlapping pushes; the next accepted turn can push the latest HEAD. */
+export declare function startStateFlowBackupPush(repositoryRoot: string, onFailure: (error: unknown) => void, onSuccess?: () => void): boolean;
+/** Resolve only after the push process has closed (including timeout termination). */
+export declare function awaitInFlightBackupPushes(repositoryRoot: string): Promise<void>;
 /** Push the current backup commit to its explicitly configured branch remote without blocking settlement. */
 export declare function pushCurrentStateFlowBackup(repositoryRoot: string): Promise<{
     commit: string;

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

@@ -7,6 +7,7 @@ import { captureOwnedFileBases, isStateFlowOwnedPath } from "./durable.js";
 import { acquirePublicationLock, withStoragePublicationLock } from "./storage.js";
 const GIT_TIMEOUT_MS = 15_000;
 const STATE_FLOW_COMMIT_TRAILER = "State-Flow-Durable: v1";
+const activePushes = new Map();
 function redactGitDiagnostic(value) {
     return value
         .replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@/gi, "$1***@")
@@ -205,6 +206,33 @@ function commitCurrentOwnedFiles(repositoryRoot, expectedHead) {
 export function backupCurrentStateFlowFiles(repositoryRoot) {
     return withBackupLock(repositoryRoot, (root) => commitCurrentOwnedFiles(root, currentHead(root)));
 }
+/** Skip overlapping pushes; the next accepted turn can push the latest HEAD. */
+export function startStateFlowBackupPush(repositoryRoot, onFailure, onSuccess) {
+    const root = resolve(repositoryRoot);
+    if (activePushes.has(root))
+        return false;
+    const push = pushCurrentStateFlowBackup(root).then((result) => {
+        if (result) {
+            try {
+                onSuccess?.();
+            }
+            catch { /* Reporting cannot change push acceptance. */ }
+        }
+    }, (error) => {
+        try {
+            onFailure(error);
+        }
+        catch { /* Reporting cannot revive a failed push. */ }
+    }).finally(() => { activePushes.delete(root); });
+    activePushes.set(root, push);
+    return true;
+}
+/** Resolve only after the push process has closed (including timeout termination). */
+export async function awaitInFlightBackupPushes(repositoryRoot) {
+    const push = activePushes.get(resolve(repositoryRoot));
+    if (push)
+        await push;
+}
 /** Push the current backup commit to its explicitly configured branch remote without blocking settlement. */
 export function pushCurrentStateFlowBackup(repositoryRoot) {
     return new Promise((resolvePush, rejectPush) => {
@@ -217,7 +245,7 @@ export function pushCurrentStateFlowBackup(repositoryRoot) {
             destination = configuredPushDestination(root);
         }
         catch (error) {
-            rejectPush(error);
+            rejectPush(new Error(redactGitDiagnostic(error instanceof Error ? error.message : String(error))));
             return;
         }
         if (commit === undefined || destination === undefined) {

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

@@ -36,4 +36,7 @@ export declare class StateFlowDiagnosticWriter {
     private readonly notify;
     constructor(enabled: boolean, path: string, repositoryRoot: string, notify: (message: string) => void);
     record(sessionId: string, cwd: string, error: string, category: StateFlowDiagnosticCategory, extras?: DiagnosticExtras): void;
+    /** Push warnings stay short; retain the available Git failure detail locally even without opt-in logging. */
+    recordBackupPushFailure(sessionId: string, cwd: string, error: string): boolean;
+    private write;
 }

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

@@ -1,5 +1,5 @@
 // Domain: opt-in diagnostic capture for rejected State Flow resolutions.
-import { appendFileSync, mkdirSync } from "node:fs";
+import { appendFileSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { isObject } from "./json.js";
 /** Preserve exact text blocks and block boundaries; reasoning bodies are never duplicated. */
@@ -18,9 +18,26 @@ export function projectDiagnosticContent(content) {
 export function stateFlowLogPath(agentDir) {
     return join(agentDir, "tmp", "state-flow", "logs.jsonl");
 }
+function ensureDiagnosticDirectory(path) {
+    if (dirname(path) !== path)
+        ensureDiagnosticDirectory(dirname(path));
+    if (!lstatSync(path, { throwIfNoEntry: false }))
+        mkdirSync(path);
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error(`State Flow diagnostic directory is not a regular directory: ${path}`);
+}
 export function appendStateFlowDiagnostic(path, record) {
-    mkdirSync(dirname(path), { recursive: true });
-    appendFileSync(path, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
+    ensureDiagnosticDirectory(dirname(path));
+    const descriptor = openSync(path, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+    try {
+        if (!fstatSync(descriptor).isFile())
+            throw new Error(`State Flow diagnostic destination is not a regular file: ${path}`);
+        appendFileSync(descriptor, `${JSON.stringify(record)}\n`, { encoding: "utf8" });
+    }
+    finally {
+        closeSync(descriptor);
+    }
 }
 /** Own diagnostic path safety, projection, persistence, and one-shot failure reporting. */
 export class StateFlowDiagnosticWriter {
@@ -38,6 +55,13 @@ export class StateFlowDiagnosticWriter {
     record(sessionId, cwd, error, category, extras = {}) {
         if (!this.enabled)
             return;
+        this.write(sessionId, cwd, error, category, extras);
+    }
+    /** Push warnings stay short; retain the available Git failure detail locally even without opt-in logging. */
+    recordBackupPushFailure(sessionId, cwd, error) {
+        return this.write(sessionId, cwd, error, "publication-conflict", {}, false);
+    }
+    write(sessionId, cwd, error, category, extras, reportFailure = true) {
         try {
             const fromRepository = relative(this.repositoryRoot, this.path);
             if (fromRepository === "" || (!isAbsolute(fromRepository) && fromRepository !== ".." && !fromRepository.startsWith(`..${sep}`))) {
@@ -54,12 +78,14 @@ export class StateFlowDiagnosticWriter {
                 ...(extras.tool === undefined ? {} : { tool: extras.tool }),
                 ...(extras.toolCallId === undefined ? {} : { toolCallId: extras.toolCallId }),
             });
+            return true;
         }
         catch (failure) {
-            if (this.warningReported)
-                return;
-            this.warningReported = true;
-            this.notify(`State Flow could not write diagnostics: ${failure instanceof Error ? failure.message : String(failure)}`);
+            if (reportFailure && !this.warningReported) {
+                this.warningReported = true;
+                this.notify(`State Flow could not write diagnostics: ${failure instanceof Error ? failure.message : String(failure)}`);
+            }
+            return false;
         }
     }
 }

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

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

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

@@ -10,7 +10,7 @@ The current repository-local stack uses Linux/x64, Node 26.8.1, Git 2.55.0, and
 
 | Pi SDK stack | Validation | Evidence status |
 | --- | --- | --- |
-| 0.87.0 | Build, typecheck, import, package dry-run, 438/438 tests | Current full-suite baseline |
+| 0.87.0 | Build, typecheck, import, package dry-run; 472/472 tests in each of five ordinary and five `push.negotiate=true` isolated-Git runs | 0.18.1 candidate source-bound acceptance (2026-09-23); not a live-provider or cross-platform claim |
 | 0.84.4 | Historical full-suite baseline | Unsupported by State Flow 0.17.0 |
 | 0.85.1 | Historical full-suite baseline | Unsupported by State Flow 0.17.0 |
 

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

@@ -22,16 +22,24 @@ BENCH_PATCHES=2 BENCH_SAMPLES=1 BENCH_ROUNDS=2 BENCH_STATE_BYTES=1024 npm run be
 
 Treat timings as observations from the named host and source identity, not universal thresholds. Compare runs only when workload fingerprints, dependencies, payloads, and validation outcomes match. A failed correctness probe invalidates its timing sample.
 
+### Within-run prompt-prefix probe (0.18.1)
+
+The v3 report records `promptPrefixRuns` for each State Flow and native Pi user run, with no duplication across lifecycle checkpoints. Per inference, `contextBytes` is the UTF-8 byte length of `JSON.stringify(context.messages)` as seen by the installed faux provider; `sharedPrefixBytes` is the longest common byte prefix of that serialization with the previous inference **in the same run**, or `null` on the first inference. Per run, `patchStateBarriers` counts successful tool completions, and `nativeUserBytes` / `specificationBytes` count JSON-serialized *string values*, excluding their containing message/field frames (`specificationBytes` is `null` for native Pi). Isolated post-resume probes expose the same per-run metrics.
+
+A bounded local sample used `BENCH_PATCHES=2 BENCH_SAMPLES=1 BENCH_ROUNDS=2 BENCH_STATE_BYTES=1024 BENCH_POST_RESUME=1 npm run benchmark` on Node 26.8.1 Linux/x64 and Pi/AI 0.87.0. The runtime-source SHA-256 was `0f4eea2394c52c6ac545260cae967a16581b8768a24a8c611c13a389e6df01a9`, workload-source SHA-256 `e9b8158d953d8622776aa075835c4aa95c98855ed5c90e85de05dccae1087e91`, base commit `5f0f688650738d4d0e9850b2529b0273c47121a8` (the measured tree had uncommitted 0.18.1 changes). Both source hashes stayed unchanged during the run and all correctness phases passed. At user run 1, native Pi's second inference shared 2,776 of 2,777 prior serialized bytes; State Flow shared 9,365 of 9,467 at inference 2 and 9,173 with inference 2 at inference 3 (one accepted barrier). In both State Flow runs, the 21-byte serialized `specification` value duplicated the 21-byte current native user string value; native Pi had no projection field. These are synthetic short-run observations, not representative cache-hit rates or timing predictions.
+
+A later 0.19 decision about freezing the projected head must compare compatible workloads and include correctness of fresh state visibility after barriers. Byte-prefix measurements omit provider framing, tool schemas, tokenization, cache policies and quality; this probe does **not** justify changing context projection in 0.18.1.
+
 ## Current cost model
 
 - Current semantic projection is proportional to projected state size.
 - Retained temporal reads are bounded by configured `historyLimit` (`0..100`, default `7`).
 - Canonical publication writes the affected scope/runtime cohort under file CAS and cooperating-writer exclusion; it executes no Git command.
 - Registered-artifact maintenance is proportional to already-registered paths and uses metadata-only `size + mtimeNs` inspection. It performs no directory discovery or generic body hashing.
-- Optional Git backup runs only after accepted work reaches `agent_before_settle`. Its canonical-lock capture costs are proportional to owned file count and bytes; all Git commands and filters run after that lock is released. Git remains synchronous within the calling settled-turn callback: independent canonical processes can publish during slow Git, but this is not a host-event-loop latency bound. Backup is not an acceptance or recovery authority.
+- Optional Git backup runs only after accepted work reaches `agent_before_settle`. Its canonical-lock capture costs are proportional to owned file count and bytes; all Git commands and filters run after that lock is released. The commit remains synchronous within the calling settled-turn callback: independent canonical processes can publish during slow Git, but this is not a host-event-loop latency bound. Remote push runs asynchronously, skips overlapping attempts per repository within one Pi process, and is awaited at session shutdown within its existing timeout and process-group termination behavior. Backup is not an acceptance or recovery authority.
 - Native transcript opening, Pi context construction, and foreign custom-context preservation remain Pi/history costs rather than canonical-state storage costs.
 
-Discarded semantic history is unavailable. Benchmarks must not count Git cold reads, revision restoration, queue workers, remote pushes, migration, terminal repair, or fallback inference; those mechanisms do not exist in the 0.17 architecture.
+Discarded semantic history is unavailable. Git cold reads, revision restoration, queue workers, migration, terminal repair and fallback inference are absent from the current architecture. Remote pushes do exist but are asynchronous and outside these local benchmark workloads; do not count them as measured costs.
 
 ## Tool-preflight parent traversal
 

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

@@ -46,7 +46,7 @@ The canonical store is `state-flow/` beneath the agent directory. Keeping config
 - `autoStart`: Defaults to `false`. When `true`, genuinely new sessions use the same initialization as explicit Start, including fresh CWDs.
 - `passiveBootstrap`: Defaults to `true`. Projects existing effective durable memory into ordinary model context without creating scopes, publishing, or starting an episode.
 - `passiveTools`: Defaults to `true`. Exposes `read_state` and `patch_state` outside active episodes. Reads remain side-effect free; the first explicit patch may initialize absent canonical storage but never converts predecessor formats or enables an episode or State Flow compaction.
-- `logging`: Defaults to `false`. When enabled, records rejected patches and accepted-answer reconciliation failures locally at `tmp/state-flow/logs.jsonl` beneath the agent directory.
+- `logging`: Defaults to `false`. When enabled, records rejected patches and accepted-answer reconciliation failures locally at `tmp/state-flow/logs.jsonl` beneath the agent directory. Asynchronous Git push failures are recorded there even when this setting is off.
 - `showSuccessfulPatches`: Defaults to `true`. In interactive Pi, successful `patch_state` rows show only the applied pretty-printed JSON arguments, with blank lines between adjacent memory sections; set it to `false` to keep only the compact summary. Rejected calls still use ordinary error rendering; State Flow adds no private validation turn.
 - `historyLimit`: Defaults to `7` and accepts integers from `0` through `100`. It bounds materialized-history and scope patch-history offsets. Lowering it on reload/restore/fork folds excess tails forward without losing current state; selected boundaries outside the new window are unavailable. Zero retains only current checkpoints. Raising the limit affects only future retention and cannot reconstruct discarded history.
 
@@ -56,7 +56,7 @@ Settings are read once at extension load. After editing, use `/reload` or restar
 
 ### Diagnostic logging and privacy
 
-Rejected-call records may contain exact attempted arguments and useful draft text, plus the error category and tool/call identity. Successful patches are not logged; reasoning bodies are excluded. Logs are not semantic state, scope metadata, Pi checkpoints, or publication input. If the log path overlaps a custom state repository, capture fails closed instead of committing it. A logging failure changes no accepted state and produces at most one local warning.
+Rejected-call records may contain exact attempted arguments and useful draft text, plus the error category and tool/call identity. Asynchronous push failures retain the available redacted Git error there regardless of `logging`; interactive warnings stay short and appear once per failure streak, then reset on success. If logging the push failure is unavailable, one warning exposes the available detail instead. Successful patches are not logged; reasoning bodies are excluded. Logs are not semantic state, scope metadata, Pi checkpoints, or publication input. If the log path overlaps a custom state repository, capture fails closed instead of committing it. A logging failure changes no accepted state and produces at most one local warning.
 
 Logs remain local unless you move them; rotation/deletion is operator-owned. Treat them and state files as private. Removing a secret from current state does not erase older offsets, Git history, native sessions, or remote copies.
 
@@ -98,13 +98,13 @@ Missing artifact provenance inside an otherwise complete scope `meta.json` means
 
 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. 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.
+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. Within one Pi process, an in-flight push per repository skips overlapping attempts; a later accepted turn retries the latest backup without a durable queue. Session shutdown waits for that repository's in-flight push to close or time out, suppressing push-failure reporting after shutdown begins. Commit or push failure is diagnostic-only; repeated push failures warn once per failure streak and remain locally diagnosable. 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. 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.
+Starting with 0.17, State Flow accepts only its canonical checkpoint/tail, temporal metadata, and separate session config/runtime contract; that boundary still applies to current versions. 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/lib/extension.ts

@@ -25,7 +25,7 @@ import {
   type SessionAddress,
 } from "./durable.ts";
 import { completeRun, prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.ts";
-import { backupCurrentStateFlowFiles, pushCurrentStateFlowBackup } from "./git.ts";
+import { awaitInFlightBackupPushes, backupCurrentStateFlowFiles, startStateFlowBackupPush } from "./git.ts";
 import { projectRecentTransitionsWithLimit } from "./history.ts";
 import { isObject, presentationJson, sameJson, type JsonObject } from "./json.ts";
 import { StateFlowDiagnosticWriter, stateFlowLogPath, type DiagnosticExtras, type StateFlowDiagnosticCategory } from "./logging.ts";
@@ -88,6 +88,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	const repositoryRoot = resolve(options.repositoryRoot ?? config.directory);
 	const diagnosticWriter = new StateFlowDiagnosticWriter(config.logging, stateFlowLogPath(agentDir), repositoryRoot, (message) => notifyActiveContext(message));
 	let backupPending = false;
+	let shuttingDown = false;
+	let pushFailureNotified = false;
 	const skillReads = new SkillReadTracker(hashSkillSource, (path) => activeContext
 		? registeredSkillResolver(activeContext.cwd, pi.getCommands())(path)
 		: undefined);
@@ -935,11 +937,16 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				backupCurrentStateFlowFiles(repositoryRoot);
 				const pushSessionId = sessionAddress(ctx).id;
 				const pushCwd = ctx.cwd;
-				void pushCurrentStateFlowBackup(repositoryRoot).catch((error) => {
+				startStateFlowBackupPush(repositoryRoot, (error) => {
+					if (shuttingDown) return;
 					const message = error instanceof Error ? error.message : String(error);
-					diagnosticWriter.record(pushSessionId, pushCwd, message, "publication-conflict");
-					notifyActiveContext(`State Flow accepted canonical state; Git backup push failed: ${message}`);
-				});
+					const recorded = diagnosticWriter.recordBackupPushFailure(pushSessionId, pushCwd, message);
+					if (pushFailureNotified) return;
+					pushFailureNotified = true;
+					notifyActiveContext(recorded
+						? `State Flow Git backup push failed; state is saved locally. Details: ${stateFlowLogPath(agentDir)}. A later accepted turn retries.`
+						: `State Flow Git backup push failed; local diagnostics unavailable: ${message}`);
+				}, () => { pushFailureNotified = false; });
 			}
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
@@ -981,11 +988,13 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		runAnchorTimestamp = undefined;
 		restoreActiveBranch(ctx);
 	});
-	pi.on("session_shutdown", (_event, _ctx) => {
+	pi.on("session_shutdown", async (_event, _ctx) => {
+		shuttingDown = true;
 		telegramStartPending = false;
 		compactionStopped = true;
 		completedRunAccepted = false;
 		activeContext = undefined;
 		telegram.dispose();
+		await awaitInFlightBackupPushes(repositoryRoot);
 	});
 }

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

@@ -8,6 +8,7 @@ import { acquirePublicationLock, withStoragePublicationLock } from "./storage.ts
 
 const GIT_TIMEOUT_MS = 15_000;
 const STATE_FLOW_COMMIT_TRAILER = "State-Flow-Durable: v1";
+const activePushes = new Map<string, Promise<void>>();
 
 function redactGitDiagnostic(value: string): string {
 	return value
@@ -206,6 +207,28 @@ export function backupCurrentStateFlowFiles(repositoryRoot: string): string | un
 	return withBackupLock(repositoryRoot, (root) => commitCurrentOwnedFiles(root, currentHead(root)));
 }
 
+/** Skip overlapping pushes; the next accepted turn can push the latest HEAD. */
+export function startStateFlowBackupPush(repositoryRoot: string, onFailure: (error: unknown) => void, onSuccess?: () => void): boolean {
+	const root = resolve(repositoryRoot);
+	if (activePushes.has(root)) return false;
+	const push = pushCurrentStateFlowBackup(root).then(
+		(result) => {
+			if (result) { try { onSuccess?.(); } catch { /* Reporting cannot change push acceptance. */ } }
+		},
+		(error) => {
+			try { onFailure(error); } catch { /* Reporting cannot revive a failed push. */ }
+		},
+	).finally(() => { activePushes.delete(root); });
+	activePushes.set(root, push);
+	return true;
+}
+
+/** Resolve only after the push process has closed (including timeout termination). */
+export async function awaitInFlightBackupPushes(repositoryRoot: string): Promise<void> {
+	const push = activePushes.get(resolve(repositoryRoot));
+	if (push) await push;
+}
+
 /** Push the current backup commit to its explicitly configured branch remote without blocking settlement. */
 export function pushCurrentStateFlowBackup(repositoryRoot: string): Promise<{ commit: string; remote: string; ref: string } | undefined> {
 	return new Promise((resolvePush, rejectPush) => {
@@ -217,7 +240,7 @@ export function pushCurrentStateFlowBackup(repositoryRoot: string): Promise<{ co
 			commit = currentHead(root);
 			destination = configuredPushDestination(root);
 		} catch (error) {
-			rejectPush(error);
+			rejectPush(new Error(redactGitDiagnostic(error instanceof Error ? error.message : String(error))));
 			return;
 		}
 		if (commit === undefined || destination === undefined) {

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

@@ -1,5 +1,5 @@
 // Domain: opt-in diagnostic capture for rejected State Flow resolutions.
-import { appendFileSync, mkdirSync } from "node:fs";
+import { appendFileSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { isObject } from "./json.ts";
 
@@ -39,9 +39,22 @@ export function stateFlowLogPath(agentDir: string): string {
 	return join(agentDir, "tmp", "state-flow", "logs.jsonl");
 }
 
+function ensureDiagnosticDirectory(path: string): void {
+	if (dirname(path) !== path) ensureDiagnosticDirectory(dirname(path));
+	if (!lstatSync(path, { throwIfNoEntry: false })) mkdirSync(path);
+	const stat = lstatSync(path);
+	if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`State Flow diagnostic directory is not a regular directory: ${path}`);
+}
+
 export function appendStateFlowDiagnostic(path: string, record: StateFlowDiagnosticRecord): void {
-	mkdirSync(dirname(path), { recursive: true });
-	appendFileSync(path, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
+	ensureDiagnosticDirectory(dirname(path));
+	const descriptor = openSync(path, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+	try {
+		if (!fstatSync(descriptor).isFile()) throw new Error(`State Flow diagnostic destination is not a regular file: ${path}`);
+		appendFileSync(descriptor, `${JSON.stringify(record)}\n`, { encoding: "utf8" });
+	} finally {
+		closeSync(descriptor);
+	}
 }
 
 export interface DiagnosticExtras {
@@ -68,6 +81,15 @@ export class StateFlowDiagnosticWriter {
 
 	record(sessionId: string, cwd: string, error: string, category: StateFlowDiagnosticCategory, extras: DiagnosticExtras = {}): void {
 		if (!this.enabled) return;
+		this.write(sessionId, cwd, error, category, extras);
+	}
+
+	/** Push warnings stay short; retain the available Git failure detail locally even without opt-in logging. */
+	recordBackupPushFailure(sessionId: string, cwd: string, error: string): boolean {
+		return this.write(sessionId, cwd, error, "publication-conflict", {}, false);
+	}
+
+	private write(sessionId: string, cwd: string, error: string, category: StateFlowDiagnosticCategory, extras: DiagnosticExtras, reportFailure = true): boolean {
 		try {
 			const fromRepository = relative(this.repositoryRoot, this.path);
 			if (fromRepository === "" || (!isAbsolute(fromRepository) && fromRepository !== ".." && !fromRepository.startsWith(`..${sep}`))) {
@@ -84,10 +106,13 @@ export class StateFlowDiagnosticWriter {
 				...(extras.tool === undefined ? {} : { tool: extras.tool }),
 				...(extras.toolCallId === undefined ? {} : { toolCallId: extras.toolCallId }),
 			});
+			return true;
 		} catch (failure) {
-			if (this.warningReported) return;
-			this.warningReported = true;
-			this.notify(`State Flow could not write diagnostics: ${failure instanceof Error ? failure.message : String(failure)}`);
+			if (reportFailure && !this.warningReported) {
+				this.warningReported = true;
+				this.notify(`State Flow could not write diagnostics: ${failure instanceof Error ? failure.message : String(failure)}`);
+			}
+			return false;
 		}
 	}
 }

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

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