evolcore 0.0.11 → 0.0.12

package/dist/core/message/response-engine.js

@@ -11,7 +11,7 @@ import { StreamIdleMonitor } from './stream-idle-monitor.js';
 import { logger } from '../../utils/logger.js';
 import { isHostChinese } from '../../utils/locale.js';
 import { getErrorMessage, classifyError, ErrorType, ERROR_PREFIX, isInfraError, isAbortTerminalReason, prefixErrorType, isRetryableError, isContextTooLongText } from '../../utils/error-utils.js';
-import { isEvolcoreSendCommandForSession } from '../permission/ec-command-parser.js';
+import { isExactEvolcoreSendCommandForSession } from '../permission/ec-command-parser.js';
 import { summarizeToolInput } from '../../utils/tool-summary.js';
 import { getPackageRoot, resolveRoot, resolvePaths } from '../../paths.js';
 import { renderKitSections } from '../../eck/kit-renderer.js';
@@ -33,7 +33,6 @@ import { eligibleFallbackModels } from '../model/model-fallback.js';
 import { RetryScheduler } from './retry-scheduler.js';
 import { constrainRuntimePermissionMode, resolveRuntimeStringField } from '../role/runtime-policy.js';
 import { resolveEffective, resolveEffectiveFieldWithSource } from '../../config/config-manager.js';
-import { dispatchToMentionMode } from '../../config/mention-mode.js';
 import { authorizationConfigRevision, checkRoleAccess, getFirstStaticAgentOwner, listStaticAgentAdmins, listStaticAgentOwners, resolvePeerRoleDetail, roleToSessionIdentity, } from '../../config/peer-role-resolver.js';
 import { insertUsageEvent, insertContextBreakdown, insertModelCalls } from '../../stats/writer.js';
 import { normalizeUsage } from '../../stats/normalizer.js';
