@piagent/platform 1.37.0 → 1.38.1

package/packages/piagent-core/runtime/checkpoints/checkpoint-authority.ts

@@ -0,0 +1,43 @@
+import fs from 'node:fs';
+import type { TurnCheckpointService } from './turn-checkpoints.mjs';
+
+export type CheckpointPort = Pick<TurnCheckpointService, 'list' | 'preview'> & {
+  restoreTo(target: string, expected: { digest: string; revision: string; tree: string }, guard?: () => void): ReturnType<TurnCheckpointService['restoreTo']>;
+};
+type Binding = { port: CheckpointPort; revoke(): void };
+const key = (cwd: string, sessionId: string) => `${fs.realpathSync(cwd)}\0${sessionId}`;
+
+// Only the live extension may supply a personal checkpoint port. Gateway must
+// never reconstruct mutation authority from persisted session messages.
+export class CheckpointAuthority {
+  #bindings = new Map<string, Binding>();
+  bind(cwd: string, sessionId: string, binding: Binding) {
+    const identity = key(cwd, sessionId), previous = this.#bindings.get(identity);
+    if (!previous && this.#bindings.size >= 1024) throw Error('checkpoint-authority-capacity');
+    previous?.revoke();
+    this.#bindings.set(identity, binding);
+    return () => {
+      binding.revoke();
+      if (this.#bindings.get(identity) === binding) this.#bindings.delete(identity);
+    };
+  }
+  resolve(cwd: string, sessionId: string) {
+    const identity = key(cwd, sessionId), binding = this.#bindings.get(identity);
+    if (!binding) throw Error('checkpoint-runtime-unavailable');
+    const current = () => this.#bindings.get(identity) === binding;
+    const check = () => { if (!current()) throw Error('checkpoint-authority-changed'); };
+    return {
+      current,
+      list: () => { check(); return binding.port.list(); },
+      preview: (target: string) => { check(); return binding.port.preview(target); },
+      restoreTo: (target: string, expected: { digest: string; revision: string; tree: string }, guard?: () => void) => {
+        check(); return binding.port.restoreTo(target, expected, () => { check(); guard?.(); });
+      },
+    };
+  }
+}
+
+// Pi's extension loader and the native Gateway can load distinct module copies.
+const AUTHORITY_KEY = Symbol.for('piagent.checkpoint-authority.v1');
+const root = globalThis as typeof globalThis & { [AUTHORITY_KEY]?: CheckpointAuthority };
+export const checkpointAuthority = root[AUTHORITY_KEY] ??= new CheckpointAuthority();

package/packages/piagent-core/runtime/checkpoints/checkpoint-refs.mjs

@@ -0,0 +1,51 @@
+// Trees referenced only by a private index are unreachable after it is removed.
+// Separate before/after refs keep their blobs alive through GC without commits,
+// branches, reflog entries, or changes to HEAD and the member's index.
+export class CheckpointRefs {
+  constructor(execute, sessionKey) {
+    if (!/^[a-f0-9]{64}$/.test(sessionKey)) throw Error('checkpoint-session-invalid');
+    this.execute = execute;
+    this.prefix = `refs/piagent/checkpoints/${sessionKey}/`;
+  }
+  #entries(point) {
+    if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(point.id)) throw Error('checkpoint-state-invalid');
+    return ['before', 'after'].flatMap(side => {
+      const tree = point[side];
+      if (side === 'after' && tree === null) return [];
+      if (typeof tree !== 'string' || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(tree)) throw Error('checkpoint-state-invalid');
+      return [[`${this.prefix}${point.id}/${side}`, tree]];
+    });
+  }
+  async #transaction(lines) {
+    const bytes = Buffer.from(['start', ...lines, 'prepare', 'commit', ''].join('\n'));
+    if (typeof this.execute !== 'function') return await this.execute.run(['update-ref', '--stdin'], bytes);
+    await this.execute(`printf %s ${bytes.toString('base64')} | base64 --decode | git update-ref --stdin`);
+  }
+  async #current(point) {
+    const entries = this.#entries(point), prefix = `${this.prefix}${point.id}/`;
+    const output = typeof this.execute === 'function'
+      ? await this.execute(`git for-each-ref --format='%(refname) %(objectname)' ${prefix}`)
+      : await this.execute.run(['for-each-ref', '--format=%(refname) %(objectname)', prefix]);
+    const current = new Map();
+    for (const line of output.trim().split('\n').filter(Boolean)) {
+      const [ref, tree, extra] = line.split(' ');
+      if (extra || !entries.some(([name, oid]) => name === ref && oid === tree) || current.has(ref))
+        throw Error('checkpoint-ref-changed');
+      current.set(ref, tree);
+    }
+    return { entries, current };
+  }
+  async pin(point) {
+    const { entries, current } = await this.#current(point);
+    // Ref creation and existing-value verification are atomic, so a race cannot
+    // replace a ref belonging to another retained checkpoint.
+    await this.#transaction(entries.map(([ref, tree]) => `${current.has(ref) ? 'verify' : 'create'} ${ref} ${tree}`));
+  }
+  async release(point) {
+    // A crash after deletion may leave cleanup pending. Missing refs are already
+    // released; changed values still refuse, including races before deletion.
+    const { entries, current } = await this.#current(point);
+    const present = entries.filter(([ref]) => current.has(ref));
+    if (present.length) await this.#transaction(present.map(([ref, tree]) => `delete ${ref} ${tree}`));
+  }
+}

