@piagent/platform 1.37.0 → 1.38.1

package/packages/piagent-core/managed/terminal-channel.mjs

@@ -0,0 +1,66 @@
+import { StringDecoder } from 'node:string_decoder';
+import { stopProcessGroup } from './background-process.mjs';
+
+// Native effects are acknowledged once. A lost response rejects as uncertain;
+// the Gateway command ledger owns retries and must never redispatch the effect.
+export function terminalChannel(child, emit) {
+  const requests = new Map(), decoder = new StringDecoder('utf8');
+  let pending = '', next = 0, ready = false, closed = false, closing, exited = false;
+  let resolveReady, rejectReady, resolveClosed;
+  const initialized = new Promise((resolve, reject) => { resolveReady = resolve; rejectReady = reject; });
+  const completed = new Promise(resolve => { resolveClosed = resolve; });
+  const timer = setTimeout(() => fail('managed-terminal-start-timeout'), 10000);
+  const notify = message => { try { emit(message); } catch { /* consumer never owns process lifetime */ } };
+  const rejectAll = reason => {
+    rejectReady(new Error(reason));
+    for (const request of requests.values()) { clearTimeout(request.timer); request.reject(new Error(reason)); }
+    requests.clear();
+  };
+  const close = () => closing ??= (async () => {
+    if (closed) return;
+    rejectAll('managed-terminal-effect-uncertain');
+    await stopProcessGroup(child);
+    let timeout;
+    try { await Promise.race([completed, new Promise((_, reject) => { timeout = setTimeout(() => reject(Error('managed-terminal-cleanup-unconfirmed')), 3000); })]); }
+    finally { clearTimeout(timeout); }
+  })();
+  const fail = reason => { rejectAll(reason); void close().catch(() => {}); };
+  child.once('error', () => fail('managed-terminal-sandbox-unavailable'));
+  child.once('close', () => {
+    closed = true; clearTimeout(timer); rejectAll('managed-terminal-effect-uncertain');
+    if (!exited) notify({ kind: 'exit', exitCode: null, signal: null });
+    resolveClosed();
+  });
+  child.stdin.on('error', () => fail('managed-terminal-effect-uncertain'));
+  child.stderr.resume(); // Sandbox startup errors are reported by code, not raw host paths.
+  child.stdout.on('data', chunk => {
+    pending += decoder.write(chunk);
+    if (Buffer.byteLength(pending) > 128 * 1024) return fail('managed-terminal-protocol-invalid');
+    for (;;) {
+      const end = pending.indexOf('\n'); if (end < 0) break;
+      const line = pending.slice(0, end); pending = pending.slice(end + 1);
+      try {
+        const value = JSON.parse(line), keys = Object.keys(value).sort().join(',');
+        if (value.kind === 'ready' && keys === 'kind' && !ready) { ready = true; clearTimeout(timer); resolveReady(); }
+        else if (value.kind === 'unavailable' && !ready) fail('managed-terminal-sandbox-unavailable');
+        else if (ready && value.kind === 'ack' && keys === 'id,kind' && requests.has(value.id)) {
+          const request = requests.get(value.id); clearTimeout(request.timer); requests.delete(value.id); request.resolve();
+        } else if (ready && value.kind === 'output' && keys === 'data,kind' && typeof value.data === 'string' && value.data.length <= 8192) notify(value);
+        else if (ready && value.kind === 'exit' && keys === 'exitCode,kind,signal' && (value.exitCode === null || Number.isInteger(value.exitCode))
+          && (value.signal === null || Number.isInteger(value.signal)) && !exited) { exited = true; notify(value); }
+        else throw Error();
+      } catch { return fail('managed-terminal-protocol-invalid'); }
+    }
+  });
+  return { initialized, completed, close, execute(payload) {
+    if (!ready || closed || closing || exited) return Promise.reject(Error('managed-terminal-exited'));
+    if (requests.size >= 128 || child.stdin.writableLength > 128 * 1024) return Promise.reject(Error('managed-terminal-capacity'));
+    const id = String(++next), line = JSON.stringify({ ...payload, id }) + '\n';
+    if (Buffer.byteLength(line) > 128 * 1024) return Promise.reject(Error('managed-terminal-input-limit'));
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { requests.delete(id); reject(Error('managed-terminal-effect-uncertain')); void close().catch(() => {}); }, 10000);
+      requests.set(id, { resolve, reject, timer });
+      child.stdin.write(line, error => { if (error) fail('managed-terminal-effect-uncertain'); });
+    });
+  } };
+}

