agent-trellis 0.21.0 → 0.22.0

package/dist/pi-bridge/bundle.js

@@ -36608,7 +36608,7 @@ var require_dist_cjs18 = __commonJS({
   "node_modules/@aws-sdk/credential-provider-web-identity/dist-cjs/index.js"(exports) {
     var { setCredentialFeature: setCredentialFeature2 } = (init_client3(), __toCommonJS(client_exports2));
     var { CredentialsProviderError: CredentialsProviderError2, externalDataInterceptor: externalDataInterceptor2 } = (init_config2(), __toCommonJS(config_exports));
-    var { readFileSync: readFileSync6 } = __require("node:fs");
+    var { readFileSync: readFileSync7 } = __require("node:fs");
     var fromWebToken = (init) => async (awsIdentityProperties) => {
       init.logger?.debug("@aws-sdk/credential-provider-web-identity - fromWebToken");
       const { roleArn, roleSessionName, webIdentityToken, providerId, policyArns, policy, durationSeconds } = init;
@@ -36649,7 +36649,7 @@ var require_dist_cjs18 = __commonJS({
       }
       const credentials = await fromWebToken({
         ...init,
-        webIdentityToken: externalDataInterceptor2?.getTokenRecord?.()[webIdentityTokenFile] ?? readFileSync6(webIdentityTokenFile, { encoding: "ascii" }),
+        webIdentityToken: externalDataInterceptor2?.getTokenRecord?.()[webIdentityTokenFile] ?? readFileSync7(webIdentityTokenFile, { encoding: "ascii" }),
         roleArn,
         roleSessionName
       })(awsIdentityProperties);
@@ -47325,8 +47325,8 @@ var require_cross_spawn = __commonJS({
 import { homedir as homedir4 } from "node:os";
 
 // src/core/canonical.ts
-var import_yaml = __toESM(require_dist(), 1);
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync3, readdirSync as readdirSync2, statSync as statSync2, writeFileSync } from "node:fs";
+var import_yaml2 = __toESM(require_dist(), 1);
+import { existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync4, readdirSync as readdirSync2, statSync as statSync2, writeFileSync } from "node:fs";
 import { homedir as homedir3 } from "node:os";
 import { basename, dirname as dirname2, join as join6 } from "node:path";
 
@@ -47387,7 +47387,7 @@ function deliveredName(entry) {
   return parsed.kind === "invalid" ? entry : parsed.delivered;
 }
 function parseEnvEntry(entry) {
-  if (entry.includes("mxenv://") || entry.includes("mx-env://")) {
+  if (entry.includes("://")) {
     try {
       const refs = (0, import_mxenv_core.findMxEnvReferences)(entry);
       if (refs.length === 1 && `mxenv://${refs[0].profile}/${refs[0].key}` === entry) {
@@ -47399,7 +47399,7 @@ function parseEnvEntry(entry) {
   }
   return { kind: "name", delivered: entry };
 }
-async function resolveSecretEnv(entries, policy) {
+async function resolveSecretEntries(entries, policy) {
   const parsed = entries.map(parseEnvEntry);
   const invalid = parsed.find((p5) => p5.kind === "invalid");
   if (invalid) {
@@ -47408,11 +47408,21 @@ async function resolveSecretEnv(entries, policy) {
   const result = {};
   const refs = parsed.filter((p5) => p5.kind === "ref");
   if (refs.length > 0) {
-    const resolver = new import_mxenv_core.ReferenceResolver((0, import_mxenv_core.loadConfigLayers)({ cwd: homedir2(), homeDir: homedir2() }), {});
+    let resolver;
+    try {
+      resolver = new import_mxenv_core.ReferenceResolver((0, import_mxenv_core.loadConfigLayers)({ cwd: homedir2(), homeDir: homedir2() }), {});
+    } catch {
+      throw new SecretReferenceError(entries[parsed.indexOf(refs[0])]);
+    }
     for (const ref of refs) {
-      if (result[ref.delivered] !== void 0) continue;
-      const { value } = await resolver.valueOf(ref.profile, ref.key);
-      result[ref.delivered] = value;
+      const entry = `mxenv://${ref.profile}/${ref.key}`;
+      if (Object.hasOwn(result, entry)) continue;
+      try {
+        const { value } = await resolver.valueOf(ref.profile, ref.key);
+        result[entry] = value;
+      } catch {
+        throw new SecretReferenceError(entry);
+      }
     }
   }
   const names = parsed.filter((p5) => p5.kind === "name");
@@ -47425,6 +47435,26 @@ async function resolveSecretEnv(entries, policy) {
   }
   return result;
 }
+var SecretReferenceError = class extends Error {
+  constructor(entry) {
+    super(`[trellis] could not resolve mxenv reference ${entry} \u2014 check the profile, KEY and provider configuration`);
+    this.entry = entry;
+  }
+  entry;
+};
+async function resolveSecretEnv(entries, policy) {
+  const values = await resolveSecretEntries(entries, policy);
+  const result = {};
+  const ordered = [
+    ...entries.filter((entry) => parseEnvEntry(entry).kind === "ref"),
+    ...entries.filter((entry) => parseEnvEntry(entry).kind !== "ref")
+  ];
+  for (const entry of ordered) {
+    const name = deliveredName(entry);
+    if (result[name] === void 0) result[name] = values[entry];
+  }
+  return result;
+}
 
 // src/core/mcpServerDef.ts
 function fromServerDefYaml(serverName, def, source = "mcp/servers.yaml") {
@@ -47467,8 +47497,26 @@ function fromAuthYaml(serverName, auth2, source) {
 }
 
 // src/lib/workspace.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2, readdirSync, statSync } from "node:fs";
+import { existsSync as existsSync3, readFileSync as readFileSync3, readdirSync, statSync } from "node:fs";
 import { dirname, join as join5, resolve } from "node:path";
+
+// src/lib/skillScope.ts
+var import_yaml = __toESM(require_dist(), 1);
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
+function registeredSkillScope(value) {
+  return Array.isArray(value) && value.every((id) => ALL_AGENTS.includes(id)) ? [...new Set(value)] : [];
+}
+function readSkillScopes(path) {
+  if (!existsSync2(path)) return {};
+  const doc = (0, import_yaml.parse)(readFileSync2(path, "utf8"));
+  if (doc?.skills === void 0) return {};
+  if (typeof doc.skills !== "object" || doc.skills === null || Array.isArray(doc.skills)) {
+    throw new Error(`${path}: skills must be a map of skill names to agent lists`);
+  }
+  return doc.skills;
+}
+
+// src/lib/workspace.ts
 var WORKSPACE_DIR_NAME = ".agents";
 var WORKSPACE_CONFIG_VERSION = 1;
 var CONFIG_SOURCE_LABEL = ".agents/config.json";
@@ -47480,10 +47528,10 @@ function loadWorkspaceLayer(workspaceDir, policy) {
   const diagnostics = [];
   const layer = { root: workspaceDir, servers: {}, tombstones: [], skills: [], diagnostics };
   const configPath = join5(layerRoot, "config.json");
-  if (existsSync2(configPath)) {
+  if (existsSync3(configPath)) {
     let parsed;
     try {
-      parsed = JSON.parse(readFileSync2(configPath, "utf-8"));
+      parsed = JSON.parse(readFileSync3(configPath, "utf-8"));
     } catch (err) {
       throw new Error(`${CONFIG_SOURCE_LABEL}: invalid JSON \u2014 ${err.message}`);
     }
@@ -47524,10 +47572,11 @@ function loadWorkspaceLayer(workspaceDir, policy) {
     }
   }
   const instructionsPath = join5(layerRoot, "AGENTS.md");
-  if (existsSync2(instructionsPath)) {
+  if (existsSync3(instructionsPath)) {
     layer.instructionsFile = instructionsPath;
   }
   const skillsRoot = join5(layerRoot, "skills");
+  const scopes = readSkillScopes(join5(layerRoot, "scope.yaml"));
   let skillEntries = [];
   try {
     skillEntries = readdirSync(skillsRoot);
@@ -47536,7 +47585,10 @@ function loadWorkspaceLayer(workspaceDir, policy) {
   for (const name of skillEntries) {
     const dir = join5(skillsRoot, name);
     try {
-      if (statSync(dir).isDirectory()) layer.skills.push({ name, dir });
+      if (statSync(dir).isDirectory()) {
+        layer.skills.push({ name, dir, scope: registeredSkillScope(scopes[name]) });
+        if (!Object.hasOwn(scopes, name)) diagnostics.push(`.agents/scope.yaml: skill "${name}" has no registered agents \u2014 Trellis distribution paused`);
+      }
     } catch {
     }
   }
@@ -47619,6 +47671,12 @@ function mergeWorkspaceLayer(base, layer) {
   };
 }
 
+// src/lib/builtinSkills.ts
+var TRELLIS_RUNTIME_SKILL_NAME = "trellis-runtime";
+function isBuiltinSkillName(name) {
+  return name === TRELLIS_RUNTIME_SKILL_NAME;
+}
+
 // src/core/canonical.ts
 function trellisRoot(homeDir) {
   return join6(homeDir, ".trellis");
@@ -47652,17 +47710,17 @@ function listSkillDirs(dir) {
   return skills;
 }
 function loadScopeYaml(path) {
-  if (!existsSync3(path)) {
+  if (!existsSync4(path)) {
     return {};
   }
-  const parsed = (0, import_yaml.parse)(readFileSync3(path, "utf-8"));
+  const parsed = (0, import_yaml2.parse)(readFileSync4(path, "utf-8"));
   return parsed ?? {};
 }
 function loadServersYaml(path) {
-  if (!existsSync3(path)) {
+  if (!existsSync4(path)) {
     return { servers: {}, knownHostInjected: [] };
   }
-  const parsed = (0, import_yaml.parse)(readFileSync3(path, "utf-8")) ?? {};
+  const parsed = (0, import_yaml2.parse)(readFileSync4(path, "utf-8")) ?? {};
   const servers = Object.fromEntries(Object.entries(parsed.servers ?? {}).map(([name, def]) => [name, fromServerDefYaml(name, def)]));
   return {
     servers,
@@ -47703,10 +47761,10 @@ function fromGatewayYaml(gateway) {
   return out;
 }
 function loadSecretsPolicyYaml(path, homeDir) {
-  if (!existsSync3(path)) {
+  if (!existsSync4(path)) {
     return { allowedVars: [], rejectPatterns: [] };
   }
-  const parsed = (0, import_yaml.parse)(readFileSync3(path, "utf-8")) ?? {};
+  const parsed = (0, import_yaml2.parse)(readFileSync4(path, "utf-8")) ?? {};
   return {
     allowedVars: parsed.allowed_vars ?? [],
     rejectPatterns: (parsed.reject_patterns ?? []).map((pattern) => new RegExp(pattern)),
@@ -47714,10 +47772,10 @@ function loadSecretsPolicyYaml(path, homeDir) {
   };
 }
 function loadManagedYaml(path, diagnostics) {
-  if (!existsSync3(path)) {
+  if (!existsSync4(path)) {
     return [];
   }
-  const parsed = (0, import_yaml.parse)(readFileSync3(path, "utf-8")) ?? {};
+  const parsed = (0, import_yaml2.parse)(readFileSync4(path, "utf-8")) ?? {};
   const raw = parsed.agents ?? [];
   const valid = [];
   for (const id of raw) {
@@ -47733,8 +47791,8 @@ function scopeFor(map3, name) {
   return map3?.[name];
 }
 function validAgentIds(scope) {
-  if (!scope) return true;
-  return scope.every((id) => ALL_AGENTS.includes(id));
+  if (scope === void 0) return true;
+  return Array.isArray(scope) && scope.every((id) => ALL_AGENTS.includes(id));
 }
 function assertAuthMetadataClean(mcp, policy) {
   for (const [name, def] of Object.entries(mcp.servers)) {
@@ -47759,7 +47817,7 @@ function loadCanonicalSource(arg = {}) {
   const options = typeof arg === "string" ? { homeDir: arg } : arg;
   const homeDir = options.homeDir ?? homedir3();
   const root7 = trellisRoot(homeDir);
-  if (!existsSync3(root7)) {
+  if (!existsSync4(root7)) {
     throw new Error(
       `No canonical source at ${root7}. Run trellis init before trellis sync.`
     );
@@ -47769,7 +47827,13 @@ function loadCanonicalSource(arg = {}) {
   const scopeYaml = loadScopeYaml(join6(root7, "scope.yaml"));
   const skillDirs = listSkillDirs(join6(root7, "skills"));
   const knownSkillNames = new Set(skillDirs.map((s3) => s3.name));
-  const skills = skillDirs.map(({ name, dir }) => ({ name, dir, scope: scopeFor(scopeYaml.skills, name) }));
+  const skills = skillDirs.map(({ name, dir }) => {
+    const declared = scopeFor(scopeYaml.skills, name);
+    if (declared === void 0 && !isBuiltinSkillName(name)) {
+      diagnostics.push(`scope.yaml: skill "${name}" has no registered agents \u2014 distribution paused; run trellis skill scope ${name} --agents <ids>`);
+    }
+    return { name, dir, scope: isBuiltinSkillName(name) && declared === void 0 ? void 0 : registeredSkillScope(declared) };
+  });
   const agentFiles = listMarkdownFiles(join6(root7, "agents"));
   const knownAgentProfileNames = new Set(agentFiles.map((a8) => a8.name));
   const agents = agentFiles.map(({ name, file: file2 }) => ({
@@ -47794,7 +47858,7 @@ function loadCanonicalSource(arg = {}) {
       if (!known.has(name)) {
         diagnostics.push(`scope.yaml: "${section}.${name}" does not match any known ${section.slice(0, -1)} \u2014 ignored`);
       } else if (!validAgentIds(map3?.[name])) {
-        diagnostics.push(`scope.yaml: "${section}.${name}" lists an unrecognized agent id \u2014 ignored`);
+        diagnostics.push(`scope.yaml: "${section}.${name}" lists an unrecognized agent id${section === "skills" ? " \u2014 distribution paused" : " \u2014 ignored"}`);
       }
     }
   }
@@ -47835,6 +47899,21 @@ function codexBearerTokenEnvVar(def) {
   return BEARER_TOKEN_VALUE_RE.exec(value)?.[1];
 }
 
+// src/lib/envVarNames.ts
+var TEMPLATE_VAR_RE = /\$\{([^{}]*)\}/g;
+function replaceTemplateVars(value, replace) {
+  return value.replace(TEMPLATE_VAR_RE, (_match, entry) => replace(entry));
+}
+function invalidHeaderTemplate(headers) {
+  return Object.entries(headers ?? {}).find(([, value]) => {
+    const literal2 = replaceTemplateVars(value, () => "");
+    return literal2.includes("${") || /mx-?env:\/\//.test(literal2);
+  })?.[0];
+}
+function extractTemplateVarNames(value) {
+  return [...value.matchAll(TEMPLATE_VAR_RE)].map((m6) => m6[1]);
+}
+
 // src/adapters/mcpPlan.ts
 var HUB_ENTRY_NAME = "trellis-hub";
 var GATEWAY_ENTRY_NAME = "trellis";
@@ -47893,18 +47972,25 @@ function findLiteralSecret(def) {
   return void 0;
 }
 async function findUnresolvedEnvName(def, policy) {
-  const names = [...def.env ?? [], ...Object.values(def.envAliases ?? {})];
+  const headerRefs = Object.values(def.headers ?? {}).flatMap(extractTemplateVarNames).filter((entry) => !isValidSecretVarName(entry));
+  const envNames = [...def.env ?? [], ...Object.values(def.envAliases ?? {})];
+  const names = [...envNames, ...headerRefs];
   if (names.length === 0) return void 0;
   const parsed = names.map(parseEnvEntry);
-  const invalid = parsed.find((p5) => p5.kind === "invalid");
-  if (invalid) return invalid.entry;
-  const resolved = await resolveSecretEnv(names, policy);
-  return names.find((name) => {
-    const p5 = parseEnvEntry(name);
-    return !resolved[p5.kind === "invalid" ? name : p5.delivered];
-  });
+  const invalid = names.find((entry, i8) => parsed[i8].kind === "invalid" || headerRefs.includes(entry) && parsed[i8].kind === "name");
+  if (invalid !== void 0) return invalid;
+  try {
+    const env2 = await resolveSecretEnv(envNames, policy);
+    const missingEnv = envNames.find((entry) => !env2[deliveredName(entry)]);
+    if (missingEnv !== void 0) return missingEnv;
+    const headers = await resolveSecretEntries(headerRefs, policy);
+    return headerRefs.find((entry) => !headers[entry]);
+  } catch (error62) {
+    if (error62 instanceof SecretReferenceError) return error62.entry;
+    throw error62;
+  }
 }
-async function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
+async function resolveMcpPlan(agentId, mcp, managedAgents, policy, options = {}) {
   const route = routeForAgent(agentId, mcp, managedAgents);
   const runtimeEnabled = capabilityDeliveryForAgent(agentId, mcp) !== "native";
   if (route.mode === "gateway") {
@@ -47986,14 +48072,14 @@ async function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
       conflicts: oauth.conflicts
     };
   }
-  const native = await planDirectServers(agentId, mcp, managedAgents, policy, route);
+  const native = await planDirectServers(agentId, mcp, managedAgents, policy, route, void 0, options.hosted || agentId === "pi");
   const hosted = native.desired.filter(({ def }) => isOAuthMcpServer(def) && oauthOwner(def.auth) === "trellis");
   return {
     desired: native.desired.filter(({ def }) => !isOAuthMcpServer(def) || oauthOwner(def.auth) === "agent"),
     conflicts: [...native.conflicts, ...hosted.map(({ name }) => ({ name, message: `Trellis-owned OAuth server "${name}" requires gateway or runtime delivery for ${agentId}`, remediation: "enable gateway/runtime delivery or set auth.owner to agent" }))]
   };
 }
-async function planDirectServers(agentId, mcp, managedAgents, policy, route, filter) {
+async function planDirectServers(agentId, mcp, managedAgents, policy, route, filter, hosted = false) {
   const desired = [];
   const conflicts = [];
   for (const [name, def] of Object.entries(mcp.servers)) {
@@ -48020,7 +48106,12 @@ async function planDirectServers(agentId, mcp, managedAgents, policy, route, fil
       });
       continue;
     }
-    if (agentId === "codex" && def.headers && Object.keys(def.headers).length > 0 && !codexBearerTokenEnvVar(def)) {
+    const invalidHeader = invalidHeaderTemplate(def.headers);
+    if (invalidHeader !== void 0) {
+      conflicts.push({ name, message: `refusing to write MCP server "${name}": invalid reference template in header ${invalidHeader}`, remediation: "use ${VAR} or ${mxenv://<profile>/<KEY>} in headers" });
+      continue;
+    }
+    if (!hosted && agentId === "codex" && def.headers && Object.keys(def.headers).length > 0 && !codexBearerTokenEnvVar(def)) {
       conflicts.push({
         name,
         message: `refusing to write MCP server "${name}" for codex: its "headers" field isn't the single { Authorization: "Bearer \${VAR}" } shape Codex's own config format can express \u2014 Codex has no generic headers concept, only \`bearer_token_env_var\`. Still written normally for every other in-scope agent.`,
@@ -48029,9 +48120,9 @@ async function planDirectServers(agentId, mcp, managedAgents, policy, route, fil
       continue;
     }
     const unresolvedName = await findUnresolvedEnvName(def, policy);
-    if (unresolvedName) {
+    if (unresolvedName !== void 0) {
       const entry = parseEnvEntry(unresolvedName);
-      if (entry.kind === "invalid") {
+      if (entry.kind === "invalid" || !isValidSecretVarName(unresolvedName) && entry.kind === "name") {
         conflicts.push({
           name,
           message: `refusing to write MCP server "${name}": its declared env entry "${unresolvedName}" is not a valid mxenv://<profile>/<KEY> reference (mx-env-secret-source)`,
@@ -48048,6 +48139,14 @@ async function planDirectServers(agentId, mcp, managedAgents, policy, route, fil
       });
       continue;
     }
+    if (!hosted && Object.values(def.headers ?? {}).flatMap(extractTemplateVarNames).some((entry) => parseEnvEntry(entry).kind === "ref")) {
+      conflicts.push({
+        name,
+        message: `refusing to write MCP server "${name}": mxenv header references require Trellis gateway/runtime delivery; native clients cannot resolve them`,
+        remediation: `enable gateway/runtime delivery for ${agentId}, keeping transport and headers in servers.yaml`
+      });
+      continue;
+    }
     desired.push({ name, def });
   }
   return { desired, conflicts };
@@ -85364,12 +85463,6 @@ var StdioClientTransport = class {
   }
 };
 
-// src/lib/envVarNames.ts
-var TEMPLATE_VAR_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
-function extractTemplateVarNames(value) {
-  return [...value.matchAll(TEMPLATE_VAR_RE)].map((m6) => m6[1]);
-}
-
 // src/lib/mcpConnect.ts
 var DEFAULT_CONNECT_TIMEOUT_MS = 1e4;
 var FAILED_TRANSPORT_CLEANUP_TIMEOUT_MS = 1e3;
@@ -85432,11 +85525,24 @@ async function connectStdio(def, secretsPolicy, timeoutMs, clientInfo) {
 }
 async function resolveHeaders(def, secretsPolicy) {
   if (!def.headers || Object.keys(def.headers).length === 0) return void 0;
+  const invalidHeader = invalidHeaderTemplate(def.headers);
+  if (invalidHeader !== void 0) throw new Error(`[trellis] invalid reference template in header ${invalidHeader} \u2014 use \${VAR} or \${mxenv://<profile>/<KEY>}`);
   const names = Object.keys(def.headers).flatMap((key) => extractTemplateVarNames(def.headers[key]));
-  const resolved = await resolveSecretEnv(names, secretsPolicy);
+  for (const name of names) {
+    const entry = parseEnvEntry(name);
+    if (entry.kind === "invalid" || entry.kind === "name" && !isValidSecretVarName(name)) {
+      throw new Error(`[trellis] invalid header reference: ${name} \u2014 expected a variable name or mxenv://<profile>/<KEY>`);
+    }
+  }
+  const resolved = await resolveSecretEntries(names, secretsPolicy);
   const result = {};
   for (const [key, template] of Object.entries(def.headers)) {
-    result[key] = template.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => resolved[name] ?? "");
+    result[key] = replaceTemplateVars(template, (name) => {
+      if (parseEnvEntry(name).kind === "ref" && !resolved[name]) {
+        throw new Error(`[trellis] unresolved header reference: ${name}`);
+      }
+      return resolved[name] ?? "";
+    });
   }
   return result;
 }
@@ -85641,7 +85747,7 @@ ${sourceLine}` : sourceLine;
 };
 
 // src/lib/oauth/store.ts
-import { chmodSync, existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync4, renameSync, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { chmodSync, existsSync as existsSync5, mkdirSync as mkdirSync3, readFileSync as readFileSync5, renameSync, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { join as join7 } from "node:path";
 function oauthDir(homeDir) {
   return join7(homeDir, ".trellis", "mcp", "oauth");
@@ -85661,9 +85767,9 @@ function assertSafeServerName(serverName) {
 }
 function readToken(homeDir, serverName) {
   const path = tokenPath(homeDir, serverName);
-  if (!existsSync4(path)) return void 0;
+  if (!existsSync5(path)) return void 0;
   try {
-    return JSON.parse(readFileSync4(path, "utf-8"));
+    return JSON.parse(readFileSync5(path, "utf-8"));
   } catch {
     return void 0;
   }
@@ -85685,7 +85791,7 @@ function isExpired(token, skewMs = 6e4, now = Date.now()) {
 }
 
 // src/lib/oauth/lock.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync4, openSync, closeSync, readFileSync as readFileSync5, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync6, mkdirSync as mkdirSync4, openSync, closeSync, readFileSync as readFileSync6, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "node:fs";
 import { dirname as dirname3 } from "node:path";
 var STALE_AFTER_MS = 6e4;
 var POLL_INTERVAL_MS = 50;
@@ -85701,7 +85807,7 @@ function processAlive(pid) {
 function isStale(path, now) {
   let contents;
   try {
-    contents = JSON.parse(readFileSync5(path, "utf-8"));
+    contents = JSON.parse(readFileSync6(path, "utf-8"));
   } catch {
     return true;
   }
@@ -85726,7 +85832,7 @@ async function withServerLock(homeDir, serverName, fn, opts = {}) {
       break;
     } catch (err) {
       if (err.code !== "EEXIST") throw err;
-      if (existsSync5(path) && isStale(path, now())) {
+      if (existsSync6(path) && isStale(path, now())) {
         rmSync2(path, { force: true });
         continue;
       }
@@ -85826,10 +85932,10 @@ async function safeText(response) {
 }
 
 // src/lib/upstreamResources.ts
-var import_yaml3 = __toESM(require_dist(), 1);
+var import_yaml4 = __toESM(require_dist(), 1);
 
 // src/lib/skillManifest.ts
-var import_yaml2 = __toESM(require_dist(), 1);
+var import_yaml3 = __toESM(require_dist(), 1);
 var MAX_SKILL_BYTES = 16 * 1024 * 1024;
 var MAX_SKILL_FILE_BYTES = 256 * 1024;
 

package/docs/architecture.md

@@ -43,7 +43,7 @@ Aligned to the `.agents Protocol` draft, extended where the draft is silent:
 ├── mcp/servers.yaml          # single MCP source, values are var-name
 │                             # references only, never literals
 ├── memories/*.md             # shared memory entries (server-memory backed)
-├── scope.yaml                 # exceptions to "shared with all agents" —
+├── scope.yaml                 # skill compatibility registry; agent/memory scope
 │                             # see "Private / agent-specific capabilities"
 └── secrets.policy.yaml       # which var names are allowed, nothing else
 
@@ -132,12 +132,14 @@ one `trellis rollback` restores originals and removes generated
 
 Not everything belongs to all six agents. A skill built around Claude
 Code's Task-based subagent delegation has no equivalent to delegate to on
-Codex; an MCP server might only make sense for one agent's workflow. Every
-scopable item — skill, subagent profile, memory entry, MCP server —
-defaults to "shared with all managed agents," and can be restricted with an explicit
-`scope` (skills/agents/memories) or inline `agents:` (MCP servers, see
-below). Restriction is the exception you declare, not something you
-configure for the common case.
+Codex; an MCP server might only make sense for one agent's workflow.
+Every custom skill must register applicable agents in `scope.yaml`.
+Missing, empty or invalid skill scope pauses Trellis distribution and Runtime
+access; sync removes only Trellis-owned links. `skill scope --all` records
+the current managed set, so adding another agent never silently expands
+compatibility. Package-owned built-ins retain their package-defined policy.
+Subagent profiles, memory entries and MCP servers retain their existing
+all-managed default and explicit restrictions.
 
 **Skills, subagent profiles, and memory entries declare scope in
 `.trellis/scope.yaml`, never inside the artifact file itself.** This
@@ -150,6 +152,18 @@ portable file exactly as its target agent's own spec expects; Trellis's
 own bookkeeping lives next to it, not inside it. See
 `schema/scope.example.yaml`.
 
+Compatibility is explicit: Claude-specific workflows list `claude-code`,
+Codex-specific workflows list `codex`, and portable workflows list each
+reviewed agent. Publisher provenance does not prove compatibility. Hermes
+skills belong to Hermes's own curator/review/archive lifecycle; Trellis
+never manages or writes its skill directory.
+
+Workspace skills use `.agents/scope.yaml` for Trellis-managed delivery and
+Runtime access. Agents that discover `.agents/skills` natively can still
+read that shared source directly; per-agent Trellis registration does not
+override a native agent's own discovery. Keep agent-specific skills in the
+global canonical store when native discovery must be isolated.
+
 **MCP servers are the one exception** — `agents:` is declared inline per
 server in `mcp/servers.yaml` (see `schema/servers.example.yaml`), because
 that file is Trellis's own format and is never handed to an agent
@@ -629,6 +643,12 @@ acceptance criteria already describes this shape ("point at a scratch
 section exists to make it a project-wide rule that every later phase's
 acceptance criteria must follow, not a detail specific to P1.
 
+CLI fixtures must isolate the working directory as well as HOME. Running
+from the real checkout with only HOME changed can make ancestor discovery
+mistake the developer's `~/.agents/` for a workspace. Run the CLI by absolute
+path from the scratch directory; otherwise read-only parity checks can
+compare different layers and write tests can reach real project artifacts.
+
 This is also why P0 needing to resolve pi's actual skill-discovery path
 (§D5 in `openspec/changes/trellis-doctor-p0/design.md`) is investigated
 directly against a real pi installation *as a read-only observation*, and

package/docs/getting-started.md

@@ -465,9 +465,10 @@ $ trellis migrate --from codex --only instructions
 | `skip-case-broken` | Found as `skill.md` instead of `SKILL.md` — fix the case on the source agent first. |
 | `skip-unsupported` | The source capability can't be safely represented (including native memory without a supported adapter); nothing was written for it. |
 
-Migrate never overwrites a genuine conflict, and never scopes a migrated
-skill (or MCP server) to just the source agent — once in canonical, it's
-visible to every agent by default (see `sync`, below). If migrate reports
+Migrate never overwrites a genuine conflict. A newly migrated skill is
+registered only for its source agent; review its compatibility before
+sharing it through `trellis skill scope <name> --agents <ids>`.
+MCP servers retain their existing scope behavior. If migrate reports
 a `conflict`, open the two files/entries it names and decide by hand
 which content should actually be canonical, then re-run.
 
@@ -663,10 +664,10 @@ remains the command for a local directory:
 npx trellis add mattpocock/skills --list
 
 # Fetch and inspect the exact plan without writing canonical or Agent files.
-npx trellis add mattpocock/skills --skill loop-me --dry-run
+npx trellis add mattpocock/skills --skill loop-me --agent codex --dry-run
 
 # Import to the user-level canonical store, then sync to every managed Agent.
-npx trellis add mattpocock/skills --skill loop-me --yes
+npx trellis add mattpocock/skills --skill loop-me --agent '*' --yes
 ```
 
 The source may be `owner/repository` or a credential-free HTTPS
@@ -678,10 +679,11 @@ dependencies, or write into `.agents/skills`, `~/.agents/skills`, or any
 Agent-specific Skill directory during import. Review the imported
 `SKILL.md` before relying on it in an Agent session.
 
-By default the imported Skill is unscoped, which means every Agent currently
-listed in `~/.trellis/managed.yaml` receives it on sync. Restrict delivery to
-managed Agents with `--agent`; comma-separated values and repeated flags are
-accepted. `--agent '*'` writes the current managed set as an explicit scope.
+Imports require an explicit choice of applicable agents. Interactive terminals
+offer a selection with no agents preselected; noninteractive/JSON calls must
+supply `--agent`. Comma-separated values and repeated flags are accepted.
+`--agent '*'` records the current managed set; `--agent none` imports a paused
+skill. A newly managed agent does not receive existing skills automatically.
 An Agent that is installed but unmanaged is refused before any canonical or
 native write. Add it to Trellis's managed boundary first:
 
@@ -785,6 +787,24 @@ the first place (see `mcp sync`'s own explanation of `env` vs.
 All four of `skill add`/`skill remove`/`mcp add`/`mcp remove` support
 `--dry-run` and `--json`, same convention as every other command.
 
+Local imports use the same compatibility rule:
+
+```sh
+trellis skill add review --from ./skills/review --agents claude-code,codex
+trellis skill add pending --from ./skills/pending --none
+trellis skill list --agent codex --json
+trellis skill scope review --all
+```
+
+Every custom skill needs a `skills.<name>: [agent ids]` entry in
+`~/.trellis/scope.yaml` (or `.agents/scope.yaml` for workspace delivery).
+Unregistered skills pause until reviewed; sync removes only their
+Trellis-owned links and leaves independent files untouched. `skill list
+--agent` shows scoped skills with `linked`, `missing`, `conflict` or `runtime`
+delivery status. Codex's global delivery root is `~/.agents/skills`.
+Use `trellis sync skills --dry-run` before converging an older installation.
+Hermes maintains its own skills; Trellis never writes its skill store.
+
 ## `trellis sync`
 
 Distributes canonical skills and instructions to every **managed** agent

package/docs/research.md

@@ -223,8 +223,21 @@ which was silently invalid). Trellis's contribution here is `trellis secrets
 audit` — a linter that fails a build if any adapter output contains a raw
 credential — not a new secret store. The concrete reference form is
 `mxenv://<profile>/<KEY>` (mx-env-secret-source): written in `servers.yaml`
-`env`/`envAliases`, resolved from the encrypted mxenv store at consumption
-point, delivered under the `KEY` segment.
+`env`/`envAliases`, or inline in a header template such as
+`Authorization: Bearer ${mxenv://legacy/SERVICE_TOKEN}`, resolved from the
+mxenv profile at consumption time. Env references are delivered under the
+`KEY` segment; header references are substituted in memory and retain their
+profile identity even when two profiles use the same key. Missing keys,
+unknown profiles and malformed header references fail explicitly, without
+printing provider output or substituting an empty credential. Bare `${VAR}`
+headers retain their existing env-file/process-env behavior.
+
+Header references require Trellis gateway/runtime delivery (or pi's bridge),
+which resolves them independently of the GUI or shell's inherited environment.
+Native clients do not understand `mxenv://`; direct native sync reports a
+conflict with instructions to enable gateway/runtime, rather than writing an
+unusable reference or persisting its resolved value. The canonical server
+still uses `transport: http`/`sse`; no third-party stdio shim is needed.
 
 A third real incident during migrate-in: a source config's `${VAR}`
 reference doesn't always name itself (`OPENAPI_MCP_HEADERS:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-trellis",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "A unified Code Agent Runtime for Skills, MCP, Memory, and shared instructions across Claude Code, Codex, Kiro, pi, Kimi Code, and ZCode.",
   "license": "MIT",
   "author": "Paul Leo",