dsh-aiterm 0.5.1 → 0.5.13

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.
@@ -1,11 +1,38 @@
1
1
  /**
2
2
  * On-disk terminal history (CONTRACTS.md §10).
3
3
  *
4
- * Each session gets one NDJSON journal (`<dir>/<sessionId>.ndjson`, one
5
- * `{"t":epochMs,"d":"base64"}` record per output chunk) plus one shared
6
- * `index.json` catalog. Appends are buffered in memory and flushed on a timer
7
- * or when the buffer grows past 64 KiB, so a chatty remote cannot turn terminal
8
- * output into one filesystem call per packet.
4
+ * Every call to {@link HistoryStore#openSession} reserves a **new** journal
5
+ * file with an exclusive create (`wx`) instead of appending to a file named
6
+ * after the logical session id:
7
+ *
8
+ * <dir>/<safe session id>~<random uuid>.ndjson
9
+ *
10
+ * Session ids are stable only inside one registry lifetime (`st-1` starts over
11
+ * after a plugin reload), so a name keyed by the id alone let a new session
12
+ * append its output to an older session's journal. The incarnation suffix is
13
+ * reserved atomically by the filesystem: two overlapping plugin instances, a
14
+ * reloaded instance and a still-pending flusher from the old instance all get
15
+ * different files, and no old journal is ever reopened for append.
16
+ *
17
+ * The journal itself carries its provenance as private NDJSON metadata lines:
18
+ *
19
+ * {"_aiterm":"journal","version":1,"id":"st-1","owner":"<dsh session id>",...}
20
+ * {"_aiterm":"close","version":1,"closedAt":...,"aiAccess":"wo",...}
21
+ *
22
+ * Owner and the AI permission at close time therefore survive a restart, a
23
+ * lost/corrupt `index.json`, and a last-writer-wins catalog race between two
24
+ * stores. A journal without a valid header, or a closed journal without valid
25
+ * close permission, is *unattributed* and fails closed for AI reads/exports.
26
+ *
27
+ * `index.json` is kept for one purpose only: describing **legacy** journals
28
+ * written by older versions, which have no provenance. Those files are never
29
+ * rewritten, never deleted by retention, and are never assigned an owner. The
30
+ * human legacy (no-owner) bucket can still read catalogued legacy history;
31
+ * AI reads and any named-owner read fail closed.
32
+ *
33
+ * Appends are buffered in memory and flushed on a timer or when the buffer
34
+ * grows past 64 KiB, so a chatty remote cannot turn terminal output into one
35
+ * filesystem call per packet.
9
36
  *
10
37
  * The store is a convenience layer, never a dependency: every disk error is
11
38
  * logged and swallowed. A full disk or a read-only home directory must not break
@@ -15,15 +42,14 @@
15
42
  * caller creates it through `init()`.
16
43
  */
17
44
 
18
- import { appendFile, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
45
+ import { createHash, randomUUID } from 'node:crypto'
46
+ import { appendFile, open, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises'
19
47
  import { join } from 'node:path'
20
48
 
21
- import { boundInteger, ensureDir, readJsonIfPresent, writeJsonAtomic } from './util.js'
49
+ import { boundInteger, ensureDir, readJsonIfPresent } from './util.js'
22
50
 
23
- /** Catalog file name inside the history directory. */
51
+ /** Legacy catalog file name inside the history directory (read-only here). */
24
52
  const INDEX_FILE = 'index.json'
25
- /** Catalog format version written by this store. */
26
- const CATALOG_VERSION = 1
27
53
  /** Default retention window: 24 hours. */
28
54
  const DEFAULT_RETENTION_MS = 24 * 60 * 60 * 1000
29
55
  /** Default journal cap per session: 8 MiB. */
@@ -40,6 +66,28 @@ const DEFAULT_QUERY_MAX_BYTES = 8 * 1024 * 1024
40
66
  const DEFAULT_MAX_MATCHES = 100
41
67
  /** Sessions' worth of pre-open output buffered to cover the open/append race. */
42
68
  const MAX_ORPHAN_SESSIONS = 32
69
+ /** Journal metadata marker discriminator. */
70
+ const META_MARKER = '_aiterm'
71
+ /** Journal metadata format version. */
72
+ const META_VERSION = 1
73
+ /** `open(..., 'wx')` collisions retried before giving up. */
74
+ const MAX_RESERVE_ATTEMPTS = 8
75
+ /** Largest journal header line accepted. */
76
+ const MAX_HEADER_BYTES = 16 * 1024
77
+ /** Bytes read from a journal tail when hydrating bookmarkkeeping fields. */
78
+ const TAIL_READ_BYTES = 64 * 1024
79
+ /** Separate an incarnation suffix from the safe session id. */
80
+ const INCARNATION_SEPARATOR = '~'
81
+ /** Directory holding one empty reservation file per allocated `st-N` id. */
82
+ const IDS_DIR = '.ids'
83
+ /** Minimum interval between opportunistic history-directory rescans. */
84
+ const SCAN_COOLDOWN_MS = 1000
85
+ /** Hard cap on one id-allocation walk (collisions should never reach this). */
86
+ const MAX_ID_ATTEMPTS = 100_000
87
+ /** Default bound for one session's unsaved buffered output. */
88
+ const DEFAULT_MAX_PENDING_BYTES = 1024 * 1024
89
+ /** Minimum delay between repeated write-failure/drop warnings. */
90
+ const FAILURE_LOG_INTERVAL_MS = 60_000
43
91
 
44
92
  /**
45
93
  * @typedef {object} CatalogEntry
@@ -56,6 +104,31 @@ const MAX_ORPHAN_SESSIONS = 32
56
104
  * @property {number} lastTs timestamp of the newest output record.
57
105
  */
58
106
 
107
+ /**
108
+ * Private provenance record for one journal incarnation. The owner, close
109
+ * permission and journal path are deliberately absent from the public
110
+ * `CatalogEntry` shape and from every tool result.
111
+ *
112
+ * @typedef {object} Recording
113
+ * @property {string} id logical session id.
114
+ * @property {string} historyId stable opaque address for this incarnation.
115
+ * @property {string | null} owner owning DSH session id; `null` = ownerless.
116
+ * @property {string} journal absolute journal path.
117
+ * @property {string} title
118
+ * @property {'ssh' | 'telnet'} transport
119
+ * @property {string} host
120
+ * @property {number} port
121
+ * @property {string} username
122
+ * @property {number} createdAt
123
+ * @property {number} [closedAt]
124
+ * @property {'ro' | 'wo' | 'rw'} [aiAccess] AI permission recorded at close.
125
+ * @property {number} [truncatedAt]
126
+ * @property {number} bytes retained output bytes.
127
+ * @property {number} lastTs timestamp of the newest output record.
128
+ * @property {number} [mtime] filesystem modification time (epoch ms).
129
+ * @property {number} fileBytes current journal file size.
130
+ */
131
+
59
132
  /**
60
133
  * @typedef {object} HistoryMatch
61
134
  * @property {number} at epoch ms.
@@ -83,7 +156,7 @@ const MAX_ORPHAN_SESSIONS = 32
83
156
  * @typedef {object} ActiveSession
84
157
  * @property {string} id
85
158
  * @property {string} file absolute journal path.
86
- * @property {CatalogEntry} entry catalog entry (same object as in `catalog`).
159
+ * @property {Recording} entry provenance record (same object as in the map).
87
160
  * @property {PendingRecord[]} pending buffered records not yet written.
88
161
  * @property {number} pendingBytes buffered decoded bytes.
89
162
  * @property {ReturnType<typeof setTimeout> | undefined} timer flush timer.
@@ -92,7 +165,8 @@ const MAX_ORPHAN_SESSIONS = 32
92
165
  */
93
166
 
94
167
  /**
95
- * Per-session journal store with a catalog and retention policy.
168
+ * Per-session journal store with an incarnation journal, provenance metadata
169
+ * and retention policy.
96
170
  */
97
171
  export class HistoryStore {
98
172
  /**
@@ -111,29 +185,60 @@ export class HistoryStore {
111
185
  this.maxBytesPerSession = boundInteger(opts.maxBytesPerSession, DEFAULT_MAX_BYTES_PER_SESSION, 256, 512 * 1024 * 1024)
112
186
  this.maxSessions = boundInteger(opts.maxSessions, DEFAULT_MAX_SESSIONS, 1, 10_000)
113
187
  this.flushIntervalMs = boundInteger(opts.flushIntervalMs, DEFAULT_FLUSH_INTERVAL_MS, 10, 60_000)
188
+ this.maxPendingBytes = boundInteger(opts.maxPendingBytes, DEFAULT_MAX_PENDING_BYTES, 1024, 64 * 1024 * 1024)
114
189
  this.log = typeof opts.log === 'function' ? opts.log : () => {}
115
190
  /** @type {Promise<void> | undefined} */
116
191
  this.ready = undefined
117
- /** @type {Map<string, CatalogEntry>} */
118
- this.catalog = new Map()
192
+ /**
193
+ * Attributed journals by absolute path. Provenance lives here (hydrated from
194
+ * each journal header), never in the shared index.
195
+ * @type {Map<string, Recording>}
196
+ */
197
+ this.recordings = new Map()
198
+ /** @type {Map<string, Recording[]>} */
199
+ this.byId = new Map()
200
+ /** @type {Map<string, Recording>} stable incarnation address -> recording. */
201
+ this.byHistory = new Map()
202
+ /** Every id that must never be handed out again (journals or reservations). */
203
+ this.usedIds = new Set()
204
+ /** @type {number | undefined} next candidate for `st-N` allocation. */
205
+ this.idHint = undefined
206
+ /** Last full directory scan, used to throttle unknown-id lookups. */
207
+ this.lastScanAt = 0
208
+ /** Number of directory scans (diagnostics/tests). */
209
+ this.scanCount = 0
210
+ /**
211
+ * Legacy catalog entries from `index.json`, keyed by id. These files have no
212
+ * provenance; they are exposed only through the explicit human legacy bucket.
213
+ * @type {Map<string, CatalogEntry>}
214
+ */
215
+ this.legacy = new Map()
119
216
  /** @type {Map<string, ActiveSession>} */
120
217
  this.active = new Map()
121
218
  /**
122
219
  * Output that arrived before `openSession()` finished. The registry opens
123
220
  * the journal without awaiting it (a disk hiccup must not delay a connect),
124
221
  * so the first banner bytes can race ahead of the registration; they are
125
- * adopted when the session opens instead of being lost.
222
+ * adopted when the session opens instead of being lost. The key includes the
223
+ * owner so a failed open can never hand one owner's bytes to another.
126
224
  * @type {Map<string, { records: PendingRecord[], bytes: number }>}
127
225
  */
128
226
  this.orphans = new Map()
129
227
  this.disposed = false
130
- /** Serializes catalog writes so two flushes cannot interleave temp files. */
131
- this.indexChain = Promise.resolve()
228
+ this.scanned = false
229
+ /** Async close operations that must finish before `dispose()` resolves. */
230
+ this.operations = new Set()
231
+ /** In-flight reservation/open operations, so a fast close can wait for one. */
232
+ this.openOps = new Set()
233
+ /** Close intents whose metadata append failed, keyed by historyId. */
234
+ this.pendingCloseRecords = new Map()
235
+ this.closeRetryTimer = undefined
236
+ this.closeRetryDelayMs = 0
132
237
  }
133
238
 
134
239
  /**
135
- * Create the directory, load the catalog and apply retention. Idempotent and
136
- * never throws.
240
+ * Create the directory, load legacy metadata and hydrate attributed journals.
241
+ * Idempotent and never throws.
137
242
  * @returns {Promise<void>} completion.
138
243
  */
139
244
  async init() {
@@ -145,82 +250,259 @@ export class HistoryStore {
145
250
  }
146
251
  try {
147
252
  await ensureDir(this.dir)
253
+ await ensureDir(this.idsDirectory).catch(() => {})
148
254
  } catch (error) {
149
255
  this.warn('cannot create history directory', error)
150
256
  }
151
- const index = await readJsonIfPresent(join(this.dir, INDEX_FILE))
152
- const entries = index !== null && typeof index === 'object' && Array.isArray(index.sessions) ? index.sessions : []
153
- for (const raw of entries) {
154
- const entry = normalizeEntry(raw)
155
- if (entry !== undefined) this.catalog.set(entry.id, entry)
156
- }
157
- await this.prune(Date.now())
257
+ await this.loadLegacyCatalog()
258
+ await this.scan()
259
+ await this.pruneRecordings(Date.now())
158
260
  })()
159
261
  return this.ready
160
262
  }
161
263
 
