mixdog 0.9.87 → 0.9.88

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 (160) hide show
  1. package/package.json +13 -7
  2. package/scripts/tool-failures.mjs +60 -24
  3. package/src/agents/heavy-worker/AGENT.md +3 -4
  4. package/src/agents/worker/AGENT.md +1 -2
  5. package/src/cli.mjs +8 -0
  6. package/src/defaults/cycle3-review-prompt.md +4 -4
  7. package/src/rules/agent/00-core.md +3 -0
  8. package/src/rules/agent/42-cycle3-agent.md +5 -6
  9. package/src/rules/lead/01-general.md +2 -0
  10. package/src/rules/shared/01-tool.md +5 -1
  11. package/src/runtime/agent/orchestrator/agent-runtime/agent-dispatch.mjs +3 -51
  12. package/src/runtime/agent/orchestrator/agent-runtime/maintenance-route.mjs +59 -0
  13. package/src/runtime/agent/orchestrator/agent-runtime/session-builder.mjs +2 -2
  14. package/src/runtime/agent/orchestrator/agent-runtime/title-completion.mjs +67 -0
  15. package/src/runtime/agent/orchestrator/agent-trace-format.mjs +57 -4
  16. package/src/runtime/agent/orchestrator/agent-trace-io.mjs +2 -3
  17. package/src/runtime/agent/orchestrator/config.mjs +29 -11
  18. package/src/runtime/agent/orchestrator/context/collect.mjs +1 -1
  19. package/src/runtime/agent/orchestrator/internal-agents.mjs +1 -1
  20. package/src/runtime/agent/orchestrator/mcp/client.mjs +0 -24
  21. package/src/runtime/agent/orchestrator/providers/admission-scheduler.mjs +3 -3
  22. package/src/runtime/agent/orchestrator/providers/anthropic-oauth.mjs +25 -17
  23. package/src/runtime/agent/orchestrator/providers/anthropic-sse.mjs +321 -22
  24. package/src/runtime/agent/orchestrator/providers/anthropic.mjs +35 -22
  25. package/src/runtime/agent/orchestrator/providers/gemini-stream.mjs +28 -23
  26. package/src/runtime/agent/orchestrator/providers/gemini.mjs +10 -2
  27. package/src/runtime/agent/orchestrator/providers/grok-oauth-login.mjs +0 -1
  28. package/src/runtime/agent/orchestrator/providers/grok-oauth-tokens.mjs +0 -1
  29. package/src/runtime/agent/orchestrator/providers/grok-oauth.mjs +2 -5
  30. package/src/runtime/agent/orchestrator/providers/lib/anthropic-native-blocks.mjs +27 -0
  31. package/src/runtime/agent/orchestrator/providers/lib/anthropic-request-utils.mjs +23 -0
  32. package/src/runtime/agent/orchestrator/providers/lib/stream-outcome.mjs +329 -0
  33. package/src/runtime/agent/orchestrator/providers/oauth-usage.mjs +23 -1
  34. package/src/runtime/agent/orchestrator/providers/openai-compat-stream.mjs +107 -20
  35. package/src/runtime/agent/orchestrator/providers/openai-compat.mjs +4 -3
  36. package/src/runtime/agent/orchestrator/providers/openai-oauth-http-sse.mjs +124 -12
  37. package/src/runtime/agent/orchestrator/providers/openai-oauth-ws.mjs +19 -2
  38. package/src/runtime/agent/orchestrator/providers/openai-oauth.mjs +1 -1
  39. package/src/runtime/agent/orchestrator/providers/openai-responses-payload.mjs +1 -1
  40. package/src/runtime/agent/orchestrator/providers/openai-ws-stream.mjs +110 -75
  41. package/src/runtime/agent/orchestrator/providers/retry-classifier.mjs +96 -113
  42. package/src/runtime/agent/orchestrator/session/agent-loop.mjs +144 -10
  43. package/src/runtime/agent/orchestrator/session/lifecycle-scan.mjs +147 -117
  44. package/src/runtime/agent/orchestrator/session/loop/stop-hooks.mjs +88 -0
  45. package/src/runtime/agent/orchestrator/session/loop/termination.mjs +25 -0
  46. package/src/runtime/agent/orchestrator/session/loop/tool-exec.mjs +1 -1
  47. package/src/runtime/agent/orchestrator/session/manager/ask-session.mjs +47 -6
  48. package/src/runtime/agent/orchestrator/session/manager/pending-messages.mjs +485 -24
  49. package/src/runtime/agent/orchestrator/session/manager/session-close.mjs +100 -2
  50. package/src/runtime/agent/orchestrator/session/manager/session-crud.mjs +28 -0
  51. package/src/runtime/agent/orchestrator/session/manager/session-lifecycle.mjs +80 -14
  52. package/src/runtime/agent/orchestrator/session/manager/turn-checkpoint.mjs +142 -2
  53. package/src/runtime/agent/orchestrator/session/manager/usage-metrics.mjs +128 -32
  54. package/src/runtime/agent/orchestrator/session/manager.mjs +5 -1
  55. package/src/runtime/agent/orchestrator/session/save-session-worker.mjs +77 -4
  56. package/src/runtime/agent/orchestrator/session/send-with-recovery.mjs +70 -39
  57. package/src/runtime/agent/orchestrator/session/store/fs-probe.mjs +91 -0
  58. package/src/runtime/agent/orchestrator/session/store/listing.mjs +141 -64
  59. package/src/runtime/agent/orchestrator/session/store/live-state.mjs +253 -0
  60. package/src/runtime/agent/orchestrator/session/store/load-cache.mjs +211 -28
  61. package/src/runtime/agent/orchestrator/session/store/save-fault.mjs +313 -0
  62. package/src/runtime/agent/orchestrator/session/store/save-worker.mjs +622 -53
  63. package/src/runtime/agent/orchestrator/session/store/serialize.mjs +43 -10
  64. package/src/runtime/agent/orchestrator/session/store/summary-cache.mjs +53 -8
  65. package/src/runtime/agent/orchestrator/session/store/summary-rebuild-worker.mjs +20 -0
  66. package/src/runtime/agent/orchestrator/session/store/write-guards.mjs +113 -9
  67. package/src/runtime/agent/orchestrator/session/store-summary-index.mjs +2 -0
  68. package/src/runtime/agent/orchestrator/session/store-summary-reader.mjs +476 -52
  69. package/src/runtime/agent/orchestrator/session/store.mjs +721 -196
  70. package/src/runtime/agent/orchestrator/session/token-native.mjs +2 -4
  71. package/src/runtime/agent/orchestrator/session/tool-batch.mjs +19 -0
  72. package/src/runtime/agent/orchestrator/tools/bash-session.mjs +4 -6
  73. package/src/runtime/agent/orchestrator/tools/builtin/list-tool.mjs +146 -90
  74. package/src/runtime/agent/orchestrator/tools/builtin/read-single-tool.mjs +6 -0
  75. package/src/runtime/agent/orchestrator/tools/builtin/rg-runner.mjs +93 -17
  76. package/src/runtime/agent/orchestrator/tools/builtin/search-path-diagnostics.mjs +5 -0
  77. package/src/runtime/agent/orchestrator/tools/builtin/search-tool.mjs +7 -7
  78. package/src/runtime/agent/orchestrator/tools/builtin/shell-job-spawn.mjs +2 -0
  79. package/src/runtime/agent/orchestrator/tools/builtin/snapshot-store.mjs +52 -0
  80. package/src/runtime/agent/orchestrator/tools/code-graph/disk-cache.mjs +54 -51
  81. package/src/runtime/agent/orchestrator/tools/code-graph/dispatch.mjs +14 -15
  82. package/src/runtime/agent/orchestrator/tools/patch/dispatch.mjs +132 -8
  83. package/src/runtime/agent/orchestrator/tools/patch/matcher.mjs +67 -3
  84. package/src/runtime/agent/orchestrator/tools/patch/native-server.mjs +6 -1
  85. package/src/runtime/agent/orchestrator/tools/patch/orchestrator.mjs +203 -38
  86. package/src/runtime/agent/orchestrator/tools/patch/paths.mjs +13 -1
  87. package/src/runtime/agent/orchestrator/tools/patch/v4a-convert.mjs +73 -19
  88. package/src/runtime/agent/orchestrator/tools/patch-manifest.json +11 -11
  89. package/src/runtime/agent/orchestrator/tools/patch-tool-defs.mjs +11 -8
  90. package/src/runtime/agent/orchestrator/tools/shell-command.mjs +12 -2
  91. package/src/runtime/media/lanes.mjs +2 -2
  92. package/src/runtime/media/renditions.mjs +101 -17
  93. package/src/runtime/media/renditions.test.mjs +54 -0
  94. package/src/runtime/media/store.mjs +111 -43
  95. package/src/runtime/media/store.test.mjs +53 -11
  96. package/src/runtime/memory/index.mjs +26 -50
  97. package/src/runtime/memory/lib/core-memory-candidates.mjs +2 -7
  98. package/src/runtime/memory/lib/core-memory-store.mjs +2 -9
  99. package/src/runtime/memory/lib/cycle-scheduler.mjs +10 -0
  100. package/src/runtime/memory/lib/embedding-provider.mjs +3 -3
  101. package/src/runtime/memory/lib/embedding-worker.mjs +60 -15
  102. package/src/runtime/memory/lib/http-router.mjs +4 -0
  103. package/src/runtime/memory/lib/ko-morph.mjs +49 -6
  104. package/src/runtime/memory/lib/memory-action-handlers.mjs +21 -18
  105. package/src/runtime/memory/lib/memory-cycle2.mjs +3 -3
  106. package/src/runtime/memory/lib/memory-cycle3.mjs +1 -3
  107. package/src/runtime/memory/lib/memory-recall-store.mjs +24 -0
  108. package/src/runtime/memory/lib/query-handlers.mjs +26 -28
  109. package/src/runtime/memory/tool-defs.mjs +3 -3
  110. package/src/runtime/shared/atomic-file.mjs +5 -1
  111. package/src/runtime/shared/child-guardian.mjs +52 -2
  112. package/src/runtime/shared/provider-api-key.mjs +22 -5
  113. package/src/runtime/shared/tool-execution-contract.mjs +53 -0
  114. package/src/session-runtime/config-helpers.mjs +6 -5
  115. package/src/session-runtime/lifecycle-api.mjs +16 -4
  116. package/src/session-runtime/media-api.mjs +31 -16
  117. package/src/session-runtime/prewarm.mjs +2 -24
  118. package/src/session-runtime/runtime-core.mjs +33 -15
  119. package/src/session-runtime/runtime-tunables.mjs +0 -3
  120. package/src/session-runtime/session-lifecycle.mjs +0 -6
  121. package/src/session-runtime/session-title.mjs +228 -0
  122. package/src/session-runtime/session-turn-api.mjs +11 -7
  123. package/src/session-runtime/workflow-agents-api.mjs +16 -0
  124. package/src/session-runtime/workflow.mjs +7 -5
  125. package/src/standalone/agent-tool/job-views.mjs +90 -36
  126. package/src/standalone/agent-tool/spawn-flow.mjs +25 -216
  127. package/src/standalone/agent-tool/worker-index.mjs +8 -0
  128. package/src/standalone/agent-tool/worker-rows.mjs +2 -1
  129. package/src/standalone/agent-tool.mjs +17 -17
  130. package/src/standalone/agent-watchdog-registry.mjs +19 -2
  131. package/src/standalone/channel-daemon.mjs +8 -0
  132. package/src/standalone/memory-runtime-proxy.mjs +4 -7
  133. package/src/standalone/projects.mjs +4 -1
  134. package/src/standalone/usage-dashboard.mjs +25 -3
  135. package/src/tui/App.jsx +5 -3
  136. package/src/tui/app/resume-picker.mjs +7 -2
  137. package/src/tui/app/slash-dispatch.mjs +13 -3
  138. package/src/tui/app/transcript-row-estimate.mjs +1 -1
  139. package/src/tui/app/transcript-window.mjs +17 -93
  140. package/src/tui/app/use-transcript-scroll.mjs +32 -2
  141. package/src/tui/app/use-transcript-window.mjs +64 -114
  142. package/src/tui/components/Markdown.jsx +19 -2
  143. package/src/tui/components/Message.jsx +8 -3
  144. package/src/tui/components/ToolExecution.jsx +7 -3
  145. package/src/tui/dist/index.mjs +233 -121
  146. package/src/tui/engine/live-share.mjs +15 -5
  147. package/src/tui/engine/render-timing.mjs +2 -2
  148. package/src/tui/engine/session-api-ext.mjs +74 -4
  149. package/src/tui/engine/session-flow.mjs +3 -1
  150. package/src/tui/engine.mjs +2 -2
  151. package/src/tui/hooks/useSharedTick.mjs +0 -2
  152. package/src/tui/index.jsx +5 -5
  153. package/src/ui/statusline-agents.mjs +44 -11
  154. package/src/vendor/statusline/bin/statusline-route.mjs +26 -3
  155. package/src/workflows/default/WORKFLOW.md +3 -3
  156. package/src/workflows/solo/WORKFLOW.md +1 -1
  157. package/src/runtime/media/index.mjs +0 -18
  158. package/src/runtime/memory/lib/embedding-warmup.mjs +0 -68
  159. package/src/standalone/agent-shard/shard-child.mjs +0 -300
  160. package/src/standalone/agent-shard/shard-pool.mjs +0 -443
