@piagent/platform 1.37.1 → 1.38.2

package/packages/piagent-core/managed/patch-snapshot.mjs

@@ -1,11 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
-import { fileURLToPath } from 'node:url';
+import { invokeReviewSnapshot } from './review-snapshot-request.mjs';
 
-const quote = value => "'" + value.replaceAll("'", "'\"'\"'") + "'";
 const textContent = result => result.content?.filter(p => p.type === 'text').map(p => p.text).join('\n') ?? '';
-const WORKER = fileURLToPath(new URL('./review-snapshot-worker.mjs', import.meta.url));
 const MAX_SNAPSHOT = 16 * 1024 * 1024;
 
 // The worker runs inside the tool boundary; what it prints is one short line.
@@ -20,8 +18,8 @@ async function worker(boundary, mode, scope = null, base = null) {
     fs.writeFileSync(path.join(boundary.temporary, scopeName), JSON.stringify([...scope]), { mode: 0o600, flag: 'wx' });
   }
   let result;
-  const from = typeof base === 'string' && BASE.test(base) ? ' ' + base : '';
-  try { result = await boundary.invoke('bash', { command: `${quote(process.execPath)} ${quote(WORKER)} ${mode}${scopeName ? ' ' + scopeName : ''}${from}`, timeout: 60 }); }
+  const extra = [...(scopeName ? [scopeName] : []), ...(typeof base === 'string' && BASE.test(base) ? [base] : [])];
+  try { result = await invokeReviewSnapshot(boundary, mode, extra); }
   finally { if (scopeName) fs.rmSync(path.join(boundary.temporary, scopeName), { force: true }); }
   const text = textContent(result).trim();
   if (result.details?.truncation?.truncated || text.includes('\n')) throw Error(/review-(patch|file|untracked)-limit/.exec(text)?.[0] ?? 'managed-review-patch-unreadable');
