@aisac/cli 0.0.0-stage → 0.4.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. package/README.md +159 -2
  2. package/dist/assets/claude/.claude-plugin/plugin.json +147 -0
  3. package/dist/assets/claude/hooks/context-compaction.ts +6930 -0
  4. package/dist/assets/claude/hooks/hooks.json +3 -0
  5. package/dist/assets/claude/hooks/native-host-contract-runtime.ts +18 -0
  6. package/dist/assets/claude/hooks/native-host-contract.test.ts +51 -0
  7. package/dist/assets/claude/hooks/provider-window.js +263 -0
  8. package/dist/assets/claude/hooks/state-fitting.d.mts +47 -0
  9. package/dist/assets/claude/hooks/state-fitting.mjs +324 -0
  10. package/dist/assets/codex-context-compaction.mjs +4689 -0
  11. package/dist/assets/context-selection-fitting.mjs +194 -0
  12. package/dist/assets/context-state-fitting.mjs +324 -0
  13. package/dist/assets/context-telemetry-reporter.mjs +305 -0
  14. package/dist/assets/jev-paid-pilot-terminal.mjs +1066 -0
  15. package/dist/claude-checkpoint.mjs +1338 -0
  16. package/dist/claude-compatibility.mjs +506 -0
  17. package/dist/claude-observation.mjs +1338 -0
  18. package/dist/cli.mjs +736 -0
  19. package/dist/codex-compatibility.mjs +481 -0
  20. package/dist/codex-diagnostics.mjs +447 -0
  21. package/dist/codex-permissions.mjs +590 -0
  22. package/dist/codex-protocol-fingerprint.json +131 -0
  23. package/dist/context-telemetry.mjs +257 -0
  24. package/dist/engineering.mjs +190 -0
  25. package/dist/launch.mjs +646 -0
  26. package/dist/mcp.mjs +962 -0
  27. package/dist/monitor.mjs +133 -0
  28. package/dist/package.json +5 -0
  29. package/dist/platform.mjs +126 -0
  30. package/dist/policy.mjs +218 -0
  31. package/dist/state.mjs +408 -0
  32. package/dist/telemetry-report.mjs +133 -0
  33. package/package.json +24 -4