@@ -1,8 +1,15 @@
1
1
  import { Worker } from 'worker_threads';
2
2
  import { guardedSaveOptions as _guardedSaveOptions } from './write-guards.mjs';
3
- import { _ensureLifecycleFields, _sessionForDisk } from './serialize.mjs';
4
- import { setLiveSession, _droppedSaveIds, clearSessionSaveError } from './live-state.mjs';
5
- import { _cacheSessionSummary, _rollbackCachedSessionSummary, _queueSessionSummaryUpsert } from './summary-cache.mjs';
3
+ import { _ensureLifecycleFields, _messagesForDisk, _sessionForDisk } from './serialize.mjs';
4
+ import { setLiveSession, _recordSaveFailure, _recordSaveDrop, _clearSaveStateIfCurrent, _nextSaveEpoch, _acquireSessionIncarnation, _releaseSessionIncarnation, _isCurrentSessionIncarnation, SAVE_OUTCOME_STALE } from './live-state.mjs';
5
+ import { _cacheSessionSummary, _rollbackCachedSessionSummary, _queueSessionSummaryUpsertRow } from './summary-cache.mjs';
6
+ import { _sessionSummary } from '../store-summary-index.mjs';
7
+ import {
8
+ serializeSessionSaveFault,
9
+ sessionSaveFaultSyncKey,
10
+ _onSessionSaveFaultChange,
11
+ _sessionStoreTestMode,
12
+ } from './save-fault.mjs';
6
13
 
