@ravefox/space 0.2.1 → 0.3.0

package/src/lib/environment.js

@@ -1,681 +0,0 @@
-/**
- * Agent Environment resolver — ADR-008 Phase 1.
- *
- * An environment.yaml/.json file is the user-authored, driver-neutral spec for
- * how an agent's runtime should be shaped: workspace path, sandbox mode, the
- * Claude skills to mount, the MCP servers to expose. This module is the
- * adapter-facing read-side: parse, validate, and realize the workspace +
- * skill mounts on disk. Sandbox argv wrapping lives in `./sandbox/bwrap.js`
- * because it is per-driver (Linux-only, bwrap-specific).
- *
- * Zero runtime deps: Node 20 has no built-in YAML, so we accept JSON only and
- * surface a clear error on .yaml/.yml inputs (per task brief). When a future
- * Node version exposes `node:yaml` natively, parseEnvironmentFile is the one
- * place to add a `.yaml` branch — the rest of the module is parser-agnostic.
- */
-
-import {
-  readFile, mkdir, lstat, cp, rm, chmod, readdir, writeFile,
-} from 'fs/promises';
-import { existsSync } from 'fs';
-import { isAbsolute, join, resolve as pathResolve, basename } from 'path';
-import { homedir } from 'os';
-import { resolveSkillSource } from './skill-prompt.js';
-
-// ── Schema — keep the allow-list narrow; ADR-008 §invariants #1+#2 ──────────
-//
-// Deliberate omission: the env file's directory (needed to resolve `seed` and
-// relative skill paths) is NOT stored on the returned spec. Leaking the user's
-// absolute filesystem path into `config.environment` sent to the backend
-// exposes `$HOME` layout for zero server-side benefit. Callers pass
-// `envFileDir` as a separate argument to resolveWorkspace / mountSkills.
-
-// `model` closes issue #774. Before it, the only way to pin a wrapper's model
-// was `ANTHROPIC_MODEL` exported at `commonly agent run` time — per-process,
-// never persisted, and silently dropped by any restart. Measured consequence on
-// 2026-08-16: six of nine live seats had lost their assigned model, including
-// ux-lead, which was supposed to be on Fable and had been running the CLI
-// default for days with nothing recording the drift.
-//
-// Putting it in the env spec makes the model a persisted, server-side fact that
-// survives restarts and is readable by the platform — which is what ADR-022's
-// "persona and runtime are chosen separately" requires to mean anything for a
-// BYO seat, and what lets an identity card answer "what is this running".
-const ALLOWED_TOP_KEYS = new Set([
-  'version', 'workspace', 'sandbox', 'skills', 'mcp', 'model', 'effort', 'provider',
-]);
-const ALLOWED_SANDBOX_MODES = new Set([
-  'none', 'workspace', 'read-only', 'bwrap', 'firejail', 'container', 'managed',
-]);
-// `workspace` is the middle trust the comment below waits for (TASK-294): a seat
-// on a pod nobody outside it can read, allowed to read its start directory and
-// run read-only git there. Only the claude adapter reads it; every other adapter
-// refuses it before spawning, so it never degrades into a bare spawn.
-const ALLOWED_SANDBOX_TRUST = new Set(['public', 'workspace']);
-// The opt-ins a `workspace` seat can carry. Each one widens a single thing:
-// `write` adds Edit/Write/Bash and a writable workspace; `web` adds WebFetch.
-export const WORKSPACE_SANDBOX_ALLOW = Object.freeze(['write', 'web']);
-const ALLOWED_NETWORK_POLICIES = new Set(['unrestricted', 'restricted']);
-const INLINE_PROVIDER_CREDENTIAL_FIELD = /(?:key|token|secret|password|authorization|header|credential|auth)/i;
-
-const findInlineProviderCredentialField = (value, path) => {
-  if (!value || typeof value !== 'object') return null;
-  for (const [key, nested] of Object.entries(value)) {
-    const normalized = key.replace(/[-_]/g, '').toLowerCase();
-    const fieldPath = `${path}.${key}`;
-    if (INLINE_PROVIDER_CREDENTIAL_FIELD.test(normalized)) return fieldPath;
-    const nestedPath = findInlineProviderCredentialField(nested, fieldPath);
-    if (nestedPath) return nestedPath;
-  }
-  return null;
-};
-
-// `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. It is refused for new declarations
-// above, and a record that already carries it is resolved TOWARD confinement,
-// never toward the bare spawn: `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 — and
-// `workspace` (above) is that trust, which is why it is NOT a legacy alias.
-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
-);
-/**
- * A declared trust resolved THROUGH the legacy table: `internal` → `public`,
- * anything else (including absent) is itself.
- *
- * Exported so every gate reads the mapping once. `normalizeSandboxTrust` above
- * rewrites a whole sandbox object; this is the scalar form for a site that only
- * compares the trust and must not write anything back. The server spells the
- * same predicate `effectiveSandboxTrust` (`grantBrokerConfinement.ts`) — the two
- * sides have to read `internal` the same way or one of them confines a seat the
- * other withholds from.
- */
-export const effectiveSandboxTrust = (trust) => (
-  typeof trust === 'string' && Object.prototype.hasOwnProperty.call(LEGACY_SANDBOX_TRUST, trust)
-    ? LEGACY_SANDBOX_TRUST[trust]
-    : trust
-);
-
-/**
- * Throw when an adapter that does not implement the `workspace` tier is handed
- * one (TASK-294). Only claude reads it. Every other adapter branches on
- * `trust === 'public'`, so an unread `workspace` would fall into its
- * non-public branch — the same silent widening `internal` was.
- * Called at each adapter's spawn entry, before any other sandbox read.
- */
-export const refuseWorkspaceTrust = (sandbox, adapterLabel) => {
-  if (sandbox?.trust !== 'workspace') return;
-  throw new Error(
-    `${adapterLabel} adapter: sandbox.trust=workspace is claude-only for now. `
-    + "Declare sandbox.trust 'public' for this seat, or attach it with the claude adapter.",
-  );
-};
-
-const expandHome = (p) => {
-  if (!p || typeof p !== 'string') return p;
-  if (p === '~') return homedir();
-  if (p.startsWith('~/')) return join(homedir(), p.slice(2));
-  return p;
-};
-
-// ── parseEnvironmentFile ────────────────────────────────────────────────────
-
-/**
- * Read and parse the env file. Accepts JSON only in Phase 1 — .yaml/.yml
- * inputs fail with a specific error pointing the user at JSON, so we never
- * silently misread a YAML file as JSON.
- */
-export const parseEnvironmentFile = async (absolutePath) => {
-  if (!isAbsolute(absolutePath)) {
-    throw new Error(`parseEnvironmentFile requires an absolute path, got: ${absolutePath}`);
-  }
-  if (!existsSync(absolutePath)) {
-    throw new Error(`Environment file not found: ${absolutePath}`);
-  }
-
-  const lower = absolutePath.toLowerCase();
-  if (lower.endsWith('.yaml') || lower.endsWith('.yml')) {
-    throw new Error(
-      `YAML environment files are not supported in Phase 1 — Node 20 has no `
-      + `built-in YAML parser and we keep zero runtime deps. Convert ${absolutePath} `
-      + `to JSON (same shape) and pass that instead.`,
-    );
-  }
-
-  const raw = await readFile(absolutePath, 'utf8');
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (err) {
-    throw new Error(`Failed to parse environment file ${absolutePath}: ${err.message}`);
-  }
-
-  const validation = validateEnvironmentSpec(parsed);
-  if (!validation.ok) {
-    throw new Error(
-      `Invalid environment spec in ${absolutePath}:\n  - ${validation.errors.join('\n  - ')}`,
-    );
-  }
-
-  // Return the bare spec — no envFileDir wrapping, no underscore-prefixed
-  // annotations. The caller is responsible for tracking envFileDir separately
-  // (compute via `dirname(envPath)`) and passing it explicitly to
-  // resolveWorkspace / mountSkills when relative paths in the spec need to
-  // resolve. The provider block is host-local; API writers omit it entirely.
-  return parsed;
-};
-
-/**
- * Remove the host-local provider declaration before an environment spec is
- * sent to the Commonly API. The full spec remains in the local token record so
- * the daemon can bind it to this host and the adapter can resolve its key file.
- */
-export const environmentForServer = (environment) => {
-  if (!environment || typeof environment !== 'object' || Array.isArray(environment)
-    || !Object.prototype.hasOwnProperty.call(environment, 'provider')) {
-    return environment;
-  }
-  const { provider: _hostLocalProvider, ...serverEnvironment } = environment;
-  return serverEnvironment;
-};
-
-// ── validateEnvironmentSpec ─────────────────────────────────────────────────
-
-export const PROVIDER_APIS = Object.freeze(['openai-chat', 'anthropic-messages']);
-
-// One provider check for config, attach, run and the daemon's adapter swap: the adapter must take a
-// provider block at all, and speak its `provider.api` (default openai-chat). An adapter's
-// `providerVerdict(environment)` answers first when it returns a refusal or null (accepted);
-// undefined leaves the seat to this check.
-export const providerRefusal = (environment, adapter) => {
-  if (environment?.provider === undefined) return null;
-  if (!adapter?.supportsProvider) return 'environment.provider requires a provider-capable adapter';
-  const verdict = adapter.providerVerdict?.(environment);
-  if (verdict !== undefined) return verdict;
-  const api = environment.provider?.api || 'openai-chat';
-  const apis = adapter.providerApis || ['openai-chat'];
-  return apis.includes(api) ? null
-    : `the ${adapter.name} adapter cannot use provider.api "${api}"; it supports ${apis.join(', ')}`;
-};
-
-export const validateEnvironmentSpec = (spec) => {
-  const errors = [];
-
-  if (!spec || typeof spec !== 'object' || Array.isArray(spec)) {
-    return { ok: false, errors: ['env spec must be a JSON object'] };
-  }
-
-  for (const key of Object.keys(spec)) {
-    if (!ALLOWED_TOP_KEYS.has(key)) {
-      errors.push(`unknown top-level key: "${key}" (allowed: ${[...ALLOWED_TOP_KEYS].join(', ')})`);
-    }
-  }
-
-  if (spec.version !== undefined && spec.version !== 1) {
-    errors.push(`version must be 1, got ${JSON.stringify(spec.version)}`);
-  }
-
-  // Validated as an opaque non-empty string, deliberately not against a list of
-  // known model ids. A whitelist here would need editing every time a provider
-  // ships a model, and would reject a valid id the local CLI understands and
-  // this file does not — failing the user's attach for a fact it is not the
-  // authority on. The adapter passes it through to `--model`; the CLI is the
-  // thing that knows what is valid, and its error is the honest one.
-  if (spec.model !== undefined) {
-    if (typeof spec.model !== 'string' || spec.model.trim() === '') {
-      errors.push('model must be a non-empty string');
-    }
-  }
-
-  if (spec.provider !== undefined) {
-    if (!spec.provider || typeof spec.provider !== 'object' || Array.isArray(spec.provider)) {
-      errors.push('provider must be an object');
-    } else {
-      const allowedProviderKeys = new Set(['id', 'baseURL', 'keyFile', 'models', 'api']);
-      for (const key of Object.keys(spec.provider)) {
-        if (!allowedProviderKeys.has(key)) {
-          errors.push(`unknown provider key: ${JSON.stringify(key)} (allowed: id, baseURL, keyFile, models, api)`);
-        }
-      }
-      const { id, baseURL, keyFile, models, api } = spec.provider;
-      // The wire the provider speaks. Absent means openai-chat; whether the
-      // chosen adapter can speak it is the adapter's `providerApis`.
-      if (api !== undefined && !PROVIDER_APIS.includes(api)) {
-        errors.push(`provider.api must be one of ${PROVIDER_APIS.join(', ')}`);
-      }
-      if (typeof id !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(id)) {
-        errors.push('provider.id must be a safe OpenCode provider id');
-      }
-      if (typeof baseURL !== 'string' || baseURL.trim() === '') {
-        errors.push('provider.baseURL must be an HTTP(S) URL');
-      } else {
-        try {
-          const url = new URL(baseURL);
-          if (!['http:', 'https:'].includes(url.protocol)
-            || !url.hostname
-            || url.username || url.password || url.search || url.hash) {
-            errors.push('provider.baseURL must be an HTTP(S) URL without credentials, query, or fragment');
-          }
-        } catch {
-          errors.push('provider.baseURL must be an HTTP(S) URL');
-        }
-      }
-      if (typeof keyFile !== 'string' || !isAbsolute(keyFile)) {
-        errors.push('provider.keyFile must be an absolute path');
-      } else if (/[\r\n}]/.test(keyFile)) {
-        errors.push('provider.keyFile contains characters that cannot be used in an OpenCode file reference');
-      }
-      if (models !== undefined) {
-        if (!models || typeof models !== 'object' || Array.isArray(models)) {
-          errors.push('provider.models must be an object keyed by bare model id');
-        } else {
-          for (const [modelId, modelConfig] of Object.entries(models)) {
-            if (!/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(modelId)) {
-              errors.push(`provider.models key ${JSON.stringify(modelId)} must be a bare model id`);
-            }
-            if (!modelConfig || typeof modelConfig !== 'object' || Array.isArray(modelConfig)) {
-              errors.push(`provider.models[${JSON.stringify(modelId)}] must be an object`);
-            } else {
-              const credentialField = findInlineProviderCredentialField(
-                modelConfig,
-                `provider.models.${modelId}`,
-              );
-              if (credentialField) {
-                errors.push(`${credentialField} must not contain inline credentials; use provider.keyFile`);
-              }
-            }
-          }
-        }
-      }
-      if (spec.model === undefined) {
-        errors.push('model is required when provider is configured');
-      } else if (typeof spec.model === 'string'
-        && !/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(spec.model)) {
-        errors.push('model must be a bare model id when provider is configured');
-      }
-    }
-  }
-
-  // `effort` is the reasoning budget the claude adapter passes to `--effort`.
-  // Unlike `model` it IS a closed set — the CLI documents exactly these — so a
-  // typo fails here at attach time, not silently at the first spawn.
-  if (spec.effort !== undefined) {
-    const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'];
-    if (typeof spec.effort !== 'string' || !EFFORTS.includes(spec.effort)) {
-      errors.push(`effort must be one of: ${EFFORTS.join(', ')}`);
-    }
-  }
-
-  if (spec.workspace !== undefined) {
-    if (typeof spec.workspace !== 'object' || spec.workspace === null) {
-      errors.push('workspace must be an object');
-    } else {
-      if (spec.workspace.path !== undefined && typeof spec.workspace.path !== 'string') {
-        errors.push('workspace.path must be a string');
-      }
-      if (spec.workspace.seed !== undefined) {
-        if (!Array.isArray(spec.workspace.seed)
-          || !spec.workspace.seed.every((s) => typeof s === 'string')) {
-          errors.push('workspace.seed must be an array of strings');
-        }
-      }
-    }
-  }
-
-  if (spec.sandbox !== undefined) {
-    if (typeof spec.sandbox !== 'object' || spec.sandbox === null) {
-      errors.push('sandbox must be an object');
-    } else {
-      const {
-        mode, trust, network, filesystem, allow,
-      } = spec.sandbox;
-      if (mode !== undefined && !ALLOWED_SANDBOX_MODES.has(mode)) {
-        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 'public' or 'workspace' — 'public' marks a seat "
-          + "anyone in the pod can talk to, 'workspace' a seat on a private pod that "
-          + 'reads its start directory; omit it for an unconfined seat of your own '
-          + `(got ${JSON.stringify(trust)})`,
-        );
-      }
-      if (allow !== undefined) {
-        if (!Array.isArray(allow) || !allow.every((a) => WORKSPACE_SANDBOX_ALLOW.includes(a))) {
-          errors.push(`sandbox.allow must be an array of: ${WORKSPACE_SANDBOX_ALLOW.join(', ')}`);
-        } else if (trust !== 'workspace') {
-          // An opt-in widens the workspace tier and nothing else. On a public
-          // seat it would read as a way to hand strangers Bash.
-          errors.push(
-            "sandbox.allow applies only to trust 'workspace' "
-            + `(got trust ${JSON.stringify(trust)})`,
-          );
-        } else if (allow.includes('write') && mode === 'read-only') {
-          errors.push("sandbox.allow 'write' cannot be combined with sandbox.mode 'read-only'");
-        }
-      }
-      if (network !== undefined) {
-        if (typeof network !== 'object' || network === null) {
-          errors.push('sandbox.network must be an object');
-        } else {
-          if (network.policy !== undefined && !ALLOWED_NETWORK_POLICIES.has(network.policy)) {
-            errors.push(`sandbox.network.policy must be one of: ${[...ALLOWED_NETWORK_POLICIES].join(', ')}`);
-          }
-          if (network['allow-hosts'] !== undefined
-            && (!Array.isArray(network['allow-hosts'])
-              || !network['allow-hosts'].every((h) => typeof h === 'string'))) {
-            errors.push('sandbox.network.allow-hosts must be an array of strings');
-          }
-        }
-      }
-      if (filesystem !== undefined) {
-        if (typeof filesystem !== 'object' || filesystem === null) {
-          errors.push('sandbox.filesystem must be an object');
-        } else {
-          for (const f of ['read-outside', 'write-outside']) {
-            if (filesystem[f] !== undefined
-              && (!Array.isArray(filesystem[f])
-                || !filesystem[f].every((p) => typeof p === 'string'))) {
-              errors.push(`sandbox.filesystem.${f} must be an array of strings`);
-            }
-          }
-        }
-      }
-    }
-  }
-
-  if (spec.skills !== undefined) {
-    if (typeof spec.skills !== 'object' || spec.skills === null) {
-      errors.push('skills must be an object');
-    } else {
-      if (spec.skills.claude !== undefined
-        && (!Array.isArray(spec.skills.claude)
-          || !spec.skills.claude.every((p) => typeof p === 'string'))) {
-        errors.push('skills.claude must be an array of strings');
-      }
-      if (spec.skills.commonly !== undefined
-        && (!Array.isArray(spec.skills.commonly)
-          || !spec.skills.commonly.every((p) => typeof p === 'string'))) {
-        errors.push('skills.commonly must be an array of strings');
-      }
-    }
-  }
-
-  // A TRANSPORT DECIDES THE ENTRY, so the fields must agree with it (TASK-071).
-  // This block is MIRRORED, not shared: the other
-  // writer-side check is the backend's, in
-  // backend/utils/environmentSpecValidation.ts, called from the
-  // `PATCH /api/registry/pods/:podId/agents/:name` handler that stores
-  // `config.environment` for the owner's daemon. The two cannot share code at
-  // runtime — this is a published ESM package, that is the CJS backend — so
-  // the wording here and there is kept parallel deliberately and the two must
-  // move together. This one refuses a hand-written `--environment <file>`; the
-  // backend's refuses a stored row.
-  //
-  // The shape rule is not decoration: every adapter branches on it
-  // (isStdioServer/isHttpServer in adapters/pi-mcp-client.mjs), and `command`
-  // is an argv ARRAY — `connectStdioMcp` destructures `const [cmd, ...args] =
-  // command`. An entry whose fields contradict its transport is a record whose
-  // reader has to pick a winner, and the readers do not agree on which.
-  if (spec.mcp !== undefined) {
-    if (!Array.isArray(spec.mcp)) {
-      errors.push('mcp must be an array');
-    } else {
-      spec.mcp.forEach((server, i) => {
-        if (!server || typeof server !== 'object' || Array.isArray(server)) {
-          errors.push(`mcp[${i}] must be an object`);
-          return;
-        }
-        if (typeof server.name !== 'string' || !server.name) {
-          errors.push(`mcp[${i}].name is required and must be a non-empty string`);
-        }
-        if (server.transport !== undefined
-          && !['http', 'stdio', 'sse'].includes(server.transport)) {
-          errors.push(`mcp[${i}].transport must be one of: http, stdio, sse`);
-          // The agreement rule below is defined in terms of a transport this
-          // entry does not have; judging it here would mean inventing the
-          // second definition that rule exists to avoid.
-          return;
-        }
-        const argv = Array.isArray(server.command) && server.command.length > 0
-          && server.command.every((part) => typeof part === 'string' && part.trim().length > 0);
-        const hasUrl = typeof server.url === 'string' && server.url.trim().length > 0;
-        if (server.transport === 'http' || server.transport === 'sse') {
-          if (!hasUrl) {
-            errors.push(`mcp[${i}].url is required when transport is ${server.transport}: a ${server.transport} server is reached by URL, and this entry declares no URL to reach`);
-          }
-          if (server.command !== undefined) {
-            errors.push(`mcp[${i}].command must not be set when transport is ${server.transport}: with a url and a command in one entry each reader picks a different winner, so the record does not say what runs`);
-          }
-        } else {
-          // stdio, or absent transport — the historical default.
-          if (!argv) {
-            errors.push(server.command === undefined
-              ? `mcp[${i}].command is required for a stdio entry (and for an entry that declares no transport): with no command and no url there is nothing to run`
-              : `mcp[${i}].command must be a non-empty array of strings (argv, e.g. ["npx", "-y", "@commonlyai/mcp@latest"]); a string command is not a command line any reader in this repo executes`);
-          }
-          if (hasUrl) {
-            errors.push(`mcp[${i}].url must not be set for a stdio entry (and for an entry that declares no transport): a url here is a second, contradictory way to reach the server`);
-          }
-        }
-      });
-    }
-  }
-
-  return { ok: errors.length === 0, errors };
-};
-
-// ── resolveWorkspace ────────────────────────────────────────────────────────
-
-/**
- * Compute the workspace path and ensure it exists. On first creation, copy
- * any `workspace.seed` paths in. Returns `{ path, created }` so the caller
- * can log the outcome and (in the future) gate one-time setup.
- *
- * `envFileDir` is the directory of the env file (used to resolve relative
- * seed paths). Required when `workspace.seed` contains relative entries;
- * ignored otherwise.
- */
-export const resolveWorkspace = async (spec, agentName, envFileDir = null) => {
-  if (!agentName) throw new Error('resolveWorkspace requires agentName');
-  const declared = spec?.workspace?.path;
-  const path = expandHome(declared) || join(homedir(), '.commonly', 'workspaces', agentName);
-  const absPath = isAbsolute(path) ? path : pathResolve(path);
-
-  const created = !existsSync(absPath);
-  await mkdir(absPath, { recursive: true });
-
-  if (created && Array.isArray(spec?.workspace?.seed)) {
-    for (const entry of spec.workspace.seed) {
-      const src = isAbsolute(entry)
-        ? entry
-        : (envFileDir ? pathResolve(envFileDir, entry) : pathResolve(entry));
-      if (!existsSync(src)) {
-        throw new Error(`workspace.seed entry not found: ${src}`);
-      }
-      const dest = join(absPath, basename(src));
-      // eslint-disable-next-line no-await-in-loop
-      await cp(src, dest, { recursive: true, force: false, errorOnExist: false });
-    }
-  }
-
-  return { path: absPath, created };
-};
-
-// ── mountSkills ─────────────────────────────────────────────────────────────
-
-// Marks a skill directory as a Commonly-managed snapshot. Its presence is what
-// licenses a refresh to delete and re-copy the directory: without it we cannot
-// distinguish "a mount we made last spawn" from "a skill the user authored in
-// their workspace", and clobbering the latter would destroy real work.
-const MOUNT_MARKER = '.commonly-skill-mount';
-
-/**
- * Recursively drop the write bit on every regular file in a mounted snapshot.
- *
- * Directories deliberately stay writable: unlinking a file requires write
- * permission on its PARENT, so read-only directories would make the next
- * refresh fail. This is defense-in-depth for the agent's own copy, not the
- * load-bearing protection — that comes from the copy existing at all.
- */
-const freezeFiles = async (dir) => {
-  const entries = await readdir(dir, { withFileTypes: true });
-  for (const entry of entries) {
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      // eslint-disable-next-line no-await-in-loop
-      await freezeFiles(full);
-    } else if (entry.isFile()) {
-      // eslint-disable-next-line no-await-in-loop
-      await chmod(full, 0o444);
-    }
-  }
-};
-
-// F171: skills are written only into a real .claude/skills directory inside
-// the workspace. Each component is read with lstat and never followed. A
-// missing one is created with a plain mkdir inside the real directory just
-// checked, then read again; a link, or anything that is not a real directory,
-// returns null and mountSkills writes nothing.
-const SKILLS_DIR_PARTS = ['.claude', 'skills'];
-
-const lstatOrNull = async (p) => {
-  try {
-    return await lstat(p);
-  } catch (err) {
-    if (err.code === 'ENOENT') return null;
-    throw err;
-  }
-};
-
-const realSkillsDir = async (workspacePath) => {
-  let dir = workspacePath;
-  for (const part of SKILLS_DIR_PARTS) {
-    dir = join(dir, part);
-    // eslint-disable-next-line no-await-in-loop
-    let st = await lstatOrNull(dir);
-    if (!st) {
-      try {
-        // eslint-disable-next-line no-await-in-loop
-        await mkdir(dir);
-      } catch (err) {
-        if (err.code !== 'EEXIST') throw err;
-      }
-      // eslint-disable-next-line no-await-in-loop
-      st = await lstatOrNull(dir);
-    }
-    if (!st || st.isSymbolicLink() || !st.isDirectory()) return null;
-  }
-  return dir;
-};
-
-/**
- * Mount each `skills.claude[]` source into `<workspacePath>/.claude/skills/`
- * as a READ-ONLY SNAPSHOT COPY.
- *
- * Why a copy and not a symlink: a symlink is writable *through*, so an agent
- * holding Write/Edit could edit the file that governs its own behaviour — and
- * because these sources are usually files tracked in a repo (the bundled
- * `cli/skills/commonly` is the common case), that edit lands in the operator's
- * working tree. `npm publish` ships the working tree, not git HEAD, so a
- * write-through edit can silently ride out in the next release. That is not
- * hypothetical: @commonlyai/cli@0.1.4 shipped with the "post as yourself,
- * never as your operator" guardrail (#702) missing for exactly this reason.
- * The snapshot makes the data flow one-way: source → workspace, never back.
- *
- * Refreshed on every call — the claude adapter mounts per spawn — so edits to
- * the source still reach the agent on its next turn. Only directories carrying
- * MOUNT_MARKER are refreshed; anything else in the slot is reported as a
- * conflict and left untouched.
- *
- * Legacy symlinks written by CLI ≤0.1.4 are replaced with a snapshot, since
- * the symlink IS the vulnerable shape being retired.
- *
- * `envFileDir` is the directory of the env file (used to resolve relative
- * skill paths). Optional — when omitted, relative paths fall back to
- * `workspacePath`.
- *
- * A workspace whose .claude or .claude/skills is a link, or not a directory,
- * gets no mount at all: every source is reported as 'unsafe-skill-dir' and
- * nothing is written (F171).
- *
- * Returns `{ mounted, conflicted }`:
- *   - `mounted`:    string[]            — absolute source paths snapshotted
- *   - `conflicted`: Array<{path, reason}> where reason ∈
- *       'not-a-mount' | 'missing-source' | 'unsafe-skill-dir'
- */
-export const mountSkills = async (spec, workspacePath, envFileDir = null) => {
-  const sources = Array.isArray(spec?.skills?.claude) ? spec.skills.claude : [];
-  const mounted = [];
-  const conflicted = [];
-  if (sources.length === 0) return { mounted, conflicted };
-
-  const skillsDir = await realSkillsDir(workspacePath);
-  if (!skillsDir) {
-    return {
-      mounted,
-      conflicted: sources.map((rawSource) => ({
-        path: resolveSkillSource(rawSource, envFileDir || workspacePath),
-        reason: 'unsafe-skill-dir',
-      })),
-    };
-  }
-
-  for (const rawSource of sources) {
-    const absSource = resolveSkillSource(rawSource, envFileDir || workspacePath);
-    if (!existsSync(absSource)) {
-      conflicted.push({ path: absSource, reason: 'missing-source' });
-      continue;
-    }
-    const destPath = join(skillsDir, basename(absSource));
-
-    let slot = null;
-    try {
-      // eslint-disable-next-line no-await-in-loop
-      slot = await lstat(destPath);
-    } catch (err) {
-      // Only ENOENT means "slot is free, proceed." EACCES / EPERM / EIO are
-      // real failures that should surface rather than becoming a confusing
-      // follow-on error from the copy below.
-      if (err.code !== 'ENOENT') throw err;
-    }
-
-    if (slot) {
-      const isLegacySymlink = slot.isSymbolicLink();
-      const isOwnedMount = slot.isDirectory() && existsSync(join(destPath, MOUNT_MARKER));
-      if (!isLegacySymlink && !isOwnedMount) {
-        // A real file, or a directory we did not create — user content.
-        conflicted.push({ path: absSource, reason: 'not-a-mount' });
-        continue;
-      }
-      // eslint-disable-next-line no-await-in-loop
-      await rm(destPath, { recursive: true, force: true });
-    }
-
-    // eslint-disable-next-line no-await-in-loop
-    await cp(absSource, destPath, { recursive: true });
-    // eslint-disable-next-line no-await-in-loop
-    await writeFile(
-      join(destPath, MOUNT_MARKER),
-      `mounted-from: ${absSource}\n`,
-      'utf8',
-    );
-    // eslint-disable-next-line no-await-in-loop
-    await freezeFiles(destPath);
-    mounted.push(absSource);
-  }
-
-  return { mounted, conflicted };
-};