@llblab/pi-state-flow 0.17.3 → 0.18.0

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.
@@ -40,7 +40,7 @@ Every materialized scope has exactly this shape:
40
40
  - `contract` retains durable requirements, decisions, interfaces and rejected approaches.
41
41
  - `working` retains verified current facts, unresolved work and exact continuation.
42
42
  - `artifacts` maps exact source paths to compiled routing metadata.
43
- - `response` is the latest complete user-facing answer for the session scope.
43
+ - `response` is owned only by the session scope and stores the exact latest accepted assistant answer, including the empty string. Global and CWD retain the required key as an empty structural placeholder so canonical scopes keep one shape; the effective overlay receives `response` only from Session.
44
44
  - `lazy` is a required object root for ordinary JSON detail, omitted from baseline model state and read explicitly.
45
45
 
46
46
  Effective state recursively overlays:
@@ -67,9 +67,9 @@ The checkpoint is an older anchored materialization. The tail contains at most t
67
67
 
68
68
  Persisted streams and lineage are validated against the format maximum before applying a newly configured lower limit. Restore/reload/fork accepts only boundaries inside the configured window, then folds excess scope tails during canonical origin acceptance. That representation-only folding preserves selected private state and current shared values/provenance; a fork never rewrites parent-private files. Zero keeps only current checkpoints, and a later increase does not reconstruct discarded records or lineage.
69
69
 
70
- `effective[n]`, `global[n]`, `cwd[n]`, and `session[n]` resolve the same nth previous causal boundary. They are not independent per-scope patch counters. The retired top-level `state` segment is rejected; pre-origin history is unavailable rather than empty.
70
+ `effective[n]`, `global[n]`, `cwd[n]`, and `session[n]` resolve the same nth previous causal boundary; the history index remains a composed-lineage offset, not a scope revision. Separately, each materially changed owner advances its persisted semantic revision once. Global and CWD counters remain shared across their canonical writers, Session remains private, and Effective is identified by the current `G#/C#/S#` revision vector. The retired top-level `state` segment is rejected; pre-origin history is unavailable rather than empty.
71
71
 
72
- A changed accepted response is runtime-owned semantic state and advances history. Ordinary completion requires no `patch_state` call when durable semantic state is already correct.
72
+ A changed accepted response is runtime-owned, session-only semantic state and advances history. An accepted empty answer becomes `""` and finalizes normally rather than producing a recovery error. Ordinary completion requires no `patch_state` call when durable semantic state is already correct.
73
73
 
74
74
  ## Pi lifecycle
75
75
 
@@ -79,7 +79,7 @@ Tool preflight follows Pi's public `getLeafEntry()` / `getEntry(parentId)` links
79
79
 
80
80
  `read_state` reads one cached effective or scoped projection at current index zero or a retained causal index through the configured `historyLimit`. It never publishes or advances history.
81
81
 
82
- Before answering, the model uses `patch_state` only when future-relevant durable state must change. An accepted ordinary answer is reconciled directly into runtime-owned `response` at `turn_end`; no terminal eligibility latch, finalization patch, repair inference, or fallback budget exists. If required artifact or Skill compilation prevents reconciliation, State Flow reports the failure without generating another inference. State Flow does not parse `state_flow` or generic HTML comments; historical comments are ordinary text and other extensions retain their own comment handling.
82
+ Before answering, the model uses `patch_state` only when future-relevant durable state must change. The exact accepted ordinary answer is reconciled directly into runtime-owned `response` at `turn_end`, including `""` when the accepted answer is empty; no terminal eligibility latch, finalization patch, repair inference, or fallback budget exists. If required ordinary-artifact compilation prevents reconciliation, State Flow reports the failure without generating another inference. Optional Skill acquisition never blocks unrelated reconciliation. State Flow does not parse `state_flow` or generic HTML comments; historical comments are ordinary text and other extensions retain their own comment handling.
83
83
 
84
84
  ## Lifecycle planes
85
85
 
@@ -93,7 +93,7 @@ Stopping State Flow ends active episode semantics, restores the configured passi
93
93
 
94
94
  A proven pre-runtime branch has no accepted runtime to persist: Stop appends State Flow's existing `{disabled:true}` checkpoint in Pi without creating canonical files. Its cached passive view remains readable under the configured policy, but is not runtime authority. Accepted canonical publication, including a later Start or passive patch, ends this pre-runtime condition; failed selected-boundary recovery never qualifies for it.
95
95
 
96
- Lifecycle-only persistence for accepted runtimes reconciles valid live global/CWD drift before publishing the current session's config/runtime pair. Changed shared streams establish a fresh proven origin, not a semantic transition; counters, semantic files, and all provenance files remain unchanged. Cached reads may constrain wider tails left by another writer without rewriting them. Same-session file races and explicitly requested stale provenance writes still fail closed under CAS. The host refreshes its scope cache after adoption: Stop freezes the accepted view, and new-run registered-artifact maintenance runs against that view before inference.
96
+ Lifecycle-only persistence for accepted runtimes reconciles valid live global/CWD drift before publishing the current session's config/runtime pair. Changed shared streams establish a fresh proven origin, not a semantic transition; the runtime adopts their already-advanced owner revisions without incrementing them, while semantic files and all provenance files remain unchanged. Cached reads may constrain wider tails left by another writer without rewriting them. Same-session file races and explicitly requested stale provenance writes still fail closed under CAS. The host refreshes its scope cache after adoption: Stop freezes the accepted view, and new-run registered-artifact maintenance runs against that view before inference.
97
97
 
