@llblab/pi-state-flow 0.22.0 → 0.24.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.
@@ -36,7 +36,7 @@ Runtime views select these documented semantic planes when present; stored scope
36
36
  }
37
37
  ```
38
38
 
39
- - `intents` retains only chosen active commitments.
39
+ - `intents` retains only chosen active commitments, not a planner, scheduler, task manager or execution loop.
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.
@@ -51,13 +51,13 @@ global → CWD → session
51
51
 
52
52
  Later scopes win. A scope-local `null` deletion removes only that scope's key and may reveal an inherited value. Scope represents applicability and ownership, never instruction authority.
53
53
 
54
- Missing planes are valid sparse semantics, not incomplete storage. Checkpoint/tail codecs select only known top-level fields on read and write; unknown fields are not retained in runtime streams or carried into later writes. Nested data within known planes remains intact. Retained record identities and positions survive even when filtering leaves an empty patch. `readTemporalView` selects present known fields at the requested boundary, then overlays scopes without inventing fields. Empty and absent responses have the same projection meaning. `readTemporalState` and the embedding callback retain default-bearing compatibility views for internal registry consumers; those defaults never become stored overrides or model context. Passive reads and Start do not fill checkpoint fields or create revisions for normalization; missing shared pairs initialize as empty objects. Authored staging uses raw scope presence and derives replay from actual writes. Existing empty/no-op tail records retain their proven boundaries; new no-op writes still create none. Present documented fields retain usable object/string types, valid artifact entries and the no-stored-null rule; ignored fields may contain arbitrary JSON. Malformed JSON and invalid storage/history authority remain errors.
54
+ Missing planes are valid sparse semantics, not incomplete storage. Checkpoint/tail codecs select only known top-level fields on read and write; unknown fields are not retained in runtime streams or carried into later writes. Nested data within known planes remains intact. Retained record identities and positions survive even when filtering leaves an empty patch. `readTemporalView` selects present known fields at the requested boundary, then overlays scopes without inventing fields. Empty and absent responses have the same projection meaning; clearing a nonempty response projects as deletion. Explicit reads of absent documented top-level fields return `null`. `readTemporalState` and the embedding callback retain default-bearing compatibility views for internal registry consumers; those defaults never become stored overrides or model context. Passive reads and Start do not fill checkpoint fields or create revisions for normalization; missing shared pairs initialize as empty objects. Authored staging uses raw scope presence and derives runtime-normalized replay from actual accepted writes, including complete artifact replacement; replay must reproduce accepted state exactly. Existing empty/no-op tail records retain their proven boundaries; new no-op writes still create none. Present documented fields retain usable object/string types, valid artifact entries and the no-stored-null rule; ignored fields may contain arbitrary JSON. Malformed JSON and invalid storage/history authority remain errors.
55
55
 
56
56
  State Flow is the memory owner while enabled. Cross-project/user/environment knowledge belongs in global state, project-only knowledge in CWD, and branch/run continuation in session. Global availability is not a feature switch and does not authorize secrets, raw history, transient progress, speculative clutter, or unsupported assertions. Explicitly uncertain hypotheses remain eligible only when they can affect an open decision.
57
57
 
58
58
  ## Temporal model
59
59
 
60
- All scopes participate in one active causal lineage. One accepted semantic transition receives one opaque identity shared by every changed scope. Sparse transitions do not create records for unchanged scopes.
60
+ All scopes participate in one active causal lineage. One accepted semantic transition receives one opaque identity shared by every changed scope. A branch-local position may order identities but never substitutes for a global counter or merges forks; origin adoption is not an invented semantic transition or retry loop. Sparse transitions do not create records for unchanged scopes.
61
61
 
62
62
  Each scope stores:
63
63
 
@@ -65,11 +65,11 @@ Each scope stores:
65
65
  checkpoint.json + patches.jsonl
66
66
  ```
67
67
 
68
- The checkpoint is an older anchored materialization. The tail contains at most the configured `historyLimit` effective patches. On overflow, the oldest tail patch folds into the checkpoint before the new patch is appended.
68
+ The checkpoint is an older anchored materialization. Current scope state is exactly `materialize(checkpoint.json, patches.jsonl, meta.json)` at the selected anchored boundary; the tail contains at most the configured `historyLimit` effective patches. On overflow, the oldest tail patch folds into the checkpoint before the new patch is appended; unapplied replay records are never truncated or replayed over an already-current snapshot.
69
69
 
70
70
  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.
71
71
 
72
- `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.
72
+ `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. Once enough accepted transitions are proven, offsets zero through the configured `historyLimit` remain addressable at their shared causal boundaries.
73
73
 
74
74
  A changed accepted response is runtime-owned, session-only semantic state and advances history. An accepted empty answer finalizes normally; it clears a previous nonempty response, but does not create a transition merely to replace an absent response with `""`. Ordinary completion requires no `patch_state` call when durable semantic state is already correct.
75
75
 
@@ -83,6 +83,8 @@ Unreported state changes, changing artifact hints, invalidation lists and rehydr
83
83
 
