Repository navigation
Expand file tree
/
Copy pathsession_store.ts
More file actions
791 lines (732 loc) · 55.6 KB
/
Copy pathsession_store.ts
File metadata and controls
791 lines (732 loc) · 55.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
/** Per-session state persistence — the dropped Python `SessionCache` JSON. token-goat hooks run as a fresh `token-goat hook <event>` process per tool call, so the session Maps in {@link file://./session.ts} (read/edit tracking, shown-hint dedup, web/bash/curl recall indexes) would die at the end of every hook if kept only in memory. This module loads that state at the start of a hook and saves it at the end, keyed by session id, so re-read dedup and the recall hints work across the separate processes. Mirrors the on-disk conventions of `snapshots.ts`: a per-session file under `~/.token-goat/sessions/`, session-id sanitization, a traversal guard, and an atomic temp-file + rename. Two invariants hold every operation together: - **Fail-soft.** A disk error never throws; a corrupt/missing file is just an empty session. {@link file://./relay.ts} additionally guards the calls so a persistence bug can never drop a hook's real output. - **Merge-on-save.** Save re-reads the on-disk state and merges it with the in-memory state (set-union for hints, field-wise for files, newest-wins for the indexes). Combined with the atomic rename this bounds the cost of two overlapping same-session hook processes to, at worst, a dropped hint — never a corrupt file. */
import { createHash } from 'node:crypto'
import * as fs from 'node:fs'
import * as path from 'node:path'
import { ensureDirSync, atomicWriteText, foldPath, sanitizeIdForFilename, withFileLock, withRetryOnLock } from './util.js'
import { normalizePath } from './paths.js'
import { SESSIONS_SUBDIR, sessionsDir } from './sessions_dir.js'
import { redactSerializedJson } from './secret_redact.js'
import { MAX_SEEN_IMAGE_HASHES, MAX_VERIFICATION_RUNS, MAX_BASH_START_CWDS, bashStartCwdsAtLoad, consumedBashStartCwdKeys, consumedCurlDownloadKeys, consumedFileLineRangeKeys, consumedFileServedOutputKeys, migrateCurlDownloadKey, migrateWebFetchKey, consumedOutstandingAgentSpawnKeys, consumedPendingLargeFileHintKeys, curlDownloadsAtLoad, exportSessionState, filesReadCountAtLoad, filesFullReadCountAtLoad, importSessionState, markCompacted, mergeEpochBase, MAX_OUTSTANDING_AGENT_SPAWNS, MAX_RANGES_PER_FILE, MAX_SERVED_OUTPUTS_PER_FILE, MAX_GENERIC_SERVED_OUTPUTS, GENERIC_SERVED_OUTPUT_KEY, outstandingAgentSpawnKey, outstandingAgentSpawnsAtLoad, pendingLargeFileHintsAtLoad, type FileEntry, type FileRangeIdentity, type SerializedSession, type VerificationRun } from './session.js'
import { coerceReadRangeEvasion, mergeReadRangeEvasion } from './read_range_evasion.js'
import { getSharedMemoryDb, redactSharedMemoryText, sharedMemoryDigest } from './shared_memory_db.js'
/** Cap on tracked file entries kept per session; oldest by last-read are evicted. */
const MAX_FILES = 500
export { SESSIONS_SUBDIR }
/** The sanitized form of relay.ts's `sessionStateKey` agent-salt separator (`:agent:`), as it actually appears in an on-disk filename after {@link sessionPath}'s sanitization (`:` -> `_`). Exported so any code that needs to recognize or exclude a subagent-scoped session blob by filename (sibling-blob discovery for the pre_compact manifest, "latest session" resolution) derives the marker from the same sanitization logic rather than hardcoding a string that could drift out of sync with it. */
export const AGENT_SALT_MARKER = sanitizeIdForFilename(':agent:')
/** Raw separator `relay.ts`'s `sessionStateKey` joins a session id and an agent id with. */
const AGENT_SALT_SEPARATOR = ':agent:'
/** Characters of agent-id digest appended to a salted stem. 12 hex chars is 48 bits: far more than enough to keep the handful of subagents alive in one session apart, and short enough that the session id keeps most of the 64-char budget. */
const AGENT_DIGEST_CHARS = 12
/** How much of the session id a SALTED stem may use, leaving room for the marker and the digest so both always survive the 64-char cap. */
const SALTED_SESSION_MAX = 64 - AGENT_SALT_MARKER.length - AGENT_DIGEST_CHARS
/** The session-id portion of a salted filename, and the prefix sibling discovery matches on. Must be derived here rather than recomputed at each site, so the writer and the scanner can never disagree about how much of the id survived. */
function saltedStemPrefix(sessionId: string): string {
return `${sanitizeIdForFilename(sessionId, SALTED_SESSION_MAX)}${AGENT_SALT_MARKER}`
}
/** Filename stem for `sessionId`, which may be a plain session id or an agent-salted key (`${sessionId}:agent:${agentId}`, see relay.ts's `sessionStateKey`). A plain id keeps its exact human-readable `<sessionId>.json` spelling, capped at 64 chars. Callers and tests (`tests/session_persistence_e2e.test.ts`) rely on that, so it must not change. A salted key is spelled `<session id, capped>_agent_<12-hex digest of the agent id>`. The agent id is hashed rather than truncated because truncation lost the very distinction the salt exists to draw. `sessionStateKey`'s docstring states the salt is there so "a subagent's genuinely-first read of a file [is not] denied as 'already read' because a *different* subagent read it earlier" -- but the whole key used to be sanitized and sliced at 64 as one string, so once the session id reached 58 sanitized characters the 7-char marker itself was cut off and every subagent in that session, and at 64 the parent too, mapped onto one file. Reproduced against the built bundle: two sibling subagents each doing their first read of the same file produced two session files at a 36-char id and one at 55 and above, with the second subagent told "You've already read package.json" about a file it had never seen. Session ids come off the wire from whatever harness is driving (`relay.ts`'s `session_id` / `sessionId`), and `CLAUDE_CODE_SESSION_ID` is a plain env var a wrapper can set to any descriptive string, so ids well past 55 characters are not exotic. Hashing also retires the ~21-char-agent-id-prefix collision this function's previous comment accepted as a known risk: two agent ids sharing a long prefix no longer share a filename. */
export function sessionFileStem(sessionId: string): string {
const sep = sessionId.indexOf(AGENT_SALT_SEPARATOR)
if (sep < 0) return sanitizeIdForFilename(sessionId, 64)
const agentId = sessionId.slice(sep + AGENT_SALT_SEPARATOR.length)
const digest = createHash('sha256').update(agentId).digest('hex').slice(0, AGENT_DIGEST_CHARS)
return `${saltedStemPrefix(sessionId.slice(0, sep))}${digest}`
}
/** Resolve the on-disk path for `sessionId`, or null when the id is empty, sanitizes to empty, or would escape the sessions dir (traversal guard). See {@link sessionFileStem} for how salted keys are spelled. */
function sessionPath(sessionId: string): string | null {
return sessionSidecarPath(sessionId, '.json')
}
/** Ensure the private directory shared by a session state file and its sidecars. */
export function ensureSessionDirectory(sessionId: string): void {
const p = sessionPath(sessionId)
if (p === null) return
ensureDirSync(path.dirname(p))
}
/** Resolve the on-disk path for a session-scoped file, or null when the id is empty, sanitizes to empty, or would escape the sessions dir (traversal guard). `suffix` selects which file: `.json` is the session state itself, and any other suffix is a sidecar sharing the same salted stem. Exported so a caller needing per-session state of its own gets this sanitization and traversal guard rather than rebuilding either -- and so that state can live beside the session instead of inside its JSON, which would mean adding a field to the serialize, deserialize, validate and merge paths where omitting one half silently does nothing. See {@link sessionFileStem} for how salted keys are spelled. */
export function sessionSidecarPath(sessionId: string, suffix: string): string | null {
if (!sessionId) return null
const safe = sessionFileStem(sessionId)
if (!safe) return null
// A suffix is chosen by calling code, never by a session id, but it still lands in a filename: reject anything that could climb out of the directory rather than trusting the call site.
if (suffix.includes('/') || suffix.includes('\\') || suffix.includes('..')) return null
// Only the session state itself may end in `.json`: every reader that lists this directory (findLatestSessionId, listSiblingSessionStates, the manifest cleanup) takes a `.json` file to be a session, so a `.call-streak.json` sidecar resolved "the latest session" to an id nobody ever used.
if (suffix !== '.json' && suffix.endsWith('.json')) return null
const dir = sessionsDir()
const candidate = path.join(dir, `${safe}${suffix}`)
try {
const rel = path.relative(dir, candidate)
if (rel.startsWith('..')) return null
} catch {
return null
}
return candidate
}
function asStringPairs(raw: unknown): Array<[string, string]> {
if (!Array.isArray(raw)) return []
const out: Array<[string, string]> = []
for (const item of raw) {
if (Array.isArray(item) && typeof item[0] === 'string' && typeof item[1] === 'string') {
out.push([item[0], item[1]])
}
}
return out
}
function asFileEntry(raw: unknown): FileEntry | null {
if (raw === null || typeof raw !== 'object') return null
const o = raw as Record<string, unknown>
if (
typeof o['path'] !== 'string' ||
typeof o['readCount'] !== 'number' ||
typeof o['lastReadAt'] !== 'number' ||
typeof o['wasEdited'] !== 'boolean' ||
typeof o['sizeBytes'] !== 'number'
) {
return null
}
let entry: FileEntry = {
path: o['path'],
readCount: o['readCount'],
lastReadAt: o['lastReadAt'],
wasEdited: o['wasEdited'],
sizeBytes: o['sizeBytes'],
}
if (o['wasTruncated'] === true) entry = { ...entry, wasTruncated: true }
// Preserve the whole-file-read markers so a re-read's "unchanged since last read" denies survive a save -> load round-trip; without this a process boundary (every hook is a fresh process) silently drops them and a ranged-only read looks indistinguishable from a full one on the very next process, or vice versa.
if (typeof o['lastFullReadAt'] === 'number') entry = { ...entry, lastFullReadAt: o['lastFullReadAt'] }
if (typeof o['fullReadCount'] === 'number') entry = { ...entry, fullReadCount: o['fullReadCount'] }
if (typeof o['lastEditedAt'] === 'number') entry = { ...entry, lastEditedAt: o['lastEditedAt'] }
// Preserve the surgical-read tokens so compact.ts's symbolsBonus survives a save -> load round-trip; without this the field is silently dropped and the bonus is always zero.
if (Array.isArray(o['symbols_read'])) {
const symbols = (o['symbols_read'] as unknown[]).filter((s): s is string => typeof s === 'string')
if (symbols.length > 0) entry = { ...entry, symbols_read: symbols }
}
// Preserve the range-identity stamp so hooks_read.ts's no-snapshot repeated-range deny survives a save -> load round-trip; without this every hook process (a fresh process per invocation) sees it as never-recorded and falls back to denying unconditionally, defeating the external-edit check it exists for.
const rangeIdentity = o['rangeFileIdentity']
if (
rangeIdentity !== null && typeof rangeIdentity === 'object' &&
typeof (rangeIdentity as Record<string, unknown>)['size'] === 'number' &&
typeof (rangeIdentity as Record<string, unknown>)['mtimeMs'] === 'number'
) {
const fp = (rangeIdentity as Record<string, unknown>)['fp']
entry = { ...entry, rangeFileIdentity: { size: (rangeIdentity as Record<string, unknown>)['size'] as number, mtimeMs: (rangeIdentity as Record<string, unknown>)['mtimeMs'] as number, ...(typeof fp === 'string' && RANGE_FP_SHAPE.test(fp) ? { fp } : {}) } }
}
// Preserve the epoch snapshot so the manifest and the re-read denies still count only the reads since the last compaction after a save -> load round-trip; dropped, every later process would fall back to lifetime counts.
const epochBase = o['epochBase']
if (epochBase !== null && typeof epochBase === 'object') {
const b = epochBase as Record<string, unknown>
if (typeof b['at'] === 'number' && typeof b['readCount'] === 'number' && typeof b['fullReadCount'] === 'number') {
entry = { ...entry, epochBase: { at: b['at'], readCount: b['readCount'], fullReadCount: b['fullReadCount'] } }
}
}
return entry
}
/** Parse one entry from a Python-format `files` dict value into a {@link FileEntry}. Returns null for any malformed entry so the caller can skip it safely. Python fields: rel_or_abs (string), read_count (int), last_read_ts (float seconds), read_size (bytes), last_edit_ts (float seconds, may be absent). The dict key itself is used as the path fallback when rel_or_abs is missing. */
function asPyFileEntry(dictKey: string, raw: unknown): FileEntry | null {
if (raw === null || typeof raw !== 'object') return null
const v = raw as Record<string, unknown>
const p = typeof v['rel_or_abs'] === 'string' ? v['rel_or_abs'] : dictKey
if (!p) return null
const readCount = typeof v['read_count'] === 'number' ? Math.max(1, Math.round(v['read_count'])) : 1
const lastReadTs = typeof v['last_read_ts'] === 'number' ? v['last_read_ts'] : 0
const sizeBytes = typeof v['read_size'] === 'number' ? Math.round(v['read_size']) : 0
const wasEdited = typeof v['last_edit_ts'] === 'number' && v['last_edit_ts'] > 0
return { path: p, readCount, lastReadAt: lastReadTs * 1000, wasEdited, sizeBytes }
}
/** The shape of the SHA-256 hex digest the session writes as a range identity's `fp` (64 lowercase hex characters). A persisted `fp` of any other shape is left out on load, so its ranges count as unproven and are read through. */
const RANGE_FP_SHAPE = /^[0-9a-f]{64}$/
/** Coerce an untrusted value into the persisted per-file range identities (size + mtimeMs), dropping anything malformed. Never throws. */
function asRangeIdentities(raw: unknown): Array<[string, FileRangeIdentity]> {
if (!Array.isArray(raw)) return []
const out: Array<[string, FileRangeIdentity]> = []
for (const pair of raw) {
if (!Array.isArray(pair) || pair.length !== 2 || typeof pair[0] !== 'string') continue
const id = pair[1] as Record<string, unknown> | null
if (id !== null && typeof id === 'object' && typeof id['size'] === 'number' && typeof id['mtimeMs'] === 'number') out.push([pair[0], { size: id['size'], mtimeMs: id['mtimeMs'], ...(typeof id['fp'] === 'string' && RANGE_FP_SHAPE.test(id['fp']) ? { fp: id['fp'] } : {}) }])
}
return out
}
/** Coerce an untrusted value into the persisted line-ranges shape, dropping anything malformed. Never throws. */
function asLineRanges(raw: unknown): Array<[string, Array<[number, number]>]> {
if (!Array.isArray(raw)) return []
const out: Array<[string, Array<[number, number]>]> = []
for (const pair of raw) {
if (!Array.isArray(pair) || pair.length !== 2) continue
const filePath = pair[0]
const ranges = pair[1]
if (typeof filePath !== 'string' || !Array.isArray(ranges)) continue
const valid: Array<[number, number]> = []
for (const r of ranges) {
if (Array.isArray(r) && r.length === 2 && typeof r[0] === 'number' && typeof r[1] === 'number') valid.push([r[0], r[1]])
}
out.push([filePath, valid])
}
return out
}
/** Coerce the served-output index: a list of [path, ids] pairs, dropping any non-string entry. Mirrors {@link asLineRanges}; a malformed pair is skipped rather than throwing, since this is untrusted on-disk JSON. */
function asServedOutputs(raw: unknown): Array<[string, string[]]> {
if (!Array.isArray(raw)) return []
const out: Array<[string, string[]]> = []
for (const pair of raw) {
if (!Array.isArray(pair) || pair.length !== 2) continue
const filePath = pair[0]
const ids = pair[1]
if (typeof filePath !== 'string' || !Array.isArray(ids)) continue
out.push([filePath, ids.filter((id): id is string => typeof id === 'string')])
}
return out
}
/** Rewrite persisted keys into the current shape as they come off disk. Every disk read passes through {@link coerce}, including the fresh re-read the save path does before merging, so migrating here means no individual caller has to know a key shape ever changed. A last-write-wins collapse is correct if two legacy keys migrate to the same key: the new key is a function of the same pair, so a collision means they were the same fetch. */
function migrateKeys(pairs: Array<[string, string]>, migrate: (key: string) => string): Array<[string, string]> {
return pairs.map(([key, value]) => [migrate(key), value])
}
/** Coerce an untrusted parsed-JSON value into a valid (possibly empty) {@link SerializedSession}, dropping anything malformed. Never throws. Handles both the TS array format (`files: FileEntry[]`) and the legacy Python dict format (`files: { path: { rel_or_abs, read_count, last_read_ts, ... } }`). Python-format files are transparently migrated to the TS shape on load; the next {@link saveSessionState} call then writes the file in the TS format so subsequent loads use the fast path automatically. */
function coerce(raw: unknown): SerializedSession {
const o = (raw !== null && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
const files: FileEntry[] = []
if (Array.isArray(o['files'])) {
for (const f of o['files']) {
const e = asFileEntry(f)
if (e !== null) files.push(e)
}
} else if (o['files'] !== null && typeof o['files'] === 'object') {
// Python-format: files is a path-keyed object, not an array.
for (const [key, val] of Object.entries(o['files'] as Record<string, unknown>)) {
const e = asPyFileEntry(key, val)
if (e !== null) files.push(e)
}
}
// TS format uses `hintsShown`; Python format uses `hints_seen` — accept both.
const hintsShown = Array.isArray(o['hintsShown'])
? o['hintsShown'].filter((h): h is string => typeof h === 'string')
: Array.isArray(o['hints_seen'])
? (o['hints_seen'] as unknown[]).filter((h): h is string => typeof h === 'string')
: []
const scheduledPromptCounts: Array<[string, number]> = Array.isArray(o['scheduledPromptCounts'])
? (o['scheduledPromptCounts'] as unknown[]).filter(
(p): p is [string, number] =>
Array.isArray(p) && p.length === 2 && typeof p[0] === 'string'
&& typeof p[1] === 'number' && Number.isSafeInteger(p[1]) && p[1] >= 0,
)
: []
const cliReads = Array.isArray(o['cliReads'])
? o['cliReads'].filter((h): h is string => typeof h === 'string')
: []
const bashReruns = Array.isArray(o['bashReruns'])
? o['bashReruns'].filter((h): h is string => typeof h === 'string')
: []
const seenImageHashes = Array.isArray(o['seenImageHashes'])
? o['seenImageHashes'].filter((h): h is string => typeof h === 'string')
: []
const verificationRuns: VerificationRun[] = Array.isArray(o['verificationRuns'])
? (o['verificationRuns'] as unknown[]).filter(
(r): r is VerificationRun =>
r !== null && typeof r === 'object' && typeof (r as VerificationRun).command === 'string' && typeof (r as VerificationRun).at === 'number' &&
((r as VerificationRun).exitCode === null || typeof (r as VerificationRun).exitCode === 'number'),
)
: []
const pendingLargeFileHints: Array<[string, number]> = Array.isArray(o['pendingLargeFileHints'])
? (o['pendingLargeFileHints'] as unknown[]).filter(
(p): p is [string, number] =>
Array.isArray(p) && p.length === 2 && typeof p[0] === 'string' && typeof p[1] === 'number',
)
: []
const grepQueries: Array<[string, number]> = Array.isArray(o['grepQueries'])
? (o['grepQueries'] as unknown[]).filter(
(p): p is [string, number] =>
Array.isArray(p) && p.length === 2 && typeof p[0] === 'string' && typeof p[1] === 'number',
)
: []
const globQueries: Array<[string, number]> = Array.isArray(o['globQueries'])
? (o['globQueries'] as unknown[]).filter(
(p): p is [string, number] =>
Array.isArray(p) && p.length === 2 && typeof p[0] === 'string' && typeof p[1] === 'number',
)
: []
const outstandingAgentSpawns: Array<[string, number]> = Array.isArray(o['outstandingAgentSpawns'])
? (o['outstandingAgentSpawns'] as unknown[]).filter(
(p): p is [string, number] =>
Array.isArray(p) && p.length === 2 && typeof p[0] === 'string' && typeof p[1] === 'number',
)
: []
const rangeIdentities = asRangeIdentities(o['fileLineRangeIdentities'])
return {
files,
hintsShown,
...(scheduledPromptCounts.length > 0 ? { scheduledPromptCounts } : {}),
webFetches: migrateKeys(asStringPairs(o['webFetches']), migrateWebFetchKey),
bashOutputs: asStringPairs(o['bashOutputs']),
curlDownloads: migrateKeys(asStringPairs(o['curlDownloads']), migrateCurlDownloadKey),
fileLineRanges: asLineRanges(o['fileLineRanges']),
readRangeEvasion: coerceReadRangeEvasion(o['readRangeEvasion']),
...(rangeIdentities.length > 0 ? { fileLineRangeIdentities: rangeIdentities } : {}),
fileServedOutputs: asServedOutputs(o['fileServedOutputs']),
cliReads,
bashReruns,
pendingLargeFileHints,
bashStartCwds: asStringPairs(o['bashStartCwds']),
grepQueries,
globQueries,
outstandingAgentSpawns,
...(typeof o['lastTabContextDigest'] === 'string' ? { lastTabContextDigest: o['lastTabContextDigest'] } : {}),
...(seenImageHashes.length > 0 ? { seenImageHashes } : {}),
...(verificationRuns.length > 0 ? { verificationRuns } : {}),
...(typeof o['compactedAt'] === 'number' ? { compactedAt: o['compactedAt'] } : {}),
...(typeof o['created_ts'] === 'number' ? { created_ts: o['created_ts'] } : {}),
}
}
/** Combine two views of one file: keep every read/edit/truncation signal and the size from the more recent read. Never loses a positive flag. */
function mergeFileEntry(a: FileEntry, b: FileEntry): FileEntry {
const newest = a.lastReadAt >= b.lastReadAt ? a : b
// readCount is reconciled, not maxed: b (this process's own in-memory view) may have started from a stale disk snapshot and incremented independently of whatever other concurrent processes already wrote into a (the freshest disk read, taken under the save lock in saveSessionState). Math.max(a, b) silently drops a concurrent process's distinct increment whenever the two counters happen to coincide. Instead, add only the reads this process genuinely made since its own load (b.readCount minus its baseline at hydration time) on top of the freshest disk count, so two processes that each record one real read from the same starting point sum to two instead of collapsing to one.
const baseline = filesReadCountAtLoad().get(b.path) ?? 0
const newReadsThisProcess = Math.max(0, b.readCount - baseline)
let merged: FileEntry = {
path: a.path,
readCount: a.readCount + newReadsThisProcess,
lastReadAt: Math.max(a.lastReadAt, b.lastReadAt),
wasEdited: a.wasEdited || b.wasEdited,
sizeBytes: newest.sizeBytes,
}
if (newest.rangeFileIdentity) merged = { ...merged, rangeFileIdentity: newest.rangeFileIdentity }
if (a.wasTruncated || b.wasTruncated) merged = { ...merged, wasTruncated: true }
const lastFullReadAt = Math.max(a.lastFullReadAt ?? 0, b.lastFullReadAt ?? 0)
if (lastFullReadAt > 0) merged = { ...merged, lastFullReadAt }
// fullReadCount is reconciled the same way readCount is above, not maxed, for the same reason: Math.max would drop a concurrent process's own genuine full read whenever the two counters happen to coincide.
const fullReadBaseline = filesFullReadCountAtLoad().get(b.path) ?? 0
const newFullReadsThisProcess = Math.max(0, (b.fullReadCount ?? 0) - fullReadBaseline)
const fullReadCount = (a.fullReadCount ?? 0) + newFullReadsThisProcess
if (fullReadCount > 0) merged = { ...merged, fullReadCount }
const lastEditedAt = Math.max(a.lastEditedAt ?? 0, b.lastEditedAt ?? 0)
if (lastEditedAt > 0) merged = { ...merged, lastEditedAt }
const epochBase = mergeEpochBase(a.epochBase, b.epochBase)
if (epochBase !== undefined) merged = { ...merged, epochBase }
// Union the surgical-read tokens from both views so a concurrent process's symbol reads are not clobbered by whichever save lands last.
const symbols = Array.from(new Set([...(a.symbols_read ?? []), ...(b.symbols_read ?? [])]))
if (symbols.length > 0) merged = { ...merged, symbols_read: symbols }
return merged
}
/** "mem overlays disk" merge: the current process's view is at least as fresh. Shared by every pure-append/overwrite disk/mem pair-list field with no removal path (webFetches, bashOutputs, grepQueries, globQueries). curlDownloads has one (clearCurlDownload) and uses {@link mergeCurlDownloads} instead so a clearing deletion actually sticks. */
function mergePairs<V>(disk: Array<[string, V]>, mem: Array<[string, V]>): Array<[string, V]> {
return Array.from(new Map([...disk, ...mem]).entries())
}
/** Merge monotonically increasing counters so stale hook processes cannot lower an occurrence. */
function mergeMaxNumberPairs(disk: Array<[string, number]>, mem: Array<[string, number]>): Array<[string, number]> {
const merged = new Map(disk)
for (const [key, value] of mem) {
merged.set(key, Math.max(merged.get(key) ?? 0, value))
}
return Array.from(merged.entries())
}
/** Merge two views of the per-file served line ranges: union per file, dedup identical ranges, cap per file. The cap never evicts a range already on disk (another process's confirmed, persisted work) — once a file is at the cap, a fresh range from this process's own in-memory view is simply not added rather than displacing a disk-persisted entry. */
function mergeLineRanges(disk: Array<[string, Array<[number, number]>]>, mem: Array<[string, Array<[number, number]>]>): Array<[string, Array<[number, number]>]> {
const byPath = new Map<string, Array<[number, number]>>()
for (const [filePath, ranges] of disk) byPath.set(filePath, [...ranges])
for (const [filePath, ranges] of mem) {
const prev = byPath.get(filePath) ?? []
const seen = new Set(prev.map(([s, e]) => s + ':' + e))
for (const [s, e] of ranges) {
const key = s + ':' + e
if (seen.has(key) || prev.length >= MAX_RANGES_PER_FILE) continue
prev.push([s, e])
seen.add(key)
}
byPath.set(filePath, prev)
}
return Array.from(byPath.entries())
}
// The generic served-output key as it appears in a serialized map, i.e. already folded the same way recordFileServedOutput folds it -- computed once so the merge below does not refold it on every entry.
const GENERIC_SERVED_OUTPUT_FOLDED_KEY = foldPath(normalizePath(GENERIC_SERVED_OUTPUT_KEY))
/** Merge served-output indexes: union per path, newest-last, capped. Unlike {@link mergeLineRanges} the cap keeps the NEWEST ids rather than refusing new ones at the cap, because a later body is the more likely container of the next read and a stale id only costs a failed containment check. The session-wide generic key uses its own, larger cap: see {@link MAX_GENERIC_SERVED_OUTPUTS}. */
function mergeServedOutputs(disk: Array<[string, string[]]>, mem: Array<[string, string[]]>): Array<[string, string[]]> {
const byPath = new Map<string, string[]>()
for (const [filePath, ids] of disk) byPath.set(filePath, [...ids])
for (const [filePath, ids] of mem) {
const prev = byPath.get(filePath) ?? []
const merged = [...prev.filter((id) => !ids.includes(id)), ...ids]
const cap = filePath === GENERIC_SERVED_OUTPUT_FOLDED_KEY ? MAX_GENERIC_SERVED_OUTPUTS : MAX_SERVED_OUTPUTS_PER_FILE
if (merged.length > cap) merged.splice(0, merged.length - cap)
byPath.set(filePath, merged)
}
return Array.from(byPath.entries())
}
/** Merge pending large-file hints: union disk with mem, but drop any key this process explicitly consumed (took an outcome for) even if a stale disk read still has it — the other merged fields are monotonic sets where union is always correct, but this one is a pending-to-consumed lifecycle where a deletion must actually stick. The overlay only re-asserts keys this process actually acted on this run: brand-new keys it added, or keys whose value it changed. A key it merely carried unchanged from hydration (same key, same size as `pendingLargeFileHintsAtLoad`) is left alone and instead defers to whatever the freshest disk read says — otherwise a process that loaded a key but never touched it would resurrect that key on every save, even after a *different* concurrent process legitimately consumed and removed it from disk in the meantime. */
function mergePendingLargeFileHints(
disk: Array<[string, number]>,
mem: Array<[string, number]>,
): Array<[string, number]> {
const merged = new Map(disk)
for (const key of consumedPendingLargeFileHintKeys()) merged.delete(key)
const atLoad = pendingLargeFileHintsAtLoad()
for (const [key, size] of mem) {
if (atLoad.get(key) === size) continue
merged.set(key, size)
}
return Array.from(merged.entries())
}
/** Merge two views of curl -o download records: union disk with mem, but drop any URL this process explicitly cleared (see {@link consumedCurlDownloadKeys}) even if a stale disk read still has it -- like mergePendingLargeFileHints, this is NOT a plain set-union field, because clearCurlDownload's removal must actually stick. The overlay only re-asserts URLs this process actually acted on this run: brand-new URLs it recorded, or URLs whose saved path it changed. A URL merely carried unchanged from hydration (same URL, same path as `curlDownloadsAtLoad`) is left alone and instead defers to whatever the freshest disk read says -- otherwise a process that loaded a URL but never touched it would resurrect that URL on every save, even after a *different* concurrent process legitimately cleared it from disk in the meantime. */
function mergeCurlDownloads(
disk: Array<[string, string]>,
mem: Array<[string, string]>,
): Array<[string, string]> {
const merged = new Map(disk)
for (const key of consumedCurlDownloadKeys()) merged.delete(key)
const atLoad = curlDownloadsAtLoad()
for (const [url, savedPath] of mem) {
if (atLoad.get(url) === savedPath) continue
merged.set(url, savedPath)
}
return Array.from(merged.entries())
}
/** Merge two views of Bash start directories the way {@link mergeCurlDownloads} merges downloads, so a post hook's take sticks against a stale disk read and an entry merely carried from load defers to disk, then keep the newest {@link MAX_BASH_START_CWDS}. */
function mergeBashStartCwds(disk: Array<[string, string]>, mem: Array<[string, string]>): Array<[string, string]> {
const merged = new Map(disk)
for (const key of consumedBashStartCwdKeys()) merged.delete(key)
const atLoad = bashStartCwdsAtLoad()
for (const [toolUseId, cwd] of mem) {
if (atLoad.get(toolUseId) === cwd) continue
merged.set(toolUseId, cwd)
}
const entries = Array.from(merged.entries())
return entries.length > MAX_BASH_START_CWDS ? entries.slice(entries.length - MAX_BASH_START_CWDS) : entries
}
/** Merge two views of outstanding Agent-spawn prompts. Like mergePendingLargeFileHints below, this is NOT a plain set-union: removal (the post-hook clearing a completed spawn) must actually stick, so a plain disk-union would silently resurrect an entry this process just removed from the pre-update disk snapshot. Start from disk, drop anything this process explicitly removed (see consumedOutstandingAgentSpawnKeys), then overlay only the entries this process newly added (present in mem but not in its own load-time snapshot) -- an entry merely carried over unchanged defers to disk. Finally cap to MAX_OUTSTANDING_AGENT_SPAWNS, dropping the oldest entries first, same oldest-evicted shape as recordOutstandingAgentSpawn's own local cap. */
function mergeOutstandingAgentSpawns(
disk: Array<[string, number]>,
mem: Array<[string, number]>,
): Array<[string, number]> {
const merged = new Map(disk.map(([prompt, ts]) => [outstandingAgentSpawnKey(prompt, ts), [prompt, ts] as [string, number]]))
for (const key of consumedOutstandingAgentSpawnKeys()) merged.delete(key)
const atLoad = new Set(outstandingAgentSpawnsAtLoad().map((e) => outstandingAgentSpawnKey(e.prompt, e.ts)))
for (const [prompt, ts] of mem) {
const key = outstandingAgentSpawnKey(prompt, ts)
if (atLoad.has(key)) continue
merged.set(key, [prompt, ts])
}
const result = Array.from(merged.values()).sort((a, b) => a[1] - b[1])
if (result.length > MAX_OUTSTANDING_AGENT_SPAWNS) {
result.splice(0, result.length - MAX_OUTSTANDING_AGENT_SPAWNS)
}
return result
}
/** Merge the on-disk snapshot with the in-memory one (see module invariants). */
function mergeSessionState(disk: SerializedSession, mem: SerializedSession): SerializedSession {
const byPath = new Map<string, FileEntry>()
for (const e of disk.files) byPath.set(foldPath(e.path), e)
for (const e of mem.files) {
const key = foldPath(e.path)
const prev = byPath.get(key)
byPath.set(key, prev ? mergeFileEntry(prev, e) : e)
}
// Compaction epoch is max-wins: it only ever moves forward, so whichever side saw the most recent compaction is authoritative and a concurrent process that predates the stamp can never roll it back. This is exactly why session.ts records an epoch instead of resetting each entry's readCount -- a readCount reset merges to a no-op here (see mergeFileEntry), a max-merged scalar does not.
const compactedAt = Math.max(disk.compactedAt ?? 0, mem.compactedAt ?? 0)
// Sed line ranges carry no timestamp of their own, so they cannot be filtered per-range against the epoch the way FileEntry.lastReadAt can. Instead drop the ranges of any side that had not yet observed the winning epoch: they were recorded by a process whose view predates the compaction, so they may describe content the model no longer holds. Erring toward dropping only costs a full read that was already going to be correct; keeping them would keep serving "you already saw lines N-M" against invisible content.
const rawDiskRanges = (disk.compactedAt ?? 0) === compactedAt ? (disk.fileLineRanges ?? []) : []
const memRanges = (mem.compactedAt ?? 0) === compactedAt ? (mem.fileLineRanges ?? []) : []
// Same epoch filter, same reason: a served body recorded before the winning compaction may no longer be in the model's context, so it must not justify withholding a later read of that file.
const rawDiskServed = (disk.compactedAt ?? 0) === compactedAt ? (disk.fileServedOutputs ?? []) : []
const memServed = (mem.compactedAt ?? 0) === compactedAt ? (mem.fileServedOutputs ?? []) : []
const rawDiskCliReads = (disk.compactedAt ?? 0) === compactedAt ? (disk.cliReads ?? []) : []
const memCliReads = (mem.compactedAt ?? 0) === compactedAt ? (mem.cliReads ?? []) : []
// One verification run per command, the later of the two when both processes saw it, oldest first and capped at MAX_VERIFICATION_RUNS; empty is omitted from the blob like the other optional lists.
const latestRuns = new Map<string, VerificationRun>()
for (const run of [...(disk.verificationRuns ?? []), ...(mem.verificationRuns ?? [])]) {
const seen = latestRuns.get(run.command)
if (seen === undefined || run.at >= seen.at) latestRuns.set(run.command, run)
}
const verificationRuns = Array.from(latestRuns.values()).sort((a, b) => a.at - b.at).slice(-MAX_VERIFICATION_RUNS)
// recordFileEdit clears a single file's line-range history in-memory (an edit moves the numbers those ranges are matched on; the served-output ids are matched on bytes instead and survive), but that per-file deletion carries no epoch of its own, so the compaction filter above cannot see it -- an unrelated disk read from before the edit would otherwise resurrect the exact entry this process just cleared. Drop those files from the disk side before the union so the clearing actually sticks.
const clearedRangeFiles = new Set(consumedFileLineRangeKeys())
const clearedServedFiles = new Set(consumedFileServedOutputKeys())
const diskRanges = rawDiskRanges.filter(([path]) => !clearedRangeFiles.has(path))
const diskServed = rawDiskServed.filter(([path]) => !clearedServedFiles.has(path))
const fileLineRanges = mergeLineRanges(diskRanges, memRanges)
const diskRangeEvasion = (disk.compactedAt ?? 0) === compactedAt ? (disk.readRangeEvasion ?? []) : []
const memRangeEvasion = (mem.compactedAt ?? 0) === compactedAt ? (mem.readRangeEvasion ?? []) : []
// A file's range identity goes and comes with its ranges: the same epoch filter and cleared-file tombstones, this process's stamp over disk's, and none kept for a file left without ranges.
const rangedFiles = new Set(fileLineRanges.map(([path]) => path))
const rawDiskIdentities = (disk.compactedAt ?? 0) === compactedAt ? (disk.fileLineRangeIdentities ?? []) : []
const memIdentities = (mem.compactedAt ?? 0) === compactedAt ? (mem.fileLineRangeIdentities ?? []) : []
const fileLineRangeIdentities = mergePairs(rawDiskIdentities.filter(([path]) => !clearedRangeFiles.has(path)), memIdentities).filter(([path]) => rangedFiles.has(path))
return {
files: Array.from(byPath.values()),
hintsShown: Array.from(new Set([...disk.hintsShown, ...mem.hintsShown])),
scheduledPromptCounts: mergeMaxNumberPairs(disk.scheduledPromptCounts ?? [], mem.scheduledPromptCounts ?? []),
webFetches: mergePairs(disk.webFetches, mem.webFetches),
bashOutputs: mergePairs(disk.bashOutputs, mem.bashOutputs),
curlDownloads: mergeCurlDownloads(disk.curlDownloads, mem.curlDownloads),
fileLineRanges,
readRangeEvasion: mergeReadRangeEvasion(diskRangeEvasion, memRangeEvasion),
...(fileLineRangeIdentities.length > 0 ? { fileLineRangeIdentities } : {}),
fileServedOutputs: mergeServedOutputs(diskServed, memServed),
...(compactedAt > 0 ? { compactedAt } : {}),
// Same epoch filter as the line ranges above: a CLI read recorded before the winning compaction is not in the model's context any more, so merging it back would resurrect the "you already ran this" note the compaction just cleared.
cliReads: Array.from(new Set([...(rawDiskCliReads), ...(memCliReads)])),
bashReruns: Array.from(new Set([...(disk.bashReruns ?? []), ...(mem.bashReruns ?? [])])),
pendingLargeFileHints: mergePendingLargeFileHints(disk.pendingLargeFileHints ?? [], mem.pendingLargeFileHints ?? []),
bashStartCwds: mergeBashStartCwds(disk.bashStartCwds ?? [], mem.bashStartCwds ?? []),
grepQueries: mergePairs(disk.grepQueries ?? [], mem.grepQueries ?? []),
globQueries: mergePairs(disk.globQueries ?? [], mem.globQueries ?? []),
outstandingAgentSpawns: mergeOutstandingAgentSpawns(disk.outstandingAgentSpawns ?? [], mem.outstandingAgentSpawns ?? []),
// An accumulating collection, so union rather than pick a winner: two hook processes can each see a screenshot the other never did. Disk first, then mem, so the order stays oldest-to-newest and the cap evicts the oldest -- the same policy recordSeenImage applies in memory, applied again here because a union of two capped lists can exceed the cap.
seenImageHashes: mergeSeenImageHashes(disk.seenImageHashes ?? [], mem.seenImageHashes ?? []),
...(verificationRuns.length > 0 ? { verificationRuns } : {}),
// Last-seen scalar, not an accumulating collection: prefer mem's value (this process's freshest observation) over disk's, since a newer write always supersedes an older one.
...(mem.lastTabContextDigest !== undefined
? { lastTabContextDigest: mem.lastTabContextDigest }
: disk.lastTabContextDigest !== undefined
? { lastTabContextDigest: disk.lastTabContextDigest }
: {}),
// Prefer the value already on disk: it marks the original creation time, and must never be bumped forward to the merge's "now". `mem` never carries one (it is not tracked in memory), so this is really "keep whatever disk has".
...(disk.created_ts !== undefined
? { created_ts: disk.created_ts }
: mem.created_ts !== undefined
? { created_ts: mem.created_ts }
: {}),
}
}
/** Union two screenshot-fingerprint lists oldest-first, keeping at most MAX_SEEN_IMAGE_HASHES. */
function mergeSeenImageHashes(disk: string[], mem: string[]): string[] {
const merged = Array.from(new Set([...disk, ...mem]))
return merged.length > MAX_SEEN_IMAGE_HASHES ? merged.slice(merged.length - MAX_SEEN_IMAGE_HASHES) : merged
}
/** Drop all but the `max` most relevant file entries: edited ones first, then most-recently-read. Ranking on `lastReadAt` alone evicted exactly the entries worth keeping. `recordFileEdit` stores a new entry with `lastReadAt: 0` -- correctly, since an edit is not a read and a fabricated read timestamp would let the dedup path claim the model has seen content it never received -- so a file this session edited and never read sorted below every file it read once, and at the cap it went first. Those entries are what `selectManifestFiles` and the resume packet's edited-files list are built from, which makes them the most expensive ones to lose. The edit flag carries that priority instead of a timestamp, so nothing has to invent a read that did not happen. */
function capFiles(s: SerializedSession, max: number): SerializedSession {
if (s.files.length <= max) return s
const kept = [...s.files]
.sort((a, b) => (a.wasEdited === b.wasEdited ? b.lastReadAt - a.lastReadAt : a.wasEdited ? -1 : 1))
.slice(0, max)
return { ...s, files: kept }
}
/** Read the on-disk JSON for `sessionPath`, coerced; null on miss/corrupt. */
function readDiskState(p: string): SerializedSession | null {
try {
return readDiskStateForMerge(p)
} catch {
return null
}
}
/** {@link readDiskState} for a caller about to write what it merges: null when there is no file or it is corrupt, but a file that exists and cannot be read throws, after a brief lock is retried. Answering null there made saveSessionState write one hook's view over a cache a scanner was holding, and every file earlier hooks recorded for the session was forgotten. */
function readDiskStateForMerge(p: string): SerializedSession | null {
let text = ''
try {
withRetryOnLock(() => {
text = fs.readFileSync(p, 'utf8')
})
} catch (err) {
if ((err as { code?: unknown }).code === 'ENOENT') return null
throw err
}
try {
return coerce(JSON.parse(text))
} catch {
return null
}
}
/** Read and coerce the on-disk session state for `sessionId` without touching in-memory session state (unlike {@link loadSessionState}, which imports the result into the live session maps for the hook lifecycle). Handles both the current TS array `files` format and the legacy Python dict format via the same {@link coerce} normalization `loadSessionState`/`saveSessionState` rely on. Returns null if the id is empty/unusable or no file exists. */
export function readSessionStateFile(sessionId: string): SerializedSession | null {
const p = sessionPath(sessionId)
if (!p) return null
return readDiskState(p)
}
/** Read every sibling subagent session-state blob for `sessionId` (i.e. every on-disk file salted with `${sessionId}:agent:${agentId}` per relay.ts's `sessionStateKey`), without touching in-memory session state. `sessionPath` sanitizes and truncates the *whole* salted key to 64 chars, so a sibling's filename is `${sanitize(sessionId)}_agent_<agentId prefix>` possibly truncated mid-agentId — but the `${sanitize(sessionId)}_agent_` prefix itself (well under 64 chars for realistic session ids) always survives intact, which is what this scan matches on. Returns [] when the id is empty/unusable, the sessions dir doesn't exist, or on any read error (fail-soft, mirroring every other read in this module). */
export function listSiblingSessionStates(sessionId: string): SerializedSession[] {
if (!sessionId) return []
// Built by the same helper the writer uses, so the two can never disagree about how much of the session id survived the 64-char cap. This used to sanitize the id with NO length limit and match `startsWith` against filenames that had been capped at 64, so once the id reached 58 sanitized characters no filename could possibly start with the prefix and the scan silently returned nothing -- indistinguishable from "no subagents ran". The pre_compact manifest, whose whole purpose is to carry session context across a compaction, reported "Files read: 0" while real work had been done.
const prefix = saltedStemPrefix(sessionId)
// An id that sanitizes to nothing leaves the bare marker, which would match every salted blob on disk regardless of which session wrote it.
if (prefix === AGENT_SALT_MARKER) return []
const dir = sessionsDir()
const out: SerializedSession[] = []
try {
if (!fs.existsSync(dir)) return out
for (const file of fs.readdirSync(dir)) {
if (!file.endsWith('.json') || !file.startsWith(prefix)) continue
const state = readDiskState(path.join(dir, file))
if (state !== null) out.push(state)
}
} catch {
return out
}
return out
}
/** What a session with nothing on disk starts from. */
const EMPTY_SESSION: SerializedSession = { files: [], hintsShown: [], webFetches: [], bashOutputs: [], curlDownloads: [] }
/** Load the persisted state for `sessionId` into the in-memory session maps. A clean session when no file exists or the id is empty/unusable, never the previous one's: the pi, opencode and OpenClaw bridges call relayInProcess inside their long-lived host process, which serves one session after another (pi re-fires session_start with a new id on new, resume and fork). Fail-soft: a corrupt file leaves the session empty rather than throwing. */
export function loadSessionState(sessionId: string): void {
const p = sessionPath(sessionId)
importSessionState((p ? readDiskState(p) : null) ?? EMPTY_SESSION)
applySessionCompaction(sessionId)
}
/** Sidecar holding the epoch of the latest compaction of a session, written by PreCompact whatever agent it carries. */
export const COMPACTED_AT_SUFFIX = '.compacted-at'
/** A subagent's state is keyed `<sid>:agent:<id>` but its PreCompact arrives without an `agent_id`, so the epoch is stamped on the parent's state, never its own. Reading the few-byte sidecar the stamp also writes brings the subagent's served-lines, line-range, CLI-read and repeat-deny state up to that compaction without parsing the parent's state file. The main session reads it too: its own PreCompact save is skipped when another process holds the session lock past saveSessionState's budget, and the sidecar, written outside that lock, is then the only place the epoch survives, so without it every read before the compaction would count as still in context. */
function applySessionCompaction(stateKey: string): void {
const at = stateKey.indexOf(':agent:')
const p = sessionSidecarPath(at < 0 ? stateKey : stateKey.slice(0, at), COMPACTED_AT_SUFFIX)
if (!p) return
try {
const epoch = Number(fs.readFileSync(p, 'utf8').trim())
if (Number.isFinite(epoch) && epoch > 0) markCompacted(epoch)
} catch {
// fail-soft: no sidecar means no compaction has been recorded for this session
}
}
/** How long saveSessionState waits behind another process's session-file lock, in milliseconds. A holder keeps it for one read-merge-write of a small JSON file, so contention that resolves does so well inside this; a holder that has outlived it is wedged, and waiting longer only charges the agent 15 s per tool call (measured 15.6-18.4 s per Read behind a live holder). */
const SESSION_SAVE_LOCK_WAIT_MS = 500
/** Persist the in-memory session state for `sessionId`, merged with whatever is already on disk (so a concurrent same-session hook process is not clobbered). No-op when the id is empty/unusable. Fail-soft: a disk error is swallowed, and a cache that exists but cannot be read is left as it is rather than written over. */
export function saveSessionState(sessionId: string): void {
const p = sessionPath(sessionId)
if (!p) return
try {
ensureSessionDirectory(sessionId)
const mem = exportSessionState()
// saveSessionState is the actual race: every hook call is a fresh OS process, and two concurrent processes for the same session can each read the pre-update disk state, merge it with their own view, and write -- whichever write lands last silently clobbers the other's update, with no error. A short-lived lockfile around just this read-merge-write section serializes concurrent savers, so each one's disk read reflects every write that already landed.
const writeMerged = (): true => {
const disk = readDiskStateForMerge(p)
const merged = capFiles(disk ? mergeSessionState(disk, mem) : mem, MAX_FILES)
// Stamp the cache's creation time exactly once, on the first write that produces no inherited value (disk had none and mem carries none). Every later write inherits it via readDiskStateForMerge -> coerce -> mergeSessionState, so it represents creation, not last-modification. Unit: seconds, matching compact.ts's `Date.now() / 1000 - created_ts` age computation.
if (merged.created_ts === undefined) merged.created_ts = Date.now() / 1000
// Defense-in-depth backstop, not the primary control: individual fields (e.g. recordOutstandingAgentSpawn in session.ts) redact at their own write sites, but CLAUDE.arch.md documents that this file is the one place a *new* SerializedSession field does not automatically inherit redaction -- relying on every future field's author to remember a redactSecrets() call is exactly the gap that shipped outstandingAgentSpawns unredacted. Sweeping the fully-serialized JSON here, at the sole place this state ever reaches disk, means a future field is covered whether or not its author remembered. Fail-safe like storeBlob(): if redaction itself throws, skip this write rather than risk persisting unredacted content -- the next successful save still merges from disk.
let json: string
try {
json = redactSerializedJson(JSON.stringify(merged)).text
} catch {
return true
}
atomicWriteText(p, json)
return true
}
// Two concurrent hook processes for the same session_id contend on this lock for their entire lifetime (every save re-acquires it), and a saver that writes without it can clobber the other's update with no error.
let heldByAnother = false
// A hook is the agent's tool call, so it waits SESSION_SAVE_LOCK_WAIT_MS and no longer. A lock still held after that skips this save: the next call's save merges from disk, whereas an unlocked write is the clobber the lock exists to prevent.
if (withFileLock(`${p}.lock`, writeMerged, { waitMs: SESSION_SAVE_LOCK_WAIT_MS, onContended: () => { heldByAnother = true } }) === undefined && !heldByAnother) writeMerged()
} catch {
// fail-soft: never let persistence break a hook
}
}
const MAX_SHARED_SESSION_ID_CHARS = 4096
const MAX_SHARED_SESSION_KEY_CHARS = 256
const MAX_SHARED_SESSION_VALUE_CHARS = 32_000
const MAX_SHARED_SESSION_LIST_LIMIT = 500
export interface SharedSessionValue {
key: string
value: string
updatedAt: string
}
export interface SharedSessionValueListOptions {
prefix?: string
limit?: number
}
interface SharedSessionValueRow {
key_display: string
value: string
updated_at: string
}
function sharedSessionScope(sessionId: string): string {
if (typeof sessionId !== 'string' || sessionId.length === 0 || sessionId.length > MAX_SHARED_SESSION_ID_CHARS || sessionId.includes('\0')) {
throw new Error(`sessionId must be a non-empty string of at most ${MAX_SHARED_SESSION_ID_CHARS} characters`)
}
const separator = sessionId.indexOf(AGENT_SALT_SEPARATOR)
const scope = separator < 0 ? sessionId : sessionId.slice(0, separator)
if (scope.trim().length === 0) throw new Error('sessionId must have a non-empty parent session id')
return scope
}
function sharedSessionKey(key: string): string {
if (typeof key !== 'string' || key.trim().length === 0 || key.length > MAX_SHARED_SESSION_KEY_CHARS || key.includes('\0')) {
throw new Error(`key must be a non-empty string of at most ${MAX_SHARED_SESSION_KEY_CHARS} characters`)
}
return key.trim()
}
function sharedSessionValue(value: string): string {
if (typeof value !== 'string' || value.includes('\0')) throw new Error('value must be a string without NUL characters')
const safeValue = redactSharedMemoryText(value)
if (safeValue.length > MAX_SHARED_SESSION_VALUE_CHARS) {
throw new Error(`value must be at most ${MAX_SHARED_SESSION_VALUE_CHARS} characters after redaction`)
}
return safeValue
}
function sharedSessionLimit(limit: number | undefined): number {
const resolved = limit ?? 100
if (!Number.isInteger(resolved) || resolved < 1 || resolved > MAX_SHARED_SESSION_LIST_LIMIT) {
throw new Error(`limit must be an integer from 1 to ${MAX_SHARED_SESSION_LIST_LIMIT}`)
}
return resolved
}
function sharedSessionPrefix(prefix: string | undefined): string | undefined {
if (prefix === undefined) return undefined
if (typeof prefix !== 'string') throw new Error('prefix must be a string')
if (prefix.trim().length === 0) return undefined
return redactSharedMemoryText(sharedSessionKey(prefix))
}
function sharedSessionRow(row: SharedSessionValueRow): SharedSessionValue {
return { key: row.key_display, value: row.value, updatedAt: row.updated_at }
}
/** Store a redacted value shared by the parent session and all of its agent-salted children. */
export function setSharedSessionValue(sessionId: string, key: string, value: string): SharedSessionValue {
const scopeHash = sharedMemoryDigest(sharedSessionScope(sessionId))
const normalizedKey = sharedSessionKey(key)
const keyHash = sharedMemoryDigest(normalizedKey)
const safeKey = redactSharedMemoryText(normalizedKey)
const safeValue = sharedSessionValue(value)
const updatedAt = new Date().toISOString()
getSharedMemoryDb().prepare(`
INSERT INTO shared_session_values (session_hash, key_hash, key_display, value, updated_at)
VALUES (?, ?, ?, ?, ?)
ON CONFLICT (session_hash, key_hash) DO UPDATE SET
key_display = excluded.key_display,
value = excluded.value,
updated_at = excluded.updated_at
`).run(scopeHash, keyHash, safeKey, safeValue, updatedAt)
return { key: safeKey, value: safeValue, updatedAt }
}
/** Look up a shared session value by its original key; returns null when absent. */
export function getSharedSessionValue(sessionId: string, key: string): SharedSessionValue | null {
const scopeHash = sharedMemoryDigest(sharedSessionScope(sessionId))
const keyHash = sharedMemoryDigest(sharedSessionKey(key))
const row = getSharedMemoryDb().prepare(`
SELECT key_display, value, updated_at
FROM shared_session_values
WHERE session_hash = ? AND key_hash = ?
`).get(scopeHash, keyHash) as SharedSessionValueRow | undefined
return row === undefined ? null : sharedSessionRow(row)
}
/** List the most recently updated shared values, optionally filtered by a safe key prefix. */
export function listSharedSessionValues(sessionId: string, options: SharedSessionValueListOptions = {}): SharedSessionValue[] {
const scopeHash = sharedMemoryDigest(sharedSessionScope(sessionId))
const limit = sharedSessionLimit(options.limit)
const prefix = sharedSessionPrefix(options.prefix)
const db = getSharedMemoryDb()
const rows = prefix === undefined
? db.prepare(`
SELECT key_hash, key_display, value, updated_at
FROM shared_session_values
WHERE session_hash = ?
ORDER BY updated_at DESC, key_display COLLATE NOCASE ASC, key_hash ASC
LIMIT ?
`).all(scopeHash, limit) as SharedSessionValueRow[]
: db.prepare(`
SELECT key_hash, key_display, value, updated_at
FROM shared_session_values
WHERE session_hash = ? AND substr(key_display, 1, length(?)) = ?
ORDER BY updated_at DESC, key_display COLLATE NOCASE ASC, key_hash ASC
LIMIT ?
`).all(scopeHash, prefix, prefix, limit) as SharedSessionValueRow[]
return rows.map(sharedSessionRow)
}
/** Delete one shared value by its original key. */
export function deleteSharedSessionValue(sessionId: string, key: string): boolean {
const scopeHash = sharedMemoryDigest(sharedSessionScope(sessionId))
const keyHash = sharedMemoryDigest(sharedSessionKey(key))
return getSharedMemoryDb().prepare(`
DELETE FROM shared_session_values
WHERE session_hash = ? AND key_hash = ?
`).run(scopeHash, keyHash).changes > 0
}
/** Delete every shared value for the parent session and its agent-salted children. */
export function clearSharedSessionValues(sessionId: string): number {
const scopeHash = sharedMemoryDigest(sharedSessionScope(sessionId))
return Number(getSharedMemoryDb().prepare(`
DELETE FROM shared_session_values
WHERE session_hash = ?
`).run(scopeHash).changes)
}