@llblab/pi-state-flow 0.18.0 → 0.19.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.
Files changed (63) hide show
  1. package/AGENTS.md +23 -17
  2. package/BACKLOG.md +5 -3
  3. package/CHANGELOG.md +17 -0
  4. package/README.md +19 -7
  5. package/dist/index.d.ts +2 -1
  6. package/dist/index.js +1 -0
  7. package/dist/lib/artifact.d.ts +2 -2
  8. package/dist/lib/artifact.js +5 -5
  9. package/dist/lib/context.d.ts +3 -2
  10. package/dist/lib/context.js +7 -2
  11. package/dist/lib/continuation.d.ts +5 -5
  12. package/dist/lib/continuation.js +54 -40
  13. package/dist/lib/durable.js +20 -20
  14. package/dist/lib/extension.js +772 -331
  15. package/dist/lib/git.d.ts +6 -2
  16. package/dist/lib/git.js +43 -18
  17. package/dist/lib/logging.d.ts +3 -0
  18. package/dist/lib/logging.js +33 -7
  19. package/dist/lib/protocol.d.ts +4 -0
  20. package/dist/lib/protocol.js +65 -23
  21. package/dist/lib/recovery.d.ts +16 -5
  22. package/dist/lib/recovery.js +32 -15
  23. package/dist/lib/runtime.d.ts +28 -2
  24. package/dist/lib/runtime.js +276 -26
  25. package/dist/lib/session.d.ts +5 -0
  26. package/dist/lib/session.js +36 -2
  27. package/dist/lib/snapshot.d.ts +3 -0
  28. package/dist/lib/snapshot.js +3 -0
  29. package/dist/lib/status.d.ts +1 -0
  30. package/dist/lib/status.js +3 -1
  31. package/dist/lib/storage.d.ts +11 -0
  32. package/dist/lib/storage.js +150 -24
  33. package/dist/lib/telegram.d.ts +14 -1
  34. package/dist/lib/telegram.js +52 -18
  35. package/dist/lib/transition.js +8 -8
  36. package/dist/package.json +1 -1
  37. package/dist/skills/state-flow-guide/SKILL.md +3 -1
  38. package/docs/architecture.md +53 -7
  39. package/docs/compatibility.md +84 -44
  40. package/docs/filesystem-recovery.md +12 -2
  41. package/docs/fork-contract.md +6 -4
  42. package/docs/performance.md +11 -3
  43. package/docs/temporal-acceptance.md +28 -8
  44. package/docs/usage.md +43 -16
  45. package/index.ts +3 -0
  46. package/lib/artifact.ts +5 -5
  47. package/lib/context.ts +8 -3
  48. package/lib/continuation.ts +57 -40
  49. package/lib/durable.ts +20 -20
  50. package/lib/extension.ts +734 -322
  51. package/lib/git.ts +40 -19
  52. package/lib/logging.ts +31 -6
  53. package/lib/protocol.ts +60 -24
  54. package/lib/recovery.ts +34 -21
  55. package/lib/runtime.ts +290 -25
  56. package/lib/session.ts +37 -2
  57. package/lib/snapshot.ts +3 -0
  58. package/lib/status.ts +4 -1
  59. package/lib/storage.ts +141 -22
  60. package/lib/telegram.ts +60 -19
  61. package/lib/transition.ts +8 -8
  62. package/package.json +1 -1
  63. package/skills/state-flow-guide/SKILL.md +3 -1
