@llblab/pi-kit 0.22.1 → 0.23.0

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

@@ -18,17 +18,36 @@ This is a maintained property-to-test map for the current canonical-file contrac
 12. **Next inference sees new current state:** The same real-Pi test inspects actual model-input projections after session, CWD, and global barriers. “real Pi reads prior scoped state lazily after a barrier and rejects path offset eight without a transition” adds model-tool access to the predecessor.
 13. **No automatic old full-state duplication:** `tests/context.test.ts` — “projects only the latest seven compact accepted transitions” rejects full-state records in transition context. The real-Pi barrier test requires exactly one current runtime projection per inference. Explicitly requested history remains ordinary tool-result trajectory, not eager snapshot injection.
 14. **Accepted response changes are transitions:** `tests/extension.test.ts` verifies that an ordinary accepted answer becomes runtime-owned `response` without a finalization patch or fallback inference, and “an empty accepted answer finalizes the run and stores an empty response” proves `""` is accepted after an earlier barrier. `tests/transition.test.ts` proves the empty value is an ordinary Session-owned semantic change when it replaces prior text.
-15. **No-op mutation signals are rejected:** “accepts only canonical materially changing atomic scope patches” rejects empty scope patches and obsolete finalization-shaped calls, while a changed accepted response remains a runtime-owned transition.
+15. **Correct repeats succeed without semantic changes:** “accepts canonical atomic scope patches and correct repeats without another checkpoint” preserves canonical bytes and native checkpoint count on repetition, while still rejecting empty supplied scopes and obsolete finalization-shaped calls. Runtime current-head witnesses preserve revisions, lineage and step across identical patches and compilations; a changed accepted response remains a runtime-owned transition.
 16. **Configured hot-history bounds:** `tests/temporal.test.ts` verifies hot-range and unavailable pre-origin boundaries; the real-Pi history-reader test rejects offset eight at the default limit seven without a transition. `tests/config.test.ts` exercises materialized and scope patch-history paths at limits 0, 1, 7, and 12, including single-path/one-item batch reads above seven and distinct configured versus actually retained boundaries.
-17. **Selected history fails closed:** `tests/recovery.test.ts` proves every failure resolving a selected retained boundary refuses without falling through to older boundaries or disabled markers. `tests/extension.test.ts` covers all passive bootstrap/tool combinations; the native “real Pi expired selection cannot reset private state through passive Start, Stop, patch, or reload” witness preserves exact canonical bytes and Pi checkpoints while allowing shared reads. Fork identity/CWD repair witnesses retry the original source with passive access both enabled and disabled.
+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 and all passive-policy combinations. 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. Checkpoint-free ordinary conversation still bootstraps; unaccepted fork identity/CWD repair retries the exact source.
 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”.
-19. **Stop changes config, not semantic history:** `tests/runtime.test.ts` lifecycle-only witnesses use a separate process to advance global/CWD semantics or provenance, including wider foreign retention, then prove exact semantic/sidecar preservation, unchanged steps, idempotent Stop, and same-session/stale-evidence refusal. Native Stop/new-request witnesses verify the accepted shared view reaches handoff/inference without a lifecycle semantic write, while a shared write racing after inference still fails closed. Mid-tool Stop tests preserve ordinary/bootstrap trajectories through tree, reload, resume, and restart. The native “real Pi retains a native split-turn continuation through late tools” Stop/no-Stop controls actually remove the original user with native threshold compaction, then require summary, paired reads and foreign context in model input. The Stop case also checks frozen semantics/step, unchanged trace prefix, tree/reload/cold resume/bootstrap restart, no resurrection of discarded input, and persistent foreign context after the next active run. Pure passive-selector tests cover missing, colliding and nonfinite recorded active anchors without changing idle/legacy cutoffs. `tests/storage.test.ts` fences lifecycle-only writes to config/runtime files; `tests/extension.test.ts` covers idle/legacy cutoffs and new/fork boundaries.
-20. **Passive observability omits active status without hiding owner revisions:** `tests/status.test.ts` proves an accepted passive patch advances semantic history while compact terminal status stays absent. `tests/telegram.test.ts` drives the real extension port after Stop, requires the passive main-menu identity to render `State Flow: off`, verifies an owner Rich-state heading uses its independent `#revision` and Effective uses `G#/C#/S#`, and separately proves Telegram can lazily observe existing shared canonical state when passive model tools are disabled without initializing or mutating storage.
+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 across all passive-policy combinations: local mode turns off, canonical bytes stay unchanged, cached memory and available context survive, 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.
+20. **Passive observability omits active status without hiding owner revisions:** `tests/status.test.ts` proves an accepted passive patch advances semantic history while compact terminal status stays absent. `tests/telegram.test.ts` drives the real extension port after Stop, requires the passive main-menu identity to render `State Flow: off`, verifies an owner Rich-state heading uses its independent `#revision` and Effective uses `G#/C#/S#`, and separately proves Telegram can lazily observe existing shared canonical state when passive model tools are disabled without initializing or mutating storage. A failed-Stop callback reports local disablement and keeps accepted cached memory inspectable without overwriting the concurrent writer.
 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.
