@commonlyai/cli 0.1.50 → 0.1.52

package/package.json

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

package/src/commands/agent.js

@@ -40,6 +40,7 @@ import {
   readPodFocus,
 } from '../lib/pod-focus.js';
 import { detectBwrap } from '../lib/sandbox/bwrap.js';
+import { resolvePublicSandboxMode } from '../lib/sandbox/mode.js';
 import { detectSeatbelt } from '../lib/sandbox/seatbelt.js';
 import {
   DEFAULT_HOOK_TIMEOUT_MS,
@@ -302,8 +303,9 @@ export const buildDefaultEnvironment = (adapterName) => {
  * enforced sandbox.
  *
  * The public-agent sandbox is real and attack-tested, but it only engages once
- * `sandbox.trust` and `sandbox.mode` are declared: `sandbox.mode` defaults to
- * `'none'`, and nothing previously connected "this pod is public" to "this
+ * an enforced sandbox is declared: `sandbox.trust: 'public'` (the adapters then
+ * resolve the mode for the host at spawn) or an explicit non-'none'
+ * `sandbox.mode`. Nothing previously connected "this pod is public" to "this
  * agent must be confined". An agent attached with no sandbox block simply ran
  * unconfined, silently, with the operator none the wiser.
  *
@@ -327,7 +329,12 @@ export const assertSandboxDeclaredForPublicPod = async ({
 
   const mode = environment?.sandbox?.mode;
   const trust = environment?.sandbox?.trust;
-  const declared = Boolean(trust) && Boolean(mode) && mode !== 'none';
+  // An ENFORCED declaration is one the adapters act on: a public trust (whose
+  // mode they resolve per host at spawn) or an explicit non-'none' mode. This
+  // mirrors the daemon's predicate in lib/default-environment.js, so the shape
+  // the daemon writes for an unconfigured seat is one attach also accepts.
+  const declared = mode !== 'none'
+    && (trust === 'public' || typeof mode === 'string');
   if (declared) return;
 
   let pod = null;
@@ -350,10 +357,11 @@ export const assertSandboxDeclaredForPublicPod = async ({
     + 'people you do not control — but its environment declares no sandbox, and '
     + 'an undeclared sandbox means NO sandbox.\n\n'
     + 'Add a sandbox block to the environment file and retry:\n\n'
-    + '  "sandbox": { "trust": "public", "mode": "read-only" }\n\n'
-    + 'Modes for a public agent: "read-only" or "workspace" (macOS Seatbelt / '
-    + 'Linux bwrap). To attach an agent to a private pod instead, pass that '
-    + 'pod id.',
+    + '  "sandbox": { "trust": "public" }\n\n'
+    + 'That is the whole declaration: the adapters pick the enforced mode for '
+    + 'the host (Seatbelt on macOS, bwrap on Linux). Pin one explicitly with '
+    + '"mode": "read-only" or "workspace" if you want a specific access level. '
+    + 'To attach an agent to a private pod instead, pass that pod id.',
   );
 };
 
@@ -501,7 +509,10 @@ export const performAttach = async ({
     workspace = await resolveWorkspace(environment, agentName, dirname(envPath));
     log(`workspace: ${workspace.path}${workspace.created ? ' (created)' : ''}`);
 
-    const sandboxMode = environment.sandbox?.mode || 'none';
+    const sandboxMode = environment.sandbox?.mode
+      || (environment.sandbox?.trust === 'public'
+        ? resolvePublicSandboxMode(environment.sandbox)
+        : 'none');
     const sandboxTrust = environment.sandbox?.trust;
     if (sandboxTrust === 'public' && sandboxMode === 'none') {
       throw new Error(

package/src/lib/adapters/claude.js

@@ -61,8 +61,13 @@ import {
 import { homedir, tmpdir } from 'os';
 import { delimiter, isAbsolute, join } from 'path';
 
-import { mountSkills } from '../environment.js';
-import { wrapArgvWithBwrap } from '../sandbox/bwrap.js';
+import {
+  isLegacySandboxTrust,
+  mountSkills,
+  normalizeSandboxTrust,
+} from '../environment.js';
+import { detectBwrap, wrapArgvWithBwrap } from '../sandbox/bwrap.js';
+import { PUBLIC_SANDBOX_MODES, resolvePublicSandboxMode } from '../sandbox/mode.js';
 import {
   publicClaudeStateRoot,
   wrapArgvWithSeatbelt,
@@ -82,7 +87,6 @@ const DEFAULT_TIMEOUT_MS = (() => {
 
 const buildPrompt = buildMemoryPreamble;
 
-const PUBLIC_SANDBOX_MODES = new Set(['workspace', 'read-only']);
 const PUBLIC_DENIED_TOOLS = [
   'WebSearch',
   'WebFetch',
@@ -410,12 +414,25 @@ const prepareArgv = async (innerArgv, ctx) => {
       .map((name) => `mcp__${name}__*`);
   }
 
-  const sandboxMode = env.sandbox?.mode;
   const sandboxTrust = env.sandbox?.trust;
+  const sandboxMode = resolvePublicSandboxMode(env.sandbox);
   const publicNativeSandbox = sandboxTrust === 'public'
     && PUBLIC_SANDBOX_MODES.has(sandboxMode);
-  if (sandboxTrust === 'public' && sandboxMode === 'none') {
-    throw new Error('public Claude agents require an enforced sandbox mode');
+  // A public trust is ONE contract on both platforms: the jail bounds the
+  // filesystem and the policy bounds the tools. The bwrap branch below used to
+  // get the jail only — a derived Linux seat kept Bash/Write/WebFetch and ran on
+  // the operator's own Claude settings inside the namespace (Vera 69578).
+  const publicBwrapSandbox = sandboxTrust === 'public' && sandboxMode === 'bwrap';
+  // A public trust MUST resolve to an enforced mode. Absent mode is resolved
+  // above; anything else that lands here (the literal 'none', a typo, a
+  // non-string) used to fall through to the bare `claude` spawn below — an
+  // unconfined seat with a public record, which is how a record can claim
+  // confinement it never applies (Vera 69548).
+  if (sandboxTrust === 'public' && !publicNativeSandbox && sandboxMode !== 'bwrap') {
+    throw new Error(
+      'public Claude agents require an enforced sandbox mode '
+      + `(workspace or read-only on macOS, bwrap elsewhere), got ${JSON.stringify(sandboxMode)}`,
+    );
   }
   if (publicNativeSandbox) {
     if (process.platform !== 'darwin') {
@@ -450,7 +467,20 @@ const prepareArgv = async (innerArgv, ctx) => {
     };
   }
 
-  if (allowedPatterns.length > 0) {
+  if (publicBwrapSandbox) {
+    // The mode is chosen here, so the mechanism is verified here: a missing
+    // bwrap must fail the seat's derivation with an actionable message, not
+    // every one of its spawns with a bare ENOENT (Wren 69586). On a non-Linux
+    // host this reports the macOS-only message, same as the wrapper would.
+    const bwrap = (ctx._detectBwrap || detectBwrap)();
+    if (!bwrap.available) {
+      throw new Error(`public Claude agents require bwrap: ${bwrap.error}`);
+    }
+    innerArgv = [
+      ...innerArgv,
+      ...buildPublicClaudePolicyArgs(allowedPatterns),
+    ];
+  } else if (allowedPatterns.length > 0) {
     innerArgv = [...innerArgv, '--allowedTools', ...allowedPatterns];
   }
   if (sandboxMode === 'bwrap') {
@@ -461,7 +491,6 @@ const prepareArgv = async (innerArgv, ctx) => {
     });
     return { cmd: wrapped[0], args: wrapped.slice(1), env: claudeEnv };
   }
-
   return { cmd: 'claude', args: innerArgv, env: claudeEnv };
 };
 
@@ -499,7 +528,31 @@ export default {
     }
   },
 
-  async spawn(prompt, ctx = {}) {
+  async spawn(prompt, rawCtx = {}) {
+    // `sandbox.trust: 'internal'` is refused for new declarations and read as
+    // `public` for a record that already carries it; such a seat is confined
+    // where it can be and refuses to derive where it cannot (Wren 69585).
+    // Resolved ONCE here and threaded to BOTH consumers — the public-state
+    // preparation below and the argv builder — because two independent reads of
+    // one declaration is exactly how this seat crashed with "public Claude
+    // state was not prepared" instead of spawning confined.
+    const ctx = rawCtx.environment
+      ? {
+        ...rawCtx,
+        environment: {
+          ...rawCtx.environment,
+          sandbox: normalizeSandboxTrust(rawCtx.environment.sandbox),
+        },
+      }
+      : rawCtx;
+    if (isLegacySandboxTrust(rawCtx.environment?.sandbox)) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[claude] sandbox.trust=internal is no longer accepted: it reads as '
+        + 'confinement and engaged none. Resolving this seat as trust=public, so '
+        + 'it is confined or it refuses to derive — never unconfined (Wren 69585).',
+      );
+    }
     const isResume = !!ctx.sessionId;
     const sessionId = ctx.sessionId || randomUUID();
     // Passed through UNCOALESCED. `ctx.memoryLongTerm || ''` was here, and
@@ -546,7 +599,7 @@ export default {
     let publicClaudeState = null;
     try {
       const publicNativeSandbox = ctx.environment?.sandbox?.trust === 'public'
-        && PUBLIC_SANDBOX_MODES.has(ctx.environment?.sandbox?.mode);
+        && PUBLIC_SANDBOX_MODES.has(resolvePublicSandboxMode(ctx.environment?.sandbox));
       if (publicNativeSandbox) {
         publicClaudeState = await preparePublicClaudeState(ctx);
       }

package/src/lib/adapters/codex.js

@@ -57,6 +57,7 @@ import {
   resolve as pathResolve,
 } from 'path';
 import { buildMemoryPreamble } from '../memory-bridge.js';
+import { isLegacySandboxTrust, normalizeSandboxTrust } from '../environment.js';
 
 // Default timeout for a single codex spawn (exec mode).
 //
@@ -439,8 +440,23 @@ export default {
         runtimeToken: ctx.runtimeToken,
         instanceUrl: ctx.instanceUrl,
       });
-      const publicSandboxMode = ctx.environment?.sandbox?.trust === 'public'
-        ? ctx.environment?.sandbox?.mode || 'unset'
+      // A derived record stores `trust: 'public'` and no mode (the block is
+      // platform-independent; see cli/src/lib/default-environment.js). Codex's
+      // mode only selects read vs write access — its permission profiles run on
+      // both macOS and Linux — so the derived default is `workspace`, and an
+      // explicit mode in the record still wins. Before this, a mode-less public
+      // record threw `got unset` and no codex seat spawned at all.
+      if (isLegacySandboxTrust(ctx.environment?.sandbox)) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          '[codex] sandbox.trust=internal is no longer accepted: it reads as '
+          + 'confinement and engaged none. Resolving this seat as trust=public '
+          + '(Wren 69585).',
+        );
+      }
+      const sandbox = normalizeSandboxTrust(ctx.environment?.sandbox);
+      const publicSandboxMode = sandbox?.trust === 'public'
+        ? sandbox?.mode ?? 'workspace'
         : null;
       const args = buildArgs({
         sessionId: ctx.sessionId || null,

package/src/lib/daemon-supervisor.js

@@ -2,7 +2,7 @@ import { isDeepStrictEqual } from 'node:util';
 import { homedir } from 'node:os';
 import { isAbsolute, resolve as pathResolve } from 'node:path';
 
-import { withDefaultMcpServer } from './default-environment.js';
+import { seatBaseline } from './default-environment.js';
 
 /**
  * ADR-026 Phase 2, slice 2: the resident supervision loop behind
@@ -190,7 +190,15 @@ export const createDaemonSupervisor = ({
         // declaration carries no mcp[] would come back tool-less. Re-apply the
         // shipped default here and below, or the seat silently loses every
         // commonly_* tool the next time the UI edits its model (TASK-048).
-        const nextEnvironment = withDefaultMcpServer(merged, nextAdapter);
+        //
+        // A DECLARED environment also gets the sandbox default when it names
+        // none: the declaration is not the operator's, and `sandbox.mode`
+        // defaults to 'none' in the adapters, so an omitted block is an
+        // unconfined seat (TASK-052). A local record with no environment at
+        // all is in the same position — nobody has authored anything.
+        const nextEnvironment = seatBaseline(merged, nextAdapter, {
+          sandbox: wanted.declared || !existing.environment,
+        });
         const workspacePath = workspacePathFor(nextEnvironment);
         const nextRecord = {
           ...existing,
@@ -209,7 +217,9 @@ export const createDaemonSupervisor = ({
       if (adapterChanged) {
         // An adapter that consumes mcp[] must not be started on a record that
         // declares none, even when only the adapter itself changed.
-        const nextEnvironment = withDefaultMcpServer(existing.environment, nextAdapter);
+        const nextEnvironment = seatBaseline(existing.environment, nextAdapter, {
+          sandbox: !existing.environment,
+        });
         saveToken(row.agentName, {
           ...existing,
           adapter: nextAdapter,
@@ -226,7 +236,9 @@ export const createDaemonSupervisor = ({
         // stays tool-less for as long as it runs. Heal it here, and only when
         // the environment actually changed — otherwise every tick rewrites the
         // file and restarts the seat forever.
-        const nextEnvironment = withDefaultMcpServer(existing.environment, existing.adapter);
+        const nextEnvironment = seatBaseline(existing.environment, existing.adapter, {
+          sandbox: !existing.environment,
+        });
         if (!isDeepStrictEqual(existing.environment || null, nextEnvironment || null)) {
           saveToken(row.agentName, { ...existing, environment: nextEnvironment });
           log('record predates the commonly MCP baseline — restarting the seat to load it');
@@ -277,10 +289,13 @@ export const createDaemonSupervisor = ({
     const environment = environmentFor(row);
     // A seat installed server-side (no local `agent attach`) arrives with no
     // mcp[] at all: without the default it spawns a CLI that has no commonly_*
-    // tools and cannot post. See lib/default-environment.js.
-    const recordEnvironment = withDefaultMcpServer(
+    // tools and cannot post. See lib/default-environment.js. Nothing here is
+    // operator-authored, so this seat also gets the sandbox default — the
+    // self-serve install's seat used to be born unconfined (TASK-052).
+    const recordEnvironment = seatBaseline(
       environment ? environment.value : null,
       adapter,
+      { sandbox: true },
     );
     saveToken(row.agentName, {
       agentName: row.agentName,
@@ -353,12 +368,26 @@ export const createDaemonSupervisor = ({
         seats.set(key, seat);
       }
       seat.desired = true;
-      const localToken = loadToken(row.agentName);
-      seat.adapter = row.runtime?.adapter || localToken?.adapter || seat.adapter || null;
-      seat.model = row.runtime?.model || localToken?.environment?.model || seat.model || null;
-      seat.effort = row.runtime?.effort || localToken?.environment?.effort || seat.effort || null;
       // eslint-disable-next-line no-await-in-loop
       const ready = await ensureToken(row);
+      // Report what the seat actually RUNS, which is the record: `agent run`
+      // reads it once at boot, and ensureToken above may have just rewritten it
+      // (a mint, or a config change). Reading it AFTER ensureToken is the point
+      // — the same tick's write is the record the seat starts from, so the very
+      // first heartbeat is already about the running seat.
+      //
+      // The row's runtime is a COMPATIBILITY OVERLAY for a seat with no record
+      // at all, never an override of a declared environment (see the overlay
+      // comment above ensureToken): leading with it here reported a model the
+      // seat was not running, because the spawn path gives the declared
+      // environment precedence over runtime.model/effort (environmentFor, and
+      // the TASK-065 measurement). ensureToken also REFUSES a change it cannot
+      // apply — a requested adapter this machine does not have — so the record
+      // is the honest answer there too: it names the adapter that kept running.
+      const current = loadToken(row.agentName);
+      seat.adapter = current ? (current.adapter || null) : (row.runtime?.adapter || null);
+      seat.model = current ? (current.environment?.model || null) : (row.runtime?.model || null);
+      seat.effort = current ? (current.environment?.effort || null) : (row.runtime?.effort || null);
       if (ready === 'changed' && seat.child) {
         // desired stays true, so the exit handler respawns with the updated
         // record — the restart path IS the D6 path, no second spawner.

package/src/lib/default-environment.js

@@ -24,6 +24,51 @@
 
 export const ADAPTERS_WITH_DEFAULT_MCP = new Set(['claude', 'codex', 'pi']);
 
+/**
+ * The adapters that can ENFORCE the default sandbox — a strict subset of the
+ * ones that consume `mcp[]`.
+ *
+ * `pi` is absent deliberately. It has no sandbox path until #1740's transport
+ * work gives it one, and since #1727 it REFUSES TO START on a spec that
+ * declares one: `assertNoSandboxDeclared` in adapters/pi.js throws on
+ * `trust: 'public'` and on any `mode` other than 'none'. So handing pi this
+ * block is not a harmless no-op — it is an unspawnable seat. A pi seat gets the
+ * `mcp[]` half only, and the residual is that such a seat runs unconfined: that
+ * belongs to the row that owns pi confinement, not to a declaration written
+ * here and hoped for. A derived pi seat used to be exactly this shape and would
+ * have failed every spawn with `public-trust seats are not supported`.
+ */
+export const ADAPTERS_WITH_DEFAULT_SANDBOX = new Set(['claude', 'codex']);
+
+/**
+ * The sandbox an unconfigured seat gets.
+ *
+ * `sandbox.mode` defaults to `'none'` in the adapters, so an ABSENT sandbox
+ * block means NO sandbox — the seat runs unconfined on the operator's machine
+ * while taking instructions from whoever is in the room. That is what a
+ * self-serve install shipped (C4-6 / TASK-052): the install declares no
+ * environment, the daemon projected nothing, and the socket was born with no
+ * confinement and no way to notice.
+ *
+ * `trust: 'public'` is the conservative declaration — "this seat takes
+ * instructions from people I do not control" — and it is the one that engages
+ * the real sandbox in the adapters.
+ *
+ * NO MODE is stored, deliberately. The record is platform-independent and the
+ * host is not: the adapters read a public trust with no mode as Seatbelt
+ * workspace on macOS and bwrap elsewhere. `mode: 'workspace'` in the row is
+ * refused on Linux, and `mode: 'bwrap'` is meaningless on macOS, so either one
+ * moves a host fact into the database and breaks the day the seat is re-homed.
+ * An explicit mode in a record still wins over the derived one.
+ *
+ * Confinement holds for claude and codex, and only they are ever handed this
+ * block (ADAPTERS_WITH_DEFAULT_SANDBOX). A pi seat must never be: it fails
+ * closed on a declared sandbox rather than run under a spec it cannot honour.
+ */
+export const COMMONLY_DEFAULT_SANDBOX = Object.freeze({ trust: 'public' });
+
+export const defaultSeatSandbox = () => ({ ...COMMONLY_DEFAULT_SANDBOX });
+
 export const COMMONLY_MCP_SERVER_NAME = 'commonly';
 
 export const commonlyMcpServer = () => ({
@@ -68,3 +113,41 @@ export const withDefaultMcpServer = (environment, adapterName) => {
   }
   return { ...(environment || {}), mcp: [...(declared || []), commonlyMcpServer()] };
 };
+
+/**
+ * Ensure the environment declares an ENFORCED sandbox, touching nothing that
+ * is already enforced. Returns the SAME reference when nothing needs adding.
+ *
+ * Only for environments this daemon derived from the server's declaration or
+ * from nothing at all — never for a local record the operator authored. A
+ * declared `mode: 'none'` is replaced rather than honoured: absence and 'none'
+ * are the same thing to the adapter, and this is the path that decides what an
+ * undeclared sandbox means.
+ */
+export const withDefaultSandbox = (environment) => {
+  if (environment !== null && environment !== undefined
+    && (typeof environment !== 'object' || Array.isArray(environment))) {
+    return environment;
+  }
+  const sandbox = environment?.sandbox;
+  // An ENFORCED declaration is one the adapters act on: a public trust (whose
+  // mode they resolve, and refuse to spawn without) or an explicit non-'none'
+  // mode. `mode: 'none'`, an empty block and a missing one are all the same
+  // thing to a spawn — no confinement — so all three are replaced here.
+  const enforced = sandbox !== null && typeof sandbox === 'object'
+    && sandbox.mode !== 'none'
+    && (sandbox.trust === 'public' || typeof sandbox.mode === 'string');
+  if (enforced) return environment;
+  return { ...(environment || {}), sandbox: defaultSeatSandbox() };
+};
+
+/**
+ * The full baseline a seat gets from the daemon: the kernel MCP server, plus an
+ * enforced sandbox when the environment is one the daemon derived rather than
+ * one the operator wrote (`sandbox: true` at the call sites).
+ */
+export const seatBaseline = (environment, adapterName, { sandbox = false } = {}) => {
+  const withMcp = withDefaultMcpServer(environment, adapterName);
+  if (!sandbox || !ADAPTERS_WITH_DEFAULT_SANDBOX.has(adapterName)) return withMcp;
+  return withDefaultSandbox(withMcp);
+};

package/src/lib/environment.js

@@ -46,9 +46,30 @@ const ALLOWED_TOP_KEYS = new Set([
 const ALLOWED_SANDBOX_MODES = new Set([
   'none', 'workspace', 'read-only', 'bwrap', 'firejail', 'container', 'managed',
 ]);
-const ALLOWED_SANDBOX_TRUST = new Set(['public', 'internal']);
+const ALLOWED_SANDBOX_TRUST = new Set(['public']);
 const ALLOWED_NETWORK_POLICIES = new Set(['unrestricted', 'restricted']);
 
+// `trust: 'internal'` was accepted by this schema and read by NO adapter. On the
+// attach path it could only name a mode the platform cannot resolve; on the
+// daemon path it was silently inert — claude fell through to a bare unconfined
+// spawn and codex took `--dangerously-bypass-approvals-and-sandbox` — so a
+// declaration that reads as "confine me, not as a public agent" meant the
+// opposite of what it said (Vera 69592). It is refused for new declarations
+// above, and a record that already carries it is resolved TOWARD confinement,
+// never toward the bare spawn (Wren 69585): `internal` is read as `public`, so
+// such a seat is confined where it can be and refuses to derive where it
+// cannot. A real middle trust arrives as its own adapter that reads it.
+export const LEGACY_SANDBOX_TRUST = Object.freeze({ internal: 'public' });
+export const isLegacySandboxTrust = (sandbox) => (
+  typeof sandbox?.trust === 'string'
+  && Object.prototype.hasOwnProperty.call(LEGACY_SANDBOX_TRUST, sandbox.trust)
+);
+export const normalizeSandboxTrust = (sandbox) => (
+  isLegacySandboxTrust(sandbox)
+    ? { ...sandbox, trust: LEGACY_SANDBOX_TRUST[sandbox.trust] }
+    : sandbox
+);
+
 const expandHome = (p) => {
   if (!p || typeof p !== 'string') return p;
   if (p === '~') return homedir();
@@ -172,7 +193,11 @@ export const validateEnvironmentSpec = (spec) => {
         errors.push(`sandbox.mode must be one of: ${[...ALLOWED_SANDBOX_MODES].join(', ')}`);
       }
       if (trust !== undefined && !ALLOWED_SANDBOX_TRUST.has(trust)) {
-        errors.push(`sandbox.trust must be one of: ${[...ALLOWED_SANDBOX_TRUST].join(', ')}`);
+        errors.push(
+          "sandbox.trust must be 'public' — it marks a seat anyone in the pod can "
+          + 'talk to; omit it for your own seat '
+          + `(got ${JSON.stringify(trust)})`,
+        );
       }
       if (network !== undefined) {
         if (typeof network !== 'object' || network === null) {

package/src/lib/sandbox/mode.js

@@ -0,0 +1,36 @@
+/**
+ * Which host mechanism enforces a public seat.
+ *
+ * A stored environment is platform-independent and the host is not. The daemon
+ * derives `sandbox: { trust: 'public' }` with NO mode (lib/default-environment.js)
+ * because `mode: 'workspace'` is Seatbelt on macOS and is refused on Linux,
+ * while `mode: 'bwrap'` is meaningless on macOS — writing either into the row
+ * moves a host fact into the database and breaks the day the seat is re-homed
+ * (Wren 69545).
+ *
+ * So the mode is resolved here, at the point that knows the host:
+ *   darwin  → 'workspace' (the claude adapter maps it to Seatbelt)
+ *   else    → 'bwrap'     (bubblewrap; attach checks it is installed)
+ *
+ * Resolution is PUBLIC-only on purpose. A non-public declaration keeps whatever
+ * mode it wrote, and an adapter that cannot enforce it is expected to refuse
+ * rather than quietly spawn unconfined. An explicit mode on a public
+ * declaration still wins — including a wrong one, which the caller then
+ * refuses (Vera 69548: an unresolvable public mode must not fall through to a
+ * bare, unconfined spawn).
+ *
+ * NOT used by the codex adapter. Codex's `mode` is read-vs-write access, not a
+ * host mechanism — its permission profiles run on both platforms — so its
+ * derived default is 'workspace' everywhere.
+ */
+
+export const PUBLIC_SANDBOX_MODES = new Set(['workspace', 'read-only']);
+
+export const resolvePublicSandboxMode = (sandbox, platform = process.platform) => {
+  const declared = sandbox?.mode;
+  if (sandbox?.trust !== 'public') return declared;
+  if (declared !== undefined && declared !== null) return declared;
+  return platform === 'darwin' ? 'workspace' : 'bwrap';
+};
+
+export default { PUBLIC_SANDBOX_MODES, resolvePublicSandboxMode };