package/packages/piagent-core/managed/terminal-runtime.mjs

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { createHash } from 'node:crypto';
+import { BWRAP } from './linux-sandbox.mjs';
+
+const require = createRequire(import.meta.url);
+const VERSION = '1.2.0-beta.15';
+const fail = () => { throw new Error('managed-terminal-runtime-invalid'); };
+
+// Inspect code without loading the native addon. The entire platform package
+// is pinned, including its JS and prebuilt binary. Linux loads it inside the
+// sandbox; macOS loads it on the company Gateway to make the PTY there (the
+// shell itself runs under Seatbelt, terminal-boundary.mjs).
+function inventory(root) {
+  const entries = [], queue = [root];
+  let bytes = 0, visited = 0;
+  while (queue.length) {
+    const directory = queue.shift();
+    if (!fs.lstatSync(directory).isDirectory() || fs.realpathSync(directory) !== directory) fail();
+    for (const name of fs.readdirSync(directory).sort()) {
+      if (++visited > 128) fail();
+      const file = path.join(directory, name), stat = fs.lstatSync(file);
+      if (stat.isSymbolicLink()) fail();
+      if (stat.isDirectory()) { queue.push(file); continue; }
+      if (!stat.isFile() || stat.size > 16 * 1024 * 1024 || (bytes += stat.size) > 32 * 1024 * 1024) fail();
+      const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+      try {
+        const opened = fs.fstatSync(fd);
+        if (!opened.isFile() || opened.dev !== stat.dev || opened.ino !== stat.ino || opened.size !== stat.size) fail();
+        const digest = createHash('sha256').update(fs.readFileSync(fd)).digest('hex');
+        entries.push([path.relative(root, file), digest, opened.mode & 0o777]);
+      } finally { fs.closeSync(fd); }
+    }
+  }
+  return JSON.stringify(entries.sort((a, b) => a[0].localeCompare(b[0])));
+}
+
+export function companyTerminalRuntime({ platform = process.platform, arch = process.arch,
+  bubblewrap = BWRAP, resolve = specifier => createRequire(require.resolve('@lydell/node-pty')).resolve(specifier) } = {}) {
+  if (!['linux', 'darwin'].includes(platform)) throw new Error('managed-terminal-platform-unavailable');
+  if (platform === 'linux' && !bubblewrap) throw new Error('managed-terminal-bubblewrap-unavailable');
+  if (!['arm64', 'x64'].includes(arch)) throw new Error('managed-terminal-platform-unavailable');
+  const name = `@lydell/node-pty-${platform}-${arch}`;
+  let entry;
+  try { entry = fs.realpathSync(resolve(name)); }
+  catch { throw new Error('managed-terminal-native-unavailable'); }
+  const root = path.dirname(path.dirname(entry));
+  if (entry !== path.join(root, 'lib/index.js')) fail();
+  const pinned = inventory(root);
+  const manifest = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+  if (manifest.name !== name || manifest.version !== VERSION || manifest.dependencies && Object.keys(manifest.dependencies).length) fail();
+  if (!fs.statSync(path.join(root, `prebuilds/${platform}-${arch}/pty.node`)).isFile()) fail();
+  return Object.freeze({ entry, root, version: VERSION,
+    assertCurrent() { if (inventory(root) !== pinned) throw new Error('managed-terminal-runtime-changed'); } });
+}
+
+export function companyTerminalDiagnostic(options = {}) {
+  let reasonCode = null;
+  try { companyTerminalRuntime(options); }
+  catch (error) { reasonCode = /^managed-terminal-/.test(error.message) ? error.message : 'managed-terminal-runtime-invalid'; }
+  return { supported: reasonCode === null, reasonCode, platform: options.platform ?? process.platform,
+    scope: 'company', probe: 'runtime-files', ptySpawnVerified: false };
+}

package/packages/piagent-core/managed/terminal-seatbelt.mjs