+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.
+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.
+24. **Awaited inspection is coherent and observational:** `tests/runtime.test.ts` pauses an independent writer between semantic-tail and metadata publication for over two seconds: shared inspection waits responsively, preserves its cached view, and then reads matching Global/CWD/artifact evidence with its own private layer. Cancellation, absent/malformed storage, unchanged reads and competing private authority preserve bytes and history. `tests/telegram.test.ts` covers lazy passive and active reads without publication/checkpoints, coupled data/revision receipts, revocation before presentation, Stop/tree/shutdown cancellation, early callback acknowledgement and escaped late errors without a second callback answer. Legacy ports and failed-Stop cached inspection remain supported.
+25. **Coherent backup capture preserves semantic acceptance and Abort:** `tests/git.test.ts` pauses an independent publisher between scope files for over two seconds, then verifies one complete committed inventory including newly created namespaces. Cancellation preserves files/HEAD/index and releases only the owned backup mutex; local waiters serialize, replacement ownership survives, and Git branch/head drift after waiting is rejected. Existing slow-Git witnesses still observe no Git command under canonical exclusion. `tests/episode.test.ts` checks operation cancellation, shutdown draining, later retry and Stop write-fence preservation. Native tests require the commit before later settlement handlers, or explicit deferral when SDK 0.87 provides no abort signal. `tests/storage.test.ts` distinguishes nonwaiting busy admission from malformed ownership without theft. Full native cancellation of a settlement wait is unavailable on this SDK; the selected policy is deferral, not scheduled upstream work or a synthetic-signal guarantee.
+26. **Advisory startup inspection awaits coherent evidence:** `tests/continuation.test.ts` pauses an independent publisher between private-tail and metadata replacement for over two seconds. Inspection and the default-launch recommendation wait; cancellation rejects without suggesting another session or changing bytes/lock ownership. After release, eligibility uses the complete accepted cohort. Absent/empty stores stay uninitialized; malformed, orphaned, symlinked and invalid-lock evidence stays ineligible. Async host callbacks preserve detached native headers and eligibility, cannot override native identity, and cannot return late decisions or inspect more candidates after cancellation. Existing native-session, shared-drift and private-lineage witnesses remain applicable; these are advisory APIs, not an installed native startup hook.
+27. **Awaited runtime-only acceptance preserves semantic authority:** `tests/runtime.test.ts` applies both raw and awaited lifecycle publication beside independently advanced Global/CWD state or evidence at limits 0/7, preserving wider stored tails, orphaned provenance, unknown metadata and private values. An independent publisher pauses mid-cohort for over two seconds; waiting/cancellation changes no accepted bytes/cache, and the post-wait callback uses current lifecycle input. Authority, malformed/partial/absent storage, private races, newer selections, single-use/expired capabilities and rollback remain fenced; correct repeats add no history. Native “real Pi context provides a cancellable lifecycle boundary” probes prove acceptance before the provider and actual Abort cancellation without later inference/publication. Those embedding probes establish the SDK seam; production preparation is covered separately below. No-transition patch publication passes the same wider-history/evidence matrix for complete accepted cohorts; an absence witness distinguishes its normal atomic initialization from the explicit lifecycle-only API, which still refuses missing semantic storage.
+28. **Pre-inference preparation accepts once or stops inference:** Extension witnesses prove capture/no-signal projection is read-only, current-head maintenance shares lifecycle acceptance, reappearing sources survive, duplicate contexts reuse preparation and pre-acceptance failure rolls back both maintenance and metadata. Abort, Stop, selection, shutdown and superseded runs preserve newer state/fences; post-acceptance failure cannot replay an old specification. Native “real Pi production preparation” holds an independent partial publisher for over two seconds, then proves matching `G2/C2/S2`, source/provenance cleanup and private isolation before the first provider, while the native missing-CWD witness preserves current-empty initialization without resurrection, or actual Abort with no publication/inference after release. Native fault injection proves public `ctx.abort()` fences Pi's otherwise fail-open context hook. Session/native tests retain uncheckpointed input through reload/Stop/cold resume and interrupted boundary-continuation tool evidence through idle Stop/reload, without inventing a run or reviving a completed specification.
+29. **Awaited Stop preserves immediate policy and accepted authority:** Extension tests prove immediate passive projection, one runtime-only acceptance for repeated pending Stops, current shared adoption with unchanged semantic/provenance bytes, and lifecycle derivation after an intervening same-instance passive patch. Operation cancellation keeps mode off and fences writes; selection/shutdown/accepted Start withdraw obsolete work without later mutation, while rejected Start leaves Stop pending. Publication faults roll back config/runtime without installing shared adoption; native checkpoint faults after acceptance do not roll back or retry writes. Native “real Pi stop keeps local mode off while awaiting a partial foreign publication without private leakage” holds an independent writer for over two seconds, then requires current Global/CWD plus local Session in passive provider input. Telegram controls acknowledge early, await results, escape late errors and suppress revoked/navigated/disposed views; legacy synchronous controls remain compatible.
+30. **Awaited Start activates current authority without stale rollback:** Runtime witnesses preserve semantics, provenance, revisions, step and aligned history across old mode/unfinished-work combinations; expired/single-use capabilities, partial private authority, unauthorized absent-root creation, noncooperating private-byte replacement after capture, rollback and no-op acceptance are checked. Extension witnesses prove coalescing, no early policy/cache/checkpoint changes, post-wait bootstrap/private-step derivation, Stop/session/tree/shutdown cancellation, physical-owner revalidation and no rollback/replayed checkpoint after acceptance. A completed Start failure loses Telegram presentation authority when selection changes during callback acknowledgement. Native “real Pi start keeps local mode off while awaiting a partial foreign publication without private leakage” waits over two seconds behind an independent partial writer, then verifies current Global/CWD and local Session in the next provider input. 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:** 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. Native caller cutover evidence is item 35.
+32. **Awaited exact-source fork 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. Every occupied child file, unsupported legacy 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. Shared unknown metadata and unrelated provenance survive. Native fork caller evidence is item 35.
+33. **Awaited current-memory recovery stays read-only:** Awaited loader matrices at limits 0/7 preserve current same-session values, step, revisions and bootstrap beside independently advanced shared streams without inheriting foreign private memory or unfinished specifications. No composed history is invented and no canonical files change, even when the in-memory view folds wider tails. Recovered caches cannot authorize lifecycle/patch publication. An independent partial writer held over two seconds proves cancelable coherent capture; injected cancellation during capture prevents cache installation. Missing roots/private authority remain absent, malformed/partial/identity/provenance errors retain the prior cache and bytes. Native failed-Stop wiring evidence is item 35.
+34. **Lifecycle fixtures await completion without trapping withdrawal:** Direct startup/tree fixture calls await their handlers before inspecting completed state. Preparation, response, Start, Stop and Telegram inspection cancellation families dispatch replacement selection separately, prove the obsolete operation withdraws while storage remains held, then release exclusion and join the replacement. Canonical-byte and stale trace/notice assertions remain; UI stability is measured after legitimate replacement completion. Item 35 records the resulting native cutover.
+35. **Native branch restoration awaits one owned lifetime:** Extension witnesses hold exclusion across startup, tree, auto-start and failed-Stop reload: mode stays passive, private reads/patches report the pending selection, and files/checkpoints stay unchanged until acceptance. Joined Starts stay inert; bootstrap derived after waiting shares the single runtime write. Replacement selection/shutdown withdraw obsolete restoration while storage remains held. Stop changes the pending acceptance's policy without revoking its memory operation; mode separation is covered by items 37–38. Failed-Stop reload stays read-only and fenced; post-acceptance checkpoint failure warns without rollback or replay. Native tree/fork witnesses hold a publisher, then require selected private memory, unchanged parent-private files and matching next-provider input. The initial cutover probes, except their shutdown case, also failed against pre-cutover synchronous orchestration.
+36. **Recovery joins, draining and cache installation retain separate owners:** Start cancellation returns while independently owned restoration still waits; physical identity stays pinned across that join, so a changed owner cannot be activated. Recovery-domain tests preserve other joiners and observe late owner failures even after pre-cancellation. Shutdown waits for both current and superseded restoration operations, including delayed reader completion. Passive reads remain detached when physical CWD changes, and late native cancellation prevents both passive and private recovery cache installation. A private patch accepted between passive capture and attachment completion retains its newer cache and canonical bytes. These extension/domain witnesses supplement the native cutover probes rather than claiming universal idle Abort support.
+37. **Fork memory creation is independent of active/passive policy:** The extension native-fork/Start-retry × warm/cold × retained/expired matrix holds exclusion while Stop selects passive policy. The copy must remain pending rather than be cancelled, including when Stop withdraws its Start waiter. After release, retained source memory is accepted once with disabled policy, passive patching changes child-owned memory without enabling the mode, and native trace reopening through `SessionManager.open` preserves that child state. Expired source history refuses canonical publication and substitute checkpoints. These fixtures replace the former tests that codified Stop cancelling copying; the separate public SDK control/next-provider witness is item 40; installed UI reachability remains unverified.
+38. **Stop cannot manufacture a restoration failure:** Held-store retained-boundary and auto-start fixtures require repeated Stop to return promptly without cancelling memory acceptance, adding an error fence or publishing early. Release accepts the selected/initial memory with passive policy, permits passive patches and retains them across reload. Stop→Start while waiting activates only after memory acceptance. A separate Start-owned attachment witness withdraws the Start waiter without cancelling restoration. The native SDK tree witness invokes `/state-flow-stop` during awaited `navigateTree`, then verifies selected private memory, passive tool availability and a successful next-provider patch; selected conversation remains visible and later-branch private memory stays absent. This public SDK route is not installed Telegram/TUI reachability certification.
+39. **Native Skill compilation reconciles an independent writer without private leakage:** The Global/CWD × duplicate/competing/invalid matrix runs real Pi acquisition and compiler tool calls while a separate process publishes between the model's source read and its patch. Identical compiler output leaves shared checkpoint/tail/provenance bytes, scope revision and runtime step unchanged. Different output replaces the complete artifact and matching source-hash/compiler evidence, preserves independent peer fields, and advances the affected revision once. The next provider sees adopted shared state and local private memory, never the peer's private sentinel; all five peer-private files remain unchanged. An invalid compilation combined with a Session mutation rejects without changing any captured canonical file or accepting the accompanying Session field. The peer uses the runtime publication API, not a second provider; these ordered interleavings supplement the separate held-writer cancellation tests.
+40. **A public SDK host can control a child while fork binding awaits memory:** The fixture observes the public `createAgentSession` result before awaiting `bindExtensions`, without private SDK hooks or direct calls to State Flow command handlers. During a held-store `runtime.fork`, it calls the child's public `prompt('/state-flow-stop')`; an optional subsequent Start waits for memory acceptance. Stop returns while the fork remains pending. After release, the child has a distinct identity, selected private memory and the requested passive/active policy. Its next provider sees selected rather than later-parent private state, successfully patches child memory and leaves all parent-private files unchanged. This certifies the embedding route on the tested SDK, not whether the installed CLI or Telegram exposes that child before its runtime replacement completes.
 
 ## Additional preservation boundaries
 