package/packages/piagent-core/runtime/checkpoints/checkpoint-store.mjs

@@ -0,0 +1,179 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { ensurePrivateStateDirectory, resolveLocalStatePath } from '../../extensions/local-state-path.js';
+import { ownerAlive } from '../process-owner.mjs';
+
+export const MAX_CHECKPOINTS = 64;
+const MAX_BYTES = 128 * 1024;
+const hash = value => createHash('sha256').update(value).digest('hex');
+const oid = value => typeof value === 'string' && /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value);
+const id = value => typeof value === 'string' && /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(value);
+const exact = (value, keys) => value && typeof value === 'object' && !Array.isArray(value)
+  && Object.keys(value).length === keys.length && Object.keys(value).every(key => keys.includes(key));
+
+export function checkpointPoint(value) {
+  if (!exact(value, ['id', 'turnRef', 'before', 'after', 'at']) || !id(value.id)
+    || typeof value.turnRef !== 'string' || !value.turnRef.length || value.turnRef.length > 160 || /[\x00-\x1f]/.test(value.turnRef)
+    || !oid(value.before) || !oid(value.after) || value.before.length !== value.after.length
+    || !Number.isSafeInteger(value.at) || value.at < 0) throw Error('checkpoint-state-invalid');
+  return { ...value };
+}
+
+function refPoint(value) {
+  if (value?.after !== null) return checkpointPoint(value);
+  checkpointPoint({ ...value, after: value.before });
+  return { ...value };
+}
+function captureRecord(value) {
+  if (value === null) return null;
+  if (!exact(value, ['point', 'pid', 'token']) || !Number.isInteger(value.pid) || value.pid <= 1 || !id(value.token)
+    || value.point?.after !== null) throw Error('checkpoint-state-invalid');
+  return { point: refPoint(value.point), pid: value.pid, token: value.token };
+}
+
+const same = (a, b) => a.dev === b.dev && a.ino === b.ino && a.mode === b.mode && a.nlink === b.nlink
+  && a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
+function privateFile(stat) {
+  if (!stat.isFile() || stat.nlink !== 1 || stat.size > MAX_BYTES
+    || typeof process.getuid === 'function' && (stat.uid !== process.getuid() || (stat.mode & 0o077)))
+    throw Error('checkpoint-state-not-private');
+}
+
+// A small synchronous CAS transaction keeps every read/write inside the same
+// owner-only directory. The lock also rejects a second process with stale state.
+export class CheckpointStore {
+  #operation = null;
+  constructor(projectRoot, sessionId) {
+    if (typeof sessionId !== 'string' || !sessionId.length || sessionId.length > 4096) throw Error('checkpoint-session-invalid');
+    this.root = fs.realpathSync(projectRoot);
+    this.key = hash(`${this.root}\0${sessionId}`);
+    this.directory = path.join(this.root, '.pi', 'piagent-state', 'checkpoints');
+    this.file = path.join(this.directory, `${this.key}.json`);
+    this.lock = path.join(this.directory, `${this.key}.lock`);
+  }
+  #safe(file, kind) { return resolveLocalStatePath(this.root, file, { label: 'Checkpoint state', kind }); }
+  #read(file) {
+    const safe = this.#safe(file, 'file');
+    const fd = fs.openSync(safe, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    try {
+      const before = fs.fstatSync(fd); privateFile(before);
+      const bytes = fs.readFileSync(fd);
+      if (!same(before, fs.fstatSync(fd)) || !same(before, fs.lstatSync(this.#safe(file, 'file')))) throw Error('checkpoint-state-changed');
+      return { bytes, stat: before };
+    } finally { fs.closeSync(fd); }
+  }
+  load() {
+    let bytes;
+    try { ({ bytes } = this.#read(this.file)); }
+    catch (error) { if (error.code === 'ENOENT') return { revision: 'absent', points: [] }; throw error; }
+    const value = JSON.parse(bytes.toString('utf8'));
+    if (!(value.version === 1 && exact(value, ['version', 'sessionKey', 'points'])
+      || value.version === 2 && exact(value, ['version', 'sessionKey', 'points', 'retired'])
+      || value.version === 3 && exact(value, ['version', 'sessionKey', 'points', 'retired', 'staged'])
+      || value.version === 4 && exact(value, ['version', 'sessionKey', 'points', 'retired', 'staged', 'capture'])) || value.sessionKey !== this.key
+      || !Array.isArray(value.points) || value.points.length > MAX_CHECKPOINTS) throw Error('checkpoint-state-invalid');
+    const points = value.points.map(checkpointPoint);
+    if (new Set(points.map(point => point.id)).size !== points.length) throw Error('checkpoint-state-invalid');
+    const retired = value.version === 1 ? [] : value.retired;
+    if (!Array.isArray(retired) || retired.length > MAX_CHECKPOINTS + 1) throw Error('checkpoint-state-invalid');
+    const checkedRetired = retired.map(refPoint), ids = new Set(points.map(point => point.id));
+    for (const point of checkedRetired) {
+      if (ids.has(point.id)) throw Error('checkpoint-state-invalid');
+      ids.add(point.id);
+    }
+    const staged = value.version >= 3 ? value.staged : [];
+    if (!Array.isArray(staged) || staged.length > MAX_CHECKPOINTS + 1) throw Error('checkpoint-state-invalid');
+    const checkedStaged = staged.map(checkpointPoint);
+    for (const point of checkedStaged) {
+      if (ids.has(point.id)) throw Error('checkpoint-state-invalid');
+      ids.add(point.id);
+    }
+    const capture = value.version === 4 ? captureRecord(value.capture) : null;
+    if (capture && ids.has(capture.point.id)) throw Error('checkpoint-state-invalid');
+    return { revision: hash(bytes), points, retired: checkedRetired, staged: checkedStaged, capture };
+  }
+  #acquire() {
+    ensurePrivateStateDirectory(this.root, this.directory, 'Checkpoint directory');
+    const directory = fs.statSync(this.#safe(this.directory, 'directory'));
+    if (typeof process.getuid === 'function' && (directory.uid !== process.getuid() || (directory.mode & 0o077)))
+      throw Error('checkpoint-state-not-private');
+    const target = this.#safe(this.lock);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        const fd = fs.openSync(target, 'wx', 0o600);
+        const token = randomUUID();
+        try { fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, token })); }
+        finally { fs.closeSync(fd); }
+        const assertOwner = () => {
+          const current = this.#read(this.lock);
+          if (JSON.parse(current.bytes).token !== token) throw Error('checkpoint-lock-changed');
+        };
+        return { assertOwner, release: () => { assertOwner(); fs.unlinkSync(this.#safe(this.lock, 'file')); } };
+      } catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+        const current = this.#read(this.lock), owner = JSON.parse(current.bytes);
+        if (!exact(owner, ['pid', 'token']) || !Number.isInteger(owner.pid) || owner.pid <= 1 || !id(owner.token)) throw Error('checkpoint-lock-invalid');
+        if (ownerAlive(owner.pid, current.stat.mtimeMs)) throw Error('checkpoint-store-busy');
+        if (!same(current.stat, fs.lstatSync(this.#safe(this.lock, 'file')))) throw Error('checkpoint-lock-changed');
+        fs.unlinkSync(this.lock);
+      }
+    }
+    throw Error('checkpoint-store-busy');
+  }
+  // Hold the same lock through asynchronous Git effects and the final CAS save.
+  // A second process must refuse before touching files, not only when saving.
+  async operation(action) {
+    if (this.#operation) throw Error('checkpoint-store-busy');
+    const owner = this.#acquire();
+    this.#operation = owner;
+    try { return await action(); }
+    finally { this.#operation = null; owner.release(); }
+  }
+  save(points, expectedRevision, { clearRetired = false, staged = [], capture = undefined } = {}) {
+    if (!Array.isArray(points) || points.length > MAX_CHECKPOINTS + 1) throw Error('checkpoint-state-limit');
+    if (!Array.isArray(staged) || staged.length > MAX_CHECKPOINTS + 1) throw Error('checkpoint-state-limit');
+    const checkedStaged = staged.map(checkpointPoint);
+    const checked = points.map(checkpointPoint);
+    if (new Set(checked.map(point => point.id)).size !== checked.length) throw Error('checkpoint-state-invalid');
+    const retained = checked.slice(-MAX_CHECKPOINTS), dropped = checked.slice(0, -MAX_CHECKPOINTS);
+    const owner = this.#operation ?? this.#acquire();
+    owner.assertOwner();
+    let temporary;
+    try {
+      const previous = this.load();
+      if (previous.revision !== expectedRevision) throw Error('checkpoint-state-stale');
+      const nextCapture = capture === undefined ? previous.capture ?? null : captureRecord(capture);
+      const promotedIds = new Set([...retained, ...checkedStaged].map(point => point.id));
+      const abandoned = previous.capture && previous.capture.point.id !== nextCapture?.point.id
+        && !promotedIds.has(previous.capture.point.id) ? [previous.capture.point] : [];
+      const retainedIds = new Set(retained.map(point => point.id));
+      const retired = [...new Map([...(clearRetired ? [] : previous.retired ?? []), ...(clearRetired ? [] : previous.staged ?? []), ...previous.points, ...dropped, ...abandoned]
+        .filter(point => !retainedIds.has(point.id)).map(point => [point.id, point])).values()];
+      if (retired.length > MAX_CHECKPOINTS + 1) throw Error('checkpoint-state-limit');
+      const ids = new Set([...retained, ...retired].map(point => point.id));
+      for (const point of checkedStaged) {
+        if (ids.has(point.id)) throw Error('checkpoint-state-invalid');
+        ids.add(point.id);
+      }
+      if (nextCapture && ids.has(nextCapture.point.id)) throw Error('checkpoint-state-invalid');
+      const bytes = Buffer.from(JSON.stringify({ version: 4, sessionKey: this.key, points: retained, retired, staged: checkedStaged, capture: nextCapture }) + '\n');
+      if (bytes.length > MAX_BYTES) throw Error('checkpoint-state-limit');
+      temporary = this.#safe(path.join(this.directory, `${this.key}.${randomUUID()}.tmp`));
+      const fd = fs.openSync(temporary, 'wx', 0o600);
+      try { fs.writeFileSync(fd, bytes); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+      // Revalidate ancestors and destination after writing the private temp file.
+      const target = this.#safe(this.file);
+      if (this.load().revision !== expectedRevision) throw Error('checkpoint-state-stale');
+      fs.renameSync(this.#safe(temporary, 'file'), target); temporary = null;
+      if (process.platform !== 'win32') {
+        const directory = fs.openSync(this.#safe(this.directory, 'directory'), fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        try { fs.fsyncSync(directory); } finally { fs.closeSync(directory); }
+      }
+      return { revision: hash(bytes), points: retained, dropped, retired, staged: checkedStaged, capture: nextCapture };
+    } finally {
+      if (temporary) fs.unlinkSync(this.#safe(temporary, 'file'));
+      if (owner !== this.#operation) owner.release();
+    }
+  }
+}

package/packages/piagent-core/runtime/checkpoints/checkpoint-worker.ts

@@ -0,0 +1,28 @@
+import { PersonalCheckpointGit } from './personal-git.ts';
+import type { WorkspacePolicy } from '../../extensions/workspace-inspection.ts';
+
+// Reuse the guarded raw-byte adapter inside the sandbox. No checkout filters,
+// host fallback or project policy bypass is needed for company restoration.
+export function managedCheckpointOperation(cwd: string, policy: () => WorkspacePolicy, value: unknown) {
+  const input = value as Record<string, unknown>;
+  if (!input || input.kind !== 'checkpoint') throw Error('checkpoint-request-invalid');
+  const fields: Record<string, string[]> = { available: [], tree: [], changed: ['from', 'to'], restore: ['before', 'restore', 'remove', 'expectedTree'] };
+  if (typeof input.operation !== 'string' || !Object.hasOwn(fields, input.operation)) throw Error('checkpoint-request-invalid');
+  const expected = ['kind', 'operation', ...fields[input.operation]!];
+  if (Object.keys(input).length !== expected.length || Object.keys(input).some(key => !expected.includes(key))) throw Error('checkpoint-request-invalid');
+  const oid = (key: string) => {
+    if (typeof input[key] !== 'string' || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(input[key])) throw Error('checkpoint-object-invalid');
+    return input[key] as string;
+  };
+  const paths = (key: string) => {
+    const value = input[key];
+    if (!Array.isArray(value) || value.length > 10000 || value.some(path => typeof path !== 'string' || !path || path.length > 4096)) throw Error('checkpoint-path-invalid');
+    return value as string[];
+  };
+  const git = new PersonalCheckpointGit(cwd, policy);
+  if (input.operation === 'available') return git.available();
+  if (input.operation === 'tree') return git.tree();
+  if (input.operation === 'changed') return git.changed(oid('from'), oid('to'));
+  git.restore(oid('before'), paths('restore'), paths('remove'), oid('expectedTree'));
+  return { restored: true };
+}

package/packages/piagent-core/runtime/checkpoints/git-adapter.mjs

@@ -0,0 +1,36 @@
+// Git operations are shared; the caller chooses the execution boundary.
+// Keeping private-index timestamps makes Git recheck same-second, same-size edits.
+// HEAD and the member's index are never used as restoration targets.
+const SNAPSHOT = `set -e; git rev-parse --is-inside-work-tree >/dev/null 2>&1 || { echo NOREPO; exit 0; }
+top=$(git rev-parse --show-toplevel); cd "$top"; idx="$TMPDIR/piagent-checkpoint-$$"
+real=$(git rev-parse --git-path index); if [ -f "$real" ]; then cp -p "$real" "$idx"; fi
+GIT_INDEX_FILE="$idx" git add -A >/dev/null 2>&1; tree=$(GIT_INDEX_FILE="$idx" git write-tree); rm -f "$idx"; echo "TREE $tree"`;
+const b64 = list => Buffer.from(list.map(p => p + '\0').join(''), 'utf8').toString('base64');
+
+export class CheckpointGitAdapter {
+  constructor(execute) { this.execute = execute; }
+  async available() {
+    return (await this.execute('git rev-parse --is-inside-work-tree 2>/dev/null || true')).trim() === 'true';
+  }
+  async tree() {
+    const out = await this.execute(SNAPSHOT);
+    return out.match(/^TREE ([0-9a-f]{40,64})$/m)?.[1] ?? null;
+  }
+  async changed(from, to) {
+    const out = await this.execute(`top=$(git rev-parse --show-toplevel) && cd "$top" && git diff --no-renames --name-status -z ${from} ${to}`);
+    const parts = out.split('\0').filter(Boolean), files = [];
+    for (let i = 0; i + 1 < parts.length; i += 2) files.push({ status: parts[i].trim(), path: parts[i + 1] });
+    return files;
+  }
+  async restore(before, restore, remove, expectedTree, guard) {
+    const steps = ['set -e', 'top=$(git rev-parse --show-toplevel); cd "$top"; idx="$TMPDIR/piagent-undo-$$"'];
+    if (expectedTree) {
+      if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(expectedTree)) throw Error('checkpoint-object-invalid');
+      steps.unshift(`current=$(\n${SNAPSHOT}\n)`, `[ "$current" = "TREE ${expectedTree}" ] || { echo checkpoint-content-changed >&2; exit 1; }`);
+    }
+    if (restore.length) steps.push(`GIT_INDEX_FILE="$idx" git read-tree ${before}`, `printf %s ${b64(restore)} | base64 --decode | GIT_INDEX_FILE="$idx" git checkout-index -f -z --stdin`, 'rm -f "$idx"');
+    if (remove.length) steps.push(`printf %s ${b64(remove)} | base64 --decode | xargs -0 rm -f --`);
+    guard?.();
+    await this.execute(steps.join('\n'), guard);
+  }
+}

package/packages/piagent-core/runtime/checkpoints/persistent-history.mjs

@@ -0,0 +1,96 @@
+import { randomUUID } from 'node:crypto';
+import { ownerAlive } from '../process-owner.mjs';
+// The SDK loader and native Gateway may load separate module instances.
+const ownersKey = Symbol.for('piagent.checkpoint.capture-owners');
+const owners = globalThis[ownersKey] ??= new Set();
+// Publish refs before state; remove retired refs only after state is durable.
+// A failed save may leave extra refs, but must never expose unprotected trees.
+export class PersistentCheckpointHistory {
+  #token = randomUUID();
+  #revoked = false;
+  revoke() { this.#revoked = true; owners.delete(this.#token); }
+  constructor(store, refs) {
+    this.store = store; this.refs = refs;
+    this.current = store.load();
+  }
+  operation(action) {
+    return this.store.operation(async () => {
+      // A closed owner may have changed only capture/cleanup metadata. The
+      // service's in-memory turn stack remains valid only when points are equal.
+      const latest = this.store.load();
+      if (latest.revision !== this.current.revision && JSON.stringify(latest.points) === JSON.stringify(this.current.points)) this.current = latest;
+      this.assertCurrent(); await this.#checkCapture(); await this.#drainRetired(); return await action();
+    });
+  }
+  async close() {
+    try {
+      if (this.store.load().capture?.token !== this.#token) return;
+      await this.store.operation(async () => {
+        const latest = this.store.load();
+        if (latest.capture?.token === this.#token) this.current = this.store.save(latest.points, latest.revision, { capture: null });
+      });
+    } finally { this.revoke(); }
+  }
+  load() { return structuredClone(this.current.points); }
+  assertCurrent() {
+    if (this.#revoked) throw Error('checkpoint-authority-changed');
+    if (this.store.load().revision !== this.current.revision) throw Error('checkpoint-state-stale');
+  }
+  async #checkCapture() {
+    const capture = this.current.capture;
+    if (!capture || capture.token === this.#token) return;
+    if (capture.pid === process.pid) {
+      if (owners.has(capture.token)) throw Error('checkpoint-turn-owned');
+    } else if (ownerAlive(capture.pid, capture.point.at)) throw Error('checkpoint-turn-owned');
+    // An interrupted turn has no trustworthy after snapshot. Keep its edits,
+    // retire only its refs, and leave completed history available for drift checks.
+    this.current = this.store.save(this.current.points, this.current.revision, { capture: null });
+    await this.#drainRetired();
+  }
+  async #drainRetired() {
+    const retired = [...(this.current.retired ?? []), ...(this.current.staged ?? [])];
+    if (!retired.length) return;
+    for (const point of retired) await this.refs.release(point);
+    // A crash before acknowledgement retries exact-value deletion. Ref release
+    // accepts already missing refs, so no durable cleanup entry is lost early.
+    this.current = this.store.save(this.current.points, this.current.revision, { clearRetired: true });
+  }
+  async begin(point) {
+    await this.prepare();
+    if (this.current.capture) throw Error('checkpoint-turn-owned');
+    const capture = { point: { ...point, after: null }, pid: process.pid, token: this.#token };
+    if (owners.size >= 1024) throw Error('checkpoint-session-capacity');
+    owners.add(this.#token);
+    try { this.current = this.store.save(this.current.points, this.current.revision, { capture }); }
+    catch (error) { owners.delete(this.#token); throw error; }
+    await this.refs.pin(capture.point);
+  }
+  async prepare() { this.assertCurrent(); await this.#checkCapture(); await this.#drainRetired(); this.assertCurrent(); }
+  async abandon(point) {
+    this.assertCurrent(); await this.#checkCapture();
+    if (this.current.capture?.point.id !== point.id) throw Error('checkpoint-capture-mismatch');
+    this.current = this.store.save(this.current.points, this.current.revision, { capture: null });
+    owners.delete(this.#token);
+    await this.#drainRetired();
+  }
+  async save(points) {
+    this.assertCurrent(); await this.#checkCapture();
+    // Do not accumulate another batch while an earlier cleanup is blocked.
+    await this.#drainRetired();
+    const existing = new Set(this.current.points.map(point => point.id));
+    const staged = points.filter(point => !existing.has(point.id));
+    // Record new refs before creating them. A failed pin/publication or process
+    // exit leaves enough data for exact-value cleanup on the next operation.
+    if (staged.length) {
+      this.current = this.store.save(this.current.points, this.current.revision, { staged, capture: null });
+      owners.delete(this.#token);
+    }
+    for (const point of points) await this.refs.pin(point);
+    const saved = this.store.save(points, this.current.revision);
+    this.current = saved;
+    // Publication is the commit point. Cleanup failure must not leave the
+    // caller using an old stack after files and durable history have advanced.
+    try { await this.#drainRetired(); } catch { /* Retry before the next publication or turn. */ }
+    return structuredClone(saved.points);
+  }
+}