@llblab/pi-state-flow 0.17.4 → 0.18.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/usage.md CHANGED
@@ -46,7 +46,7 @@ The canonical store is `state-flow/` beneath the agent directory. Keeping config
46
46
  - `autoStart`: Defaults to `false`. When `true`, genuinely new sessions use the same initialization as explicit Start, including fresh CWDs.
47
47
  - `passiveBootstrap`: Defaults to `true`. Projects existing effective durable memory into ordinary model context without creating scopes, publishing, or starting an episode.
48
48
  - `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.
49
- - `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.
49
+ - `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.
50
50
  - `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.
51
51
  - `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.
52
52
 
@@ -56,7 +56,7 @@ Settings are read once at extension load. After editing, use `/reload` or restar
56
56
 
57
57
  ### Diagnostic logging and privacy
58
58
 
59
- 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.
59
+ 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.
60
60
 
61
61
  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.
62
62
 
@@ -64,14 +64,14 @@ Logs remain local unless you move them; rotation/deletion is operator-owned. Tre
64
64
 
65
65
  `/state-flow-status` separates runtime configuration/metadata from semantic state. It reports:
66
66
 
67
- - Selected CWD/session keys, step, temporal head, recovery failures, and available hot history.
67
+ - Selected CWD/session keys, internal step, independent scope revisions, temporal head, recovery failures, and available hot history.
68
68
  - 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.
69
69
  - Already-known runtime hints or pending artifact invalidations; status does not discover or validate sources.
70
70
  - Memory-bearing scopes. Promotion-shaped values receive no special interpretation.
71
71
 
72
72
  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.
73
73
 
74
- 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).
74
+ 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).
75
75
 
76
76
  ## Storage and recovery
77
77
 
@@ -92,19 +92,19 @@ Exactly one surviving pair member is corruption and fails closed. Present malfor
92
92
 
93
93
  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.
94
94
 
95
- 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).
95
+ 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).
96
96
 
97
97
  ### Canonical files and optional Git backup
98
98
 
99
99
  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.
100
100
 
101
- 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.
101
+ 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.
102
102
 
103
103
  ### Moving a store and the 0.17 format boundary
104
104
 
105
105
  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.
106
106
 
107
- 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.
107
+ 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.
108
108
 
109
109
  ### Conflicts and interrupted publication
110
110
 
package/index.ts CHANGED
@@ -71,7 +71,7 @@ export {
71
71
  temporalStateFileUpdates, type ScopeStreamSources, type TemporalScopePaths
72
72
  } from "./lib/durable.ts";
73
73
  export { default, PATCH_STATE_TOOL_NAME, READ_STATE_TOOL_NAME, type StateFlowExtensionOptions } from "./lib/extension.ts";
74
- export { backupCurrentStateFlowFiles } from "./lib/git.ts";
74
+ export { backupCurrentStateFlowFiles, pushCurrentStateFlowBackup } from "./lib/git.ts";
75
75
  export {
76
76
  createAcceptedTransition,
77
77
  DEFAULT_HISTORY_LIMIT,
@@ -139,5 +139,5 @@ export {
139
139
  type StateFlowTelegramSnapshot,
140
140
  type StateFlowTelegramView
141
141
  } from "./lib/telegram.ts";
142
- export { advanceTemporalState, readTemporalState, type TemporalState } from "./lib/temporal.ts";
142
+ export { advanceTemporalState, readTemporalState, temporalScopeRevisions, type ScopeRevisions, type TemporalState } from "./lib/temporal.ts";
143
143
  export { parseStateReadPath, readStatePath, type StateReadQuery, type StateReadResult } from "./lib/query.ts";
package/lib/durable.ts CHANGED
@@ -50,6 +50,7 @@ export function hasCwdMaterialization(cwd: string, repositoryRoot: string): bool
50
50
  }
51
51
 
52
52
  export interface ScopeTemporalMetadata {
53
+ revision: number;
53
54
  checkpoint: ScopeStream["checkpoint"]["through"];
54
55
  patches: ScopeStream["patches"][number]["transition"][];
55
56
  }
@@ -68,6 +69,7 @@ export function serializeScopeStream(stream: ScopeStream, scope: StateScope, cwd
68
69
  checkpoint: `${canonicalJson(stream.checkpoint.state)}\n`,
69
70
  patches: stream.patches.map((record) => `${canonicalJson(record.patch)}\n`).join(""),
70
71
  temporal: {
72
+ revision: stream.revision,
71
73
  checkpoint: structuredClone(stream.checkpoint.through),
72
74
  patches: stream.patches.map((record) => structuredClone(record.transition)),
73
75
  },
@@ -124,6 +126,9 @@ export function classifyScopeStream(
124
126
  const boundaries = temporal.patches;
125
127
  if (boundaries.length !== patches.length) throw new Error(`State Flow ${scope} temporal metadata does not match its semantic tail`);
126
128
  const stream = {
129
+ // 0.17.4 and earlier did not persist scope revisions. Credit only their still-retained
130
+ // semantic tail; discarded ancestry cannot be reconstructed without inventing history.
131
+ revision: temporal.revision === undefined ? patches.length : temporal.revision,
127
132
  checkpoint: { through: temporal.checkpoint, state: checkpoint },
128
133
  patches: patches.map((patch, index) => ({ transition: boundaries[index], patch })),
129
134
  };
@@ -219,7 +224,7 @@ export function serializeScopeMetadata(
219
224
  const sources = serializeScopeStream(stream, scope, cwdIdentity);
220
225
  const value = {
221
226
  ...existing,
222
- version: 1,
227
+ version: 2,
223
228
  ...(registry === undefined ? {} : { artifacts: serializeArtifactProvenanceRegistry(registry) }),
224
229
  temporal: sources.temporal,
225
230
  ...(scope === "cwd" ? { owner: { cwd: resolve(cwdIdentity!) } } : {}),
@@ -229,7 +234,7 @@ export function serializeScopeMetadata(
229
234
 
230
235
  /** Compatibility serializer retained for metadata-only callers. */
231
236
  export function serializeScopeProvenance(registry: Readonly<ArtifactProvenanceRegistry>): string {
232
- return `${canonicalJson({ version: 1, artifacts: serializeArtifactProvenanceRegistry(registry) })}\n`;
237
+ return `${canonicalJson({ version: 2, artifacts: serializeArtifactProvenanceRegistry(registry) })}\n`;
233
238
  }
234
239
 
235
240
  function parseMetadataDocument(source: string | undefined, label: string): Record<string, unknown> {
@@ -245,7 +250,7 @@ function parseMetadataDocument(source: string | undefined, label: string): Recor
245
250
  export function parseScopeProvenance(source: string | undefined, path: string): ArtifactProvenanceRegistry {
246
251
  const value = parseMetadataDocument(source, `State Flow provenance file: ${path}`);
247
252
  if (Object.keys(value).length === 0) return {};
248
- if (value.version !== 1) throw new Error(`Invalid State Flow provenance document: ${path}`);
253
+ if (value.version !== 1 && value.version !== 2) throw new Error(`Invalid State Flow provenance document: ${path}`);
249
254
  if (!Object.hasOwn(value, "artifacts")) return {};
250
255
  return parseArtifactProvenanceRegistry(value.artifacts, `State Flow provenance at ${path}`);
251
256
  }
package/lib/extension.ts CHANGED
@@ -25,7 +25,7 @@ import {
25
25
  type SessionAddress,
26
26
  } from "./durable.ts";
27
27
  import { completeRun, prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.ts";
28
- import { backupCurrentStateFlowFiles } from "./git.ts";
28
+ import { awaitInFlightBackupPushes, backupCurrentStateFlowFiles, startStateFlowBackupPush } from "./git.ts";
29
29
  import { projectRecentTransitionsWithLimit } from "./history.ts";
30
30
  import { isObject, presentationJson, sameJson, type JsonObject } from "./json.ts";
31
31
  import { StateFlowDiagnosticWriter, stateFlowLogPath, type DiagnosticExtras, type StateFlowDiagnosticCategory } from "./logging.ts";
@@ -40,6 +40,7 @@ import { emptySnapshot, migrationFailure, type Snapshot } from "./snapshot.ts";
40
40
  import { emptyState, overlayStates, projectStateForModel, type AtomicScopePatches, type MaterializedState, type ModelState, type ScopedStates, type StateScope } from "./state.ts";
41
41
  import { compactStatus, detailedStatus, STATUS_KEY, type StatusDiagnostics } from "./status.ts";
42
42
  import { createStateFlowTelegramAdapter, type StateFlowTelegramControlResult, type StateFlowTelegramLoader, type StateFlowTelegramScope } from "./telegram.ts";
43
+ import { temporalScopeRevisions, type ScopeRevisions } from "./temporal.ts";
43
44
  import { commitScopedTransition, stageAtomicScopePatches, stageScopedTransition, type StagedScopedTransition } from "./transition.ts";
44
45
 
45
46
  export interface StateFlowExtensionOptions {
@@ -85,8 +86,10 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
85
86
  let activeContext: ExtensionContext | undefined;
86
87
  let rehydrationPhase: RehydrationPhase | undefined;
87
88
  const repositoryRoot = resolve(options.repositoryRoot ?? config.directory);
88
- const diagnosticWriter = new StateFlowDiagnosticWriter(config.logging, stateFlowLogPath(agentDir), repositoryRoot, (message) => activeContext?.ui.notify(message, "warning"));
89
+ const diagnosticWriter = new StateFlowDiagnosticWriter(config.logging, stateFlowLogPath(agentDir), repositoryRoot, (message) => notifyActiveContext(message));
89
90
  let backupPending = false;
91
+ let shuttingDown = false;
92
+ let pushFailureNotified = false;
90
93
  const skillReads = new SkillReadTracker(hashSkillSource, (path) => activeContext
91
94
  ? registeredSkillResolver(activeContext.cwd, pi.getCommands())(path)
92
95
  : undefined);
@@ -100,6 +103,14 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
100
103
  return resolveSessionAddress(ctx.sessionManager.getSessionFile(), ctx.sessionManager.getSessionId(), ctx.sessionManager.getHeader()?.timestamp);
101
104
  }
102
105
 
106
+ function notifyActiveContext(message: string): void {
107
+ try {
108
+ activeContext?.ui.notify(message, "warning");
109
+ } catch {
110
+ // An asynchronous push attempt can outlive the Pi context that launched it.
111
+ }
112
+ }
113
+
103
114
  function createRuntime(ctx: ExtensionContext): TemporalRuntime {
104
115
  return new TemporalRuntime(ctx.cwd, sessionAddress(ctx), repositoryRoot, undefined, config.historyLimit);
105
116
  }
@@ -134,8 +145,14 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
134
145
  if ("boundary" in checkpoint) branchStartsWithoutRuntime = false;
135
146
  }
136
147
 
148
+ function scopeRevisions(): ScopeRevisions {
149
+ return runtime?.view
150
+ ? temporalScopeRevisions(runtime.view)
151
+ : { global: 0, cwd: 0, session: 0 };
152
+ }
153
+
137
154
  function updateUi(ctx: ExtensionContext): void {
138
- ctx.ui.setStatus(STATUS_KEY, compactStatus(snapshot, (color, text) => ctx.ui.theme.fg(color, text)));
155
+ ctx.ui.setStatus(STATUS_KEY, compactStatus(snapshot, scopeRevisions(), (color, text) => ctx.ui.theme.fg(color, text)));
139
156
  }
140
157
 
141
158
  function clearRunTransient(): void {
@@ -202,6 +219,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
202
219
  if (Object.keys(removals).length > 0) {
203
220
  const stage = stageAtomicScopePatches(scopeStates, removals, [], runtime.causalBasis());
204
221
  commitStage(stage, ctx, false);
222
+ updateUi(ctx);
205
223
  }
206
224
  refreshArtifactHints();
207
225
  }
@@ -217,10 +235,13 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
217
235
 
218
236
  function refreshTelegramStateView(scope: StateFlowTelegramScope): void {
219
237
  if (scope === "session" || scope === "effective") assertSelectedBranchAvailable();
220
- if (runtime?.view) return;
221
- if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
222
- runtime ??= createRuntime(activeContext);
223
- runtime.loadPassive();
238
+ if (!runtime?.view) {
239
+ if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
240
+ runtime ??= createRuntime(activeContext);
241
+ runtime.loadPassive();
242
+ } else if (scope !== "session") {
243
+ runtime.refreshShared();
244
+ }
224
245
  installScopeStates();
225
246
  }
226
247
 
@@ -319,6 +340,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
319
340
  head: structuredClone(view.lineage.at(-1)!),
320
341
  historyDepth: view.lineage.length - 1,
321
342
  tailCounts: { global: view.scopes.global.patches.length, cwd: view.scopes.cwd.patches.length, session: view.scopes.session.patches.length },
343
+ revisions: temporalScopeRevisions(view),
322
344
  } }),
323
345
  staleArtifacts,
324
346
  ...(durableStateError === undefined ? {} : { durableStateError }),
@@ -699,6 +721,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
699
721
  snapshot: () => ({
700
722
  enabled: snapshot.config.enabled,
701
723
  step: snapshot.meta.step,
724
+ revisions: scopeRevisions(),
702
725
  bootstrap: snapshot.meta.bootstrap === true,
703
726
  startPending: telegramStartPending,
704
727
  }),
@@ -709,6 +732,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
709
732
  : scopeStates[scope];
710
733
  return { ...projectModelState(selected), lazy: structuredClone(selected.lazy) };
711
734
  },
735
+ revisions: () => scopeRevisions(),
712
736
  canStartNow: () => activeContext === undefined || activeContext.isIdle(),
713
737
  start: () => {
714
738
  if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
@@ -909,7 +933,21 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
909
933
  if (!backupPending) return;
910
934
  backupPending = false;
911
935
  try {
912
- if (existsSync(join(repositoryRoot, ".git"))) backupCurrentStateFlowFiles(repositoryRoot);
936
+ if (existsSync(join(repositoryRoot, ".git"))) {
937
+ backupCurrentStateFlowFiles(repositoryRoot);
938
+ const pushSessionId = sessionAddress(ctx).id;
939
+ const pushCwd = ctx.cwd;
940
+ startStateFlowBackupPush(repositoryRoot, (error) => {
941
+ if (shuttingDown) return;
942
+ const message = error instanceof Error ? error.message : String(error);
943
+ const recorded = diagnosticWriter.recordBackupPushFailure(pushSessionId, pushCwd, message);
944
+ if (pushFailureNotified) return;
945
+ pushFailureNotified = true;
946
+ notifyActiveContext(recorded
947
+ ? `State Flow Git backup push failed; state is saved locally. Details: ${stateFlowLogPath(agentDir)}. A later accepted turn retries.`
948
+ : `State Flow Git backup push failed; local diagnostics unavailable: ${message}`);
949
+ }, () => { pushFailureNotified = false; });
950
+ }
913
951
  } catch (error) {
914
952
  const message = error instanceof Error ? error.message : String(error);
915
953
  recordDiagnostic(message, "publication-conflict", ctx);
@@ -950,10 +988,13 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
950
988
  runAnchorTimestamp = undefined;
951
989
  restoreActiveBranch(ctx);
952
990
  });
953
- pi.on("session_shutdown", (_event, ctx) => {
991
+ pi.on("session_shutdown", async (_event, _ctx) => {
992
+ shuttingDown = true;
954
993
  telegramStartPending = false;
955
994
  compactionStopped = true;
956
995
  completedRunAccepted = false;
996
+ activeContext = undefined;
957
997
  telegram.dispose();
998
+ await awaitInFlightBackupPushes(repositoryRoot);
958
999
  });
959
1000
  }
package/lib/git.ts CHANGED
@@ -2,12 +2,19 @@
2
2
  import { closeSync, constants, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
3
3
  import { tmpdir } from "node:os";
4
4
  import { dirname, join, relative, resolve, sep } from "node:path";
5
- import { spawnSync } from "node:child_process";
5
+ import { spawn, spawnSync } from "node:child_process";
6
6
  import { captureOwnedFileBases, isStateFlowOwnedPath } from "./durable.ts";
7
7
  import { acquirePublicationLock, withStoragePublicationLock } from "./storage.ts";
8
8
 
9
9
  const GIT_TIMEOUT_MS = 15_000;
10
10
  const STATE_FLOW_COMMIT_TRAILER = "State-Flow-Durable: v1";
11
+ const activePushes = new Map<string, Promise<void>>();
12
+
13
+ function redactGitDiagnostic(value: string): string {
14
+ return value
15
+ .replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@/gi, "$1***@")
16
+ .replace(/([?&](?:access_token|auth|password|token)=)[^&\s]+/gi, "$1***");
17
+ }
11
18
 
12
19
  interface GitResult {
13
20
  status: number;
@@ -134,6 +141,22 @@ function currentBranchRef(repositoryRoot: string): string {
134
141
  return result.stdout.trim();
135
142
  }
136
143
 
144
+ function configuredPushDestination(repositoryRoot: string): { remote: string; ref: string } | undefined {
145
+ const branchRef = currentBranchRef(repositoryRoot);
146
+ const branch = branchRef.slice("refs/heads/".length);
147
+ const configuredRemote = git(repositoryRoot, ["config", "--get", `branch.${branch}.remote`], { allowFailure: true });
148
+ if (configuredRemote.status > 1) throw new Error(configuredRemote.stderr || "Cannot inspect State Flow backup remote configuration");
149
+ if (configuredRemote.status !== 0 || configuredRemote.stdout.trim().length === 0) return undefined;
150
+ const remote = configuredRemote.stdout.trim();
151
+ if (remote === ".") throw new Error("State Flow backup replication requires a non-local Git remote");
152
+ const configuredMerge = git(repositoryRoot, ["config", "--get", `branch.${branch}.merge`], { allowFailure: true });
153
+ if (configuredMerge.status > 1) throw new Error(configuredMerge.stderr || "Cannot inspect State Flow backup branch configuration");
154
+ const ref = configuredMerge.status === 0 && configuredMerge.stdout.trim().length > 0
155
+ ? configuredMerge.stdout.trim()
156
+ : branchRef;
157
+ return { remote, ref };
158
+ }
159
+
137
160
  function commitCurrentOwnedFiles(repositoryRoot: string, expectedHead: string | undefined): string | undefined {
138
161
  const branchRef = currentBranchRef(repositoryRoot);
139
162
  if (currentHead(repositoryRoot) !== expectedHead) throw new Error("State Flow backup Git base changed concurrently");
@@ -183,3 +206,85 @@ function commitCurrentOwnedFiles(repositoryRoot: string, expectedHead: string |
183
206
  export function backupCurrentStateFlowFiles(repositoryRoot: string): string | undefined {
184
207
  return withBackupLock(repositoryRoot, (root) => commitCurrentOwnedFiles(root, currentHead(root)));
185
208
  }
209
+
210
+ /** Skip overlapping pushes; the next accepted turn can push the latest HEAD. */
211
+ export function startStateFlowBackupPush(repositoryRoot: string, onFailure: (error: unknown) => void, onSuccess?: () => void): boolean {
212
+ const root = resolve(repositoryRoot);
213
+ if (activePushes.has(root)) return false;
214
+ const push = pushCurrentStateFlowBackup(root).then(
215
+ (result) => {
216
+ if (result) { try { onSuccess?.(); } catch { /* Reporting cannot change push acceptance. */ } }
217
+ },
218
+ (error) => {
219
+ try { onFailure(error); } catch { /* Reporting cannot revive a failed push. */ }
220
+ },
221
+ ).finally(() => { activePushes.delete(root); });
222
+ activePushes.set(root, push);
223
+ return true;
224
+ }
225
+
226
+ /** Resolve only after the push process has closed (including timeout termination). */
227
+ export async function awaitInFlightBackupPushes(repositoryRoot: string): Promise<void> {
228
+ const push = activePushes.get(resolve(repositoryRoot));
229
+ if (push) await push;
230
+ }
231
+
232
+ /** Push the current backup commit to its explicitly configured branch remote without blocking settlement. */
233
+ export function pushCurrentStateFlowBackup(repositoryRoot: string): Promise<{ commit: string; remote: string; ref: string } | undefined> {
234
+ return new Promise((resolvePush, rejectPush) => {
235
+ let root: string;
236
+ let commit: string | undefined;
237
+ let destination: { remote: string; ref: string } | undefined;
238
+ try {
239
+ root = assertRepositoryRoot(repositoryRoot);
240
+ commit = currentHead(root);
241
+ destination = configuredPushDestination(root);
242
+ } catch (error) {
243
+ rejectPush(new Error(redactGitDiagnostic(error instanceof Error ? error.message : String(error))));
244
+ return;
245
+ }
246
+ if (commit === undefined || destination === undefined) {
247
+ resolvePush(undefined);
248
+ return;
249
+ }
250
+ const child = spawn("git", ["-C", root, "push", "--porcelain", "--", destination.remote, `${commit}:${destination.ref}`], {
251
+ detached: process.platform !== "win32",
252
+ stdio: ["ignore", "ignore", "pipe"],
253
+ windowsHide: true,
254
+ env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GCM_INTERACTIVE: "never" },
255
+ });
256
+ let stderr = "";
257
+ let failure: Error | undefined;
258
+ let settled = false;
259
+ function terminate(error: Error): void {
260
+ failure ??= error;
261
+ if (child.exitCode !== null || child.signalCode !== null) {
262
+ child.stderr?.destroy();
263
+ return;
264
+ }
265
+ if (!child.pid) return;
266
+ try {
267
+ if (process.platform === "win32") child.kill("SIGKILL");
268
+ else process.kill(-child.pid, "SIGKILL");
269
+ } catch {
270
+ // Keep waiting for close: signalling failure is not proof that the process ended.
271
+ }
272
+ }
273
+ const timeout = setTimeout(() => terminate(new Error(`Git backup push timed out after ${GIT_TIMEOUT_MS}ms`)), GIT_TIMEOUT_MS);
274
+ function finish(error?: Error): void {
275
+ if (settled) return;
276
+ settled = true;
277
+ clearTimeout(timeout);
278
+ if (error) rejectPush(error);
279
+ else resolvePush({ commit: commit!, ...destination! });
280
+ }
281
+ child.stderr?.on("data", (chunk: Buffer) => { stderr = (stderr + chunk.toString("utf8")).slice(-1000); });
282
+ child.on("error", (error) => {
283
+ failure ??= error;
284
+ if (!child.pid) finish(error);
285
+ });
286
+ child.once("exit", () => { if (failure) child.stderr?.destroy(); });
287
+ child.once("close", (code, endedBy) => finish(failure ?? (code === 0 ? undefined
288
+ : new Error(`Git backup push failed (${endedBy ?? code}): ${redactGitDiagnostic(stderr.trim()) || "no diagnostic output"}`))));
289
+ });
290
+ }
package/lib/logging.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  // Domain: opt-in diagnostic capture for rejected State Flow resolutions.
2
- import { appendFileSync, mkdirSync } from "node:fs";
2
+ import { appendFileSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync } from "node:fs";
3
3
  import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
4
4
  import { isObject } from "./json.ts";
5
5
 
@@ -39,9 +39,22 @@ export function stateFlowLogPath(agentDir: string): string {
39
39
  return join(agentDir, "tmp", "state-flow", "logs.jsonl");
40
40
  }
41
41
 
42
+ function ensureDiagnosticDirectory(path: string): void {
43
+ if (dirname(path) !== path) ensureDiagnosticDirectory(dirname(path));
44
+ if (!lstatSync(path, { throwIfNoEntry: false })) mkdirSync(path);
45
+ const stat = lstatSync(path);
46
+ if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`State Flow diagnostic directory is not a regular directory: ${path}`);
47
+ }
48
+
42
49
  export function appendStateFlowDiagnostic(path: string, record: StateFlowDiagnosticRecord): void {
43
- mkdirSync(dirname(path), { recursive: true });
44
- appendFileSync(path, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
50
+ ensureDiagnosticDirectory(dirname(path));
51
+ const descriptor = openSync(path, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
52
+ try {
53
+ if (!fstatSync(descriptor).isFile()) throw new Error(`State Flow diagnostic destination is not a regular file: ${path}`);
54
+ appendFileSync(descriptor, `${JSON.stringify(record)}\n`, { encoding: "utf8" });
55
+ } finally {
56
+ closeSync(descriptor);
57
+ }
45
58
  }
46
59
 
47
60
  export interface DiagnosticExtras {
@@ -68,6 +81,15 @@ export class StateFlowDiagnosticWriter {
68
81
 
69
82
  record(sessionId: string, cwd: string, error: string, category: StateFlowDiagnosticCategory, extras: DiagnosticExtras = {}): void {
70
83
  if (!this.enabled) return;
84
+ this.write(sessionId, cwd, error, category, extras);
85
+ }
86
+
87
+ /** Push warnings stay short; retain the available Git failure detail locally even without opt-in logging. */
88
+ recordBackupPushFailure(sessionId: string, cwd: string, error: string): boolean {
89
+ return this.write(sessionId, cwd, error, "publication-conflict", {}, false);
90
+ }
91
+
92
+ private write(sessionId: string, cwd: string, error: string, category: StateFlowDiagnosticCategory, extras: DiagnosticExtras, reportFailure = true): boolean {
71
93
  try {
72
94
  const fromRepository = relative(this.repositoryRoot, this.path);
73
95
  if (fromRepository === "" || (!isAbsolute(fromRepository) && fromRepository !== ".." && !fromRepository.startsWith(`..${sep}`))) {
@@ -84,10 +106,13 @@ export class StateFlowDiagnosticWriter {
84
106
  ...(extras.tool === undefined ? {} : { tool: extras.tool }),
85
107
  ...(extras.toolCallId === undefined ? {} : { toolCallId: extras.toolCallId }),
86
108
  });
109
+ return true;
87
110
  } catch (failure) {
88
- if (this.warningReported) return;
89
- this.warningReported = true;
90
- this.notify(`State Flow could not write diagnostics: ${failure instanceof Error ? failure.message : String(failure)}`);
111
+ if (reportFailure && !this.warningReported) {
112
+ this.warningReported = true;
113
+ this.notify(`State Flow could not write diagnostics: ${failure instanceof Error ? failure.message : String(failure)}`);
114
+ }
115
+ return false;
91
116
  }
92
117
  }
93
118
  }
package/lib/protocol.ts CHANGED
@@ -56,7 +56,7 @@ READ: Use read_state for concrete scope/history gaps. lazy_navigation lists boun
56
56
 
57
57
  WRITE: patch_state is the sole model-authored semantic mutation mechanism. Supply global/cwd/session patches in any combination; all supplied scopes are validated and durably accepted as one atomic transition. Call it alone in an assistant response, then continue only after its acknowledgement.
58
58
 
59
- RESPONSE: Ordinary assistant completion needs no finalization patch. Runtime reconciles the accepted non-empty answer into response at turn_end without another inference.
59
+ RESPONSE: Ordinary assistant completion needs no finalization patch. At turn_end, runtime stores the exact accepted answer; empty becomes response "".
60
60
 
61
61
  INTENTS: Keep chosen actions; detail may stay lazy. State refs use {"$ref":"cwd.lazy.plan"} or \`$cwd.lazy.plan\` in text. Resolve only when needed; infer no authority, hydration, execution, or completion. If that resolution proves a dangling state ref, fix/drop it in owning text; never scan for broken refs.
62
62
 
@@ -88,10 +88,8 @@ export function finalizedAssistantResponse(message: AgentMessage): string {
88
88
  if (message.content.some((block) => block.type === "toolCall")) {
89
89
  throw new Error("Accepted State Flow response cannot contain a tool call");
90
90
  }
91
- const response = message.content
91
+ return message.content
92
92
  .filter((block) => block.type === "text")
93
93
  .map((block) => block.text)
94
94
  .join("");
95
- if (response.trim().length === 0) throw new Error("Finalized State Flow response must contain non-empty text");
96
- return response;
97
95
  }
package/lib/runtime.ts CHANGED
@@ -415,6 +415,17 @@ export class TemporalRuntime {
415
415
  return { view: reconciledView(), base: captured, provenance };
416
416
  }
417
417
 
418
+ /** Refresh live shared scopes in memory without publishing or advancing private semantic history. */
419
+ refreshShared(): boolean {
420
+ if (!this.view || !this.base) throw new Error("State Flow shared refresh requires a selected temporal runtime");
421
+ const before = this.view;
422
+ const reconciled = this.reconcileSharedDrift(new Set());
423
+ this.view = reconciled.view;
424
+ this.base = reconciled.base;
425
+ this.provenanceByScope = reconciled.provenance;
426
+ return before !== this.view;
427
+ }
428
+
418
429
  /** Canonically accept a prepared retained-boundary origin before lifecycle-only persistence. */
419
430
  acceptRestoredOrigin(snapshot: Snapshot): RuntimePublication {
420
431
  if (!this.restoredOriginPending) throw new Error("State Flow has no prepared restored origin to accept");
package/lib/status.ts CHANGED
@@ -3,7 +3,7 @@ import { projectRecentTransitionsWithLimit, type RecentTransitionWindow } from "
3
3
  import { retainedMemoryScopes } from "./memory.ts";
4
4
  import type { Snapshot } from "./snapshot.ts";
5
5
  import { overlayStates, type ScopedStates, type StateScope } from "./state.ts";
6
- import type { TransitionBoundary } from "./temporal.ts";
6
+ import type { ScopeRevisions, TransitionBoundary } from "./temporal.ts";
7
7
 
8
8
  export const STATUS_KEY = "state-flow";
9
9
 
@@ -24,13 +24,18 @@ export interface StatusDiagnostics {
24
24
  scopeStates: ScopedStates;
25
25
  recent: RecentTransitionWindow;
26
26
  historyLimit: number;
27
- temporal?: { head: TransitionBoundary; historyDepth: number; tailCounts: Record<StateScope, number> };
27
+ temporal?: { head: TransitionBoundary; historyDepth: number; tailCounts: Record<StateScope, number>; revisions: ScopeRevisions };
28
28
  staleArtifacts: readonly StaleArtifactDiagnostic[];
29
29
  durableStateError?: string;
30
30
  }
31
31
 
32
- export function compactStatus(snapshot: Snapshot, colorize: Colorize): string {
33
- return `${colorize("accent", "state-flow")} ${colorize("dim", `#${snapshot.meta.step}`)}`;
32
+ export function formatScopeRevisionVector(revisions: ScopeRevisions): string {
33
+ return `G${revisions.global}/C${revisions.cwd}/S${revisions.session}`;
34
+ }
35
+
36
+ export function compactStatus(snapshot: Snapshot, revisions: ScopeRevisions, colorize: Colorize): string | undefined {
37
+ if (!snapshot.config.enabled) return undefined;
38
+ return `${colorize("accent", "state-flow")} ${colorize("dim", formatScopeRevisionVector(revisions))}`;
34
39
  }
35
40
 
36
41
  function countArtifacts(states: ScopedStates, scope: StateScope): number {
@@ -62,6 +67,7 @@ export function detailedStatus(snapshot: Snapshot, diagnostics: StatusDiagnostic
62
67
  `Hot history: unavailable; configured maximum depth ${diagnostics.historyLimit}`,
63
68
  "Retained patch tails: unavailable"]
64
69
  : [`Temporal head: ${JSON.stringify(temporal.head.id)}; branch-local position ${temporal.head.position}`,
70
+ `Scope revisions: global #${temporal.revisions.global}; CWD #${temporal.revisions.cwd}; session #${temporal.revisions.session}; effective ${formatScopeRevisionVector(temporal.revisions)}`,
65
71
  `Hot history: offsets 0..${temporal.historyDepth}; maximum depth ${diagnostics.historyLimit}`,