@@ -12,19 +12,20 @@ import { createPassiveContinuation, currentRunTrajectory, lazyNavigationHint, pa
12
12
  import { readNativeSessionHeader } from "./continuation.js";
13
13
  import { cwdScopeKey, resolveSessionAddress, sessionScopeKey, } from "./durable.js";
14
14
  import { completeRun, prepareRun, resumeEpisode, startEpisode, stopEpisode } from "./episode.js";
15
- import { backupCurrentStateFlowFiles, pushCurrentStateFlowBackup } from "./git.js";
15
+ import { awaitInFlightBackupPushes, backupCurrentStateFlowFiles, startStateFlowBackupPush } from "./git.js";
16
16
  import { projectRecentTransitionsWithLimit } from "./history.js";
17
17
  import { isObject, presentationJson, sameJson } from "./json.js";
18
18
  import { StateFlowDiagnosticWriter, stateFlowLogPath } from "./logging.js";
19
- import { assistantToolCallCount, finalizedAssistantResponse, formatPatchStateArguments, PASSIVE_MEMORY_PROTOCOL, separatedFailure, separatedOutput, stateFlowProtocol } from "./protocol.js";
19
+ import { assistantToolCallCount, conciseDiagnostic, diagnosticText, finalizedAssistantResponse, formatPatchStateArguments, PASSIVE_MEMORY_PROTOCOL, separatedFailure, separatedOutput, stateFlowProtocol } from "./protocol.js";
20
20
  import { readProjectedState, readStatePath } from "./query.js";
21
- import { recoverSnapshot } from "./recovery.js";
22
- import { SharedScopeRemovalConflictError, TemporalRuntime } from "./runtime.js";
23
- import { discoverSnapshotData, findAssistantToolBatch, findPassiveStopBoundary, hasPriorConversation, isNewSession, retainsPhysicalSessionProjection, SNAPSHOT_ENTRY_TYPE } from "./session.js";
21
+ import { selectedBoundaryFailure, selectRetainedCheckpoint, waitForRecovery } from "./recovery.js";
22
+ import { TemporalRuntime } from "./runtime.js";
23
+ import { discoverSnapshotData, findAssistantToolBatch, findPassiveStopBoundary, hasPriorConversation, hasUncheckpointedConversation, isNewSession, retainsPhysicalSessionProjection, SNAPSHOT_ENTRY_TYPE } from "./session.js";
24
24
  import { hasCompiledSkillArtifact, hashSkillSource, registeredSkillResolver, SkillReadTracker } from "./skills.js";
25
- import { emptySnapshot, migrationFailure } from "./snapshot.js";
25
+ import { HistoryBoundaryExpiredError, emptySnapshot, migrationFailure } from "./snapshot.js";
26
26
  import { emptyState, overlayStates, projectStateForModel } from "./state.js";
27
27
  import { compactStatus, detailedStatus, STATUS_KEY } from "./status.js";
28
+ import { PublicationBusyError } from "./storage.js";
28
29
  import { createStateFlowTelegramAdapter } from "./telegram.js";
29
30
  import { temporalScopeRevisions } from "./temporal.js";
30
31
  import { commitScopedTransition, stageAtomicScopePatches, stageScopedTransition } from "./transition.js";
@@ -42,10 +43,16 @@ export default function stateFlowExtension(pi, options = {}) {
42
43
  };
43
44
  let snapshot = emptySnapshot();
44
45
  let scopeStates = { global: emptyState(), cwd: emptyState(), session: emptyState() };
45
- let branchHasSnapshot = false;
46
46
  let branchStartsWithoutRuntime = false;
47
+ let selectedHistoryExpired = false;
48
+ let stopPersistenceError;
49
+ let stopPersistence;
50
+ let startActivation;
47
51
  let forkInitialization = false;
48
- let responseAwaitingReconciliation = false;
52
+ let branchRestoration;
53
+ const restorationOperations = new Set();
54
+ let responseReconciliation;
55
+ let sharedInspectionLifetime = new AbortController();
49
56
  let completedRunAccepted = false;
50
57
  let turnAcceptedForBackup = false;
51
58
  let compactionPlan;
@@ -54,7 +61,7 @@ export default function stateFlowExtension(pi, options = {}) {
54
61
  const compactionMarker = `state-flow-boundary:${randomUUID()}`;
55
62
  let passiveContinuation;
56
63
  let bootstrapContinuation;
57
- let artifactRefreshPending = false;
64
+ let inferencePreparation;
58
65
  let runAnchorTimestamp;
59
66
  let runtime;
60
67
  let activeContext;
@@ -62,6 +69,10 @@ export default function stateFlowExtension(pi, options = {}) {
62
69
  const repositoryRoot = resolve(options.repositoryRoot ?? config.directory);
63
70
  const diagnosticWriter = new StateFlowDiagnosticWriter(config.logging, stateFlowLogPath(agentDir), repositoryRoot, (message) => notifyActiveContext(message));
64
71
  let backupPending = false;
72
+ const backupLifetime = new AbortController();
73
+ const backupOperations = new Set();
74
+ let shuttingDown = false;
75
+ let pushFailureNotified = false;
65
76
  const skillReads = new SkillReadTracker(hashSkillSource, (path) => activeContext
66
77
  ? registeredSkillResolver(activeContext.cwd, pi.getCommands())(path)
67
78
  : undefined);
@@ -73,9 +84,13 @@ export default function stateFlowExtension(pi, options = {}) {
73
84
  function sessionAddress(ctx) {
74
85
  return resolveSessionAddress(ctx.sessionManager.getSessionFile(), ctx.sessionManager.getSessionId(), ctx.sessionManager.getHeader()?.timestamp);
75
86
  }
87
+ function notifyProblem(ctx, message, level) {
88
+ ctx.ui.notify(conciseDiagnostic(message), level);
89
+ }
76
90
  function notifyActiveContext(message) {
77
91
  try {
78
- activeContext?.ui.notify(message, "warning");
92
+ if (activeContext)
93
+ notifyProblem(activeContext, message, "warning");
79
94
  }
80
95
  catch {
81
96
  // An asynchronous push attempt can outlive the Pi context that launched it.
@@ -89,7 +104,7 @@ export default function stateFlowExtension(pi, options = {}) {
89
104
  }
90
105
  function assertSelectedBranchAvailable() {
91
106
  if (snapshot.meta.validation?.attempt === 0) {
92
- throw new Error(`State Flow selected branch is unavailable: ${snapshot.meta.validation.error}. Restore its canonical files and retry /state-flow-start, or select a retained boundary.`);
107
+ throw new Error(`State Flow selected branch is unavailable: ${snapshot.meta.validation.error}`);
93
108
  }
94
109
  }
95
110
  options.onRuntime?.({ read: (offset, scope) => {
@@ -99,14 +114,12 @@ export default function stateFlowExtension(pi, options = {}) {
99
114
  throw new Error("State Flow temporal runtime is unavailable");
100
115
  return projectModelState(runtime.read(offset, scope));
101
116
  } });
102
- function persist() {
117
+ function assertPublicationAvailable() {
103
118
  assertSelectedBranchAvailable();
104
- const previousView = runtime?.view;
105
- const publication = !branchStartsWithoutRuntime && runtime?.view ? runtime.publish(snapshot, false, undefined) : undefined;
106
- if (runtime?.view !== previousView)
107
- installScopeStates();
108
- if (publication && activeContext)
109
- recordPublication(publication, activeContext);
119
+ if (stopPersistenceError)
120
+ throw new Error(`Memory writes paused after Stop: ${stopPersistenceError}; use /state-flow-start`);
121
+ }
122
+ function appendCheckpoint() {
110
123
  const checkpoint = branchStartsWithoutRuntime ? { disabled: true } : runtime?.retainedCheckpoint(snapshot) ?? { disabled: true };
111
124
  if ("disabled" in checkpoint && !branchStartsWithoutRuntime) {
112
125
  throw new Error("State Flow cannot checkpoint an unproven branch as ordinary disabled; restore a valid checkpoint first");
@@ -123,8 +136,40 @@ export default function stateFlowExtension(pi, options = {}) {
123
136
  function updateUi(ctx) {
124
137
  ctx.ui.setStatus(STATUS_KEY, compactStatus(snapshot, scopeRevisions(), (color, text) => ctx.ui.theme.fg(color, text)));
125
138
  }
139
+ function cancelStopPersistence() {
140
+ const pending = stopPersistence;
141
+ pending?.controller.abort();
142
+ stopPersistence = undefined;
143
+ return pending?.operation;
144
+ }
145
+ function cancelStartActivation() {
146
+ const pending = startActivation;
147
+ pending?.controller.abort();
148
+ startActivation = undefined;
149
+ return pending?.operation;
150
+ }
151
+ function cancelBranchRestoration() {
152
+ const pending = branchRestoration;
153
+ pending?.controller.abort();
154
+ branchRestoration = undefined;
155
+ return pending?.operation;
156
+ }
157
+ function cancelResponseReconciliation() {
158
+ responseReconciliation?.abort();
159
+ responseReconciliation = undefined;
160
+ }
161
+ function cancelSharedInspections() {
162
+ sharedInspectionLifetime.abort(new Error("State Flow inspection was cancelled; select the scope again"));
163
+ sharedInspectionLifetime = new AbortController();
164
+ }
165
+ function cancelInferencePreparation() {
166
+ inferencePreparation?.controller.abort();
167
+ inferencePreparation = undefined;
168
+ }
126
169
  function clearRunTransient() {
127
- responseAwaitingReconciliation = false;
170
+ cancelInferencePreparation();
171
+ cancelResponseReconciliation();
172
+ cancelSharedInspections();
128
173
  completedRunAccepted = false;
129
174
  turnAcceptedForBackup = false;
130
175
  compactionPlan = undefined;
@@ -132,10 +177,11 @@ export default function stateFlowExtension(pi, options = {}) {
132
177
  skillReads.clear();
133
178
  artifactReads.clear();
134
179
  }
135
- function deferArtifactRefresh() {
180
+ function deferInferencePreparation(prompt) {
181
+ cancelInferencePreparation();
182
+ inferencePreparation = { controller: new AbortController(), prompt };
136
183
  artifactInvalidations = [];
137
184
  artifactReads.setCandidates([]);
138
- artifactRefreshPending = true;
139
185
  }
140
186
  function refreshArtifactHints() {
141
187
  if (!runtime?.view) {
@@ -173,12 +219,10 @@ export default function stateFlowExtension(pi, options = {}) {
173
219
  artifactInvalidations = [...nextInvalidations.values()].sort((left, right) => left.path.localeCompare(right.path));
174
220
  artifactReads.setCandidates(artifactInvalidations);
175
221
  }
176
- function removeMissingRegisteredArtifacts(ctx) {
177
- if (!snapshot.config.enabled || !runtime?.view)
178
- return;
222
+ function missingArtifactRemovals(states) {
179
223
  const owners = new Map();
180
224
  for (const scope of ["global", "cwd", "session"])
181
- for (const path of Object.keys(scopeStates[scope].artifacts)) {
225
+ for (const path of Object.keys(states[scope].artifacts)) {
182
226
  owners.set(path, [...owners.get(path) ?? [], scope]);
183
227
  }
184
228
  const removals = {};
@@ -190,12 +234,7 @@ export default function stateFlowExtension(pi, options = {}) {
190
234
  removals[scope] = { ...(removals[scope] ?? {}), artifacts: { ...artifacts, [observation.path]: null } };
191
235
  }
192
236
  }
193
- if (Object.keys(removals).length > 0) {
194
- const stage = stageAtomicScopePatches(scopeStates, removals, [], runtime.causalBasis());
195
- commitStage(stage, ctx, false);
196
- updateUi(ctx);
197
- }
198
- refreshArtifactHints();
237
+ return removals;
199
238
  }
200
239
  function installScopeStates() {
201
240
  scopeStates = runtime?.view ? runtime.states() : { global: emptyState(), cwd: emptyState(), session: emptyState() };
@@ -203,19 +242,27 @@ export default function stateFlowExtension(pi, options = {}) {
203
242
  function passiveToolsAvailable() {
204
243
  return snapshot.config.enabled || config.passiveTools;
205
244
  }
206
- function refreshTelegramStateView(scope) {
245
+ async function inspectTelegramState(scope) {
246
+ if (!activeContext || shuttingDown)
247
+ throw new Error("State Flow is not attached to an active session yet");
207
248
  if (scope === "session" || scope === "effective")
208
249
  assertSelectedBranchAvailable();
209
- if (!runtime?.view) {
210
- if (!activeContext)
211
- throw new Error("State Flow is not attached to an active session yet");
212
- runtime ??= createRuntime(activeContext);
213
- runtime.loadPassive();
214
- }
215
- else if (scope !== "session") {
216
- runtime.refreshShared();
217
- }
250
+ const selected = runtime ??= createRuntime(activeContext);
251
+ const signal = sharedInspectionLifetime.signal;
252
+ if (!selected.view || (scope !== "session" && !stopPersistenceError))
253
+ await selected.refreshShared(signal);
254
+ signal.throwIfAborted();
255
+ if (runtime !== selected)
256
+ throw new Error("State Flow inspection selection changed; select the scope again");
257
+ if (scope === "session" || scope === "effective")
258
+ assertSelectedBranchAvailable();
259
+ if (!selected.view)
260
+ throw new Error("State Flow temporal runtime is unavailable");
218
261
  installScopeStates();
262
+ const state = scope === "effective"
263
+ ? overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)
264
+ : scopeStates[scope];
265
+ return { state: { ...projectModelState(state), lazy: structuredClone(state.lazy) }, revisions: scopeRevisions(), signal };
219
266
  }
220
267
  function syncStateFlowTools() {
221
268
  const active = pi.getActiveTools();
@@ -252,34 +299,65 @@ export default function stateFlowExtension(pi, options = {}) {
252
299
  const target = `${read.scope}.artifacts[${JSON.stringify(read.path)}]`;
253
300
  return `State Flow acquisition: this registered Skill belongs at ${target}. If durable compiled guidance is useful, include a non-empty description, kind:"skill", and compilation object there. Unrelated semantic patches do not need to include it.`;
254
301
  }
255
- function commitStage(stage, ctx, finalizeRun) {
256
- const acquiredArtifactPaths = new Set(artifactReads.successful.keys());
257
- let committed;
302
+ function clearAcceptedAcquisitions(acquiredArtifactPaths = new Set(artifactReads.successful.keys())) {
303
+ artifactInvalidations = artifactInvalidations.filter(({ path }) => !acquiredArtifactPaths.has(path));
304
+ artifactReads.setCandidates(artifactInvalidations);
305
+ dropCurrentSkillReads();
306
+ artifactReads.clear();
307
+ }
308
+ async function prepareInference(pending, selected, ctx, operationSignal) {
309
+ const signal = AbortSignal.any([pending.controller.signal, operationSignal]);
258
310
  try {
259
- committed = commitScopedTransition(snapshot, scopeStates, stage, (accepted, nextSnapshot) => {
260
- if (!runtime?.view)
261
- throw new Error("Temporal State Flow runtime is unavailable; reload before publishing");
262
- const publication = runtime.publish(nextSnapshot, accepted !== undefined, accepted, {
263
- provenance: stage.provenanceUpdates,
264
- });
265
- if (publication)
311
+ if (!selected?.view)
312
+ throw new Error("Temporal State Flow runtime is unavailable; reload before publishing");
313
+ await selected.withPatchTransaction((transaction) => {
314
+ signal.throwIfAborted();
315
+ if (runtime !== selected || inferencePreparation !== pending || !snapshot.config.enabled || shuttingDown) {
316
+ throw new Error("State Flow inference selection changed while awaiting publication");
317
+ }
318
+ assertPublicationAvailable();
319
+ const nextSnapshot = structuredClone(snapshot);
320
+ const rotatesRun = pending.prompt !== undefined && nextSnapshot.meta.specification !== undefined;
321
+ if (pending.prompt !== undefined)
322
+ prepareRun(nextSnapshot, pending.prompt);
323
+ // Exact-path metadata validation belongs to the locked current head, including newly adopted registrations.
324
+ const removals = missingArtifactRemovals(transaction.states);
325
+ let publication;
326
+ if (Object.keys(removals).length > 0) {
327
+ const stage = stageAtomicScopePatches(transaction.states, removals, [], transaction.causalBasis);
328
+ commitScopedTransition(nextSnapshot, transaction.states, stage, (transition, next) => {
329
+ publication = transaction.publish(next, transition);
330
+ pending.accepted = true;
331
+ }, transaction.causalBasis, { finalizeRun: false });
332
+ }
333
+ else {
334
+ publication = transaction.publish(nextSnapshot);
335
+ pending.accepted = true;
336
+ }
337
+ snapshot = nextSnapshot;
338
+ installScopeStates();
339
+ if (rotatesRun && rehydrationPhase !== "new-bootstrap" && rehydrationPhase !== "resume-bootstrap")
340
+ rehydrationPhase = "step";
341
+ if (publication?.changed)
266
342
  recordPublication(publication, ctx);
267
- }, runtime.causalBasis(), { finalizeRun });
343
+ if (pending.prompt !== undefined || publication?.changed)
344
+ appendCheckpoint();
345
+ if (Object.keys(removals).length > 0)
346
+ clearAcceptedAcquisitions();
347
+ updateUi(ctx);
348
+ }, signal);
268
349
  }
269
350
  catch (error) {
270
- if (error instanceof SharedScopeRemovalConflictError)
271
- installScopeStates();
272
- throw error;
351
+ if (signal.aborted || runtime !== selected || inferencePreparation !== pending || shuttingDown)
352
+ return;
353
+ // Pi reports context-hook exceptions and continues. Abort through its public port rather than infer from stale preparation.
354
+ ctx.abort();
355
+ const cause = diagnosticText(error);
356
+ recordDiagnostic(cause, "publication-conflict", ctx);
357
+ notifyProblem(ctx, pending.accepted
358
+ ? `State Flow preparation saved; lifecycle update failed: ${cause}`
359
+ : `State Flow inference preparation failed: ${cause}`, "error");
273
360
  }
274
- if (!committed)
275
- return false;
276
- installScopeStates();
277
- artifactInvalidations = artifactInvalidations.filter(({ path }) => !acquiredArtifactPaths.has(path));
278
- artifactReads.setCandidates(artifactInvalidations);
279
- dropCurrentSkillReads();
280
- artifactReads.clear();
281
- persist();
282
- return true;
283
361
  }
284
362
  function currentRehydrationPhase() {
285
363
  return rehydrationPhase;
@@ -310,6 +388,7 @@ export default function stateFlowExtension(pi, options = {}) {
310
388
  } }),
311
389
  staleArtifacts,
312
390
  ...(durableStateError === undefined ? {} : { durableStateError }),
391
+ ...(stopPersistenceError === undefined ? {} : { publicationError: stopPersistenceError }),
313
392
  };
314
393
  }
315
394
  function forkSource(ctx) {
@@ -321,122 +400,255 @@ export default function stateFlowExtension(pi, options = {}) {
321
400
  throw new Error("State Flow fork parent CWD identity mismatch");
322
401
  return resolveSessionAddress(parent.file, parent.id, parent.timestamp);
323
402
  }
324
- function restoreActiveBranch(ctx, sessionStartReason) {
403
+ /** Select the active native branch under one owned restoration lifetime; only current accepted work installs memory. */
404
+ function restoreActiveBranch(ctx, sessionStartReason, notifyRecovery = true, startOwner) {
405
+ cancelBranchRestoration();
406
+ // Start-owned attachment/fork recovery keeps its owner; only accepted Start cancels Stop.
407
+ if (!startOwner) {
408
+ cancelStartActivation();
409
+ cancelStopPersistence();
410
+ }
325
411
  clearRunTransient();
326
412
  passiveContinuation = undefined;
327
413
  bootstrapContinuation = undefined;
328
414
  artifactInvalidations = [];
329
415
  artifactReads.setCandidates([]);
330
- artifactRefreshPending = false;
331
416
  telegramStartPending = false;
332
417
  activeContext = ctx;
333
- const session = sessionAddress(ctx);
334
- runtime = new TemporalRuntime(ctx.cwd, session, repositoryRoot, undefined, config.historyLimit);
418
+ runtime = createRuntime(ctx);
335
419
  installScopeStates();
336
- branchHasSnapshot = false;
337
420
  branchStartsWithoutRuntime = false;
421
+ selectedHistoryExpired = false;
338
422
  forkInitialization = sessionStartReason === "fork";
423
+ let selection = { kind: "settled" };
424
+ let skipped = 0;
339
425
  try {
340
426
  const branch = ctx.sessionManager.getBranch();
341
- const discovery = discoverSnapshotData(branch);
342
- let restoreSelected;
343
- const recovery = recoverSnapshot(discovery.candidates, (checkpoint) => {
344
- if (forkInitialization) {
345
- const prepared = runtime.prepareBoundaryFork(forkSource(ctx), checkpoint);
346
- restoreSelected = () => {
347
- const accepted = prepared.fork();
348
- snapshot = accepted.snapshot;
349
- recordPolicyPublication(accepted.publication, ctx);
350
- pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, { reset: true, owner: ctx.sessionManager.getSessionId() });
351
- forkInitialization = false;
352
- return snapshot;
353
- };
354
- return prepared.snapshot;
355
- }
356
- const prepared = runtime.prepareBoundaryRestore(checkpoint);
357
- restoreSelected = () => {
358
- const restored = prepared.restore();
359
- const publication = runtime.acceptRestoredOrigin(restored);
360
- recordPolicyPublication(publication, ctx);
361
- return restored;
362
- };
363
- return prepared.snapshot;
364
- });
365
- branchStartsWithoutRuntime = recovery.disabledMarker === true
366
- || (discovery.candidates.length === 0 && discovery.errors.length === 0);
367
- const skipped = discovery.errors.length + recovery.skipped.length;
368
- branchHasSnapshot = recovery.skipped.length < discovery.candidates.length;
369
- if (discovery.candidates.length === 0 && discovery.errors.length > 0) {
370
- snapshot = migrationFailure({}, `Snapshot restoration failed: ${discovery.errors[0]}`);
427
+ const fence = retainsPhysicalSessionProjection(sessionStartReason)
428
+ ? findPassiveStopBoundary(branch, ctx.sessionManager.getSessionId(), PASSIVE_STOP_ENTRY_TYPE)?.persistenceError
429
+ : undefined;
430
+ stopPersistenceError = fence ?? (startOwner ? stopPersistenceError : undefined);
431
+ if (fence) {
432
+ // The native Stop owns policy only: read proven memory, never replay or publish a stale selection.
433
+ selection = { kind: "current" };
371
434
  }
372
- else if (discovery.candidates.length > 0) {
373
- snapshot = recovery.snapshot;
374
- if (branchHasSnapshot && restoreSelected) {
375
- snapshot = restoreSelected();
376
- persist();
435
+ else {
436
+ const discovery = discoverSnapshotData(branch);
437
+ const selected = selectRetainedCheckpoint(discovery.candidates);
438
+ skipped = discovery.errors.length + selected.skipped.length;
439
+ branchStartsWithoutRuntime = selected.kind === "disabled" || (discovery.candidates.length === 0 && discovery.errors.length === 0);
440
+ if (discovery.candidates.length === 0 && discovery.errors.length > 0) {
441
+ snapshot = migrationFailure({}, `Snapshot restoration failed: ${discovery.errors[0]}`);
377
442
  }
378
- else if (branchHasSnapshot && snapshot.config.enabled) {
379
- const publication = runtime.initialize(snapshot, true);
380
- recordPolicyPublication(publication, ctx);
443
+ else if (selected.kind === "boundary" && forkInitialization) {
444
+ try {
445
+ // Native parent acquisition stays outside canonical exclusion.
446
+ const source = forkSource(ctx);
447
+ const sourceStopped = findPassiveStopBoundary(branch, source.id, PASSIVE_STOP_ENTRY_TYPE)?.persistenceError !== undefined;
448
+ selection = { kind: "fork", source, checkpoint: sourceStopped ? { ...selected.checkpoint, enabled: false } : selected.checkpoint };
449
+ }
450
+ catch (error) {
451
+ snapshot = selectedBoundaryFailure(diagnosticText(error));
452
+ }
381
453
  }
382
- installScopeStates();
383
- }
384
- else if (config.autoStart && isNewSession(sessionStartReason, branch)) {
385
- snapshot = startEpisode(hasPriorConversation(branch));
386
- runtime.prepare();
387
- const initialization = runtime.initialize(snapshot, true);
388
- recordPolicyPublication(initialization, ctx);
389
- if (!runtime.view)
454
+ else if (selected.kind === "boundary") {
455
+ selection = { kind: "restore", checkpoint: selected.checkpoint };
456
+ }
457
+ else if (discovery.candidates.length > 0) {
458
+ snapshot = selected.kind === "disabled" ? emptySnapshot() : selected.snapshot;
459
+ }
460
+ else if (config.autoStart && isNewSession(sessionStartReason, branch)) {
461
+ selection = { kind: "auto-start" };
462
+ }
463
+ else {
390
464
  snapshot = emptySnapshot();
391
- installScopeStates();
392
- if (snapshot.config.enabled) {
393
- branchHasSnapshot = true;
394
- persist();
395
465
  }
396
466
  }
397
- else {
398
- snapshot = emptySnapshot();
399
- installScopeStates();
467
+ }
468
+ catch (error) {
469
+ selection = { kind: "settled" };
470
+ snapshot = selectedBoundaryFailure(diagnosticText(error));
471
+ }
472
+ // Pending selection grants neither private reads nor publication until its acceptance installs memory.
473
+ if (selection.kind !== "settled")
474
+ snapshot = migrationFailure({}, "State Flow branch restoration is pending");
475
+ const pending = {
476
+ controller: new AbortController(),
477
+ awaitingAcceptance: selection.kind !== "settled" && selection.kind !== "current",
478
+ };
479
+ branchRestoration = pending;
480
+ const operation = attachBranch(ctx, pending, selection, sessionStartReason, notifyRecovery, skipped);
481
+ pending.operation = operation;
482
+ restorationOperations.add(operation);
483
+ const finished = () => { restorationOperations.delete(operation); };
484
+ void operation.then(finished, finished);
485
+ return operation;
486
+ }
487
+ async function attachBranch(ctx, pending, selection, reason, notifyRecovery, skipped) {
488
+ const placeholder = runtime;
489
+ let selected = runtime;
490
+ const owner = ctx.sessionManager.getSessionId();
491
+ const cwd = ctx.cwd;
492
+ const file = ctx.sessionManager.getSessionFile();
493
+ const timestamp = ctx.sessionManager.getHeader()?.timestamp;
494
+ const signal = AbortSignal.any([pending.controller.signal, ...(ctx.signal ? [ctx.signal] : [])]);
495
+ const isCurrent = () => branchRestoration === pending && !pending.controller.signal.aborted && !shuttingDown && runtime === selected
496
+ && ctx.cwd === cwd && ctx.sessionManager.getSessionId() === owner && ctx.sessionManager.getSessionFile() === file
497
+ && ctx.sessionManager.getHeader()?.timestamp === timestamp;
498
+ const assertCurrent = () => {
499
+ signal.throwIfAborted();
500
+ if (!isCurrent())
501
+ throw new Error("State Flow branch selection changed while awaiting publication");
502
+ };
503
+ let accepted = false;
504
+ // Install accepted memory before native writes; later ancillary failures cannot revert or replay it.
505
+ const accept = (candidate, next, publication, nativeWrites) => {
506
+ accepted = true;
507
+ pending.awaitingAcceptance = false;
508
+ runtime = selected = candidate;
509
+ snapshot = next;
510
+ installScopeStates();
511
+ recordPolicyPublication(publication, ctx);
512
+ let failure;
513
+ try {
514
+ nativeWrites();
400
515
  }
401
- if (snapshot.config.enabled && skipped > 0) {
402
- ctx.ui.notify(`State Flow recovered the previous valid snapshot after skipping ${skipped} malformed newer snapshot(s).`, "warning");
516
+ catch (error) {
517
+ failure = error;
403
518
  }
519
+ settleSelection(ctx, reason, notifyRecovery, skipped, true);
520
+ if (failure !== undefined)
521
+ throw failure;
522
+ };
523
+ try {
524
+ if (selection.kind !== "settled") {
525
+ // Local policy is already passive while the selection waits for exclusion.
526
+ syncStateFlowTools();
527
+ updateUi(ctx);
528
+ const candidate = createRuntime(ctx);
529
+ try {
530
+ if (selection.kind === "current") {
531
+ const current = await candidate.refreshCurrentMemory(signal);
532
+ assertCurrent();
533
+ if (current)
534
+ runtime = selected = candidate;
535
+ snapshot = current ?? migrationFailure({}, "Current State Flow session memory is unavailable");
536
+ installScopeStates();
537
+ }
538
+ else if (selection.kind === "restore") {
539
+ await candidate.withRestoreTransaction(selection.checkpoint, (restored, publish) => {
540
+ assertCurrent();
541
+ // Canceled preparation or boundary continuation may have no specification. Retain uncompiled native context.
542
+ if (restored.config.enabled && restored.meta.specification === undefined
543
+ && retainsPhysicalSessionProjection(reason) && hasUncheckpointedConversation(ctx.sessionManager.getBranch()))
544
+ restored.meta.bootstrap = true;
545
+ const next = pending.passiveRequested ? stopEpisode(restored) : restored;
546
+ accept(candidate, next, publish(next), appendCheckpoint);
547
+ }, signal);
548
+ }
549
+ else if (selection.kind === "fork") {
550
+ await candidate.withForkTransaction(selection.source, selection.checkpoint, (child, publish) => {
551
+ assertCurrent();
552
+ // Mode is selected independently of creating the child's private memory.
553
+ const next = pending.passiveRequested ? stopEpisode(child) : child;
554
+ const publication = publish(next);
555
+ forkInitialization = false;
556
+ accept(candidate, next, publication, () => {
557
+ pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, { reset: true, owner });
558
+ appendCheckpoint();
559
+ });
560
+ }, signal);
561
+ }
562
+ else {
563
+ await candidate.withStartTransaction((current, publish) => {
564
+ assertCurrent();
565
+ // Truly new branch authority is rechecked after waiting; existing memory needs its own selection.
566
+ const branch = ctx.sessionManager.getBranch();
567
+ const discovery = discoverSnapshotData(branch);
568
+ if (current || discovery.candidates.length > 0 || discovery.errors.length > 0)
569
+ throw new Error("Existing session runtime requires retained-boundary restoration");
570
+ const activated = startEpisode(hasPriorConversation(branch));
571
+ const next = pending.passiveRequested ? stopEpisode(activated) : activated;
572
+ accept(candidate, next, publish(next), appendCheckpoint);
573
+ }, signal, true);
574
+ }
575
+ }
576
+ catch (error) {
577
+ if (accepted) {
578
+ if (isCurrent())
579
+ notifyProblem(ctx, `State Flow memory restored; lifecycle update failed: ${diagnosticText(error)}`, "warning");
580
+ return;
581
+ }
582
+ if (!isCurrent())
583
+ return;
584
+ if (error instanceof HistoryBoundaryExpiredError)
585
+ selectedHistoryExpired = true;
586
+ snapshot = selectedBoundaryFailure(diagnosticText(error));
587
+ installScopeStates();
588
+ }
589
+ finally {
590
+ pending.awaitingAcceptance = false;
591
+ }
592
+ if (accepted)
593
+ return;
594
+ }
595
+ settleSelection(ctx, reason, notifyRecovery, skipped, selected !== placeholder);
596
+ if (snapshot.config.enabled || !(config.passiveBootstrap || config.passiveTools) || runtime?.view)
597
+ return;
598
+ const passive = createRuntime(ctx);
599
+ const priorView = selected?.view;
600
+ try {
601
+ await passive.refreshShared(signal);
602
+ }
603
+ catch (error) {
604
+ if (isCurrent() && !signal.aborted && notifyRecovery && !stopPersistenceError)
605
+ notifyProblem(ctx, `State Flow passive memory is unavailable: ${diagnosticText(error)}`, "warning");
606
+ return;
607
+ }
608
+ assertCurrent();
609
+ // An intervening passive patch or inspection owns its newer cache, even on the same physical branch.
610
+ if (selected?.view !== priorView)
611
+ return;
612
+ runtime = selected = passive;
613
+ installScopeStates();
614
+ updateUi(ctx);
404
615
  }
405
616
  catch (error) {
406
- const failure = migrationFailure({}, `Snapshot restoration failed: ${error instanceof Error ? error.message : String(error)}`);
407
- snapshot = {
408
- ...snapshot,
409
- config: { ...snapshot.config, enabled: false },
410
- meta: { ...snapshot.meta, validation: failure.meta.validation },
411
- };
412
- }
413
- if (!snapshot.config.enabled && snapshot.meta.validation?.attempt === 0) {
414
- // A failed acceptance may have installed a prepared view; only shared passive reads may survive.
415
- runtime = createRuntime(ctx);
617
+ // Host failures before acceptance leave the selection unavailable, never invented empty memory.
618
+ if (accepted || !isCurrent())
619
+ return;
620
+ snapshot = selectedBoundaryFailure(diagnosticText(error));
416
621
  installScopeStates();
417
- ctx.ui.notify(`State Flow restored disabled: ${snapshot.meta.validation.error}`, "error");
418
622
  }
419
- if (retainsPhysicalSessionProjection(sessionStartReason) && runtime?.view) {
623
+ finally {
624
+ pending.awaitingAcceptance = false;
625
+ if (branchRestoration === pending)
626
+ branchRestoration = undefined;
627
+ }
628
+ }
629
+ function settleSelection(ctx, reason, notifyRecovery, skipped, selectedMemory) {
630
+ const failure = !snapshot.config.enabled && snapshot.meta.validation?.attempt === 0 ? snapshot.meta.validation.error : undefined;
631
+ if (failure !== undefined && notifyRecovery && !stopPersistenceError) {
632
+ if (selectedHistoryExpired)
633
+ notifyProblem(ctx, "State Flow history is outside the retained temporal window; /state-flow-start can use current session memory.", "warning");
634
+ else
635
+ notifyProblem(ctx, `State Flow restore failed: ${failure}`, "error");
636
+ }
637
+ if (selectedMemory && retainsPhysicalSessionProjection(reason) && runtime?.view) {
420
638
  const boundary = findPassiveStopBoundary(ctx.sessionManager.getBranch(), ctx.sessionManager.getSessionId(), PASSIVE_STOP_ENTRY_TYPE);
421
639
  if (boundary !== undefined) {
422
- const continuation = createPassiveContinuation(projectModelState(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)), boundary.at, boundary.from);
640
+ const continuation = createPassiveContinuation(projectModelState(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)), boundary.at, boundary.from, boundary.preserveContext);
423
641
  if (!snapshot.config.enabled)
424
642
  passiveContinuation = continuation;
425
643
  else if (snapshot.meta.bootstrap)
426
644
  bootstrapContinuation = continuation;
427
645
  }
428
646
  }
429
- if (!snapshot.config.enabled && (config.passiveBootstrap || config.passiveTools) && !runtime?.view) {
430
- try {
431
- runtime?.loadPassive();
432
- installScopeStates();
433
- }
434
- catch (error) {
435
- ctx.ui.notify(`State Flow passive memory is unavailable: ${error instanceof Error ? error.message : String(error)}`, "warning");
436
- }
647
+ if (notifyRecovery && snapshot.config.enabled && skipped > 0) {
648
+ notifyProblem(ctx, `State Flow skipped ${skipped} malformed snapshot(s); restored the last valid one.`, "warning");
437
649
  }
438
650
  if (snapshot.config.enabled)
439
- deferArtifactRefresh();
651
+ deferInferencePreparation();
440
652
  syncStateFlowTools();
441
653
  updateUi(ctx);
442
654
  }
@@ -520,11 +732,12 @@ export default function stateFlowExtension(pi, options = {}) {
520
732
  try {
521
733
  if (!passiveToolsAvailable())
522
734
  throw new Error("State Flow tools are disabled by configuration");
523
- assertSelectedBranchAvailable();
735
+ assertPublicationAvailable();
524
736
  if (signal?.aborted)
525
737
  throw new Error("State Flow patch was aborted before materialization");
526
738
  if (!isObject(params))
527
739
  throw new Error("patch_state requires an object");
740
+ params = structuredClone(params);
528
741
  const allowed = new Set(["global", "cwd", "session"]);
529
742
  for (const key of Object.keys(params)) {
530
743
  if (!allowed.has(key))
@@ -543,31 +756,43 @@ export default function stateFlowExtension(pi, options = {}) {
543
756
  }
544
757
  const scopes = Object.keys(patches);
545
758
  if (scopes.length === 0)
546
- throw new Error("patch_state requires at least one materially changed scope patch");
547
- if (!runtime?.view) {
548
- runtime ??= createRuntime(ctx);
549
- runtime.prepare();
550
- const publication = runtime.initialize(snapshot, true, undefined, true);
551
- recordPolicyPublication(publication, ctx);
759
+ throw new Error("patch_state requires at least one scope patch");
760
+ const selected = runtime ??= createRuntime(ctx);
761
+ const acquiredArtifacts = structuredClone([...artifactReads.successful.values()]);
762
+ const acquiredSkills = structuredClone([...skillReads.successful.values()]);
763
+ return await selected.withPatchTransaction((transaction) => {
764
+ if (runtime !== selected)
765
+ throw new Error("State Flow session selection changed while awaiting publication");
766
+ if (!passiveToolsAvailable())
767
+ throw new Error("State Flow tools are disabled by configuration");
768
+ assertPublicationAvailable();
769
+ for (const acquired of acquiredArtifacts) {
770
+ const observation = inspectRegisteredArtifactPaths([acquired.path])[0];
771
+ if (acquired.sourceFingerprint === undefined || observation?.kind !== "present"
772
+ || !sameArtifactSourceFingerprint(acquired.sourceFingerprint, observation.fingerprint)) {
773
+ throw new Error(`Artifact source changed after acquisition: ${acquired.path}`);
774
+ }
775
+ }
776
+ const stage = stageAtomicScopePatches(transaction.states, patches, acquiredSkills, transaction.causalBasis, acquiredArtifacts);
777
+ const changed = ["global", "cwd", "session"].some((scope) => !sameJson(transaction.states[scope], stage.nextStates[scope])
778
+ || Object.entries(stage.provenanceUpdates[scope]).some(([path, evidence]) => !Object.hasOwn(transaction.provenance[scope], path) || !sameJson(transaction.provenance[scope][path], evidence)));
779
+ const nextSnapshot = structuredClone(snapshot);
780
+ let publication;
781
+ commitScopedTransition(nextSnapshot, transaction.states, stage, (accepted, next) => {
782
+ publication = transaction.publish(next, accepted, stage.provenanceUpdates);
783
+ }, transaction.causalBasis, { finalizeRun: false });
784
+ snapshot = nextSnapshot;
552
785
  installScopeStates();
553
- branchHasSnapshot = true;
554
- }
555
- installScopeStates();
556
- for (const acquired of artifactReads.successful.values()) {
557
- const observation = inspectRegisteredArtifactPaths([acquired.path])[0];
558
- if (acquired.sourceFingerprint === undefined || observation?.kind !== "present"
559
- || !sameArtifactSourceFingerprint(acquired.sourceFingerprint, observation.fingerprint)) {
560
- throw new Error(`Artifact source changed after acquisition: ${acquired.path}`);
786
+ if (publication?.changed) {
787
+ recordPublication(publication, ctx);
788
+ appendCheckpoint();
561
789
  }
562
- }
563
- const stage = stageAtomicScopePatches(scopeStates, patches, skillReads.successful.values(), runtime.causalBasis(), artifactReads.successful.values());
564
- const semanticChange = ["global", "cwd", "session"].some((scope) => !sameJson(scopeStates[scope], stage.nextStates[scope]));
565
- const provenanceChange = Object.values(stage.provenanceUpdates).some((updates) => Object.keys(updates).length > 0);
566
- if (!semanticChange && !provenanceChange)
567
- throw new Error("patch_state scope patches must materially update state or required provenance");
568
- commitStage(stage, ctx, false);
569
- updateUi(ctx);
570
- return { content: [{ type: "text", text: `\nState materialized atomically at ${scopes.join("+")} scope${scopes.length === 1 ? "" : "s"}.` }], details: { scopes, step: snapshot.meta.step } };
790
+ clearAcceptedAcquisitions(new Set(acquiredArtifacts.map(({ path }) => path)));
791
+ updateUi(ctx);
792
+ return { content: [{ type: "text", text: changed
793
+ ? `\nState materialized atomically at ${scopes.join("+")} scope${scopes.length === 1 ? "" : "s"}.`
794
+ : "\nState already current." }], details: { scopes, step: snapshot.meta.step, changed } };
795
+ }, signal);
571
796
  }
572
797
  catch (error) {
573
798
  let attempted;
@@ -577,7 +802,8 @@ export default function stateFlowExtension(pi, options = {}) {
577
802
  catch {
578
803
  attempted = undefined;
579
804
  }
580
- recordDiagnostic(error instanceof Error ? error.message : String(error), /concurrently|advanced/.test(String(error)) ? "publication-conflict" : "invalid-patch", ctx, {
805
+ const cause = diagnosticText(error);
806
+ recordDiagnostic(cause, /concurrently|advanced/.test(cause) ? "publication-conflict" : "invalid-patch", ctx, {
581
807
  input: attempted,
582
808
  tool: PATCH_STATE_TOOL_NAME,
583
809
  toolCallId,
@@ -587,73 +813,136 @@ export default function stateFlowExtension(pi, options = {}) {
587
813
  },
588
814
  });
589
815
  function startStateFlow(ctx) {
590
- if (!activeContext)
591
- restoreActiveBranch(ctx);
816
+ if (shuttingDown)
817
+ return Promise.resolve({ ok: false, message: "State Flow is shutting down" });
818
+ if (startActivation?.operation)
819
+ return startActivation.operation;
592
820
  telegramStartPending = false;
593
- const previousSnapshot = structuredClone(snapshot);
594
- const previousPassiveContinuation = passiveContinuation;
595
- const previousBootstrapContinuation = bootstrapContinuation;
596
- const previousArtifactRefreshPending = artifactRefreshPending;
597
- const previousArtifactInvalidations = structuredClone(artifactInvalidations);
821
+ if (activeContext && !branchRestoration && snapshot.config.enabled) {
822
+ return Promise.resolve({ ok: true, message: "State Flow is already enabled", signal: sharedInspectionLifetime.signal });
823
+ }
824
+ const pending = { controller: new AbortController() };
825
+ startActivation = pending;
826
+ const operation = runStart(ctx, pending.controller);
827
+ pending.operation = operation;
828
+ const finished = () => { if (startActivation === pending)
829
+ startActivation = undefined; };
830
+ void operation.then(finished, finished);
831
+ return operation;
832
+ }
833
+ /** Await restoration-owned attachment and exact-source fork recovery before current-head activation. */
834
+ async function runStart(ctx, pending) {
835
+ const owner = ctx.sessionManager.getSessionId();
836
+ const cwd = ctx.cwd;
837
+ const file = ctx.sessionManager.getSessionFile();
838
+ const timestamp = ctx.sessionManager.getHeader()?.timestamp;
839
+ const signal = ctx.signal ? AbortSignal.any([pending.signal, ctx.signal]) : pending.signal;
840
+ const isOwner = () => startActivation?.controller === pending && !signal.aborted && !shuttingDown
841
+ && ctx.cwd === cwd && ctx.sessionManager.getSessionId() === owner && ctx.sessionManager.getSessionFile() === file
842
+ && ctx.sessionManager.getHeader()?.timestamp === timestamp;
843
+ const superseded = () => {
844
+ pending.abort();
845
+ return { ok: false, message: "State Flow Start was superseded", signal: pending.signal };
846
+ };
598
847
  try {
599
- if (!branchStartsWithoutRuntime && (!runtime?.view || snapshot.meta.validation?.attempt === 0)) {
600
- const retryFork = forkInitialization;
601
- restoreActiveBranch(ctx, retryFork ? "fork" : undefined);
848
+ if (!activeContext)
849
+ await waitForRecovery(restoreActiveBranch(ctx, undefined, false, pending), signal);
850
+ else if (branchRestoration?.operation)
851
+ await waitForRecovery(branchRestoration.operation, signal);
852
+ if (!isOwner())
853
+ return superseded();
854
+ if (snapshot.config.enabled)
855
+ return { ok: true, message: "State Flow is already enabled", signal: sharedInspectionLifetime.signal };
856
+ if (forkInitialization) {
857
+ // Withdraw this join on cancellation without revoking the independently owned Stop.
858
+ const stopping = stopPersistence?.operation;
859
+ if (stopping)
860
+ await waitForRecovery(stopping, signal);
861
+ if (!isOwner())
862
+ return superseded();
863
+ await waitForRecovery(restoreActiveBranch(ctx, "fork", false, pending), signal);
864
+ if (!isOwner())
865
+ return superseded();
866
+ assertSelectedBranchAvailable();
602
867
  }
603
- assertSelectedBranchAvailable();
604
- if (!runtime?.view && !branchStartsWithoutRuntime)
605
- throw new Error("Selected State Flow boundary is unavailable; restore its canonical files before starting State Flow");
606
- const branch = ctx.sessionManager.getBranch();
607
- activeContext = ctx;
608
- runtime ??= createRuntime(ctx);
609
- if (branchStartsWithoutRuntime)
610
- runtime.prepare();
611
- const bootstrap = (!branchHasSnapshot || !snapshot.config.enabled)
612
- && (hasPriorConversation(branch) || previousPassiveContinuation !== undefined);
613
- const existingBranch = branchHasSnapshot;
614
- snapshot = existingBranch
615
- ? resumeEpisode(snapshot, bootstrap)
616
- : startEpisode(bootstrap);
617
- branchHasSnapshot = true;
618
- // Activation reasserts the selected session stream as a complete cohort. A resumed
619
- // branch may have no reusable temporal revision after an extension upgrade; a
620
- // runtime-only write would then reject its selected session as an omitted change.
621
- const publication = runtime.view
622
- ? runtime.publish(snapshot, true)
623
- : runtime.initialize(snapshot, true, undefined, branchStartsWithoutRuntime);
624
- recordPolicyPublication(publication, ctx);
625
- installScopeStates();
626
- clearRunTransient();
627
- passiveContinuation = undefined;
628
- bootstrapContinuation = snapshot.meta.bootstrap
629
- ? previousPassiveContinuation ?? previousBootstrapContinuation
630
- : undefined;
631
- deferArtifactRefresh();
632
- syncStateFlowTools();
633
- persist();
634
- updateUi(ctx);
635
- ctx.ui.notify(snapshot.meta.bootstrap
636
- ? "State Flow enabled. The next complete agent run will migrate active context into state."
637
- : "State Flow enabled. The next prompt starts a stateful agent run.", "info");
638
- return { ok: true, message: "State Flow enabled" };
868
+ return activateCurrentState(ctx, pending);
639
869
  }
640
870
  catch (error) {
641
- snapshot = previousSnapshot;
642
- passiveContinuation = previousPassiveContinuation;
643
- bootstrapContinuation = previousBootstrapContinuation;
644
- artifactRefreshPending = previousArtifactRefreshPending;
645
- artifactInvalidations = previousArtifactInvalidations;
646
- artifactReads.setCandidates(artifactInvalidations);
647
- syncStateFlowTools();
648
- const message = `State Flow could not initialize CWD state: ${error instanceof Error ? error.message : String(error)}`;
649
- ctx.ui.notify(message, "error");
650
- return { ok: false, message };
871
+ if (!isOwner())
872
+ return superseded();
873
+ const message = conciseDiagnostic(`State Flow Start failed: ${diagnosticText(error)}`);
874
+ notifyProblem(ctx, message, "error");
875
+ return { ok: false, message, signal: AbortSignal.any([pending.signal, sharedInspectionLifetime.signal]) };
876
+ }
877
+ }
878
+ async function activateCurrentState(ctx, pending) {
879
+ let selected = runtime;
880
+ const owner = ctx.sessionManager.getSessionId();
881
+ const cwd = ctx.cwd;
882
+ const file = ctx.sessionManager.getSessionFile();
883
+ const timestamp = ctx.sessionManager.getHeader()?.timestamp;
884
+ const initiallyEnabled = snapshot.config.enabled;
885
+ let accepted = false;
886
+ let receipt = AbortSignal.any([pending.signal, sharedInspectionLifetime.signal]);
887
+ const isCurrent = () => startActivation?.controller === pending && runtime === selected && !shuttingDown
888
+ && ctx.cwd === cwd && ctx.sessionManager.getSessionId() === owner && ctx.sessionManager.getSessionFile() === file
889
+ && ctx.sessionManager.getHeader()?.timestamp === timestamp && snapshot.config.enabled === (accepted || initiallyEnabled);
890
+ const superseded = () => {
891
+ pending.abort();
892
+ return { ok: false, message: "State Flow Start was superseded", signal: pending.signal };
893
+ };
894
+ try {
895
+ const activation = createRuntime(ctx);
896
+ const signal = ctx.signal ? AbortSignal.any([pending.signal, ctx.signal]) : pending.signal;
897
+ const result = await activation.withStartTransaction((current, publish) => {
898
+ signal.throwIfAborted();
899
+ if (!isCurrent())
900
+ throw new Error("State Flow Start selection changed while awaiting publication");
901
+ if (!current && !branchStartsWithoutRuntime)
902
+ throw new Error(snapshot.meta.validation?.error ?? "Current State Flow session memory is unavailable");
903
+ const continuation = passiveContinuation ?? bootstrapContinuation;
904
+ const bootstrap = hasPriorConversation(ctx.sessionManager.getBranch()) || passiveContinuation !== undefined;
905
+ const activated = current ? resumeEpisode(current, bootstrap) : startEpisode(bootstrap);
906
+ const recoveredCurrent = selectedHistoryExpired;
907
+ const publication = publish(activated);
908
+ accepted = true;
909
+ cancelStopPersistence();
910
+ runtime = selected = activation;
911
+ snapshot = activated;
912
+ activeContext = ctx;
913
+ selectedHistoryExpired = false;
914
+ stopPersistenceError = undefined;
915
+ installScopeStates();
916
+ clearRunTransient();
917
+ passiveContinuation = undefined;
918
+ bootstrapContinuation = snapshot.meta.bootstrap ? continuation : undefined;
919
+ deferInferencePreparation();
920
+ receipt = AbortSignal.any([pending.signal, sharedInspectionLifetime.signal]);
921
+ recordPolicyPublication(publication, ctx);
922
+ syncStateFlowTools();
923
+ updateUi(ctx);
924
+ appendCheckpoint();
925
+ ctx.ui.notify(recoveredCurrent
926
+ ? "State Flow enabled from current session memory; unavailable historical state was not restored."
927
+ : snapshot.meta.bootstrap
928
+ ? "State Flow enabled. The next complete agent run will migrate active context into state."
929
+ : "State Flow enabled. The next prompt starts a stateful agent run.", "info");
930
+ return { ok: true, message: "State Flow enabled", signal: receipt };
931
+ }, signal, branchStartsWithoutRuntime);
932
+ return isCurrent() ? result : superseded();
933
+ }
934
+ catch (error) {
935
+ if (!isCurrent())
936
+ return superseded();
937
+ const message = conciseDiagnostic(`${accepted ? "State Flow enabled; lifecycle update failed" : "State Flow Start failed"}: ${diagnosticText(error)}`);
938
+ notifyProblem(ctx, message, accepted ? "warning" : "error");
939
+ return { ok: accepted, message, signal: receipt };
651
940
  }
652
941
  }
653
942
  pi.registerCommand("state-flow-start", {
654
943
  description: "Start State Flow mode",
655
944
  handler: async (_args, ctx) => {
656
- startStateFlow(ctx);
945
+ await startStateFlow(ctx);
657
946
  },
658
947
  });
659
948
  pi.registerCommand("state-flow-status", {
@@ -663,43 +952,123 @@ export default function stateFlowExtension(pi, options = {}) {
663
952
  },
664
953
  });
665
954
  function stopStateFlow(ctx) {
955
+ cancelStartActivation();
956
+ if (shuttingDown)
957
+ return Promise.resolve({ ok: false, message: "State Flow is shutting down" });
958
+ if (stopPersistence?.operation)
959
+ return stopPersistence.operation;
666
960
  if (!activeContext)
667
- restoreActiveBranch(ctx);
668
- assertSelectedBranchAvailable();
961
+ void restoreActiveBranch(ctx, undefined, false);
962
+ const restoring = branchRestoration;
963
+ if (restoring?.awaitingAcceptance) {
964
+ // Stop changes policy without cancelling memory restoration or initialization.
965
+ restoring.passiveRequested = true;
966
+ snapshot = stopEpisode(snapshot);
967
+ clearRunTransient();
968
+ syncStateFlowTools();
969
+ updateUi(ctx);
970
+ return Promise.resolve({ ok: true, message: "State Flow disabled; memory restoration continues" });
971
+ }
972
+ const pending = { controller: new AbortController() };
973
+ stopPersistence = pending;
974
+ const operation = persistStoppedState(ctx, pending.controller);
975
+ pending.operation = operation;
976
+ const finished = () => { if (stopPersistence === pending)
977
+ stopPersistence = undefined; };
978
+ void operation.then(finished, finished);
979
+ return operation;
980
+ }
981
+ async function persistStoppedState(ctx, pending) {
669
982
  telegramStartPending = false;
983
+ const selected = runtime;
984
+ const owner = ctx.sessionManager.getSessionId();
670
985
  const current = snapshot;
671
- const stoppedAt = Date.now();
672
- const stopped = stopEpisode(current);
673
- const publication = !branchStartsWithoutRuntime && runtime?.view ? runtime.publish(stopped) : undefined;
674
- installScopeStates();
675
- // Freeze the accepted shared adoption, not the pre-publication cache.
676
- const exitHandoff = current.config.enabled && runtime?.view
677
- ? createPassiveContinuation(projectModelState(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)), stoppedAt, ctx.isIdle() ? undefined : runAnchorTimestamp)
678
- : undefined;
679
- const retainedHandoff = exitHandoff ?? (!current.config.enabled ? passiveContinuation : undefined);
680
- snapshot = stopped;
681
- recordPolicyPublication(publication, ctx);
682
- branchHasSnapshot = true;
986
+ let unfinished = current.meta.specification !== undefined
987
+ || (inferencePreparation?.prompt !== undefined && !inferencePreparation.accepted);
988
+ snapshot = stopEpisode(current);
683
989
  clearRunTransient();
684
- passiveContinuation = retainedHandoff;
685
- bootstrapContinuation = undefined;
686
- artifactInvalidations = [];
687
- artifactReads.setCandidates([]);
688
- artifactRefreshPending = false;
689
- if (exitHandoff)
690
- pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, {
691
- at: stoppedAt,
692
- ...(exitHandoff.activeRunStartedAt === undefined ? {} : { from: exitHandoff.activeRunStartedAt }),
693
- });
694
990
  syncStateFlowTools();
695
- persist();
696
991
  updateUi(ctx);
697
- return { ok: true, message: "State Flow disabled" };
992
+ if (stopPersistenceError)
993
+ return { ok: true, message: "State Flow disabled; memory writes remain paused" };
994
+ const stoppedAt = Date.now();
995
+ const incomingBoundary = current.meta.bootstrap ? bootstrapContinuation : undefined;
996
+ const anchor = runAnchorTimestamp;
997
+ const idle = ctx.isIdle();
998
+ const isCurrent = () => stopPersistence?.controller === pending && runtime === selected
999
+ && !shuttingDown && ctx.sessionManager.getSessionId() === owner && !snapshot.config.enabled;
1000
+ const superseded = () => ({ ok: false, message: "State Flow Stop was superseded" });
1001
+ const freezeHandoff = () => {
1002
+ const handoff = (current.config.enabled || stopPersistenceError) && selected?.view && current.meta.validation?.attempt !== 0
1003
+ ? createPassiveContinuation(projectModelState(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)), incomingBoundary?.startedAt ?? stoppedAt, incomingBoundary ? incomingBoundary.activeRunStartedAt : !idle || unfinished ? anchor : undefined, stopPersistenceError !== undefined || (incomingBoundary ? incomingBoundary.preserveContext : current.meta.bootstrap === true || (unfinished && anchor === undefined)))
1004
+ : undefined;
1005
+ passiveContinuation = handoff ?? (!current.config.enabled ? passiveContinuation : undefined);
1006
+ return handoff;
1007
+ };
1008
+ const complete = () => {
1009
+ const exitHandoff = freezeHandoff();
1010
+ if (exitHandoff || stopPersistenceError)
1011
+ pi.appendEntry(PASSIVE_STOP_ENTRY_TYPE, {
1012
+ at: exitHandoff?.startedAt ?? stoppedAt,
1013
+ ...(exitHandoff?.activeRunStartedAt === undefined ? {} : { from: exitHandoff.activeRunStartedAt }),
1014
+ ...(exitHandoff?.preserveContext || stopPersistenceError ? { preserveContext: true } : {}),
1015
+ ...(stopPersistenceError === undefined ? {} : { owner, persistenceError: stopPersistenceError }),
1016
+ });
1017
+ if (!stopPersistenceError) {
1018
+ appendCheckpoint();
1019
+ return { ok: true, message: "State Flow disabled" };
1020
+ }
1021
+ const message = conciseDiagnostic(`State Flow disabled; memory writes paused: ${stopPersistenceError}`);
1022
+ notifyProblem(ctx, message, "warning");
1023
+ return { ok: true, message };
1024
+ };
1025
+ let accepted = false;
1026
+ try {
1027
+ unfinished ||= current.config.enabled && hasUncheckpointedConversation(ctx.sessionManager.getBranch());
1028
+ // Projection changes before any wait; capture the old run's boundary before later native input can replace it.
1029
+ freezeHandoff();
1030
+ bootstrapContinuation = undefined;
1031
+ artifactInvalidations = [];
1032
+ artifactReads.setCandidates([]);
1033
+ assertPublicationAvailable();
1034
+ if (branchStartsWithoutRuntime || !selected?.view)
1035
+ return complete();
1036
+ const signal = ctx.signal ? AbortSignal.any([pending.signal, ctx.signal]) : pending.signal;
1037
+ const result = await selected.withLifecycleTransaction((publish) => {
1038
+ signal.throwIfAborted();
1039
+ if (!isCurrent())
1040
+ throw new Error("State Flow Stop selection changed while awaiting publication");
1041
+ assertPublicationAvailable();
1042
+ const stopped = stopEpisode(snapshot);
1043
+ const publication = publish(stopped);
1044
+ accepted = true;
1045
+ snapshot = stopped;
1046
+ installScopeStates();
1047
+ recordPolicyPublication(publication, ctx);
1048
+ return complete();
1049
+ }, signal);
1050
+ return isCurrent() ? result : superseded();
1051
+ }
1052
+ catch (error) {
1053
+ if (!isCurrent())
1054
+ return superseded();
1055
+ const cause = diagnosticText(error);
1056
+ if (accepted) {
1057
+ const message = conciseDiagnostic(`State Flow disabled; lifecycle update failed: ${cause}`);
1058
+ notifyProblem(ctx, message, "warning");
1059
+ return { ok: true, message };
1060
+ }
1061
+ stopPersistenceError = cause.trim() ? cause : "Canonical State Flow persistence failed";
1062
+ bootstrapContinuation = undefined;
1063
+ artifactInvalidations = [];
1064
+ artifactReads.setCandidates([]);
1065
+ return complete();
1066
+ }
698
1067
  }
699
1068
  pi.registerCommand("state-flow-stop", {
700
1069
  description: "Stop State Flow on the current session branch",
701
1070
  handler: async (_args, ctx) => {
702
- stopStateFlow(ctx);
1071
+ await stopStateFlow(ctx);
703
1072
  },
704
1073
  });
705
1074
  const telegram = createStateFlowTelegramAdapter({
@@ -712,28 +1081,23 @@ export default function stateFlowExtension(pi, options = {}) {
712
1081
  bootstrap: snapshot.meta.bootstrap === true,
713
1082
  startPending: telegramStartPending,
714
1083
  }),
715
- state: (scope) => {
716
- refreshTelegramStateView(scope);
717
- const selected = scope === "effective"
718
- ? overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)
719
- : scopeStates[scope];
720
- return { ...projectModelState(selected), lazy: structuredClone(selected.lazy) };
721
- },
722
- revisions: () => scopeRevisions(),
1084
+ inspect: inspectTelegramState,
723
1085
  canStartNow: () => activeContext === undefined || activeContext.isIdle(),
724
1086
  start: () => {
725
1087
  if (!activeContext)
726
1088
  throw new Error("State Flow is not attached to an active session yet");
727
1089
  return startStateFlow(activeContext);
728
1090
  },
729
- stop: () => {
1091
+ stop: async () => {
730
1092
  if (!activeContext)
731
1093
  throw new Error("State Flow is not attached to an active session yet");
1094
+ const operation = stopStateFlow(activeContext);
1095
+ const signal = sharedInspectionLifetime.signal;
732
1096
  try {
733
- return stopStateFlow(activeContext);
1097
+ return { ...await operation, signal };
734
1098
  }
735
1099
  catch (error) {
736
- return { ok: false, message: error instanceof Error ? error.message : String(error) };
1100
+ return { ok: false, message: diagnosticText(error), signal };
737
1101
  }
738
1102
  },
739
1103
  deferStart: () => {
@@ -741,11 +1105,12 @@ export default function stateFlowExtension(pi, options = {}) {
741
1105
  },
742
1106
  cancelStart: () => {
743
1107
  telegramStartPending = false;
1108
+ cancelStartActivation();
744
1109
  },
745
1110
  },
746
1111
  });
747
1112
  void telegram.ensure();
748
- pi.on("before_agent_start", (event, ctx) => {
1113
+ pi.on("before_agent_start", (event) => {
749
1114
  // Native run identity is independent of semantic enablement and survives mode toggles.
750
1115
  runAnchorTimestamp = undefined;
751
1116
  if (!snapshot.config.enabled) {
@@ -756,20 +1121,10 @@ export default function stateFlowExtension(pi, options = {}) {
756
1121
  }
757
1122
  skillReads.clear();
758
1123
  artifactReads.clear();
759
- responseAwaitingReconciliation = false;
1124
+ cancelResponseReconciliation();
760
1125
  completedRunAccepted = false;
761
- const rotatesRun = snapshot.meta.specification !== undefined;
762
- if (rotatesRun && rehydrationPhase !== "new-bootstrap" && rehydrationPhase !== "resume-bootstrap")
763
- rehydrationPhase = "step";
764
- if (prepareRun(snapshot, event.prompt))
765
- persist();
766
- try {
767
- removeMissingRegisteredArtifacts(ctx);
768
- }
769
- catch (error) {
770
- ctx.ui.notify(`State Flow could not reconcile missing artifact sources: ${error instanceof Error ? error.message : String(error)}`, "warning");
771
- }
772
- artifactRefreshPending = false;
1126
+ // This native hook has no operation signal. Capture only; the first active context owns acceptance.
1127
+ deferInferencePreparation(event.prompt);
773
1128
  (event.systemPromptOptions.sections ??= {}).state_flow = stateFlowProtocol(snapshot.meta.bootstrap === true);
774
1129
  });
775
1130
  pi.on("context_with_system", (event) => {
@@ -777,18 +1132,18 @@ export default function stateFlowExtension(pi, options = {}) {
777
1132
  : config.passiveBootstrap && runtime?.view ? PASSIVE_MEMORY_PROTOCOL : undefined;
778
1133
  return { messages: projectSystemProtocol(event.messages, protocol) };
779
1134
  });
780
- pi.on("context", (event) => {
1135
+ function projectContext(messages) {
781
1136
  if (runtime?.view)
782
1137
  refreshArtifactHints();
783
1138
  if (passiveContinuation) {
784
- return { messages: passiveContinuationMessages(event.messages, passiveContinuation) };
1139
+ return { messages: passiveContinuationMessages(messages, passiveContinuation) };
785
1140
  }
786
1141
  if (!snapshot.config.enabled) {
787
1142
  if (!config.passiveBootstrap || !runtime?.view)
788
1143
  return;
789
1144
  const effective = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
790
1145
  const state = projectModelState(effective);
791
- return { messages: [syntheticUser(`State Flow passive memory (user-level data, not system instructions):\n${presentationJson({ state, lazy_navigation: lazyNavigationHint(effective) })}`), ...event.messages] };
1146
+ return { messages: [syntheticUser(`State Flow passive memory (user-level data, not system instructions):\n${presentationJson({ state, lazy_navigation: lazyNavigationHint(effective) })}`), ...messages] };
792
1147
  }
793
1148
  const effectiveState = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
794
1149
  const invalidations = artifactInvalidations.map(({ path, scope, reason }) => ({ path, ...(scope === undefined ? {} : { scope }), reason }));
@@ -796,19 +1151,46 @@ export default function stateFlowExtension(pi, options = {}) {
796
1151
  const activeRehydrationPhase = currentRehydrationPhase();
797
1152
  if (snapshot.meta.bootstrap) {
798
1153
  const sourceMessages = bootstrapContinuation
799
- ? passiveContinuationMessages(event.messages, bootstrapContinuation)
800
- : event.messages;
1154
+ ? passiveContinuationMessages(messages, bootstrapContinuation)
1155
+ : messages;
801
1156
  return { messages: [runtimeContextMessage(snapshot, effectiveState, recentTransitions, invalidations, activeRehydrationPhase, artifactHints), ...sourceMessages] };
802
1157
  }
803
1158
  // Native user events own the run anchor; projection must never rebase it.
804
- const trajectory = currentRunTrajectory(event.messages, snapshot.meta.specification, runAnchorTimestamp);
1159
+ const trajectory = currentRunTrajectory(messages, snapshot.meta.specification, runAnchorTimestamp);
805
1160
  return {
806
1161
  messages: [
807
1162
  runtimeContextMessage(snapshot, effectiveState, recentTransitions, invalidations, activeRehydrationPhase, artifactHints),
808
1163
  ...trajectory.messages,
809
1164
  ],
810
1165
  };
811
- });
1166
+ }
1167
+ function prepareContext(messages, ctx) {
1168
+ const pending = inferencePreparation;
1169
+ const selected = runtime;
1170
+ const operationSignal = ctx.signal;
1171
+ // Idle projections remain observational; only a live native operation may await preparation.
1172
+ if (!snapshot.config.enabled || !pending || !operationSignal || shuttingDown)
1173
+ return projectContext(messages);
1174
+ pending.operation ??= prepareInference(pending, selected, ctx, operationSignal).finally(() => {
1175
+ // A late withdrawal must not clear newer work; accepted lifecycle is never replayed after an error.
1176
+ if (!pending.accepted && inferencePreparation === pending)
1177
+ pending.operation = undefined;
1178
+ });
1179
+ return pending.operation.then(() => {
1180
+ if (shuttingDown || operationSignal.aborted || runtime !== selected || ctx.signal !== operationSignal)
1181
+ return;
1182
+ if (snapshot.config.enabled && inferencePreparation !== pending) {
1183
+ // Start may require same-run maintenance. A new captured user prompt instead owns a different context request.
1184
+ if (inferencePreparation?.prompt === undefined)
1185
+ return prepareContext(messages, ctx);
1186
+ return;
1187
+ }
1188
+ if (snapshot.config.enabled && !pending.accepted)
1189
+ return;
1190
+ return projectContext(messages);
1191
+ });
1192
+ }
1193
+ pi.on("context", (event, ctx) => prepareContext(event.messages, ctx));
812
1194
  pi.on("tool_execution_start", (event) => {
813
1195
  if (!snapshot.config.enabled)
814
1196
  return;
@@ -862,53 +1244,77 @@ export default function stateFlowExtension(pi, options = {}) {
862
1244
  // Observe actual user events even while disabled; Start/Stop cannot invent or erase them.
863
1245
  if (event.message.role === "user" && runAnchorTimestamp === undefined)
864
1246
  runAnchorTimestamp = event.message.timestamp;
865
- if (!snapshot.config.enabled)
1247
+ if (shuttingDown || !snapshot.config.enabled)
866
1248
  return;
867
1249
  if (event.message.role !== "assistant")
868
1250
  return;
1251
+ cancelResponseReconciliation();
869
1252
  const message = event.message;
870
- if (message.stopReason === "aborted" || assistantToolCallCount(message.content) > 0 || message.stopReason === "toolUse") {
871
- responseAwaitingReconciliation = false;
1253
+ if (message.stopReason === "aborted" || assistantToolCallCount(message.content) > 0 || message.stopReason === "toolUse")
872
1254
  return;
873
- }
874
1255
  if (message.stopReason === "length" || message.stopReason === "error") {
875
- responseAwaitingReconciliation = false;
876
1256
  recordDiagnostic(`Assistant response ended with ${message.stopReason}`, "finalization", ctx, { content: message.content });
877
1257
  return;
878
1258
  }
879
- responseAwaitingReconciliation = true;
1259
+ responseReconciliation = new AbortController();
880
1260
  });
881
- pi.on("turn_end", (event, ctx) => {
882
- const wasBootstrap = snapshot.meta.bootstrap === true;
883
- if (!snapshot.config.enabled || !responseAwaitingReconciliation) {
1261
+ pi.on("turn_end", async (event, ctx) => {
1262
+ if (shuttingDown)
1263
+ return;
1264
+ const pending = responseReconciliation;
1265
+ if (!snapshot.config.enabled || !pending) {
884
1266
  updateUi(ctx);
885
1267
  return;
886
1268
  }
1269
+ const selected = runtime;
1270
+ const signal = ctx.signal ? AbortSignal.any([pending.signal, ctx.signal]) : pending.signal;
887
1271
  let responseCommitted = false;
888
- const specification = snapshot.meta.specification;
889
1272
  try {
890
1273
  const response = finalizedAssistantResponse(event.message);
891
- const stage = stageScopedTransition(scopeStates, { transitions: [], response }, [], runtime.causalBasis());
892
- completeRun(snapshot);
893
- commitStage(stage, ctx, true);
894
- responseCommitted = true;
895
- bootstrapContinuation = undefined;
896
- rehydrationPhase = "step";
897
- completedRunAccepted = !wasBootstrap;
898
- turnAcceptedForBackup = true;
1274
+ if (!selected?.view)
1275
+ throw new Error("Temporal State Flow runtime is unavailable; reload before publishing");
1276
+ await selected.withPatchTransaction((transaction) => {
1277
+ signal.throwIfAborted();
1278
+ if (runtime !== selected || responseReconciliation !== pending || !snapshot.config.enabled) {
1279
+ throw new Error("State Flow response selection changed while awaiting publication");
1280
+ }
1281
+ assertPublicationAvailable();
1282
+ const wasBootstrap = snapshot.meta.bootstrap === true;
1283
+ const nextSnapshot = structuredClone(snapshot);
1284
+ const stage = stageScopedTransition(transaction.states, { transitions: [], response }, [], transaction.causalBasis);
1285
+ completeRun(nextSnapshot);
1286
+ let publication;
1287
+ commitScopedTransition(nextSnapshot, transaction.states, stage, (accepted, next) => {
1288
+ publication = transaction.publish(next, accepted);
1289
+ }, transaction.causalBasis, { finalizeRun: true });
1290
+ snapshot = nextSnapshot;
1291
+ installScopeStates();
1292
+ responseCommitted = true;
1293
+ if (publication?.changed)
1294
+ recordPublication(publication, ctx);
1295
+ appendCheckpoint();
1296
+ clearAcceptedAcquisitions();
1297
+ bootstrapContinuation = undefined;
1298
+ rehydrationPhase = "step";
1299
+ completedRunAccepted = !wasBootstrap;
1300
+ turnAcceptedForBackup = true;
1301
+ updateUi(ctx);
1302
+ }, signal);
899
1303
  }
900
1304
  catch (error) {
901
- if (!responseCommitted && specification !== undefined)
902
- snapshot.meta.specification = specification;
903
- recordDiagnostic(error instanceof Error ? error.message : String(error), "finalization", ctx);
904
- ctx.ui.notify(responseCommitted
905
- ? `State Flow accepted the final response; a post-acceptance lifecycle update failed: ${error instanceof Error ? error.message : String(error)}`
906
- : `State Flow could not reconcile the final response: ${error instanceof Error ? error.message : String(error)}`, "error");
1305
+ // Superseded completion owns neither the new lifecycle nor its diagnostics/UI.
1306
+ if (signal.aborted || runtime !== selected || responseReconciliation !== pending)
1307
+ return;
1308
+ const cause = diagnosticText(error);
1309
+ recordDiagnostic(cause, "finalization", ctx);
1310
+ notifyProblem(ctx, responseCommitted
1311
+ ? `State Flow response saved; lifecycle update failed: ${cause}`
1312
+ : `State Flow response reconciliation failed: ${cause}`, "error");
907
1313
  }
908
1314
  finally {
909
- responseAwaitingReconciliation = false;
1315
+ if (responseReconciliation === pending)
1316
+ responseReconciliation = undefined;
910
1317
  }
911
- updateUi(ctx);
912
1318
  });
913
1319
  pi.on("session_before_compact", (event) => {
914
1320
  if (!compactionPlan)
@@ -920,35 +1326,60 @@ export default function stateFlowExtension(pi, options = {}) {
920
1326
  return result;
921
1327
  return { compaction: result };
922
1328
  });
923
- pi.on("agent_before_settle", (_event, ctx) => {
924
- if (!turnAcceptedForBackup)
1329
+ pi.on("agent_before_settle", async (_event, ctx) => {
1330
+ if (shuttingDown || !turnAcceptedForBackup)
925
1331
  return;
926
1332
  turnAcceptedForBackup = false;
927
1333
  if (!backupPending)
928
1334
  return;
929
1335
  backupPending = false;
1336
+ const operationSignal = ctx.signal;
1337
+ const signal = operationSignal ? AbortSignal.any([backupLifetime.signal, operationSignal]) : backupLifetime.signal;
1338
+ const selected = runtime;
930
1339
  try {
931
1340
  if (existsSync(join(repositoryRoot, ".git"))) {
932
- backupCurrentStateFlowFiles(repositoryRoot);
933
1341
  const pushSessionId = sessionAddress(ctx).id;
934
1342
  const pushCwd = ctx.cwd;
935
- void pushCurrentStateFlowBackup(repositoryRoot).catch((error) => {
936
- const message = error instanceof Error ? error.message : String(error);
937
- diagnosticWriter.record(pushSessionId, pushCwd, message, "publication-conflict");
938
- notifyActiveContext(`State Flow accepted canonical state; Git backup push failed: ${message}`);
939
- });
1343
+ // Pi 0.87 settles after its agent signal ends; waiting there would strand native Abort.
1344
+ const operation = backupCurrentStateFlowFiles(repositoryRoot, signal, operationSignal !== undefined);
1345
+ backupOperations.add(operation);
1346
+ try {
1347
+ await operation;
1348
+ }
1349
+ finally {
1350
+ backupOperations.delete(operation);
1351
+ }
1352
+ if (signal.aborted)
1353
+ return;
1354
+ startStateFlowBackupPush(repositoryRoot, (error) => {
1355
+ if (shuttingDown)
1356
+ return;
1357
+ const message = diagnosticText(error);
1358
+ const recorded = diagnosticWriter.recordBackupPushFailure(pushSessionId, pushCwd, message);
1359
+ if (pushFailureNotified)
1360
+ return;
1361
+ pushFailureNotified = true;
1362
+ notifyActiveContext(recorded
1363
+ ? `State Flow Git backup push failed; state is saved locally. Details: ${stateFlowLogPath(agentDir)}. A later accepted turn retries.`
1364
+ : `State Flow Git backup push failed; local diagnostics unavailable: ${message}`);
1365
+ }, () => { pushFailureNotified = false; });
940
1366
  }
941
1367
  }
942
1368
  catch (error) {
943
- const message = error instanceof Error ? error.message : String(error);
1369
+ if (signal.aborted || runtime !== selected)
1370
+ return;
1371
+ const message = diagnosticText(error);
944
1372
  recordDiagnostic(message, "publication-conflict", ctx);
945
- ctx.ui.notify(`State Flow accepted canonical state; Git backup failed: ${message}`, "warning");
1373
+ notifyProblem(ctx, error instanceof PublicationBusyError
1374
+ ? "State Flow state saved; Git backup deferred: Pi supplied no cancellable settlement wait. A later accepted turn retries."
1375
+ : `State Flow state saved; Git backup failed: ${message}`, "warning");
946
1376
  }
947
1377
  });
948
1378
  pi.on("agent_settled", async (_event, ctx) => {
949
1379
  if (telegramStartPending && !snapshot.config.enabled) {
950
1380
  telegramStartPending = false;
951
- startStateFlow(ctx);
1381
+ await startStateFlow(ctx);
1382
+ return;
952
1383
  }
953
1384
  if (!completedRunAccepted || compactionStopped || !snapshot.config.enabled || snapshot.meta.bootstrap
954
1385
  || compactionInFlight || !ctx.isIdle() || ctx.hasPendingMessages() || !runtime?.view
@@ -969,22 +1400,32 @@ export default function stateFlowExtension(pi, options = {}) {
969
1400
  ctx.compact({ customInstructions: compactionMarker, onComplete: finished, onError: finished });
970
1401
  });
971
1402
  });
972
- pi.on("session_start", (event, ctx) => {
1403
+ pi.on("session_start", async (event, ctx) => {
973
1404
  runAnchorTimestamp = undefined;
974
1405
  rehydrationPhase = event.reason === "resume" ? "resume-bootstrap" : "new-bootstrap";
975
- restoreActiveBranch(ctx, event.reason);
976
- updateUi(ctx);
977
- void telegram.ensure();
1406
+ await restoreActiveBranch(ctx, event.reason);
1407
+ if (!shuttingDown)
1408
+ void telegram.ensure();
978
1409
  });
979
- pi.on("session_tree", (_event, ctx) => {
1410
+ pi.on("session_tree", async (_event, ctx) => {
980
1411
  runAnchorTimestamp = undefined;
981
- restoreActiveBranch(ctx);
1412
+ await restoreActiveBranch(ctx);
982
1413
  });
983
- pi.on("session_shutdown", (_event, _ctx) => {
1414
+ pi.on("session_shutdown", async (_event, _ctx) => {
1415
+ shuttingDown = true;
1416
+ const restoring = cancelBranchRestoration();
1417
+ const starting = cancelStartActivation();
1418
+ const stopping = cancelStopPersistence();
1419
+ backupLifetime.abort();
1420
+ cancelInferencePreparation();
1421
+ cancelResponseReconciliation();
1422
+ cancelSharedInspections();
984
1423
  telegramStartPending = false;
985
1424
  compactionStopped = true;
986
1425
  completedRunAccepted = false;
987
1426
  activeContext = undefined;
988
1427
  telegram.dispose();
1428
+ await Promise.allSettled([...backupOperations, ...restorationOperations, ...[restoring, stopping, starting].filter((operation) => operation !== undefined)]);
1429
+ await awaitInFlightBackupPushes(repositoryRoot);
989
1430
  });
990
1431
  }