162
264
  /**
163
- * Register (or refresh) a session in the catalog and start buffering output.
164
- * @param {{ id: string, title?: string, transport?: 'ssh' | 'telnet', host?: string, port?: number, username?: string, createdAt?: number }} meta session metadata.
165
- * @returns {Promise<void>} completion.
265
+ * Allocate a globally unique `st-N` id that stays unique across restarts and
266
+ * concurrent Host instances.
267
+ *
268
+ * The directory is scanned only to pick a starting candidate; the reservation
269
+ * file is created with `open(..., 'wx')`, so two processes that race for the
270
+ * same candidate cannot both win. A candidate is also skipped when any
271
+ * journal (legacy or incarnation) already exists for it, because an id whose
272
+ * history predates reservations must keep its address.
273
+ * @returns {Promise<string | undefined>} the allocated id, or undefined when
274
+ * durable allocation is unavailable (the caller must then not open history
275
+ * for the session, so it can never collide with an old journal).
276
+ */
277
+ async allocateSessionId(options = {}) {
278
+ await this.ensureReady()
279
+ if (this.dir.length === 0) return undefined
280
+ const isIdAvailable = typeof options.isIdAvailable === 'function' ? options.isIdAvailable : undefined
281
+ let used
282
+ try {
283
+ used = await this.collectUsedIdsForAllocation()
284
+ } catch (error) {
285
+ this.warn('cannot scan ids for allocation', error)
286
+ return undefined
287
+ }
288
+ this.usedIds = used
289
+ let max = 0
290
+ for (const id of used) {
291
+ const match = /^st-(\d+)$/.exec(id)
292
+ if (match === null) continue
293
+ const value = Number(match[1])
294
+ if (Number.isFinite(value) && value > max) max = value
295
+ }
296
+ // A stale in-memory hint is advanced by the fresh high-water mark; the
297
+ // candidate loop itself does no directory I/O except the atomic wx create.
298
+ this.idHint = Math.max(this.idHint ?? 0, max + 1)
299
+ for (let attempt = 0; attempt < MAX_ID_ATTEMPTS; attempt += 1) {
300
+ const id = `st-${this.idHint}`
301
+ this.idHint += 1
302
+ if (used.has(id)) continue
303
+ if (isIdAvailable !== undefined) {
304
+ let available
305
+ try {
306
+ available = await isIdAvailable(id)
307
+ } catch (error) {
308
+ this.warn(`cannot check id availability for ${id}`, error)
309
+ return undefined
310
+ }
311
+ if (!available) {
312
+ used.add(id)
313
+ continue
314
+ }
315
+ }
316
+ let handle
317
+ try {
318
+ handle = await open(join(this.idsDirectory, id), 'wx', 0o600)
319
+ } catch (error) {
320
+ if (error?.code === 'EEXIST') {
321
+ used.add(id)
322
+ continue
323
+ }
324
+ this.warn(`cannot reserve session id ${id}`, error)
325
+ return undefined
326
+ }
327
+ try {
328
+ await handle.writeFile(`${JSON.stringify({ id, reservedAt: Date.now() })}\n`, 'utf8')
329
+ await handle.sync()
330
+ } catch (error) {
331
+ this.warn(`cannot persist session id reservation ${id}`, error)
332
+ return undefined
333
+ } finally {
334
+ try {
335
+ await handle.close()
336
+ } catch {
337
+ // the reservation exists; a close failure is harmless
338
+ }
339
+ }
340
+ // One final check for an uncoordinated old writer that created a journal
341
+ // after the scan. Non-ENOENT directory errors fail allocation immediately
342
+ // instead of walking 100k candidates.
343
+ let exists
344
+ try {
345
+ exists = await this.journalFileExists(id)
346
+ } catch (error) {
347
+ this.warn('cannot verify the allocated journal id', error)
348
+ return undefined
349
+ }
350
+ if (exists) {
351
+ used.add(id)
352
+ continue
353
+ }
354
+ used.add(id)
355
+ return id
356
+ }
357
+ this.warn('cannot allocate a unique session id')
358
+ return undefined
359
+ }
360
+
361
+ /**
362
+ * One scan to build the occupied-id set used by allocation. Values are taken
363
+ * from journal basenames (incarnation prefix / legacy stem) and `.ids`
364
+ * reservations; headers are not needed for `st-N` allocation.
365
+ * @returns {Promise<Set<string>>} used ids.
366
+ * @private
367
+ */
368
+ async collectUsedIdsForAllocation() {
369
+ const used = new Set(this.usedIds)
370
+ let names
371
+ try {
372
+ names = await readdir(this.dir)
373
+ } catch (error) {
374
+ if (error?.code !== 'ENOENT') throw error
375
+ names = []
376
+ }
377
+ for (const name of names) {
378
+ if (!name.endsWith('.ndjson')) continue
379
+ if (isIncarnationName(name)) {
380
+ const marker = name.indexOf(INCARNATION_SEPARATOR)
381
+ if (marker > 0) used.add(name.slice(0, marker))
382
+ } else {
383
+ used.add(name.slice(0, -'.ndjson'.length))
384
+ }
385
+ }
386
+ let reservations
387
+ try {
388
+ reservations = await readdir(this.idsDirectory)
389
+ } catch (error) {
390
+ if (error?.code !== 'ENOENT') throw error
391
+ reservations = []
392
+ }
393
+ for (const name of reservations) used.add(name)
394
+ return used
395
+ }
396
+
397
+ /**
398
+ * Strict journal existence check for allocation (one readdir on success).
399
+ * @param {string} id session id.
400
+ * @returns {Promise<boolean>} true when a journal occupies the id.
401
+ * @private
402
+ */
403
+ async journalFileExists(id) {
404
+ const safe = safeSessionFileName(id)
405
+ const names = await readdir(this.dir)
406
+ return names.some((name) => name === `${safe}.ndjson` || (name.startsWith(`${safe}${INCARNATION_SEPARATOR}`) && name.endsWith('.ndjson')))
407
+ }
408
+
409
+ /**
410
+ * @returns {string} reservation directory path.
411
+ */
412
+ get idsDirectory() {
413
+ return this.dir.length > 0 ? join(this.dir, IDS_DIR) : ''
414
+ }
415
+
416
+ /**
417
+ * Register a new session incarnation and start buffering output.
418
+ *
419
+ * The journal is claimed with `open(file, 'wx')` before any byte is written:
420
+ * two stores, two processes or a reloaded plugin racing on the same logical id
421
+ * each get their own file. An existing journal is never reopened or appended.
422
+ * @param {{ id: string, owner?: string | null, title?: string, transport?: 'ssh' | 'telnet', host?: string, port?: number, username?: string, createdAt?: number }} meta session metadata.
423
+ * @returns {Promise<{ historyId: string, journal: string, fileBytes: number } | false>} the
424
+ * reserved incarnation handle, or `false` when no journal could be created.
166
425
  */