@@ -0,0 +1,48 @@
+import { createRequire } from 'node:module';
+import { stopProcessGroup } from './background-process.mjs';
+import { ProcessTreeWatch } from '../runtime/process-tree-watch.mjs';
+
+const watch = new ProcessTreeWatch();
+
+// macOS: Seatbelt denies creating a PTY, so the company Gateway makes it and
+// only the shell runs sandboxed, under the agent's offline profile plus these
+// rules: ioctls on terminal devices (only the one this shell was handed can be
+// reached, since opening any other stays denied) and /dev/tty, which always
+// names the process's own terminal.
+export const SEATBELT_TERMINAL_RULES = `
+(allow file-ioctl (regex #"^/dev/ttys[0-9]+$"))
+(allow file-read* file-write* file-ioctl (literal "/dev/tty"))
+`;
+
+export function seatbeltTerminal({ entry, profile, cwd, env, size, emit }) {
+  const pty = createRequire(import.meta.url)(entry);
+  const child = pty.spawn('/usr/bin/sandbox-exec', ['-p', profile, '/bin/bash', '--noprofile', '--norc'],
+    { cwd, env, cols: size.cols, rows: size.rows, name: 'xterm-256color' });
+  watch.watch(child.pid);
+  const notify = message => { try { emit(message); } catch { /* consumer never owns process lifetime */ } };
+  let exited = false, closing, resolveClosed;
+  const completed = new Promise(resolve => { resolveClosed = resolve; });
+  child.onData(text => {
+    for (let start = 0; start < text.length;) {
+      let end = Math.min(start + 8192, text.length);
+      if (end < text.length && /[\uD800-\uDBFF]/.test(text[end - 1])) end--;
+      notify({ kind: 'output', data: text.slice(start, end) }); start = end;
+    }
+  });
+  child.onExit(({ exitCode, signal }) => {
+    exited = true; notify({ kind: 'exit', exitCode, signal: signal || null });
+    void watch.stop(child.pid).finally(resolveClosed);
+  });
+  const close = () => closing ??= (async () => {
+    if (exited) return;
+    await stopProcessGroup({ pid: child.pid, exitCode: null, signalCode: null });
+    let timeout;
+    try { await Promise.race([completed, new Promise((_, reject) => { timeout = setTimeout(() => reject(Error('managed-terminal-cleanup-unconfirmed')), 3000); })]); }
+    finally { clearTimeout(timeout); }
+  })();
+  return { initialized: Promise.resolve(), completed, close, execute(payload) {
+    if (exited || closing) return Promise.reject(Error('managed-terminal-exited'));
+    if (payload.kind === 'input') child.write(payload.data); else child.resize(payload.cols, payload.rows);
+    return Promise.resolve();
+  } };
+}

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

