@piagent/platform 1.37.1 → 1.38.1

package/packages/piagent-core/managed/tool-boundary.mjs

@@ -1,3 +1,9 @@
+import { consumeReviewSnapshot } from './review-snapshot-request.mjs';
+import { SessionMutationObservations } from "./session-mutation-observations.mjs";
+import { BoundaryTerminals } from './terminal-boundary.mjs';
+import { ToolFreshness } from './tool-freshness.mjs';
+import { BoundaryQueue } from './boundary-queue.mjs';
+import { workspaceWorkerPins, verifyWorkspaceWorker } from './workspace-worker-pins.mjs';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -11,10 +17,11 @@ import { languageEnvironment } from './language-environment.mjs';
 import { PI_HOST_VERSION, hostPackage } from './pi-host.mjs';
 export { PI_HOST_VERSION, hostPackage };
 import { containerEngine, dockerCli, engineEnvironment } from './container-engine.mjs';
-import { DEFAULT_DOMAINS, PackageProxy, mavenSettings, memberDomains, proxyEnvironment } from './package-proxy.mjs';
+import { proxyEnvironment } from './package-proxy.mjs';
+import { startBoundaryPackageProxy } from './boundary-package-proxy.mjs';
+import { SourceRevertRequests } from './source-revert-requests.mjs';
 import { BWRAP, bubblewrapArgs, credentialFiles, referenceFolders } from './linux-sandbox.mjs';
 import { agentWatchDataDirectory } from './store.mjs';
-
 const TOOL_NAMES = Object.freeze(['read', 'bash', 'edit', 'write', 'grep', 'find', 'ls']);
 const MAX_WIRE_BYTES = 12 * 1024 * 1024;
 const workerPath = fileURLToPath(new URL('./tool-worker.mjs', import.meta.url));
@@ -25,7 +32,6 @@ function literal(value) {
 }
 function inside(file, root) { return file === root || file.startsWith(root + path.sep); }
 const pattern = value => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-
 // Folders a member points the agent to for reference (an @ mention, "read
 // ~/Documents/old-shop"): their own files on this Mac, external drives and
 // the shared folder, read-only. Hidden entries of the home folder (shell
@@ -41,7 +47,6 @@ function referenceRules(home, roots) {
   return `(allow file-read* (subpath ${literal(home)}) (subpath "/Volumes") (subpath "/Users/Shared") (subpath "/private/tmp"))
 (deny file-read-data file-read-xattr (require-all (require-any (regex #"^${pattern(home)}/\\.") (subpath ${literal(path.join(home, 'Library'))}))${opened}))`;
 }