167
426
  async openSession(meta) {
168
- if (this.disposed) return
427
+ if (this.disposed) return false
428
+ const run = this.openInternal(meta)
429
+ this.openOps.add(run)
430
+ const forget = () => {
431
+ this.openOps.delete(run)
432
+ }
433
+ run.then(forget, forget)
434
+ return run
435
+ }
436
+
437
+ /**
438
+ * @param {{ id: string, owner?: string | null, title?: string, transport?: 'ssh' | 'telnet', host?: string, port?: number, username?: string, createdAt?: number }} meta session metadata.
439
+ * @returns {Promise<boolean>} whether a journal was reserved.
440
+ * @private
441
+ */
442
+ async openInternal(meta) {
169
443
  await this.ensureReady()
170
- if (this.dir.length === 0) return
444
+ if (this.dir.length === 0) return false
171
445
  const source = meta !== null && typeof meta === 'object' ? meta : {}
172
446
  const id = typeof source.id === 'string' && source.id.length > 0 ? source.id : ''
173
447
  if (id.length === 0) {
174
448
  this.log('debug', '[aiterm] history: openSession without an id ignored')
175
- return
449
+ return false
176
450
  }
451
+ const owner = normalizeOwnerValue(source.owner)
177
452
  const now = Date.now()
178
- const previous = this.catalog.get(id)
179
453
  const createdAt =
180
- typeof source.createdAt === 'number' && Number.isFinite(source.createdAt)
181
- ? Math.floor(source.createdAt)
182
- : (previous?.createdAt ?? now)
183
- /** @type {CatalogEntry} */
184
- const entry = {
185
- id,
186
- title:
187
- typeof source.title === 'string' && source.title.length > 0
188
- ? source.title.slice(0, 120)
189
- : (previous?.title ?? id),
454
+ typeof source.createdAt === 'number' && Number.isFinite(source.createdAt) ? Math.floor(source.createdAt) : now
455
+ // Retire a previous incarnation held by this store (same id) BEFORE
456
+ // reserving a new journal. A failed retire must not leave an orphan empty
457
+ // journal behind, and an unsaved older incarnation must stay writable.
458
+ const previous = this.active.get(id)
459
+ if (previous !== undefined) {
460
+ await this.writePending(previous)
461
+ if (previous.pending.length > 0 || previous.corrupt || previous.pendingClose !== undefined) {
462
+ this.warn(`cannot retire ${id} for a new incarnation: its bytes or close intent are still unsaved`)
463
+ return false
464
+ }
465
+ }
466
+ const reserved = await this.reserveJournal(id, owner, {
467
+ title: typeof source.title === 'string' && source.title.length > 0 ? source.title.slice(0, 120) : id,
190
468
  transport: source.transport === 'telnet' ? 'telnet' : 'ssh',
191
- host: typeof source.host === 'string' ? source.host.slice(0, 253) : (previous?.host ?? ''),
192
- port: boundInteger(source.port, previous?.port ?? 22, 1, 65_535),
193
- username: typeof source.username === 'string' ? source.username.slice(0, 128) : (previous?.username ?? ''),
469
+ host: typeof source.host === 'string' ? source.host.slice(0, 253) : '',
470
+ port: boundInteger(source.port, 22, 1, 65_535),
471
+ username: typeof source.username === 'string' ? source.username.slice(0, 128) : '',
194
472
  createdAt,
195
- bytes: previous?.bytes ?? 0,
196
- lastTs: previous?.lastTs ?? createdAt,
197
- }
198
- this.catalog.set(id, entry)
199
- this.discardState(id)
200
- const file = this.fileFor(id)
201
- let fileBytes = 0
202
- try {
203
- const info = await stat(file)
204
- fileBytes = info.size
205
- } catch (error) {
206
- if (error?.code !== 'ENOENT') this.warn(`cannot stat ${file}`, error)
473
+ })
474
+ if (reserved === undefined) return false
475
+ if (previous !== undefined) {
476
+ if (previous.timer !== undefined) clearTimeout(previous.timer)
477
+ this.active.delete(id)
207
478
  }
479
+ this.register(reserved)
480
+
208
481
  /** @type {ActiveSession} */
209
482
  const state = {
210
483
  id,
211
- file,
212
- entry,
484
+ file: reserved.journal,
485
+ entry: reserved,
213
486
  pending: [],
214
487
  pendingBytes: 0,
215
488
  timer: undefined,
216
489
  chain: Promise.resolve(),
217
- fileBytes,
490
+ fileBytes: reserved.fileBytes,
491
+ droppedBytes: 0,
492
+ writeFailures: 0,
493
+ retryDelayMs: 0,
494
+ degraded: false,
495
+ lastFailureLogAt: 0,
496
+ lastDropLogAt: 0,
497
+ pendingClose: undefined,
498
+ corrupt: false,
218
499
  }
219
500
  this.active.set(id, state)
220
501
  // Adopt output that raced ahead of this open (first banner, fast telnet).
221
- const orphan = this.orphans.get(id)
502
+ const orphanKey = orphanKeyFor(id, owner)
503
+ const orphan = this.orphans.get(orphanKey)
222
504
  if (orphan !== undefined) {
223
- this.orphans.delete(id)
505
+ this.orphans.delete(orphanKey)
224
506
  if (orphan.records.length > 0) {
225
507
  state.pending.push(...orphan.records)
226
508
  state.pendingBytes += orphan.bytes
@@ -230,9 +512,8 @@ export class HistoryStore {
230
512
  this.scheduleFlush(state, this.flushIntervalMs)
231
513
  }
232
514
  }
233
- if (fileBytes > 0 && entry.bytes === 0) entry.bytes = fileBytes
234
- await this.saveIndex()
235
- if (fileBytes > this.maxBytesPerSession) await this.truncateSession(state)
515
+ if (reserved.fileBytes > this.maxBytesPerSession) await this.truncateSession(state)
516
+ return { historyId: reserved.historyId, journal: reserved.journal, fileBytes: reserved.fileBytes }
236
517
  }
237
518
 
238
519
  /**
@@ -242,9 +523,10 @@ export class HistoryStore {
242
523
  * @param {string} sessionId session id.
243
524
  * @param {string} text decoded output.
244
525
  * @param {number} [at] epoch ms (default: now).
526
+ * @param {unknown} [owner] owning DSH session id (the registry always passes it).
245
527
  * @returns {void}
246
528
  */
247
- appendChunk(sessionId, text, at) {
529
+ appendChunk(sessionId, text, at, owner) {
248
530
  if (this.disposed) return
249
531
  if (typeof text !== 'string' || text.length === 0) return
250
532
  let bytes
@@ -257,18 +539,86 @@ export class HistoryStore {
257
539
  const timestamp = typeof at === 'number' && Number.isFinite(at) ? Math.floor(at) : Date.now()
258
540
  /** @type {PendingRecord} */
259
541
  const record = { t: timestamp, d: bytes.toString('base64'), size: bytes.length }
260
- const state = this.active.get(typeof sessionId === 'string' ? sessionId : '')
261
- if (state === undefined) {
262
- this.bufferOrphan(typeof sessionId === 'string' ? sessionId : '', record)
542
+ const id = typeof sessionId === 'string' ? sessionId : ''
543
+ const wanted = normalizeOwnerValue(owner)
544
+ const state = this.active.get(id)
545
+ if (state === undefined || state.entry.owner !== wanted) {
546
+ this.bufferOrphan(id, wanted, record)
547
+ return
548
+ }
549
+ if (state.corrupt) {
550
+ this.dropPending(state, record.size, 'journal is marked corrupt; writes are disabled')
551
+ return
552
+ }
553
+ if (record.size > this.maxPendingBytes) {
554
+ this.dropPending(state, record.size, 'single chunk exceeds the pending bound')
263
555
  return
264
556
  }
265
557
  state.pending.push(record)
266
558
  state.pendingBytes += bytes.length
267
559
  if (timestamp > state.entry.lastTs) state.entry.lastTs = timestamp
268
- if (state.pendingBytes >= FLUSH_THRESHOLD_BYTES) this.scheduleFlush(state, 0)
560
+ this.trimPending(state)
561
+ if (state.degraded) this.scheduleFlush(state, Math.max(this.flushIntervalMs, state.retryDelayMs))
562
+ else if (state.pendingBytes >= FLUSH_THRESHOLD_BYTES) this.scheduleFlush(state, 0)
269
563
  else this.scheduleFlush(state, this.flushIntervalMs)
270
564
  }
271
565
 
566
+ /**
567
+ * Bound one session's unsaved buffer. Oldest unsaved records are dropped
568
+ * first so the newest terminal output survives; a single oversized chunk is
569
+ * dropped as a whole. This is explicit loss, never a zero-loss promise.
570
+ * @param {ActiveSession} state session state.
571
+ * @returns {void}
572
+ * @private
573
+ */
574
+ trimPending(state) {
575
+ while (state.pendingBytes > this.maxPendingBytes && state.pending.length > 0) {
576
+ const removed = state.pending.shift()
577
+ if (removed === undefined) break
578
+ state.pendingBytes -= removed.size
579
+ this.dropPending(state, removed.size, 'pending bound reached')
580
+ }
581
+ }
582
+
583
+ /**
584
+ * Account for dropped bytes and emit a throttled warning.
585
+ * @param {ActiveSession} state session state.
586
+ * @param {number} bytes dropped bytes.
587
+ * @param {string} reason fixed reason.
588
+ * @returns {void}
589
+ * @private
590
+ */
591
+ dropPending(state, bytes, reason) {
592
+ state.droppedBytes += Math.max(0, bytes)
593
+ state.degraded = true
594
+ const now = Date.now()
595
+ if (now - state.lastDropLogAt >= FAILURE_LOG_INTERVAL_MS) {
596
+ state.lastDropLogAt = now
597
+ this.warn(`dropped ${state.droppedBytes} buffered byte(s) for ${state.id}: ${reason}`)
598
+ }
599
+ }
600
+
601
+ /**
602
+ * Diagnostics for tests/operators. Counts are cumulative; `degraded` means
603
+ * the session has lost buffered bytes or is currently failing appends.
604
+ * @param {string} sessionId session id.
605
+ * @returns {Promise<{ pendingBytes: number, droppedBytes: number, writeFailures: number, retryDelayMs: number, degraded: boolean } | undefined>} stats.
606
+ */
607
+ async stats(sessionId) {
608
+ await this.ensureReady()
609
+ const state = this.active.get(typeof sessionId === 'string' ? sessionId : '')
610
+ if (state === undefined) return undefined
611
+ return {
612
+ pendingBytes: state.pendingBytes,
613
+ droppedBytes: state.droppedBytes,
614
+ writeFailures: state.writeFailures,
615
+ retryDelayMs: state.retryDelayMs,
616
+ degraded: state.degraded,
617
+ pendingClose: state.pendingClose !== undefined,
618
+ corrupt: state.corrupt === true,
619
+ }
620
+ }
621
+
272
622
  /**
273
623
  * Flush buffered records for one session (or every session).
274
624
  * @param {string} [sessionId] session to flush; omit for all.
@@ -281,93 +631,928 @@ export class HistoryStore {
281
631
  if (state !== undefined) await this.writePending(state)
282
632
  return
283
633
  }
284
- await Promise.allSettled([...this.active.values()].map((state) => this.writePending(state)))
634
+ await Promise.allSettled([...this.active.values()].map((state) => this.writePending(state)))
635
+ }
636
+
637
+ /**
638
+ * Wait for buffered writes and pending close-metadata appends.
639
+ * @returns {Promise<void>} completion.
640
+ */
641
+ async whenIdle() {
642
+ await this.ensureReady()
643
+ while (this.openOps.size > 0) await Promise.allSettled([...this.openOps])
644
+ await Promise.allSettled([...this.active.values()].map((state) => this.writePending(state)))
645
+ while (this.operations.size > 0) await Promise.allSettled([...this.operations])
646
+ await this.retryPendingCloses().catch(() => {})
647
+ await Promise.allSettled([...this.active.values()].map((state) => state.chain))
648
+ }
649
+
650
+ /**
651
+ * Flush and mark a session closed. The journal and metadata stay for
652
+ * `listRecordings` / `queryRecording`; only the owning incarnation is touched.
653
+ * @param {string} sessionId session id.
654
+ * @param {{ closedAt?: number, permission?: { aiAccess?: unknown }, owner?: unknown, historyId?: string }} [info] close details.
655
+ * @returns {Promise<void>} completion.
656
+ */
657
+ async closeSession(sessionId, info) {
658
+ if (this.disposed) return
659
+ const run = this.closeInternal(sessionId, info)
660
+ this.operations.add(run)
661
+ const forget = () => {
662
+ this.operations.delete(run)
663
+ }
664
+ run.then(forget, forget)
665
+ return run
666
+ }
667
+
668
+ /**
669
+ * @param {string} sessionId session id.
670
+ * @param {{ closedAt?: number, permission?: { aiAccess?: unknown }, owner?: unknown }} [info] close details.
671
+ * @returns {Promise<void>} completion.
672
+ * @private
673
+ */
674
+ async closeInternal(sessionId, info) {
675
+ await this.ensureReady()
676
+ // A close may race the fire-and-forget open from `create()` (the registry
677
+ // never blocks a connect on disk). Wait for in-flight reservations so the
678
+ // close metadata is appended to the same incarnation, never lost.
679
+ if (this.openOps.size > 0) await Promise.allSettled([...this.openOps])
680
+ const id = typeof sessionId === 'string' ? sessionId : ''
681
+ const details = info !== null && typeof info === 'object' ? info : {}
682
+ const ownerGiven = details.owner !== undefined
683
+ const wanted = ownerGiven ? normalizeOwnerValue(details.owner) : undefined
684
+ const address = typeof details.historyId === 'string' && details.historyId.length > 0 ? details.historyId : undefined
685
+ const closedAt =
686
+ typeof details.closedAt === 'number' && Number.isFinite(details.closedAt) ? Math.floor(details.closedAt) : Date.now()
687
+ const aiAccess = typeof details.permission?.aiAccess === 'string' && isAiAccess(details.permission.aiAccess)
688
+ ? details.permission.aiAccess
689
+ : undefined
690
+ /** @type {{ id: string, owner: string | null, closedAt: number, aiAccess?: 'ro' | 'wo' | 'rw', historyId?: string }} */
691
+ const intent = {
692
+ id,
693
+ owner: ownerGiven ? wanted : null,
694
+ closedAt,
695
+ historyId: address,
696
+ ownerGiven,
697
+ }
698
+ if (aiAccess !== undefined) intent.aiAccess = aiAccess
699
+ this.dropOrphans(id, wanted)
700
+
701
+ const state = this.active.get(id)
702
+ // A close must target exactly the incarnation this store opened. When a
703
+ // reservation failed there is no active state: never guess another
704
+ // incarnation by id/owner, because stamping a permission onto a crashed
705
+ // journal would turn an unknown-permission file into an AI-readable one.
706
+ if (
707
+ state !== undefined &&
708
+ (!ownerGiven || state.entry.owner === wanted) &&
709
+ (address === undefined || state.entry.historyId === address)
710
+ ) {
711
+ if (state.corrupt) {
712
+ this.warn(`refusing to close ${id}: its journal is marked corrupt`)
713
+ return
714
+ }
715
+ state.pendingClose = intent
716
+ await this.writePending(state)
717
+ // If the data flush is still incomplete the close stays pending; the same
718
+ // writer retries and appends the close metadata only after data succeeds.
719
+ if (state.pendingClose !== undefined) {
720
+ if (!this.disposed) this.scheduleFlush(state, Math.max(1000, state.retryDelayMs || 1000))
721
+ }
722
+ return
723
+ }
724
+ this.dropOrphans(id, wanted)
725
+ if (address !== undefined) {
726
+ const exact = this.byHistory.get(address)
727
+ if (exact !== undefined && exact.id === id && (!ownerGiven || exact.owner === wanted)) {
728
+ intent.historyId = exact.historyId
729
+ if (!(await this.appendCloseFor(exact, intent))) {
730
+ this.pendingCloseRecords.set(exact.historyId, intent)
731
+ this.scheduleCloseRetry()
732
+ }
733
+ }
734
+ }
735
+ }
736
+
737
+ /**
738
+ * Append close metadata for an exact recording; update in-memory permission
739
+ * only after the append succeeded. Never touches another incarnation.
740
+ * @param {Recording} recording recording.
741
+ * @param {{ closedAt: number, aiAccess?: 'ro' | 'wo' | 'rw', historyId?: string }} intent close intent.
742
+ * @returns {Promise<boolean>} whether the metadata was written.
743
+ * @private
744
+ */
745
+ async appendCloseFor(recording, intent) {
746
+ if (recording === null || typeof recording !== 'object') return false
747
+ if (typeof intent.historyId === 'string' && recording.historyId !== intent.historyId) return false
748
+ /** @type {Record<string, unknown>} */
749
+ const meta = {
750
+ [META_MARKER]: 'close',
751
+ version: META_VERSION,
752
+ closedAt: intent.closedAt,
753
+ bytes: Math.max(0, Math.floor(recording.bytes)),
754
+ lastTs: Math.max(0, Math.floor(recording.lastTs)),
755
+ }
756
+ if (intent.aiAccess !== undefined) meta.aiAccess = intent.aiAccess
757
+ const line = `${JSON.stringify(meta)}\n`
758
+ try {
759
+ await this.appendCloseLine(recording.journal, line)
760
+ recording.fileBytes += Buffer.byteLength(line, 'utf8')
761
+ recording.closedAt = intent.closedAt
762
+ recording.mtime = Date.now()
763
+ if (intent.aiAccess !== undefined) recording.aiAccess = intent.aiAccess
764
+ return true
765
+ } catch (error) {
766
+ this.warn(`cannot append close metadata for ${recording.id}`, error)
767
+ return false
768
+ }
769
+ }
770
+
771
+ /**
772
+ * Low-level close metadata append (overridable in tests).
773
+ * @param {string} file journal path.
774
+ * @param {string} line encoded metadata line.
775
+ * @returns {Promise<void>} completion.
776
+ */
777
+ async appendCloseLine(file, line) {
778
+ await appendFile(file, line, { mode: 0o600 })
779
+ }
780
+
781
+ /**
782
+ * Retry pending close metadata without touching any other incarnation.
783
+ * @returns {Promise<void>} completion.
784
+ * @private
785
+ */
786
+ async retryPendingCloses() {
787
+ if (this.pendingCloseRecords.size === 0) return
788
+ for (const [historyId, intent] of [...this.pendingCloseRecords]) {
789
+ const recording = this.byHistory.get(historyId)
790
+ if (recording === undefined || recording.id !== intent.id) {
791
+ this.pendingCloseRecords.delete(historyId)
792
+ continue
793
+ }
794
+ if (intent.ownerGiven === true && recording.owner !== normalizeOwnerValue(intent.owner)) {
795
+ // recording identity is the key; owner is fixed at open and re-checked
796
+ // here so a stale intent cannot stamp a reused id.
797
+ this.pendingCloseRecords.delete(historyId)
798
+ continue
799
+ }
800
+ if (await this.appendCloseFor(recording, intent)) this.pendingCloseRecords.delete(historyId)
801
+ }
802
+ this.scheduleCloseRetry()
803
+ }
804
+
805
+ /**
806
+ * One bounded retry timer for close metadata.
807
+ * @returns {void}
808
+ * @private
809
+ */
810
+ scheduleCloseRetry() {
811
+ if (this.disposed || this.pendingCloseRecords.size === 0 || this.closeRetryTimer !== undefined) return
812
+ this.closeRetryDelayMs = Math.min(60_000, Math.max(1000, (this.closeRetryDelayMs || 1000) * 2))
813
+ this.closeRetryTimer = setTimeout(() => {
814
+ this.closeRetryTimer = undefined
815
+ void this.retryPendingCloses()
816
+ }, this.closeRetryDelayMs)
817
+ if (typeof this.closeRetryTimer?.unref === 'function') this.closeRetryTimer.unref()
818
+ }
819
+
820
+ /**
821
+ * Attributed recordings (new journals with a valid provenance header).
822
+ * The returned objects carry private `owner`, `aiAccess` and `journal`
823
+ * fields: callers must map them to the public catalog shape before exposing
824
+ * them to tools or the browser.
825
+ * @param {{ limit?: number, since?: number, until?: number }} [query] filter.
826
+ * @returns {Promise<Recording[]>} recordings, newest activity first.
827
+ */
828
+ async listRecordings(query = {}) {
829
+ const page = await this.listRecordingsPage(query)
830
+ return page.recordings
831
+ }
832
+
833
+ /**
834
+ * Paged attributed recordings with owner filtering applied **before** the
835
+ * limit, so another owner cannot crowd this owner's rows out and the total is
836
+ * truthful. `total` counts all matching rows; `truncated` means offset+shown
837
+ * is below it.
838
+ * @param {{ limit?: number, offset?: number, owner?: unknown, since?: number, until?: number }} [query] filter/paging.
839
+ * @returns {Promise<{ recordings: Recording[], total: number, truncated: boolean }>} page.
840
+ */
841
+ async listRecordingsPage(query = {}) {
842
+ await this.ensureReady()
843
+ const options = query !== null && typeof query === 'object' ? query : {}
844
+ const limit = boundInteger(options.limit, 100, 1, 20_000)
845
+ const offset = boundInteger(options.offset, 0, 0, 100_000)
846
+ const since = typeof options.since === 'number' && Number.isFinite(options.since) ? options.since : -Infinity
847
+ const until = typeof options.until === 'number' && Number.isFinite(options.until) ? options.until : Infinity
848
+ const ownerFilter = options.owner !== undefined ? normalizeOwnerValue(options.owner) : undefined
849
+ const filtered = [...this.recordings.values()]
850
+ .filter((recording) => ownerFilter === undefined || recording.owner === ownerFilter)
851
+ .filter((recording) => activity(recording) >= since && recording.createdAt <= until)
852
+ .sort(newestFirst)
853
+ const page = filtered.slice(offset, offset + limit)
854
+ return {
855
+ recordings: page.map((recording) => ({ ...recording })),
856
+ total: filtered.length,
857
+ truncated: offset + page.length < filtered.length,
858
+ snapshot: pageSnapshot(filtered),
859
+ }
860
+ }
861
+
862
+ /**
863
+ * Paged legacy entries. The legacy catalog is normally small, but the same
864
+ * owner/limit discipline keeps recoverability explicit.
865
+ * @param {{ limit?: number, offset?: number, since?: number, until?: number }} [query] filter/paging.
866
+ * @returns {Promise<{ sessions: CatalogEntry[], total: number, truncated: boolean }>} page.
867
+ */
868
+ async listLegacySessionsPage(query = {}) {
869
+ await this.ensureReady()
870
+ const options = query !== null && typeof query === 'object' ? query : {}
871
+ const limit = boundInteger(options.limit, 100, 1, 20_000)
872
+ const offset = boundInteger(options.offset, 0, 0, 100_000)
873
+ const since = typeof options.since === 'number' && Number.isFinite(options.since) ? options.since : -Infinity
874
+ const until = typeof options.until === 'number' && Number.isFinite(options.until) ? options.until : Infinity
875
+ const filtered = [...this.legacy.values()]
876
+ .filter((entry) => activity(entry) >= since && entry.createdAt <= until)
877
+ .sort(newestFirst)
878
+ const page = filtered.slice(offset, offset + limit)
879
+ return {
880
+ sessions: page.map((entry) => publicEntry(entry)),
881
+ total: filtered.length,
882
+ truncated: offset + page.length < filtered.length,
883
+ snapshot: pageSnapshot(filtered),
884
+ }
885
+ }
886
+
887
+ /**
888
+ * Legacy catalog entries (ownerless, from the old `index.json`).
889
+ * @param {{ limit?: number, since?: number, until?: number }} [query] filter.
890
+ * @returns {Promise<CatalogEntry[]>} legacy entries, newest activity first.
891
+ */
892
+ async listLegacySessions(query = {}) {
893
+ const page = await this.listLegacySessionsPage(query)
894
+ return page.sessions
895
+ }
896
+
897
+ /**
898
+ * Catalogued legacy entry for one id, if any. The caller must enforce the
899
+ * human-only legacy policy; this method only answers what the old index says.
900
+ * @param {string} sessionId session id.
901
+ * @returns {Promise<CatalogEntry | undefined>} legacy entry.
902
+ */
903
+ async legacyEntry(sessionId) {
904
+ await this.ensureReady()
905
+ return typeof sessionId === 'string' ? this.legacy.get(sessionId) : undefined
906
+ }
907
+
908
+ /**
909
+ * Exact legacy journal path for a catalogued legacy entry. Unlike
910
+ * `journalForSync`, this never resolves a new-format incarnation, so the
911
+ * explicit legacy view cannot accidentally export a different file.
912
+ * @param {string} sessionId session id.
913
+ * @returns {Promise<string | undefined>} legacy journal path.
914
+ */
915
+ async legacyJournal(sessionId) {
916
+ await this.ensureReady()
917
+ return typeof sessionId === 'string' && this.legacy.has(sessionId) ? this.legacyFileFor(sessionId) : undefined
918
+ }
919
+
920
+ /**
921
+ * Resolve one exact incarnation by its opaque history address.
922
+ * @param {string} historyId incarnation address.
923
+ * @param {string | null} wanted normalized owner.
924
+ * @param {'human' | 'ai'} actor caller.
925
+ * @returns {Promise<{ kind: 'attributed', recording: Recording } | undefined>} resolution.
926
+ */
927
+ async resolveByHistoryId(historyId, wanted, actor) {
928
+ if (typeof historyId !== 'string' || historyId.length === 0) return undefined
929
+ await this.ensureReady()
930
+ if (actor === 'ai' && wanted === null) return undefined
931
+ let recording = this.byHistory.get(historyId)
932
+ if (recording === undefined && this.scanned && Date.now() - this.lastScanAt >= SCAN_COOLDOWN_MS) {
933
+ await this.scan()
934
+ recording = this.byHistory.get(historyId)
935
+ }
936
+ if (recording === undefined || recording.owner !== wanted) return undefined
937
+ return { kind: 'attributed', recording }
938
+ }
939
+
940
+ /**
941
+ * Resolve one journal for a read by an owner-scoped caller.
942
+ *
943
+ * Attributed journals are matched by the owner recorded in the header; when
944
+ * several incarnations share a logical id, the newest one for that owner is
945
+ * used. Legacy journals are only resolvable by the explicit human legacy
946
+ * (owner `null`) bucket. Orphans are never resolvable.
947
+ * @param {string} sessionId session id.
948
+ * @param {unknown} owner requester owner (`null` = legacy bucket).
949
+ * @param {'human' | 'ai'} actor caller.
950
+ * @returns {Promise<{ kind: 'attributed', recording: Recording } | { kind: 'legacy', entry: CatalogEntry } | undefined>} resolution.
951
+ */
952
+ async resolveForRead(sessionId, owner, actor, historyId) {
953
+ await this.ensureReady()
954
+ if (typeof sessionId !== 'string' || sessionId.length === 0) return undefined
955
+ const wanted = normalizeOwnerValue(owner)
956
+ if (typeof historyId === 'string' && historyId.length > 0) {
957
+ const resolved = await this.resolveByHistoryId(historyId, wanted, actor)
958
+ if (resolved === undefined) return undefined
959
+ if (resolved.recording.id !== sessionId) return undefined
960
+ return resolved
961
+ }
962
+ // An AI caller must never fall into the ownerless bucket, even if a caller
963
+ // forgets to check before reaching the store.
964
+ if (actor === 'ai' && wanted === null) return undefined
965
+ const list = await this.lookupRecordings(sessionId)
966
+ const owned = list.filter((recording) => recording.owner === wanted).sort(newestFirst)
967
+ if (owned.length > 0) return { kind: 'attributed', recording: owned[0] }
968
+ if (actor === 'human' && wanted === null) {
969
+ const entry = this.legacy.get(sessionId)
970
+ if (entry !== undefined) return { kind: 'legacy', entry }
971
+ }
972
+ return undefined
973
+ }
974
+
975
+ /**
976
+ * Current in-memory recording for an exact incarnation address.
977
+ *
978
+ * The returned object is live: a concurrent close may add `aiAccess`/
979
+ * `closedAt` after the caller looked. Callers that authorize before using it
980
+ * must re-check owner and permission at the point of use.
981
+ * @param {string} historyId opaque address.
982
+ * @returns {Recording | undefined} recording.
983
+ */
984
+ recordingByHistoryIdSync(historyId) {
985
+ if (typeof historyId !== 'string' || historyId.length === 0) return undefined
986
+ return this.byHistory.get(historyId)
987
+ }
988
+
989
+ /**
990
+ * Whether the recorded closed permission lets the AI read this journal.
991
+ * An absent or unknown value fails closed.
992
+ * @param {Recording} recording recording.
993
+ * @returns {boolean} true only for `ro`/`rw`.
994
+ */
995
+ canAiRead(recording) {
996
+ return recording !== null && typeof recording === 'object' && (recording.aiAccess === 'ro' || recording.aiAccess === 'rw')
997
+ }
998
+
999
+ /**
1000
+ * Synchronous journal lookup for the exporter. The caller has already
1001
+ * resolved/listed this id; this method re-checks owner and permission so a
1002
+ * facade cannot accidentally fall back to another owner's or a legacy file.
1003
+ * @param {string} sessionId session id.
1004
+ * @param {{ owner?: unknown, actor?: 'human' | 'ai' }} [options] requester.
1005
+ * @returns {string | undefined} absolute journal path.
1006
+ */
1007
+ journalForSync(sessionId, options = {}) {
1008
+ const id = typeof sessionId === 'string' ? sessionId : ''
1009
+ if (id.length === 0) return undefined
1010
+ const wanted = normalizeOwnerValue(options.owner)
1011
+ const actor = options.actor === 'human' ? 'human' : 'ai'
1012
+ if (actor === 'ai' && wanted === null) return undefined
1013
+ const address = typeof options.historyId === 'string' && options.historyId.length > 0 ? options.historyId : undefined
1014
+ if (address !== undefined) {
1015
+ const exact = this.byHistory.get(address)
1016
+ if (exact === undefined || exact.id !== id || exact.owner !== wanted) return undefined
1017
+ if (actor === 'ai' && !this.canAiRead(exact)) return undefined
1018
+ return exact.journal
1019
+ }
1020
+ const state = this.active.get(id)
1021
+ if (state !== undefined && state.entry.owner === wanted) return state.file
1022
+ const owned = (this.byId.get(id) ?? []).filter((recording) => recording.owner === wanted).sort(newestFirst)
1023
+ if (owned.length > 0) {
1024
+ const recording = owned[0]
1025
+ if (actor === 'ai' && (wanted === null || !this.canAiRead(recording))) return undefined
1026
+ return recording.journal
1027
+ }
1028
+ if (actor === 'human' && wanted === null && this.legacy.has(id)) return this.legacyFileFor(id)
1029
+ return undefined
1030
+ }
1031
+
1032
+ /**
1033
+ * Journal path of the active incarnation for an id, if this store owns it.
1034
+ * @param {string} sessionId session id.
1035
+ * @returns {string | undefined} absolute journal path.
1036
+ */
1037
+ activeJournal(sessionId, owner, historyId) {
1038
+ const state = this.active.get(typeof sessionId === 'string' ? sessionId : '')
1039
+ if (state === undefined) return undefined
1040
+ const wanted = normalizeOwnerValue(owner)
1041
+ if (state.entry.owner !== wanted) return undefined
1042
+ if (typeof historyId === 'string' && historyId.length > 0 && state.entry.historyId !== historyId) return undefined
1043
+ return state.file
1044
+ }
1045
+
1046
+ /**
1047
+ * Exact active-incarnation handle for a live session (owner-checked).
1048
+ * @param {string} sessionId session id.
1049
+ * @param {unknown} owner owner.
1050
+ * @param {string} [historyId] optional exact address.
1051
+ * @returns {{ historyId: string, journal: string } | undefined} handle.
1052
+ */
1053
+ activeHandle(sessionId, owner, historyId) {
1054
+ const state = this.active.get(typeof sessionId === 'string' ? sessionId : '')
1055
+ if (state === undefined) return undefined
1056
+ const wanted = normalizeOwnerValue(owner)
1057
+ if (state.entry.owner !== wanted) return undefined
1058
+ if (typeof historyId === 'string' && historyId.length > 0 && state.entry.historyId !== historyId) return undefined
1059
+ return { historyId: state.entry.historyId, journal: state.file }
1060
+ }
1061
+
1062
+ /**
1063
+ * Search one attributed journal. Metadata lines carry no `t`/`d` pair and are
1064
+ * therefore ignored by the record parser.
1065
+ * @param {Recording} recording recording.
1066
+ * @param {{ since?: number, until?: number, search?: string, context?: number, maxMatches?: number, maxBytes?: number }} [query] query.
1067
+ * @returns {Promise<HistoryQueryResult>} matches and scan bookkeeping.
1068
+ */
1069
+ async queryRecording(recording, query = {}) {
1070
+ await this.ensureReady()
1071
+ if (recording === null || typeof recording !== 'object' || typeof recording.journal !== 'string') {
1072
+ return { matches: [], scannedBytes: 0, truncated: false }
1073
+ }
1074
+ return this.searchJournal(recording.journal, publicEntry(recording), query)
1075
+ }
1076
+
1077
+ /**
1078
+ * Catalogued legacy entry for one id, if any. The caller must enforce the
1079
+ * human-only legacy policy; this method only answers what the old index says.
1080
+ * @param {string} sessionId session id.
1081
+ * @returns {Promise<CatalogEntry | undefined>} legacy entry.
1082
+ */
1083
+ async legacyEntry(sessionId) {
1084
+ await this.ensureReady()
1085
+ return typeof sessionId === 'string' ? this.legacy.get(sessionId) : undefined
1086
+ }
1087
+
1088
+ /**
1089
+ * Exact legacy journal path for a catalogued legacy entry. Unlike
1090
+ * `journalForSync`, this never resolves a new-format incarnation, so the
1091
+ * explicit legacy view cannot accidentally export a different file.
1092
+ * @param {string} sessionId session id.
1093
+ * @returns {Promise<string | undefined>} legacy journal path.
1094
+ */
1095
+ async legacyJournal(sessionId) {
1096
+ await this.ensureReady()
1097
+ return typeof sessionId === 'string' && this.legacy.has(sessionId) ? this.legacyFileFor(sessionId) : undefined
1098
+ }
1099
+
1100
+ /**
1101
+ * Search one catalogued legacy journal (human legacy bucket only).
1102
+ * @param {CatalogEntry} entry legacy entry.
1103
+ * @param {{ since?: number, until?: number, search?: string, context?: number, maxMatches?: number, maxBytes?: number }} [query] query.
1104
+ * @returns {Promise<HistoryQueryResult>} matches and scan bookkeeping.
1105
+ */
1106
+ async queryLegacy(entry, query = {}) {
1107
+ await this.ensureReady()
1108
+ if (entry === null || typeof entry !== 'object' || typeof entry.id !== 'string') {
1109
+ return { matches: [], scannedBytes: 0, truncated: false }
1110
+ }
1111
+ return this.searchJournal(this.legacyFileFor(entry.id), publicEntry(entry), query)
1112
+ }
1113
+
1114
+ /**
1115
+ * Owner-scoped read convenience. Callers that need to distinguish
1116
+ * "not found" from "permission denied" use {@link resolveForRead} plus
1117
+ * {@link canAiRead} (the registry does that); this wrapper fails closed.
1118
+ * @param {{ sessionId?: string, owner?: unknown, actor?: 'human' | 'ai', since?: number, until?: number, search?: string, context?: number, maxMatches?: number, maxBytes?: number }} [query] query.
1119
+ * @returns {Promise<HistoryQueryResult>} matches and scan bookkeeping.
1120
+ */
1121
+ async query(query = {}) {
1122
+ await this.ensureReady()
1123
+ const options = query !== null && typeof query === 'object' ? query : {}
1124
+ const actor = options.actor === 'human' ? 'human' : 'ai'
1125
+ const wanted = normalizeOwnerValue(options.owner)
1126
+ const resolved = await this.resolveForRead(
1127
+ typeof options.sessionId === 'string' ? options.sessionId : '',
1128
+ wanted,
1129
+ actor,
1130
+ )
1131
+ if (resolved === undefined) return { matches: [], scannedBytes: 0, truncated: false }
1132
+ if (resolved.kind === 'attributed') {
1133
+ if (actor === 'ai' && (wanted === null || !this.canAiRead(resolved.recording))) {
1134
+ return { matches: [], scannedBytes: 0, truncated: false }
1135
+ }
1136
+ return this.queryRecording(resolved.recording, options)
1137
+ }
1138
+ if (actor !== 'human' || wanted !== null) return { matches: [], scannedBytes: 0, truncated: false }
1139
+ return this.queryLegacy(resolved.entry, options)
1140
+ }
1141
+
1142
+ /**
1143
+ * Apply retention and the size cap to attributed journals. Legacy files are
1144
+ * never deleted or rewritten: they are exactly the data this migration must
1145
+ * preserve.
1146
+ * @param {number} [now] epoch ms (default: now).
1147
+ * @returns {Promise<void>} completion.
1148
+ */
1149
+ async prune(now) {
1150
+ if (this.disposed) return
1151
+ await this.ensureReady()
1152
+ await this.pruneRecordings(now)
1153
+ }
1154
+
1155
+ /**
1156
+ * Flush everything, finish pending metadata appends and stop timers.
1157
+ * Idempotent; never throws.
1158
+ * @returns {Promise<void>} completion.
1159
+ */
1160
+ async dispose() {
1161
+ if (this.disposed) return
1162
+ this.disposed = true
1163
+ // Let an open that started before shutdown finish first: it may still add a
1164
+ // writer that must be flushed, and it must never be left unflushed.
1165
+ while (this.openOps.size > 0) await Promise.allSettled([...this.openOps])
1166
+ const states = [...this.active.values()]
1167
+ for (const state of states) {
1168
+ if (state.timer !== undefined) {
1169
+ clearTimeout(state.timer)
1170
+ state.timer = undefined
1171
+ }
1172
+ }
1173
+ await Promise.allSettled(states.map((state) => this.writePending(state)))
1174
+ await this.retryPendingCloses().catch(() => {})
1175
+ if (this.closeRetryTimer !== undefined) {
1176
+ clearTimeout(this.closeRetryTimer)
1177
+ this.closeRetryTimer = undefined
1178
+ }
1179
+ this.active.clear()
1180
+ this.orphans.clear()
1181
+ while (this.operations.size > 0) await Promise.allSettled([...this.operations])
1182
+ }
1183
+
1184
+ /**
1185
+ * Legacy path for one id, used only for catalogued pre-upgrade journals.
1186
+ * @param {string} id session id.
1187
+ * @returns {string} journal path.
1188
+ */
1189
+ legacyFileFor(id) {
1190
+ return join(this.dir, `${safeSessionFileName(id)}.ndjson`)
1191
+ }
1192
+
1193
+ /**
1194
+ * Compatibility alias: older callers used `fileFor` for the legacy path.
1195
+ * New code must use {@link journalForSync} or {@link activeJournal}.
1196
+ * @param {string} id session id.
1197
+ * @returns {string} legacy journal path.
1198
+ */
1199
+ fileFor(id) {
1200
+ return this.legacyFileFor(id)
1201
+ }
1202
+
1203
+ /**
1204
+ * Await `init()`, running it on first use.
1205
+ * @returns {Promise<void>} completion.
1206
+ */
1207
+ async ensureReady() {
1208
+ if (this.ready === undefined) await this.init()
1209
+ else await this.ready
1210
+ }
1211
+
1212
+ /**
1213
+ * Read the legacy catalog. Entries are treated as ownerless metadata only:
1214
+ * an `owner` field written by some other version is ignored, never trusted.
1215
+ * @returns {Promise<void>} completion.
1216
+ * @private
1217
+ */
1218
+ async loadLegacyCatalog() {
1219
+ const index = await readJsonIfPresent(join(this.dir, INDEX_FILE))
1220
+ const entries = index !== null && typeof index === 'object' && Array.isArray(index.sessions) ? index.sessions : []
1221
+ for (const raw of entries) {
1222
+ const entry = normalizeEntry(raw)
1223
+ if (entry !== undefined) {
1224
+ this.legacy.set(entry.id, entry)
1225
+ this.usedIds.add(entry.id)
1226
+ }
1227
+ }
1228
+ }
1229
+
1230
+ /**
1231
+ * Discover attributed journals by reading their first line. The directory is
1232
+ * scanned for read/list purposes only; it is never used to decide an append
1233
+ * target (that is the exclusive-create reservation in `reserveJournal`).
1234
+ * @returns {Promise<void>} completion.
1235
+ * @private
1236
+ */
1237
+ async scan() {
1238
+ if (this.dir.length === 0) return
1239
+ let names
1240
+ try {
1241
+ names = await readdir(this.dir)
1242
+ } catch (error) {
1243
+ if (error?.code !== 'ENOENT') this.warn('cannot scan history directory', error)
1244
+ this.scanned = true
1245
+ return
1246
+ }
1247
+ this.scanned = true
1248
+ this.scanCount += 1
1249
+ this.lastScanAt = Date.now()
1250
+ for (const name of names) {
1251
+ if (name.endsWith('.ndjson') && !isIncarnationName(name)) {
1252
+ // A legacy journal occupies its id even before/without an index entry.
1253
+ this.usedIds.add(name.slice(0, -'.ndjson'.length))
1254
+ continue
1255
+ }
1256
+ if (!isIncarnationName(name)) continue
1257
+ const file = join(this.dir, name)
1258
+ try {
1259
+ const recording = await this.readRecording(file)
1260
+ if (recording !== undefined) {
1261
+ this.usedIds.add(recording.id)
1262
+ this.register(recording)
1263
+ }
1264
+ } catch (error) {
1265
+ this.warn(`cannot hydrate history journal ${name}`, error)
1266
+ }
1267
+ }
1268
+ try {
1269
+ for (const name of await readdir(this.idsDirectory)) this.usedIds.add(name)
1270
+ } catch {
1271
+ // no reservation directory yet
1272
+ }
1273
+ }
1274
+
1275
+ /**
1276
+ * Read one incarnation's header, size and close metadata.
1277
+ * @param {string} file absolute path.
1278
+ * @returns {Promise<Recording | undefined>} recording or undefined when the
1279
+ * header is missing/malformed (the file is then left untouched and fails
1280
+ * closed for every owner-scoped caller).
1281
+ * @private
1282
+ */
1283
+ async readRecording(file) {
1284
+ const headerLine = await readFirstLine(file)
1285
+ const meta = parseJournalHeader(headerLine)
1286
+ if (meta === undefined) return undefined
1287
+ let info
1288
+ try {
1289
+ info = await stat(file)
1290
+ } catch {
1291
+ return undefined
1292
+ }
1293
+ const tail = await readTailLines(file, info.size)
1294
+ let closedAt
1295
+ let aiAccess
1296
+ let closedBytes
1297
+ let lastTs = meta.createdAt
1298
+ for (const line of tail) {
1299
+ const parsed = parseJsonObject(line)
1300
+ if (parsed === undefined) continue
1301
+ if (parsed[META_MARKER] === 'close') {
1302
+ const candidate = finiteInteger(parsed.closedAt, undefined)
1303
+ if (candidate !== undefined) closedAt = candidate
1304
+ if (typeof parsed.aiAccess === 'string' && isAiAccess(parsed.aiAccess)) aiAccess = parsed.aiAccess
1305
+ const bytes = finiteInteger(parsed.bytes, undefined)
1306
+ if (bytes !== undefined && bytes >= 0) closedBytes = bytes
1307
+ const closedLast = finiteInteger(parsed.lastTs, undefined)
1308
+ if (closedLast !== undefined && closedLast > lastTs) lastTs = closedLast
1309
+ } else if (typeof parsed.t === 'number' && Number.isFinite(parsed.t) && parsed.t > lastTs) {
1310
+ lastTs = Math.floor(parsed.t)
1311
+ }
1312
+ }
1313
+ const headerBytes = Buffer.byteLength(headerLine, 'utf8') + 1
1314
+ /** @type {Recording} */
1315
+ const recording = {
1316
+ ...meta,
1317
+ historyId: historyIdOf(file),
1318
+ journal: file,
1319
+ fileBytes: info.size,
1320
+ mtime: info.mtimeMs,
1321
+ bytes: closedBytes !== undefined ? closedBytes : Math.max(0, info.size - headerBytes),
1322
+ lastTs,
1323
+ }
1324
+ if (closedAt !== undefined) recording.closedAt = closedAt
1325
+ if (aiAccess !== undefined) recording.aiAccess = aiAccess
1326
+ return recording
1327
+ }
1328
+
1329
+ /**
1330
+ * Add/merge one hydrated recording without replacing an active in-memory
1331
+ * writer (which owns the freshest buffered state).
1332
+ * @param {Recording} recording recording.
1333
+ * @returns {void}
1334
+ * @private
1335
+ */
1336
+ register(recording) {
1337
+ const existing = this.recordings.get(recording.journal)
1338
+ if (existing !== undefined) {
1339
+ const active = [...this.active.values()].some((state) => state.entry === existing)
1340
+ if (!active) Object.assign(existing, recording)
1341
+ return
1342
+ }
1343
+ this.recordings.set(recording.journal, recording)
1344
+ if (typeof recording.historyId === 'string' && recording.historyId.length > 0) {
1345
+ this.byHistory.set(recording.historyId, recording)
1346
+ }
1347
+ const list = this.byId.get(recording.id)
1348
+ if (list === undefined) this.byId.set(recording.id, [recording])
1349
+ else list.push(recording)
1350
+ }
1351
+
1352
+ /**
1353
+ * @param {string} sessionId session id.
1354
+ * @returns {Promise<Recording[]>} recordings for the id (rescans once on miss).
1355
+ * @private
1356
+ */
1357
+ async lookupRecordings(sessionId) {
1358
+ let list = this.byId.get(sessionId)
1359
+ if (list === undefined && this.scanned && Date.now() - this.lastScanAt >= SCAN_COOLDOWN_MS) {
1360
+ await this.scan()
1361
+ list = this.byId.get(sessionId)
1362
+ }
1363
+ return list ?? []
1364
+ }
1365
+
1366
+ /**
1367
+ * Reserve a brand-new journal incarnation with an exclusive create.
1368
+ * @param {string} id session id.
1369
+ * @param {string | null} owner owner.
1370
+ * @param {{ title: string, transport: 'ssh' | 'telnet', host: string, port: number, username: string, createdAt: number }} meta metadata.
1371
+ * @returns {Promise<Recording | undefined>} the reserved recording.
1372
+ * @private
1373
+ */
1374
+ async reserveJournal(id, owner, meta) {
1375
+ for (let attempt = 0; attempt < MAX_RESERVE_ATTEMPTS; attempt += 1) {
1376
+ const file = join(this.dir, `${safeSessionFileName(id)}${INCARNATION_SEPARATOR}${randomUUID()}.ndjson`)
1377
+ let handle
1378
+ try {
1379
+ handle = await open(file, 'wx', 0o600)
1380
+ } catch (error) {
1381
+ if (error?.code === 'EEXIST') continue
1382
+ this.warn(`cannot reserve history journal for ${id}`, error)
1383
+ return undefined
1384
+ }
1385
+ try {
1386
+ /** @type {Record<string, unknown>} */
1387
+ const header = {
1388
+ [META_MARKER]: 'journal',
1389
+ version: META_VERSION,
1390
+ id: id.slice(0, 128),
1391
+ owner,
1392
+ title: meta.title,
1393
+ transport: meta.transport,
1394
+ host: meta.host,
1395
+ port: meta.port,
1396
+ username: meta.username,
1397
+ createdAt: meta.createdAt,
1398
+ }
1399
+ await handle.writeFile(`${JSON.stringify(header)}\n`, 'utf8')
1400
+ await handle.sync()
1401
+ const info = await handle.stat()
1402
+ /** @type {Recording} */
1403
+ const recording = {
1404
+ id: id.slice(0, 128),
1405
+ historyId: historyIdOf(file),
1406
+ owner,
1407
+ journal: file,
1408
+ title: meta.title,
1409
+ transport: meta.transport,
1410
+ host: meta.host,
1411
+ port: meta.port,
1412
+ username: meta.username,
1413
+ createdAt: meta.createdAt,
1414
+ bytes: 0,
1415
+ lastTs: meta.createdAt,
1416
+ mtime: info.mtimeMs,
1417
+ fileBytes: info.size,
1418
+ }
1419
+ return recording
1420
+ } catch (error) {
1421
+ this.warn(`cannot initialize history journal for ${id}`, error)
1422
+ // Never leave a headerless/partial reservation that later looks like an
1423
+ // unclosed orphan on restart.
1424
+ try {
1425
+ await rm(file, { force: true })
1426
+ } catch {
1427
+ // best effort; the file has no valid header and stays fail-closed
1428
+ }
1429
+ return undefined
1430
+ } finally {
1431
+ try {
1432
+ await handle.close()
1433
+ } catch {
1434
+ // the reservation already exists; a close failure is harmless
1435
+ }
1436
+ }
1437
+ }
1438
+ this.warn(`cannot reserve a unique history journal for ${id} after ${MAX_RESERVE_ATTEMPTS} attempts`)
1439
+ return undefined
1440
+ }
1441
+
1442
+ /**
1443
+ * Apply retention/cap internally (no `ensureReady`, so `init()` can call it).
1444
+ * @param {number} [now] epoch ms.
1445
+ * @returns {Promise<void>} completion.
1446
+ * @private
1447
+ */
1448
+ async pruneRecordings(now) {
1449
+ const at = typeof now === 'number' && Number.isFinite(now) ? now : Date.now()
1450
+ const cutoff = at - this.retentionMs
1451
+ const activeJournals = new Set([...this.active.values()].map((state) => state.entry.journal))
1452
+ const all = [...this.recordings.values()].sort(newestFirst)
1453
+ let preservedOpen = 0
1454
+ for (const recording of all) {
1455
+ if (activeJournals.has(recording.journal)) continue
1456
+ // Without a cross-process lease we cannot prove that an unclosed journal
1457
+ // has no live writer elsewhere. Preserve it: deleting a live file is worse
1458
+ // than retaining a crashed incarnation until a human/retention decision.
1459
+ if (recording.closedAt === undefined) {
1460
+ preservedOpen += 1
1461
+ continue
1462
+ }
1463
+ let diskMtime = 0
1464
+ try {
1465
+ diskMtime = (await stat(recording.journal)).mtimeMs
1466
+ recording.mtime = diskMtime
1467
+ } catch {
1468
+ diskMtime = typeof recording.mtime === 'number' ? recording.mtime : 0
1469
+ }
1470
+ if (Math.max(retentionActivity(recording), diskMtime) < cutoff) await this.removeRecording(recording)
1471
+ }
1472
+ const remaining = [...this.recordings.values()]
1473
+ .filter((recording) => !activeJournals.has(recording.journal) && recording.closedAt !== undefined)
1474
+ // Refresh mtime before ordering: a recent external write must protect a
1475
+ // journal even when its last output timestamp is old.
1476
+ for (const recording of remaining) {
1477
+ try {
1478
+ recording.mtime = (await stat(recording.journal)).mtimeMs
1479
+ } catch {
1480
+ // keep the last known mtime
1481
+ }
1482
+ }
1483
+ remaining.sort((left, right) => retentionActivity(right) - retentionActivity(left))
1484
+ if (remaining.length > this.maxSessions) {
1485
+ for (const recording of remaining.slice(this.maxSessions)) await this.removeRecording(recording)
1486
+ }
1487
+ if (preservedOpen > 0) {
1488
+ this.warn(`preserved ${preservedOpen} unclosed journal(s) because no cross-process activity lease is available`)
1489
+ }
285
1490
  }
286
1491
 
287
1492
  /**
288
- * Flush and mark a session closed. The journal and catalog entry stay for
289
- * `listSessions` / `query`.
290
- * @param {string} sessionId session id.
291
- * @param {{ closedAt?: number }} [info] close details.
1493
+ * Delete one attributed journal (retention/cap only; legacy is untouched).
1494
+ * @param {Recording} recording recording.
292
1495
  * @returns {Promise<void>} completion.
1496
+ * @private
293
1497
  */
294
- async closeSession(sessionId, info) {
295
- if (this.disposed) return
296
- await this.ensureReady()
297
- const id = typeof sessionId === 'string' ? sessionId : ''
298
- const state = this.active.get(id)
299
- if (state !== undefined) {
300
- await this.writePending(state)
301
- if (state.timer !== undefined) {
302
- clearTimeout(state.timer)
303
- state.timer = undefined
304
- }
305
- this.active.delete(id)
1498
+ async removeRecording(recording) {
1499
+ this.recordings.delete(recording.journal)
1500
+ if (typeof recording.historyId === 'string') this.byHistory.delete(recording.historyId)
1501
+ const list = this.byId.get(recording.id)
1502
+ if (list !== undefined) {
1503
+ const next = list.filter((entry) => entry !== recording)
1504
+ if (next.length === 0) this.byId.delete(recording.id)
1505
+ else this.byId.set(recording.id, next)
1506
+ }
1507
+ try {
1508
+ await rm(recording.journal, { force: true })
1509
+ } catch (error) {
1510
+ this.warn(`cannot remove history for ${recording.id}`, error)
306
1511
  }
307
- this.orphans.delete(id)
308
- const entry = this.catalog.get(id)
309
- if (entry === undefined) return
310
- const closedAt = info !== null && typeof info === 'object' && typeof info.closedAt === 'number' && Number.isFinite(info.closedAt)
311
- ? Math.floor(info.closedAt)
312
- : Date.now()
313
- entry.closedAt = closedAt
314
- await this.saveIndex()
315
- }
316
-
317
- /**
318
- * Catalog listing, newest activity first.
319
- * @param {{ limit?: number, since?: number, until?: number }} [query] filter.
320
- * @returns {Promise<CatalogEntry[]>} catalog entries (copies).
321
- */
322
- async listSessions(query = {}) {
323
- await this.ensureReady()
324
- const options = query !== null && typeof query === 'object' ? query : {}
325
- const limit = boundInteger(options.limit, 100, 1, 1000)
326
- const since = typeof options.since === 'number' && Number.isFinite(options.since) ? options.since : -Infinity
327
- const until = typeof options.until === 'number' && Number.isFinite(options.until) ? options.until : Infinity
328
- const entries = [...this.catalog.values()].filter((entry) => {
329
- const last = typeof entry.lastTs === 'number' ? entry.lastTs : entry.createdAt
330
- return last >= since && entry.createdAt <= until
331
- })
332
- entries.sort((left, right) => activity(right) - activity(left))
333
- return entries.slice(0, limit).map((entry) => publicEntry(entry))
334
1512
  }
335
1513
 
336
1514
  /**
337
- * Search one session's journal.
338
- *
339
- * At most the last `maxBytes` (default 8 MiB) of the file is scanned; a
340
- * partial first line produced by that tail cut is discarded. Corrupt or
341
- * partially written NDJSON lines are skipped rather than failing the query.
342
- * Without `search`, the most recent `maxMatches` lines are returned.
343
- * @param {{ sessionId?: string, since?: number, until?: number, search?: string, context?: number, maxMatches?: number, maxBytes?: number }} query query.
1515
+ * Run the journal-tail search shared by attributed and legacy reads.
1516
+ * @param {string} file journal path.
1517
+ * @param {CatalogEntry} entry public entry.
1518
+ * @param {{ since?: number, until?: number, search?: string, context?: number, maxMatches?: number, maxBytes?: number }} [query] query.
344
1519
  * @returns {Promise<HistoryQueryResult>} matches and scan bookkeeping.
1520
+ * @private
345
1521
  */
346
- async query(query = {}) {
347
- await this.ensureReady()
1522
+ async searchJournal(file, entry, query = {}) {
348
1523
  const options = query !== null && typeof query === 'object' ? query : {}
349
- const sessionId = typeof options.sessionId === 'string' ? options.sessionId : ''
350
1524
  /** @type {HistoryQueryResult} */
351
1525
  const result = { matches: [], scannedBytes: 0, truncated: false }
352
1526
  if (this.dir.length === 0) return result
353
- const entry = this.catalog.get(sessionId)
354
- // A live session may still hold buffered bytes: flush so the query sees them.
355
- if (this.active.has(sessionId)) await this.flush(sessionId)
356
- const file = this.fileFor(sessionId)
1527
+ const maxBytes = boundInteger(options.maxBytes, DEFAULT_QUERY_MAX_BYTES, 256, 256 * 1024 * 1024)
357
1528
  let buffer
358
1529
  try {
359
- buffer = await readFile(file)
1530
+ const info = await stat(file)
1531
+ const start = info.size > maxBytes ? info.size - maxBytes : 0
1532
+ const length = info.size - start
1533
+ if (info.size > maxBytes) result.truncated = true
1534
+ const handle = await open(file, 'r')
1535
+ try {
1536
+ const allocated = Buffer.allocUnsafe(length)
1537
+ let offset = 0
1538
+ while (offset < length) {
1539
+ const { bytesRead } = await handle.read(allocated, offset, length - offset, start + offset)
1540
+ if (bytesRead === 0) break
1541
+ offset += bytesRead
1542
+ }
1543
+ buffer = allocated.subarray(0, offset)
1544
+ } finally {
1545
+ await handle.close()
1546
+ }
360
1547
  } catch (error) {
361
- if (error?.code !== 'ENOENT') this.warn(`cannot read history for ${sessionId}`, error)
1548
+ if (error?.code !== 'ENOENT') this.warn(`cannot read history for ${entry?.id ?? 'unknown session'}`, error)
362
1549
  return withEntry(result, entry)
363
1550
  }
364
1551
 
365
- const maxBytes = boundInteger(options.maxBytes, DEFAULT_QUERY_MAX_BYTES, 256, 256 * 1024 * 1024)
366
1552
  let scanStart = 0
367
- if (buffer.length > maxBytes) {
368
- scanStart = buffer.length - maxBytes
369
- result.truncated = true
370
- const newline = buffer.indexOf(0x0a, scanStart)
1553
+ if (result.truncated === true) {
1554
+ // `buffer` starts at the tail cut; discard a partial first line.
1555
+ const newline = buffer.indexOf(0x0a)
371
1556
  scanStart = newline === -1 ? buffer.length : newline + 1
372
1557
  }
373
1558
  const scanBuffer = buffer.subarray(scanStart)
@@ -419,7 +1604,6 @@ export class HistoryStore {
419
1604
  } else {
420
1605
  /** @type {HistoryMatch[]} */
421
1606
  const pendingAfter = []
422
- let stopped = false
423
1607
  for (let index = 0; index < records.length; index += 1) {
424
1608
  const record = records[index]
425
1609
  for (const match of pendingAfter) {
@@ -432,12 +1616,11 @@ export class HistoryStore {
432
1616
  if (!pattern.test(record.text)) continue
433
1617
  if (matches.length >= maxMatches) {
434
1618
  result.truncated = true
435
- stopped = true
436
1619
  break
437
1620
  }
438
1621
  /** @type {HistoryMatch} */
439
1622
  const match = {
440
- at: timestampAt(boundaries, record.offset),
1623
+ at: timestampAt(boundaries, records[index].offset),
441
1624
  line: record.text,
442
1625
  before: [],
443
1626
  after: [],
@@ -446,106 +1629,31 @@ export class HistoryStore {
446
1629
  matches.push(match)
447
1630
  if (context > 0) pendingAfter.push(match)
448
1631
  }
449
- if (stopped) {
450
- // Nothing extra to report beyond the truncation flag already set.
451
- }
452
1632
  }
453
1633
 
454
1634
  result.matches = matches
455
1635
  return withEntry(result, entry)
456
1636
  }
457
1637
 
458
- /**
459
- * Apply retention and the catalog size cap, deleting both catalog entries and
460
- * journal files. Safe to call at any time.
461
- * @param {number} [now] epoch ms (default: now).
462
- * @returns {Promise<void>} completion.
463
- */
464
- async prune(now) {
465
- if (this.disposed) return
466
- const at = typeof now === 'number' && Number.isFinite(now) ? now : Date.now()
467
- const cutoff = at - this.retentionMs
468
- let changed = false
469
- for (const [id, entry] of [...this.catalog]) {
470
- // A live session is not retention-pruned: its writer still owns the file.
471
- if (this.active.has(id)) continue
472
- const last = typeof entry.lastTs === 'number' ? entry.lastTs : entry.createdAt
473
- if (last < cutoff) {
474
- this.catalog.delete(id)
475
- this.orphans.delete(id)
476
- changed = true
477
- await this.removeFile(id)
478
- }
479
- }
480
- if (this.catalog.size > this.maxSessions) {
481
- const sorted = [...this.catalog.values()].sort((left, right) => activity(right) - activity(left))
482
- for (const entry of sorted.slice(this.maxSessions)) {
483
- this.catalog.delete(entry.id)
484
- this.discardState(entry.id)
485
- this.orphans.delete(entry.id)
486
- changed = true
487
- await this.removeFile(entry.id)
488
- }
489
- }
490
- if (changed) await this.saveIndex()
491
- }
492
-
493
- /**
494
- * Flush everything and stop timers. Idempotent; never throws.
495
- * @returns {Promise<void>} completion.
496
- */
497
- async dispose() {
498
- if (this.disposed) return
499
- this.disposed = true
500
- const states = [...this.active.values()]
501
- for (const state of states) {
502
- if (state.timer !== undefined) {
503
- clearTimeout(state.timer)
504
- state.timer = undefined
505
- }
506
- }
507
- await Promise.allSettled(states.map((state) => this.writePending(state)))
508
- this.active.clear()
509
- this.orphans.clear()
510
- await this.saveIndex()
511
- }
512
-
513
- /**
514
- * @param {string} id session id.
515
- * @returns {string} journal path.
516
- */
517
- fileFor(id) {
518
- return join(this.dir, `${safeSessionFileName(id)}.ndjson`)
519
- }
520
-
521
- /**
522
- * Await `init()`, running it on first use.
523
- * @returns {Promise<void>} completion.
524
- */
525
- async ensureReady() {
526
- if (this.ready === undefined) await this.init()
527
- else await this.ready
528
- }
529
-
530
1638
  /**
531
1639
  * Hold output for a session whose `openSession()` has not finished yet.
532
- * Bounded by session count and 64 KiB per session, so a session that never
533
- * opens cannot grow the store.
534
1640
  * @param {string} id session id.
1641
+ * @param {string | null} owner owner.
535
1642
  * @param {PendingRecord} record decoded record.
536
1643
  * @returns {void}
537
1644
  * @private
538
1645
  */
539
- bufferOrphan(id, record) {
1646
+ bufferOrphan(id, owner, record) {
540
1647
  if (id.length === 0) return
541
- let orphan = this.orphans.get(id)
1648
+ const key = orphanKeyFor(id, owner)
1649
+ let orphan = this.orphans.get(key)
542
1650
  if (orphan === undefined) {
543
1651
  if (this.orphans.size >= MAX_ORPHAN_SESSIONS) {
544
1652
  const oldest = this.orphans.keys().next()
545
1653
  if (oldest.done !== true) this.orphans.delete(oldest.value)
546
1654
  }
547
1655
  orphan = { records: [], bytes: 0 }
548
- this.orphans.set(id, orphan)
1656
+ this.orphans.set(key, orphan)
549
1657
  this.log('debug', `[aiterm] history: buffering output for not-yet-open session ${id}`)
550
1658
  }
551
1659
  if (orphan.bytes + record.size > FLUSH_THRESHOLD_BYTES) return
@@ -553,6 +1661,45 @@ export class HistoryStore {
553
1661
  orphan.bytes += record.size
554
1662
  }
555
1663
 
1664
+ /**
1665
+ * Drop every pre-open buffer for an id when the session closes.
1666
+ * @param {string} id session id.
1667
+ * @returns {void}
1668
+ * @private
1669
+ */
1670
+ dropOrphans(id, owner) {
1671
+ if (owner !== undefined) {
1672
+ this.orphans.delete(orphanKeyFor(id, owner))
1673
+ return
1674
+ }
1675
+ const suffix = `\u0000${id}`
1676
+ for (const key of [...this.orphans.keys()]) {
1677
+ if (key.endsWith(suffix)) this.orphans.delete(key)
1678
+ }
1679
+ }
1680
+
1681
+ /**
1682
+ * Commit a close intent held by an active writer. The active writer is only
1683
+ * removed after the metadata append succeeds; on failure it stays so the retry
1684
+ * timer can try again, and AI remains fail-closed meanwhile.
1685
+ * @param {ActiveSession} state session state.
1686
+ * @returns {Promise<void>} completion.
1687
+ * @private
1688
+ */
1689
+ async commitStateClose(state) {
1690
+ const intent = state.pendingClose
1691
+ if (intent === undefined) return
1692
+ if (state.pending.length > 0) return
1693
+ if (await this.appendCloseFor(state.entry, intent)) {
1694
+ state.pendingClose = undefined
1695
+ if (state.entry.historyId !== undefined) this.pendingCloseRecords.delete(state.entry.historyId)
1696
+ this.active.delete(state.id)
1697
+ return
1698
+ }
1699
+ state.retryDelayMs = Math.min(60_000, Math.max(1000, (state.retryDelayMs || 1000) * 2))
1700
+ if (!this.disposed) this.scheduleFlush(state, state.retryDelayMs)
1701
+ }
1702
+
556
1703
  /**
557
1704
  * Arm or re-arm a flush timer for a session.
558
1705
  * @param {ActiveSession} state session state.
@@ -573,7 +1720,20 @@ export class HistoryStore {
573
1720
  }
574
1721
 
575
1722
  /**
576
- * Append buffered records to the journal, serialized per session.
1723
+ * Low-level append used by the buffered writer. Kept as a method so failure
1724
+ * behavior (retention of unsaved bytes, close fail-closed) can be exercised
1725
+ * deterministically by tests without touching real files.
1726
+ * @param {string} file journal path.
1727
+ * @param {Buffer} data encoded NDJSON batch.
1728
+ * @returns {Promise<void>} completion.
1729
+ */
1730
+ async appendJournal(file, data) {
1731
+ await appendFile(file, data, { mode: 0o600 })
1732
+ }
1733
+
1734
+ /**
1735
+ * Append buffered records to this incarnation's journal, serialized per
1736
+ * session. Only the state's own file is ever touched.
577
1737
  * @param {ActiveSession} state session state.
578
1738
  * @returns {Promise<void>} completion.
579
1739
  * @private
@@ -584,37 +1744,158 @@ export class HistoryStore {
584
1744
  clearTimeout(state.timer)
585
1745
  state.timer = undefined
586
1746
  }
587
- if (state.pending.length === 0) return
1747
+ if (state.corrupt) return
1748
+ if (state.pending.length === 0) {
1749
+ if (state.pendingClose !== undefined) await this.commitStateClose(state)
1750
+ return
1751
+ }
588
1752
  const batch = state.pending
589
1753
  state.pending = []
590
1754
  state.pendingBytes = 0
591
- let payload = ''
592
- let payloadBytes = 0
593
- for (const record of batch) {
594
- payload += `${JSON.stringify({ t: record.t, d: record.d })}\n`
595
- payloadBytes += record.size
596
- }
597
- const data = Buffer.from(payload, 'utf8')
598
1755
  try {
599
- await appendFile(state.file, data, { mode: 0o600 })
600
- state.fileBytes += data.length
601
- state.entry.bytes += payloadBytes
1756
+ await this.appendBatch(state, batch)
1757
+ const wasFailing = state.writeFailures > 0
1758
+ state.writeFailures = 0
1759
+ state.retryDelayMs = 0
1760
+ // Keep the alert sticky once bytes have actually been dropped.
1761
+ state.degraded = state.droppedBytes > 0
1762
+ if (wasFailing) {
1763
+ this.warn(`history writer recovered for ${state.id} (dropped=${state.droppedBytes})`)
1764
+ }
602
1765
  } catch (error) {
603
- this.warn(`cannot append history for ${state.id}`, error)
604
- return
605
- }
606
- if (state.fileBytes > this.maxBytesPerSession) {
607
- await this.truncateSession(state)
1766
+ const payloadBytes = batch.reduce((sum, record) => sum + record.size, 0)
1767
+ // Keep the bytes for a retry (and for a later close that must not
1768
+ // stamp a permission while the data is still unsaved), but bound the
1769
+ // buffer so a permanent disk failure cannot grow memory without limit.
1770
+ state.pending = [...batch, ...state.pending]
1771
+ state.pendingBytes += payloadBytes
1772
+ this.trimPending(state)
1773
+ if (error?.rollbackOk === false) {
1774
+ // The partial line could not be truncated. Do not append more bytes
1775
+ // or pretend the journal is healthy; fail closed and leave it for a
1776
+ // human/retention decision.
1777
+ state.corrupt = true
1778
+ state.degraded = true
1779
+ this.warn(`history journal ${state.id} is corrupt after a failed rollback; writes disabled`, error)
1780
+ return
1781
+ }
1782
+ state.writeFailures += 1
1783
+ state.degraded = true
1784
+ const now = Date.now()
1785
+ if (state.writeFailures === 1 || now - state.lastFailureLogAt >= FAILURE_LOG_INTERVAL_MS) {
1786
+ state.lastFailureLogAt = now
1787
+ this.warn(
1788
+ `cannot append history for ${state.id} (failures=${state.writeFailures}, pending=${state.pendingBytes}, dropped=${state.droppedBytes})`,
1789
+ error,
1790
+ )
1791
+ }
1792
+ state.retryDelayMs = Math.min(60_000, Math.max(1000, (state.retryDelayMs || 1000) * 2))
1793
+ if (!this.disposed) this.scheduleFlush(state, state.retryDelayMs)
608
1794
  return
609
1795
  }
610
- await this.saveIndex()
1796
+ if (state.fileBytes > this.maxBytesPerSession) await this.truncateSession(state)
1797
+ if (state.pendingClose !== undefined && state.pending.length === 0) await this.commitStateClose(state)
611
1798
  }
612
1799
  state.chain = state.chain.then(task, task)
613
1800
  return state.chain
614
1801
  }
615
1802
 
616
1803
  /**
617
- * Rewrite a journal to its tail, keeping complete records up to the byte cap.
1804
+ * Append one batch inside a rollback boundary. The file is truncated back to
1805
+ * its size before this batch if any write/sync fails, so a partial NDJSON line
1806
+ * is never left for the next retry to duplicate. On rollback failure the error
1807
+ * carries `rollbackOk=false` and the writer is marked corrupt.
1808
+ * @param {ActiveSession} state session state.
1809
+ * @param {PendingRecord[]} batch records to append.
1810
+ * @returns {Promise<void>} completion.
1811
+ * @private
1812
+ */
1813
+ async appendBatch(state, batch) {
1814
+ const startBytes = state.fileBytes
1815
+ let handle
1816
+ let payloadBytes = 0
1817
+ let lineBytes = 0
1818
+ try {
1819
+ handle = await this.openAppendHandle(state.file)
1820
+ for (const record of batch) {
1821
+ const line = Buffer.from(`${JSON.stringify({ t: record.t, d: record.d })}\n`, 'utf8')
1822
+ await this.writeHandle(handle, line)
1823
+ lineBytes += line.length
1824
+ payloadBytes += record.size
1825
+ }
1826
+ await handle.sync()
1827
+ } catch (error) {
1828
+ let rollbackOk = true
1829
+ if (handle !== undefined) {
1830
+ try {
1831
+ await this.truncateHandle(handle, startBytes)
1832
+ await handle.sync()
1833
+ } catch (rollbackError) {
1834
+ rollbackOk = false
1835
+ this.warn(`cannot roll back a partial history append for ${state.id}`, rollbackError)
1836
+ }
1837
+ }
1838
+ if (error !== null && typeof error === 'object') {
1839
+ error.rollbackOk = rollbackOk
1840
+ error.payloadBytes = payloadBytes
1841
+ }
1842
+ throw error
1843
+ } finally {
1844
+ if (handle !== undefined) {
1845
+ try {
1846
+ await handle.close()
1847
+ } catch {
1848
+ // close failure does not change the committed bytes
1849
+ }
1850
+ }
1851
+ }
1852
+ state.fileBytes = startBytes + lineBytes
1853
+ state.entry.bytes += payloadBytes
1854
+ state.entry.mtime = Date.now()
1855
+ }
1856
+
1857
+ /**
1858
+ * Open an append handle (overridable for deterministic partial-write tests).
1859
+ * @param {string} file journal path.
1860
+ * @returns {Promise<import('node:fs/promises').FileHandle>} handle.
1861
+ */
1862
+ async openAppendHandle(file) {
1863
+ return open(file, 'a', 0o600)
1864
+ }
1865
+
1866
+ /**
1867
+ * Write all bytes, handling partial `FileHandle.write` results.
1868
+ * @param {import('node:fs/promises').FileHandle} handle handle.
1869
+ * @param {Buffer} buffer data.
1870
+ * @returns {Promise<void>} completion.
1871
+ */
1872
+ async writeHandle(handle, buffer) {
1873
+ let offset = 0
1874
+ while (offset < buffer.length) {
1875
+ const { bytesWritten } = await handle.write(buffer, offset, buffer.length - offset)
1876
+ if (!Number.isInteger(bytesWritten) || bytesWritten <= 0) {
1877
+ const error = new Error('write made no progress')
1878
+ error.code = 'ENOSPC'
1879
+ throw error
1880
+ }
1881
+ offset += bytesWritten
1882
+ }
1883
+ }
1884
+
1885
+ /**
1886
+ * Roll a failed append back to its pre-batch size.
1887
+ * @param {import('node:fs/promises').FileHandle} handle handle.
1888
+ * @param {number} size byte offset.
1889
+ * @returns {Promise<void>} completion.
1890
+ */
1891
+ async truncateHandle(handle, size) {
1892
+ await handle.truncate(size)
1893
+ }
1894
+
1895
+ /**
1896
+ * Rewrite a journal to its tail, always preserving the provenance header.
1897
+ * Without the header the data is unusable (fail closed), so a file whose
1898
+ * header cannot be found is left alone.
618
1899
  * @param {ActiveSession} state session state.
619
1900
  * @returns {Promise<void>} completion.
620
1901
  * @private
@@ -629,12 +1910,17 @@ export class HistoryStore {
629
1910
  return
630
1911
  }
631
1912
  const lines = buffer.toString('utf8').split('\n')
1913
+ const headerLine = lines.length > 0 && parseJournalHeader(lines[0]) !== undefined ? lines[0] : undefined
1914
+ if (headerLine === undefined) {
1915
+ this.warn(`refusing to truncate history for ${state.id}: provenance header is missing`)
1916
+ return
1917
+ }
632
1918
  /** @type {string[]} */
633
1919
  const kept = []
634
- let fileBytes = 0
1920
+ let fileBytes = Buffer.byteLength(headerLine, 'utf8') + 1
635
1921
  let payloadBytes = 0
636
1922
  let lastTs = 0
637
- for (let index = lines.length - 1; index >= 0; index -= 1) {
1923
+ for (let index = lines.length - 1; index >= 1; index -= 1) {
638
1924
  const line = lines[index]
639
1925
  if (line.length === 0) continue
640
1926
  const lineBytes = Buffer.byteLength(line, 'utf8') + 1
@@ -648,7 +1934,7 @@ export class HistoryStore {
648
1934
  if (parsed.t > lastTs) lastTs = parsed.t
649
1935
  }
650
1936
  kept.reverse()
651
- const body = kept.length > 0 ? `${kept.join('\n')}\n` : ''
1937
+ const body = `${headerLine}\n${kept.length > 0 ? `${kept.join('\n')}\n` : ''}`
652
1938
  const written = Buffer.byteLength(body, 'utf8')
653
1939
  const temp = `${state.file}.${process.pid}.${Date.now()}.tmp`
654
1940
  try {
@@ -665,54 +1951,9 @@ export class HistoryStore {
665
1951
  }
666
1952
  state.fileBytes = written
667
1953
  state.entry.bytes = payloadBytes
1954
+ state.entry.mtime = Date.now()
668
1955
  state.entry.truncatedAt = Date.now()
669
1956
  if (lastTs > 0) state.entry.lastTs = lastTs
670
- await this.saveIndex()
671
- }
672
-
673
- /**
674
- * Persist the catalog atomically, serialized behind earlier writes.
675
- * @returns {Promise<void>} completion (errors are logged, not thrown).
676
- * @private
677
- */
678
- saveIndex() {
679
- const payload = { version: CATALOG_VERSION, sessions: [...this.catalog.values()].map((entry) => ({ ...entry })) }
680
- const write = async () => {
681
- try {
682
- await writeJsonAtomic(join(this.dir, INDEX_FILE), payload)
683
- } catch (error) {
684
- this.warn('cannot write history index', error)
685
- }
686
- }
687
- this.indexChain = this.indexChain.then(write, write)
688
- return this.indexChain
689
- }
690
-
691
- /**
692
- * Delete one session's journal file.
693
- * @param {string} id session id.
694
- * @returns {Promise<void>} completion.
695
- * @private
696
- */
697
- async removeFile(id) {
698
- try {
699
- await rm(this.fileFor(id), { force: true })
700
- } catch (error) {
701
- this.warn(`cannot remove history for ${id}`, error)
702
- }
703
- }
704
-
705
- /**
706
- * Drop buffered state for a session (after close or pruning).
707
- * @param {string} id session id.
708
- * @returns {void}
709
- * @private
710
- */
711
- discardState(id) {
712
- const state = this.active.get(id)
713
- if (state === undefined) return
714
- if (state.timer !== undefined) clearTimeout(state.timer)
715
- this.active.delete(id)
716
1957
  }
717
1958
 
718
1959
  /**
@@ -723,7 +1964,11 @@ export class HistoryStore {
723
1964
  * @private
724
1965
  */
725
1966
  warn(message, error) {
726
- const detail = error instanceof Error ? error.message : error === undefined ? '' : String(error)
1967
+ // Prefer a stable error code over a free-form message: Node fs messages
1968
+ // contain absolute paths (including private incarnation journal paths).
1969
+ const detail = typeof error?.code === 'string'
1970
+ ? error.code
1971
+ : error instanceof Error ? error.message : error === undefined ? '' : String(error)
727
1972
  try {
728
1973
  this.log('warn', `[aiterm] history: ${message}${detail.length > 0 ? `: ${detail}` : ''}`)
729
1974
  } catch {
@@ -732,6 +1977,29 @@ export class HistoryStore {
732
1977
  }
733
1978
  }
734
1979
 
1980
+ /**
1981
+ * Normalize an owner for comparison in this store.
1982
+ * @param {unknown} value raw owner.
1983
+ * @returns {string | null} trimmed owner or `null`.
1984
+ */
1985
+ export function normalizeOwnerValue(value) {
1986
+ if (typeof value !== 'string') return null
1987
+ const text = value.trim()
1988
+ if (text.length === 0) return null
1989
+ return text.slice(0, 128)
1990
+ }
1991
+
1992
+ /**
1993
+ * Stable key for pre-open output, scoped to one owner so a failed open cannot
1994
+ * leak bytes into a later incarnation owned by somebody else.
1995
+ * @param {string} id session id.
1996
+ * @param {string | null} owner owner.
1997
+ * @returns {string} key.
1998
+ */
1999
+ function orphanKeyFor(id, owner) {
2000
+ return `${owner === null ? '\u0001null' : owner}\u0000${id}`
2001
+ }
2002
+
735
2003
  /**
736
2004
  * Turn a session id into a safe journal basename (ids come from the registry,
737
2005
  * but this is the only place a string reaches a filesystem path).
@@ -746,13 +2014,185 @@ function safeSessionFileName(id) {
746
2014
  }
747
2015
 
748
2016
  /**
749
- * @param {CatalogEntry} entry catalog entry.
2017
+ * Whether a directory entry is a new-format incarnation journal.
2018
+ * Legacy files are `<id>.ndjson` (never enumerated as attributed data).
2019
+ * @param {string} name file name.
2020
+ * @returns {boolean} true for new-format journals.
2021
+ */
2022
+ function isIncarnationName(name) {
2023
+ return name.endsWith('.ndjson') && name.includes(INCARNATION_SEPARATOR)
2024
+ }
2025
+
2026
+ /**
2027
+ * Read the first line of a file without slurping a large journal.
2028
+ * @param {string} file absolute path.
2029
+ * @returns {Promise<string>} first line (or the partial file when there is no newline).
2030
+ */
2031
+ async function readFirstLine(file) {
2032
+ const handle = await open(file, 'r')
2033
+ try {
2034
+ const buffer = Buffer.allocUnsafe(MAX_HEADER_BYTES)
2035
+ const { bytesRead } = await handle.read(buffer, 0, MAX_HEADER_BYTES, 0)
2036
+ const chunk = buffer.subarray(0, bytesRead)
2037
+ const newline = chunk.indexOf(0x0a)
2038
+ return chunk.subarray(0, newline === -1 ? chunk.length : newline).toString('utf8')
2039
+ } finally {
2040
+ try {
2041
+ await handle.close()
2042
+ } catch {
2043
+ // read handle cleanup is best effort
2044
+ }
2045
+ }
2046
+ }
2047
+
2048
+ /**
2049
+ * Read the last lines of a journal for close metadata and newest timestamp.
2050
+ * @param {string} file absolute path.
2051
+ * @param {number} size file size.
2052
+ * @returns {Promise<string[]>} complete tail lines.
2053
+ */
2054
+ async function readTailLines(file, size) {
2055
+ if (size <= 0) return []
2056
+ const start = Math.max(0, size - TAIL_READ_BYTES)
2057
+ const handle = await open(file, 'r')
2058
+ try {
2059
+ const buffer = Buffer.allocUnsafe(size - start)
2060
+ const { bytesRead } = await handle.read(buffer, 0, buffer.length, start)
2061
+ let text = buffer.subarray(0, bytesRead).toString('utf8')
2062
+ // A tail cut starts mid-line; drop that partial first line.
2063
+ if (start > 0) {
2064
+ const newline = text.indexOf('\n')
2065
+ text = newline === -1 ? '' : text.slice(newline + 1)
2066
+ }
2067
+ return text.split('\n').filter((line) => line.trim().length > 0)
2068
+ } finally {
2069
+ try {
2070
+ await handle.close()
2071
+ } catch {
2072
+ // read handle cleanup is best effort
2073
+ }
2074
+ }
2075
+ }
2076
+
2077
+ /**
2078
+ * Parse a journal header line.
2079
+ * @param {string} line first line.
2080
+ * @returns {{ id: string, owner: string | null, title: string, transport: 'ssh' | 'telnet', host: string, port: number, username: string, createdAt: number } | undefined} metadata.
2081
+ */
2082
+ function parseJournalHeader(line) {
2083
+ const parsed = parseJsonObject(line)
2084
+ if (parsed === undefined) return undefined
2085
+ if (parsed[META_MARKER] !== 'journal') return undefined
2086
+ if (parsed.version !== META_VERSION) return undefined
2087
+ if (typeof parsed.id !== 'string' || parsed.id.length === 0) return undefined
2088
+ const ownerValid = parsed.owner === null || typeof parsed.owner === 'string'
2089
+ if (!ownerValid) return undefined
2090
+ let owner = null
2091
+ if (typeof parsed.owner === 'string') {
2092
+ const text = parsed.owner.trim()
2093
+ // An empty owner string in a header is corruption: an ownerless journal
2094
+ // must say `null`, so this file is left unattributed and fails closed.
2095
+ if (text.length === 0) return undefined
2096
+ owner = text.slice(0, 128)
2097
+ }
2098
+ return {
2099
+ id: parsed.id.slice(0, 128),
2100
+ owner,
2101
+ title: typeof parsed.title === 'string' ? parsed.title.slice(0, 120) : parsed.id.slice(0, 128),
2102
+ transport: parsed.transport === 'telnet' ? 'telnet' : 'ssh',
2103
+ host: typeof parsed.host === 'string' ? parsed.host.slice(0, 253) : '',
2104
+ port: boundInteger(parsed.port, 22, 1, 65_535),
2105
+ username: typeof parsed.username === 'string' ? parsed.username.slice(0, 128) : '',
2106
+ createdAt: finiteInteger(parsed.createdAt, 0),
2107
+ }
2108
+ }
2109
+
2110
+ /**
2111
+ * @param {unknown} value candidate.
2112
+ * @returns {boolean} whether it is a known AI access mode.
2113
+ */
2114
+ function isAiAccess(value) {
2115
+ return value === 'ro' || value === 'wo' || value === 'rw'
2116
+ }
2117
+
2118
+ /**
2119
+ * Parse a JSON object defensively.
2120
+ * @param {string} line input line.
2121
+ * @returns {Record<string, unknown> | undefined} parsed object.
2122
+ */
2123
+ function parseJsonObject(line) {
2124
+ if (typeof line !== 'string' || line.trim().length === 0) return undefined
2125
+ let parsed
2126
+ try {
2127
+ parsed = JSON.parse(line)
2128
+ } catch {
2129
+ return undefined
2130
+ }
2131
+ if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return undefined
2132
+ return /** @type {Record<string, unknown>} */ (parsed)
2133
+ }
2134
+
2135
+ /**
2136
+ * Stable address for one incarnation: its journal basename without extension.
2137
+ * @param {string} journal absolute journal path.
2138
+ * @returns {string} opaque history id.
2139
+ */
2140
+ function historyIdOf(journal) {
2141
+ const base = String(journal).replace(/\\/g, '/').split('/').pop() ?? ''
2142
+ return base.endsWith('.ndjson') ? base.slice(0, -'.ndjson'.length) : base
2143
+ }
2144
+
2145
+ /**
2146
+ * Activity used consistently by retention and the maxSessions cap: the newest of
2147
+ * output timestamp, explicit close time and filesystem mtime. A recently closed
2148
+ * or recently written journal must not be treated as old just because its last
2149
+ * output record was old.
2150
+ * @param {{ createdAt: number, lastTs?: number, closedAt?: number, mtime?: number }} entry recording.
2151
+ * @returns {number} activity timestamp.
2152
+ */
2153
+ function retentionActivity(entry) {
2154
+ return Math.max(
2155
+ activity(entry),
2156
+ typeof entry.closedAt === 'number' ? entry.closedAt : 0,
2157
+ typeof entry.mtime === 'number' ? entry.mtime : 0,
2158
+ )
2159
+ }
2160
+
2161
+ /**
2162
+ * Stable token for a complete filtered page set. A client that pages with an
2163
+ * offset can send it back; a change in any listed identity/activity means the
2164
+ * offsets may have shifted and the UI must reload instead of silently skipping.
2165
+ * @param {Array<Record<string, any>>} entries entries.
2166
+ * @returns {string} short snapshot token.
2167
+ */
2168
+ function pageSnapshot(entries) {
2169
+ const payload = entries.map((entry) => [
2170
+ entry.id ?? '',
2171
+ entry.historyId ?? '',
2172
+ entry.createdAt ?? 0,
2173
+ entry.lastTs ?? 0,
2174
+ entry.closedAt ?? '',
2175
+ ].join('\u0000')).join('\n')
2176
+ return createHash('sha256').update(payload).digest('hex').slice(0, 20)
2177
+ }
2178
+
2179
+ /**
2180
+ * @param {{ createdAt: number, lastTs?: number }} entry entry.
750
2181
  * @returns {number} sortable activity timestamp.
751
2182
  */
752
2183
  function activity(entry) {
753
2184
  return typeof entry.lastTs === 'number' ? entry.lastTs : entry.createdAt
754
2185
  }
755
2186
 
2187
+ /**
2188
+ * @param {{ createdAt: number, lastTs?: number }} left first.
2189
+ * @param {{ createdAt: number, lastTs?: number }} right second.
2190
+ * @returns {number} comparator, newest first.
2191
+ */
2192
+ function newestFirst(left, right) {
2193
+ return activity(right) - activity(left) || right.createdAt - left.createdAt
2194
+ }
2195
+
756
2196
  /**
757
2197
  * @param {unknown} raw catalog value from disk.
758
2198
  * @returns {CatalogEntry | undefined} normalized entry.
@@ -816,9 +2256,9 @@ function parseRecord(line) {
816
2256
  */
817
2257
  function compileSearch(search) {
818
2258
  try {
819
- return new RegExp(search)
2259
+ return new RegExp(search, 'i')
820
2260
  } catch {
821
- return new RegExp(search.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
2261
+ return new RegExp(search.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i')
822
2262
  }
823
2263
  }
824
2264
 
@@ -873,10 +2313,9 @@ function timestampAt(boundaries, offset) {
873
2313
  /**
874
2314
  * Copy a catalog entry for public consumption.
875
2315
  *
876
- * `truncatedAt` is recorded in `index.json` (§10: 记 truncatedAt) but is not
877
- * part of the `CatalogEntry` contract and the history tool schema rejects
878
- * undeclared fields (`additionalProperties: false`), so it stays internal.
879
- * @param {CatalogEntry} entry catalog entry.
2316
+ * `owner`, `aiAccess` and `journal` are private provenance and are deliberately
2317
+ * dropped here: no tool result or browser payload may reveal them.
2318
+ * @param {CatalogEntry | Recording} entry catalog entry or recording.
880
2319
  * @returns {CatalogEntry} a plain copy of the documented shape.
881
2320
  */
882
2321
  function publicEntry(entry) {
@@ -892,6 +2331,7 @@ function publicEntry(entry) {
892
2331
  bytes: entry.bytes,
893
2332
  lastTs: entry.lastTs,
894
2333
  }
2334
+ if (entry.historyId !== undefined) copy.historyId = entry.historyId
895
2335
  if (entry.closedAt !== undefined) copy.closedAt = entry.closedAt
896
2336
  return copy
897
2337
  }