98
98
  The existing native passive-stop marker stores the stop timestamp and an optional `from` timestamp identifying the active run's first user message. Native user events are observed independently of State Flow enablement, so starting mid-tool and repeated Start/Stop retain the actual first-user timestamp. Native user-run preparation and session-start/tree events reset capture; semantic mode changes do not. No new marker field, stored format or projection-derived lifecycle authority is introduced. Transcript bodies remain in Pi's trace rather than being copied into another state store. A recorded active anchor uses the same conservative selector as active inference: if native compaction removed it, or matching is ambiguous/nonfinite, retain the available native summary and tool trajectory without guessing a post-stop boundary or rereading discarded raw entries. Idle and legacy markers without an active anchor still retain only post-stop conversation plus foreign custom context. The initial system prompt is composed at `before_agent_start`; Stop does not rewrite an already-issued request, while the next provider request receives the current owned protocol section as described below.
99
99
 
@@ -128,7 +128,7 @@ meta.json
128
128
 
129
129
  CWD and session keys mirror Pi's native encoding. The Pi UUID remains authoritative; readable directory keys never replace identity validation.
130
130
 
131
- Root `config.json` is the read-only operator configuration shared by every session in the repository; it never participates in semantic overlay or State Flow-owned staging. Include operator configuration in operator-managed copies/versioning. `checkpoint.json` is only the canonical materialized semantic state, and each nonblank `patches.jsonl` line is only one semantic patch. Every scope's `meta.json` symmetrically owns checkpoint/tail boundaries and artifact provenance, with CWD ownership added where applicable. Session `config.json` owns behavior; session `runtime.json` asymmetrically owns lineage, counters, session identity, and the full specification only while a run is unfinished. Predecessor combined session metadata is unsupported; session `meta.json`, `config.json`, and `runtime.json` must already satisfy their canonical ownership contracts. Metadata writers replace only their owned leaves and preserve JSON-safe unknown siblings. Pi checkpoints retain only a semantic boundary plus lifecycle fields, or a proven ordinary-disabled marker. Revision-pointer checkpoints are unsupported and fail closed without Git restoration.
131
+ Root `config.json` is the read-only operator configuration shared by every session in the repository; it never participates in semantic overlay or State Flow-owned staging. Include operator configuration in operator-managed copies/versioning. `checkpoint.json` is only the canonical materialized semantic state, and each nonblank `patches.jsonl` line is only one semantic patch. Every scope's `meta.json` symmetrically owns its independent semantic revision, checkpoint/tail boundaries and artifact provenance, with CWD ownership added where applicable. Session `config.json` owns behavior; session `runtime.json` asymmetrically owns lineage, the internal branch step, session identity, and the full specification only while a run is unfinished. Predecessor combined session metadata is unsupported; session `meta.json`, `config.json`, and `runtime.json` must already satisfy their canonical ownership contracts. Metadata writers replace only their owned leaves and preserve JSON-safe unknown siblings. A pre-revision 0.17 scope initializes its counter from the still-retained semantic tail and persists that baseline on its next owned write; folded ancestry is not guessed. Revision-aware writes emit scope metadata version 2 while continuing to read version 1. The version fence makes an older writer refuse a scope after its first revision-aware write instead of silently dropping the counter; all cooperating instances should still upgrade together. Pi checkpoints retain only a semantic boundary plus lifecycle fields, or a proven ordinary-disabled marker. Revision-pointer checkpoints are unsupported and fail closed without Git restoration.
132
132
 
