@piagent/platform 1.24.0 → 1.26.0

package/packages/piagent-core/managed/repository-operation.mjs

@@ -16,28 +16,50 @@ export function githubRemote(value) {
   return {repository:`${match[1]}/${match[2]}`,url:`https://github.com/${match[1]}/${match[2]}.git`};
 }
 
-export async function repositoryFetchPlan(boundary) {
-  const result=await boundary.invoke('bash',{command:'git config --local --get remote.origin.url',timeout:5});
-  const remote=githubRemote(text(result));
-  return Object.freeze({...remote,cwd:boundary.cwd});
+// The repository is the conversation folder, or a folder inside it (a
+// workspace folder holding several repositories).
+export function repositoryFolder(cwd, folder) {
+  if (folder === undefined || folder === null || folder === '' || folder === '.') return cwd;
+  if (typeof folder !== 'string' || path.isAbsolute(folder) || folder.length > 500) throw Error('managed-repository-path-invalid: path is a folder inside the conversation folder, such as "api".');
+  const dir = path.resolve(cwd, folder);
+  let real;
+  try { real = fs.realpathSync(dir); } catch { throw Error(`managed-repository-not-found: ${folder} does not exist.`); }
+  const top = fs.realpathSync(cwd);
+  if (real !== top && !real.startsWith(top + path.sep)) throw Error('managed-repository-path-invalid: path is a folder inside the conversation folder.');
+  return real;
 }
 
-function command(binary,args,{cwd,env,signal,secret='',limit=1024*1024}={}) {
+export async function repositoryFetchPlan(boundary, folder) {
+  const cwd=repositoryFolder(boundary.cwd,folder);
+  let url='';
+  try { url=text(await boundary.invoke('bash',{command:`git -C ${quote(cwd)} config --local --get remote.origin.url`,timeout:5})); } catch { url=''; }
+  if (!url || /^fatal:|Command exited with code/m.test(url)) throw Error(cwd===boundary.cwd
+    ? 'managed-repository-not-found: the conversation folder is not a Git repository. Pass path: the repository folder inside it, such as "api".'
+    : `managed-repository-not-found: ${folder} is not a Git repository with an origin remote.`);
+  return Object.freeze({...githubRemote(url),cwd});
+}
+
+// Git's own error stays out of model context; the way on does not.
+const FETCH_FAILED='managed-repository-fetch-failed: fetch_origin không tải được nhánh từ GitHub (repo cần quyền mà tài khoản gh trên máy không có, gh chưa đăng nhập, mạng lỗi hoặc tải quá lâu). Dùng run_on_host để member duyệt chạy git fetch trên máy bằng tài khoản của họ (ví dụ git -C <thư mục repo> fetch origin <nhánh>).';
+function command(binary,args,{cwd,env,signal,secret='',limit=1024*1024,timeoutMs=60000}={}) {
   return new Promise((resolve,reject)=>{
     if(signal?.aborted) return reject(Error('managed-operation-cancelled'));
     const child=spawn(binary,args,{cwd,env,stdio:['ignore','pipe','pipe']});let output='',size=0,failed=false;
     const abort=()=>{failed=true;child.kill('SIGKILL')};signal?.addEventListener('abort',abort,{once:true});
-    const timer=setTimeout(abort,60000);timer.unref();
+    const timer=setTimeout(abort,timeoutMs);timer.unref();
     child.stdout.on('data',chunk=>{size+=chunk.length;if(size>limit)abort();else output+=chunk});
     // Credential helpers and Git diagnostics are never relayed to model context.
     child.stderr.on('data',()=>{});child.on('error',()=>{failed=true});
     child.on('close',code=>{clearTimeout(timer);signal?.removeEventListener('abort',abort);
-      if(failed||code!==0) reject(Error(signal?.aborted?'managed-operation-cancelled':'managed-repository-fetch-failed'));
+      if(failed||code!==0) reject(Error(signal?.aborted?'managed-operation-cancelled':FETCH_FAILED));
       else resolve(secret?output.replaceAll(secret,'[REDACTED]'):output);
     });
   });
 }
 
+// Every branch of a repository with many (a team's 90 branches took two
+// minutes): ten minutes, as long as a command may run.
+const FETCH_MS=10*60*1000;
 export async function fetchRepositoryBundle(plan, destination, signal) {
   // This private process sees only fixed arguments and an empty bare repo. It
   // never executes a command, hook, helper, filter or config from the project.
@@ -60,7 +82,7 @@ export async function fetchRepositoryBundle(plan, destination, signal) {
     await command(git,['init','--bare','--quiet',temporary],{cwd:temporary,env,signal});
     if(hash(git)!==gitHash)throw Error('managed-runtime-changed');
     const authentication=token?{GIT_CONFIG_COUNT:'1',GIT_CONFIG_KEY_0:'http.https://github.com/.extraheader',GIT_CONFIG_VALUE_0:'Authorization: Basic '+Buffer.from('x-access-token:'+token).toString('base64')}:{};
-    await command(git,['-c','credential.helper=','-c','core.hooksPath=/dev/null','-c','http.followRedirects=false','-c','protocol.allow=never','-c','protocol.https.allow=always','fetch','--quiet','--no-tags','--no-recurse-submodules','--depth=100',plan.url,'+refs/heads/*:refs/heads/*'],{cwd:temporary,env:{...env,...authentication},signal,secret:token});
+    await command(git,['-c','credential.helper=','-c','core.hooksPath=/dev/null','-c','http.followRedirects=false','-c','protocol.allow=never','-c','protocol.https.allow=always','fetch','--quiet','--no-tags','--no-recurse-submodules','--depth=100',plan.url,'+refs/heads/*:refs/heads/*'],{cwd:temporary,env:{...env,...authentication},signal,secret:token,timeoutMs:FETCH_MS});
     // A self-contained bundle cannot be shallow. Do not silently fetch an
     // unbounded history; export fetched objects as a local bare repository.
     fs.cpSync(temporary,destination,{recursive:true,errorOnExist:true,force:false});
@@ -70,15 +92,15 @@ export async function fetchRepositoryBundle(plan, destination, signal) {
 }
 
 export async function executeRepositoryFetch(boundary,plan,signal,{transport=fetchRepositoryBundle}={}) {
-  const current=await repositoryFetchPlan(boundary);
+  const current=await repositoryFetchPlan(boundary,path.relative(boundary.cwd,plan.cwd));
   if(current.url!==plan.url||current.cwd!==plan.cwd)throw Error('managed-operation-scope-changed');
   const staging=path.join(boundary.temporary,'approved-origin-'+Date.now());
   try {
     await transport(plan,staging,signal);
-    const rechecked=await repositoryFetchPlan(boundary);
+    const rechecked=await repositoryFetchPlan(boundary,path.relative(boundary.cwd,plan.cwd));
     if(rechecked.url!==plan.url)throw Error('managed-operation-scope-changed');
     // Import is sandboxed. Malicious repo hooks/config cannot reach credentials.
-    await boundary.invoke('bash',{command:`git -c core.hooksPath=/dev/null -c protocol.allow=never -c protocol.file.allow=always fetch --no-tags --no-recurse-submodules --no-write-fetch-head --update-shallow ${quote(staging)} '+refs/heads/*:refs/remotes/origin/*'`,timeout:30},signal);
+    await boundary.invoke('bash',{command:`git -C ${quote(plan.cwd)} -c core.hooksPath=/dev/null -c protocol.allow=never -c protocol.file.allow=always fetch --no-tags --no-recurse-submodules --no-write-fetch-head --update-shallow ${quote(staging)} '+refs/heads/*:refs/remotes/origin/*'`,timeout:120},signal);
     return {content:[{type:'text',text:`Fetched origin branches for ${plan.repository}. Working files and current branch were not changed.`}],details:{operation:'git.fetch',repository:plan.repository}};
   } finally {fs.rmSync(staging,{recursive:true,force:true});}
 }
@@ -86,17 +108,17 @@ export async function executeRepositoryFetch(boundary,plan,signal,{transport=fet
 // The fetch_origin tool of a company conversation: one approved fetch of the
 // GitHub origin (Bypass fetches without asking).
 export function fetchOriginTool(self) {
-  return {name:'fetch_origin',label:'Fetch origin',description:'Request one approved GitHub origin fetch. Refreshes origin branches without changing working files. Does not expose credentials or allow arbitrary network commands.',
-    parameters:{type:'object',properties:{},additionalProperties:false},
-    execute:async(id,_args,signal,_update,ctx)=>{
-      const plan=await repositoryFetchPlan(self.boundary);
+  return {name:'fetch_origin',label:'Fetch origin',description:'Request one approved GitHub origin fetch. Refreshes origin branches without changing working files. Does not expose credentials or allow arbitrary network commands. When the conversation folder holds several repositories, pass path: the repository folder inside it. Use this instead of git fetch, which has no GitHub sign-in here.',
+    parameters:{type:'object',properties:{path:{type:'string',maxLength:500,description:'Repository folder inside the conversation folder, such as "api"; omit when the conversation folder is the repository.'}},additionalProperties:false},
+    execute:async(id,args,signal,_update,ctx)=>{
+      const plan=await repositoryFetchPlan(self.boundary,args?.path);
       if(self.permission==='trusted-full-access'&&!signal?.aborted)return executeRepositoryFetch(self.boundary,plan,signal);
       const {piApprovalBroker}=await import('../runtime/inspection/approval-broker.ts');
       const decision=await piApprovalBroker.request({cwd:self.cwd,rawSessionId:self.session.sessionManager.getSessionId(),toolCallId:id,
         action:{kind:'external-provider-action',preconditionClass:'runtime-only',toolName:'fetch_origin',rawAction:plan,
-          targetPaths:[self.cwd],provider:'github',urlOrigin:'https://github.com',requestedScope:'fetch-origin-once',
+          targetPaths:[plan.cwd],provider:'github',urlOrigin:'https://github.com',requestedScope:'fetch-origin-once',
           reason:`Fetch origin branches from ${plan.repository}`,riskClass:'low',allowConsequence:'Download origin branches once; keep the current branch and working files unchanged.',denyConsequence:'No network request or credential read.'},
-        terminalConfirm:()=>ctx?.ui?.confirm?.('Tải nhánh từ origin',`Tải các nhánh của ${plan.repository} về ${self.cwd} một lần.\n\nĐồng ý: chỉ tải nhánh; nhánh hiện tại và file đang làm không đổi.\nTừ chối: không gửi request mạng, không đọc thông tin đăng nhập.`)??Promise.resolve(false),
+        terminalConfirm:()=>ctx?.ui?.confirm?.('Tải nhánh từ origin',`Tải các nhánh của ${plan.repository} về ${plan.cwd} một lần.\n\nĐồng ý: chỉ tải nhánh; nhánh hiện tại và file đang làm không đổi.\nTừ chối: không gửi request mạng, không đọc thông tin đăng nhập.`)??Promise.resolve(false),
         unavailableFallback:'terminal-confirm',recheck:()=>!signal?.aborted&&Boolean(self.grant)});
       if(!decision.allowed||!decision.consume()||signal?.aborted)throw Error('managed-operation-denied');
       return executeRepositoryFetch(self.boundary,plan,signal);

package/packages/piagent-core/managed/sandbox-diagnostic.mjs

@@ -1,26 +1,39 @@
+// What a failed command tells the agent. Every environment failure names the
+// way on (owner, 2026-10-13): a tool that asks the member's approval
+// (run_with_network, run_with_docker, start_docker, fetch_origin, run_on_host)
+// or a question to the member (ask_user), never "tell the user and stop".
 const DENIAL = /\b(?:EPERM|EACCES)\b|operation not permitted|permission denied/i;
 // A download that never left the machine: resolvers, npm/pip, and the curl or
 // wget a build wrapper runs (mvnw/gradlew fetch their distribution: "curl:
-// Failed to fetch https://repo.maven.apache.org/…").
-const OFFLINE = /ENOTFOUND|EAI_AGAIN|Could not resolve host|getaddrinfo|npm error network|Failed to establish a new connection|\bcurl: (?:\(\d+\) )?Failed to (?:fetch|connect)|\bwget: unable to resolve|Unknown host|UnknownHostException/i;
+// Failed to fetch https://repo.maven.apache.org/…", "wget: Failed to fetch …").
+const OFFLINE = /ENOTFOUND|EAI_AGAIN|Could not resolve host|getaddrinfo|npm error network|Failed to establish a new connection|\bcurl: (?:\(\d+\) )?Failed to (?:fetch|connect)|\bwget: (?:unable to resolve|Failed to fetch)|Unknown host|UnknownHostException/i;
 // `network`: the member approved this command and it ran with network, so a
 // name that does not resolve is the machine's network, not the sandbox.
 // `isolated`: a proxy listens on this Mac, so without approval a command does
 // not reach this Mac's own servers either (tool-boundary.mjs).
+// Node's fetch reports that refusal as a bare "fetch failed" when a test
+// runner prints the error without its cause (node --test on Node 22).
 // `docker`: the command ran with the Docker engine (run_with_docker);
 // `engine`: one is there for run_with_docker, but this command ran without it.
 const DOCKER_DAEMON = /Cannot connect to the Docker daemon|connect to the docker API|docker\.sock|Is the docker daemon running|Could not find a valid Docker environment/i;
+// A runtime or tool the command needs is not on this machine (or not the
+// version the project asks for).
+const TOOLCHAIN = /Unable to locate a Java Runtime|No Java runtime present|JAVA_HOME is not (?:set|defined correctly)|(?:^|\n)\S*?(?:ba|z)?sh: (?:line \d+: )?[\w.+-]+: command not found|zsh: command not found: [\w.+-]+|xcrun: error: (?:unable to find utility|invalid active developer path)|env: '?[\w.+-]+'?: No such file or directory|Unsupported class file major version|invalid target release: \d+|release version \d+ not supported|requires? (?:at least )?Java \d+|The engine "node" is incompatible|Unsupported engine/i;
+// The member's sign-in, which the sandbox does not have.
+const SIGN_IN = /could not read (?:Username|Password) for|terminal prompts disabled|Authentication failed for|Permission denied \(publickey|Host key verification failed|not logged into any GitHub hosts|please run:\s+gh auth login|Could not open a connection to your authentication agent|\bENEEDAUTH\b|\bE401\b|\b401 Unauthorized|requires authentication|denied: requested access to the resource is denied|pull access denied/i;
+
 export function sandboxDiagnostic(message, { network = false, isolated = false, docker = false, engine = false } = {}) {
   const text=String(message);
-  if(docker&&DOCKER_DAEMON.test(text))return 'managed-docker-unreachable: Lệnh chạy với Docker nhưng Docker engine không trả lời (Docker Desktop/Colima chưa chạy hoặc đang khởi động). Không xin duyệt lại cùng lệnh; báo người dùng mở Docker rồi thử lại.\n'+text;
-  if(!docker&&DOCKER_DAEMON.test(text))return (engine?'managed-docker-blocked: Lệnh bash thường không dùng được Docker trong chế độ công ty. Lệnh docker, docker compose, hoặc test cần Docker (Testcontainers) chạy qua run_with_docker để người dùng duyệt đúng lệnh đó.\n':'managed-docker-unavailable: Máy chưa có Docker engine đang chạy (Docker Desktop, Colima, OrbStack…). Báo người dùng mở Docker; sau đó cuộc trò chuyện mới có run_with_docker.\n')+text;
-  if(isolated&&!/CONNECT tunnel failed|tunneling socket|statusCode=403|response 403/i.test(text)&&/ECONNREFUSED|EPERM|connect|Connection refused|could not connect/i.test(text))return 'managed-loopback-blocked: Máy đang chạy một proxy cục bộ, nên lệnh không có mạng cũng không được kết nối tới server trên localhost (proxy có thể đưa lệnh ra internet). Test cần server hoặc database trên localhost: dùng run_with_network để người dùng duyệt đúng lệnh đó.\n'+text;
-  if(network&&!DENIAL.test(text)&&OFFLINE.test(text))return 'managed-network-unreachable: Lệnh đã được duyệt và chạy có mạng nhưng không tới được host (máy đang offline, cần VPN/proxy công ty, hoặc sai tên host). Không xin duyệt lại cùng lệnh; báo người dùng lỗi mạng này.\n'+text;
+  if(docker&&DOCKER_DAEMON.test(text))return 'managed-docker-unreachable: Lệnh chạy với Docker nhưng Docker engine không trả lời (Docker Desktop/Colima/OrbStack chưa chạy hoặc đang khởi động). Gọi start_docker để xin member duyệt mở Docker, rồi chạy lại đúng lệnh này bằng run_with_docker.\n'+text;
+  if(!docker&&DOCKER_DAEMON.test(text))return (engine?'managed-docker-blocked: Lệnh bash thường không dùng được Docker trong chế độ công ty. Lệnh docker, docker compose, hoặc test cần Docker (Testcontainers) chạy qua run_with_docker để người dùng duyệt đúng lệnh đó.\n':'managed-docker-unavailable: Docker engine trên máy chưa chạy. Gọi start_docker để xin member duyệt mở Docker, rồi chạy lệnh bằng run_with_docker.\n')+text;
+  if(TOOLCHAIN.test(text))return 'managed-toolchain-missing: Máy thiếu runtime/công cụ mà lệnh cần, hoặc sai version project yêu cầu. Đừng dừng ở đây: xem project cần gì (pom.xml, build.gradle, .nvmrc, .tool-versions, package.json engines…) rồi dùng run_on_host để xin member duyệt cài trên máy (ví dụ brew install openjdk@21, brew install node@22, sdk install java 21-tem), sau đó chạy lại lệnh. Nếu project build được trong Docker thì có thể đề xuất run_with_docker. Trình cài cần mật khẩu (sudo, file .pkg) thì hỏi member bằng ask_user.\n'+text;
+  if(SIGN_IN.test(text))return 'managed-credentials-unavailable: Lệnh cần tài khoản đăng nhập của member (git qua HTTPS/SSH, registry riêng, image riêng), sandbox không có. git fetch dùng fetch_origin; git pull, git push, cài từ registry riêng hoặc pull image riêng thì dùng run_on_host để member duyệt chạy đúng lệnh đó trên máy bằng tài khoản của họ.\n'+text;
+  if(isolated&&!/CONNECT tunnel failed|tunneling socket|statusCode=403|response 403/i.test(text)&&/ECONNREFUSED|EPERM|connect|Connection refused|could not connect|fetch failed/i.test(text))return 'managed-loopback-blocked: Máy đang chạy một proxy cục bộ, nên lệnh không có mạng cũng không được kết nối tới server trên localhost (proxy có thể đưa lệnh ra internet). Test cần server hoặc database trên localhost: dùng run_with_network để người dùng duyệt đúng lệnh đó.\n'+text;
+  if(network&&!DENIAL.test(text)&&OFFLINE.test(text))return 'managed-network-unreachable: Lệnh đã được duyệt và chạy có mạng nhưng không tới được host (máy offline, cần VPN/proxy công ty, hoặc sai tên host). Hỏi member bằng ask_user, kèm lựa chọn "Đã kết nối mạng/VPN, chạy lại" và "Bỏ qua bước này"; member trả lời xong thì làm theo.\n'+text;
   if(!DENIAL.test(text)&&OFFLINE.test(text))return 'managed-network-blocked: Lệnh bash thường không có mạng trong chế độ công ty. Nếu lệnh thật sự cần mạng (cài package, tải dữ liệu), dùng run_with_network để người dùng duyệt đúng lệnh đó.\n'+text;
   if(!DENIAL.test(text))return text;
   // /tmp is shared by every process on the Mac, so it stays read-only; each
   // command has its own temporary folder in $TMPDIR (Linux: a private /tmp).
-  if(/(?:^|[\s'"=:(])\/(?:private\/)?tmp\//.test(text))return 'managed-sandbox-denied: /tmp chỉ được đọc trong chế độ công ty. Ghi file tạm (log, kết quả test) vào "$TMPDIR" (thư mục tạm riêng của lệnh, ví dụ "$TMPDIR/test.log") hoặc trong project. Không tự chạy lại bên ngoài sandbox.\n'+text;
-  return 'managed-sandbox-denied: Công cụ bị giới hạn quyền trong chế độ công ty (hoặc quyền file của hệ điều hành). Keychain và file chứa credential như .env/.npmrc bị chặn. Lệnh cần mạng (cài package, tải dữ liệu) dùng run_with_network để xin duyệt; git fetch origin dùng fetch_origin. Không tự chạy lại bên ngoài sandbox.\n'+text;
+  if(/(?:^|[\s'"=:(])\/(?:private\/)?tmp\//.test(text))return 'managed-sandbox-denied: /tmp chỉ được đọc trong chế độ công ty. Ghi file tạm (log, kết quả test) vào "$TMPDIR" (thư mục tạm riêng của lệnh, ví dụ "$TMPDIR/test.log") hoặc trong project.\n'+text;
+  return 'managed-sandbox-denied: Sandbox chặn thao tác này (ghi ngoài project, Keychain, file credential như .env/.npmrc, thư mục hệ thống). Nếu task thật sự cần nó, dùng run_on_host để member duyệt chạy đúng lệnh đó trên máy, ngoài sandbox. Lệnh chỉ cần mạng thì dùng run_with_network; git fetch dùng fetch_origin.\n'+text;
 }
-

package/packages/piagent-core/managed/session.mjs

@@ -3,7 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { randomUUID, createHash } from 'node:crypto';
 import { pathToFileURL, fileURLToPath } from 'node:url';
-import { ManagedToolBoundary } from './tool-boundary.mjs';
+import { ManagedToolBoundary, PI_HOST_VERSION, hostPackage } from './tool-boundary.mjs';
 import { ensureSearchTools, trustSystemCertificates } from './toolchain.mjs';
 import { inlineExtensions, managedResourceLoader, projectInstructions } from './resource-loader.mjs';
 import { fetchPublicPage, fetchLimits } from './web-fetch.mjs';
@@ -91,10 +91,10 @@ export class ManagedSession {
   // the conversation enrolls again before its next run.
   static async create({ sdkRoot, cwd, origin, broker, protectedRoots = [], agentDir, sessionManager, renewBroker = null, bindingRevision = null, terminalExtensions = [] }) {
     const sdk = fs.realpathSync(sdkRoot);
-    if (JSON.parse(fs.readFileSync(path.join(sdk, 'package.json'))).version !== '0.87.1') throw Error('managed-sdk-version-unqualified');
+    if (JSON.parse(fs.readFileSync(path.join(sdk, 'package.json'))).version !== PI_HOST_VERSION) throw Error('managed-sdk-version-unqualified');
     await trustSystemCertificates();
     const api = await import(pathToFileURL(path.join(sdk, 'dist/index.js')));
-    const ai = await import(pathToFileURL(path.join(sdk, 'node_modules/@earendil-works/pi-ai/dist/index.js')));
+    const ai = await import(pathToFileURL(path.join(hostPackage(sdk, '@earendil-works/pi-ai'), 'dist/index.js')));
     const manifest = usable(await patiently(() => broker.request('config'), 3));
     const self = new ManagedSession(); Object.assign(self, { sdk, cwd: fs.realpathSync(cwd), origin: safeOrigin(origin), broker, api, ai, manifest, protectedRoots, helpers: new Map(), helperCalls: new Map(), ownPaths: new Set(), listeners: new Set(), capacityWaits: new Set(), routes: new WeakMap(), grant: null,
       renewBroker, bindingRevision, bindingSeen: bindingRevision?.() ?? null, preflight: null, blocked: null });

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

@@ -8,7 +8,9 @@ import { createHash, randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { developerLicense, developerTools, managedGit, searchToolPath, userToolchains } from './toolchain.mjs';
 import { languageEnvironment } from './language-environment.mjs';
-import { containerEngine, engineEnvironment } from './container-engine.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 { BWRAP, bubblewrapArgs, credentialFiles, referenceFolders } from './linux-sandbox.mjs';
 import { agentWatchDataDirectory } from './store.mjs';
@@ -205,8 +207,8 @@ export class ManagedToolBoundary {
     this.runtimeRoot = fs.realpathSync(path.dirname(workerPath));
     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 !== '0.87.1') throw new Error('managed-sdk-version-unqualified');
-    const workerModules = ['search-fallback.mjs', 'sandbox-diagnostic.mjs'].map(name => path.join(this.runtimeRoot, name));
+    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));
     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)
@@ -229,11 +231,6 @@ export class ManagedToolBoundary {
     // A repository above the home folder (a dotfiles repo) is never opened:
     // neither read as a monorepo nor writable through its git directory.
     const gitDirs = repo && (repo.top === this.cwd || allowedRoot(repo.top)) ? [...new Set([repo.gitDir, repo.commonDir])].filter(dir => !inside(dir, this.cwd) && allowedRoot(dir)) : [];
-    const toolchains = userToolchains(userHome, this.node), developer = developerTools(), browsers = playwrightBrowsers(userHome);
-    const languages = languageEnvironment({ userHome, repositoryTop: this.repositoryTop, home: this.home });
-    this.packageCache = languages.cache;
-    // The Docker engine, for commands the member approves (run_with_docker).
-    this.engine = readOnly ? null : containerEngine({ userHome });
     // A skill folder opens for reading only inside the agent folders (.claude,
     // .codex, .pi, .agents) or outside the home folder's hidden entries, and
     // never when it holds a closed folder (a link to ~/.ssh, the home folder).
@@ -241,42 +238,77 @@ export class ManagedToolBoundary {
     const skills = [...new Set(skillFolders.flatMap(dir => { try { return [fs.realpathSync(dir)]; } catch { return []; } }))]
       .filter(dir => dir !== '/' && !/[\x00-\x1f\x7f]/.test(dir) && !narrowed.some(root => inside(root, dir)) && !inside(userHome, dir)
         && (!inside(dir, userHome) || agentFolders.some(root => inside(dir, root)) || !path.relative(userHome, dir).startsWith('.')));
-    const base = { cwd: this.cwd, sdkRoot: this.sdkRoot, runtimeRoot: this.runtimeRoot, temporary: this.temporary, node: this.node,
-      denied: narrowed, readOnly, repository, gitDirs, toolchains: [...toolchains.roots, ...languages.readRoots], developer: developer.roots,
-      browsers: browsers ? [browsers] : [], skills, caches: languages.writeRoots, license: developerLicense() };
     this.userHome = userHome;
     // Only for commands the user approved (run_with_network); credentials stay
     // denied, and so do reference folders: what a command with network can
     // read is the project, not the member's other files.
     this.networkAllowed = !readOnly;
-    if (this.linux) {
-      const references = referenceFolders(userHome).filter(dir => !narrowed.some(root => inside(dir, root) || inside(root, dir)));
-      const empty = path.join(this.temporary, 'empty'); fs.writeFileSync(empty, '', { mode: 0o400 });
-      this.linuxBase = { ...base, toolchains: [...base.toolchains, ...base.browsers], references, empty, engineRoots: this.engine?.readRoots ?? [] };
-      this.referenceCredentials = credentialFiles(references, { limit: 30_000 });
-      this.projectCredentials = { at: 0, files: [] };
-    } else {
-      this.profile = managedSeatbelt({ ...base, references: userHome });
-      // The same without loopback, while a local proxy listens (localProxyListening).
-      this.isolatedProfile = managedSeatbelt({ ...base, references: userHome, loopback: false });
-      this.proxyPorts = proxyPorts ?? localProxyPorts(); this.proxyCheck = { at: 0, listening: Promise.resolve(false) };
-      this.networkProfile = readOnly ? null : managedSeatbelt({ ...base, network: true });
-      // An approved network command that also reaches the Docker engine's socket.
-      this.dockerProfile = this.engine ? managedSeatbelt({ ...base, network: true, docker: this.engine.socket, toolchains: [...base.toolchains, ...this.engine.readRoots] }) : null;
-    }
     // Every process a command starts carries this marker, also one it detaches.
     this.scope = randomUUID();
-    this.environment = toolEnvironment({ git: this.git, node: this.node, home: this.home, temporary: this.temporary, toolchains, developer, scope: this.scope, browsers, languages,
-      identity: identity !== undefined ? identity : gitIdentity(this.git, this.cwd) });
-    if (this.engine) this.environment.docker = { ...this.environment.network, ...engineEnvironment(this.engine, this.home) };
+    this.setup = { narrowed, readOnly, repository, gitDirs, skills, identity: identity !== undefined ? identity : gitIdentity(this.git, this.cwd) };
+    if (this.linux) {
+      this.references = referenceFolders(userHome).filter(dir => !narrowed.some(root => inside(dir, root) || inside(root, dir)));
+      this.empty = path.join(this.temporary, 'empty'); fs.writeFileSync(this.empty, '', { mode: 0o400 });
+      this.referenceCredentials = credentialFiles(this.references, { limit: 30_000 });
+      this.projectCredentials = { at: 0, files: [] };
+    } else { this.proxyPorts = proxyPorts ?? localProxyPorts(); this.proxyCheck = { at: 0, listening: Promise.resolve(false) }; }
+    this.#configure();
     // Package registries without asking (package-proxy.mjs): commands that
     // write the project reach them through the runtime's proxy; read-only
     // helpers keep no network at all.
-    if (!readOnly) this.proxyReady = this.startProxy(base, languages);
+    if (!readOnly) this.proxyReady = this.startProxy();
     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];
   }
+  // What the machine offers commands: toolchains, the JDK, the Docker engine.
+  // Looked up again after the member installs or starts something
+  // (run_on_host, start_docker), so the conversation sees it without a restart.
+  #configure() {
+    const { narrowed, readOnly, repository, gitDirs, skills, identity } = this.setup, userHome = this.userHome;
+    const toolchains = userToolchains(userHome, this.node), developer = developerTools(), browsers = playwrightBrowsers(userHome);
+    const languages = languageEnvironment({ userHome, repositoryTop: this.repositoryTop, home: this.home });
+    this.packageCache = languages.cache; this.languages = languages;
+    // The Docker engine, for commands the member approves (run_with_docker).
+    this.engine = readOnly ? null : containerEngine({ userHome });
+    this.dockerCli = readOnly ? null : this.engine?.cli ?? dockerCli();
+    // What the host loads: its own folder, and the node_modules its
+    // dependencies were hoisted to when they are not nested in it (Pi 1.x).
+    const ai = hostPackage(this.sdkRoot, '@earendil-works/pi-ai'), hostRoot = inside(fs.realpathSync(ai), this.sdkRoot) ? this.sdkRoot : fs.realpathSync(path.dirname(path.dirname(ai)));
+    const base = this.base = { cwd: this.cwd, sdkRoot: hostRoot, runtimeRoot: this.runtimeRoot, temporary: this.temporary, node: this.node,
+      denied: narrowed, readOnly, repository, gitDirs, toolchains: [...toolchains.roots, ...languages.readRoots], developer: developer.roots,
+      browsers: browsers ? [browsers] : [], skills, caches: languages.writeRoots, license: developerLicense() };
+    if (this.linux) this.linuxBase = { ...base, toolchains: [...base.toolchains, ...base.browsers], references: this.references, empty: this.empty, engineRoots: this.engine?.readRoots ?? [] };
+    else {
+      this.networkProfile = readOnly ? null : managedSeatbelt({ ...base, network: true });
+      // An approved network command that also reaches the Docker engine's socket.
+      this.dockerProfile = this.engine ? managedSeatbelt({ ...base, network: true, docker: this.engine.socket, toolchains: [...base.toolchains, ...this.engine.readRoots] }) : null;
+    }
+    this.environment = toolEnvironment({ git: this.git, node: this.node, home: this.home, temporary: this.temporary, toolchains, developer, scope: this.scope, browsers, languages, identity });
+    if (this.engine) this.environment.docker = { ...this.environment.network, ...engineEnvironment(this.engine, this.home) };
+    this.#applyProxy();
+  }
+  // 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;
+    if (!this.linux) {
+      // TLS through the macOS Security framework (Go, Swift, .NET) verifies
+      // the registries' certificates with the system's trust services.
+      this.profile = managedSeatbelt({ ...this.base, references: this.userHome, ...(port ? { proxyPort: port } : {}) });
+      // The same without loopback, while a local proxy listens (localProxyListening).
+      this.isolatedProfile = managedSeatbelt({ ...this.base, references: this.userHome, loopback: false, ...(port ? { proxyPort: port } : {}) });
+    }
+    if (!this.proxyUrl) return;
+    const offline = this.environment.offline;
+    for (const key of ['npm_config_fetch_retries', 'npm_config_fetch_timeout', 'PIP_RETRIES', 'PIP_TIMEOUT']) delete offline[key];
+    Object.assign(offline, proxyEnvironment(this.proxyUrl, { mavenOpts: offline.MAVEN_OPTS, gradleOpts: offline.GRADLE_OPTS, mavenHome: this.home }), { GOPROXY: this.languages.env.network.GOPROXY },
+      this.linux ? { PIAGENT_PROXY_SOCKET: '/run/piagent-proxy.sock' } : {});
+  }
+  // Looks the machine up again; true when the Docker engine is there now.
+  refreshEnvironment() {
+    if (!this.#closed) this.#configure();
+    return Boolean(this.engine);
+  }
   tools(api) {
     const factories = { read: api.createReadToolDefinition, write: api.createWriteToolDefinition,
       edit: api.createEditToolDefinition, bash: api.createBashToolDefinition,
@@ -291,7 +323,7 @@ export class ManagedToolBoundary {
   // 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(base, languages) {
+  async startProxy() {
     this.proxy = new PackageProxy({ domains: [...DEFAULT_DOMAINS, ...memberDomains(this.userHome)] });
     try {
       let url;
@@ -299,21 +331,10 @@ export class ManagedToolBoundary {
         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';
-        this.environment.offline.PIAGENT_PROXY_SOCKET = '/run/piagent-proxy.sock';
-      } else {
-        const { port } = await this.proxy.listen();
-        url = `http://127.0.0.1:${port}`;
-        // TLS through the macOS Security framework (Go, Swift, .NET) verifies
-        // the registries' certificates with the system's trust services.
-        this.profile = managedSeatbelt({ ...base, references: this.userHome, proxyPort: port });
-        this.isolatedProfile = managedSeatbelt({ ...base, references: this.userHome, loopback: false, proxyPort: port });
-      }
-      const offline = this.environment.offline;
-      for (const key of ['npm_config_fetch_retries', 'npm_config_fetch_timeout', 'PIP_RETRIES', 'PIP_TIMEOUT']) delete offline[key];
+      } 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 });
-      Object.assign(offline, proxyEnvironment(url, { mavenOpts: offline.MAVEN_OPTS, gradleOpts: offline.GRADLE_OPTS, mavenHome: this.home }), { GOPROXY: languages.env.network.GOPROXY });
-      this.proxyUrl = url;
+      this.proxyUrl = url; this.#applyProxy();
     } catch { await this.proxy.close().catch(() => {}); this.proxy = null; }
   }
   async invoke(name, args, signal, onUpdate, model, { network = false, docker = false } = {}) {
@@ -420,28 +441,50 @@ export class ManagedToolBoundary {
   async stopStrays() {
     // On Linux a command's processes end with it (its own PID namespace).
     if (this.#children.size || this.linux) return 0;
-    const marker = `PIAGENT_TOOL_SCOPE=${this.scope}`, find = () => {
-      try {
-        return execFileSync('/bin/ps', ['-axwwE', '-o', 'pid=,command='], { encoding: 'utf8', maxBuffer: 64 << 20, timeout: 5000 }).split('\n')
-          .filter(row => row.includes(marker)).map(row => Number(row.trim().split(/\s+/)[0])).filter(pid => Number.isSafeInteger(pid) && pid > 1 && pid !== process.pid);
-      } catch { return []; }
-    };
-    const strays = find();
-    for (const pid of strays) try { process.kill(pid, 'SIGTERM'); } catch {}
-    for (let waited = 0; strays.length && waited < 2000; waited += 100) {
-      await new Promise(resolve => setTimeout(resolve, 100));
-      if (!find().length) break;
-    }
-    for (const pid of find()) try { process.kill(pid, 'SIGKILL'); } catch {}
-    return strays.length;
+    return stopMarked(`PIAGENT_TOOL_SCOPE=${this.scope}`);
+  }
+  // A process the agent keeps running across turns (background-process.mjs):
+  // the plain command sandbox and environment, marked as this conversation's
+  // background process instead of the turn's, so stopStrays leaves it.
+  async spawnBackground(command, key) { return this.spawnSandboxed(['/bin/bash', '-c', command], key); }
+  // `argv` in the plain command sandbox; stdin 'pipe' for a process that
+  // answers requests (ts-diagnostics.mjs).
+  async spawnSandboxed(argv, key, { stdin = 'ignore' } = {}) {
+    if (this.#closed || this.linux || !this.allowed.includes('bash') || !/^[0-9a-f-]{36}$/.test(key)) throw new Error('managed-tool-unavailable');
+    for (const [file, digest] of this.pins) if (hash(file) !== digest) throw new Error('managed-runtime-changed');
+    if (Date.now() - this.proxyCheck.at > 5000) this.proxyCheck = { at: Date.now(), listening: localProxyListening(this.proxyPorts) };
+    const isolated = await this.proxyCheck.listening, { PIAGENT_TOOL_SCOPE: _turn, ...env } = this.environment.offline;
+    const child = spawn('/usr/bin/sandbox-exec', ['-p', isolated ? this.isolatedProfile : this.profile, ...argv],
+      { cwd: this.cwd, detached: true, stdio: [stdin, 'pipe', 'pipe'], env: { ...env, PIAGENT_PROCESS_SCOPE: `${this.scope}:${key}` } });
+    return { child, isolated };
   }
+  stopBackground(key) { return stopMarked(`PIAGENT_PROCESS_SCOPE=${this.scope}:${key}`); }
   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 this.stopStrays();
+    await this.background?.dispose(); await this.stopStrays(); if (!this.linux) await stopMarked(`PIAGENT_PROCESS_SCOPE=${this.scope}:`);
     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 });
   }
 }
+
+// Stops every process whose environment carries `marker` (ps -E), then
+// whatever is left after two seconds.
+async function stopMarked(marker) {
+  const find = () => {
+    try {
+      return execFileSync('/bin/ps', ['-axwwE', '-o', 'pid=,command='], { encoding: 'utf8', maxBuffer: 64 << 20, timeout: 5000 }).split('\n')
+        .filter(row => row.includes(marker)).map(row => Number(row.trim().split(/\s+/)[0])).filter(pid => Number.isSafeInteger(pid) && pid > 1 && pid !== process.pid);
+    } catch { return []; }
+  };
+  const found = find();
+  for (const pid of found) try { process.kill(pid, 'SIGTERM'); } catch {}
+  for (let waited = 0; found.length && waited < 2000; waited += 100) {
+    await new Promise(resolve => setTimeout(resolve, 100));
+    if (!find().length) break;
+  }
+  for (const pid of find()) try { process.kill(pid, 'SIGKILL'); } catch {}
+  return found.length;
+}

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

@@ -43,7 +43,9 @@ input.on('line', async line => {
       : await factories[message.name](cwd, options).execute('managed-tool', message.args, controller.signal,
         update => emit({ update }), { cwd, model: message.model });
     // Successful output is returned verbatim; the sandbox note is only added to
-    // failures (Pi tools throw on denial and on a non-zero shell exit).
+    // 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 });
   } 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/ts-diagnostics-server.mjs

@@ -0,0 +1,102 @@
+// Runs inside the command sandbox (ts-diagnostics.mjs starts it): the
+// project's own TypeScript reports the errors of one file, one request per
+// line on stdin ({id, file}), one answer per line on stdout. TypeScript 5 and
+// 6 keep a language service per tsconfig/jsconfig; TypeScript 7 (the native
+// compiler, which has no such JavaScript API) checks the project with its own
+// tsc, fast enough to run on each change.
+import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { createInterface } from 'node:readline';
+
+const [cwd] = process.argv.slice(2);
+const services = new Map();
+const inside = (root, file) => { const relative = path.relative(root, file); return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative)); };
+const version = file => { try { const stat = fs.statSync(file); return `${stat.mtimeMs}:${stat.size}`; } catch { return '0'; } };
+
+// The nearest tsconfig.json, else jsconfig.json, inside the project.
+function configFor(file) {
+  for (const name of ['tsconfig.json', 'jsconfig.json']) {
+    for (let dir = path.dirname(file); inside(cwd, dir); dir = path.dirname(dir)) {
+      if (fs.existsSync(path.join(dir, name))) return path.join(dir, name);
+      if (dir === cwd) break;
+    }
+  }
+  return null;
+}
+
+function serviceFor(file) {
+  let manifest;
+  try { manifest = createRequire(file).resolve('typescript/package.json'); } catch { return { reason: 'no-typescript' }; }
+  const config = configFor(file);
+  if (!config) return { reason: 'no-config' };
+  if (services.has(config)) return services.get(config);
+  const major = Number.parseInt(JSON.parse(fs.readFileSync(manifest, 'utf8')).version, 10);
+  if (major >= 7) {
+    const entry = { native: path.join(path.dirname(manifest), 'bin/tsc'), config };
+    services.set(config, entry); return entry;
+  }
+  const ts = createRequire(file)(path.dirname(manifest));
+  const parsed = ts.getParsedCommandLineOfConfigFile(config, {}, { ...ts.sys, onUnRecoverableConfigFileDiagnostic: () => {} });
+  if (!parsed) return { reason: 'no-config' };
+  const extra = new Set();
+  const host = {
+    getScriptFileNames: () => [...new Set([...parsed.fileNames, ...extra])],
+    getScriptVersion: version,
+    getScriptSnapshot: name => fs.existsSync(name) ? ts.ScriptSnapshot.fromString(fs.readFileSync(name, 'utf8')) : undefined,
+    getCurrentDirectory: () => path.dirname(config),
+    getCompilationSettings: () => parsed.options,
+    getDefaultLibFileName: options => ts.getDefaultLibFilePath(options),
+    fileExists: ts.sys.fileExists, readFile: ts.sys.readFile, readDirectory: ts.sys.readDirectory,
+    directoryExists: ts.sys.directoryExists, getDirectories: ts.sys.getDirectories,
+  };
+  const entry = { ts, config, extra, service: ts.createLanguageService(host, ts.createDocumentRegistry()) };
+  services.set(config, entry);
+  return entry;
+}
+
+// tsc --pretty false prints "file(line,col): error TS1234: message".
+function nativeDiagnostics({ native, config }, file) {
+  let output;
+  try { output = execFileSync(process.execPath, [native, '--noEmit', '--pretty', 'false', '-p', config], { cwd: path.dirname(config), encoding: 'utf8', timeout: 30000, maxBuffer: 16 << 20, stdio: ['ignore', 'pipe', 'pipe'] }); }
+  catch (error) { output = String(error.stdout ?? ''); }
+  const found = [], elsewhere = [];
+  for (const line of output.split('\n')) {
+    const match = line.match(/^(.+?)\((\d+),(\d+)\): error TS(\d+): (.*)$/);
+    if (!match) continue;
+    const at = path.resolve(path.dirname(config), match[1]), item = { line: Number(match[2]), column: Number(match[3]), code: Number(match[4]), message: match[5].slice(0, 400) };
+    if (at === file) found.push(item); else elsewhere.push({ ...item, file: path.relative(cwd, at) });
+  }
+  // A syntax error anywhere stops tsc before it checks types: say so rather
+  // than let silence read as a clean file.
+  const syntax = elsewhere.filter(item => item.code >= 1000 && item.code < 2000);
+  return found.length || !syntax.length ? { diagnostics: found } : { diagnostics: [], uncheckedBecause: syntax.slice(0, 3) };
+}
+
+function diagnostics(file) {
+  const entry = serviceFor(file);
+  if (entry.reason) return { reason: entry.reason };
+  if (entry.native) return { config: path.relative(cwd, entry.config), ...nativeDiagnostics(entry, file) };
+  const { ts, service, extra, config } = entry;
+  extra.add(file);
+  const found = [...service.getSyntacticDiagnostics(file), ...service.getSemanticDiagnostics(file)]
+    .filter(d => d.category === ts.DiagnosticCategory.Error)
+    .map(d => {
+      const at = d.file && d.start !== undefined ? d.file.getLineAndCharacterOfPosition(d.start) : { line: 0, character: 0 };
+      return { line: at.line + 1, column: at.character + 1, code: d.code, message: ts.flattenDiagnosticMessageText(d.messageText, ' ').slice(0, 400) };
+    });
+  return { config: path.relative(cwd, config), diagnostics: found };
+}
+
+const input = createInterface({ input: process.stdin });
+input.on('line', line => {
+  let id = null;
+  try {
+    const request = JSON.parse(line); id = request.id;
+    const file = path.resolve(cwd, String(request.file));
+    if (!inside(cwd, file)) throw new Error('outside the project');
+    process.stdout.write(JSON.stringify({ id, ...diagnostics(file) }) + '\n');
+  } catch (error) { process.stdout.write(JSON.stringify({ id, error: String(error?.message ?? error).slice(0, 300) }) + '\n'); }
+});
+input.on('close', () => process.exit(0));