-- `tests/continuation.test.ts` independently advances global/CWD at limits 0/7, then proves read-only eligibility agrees with actual restore and preserves the session layer, including shared-only transitions. `tests/temporal.test.ts` covers sparse/inherited session lineage, conflicting checkpoint/tail identities and parents, future patches, and immutable inputs. The runtime restore/fork contradiction witnesses preserve source/target files rather than accepting a new origin over mixed session files. The native “real Pi refuses contradictory session files without passive substitution and retries the repaired selection” witness retains shared access, fences session access/Start/Stop, preserves the selected checkpoint, and succeeds after exact-source repair. These are synthetic integrity tests, not evidence of spontaneous cross-session leakage.
+- `tests/continuation.test.ts` independently advances global/CWD at limits 0/7, then proves read-only eligibility agrees with actual restore and preserves the session layer, including shared-only transitions. `tests/temporal.test.ts` covers sparse/inherited session lineage, conflicting checkpoint/tail identities and parents, future patches, and immutable inputs. The runtime restore/fork contradiction witnesses preserve source/target files rather than accepting a new origin over mixed session files. The native “real Pi refuses contradictory session files without passive substitution and retries the repaired selection” witness retains shared access, fences private access and publication, permits local Stop without a substitute checkpoint, and succeeds after exact-source repair. These are synthetic integrity tests, not evidence of spontaneous cross-session leakage.
 - `tests/extension.test.ts` distinguishes pre-runtime Stop from accepted-runtime Stop across passive configurations: global-only and shared storage remain unchanged, repeated Stop/reload retain the disabled marker, and subsequent Start/passive patch establishes a retained session boundary. Malformed/incomplete scope files remain unavailable; Stop does not repair CWD-only storage, while explicit Start may initialize its wholly absent global scope. The native “real Pi Stop preserves a global-only passive branch through reload, patch, and Start” witness checks the same lifecycle without Git. `tests/invariants.test.ts` rejects the retired Skill converter in both package and domain exports; existing Skill/transition witnesses preserve real source hashing, hashing failure, and retired-field rejection.
 - `tests/durable.test.ts` and `tests/storage.test.ts` cover canonical-format rejection, owned regular files, raw-byte rollback, prepared-output receipts, stale/omitted-scope CAS, literal paths, malformed cohorts, and shared-writer exclusion.
 - `tests/git.test.ts` proves settled backup preserves unrelated staged/index-only/worktree data, already-staged owned deletions, Git ignore/filter policy, literal paths, and opaque bytes. Controlled Git pauses before/after snapshot capture allow an independent canonical writer to advance and create a new scope; the commit must match exactly one captured cohort, never mixed live bytes. Every observed Git command runs outside the backup's canonical lock. Namespace/type witnesses exclude unrelated traversal and refuse non-regular sources. No-op/unowned-only initial backups skip; Git/index failures preserve canonical acceptance and caller data. `tests/episode.test.ts` proves one diagnostic-only attempt at `agent_before_settle`, without answer changes or an automatic retry.
@@ -40,7 +59,7 @@ This is a maintained property-to-test map for the current canonical-file contrac
 - `tests/integration.test.ts` — “real Pi boundary continuation keeps accepted State Flow memory” exercises actual companion `turn_end` and `agent_before_settle` draft entries and continuation. Each next provider input has exactly one current-memory projection before/after a continued patch, the accepted response and current tool declarations. There is only one `before_agent_start`, no restored specification in runtime checkpoints or model projection, exactly one requested continuation and correct final response/step. The pure “projects accepted memory without resurrecting a completed specification for boundary continuation” witness preserves source state, omits lazy bodies, and keeps available context when both specification and native capture are absent.
 - `tests/integration.test.ts` — “real Pi context edits remain canonical through tools, tree selection and reload” proves native user-content replacement, assistant/custom-message omission and live tool-result replacement reach provider input without resurrecting raw history. Selecting an unedited branch restores its native view without overwriting accepted semantic files; selecting the edited branch and reloading preserves its edits and independent memory. Raw JSONL stays append-only.
 - `tests/integration.test.ts` — “real Pi structured prompt composes with context hooks” covers active, passive, disabled and explicit foreign-force modes. Conversation hooks exclude systems; full-system hooks receive them; companion before-run and per-request sections plus actual tool declarations survive. User specifications remain outside system authority. Stop/Start on subsequent user requests removes/reinstates the owned section once.
-- `tests/integration.test.ts` — “real Pi preserves native run identity across mode toggles” covers initially enabled, mid-tool Start and repeated Start/Stop with passive bootstrap on/off. Actual provider inputs retain original user/read evidence but not the preceding disabled request; persisted Stop markers name the observed native user, and fixture reload preserves trajectory, frozen state and raw trace prefix. `tests/compaction.test.ts` — “native session boundaries invalidate observed run capture without projection reacquisition” pairs session-start/tree resets with an admitted unchanged-run control. No new stored field or guessed anchor is used.
+- `tests/integration.test.ts` — “real Pi preserves native run identity across mode toggles” covers initially enabled, mid-tool Start and repeated Start/Stop with passive bootstrap on/off. Actual provider inputs retain original user/read evidence but not the preceding disabled request; persisted Stop markers name the observed native user, and fixture reload preserves trajectory, frozen state and raw trace prefix. `tests/compaction.test.ts` — “native session boundaries invalidate observed run capture without projection reacquisition” pairs session-start/tree resets with an admitted unchanged-run control. Run identity remains native rather than guessed; an independent optional Stop-marker flag preserves uncompiled bootstrap context without changing the captured anchor.
 - `tests/integration.test.ts` — “real Pi refreshes protocol within the same run” covers mid-read Stop, passive Stop, mid-read Start and accepted-boundary Stop/continuation. The next provider request has current protocol/tools, foreign context and tool evidence, no elevated specification and only one user-run preparation; response reconciliation follows the actual mode and earlier native system frames remain intact. `tests/context.test.ts` — “refreshes only owned system protocol without mutating native frames” covers old/replaced/deleted sections, foreign content/tools, conversation identity/order, frozen inputs, absent-frame non-synthesis and unchanged-delta no-ops.
 - `tests/integration.test.ts` — “real Pi recovery omits failed attempts without accepting them” checks retry/length/overflow through actual SDK dispatch: durable omission edits, raw trace preservation, unchanged accepted response/step until successful recovery, native split-turn summaries and fixture reload. “real Pi edited-context accounting discards stale provider usage” checks reduced native usage after replacement and one subsequent inference without phantom compaction.
 - `tests/integration.test.ts` — “real Pi settled dispatch preserves deferred companion work” covers low pressure, real owned compaction and explicit compaction refusal. The native completion/error callback finishes before settled dispatch returns; all companion observers precede exactly one deferred request, which sees accepted memory and reconciles the expected response/step. The admitted case verifies an actual State Flow-owned compaction rather than relying only on a token estimate.
@@ -49,9 +68,10 @@ This is a maintained property-to-test map for the current canonical-file contrac
 - `tests/context.test.ts` and `tests/extension.test.ts` prohibit process queries during ordinary context/history reads. `tests/transition.test.ts` rejects stale staging even when semantic values coincide across different causal boundaries.
 - `tests/status.test.ts` distinguishes selected temporal history depth from retained per-scope tails and unavailable materialization from an empty state.
 - `tests/artifact.test.ts` and extension/native integration witnesses prove exact registered-path inspection, `size + mtimeNs` evidence, non-destructive unavailable/symlink handling, owning-scope removal, runtime-only changed-source hints, and stable-read acceptance without directory discovery. The native newly-adopted-artifact witness proves run preparation refreshes live shared state before proven-missing maintenance and the first inference. Artifact/acquisition/rehydration tests and “real Pi ordinary artifact invalidations share the public fingerprint classifier” cover equal/changed/missing/malformed fingerprints, pre-epoch timestamps, compiler invalidation, detached read plans, legacy hash handling, and effective Skill masking while preserving Skill hashing.