133
133
  In-memory patching detaches one basis at its public boundary, then privately path-copies changed object/array containers while sharing untouched nodes only inside that owned draft. Incoming replacement values remain detached; staging no longer makes redundant cohort/per-scope pre-clones. Mutable staged responses and artifact registries stay isolated from accepted scopes, and commit/public temporal reads retain their detachment boundaries. This is not cross-version mutable sharing or a new disk generation format; see [copy-work evidence](performance.md#memory-only-owned-draft-cow).
134
134
 
@@ -144,7 +144,9 @@ After response reconciliation and Pi's retry/queue processing, `agent_before_set
144
144
 
145
145
  Only exact backed-up owned paths are synchronized in the caller's index, preserving unrelated staged additions, modifications, deletions, index-only content, and worktree edits. HEAD-owned paths remain candidates when their deletion is already staged. Unchanged trees and unowned-only initial backups are skipped; failed index synchronization rolls back only the backup ref, never canonical files. Failure cannot suppress the answer or trigger another inference. Notification-only `agent_settled` does not perform backup writes.
146
146
 
147
- Durable push queues, publication workers, leases, retries, queue filesystem state, and publication-policy metadata have been deleted. Git revision restore, immutable-revision fork APIs, and the legacy semantic Git backend have been removed from `TemporalRuntime`; all initialization, passive loading, model patches, runtime-only persistence, retained-boundary restoration, and retained-boundary forks use canonical files only.
147
+ After a successful backup attempt, State Flow resolves only the attached branch's explicitly configured remote and destination ref, snapshots the exact current commit, and starts one non-interactive, non-force push outside all backup and canonical locks. Settlement does not await network completion. Failure is diagnostic-only; no queue is persisted, and the next accepted settled turn attempts the latest current backup again. A repository without an explicitly configured branch remote remains local-only.
148
+
149
+ Durable push queues, publication workers, leases, retry generations, queue filesystem state, and publication-policy metadata remain absent. Git revision restore, immutable-revision fork APIs, and the legacy semantic Git backend have been removed from `TemporalRuntime`; all initialization, passive loading, model patches, runtime-only persistence, retained-boundary restoration, and retained-boundary forks use canonical files only.
148
150
 
149
151
  Predecessor checkpoint envelopes, combined session metadata, pre-intents checkpoints, `state.json`, hashed layouts, and semantic Pi checkpoints are unsupported and remain untouched.
150
152
 
@@ -165,17 +167,17 @@ Runtime-owned compilation evidence is retained per scope in `meta.json`; current
165
167
 
166
168
  The public `classifyArtifactCompilationNeed` owns acquisition/rehydration and ordinary-artifact Pi decisions. An observed fingerprint needs matching valid retained fingerprint evidence; missing/malformed fingerprints, malformed compiler evidence, or a changed compiler request compilation without removing semantics. Changed size or signed nanosecond mtime (including pre-epoch dates) preserves the value and adds a runtime-only model `hint`. Fingerprint-only decisions ignore unused legacy hashes; explicit current-hash observations and the separate Skill hash protocol remain checked. Rehydration read plans carry detached fingerprints and optional hashes, never invented identities.
167
169
 
168
- Invalidation notices identify the selected `global`, `cwd`, or `session` owner. Guidance and missing-output errors direct compilation to that exact scope/path, without relocating the entry or creating a global copy. Successful exact reads require stable fingerprints before/after acquisition and at publication, then publish compiler output and provenance to that owner under scope causal-basis CAS. Generic maintenance computes no content hash. Effective Skill entries mask lower ordinary entries and remain owned by the separate CWD Skill protocol.
170
+ Invalidation notices identify the selected `global`, `cwd`, or `session` owner. Guidance and missing-output errors direct compilation to that exact scope/path, without relocating the entry or creating a global copy. Successful exact reads require stable fingerprints before/after acquisition and at publication, then publish compiler output and provenance to that owner under scope causal-basis CAS. Generic maintenance computes no content hash. Effective Skill entries mask lower ordinary entries and retain their separate hash protocol.
169
171
 
170
172
  Compilation is routing, not a substitute for source text. Full source is read only for a concrete unresolved gap, exact source/edit operation, fingerprint invalidation, contradiction/failure, or explicit request. The rehydration planner supports new-bootstrap, resume-bootstrap and later-step phases without hidden directory traversal.
171
173
 
172
- Skills are CWD artifacts with stricter compilation: `kind: "skill"` and a non-empty compilation describing applicability, constraints and failure conditions. Their source bodies do not persist in state. Matching provenance proves source-version consistency, not semantic fidelity, truth, or higher instruction authority.
174
+ Skill acquisition applies only to exact registered Pi Skills. State Flow resolves identity and ownership through the public slash-command inventory rather than file-path conventions: Pi `user`, `project` and `temporary` source scopes map to State Flow `global`, `cwd` and `session`. A successful read with matching current source hash needs no new compilation. Otherwise the tool result names the exact optional target. Attempted durable output requires `kind: "skill"` and a non-empty compilation describing applicability, constraints and failure conditions; an omitted output leaves the read volatile and does not block unrelated patches or ordinary completion. Source bodies do not persist in state. Matching provenance proves source-version consistency, not semantic fidelity, truth, or higher instruction authority.
173
175
 
174
176
  ## Operational guidance and memory curation
175
177
 
176
178
  The packaged Skills deliberately separate two responsibilities. `state-flow-guide` is the on-demand operational reference for concrete read, patch, inheritance, acquisition, completion, and recovery questions; it does not initiate memory audits or unsolicited cleanup. `state-flow-memory` performs one explicitly requested bounded curation over stale knowledge, commitments, continuation, ownership, and external handoffs; phase completion does not activate an audit.
177
179
 
178
- Curation compiles a read Skill at CWD before dependent work. Within one store, a proven scope move inspects both owners, resolves conflicts, and commits destination/source changes through one atomic multi-scope patch, followed by ownership/overlay verification. Simultaneously pending acquisitions across scopes must be compiled together in one atomic `patch_state` call.
180
+ Curation may persist reusable guidance from a registered Skill at its provenance-derived scope. Within one store, a proven scope move inspects both owners, resolves conflicts, and commits destination/source changes through one atomic multi-scope patch, followed by ownership/overlay verification. Existing Skill artifacts written under the former CWD-only policy are not silently promoted: a later registered read identifies the current owner, while explicit curation may move proven reusable content and remove the old owner atomically.
179
181
 
180
182
  External transfers use the destination's native interface and receipts; accepted-copy verification precedes source deletion in a later State Flow patch. State Flow defines no promotion registry, status schema, record type, or dedicated promotion tool; destination uncertainty simply leaves the source intact.
181
183
 
@@ -232,7 +234,7 @@ Agent configuration is read once per extension load; session runtime configurati
232
234
 
233
235
  ## Observability
234
236
 
235
- Status is a projection of the selected runtime and semantic view, not a second store. Missing evidence stays unavailable instead of appearing empty. The optional Telegram leaf adapter reads the same snapshot and calls the same Start/Stop owners; registration is fail-open and disposal belongs to session shutdown. Local diagnostics stay outside semantic state, scope metadata, checkpoints, and publication, and failures cannot change accepted state. Operator-facing fields and privacy boundaries are in [usage](usage.md#status-and-controls).
237
+ Status is a projection of the selected runtime and semantic view, not a second store. Compact terminal and Telegram main-menu status render `G#/C#/S#` only while active; passive Telegram renders `State Flow: off`. Requested Global, CWD and Session Rich snapshots show their independent `#revision`, while Effective shows the vector. Global/CWD Rich views omit the empty structural response placeholder; Session and Effective expose the Session-owned response. Missing evidence stays unavailable instead of appearing empty. The optional Telegram leaf adapter calls the same Start/Stop owners, and its inspectors remain available in either mode. Inspection may refresh live Global/CWD streams in memory so foreign accepted revisions become visible, but never publishes or increments a revision. If model-facing passive access is disabled and no runtime is selected, inspection may lazily load existing canonical shared state under the same read-only rule. Registration is fail-open and disposal belongs to session shutdown. Local diagnostics stay outside semantic state and cannot change accepted state. Operator-facing fields and privacy boundaries are in [usage](usage.md#status-and-controls).
236
238
 
237
239
  ## Validation boundaries
238
240
 
@@ -42,11 +42,11 @@ global | CWD | session
42
42
  ├── contract
43
43
  ├── working
44
44
  ├── artifacts
45
- ├── response (session-owned where applicable)
45
+ ├── response (session-owned; empty structural slot in Global/CWD)
46
46
  └── lazy
47
47
  ```
48
48
 
49
- `intents`, `contract`, `working`, `artifacts`, and `response` remain hot. `intents` may keep compact active direction while referring to large supporting detail in `lazy`. `lazy` differs only in projection policy:
49
+ `intents`, `contract`, `working`, and `artifacts` remain hot in every scope. Session-owned `response` is also hot; Global and CWD keep only its required empty structural slot, and Effective inherits the Session value. `intents` may keep compact active direction while referring to large supporting detail in `lazy`. `lazy` differs only in projection policy:
50
50
 
51
51
  - It is canonical semantic JSON, validated and versioned with its owning scope.
52
52
  - It is excluded from the ordinary baseline effective-state body.
@@ -17,12 +17,14 @@ This is a maintained property-to-test map for the current canonical-file contrac
17
17
  11. **Barrier shifts current to offset 1:** `tests/integration.test.ts` — “real Pi patch_state barriers rematerialize every scope before the next inference” observes the predecessor immediately after a barrier.
18
18
  12. **Next inference sees new current state:** The same real-Pi test inspects actual model-input projections after session, CWD, and global barriers. “real Pi reads prior scoped state lazily after a barrier and rejects path offset eight without a transition” adds model-tool access to the predecessor.
19
19
  13. **No automatic old full-state duplication:** `tests/context.test.ts` — “projects only the latest seven compact accepted transitions” rejects full-state records in transition context. The real-Pi barrier test requires exactly one current runtime projection per inference. Explicitly requested history remains ordinary tool-result trajectory, not eager snapshot injection.
20
- 14. **Accepted response changes are transitions:** `tests/extension.test.ts` — “accepts only canonical materially changing atomic scope patches” verifies that an ordinary accepted answer becomes runtime-owned `response` without a finalization patch or fallback inference.
21
- 15. **No-op mutation signals are rejected:** The same extension test rejects empty and obsolete finalization-shaped calls, while a changed accepted response remains a runtime-owned transition.
20
+ 14. **Accepted response changes are transitions:** `tests/extension.test.ts` verifies that an ordinary accepted answer becomes runtime-owned `response` without a finalization patch or fallback inference, and “an empty accepted answer finalizes the run and stores an empty response” proves `""` is accepted after an earlier barrier. `tests/transition.test.ts` proves the empty value is an ordinary Session-owned semantic change when it replaces prior text.
21
+ 15. **No-op mutation signals are rejected:** “accepts only canonical materially changing atomic scope patches” rejects empty scope patches and obsolete finalization-shaped calls, while a changed accepted response remains a runtime-owned transition.
22
22
  16. **Configured hot-history bounds:** `tests/temporal.test.ts` verifies hot-range and unavailable pre-origin boundaries; the real-Pi history-reader test rejects offset eight at the default limit seven without a transition. `tests/config.test.ts` exercises materialized and scope patch-history paths at limits 0, 1, 7, and 12, including single-path/one-item batch reads above seven and distinct configured versus actually retained boundaries.
23
23
  17. **Selected history fails closed:** `tests/recovery.test.ts` proves every failure resolving a selected retained boundary refuses without falling through to older boundaries or disabled markers. `tests/extension.test.ts` covers all passive bootstrap/tool combinations; the native “real Pi expired selection cannot reset private state through passive Start, Stop, patch, or reload” witness preserves exact canonical bytes and Pi checkpoints while allowing shared reads. Fork identity/CWD repair witnesses retry the original source with passive access both enabled and disabled.
24
24
  18. **Tree/resume select the correct lineage:** `tests/integration.test.ts` — “real Pi preserves branch-local state through compaction and rejects an expired sibling after fresh-origin navigation” and “real Pi old tree branch stop and resume preserve selected semantics without rewinding shared files”.
25
25
  19. **Stop changes config, not semantic history:** `tests/runtime.test.ts` lifecycle-only witnesses use a separate process to advance global/CWD semantics or provenance, including wider foreign retention, then prove exact semantic/sidecar preservation, unchanged steps, idempotent Stop, and same-session/stale-evidence refusal. Native Stop/new-request witnesses verify the accepted shared view reaches handoff/inference without a lifecycle semantic write, while a shared write racing after inference still fails closed. Mid-tool Stop tests preserve ordinary/bootstrap trajectories through tree, reload, resume, and restart. The native “real Pi retains a native split-turn continuation through late tools” Stop/no-Stop controls actually remove the original user with native threshold compaction, then require summary, paired reads and foreign context in model input. The Stop case also checks frozen semantics/step, unchanged trace prefix, tree/reload/cold resume/bootstrap restart, no resurrection of discarded input, and persistent foreign context after the next active run. Pure passive-selector tests cover missing, colliding and nonfinite recorded active anchors without changing idle/legacy cutoffs. `tests/storage.test.ts` fences lifecycle-only writes to config/runtime files; `tests/extension.test.ts` covers idle/legacy cutoffs and new/fork boundaries.
26
+ 20. **Passive observability omits active status without hiding owner revisions:** `tests/status.test.ts` proves an accepted passive patch advances semantic history while compact terminal status stays absent. `tests/telegram.test.ts` drives the real extension port after Stop, requires the passive main-menu identity to render `State Flow: off`, verifies an owner Rich-state heading uses its independent `#revision` and Effective uses `G#/C#/S#`, and separately proves Telegram can lazily observe existing shared canonical state when passive model tools are disabled without initializing or mutating storage.
27
+ 21. **Independent revisions survive folding and foreign writers:** `tests/temporal.test.ts` proves each materially changed scope advances once for sparse and multi-scope cohorts, response-only transitions advance only Session, no-ops advance none, selected retained history restores the matching revision, and folding never resets it. `tests/durable.test.ts` covers revision serialization plus the pre-revision 0.17 retained-tail baseline. `tests/runtime.test.ts` uses an independent file-backed writer to advance Global, then refreshes the first runtime without file mutation and proves `G1/C0/S1` becomes `G1/C0/S2` after one private Session patch.
26
28
 
27
29
  ## Additional preservation boundaries
28
30
 
@@ -47,7 +49,7 @@ This is a maintained property-to-test map for the current canonical-file contrac
47
49
  - `tests/context.test.ts` and `tests/extension.test.ts` prohibit process queries during ordinary context/history reads. `tests/transition.test.ts` rejects stale staging even when semantic values coincide across different causal boundaries.
48
50
  - `tests/status.test.ts` distinguishes selected temporal history depth from retained per-scope tails and unavailable materialization from an empty state.
49
51
  - `tests/artifact.test.ts` and extension/native integration witnesses prove exact registered-path inspection, `size + mtimeNs` evidence, non-destructive unavailable/symlink handling, owning-scope removal, runtime-only changed-source hints, and stable-read acceptance without directory discovery. The native newly-adopted-artifact witness proves run preparation refreshes live shared state before proven-missing maintenance and the first inference. Artifact/acquisition/rehydration tests and “real Pi ordinary artifact invalidations share the public fingerprint classifier” cover equal/changed/missing/malformed fingerprints, pre-epoch timestamps, compiler invalidation, detached read plans, legacy hash handling, and effective Skill masking while preserving Skill hashing.
50
- - `tests/protocol.test.ts` checks runtime/Skill guidance names the reported artifact owner. Transition and native three-scope compilation witnesses reject wrong-scope output with an exact owning-scope target, preserve canonical bytes on failure, and accept stable recompilation without unrelated-scope writes; native reload retains the accepted provenance.
52
+ - `tests/protocol.test.ts` checks runtime/Skill guidance names the reported artifact owner. Registered-Skill unit and native witnesses use Pi's public command source metadata to map user/project/temporary Skills to global/CWD/session, ignore unregistered `SKILL.md` reads, skip matching hashes, permit unrelated patches while compilation remains optional, retain strict attempted-output validation, and publish source-hash provenance to the exact reported owner.
51
53
  - `tests/transition.test.ts` rejects authored provenance fields and field deletions in every scope through both staging entrypoints, without requiring a preceding read; legacy semantic edits and whole-artifact deletion remain valid. The native “real Pi rejects no-read provenance forgery atomically and accepts a corrected model patch” witness proves whole-cohort rejection and recovery, while existing artifact/Skill tests preserve runtime-owned compilation evidence and legacy decoding.
52
54
  - `tests/storage.test.ts` covers exact file-cohort references, file CAS/rollback, and shared writer exclusion. `tests/runtime.test.ts` and native Pi lifecycle tests cover retained-boundary restart, immediate barriers, finalized response, config-only stop, and unavailable-reference provenance. Canonical files supply current state and bounded hot history; arbitrary cold revision recovery is unsupported.
53
55
  - `tests/runtime.test.ts` and native integration cover retained-boundary restoration and fork after lowering `historyLimit` to 0/1: current shared values/provenance and selected private state survive folding, parent-private fork files remain unchanged, out-of-window selections fail closed, and later increases do not reconstruct discarded history. `tests/config.test.ts` covers optional agent configuration, path precedence/expansion, invalid input, load-time caching and read-only behavior. Session tests and native Pi distinguish configured new-session auto-start from branch-local resume/tree/stop. `tests/extension.test.ts` proves registered artifacts are reconciled only at enabled inference boundaries. The global default is manual; CWD materialization alone no longer grants automatic activation.
package/docs/usage.md CHANGED
@@ -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`. When `pi-telegram` is available, one main-menu section carries the live State Flow status and opens Start/Stop controls. 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. 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.
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
+ 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.
108
108
 
109
109
  ### Conflicts and interrupted publication
110
110
 
@@ -118,6 +118,6 @@ An untouched shared scope may be adopted from newer proven live state at a fresh
118
118
 
119
119
  The agent should use sufficient materialized knowledge before rereading files. Read for a concrete gap, exact-source/edit operation, evidenced invalidation, contradiction/failure, explicit request, or bounded maintenance—not simply because a new session began.
120
120
 
121
- Artifact maintenance inspects only exact paths already registered in global, CWD, or session state, using `size + mtimeNs` without directory traversal or generic content hashing. Proven-missing paths are pruned from their exact owning scopes; unavailable, relative, directory, and symlink paths are preserved. Changed sources keep their artifact value and receive a runtime-only model `hint` until a stable read and same-path compilation updates hidden provenance. Skill reads retain their separate CWD compilation protocol. Model patches cannot author or delete runtime provenance or hints.
121
+ Artifact maintenance inspects only exact paths already registered in global, CWD, or session state, using `size + mtimeNs` without directory traversal or generic content hashing. Proven-missing paths are pruned from their exact owning scopes; unavailable, relative, directory, and symlink paths are preserved. Changed sources keep their artifact value and receive a runtime-only model `hint` until a stable read and same-path compilation updates hidden provenance. Only exact registered Pi Skill reads enter the separate hash protocol. Public Pi source provenance maps user Skills to global, project Skills to CWD and temporary Skills to session; matching compiled hashes require no update, and an uncompiled read remains volatile without blocking unrelated patches. Model patches cannot author or delete runtime provenance or hints.
122
122
 
123
123
  The packaged `state-flow-guide` Skill answers concrete operational questions about reads, patches, inheritance, acquisition, completion, and recovery without initiating cleanup. The separate `state-flow-memory` Skill handles explicitly requested bounded curation and externally verified transfers. Feature/release/project boundaries may motivate recommending cleanup, not starting an audit. Ordinary handoffs reconcile touched state; neither Skill is a background maintenance loop. External transfers use the destination's native receipt and preserve the source whenever acceptance is uncertain. Artifact/compiler details and model-tool contracts belong in the [architecture](architecture.md#artifact-routing).
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 { backupCurrentStateFlowFiles, pushCurrentStateFlowBackup } 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";
@@ -35,11 +35,12 @@ import { recoverSnapshot } from "./recovery.ts";
35
35
  import type { RehydrationPhase } from "./rehydration.ts";
36
36
  import { SharedScopeRemovalConflictError, TemporalRuntime, type RuntimePublication } from "./runtime.ts";
37
37
  import { discoverSnapshotData, findAssistantToolBatch, findPassiveStopBoundary, hasPriorConversation, isNewSession, retainsPhysicalSessionProjection, SNAPSHOT_ENTRY_TYPE } from "./session.ts";
38
- import { SkillReadTracker } from "./skills.ts";
38
+ import { hasCompiledSkillArtifact, hashSkillSource, registeredSkillResolver, SkillReadTracker, type SuccessfulSkillRead } from "./skills.ts";
39
39
  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
- import { createStateFlowTelegramAdapter, type StateFlowTelegramControlResult, type StateFlowTelegramLoader } from "./telegram.ts";
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,9 +86,11 @@ 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;
90
- const skillReads = new SkillReadTracker();
91
+ const skillReads = new SkillReadTracker(hashSkillSource, (path) => activeContext
92
+ ? registeredSkillResolver(activeContext.cwd, pi.getCommands())(path)
93
+ : undefined);
91
94
  const artifactReads = new ArtifactReadTracker();
92
95
  let artifactInvalidations: ArtifactInvalidationRequest[] = [];
93
96
  let artifactHints: Record<string, string> = {};
@@ -98,6 +101,14 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
98
101
  return resolveSessionAddress(ctx.sessionManager.getSessionFile(), ctx.sessionManager.getSessionId(), ctx.sessionManager.getHeader()?.timestamp);
99
102
  }
100
103
 
104
+ function notifyActiveContext(message: string): void {
105
+ try {
106
+ activeContext?.ui.notify(message, "warning");
107
+ } catch {
108
+ // An asynchronous push attempt can outlive the Pi context that launched it.
109
+ }
110
+ }
111
+
101
112
  function createRuntime(ctx: ExtensionContext): TemporalRuntime {
102
113
  return new TemporalRuntime(ctx.cwd, sessionAddress(ctx), repositoryRoot, undefined, config.historyLimit);
103
114
  }
@@ -132,8 +143,14 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
132
143
  if ("boundary" in checkpoint) branchStartsWithoutRuntime = false;
133
144
  }
134
145
 
146
+ function scopeRevisions(): ScopeRevisions {
147
+ return runtime?.view
148
+ ? temporalScopeRevisions(runtime.view)
149
+ : { global: 0, cwd: 0, session: 0 };
150
+ }
151
+
135
152
  function updateUi(ctx: ExtensionContext): void {
136
- ctx.ui.setStatus(STATUS_KEY, compactStatus(snapshot, (color, text) => ctx.ui.theme.fg(color, text)));
153
+ ctx.ui.setStatus(STATUS_KEY, compactStatus(snapshot, scopeRevisions(), (color, text) => ctx.ui.theme.fg(color, text)));
137
154
  }
138
155
 
139
156
  function clearRunTransient(): void {
@@ -200,6 +217,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
200
217
  if (Object.keys(removals).length > 0) {
201
218
  const stage = stageAtomicScopePatches(scopeStates, removals, [], runtime.causalBasis());
202
219
  commitStage(stage, ctx, false);
220
+ updateUi(ctx);
203
221
  }
204
222
  refreshArtifactHints();
205
223
  }
@@ -213,6 +231,18 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
213
231
  return snapshot.config.enabled || config.passiveTools;
214
232
  }
215
233
 
234
+ function refreshTelegramStateView(scope: StateFlowTelegramScope): void {
235
+ if (scope === "session" || scope === "effective") assertSelectedBranchAvailable();
236
+ if (!runtime?.view) {
237
+ if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
238
+ runtime ??= createRuntime(activeContext);
239
+ runtime.loadPassive();
240
+ } else if (scope !== "session") {
241
+ runtime.refreshShared();
242
+ }
243
+ installScopeStates();
244
+ }
245
+
216
246
  function syncStateFlowTools(): void {
217
247
  const active = pi.getActiveTools();
218
248
  const owned = [PATCH_STATE_TOOL_NAME, READ_STATE_TOOL_NAME];
@@ -234,6 +264,27 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
234
264
  if (publication) recordPublication(publication, ctx);
235
265
  }
236
266
 
267
+ function skillReadIsCurrent(read: SuccessfulSkillRead): boolean {
268
+ return read.hash !== undefined && runtime?.view !== undefined && hasCompiledSkillArtifact(
269
+ scopeStates[read.scope].artifacts,
270
+ runtime.artifactProvenance(read.scope)[read.path],
271
+ read.path,
272
+ read.hash,
273
+ );
274
+ }
275
+
276
+ function dropCurrentSkillReads(): void {
277
+ for (const read of skillReads.successful.values()) {
278
+ if (skillReadIsCurrent(read)) skillReads.delete(read.path);
279
+ }
280
+ }
281
+
282
+ function skillAcquisitionHint(read: SuccessfulSkillRead): string | undefined {
283
+ if (read.hash === undefined || skillReadIsCurrent(read)) return undefined;
284
+ const target = `${read.scope}.artifacts[${JSON.stringify(read.path)}]`;
285
+ return `State Flow acquisition: this registered Skill belongs at ${target}. If durable compiled guidance is useful, include a non-empty description, kind:"skill", and compilation object there. Unrelated semantic patches do not need to include it.`;
286
+ }
287
+
237
288
  function commitStage(stage: StagedScopedTransition, ctx: ExtensionContext, finalizeRun: boolean): boolean {
238
289
  const acquiredArtifactPaths = new Set(artifactReads.successful.keys());
239
290
  let committed: boolean;
@@ -253,7 +304,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
253
304
  installScopeStates();
254
305
  artifactInvalidations = artifactInvalidations.filter(({ path }) => !acquiredArtifactPaths.has(path));
255
306
  artifactReads.setCandidates(artifactInvalidations);
256
- skillReads.clear();
307
+ dropCurrentSkillReads();
257
308
  artifactReads.clear();
258
309
  persist();
259
310
  return true;
@@ -287,6 +338,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
287
338
  head: structuredClone(view.lineage.at(-1)!),
288
339
  historyDepth: view.lineage.length - 1,
289
340
  tailCounts: { global: view.scopes.global.patches.length, cwd: view.scopes.cwd.patches.length, session: view.scopes.session.patches.length },
341
+ revisions: temporalScopeRevisions(view),
290
342
  } }),
291
343
  staleArtifacts,
292
344
  ...(durableStateError === undefined ? {} : { durableStateError }),
@@ -667,16 +719,18 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
667
719
  snapshot: () => ({
668
720
  enabled: snapshot.config.enabled,
669
721
  step: snapshot.meta.step,
722
+ revisions: scopeRevisions(),
670
723
  bootstrap: snapshot.meta.bootstrap === true,
671
724
  startPending: telegramStartPending,
672
725
  }),
673
726
  state: (scope) => {
674
- if (scope === "session") assertSelectedBranchAvailable();
727
+ refreshTelegramStateView(scope);
675
728
  const selected = scope === "effective"
676
729
  ? overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)
677
730
  : scopeStates[scope];
678
731
  return { ...projectModelState(selected), lazy: structuredClone(selected.lazy) };
679
732
  },
733
+ revisions: () => scopeRevisions(),
680
734
  canStartNow: () => activeContext === undefined || activeContext.isIdle(),
681
735
  start: () => {
682
736
  if (!activeContext) throw new Error("State Flow is not attached to an active session yet");
@@ -801,9 +855,20 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
801
855
  pi.on("tool_execution_end", (event) => {
802
856
  if (!snapshot.config.enabled) return;
803
857
  skillReads.recordEnd(event.toolCallId, event.toolName, event.isError);
858
+ dropCurrentSkillReads();
804
859
  artifactReads.recordEnd(event.toolCallId, event.toolName, event.isError);
805
860
  });
806
861
 
862
+ pi.on("tool_result", (event) => {
863
+ if (!snapshot.config.enabled) return;
864
+ const read = skillReads.recordResult(event.toolName, event.input, event.isError);
865
+ if (!read) return;
866
+ dropCurrentSkillReads();
867
+ const hint = skillAcquisitionHint(read);
868
+ if (!hint) return;
869
+ return { content: [...event.content, { type: "text", text: `\n${hint}` }] };
870
+ });
871
+
807
872
  pi.on("message_end", (event, ctx): any => {
808
873
  // Observe actual user events even while disabled; Start/Stop cannot invent or erase them.
809
874
  if (event.message.role === "user" && runAnchorTimestamp === undefined) runAnchorTimestamp = event.message.timestamp;
@@ -866,7 +931,16 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
866
931
  if (!backupPending) return;
867
932
  backupPending = false;
868
933
  try {
869
- if (existsSync(join(repositoryRoot, ".git"))) backupCurrentStateFlowFiles(repositoryRoot);
934
+ if (existsSync(join(repositoryRoot, ".git"))) {
935
+ backupCurrentStateFlowFiles(repositoryRoot);
936
+ const pushSessionId = sessionAddress(ctx).id;
937
+ const pushCwd = ctx.cwd;
938
+ void pushCurrentStateFlowBackup(repositoryRoot).catch((error) => {
939
+ const message = error instanceof Error ? error.message : String(error);
940
+ diagnosticWriter.record(pushSessionId, pushCwd, message, "publication-conflict");
941
+ notifyActiveContext(`State Flow accepted canonical state; Git backup push failed: ${message}`);
942
+ });
943
+ }
870
944
  } catch (error) {
871
945
  const message = error instanceof Error ? error.message : String(error);
872
946
  recordDiagnostic(message, "publication-conflict", ctx);
@@ -907,10 +981,11 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
907
981
  runAnchorTimestamp = undefined;
908
982
  restoreActiveBranch(ctx);
909
983
  });
910
- pi.on("session_shutdown", (_event, ctx) => {
984
+ pi.on("session_shutdown", (_event, _ctx) => {
911
985
  telegramStartPending = false;
912
986
  compactionStopped = true;
913
987
  completedRunAccepted = false;
988
+ activeContext = undefined;
914
989
  telegram.dispose();
915
990
  });
916
991
  }
package/lib/git.ts CHANGED
@@ -2,13 +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
11
 
12
+ function redactGitDiagnostic(value: string): string {
13
+ return value
14
+ .replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@/gi, "$1***@")
15
+ .replace(/([?&](?:access_token|auth|password|token)=)[^&\s]+/gi, "$1***");
16
+ }
17
+
12
18
  interface GitResult {
13
19
  status: number;
14
20
  stdout: string;
@@ -134,6 +140,22 @@ function currentBranchRef(repositoryRoot: string): string {
134
140
  return result.stdout.trim();
135
141
  }
136
142
 
143
+ function configuredPushDestination(repositoryRoot: string): { remote: string; ref: string } | undefined {
144
+ const branchRef = currentBranchRef(repositoryRoot);
145
+ const branch = branchRef.slice("refs/heads/".length);
146
+ const configuredRemote = git(repositoryRoot, ["config", "--get", `branch.${branch}.remote`], { allowFailure: true });
147
+ if (configuredRemote.status > 1) throw new Error(configuredRemote.stderr || "Cannot inspect State Flow backup remote configuration");
148
+ if (configuredRemote.status !== 0 || configuredRemote.stdout.trim().length === 0) return undefined;
149
+ const remote = configuredRemote.stdout.trim();
150
+ if (remote === ".") throw new Error("State Flow backup replication requires a non-local Git remote");
151
+ const configuredMerge = git(repositoryRoot, ["config", "--get", `branch.${branch}.merge`], { allowFailure: true });
152
+ if (configuredMerge.status > 1) throw new Error(configuredMerge.stderr || "Cannot inspect State Flow backup branch configuration");
153
+ const ref = configuredMerge.status === 0 && configuredMerge.stdout.trim().length > 0
154
+ ? configuredMerge.stdout.trim()
155
+ : branchRef;
156
+ return { remote, ref };
157
+ }
158
+
137
159
  function commitCurrentOwnedFiles(repositoryRoot: string, expectedHead: string | undefined): string | undefined {
138
160
  const branchRef = currentBranchRef(repositoryRoot);
139
161
  if (currentHead(repositoryRoot) !== expectedHead) throw new Error("State Flow backup Git base changed concurrently");
@@ -183,3 +205,63 @@ function commitCurrentOwnedFiles(repositoryRoot: string, expectedHead: string |
183
205
  export function backupCurrentStateFlowFiles(repositoryRoot: string): string | undefined {
184
206
  return withBackupLock(repositoryRoot, (root) => commitCurrentOwnedFiles(root, currentHead(root)));
185
207
  }
208
+
209
+ /** Push the current backup commit to its explicitly configured branch remote without blocking settlement. */
210
+ export function pushCurrentStateFlowBackup(repositoryRoot: string): Promise<{ commit: string; remote: string; ref: string } | undefined> {
211
+ return new Promise((resolvePush, rejectPush) => {
212
+ let root: string;
213
+ let commit: string | undefined;
214
+ let destination: { remote: string; ref: string } | undefined;
215
+ try {
216
+ root = assertRepositoryRoot(repositoryRoot);
217
+ commit = currentHead(root);
218
+ destination = configuredPushDestination(root);
219
+ } catch (error) {
220
+ rejectPush(error);
221
+ return;
222
+ }
223
+ if (commit === undefined || destination === undefined) {
224
+ resolvePush(undefined);
225
+ return;
226
+ }
227
+ const child = spawn("git", ["-C", root, "push", "--porcelain", "--", destination.remote, `${commit}:${destination.ref}`], {
228
+ detached: process.platform !== "win32",
229
+ stdio: ["ignore", "ignore", "pipe"],
230
+ windowsHide: true,
231
+ env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GCM_INTERACTIVE: "never" },
232
+ });
233
+ let stderr = "";
234
+ let failure: Error | undefined;
235
+ let settled = false;
236
+ function terminate(error: Error): void {
237
+ failure ??= error;
238
+ if (child.exitCode !== null || child.signalCode !== null) {
239
+ child.stderr?.destroy();
240
+ return;
241
+ }
242
+ if (!child.pid) return;
243
+ try {
244
+ if (process.platform === "win32") child.kill("SIGKILL");
245
+ else process.kill(-child.pid, "SIGKILL");
246
+ } catch {
247
+ // Keep waiting for close: signalling failure is not proof that the process ended.
248
+ }
249
+ }
250
+ const timeout = setTimeout(() => terminate(new Error(`Git backup push timed out after ${GIT_TIMEOUT_MS}ms`)), GIT_TIMEOUT_MS);
251
+ function finish(error?: Error): void {
252
+ if (settled) return;
253
+ settled = true;
254
+ clearTimeout(timeout);
255
+ if (error) rejectPush(error);
256
+ else resolvePush({ commit: commit!, ...destination! });
257
+ }
258
+ child.stderr?.on("data", (chunk: Buffer) => { stderr = (stderr + chunk.toString("utf8")).slice(-1000); });
259
+ child.on("error", (error) => {
260
+ failure ??= error;
261
+ if (!child.pid) finish(error);
262
+ });
263
+ child.once("exit", () => { if (failure) child.stderr?.destroy(); });
264
+ child.once("close", (code, endedBy) => finish(failure ?? (code === 0 ? undefined
265
+ : new Error(`Git backup push failed (${endedBy ?? code}): ${redactGitDiagnostic(stderr.trim()) || "no diagnostic output"}`))));
266
+ });
267
+ }