@llblab/pi-kit 0.28.0 → 0.29.1

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

@@ -53,7 +53,7 @@ On the tested SDK, `before_agent_start` precedes the low-level agent's `prompt`;
 2. The active `context` hook supplies the operation signal and awaits preparation/maintenance before provider inference.
 3. If preparation fails, State Flow calls public `ctx.abort()`. Pi catches context-hook errors and may otherwise continue inference, so a thrown error alone is not a fence.
 
-Native tests prove no provider call before coherent acceptance, cancellation while an independent writer remains held, rollback without draft installation and preservation of uncompiled native input. Failed retained Active restoration also aborts live inference before the provider; native witnesses cover expired tree selection/reload and contradictory private lineage without changing canonical bytes. Explicit inactive policy releases that inference fence, not the write fence.
+Native tests prove no provider call before coherent acceptance, cancellation while an independent writer remains held, rollback without draft installation and preservation of uncompiled native input. Unreadable current Active memory also aborts live inference before the provider; native witnesses cover contradictory private lineage and malformed runtime files without changing canonical bytes, while old-step tree selection/reload is not a failure. Failed attachment retains Active policy and exposes `active (blocked)` in terminal/Telegram; the fence is derived from selected mode plus unavailable-memory validation. Active controls retry current-memory acceptance rather than claiming it is already active. Explicit Passive accepts validated current memory and releases both fences; explicit Off releases only the inference fence.
 
 **Signals are not universal.** Idle commands and session events can lack them. Do not infer native Abort cancellation from an extension-owned shutdown signal or generalize active-run tests to idle waits.
 
@@ -76,7 +76,7 @@ Native tests prove no provider call before coherent acceptance, cancellation whi
 
 To use Passive, select it in the current session or set global `mode: "passive"` for new sessions.
 
-**SDK and Telegram controls.** The extension SDK accepts an optional `mode` default override. Both Telegram port variants use `snapshot.mode` plus `select(mode)`. A stale callback keyboard may refresh the view without selecting a mode. Synchronous enum-based ports are supported; Start/Stop port signatures are not.
+**SDK and Telegram controls.** The extension SDK accepts an optional `mode` default override. Both Telegram port variants use `snapshot.mode` plus `select(mode)`. The optional additive `snapshot.inferenceBlocked` diagnostic marks failed Active restoration; legacy ports may omit it. A stale callback keyboard may refresh the view without selecting a mode. Synchronous enum-based ports are supported; Start/Stop port signatures are not.
 
 ## Mode selection and memory restoration
 
@@ -84,17 +84,17 @@ To use Passive, select it in the current session or set global `mode: "passive"`
 
 - Activates current same-session authority under awaited exclusion.
 - Rechecks physical identity and initialization permission after waiting, accepts once, then installs policy, memory and checkpoint.
-- Does not claim to restore an expired historical boundary.
+- Uses current memory; branch checkpoints never select a past revision.
 - Native tests prove current shared plus local-private memory at the next provider, and actual Abort withdrawal for in-run Start with an operation signal.
 
 **Passive:**
 
 - Selects local tools/context policy before waiting for persistence.
 - For accepted memory, publishes lifecycle metadata without rewriting semantic/provenance files. Pending inactive choices share one acceptance of the latest mode.
-- Keeps independently owned retained restoration, Active-default initialization and fork copying; the latest inactive policy is applied at acceptance.
+- Keeps independently owned current-memory attachment, Active-default initialization and fork copying; the latest inactive policy is applied at acceptance.
 - Read-only recovery preserves an intervening Passive choice and its write fence.
 - Selection, shutdown and accepted Start cancel obsolete Stop persistence; rejected Start does not.
-- Genuine persistence failure retains readable memory and native context while fencing writes until accepted Start.
+- Genuine persistence failure retains readable memory and native context while fencing writes until accepted Start or a later explicit Passive that successfully accepts current memory. A Passive retry that still fails adds no duplicate fence marker.
 
 **Off:**
 
@@ -104,7 +104,7 @@ To use Passive, select it in the current session or set global `mode: "passive"`
 
 Modes select workflow policy, not whether canonical memory exists. Cancelling a Start waiter does not cancel independently owned restoration. Selection changes, shutdown and an available native operation signal can revoke obsolete restoration; failure after acceptance cannot undo memory.
 