@@ -0,0 +1,70 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { StringDecoder } from 'node:string_decoder';
+
+// Only the boundary launches this entrypoint. Check both namespaces before
+// loading native code: accidentally invoking it on the host must fail closed.
+const [entry, hostPidNamespace, hostNetworkNamespace, columns, rows] = process.argv.slice(2);
+const size = (cols, rows) => Number.isInteger(cols) && cols >= 2 && cols <= 500 && Number.isInteger(rows) && rows >= 1 && rows <= 200;
+const send = message => {
+  if (process.stdout.writableLength > 512 * 1024) process.exit(1);
+  process.stdout.write(JSON.stringify(message) + '\n');
+};
+let terminal;
+try {
+  if (process.platform !== 'linux' || !/^pid:\[\d+\]$/.test(hostPidNamespace ?? '') || !/^net:\[\d+\]$/.test(hostNetworkNamespace ?? '')
+    || fs.readlinkSync('/proc/self/ns/pid') === hostPidNamespace || fs.readlinkSync('/proc/self/ns/net') === hostNetworkNamespace
+    || !size(Number(columns), Number(rows))) throw Error('sandbox-required');
+  const pty = createRequire(import.meta.url)(entry);
+  terminal = pty.spawn('/bin/bash', ['--noprofile', '--norc'], { cols: Number(columns), rows: Number(rows),
+    cwd: process.cwd(), env: { ...process.env, TERM: 'xterm-256color' }, name: 'xterm-256color' });
+} catch {
+  process.stdout.write(JSON.stringify({ kind: 'unavailable', reasonCode: 'managed-terminal-sandbox-unavailable' }) + '\n', () => process.exit(1));
+}
+if (terminal) {
+  let ending = false;
+  const finish = message => {
+    if (ending) return;
+    ending = true;
+    // Exiting the namespace's main process also stops detached shell children.
+    const timer = setTimeout(() => process.exit(0), 1000); timer.unref();
+    process.stdout.write(JSON.stringify(message) + '\n', () => process.exit(0));
+  };
+  // A writer faster than the Gateway reads (`yes`) waits on the terminal, as
+  // on a real one, instead of growing this pipe until the worker gives up.
+  let paused = false;
+  process.stdout.on('drain', () => { if (paused && !ending) { paused = false; terminal.resume(); } });
+  terminal.onData(text => {
+    for (let start = 0; start < text.length;) {
+      let end = Math.min(start + 8192, text.length);
+      if (end < text.length && /[\uD800-\uDBFF]/.test(text[end - 1])) end--;
+      send({ kind: 'output', data: text.slice(start, end) }); start = end;
+    }
+    if (!paused && process.stdout.writableLength > 128 * 1024) { paused = true; terminal.pause(); }
+  });
+  terminal.onExit(({ exitCode, signal }) => finish({ kind: 'exit', exitCode, signal: signal ?? null }));
+  send({ kind: 'ready' });
+  let pending = '';
+  const decoder = new StringDecoder('utf8');
+  process.stdin.on('data', chunk => {
+    pending += decoder.write(chunk);
+    if (Buffer.byteLength(pending) > 128 * 1024) return process.exit(1);
+    for (;;) {
+      const end = pending.indexOf('\n'); if (end < 0) break;
+      const line = pending.slice(0, end); pending = pending.slice(end + 1);
+      try {
+        const request = JSON.parse(line);
+        if (!request || typeof request !== 'object' || !/^[0-9]{1,16}$/.test(request.id) || ending) throw Error();
+        const keys = Object.keys(request).sort().join(',');
+        if (request.kind === 'input' && keys === 'data,id,kind' && typeof request.data === 'string' && Buffer.byteLength(request.data) <= 16384)
+          terminal.write(request.data);
+        else if (request.kind === 'resize' && keys === 'cols,id,kind,rows' && size(request.cols, request.rows)) terminal.resize(request.cols, request.rows);
+        else throw Error();
+        send({ kind: 'ack', id: request.id });
+      } catch { return process.exit(1); }
+    }
+  });
+  process.stdin.on('end', () => finish({ kind: 'exit', exitCode: null, signal: null }));
+  process.stdin.on('error', () => process.exit(1));
+  process.stdout.on('error', () => process.exit(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/web-fetch.mjs

@@ -2,6 +2,9 @@ import dns from 'node:dns/promises';
 import https from 'node:https';
 import net from 'node:net';
 import zlib from 'node:zlib';
+import { privateAddress } from './ip-policy.mjs';
+
+export { privateAddress };
 
 // Reads one public https page for the company session, from the runtime
 // process (tools in the sandbox have no network). GET only, no cookies or
@@ -11,20 +14,6 @@ const MAX_BYTES = 5 * 1024 * 1024;
 const MAX_REDIRECTS = 5;
 const TEXT = /^(text\/|application\/(json|xml|xhtml\+xml|javascript|x-yaml|yaml|ld\+json|rss\+xml|atom\+xml))/i;
 
-function v4Private(address) {
-  const [a, b] = address.split('.').map(Number);
-  return a === 0 || a === 10 || a === 127 || a >= 224 || (a === 100 && b >= 64 && b <= 127) || (a === 169 && b === 254)
-    || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 192 && b === 0) || (a === 198 && (b === 18 || b === 19));
-}
-export function privateAddress(address) {
-  if (net.isIPv4(address)) return v4Private(address);
-  if (!net.isIPv6(address)) return true;
-  const value = address.toLowerCase();
-  const mapped = value.match(/^(?:0*:)*:ffff:(\d+\.\d+\.\d+\.\d+)$/) ?? value.match(/^64:ff9b::(\d+\.\d+\.\d+\.\d+)$/);
-  if (mapped) return v4Private(mapped[1]);
-  return value === '::' || value === '::1' || /^f[cd]/.test(value) || /^fe[89ab]/.test(value) || /^ff/.test(value) || value.startsWith('2001:db8');
-}
-
 async function publicTarget(url, resolve) {
   if (url.protocol !== 'https:' || url.username || url.password) throw new Error('web-fetch-url-not-allowed');
   const host = url.hostname.replace(/^\[|\]$/g, '');

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.0",
+  "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": {