66
72
  `Retained patch tails: global ${temporal.tailCounts.global}; CWD ${temporal.tailCounts.cwd}; session ${temporal.tailCounts.session}`];
67
73
  const artifacts = (scope: StateScope) => available ? countArtifacts(diagnostics.scopeStates, scope) : "unknown";
package/lib/telegram.ts CHANGED
@@ -3,6 +3,9 @@
3
3
  // This is a leaf adapter. Core semantics, storage, and inference never depend on it; when
4
4
  // pi-telegram is absent or its registry is not ready, registration fails open and retries.
5
5
 
6
+ import { formatScopeRevisionVector } from "./status.ts";
7
+ import type { ScopeRevisions } from "./temporal.ts";
8
+
6
9
  export const STATE_FLOW_TELEGRAM_ID = "@llblab/pi-state-flow";
7
10
 
8
11
  /** Resolve the package export or the compiled sibling-extension layout used in local development. */
@@ -15,7 +18,9 @@ export function stateFlowTelegramSectionSpecifiers(moduleUrl = import.meta.url):
15
18
 
16
19
  export interface StateFlowTelegramSnapshot {
17
20
  enabled: boolean;
21
+ /** Legacy branch step retained for existing adapter ports; current runtime ports also supply owner revisions. */
18
22
  step: number;
23
+ revisions?: ScopeRevisions;
19
24
  bootstrap: boolean;
20
25
  startPending: boolean;
21
26
  }