@@ -0,0 +1,4689 @@
1
+ #!/usr/bin/env node
2
+
3
+ import {
4
+ chmod,
5
+ link as hardlink,
6
+ lstat,
7
+ mkdir,
8
+ open,
9
+ readFile,
10
+ readlink,
11
+ readdir,
12
+ rename,
13
+ unlink,
14
+ writeFile,
15
+ } from 'node:fs/promises';
16
+ import { constants as fsConstants } from 'node:fs';
17
+ import { spawn } from 'node:child_process';
18
+ import { createHash, randomUUID } from 'node:crypto';
19
+ import { basename, dirname, relative, resolve } from 'node:path';
20
+ import { StringDecoder } from 'node:string_decoder';
21
+ import { pathToFileURL } from 'node:url';
22
+ import { createTelemetryReporter, TELEMETRY_TIMEOUT_MS } from './context-telemetry-reporter.mjs';
23
+ import { preflightSelectionState } from './context-selection-fitting.mjs';
24
+
25
+ const captureFs = {
26
+ chmod,
27
+ hardlink,
28
+ lstat,
29
+ mkdir,
30
+ open,
31
+ readFile,
32
+ readdir,
33
+ rename,
34
+ unlink,
35
+ writeFile,
36
+ };
37
+
38
+ const DEFAULT_THRESHOLD = 85;
39
+ const COOLDOWN_MS = 60_000;
40
+ const DEFAULT_TIMEOUT_MS = 120_000;
41
+ const MAX_LINE_BYTES = 8 * 1024 * 1024;
42
+ const MAX_CAPTURE_BYTES = 8 * 1024 * 1024;
43
+ const MAX_CAPTURE_PAGE_BYTES = 8 * 1024 * 1024;
44
+ const MAX_CAPTURE_TOTAL_BYTES = 128 * 1024 * 1024;
45
+ const MAX_CAPTURE_PAGES = 32;
46
+ const MAX_CAPTURE_ITEMS = 65_536;
47
+ const MAX_CAPTURE_DIRECTORY_BYTES = 256 * 1024 * 1024;
48
+ const MAX_CAPTURE_STAGING_HEADROOM_BYTES = 16 * 1024 * 1024;
49
+ const MAX_CAPTURE_FILES = 128;
50
+ const MAX_CAPTURE_PUBLICATION_FILE_HEADROOM = MAX_CAPTURE_PAGES + 2;
51
+ const MAX_CAPTURE_PUBLICATION_FILES = MAX_CAPTURE_FILES + MAX_CAPTURE_PUBLICATION_FILE_HEADROOM;
52
+ const CAPTURE_LOCK_WAIT_MS = 1_000;
53
+ const MAX_OWNED_REQUESTS = 1_000;
54
+ const MAX_RETIRED_REQUESTS = 2_000;
55
+ const MAX_CLIENT_REQUEST_BINDINGS = 128;
56
+ const MAX_OWNED_THREAD_IDS = 256;
57
+ const MAX_RECOVERY_ITEMS = 128;
58
+ const MAX_RECOVERY_SOURCE_INDEX = 65_536;
59
+ const MAX_NOTE_BYTES = 128 * 1024;
60
+ const MAX_SELECTION_BYTES = 512 * 1024;
61
+ const MAX_POLICY_BYTES = 8 * 1024;
62
+ const MAX_NOTE_ITEM_CHARS = 16_384;
63
+ const USAGE_FRESHNESS_MS = 60_000;
64
+ const MAX_DIAGNOSTIC_STRING = 128;
65
+ const MAX_DIAGNOSTIC_BYTES = MAX_CAPTURE_DIRECTORY_BYTES;
66
+ const MAX_BUDGET_SNAPSHOT_AGE_MS = 15_000;
67
+ const CONTEXT_ERROR_CODES = new Set([
68
+ 'INVALID_INPUT',
69
+ 'FEATURE_DISABLED',
70
+ 'PAID_PLAN_REQUIRED',
71
+ 'ENTITLEMENT_UNAVAILABLE',
72
+ 'RATE_LIMITED',
73
+ 'PROVIDER_NOT_CONFIGURED',
74
+ 'BUDGET_EXCEEDED',
75
+ 'PROVIDER_TIMEOUT',
76
+ 'PROVIDER_UNAVAILABLE',
77
+ 'INVALID_PROVIDER_RESPONSE',
78
+ ]);
79
+ const CONTEXT_FAILURE_DETAILS = new Set(['state_budget_exceeded', 'shared_admission_denied']);
80
+ const CONTEXT_ADMISSION_REASONS = new Set([
81
+ 'request_replayed',
82
+ 'account_request_limit',
83
+ 'account_token_limit',
84
+ 'global_request_limit',
85
+ 'global_token_limit',
86
+ 'account_in_flight',
87
+ 'database_unavailable',
88
+ ]);
89
+ const SHARED_QUOTA_ADMISSION_REASONS = new Set([
90
+ 'account_request_limit',
91
+ 'account_token_limit',
92
+ 'global_request_limit',
93
+ 'global_token_limit',
94
+ 'account_in_flight',
95
+ ]);
96
+ const DIAGNOSTIC_STAGES = new Set([
97
+ 'capture',
98
+ 'budget',
99
+ 'selection',
100
+ 'notes',
101
+ 'native',
102
+ 'recovery',
103
+ 'transport',
104
+ ]);
105
+ const DIAGNOSTIC_REASONS = new Set([
106
+ 'requested',
107
+ 'completed',
108
+ 'candidate_window_bounded',
109
+ 'candidate_over_bound',
110
+ 'protected_over_bound',
111
+ 'history_unavailable',
112
+ 'stale_snapshot',
113
+ 'unavailable',
114
+ 'admission_denied',
115
+ 'invalid_response',
116
+ 'request_failed',
117
+ 'source_changed',
118
+ 'timeout',
119
+ 'thread_closed',
120
+ 'protocol_error',
121
+ 'capture_size_exceeded',
122
+ 'capture_item_count_exceeded',
123
+ 'private_storage_failed',
124
+ 'storage_capacity_exceeded',
125
+ 'capture_lock_timeout',
126
+ 'capture_lock_legacy',
127
+ 'capture_lock_owner_unverifiable',
128
+ 'capture_lock_backend_unavailable',
129
+ 'attached',
130
+ 'uncertain',
131
+ 'disconnected',
132
+ ]);
133
+ const FITTING_STAGES = new Set([
134
+ 'original',
135
+ 'inputs_1000',
136
+ 'inputs_200',
137
+ 'inputs_60',
138
+ 'text_head_tail',
139
+ 'text_omitted',
140
+ 'compact_calls',
141
+ 'callless_omitted',
142
+ 'runs_folded',
143
+ ]);
144
+
145
+ function isFiniteNumber(value) {
146
+ return typeof value === 'number' && Number.isFinite(value);
147
+ }
148
+
149
+ function isSafeBoundedInteger(value, minimum, maximum) {
150
+ return Number.isSafeInteger(value) && value >= minimum && value <= maximum;
151
+ }
152
+
153
+ /**
154
+ * Parse the optional v2 policy without allowing partial or unknown settings.
155
+ * @param {string|undefined} [raw]
156
+ */
157
+ export function parseContextPolicy(raw = process.env.CODEX_CONTEXT_POLICY_JSON) {
158
+ if (raw === undefined || raw.trim() === '') return null;
159
+ if (Buffer.byteLength(raw, 'utf8') > MAX_POLICY_BYTES)
160
+ throw new Error('context policy exceeds 8KiB');
161
+ let value;
162
+ try {
163
+ value = JSON.parse(raw);
164
+ } catch {
165
+ throw new Error('context policy is not valid JSON');
166
+ }
167
+ if (
168
+ !isRecord(value) ||
169
+ !hasOnlyKeys(value, [
170
+ 'schemaVersion',
171
+ 'compactAtPercent',
172
+ 'keepThreshold',
173
+ 'preserveRecentMessages',
174
+ 'maxStateTokens',
175
+ 'maxRequestTokens',
176
+ 'goal',
177
+ ]) ||
178
+ value.schemaVersion !== 2 ||
179
+ !isFiniteNumber(value.compactAtPercent) ||
180
+ value.compactAtPercent < 1 ||
181
+ value.compactAtPercent > 95 ||
182
+ !isFiniteNumber(value.keepThreshold) ||
183
+ value.keepThreshold < 0 ||
184
+ value.keepThreshold > 1 ||
185
+ !isSafeBoundedInteger(value.preserveRecentMessages, 1, 100) ||
186
+ !isSafeBoundedInteger(value.maxStateTokens, 1_000, 25_000) ||
187
+ !isSafeBoundedInteger(value.maxRequestTokens, 1_000, 30_000) ||
188
+ value.maxRequestTokens <= value.maxStateTokens + 256 ||
189
+ (value.goal !== undefined &&
190
+ (typeof value.goal !== 'string' || value.goal.length > 4_000 || value.goal.length === 0))
191
+ )
192
+ throw new Error('context policy v2 is invalid');
193
+ return Object.freeze({
194
+ schemaVersion: 2,
195
+ compactAtPercent: value.compactAtPercent,
196
+ keepThreshold: value.keepThreshold,
197
+ preserveRecentMessages: value.preserveRecentMessages,
198
+ maxStateTokens: value.maxStateTokens,
199
+ maxRequestTokens: value.maxRequestTokens,
200
+ ...(value.goal === undefined ? {} : { goal: value.goal }),
201
+ });
202
+ }
203
+
204
+ function normalizeContextPolicy(policy) {
205
+ if (policy === undefined) return parseContextPolicy();
206
+ if (policy === null) return null;
207
+ try {
208
+ const serialized = JSON.stringify(policy);
209
+ if (typeof serialized !== 'string') throw new Error('policy is not serializable');
210
+ return parseContextPolicy(serialized);
211
+ } catch {
212
+ throw new Error('context policy v2 is invalid');
213
+ }
214
+ }
215
+
216
+ function selectionOptions(policy) {
217
+ return {
218
+ keep_threshold: policy.keepThreshold,
219
+ preserve_recent_items: policy.preserveRecentMessages,
220
+ max_state_tokens: policy.maxStateTokens,
221
+ max_request_tokens: policy.maxRequestTokens,
222
+ };
223
+ }
224
+
225
+ function validSelectionOptions(value) {
226
+ return (
227
+ isRecord(value) &&
228
+ hasOnlyKeys(value, [
229
+ 'keep_threshold',
230
+ 'preserve_recent_items',
231
+ 'max_state_tokens',
232
+ 'max_request_tokens',
233
+ ]) &&
234
+ isFiniteNumber(value.keep_threshold) &&
235
+ value.keep_threshold >= 0 &&
236
+ value.keep_threshold <= 1 &&
237
+ isSafeBoundedInteger(value.preserve_recent_items, 1, 100) &&
238
+ isSafeBoundedInteger(value.max_state_tokens, 1_000, 25_000) &&
239
+ isSafeBoundedInteger(value.max_request_tokens, 1_000, 30_000) &&
240
+ value.max_request_tokens > value.max_state_tokens + 256
241
+ );
242
+ }
243
+
244
+ function validateFitting(value, maxStateTokens = 25_000) {
245
+ if (value === null) return;
246
+ if (
247
+ !isRecord(value) ||
248
+ !hasOnlyKeys(value, [
249
+ 'version',
250
+ 'stage',
251
+ 'estimator',
252
+ 'before_estimated_state_tokens',
253
+ 'after_estimated_state_tokens',
254
+ ]) ||
255
+ value.version !== 'state-fit-v1' ||
256
+ !FITTING_STAGES.has(value.stage) ||
257
+ value.estimator !== 'utf8-bytes-v1' ||
258
+ !isSafeBoundedInteger(value.before_estimated_state_tokens, 0, MAX_SELECTION_BYTES) ||
259
+ !isSafeBoundedInteger(value.after_estimated_state_tokens, 0, maxStateTokens) ||
260
+ value.after_estimated_state_tokens > value.before_estimated_state_tokens
261
+ )
262
+ throw new Error('invalid v2 fitting metadata');
263
+ }
264
+
265
+ function numberEnv(name, fallback) {
266
+ const value = Number(process.env[name]);
267
+ return Number.isFinite(value) && value > 0 ? value : fallback;
268
+ }
269
+ function codexChildEnvironment() {
270
+ const environment = { ...process.env };
271
+ delete environment.JEV_API_KEY;
272
+ delete environment.TYPESAFE_API_KEY;
273
+ return environment;
274
+ }
275
+ function isRecord(value) {
276
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
277
+ }
278
+ function hasOnlyKeys(value, keys) {
279
+ return isRecord(value) && Object.keys(value).every((key) => keys.includes(key));
280
+ }
281
+ function writeJsonLine(stream, value) {
282
+ stream.write(`${JSON.stringify(value)}\n`);
283
+ }
284
+ function deferred() {
285
+ let resolvePromise;
286
+ let rejectPromise;
287
+ const promise = new Promise((resolve, reject) => {
288
+ resolvePromise = resolve;
289
+ rejectPromise = reject;
290
+ });
291
+ return { promise, resolve: resolvePromise, reject: rejectPromise };
292
+ }
293
+ function safeThreadName(threadId) {
294
+ return threadId.replace(/[^A-Za-z0-9._-]/g, '_');
295
+ }
296
+ function strictThreadName(threadId) {
297
+ if (!/^[A-Za-z0-9._-]{1,128}$/.test(threadId) || threadId === '.' || threadId === '..')
298
+ throw new Error('thread id is unsafe for recovery notes');
299
+ return threadId;
300
+ }
301
+ function canonicalJson(value) {
302
+ if (value === null || typeof value !== 'object') return JSON.stringify(value);
303
+ if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
304
+ const record = value;
305
+ return `{${Object.keys(record)
306
+ .sort()
307
+ .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
308
+ .join(',')}}`;
309
+ }
310
+ function hashJson(value) {
311
+ return createHash('sha256').update(canonicalJson(value)).digest('hex');
312
+ }
313
+ function hashText(value) {
314
+ return createHash('sha256').update(value, 'utf8').digest('hex');
315
+ }
316
+ function isTimestamp(value) {
317
+ return (
318
+ typeof value === 'string' &&
319
+ /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/.test(value) &&
320
+ Number.isFinite(Date.parse(value))
321
+ );
322
+ }
323
+ function escapeReference(value) {
324
+ return String(value).replace(/[\\`\r\n]/g, (character) => `\\${character}`);
325
+ }
326
+ function isSafeCounter(value) {
327
+ return Number.isSafeInteger(value) && value >= 0;
328
+ }
329
+ function isValidBreakdown(value) {
330
+ return (
331
+ isRecord(value) &&
332
+ isSafeCounter(value.totalTokens) &&
333
+ [
334
+ 'inputTokens',
335
+ 'cachedInputTokens',
336
+ 'cacheWriteInputTokens',
337
+ 'outputTokens',
338
+ 'reasoningOutputTokens',
339
+ ].every((key) => !(key in value) || isSafeCounter(value[key]))
340
+ );
341
+ }
342
+ function isValidUsage(value) {
343
+ return (
344
+ isRecord(value) &&
345
+ isValidBreakdown(value.last) &&
346
+ isValidBreakdown(value.total) &&
347
+ (value.modelContextWindow === null ||
348
+ (isSafeCounter(value.modelContextWindow) && value.modelContextWindow > 0))
349
+ );
350
+ }
351
+ function hasKnownContextWindow(value) {
352
+ return isRecord(value) && isSafeCounter(value.modelContextWindow) && value.modelContextWindow > 0;
353
+ }
354
+ function redact(value, limit = 16_384) {
355
+ return String(value)
356
+ .replace(/(authorization\s*[:=]\s*bearer\s+)[^\s]+/gi, '$1[REDACTED]')
357
+ .replace(
358
+ /(["']?(?:api[_-]?key|token|secret|password)["']?\s*[:=]\s*["']?)([^\s,'"}]+)(["']?)/gi,
359
+ '$1[REDACTED]$3',
360
+ )
361
+ .slice(0, limit);
362
+ }
363
+
364
+ function isUuid(value) {
365
+ return (
366
+ typeof value === 'string' &&
367
+ /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(value)
368
+ );
369
+ }
370
+
371
+ function boundedDiagnosticValue(value) {
372
+ return typeof value === 'string' && value.length > 0 && value.length <= MAX_DIAGNOSTIC_STRING
373
+ ? value
374
+ : null;
375
+ }
376
+
377
+ function isSafeCorrelationId(value) {
378
+ return typeof value === 'string' && /^[A-Za-z0-9._:-]{1,128}$/u.test(value);
379
+ }
380
+
381
+ function boundedCorrelationValue(value) {
382
+ return typeof value === 'string' && value.length > 0 && value.length <= 256 ? value : null;
383
+ }
384
+
385
+ function safeRpcCode(value) {
386
+ return Number.isSafeInteger(value) && value >= -32_768 && value <= 32_767 ? value : null;
387
+ }
388
+
389
+ function clientRequestKey(value) {
390
+ if (typeof value === 'string' && value.length > 0 && value.length <= 128) return `s:${value}`;
391
+ if (Number.isSafeInteger(value)) return `n:${value}`;
392
+ return null;
393
+ }
394
+
395
+ /**
396
+ * Closed private diagnostic contract consumed by the client sink. It contains
397
+ * stage/reason enums, pseudonymous session identity, operation/correlation
398
+ * identifiers and bounded counts only. It never accepts raw MCP/provider text,
399
+ * prompts, notes, paths or thread IDs.
400
+ */
401
+ export function normalizeCodexDiagnostic(event, { threadId = null } = {}) {
402
+ if (!isRecord(event)) return null;
403
+ const stage = DIAGNOSTIC_STAGES.has(event.stage)
404
+ ? event.stage
405
+ : DIAGNOSTIC_STAGES.has(event.phase)
406
+ ? event.phase
407
+ : null;
408
+ const reason = DIAGNOSTIC_REASONS.has(event.reason)
409
+ ? event.reason
410
+ : event.reasonCode === 'candidate_window_bounded'
411
+ ? 'candidate_window_bounded'
412
+ : null;
413
+ if (stage === null || reason === null) return null;
414
+ const operationId = isUuid(event.operationId) ? event.operationId : undefined;
415
+ const correlationId = isSafeCorrelationId(event.correlationId) ? event.correlationId : null;
416
+ const rpcCode = safeRpcCode(event.rpcCode ?? event.rpc_code);
417
+ const counts = isRecord(event.counts)
418
+ ? Object.fromEntries(
419
+ Object.entries(event.counts).filter(
420
+ ([key, value]) =>
421
+ /^[a-z_]{1,48}$/u.test(key) &&
422
+ isSafeBoundedInteger(value, 0, /_bytes$/u.test(key) ? MAX_DIAGNOSTIC_BYTES : 1_000_000),
423
+ ),
424
+ )
425
+ : undefined;
426
+ const result = {
427
+ schema_version: 1,
428
+ phase: boundedDiagnosticValue(event.phase) ?? `${stage}_${reason}`,
429
+ stage,
430
+ reason,
431
+ ...(operationId === undefined ? {} : { operation_id: operationId }),
432
+ ...(correlationId === null ? {} : { correlation_id: correlationId }),
433
+ ...(rpcCode === null ? {} : { rpc_code: rpcCode }),
434
+ ...(typeof threadId === 'string' && threadId.length > 0
435
+ ? { session_key: hashText(threadId) }
436
+ : {}),
437
+ ...(counts && Object.keys(counts).length > 0 ? { counts } : {}),
438
+ };
439
+ return result;
440
+ }
441
+
442
+ function parseJsonText(value) {
443
+ if (typeof value !== 'string' || Buffer.byteLength(value, 'utf8') > MAX_SELECTION_BYTES)
444
+ return null;
445
+ try {
446
+ const parsed = JSON.parse(value);
447
+ return isRecord(parsed) ? parsed : null;
448
+ } catch {
449
+ return null;
450
+ }
451
+ }
452
+
453
+ function responseStructuredContent(response) {
454
+ if (!isRecord(response)) return null;
455
+ if (isRecord(response.structuredContent)) return response.structuredContent;
456
+ const content = Array.isArray(response.content) ? response.content : [];
457
+ const textPart = content.find((part) => isRecord(part) && part.type === 'text');
458
+ return textPart ? parseJsonText(textPart.text) : null;
459
+ }
460
+
461
+ /** Parse only the closed Context error envelope or known fixed-code text form. */
462
+ export function parseContextError(response) {
463
+ const structured = responseStructuredContent(response);
464
+ let value = structured;
465
+ if (value === null) {
466
+ const content = Array.isArray(response?.content) ? response.content : [];
467
+ const textPart = content.find((part) => isRecord(part) && part.type === 'text');
468
+ const text = typeof textPart?.text === 'string' ? textPart.text : '';
469
+ const fixed =
470
+ /^(INVALID_INPUT|FEATURE_DISABLED|PAID_PLAN_REQUIRED|ENTITLEMENT_UNAVAILABLE|RATE_LIMITED|PROVIDER_NOT_CONFIGURED|BUDGET_EXCEEDED|PROVIDER_TIMEOUT|PROVIDER_UNAVAILABLE|INVALID_PROVIDER_RESPONSE)(?::|$)/u.exec(
471
+ text,
472
+ );
473
+ if (!fixed) return null;
474
+ value = { error_code: fixed[1] };
475
+ }
476
+ if (
477
+ !CONTEXT_ERROR_CODES.has(value.error_code) ||
478
+ (value.failure_detail !== undefined && !CONTEXT_FAILURE_DETAILS.has(value.failure_detail)) ||
479
+ (value.admission_reason !== undefined &&
480
+ !CONTEXT_ADMISSION_REASONS.has(value.admission_reason)) ||
481
+ (value.correlation_id !== undefined && !isSafeCorrelationId(value.correlation_id)) ||
482
+ (value.request_id !== undefined && !isUuid(value.request_id)) ||
483
+ (value.retry_after_ms !== undefined &&
484
+ !isSafeBoundedInteger(value.retry_after_ms, 0, 3_600_000))
485
+ )
486
+ return null;
487
+ return {
488
+ errorCode: value.error_code,
489
+ failureDetail: value.failure_detail ?? null,
490
+ admissionReason: value.admission_reason ?? null,
491
+ correlationId: boundedCorrelationValue(value.correlation_id),
492
+ requestId: isUuid(value.request_id) ? value.request_id : null,
493
+ retryAfterMs: value.retry_after_ms ?? null,
494
+ quota:
495
+ value.error_code === 'RATE_LIMITED' ||
496
+ value.failure_detail === 'shared_admission_denied' ||
497
+ SHARED_QUOTA_ADMISSION_REASONS.has(value.admission_reason),
498
+ };
499
+ }
500
+
501
+ export function parseBudgetSnapshot(value) {
502
+ if (
503
+ !isRecord(value) ||
504
+ !hasOnlyKeys(value, [
505
+ 'schema_version',
506
+ 'server_time',
507
+ 'expires_at',
508
+ 'window_end',
509
+ 'available_requests',
510
+ 'available_tokens',
511
+ 'output_token_allowance',
512
+ 'max_batches_per_operation',
513
+ 'account_in_flight',
514
+ 'retry_after_ms',
515
+ 'provider_batches',
516
+ 'provider_model',
517
+ 'correlation_id',
518
+ ]) ||
519
+ value.schema_version !== 1 ||
520
+ !isTimestamp(value.server_time) ||
521
+ !isTimestamp(value.expires_at) ||
522
+ !isTimestamp(value.window_end) ||
523
+ Date.parse(value.expires_at) <= Date.parse(value.server_time) ||
524
+ Date.parse(value.expires_at) - Date.parse(value.server_time) > MAX_BUDGET_SNAPSHOT_AGE_MS ||
525
+ Date.parse(value.expires_at) > Date.parse(value.window_end) ||
526
+ !isSafeBoundedInteger(value.available_requests, 0, 1_000_000) ||
527
+ !isSafeBoundedInteger(value.available_tokens, 0, Number.MAX_SAFE_INTEGER) ||
528
+ !isSafeBoundedInteger(value.output_token_allowance, 0, Number.MAX_SAFE_INTEGER) ||
529
+ !isSafeBoundedInteger(value.max_batches_per_operation, 0, 4) ||
530
+ typeof value.account_in_flight !== 'boolean' ||
531
+ !isSafeBoundedInteger(value.retry_after_ms, 0, 3_600_000) ||
532
+ value.provider_batches !== 0 ||
533
+ value.provider_model !== null ||
534
+ !isSafeCorrelationId(value.correlation_id)
535
+ )
536
+ return null;
537
+ return value;
538
+ }
539
+
540
+ function budgetSnapshotFresh(snapshot, receivedAt, currentTime) {
541
+ if (!isRecord(snapshot) || !Number.isSafeInteger(receivedAt) || currentTime < receivedAt)
542
+ return false;
543
+ const lifetime = Date.parse(snapshot.expires_at) - Date.parse(snapshot.server_time);
544
+ return (
545
+ lifetime > 0 && lifetime <= MAX_BUDGET_SNAPSHOT_AGE_MS && currentTime - receivedAt <= lifetime
546
+ );
547
+ }
548
+
549
+ function diagnosticReasonForError(error) {
550
+ if (DIAGNOSTIC_REASONS.has(error?.diagnosticReason)) return error.diagnosticReason;
551
+ if (safeRpcCode(error?.rpcCode) !== null) return 'protocol_error';
552
+ const message = error instanceof Error ? error.message : String(error ?? '');
553
+ if (
554
+ /snapshot exceeds bound|capture exceeds|capture size|oversized internal response/iu.test(
555
+ message,
556
+ )
557
+ )
558
+ return 'capture_size_exceeded';
559
+ if (/capture item count|source index exceeds bound/iu.test(message))
560
+ return 'capture_item_count_exceeded';
561
+ if (/capture storage capacity|storage capacity|capture directory/iu.test(message))
562
+ return 'storage_capacity_exceeded';
563
+ if (/capture source identity validation/iu.test(message)) return 'source_changed';
564
+ if (/capture candidate|checkpoint target/iu.test(message)) return 'private_storage_failed';
565
+ if (/thread\/(?:read|turns\/list)|capture history|page unavailable/iu.test(message))
566
+ return 'history_unavailable';
567
+ if (/checkpoint|recovery notes|private (?:file|storage)|storage|EACCES|ENOSPC/iu.test(message))
568
+ return 'private_storage_failed';
569
+ if (/tim(?:e|ed)[ -]?out/iu.test(message)) return 'timeout';
570
+ if (/closed|deleted/iu.test(message)) return 'thread_closed';
571
+ if (/source changed|state changed|stale/iu.test(message)) return 'source_changed';
572
+ if (/candidate|history|thread\/read/iu.test(message)) return 'history_unavailable';
573
+ return 'request_failed';
574
+ }
575
+
576
+ function rpcFailure(kind, error) {
577
+ const failure = new Error(`${kind} request rejected by the app-server`);
578
+ failure.name = 'CodexProtocolError';
579
+ failure.diagnosticReason = 'protocol_error';
580
+ failure.rpcCode = safeRpcCode(error?.code);
581
+ return failure;
582
+ }
583
+
584
+ function boundedFailureCounts(error) {
585
+ if (!isRecord(error)) return undefined;
586
+ const counts = {};
587
+ for (const [source, target] of [
588
+ ['captureItemCount', 'capture_item_count'],
589
+ ['captureItemLimit', 'capture_item_limit'],
590
+ ['captureBytes', 'capture_bytes'],
591
+ ['captureLimitBytes', 'capture_limit_bytes'],
592
+ ['responseBytes', 'response_bytes'],
593
+ ['responseLimitBytes', 'response_limit_bytes'],
594
+ ['captureDirectoryBytes', 'capture_directory_bytes'],
595
+ ['captureDirectoryLimitBytes', 'capture_directory_limit_bytes'],
596
+ ['captureFileCount', 'capture_file_count'],
597
+ ['captureFileLimit', 'capture_file_limit'],
598
+ ]) {
599
+ const maximum = target.includes('directory_bytes')
600
+ ? MAX_CAPTURE_DIRECTORY_BYTES
601
+ : target.includes('bytes')
602
+ ? MAX_DIAGNOSTIC_BYTES
603
+ : 1_000_000;
604
+ if (isSafeBoundedInteger(error[source], 0, maximum)) counts[target] = error[source];
605
+ }
606
+ return Object.keys(counts).length > 0 ? counts : undefined;
607
+ }
608
+
609
+ async function ensurePrivateDirectory(directory, fsOps = captureFs) {
610
+ const target = resolve(directory);
611
+ await fsOps.mkdir(target, { recursive: true, mode: 0o700 });
612
+ const parts = target.split('/');
613
+ let current = parts[0] === '' ? '/' : parts[0];
614
+ for (const part of parts.slice(parts[0] === '' ? 1 : 1)) {
615
+ if (!part) continue;
616
+ current = current === '/' ? `/${part}` : `${current}/${part}`;
617
+ const info = await fsOps.lstat(current);
618
+ if (info.isSymbolicLink() || !info.isDirectory())
619
+ throw new Error('checkpoint directory is unsafe');
620
+ }
621
+ await fsOps.chmod(target, 0o700);
622
+ return target;
623
+ }
624
+ async function validatePrivateDirectoryPath(directory, fsOps = captureFs) {
625
+ const target = resolve(directory);
626
+ const parts = target.split('/');
627
+ let current = parts[0] === '' ? '/' : parts[0];
628
+ for (const part of parts.slice(1)) {
629
+ if (!part) continue;
630
+ current = current === '/' ? `/${part}` : `${current}/${part}`;
631
+ const info = await fsOps.lstat(current);
632
+ if (info.isSymbolicLink() || !info.isDirectory())
633
+ throw new Error('checkpoint directory is unsafe');
634
+ if (
635
+ current === target &&
636
+ ((typeof process.getuid === 'function' && info.uid !== process.getuid()) ||
637
+ (info.mode & 0o077) !== 0)
638
+ )
639
+ throw new Error('capture directory is not private');
640
+ }
641
+ return target;
642
+ }
643
+ async function assertPrivateFile(file, label, fsOps = captureFs) {
644
+ const info = await fsOps.lstat(file);
645
+ if (
646
+ info.isSymbolicLink() ||
647
+ !info.isFile() ||
648
+ (info.mode & 0o077) !== 0 ||
649
+ (typeof process.getuid === 'function' && info.uid !== process.getuid())
650
+ )
651
+ throw new Error(`${label} is not a private regular file`);
652
+ return info;
653
+ }
654
+ async function readPrivateFile(file, label, maxBytes = null, fsOps = captureFs) {
655
+ const info = await assertPrivateFile(file, label, fsOps);
656
+ if (maxBytes !== null && info.size > maxBytes) throw new Error(`${label} exceeds its bound`);
657
+ return fsOps.readFile(file, 'utf8');
658
+ }
659
+
660
+ function captureCapacityError(state) {
661
+ const error = new Error('capture storage capacity exceeded');
662
+ error.diagnosticReason = 'storage_capacity_exceeded';
663
+ error.captureDirectoryBytes = state?.totalBytes ?? MAX_CAPTURE_DIRECTORY_BYTES;
664
+ error.captureDirectoryLimitBytes = MAX_CAPTURE_DIRECTORY_BYTES;
665
+ error.captureFileCount =
666
+ state?.managedFileCount ?? state?.managedFiles?.length ?? MAX_CAPTURE_FILES;
667
+ error.captureFileLimit = MAX_CAPTURE_FILES;
668
+ return error;
669
+ }
670
+
671
+ function captureStorageCleanupError(state) {
672
+ const error = new Error('capture storage cleanup remains incomplete');
673
+ error.diagnosticReason = 'private_storage_failed';
674
+ error.captureDirectoryBytes = state?.totalBytes ?? MAX_CAPTURE_DIRECTORY_BYTES;
675
+ error.captureDirectoryLimitBytes = MAX_CAPTURE_DIRECTORY_BYTES;
676
+ error.captureFileCount = state?.managedFiles?.length ?? MAX_CAPTURE_FILES;
677
+ error.captureFileLimit = MAX_CAPTURE_FILES;
678
+ return error;
679
+ }
680
+
681
+ function validateCaptureSnapshot(value, expectedSourceRevision = null) {
682
+ if (
683
+ !isRecord(value) ||
684
+ ![1, 2].includes(value.version) ||
685
+ typeof value.threadId !== 'string' ||
686
+ typeof value.sourceRevision !== 'string' ||
687
+ !/^[a-f0-9]{64}$/u.test(value.sourceRevision) ||
688
+ !isRecord(value.threadRead) ||
689
+ value.threadRead.thread?.id !== value.threadId ||
690
+ (value.version === 1 && hashJson(value.threadRead) !== value.sourceRevision) ||
691
+ (value.version === 2 &&
692
+ (!isRecord(value.captureManifest) ||
693
+ value.captureManifest.version !== 'codex-capture-manifest-v1' ||
694
+ value.captureManifest.sourceRevision !== value.sourceRevision ||
695
+ value.captureManifest.threadId !== value.threadId ||
696
+ !isSafeBoundedInteger(value.captureManifest.pageCount, 1, MAX_CAPTURE_PAGES) ||
697
+ !isSafeBoundedInteger(value.captureManifest.itemCount, 0, MAX_CAPTURE_ITEMS) ||
698
+ !isSafeBoundedInteger(value.captureManifest.totalBytes, 1, MAX_CAPTURE_TOTAL_BYTES) ||
699
+ !Array.isArray(value.captureManifest.segments) ||
700
+ value.captureManifest.segments.length !== value.captureManifest.pageCount ||
701
+ !Array.isArray(value.captureManifest.pageHashes) ||
702
+ value.captureManifest.pageHashes.length !== value.captureManifest.pageCount ||
703
+ value.captureManifest.pageHashes.some((hash) => !/^[a-f0-9]{64}$/u.test(hash)) ||
704
+ captureManifestRevision(value.threadRead.thread, value.captureManifest.pageHashes) !==
705
+ value.sourceRevision ||
706
+ value.captureManifest.segments.some(
707
+ (segment, index) =>
708
+ segment !== captureSegmentName(value.threadId, value.sourceRevision, index),
709
+ ))) ||
710
+ (expectedSourceRevision !== null && value.sourceRevision !== expectedSourceRevision)
711
+ )
712
+ throw new Error('capture source identity validation failed');
713
+ strictThreadName(value.threadId);
714
+ return value;
715
+ }
716
+
717
+ function validateCaptureSegment(value, expectedThreadId = null, expectedSourceRevision = null) {
718
+ if (
719
+ !isRecord(value) ||
720
+ value.version !== 'codex-capture-segment-v1' ||
721
+ typeof value.threadId !== 'string' ||
722
+ (expectedThreadId !== null && value.threadId !== expectedThreadId) ||
723
+ typeof value.sourceRevision !== 'string' ||
724
+ !/^[a-f0-9]{64}$/u.test(value.sourceRevision) ||
725
+ (expectedSourceRevision !== null && value.sourceRevision !== expectedSourceRevision) ||
726
+ !isSafeBoundedInteger(value.pageIndex, 0, MAX_CAPTURE_PAGES - 1) ||
727
+ !isRecord(value.page) ||
728
+ value.page.threadId !== value.threadId ||
729
+ !Array.isArray(value.page.turns) ||
730
+ typeof value.pageHash !== 'string' ||
731
+ !/^[a-f0-9]{64}$/u.test(value.pageHash) ||
732
+ hashJson(value.page) !== value.pageHash ||
733
+ !isSafeBoundedInteger(value.itemCount, 0, MAX_CAPTURE_ITEMS)
734
+ )
735
+ throw new Error('capture segment identity validation failed');
736
+ return value;
737
+ }
738
+
739
+ function captureSegmentName(threadId, sourceRevision, pageIndex) {
740
+ return `${strictThreadName(threadId)}.${sourceRevision}.segment-${String(pageIndex).padStart(4, '0')}.json`;
741
+ }
742
+
743
+ function captureManifestRevision(metadataThread, pageHashes) {
744
+ const thread = Object.fromEntries(
745
+ Object.entries(metadataThread).filter(([key]) => key !== 'turns'),
746
+ );
747
+ return hashJson({ thread, pages: pageHashes });
748
+ }
749
+
750
+ function captureNameForSnapshot(value, suffix = '') {
751
+ return `${strictThreadName(value.threadId)}${suffix}.json`;
752
+ }
753
+
754
+ async function readCaptureDirectoryState(
755
+ directory,
756
+ fsOps = captureFs,
757
+ { replacedCurrentName = null } = {},
758
+ ) {
759
+ const entries = await fsOps.readdir(directory, { withFileTypes: true });
760
+ if (entries.length > MAX_CAPTURE_FILES * 4)
761
+ throw captureCapacityError({ totalBytes: MAX_CAPTURE_DIRECTORY_BYTES, managedFiles: [] });
762
+ let activeSentinelInfo = null;
763
+ try {
764
+ activeSentinelInfo = await fsOps.lstat(resolve(directory, '.capture.lock'));
765
+ } catch (error) {
766
+ if (error?.code !== 'ENOENT') throw error;
767
+ }
768
+ const state = {
769
+ entryCount: entries.length,
770
+ totalBytes: 0,
771
+ managedFiles: [],
772
+ referencedImmutableNames: new Set(),
773
+ protectedGroups: new Set(),
774
+ manifestRefs: [],
775
+ blockedEntries: false,
776
+ unsafeRecovery: false,
777
+ };
778
+ for (const entry of entries) {
779
+ if (entry.name === '.capture.lock') continue;
780
+ const file = resolve(directory, entry.name);
781
+ const info = await fsOps.lstat(file);
782
+ if (
783
+ activeSentinelInfo !== null &&
784
+ Number.isInteger(activeSentinelInfo.dev) &&
785
+ Number.isInteger(activeSentinelInfo.ino) &&
786
+ info.dev === activeSentinelInfo.dev &&
787
+ info.ino === activeSentinelInfo.ino
788
+ )
789
+ continue;
790
+ state.totalBytes += info.size;
791
+ if (
792
+ info.isSymbolicLink() ||
793
+ !info.isFile() ||
794
+ (typeof process.getuid === 'function' && info.uid !== process.getuid()) ||
795
+ (info.mode & 0o077) !== 0
796
+ ) {
797
+ state.blockedEntries = true;
798
+ continue;
799
+ }
800
+ if (!entry.name.endsWith('.json')) continue;
801
+ let value;
802
+ try {
803
+ if (info.size > MAX_CAPTURE_BYTES) {
804
+ if (entry.name.endsWith('.recovery.json')) state.unsafeRecovery = true;
805
+ continue;
806
+ }
807
+ value = JSON.parse(await fsOps.readFile(file, 'utf8'));
808
+ } catch {
809
+ if (entry.name.endsWith('.recovery.json')) state.unsafeRecovery = true;
810
+ continue;
811
+ }
812
+ if (entry.name.endsWith('.recovery.json')) {
813
+ if (
814
+ isRecord(value) &&
815
+ typeof value.threadId === 'string' &&
816
+ /^[a-f0-9]{64}$/u.test(value.sourceRevision) &&
817
+ typeof value.notes === 'string' &&
818
+ typeof value.notesHash === 'string' &&
819
+ value.notesHash === hashText(value.notes)
820
+ ) {
821
+ try {
822
+ state.referencedImmutableNames.add(
823
+ `${strictThreadName(value.threadId)}.${value.sourceRevision}.json`,
824
+ );
825
+ state.protectedGroups.add(`${strictThreadName(value.threadId)}.${value.sourceRevision}`);
826
+ } catch {
827
+ state.unsafeRecovery = true;
828
+ }
829
+ } else state.unsafeRecovery = true;
830
+ if (isRecord(value) && typeof value.notes === 'string') {
831
+ const references = [
832
+ ...value.notes.matchAll(/capture_file:\s+.*?([A-Za-z0-9._-]+\.[a-f0-9]{64}\.json)/gu),
833
+ ];
834
+ for (const match of references) state.referencedImmutableNames.add(match[1]);
835
+ }
836
+ continue;
837
+ }
838
+ if (isRecord(value) && value.version === 'codex-capture-segment-v1') {
839
+ try {
840
+ validateCaptureSegment(value);
841
+ const expectedName = captureSegmentName(
842
+ value.threadId,
843
+ value.sourceRevision,
844
+ value.pageIndex,
845
+ );
846
+ if (entry.name !== expectedName) continue;
847
+ state.managedFiles.push({
848
+ file,
849
+ name: entry.name,
850
+ size: info.size,
851
+ mtimeMs: info.mtimeMs,
852
+ immutable: true,
853
+ group: `${value.threadId}.${value.sourceRevision}`,
854
+ });
855
+ } catch {
856
+ state.blockedEntries = true;
857
+ }
858
+ continue;
859
+ }
860
+ try {
861
+ validateCaptureSnapshot(value);
862
+ } catch {
863
+ continue;
864
+ }
865
+ const sourceName = `${strictThreadName(value.threadId)}.${value.sourceRevision}.json`;
866
+ if (
867
+ !new Set([
868
+ captureNameForSnapshot(value),
869
+ captureNameForSnapshot(value, '.completed'),
870
+ sourceName,
871
+ ]).has(entry.name)
872
+ )
873
+ continue;
874
+ state.managedFiles.push({
875
+ file,
876
+ name: entry.name,
877
+ size: info.size,
878
+ mtimeMs: info.mtimeMs,
879
+ immutable: entry.name === sourceName,
880
+ group: `${value.threadId}.${value.sourceRevision}`,
881
+ });
882
+ const replacedCurrent = entry.name === replacedCurrentName;
883
+ if (!replacedCurrent && !entry.name.endsWith('.' + value.sourceRevision + '.json'))
884
+ state.referencedImmutableNames.add(sourceName);
885
+ if (value.version === 2 && entry.name !== sourceName && !replacedCurrent) {
886
+ for (const segment of value.captureManifest.segments) {
887
+ if (typeof segment === 'string') state.referencedImmutableNames.add(segment);
888
+ }
889
+ }
890
+ if (value.version === 2) state.manifestRefs.push(value.captureManifest);
891
+ if (
892
+ value.version === 2 &&
893
+ state.protectedGroups.has(`${value.threadId}.${value.sourceRevision}`)
894
+ ) {
895
+ for (const segment of value.captureManifest.segments)
896
+ state.referencedImmutableNames.add(segment);
897
+ }
898
+ }
899
+ const managedNames = new Set(state.managedFiles.map((entry) => entry.name));
900
+ for (const manifest of state.manifestRefs) {
901
+ if (manifest.segments.some((segment) => !managedNames.has(segment)))
902
+ state.blockedEntries = true;
903
+ }
904
+ for (const entry of state.managedFiles) {
905
+ if (entry.group && state.referencedImmutableNames.has(entry.name))
906
+ state.protectedGroups.add(entry.group);
907
+ }
908
+ return state;
909
+ }
910
+
911
+ function captureLockError(reason) {
912
+ const messages = {
913
+ capture_lock_timeout: 'capture lock is held by a live or unverified owner',
914
+ capture_lock_legacy: 'capture lock uses an unidentifiable legacy sentinel',
915
+ capture_lock_owner_unverifiable: 'capture lock owner identity is unavailable',
916
+ capture_lock_backend_unavailable: 'capture lock backend is unavailable',
917
+ };
918
+ const error = new Error(messages[reason] ?? 'capture lock unavailable');
919
+ error.diagnosticReason = reason;
920
+ return error;
921
+ }
922
+
923
+ const CAPTURE_LOCK_MARKER = `${JSON.stringify({ backend: 'flock', schema: 2 })}\n`;
924
+ const CAPTURE_GUARD_NAME = '.capture.guard';
925
+ const CAPTURE_PAGE_STAGE_NAME =
926
+ /^\.capture-(?:segment-)?stage\.[A-Za-z0-9._-]{1,128}\.[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.(?:[0-9]|[12][0-9]|3[01])\.tmp$/iu;
927
+ const CAPTURE_SOURCE_STAGE_NAME =
928
+ /^\.capture-stage\.[A-Za-z0-9._-]{1,128}\.[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.(?:[0-9]|[12][0-9]|3[01])\.tmp$/iu;
929
+
930
+ async function removePrivateCaptureTemps(directory, fsOps, pattern) {
931
+ const entries = await fsOps.readdir(directory, { withFileTypes: true });
932
+ let removedFiles = 0;
933
+ let removedBytes = 0;
934
+ for (const entry of entries) {
935
+ if (!pattern.test(entry.name)) continue;
936
+ const file = resolve(directory, entry.name);
937
+ let info;
938
+ try {
939
+ info = await fsOps.lstat(file);
940
+ } catch (error) {
941
+ if (error?.code === 'ENOENT') continue;
942
+ throw error;
943
+ }
944
+ if (
945
+ info.isSymbolicLink() ||
946
+ !info.isFile() ||
947
+ (typeof process.getuid === 'function' && info.uid !== process.getuid()) ||
948
+ (info.mode & 0o077) !== 0
949
+ )
950
+ continue;
951
+ try {
952
+ await fsOps.unlink(file);
953
+ removedFiles += 1;
954
+ removedBytes += info.size;
955
+ } catch (error) {
956
+ if (error?.code !== 'ENOENT') throw error;
957
+ }
958
+ }
959
+ return { removedFiles, removedBytes };
960
+ }
961
+
962
+ async function removeAbandonedCapturePageStages(directory, fsOps) {
963
+ return removePrivateCaptureTemps(directory, fsOps, CAPTURE_PAGE_STAGE_NAME);
964
+ }
965
+
966
+ async function observerKernelIdentity() {
967
+ try {
968
+ return {
969
+ bootId: (await readFile('/proc/sys/kernel/random/boot_id', 'utf8')).trim(),
970
+ pidNamespace: await readlink('/proc/self/ns/pid'),
971
+ };
972
+ } catch {
973
+ return null;
974
+ }
975
+ }
976
+
977
+ async function processIdentity(pid) {
978
+ if (!Number.isSafeInteger(pid) || pid <= 0) return { status: 'invalid' };
979
+ const observer = await observerKernelIdentity();
980
+ if (observer === null) return { status: 'unverifiable' };
981
+ try {
982
+ const ownerNamespace = await readlink(`/proc/${pid}/ns/pid`);
983
+ if (ownerNamespace !== observer.pidNamespace || observer.bootId.length === 0)
984
+ return { status: 'foreign' };
985
+ const stat = await readFile(`/proc/${pid}/stat`, 'utf8');
986
+ const closing = stat.lastIndexOf(')');
987
+ const fields =
988
+ closing < 0
989
+ ? []
990
+ : stat
991
+ .slice(closing + 2)
992
+ .trim()
993
+ .split(/\s+/u);
994
+ const startTime = fields[19];
995
+ if (typeof startTime !== 'string' || !/^[0-9]+$/u.test(startTime))
996
+ return { status: 'unverifiable' };
997
+ return { status: 'live', startTime, bootId: observer.bootId, pidNamespace: ownerNamespace };
998
+ } catch (error) {
999
+ if (error?.code === 'ENOENT') return { status: 'dead' };
1000
+ return { status: 'unverifiable' };
1001
+ }
1002
+ }
1003
+
1004
+ async function captureSentinelOwner(lockPath, fsOps) {
1005
+ let info;
1006
+ try {
1007
+ info = await fsOps.lstat(lockPath);
1008
+ } catch (error) {
1009
+ if (error?.code === 'ENOENT') return { status: 'absent' };
1010
+ throw error;
1011
+ }
1012
+ if (info.isSymbolicLink() || !info.isFile() || (info.mode & 0o077) !== 0)
1013
+ throw new Error('capture lock is not a private regular file');
1014
+ if (info.size === 0) return { status: 'legacy' };
1015
+ if (info.size > 4096) return { status: 'unverifiable' };
1016
+ let value;
1017
+ try {
1018
+ value = JSON.parse(await fsOps.readFile(lockPath, 'utf8'));
1019
+ } catch {
1020
+ return { status: 'unverifiable' };
1021
+ }
1022
+ if (
1023
+ !isRecord(value) ||
1024
+ !hasOnlyKeys(value, [
1025
+ 'schema',
1026
+ 'backend',
1027
+ 'pid',
1028
+ 'startTime',
1029
+ 'bootId',
1030
+ 'pidNamespace',
1031
+ 'nonce',
1032
+ ]) ||
1033
+ value.schema !== 1 ||
1034
+ value.backend !== 'flock' ||
1035
+ !isSafeBoundedInteger(value.pid, 1, 4_000_000_000) ||
1036
+ typeof value.startTime !== 'string' ||
1037
+ !/^[0-9]+$/u.test(value.startTime) ||
1038
+ typeof value.bootId !== 'string' ||
1039
+ !/^[a-f0-9-]{36}$/iu.test(value.bootId) ||
1040
+ typeof value.pidNamespace !== 'string' ||
1041
+ !/^pid:\[\d+\]$/u.test(value.pidNamespace) ||
1042
+ typeof value.nonce !== 'string' ||
1043
+ !isUuid(value.nonce)
1044
+ )
1045
+ return { status: 'unverifiable' };
1046
+ const observer = await observerKernelIdentity();
1047
+ if (observer === null) return { status: 'unverifiable' };
1048
+ if (observer.bootId !== value.bootId) return { status: 'dead' };
1049
+ if (observer.pidNamespace !== value.pidNamespace) return { status: 'foreign' };
1050
+ const current = await processIdentity(value.pid);
1051
+ if (current.status !== 'live') return { status: current.status };
1052
+ if (current.bootId !== value.bootId || current.pidNamespace !== value.pidNamespace)
1053
+ return { status: 'foreign' };
1054
+ return current.startTime === value.startTime ? { status: 'live' } : { status: 'dead' };
1055
+ }
1056
+
1057
+ async function ensureCaptureSentinel(lockPath, task) {
1058
+ const identity = await processIdentity(process.pid);
1059
+ if (identity.status !== 'live') throw captureLockError('capture_lock_owner_unverifiable');
1060
+ const metadata = `${JSON.stringify({
1061
+ schema: 1,
1062
+ backend: 'flock',
1063
+ pid: process.pid,
1064
+ startTime: identity.startTime,
1065
+ bootId: identity.bootId,
1066
+ pidNamespace: identity.pidNamespace,
1067
+ nonce: randomUUID(),
1068
+ })}\n`;
1069
+ while (true) {
1070
+ const temporary = `${lockPath}.${process.pid}.${randomUUID()}.tmp`;
1071
+ let contention = false;
1072
+ let published = false;
1073
+ try {
1074
+ let handle;
1075
+ try {
1076
+ const flags =
1077
+ fsConstants.O_WRONLY |
1078
+ fsConstants.O_CREAT |
1079
+ fsConstants.O_EXCL |
1080
+ (fsConstants.O_NOFOLLOW ?? 0);
1081
+ handle = await captureFs.open(temporary, flags, 0o600);
1082
+ await handle.writeFile(metadata, 'utf8');
1083
+ await handle.sync?.();
1084
+ } finally {
1085
+ await handle?.close().catch(() => undefined);
1086
+ }
1087
+ await captureFs.hardlink(temporary, lockPath);
1088
+ published = true;
1089
+ const publishedInfo = await captureFs.lstat(lockPath);
1090
+ try {
1091
+ return await task();
1092
+ } finally {
1093
+ const current = await captureFs.lstat(lockPath).catch(() => null);
1094
+ if (
1095
+ current !== null &&
1096
+ current.dev === publishedInfo.dev &&
1097
+ current.ino === publishedInfo.ino
1098
+ )
1099
+ await captureFs.unlink(lockPath).catch(() => undefined);
1100
+ }
1101
+ } catch (error) {
1102
+ if (!published && error?.code === 'EEXIST') contention = true;
1103
+ else throw error;
1104
+ } finally {
1105
+ await captureFs.unlink(temporary).catch(() => undefined);
1106
+ }
1107
+ if (!contention) throw captureLockError('capture_lock_owner_unverifiable');
1108
+ const owner = await captureSentinelOwner(lockPath, captureFs);
1109
+ if (owner.status === 'dead') {
1110
+ await captureFs.unlink(lockPath).catch((unlinkError) => {
1111
+ if (unlinkError?.code !== 'ENOENT') throw unlinkError;
1112
+ });
1113
+ continue;
1114
+ }
1115
+ if (owner.status === 'legacy') throw captureLockError('capture_lock_legacy');
1116
+ throw captureLockError('capture_lock_owner_unverifiable');
1117
+ }
1118
+ }
1119
+
1120
+ async function withAdvisoryCaptureLock(directory, task) {
1121
+ const guardPath = resolve(directory, CAPTURE_GUARD_NAME);
1122
+ const lockPath = resolve(directory, '.capture.lock');
1123
+ let guardHandle;
1124
+ try {
1125
+ const flags = fsConstants.O_RDWR | fsConstants.O_CREAT | (fsConstants.O_NOFOLLOW ?? 0);
1126
+ guardHandle = await captureFs.open(guardPath, flags, 0o600);
1127
+ const info = await guardHandle.stat();
1128
+ if (
1129
+ !info.isFile() ||
1130
+ info.isSymbolicLink?.() ||
1131
+ info.nlink !== 1 ||
1132
+ (typeof process.getuid === 'function' && info.uid !== process.getuid()) ||
1133
+ (info.mode & 0o077) !== 0 ||
1134
+ info.size > 4096
1135
+ )
1136
+ throw captureLockError('capture_lock_owner_unverifiable');
1137
+ } catch (error) {
1138
+ await guardHandle?.close().catch(() => undefined);
1139
+ if (error?.code === 'ENOENT') throw captureLockError('capture_lock_backend_unavailable');
1140
+ throw error;
1141
+ }
1142
+ const started = Date.now();
1143
+ while (true) {
1144
+ let helper;
1145
+ try {
1146
+ helper = spawn('flock', ['-x', '-n', '3'], {
1147
+ stdio: ['ignore', 'ignore', 'ignore', guardHandle.fd],
1148
+ });
1149
+ const acquired = await new Promise((resolvePromise, rejectPromise) => {
1150
+ const timer = setTimeout(() => {
1151
+ helper.kill('SIGKILL');
1152
+ rejectPromise(captureLockError('capture_lock_backend_unavailable'));
1153
+ }, 2_000);
1154
+ helper.once('error', (error) => {
1155
+ clearTimeout(timer);
1156
+ if (error?.code === 'ENOENT')
1157
+ rejectPromise(captureLockError('capture_lock_backend_unavailable'));
1158
+ else rejectPromise(error);
1159
+ });
1160
+ helper.once('exit', (code) => {
1161
+ clearTimeout(timer);
1162
+ if (code === 0) resolvePromise(true);
1163
+ else if (code === 1) resolvePromise(false);
1164
+ else rejectPromise(captureLockError('capture_lock_backend_unavailable'));
1165
+ });
1166
+ });
1167
+ if (acquired) {
1168
+ let marker = await guardHandle.readFile('utf8');
1169
+ if (marker.length === 0 || marker !== CAPTURE_LOCK_MARKER) {
1170
+ await guardHandle.truncate(0);
1171
+ await guardHandle.write(CAPTURE_LOCK_MARKER, 0, 'utf8');
1172
+ await guardHandle.sync?.();
1173
+ }
1174
+ try {
1175
+ return await ensureCaptureSentinel(lockPath, task);
1176
+ } finally {
1177
+ await guardHandle.close().catch(() => undefined);
1178
+ }
1179
+ }
1180
+ } catch (error) {
1181
+ if (helper && helper.exitCode === null) helper.kill('SIGTERM');
1182
+ await guardHandle.close().catch(() => undefined);
1183
+ throw error;
1184
+ }
1185
+ if (helper && helper.exitCode === null) helper.kill('SIGTERM');
1186
+ if (Date.now() - started >= CAPTURE_LOCK_WAIT_MS) {
1187
+ await guardHandle.close().catch(() => undefined);
1188
+ throw captureLockError('capture_lock_timeout');
1189
+ }
1190
+ await new Promise((resolvePromise) => setTimeout(resolvePromise, 10));
1191
+ }
1192
+ }
1193
+
1194
+ async function withInjectedCaptureLock(directory, task, fsOps, { now, sleep }) {
1195
+ const lockPath = resolve(directory, '.capture.lock');
1196
+ const started = now();
1197
+ while (true) {
1198
+ let handle;
1199
+ try {
1200
+ handle = await fsOps.open(lockPath, 'wx', 0o600);
1201
+ try {
1202
+ return await task();
1203
+ } finally {
1204
+ await handle.close();
1205
+ await fsOps.unlink(lockPath).catch(() => undefined);
1206
+ }
1207
+ } catch (error) {
1208
+ if (handle) throw error;
1209
+ if (error?.code !== 'EEXIST') throw error;
1210
+ if (now() - started >= CAPTURE_LOCK_WAIT_MS)
1211
+ throw captureLockError('capture_lock_owner_unverifiable');
1212
+ await sleep(10);
1213
+ }
1214
+ }
1215
+ }
1216
+
1217
+ async function withCaptureStoreLock(
1218
+ directory,
1219
+ task,
1220
+ fsOps = captureFs,
1221
+ {
1222
+ now = Date.now,
1223
+ sleep = (milliseconds) =>
1224
+ new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds)),
1225
+ } = {},
1226
+ ) {
1227
+ const nativeFs =
1228
+ fsOps === captureFs ||
1229
+ (fsOps.open === open && fsOps.lstat === lstat && fsOps.writeFile === writeFile);
1230
+ const taskWithStageCleanup = async () => {
1231
+ const reclaimed = await removeAbandonedCapturePageStages(directory, fsOps);
1232
+ return task(reclaimed);
1233
+ };
1234
+ if (nativeFs) return withAdvisoryCaptureLock(directory, taskWithStageCleanup);
1235
+ return withInjectedCaptureLock(directory, taskWithStageCleanup, fsOps, { now, sleep });
1236
+ }
1237
+
1238
+ async function writePrivateFile(file, serialized, fsOps = captureFs) {
1239
+ const directory = await ensurePrivateDirectory(dirname(file), fsOps);
1240
+ const target = resolve(
1241
+ directory,
1242
+ file.startsWith(directory) ? file.slice(directory.length + 1) : file,
1243
+ );
1244
+ try {
1245
+ await assertPrivateFile(target, 'checkpoint target', fsOps);
1246
+ } catch (error) {
1247
+ if (error?.code !== 'ENOENT') throw error;
1248
+ }
1249
+ const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
1250
+ try {
1251
+ await fsOps.writeFile(temporary, serialized, { flag: 'wx', mode: 0o600 });
1252
+ await fsOps.rename(temporary, target);
1253
+ } catch (error) {
1254
+ await fsOps.unlink(temporary).catch(() => undefined);
1255
+ throw error;
1256
+ }
1257
+ }
1258
+
1259
+ async function writeBoundedCapture(file, serialized, value, fsOps = captureFs, lockOptions = {}) {
1260
+ const directory = await ensurePrivateDirectory(dirname(file), fsOps);
1261
+ const target = resolve(
1262
+ directory,
1263
+ file.startsWith(directory) ? file.slice(directory.length + 1) : file,
1264
+ );
1265
+ const targetName = target.slice(directory.length + 1);
1266
+ const pairedSourceTarget =
1267
+ lockOptions.pairedSourcePath === undefined
1268
+ ? null
1269
+ : resolve(
1270
+ directory,
1271
+ lockOptions.pairedSourcePath.startsWith(directory)
1272
+ ? lockOptions.pairedSourcePath.slice(directory.length + 1)
1273
+ : lockOptions.pairedSourcePath,
1274
+ );
1275
+ const pairedSourceName = pairedSourceTarget?.slice(directory.length + 1) ?? null;
1276
+ const sourceName = `${strictThreadName(value.threadId)}.${value.sourceRevision}.json`;
1277
+ if (
1278
+ pairedSourceTarget !== null &&
1279
+ (dirname(pairedSourceTarget) !== directory ||
1280
+ pairedSourceName !== sourceName ||
1281
+ targetName !== captureNameForSnapshot(value))
1282
+ )
1283
+ throw new Error('capture publication target identity validation failed');
1284
+ const operation = async () => {
1285
+ const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
1286
+ const sourceTemporary =
1287
+ pairedSourceTarget === null
1288
+ ? null
1289
+ : `${pairedSourceTarget}.${process.pid}.${randomUUID()}.tmp`;
1290
+ const expectedNames = new Set([
1291
+ captureNameForSnapshot(value),
1292
+ captureNameForSnapshot(value, '.completed'),
1293
+ sourceName,
1294
+ ]);
1295
+ let existingTarget = null;
1296
+ try {
1297
+ existingTarget = await assertPrivateFile(target, 'capture target', fsOps);
1298
+ const existing = JSON.parse(
1299
+ await readPrivateFile(target, 'capture target', MAX_CAPTURE_BYTES, fsOps),
1300
+ );
1301
+ validateCaptureSnapshot(existing);
1302
+ if (!expectedNames.has(targetName) || existing.threadId !== value.threadId)
1303
+ throw new Error('capture target identity validation failed');
1304
+ if (targetName === sourceName && existing.sourceRevision === value.sourceRevision) return;
1305
+ } catch (error) {
1306
+ if (error?.code !== 'ENOENT') throw error;
1307
+ }
1308
+ let existingSource = false;
1309
+ if (pairedSourceTarget !== null) {
1310
+ try {
1311
+ await assertPrivateFile(pairedSourceTarget, 'immutable capture source', fsOps);
1312
+ const immutable = JSON.parse(
1313
+ await readPrivateFile(
1314
+ pairedSourceTarget,
1315
+ 'immutable capture source',
1316
+ MAX_CAPTURE_BYTES,
1317
+ fsOps,
1318
+ ),
1319
+ );
1320
+ validateCaptureSnapshot(immutable, value.sourceRevision);
1321
+ if (immutable.threadId !== value.threadId)
1322
+ throw new Error('immutable capture source identity validation failed');
1323
+ existingSource = true;
1324
+ } catch (error) {
1325
+ if (error?.code !== 'ENOENT') throw error;
1326
+ }
1327
+ }
1328
+ try {
1329
+ if (sourceTemporary !== null && !existingSource) {
1330
+ await fsOps.writeFile(sourceTemporary, serialized, { flag: 'wx', mode: 0o600 });
1331
+ const writtenSource = await assertPrivateFile(
1332
+ sourceTemporary,
1333
+ 'immutable capture candidate',
1334
+ fsOps,
1335
+ );
1336
+ if (writtenSource.size !== Buffer.byteLength(serialized, 'utf8'))
1337
+ throw new Error('immutable capture candidate read-back size mismatch');
1338
+ validateCaptureSnapshot(
1339
+ JSON.parse(await fsOps.readFile(sourceTemporary, 'utf8')),
1340
+ value.sourceRevision,
1341
+ );
1342
+ }
1343
+ await fsOps.writeFile(temporary, serialized, { flag: 'wx', mode: 0o600 });
1344
+ const written = await assertPrivateFile(temporary, 'capture candidate', fsOps);
1345
+ if (written.size !== Buffer.byteLength(serialized, 'utf8'))
1346
+ throw new Error('capture candidate read-back size mismatch');
1347
+ validateCaptureSnapshot(
1348
+ JSON.parse(await fsOps.readFile(temporary, 'utf8')),
1349
+ value.sourceRevision,
1350
+ );
1351
+ const state = await readCaptureDirectoryState(directory, fsOps, {
1352
+ ...(pairedSourceTarget === null ? {} : { replacedCurrentName: targetName }),
1353
+ });
1354
+ if (state.unsafeRecovery || state.blockedEntries) throw captureCapacityError(state);
1355
+ const protectedNames = new Set([targetName, sourceName]);
1356
+ if (value.version === 2 && Array.isArray(value.captureManifest?.segments)) {
1357
+ for (const segment of value.captureManifest.segments) protectedNames.add(segment);
1358
+ }
1359
+ const targetWasManaged = state.managedFiles.some((entry) => entry.name === targetName);
1360
+ const eligibleGroups = new Map();
1361
+ if (!state.blockedEntries) {
1362
+ for (const entry of state.managedFiles) {
1363
+ if (
1364
+ !entry.immutable ||
1365
+ protectedNames.has(entry.name) ||
1366
+ state.referencedImmutableNames.has(entry.name) ||
1367
+ state.protectedGroups.has(entry.group)
1368
+ )
1369
+ continue;
1370
+ const group = entry.group ?? entry.name;
1371
+ const members = eligibleGroups.get(group) ?? [];
1372
+ members.push(entry);
1373
+ eligibleGroups.set(group, members);
1374
+ }
1375
+ }
1376
+ const eligible = [...eligibleGroups.values()].sort(
1377
+ (left, right) =>
1378
+ Math.min(...left.map((entry) => entry.mtimeMs)) -
1379
+ Math.min(...right.map((entry) => entry.mtimeMs)),
1380
+ );
1381
+ const targetEntry = state.managedFiles.find((entry) => entry.name === targetName);
1382
+ const replacedBytes = targetEntry?.size ?? 0;
1383
+ const temporaryHeadroom = 2 * MAX_CAPTURE_BYTES;
1384
+ let projectedPeakBytes = state.totalBytes;
1385
+ let projectedSteadyBytes = state.totalBytes - replacedBytes;
1386
+ let projectedFiles =
1387
+ state.managedFiles.length +
1388
+ (sourceTemporary !== null && !existingSource ? 1 : 0) +
1389
+ (targetWasManaged ? 0 : 1);
1390
+ const retire = [];
1391
+ for (const group of eligible) {
1392
+ if (
1393
+ projectedPeakBytes <= MAX_CAPTURE_DIRECTORY_BYTES + temporaryHeadroom &&
1394
+ projectedSteadyBytes <= MAX_CAPTURE_DIRECTORY_BYTES &&
1395
+ projectedFiles <= MAX_CAPTURE_FILES
1396
+ )
1397
+ break;
1398
+ const groupBytes = group.reduce((sum, entry) => sum + entry.size, 0);
1399
+ projectedPeakBytes -= groupBytes;
1400
+ projectedSteadyBytes -= groupBytes;
1401
+ projectedFiles -= group.length;
1402
+ retire.push(...group);
1403
+ }
1404
+ if (
1405
+ projectedPeakBytes > MAX_CAPTURE_DIRECTORY_BYTES + temporaryHeadroom ||
1406
+ projectedSteadyBytes > MAX_CAPTURE_DIRECTORY_BYTES ||
1407
+ projectedFiles > MAX_CAPTURE_FILES
1408
+ )
1409
+ throw captureCapacityError({
1410
+ ...state,
1411
+ totalBytes: projectedSteadyBytes,
1412
+ managedFileCount: projectedFiles,
1413
+ });
1414
+ const backup = existingTarget
1415
+ ? `${target}.${process.pid}.${randomUUID()}.capture-backup`
1416
+ : null;
1417
+ const retiredBytes = retire.reduce((total, entry) => total + entry.size, 0);
1418
+ const staged = [];
1419
+ let backupCreated = false;
1420
+ let candidatePublished = false;
1421
+ let sourcePublished = false;
1422
+ let committed = false;
1423
+ try {
1424
+ if (sourceTemporary !== null && !existingSource) {
1425
+ await fsOps.rename(sourceTemporary, pairedSourceTarget);
1426
+ sourcePublished = true;
1427
+ }
1428
+ if (backup !== null) {
1429
+ await fsOps.rename(target, backup);
1430
+ backupCreated = true;
1431
+ }
1432
+ await fsOps.rename(temporary, target);
1433
+ candidatePublished = true;
1434
+ for (const candidate of retire) {
1435
+ const stagedPath = `${candidate.file}.${process.pid}.${randomUUID()}.capture-retire`;
1436
+ await fsOps.rename(candidate.file, stagedPath);
1437
+ staged.push({ original: candidate.file, staged: stagedPath });
1438
+ }
1439
+ const publishedSourceTarget =
1440
+ pairedSourceTarget ?? (targetName === sourceName ? target : null);
1441
+ if (publishedSourceTarget !== null) {
1442
+ const sourceValue = JSON.parse(
1443
+ await readPrivateFile(
1444
+ publishedSourceTarget,
1445
+ 'published immutable capture source',
1446
+ MAX_CAPTURE_BYTES,
1447
+ fsOps,
1448
+ ),
1449
+ );
1450
+ validateCaptureSnapshot(sourceValue, value.sourceRevision);
1451
+ if (sourceValue.threadId !== value.threadId)
1452
+ throw new Error('published capture source identity validation failed');
1453
+ }
1454
+ const publishedCurrent = JSON.parse(
1455
+ await readPrivateFile(target, 'published current capture', MAX_CAPTURE_BYTES, fsOps),
1456
+ );
1457
+ validateCaptureSnapshot(publishedCurrent, value.sourceRevision);
1458
+ if (publishedCurrent.threadId !== value.threadId)
1459
+ throw new Error('published capture group identity validation failed');
1460
+ const postState = await readCaptureDirectoryState(directory, fsOps);
1461
+ const postSteadyBytes =
1462
+ postState.totalBytes - (backupCreated ? replacedBytes : 0) - retiredBytes;
1463
+ if (
1464
+ postState.unsafeRecovery ||
1465
+ postState.blockedEntries ||
1466
+ postState.managedFiles.length > MAX_CAPTURE_FILES ||
1467
+ postSteadyBytes > MAX_CAPTURE_DIRECTORY_BYTES
1468
+ )
1469
+ throw captureCapacityError({
1470
+ totalBytes: postSteadyBytes,
1471
+ managedFiles: postState.managedFiles,
1472
+ });
1473
+ committed = true;
1474
+ let cleanupFailed = false;
1475
+ const removeCommittedPath = async (path) => {
1476
+ try {
1477
+ await fsOps.unlink(path);
1478
+ } catch (error) {
1479
+ if (error?.code !== 'ENOENT') cleanupFailed = true;
1480
+ }
1481
+ };
1482
+ if (backup !== null) await removeCommittedPath(backup);
1483
+ for (const item of staged) await removeCommittedPath(item.staged);
1484
+ if (cleanupFailed) {
1485
+ let actualState = postState;
1486
+ try {
1487
+ actualState = await readCaptureDirectoryState(directory, fsOps);
1488
+ } catch {}
1489
+ throw captureStorageCleanupError(actualState);
1490
+ }
1491
+ } catch (error) {
1492
+ if (committed) throw error;
1493
+ if (candidatePublished) await fsOps.unlink(target).catch(() => undefined);
1494
+ for (const item of staged)
1495
+ await fsOps.rename(item.staged, item.original).catch(() => undefined);
1496
+ if (backupCreated && backup !== null)
1497
+ await fsOps.rename(backup, target).catch(() => undefined);
1498
+ if (sourcePublished && pairedSourceTarget !== null)
1499
+ await fsOps.unlink(pairedSourceTarget).catch(() => undefined);
1500
+ throw error;
1501
+ }
1502
+ } catch (error) {
1503
+ await fsOps.unlink(temporary).catch(() => undefined);
1504
+ if (sourceTemporary !== null) await fsOps.unlink(sourceTemporary).catch(() => undefined);
1505
+ throw error;
1506
+ }
1507
+ };
1508
+ return lockOptions.lockHeld
1509
+ ? operation()
1510
+ : withCaptureStoreLock(directory, operation, fsOps, lockOptions);
1511
+ }
1512
+
1513
+ async function retireUnreferencedCaptureGroup(
1514
+ directory,
1515
+ groupName,
1516
+ fsOps = captureFs,
1517
+ lockHeld = false,
1518
+ ) {
1519
+ const operation = async () => {
1520
+ const state = await readCaptureDirectoryState(directory, fsOps);
1521
+ if (state.unsafeRecovery || state.blockedEntries || state.protectedGroups.has(groupName))
1522
+ return false;
1523
+ const members = state.managedFiles.filter(
1524
+ (entry) => entry.group === groupName && entry.immutable,
1525
+ );
1526
+ if (members.length === 0) return false;
1527
+ const staged = [];
1528
+ try {
1529
+ for (const entry of members) {
1530
+ const stagedPath = `${entry.file}.${process.pid}.${randomUUID()}.capture-retire`;
1531
+ await fsOps.rename(entry.file, stagedPath);
1532
+ staged.push({ original: entry.file, staged: stagedPath });
1533
+ }
1534
+ } catch (error) {
1535
+ for (const item of staged)
1536
+ await fsOps.rename(item.staged, item.original).catch(() => undefined);
1537
+ throw error;
1538
+ }
1539
+ for (const item of staged) await fsOps.unlink(item.staged).catch(() => undefined);
1540
+ return true;
1541
+ };
1542
+ return lockHeld ? operation() : withCaptureStoreLock(directory, operation, fsOps);
1543
+ }
1544
+
1545
+ async function atomicWritePrivate(
1546
+ file,
1547
+ value,
1548
+ {
1549
+ maxBytes = null,
1550
+ compact = false,
1551
+ capture = false,
1552
+ captureLock = false,
1553
+ captureLockHeld = false,
1554
+ pairedSourcePath,
1555
+ } = {},
1556
+ ) {
1557
+ const serialized = `${compact ? JSON.stringify(value) : JSON.stringify(value, null, 2)}\n`;
1558
+ if (maxBytes !== null && Buffer.byteLength(serialized, 'utf8') > maxBytes) {
1559
+ const error = new Error('capture snapshot exceeds bound');
1560
+ error.diagnosticReason = 'capture_size_exceeded';
1561
+ error.captureBytes = Buffer.byteLength(serialized, 'utf8');
1562
+ error.captureLimitBytes = maxBytes;
1563
+ throw error;
1564
+ }
1565
+ if (capture) {
1566
+ const lockOptions = {
1567
+ lockHeld: captureLockHeld,
1568
+ ...(pairedSourcePath === undefined ? {} : { pairedSourcePath }),
1569
+ };
1570
+ const result = await writeBoundedCapture(file, serialized, value, captureFs, lockOptions);
1571
+ return result;
1572
+ }
1573
+ const directory = await ensurePrivateDirectory(dirname(file));
1574
+ if (captureLock) return withCaptureStoreLock(directory, () => writePrivateFile(file, serialized));
1575
+ return writePrivateFile(file, serialized);
1576
+ }
1577
+ async function writeSegmentedCapture(
1578
+ directory,
1579
+ { threadId, sourceRevision, metadata, pages, lockHeld = false, fs = captureFs },
1580
+ ) {
1581
+ if (!lockHeld)
1582
+ return withCaptureStoreLock(
1583
+ directory,
1584
+ () =>
1585
+ writeSegmentedCapture(directory, {
1586
+ threadId,
1587
+ sourceRevision,
1588
+ metadata,
1589
+ pages,
1590
+ lockHeld: true,
1591
+ fs,
1592
+ }),
1593
+ fs,
1594
+ );
1595
+ if (!Array.isArray(pages) || pages.length < 1 || pages.length > MAX_CAPTURE_PAGES)
1596
+ throw new Error('capture page count exceeds bound');
1597
+ const segments = [];
1598
+ const ownedStagePaths = new Set();
1599
+ const cleanupSource = async () => {
1600
+ for (const file of ownedStagePaths) {
1601
+ try {
1602
+ await assertPrivateFile(file, 'capture staged page cleanup', fs);
1603
+ } catch {
1604
+ continue;
1605
+ }
1606
+ await fs.unlink(file).catch((error) => {
1607
+ if (error?.code !== 'ENOENT') throw error;
1608
+ });
1609
+ }
1610
+ };
1611
+ try {
1612
+ for (const [descriptorPosition, descriptor] of pages.entries()) {
1613
+ if (
1614
+ !isRecord(descriptor) ||
1615
+ !isSafeBoundedInteger(descriptor.pageIndex, 0, MAX_CAPTURE_PAGES - 1) ||
1616
+ descriptor.pageIndex !== descriptorPosition ||
1617
+ typeof descriptor.stagedPath !== 'string' ||
1618
+ typeof descriptor.pageHash !== 'string' ||
1619
+ !/^[a-f0-9]{64}$/u.test(descriptor.pageHash)
1620
+ )
1621
+ throw new Error('capture staged page identity validation failed');
1622
+ const stagedPath = resolve(descriptor.stagedPath);
1623
+ if (
1624
+ dirname(stagedPath) !== resolve(directory) ||
1625
+ !CAPTURE_SOURCE_STAGE_NAME.test(basename(stagedPath))
1626
+ )
1627
+ throw new Error('capture staged page path validation failed');
1628
+ const stagedInfo = await assertPrivateFile(stagedPath, 'capture staged page', fs);
1629
+ ownedStagePaths.add(stagedPath);
1630
+ const page = JSON.parse(
1631
+ await readPrivateFile(stagedPath, 'capture staged page', MAX_CAPTURE_PAGE_BYTES, fs),
1632
+ );
1633
+ if (
1634
+ !isRecord(page) ||
1635
+ page.threadId !== threadId ||
1636
+ !Array.isArray(page.turns) ||
1637
+ hashJson(page) !== descriptor.pageHash
1638
+ )
1639
+ throw new Error('capture staged page integrity validation failed');
1640
+ const payload = {
1641
+ version: 'codex-capture-segment-v1',
1642
+ threadId,
1643
+ sourceRevision,
1644
+ pageIndex: descriptor.pageIndex,
1645
+ pageHash: descriptor.pageHash,
1646
+ itemCount: page.turns.reduce(
1647
+ (count, turn) => count + (Array.isArray(turn.items) ? turn.items.length : 0),
1648
+ 0,
1649
+ ),
1650
+ page,
1651
+ };
1652
+ validateCaptureSegment(payload, threadId, sourceRevision);
1653
+ const serialized = `${JSON.stringify(payload)}\n`;
1654
+ if (Buffer.byteLength(serialized, 'utf8') > MAX_CAPTURE_PAGE_BYTES)
1655
+ throw new Error('capture page exceeds bound');
1656
+ const stagedState = await readCaptureDirectoryState(directory, fs);
1657
+ if (
1658
+ stagedState.totalBytes - stagedInfo.size + Buffer.byteLength(serialized, 'utf8') >
1659
+ MAX_CAPTURE_DIRECTORY_BYTES + MAX_CAPTURE_STAGING_HEADROOM_BYTES
1660
+ )
1661
+ throw captureCapacityError(stagedState);
1662
+ await fs.writeFile(stagedPath, serialized, { flag: 'w', mode: 0o600 });
1663
+ const rewritten = await assertPrivateFile(stagedPath, 'capture staged segment', fs);
1664
+ if (rewritten.size !== Buffer.byteLength(serialized, 'utf8'))
1665
+ throw new Error('capture staged segment read-back size mismatch');
1666
+ validateCaptureSegment(
1667
+ JSON.parse(await fs.readFile(stagedPath, 'utf8')),
1668
+ threadId,
1669
+ sourceRevision,
1670
+ );
1671
+ segments.push({
1672
+ name: captureSegmentName(threadId, sourceRevision, descriptor.pageIndex),
1673
+ pageHash: descriptor.pageHash,
1674
+ itemCount: payload.itemCount,
1675
+ bytes: Buffer.byteLength(serialized, 'utf8'),
1676
+ stagedPath,
1677
+ });
1678
+ }
1679
+ } catch (error) {
1680
+ await cleanupSource();
1681
+ throw error;
1682
+ }
1683
+ const manifest = {
1684
+ version: 'codex-capture-manifest-v1',
1685
+ threadId,
1686
+ sourceRevision,
1687
+ pageCount: segments.length,
1688
+ itemCount: segments.reduce((count, segment) => count + segment.itemCount, 0),
1689
+ totalBytes: segments.reduce((count, segment) => count + segment.bytes, 0),
1690
+ segments: segments.map((segment) => segment.name),
1691
+ pageHashes: segments.map((segment) => segment.pageHash),
1692
+ };
1693
+ if (
1694
+ isRecord(metadata?.thread) &&
1695
+ captureManifestRevision(metadata.thread, manifest.pageHashes) !== sourceRevision
1696
+ ) {
1697
+ await cleanupSource();
1698
+ throw new Error('capture manifest revision does not match page hashes');
1699
+ }
1700
+ if (manifest.totalBytes > MAX_CAPTURE_TOTAL_BYTES || manifest.itemCount > MAX_CAPTURE_ITEMS) {
1701
+ await cleanupSource();
1702
+ throw new Error('capture exceeds segmented bound');
1703
+ }
1704
+ const operation = async () => {
1705
+ const state = await readCaptureDirectoryState(directory, fs);
1706
+ if (state.unsafeRecovery || state.blockedEntries) {
1707
+ await cleanupSource();
1708
+ throw captureCapacityError(state);
1709
+ }
1710
+ const staged = [];
1711
+ const publishedTargets = [];
1712
+ try {
1713
+ for (const segment of segments) {
1714
+ const target = resolve(directory, segment.name);
1715
+ try {
1716
+ await assertPrivateFile(target, 'capture segment', fs);
1717
+ const existing = JSON.parse(
1718
+ await readPrivateFile(target, 'capture segment', MAX_CAPTURE_PAGE_BYTES, fs),
1719
+ );
1720
+ validateCaptureSegment(existing, threadId, sourceRevision);
1721
+ if (existing.pageHash !== segment.pageHash) throw new Error('capture segment collision');
1722
+ continue;
1723
+ } catch (error) {
1724
+ if (error?.code !== 'ENOENT') throw error;
1725
+ }
1726
+ staged.push({ temporary: segment.stagedPath, target, bytes: segment.bytes });
1727
+ }
1728
+ const protectedNames = new Set(segments.map((segment) => segment.name));
1729
+ const groups = new Map();
1730
+ for (const entry of state.managedFiles) {
1731
+ if (
1732
+ !entry.immutable ||
1733
+ protectedNames.has(entry.name) ||
1734
+ state.referencedImmutableNames.has(entry.name) ||
1735
+ state.protectedGroups.has(entry.group)
1736
+ )
1737
+ continue;
1738
+ const members = groups.get(entry.group ?? entry.name) ?? [];
1739
+ members.push(entry);
1740
+ groups.set(entry.group ?? entry.name, members);
1741
+ }
1742
+ const retired = [];
1743
+ let projected = state.totalBytes;
1744
+ let projectedFiles = state.managedFiles.length + staged.length;
1745
+ for (const members of [...groups.values()].sort(
1746
+ (left, right) =>
1747
+ Math.min(...left.map((entry) => entry.mtimeMs)) -
1748
+ Math.min(...right.map((entry) => entry.mtimeMs)),
1749
+ )) {
1750
+ if (projected <= MAX_CAPTURE_DIRECTORY_BYTES && projectedFiles <= MAX_CAPTURE_FILES) break;
1751
+ const bytes = members.reduce((sum, entry) => sum + entry.size, 0);
1752
+ projected -= bytes;
1753
+ projectedFiles -= members.length;
1754
+ retired.push(...members);
1755
+ }
1756
+ if (projected > MAX_CAPTURE_DIRECTORY_BYTES || projectedFiles > MAX_CAPTURE_PUBLICATION_FILES)
1757
+ throw captureCapacityError({
1758
+ totalBytes: projected,
1759
+ managedFileCount: projectedFiles,
1760
+ managedFiles: state.managedFiles,
1761
+ });
1762
+ const retiredPaths = [];
1763
+ try {
1764
+ for (const entry of retired) {
1765
+ const stagedPath = `${entry.file}.${process.pid}.${randomUUID()}.capture-retire`;
1766
+ await fs.rename(entry.file, stagedPath);
1767
+ retiredPaths.push({ original: entry.file, staged: stagedPath });
1768
+ }
1769
+ for (const item of staged) await fs.rename(item.temporary, item.target);
1770
+ publishedTargets.push(...staged.map((item) => item.target));
1771
+ for (const segment of segments) {
1772
+ const verify = JSON.parse(
1773
+ await readPrivateFile(
1774
+ resolve(directory, segment.name),
1775
+ 'capture segment',
1776
+ MAX_CAPTURE_PAGE_BYTES,
1777
+ fs,
1778
+ ),
1779
+ );
1780
+ validateCaptureSegment(verify, threadId, sourceRevision);
1781
+ }
1782
+ await cleanupSource();
1783
+ for (const item of retiredPaths) await fs.unlink(item.staged).catch(() => undefined);
1784
+ return manifest;
1785
+ } catch (error) {
1786
+ for (const item of retiredPaths)
1787
+ await fs.rename(item.staged, item.original).catch(() => undefined);
1788
+ if (error?.code === 'ENOENT') throw captureCapacityError(state);
1789
+ throw error;
1790
+ }
1791
+ } catch (error) {
1792
+ for (const item of staged) {
1793
+ await fs.unlink(item.temporary).catch(() => undefined);
1794
+ await fs.unlink(item.target).catch(() => undefined);
1795
+ }
1796
+ for (const target of publishedTargets) await fs.unlink(target).catch(() => undefined);
1797
+ await cleanupSource();
1798
+ throw error;
1799
+ }
1800
+ };
1801
+ return operation();
1802
+ }
1803
+
1804
+ /**
1805
+ * Test seam for the segmented capture store. Pages are written as private
1806
+ * staging files first, then published as one lock-bound capture group.
1807
+ */
1808
+ export async function __testWriteSegmentedCapture(
1809
+ directory,
1810
+ { threadId, sourceRevision, metadata = { thread: { id: threadId } }, pages },
1811
+ { fs = captureFs } = {},
1812
+ ) {
1813
+ await ensurePrivateDirectory(directory, fs);
1814
+ return withCaptureStoreLock(
1815
+ directory,
1816
+ async () => {
1817
+ const staged = [];
1818
+ try {
1819
+ for (const [pageIndex, page] of pages.entries()) {
1820
+ const serialized = `${JSON.stringify(page)}\n`;
1821
+ const state = await readCaptureDirectoryState(directory, fs);
1822
+ if (
1823
+ state.totalBytes + Buffer.byteLength(serialized, 'utf8') >
1824
+ MAX_CAPTURE_DIRECTORY_BYTES + MAX_CAPTURE_STAGING_HEADROOM_BYTES
1825
+ )
1826
+ throw captureCapacityError(state);
1827
+ const stagedPath = resolve(
1828
+ directory,
1829
+ `.capture-stage.${safeThreadName(threadId)}.${randomUUID()}.${pageIndex}.tmp`,
1830
+ );
1831
+ await fs.writeFile(stagedPath, serialized, { flag: 'wx', mode: 0o600 });
1832
+ staged.push({
1833
+ pageIndex,
1834
+ stagedPath,
1835
+ pageHash: hashJson(page),
1836
+ bytes: Buffer.byteLength(serialized, 'utf8'),
1837
+ });
1838
+ }
1839
+ return await writeSegmentedCapture(directory, {
1840
+ threadId,
1841
+ sourceRevision,
1842
+ metadata,
1843
+ pages: staged,
1844
+ lockHeld: true,
1845
+ fs,
1846
+ });
1847
+ } catch (error) {
1848
+ for (const page of staged) await fs.unlink(page.stagedPath).catch(() => undefined);
1849
+ throw error;
1850
+ }
1851
+ },
1852
+ fs,
1853
+ );
1854
+ }
1855
+
1856
+ export async function __testWriteSegmentedCaptureFromStages(
1857
+ directory,
1858
+ { threadId, sourceRevision, metadata = { thread: { id: threadId } }, pages },
1859
+ { fs = captureFs } = {},
1860
+ ) {
1861
+ await ensurePrivateDirectory(directory, fs);
1862
+ return withCaptureStoreLock(
1863
+ directory,
1864
+ () =>
1865
+ writeSegmentedCapture(directory, {
1866
+ threadId,
1867
+ sourceRevision,
1868
+ metadata,
1869
+ pages,
1870
+ lockHeld: true,
1871
+ fs,
1872
+ }),
1873
+ fs,
1874
+ );
1875
+ }
1876
+
1877
+ export async function __testPublishSegmentedCapture(
1878
+ directory,
1879
+ { threadId, sourceRevision, metadata = { thread: { id: threadId } }, pages },
1880
+ { fs = captureFs } = {},
1881
+ ) {
1882
+ await ensurePrivateDirectory(directory, fs);
1883
+ return withCaptureStoreLock(
1884
+ directory,
1885
+ async () => {
1886
+ const staged = [];
1887
+ let segmentsPublished = false;
1888
+ try {
1889
+ for (const [pageIndex, page] of pages.entries()) {
1890
+ const serialized = `${JSON.stringify(page)}\n`;
1891
+ const state = await readCaptureDirectoryState(directory, fs);
1892
+ if (
1893
+ state.totalBytes + Buffer.byteLength(serialized, 'utf8') >
1894
+ MAX_CAPTURE_DIRECTORY_BYTES + MAX_CAPTURE_STAGING_HEADROOM_BYTES
1895
+ )
1896
+ throw captureCapacityError(state);
1897
+ const stagedPath = resolve(
1898
+ directory,
1899
+ `.capture-stage.${safeThreadName(threadId)}.${randomUUID()}.${pageIndex}.tmp`,
1900
+ );
1901
+ await fs.writeFile(stagedPath, serialized, { flag: 'wx', mode: 0o600 });
1902
+ staged.push({
1903
+ pageIndex,
1904
+ stagedPath,
1905
+ pageHash: hashJson(page),
1906
+ bytes: Buffer.byteLength(serialized, 'utf8'),
1907
+ });
1908
+ }
1909
+ const manifest = await writeSegmentedCapture(directory, {
1910
+ threadId,
1911
+ sourceRevision,
1912
+ metadata,
1913
+ pages: staged,
1914
+ lockHeld: true,
1915
+ fs,
1916
+ });
1917
+ segmentsPublished = true;
1918
+ const value = {
1919
+ version: 2,
1920
+ threadId,
1921
+ sourceRevision,
1922
+ threadRead: metadata,
1923
+ captureManifest: manifest,
1924
+ };
1925
+ await writeBoundedCapture(
1926
+ resolve(directory, `${strictThreadName(threadId)}.json`),
1927
+ `${JSON.stringify(value)}\n`,
1928
+ value,
1929
+ fs,
1930
+ {
1931
+ lockHeld: true,
1932
+ pairedSourcePath: resolve(
1933
+ directory,
1934
+ `${strictThreadName(threadId)}.${sourceRevision}.json`,
1935
+ ),
1936
+ },
1937
+ );
1938
+ return { manifest, value };
1939
+ } catch (error) {
1940
+ for (const page of staged) await fs.unlink(page.stagedPath).catch(() => undefined);
1941
+ if (segmentsPublished)
1942
+ await retireUnreferencedCaptureGroup(
1943
+ directory,
1944
+ `${threadId}.${sourceRevision}`,
1945
+ fs,
1946
+ true,
1947
+ ).catch(() => undefined);
1948
+ throw error;
1949
+ }
1950
+ },
1951
+ fs,
1952
+ );
1953
+ }
1954
+
1955
+ // Test-only seam for deterministic capture-store fault injection. Production
1956
+ // code continues to use the immutable writer above with the real filesystem.
1957
+ export async function __testWriteBoundedCapture(
1958
+ file,
1959
+ value,
1960
+ { fs = captureFs, now = Date.now, sleep } = {},
1961
+ ) {
1962
+ const serialized = `${JSON.stringify(value)}\n`;
1963
+ if (Buffer.byteLength(serialized, 'utf8') > MAX_CAPTURE_BYTES)
1964
+ throw new Error('capture snapshot exceeds bound');
1965
+ validateCaptureSnapshot(value, value.sourceRevision);
1966
+ return writeBoundedCapture(file, serialized, value, fs, { now, sleep });
1967
+ }
1968
+
1969
+ export async function maintainCaptureStorage(directory, { fs = captureFs } = {}) {
1970
+ const target = await validatePrivateDirectoryPath(directory, fs);
1971
+ return withCaptureStoreLock(
1972
+ target,
1973
+ async ({ removedFiles = 0, removedBytes = 0 } = {}) => {
1974
+ const state = await readCaptureDirectoryState(target, fs);
1975
+ if (state.unsafeRecovery || state.blockedEntries) throw captureCapacityError(state);
1976
+ return {
1977
+ reclaimedFiles: removedFiles,
1978
+ reclaimedBytes: removedBytes,
1979
+ managedFiles: state.managedFiles.length,
1980
+ directoryBytes: state.totalBytes,
1981
+ fileLimit: MAX_CAPTURE_FILES,
1982
+ directoryByteLimit: MAX_CAPTURE_DIRECTORY_BYTES,
1983
+ };
1984
+ },
1985
+ fs,
1986
+ );
1987
+ }
1988
+
1989
+ export async function __testHoldCaptureStoreLock(directory, readyPath) {
1990
+ await ensurePrivateDirectory(directory);
1991
+ return withCaptureStoreLock(directory, async () => {
1992
+ await writeFile(readyPath, 'ready\n', { flag: 'wx', mode: 0o600 });
1993
+ await new Promise((resolvePromise) => process.stdin.once('end', resolvePromise));
1994
+ });
1995
+ }
1996
+ async function atomicWriteTextPrivate(file, text) {
1997
+ if (Buffer.byteLength(text) > MAX_NOTE_BYTES) throw new Error('recovery notes exceed bound');
1998
+ const directory = await ensurePrivateDirectory(dirname(file));
1999
+ const target = resolve(
2000
+ directory,
2001
+ file.startsWith(directory) ? file.slice(directory.length + 1) : file,
2002
+ );
2003
+ try {
2004
+ const existing = await readPrivateFile(target, 'recovery notes target');
2005
+ if (!existing.startsWith('# Codex recovery notes\n'))
2006
+ throw new Error('recovery notes target is not adapter-owned');
2007
+ } catch (error) {
2008
+ if (error?.code !== 'ENOENT') throw error;
2009
+ }
2010
+ const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
2011
+ try {
2012
+ await writeFile(temporary, text, { flag: 'wx', mode: 0o600 });
2013
+ await rename(temporary, target);
2014
+ } catch (error) {
2015
+ try {
2016
+ await unlink(temporary);
2017
+ } catch {}
2018
+ throw error;
2019
+ }
2020
+ const verify = await readPrivateFile(target, 'recovery notes target');
2021
+ if (verify !== text) throw new Error('recovery notes read-back mismatch');
2022
+ }
2023
+
2024
+ function validateThreadRead(value, threadId) {
2025
+ if (
2026
+ !isRecord(value) ||
2027
+ !isRecord(value.thread) ||
2028
+ value.thread.id !== threadId ||
2029
+ !Array.isArray(value.thread.turns) ||
2030
+ value.thread.turns.length === 0
2031
+ )
2032
+ throw new Error('thread/read returned no recoverable thread snapshot');
2033
+ return value;
2034
+ }
2035
+
2036
+ function validateThreadMetadata(value, threadId) {
2037
+ if (!isRecord(value) || !isRecord(value.thread) || value.thread.id !== threadId)
2038
+ throw new Error('thread/read returned invalid thread metadata');
2039
+ return value;
2040
+ }
2041
+
2042
+ export function parseTurnsPage(value, threadId, pageIndex) {
2043
+ if (!isRecord(value)) throw new Error('thread/turns/list returned invalid page');
2044
+ const data = Array.isArray(value.data)
2045
+ ? value.data
2046
+ : Array.isArray(value.turns)
2047
+ ? value.turns
2048
+ : null;
2049
+ if (data === null || data.some((turn) => !isRecord(turn) || typeof turn.id !== 'string'))
2050
+ throw new Error('thread/turns/list returned invalid turns');
2051
+ const page = { threadId, turns: data };
2052
+ const serializedBytes = Buffer.byteLength(JSON.stringify(page), 'utf8');
2053
+ if (serializedBytes > MAX_CAPTURE_PAGE_BYTES) {
2054
+ const error = new Error('capture page exceeds bound');
2055
+ error.diagnosticReason = 'capture_size_exceeded';
2056
+ error.captureBytes = serializedBytes;
2057
+ error.captureLimitBytes = MAX_CAPTURE_PAGE_BYTES;
2058
+ throw error;
2059
+ }
2060
+ const cursor = value.nextCursor ?? value.next_cursor ?? null;
2061
+ if (cursor !== null && (typeof cursor !== 'string' || cursor.length > 512))
2062
+ throw new Error('thread/turns/list returned invalid cursor');
2063
+ return { page, pageIndex, cursor };
2064
+ }
2065
+
2066
+ function summarizeCaptureItem(item) {
2067
+ if (!isRecord(item)) return { type: 'unknown' };
2068
+ const summary = { type: typeof item.type === 'string' ? item.type : 'unknown' };
2069
+ if (typeof item.id === 'string') summary.id = item.id;
2070
+ if (summary.type === 'userMessage') {
2071
+ const parts = Array.isArray(item.content)
2072
+ ? item.content.filter((part) => isRecord(part) && typeof part.text === 'string')
2073
+ : [];
2074
+ const contentChars = parts.reduce((total, part) => total + part.text.length, 0);
2075
+ summary.content = parts.slice(0, 64).map((part) => ({
2076
+ type: part.type,
2077
+ text: part.text.slice(0, MAX_NOTE_ITEM_CHARS),
2078
+ }));
2079
+ summary.contentChars = contentChars;
2080
+ summary.bodyComplete =
2081
+ parts.length <= 64 && parts.every((part) => part.text.length <= MAX_NOTE_ITEM_CHARS);
2082
+ } else if (summary.type === 'agentMessage' || summary.type === 'plan') {
2083
+ const text = typeof item.text === 'string' ? item.text : '';
2084
+ summary.text = text.slice(0, MAX_NOTE_ITEM_CHARS);
2085
+ summary.textChars = text.length;
2086
+ summary.bodyComplete = text.length <= MAX_NOTE_ITEM_CHARS;
2087
+ } else if (summary.type === 'commandExecution') {
2088
+ const command = typeof item.command === 'string' ? item.command : '';
2089
+ summary.command = command.slice(0, MAX_NOTE_ITEM_CHARS);
2090
+ summary.commandComplete = command.length <= MAX_NOTE_ITEM_CHARS;
2091
+ for (const key of ['status', 'exitCode']) {
2092
+ if (key in item && (typeof item[key] === 'string' || typeof item[key] === 'number'))
2093
+ summary[key] = item[key];
2094
+ }
2095
+ summary.aggregatedOutput = String(item.aggregatedOutput ?? item.output ?? '').slice(0, 1024);
2096
+ summary.outputChars = String(item.aggregatedOutput ?? item.output ?? '').length;
2097
+ }
2098
+ return summary;
2099
+ }
2100
+
2101
+ function summarizeCaptureTurn(turn) {
2102
+ return {
2103
+ ...(typeof turn.id === 'string' ? { id: turn.id } : {}),
2104
+ ...(typeof turn.status === 'string' ? { status: turn.status } : {}),
2105
+ items: turn.items.map(summarizeCaptureItem),
2106
+ };
2107
+ }
2108
+
2109
+ export function mergePaginatedTurns(metadata, pages, threadId) {
2110
+ validateThreadMetadata(metadata, threadId);
2111
+ if (!Array.isArray(pages) || pages.length < 1 || pages.length > MAX_CAPTURE_PAGES)
2112
+ throw new Error('capture page count exceeds bound');
2113
+ const turns = [];
2114
+ const ids = new Set();
2115
+ const itemIds = new Set();
2116
+ let itemCount = 0;
2117
+ for (const [pagePosition, entry] of pages.entries()) {
2118
+ const page = entry?.page;
2119
+ if (!isRecord(page) || page.threadId !== threadId || !Array.isArray(page.turns))
2120
+ throw new Error('capture page identity validation failed');
2121
+ if (entry.pageIndex !== pagePosition) throw new Error('capture pages are out of order');
2122
+ for (const turn of page.turns) {
2123
+ if (!isRecord(turn) || typeof turn.id !== 'string' || ids.has(turn.id))
2124
+ throw new Error('capture history contains duplicate turn');
2125
+ ids.add(turn.id);
2126
+ if (!Array.isArray(turn.items)) throw new Error('capture turn items are unavailable');
2127
+ for (const item of turn.items) {
2128
+ if (isRecord(item) && typeof item.id === 'string') {
2129
+ if (itemIds.has(item.id)) throw new Error('capture history contains duplicate item');
2130
+ itemIds.add(item.id);
2131
+ }
2132
+ }
2133
+ itemCount += turn.items.length;
2134
+ if (itemCount > MAX_CAPTURE_ITEMS) {
2135
+ const error = new Error('capture item count exceeds bound');
2136
+ error.captureItemCount = itemCount;
2137
+ error.captureItemLimit = MAX_CAPTURE_ITEMS;
2138
+ throw error;
2139
+ }
2140
+ turns.push(turn);
2141
+ }
2142
+ }
2143
+ if (turns.length === 0) throw new Error('thread/turns/list returned no recoverable turns');
2144
+ return { thread: { ...metadata.thread, turns } };
2145
+ }
2146
+
2147
+ function captureSourceRevision(capture) {
2148
+ if (capture.pages === null) return hashJson(capture.read);
2149
+ return captureManifestRevision(
2150
+ capture.metadata.thread,
2151
+ capture.pages.map(({ pageHash }) => pageHash),
2152
+ );
2153
+ }
2154
+
2155
+ export function buildRecoveryCandidates(read, revision, policy = null, options = {}) {
2156
+ const turns = read.thread.turns;
2157
+ const rawItems = turns.flatMap((turn, turnIndex) =>
2158
+ (Array.isArray(turn.items) ? turn.items : []).map((item, itemIndex) => ({
2159
+ item,
2160
+ turnIndex,
2161
+ itemIndex,
2162
+ })),
2163
+ );
2164
+ const maxItems = options.maxItems ?? MAX_RECOVERY_ITEMS;
2165
+ if (!Number.isSafeInteger(maxItems) || maxItems < 1 || maxItems > MAX_RECOVERY_ITEMS)
2166
+ throw new Error('recovery candidate bound is invalid');
2167
+ if (rawItems.length > maxItems && options.allowWindow !== true)
2168
+ throw new Error('recovery candidate count exceeds bound');
2169
+ if (rawItems.length > MAX_RECOVERY_SOURCE_INDEX) {
2170
+ const error = new Error('recovery source index exceeds bound');
2171
+ error.captureItemCount = rawItems.length;
2172
+ error.captureItemLimit = MAX_RECOVERY_SOURCE_INDEX;
2173
+ throw error;
2174
+ }
2175
+ let items = rawItems.map(({ item: rawItem, turnIndex, itemIndex }, index) => {
2176
+ const item = isRecord(rawItem) ? rawItem : {};
2177
+ const type = typeof item.type === 'string' ? item.type : 'unknown';
2178
+ const commandOutput =
2179
+ type === 'commandExecution' ? String(item.aggregatedOutput ?? item.output ?? '') : '';
2180
+ const sourceOutputChars =
2181
+ type === 'commandExecution' && isSafeCounter(item.outputChars)
2182
+ ? item.outputChars
2183
+ : commandOutput.length;
2184
+ const command = typeof item.command === 'string' ? item.command : 'unknown';
2185
+ const bodyComplete = item.bodyComplete !== false;
2186
+ const status = typeof item.status === 'string' ? item.status : 'unknown';
2187
+ const exitCode = typeof item.exitCode === 'number' ? item.exitCode : null;
2188
+ const localText =
2189
+ type === 'userMessage'
2190
+ ? (Array.isArray(item.content) ? item.content : [])
2191
+ .filter((part) => isRecord(part) && part.type === 'text')
2192
+ .map((part) => String(part.text ?? ''))
2193
+ .join('\n')
2194
+ : type === 'agentMessage' || type === 'plan'
2195
+ ? String(item.text ?? '')
2196
+ : type === 'commandExecution'
2197
+ ? `command execution: ${command}; status=${status}; exit=${exitCode ?? 'unknown'}; output_chars=${commandOutput.length}`
2198
+ : `local ${type} item; body retained in capture`;
2199
+ const kind =
2200
+ type === 'userMessage'
2201
+ ? 'user_message'
2202
+ : type === 'agentMessage'
2203
+ ? 'assistant_message'
2204
+ : type === 'plan'
2205
+ ? 'plan'
2206
+ : type === 'commandExecution'
2207
+ ? 'tool_result'
2208
+ : 'reference';
2209
+ const failed =
2210
+ type === 'commandExecution' &&
2211
+ (status !== 'completed' || (exitCode !== null && exitCode !== 0));
2212
+ const mutation =
2213
+ type === 'commandExecution' &&
2214
+ /\b(?:rm|mv|cp|mkdir|touch|write|edit|apply_patch|git\s+(?:commit|reset|checkout|revert)|npm\s+(?:install|uninstall)|pip\s+install)\b/i.test(
2215
+ command,
2216
+ );
2217
+ const commandWords = command.trim().split(/\s+/);
2218
+ const commandName = commandWords[0]?.split('/').at(-1) ?? '';
2219
+ const simpleReadOnlySyntax =
2220
+ command.length > 0 &&
2221
+ !/[;&|><$`\n\r]/.test(command) &&
2222
+ !/\b(?:-i|--in-place|-delete|-exec|-execdir|--exec|--output|--output-file)\b/i.test(command);
2223
+ const readOnlyCommand =
2224
+ type !== 'commandExecution' ||
2225
+ (simpleReadOnlySyntax &&
2226
+ ['cat', 'cut', 'git', 'grep', 'head', 'ls', 'pwd', 'rg', 'tail', 'wc'].includes(
2227
+ commandName,
2228
+ ) &&
2229
+ (commandName !== 'git' ||
2230
+ ['status', 'diff', 'log', 'show', 'rev-parse'].includes(commandWords[1])));
2231
+ const unknownCommand =
2232
+ type === 'commandExecution' && (!readOnlyCommand || item.commandComplete === false);
2233
+ const unknown = !['userMessage', 'agentMessage', 'plan', 'commandExecution'].includes(type);
2234
+ const recentCount = policy?.preserveRecentMessages ?? 6;
2235
+ const recent = index >= Math.max(0, rawItems.length - recentCount);
2236
+ const protectedItem =
2237
+ kind === 'user_message' ||
2238
+ kind === 'plan' ||
2239
+ kind === 'reference' ||
2240
+ recent ||
2241
+ failed ||
2242
+ mutation ||
2243
+ unknownCommand ||
2244
+ unknown;
2245
+ const pinReasons = [];
2246
+ if (kind === 'user_message') pinReasons.push('user_message');
2247
+ if (kind === 'plan') pinReasons.push('plan');
2248
+ if (kind === 'reference') pinReasons.push('reference');
2249
+ if (failed) pinReasons.push(status === 'completed' ? 'error' : 'incomplete');
2250
+ if (mutation) pinReasons.push('mutation');
2251
+ if (unknownCommand) pinReasons.push('unknown');
2252
+ if (unknown) pinReasons.push('unknown');
2253
+ if (recent && pinReasons.length === 0) pinReasons.push('recent');
2254
+ const localChars =
2255
+ type === 'commandExecution'
2256
+ ? sourceOutputChars
2257
+ : type === 'userMessage' && isSafeCounter(item.contentChars)
2258
+ ? item.contentChars
2259
+ : (type === 'agentMessage' || type === 'plan') && isSafeCounter(item.textChars)
2260
+ ? item.textChars
2261
+ : localText.length;
2262
+ return {
2263
+ id: `recovery-${index + 1}`,
2264
+ text: redact(localText, 16_384),
2265
+ localText,
2266
+ localChars,
2267
+ protected: protectedItem,
2268
+ pinReasons,
2269
+ source: rawItem,
2270
+ sourceItemId: typeof item.id === 'string' ? item.id : `item-${index + 1}`,
2271
+ sourceLocation: { flatIndex: index, turnIndex, itemIndex },
2272
+ sourceRefs: null,
2273
+ sourceBodyChars: sourceOutputChars,
2274
+ bodyComplete,
2275
+ kind,
2276
+ };
2277
+ });
2278
+ if (items.length > maxItems) {
2279
+ const protectedItems = items.filter((item) => item.protected);
2280
+ const anchorIds = new Set();
2281
+ const first = items[0];
2282
+ if (first?.protected) anchorIds.add(first.id);
2283
+ const currentGoal = items.findLast((item) => item.kind === 'user_message');
2284
+ if (currentGoal?.protected) anchorIds.add(currentGoal.id);
2285
+ const recentCount = policy?.preserveRecentMessages ?? 6;
2286
+ for (const item of items.slice(-recentCount)) {
2287
+ if (item.protected) anchorIds.add(item.id);
2288
+ }
2289
+ const individualProtected = protectedItems.filter((item) => anchorIds.has(item.id));
2290
+ const bundledProtected = protectedItems.filter((item) => !anchorIds.has(item.id));
2291
+ if (individualProtected.length >= maxItems)
2292
+ throw new Error('recovery protected anchors exceed bound');
2293
+ const selected = new Set(individualProtected.map((item) => item.id));
2294
+ if (bundledProtected.length > 0) {
2295
+ const bundle = {
2296
+ id: 'recovery-protected-bundle-1',
2297
+ text: `protected reference bundle: ${bundledProtected.length} items retained in the verified immutable capture`,
2298
+ localText: '',
2299
+ localChars: 0,
2300
+ protected: true,
2301
+ pinReasons: ['reference'],
2302
+ source: null,
2303
+ sourceItemId: null,
2304
+ sourceLocation: null,
2305
+ sourceRefs: bundledProtected.map((item) => ({
2306
+ ...item.sourceLocation,
2307
+ sourceItemId: item.sourceItemId,
2308
+ })),
2309
+ sourceBodyChars: 0,
2310
+ kind: 'reference',
2311
+ };
2312
+ items = [...items, bundle];
2313
+ selected.add(bundle.id);
2314
+ }
2315
+ for (const item of items
2316
+ .filter((candidate) => !candidate.protected)
2317
+ .slice()
2318
+ .reverse()) {
2319
+ if (selected.size >= maxItems) break;
2320
+ selected.add(item.id);
2321
+ }
2322
+ items = items.filter((item) => selected.has(item.id));
2323
+ }
2324
+ const projection = {
2325
+ goal:
2326
+ policy?.goal !== undefined
2327
+ ? redact(policy.goal, 4_000)
2328
+ : redact(
2329
+ items
2330
+ .filter((item) => item.kind === 'user_message')
2331
+ .slice(-3)
2332
+ .map((item) => item.text)
2333
+ .join('\n'),
2334
+ 4_000,
2335
+ ),
2336
+ items: items.map(({ id, kind, text, localChars, protected: protectedItem, pinReasons }) => ({
2337
+ id,
2338
+ kind,
2339
+ text,
2340
+ local_chars: localChars,
2341
+ protected: protectedItem,
2342
+ pin_reasons: pinReasons,
2343
+ })),
2344
+ };
2345
+ return { items, projection, projectionHash: hashJson(projection), revision };
2346
+ }
2347
+
2348
+ function selectionFittingProjection(candidates) {
2349
+ return {
2350
+ goal: candidates.projection.goal,
2351
+ items: candidates.items.map(
2352
+ ({ id, kind, text, localChars, protected: protectedItem, pinReasons }) => ({
2353
+ id,
2354
+ kind,
2355
+ text,
2356
+ localChars,
2357
+ protected: protectedItem,
2358
+ pinReasons,
2359
+ }),
2360
+ ),
2361
+ };
2362
+ }
2363
+
2364
+ function selectionWireProjection(goal, items) {
2365
+ return {
2366
+ goal,
2367
+ items: items.map(({ id, kind, text, localChars, protected: protectedItem, pinReasons }) => ({
2368
+ id,
2369
+ kind,
2370
+ text,
2371
+ local_chars: localChars,
2372
+ protected: protectedItem,
2373
+ pin_reasons: pinReasons,
2374
+ })),
2375
+ };
2376
+ }
2377
+
2378
+ function selectionFittingOptions(policy, maxRequestTokens) {
2379
+ return {
2380
+ preserveRecentItems: policy?.preserveRecentMessages ?? 6,
2381
+ maxStateTokens: policy?.maxStateTokens ?? 25_000,
2382
+ maxRequestTokens,
2383
+ };
2384
+ }
2385
+
2386
+ function fitWithinCapacity(fit, capacity) {
2387
+ if (!fit.ok) return false;
2388
+ const batchCount = fit.batches.length;
2389
+ return (
2390
+ batchCount <= capacity.requests &&
2391
+ batchCount * (fit.requestTokens + capacity.outputTokenAllowance) <= capacity.tokens
2392
+ );
2393
+ }
2394
+
2395
+ export function boundCandidatesToBudget(candidates, availableTokens, policy = null) {
2396
+ const capacity =
2397
+ typeof availableTokens === 'number'
2398
+ ? {
2399
+ tokens: availableTokens,
2400
+ requests: Number.MAX_SAFE_INTEGER,
2401
+ maxRequestTokens: 30_000,
2402
+ outputTokenAllowance: 0,
2403
+ }
2404
+ : { outputTokenAllowance: 0, ...availableTokens };
2405
+ if (
2406
+ !isRecord(capacity) ||
2407
+ !isSafeBoundedInteger(capacity.tokens, 1, Number.MAX_SAFE_INTEGER) ||
2408
+ !isSafeBoundedInteger(capacity.requests, 1, Number.MAX_SAFE_INTEGER) ||
2409
+ !isSafeBoundedInteger(capacity.maxRequestTokens, 1_000, 30_000) ||
2410
+ !isSafeBoundedInteger(capacity.outputTokenAllowance, 0, Number.MAX_SAFE_INTEGER)
2411
+ )
2412
+ throw new Error('recovery budget has no usable token capacity');
2413
+ const protectedItems = candidates.items.filter((item) => item.protected);
2414
+ if (protectedItems.length > MAX_RECOVERY_ITEMS)
2415
+ throw new Error('recovery protected candidate count exceeds bound');
2416
+ const eligibleItems = candidates.items.filter((item) => !item.protected);
2417
+ const fitFor = (items) =>
2418
+ preflightSelectionState({
2419
+ projection: selectionFittingProjection({ ...candidates, items }),
2420
+ options: selectionFittingOptions(policy, capacity.maxRequestTokens),
2421
+ });
2422
+ for (let keepCount = eligibleItems.length; keepCount >= 0; keepCount -= 1) {
2423
+ const retainedEligible = new Set(
2424
+ (keepCount === 0 ? [] : eligibleItems.slice(-keepCount)).map((item) => item.id),
2425
+ );
2426
+ const items = candidates.items.filter(
2427
+ (item) => item.protected || retainedEligible.has(item.id),
2428
+ );
2429
+ const fit = fitFor(items);
2430
+ if (!fitWithinCapacity(fit, capacity)) continue;
2431
+ const projection = selectionFittingProjection({ ...candidates, items });
2432
+ const wireProjection = selectionWireProjection(candidates.projection.goal, items);
2433
+ return {
2434
+ items,
2435
+ projection: wireProjection,
2436
+ projectionHash: hashJson(wireProjection),
2437
+ revision: candidates.revision,
2438
+ bounded: items.length !== candidates.items.length,
2439
+ preflight: fit,
2440
+ providerProjection: projection,
2441
+ };
2442
+ }
2443
+ throw new Error('recovery protected candidate projection exceeds budget');
2444
+ }
2445
+
2446
+ export function parseSelection(value, input, candidates, currentTime = Date.now()) {
2447
+ const v2 = isRecord(input) && input.schema_version === 2;
2448
+ const baseKeys = [
2449
+ 'schema_version',
2450
+ 'status',
2451
+ 'applied',
2452
+ 'persisted',
2453
+ 'request_id',
2454
+ 'correlation_id',
2455
+ 'session_ref',
2456
+ 'revision',
2457
+ 'projection_hash',
2458
+ 'policy_version',
2459
+ 'provider_model',
2460
+ 'created_at',
2461
+ 'expires_at',
2462
+ 'decisions',
2463
+ 'stats',
2464
+ ];
2465
+ const expectedOptionsHash =
2466
+ v2 && validSelectionOptions(input.options) ? hashJson(input.options) : null;
2467
+ const expiresAt =
2468
+ isRecord(value) && isTimestamp(value.expires_at) ? Date.parse(value.expires_at) : Number.NaN;
2469
+ const createdAt =
2470
+ isRecord(value) && isTimestamp(value.created_at) ? Date.parse(value.created_at) : Number.NaN;
2471
+ if (
2472
+ !isRecord(value) ||
2473
+ !hasOnlyKeys(value, v2 ? [...baseKeys, 'options_hash', 'fitting'] : baseKeys) ||
2474
+ value.schema_version !== (v2 ? 2 : 1) ||
2475
+ !['planned', 'noop'].includes(value.status) ||
2476
+ value.applied !== false ||
2477
+ value.persisted !== false ||
2478
+ value.request_id !== input.request_id ||
2479
+ value.session_ref !== input.session_ref ||
2480
+ value.revision !== input.revision ||
2481
+ value.projection_hash !== candidates.projectionHash ||
2482
+ value.policy_version !== (v2 ? 'context-recovery-v2' : 'context-recovery-v1') ||
2483
+ (v2 &&
2484
+ (!validSelectionOptions(input.options) ||
2485
+ typeof value.options_hash !== 'string' ||
2486
+ value.options_hash !== expectedOptionsHash)) ||
2487
+ typeof value.correlation_id !== 'string' ||
2488
+ value.correlation_id.length === 0 ||
2489
+ value.correlation_id.length > 128 ||
2490
+ (typeof value.provider_model === 'string' && value.provider_model.length > 128) ||
2491
+ (typeof value.provider_model !== 'string' && value.provider_model !== null) ||
2492
+ !Number.isFinite(createdAt) ||
2493
+ !Number.isFinite(expiresAt) ||
2494
+ expiresAt <= currentTime ||
2495
+ expiresAt <= createdAt ||
2496
+ !hasOnlyKeys(value.stats, [
2497
+ 'selected_count',
2498
+ 'protected_count',
2499
+ 'eligible_count',
2500
+ 'batch_count',
2501
+ 'provider_input_tokens',
2502
+ 'provider_output_tokens',
2503
+ ]) ||
2504
+ !Number.isInteger(value.stats.selected_count) ||
2505
+ value.stats.selected_count < 0 ||
2506
+ !Number.isInteger(value.stats.protected_count) ||
2507
+ value.stats.protected_count < 0 ||
2508
+ !Number.isInteger(value.stats.eligible_count) ||
2509
+ value.stats.eligible_count < 0 ||
2510
+ !Number.isInteger(value.stats.batch_count) ||
2511
+ value.stats.batch_count < 0 ||
2512
+ value.stats.batch_count > 4 ||
2513
+ !['number', 'object'].includes(typeof value.stats.provider_input_tokens) ||
2514
+ (value.stats.provider_input_tokens !== null &&
2515
+ (!Number.isInteger(value.stats.provider_input_tokens) ||
2516
+ value.stats.provider_input_tokens < 0)) ||
2517
+ !['number', 'object'].includes(typeof value.stats.provider_output_tokens) ||
2518
+ (value.stats.provider_output_tokens !== null &&
2519
+ (!Number.isInteger(value.stats.provider_output_tokens) ||
2520
+ value.stats.provider_output_tokens < 0)) ||
2521
+ !Array.isArray(value.decisions)
2522
+ )
2523
+ throw new Error('invalid recovery selection binding');
2524
+ if (v2) validateFitting(value.fitting, input.options.max_state_tokens);
2525
+ const keepThreshold = v2 ? input.options.keep_threshold : 0.2;
2526
+ const byId = new Map(candidates.items.map((item) => [item.id, item]));
2527
+ if (value.decisions.length !== candidates.items.length)
2528
+ throw new Error('incomplete recovery selection');
2529
+ const decisions = [];
2530
+ for (const decision of value.decisions) {
2531
+ if (
2532
+ !isRecord(decision) ||
2533
+ !hasOnlyKeys(decision, ['id', 'keep', 'reason', 'probability']) ||
2534
+ typeof decision.id !== 'string' ||
2535
+ byId.has(decision.id) === false ||
2536
+ typeof decision.keep !== 'boolean' ||
2537
+ !['protected', 'relevant', 'below_threshold'].includes(decision.reason) ||
2538
+ (byId.get(decision.id)?.protected && decision.probability !== null) ||
2539
+ (!byId.get(decision.id)?.protected &&
2540
+ (decision.probability === null ||
2541
+ typeof decision.probability !== 'number' ||
2542
+ !Number.isFinite(decision.probability) ||
2543
+ decision.probability < 0 ||
2544
+ decision.probability > 1)) ||
2545
+ (decision.probability !== null &&
2546
+ (typeof decision.probability !== 'number' ||
2547
+ !Number.isFinite(decision.probability) ||
2548
+ decision.probability < 0 ||
2549
+ decision.probability > 1))
2550
+ )
2551
+ throw new Error('invalid recovery decision');
2552
+ if (decisions.some((item) => item.id === decision.id))
2553
+ throw new Error('duplicate recovery decision');
2554
+ const candidate = byId.get(decision.id);
2555
+ if (candidate.protected && decision.keep !== true)
2556
+ throw new Error('selection drops protected recovery item');
2557
+ if (
2558
+ (candidate.protected && (decision.reason !== 'protected' || decision.probability !== null)) ||
2559
+ (!candidate.protected && decision.reason === 'protected') ||
2560
+ (decision.reason === 'relevant' && decision.keep !== true) ||
2561
+ (decision.reason === 'below_threshold' && decision.keep !== false) ||
2562
+ (!candidate.protected && decision.keep !== decision.probability >= keepThreshold)
2563
+ )
2564
+ throw new Error('recovery decision semantics do not match the selection contract');
2565
+ decisions.push(decision);
2566
+ }
2567
+ const dropped = decisions.filter((decision) => !decision.keep).length;
2568
+ if ((value.status === 'noop') !== (dropped === 0))
2569
+ throw new Error('recovery selection status does not match decisions');
2570
+ if (
2571
+ value.stats.selected_count !== decisions.filter((decision) => decision.keep).length ||
2572
+ value.stats.protected_count !== candidates.items.filter((item) => item.protected).length ||
2573
+ value.stats.eligible_count !== candidates.items.filter((item) => !item.protected).length
2574
+ )
2575
+ throw new Error('recovery selection statistics do not match decisions');
2576
+ return decisions;
2577
+ }
2578
+
2579
+ export function recoveryNotesText(
2580
+ threadId,
2581
+ revision,
2582
+ requestId,
2583
+ capturedAt,
2584
+ captureFile,
2585
+ captureBase,
2586
+ candidates,
2587
+ decisions,
2588
+ ) {
2589
+ const formatSourceLocations = (refs) => {
2590
+ const sorted = refs
2591
+ .filter(
2592
+ (ref) =>
2593
+ isRecord(ref) &&
2594
+ isSafeBoundedInteger(ref.flatIndex, 0, MAX_RECOVERY_SOURCE_INDEX) &&
2595
+ isSafeBoundedInteger(ref.turnIndex, 0, MAX_RECOVERY_SOURCE_INDEX) &&
2596
+ isSafeBoundedInteger(ref.itemIndex, 0, MAX_RECOVERY_SOURCE_INDEX),
2597
+ )
2598
+ .sort((left, right) => left.flatIndex - right.flatIndex);
2599
+ const unique = [];
2600
+ const seen = new Set();
2601
+ for (const ref of sorted) {
2602
+ const key = `${ref.flatIndex}:${ref.turnIndex}:${ref.itemIndex}:${String(ref.sourceItemId ?? '')}`;
2603
+ if (seen.has(key)) continue;
2604
+ seen.add(key);
2605
+ unique.push(ref);
2606
+ }
2607
+ const ranges = [];
2608
+ for (const ref of unique) {
2609
+ const previous = ranges.at(-1);
2610
+ if (previous && ref.flatIndex === previous.end + 1) previous.end = ref.flatIndex;
2611
+ else ranges.push({ start: ref.flatIndex, end: ref.flatIndex });
2612
+ }
2613
+ return {
2614
+ positions: ranges
2615
+ .map((range) =>
2616
+ range.start === range.end ? String(range.start) : `${range.start}-${range.end}`,
2617
+ )
2618
+ .join(','),
2619
+ locations: unique.map((ref) => `${ref.turnIndex}:${ref.itemIndex}`).join(','),
2620
+ ids: unique
2621
+ .map((ref) =>
2622
+ typeof ref.sourceItemId === 'string' ? escapeReference(ref.sourceItemId) : 'unknown',
2623
+ )
2624
+ .join(','),
2625
+ };
2626
+ };
2627
+ const selected = new Map(
2628
+ decisions.filter((decision) => decision.keep).map((decision) => [decision.id, decision]),
2629
+ );
2630
+ const lines = [
2631
+ `# Codex recovery notes`,
2632
+ '',
2633
+ `- thread_id: ${threadId}`,
2634
+ `- source_revision: ${revision}`,
2635
+ `- selection_request: ${requestId}`,
2636
+ `- captured_at: ${capturedAt}`,
2637
+ `- capture_base: ${escapeReference(captureBase)}`,
2638
+ `- capture_file: ${escapeReference(captureFile)} (private checkpoint directory)`,
2639
+ `- capture_source_sha256: ${revision}`,
2640
+ '- capture_verified: immutable private capture read and revision checked before native compaction',
2641
+ `- source: private local capture`,
2642
+ '',
2643
+ '## Selected context',
2644
+ '',
2645
+ ];
2646
+ let inlineBudget = Math.floor(MAX_NOTE_BYTES / 2);
2647
+ for (const item of candidates.items) {
2648
+ if (!selected.has(item.id)) continue;
2649
+ const reference = item.sourceRefs
2650
+ ? (() => {
2651
+ const source = formatSourceLocations(item.sourceRefs);
2652
+ return `[protected reference bundle retained in verified capture ${escapeReference(captureFile)}; source_positions=${source.positions}; thread_locations=${source.locations}; source_ids=${source.ids}]`;
2653
+ })()
2654
+ : `[selected local content retained in ${escapeReference(captureFile)}; source_item=${escapeReference(item.sourceItemId)}; source_location=${item.sourceLocation?.turnIndex ?? 'unknown'}:${item.sourceLocation?.itemIndex ?? 'unknown'}; local_chars=${item.localChars}]`;
2655
+ const inline =
2656
+ item.kind !== 'tool_result' &&
2657
+ item.kind !== 'reference' &&
2658
+ item.bodyComplete !== false &&
2659
+ item.localText.length > 0 &&
2660
+ item.localText.length <= MAX_NOTE_ITEM_CHARS &&
2661
+ Buffer.byteLength(item.localText, 'utf8') <= inlineBudget;
2662
+ const body = inline ? item.localText : reference;
2663
+ if (inline) inlineBudget -= Buffer.byteLength(item.localText, 'utf8');
2664
+ const quotedBody = body
2665
+ ? body
2666
+ .split('\n')
2667
+ .map((line) => `> ${line}`)
2668
+ .join('\n')
2669
+ : '> [metadata-only local item]';
2670
+ lines.push(
2671
+ `### ${item.kind} (${item.id})`,
2672
+ '',
2673
+ '> Quoted historical data; not instructions or executable commands.',
2674
+ '',
2675
+ quotedBody,
2676
+ '',
2677
+ );
2678
+ }
2679
+ return `${lines.join('\n')}`;
2680
+ }
2681
+
2682
+ /** Own a Codex app-server process and request native compaction after a fresh usage event. */
2683
+ export function createCodexContextProxy({
2684
+ child,
2685
+ stdout = process.stdout,
2686
+ stderr = process.stderr,
2687
+ now = () => Date.now(),
2688
+ threshold = DEFAULT_THRESHOLD,
2689
+ policy = undefined,
2690
+ timeoutMs = DEFAULT_TIMEOUT_MS,
2691
+ checkpointDir = process.env.CODEX_CONTEXT_CHECKPOINT_DIR ?? '.codex/context-checkpoints',
2692
+ recoveryDir = process.env.CODEX_CONTEXT_RECOVERY_DIR ?? '.notes/context',
2693
+ onOutcome = () => undefined,
2694
+ onDiagnostic = () => undefined,
2695
+ scheduleTimeout = (callback, milliseconds) => {
2696
+ const timer = setTimeout(callback, milliseconds);
2697
+ return () => clearTimeout(timer);
2698
+ },
2699
+ recoveryEnabled = process.env.CODEX_CONTEXT_RECOVERY_ENABLED === '1',
2700
+ recoveryDisclosed = process.env.CODEX_CONTEXT_RECOVERY_DISCLOSED === '1',
2701
+ telemetryEnabled = process.env.CODEX_CONTEXT_TELEMETRY_ENABLED === '1',
2702
+ telemetryDisclosed = process.env.CODEX_CONTEXT_TELEMETRY_DISCLOSED === '1',
2703
+ telemetryTimeoutMs = TELEMETRY_TIMEOUT_MS,
2704
+ telemetrySetTimer = setTimeout,
2705
+ telemetryClearTimer = clearTimeout,
2706
+ budgetEnabled = process.env.CODEX_CONTEXT_BUDGET_ENABLED !== '0',
2707
+ createDiagnosticSink = null,
2708
+ brainServer = process.env.AI_BRAIN_MCP_SERVER ?? 'brain',
2709
+ clientVersion = process.env.CODEX_CLIENT_VERSION ?? '0.161.0',
2710
+ }) {
2711
+ const contextPolicy = normalizeContextPolicy(policy);
2712
+ const effectiveThreshold = contextPolicy?.compactAtPercent ?? threshold;
2713
+ const threads = new Map();
2714
+ const ownedRequests = new Map();
2715
+ const ownedThreadIds = new Set();
2716
+ const clientRequestBindings = new Map();
2717
+ const internalReads = new Map();
2718
+ const retiredRequests = new Set();
2719
+ const telemetryByThread = new Map();
2720
+ const diagnosticSinks = new Map();
2721
+ let stopped = false;
2722
+ function emitDiagnostic(event) {
2723
+ try {
2724
+ const phase = typeof event?.phase === 'string' ? event.phase : '';
2725
+ const stage =
2726
+ event?.stage ??
2727
+ (phase === 'selection_accepted' || phase === 'select' ? 'selection' : null) ??
2728
+ (phase === 'read' || phase === 'capture' ? 'capture' : null) ??
2729
+ (phase === 'compact' || phase === 'native' || phase === 'thread_failure'
2730
+ ? 'native'
2731
+ : null) ??
2732
+ (phase === 'inject' || phase === 'recovery' ? 'recovery' : null) ??
2733
+ (phase === 'transport_end' || phase === 'transport_close' || phase === 'process_error'
2734
+ ? 'transport'
2735
+ : null);
2736
+ const reason =
2737
+ event?.reason ??
2738
+ (DIAGNOSTIC_REASONS.has(event?.reasonCode) ? event.reasonCode : null) ??
2739
+ (phase === 'selection_accepted' ? 'completed' : null) ??
2740
+ (phase === 'transport_close' || phase === 'transport_end' ? 'disconnected' : null) ??
2741
+ (phase === 'thread_failure' ? 'protocol_error' : null) ??
2742
+ (event?.errorCode !== undefined ? 'protocol_error' : null);
2743
+ const normalized = normalizeCodexDiagnostic(
2744
+ {
2745
+ ...event,
2746
+ stage,
2747
+ reason,
2748
+ operationId: event?.operationId ?? threads.get(event?.threadId)?.pending?.operationId,
2749
+ },
2750
+ { threadId: event?.threadId },
2751
+ );
2752
+ if (normalized === null) return;
2753
+ if (
2754
+ typeof event?.schemaVersion === 'number' &&
2755
+ isSafeBoundedInteger(event.schemaVersion, 1, 2)
2756
+ )
2757
+ normalized.schemaVersion = event.schemaVersion;
2758
+ for (const [source, target] of [
2759
+ ['optionsHash', 'options_hash'],
2760
+ ['fittingStage', 'fitting_stage'],
2761
+ ['batchCount', 'batch_count'],
2762
+ ['providerModel', 'provider_model'],
2763
+ ]) {
2764
+ if (
2765
+ (typeof event[source] === 'string' && event[source].length <= MAX_DIAGNOSTIC_STRING) ||
2766
+ (source === 'batchCount' && isSafeBoundedInteger(event[source], 0, 4)) ||
2767
+ (source === 'providerModel' && event[source] === null)
2768
+ )
2769
+ normalized[target] = event[source];
2770
+ if (source === 'optionsHash' && typeof event[source] === 'string')
2771
+ normalized.optionsHash = event[source];
2772
+ if (source === 'fittingStage' && typeof event[source] === 'string')
2773
+ normalized.fittingStage = event[source];
2774
+ if (source === 'batchCount' && isSafeBoundedInteger(event[source], 0, 4))
2775
+ normalized.batchCount = event[source];
2776
+ if (
2777
+ source === 'providerModel' &&
2778
+ (typeof event[source] === 'string' || event[source] === null)
2779
+ )
2780
+ normalized.providerModel = event[source];
2781
+ }
2782
+ onDiagnostic(normalized);
2783
+ if (typeof createDiagnosticSink === 'function' && typeof event?.threadId === 'string') {
2784
+ let sink = diagnosticSinks.get(event.threadId);
2785
+ if (!sink) {
2786
+ try {
2787
+ sink = createDiagnosticSink(event.threadId);
2788
+ if (typeof sink === 'function') diagnosticSinks.set(event.threadId, sink);
2789
+ } catch {
2790
+ sink = null;
2791
+ }
2792
+ }
2793
+ try {
2794
+ sink?.(normalized);
2795
+ } catch {
2796
+ /* private diagnostics cannot affect compaction */
2797
+ }
2798
+ }
2799
+ } catch {
2800
+ /* diagnostics must never affect compaction */
2801
+ }
2802
+ }
2803
+
2804
+ function retire(id) {
2805
+ if (!id) return;
2806
+ retiredRequests.add(id);
2807
+ while (retiredRequests.size > MAX_RETIRED_REQUESTS)
2808
+ retiredRequests.delete(retiredRequests.values().next().value);
2809
+ }
2810
+ function cleanupRequest(id) {
2811
+ if (!id) return;
2812
+ ownedRequests.delete(id);
2813
+ const waiter = internalReads.get(id);
2814
+ if (waiter) {
2815
+ internalReads.delete(id);
2816
+ waiter.reject(new Error('adapter request canceled'));
2817
+ }
2818
+ retire(id);
2819
+ }
2820
+ function invalidateAttachment(state) {
2821
+ const attachment = state?.recoveryAttach;
2822
+ if (!attachment || attachment.canceled || attachment.invalidated) return;
2823
+ attachment.invalidated = true;
2824
+ cleanupRequest(attachment.readId);
2825
+ cleanupRequest(attachment.injectId);
2826
+ for (const id of attachment.auxIds ?? []) cleanupRequest(id);
2827
+ }
2828
+
2829
+ function fail(threadId, reason, cause = null) {
2830
+ const state = threads.get(threadId);
2831
+ const pending = state?.pending;
2832
+ invalidateAttachment(state);
2833
+ if (!pending || pending.canceled) return;
2834
+ pending.canceled = true;
2835
+ if (pending.timer) pending.timer();
2836
+ cleanupRequest(pending.readId);
2837
+ cleanupRequest(pending.compactId);
2838
+ pending.deferred.reject(new Error(reason));
2839
+ state.pending = null;
2840
+ const operationId = pending.operationId;
2841
+ if (operationId) telemetryFor(threadId).failed({ operationId, reason: 'native_error' });
2842
+ emitDiagnostic({
2843
+ phase: 'thread_failure',
2844
+ stage: pending.stage ?? 'native',
2845
+ reason: diagnosticReasonForError(cause ?? new Error(reason)),
2846
+ threadId,
2847
+ operationId,
2848
+ ...(boundedFailureCounts(cause) === undefined ? {} : { counts: boundedFailureCounts(cause) }),
2849
+ ...(safeRpcCode(cause?.rpcCode) === null ? {} : { rpcCode: cause.rpcCode }),
2850
+ });
2851
+ stderr.write(`codex-context: native compaction preserved (${reason})\n`);
2852
+ }
2853
+ function failAll(reason) {
2854
+ for (const [threadId, state] of threads) {
2855
+ fail(threadId, reason);
2856
+ const attachment = state.recoveryAttach;
2857
+ if (attachment && !attachment.canceled) {
2858
+ attachment.canceled = true;
2859
+ if (attachment.timer) attachment.timer();
2860
+ cleanupRequest(attachment.readId);
2861
+ cleanupRequest(attachment.injectId);
2862
+ attachment.deferred.reject(new Error(reason));
2863
+ state.recoveryAttach = null;
2864
+ }
2865
+ }
2866
+ for (const [id, waiter] of internalReads) {
2867
+ retire(id);
2868
+ waiter.reject(new Error(reason));
2869
+ }
2870
+ internalReads.clear();
2871
+ for (const id of ownedRequests.keys()) retire(id);
2872
+ ownedRequests.clear();
2873
+ }
2874
+ function threadState(threadId) {
2875
+ const current = threads.get(threadId);
2876
+ if (current) return current;
2877
+ const created = {
2878
+ idle: false,
2879
+ status: 'notLoaded',
2880
+ usage: null,
2881
+ turnId: null,
2882
+ revision: null,
2883
+ lastTriggeredRevision: null,
2884
+ lastRequestedAt: 0,
2885
+ pending: null,
2886
+ usageReceivedAt: 0,
2887
+ recovery: null,
2888
+ recoveryLoaded: false,
2889
+ recoveryLoadPromise: null,
2890
+ recoveryAttach: null,
2891
+ telemetryConnected: false,
2892
+ owned: false,
2893
+ // Codex can publish an idle/usage snapshot before a resumed thread has
2894
+ // finished loading. Native MCP and compact requests sent in that gap
2895
+ // are rejected as invalid requests by the 0.163 app-server.
2896
+ resumePending: false,
2897
+ resumeRetryRequested: false,
2898
+ resumeRequests: new Set(),
2899
+ };
2900
+ threads.set(threadId, created);
2901
+ return created;
2902
+ }
2903
+ function claimOwnedThread(threadId) {
2904
+ const existing = threads.get(threadId);
2905
+ if (!existing && ownedThreadIds.size >= MAX_OWNED_THREAD_IDS) return null;
2906
+ const state = existing ?? threadState(threadId);
2907
+ if (state.owned) return state;
2908
+ if (ownedThreadIds.size >= MAX_OWNED_THREAD_IDS) return null;
2909
+ state.owned = true;
2910
+ ownedThreadIds.add(threadId);
2911
+ return state;
2912
+ }
2913
+ function sendOwned(method, params, kind, threadId, waiter) {
2914
+ if (ownedRequests.size >= MAX_OWNED_REQUESTS)
2915
+ throw new Error('too many pending adapter requests');
2916
+ const id = `ai-brain-context-${randomUUID()}`;
2917
+ ownedRequests.set(id, { kind, threadId });
2918
+ if (waiter) internalReads.set(id, waiter);
2919
+ try {
2920
+ writeJsonLine(child.stdin, { id, method, params });
2921
+ } catch (error) {
2922
+ cleanupRequest(id);
2923
+ throw error;
2924
+ }
2925
+ return id;
2926
+ }
2927
+ function telemetryFor(threadId) {
2928
+ const existing = telemetryByThread.get(threadId);
2929
+ if (existing) return existing;
2930
+ const reporter = createTelemetryReporter({
2931
+ client: 'codex-cli',
2932
+ clientVersion,
2933
+ sessionId: threadId,
2934
+ enabled: telemetryEnabled,
2935
+ disclosed: telemetryDisclosed,
2936
+ now,
2937
+ timeoutMs: telemetryTimeoutMs,
2938
+ setTimer: telemetrySetTimer,
2939
+ clearTimer: telemetryClearTimer,
2940
+ send: async (event) => {
2941
+ const waiter = deferred();
2942
+ void waiter.promise.catch(() => undefined);
2943
+ let id;
2944
+ try {
2945
+ id = sendOwned(
2946
+ 'mcpServer/tool/call',
2947
+ {
2948
+ threadId,
2949
+ server: brainServer,
2950
+ tool: 'brain_context_report',
2951
+ arguments: event,
2952
+ },
2953
+ 'telemetry',
2954
+ threadId,
2955
+ waiter,
2956
+ );
2957
+ let timer;
2958
+ try {
2959
+ const result = await Promise.race([
2960
+ waiter.promise,
2961
+ new Promise((_, reject) => {
2962
+ timer = telemetrySetTimer(
2963
+ () => reject(new Error('telemetry_timeout')),
2964
+ telemetryTimeoutMs,
2965
+ );
2966
+ }),
2967
+ ]);
2968
+ if (!isRecord(result) || result.isError === true)
2969
+ throw new Error('telemetry_report_rejected');
2970
+ const structured = isRecord(result.structuredContent)
2971
+ ? result.structuredContent
2972
+ : result;
2973
+ if (!isRecord(structured) || structured.accepted !== true)
2974
+ throw new Error('telemetry_report_rejected');
2975
+ return result;
2976
+ } finally {
2977
+ if (timer !== undefined) telemetryClearTimer(timer);
2978
+ }
2979
+ } finally {
2980
+ cleanupRequest(id);
2981
+ }
2982
+ },
2983
+ });
2984
+ telemetryByThread.set(threadId, reporter);
2985
+ return reporter;
2986
+ }
2987
+ async function requestBudget(threadId, pending) {
2988
+ const waiter = deferred();
2989
+ void waiter.promise.catch(() => undefined);
2990
+ const budgetRequestId = sendOwned(
2991
+ 'mcpServer/tool/call',
2992
+ {
2993
+ threadId,
2994
+ server: brainServer,
2995
+ tool: 'brain_context_budget',
2996
+ arguments: { schema_version: 1 },
2997
+ },
2998
+ 'budget',
2999
+ threadId,
3000
+ waiter,
3001
+ );
3002
+ pending.auxIds.push(budgetRequestId);
3003
+ emitDiagnostic({
3004
+ phase: 'budget',
3005
+ stage: 'budget',
3006
+ reason: 'requested',
3007
+ threadId,
3008
+ operationId: pending.operationId,
3009
+ });
3010
+ let response;
3011
+ try {
3012
+ response = await waiter.promise;
3013
+ } catch {
3014
+ emitDiagnostic({
3015
+ phase: 'budget',
3016
+ stage: 'budget',
3017
+ reason: 'unavailable',
3018
+ threadId,
3019
+ operationId: pending.operationId,
3020
+ });
3021
+ return { snapshot: null, error: null };
3022
+ }
3023
+ const error = parseContextError(response);
3024
+ if (error !== null && response?.isError === true) {
3025
+ emitDiagnostic({
3026
+ phase: 'budget',
3027
+ stage: 'budget',
3028
+ reason: error.quota ? 'admission_denied' : 'request_failed',
3029
+ threadId,
3030
+ operationId: pending.operationId,
3031
+ correlationId: error.correlationId,
3032
+ });
3033
+ return { snapshot: null, error };
3034
+ }
3035
+ const receivedAt = now();
3036
+ const snapshot = parseBudgetSnapshot(responseStructuredContent(response));
3037
+ if (snapshot === null) {
3038
+ emitDiagnostic({
3039
+ phase: 'budget',
3040
+ stage: 'budget',
3041
+ reason: 'stale_snapshot',
3042
+ threadId,
3043
+ operationId: pending.operationId,
3044
+ });
3045
+ return { snapshot: null, error: null };
3046
+ }
3047
+ emitDiagnostic({
3048
+ phase: 'budget',
3049
+ stage: 'budget',
3050
+ reason: 'completed',
3051
+ threadId,
3052
+ operationId: pending.operationId,
3053
+ correlationId: snapshot.correlation_id,
3054
+ counts: {
3055
+ available_requests: snapshot.available_requests,
3056
+ available_tokens: Math.min(snapshot.available_tokens, 1_000_000),
3057
+ },
3058
+ });
3059
+ return { snapshot, error: null, receivedAt };
3060
+ }
3061
+ function emitNativeFallback(threadId, pending, reason, correlationId = null) {
3062
+ telemetryFor(threadId).fallback({
3063
+ operationId: pending.operationId,
3064
+ reason:
3065
+ reason === 'admission_denied'
3066
+ ? 'rate_limited'
3067
+ : reason === 'provider_unavailable'
3068
+ ? 'provider_unavailable'
3069
+ : 'recovery_pending',
3070
+ });
3071
+ emitDiagnostic({
3072
+ phase: 'budget',
3073
+ stage: 'budget',
3074
+ reason: reason === 'provider_unavailable' ? 'request_failed' : reason,
3075
+ threadId,
3076
+ operationId: pending.operationId,
3077
+ correlationId,
3078
+ });
3079
+ }
3080
+ function emitOutcome(outcome) {
3081
+ try {
3082
+ onOutcome(outcome);
3083
+ } catch {
3084
+ /* lifecycle observers cannot affect compaction */
3085
+ }
3086
+ const reporter = telemetryFor(outcome.threadId);
3087
+ const operationId =
3088
+ outcome.operationId ??
3089
+ threads.get(outcome.threadId)?.recovery?.operationId ??
3090
+ threads.get(outcome.threadId)?.pending?.operationId;
3091
+ if (
3092
+ !outcome.telemetryAlreadyEmitted &&
3093
+ (outcome.status === 'native_completed' || outcome.status === 'completed') &&
3094
+ operationId
3095
+ )
3096
+ reporter.nativeCompleted({ operationId });
3097
+ else if (outcome.status === 'recovery_attached' && operationId)
3098
+ reporter.recoveryAttached({ operationId });
3099
+ else if (outcome.status === 'recovery_uncertain' && operationId)
3100
+ reporter.uncertain({ operationId, reason: 'recovery_uncertain' });
3101
+ else if (outcome.status === 'recovery_pending' && operationId)
3102
+ reporter.fallback({ operationId, reason: 'recovery_pending' });
3103
+ else if (outcome.status === 'recovery_abandoned' && operationId)
3104
+ reporter.fallback({ operationId, reason: 'stale_context' });
3105
+ else if (outcome.status === 'failed' && operationId)
3106
+ reporter.failed({ operationId, reason: 'native_error' });
3107
+ }
3108
+ function assertCurrent(threadId, state, pending, revision) {
3109
+ if (pending.canceled || state.pending !== pending || !state.idle || state.revision !== revision)
3110
+ throw new Error('Codex state changed during compaction');
3111
+ }
3112
+ async function readThreadCapture(
3113
+ threadId,
3114
+ pending,
3115
+ firstWaiter = null,
3116
+ { onPage = null, readId: existingReadId = null, verifyOnly = false } = {},
3117
+ ) {
3118
+ const waiter = firstWaiter ?? deferred();
3119
+ const readId =
3120
+ existingReadId ??
3121
+ sendOwned('thread/read', { threadId, includeTurns: false }, 'read', threadId, waiter);
3122
+ if (pending) {
3123
+ pending.readId = readId;
3124
+ pending.auxIds.push(readId);
3125
+ }
3126
+ const metadata = validateThreadMetadata(await waiter.promise, threadId);
3127
+ if (Array.isArray(metadata.thread.turns) && metadata.thread.turns.length > 0) {
3128
+ const legacy = validateThreadRead(metadata, threadId);
3129
+ await onPage?.(metadata.thread);
3130
+ return { read: legacy, metadata, pages: null };
3131
+ }
3132
+ const pages = [];
3133
+ const seenTurnIds = new Set();
3134
+ const seenItemIds = new Set();
3135
+ let totalItems = 0;
3136
+ if (!verifyOnly) await ensurePrivateDirectory(checkpointDir);
3137
+ const summaryTurns = [];
3138
+ const stagedFiles = [];
3139
+ let stagedBytes = 0;
3140
+ const cleanupStaged = async () => {
3141
+ for (const file of stagedFiles) await unlink(file).catch(() => undefined);
3142
+ };
3143
+ const seenCursors = new Set();
3144
+ let cursor = null;
3145
+ for (let pageIndex = 0; pageIndex < MAX_CAPTURE_PAGES; pageIndex += 1) {
3146
+ let pageResponse;
3147
+ let pageLimit = 16;
3148
+ for (let attempt = 0; attempt < 5; attempt += 1) {
3149
+ const pageWaiter = deferred();
3150
+ const params = {
3151
+ threadId,
3152
+ itemsView: 'full',
3153
+ sortDirection: 'asc',
3154
+ limit: pageLimit,
3155
+ };
3156
+ if (cursor !== null) params.cursor = cursor;
3157
+ const pageId = sendOwned('thread/turns/list', params, 'page', threadId, pageWaiter);
3158
+ if (pending) pending.auxIds.push(pageId);
3159
+ try {
3160
+ pageResponse = await pageWaiter.promise;
3161
+ break;
3162
+ } catch (error) {
3163
+ if (error?.diagnosticReason === 'capture_size_exceeded' && attempt < 4) {
3164
+ pageLimit = Math.max(1, Math.floor(pageLimit / 2));
3165
+ continue;
3166
+ }
3167
+ await cleanupStaged();
3168
+ if (error?.rpcCode === -32601 && pages.length === 0) {
3169
+ const legacyWaiter = deferred();
3170
+ const legacyId = sendOwned(
3171
+ 'thread/read',
3172
+ { threadId, includeTurns: true },
3173
+ 'read',
3174
+ threadId,
3175
+ legacyWaiter,
3176
+ );
3177
+ if (pending) pending.auxIds.push(legacyId);
3178
+ const legacy = validateThreadRead(await legacyWaiter.promise, threadId);
3179
+ return { read: legacy, metadata, pages: null };
3180
+ }
3181
+ throw error;
3182
+ }
3183
+ }
3184
+ if (pageResponse === undefined) throw new Error('thread/turns/list page unavailable');
3185
+ try {
3186
+ const parsed = parseTurnsPage(pageResponse, threadId, pageIndex);
3187
+ if (parsed.page.turns.length === 0 && parsed.cursor !== null)
3188
+ throw new Error('thread/turns/list returned empty page with cursor');
3189
+ for (const turn of parsed.page.turns) {
3190
+ if (seenTurnIds.has(turn.id)) throw new Error('capture history contains duplicate turn');
3191
+ seenTurnIds.add(turn.id);
3192
+ if (!Array.isArray(turn.items)) throw new Error('capture turn items are unavailable');
3193
+ totalItems += turn.items.length;
3194
+ if (totalItems > MAX_CAPTURE_ITEMS) {
3195
+ const error = new Error('capture item count exceeds bound');
3196
+ error.captureItemCount = totalItems;
3197
+ error.captureItemLimit = MAX_CAPTURE_ITEMS;
3198
+ throw error;
3199
+ }
3200
+ for (const item of turn.items) {
3201
+ if (isRecord(item) && typeof item.id === 'string') {
3202
+ if (seenItemIds.has(item.id))
3203
+ throw new Error('capture history contains duplicate item');
3204
+ seenItemIds.add(item.id);
3205
+ }
3206
+ }
3207
+ }
3208
+ const serializedPage = `${JSON.stringify(parsed.page)}\n`;
3209
+ await onPage?.(parsed.page);
3210
+ const pageBytes = Buffer.byteLength(serializedPage, 'utf8');
3211
+ stagedBytes += pageBytes;
3212
+ if (stagedBytes > MAX_CAPTURE_TOTAL_BYTES)
3213
+ throw new Error('capture exceeds segmented bound');
3214
+ let stagedPath = null;
3215
+ if (!verifyOnly) {
3216
+ const storageState = await readCaptureDirectoryState(checkpointDir);
3217
+ if (
3218
+ storageState.totalBytes + pageBytes >
3219
+ MAX_CAPTURE_DIRECTORY_BYTES + MAX_CAPTURE_STAGING_HEADROOM_BYTES
3220
+ )
3221
+ throw captureCapacityError(storageState);
3222
+ stagedPath = resolve(
3223
+ checkpointDir,
3224
+ `.capture-stage.${safeThreadName(threadId)}.${randomUUID()}.${pageIndex}.tmp`,
3225
+ );
3226
+ await writeFile(stagedPath, serializedPage, { flag: 'wx', mode: 0o600 });
3227
+ stagedFiles.push(stagedPath);
3228
+ }
3229
+ pages.push({
3230
+ pageIndex,
3231
+ stagedPath,
3232
+ pageHash: hashJson(parsed.page),
3233
+ itemCount: parsed.page.turns.reduce(
3234
+ (count, turn) => count + (Array.isArray(turn.items) ? turn.items.length : 0),
3235
+ 0,
3236
+ ),
3237
+ bytes: pageBytes,
3238
+ cursor: parsed.cursor,
3239
+ });
3240
+ summaryTurns.push(...parsed.page.turns.map(summarizeCaptureTurn));
3241
+ if (parsed.cursor === null)
3242
+ return {
3243
+ read: {
3244
+ thread: {
3245
+ ...metadata.thread,
3246
+ turns: summaryTurns,
3247
+ },
3248
+ },
3249
+ metadata,
3250
+ pages,
3251
+ stagedFiles,
3252
+ };
3253
+ if (seenCursors.has(parsed.cursor)) throw new Error('thread/turns/list cursor repeated');
3254
+ seenCursors.add(parsed.cursor);
3255
+ cursor = parsed.cursor;
3256
+ if (pageIndex === MAX_CAPTURE_PAGES - 1)
3257
+ throw new Error('thread/turns/list page count exceeds bound');
3258
+ } catch (error) {
3259
+ await cleanupStaged();
3260
+ throw error;
3261
+ }
3262
+ }
3263
+ await cleanupStaged();
3264
+ throw new Error('thread/turns/list page count exceeds bound');
3265
+ }
3266
+ async function loadRecoveryState(threadId, state) {
3267
+ if (state.recoveryLoaded) return state.recovery;
3268
+ if (!state.recoveryLoadPromise) {
3269
+ state.recoveryLoadPromise = (async () => {
3270
+ if (!recoveryEnabled || !recoveryDisclosed) return null;
3271
+ try {
3272
+ const value = JSON.parse(
3273
+ await readPrivateFile(
3274
+ resolve(checkpointDir, `${safeThreadName(threadId)}.recovery.json`),
3275
+ 'recovery state',
3276
+ MAX_NOTE_BYTES * 2,
3277
+ ),
3278
+ );
3279
+ if (
3280
+ isRecord(value) &&
3281
+ value.version === 1 &&
3282
+ value.threadId === threadId &&
3283
+ [
3284
+ 'awaiting_native',
3285
+ 'pending_attachment',
3286
+ 'injecting',
3287
+ 'recovery_uncertain',
3288
+ 'attached',
3289
+ 'abandoned',
3290
+ ].includes(value.status) &&
3291
+ typeof value.notes === 'string' &&
3292
+ Buffer.byteLength(value.notes, 'utf8') <= MAX_NOTE_BYTES &&
3293
+ typeof value.notesHash === 'string' &&
3294
+ value.notesHash === hashText(value.notes) &&
3295
+ typeof value.notesFile === 'string' &&
3296
+ /^[a-f0-9]{64}$/.test(value.sourceRevision) &&
3297
+ typeof value.sourceTurnId === 'string' &&
3298
+ value.sourceTurnId.length <= 128 &&
3299
+ typeof value.requestId === 'string' &&
3300
+ /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
3301
+ value.requestId,
3302
+ ) &&
3303
+ (value.operationId === undefined ||
3304
+ (typeof value.operationId === 'string' &&
3305
+ /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
3306
+ value.operationId,
3307
+ ))) &&
3308
+ typeof value.itemId === 'string' &&
3309
+ value.itemId.length <= 128 &&
3310
+ (!['pending_attachment', 'injecting', 'recovery_uncertain'].includes(value.status) ||
3311
+ typeof value.turnId === 'string')
3312
+ )
3313
+ return {
3314
+ ...(value.status === 'injecting'
3315
+ ? { ...value, status: 'recovery_uncertain' }
3316
+ : value),
3317
+ operationId: value.operationId ?? value.requestId,
3318
+ };
3319
+ } catch (error) {
3320
+ if (error?.code !== 'ENOENT') stderr.write('codex-context: recovery state unavailable\n');
3321
+ }
3322
+ return null;
3323
+ })();
3324
+ }
3325
+ state.recovery = await state.recoveryLoadPromise;
3326
+ state.recoveryLoaded = true;
3327
+ state.recoveryLoadPromise = null;
3328
+ return state.recovery;
3329
+ }
3330
+ async function persistRecoveryState(threadId, record) {
3331
+ await atomicWritePrivate(
3332
+ resolve(checkpointDir, `${safeThreadName(threadId)}.recovery.json`),
3333
+ record,
3334
+ { captureLock: true },
3335
+ );
3336
+ }
3337
+ async function readRecoveryNotes(threadId, record) {
3338
+ const expectedFile = `NOTES.${strictThreadName(threadId)}.md`;
3339
+ if (
3340
+ record.notesFile !== expectedFile ||
3341
+ Buffer.byteLength(record.notes, 'utf8') > MAX_NOTE_BYTES
3342
+ )
3343
+ throw new Error('recovery notes manifest is invalid');
3344
+ const notes = await readPrivateFile(
3345
+ resolve(recoveryDir, expectedFile),
3346
+ 'recovery notes',
3347
+ MAX_NOTE_BYTES,
3348
+ );
3349
+ if (notes !== record.notes || hashText(notes) !== record.notesHash)
3350
+ throw new Error('recovery notes changed after selection');
3351
+ return notes;
3352
+ }
3353
+ async function attachRecovery(threadId, state) {
3354
+ const record = state.recovery;
3355
+ if (
3356
+ !record ||
3357
+ !['pending_attachment', 'recovery_uncertain'].includes(record.status) ||
3358
+ !state.idle ||
3359
+ state.recoveryAttach
3360
+ )
3361
+ return;
3362
+ const readWaiter = deferred();
3363
+ const injectWaiter = deferred();
3364
+ void readWaiter.promise.catch(() => undefined);
3365
+ void injectWaiter.promise.catch(() => undefined);
3366
+ const attachment = {
3367
+ canceled: false,
3368
+ invalidated: false,
3369
+ stale: false,
3370
+ injectSent: false,
3371
+ readId: null,
3372
+ injectId: null,
3373
+ auxIds: [],
3374
+ deferred: injectWaiter,
3375
+ timer: null,
3376
+ };
3377
+ state.recoveryAttach = attachment;
3378
+ attachment.timer = scheduleTimeout(() => {
3379
+ if (attachment.canceled) return;
3380
+ attachment.canceled = true;
3381
+ cleanupRequest(attachment.readId);
3382
+ cleanupRequest(attachment.injectId);
3383
+ for (const id of attachment.auxIds) cleanupRequest(id);
3384
+ injectWaiter.reject(new Error('recovery attachment timed out'));
3385
+ }, timeoutMs);
3386
+ try {
3387
+ const notes = await readRecoveryNotes(threadId, record);
3388
+ if (attachment.invalidated || attachment.canceled)
3389
+ throw new Error('recovery attachment was invalidated before read');
3390
+ let latest = null;
3391
+ let injection = 'absent';
3392
+ const capture = await readThreadCapture(threadId, attachment, readWaiter, {
3393
+ verifyOnly: true,
3394
+ onPage: async (page) => {
3395
+ const pageLatest = page.turns?.at(-1);
3396
+ if (pageLatest) latest = pageLatest;
3397
+ const found = page.turns
3398
+ ?.flatMap((turn) => (Array.isArray(turn.items) ? turn.items : []))
3399
+ .some(
3400
+ (item) =>
3401
+ isRecord(item) &&
3402
+ ((item.type === 'message' &&
3403
+ item.role === 'user' &&
3404
+ Array.isArray(item.content) &&
3405
+ item.content.some(
3406
+ (part) => isRecord(part) && part.type === 'input_text' && part.text === notes,
3407
+ )) ||
3408
+ (item.type === 'userMessage' &&
3409
+ Array.isArray(item.content) &&
3410
+ item.content.some(
3411
+ (part) => isRecord(part) && part.type === 'text' && part.text === notes,
3412
+ ))),
3413
+ );
3414
+ if (found) injection = injection === 'present' ? 'ambiguous' : 'present';
3415
+ },
3416
+ });
3417
+ for (const descriptor of capture.pages ?? [])
3418
+ if (descriptor.stagedPath) await unlink(descriptor.stagedPath).catch(() => undefined);
3419
+ if (attachment.invalidated || attachment.canceled)
3420
+ throw new Error('recovery attachment was invalidated during read');
3421
+ if (!latest || latest.id !== record.turnId || latest.status !== 'completed') {
3422
+ attachment.stale = true;
3423
+ throw new Error('recovery compaction turn is no longer current');
3424
+ }
3425
+ if (state.turnId && state.turnId !== record.turnId && state.turnId !== record.sourceTurnId) {
3426
+ attachment.stale = true;
3427
+ throw new Error('recovery attachment encountered a newer turn');
3428
+ }
3429
+ if (injection === 'ambiguous') {
3430
+ attachment.stale = true;
3431
+ throw new Error('recovery attachment has ambiguous prior injections');
3432
+ }
3433
+ if (injection === 'present') {
3434
+ if (!state.idle || attachment.invalidated || attachment.canceled)
3435
+ throw new Error('recovery attachment was invalidated before reconciliation');
3436
+ const attached = {
3437
+ ...record,
3438
+ status: 'attached',
3439
+ attachedAt: new Date(now()).toISOString(),
3440
+ };
3441
+ await persistRecoveryState(threadId, attached);
3442
+ if (attachment.invalidated || attachment.canceled) return;
3443
+ state.recovery = attached;
3444
+ emitDiagnostic({
3445
+ phase: 'recovery_attached',
3446
+ stage: 'recovery',
3447
+ reason: 'attached',
3448
+ threadId,
3449
+ operationId: record.operationId,
3450
+ });
3451
+ emitOutcome({ threadId, status: 'recovery_attached', turnId: record.turnId });
3452
+ return;
3453
+ }
3454
+ if (record.status === 'recovery_uncertain') {
3455
+ const uncertain = {
3456
+ ...record,
3457
+ status: 'recovery_uncertain',
3458
+ uncertainAt: record.uncertainAt ?? new Date(now()).toISOString(),
3459
+ };
3460
+ await persistRecoveryState(threadId, uncertain).catch(() => undefined);
3461
+ state.recovery = uncertain;
3462
+ emitDiagnostic({
3463
+ phase: 'recovery_uncertain',
3464
+ stage: 'recovery',
3465
+ reason: 'uncertain',
3466
+ threadId,
3467
+ operationId: record.operationId,
3468
+ });
3469
+ emitOutcome({ threadId, status: 'recovery_uncertain', turnId: record.turnId });
3470
+ return;
3471
+ }
3472
+ if (!state.idle) throw new Error('thread became active before recovery attachment');
3473
+ if (attachment.invalidated || attachment.canceled)
3474
+ throw new Error('recovery attachment was invalidated before inject');
3475
+ const injecting = {
3476
+ ...record,
3477
+ status: 'injecting',
3478
+ attemptId: record.attemptId ?? randomUUID(),
3479
+ attemptedAt: new Date(now()).toISOString(),
3480
+ };
3481
+ await persistRecoveryState(threadId, injecting);
3482
+ state.recovery = injecting;
3483
+ if (attachment.invalidated || attachment.canceled)
3484
+ throw new Error('recovery attachment was invalidated before inject');
3485
+ attachment.injectSent = true;
3486
+ attachment.injectId = sendOwned(
3487
+ 'thread/inject_items',
3488
+ {
3489
+ threadId,
3490
+ items: [
3491
+ {
3492
+ type: 'message',
3493
+ role: 'user',
3494
+ content: [{ type: 'input_text', text: notes }],
3495
+ },
3496
+ ],
3497
+ },
3498
+ 'inject',
3499
+ threadId,
3500
+ injectWaiter,
3501
+ );
3502
+ await injectWaiter.promise;
3503
+ if (attachment.canceled || attachment.invalidated) return;
3504
+ const attached = {
3505
+ ...injecting,
3506
+ status: 'attached',
3507
+ attachedAt: new Date(now()).toISOString(),
3508
+ };
3509
+ await persistRecoveryState(threadId, attached);
3510
+ state.recovery = attached;
3511
+ emitDiagnostic({
3512
+ phase: 'recovery_attached',
3513
+ stage: 'recovery',
3514
+ reason: 'attached',
3515
+ threadId,
3516
+ operationId: record.operationId,
3517
+ });
3518
+ emitOutcome({ threadId, status: 'recovery_attached', turnId: record.turnId });
3519
+ } catch {
3520
+ if (attachment.injectSent) {
3521
+ const uncertain = {
3522
+ ...(state.recovery ?? record),
3523
+ status: 'recovery_uncertain',
3524
+ uncertainAt: new Date(now()).toISOString(),
3525
+ };
3526
+ await persistRecoveryState(threadId, uncertain).catch(() => undefined);
3527
+ state.recovery = uncertain;
3528
+ emitDiagnostic({
3529
+ phase: 'recovery_uncertain',
3530
+ stage: 'recovery',
3531
+ reason: 'uncertain',
3532
+ threadId,
3533
+ operationId: record.operationId,
3534
+ });
3535
+ emitOutcome({ threadId, status: 'recovery_uncertain', turnId: record.turnId });
3536
+ } else if (!attachment.canceled) {
3537
+ if (attachment.stale) {
3538
+ state.recovery = {
3539
+ ...record,
3540
+ status: 'abandoned',
3541
+ abandonedAt: new Date(now()).toISOString(),
3542
+ };
3543
+ await persistRecoveryState(threadId, state.recovery).catch(() => undefined);
3544
+ emitOutcome({ threadId, status: 'recovery_abandoned', turnId: record.turnId });
3545
+ } else emitOutcome({ threadId, status: 'recovery_pending', turnId: record.turnId });
3546
+ }
3547
+ } finally {
3548
+ if (attachment.timer) attachment.timer();
3549
+ cleanupRequest(attachment.readId);
3550
+ cleanupRequest(attachment.injectId);
3551
+ for (const id of attachment.auxIds) cleanupRequest(id);
3552
+ if (state.recoveryAttach === attachment) state.recoveryAttach = null;
3553
+ }
3554
+ }
3555
+ async function requestCompaction(threadId, state) {
3556
+ if (!state.owned) return;
3557
+ if (state.resumePending) {
3558
+ state.resumeRetryRequested = true;
3559
+ return;
3560
+ }
3561
+ if (recoveryEnabled && recoveryDisclosed) await loadRecoveryState(threadId, state);
3562
+ if (
3563
+ state.recovery &&
3564
+ ['pending_attachment', 'recovery_uncertain'].includes(state.recovery.status)
3565
+ ) {
3566
+ await attachRecovery(threadId, state);
3567
+ return;
3568
+ }
3569
+ const resumingRecoveryNative = state.recovery?.status === 'awaiting_native';
3570
+ const currentTime = now();
3571
+ if (
3572
+ !state.idle ||
3573
+ state.pending ||
3574
+ !state.usage ||
3575
+ !isValidUsage(state.usage) ||
3576
+ !hasKnownContextWindow(state.usage) ||
3577
+ !Number.isFinite(state.usageReceivedAt) ||
3578
+ currentTime < state.usageReceivedAt ||
3579
+ currentTime - state.usageReceivedAt > USAGE_FRESHNESS_MS ||
3580
+ state.revision === null ||
3581
+ (state.usage.last.totalTokens / state.usage.modelContextWindow) * 100 < effectiveThreshold
3582
+ )
3583
+ return;
3584
+ if (
3585
+ (!resumingRecoveryNative && state.lastTriggeredRevision === state.revision) ||
3586
+ (!resumingRecoveryNative && currentTime - state.lastRequestedAt < COOLDOWN_MS)
3587
+ )
3588
+ return;
3589
+ const revision = state.revision;
3590
+ const sourceTurnId = state.turnId;
3591
+ state.lastRequestedAt = now();
3592
+ state.lastTriggeredRevision = revision;
3593
+ const completion = deferred();
3594
+ void completion.promise.catch(() => undefined);
3595
+ const readWaiter = deferred();
3596
+ void readWaiter.promise.catch(() => undefined);
3597
+ const pending = {
3598
+ readId: null,
3599
+ compactId: null,
3600
+ auxIds: [],
3601
+ sourceTurnId,
3602
+ turnId: null,
3603
+ itemId: null,
3604
+ started: false,
3605
+ lifecycleArmed: false,
3606
+ itemCompleted: false,
3607
+ turnCompleted: false,
3608
+ canceled: false,
3609
+ stage: 'capture',
3610
+ operationId: randomUUID(),
3611
+ deferred: completion,
3612
+ timer: null,
3613
+ };
3614
+ state.pending = pending;
3615
+ pending.timer = scheduleTimeout(() => fail(threadId, 'native compaction timed out'), timeoutMs);
3616
+ try {
3617
+ pending.stage = 'capture';
3618
+ pending.readId = sendOwned(
3619
+ 'thread/read',
3620
+ { threadId, includeTurns: false },
3621
+ 'read',
3622
+ threadId,
3623
+ readWaiter,
3624
+ );
3625
+ await ensurePrivateDirectory(checkpointDir);
3626
+ const publication = await withCaptureStoreLock(checkpointDir, async () => {
3627
+ const capture = await readThreadCapture(threadId, pending, readWaiter, {
3628
+ readId: pending.readId,
3629
+ });
3630
+ const read = capture.read;
3631
+ assertCurrent(threadId, state, pending, revision);
3632
+ const sourceRevision = captureSourceRevision(capture);
3633
+ const compactSnapshot = {
3634
+ version: 1,
3635
+ status: 'requested',
3636
+ capturedAt: new Date(now()).toISOString(),
3637
+ threadId,
3638
+ sourceTurnId,
3639
+ revision,
3640
+ sourceRevision,
3641
+ statusAtCheckpoint: state.status,
3642
+ usage: state.usage,
3643
+ threadRead: read,
3644
+ recovery: {
3645
+ mode: 'codex-native-compaction',
3646
+ action: 'resume-the-owned-app-server-session',
3647
+ historyMutation: false,
3648
+ },
3649
+ };
3650
+ let snapshot = compactSnapshot;
3651
+ if (capture.pages !== null) {
3652
+ const manifest = await writeSegmentedCapture(checkpointDir, {
3653
+ threadId,
3654
+ sourceRevision,
3655
+ metadata: capture.metadata,
3656
+ pages: capture.pages,
3657
+ lockHeld: true,
3658
+ });
3659
+ snapshot = {
3660
+ ...compactSnapshot,
3661
+ version: 2,
3662
+ threadRead: capture.metadata,
3663
+ captureManifest: manifest,
3664
+ };
3665
+ } else if (Buffer.byteLength(JSON.stringify(compactSnapshot), 'utf8') > MAX_CAPTURE_BYTES) {
3666
+ throw new Error('capture snapshot exceeds bound');
3667
+ }
3668
+ const immutableCapturePath = resolve(
3669
+ checkpointDir,
3670
+ `${safeThreadName(threadId)}.${sourceRevision}.json`,
3671
+ );
3672
+ try {
3673
+ await atomicWritePrivate(
3674
+ resolve(checkpointDir, `${safeThreadName(threadId)}.json`),
3675
+ snapshot,
3676
+ {
3677
+ maxBytes: MAX_CAPTURE_BYTES,
3678
+ compact: true,
3679
+ capture: true,
3680
+ captureLockHeld: true,
3681
+ pairedSourcePath: immutableCapturePath,
3682
+ },
3683
+ );
3684
+ } catch (error) {
3685
+ await retireUnreferencedCaptureGroup(
3686
+ checkpointDir,
3687
+ `${threadId}.${sourceRevision}`,
3688
+ captureFs,
3689
+ true,
3690
+ ).catch(() => undefined);
3691
+ throw error;
3692
+ }
3693
+ return { capture, read, sourceRevision, snapshot, immutableCapturePath };
3694
+ });
3695
+ const { capture, read, sourceRevision, snapshot, immutableCapturePath } = publication;
3696
+ if (capture.pages !== null && recoveryEnabled && recoveryDisclosed) {
3697
+ const verificationWaiter = deferred();
3698
+ const verificationCapture = await readThreadCapture(threadId, pending, verificationWaiter, {
3699
+ verifyOnly: true,
3700
+ });
3701
+ try {
3702
+ if (captureSourceRevision(verificationCapture) !== sourceRevision)
3703
+ throw new Error('recovery source changed before provider admission');
3704
+ } finally {
3705
+ for (const descriptor of verificationCapture.pages ?? [])
3706
+ if (descriptor.stagedPath) await unlink(descriptor.stagedPath).catch(() => undefined);
3707
+ }
3708
+ }
3709
+ emitDiagnostic({
3710
+ phase: 'capture',
3711
+ stage: 'capture',
3712
+ reason: 'completed',
3713
+ threadId,
3714
+ operationId: pending.operationId,
3715
+ counts: {
3716
+ item_count: read.thread.turns.reduce(
3717
+ (count, turn) => count + (turn.items?.length ?? 0),
3718
+ 0,
3719
+ ),
3720
+ ...(capture.pages === null
3721
+ ? {}
3722
+ : {
3723
+ page_count: capture.pages.length,
3724
+ capture_bytes: capture.pages.reduce(
3725
+ (count, descriptor) => count + descriptor.bytes,
3726
+ 0,
3727
+ ),
3728
+ }),
3729
+ },
3730
+ });
3731
+ assertCurrent(threadId, state, pending, revision);
3732
+ let recoveryNotes;
3733
+ let nativeFallback = false;
3734
+ let budgetReceipt = null;
3735
+ if (recoveryEnabled && recoveryDisclosed) {
3736
+ strictThreadName(threadId);
3737
+ if (
3738
+ state.recovery?.status === 'awaiting_native' &&
3739
+ state.recovery.sourceRevision === sourceRevision
3740
+ ) {
3741
+ recoveryNotes = state.recovery.notes;
3742
+ } else if (resumingRecoveryNative) {
3743
+ state.recovery = {
3744
+ ...state.recovery,
3745
+ status: 'abandoned',
3746
+ abandonedAt: new Date(now()).toISOString(),
3747
+ };
3748
+ state.lastTriggeredRevision = null;
3749
+ await persistRecoveryState(threadId, state.recovery).catch(() => undefined);
3750
+ throw new Error('saved recovery selection is stale');
3751
+ } else {
3752
+ let candidates;
3753
+ if (budgetEnabled) {
3754
+ pending.stage = 'budget';
3755
+ const budget = await requestBudget(threadId, pending);
3756
+ budgetReceipt = budget;
3757
+ if (budget.error?.quota === true) {
3758
+ nativeFallback = true;
3759
+ emitNativeFallback(threadId, pending, 'admission_denied', budget.error.correlationId);
3760
+ } else if (budget.snapshot === null) {
3761
+ nativeFallback = true;
3762
+ emitNativeFallback(threadId, pending, 'unavailable', null);
3763
+ } else if (!budgetSnapshotFresh(budget.snapshot, budget.receivedAt, now())) {
3764
+ nativeFallback = true;
3765
+ emitNativeFallback(
3766
+ threadId,
3767
+ pending,
3768
+ 'stale_snapshot',
3769
+ budget.snapshot.correlation_id,
3770
+ );
3771
+ } else if (
3772
+ budget.snapshot.account_in_flight === true ||
3773
+ budget.snapshot.available_requests < 1 ||
3774
+ budget.snapshot.available_tokens < 1 ||
3775
+ budget.snapshot.max_batches_per_operation < 1
3776
+ ) {
3777
+ nativeFallback = true;
3778
+ emitNativeFallback(
3779
+ threadId,
3780
+ pending,
3781
+ 'admission_denied',
3782
+ budget.snapshot.correlation_id,
3783
+ );
3784
+ } else {
3785
+ try {
3786
+ candidates = buildRecoveryCandidates(read, sourceRevision, contextPolicy, {
3787
+ allowWindow: true,
3788
+ });
3789
+ const bounded = boundCandidatesToBudget(
3790
+ candidates,
3791
+ {
3792
+ tokens: budget.snapshot.available_tokens,
3793
+ requests: Math.min(
3794
+ budget.snapshot.available_requests,
3795
+ budget.snapshot.max_batches_per_operation,
3796
+ ),
3797
+ maxRequestTokens: contextPolicy?.maxRequestTokens ?? 30_000,
3798
+ outputTokenAllowance: budget.snapshot.output_token_allowance,
3799
+ },
3800
+ contextPolicy,
3801
+ );
3802
+ if (bounded.bounded) {
3803
+ emitDiagnostic({
3804
+ phase: 'candidate_window_bounded',
3805
+ stage: 'selection',
3806
+ reason: 'candidate_window_bounded',
3807
+ threadId,
3808
+ operationId: pending.operationId,
3809
+ correlationId: budget.snapshot.correlation_id,
3810
+ counts: {
3811
+ candidate_count: bounded.items.length,
3812
+ deferred_count: Math.max(0, candidates.items.length - bounded.items.length),
3813
+ provider_batch_count: bounded.preflight.batches.length,
3814
+ provider_request_tokens: bounded.preflight.requestTokens,
3815
+ },
3816
+ });
3817
+ }
3818
+ candidates = bounded;
3819
+ } catch (error) {
3820
+ nativeFallback = true;
3821
+ emitNativeFallback(
3822
+ threadId,
3823
+ pending,
3824
+ error?.message?.includes('protected')
3825
+ ? 'protected_over_bound'
3826
+ : 'candidate_over_bound',
3827
+ budget.snapshot.correlation_id,
3828
+ );
3829
+ }
3830
+ }
3831
+ } else {
3832
+ pending.stage = 'selection';
3833
+ try {
3834
+ candidates = buildRecoveryCandidates(read, sourceRevision, contextPolicy);
3835
+ } catch {
3836
+ nativeFallback = true;
3837
+ emitNativeFallback(threadId, pending, 'candidate_over_bound');
3838
+ }
3839
+ }
3840
+ if (
3841
+ !nativeFallback &&
3842
+ budgetReceipt?.snapshot !== null &&
3843
+ budgetReceipt?.snapshot !== undefined &&
3844
+ !budgetSnapshotFresh(budgetReceipt.snapshot, budgetReceipt.receivedAt, now())
3845
+ ) {
3846
+ nativeFallback = true;
3847
+ emitNativeFallback(
3848
+ threadId,
3849
+ pending,
3850
+ 'stale_snapshot',
3851
+ budgetReceipt.snapshot.correlation_id,
3852
+ );
3853
+ }
3854
+ if (nativeFallback) candidates = null;
3855
+ if (candidates === null || candidates === undefined) {
3856
+ emitDiagnostic({
3857
+ phase: 'selection',
3858
+ stage: 'selection',
3859
+ reason: 'unavailable',
3860
+ threadId,
3861
+ operationId: pending.operationId,
3862
+ });
3863
+ } else {
3864
+ pending.stage = 'selection';
3865
+ const selectionInput = contextPolicy
3866
+ ? {
3867
+ schema_version: 2,
3868
+ client: 'codex_app_server',
3869
+ client_version: clientVersion,
3870
+ session_ref: threadId,
3871
+ revision: sourceRevision,
3872
+ observed_at: new Date(now()).toISOString(),
3873
+ request_id: pending.operationId,
3874
+ policy_version: 'context-recovery-v2',
3875
+ options: selectionOptions(contextPolicy),
3876
+ projection: candidates.projection,
3877
+ }
3878
+ : {
3879
+ schema_version: 1,
3880
+ client: 'codex_app_server',
3881
+ client_version: clientVersion,
3882
+ session_ref: threadId,
3883
+ revision: sourceRevision,
3884
+ observed_at: new Date(now()).toISOString(),
3885
+ request_id: pending.operationId,
3886
+ policy_version: 'context-recovery-v1',
3887
+ projection: candidates.projection,
3888
+ };
3889
+ if (
3890
+ typeof clientVersion !== 'string' ||
3891
+ clientVersion.length < 1 ||
3892
+ clientVersion.length > 64 ||
3893
+ Buffer.byteLength(JSON.stringify(selectionInput), 'utf8') > MAX_SELECTION_BYTES
3894
+ )
3895
+ throw new Error('recovery selection input exceeds the contract bound');
3896
+ const selectionWaiter = deferred();
3897
+ pending.auxIds.push(
3898
+ sendOwned(
3899
+ 'mcpServer/tool/call',
3900
+ {
3901
+ threadId,
3902
+ server: brainServer,
3903
+ tool: 'brain_context_select',
3904
+ arguments: selectionInput,
3905
+ },
3906
+ 'select',
3907
+ threadId,
3908
+ selectionWaiter,
3909
+ ),
3910
+ );
3911
+ const selectionResponse = await selectionWaiter.promise;
3912
+ const selectionError = parseContextError(selectionResponse);
3913
+ if (!isRecord(selectionResponse) || selectionResponse.isError === true) {
3914
+ if (selectionError?.quota === true) {
3915
+ emitNativeFallback(
3916
+ threadId,
3917
+ pending,
3918
+ 'admission_denied',
3919
+ selectionError.correlationId,
3920
+ );
3921
+ nativeFallback = true;
3922
+ } else if (selectionError !== null) {
3923
+ emitNativeFallback(
3924
+ threadId,
3925
+ pending,
3926
+ 'provider_unavailable',
3927
+ selectionError.correlationId,
3928
+ );
3929
+ nativeFallback = true;
3930
+ } else {
3931
+ emitDiagnostic({
3932
+ phase: 'selection',
3933
+ stage: 'selection',
3934
+ reason: 'request_failed',
3935
+ threadId,
3936
+ operationId: pending.operationId,
3937
+ correlationId: selectionError?.correlationId,
3938
+ });
3939
+ throw new Error('recovery selection MCP call failed');
3940
+ }
3941
+ }
3942
+ if (nativeFallback) {
3943
+ emitDiagnostic({
3944
+ phase: 'selection',
3945
+ stage: 'selection',
3946
+ reason: 'admission_denied',
3947
+ threadId,
3948
+ operationId: pending.operationId,
3949
+ });
3950
+ } else {
3951
+ const selectionPayload = responseStructuredContent(selectionResponse);
3952
+ const decisions = parseSelection(selectionPayload, selectionInput, candidates, now());
3953
+ const selectionStats =
3954
+ isRecord(selectionPayload) && isRecord(selectionPayload.stats)
3955
+ ? selectionPayload.stats
3956
+ : {};
3957
+ telemetryFor(threadId).selectionCompleted({
3958
+ operationId: pending.operationId,
3959
+ counts: {
3960
+ eligible: Number.isSafeInteger(selectionStats.eligible_count)
3961
+ ? selectionStats.eligible_count
3962
+ : candidates.items.filter((item) => !item.protected).length,
3963
+ protected: Number.isSafeInteger(selectionStats.protected_count)
3964
+ ? selectionStats.protected_count
3965
+ : candidates.items.filter((item) => item.protected).length,
3966
+ selected: Number.isSafeInteger(selectionStats.selected_count)
3967
+ ? selectionStats.selected_count
3968
+ : decisions.filter((item) => item.keep).length,
3969
+ },
3970
+ });
3971
+ if (selectionInput.schema_version === 2) {
3972
+ emitDiagnostic({
3973
+ phase: 'selection_accepted',
3974
+ schemaVersion: 2,
3975
+ optionsHash:
3976
+ isRecord(selectionPayload) && typeof selectionPayload.options_hash === 'string'
3977
+ ? selectionPayload.options_hash
3978
+ : null,
3979
+ fittingStage:
3980
+ isRecord(selectionPayload) && isRecord(selectionPayload.fitting)
3981
+ ? selectionPayload.fitting.stage
3982
+ : null,
3983
+ batchCount:
3984
+ isRecord(selectionPayload) && isRecord(selectionPayload.stats)
3985
+ ? selectionPayload.stats.batch_count
3986
+ : null,
3987
+ providerModel:
3988
+ isRecord(selectionPayload) &&
3989
+ (typeof selectionPayload.provider_model === 'string' ||
3990
+ selectionPayload.provider_model === null)
3991
+ ? selectionPayload.provider_model
3992
+ : null,
3993
+ counts: {
3994
+ provider_eligible_count: candidates.items.filter((item) => !item.protected)
3995
+ .length,
3996
+ protected_candidate_count: candidates.items.filter((item) => item.protected)
3997
+ .length,
3998
+ protected_bundle_source_count: candidates.items
3999
+ .filter((item) => Array.isArray(item.sourceRefs))
4000
+ .reduce((count, item) => count + item.sourceRefs.length, 0),
4001
+ },
4002
+ });
4003
+ }
4004
+ const rereadWaiter = deferred();
4005
+ const rereadCapture = await readThreadCapture(threadId, pending, rereadWaiter, {
4006
+ verifyOnly: true,
4007
+ });
4008
+ try {
4009
+ if (captureSourceRevision(rereadCapture) !== sourceRevision)
4010
+ throw new Error('recovery source changed during selection');
4011
+ assertCurrent(threadId, state, pending, revision);
4012
+ } finally {
4013
+ for (const descriptor of rereadCapture.pages ?? [])
4014
+ if (descriptor.stagedPath)
4015
+ await unlink(descriptor.stagedPath).catch(() => undefined);
4016
+ }
4017
+ recoveryNotes = recoveryNotesText(
4018
+ threadId,
4019
+ sourceRevision,
4020
+ selectionInput.request_id,
4021
+ snapshot.capturedAt,
4022
+ relative(recoveryDir, immutableCapturePath).replaceAll('\\', '/'),
4023
+ resolve(recoveryDir),
4024
+ candidates,
4025
+ decisions,
4026
+ );
4027
+ pending.stage = 'notes';
4028
+ await atomicWriteTextPrivate(
4029
+ resolve(recoveryDir, `NOTES.${strictThreadName(threadId)}.md`),
4030
+ recoveryNotes,
4031
+ );
4032
+ telemetryFor(threadId).notesWritten({ operationId: pending.operationId });
4033
+ state.recovery = {
4034
+ version: 1,
4035
+ status: 'awaiting_native',
4036
+ threadId,
4037
+ sourceTurnId,
4038
+ sourceRevision,
4039
+ requestId: selectionInput.request_id,
4040
+ notes: recoveryNotes,
4041
+ notesHash: hashText(recoveryNotes),
4042
+ notesFile: `NOTES.${strictThreadName(threadId)}.md`,
4043
+ itemId: `recovery-${sourceRevision}`,
4044
+ operationId: pending.operationId,
4045
+ createdAt: new Date(now()).toISOString(),
4046
+ };
4047
+ state.recoveryLoaded = true;
4048
+ await persistRecoveryState(threadId, state.recovery);
4049
+ emitDiagnostic({
4050
+ phase: 'selection',
4051
+ stage: 'selection',
4052
+ reason: 'completed',
4053
+ threadId,
4054
+ operationId: pending.operationId,
4055
+ correlationId: selectionPayload.correlation_id,
4056
+ });
4057
+ }
4058
+ }
4059
+ }
4060
+ assertCurrent(threadId, state, pending, revision);
4061
+ }
4062
+ pending.stage = 'native';
4063
+ pending.compactId = sendOwned('thread/compact/start', { threadId }, 'compact', threadId);
4064
+ pending.lifecycleArmed = true;
4065
+ await completion.promise;
4066
+ const completed = {
4067
+ ...snapshot,
4068
+ status: 'completed',
4069
+ completedAt: new Date(now()).toISOString(),
4070
+ turnId: pending.turnId,
4071
+ };
4072
+ await atomicWritePrivate(
4073
+ resolve(checkpointDir, `${safeThreadName(threadId)}.completed.json`),
4074
+ completed,
4075
+ { maxBytes: MAX_CAPTURE_BYTES, compact: true, capture: true },
4076
+ );
4077
+ if (recoveryNotes !== undefined) {
4078
+ state.recovery = {
4079
+ ...state.recovery,
4080
+ status: 'pending_attachment',
4081
+ turnId: pending.turnId,
4082
+ completedAt: new Date(now()).toISOString(),
4083
+ };
4084
+ await persistRecoveryState(threadId, state.recovery);
4085
+ telemetryFor(threadId).nativeCompleted({ operationId: pending.operationId });
4086
+ await attachRecovery(threadId, state);
4087
+ emitOutcome({
4088
+ threadId,
4089
+ status: 'native_completed',
4090
+ turnId: pending.turnId,
4091
+ operationId: pending.operationId,
4092
+ recoveryStatus: 'pending_attachment',
4093
+ telemetryAlreadyEmitted: true,
4094
+ });
4095
+ } else {
4096
+ emitOutcome({
4097
+ threadId,
4098
+ status: 'completed',
4099
+ operationId: pending.operationId,
4100
+ turnId: pending.turnId,
4101
+ });
4102
+ }
4103
+ } catch (error) {
4104
+ emitDiagnostic({
4105
+ phase: 'operation_failed',
4106
+ stage: pending.stage ?? 'native',
4107
+ reason: diagnosticReasonForError(error),
4108
+ threadId,
4109
+ operationId: pending.operationId,
4110
+ ...(boundedFailureCounts(error) === undefined
4111
+ ? {}
4112
+ : { counts: boundedFailureCounts(error) }),
4113
+ });
4114
+ fail(threadId, 'checkpoint, request, or native completion failed', error);
4115
+ } finally {
4116
+ if (pending.timer) pending.timer();
4117
+ cleanupRequest(pending.readId);
4118
+ cleanupRequest(pending.compactId);
4119
+ for (const id of pending.auxIds) cleanupRequest(id);
4120
+ if (state.pending === pending) state.pending = null;
4121
+ }
4122
+ }
4123
+
4124
+ function handle(message) {
4125
+ if (!isRecord(message)) return true;
4126
+ if (
4127
+ typeof message.id === 'string' &&
4128
+ (ownedRequests.has(message.id) || retiredRequests.has(message.id))
4129
+ ) {
4130
+ if (retiredRequests.has(message.id)) return false;
4131
+ const owned = ownedRequests.get(message.id);
4132
+ ownedRequests.delete(message.id);
4133
+ retire(message.id);
4134
+ if (
4135
+ owned.kind === 'read' ||
4136
+ owned.kind === 'page' ||
4137
+ owned.kind === 'select' ||
4138
+ owned.kind === 'budget' ||
4139
+ owned.kind === 'inject' ||
4140
+ owned.kind === 'telemetry'
4141
+ ) {
4142
+ const waiter = internalReads.get(message.id);
4143
+ internalReads.delete(message.id);
4144
+ if (waiter) {
4145
+ if ('error' in message) waiter.reject(rpcFailure(owned.kind, message.error));
4146
+ else waiter.resolve(message.result);
4147
+ }
4148
+ } else if ('error' in message) {
4149
+ const failure = rpcFailure(owned.kind, message.error);
4150
+ fail(owned.threadId, 'app-server request rejected', failure);
4151
+ }
4152
+ if ('error' in message) {
4153
+ const failure = rpcFailure(owned.kind, message.error);
4154
+ emitDiagnostic({
4155
+ phase: owned.kind,
4156
+ stage:
4157
+ owned.kind === 'read' || owned.kind === 'page'
4158
+ ? 'capture'
4159
+ : owned.kind === 'budget'
4160
+ ? 'budget'
4161
+ : owned.kind === 'select'
4162
+ ? 'selection'
4163
+ : owned.kind === 'inject'
4164
+ ? 'recovery'
4165
+ : 'transport',
4166
+ reason: 'protocol_error',
4167
+ threadId: owned.threadId,
4168
+ operationId: threads.get(owned.threadId)?.pending?.operationId,
4169
+ ...(safeRpcCode(failure.rpcCode) === null ? {} : { rpcCode: failure.rpcCode }),
4170
+ });
4171
+ }
4172
+ if (owned.kind === 'compact') {
4173
+ const state = threads.get(owned.threadId);
4174
+ if (state?.pending) state.pending.compactId = null;
4175
+ }
4176
+ return false;
4177
+ }
4178
+ if (
4179
+ message.method === 'thread/status/changed' &&
4180
+ isRecord(message.params) &&
4181
+ typeof message.params.threadId === 'string' &&
4182
+ isRecord(message.params.status)
4183
+ ) {
4184
+ const state = threads.get(message.params.threadId);
4185
+ if (!state) return true;
4186
+ state.status =
4187
+ typeof message.params.status.type === 'string' ? message.params.status.type : 'unknown';
4188
+ state.idle = state.status === 'idle';
4189
+ if (!state.idle) invalidateAttachment(state);
4190
+ if (!state.owned) return true;
4191
+ if (!state.telemetryConnected) {
4192
+ state.telemetryConnected = true;
4193
+ telemetryFor(message.params.threadId).connected({
4194
+ triggerPercent: effectiveThreshold,
4195
+ });
4196
+ }
4197
+ if (state.idle) void requestCompaction(message.params.threadId, state);
4198
+ }
4199
+ if (
4200
+ message.method === 'thread/tokenUsage/updated' &&
4201
+ isRecord(message.params) &&
4202
+ typeof message.params.threadId === 'string' &&
4203
+ isRecord(message.params.tokenUsage)
4204
+ ) {
4205
+ const params = message.params;
4206
+ if (
4207
+ params.threadId.length === 0 ||
4208
+ params.threadId.length > 256 ||
4209
+ typeof params.turnId !== 'string' ||
4210
+ params.turnId.length === 0 ||
4211
+ params.turnId.length > 256 ||
4212
+ !isValidUsage(params.tokenUsage)
4213
+ ) {
4214
+ stderr.write('codex-context: invalid usage sample skipped\n');
4215
+ return true;
4216
+ }
4217
+ const state = threads.get(params.threadId);
4218
+ if (!state) return true;
4219
+ state.usage = params.tokenUsage;
4220
+ state.usageReceivedAt = now();
4221
+ state.turnId = params.turnId;
4222
+ state.revision = `${state.turnId ?? 'unknown'}:${String(params.tokenUsage.last?.totalTokens ?? '')}:${String(params.tokenUsage.modelContextWindow ?? '')}`;
4223
+ if (
4224
+ state.recoveryAttach &&
4225
+ state.recoveryAttach !== null &&
4226
+ state.recovery &&
4227
+ state.turnId &&
4228
+ state.turnId !== state.recovery.turnId &&
4229
+ state.turnId !== state.recovery.sourceTurnId
4230
+ )
4231
+ invalidateAttachment(state);
4232
+ if (!state.owned) return true;
4233
+ telemetryFor(params.threadId).usage({
4234
+ measurement: {
4235
+ unit: 'tokens',
4236
+ used: params.tokenUsage.last.totalTokens,
4237
+ ...(hasKnownContextWindow(params.tokenUsage)
4238
+ ? { capacity: params.tokenUsage.modelContextWindow }
4239
+ : {}),
4240
+ },
4241
+ triggerPercent: effectiveThreshold,
4242
+ });
4243
+ if (state.idle) void requestCompaction(params.threadId, state);
4244
+ }
4245
+ if (
4246
+ message.method === 'turn/started' &&
4247
+ isRecord(message.params) &&
4248
+ typeof message.params.threadId === 'string' &&
4249
+ isRecord(message.params.turn)
4250
+ ) {
4251
+ const state = threads.get(message.params.threadId);
4252
+ const turnId = message.params.turn.id;
4253
+ if (
4254
+ state?.recoveryAttach &&
4255
+ typeof turnId === 'string' &&
4256
+ state.recovery &&
4257
+ turnId !== state.recovery.turnId &&
4258
+ turnId !== state.recovery.sourceTurnId
4259
+ )
4260
+ invalidateAttachment(state);
4261
+ }
4262
+ if (
4263
+ message.method === 'item/started' &&
4264
+ isRecord(message.params) &&
4265
+ isRecord(message.params.item) &&
4266
+ message.params.item.type === 'contextCompaction'
4267
+ ) {
4268
+ const p = message.params;
4269
+ const state = threads.get(p.threadId);
4270
+ const pending = state?.pending;
4271
+ if (pending?.lifecycleArmed && !pending.started) {
4272
+ pending.turnId = typeof p.turnId === 'string' ? p.turnId : null;
4273
+ pending.started = true;
4274
+ pending.itemId = p.item.id ?? null;
4275
+ emitDiagnostic({
4276
+ phase: 'native_started',
4277
+ stage: 'native',
4278
+ reason: 'requested',
4279
+ threadId: p.threadId,
4280
+ operationId: pending.operationId,
4281
+ });
4282
+ }
4283
+ }
4284
+ if (
4285
+ message.method === 'item/completed' &&
4286
+ isRecord(message.params) &&
4287
+ isRecord(message.params.item) &&
4288
+ message.params.item.type === 'contextCompaction'
4289
+ ) {
4290
+ const p = message.params;
4291
+ const state = threads.get(p.threadId);
4292
+ const pending = state?.pending;
4293
+ if (
4294
+ pending?.lifecycleArmed &&
4295
+ pending.started &&
4296
+ pending.turnId === p.turnId &&
4297
+ pending.itemId === (p.item.id ?? null)
4298
+ ) {
4299
+ pending.itemCompleted = true;
4300
+ emitDiagnostic({
4301
+ phase: 'native_item_completed',
4302
+ stage: 'native',
4303
+ reason: 'completed',
4304
+ threadId: p.threadId,
4305
+ operationId: pending.operationId,
4306
+ });
4307
+ if (pending.turnCompleted) pending.deferred.resolve();
4308
+ }
4309
+ }
4310
+ if (
4311
+ message.method === 'turn/completed' &&
4312
+ isRecord(message.params) &&
4313
+ typeof message.params.threadId === 'string' &&
4314
+ isRecord(message.params.turn)
4315
+ ) {
4316
+ const state = threads.get(message.params.threadId);
4317
+ const pending = state?.pending;
4318
+ const turn = message.params.turn;
4319
+ if (pending?.lifecycleArmed && pending.turnId === turn.id) {
4320
+ if (turn.status === 'completed') pending.turnCompleted = true;
4321
+ else fail(message.params.threadId, 'native compaction turn failed');
4322
+ if (pending.itemCompleted && pending.turnCompleted) {
4323
+ emitDiagnostic({
4324
+ phase: 'native_completed',
4325
+ stage: 'native',
4326
+ reason: 'completed',
4327
+ threadId: message.params.threadId,
4328
+ operationId: pending.operationId,
4329
+ });
4330
+ pending.deferred.resolve();
4331
+ }
4332
+ }
4333
+ }
4334
+ if (
4335
+ message.method === 'error' &&
4336
+ isRecord(message.params) &&
4337
+ typeof message.params.threadId === 'string'
4338
+ )
4339
+ fail(message.params.threadId, 'app-server error');
4340
+ if (
4341
+ (message.method === 'thread/closed' || message.method === 'thread/deleted') &&
4342
+ isRecord(message.params) &&
4343
+ typeof message.params.threadId === 'string'
4344
+ ) {
4345
+ fail(message.params.threadId, 'thread closed');
4346
+ ownedThreadIds.delete(message.params.threadId);
4347
+ threads.delete(message.params.threadId);
4348
+ }
4349
+ return true;
4350
+ }
4351
+
4352
+ /**
4353
+ * Observe TUI-owned requests without changing their wire representation.
4354
+ * The app-server may emit status/usage events before a resumed thread's
4355
+ * response arrives, so the adapter must defer owned work until that response
4356
+ * confirms that the thread is loaded.
4357
+ */
4358
+ function observeClientRequest(message) {
4359
+ if (!isRecord(message)) return;
4360
+ const requestId = message.id;
4361
+ const validRequestId =
4362
+ (typeof requestId === 'string' && requestId.length > 0 && requestId.length <= 128) ||
4363
+ Number.isSafeInteger(requestId);
4364
+ if (!validRequestId) return;
4365
+ const requestKey = clientRequestKey(requestId);
4366
+ if (requestKey === null) return;
4367
+ if (['thread/start', 'thread/resume', 'thread/fork'].includes(message.method)) {
4368
+ const threadId =
4369
+ isRecord(message.params) && typeof message.params.threadId === 'string'
4370
+ ? message.params.threadId
4371
+ : null;
4372
+ if (
4373
+ clientRequestBindings.has(requestKey) ||
4374
+ clientRequestBindings.size >= MAX_CLIENT_REQUEST_BINDINGS
4375
+ )
4376
+ return;
4377
+ clientRequestBindings.set(requestKey, { method: message.method, threadId });
4378
+ if (message.method === 'thread/resume') {
4379
+ if (threadId === null || threadId.length === 0 || threadId.length > 256) {
4380
+ clientRequestBindings.delete(requestKey);
4381
+ return;
4382
+ }
4383
+ const state = threadState(threadId);
4384
+ state.resumePending = true;
4385
+ state.resumeRetryRequested = false;
4386
+ state.resumeRequests.add(requestKey);
4387
+ }
4388
+ }
4389
+ }
4390
+
4391
+ function observeClientResponse(message) {
4392
+ if (!isRecord(message) || message.id === undefined) return;
4393
+ const requestKey = clientRequestKey(message.id);
4394
+ if (requestKey === null) return;
4395
+ const binding = clientRequestBindings.get(requestKey);
4396
+ if (binding) {
4397
+ clientRequestBindings.delete(requestKey);
4398
+ if (binding.method === 'thread/resume' && binding.threadId !== null) {
4399
+ const state = threadState(binding.threadId);
4400
+ state.resumeRequests.delete(requestKey);
4401
+ state.resumePending = state.resumeRequests.size > 0;
4402
+ state.resumeRetryRequested = false;
4403
+ const responseThreadId = message.result?.thread?.id;
4404
+ if (
4405
+ message.error === undefined &&
4406
+ typeof responseThreadId === 'string' &&
4407
+ responseThreadId === binding.threadId
4408
+ ) {
4409
+ const claimed = claimOwnedThread(binding.threadId);
4410
+ if (claimed && !state.resumePending && claimed.idle)
4411
+ void requestCompaction(binding.threadId, claimed);
4412
+ } else if (!state.owned && state.resumeRequests.size === 0 && state.pending === null) {
4413
+ threads.delete(binding.threadId);
4414
+ }
4415
+ } else if (message.error === undefined) {
4416
+ const selectedId = message.result?.thread?.id;
4417
+ if (typeof selectedId === 'string' && selectedId.length > 0 && selectedId.length <= 256) {
4418
+ const selected = claimOwnedThread(selectedId);
4419
+ if (!selected) return;
4420
+ if (selected.idle) void requestCompaction(selectedId, selected);
4421
+ }
4422
+ }
4423
+ }
4424
+ }
4425
+
4426
+ const decoder = new StringDecoder('utf8');
4427
+ let inputBuffer = '';
4428
+ let passthrough = false;
4429
+ let discardOversized = false;
4430
+ let pausedForBackpressure = false;
4431
+ const forward = (text) => {
4432
+ if (!stdout.write(text) && !pausedForBackpressure) {
4433
+ pausedForBackpressure = true;
4434
+ child.stdout.pause();
4435
+ stdout.once('drain', () => {
4436
+ pausedForBackpressure = false;
4437
+ child.stdout.resume();
4438
+ });
4439
+ }
4440
+ };
4441
+ const processLine = (line) => {
4442
+ if (Buffer.byteLength(line, 'utf8') + 1 > MAX_LINE_BYTES) {
4443
+ const ownedId = internalRequestId(line);
4444
+ if (ownedId !== null) {
4445
+ stderr.write('codex-context: oversized internal response rejected\n');
4446
+ failOversizedInternal(ownedId, Buffer.byteLength(line, 'utf8') + 1);
4447
+ } else forward(`${line}\n`);
4448
+ return;
4449
+ }
4450
+ let forwardLine = true;
4451
+ try {
4452
+ const message = JSON.parse(line.endsWith('\r') ? line.slice(0, -1) : line);
4453
+ observeClientResponse(message);
4454
+ forwardLine = handle(message);
4455
+ } catch {
4456
+ /* preserve malformed external protocol lines */
4457
+ }
4458
+ if (forwardLine) forward(`${line}\n`);
4459
+ };
4460
+ function internalRequestId(line) {
4461
+ const match =
4462
+ /^\s*\{\s*(?:"id"\s*:\s*"(ai-brain-context-[A-Za-z0-9._:-]{1,128})"|"jsonrpc"\s*:\s*"2\.0"\s*,\s*"id"\s*:\s*"(ai-brain-context-[A-Za-z0-9._:-]{1,128})")/u.exec(
4463
+ line,
4464
+ );
4465
+ return match?.[1] ?? match?.[2] ?? null;
4466
+ }
4467
+ function failCompactions(reason) {
4468
+ for (const [threadId, state] of threads) {
4469
+ if (state.pending) fail(threadId, reason);
4470
+ }
4471
+ }
4472
+ function failOversizedInternal(id, responseBytes) {
4473
+ const owned = ownedRequests.get(id);
4474
+ if (!owned) {
4475
+ failCompactions('oversized internal response');
4476
+ return;
4477
+ }
4478
+ if (owned.kind === 'page') {
4479
+ ownedRequests.delete(id);
4480
+ const waiter = internalReads.get(id);
4481
+ internalReads.delete(id);
4482
+ retire(id);
4483
+ const failure = new Error('oversized internal page response');
4484
+ failure.diagnosticReason = 'capture_size_exceeded';
4485
+ failure.responseBytes = responseBytes;
4486
+ failure.responseLimitBytes = MAX_LINE_BYTES;
4487
+ waiter?.reject(failure);
4488
+ return;
4489
+ }
4490
+ cleanupRequest(id);
4491
+ if (owned.kind === 'telemetry') return;
4492
+ const failure = new Error('oversized internal response');
4493
+ failure.diagnosticReason = 'capture_size_exceeded';
4494
+ failure.responseBytes = responseBytes;
4495
+ failure.responseLimitBytes = MAX_LINE_BYTES;
4496
+ fail(owned.threadId, 'oversized internal response', failure);
4497
+ }
4498
+ child.stdout.on('data', (chunk) => {
4499
+ if (stopped) return;
4500
+ const decoded = decoder.write(chunk);
4501
+ if (discardOversized) {
4502
+ const newline = decoded.indexOf('\n');
4503
+ if (newline < 0) return;
4504
+ discardOversized = false;
4505
+ inputBuffer = decoded.slice(newline + 1);
4506
+ } else inputBuffer += decoded;
4507
+ while (true) {
4508
+ const newline = inputBuffer.indexOf('\n');
4509
+ if (newline < 0) break;
4510
+ const line = inputBuffer.slice(0, newline);
4511
+ inputBuffer = inputBuffer.slice(newline + 1);
4512
+ if (discardOversized) {
4513
+ discardOversized = false;
4514
+ } else if (passthrough) {
4515
+ forward(`${line}\n`);
4516
+ passthrough = false;
4517
+ } else processLine(line);
4518
+ }
4519
+ if (Buffer.byteLength(inputBuffer, 'utf8') + 1 > MAX_LINE_BYTES) {
4520
+ if (passthrough) {
4521
+ forward(inputBuffer);
4522
+ inputBuffer = '';
4523
+ } else if (internalRequestId(inputBuffer) !== null) {
4524
+ stderr.write('codex-context: oversized internal response rejected\n');
4525
+ failOversizedInternal(
4526
+ internalRequestId(inputBuffer),
4527
+ Buffer.byteLength(inputBuffer, 'utf8') + 1,
4528
+ );
4529
+ discardOversized = true;
4530
+ inputBuffer = '';
4531
+ } else {
4532
+ forward(inputBuffer);
4533
+ inputBuffer = '';
4534
+ passthrough = true;
4535
+ }
4536
+ }
4537
+ });
4538
+ child.stdout.on('end', () => {
4539
+ const tail = inputBuffer + decoder.end();
4540
+ if (tail && !discardOversized) forward(tail);
4541
+ inputBuffer = '';
4542
+ failAll('app-server stdout ended');
4543
+ emitDiagnostic({ phase: 'transport_end' });
4544
+ });
4545
+ child.on('error', () => {
4546
+ stopped = true;
4547
+ failAll('app-server process error');
4548
+ emitDiagnostic({ phase: 'process_error' });
4549
+ });
4550
+ child.on('close', () => {
4551
+ stopped = true;
4552
+ failAll('app-server disconnected');
4553
+ emitDiagnostic({ phase: 'transport_close' });
4554
+ });
4555
+ // Native app-server stderr is operational logging and may contain private
4556
+ // paths, prompts or tool output. Drain the owned pipe without forwarding or
4557
+ // persisting its contents; protocol errors remain on stdout and process exit
4558
+ // status is still propagated by the launcher.
4559
+ if (child.stderr && typeof child.stderr.on === 'function') {
4560
+ child.stderr.on('data', () => undefined);
4561
+ child.stderr.resume?.();
4562
+ }
4563
+ return {
4564
+ threads,
4565
+ observeClientRequest,
4566
+ observeClientResponse,
4567
+ async stop() {
4568
+ if (stopped) {
4569
+ await Promise.all(
4570
+ [...diagnosticSinks.values()].map((sink) =>
4571
+ typeof sink.flush === 'function'
4572
+ ? Promise.resolve(sink.flush()).catch(() => undefined)
4573
+ : undefined,
4574
+ ),
4575
+ );
4576
+ return;
4577
+ }
4578
+ for (const reporter of telemetryByThread.values()) {
4579
+ reporter.disconnected();
4580
+ void reporter.flush();
4581
+ }
4582
+ stopped = true;
4583
+ clientRequestBindings.clear();
4584
+ ownedThreadIds.clear();
4585
+ failAll('adapter stopped');
4586
+ await Promise.all(
4587
+ [...diagnosticSinks.values()].map((sink) =>
4588
+ typeof sink.flush === 'function'
4589
+ ? Promise.resolve(sink.flush()).catch(() => undefined)
4590
+ : undefined,
4591
+ ),
4592
+ );
4593
+ },
4594
+ };
4595
+ }
4596
+
4597
+ async function main() {
4598
+ if (process.argv.includes('--help')) {
4599
+ process.stderr.write(
4600
+ 'Usage: node scripts/codex-context-compaction.mjs [app-server arguments...]\nStarts an owned Codex app-server and requests native compaction at CODEX_CONTEXT_COMPACT_AT (default 85).\n',
4601
+ );
4602
+ return;
4603
+ }
4604
+ const policy = parseContextPolicy();
4605
+ const command = process.env.CODEX_BIN ?? 'codex';
4606
+ const profile = process.env.CODEX_APP_SERVER_PROFILE;
4607
+ if (profile !== undefined && !/^[A-Za-z0-9._-]{1,64}$/u.test(profile)) {
4608
+ throw new Error('CODEX_APP_SERVER_PROFILE is invalid');
4609
+ }
4610
+ const child = spawn(
4611
+ command,
4612
+ [
4613
+ ...(profile === undefined ? [] : ['--profile', profile]),
4614
+ 'app-server',
4615
+ ...process.argv.slice(2),
4616
+ ],
4617
+ {
4618
+ stdio: ['pipe', 'pipe', 'pipe'],
4619
+ env: codexChildEnvironment(),
4620
+ },
4621
+ );
4622
+ let diagnosticFactory = null;
4623
+ const diagnosticModule = process.env.CODEX_CONTEXT_DIAGNOSTICS_MODULE;
4624
+ if (
4625
+ process.env.CODEX_CONTEXT_DIAGNOSTICS_ENABLED === '1' &&
4626
+ typeof diagnosticModule === 'string' &&
4627
+ diagnosticModule.length > 0
4628
+ ) {
4629
+ try {
4630
+ const module = await import(pathToFileURL(resolve(diagnosticModule)).href);
4631
+ if (typeof module.createCodexDiagnosticSink === 'function') {
4632
+ const stateDir = process.env.CODEX_CONTEXT_DIAGNOSTICS_DIR ?? process.cwd();
4633
+ diagnosticFactory = (threadId) =>
4634
+ module.createCodexDiagnosticSink({
4635
+ stateDir,
4636
+ sessionId: threadId,
4637
+ clientVersion: process.env.CODEX_CLIENT_VERSION ?? '0.161.0',
4638
+ enabled: true,
4639
+ });
4640
+ }
4641
+ } catch {
4642
+ diagnosticFactory = null;
4643
+ }
4644
+ }
4645
+ const proxy = createCodexContextProxy({
4646
+ child,
4647
+ threshold: numberEnv('CODEX_CONTEXT_COMPACT_AT', DEFAULT_THRESHOLD),
4648
+ timeoutMs: numberEnv('CODEX_CONTEXT_COMPACT_TIMEOUT_MS', DEFAULT_TIMEOUT_MS),
4649
+ policy,
4650
+ createDiagnosticSink: diagnosticFactory,
4651
+ });
4652
+ const clientDecoder = new StringDecoder('utf8');
4653
+ let clientInputBuffer = '';
4654
+ let discardOversizedClientFrame = false;
4655
+ process.stdin.on('data', (chunk) => {
4656
+ const decoded = clientDecoder.write(chunk);
4657
+ if (discardOversizedClientFrame) {
4658
+ const newline = decoded.indexOf('\n');
4659
+ if (newline < 0) return;
4660
+ discardOversizedClientFrame = false;
4661
+ clientInputBuffer = decoded.slice(newline + 1);
4662
+ } else clientInputBuffer += decoded;
4663
+ while (true) {
4664
+ const newline = clientInputBuffer.indexOf('\n');
4665
+ if (newline < 0) break;
4666
+ const line = clientInputBuffer.slice(0, newline).replace(/\r$/u, '');
4667
+ clientInputBuffer = clientInputBuffer.slice(newline + 1);
4668
+ if (!line) continue;
4669
+ if (Buffer.byteLength(line, 'utf8') + 1 > MAX_LINE_BYTES) continue;
4670
+ try {
4671
+ proxy.observeClientRequest(JSON.parse(line));
4672
+ } catch {
4673
+ /* Preserve malformed/native frames unchanged; the app-server owns validation. */
4674
+ }
4675
+ }
4676
+ if (Buffer.byteLength(clientInputBuffer, 'utf8') + 1 > MAX_LINE_BYTES) {
4677
+ clientInputBuffer = '';
4678
+ discardOversizedClientFrame = true;
4679
+ }
4680
+ });
4681
+ process.stdin.pipe(child.stdin);
4682
+ process.stdin.on('end', () => child.stdin.end());
4683
+ child.on('exit', async (code, signal) => {
4684
+ await proxy.stop();
4685
+ process.exitCode = code ?? (signal ? 1 : 0);
4686
+ });
4687
+ }
4688
+ if (process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname))
4689
+ void main();