@entrorove/skill 0.1.41 → 0.1.47

package/ide-install.mjs

@@ -1,65 +1,233 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { ideDirectory, ideDigest, readIdeJson, writeIdeJson, ideError } from './ide-session.mjs';
 import { withStateLock } from './local-state-lock.mjs';
 
 const source = path.dirname(fileURLToPath(import.meta.url));
-const files = ['ide-hook.mjs', 'ide-session.mjs', 'break-glass.mjs', 'ide-results.mjs', 'ide-queue.mjs', 'ide-command.mjs', 'ide-code-mode.mjs', 'remote-transport.mjs', 'local-credential.mjs', 'local-state-lock.mjs'];
-const events = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'PostCompact', 'Stop'];
+const files = ['ide-hook.mjs', 'ide-session.mjs', 'break-glass.mjs', 'ide-results.mjs', 'ide-queue.mjs', 'ide-command.mjs', 'ide-code-mode.mjs', 'remote-transport.mjs', 'local-credential.mjs', 'local-state-lock.mjs', 'local-stage-boundary.mjs'];
 const quote = text => `'${text.replace(/'/gu, "'\\''")}'`;
-function definition(node, file) {
+
+// One shared host-agnostic hook binary; every host is described by its own
+// adapter (config location, event names, entry shape). Codex and Claude Code
+// are the verified adapters; adding a host that exposes the same callback
+// contract is data, not a new code path.
+export const ideAdapters = [
+  { id: 'codex', host: 'Codex', marker: 'CODEX_THREAD_ID', directory: '.codex', config: 'hooks.json',
+    record: 'installation.json', events: ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'PostCompact', 'Stop'],
+    entry: hook => ({ hooks: [hook] }) },
+  { id: 'claude', host: 'Claude Code', marker: 'CLAUDE_CODE_ENTRYPOINT', directory: '.claude', config: 'settings.json',
+    record: 'installation-claude.json', events: ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'PreCompact', 'Stop'],
+    entry: hook => ({ matcher: '*', hooks: [hook] }) },
+];
+export const verifiedIdeHosts = ideAdapters.map(adapter => adapter.host);
+
+// Universal entry: any host can be wired by declaring an adapter module
+// (ENTROROVE_IDE_ADAPTER=/absolute/module.mjs) whose default export describes
+// where its guard config lives and how its entries are shaped. Verified hosts
+// stay built in; a declared adapter is treated as verified for its own host.
+export async function resolveAdapters({ environment = process.env, extra = [] } = {}) {
+  const declared = String(environment.ENTROROVE_IDE_ADAPTER ?? '').split(',').map(value => value.trim()).filter(Boolean);
+  const resolved = [...ideAdapters, ...extra];
+  for (const pathname of declared) {
+    if (!path.isAbsolute(pathname)) throw ideError('ENTROROVE_IDE_ADAPTER', 'A declared adapter module must use an absolute path');
+    const module = await import(pathToFileURL(pathname).href).catch(cause => { throw ideError('ENTROROVE_IDE_ADAPTER', `Declared adapter could not be loaded: ${cause.message}`); });
+    const adapter = module.default ?? module.adapter;
+    if (!adapter || typeof adapter !== 'object' || typeof adapter.host !== 'string' || !/^[\p{L}\p{N} .+_-]{2,48}$/u.test(adapter.host)
+      || typeof adapter.directory !== 'string' || !/^\.[a-z0-9-]{1,32}$/u.test(adapter.directory)
+      || typeof adapter.config !== 'string' || adapter.config.includes('/') || adapter.config.includes('..')
+      || !Array.isArray(adapter.events) || !adapter.events.includes('PreToolUse')
+      || !['hooks', 'matcher-hooks'].includes(adapter.entry)) {
+      throw ideError('ENTROROVE_IDE_ADAPTER', 'A declared adapter must describe its host, config directory and entry shape');
+    }
+    const id = adapter.id ?? adapter.host.toLowerCase().replace(/[^a-z0-9]+/gu, '-');
+    resolved.push({ id, host: adapter.host, declared: true, marker: adapter.marker ?? null, directory: adapter.directory, config: adapter.config,
+      record: `installation-${id}.json`, events: adapter.events, minimal: adapter.entry === 'matcher-hooks',
+      entry: adapter.entry === 'matcher-hooks' ? hook => ({ matcher: '*', hooks: [hook] }) : hook => ({ hooks: [hook] }) });
+  }
+  return resolved;
+}
+
+function definition(adapter, node, file) {
   const command = `${quote(node)} ${quote(file)}`;
-  return { hooks: Object.fromEntries(events.map(event => [event, [{ hooks: [{ type: 'command', command,
+  const hooks = Object.fromEntries(adapter.events.map(event => [event, [adapter.entry({ type: 'command', command,
     timeout: 10, statusMessage: 'Entrorove · 检查任务',
-    ...(['PostCompact','Stop'].includes(event) ? {} : {additionalContextLimit:1500}) }] }]])) };
+    ...(['PostCompact', 'PreCompact', 'Stop'].includes(event) ? {} : { additionalContextLimit: 1500 }) })]]));
+  return { hooks };
 }
