@ravefox/space 0.0.0-stage → 0.2.0

package/src/lib/adapters/goose.js

@@ -0,0 +1,510 @@
+/** Goose 1.54.0 wrapper. Public seats expose only the Commonly MCP extension. */
+import { requireSeatModel } from './seat-model.js';
+import { probeVersion } from './tested-version.js';
+import { spawn as childSpawn, spawnSync } from 'node:child_process';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+import { buildMemoryPreamble } from '../memory-bridge.js';
+import { OWNER_WOKEN_MEMORY_TOOLS } from '../public-withheld-tools.js';
+import { effectiveSandboxTrust, refuseWorkspaceTrust, validateEnvironmentSpec } from '../environment.js';
+import { armCredentialRelease, writeCredentialFile } from '../credential-file.js';
+import { MCP_READY_FILE_ENV, bridgeReadyFile, commonlyMcpReadyFile } from '../mcp-ready.js';
+import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
+import { prepareMcpSpawn, selectedMcpVersionDir } from '../mcp-home.js';
+import { describeMcpCommand } from '../mcp-server-version.js';
+import { resolveProviderKeyFile, startProviderProxy } from '../provider-proxy.js';
+import { resolvePublicSandboxMode } from '../sandbox/mode.js';
+import { detectBwrap, wrapArgvWithBwrap } from '../sandbox/bwrap.js';
+import { wrapArgvWithSeatbelt } from '../sandbox/seatbelt.js';
+import { refuseWorkspaceHoldingTurnDirs } from '../sandbox/turn-dir.js';
+import { adapterFailure, spawnCredentials } from '../upstream-refusal.js';
+import { isOurGrantBroker } from '../grant-broker-guard.js';
+import { brokerBridgeEntry } from './broker-bridge-entry.js';
+import { BRIDGE_PATH } from './codex-broker-bridge.mjs';
+
+// A version enters this list only after a real headless turn with that binary.
+// Each version here is proven by the real-binary smoke test on macOS and Linux
+// (.github/workflows/goose-public-proof.yml carries one pinned row per version).
+// 1.56.0 is NOT admitted (11-04, F113c): its state-machine agent loop offers the
+// model a `load_skill` operation on every turn that the extension allowlist
+// cannot remove, so a stranger could read any skill under the seat's working
+// directory (.agents/.goose/.claude skills) and Goose's builtin skills. The
+// proof failed on both hosts at the allowlist check. Re-admit a version only
+// once skills can be switched off for public turns and the proof is green.
+export const TESTED_GOOSE_VERSIONS = Object.freeze(['1.54.0']);
+const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
+const TERMINATION_GRACE_MS = 5000;
+const DEFAULT_PROVIDER_HOST = 'https://litellm.commonly.me';
+const DEFAULT_PROVIDER_KEY = 'COMMONLY_LITELLM_KEY';
+const PLACEHOLDER_RE = /\$\{(COMMONLY_[A-Z_]+)\}/g;
+const SAFE_ENV = /^(?:PATH|LANG|LC_[A-Z_]+|TERM|USER|LOGNAME|NO_COLOR|CI|SSL_CERT_FILE|SSL_CERT_DIR)$/;
+const safeEnv = (env) => Object.fromEntries(Object.entries(env).filter(([name]) => SAFE_ENV.test(name)));
+
+// Goose renders a recipe file as a template before it reads it, so a stranger's
+// `{{ … }}` or `{% include %}` in the prompt would run. Every `{` is written as
+// an expression that prints one, which renders back to exactly the given text.
+const templateLiteral = (value) => {
+  if (typeof value === 'string') return value.replace(/\{/g, "{{ '{' }}");
+  if (Array.isArray(value)) return value.map(templateLiteral);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([name, item]) => [name, templateLiteral(item)]));
+  }
+  return value;
+};
+// Explicit API-only list: new MCP tools do not silently gain public authority.
+// attach_file reads this process's filesystem, including its credential file.
+// catch_up is left out too: it moves the read cursor past history unread, so a
+// public seat past 50 unseen falls back to continueAnyway, which it keeps.
+// Self-install, the memory writes (log_cycle included) and delete_message are
+// left out on every public seat (F118, F141, PUBLIC_ONLY_WITHHELD_TOOLS);
+// reading memory stays. The writes join only on a turn its owner woke (F145).
+export const PUBLIC_GOOSE_TOOLS = Object.freeze([
+  'commonly_get_started', 'commonly_post_message', 'commonly_claim_message',
+  'commonly_release_claim', 'commonly_get_messages', 'commonly_get_context',
+  'commonly_list_files', 'commonly_list_artifacts', 'commonly_read_file',
+  'commonly_get_posts', 'commonly_post_thread_comment', 'commonly_get_tasks',
+  'commonly_create_task', 'commonly_claim_task', 'commonly_watch_task',
+  'commonly_complete_task', 'commonly_update_task', 'commonly_create_pod',
+  'commonly_list_pods', 'commonly_read_agent_memory',
+  'commonly_dm_agent', 'commonly_ask_agent', 'commonly_request_decision',
+  'commonly_respond_to_ask', 'commonly_react_to_message',
+]);
+
+const publicGooseTools = (ctx) => (ctx?.ownerWoken === true
+  ? [...PUBLIC_GOOSE_TOOLS, ...OWNER_WOKEN_MEMORY_TOOLS]
+  : PUBLIC_GOOSE_TOOLS);
+
+export const assertSandboxSupported = (environment = {}) => {
+  const sandbox = environment?.sandbox || {};
+  refuseWorkspaceTrust(sandbox, 'goose');
+  if (effectiveSandboxTrust(sandbox.trust) === 'public') {
+    if (sandbox.filesystem?.['read-outside']?.length) {
+      throw new Error('goose adapter: public seats do not allow sandbox.filesystem.read-outside');
+    }
+    if (!['workspace', 'read-only', 'bwrap'].includes(resolvePublicSandboxMode(sandbox))) {
+      throw new Error('goose adapter: public seats require an enforced sandbox');
+    }
+    if (!environment.provider || !environment.model) {
+      throw new Error('goose adapter: public seats require an explicit provider and model');
+    }
+    if (sandbox.network?.policy === 'restricted') {
+      throw new Error('goose adapter: restricted networking is not supported');
+    }
+  } else if (sandbox.mode && sandbox.mode !== 'none') {
+    throw new Error(`goose adapter: sandbox.mode=${sandbox.mode} cannot be enforced by Goose`);
+  }
+};
+
+// The version is read whole or not at all. A prerelease is kept (`1.54.0-rc.1` is not the tested 1.54.0), and a
+// version touching a letter, digit, `.`, `+`, `-` or `~` on either side (`1.54.0rc1`, `1.54.0.1`, `2.1.54.0`,
+// `v1.54.0`, `1.54.0+build`, the Debian-style `1.54.0~rc1`) reads as unknown, so the public gate never admits part
+// of a longer string.
+const versionOf = (value) => String(value || '').trim()
+  .match(/(?<![\w.+~-])(\d+\.\d+\.\d+(?:-[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*)?)(?![\w.+~-])/)?.[1] || null;
+
+/** Goose splits this string itself; reject quotes it cannot represent safely. */
+const gooseWord = (value) => {
+  const word = String(value);
+  if (!word || /["\r\n\0]/.test(word)) throw new Error('goose adapter: MCP argument contains an unsupported character');
+  return `"${word}"`;
+};
+
+const substitute = (value, ctx) => String(value).replace(PLACEHOLDER_RE, (whole, name) => ({
+  COMMONLY_TOKEN_FILE: ctx.credentialFile,
+  COMMONLY_API_URL: ctx.instanceUrl,
+  COMMONLY_INSTANCE_URL: ctx.instanceUrl,
+}[name] || whole));
+
+/**
+ * F175d: the grant broker as a recipe extension running our stdio bridge, or
+ * null when this entry can't be wired. Goose fills an HTTP header from its own
+ * environment or a literal in the recipe, and neither keeps the token to the
+ * credential file. No `available_tools`: the broker lists only what the grant
+ * holds, and re-checks the grant and this seat on every call.
+ */
+export const bridgedGooseExtension = (server, ctx) => {
+  const entry = brokerBridgeEntry(server, ctx);
+  if (entry.skip) {
+    // eslint-disable-next-line no-console
+    console.warn(`[goose] grant broker ${server.name}: ${entry.skip}, so it is not wired for this spawn.`);
+    return null;
+  }
+  const readyPath = bridgeReadyFile(server, ctx);
+  return {
+    type: 'stdio', name: server.name, cmd: entry.command, args: entry.args,
+    envs: readyPath ? { ...entry.env, [MCP_READY_FILE_ENV]: readyPath } : entry.env,
+  };
+};
+
+/** The flag contains paths and URLs only. Literal MCP secrets cannot ride argv. */
+export const extensionArgs = (servers, ctx) => {
+  const args = [];
+  // A broker is the one extra a public seat may hold. A private seat has no
+  // jail, so the guard withholds its broker, and an entry that reaches here
+  // anyway meets the HTTP refusal below.
+  const declared = Array.isArray(servers) ? servers : [];
+  const brokers = ctx.publicSeat
+    ? declared.filter((server) => isOurGrantBroker(server, { instanceUrl: ctx.instanceUrl })) : [];
+  const others = declared.filter((server) => !brokers.includes(server));
+  if (ctx.publicSeat && others.length !== 1) {
+    throw new Error('goose adapter: public seats require only the Space MCP extension');
+  }
+  for (const server of others) {
+    if (ctx.publicSeat && (server.name !== 'commonly' || (server.transport || 'stdio') !== 'stdio'
+      || !describeMcpCommand(server.command)?.isCommonly)) {
+      throw new Error('goose adapter: public seats require only the Space stdio MCP extension');
+    }
+    if (!/^[A-Za-z0-9_-]{2,}$/.test(server?.name || '')) {
+      throw new Error('goose adapter: MCP server needs a safe name');
+    }
+    const transport = server.transport || 'stdio';
+    if (transport === 'http') {
+      if (server.headers && Object.keys(server.headers).length) {
+        throw new Error(`goose adapter: HTTP MCP server ${server.name} has headers Goose cannot deliver without exposing credentials`);
+      }
+      if (typeof server.url !== 'string' || !server.url) throw new Error(`goose adapter: ${server.name} has no HTTP URL`);
+      const url = substitute(server.url, ctx);
+      const parsed = new URL(url);
+      if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+        throw new Error(`goose adapter: HTTP MCP server ${server.name} contains a credential-bearing URL`);
+      }
+      if (parsed.origin !== new URL(ctx.instanceUrl).origin) {
+        throw new Error(`goose adapter: HTTP MCP server ${server.name} is outside the Space instance`);
+      }
+      args.push('--with-streamable-http-extension', url);
+      continue;
+    }
+    if (transport !== 'stdio' || !Array.isArray(server.command) || !server.command.length) {
+      throw new Error(`goose adapter: MCP server ${server.name} has an unsupported transport or command`);
+    }
+    const command = prepareMcpSpawn(server.command, { apiUrl: ctx.instanceUrl, publicSeat: ctx.publicSeat });
+    if (!command) throw new Error('goose adapter: Space MCP is not prepared for this public turn');
+    if (ctx.publicSeat) {
+      const tree = selectedMcpVersionDir(command);
+      if (!tree || !isAbsolute(tree)) throw new Error('goose adapter: public MCP requires an absolute prepared entry');
+      ctx.mcpReadDirectories?.push(tree);
+    }
+    const delivery = deliverSeatCredential({ ...server, command }, {
+      credentialFile: ctx.credentialFile, label: 'goose',
+    });
+    if (delivery.delivered === 'env' || delivery.delivered === 'unavailable') {
+      throw new Error(`goose adapter: MCP server ${server.name} cannot receive its credential by file`);
+    }
+    const env = Object.entries(delivery.env).map(([name, value]) => {
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error('goose adapter: invalid MCP environment key');
+      // COMMONLY_MCP_PUBLIC_SEAT is the constant '1' (public-seat-mcp-flag.js),
+      // never a secret, so it may ride either path.
+      if (!['COMMONLY_TOKEN_FILE', 'COMMONLY_API_URL', 'COMMONLY_INSTANCE_URL', 'COMMONLY_MCP_PUBLIC_SEAT'].includes(name)) {
+        throw new Error(`goose adapter: MCP server ${server.name} has ${name}, which cannot safely ride a CLI flag`);
+      }
+      const resolved = substitute(value, ctx);
+      if (resolved.includes('${COMMONLY_AGENT_TOKEN}') || (ctx.runtimeToken && resolved.includes(ctx.runtimeToken))) {
+        throw new Error(`goose adapter: MCP server ${server.name} would expose the runtime token in argv`);
+      }
+      return gooseWord(`${name}=${resolved}`);
+    });
+    const commandWords = command.map((part) => gooseWord(substitute(part, ctx)));
+    if (ctx.publicSeat) {
+      // F460: our server names the file it writes once it has read the
+      // credential (a path, not a secret). An older warm build refuses.
+      const readyPath = commonlyMcpReadyFile(server, command, ctx, { env: delivery.env });
+      ctx.publicExtensions.push({ type: 'stdio', name: server.name, cmd: command[0],
+        args: command.slice(1).map((part) => substitute(part, ctx)),
+        envs: {
+          ...Object.fromEntries(Object.entries(delivery.env).map(([name, value]) => [name, substitute(value, ctx)])),
+          ...(readyPath ? { [MCP_READY_FILE_ENV]: readyPath } : {}),
+        },
+        available_tools: publicGooseTools(ctx),
+      });
+    } else {
+      args.push('--with-extension', `${server.name}:${[...env, ...commandWords].join(' ')}`);
+    }
+  }
+  for (const server of brokers) {
+    const extension = bridgedGooseExtension(server, ctx);
+    if (extension) {
+      ctx.publicExtensions.push(extension);
+      ctx.brokerExtensions?.add(extension.name);
+      ctx.mcpReadDirectories?.push(BRIDGE_PATH);
+    }
+  }
+  return args;
+};
+
+export const readGooseStream = (stdout) => {
+  let text = '';
+  let error = null;
+  let complete = false;
+  for (const line of String(stdout || '').split('\n')) {
+    let event;
+    try { event = JSON.parse(line); } catch { continue; }
+    if (event?.type === 'complete') complete = true;
+    if (event?.type === 'error') error = event.error?.message || event.message || 'Goose turn failed';
+    if (event?.type === 'message' && event.message?.role === 'assistant'
+      && event.message?.metadata?.userVisible !== false) {
+      const body = event.message.content?.filter((item) => item?.type === 'text' && typeof item.text === 'string')
+        .map((item) => item.text).join('') || '';
+      if (body.trim()) text = body.trim();
+    }
+  }
+  return { text, error, complete };
+};
+
+const runGoose = ({
+  binary, args, cwd, env, timeoutMs, credentials, optionalExtensions = new Set(), spawnImpl = childSpawn,
+}) => new Promise((resolve, reject) => {
+  const child = spawnImpl(binary, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+  let stdout = '';
+  const stdoutDecoder = new StringDecoder('utf8');
+  let stderr = '';
+  let timedOut = false;
+  let streamOverflow = false;
+  let extensionFailure = null;
+  let settled = false;
+  let killTimer;
+  const finish = (error, result) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    clearTimeout(killTimer);
+    if (error) reject(error); else resolve(result);
+  };
+  const timer = setTimeout(() => {
+    timedOut = true;
+    child.kill('SIGTERM');
+    killTimer = setTimeout(() => child.kill('SIGKILL'), TERMINATION_GRACE_MS);
+  }, timeoutMs);
+  child.stdout?.on('data', (chunk) => {
+    if (streamOverflow) return;
+    stdout += stdoutDecoder.write(chunk);
+    if (stdout.length > 2 * 1024 * 1024) {
+      streamOverflow = true;
+      stdout = '';
+      clearTimeout(timer);
+      child.kill('SIGTERM');
+      killTimer = setTimeout(() => child.kill('SIGKILL'), TERMINATION_GRACE_MS);
+    }
+  });
+  child.stderr?.on('data', (chunk) => {
+    const received = chunk.toString();
+    // A broker that won't start (a grant refused at the door, the instance
+    // down) costs that grant, not the turn: the seat still answers the pod.
+    extensionFailure ||= [...(stderr + received).matchAll(/Failed to start extension '([^']+)'[^\n]*/g)]
+      .find((failure) => !optionalExtensions.has(failure[1]))?.[0] || null;
+    stderr = (stderr + received).slice(-8192);
+  });
+  child.on('error', (error) => finish(error));
+  child.on('close', (code) => {
+    stdout += stdoutDecoder.end();
+    if (timedOut) return finish(new Error(`goose adapter: timed out after ${timeoutMs}ms`));
+    if (streamOverflow) return finish(new Error('goose adapter: stream exceeded 2 MiB'));
+    const result = readGooseStream(stdout);
+    // Goose reports an extension startup failure on stderr yet exits 0 and
+    // lets the model answer without that tool. A Commonly seat cannot silently
+    // lose its only path back to the pod.
+    if (code !== 0 || result.error || !result.complete || extensionFailure) {
+      return finish(adapterFailure('goose', extensionFailure || result.error || stderr.trim() || `exit ${code}; incomplete stream`, {
+        credentials, exitCode: code, limit: 500,
+      }));
+    }
+    return finish(null, result.text);
+  });
+});
+
+export default {
+  requiresModel: true,
+  name: 'goose',
+  providerKeyEnv: DEFAULT_PROVIDER_KEY,
+  supportsProvider: true,
+
+  async validateEnvironment(environment, workspacePath) {
+    assertSandboxSupported(environment);
+    const validation = validateEnvironmentSpec(environment || {});
+    if (!validation.ok) throw new Error(validation.errors.join('; '));
+    return resolveProviderKeyFile(environment?.provider, workspacePath, 'Goose', { environment });
+  },
+
+  async detect() {
+    const result = spawnSync('goose', ['--version'], { encoding: 'utf8', timeout: 5000 });
+    if (result.error || result.status !== 0) return null;
+    const where = spawnSync('which', ['goose'], { encoding: 'utf8', timeout: 5000 });
+    return { path: String(where.stdout || 'goose').trim() || 'goose', version: versionOf(result.stdout) || 'unknown' };
+  },
+
+  async spawn(prompt, ctx = {}) {
+    const seatModel = requireSeatModel(ctx.environment, 'goose', true);
+    const keyFile = await this.validateEnvironment(ctx.environment, ctx.cwd);
+    const isPublic = effectiveSandboxTrust(ctx.environment?.sandbox?.trust) === 'public';
+    const sourceEnv = ctx.env || process.env;
+    const configured = ctx.environment?.provider;
+    const key = isPublic ? '' : configured
+      ? (await readFile(keyFile, 'utf8')).trim() : sourceEnv[DEFAULT_PROVIDER_KEY];
+    if (!isPublic && !key) throw new Error(`goose adapter: ${configured ? 'provider.keyFile' : DEFAULT_PROVIDER_KEY} is missing`);
+    const baseUrl = new URL(configured?.baseURL || `${DEFAULT_PROVIDER_HOST}/v1`);
+    if (!/^https?:$/.test(baseUrl.protocol) || baseUrl.username || baseUrl.password || baseUrl.search || baseUrl.hash) {
+      throw new Error('goose adapter: provider.baseURL must be a plain HTTP(S) URL');
+    }
+    const model = seatModel;
+    const binary = ctx._binaryPath || (isPublic
+      ? String(spawnSync('which', ['goose'], { encoding: 'utf8', env: sourceEnv }).stdout || '').trim()
+      : 'goose');
+    if (isPublic && !isAbsolute(binary)) throw new Error('goose adapter: public seats require an absolute Goose executable');
+    // A cold first launch can take several seconds while macOS scans the binary.
+    // Async and cached per binary (tested-version.js probeVersion): a
+    // synchronous probe stalled every other seat's provider proxy on the
+    // daemon's loop for as long as this cold start took.
+    const version = ctx._version || await probeVersion(binary, {
+      env: safeEnv(sourceEnv), timeoutMs: 30000, parse: versionOf,
+    });
+    if (!TESTED_GOOSE_VERSIONS.includes(version)) {
+      if (isPublic) throw new Error(`goose adapter: public seats refuse untested version ${version || 'unknown'}`);
+      // eslint-disable-next-line no-console
+      console.warn(`[goose] installed ${version || 'unknown'} differs from smoke-tested ${TESTED_GOOSE_VERSIONS.join(', ')}; private seat continues`);
+    }
+    if (isPublic) await refuseWorkspaceHoldingTurnDirs({ workspace: ctx.cwd, seat: 'public Goose agents' });
+    // Keep child-writable state separate from adapter-owned config and keys, as
+    // qwen does (F219). The jail reads tempDir and cannot change it: the
+    // Commonly MCP child runs in the jail, so the credential stays readable.
+    const tempDir = await mkdtemp(join(tmpdir(), 'commonly-goose-'));
+    const home = await mkdtemp(join(tmpdir(), 'commonly-goose-home-'));
+    let proxy;
+    let credentialRelease = null;
+    let reply = null;
+    let cleanupFailure = null;
+    try {
+      const credential = writeCredentialFile(ctx.runtimeToken, {
+        root: tempDir, agentName: ctx.agentName || 'agent',
+      });
+      // F460: the jail writes only the seat's home, so a public seat's MCP
+      // servers write their ready files there.
+      const readyFileDir = isPublic && credential ? join(home, 'mcp-ready') : null;
+      if (readyFileDir) await mkdir(readyFileDir, { recursive: true, mode: 0o700 });
+      const readyFiles = [];
+      // No tokenFile: nothing here reads one, so the token is never on disk.
+      if (isPublic) proxy = await startProviderProxy({
+        provider: configured, keyFile, adapterLabel: 'Goose', pinnedModel: model,
+      });
+      const mcpReadDirectories = [];
+      const publicExtensions = [];
+      const brokerExtensions = new Set();
+      // Node's compiled-in OpenSSL config can sit outside the permitted tree
+      // (including hostedtoolcache on CI). Use our empty config, retaining
+      // Node's bundled TLS roots, instead of granting host configuration reads.
+      const opensslConfig = join(tempDir, 'openssl.cnf');
+      if (isPublic) await writeFile(opensslConfig, '', { mode: 0o600 });
+      // The recipe's own directory is the template include root, so it holds
+      // the recipe alone, never the credential file.
+      const recipeDir = join(tempDir, 'recipe');
+      const recipePath = join(recipeDir, 'public-recipe.json');
+      const args = [
+        'run', '--no-session', ...(!isPublic ? ['--no-profile', '--with-builtin', 'developer'] : []),
+        ...(isPublic ? ['--recipe', recipePath] : []),
+        '--output-format', 'stream-json', '--provider', 'openai', '--model', model,
+        ...extensionArgs(ctx.environment?.mcp, {
+          credentialFile: credential?.path || '', instanceUrl: ctx.instanceUrl || '',
+          runtimeToken: ctx.runtimeToken || '',
+          publicSeat: isPublic, ownerWoken: ctx.ownerWoken, mcpReadDirectories, publicExtensions, brokerExtensions,
+          readyFileDir, readyFiles,
+        }),
+        ...(!isPublic ? ['-t', buildMemoryPreamble(prompt, ctx.memoryLongTerm, { freshSession: true })] : []),
+      ];
+      if (isPublic) await mkdir(recipeDir, { mode: 0o700 });
+      if (isPublic) await writeFile(recipePath, JSON.stringify(templateLiteral({ version: '1.0.0',
+        title: 'Space public seat', description: 'Only audited Space API tools are available.',
+        instructions: 'Respond to the user using the available Space tools.',
+        extensions: publicExtensions.map((extension) => ({ ...extension,
+          envs: { ...extension.envs, OPENSSL_CONF: opensslConfig },
+        })),
+        // F118, F145: a public seat reads its memory, and is offered a write
+        // only on a turn its owner woke.
+        prompt: buildMemoryPreamble(prompt, ctx.memoryLongTerm, { freshSession: true, memoryReadOnly: ctx.ownerWoken !== true }),
+      })), { mode: 0o600 });
+      const env = {
+        ...safeEnv(sourceEnv),
+        HOME: home,
+        TMPDIR: home,
+        XDG_CONFIG_HOME: join(home, 'config'),
+        XDG_DATA_HOME: join(home, 'data'),
+        GOOSE_PATH_ROOT: home,
+        GOOSE_PROVIDER: 'openai',
+        GOOSE_MODEL: model,
+        GOOSE_MODE: 'auto',
+        GOOSE_TELEMETRY_ENABLED: 'false',
+        ...(isPublic ? { OPENSSL_CONF: opensslConfig } : {}),
+        OPENAI_HOST: proxy ? new URL(proxy.baseURL).origin : baseUrl.origin,
+        OPENAI_BASE_PATH: `${new URL(proxy?.baseURL || baseUrl).pathname.replace(/\/$/, '')}/chat/completions`.replace(/^\//, ''),
+        OPENAI_API_KEY: proxy ? proxy.token : key,
+      };
+      withholdRuntimeCredential(env, { credentialFile: credential?.path || null });
+      const requestedTimeout = Number(ctx.timeoutMs);
+      const timeoutMs = Number.isFinite(requestedTimeout) && requestedTimeout > 0
+        ? Math.min(requestedTimeout, DEFAULT_TIMEOUT_MS) : DEFAULT_TIMEOUT_MS;
+      let executable = binary;
+      let spawnArgs = args;
+      if (isPublic) {
+        const sandbox = { ...ctx.environment.sandbox, trust: 'public' };
+        const mode = resolvePublicSandboxMode(sandbox, ctx._platform || process.platform);
+        if (mode === 'bwrap') {
+          const available = (ctx._detectBwrap || detectBwrap)();
+          if (!available.available) throw new Error(`goose adapter: bwrap unavailable: ${available.error}`);
+          [executable, ...spawnArgs] = (ctx._wrapArgvWithBwrap || wrapArgvWithBwrap)([binary, ...args], {
+            ...ctx.environment, sandbox: { ...sandbox, filesystem: {
+              ...(sandbox.filesystem || {}), 'write-outside': [home],
+            } },
+          }, { workspacePath: ctx.cwd, homePath: home,
+            readOnlyPaths: [tempDir, binary, process.execPath, ...mcpReadDirectories] });
+        } else {
+          if ((ctx._platform || process.platform) !== 'darwin') throw new Error('goose adapter: Seatbelt requires macOS');
+          [executable, ...spawnArgs] = (ctx._wrapArgvWithSeatbelt || wrapArgvWithSeatbelt)([binary, ...args], {
+            workspacePath: ctx.cwd, workspaceAccess: mode === 'read-only' ? 'read' : 'write',
+            executablePath: binary, statePath: home, mcpConfigDir: tempDir,
+            // Public seat: the CLI made this workspace, so it is pinned (F197).
+            pinWorkspace: true,
+            loopbackNetworkPorts: [proxy.port], readOnlyDirectories: mcpReadDirectories,
+          });
+        }
+      }
+      // F460: on a public seat the credential goes once every MCP reader has it
+      // (their ready files), or at the deadline. A delete that fails ends the turn.
+      let releaseFailure = null;
+      let child = null;
+      const spawnImpl = (...spawnArgs) => {
+        child = (ctx._spawnImpl || childSpawn)(...spawnArgs);
+        return child;
+      };
+      if (readyFileDir) {
+        credentialRelease = armCredentialRelease(credential, {
+          readyFiles: readyFiles.map(({ path }) => path),
+          label: 'public Goose seat',
+          // eslint-disable-next-line no-console
+          warn: (text) => console.warn(`[goose] ${text}`),
+          onFailure: (err) => { releaseFailure = err; child?.kill?.('SIGKILL'); },
+          ...ctx._credentialRelease,
+        });
+        if (credentialRelease.error) throw credentialRelease.error;
+      }
+      const text = await runGoose({
+        binary: executable, args: spawnArgs, cwd: ctx.cwd, env, timeoutMs,
+        credentials: [...spawnCredentials(ctx, [DEFAULT_PROVIDER_KEY]), key, env.OPENAI_API_KEY],
+        optionalExtensions: brokerExtensions,
+        spawnImpl,
+      }).catch((err) => { throw releaseFailure || err; });
+      if (releaseFailure) throw releaseFailure;
+      reply = { text, newSessionId: null };
+    } finally {
+      credentialRelease?.stop();
+      try { await proxy?.close(); } finally {
+        const removed = await Promise.allSettled([tempDir, home].map((path) => rm(path, { recursive: true, force: true })));
+        cleanupFailure = removed.find((outcome) => outcome.status === 'rejected')?.reason || null;
+      }
+    }
+    // Reached only when the turn worked. A cleanup failure is then the turn's
+    // error: on a private seat that rm is the one delete of the credential, so
+    // the turn must not report success over it. When another error ended the
+    // turn (a failed release, say), it propagates past this and is kept.
+    if (cleanupFailure) throw cleanupFailure;
+    return reply;
+  },
+};

package/src/lib/adapters/hermes.js

@@ -0,0 +1,18 @@
+import { homedir } from 'os';
+import { join } from 'path';
+import { createHermesAdapter } from '@commonlyai/seats/adapters/hermes';
+import { buildMemoryPreamble } from '../memory-bridge.js';
+import { effectiveSandboxTrust } from '../environment.js';
+import { seatModelRequired } from './seat-model.js';
+
+export { SUPPORTED_HERMES_VERSION_RANGE, readHermesJsonl, syncProfileEnv } from '@commonlyai/seats/adapters/hermes';
+
+// Commonly's policy for the generic Hermes adapter: its memory preamble, its
+// legacy sandbox-trust names, the fleet seat-model switch, and the profile
+// directory seats have always used.
+export default createHermesAdapter({
+  memoryPreamble: buildMemoryPreamble,
+  effectiveTrust: effectiveSandboxTrust,
+  seatModelRequired,
+  profileRoot: join(homedir(), '.commonly', 'hermes', 'profiles'),
+});

package/src/lib/adapters/index.js

@@ -0,0 +1,68 @@
+/**
+ * Adapter registry — ADR-005 §Adapter pattern.
+ *
+ * `attach <adapter>` and `run <name>` both resolve an adapter by its string
+ * name through this single registry. Adding a new CLI (claude, codex, cursor,
+ * gemini, …) is a one-file PR that exports a default adapter and adds an
+ * entry below.
+ */
+
+import stub from './stub.js';
+import claude from './claude.js';
+import codex from './codex.js';
+import pi from './pi.js';
+import opencode from './opencode.js';
+import qwen from './qwen.js';
+import dsh from './dsh.js';
+import goose from './goose.js';
+import hermes from './hermes.js';
+
+const ADAPTERS = {
+  [stub.name]: stub,
+  [claude.name]: claude,
+  [codex.name]: codex,
+  [pi.name]: pi,
+  [opencode.name]: opencode,
+  [qwen.name]: qwen,
+  [dsh.name]: dsh,
+  [goose.name]: goose,
+  [hermes.name]: hermes,
+};
+
+export const listAdapterNames = () => Object.keys(ADAPTERS);
+
+// The adapters a person can choose: every one but the internal test stub. Help
+// text and "Known:" lists read this, so they never drift from the registry.
+export const listPublicAdapterNames = () => listAdapterNames().filter((name) => name !== stub.name);
+
+export const getAdapter = (name) => ADAPTERS[name] || null;
+
+/**
+ * TASK-049: the environment a seat's ADAPTER needs from the operator's shell.
+ *
+ * The adapter owns the provider, so the adapter declares the variable (see
+ * `pi.js`); the daemon reads the list to carry those keys into its login
+ * service, because launchd and systemd start the daemon with a clean
+ * environment — a key that exists only in an interactive shell is absent at
+ * boot, and the seat then dies inside its own adapter. An adapter that
+ * authenticates through its own CLI (claude, codex) declares nothing here and
+ * contributes nothing.
+ */
+export const providerKeyEnvNames = (adapters = ADAPTERS) => [...new Set(
+  Object.values(adapters).map((adapter) => adapter.providerKeyEnv).filter(Boolean),
+)];
+
+/**
+ * The provider key ONE seat reads from the environment, or null when it reads
+ * none: its adapter signs in through its own CLI (claude, codex), or its
+ * provider block names a keyFile. The daemon warns per seat with this, so a
+ * BYO computer running only claude never hears about keys it has no use for
+ * (Growth's F370 walk).
+ */
+export const seatProviderKeyEnv = ({ adapter, environment, adapters = ADAPTERS } = {}) => {
+  const declared = adapters[adapter]?.providerKeyEnv;
+  if (!declared) return null;
+  const provider = environment?.provider;
+  if (provider?.keyFile) return null;
+  return provider?.apiKeyEnv || declared;
+};