@ravefox/space 0.0.0-stage → 0.2.0

package/src/lib/daemon-watch.js

@@ -0,0 +1,115 @@
+// The live view behind `commonly daemon status --watch`: the machine, then one
+// block per supervised agent with its state, last turn, last error and the tail
+// of its log. Rendering is a pure function of its inputs so the layout can be
+// tested at fixed widths; the redraw loop lives in the command.
+
+import { seatKey } from './daemon-agent-states.js';
+
+export const WATCH_INTERVAL_MS = 2000;
+
+const ANSI = {
+  dim: '\x1b[2m',
+  bold: '\x1b[1m',
+  reset: '\x1b[0m',
+};
+
+// A redraw clears the screen and returns the cursor home. Plain ANSI, no
+// dependency; the caller decides whether to use it at all.
+export const CLEAR_SCREEN = '\x1b[H\x1b[2J';
+
+// The view is for a person watching a terminal. Anything else gets one print.
+export const shouldRedraw = ({ isTTY, env = process.env } = {}) => (
+  Boolean(isTTY) && !(env && env.NO_COLOR !== undefined && env.NO_COLOR !== '')
+);
+
+const relative = (iso, now) => {
+  if (!iso) return 'never';
+  const ms = now - new Date(iso).getTime();
+  if (!Number.isFinite(ms)) return 'unknown';
+  if (ms < 60_000) return `${Math.max(0, Math.round(ms / 1000))}s ago`;
+  if (ms < 3_600_000) return `${Math.round(ms / 60_000)}m ago`;
+  return `${Math.round(ms / 3_600_000)}h ago`;
+};
+
+// Terminal control sequences in a log or state field would reach the operator's
+// terminal: a line could clear the watch, set the title, or write the clipboard.
+// Strip OSC and CSI sequences, bare escapes, and C0/C1 controls before anything
+// else. Tabs become spaces so the column count stays honest.
+// eslint-disable-next-line no-control-regex -- matching control characters is the point
+const OSC = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?/g;
+// eslint-disable-next-line no-control-regex -- matching control characters is the point
+const CSI = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+// eslint-disable-next-line no-control-regex -- matching control characters is the point
+const ESC = /\x1b[@-Z\\-_]/g;
+// eslint-disable-next-line no-control-regex -- matching control characters is the point
+const CONTROL = /[\x00-\x08\x0a-\x1f\x7f-\x9f]/g;
+export const stripControls = (text) => String(text ?? '')
+  .replace(OSC, '').replace(CSI, '').replace(ESC, '').replace(CONTROL, '').replace(/\t/g, '  ');
+
+// Credential shapes the CLI knows, plus the forms that carry a credential in a
+// log without a known prefix: `Authorization: Basic …`, and a quoted or bare
+// `token`/`password`/`secret`/`api_key` field. Generic key/value redaction can
+// over-match, which is the cheaper error for a watch that prints logs.
+const CREDENTIAL = [
+  [/cm_(?:daemon|agent|user)_[A-Za-z0-9_-]+/g, '[redacted]'],
+  [/\bBearer\s+\S+/gi, '[redacted]'],
+  [/\bBasic\s+[A-Za-z0-9+/=._-]+/g, '[redacted]'],
+  [/(\bauthorization\s*[:=]\s*)(?:(?:basic|bearer|digest|token)\s+)?\S+/gi, '$1[redacted]'],
+  [/(["']?\b(?:token|password|passwd|secret|api[_-]?key|access[_-]?token|refresh[_-]?token)\b["']?\s*[:=]\s*)(["']?)[^\s"',}&]+\2/gi, '$1$2[redacted]$2'],
+];
+const redact = (text) => CREDENTIAL.reduce((value, [shape, replacement]) => value.replace(shape, replacement), text);
+
+// Every field the watch prints goes through here: control sequences out,
+// credentials redacted, then clipped to the width.
+const clip = (text, width) => {
+  const value = redact(stripControls(text));
+  return value.length <= width ? value : `${value.slice(0, Math.max(0, width - 1))}…`;
+};
+
+// A log line can carry a credential or a whole prompt; the same boundary covers it.
+export const safeLogLine = (line, width) => clip(line, width);
+
+// The state is the server's verdict, read by daemon-agent-states. `states` is
+// that Map. Without it (no login, or the read failed) the seat shows its local
+// process state, labelled `local`, and never a server word. An agent the verdict
+// does not list has no installation on its pod.
+export const agentStateLabel = (seat = {}, states = null) => {
+  if (!states) return `local ${seat.state || 'unknown'}`;
+  return states.get(seatKey(seat.agentName, seat.instanceId)) || 'not registered';
+};
+
+const agentBlock = (seat, { now, width, color, logTail, states }) => {
+  const dim = (text) => (color ? `${ANSI.dim}${text}${ANSI.reset}` : text);
+  const bold = (text) => (color ? `${ANSI.bold}${text}${ANSI.reset}` : text);
+  const lines = [
+    `${bold(clip(seat.recordKey || seat.agentName || 'unknown', width))}  ${agentStateLabel(seat, states)}  last turn ${relative(seat.lastTurnAt, now)}`,
+  ];
+  if (seat.lastError) lines.push(clip(`  error: ${seat.lastError}`, width));
+  for (const line of logTail || []) lines.push(dim(`  ${safeLogLine(line, Math.max(10, width - 2))}`));
+  return lines;
+};
+
+// Inputs: `machine` { name, status, lastSeenAt }, `seats` (from the daemon state
+// file), `logTails` { [recordKey || agentName]: string[] }, `states` (Map from
+// loadReachByAgent, or null), `stateNote` (why states is null), `now` (ms),
+// `width` (columns).
+export const renderDaemonWatch = ({
+  machine = {}, seats = [], logTails = {}, states = null, stateNote = '', now = Date.now(), width = 80, color = false,
+} = {}) => {
+  const bold = (text) => (color ? `${ANSI.bold}${text}${ANSI.reset}` : text);
+  const out = [
+    bold(clip(`${machine.name || 'machine'}: ${machine.status || 'unknown'}`, width)),
+    clip(`last heartbeat ${relative(machine.lastSeenAt, now)}`, width),
+  ];
+  if (stateNote) out.push(clip(stateNote, width));
+  out.push('');
+  if (!seats.length) {
+    out.push('No supervised agents on this machine.');
+    return out.join('\n');
+  }
+  for (const seat of seats) {
+    out.push(...agentBlock(seat, { now, width, color, logTail: logTails[seat.recordKey || seat.agentName] || [], states }));
+    out.push('');
+  }
+  return out.join('\n').replace(/\n+$/, '');
+};

package/src/lib/declared-mcp-guard.js

@@ -0,0 +1,284 @@
+/**
+ * Guard server-declared `environment.mcp` before the daemon adopts it.
+ *
+ * The daemon projects `AgentInstallation.config.environment` onto the OWNER's
+ * machine: every declared stdio server is spawned as the operator, and every
+ * declared http server is handed the seat token wherever the declaration puts
+ * the `${COMMONLY_AGENT_TOKEN}` placeholder. The registry PATCH that writes
+ * that declaration was pod-member gated (Vera, Connectors 69500, 2026-09-18),
+ * so a plain member could run a command on the owner's laptop or ship the
+ * token to a host they control. The server fix is owner/admin gating; this is
+ * the daemon's own layer, which must hold even if the server is wrong again.
+ *
+ * Two rules, both fail-closed:
+ *   stdio — the ENTRY must be the shipped commonly MCP server — command
+ *           `npx -y @commonlyai/mcp@<tag>`, env limited to the two canonical
+ *           placeholders, no args/cwd — or equal, as a whole entry, to one
+ *           the operator already installed by hand in the local token record.
+ *           Command alone is not enough: the shipped command with
+ *           `NODE_OPTIONS=--import=data:…` executes code, with
+ *           `npm_config_registry` fetches the package from an attacker, and
+ *           with a literal `COMMONLY_API_URL=https://attacker…` posts the
+ *           token there (sprint-review, Sharpen 69526/69534).
+ *   http  — the ENTRY, `name` aside, must BE the one http server the instance
+ *           ships: the grant broker (`grantBrokerServer`,
+ *           backend/services/grantBrokerProjectionService.ts). `transport`
+ *           exactly `http`; the url, with ONLY the two instance placeholders
+ *           resolved and nothing else expanded, of our own origin at
+ *           `/api/mcp/grants/<id>`, with no query, hash or userinfo; headers
+ *           exactly the single Bearer token placeholder; and no other field.
+ *           `sse` is not admitted at all: nothing ships it, and its GET is the
+ *           method every 3xx route in this repo answers. Pinning the ORIGIN
+ *           alone was not enough — a same-origin url whose path is a GET route
+ *           that redirects (`/api/auth/oauth/*`, both Slack and Discord
+ *           callbacks) passed the origin check and let the client leave the
+ *           instance on the hop, and an added header would have travelled with
+ *           it (TASK-150). Matched exactly rather than folded: the set this
+ *           guard ADMITS has to equal the set that is TESTED for the absence of
+ *           a redirect, and folding case or collapsing slashes widens what is
+ *           admitted while narrowing what is withheld.
+ * The rule is origin-based, not placeholder-based, because the claude CLI
+ * expands `${VAR}` and `${VAR:-default}` in url and headers from its own
+ * environment: `?t=${COMMONLY_AGENT_TOKEN:-}` is not the literal placeholder
+ * and still becomes the token, and outside the public sandbox that
+ * environment is the operator's, so `?k=${GITHUB_TOKEN}` leaks too (Vera,
+ * Connectors 69519). So any `${` other than the three known placeholders,
+ * anywhere in an entry — url, headers, command, env — is refused outright.
+ *
+ * The guarantee is instance-specific: a self-hosted proxy that redirects
+ * `/api/mcp/grants/…` breaks it in a way no test in this repo can see.
+ */
+
+const URL_PLACEHOLDERS = ['${COMMONLY_API_URL}', '${COMMONLY_INSTANCE_URL}'];
+const KNOWN_PLACEHOLDERS = [...URL_PLACEHOLDERS, '${COMMONLY_AGENT_TOKEN}'];
+const SHIPPED_PACKAGE = /^@commonlyai\/mcp(@[A-Za-z0-9._-]+)?$/;
+
+export const isShippedCommonlyMcpCommand = (command) => (
+  Array.isArray(command)
+  && command.length === 3
+  && command[0] === 'npx'
+  && command[1] === '-y'
+  && typeof command[2] === 'string'
+  && SHIPPED_PACKAGE.test(command[2])
+);
+
+const CANONICAL_STDIO_ENV = {
+  COMMONLY_API_URL: '${COMMONLY_API_URL}',
+  COMMONLY_AGENT_TOKEN: '${COMMONLY_AGENT_TOKEN}',
+};
+
+// The execution-relevant shape of a stdio entry: everything that decides what
+// runs and with what. `name` and `transport` are identity, not execution.
+const executionShape = (server) => JSON.stringify({
+  command: Array.isArray(server.command) ? server.command : null,
+  args: Array.isArray(server.args) && server.args.length ? server.args : null,
+  cwd: typeof server.cwd === 'string' ? server.cwd : null,
+  env: server.env && typeof server.env === 'object'
+    ? Object.fromEntries(Object.entries(server.env).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+    : null,
+});
+
+// The shipped server exactly: its command, only its own env keys at their
+// canonical placeholder values, nothing else that changes what executes.
+export const isShippedCommonlyMcpEntry = (server) => {
+  if (!server || typeof server !== 'object') return false;
+  if (!isShippedCommonlyMcpCommand(server.command)) return false;
+  if (Array.isArray(server.args) && server.args.length) return false;
+  if (server.cwd !== undefined) return false;
+  const env = server.env && typeof server.env === 'object' ? server.env : {};
+  return Object.entries(env).every(([key, value]) => CANONICAL_STDIO_ENV[key] === value);
+};
+
+// True when a string still contains `${` after the known placeholders are
+// removed — a `${VAR}`, `${VAR:-default}` or any other expansion the CLI
+// would resolve from an environment this declaration does not own.
+// A field the guard cannot READ is not a field it can judge. `env` and
+// `headers` are spread by every reader (`{ ...server.env }`), so a STRING there
+// becomes single-character keys and the declaration is silently dropped rather
+// than honoured — the next consumer that parses the string instead would honour
+// it, and this guard would have admitted the entry on the strength of its other
+// fields (TASK-069: judge the whole entry, not selected fields). `args` is read
+// only through `Array.isArray`, and `cwd` through `typeof === 'string'` in
+// `executionShape`, so a value of the wrong type there is dropped the same way —
+// and for `cwd` that drop is load-bearing: the normalised shape then equals an
+// installed entry that declares NO cwd, so the entry is admitted as one the
+// operator already installed (Vera, hold on #1915).
+// Fail closed: an unreadable shape is a refusal, never an absence.
+// The one http entry the server ships: url and headers as `grantBrokerServer`
+// writes them (`GRANT_BROKER_URL` / `GRANT_BROKER_AUTHORIZATION`).
+const GRANT_BROKER_PATH = /^\/api\/mcp\/grants\/[A-Za-z0-9_-]+$/;
+const GRANT_BROKER_AUTHORIZATION = 'Bearer ${COMMONLY_AGENT_TOKEN}';
+
+const sameOriginAsInstance = (url, instanceUrl) => {
+  const origin = originOf(url, instanceUrl);
+  if (!origin) return false;
+  try {
+    return origin === new URL(instanceUrl).origin;
+  } catch {
+    return false;
+  }
+};
+
+// The url is judged by what a client would carry, not by the substring the
+// origin check happens to read: the path has to be the grants path with ONE id
+// segment, and a query, a hash or userinfo is a field the origin comparison
+// does not look at but the request does carry.
+const grantBrokerUrl = (url, instanceUrl) => {
+  if (!sameOriginAsInstance(url, instanceUrl)) return false;
+  let expanded = String(url);
+  for (const placeholder of URL_PLACEHOLDERS) expanded = expanded.split(placeholder).join(instanceUrl);
+  let parsed;
+  try {
+    parsed = new URL(expanded);
+  } catch {
+    return false;
+  }
+  if (parsed.username || parsed.password || parsed.search || parsed.hash) return false;
+  return GRANT_BROKER_PATH.test(parsed.pathname);
+};
+
+/**
+ * The shipped grant broker, matched as a WHOLE entry (the http twin of
+ * `isShippedCommonlyMcpEntry`): `name` is identity — the projection suffixes it
+ * when one seat holds several grants — and every other field has to equal what
+ * `grantBrokerServer` writes, with no field added, because a field the client
+ * reads and this guard does not is exactly the shape the whole-entry rule
+ * exists to refuse (TASK-069).
+ */
+export const isShippedGrantBrokerEntry = (server, instanceUrl) => {
+  if (!server || typeof server !== 'object') return false;
+  if (server.transport !== 'http') return false;
+  const keys = Object.keys(server).filter((key) => key !== 'name').sort();
+  if (keys.join(',') !== 'headers,transport,url') return false;
+  const headers = server.headers;
+  if (!headers || typeof headers !== 'object' || Array.isArray(headers)) return false;
+  const headerKeys = Object.keys(headers);
+  if (headerKeys.length !== 1 || headerKeys[0] !== 'Authorization') return false;
+  if (headers.Authorization !== GRANT_BROKER_AUTHORIZATION) return false;
+  return grantBrokerUrl(server.url, instanceUrl);
+};
+
+const unreadableField = (server) => {
+  for (const key of ['env', 'headers']) {
+    const value = server[key];
+    if (value === undefined || value === null) continue;
+    if (typeof value !== 'object' || Array.isArray(value)) {
+      return `${key} is of type ${typeof value}, not an object`;
+    }
+    const badValue = Object.entries(value).find(([, v]) => typeof v !== 'string');
+    if (badValue) return `${key}.${badValue[0]} is not a string`;
+  }
+  if (server.cwd !== undefined && server.cwd !== null && typeof server.cwd !== 'string') {
+    return `cwd is of type ${typeof server.cwd}, not a string`;
+  }
+  if (server.args === undefined || server.args === null) return null;
+  if (!Array.isArray(server.args)) return `args is of type ${typeof server.args}, not an array`;
+  if (server.args.some((a) => typeof a !== 'string')) return 'args carries a non-string';
+  return null;
+};
+
+const hasForeignExpansion = (value) => {
+  if (typeof value !== 'string') return false;
+  let rest = value;
+  for (const placeholder of KNOWN_PLACEHOLDERS) rest = rest.split(placeholder).join('');
+  return rest.includes('${');
+};
+
+const stringsOf = (server) => {
+  const out = [];
+  if (typeof server.url === 'string') out.push(server.url);
+  for (const bag of [server.headers, server.env]) {
+    if (bag && typeof bag === 'object') out.push(...Object.values(bag));
+  }
+  if (Array.isArray(server.command)) out.push(...server.command);
+  if (Array.isArray(server.args)) out.push(...server.args);
+  return out.filter((v) => typeof v === 'string');
+};
+
+const originOf = (url, instanceUrl) => {
+  let expanded = String(url);
+  for (const placeholder of URL_PLACEHOLDERS) expanded = expanded.split(placeholder).join(instanceUrl);
+  try {
+    return new URL(expanded).origin;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * @returns {{ ok: boolean, refusals: string[] }} — one refusal line per
+ * offending server, naming it, so the daemon log says exactly what was kept
+ * off the machine.
+ */
+export const auditDeclaredMcp = (environment, { instanceUrl, allowedStdioEntries = [] } = {}) => {
+  const refusals = [];
+  const servers = environment && typeof environment === 'object' && Array.isArray(environment.mcp)
+    ? environment.mcp : [];
+  let instanceOrigin = null;
+  try {
+    instanceOrigin = new URL(instanceUrl).origin;
+  } catch {
+    instanceOrigin = null;
+  }
+
+  servers.forEach((server, index) => {
+    if (!server || typeof server !== 'object') {
+      refusals.push(`mcp[${index}] is not an object`);
+      return;
+    }
+    const name = typeof server.name === 'string' && server.name ? server.name : `mcp[${index}]`;
+    const transport = server.transport || 'stdio';
+    const unreadable = unreadableField(server);
+    if (unreadable) {
+      refusals.push(`'${name}': declares ${unreadable}, so this guard cannot judge what the entry would run; refusing it rather than reading the field as absent`);
+      return;
+    }
+    // One shape per entry. The adapters classified by which field was present,
+    // so `{transport:'http', url:<instance>, command:['sh','-c',…]}` passed an
+    // origin check here and ran as stdio there with the token substituted
+    // (#1764 fixes the adapters; the guard refuses the shape outright).
+    if (server.command !== undefined && server.url !== undefined) {
+      refusals.push(`'${name}': declares both a command and a url; one entry is one transport`);
+      return;
+    }
+    if (transport === 'stdio' && server.url !== undefined) {
+      refusals.push(`'${name}': stdio entry carries a url`);
+      return;
+    }
+    if ((transport === 'http' || transport === 'sse') && server.command !== undefined) {
+      refusals.push(`'${name}': ${transport} entry carries a command`);
+      return;
+    }
+    const foreign = stringsOf(server).find(hasForeignExpansion);
+    if (foreign !== undefined) {
+      refusals.push(`'${name}': ${JSON.stringify(foreign)} contains an expansion other than the instance placeholders; the CLI would resolve it from this machine's environment`);
+      return;
+    }
+    if (transport === 'stdio') {
+      if (isShippedCommonlyMcpEntry(server)) return;
+      const shape = executionShape(server);
+      if (allowedStdioEntries.some((allowed) => executionShape(allowed) === shape)) return;
+      const why = isShippedCommonlyMcpCommand(server.command)
+        ? `carries env/args/cwd beyond the shipped server's own (${Object.keys(server.env || {}).filter((k) => CANONICAL_STDIO_ENV[k] !== server.env[k]).join(', ') || 'args/cwd'})`
+        : `command ${JSON.stringify(server.command)} is not the shipped commonly MCP server`;
+      refusals.push(`'${name}': declared stdio entry ${why}, and no entry installed on this machine matches it as a whole`);
+      return;
+    }
+    if (transport === 'http' || transport === 'sse') {
+      if (transport === 'http' && isShippedGrantBrokerEntry(server, instanceUrl)) return;
+      refusals.push(`'${name}': declared ${transport} entry ${JSON.stringify(server.url)} is not the one http server this instance ships; a declaration is admitted only as the grant broker (transport 'http', url ${instanceOrigin || instanceUrl}/api/mcp/grants/<id> with no query or fragment, headers exactly {'Authorization': 'Bearer \${COMMONLY_AGENT_TOKEN}'}, and no other field), and 'sse' is not admitted at all`);
+      return;
+    }
+    refusals.push(`'${name}': unknown transport ${JSON.stringify(transport)}`);
+  });
+
+  return { ok: refusals.length === 0, refusals };
+};
+
+/** The stdio entries an operator has already placed in a local token record. */
+export const installedStdioEntries = (record) => (
+  Array.isArray(record?.environment?.mcp)
+    ? record.environment.mcp
+      .filter((s) => s && typeof s === 'object' && (s.transport || 'stdio') === 'stdio' && Array.isArray(s.command))
+    : []
+);

package/src/lib/default-environment.js

@@ -0,0 +1,207 @@
+/**
+ * The commonly MCP server every wrapper seat gets by default (ADR-008 `mcp[]`).
+ *
+ * One declaration, three consumers: `agent attach`, the COMMONLY_AGENT_TOKEN
+ * bootstrap in `agent run`, and the daemon's per-seat token provisioning. The
+ * third consumer was missing until 2026-09-18 — a seat installed server-side
+ * (nobody ever ran `agent attach` on that host) got a token record carrying
+ * runtime model/effort and no `mcp[]` at all, so the CLI it spawned had no
+ * `commonly_*` tools and could not post; the operator hand-added the entry to
+ * get the seat working (C4 run, TASK-048).
+ *
+ * Only adapters with a real `mcp[]` consumption path get a default:
+ *   claude — `--mcp-config` (adapters/claude.js)
+ *   codex  — `-c mcp_servers.*` overrides (adapters/codex.js; added after the
+ *            2026-07-22 as-operator attribution incident, where an MCP-less
+ *            codex agent posted through the operator's own CLI profile because
+ *            it had no commonly_* tool of its own)
+ *   pi     — stdio servers from the environment spec (adapters/pi.js)
+ *   opencode — per-spawn config file with local/remote MCP entries (adapters/opencode.js)
+ *   qwen — per-spawn --mcp-config with file-backed stdio credentials (adapters/qwen.js)
+ *   dsh — per-spawn --patch with file-backed stdio credentials (adapters/dsh.js)
+ *   goose — per-spawn --with-extension with file-backed stdio credentials (adapters/goose.js)
+ * `stub` has no consumption path and must keep being handed `environment: null`.
+ *
+ * The placeholders are substituted at spawn time by the adapter, so the
+ * declaration itself carries no secret and is safe to persist to a token file.
+ */
+
+import { normalizeSandboxTrust } from './environment.js';
+
+export const ADAPTERS_WITH_DEFAULT_MCP = new Set(['claude', 'codex', 'pi', 'opencode', 'qwen', 'dsh', 'goose']);
+
+/**
+ * The adapters that take the default sandbox — a strict subset of the ones that
+ * consume `mcp[]`, and of the ones that enforce a sandbox (below).
+ *
+ * Goose and pi enforce an explicitly declared public sandbox but are not handed
+ * this default. Goose: a default cannot supply its required provider and model.
+ * pi (F113b): a public pi turn has no shell and no file tools, the same as every
+ * public adapter, and the daemon derives pi's environment for the private fleet
+ * seats that write code with exactly those tools. A derived public default would
+ * strip them from every one of those seats. A pi seat that takes instructions
+ * from strangers declares `sandbox.trust: 'public'` and is confined then.
+ */
+export const ADAPTERS_WITH_DEFAULT_SANDBOX = new Set(['claude', 'codex', 'opencode', 'qwen']);
+
+// Adapters that confine a public turn themselves. This is wider than the set
+// above: Goose enforces Seatbelt/bwrap and pi enforces Seatbelt (macOS only;
+// adapters/pi.js), and neither is handed the default block (see above). The
+// attach gate (agent.js resolveAttachSandbox) reads this set, not the default
+// one, or an explicitly configured public Goose or pi seat is refused before its
+// adapter runs (D247 walk, 11-04; F113b).
+export const ADAPTERS_WITH_SANDBOX_ENFORCEMENT = new Set([...ADAPTERS_WITH_DEFAULT_SANDBOX, 'goose', 'pi']);
+
+// Adapters that may receive a room grant: each confines a public seat AND keeps
+// the per-spawn credential out of its own tools' reach (OpenCode: F175a, its
+// external_directory deny with the credential outside --dir; pi: F175c, a
+// public turn with no built-in tool, and the credential file deleted once pi
+// has loaded its extensions; Qwen and Goose: F175d, a public turn that offers no
+// file or shell tool, with the broker behind the stdio bridge so the token
+// stays in one file). Narrower than the sandbox sets above on purpose, and
+// mirrored by the server's CONFINING_ADAPTERS
+// (backend/services/grantBrokerConfinement.ts).
+export const ADAPTERS_WITH_GRANT_BROKER = new Set(['claude', 'codex', 'opencode', 'pi', 'qwen', 'goose']);
+
+// The modes a jail enforces, by host: what an adapter's spawn turns into
+// Seatbelt on macOS and bubblewrap on Linux.
+const SEATBELT_MODES = new Set(['workspace', 'read-only']);
+const BWRAP_MODES = new Set(['bwrap']);
+
+// F175c, F175d: adapters in the set above that hold a grant ONLY on a confined
+// public seat, in the modes each host's jail enforces; a host with no entry has
+// no jail for it. Each runs a private seat with no sandbox at all, so a private
+// seat is never confined. pi confines in macOS Seatbelt alone
+// (adapters/pi.js assertSandboxSupported). Naming the agent on the grant (F94)
+// does not lift this, unlike the sandbox refusals of Claude, Codex and OpenCode.
+// Mirrored by the server's PUBLIC_ONLY_GRANT_ADAPTERS.
+export const ADAPTERS_WITH_PUBLIC_ONLY_GRANT = new Map([
+  ['pi', Object.freeze({ darwin: SEATBELT_MODES })],
+  ['qwen', Object.freeze({ darwin: SEATBELT_MODES, linux: BWRAP_MODES })],
+  ['goose', Object.freeze({ darwin: SEATBELT_MODES, linux: BWRAP_MODES })],
+]);
+
+/**
+ * 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.
+ *
+ * Claude, codex, opencode and qwen receive this default block
+ * (ADAPTERS_WITH_DEFAULT_SANDBOX). Goose and pi support explicitly configured
+ * public confinement, but are not defaulted into it (see the set's comment).
+ * Grant-broker eligibility is its own list (ADAPTERS_WITH_GRANT_BROKER).
+ */
+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 = () => ({
+  name: COMMONLY_MCP_SERVER_NAME,
+  transport: 'stdio',
+  command: ['npx', '-y', '@commonlyai/mcp@latest'],
+  env: {
+    COMMONLY_API_URL: '${COMMONLY_API_URL}',
+    COMMONLY_AGENT_TOKEN: '${COMMONLY_AGENT_TOKEN}',
+  },
+});
+
+/** The default `mcp[]` for an adapter, or [] when it has no consumption path. */
+export const defaultMcpServers = (adapterName) => (
+  ADAPTERS_WITH_DEFAULT_MCP.has(adapterName) ? [commonlyMcpServer()] : []
+);
+
+/**
+ * Ensure `environment` declares the commonly MCP server, touching nothing that
+ * is already declared.
+ *
+ * The predicate is "is there an mcp entry named commonly?", not "is mcp[]
+ * absent?" — the daemon projects live room grants into this same array, so a
+ * seat can arrive with `mcp: [<grant broker>]` and no kernel server, and it is
+ * exactly as tool-less as one with no `mcp` key at all.
+ *
+ * Returns the SAME reference when nothing needs adding, so callers can use the
+ * identity as a dirty check. A declared commonly entry is never replaced or
+ * duplicated — an operator's hand-set command (a pinned version, a staging
+ * checkout) wins over the shipped default — and a non-consuming adapter is
+ * returned untouched. A malformed (non-object) spec is not ours to repair.
+ */
+export const withDefaultMcpServer = (environment, adapterName) => {
+  if (!ADAPTERS_WITH_DEFAULT_MCP.has(adapterName)) return environment;
+  if (environment !== null && environment !== undefined
+    && (typeof environment !== 'object' || Array.isArray(environment))) {
+    return environment;
+  }
+  const declared = Array.isArray(environment?.mcp) ? environment.mcp : null;
+  if (declared && declared.some((server) => server?.name === COMMONLY_MCP_SERVER_NAME)) {
+    return environment;
+  }
+  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.
+ */
+/**
+ * Whether an environment declares a sandbox the adapters ENFORCE: a public or
+ * workspace trust (whose mode they resolve, and refuse to spawn without, every
+ * adapter but claude refusing `workspace` outright, TASK-294) 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.
+ *
+ * Normalized first (Wren 71719): a legacy `internal` means `public` here as it
+ * does to the attach gate and the adapters.
+ */
+export const declaresEnforcedSandbox = (environment) => {
+  const sandbox = normalizeSandboxTrust(environment?.sandbox);
+  return sandbox !== null && typeof sandbox === 'object'
+    && sandbox.mode !== 'none'
+    && (sandbox.trust === 'public' || sandbox.trust === 'workspace'
+      || typeof sandbox.mode === 'string');
+};
+
+export const withDefaultSandbox = (environment) => {
+  if (environment !== null && environment !== undefined
+    && (typeof environment !== 'object' || Array.isArray(environment))) {
+    return environment;
+  }
+  // `mode: 'none'`, an empty block and a missing one are replaced; the ORIGINAL
+  // block is what is returned when it is enforced.
+  if (declaresEnforcedSandbox(environment)) 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);
+};