@brunobracaioli/aibrain 0.1.0-beta.1 → 0.3.0-beta.13

package/dist/claude-checkpoint.mjs

@@ -0,0 +1,1338 @@
+#!/usr/bin/env node
+// @ts-check
+
+import { createHash, randomUUID } from 'node:crypto';
+import { chmod, lstat, mkdir, open, readFile, readdir, rename, unlink } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const PROTOCOL_VERSION = 1;
+export const MAX_SNAPSHOT_BYTES = 32 * 1024 * 1024;
+export const MAX_STDIN_BYTES = 40 * 1024 * 1024;
+export const MAX_STORED_BYTES = 64 * 1024 * 1024;
+export const MAX_COMPLETED_CHECKPOINTS = 4;
+export const MAX_SESSION_REF_BYTES = 256;
+export const MAX_RECORD_FILES = 16;
+export const NOTES_PROTOCOL_VERSION = 2;
+export const MAX_NOTE_TEXT_BYTES = 96 * 1024;
+export const MAX_NOTE_ENVELOPE_BYTES = 128 * 1024;
+export const MAX_NOTE_RECORDS_PER_BINDING = 8;
+export const MAX_NOTE_AGGREGATE_BYTES = 2 * 1024 * 1024;
+export const NOTE_EXPIRY_MS = 30 * 24 * 60 * 60 * 1000;
+export const NOTE_MAX_CLOCK_SKEW_MS = 5 * 60 * 1000;
+const STALE_ARTIFACT_MS = 60_000;
+
+const FILE_PREFIX = 'aibrain-claude-checkpoint-v1-';
+const FILE_SUFFIX = '.json';
+const LOCK_NAME = `${FILE_PREFIX}lock`;
+const NOTE_FILE_PREFIX = 'aibrain-claude-note-v2-';
+const NOTE_TARGET_NAME = new RegExp(`^${NOTE_FILE_PREFIX}([a-f0-9]{64})\\${FILE_SUFFIX}$`, 'u');
+const NOTE_TEMP_NAME = new RegExp(
+  `^${NOTE_FILE_PREFIX}[a-f0-9]{64}\\${FILE_SUFFIX}\\.tmp-\\d+-[0-9a-f-]{36}$`,
+  'u',
+);
+const NOTE_BACKUP_NAME = new RegExp(
+  `^${NOTE_FILE_PREFIX}([a-f0-9]{64})${FILE_SUFFIX}\\.bak-\\d+-[0-9a-f-]{36}$`,
+  'u',
+);
+const HEX64 = /^[a-f0-9]{64}$/u;
+const SESSION_REF = /^[A-Za-z0-9._:-]{1,128}$/u;
+const REVISION = /^[a-f0-9]{64}$/u;
+const OPERATION_ID = /^[A-Za-z0-9._:-]{1,128}$/u;
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u;
+const TARGET_NAME = new RegExp(`^${FILE_PREFIX}([a-f0-9]{64})\\${FILE_SUFFIX}$`, 'u');
+const TEMP_NAME = new RegExp(`^${FILE_PREFIX}[a-f0-9]{64}\\.tmp-\\d+-[0-9a-f-]{36}$`, 'u');
+const BACKUP_NAME = new RegExp(
+  `^${FILE_PREFIX}([a-f0-9]{64})${FILE_SUFFIX}\\.bak-\\d+-[0-9a-f-]{36}$`,
+  'u',
+);
+const ERROR_CODES = new Set([
+  'invalid_arguments',
+  'input_too_large',
+  'invalid_input',
+  'state_dir_invalid',
+  'state_owner_mismatch',
+  'state_permissions_invalid',
+  'state_symlink_rejected',
+  'checkpoint_not_found',
+  'checkpoint_invalid',
+  'checkpoint_corrupt',
+  'checkpoint_oversized',
+  'checkpoint_write_failed',
+  'checkpoint_read_failed',
+  'checkpoint_lock_failed',
+  'checkpoint_lock_timeout',
+  'checkpoint_binding_mismatch',
+  'checkpoint_retention_failed',
+  'checkpoint_ack_failed',
+  'note_not_found',
+  'note_invalid',
+  'note_corrupt',
+  'note_expired',
+  'note_oversized',
+  'note_write_failed',
+  'note_read_failed',
+  'note_lock_failed',
+  'note_lock_timeout',
+  'note_binding_mismatch',
+  'note_retention_failed',
+  'note_ack_failed',
+  'note_metadata_mismatch',
+]);
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function object(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** @param {unknown} value @returns {string} */
+function canonical(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  const record = /** @type {Record<string, unknown>} */ (value);
+  return `{${Object.keys(record)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${canonical(record[key])}`)
+    .join(',')}}`;
+}
+
+/** @param {unknown} value */
+function digest(value) {
+  return createHash('sha256').update(canonical(value), 'utf8').digest('hex');
+}
+
+/** @param {string} value */
+function textDigest(value) {
+  return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+
+/** @param {unknown} value */
+function normalizedJson(value) {
+  let text;
+  try {
+    text = JSON.stringify(value);
+  } catch {
+    throw new Error('invalid_input');
+  }
+  if (typeof text !== 'string') throw new Error('invalid_input');
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error('invalid_input');
+  }
+  const output = JSON.stringify(parsed);
+  if (typeof output !== 'string') throw new Error('invalid_input');
+  return output;
+}
+
+/** @param {string} path @param {boolean} allowMissing */
+async function assertPath(path, allowMissing) {
+  const target = resolve(path);
+  if (!isAbsolute(path)) throw new Error('state_dir_invalid');
+  const parts = target.split('/').filter(Boolean);
+  let current = target.startsWith('/') ? '/' : '';
+  for (const part of parts) {
+    current = current === '/' ? `/${part}` : join(current, part);
+    try {
+      const entry = await lstat(current);
+      if (entry.isSymbolicLink()) throw new Error('state_symlink_rejected');
+    } catch (error) {
+      if (error instanceof Error && error.message === 'state_symlink_rejected') throw error;
+      if (!(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT'))
+        throw error;
+      if (!allowMissing) throw new Error('state_dir_invalid');
+      break;
+    }
+  }
+}
+
+/** @param {string} stateDir */
+async function ownedDirectory(stateDir) {
+  if (!isAbsolute(stateDir)) throw new Error('state_dir_invalid');
+  const target = resolve(stateDir);
+  await assertPath(target, true);
+  await mkdir(target, { recursive: true, mode: 0o700 });
+  await assertPath(target, false);
+  const entry = await lstat(target);
+  if (entry.isSymbolicLink() || !entry.isDirectory()) throw new Error('state_dir_invalid');
+  if (typeof process.getuid === 'function' && entry.uid !== process.getuid())
+    throw new Error('state_owner_mismatch');
+  if ((entry.mode & 0o077) !== 0) throw new Error('state_permissions_invalid');
+  await chmod(target, 0o700);
+  return target;
+}
+
+/** @param {string} path */
+async function ownedFile(path) {
+  const entry = await lstat(path);
+  if (entry.isSymbolicLink() || !entry.isFile()) throw new Error('checkpoint_corrupt');
+  if (typeof process.getuid === 'function' && entry.uid !== process.getuid())
+    throw new Error('state_owner_mismatch');
+  if ((entry.mode & 0o077) !== 0) throw new Error('state_permissions_invalid');
+  if (entry.size > MAX_SNAPSHOT_BYTES + 16 * 1024) throw new Error('checkpoint_oversized');
+  return entry;
+}
+
+/** @param {string} sessionRef @param {string} binding */
+function fileName(sessionRef, binding) {
+  return `${FILE_PREFIX}${digest({ binding, sessionRef })}${FILE_SUFFIX}`;
+}
+
+/** @param {string[]} raw */
+function parseArgs(raw) {
+  if (
+    raw.length !== 6 ||
+    raw[0] !== '--state-dir' ||
+    raw[2] !== '--config-digest' ||
+    typeof raw[1] !== 'string' ||
+    !isAbsolute(raw[1]) ||
+    typeof raw[3] !== 'string' ||
+    !HEX64.test(raw[3]) ||
+    raw[4] !== '--binding' ||
+    typeof raw[5] !== 'string' ||
+    !HEX64.test(raw[5]) ||
+    raw[5] !== raw[3]
+  )
+    throw new Error('invalid_arguments');
+  return { stateDir: resolve(raw[1]), configDigest: raw[3], binding: raw[5] };
+}
+
+/** @param {string} capturedAt @param {string} errorCode */
+function validateNoteTimestamp(capturedAt, errorCode) {
+  if (!ISO.test(capturedAt)) throw new Error(errorCode);
+  let timestamp;
+  try {
+    timestamp = Date.parse(capturedAt);
+  } catch {
+    throw new Error(errorCode);
+  }
+  if (!Number.isFinite(timestamp)) throw new Error(errorCode);
+  if (timestamp > Date.now() + NOTE_MAX_CLOCK_SKEW_MS) throw new Error(errorCode);
+  if (Date.now() - timestamp > NOTE_EXPIRY_MS) throw new Error('note_expired');
+}
+
+/** @param {unknown} value */
+function parseNotesInput(value) {
+  if (!object(value) || value.schema_version !== NOTES_PROTOCOL_VERSION)
+    throw new Error('note_invalid');
+  const operation = value.operation;
+  const writeKeys = new Set([
+    'schema_version',
+    'operation',
+    'binding',
+    'session_ref',
+    'operation_id',
+    'request_id',
+    'revision',
+    'projection_hash',
+    'captured_at',
+    'note_text',
+    'note_sha256',
+  ]);
+  const readKeys = new Set([
+    'schema_version',
+    'operation',
+    'binding',
+    'session_ref',
+    'operation_id',
+    'note_sha256',
+  ]);
+  const allowed =
+    operation === 'notes.write' ? writeKeys : operation === 'notes.read' ? readKeys : null;
+  if (allowed === null || Object.keys(value).some((key) => !allowed.has(key)))
+    throw new Error('note_invalid');
+  if (
+    typeof value.binding !== 'string' ||
+    !HEX64.test(value.binding) ||
+    typeof value.session_ref !== 'string' ||
+    !SESSION_REF.test(value.session_ref) ||
+    Buffer.byteLength(value.session_ref, 'utf8') > MAX_SESSION_REF_BYTES ||
+    typeof value.operation_id !== 'string' ||
+    !OPERATION_ID.test(value.operation_id) ||
+    typeof value.note_sha256 !== 'string' ||
+    !HEX64.test(value.note_sha256)
+  )
+    throw new Error('note_invalid');
+  if (operation === 'notes.read')
+    return /** @type {Record<string, unknown> & {schema_version:2, operation:'notes.read', binding:string, session_ref:string, operation_id:string, note_sha256:string}} */ (
+      value
+    );
+  if (
+    typeof value.request_id !== 'string' ||
+    !OPERATION_ID.test(value.request_id) ||
+    typeof value.revision !== 'string' ||
+    !REVISION.test(value.revision) ||
+    typeof value.projection_hash !== 'string' ||
+    !HEX64.test(value.projection_hash) ||
+    typeof value.captured_at !== 'string' ||
+    !ISO.test(value.captured_at) ||
+    typeof value.note_text !== 'string'
+  )
+    throw new Error('note_invalid');
+  try {
+    if (new Date(value.captured_at).toISOString() !== value.captured_at)
+      throw new Error('note_invalid');
+  } catch {
+    throw new Error('note_invalid');
+  }
+  validateNoteTimestamp(value.captured_at, 'note_invalid');
+  const noteBytes = Buffer.byteLength(value.note_text, 'utf8');
+  if (noteBytes > MAX_NOTE_TEXT_BYTES) throw new Error('note_oversized');
+  if (textDigest(value.note_text) !== value.note_sha256) throw new Error('note_ack_failed');
+  return /** @type {Record<string, unknown> & {schema_version:2, operation:'notes.write', binding:string, session_ref:string, operation_id:string, request_id:string, revision:string, projection_hash:string, captured_at:string, note_text:string, note_sha256:string}} */ (
+    value
+  );
+}
+
+/** @param {string} text */
+function parseInput(text) {
+  if (Buffer.byteLength(text, 'utf8') > MAX_STDIN_BYTES) throw new Error('input_too_large');
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new Error('invalid_input');
+  }
+  if (object(value) && value.schema_version === NOTES_PROTOCOL_VERSION)
+    return parseNotesInput(value);
+  if (!object(value) || value.schema_version !== PROTOCOL_VERSION) throw new Error('invalid_input');
+  if (value.operation !== 'checkpoint.write') throw new Error('invalid_input');
+  const allowed = new Set([
+    'schema_version',
+    'operation',
+    'operation_id',
+    'binding',
+    'session_ref',
+    'revision',
+    'preservation_mode',
+    'checkpoint',
+    'byte_count',
+    'payload_sha256',
+  ]);
+  if (Object.keys(value).some((key) => !allowed.has(key))) throw new Error('invalid_input');
+  if (typeof value.session_ref !== 'string' || !SESSION_REF.test(value.session_ref))
+    throw new Error('invalid_input');
+  if (Buffer.byteLength(value.session_ref, 'utf8') > MAX_SESSION_REF_BYTES)
+    throw new Error('invalid_input');
+  if (typeof value.revision !== 'string' || !REVISION.test(value.revision))
+    throw new Error('invalid_input');
+  if (!Object.hasOwn(value, 'checkpoint')) throw new Error('invalid_input');
+  if (typeof value.binding !== 'string' || !HEX64.test(value.binding))
+    throw new Error('invalid_input');
+  if (typeof value.operation_id !== 'string' || !OPERATION_ID.test(value.operation_id))
+    throw new Error('invalid_input');
+  if (
+    value.preservation_mode !== 'preserve_internal' &&
+    value.preservation_mode !== 'upstream_compatible'
+  )
+    throw new Error('invalid_input');
+  const checkpoint = value.checkpoint;
+  if (!object(checkpoint)) throw new Error('invalid_input');
+  const checkpointKeys = new Set([
+    'version',
+    'sessionRef',
+    'revision',
+    'preservationMode',
+    'capturedAt',
+    'messages',
+  ]);
+  if (Object.keys(checkpoint).some((key) => !checkpointKeys.has(key)))
+    throw new Error('invalid_input');
+  if (
+    checkpoint.version !== 1 ||
+    checkpoint.sessionRef !== value.session_ref ||
+    checkpoint.revision !== value.revision ||
+    checkpoint.preservationMode !== value.preservation_mode ||
+    typeof checkpoint.capturedAt !== 'string' ||
+    !ISO.test(checkpoint.capturedAt) ||
+    !Array.isArray(checkpoint.messages)
+  )
+    throw new Error('invalid_input');
+  const payload = normalizedJson(checkpoint);
+  const bytes = Buffer.byteLength(payload, 'utf8');
+  if (bytes > MAX_SNAPSHOT_BYTES) throw new Error('checkpoint_oversized');
+  if (
+    value.byte_count !== bytes ||
+    typeof value.payload_sha256 !== 'string' ||
+    !HEX64.test(value.payload_sha256) ||
+    textDigest(payload) !== value.payload_sha256
+  )
+    throw new Error('checkpoint_ack_failed');
+  return /** @type {Record<string, unknown> & {schema_version:1, operation:'checkpoint.write', session_ref:string, revision:string, preservation_mode:string, checkpoint:Record<string, unknown>, byte_count:number, payload_sha256:string}} */ (
+    value
+  );
+}
+
+async function readStdin() {
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of process.stdin) {
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+    total += bytes.byteLength;
+    if (total > MAX_STDIN_BYTES) throw new Error('input_too_large');
+    chunks.push(bytes);
+  }
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks));
+  } catch {
+    throw new Error('invalid_input');
+  }
+}
+
+/** @param {string} stateDir */
+async function acquireLock(stateDir) {
+  const lock = join(stateDir, LOCK_NAME);
+  let handle;
+  const nonce = randomUUID();
+  /** @type {import('node:fs').Stats | undefined} */
+  let identity;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      handle = await open(
+        lock,
+        constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
+        0o600,
+      );
+      await handle.writeFile(`${process.pid}:${nonce}\n`, 'utf8');
+      await handle.close();
+      handle = undefined;
+      identity = await lstat(lock);
+      break;
+    } catch (error) {
+      await handle?.close().catch(() => undefined);
+      handle = undefined;
+      if (!(error && typeof error === 'object' && 'code' in error && error.code === 'EEXIST'))
+        throw new Error('checkpoint_lock_failed');
+      if (attempt > 0) throw new Error('checkpoint_lock_timeout');
+      try {
+        const entry = await lstat(lock);
+        if (
+          entry.isSymbolicLink() ||
+          !entry.isFile() ||
+          entry.size > 128 ||
+          (entry.mode & 0o077) !== 0 ||
+          (typeof process.getuid === 'function' && entry.uid !== process.getuid())
+        )
+          throw new Error('checkpoint_lock_failed');
+        const age = Date.now() - entry.mtimeMs;
+        const ownerText = await readFile(lock, 'utf8');
+        const lockMatch = /^(\d+):([0-9a-f-]{36})\n?$/u.exec(ownerText);
+        if (lockMatch === null) throw new Error('checkpoint_lock_failed');
+        const ownerPid = Number.parseInt(lockMatch[1], 10);
+        let alive = false;
+        if (Number.isSafeInteger(ownerPid) && ownerPid > 0) {
+          try {
+            process.kill(ownerPid, 0);
+            alive = true;
+          } catch (probeError) {
+            alive = Boolean(
+              probeError &&
+              typeof probeError === 'object' &&
+              'code' in probeError &&
+              probeError.code !== 'ESRCH',
+            );
+          }
+        }
+        if (alive || age < STALE_ARTIFACT_MS) throw new Error('checkpoint_lock_timeout');
+        const latest = await lstat(lock);
+        if (latest.dev !== entry.dev || latest.ino !== entry.ino)
+          throw new Error('checkpoint_lock_timeout');
+        if ((await readFile(lock, 'utf8')) !== ownerText)
+          throw new Error('checkpoint_lock_timeout');
+        await unlink(lock);
+      } catch (staleError) {
+        if (staleError instanceof Error && staleError.message.startsWith('checkpoint_'))
+          throw staleError;
+        throw new Error('checkpoint_lock_failed');
+      }
+    }
+  }
+  return async () => {
+    try {
+      const entry = await lstat(lock);
+      if (
+        entry.isSymbolicLink() ||
+        !entry.isFile() ||
+        (entry.mode & 0o077) !== 0 ||
+        identity === undefined ||
+        entry.dev !== identity.dev ||
+        entry.ino !== identity.ino
+      )
+        return;
+      if ((await readFile(lock, 'utf8')) === `${process.pid}:${nonce}\n`) await unlink(lock);
+    } catch {
+      // An absent lock is already released. Never remove an unexpected target.
+    }
+  };
+}
+
+/** @param {unknown} value @param {string} binding @param {string} name */
+function validateEnvelope(value, binding, name) {
+  if (!object(value) || value.schema_version !== PROTOCOL_VERSION || value.kind !== 'completed')
+    throw new Error('checkpoint_corrupt');
+  const allowed = new Set([
+    'schema_version',
+    'kind',
+    'binding',
+    'operation_id',
+    'session_ref',
+    'revision',
+    'captured_at',
+    'payload',
+    'payload_sha256',
+  ]);
+  if (Object.keys(value).some((key) => !allowed.has(key))) throw new Error('checkpoint_corrupt');
+  if (
+    typeof value.session_ref !== 'string' ||
+    !SESSION_REF.test(value.session_ref) ||
+    typeof value.revision !== 'string' ||
+    !REVISION.test(value.revision) ||
+    typeof value.binding !== 'string' ||
+    !HEX64.test(value.binding) ||
+    typeof value.captured_at !== 'string' ||
+    !ISO.test(value.captured_at) ||
+    (value.operation_id !== undefined &&
+      (typeof value.operation_id !== 'string' || !OPERATION_ID.test(value.operation_id))) ||
+    !object(value.payload) ||
+    typeof value.payload_sha256 !== 'string' ||
+    !HEX64.test(value.payload_sha256)
+  )
+    throw new Error('checkpoint_corrupt');
+  const payload = value.payload;
+  const payloadKeys = new Set([
+    'version',
+    'sessionRef',
+    'revision',
+    'preservationMode',
+    'capturedAt',
+    'messages',
+  ]);
+  if (
+    Object.keys(payload).some((key) => !payloadKeys.has(key)) ||
+    payload.version !== 1 ||
+    payload.sessionRef !== value.session_ref ||
+    payload.revision !== value.revision ||
+    (payload.preservationMode !== 'preserve_internal' &&
+      payload.preservationMode !== 'upstream_compatible') ||
+    payload.capturedAt !== value.captured_at ||
+    !Array.isArray(payload.messages)
+  )
+    throw new Error('checkpoint_corrupt');
+  const normalized = normalizedJson(payload);
+  if (
+    Buffer.byteLength(normalized, 'utf8') > MAX_SNAPSHOT_BYTES ||
+    textDigest(normalized) !== value.payload_sha256 ||
+    digest({ binding: value.binding, sessionRef: value.session_ref }) !== name
+  )
+    throw new Error('checkpoint_corrupt');
+  return value;
+}
+
+/** @param {string} path @param {string} binding @param {string} name */
+async function readEnvelope(path, binding, name) {
+  await ownedFile(path);
+  let value;
+  try {
+    value = JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    throw new Error('checkpoint_corrupt');
+  }
+  return validateEnvelope(value, binding, name);
+}
+
+/** @param {string} stateDir @param {string} binding */
+async function listRecords(stateDir, binding) {
+  let names;
+  try {
+    names = await readdir(stateDir);
+  } catch {
+    throw new Error('checkpoint_read_failed');
+  }
+  const records = [];
+  for (const name of names) {
+    if (name === LOCK_NAME || TEMP_NAME.test(name) || BACKUP_NAME.test(name)) continue;
+    if (!name.startsWith(FILE_PREFIX)) continue;
+    const targetMatch = TARGET_NAME.exec(name);
+    if (targetMatch === null) throw new Error('checkpoint_corrupt');
+    const path = join(stateDir, name);
+    const value = await readEnvelope(path, binding, targetMatch[1]);
+    records.push({
+      name,
+      path,
+      value,
+      bytes: (await lstat(path)).size,
+      foreign: value.binding !== binding,
+    });
+    if (records.length > MAX_RECORD_FILES) throw new Error('checkpoint_retention_failed');
+  }
+  return records;
+}
+
+/** @param {{sessionRef:string, operationId:string, binding:string, requestId:string, revision:string, projectionHash:string, capturedAt:string, noteSha256:string}} identity */
+function noteFileName(identity) {
+  return `${NOTE_FILE_PREFIX}${digest({
+    binding: identity.binding,
+    sessionRef: identity.sessionRef,
+    operationId: identity.operationId,
+    requestId: identity.requestId,
+    revision: identity.revision,
+    projectionHash: identity.projectionHash,
+    capturedAt: identity.capturedAt,
+    noteSha256: identity.noteSha256,
+  })}${FILE_SUFFIX}`;
+}
+
+/** @param {string} path */
+async function ownedNoteFile(path) {
+  let entry;
+  try {
+    entry = await lstat(path);
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+      throw error;
+    throw new Error('note_corrupt');
+  }
+  if (entry.isSymbolicLink() || !entry.isFile()) throw new Error('note_corrupt');
+  if (typeof process.getuid === 'function' && entry.uid !== process.getuid())
+    throw new Error('state_owner_mismatch');
+  if ((entry.mode & 0o077) !== 0) throw new Error('state_permissions_invalid');
+  if (entry.size > MAX_NOTE_ENVELOPE_BYTES) throw new Error('note_oversized');
+  return entry;
+}
+
+/** @param {unknown} value @param {string} name */
+function validateNoteEnvelope(value, name) {
+  if (
+    !object(value) ||
+    value.schema_version !== NOTES_PROTOCOL_VERSION ||
+    value.kind !== 'retained_note'
+  )
+    throw new Error('note_corrupt');
+  const allowed = new Set([
+    'schema_version',
+    'kind',
+    'binding',
+    'session_ref',
+    'operation_id',
+    'request_id',
+    'revision',
+    'projection_hash',
+    'captured_at',
+    'note_text',
+    'note_sha256',
+  ]);
+  if (Object.keys(value).some((key) => !allowed.has(key))) throw new Error('note_corrupt');
+  if (
+    typeof value.binding !== 'string' ||
+    !HEX64.test(value.binding) ||
+    typeof value.session_ref !== 'string' ||
+    !SESSION_REF.test(value.session_ref) ||
+    Buffer.byteLength(value.session_ref, 'utf8') > MAX_SESSION_REF_BYTES ||
+    typeof value.operation_id !== 'string' ||
+    !OPERATION_ID.test(value.operation_id) ||
+    typeof value.request_id !== 'string' ||
+    !OPERATION_ID.test(value.request_id) ||
+    typeof value.revision !== 'string' ||
+    !REVISION.test(value.revision) ||
+    typeof value.projection_hash !== 'string' ||
+    !HEX64.test(value.projection_hash) ||
+    typeof value.captured_at !== 'string' ||
+    !ISO.test(value.captured_at) ||
+    typeof value.note_text !== 'string' ||
+    typeof value.note_sha256 !== 'string' ||
+    !HEX64.test(value.note_sha256) ||
+    noteFileName({
+      binding: value.binding,
+      sessionRef: value.session_ref,
+      operationId: value.operation_id,
+      requestId: value.request_id,
+      revision: value.revision,
+      projectionHash: value.projection_hash,
+      capturedAt: value.captured_at,
+      noteSha256: value.note_sha256,
+    }).slice(NOTE_FILE_PREFIX.length, -FILE_SUFFIX.length) !== name
+  )
+    throw new Error('note_corrupt');
+  try {
+    if (new Date(value.captured_at).toISOString() !== value.captured_at)
+      throw new Error('note_corrupt');
+  } catch {
+    throw new Error('note_corrupt');
+  }
+  if (Date.parse(value.captured_at) > Date.now() + NOTE_MAX_CLOCK_SKEW_MS)
+    throw new Error('note_corrupt');
+  if (Buffer.byteLength(value.note_text, 'utf8') > MAX_NOTE_TEXT_BYTES)
+    throw new Error('note_oversized');
+  if (textDigest(value.note_text) !== value.note_sha256) throw new Error('note_corrupt');
+  return /** @type {Record<string, unknown> & {schema_version:2, kind:'retained_note', binding:string, session_ref:string, operation_id:string, request_id:string, revision:string, projection_hash:string, captured_at:string, note_text:string, note_sha256:string}} */ (
+    value
+  );
+}
+
+/** @param {string} path @param {string} name */
+async function readNoteEnvelope(path, name) {
+  await ownedNoteFile(path);
+  let value;
+  try {
+    value = JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    throw new Error('note_corrupt');
+  }
+  const normalized = `${JSON.stringify(value)}\n`;
+  if (Buffer.byteLength(normalized, 'utf8') > MAX_NOTE_ENVELOPE_BYTES)
+    throw new Error('note_oversized');
+  return validateNoteEnvelope(value, name);
+}
+
+/** @param {string} stateDir */
+async function listNoteRecords(stateDir) {
+  let names;
+  try {
+    names = await readdir(stateDir);
+  } catch {
+    throw new Error('note_read_failed');
+  }
+  const records = [];
+  let aggregate = 0;
+  const scanLimit =
+    MAX_NOTE_AGGREGATE_BYTES + MAX_NOTE_ENVELOPE_BYTES * (MAX_NOTE_RECORDS_PER_BINDING + 1);
+  for (const name of names) {
+    if (name === LOCK_NAME || NOTE_TEMP_NAME.test(name) || NOTE_BACKUP_NAME.test(name)) continue;
+    if (!name.startsWith(NOTE_FILE_PREFIX)) continue;
+    const targetMatch = NOTE_TARGET_NAME.exec(name);
+    if (targetMatch === null) throw new Error('note_corrupt');
+    const path = join(stateDir, name);
+    const entry = await ownedNoteFile(path);
+    aggregate += entry.size;
+    if (aggregate > scanLimit) throw new Error('note_retention_failed');
+    const value = await readNoteEnvelope(path, targetMatch[1]);
+    records.push({
+      name,
+      path,
+      value,
+      bytes: entry.size,
+    });
+  }
+  return records;
+}
+
+/** @param {string} stateDir */
+async function cleanNoteStaleArtifacts(stateDir) {
+  let names;
+  try {
+    names = await readdir(stateDir);
+  } catch {
+    throw new Error('note_read_failed');
+  }
+  for (const name of names) {
+    if (name === LOCK_NAME || !name.startsWith(NOTE_FILE_PREFIX)) continue;
+    const isTemp = NOTE_TEMP_NAME.test(name);
+    const isBackup = NOTE_BACKUP_NAME.test(name);
+    if (!isTemp && !isBackup && NOTE_TARGET_NAME.test(name)) continue;
+    if (!isTemp && !isBackup) throw new Error('note_corrupt');
+    const path = join(stateDir, name);
+    const entry = await ownedNoteFile(path);
+    if (Date.now() - entry.mtimeMs < STALE_ARTIFACT_MS) throw new Error('note_lock_timeout');
+    if (isTemp) {
+      await unlink(path).catch(() => {
+        throw new Error('note_retention_failed');
+      });
+      continue;
+    }
+    const match = NOTE_BACKUP_NAME.exec(name);
+    if (match === null) throw new Error('note_corrupt');
+    const targetName = `${NOTE_FILE_PREFIX}${match[1]}${FILE_SUFFIX}`;
+    const target = join(stateDir, targetName);
+    let targetEntry;
+    try {
+      targetEntry = await lstat(target);
+    } catch (error) {
+      if (!(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT'))
+        throw new Error('note_read_failed');
+    }
+    if (targetEntry === undefined) {
+      await readNoteEnvelope(path, match[1]);
+      await rename(path, target);
+    } else {
+      if (targetEntry.isSymbolicLink() || !targetEntry.isFile()) throw new Error('note_corrupt');
+      await readNoteEnvelope(target, match[1]);
+      await readNoteEnvelope(path, match[1]);
+      await unlink(path).catch(() => {
+        throw new Error('note_retention_failed');
+      });
+    }
+  }
+}
+
+/** @param {string} stateDir */
+async function cleanStaleArtifacts(stateDir) {
+  let names;
+  try {
+    names = await readdir(stateDir);
+  } catch {
+    throw new Error('checkpoint_read_failed');
+  }
+  for (const name of names) {
+    if (name === LOCK_NAME) continue;
+    const isTemp = TEMP_NAME.test(name);
+    const isBackup = BACKUP_NAME.test(name);
+    if (!name.startsWith(FILE_PREFIX)) continue;
+    if (!isTemp && !isBackup && TARGET_NAME.test(name)) continue;
+    if (!isTemp && !isBackup) throw new Error('checkpoint_corrupt');
+    const path = join(stateDir, name);
+    let entry;
+    try {
+      entry = await lstat(path);
+    } catch {
+      throw new Error('checkpoint_read_failed');
+    }
+    if (
+      entry.isSymbolicLink() ||
+      !entry.isFile() ||
+      entry.size > MAX_SNAPSHOT_BYTES + 16 * 1024 ||
+      (entry.mode & 0o077) !== 0 ||
+      (typeof process.getuid === 'function' && entry.uid !== process.getuid())
+    )
+      throw new Error('checkpoint_corrupt');
+    if (Date.now() - entry.mtimeMs < STALE_ARTIFACT_MS) throw new Error('checkpoint_lock_timeout');
+    if (isTemp) {
+      await unlink(path).catch(() => {
+        throw new Error('checkpoint_retention_failed');
+      });
+      continue;
+    }
+    const match = BACKUP_NAME.exec(name);
+    if (match === null) throw new Error('checkpoint_corrupt');
+    const targetName = `${FILE_PREFIX}${match[1]}${FILE_SUFFIX}`;
+    const target = join(stateDir, targetName);
+    let targetEntry;
+    try {
+      targetEntry = await lstat(target);
+    } catch (error) {
+      if (!(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT'))
+        throw new Error('checkpoint_read_failed');
+    }
+    if (targetEntry === undefined) {
+      await readEnvelope(path, '', match[1]);
+      await rename(path, target);
+      continue;
+    }
+    if (targetEntry.isSymbolicLink() || !targetEntry.isFile())
+      throw new Error('checkpoint_corrupt');
+    await readEnvelope(target, '', match[1]);
+    await readEnvelope(path, '', match[1]);
+    await unlink(path).catch(() => {
+      throw new Error('checkpoint_retention_failed');
+    });
+  }
+}
+
+/** @param {string} stateDir @param {string} expectedBinding */
+async function verifyConfigBinding(stateDir, expectedBinding) {
+  const checkpointDir = resolve(stateDir);
+  const root = resolve(join(checkpointDir, '..', '..'));
+  if (checkpointDir !== join(root, 'claude', 'checkpoints')) throw new Error('state_dir_invalid');
+  await assertPath(root, false);
+  const rootEntry = await lstat(root);
+  if (!rootEntry.isDirectory() || rootEntry.isSymbolicLink()) throw new Error('state_dir_invalid');
+  if (typeof process.getuid === 'function' && rootEntry.uid !== process.getuid())
+    throw new Error('state_owner_mismatch');
+  if ((rootEntry.mode & 0o077) !== 0) throw new Error('state_permissions_invalid');
+  const configPath = join(root, 'config.json');
+  await assertPath(configPath, false);
+  const configEntry = await lstat(configPath);
+  if (configEntry.isSymbolicLink() || !configEntry.isFile()) throw new Error('state_dir_invalid');
+  if (typeof process.getuid === 'function' && configEntry.uid !== process.getuid())
+    throw new Error('state_owner_mismatch');
+  if ((configEntry.mode & 0o077) !== 0) throw new Error('state_permissions_invalid');
+  let config;
+  try {
+    config = JSON.parse(await readFile(configPath, 'utf8'));
+  } catch {
+    throw new Error('state_dir_invalid');
+  }
+  if (
+    !object(config) ||
+    typeof config.endpoint !== 'string' ||
+    typeof config.token !== 'string' ||
+    typeof config.disclosedAt !== 'string' ||
+    !ISO.test(config.disclosedAt) ||
+    config.token.length < 1 ||
+    /[\u0000-\u001f\u007f-\u009f]/u.test(config.token)
+  )
+    throw new Error('state_dir_invalid');
+  let endpoint;
+  try {
+    endpoint = new URL(config.endpoint);
+  } catch {
+    throw new Error('state_dir_invalid');
+  }
+  if (
+    endpoint.protocol !== 'https:' ||
+    endpoint.username ||
+    endpoint.password ||
+    endpoint.search ||
+    endpoint.hash
+  )
+    throw new Error('state_dir_invalid');
+  const actual = textDigest(
+    `${endpoint.toString()}\u0000${config.token}\u0000${config.disclosedAt}`,
+  );
+  if (actual !== expectedBinding) throw new Error('checkpoint_binding_mismatch');
+}
+
+/** @param {string} stateDir @param {string} targetName @param {Record<string, unknown>} envelope @param {{failAfterRename?: boolean}} [options] */
+async function atomicWrite(stateDir, targetName, envelope, options = {}) {
+  const target = join(stateDir, targetName);
+  const temporary = join(stateDir, `${targetName}.tmp-${process.pid}-${randomUUID()}`);
+  const backup = join(stateDir, `${targetName}.bak-${process.pid}-${randomUUID()}`);
+  const text = `${JSON.stringify(envelope)}\n`;
+  const bytes = Buffer.byteLength(text, 'utf8');
+  if (bytes > MAX_SNAPSHOT_BYTES + 16 * 1024) throw new Error('checkpoint_oversized');
+  let handle;
+  let movedPrevious = false;
+  try {
+    handle = await open(
+      temporary,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
+      0o600,
+    );
+    await handle.writeFile(text, 'utf8');
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    await ownedFile(temporary);
+    const readback = await readFile(temporary, 'utf8');
+    if (readback !== text) throw new Error('checkpoint_ack_failed');
+    try {
+      await ownedFile(target);
+      await rename(target, backup);
+      movedPrevious = true;
+    } catch (error) {
+      if (!(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT'))
+        throw error;
+    }
+    await rename(temporary, target);
+    await ownedFile(target);
+    if ((await readFile(target, 'utf8')) !== text) throw new Error('checkpoint_ack_failed');
+    if (options.failAfterRename === true) throw new Error('checkpoint_ack_failed');
+    if (movedPrevious) {
+      await ownedFile(backup);
+      await unlink(backup);
+      movedPrevious = false;
+    }
+  } catch (error) {
+    await handle?.close().catch(() => undefined);
+    await unlink(temporary).catch(() => undefined);
+    if (movedPrevious) {
+      await unlink(target).catch(() => undefined);
+      await rename(backup, target).catch(() => undefined);
+    }
+    if (error instanceof Error && ERROR_CODES.has(error.message)) throw error;
+    throw new Error('checkpoint_write_failed');
+  }
+  return bytes;
+}
+
+/** @param {string} stateDir @param {string} targetName @param {string} expectedText */
+async function removeInstalledNote(stateDir, targetName, expectedText) {
+  const target = join(stateDir, targetName);
+  let entry;
+  try {
+    entry = await lstat(target);
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') return;
+    throw new Error('note_retention_failed');
+  }
+  if (
+    entry.isSymbolicLink() ||
+    !entry.isFile() ||
+    (typeof process.getuid === 'function' && entry.uid !== process.getuid()) ||
+    (entry.mode & 0o077) !== 0
+  )
+    throw new Error('note_retention_failed');
+  let text;
+  try {
+    text = await readFile(target, 'utf8');
+  } catch {
+    throw new Error('note_retention_failed');
+  }
+  if (text !== expectedText) throw new Error('note_retention_failed');
+  await unlink(target).catch(() => {
+    throw new Error('note_retention_failed');
+  });
+}
+
+/** @param {string} stateDir @param {{name:string, path:string, text:string}} record */
+async function restoreRemovedNote(stateDir, record) {
+  const target = join(stateDir, record.name);
+  let entry;
+  try {
+    entry = await lstat(target);
+  } catch (error) {
+    if (!(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT'))
+      throw new Error('note_retention_failed');
+  }
+  if (entry !== undefined) {
+    if (
+      entry.isSymbolicLink() ||
+      !entry.isFile() ||
+      (typeof process.getuid === 'function' && entry.uid !== process.getuid()) ||
+      (entry.mode & 0o077) !== 0
+    )
+      throw new Error('note_retention_failed');
+    if ((await readFile(target, 'utf8')) !== record.text) throw new Error('note_retention_failed');
+    return;
+  }
+  const targetMatch = NOTE_TARGET_NAME.exec(record.name);
+  if (targetMatch === null) throw new Error('note_retention_failed');
+  let envelope;
+  try {
+    envelope = JSON.parse(record.text);
+  } catch {
+    throw new Error('note_retention_failed');
+  }
+  validateNoteEnvelope(envelope, targetMatch[1]);
+  await atomicWriteNote(stateDir, record.name, envelope);
+  if ((await readFile(target, 'utf8')) !== record.text) {
+    await removeInstalledNote(stateDir, record.name, `${JSON.stringify(envelope)}\n`).catch(
+      () => undefined,
+    );
+    throw new Error('note_retention_failed');
+  }
+}
+
+/** @param {string} stateDir @param {string} targetName @param {Record<string, unknown>} envelope @param {{failAfterRename?: boolean, removeNewOnFailure?: boolean}} [options] */
+async function atomicWriteNote(stateDir, targetName, envelope, options = {}) {
+  const target = join(stateDir, targetName);
+  const temporary = join(stateDir, `${targetName}.tmp-${process.pid}-${randomUUID()}`);
+  const backup = join(stateDir, `${targetName}.bak-${process.pid}-${randomUUID()}`);
+  const text = `${JSON.stringify(envelope)}\n`;
+  const bytes = Buffer.byteLength(text, 'utf8');
+  if (bytes > MAX_NOTE_ENVELOPE_BYTES) throw new Error('note_oversized');
+  let handle;
+  let movedPrevious = false;
+  let installed = false;
+  try {
+    handle = await open(
+      temporary,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
+      0o600,
+    );
+    await handle.writeFile(text, 'utf8');
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    await ownedNoteFile(temporary);
+    if ((await readFile(temporary, 'utf8')) !== text) throw new Error('note_ack_failed');
+    try {
+      await ownedNoteFile(target);
+      await rename(target, backup);
+      movedPrevious = true;
+    } catch (error) {
+      if (!(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT'))
+        throw error;
+    }
+    await rename(temporary, target);
+    installed = true;
+    await ownedNoteFile(target);
+    if ((await readFile(target, 'utf8')) !== text) throw new Error('note_ack_failed');
+    if (options.failAfterRename === true) throw new Error('note_ack_failed');
+    if (movedPrevious) {
+      await ownedNoteFile(backup);
+      await unlink(backup);
+      movedPrevious = false;
+    }
+  } catch (error) {
+    await handle?.close().catch(() => undefined);
+    await unlink(temporary).catch(() => undefined);
+    if (movedPrevious) {
+      await unlink(target).catch(() => undefined);
+      await rename(backup, target).catch(() => undefined);
+    } else if (installed && options.removeNewOnFailure === true) {
+      await removeInstalledNote(stateDir, targetName, text);
+    }
+    if (error instanceof Error && ERROR_CODES.has(error.message)) throw error;
+    throw new Error('note_write_failed');
+  }
+  return bytes;
+}
+
+/** @param {string} stateDir @param {string} binding @param {{operation_id?:string, session_ref:string, revision:string, preservation_mode:string, checkpoint:Record<string, unknown>, byte_count:number, payload_sha256:string}} input @param {{failAfterRename?: boolean}} [options] */
+async function save(stateDir, binding, input, options = {}) {
+  const payload = normalizedJson(input.checkpoint);
+  const bytes = Buffer.byteLength(payload, 'utf8');
+  if (bytes > MAX_SNAPSHOT_BYTES) throw new Error('checkpoint_oversized');
+  let parsed;
+  try {
+    parsed = JSON.parse(payload);
+  } catch {
+    throw new Error('checkpoint_invalid');
+  }
+  const checksum = textDigest(payload);
+  const name = fileName(input.session_ref, binding);
+  const envelope = {
+    schema_version: PROTOCOL_VERSION,
+    kind: 'completed',
+    binding,
+    ...(input.operation_id === undefined ? {} : { operation_id: input.operation_id }),
+    session_ref: input.session_ref,
+    revision: input.revision,
+    captured_at: input.checkpoint.capturedAt,
+    payload: parsed,
+    payload_sha256: checksum,
+  };
+  const records = await listRecords(stateDir, binding);
+  const current = records.find((record) => record.name === name);
+  const candidateFileBytes = Buffer.byteLength(`${JSON.stringify(envelope)}\n`, 'utf8');
+  let prospective =
+    records.reduce((total, record) => total + record.bytes, 0) -
+    (current?.bytes ?? 0) +
+    candidateFileBytes;
+  const retained = records
+    .filter((record) => record.name !== name && record.foreign !== true)
+    .sort((a, b) => String(b.value.captured_at).localeCompare(String(a.value.captured_at)));
+  while (retained.length + 1 > MAX_COMPLETED_CHECKPOINTS || prospective > MAX_STORED_BYTES) {
+    const removable = retained.pop();
+    if (removable === undefined) break;
+    await unlink(removable.path).catch(() => {
+      throw new Error('checkpoint_retention_failed');
+    });
+    prospective -= removable.bytes;
+  }
+  if (prospective > MAX_STORED_BYTES) throw new Error('checkpoint_retention_failed');
+  const byteCount = await atomicWrite(stateDir, name, envelope, options);
+  return {
+    schema_version: PROTOCOL_VERSION,
+    accepted: true,
+    operation: 'checkpoint.write',
+    binding,
+    ...(input.operation_id === undefined ? {} : { operation_id: input.operation_id }),
+    session_ref: input.session_ref,
+    revision: input.revision,
+    byte_count: bytes,
+    payload_sha256: checksum,
+    stored_bytes: byteCount,
+  };
+}
+
+/** @param {string} stateDir @param {string} binding @param {ReturnType<typeof parseNotesInput> & {operation:'notes.write'}} input @param {{failAfterRename?: boolean, failRetirementAt?: number, failAfterRetirementAt?: number, onRetirementStep?: (index:number, path:string) => Promise<void>, onRetirementRemoved?: (index:number, path:string) => Promise<void>}} [options] */
+async function saveNote(stateDir, binding, input, options = {}) {
+  if (input.binding !== binding) throw new Error('note_binding_mismatch');
+  validateNoteTimestamp(input.captured_at, 'note_invalid');
+  const envelope = {
+    schema_version: NOTES_PROTOCOL_VERSION,
+    kind: 'retained_note',
+    binding,
+    session_ref: input.session_ref,
+    operation_id: input.operation_id,
+    request_id: input.request_id,
+    revision: input.revision,
+    projection_hash: input.projection_hash,
+    captured_at: input.captured_at,
+    note_text: input.note_text,
+    note_sha256: input.note_sha256,
+  };
+  const targetName = noteFileName({
+    sessionRef: input.session_ref,
+    operationId: input.operation_id,
+    binding,
+    requestId: input.request_id,
+    revision: input.revision,
+    projectionHash: input.projection_hash,
+    capturedAt: input.captured_at,
+    noteSha256: input.note_sha256,
+  });
+  const candidateBytes = Buffer.byteLength(`${JSON.stringify(envelope)}\n`, 'utf8');
+  const candidateText = `${JSON.stringify(envelope)}\n`;
+  if (candidateBytes > MAX_NOTE_ENVELOPE_BYTES) throw new Error('note_oversized');
+  const records = await listNoteRecords(stateDir);
+  const sameOperation = records.filter(
+    (record) =>
+      record.value.binding === binding &&
+      record.value.session_ref === input.session_ref &&
+      record.value.operation_id === input.operation_id,
+  );
+  if (sameOperation.length > 1) throw new Error('note_corrupt');
+  const current = sameOperation[0];
+  if (current !== undefined) {
+    const currentValue = current.value;
+    const same =
+      currentValue.binding === binding &&
+      currentValue.session_ref === input.session_ref &&
+      currentValue.operation_id === input.operation_id &&
+      currentValue.request_id === input.request_id &&
+      currentValue.revision === input.revision &&
+      currentValue.projection_hash === input.projection_hash &&
+      currentValue.captured_at === input.captured_at &&
+      currentValue.note_sha256 === input.note_sha256 &&
+      currentValue.note_text === input.note_text;
+    if (!same) throw new Error('note_metadata_mismatch');
+    return noteWriteAck(input);
+  }
+  const sameBinding = records
+    .filter((record) => record.value.binding === binding)
+    .sort((left, right) => {
+      const timestamp = Date.parse(left.value.captured_at) - Date.parse(right.value.captured_at);
+      return timestamp || left.name.localeCompare(right.name);
+    });
+  const aggregate = records.reduce((total, record) => total + record.bytes, 0);
+  /** @type {Array<{name:string, path:string, bytes:number, value:Record<string, unknown>}>} */
+  const retirees = [];
+  while (
+    sameBinding.length - retirees.length + 1 > MAX_NOTE_RECORDS_PER_BINDING ||
+    aggregate - retirees.reduce((total, record) => total + record.bytes, 0) + candidateBytes >
+      MAX_NOTE_AGGREGATE_BYTES
+  ) {
+    const retire = sameBinding[retirees.length];
+    if (retire === undefined) throw new Error('note_retention_failed');
+    retirees.push(retire);
+  }
+  await atomicWriteNote(stateDir, targetName, envelope, { ...options, removeNewOnFailure: true });
+  const removed = [];
+  try {
+    for (const [index, retire] of retirees.entries()) {
+      await options.onRetirementStep?.(index, retire.path);
+      if (options.failRetirementAt === index) throw new Error('note_retention_failed');
+      removed.push({
+        name: retire.name,
+        path: retire.path,
+        text: await readFile(retire.path, 'utf8'),
+      });
+      await unlink(retire.path);
+      await options.onRetirementRemoved?.(index, retire.path);
+      if (options.failAfterRetirementAt === index) throw new Error('note_retention_failed');
+    }
+  } catch {
+    let rollbackFailed = false;
+    await removeInstalledNote(stateDir, targetName, candidateText).catch(() => {
+      rollbackFailed = true;
+    });
+    for (const previous of removed.reverse()) {
+      await restoreRemovedNote(stateDir, previous).catch(() => {
+        rollbackFailed = true;
+      });
+    }
+    if (rollbackFailed) throw new Error('note_retention_failed');
+    throw new Error('note_retention_failed');
+  }
+  return noteWriteAck(input);
+}
+
+/** @param {Record<string, unknown>} input */
+function noteWriteAck(input) {
+  return {
+    schema_version: NOTES_PROTOCOL_VERSION,
+    accepted: true,
+    operation: 'notes.write',
+    binding: input.binding,
+    session_ref: input.session_ref,
+    operation_id: input.operation_id,
+    note_sha256: input.note_sha256,
+    byte_count: Buffer.byteLength(/** @type {string} */ (input.note_text), 'utf8'),
+  };
+}
+
+/** @param {string} stateDir @param {string} binding @param {ReturnType<typeof parseNotesInput> & {operation:'notes.read'}} input */
+async function readNote(stateDir, binding, input) {
+  if (input.binding !== binding) throw new Error('note_binding_mismatch');
+  const records = await listNoteRecords(stateDir);
+  if (records.reduce((total, record) => total + record.bytes, 0) > MAX_NOTE_AGGREGATE_BYTES)
+    throw new Error('note_retention_failed');
+  const record = records.find(
+    (candidate) =>
+      candidate.value.binding === binding &&
+      candidate.value.session_ref === input.session_ref &&
+      candidate.value.operation_id === input.operation_id &&
+      candidate.value.note_sha256 === input.note_sha256,
+  );
+  if (record === undefined) throw new Error('note_not_found');
+  const captured = Date.parse(record.value.captured_at);
+  if (!Number.isFinite(captured) || Date.now() - captured > NOTE_EXPIRY_MS)
+    throw new Error('note_expired');
+  return {
+    schema_version: NOTES_PROTOCOL_VERSION,
+    accepted: true,
+    operation: 'notes.read',
+    binding,
+    session_ref: record.value.session_ref,
+    operation_id: record.value.operation_id,
+    note_sha256: record.value.note_sha256,
+    byte_count: Buffer.byteLength(record.value.note_text, 'utf8'),
+    note_text: record.value.note_text,
+  };
+}
+
+/** @param {string} stateDir @param {string} binding @param {ReturnType<typeof parseInput>} input @param {{failAfterRename?: boolean, failRetirementAt?: number, failAfterRetirementAt?: number, onRetirementStep?: (index:number, path:string) => Promise<void>, onRetirementRemoved?: (index:number, path:string) => Promise<void>}} [options] */
+export async function executeCheckpoint(stateDir, binding, input, options = {}) {
+  const isNote = input.operation === 'notes.write' || input.operation === 'notes.read';
+  let release;
+  try {
+    release = await acquireLock(stateDir);
+  } catch (error) {
+    if (isNote && error instanceof Error && error.message === 'checkpoint_lock_timeout')
+      throw new Error('note_lock_timeout');
+    if (isNote && error instanceof Error && error.message === 'checkpoint_lock_failed')
+      throw new Error('note_lock_failed');
+    throw error;
+  }
+  try {
+    await cleanStaleArtifacts(stateDir);
+    if (input.operation === 'notes.write') {
+      await cleanNoteStaleArtifacts(stateDir);
+      return await saveNote(stateDir, binding, input, options);
+    }
+    if (input.operation === 'notes.read') {
+      await cleanNoteStaleArtifacts(stateDir);
+      return await readNote(stateDir, binding, input);
+    }
+    return await save(stateDir, binding, input, options);
+  } finally {
+    await release();
+  }
+}
+
+/** @param {unknown} error @param {number} [protocolVersion] */
+function safeErrorCode(error, protocolVersion = PROTOCOL_VERSION) {
+  return error instanceof Error && ERROR_CODES.has(error.message)
+    ? error.message
+    : protocolVersion === NOTES_PROTOCOL_VERSION
+      ? 'note_read_failed'
+      : 'checkpoint_failed';
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  let protocolVersion = PROTOCOL_VERSION;
+  try {
+    const { stateDir, configDigest, binding } = parseArgs(argv);
+    await verifyConfigBinding(stateDir, configDigest);
+    const safeDir = await ownedDirectory(stateDir);
+    const rawInput = await readStdin();
+    try {
+      const hinted = JSON.parse(rawInput);
+      if (object(hinted) && hinted.schema_version === NOTES_PROTOCOL_VERSION)
+        protocolVersion = NOTES_PROTOCOL_VERSION;
+    } catch {
+      // parseInput emits the closed invalid_input response below.
+    }
+    const input = parseInput(rawInput);
+    protocolVersion = input.schema_version;
+    if (input.binding !== binding)
+      throw new Error(
+        input.operation.startsWith('notes.') ? 'note_binding_mismatch' : 'checkpoint_ack_failed',
+      );
+    const result = await executeCheckpoint(safeDir, binding, input);
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    return 0;
+  } catch (error) {
+    process.stdout.write(
+      `${JSON.stringify({ schema_version: protocolVersion, accepted: false, error_code: safeErrorCode(error, protocolVersion) })}\n`,
+    );
+    return 1;
+  }
+}
+
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === resolve(process.argv[1]))
+  process.exitCode = await main();