@piagent/platform 1.37.0 → 1.38.1

package/packages/piagent-core/managed/helper-run.mjs

@@ -15,6 +15,7 @@ import { HELPER_CALLS, HELPER_SETUP, READ_TOOLS, countedCheck } from './helper-r
 import { trackToolFailures } from './tool-failures.mjs';
 import { helperMemoryTools, renewer } from './memory.mjs';
 import { answeredSettlement, failedSettlement, settleHelper, OUTCOME_WORDS } from './helper-settlement.mjs';
+import { viaLink } from './studio-link.mjs';
 
 const textContent = result => result.content?.filter(p => p.type === 'text').map(p => p.text).join('\n') ?? '';
 // A helper failure that another model of its role may not have: the model's
@@ -53,7 +54,16 @@ export async function runHelper(managed, role, task, signal, harness, { verifyGr
     }
   }
 }
+// A helper's role closes through the same wait as the run's close: a passing
+// failure of Agent Watch's way to Studio is asked again. A close that still
+// fails leaves the helper's answer standing: the role closes with the run,
+// and the next helper of the role closes it first.
+export async function closeRole(managed, role) {
+  try { await viaLink(managed.studioLink, () => managed.broker.request('close', { role })); managed.unclosed?.delete(role); }
+  catch { (managed.unclosed ??= new Set()).add(role); }
+}
 async function helperAttempt(managed, role, task, signal, harness, snapshot, parts, { verifyGrant, patiently, title }) {
+  if (managed.unclosed?.has(role)) await closeRole(managed, role);
   // A long local tool step may outlive the main lease. Refresh authority
   // before asking for a child; the broker serializes concurrent renewals,
   // and main's own searches running beside it share managed renew.
@@ -143,6 +153,6 @@ async function helperAttempt(managed, role, task, signal, harness, snapshot, par
   finally {
     for (const session of sessions) session.dispose(); await boundary?.dispose();
     await settleHelper(managed, renew.lease, report); // with the role's current token, before it closes
-    await managed.broker.request('close', { role });
+    await closeRole(managed, role);
   }
 }

package/packages/piagent-core/managed/helper-settlement.mjs

@@ -78,8 +78,11 @@ export function failedSettlement(role, error, signal, spec = {}) {
     evidence: [], files: [], ...(Object.keys(spec ?? {}).length ? { spec } : {}) };
 }
 