-
 export function managedSeatbelt({ cwd, sdkRoot, runtimeRoot, temporary, node, denied = [], readOnly = false, repository = [], gitDirs = [], toolchains = [], developer = [], browsers = [], network = false, references = null, skills = [], caches = [], loopback = true, license = null, docker = null, proxyPort = null }) {
   // Default-deny protects Keychain/SSH agent/Watch IPC and process inspection.
   // System libraries/toolchains are read-only. Writes stay in this project and
@@ -110,7 +115,6 @@ ${denied.map(root => `(deny file-read* file-write* (require-all (subpath ${liter
   (require-not (regex #"(^|/)\\.env\\.(example|sample|template|dist|defaults)$"))))
 `;
 }
-
 // Toolchains from the pinned node/git and Homebrew, compilers and SDK; the
 // git identity this project gets on the user's machine (name and email only)
 // so commits work. Without network, package managers fail fast instead of
@@ -192,7 +196,13 @@ function provisionSearchTools(home, userHome) {
 }
 
 export class ManagedToolBoundary {
-  #tail = Promise.resolve();
+  #queue = new BoundaryQueue();
+  #freshness = new ToolFreshness();
+  #sourceRequests = new SourceRevertRequests();
+  get sourceControlRevision() { return this.#sourceRequests.revision; }
+  source(request, binding) { return this.invoke("workspace", this.#sourceRequests.request(request, binding)); }
+  #mutationObservations = new SessionMutationObservations();
+  mutationObservation(file) { return this.#mutationObservations.get(file); }
   #children = new Set();
   #closed = false;
   // readOnly: the project cannot be written. commands: bash is offered all
@@ -205,10 +215,11 @@ export class ManagedToolBoundary {
     this.cwd = fs.realpathSync(cwd); this.sdkRoot = fs.realpathSync(sdkRoot);
     this.node = fs.realpathSync(node);
     this.runtimeRoot = fs.realpathSync(path.dirname(workerPath));
+    this.workspacePins = workspaceWorkerPins(this.runtimeRoot);
     this.sdkPath = path.join(this.sdkRoot, 'dist/index.js');
     this.git = managedGit();
     if (JSON.parse(fs.readFileSync(path.join(this.sdkRoot, 'package.json'), 'utf8')).version !== PI_HOST_VERSION) throw new Error('managed-sdk-version-unqualified');
-    const workerModules = ['search-fallback.mjs', 'sandbox-diagnostic.mjs', 'ts-diagnostics-server.mjs'].map(name => path.join(this.runtimeRoot, name));
+    const workerModules = ['review-snapshot-worker.mjs', 'tool-freshness.mjs', 'search-fallback.mjs', 'sandbox-diagnostic.mjs', 'ts-diagnostics-server.mjs', 'workspace-worker-pins.mjs'].map(name => path.join(this.runtimeRoot, name));
     this.pins = new Map([this.node, this.git, workerPath, ...workerModules, this.sdkPath].map(file => [file, hash(file)]));
     const userHome = fs.realpathSync(home ?? os.homedir());
     if ([userHome, '/', this.sdkRoot, this.runtimeRoot].includes(this.cwd)
@@ -260,6 +271,7 @@ export class ManagedToolBoundary {
     if (searchTools) provisionSearchTools(this.home, userHome);
     else fs.writeFileSync(path.join(this.home, '.ripgreprc'), '', { mode: 0o600 });
     this.allowed = readOnly ? TOOL_NAMES.filter(name => !['write', 'edit'].includes(name) && (name !== 'bash' || commands)) : [...TOOL_NAMES];
+    this.terminals = new BoundaryTerminals(this);
   }
   // What the machine offers commands: toolchains, the JDK, the Docker engine.
   // Looked up again after the member installs or starts something
@@ -288,6 +300,8 @@ export class ManagedToolBoundary {
     if (this.engine) this.environment.docker = { ...this.environment.network, ...engineEnvironment(this.engine, this.home) };
     this.#applyProxy();
   }
+  // A company terminal's shell (terminal-seatbelt.mjs): offline, its own temporary root.
+  terminalProfile(temporary) { return managedSeatbelt({ ...this.base, temporary, references: this.userHome, loopback: false }); }
   // Plain commands' profile and environment, with the package proxy once it listens.
   #applyProxy() {
     const port = this.proxyUrl && !this.linux ? Number(new URL(this.proxyUrl).port) : null;
@@ -313,34 +327,20 @@ export class ManagedToolBoundary {
     const factories = { read: api.createReadToolDefinition, write: api.createWriteToolDefinition,
       edit: api.createEditToolDefinition, bash: api.createBashToolDefinition,
       grep: api.createGrepToolDefinition, find: api.createFindToolDefinition, ls: api.createLsToolDefinition };
-    return this.allowed.map(name => ({ ...factories[name](this.cwd), execute: (_id, args, signal, onUpdate, context) => {
-      // One queue spans read and all mutations so two concurrent edit requests
-      // observe a deterministic order. Helpers use separate read-only workers.
-      const run = this.#tail.then(() => this.invoke(name, args, signal, onUpdate, context?.model));
-      this.#tail = run.catch(() => {}); return run;
-    } }));
+    return this.allowed.map(name => ({ ...factories[name](this.cwd), execute: (_id, args, signal, onUpdate, context) =>
+      this.invoke(name, args, signal, onUpdate, context?.model) }));
   }
   // The proxy listens on loopback (macOS: Seatbelt opens its one port even
   // while a local proxy closes the rest of loopback) or on a Unix socket that
   // the worker forwards from inside the command's network namespace (Linux).
-  async startProxy() {
-    this.proxy = new PackageProxy({ domains: [...DEFAULT_DOMAINS, ...memberDomains(this.userHome)] });
-    try {
-      let url;
-      if (this.linux) {
-        this.proxySocket = path.join(os.tmpdir(), `piagent-proxy-${randomUUID().slice(0, 8)}.sock`);
-        await this.proxy.listen(this.proxySocket);
-        url = 'http://127.0.0.1:3128';
-      } else url = `http://127.0.0.1:${(await this.proxy.listen()).port}`;
-      const settings = path.join(this.home, '.m2/settings.xml');
-      fs.mkdirSync(path.dirname(settings), { recursive: true, mode: 0o700 }); fs.writeFileSync(settings, mavenSettings(url), { mode: 0o600 });
-      this.proxyUrl = url; this.#applyProxy();
-    } catch { await this.proxy.close().catch(() => {}); this.proxy = null; }
+  startProxy() { return startBoundaryPackageProxy(this, () => this.#applyProxy()); }
+  invoke(name, args, signal, onUpdate, model, options = {}) {
+    return this.#queue.run(name, args, () => this.#queuedInvoke(name, args, signal, onUpdate, model, options));
   }
-  async invoke(name, args, signal, onUpdate, model, { network = false, docker = false } = {}) {
+  async #queuedInvoke(name, args, signal, onUpdate, model, { network = false, docker = false, guard = undefined } = {}) {
     await this.proxyReady;
     const before = this.proxy?.deniedCount ?? 0;
-    try { return await this.#invoke(name, args, signal, onUpdate, model, { network, docker }); }
+    try { guard?.(); return await this.#invoke(name, args, signal, onUpdate, model, { network, docker, guard }); }
     catch (error) {
       // A command that failed after the proxy refused a host: name the hosts.
       const refused = !network && !docker && this.proxy ? this.proxy.deniedSince(before) : [];
@@ -348,10 +348,11 @@ export class ManagedToolBoundary {
       throw new Error(`managed-domain-blocked: Lệnh thường chỉ tải được từ các registry package quen thuộc (npm, PyPI, Go, crates.io, Maven, Gradle, NuGet, RubyGems, Packagist, pub.dev…) và tải về public từ GitHub. Host bị chặn: ${refused.join(', ')}. Nếu lệnh thật sự cần host này, dùng run_with_network để người dùng duyệt đúng lệnh đó.\n${String(error?.message ?? error)}`);
     }
   }
-  async #invoke(name, args, signal, onUpdate, model, { network = false, docker = false } = {}) {
+  async #invoke(name, args, signal, onUpdate, model, { network = false, docker = false, guard = undefined } = {}) {
     if (docker && !this.engine) throw new Error('managed-tool-unavailable');
     network ||= docker;
-    if (this.#closed || !this.allowed.includes(name) || network && (name !== 'bash' || !this.networkAllowed)) throw new Error('managed-tool-unavailable');
+    if (name === 'workspace') { if (network || docker) throw Error('managed-tool-unavailable'); verifyWorkspaceWorker(this.workspacePins); }
+    if (this.#closed || (name !== 'workspace' && !this.allowed.includes(name)) || network && (name !== 'bash' || !this.networkAllowed)) throw new Error('managed-tool-unavailable');
     if (signal?.aborted) throw new Error('managed-tool-cancelled');
     for (const [file, digest] of this.pins) if (hash(file) !== digest) throw new Error('managed-runtime-changed');
     // `~` (as in an @~/… mention) is the member's home folder: the sandbox's
@@ -359,9 +360,15 @@ export class ManagedToolBoundary {
     if (name !== 'bash' && typeof args?.path === 'string' && /^@?~(\/|$)/.test(args.path)) args = { ...args, path: this.userHome + args.path.replace(/^@?~/, '') };
     if (!this.linux && !network && Date.now() - this.proxyCheck.at > 5000) this.proxyCheck = { at: Date.now(), listening: localProxyListening(this.proxyPorts) };
     const isolated = !this.linux && !network && await this.proxyCheck.listening;
-    const message = JSON.stringify({ name, args, ...(network ? { network: true } : {}), ...(isolated ? { isolated: true } : {}), ...(docker ? { docker: true } : this.engine ? { engine: true } : {}), model: model ? { input: model.input, inputLimits: model.inputLimits } : undefined }) + '\n';
+    const observing = ['edit', 'write'].includes(name) && this.workspacePins;
+    if (observing) verifyWorkspaceWorker(this.workspacePins);
+    const snapshotRead = name === 'bash' && consumeReviewSnapshot(args);
+    const mutationObservation = snapshotRead ? undefined : this.#mutationObservations.prepare(this.cwd, name, args, observing);
+    const sourceContext = this.#sourceRequests.consume(args, this.#mutationObservations);
+    const message = JSON.stringify({ name, args, sourceContext, mutationObservation, expectedFileDigest: this.#freshness.expected(this.cwd, name, args), workspaceReadOnly: this.setup.readOnly, ...(network ? { network: true } : {}), ...(isolated ? { isolated: true } : {}), ...(docker ? { docker: true } : this.engine ? { engine: true } : {}), model: model ? { input: model.input, inputLimits: model.inputLimits } : undefined }) + '\n';
     if (Buffer.byteLength(message) > MAX_WIRE_BYTES) throw new Error('managed-tool-input-too-large');
     return await new Promise((resolve, reject) => {
+      guard?.();
       const [sandbox, sandboxArgs] = this.linux ? [BWRAP, this.bubblewrap(network, docker)]
         : ['/usr/bin/sandbox-exec', ['-p', docker ? this.dockerProfile : network ? this.networkProfile : isolated ? this.isolatedProfile : this.profile]];
       const child = spawn(sandbox, [...sandboxArgs, this.node, workerPath, this.sdkPath, this.cwd], {
@@ -370,7 +377,7 @@ export class ManagedToolBoundary {
       });
       this.#children.add(child);
       const decoder = new StringDecoder('utf8');
-      let pending = '', bytes = 0, result, failure, terminated = false, hardStop;
+      let pending = '', bytes = 0, result, freshness, observation, sourceObservation, failure, terminated = false, hardStop;
       const terminate = () => {
         if (terminated) return; terminated = true;
         child.stdin.write('{"cancel":true}\n');
@@ -405,7 +412,7 @@ export class ManagedToolBoundary {
             // A cancel or timeout asked for first stays the reason: the worker
             // then reports how its command ended ("Command aborted").
             else if (value.error) failure ??= new Error(String(value.error).slice(0, 1000));
-            else if (value.result) result = value.result;
+            else if (value.result) { result = value.result; freshness = value.freshness; observation = value.mutationObservation; sourceObservation = value.sourceObservation; }
             else throw new Error('managed-worker-invalid-response');
           } catch { failure = new Error('managed-worker-invalid-response'); terminate(); }
         }
@@ -419,7 +426,9 @@ export class ManagedToolBoundary {
         this.#children.delete(child); signal?.removeEventListener('abort', abort);
         if (failure) reject(failure);
         else if (code !== 0 || !result || pending) reject(new Error('managed-worker-failed'));
-        else resolve(result);
+        else { this.#freshness.observe(this.cwd, name, args, freshness);
+          this.#mutationObservations.acceptRevert(args, sourceContext, result, sourceObservation);
+          this.#mutationObservations.accept(this.cwd, name, args, mutationObservation, observation); resolve(result); }
       });
       child.stdin.write(message);
       if (signal?.aborted) abort();
@@ -462,8 +471,9 @@ export class ManagedToolBoundary {
   async dispose() {
     this.#closed = true;
     const stopping = [...this.#children].map(child => new Promise(resolve => { child.once('close', resolve); child.managedCancel(); }));
-    await Promise.all(stopping); await this.#tail;
+    await Promise.all([this.terminals.dispose(), ...stopping]); await this.#queue.idle();
     await this.background?.dispose(); await this.stopStrays(); if (!this.linux) await stopMarked(`PIAGENT_PROCESS_SCOPE=${this.scope}:`);
+    this.#mutationObservations.clear();
     await this.proxyReady; await this.proxy?.close().catch(() => {});
     if (this.proxySocket) fs.rmSync(this.proxySocket, { force: true });
     fs.rmSync(this.temporary, { recursive: true, force: true });

package/packages/piagent-core/managed/tool-freshness.mjs

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+const LIMIT = 20 * 1024 * 1024;
+export function freshnessPath(cwd, name, args) {
+  if (!['read', 'edit', 'write'].includes(name) || typeof args?.path !== 'string') return null;
+  const relative = path.relative(cwd, path.resolve(cwd, args.path));
+  return relative && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative) ? relative : null;
+}
+// Called only inside the sandbox. The parent stores opaque digests and never
+// opens a company project file to decide whether an edit is fresh.
+export function fileDigest(cwd, relative) {
+  if (!relative) return null;
+  let descriptor;
+  try {
+    const file = path.resolve(cwd, relative), real = fs.realpathSync(file);
+    if (real !== file) return null;
+    descriptor = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile() || stat.size > LIMIT) return null;
+    const bytes = Buffer.alloc(stat.size + 1), length = fs.readSync(descriptor, bytes, 0, bytes.length, 0), after = fs.fstatSync(descriptor);
+    if (length !== stat.size || after.size !== stat.size || after.mtimeMs !== stat.mtimeMs || after.ctimeMs !== stat.ctimeMs) return null;
+    return createHash('sha256').update(bytes.subarray(0, length)).digest('hex');
+  } catch (error) { return error?.code === 'ENOENT' ? 'absent' : null; }
+  finally { if (descriptor !== undefined) fs.closeSync(descriptor); }
+}
+export function beginToolFreshness(cwd, name, args, expected) {
+  const relative = freshnessPath(cwd, name, args), before = fileDigest(cwd, relative);
+  if (relative && ['edit', 'write'].includes(name) && expected !== undefined && before !== expected)
+    throw new Error(`stale-content: ${relative} changed since the last read. Read its current contents before editing.`);
+  return () => {
+    const digest = fileDigest(cwd, relative);
+    if (name === 'read' && relative && before !== digest) throw new Error(`stale-content: ${relative} changed during the read. Read it again.`);
+    return relative && digest ? { path: relative, digest } : null;
+  };
+}
+export class ToolFreshness {
+  #observed = new Map();
+  expected(cwd, name, args) { return this.#observed.get(freshnessPath(cwd, name, args)); }
+  observe(cwd, name, args, value) {
+    const relative = freshnessPath(cwd, name, args);
+    if (!relative || value?.path !== relative || !/^(absent|[a-f0-9]{64})$/.test(value?.digest ?? '')) return;
+    this.#observed.delete(relative); this.#observed.set(relative, value.digest);
+    while (this.#observed.size > 256) this.#observed.delete(this.#observed.keys().next().value);
+  }
+}

package/packages/piagent-core/managed/tool-worker.mjs

@@ -1,9 +1,10 @@
+import { beginToolFreshness } from './tool-freshness.mjs';
 import { sandboxDiagnostic } from './sandbox-diagnostic.mjs';
 import { fallbackFind, fallbackGrep } from './search-fallback.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 // A dedicated, credential-free process already inside Seatbelt. The launch
 // profile and environment are supplied by the trusted runtime, never the LLM.
 const [sdkPath, cwd] = process.argv.slice(2);
@@ -33,8 +34,22 @@ input.on('line', async line => {
   try {
     const message = JSON.parse(line);
     if (message.cancel === true) { controller?.abort(); return; }
-    if (active || !Object.hasOwn(factories, message.name)) throw new Error('managed-worker-request-invalid');
+    if (active || (message.name !== 'workspace' && !Object.hasOwn(factories, message.name))) throw new Error('managed-worker-request-invalid');
     active = true; controller = new AbortController(); network = message.network === true; isolated = message.isolated === true; docker = message.docker === true; engine = message.engine === true;
+    if (message.name === 'workspace') {
+      const { inspectManagedWorkspace, inspectManagedSource } = await import('./dist/workspace/worker.mjs');
+      const assets = fileURLToPath(new URL('./dist/workspace/assets/', import.meta.url));
+      emit(message.args?.kind === 'source'
+        ? await inspectManagedSource(cwd, assets, message.args.request, message.sourceContext, message.workspaceReadOnly === true)
+        : { result: await inspectManagedWorkspace(cwd, assets, message.args, message.workspaceReadOnly === true) }); return;
+    }
+    let finishObservation = () => null;
+    if (message.mutationObservation && ['edit', 'write'].includes(message.name)) {
+      const { beginManagedMutationObservation } = await import('./dist/workspace/worker.mjs');
+      finishObservation = beginManagedMutationObservation(cwd, fileURLToPath(new URL('./dist/workspace/assets/', import.meta.url)),
+        { ...message.mutationObservation, toolName: message.name, args: message.args }, message.workspaceReadOnly === true);
+    }
+    const finishFreshness = beginToolFreshness(cwd, message.name, message.args, message.expectedFileDigest);
     const options = message.name === 'bash' ? { shellPath: '/bin/bash', exposeSessionEnvironment: false } : undefined;
     // The runtime copies ripgrep/fd here when the machine has or can fetch them.
     const provided = name => fs.existsSync(path.join(process.env.HOME ?? '', '.pi/agent/bin', name));
@@ -46,7 +61,7 @@ input.on('line', async line => {
     // failures. Pi 0.87 throws on denial and on a non-zero shell exit; Pi 1.x
     // returns an isError result with the same text instead: read as the throw.
     if (result?.isError === true) throw new Error((result.content ?? []).filter(part => part.type === 'text').map(part => part.text).join('\n') || 'managed-worker-failed');
-    emit({ result });
+    emit({ result, freshness: finishFreshness(), mutationObservation: finishObservation() });
   } catch (error) { emit({ error: sandboxDiagnostic(error instanceof Error ? error.message : 'managed-worker-failed', { network, isolated, docker, engine }) }); }
   finally { if (active) { input.close(); process.stdin.destroy(); } }
 });

package/packages/piagent-core/managed/workspace-worker-pins.mjs

@@ -0,0 +1,26 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+const digest = file => createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+
+export function workspaceWorkerPins(runtimeRoot) {
+  const root = path.join(runtimeRoot, 'dist/workspace'), manifest = path.join(root, 'manifest.json');
+  if (!fs.existsSync(manifest)) return null;
+  const source = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+  if (source.version !== 1 || !Array.isArray(source.files) || source.files.length > 200) throw Error('workspace-worker-invalid');
+  const pins = new Map([[manifest, digest(manifest)]]);
+  for (const item of source.files) {
+    if (typeof item.file !== 'string' || !/^[a-zA-Z0-9_./-]+$/.test(item.file)
+      || item.file.split('/').some(part => !part || part === '.' || part === '..') || !/^[a-f0-9]{64}$/.test(item.sha256)) throw Error('workspace-worker-invalid');
+    const file = path.join(root, item.file);
+    if (fs.realpathSync(file) !== file || !fs.statSync(file).isFile() || digest(file) !== item.sha256) throw Error('workspace-worker-invalid');
+    pins.set(file, item.sha256);
+  }
+  if (!pins.has(path.join(root, 'worker.mjs'))) throw Error('workspace-worker-invalid');
+  return pins;
+}
+
+export function verifyWorkspaceWorker(pins) {
+  if (!pins) throw Error('workspace-worker-unavailable');
+  for (const [file, expected] of pins) if (digest(file) !== expected) throw Error('managed-runtime-changed');
+}

package/packages/piagent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/core",
-  "version": "1.37.1",
+  "version": "1.38.1",
   "type": "module",
   "private": true,
   "license": "MIT",

package/packages/piagent-core/policies/base-policy.json

@@ -93,7 +93,8 @@
     "allowedModes": [
       "read-only",
       "workspace-write",
-      "trusted-full-access"
+      "trusted-full-access",
+      "bypass"
     ]
   },
   "execPolicy": {

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