@@ -727,7 +726,19 @@ export class ResponseEngine {
         const selfAid = runtime?.selfAid || session?.selfAID;
         if (!selfAid)
             return { ok: false, code: 'HANDOFF_NOT_FOUND', error: 'self agent not found' };
-        return this.handoffRuntime.returnHandoff({
+        return this.returnAuthorizedHandoffResult({
+            sessionId: params.sessionId,
+            handoffId: params.handoffId,
+            content: params.content,
+        }, selfAid);
+    }
+    /** Execute a handoff return after the daemon IPC boundary has authorized the task delegation. */
+    async returnAuthorizedHandoffResult(params, selfAid) {
+        if (!this.handoffRuntime) {
+            return { ok: false, code: 'HANDOFF_NOT_FOUND', error: 'handoff runtime not configured' };
+        }
+        const runtime = this.activeTaskRuntimeContexts.get(params.sessionId);
+        return await this.handoffRuntime.returnHandoff({
             selfAid,
             currentSessionId: params.sessionId,
             handoffId: params.handoffId,
@@ -1152,6 +1163,14 @@ export class ResponseEngine {
     async processMessage(message) {
         const idleMs = (this.globalSettings.idleMonitor?.timeout ?? 120) * 1000;
         const totalExecutionMs = this.totalExecutionLimitMs();
+        if (message.handoffDelivery
+            && this.handoffRuntime
+            && this.handoffRuntime.isDiscardedDelivery(message)) {
+            logger.info(`[ResponseEngine] Skip stale handoff delivery before session resolution:`
+                + ` direction=${message.handoffDelivery.direction}`
+                + ` handoff=${message.handoffDelivery.handoffId}`);
+            return;
+        }
         // 先解析会话，再优先用 session.metadata.channelKey 精确定位实例级 adapter
         // message.channel 现在存实例名（channelName），可直接用于精确路由
         const { session, absoluteProjectPath } = await this.resolveSession(message);
@@ -1720,11 +1739,11 @@ export class ResponseEngine {
                 messageId: message.messageId, peerId: message.peerId, content: message.content,
                 peerType: message.peerType || session.metadata?.peerType,
                 chatType: chatType, isMentioned: message.isMentioned,
-                mentionAids: message.mentionAids, source: message.source,
+                mentions: message.mentions, mentionAids: message.mentionAids, source: message.source,
             },
             modeConfig: resolvedMode.context.modeConfig,
             state: modeState,
-            isSendCommand: (toolName, toolInput) => isEvolcoreSendCommandForSession(toolName, toolInput, session.channelId),
+            isSendCommand: (toolName, toolInput) => isExactEvolcoreSendCommandForSession(toolName, toolInput, session.channelId, chatType, session.selfAID || message.selfAID),
             logger,
         } : null;
         if (resolvedMode?.mode.beforeProcess && modeProcessCtx) {
@@ -2118,11 +2137,21 @@ export class ResponseEngine {
                     },
                 };
             })();
+            let effectivePermissionMode = 'readonly';
             const recordExecutionAnomaly = triggerRunId
                 ? (anomaly) => {
-                    recordTriggerExecutionAnomaly(triggerRunId, anomaly);
+                    recordTriggerExecutionAnomaly(triggerRunId, {
+                        ...anomaly,
+                        agentAid: anomaly.agentAid ?? session.selfAID ?? message.selfAID,
+                        sessionId: anomaly.sessionId ?? session.id,
+                        permissionMode: anomaly.permissionMode ?? effectivePermissionMode,
+                    });
                 }
                 : undefined;
+            const runModeConfig = resolvedMode?.mode.configureRun && modeProcessCtx
+                ? resolvedMode.mode.configureRun(modeProcessCtx)
+                : undefined;
+            const pureSessionPolicyHook = runModeConfig?.policyHook;
             // 设置权限审批的交互上下文（支持交互卡片）
             agent.setPermissionContext?.(session.id, {
                 sendPrompt: permissionPromptForOrigin,
@@ -2144,6 +2173,7 @@ export class ResponseEngine {
                 approvalRouting,
                 approvalInteractionPolicy: authorizationIdentity ? 'deny' : 'interactive',
                 recordExecutionAnomaly,
+                preToolUsePolicyHook: pureSessionPolicyHook,
                 armApprovedDelegationCommand: this.agentDelegationRegistry
                     ? (carrierToken, commandHash) => this.agentDelegationRegistry.armApprovedCommand({
                         carrierToken,
@@ -2233,10 +2263,7 @@ export class ResponseEngine {
                 // [迁移点2] policyHook 由 ProactiveMode.configureRun 提供（插件决策）；
                 // 引擎补充副作用：违规时注入提醒到模型上下文 + 行为探针。
                 policyHook: (() => {
-                    const runConfig = resolvedMode?.mode.configureRun && modeProcessCtx
-                        ? resolvedMode.mode.configureRun(modeProcessCtx)
-                        : undefined;
-                    const pluginHook = runConfig?.policyHook;
+                    const pluginHook = pureSessionPolicyHook;
                     if (!pluginHook)
                         return undefined;
                     return (toolName, toolInput) => {
@@ -2250,9 +2277,9 @@ export class ResponseEngine {
                             agent.injectUserMessage?.(session.id, errorMsg);
                             return result;
                         }
-                        // 首工具检查通过（firstToolDone 从 false 翻成 true 且未拦截）
-                        const stAfter = modeState.get('proactive');
-                        if (wasFirstPending && stAfter?.firstToolDone) {
+                        // 这里只记录审批结果。firstToolDone 必须等真实 tool_use 事件再推进，
+                        // 避免伪造 managed hook IPC 提前解除门禁。
+                        if (wasFirstPending) {
                             snapshot.set(session.id, taskId, { policyHook: { triggered: true, blocked: false, toolName } });
                         }
                         return undefined;
@@ -2290,8 +2317,6 @@ export class ResponseEngine {
             let handoffPromptRendered = false;
             let runtimeEnv;
             try {
-                // 动态构建运行时上下文提示
-                const contextParts = [];
                 // 通道能力
                 const supportsFileMarker = currentChannelType !== 'aun' && !isProactive && !!channelInfo.adapter.capabilities?.file;
                 const capParts = [];
@@ -2301,14 +2326,11 @@ export class ResponseEngine {
                     capParts.push('图片输出');
                 if (!isProactive && channelInfo.adapter.capabilities?.file)
                     capParts.push('文件发送');
-                // Personal layer
+                // Personal state is exposed to the manifest as vars. The manifest owns
+                // loading persona.md and working.md into the system prompt.
                 const owningAgent = owningAgentForTask;
                 const persona = owningAgent?.getPersona?.() || undefined;
                 const working = owningAgent?.getWorkingMemory?.() || undefined;
-                if (persona)
-                    contextParts.push(persona);
-                if (working)
-                    contextParts.push(`[当前关注]\n${working}`);
                 // 计算 peerKey：群聊固定按 groupId/channelId，私聊按发送者 peerId。
                 // 这样单条和积压合并批次不会因队列状态不同而切换关系级配置。
                 const normalizedBaseagent = normalizeBaseagent(agent.name);
@@ -2316,7 +2338,6 @@ export class ResponseEngine {
                 // Trigger 只能降低本次调用权限，不能突破当前角色的权限上限。
                 // 作为 per-call 入参随 modelOverride 传入 runQuery —— 与 model/effort 同构，
                 // 不写 AgentRunner 实例字段，多对端/多会话并发共享同一 runner 实例时互不污染。
-                let effectivePermissionMode;
                 const triggerPermissionModeOverride = message.triggerMeta?.permissionModeOverride;
                 try {
                     effectivePermissionMode = constrainRuntimePermissionMode({
@@ -2532,9 +2553,10 @@ export class ResponseEngine {
                         channel: currentChannelType || null,
                         venueUid: undefined,
                         // 群 @ 处理模式 / 客户端类型 / 权限模式
-                        // 优先 agent/relation mentionMode 配置，fallback 到服务器 dispatch_mode 缓存（协议词汇需翻译）。
+                        // 优先 agent/relation mentionMode 配置，fallback 到服务器 mention_mode 缓存。
                         mentionMode: effectiveAgentConfig?.mentionMode
-                            ?? dispatchToMentionMode(session.metadata?.dispatchMode ?? message.dispatchMode)
+                            ?? session.metadata?.mentionMode
+                            ?? message.mentionMode
                             ?? undefined,
                         clientType: message.clientType || undefined,
                         permissionMode: effectivePermissionMode,
@@ -2583,17 +2605,13 @@ export class ResponseEngine {
                 const sessionManifests = this.agentRegistry?.resolveByChannel(channelKey)?.config?.sessionManifests;
                 const manifestFile = sessionManifests?.[sessionType] ?? 'eck_manifest.json';
                 const kitContext = renderKitSections(kitCtx, manifestFile);
-                if (kitContext)
-                    contextParts.push(kitContext);
-                effectiveSystemPrompt = [options?.systemPromptAppend, ...contextParts].filter(Boolean).join('\n') || undefined;
+                effectiveSystemPrompt = [options?.systemPromptAppend, kitContext].filter(Boolean).join('\n') || undefined;
                 // ── Stats: context_breakdown 旁路采集（各段估算 token 数，字符数/4 近似） ──
                 try {
                     const estTokens = (s) => s ? Math.ceil(s.length / 4) : 0;
                     const cbModel = effectiveModel || agentModel || 'unknown';
                     const cbMaxTokens = 200000; // 保守默认，后续可从 model-catalog 取
                     const systemPromptTokens = estTokens(options?.systemPromptAppend);
-                    const personaTokens = estTokens(persona);
-                    const workingTokens = estTokens(working);
                     const kitTokens = estTokens(kitContext);
                     const totalEst = estTokens(effectiveSystemPrompt);
                     insertContextBreakdown(resolveRoot(), {
@@ -2603,7 +2621,7 @@ export class ResponseEngine {
                         turn_count: 0, // 按 ts 排序得轮次
                         model: cbModel,
                         max_tokens: cbMaxTokens,
-                        system_prompt: systemPromptTokens + personaTokens + workingTokens,
+                        system_prompt: systemPromptTokens,
                         system_tools: 0, // 工具 schema 不在此层，留 0（后续 runner 层补）
                         mcp_tools: 0,
                         custom_agents: 0,
@@ -2629,6 +2647,7 @@ export class ResponseEngine {
                                 encrypted: message.encrypted,
                                 content: message.content, timestamp: message.timestamp,
                                 images: message.images,
+                                mentions: message.mentions,
                                 mentionAids: message.mentionAids,
                             }];
                     const peerItems = (() => {
@@ -3916,12 +3935,10 @@ export class ResponseEngine {
                 await this.sessionManager.updateSession(session.id, { metadata: session.metadata });
             }
         }
-        // 群聊分发模式同步：aun.ts 从服务器信封解析的 dispatchMode 注入到 message，
-        // 此处写入 session.metadata，确保 ECK 上下文的 venue fragment 正确渲染 dispatch 变量。
-        // 仅当 message.dispatchMode 有值且与 session 记录不一致时更新。
-        if (message.chatType === 'group' && message.dispatchMode && session.metadata?.dispatchMode !== message.dispatchMode) {
-            logger.info(`[ResponseEngine] dispatchMode sync: sessionId=${session.id} ${session.metadata?.dispatchMode ?? 'none'} -> ${message.dispatchMode}`);
-            session.metadata = { ...(session.metadata || {}), dispatchMode: message.dispatchMode };
+        // 同步服务端 mention_mode，供同一群会话的上下文和菜单展示使用。
+        if (message.chatType === 'group' && message.mentionMode && session.metadata?.mentionMode !== message.mentionMode) {
+            logger.info(`[ResponseEngine] mentionMode sync: sessionId=${session.id} ${session.metadata?.mentionMode ?? 'none'} -> ${message.mentionMode}`);
+            session.metadata = { ...(session.metadata || {}), mentionMode: message.mentionMode };
             await this.sessionManager.updateSession(session.id, { metadata: session.metadata });
         }
         // chatMode 策略由 agent/relation behavior 配置在处理阶段解析；此处不再写 session 级参数。
@@ -4293,6 +4310,7 @@ export class ResponseEngine {
                         }
                         // [迁移点4] 工具汇报提醒：由 ProactiveMode.onToolUse 实现
                         if (modeHooks?.mode?.onToolUse) {
+                            const proactiveState = modeHooks.state.get('proactive');
                             modeHooks.mode.onToolUse({
                                 session,
                                 state: modeHooks.state,
@@ -4300,7 +4318,7 @@ export class ResponseEngine {
                                 toolInput: event.input || {},
                                 injectToModel: (text) => { agent.injectUserMessage?.(session.id, text); },
                                 getQueueLength: () => this.messageQueue?.getQueueLength(session.id) ?? 0,
-                                isSendCommand: (toolName, toolInput) => isEvolcoreSendCommandForSession(toolName, toolInput, session.channelId),
+                                isSendCommand: (toolName, toolInput) => isExactEvolcoreSendCommandForSession(toolName, toolInput, session.channelId, proactiveState?.chatType === 'group' ? 'group' : 'private', session.selfAID),
                                 logger,
                             });
                         }

package/dist/core/permission/ec-command-parser.js

@@ -1,4 +1,11 @@
 const HEAD_EXECUTABLES = new Set(['head', '/bin/head', '/usr/bin/head']);
+// Codex app-server sends command executions through a fixed shell carrier.
+// Treat the carrier as syntax only after parsing it as literal argv; never
+// accept an arbitrary `sh -c` string or unwrap shell composition here.
+const CODEX_SHELL_EXECUTABLES = new Set([
+    'bash', '/bin/bash', '/usr/bin/bash',
+    'sh', '/bin/sh', '/usr/bin/sh',
+]);
 const SHELL_UNQUOTED_META = new Set([
     ';', '&', '|', '`', '<', '>', '$', '(', ')', '*', '?', '[', ']', '{', '}', '#',
 ]);
@@ -135,6 +142,42 @@ export function parseLiteralShellArgv(command) {
     const result = parseLiteralShellCommand(command);
     return result.ok ? result.argv : null;
 }
+/**
+ * Return the command string carried by Codex's literal `/bin/bash -lc ...`
+ * wrapper. The wrapper is accepted only in its exact three-argv form and the
+ * caller must parse the returned string with the literal shell parser again.
+ */
+export function unwrapCodexShellCommandArgv(argv) {
+    if (argv.length !== 3 || argv[1] !== '-lc')
+        return undefined;
+    return CODEX_SHELL_EXECUTABLES.has(argv[0]) ? argv[2] : undefined;
+}
+/**
+ * Parse either a bare literal command or the exact shell carrier emitted by
+ * Codex app-server. This does not make shell composition safe: the nested
+ * command still has to pass `parseLiteralShellCommand`.
+ */
+export function parseCodexShellCommandArgv(command) {
+    const outer = parseLiteralShellArgv(command);
+    if (!outer)
+        return null;
+    const wrapped = unwrapCodexShellCommandArgv(outer);
+    return wrapped === undefined ? outer : parseLiteralShellArgv(wrapped);
+}
+/**
+ * Resolve a Codex command input while preserving the raw `commandArgv` form
+ * supplied by app-server. Joining that argv with spaces loses the quoting of
+ * the inner `-lc` command and was the source of a false proactive denial.
+ */
+export function parseCodexToolCommandArgv(input) {
+    if (Array.isArray(input.commandArgv) && input.commandArgv.every(value => typeof value === 'string')) {
+        const outer = input.commandArgv;
+        const wrapped = unwrapCodexShellCommandArgv(outer);
+        return wrapped === undefined ? outer : parseLiteralShellArgv(wrapped);
+    }
+    const command = typeof input.command === 'string' ? input.command : '';
+    return parseCodexShellCommandArgv(command);
+}
 function scanBoundedOutputOperators(command) {
     const operators = [];
     let quote = null;
@@ -314,9 +357,18 @@ export function parseBoundedOutputShellCommand(command) {
 export function classifyEvolcoreShellCommand(command) {
     const literal = parseLiteralShellCommand(command);
     if (literal.ok) {
-        return literal.argv[0] === 'ec'
-            ? { kind: 'literal' }
-            : { kind: 'none' };
+        if (literal.argv[0] === 'ec')
+            return { kind: 'literal' };
+        const wrapped = unwrapCodexShellCommandArgv(literal.argv);
+        if (wrapped !== undefined) {
+            const nested = parseLiteralShellCommand(wrapped);
+            if (nested.ok && nested.argv[0] === 'ec')
+                return { kind: 'literal' };
+            if (!nested.ok && EVOLCORE_COMMAND_POSITION_RE.test(wrapped)) {
+                return { kind: 'composite', issue: nested.issue };
+            }
+        }
+        return { kind: 'none' };
     }
     const boundedOutput = parseBoundedOutputShellCommand(command);
     if (boundedOutput && boundedOutput.argv[0] === 'ec') {
@@ -350,8 +402,81 @@ function findSingleFileOption(argv, startIndex) {
         ? { path: filePath, invalid: false }
         : { invalid: true };
 }
-export function parseEvolcoreSendCommand(command) {
-    const argv = parseLiteralShellArgv(command);
+const PROACTIVE_SEND_VALUE_FLAGS = new Set([
+    '--format', '--app', '--file', '--text-from-file', '--link', '--payload',
+    '--title', '--description', '--text', '--transcript', '--as',
+    '--content-type', '--mention', '--aun-path', '--thread', '--return',
+]);
+const PROACTIVE_SEND_BOOLEAN_FLAGS = new Set([
+    '--encrypt', '--no-encrypt', '--mention-all',
+]);
+function hasExecutableProactiveSendPayload(argv, scope) {
+    if (!argv || argv[0] !== 'ec' || argv[1] !== scope || argv[2] !== 'send')
+        return false;
+    const positionals = [];
+    const modes = new Map();
+    let endOfOptions = false;
+    for (let index = 5; index < argv.length; index++) {
+        const value = argv[index];
+        if (endOfOptions) {
+            positionals.push(value);
+            continue;
+        }
+        if (value === '--') {
+            endOfOptions = true;
+            continue;
+        }
+        if (PROACTIVE_SEND_BOOLEAN_FLAGS.has(value))
+            continue;
+        if (!PROACTIVE_SEND_VALUE_FLAGS.has(value)) {
+            positionals.push(value);
+            continue;
+        }
+        const operand = argv[++index];
+        if (operand === undefined || operand.startsWith('--'))
+            return false;
+        if (value === '--file' || value === '--text-from-file')
+            return false;
+        if (value === '--app' || value === '--aun-path')
+            return false;
+        if (value === '--return' && operand !== 'none' && operand !== 'required')
+            return false;
+        if (value === '--format' && operand !== 'json')
+            return false;
+        if (value === '--link') {
+            if (scope !== 'msg' || modes.has('link'))
+                return false;
+            modes.set('link', operand);
+        }
+        if (value === '--payload') {
+            if (modes.has('payload'))
+                return false;
+            modes.set('payload', operand);
+        }
+    }
+    if (modes.size > 1)
+        return false;
+    if (modes.has('link')) {
+        try {
+            const url = new URL(modes.get('link'));
+            return url.protocol === 'http:' || url.protocol === 'https:';
+        }
+        catch {
+            return false;
+        }
+    }
+    if (modes.has('payload')) {
+        try {
+            const payload = JSON.parse(modes.get('payload'));
+            return !!payload && typeof payload === 'object' && !Array.isArray(payload);
+        }
+        catch {
+            return false;
+        }
+    }
+    return positionals.join(' ').length > 0;
+}
+function parseEvolcoreSendArgv(argv) {
     if (!argv || argv[0] !== 'ec')
         return null;
     if (argv[1] === 'ctl') {
@@ -380,23 +505,44 @@ export function parseEvolcoreSendCommand(command) {
     if (subcommand === 'file') {
         if (argv.length !== 6 || !isDeterministicFilePath(argv[5]))
             return null;
-        return { scope, action: 'file', targetId, filePath: argv[5] };
+        return { scope, action: 'file', sourceId: argv[3], targetId, filePath: argv[5] };
     }
     const fileOption = findSingleFileOption(argv, 5);
     if (fileOption.invalid)
         return null;
     return fileOption.path
-        ? { scope, action: 'file', targetId, filePath: fileOption.path }
-        : { scope, action: 'send', targetId };
+        ? { scope, action: 'file', sourceId: argv[3], targetId, filePath: fileOption.path }
+        : { scope, action: 'send', sourceId: argv[3], targetId };
+}
+export function parseEvolcoreSendCommand(command) {
+    const argv = parseCodexShellCommandArgv(command);
+    return argv ? parseEvolcoreSendArgv(argv) : null;
 }
 export function isEvolcoreSendCommandForSession(toolName, input, channelId) {
     if (toolName !== 'Bash')
         return false;
-    const cmd = typeof input.command === 'string' ? input.command : '';
-    const parsed = parseEvolcoreSendCommand(cmd);
+    const argv = parseCodexToolCommandArgv(input);
+    const parsed = argv ? parseEvolcoreSendArgv(argv) : null;
     if (!parsed)
         return false;
     if (parsed.scope === 'ctl')
         return true;
     return parsed.targetId === channelId;
 }
+/** Proactive first-send guard: exact channel kind and current target only. */
+export function isExactEvolcoreSendCommandForSession(toolName, input, channelId, chatType, selfAid) {
+    // Codex hooks use the canonical name `Bash`; the app-server event adapter
+    // exposes the same commandExecution items as `Shell` to the renderer.
+    if ((toolName !== 'Bash' && toolName !== 'Shell') || !selfAid)
+        return false;
+    const argv = parseCodexToolCommandArgv(input);
+    const parsed = argv ? parseEvolcoreSendArgv(argv) : null;
+    if (!parsed || parsed.action !== 'send')
+        return false;
+    const expectedScope = chatType === 'group' ? 'group' : 'msg';
+    return parsed.scope === expectedScope
+        && parsed.targetId === channelId
+        && parsed.sourceId === selfAid
+        && !!argv
+        && hasExecutableProactiveSendPayload(argv, expectedScope);
+}

package/dist/core/permission/sandbox-runtime.js

@@ -210,7 +210,7 @@ function appendLClassReadOnlyBinds(args, root) {
         args.push('--ro-bind', target.path, target.path);
     }
 }
-export function buildHClassGuardCommand(executable, executableArgs, root = resolveRoot()) {
+export function buildHClassGuardCommand(executable, executableArgs, root = resolveRoot(), options = {}) {
     const bubblewrapPath = resolveBubblewrapPath();
     if (!bubblewrapPath)
         return undefined;
@@ -224,6 +224,27 @@ export function buildHClassGuardCommand(executable, executableArgs, root = resol
     ];
     appendLClassReadOnlyBinds(args, path.resolve(root));
     appendHClassMasks(args, path.resolve(root), true);
+    if (options.managedCodexRequirements) {
+        const requirements = path.resolve(options.managedCodexRequirements);
+        if (!fs.statSync(requirements).isFile()) {
+            throw new Error(`Codex managed requirements is not a file: ${requirements}`);
+        }
+        const managedDirectory = path.dirname(requirements);
+        // Keep the copied hook immutable even when a session uses bypass mode.
+        args.push('--ro-bind', managedDirectory, managedDirectory);
+        // A host may not have /etc/codex yet. Overlay /etc inside this namespace so
+        // Bubblewrap can create the mountpoint without modifying the host, while
+        // retaining the complete host /etc as the read-only lower layer.
+        args.push('--overlay-src', '/etc');
+        args.push('--tmp-overlay', '/etc');
+        args.push('--dir', '/etc/codex');
+        // Replace the complete Codex system-config directory inside this app-server
+        // namespace so host system hooks cannot join EvolCore's managed hook set.
+        args.push('--tmpfs', '/etc/codex');
+        args.push('--ro-bind', requirements, '/etc/codex/requirements.toml');
+        args.push('--remount-ro', '/etc/codex');
+        args.push('--remount-ro', '/etc');
+    }
     args.push('--', executable, ...executableArgs);
     return { command: bubblewrapPath, args };
 }