@commonlyai/cli 0.1.60 → 0.1.63

package/package.json

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

package/src/lib/adapters/pi-mcp-client.mjs

@@ -18,7 +18,10 @@
  */
 
 import { spawn } from 'node:child_process';
-import { closeSync, readFileSync } from 'node:fs';
+import {
+  closeSync, readFileSync, existsSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
 
 /**
  * The grant broker's path. wren's ruling for the daemon-side half of TASK-063:
@@ -86,10 +89,172 @@ export const connectMcp = (server, opts = {}) => (typeof server?.url === 'string
   ? connectHttpMcp(server, opts)
   : connectStdioMcp(server, opts));
 
+/**
+ * The credential channel (TASK-078, ruled 2026-09-19: "take the token out of
+ * the environment", inherited pipe).
+ *
+ * `connectStdioMcp` spawns each declared stdio server with
+ * `{...process.env, ...env}`, and the default declaration puts the seat's
+ * runtime token in that `env` map. So the token sat in the MCP child's
+ * environment, where any same-user process could read it back with
+ * `ps eww <pid>` or `/proc/<pid>/environ` — including, on a shared host, a
+ * process the seat is not allowed to talk to.
+ *
+ * Now the token rides an inherited pipe on fd 3 and the child's environment
+ * carries only a pointer to it (`COMMONLY_TOKEN_FD=3`) — not a secret. The
+ * child end of that pipe is read to EOF.
+ *
+ * THE PIPE IS ONLY AVAILABLE WHERE WE SPAWN. This is the pi path; claude and
+ * codex let their own CLI start the server (claude expands `${VAR}` in its own
+ * process env, codex rides `mcp_servers.*.env_vars`), so a pipe opened here
+ * never reaches that grandchild. Those two still hand the token over in their
+ * runtime's environment, which is a separate, still-open half of the same row.
+ *
+ * THE OLD SERVER STILL WORKS. `@commonlyai/mcp` only learned to read the pipe in
+ * 0.3.11, and a seat may pin an older one — the sprint seats run a staging
+ * checkout of 0.3.4 — so a declaration whose command names an older
+ * `@commonlyai/mcp` keeps the environment variable AS WELL, with a warning that
+ * names the pin. An operator can also opt out explicitly with
+ * `COMMONLY_TOKEN_CHANNEL=env` in the entry's own env. Otherwise the token is
+ * piped and the environment is left clean.
+ */
+export const CREDENTIAL_KEY = 'COMMONLY_AGENT_TOKEN';
+export const CREDENTIAL_FD_VAR = 'COMMONLY_TOKEN_FD';
+export const CREDENTIAL_CHANNEL_VAR = 'COMMONLY_TOKEN_CHANNEL';
+export const CREDENTIAL_FD = 3;
+
+/** The `@commonlyai/mcp` release whose `loadConfig` reads the pipe channel. */
+export const PIPE_READER_VERSION = [0, 3, 11];
+
+const MCP_PACKAGE = '@commonlyai/mcp';
+
+const parseVersion = (spec) => {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(String(spec || '').trim());
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+};
+
+const olderThanPipeReader = (version) => {
+  if (!version) return null;
+  for (let i = 0; i < 3; i += 1) {
+    if (version[i] !== PIPE_READER_VERSION[i]) return version[i] < PIPE_READER_VERSION[i];
+  }
+  return false;
+};
+
+/**
+ * What an `@commonlyai/mcp` command would run, or null when the command cannot
+ * be identified as that package at all.
+ *
+ * Two shapes matter: `npx [-y] @commonlyai/mcp@<spec>` (a spec is a version, or
+ * `latest`/absent, which resolves to whatever is published — never treated as
+ * old), and a local checkout, `node <path>/src/index.js`, which is what the
+ * staging seats run; for that one the package.json beside it is the only honest
+ * answer, and a package.json naming something else means this is not our server.
+ *
+ * `{ isCommonly: true, version: null }` means "our server, version unknown" —
+ * an unpinned npx spec, whose whole point is that it tracks the published one.
+ * `null` as the return value means "not identifiable as our server", which is a
+ * different answer and takes a different branch: a stranger's server gets its
+ * declaration honoured unchanged.
+ */
+export const describeMcpCommand = (command, { readTextFile = (p) => (existsSync(p) ? readFileSync(p, 'utf8') : null) } = {}) => {
+  if (!Array.isArray(command) || command.length === 0) return null;
+  const parts = command.map(String);
+  const pkgArg = parts.find((p) => p.includes(MCP_PACKAGE));
+  if (pkgArg) {
+    const at = pkgArg.lastIndexOf('@');
+    if (at <= pkgArg.indexOf(MCP_PACKAGE)) return { isCommonly: true, version: null };
+    return { isCommonly: true, version: parseVersion(pkgArg.slice(at + 1)) };
+  }
+  const scriptPath = parts.find((p) => p.endsWith('.js') || p.endsWith('.mjs'));
+  if (!scriptPath) return null;
+  // `src/index.js` → `../package.json`; also try one level further up, because a
+  // bin shim can live in `bin/` beside `src/`.
+  for (const candidate of [join(dirname(scriptPath), '..', 'package.json'), join(dirname(scriptPath), 'package.json')]) {
+    let raw;
+    try {
+      raw = readTextFile(candidate);
+    } catch {
+      raw = null;
+    }
+    if (!raw) continue;
+    try {
+      const pkg = JSON.parse(raw);
+      if (!pkg || typeof pkg !== 'object') continue;
+      if (pkg.name === MCP_PACKAGE) return { isCommonly: true, version: parseVersion(pkg.version) };
+      // A package.json that names another package settles it: not ours, so its
+      // declaration is none of this function's business.
+      return null;
+    } catch {
+      // A malformed package.json is not an answer; keep looking.
+    }
+  }
+  return null;
+};
+
+/**
+ * Split a declared env map into the child's environment and the credential to
+ * hand over the pipe.
+ *
+ * Returns `{ env, credential, keepInEnv }`. `keepInEnv` is true only when the
+ * server cannot read the pipe — it predates the reader, it is somebody else's
+ * server, or the declaration opted out explicitly. Everything else gets the
+ * pointer variable and no secret.
+ */
+export const splitCredential = (env, command, { onWarn = (m) => process.stderr.write(`${m}\n`) } = {}) => {
+  const declared = { ...(env || {}) };
+  const credential = declared[CREDENTIAL_KEY];
+  const requested = String(declared[CREDENTIAL_CHANNEL_VAR] || '').trim().toLowerCase();
+  delete declared[CREDENTIAL_CHANNEL_VAR];
+  if (!credential) {
+    delete declared[CREDENTIAL_KEY];
+    return { env: declared, credential: null, keepInEnv: false };
+  }
+  if (requested === 'env') {
+    return { env: declared, credential: null, keepInEnv: true };
+  }
+  const server = describeMcpCommand(command);
+  if (!server) {
+    // Not identifiable as @commonlyai/mcp. A declaration that put this key in a
+    // stranger's environment asked for it to be there, and that server has no
+    // reason to know about a pipe; changing its contract is not this change's
+    // business.
+    return { env: declared, credential: null, keepInEnv: true };
+  }
+  if (server.version && olderThanPipeReader(server.version) === true) {
+    onWarn(`[pi-mcp-client] ${command[0]} runs ${MCP_PACKAGE} ${server.version.join('.')}, which predates the pipe channel (0.3.11): keeping the token in the child environment. Unpin it, or set ${CREDENTIAL_CHANNEL_VAR}=env to say so on purpose.`);
+    return { env: declared, credential: null, keepInEnv: true };
+  }
+  delete declared[CREDENTIAL_KEY];
+  declared[CREDENTIAL_FD_VAR] = String(CREDENTIAL_FD);
+  return { env: declared, credential, keepInEnv: false };
+};
+
 /** A minimal MCP stdio client: initialize, tools/list, tools/call. */
-export const connectStdioMcp = ({ name, command, env }, { spawnImpl = spawn, timeoutMs = 60_000 } = {}) => {
+export const connectStdioMcp = ({
+  name, command, env,
+}, {
+  spawnImpl = spawn, timeoutMs = 60_000, onWarn,
+} = {}) => {
   const [cmd, ...args] = command;
-  const proc = spawnImpl(cmd, args, { env: { ...process.env, ...(env || {}) }, stdio: ['pipe', 'pipe', 'pipe'] });
+  const { env: declaredEnv, credential, keepInEnv } = splitCredential(env, command, onWarn ? { onWarn } : {});
+  // The inherited environment is stripped of the key unless an old server has to
+  // read it there: the daemon's own environment is not a channel into a child,
+  // and `...process.env` used to make it one.
+  const childEnv = { ...process.env, ...declaredEnv };
+  if (!keepInEnv) delete childEnv[CREDENTIAL_KEY];
+  const stdio = credential ? ['pipe', 'pipe', 'pipe', 'pipe'] : ['pipe', 'pipe', 'pipe'];
+  const proc = spawnImpl(cmd, args, { env: childEnv, stdio });
+  if (credential) {
+    const channel = proc.stdio && proc.stdio[CREDENTIAL_FD];
+    if (!channel) {
+      // Fail loudly rather than fall back: the environment it would fall back to
+      // is the thing this change exists to empty.
+      throw new Error(`${name}: no fd ${CREDENTIAL_FD} pipe to carry the runtime token`);
+    }
+    channel.on('error', () => {});
+    channel.end(credential);
+  }
   const pending = new Map();
   let nextId = 1;
   let buffer = '';

package/src/lib/daemon-supervisor.js

@@ -4,6 +4,7 @@ import { isAbsolute, resolve as pathResolve } from 'node:path';
 import { auditDeclaredMcp, installedStdioEntries } from './declared-mcp-guard.js';
 
 import { seatBaseline } from './default-environment.js';
+import { withholdGrantBroker } from './grant-broker-guard.js';
 
 /**
  * ADR-026 Phase 2, slice 2: the resident supervision loop behind
@@ -172,6 +173,27 @@ export const createDaemonSupervisor = ({
   // Returns 'ready' | 'changed' (record updated — the seat must restart to
   // load it) | false.
   const ensureToken = async (row) => {
+    // One derive for this seat, so the broker refusal cannot be applied at three
+    // of four sites: `seatBaseline` is where an environment becomes the one the
+    // seat RUNS under, and `withholdGrantBroker` asks the same question the
+    // server asks (`can this seat confine a granter's authority?`) for the cases
+    // the server cannot see — a row naming no adapter, a backend older than the
+    // refusal, a record written by hand. Entry-level per wren 69829: the broker
+    // entry is withheld and the seat still starts, because it was never promised
+    // confinement. `record.instanceUrl` is what makes the injected url
+    // identifiable at all — the record holds the UNRESOLVED
+    // `${COMMONLY_API_URL}/api/mcp/grants/<id>` placeholder.
+    const derive = (environment, adapter, options) => withholdGrantBroker(
+      seatBaseline(environment, adapter, options),
+      adapter,
+      {
+        instanceUrl: record.instanceUrl,
+        onRefuse: (refusal, names) => log(
+          `[${row.agentName}] ${refusal.code} (${refusal.reason}) — withholding ${names.join(', ')}: ${refusal.detail}`,
+        ),
+      },
+    );
+
     const existing = loadToken(row.agentName);
     if (existing) {
       // A model changed in the UI reaches the seat here: update the record,
@@ -214,7 +236,7 @@ export const createDaemonSupervisor = ({
         // 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, {
+        const nextEnvironment = derive(merged, nextAdapter, {
           sandbox: wanted.declared || !existing.environment,
         });
         const workspacePath = workspacePathFor(nextEnvironment);
@@ -235,7 +257,7 @@ 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 = seatBaseline(existing.environment, nextAdapter, {
+        const nextEnvironment = derive(existing.environment, nextAdapter, {
           sandbox: !existing.environment,
         });
         saveToken(row.agentName, {
@@ -254,7 +276,7 @@ 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 = seatBaseline(existing.environment, existing.adapter, {
+        const nextEnvironment = derive(existing.environment, existing.adapter, {
           sandbox: !existing.environment,
         });
         if (!isDeepStrictEqual(existing.environment || null, nextEnvironment || null)) {
@@ -312,7 +334,7 @@ export const createDaemonSupervisor = ({
     // 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(
+    const recordEnvironment = derive(
       environment ? environment.value : null,
       adapter,
       { sandbox: true },

package/src/lib/grant-broker-guard.js

@@ -0,0 +1,268 @@
+/**
+ * Withhold the grant broker from a seat this daemon cannot confine (TASK-063).
+ *
+ * The grant arrives as an injected MCP server, and confinement is declared in a
+ * different field — `sandbox` — so the two can disagree: a seat can be handed a
+ * granter's authority and no confinement. wren's ruling (69799) is REFUSE, not
+ * derive, and it is ENTRY-level (69829): the broker entry is withheld and the
+ * seat runs, because the seat was never promised confinement — a seat-level
+ * refusal is #1727's case only (a declared sandbox the host cannot enforce).
+ *
+ * This is the daemon half of one refusal with TWO emitters. The server refuses
+ * at the projection (`backend/services/grantBrokerConfinement.ts`) for rows it
+ * can judge host-independently; the daemon decides the rest, because it is the
+ * layer that knows this host, that resolved the adapter locally, and that holds
+ * the record the seat actually runs from — including records the projection
+ * never reaches (a row naming no adapter, a backend older than the refusal, a
+ * hand-written token file). Both halves emit the same `code`.
+ *
+ * THE ADAPTER IS THE HOST-INDEPENDENT FACT, so the set of adapters this daemon
+ * can confine is the set that derives an enforced sandbox — `claude` and
+ * `codex` (`ADAPTERS_WITH_DEFAULT_SANDBOX`, imported rather than retyped).
+ * Anything else, `pi` included, confines on no host: `pi` refuses a declared
+ * sandbox rather than honouring it, so an undeclared one is never derived.
+ *
+ * ONE REASON THE SERVER DOES NOT HAVE: `sandbox_absent`. The server must ALLOW
+ * an absent block (a daemon-provisioned seat's baseline is derived here and is
+ * not visible from the installation row — `quill` carries no sandbox key), so
+ * absence is this layer's to judge. Reaching it here means the baseline did not
+ * supply one, which happens for a local record with no environment of its own
+ * (`sandbox: !existing.environment` at the derive sites): nobody authored a
+ * sandbox and nothing derived one, so the seat would run unconfined.
+ *
+ * THE URL IS THE FACT, AND THE URL THIS LAYER HOLDS USUALLY CANNOT BE PARSED.
+ * Measured on the live fleet: the broker url in a token record is the
+ * UNRESOLVED placeholder `"${COMMONLY_API_URL}/api/mcp/grants/<id>"` (c4-smoke,
+ * the only record declaring one). `new URL()` throws on that string, so
+ * `isGrantBrokerUrl` — which the pi adapter calls AFTER substituting — returns
+ * false here. A daemon-side predicate that reused it unchanged would match
+ * nothing and refuse nothing while reading as if it enforced something. So the
+ * known placeholders are resolved to this instance first, and an entry counts
+ * only when it is OUR broker: our origin, or a relative/placeholder-prefixed
+ * path. A foreign server that happens to live under `/api/mcp/grants/` is not
+ * our grant and is left alone.
+ *
+ * AND A MISS HERE IS FAIL-OPEN, so the path is NORMALIZED before it is judged.
+ * Measured (vera, 70369): a bound instance spelled `https://api.commonly.me/`
+ * turns `"${COMMONLY_API_URL}/api/mcp/grants/g1"` into
+ * `https://api.commonly.me//api/mcp/grants/g1`, whose pathname starts `//api/`
+ * and matches nothing — the entry goes unrecognised and the broker RIDES into a
+ * seat this daemon just decided it cannot confine. Reachable: `agent.js` takes
+ * `instanceUrl` from `COMMONLY_API_URL` with a bare `.trim()`, while `config.js`
+ * is what strips the slash.
+ *
+ * The enforcement is ONE mechanism: duplicate slashes are collapsed before the
+ * path predicate sees them. It covers the doubled slash whichever side produced
+ * it — the join, a hand-written record, and a protocol-relative spelling OF THE
+ * PATH (`//api/mcp/grants/g1`, which collapses to the broker's path) — where
+ * stripping the instance's trailing slash covers only the join, and a mutation
+ * showed the two were redundant here (removing the strip reddened nothing).
+ *
+ * A URL WITH NO SCHEME HAS TWO READINGS, and both are taken (vera, 70372, who
+ * corrected a first draft of this paragraph for claiming the second was
+ * covered). Collapsing alone reads `//api.commonly.me/api/mcp/grants/g1` as the
+ * PATH `/api.commonly.me/api/...`, which is not the broker's path and measures
+ * false — a fail-open, because URL semantics say that string names THIS
+ * instance. So a schemeless value is also resolved against the bound instance,
+ * and counts when that reading lands on our origin and the broker's path. A
+ * foreign host is left alone under either reading; the path reading is what the
+ * shipped declarations use, and a record is free to hold the other.
+ *
+ * Collapsing can only turn a miss into a match, and a match here means WITHHOLD,
+ * so it moves in the safe direction; origin equality is still required first, so
+ * a foreign server cannot be drawn in by its spelling.
+ */
+import { isGrantBrokerUrl } from './adapters/pi-mcp-client.mjs';
+import { ADAPTERS_WITH_DEFAULT_SANDBOX } from './default-environment.js';
+import { LEGACY_SANDBOX_TRUST } from './environment.js';
+import { PUBLIC_SANDBOX_MODES, resolvePublicSandboxMode } from './sandbox/mode.js';
+
+/** One typed code, two emitters (`decidedBy` says which one spoke). */
+export const GRANT_BROKER_REFUSAL_CODE = 'grant_broker_unconfined';
+
+/**
+ * Every mode an adapter enforces for a public seat: the cli's own public set
+ * ({workspace, read-only}) plus `bwrap`, which `resolvePublicSandboxMode`
+ * resolves to on Linux and claude implements there. Derived from the cli's
+ * constants rather than restated, so a mode added to one is not silently
+ * missing from the other.
+ */
+export const ENFORCING_MODES = new Set([...PUBLIC_SANDBOX_MODES, 'bwrap']);
+
+const URL_PLACEHOLDERS = ['${COMMONLY_API_URL}', '${COMMONLY_INSTANCE_URL}'];
+const PARSE_ANCHOR = 'https://grant-declaration.invalid';
+
+/** `internal` → `public`; anything else (including absent) is itself. */
+const effectiveTrust = (trust) => (
+  typeof trust === 'string' && Object.prototype.hasOwnProperty.call(LEGACY_SANDBOX_TRUST, trust)
+    ? LEGACY_SANDBOX_TRUST[trust]
+    : trust
+);
+
+/**
+ * A bound instance is only trimmed here (`agent.js` does the same). Any
+ * trailing slash it carries is deliberately left alone: the doubled slash it
+ * would manufacture is answered by `collapseSlashes` below, one mechanism for
+ * every spelling rather than two that a mutation cannot tell apart.
+ */
+const resolveInstance = (instanceUrl) => (
+  typeof instanceUrl === 'string' ? instanceUrl.trim() : ''
+);
+
+/**
+ * `//api/mcp/grants/g1` and `/api/mcp/grants/g1` are the same path written two
+ * ways, and only one of them is ours to withhold — the absolute branch needs it
+ * for a doubled slash after the origin, the relative branch for a
+ * protocol-relative spelling of the path, i.e. one that names no host (a
+ * protocol-relative URL naming a HOST is a different string and is not ours).
+ * Collapsing is one-directional (a miss becomes a match) and never widens the
+ * ORIGIN check above it.
+ */
+const collapseSlashes = (path) => path.replace(/\/{2,}/g, '/');
+
+const parseUrl = (value, baseUrl) => {
+  try {
+    return baseUrl ? new URL(value, baseUrl) : new URL(value);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Does this one declaration name the grant broker WE inject?
+ *
+ * Resolves the declaration's own placeholders against the instance this daemon
+ * is bound to, then asks the same path predicate the adapters use — so the
+ * expanded spelling and the placeholder spelling agree, and an entry on another
+ * origin does not match just because its path resembles ours.
+ */
+export const isOurGrantBroker = (server, { instanceUrl } = {}) => {
+  const url = server?.url;
+  if (typeof url !== 'string' || url === '') return false;
+
+  const base = resolveInstance(instanceUrl);
+  let resolvedUrl = url;
+  for (const placeholder of URL_PLACEHOLDERS) {
+    if (!resolvedUrl.includes(placeholder)) continue;
+    // A placeholder we cannot resolve is not ours to judge; an entry that is
+    // only a placeholder has no origin to compare and no path to match.
+    if (base === '') return false;
+    resolvedUrl = resolvedUrl.split(placeholder).join(base);
+  }
+
+  const parsed = parseUrl(resolvedUrl);
+  const ours = base === '' ? null : parseUrl(base);
+  const onOurOrigin = (url) => url.origin + collapseSlashes(url.pathname) + url.search;
+
+  // Every candidate below is first proven to be on OUR origin, so an entry that
+  // merely resembles the broker is left alone; a match means WITHHOLD.
+  const candidates = [];
+  if (parsed) {
+    // An absolute url: our origin, or it is not our grant however its path reads.
+    if (ours && parsed.origin === ours.origin) candidates.push(onOurOrigin(parsed));
+  } else if (resolvedUrl.startsWith('/')) {
+    // A schemeless url, read BOTH ways — as a path (anchored so its path can be
+    // judged), and as a protocol-relative reference to the bound instance.
+    candidates.push(PARSE_ANCHOR + collapseSlashes(resolvedUrl));
+    const against = ours ? parseUrl(resolvedUrl, base) : null;
+    if (against && against.origin === ours.origin) candidates.push(onOurOrigin(against));
+  }
+  // An unparseable value that is neither — an unknown `${...}` expansion, a
+  // malformed string — is not an entry this daemon can identify as the broker
+  // it injects, and the injected spelling is one of the two handled above.
+  return candidates.some((candidate) => isGrantBrokerUrl(candidate));
+};
+
+/** True when the environment declares our grant broker at all. */
+export const declaresGrantBroker = (environment, opts) => (
+  Array.isArray(environment?.mcp) && environment.mcp.some((server) => isOurGrantBroker(server, opts))
+);
+
+/**
+ * Why this daemon cannot confine a seat running `adapter` with this
+ * environment — or `null` when confinement is enforced and the broker may ride.
+ * The reason vocabulary mirrors the server's, plus `sandbox_absent`.
+ */
+export const confinementReason = (environment, adapter, platform = process.platform) => {
+  if (!ADAPTERS_WITH_DEFAULT_SANDBOX.has(adapter)) return 'adapter_cannot_confine';
+
+  const sandbox = environment?.sandbox;
+  if (sandbox === null || typeof sandbox !== 'object' || Array.isArray(sandbox)) return 'sandbox_absent';
+  const declared = sandbox;
+  if (declared.mode === 'none') return 'sandbox_mode_none';
+  if (effectiveTrust(declared.trust) !== 'public') return 'sandbox_trust_not_public';
+  const mode = resolvePublicSandboxMode(declared, platform);
+  if (typeof mode !== 'string' || !ENFORCING_MODES.has(mode)) return 'sandbox_mode_unenforceable';
+  return null;
+};
+
+const detailFor = (reason, adapter, environment) => {
+  const drop = 'or drop the grant broker from this seat';
+  if (reason === 'adapter_cannot_confine') {
+    return `the seat runs the '${adapter || 'unresolved'}' adapter, which confines on no host — a declared sandbox is`
+      + ' refused rather than enforced, and an absent one is never derived; move this seat to the claude or codex'
+      + ` adapter, ${drop}`;
+  }
+  if (reason === 'sandbox_absent') {
+    return 'this seat declares no sandbox block and this daemon derives one only for the claude and codex adapters,'
+      + ` so it would run with a granter's authority and no confinement; declare sandbox.trust 'public' ${drop}`;
+  }
+  if (reason === 'sandbox_mode_none') {
+    return "the declared sandbox.mode is 'none', which no host confines; declare a confining mode"
+      + ` (e.g. 'workspace') ${drop}`;
+  }
+  if (reason === 'sandbox_mode_unenforceable') {
+    const shown = typeof environment?.sandbox?.mode === 'string'
+      ? `'${environment.sandbox.mode}'`
+      : (JSON.stringify(environment?.sandbox?.mode) ?? String(environment?.sandbox?.mode));
+    return `the declared sandbox.mode is ${shown}, which no adapter enforces on any host;`
+      + " declare one of 'workspace' / 'read-only' (or 'bwrap' on Linux)" + ` ${drop}`;
+  }
+  const trust = environment?.sandbox?.trust;
+  const shown = trust === undefined ? 'absent' : `'${String(trust)}'`;
+  return `the declared sandbox.trust is ${shown}${shown === 'absent' ? '' : ` (effective '${String(effectiveTrust(trust))}')`},`
+    + " and no host confines a seat whose trust is not 'public'; declare sandbox.trust 'public'" + ` ${drop}`;
+};
+
+/**
+ * The env a seat may actually run with: the same environment when it declares
+ * no broker WE injected, or when this daemon can confine it; otherwise the same
+ * environment minus the broker, with the refusal handed to `onRefuse`.
+ *
+ * Identity is preserved when nothing is withheld — the derive sites use
+ * `isDeepStrictEqual` against the stored record as their dirty check, so
+ * returning a fresh object every tick would rewrite the record and restart the
+ * seat forever.
+ */
+export const withholdGrantBroker = (environment, adapter, {
+  instanceUrl,
+  onRefuse,
+  platform = process.platform,
+} = {}) => {
+  if (!declaresGrantBroker(environment, { instanceUrl })) return environment;
+  const reason = confinementReason(environment, adapter, platform);
+  if (!reason) return environment;
+
+  const kept = environment.mcp.filter((server) => !isOurGrantBroker(server, { instanceUrl }));
+  const withheld = environment.mcp
+    .filter((server) => isOurGrantBroker(server, { instanceUrl }))
+    .map((server) => (typeof server?.name === 'string' && server.name ? server.name : '(unnamed)'));
+  if (typeof onRefuse === 'function') {
+    onRefuse({
+      code: GRANT_BROKER_REFUSAL_CODE,
+      decidedBy: 'daemon',
+      reason,
+      detail: detailFor(reason, adapter, environment),
+    }, withheld);
+  }
+  return { ...environment, mcp: kept };
+};
+
+export default {
+  GRANT_BROKER_REFUSAL_CODE,
+  ENFORCING_MODES,
+  isOurGrantBroker,
+  declaresGrantBroker,
+  confinementReason,
+  withholdGrantBroker,
+};