-- `tests/protocol.test.ts` checks runtime/Skill guidance names the reported artifact owner. Registered-Skill unit and native witnesses use Pi's public command source metadata to map user/project/temporary Skills to global/CWD/session, ignore unregistered `SKILL.md` reads, skip matching hashes, permit unrelated patches while compilation remains optional, retain strict attempted-output validation, and publish source-hash provenance to the exact reported owner.
+- `tests/protocol.test.ts` covers long/spaced/Windows/Unicode operands, exact scopes and basenames, trailing causes, prose apostrophes, nested/aggregate/cyclic causes, repeated compaction and malformed escaped quotes. Native “real Pi transports actionable long-path diagnostics and accepts an exact-target correction” cases cover all three scopes: rejection preserves canonical bytes, the next provider receives the same actionable error text despite empty `toolResult.details`, a corrected patch uses the original target, and opt-in logs retain full attempted input/path/call identity. The nested-publication native witness separately proves textual cause delivery. Extension lifecycle tests preserve filenames, `EEXIST`, one failed-Start notice and fenced-write recovery guidance under long spaced store paths; status and Telegram tests preserve causes/targets within their display budgets. `tests/episode.test.ts` retains the Git operation and missing-identity reason without undoing accepted memory. Tool failures keep heading separation.
+- 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.
 - `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.
-- `tests/storage.test.ts` covers exact file-cohort references, file CAS/rollback, and shared writer exclusion. `tests/runtime.test.ts` and native Pi lifecycle tests cover retained-boundary restart, immediate barriers, finalized response, config-only stop, and unavailable-reference provenance. Canonical files supply current state and bounded hot history; arbitrary cold revision recovery is unsupported.
+- `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.
 - `tests/runtime.test.ts` and native integration cover retained-boundary restoration and fork after lowering `historyLimit` to 0/1: current shared values/provenance and selected private state survive folding, parent-private fork files remain unchanged, out-of-window selections fail closed, and later increases do not reconstruct discarded history. `tests/config.test.ts` covers optional agent configuration, path precedence/expansion, invalid input, load-time caching and read-only behavior. Session tests and native Pi distinguish configured new-session auto-start from branch-local resume/tree/stop. `tests/extension.test.ts` proves registered artifacts are reconciled only at enabled inference boundaries. The global default is manual; CWD materialization alone no longer grants automatic activation.
 
 ## Validation and limits

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

@@ -4,15 +4,34 @@ For the concept and installation, start with the [README](../README.md). This gu
 
 ## Session behavior
 
-`/state-flow-start` initializes any missing storage and enables the current Pi branch. No remote is required. Starting mid-conversation retains Pi's active context for one complete bootstrap run, during which the agent must compile future-relevant information into state.
+### Active, passive and configured off
+
+State Flow has three distinct model-facing states. **Active versus passive changes the agent's workflow, not the existence of disk memory.**
+
+- **Active:** Both `read_state` and `patch_state` are available, subject to host restrictions and valid memory authority. Prompts require the agent to consolidate future-relevant results into state before ending an iteration. The final meaningful semantic patch preserves decisions, outcomes and continuation needed after the completed conversation is removed from model projection. The next iteration starts from accepted state and its new input, not the previous iteration's completed reasoning. Native trace remains inspectable; a clean model context does not mean deleting Pi history.
+- **Passive:** Both memory tools remain available with the default passive configuration. Existing state is projected into context, and the agent may read or patch it as useful. Ordinary conversation continuity remains: State Flow does not impose the active iteration-ending context reset or the same mandatory consolidation pressure. Accepted patches still reach the same canonical store with the same validation and ownership guarantees.
+- **Configured off:** Neither memory tool is exposed to the model, and State Flow injects no bootstrap/state context. This is distinct from passive mode, and does not mean deleting stored memory. With the current configuration, this means an inactive branch plus `passiveTools: false` and `passiveBootstrap: false`. `autoStart: false` only disables automatic activation of new sessions; it does not disable passive memory or override an already active resumed branch.
+
+The two passive settings are independent: turning off only tools or only projection produces a deliberately partial integration, not the fully off state. Host restrictions and genuine unavailable/corrupt-memory fences are separate from these mode definitions.
+
+**Completion is semantic, not ceremonial.** In active mode, necessary final state changes must be accepted before relying on state-only continuation. This does not require an empty `patch_state` when memory is already current, an extra model turn, or a special finalization tool. Each `patch_state` remains an inference barrier, not automatically the end of an iteration; the runtime separately persists the accepted ordinary answer as Session `response` and completes the run.
+
+Here, “bootstrap from state” means constructing model context from durable memory. The implementation's `meta.bootstrap` is narrower: the one transition run that retains an existing conversation while active mode is first enabled and that conversation is compiled into state. It is not a flag that must be re-entered on every active iteration. Native compaction is also separate from model-context projection; its safety checks and usage threshold still apply.
+
+Start/Stop change active/passive behavior and respect the configured passive capabilities. They do not choose a different storage algorithm or cancel creation of a fork's private memory. A fork receives its own initial Session state from the selected parent boundary, then lives independently in either mode. See [fork support](#fork-support-and-limits).
+
+### Lifecycle operations
+
+`/state-flow-start` enables the current Pi branch over validated current same-session memory, initializing absent storage when safe. No remote is required. Starting mid-conversation retains Pi's active context for one complete bootstrap run, during which the agent must compile future-relevant information into state. Repeating Start while already active leaves the in-progress run unchanged. On an attached branch, current-memory activation waits asynchronously for a coherent canonical cohort; pending repeats share the wait. Until acceptance, existing passive context, tools and any Stop fence remain in effect. Stop or selection can withdraw obsolete activation; an error after acceptance does not undo enabled memory.
 
 - **New session:** Passive durable memory is available by default without starting an episode. `autoStart` promotes genuinely new sessions into active State Flow; an active new session has its own empty session layer and inherits global/CWD state, never another session's private continuation.
 - **Resume:** Restores the selected session's stored enablement, state, and lineage. Agent-level `autoStart` does not override a resumed branch.
 - **Tree navigation:** Restores the selected retained private boundary over live shared scopes without checking out or resetting the shared store.
-- **Abort inference:** Stops generation while already accepted patches remain durable for continued work and corrected direction in the same session. It does not roll back memory or require immediate remote replication.
+- **Abort inference:** Stops generation or an outstanding response-publication wait while already accepted patches remain durable for continued work and corrected direction in the same session. Cancellation before response acceptance keeps the previous response and unfinished run; cancellation after acceptance never rolls it back. It does not require immediate remote replication.
 - **Native boundary continuation:** A companion may continue through Pi's `turn_end` or `agent_before_settle` boundary without a new user prompt. State Flow keeps projecting current memory and accepted response across those requests and subsequent patches; it does not restore the completed specification or request another turn itself.