-async function prepareConfigDirectory(home) {
-  const directory = path.join(home, '.codex');
+async function prepareConfigDirectory(home, adapter) {
+  const directory = path.join(home, adapter.directory);
   await fs.mkdir(directory, { recursive: true, mode: 0o700 });
   const stat = await fs.lstat(directory);
-  if (!stat.isDirectory() || stat.isSymbolicLink() || process.platform !== 'win32' && stat.uid !== process.getuid()) throw ideError('ENTROROVE_IDE_CONFIG', 'Codex config must be an owned real directory');
+  if (!stat.isDirectory() || stat.isSymbolicLink() || process.platform !== 'win32' && stat.uid !== process.getuid()) {
+    throw ideError('ENTROROVE_IDE_CONFIG', `${adapter.host} config must be an owned real directory`);
+  }
   return directory;
 }
-async function readHostConfig(file) {
-  const raw = await fs.readFile(file, 'utf8').catch(cause => { if (cause.code === 'ENOENT') return null; throw cause; });
-  if (raw === null) return null;
-  try { return JSON.parse(raw); } catch { throw ideError('ENTROROVE_IDE_CONFIG', 'Existing Codex hooks config is not valid JSON; it was preserved'); }
-}
-function mergeHooks(existing, previous, current) {
+function mergeHooks(existing, previous, current, adapter) {
   if (existing && (typeof existing !== 'object' || Array.isArray(existing) || existing.hooks && typeof existing.hooks !== 'object')) throw ideError('ENTROROVE_IDE_CONFIG', 'Existing hooks config is invalid; it was preserved');
   const next = { ...existing, hooks: { ...existing?.hooks } };
-  for (const event of events) {
+  for (const event of new Set([...Object.keys(previous?.hooks ?? {}), ...adapter.events])) {
     const old = previous?.hooks?.[event]?.[0], entries = next.hooks[event] ?? [];
     if (!Array.isArray(entries)) throw ideError('ENTROROVE_IDE_CONFIG', 'Existing hook list is invalid; it was preserved');
     const ours = entries.filter(entry => old && JSON.stringify(entry) === JSON.stringify(old));
     if (previous && !ours.length && entries.some(entry => entry.hooks?.some(hook => hook.command === old?.hooks?.[0]?.command))) throw ideError('ENTROROVE_IDE_CONFIG_EDITED', 'A hand-edited Entrorove hook was preserved; review it before updating');
-    next.hooks[event] = [...entries.filter(entry => !ours.includes(entry)), current.hooks[event][0]];
+    const retained = entries.filter(entry => !ours.includes(entry));
+    if (current.hooks[event]) next.hooks[event] = [...retained, current.hooks[event][0]];
+    else if (retained.length) next.hooks[event] = retained;
+    else delete next.hooks[event];
   }
   return next;
 }
-export async function installIdeHooks({ home, version, packageDirectory = source, node = process.execPath }) {
-  const directory = await ideDirectory(home, true), configDirectory = await prepareConfigDirectory(home);
-  const hooksPath = path.join(configDirectory, 'hooks.json'), recordPath = path.join(directory, 'installation.json');
-  return withStateLock(hooksPath, async () => {
-    const existing = await readHostConfig(hooksPath), previous = await readIdeJson(recordPath);
-    const current = definition(node, path.join(directory, 'ide-hook.mjs'));
-    const config = mergeHooks(existing, previous?.definition, current);
-    const contents = await Promise.all(files.map(async name => [name, await fs.readFile(path.join(source, name))]));
-    for (const [name, bytes] of contents) {
-      const target = path.join(directory, name), stat = await fs.lstat(target).catch(cause => { if (cause.code !== 'ENOENT') throw cause; return null; });
-      if (stat && (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1)) throw ideError('ENTROROVE_IDE_STORE', 'Managed hook target must be a private regular file');
-      if (stat && previous?.files?.[name] && ideDigest((await fs.readFile(target)).toString('utf8')) !== previous.files[name]) throw ideError('ENTROROVE_IDE_HOOK_EDITED', 'Hand-edited hook code was preserved');
-      await fs.writeFile(target, bytes, { mode: 0o600 });
-    }
-    const cli = path.join(packageDirectory, 'cli.mjs');
-    await writeIdeJson(path.join(directory, 'runtime.json'), { schemaVersion: 'entrorove.ide-runtime/1.0', version, node, cli,
-      apiOrigin: 'https://entrorove.com',
-      cliDigest: ideDigest((await fs.readFile(cli)).toString('utf8')) });
-    if (JSON.stringify(existing) !== JSON.stringify(config)) await writeIdeJson(hooksPath, config);
-    await writeIdeJson(recordPath, { schemaVersion: 'entrorove.ide-installation/1.0', version, definition: current,
-      files: Object.fromEntries(contents.map(([name, bytes]) => [name, ideDigest(bytes.toString('utf8'))])) });
-    return { host: 'Codex', configured: true, enforcement: 'review-required', hooksPath,
-      message: '已安装持续执行检查。请在 Codex /hooks 审查并信任 Entrorove；实际收到 PreToolUse 回调后才算拦截已生效。' };
+// A host's own config is not ours to police: read it permissively (its file
+// mode belongs to that host), while our own state files stay strictly private.
+async function readConfigJson(file, previous) {
+  const raw = await fs.readFile(file, 'utf8').catch(cause => { if (cause.code === 'ENOENT') return null; throw cause; });
+  if (raw === null) return { value: null, recoveredEmpty: false };
+  if (!raw.trim() && previous?.schemaVersion === 'entrorove.ide-installation/1.0' && previous.definition?.hooks?.PreToolUse) {
+    return { value: previous.definition, recoveredEmpty: true };
+  }
+  try { return { value: JSON.parse(raw), recoveredEmpty: false }; }
+  catch { throw ideError('ENTROROVE_IDE_CONFIG', 'Existing host config is not valid JSON; it was preserved'); }
+}
+async function directoryExists(directory) {
+  const stat = await fs.lstat(directory).catch(cause => { if (cause.code === 'ENOENT') return null; throw cause; });
+  return Boolean(stat?.isDirectory());
+}
+export async function activeIdeAdapters({ home, environment = process.env } = {}) {
+  const directory = await ideDirectory(home).catch(cause => {
+    if (cause.code === 'ENOENT') return null;
+    throw cause;
   });
+  if (!directory) return [];
+  const active = [];
+  for (const adapter of await resolveAdapters({ environment })) {
+    const record = await readIdeJson(path.join(directory, adapter.record));
+    if (record?.schemaVersion !== 'entrorove.ide-installation/1.0'
+      || record.host && record.host !== adapter.host) continue;
+    const configPath = path.join(home, adapter.directory, adapter.config);
+    const stat = await fs.lstat(configPath).catch(cause => {
+      if (cause.code === 'ENOENT') return null;
+      throw cause;
+    });
+    if (!stat?.isFile() || stat.isSymbolicLink()) continue;
+    let config;
+    try { config = JSON.parse(await fs.readFile(configPath, 'utf8')); } catch { continue; }
+    const entry = record.definition?.hooks?.PreToolUse?.[0];
+    const entries = config?.hooks?.PreToolUse;
+    if (entry && Array.isArray(entries)
+      && entries.some(value => JSON.stringify(value) === JSON.stringify(entry))) active.push(adapter);
+  }
+  return active;
+}
+export async function installIdeHooks({ home, version, packageDirectory = source, node = process.execPath,
+  environment = process.env, adapters = null }) {
+  const directory = await ideDirectory(home, true);
+  // Hand-edited protection must consider every host's record, not just the
+  // primary one: a machine configured for another host still has our files.
+  const records = (await Promise.all([...new Set(['installation.json', ...ideAdapters.map(adapter => adapter.record)])]
+    .map(name => readIdeJson(path.join(directory, name))))).filter(Boolean);
+  const record = records[0] ?? null;
+  void record;
+  const previousDigest = name => records.map(item => item.files?.[name]).find(value => typeof value === 'string') ?? null;
+  const contents = await Promise.all(files.map(async name => [name, await fs.readFile(path.join(source, name))]));
+  for (const [name, bytes] of contents) {
+    const target = path.join(directory, name), stat = await fs.lstat(target).catch(cause => { if (cause.code !== 'ENOENT') throw cause; return null; });
+    if (stat && (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1)) throw ideError('ENTROROVE_IDE_STORE', 'Managed hook target must be a private regular file');
+    const expectedDigest = previousDigest(name);
+    if (stat && expectedDigest && ideDigest((await fs.readFile(target)).toString('utf8')) !== expectedDigest) throw ideError('ENTROROVE_IDE_HOOK_EDITED', 'Hand-edited hook code was preserved');
+    await fs.writeFile(target, bytes, { mode: 0o600 });
+  }
+  const cli = path.join(packageDirectory, 'cli.mjs');
+  await writeIdeJson(path.join(directory, 'runtime.json'), { schemaVersion: 'entrorove.ide-runtime/1.0', version, node, cli,
+    apiOrigin: 'https://entrorove.com', cliDigest: ideDigest((await fs.readFile(cli)).toString('utf8')) });
+  const installedFiles = Object.fromEntries(contents.map(([name, bytes]) => [name, ideDigest(bytes.toString('utf8'))]));
+  const targets = [];
+  for (const adapter of adapters ?? await resolveAdapters({ environment })) {
+    if (adapter.id === 'codex' || adapter.declared || environment[adapter.marker] !== undefined || await directoryExists(path.join(home, adapter.directory))) targets.push(adapter);
+  }
+  const installed = [];
+  for (const adapter of targets) {
+    const configDirectory = await prepareConfigDirectory(home, adapter);
+    const configPath = path.join(configDirectory, adapter.config), recordPath = path.join(directory, adapter.record);
+    installed.push(await withStateLock(configPath, async () => {
+      const previous = await readIdeJson(recordPath);
+      const { value: existing, recoveredEmpty } = await readConfigJson(configPath, previous);
+      const current = definition(adapter, node, path.join(directory, 'ide-hook.mjs'));
+      const config = mergeHooks(existing, previous?.definition, current, adapter);
+      if (recoveredEmpty || JSON.stringify(existing) !== JSON.stringify(config)) await writeIdeJson(configPath, config);
+      await writeIdeJson(recordPath, { schemaVersion: 'entrorove.ide-installation/1.0', version, host: adapter.host,
+        definition: current, files: installedFiles });
+      return { host: adapter.host, id: adapter.id, configured: true, enforcement: 'configured', hooksPath: configPath };
+    }));
+  }
+  return { host: installed[0]?.host ?? ideAdapters[0].host, hosts: installed.map(item => item.host), configured: true,
+    enforcement: 'configured', hooksPath: installed[0]?.hooksPath,
+    message: `已写入 Entrorove Hook 配置（${installed.map(item => item.host).join('、')}）；需由 IDE 信任并收到真实回调后才能确认生效。` };
+}
+
+export async function uninstallIdeHooks({ home }) {
+  const directory = await ideDirectory(home).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+  if (!directory) return { removed: [], preserved: [] };
+  const removed = [], preserved = [], records = [];
+  const hookPath = path.join(directory, 'ide-hook.mjs');
+  for (const adapter of ideAdapters) {
+    const recordPath = path.join(directory, adapter.record), record = await readIdeJson(recordPath);
+    if (record && (record.schemaVersion !== 'entrorove.ide-installation/1.0' || record.host !== adapter.host)) {
+      throw ideError('ENTROROVE_IDE_STORE', `${adapter.host} installation record is invalid; it was preserved`);
+    }
+    if (record) records.push(record);
+    const configPath = path.join(home, adapter.directory, adapter.config);
+    await withStateLock(configPath, async () => {
+      const { value: existing } = await readConfigJson(configPath, record);
+      if (!existing) { if (record) await fs.rm(recordPath); return; }
+      if (!existing.hooks || typeof existing.hooks !== 'object' || Array.isArray(existing.hooks)) {
+        throw ideError('ENTROROVE_IDE_CONFIG', `${adapter.host} hook config is invalid; it was preserved`);
+      }
+      const commands = new Set(Object.values(record?.definition?.hooks ?? {}).flatMap(entries =>
+        entries.flatMap(entry => entry.hooks?.map(hook => hook.command) ?? [])).filter(command => typeof command === 'string'));
+      const hooks = {};
+      for (const [event, entries] of Object.entries(existing.hooks)) {
+        if (!Array.isArray(entries)) throw ideError('ENTROROVE_IDE_CONFIG', `${adapter.host} hook list is invalid; it was preserved`);
+        hooks[event] = entries.flatMap(entry => {
+          if (!Array.isArray(entry.hooks)) return [entry];
+          const retained = entry.hooks.filter(hook => !commands.has(hook.command)
+            && !hook.command?.endsWith(` ${quote(hookPath)}`));
+          return retained.length ? [{ ...entry, hooks: retained }] : [];
+        });
+        if (!hooks[event].length) delete hooks[event];
+      }
+      const next = { ...existing, hooks };
+      if (JSON.stringify(existing) !== JSON.stringify(next)) {
+        if (!Object.keys(hooks).length && Object.keys(next).length === 1) await fs.rm(configPath);
+        else await writeIdeJson(configPath, next);
+        removed.push(configPath);
+      }
+      if (record) await fs.rm(recordPath);
+    });
+  }
+  const digests = new Map();
+  for (const record of records) for (const [name, digest] of Object.entries(record.files ?? {})) {
+    if (!digests.has(name)) digests.set(name, new Set());
+    digests.get(name).add(digest);
+  }
+  for (const [name, known] of digests) {
+    if (!files.includes(name)) continue;
+    const target = path.join(directory, name), stat = await fs.lstat(target).catch(error => {
+      if (error.code === 'ENOENT') return null; throw error;
+    });
+    if (!stat) continue;
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1
+      || !known.has(ideDigest((await fs.readFile(target)).toString('utf8')))) { preserved.push(target); continue; }
+    await fs.rm(target); removed.push(target);
+  }
+  for (const name of files.filter(item => !digests.has(item))) {
+    const target = path.join(directory, name);
+    if (await fs.lstat(target).catch(error => { if (error.code === 'ENOENT') return null; throw error; })) preserved.push(target);
+  }
+  const runtimePath = path.join(directory, 'runtime.json'), runtime = await readIdeJson(runtimePath);
+  if (runtime?.schemaVersion === 'entrorove.ide-runtime/1.0' && runtime.cli?.endsWith('/cli.mjs')) {
+    await fs.rm(runtimePath); removed.push(runtimePath);
+  }
+  return { removed, preserved };
 }

package/ide-session.mjs

@@ -1,11 +1,12 @@
 import { constants, promises as fs } from 'node:fs';
+import { pathToFileURL } from 'node:url';
 import { createHash, randomUUID } from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
 import { credentialDirectory, readCredential } from './local-credential.mjs';
 import { withStateLock } from './local-state-lock.mjs';
 import { requestTransport, parseTransportResponse } from './remote-transport.mjs';
-import { breakGlassPath, breakGlassSchema, writeBreakGlass as writeOfflineBreakGlass } from './break-glass.mjs';
+import { breakGlassPath, breakGlassSchema, breakGlassSessionDigest, writeBreakGlass as writeOfflineBreakGlass } from './break-glass.mjs';
 
 export const ideDigest = value => createHash('sha256').update(typeof value === 'string' ? value : JSON.stringify(value)).digest('hex');
 export const ideError = (code, message) => Object.assign(new Error(message), { code });
@@ -34,10 +35,12 @@ export async function writeIdeJson(file, value) {
   try { await fs.rename(stage, file); } finally { await fs.rm(stage, { force: true }); }
 }
 export const writeBreakGlass = writeOfflineBreakGlass;
-export async function readBreakGlass(home = os.homedir()) {
-  await ideDirectory(home, true);
+export async function readBreakGlass(home = os.homedir(), sessionId) {
+  if (!sessionId) return null;
+  const directory = await ideDirectory(home, true);
   const value = await readIdeJson(breakGlassPath(home));
   if (!value || value.schemaVersion !== breakGlassSchema || value.mode !== 'management-only'
+    || value.sessionDigest !== breakGlassSessionDigest(sessionId)
     || typeof value.expiresAt !== 'string' || !Number.isFinite(Date.parse(value.expiresAt))
     || Date.parse(value.expiresAt) <= Date.now()) return null;
   return value;
@@ -47,8 +50,10 @@ export async function ideSession(event, action, home = os.homedir()) {
   const directory = await ideDirectory(home, true), file = path.join(directory, `session-${ideDigest(event.session_id)}.json`);
   return withStateLock(file, async () => {
     const root = await fs.realpath(event.cwd), prior = await readIdeJson(file);
-    if (prior && (prior.schemaVersion !== 'entrorove.ide-session/1.0' || prior.sessionId !== event.session_id || prior.repositoryRoot !== root)) throw ideError('ENTROROVE_IDE_IDENTITY', 'A session cannot replace its original physical repository');
-    const state = prior ?? { schemaVersion: 'entrorove.ide-session/1.0', sessionId: event.session_id, repositoryRoot: root, active: false, phase: 'entry', seen: [], blockStreak: 0 };
+    if (prior && (prior.schemaVersion !== 'entrorove.ide-session/1.0' || prior.sessionId !== event.session_id
+      || prior.repositoryRoot !== root && prior.active)) throw ideError('ENTROROVE_IDE_IDENTITY', 'An active task cannot replace its original physical repository');
+    const state = prior?.repositoryRoot === root ? prior
+      : { schemaVersion: 'entrorove.ide-session/1.0', sessionId: event.session_id, repositoryRoot: root, active: false, phase: 'entry', seen: [], blockStreak: 0 };
     state.stateFile = file;
     const result = await action(state);
     const { stateFile, ...persisted } = state;
@@ -79,20 +84,84 @@ export async function ideRuntime(home = os.homedir()) {
   return runtime;
 }
 export function ideContext(state) {
-  return `Entrorove 已强制接管本任务。${state.taskNumber ? `云端任务 ${state.taskNumber}。` : '尚未获得云端任务编号，不得声称已进入云端。'}${state.flowId ? `继续原 flowId=${state.flowId}，` : ''}${state.requestId ? `原 requestId=${state.requestId}。` : ''}当前阶段 ${state.phase}。必须读 SKILL.md 并执行返回的 nextStep；禁止在失败后替换执行器。源文件、数据及终端写入必须走原任务的受控入口。`;
+  const delivered = state.phase === 'delivered' && Number.isSafeInteger(state.deliveredStage)
+    ? `阶段 ${state.deliveredStage} 已按边界独立交付（终态，不等于失败或阻塞）；续跑从下一个边界继续，不重新执行已交付阶段。` : '';
+  return `Entrorove 已强制接管本任务。${state.taskNumber ? `云端任务 ${state.taskNumber}。` : '尚未获得云端任务编号，不得声称已进入云端。'}${state.flowId ? `继续原 flowId=${state.flowId}，` : ''}${state.requestId ? `原 requestId=${state.requestId}。` : ''}当前阶段 ${state.phase}。${delivered}必须读 SKILL.md 并执行返回的 nextStep；禁止在失败后替换执行器。源文件、数据及终端写入必须走原任务的受控入口。`;
+}
+// Verified hosts only: the guard is universal in shape (host label + session
+// id), and each host proves itself through its own adapter callback.
+export const verifiedIdeGuards = { 'Codex': 'CODEX_THREAD_ID', 'Claude Code': 'CLAUDE_SESSION_ID' };
+export function ideGuardBinding(environment = process.env) {
+  const host = environment.ENTROROVE_IDE ?? (environment.CODEX_THREAD_ID ? 'Codex' : environment.CLAUDE_CODE_ENTRYPOINT ? 'Claude Code'
+    : environment.CURSOR_TRACE_ID ? 'Cursor' : null);
+  const sessionId = environment.ENTROROVE_SESSION ?? (host ? environment[verifiedIdeGuards[host] ?? ''] : undefined) ?? environment.CODEX_THREAD_ID;
+  return { host, sessionId: typeof sessionId === 'string' ? sessionId : null };
+}
+async function declaredHost(environment) {
+  const declared = String(environment.ENTROROVE_IDE_ADAPTER ?? '').split(',').map(value => value.trim()).filter(Boolean);
+  for (const pathname of declared) {
+    try {
+      const module = await import(pathToFileURL(pathname).href);
+      const host = (module.default ?? module.adapter)?.host;
+      if (typeof host === 'string') return host;
+    } catch { return null; }
+  }
+  return null;
 }
 export async function assertIdeExecution(args, input, { home = os.homedir(), environment = process.env } = {}) {
-  const host = environment.ENTROROVE_IDE ?? (environment.CODEX_THREAD_ID ? 'Codex' : environment.CURSOR_TRACE_ID ? 'Cursor' : environment.CLAUDE_CODE_ENTRYPOINT ? 'Claude Code' : null);
+  const { host, sessionId } = ideGuardBinding(environment);
   if (!host || host === 'Entrorove CLI') return;
-  if (host !== 'Codex' || !environment.CODEX_THREAD_ID) throw ideError('ENTROROVE_IDE_GUARD_UNSUPPORTED', 'This IDE has no verified tool guard adapter. Execution is blocked; never continue with another executor.');
-  const directory = await ideDirectory(home), state = await readIdeJson(path.join(directory, `session-${ideDigest(environment.CODEX_THREAD_ID)}.json`));
+  const lifecycle = args[0] === 'local' ? args[1] : args[0] === 'invoke' ? input?.operation : null;
+  if (['flow-cancel', 'flow-abandon'].includes(lifecycle) && await readBreakGlass(home, sessionId)) {
+    const flowId = args[0] === 'invoke' ? input?.input?.flowId : input?.flowId;
+    const state = await readIdeJson(path.join(await ideDirectory(home), `session-${ideDigest(sessionId)}.json`));
+    if (state?.flowId && state.flowId !== flowId) throw ideError('ENTROROVE_IDE_RECOVERY_SCOPE', 'Recovery must settle the flow bound to this IDE session');
+    if (args[0] === 'local') {
+      const root = input?.repositoryRoot ?? args[2];
+      if (state?.repositoryRoot && root && await fs.realpath(root) !== state.repositoryRoot) {
+        throw ideError('ENTROROVE_IDE_RECOVERY_SCOPE', 'Recovery cannot switch the IDE session repository');
+      }
+      if (input?.home && await fs.realpath(input.home) !== await fs.realpath(home)) {
+        throw ideError('ENTROROVE_IDE_RECOVERY_SCOPE', 'Recovery cannot switch the IDE session home');
+      }
+    }
+    return;
+  }
+  const declared = verifiedIdeGuards[host] ? null : await declaredHost(environment);
+  if (!verifiedIdeGuards[host] && declared !== host || !sessionId) {
+    throw ideError('ENTROROVE_IDE_GUARD_UNSUPPORTED', `${host} has no verified tool guard adapter. Execution is blocked; never continue with another executor.`);
+  }
+  const directory = await ideDirectory(home), state = await readIdeJson(path.join(directory, `session-${ideDigest(sessionId)}.json`));
   const expected = ideDigest({ args, input });
   const approved = [state?.pendingCall, ...Object.values(state?.readCalls ?? {})].find(call => call?.inputDigest === expected);
-  if (!state?.active || !approved || state.sessionId !== environment.CODEX_THREAD_ID
+  if (!state?.active || !approved || state.sessionId !== sessionId
     || Date.now() - Date.parse(state.observedAt) > 120_000) {
-    throw ideError('ENTROROVE_IDE_GUARD_REQUIRED', 'Codex tool guard has not approved this exact call. Run install, review Entrorove in /hooks, and resume the original task.');
+    throw ideError('ENTROROVE_IDE_GUARD_REQUIRED', `${host} tool guard has not approved this exact call. Run install, accept the host hook, and resume the original task.`);
   }
   await bindIdeAccount(state, home);
   approvedResultContext = { home, sessionId: state.sessionId, repositoryRoot: state.repositoryRoot,
     accountDigest: state.accountDigest, toolUseId: approved.toolUseId, inputDigest: expected };
 }
+
+export async function settleBreakGlassSession(args, input, result, { home = os.homedir(), environment = process.env } = {}) {
+  const operation = args[0] === 'local' ? args[1] : args[0] === 'invoke' ? input?.operation : null;
+  if (!['flow-cancel', 'flow-abandon'].includes(operation)) return false;
+  const value = result?.output ?? result;
+  const flowId = args[0] === 'invoke' ? input?.input?.flowId : input?.flowId;
+  if (value?.operation !== operation || value.flowId !== flowId || !['succeeded', 'reported'].includes(value.status)
+    || operation === 'flow-abandon' && value.unbound !== true) return false;
+  const { host, sessionId } = ideGuardBinding(environment);
+  if (!host || host === 'Entrorove CLI' || !await readBreakGlass(home, sessionId)) return false;
+  const file = path.join(await ideDirectory(home), `session-${ideDigest(sessionId)}.json`);
+  const current = await readIdeJson(file);
+  if (!current) return false;
+  return ideSession({ session_id: sessionId, cwd: current.repositoryRoot }, state => {
+    if (state.flowId !== flowId) throw ideError('ENTROROVE_IDE_RECOVERY_SCOPE', 'Recovered flow no longer matches the IDE session');
+    if (operation === 'flow-abandon') {
+      for (const key of ['flowId', 'taskId', 'taskNumber', 'requestId', 'remoteRequestId', 'nextStep', 'pendingCall', 'readCalls']) delete state[key];
+      state.feedbackAcknowledged = false;
+      if (state.phase !== 'user-exited') state.phase = 'entry';
+    } else state.phase = 'ended';
+    return true;
+  }, home);
+}

package/install-cleanup.mjs

@@ -0,0 +1,59 @@
+import { randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+function gitRoot(directory) {
+  try { return execFileSync('git', ['-C', directory, 'rev-parse', '--show-toplevel'],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); }
+  catch { return null; }
+}
+
+function tracked(root, directory) {
+  if (!root) return false;
+  const relative = path.relative(root, directory);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return false;
+  return execFileSync('git', ['-C', root, 'ls-files', '--cached', '--', relative],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim().length > 0;
+}
+
+async function removeDuplicate(directory, target, root, isManaged) {
+  const stat = await fs.lstat(directory).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+  if (!stat) return 'absent';
+  if (tracked(root, directory)) return 'git-tracked';
+  if (stat.isSymbolicLink()) {
+    if (await fs.realpath(directory).catch(() => null) !== target) return 'unmanaged';
+    await fs.unlink(directory);
+    return 'removed';
+  }
+  if (!await isManaged(directory)) return 'unmanaged-or-edited';
+  const quarantine = `${directory}.entrorove-cleanup-${randomUUID()}`;
+  await fs.rename(directory, quarantine);
+  try {
+    if (!await isManaged(quarantine)) throw new Error('Managed duplicate changed during cleanup');
+    await fs.rm(quarantine, { recursive: true });
+  } catch (error) {
+    await fs.rename(quarantine, directory);
+    throw error;
+  }
+  return 'removed';
+}
+
+export async function cleanManagedDuplicates({ target, cwd, home, isManaged, includeProject = true }) {
+  const root = includeProject ? gitRoot(cwd) : null, homeRoot = gitRoot(home);
+  const candidates = [
+    ...(root ? ['.codex/skills/entrorove', '.agents/skills/entrorove', '.claude/skills/entrorove']
+      .map(relative => ({ directory: path.join(root, relative), label: relative, root })) : []),
+    ...['.agents/skills/entrorove', '.claude/skills/entrorove']
+      .map(relative => ({ directory: path.join(home, relative), label: `~/${relative}`, root: homeRoot })),
+  ];
+  const removed = [], preserved = [], seen = new Set([target]);
+  for (const candidate of candidates) {
+    if (seen.has(candidate.directory)) continue;
+    seen.add(candidate.directory);
+    const result = await removeDuplicate(candidate.directory, target, candidate.root, isManaged);
+    if (result === 'removed') removed.push(candidate.label);
+    else if (result !== 'absent') preserved.push({ path: candidate.label, reason: result });
+  }
+  return { removed, preserved };
+}

package/local-budget.mjs

@@ -38,7 +38,8 @@ export function budgetView(state, now = Date.now()) {
     ? Math.floor((elapsedMs - state.maxDurationMs) / auto.policy.intervalMs) + 1 : 0;
   const autoRenewEligible = Boolean(intervals && !state.closedReason && now < Date.parse(state.grant.expiresAt)
     && auto.renewalsUsed + intervals <= auto.policy.maxRenewals);
-  return { ...state, elapsedMs, remainingFiles: state.enforced ? Math.max(0, state.maxFiles - state.files.length) : null,
+  return { ...state, elapsedMs, consumedRatio: state.enforced ? elapsedMs / state.maxDurationMs : null,
+    remainingFiles: state.enforced ? Math.max(0, state.maxFiles - state.files.length) : null,
     remainingTokenEstimate: state.enforced ? Math.max(0, state.maxTokenEstimate - state.tokenEstimate) : null,
     remainingDurationMs: state.enforced ? Math.max(0, state.maxDurationMs - elapsedMs) : null,
     enforcement: state.enforced ? 'cloud-sandbox' : 'continuous', autoRenewEligible,

package/local-chain-broker.mjs

@@ -4,11 +4,6 @@ import { inspectLocalChainResult } from './local-chain-plan.mjs';
 
 const STAGES = Object.freeze({ 'workflow-gate': 'aimlock', 'workflow-contract': 'aimlock',
   'workflow-plan': 'blueprint', 'workflow-dispatch': 'swarm', 'workflow-verdict': 'validator' });
-function nativeSchema(runtime, operation) {
-  const schemas = runtime.operationSchemas;
-  const selected = Array.isArray(schemas) ? schemas.find(value => value.operation === operation) : schemas?.[operation];
-  return selected?.inputSchema ?? selected?.input ?? selected;
-}
 export async function captureChainCloud(plan, client) {
   if (!plan.skills.length) return null;
   const output = await client.invoke('capabilities', {}), capabilities = output.capabilities;
@@ -37,10 +32,16 @@ export function checkChainSkillDispatch(original, state, resumed, input) {
   }
   const slug = STAGES[original.operation] ?? resumed.route?.slug;
   if (slug !== original.skillId) fail('ENTROROVE_CHAIN_SKILL_BINDING', 'declared skill differs from the original native workflow stage');
-  const runtime = state.cloud.runtimes.find(value => value.slug === original.skillId);
-  const schema = state.cloud.workflowOperations?.operationSchemas?.[original.operation] ?? nativeSchema(runtime, original.operation);
+  // `continue` is a workflow operation. A native skill operation with the
+  // same name can have a different request body (for example, the workflow
+  // reads its persisted interaction while the native runtime requires one).
+  const schema = state.cloud.workflowOperations?.operationSchemas?.[original.operation];
   if (schema) {
-    const validate = new Ajv({ strict: true, strictRequired: false, allErrors: true }).compile(schema);
+    // Pinned native schemas include legacy `optional` annotations and nested
+    // object branches without an explicit `type`. Keep validation of the
+    // actual JSON Schema constraints while accepting those published forms.
+    const validate = new Ajv({ strict: true, strictRequired: false, strictTypes: false, allErrors: true })
+      .addKeyword({ keyword: 'optional', schemaType: 'boolean', valid: true }).compile(schema);
     if (!validate(input)) fail('ENTROROVE_CHAIN_SKILL_INPUT', 'bound input violates its fixed original operation schema');
   }
   // Native operations without public nested schemas remain server-validated on

package/local-cli.mjs

@@ -25,7 +25,7 @@ import { ARCHGUARD_LOCAL_OPERATIONS } from './local-archguard-operations.mjs';
 import { LOCAL_BUDGET_HANDOFF_OPERATIONS } from './local-budget-handoff.mjs';
 import { LOCAL_CHAIN_OPERATIONS } from './local-chain-operations.mjs';
 import { DISCIPLINE_LOCAL_OPERATIONS } from './local-discipline-operations.mjs';
-import { assertIdeExecution } from './ide-session.mjs';
+import { assertIdeExecution, settleBreakGlassSession } from './ide-session.mjs';
 import { runManagedWorkflowLocalStep } from './workflow-local-client.mjs';
 import { localErrorEnvelope } from './local-error.mjs';
 
@@ -101,6 +101,7 @@ export async function runLocal(args = [], dependencies) {
     const validated = await checkedLocalInput(operation, input);
     const supplied = operation === 'workflow-run-step' || Object.hasOwn(LOCAL_CHAIN_OPERATIONS, operation) ? dependencies : undefined;
     const output = await withLocalInvocation(operation, validated, () => withBudgetReadContext(validated, () => handler(validated, supplied)));
+    await settleBreakGlassSession(['local', ...args], validated, output);
     process.stdout.write(`${JSON.stringify(output)}\n`);
     if (['pending', 'blocked', 'failed', 'incomplete'].includes(output?.status)) process.exitCode = 2;
   } catch (cause) {
@@ -115,5 +116,7 @@ export async function runLocalInput(operation, input, dependencies) {
   if (!handler) throw new Error(`Unsupported local operation: ${operation}`);
   const validated = await checkedLocalInput(operation, input);
   const supplied = operation === 'workflow-run-step' || Object.hasOwn(LOCAL_CHAIN_OPERATIONS, operation) ? dependencies : undefined;
-  return withLocalInvocation(operation, validated, () => withBudgetReadContext(validated, () => handler(validated, supplied)));
+  const output = await withLocalInvocation(operation, validated, () => withBudgetReadContext(validated, () => handler(validated, supplied)));
+  await settleBreakGlassSession(['local', operation], validated, output);
+  return output;
 }