@piagent/platform 1.12.1 → 1.13.1

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

@@ -54,8 +54,10 @@ export async function runDoctor({ sdkRoot, origin, broker, network = true }) {
       if (await bash("cat 'Dự án mới/ghi chú.md'") !== 'ổn') throw Error('content changed'); return 'ok';
     });
     await check('folders outside the project are read-only', true, async () => {
-      let refused = false; try { await boundary.invoke('write', { path: '../piagent-doctor-outside.txt', content: 'x' }); } catch { refused = true; }
-      if (!refused) { fs.rmSync(path.join(path.dirname(project), 'piagent-doctor-outside.txt'), { force: true }); throw Error('a write outside the project was allowed'); }
+      // Refused, or (Linux) kept in the sandbox's own /tmp: never on this machine.
+      const outside = path.join(path.dirname(project), 'piagent-doctor-outside.txt');
+      try { await boundary.invoke('write', { path: '../piagent-doctor-outside.txt', content: 'x' }); } catch { /* refused */ }
+      if (fs.existsSync(outside)) { fs.rmSync(outside, { force: true }); throw Error('a write outside the project was allowed'); }
       // A folder the member points to for reference (@~/…) is readable.
       await boundary.invoke('ls', { path: '~' });
       return 'read, write refused';
@@ -79,7 +81,7 @@ export async function runDoctor({ sdkRoot, origin, broker, network = true }) {
     });
     await check('make', false, () => bash('make --version'));
     // Tests that start a server or use a local database (tool-boundary.mjs).
-    await check('tests reach servers on this Mac (localhost)', false, async () => {
+    await check('tests reach their own servers (localhost)', false, async () => {
       await boundary.invoke('write', { path: 'loopback.mjs', content: "import http from 'node:http'; const s = http.createServer((q, r) => r.end('ok')); s.listen(0, '127.0.0.1', async () => { console.log(await (await fetch(`http://127.0.0.1:${s.address().port}/`)).text()); s.close(); });\n" });
       try { return await bash('node loopback.mjs'); }
       catch (error) { throw Error(/loopback-blocked/.test(String(error?.message)) ? 'a local proxy listens on this Mac: tests that use localhost need run_with_network' : first(String(error?.message))); }

package/packages/piagent-core/managed/language-environment.mjs

@@ -30,6 +30,13 @@ function prune(root, keep) {
 }
 
 function javaHome(userHome) {
+  if (process.platform === 'linux') {
+    if (process.env.JAVA_HOME) return existing(process.env.JAVA_HOME);
+    for (const dir of (process.env.PATH ?? '/usr/bin').split(':')) {
+      try { return existing(path.dirname(path.dirname(fs.realpathSync(path.join(dir, 'javac'))))); } catch { /* next */ }
+    }
+    return null;
+  }
   try {
     const home = execFileSync('/usr/libexec/java_home', [], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'], env: { HOME: userHome, PATH: '/usr/bin:/bin' } }).trim();
     return existing(home);
@@ -56,7 +63,8 @@ esac
 `;
 
 export function languageEnvironment({ userHome, repositoryTop, home }) {
-  const root = path.join(userHome, 'Library/Caches/Piagent/sandbox');
+  const linux = process.platform === 'linux';
+  const root = linux ? path.join(process.env.XDG_CACHE_HOME || path.join(userHome, '.cache'), 'piagent/sandbox') : path.join(userHome, 'Library/Caches/Piagent/sandbox');
   const cache = path.join(root, createHash('sha256').update(repositoryTop).digest('hex').slice(0, 24));
   fs.mkdirSync(cache, { recursive: true, mode: 0o700 });
   fs.chmodSync(cache, 0o700);
@@ -73,16 +81,17 @@ export function languageEnvironment({ userHome, repositoryTop, home }) {
     // here: packages the member restored are read from their own folder.
     nuget: existing(path.join(userHome, '.nuget/packages')),
   };
-  const java = javaHome(userHome), android = existing(path.join(userHome, 'Library/Android/sdk'));
+  const java = javaHome(userHome), android = existing(path.join(userHome, linux ? 'Android/Sdk' : 'Library/Android/sdk'));
   const readRoots = [...new Set([...Object.values(seeds), java, android, existing(path.join(userHome, 'Library/Java/JavaVirtualMachines')),
     existing('/Library/Ruby'), existing('/opt/local')].filter(Boolean))];
 
   const bin = path.join(home, '.piagent/bin');
   fs.mkdirSync(bin, { recursive: true, mode: 0o700 });
-  for (const name of ['swift', 'xcodebuild']) fs.writeFileSync(path.join(bin, name), SWIFT_WRAPPER, { mode: 0o755 });
+  // (Only macOS: SwiftPM on Linux starts no sandbox of its own.)
+  if (!linux) for (const name of ['swift', 'xcodebuild']) fs.writeFileSync(path.join(bin, name), SWIFT_WRAPPER, { mode: 0o755 });
   // pnpm's store: its own settings file, which npm does not read (an npm_config_
   // variable would make every npm command warn about an unknown setting).
-  const pnpm = path.join(home, 'Library/Preferences/pnpm');
+  const pnpm = path.join(home, linux ? '.config/pnpm' : 'Library/Preferences/pnpm');
   fs.mkdirSync(pnpm, { recursive: true, mode: 0o700 });
   fs.writeFileSync(path.join(pnpm, 'rc'), `store-dir=${at('pnpm-store')}\n`, { mode: 0o600 });
 
@@ -105,9 +114,10 @@ export function languageEnvironment({ userHome, repositoryTop, home }) {
   // .NET keeps its named mutexes (NuGet's among them) as files in
   // /tmp/.dotnet, whatever TMPDIR says.
   const dotnet = [path.join(userHome, '.dotnet/dotnet'), '/usr/local/share/dotnet/dotnet', '/opt/homebrew/bin/dotnet'].some(file => fs.existsSync(file));
-  if (dotnet) try { fs.mkdirSync('/private/tmp/.dotnet', { recursive: true, mode: 0o777 }); } catch { /* another user's */ }
+  // (On Linux the sandbox has its own /tmp.)
+  if (dotnet && !linux) try { fs.mkdirSync('/private/tmp/.dotnet', { recursive: true, mode: 0o777 }); } catch { /* another user's */ }
   return {
-    cache, readRoots, writeRoots: [cache, ...(dotnet && existing('/private/tmp/.dotnet') ? ['/private/tmp/.dotnet'] : [])], bin,
+    cache, readRoots, writeRoots: [cache, ...(dotnet && !linux && existing('/private/tmp/.dotnet') ? ['/private/tmp/.dotnet'] : [])], bin,
     env: {
       // .NET's dual-stack sockets reach 127.0.0.1 as ::ffff:127.0.0.1, which
       // the loopback rule does not name (the test host would not connect).

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

@@ -0,0 +1,81 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// The company sandbox on Linux, and so on Windows through WSL2: what Seatbelt
+// does on macOS (tool-boundary.mjs), built from bubblewrap mounts. Nothing is
+// there unless mounted:
+// - system folders, toolchains, the SDK and skill folders read-only;
+// - the project (read-only for helpers), its package cache and a private
+//   temporary folder writable;
+// - the member's own folders read-only for reference, without the home
+//   folder's hidden entries (shell files, histories, tool settings, keys);
+// - credential files found in what is mounted read as empty (an empty file
+//   mounted over them: /dev/null cannot be opened in a user namespace);
+// - everything else, the root included, read-only: a write elsewhere fails
+//   as it does on macOS instead of landing in a throwaway folder.
+// A command without approval runs in its own network namespace: it reaches
+// the servers it starts itself, nothing else (no internet, no proxy, no
+// service of this machine). Its processes end with it. Windows programs
+// cannot be started from inside: WSL's interop socket is not mounted.
+export const BWRAP = ['/usr/bin/bwrap', '/bin/bwrap', '/usr/local/bin/bwrap'].find(file => { try { fs.accessSync(file, fs.constants.X_OK); return true; } catch { return false; } }) ?? null;
+
+const SYSTEM = ['/usr', '/bin', '/sbin', '/lib', '/lib32', '/lib64', '/libx32', '/etc', '/opt', '/snap', '/sys', '/run/systemd/resolve'];
+const SKIP = new Set(['node_modules', '.git', '.hg', '.svn', 'dist', 'build', 'target', 'vendor', '.venv', 'venv', '__pycache__', '.cache', '.next', '.gradle']);
+const SCAN_ENTRIES = 50_000;
+
+// Names the macOS profile closes (tool-boundary.mjs): .env and .env.* but not
+// committed templates, credentials and credentials.*, .npmrc, .netrc, and
+// auth.json at a project's root or in a dot folder.
+export function credentialName(name, parent, roots) {
+  if (/^\.env(\.|$)/.test(name)) return !/^\.env\.(example|sample|template|dist|defaults)$/.test(name);
+  if (/^credentials(\.|$)/.test(name) || name === '.npmrc' || name === '.netrc') return true;
+  return name === 'auth.json' && (roots.includes(parent) || path.basename(parent).startsWith('.'));
+}
+
+// Credential files and folders under these roots, walking at most
+// SCAN_ENTRIES entries and never into dependency or build folders or links.
+export function credentialFiles(roots, { limit = SCAN_ENTRIES } = {}) {
+  const found = [], queue = [...roots];
+  let seen = 0;
+  while (queue.length && seen < limit) {
+    const dir = queue.shift();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      seen += 1;
+      const full = path.join(dir, entry.name);
+      if (credentialName(entry.name, dir, roots)) { found.push({ path: full, directory: entry.isDirectory() }); continue; }
+      if (entry.isDirectory() && !entry.isSymbolicLink() && !SKIP.has(entry.name)) queue.push(full);
+    }
+  }
+  return found;
+}
+
+const depth = file => file.split('/').length;
+export function bubblewrapArgs({ cwd, sdkRoot, runtimeRoot, temporary, empty, node, readOnly = false, repository = [], gitDirs = [], toolchains = [], skills = [], caches = [], references = [], network = false, credentials = [] }) {
+  const exists = file => { try { fs.statSync(file); return true; } catch { return false; } };
+  const readable = [...new Set([sdkRoot, runtimeRoot, path.dirname(node), ...repository, ...toolchains, ...skills, ...references, ...(readOnly ? [cwd, ...gitDirs] : [])])].filter(exists);
+  const writable = [...new Set([...caches, ...(readOnly ? [] : [cwd, ...gitDirs])])].filter(exists);
+  // A parent is mounted before what lies under it (a later mount covers).
+  const mounts = [...readable.map(dir => ['--ro-bind', dir]), ...writable.map(dir => ['--bind', dir])]
+    .sort((a, b) => depth(a[1]) - depth(b[1]) || (a[0] === '--ro-bind' ? -1 : 1));
+  return [
+    '--die-with-parent', '--new-session', '--unshare-pid', '--unshare-ipc', '--unshare-uts', '--unshare-cgroup-try',
+    ...(network ? [] : ['--unshare-net']),
+    ...SYSTEM.filter(exists).flatMap(dir => ['--ro-bind', dir, dir]),
+    '--proc', '/proc', '--dev', '/dev', '--tmpfs', '/tmp', '--bind', temporary, temporary,
+    ...mounts.flatMap(([kind, dir]) => [kind, dir, dir]),
+    ...credentials.filter(item => exists(item.path)).flatMap(item => item.directory ? ['--tmpfs', item.path] : ['--ro-bind', empty, item.path]),
+    '--remount-ro', '/', '--chdir', cwd,
+  ];
+}
+
+// The member's own folders for reference: the home folder's entries except
+// hidden ones (and the Windows profile's, from WSL, except AppData).
+export function referenceFolders(userHome, windowsHome = null) {
+  const list = (home, skip = () => false) => {
+    try { return fs.readdirSync(home, { withFileTypes: true }).filter(entry => !entry.name.startsWith('.') && !skip(entry.name)).map(entry => path.join(home, entry.name)); }
+    catch { return []; }
+  };
+  return [...list(userHome), ...(windowsHome ? list(windowsHome, name => /^(AppData|NTUSER|ntuser)/i.test(name)) : [])];
+}

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

@@ -31,7 +31,10 @@ const BASE_PROMPT = 'You are Piagent, the company coding assistant. If an earlie
 // they name) are readable for reference; the sandbox keeps them read-only.
 const referencePrompt = home => ` The member may point you to folders outside the project for reference (an @path mention or a folder they name): read them with read, ls, grep and find. They are read-only: changes go in the project only. In those tools ~ is the member's home folder (${home}); in bash ~ is a private empty folder, so use absolute paths there.`;
 // Tests in the sandbox (tool-boundary.mjs, language-environment.mjs).
-const TEST_PROMPT = ' To run unit and integration tests, use bash. Installing packages (npm, pnpm, pip, uv, go, cargo, gradle, maven…) needs run_with_network once; the project\'s package caches are kept, so later runs work offline. Servers on localhost (a test\'s own server, a local database) are reachable, except while a local proxy runs (the error says so: then use run_with_network). Docker and the iOS Simulator are not available in the sandbox: ask the member to start those services or run those tests.';
+const TEST_PROMPT = ' To run unit and integration tests, use bash. Installing packages (npm, pnpm, pip, uv, go, cargo, gradle, maven…) needs run_with_network once; the project\'s package caches are kept, so later runs work offline. '
+  + (process.platform === 'linux'
+    ? 'A command without network reaches only the servers it starts itself, which end with it: start a test server and run the tests in one command; a database or service already running on this machine needs run_with_network. Docker is not available in the sandbox: ask the member to start those services.'
+    : 'Servers on localhost (a test\'s own server, a local database) are reachable, except while a local proxy runs (the error says so: then use run_with_network). Docker and the iOS Simulator are not available in the sandbox: ask the member to start those services or run those tests.');
 const textContent = result => result.content?.filter(p => p.type === 'text').map(p => p.text).join('\n') ?? '';
 export function taskClass(text) {
   // Advisory hint only. Studio owns allowed models, budgets and run authority.

package/packages/piagent-core/managed/store.d.mts

@@ -1,3 +1,5 @@
 export function memberId(origin: unknown, userId: unknown): string | null;
 export function storedSlot(root: string, slot: string): string | null;
 export function resolveStore(root: string, slot: string, identity: { origin: unknown; userId: unknown }): string;
+export function agentWatchDataDirectory(home: string, environment?: Readonly<Record<string, string | undefined>>): string;
+export function interopEnvironment(environment?: Readonly<Record<string, string | undefined>>): Record<string, string>;

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

@@ -9,6 +9,18 @@ import { createHash } from 'node:crypto';
 // points at it (`<slot>/store`), so a new key lists and continues the same
 // conversations. Another member, or another Studio, gets another store.
 const SLOT = /^[a-f0-9]{64}$/;
+
+// Where Agent Watch keeps a member's company data on this machine: the macOS
+// app's support folder; on Linux, and so in WSL, the XDG data folder.
+export function agentWatchDataDirectory(home, environment = process.env) {
+  return process.platform === 'linux' ? path.join(environment.XDG_DATA_HOME || path.join(home, '.local/share'), 'agentwatch')
+    : path.join(home, 'Library/Application Support/AgentWatch');
+}
+// What a Windows program (Agent Watch's broker) needs to start from WSL; a
+// clean environment otherwise drops it.
+export function interopEnvironment(environment = process.env) {
+  return Object.fromEntries(['WSL_INTEROP', 'WSL_DISTRO_NAME'].filter(name => environment[name]).map(name => [name, environment[name]]));
+}
 const read = file => { try { return fs.readFileSync(file, 'utf8').trim(); } catch { return null; } };
 const write = (file, value) => { fs.writeFileSync(file, value + '\n', { mode: 0o600 }); };
 const sessionFiles = dir => { try { return fs.readdirSync(path.join(dir, 'sessions')).filter(name => name.endsWith('.jsonl')); } catch { return []; } };

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

@@ -8,6 +8,8 @@ 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 { 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;
@@ -108,7 +110,9 @@ ${denied.map(root => `(deny file-read* file-write* (require-all (subpath ${liter
 // retrying for minutes.
 function toolEnvironment({ git, node, home, temporary, toolchains, developer, identity, scope, browsers, languages }) {
   const PATH = [...new Set([languages.bin, path.dirname(node), ...toolchains.bins, '/opt/homebrew/bin', '/opt/homebrew/sbin', '/usr/local/bin', ...developer.bins, path.dirname(git), '/usr/bin', '/bin', '/usr/sbin', '/sbin'])].join(':');
-  const common = { ...toolchains.env, ...developer.env, PATH, HOME: home, TMPDIR: temporary, PIAGENT_TOOL_SCOPE: scope, LANG: 'en_US.UTF-8', LC_ALL: 'en_US.UTF-8', RIPGREP_CONFIG_PATH: path.join(home, '.ripgreprc'),
+  // C.UTF-8 is on every Linux; en_US.UTF-8 may not be generated there.
+  const locale = process.platform === 'linux' ? 'C.UTF-8' : 'en_US.UTF-8';
+  const common = { ...toolchains.env, ...developer.env, PATH, HOME: home, TMPDIR: temporary, PIAGENT_TOOL_SCOPE: scope, LANG: locale, LC_ALL: locale, RIPGREP_CONFIG_PATH: path.join(home, '.ripgreprc'),
     ...(identity ? { GIT_AUTHOR_NAME: identity.name, GIT_AUTHOR_EMAIL: identity.email, GIT_COMMITTER_NAME: identity.name, GIT_COMMITTER_EMAIL: identity.email } : {}) };
   // The sandbox home is empty: Playwright finds the member's browsers by path.
   const playwright = browsers ? { PLAYWRIGHT_BROWSERS_PATH: browsers } : {};
@@ -117,7 +121,8 @@ function toolEnvironment({ git, node, home, temporary, toolchains, developer, id
 }
 // The browsers `npx playwright install` put in the member's cache.
 function playwrightBrowsers(userHome) {
-  try { const dir = fs.realpathSync(path.join(userHome, 'Library/Caches/ms-playwright')); return fs.statSync(dir).isDirectory() ? dir : null; } catch { return null; }
+  const cache = process.platform === 'darwin' ? 'Library/Caches/ms-playwright' : '.cache/ms-playwright';
+  try { const dir = fs.realpathSync(path.join(userHome, cache)); return fs.statSync(dir).isDirectory() ? dir : null; } catch { return null; }
 }
 // Without network a command still reaches servers on this Mac (a test's own
 // server, a database for integration tests), unless a proxy listens here:
@@ -187,7 +192,9 @@ export class ManagedToolBoundary {
   // the same (a helper that runs checks); it writes only to its temporary
   // directory, and has no network.
   constructor({ cwd, sdkRoot, protectedRoots = [], readOnly = false, commands = false, node = process.execPath, identity, userHome: home, searchTools = true, skills: skillFolders = [], proxyPorts }) {
-    if (process.platform !== 'darwin') throw new Error('managed-sandbox-unavailable');
+    // macOS: Seatbelt. Linux, and Windows through WSL2: bubblewrap (linux-sandbox.mjs).
+    this.linux = process.platform === 'linux';
+    if (process.platform !== 'darwin' && !(this.linux && BWRAP)) throw new Error('managed-sandbox-unavailable');
     this.cwd = fs.realpathSync(cwd); this.sdkRoot = fs.realpathSync(sdkRoot);
     this.node = fs.realpathSync(node);
     this.runtimeRoot = fs.realpathSync(path.dirname(workerPath));
@@ -204,7 +211,7 @@ export class ManagedToolBoundary {
     this.home = path.join(this.temporary, 'home'); fs.mkdirSync(this.home, { mode: 0o700 });
     const denied = [path.join(userHome, '.ssh'), path.join(userHome, '.aws'), path.join(userHome, '.config'),
       path.join(userHome, '.pi'), path.join(userHome, '.codex'), path.join(userHome, '.claude'),
-      path.join(userHome, 'Library/Keychains'), path.join(userHome, 'Library/Application Support/AgentWatch'),
+      path.join(userHome, 'Library/Keychains'), agentWatchDataDirectory(userHome),
       ...protectedRoots.map(p => path.resolve(p))];
     // A pinned SDK may itself be installed under ~/.pi; grant that code only,
     // while keeping the adjacent personal auth/config subtree inaccessible.
@@ -231,14 +238,23 @@ export class ManagedToolBoundary {
       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;
-    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) };
     // 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.networkProfile = readOnly ? null : managedSeatbelt({ ...base, network: true });
+    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 };
+      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 });
+    }
     // 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,
@@ -259,18 +275,20 @@ export class ManagedToolBoundary {
     } }));
   }
   async invoke(name, args, signal, onUpdate, model, { network = false } = {}) {
-    if (this.#closed || !this.allowed.includes(name) || network && (name !== 'bash' || !this.networkProfile)) throw new Error('managed-tool-unavailable');
+    if (this.#closed || !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
     // own HOME is an empty private folder.
     if (name !== 'bash' && typeof args?.path === 'string' && /^@?~(\/|$)/.test(args.path)) args = { ...args, path: this.userHome + args.path.replace(/^@?~/, '') };
-    if (!network && Date.now() - this.proxyCheck.at > 5000) this.proxyCheck = { at: Date.now(), listening: localProxyListening(this.proxyPorts) };
-    const isolated = !network && await this.proxyCheck.listening;
+    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 } : {}), 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) => {
-      const child = spawn('/usr/bin/sandbox-exec', ['-p', network ? this.networkProfile : isolated ? this.isolatedProfile : this.profile, this.node, workerPath, this.sdkPath, this.cwd], {
+      const [sandbox, sandboxArgs] = this.linux ? [BWRAP, this.bubblewrap(network)]
+        : ['/usr/bin/sandbox-exec', ['-p', network ? this.networkProfile : isolated ? this.isolatedProfile : this.profile]];
+      const child = spawn(sandbox, [...sandboxArgs, this.node, workerPath, this.sdkPath, this.cwd], {
         cwd: this.cwd, detached: true, stdio: ['pipe', 'pipe', 'pipe'],
         env: network ? this.environment.network : this.environment.offline,
       });
@@ -327,11 +345,20 @@ export class ManagedToolBoundary {
       if (signal?.aborted) abort();
     });
   }
+  // bubblewrap arguments for one command: credential files of the project are
+  // looked for again every 15 seconds (a file the member just added).
+  bubblewrap(network) {
+    if (Date.now() - this.projectCredentials.at > 15_000)
+      this.projectCredentials = { at: Date.now(), files: credentialFiles([this.cwd, ...this.linuxBase.repository]) };
+    const credentials = [...this.projectCredentials.files, ...(network ? [] : this.referenceCredentials)];
+    return bubblewrapArgs({ ...this.linuxBase, references: network ? [] : this.linuxBase.references, network, credentials });
+  }
   // Processes a command left running (`nohup … &`, a detached child) outlive
   // it with the marker in their environment. They are stopped when a turn ends
   // and when the boundary closes; nothing outside this boundary has the marker.
   async stopStrays() {
-    if (this.#children.size) return 0;
+    // 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')

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

@@ -16,7 +16,8 @@ function selectedDeveloperDir() {
 // Pin the actual installed binary; never widen access to user preferences.
 export function managedGit() {
   const selected = selectedDeveloperDir();
-  for (const candidate of [`${CLT}/usr/bin/git`, ...(selected ? [path.join(selected, 'usr/bin/git')] : []), '/Applications/Xcode.app/Contents/Developer/usr/bin/git', '/opt/homebrew/bin/git', '/usr/local/bin/git']) {
+  for (const candidate of [`${CLT}/usr/bin/git`, ...(selected ? [path.join(selected, 'usr/bin/git')] : []), '/Applications/Xcode.app/Contents/Developer/usr/bin/git', '/opt/homebrew/bin/git', '/usr/local/bin/git',
+    ...(process.platform === 'linux' ? ['/usr/bin/git'] : [])]) {
     if (executable(candidate)) return fs.realpathSync(candidate);
   }
   throw Error('managed-git-unavailable');
@@ -65,7 +66,9 @@ const downloaded = new Map();
 // ripgrep and fd for Pi's grep/find, on any member machine: an installed copy,
 // else Pi's own downloader run here (outside the sandbox, like personal Pi).
 export function searchToolPath(name, userHome = os.homedir()) {
-  for (const candidate of [downloaded.get(name), `/opt/homebrew/bin/${name}`, `/usr/local/bin/${name}`, path.join(userHome, '.pi/agent/bin', name)]) {
+  // Debian and Ubuntu install fd as fdfind.
+  const system = process.platform === 'linux' ? [`/usr/bin/${name}`, ...(name === 'fd' ? ['/usr/bin/fdfind'] : [])] : [];
+  for (const candidate of [downloaded.get(name), `/opt/homebrew/bin/${name}`, `/usr/local/bin/${name}`, path.join(userHome, '.pi/agent/bin', name), ...system]) {
     if (candidate && executable(candidate)) return fs.realpathSync(candidate);
   }
   return null;

package/packages/piagent-core/package.json

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

package/packages/piagent-core/runtime/host/browser-opener.d.mts

@@ -0,0 +1,2 @@
+export function browserCommand(url: string, options?: { platform?: NodeJS.Platform; environment?: Readonly<Record<string, string | undefined>> }):
+  { command: string; args: string[]; options?: { cwd?: string } } | null;

package/packages/piagent-core/runtime/host/browser-opener.mjs

@@ -0,0 +1,20 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// How this machine opens a link in the member's browser: `open` on macOS,
+// `start` on Windows, and from WSL the Windows browser (wslview when
+// installed, else explorer.exe, which takes a link as it is: cmd's start
+// would split one at &). Elsewhere xdg-open. null: no way here.
+export function browserCommand(url, { platform = process.platform, environment = process.env } = {}) {
+  if (platform === 'darwin') return { command: 'open', args: [url] };
+  if (platform === 'win32') return { command: 'cmd', args: ['/c', 'start', '', url] };
+  if (platform !== 'linux') return null;
+  const onPath = name => String(environment.PATH ?? '').split(':').filter(Boolean).map(dir => path.join(dir, name)).find(file => { try { fs.accessSync(file, fs.constants.X_OK); return true; } catch { return false; } });
+  if (environment.WSL_DISTRO_NAME) {
+    const wslview = onPath('wslview');
+    if (wslview) return { command: wslview, args: [url] };
+    const explorer = onPath('explorer.exe');
+    if (explorer) return { command: explorer, args: [url], options: { cwd: '/mnt/c' } };
+  }
+  return { command: 'xdg-open', args: [url] };
+}

package/packages/piagent-core/runtime/input/chat-images.ts

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -84,19 +85,24 @@ export function supportedChatImageMimeType(bytes: Buffer): string | undefined {
   return undefined;
 }
 
+// On Windows a path may also start with a drive (C:\) and use backslashes.
+const WINDOWS = process.platform === "win32";
+const HOME_PREFIX = WINDOWS ? /^~[\\/]/ : /^~\//;
+const RELATIVE_PREFIX = WINDOWS ? /^\.\.?[\\/]/ : /^\.\.?\//;
+
 function normalizeImagePathCandidate(candidate: string, cwd: string, options: { allowBareRelative?: boolean } = {}): string | undefined {
   let raw = candidate.trim().replace(/^['"`<]+|['"`>,.;:!?]+$/g, "");
   if (!raw) return undefined;
   const allowBareRelative = options.allowBareRelative !== false;
-  const hasExplicitPathPrefix = raw.startsWith("file://") || raw.startsWith("~/") || path.isAbsolute(raw) || raw.startsWith("./") || raw.startsWith("../");
+  const hasExplicitPathPrefix = raw.startsWith("file://") || HOME_PREFIX.test(raw) || path.isAbsolute(raw) || RELATIVE_PREFIX.test(raw);
   if (!allowBareRelative && !hasExplicitPathPrefix) return undefined;
   try {
     if (raw.startsWith("file://")) raw = fileURLToPath(raw);
   } catch {
     return undefined;
   }
-  if (raw.startsWith("~/")) {
-    const home = process.env.HOME;
+  if (HOME_PREFIX.test(raw)) {
+    const home = process.env.HOME || (WINDOWS ? os.homedir() : undefined);
     if (!home) return undefined;
     raw = path.join(home, raw.slice(2));
   }
@@ -123,7 +129,8 @@ export function extractLocalImagePathCandidates(text: string, cwd: string): stri
     if (normalized) candidates.add(normalized);
   }
 
-  const linePathPattern = '\\s((?:/|~\\/|\\.\\.?/)[^\\n\\r"\\\'<>]*?\\.' + imageExt + ')(?=$|\\s|["\\\'`)>])';
+  const start = WINDOWS ? "(?:/|[A-Za-z]:[\\\\/]|~[\\\\/]|\\.\\.?[\\\\/])" : "(?:/|~\\/|\\.\\.?/)";
+  const linePathPattern = '\\s(' + start + '[^\\n\\r"\\\'<>]*?\\.' + imageExt + ')(?=$|\\s|["\\\'`)>])';
   const linePath = new RegExp(linePathPattern, "gi");
   for (const match of text.matchAll(linePath)) {
     const normalized = normalizeImagePathCandidate(match[1], cwd);

package/packages/piagent-core/runtime/resources/agent-resources.mjs

@@ -17,14 +17,14 @@ const MAX_FILE_BYTES = 256 * 1024;
 const MAX_ENTRIES = 400;
 
 function folder(file) {
-  try { return fs.statSync(file).isDirectory() ? fs.realpathSync(file) : null; } catch { return null; }
+  try { return fs.statSync(file).isDirectory() ? fs.realpathSync.native(file) : null; } catch { return null; }
 }
 
 // The project folder and its parents up to the repository root (the first
 // folder holding .git), at most 12 levels, never the home folder or above it.
 export function projectFolders(cwd, home = os.homedir()) {
-  const folders = [], stop = fs.realpathSync(home);
-  for (let dir = fs.realpathSync(cwd), depth = 0; depth < 12; depth += 1) {
+  const folders = [], stop = fs.realpathSync.native(home);
+  for (let dir = fs.realpathSync.native(cwd), depth = 0; depth < 12; depth += 1) {
     if (dir === stop || dir === path.dirname(dir) || (stop + path.sep).startsWith(dir + path.sep)) break;
     folders.push(dir);
     if (fs.existsSync(path.join(dir, '.git'))) break;
@@ -89,7 +89,7 @@ function readSmall(file) {
 
 function origin(file, home) {
   const name = /(?:^|\/)\.(claude|codex|agents|pi)\//.exec(file)?.[1] ?? 'pi';
-  return { origin: name, scope: file.startsWith(`${fs.realpathSync(home)}${path.sep}.`) ? 'user' : 'project' };
+  return { origin: name, scope: file.startsWith(`${fs.realpathSync.native(home)}${path.sep}.`) ? 'user' : 'project' };
 }
 
 function skillFiles(root, depth = 0, files = []) {