@@ -93,6 +98,8 @@ export interface StateFlowTelegramControlResult {
93
98
  export interface StateFlowTelegramPort {
94
99
  snapshot(): StateFlowTelegramSnapshot;
95
100
  state(scope: StateFlowTelegramScope): StateFlowTelegramState;
101
+ /** Optional additive capability; absent legacy ports retain their branch-step presentation. */
102
+ revisions?(): ScopeRevisions;
96
103
  canStartNow(): boolean;
97
104
  start(): StateFlowTelegramControlResult;
98
105
  stop(): StateFlowTelegramControlResult;
@@ -107,12 +114,14 @@ export interface StateFlowTelegramAdapter {
107
114
 
108
115
  /** Main-menu section label doubles as the live status value: the spiral identity is constant, the value is not. */
109
116
  export function formatStateFlowSectionLabel(snapshot: StateFlowTelegramSnapshot): string {
110
- return `🌀 State Flow: ${stateFlowLabelValue(snapshot)}`;
117
+ if (!snapshot.enabled) return "🌀 State Flow: off";
118
+ return `🌀 State Flow: ${snapshot.revisions ? formatScopeRevisionVector(snapshot.revisions) : `#${snapshot.step}`}`;
111
119
  }
112
120
 
113
121
  /** Shared live value: plain in the button label, monospaced in the submenu state line. */
114
122
  function stateFlowLabelValue(snapshot: StateFlowTelegramSnapshot): string {
115
- return `#${snapshot.step}`;
123
+ if (!snapshot.enabled) return "off";
124
+ return snapshot.revisions ? formatScopeRevisionVector(snapshot.revisions) : `#${snapshot.step}`;
116
125
  }
117
126
 
118
127
  /** Submenu state line: the same identity as the button label, with the live value in monospace. */
@@ -191,13 +200,18 @@ function renderStateFlowTelegramField(value: unknown): string {
191
200
  return rendered;
192
201
  }
193
202
 
194
- export function renderStateFlowRichState(scope: StateFlowTelegramScope, step: number, state: StateFlowTelegramState): StateFlowTelegramRichMessage {
195
- const fields = ["intents", "contract", "working", "artifacts", "response", "lazy"] as const;
203
+ export function renderStateFlowRichState(scope: StateFlowTelegramScope, revisions: ScopeRevisions, state: StateFlowTelegramState): StateFlowTelegramRichMessage {
204
+ const fields: Array<keyof StateFlowTelegramState> = scope === "global" || scope === "cwd"
205
+ ? ["intents", "contract", "working", "artifacts", "lazy"]
206
+ : ["intents", "contract", "working", "artifacts", "response", "lazy"];
207
+ const revision = scope === "effective"
208
+ ? formatScopeRevisionVector(revisions)
209
+ : `#${revisions[scope]}`;
196
210
  return {
197
211
  blocks: [
198
212
  {
199
213
  type: "heading",
200
- text: [`${STATE_FLOW_SCOPE_LABELS[scope]}: `, { type: "code", text: `#${step}` }],
214
+ text: [`${STATE_FLOW_SCOPE_LABELS[scope]}: `, { type: "code", text: revision }],
201
215
  size: 3,
202
216
  },
203
217
  ...fields.map((field) => ({
@@ -233,7 +247,10 @@ function buildStateFlowTelegramSection(port: StateFlowTelegramPort) {
233
247
  }
234
248
  if (ctx.action === "inspect") {
235
249
  if (!isStateFlowTelegramScope(ctx.payload)) throw new Error("Unknown State Flow scope");
236
- await ctx.openRich(renderStateFlowRichState(ctx.payload, port.snapshot().step, port.state(ctx.payload)));
250
+ const state = port.state(ctx.payload);
251
+ const live = port.snapshot();
252
+ const revisions = port.revisions?.() ?? live.revisions ?? { global: live.step, cwd: live.step, session: live.step };
253
+ await ctx.openRich(renderStateFlowRichState(ctx.payload, revisions, state));
237
254
  await ctx.answerCallback();
238
255
  return "handled" as const;
239
256
  }