-**Native restoration evidence.** Startup and tree handlers await restoration. Tests cover held-store tree/fork selection, exact private state over live shared streams, unchanged parent-private files, cold reopening, failed-Stop recovery and next-provider input without later-branch private values.
+**Native attachment evidence.** Startup and tree handlers await attachment. Tests cover held-store tree/fork selection, current private state over live shared streams after old-step navigation, fork copies of the parent's current memory, unchanged parent-private files, cold reopening, failed-Stop recovery and next-provider input with current private values.
 
 A public SDK host can observe the child factory result before awaiting extension binding and send Stop or Stop→Start through the child's public `prompt` method while copying waits. This proves that embedding route, not that the installed CLI or Telegram exposes the child before runtime replacement finishes.
 
@@ -153,8 +153,7 @@ The package root exports `TemporalRuntime`. The Pi registration shim is a separa
 - **Authored semantic patch — `withPatchTransaction`:** current shared basis and selected private authority; one atomic acceptance.
 - **Accepted-runtime lifecycle — `withLifecycleTransaction`:** config/runtime only; cannot initialize or repair semantic storage.
 - **Current-head activation — `withStartTransaction`:** origin creation defaults off and requires explicit authorization.
-- **Retained restoration — `withRestoreTransaction`:** exact retained private boundary beside current shared streams.
-- **Child creation — `withForkTransaction`:** exact parent authority and an unoccupied independent child.
+- **Child creation — `withForkTransaction(source, lifecycle, …)`:** the parent's current memory copied into an unoccupied independent child; `lifecycle` supplies only mode/bootstrap.
 
 Await completion before consuming results. Transaction callbacks:
 
@@ -166,7 +165,7 @@ Keep inference, source acquisition and Git outside canonical exclusion. Raw prec
 
 Continuation inspection/candidate building and Git backup also return Promises. Await them rather than treating a Promise as a boolean or accessing a result before completion. Continuation inspection is advisory: it cannot initialize, restore or select a session on the host's behalf.
 
-**Synchronous runtime methods:** `loadPassive`, `prepareBoundaryRestore`, `restoreBoundary`, `acceptRestoredOrigin`, `prepareBoundaryFork` and `initialize`.
+**Synchronous runtime methods:** `loadPassive` and `initialize`. Version 0.26.0 removed the boundary-restoration APIs (`withRestoreTransaction`, `prepareBoundaryRestore`, `restoreBoundary`, `acceptRestoredOrigin`, `prepareBoundaryFork`) and `HistoryBoundaryExpiredError`; memory never rewinds to an older boundary.
 
 - They are supported for library consumers and local tests/benchmarks; production lifecycle wiring uses the awaited APIs.
 - They are not signature-compatible substitutes and do not acquire the awaited APIs' cancellation behavior.

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

@@ -21,9 +21,9 @@ State Flow classifies absence separately from partial or malformed evidence. Rec
 ### Session `checkpoint.json` + `patches.jsonl`
 
 - **Authority:** State Flow; authoritative private semantics.
-- **Wholly absent:** Fresh lifecycle origin may initialize; an existing selected session requires exact retained authority.
+- **Wholly absent:** Fresh lifecycle origin may initialize; an existing session with a checkpoint requires its current files.
 - **Partial or malformed:** Partial or malformed pair fails closed.
-- **Allowed repair and writes:** Fresh initialization or exact retained-boundary recovery only.
+- **Allowed repair and writes:** Fresh initialization or acceptance of validated current memory only.
 
 ### Global/CWD `meta.json`
 
@@ -91,8 +91,8 @@ State Flow classifies absence separately from partial or malformed evidence. Rec
 ### Pi State Flow entries
 
 - **Authority:** Pi session log / State Flow entry owner.
-- **Wholly absent:** Missing required selected boundary blocks that restore.
-- **Partial or malformed:** Malformed or contradictory owner/version/boundary fails the dependent restore.
+- **Wholly absent:** No checkpoint means no recorded branch mode; memory is not affected.
+- **Partial or malformed:** Malformed or unsupported envelopes are skipped or fail the dependent mode selection; a checkpoint boundary is never a memory revision to restore.
 - **Allowed repair and writes:** Append through Pi entry APIs only; never replace failed selection with passive state.
 
 ### Optional diagnostic log

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

