@llblab/pi-state-flow 0.27.6 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -18,10 +18,10 @@ The [relocation ledger](docs/agent-contract-relocation.md) maps every pre-compac
18
18
 
19
19
  ## Publication and lifecycle
20
20
 
21
- - Keep one Strategy/Tactics model/API across metadata3 core cohorts and metadata4 retained-module cohorts. Translate declared legacy v1/v2 cohorts before filtering; reject raw collisions and target-format retired roots. Only owned semantic acceptance may convert, after verified exact-byte backup and CAS; inspection and runtime-only mode persistence cannot. Preserve revisions/causal identities and opaque recovery bytes; semantic decoding must reject invalid UTF-8. Quiesce unsupported old writers. See [migration and backup](docs/usage.md#moving-a-store-and-supported-formats).
22
- - Treat canonical scope files as semantic authority and Git only as optional backup. Classify complete, wholly absent, partial and malformed cohorts before recovery; absent shared pairs may initialize only under accepted authority, while incomplete/private evidence fails closed. Never repair through ad-hoc writes. See [storage recovery](docs/usage.md#storage-and-recovery) and [transaction rule](docs/filesystem-recovery.md#transaction-rule).
21
+ - Keep one Strategy/Tactics model/API across metadata3 core cohorts and metadata4 retained-module cohorts. Since 1.0.0, retired metadata v1/v2 cohorts are refused with an actionable message instead of translated, and `RetiredSemanticFormatError` keeps self-healing from treating a known old format as corruption; target-format retired roots stay reserved. Only owned semantic acceptance may convert or upgrade (lifecycle v1, module descriptors), after verified exact-byte backup and CAS; inspection and runtime-only mode persistence cannot. Preserve revisions/causal identities and opaque recovery bytes; semantic decoding must reject invalid UTF-8. Quiesce unsupported old writers. See [migration and backup](docs/usage.md#moving-a-store-and-supported-formats).
22
+ - Treat canonical scope files as semantic authority and Git only as optional backup. Classify complete, wholly absent, partial and malformed cohorts before recovery; absent shared pairs may initialize only under accepted authority. Unrecoverable owners self-heal only through `lib/healing.ts`: after a failed acquisition, under store exclusion and never behind a live writer, quarantine the owner's exact bytes privately, reset only that owner to wholly absent and announce it to both operator and model; never silently. Filesystem, lock, cancellation and foreign-identity failures stay fail-closed. Never repair through other ad-hoc writes. See [self-healing](docs/filesystem-recovery.md#self-healing). See [storage recovery](docs/usage.md#storage-and-recovery) and [transaction rule](docs/filesystem-recovery.md#transaction-rule).
23
23
  - Keep exact regular-file, byte-CAS and lock-serialized publication with cancelable waits, single-use callback-scoped capabilities and guarded rollback. Never hold exclusion across inference, source acquisition or Git; do not steal interrupted locks, claim kernel-atomic multi-file publication or promise power-loss durability. See [asynchronous transaction](docs/architecture.md#asynchronous-storage-transaction) and [durability boundary](docs/filesystem-recovery.md#power-loss-durability).
24
- - Attach Off branches through native policy bookkeeping only, deferring memory acquisition and recovery diagnostics until explicit Passive/Active. Preserve pending Off forks across cold reload with child-owned native markers, without reading the parent header/store until acquisition. Memory never depends on the Pi step: it is the current same-session JSON state, advanced only by accepted `state_flow_patch`/lifecycle publications. Startup, reload, resume and tree navigation validate and accept current same-session memory; native checkpoints supply only mode and run lifecycle, never a revision to rewind to. A fork copies its parent's current memory into a fresh child owner. Never substitute empty, Git, foreign or fabricated memory when current files are missing, corrupt or contradictory. Only accepted candidates install cache, checkpoint and mode. Unreadable current memory under Active retains Active policy, visibly reports `active (blocked)` and fences live inference through public Abort until accepted Active/Passive or explicit Off; never silently expose native history or an inactive indicator as fallback. See [Pi lifecycle](docs/architecture.md#pi-lifecycle) and [fork contract](docs/fork-contract.md).
24
+ - Attach Off branches through native policy bookkeeping only, deferring memory acquisition and recovery diagnostics until explicit Passive/Active. Preserve pending Off forks across cold reload with child-owned native markers, without reading the parent header/store until acquisition. Memory never depends on the Pi step: it is the current same-session JSON state, advanced only by accepted `state_flow_patch`/lifecycle publications. Startup, reload, resume and tree navigation validate and accept current same-session memory; native checkpoints supply only mode and run lifecycle, never a revision to rewind to. A fork copies its parent's current memory into a fresh child owner. Never substitute Git, foreign or fabricated memory; missing or unreadable current files restart only the affected owner from visible empty memory through self-healing, never silently. Only accepted candidates install cache, checkpoint and mode. Memory that stays unavailable after healing (unhealable causes) under Active retains Active policy, visibly reports `active (blocked)` and fences live inference through public Abort until accepted Active/Passive or explicit Off; never silently expose native history or an inactive indicator as fallback. See [Pi lifecycle](docs/architecture.md#pi-lifecycle) and [fork contract](docs/fork-contract.md).
25
25
  - Persist each material semantic change and its affected revisions exactly once, including accepted Session responses. Optional settled-turn Git backup may capture only already-accepted owned files, leave unrelated index/worktree data intact and push without force or semantic side effects. Defer busy backup when the host provides no settlement operation signal rather than blocking Abort; never move it to `turn_end` or add a durable push queue. Off cancels owned captures/pushes and suppresses late reporting; normal agent-operation completion must not cancel an independently admitted push, and foreign callers' pushes retain ownership. See [optional Git backup](docs/architecture.md#optional-git-backup).
26
26
  - Accept one atomic `state_flow_patch` cohort across supplied scopes against current shared memory; reject empty scopes, unknown/retired grammar and model-authored `response`. Correct no-ops create no transition. Enforce the single-call inference barrier before sibling tools execute and retain conservative model-facing reconciliation when a result cannot be predicted. See [model tools](docs/architecture.md#model-tools) and [Pi lifecycle](docs/architecture.md#pi-lifecycle).
27
27
  - Reconcile the actual accepted ordinary answer at `turn_end` with response-owned cancellation and one accepted lifecycle publication; do not request private repair inference, ceremonial finalization patches or roll back accepted memory after cancellation. See [Pi lifecycle](docs/architecture.md#pi-lifecycle).
package/BACKLOG.md CHANGED
@@ -11,8 +11,12 @@ These remain outstanding separately from release-local 0.27.2 acceptance; neithe
11
11
  - [ ] **Live-model semantic-memory comparison — authorization-gated, not run.** Use the [existing corpus, runner and rubric](docs/semantic-memory-evaluation.md), preserved baseline source and actual target digests. Include feasible flat-versus-scoped errors/retries/quality/cost comparisons; disclose provider/model drift and unsupported comparisons. Unblocker: an explicitly authorized normal inference route, pinned model/provider/reasoning and bounded request/token/time limits. Do not scrape/copy credentials or relabel faux calibration as model evidence.
12
12
  - [ ] **Installed-client compatibility smoke — operator/environment-gated, not established by CI.** With explicit installation/reload authority and an isolated store/session, check the intended TUI/Telegram client's mode controls, captured selection, inspection and unavailable-owner presentation against [compatibility boundaries](docs/compatibility.md). Record exact client/SDK/package identities and observed results; scripted/native fixtures do not certify live reachability, rendering or every newer SDK.
13
13
 
14
+ ## Compatibility window
15
+
16
+ - The `contract`/`working` converter was removed in 1.0.0 and both retired root names stay reserved. A store still in metadata v1/v2 must be opened once with a State Flow 0.x release, where owned Active/Start acceptance converts it after a verified backup. The operator's active store was inventoried before the release and contained no legacy cohorts.
17
+
14
18
  ## Scope and authorization limits
15
19
 
16
- - Preserve legacy conversion and retired-root reservations throughout State Flow 0.x, with the settled 1.0.0 cutoff and explicit unsupported-version refusal; see the [migration support policy](docs/semantic-compatibility-decision.md#implementation-direction-and-reserved-names). No converter-removal or new migration task is implied.
20
+ - Preserve explicit unsupported-version refusal and retired-root reservations; see the [migration support policy](docs/semantic-compatibility-decision.md#implementation-direction-and-reserved-names). No further converter, downgrade or live-store repair is implied.
17
21
  - New planes/scopes, changed public module semantics, dynamic loading/sandboxing, background inference, storage formats, speculative performance work and broad redesign remain outside consolidation. They are not dormant implementation promises.
18
22
  - Live-store conversion and all other release/rollout actions require their normal explicit authorization. Temporary evidence belongs under ignored `temp/`, not a parallel task queue.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,17 @@
4
4
 
5
5
  ## Unreleased
6
6
 
7
+ ## 1.0.0: Automatic Recovery, No Legacy Conversion
8
+
9
+ - `Visible self-healing`: An owner whose canonical files cannot be decoded, or a boundary whose session memory is missing, no longer blocks forever. After a failed acquisition, State Flow quarantines the exact bytes privately in `<store>-quarantine/`, resets only that owner to empty memory, retries once and tells the operator, the model and the local log. Healthy owners stay untouched; filesystem, lock, cancellation and foreign-identity failures stay fail-closed.
10
+ - `Retired formats refused`: The temporary `contract`/`working` converter is gone. A store still in metadata v1/v2 now fails with an actionable message instead of being converted; open it once with a State Flow 0.x release first. Both retired root names stay reserved, and self-healing never resets a known old format.
11
+ - `Empty stores read as empty`: A branch without accepted memory reads absent shared values as `null` instead of an unavailable runtime; an uncreated Session says the first accepted patch creates it.
12
+
13
+ ## 0.28.0: Visible Self-Healing Memory
14
+
15
+ - `Visible self-healing`: An owner whose canonical files cannot be decoded, or a boundary whose session memory is missing, no longer blocks forever. After a failed acquisition, State Flow quarantines the exact bytes privately in `<store>-quarantine/`, resets only that owner to empty memory, retries once and tells the operator, the model and the local log. Healthy owners stay untouched; filesystem, lock, cancellation and foreign-identity failures stay fail-closed.
16
+ - `Empty stores read as empty`: A branch without accepted memory reads absent shared values as `null` instead of an unavailable runtime; an uncreated Session says the first accepted patch creates it.
17
+
7
18
  ## 0.27.6: Namespaced Memory Tools
8
19
 
9
20
  - `Canonical tool names`: Advertises `state_flow_read` and `state_flow_patch`, retaining explicit unadvertised `read_state`/`patch_state` dispatch compatibility without rewriting historical calls, stores or conversion policy. Skills, prompts, examples and packaged guidance use the canonical names.
package/README.md CHANGED
@@ -225,7 +225,7 @@ The default store is `~/.pi/agent/state-flow/`, independent of registered source
225
225
  - A new session gets its own private layer only when Session acquisition is admitted; shared-only selections create no hidden private semantics.
226
226
  - Supported native forks inherit captured policy and copy parent-**current** Session memory into a fresh child owner when admitted, without changing parent-private data. Off or Session-excluded forks defer private acquisition; an acquired child never recopies.
227
227
  - Explicit Active or Passive accepts the validated current memory of that same session; modes stay stable.
228
- - Missing, malformed or contradictory current files, unsafe fork copying and concurrent writes remain fenced and are never replaced by empty or foreign memory.
228
+ - Missing, malformed or contradictory current files self-heal visibly: the broken owner's bytes are quarantined, only that owner restarts empty, and both operator and agent are told. Unsafe fork copying, concurrent writes and foreign-owner evidence remain fenced and are never replaced by foreign memory.
229
229
 
230
230
  See [fork support](docs/usage.md#fork-support-and-limits) and [storage recovery](docs/usage.md#storage-and-recovery).
231
231
 
@@ -4,7 +4,7 @@ import { basename, dirname, join, relative, resolve, sep } from "node:path";
4
4
  import { getAgentDir } from "@earendil-works/pi-coding-agent";
5
5
  import { parseArtifactProvenanceRegistry, serializeArtifactProvenanceRegistry, } from "./artifact.js";
6
6
  import { MAX_HISTORY_LIMIT } from "./history.js";
7
- import { prepareSerializedScopeMigration } from "./migration.js";
7
+ import { prepareSerializedScopeMigration, refuseRetiredSemanticVersion } from "./migration.js";
8
8
  import { canonicalJson, isJsonValue, isObject } from "./json.js";
9
9
  import { validateScopeStream, validateTemporalState } from "./temporal.js";
10
10
  import { assertRetainedModules, validateRetainedModules } from "./semantic-module.js";
@@ -46,7 +46,7 @@ export function serializeScopeStream(stream, scope, cwdIdentity) {
46
46
  };
47
47
  }
48
48
  function isSupportedScopeMetadataVersion(version) {
49
- return version === 1 || version === 2 || version === 3 || version === 4;
49
+ return version === 3 || version === 4;
50
50
  }
51
51
  /** Distinguish a wholly absent semantic cohort from partial or malformed surviving authority. */
52
52
  export function classifyScopeStream(checkpointSource, patchesSource, scope, expectedCwd, metaSource) {
@@ -77,6 +77,8 @@ export function classifyScopeStream(checkpointSource, patchesSource, scope, expe
77
77
  throw new Error(`Unsupported State Flow ${scope} storage format`);
78
78
  }
79
79
  const metadata = parseMetadataDocument(metaSource, `State Flow ${scope} metadata`);
80
+ if (metadata.version === 1 || metadata.version === 2)
81
+ refuseRetiredSemanticVersion(metadata.version);
80
82
  if (!isSupportedScopeMetadataVersion(metadata.version))
81
83
  throw new Error(`Unsupported State Flow ${scope} metadata version`);
82
84
  // In Unicode mode this range matches lone UTF-16 surrogates, not valid pairs or JSON escapes.
@@ -31,7 +31,8 @@ import { compactStatus, detailedStatus, STATUS_KEY } from "./status.js";
31
31
  import { PublicationBusyError, loadSelectedFileCohort } from "./storage.js";
32
32
  import { captureScopeSelection, DEFAULT_SCOPE_SELECTION, parseScopeSelectionArguments, scopeSelectionArgumentCompletions } from "./selection.js";
33
33
  import { createStateFlowTelegramAdapter } from "./telegram.js";
34
- import { readTemporalScopes, temporalScopeRevisions } from "./temporal.js";
34
+ import { createSelectedTemporalState, readTemporalScopes, temporalScopeRevisions } from "./temporal.js";
35
+ import { describeHealedScopes, healSelectedStore, HealNotice } from "./healing.js";
35
36
  import { commitSelectedTransition, stageSelectedScopePatches, stageSelectedScopedTransition } from "./transition.js";
36
37
  export { formatPatchStateArguments };
37
38
  export const PATCH_STATE_TOOL_NAME = "state_flow_patch";
@@ -63,6 +64,7 @@ export default function stateFlowExtension(pi, options = {}) {
63
64
  let effectiveState = {};
64
65
  let branchStartsWithoutRuntime = false;
65
66
  let modePersistenceError;
67
+ const healNotice = new HealNotice();
66
68
  /** One pending inactive-mode persistence; later inactive choices coalesce until it publishes. */
67
69
  const inactivePersistence = new OwnedOperationSlot();
68
70
  const startActivation = new OwnedOperationSlot();
@@ -111,6 +113,40 @@ export default function stateFlowExtension(pi, options = {}) {
111
113
  function notifyProblem(ctx, message, level) {
112
114
  ctx.ui.notify(conciseDiagnostic(message), level);
113
115
  }
116
+ /** Announce a reset to both operator and model; a reset is never silent. */
117
+ function announceHealing(ctx, message) {
118
+ healNotice.announce(message);
119
+ diagnosticWriter.recordSelfHeal(sessionAddress(ctx).id, ctx.cwd, message);
120
+ ctx.ui.notify(message, "warning");
121
+ }
122
+ /** Quarantine unrecoverable selected owners before acceptance; unhealable failures keep failing closed downstream. */
123
+ async function healCurrentStore(ctx, wanted, signal) {
124
+ const address = sessionAddress(ctx);
125
+ let result;
126
+ try {
127
+ result = await healSelectedStore({ cwd: ctx.cwd, sessionId: address.id, sessionKey: address.key, selection: wanted,
128
+ historyLimit: config.historyLimit, root: repositoryRoot }, signal);
129
+ }
130
+ catch (error) {
131
+ if (signal.aborted)
132
+ throw error;
133
+ return undefined;
134
+ }
135
+ if (result.healed.length)
136
+ announceHealing(ctx, `State Flow self-healed: ${describeHealedScopes(result.healed)}`);
137
+ return result;
138
+ }
139
+ /** A pre-runtime branch with no stored cohort reads as empty memory instead of an unavailable runtime. */
140
+ function emptyPreRuntimeView(wanted) {
141
+ if (!branchStartsWithoutRuntime || snapshot.config.mode === "off" || snapshot.meta.validation?.attempt === 0
142
+ || branchRestoration.current?.awaitingAcceptance)
143
+ return undefined;
144
+ // Shared absence is empty reality; unacquired Session keeps its explicit selected-unavailable diagnostic.
145
+ const shared = wanted.filter(scope => scope !== "session");
146
+ if (!shared.length)
147
+ return undefined;
148
+ return createSelectedTemporalState(Object.fromEntries(shared.map(scope => [scope, {}])), captureScopeSelection(shared), "empty:pre-runtime", config.historyLimit);
149
+ }
114
150
  function notifyActiveContext(message) {
115
151
  try {
116
152
  if (activeContext)
@@ -659,7 +695,30 @@ export default function stateFlowExtension(pi, options = {}) {
659
695
  // attachBranch releases its own ownership; settlement only drains it for shutdown.
660
696
  return branchRestoration.track(pending, attachBranch(ctx, pending, selection, sessionStartReason, notifyRecovery, skipped), false);
661
697
  }
662
- async function attachBranch(ctx, pending, selection, reason, notifyRecovery, skipped) {
698
+ /**
699
+ * After a failed attachment, heal selected owners once. Returns the selection to retry, or undefined when healing
700
+ * changed nothing; expected-but-absent session memory restarts visibly from empty memory.
701
+ */
702
+ async function healBranchSelection(ctx, selection, requestedMode, signal) {
703
+ if (selection.kind === "settled")
704
+ return undefined;
705
+ const healing = await healCurrentStore(ctx, nativeScopeSelection(ctx), signal).catch(() => undefined);
706
+ if (!healing || signal.aborted || shuttingDown)
707
+ return undefined;
708
+ if (healing.lifecycleAbsent && (selection.kind === "attach" || selection.kind === "current")) {
709
+ const mode = requestedMode ?? (selection.kind === "current" ? selection.mode : selection.checkpoint.mode);
710
+ if (mode === "off")
711
+ return undefined;
712
+ if (!healing.healed.some(item => item.scope === "session")) {
713
+ announceHealing(ctx, "State Flow self-healed: session memory files were missing and session memory restarts empty");
714
+ }
715
+ branchStartsWithoutRuntime = true;
716
+ modePersistenceError = undefined;
717
+ return mode === "active" ? { kind: "auto-start" } : { kind: "pre-runtime", mode };
718
+ }
719
+ return healing.healed.length > 0 ? selection : undefined;
720
+ }
721
+ async function attachBranch(ctx, pending, selection, reason, notifyRecovery, skipped, healed = false) {
663
722
  const placeholder = runtime;
664
723
  let selected = runtime;
665
724
  const wanted = nativeScopeSelection(ctx);
@@ -850,6 +909,13 @@ export default function stateFlowExtension(pi, options = {}) {
850
909
  notifyProblem(ctx, `State Flow memory restored; lifecycle update failed: ${diagnosticText(error)}`, "warning");
851
910
  return;
852
911
  }
912
+ if (!isCurrent())
913
+ return;
914
+ const retry = healed ? undefined : await healBranchSelection(ctx, selection, pending.requestedMode, signal);
915
+ if (retry && isCurrent()) {
916
+ pending.awaitingAcceptance = retry.kind !== "settled" && retry.kind !== "current";
917
+ return await attachBranch(ctx, pending, retry, reason, notifyRecovery, skipped, true);
918
+ }
853
919
  if (!isCurrent())
854
920
  return;
855
921
  failSelection(error);
@@ -864,7 +930,7 @@ export default function stateFlowExtension(pi, options = {}) {
864
930
  if (snapshot.config.mode === "off" || isActive() || readableView() || snapshot.meta.validation?.attempt === 0 || !branchStartsWithoutRuntime)
865
931
  return;
866
932
  // Only a proven pre-runtime Passive branch may observe shared owners without private acquisition.
867
- const passive = await loadPassiveView(ctx, signal, isCurrent, notifyRecovery);
933
+ const passive = await loadPassiveView(ctx, signal, isCurrent, notifyRecovery, !healed);
868
934
  if (passive === undefined)
869
935
  return;
870
936
  assertCurrent();
@@ -887,16 +953,27 @@ export default function stateFlowExtension(pi, options = {}) {
887
953
  }
888
954
  }
889
955
  /** Load current shared memory for passive projection without initializing or publishing it. */
890
- async function loadPassiveView(ctx, signal, isCurrent, notify) {
956
+ async function loadPassiveView(ctx, signal, isCurrent, notify, heal = true) {
891
957
  const wanted = nativeScopeSelection(ctx), shared = wanted.filter(scope => scope !== "session");
892
958
  if (!shared.length)
893
959
  return undefined;
894
960
  const passive = createRuntime(ctx);
961
+ const observe = () => passive.refreshSelectedShared(captureScopeSelection(shared), () => {
962
+ if (!isCurrent() || !sameJson(nativeScopeSelection(ctx), wanted))
963
+ throw new Error("State Flow observation selection changed");
964
+ }, signal);
895
965
  try {
896
- await passive.refreshSelectedShared(captureScopeSelection(shared), () => {
897
- if (!isCurrent() || !sameJson(nativeScopeSelection(ctx), wanted))
898
- throw new Error("State Flow observation selection changed");
899
- }, signal);
966
+ try {
967
+ await observe();
968
+ }
969
+ catch (error) {
970
+ if (!heal || signal.aborted || !isCurrent())
971
+ throw error;
972
+ const healing = await healCurrentStore(ctx, captureScopeSelection(shared), signal).catch(() => undefined);
973
+ if (!healing?.healed.length)
974
+ throw error;
975
+ await observe();
976
+ }
900
977
  }
901
978
  catch (error) {
902
979
  if (isCurrent() && !signal.aborted && notify && !modePersistenceError)
@@ -1004,12 +1081,13 @@ export default function stateFlowExtension(pi, options = {}) {
1004
1081
  const requestedPaths = [...(params.paths ?? [params.path])];
1005
1082
  const paths = requestedPaths.map(path => normalizeModelReadPath(path, wanted, config.historyLimit));
1006
1083
  check();
1007
- const view = readableView(selected);
1084
+ const view = readableView(selected) ?? emptyPreRuntimeView(wanted);
1008
1085
  // Wanted policy was checked by normalization; an observational subset is not an exclusion.
1009
1086
  for (const path of paths) {
1010
1087
  const owner = /^(global|cwd|session)(?=\.|\[|$)/.exec(path)?.[1];
1011
1088
  if (owner && !view?.selection.includes(owner))
1012
- throw new Error(`State Flow ${owner}: selected, unavailable`);
1089
+ throw new Error(`State Flow ${owner}: selected, unavailable${branchStartsWithoutRuntime
1090
+ ? "; no memory is stored for it yet, and an accepted state_flow_patch creates it" : ""}`);
1013
1091
  }
1014
1092
  if (!view)
1015
1093
  throw new Error("State Flow temporal runtime is unavailable");
@@ -1280,7 +1358,7 @@ export default function stateFlowExtension(pi, options = {}) {
1280
1358
  }
1281
1359
  }
1282
1360
  /** Explicit Active or Passive accepts validated current same-session memory without claiming unavailable history. */
1283
- async function activateCurrentState(ctx, pending, mode = "active", owns = () => startActivation.current?.controller === pending) {
1361
+ async function activateCurrentState(ctx, pending, mode = "active", owns = () => startActivation.current?.controller === pending, healing) {
1284
1362
  let selected = runtime;
1285
1363
  const wanted = nativeScopeSelection(ctx);
1286
1364
  const sameSession = sessionIdentity(ctx);
@@ -1306,17 +1384,26 @@ export default function stateFlowExtension(pi, options = {}) {
1306
1384
  const retained = selectRetainedCheckpoint(discovery.candidates, config.inactiveMode);
1307
1385
  branchStartsWithoutRuntime = retained.kind === "pre-runtime" || (discovery.candidates.length === 0 && discovery.errors.length === 0);
1308
1386
  }
1387
+ // After a failed attempt, a missing or reset session lifecycle restarts visibly from empty memory instead of blocking forever.
1388
+ const sessionReset = healing?.lifecycleAbsent === true && !forkInitialization && !branchPolicy(ctx).forkPending
1389
+ && !(selected?.cwd === ctx.cwd && selected.sessionKey === activation.sessionKey && selected.selectedView()?.selection.includes("session"));
1390
+ if (sessionReset) {
1391
+ if (!branchStartsWithoutRuntime && !healing.healed.some(item => item.scope === "session")) {
1392
+ announceHealing(ctx, "State Flow self-healed: session memory files were missing and session memory restarts empty");
1393
+ }
1394
+ branchStartsWithoutRuntime = true;
1395
+ }
1309
1396
  // Off activation owns one cancellable current-head publication, not an independent read-only restore.
1310
1397
  const acceptActivation = (current, publish) => {
1311
1398
  signal.throwIfAborted();
1312
1399
  if (!isCurrent())
1313
1400
  throw new Error("State Flow activation selection changed while awaiting publication");
1314
- if (!current && (!active || !branchStartsWithoutRuntime))
1401
+ if (!current && (!(active || sessionReset) || !branchStartsWithoutRuntime))
1315
1402
  throw new Error(snapshot.meta.validation?.error ?? "Current State Flow session memory is unavailable");
1316
1403
  const boundary = deferred && retainsPhysicalSessionProjection(deferred.reason)
1317
1404
  ? branchPolicy(ctx).stop : undefined;
1318
1405
  const bootstrap = hasPriorConversation(ctx.sessionManager.getBranch()) || passiveContinuation !== undefined || boundary !== undefined;
1319
- const activated = !active ? deactivateEpisode(current, "passive")
1406
+ const activated = !active ? deactivateEpisode(current ?? startEpisode(false), "passive")
1320
1407
  : current ? resumeEpisode(current, bootstrap) : startEpisode(bootstrap);
1321
1408
  if (active) {
1322
1409
  // Explicit Start accepts current memory, not the prior run's prompt or repair attempt.
@@ -1389,8 +1476,9 @@ export default function stateFlowExtension(pi, options = {}) {
1389
1476
  acquiredResult = acceptActivation(basis.snapshot, activated => publish(activated));
1390
1477
  } }, publish => { check(); publish(); return acquiredResult; }, signal, true);
1391
1478
  }
1392
- else if (active && branchStartsWithoutRuntime && !acceptedSession && !disposition) {
1393
- const next = startEpisode(hasPriorConversation(ctx.sessionManager.getBranch()) || passiveContinuation !== undefined);
1479
+ else if ((active || sessionReset) && branchStartsWithoutRuntime && !acceptedSession && !disposition) {
1480
+ const started = startEpisode(hasPriorConversation(ctx.sessionManager.getBranch()) || passiveContinuation !== undefined);
1481
+ const next = active ? started : deactivateEpisode(startEpisode(false), "passive");
1394
1482
  result = await activation.withSelectedFirstPatchTransaction(wanted, next, transaction => {
1395
1483
  check();
1396
1484
  if (!branchStartsWithoutRuntime || forkInitialization)
@@ -1405,6 +1493,14 @@ export default function stateFlowExtension(pi, options = {}) {
1405
1493
  catch (error) {
1406
1494
  if (!isCurrent())
1407
1495
  return superseded();
1496
+ if (!accepted && healing === undefined) {
1497
+ // Self-healing is lazy: healthy stores never pay for it, and one retry bounds convergence.
1498
+ const healed = await healCurrentStore(ctx, wanted, signal).catch(() => undefined);
1499
+ if (!isCurrent())
1500
+ return superseded();
1501
+ if (healed && (healed.healed.length > 0 || healed.lifecycleAbsent))
1502
+ return activateCurrentState(ctx, pending, mode, owns, healed);
1503
+ }
1408
1504
  const message = conciseDiagnostic(`${accepted ? `State Flow ${mode}; lifecycle update failed` : active ? "State Flow activation failed" : "State Flow passive acceptance failed"}: ${diagnosticText(error)}`);
1409
1505
  // An unaccepted activation cannot replace retained lifecycle or poison an independent Stop.
1410
1506
  // Attachment owns required-proof unavailability; failed Passive acceptance reports through its caller's fence.
@@ -1862,7 +1958,9 @@ export default function stateFlowExtension(pi, options = {}) {
1862
1958
  // Off removes the owned section, including one contributed before an in-flight mode change.
1863
1959
  const protocol = isActive() ? stateFlowProtocol(snapshot.meta.bootstrap === true, nativeScopeSelection(ctx))
1864
1960
  : passiveMemoryAvailable() ? passiveMemoryProtocol(nativeScopeSelection(ctx)) : undefined;
1865
- return { messages: projectSystemProtocol(event.messages, protocol) };
1961
+ // Only a request that can carry the section consumes the reset notice.
1962
+ const notice = snapshot.config.mode !== "off" && event.messages.some(message => message.role === "system") ? healNotice.project() : undefined;
1963
+ return { messages: projectSystemProtocol(event.messages, [protocol, notice].filter(Boolean).join("\n\n") || undefined) };
1866
1964
  });
1867
1965
  // Optional transport checkpoint: no payload/header inspection or transformation.
1868
1966
  pi.on("before_provider_request", (_event, ctx) => {
@@ -2264,6 +2362,9 @@ export default function stateFlowExtension(pi, options = {}) {
2264
2362
  return { compaction: result };
2265
2363
  });
2266
2364
  pi.on("agent_before_settle", async (_event, ctx) => {
2365
+ // Passive has no response reconciliation: its settled run is the accepted turn for already published patches.
2366
+ if (!shuttingDown && snapshot.config.mode === "passive" && memoryToolsAvailable())
2367
+ backup.markTurnAccepted();
2267
2368
  if (shuttingDown || !memoryToolsAvailable() || !backup.takeSettledTurn())
2268
2369
  return;
2269
2370
  const operationSignal = ctx.signal;
@@ -2302,6 +2403,7 @@ export default function stateFlowExtension(pi, options = {}) {
2302
2403
  }
2303
2404
  });
2304
2405
  pi.on("agent_settled", async (_event, ctx) => {
2406
+ healNotice.settle();
2305
2407
  if (telegramStartPending && !isActive()) {
2306
2408
  telegramStartPending = false;
2307
2409
  await startStateFlow(ctx);
@@ -0,0 +1,47 @@
1
+ import { type ScopeSelection } from "./selection.ts";
2
+ import type { StateScope } from "./state.ts";
3
+ import { type StorageTransaction } from "./storage.ts";
4
+ /** One visible reset: the scope became wholly absent after its exact bytes were quarantined. */
5
+ export interface HealedScope {
6
+ scope: StateScope;
7
+ reason: string;
8
+ quarantine: string;
9
+ }
10
+ /** Healing outcome; `lifecycleAbsent` means this session owns no lifecycle after healing. */
11
+ export interface HealResult {
12
+ healed: HealedScope[];
13
+ lifecycleAbsent: boolean;
14
+ }
15
+ export interface HealRequest {
16
+ cwd: string;
17
+ sessionId: string;
18
+ sessionKey: string;
19
+ selection: ScopeSelection;
20
+ historyLimit: number;
21
+ root: string;
22
+ /** Wall-clock source for deterministic tests. */
23
+ now?: () => Date;
24
+ }
25
+ /**
26
+ * Only semantic decoding/validation failures are healable. Filesystem, lock, cancellation and
27
+ * foreign-owner identity failures keep failing closed because resetting cannot fix them safely.
28
+ */
29
+ export declare function isHealableCorruption(error: unknown): boolean;
30
+ /**
31
+ * Converge the selected owners to a loadable store: decode each owner independently, then the
32
+ * complete selected cohort. A broken owner is quarantined and becomes wholly absent, which the
33
+ * normal lifecycle treats as empty memory. Healthy stores are never written.
34
+ */
35
+ export declare function healSelectedStoreLocked(storage: StorageTransaction, request: HealRequest, signal?: AbortSignal): HealResult;
36
+ /** Never waits behind a live writer: a busy store is being used, so healing defers to a later attempt. */
37
+ export declare function healSelectedStore(request: HealRequest, signal?: AbortSignal): Promise<HealResult>;
38
+ /** One pending reset notice: projected to the model until an agent run settles after seeing it. */
39
+ export declare class HealNotice {
40
+ #private;
41
+ announce(message: string): void;
42
+ /** Model-facing text for the current request, marking it as seen. */
43
+ project(): string | undefined;
44
+ /** A settled run that saw the notice consumes it; an unseen notice survives. */
45
+ settle(): void;
46
+ }
47
+ export declare function describeHealedScopes(healed: readonly HealedScope[]): string;
@@ -0,0 +1,160 @@
1
+ // Domain: visible self-healing of unrecoverable canonical scope cohorts by quarantine and reset to absence.
2
+ // Excludes: semantic repair, Git restoration, foreign-owner data, transient I/O failures and Pi lifecycle policy.
3
+ import { createHash } from "node:crypto";
4
+ import { constants, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
5
+ import { basename, dirname, relative, resolve } from "node:path";
6
+ import { canonicalJson } from "./json.js";
7
+ import { RetiredSemanticFormatError } from "./migration.js";
8
+ import { sessionRuntimePaths, temporalScopePaths } from "./durable.js";
9
+ import { captureScopeSelection } from "./selection.js";
10
+ import { RevisionUnavailableError } from "./snapshot.js";
11
+ import { assertStorageDirectory, PublicationBusyError, withStorageTransaction } from "./storage.js";
12
+ /**
13
+ * Only semantic decoding/validation failures are healable. Filesystem, lock, cancellation and
14
+ * foreign-owner identity failures keep failing closed because resetting cannot fix them safely.
15
+ */
16
+ export function isHealableCorruption(error) {
17
+ if (!(error instanceof Error))
18
+ return false;
19
+ if (error instanceof RevisionUnavailableError || error instanceof PublicationBusyError || error instanceof RetiredSemanticFormatError)
20
+ return false;
21
+ if (error.name === "AbortError")
22
+ return false;
23
+ if (typeof error.code === "string")
24
+ return false;
25
+ if (/identity mismatch/i.test(error.message))
26
+ return false;
27
+ if (error instanceof AggregateError)
28
+ return error.errors.every(isHealableCorruption);
29
+ return true;
30
+ }
31
+ function scopeFiles(request, scope) {
32
+ const paths = temporalScopePaths(request.cwd, request.sessionId, scope, request.root, request.sessionKey);
33
+ const semantic = [paths.checkpoint, paths.patches, paths.meta, resolve(paths.directory, "state.json")];
34
+ if (scope !== "session")
35
+ return semantic;
36
+ const runtime = sessionRuntimePaths(request.cwd, request.sessionId, request.root, request.sessionKey);
37
+ return [...semantic, runtime.config, runtime.runtime];
38
+ }
39
+ function readPresent(path) {
40
+ const stat = lstatSync(path, { throwIfNoEntry: false });
41
+ if (!stat)
42
+ return undefined;
43
+ if (!stat.isFile() || stat.isSymbolicLink())
44
+ throw new Error(`State Flow quarantine refuses a non-regular file: ${JSON.stringify(path)}`);
45
+ return readFileSync(path, { flag: constants.O_RDONLY | constants.O_NOFOLLOW });
46
+ }
47
+ /** Exact-byte private record first; canonical files are removed only after the record verifies. */
48
+ function quarantineScope(request, scope, reason) {
49
+ const root = resolve(request.root);
50
+ const files = scopeFiles(request, scope).map(path => ({ path, bytes: readPresent(path) })).filter(file => file.bytes !== undefined);
51
+ if (files.length === 0)
52
+ return undefined;
53
+ const at = (request.now?.() ?? new Date()).toISOString();
54
+ const content = `${canonicalJson({ version: 1, kind: "state-flow-quarantine", at, root, cwd: resolve(request.cwd),
55
+ sessionId: request.sessionId, sessionKey: request.sessionKey, scope, reason,
56
+ files: files.map(file => ({ path: relative(root, file.path), bytes: file.bytes.toString("base64") })) })}\n`;
57
+ const directory = resolve(dirname(root), `${basename(root)}-quarantine`);
58
+ assertStorageDirectory(directory);
59
+ mkdirSync(directory, { recursive: true, mode: 0o700 });
60
+ const directoryStat = lstatSync(directory);
61
+ if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink() || (directoryStat.mode & 0o077) !== 0) {
62
+ throw new Error("State Flow quarantine directory must be private; canonical files preserved");
63
+ }
64
+ const digest = createHash("sha256").update(content).digest("hex").slice(0, 16);
65
+ const path = resolve(directory, `${at.replace(/[:.]/g, "-")}-${scope}-${digest}.json`);
66
+ try {
67
+ writeFileSync(path, content, { flag: "wx", mode: 0o600 });
68
+ }
69
+ catch (error) {
70
+ if (error.code !== "EEXIST")
71
+ throw error;
72
+ }
73
+ if (readFileSync(path, { encoding: "utf8", flag: constants.O_RDONLY | constants.O_NOFOLLOW }) !== content) {
74
+ throw new Error("State Flow quarantine record changed; canonical files preserved");
75
+ }
76
+ for (const file of files)
77
+ rmSync(file.path);
78
+ return { scope, reason, quarantine: path };
79
+ }
80
+ function probe(action, signal) {
81
+ try {
82
+ action();
83
+ return undefined;
84
+ }
85
+ catch (error) {
86
+ // Cancellation reasons are arbitrary values; they never prove corruption.
87
+ signal?.throwIfAborted();
88
+ if (!isHealableCorruption(error))
89
+ throw error;
90
+ return error;
91
+ }
92
+ }
93
+ /**
94
+ * Converge the selected owners to a loadable store: decode each owner independently, then the
95
+ * complete selected cohort. A broken owner is quarantined and becomes wholly absent, which the
96
+ * normal lifecycle treats as empty memory. Healthy stores are never written.
97
+ */
98
+ export function healSelectedStoreLocked(storage, request, signal) {
99
+ const wanted = captureScopeSelection(request.selection);
100
+ const { cwd, sessionId, sessionKey, root, historyLimit } = request;
101
+ const healed = [];
102
+ const reset = (scope, error) => {
103
+ const result = quarantineScope(request, scope, error.message);
104
+ if (result)
105
+ healed.push(result);
106
+ };
107
+ for (const scope of wanted.filter(owner => owner !== "session")) {
108
+ const failure = probe(() => storage.observeSelectedShared(cwd, captureScopeSelection([scope]), root), signal);
109
+ if (failure)
110
+ reset(scope, failure);
111
+ }
112
+ let lifecycle;
113
+ const lifecycleFailure = probe(() => { lifecycle = storage.inspectSelectedLifecycle(cwd, sessionId, wanted, root, sessionKey); }, signal);
114
+ if (lifecycleFailure) {
115
+ reset("session", lifecycleFailure);
116
+ return { healed, lifecycleAbsent: true };
117
+ }
118
+ if (!lifecycle)
119
+ return { healed, lifecycleAbsent: true };
120
+ if (wanted.includes("session") && lifecycle.runtime.meta.privateAcquisition !== "acquired")
121
+ return { healed, lifecycleAbsent: false };
122
+ // The session lifecycle anchors cross-owner lineage, so a contradictory cohort resets that private anchor.
123
+ const cohortFailure = probe(() => storage.prepareSelectedCurrent(cwd, sessionId, wanted, historyLimit, root, sessionKey), signal);
124
+ if (cohortFailure)
125
+ reset("session", cohortFailure);
126
+ return { healed, lifecycleAbsent: cohortFailure !== undefined };
127
+ }
128
+ /** Never waits behind a live writer: a busy store is being used, so healing defers to a later attempt. */
129
+ export async function healSelectedStore(request, signal) {
130
+ const root = resolve(request.root);
131
+ if (!lstatSync(root, { throwIfNoEntry: false }))
132
+ return { healed: [], lifecycleAbsent: true };
133
+ return withStorageTransaction(root, storage => healSelectedStoreLocked(storage, { ...request, root }, signal), signal, false);
134
+ }
135
+ /** One pending reset notice: projected to the model until an agent run settles after seeing it. */
136
+ export class HealNotice {
137
+ #message;
138
+ #projected = false;
139
+ announce(message) {
140
+ this.#message = message;
141
+ this.#projected = false;
142
+ }
143
+ /** Model-facing text for the current request, marking it as seen. */
144
+ project() {
145
+ if (this.#message === undefined)
146
+ return undefined;
147
+ this.#projected = true;
148
+ return `${this.#message}. Tell the user about this State Flow memory reset in your next answer.`;
149
+ }
150
+ /** A settled run that saw the notice consumes it; an unseen notice survives. */
151
+ settle() {
152
+ if (!this.#projected)
153
+ return;
154
+ this.#message = undefined;
155
+ this.#projected = false;
156
+ }
157
+ }
158
+ export function describeHealedScopes(healed) {
159
+ return healed.map(item => `${item.scope} memory was unreadable (${item.reason}) and was reset to empty; original bytes quarantined at ${item.quarantine}`).join("; ");
160
+ }
@@ -1,4 +1,4 @@
1
- export type StateFlowDiagnosticCategory = "invalid-patch" | "publication-conflict" | "finalization" | "barrier-block";
1
+ export type StateFlowDiagnosticCategory = "invalid-patch" | "publication-conflict" | "finalization" | "barrier-block" | "self-heal";
2
2
  /** Minimal structural block; only ordinary text keeps its exact content. */
3
3
  export interface StateFlowDiagnosticBlock {
4
4
  type: string;
@@ -41,5 +41,7 @@ export declare class StateFlowDiagnosticWriter {
41
41
  record(sessionId: string, cwd: string, error: string, category: StateFlowDiagnosticCategory, extras?: DiagnosticExtras): void;
42
42
  /** Push warnings stay short; retain the available Git failure detail locally even without opt-in logging. */
43
43
  recordBackupPushFailure(sessionId: string, cwd: string, error: string): boolean;
44
+ /** Memory resets are always recorded locally, independently of opt-in logging. */
45
+ recordSelfHeal(sessionId: string, cwd: string, error: string): boolean;
44
46
  private write;
45
47
  }
@@ -61,6 +61,10 @@ export class StateFlowDiagnosticWriter {
61
61
  recordBackupPushFailure(sessionId, cwd, error) {
62
62
  return this.write(sessionId, cwd, error, "publication-conflict", {}, false);
63
63
  }
64
+ /** Memory resets are always recorded locally, independently of opt-in logging. */
65
+ recordSelfHeal(sessionId, cwd, error) {
66
+ return this.write(sessionId, cwd, error, "self-heal", {});
67
+ }
64
68
  write(sessionId, cwd, error, category, extras, reportFailure = true) {
65
69
  try {
66
70
  const fromRepository = relative(this.repositoryRoot, this.path);
@@ -1,10 +1,9 @@
1
- import { type JsonObject } from "./json.ts";
2
1
  import { type RetainedModules } from "./semantic-module.ts";
3
2
  import { type StateScope } from "./state.ts";
4
3
  import { type ScopeStream } from "./temporal.ts";
5
- /** Owns temporary pure semantic-dialect conversion; excludes I/O, publication, backup and lifecycle authority. */
4
+ /** Owns the pure v3/v4 semantic codec and module-descriptor upgrade; excludes I/O, publication, backup and lifecycle authority. */
6
5
  export interface SemanticMigrationCandidate {
7
- sourceVersion: 1 | 2 | 3 | 4;
6
+ sourceVersion: 3 | 4;
8
7
  targetVersion: 3 | 4;
9
8
  /** A format conversion is not an authored semantic transition or revision. */
10
9
  requiresConversion: boolean;
@@ -21,8 +20,11 @@ export interface SerializedSemanticMigrationCandidate extends SemanticMigrationC
21
20
  basis: Record<ScopeMigrationFile, MigrationByteReceipt>;
22
21
  target: Record<ScopeMigrationFile, string>;
23
22
  }
24
- /** Translate a raw legacy checkpoint or replay patch before any known-field filtering. */
25
- export declare function translateLegacySemanticObject(value: unknown): JsonObject;
23
+ /** A known retired format, not corruption: self-healing must never reset it. */
24
+ export declare class RetiredSemanticFormatError extends Error {
25
+ }
26
+ /** State Flow 1.0.0 ended the temporary contract/working conversion window; refusal stays explicit. */
27
+ export declare function refuseRetiredSemanticVersion(version: unknown): never;
26
28
  /** Build a detached target candidate; publication still belongs to the guarded storage transaction. */
27
29
  export declare function prepareSemanticMigration(value: unknown, scope: StateScope, sourceVersion: number, historyLimit?: number, targetModules?: RetainedModules): SemanticMigrationCandidate;
28
30
  /** Decode a complete raw owner cohort before filtering; never load files, normalize authority or publish. */