@@ -37,7 +35,7 @@ export async function readPatchDigest(boundary, scope = null, base = null) { ret
 // The commit HEAD names now, or null (no repository, no commit yet).
 export async function readHead(boundary) {
   try {
-    const result = await boundary.invoke('bash', { command: `${quote(process.execPath)} ${quote(WORKER)} head`, timeout: 60 });
+    const result = await invokeReviewSnapshot(boundary, 'head');
     const text = textContent(result).trim();
     return BASE.test(text) ? text : null;
   } catch { return null; }
@@ -48,7 +46,7 @@ export async function readHead(boundary) {
 export async function resolveReviewBase(boundary, ref) {
   if (typeof ref !== 'string' || !/^[A-Za-z0-9._\/~^@{}-]{1,200}$/.test(ref) || ref.startsWith('-')) return null;
   try {
-    const result = await boundary.invoke('bash', { command: `${quote(process.execPath)} ${quote(WORKER)} since ${quote(ref)}`, timeout: 60 });
+    const result = await invokeReviewSnapshot(boundary, 'since', [ref]);
     const text = textContent(result).trim();
     return BASE.test(text) ? text : null;
   } catch { return null; }
@@ -57,7 +55,7 @@ export async function resolveReviewBase(boundary, ref) {
 // came since: { base, ref }, or null.
 export async function readBranchBase(boundary) {
   try {
-    const result = await boundary.invoke('bash', { command: `${quote(process.execPath)} ${quote(WORKER)} branch-base`, timeout: 60 });
+    const result = await invokeReviewSnapshot(boundary, 'branch-base');
     const [base, ref] = textContent(result).trim().split(' ');
     return BASE.test(base ?? '') && ref ? { base, ref } : null;
   } catch { return null; }

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

@@ -1,12 +1,22 @@
 // A company conversation's access, chosen by the member and kept with the
 // conversation: "workspace-write" asks before every command that needs the
-// internet; "trusted-full-access" (Bypass) asks only for what must be
-// confirmed (runtime/policy/bypass-policy.mjs).
+// internet; "trusted-full-access" (Full access) asks only for what must be
+// confirmed (runtime/policy/bypass-policy.mjs); "bypass" asks nothing, as
+// Codex's bypass mode, where the team's Harness allows it
+// (harness.configuration.bypass_mode, an administrator's switch in Studio).
+// The sandbox itself stays: bypass removes the questions, not the boundary.
 import { mustConfirm } from '../runtime/policy/bypass-policy.mjs';
 
-export const PERMISSIONS = ['workspace-write', 'trusted-full-access'];
+export const PERMISSIONS = ['workspace-write', 'trusted-full-access', 'bypass'];
 const ENTRY = 'agent-watch-permission';
 
+// Only an explicit yes from Studio: an Agent Watch that does not carry the
+// field, or a Harness an administrator switched off, gives no bypass.
+export const bypassAllowed = manifest => manifest?.harness?.configuration?.bypass_mode === true;
+// What applies now: a conversation left in bypass after the administrator
+// switched it off falls back to Full access.
+export const effectivePermission = owner => owner.permission === 'bypass' && !bypassAllowed(owner.manifest) ? 'trusted-full-access' : owner.permission;
+
 export function restorePermission(manager) {
   const chosen = manager.getEntries().filter(e => e.type === 'custom' && e.customType === ENTRY).at(-1)?.data?.mode;
   return PERMISSIONS.includes(chosen) ? chosen : 'workspace-write';
@@ -14,9 +24,22 @@ export function restorePermission(manager) {
 export function permissionSetter(owner, manager) {
   return mode => {
     if (!PERMISSIONS.includes(mode)) throw Error('managed-permission-unavailable');
+    if (mode === 'bypass' && !bypassAllowed(owner.manifest)) throw Error('managed-bypass-unavailable');
     manager.appendCustomEntry(ENTRY, { mode, at: new Date().toISOString() }); owner.permission = mode;
   };
 }
-// Why a network command must still be asked about: null runs it in Bypass,
-// 'ask' when the member asks first.
-export const networkConfirmation = (owner, command) => owner.permission === 'trusted-full-access' ? mustConfirm(command) : 'ask';
+// The conversation records whether its Harness allows Bypass, so the
+// dashboard offers it (or not) without the runtime.
+const ALLOWANCE = 'agent-watch-bypass';
+export function recordBypass(owner, manager) {
+  const allowed = bypassAllowed(owner.manifest);
+  const last = manager.getEntries().filter(e => e.type === 'custom' && e.customType === ALLOWANCE).at(-1)?.data;
+  if ((last?.allowed === true) !== allowed) manager.appendCustomEntry(ALLOWANCE, { allowed, at: new Date().toISOString() });
+}
+// Whether this conversation may skip the questions Full access still asks.
+export const asksNothing = owner => effectivePermission(owner) === 'bypass';
+export const broadAccess = owner => ['trusted-full-access', 'bypass'].includes(effectivePermission(owner));
+// Why a network command must still be asked about: null runs it in Full
+// access or Bypass, 'ask' when the member asks first.
+export const networkConfirmation = async (owner, command) => asksNothing(owner) ? null
+  : effectivePermission(owner) === 'trusted-full-access' ? mustConfirm(command) : 'ask';

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

@@ -1,3 +1,4 @@
+import { broadAccess } from './permission.mjs';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -112,7 +113,7 @@ export function fetchOriginTool(self) {
     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);
+      if(broadAccess(self)&&!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,

package/packages/piagent-core/managed/review-snapshot-request.mjs

@@ -0,0 +1,21 @@
+import { fileURLToPath } from 'node:url';
+
+const worker = fileURLToPath(new URL('./review-snapshot-worker.mjs', import.meta.url));
+const requests = new WeakSet();
+const quote = value => "'" + value.replaceAll("'", "'\"'\"'") + "'";
+
+// Only fixed runtime snapshot reads preserve provenance. JSON tool arguments
+// cannot forge this identity; freezing prevents substitution before dispatch.
+export function invokeReviewSnapshot(boundary, mode, extra = []) {
+  if (!['head', 'since', 'branch-base', 'digest', 'file', 'files'].includes(mode)
+    || !Array.isArray(extra) || extra.some(value => typeof value !== 'string')) throw Error('review-request-invalid');
+  const args = Object.freeze({ command: [process.execPath, worker, mode, ...extra].map(quote).join(' '), timeout: 60 });
+  requests.add(args);
+  return boundary.invoke('bash', args);
+}
+
+export function consumeReviewSnapshot(args) {
+  const trusted = requests.has(args);
+  requests.delete(args);
+  return trusted;
+}

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

@@ -1,3 +1,5 @@
+export { companyTerminalDiagnostic } from './terminal-runtime.mjs';
+
 // 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)

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

@@ -0,0 +1,37 @@
+import { randomUUID } from 'node:crypto';
+import { freshnessPath } from './tool-freshness.mjs';
+
+// Trusted sandbox metadata only. No project filesystem access in the parent.
+// Every consumer must revalidate policy and digests inside the boundary.
+export class SessionMutationObservations {
+  #sessionId = randomUUID();
+  #files = new Map();
+  get(file) { return structuredClone(this.#files.get(file) ?? null); }
+  snapshot() { return structuredClone([...this.#files.entries()]); }
+  clear() { this.#files.clear(); }
+  prepare(cwd, name, args, enabled) {
+    const file = freshnessPath(cwd, name, args);
+    const request = enabled ? { sessionId: this.#sessionId, toolCallId: randomUUID(), prior: this.get(file) } : undefined;
+    if (['edit', 'write'].includes(name)) this.#files.delete(file);
+    if (name === 'bash') this.clear();
+    if (name === 'workspace' && args?.kind === 'write') this.#files.delete(args.payload?.path);
+    return request;
+  }
+  acceptRevert(args, trusted, result, update) {
+    if (args?.kind !== 'source' || args.request?.kind !== 'execute') return;
+    const file = args.request.target?.path, prior = this.#files.get(file);
+    this.#files.delete(file);
+    const next = update?.observation;
+    if (!trusted || result?.state !== 'settled' || update?.path !== file || !prior || !next || next.path !== file
+      || next.toolCallId !== prior.toolCallId || JSON.stringify(next.baseline) !== JSON.stringify(prior.baseline)
+      || !/^[a-f0-9]{64}$/.test(next.currentDigest) || !/^session-mutation\.[a-f0-9]{64}$/.test(next.evidenceRef)) return;
+    this.#files.set(file, structuredClone(next));
+  }
+  accept(cwd, name, args, request, observation) {
+    const file = freshnessPath(cwd, name, args);
+    if (!request || !file || observation?.path !== file || observation.toolCallId !== request.toolCallId
+      || typeof observation.baseline?.content !== 'string' || Buffer.byteLength(observation.baseline.content) > 256 * 1024) return;
+    this.#files.set(file, observation);
+    while (this.#files.size > 32) this.#files.delete(this.#files.keys().next().value);
+  }
+}

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

@@ -26,7 +26,7 @@ import { workflowPolicy, repositoryChecks, planTool, currentPlan, PLAN_ENTRY, wo
 import { beforeDelegate } from './objections.mjs';
 import { HELPER_CALLS, HELPER_ROLES, helperRoles, helperPrompt, webPrompt, delegateDescription } from './helper-roles.mjs'; import { delegateParameters, delegateArgs, SPEC_PROMPT } from './helper-settlement.mjs';
 import { loadAgentResources } from './agent-skills.mjs';
-import { restorePermission, permissionSetter } from './permission.mjs';
+import { restorePermission, recordBypass, permissionSetter } from './permission.mjs';
 import { commandTools, servicesPrompt } from './command-tools.mjs'; import { attachMemory, memoryToolsFor, openRound, closeRound, prepareMemoryContext, trackMemoryLessons } from './memory.mjs';
 
 const PROVIDER = 'agent_watch_managed';
@@ -169,7 +169,7 @@ export class ManagedSession {
     self.session.managedExecution = true;
     self.turnRetry = enableCompanyTurnRetry(self.session, settings, self.studioLink);
     // The member's access for this conversation: ask first, or Bypass (permission.mjs).
-    self.permission = restorePermission(manager); self.session.managedSetPermission = permissionSetter(self, manager);
+    self.permission = restorePermission(manager); recordBypass(self, 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 where the Harness does not allow it
     self.session.managedFastServed = () => { const route = self.routes.get(self.modelRuntime); return route ? fastServed(route) : null; };

package/packages/piagent-core/managed/source-revert-requests.mjs

@@ -0,0 +1,21 @@
+import { createHash, randomBytes } from 'node:crypto';
+
+// Authorization lives outside JSON arguments. Model tools cannot manufacture
+// the object identity needed to obtain the boundary's key or observations.
+export class SourceRevertRequests {
+  #key = randomBytes(32).toString('hex');
+  #requests = new WeakMap();
+  get revision() { return `source-control.${createHash("sha256").update(this.#key).digest("hex")}`; }
+  request(request, binding) {
+    const args = { kind: 'source', request: structuredClone(request) };
+    this.#requests.set(args, binding);
+    return args;
+  }
+  consume(args, observations) {
+    if (args?.kind !== 'source') return undefined;
+    const binding = this.#requests.get(args); this.#requests.delete(args);
+    if (!binding || !binding.current() || !binding.idle()) throw new Error('source-session-unavailable');
+    return { identity: structuredClone(binding.identity), rawSessionId: binding.rawSessionId,
+      controlRevision: binding.controlRevision, confirmationKey: this.#key, observations: observations.snapshot() };
+  }
+}

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

@@ -0,0 +1,88 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { BWRAP, bubblewrapArgs, credentialFiles } from './linux-sandbox.mjs';
+import { companyTerminalRuntime } from './terminal-runtime.mjs';
+import { terminalChannel } from './terminal-channel.mjs';
+import { SEATBELT_TERMINAL_RULES, seatbeltTerminal } from './terminal-seatbelt.mjs';
+
+const worker = fileURLToPath(new URL('./terminal-worker.mjs', import.meta.url));
+const hash = file => createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+const inside = (file, root) => file === root || file.startsWith(root + path.sep);
+const dimensions = ({ cols, rows }) => Number.isInteger(cols) && cols >= 2 && cols <= 500 && Number.isInteger(rows) && rows >= 1 && rows <= 200;
+
+export class BoundaryTerminals {
+  #boundary; #runtime; #workerDigest; #entries = new Map(); #closed = false;
+  reasonCode = null;
+  constructor(boundary) {
+    this.#boundary = boundary;
+    try {
+      this.#runtime = companyTerminalRuntime();
+      if (inside(this.#runtime.root, boundary.cwd) || inside(worker, boundary.cwd)) throw Error('managed-terminal-runtime-overlap');
+      this.#workerDigest = hash(worker);
+    } catch (error) { this.reasonCode = /^managed-terminal-/.test(error.message) ? error.message : 'managed-terminal-runtime-invalid'; }
+  }
+  async open(size, emit) {
+    if (this.#closed) throw Error('managed-terminal-boundary-closed');
+    if (this.reasonCode) throw Error(this.reasonCode);
+    const boundary = this.#boundary;
+    if (!boundary.allowed.includes('bash')) throw Error('managed-terminal-permission-denied');
+    if (!dimensions(size)) throw Error('managed-terminal-invalid-size');
+    if (this.#entries.size >= 4) throw Error('managed-terminal-limit');
+    this.#runtime.assertCurrent();
+    if (hash(worker) !== this.#workerDigest) throw Error('managed-terminal-runtime-changed');
+    for (const [file, digest] of boundary.pins) if (hash(file) !== digest) throw Error('managed-runtime-changed');
+    const temporary = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'piagent-terminal-')));
+    fs.chmodSync(temporary, 0o700);
+    let channel;
+    try {
+      const home = path.join(temporary, 'home'), empty = path.join(temporary, 'empty');
+      fs.mkdirSync(home, { mode: 0o700 }); fs.writeFileSync(empty, '', { mode: 0o400 });
+      const env = Object.fromEntries(Object.entries(boundary.environment.offline)
+        .filter(([key]) => !/proxy/i.test(key) && !['NODE_OPTIONS', 'NODE_PATH', 'BASH_ENV', 'ENV', 'PIAGENT_TOOL_SCOPE'].includes(key))
+        .map(([key, value]) => [key, String(value).split(boundary.temporary).join(temporary)]));
+      Object.assign(env, { HOME: home, TMPDIR: temporary, TERM: 'xterm-256color', BASH_SILENCE_DEPRECATION_WARNING: '1',
+        PIAGENT_PROCESS_SCOPE: `${boundary.scope}:${randomUUID()}` });
+      // A separate temporary root excludes the boundary's package-proxy socket.
+      // Writes reach the project, its Git directories and the project's
+      // package caches, as the agent's own offline commands do.
+      if (!boundary.linux) channel = seatbeltTerminal({ entry: this.#runtime.entry, cwd: boundary.cwd, env, size, emit,
+        profile: boundary.terminalProfile(temporary) + SEATBELT_TERMINAL_RULES });
+      else {
+        const base = boundary.linuxBase;
+        const protectedPaths = (base.denied ?? []).filter(file => fs.existsSync(file))
+          .map(file => ({ path: file, directory: fs.statSync(file).isDirectory() }));
+        const args = bubblewrapArgs({ ...base, temporary, empty, network: false, proxySocket: null, docker: null,
+          toolchains: [...base.toolchains, this.#runtime.root],
+          credentials: [...credentialFiles([boundary.cwd, ...base.repository, ...base.references]), ...protectedPaths] });
+        // There is intentionally no alternative spawn path or injected host shell.
+        const child = spawn(BWRAP, [...args, boundary.node, worker, this.#runtime.entry,
+          fs.readlinkSync('/proc/self/ns/pid'), fs.readlinkSync('/proc/self/ns/net'), String(size.cols), String(size.rows)],
+        { cwd: boundary.cwd, detached: true, stdio: ['pipe', 'pipe', 'pipe'], env });
+        channel = terminalChannel(child, emit);
+      }
+      const id = randomUUID();
+      this.#entries.set(id, channel);
+      void channel.completed.then(() => { this.#entries.delete(id); fs.rmSync(temporary, { recursive: true, force: true }); }).catch(() => {});
+      await channel.initialized;
+      return { id, input(data) {
+        if (typeof data !== 'string' || Buffer.byteLength(data) > 16384) return Promise.reject(Error('managed-terminal-input-limit'));
+        return channel.execute({ kind: 'input', data });
+      }, resize(size) {
+        if (!dimensions(size)) return Promise.reject(Error('managed-terminal-invalid-size'));
+        return channel.execute({ kind: 'resize', cols: size.cols, rows: size.rows });
+      }, close: channel.close };
+    } catch (error) {
+      if (channel) await channel.close();
+      else fs.rmSync(temporary, { recursive: true, force: true });
+      throw error;
+    }
+  }
+  async dispose() {
+    this.#closed = true;
+    await Promise.all([...this.#entries.values()].map(channel => channel.close()));
+  }
+}

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

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

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

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

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

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

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

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