-// Sends the report with the attempt's own token; never fails the helper.
-export async function settleHelper(managed, grant, report, fetchImpl = (...args) => globalThis.fetch(...args)) {
+// Sends the report with the attempt's own token; never fails the helper. A
+// passing failure (no answer, 5xx, 429) is sent again after these pauses:
+// Studio keeps one report per role, so a repeat is safe.
+const SETTLE_PAUSES_MS = [500, 2_000];
+export async function settleHelper(managed, grant, report, fetchImpl = (...args) => globalThis.fetch(...args), pauses = SETTLE_PAUSES_MS) {
   if (!report || !hasCapability(managed, 'managed.settle.v1')) return false;
   let held = null;
   try {
@@ -87,10 +90,18 @@ export async function settleHelper(managed, grant, report, fetchImpl = (...args)
     // current one (the attempt's first token may be stale by now).
     if (typeof grant === 'function') { held = await grant(); grant = held.grant; }
     if (!grant?.token) return false;
-    const response = await fetchImpl(`${managed.origin}/v1/managed/settle`, { method: 'POST', signal: AbortSignal.timeout(3_000),
-      headers: { Authorization: `Bearer ${grant.token}`, 'Content-Type': 'application/json', 'User-Agent': CLIENT_AGENT }, body: JSON.stringify(report) });
-    void response.body?.cancel?.().catch(() => {});
-    return response.ok;
+    for (let attempt = 0; ; attempt += 1) {
+      let status = 0;
+      try {
+        const response = await fetchImpl(`${managed.origin}/v1/managed/settle`, { method: 'POST', signal: AbortSignal.timeout(3_000),
+          headers: { Authorization: `Bearer ${grant.token}`, 'Content-Type': 'application/json', 'User-Agent': CLIENT_AGENT }, body: JSON.stringify(report) });
+        void response.body?.cancel?.().catch(() => {});
+        if (response.ok) return true;
+        status = response.status;
+      } catch { /* no answer */ }
+      if ((status && status < 500 && status !== 429) || attempt >= pauses.length) return false;
+      await new Promise(resolve => setTimeout(resolve, pauses[attempt]));
+    }
   } catch { return false; } finally { held?.release(); }
 }
 

package/packages/piagent-core/managed/ip-policy.mjs

@@ -0,0 +1,50 @@
+import net from 'node:net';
+
+// Whether an address is this machine, a private network or not routable on
+// the internet (IANA special-purpose registries). One classifier for every
+// outbound check (web-fetch, package-proxy). IPv6 forms that carry an IPv4
+// address (mapped, compatible, translated, NAT64, 6to4), dotted or hex, are
+// judged by that IPv4 address. Teredo, IPv6 outside 2000::/3, and anything
+// that does not parse count as private: fail closed.
+const V4_RANGES = [['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8], ['169.254.0.0', 16], ['172.16.0.0', 12],
+  ['192.0.0.0', 24], ['192.0.2.0', 24], ['192.88.99.0', 24], ['192.168.0.0', 16], ['198.18.0.0', 15], ['198.51.100.0', 24],
+  ['203.0.113.0', 24], ['224.0.0.0', 4], ['240.0.0.0', 4]].map(([base, bits]) => [v4Number(base), 2 ** (32 - bits)]);
+
+function v4Number(text) {
+  const parts = String(text).split('.');
+  if (parts.length !== 4 || !parts.every(part => /^(0|[1-9]\d{0,2})$/.test(part) && Number(part) <= 255)) return null;
+  return parts.reduce((value, part) => value * 256 + Number(part), 0);
+}
+const v4Private = value => V4_RANGES.some(([base, size]) => value >= base && value < base + size);
+
+// Eight 16-bit groups, or null: "::" expanded, a dotted IPv4 tail and a zone id accepted.
+function v6Groups(text) {
+  let value = String(text).toLowerCase().replace(/%[^%]*$/, '');
+  const tail = /:(\d+\.\d+\.\d+\.\d+)$/.exec(value);
+  if (tail) {
+    const v4 = v4Number(tail[1]); if (v4 === null) return null;
+    value = value.slice(0, -tail[1].length) + `${(v4 >>> 16).toString(16)}:${(v4 & 0xffff).toString(16)}`;
+  }
+  const halves = value.split('::');
+  if (halves.length > 2) return null;
+  const head = halves[0] ? halves[0].split(':') : [], rest = halves[1] ? halves[1].split(':') : [];
+  const missing = 8 - head.length - rest.length;
+  if (halves.length === 2 ? missing < 1 : missing !== 0) return null;
+  const groups = [...head, ...Array(halves.length === 2 ? missing : 0).fill('0'), ...rest];
+  return groups.every(group => /^[0-9a-f]{1,4}$/.test(group)) ? groups.map(group => parseInt(group, 16)) : null;
+}
+
+export function privateAddress(address) {
+  if (net.isIPv4(String(address))) { const v4 = v4Number(address); return v4 === null || v4Private(v4); }
+  const g = v6Groups(address);
+  if (!g) return true;
+  const zero = (from, to) => g.slice(from, to).every(group => group === 0);
+  const v4 = (high, low) => v4Private(high * 0x10000 + low);
+  if (zero(0, 5) && (g[5] === 0xffff || g[5] === 0)) return v4(g[6], g[7]); // ::ffff:0:0/96 mapped, ::/96 compatible (with :: and ::1)
+  if (zero(0, 4) && g[4] === 0xffff && g[5] === 0) return v4(g[6], g[7]); // ::ffff:0:0:0/96 translated
+  if (g[0] === 0x64 && g[1] === 0xff9b) return zero(2, 6) ? v4(g[6], g[7]) : true; // NAT64 64:ff9b::/96; 64:ff9b:1::/48 local
+  if (g[0] === 0x2002) return v4(g[1], g[2]); // 6to4
+  if ((g[0] & 0xe000) !== 0x2000) return true; // not global unicast: 100::/64, fc00::/7, fe80::/10, fec0::/10, ff00::/8, ...
+  return g[0] === 0x2001 && (g[1] === 0 || g[1] === 0xdb8 || (g[1] === 2 && g[2] === 0)) // Teredo, documentation, benchmarking
+    || (g[0] & 0xfff0) === 0x3ff0; // 3fff::/20 documentation
+}

package/packages/piagent-core/managed/memory-lessons.mjs

@@ -43,6 +43,9 @@ function passed(output) {
 // What an error says, without what varies between runs: numbers, ids,
 // temporary paths and quoted values.
 export const errorShape = text => clean(text,180).replace(/\/(?:tmp|var\/folders|private)\/\S*/g,'<tmp>').replace(/\b[0-9a-f]{8,}\b/gi,'<id>').replace(/\d+/g,'N').replace(/(["'`])[^"'`]{1,80}\1/g,'$1…$1');
+// A command without what varies between runs (temporary paths, ids,
+// numbers): \`curl service-a\` and \`curl service-b\` stay two commands.
+const commandShape = text => clean(text,160).replace(/\/(?:tmp|var\/folders|private)\/\S*/g,'<tmp>').replace(/\b[0-9a-f]{8,}\b/gi,'<id>').replace(/\d+/g,'N');
 const ERROR_LINE = /error|fail|exception|not found|no such|denied|refused|cannot|unknown (?:option|flag|command)|invalid|EADDRINUSE|ENOENT|EACCES/i;
 const MAX_LESSONS = 3;
 
@@ -55,7 +58,7 @@ export class CheckLessons {
   if(/managed[-_](?:tool[-_]cancelled|operation[-_]denied|helper[-_]cancelled)|Command aborted|Command timed out/i.test(output))return;
   const line=output.split('\n').find(l=>ERROR_LINE.test(l));
   if(!line)return;
-  const command=clean(call.command,160).split(' ')[0];
+  const command=commandShape(call.command);
   if(!command)return;
   const shape=errorShape(line), key=hash(command+'\0'+shape), seen=this.errors.get(key);
   if(!seen){if(this.errors.size>=40)this.errors.delete(this.errors.keys().next().value);this.errors.set(key,{id:event.toolCallId,command:clean(call.command,160),error:clean(line,180),done:false});return;}

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

@@ -78,7 +78,7 @@ export class TeamMemory {
     const scope = this.scope(), id = scopeID(scope);
     if (id !== this.scopeHash) {
       this.scopeHash = id; this.outbox = new MemoryOutbox(this.stateDir, scope, this.now);
-      this.protocol = 0; this.briefed = false; this.offUntil = 0; this.retain = true;
+      this.protocol = 0; this.briefed = false; this.offUntil = 0; this.retain = true; this.serves = new RoundServes(); // served under the old scope
     }
     return scope;
   }

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

@@ -3,6 +3,9 @@ import http from 'node:http';
 import net from 'node:net';
 import path from 'node:path';
 import { lookup } from 'node:dns/promises';
+import { privateAddress } from './ip-policy.mjs';
+
+export { privateAddress };
 
 // The package registries a company command reaches without asking: plain
 // bash has no network, except through this proxy, which the trusted runtime
@@ -10,6 +13,10 @@ import { lookup } from 'node:dns/promises';
 // HTTP to the hosts below and the member's own additions, on ports 443 and
 // 80 only, never to an IP literal or a name that resolves to this machine or
 // a private network (DNS rebinding), and connects to the address it checked.
+// With a company upstream proxy (HTTPS_PROXY) the name is still looked up and
+// checked here, and the upstream is asked for that checked address, never the
+// name, so it cannot resolve it elsewhere; a name this machine cannot look up
+// is refused (run_with_network still reaches it after the member approves).
 // Everything else is refused with 403 and remembered, so the command's
 // failure names the host and run_with_network (the member approves it).
 // Registries (and GitHub) take no upload without a token, and tokens stay
@@ -50,17 +57,8 @@ export function domainAllowed(host, domains) {
   return domains.some(rule => rule.startsWith('*.') ? name.endsWith(rule.slice(1)) && name.length > rule.length - 1 : name === rule);
 }
 
-// Addresses that are this machine, a private network or not routable.
-export function privateAddress(address) {
-  if (net.isIPv4(address)) {
-    const [a, b] = address.split('.').map(Number);
-    return a === 0 || a === 10 || a === 127 || (a === 100 && b >= 64 && b < 128) || (a === 169 && b === 254) || (a === 172 && b >= 16 && b < 32)
-      || (a === 192 && b === 168) || (a === 198 && (b === 18 || b === 19)) || a >= 224;
-  }
-  const v6 = address.toLowerCase();
-  if (v6.startsWith('::ffff:')) return privateAddress(v6.slice(7));
-  return v6 === '::' || v6 === '::1' || /^f[cd]/.test(v6) || /^fe[89ab]/.test(v6) || v6.startsWith('ff');
-}
+// host:port of a checked address, as a CONNECT target or URL host.
+const authority = ({ host, port }) => `${net.isIPv6(host) ? `[${host}]` : host}:${port}`;
 
 function upstreamProxy(env) {
   for (const name of ['HTTPS_PROXY', 'https_proxy']) {
@@ -101,7 +99,6 @@ export class PackageProxy {
   // The checked public address of an allowed host, or null.
   async #target(host, port) {
     if (!this.ports.has(port) || !domainAllowed(host, this.domains)) { this.#deny(host); return null; }
-    if (this.upstream) return { host, port };
     try {
       const addresses = await this.resolve(host);
       if (!addresses.length || addresses.some(entry => this.isPrivate(entry.address))) { this.#deny(host); return null; }
@@ -117,7 +114,7 @@ export class PackageProxy {
     upstream.setTimeout(10 * 60_000, () => upstream.destroy());
     upstream.once('connect', () => {
       if (this.upstream) {
-        upstream.write(`CONNECT ${match[1]}:${match[2]} HTTP/1.1\r\nHost: ${match[1]}:${match[2]}\r\n\r\n`);
+        upstream.write(`CONNECT ${authority(target)} HTTP/1.1\r\nHost: ${authority(target)}\r\n\r\n`);
         let reply = Buffer.alloc(0);
         const onData = chunk => {
           reply = Buffer.concat([reply, chunk]);
@@ -144,8 +141,9 @@ export class PackageProxy {
     const target = await this.#target(url.hostname, Number(url.port) || 80);
     if (!target) { response.writeHead(403, { 'X-Piagent-Proxy': 'domain-not-allowed', 'Content-Type': 'text/plain; charset=utf-8' }).end(`piagent: ${url.hostname} is not an allowed package registry\n`); return; }
     const headers = { ...request.headers, host: url.host }; delete headers['proxy-connection']; delete headers['proxy-authorization'];
+    const pinned = new URL(url); pinned.host = authority(target);
     const outgoing = http.request(this.upstream
-      ? { host: this.upstream.host, port: this.upstream.port, path: url.href, method: request.method, headers }
+      ? { host: this.upstream.host, port: this.upstream.port, path: pinned.href, method: request.method, headers }
       : { host: target.host, port: target.port, path: url.pathname + url.search, method: request.method, headers, servername: url.hostname }, incoming => {
       response.writeHead(incoming.statusCode ?? 502, incoming.headers); incoming.pipe(response);
     });

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

@@ -13,7 +13,7 @@ import { managedThinkingLevels, nearestLevel } from './capabilities.mjs';
 import { nativeManagedModel, isVendor, piProvider, studioAPI, studioPath } from './native-catalog.mjs';
 import { fetchOriginTool } from './repository-operation.mjs';
 import { describeFailure, failureCode, failureText } from '../runtime/managed-failure.mjs';
-import { enableCompanyTurnRetry, wrapRoleStreams, conversationSession } from './request-stream.mjs'; import { StudioLink, viaLink } from './studio-link.mjs';
+import { enableCompanyTurnRetry, wrapRoleStreams, conversationSession } from './request-stream.mjs'; import { StudioLink, closeRun } from './studio-link.mjs';
 import { trackToolFailures } from './tool-failures.mjs';
 import { fastServed, fastSetter, fastState, recordFast, restoreFast } from './fast-mode.mjs';
 import { runHelper } from './helper-run.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; };
@@ -296,15 +296,14 @@ export class ManagedSession {
             // the newest version the broker advertises.
             const features = self.manifest.broker_features ?? [];
             const process = self.run && features.includes('process') ? self.run.report(currentPlan(manager), features.includes('process-v3') ? 3 : features.includes('process-v2') ? 2 : 1) : null;
-            try { await viaLink(self.studioLink, () => self.broker.request('close', process ? { process } : {}), { conversation: conversationSession(self), runId: self.grant.run_id }); } // only a refused report closes again without it; an unconfirmed close fails the turn
-            catch (error) { if (!process || String(error?.message) !== 'managed-broker:invalidResponse') throw error; await viaLink(self.studioLink, () => self.broker.request('close'), { conversation: conversationSession(self), runId: self.grant.run_id }); }
-            manager.appendCustomEntry('agent-watch-run', { run_id: self.grant.run_id, state: 'closed' });
+            // A close Studio may not have had stays "active" here (closeRun).
+            if (await closeRun(self.studioLink, self.broker, features, process, { conversation: conversationSession(self), runId: self.grant.run_id })) manager.appendCustomEntry('agent-watch-run', { run_id: self.grant.run_id, state: 'closed' });
           }
         // A run that could not be closed (the network or Agent Watch went away)
         // ends the turn as failed; the run stays "active" here, so reopening
         // the conversation recovers or abandons it.
         } catch (error) { round.closeFailed = failureCode(failureText(error)) || 'close_failed'; }
-        finally { self.grant = null; self.run = null; self.preflight = null; }
+        finally { self.grant = null; self.run = null; self.preflight = null; self.unclosed = null; }
       }
     };
     self.session.prompt = async (text, options) => {

package/packages/piagent-core/managed/skill-feedback.mjs

@@ -5,9 +5,17 @@
 // Piagent never edits a skill itself and makes no model call for this.
 import fs from 'node:fs';
 import path from 'node:path';
+import { createHash } from 'node:crypto';
 
 const MIN_FAILURES = 3, MIN_SHARE = 0.5, KEEP = 10, REPROPOSE_MS = 7 * 86400_000;
-const safeName = name => String(name).replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 80);
+// One file name per skill name: a name with other characters (or capitals,
+// on a case-insensitive disk) gets a digest of itself, so \`a/b\` and \`a_b\`
+// keep their own counts.
+const safeName = name => {
+  name = String(name);
+  if (/^[a-z0-9_.-]{1,80}$/.test(name) && !/^\.+$/.test(name)) return name;
+  return `${name.replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 60)}~${createHash('sha256').update(name).digest('hex').slice(0, 12)}`;
+};
 
 export class SkillFeedback {
   // A managed round's tracker, when the conversation has skills.

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/studio-link.mjs

@@ -269,3 +269,19 @@ export async function viaLink(link, ask, { conversation = null, runId = null } =
     }
   }
 }
+
+// Closing a round's run, asked again through the link. Only a refused report
+// closes again without it; an unconfirmed close throws (the turn fails). An
+// Agent Watch without close-retry forgets a run whose close failed, so asking
+// again "succeeds" without reaching Studio: false then, and the run stays
+// "active" for the runtime (reopening recovers or abandons it).
+export async function closeRun(link, broker, features, process, where) {
+  let unsent = false;
+  const close = args => viaLink(link, () => broker.request('close', args).catch(error => {
+    if (!features.includes('close-retry') && String(error?.message) !== 'managed-broker:invalidResponse') unsent = true;
+    throw error;
+  }), where);
+  try { await close(process ? { process } : {}); }
+  catch (error) { if (!process || String(error?.message) !== 'managed-broker:invalidResponse') throw error; await close(); }
+  return !unsent;
+}

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()));
+  }
+}