84
84
  Tool preflight follows Pi's public `getLeafEntry()` / `getEntry(parentId)` links to the nearest assistant containing the current call ID. It inspects that response's complete tool batch without constructing the whole branch or caching a batch across calls/selections. Foreign custom entries and earlier sibling results remain in the native trace. A missing call ID still searches the selected ancestry and preserves the existing unmatched-call behavior; this is not an unconditional constant-time guarantee. See [measured traversal evidence](performance.md#tool-preflight-parent-traversal).
85
85
 
86
+ Opt-in local JSONL diagnostic categories are `invalid-patch`, `publication-conflict`, `finalization` and `barrier-block`. Active preflight records each blocked call when a batch has multiple `patch_state` calls or a sibling of its single `patch_state` call. A `barrier-block` record has the blocked tool name, call id, existing block reason and ordered batch tool names only: it does not capture sibling arguments, reasoning or draft content. Logging off creates no barrier record; Passive has no barrier. Diagnostic persistence is outside canonical state and cannot change the blocking decision. Asynchronous Git push failure detail is the separate logging-off exception; see [diagnostic privacy](usage.md#diagnostic-logging-and-privacy).
87
+
86
88
  `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.
87
89
 
88
90
  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.
@@ -103,15 +105,17 @@ A proven pre-runtime branch has no accepted runtime to persist: an inactive new-
103
105
 
104
106
  Explicit Start independently prepares the validated current same-session canonical cohort rather than replaying the selected Pi pointer. Active/passive or unfinished runtime metadata and expired/pre-runtime selections do not erase current private memory or block activation. `withStartTransaction` acquires exclusion before capture and binds private stream identity to current runtime lineage, with one synchronous, single-use exact-cohort acceptance before installation. Pending repeats share the same operation. Current branch/physical identity, initialization permission and bootstrap context are rechecked after waiting; Stop, selection and shutdown withdraw obsolete activation. Only acceptance enables the new mode, clears Stop fences and cancels older Stop persistence. Caches, preparation policy and one native checkpoint install before yielding without a second persistence call; a later failure cannot roll them back. Commands, deferred settled Start and Telegram await completion, and presentation receipts for both success and failure revoke with selection. It preserves private values, artifact provenance, independent revisions and step, discards the old unfinished specification, and retains available aligned history within the configured limit. Incompatible but independently valid live shared streams require a fresh origin rather than invented cross-writer history. An empty session origin is allowed only with wholly absent private authority and initialization-safe branch provenance; incomplete or contradictory evidence remains closed. Initial physical fork copying still requires its exact-source contract; an already accepted child can activate its own current memory without recopying its parent. Repeated Start while already active does not change the current run or pending response reconciliation.
105
107
 
106
- 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.
108
+ The Pi adapter's Passive 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.
109
+
110
+ Passive selection immediately applies the selected tools/context policy and disables active response/compaction behavior before attempting canonical persistence. For accepted runtimes it freezes the passive handoff immediately, then awaits `withLifecycleTransaction` with Stop-owned cancellation and any available Pi operation signal. Pending inactive choices share one acceptance of the latest mode. After acquisition, recheck runtime/physical owner/policy and derive the snapshot from current lifecycle state, including an intervening same-instance passive patch. Successful publication installs the adopted shared cache, final handoff and native checkpoint before yielding. Off, session/tree selection, shutdown or accepted Start revoke obsolete Passive persistence; a failed Start leaves it pending. Shutdown drains the canceled operation. A post-acceptance lifecycle failure never restores old metadata or retries native writes. If persistence fails, it keeps accepted cached memory and all available native context, then records `owner`, the selected inactive `mode`, `persistenceError` and `preserveContext: true` in the existing native passive-stop marker. This is a same-session policy override and write fence, not semantic authority or a substitute checkpoint. No canonical failure is repaired by resetting memory. Memory-enabled tree/reload/resume with that pending marker use `TemporalRuntime.refreshCurrentMemory()` to validate and read current memory without historical restoration or publication; unavailable evidence remains unavailable. A later accepted checkpoint supersedes the fence, while preserving the context boundary for bootstrap. Repeating the same degraded choice is inert; another inactive choice updates only native policy and preserves the fence. An in-flight read-only recovery retains a repeated Passive choice; Off cancels it before further acquisition. Successful explicit Start uses the same detached validation path under CAS before clearing the fence. Status and inspection distinguish accepted cached/read-only memory from unavailable publication. If Pi's own trace is unwritable, the local disablement still precedes the error, but durable fallback cannot be guaranteed.
107
111
 
108
- Passive/Off selection immediately applies the selected tools/context policy and disables active response/compaction behavior before attempting canonical persistence. For accepted runtimes it freezes the passive handoff immediately, then awaits `withLifecycleTransaction` with Stop-owned cancellation and any available Pi operation signal. Pending inactive choices share one acceptance of the latest mode. After acquisition, recheck runtime/physical owner/policy and derive the snapshot from current lifecycle state, including an intervening same-instance passive patch. Successful publication installs the adopted shared cache, final handoff and native checkpoint before yielding. Session/tree selection, shutdown or accepted Start revoke obsolete Stop work; a failed Start leaves it pending. Shutdown drains the canceled operation. A post-acceptance lifecycle failure never restores old metadata or retries native writes. If persistence fails, it keeps accepted cached memory and all available native context, then records `owner`, the selected inactive `mode`, `persistenceError` and `preserveContext: true` in the existing native passive-stop marker. This is a same-session policy override and write fence, not semantic authority or a substitute checkpoint. No canonical failure is repaired by resetting memory. Tree/reload/resume with that pending marker use `TemporalRuntime.refreshCurrentMemory()` to validate and read current memory without historical restoration or publication; unavailable evidence remains unavailable. A later accepted checkpoint supersedes the fence, while preserving the context boundary for bootstrap. Repeating the same degraded choice is inert; another inactive choice updates only native policy and preserves the fence. An in-flight read-only recovery applies the latest choice, never an older captured mode. Successful explicit Start uses the same detached validation path under CAS before clearing the fence. Status and inspection distinguish accepted cached/read-only memory from unavailable publication. If Pi's own trace is unwritable, the local disablement still precedes the error, but durable fallback cannot be guaranteed.
112
+ Off uses a separate local owner: it aborts restore/fork, activation, preparation, response, model-patch and Passive-persistence lifetimes, clears cached semantic views and records native policy without any canonical transaction. A usable cached accepted boundary may be bookmarked read-only in a native Off checkpoint; an unusable cached bookmark never prevents local Off or authorizes replacement memory. The owner-local stop marker's `memoryDeferred: true` plus `mode: "off"` selects Off even when canonical runtime mode is still Active/Passive. It also retains continuation timestamps, a carried write fence and an unaccepted fork marker when needed. Exact selected-boundary restoration remains separate from current-memory Active; already accepted canonical bytes are not rolled back. Late canceled model patches do not log memory diagnostics. Automatic context, Skill/artifact tracking, queued tool failures, settlement and shutdown callbacks remain memory-inert in Off, including with opt-in logging. Only native policy bookkeeping and release of already-owned protocol resources survive.
109
113
 
110
114
  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 activating mid-tool and repeated mode changes retain the actual first-user timestamp. Native user-run preparation and session-start/tree events reset capture; semantic mode changes do not. The same marker accepts optional `preserveContext: true` when compilation is unfinished and no narrower incoming boundary is sufficient; omitted flags keep legacy selection behavior. This projection flag creates no semantic storage authority. 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. An interrupted run keeps its captured anchor even after Pi becomes idle; if capture is unavailable, Stop preserves all available context. Completed idle runs and legacy markers without an active anchor or preservation flag 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.
111
115
 
112
116
  The current user specification stays at user authority and appears only in synthetic user runtime context. State is fallible assistant-produced data. Active/passive protocol contributes to Pi's native `state_flow` system-prompt section at `before_agent_start`, rather than forcing the entire prompt. Later companion sections and `context_with_system` transformations compose normally; explicit foreign forced prompts retain Pi's documented precedence. Native section diffs remove/reinstate the initial protocol across user requests. At `context_with_system`, the context domain also refreshes only the owned section from current enablement/bootstrap/passive policy, covering Stop/Start inside the same tool loop and accepted-boundary continuations. Unchanged effective protocol reuses the original array without relocating native deltas; a changed mode preserves foreign sections/content/tools and conversation identity/order without mutating native frames or creating missing system authority. Accepted completion removes the specification, not memory availability: a companion's actionable `turn_end` or `agent_before_settle` continuation can request another inference without `before_agent_start`. Every enabled request still gets one current-memory projection, omitting an absent specification and using the captured native anchor when available; no synthetic user run, persisted continuation field or State Flow scheduler is created. Completed trajectories leave model context at user-run boundaries, while Pi's full JSONL trace remains inspectable.
113
117
 
114
- After an accepted non-bootstrap run settles with no queued input, State Flow may request native manual compaction under a generation-private marker when public `getContextUsage()` reports at least 24,000 tokens. The settled handler awaits native completion/error callbacks before returning, so Pi can dispatch deferred companion prompts after every observer finishes without racing an in-flight manual compaction. This waits for one existing native operation, without adding a timer, queue or second continuation owner. This token signal provides a modest margin above Pi's default 20,000-token retained suffix; Pi still owns preparation and may benignly decline when custom settings leave no compactable prefix. The extension supplies no model-generated state body: it forwards the existing `runAnchorTimestamp` to the planner, requires one matching native user entry, and keeps the complete accepted run including later steering and tools. A missing, ambiguous, or unanswered anchor produces no request; the planner never falls back to the nearest user message. Compaction details still contain only the retained semantic boundary/step. `buildContextEntries()` then omits the older completed prefix while append-only JSONL/tree history remains intact.
118
+ After an accepted non-bootstrap run settles with no queued input, State Flow may request native manual compaction under an extension-private prefix and a fresh per-request marker when public `getContextUsage()` reports at least 24,000 tokens. The settled handler awaits native completion/error callbacks before returning, so Pi can dispatch deferred companion prompts after every observer finishes without racing an in-flight manual compaction. The `state-flow-boundary:` namespace identifies owned requests even after extension recreation. Inactive, missing-plan, completed or superseded owned requests return cancellation even after transient-plan cleanup, never default model-summary fallback. Callback completion clears only its own marker's plan; an old callback cannot clear a new request. Foreign manual and native threshold/overflow hooks remain untouched. This waits for one existing native operation, without adding a timer, queue or second continuation owner. This token signal provides a modest margin above Pi's default 20,000-token retained suffix; Pi still owns preparation and may benignly decline when custom settings leave no compactable prefix. The extension supplies no model-generated state body: it forwards the existing `runAnchorTimestamp` to the planner, requires one matching native user entry, and keeps the complete accepted run including later steering and tools. A missing, ambiguous, or unanswered anchor produces no request; the planner never falls back to the nearest user message. Compaction details still contain only the retained semantic boundary/step. `buildContextEntries()` then omits the older completed prefix while append-only JSONL/tree history remains intact.
115
119
 
116
120
  Pi 0.87 supports retain-none boundary compactions, but State Flow intentionally does not use them. Completed canonical state omits the exact user prompt, and foreign custom context can legitimately occur inside the latest retained iteration; hiding both would make the projected semantic state a lossy substitute for native context. Unknown or smaller usage, foreign custom metadata or native `custom_message` context in the removed prefix, stale selection, Stop/bootstrap/error/abort, and pending input do not produce this boundary. User manual and native threshold/overflow compaction remain unmodified; unaccepted work stays under Pi's native compaction contract.
117
121
 
@@ -138,13 +142,13 @@ meta.json
138
142
  <cwd-key>/<session-key>/runtime.json
139
143
  ```
140
144
 
141
- CWD and session keys mirror Pi's native encoding. The Pi UUID remains authoritative; readable directory keys never replace identity validation.
145
+ CWD and session keys mirror Pi's native encoding, deriving the in-memory session key from `<header timestamp>_<UUID>` when no JSONL basename exists. The Pi UUID remains authoritative; readable directory keys never replace identity validation. Reject unsafe segments, mismatches and CWD-key ownership collisions rather than selecting a different scope.
142
146
 
143
- Root `config.json` is read-only operator configuration whose `mode` supplies the new-session default (Passive when absent); 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` serializes only its concrete `mode` (`active`, `passive`, `off`), independently of later global defaults; 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 inactive pre-runtime `{mode}` marker. Supported legacy flags decode read-only; mixed session `mode`/`enabled` representations are rejected, and no eager migration runs. Revision-pointer checkpoints are unsupported and fail closed without Git restoration.
147
+ Root `config.json` is read-only operator configuration whose `mode` supplies the new-session default (Off when absent and no legacy mode flags are present); 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` serializes only its concrete `mode` (`active`, `passive`, `off`), independently of later global defaults; session `runtime.json` asymmetrically owns lineage, the internal branch step, session identity, and the full specification only while a run is unfinished. Runtime metadata stores no storage receipt, Git identity, temporal revision pointer, publication mode or push intent. 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 inactive pre-runtime `{mode}` marker. Supported legacy flags and native `{disabled:true}` markers decode read-only; mixed session `mode`/`enabled` representations are rejected, and no eager migration runs. Revision-pointer checkpoints are unsupported and fail closed without Git restoration.
144
148
 
145
149
  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).
146
150
 
147
- All owned writes use same-directory atomic replacement, regular-file and symlink checks, prepared byte receipts and CAS validation. Unrelated files and detected concurrent bytes are preserved. Rollback restores only bytes still matching the failed publisher's output.
151
+ All owned writes use same-directory atomic replacement, regular-file and symlink checks, prepared opaque source-byte receipts and CAS validation. Unrelated files and detected concurrent bytes are preserved. Rollback restores only bytes still matching the failed publisher's output. Use validated structural JSON equality for in-process semantic comparisons; cryptographic hashes are for compact identities crossing process or persistence boundaries.
148
152
 
149
153
  ### Asynchronous storage transaction
150
154
 
@@ -174,7 +178,9 @@ Accepted-answer reconciliation also uses `withPatchTransaction`: `turn_end` awai
174
178
 
175
179
  `TemporalRuntime.refreshCurrentMemory(signal?)` supplies an awaited read-only recovery view of current same-session authority. It shares current-memory validation with Start, but neither publishes nor accepts write authority: returned policy is disabled and unfinished specifications are omitted. Current private values, step, revisions, bootstrap and provenance remain available beside independently validated shared streams; retention is constrained only in memory. Absence returns `undefined` without creation, and malformed evidence or cancellation (including during capture) leaves the prior cache unchanged. Lifecycle/patch publication still requires accepted authority or explicit Start. Native failed-Stop reload uses it and keeps the write fence.
176
180
 
177
- Native `session_start` and `session_tree` await one extension-owned branch restoration. Its synchronous prelude revokes older selection work, pins session id, file, header timestamp and CWD, and selects active-branch evidence through the recovery domain's pure `selectRetainedCheckpoint`: newer malformed envelopes are skipped, while revision pointers and every failure resolving the selected boundary fail closed. While it waits, mode is the selected inactive policy and private reads/publication report the pending selection. The selected boundary, exact-source fork, truly new auto-start origin (`withStartTransaction` with creation authority, rechecking branch evidence after waiting) or failed-Stop read-only recovery then use the awaited runtime API. Bootstrap/policy derive after waiting and publish in that single acceptance; only the current lifetime installs memory, checkpoint, continuation, tools and UI before yielding, and later native-write failure only warns. New selection revokes older work; shutdown drains current and superseded restoration operations. Passive/Off selection never cancels retained restoration, new-session initialization or fork copying, including attachment requested by a now-cancelled Active waiter. The pending publisher applies the latest inactive policy inside its single acceptance; Passive can then patch memory without an artificial error fence, while Off exposes no model access. Repeated selections are inert with respect to that acceptance. Start after Stop joins the independent memory operation before activating current memory. Selection changes, shutdown and native operation cancellation still revoke obsolete work; real validation/publication failures remain unavailable rather than becoming empty memory. Start joins pending restoration, owns initial attachment and fork retry without cancelling itself, and is inert when the result is active. A cancelled Start withdraws its join without cancelling independently owned restoration or Stop persistence. Read-only recovery uses detached candidates and rechecks cancellation/physical identity before host installation; passive attachment cannot overwrite a newer cache established by an intervening patch or inspection. Six synchronous runtime methods remain supported for library consumers and local tests/benchmarks; production lifecycle wiring uses the awaited APIs. Their contracts and cancellation boundaries are documented in [library API compatibility](compatibility.md#state-flow-library-api-compatibility).
181
+ Native `session_start` and `session_tree` first read only mode policy through `session.findBranchPolicy` and `snapshot.readCheckpointMode`. Off attaches without constructing a temporal runtime, resolving semantic boundaries, reading memory or emitting recovery warnings; native mode/write-fence bookkeeping remains available. Deferred fork ownership is recorded in a child-owned `forkPending` native marker and survives extension recreation; accepted child initialization resets it. Explicit Passive restores the deferred selected boundary (or fenced read-only current authority), while explicit Active retains documented current-memory activation after attachment. Policy decoding is never proof that a historical boundary is valid. Automatic callbacks remain memory-inert in Off; installed-client acceptance gates remain separate in [BACKLOG](../BACKLOG.md).
182
+
183
+ Memory-enabled native `session_start` and `session_tree`, and explicit acquisition after an Off attachment, await one extension-owned branch restoration. Its synchronous prelude revokes older selection work, pins session id, file, header timestamp and CWD, and selects active-branch evidence through the recovery domain's pure `selectRetainedCheckpoint`: newer malformed envelopes are skipped, while revision pointers and every failure resolving the selected boundary fail closed. While it waits, mode is the selected inactive policy and private reads/publication report the pending selection. The selected boundary, exact-source fork, truly new auto-start origin (`withStartTransaction` with creation authority, rechecking branch evidence after waiting) or failed-Stop read-only recovery then use the awaited runtime API. Bootstrap/policy derive after waiting and publish in that single acceptance; only the current lifetime installs memory, checkpoint, continuation, tools and UI before yielding, and later native-write failure only warns. New selection revokes older work; shutdown drains current and superseded restoration operations. Passive selection retains independently owned restoration, new-session initialization and fork copying, including attachment requested by a now-cancelled Active waiter. Off cancels those owned waits and retains only native policy/source bookkeeping for later explicit acquisition. The pending publisher applies the latest inactive policy inside its single acceptance; Passive can then patch memory without an artificial error fence, while Off exposes no model access. Repeated selections are inert with respect to that acceptance. Start joins retained Passive acquisition; after Off, non-fork Active goes directly through one cancellable current-head Start transaction, keeping the deferred native selection and local Off policy until publication. A superseding Passive cancels that activation and acquires its original retained private boundary, not the current-memory candidate; native Abort silently withdraws Active without inventing a write fence or losing later acquisition choices. Accepted activation reconstructs any native continuation from its proven current memory. Exact-source fork acquisition retains its independent restoration owner. Selection changes, shutdown and native operation cancellation still revoke obsolete work; real validation/publication failures remain unavailable rather than becoming empty memory. Start joins pending restoration, owns initial attachment and fork retry without cancelling itself, and is inert when the result is active. A cancelled Start withdraws its join without cancelling independently owned restoration or Stop persistence. Read-only recovery uses detached candidates and rechecks cancellation/physical identity before host installation; passive attachment cannot overwrite a newer cache established by an intervening patch or inspection. Six synchronous runtime methods remain supported for library consumers and local tests/benchmarks; production lifecycle wiring uses the awaited APIs. Their contracts and cancellation boundaries are documented in [library API compatibility](compatibility.md#state-flow-library-api-compatibility).
178
184
 
179
185
  The advisory [continuation-candidate reader](#session-continuation) also awaits coherent capture. Current-head activation on an attached branch uses the awaited Start transaction. Raw precomputed replay keeps its selected-target guard, unlike current-head authored patch staging. Model inference, source acquisition and Git commands do not belong inside a canonical critical section; artifact freshness validation remains part of publication validation.
180
186
 
@@ -186,11 +192,11 @@ Scope artifact provenance records only current evidence. Restore/fork drops sess
186
192
 
187
193
  After response reconciliation and Pi's retry/queue processing, `agent_before_settle` may commit the already-accepted State Flow-owned files once. `backupCurrentStateFlowFiles(root, signal?, waitForLock = true)` now returns `Promise<string | undefined>` and must be awaited. It awaits its own Git mutex and canonical exclusion to inventory the bounded root/CWD/session namespace and capture regular-file bytes, then releases canonical exclusion before every Git command or filter. `withFilePublicationLock` owns the shared acquisition/release mechanics: both mutexes retain exact ownership across awaits, refuse recursion and preserve replacement owners or combined action/cleanup failures. The backup mutex spans capture and Git completion; the branch/head is rechecked after waiting. It never descends into artifact sources, `.git`, or unrelated directory trees. A private temporary worktree/index stages the captured snapshot with Git ignore/filter policy preserved; concurrent writers may advance canonical files without changing that snapshot.
188
194
 
189
- Settlement combines an available Pi operation signal with shutdown cancellation and awaits the local backup; shutdown cancels and drains its own attempts before waiting for remote pushes. Pi SDK 0.87 has no operation signal at `agent_before_settle`, and native Abort cannot cancel a wait there. On such a host the adapter passes `waitForLock = false`: uncontended work proceeds, while live/initializing ownership raises `PublicationBusyError` and produces an explicit backup-deferred notice. Invalid/interrupted evidence remains an error, never a successful or partial capture. No commit or push follows deferral; a later accepted turn may retry. This is a narrow optional-backup admission policy, not semantic-write conflict repair or an operator configuration. The operator accepts this best-effort deferral independently of power-loss durability and retains `agent_before_settle` as the backup boundary. Moving backup to `turn_end` or extending the SDK solely for settlement waiting is not planned; backup is not a stronger canonical persistence guarantee. See the [SDK boundary evidence](compatibility.md#settlement-cancellation).
195
+ Settlement combines an available Pi operation signal with the extension-owned backup lifetime and awaits the local backup. Off or shutdown revoke that lifetime, cancel pending capture and suppress late reporting; only release of already-owned locks/resources may continue. An Off attachment revokes the previous memory-enabled background lifetime too. Shutdown drains its own attempts before waiting for remote pushes. Pi SDK 0.87 has no operation signal at `agent_before_settle`, and native Abort cannot cancel a wait there. On such a host the adapter passes `waitForLock = false`: uncontended work proceeds, while live/initializing ownership raises `PublicationBusyError` and produces an explicit backup-deferred notice. Invalid/interrupted evidence remains an error, never a successful or partial capture. No commit or push follows deferral; a later accepted turn may retry. This is a narrow optional-backup admission policy, not semantic-write conflict repair or an operator configuration. The operator accepts this best-effort deferral independently of power-loss durability and retains `agent_before_settle` as the backup boundary. Moving backup to `turn_end` or extending the SDK solely for settlement waiting is not planned; backup is not a stronger canonical persistence guarantee. See the [SDK boundary evidence](compatibility.md#settlement-cancellation).
190
196
 
191
197
  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.
192
198
 
193
- 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.
199
+ 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. `pushCurrentStateFlowBackup(root, signal?)` and `startStateFlowBackupPush(root, onFailure, onSuccess?, signal?)` accept an optional caller-owned cancellation signal; overlap refusal does not attach the rejected caller's signal to the existing push. The adapter passes its captured backup-lifetime signal, not the completed agent-operation signal. Off/shutdown terminate only their admitted process group, retain the in-flight slot until process close, and suppress canceled success/failure callbacks. Already accepted commits remain intact; cancellation is not remote rollback. 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.
194
200
 
195
201
  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.
196
202
 
@@ -200,7 +206,7 @@ Predecessor checkpoint envelopes, combined session metadata, `state.json`, hashe
200
206
 
201
207
  State Flow never discovers source directories. Before enabled inference it inspects only exact source paths already registered as artifacts in global, CWD, or session state. Observation uses regular non-symlink file metadata `{size, mtimeNs}` without reading bodies. Proven absence removes the artifact from each owning scope; unavailable, relative, directory, or symlink evidence is non-destructive. Unregistered files are never observed.
202
208
 
203
- A model-visible artifact entry requires only a description:
209
+ A model-visible artifact entry requires only a non-empty description:
204
210
 
205
211
  ```json
206
212
  {
@@ -209,21 +215,21 @@ A model-visible artifact entry requires only a description:
209
215
  }
210
216
  ```
211
217
 
212
- Runtime-owned compilation evidence is retained per scope in `meta.json`; current ordinary artifacts use `sourceFingerprint: {size, mtimeNs}` plus `compilerRevision`, while retained `sourceHash`/`compiledAt` are transitional compatibility evidence. At artifact-entry level, every model scope patch rejects authored `hash`, `compiler`, `compiled_at`, `sourceHash`, `sourceFingerprint`, `compilerRevision`, `compiledAt`, `source_hash_verified`, and `hint` fields, including field-deletion markers, even without a preceding read. Retained legacy evidence stays readable; ordinary semantic edits and whole-artifact deletion remain valid. Compiler output may add other finite non-null JSON metadata; known optional semantic fields include `kind`, `tags` and `compilation`. Tags are unique trimmed non-empty strings and support deterministic candidate filtering, but never authorize reading.
218
+ Runtime-owned compilation evidence is retained per scope in `meta.json`; current ordinary artifacts use `sourceFingerprint: {size, mtimeNs}` plus `compilerRevision`, while retained `sourceHash`/`compiledAt` are transitional compatibility evidence. At artifact-entry level, every model scope patch rejects authored `hash`, `compiler`, `compiled_at`, `sourceHash`, `sourceFingerprint`, `compilerRevision`, `compiledAt`, `source_hash_verified`, and `hint` fields, including field-deletion markers, even without a preceding read. Retained legacy evidence stays readable but its embedded `hash`/`compiler`/`compiled_at` fields are omitted from model projection; ordinary semantic edits and whole-artifact deletion remain valid. Compiler output may add other finite non-null JSON metadata; known optional semantic fields include `kind`, `tags` and `compilation`. Tags are unique trimmed non-empty strings and support deterministic candidate filtering, but never authorize reading.
213
219
 
214
- 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.
220
+ The retired `contract.compiled_skills` location is rejected; Skill compilations belong only in source-addressed artifacts, with no fabricated source hashes. 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.
215
221
 
216
222
  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.
217
223
 
218
224
  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.
219
225
 
220
- 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.
226
+ Skill acquisition applies only to exact registered Pi Skills. State Flow resolves identity and ownership through the public `getCommands()` inventory's `sourceInfo.scope`, 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 at the reported scope and path requires a non-empty description, `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. The accepted compilation replaces the complete prior Skill card and provenance, storing runtime-owned `sourceHash` and `skill-artifact-v1` `compilerRevision`; obsolete evidence cannot survive refresh. Source bodies do not persist in state. Matching provenance proves source-version consistency, not semantic fidelity, truth, or higher instruction authority.
221
227
 
222
228
  ## Operational guidance and memory curation
223
229
 
224
230
  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.
225
231
 
226
- 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.
232
+ Curation may persist reusable guidance from a registered Skill at its provenance-derived scope. Treat terminal state as a decision-relevant handoff rather than a progress transcript: retain operational knowledge in source-addressed artifacts, confirmed constraints/decisions and rejected approaches in contract, observations/failures/uncertainties and exact continuation in working, and only chosen active commitments in intents. Distinguish user requirements from assistant conclusions and hypotheses; preserve consequential negative evidence and reconsideration conditions. Do not silently overwrite established constraints when evidence conflicts, treat working observations as live external facts, or infer success/absence of external effects from restored memory. After interruption, inspect the relevant effects before repetition. These are model stewardship duties, not deterministic semantic gates. 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.
227
233
 
228
234
  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.
229
235
 
@@ -250,7 +256,7 @@ The [tested Pi SDK baseline](compatibility.md) chooses or creates `SessionManage
250
256
 
251
257
  ### Model tools
252
258
 
253
- `patch_state` accepts one or more fixed `global`, `cwd`, and `session` semantic patches. Supplied scopes contain object-valued `artifacts`, `contract`, `working`, and `intents`, plus object-valued `lazy` whose nested values are ordinary JSON; omitted fields preserve their values, recursive object merge updates them, arrays/primitives replace, and nested object-key `null` deletes. Materialized null, empty supplied scopes, unknown top-level fields, model-authored `response`, and retired finalization or patch grammars are rejected. Correct repeated results succeed as `State already current.` without another semantic revision or history record; avoid gratuitous acknowledgment patches. Global/CWD overlap follows successful acceptance order, while unmentioned current fields survive. Session ownership is not a shared-memory merge.
259
+ `patch_state` accepts one or more fixed `global`, `cwd`, and `session` semantic patches. Supplied scopes contain object-valued `artifacts`, `contract`, `working`, and `intents`, plus object-valued `lazy` whose nested values are ordinary JSON; omitted fields preserve their values, recursive object merge updates them, arrays/primitives replace, and nested object-key `null` deletes. Materialized null within documented semantic planes, empty supplied scopes, unknown top-level fields, model-authored `response`, and retired finalization or `{scope, patch}` / `unchanged` grammars are rejected. The semantic null rule does not apply to runtime envelopes such as an origin's null parent. Correct repeated results succeed as `State already current.` without another semantic revision or history record; avoid gratuitous acknowledgment patches. Global/CWD overlap follows successful acceptance order, while unmentioned current fields survive. Session ownership is not a shared-memory merge.
254
260
 
255
261
  ```json
256
262
  {"session":{"intents":{"next":"Verify the corrected behavior"}}}
@@ -270,7 +276,7 @@ The [tested Pi SDK baseline](compatibility.md) chooses or creates `SessionManage
270
276
 
271
277
  Unscoped semantic paths such as `intents.next` alias the current effective overlay. `value`, `keys`, and `patch` projections plus ordered `paths` batches remain all-or-error.
272
278
 
273
- Both tools are exposed in Active/Passive and withdrawn in Off, subject to host restrictions. The patch barrier also blocks reader siblings. These tools do not impose project schemas or state-size caps; semantic usefulness, scope choice, and compression remain model responsibilities. Ordinary handoffs reconcile touched state. Dedicated cleanup and scope review require an explicit user request, including at feature/release/project boundaries. Global retains established cross-project/user/environment knowledge, CWD owns reusable project truth, and session owns branch/run continuation. Intra-store moves use targeted owner reads and one atomic multi-scope patch followed by verification; external moves require verified destination acceptance before source deletion.
279
+ Both tools are exposed in Active/Passive and withdrawn in Off, subject to host restrictions; mode toggles preserve unrelated active tools. Passive reads never initialize storage, but an explicit passive patch may initialize absent canonical storage without starting an episode. The patch barrier also blocks reader siblings. These tools do not impose project schemas or state-size caps; semantic usefulness, scope choice, and compression remain model responsibilities. Ordinary handoffs reconcile touched state. Dedicated cleanup and scope review require an explicit user request, including at feature/release/project boundaries. Global retains established cross-project/user/environment knowledge, CWD owns reusable project truth, and session owns branch/run continuation. Intra-store moves use targeted owner reads and one atomic multi-scope patch followed by verification; external moves require verified destination acceptance before source deletion.
274
280
 
275
281
  ### Embedding
276
282
 
@@ -284,12 +290,12 @@ Agent configuration is read once per extension load; session runtime configurati
284
290
 
285
291
  ## Observability
286
292
 
287
- The inspection-capable Telegram port accepts synchronous or Promise-returning `select(mode)` results with optional revocation signals, while the legacy `StateFlowTelegramPort` stays synchronous. Controls initiate callback acknowledgement alongside execution rather than waiting for a network round trip before local Stop. Final feedback follows completion, uses the current menu and escapes late failures without answering the callback twice. Revoked receipts, newer callback navigation and disposal suppress stale view writes; they never roll back canonical acceptance.
293
+ The inspection-capable Telegram port accepts synchronous or Promise-returning `select(mode)` results with optional revocation signals, while the legacy `StateFlowTelegramPort` stays synchronous. Controls initiate callback acknowledgement alongside execution rather than waiting for a network round trip before local Stop. Final feedback follows completion, uses the current menu and escapes late failures without answering the callback twice. Revoked receipts, newer callback navigation and disposal suppress stale view writes; they never roll back canonical acceptance. Obsolete start/stop callback keyboards may refresh the current view but never silently select a mode.
288
294
 
289
- Status is a projection of the selected runtime and semantic view, not a second store. Compact terminal status uses accent `state-flow` with dim `active` or `passive`, and is hidden in Off. Telegram main-menu status uses `State Flow: active`, `State Flow: passive` or `State Flow: off`. `/state-flow-status` retains the `g#c#s#` vector beside concise diagnostics and blank-line-separated top-level semantic JSON. Mode is read directly from the session's selected enum, never derived from a pending patch or separate passive flags. 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 presents the current mode as a monospace value in the submenu heading and describes all modes with `<code>-</code> <code>value</code>` settings-card lines above one lowercase `off | passive | active` option row with only the current option marked, followed immediately by four direct scope-inspection buttons; inspection remains available in all three modes. 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. The awaited `StateFlowTelegramInspectionPort` returns a `StateFlowTelegramInspection` containing state and matching revisions, plus an optional revocation signal checked immediately before presentation. Stop, selection changes and shutdown cancel obsolete reads without altering newer memory or clearing write fences. The existing synchronous `StateFlowTelegramPort` contract remains supported. A callback is acknowledged before waiting; late failures appear escaped in the existing menu, without a second answer to an expired query. 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).
295
+ Status is a projection of the selected runtime and semantic view, not a second store. Compact terminal status uses accent `state-flow` with dim `active` or `passive`, and is hidden in Off. Telegram main-menu status uses `State Flow: active`, `State Flow: passive` or `State Flow: off`. `/state-flow-status` retains the `g#c#s#` vector beside concise diagnostics and blank-line-separated top-level semantic JSON. Mode is read directly from the session's selected enum, never derived from a pending patch or separate passive flags. 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 presents the current mode as a monospace value in the submenu heading, followed by matching Mode and Inspect memory headings (long-dash-separated description ending in a colon), each separated by a blank line from its settings-style monospaced-key list, above one radio row `Off | Passive | Active`: selected Off uses 🟡, Passive 🟣 or Active 🟢, and inactive choices use ⚫️; four direct scope-inspection buttons follow, while inspection remains available in all three modes. Inspection may refresh live Global/CWD streams in memory so foreign accepted revisions become visible, but never publishes or increments a revision. Off inspection uses a fresh disposable `TemporalRuntime`: Global/CWD use coherent shared reads; Session/Effective use `refreshCurrentMemory` and reject absent, incomplete or malformed same-session private evidence rather than manufacturing an empty layer/revision or borrowing foreign private data. A result checks its revocation lifetime and physical owner before presentation. No reader installs the extension runtime/cache, changes native policy or canonical bytes, clears a carried write fence, acquires an unaccepted fork parent, or replaces the selected historical target. Expired selected history may coexist with inspectable current stored memory; later Passive still restores the selected past fail-closed while Active validates current memory. Memory-enabled inspection retains its accepted-private/shared-refresh and failed-Passive cache rules. The awaited `StateFlowTelegramInspectionPort` returns a `StateFlowTelegramInspection` containing state and matching revisions, plus an optional revocation signal checked immediately before presentation. Stop, selection changes and shutdown cancel obsolete reads without altering newer memory or clearing write fences. The existing synchronous `StateFlowTelegramPort` contract remains supported. A callback is acknowledged before waiting; late failures appear escaped in the existing menu, without a second answer to an expired query. 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).
290
296
 
291
297
  ## Validation boundaries
292
298
 
293
299
  Structural validation proves JSON shape, exact identity, causal lineage, compilation evidence, CAS and publication invariants. A valid state, receipt, source hash, or compiler revision cannot prove semantic importance, truth, sufficient compilation, correct scope, useful curation, or historical deletion. Those remain model-judgment concerns evaluated separately from deterministic transport checks.
294
300
 
295
- The deterministic continuity and temporal evidence map is in [temporal-acceptance.md](temporal-acceptance.md). Release-scoped open work is in [BACKLOG.md](../BACKLOG.md), and shipped outcomes belong in [CHANGELOG.md](../CHANGELOG.md).
301
+ The deterministic continuity and temporal evidence map is in [temporal-acceptance.md](temporal-acceptance.md). Release-scoped open work is in [BACKLOG.md](../BACKLOG.md), and shipped outcomes belong in [CHANGELOG.md](../CHANGELOG.md). The exact-tag [release workflow](../.github/workflows/release.yml) owns npm Trusted Publisher publication with provenance and creates a GitHub Release only after public-package verification. Keep `dist/` tracked and rebuild it from final sources and package metadata; Git tracking, source/build parity and npm `files` inventory are separate proofs. Never substitute a long-lived npm token. Native scripted-provider tests need a completion assertion outside the callback because Pi can turn an in-provider assertion failure into an assistant error. Await startup/tree fixture handlers, and in contention tests prove withdrawal while exclusion remains held before releasing storage and joining replacement selection.
@@ -2,9 +2,9 @@
2
2
 
3
3
  ## Supported Pi stack
4
4
 
5
- State Flow requires matching `pi-coding-agent`, `pi-agent-core`, `pi-ai`, and `pi-tui` packages at `>=0.87.0`. Keep all four on the same release line. The open-ended peer range permits newer SDK releases; it does not certify them.
5
+ State Flow requires matching `pi-coding-agent`, `pi-agent-core`, `pi-ai`, and `pi-tui` packages at `>=1.0.0`. Keep all four on the same release line. The open-ended peer range permits newer SDK releases; it does not certify them.
6
6
 
7
- The repository-local verified stack is Linux/x64, Node 26.8.1, Git 2.55.0 and Pi SDK 0.87.0. Repository validation covers tests, typecheck, build, compiled imports and package dry-run; successful results are bound to the validated source and dependency identities. The release workflow uses Node 24; its result is a separate verification gate.
7
+ The repository-local verified stack is Linux/x64, Node 26.8.1, Git 2.55.0 and matching Pi SDK 1.0.0 packages. Earlier source-bound measurements on Pi 0.87.0 remain historical evidence, not 1.0.0 performance results. Repository validation covers tests, typecheck, build, compiled imports and package dry-run; successful results are bound to the validated source and dependency identities. The release workflow uses Node 24; its result is a separate verification gate.
8
8
 
9
9
  Tests use isolated stores and scripted providers through the real Pi SDK. They do not certify installed Telegram/TUI reachability, live provider behavior, other operating systems, mixed SDK versions or untested newer SDK releases. Detailed behavioral witnesses live in [temporal acceptance](temporal-acceptance.md); benchmark methodology and source-bound results live in [performance](performance.md).
10
10
 
@@ -42,9 +42,9 @@ Operation signals are not universal. Idle commands and session events can lack t
42
42
 
43
43
  ## Mode configuration compatibility
44
44
 
45
- Global `config.json` accepts `mode: "active" | "passive" | "off"`, defaulting to Passive, solely as the initial policy for new sessions. Session `config.json` uses the same key for the concrete retained choice; commands and Telegram never edit the global default. Before semantic initialization, an inactive choice is retained in a native `{mode}` checkpoint instead.
45
+ Global `config.json` accepts `mode: "active" | "passive" | "off"`, defaulting to Off when no mode policy is configured, solely as the initial policy for new sessions. Session `config.json` uses the same key for the concrete retained choice; commands and Telegram never edit the global default. Before semantic initialization, an inactive choice is retained in a native `{mode}` checkpoint instead.
46
46
 
47
- Legacy decoding is read-only. Without explicit global mode, `autoStart: true` means Active; otherwise `passiveBootstrap: false` together with `passiveTools: false` means Off, and either enabled/defaulted flag means Passive. Explicit global mode overrides valid legacy flags; invalid values still fail validation. Session `enabled:true` remains Active, and `enabled:false` is non-active. Native legacy inactive checkpoints use the configured inactive fallback, never an Active default. Session config and native checkpoints reject mixed `mode`/`enabled` representations, even when apparently consistent, rather than choosing between two stored policies. Ordinary writers emit only mode; no eager migration or semantic normalization runs.
47
+ Legacy decoding is read-only. Without explicit global mode, the absence of all legacy mode flags means Off; `autoStart: true` means Active, while any present legacy mode flag retains its former mapping: `passiveBootstrap: false` together with `passiveTools: false` means Off, and otherwise the fallback is Passive. An operator who previously relied on an absent configuration for implicit Passive must now select Passive in that session or set global `mode: "passive"` for new sessions. Explicit global mode overrides valid legacy flags; invalid values still fail validation. Session `enabled:true` remains Active, and `enabled:false` is non-active. Native legacy inactive checkpoints use the configured inactive fallback, never an Active default. Session config and native checkpoints reject mixed `mode`/`enabled` representations, even when apparently consistent, rather than choosing between two stored policies. Ordinary writers emit only mode; no eager migration or semantic normalization runs.
48
48
 
49
49
  The extension SDK uses an optional `mode` default override, and both Telegram port variants use `snapshot.mode` plus `select(mode)`. Old callback keyboards may refresh the view without selecting a mode. Synchronous enum-based ports remain supported; this does not promise the removed Start/Stop port signatures.
50
50
 
@@ -29,9 +29,11 @@ Artifact provenance is current-only, not a historical registry. Any retained par
29
29
 
30
30
  `TemporalRuntime.withForkTransaction(source, checkpoint, action, signal?)` pins source identity/boundary before waiting and selects exact parent authority plus an unoccupied child under one awaited exclusion. The caller rechecks native selection/policy and publishes its child lifecycle synchronously once. Parent evidence is revalidated before publication, the child cohort is CAS-protected, and only accepted memory installs. Cancellation or rejection cannot initialize an empty child; post-acceptance failure cannot roll it back or authorize another parent copy. Existing child storage, identity mismatch, missing parent files, malformed storage, concurrency conflict, or an expired boundary fails closed.
31
31
 
32
- Native fork adoption and Start's exact-source retry use this transaction inside the extension's owned restoration lifetime; the synchronous `prepareBoundaryFork()` adapter remains supported for library consumers. Both paths publish the fresh child origin before any runtime-only lifecycle write. Native evidence holds a publisher across fork adoption; it does not certify idle native Abort.
32
+ An Off native fork defers parent-header acquisition and canonical copying. Only a child-owned pending-fork marker is appended to the native trace; it carries no semantic authority. The marker survives cold extension reload and permits later explicit Passive/Active acquisition of the still-selected exact parent boundary, subject to the same identity, retention and occupied-child checks. Accepted initialization resets the marker. Parent expiry while Off is diagnosed only on explicit acquisition, never silently replaced with newer parent memory.
33
33
 
34
- A failed or expired selection never substitutes the parent's current/newer private state and never falls through to an older disabled marker. In the same live extension instance, explicit Start may retry the unaccepted fork after missing identity or storage evidence is corrected. Passive/Off selection does not cancel an in-flight fork or its activation-owned retry: the latest requested inactive mode is applied inside the existing fork acceptance. Cancelling the Start waiter does not cancel that independently owned copy. After acceptance, Passive exposes both tools for child memory without active episode behavior, while Off exposes neither; ordinary cold reopening loads that child-owned state. Selection, shutdown, native Abort, invalid source evidence and expired history still can prevent acceptance. Cold recovery before the first child-owned checkpoint remains unsupported; missing child files never authorize a parent recopy. Once child storage has been accepted, explicit Start can activate its validated current child-owned memory even after selecting an inherited parent checkpoint; this neither restores parent history nor copies newer parent data. Child-owned checkpoints subsequently use ordinary retained-boundary reload/resume without rereading the parent header.
34
+ Memory-enabled native fork adoption and Start's exact-source retry use this transaction inside the extension's owned restoration lifetime; the synchronous `prepareBoundaryFork()` adapter remains supported for library consumers. Both paths publish the fresh child origin before any runtime-only lifecycle write. Native evidence holds a publisher across fork adoption; it does not certify idle native Abort.
35
+
36
+ A failed or expired selection never substitutes the parent's current/newer private state and never falls through to an older disabled marker. In the same live extension instance, explicit Start may retry the unaccepted fork after missing identity or storage evidence is corrected. Passive selection retains an in-flight fork or its activation-owned retry and applies Passive inside that existing acceptance. Off instead aborts the owned copy/retry before acceptance and records child-owned native Off/pending-fork policy without publishing memory; a later explicit Passive/Active request reacquires the exact source. Cancelling the Start waiter does not cancel that independently owned copy. After acceptance, Passive exposes both tools for child memory without active episode behavior, while Off exposes neither; ordinary memory-enabled cold reopening loads that child-owned state, while Off defers loading it. Off, selection, shutdown, native Abort, invalid source evidence and expired history still can prevent acceptance. Cold recovery before the first child-owned checkpoint remains unsupported without the explicit Off-deferred pending marker; missing child files alone never authorize a parent recopy. Once child storage has been accepted, explicit Start can activate its validated current child-owned memory even after selecting an inherited parent checkpoint; this neither restores parent history nor copies newer parent data. Child-owned checkpoints subsequently use ordinary retained-boundary reload/resume without rereading the parent header.
35
37
 
36
38
  A child-owned passive-projection reset prevents copied parent Stop markers from resurfacing after child reload. Inactive sources retain their selected mode, including a same-owner native failed-Stop policy that could not reach canonical config. A child inherits neither that parent's write fence nor its passive projection; source history must still be provable and copying must pass CAS. Ordinary activation policy is not overridden. Nested forks require each direct parent boundary to remain retained; ancestry is not recursively reconstructed.
37
39
 
@@ -23,7 +23,7 @@ This is a maintained property-to-test map for the current canonical-file contrac
23
23
  17. **Historical restoration is distinct from activation:** `tests/recovery.test.ts` rejects unavailable selections without older-pointer or disabled-marker fallback. Extension/native tests fence passive publication until explicit current-memory activation, with unchanged canonical bytes in both inactive modes. Native “real Pi activates current … memory after expired tree selection and reload” cases cover passive, active and interrupted work plus the next provider's private-memory input. Runtime current-head tests preserve semantics, provenance, revisions, step and available history across old modes, distinguish absent from incomplete private authority, adopt validated foreign shared streams without private leakage or invented history, and reject a concurrent private writer. Native pre-runtime and inherited-fork-selection witnesses preserve current owned session memory instead of resetting it or recopying a parent. Repeated active Start leaves response reconciliation intact. Ordinary conversation with only a pre-runtime mode checkpoint still bootstraps; unaccepted fork identity/CWD repair retries the exact source.
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 policy, 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 the current-head native witness accepts a shared write racing after inference and retains its actual accepted predecessor. 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 and explicit preservation of unfinished compilation. The native “real Pi repeated Start/Stop preserves uncompiled conversation and its prior boundary” cases cover initial/restarted bootstrap, repeated idle toggles, reload, unchanged native trace, and release after accepted compilation; extension tests cover interrupted idle Stop with and without a captured anchor. Completed idle/legacy cutoffs remain bounded. The extension's failed-Stop matrix covers concurrent private writers, invalid lock ownership and malformed runtime files in both inactive modes: the selected mode remains applied, canonical bytes stay unchanged, accepted memory and native conversation survive, and only Passive projects the handoff; reload is read-only, and writes remain fenced until accepted Start. Native “real Pi failed Stop stays passive through late tools, tree, reload and resume” cases verify provider inputs, rejected tool calls, untouched trace prefixes, private memory, current foreign writes, and recovery through explicit Start. A native fork witness retains disabled policy without inheriting the parent's fence. Session tests bind fence lifetime to owner/reset/accepted-checkpoint evidence; runtime current-head tests prove read-only loading changes no canonical bytes. `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. **Compact mode, inspectable revisions:** `tests/status.test.ts` proves Active/Passive terminal indicators omit revisions, Off alone hides the indicator, and `/state-flow-status` retains the effective `g#c#s#` vector with blank lines between top-level JSON planes. `tests/telegram.test.ts` verifies mode-only section labels, lowercase options with one selected marker, direct scope buttons, owner Rich headings with `#revision` and Effective with `g#c#s#`. Telegram can inspect existing shared memory even in Off without initializing or mutating storage. Failure-fenced inspection retains accepted cached memory without overwriting another writer.
26
+ 20. **Compact mode, inspectable revisions:** `tests/status.test.ts` proves Active/Passive terminal indicators omit revisions, Off alone hides the indicator, and `/state-flow-status` retains the effective `g#c#s#` vector with blank lines between top-level JSON planes. `tests/telegram.test.ts` verifies mode-only section labels, capitalized radio options with one mode-specific selected marker and ⚫️ inactive markers, direct scope buttons, owner Rich headings with `#revision` and Effective with `g#c#s#`. Telegram can inspect existing shared memory even in Off without initializing or mutating storage. Failure-fenced inspection retains accepted cached memory without overwriting another writer.
27
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.
28
28
  22. **Current-head atomic model publication:** `tests/runtime.test.ts` applies authored independent/overlapping assignments, deletion and arrays to current shared values, preserves another owner's private files, and derives the predecessor/revisions from that basis. Compilation witnesses replace complete cards with matching provenance, preserve untouched evidence, accept repeats and refuse orphaned evidence after semantic-pair disappearance. Partial/malformed shared evidence and concurrent/unselected private authority stay fenced. Fault injection rolls back a mixed publication without installing the candidate's shared adoption or private draft. Extension tests reject a first passive patch without publishing empty setup, and recheck acquired-source freshness after lock waiting. Native “real Pi awaits foreign publication” cases hold an independent process beyond the former wait budget, verify responsive waiting/cancellation with unchanged canonical bytes, and require the next provider to see accepted current Global/CWD plus its own Session, never the foreign private layer.
29
29
  23. **Awaited response acceptance owns its lifecycle:** `tests/extension.test.ts` verifies waiting against current shared memory, one accepted checkpoint without a second publication, rollback without candidate/cache or lifecycle installation, cancellation at Stop/session/tree/shutdown boundaries, shutdown fencing and superseding-answer isolation. Native “real Pi awaits response publication” witnesses wait behind an independent writer for over two seconds, then prove later boundary handlers and continuation inference see the accepted response, current Global/CWD and only their own Session. Native Abort withdraws the wait without changing canonical bytes, the prior response or unfinished specification, and without requesting a repair inference.
@@ -76,7 +76,7 @@ This is a maintained property-to-test map for the current canonical-file contrac
76
76
  - 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.
77
77
  - `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.
78
78
  - `tests/storage.test.ts` covers exact file-cohort references, file CAS/rollback, and shared writer exclusion. The asynchronous transaction witnesses pause an independent writer between tail and metadata renames for longer than the old wait budget: the waiting process remains responsive and captures the complete accepted receipt only after release. Local waiters, cancellation before acquisition/publication, interrupted/malformed/empty locks, root/lifetime binding, active recursive refusal, deferred work after context expiry, rollback and replaced-owner preservation are separately checked. The current-head and response witnesses above additionally prove awaited model patch/finalization integration; runtime startup/recovery and exact restoration/fork cutover, including Start's initial attachment and unaccepted-fork paths, are covered by items 35–40. Current-head Start and accepted-runtime Stop are covered above; optional settlement backup uses the selected no-signal deferral rather than an upstream release gate. `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.
79
- - `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 Passive; CWD materialization alone never grants Active mode.
79
+ - `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 Off without a configured mode; CWD materialization alone never grants Active mode.
80
80
 
81
81
  ## Validation and limits
82
82