@ravefox/space 0.0.0-stage → 0.2.1

package/src/lib/environment.js

@@ -0,0 +1,681 @@
+/**
+ * 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 };
+};