@llblab/pi-state-flow 0.27.6 → 0.28.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 +2 -2
- package/CHANGELOG.md +5 -0
- package/README.md +1 -1
- package/dist/lib/extension.js +115 -16
- package/dist/lib/healing.d.ts +47 -0
- package/dist/lib/healing.js +159 -0
- package/dist/lib/logging.d.ts +3 -1
- package/dist/lib/logging.js +4 -0
- package/dist/package.json +1 -1
- package/docs/architecture.md +1 -1
- package/docs/filesystem-recovery.md +14 -0
- package/docs/usage.md +13 -12
- package/lib/extension.ts +103 -14
- package/lib/healing.ts +168 -0
- package/lib/logging.ts +6 -1
- package/package.json +1 -1
package/AGENTS.md
CHANGED
|
@@ -19,9 +19,9 @@ The [relocation ledger](docs/agent-contract-relocation.md) maps every pre-compac
|
|
|
19
19
|
## Publication and lifecycle
|
|
20
20
|
|
|
21
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
|
|
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
|
|
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/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,11 @@
|
|
|
4
4
|
|
|
5
5
|
## Unreleased
|
|
6
6
|
|
|
7
|
+
## 0.28.0: Visible Self-Healing Memory
|
|
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
|
+
- `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.
|
|
11
|
+
|
|
7
12
|
## 0.27.6: Namespaced Memory Tools
|
|
8
13
|
|
|
9
14
|
- `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,
|
|
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
|
|
package/dist/lib/extension.js
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
897
|
-
|
|
898
|
-
|
|
899
|
-
|
|
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
|
|
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
|
-
|
|
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) => {
|
|
@@ -2302,6 +2400,7 @@ export default function stateFlowExtension(pi, options = {}) {
|
|
|
2302
2400
|
}
|
|
2303
2401
|
});
|
|
2304
2402
|
pi.on("agent_settled", async (_event, ctx) => {
|
|
2403
|
+
healNotice.settle();
|
|
2305
2404
|
if (telegramStartPending && !isActive()) {
|
|
2306
2405
|
telegramStartPending = false;
|
|
2307
2406
|
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,159 @@
|
|
|
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 { sessionRuntimePaths, temporalScopePaths } from "./durable.js";
|
|
8
|
+
import { captureScopeSelection } from "./selection.js";
|
|
9
|
+
import { RevisionUnavailableError } from "./snapshot.js";
|
|
10
|
+
import { assertStorageDirectory, PublicationBusyError, withStorageTransaction } from "./storage.js";
|
|
11
|
+
/**
|
|
12
|
+
* Only semantic decoding/validation failures are healable. Filesystem, lock, cancellation and
|
|
13
|
+
* foreign-owner identity failures keep failing closed because resetting cannot fix them safely.
|
|
14
|
+
*/
|
|
15
|
+
export function isHealableCorruption(error) {
|
|
16
|
+
if (!(error instanceof Error))
|
|
17
|
+
return false;
|
|
18
|
+
if (error instanceof RevisionUnavailableError || error instanceof PublicationBusyError)
|
|
19
|
+
return false;
|
|
20
|
+
if (error.name === "AbortError")
|
|
21
|
+
return false;
|
|
22
|
+
if (typeof error.code === "string")
|
|
23
|
+
return false;
|
|
24
|
+
if (/identity mismatch/i.test(error.message))
|
|
25
|
+
return false;
|
|
26
|
+
if (error instanceof AggregateError)
|
|
27
|
+
return error.errors.every(isHealableCorruption);
|
|
28
|
+
return true;
|
|
29
|
+
}
|
|
30
|
+
function scopeFiles(request, scope) {
|
|
31
|
+
const paths = temporalScopePaths(request.cwd, request.sessionId, scope, request.root, request.sessionKey);
|
|
32
|
+
const semantic = [paths.checkpoint, paths.patches, paths.meta, resolve(paths.directory, "state.json")];
|
|
33
|
+
if (scope !== "session")
|
|
34
|
+
return semantic;
|
|
35
|
+
const runtime = sessionRuntimePaths(request.cwd, request.sessionId, request.root, request.sessionKey);
|
|
36
|
+
return [...semantic, runtime.config, runtime.runtime];
|
|
37
|
+
}
|
|
38
|
+
function readPresent(path) {
|
|
39
|
+
const stat = lstatSync(path, { throwIfNoEntry: false });
|
|
40
|
+
if (!stat)
|
|
41
|
+
return undefined;
|
|
42
|
+
if (!stat.isFile() || stat.isSymbolicLink())
|
|
43
|
+
throw new Error(`State Flow quarantine refuses a non-regular file: ${JSON.stringify(path)}`);
|
|
44
|
+
return readFileSync(path, { flag: constants.O_RDONLY | constants.O_NOFOLLOW });
|
|
45
|
+
}
|
|
46
|
+
/** Exact-byte private record first; canonical files are removed only after the record verifies. */
|
|
47
|
+
function quarantineScope(request, scope, reason) {
|
|
48
|
+
const root = resolve(request.root);
|
|
49
|
+
const files = scopeFiles(request, scope).map(path => ({ path, bytes: readPresent(path) })).filter(file => file.bytes !== undefined);
|
|
50
|
+
if (files.length === 0)
|
|
51
|
+
return undefined;
|
|
52
|
+
const at = (request.now?.() ?? new Date()).toISOString();
|
|
53
|
+
const content = `${canonicalJson({ version: 1, kind: "state-flow-quarantine", at, root, cwd: resolve(request.cwd),
|
|
54
|
+
sessionId: request.sessionId, sessionKey: request.sessionKey, scope, reason,
|
|
55
|
+
files: files.map(file => ({ path: relative(root, file.path), bytes: file.bytes.toString("base64") })) })}\n`;
|
|
56
|
+
const directory = resolve(dirname(root), `${basename(root)}-quarantine`);
|
|
57
|
+
assertStorageDirectory(directory);
|
|
58
|
+
mkdirSync(directory, { recursive: true, mode: 0o700 });
|
|
59
|
+
const directoryStat = lstatSync(directory);
|
|
60
|
+
if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink() || (directoryStat.mode & 0o077) !== 0) {
|
|
61
|
+
throw new Error("State Flow quarantine directory must be private; canonical files preserved");
|
|
62
|
+
}
|
|
63
|
+
const digest = createHash("sha256").update(content).digest("hex").slice(0, 16);
|
|
64
|
+
const path = resolve(directory, `${at.replace(/[:.]/g, "-")}-${scope}-${digest}.json`);
|
|
65
|
+
try {
|
|
66
|
+
writeFileSync(path, content, { flag: "wx", mode: 0o600 });
|
|
67
|
+
}
|
|
68
|
+
catch (error) {
|
|
69
|
+
if (error.code !== "EEXIST")
|
|
70
|
+
throw error;
|
|
71
|
+
}
|
|
72
|
+
if (readFileSync(path, { encoding: "utf8", flag: constants.O_RDONLY | constants.O_NOFOLLOW }) !== content) {
|
|
73
|
+
throw new Error("State Flow quarantine record changed; canonical files preserved");
|
|
74
|
+
}
|
|
75
|
+
for (const file of files)
|
|
76
|
+
rmSync(file.path);
|
|
77
|
+
return { scope, reason, quarantine: path };
|
|
78
|
+
}
|
|
79
|
+
function probe(action, signal) {
|
|
80
|
+
try {
|
|
81
|
+
action();
|
|
82
|
+
return undefined;
|
|
83
|
+
}
|
|
84
|
+
catch (error) {
|
|
85
|
+
// Cancellation reasons are arbitrary values; they never prove corruption.
|
|
86
|
+
signal?.throwIfAborted();
|
|
87
|
+
if (!isHealableCorruption(error))
|
|
88
|
+
throw error;
|
|
89
|
+
return error;
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* Converge the selected owners to a loadable store: decode each owner independently, then the
|
|
94
|
+
* complete selected cohort. A broken owner is quarantined and becomes wholly absent, which the
|
|
95
|
+
* normal lifecycle treats as empty memory. Healthy stores are never written.
|
|
96
|
+
*/
|
|
97
|
+
export function healSelectedStoreLocked(storage, request, signal) {
|
|
98
|
+
const wanted = captureScopeSelection(request.selection);
|
|
99
|
+
const { cwd, sessionId, sessionKey, root, historyLimit } = request;
|
|
100
|
+
const healed = [];
|
|
101
|
+
const reset = (scope, error) => {
|
|
102
|
+
const result = quarantineScope(request, scope, error.message);
|
|
103
|
+
if (result)
|
|
104
|
+
healed.push(result);
|
|
105
|
+
};
|
|
106
|
+
for (const scope of wanted.filter(owner => owner !== "session")) {
|
|
107
|
+
const failure = probe(() => storage.observeSelectedShared(cwd, captureScopeSelection([scope]), root), signal);
|
|
108
|
+
if (failure)
|
|
109
|
+
reset(scope, failure);
|
|
110
|
+
}
|
|
111
|
+
let lifecycle;
|
|
112
|
+
const lifecycleFailure = probe(() => { lifecycle = storage.inspectSelectedLifecycle(cwd, sessionId, wanted, root, sessionKey); }, signal);
|
|
113
|
+
if (lifecycleFailure) {
|
|
114
|
+
reset("session", lifecycleFailure);
|
|
115
|
+
return { healed, lifecycleAbsent: true };
|
|
116
|
+
}
|
|
117
|
+
if (!lifecycle)
|
|
118
|
+
return { healed, lifecycleAbsent: true };
|
|
119
|
+
if (wanted.includes("session") && lifecycle.runtime.meta.privateAcquisition !== "acquired")
|
|
120
|
+
return { healed, lifecycleAbsent: false };
|
|
121
|
+
// The session lifecycle anchors cross-owner lineage, so a contradictory cohort resets that private anchor.
|
|
122
|
+
const cohortFailure = probe(() => storage.prepareSelectedCurrent(cwd, sessionId, wanted, historyLimit, root, sessionKey), signal);
|
|
123
|
+
if (cohortFailure)
|
|
124
|
+
reset("session", cohortFailure);
|
|
125
|
+
return { healed, lifecycleAbsent: cohortFailure !== undefined };
|
|
126
|
+
}
|
|
127
|
+
/** Never waits behind a live writer: a busy store is being used, so healing defers to a later attempt. */
|
|
128
|
+
export async function healSelectedStore(request, signal) {
|
|
129
|
+
const root = resolve(request.root);
|
|
130
|
+
if (!lstatSync(root, { throwIfNoEntry: false }))
|
|
131
|
+
return { healed: [], lifecycleAbsent: true };
|
|
132
|
+
return withStorageTransaction(root, storage => healSelectedStoreLocked(storage, { ...request, root }, signal), signal, false);
|
|
133
|
+
}
|
|
134
|
+
/** One pending reset notice: projected to the model until an agent run settles after seeing it. */
|
|
135
|
+
export class HealNotice {
|
|
136
|
+
#message;
|
|
137
|
+
#projected = false;
|
|
138
|
+
announce(message) {
|
|
139
|
+
this.#message = message;
|
|
140
|
+
this.#projected = false;
|
|
141
|
+
}
|
|
142
|
+
/** Model-facing text for the current request, marking it as seen. */
|
|
143
|
+
project() {
|
|
144
|
+
if (this.#message === undefined)
|
|
145
|
+
return undefined;
|
|
146
|
+
this.#projected = true;
|
|
147
|
+
return `${this.#message}. Tell the user about this State Flow memory reset in your next answer.`;
|
|
148
|
+
}
|
|
149
|
+
/** A settled run that saw the notice consumes it; an unseen notice survives. */
|
|
150
|
+
settle() {
|
|
151
|
+
if (!this.#projected)
|
|
152
|
+
return;
|
|
153
|
+
this.#message = undefined;
|
|
154
|
+
this.#projected = false;
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
export function describeHealedScopes(healed) {
|
|
158
|
+
return healed.map(item => `${item.scope} memory was unreadable (${item.reason}) and was reset to empty; original bytes quarantined at ${item.quarantine}`).join("; ");
|
|
159
|
+
}
|
package/dist/lib/logging.d.ts
CHANGED
|
@@ -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
|
}
|
package/dist/lib/logging.js
CHANGED
|
@@ -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);
|
package/dist/package.json
CHANGED
package/docs/architecture.md
CHANGED
|
@@ -514,7 +514,7 @@ Without removals on a complete accepted cohort, publication preserves semantic/p
|
|
|
514
514
|
3. **Acceptance.** Same-session attachment accepts current memory through `withStartTransaction` under the checkpoint's mode; a fork copies the parent's current memory; a truly new auto-start origin uses `withStartTransaction` with creation authority (rechecking branch evidence after waiting); failed-Stop reload uses read-only recovery. Bootstrap and policy are derived after waiting and published in that single acceptance.
|
|
515
515
|
4. **Installation.** Only the current lifetime installs memory, checkpoint, continuation, tools and UI before yielding; a later native-write failure only warns.
|
|
516
516
|
|
|
517
|
-
**Failed Active selection.**
|
|
517
|
+
**Failed Active selection.** Missing, corrupt, partial or contradictory current files first go through one visible [self-healing](filesystem-recovery.md#self-healing) attempt. Memory still unavailable after that (an unhealable cause), a failed fork copy or automatic Start failure retains the selected Active mode with unavailable-memory validation. The inference fence is derived from that mode and validation, not an independent flag under an inactive fallback. No Active lifecycle work or fabricated projection runs before validated acceptance; shared reads may remain available. Terminal and Telegram show `active (blocked)` with explicit recovery guidance. The live `context` hook calls public `ctx.abort()` before returning; merely throwing would let Pi continue with native history. Reloading while current memory stays unreadable reconstructs the fence. Accepted Start or accepted explicit Passive releases it; explicit Off permits native context but grants no memory authority. Signal-less inspection does not cancel or clear the fence.
|
|
518
518
|
|
|
519
519
|
**Interaction with mode choices:**
|
|
520
520
|
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
State Flow classifies absence separately from partial or malformed evidence. Recovery may derive bytes only from an authoritative surviving cohort or from a semantic default that the owner explicitly permits. It never invents history, ownership, provenance, or external success.
|
|
4
4
|
|
|
5
|
+
The "fails closed" rules below describe what a single operation does with partial or malformed evidence. They are not permanent: the next acquisition heals an unrecoverable owner visibly; see [self-healing](#self-healing).
|
|
6
|
+
|
|
5
7
|
## Resource rules
|
|
6
8
|
|
|
7
9
|
### Global `checkpoint.json` + `patches.jsonl`
|
|
@@ -138,3 +140,15 @@ Every semantic repair follows the ordinary transaction path:
|
|
|
138
140
|
- Authored `state_flow_patch` operations select this basis under the awaited store lock and publish only after complete validation. A rejected first patch never leaves separately published empty initialization.
|
|
139
141
|
- Raw precomputed replay targeting a disappeared selected basis still fails closed.
|
|
140
142
|
- Discarded history is unavailable and is never reconstructed or promoted back into current shared memory.
|
|
143
|
+
|
|
144
|
+
## Self-healing
|
|
145
|
+
|
|
146
|
+
`lib/healing.ts` is the single owner allowed to remove canonical bytes outside publication. It runs only after an acquisition (startup, reload, resume, tree navigation, Start, Passive, pre-runtime shared observation) has failed, so healthy stores pay nothing and keep their existing lock timing.
|
|
147
|
+
|
|
148
|
+
1. Take the store publication lock without waiting; a live writer means the store is in use, so healing defers to a later attempt.
|
|
149
|
+
2. Decode each selected shared owner alone, then the session lifecycle, then the complete selected cohort.
|
|
150
|
+
3. For an owner that fails with a semantic decode/validation error, write one private exact-byte record (`<parent-of-store>/<store-name>-quarantine/<time>-<scope>-<digest>.json`, directory 0700, file 0600, verified by reading back), then delete that owner's canonical files so it becomes wholly absent. A cohort-level lineage contradiction resets the session (the lineage anchor), never healthy shared owners.
|
|
151
|
+
4. Retry the failed acquisition once. A session that is now absent, or a boundary whose session memory was missing, restarts from empty memory under the branch's captured mode and selection.
|
|
152
|
+
5. Announce every reset to the operator (warning), the model (one projected notice until a run that saw it settles) and the local diagnostic log (always, independent of `logging`).
|
|
153
|
+
|
|
154
|
+
Never healed: filesystem errors, lock or busy states, cancellation, and identity mismatches that indicate another owner's data. Those keep failing closed. Quarantine records are recovery evidence for manual restoration, not an automatic fallback.
|
package/docs/usage.md
CHANGED
|
@@ -290,32 +290,33 @@ See the [storage contract](architecture.md#storage-and-identity) for the exact l
|
|
|
290
290
|
|
|
291
291
|
**Wholly absent shared files.** A checkpoint and its tail are one semantic pair. If both live files of a global or CWD scope disappear, State Flow treats that complete absence as current empty shared reality. An authored `state_flow_patch` applies to that empty basis under exclusion, and 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.
|
|
292
292
|
|
|
293
|
-
**
|
|
293
|
+
**Unrecoverable owners self-heal, visibly.** When startup, reload, resume, tree navigation, Start or Passive cannot accept memory, State Flow examines each selected owner once:
|
|
294
294
|
|
|
295
|
-
- exactly one surviving pair member;
|
|
296
|
-
-
|
|
297
|
-
-
|
|
298
|
-
-
|
|
295
|
+
- An owner that cannot be decoded (exactly one surviving pair member, malformed JSON, unsupported envelopes, semantic/metadata boundary mismatches, partial or contradictory session runtime evidence) has its exact bytes copied to a private record in `<parent-of-store>/<store-name>-quarantine/` and is then reset to wholly absent, which is empty memory. Healthy owners are untouched; a cross-owner lineage contradiction resets the private session anchor, not shared memory.
|
|
296
|
+
- A boundary whose stored session memory is missing restarts that session from empty memory too.
|
|
297
|
+
- Every reset is announced: a terminal/Telegram warning names the owner, the cause and the quarantine record; the next model request carries a notice asking the agent to tell the user; the local diagnostic log records it even when `logging` is off.
|
|
298
|
+
- Healing never waits behind a live writer, and filesystem errors, lock problems, cancellation and foreign-owner identity mismatches are not healed: they keep the fail-closed behavior below.
|
|
299
299
|
|
|
300
|
-
Memory never depends on the Pi step, so an old or expired branch checkpoint is not a failure: attachment always uses the current same-session files. State Flow does not substitute Git history
|
|
300
|
+
Memory never depends on the Pi step, so an old or expired branch checkpoint is not a failure: attachment always uses the current same-session files. State Flow does not substitute Git history or another session's files.
|
|
301
301
|
|
|
302
|
-
**When current session memory
|
|
302
|
+
**When current session memory stays unavailable** (an unhealable cause):
|
|
303
303
|
|
|
304
|
-
- Under Active, the selected mode remains Active and the indicator shows `active (blocked)`. Live inference is aborted before the provider instead of silently sending native history under an inactive fallback. Reload/resume retains this fence.
|
|
305
|
-
- Global/CWD memory stays readable; the unavailable session layer is never replaced
|
|
304
|
+
- Under Active, the selected mode remains Active and the indicator shows `active (blocked)`. Live inference is aborted before the provider instead of silently sending native history under an inactive fallback. Reload/resume retains this fence. Fix the cause and choose Active/Passive; explicit Off permits native context without reading memory. Signal-less inspection remains observational.
|
|
305
|
+
- Global/CWD memory stays readable; the unavailable session layer is never silently replaced.
|
|
306
306
|
- Session reads and every `state_flow_patch` refuse without changing canonical files or appending substitute checkpoints.
|
|
307
|
-
- **Modes are stable.** Explicit Passive accepts validated current same-session memory exactly like Active, keeping Passive policy. Only while current memory is still
|
|
307
|
+
- **Modes are stable.** Explicit Passive accepts validated current same-session memory exactly like Active, keeping Passive policy. Only while current memory is still unavailable or unpublishable does Passive keep native inference with paused writes and report the cause. Off records native policy only.
|
|
308
308
|
- Status distinguishes a write fence from unavailable materialization.
|
|
309
309
|
|
|
310
|
+
**Empty stores read as empty.** On a branch without accepted memory, `state_flow_read` returns `null` for absent shared values instead of reporting an unavailable runtime; a selected but not yet created Session reports that the first accepted `state_flow_patch` creates it.
|
|
311
|
+
|
|
310
312
|
**Explicit Start uses current memory.**
|
|
311
313
|
|
|
312
314
|
- It independently validates the current same-session canonical cohort, preserving private memory, artifact provenance, revisions, step and available aligned history.
|
|
313
315
|
- Expired active/passive pointers and unfinished runtime work do not block activation. A pre-runtime selection also keeps current accepted same-session memory instead of resetting it.
|
|
314
316
|
- 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.
|
|
315
317
|
- Independently advanced shared scopes may require a new temporal origin; unavailable history is never invented.
|
|
316
|
-
- Exact-cohort CAS rejects a concurrent writer
|
|
318
|
+
- Exact-cohort CAS rejects a concurrent writer; incomplete or corrupt storage is changed only by visible self-healing.
|
|
317
319
|
- An unaccepted native fork retries copying its parent's current memory rather than inventing child memory.
|
|
318
|
-
- When evidence is missing, repair it or open a genuinely new Pi session.
|
|
319
320
|
|
|
320
321
|
**Artifact evidence and replication:**
|
|
321
322
|
|
package/lib/extension.ts
CHANGED
|
@@ -40,7 +40,8 @@ import { compactStatus, detailedStatus, STATUS_KEY, type StatusDiagnostics } fro
|
|
|
40
40
|
import { PublicationBusyError, loadSelectedFileCohort, type SelectedFilePublication } from "./storage.ts";
|
|
41
41
|
import { captureScopeSelection, DEFAULT_SCOPE_SELECTION, parseScopeSelectionArguments, scopeSelectionArgumentCompletions, type ScopeSelection } from "./selection.ts";
|
|
42
42
|
import { createStateFlowTelegramAdapter, type StateFlowTelegramControlResult, type StateFlowTelegramInspection, type StateFlowTelegramLoader, type StateFlowTelegramScope } from "./telegram.ts";
|
|
43
|
-
import { readTemporalScopes, temporalScopeRevisions, type ScopeRevisions } from "./temporal.ts";
|
|
43
|
+
import { createSelectedTemporalState, readTemporalScopes, temporalScopeRevisions, type ScopeRevisions, type SelectedTemporalState } from "./temporal.ts";
|
|
44
|
+
import { describeHealedScopes, healSelectedStore, HealNotice, type HealResult } from "./healing.ts";
|
|
44
45
|
import { commitSelectedTransition, stageSelectedScopePatches, stageSelectedScopedTransition, type ModuleReplacement } from "./transition.ts";
|
|
45
46
|
|
|
46
47
|
export interface StateFlowExtensionOptions {
|
|
@@ -129,6 +130,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
129
130
|
let effectiveState: SemanticState = {};
|
|
130
131
|
let branchStartsWithoutRuntime = false;
|
|
131
132
|
let modePersistenceError: string | undefined;
|
|
133
|
+
const healNotice = new HealNotice();
|
|
132
134
|
/** One pending inactive-mode persistence; later inactive choices coalesce until it publishes. */
|
|
133
135
|
const inactivePersistence = new OwnedOperationSlot<InactivePersistence>();
|
|
134
136
|
const startActivation = new OwnedOperationSlot<ModeOperation>();
|
|
@@ -181,6 +183,38 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
181
183
|
ctx.ui.notify(conciseDiagnostic(message), level);
|
|
182
184
|
}
|
|
183
185
|
|
|
186
|
+
/** Announce a reset to both operator and model; a reset is never silent. */
|
|
187
|
+
function announceHealing(ctx: ExtensionContext, message: string): void {
|
|
188
|
+
healNotice.announce(message);
|
|
189
|
+
diagnosticWriter.recordSelfHeal(sessionAddress(ctx).id, ctx.cwd, message);
|
|
190
|
+
ctx.ui.notify(message, "warning");
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/** Quarantine unrecoverable selected owners before acceptance; unhealable failures keep failing closed downstream. */
|
|
194
|
+
async function healCurrentStore(ctx: ExtensionContext, wanted: ScopeSelection, signal: AbortSignal): Promise<HealResult | undefined> {
|
|
195
|
+
const address = sessionAddress(ctx);
|
|
196
|
+
let result: HealResult;
|
|
197
|
+
try {
|
|
198
|
+
result = await healSelectedStore({ cwd: ctx.cwd, sessionId: address.id, sessionKey: address.key, selection: wanted,
|
|
199
|
+
historyLimit: config.historyLimit, root: repositoryRoot }, signal);
|
|
200
|
+
} catch (error) {
|
|
201
|
+
if (signal.aborted) throw error;
|
|
202
|
+
return undefined;
|
|
203
|
+
}
|
|
204
|
+
if (result.healed.length) announceHealing(ctx, `State Flow self-healed: ${describeHealedScopes(result.healed)}`);
|
|
205
|
+
return result;
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/** A pre-runtime branch with no stored cohort reads as empty memory instead of an unavailable runtime. */
|
|
209
|
+
function emptyPreRuntimeView(wanted: ScopeSelection): SelectedTemporalState | undefined {
|
|
210
|
+
if (!branchStartsWithoutRuntime || snapshot.config.mode === "off" || snapshot.meta.validation?.attempt === 0
|
|
211
|
+
|| branchRestoration.current?.awaitingAcceptance) return undefined;
|
|
212
|
+
// Shared absence is empty reality; unacquired Session keeps its explicit selected-unavailable diagnostic.
|
|
213
|
+
const shared = wanted.filter(scope => scope !== "session");
|
|
214
|
+
if (!shared.length) return undefined;
|
|
215
|
+
return createSelectedTemporalState(Object.fromEntries(shared.map(scope => [scope, {}])), captureScopeSelection(shared), "empty:pre-runtime", config.historyLimit);
|
|
216
|
+
}
|
|
217
|
+
|
|
184
218
|
function notifyActiveContext(message: string): void {
|
|
185
219
|
try {
|
|
186
220
|
if (activeContext) notifyProblem(activeContext, message, "warning");
|
|
@@ -695,9 +729,30 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
695
729
|
return branchRestoration.track(pending, attachBranch(ctx, pending, selection, sessionStartReason, notifyRecovery, skipped), false);
|
|
696
730
|
}
|
|
697
731
|
|
|
732
|
+
/**
|
|
733
|
+
* After a failed attachment, heal selected owners once. Returns the selection to retry, or undefined when healing
|
|
734
|
+
* changed nothing; expected-but-absent session memory restarts visibly from empty memory.
|
|
735
|
+
*/
|
|
736
|
+
async function healBranchSelection(ctx: ExtensionContext, selection: BranchSelection, requestedMode: InactiveMode | undefined, signal: AbortSignal): Promise<BranchSelection | undefined> {
|
|
737
|
+
if (selection.kind === "settled") return undefined;
|
|
738
|
+
const healing = await healCurrentStore(ctx, nativeScopeSelection(ctx), signal).catch(() => undefined);
|
|
739
|
+
if (!healing || signal.aborted || shuttingDown) return undefined;
|
|
740
|
+
if (healing.lifecycleAbsent && (selection.kind === "attach" || selection.kind === "current")) {
|
|
741
|
+
const mode = requestedMode ?? (selection.kind === "current" ? selection.mode : selection.checkpoint.mode);
|
|
742
|
+
if (mode === "off") return undefined;
|
|
743
|
+
if (!healing.healed.some(item => item.scope === "session")) {
|
|
744
|
+
announceHealing(ctx, "State Flow self-healed: session memory files were missing and session memory restarts empty");
|
|
745
|
+
}
|
|
746
|
+
branchStartsWithoutRuntime = true;
|
|
747
|
+
modePersistenceError = undefined;
|
|
748
|
+
return mode === "active" ? { kind: "auto-start" } : { kind: "pre-runtime", mode };
|
|
749
|
+
}
|
|
750
|
+
return healing.healed.length > 0 ? selection : undefined;
|
|
751
|
+
}
|
|
752
|
+
|
|
698
753
|
async function attachBranch(
|
|
699
754
|
ctx: ExtensionContext, pending: BranchRestoration, selection: BranchSelection,
|
|
700
|
-
reason: unknown, notifyRecovery: boolean, skipped: number,
|
|
755
|
+
reason: unknown, notifyRecovery: boolean, skipped: number, healed = false,
|
|
701
756
|
): Promise<void> {
|
|
702
757
|
const placeholder = runtime;
|
|
703
758
|
let selected = runtime;
|
|
@@ -857,6 +912,12 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
857
912
|
return;
|
|
858
913
|
}
|
|
859
914
|
if (!isCurrent()) return;
|
|
915
|
+
const retry = healed ? undefined : await healBranchSelection(ctx, selection, pending.requestedMode, signal);
|
|
916
|
+
if (retry && isCurrent()) {
|
|
917
|
+
pending.awaitingAcceptance = retry.kind !== "settled" && retry.kind !== "current";
|
|
918
|
+
return await attachBranch(ctx, pending, retry, reason, notifyRecovery, skipped, true);
|
|
919
|
+
}
|
|
920
|
+
if (!isCurrent()) return;
|
|
860
921
|
failSelection(error);
|
|
861
922
|
} finally {
|
|
862
923
|
pending.awaitingAcceptance = false;
|
|
@@ -866,7 +927,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
866
927
|
settleSelection(ctx, reason, notifyRecovery, skipped, selected !== placeholder);
|
|
867
928
|
if (snapshot.config.mode === "off" || isActive() || readableView() || snapshot.meta.validation?.attempt === 0 || !branchStartsWithoutRuntime) return;
|
|
868
929
|
// Only a proven pre-runtime Passive branch may observe shared owners without private acquisition.
|
|
869
|
-
const passive = await loadPassiveView(ctx, signal, isCurrent, notifyRecovery);
|
|
930
|
+
const passive = await loadPassiveView(ctx, signal, isCurrent, notifyRecovery, !healed);
|
|
870
931
|
if (passive === undefined) return;
|
|
871
932
|
assertCurrent();
|
|
872
933
|
// An intervening passive patch or inspection owns its newer cache, even on the same physical branch.
|
|
@@ -885,14 +946,21 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
885
946
|
}
|
|
886
947
|
|
|
887
948
|
/** Load current shared memory for passive projection without initializing or publishing it. */
|
|
888
|
-
async function loadPassiveView(ctx: ExtensionContext, signal: AbortSignal, isCurrent: () => boolean, notify: boolean): Promise<TemporalRuntime | undefined> {
|
|
949
|
+
async function loadPassiveView(ctx: ExtensionContext, signal: AbortSignal, isCurrent: () => boolean, notify: boolean, heal = true): Promise<TemporalRuntime | undefined> {
|
|
889
950
|
const wanted = nativeScopeSelection(ctx), shared = wanted.filter(scope => scope !== "session");
|
|
890
951
|
if (!shared.length) return undefined;
|
|
891
952
|
const passive = createRuntime(ctx);
|
|
953
|
+
const observe = () => passive.refreshSelectedShared(captureScopeSelection(shared), () => {
|
|
954
|
+
if (!isCurrent() || !sameJson(nativeScopeSelection(ctx), wanted)) throw new Error("State Flow observation selection changed");
|
|
955
|
+
}, signal);
|
|
892
956
|
try {
|
|
893
|
-
await
|
|
894
|
-
|
|
895
|
-
|
|
957
|
+
try { await observe(); }
|
|
958
|
+
catch (error) {
|
|
959
|
+
if (!heal || signal.aborted || !isCurrent()) throw error;
|
|
960
|
+
const healing = await healCurrentStore(ctx, captureScopeSelection(shared), signal).catch(() => undefined);
|
|
961
|
+
if (!healing?.healed.length) throw error;
|
|
962
|
+
await observe();
|
|
963
|
+
}
|
|
896
964
|
} catch (error) {
|
|
897
965
|
if (isCurrent() && !signal.aborted && notify && !modePersistenceError) notifyProblem(ctx, `State Flow passive memory is unavailable: ${diagnosticText(error)}`, "warning");
|
|
898
966
|
return undefined;
|
|
@@ -989,11 +1057,12 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
989
1057
|
const requestedPaths = [...(params.paths ?? [params.path!])];
|
|
990
1058
|
const paths = requestedPaths.map(path => normalizeModelReadPath(path, wanted, config.historyLimit));
|
|
991
1059
|
check();
|
|
992
|
-
const view = readableView(selected);
|
|
1060
|
+
const view = readableView(selected) ?? emptyPreRuntimeView(wanted);
|
|
993
1061
|
// Wanted policy was checked by normalization; an observational subset is not an exclusion.
|
|
994
1062
|
for (const path of paths) {
|
|
995
1063
|
const owner = /^(global|cwd|session)(?=\.|\[|$)/.exec(path)?.[1] as StateScope | undefined;
|
|
996
|
-
if (owner && !view?.selection.includes(owner)) throw new Error(`State Flow ${owner}: selected, unavailable
|
|
1064
|
+
if (owner && !view?.selection.includes(owner)) throw new Error(`State Flow ${owner}: selected, unavailable${branchStartsWithoutRuntime
|
|
1065
|
+
? "; no memory is stored for it yet, and an accepted state_flow_patch creates it" : ""}`);
|
|
997
1066
|
}
|
|
998
1067
|
if (!view) throw new Error("State Flow temporal runtime is unavailable");
|
|
999
1068
|
check();
|
|
@@ -1239,6 +1308,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
1239
1308
|
async function activateCurrentState(
|
|
1240
1309
|
ctx: ExtensionContext, pending: AbortController, mode: "active" | "passive" = "active",
|
|
1241
1310
|
owns = () => startActivation.current?.controller === pending,
|
|
1311
|
+
healing?: HealResult,
|
|
1242
1312
|
): Promise<StateFlowTelegramControlResult> {
|
|
1243
1313
|
let selected = runtime;
|
|
1244
1314
|
const wanted = nativeScopeSelection(ctx);
|
|
@@ -1265,15 +1335,24 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
1265
1335
|
const retained = selectRetainedCheckpoint(discovery.candidates, config.inactiveMode);
|
|
1266
1336
|
branchStartsWithoutRuntime = retained.kind === "pre-runtime" || (discovery.candidates.length === 0 && discovery.errors.length === 0);
|
|
1267
1337
|
}
|
|
1338
|
+
// After a failed attempt, a missing or reset session lifecycle restarts visibly from empty memory instead of blocking forever.
|
|
1339
|
+
const sessionReset = healing?.lifecycleAbsent === true && !forkInitialization && !branchPolicy(ctx).forkPending
|
|
1340
|
+
&& !(selected?.cwd === ctx.cwd && selected.sessionKey === activation.sessionKey && selected.selectedView()?.selection.includes("session"));
|
|
1341
|
+
if (sessionReset) {
|
|
1342
|
+
if (!branchStartsWithoutRuntime && !healing!.healed.some(item => item.scope === "session")) {
|
|
1343
|
+
announceHealing(ctx, "State Flow self-healed: session memory files were missing and session memory restarts empty");
|
|
1344
|
+
}
|
|
1345
|
+
branchStartsWithoutRuntime = true;
|
|
1346
|
+
}
|
|
1268
1347
|
// Off activation owns one cancellable current-head publication, not an independent read-only restore.
|
|
1269
1348
|
const acceptActivation = (current: Snapshot | undefined, publish: (next: Snapshot) => SelectedFilePublication) => {
|
|
1270
1349
|
signal.throwIfAborted();
|
|
1271
1350
|
if (!isCurrent()) throw new Error("State Flow activation selection changed while awaiting publication");
|
|
1272
|
-
if (!current && (!active || !branchStartsWithoutRuntime)) throw new Error(snapshot.meta.validation?.error ?? "Current State Flow session memory is unavailable");
|
|
1351
|
+
if (!current && (!(active || sessionReset) || !branchStartsWithoutRuntime)) throw new Error(snapshot.meta.validation?.error ?? "Current State Flow session memory is unavailable");
|
|
1273
1352
|
const boundary = deferred && retainsPhysicalSessionProjection(deferred.reason)
|
|
1274
1353
|
? branchPolicy(ctx).stop : undefined;
|
|
1275
1354
|
const bootstrap = hasPriorConversation(ctx.sessionManager.getBranch()) || passiveContinuation !== undefined || boundary !== undefined;
|
|
1276
|
-
const activated = !active ? deactivateEpisode(current
|
|
1355
|
+
const activated = !active ? deactivateEpisode(current ?? startEpisode(false), "passive")
|
|
1277
1356
|
: current ? resumeEpisode(current, bootstrap) : startEpisode(bootstrap);
|
|
1278
1357
|
if (active) {
|
|
1279
1358
|
// Explicit Start accepts current memory, not the prior run's prompt or repair attempt.
|
|
@@ -1337,8 +1416,9 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
1337
1416
|
if (forkInitialization || branchPolicy(ctx).forkPending) throw new Error("Pending fork cannot use independent private acquisition");
|
|
1338
1417
|
acquiredResult = acceptActivation(basis.snapshot, activated => publish(activated));
|
|
1339
1418
|
} }, publish => { check(); publish(); return acquiredResult; }, signal, true);
|
|
1340
|
-
} else if (active && branchStartsWithoutRuntime && !acceptedSession && !disposition) {
|
|
1341
|
-
const
|
|
1419
|
+
} else if ((active || sessionReset) && branchStartsWithoutRuntime && !acceptedSession && !disposition) {
|
|
1420
|
+
const started = startEpisode(hasPriorConversation(ctx.sessionManager.getBranch()) || passiveContinuation !== undefined);
|
|
1421
|
+
const next = active ? started : deactivateEpisode(startEpisode(false), "passive");
|
|
1342
1422
|
result = await activation.withSelectedFirstPatchTransaction(wanted, next, transaction => {
|
|
1343
1423
|
check();
|
|
1344
1424
|
if (!branchStartsWithoutRuntime || forkInitialization) throw new Error("State Flow origin authority changed");
|
|
@@ -1349,6 +1429,12 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
1349
1429
|
return isCurrent() ? result : superseded();
|
|
1350
1430
|
} catch (error) {
|
|
1351
1431
|
if (!isCurrent()) return superseded();
|
|
1432
|
+
if (!accepted && healing === undefined) {
|
|
1433
|
+
// Self-healing is lazy: healthy stores never pay for it, and one retry bounds convergence.
|
|
1434
|
+
const healed = await healCurrentStore(ctx, wanted, signal).catch(() => undefined);
|
|
1435
|
+
if (!isCurrent()) return superseded();
|
|
1436
|
+
if (healed && (healed.healed.length > 0 || healed.lifecycleAbsent)) return activateCurrentState(ctx, pending, mode, owns, healed);
|
|
1437
|
+
}
|
|
1352
1438
|
const message = conciseDiagnostic(`${accepted ? `State Flow ${mode}; lifecycle update failed` : active ? "State Flow activation failed" : "State Flow passive acceptance failed"}: ${diagnosticText(error)}`);
|
|
1353
1439
|
// An unaccepted activation cannot replace retained lifecycle or poison an independent Stop.
|
|
1354
1440
|
// Attachment owns required-proof unavailability; failed Passive acceptance reports through its caller's fence.
|
|
@@ -1782,7 +1868,9 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
1782
1868
|
// Off removes the owned section, including one contributed before an in-flight mode change.
|
|
1783
1869
|
const protocol = isActive() ? stateFlowProtocol(snapshot.meta.bootstrap === true, nativeScopeSelection(ctx))
|
|
1784
1870
|
: passiveMemoryAvailable() ? passiveMemoryProtocol(nativeScopeSelection(ctx)) : undefined;
|
|
1785
|
-
|
|
1871
|
+
// Only a request that can carry the section consumes the reset notice.
|
|
1872
|
+
const notice = snapshot.config.mode !== "off" && event.messages.some(message => message.role === "system") ? healNotice.project() : undefined;
|
|
1873
|
+
return { messages: projectSystemProtocol(event.messages, [protocol, notice].filter(Boolean).join("\n\n") || undefined) };
|
|
1786
1874
|
});
|
|
1787
1875
|
|
|
1788
1876
|
// Optional transport checkpoint: no payload/header inspection or transformation.
|
|
@@ -2129,6 +2217,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
|
|
|
2129
2217
|
});
|
|
2130
2218
|
|
|
2131
2219
|
pi.on("agent_settled", async (_event, ctx) => {
|
|
2220
|
+
healNotice.settle();
|
|
2132
2221
|
if (telegramStartPending && !isActive()) {
|
|
2133
2222
|
telegramStartPending = false;
|
|
2134
2223
|
await startStateFlow(ctx);
|
package/lib/healing.ts
ADDED
|
@@ -0,0 +1,168 @@
|
|
|
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.ts";
|
|
7
|
+
import { sessionRuntimePaths, temporalScopePaths } from "./durable.ts";
|
|
8
|
+
import { captureScopeSelection, type ScopeSelection } from "./selection.ts";
|
|
9
|
+
import { RevisionUnavailableError } from "./snapshot.ts";
|
|
10
|
+
import type { StateScope } from "./state.ts";
|
|
11
|
+
import { assertStorageDirectory, PublicationBusyError, withStorageTransaction, type StorageTransaction } from "./storage.ts";
|
|
12
|
+
|
|
13
|
+
/** One visible reset: the scope became wholly absent after its exact bytes were quarantined. */
|
|
14
|
+
export interface HealedScope {
|
|
15
|
+
scope: StateScope;
|
|
16
|
+
reason: string;
|
|
17
|
+
quarantine: string;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** Healing outcome; `lifecycleAbsent` means this session owns no lifecycle after healing. */
|
|
21
|
+
export interface HealResult {
|
|
22
|
+
healed: HealedScope[];
|
|
23
|
+
lifecycleAbsent: boolean;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export interface HealRequest {
|
|
27
|
+
cwd: string;
|
|
28
|
+
sessionId: string;
|
|
29
|
+
sessionKey: string;
|
|
30
|
+
selection: ScopeSelection;
|
|
31
|
+
historyLimit: number;
|
|
32
|
+
root: string;
|
|
33
|
+
/** Wall-clock source for deterministic tests. */
|
|
34
|
+
now?: () => Date;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* Only semantic decoding/validation failures are healable. Filesystem, lock, cancellation and
|
|
39
|
+
* foreign-owner identity failures keep failing closed because resetting cannot fix them safely.
|
|
40
|
+
*/
|
|
41
|
+
export function isHealableCorruption(error: unknown): boolean {
|
|
42
|
+
if (!(error instanceof Error)) return false;
|
|
43
|
+
if (error instanceof RevisionUnavailableError || error instanceof PublicationBusyError) return false;
|
|
44
|
+
if (error.name === "AbortError") return false;
|
|
45
|
+
if (typeof (error as NodeJS.ErrnoException).code === "string") return false;
|
|
46
|
+
if (/identity mismatch/i.test(error.message)) return false;
|
|
47
|
+
if (error instanceof AggregateError) return error.errors.every(isHealableCorruption);
|
|
48
|
+
return true;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
function scopeFiles(request: HealRequest, scope: StateScope): string[] {
|
|
52
|
+
const paths = temporalScopePaths(request.cwd, request.sessionId, scope, request.root, request.sessionKey);
|
|
53
|
+
const semantic = [paths.checkpoint, paths.patches, paths.meta, resolve(paths.directory, "state.json")];
|
|
54
|
+
if (scope !== "session") return semantic;
|
|
55
|
+
const runtime = sessionRuntimePaths(request.cwd, request.sessionId, request.root, request.sessionKey);
|
|
56
|
+
return [...semantic, runtime.config, runtime.runtime];
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function readPresent(path: string): Buffer | undefined {
|
|
60
|
+
const stat = lstatSync(path, { throwIfNoEntry: false });
|
|
61
|
+
if (!stat) return undefined;
|
|
62
|
+
if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`State Flow quarantine refuses a non-regular file: ${JSON.stringify(path)}`);
|
|
63
|
+
return readFileSync(path, { flag: constants.O_RDONLY | constants.O_NOFOLLOW });
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** Exact-byte private record first; canonical files are removed only after the record verifies. */
|
|
67
|
+
function quarantineScope(request: HealRequest, scope: StateScope, reason: string): HealedScope | undefined {
|
|
68
|
+
const root = resolve(request.root);
|
|
69
|
+
const files = scopeFiles(request, scope).map(path => ({ path, bytes: readPresent(path) })).filter(file => file.bytes !== undefined);
|
|
70
|
+
if (files.length === 0) return undefined;
|
|
71
|
+
const at = (request.now?.() ?? new Date()).toISOString();
|
|
72
|
+
const content = `${canonicalJson({ version: 1, kind: "state-flow-quarantine", at, root, cwd: resolve(request.cwd),
|
|
73
|
+
sessionId: request.sessionId, sessionKey: request.sessionKey, scope, reason,
|
|
74
|
+
files: files.map(file => ({ path: relative(root, file.path), bytes: file.bytes!.toString("base64") })) })}\n`;
|
|
75
|
+
const directory = resolve(dirname(root), `${basename(root)}-quarantine`);
|
|
76
|
+
assertStorageDirectory(directory);
|
|
77
|
+
mkdirSync(directory, { recursive: true, mode: 0o700 });
|
|
78
|
+
const directoryStat = lstatSync(directory);
|
|
79
|
+
if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink() || (directoryStat.mode & 0o077) !== 0) {
|
|
80
|
+
throw new Error("State Flow quarantine directory must be private; canonical files preserved");
|
|
81
|
+
}
|
|
82
|
+
const digest = createHash("sha256").update(content).digest("hex").slice(0, 16);
|
|
83
|
+
const path = resolve(directory, `${at.replace(/[:.]/g, "-")}-${scope}-${digest}.json`);
|
|
84
|
+
try { writeFileSync(path, content, { flag: "wx", mode: 0o600 }); }
|
|
85
|
+
catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
|
|
86
|
+
if (readFileSync(path, { encoding: "utf8", flag: constants.O_RDONLY | constants.O_NOFOLLOW }) !== content) {
|
|
87
|
+
throw new Error("State Flow quarantine record changed; canonical files preserved");
|
|
88
|
+
}
|
|
89
|
+
for (const file of files) rmSync(file.path);
|
|
90
|
+
return { scope, reason, quarantine: path };
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
function probe(action: () => unknown, signal?: AbortSignal): Error | undefined {
|
|
94
|
+
try { action(); return undefined; }
|
|
95
|
+
catch (error) {
|
|
96
|
+
// Cancellation reasons are arbitrary values; they never prove corruption.
|
|
97
|
+
signal?.throwIfAborted();
|
|
98
|
+
if (!isHealableCorruption(error)) throw error;
|
|
99
|
+
return error as Error;
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Converge the selected owners to a loadable store: decode each owner independently, then the
|
|
105
|
+
* complete selected cohort. A broken owner is quarantined and becomes wholly absent, which the
|
|
106
|
+
* normal lifecycle treats as empty memory. Healthy stores are never written.
|
|
107
|
+
*/
|
|
108
|
+
export function healSelectedStoreLocked(storage: StorageTransaction, request: HealRequest, signal?: AbortSignal): HealResult {
|
|
109
|
+
const wanted = captureScopeSelection(request.selection);
|
|
110
|
+
const { cwd, sessionId, sessionKey, root, historyLimit } = request;
|
|
111
|
+
const healed: HealedScope[] = [];
|
|
112
|
+
const reset = (scope: StateScope, error: Error) => {
|
|
113
|
+
const result = quarantineScope(request, scope, error.message);
|
|
114
|
+
if (result) healed.push(result);
|
|
115
|
+
};
|
|
116
|
+
for (const scope of wanted.filter(owner => owner !== "session")) {
|
|
117
|
+
const failure = probe(() => storage.observeSelectedShared(cwd, captureScopeSelection([scope]), root), signal);
|
|
118
|
+
if (failure) reset(scope, failure);
|
|
119
|
+
}
|
|
120
|
+
let lifecycle: ReturnType<StorageTransaction["inspectSelectedLifecycle"]>;
|
|
121
|
+
const lifecycleFailure = probe(() => { lifecycle = storage.inspectSelectedLifecycle(cwd, sessionId, wanted, root, sessionKey); }, signal);
|
|
122
|
+
if (lifecycleFailure) {
|
|
123
|
+
reset("session", lifecycleFailure);
|
|
124
|
+
return { healed, lifecycleAbsent: true };
|
|
125
|
+
}
|
|
126
|
+
if (!lifecycle) return { healed, lifecycleAbsent: true };
|
|
127
|
+
if (wanted.includes("session") && lifecycle.runtime.meta.privateAcquisition !== "acquired") return { healed, lifecycleAbsent: false };
|
|
128
|
+
// The session lifecycle anchors cross-owner lineage, so a contradictory cohort resets that private anchor.
|
|
129
|
+
const cohortFailure = probe(() => storage.prepareSelectedCurrent(cwd, sessionId, wanted, historyLimit, root, sessionKey), signal);
|
|
130
|
+
if (cohortFailure) reset("session", cohortFailure);
|
|
131
|
+
return { healed, lifecycleAbsent: cohortFailure !== undefined };
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/** Never waits behind a live writer: a busy store is being used, so healing defers to a later attempt. */
|
|
135
|
+
export async function healSelectedStore(request: HealRequest, signal?: AbortSignal): Promise<HealResult> {
|
|
136
|
+
const root = resolve(request.root);
|
|
137
|
+
if (!lstatSync(root, { throwIfNoEntry: false })) return { healed: [], lifecycleAbsent: true };
|
|
138
|
+
return withStorageTransaction(root, storage => healSelectedStoreLocked(storage, { ...request, root }, signal), signal, false);
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/** One pending reset notice: projected to the model until an agent run settles after seeing it. */
|
|
142
|
+
export class HealNotice {
|
|
143
|
+
#message: string | undefined;
|
|
144
|
+
#projected = false;
|
|
145
|
+
|
|
146
|
+
announce(message: string): void {
|
|
147
|
+
this.#message = message;
|
|
148
|
+
this.#projected = false;
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/** Model-facing text for the current request, marking it as seen. */
|
|
152
|
+
project(): string | undefined {
|
|
153
|
+
if (this.#message === undefined) return undefined;
|
|
154
|
+
this.#projected = true;
|
|
155
|
+
return `${this.#message}. Tell the user about this State Flow memory reset in your next answer.`;
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/** A settled run that saw the notice consumes it; an unseen notice survives. */
|
|
159
|
+
settle(): void {
|
|
160
|
+
if (!this.#projected) return;
|
|
161
|
+
this.#message = undefined;
|
|
162
|
+
this.#projected = false;
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
export function describeHealedScopes(healed: readonly HealedScope[]): string {
|
|
167
|
+
return healed.map(item => `${item.scope} memory was unreadable (${item.reason}) and was reset to empty; original bytes quarantined at ${item.quarantine}`).join("; ");
|
|
168
|
+
}
|
package/lib/logging.ts
CHANGED
|
@@ -3,7 +3,7 @@ import { appendFileSync, closeSync, constants, fstatSync, lstatSync, mkdirSync,
|
|
|
3
3
|
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
|
|
4
4
|
import { isObject } from "./json.ts";
|
|
5
5
|
|
|
6
|
-
export type StateFlowDiagnosticCategory = "invalid-patch" | "publication-conflict" | "finalization" | "barrier-block";
|
|
6
|
+
export type StateFlowDiagnosticCategory = "invalid-patch" | "publication-conflict" | "finalization" | "barrier-block" | "self-heal";
|
|
7
7
|
|
|
8
8
|
/** Minimal structural block; only ordinary text keeps its exact content. */
|
|
9
9
|
export interface StateFlowDiagnosticBlock {
|
|
@@ -92,6 +92,11 @@ export class StateFlowDiagnosticWriter {
|
|
|
92
92
|
return this.write(sessionId, cwd, error, "publication-conflict", {}, false);
|
|
93
93
|
}
|
|
94
94
|
|
|
95
|
+
/** Memory resets are always recorded locally, independently of opt-in logging. */
|
|
96
|
+
recordSelfHeal(sessionId: string, cwd: string, error: string): boolean {
|
|
97
|
+
return this.write(sessionId, cwd, error, "self-heal", {});
|
|
98
|
+
}
|
|
99
|
+
|
|
95
100
|
private write(sessionId: string, cwd: string, error: string, category: StateFlowDiagnosticCategory, extras: DiagnosticExtras, reportFailure = true): boolean {
|
|
96
101
|
try {
|
|
97
102
|
const fromRepository = relative(this.repositoryRoot, this.path);
|