@piagent/platform 1.23.1 → 1.25.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,8 +1,12 @@
+// 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
@@ -10,17 +14,24 @@ const OFFLINE = /ENOTFOUND|EAI_AGAIN|Could not resolve host|getaddrinfo|npm erro
 // `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|\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(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/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(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

@@ -171,7 +171,7 @@ export class ManagedSession {
     // The member's access for this conversation: ask first, or Bypass (permission.mjs).
     self.permission = restorePermission(manager); self.session.managedSetPermission = permissionSetter(self, manager);
     // Fast mode, where the Harness allows it (fast-mode.mjs): off until the member turns it on.
-    self.fast = restoreFast(manager); recordFast(self, manager); self.session.managedSetFast = fastSetter(self, manager); self.session.managedFastState = () => fastState(self); // null before the first run
+    self.fast = restoreFast(manager); recordFast(self, manager); self.session.managedSetFast = fastSetter(self, manager); self.session.managedFastState = () => fastState(self); // null where the Harness does not allow it
     self.session.managedFastServed = () => { const route = self.routes.get(self.modelRuntime); return route ? fastServed(route) : null; };
     // A helper's receipt (its tokens, the patch it read) is for the member's
     // eyes: the agent has the helper's answer as the tool result, and a

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

@@ -8,7 +8,7 @@ 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 { 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';
@@ -229,11 +229,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 +236,74 @@ 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();
+    const base = this.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() };
+    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 +318,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 +326,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 } = {}) {

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

@@ -58,10 +58,13 @@ export function repositoryChecks(agentsFiles, cwd, top = cwd) {
 }
 // A command that verifies code: a declared check, or a known test, type,
 // lint or build runner. Text tools that merely mention one do not count.
-const RUNNER = /\b(npm|pnpm|yarn|bun)\s+(run\s+)?(test|lint|typecheck|type-check|check|build|verify)\b|\bnode\s+--test\b|\b(tsc|vitest|jest|eslint|biome|ruff|mypy|pyright|pytest|rspec|phpunit)\b|\bplaywright\s+test\b|\bpython3?\s+-m\s+(pytest|unittest|mypy)\b|\bgo\s+(test|vet|build)\b|\bcargo\s+(test|check|clippy|build)\b|\bswift\s+(test|build)\b|\bxcodebuild\b.*\b(test|build)\b|\bmake\s+(test|check|lint)\b|\b(gradle|gradlew|mvn)\b.*\b(test|check|verify)\b|\bdotnet\s+(test|build)\b|\bdeno\s+(test|check|lint)\b/;
+const RUNNER = /\b(npm|pnpm|yarn|bun)\s+(run\s+)?(test|lint|typecheck|type-check|check|build|verify)\b|\bnode\s+--test\b|\b(tsc|vitest|jest|eslint|biome|ruff|mypy|pyright|pytest|rspec|phpunit)\b|\bplaywright\s+test\b|\bpython3?\s+-m\s+(pytest|unittest|mypy)\b|\bgo\s+(test|vet|build)\b|\bcargo\s+(test|check|clippy|build)\b|\bswift\s+(test|build)\b|\bxcodebuild\b.*\b(test|build)\b|\bmake\s+(test|check|lint)\b|\b(gradle|gradlew|mvn|mvnw)\b.*\b(test|check|verify|compile|package|build)\b|\bdotnet\s+(test|build)\b|\bdeno\s+(test|check|lint)\b/;
 // A command that only reads: each part starts with a reading tool and nothing
-// is written to a file. Anything else may change files.
-const READER = /^(ls|cat|head|tail|wc|grep|egrep|rg|find|fd|sed|awk|cut|sort|uniq|tr|echo|printf|pwd|which|stat|file|du|df|tree|jq|diff|cmp|basename|dirname|realpath|date|true|cd|git\s+(status|diff|log|show|branch|ls-files|rev-parse|blame))\b/;
+// is written to a file. Anything else may change files. Git may name the
+// repository first (git -C <folder>): a workspace folder holding several
+// repositories is read that way.
+const GIT_READ = String.raw`git(\s+(-C\s+('[^']*'|"[^"]*"|\S+)|-c\s+\S+|--no-pager))*\s+(status|diff|log|show|branch|ls-files|rev-parse|rev-list|blame|describe|shortlog|cat-file|for-each-ref|reflog(?!\s+(expire|delete))|remote(\s+(-v|--verbose|show|get-url)\b|$))`;
+const READER = new RegExp(String.raw`^(ls|cat|head|tail|wc|grep|egrep|rg|find|fd|sed|awk|cut|sort|uniq|tr|echo|printf|pwd|which|stat|file|du|df|tree|jq|diff|cmp|basename|dirname|realpath|date|true|cd|${GIT_READ})(\b|$)`);
 export function isReadOnlyCommand(command) {
   const text = String(command ?? '').trim();
   if (!text || />(?!>|\s*&\d|\s*\/dev\/null)|\btee\b|\bsed\s+(-[a-zA-Z]*i|--in-place)|\s-(delete|exec|execdir|fprint|ok)\b|\bxargs\b|\$\(|`/.test(text)) return false;
@@ -117,7 +120,7 @@ export function workflowPrompt(policy, checks) {
   }
   if (policy.review !== 'off') lines.push(policy.review === 'require' ? '- Review: the harness reviews the final patch with an independent reviewer; blocking findings come back to you to fix, or to answer when a finding is wrong: the reviewer then judges your answer, and a disagreement that remains goes to the member.'
     : '- Review: before you finish a code change, ask the review helper (delegate role "review") to review the patch, then fix blocking findings.');
-  return lines.length ? `\n\nProcess for code changes (company Harness):\n${lines.join('\n')}\nEnd-to-end tests that start a local server and a browser run through run_with_network, which the user approves. If a step cannot be done here (a check needs a database or another service), say so plainly; do not try to install or start services to get around the sandbox.\nA command stops after 10 minutes and anything left running in the background stops when the turn ends: run the checks that cover your change first and a long suite in parts, not in the background.` : '';
+  return lines.length ? `\n\nProcess for code changes (company Harness):\n${lines.join('\n')}\nEnd-to-end tests that start a local server and a browser run through run_with_network, which the user approves. If a check cannot run because the machine lacks something (a runtime such as a JDK, Docker, a database or another service, the network), do not stop there: request the approval that makes it run (run_with_network, run_with_docker, start_docker, or run_on_host to install what is missing) or ask the member with ask_user; never install or start anything without that approval.\nA command stops after 10 minutes and anything left running in the background stops when the turn ends: run the checks that cover your change first and a long suite in parts, not in the background.` : '';
 }
 
 // Every helper checks the brief it was given: it may object with evidence, it
@@ -280,9 +283,10 @@ export async function completionGate(managed, run, signal) {
   for (let step = 0; step < 16; step += 1) {
     digest = await digestOf();
     run.changed = run.startDigest !== null && digest !== null ? digest !== run.startDigest : run.mutations > 0;
+    // A check that passed still counts when the turn was cut off after it.
+    if (run.changed) run.verified = run.verifiedOn(digest);
     if (stopped()) { interrupted = run.changed; break; }
     if (run.changed) {
-      run.verified = run.verifiedOn(digest);
       const reviewDigest = managed.review ? await reviewDigestOf() : null;
       const review = managed.review, fresh = !!review && !review.stale && reviewDigest !== null && review.patchDigest === reviewDigest;
       run.reviewed = fresh;
@@ -292,7 +296,7 @@ export async function completionGate(managed, run, signal) {
       if (policy.verify === 'require' && !run.verified && !verifyGaveUp) {
         run.fixLoops += 1;
         const list = run.checks.commands.length ? run.checks.commands.map(c => '`' + c + '`').join(', ') : 'the tests, type check or build that cover the change';
-        await send(`Harness process check: code changed in this turn, but no check has passed on the current code. Run the checks that cover your change (${list}) and fix what fails. If a check cannot run here (it needs a database, a service or the network) or fails for a reason unrelated to your change, say so plainly instead of trying to install or start services.`,
+        await send(`Harness process check: code changed in this turn, but no check has passed on the current code. Run the checks that cover your change (${list}) and fix what fails. If a check cannot run because the machine lacks something (a runtime such as a JDK, Docker, a database or another service, the network), request the approval that makes it run (run_with_network, run_with_docker, start_docker, run_on_host) or ask the member with ask_user, then run it; install or start nothing without that approval. If it fails for a reason unrelated to your change, say so plainly.`,
           { phase: 'verify', loop: run.fixLoops, maxLoops: policy.maxFixLoops, lastCheckFailed: run.lastCheck?.ok === false });
         continue;
       }

package/packages/piagent-core/package.json

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