@piagent/platform 1.37.1 → 1.38.2

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);
+  }
+}

package/packages/piagent-core/runtime/checkpoints/personal-git.ts

@@ -0,0 +1,272 @@
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { workspacePathFlags, type WorkspacePolicy } from '../../extensions/workspace-inspection.ts';
+import { effectiveProtectedPaths, matchesProtectedPath } from '../../extensions/workspace-policy.js';
+import { inspectWorkspaceEntry, readWorkspaceLink, WorkspaceReadError } from '../../security/workspace-file-reader.ts';
+
+// Untracked files above this size (a dataset, a build artifact nobody ignored)
+// stay out of snapshots: undo leaves them alone rather than copying them into
+// Git objects on every turn. Tracked files of any size are included.
+const MAX_UNTRACKED = 100 << 20, MAX_ENTRIES = 500000, OUTPUT = 256 << 20;
+const executable = process.platform === 'darwin' ? '/usr/bin/git' : 'git';
+const oid = (value: string) => { if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value)) throw Error('checkpoint-object-invalid'); return value; };
+const internal = (file: string) => file.split('/').includes('.git') || file === '.pi/piagent-state' || file.startsWith('.pi/piagent-state/');
+const safe = (file: string) => Boolean(file) && file.length <= 4096 && !/[\\\x00-\x1f\x7f]/.test(file) && !path.isAbsolute(file)
+  && !file.split('/').some(part => !part || part === '.' || part === '..') && !internal(file);
+function valid(file: string) { if (!safe(file)) throw Error('checkpoint-path-invalid'); }
+type FileState = { mode: string; fingerprint: string; permissions: number };
+type TreeEntry = { mode: string; object: string; file: string };
+type Hashed = { key: string; object: string };
+const statKey = (stat: fs.Stats) => `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}:${stat.mode}`;
+
+// Snapshots hash raw bytes into a private index; neither Git filters nor
+// checkout commands read or write workspace paths. One `hash-object
+// --stdin-paths` per snapshot, and files unchanged since the last snapshot are
+// not read again. Files Git cannot snapshot as blobs (submodules, sockets) are
+// left out, so undo never touches them, instead of failing the turn.
+// With `store`, objects and refs live in a private repository inside the Git
+// directory: `git push --mirror` and the project's refs never see them, and the
+// project's objects serve as alternates so tracked content is not copied.
+export class PersonalCheckpointGit {
+  readonly root: string;
+  readonly #policy: () => WorkspacePolicy;
+  readonly #store: boolean;
+  #repository: string | null = null;
+  #objects: string | undefined;
+  #hashed = new Map<string, Hashed>();
+  constructor(root: string, policy: () => WorkspacePolicy, { store = false }: { store?: boolean } = {}) {
+    this.root = fs.realpathSync(root); this.#policy = policy; this.#store = store;
+  }
+  #run(args: string[], input?: Buffer, index?: string, cwd = this.root, objects: string | null | undefined = this.#objects, output?: number): Buffer {
+    // `objects` null: the project's own repository (listing files, finding it).
+    const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !/^GIT_/i.test(name)));
+    Object.assign(env, { GIT_OPTIONAL_LOCKS: '0', GIT_LITERAL_PATHSPECS: '1', ...(index ? { GIT_INDEX_FILE: index } : {}) });
+    const argv = ['-C', cwd, ...(objects ? [`--git-dir=${objects}`] : []), ...args];
+    return execFileSync(executable, argv, { env, input, timeout: 120000, maxBuffer: OUTPUT,
+      stdio: [input ? 'pipe' : 'ignore', output ?? 'pipe', 'pipe'] }) ?? Buffer.alloc(0);
+  }
+  #top(): string | null {
+    if (fs.realpathSync(this.root) !== this.root) throw Error('checkpoint-project-changed');
+    let top: string;
+    try { top = fs.realpathSync(this.#run(['rev-parse', '--show-toplevel'], undefined, undefined, this.root, null).toString().trim()); }
+    catch (error) {
+      if (!this.#repository && /not a git repository/i.test(String((error as { stderr?: Buffer }).stderr))) return null;
+      throw Error('checkpoint-repository-unavailable');
+    }
+    const relative = path.relative(top, this.root);
+    if (relative === '..' || relative.startsWith('../') || path.isAbsolute(relative) || this.#repository && this.#repository !== top)
+      throw Error('checkpoint-project-changed');
+    this.#repository = top;
+    if (this.#store && !this.#objects) this.#objects = this.#openStore();
+    return top;
+  }
+  #openStore(): string {
+    const common = path.resolve(this.root, this.#run(['rev-parse', '--git-common-dir'], undefined, undefined, this.root, null).toString().trim());
+    const parent = path.join(common, 'piagent'), store = path.join(parent, 'checkpoints.git');
+    for (const directory of [parent, store]) {
+      try { fs.mkdirSync(directory, { mode: 0o700 }); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error; }
+      const stat = fs.lstatSync(directory);
+      if (!stat.isDirectory() || typeof process.getuid === 'function' && stat.uid !== process.getuid()) throw Error('checkpoint-store-invalid');
+    }
+    if (!fs.existsSync(path.join(store, 'HEAD'))) this.#run(['init', '--bare', '--quiet', '--template=', store], undefined, undefined, this.root, null);
+    const alternates = path.join(store, 'objects', 'info', 'alternates'), objects = path.join(common, 'objects') + '\n';
+    fs.mkdirSync(path.dirname(alternates), { recursive: true });
+    if (!fs.existsSync(alternates) || fs.readFileSync(alternates, 'utf8') !== objects) fs.writeFileSync(alternates, objects, { mode: 0o600 });
+    return store;
+  }
+  available() { return this.#top() !== null; }
+  #flags(file: string, write = false) {
+    valid(file);
+    const policy = this.#policy(), flags = workspacePathFlags(file, policy);
+    if (flags.protected) throw Error(`checkpoint-path-protected: ${file}`);
+    if (write && (flags.readOnly || policy.readOnly === undefined && policy.profile.permissionProfile === 'read-only'))
+      throw Error(`checkpoint-read-only: ${file}`);
+  }
+  // Drift checks compare identity and timestamps, which every write changes,
+  // so a restore never reads whole files into memory.
+  #state(file: string): FileState | null {
+    this.#flags(file);
+    let stat: fs.Stats;
+    try { stat = inspectWorkspaceEntry(this.root, file); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null; throw error; }
+    let mode: string, link = '';
+    if (stat.isSymbolicLink()) { mode = '120000'; link = readWorkspaceLink(this.root, file); }
+    else if (stat.isFile()) mode = stat.mode & 0o111 ? '100755' : '100644';
+    else throw Error(`checkpoint-unsupported-entry: ${file}`);
+    return { mode, permissions: stat.mode & 0o777, fingerprint: `${mode}:${statKey(stat)}:${link}` };
+  }
+  #list(args: string[]) {
+    return this.#run(['ls-files', ...args, '-z', '--', '.'], undefined, undefined, this.root, null)
+      .toString('utf8').split('\0').filter(Boolean);
+  }
+  #hash(files: { file: string; key: string }[], top: string): string[] {
+    if (!files.length) return [];
+    const input = Buffer.from(files.map(item => path.join(this.root, item.file)).join('\n') + '\n');
+    try {
+      const objects = this.#run(['hash-object', '-w', '--no-filters', '--stdin-paths'], input, undefined, top).toString().trim().split('\n');
+      if (objects.length !== files.length) throw Error('checkpoint-object-invalid');
+      return objects.map(oid);
+    } catch {
+      // A file removed while the batch ran: hash the rest one by one.
+      return files.map(item => {
+        try { return oid(this.#run(['hash-object', '-w', '--no-filters', '--', path.join(this.root, item.file)], undefined, undefined, top).toString().trim()); }
+        catch { if (!fs.existsSync(path.join(this.root, item.file))) return ''; throw Error(`checkpoint-hash-failed: ${item.file}`); }
+      });
+    }
+  }
+  tree(): string | null {
+    const top = this.#top(); if (!top) return null;
+    const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'piagent-checkpoint-')); fs.chmodSync(temporary, 0o700);
+    const index = path.join(temporary, 'index'), policy = this.#policy();
+    // workspacePathFlags(...).protected, with each folder decided once per snapshot.
+    const patterns = effectiveProtectedPaths(policy.policy, policy.profile).readProtectedPaths, known = new Map<string, boolean>();
+    const protectedPath = (file: string) => file.split('/').some((_, i, parts) => {
+      const prefix = parts.slice(0, i + 1).join('/');
+      if (!known.has(prefix)) known.set(prefix, !!matchesProtectedPath(prefix, patterns));
+      return known.get(prefix);
+    });
+    try {
+      const tracked = new Set(this.#list(['--cached'])), records: string[] = [], pending: { file: string; mode: string; key: string }[] = [];
+      const listed = [...new Set(this.#list(['--cached', '--others', '--exclude-standard']))].sort();
+      if (listed.length > MAX_ENTRIES) throw Error('checkpoint-file-limit');
+      const now = Date.now(), seen = new Set<string>();
+      for (const file of listed) {
+        if (!safe(file) || protectedPath(file)) continue;
+        let stat: fs.Stats;
+        try { stat = inspectWorkspaceEntry(this.root, file); }
+        catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT' || error instanceof WorkspaceReadError) continue; throw error; }
+        if (stat.isSymbolicLink()) {
+          let target: string;
+          try { target = readWorkspaceLink(this.root, file); } catch { continue; }
+          const object = oid(this.#run(['hash-object', '-w', '--no-filters', '--stdin'], Buffer.from(target), undefined, top).toString().trim());
+          records.push(`120000 ${object}\t${file}\0`); continue;
+        }
+        if (!stat.isFile() || !tracked.has(file) && stat.size > MAX_UNTRACKED) continue;
+        const mode = stat.mode & 0o111 ? '100755' : '100644', key = statKey(stat), known = this.#hashed.get(file);
+        seen.add(file);
+        if (known?.key === key) records.push(`${mode} ${known.object}\t${file}\0`);
+        // A file written within the last two seconds may change again without
+        // moving its timestamp: hash it now, remember it next time.
+        else pending.push({ file, mode, key: now - stat.mtimeMs > 2000 ? key : '' });
+      }
+      this.#hash(pending, top).forEach((object, i) => {
+        const item = pending[i]!; if (!object) return;
+        if (item.key) this.#hashed.set(item.file, { key: item.key, object }); else this.#hashed.delete(item.file);
+        records.push(`${item.mode} ${object}\t${item.file}\0`);
+      });
+      for (const file of this.#hashed.keys()) if (!seen.has(file)) this.#hashed.delete(file);
+      this.#run(['read-tree', '--empty'], undefined, index, top);
+      this.#run(['update-index', '-z', '--index-info'], Buffer.from(records.join('')), index, top);
+      return oid(this.#run(['write-tree'], undefined, index, top).toString().trim());
+    } finally { fs.rmSync(temporary, { recursive: true, force: true }); }
+  }
+  #entries(tree: string): Map<string, TreeEntry> {
+    const records = this.#run(['ls-tree', '--full-tree', '-r', '-z', oid(tree)]).toString('utf8').split('\0').filter(Boolean);
+    if (records.length > MAX_ENTRIES) throw Error('checkpoint-file-limit');
+    const entries = new Map<string, TreeEntry>();
+    for (const record of records) {
+      const match = /^(100644|100755|120000) blob ([a-f0-9]{40}|[a-f0-9]{64})\t([\s\S]+)$/.exec(record);
+      if (!match) throw Error('checkpoint-tree-invalid');
+      const mode = match[1]!, object = match[2]!, file = match[3]!; valid(file);
+      if (entries.has(file)) throw Error('checkpoint-tree-invalid');
+      entries.set(file, { mode, object, file });
+    }
+    return entries;
+  }
+  changed(from: string, to: string) {
+    this.#top();
+    const before = this.#entries(from), after = this.#entries(to);
+    return [...new Set([...before.keys(), ...after.keys()])].sort().flatMap(file => {
+      const a = before.get(file), b = after.get(file);
+      return a?.object === b?.object && a?.mode === b?.mode ? [] : [{ status: !a ? 'A' : !b ? 'D' : 'M', path: file }];
+    });
+  }
+  restore(before: string, restore: string[], remove: string[], expectedTree?: string) {
+    if (!expectedTree) throw Error('checkpoint-current-tree-required');
+    const currentTree = this.tree();
+    if (currentTree !== oid(expectedTree)) {
+      const affected = new Set([...restore, ...remove]);
+      const changed = currentTree ? this.changed(expectedTree, currentTree).map(entry => entry.path).filter(file => affected.has(file)) : [];
+      if (!currentTree || changed.length) throw Error(`checkpoint-content-changed${changed.length ? ': ' + changed.slice(0, 5).join(', ') : ''}`);
+    }
+    const entries = this.#entries(before), files = [...restore, ...remove], current = this.#entries(expectedTree);
+    if (files.length > MAX_ENTRIES || new Set(files).size !== files.length) throw Error('checkpoint-file-limit');
+    const states = new Map<string, FileState | null>(), objects: string[] = [];
+    for (const file of files) {
+      this.#flags(file, true); states.set(file, this.#state(file));
+      // On disk but outside the current snapshot (ignored since, or too large
+      // to snapshot): its present content was never compared, so keep it.
+      if (states.get(file) && !current.has(file)) throw Error(`checkpoint-content-changed: ${file}`);
+      if (!restore.includes(file)) continue;
+      const entry = entries.get(file); if (!entry) throw Error('checkpoint-tree-invalid');
+      objects.push(entry.object);
+    }
+    // Every object must be readable before the first file changes; contents are
+    // then streamed straight into each replacement, whatever their size.
+    if (objects.length) {
+      const missing = this.#run(['cat-file', '--batch-check=%(objectname) %(objecttype)'], Buffer.from(objects.join('\n') + '\n'))
+        .toString().trim().split('\n').filter(line => !/^[a-f0-9]+ blob$/.test(line));
+      if (missing.length) throw Error('checkpoint-object-missing');
+    }
+    // Preflight every file before the first effect; recheck it again immediately
+    // before its atomic replacement. No Git checkout/filter can bypass policy.
+    for (const file of files) {
+      this.#flags(file, true);
+      if ((this.#state(file)?.fingerprint ?? null) !== (states.get(file)?.fingerprint ?? null)) throw Error(`checkpoint-content-changed: ${file}`);
+    }
+    // An error after the first file changed says so (checkpoint-partial), so
+    // the caller reports an uncertain result rather than a clean refusal.
+    let changed = 0;
+    try { for (const file of files) {
+      this.#flags(file, true);
+      if ((this.#state(file)?.fingerprint ?? null) !== (states.get(file)?.fingerprint ?? null)) throw Error(`checkpoint-content-changed: ${file}`);
+      const target = path.join(this.root, file);
+      if (remove.includes(file)) { if (states.get(file)) { fs.unlinkSync(target); changed++; this.#prune(file, entries); } continue; }
+      const parts = file.split('/');
+      for (let i = 1; i < parts.length; i++) {
+        const parent = parts.slice(0, i).join('/'); this.#flags(parent, true);
+        try { fs.mkdirSync(path.join(this.root, parent)); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error; }
+        const stat = inspectWorkspaceEntry(this.root, parent);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) throw Error('checkpoint-unsafe-parent');
+      }
+      const parent = path.dirname(target), parentStat = fs.lstatSync(parent);
+      const temporary = path.join(parent, `.piagent-checkpoint-${randomUUID()}`), entry = entries.get(file)!;
+      try {
+        if (entry.mode === '120000') fs.symlinkSync(this.#run(['cat-file', 'blob', entry.object]).toString('utf8'), temporary);
+        else {
+          const fd = fs.openSync(temporary, 'wx', 0o600);
+          try {
+            this.#run(['cat-file', 'blob', entry.object], undefined, undefined, this.root, this.#objects, fd);
+            // A file the turn deleted comes back as a new file would be made.
+            const permissions = states.get(file)?.permissions ?? 0o666 & ~process.umask();
+            fs.fchmodSync(fd, (permissions & 0o666) | (entry.mode === '100755' ? 0o111 : 0));
+            fs.fsyncSync(fd);
+          } finally { fs.closeSync(fd); }
+        }
+        this.#flags(file, true);
+        const currentParent = fs.lstatSync(parent);
+        if (fs.realpathSync(parent) !== parent || currentParent.dev !== parentStat.dev || currentParent.ino !== parentStat.ino
+          || (this.#state(file)?.fingerprint ?? null) !== (states.get(file)?.fingerprint ?? null)) throw Error(`checkpoint-content-changed: ${file}`);
+        fs.renameSync(temporary, target); changed++;
+      } finally { fs.rmSync(temporary, { force: true }); }
+    } } catch (error) { throw changed ? Error(`checkpoint-partial: ${(error as Error).message}`) : error; }
+  }
+  // Folders the turn created and its undo emptied go too; a folder that held
+  // files before the turn, or holds anything now, stays.
+  #prune(file: string, before: Map<string, TreeEntry>) {
+    const parts = file.split('/');
+    for (let i = parts.length - 1; i > 0; i--) {
+      const folder = parts.slice(0, i).join('/');
+      if ([...before.keys()].some(entry => entry.startsWith(folder + '/'))) return;
+      try { fs.rmdirSync(path.join(this.root, folder)); } catch { return; }
+    }
+  }
+  // Only the ref manager receives this plumbing port; it never accepts shell.
+  readonly refsExecutor = { run: (args: string[], input?: Buffer) => {
+    if (!this.#top() || !['for-each-ref', 'update-ref'].includes(args[0] ?? '')) throw Error('checkpoint-ref-command-invalid');
+    return this.#run(args, input).toString('utf8');
+  } };
+}

package/packages/piagent-core/runtime/checkpoints/personal-runtime.ts

@@ -0,0 +1,158 @@
+import fs from 'node:fs';
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { WorkspacePolicy } from '../../extensions/workspace-inspection.ts';
+import { isCompanySession } from '../../extensions/company-session-guard.ts';
+import { PersonalCheckpointGit } from './personal-git.ts';
+import { CheckpointStore } from './checkpoint-store.mjs';
+import { CheckpointRefs } from './checkpoint-refs.mjs';
+import { PersistentCheckpointHistory } from './persistent-history.mjs';
+import { pruneStaleCheckpointSessions } from './prune.mjs';
+import { TurnCheckpointService, checkpointOwnershipError } from './turn-checkpoints.mjs';
+import { checkpointAuthority } from './checkpoint-authority.ts';
+import { workspaceMemberEditsSince } from '../session/workspace-member-edits.mjs';
+
+type Run = { turnRef: string; checkpoint?: unknown };
+type Binding = { ctx: ExtensionContext; service: TurnCheckpointService; run?: Run; active: boolean; guard?: () => void; unbind(): void };
+
+// The extension owns these bindings; refreshed contexts supply live permissions.
+export class PersonalCheckpointRuntime {
+  #bindings = new Map<string, Binding>();
+  #pruned = new Set<string>();
+  #tail = Promise.resolve();
+  #pending = 0;
+  private policy: (ctx: ExtensionContext) => WorkspacePolicy;
+  constructor(policy: (ctx: ExtensionContext) => WorkspacePolicy) { this.policy = policy; }
+  #key(ctx: ExtensionContext) {
+    if (ctx.model?.provider === 'agent_watch_managed' || isCompanySession(ctx)) throw Error('checkpoint-company-boundary-required');
+    const session = ctx.sessionManager.getSessionId();
+    if (!session) throw Error('checkpoint-session-unavailable');
+    return `${fs.realpathSync(ctx.cwd)}\0${session}`;
+  }
+  #binding(ctx: ExtensionContext): Binding {
+    const key = this.#key(ctx);
+    let binding = this.#bindings.get(key);
+    if (!binding) {
+      if (this.#bindings.size >= 64) throw Error('checkpoint-session-capacity');
+      const state = { ctx, active: true } as Binding;
+      const git = new PersonalCheckpointGit(ctx.cwd, () => {
+        if (!state.active) throw Error('checkpoint-authority-changed');
+        state.guard?.();
+        return this.policy(state.ctx);
+      }, { store: true });
+      const store = new CheckpointStore(ctx.cwd, ctx.sessionManager.getSessionId());
+      if (!this.#pruned.has(store.directory)) {
+        this.#pruned.add(store.directory);
+        try { if (git.available()) pruneStaleCheckpointSessions(store.directory, git.refsExecutor, store.key); } catch { /* best effort */ }
+      }
+      state.service = new TurnCheckpointService(git, {
+        busy: () => { state.guard?.(); return !state.active || !state.ctx.isIdle(); },
+        history: new PersistentCheckpointHistory(store, new CheckpointRefs(git.refsExecutor, store.key)),
+        memberEdits: since => workspaceMemberEditsSince(state.ctx.sessionManager, since),
+      });
+      state.unbind = checkpointAuthority.bind(ctx.cwd, ctx.sessionManager.getSessionId(), {
+        revoke: () => { state.active = false; state.service.revoke(); },
+        port: {
+          list: () => this.list(state.ctx),
+          preview: target => this.preview(state.ctx, target),
+          restoreTo: (target, expected, guard) => this.restoreTo(state.ctx, target, expected, guard),
+        },
+      });
+      binding = state;
+      this.#bindings.set(key, binding);
+    }
+    if (!binding.active) throw Error('checkpoint-authority-changed');
+    binding.ctx = ctx;
+    return binding;
+  }
+  bind(ctx: ExtensionContext) {
+    if (ctx.model?.provider === 'agent_watch_managed' || isCompanySession(ctx)) return;
+    this.#binding(ctx);
+  }
+  async #settledBinding(ctx: ExtensionContext) {
+    const binding = this.#binding(ctx);
+    if (ctx.isIdle() && binding.run) {
+      await binding.service.finish(binding.run);
+      binding.run = undefined;
+    }
+    return binding;
+  }
+  list(ctx: ExtensionContext) {
+    return this.#serial(async () => (await this.#settledBinding(ctx)).service.list());
+  }
+  preview(ctx: ExtensionContext, target: string) {
+    return this.#serial(async () => (await this.#settledBinding(ctx)).service.preview(target));
+  }
+  restoreTo(ctx: ExtensionContext, target: string, expected: { digest: string; revision: string; tree: string }, guard?: () => void) {
+    return this.#serial(async () => {
+      guard?.();
+      const binding = await this.#settledBinding(ctx);
+      binding.guard = guard;
+      try { guard?.(); return await binding.service.restoreTo(target, expected); }
+      finally { binding.guard = undefined; }
+    });
+  }
+  #serial<T>(action: () => Promise<T>): Promise<T> {
+    if (this.#pending >= 128) return Promise.reject(Error('checkpoint-command-capacity'));
+    this.#pending++;
+    const operation = this.#tail.then(action, action);
+    this.#tail = operation.then(() => {}, () => {});
+    return operation.finally(() => { this.#pending--; });
+  }
+  beforeMutation(ctx: ExtensionContext) {
+    return this.#serial(async () => {
+      const binding = this.#binding(ctx);
+      let turn: string | undefined;
+      try {
+        const user = [...ctx.sessionManager.getBranch()].reverse().find(entry => entry.type === 'message' && entry.message.role === 'user');
+        turn = user?.id;
+        if (!user?.id) throw Error('checkpoint-turn-unavailable');
+        if (binding.run?.turnRef !== user.id) {
+          // Steering can add a user turn before the enclosing agent settles.
+          if (binding.run) await binding.service.finish(binding.run);
+          binding.run = { turnRef: user.id };
+        }
+        await binding.service.take(binding.run);
+      } catch (error) {
+        // Only a turn that already has its checkpoint may change files unrecorded.
+        if (!checkpointOwnershipError(error) && (!turn || binding.run?.turnRef !== turn || binding.run.checkpoint === undefined)) binding.service.markGap();
+        throw error;
+      }
+      if (!binding.active) throw Error('checkpoint-authority-changed');
+    });
+  }
+  finish(ctx: ExtensionContext) {
+    return this.#serial(async () => {
+      if (ctx.model?.provider === 'agent_watch_managed' || isCompanySession(ctx)) return;
+      const binding = this.#bindings.get(this.#key(ctx));
+      if (!binding) return;
+      if (!binding.active) throw Error('checkpoint-authority-changed');
+      binding.ctx = ctx;
+      if (binding.run) await binding.service.finish(binding.run);
+      binding.run = undefined;
+    });
+  }
+  undo(ctx: ExtensionContext) {
+    return this.#serial(async () => {
+      const binding = this.#binding(ctx);
+      // A failed settlement must be resolved before exposing the older stack.
+      if (ctx.isIdle() && binding.run) {
+        await binding.service.finish(binding.run);
+        binding.run = undefined;
+      }
+      return await binding.service.undo();
+    });
+  }
+  close(ctx: ExtensionContext) {
+    return this.#serial(async () => {
+      if (ctx.model?.provider === 'agent_watch_managed' || isCompanySession(ctx)) return;
+      const key = this.#key(ctx), binding = this.#bindings.get(key);
+      if (!binding) return;
+      binding.ctx = ctx;
+      try { if (binding.active && binding.run) await binding.service.finish(binding.run); }
+      finally {
+        try { await binding.service.close(); }
+        finally { binding.unbind(); this.#bindings.delete(key); }
+      }
+    });
+  }
+}

package/packages/piagent-core/runtime/checkpoints/prune.mjs

@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const STALE_MS = 30 * 24 * 60 * 60 * 1000;
+
+// Conversations nobody has touched for 30 days give up their checkpoints: the
+// state file goes, and with it the refs that kept their trees alive, so the
+// private store does not grow with every conversation ever held in a project.
+// A session holding its lock, and the caller's own session, are left alone.
+export function pruneStaleCheckpointSessions(directory, refs, keep, now = Date.now()) {
+  let names;
+  try { names = fs.readdirSync(directory); } catch { return 0; }
+  let pruned = 0;
+  for (const name of names) {
+    const key = /^([a-f0-9]{64})\.json$/.exec(name)?.[1];
+    if (!key || key === keep || names.includes(`${key}.lock`)) continue;
+    const file = path.join(directory, name);
+    try {
+      const stat = fs.lstatSync(file);
+      if (!stat.isFile() || now - stat.mtimeMs < STALE_MS) continue;
+      const prefix = `refs/piagent/checkpoints/${key}/`;
+      const lines = refs.run(['for-each-ref', '--format=%(refname) %(objectname)', prefix]).trim().split('\n').filter(Boolean)
+        .map(line => { const [ref, object] = line.split(' '); return `delete ${ref} ${object}`; });
+      if (lines.length) refs.run(['update-ref', '--stdin'], Buffer.from(['start', ...lines, 'prepare', 'commit', ''].join('\n')));
+      fs.unlinkSync(file); pruned++;
+    } catch { /* another process is using it; try again next time */ }
+  }
+  return pruned;
+}