-- **Stop:** Ends active episode semantics and returns to the configured passive bootstrap/tool combination. For a proven pre-runtime branch, it records only the existing disabled checkpoint in Pi, without creating canonical files or publishing the passive view; later Start or passive patch remains available. For an accepted runtime, it adopts unrelated shared-state changes without semantic/provenance writes or step changes, while same-session conflicts still fail closed. Its frozen handoff uses the accepted view. It does not change passive or automatic-start policy.
-- **Continue after Stop:** The same physical session retains a frozen state handoff, any interrupted current request and tool trajectory (including late results), and post-stop conversation. A proven active boundary excludes completed earlier conversation; when native split-turn compaction removed the original request anchor, Stop instead preserves the available summary and tools without reconstructing discarded raw input. Other extensions' custom context survives. Idle Stop still retains only later conversation plus foreign custom context. Reload/resume/tree preserve this projection; new/forked physical sessions do not inherit it. Mid-tool Start and repeated Start/Stop retain the first user event already observed while disabled, so subsequent Stop does not mistake that busy run for idle. Active restart uses the retained projection for one bootstrap run.
+- **Stop:** Ends active episode semantics and returns to the configured passive bootstrap/tool combination. For a proven pre-runtime branch, it records only the existing disabled checkpoint in Pi, without creating canonical files or publishing the passive view; later Start or passive patch remains available. For an accepted runtime, it adopts unrelated shared-state changes without semantic/provenance writes or step changes. Same-session conflicts refuse canonical publication but do not prevent local disablement. Its frozen handoff uses the accepted view. It does not change passive or automatic-start policy.
+- **If Stop cannot persist:** Active mode still turns off. The last accepted cache remains readable and all available native conversation is retained. Pi's native session records the local Stop and a write fence, without a replacement semantic checkpoint. Tree/reload/resume stay passive and load validated current same-session memory read-only; they never replay an older selection over another writer. Unavailable or corrupt memory stays unavailable. Repeated Stop does not retry or clear the fence. Explicit Start revalidates current memory and clears the fence only after canonical acceptance. This fallback requires Pi's native trace to remain writable; it does not repair storage. The canonical config may still say enabled, but the native failed-Stop policy overrides it on this branch.
+- **Continue after Stop:** The same physical session retains a frozen state handoff, any interrupted current request and tool trajectory (including late results), and post-stop conversation. Outside an unfinished bootstrap, a proven active boundary excludes completed earlier conversation; when native split-turn compaction removed the original request anchor, Stop instead preserves the available summary and tools without reconstructing discarded raw input. An unfinished bootstrap keeps all available native context, or the earlier passive boundary it received; repeated Start/Stop cannot move that boundary past uncompiled conversation. An interrupted run retains its captured anchor even after Pi becomes idle, falling back to all available context when that anchor is unknown. Other extensions' custom context survives. Only Stop after a completed idle run retains just later conversation plus foreign custom context. Reload/resume/tree preserve this projection; new/forked physical sessions do not inherit it. Mid-tool Start and repeated Start/Stop retain the first user event already observed while disabled, so subsequent Stop does not mistake that busy run for idle. Active restart uses the retained projection for one bootstrap run.
 - **Completed-history compaction:** After an accepted run settles without queued input, State Flow asks Pi for a native compaction boundary only when public context usage reaches 24,000 tokens. No extra model summary is requested; Pi keeps the complete latest run—from its original request through steering, tools, foreign context and final answer—in active history and retains the complete append-only JSONL/tree. State Flow uses the native first-user anchor, independent of image-normalization hints or later steering; images and earlier tool results remain available to the model. Uncertain projection retains available context without changing that anchor. A missing or ambiguous native anchor skips compaction instead of choosing the last steering message. On resume, native `buildContextEntries()` and TUI rendering omit the older completed prefix. Unknown or smaller usage skips the request, and custom Pi retention settings may still decline it benignly. Foreign custom context in the removed prefix, bootstrap/abort/error, Stop and pending input prevent State Flow-owned shortening; ordinary manual/threshold/overflow compaction remains native and may preserve unfinished work not yet patched into memory.
 
 State Flow does not undo tool effects. After interruption or returning to an older branch, check the relevant workspace or external system before repeating consequential operations. Restored memory is not restored reality.
@@ -25,7 +44,7 @@ The child starts at step zero and a new temporal origin. Its copied tail obeys t
 
 Initial copying requires 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/unsafe evidence or CAS conflicts leave the copy unavailable rather than importing unrelated or newer private state. Explicit Start can retry an unaccepted copy in the same loaded fork after the cause is corrected.
 
