@stage-labs/metro 0.1.0-beta.279 → 0.1.0-beta.280

package/runtime/node_modules/@metro-labs/daemon/src/claude/github-validate.ts

@@ -0,0 +1,53 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { isRecord } from '@metro-labs/core/is-record';
+import { SKILL_NAME, skillGeneration, type SkillGeneration, type SkillSource } from '@metro-labs/core/skill-source';
+import { ApiError } from '@metro-labs/http/api-error';
+import type { GitHubSnapshot } from './github-fetch.js';
+
+const FIELDS = new Set(['name', 'description', 'argument-hint', 'disable-model-invocation', 'user-invocable']);
+export const skillDigest = (bytes: string | Uint8Array): string => createHash('sha256').update(bytes).digest('hex');
+
+function validRef(value: unknown): value is string {
+  return typeof value === 'string' && value.length <= 200 && /^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(value) && !value.includes('..') && !value.includes('//');
+}
+
+function validFolder(value: unknown): value is string {
+  if (typeof value !== 'string' || value.length > 240) return false;
+  if (value === '') return true;
+  const parts = value.split('/');
+  return parts.length <= 6 && parts.every((part) => /^[A-Za-z0-9._-]{1,80}$/.test(part) && part !== '.' && part !== '..');
+}
+
+export function githubSource(raw: unknown): SkillSource & { token: string } {
+  if (!isRecord(raw) || typeof raw.repository !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(raw.repository)) throw new ApiError('Use a GitHub repository in owner/repository form.', 400);
+  if (!validRef(raw.ref)) throw new ApiError('Use a branch, tag or full commit SHA.', 400);
+  if (!validFolder(raw.folder)) throw new ApiError('Use a relative skills folder, or leave it empty for the repository root.', 400);
+  if (typeof raw.token !== 'string' || !/^github_pat_[A-Za-z0-9_]{20,240}$/.test(raw.token)) throw new ApiError('Use a fine-grained GitHub token with Contents read access to this repository only.', 400);
+  return { repository: raw.repository, ref: raw.ref, folder: raw.folder, token: raw.token };
+}
+
+function passiveMetadata(meta: Record<string, unknown>): void {
+  if (Object.keys(meta).some((key) => !FIELDS.has(key))) throw new Error('Unsupported skill metadata. Only name, description, argument-hint, disable-model-invocation and user-invocable are allowed. Hooks, tool grants, model changes and agents are not imported.');
+  if (['disable-model-invocation', 'user-invocable'].some((key) => key in meta && typeof meta[key] !== 'boolean') || ('argument-hint' in meta && typeof meta['argument-hint'] !== 'string')) throw new Error('Invalid skill metadata types.');
+}
+
+function skillMetadata(name: string, bytes: Buffer): { name: string; description: string } {
+  const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+  if (match === null || /!`|\0/.test(text)) throw new Error('A skill needs YAML frontmatter. Shell substitutions are not supported.');
+  const meta: unknown = Bun.YAML.parse(match[1] ?? '');
+  if (!isRecord(meta) || meta.name !== name || !SKILL_NAME.test(name) || typeof meta.description !== 'string' || meta.description.trim() === '' || meta.description.length > 1024) throw new Error('A skill needs a name matching its folder and a description of up to 1024 characters.');
+  passiveMetadata(meta);
+  return { name, description: meta.description };
+}
+
+export function validatedGeneration(source: SkillSource | null, snapshot: GitHubSnapshot | null): SkillGeneration {
+  const files = snapshot?.files ?? new Map<string, Buffer>();
+  const skills = [...files].filter(([path]) => path.endsWith('/SKILL.md')).map(([path, bytes]) => skillMetadata(path.split('/')[0] ?? '', bytes));
+  const manifest = {
+    source: source === null || snapshot === null ? null : { repository: source.repository, ref: source.ref, folder: source.folder, repositoryId: snapshot.repositoryId, commit: snapshot.commit },
+    skills,
+    files: [...files].map(([path, bytes]) => ({ path, size: bytes.byteLength, sha256: skillDigest(bytes), ...(snapshot?.executables?.includes(path) === true ? { executable: true } : {}) })),
+  };
+  return skillGeneration({ ...manifest, id: skillDigest(randomUUID()), createdAt: new Date().toISOString() });
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/skills.ts

@@ -18,6 +18,8 @@ export interface ClaudeSkill {
   path: string;
   editable: boolean;
   updatedAt: string | null;
+  managed?: boolean;
+  shadowed?: boolean;
 }
 
 const frontmatterField = (text: string, field: string): string => {

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.279"
+  "version": "0.1.0-beta.280"
 }

package/runtime/sdk-runner/node_modules/@metro-labs/core/package.json

@@ -13,6 +13,7 @@
     "./automation-types": "./src/automation-types.ts",
     "./call": "./src/call.ts",
     "./secure-fs": "./src/secure-fs.ts",
+    "./skill-source": "./src/skill-source.ts",
     "./version": "./src/version.ts",
     "./train-error": "./src/train-error.ts",
     "./trains/protocol": "./src/protocol.ts",

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/skill-source.ts

@@ -0,0 +1,96 @@
+import { join } from 'node:path';
+import { isRecord } from './is-record.js';
+
+export const SKILL_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+export const SKILL_HASH = /^[a-f0-9]{64}$/;
+export const SKILL_COMMIT = /^[a-f0-9]{40}$/;
+export const SKILL_FILE_MAX = 256 * 1024;
+export const SKILL_TOTAL_MAX = 8 * 1024 * 1024;
+export const SKILL_FILES_MAX = 256;
+export const SKILL_MANIFEST_MAX = 128 * 1024;
+
+export interface SkillSource {
+  repository: string;
+  ref: string;
+  folder: string;
+}
+
+export interface SkillFile {
+  path: string;
+  size: number;
+  sha256: string;
+  executable?: boolean;
+}
+
+export interface SkillGeneration {
+  id: string;
+  source: (SkillSource & { repositoryId: number; commit: string }) | null;
+  createdAt: string;
+  skills: { name: string; description: string }[];
+  files: SkillFile[];
+}
+
+export interface SkillActivation {
+  generation: string | null;
+  loading: string | null;
+  rollback?: string | null;
+  appliedAt: string | null;
+  problem: string | null;
+  shadowed: string[];
+}
+
+export const skillSourceRoot = (claudeDir: string): string => join(claudeDir, 'metro-github');
+export const skillRelease = (root: string, id: string): string => {
+  if (!SKILL_HASH.test(id)) throw new Error('Invalid skills generation.');
+  return join(root, 'releases', id);
+};
+
+export function skillPath(path: string): boolean {
+  const parts = path.split('/');
+  return path.length <= 240 && parts.length >= 2 && parts.length <= 8 && SKILL_NAME.test(parts[0] ?? '') &&
+    parts.every((part) => /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(part)) &&
+    !parts.slice(1, -1).includes('SKILL.md') && !(parts.length > 2 && parts.at(-1) === 'SKILL.md');
+}
+
+function manifestSkill(value: unknown): SkillGeneration['skills'][number] {
+  if (!isRecord(value) || typeof value.name !== 'string' || !SKILL_NAME.test(value.name) || typeof value.description !== 'string' || value.description.length > 1024) throw new Error('Invalid skill name or description.');
+  return { name: value.name, description: value.description };
+}
+
+function fileSize(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > SKILL_FILE_MAX) throw new Error('Invalid skills file size.');
+  return value;
+}
+
+function manifestFile(value: unknown): SkillFile {
+  if (!isRecord(value)) throw new Error('Invalid skills file.');
+  if (typeof value.path !== 'string' || !skillPath(value.path) || typeof value.sha256 !== 'string' || !SKILL_HASH.test(value.sha256)) throw new Error('Invalid skills file path or hash.');
+  return { path: value.path, size: fileSize(value.size), sha256: value.sha256, ...(value.executable === true ? { executable: true } : {}) };
+}
+
+function manifestSource(s: unknown): SkillGeneration['source'] {
+  if (s === null) return null;
+  if (!isRecord(s) || typeof s.repository !== 'string' || typeof s.ref !== 'string' || typeof s.folder !== 'string' || typeof s.repositoryId !== 'number' || typeof s.commit !== 'string' || !SKILL_COMMIT.test(s.commit)) throw new Error('Invalid skills provenance.');
+  return { repository: s.repository, ref: s.ref, folder: s.folder, repositoryId: s.repositoryId, commit: s.commit };
+}
+
+function checkFiles(skills: SkillGeneration['skills'], files: SkillFile[]): void {
+  if (files.reduce((sum, file) => sum + file.size, 0) > SKILL_TOTAL_MAX || new Set(files.map((f) => f.path.toLowerCase())).size !== files.length || new Set(skills.map((s) => s.name)).size !== skills.length) throw new Error('Duplicate or oversized skills files.');
+  if (files.some((f) => !skills.some((s) => f.path.startsWith(`${s.name}/`))) || skills.some((s) => !files.some((f) => f.path === `${s.name}/SKILL.md`))) throw new Error('Every skill needs its own SKILL.md.');
+}
+
+function boundedGeneration(generation: SkillGeneration): SkillGeneration {
+  if (Buffer.byteLength(JSON.stringify(generation)) > SKILL_MANIFEST_MAX) throw new Error('Skills manifest is too large.');
+  return generation;
+}
+
+export function skillGeneration(raw: unknown): SkillGeneration {
+  if (!isRecord(raw) || typeof raw.id !== 'string' || !SKILL_HASH.test(raw.id) || typeof raw.createdAt !== 'string' || !Array.isArray(raw.skills) || !Array.isArray(raw.files)) throw new Error('Invalid skills manifest.');
+  if (raw.skills.length > 64 || raw.files.length > SKILL_FILES_MAX) throw new Error('Skills manifest is too large.');
+  const skills = raw.skills.map(manifestSkill);
+  const files = raw.files.map(manifestFile);
+  const source = manifestSource(raw.source);
+  checkFiles(skills, files);
+  if (source === null) checkFiles([], files);
+  return boundedGeneration({ id: raw.id, source, createdAt: raw.createdAt, skills, files });
+}

package/runtime/sdk-runner/runner.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0-beta.279",
+  "version": "0.1.0-beta.280",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.287",
     "@modelcontextprotocol/sdk": "^1.29.0",

package/runtime/sdk-runner/src/app.ts

@@ -2,6 +2,8 @@ import { dirname, join } from 'node:path';
 import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
 import { AutomationStore } from '@metro-labs/core/automation-store';
 import { errMsg, log } from '@metro-labs/core/log';
+import { skillSourceRoot } from '@metro-labs/core/skill-source';
+import { SkillsRefresh } from './skills.js';
 import { failureSummary, type Activity } from './activity.js';
 import { approvalsThrough } from './approvals.js';
 import type { RunnerConfig } from './config.js';
@@ -30,7 +32,8 @@ async function connected(cfg: RunnerConfig, hooks: AppHooks, release: () => Prom
   const store = new SessionStore(cfg.statePath, cfg.claudeDir, cfg.cwd);
   let tools: MetroTools | null = null;
   const automationStore = new AutomationStore(join(dirname(cfg.statePath), 'automation'));
-  const runner = new Runner({ store, automationStore, readOnly: (tool) => tools?.readOnly(tool) ?? false, ...hooks });
+  const skills = new SkillsRefresh(skillSourceRoot(cfg.claudeDir), cfg.claudeDir);
+  const runner = new Runner({ store, automationStore, skills, readOnly: (tool) => tools?.readOnly(tool) ?? false, ...hooks });
   const link = await MetroLink.open(cfg.mcpUrl, cfg.key, {
     channel: (event) => { runner.chat(event); },
     call: (notice) => { runner.calls.notice(notice); },

package/runtime/sdk-runner/src/runner.ts

@@ -1,5 +1,8 @@
 import { query, type CanUseTool, type Options, type Query, type SDKMessage, type SDKUserMessage } from '@anthropic-ai/claude-agent-sdk';
 import { errMsg, log } from '@metro-labs/core/log';
+import { skillSourceRoot } from '@metro-labs/core/skill-source';
+import { type SkillsRefresh } from './skills.js';
+import { SkillWork } from './skill-work.js';
 import { isRecord } from '@metro-labs/core/is-record';
 import type { AutomationStore } from '@metro-labs/core/automation-store';
 import type { Activity } from './activity.js';
@@ -41,6 +44,7 @@ export function runnerOptions(cfg: RunnerConfig, tools: MetroTools, canUseTool:
     env: runnerEnv(env),
     ...(cfg.claude === null ? {} : { pathToClaudeCodeExecutable: cfg.claude }),
     settingSources: ['user', 'project', 'local'],
+    additionalDirectories: [skillSourceRoot(cfg.claudeDir)],
     systemPrompt: { type: 'preset', preset: 'claude_code', append: cfg.prompt === null ? FRONT_RULES : `${cfg.prompt}\n\n${FRONT_RULES}` },
     mcpServers: { [METRO_SERVER]: tools.config },
     permissionMode: cfg.permissionMode,
@@ -73,6 +77,7 @@ export interface RunnerParts {
   open?: OpenSession;
   activity?: Activity;
   automationStore?: AutomationStore;
+  skills?: SkillsRefresh;
 }
 
 function streamOutput(event: Record<string, unknown>): boolean {
@@ -94,6 +99,7 @@ export class Runner {
   private readonly recovery: TaskRecovery;
   private readonly watch: SessionWatch;
   private readonly tasks = new ActivityTasks(() => undefined);
+  private readonly skillWork = new SkillWork();
   private compactTimer: ReturnType<typeof setTimeout> | null = null;
   private session: Query | null = null;
   private sessionId: string | null = null;
@@ -109,7 +115,7 @@ export class Runner {
   constructor(private readonly parts: RunnerParts) {
     this.watch = new SessionWatch(parts.readOnly);
     this.inbox = new Inbox((unanswered) => { this.keep(unanswered); }, {
-      ready: () => this.watch.admitting,
+      ready: () => { parts.skills?.check(); return this.watch.admitting && parts.skills?.busy !== true; },
       dispatch: (message) => { this.automation?.dispatched(message.uuid); this.watch.dispatched(message.uuid); },
       input: (input) => { this.cancelCompact(); parts.activity?.input(input); },
       queue: (count, oldest) => { parts.activity?.pending(count, oldest); },
@@ -146,6 +152,11 @@ export class Runner {
     this.session = (this.parts.open ?? query)({ prompt: this.inbox, options });
     this.model = options.model ?? null;
     this.queueModel(this.model);
+    this.parts.skills?.start({
+      safe: () => !this.ended && this.watch.safe && this.watch.admitting && this.compactAsked === null && !this.calls.live && this.skillWork.safe,
+      reload: () => this.session?.reloadSkills() ?? Promise.reject(new Error('The SDK session is closed.')),
+      wake: () => { this.inbox.notify(); },
+    });
     this.recovery.start();
     this.automation?.start();
     return this.session;
@@ -167,7 +178,7 @@ export class Runner {
         this.recovery.observe(m);
         this.automation?.observe(m);
         this.trackInput(m);
-        this.watch.observe(m);
+        this.observeWork(m);
         this.note(m);
         this.parts.activity?.observe(message);
         this.inbox.notify();
@@ -176,6 +187,7 @@ export class Runner {
       }
     } finally {
       this.cancelCompact();
+      this.parts.skills?.close();
       this.automation?.close(false);
       this.recovery.close(false);
       this.ended = true;
@@ -200,6 +212,7 @@ export class Runner {
 
   close(cancelActive = false): void {
     this.cancelCompact();
+    this.parts.skills?.close();
     this.calls.close();
     try {
       this.recovery.close(cancelActive);
@@ -281,8 +294,18 @@ export class Runner {
     }
   }
 
+  private observeWork(message: Record<string, unknown>): void {
+    this.watch.observe(message);
+    this.skillWork.observe(message);
+    this.parts.skills?.check();
+  }
+
+  private get maintenanceBusy(): boolean {
+    return this.ended || this.parts.skills?.busy === true || this.compactAsked !== null || !this.watch.safe || !this.watch.admitting;
+  }
+
   private compactReady(resuming = false): boolean {
-    const busy = this.ended || this.compactAsked !== null || !this.watch.safe || !this.watch.admitting || (!resuming && (this.calls.live || this.inbox.pending > 0 || this.tasks.running > 0));
+    const busy = this.maintenanceBusy || (!resuming && (this.calls.live || this.inbox.pending > 0 || this.tasks.running > 0));
     return compactDue({ context: this.watch.context, floor: this.compactFloor, limit: this.parts.compactAt ?? COMPACT_AT, busy });
   }
 

package/runtime/sdk-runner/src/skill-work.ts

@@ -0,0 +1,76 @@
+import { isRecord } from '@metro-labs/core/is-record';
+
+const TERMINAL = new Set(['completed', 'failed', 'killed', 'stopped']);
+interface Task { tool: string | null; background: boolean }
+
+export class SkillWork {
+  private readonly tasks = new Map<string, Task>();
+  private readonly tools = new Map<string, string | null>();
+  private overflow = false;
+  get safe(): boolean { return !this.overflow && this.tasks.size === 0 && this.tools.size === 0; }
+
+  private blocks(message: Record<string, unknown>): void {
+    if (!isRecord(message.message) || !Array.isArray(message.message.content)) return;
+    const parent = typeof message.parent_tool_use_id === 'string' ? message.parent_tool_use_id : null;
+    for (const block of message.message.content.filter(isRecord)) {
+      if (block.type === 'tool_use' && typeof block.id === 'string') this.tools.set(block.id, parent);
+      if (block.type === 'tool_result' && typeof block.tool_use_id === 'string') this.tools.delete(block.tool_use_id);
+    }
+  }
+
+  private retire(id: string, tool = this.tasks.get(id)?.tool): void {
+    this.tasks.delete(id);
+    if (tool == null) return;
+    const retired = new Set([tool]);
+    for (let changed = true; changed;) {
+      changed = false;
+      for (const [child, parent] of this.tools) {
+        if (parent === null || !retired.has(parent) || retired.has(child)) continue;
+        retired.add(child);
+        changed = true;
+      }
+    }
+    for (const child of retired) this.tools.delete(child);
+  }
+
+  private background(id: string, value: unknown): boolean {
+    return typeof value === 'boolean' ? value : this.tasks.get(id)?.background ?? false;
+  }
+
+  private task(message: Record<string, unknown>): void {
+    if (typeof message.task_id !== 'string') return;
+    const id = message.task_id;
+    const tool = typeof message.tool_use_id === 'string' ? message.tool_use_id : this.tasks.get(id)?.tool ?? null;
+    if (message.subtype === 'task_started') this.tasks.set(id, { tool, background: this.background(id, message.is_backgrounded) });
+    if (message.subtype === 'task_notification') this.retire(id, tool);
+    if (message.subtype === 'task_updated' && isRecord(message.patch)) this.patch(id, message.patch);
+  }
+
+  private patch(id: string, patch: Record<string, unknown>): void {
+    if (TERMINAL.has(String(patch.status))) { this.retire(id); return; }
+    if (!this.tasks.has(id) && !['running', 'paused', 'pending'].includes(String(patch.status))) return;
+    const task = this.tasks.get(id) ?? { tool: null, background: false };
+    if (typeof patch.is_backgrounded === 'boolean') task.background = patch.is_backgrounded;
+    this.tasks.set(id, task);
+  }
+
+  private snapshot(entries: unknown[]): void {
+    const ids = new Set(entries.filter(isRecord).flatMap((task) => typeof task.task_id === 'string' ? [task.task_id] : []));
+    for (const [id, task] of this.tasks) if (task.background && !ids.has(id)) this.retire(id);
+    for (const id of ids) this.tasks.set(id, { tool: this.tasks.get(id)?.tool ?? null, background: true });
+  }
+
+  private frontDone(message: Record<string, unknown>): void {
+    if (message.parent_tool_use_id != null) return;
+    for (const [id, parent] of this.tools) if (parent === null) this.tools.delete(id);
+  }
+
+  observe(message: Record<string, unknown>): void {
+    if (this.overflow) return;
+    this.blocks(message);
+    if (message.type === 'result') this.frontDone(message);
+    if (message.type === 'system') this.task(message);
+    if (message.subtype === 'background_tasks_changed' && Array.isArray(message.tasks)) this.snapshot(message.tasks);
+    this.overflow = this.tools.size > 4096 || this.tasks.size > 4096;
+  }
+}

package/runtime/sdk-runner/src/skills-files.ts

@@ -0,0 +1,169 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, constants, fstatSync, openSync, readSync, lstatSync, statSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, symlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { isRecord } from '@metro-labs/core/is-record';
+import { SKILL_FILE_MAX, SKILL_HASH, SKILL_MANIFEST_MAX, skillGeneration, skillRelease, type SkillGeneration } from '@metro-labs/core/skill-source';
+
+const digest = (bytes: string | Uint8Array): string => createHash('sha256').update(bytes).digest('hex');
+const LINK = /^\.\.\/releases\/[a-f0-9]{64}\/visible-[a-f0-9]{64}$/;
+
+function directory(path: string): void {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  if (!lstatSync(path).isDirectory()) throw new Error('The managed skills directory is not a regular directory.');
+}
+
+export function prepareSkillsRoot(root: string): void {
+  directory(root);
+  directory(join(root, 'releases'));
+  directory(join(root, '.claude'));
+}
+
+export function pendingSkills(root: string): SkillGeneration | null {
+  const path = join(root, 'pending.json');
+  let stat;
+  try { stat = lstatSync(path); } catch (err) { if (isRecord(err) && err.code === 'ENOENT') return null; throw err; }
+  if (!stat.isFile() || stat.size > SKILL_MANIFEST_MAX) throw new Error('Invalid pending skills manifest.');
+  return skillGeneration(JSON.parse(readFileSync(path, 'utf8')) as unknown);
+}
+
+function localText(file: string): string {
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NONBLOCK);
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > SKILL_FILE_MAX) throw new Error('A local skill cannot be checked safely.');
+    const bytes = Buffer.alloc(SKILL_FILE_MAX + 1);
+    let size = 0;
+    for (;;) {
+      const read = readSync(fd, bytes, size, bytes.length - size, size);
+      if (read === 0) break;
+      size += read;
+      if (size === bytes.length) break;
+    }
+    if (size > SKILL_FILE_MAX) throw new Error('A local skill is too large.');
+    return bytes.subarray(0, size).toString('utf8');
+  } finally { closeSync(fd); }
+}
+
+export type LocalAliases = Map<string, { signature: string; name: string | null }>;
+
+function localAlias(file: string, cache: LocalAliases): string | null {
+  try {
+    const stat = statSync(file);
+    const signature = `${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`;
+    const cached = cache.get(file);
+    if (cached?.signature === signature) return cached.name;
+    const header = /^---\r?\n([\s\S]*?)\r?\n---/.exec(localText(file))?.[1];
+    const meta: unknown = header === undefined ? null : Bun.YAML.parse(header);
+    const name = isRecord(meta) && typeof meta.name === 'string' ? meta.name : null;
+    cache.set(file, { signature, name });
+    return name;
+  } catch (err) { return isRecord(err) && ['ENOENT', 'ENOTDIR'].includes(String(err.code)) ? null : '*'; }
+}
+
+export function localSkillNames(claude: string, cache: LocalAliases = new Map()): string[] {
+  const names = new Set<string>();
+  let folders: string[];
+  try { folders = readdirSync(join(claude, 'skills')); } catch (err) { if (isRecord(err) && err.code === 'ENOENT') return []; throw err; }
+  if (folders.length > 2000) return ['*'];
+  const paths = new Set<string>();
+  for (const name of folders) {
+    names.add(name);
+    const path = join(claude, 'skills', name, 'SKILL.md');
+    paths.add(path);
+    const alias = localAlias(path, cache);
+    if (alias !== null) names.add(alias);
+  }
+  for (const path of cache.keys()) if (!paths.has(path)) cache.delete(path);
+  return [...names].sort();
+}
+
+export function projectionKey(generation: SkillGeneration, locals: string[]): string {
+  return `${generation.id}:${digest(JSON.stringify(locals))}`;
+}
+
+function onlyManifestFiles(root: string, generation: SkillGeneration): void {
+  const files = new Set(generation.files.map((file) => file.path));
+  const directories = new Set(generation.files.flatMap((file) => file.path.split('/').slice(0, -1).map((_part, index, parts) => parts.slice(0, index + 1).join('/'))));
+  const visit = (path: string): void => {
+    for (const entry of readdirSync(join(root, path), { withFileTypes: true })) {
+      const relative = path === '' ? entry.name : `${path}/${entry.name}`;
+      if (entry.isDirectory() && directories.has(relative)) visit(relative);
+      else if (!entry.isFile() || !files.has(relative)) throw new Error('Unexpected file in staged skills.');
+    }
+  };
+  visit('');
+}
+
+function verifiedFiles(release: string, generation: SkillGeneration): void {
+  directory(release);
+  directory(join(release, 'skills'));
+  onlyManifestFiles(join(release, 'skills'), generation);
+  for (const file of generation.files) {
+    let parent = join(release, 'skills');
+    for (const part of file.path.split('/').slice(0, -1)) {
+      parent = join(parent, part);
+      if (!lstatSync(parent).isDirectory()) throw new Error('A managed skill contains a linked directory.');
+    }
+    const path = join(release, 'skills', file.path);
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.size !== file.size || digest(readFileSync(path)) !== file.sha256) throw new Error('A staged skill changed before activation.');
+  }
+}
+
+export function projectSkills(root: string, generation: SkillGeneration, locals: string[]): { target: string; shadowed: string[] } {
+  prepareSkillsRoot(root);
+  const release = skillRelease(root, generation.id);
+  verifiedFiles(release, generation);
+  const shadowed = generation.skills.filter((skill) => locals.includes('*') || locals.includes(skill.name)).map((skill) => skill.name);
+  const name = `visible-${digest(JSON.stringify(locals))}`;
+  const visible = join(release, name);
+  directory(visible);
+  const expected = generation.skills.filter((skill) => !shadowed.includes(skill.name)).map((skill) => skill.name);
+  if (readdirSync(visible).some((entry) => !expected.includes(entry))) throw new Error('Unexpected file in skills projection.');
+  for (const skill of generation.skills) {
+    if (shadowed.includes(skill.name)) continue;
+    const path = join(visible, skill.name);
+    try { symlinkSync(`../skills/${skill.name}`, path, 'dir'); }
+    catch (err) { if (!isRecord(err) || err.code !== 'EEXIST' || readlinkSync(path) !== `../skills/${skill.name}`) throw err; }
+  }
+  return { target: `../releases/${generation.id}/${name}`, shadowed };
+}
+
+export function currentSkills(root: string): string | null {
+  try {
+    const target = readlinkSync(join(root, '.claude', 'skills'));
+    if (!LINK.test(target)) throw new Error('The managed skills link has an unexpected target.');
+    return target;
+  } catch (err) { if (isRecord(err) && err.code === 'ENOENT') return null; throw err; }
+}
+
+export function switchSkills(root: string, target: string | null): void {
+  prepareSkillsRoot(root);
+  const link = join(root, '.claude', 'skills');
+  currentSkills(root);
+  if (target === null) { rmSync(link, { force: true }); return; }
+  if (!LINK.test(target)) throw new Error('Invalid managed skills target.');
+  const next = `${link}-${randomUUID()}`;
+  try { symlinkSync(target, next, 'dir'); renameSync(next, link); }
+  finally { rmSync(next, { force: true }); }
+}
+
+function oldRelease(path: string): boolean {
+  let stat;
+  try { stat = lstatSync(join(path, 'manifest.json')); }
+  catch (err) { if (!isRecord(err) || err.code !== 'ENOENT') throw err; stat = lstatSync(path); }
+  return Date.now() - stat.mtimeMs > 5 * 60_000;
+}
+
+export function pruneSkills(root: string, keep: Set<string>): void {
+  const pending = pendingSkills(root);
+  if (pending !== null) keep.add(pending.id);
+  for (const id of readdirSync(join(root, 'releases'))) {
+    if (!SKILL_HASH.test(id) || keep.has(id)) continue;
+    const release = skillRelease(root, id);
+    if (!lstatSync(release).isDirectory()) continue;
+    try {
+      if (oldRelease(release)) rmSync(release, { recursive: true });
+    } catch (err) { if (!isRecord(err) || err.code !== 'ENOENT') throw err; }
+  }
+}