@@ -1,23 +1,23 @@
-# Physical fork: retained session-stream copy
+# Physical fork: current session-memory copy
 
 [Usage](usage.md#fork-support-and-limits) owns operation and recovery; [BACKLOG.md](../BACKLOG.md) owns release tracking.
 
 ## Contract
 
-A physical Pi fork creates a fresh child session from a retained boundary in its direct parent's canonical session lineage:
+A physical Pi fork creates a fresh child session from its direct parent's **current** canonical session memory. State Flow does not depend on the Pi step the fork starts from:
 
 ```text
 child.global  = current live global
 child.cwd     = current live CWD
-child.session = parent session selected at retained boundary
+child.session = parent session current head
 ```
 
-The adapter reads Pi's persisted direct-parent header, requires matching CWD and session identity, and selects the boundary only if it remains in the parent's retained canonical lineage. It never consults Git, a storage receipt, an older checkpoint entry, or the parent's newer private state.
+The adapter reads Pi's persisted direct-parent header, requires matching CWD and session identity, reads the parent's current memory and uses its head as the copied boundary. It never consults Git, a storage receipt or an older checkpoint revision.
 
 The child receives:
 
 - its own UUID, native session key, runtime metadata, and fresh lineage origin;
-- the selected parent session materialization and matching artifact provenance;
+- the parent's current session materialization and matching artifact provenance;
 - current live global/CWD values and provenance without rewinding them;
 - selected `mode` and bootstrap lifecycle state, with step reset to zero and no inherited unfinished specification or validation diagnostic.
 
@@ -27,47 +27,42 @@ The child receives:
 - Applying a smaller configured `historyLimit` may fold excess shared tails during child acceptance under file-cohort CAS, without changing current shared materialization or provenance. Without retention reduction, the shared files remain unchanged too.
 - Forking semantic memory does not clone or roll back project files or tool effects.
 
-**Artifact evidence is current-only, not a historical registry.**
-
-- Any retained parent session patch touching an artifact after the selected boundary makes its current provenance unproven for that selection, even if a later patch restores an equal value.
-- The child keeps the selected artifact semantics but omits that provenance until explicit reacquisition and compilation.
-- Untouched artifact paths retain their evidence, including provenance-only refreshes of unchanged semantics; shared provenance remains live.
+**Artifact evidence is current-only, not a historical registry.** Because the child copies the parent's current head, current artifact semantics and their current provenance stay together; shared provenance remains live.
 
 ## Lifecycle and failure
 
-**Copying and acceptance.** `TemporalRuntime.withForkTransaction(source, checkpoint, action, signal?)`:
+**Copying and acceptance.** `TemporalRuntime.withForkTransaction(source, lifecycle, action, signal?)`:
 
-1. Pins source identity/boundary before waiting.
+1. Pins source identity and the parent's current head boundary before waiting.
 2. Selects exact parent authority plus an unoccupied child under one awaited exclusion.
 3. Lets the caller recheck native selection/policy and publish its child lifecycle synchronously, once.
 4. Revalidates parent evidence before publication and protects the child cohort with CAS. Only accepted memory installs.
 
-Cancellation or rejection cannot initialize an empty child. Failure after acceptance cannot roll it back or authorize another parent copy. Existing child storage, an identity mismatch, missing parent files, malformed storage, a concurrency conflict or an expired boundary fails closed.
+Cancellation or rejection cannot initialize an empty child. Failure after acceptance cannot roll it back or authorize another parent copy. Existing child storage, an identity mismatch, missing parent files, malformed storage or a concurrency conflict fails closed.
 
 **Forking while Off:**
 
 - Parent-header acquisition and canonical copying are deferred. 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.
+- The marker survives cold extension reload and permits later explicit Passive/Active acquisition, which copies the parent's then-current memory subject to the same identity 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.
 
-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.
+Memory-enabled native fork adoption and Start's fork retry use this transaction inside the extension's owned restoration lifetime. It publishes 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.
 
 **Retry and cancellation:**
 
-- A failed or expired selection never substitutes the parent's current/newer private state and never falls through to an older disabled marker.
+- A failed copy never substitutes empty or foreign memory 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 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.
+- Off 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 copies the parent's current memory.
 - Cancelling the Start waiter does not cancel that independently owned copy.
-- Off, selection, shutdown, native Abort, invalid source evidence and expired history can prevent acceptance.
+- Off, selection, shutdown, native Abort and invalid source evidence can prevent acceptance.
 
 **After acceptance:**
 
 - Passive exposes both tools for child memory without active episode behavior; Off exposes neither.
 - Ordinary memory-enabled cold reopening loads that child-owned state; Off defers loading it.
-- Explicit Start can activate 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 use ordinary retained-boundary reload/resume without rereading the parent header.
+- Navigating to an inherited parent step keeps current child-owned memory; it neither rewinds nor recopies parent data.
+- Child-owned checkpoints use ordinary current-memory reload/resume without rereading the parent header.
 
 **Before the first child-owned checkpoint:** cold recovery requires the explicit Off-deferred pending marker. Missing child files alone never authorize a parent recopy.
 
@@ -75,8 +70,8 @@ Memory-enabled native fork adoption and Start's exact-source retry use this tran
 
 - 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 its 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.
+- A child inherits neither its parent's write fence nor its passive projection. Parent current memory must be valid, and copying must pass CAS; ordinary activation policy is not overridden.
+- Nested forks copy each direct parent's current memory. Ancestry is not recursively reconstructed.
 
 ## Support boundary
 

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

@@ -75,19 +75,19 @@ This is a maintained property-to-test map for the current canonical-file contrac
 - `tests/temporal.test.ts` verifies hot-range and unavailable pre-origin boundaries; the real-Pi history-reader test rejects offset eight at the default limit seven without a transition.
 - `tests/config.test.ts` exercises materialized and scope patch-history paths at limits 0, 1, 7, and 12, including single-path/one-item batch reads above seven and distinct configured versus actually retained boundaries.
 
-### 17. Historical restoration is distinct from activation
+### 17. Memory never depends on the Pi step
 
-- `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.
+- `tests/recovery.test.ts` rejects unsupported checkpoint envelopes without older-pointer or disabled-marker fallback.
+- Extension/native tests prove old-step tree navigation, reload and resume keep current memory writable in Active and Passive; unreadable current files block Active visibly, Passive retries acceptance and Off releases inference only, with unchanged canonical bytes.
+- Native “real Pi keeps current … memory after old-step 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.
+- Ordinary conversation with only a pre-runtime mode checkpoint still bootstraps; unaccepted fork identity/CWD repair retries copying the parent's current memory.
 
-### 18. Tree/resume select the correct lineage
+### 18. Tree/resume restore branch mode over current memory
 
-- `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”.
+- `tests/integration.test.ts` — “real Pi branch navigation through compaction restores branch modes over current memory” and “real Pi old tree branch stop and resume keep current semantics without rewinding any files”.
 
 ### 19. Stop changes policy, not semantic history
 
@@ -99,7 +99,7 @@ This is a maintained property-to-test map for the current canonical-file contrac
 - 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 and marker-based 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.
+- 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 or a successful explicit Passive retry; failed retries add no duplicate fence.
 - 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.
@@ -193,20 +193,18 @@ This is a maintained property-to-test map for the current canonical-file contrac
 - Native “real Pi Abort cancels an in-run Start without waiting for the canonical owner or another provider call” uses the actual command and active operation signal: cancellation returns while the store remains held, without changed files/checkpoints, another provider call or late activation.
 - Idle/no-signal waits and the separate initial-attachment/fork recovery paths are not certified by that Abort witness.
 
-### 31. Awaited retained restoration selects and accepts one coherent cohort
+### 31. Branch attachment accepts one coherent current cohort
 
-- Runtime restore matrices cover limits 0/1/12, historical/head artifact provenance and contradictory lineage.
-- An independent partial publisher holds exclusion for over two seconds: cancellation preserves cache/files, successful restoration retains historical local Session over current shared values, and all five foreign-private files remain unchanged.
-- Pointer mutation after admission cannot retarget selection; lifecycle policy is checked after waiting.
-- Further witnesses cover expiry during the wait, missing/malformed/foreign authority, private checkpoint/runtime CAS races, rollback/retry, expired/single-use capabilities and post-acceptance failure.
-- No current-head/empty fallback, invented history or unaccepted cache installation is permitted.
+- Attachment uses the current-head Start transaction, whose witnesses cover foreign shared adoption, incomplete private storage, noncooperating private replacement, single-use acceptance and preserved cohorts on publication failure.
+- Runtime attach/fork cases reject contradictory session lineage without installing a cache or changing files.
+- No empty fallback, invented history or unaccepted cache installation is permitted; there is no boundary-restoration API.
 - Native caller cutover evidence is item 35.
 
-### 32. Awaited exact-source fork preserves parent and child authority
+### 32. Awaited fork copies current parent memory and preserves parent and child authority
 
-- Runtime restore/fork matrices cover limits 0/1/12, provenance and contradictory lineage.
-- An independent partial writer held over two seconds proves responsive cancellation, pinned source identity/checkpoint, current shared adoption and historical private copying without parent/foreign-private changes.
-- Source expiry during waiting and competing child acceptances prove post-wait checks.
+- Runtime fork cases cover limits 0/1/12 from an old step, current artifact provenance and contradictory lineage.
+- An independent partial writer held over two seconds proves responsive cancellation, pinned source identity/checkpoint, current shared adoption and private copying without parent/foreign-private changes. The extension pins the parent's current head, so native fork copies never depend on the fork step.
+- Competing child acceptances prove post-wait checks.
 - Every occupied child file, unsupported storage evidence, invalid/missing parent authority and parent/child byte races refuse publication.
 - Fault injection proves rollback/retry; expired/single-use capabilities and post-acceptance checkpoint failure cannot replace accepted child memory.
 - Child lifecycle resets step and unfinished specification while retaining selected mode/bootstrap; later child writes leave the parent unchanged.
@@ -304,7 +302,7 @@ This is a maintained property-to-test map for the current canonical-file contrac
 - `tests/config.test.ts` and `tests/snapshot.test.ts` cover enum round trips, read-only compatibility decoding, invalid/mixed session policies and pre-runtime mode retention without semantic initialization.
 - Native global-default tests prove later defaults affect only new sessions.
 - Extension inactive-choice matrices prove coalescing, no semantic revision and last-choice wins.
-- Held-store “fenced reload preserves …” cases cover all four inactive pairs, unchanged canonical bytes, retained write fences, immediate/final tools/context/status and a subsequent reload.
+- Held-store “fenced reload preserves …” cases cover Off with unchanged canonical bytes and retained fence, and Passive joining read-only recovery before accepting current memory and staying writable across reload.
 - Telegram “pre-runtime Telegram Passive reports only its current successful selection” proves truthful success after cache installation and suppression of superseded receipts through the real composition port.
 
 
@@ -401,9 +399,9 @@ This is a maintained property-to-test map for the current canonical-file contrac
   - 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.
-- `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/runtime.test.ts` covers fork after lowering `historyLimit` to 0/1; native integration proves reload keeps current state and exactly the retained window, parent-private fork files remain unchanged, 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.
+  - Session tests and native Pi distinguish configured new-session auto-start from branch-mode resume/tree/stop over current memory.
   - `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.
 

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

@@ -35,7 +35,7 @@ Each `patch_state` is an inference barrier, not automatically the end of an iter
 
 Native compaction is separate from model-context projection; its safety checks and usage threshold still apply.
 
-Active, Passive and Off select the session's workflow and model-facing access, not a different storage algorithm. Native Off attachment defers memory acquisition, including creation of a fork's private memory, until Passive or Active is explicitly selected. Once acquired, a fork owns Session state copied from the selected parent boundary and lives independently in its selected mode. See [fork support](#fork-support-and-limits).
+Active, Passive and Off select the session's workflow and model-facing access, not a different storage algorithm. Native Off attachment defers memory acquisition, including creation of a fork's private memory, until Passive or Active is explicitly selected. Once acquired, a fork owns Session state copied from the parent's current memory and lives independently in its selected mode. See [fork support](#fork-support-and-limits).
 
 ### Lifecycle operations
 
@@ -44,8 +44,8 @@ Active, Passive and Off select the session's workflow and model-facing access, n
 - Starting mid-conversation keeps Pi's active context for one complete bootstrap run, during which the agent must compile future-relevant information into state.
 - Repeating Active while already active leaves the in-progress run unchanged.
 - On an attached branch, activation waits asynchronously for a coherent canonical cohort; pending repeats share the wait.
-- Until acceptance, the existing inactive mode, deferred historical selection and any write fence stay in effect.
-- Cancelling a pending Active from Off preserves later acquisition choices. A superseding Passive still selects its retained private boundary rather than newer current memory, and ordinary cancellation creates no write fence.
+- Until acceptance, the existing inactive mode and any write fence stay in effect.
+- Cancelling a pending Active from Off preserves later acquisition choices; ordinary cancellation creates no write fence.
 - Passive, Off or a branch selection can withdraw an obsolete activation. An error after acceptance does not undo accepted memory.
 
 How each lifecycle event behaves:
@@ -54,9 +54,10 @@ How each lifecycle event behaves:
   - An inactive default is recorded once in Pi as `{mode:"off"}` or `{mode:"passive"}`, without creating semantic storage.
   - An Active default initializes a distinct empty Session layer over global/CWD memory, never another session's private continuation.
 - **Resume:** Keeps the selected session's mode; later global default changes do not override it.
-  - Passive/Active restore state and lineage.
+  - Passive/Active attach the current same-session memory and its retained history.
   - Off attaches native policy only, without probing semantic files or emitting recovery warnings.
-- **Tree navigation:** In Passive/Active, restores the selected retained private boundary over live shared scopes, without checking out or resetting the shared store. Off defers this acquisition until a mode is explicitly selected.
+- **Tree navigation:** Restores the selected branch's mode, but never rewinds memory: State Flow does not depend on the Pi step. Passive/Active keep the current JSON state of every scope, which changes only through accepted patches. Off defers acquisition until a mode is explicitly selected.
+- **Fork:** The child copies its parent's current memory into its own session layer, independent of the step it forked from.
 - **Abort inference:** Stops generation or an outstanding response-publication wait. Already accepted patches stay durable, so work and corrected direction can continue in the same session.
   - Cancellation before response acceptance keeps the previous response and the unfinished run.
   - Cancellation after acceptance never rolls it back.
@@ -75,7 +76,7 @@ How each lifecycle event behaves:
   - The selected Passive policy stays applied. Accepted memory and the native conversation stay intact.
   - Pi records the selected mode and a write fence, not a replacement semantic checkpoint. This needs a writable Pi trace and never repairs storage; native fenced policy overrides an older canonical config.
   - Tree/reload/resume in Passive read validated current same-session memory without publishing or restoring an older selection.
-  - Off keeps the native policy and the write fence without reading memory, and still exposes no State Flow context or tools; explicit Passive may acquire that read-only current authority later.
+  - Off keeps the native policy and the write fence without reading memory, and still exposes no State Flow context or tools. A later explicit Passive retries current-memory acceptance; success clears the fence.
   - Newer mode choices survive an in-flight read-only recovery. Repeating the same choice is inert; changing the inactive mode updates only native policy and keeps the fence.
   - Explicit Active clears the fence only after canonical acceptance.
 - **Continue in Passive after Active:** The same physical session projects a frozen state handoff, any interrupted current request and tool trajectory (including late results), and the conversation after Stop. Which earlier conversation is kept:
@@ -101,11 +102,10 @@ State Flow does not undo tool effects. After an interruption or a return to an o
 
 ### Fork support and limits
 
-**What a fork copies.** Memory-enabled native fork replacement copies the source session checkpoint, retained patch tail and matching provenance into the new session's own storage.
+**What a fork copies.** Memory-enabled native fork replacement copies the parent's **current** session checkpoint, retained patch tail and matching provenance into the new session's own storage, independent of the Pi step it forked from.
 
 - Off records only a child-owned pending-fork policy. Header/store reads and copying wait until an explicit Passive/Active, including after a cold reload.
 - Global/CWD values and provenance stay current. Applying a smaller `historyLimit` may fold shared tails under CAS.
-- An earlier fork selection copies that point's private state, not the parent's later private work.
 - Parent-private data and history stay intact. The selected mode is kept, so an inactive source does not become Active automatically.
 
 **The child's own history.** The child starts at step zero with a new temporal origin.
@@ -114,11 +114,11 @@ State Flow does not undo tool effects. After an interruption or a return to an o
 - The child's own transitions build its hot window, and owned checkpoints support normal reload/resume.
 - Parent Stop projection is not inherited, including after a child reload.
 
-**Requirements for the initial copy:** a native fork start event, a regular canonical direct-parent session file, matching CWD/identity, a readable temporal source and an unused child namespace. Missing or unsafe evidence or a CAS conflict leaves the copy unavailable rather than importing unrelated or newer private state. Explicit Start can retry an unaccepted copy in the same loaded fork once the cause is corrected.
+**Requirements for the initial copy:** a native fork start event, a regular canonical direct-parent session file, matching CWD/identity, a readable temporal source and an unused child namespace. Missing or unsafe evidence or a CAS conflict leaves the copy unavailable rather than importing unrelated private state. Explicit Start can retry an unaccepted copy in the same loaded fork once the cause is corrected.
 
 **Limits:**
 
-- Selecting a copied parent checkpoint through the child's `/tree` does not make it child-owned: historical restoration stays disabled without resetting existing child data. Instead, select a child-owned checkpoint, resume the original session, or explicitly Start from the validated current child-owned memory. Start does not copy newer parent data.
+- Selecting a copied parent step through the child's `/tree` keeps current child-owned memory; it neither rewinds nor recopies parent data.
 - Cold recovery before the first child checkpoint requires an Off-deferred pending-fork marker. Otherwise, it and startup paths lacking the fork event remain unsupported.
 - In-memory parent locators and cross-CWD imports remain unsupported.
 - File-only copying requires an exact still-available source cohort.
@@ -144,7 +144,7 @@ The canonical store is `state-flow/` beneath the agent directory. Keeping config
   - Active initializes missing storage when safe.
   - Passive reads existing memory without publishing; its first explicit patch may initialize absent storage without starting an episode or compaction.
   - Off exposes neither memory tools nor State Flow context.
-- `logging`: Defaults to `false`. When enabled, rejected patch executions, active barrier blocks, preparation failures and accepted-answer reconciliation failures are recorded locally at `tmp/state-flow/logs.jsonl` beneath the agent directory. Asynchronous Git push failures are recorded there even when this setting is off.
+- `logging`: Defaults to `false`. When enabled, rejected patch executions, active barrier blocks, preparation failures and accepted-answer reconciliation failures are recorded locally at `tmp/pi-state-flow/logs.jsonl` beneath the agent directory. Older `tmp/state-flow` logs are left untouched and are not migrated. Asynchronous Git push failures are recorded there even when this setting is off.
 - `showSuccessfulPatches`: Defaults to `true`. In interactive Pi, `patch_state` rows show pretty-printed JSON arguments once in the call, with blank lines between adjacent memory sections; the result shows the acceptance or no-op acknowledgement, never a second patch. Set it to `false` to hide call arguments and keep the compact acknowledgement. Rejected calls retain their arguments and error acknowledgement; State Flow adds no private validation turn.
 - `historyLimit`: Defaults to `7` and accepts integers from `0` through `100`. It counts accepted semantic transitions, **not elapsed time or conversation length**, and bounds materialized-history and scope patch-history offsets.
   - Lowering it on reload/restore/fork folds excess tails forward without losing current state; selected boundaries outside the new window become unavailable.
@@ -194,21 +194,21 @@ Treat logs and state files as private. Removing a secret from current state does
 - A `Scope memory:` block with one line per scope that has content: the UTF-8 byte size of each present nonempty plane and, when `working` or `lazy` has top-level entries, the share owned by an open intent of that scope (for example `- cwd: intents 137 B, working 32 B; intent-owned working 1/2`). It is operator-only: no notice, threshold or model-facing effect.
 - One JSON representation of effective global → CWD → session memory, with a blank line between top-level semantic planes. Nested JSON is unchanged; individual scope JSON remains available through `read_state`.
 
-Status omits the already-visible mode and generic ownership/configuration prose. 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.
+Status reports the selected mode and any Active restoration inference fence, while omitting generic ownership/configuration prose. 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.
 
 **Revisions and indicators:**
 
-- The terminal indicator is accent `state-flow` plus dim `active` or `passive`; Off hides it.
+- The terminal indicator is accent `state-flow` plus dim `active` or `passive`; Off hides it. Failed Active restoration stays visible as `active (blocked)`, never as an apparently inactive 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. It uses the compact lowercase `g#c#s#` revision vector (for example, `g15c8s31`), with no slashes or spaces between counters. The vector appears in `/state-flow-status` and in Telegram's Effective inspection, not in the compact indicators.
 
 ### Telegram controls
 
-When `pi-telegram` is available, its main-menu section shows `State Flow: active`, `State Flow: passive` or `State Flow: off`. The adapter is optional; the Pi commands work without it. All Telegram controls use the same lifecycle owners as the terminal commands.
+When `pi-telegram` is available, its main-menu section shows `State Flow: active`, `State Flow: passive` or `State Flow: off`. Failed Active restoration shows `State Flow: active (blocked)` and recovery guidance in the submenu; the Active control can retry current-memory acceptance. The adapter is optional; the Pi commands work without it. All Telegram controls use the same lifecycle owners as the terminal commands.
 
 **Mode controls:**
 
-- A horizontal radio row presents `Off | Passive | Active`. The selected option uses 🟡, 🟣 or 🟢 respectively; each inactive option uses ⚫️.
+- A horizontal radio row presents `Off | Passive | Active`. The selected option uses 🟣, 🟡 or 🟢 respectively; each inactive option uses ⚫️.
 - Telegram Active requested during a run waits for settlement; Passive and Off apply immediately.
 - Ordinary successful controls add no redundant mode receipt; diagnostic outcomes stay visible.
 - Off exposes neither tool nor State Flow model context.
@@ -234,9 +234,8 @@ When `pi-telegram` is available, its main-menu section shows `State Flow: active
 **Inspecting while Off.** Explicit Off inspection reads current stored memory through a disposable reader.
 
 - Session and Effective require validated same-session private authority and cannot show a fabricated empty layer or revision. Shared Global/CWD inspection stays available independently of private failures.
-- These reads install no model/runtime cache, change no bytes or mode, clear no write fence, and leave the selected historical/fork boundary intact for a future Passive/Active acquisition.
+- These reads install no model/runtime cache, change no bytes or mode, clear no write fence, and leave pending fork acquisition intact for a future Passive/Active selection.
 - Automatic Off callbacks never acquire memory.
-- Current stored data does not prove that a selected past boundary is restorable.
 
 Open implementation work is tracked in [BACKLOG.md](../BACKLOG.md).
 
@@ -277,25 +276,25 @@ See the [storage contract](architecture.md#storage-and-identity) for the exact l
 - semantic/metadata boundary mismatches and identity contradictions;
 - partial session runtime evidence.
 
-A missing or expired private retained boundary is unavailable; State Flow does not substitute Git history or newer private files.
+Memory never depends on the Pi step, so an old or expired branch checkpoint is not a failure: attachment always uses the current same-session files. State Flow does not substitute Git history, empty memory or another session's files.
 
-**After a selected-boundary failure:**
+**When current session memory is unreadable** (missing, corrupt, partial or contradictory files):
 
-- If the selected Active boundary cannot be restored, live inference is aborted before the provider instead of silently sending native history under an inactive fallback. Reload/resume retains this fence. Select a valid branch or explicitly Start from current same-session memory; explicit Passive/Off permits native context without repairing historical authority. Signal-less inspection remains observational.
-- Passive may still expose current global/CWD memory, but never the unavailable historical session layer or permission to publish an empty replacement.
-- Historical session reads and every `patch_state` refuse without changing canonical files or appending substitute checkpoints.
-- Passive/Off selection stays available and records the native policy/write fence described above. A later reload may expose validated current memory read-only, not the unavailable selected history.
+- Under Active, the selected mode remains Active and the indicator shows `active (blocked)`. Live inference is aborted before the provider instead of silently sending native history under an inactive fallback. Reload/resume retains this fence. Repair the files and choose Active/Passive; explicit Off permits native context without reading memory. Signal-less inspection remains observational.
+- Global/CWD memory stays readable; the unavailable session layer is never replaced by an empty one.
+- Session reads and every `patch_state` refuse without changing canonical files or appending substitute checkpoints.
+- **Modes are stable.** Explicit Passive accepts validated current same-session memory exactly like Active, keeping Passive policy. Only while current memory is still unreadable or unpublishable does Passive keep native inference with paused writes and report the cause. Off records native policy only.
 - Status distinguishes a write fence from unavailable materialization.
 
-**Explicit Start uses current memory, not unavailable history.**
+**Explicit Start uses current memory.**
 
 - It independently validates the current same-session canonical cohort, preserving private memory, artifact provenance, revisions, step and available aligned history.
 - Expired active/passive pointers and unfinished runtime work do not block activation. A pre-runtime selection also keeps current accepted same-session memory instead of resetting it.
 - Start bootstraps the conversation available on the selected Pi branch, without resurrecting an old unfinished specification or claiming that expired historical private state was restored.
 - Independently advanced shared scopes may require a new temporal origin; unavailable history is never invented.
 - Exact-cohort CAS rejects a concurrent writer, and incomplete or corrupt storage stays untouched.
-- An unaccepted native fork still retries its exact source rather than inventing child memory.
-- When evidence is missing, repair it, select a retained boundary, or open a genuinely new Pi session.
+- An unaccepted native fork retries copying its parent's current memory rather than inventing child memory.
+- When evidence is missing, repair it or open a genuinely new Pi session.
 
 **Artifact evidence and replication:**
 
@@ -307,7 +306,7 @@ See the complete [filesystem recovery contract](filesystem-recovery.md).
 
 ### Canonical files and optional Git backup
 
-Canonical scope/runtime files own the current materialization and retained hot history, whether or not Git is available. Pi checkpoints identify a retained semantic boundary, not a Git commit or an arbitrary historical snapshot. Restart and branch restoration fail closed when the selected boundary has expired, rather than substituting newer files as the selected past.
+Canonical scope/runtime files own the current materialization and retained hot history, whether or not Git is available. Pi checkpoints record mode and run lifecycle for a branch, not a Git commit or a memory revision to rewind to. Restart and branch navigation always attach the current files; historical states remain available only through explicit `read_state` offsets within retained history.
 
 **Local backup commit:**