7
14
  // ── Worker-thread async save ──────────────────────────────────────────────────
8
15
  // Single long-lived Worker serializes all saveSessionAsync calls.
@@ -23,6 +30,90 @@ let _saveWorkerRefCount = 0;
23
30
  let _deferredSaveReqId = 0;
24
31
  export const _deferredSessionSaves = new Map();
25
32
 
33
+ // ── Delta handoff to the save worker ─────────────────────────────────────────
34
+ // Worker.postMessage structured-clones on the CALLER's thread, so a full-
35
+ // transcript payload per turn cost O(whole conversation) on the engine thread.
36
+ // Turns normally APPEND to the message list (the array is replaced but the
37
+ // settled message objects are reused by reference), so the parent tracks the
38
+ // exact refs last handed to the worker and, on a pure append, ships only the
39
+ // header + projected tail — O(turn). Any prefix change (compaction, clear,
40
+ // repair), a broken chain (failure/restart), or the periodic full resync
41
+ // falls back to a full snapshot. Lock-free and per-id: sessions stay fully
42
+ // parallel and the single worker's per-id FIFO preserves chain order.
43
+ const _deltaBaseline = new Map(); // id → { refs: message[], deltasSinceFull }
44
+ const DELTA_BASELINE_MAX = 8;
45
+ const DELTA_FULL_RESYNC_EVERY = 25;
46
+
47
+ function _touchDeltaBaseline(id, entry) {
48
+ _deltaBaseline.delete(id);
49
+ _deltaBaseline.set(id, entry);
50
+ while (_deltaBaseline.size > DELTA_BASELINE_MAX) {
51
+ const oldest = _deltaBaseline.keys().next().value;
52
+ if (oldest === undefined) break;
53
+ _deltaBaseline.delete(oldest);
54
+ }
55
+ }
56
+
57
+ function _invalidateDeltaBaseline(id) {
58
+ _deltaBaseline.delete(id);
59
+ }
60
+
61
+ function _immutableProjection(messages) {
62
+ if (!Array.isArray(messages)) return null;
63
+ // DEEP copy: the projected baseline must survive in-place nested edits of
64
+ // messages that were already sent (a reference-identity delta never ships
65
+ // those, so they may not appear in failure evidence either).
66
+ try { return structuredClone(messages); } catch { return null; }
67
+ }
68
+
69
+ function _buildWirePayload(id, session, forceFull = false) {
70
+ const live = Array.isArray(session.messages) ? session.messages : [];
71
+ const base = forceFull ? null : _deltaBaseline.get(id);
72
+ if (base && base.deltasSinceFull < DELTA_FULL_RESYNC_EVERY && live.length >= base.refs.length) {
73
+ let pureAppend = true;
74
+ for (let index = 0; index < base.refs.length; index += 1) {
75
+ if (live[index] !== base.refs[index]) { pureAppend = false; break; }
76
+ }
77
+ if (pureAppend) {
78
+ // Header: full disk projection with an empty message list (strips
79
+ // transient aliases); tail: per-message projection of the appended
80
+ // suffix only. Both use the same idempotent per-message projection
81
+ // as a full send, so worker-side reconstruction is byte-identical.
82
+ const header = _sessionForDisk({ ...session, messages: [] });
83
+ const tailMessages = _messagesForDisk(live.slice(base.refs.length));
84
+ // The EXACT payload the worker will reconstruct and write:
85
+ // immutable projected baseline + this delta. Failure evidence must
86
+ // be this, never a fresh projection of the mutable live session
87
+ // (an in-place nested edit of an already-sent message is NOT part
88
+ // of a reference-identity delta and must be absent here too).
89
+ const projectedBase = Array.isArray(base.projected) && base.projected.length === base.refs.length
90
+ ? base.projected
91
+ : null;
92
+ const clonedTail = _immutableProjection(tailMessages);
93
+ const projected = projectedBase && clonedTail ? [...projectedBase, ...clonedTail] : null;
94
+ _touchDeltaBaseline(id, {
95
+ refs: live.slice(),
96
+ deltasSinceFull: base.deltasSinceFull + 1,
97
+ projected,
98
+ });
99
+ return {
100
+ delta: { baseCount: base.refs.length, header, tailMessages },
101
+ attempt: projected ? { ...header, messages: projected } : null,
102
+ };
103
+ }
104
+ }
105
+ const full = _sessionForDisk(session);
106
+ _touchDeltaBaseline(id, {
107
+ refs: live.slice(),
108
+ deltasSinceFull: 0,
109
+ // DEEP COPY: _sessionForDisk may return the live array (and the live
110
+ // message objects) itself; later appends or in-place nested edits must
111
+ // not reach this baseline.
112
+ projected: _immutableProjection(full.messages) ?? [],
113
+ });
114
+ return { session: full, attempt: full };
115
+ }
116
+
26
117
  /**
27
118
  * Build the exact payload the worker will persist BEFORE Worker.postMessage
28
119
  * structured-clones it on the caller's thread. Inline image/document bytes and
@@ -34,11 +125,105 @@ export function _sessionPayloadForSaveWorker(session) {
34
125
  return _sessionForDisk(session);
35
126
  }
36
127
 
128
+ // ── Fault-state mirroring (parent → worker) ─────────────────────────────────
129
+ // The worker thread is long-lived and owns its own module instance of
130
+ // save-fault.mjs, which setSessionSaveFault() never reaches, so the parent
131
+ // pushes the authoritative state: on spawn, on every config change, and (as a
132
+ // cheap key compare) before every posted write. Clearing propagates the same
133
+ // way, which is what makes `setSessionSaveFault(null)` stop worker faults.
134
+ let _faultSyncedKey = null;
135
+
136
+ // ── Pre-admission authority (parent-side) ───────────────────────────────────
137
+ // store.mjs registers its strict canonical-record check here (an import would
138
+ // be circular). An async/worker save must pass it BEFORE any live snapshot or
139
+ // optimistic summary row is published: foreign/ambiguous records must never be
140
+ // cached as owned, not even transiently.
141
+ let _writeAuthorityCheck = null;
142
+
143
+ export function _setSessionWriteAuthorityCheck(check) {
144
+ _writeAuthorityCheck = typeof check === 'function' ? check : null;
145
+ }
146
+
147
+ function _refuseUnownedWrite(id) {
148
+ if (!_writeAuthorityCheck || !id) return null;
149
+ let refusal = null;
150
+ // A THROWN check is a refusal, never acceptance.
151
+ try { refusal = _writeAuthorityCheck(id); } catch { refusal = 'unreadable'; }
152
+ if (!refusal) return null;
153
+ const err = new Error(`[session-store] ${id}: refusing async save — canonical record is ${refusal}`);
154
+ err.code = 'ESESSIONNOTOWNED';
155
+ err.sessionAuthorityRefusal = refusal;
156
+ return err;
157
+ }
158
+
159
+ function _syncFaultToWorker(worker, { force = false } = {}) {
160
+ if (!worker) return;
161
+ const key = sessionSaveFaultSyncKey();
162
+ if (!force && key === _faultSyncedKey) return;
163
+ try {
164
+ worker.postMessage({ __fault: serializeSessionSaveFault() });
165
+ _faultSyncedKey = key;
166
+ } catch { /* worker died; respawn re-syncs (force) */ }
167
+ }
168
+
169
+ // Config changes are pushed immediately so a fault set/cleared between saves
170
+ // is honoured by the worker's very next commit.
171
+ _onSessionSaveFaultChange(() => {
172
+ if (_saveWorker) _syncFaultToWorker(_saveWorker, { force: true });
173
+ });
174
+
175
+ /**
176
+ * Reject one settled worker write. The failure is RECORDED BEFORE the waiters
177
+ * are rejected, so a caller's rejection handler already observes
178
+ * getSessionSaveError(id) / the non-evictable live snapshot; and the
179
+ * optimistic summary row is rolled back so a failed write never publishes.
180
+ */
181
+ function _failWorkerWrite(id, summaryVersion, waiters, err, epoch = null, incarnation = null, session = null, known = null) {
182
+ // Currentness may be PRECOMPUTED by the caller: once the pending reference
183
+ // is released, cap eviction can drop the token, and re-deriving here would
184
+ // then misread a real failure as a stale post-delete outcome.
185
+ const isCurrent = typeof known === 'boolean'
186
+ ? known
187
+ : _isCurrentSessionIncarnation(id, incarnation);
188
+ if (!isCurrent) {
189
+ // The session was hard-deleted (and possibly re-created) after this
190
+ // write was posted: its failure is about a file that no longer exists.
191
+ // Settle the callers ONCE and touch nothing — no marker, no delta
192
+ // baseline: none of it belongs to this incarnation any more.
193
+ for (const w of waiters) w.reject(err);
194
+ return;
195
+ }
196
+ _invalidateDeltaBaseline(id);
197
+ _rollbackCachedSessionSummary(id, summaryVersion);
198
+ // The failed payload's own snapshot travels with the failure: it is the
199
+ // only in-memory copy allowed to stand in for an unreadable canonical file.
200
+ _recordSaveFailure(id, err, epoch, session);
201
+ for (const w of waiters) w.reject(err);
202
+ }
203
+
204
+ /** Rebuild the worker-side error locally WITHOUT losing its code/marker. */
205
+ function _workerSaveError(message, code, injected) {
206
+ const err = new Error(`[session-store] worker save failed: ${message}`);
207
+ if (code) err.code = code;
208
+ if (injected) err.injectedSaveFault = true;
209
+ err.workerMessage = message;
210
+ return err;
211
+ }
212
+
37
213
  function _getOrSpawnWorker() {
38
214
  if (_saveWorker) return _saveWorker;
39
- _saveWorker = new Worker(new URL('../save-session-worker.mjs', import.meta.url), {
215
+ // Every handler below is bound to THIS instance: a worker that already
216
+ // died (its error/exit events can arrive after a replacement is live, and
217
+ // 'exit' always follows 'error') must never settle, reject or ref-count
218
+ // the pending writes of the worker that replaced it.
219
+ const worker = new Worker(new URL('../save-session-worker.mjs', import.meta.url), {
40
220
  execArgv: [],
41
221
  });
222
+ _saveWorker = worker;
223
+ // Push current fault state before any write can be posted: the worker's
224
+ // own realm has no other source for it.
225
+ _faultSyncedKey = null;
226
+ _syncFaultToWorker(worker, { force: true });
42
227
  // Worker logs arrive as `{ __log }` messages, NOT via piped stdio
43
228
  // (stdout:true/stderr:true): once the parent starts reading a worker's
44
229
  // piped stdio, the underlying MessagePort stays ref'd for the worker's
@@ -48,44 +233,110 @@ function _getOrSpawnWorker() {
48
233
  // to forward through this channel, which keeps stray prints off the TUI
49
234
  // frame (routed through the parent's guardable stderr) without holding
50
235
  // the event loop.
51
- _saveWorker.on('message', ({ __log, ok, saved, error, reqId }) => {
236
+ worker.on('message', ({ __log, ok, saved, outcome, deltaMiss, error, errorCode, injectedSaveFault, reqId }) => {
52
237
  if (__log !== undefined) {
53
238
  try { process.stderr.write(String(__log)); } catch { /* best-effort */ }
54
239
  return;
55
240
  }
241
+ if (worker !== _saveWorker) return; // stale instance: not our bookkeeping
56
242
  const p = _saveWorkerPending.get(reqId);
57
243
  if (!p) return;
58
244
  _saveWorkerPending.delete(reqId);
59
245
  // Drop the ref AFTER pending was registered ref-up'd so the worker
60
- // becomes unref'd again once all in-flight writes settle. _saveWorker
61
- // null-check covers the error/exit race where the worker died first.
62
- if (--_saveWorkerRefCount === 0 && _saveWorker) _saveWorker.unref();
63
- const { id, session, summaryVersion, waiters } = p;
246
+ // becomes unref'd again once all in-flight writes settle.
247
+ // Never let the count go negative (a drain may have retired the
248
+ // bookkeeping while this write was still in the worker's queue),
249
+ // otherwise the `=== 0` unref below can never fire again and the
250
+ // process stays alive on a ref'd worker.
251
+ if (_saveWorkerRefCount > 0) _saveWorkerRefCount--;
252
+ if (_saveWorkerRefCount === 0) worker.unref();
253
+ const { id, session, attemptSnapshot, summaryVersion, summaryRow, waiters, epoch, revision, incarnation } = p;
254
+ const isCurrentIncarnation = _isCurrentSessionIncarnation(id, incarnation);
255
+ // NOTE: the reference is released in the finally below, AFTER every
256
+ // marker decision, so release-time eviction cannot change the verdict.
257
+ try {
258
+ if (!isCurrentIncarnation) {
259
+ // Hard delete landed after this write was posted. Its outcome is
260
+ // about a file that no longer exists: settle every caller exactly
261
+ // once, then touch NOTHING — no drop/failure marker, no summary
262
+ // publish, no live pin, no delta baseline. The id may already
263
+ // belong to a NEW incarnation, so only slots this very request
264
+ // still owns may be cleared.
265
+ if (_saveAsyncInflight.get(id) === reqId) _saveAsyncInflight.delete(id);
266
+ const stale = _saveAsyncQueued.get(id);
267
+ if (stale && stale.incarnation === incarnation) {
268
+ _saveAsyncQueued.delete(id);
269
+ _releaseSessionIncarnation(stale.incarnation);
270
+ for (const w of stale.waiters) w.resolve();
271
+ }
272
+ if (ok) for (const w of waiters) w.resolve();
273
+ else for (const w of waiters) w.reject(_workerSaveError(error, errorCode, injectedSaveFault));
274
+ return;
275
+ }
64
276
  _saveAsyncInflight.delete(id);
277
+ if (ok && deltaMiss && !p.retriedFull) {
278
+ // The worker restarted or evicted this id's base mid-chain. Not a
279
+ // drop: retry once as a FULL snapshot of the current live session
280
+ // (latest-wins durability, same waiters). The queued slot stays
281
+ // queued and promotes after the retry settles.
282
+ _invalidateDeltaBaseline(id);
283
+ try {
284
+ _postAsyncWrite(id, session, p.opts, waiters, summaryVersion, epoch, revision, {
285
+ forceFull: true,
286
+ retriedFull: true,
287
+ });
288
+ return;
289
+ } catch (err) {
290
+ // The RETRY is its own attempt: only its projected payload may
291
+ // stand as evidence. Falling back to the original delta
292
+ // snapshot would publish bytes this failure never attempted.
293
+ _failWorkerWrite(id, summaryVersion, waiters, err, epoch, incarnation, err?.attemptSnapshot ?? null, isCurrentIncarnation);
294
+ }
295
+ }
65
296
  // Resolve/reject every caller whose payload this write represents
66
297
  // (the originating call plus any that coalesced onto it before it was
67
298
  // posted). A supersede never lands here as a rejection — only a real
68
- // worker failure does.
69
- if (ok) {
299
+ // worker failure does. (A deltaMiss on a retried FULL is unreachable —
300
+ // the worker only misses on delta payloads.)
301
+ else if (ok) {
70
302
  // A close/delete may have completed while the worker was writing.
71
303
  // Do not let this older completion put an open row back in the
72
304
  // process-local cache after its tombstone/removal.
73
305
  if (saved) {
74
- _queueSessionSummaryUpsert(session, summaryVersion);
75
- _droppedSaveIds.delete(id);
306
+ // Publish the IMMUTABLE row captured when this payload was
307
+ // built — never a row re-derived from the live session, which
308
+ // may already carry a newer (unwritten, possibly failing) turn.
309
+ _queueSessionSummaryUpsertRow(summaryRow, summaryVersion);
310
+ // ONLY a landed write proves durability, so this is the only
311
+ // place the save-failure flag may be cleared — and only when
312
+ // THIS payload is at least as new as the newest failed/dropped
313
+ // one. An older worker write finishing after a newer sync/async
314
+ // failure carries stale content and must leave the markers (and
315
+ // therefore the live pin) exactly where they are.
316
+ _clearSaveStateIfCurrent(id, epoch);
317
+ } else if (outcome === SAVE_OUTCOME_STALE) {
318
+ // A strictly NEWER write for this id already landed: disk is
319
+ // AHEAD of this payload, not behind it. Nothing was lost, so
320
+ // no drop marker, no save error and no live pin — the snapshot
321
+ // stays immediately evictable. Only the optimistic summary row
322
+ // for these bytes is rolled back.
323
+ _invalidateDeltaBaseline(id);
324
+ _rollbackCachedSessionSummary(id, summaryVersion);
76
325
  } else {
77
326
  // The worker's _shouldDrop declined the write: disk ownership
78
327
  // moved past this snapshot — flag the split-brain so eviction
79
328
  // and disk-over-live arbitration keep the richer local copy.
329
+ // Nothing was written, so an earlier save failure for this id
330
+ // STAYS recorded (clearing it here would un-pin the only good
331
+ // in-memory transcript for an id whose disk copy is behind).
332
+ _invalidateDeltaBaseline(id);
80
333
  _rollbackCachedSessionSummary(id, summaryVersion);
81
- _droppedSaveIds.add(id);
334
+ _recordSaveDrop(id, epoch);
82
335
  }
83
- clearSessionSaveError(id);
84
336
  for (const w of waiters) w.resolve();
85
337
  }
86
338
  else {
87
- const e = new Error(`[session-store] worker save failed: ${error}`);
88
- for (const w of waiters) w.reject(e);
339
+ _failWorkerWrite(id, summaryVersion, waiters, _workerSaveError(error, errorCode, injectedSaveFault), epoch, incarnation, attemptSnapshot, isCurrentIncarnation);
89
340
  }
90
341
  // Promote the latest-wins queued payload (if any) into the now-free
91
342
  // in-flight slot for this id. Runs regardless of ok: the queued write
@@ -94,30 +345,52 @@ function _getOrSpawnWorker() {
94
345
  const q = _saveAsyncQueued.get(id);
95
346
  if (q) {
96
347
  _saveAsyncQueued.delete(id);
348
+ // The promotion KEEPS the queued reference through projection, the
349
+ // post and any immediate failure settlement: releasing first would
350
+ // let cap eviction drop the token and make a real current failure
351
+ // look like a stale post-delete outcome (no marker, no live pin).
352
+ const queuedCurrent = _isCurrentSessionIncarnation(id, q.incarnation);
97
353
  try {
98
- _postAsyncWrite(id, q.session, q.opts, q.waiters, q.summaryVersion);
354
+ _postAsyncWrite(id, q.session, q.opts, q.waiters, q.summaryVersion, q.epoch, q.revision);
99
355
  } catch (err) {
100
- _rollbackCachedSessionSummary(id, q.summaryVersion);
101
- for (const w of q.waiters) w.reject(err);
356
+ // Evidence is this promotion's OWN projected attempt when it
357
+ // got that far, never the queued (unprojected) live session.
358
+ _failWorkerWrite(id, q.summaryVersion, q.waiters, err, q.epoch, q.incarnation, err?.attemptSnapshot ?? null, queuedCurrent);
359
+ } finally {
360
+ _releaseSessionIncarnation(q.incarnation);
102
361
  }
103
362
  }
363
+ } finally {
364
+ _releaseSessionIncarnation(incarnation);
365
+ }
104
366
  });
105
- _saveWorker.on('error', (err) => {
367
+ worker.on('error', (err) => {
368
+ if (worker !== _saveWorker) return; // a replacement owns the maps now
369
+ _deltaBaseline.clear();
106
370
  for (const [, p] of _saveWorkerPending) {
107
- _rollbackCachedSessionSummary(p.id, p.summaryVersion);
108
- for (const w of p.waiters) w.reject(err);
371
+ _failWorkerWrite(p.id, p.summaryVersion, p.waiters, err, p.epoch, p.incarnation, p.attemptSnapshot);
372
+ _releaseSessionIncarnation(p.incarnation);
109
373
  }
110
374
  _saveWorkerPending.clear();
111
375
  for (const [id, q] of _saveAsyncQueued) {
112
- _rollbackCachedSessionSummary(id, q.summaryVersion);
113
- for (const w of q.waiters) w.reject(err);
376
+ // A queued payload was never projected or posted: it is settled and the
377
+ // operational error is recorded, but it may NEVER stand as recovery
378
+ // evidence (that must be an attempted, immutable payload).
379
+ _failWorkerWrite(id, q.summaryVersion, q.waiters, err, q.epoch, q.incarnation, null);
380
+ _releaseSessionIncarnation(q.incarnation);
114
381
  }
115
382
  _saveAsyncQueued.clear();
116
383
  _saveAsyncInflight.clear();
117
384
  _saveWorkerRefCount = 0;
385
+ _faultSyncedKey = null;
118
386
  _saveWorker = null;
119
387
  });
120
- _saveWorker.on('exit', (code) => {
388
+ worker.on('exit', (code) => {
389
+ // 'exit' ALWAYS follows 'error' (which already nulled _saveWorker) and
390
+ // can arrive after a replacement spawned: only the current instance may
391
+ // retire the shared bookkeeping.
392
+ if (worker !== _saveWorker) return;
393
+ _deltaBaseline.clear();
121
394
  // Reject pending resolvers on ANY exit (code 0 included) so an idle
122
395
  // worker that races a pending postMessage cannot leak resolvers. The
123
396
  // map is empty on the normal idle-exit path so the loop is a no-op,
@@ -126,21 +399,25 @@ function _getOrSpawnWorker() {
126
399
  // received the message.
127
400
  const err = new Error(`[session-store] save worker exited with code ${code}`);
128
401
  for (const [, p] of _saveWorkerPending) {
129
- _rollbackCachedSessionSummary(p.id, p.summaryVersion);
130
- for (const w of p.waiters) w.reject(err);
402
+ _failWorkerWrite(p.id, p.summaryVersion, p.waiters, err, p.epoch, p.incarnation, p.attemptSnapshot);
403
+ _releaseSessionIncarnation(p.incarnation);
131
404
  }
132
405
  _saveWorkerPending.clear();
133
406
  for (const [id, q] of _saveAsyncQueued) {
134
- _rollbackCachedSessionSummary(id, q.summaryVersion);
135
- for (const w of q.waiters) w.reject(err);
407
+ // A queued payload was never projected or posted: it is settled and the
408
+ // operational error is recorded, but it may NEVER stand as recovery
409
+ // evidence (that must be an attempted, immutable payload).
410
+ _failWorkerWrite(id, q.summaryVersion, q.waiters, err, q.epoch, q.incarnation, null);
411
+ _releaseSessionIncarnation(q.incarnation);
136
412
  }
137
413
  _saveAsyncQueued.clear();
138
414
  _saveAsyncInflight.clear();
139
415
  _saveWorkerRefCount = 0;
416
+ _faultSyncedKey = null;
140
417
  _saveWorker = null;
141
418
  });
142
- _saveWorker.unref(); // don't keep process alive
143
- return _saveWorker;
419
+ worker.unref(); // don't keep process alive
420
+ return worker;
144
421
  }
145
422
 
146
423
  /**
@@ -149,26 +426,70 @@ function _getOrSpawnWorker() {
149
426
  * in flight for `id`. Throws (after cleaning its own map entries) if the
150
427
  * worker postMessage fails so the caller can reject the affected waiters.
151
428
  */
152
- function _postAsyncWrite(id, session, opts, waiters, summaryVersion) {
429
+ function _postAsyncWrite(id, session, opts, waiters, summaryVersion, epoch, revision = 0, { forceFull = false, retriedFull = false } = {}) {
153
430
  const reqId = ++_saveWorkerReqId;
431
+ // The wire payload is built at POST time from the live session: N calls
432
+ // coalesced behind one in-flight write project ONCE (newest state), and a
433
+ // pure-append turn ships only the tail (see _buildWirePayload).
434
+ const wire = _buildWirePayload(id, session, forceFull);
435
+ // Snapshot the summary metadata for exactly these bytes, at exactly this
436
+ // moment. The pending entry then holds immutable payload data even though
437
+ // `session` remains the live object the exit drain needs.
438
+ const summaryRow = _sessionSummary(session);
439
+ // IMMUTABLE failure evidence for exactly this attempt: the message list is
440
+ // copied now, so a later mutation of the live session cannot change what a
441
+ // failed settlement records.
442
+ // DEEP, immutable copy of the EXACT projected payload posted to the
443
+ // worker (disk-ineligible data already stripped). Mutating any nested
444
+ // message/tool/media field afterwards cannot change this evidence.
445
+ let attemptSnapshot = null;
446
+ try {
447
+ attemptSnapshot = wire.attempt ? structuredClone(wire.attempt) : null;
448
+ } catch {
449
+ attemptSnapshot = null; // unclonable payload records no evidence at all
450
+ }
154
451
  _saveWorkerPending.set(reqId, {
155
452
  id,
156
453
  session,
454
+ attemptSnapshot,
157
455
  opts,
158
456
  summaryVersion,
457
+ summaryRow,
159
458
  waiters,
459
+ retriedFull,
460
+ epoch,
461
+ revision,
462
+ // Incarnation observed at POST time. Settlement compares OBJECT
463
+ // IDENTITY, so a hard delete — and any later reuse of the id — is
464
+ // detected exactly, with no counter to wrap, reset or collide.
465
+ incarnation: _acquireSessionIncarnation(id),
160
466
  });
161
467
  _saveAsyncInflight.set(id, reqId);
162
468
  try {
163
469
  const w = _getOrSpawnWorker();
164
- w.postMessage({ session, opts, reqId });
470
+ // Cheap key compare; posts only when the fault config/env moved.
471
+ _syncFaultToWorker(w);
472
+ const { attempt: _attempt, ...wireForPost } = wire;
473
+ w.postMessage({ ...wireForPost, id, opts, reqId });
165
474
  // Ref AFTER successful postMessage so a queue/throw failure path does
166
475
  // not leave the worker held alive with no pending message. Paired with
167
476
  // the unref in the message handler when count hits 0.
168
477
  if (++_saveWorkerRefCount === 1) w.ref();
169
478
  } catch (err) {
479
+ // Projection SUCCEEDED but posting failed: carry the exact projected
480
+ // attempt with the error so the caller records immutable evidence
481
+ // instead of the mutable live session. When projection/clone itself
482
+ // failed there is no attempted payload, so no evidence is recorded.
483
+ if (attemptSnapshot && err && typeof err === 'object' && err.attemptSnapshot === undefined) {
484
+ try { err.attemptSnapshot = attemptSnapshot; } catch { /* frozen error */ }
485
+ }
486
+ // This entry never reaches the message handler, so its incarnation
487
+ // reference is freed here.
488
+ const orphan = _saveWorkerPending.get(reqId);
489
+ _releaseSessionIncarnation(orphan?.incarnation);
170
490
  _saveWorkerPending.delete(reqId);
171
491
  _saveAsyncInflight.delete(id);
492
+ _invalidateDeltaBaseline(id);
172
493
  throw err;
173
494
  }
174
495
  }
@@ -184,16 +505,42 @@ function _postAsyncWrite(id, session, opts, waiters, summaryVersion) {
184
505
  * is only posted once the prior in-flight write for that id settles); different
185
506
  * ids interleave freely as before.
186
507
  */
187
- export function saveSessionAsync(session, opts) {
188
- _ensureLifecycleFields(session);
189
- setLiveSession(session);
508
+ export function saveSessionAsync(session, opts, options = {}) {
190
509
  const id = session.id;
191
- const summaryVersion = _cacheSessionSummary(session);
192
- const safeOpts = opts?._sessionWriteGuard ? opts : _guardedSaveOptions(id, opts);
193
- // Worker.postMessage clones on THIS thread. Project to the canonical disk
194
- // shape first so media bytes and duplicate live-turn aliases never enter
195
- // that clone. setLiveSession above deliberately retains the rich original.
196
- const clonePayload = _sessionPayloadForSaveWorker(session);
510
+ let summaryVersion = null;
511
+ let safeOpts = null;
512
+ // Identity of THIS attempt (see live-state _clearSaveStateIfCurrent): the
513
+ // content handed over here, not the moment the worker happens to finish.
514
+ // A deferred save promotes with the epoch it was ISSUED with, so the wait
515
+ // for its check phase cannot make an older snapshot look newer.
516
+ const epoch = Number.isFinite(options.epoch) ? options.epoch : _nextSaveEpoch();
517
+ // Payload revision WITHIN that identity (see parkSessionSnapshotForDrain):
518
+ // the drain uses it to rank this exact payload against a parked snapshot
519
+ // sharing the same epoch.
520
+ const revision = Number.isFinite(options.revision) ? options.revision : 0;
521
+ // PRE-ADMISSION: strict canonical authority BEFORE anything is published.
522
+ // A refusal publishes no live snapshot and no optimistic summary row, so a
523
+ // foreign/ambiguous record is never cached as owned even transiently.
524
+ const unowned = _refuseUnownedWrite(id);
525
+ if (unowned) return Promise.reject(unowned);
526
+ try {
527
+ _ensureLifecycleFields(session);
528
+ // Pin the live snapshot BEFORE anything can fail: every failure below
529
+ // leaves this process's memory as the only copy of the newest turn.
530
+ setLiveSession(session);
531
+ summaryVersion = _cacheSessionSummary(session);
532
+ // The guard carries this snapshot's epoch across the thread boundary,
533
+ // so the worker's own commit is fenced against a newer landed write.
534
+ safeOpts = opts?._sessionWriteGuard ? opts : _guardedSaveOptions(id, opts, epoch);
535
+ } catch (err) {
536
+ // Setup/guard failure is a save failure like any other: record it
537
+ // before the caller can observe the rejection.
538
+ _failWorkerWrite(id, summaryVersion, [], err, epoch, null, err?.attemptSnapshot ?? null);
539
+ return Promise.reject(err);
540
+ }
541
+ // Projection/clone now happen at POST time (see _postAsyncWrite): pending
542
+ // entries hold the LIVE session reference — same object listings and the
543
+ // exit drain already consume — so superseded saves never pay a projection.
197
544
  return new Promise((resolve, reject) => {
198
545
  const waiter = { resolve, reject };
199
546
  if (_saveAsyncInflight.has(id)) {
@@ -203,15 +550,20 @@ export function saveSessionAsync(session, opts) {
203
550
  // hang, never reject on supersede).
204
551
  const q = _saveAsyncQueued.get(id);
205
552
  if (q) {
206
- q.session = clonePayload;
553
+ q.session = session;
207
554
  q.opts = safeOpts;
208
555
  q.summaryVersion = summaryVersion;
556
+ q.epoch = epoch;
557
+ q.revision = revision;
209
558
  q.waiters.push(waiter);
210
559
  } else {
211
560
  _saveAsyncQueued.set(id, {
212
- session: clonePayload,
561
+ session,
213
562
  opts: safeOpts,
214
563
  summaryVersion,
564
+ epoch,
565
+ revision,
566
+ incarnation: _acquireSessionIncarnation(id),
215
567
  waiters: [waiter],
216
568
  });
217
569
  }
@@ -221,10 +573,12 @@ export function saveSessionAsync(session, opts) {
221
573
  // in-flight entry persists {session, opts} so drainSessionStore can
222
574
  // sync-flush outstanding writes if process exit interrupts the queue.
223
575
  try {
224
- _postAsyncWrite(id, clonePayload, safeOpts, [waiter], summaryVersion);
576
+ _postAsyncWrite(id, session, safeOpts, [waiter], summaryVersion, epoch, revision);
225
577
  } catch (err) {
226
- _rollbackCachedSessionSummary(id, summaryVersion);
227
- reject(err);
578
+ // Payload-build / spawn / postMessage-clone failure. Record the
579
+ // save failure (live snapshot pinned + non-evictable) BEFORE the
580
+ // waiter is rejected, exactly like a settled worker failure.
581
+ _failWorkerWrite(id, summaryVersion, [waiter], err, epoch, null, err?.attemptSnapshot ?? null);
228
582
  }
229
583
  });
230
584
  }
@@ -234,14 +588,33 @@ export function saveSessionAsync(session, opts) {
234
588
  * Worker.postMessage performs its main-thread structured clone.
235
589
  */
236
590
  export function saveSessionAsyncDeferred(session, opts) {
237
- _ensureLifecycleFields(session);
238
- setLiveSession(session);
239
- _cacheSessionSummary(session);
240
591
  const reqId = ++_deferredSaveReqId;
592
+ // Issued NOW: this identity travels through the deferred map, the promoted
593
+ // async save and the exit drain unchanged.
594
+ const epoch = _nextSaveEpoch();
241
595
  return new Promise((resolve, reject) => {
596
+ const unowned = _refuseUnownedWrite(session?.id);
597
+ if (unowned) {
598
+ reject(unowned);
599
+ return;
600
+ }
601
+ try {
602
+ _ensureLifecycleFields(session);
603
+ setLiveSession(session);
604
+ _cacheSessionSummary(session);
605
+ } catch (err) {
606
+ _failWorkerWrite(session?.id, null, [], err, epoch, null, err?.attemptSnapshot ?? null);
607
+ reject(err);
608
+ return;
609
+ }
242
610
  _deferredSessionSaves.set(reqId, {
243
611
  session,
244
- opts: _guardedSaveOptions(session.id, opts),
612
+ opts: _guardedSaveOptions(session.id, opts, epoch),
613
+ epoch,
614
+ revision: 0,
615
+ // Deferred payloads are incarnation-stamped like every other unit
616
+ // of work: a hard delete retires them with the id.
617
+ incarnation: _acquireSessionIncarnation(session.id),
245
618
  resolve,
246
619
  reject,
247
620
  });
@@ -249,14 +622,210 @@ export function saveSessionAsyncDeferred(session, opts) {
249
622
  const pending = _deferredSessionSaves.get(reqId);
250
623
  if (!pending) return;
251
624
  _deferredSessionSaves.delete(reqId);
252
- saveSessionAsync(pending.session, pending.opts).then(resolve, reject);
625
+ // The promoted save takes its own stamp.
626
+ _releaseSessionIncarnation(pending.incarnation);
627
+ try {
628
+ saveSessionAsync(pending.session, pending.opts, { epoch: pending.epoch }).then(resolve, reject);
629
+ } catch (err) {
630
+ _failWorkerWrite(session?.id, null, [], err, epoch, null, err?.attemptSnapshot ?? null);
631
+ reject(err);
632
+ }
253
633
  });
254
634
  });
255
635
  }
256
636
 
257
637
  export function _resetSaveWorkerBookkeeping() {
638
+ // Release any worker ref still held by writes we are retiring: dropping
639
+ // the maps without unref'ing leaves the process pinned alive by a worker
640
+ // whose completion message will never find its pending entry.
641
+ if (_saveWorkerRefCount > 0 && _saveWorker) {
642
+ try { _saveWorker.unref(); } catch { /* worker already gone */ }
643
+ }
644
+ // Retiring the maps also retires their incarnation references.
645
+ for (const [, p] of _saveWorkerPending) _releaseSessionIncarnation(p.incarnation);
646
+ for (const [, q] of _saveAsyncQueued) _releaseSessionIncarnation(q.incarnation);
647
+ _saveWorkerPending.clear();
648
+ _saveAsyncQueued.clear();
649
+ _saveAsyncInflight.clear();
650
+ _saveWorkerRefCount = 0;
651
+ _deltaBaseline.clear();
652
+ }
653
+
654
+ const _noopSettle = () => {};
655
+
656
+ /**
657
+ * Park a still-deferred snapshot in the SAME map the exit drain already walks
658
+ * (`_deferredSessionSaves`). A module that throttles its own saves therefore
659
+ * needs no second exit-flush path: the drain picks the snapshot up ranked by
660
+ * its issuance epoch, under a fresh cancellation guard, the shared commit
661
+ * lock, the ownership (`expectedGeneration`) check, the landed-epoch fence and
662
+ * the one global drain deadline.
663
+ *
664
+ * Re-parking the same session PRESERVES the epoch and the guarded options it
665
+ * was first deferred with — parking never mints fresh write authority, and the
666
+ * original `expectedGeneration` keeps a later lifecycle barrier authoritative.
667
+ * The returned handle carries those guarded options so the owner can run its
668
+ * OWN save (and every retry of it) under exactly this identity.
669
+ */
670
+ export function parkSessionSnapshotForDrain(session, opts, handle = null) {
671
+ const id = session?.id;
672
+ if (!id) return null;
673
+ const parked = handle?.key === undefined ? null : _deferredSessionSaves.get(handle.key);
674
+ if (parked && parked.session?.id === id) {
675
+ if (parked.session !== session) {
676
+ // A DISTINCT newer payload under the same issuance identity: bump
677
+ // the revision so the drain can rank it above an in-flight write
678
+ // that was posted from the previous ref.
679
+ parked.session = session;
680
+ parked.revision += 1;
681
+ handle.revision = parked.revision;
682
+ }
683
+ return handle;
684
+ }
685
+ const epoch = _nextSaveEpoch();
686
+ const key = ++_deferredSaveReqId;
687
+ const guarded = _guardedSaveOptions(id, opts, epoch);
688
+ _deferredSessionSaves.set(key, {
689
+ session,
690
+ opts: guarded,
691
+ epoch,
692
+ revision: 0,
693
+ incarnation: _acquireSessionIncarnation(id),
694
+ resolve: _noopSettle,
695
+ reject: _noopSettle,
696
+ });
697
+ return { key, epoch, revision: 0, opts: guarded };
698
+ }
699
+
700
+ /** Drop a parked snapshot once its own save path took over (or on close). */
701
+ export function unparkSessionSnapshotForDrain(handle) {
702
+ if (handle?.key === undefined) return;
703
+ const parked = _deferredSessionSaves.get(handle.key);
704
+ if (parked) _releaseSessionIncarnation(parked.incarnation);
705
+ _deferredSessionSaves.delete(handle.key);
706
+ }
707
+
708
+ /**
709
+ * Hard delete: drop ALL save bookkeeping owned by the retired incarnation —
710
+ * deferred/parked snapshots, the in-flight slot and the latest-wins queued
711
+ * follow-up — so nothing (the exit drain included) can re-create the file, and
712
+ * so a RE-CREATED id starts from an empty slot instead of queueing behind a
713
+ * dead write. Settled as resolved: the session is gone, so the write is moot
714
+ * (rejecting would strand unhandled rejections on finished callers).
715
+ * Returns how many entries were purged.
716
+ */
717
+ export function purgeSessionSaveBookkeeping(id) {
718
+ if (!id) return 0;
719
+ let purged = 0;
720
+ for (const [key, pending] of [..._deferredSessionSaves]) {
721
+ if (pending?.session?.id !== id) continue;
722
+ _deferredSessionSaves.delete(key);
723
+ _releaseSessionIncarnation(pending.incarnation);
724
+ purged += 1;
725
+ try { pending.resolve(); } catch { /* best-effort */ }
726
+ }
727
+ // The in-flight slot and the queued follow-up belong to the retired
728
+ // incarnation: their replies settle inert, so free the slots now.
729
+ _saveAsyncInflight.delete(id);
730
+ const queued = _saveAsyncQueued.get(id);
731
+ if (queued) {
732
+ _saveAsyncQueued.delete(id);
733
+ _releaseSessionIncarnation(queued.incarnation);
734
+ purged += 1;
735
+ for (const w of queued.waiters) {
736
+ try { w.resolve(); } catch { /* best-effort */ }
737
+ }
738
+ }
739
+ _invalidateDeltaBaseline(id);
740
+ return purged;
741
+ }
742
+
743
+ /**
744
+ * TEST-ONLY, STRUCTURALLY GATED to the store's fault-injection test mode:
745
+ * detach the live save worker exactly as its own 'error' handler would (module
746
+ * pointer cleared, instance and its handlers left intact) and return it. That
747
+ * is the real shape of the race — the next save spawns a replacement while the
748
+ * detached instance can still emit its late 'exit'/'error'. Returns null when
749
+ * the gate is absent, so production cannot reach it.
750
+ *
751
+ * Detaching with work in flight settles that work exactly like the 'error'
752
+ * path: every waiter is rejected (failure recorded first, live snapshot
753
+ * pinned), the queued slots are settled the same way and the worker ref is
754
+ * released, so no promise and no ref-count can be orphaned.
755
+ */
756
+ export function _detachSaveWorkerForTest() {
757
+ if (!_sessionStoreTestMode()) return null;
758
+ const worker = _saveWorker;
759
+ if (!worker) return null;
760
+ _saveWorker = null;
761
+ _faultSyncedKey = null;
762
+ const detached = new Error('[session-store] save worker detached before this write settled');
763
+ for (const [, p] of _saveWorkerPending) {
764
+ _failWorkerWrite(p.id, p.summaryVersion, p.waiters, detached, p.epoch, p.incarnation, p.attemptSnapshot);
765
+ _releaseSessionIncarnation(p.incarnation);
766
+ }
258
767
  _saveWorkerPending.clear();
768
+ for (const [id, q] of _saveAsyncQueued) {
769
+ _failWorkerWrite(id, q.summaryVersion, q.waiters, detached, q.epoch, q.incarnation, null);
770
+ _releaseSessionIncarnation(q.incarnation);
771
+ }
259
772
  _saveAsyncQueued.clear();
260
773
  _saveAsyncInflight.clear();
774
+ if (_saveWorkerRefCount > 0) {
775
+ try { worker.unref(); } catch { /* worker already gone */ }
776
+ }
261
777
  _saveWorkerRefCount = 0;
778
+ _deltaBaseline.clear();
779
+ return worker;
780
+ }
781
+
782
+ /**
783
+ * TEST-ONLY, STRUCTURALLY GATED to the store's fault-injection test mode:
784
+ * make the LIVE worker forget one id's delta base, leaving the worker instance
785
+ * and the parent's delta baseline untouched. The next delta for that id then
786
+ * legitimately answers `deltaMiss`, which is the only way to exercise the
787
+ * parent's full-retry path deterministically.
788
+ */
789
+ export function _evictWorkerDeltaBaseForTest(id) {
790
+ if (!_sessionStoreTestMode() || !id || !_saveWorker) return false;
791
+ try {
792
+ _saveWorker.postMessage({ __evictBase: String(id) });
793
+ return true;
794
+ } catch {
795
+ return false;
796
+ }
797
+ }
798
+
799
+ /**
800
+ * TEST-ONLY, STRUCTURALLY GATED read-only inspector: does the live worker
801
+ * still hold a delta base for `id`? Used to prove that the eviction seam
802
+ * touches exactly one id (and never clears the whole base map).
803
+ */
804
+ export function _probeWorkerDeltaBaseForTest(id, { timeoutMs = 2000 } = {}) {
805
+ if (!_sessionStoreTestMode() || !id || !_saveWorker) return Promise.resolve(null);
806
+ const worker = _saveWorker;
807
+ return new Promise((resolve) => {
808
+ let timer = null;
809
+ const onMessage = (message) => {
810
+ const result = message?.__baseProbeResult;
811
+ if (!result || result.id !== id) return;
812
+ worker.off('message', onMessage);
813
+ if (timer) clearTimeout(timer);
814
+ resolve(result.hasBase === true);
815
+ };
816
+ worker.on('message', onMessage);
817
+ timer = setTimeout(() => {
818
+ worker.off('message', onMessage);
819
+ resolve(null);
820
+ }, timeoutMs);
821
+ // Deliberately NOT unref'd: the probe must settle even when nothing
822
+ // else keeps the loop alive (an unref'd timer would strand it).
823
+ try {
824
+ worker.postMessage({ __baseProbe: String(id) });
825
+ } catch {
826
+ worker.off('message', onMessage);
827
+ if (timer) clearTimeout(timer);
828
+ resolve(null);
829
+ }
830
+ });
262
831
  }