@commonlyai/cli 0.1.182 → 0.1.184

package/node_modules/@commonlyai/seats/src/record/format.js

@@ -371,7 +371,13 @@ const CHECKS = {
     optionalArgsDigest(data, 'tool.call');
     return data;
   },
-  'credential.granted': (data) => ({ ...data, names: envNames(data.names ?? [], 'credential.granted.names') }),
+  'credential.granted': (data) => {
+    const names = envNames(data.names ?? [], 'credential.granted.names');
+    if (data.injected === undefined) return { ...data, names };
+    const injected = envNames(data.injected, 'credential.granted.injected');
+    if (!injected.every((name) => names.includes(name))) fail('credential.granted.injected must be a subset of names');
+    return { ...data, names, injected };
+  },
   'credential.denied': (data) => {
     envNames([data.name], 'credential.denied.name');
     return data;

package/node_modules/@commonlyai/seats/src/trace/events.js

@@ -23,8 +23,8 @@ export const EVENT_TYPES = Object.freeze([
   'usage', // { inputTokens?, outputTokens?, totalTokens?, cost? }  null-not-zero when unknown
   'liveness.stalled', // { idleMs, windowMs }
   'liveness.recovery', // { action: 'cancel'|'kill'|'retry', attempt }
-  'credential.granted', // { names: [...] }  names only, never values
-  'credential.denied', // { name, reason?: 'not_granted'|'unresolved'|'too_short' }
+  'credential.granted', // { names: [...], injected?: [...] }  names only, never values
+  'credential.denied', // { name, reason?: 'not_granted'|'unresolved'|'too_short'|'no_upstream' }
   'process.exited', // { code, signal }
   // Record kinds with no earlier trace name (docs/record-v1.md has the full data).
   'task.claimed', // { leaseUntil? }  mirrors the board's claim; the board stays the source of truth

package/node_modules/@commonlyai/seats/src/valet/env.js

@@ -19,6 +19,7 @@ import { traceOf } from '../trace/events.js';
 import { runFailure } from '../failures.js';
 import { MIN_CREDENTIAL_LENGTH } from '../upstream-refusal.js';
 import { validateGrant } from './grant.js';
+import { startProviderProxy } from '../wire/provider-proxy.js';
 
 // Same spirit as the goose adapter's SAFE_ENV: locale, terminal and TLS trust
 // only. USER/LOGNAME are left out on purpose; they name the account whose
@@ -104,8 +105,8 @@ const grantIssued = (meta) => {
 };
 
 /**
- * prepareRunEnv({ grant, baseEnv, resolveSecret, root?, require?, trace?, ctx?, grantMeta? })
- *   → { env, home, cleanup, granted: [names], grantId? }
+ * prepareRunEnv({ grant, baseEnv, resolveSecret, root?, require?, trace?, ctx?, grantMeta?, upstreams? })
+ *   → { env, home, cleanup, granted: [names], injected: { NAME: { baseURL, wire } }, grantId? }
  *
  * `require` lists credential names the adapter cannot run without; one the
  * grant does not name fails the run as credential_denied before any spawn.
@@ -114,14 +115,25 @@ const grantIssued = (meta) => {
  * silently lacks its key fails later and less legibly, and a value that short
  * would slip past the refusal-text reader's redaction.
  *
+ * A credential the grant marks `inject: true` never reaches the env. The host
+ * names its provider in `upstreams[NAME]` ({ baseURL, wire }, wire defaulting
+ * to openai-chat); the run gets a loopback provider proxy holding the value in
+ * memory, env[NAME] becomes that proxy's token, and `injected[NAME].baseURL`
+ * is where the host points the CLI. cleanup() closes the proxies. One with no
+ * upstream fails as credential_denied (no_upstream) before it is resolved.
+ * The proxy listens on 127.0.0.1, so a run without the host's network
+ * (bwrap --unshare-net) cannot reach it yet.
+ *
  * Events go to `trace`, else ctx.trace: grant.issued (only with grantMeta,
- * first), then credential.granted {names} or credential.denied {name, reason}.
+ * first), then credential.granted {names, injected?} or credential.denied
+ * {name, reason}. `injected` lists the names held by a proxy; the rest of
+ * `names` are held by the run.
  * Values never enter an event or a message, and a hook that offers
- * redact(values) is handed the resolved values so the record can scrub them
- * out of agent text too.
+ * redact(values) is handed the resolved values and each proxy token, so the
+ * record can scrub them out of agent text too.
  */
 export const prepareRunEnv = async ({
-  grant, baseEnv = {}, resolveSecret, root, require: required = [], trace, ctx, grantMeta,
+  grant, baseEnv = {}, resolveSecret, root, require: required = [], trace, ctx, grantMeta, upstreams = {},
 } = {}) => {
   const valid = validateGrant(grant);
   const hook = trace && typeof trace.emit === 'function' ? trace : traceOf(ctx);
@@ -132,6 +144,7 @@ export const prepareRunEnv = async ({
     not_granted: 'is not in the run grant',
     unresolved: 'could not be resolved',
     too_short: `resolved to a value shorter than ${MIN_CREDENTIAL_LENGTH} characters`,
+    no_upstream: 'is marked inject, but the host named no upstream for it',
   };
   const deny = (name, reason, values) => {
     hook.emit('credential.denied', { name, reason });
@@ -143,11 +156,18 @@ export const prepareRunEnv = async ({
   if (missing) throw deny(missing, 'not_granted', []);
 
   const { home, dirs } = await makeHome(root);
-  const cleanup = () => rm(home, { recursive: true, force: true });
+  const proxies = [];
+  const cleanup = async () => {
+    await Promise.all(proxies.splice(0).map((proxy) => proxy.close()));
+    await rm(home, { recursive: true, force: true });
+  };
   const env = { ...pickBaseEnv(baseEnv, realHomes), HOME: home, ...dirs };
   const values = [];
+  const injected = {};
   try {
     for (const spec of valid.credentials) {
+      const upstream = spec.inject ? upstreams[spec.name] : undefined;
+      if (spec.inject && !upstream) throw deny(spec.name, 'no_upstream', values);
       let value;
       // A resolver's error text may quote the secret it failed on; drop it.
       try { value = await resolveOne(spec, { baseEnv, resolveSecret }); } catch { value = undefined; }
@@ -156,14 +176,26 @@ export const prepareRunEnv = async ({
       // refusal-text reader would not redact it. Refuse it here, before spawn.
       if (value.length < MIN_CREDENTIAL_LENGTH) throw deny(spec.name, 'too_short', values);
       values.push(value);
-      env[spec.name] = value;
+      if (upstream) {
+        const wire = upstream.wire ?? 'openai-chat';
+        const proxy = await startProviderProxy({
+          provider: { baseURL: upstream.baseURL }, keyMaterial: value, wire, adapterLabel: 'Valet',
+        });
+        proxies.push(proxy);
+        env[spec.name] = proxy.token;
+        injected[spec.name] = { baseURL: proxy.baseURL, wire };
+      } else {
+        env[spec.name] = value;
+      }
     }
   } catch (error) {
     await cleanup();
     throw error;
   }
-  if (typeof hook.redact === 'function') hook.redact(values);
+  // A proxy token authorizes provider calls until cleanup, so the record scrubs it too.
+  if (typeof hook.redact === 'function') hook.redact([...values, ...proxies.map((proxy) => proxy.token)]);
   const names = valid.credentials.map((c) => c.name);
-  hook.emit('credential.granted', { names });
-  return { env, home, cleanup, granted: names, ...(issued ? { grantId: issued.grantId } : {}) };
+  const proxied = Object.keys(injected);
+  hook.emit('credential.granted', proxied.length ? { names, injected: proxied } : { names });
+  return { env, home, cleanup, granted: names, injected, ...(issued ? { grantId: issued.grantId } : {}) };
 };

package/node_modules/@commonlyai/seats/src/valet/grant.js

@@ -3,7 +3,7 @@
  * and which tool calls it may make without asking, only after asking, or never.
  *
  *   {
- *     credentials: [{ name: 'OPENAI_API_KEY', from: 'env'|'file'|'resolver', ref? }],
+ *     credentials: [{ name: 'OPENAI_API_KEY', from: 'env'|'file'|'resolver', ref?, inject? }],
  *     tools: { allow: [pattern], ask: [pattern], deny: [pattern] },
  *   }
  *
@@ -11,6 +11,10 @@
  * path in `ref`; `from: 'resolver'` asks the host's resolveSecret(name, spec),
  * with `ref` as an opaque hint for it.
  *
+ * `inject: true` keeps the value out of the run: its env gets a per-run proxy
+ * token under the name instead, and a loopback provider proxy adds the real
+ * key to outbound requests. Default false: the run holds the value.
+ *
  * A tool pattern is `<kind>` or `<kind>:<title glob>`, where kind is one of
  * ACP's ToolKind values or `*`. `execute` matches every execute call;
  * `execute:git status*` matches execute calls whose title starts that way;
@@ -61,8 +65,8 @@ const parsePattern = (pattern, where) => {
 const validateCredential = (credential, index, seen) => {
   const where = `credentials[${index}]`;
   if (!isPlainObject(credential)) fail(`${where} must be an object`);
-  refuseUnknownKeys(credential, ['name', 'from', 'ref'], `${where}.`);
-  const { name, from, ref } = credential;
+  refuseUnknownKeys(credential, ['name', 'from', 'ref', 'inject'], `${where}.`);
+  const { name, from, ref, inject } = credential;
   if (typeof name !== 'string' || !ENV_NAME.test(name)) fail(`${where}.name must be an ENV_NAME (A-Z, 0-9, _)`);
   if (RESERVED_NAME.test(name)) fail(`${where}.name ${name} is reserved for the run env`);
   if (seen.has(name)) fail(`${where}.name ${name} is granted twice`);
@@ -71,7 +75,8 @@ const validateCredential = (credential, index, seen) => {
   if (ref !== undefined && (typeof ref !== 'string' || !ref)) fail(`${where}.ref must be a non-empty string`);
   if (from === 'env' && ref !== undefined && !ENV_NAME.test(ref)) fail(`${where}.ref must be an ENV_NAME for from: env`);
   if (from === 'file' && (ref === undefined || !ref.startsWith('/'))) fail(`${where}.ref must be an absolute path for from: file`);
-  return Object.freeze(ref === undefined ? { name, from } : { name, from, ref });
+  if (inject !== undefined && typeof inject !== 'boolean') fail(`${where}.inject must be true or false`);
+  return Object.freeze({ name, from, ...(ref === undefined ? {} : { ref }), ...(inject ? { inject } : {}) });
 };
 
 /** Validate and freeze a grant. Throws on the first problem; never repairs one. */

package/node_modules/@commonlyai/seats/src/wire/provider-proxy.js

@@ -1,5 +1,6 @@
 import { Transform } from 'node:stream';
-/** The per-spawn loopback proxy shared by OpenAI-compatible CLI adapters. */
+import { StringDecoder } from 'node:string_decoder';
+/** The per-spawn loopback proxy that holds a provider key for a CLI (OpenAI chat, Anthropic Messages, OpenAI Responses). */
 import { randomBytes, timingSafeEqual } from 'crypto';
 import { constants as fsConstants, realpathSync } from 'fs';
 import { createServer, request as httpRequest } from 'http';
@@ -40,6 +41,71 @@ export const redactProviderMaterial = (material) => {
   });
 };
 
+const MAX_PINNED_REQUEST_BYTES = 8 * 1024 * 1024;
+const MAX_PINNED_RESPONSE_BYTES = 16 * 1024 * 1024;
+
+/**
+ * Checks that every completion an upstream serves names the pinned model.
+ * SSE is checked line by line, and nothing is released until a line has named
+ * the pinned model; after that only checked lines are released, so a chunk
+ * naming another model never reaches the CLI. Any other body is held whole and
+ * released only after its `model` is checked. A body that names no model is
+ * unverified, which counts as a failure: the pin is only as good as the check.
+ */
+const servedModelCheck = ({ pinned, stream, onServed }) => {
+  // A chunk boundary can fall inside a multi-byte character; the decoder
+  // carries the partial bytes into the next chunk instead of mangling both.
+  const decoder = new StringDecoder('utf8');
+  let pending = '';
+  let held = '';
+  let named = false;
+  let size = 0;
+  const check = (value) => {
+    if (typeof value !== 'string') return;
+    named = true;
+    onServed(value);
+    if (value !== pinned) throw new Error(`served model ${JSON.stringify(value)} is not the pinned ${JSON.stringify(pinned)}`);
+  };
+  const checkLine = (line) => {
+    const data = /^data:\s?(.*)$/.exec(line.replace(/\r$/, ''))?.[1];
+    if (data === undefined || data.trim() === '[DONE]' || !data.trim()) return;
+    let parsed;
+    try { parsed = JSON.parse(data); } catch { return; }
+    check(parsed?.model);
+  };
+  return new Transform({
+    transform(chunk, _encoding, done) {
+      size += chunk.length;
+      if (size > MAX_PINNED_RESPONSE_BYTES) { done(new Error('provider response exceeded the pinned-model check limit')); return; }
+      pending += decoder.write(chunk);
+      if (!stream) { done(); return; }
+      const end = pending.lastIndexOf('\n');
+      if (end < 0) { done(); return; }
+      const complete = pending.slice(0, end + 1);
+      pending = pending.slice(end + 1);
+      try { complete.split('\n').forEach(checkLine); } catch (error) { done(error); return; }
+      held += complete;
+      if (!named) { done(); return; }
+      const release = held;
+      held = '';
+      done(null, release);
+    },
+    flush(done) {
+      pending += decoder.end();
+      try {
+        if (stream) checkLine(pending);
+        else {
+          let parsed;
+          try { parsed = JSON.parse(pending); } catch { parsed = null; }
+          check(parsed?.model);
+        }
+        if (!named) throw new Error(`provider response named no model; the pinned ${JSON.stringify(pinned)} cannot be verified`);
+      } catch (error) { done(error); return; }
+      done(null, held + pending);
+    },
+  });
+};
+
 const isPathWithin = (parent, candidate) => {
   const fromParent = relative(parent, candidate);
   return fromParent === '' || (fromParent !== '..'
@@ -101,9 +167,34 @@ const readProviderKey = async (keyFile, adapterLabel) => {
   }
 };
 
+// The routes a CLI on each wire may call, relative to the configured base
+// path, and the header the real key goes out in. Anything else is refused.
+const WIRES = Object.freeze({
+  'openai-chat': { routes: [['POST', 'chat/completions'], ['GET', 'models']], auth: 'bearer' },
+  'anthropic-messages': {
+    routes: [['POST', 'v1/messages'], ['POST', 'v1/messages/count_tokens'], ['GET', 'v1/models']],
+    auth: 'x-api-key',
+  },
+  'openai-responses': { routes: [['POST', 'responses'], ['GET', 'models']], auth: 'bearer' },
+});
+export const PROVIDER_WIRES = Object.freeze(Object.keys(WIRES));
+
+const presents = (value, expected) => {
+  const supplied = Buffer.from(typeof value === 'string' ? value : '');
+  return supplied.length === expected.length && timingSafeEqual(supplied, expected);
+};
+
 export const startProviderProxy = async ({
-  provider, keyFile, keyMaterial, tokenFile, socketPath, isolatedPort, adapterLabel = 'OpenCode',
+  provider, keyFile, keyMaterial, tokenFile, socketPath, isolatedPort, adapterLabel = 'OpenCode', wire = 'openai-chat',
+  // When set, every completion must request this model and be served by it.
+  pinnedModel,
 }) => {
+  const wireSpec = WIRES[wire];
+  if (!wireSpec) throw new Error(`${adapterLabel} provider wire must be one of ${PROVIDER_WIRES.join(', ')}`);
+  if (pinnedModel !== undefined && (typeof pinnedModel !== 'string' || !pinnedModel.trim())) {
+    throw new Error(`${adapterLabel} pinnedModel must be a non-empty string`);
+  }
+  const modelState = { requested: new Set(), served: new Set(), refused: 0, failures: [] };
   const upstream = new URL(provider.baseURL);
   if (socketPath && (!isAbsolute(socketPath)
     || !Number.isInteger(isolatedPort) || isolatedPort < 1 || isolatedPort > 65535)) {
@@ -117,8 +208,13 @@ export const startProviderProxy = async ({
   const upstreamKey = keyMaterial === undefined ? await readProviderKey(keyFile, adapterLabel) : keyMaterial;
   if (typeof upstreamKey !== 'string' || !upstreamKey || /[\r\n]/.test(upstreamKey)) throw new Error('Invalid provider key');
   const proxyToken = randomBytes(32).toString('base64url');
-  await writeFile(tokenFile, proxyToken, { encoding: 'utf8', mode: 0o600 });
-  await chmod(tokenFile, 0o600);
+  // A caller that hands the token to its child in memory needs no file.
+  if (tokenFile) {
+    await writeFile(tokenFile, proxyToken, { encoding: 'utf8', mode: 0o600 });
+    await chmod(tokenFile, 0o600);
+  }
+  const bearerToken = Buffer.from(`Bearer ${proxyToken}`);
+  const bareToken = Buffer.from(proxyToken);
 
   const logRefusedRequest = (method, requestPath) => {
     let normalizedPath = '/';
@@ -132,29 +228,34 @@ export const startProviderProxy = async ({
     process.stderr.write(`[${adapterLabel.toLowerCase()}] provider proxy refused ${safeMethod} ${normalizedPath}\n`);
   };
 
+  // A refusal answers before the request body has been read. A keep-alive
+  // client that reuses that socket can have its next request reset, so every
+  // refusal on every wire also closes the connection.
+  const refuse = (incoming, outgoing, status, headers = {}, body = undefined) => {
+    incoming.resume();
+    outgoing.writeHead(status, { ...headers, connection: 'close' });
+    outgoing.end(body);
+  };
+
   const server = createServer((incoming, outgoing) => {
-    const supplied = Buffer.from(incoming.headers.authorization || '');
-    const expected = Buffer.from(`Bearer ${proxyToken}`);
-    if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected)) {
-      incoming.resume();
-      outgoing.writeHead(401).end();
+    // Anthropic clients send their key as x-api-key, the others as a Bearer.
+    if (!presents(incoming.headers.authorization, bearerToken)
+      && !presents(incoming.headers['x-api-key'], bareToken)) {
+      refuse(incoming, outgoing, 401);
       return;
     }
     if (!['GET', 'POST'].includes(incoming.method || '')) {
-      incoming.resume();
-      outgoing.writeHead(405).end();
+      refuse(incoming, outgoing, 405);
       return;
     }
     const rejectRoute = (path) => {
       logRefusedRequest(incoming.method, path);
-      incoming.resume();
-      outgoing.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
-      outgoing.end(`Unsupported provider request: ${incoming.method || 'UNKNOWN'} ${path}`);
+      refuse(incoming, outgoing, 403, { 'content-type': 'text/plain; charset=utf-8' },
+        `Unsupported provider request: ${incoming.method || 'UNKNOWN'} ${path}`);
     };
     const rejectBadRequest = () => {
       logRefusedRequest(incoming.method, incoming.url);
-      incoming.resume();
-      outgoing.writeHead(400).end();
+      refuse(incoming, outgoing, 400);
     };
 
     let target;
@@ -169,8 +270,8 @@ export const startProviderProxy = async ({
         return;
       }
       // The CLI owns this local request path, so never use it as an outbound
-      // URL. The OpenAI-compatible chat provider needs only these fixed routes;
-      // parse the incoming URL against a loopback sentinel, then select a
+      // URL. Each wire needs only the fixed routes in WIRES; parse the
+      // incoming URL against a loopback sentinel, then select a
       // constant endpoint after matching the configured base path exactly.
       // This keeps a CLI request from turning the proxy into an arbitrary
       // path/URL fetcher (including paths on a local provider host).
@@ -180,17 +281,13 @@ export const startProviderProxy = async ({
         return;
       }
       const configuredPath = basePath === '/' ? '' : basePath;
-      let endpoint;
-      if (incoming.method === 'POST'
-        && requested.pathname === `${configuredPath}/chat/completions`) {
-        endpoint = 'chat/completions';
-      } else if (incoming.method === 'GET'
-        && requested.pathname === `${configuredPath}/models`) {
-        endpoint = 'models';
-      } else {
+      const route = wireSpec.routes.find(([method, path]) => incoming.method === method
+        && requested.pathname === `${configuredPath}/${path}`);
+      if (!route) {
         rejectRoute(requested.pathname);
         return;
       }
+      const endpoint = route[1];
       target = {
         path: `${configuredPath}/${endpoint}`,
         protocol: upstream.protocol,
@@ -209,45 +306,108 @@ export const startProviderProxy = async ({
         'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade',
         'x-api-key',
       ].includes(name.toLowerCase())));
-    headers.authorization = `Bearer ${upstreamKey}`;
+    if (wireSpec.auth === 'x-api-key') headers['x-api-key'] = upstreamKey;
+    else headers.authorization = `Bearer ${upstreamKey}`;
     headers.host = target.host;
     headers['accept-encoding'] = 'identity';
-    const request = (target.protocol === 'https:' ? httpsRequest : httpRequest)({
-      protocol: target.protocol,
-      hostname: target.hostname,
-      port: target.port,
-      path: target.path,
-      method: incoming.method,
-      headers,
-    }, (response) => {
-      if (response.statusCode >= 300 && response.statusCode < 400) {
-        response.resume();
-        outgoing.writeHead(502).end('Provider redirects are not supported');
-        return;
-      }
-      if (response.headers['content-encoding'] && response.headers['content-encoding'] !== 'identity') {
-        response.resume(); outgoing.writeHead(502).end('Compressed provider responses are not supported'); return;
-      }
-      const responseHeaders = Object.fromEntries(Object.entries(response.headers)
-        .filter(([name]) => ![
-          'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization',
-          'te', 'trailer', 'transfer-encoding', 'upgrade',
-        ].includes(name.toLowerCase())));
-      delete responseHeaders['content-length'];
-      for (const [name, value] of Object.entries(responseHeaders)) {
-        if (typeof value === 'string') responseHeaders[name] = value.split(upstreamKey).join('[redacted]');
-        else if (Array.isArray(value)) responseHeaders[name] = value.map((entry) => entry.split(upstreamKey).join('[redacted]'));
+    const pinned = pinnedModel !== undefined && target.path.endsWith('/chat/completions');
+    const forward = (body) => {
+      let streamed = false;
+      if (body) {
+        headers['content-length'] = String(body.length);
+        try { streamed = JSON.parse(body.toString('utf8'))?.stream === true; } catch { /* checked before forward */ }
       }
-      outgoing.writeHead(response.statusCode || 502, responseHeaders);
-      response.pipe(redactProviderMaterial(upstreamKey)).pipe(outgoing);
+      const request = (target.protocol === 'https:' ? httpsRequest : httpRequest)({
+        protocol: target.protocol,
+        hostname: target.hostname,
+        port: target.port,
+        path: target.path,
+        method: incoming.method,
+        headers,
+      }, (response) => {
+        if (response.statusCode >= 300 && response.statusCode < 400) {
+          response.resume();
+          outgoing.writeHead(502).end('Provider redirects are not supported');
+          return;
+        }
+        if (response.headers['content-encoding'] && response.headers['content-encoding'] !== 'identity') {
+          response.resume(); outgoing.writeHead(502).end('Compressed provider responses are not supported'); return;
+        }
+        const responseHeaders = Object.fromEntries(Object.entries(response.headers)
+          .filter(([name]) => ![
+            'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization',
+            'te', 'trailer', 'transfer-encoding', 'upgrade',
+          ].includes(name.toLowerCase())));
+        delete responseHeaders['content-length'];
+        for (const [name, value] of Object.entries(responseHeaders)) {
+          if (typeof value === 'string') responseHeaders[name] = value.split(upstreamKey).join('[redacted]');
+          else if (Array.isArray(value)) responseHeaders[name] = value.map((entry) => entry.split(upstreamKey).join('[redacted]'));
+        }
+        const ok = response.statusCode >= 200 && response.statusCode < 300;
+        if (!pinned || !ok) {
+          outgoing.writeHead(response.statusCode || 502, responseHeaders);
+          response.pipe(redactProviderMaterial(upstreamKey)).pipe(outgoing);
+          return;
+        }
+        const sse = streamed || /text\/event-stream/i.test(String(response.headers['content-type'] || ''));
+        const check = servedModelCheck({
+          pinned: pinnedModel, stream: sse, onServed: (served) => modelState.served.add(served),
+        });
+        const fail = (error) => {
+          modelState.failures.push(error.message);
+          process.stderr.write(`[${adapterLabel.toLowerCase()}] provider proxy: ${error.message}\n`);
+          response.destroy();
+          if (!outgoing.headersSent) outgoing.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' }).end('Served model check failed');
+          else outgoing.destroy();
+        };
+        check.on('error', fail);
+        // A stream's headers go out at once; a whole body waits for its check.
+        if (sse) outgoing.writeHead(response.statusCode, responseHeaders);
+        else check.once('data', () => { if (!outgoing.headersSent) outgoing.writeHead(response.statusCode, responseHeaders); });
+        response.pipe(check).pipe(redactProviderMaterial(upstreamKey)).pipe(outgoing);
+      });
+      request.on('error', () => {
+        if (!outgoing.headersSent) outgoing.writeHead(502);
+        outgoing.end('Provider request failed');
+      });
+      outgoing.on('close', () => request.destroy());
+      incoming.on('aborted', () => request.destroy());
+      if (body) request.end(body);
+      else incoming.pipe(request);
+    };
+    if (!pinned) {
+      forward(null);
+      return;
+    }
+    // A pinned proxy reads the request first: a completion for any other model
+    // is refused here, before the provider bills it.
+    const chunks = [];
+    let size = 0;
+    incoming.on('data', (chunk) => {
+      size += chunk.length;
+      if (size <= MAX_PINNED_REQUEST_BYTES) chunks.push(chunk);
     });
-    request.on('error', () => {
-      if (!outgoing.headersSent) outgoing.writeHead(502);
-      outgoing.end('Provider request failed');
+    incoming.on('end', () => {
+      if (size > MAX_PINNED_REQUEST_BYTES) { outgoing.writeHead(413).end(); return; }
+      const body = Buffer.concat(chunks);
+      let requested;
+      try { requested = JSON.parse(body.toString('utf8'))?.model; } catch { requested = undefined; }
+      if (requested !== pinnedModel) {
+        modelState.refused += 1;
+        process.stderr.write(`[${adapterLabel.toLowerCase()}] provider proxy refused a completion for an unpinned model\n`);
+        outgoing.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
+        outgoing.end(`This seat is pinned to ${pinnedModel}`);
+        return;
+      }
+      modelState.requested.add(requested);
+      forward(body);
     });
-    outgoing.on('close', () => request.destroy());
-    incoming.on('aborted', () => request.destroy());
-    incoming.pipe(request);
+  });
+
+  // A WebSocket client (codex on the Responses wire) falls back to HTTP SSE on
+  // 426. Nothing is relayed over an upgrade, so no token check is needed first.
+  server.on('upgrade', (_incoming, socket) => {
+    socket.end('HTTP/1.1 426 Upgrade Required\r\nconnection: close\r\ncontent-length: 0\r\n\r\n');
   });
 
   await new Promise((resolve, reject) => {
@@ -271,9 +431,18 @@ export const startProviderProxy = async ({
   const proxyBaseURL = new URL(upstream.pathname, `http://127.0.0.1:${port}`).toString();
   return {
     baseURL: proxyBaseURL,
+    token: proxyToken,
     tokenFile,
     socketPath,
     port,
+    /** The pin's verdict so far: what was asked for, what was served, and what failed. */
+    modelCheck: () => ({
+      pinned: pinnedModel ?? null,
+      requested: [...modelState.requested],
+      served: [...modelState.served],
+      refused: modelState.refused,
+      failures: [...modelState.failures],
+    }),
     close: () => new Promise((resolve) => {
       server.close(async () => {
         if (socketPath) await unlink(socketPath).catch(() => {});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.182",
+  "version": "0.1.184",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

package/src/lib/adapters/dsh.js

@@ -1,12 +1,28 @@
 import { observeSpawn } from '../runtime-observation.js';
-/** DeepSeek Harness 0.2.1-rc.2, private seats only. Configuration is per spawn. */
+/**
+ * DeepSeek Harness 0.2.1-rc.2, private seats only. Configuration is per spawn.
+ *
+ * A seat runs plain, or confined: `sandbox: { mode: 'workspace', network:
+ * { policy: 'restricted' } }` runs dsh inside one Seatbelt profile that writes
+ * only the workspace and the seat's home, reaches only three loopback ports
+ * (the provider proxy, the Commonly instance relay and the GitHub egress
+ * proxy), and cannot reach the Security services the keychain sits behind.
+ * The provider proxy is pinned to the seat's model and checks the model each
+ * response names. dsh's own sandbox is turned off inside it, because a second
+ * Seatbelt cannot be applied under the first.
+ */
+import { spawnInOwnGroup, wantsOwnProcessGroup } from '@commonlyai/seats/process-group';
 import { requireSeatModel } from './seat-model.js';
 import { spawn as childSpawn, spawnSync } from 'child_process';
 import { createHash } from 'crypto';
-import { existsSync } from 'fs';
+import { existsSync, realpathSync } from 'fs';
 import { chmod, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'fs/promises';
 import { homedir, tmpdir } from 'os';
-import { basename, join } from 'path';
+import { basename, delimiter, isAbsolute, join, sep } from 'path';
+import { startEgressProxy } from '../egress-proxy.js';
+import { startInstanceProxy } from '../instance-proxy.js';
+import { prepareMcpSpawn, selectedMcpVersionDir } from '../mcp-home.js';
+import { detectSeatbelt, wrapArgvWithSeatbelt } from '../sandbox/seatbelt.js';
 import { buildMemoryPreamble } from '../memory-bridge.js';
 import { commonlyMcpServer } from '../default-environment.js';
 import { effectiveSandboxTrust, refuseWorkspaceTrust, validateEnvironmentSpec } from '../environment.js';
@@ -21,15 +37,56 @@ const PROXY_KEY_ENV = 'COMMONLY_DSH_PROXY_KEY';
 const MAX_TIMEOUT_MS = 15 * 60 * 1000;
 const SAFE_ENV = /^(?:PATH|LANG|LC_[A-Z_]+|TERM|USER|LOGNAME|NO_COLOR|CI|SSL_CERT_FILE|SSL_CERT_DIR)$/;
 
-export const assertPrivateDsh = (environment = {}) => {
+/** True for the one confined shape this adapter enforces; throws on any other sandbox. */
+export const isConfinedDsh = (environment = {}) => {
   const sandbox = environment?.sandbox || {};
   refuseWorkspaceTrust(sandbox, 'dsh');
   if (effectiveSandboxTrust(sandbox.trust) === 'public') {
     throw new Error('dsh adapter: public-trust seats are not supported; nested Seatbelt fails closed');
   }
-  if (sandbox.mode !== undefined) {
-    throw new Error(`dsh adapter: sandbox.mode=${sandbox.mode} cannot be enforced by this adapter`);
+  if (sandbox.mode === undefined) return false;
+  const { mode, network, ...rest } = sandbox;
+  const networkKeys = Object.keys(network || {});
+  if (mode === 'workspace' && network?.policy === 'restricted'
+    && networkKeys.length === 1 && Object.keys(rest).length === 0) return true;
+  throw new Error(`dsh adapter: sandbox.mode=${mode} cannot be enforced by this adapter; `
+    + "the one confined shape is { mode: 'workspace', network: { policy: 'restricted' } }");
+};
+
+export const assertPrivateDsh = (environment = {}) => { isConfinedDsh(environment); };
+
+const onPath = (name, env) => {
+  if (isAbsolute(name)) return existsSync(name) ? name : null;
+  for (const dir of String(env?.PATH || '').split(delimiter)) {
+    if (dir && existsSync(join(dir, name))) return join(dir, name);
   }
+  return null;
+};
+
+/**
+ * The script a dsh executable runs, and the outermost node_modules holding it:
+ * a confined run starts that script with this node, and reads that tree only.
+ */
+export const resolveDshEntry = (binary, env) => {
+  const found = onPath(binary, env);
+  if (!found) throw new Error(`dsh adapter: a confined seat could not find ${binary} on PATH`);
+  const entry = realpathSync(found);
+  const parts = entry.split(sep);
+  const root = parts.indexOf('node_modules');
+  if (root < 1 || !/\.(?:c|m)?js$/.test(entry)) {
+    throw new Error(`dsh adapter: a confined seat runs dsh from its node package; ${found} resolves to ${entry}`);
+  }
+  return { entry, packages: parts.slice(0, root + 1).join(sep) };
+};
+
+/** Fail a confined turn whose provider traffic broke the model pin. */
+export const assertServedModel = (check, credentials) => {
+  if (!check.refused && !check.failures.length) return;
+  const parts = [
+    ...(check.refused ? [`${check.refused} request(s) for a model other than ${check.pinned} refused`] : []),
+    ...check.failures,
+  ];
+  throw adapterFailure('dsh', `served model check failed: ${parts.join('; ')}`, { credentials, limit: 500 });
 };
 
 /** A stable home per agent and Commonly instance, never the operator's ~/.dsh. */
@@ -71,9 +128,17 @@ export const resolveCommonlyMcp = (declared, ctx) => {
   if (servers.length !== 1 || servers[0]?.name !== 'commonly') {
     throw new Error('dsh adapter: PR 1 supports only the Commonly MCP server');
   }
-  const server = servers[0];
-  if ((server.transport || 'stdio') !== 'stdio'
-    || !isCommonlyCommand(server.command) || !describeMcpCommand(server.command)?.isCommonly) {
+  const isCommonly = (entry) => (entry.transport || 'stdio') === 'stdio'
+    && isCommonlyCommand(entry.command) && !!describeMcpCommand(entry.command)?.isCommonly;
+  if (!isCommonly(servers[0])) {
+    throw new Error('dsh adapter: Commonly MCP must be a recognized stdio @commonlyai/mcp command');
+  }
+  // A confined seat runs the warmed build it can read, never a package runner,
+  // and that build is held to the same check as the declaration.
+  const server = ctx.prepareCommand
+    ? { ...servers[0], command: ctx.prepareCommand(servers[0].command) }
+    : servers[0];
+  if (!isCommonly(server)) {
     throw new Error('dsh adapter: Commonly MCP must be a recognized stdio @commonlyai/mcp command');
   }
   const delivery = deliverSeatCredential(server, {
@@ -101,7 +166,9 @@ export const resolveCommonlyMcp = (declared, ctx) => {
 };
 
 /** JSON is valid YAML; a generated patch has no expression or quoting ambiguity. */
-export const buildPatch = ({ proxyBaseURL, model, cwd, mcp, effort, deepseekOfficial = false }) => ([
+export const buildPatch = ({
+  proxyBaseURL, model, cwd, mcp, effort, deepseekOfficial = false, confined = false,
+}) => ([
   { id: 'llm-pi-ai', config: { providers: {
     commonly: {
       apiKeyEnv: PROXY_KEY_ENV, api: 'openai-completions', baseURL: proxyBaseURL,
@@ -124,7 +191,9 @@ export const buildPatch = ({ proxyBaseURL, model, cwd, mcp, effort, deepseekOffi
   { id: 'llm-deepseek', disabled: true },
   { id: 'llm-deepseek-account', disabled: true },
   { id: 'session-log-deepseek', config: { enabled: false } },
-  { id: 'sandbox-policy', config: { mode: 'workspace-write', workspaceRoot: cwd } },
+  // Confined, the outer Seatbelt is the sandbox: dsh's own would nest a second
+  // one, which macOS refuses, so it is off.
+  { id: 'sandbox-policy', config: { mode: confined ? 'danger-full-access' : 'workspace-write', workspaceRoot: cwd } },
   { insert: [mcp] },
 ]);
 
@@ -169,8 +238,10 @@ const parseEvent = (line, state) => {
   }
 };
 
-export const runDsh = ({ binary, args, cwd, env, timeoutMs, credentials, spawnImpl = childSpawn, onSpawn, controls = {} }) => new Promise((resolve, reject) => {
-  const proc = spawnImpl(binary, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+export const runDsh = ({
+  binary, args, cwd, env, timeoutMs, credentials, spawnImpl = childSpawn, onSpawn, controls = {}, ownGroup = false,
+}) => new Promise((resolve, reject) => {
+  const proc = spawnInOwnGroup(spawnImpl, binary, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] }, { ownGroup });
   observeSpawn(proc, onSpawn, controls);
   const state = { sessionId: null, final: null, error: null, buffer: '' };
   let stderr = '';
@@ -252,7 +323,14 @@ export default {
 
   async spawn(prompt, ctx = {}) {
     const seatModel = requireSeatModel(ctx.environment, 'dsh', true);
-    assertPrivateDsh(ctx.environment);
+    const confined = isConfinedDsh(ctx.environment);
+    if (confined) {
+      if ((ctx._platform || process.platform) !== 'darwin') {
+        throw new Error('dsh adapter: a confined seat needs Seatbelt, which is macOS only');
+      }
+      const seatbelt = (ctx._detectSeatbelt || detectSeatbelt)();
+      if (!seatbelt.available) throw new Error(`dsh adapter: a confined seat needs Seatbelt: ${seatbelt.error}`);
+    }
     if (!ctx.environment?.provider || !ctx.environment?.model) {
       throw new Error('dsh requires environment.provider and environment.model');
     }
@@ -270,19 +348,39 @@ export default {
     const tempDir = await mkdtemp(join(tmpdir(), 'commonly-dsh-'));
     await chmod(tempDir, 0o700);
     let proxy;
+    let relay;
+    let egress;
     try {
       const credential = writeCredentialFile(ctx.runtimeToken, { agentName: 'commonly', root: tempDir });
       proxy = await startProviderProxy({
         provider: ctx.environment.provider, keyFile,
         tokenFile: join(tempDir, 'provider-proxy-token'), adapterLabel: 'dsh',
+        ...(confined ? { pinnedModel: seatModel } : {}),
       });
       const bearer = (await readFile(proxy.tokenFile, 'utf8')).trim();
+      const mcpDirectories = [];
+      if (confined) {
+        relay = await startInstanceProxy({ instanceUrl: ctx.instanceUrl });
+        egress = await (ctx._startEgressProxy || startEgressProxy)();
+      }
       const mcp = resolveCommonlyMcp(ctx.environment?.mcp, {
-        credentialFile: credential.path, instanceUrl: ctx.instanceUrl,
+        credentialFile: credential.path,
+        instanceUrl: confined ? relay.url : ctx.instanceUrl,
+        ...(confined ? {
+          prepareCommand: (command) => {
+            const warmed = (ctx._prepareMcpSpawn || prepareMcpSpawn)(command, { apiUrl: ctx.instanceUrl, publicSeat: true });
+            const directory = warmed && (ctx._selectedMcpVersionDir || selectedMcpVersionDir)(warmed);
+            if (!directory) {
+              throw new Error('dsh adapter: a confined seat runs only a warmed Commonly MCP build, and none is ready on this host');
+            }
+            mcpDirectories.push(directory);
+            return [process.execPath, warmed[1]];
+          },
+        } : {}),
       });
       const patchData = buildPatch({
         proxyBaseURL: proxy.baseURL, model: seatModel,
-        cwd: ctx.cwd, mcp, effort: ctx.environment.effort,
+        cwd: ctx.cwd, mcp, effort: ctx.environment.effort, confined,
         deepseekOfficial: new URL(ctx.environment.provider.baseURL).hostname === 'api.deepseek.com',
       });
       const patch = JSON.stringify(patchData, null, 2);
@@ -300,11 +398,51 @@ export default {
       const requested = Number(ctx.timeoutMs);
       const timeoutMs = Number.isFinite(requested) && requested > 0
         ? Math.min(requested, MAX_TIMEOUT_MS) : MAX_TIMEOUT_MS;
-      return await runDsh({
-        binary, args, cwd: ctx.cwd, env, timeoutMs,
-        credentials: [...spawnCredentials(ctx, []), bearer], spawnImpl: ctx._spawnImpl, onSpawn: ctx.onSpawn, controls: { model: passedModel || null, effort: passedProvider.reasoning || null },
-      });
+      let command = binary;
+      let commandArgs = args;
+      if (confined) {
+        const { entry, packages } = resolveDshEntry(binary, sourceEnv);
+        const tempWork = join(home, 'tmp');
+        await mkdir(tempWork, { recursive: true, mode: 0o700 });
+        env.TMPDIR = tempWork;
+        for (const name of ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy']) env[name] = egress.url;
+        env.NO_PROXY = '127.0.0.1,localhost';
+        env.no_proxy = env.NO_PROXY;
+        [command, ...commandArgs] = (ctx._wrapArgvWithSeatbelt || wrapArgvWithSeatbelt)([process.execPath, entry, ...args], {
+          workspacePath: ctx.cwd,
+          workspaceAccess: 'write',
+          executablePath: process.execPath,
+          statePath: home,
+          mcpConfigDir: tempDir,
+          network: 'loopback',
+          loopbackNetworkPorts: [proxy.port, relay.port, egress.port],
+          readOnlyDirectories: [packages, ...mcpDirectories],
+        });
+      }
+      const credentials = [...spawnCredentials(ctx, []), bearer];
+      let result;
+      let failure;
+      try {
+        result = await runDsh({
+          binary: command, args: commandArgs, cwd: ctx.cwd, env, timeoutMs, credentials,
+          spawnImpl: ctx._spawnImpl, onSpawn: ctx.onSpawn, ownGroup: wantsOwnProcessGroup(ctx),
+          controls: { model: passedModel || null, effort: passedProvider.reasoning || null },
+        });
+      } catch (error) {
+        failure = error;
+      }
+      // A broken pin is the reason a turn failed, whatever dsh said about it.
+      if (confined) {
+        const { refusals } = egress.stats();
+        // eslint-disable-next-line no-console
+        if (refusals.length) console.warn(`[dsh] egress refused: ${refusals.map((r) => `${r.target} (${r.reason})`).join(', ')}`);
+        assertServedModel(proxy.modelCheck(), credentials);
+      }
+      if (failure) throw failure;
+      return result;
     } finally {
+      try { await egress?.close(); } catch { /* best effort */ }
+      try { await relay?.close(); } catch { /* best effort */ }
       try { await proxy?.close(); } catch { /* best effort */ }
       await rm(tempDir, { recursive: true, force: true });
     }

package/src/lib/egress-proxy.js

@@ -0,0 +1,160 @@
+/**
+ * A per-spawn loopback CONNECT proxy that reaches only a fixed list of hosts.
+ *
+ * A confined run gets no outbound network of its own (Seatbelt `network:
+ * 'loopback'`); HTTPS_PROXY points it here. Only CONNECT to an allowlisted
+ * name on an allowlisted port is opened, and the name is resolved here and
+ * the connection made to the address resolved, so a name that resolves to
+ * loopback or a private network is refused rather than followed. Plain HTTP
+ * requests are refused: the proxy never sees the content of what it carries.
+ *
+ * There is no proxy credential. Everything the proxy reaches, any process on
+ * the host already reaches; it gives the confined run a route, not authority.
+ */
+import { createServer } from 'http';
+import { BlockList, connect, isIP } from 'net';
+import { lookup } from 'dns/promises';
+
+// GitHub's download hosts only. github.com and api.github.com accept writes
+// (git push, gists, issues) made with any token a run is handed, and a tunnel
+// cannot tell a read from a write, so they would be an outbound route for
+// anything the run can read. These hosts only serve content.
+export const GITHUB_CONTENT_HOSTS = Object.freeze([
+  'codeload.github.com',
+  'raw.githubusercontent.com',
+  'objects.githubusercontent.com',
+]);
+
+const CONNECT_TIMEOUT_MS = 10_000;
+const MAX_REFUSALS_KEPT = 20;
+
+const nonPublic = new BlockList();
+for (const [address, prefix] of [
+  ['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.168.0.0', 16],
+  ['198.18.0.0', 15], ['224.0.0.0', 4], ['240.0.0.0', 4],
+]) nonPublic.addSubnet(address, prefix, 'ipv4');
+for (const [address, prefix] of [
+  ['::', 128], ['::1', 128], ['fc00::', 7], ['fe80::', 10], ['ff00::', 8], ['64:ff9b::', 96],
+]) nonPublic.addSubnet(address, prefix, 'ipv6');
+
+/** True for an address no public host name should resolve to. */
+export const isNonPublicAddress = (address) => {
+  const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address);
+  if (mapped) return nonPublic.check(mapped[1], 'ipv4');
+  const family = isIP(address);
+  if (!family) return true;
+  return nonPublic.check(address, family === 6 ? 'ipv6' : 'ipv4');
+};
+
+/** `host:port` from a CONNECT target, or null when it is not one. */
+const parseTarget = (target) => {
+  const match = /^([A-Za-z0-9.-]+):(\d{1,5})$/.exec(target || '');
+  if (!match) return null;
+  const port = Number(match[2]);
+  if (port < 1 || port > 65535) return null;
+  return { host: match[1].toLowerCase().replace(/\.$/, ''), port };
+};
+
+/**
+ * startEgressProxy({ allowHosts?, allowPorts? }) → { port, url, refusals, close }
+ *
+ * Listens on 127.0.0.1 at an ephemeral port. `_resolve` and `_allowPrivate`
+ * exist for tests only, so a test can reach a loopback upstream.
+ */
+export const startEgressProxy = async ({
+  allowHosts = GITHUB_CONTENT_HOSTS,
+  allowPorts = [443],
+  _resolve = (host) => lookup(host, { all: true, verbatim: true }),
+  _allowPrivate = false,
+} = {}) => {
+  const hosts = new Set(allowHosts.map((host) => String(host).toLowerCase()));
+  const ports = new Set(allowPorts);
+  if (!hosts.size || [...ports].some((port) => !Number.isInteger(port) || port < 1 || port > 65535)) {
+    throw new Error('Egress proxy needs at least one host and valid TCP ports');
+  }
+  const refusals = [];
+  let opened = 0;
+  const refuse = (socket, status, target, reason) => {
+    refusals.push({ target, reason });
+    if (refusals.length > MAX_REFUSALS_KEPT) refusals.shift();
+    if (!socket.destroyed) socket.end(`HTTP/1.1 ${status}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+  };
+  const sockets = new Set();
+  const track = (socket) => {
+    sockets.add(socket);
+    socket.on('close', () => sockets.delete(socket));
+  };
+
+  const server = createServer((incoming, outgoing) => {
+    incoming.resume();
+    refusals.push({ target: String(incoming.url || '').slice(0, 200), reason: 'not CONNECT' });
+    if (refusals.length > MAX_REFUSALS_KEPT) refusals.shift();
+    outgoing.writeHead(405, { Connection: 'close' }).end();
+  });
+  server.on('connection', track);
+  server.on('connect', async (request, client, head) => {
+    client.on('error', () => {});
+    const target = parseTarget(request.url);
+    const label = String(request.url || '').slice(0, 200);
+    if (!target) { refuse(client, '400 Bad Request', label, 'malformed target'); return; }
+    if (isIP(target.host)) { refuse(client, '403 Forbidden', label, 'address literal'); return; }
+    if (!hosts.has(target.host) || !ports.has(target.port)) {
+      refuse(client, '403 Forbidden', label, 'not allowlisted');
+      return;
+    }
+    let addresses;
+    try {
+      addresses = (await _resolve(target.host)).map((entry) => entry.address);
+    } catch {
+      refuse(client, '502 Bad Gateway', label, 'did not resolve');
+      return;
+    }
+    // Every address must be public, not just the one used: a name that
+    // resolves to both is not one this proxy was asked to reach.
+    if (!addresses.length || (!_allowPrivate && addresses.some(isNonPublicAddress))) {
+      refuse(client, '403 Forbidden', label, 'resolves to a non-public address');
+      return;
+    }
+    if (client.destroyed) return;
+    const upstream = connect({ host: addresses[0], port: target.port });
+    track(upstream);
+    let established = false;
+    client.on('close', () => upstream.destroy());
+    upstream.setTimeout(CONNECT_TIMEOUT_MS, () => upstream.destroy());
+    upstream.on('error', () => {});
+    upstream.on('close', () => {
+      if (established) client.destroy();
+      else refuse(client, '502 Bad Gateway', label, 'upstream unreachable');
+    });
+    upstream.once('connect', () => {
+      upstream.setTimeout(0);
+      established = true;
+      opened += 1;
+      client.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+      if (head?.length) upstream.write(head);
+      upstream.pipe(client);
+      client.pipe(upstream);
+    });
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      server.removeListener('error', reject);
+      resolve();
+    });
+  });
+  const { port } = server.address();
+  return {
+    port,
+    url: `http://127.0.0.1:${port}`,
+    /** { opened, refusals: [{ target, reason }] } — the last 20 refusals. */
+    stats: () => ({ opened, refusals: refusals.map((entry) => ({ ...entry })) }),
+    close: async () => {
+      const closed = new Promise((resolve) => server.close(resolve));
+      for (const socket of sockets) socket.destroy();
+      await closed;
+    },
+  };
+};

package/src/lib/instance-proxy.js

@@ -1,4 +1,8 @@
-/** A per-spawn Unix-socket relay to one declared Commonly instance origin. */
+/**
+ * A per-spawn relay to one declared Commonly instance origin, on a Unix
+ * socket, or on an ephemeral loopback TCP port when no socketPath is given
+ * (for a Seatbelt run whose only network is loopback).
+ */
 import { createServer, request as httpRequest } from 'http';
 import { request as httpsRequest } from 'https';
 import { chmod, unlink } from 'fs/promises';
@@ -48,20 +52,25 @@ export const startInstanceProxy = async ({ instanceUrl, socketPath }) => {
   });
   await new Promise((resolve, reject) => {
     server.once('error', reject);
-    server.listen(socketPath, () => {
+    const listening = () => {
       server.removeListener('error', reject);
       resolve();
-    });
+    };
+    if (socketPath) server.listen(socketPath, listening);
+    else server.listen(0, '127.0.0.1', listening);
   });
-  await chmod(socketPath, 0o600);
+  if (socketPath) await chmod(socketPath, 0o600);
+  const port = socketPath ? null : server.address().port;
   return {
-    socketPath,
+    socketPath: socketPath || null,
+    port,
+    url: port ? `http://127.0.0.1:${port}` : null,
     close: async () => {
       const closed = new Promise((resolve) => server.close(resolve));
       for (const upstream of upstreams) upstream.destroy();
       server.closeAllConnections();
       await closed;
-      await unlink(socketPath).catch((err) => { if (err.code !== 'ENOENT') throw err; });
+      if (socketPath) await unlink(socketPath).catch((err) => { if (err.code !== 'ENOENT') throw err; });
     },
   };
 };

package/src/lib/sandbox/seatbelt.js

@@ -274,7 +274,12 @@ const PLATFORM_BASELINE = String.raw`
 ; Apple's App Sandbox grants every app this same domain.
 (allow user-preference-read
   (preference-domain "kCFPreferencesAnyApplication"))
+`;
 
+// Open network, the tail of the default baseline. A `network: 'loopback'`
+// profile leaves it out: no outbound except the loopback ports it lists, and
+// none of the Security framework services the keychain is reached through.
+const OPEN_NETWORK = String.raw`
 ; The selected provider and declared MCP transports need outbound network. The model's
 ; WebSearch/WebFetch/Bash tools are denied independently in the adapter argv.
 (allow network-outbound)
@@ -367,6 +372,8 @@ export const buildSeatbeltProfile = ({
   readOnlyDirectories = [],
   loopbackNetworkPorts = [],
   allowClaudeRuntimeAccess = false,
+  // 'open' (the default) or 'loopback': only the listed loopback ports.
+  network = 'open',
   // Names directly inside a writable workspace that stay read-only. A
   // workspace seat granted write keeps its project's .git read-only, so every
   // change it makes is one `git status` shows the person (TASK-294).
@@ -387,6 +394,9 @@ export const buildSeatbeltProfile = ({
       throw new Error('Seatbelt loopbackNetworkPorts entries must be valid TCP ports');
     }
   }
+  if (!['open', 'loopback'].includes(network)) {
+    throw new Error('Seatbelt network must be open or loopback');
+  }
   if (!['read', 'write'].includes(workspaceAccess)) {
     throw new Error('Seatbelt workspaceAccess must be read or write');
   }
@@ -456,7 +466,7 @@ export const buildSeatbeltProfile = ({
   })() : [];
 
   return [
-    PLATFORM_BASELINE.trim(),
+    (network === 'open' ? `${PLATFORM_BASELINE}${OPEN_NETWORK}` : PLATFORM_BASELINE).trim(),
     executableRules,
     executableSymlinkRules,
     `(allow file-read-metadata file-test-existence (path-ancestors "${escapeSbplString(resolvedWorkspace)}"))`,