@milpa/comal 0.0.0-stage → 0.1.1

package/src/session.mjs

@@ -0,0 +1,71 @@
+import { mkdir, open, readFile, readdir, appendFile, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const validId = id => /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(id);
+export class Session {
+  constructor(root, id, records, persistent = true) {
+    this.root = root; this.id = id; this.records = records; this.persistent = persistent;
+    this.path = join(root, '.harness', 'sessions', `${id}.jsonl`);
+    this.queue = Promise.resolve();
+  }
+  static async create(root, system, options = {}) {
+    root = await realpath(root);
+    const record = { type: 'session', version: 1, id: randomUUID(), root, system, created_at: new Date().toISOString() };
+    const session = new Session(root, record.id, [record], options.persistent !== false);
+    if (session.persistent) {
+      await mkdir(join(root, '.harness', 'sessions'), { recursive: true, mode: 0o700 });
+      const file = await open(session.path, 'wx', 0o600);
+      try { await file.writeFile(JSON.stringify(record) + '\n'); } finally { await file.close(); }
+    }
+    return session;
+  }
+  static async load(root, id) {
+    if (!validId(id)) throw new Error('ID de sesión inválido; se requiere un UUID.');
+    root = await realpath(root);
+    const path = join(root, '.harness', 'sessions', `${id}.jsonl`);
+    const records = (await readFile(path, 'utf8')).trimEnd().split('\n').map((line, i) => {
+      try { return JSON.parse(line); } catch { throw new Error(`Sesión dañada en la línea ${i + 1}; no se reejecutaron herramientas.`); }
+    });
+    const header = records[0];
+    if (header?.type !== 'session' || header.version !== 1 || header.root !== root || header.id !== id) throw new Error('La sesión no pertenece a este directorio o usa otro formato.');
+    return new Session(root, id, records);
+  }
+  static async list(root) {
+    const dir = join(root, '.harness', 'sessions');
+    let names;
+    try { names = await readdir(dir); } catch (e) { if (e.code === 'ENOENT') return []; throw e; }
+    const sessions = await Promise.all(names.filter(n => validId(n.slice(0, -6)) && n.endsWith('.jsonl')).map(async name => {
+      const s = await Session.load(root, name.slice(0, -6));
+      const first = s.messages.find(m => m.role === 'user');
+      return { id: s.id, created_at: s.records[0].created_at, prompt: typeof first?.content === 'string' ? first.content.slice(0, 100) : '', messages: s.messages.length };
+    }));
+    return sessions.sort((a, b) => b.created_at.localeCompare(a.created_at));
+  }
+  get system() { return this.records[0].system; }
+  get messages() { return this.records.filter(r => r.type === 'message').map(r => r.message); }
+  async append(record) {
+    const item = { ...record, at: new Date().toISOString() };
+    this.queue = this.queue.then(async () => {
+      if (this.persistent) await appendFile(this.path, JSON.stringify(item) + '\n', { mode: 0o600 });
+      this.records.push(item);
+    });
+    return this.queue;
+  }
+  async message(message) { return this.append({ type: 'message', message }); }
+  async recoverPendingTools() {
+    const pending = new Map();
+    for (const msg of this.messages) {
+      if (!Array.isArray(msg.content)) continue;
+      for (const block of msg.content) {
+        if (msg.role === 'assistant' && block.type === 'tool_use') pending.set(block.id, block);
+        if (msg.role === 'user' && block.type === 'tool_result') pending.delete(block.tool_use_id);
+      }
+    }
+    if (pending.size) await this.message({ role: 'user', content: [...pending.keys()].map(id => ({
+      type: 'tool_result', tool_use_id: id, is_error: true,
+      content: 'El proceso terminó antes de registrar el resultado. El efecto es desconocido; inspecciona el estado antes de volver a intentar. La llamada no se reejecutó.'
+    })) });
+    return pending.size;
+  }
+}

package/src/sessions.mjs

@@ -0,0 +1,140 @@
+import { performance } from 'node:perf_hooks';
+import { SessionJournalCache } from './session-read-cache.mjs';
+import { mkdir, open, readFile, readdir, unlink, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { defaultStateDir } from './compat.mjs';
+import { auditJournal, sealRecord } from './audit.mjs';
+import { acquireProcessLock } from './process-lock.mjs';
+
+export class SessionStore {
+  #journalCache;
+  constructor({ cwd, stateDir = defaultStateDir(cwd), journalCacheBytes=8*1024*1024 }) {
+    this.cwd = cwd;
+    this.dir = path.join(stateDir, 'sessions', createHash('sha256').update(cwd).digest('hex').slice(0, 16));
+    this.writers = new Map();
+    this.#journalCache=new SessionJournalCache({maxBytes:journalCacheBytes});
+    this.lastLoadProfile=null;
+  }
+  file(id) {
+    if (!/^[a-f0-9-]{36}$/.test(id)) throw new Error('ID de sesión inválido.');
+    return path.join(this.dir, `${id}.jsonl`);
+  }
+  async validateForRecovery(id) {
+    // Do not go through load(): append's own writer promise may be awaiting us.
+    const rows=(await readFile(this.file(id),'utf8')).trim().split('\n').map(JSON.parse);
+    if(rows[0]?.type!=='session' || rows[0]?.id!==id || rows[0]?.cwd!==this.cwd || !auditJournal(rows).consistent)throw Object.assign(new Error('Libro inválido; no se retiró el lock ni se ejecutaron efectos.'),{code:'AUDIT_INVALID'});
+  }
+  async create(model, provider = 'anthropic') {
+    await mkdir(this.dir, { recursive: true, mode: 0o700 });
+    const id = randomUUID(), file = await open(this.file(id), 'wx', 0o600);
+    try { await file.writeFile(JSON.stringify(sealRecord({ type: 'session', id, cwd: this.cwd, model, provider, created_at: new Date().toISOString() }, 0)) + '\n'); await file.sync(); }
+    finally { await file.close(); }
+    return this.load(id);
+  }
+  async load(id) {
+    const began=performance.now();
+    this.lastLoadProfile={pid:process.pid,session_id:id,status:'loading',phase:'wait_writers'};
+    try {
+    while (this.writers.has(id)) await this.writers.get(id).catch(() => {});
+    this.lastLoadProfile.phase='read';
+    const waitDone=performance.now(),bytes=await readFile(this.file(id)),readDone=performance.now();
+    this.lastLoadProfile.phase='parse';this.lastLoadProfile.bytes_read=bytes.length;
+    const rows=bytes.toString('utf8').trim().split('\n').map(row=>JSON.parse(row)),parseDone=performance.now();
+    if (rows[0]?.type !== 'session' || rows[0].cwd !== this.cwd) throw new Error('La sesión pertenece a otro directorio o es inválida.');
+    this.lastLoadProfile.phase='fold';
+    let messages = []; const historyMessages = []; let metadata = rows[0], goal, queue, draft = '', draftAttachments = [], compaction, projection;
+    for (const row of rows.slice(1)) {
+      if (row.type === 'reset') { messages = []; historyMessages.length = 0; compaction = undefined; projection = undefined; }
+      if (row.type === 'compaction') { messages = row.messages.slice(); compaction = row; }
+      if (row.type === 'context_projection') { messages = row.messages.slice(); projection = row; compaction = row; }
+      if (row.type === 'context_rebase') { messages = row.messages.slice(); projection = undefined; compaction = undefined; }
+      if (row.type === 'message') { messages.push(row.message); historyMessages.push(row.message); }
+      if (row.type === 'model') metadata = { ...metadata, model: row.model };
+      if (row.type === 'provider') metadata = { ...metadata, provider: row.provider, model: row.model, ...(row.profile !== undefined ? {provider_profile:row.profile} : {}),...(row.connection ? {provider_connection:row.connection} : {}) };
+      if (row.type === 'goal') goal = row.goal;
+      if (row.type === 'queue') queue = row.snapshot;
+      if (row.type === 'draft') { draft = row.text; draftAttachments = row.attachments || []; }
+      if (row.type === 'name') metadata = { ...metadata, name: row.name };
+      if (row.type === 'parent') metadata = { ...metadata, parent_session_id: row.parent_session_id, subagent_type: row.subagent_type, name: row.description };
+    }
+    this.lastLoadProfile.phase='audit';
+    const foldDone=performance.now(),cachedAudit=this.#journalCache.get(id,bytes),cacheDone=performance.now();
+    const journalAudit=cachedAudit || auditJournal(rows),auditDone=performance.now();
+    if(!cachedAudit)this.#journalCache.set(id,bytes,journalAudit);
+    this.lastLoadProfile={pid:process.pid,session_id:id,status:'returned',phase:'complete',bytes_read:bytes.length,rows:rows.length,wait_writers_ms:waitDone-began,read_ms:readDone-waitDone,parse_ms:parseDone-readDone,fold_ms:foldDone-parseDone,cache_compare_ms:cacheDone-foldDone,audit_ms:auditDone-cacheDone,total_ms:performance.now()-began,audit_source:cachedAudit?'verified_identical_bytes':'full_journal_replay',cache:this.#journalCache.status()};
+    return { ...metadata, messages, historyMessages, compaction, projection, rows, journalAudit, goal, queue, draft, draftAttachments };
+    }catch(error){this.lastLoadProfile={...this.lastLoadProfile,status:'failed',error_code:error.code || error.name,total_ms:performance.now()-began,cache:this.#journalCache.status()};throw error;}
+  }
+  getLoadProfile(){return this.lastLoadProfile?structuredClone(this.lastLoadProfile):null;}
+  async append(id, record) {
+    const previous = this.writers.get(id) || Promise.resolve();
+    const next = previous.catch(() => {}).then(async () => {
+      const name = this.file(id), lockPath = `${name}.append.lock`;
+      const mutex=await acquireProcessLock(lockPath,{waitMs:5000,validate:()=>this.validateForRecovery(id)});
+      let file;
+      try {
+        file = await open(name, 'r+'); const size = (await file.stat()).size;
+        // Read the complete final record, without rehashing the entire book for every append.
+        let span = Math.min(size, 65536), tail;
+        while (true) {
+          const bytes = Buffer.alloc(span); await file.read(bytes, 0, span, size - span);
+          const text = bytes.toString('utf8').trimEnd(), split = text.lastIndexOf('\n');
+          if (split >= 0 || span === size) { tail = JSON.parse(text.slice(split + 1)); break; }
+          span = Math.min(size, span * 2);
+        }
+        let sequence, previousHash;
+        if (tail.audit) {
+          const expected = sealRecord(tail, tail.audit.sequence, tail.audit.previous_sha256).audit;
+          if (tail.audit.sha256 !== expected.sha256) throw new Error('Audit del libro inválido; no se añadió el registro.');
+          sequence = tail.audit.sequence + 1; previousHash = tail.audit.sha256;
+        } else {
+          const rows = (await readFile(name, 'utf8')).trim().split('\n').map(JSON.parse), audit = auditJournal(rows);
+          if (!audit.consistent) throw new Error('Audit del libro inválido; no se añadió el registro.');
+          sequence = rows.length; previousHash = audit.tip_sha256;
+        }
+        const row = sealRecord({ ...record, ...(mutex.recovered?{recovered_append_lock:mutex.recovered}:{}), timestamp: new Date().toISOString() }, sequence, previousHash);
+        const bytes = Buffer.from(JSON.stringify(row) + '\n');
+        for (let offset = 0; offset < bytes.length;) { const written = await file.write(bytes, offset, bytes.length - offset, size + offset); if (!written.bytesWritten) throw new Error('No se pudo completar el asiento del libro.'); offset += written.bytesWritten; }
+        await file.sync(); return row;
+      } finally { await file?.close(); await mutex.release(); }
+    });
+    this.writers.set(id, next);
+    try { return await next; } finally { if (this.writers.get(id) === next) this.writers.delete(id); }
+  }
+  // Serialize work-state read/validate/append across coordinator instances/processes.
+  // Separate from the turn lock: work operations run inside an already locked turn.
+  async workTransaction(id, action) {
+    const lockPath = `${this.file(id)}.work.lock`, mutex=await acquireProcessLock(lockPath,{waitMs:5000,validate:()=>this.validateForRecovery(id)});
+    try { if(mutex.recovered)await this.append(id,{type:'session_lock_recovered',source:'session_host',kind:'work',...mutex.recovered}); return await action(); }
+    finally { await mutex.release(); }
+  }
+  async list({ includeChildren = false } = {}) {
+    let names; try { names = await readdir(this.dir); } catch (e) { if (e.code === 'ENOENT') return []; throw e; }
+    const items = [];
+    for (const name of names.filter(n => n.endsWith('.jsonl'))) {
+      try {
+        const session = await this.load(name.slice(0, -6));
+        if (session.parent_session_id && !includeChildren) continue;
+        const first = session.historyMessages.find(m => m.role === 'user' && typeof m.content === 'string');
+        items.push({ id: session.id, name: session.name, parent_session_id: session.parent_session_id, model: session.model, provider:session.provider, provider_profile:session.provider_profile, created_at: session.created_at, updated_at: session.rows.at(-1).timestamp || session.created_at, messages: session.messages.length, prompt: first?.content.slice(0, 70) || '(vacía)' });
+      } catch { items.push({ id: name.slice(0, -6), model: '?', messages: 0, prompt: '(sesión dañada)', invalid: true, updated_at: '' }); }
+    }
+    return items.sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+  }
+  async lock(id, { kind = 'turn', withinGoal = false } = {}) {
+    if (!['turn', 'goal'].includes(kind)) throw new Error('Tipo de lock inválido.');
+    const base = this.file(id), lockPath = `${base}${kind === 'goal' ? '.goal' : ''}.lock`;
+    const exists = async file => { try { await stat(file); return true; } catch (e) { if (e.code === 'ENOENT') return false; throw e; } };
+    if (kind === 'turn' && !withinGoal && await exists(`${base}.goal.lock`)) {
+      throw new Error('La sesión tiene un /goal pendiente o en ejecución. Usa /goal resume para conservar su presupuesto; no se retiró su lock.');
+    }
+    const mutex=await acquireProcessLock(lockPath,{validate:()=>this.validateForRecovery(id)});
+    if ((kind === 'goal' && await exists(`${base}.lock`)) || (kind === 'turn' && !withinGoal && await exists(`${base}.goal.lock`))) {
+      await mutex.release(); throw new Error('Sesión en uso por un turno o /goal.');
+    }
+    try{if(mutex.recovered)await this.append(id,{type:'session_lock_recovered',source:'session_host',kind,...mutex.recovered});}
+    catch(error){await mutex.release();throw error;}
+    return mutex.release;
+  }
+}

package/src/skill-runtime.mjs

@@ -0,0 +1,130 @@
+import { randomUUID } from 'node:crypto';
+import { digest, immutable } from './operations.mjs';
+import { normalizeEffort } from './model-controls.mjs';
+import { acquireProcessLock, processIdentity, processDead } from './process-lock.mjs';
+
+const failure = (message, code = 'SKILL_MANIFEST_INVALID') => Object.assign(new Error(message), { code });
+const priorLease = prior => prior ? Object.fromEntries(['action', 'pack', 'task_id', 'plan_version', 'work_digest', 'turn_id', 'tools'].filter(key => prior[key] !== undefined).map(key => [key, prior[key]])) : null;
+const controlEvidence = controls => {
+  const result = Object.fromEntries(['model', 'effort', 'provider', 'profile', 'thinking'].filter(key => typeof controls[key] === 'string').map(key => [key, controls[key]]));
+  if (controls.provider_ref !== undefined) {
+    const ref = controls.provider_ref;
+    if (!ref || typeof ref !== 'object' || Object.keys(ref).some(key => !['row', 'digest'].includes(key)) || !Number.isSafeInteger(ref.row) || ref.row < 0 || typeof ref.digest !== 'string' || !/^[a-f0-9]{64}$/.test(ref.digest)) throw failure('Referencia de proveedor inválida para la skill.', 'SKILL_CONTROL_REFERENCE');
+    result.provider_ref = { row: ref.row, digest: ref.digest };
+  }
+  return result;
+};
+export function compileSkill({ name, content, manifest = {}, file = null }) {
+  if (typeof name !== 'string' || !/^[a-z][a-z0-9-]*$/.test(name) || typeof content !== 'string' || content.length > 32000 || !manifest || typeof manifest !== 'object' || Array.isArray(manifest)) throw failure('Skill inválida.');
+  for (const key of Object.keys(manifest)) if (!['name', 'description', 'allowed_tools', 'model', 'effort', 'context'].includes(key)) throw failure('Campo de manifiesto de skill desconocido: ' + key);
+  if (manifest.name !== undefined && manifest.name !== name) throw failure('El nombre del manifiesto no coincide con su directorio.');
+  if (manifest.description !== undefined && (typeof manifest.description !== 'string' || manifest.description.length > 300)) throw failure('Descripción de skill inválida.');
+  if (manifest.allowed_tools !== undefined && (!Array.isArray(manifest.allowed_tools) || manifest.allowed_tools.length > 24 || new Set(manifest.allowed_tools).size !== manifest.allowed_tools.length || manifest.allowed_tools.some(tool => typeof tool !== 'string' || !/^[A-Za-z][A-Za-z0-9_-]{0,127}$/.test(tool)))) throw failure('allowed_tools requiere hasta 24 nombres canónicos únicos, sin wildcards.');
+  if (manifest.model !== undefined && (typeof manifest.model !== 'string' || !manifest.model || manifest.model.length > 128 || /[\x00-\x1f\x7f]/.test(manifest.model))) throw failure('Modelo solicitado por skill inválido.');
+  if (manifest.effort !== undefined) normalizeEffort(manifest.effort);
+  if (manifest.context !== undefined && !['inline', 'fork'].includes(manifest.context)) throw failure('context debe ser inline o fork.');
+  const normalized = { context: 'inline', ...structuredClone(manifest) };
+  return immutable({ name, content, manifest: normalized, file, digest: digest({ name, content, manifest: normalized }) });
+}
+
+// This controller narrows a host-bound executor. It never constructs permission or model grants.
+export class SkillRuntime {
+  constructor({ house, store, toolPacks, sessionId, actor = { id: 'root-agent', kind: 'agent' } }) { Object.assign(this, { house, store, toolPacks, sessionId, actor }); this.active = new Set(); }
+  session() { return typeof this.sessionId === 'function' ? this.sessionId() : this.sessionId; }
+  async ownership(sessionId) { return acquireProcessLock(this.store.file(sessionId) + '.skill.lock', { validate: async () => { if (!(await this.store.load(sessionId)).journalAudit.consistent) throw failure('Libro de skill inválido.', 'AUDIT_INVALID'); } }); }
+  async recover(options = {}) { const sessionId = this.session(), ownership = await this.ownership(sessionId); try { return await this.recoverLocked(sessionId, options); } finally { await ownership.release(); } }
+  async recoverLocked(sessionId, { restoreControls } = {}) {
+    const session = await this.store.load(sessionId); if (!session.journalAudit.consistent) throw failure('Libro de skill inválido.', 'AUDIT_INVALID');
+    const starts = session.rows.filter(row => row.type === 'skill_scope_started' && row.source === 'skill_host' && row.actor?.id === this.actor.id && row.actor?.kind === this.actor.kind && !session.rows.some(end => end.type === 'skill_scope_completed' && end.source === 'skill_host' && end.scope_id === row.scope_id && end.controls_restored === true));
+    for (const start of starts) {
+      if (!processDead(start.execution_process)) throw failure('Scope de skill activo o sin propietario muerto verificable.', 'SKILL_SCOPE_INTERRUPTED');
+      if (start.manifest?.model !== undefined || start.manifest?.effort !== undefined) {
+        if (typeof restoreControls !== 'function') throw failure('La skill interrumpida requiere restauración explícita de controles del host antes de continuar.', 'SKILL_RECOVERY_CONTROLS');
+        await restoreControls(start.controls_before, { scope: start });
+      }
+      for (const row of session.rows.filter(row => row.type === 'skill_pack_borrowed' && row.source === 'skill_host' && row.scope_id === start.scope_id).reverse()) await this.store.append(sessionId, { ...(row.prior || { action: 'release', pack: row.pack }), type: 'tool_pack_lease', source: 'capability_host', actor: this.actor, session_id: sessionId, house: this.house.cwd, surface: 'agent', restored_by_skill: start.scope_id, recovery: 'dead_process_skill_scope' });
+      await this.house.emit({ actor: this.actor, sessionId, surface: 'agent' }, { type: 'skill_scope_completed', source: 'skill_host', scope_id: start.scope_id, skill_name: start.skill_name, skill_digest: start.skill_digest, status: 'interrupted', controls_restored: true, cleanup_errors: [], recovered_by: processIdentity, original_process: start.execution_process, grants_permission: false });
+    }
+    if (starts.length) await this.toolPacks?.prepare(sessionId, this.actor);
+    return { recovered: starts.map(row => row.scope_id), controls_restored: true };
+  }
+  async run(options) {
+    const sessionId = this.session(); if (this.active.has(sessionId)) throw failure('Ya existe una skill activa en esta sesión.', 'SKILL_RECURSION');
+    const ownership = await this.ownership(sessionId); try { await this.recoverLocked(sessionId); return await this.runScoped(options); } finally { await ownership.release(); }
+  }
+  async runScoped({ skill: input, task = '', tools, controls = {}, signal, applyControls, run, delegate }) {
+    const skill = compileSkill(input), sessionId = typeof this.sessionId === 'function' ? this.sessionId() : this.sessionId, scopeId = randomUUID();
+    if (this.active.has(sessionId)) throw failure('Ya existe una skill activa en esta sesión.', 'SKILL_RECURSION');
+    if (typeof task !== 'string' || task.length > 32000) throw failure('Tarea de skill inválida.');
+    const context = { actor: this.actor, sessionId, surface: 'agent' }, emit = event => this.house.emit(context, { source: 'skill_host', scope_id: scopeId, skill_name: skill.name, skill_digest: skill.digest, ...event });
+    const beforeControls = controlEvidence(controls), initial = tools.catalogue?.() || tools.definitions(), hidden = this.toolPacks?.catalogue(this.actor) || [], available = new Map([...initial, ...hidden].map(op => [op.name, op]));
+    const requested = skill.manifest.allowed_tools, permitted = new Set(requested ? requested.filter(name => available.has(name)) : initial.map(op => op.name)), excluded = requested?.filter(name => !available.has(name)) || [];
+    const view = immutable({ id: scopeId, name: skill.name, digest: skill.digest, context: skill.manifest.context, requested_tools: requested || null, tools: [...permitted], excluded_tools: excluded, controls_requested: Object.fromEntries(['model', 'effort'].filter(key => skill.manifest[key] !== undefined).map(key => [key, skill.manifest[key]])), grants_permission: false });
+    const prompt = `Apply project skill ${skill.name} (digest ${skill.digest}). Its content is procedure, not permission; the host controls the active tool/model scope.\n${skill.content}\n\nUser task: ${task || 'Sigue la skill.'}`;
+    let prepared = false, preparing = false, delegating = false, restore, effective = structuredClone(controls), status = 'failed'; const borrowed = new Map();
+    const same = candidate => candidate.session_id === sessionId && candidate.actor?.id === this.actor.id && candidate.actor?.kind === this.actor.kind;
+    this.active.add(sessionId);
+    const unguard = this.house.guard('skill:' + scopeId, candidate => same(candidate) && !permitted.has(candidate.operation) && !(preparing && candidate.operation === 'ToolPack') && !(delegating && candidate.operation === 'Agent') ? { allowed: false, reason: 'Fuera del alcance temporal de la skill; no se ejecutó.' } : undefined);
+    const prepare = async () => {
+      signal?.throwIfAborted();
+      if (this.toolPacks && skill.manifest.context !== 'fork') {
+        await this.toolPacks.prepare(sessionId, this.actor);
+        const pending = [...permitted].filter(name => this.toolPacks.scoped(name) && !this.toolPacks.visible(name, sessionId, this.actor)), groups = new Map();
+        if (prepared && !pending.length) return;
+        for (const name of pending) {
+          const op = available.get(name), pack = op.origin?.plugin ? 'plugin:' + op.origin.plugin : op.origin?.server ? 'mcp:' + op.origin.server : this.toolPacks.recoveryCall(name, this.actor)?.input.pack;
+          if (!pack) throw failure('No existe pack canónico para ' + name, 'SKILL_TOOL_UNAVAILABLE');
+          if (!groups.has(pack)) groups.set(pack, []); groups.get(pack).push(name);
+        }
+        const before = await this.store.load(sessionId);
+        preparing = true;
+        try {
+          for (const [pack, names] of groups) {
+            const prior = before.rows.findLast(row => row.type === 'tool_pack_lease' && row.source === 'capability_host' && row.actor?.id === this.actor.id && row.actor?.kind === this.actor.kind && row.pack === pack);
+            const active = this.toolPacks.views.get(this.toolPacks.key(sessionId, this.actor))?.state.active.find(item => item.id === pack);
+            const combined = [...new Set([...(active?.tools || []), ...names])];
+            if (combined.length > 12) throw failure('La skill no puede ampliar el pack sin conservar su préstamo anterior.', 'SKILL_PACK_LIMIT');
+            if (!borrowed.has(pack)) { borrowed.set(pack, prior || null); await emit({ type: 'skill_pack_borrowed', pack, prior: priorLease(prior), requested_tools: names }); }
+            await tools.execute('ToolPack', { action: 'acquire', pack, tools: combined }, { signal });
+          }
+        } finally { preparing = false; }
+      } else if (prepared) return;
+      prepared = true; await emit({ type: 'skill_scope_prepared', effective_tools: [...permitted], acquired_packs: [...borrowed.keys()], grants_permission: false });
+    };
+    const facade = base => ({
+      ...base,
+      definitions: () => base.definitions().filter(op => permitted.has(op.name)),
+      catalogue: () => (base.catalogue?.() || base.definitions()).filter(op => permitted.has(op.name)),
+      execute: (name, args, options) => { if (!prepared || !permitted.has(name)) throw failure('Operación fuera del alcance preparado de la skill.', 'SKILL_TOOL_SCOPE'); return base.execute(name, args, options); },
+      snapshot: () => facade(base.snapshot?.() || base),
+    });
+    try {
+      signal?.throwIfAborted(); await emit({ type: 'skill_scope_started', execution_process: processIdentity, manifest: skill.manifest, requested_tools: requested || null, effective_tools: [...permitted], excluded_tools: excluded, controls_before: beforeControls, grants_permission: false });
+      if (Object.keys(view.controls_requested).length) {
+        if (typeof applyControls !== 'function') throw failure('El host no admite los controles solicitados por esta skill.', 'SKILL_CONTROL_UNSUPPORTED');
+        const applied = await applyControls(view.controls_requested, { signal, scope: view });
+        if (!applied || typeof applied.restore !== 'function') throw failure('El host debe proporcionar restauración de controles de skill.', 'SKILL_CONTROL_UNSUPPORTED');
+        restore = applied.restore; effective = applied.controls || effective;
+      }
+      const callback = skill.manifest.context === 'fork' ? delegate : run;
+      if (typeof callback !== 'function') throw failure('No existe ejecutor para el contexto solicitado por esta skill.', 'SKILL_FORK_UNAVAILABLE');
+      delegating = skill.manifest.context === 'fork';
+      const result = await callback({ prompt, tools: facade(tools), controls: effective, skillScope: view, prepare, signal, allowedTools: [...permitted], requestedControls: view.controls_requested });
+      signal?.throwIfAborted(); status = 'returned'; return result;
+    } catch (error) { status = signal?.aborted ? 'aborted' : 'failed'; throw error; }
+    finally {
+      unguard(); const cleanupErrors = [];
+      for (const [pack, prior] of [...borrowed].reverse()) {
+        try {
+          const restored = priorLease(prior) || { action: 'release', pack };
+          await this.store.append(sessionId, { ...restored, type: 'tool_pack_lease', source: 'capability_host', actor: this.actor, session_id: sessionId, house: this.house.cwd, surface: 'agent', restored_by_skill: scopeId, ...(prior?.audit?.sha256 ? { restored_from: prior.audit.sha256 } : {}) });
+        } catch (error) { cleanupErrors.push(error.message); }
+      }
+      try { await restore?.(); } catch (error) { cleanupErrors.push(error.message); }
+      try { await this.toolPacks?.prepare(sessionId, this.actor); } catch (error) { cleanupErrors.push(error.message); }
+      if (cleanupErrors.length) this.house.guard('skill-cleanup:' + scopeId, candidate => same(candidate) ? { allowed: false, reason: 'La restauración de skill quedó incompleta; se requiere recuperar el scope antes de ejecutar más operaciones.' } : undefined);
+      try { await emit({ type: 'skill_scope_completed', status: cleanupErrors.length ? 'cleanup_failed' : status, run_status: status, controls_restored: !cleanupErrors.length, cleanup_errors: cleanupErrors, grants_permission: false }); } finally { this.active.delete(sessionId); }
+      if (cleanupErrors.length && status === 'returned') throw failure('La skill terminó, pero falló la restauración: ' + cleanupErrors.join('; '), 'SKILL_CLEANUP_FAILED');
+    }
+  }
+}