-Selecting a copied parent checkpoint through the child's `/tree` does not make it child-owned: State Flow stays disabled without resetting existing child data. Select a child-owned checkpoint or resume the original session. Cold recovery before the first child checkpoint, startup paths lacking the fork event, in-memory parent locators and cross-CWD imports remain outside this slice. File-only copying requires an exact still-available source cohort. See the [contract](fork-contract.md) and [SDK compatibility boundary](compatibility.md#public-host-seams); do not rewrite UUIDs or delete pointers to force recovery.
+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. 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. Cold recovery before the first child checkpoint, startup paths lacking the fork event, in-memory parent locators and cross-CWD imports remain outside this slice. File-only copying requires an exact still-available source cohort. See the [contract](fork-contract.md) and [SDK compatibility boundary](compatibility.md#public-host-seams); do not rewrite UUIDs or delete pointers to force recovery.
 
 ## Configuration
 
@@ -46,9 +65,9 @@ The canonical store is `state-flow/` beneath the agent directory. Keeping config
 - `autoStart`: Defaults to `false`. When `true`, genuinely new sessions use the same initialization as explicit Start, including fresh CWDs.
 - `passiveBootstrap`: Defaults to `true`. Projects existing effective durable memory into ordinary model context without creating scopes, publishing, or starting an episode.
 - `passiveTools`: Defaults to `true`. Exposes `read_state` and `patch_state` outside active episodes. Reads remain side-effect free; the first explicit patch may initialize absent canonical storage but never converts predecessor formats or enables an episode or State Flow compaction.
-- `logging`: Defaults to `false`. When enabled, records rejected patches and accepted-answer reconciliation failures locally at `tmp/state-flow/logs.jsonl` beneath the agent directory. Asynchronous Git push failures are recorded there even when this setting is off.
+- `logging`: Defaults to `false`. When enabled, records rejected patches, preparation failures and accepted-answer reconciliation failures locally at `tmp/state-flow/logs.jsonl` beneath the agent directory. Asynchronous Git push failures are recorded there even when this setting is off.
 - `showSuccessfulPatches`: Defaults to `true`. In interactive Pi, successful `patch_state` rows show only the applied pretty-printed JSON arguments, with blank lines between adjacent memory sections; set it to `false` to keep only the compact summary. Rejected calls still use ordinary error rendering; State Flow adds no private validation turn.
-- `historyLimit`: Defaults to `7` and accepts integers from `0` through `100`. It bounds materialized-history and scope patch-history offsets. Lowering it on reload/restore/fork folds excess tails forward without losing current state; selected boundaries outside the new window are unavailable. Zero retains only current checkpoints. Raising the limit affects only future retention and cannot reconstruct discarded history.
+- `historyLimit`: Defaults to `7` and accepts integers from `0` through `100`. It counts accepted semantic transitions, **not elapsed time or conversation length**. It bounds materialized-history and scope patch-history offsets. Lowering it on reload/restore/fork folds excess tails forward without losing current state; selected boundaries outside the new window are unavailable. Zero retains only current checkpoints. Raising the limit affects only future retention and cannot reconstruct discarded history.
 
 Settings are read once at extension load. After editing, use `/reload` or restart Pi. A missing file uses defaults without creating a configuration file; malformed JSON, unknown keys, or invalid values fail loading rather than silently selecting another store.
 
@@ -58,7 +77,7 @@ Settings are read once at extension load. After editing, use `/reload` or restar
 
 Rejected-call records may contain exact attempted arguments and useful draft text, plus the error category and tool/call identity. Asynchronous push failures retain the available redacted Git error there regardless of `logging`; interactive warnings stay short and appear once per failure streak, then reset on success. If logging the push failure is unavailable, one warning exposes the available detail instead. Successful patches are not logged; reasoning bodies are excluded. Logs are not semantic state, scope metadata, Pi checkpoints, or publication input. If the log path overlaps a custom state repository, capture fails closed instead of committing it. A logging failure changes no accepted state and produces at most one local warning.
 
-Logs remain local unless you move them; rotation/deletion is operator-owned. Treat them and state files as private. Removing a secret from current state does not erase older offsets, Git history, native sessions, or remote copies.
+Logs remain local unless you move them; rotation/deletion is operator-owned. State Flow-authored errors and warnings display as one compact line: long operands are elided with `…` before prose so the operation, offending scope, target basename/suffix and actionable reason remain visible. Nested causes travel as text because Pi tool results need not retain `Error.cause`. Enabled diagnostic records keep the full target and rejected input for investigation. An explicit Start retry reports its final failure once rather than repeating its startup warning. Tool failures still keep the required blank line beneath their heading. Treat logs and state files as private. Removing a secret from current state does not erase older offsets, Git history, native sessions, or remote copies.
 
 ## Status and controls
 
@@ -71,7 +90,7 @@ Logs remain local unless you move them; rotation/deletion is operator-owned. Tre
 
 Tail counts are not history depth: inherited records may predate the active origin. Failed inspection reports unavailable evidence, not invented empty state. Status is observational: it does not read source files, calculate fingerprints, create invalidations, or mutate semantic state.
 
-The terminal indicator is `state-flow G15/C8/S31` only in active mode. Global, CWD and Session own independent semantic revisions; one atomic transition advances each materially changed scope once, including session-only response reconciliation. Effective has no scalar counter and uses the `G#/C#/S#` revision vector. When `pi-telegram` is available, its main-menu section shows that vector only while active and `State Flow: off` while passive. Requested owner-scope Rich snapshots show `#revision`; Effective shows the vector. Telegram inspection may lazily load or refresh live shared state from other instances even when passive model tools are disabled, but it does not initialize, publish, or advance storage. Start requested during a run waits for settlement; Stop currently applies immediately. The adapter is optional and the Pi commands remain available without it. Open implementation work is tracked in [BACKLOG.md](../BACKLOG.md).
+The terminal indicator is `state-flow G15/C8/S31` only in active mode. Global, CWD and Session own independent semantic revisions; one atomic transition advances each materially changed scope once, including session-only response reconciliation. Effective has no scalar counter and uses the `G#/C#/S#` revision vector. When `pi-telegram` is available, its main-menu section shows that vector only while active and `State Flow: off` while passive. Requested owner-scope Rich snapshots show `#revision`; Effective shows the vector. During a failed-Stop write fence, inspection uses the accepted cache without a potentially conflicting refresh. Otherwise, Telegram inspection waits cancelably to load or refresh one coherent shared view, even when passive model tools are disabled. It does not initialize, publish, or advance storage. Data and displayed revisions belong to the same observation; absent/invalid memory stays unavailable. Stop, session/tree changes and shutdown cancel obsolete observations. The button acknowledges immediately, and a late failure appears in the menu instead of an expired callback popup. Start requested during a run waits for settlement; Stop currently applies immediately. The adapter is optional and the Pi commands remain available without it. Open implementation work is tracked in [BACKLOG.md](../BACKLOG.md).
 
 ## Storage and recovery
 
@@ -86,11 +105,13 @@ Each scope materializes an anchored semantic-only `checkpoint.json` plus semanti
 
 ### Missing, partial, and malformed storage
 
-A checkpoint and tail are one semantic pair. If both live files for an untouched global or CWD scope disappear, State Flow treats that complete absence as current empty shared reality during the next accepted publication. It creates a fresh canonical pair through normal file-cohort exclusion and CAS; no cold Git value is resurrected. A patch targeting the disappeared scope is rejected once as stale so a later inference can work from the actual empty basis.
+A checkpoint and tail are one semantic pair. If both live files for a global or CWD scope disappear, State Flow treats that complete absence as current empty shared reality. An authored `patch_state` applies to that empty basis under exclusion; normal file-cohort CAS creates the accepted pair without resurrecting cold values or orphaned compilation evidence. Raw precomputed replay still refuses a removed selected target rather than replaying stale normalized changes.
 
 Exactly one surviving pair member is corruption and fails closed. Present malformed JSON, incomplete predecessor envelopes, semantic/metadata boundary mismatches, identity contradictions, and partial session runtime evidence also remain fail-closed and are not replaced. A missing or expired private retained boundary is unavailable; State Flow does not substitute Git history or newer private files.
 
-After a selected-boundary failure, configured passive access may still expose current global/CWD memory, but it never grants access to the unavailable session layer or permission to publish an empty replacement. Session reads, every `patch_state`, and Stop refuse without changing canonical files or appending substitute checkpoints. Status retains the restoration error even when shared reads work. Start retries the original selection; repair its missing or invalid evidence, select a still-retained boundary, or use a genuinely new Pi session instead of forcing a reset.
+After a selected-boundary failure, configured passive access may still expose current global/CWD memory, but it never grants access to 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. Stop remains available and records the native policy/write fence described above; a subsequent reload may expose validated current memory read-only, not the unavailable selected history. Status distinguishes a write fence from unavailable materialization.
+
+**Explicit Start uses current memory, not unavailable history.** 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 no longer block activation. A pre-runtime selection also keeps current accepted same-session memory rather than 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/corrupt storage remains 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.
 
 Missing artifact provenance inside an otherwise complete scope `meta.json` means compilation evidence is unavailable while semantic state remains usable; removing the whole metadata file also removes temporal authority and fails closed. An unavailable registered source path does not prove that durable artifact routing was deleted, and external files are never created. State Flow has no durable push queue or publication-worker lease; failed replication is attempted again only after a later accepted turn. See the complete [filesystem recovery contract](filesystem-recovery.md).
 
@@ -98,7 +119,7 @@ Missing artifact provenance inside an otherwise complete scope `meta.json` means
 
 Canonical scope/runtime files own current materialization and retained hot history regardless of Git availability. Pi checkpoints identify a retained semantic boundary, not a Git commit or arbitrary historical snapshot. Restart and branch restoration fail closed when the selected boundary has expired rather than substituting newer files as the selected past.
 
-After an accepted turn has reconciled its response, Pi 0.87's final actionable `agent_before_settle` boundary may create one best-effort backup commit when Git is available. If the attached branch has an explicitly configured remote/ref, State Flow starts a non-interactive asynchronous push of the exact current commit without force. Settlement does not wait for the network. Within one Pi process, an in-flight push per repository skips overlapping attempts; a later accepted turn retries the latest backup without a durable queue. Session shutdown waits for that repository's in-flight push to close or time out, suppressing push-failure reporting after shutdown begins. Commit or push failure is diagnostic-only; repeated push failures warn once per failure streak and remain locally diagnosable. Git availability never changes semantic authority, step, or retained lineage.
+After an accepted turn has reconciled its response, Pi 0.87's final actionable `agent_before_settle` boundary may create one best-effort backup commit when Git is available. The local attempt completes before settlement continues. Its capture waits cancelably when Pi supplies an operation signal; on Pi 0.87 that signal is absent at settlement, so an occupied backup/storage mutex explicitly defers backup until a later accepted turn instead of trapping Abort. Deferral neither changes memory nor starts a push. Shutdown cancels and drains pending local attempts. If the attached branch has an explicitly configured remote/ref, State Flow starts a non-interactive asynchronous push of the exact current commit without force. Settlement does not wait for the network. Within one Pi process, an in-flight push per repository skips overlapping attempts; a later accepted turn retries the latest backup without a durable queue. Session shutdown waits for that repository's in-flight push to close or time out, suppressing push-failure reporting after shutdown begins. Commit or push failure is diagnostic-only; repeated push failures warn once per failure streak and remain locally diagnosable. Git availability never changes semantic authority, step, or retained lineage.
 
 ### Moving a store and the 0.17 format boundary
 
@@ -108,11 +129,17 @@ Starting with 0.17, State Flow accepts only its canonical checkpoint/tail, tempo
 
 ### Conflicts and interrupted publication
 
-Cooperating canonical writers use file-cohort exclusion, exact prepared bytes, and compare-and-swap checks. These are not kernel-atomic multi-file transactions against nonparticipating writers. A busy writer lock fails before writes and is not silently stolen; reconcile the active or interrupted owner before retrying. Do not delete locks or state directories merely because an operation is slow.
+`patch_state` asynchronously waits for a live cooperating writer, with native cancellation and no ordinary-contention deadline. It then applies authored Global/CWD operations to current canonical values: unmentioned fields survive, overlapping assignments follow successful acceptance order, and correct repeats return `State already current.` without another semantic revision. Session remains private; invalid/unavailable evidence and an independently changed private cohort still fail closed. Do not repeat external actions while memory publication waits.
+
+Final-answer reconciliation also waits cancelably, then saves the response and completed-run lifecycle together over current shared memory. Stop, session/tree changes, shutdown and a superseding answer cancel obsolete waits without modifying newer work. A failed or canceled publication leaves the prior response and unfinished run intact; it never requests a repair inference.
+
+Run preparation and missing-artifact maintenance wait cancelably before the first enabled inference, accepting current shared memory and lifecycle together. If preparation fails, State Flow aborts that native operation rather than sending a rejected or stale draft to the provider; previously accepted memory remains available. Cancellation can leave the new request without a specification checkpoint, so its native conversation is conservatively preserved through idle Stop/reload. Boundary continuation never replays a completed specification.
+
+Telegram shared inspection also awaits exclusion read-only. Backup capture also uses the awaited API, with the no-signal settlement exception described above. Accepted-runtime Stop switches local policy and passive projection immediately, then awaits runtime-only persistence; pending repeats share that operation. Selection/shutdown or a successful Start cancel obsolete Stop work. An available host operation signal can cancel persistence without re-enabling mode; idle commands do not necessarily have that signal. Current-head Start similarly waits before enabling mode, with Stop/selection/shutdown cancellation and any available native operation signal. Startup, tree, auto-start, fork and failed-Stop reload restoration, including Start's initial attachment and fork retry, also await exclusion; until acceptance, mode stays passive and private memory reports the pending selection. Interrupted, malformed or unreadable locks are never stolen. Reconcile the owner rather than deleting locks or state directories merely because an operation is slow. File-cohort exclusion, exact prepared bytes and compare-and-swap checks are not kernel-atomic multi-file transactions against nonparticipating writers.
 
 Fatal process termination can leave an incomplete canonical file cohort. Before repair, quiesce all store writers and preserve the complete store plus selected Pi retained-boundary references. Reconcile exact files against the last complete checkpoint/tail/metadata cohort; no automatic crash repair or power-loss durability is promised. Git backup has no semantic recovery authority.
 
-An untouched shared scope may be adopted from newer proven live state at a fresh origin. A patch that actually changes an advanced shared scope fails with a named conflict instead of silently overwriting it. Rollback restores only bytes still matching that publisher's output and preserves detected external changes. See [performance evidence](performance.md) for measured contention and the [acceptance map](temporal-acceptance.md) for the tested boundaries; the [backlog](../BACKLOG.md) owns open implementation work.
+Independently valid shared streams may require a fresh composed origin without inventing cross-writer history. Authored patches use that current basis; raw precomputed replay still refuses an advanced target instead of applying stale normalized changes. Rollback restores only bytes still matching that publisher's output and preserves detected external changes. See [performance evidence](performance.md) for measured contention and the [acceptance map](temporal-acceptance.md) for the tested boundaries; the [backlog](../BACKLOG.md) owns open implementation work.
 
 ## Memory and source acquisition
 

package/node_modules/@llblab/pi-state-flow/index.ts

@@ -121,6 +121,7 @@ export {
   type StateScope,
   type TerminalTransition
 } from "./lib/state.ts";
+export { PublicationBusyError } from "./lib/storage.ts";
 export {
   buildStateFlowSectionView,
   createStateFlowTelegramAdapter,
@@ -131,6 +132,8 @@ export {
   type StateFlowTelegramButton,
   type StateFlowTelegramCallbackContext,
   type StateFlowTelegramControlResult,
+  type StateFlowTelegramInspection,
+  type StateFlowTelegramInspectionPort,
   type StateFlowTelegramLoader,
   type StateFlowTelegramModules,
   type StateFlowTelegramPort,

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

@@ -204,11 +204,11 @@ export function isArtifactMetadata(value: unknown): value is ArtifactMetadata {
 	}
 }
 
-export function validateArtifactRegistry(value: unknown): asserts value is ArtifactRegistry {
+export function validateArtifactRegistry(value: unknown, context = "artifacts"): asserts value is ArtifactRegistry {
 	if (!isObject(value)) throw new Error("Artifacts must be a path-keyed JSON object");
 	for (const [path, metadata] of Object.entries(value)) {
 		if (path.trim().length === 0) throw new Error("Artifact path keys must be non-empty");
-		validateArtifactMetadata(metadata, path);
+		validateArtifactMetadata(metadata, `${context}[${JSON.stringify(path)}]`);
 	}
 }
 
@@ -368,7 +368,7 @@ export function compileArtifact(update: ArtifactCompilationUpdate): CompiledArti
 	// Timestamps are runtime evidence; the model-visible entry never retains them.
 	const semantic = structuredClone(update.output) as ArtifactMetadata;
 	delete semantic.compiled_at;
-	validateArtifactMetadata(semantic, update.source.path);
+	validateArtifactMetadata(semantic, `${update.source.scope ? `${update.source.scope}.` : ""}artifacts[${JSON.stringify(update.source.path)}]`);
 	return {
 		semantic,
 		provenance: {
@@ -441,11 +441,11 @@ export function updateArtifactRegistry(
 const RUNTIME_ARTIFACT_FIELDS = [...MODEL_FORBIDDEN_PROVENANCE_FIELDS, "compiled_at", "hint"] as const;
 
 /** Validate authored fields only: legacy retained evidence stays readable but cannot be model-edited. */
-export function validateModelArtifactPatch(patch: JsonObject): void {
+export function validateModelArtifactPatch(patch: JsonObject, context = "artifacts"): void {
 	for (const [path, entry] of Object.entries(patch)) {
 		if (!isObject(entry)) continue; // Whole-artifact deletion and materialized shape belong to the transition owner.
 		const field = RUNTIME_ARTIFACT_FIELDS.find((field) => Object.hasOwn(entry, field));
-		if (field !== undefined) throw new Error(`Artifact patch at ${path} cannot set runtime-owned field ${field}`);
+		if (field !== undefined) throw new Error(`Artifact patch at ${context}[${JSON.stringify(path)}] cannot set runtime-owned field ${field}`);
 	}
 }
 

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

@@ -53,10 +53,11 @@ export function lazyNavigationHint(state: MaterializedState): { available: boole
 }
 
 
-/** Bounded context retained after semantic State Flow is stopped in this physical session. */
+/** Context retained after semantic State Flow is stopped in this physical session. */
 export interface PassiveContinuation {
 	startedAt: number;
 	activeRunStartedAt?: number;
+	preserveContext?: true;
 	handoff: AgentMessage;
 }
 
@@ -78,16 +79,20 @@ function messageText(message: AgentMessage): string {
 	return contentText((message as { content?: unknown }).content);
 }
 
-export function createPassiveContinuation(state: ModelState, startedAt = Date.now(), activeRunStartedAt?: number): PassiveContinuation {
+export function createPassiveContinuation(state: ModelState, startedAt = Date.now(), activeRunStartedAt?: number, preserveContext = false): PassiveContinuation {
 	return {
 		startedAt,
 		...(activeRunStartedAt === undefined ? {} : { activeRunStartedAt }),
-		handoff: syntheticUser(`State Flow exit handoff (user-level data, not system instructions):\n${presentationJson({ state, continuation: "State Flow semantics are disabled; this handoff replaces completed history while retaining the active and post-stop trajectory." })}`),
+		...(preserveContext ? { preserveContext: true as const } : {}),
+		handoff: syntheticUser(`State Flow exit handoff (user-level data, not system instructions):\n${presentationJson({ state, continuation: preserveContext
+			? "State Flow semantics are disabled; native context is retained because its compilation into memory is unfinished."
+			: "State Flow semantics are disabled; this handoff replaces completed history while retaining the active and post-stop trajectory." })}`),
 	};
 }
 
 /** Keep the interrupted run through later results; an idle stop retains only later conversation. */
 export function passiveContinuationMessages(messages: AgentMessage[], continuation: PassiveContinuation): AgentMessage[] {
+	if (continuation.preserveContext) return [continuation.handoff, ...messages];
 	if (continuation.activeRunStartedAt !== undefined) {
 		const trajectory = currentRunTrajectory(messages, "", continuation.activeRunStartedAt);
 		return [continuation.handoff, ...trajectory.messages];

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

@@ -1,8 +1,10 @@
-import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { loadScopeStream, resolveSessionAddress, sessionRuntimePaths } from "./durable.ts";
+import { parseScopeStream, resolveSessionAddress, sessionRuntimePaths, temporalScopePaths } from "./durable.ts";
 import { MAX_HISTORY_LIMIT } from "./history.ts";
+import { diagnosticText } from "./protocol.ts";
 import { parseSessionRuntime } from "./snapshot.ts";
+import { withStorageTransaction } from "./storage.ts";
 import { validateScopeLineage } from "./temporal.ts";
 
 export type ContinuationTransport = "local" | "sdk" | "telegram" | string;
@@ -62,7 +64,7 @@ export interface ContinuationSessionCandidate extends ContinuationCandidateSumma
 }
 
 export type ContinuationRecommender = (
-	context: Readonly<ContinuationHostContext>,
+	context: Readonly<ContinuationHostContext>, signal?: AbortSignal,
 ) => ContinuationRecommendation | Promise<ContinuationRecommendation>;
 
 /**
@@ -115,7 +117,9 @@ export async function resolveContinuationStartup(
 	context: ContinuationHostContext,
 	intent: ContinuationHostIntent,
 	recommend: ContinuationRecommender,
+	signal?: AbortSignal,
 ): Promise<ContinuationStartupDecision> {
+	signal?.throwIfAborted();
 	switch (intent.kind) {
 		case "new":
 			return { action: "new", reason: "explicit-new" };
@@ -127,8 +131,11 @@ export async function resolveContinuationStartup(
 			return { action: "native", mode: "continue-recent" };
 		case "no-session":
 			return { action: "native", mode: "no-session" };
-		case "default":
-			return recommend(Object.freeze({ ...context }));
+		case "default": {
+			const recommendation = await recommend(Object.freeze({ ...context }), signal);
+			signal?.throwIfAborted();
+			return recommendation;
+		}
 	}
 }
 
@@ -207,55 +214,65 @@ export function discoverNativeSessionHeaders(sessionDir: string): { headers: Nat
 	return { headers, invalid };
 }
 
-function readRegular(path: string): string | undefined {
-	if (!existsSync(path)) return undefined;
-	if (!lstatSync(path).isFile()) throw new Error("State Flow continuation provenance must be a regular file");
-	return readFileSync(path, "utf8");
-}
-
-/** Inspect only exact current runtime provenance; never initialize, migrate, lock, checkout, or publish. */
-export function inspectStateFlowContinuationProvenance(
-	header: NativeSessionHeader,
+/** Await one exact canonical cohort; never read transcript bodies, initialize, or publish. */
+export async function inspectStateFlowContinuationProvenance(
+	header: Readonly<NativeSessionHeader>,
 	repositoryRoot: string,
-): Pick<ContinuationCandidateProvenance, "stateFlow" | "reason"> {
-	const sessionKey = resolveSessionAddress(header.file, header.id, header.timestamp).key;
-	const paths = sessionRuntimePaths(header.cwd, header.id, repositoryRoot, sessionKey);
+	signal?: AbortSignal,
+): Promise<Pick<ContinuationCandidateProvenance, "stateFlow" | "reason">> {
+	signal?.throwIfAborted();
+	const selected = { ...header };
+	const root = resolve(repositoryRoot);
+	const sessionKey = resolveSessionAddress(selected.file, selected.id, selected.timestamp).key;
+	const paths = sessionRuntimePaths(selected.cwd, selected.id, root, sessionKey);
+	const absent = { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
 	try {
-		const config = readRegular(paths.config);
-		const runtimeSource = readRegular(paths.runtime);
-		const meta = readRegular(paths.meta);
-		if (config === undefined && runtimeSource === undefined && meta === undefined) {
-			return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
-		}
-		const runtime = parseSessionRuntime(config, runtimeSource, header.cwd, header.id);
-		if (!runtime) return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
-		if (!runtime.config.enabled) return { stateFlow: { enabled: false, restorable: true }, reason: "State Flow stopped on selected runtime" };
-		const global = loadScopeStream(header.cwd, header.id, "global", repositoryRoot, sessionKey);
-		const cwd = loadScopeStream(header.cwd, header.id, "cwd", repositoryRoot, sessionKey);
-		const session = loadScopeStream(header.cwd, header.id, "session", repositoryRoot, sessionKey);
-		if (!global || !cwd || !session) throw new Error("incomplete canonical temporal cohort");
-		// Shared streams are current, independently validated by their codecs, not frozen to this session's history.
-		validateScopeLineage(session, "session", runtime.meta.lineage, MAX_HISTORY_LIMIT);
-		return { stateFlow: { enabled: true, restorable: true }, reason: "canonical session lineage is valid beside current shared streams" };
+		if (!lstatSync(root, { throwIfNoEntry: false })) return absent;
+		const result = await withStorageTransaction(root, (tx) => {
+			const files = new Map(tx.capture(selected.cwd, selected.id, root, sessionKey).files.map((file) => [file.path, file.content]));
+			const privatePaths = temporalScopePaths(selected.cwd, selected.id, "session", root, sessionKey);
+			if ([paths.config, paths.runtime, privatePaths.meta, privatePaths.checkpoint, privatePaths.patches].every((path) => files.get(path) === undefined)) return absent;
+			const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), selected.cwd, selected.id);
+			if (!runtime) throw new Error("incomplete canonical session runtime");
+			if (!runtime.config.enabled) return { stateFlow: { enabled: false, restorable: true }, reason: "State Flow stopped on selected runtime" };
+			const streams = (["global", "cwd", "session"] as const).map((scope) => {
+				const owned = temporalScopePaths(selected.cwd, selected.id, scope, root, sessionKey);
+				return parseScopeStream(files.get(owned.checkpoint), files.get(owned.patches), scope,
+					scope === "cwd" ? selected.cwd : undefined, files.get(owned.meta));
+			});
+			if (streams.some((stream) => stream === undefined)) throw new Error("incomplete canonical temporal cohort");
+			// Shared streams remain current and independently valid; only the private stream binds to this lineage.
+			validateScopeLineage(streams[2]!, "session", runtime.meta.lineage, MAX_HISTORY_LIMIT);
+			return { stateFlow: { enabled: true, restorable: true }, reason: "canonical session lineage is valid beside current shared streams" };
+		}, signal);
+		signal?.throwIfAborted();
+		return result;
 	} catch (error) {
-		return { stateFlow: { enabled: true, restorable: false }, reason: `State Flow runtime is ineligible: ${error instanceof Error ? error.message : String(error)}` };
+		signal?.throwIfAborted();
+		return { stateFlow: { enabled: true, restorable: false }, reason: `State Flow runtime is ineligible: ${diagnosticText(error)}` };
 	}
 }
 
-export function buildContinuationCandidates(
+export async function buildContinuationCandidates(
 	headers: readonly NativeSessionHeader[],
-	inspect: (header: Readonly<NativeSessionHeader>) => ContinuationCandidateProvenance | undefined,
-): ContinuationSessionCandidate[] {
+	inspect: (header: Readonly<NativeSessionHeader>, signal?: AbortSignal) => ContinuationCandidateProvenance | undefined | Promise<ContinuationCandidateProvenance | undefined>,
+	signal?: AbortSignal,
+): Promise<ContinuationSessionCandidate[]> {
+	signal?.throwIfAborted();
+	const selected = headers.map((header) => Object.freeze({ ...header }));
 	const candidates: ContinuationSessionCandidate[] = [];
-	for (const header of headers) {
-		const provenance = inspect(Object.freeze({ ...header }));
+	for (const header of selected) {
+		signal?.throwIfAborted();
+		const provenance = await inspect(header, signal);
+		signal?.throwIfAborted();
 		if (!provenance) continue;
 		candidates.push({
+			...provenance,
+			stateFlow: { ...provenance.stateFlow },
 			sessionFile: header.file,
 			sessionId: header.id,
 			lastActivity: header.lastActivity,
 			cwd: header.cwd,
-			...provenance,
 		});
 	}
 	return candidates;