@jc_stack/ez-agents 0.1.0-beta.33 → 0.1.0-beta.36

package/src/delivery-socket.ts

@@ -0,0 +1,354 @@
+import { createServer, type Server, type Socket } from 'node:net'
+import { randomBytes, timingSafeEqual } from 'node:crypto'
+import { rename, rm, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { callDeliverySocket as callSocket, deliverySocketAlive as socketAlive, deliverySocketPath } from './delivery-socket-client.mjs'
+import { RunStore, sentOutbox, type RunRecord } from './runs.js'
+import { ApprovalStore } from './approval.js'
+import { deliveredMessages } from './message-history.js'
+import { readOnlyOwner, requireOwnerExecution } from './execution-authority.js'
+import { telegramOwner } from './control-state.js'
+
+// Stateless pipe transport. The relay owns the runs/outbox ledger in process
+// memory; engine children, plugin children and the host executor reach it
+// through this socket instead of control/ files. The socket lives on the
+// shared control volume so container-colocated and host-side children use the
+// same path. Binding it also guards single-relay ownership (replacing the old
+// relay.lock flock): a second relay finds the address live and exits.
+//
+// Frames are newline-delimited JSON: {id, op, payload} -> {id, ok, result?,
+// error?}. Every op re-verifies ownership server-side; request metadata is
+// never trusted. A restart drops the ledger by design: in-flight sends report
+// unknown rather than claiming success. The transport itself lives in
+// delivery-socket-client.mjs so plain-Node tools share one implementation.
+
+export { deliverySocketPath }
+
+export type DeliverySocketOp =
+  | { op: 'ping' }
+  | { op: 'status' }
+  | { op: 'enqueue'; payload: Record<string, unknown> }
+  | { op: 'wait'; payload: { id: string; timeoutMs?: number } }
+  | { op: 'get'; payload: { runId: string } }
+  | { op: 'list'; payload?: Record<string, never> }
+  | { op: 'patch'; payload: { runId: string; change: Record<string, unknown> } }
+  | { op: 'authorize'; payload: { runId: string } }
+  | { op: 'receipt'; payload: { context: unknown; id: string } }
+  | { op: 'history'; payload: { runId: string; limit?: number; messageId?: number } }
+  | { op: 'deliveryStatus'; payload?: Record<string, never> }
+  | { op: 'approvalCheck'; payload: { actionId: string } }
+  | { op: 'latestReply'; payload?: Record<string, never> }
+
+export type DeliveryHandler = (op: DeliverySocketOp) => Promise<unknown>
+
+// Socket-first run reads for library modules that execute both inside the
+// relay (shared memory) and in sibling processes (host executor,
+// task executor). A relay answering on the shared-volume socket is
+// authoritative; connect-level failures fall back to direct memory, which is
+// empty in a fresh sibling process and therefore fails closed. Post-connect
+// errors (unknown run, revoked owner) always propagate.
+const connectFailure = (error: unknown): boolean =>
+  error instanceof Error && (/Delivery relay unavailable/.test(error.message) || /ECONNREFUSED|ENOENT/.test(error.message))
+
+export const readRun = async (controlDir: string, runId: string): Promise<RunRecord | null> => {
+  try {
+    const run = await callDeliverySocket(socketPathFor(controlDir), { op: 'get', payload: { runId } }, 10_000)
+    return run as RunRecord
+  } catch (error) {
+    if (!connectFailure(error)) throw error
+    if (error instanceof Error && /Unknown run/.test(error.message)) return null
+    return new RunStore(controlDir).get(runId)
+  }
+}
+
+export const authorizeRun = async (controlDir: string, runId: string): Promise<RunRecord> => {
+  try {
+    const run = await callDeliverySocket(socketPathFor(controlDir), { op: 'authorize', payload: { runId } }, 10_000)
+    return run as RunRecord
+  } catch (error) {
+    if (!connectFailure(error)) throw error
+    return requireOwnerExecution(controlDir, runId)
+  }
+}
+
+const encode = (value: unknown): string => `${JSON.stringify(value)}\n`
+
+export type DeliveryEndpoint = { host: '127.0.0.1'; port: number; token: string }
+export type DeliveryServeOptions = { tcpPort?: number }
+const endpointFile = 'delivery-endpoint.json'
+const tokensMatch = (candidate: unknown, token: string): boolean =>
+  typeof candidate === 'string' && candidate.length === token.length && timingSafeEqual(Buffer.from(candidate), Buffer.from(token))
+
+export const serveDeliverySocket = async (
+  controlDir: string,
+  handle: DeliveryHandler,
+  options: DeliveryServeOptions = {},
+): Promise<{ socketPath: string; endpoint: DeliveryEndpoint | null; stop: () => Promise<void> }> => {
+  const socketPath = deliverySocketPath(controlDir)
+  await rm(socketPath, { force: true }).catch(() => {})
+  const attach = (socket: Socket, token: string | null): void => {
+    let buffer = ''
+    socket.setEncoding('utf8')
+    socket.on('data', (chunk: string) => {
+      buffer += chunk
+      let newline: number
+      while ((newline = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, newline)
+        buffer = buffer.slice(newline + 1)
+        if (!line.trim()) continue
+        void (async () => {
+          let id: unknown = null
+          try {
+            const envelope = JSON.parse(line) as { id?: unknown; token?: unknown; op?: unknown; payload?: unknown }
+            id = envelope.id ?? null
+            // Loopback TCP callers authenticate per frame against the token in
+            // the owner-readable control directory; the filesystem channels
+            // (Unix socket) keep their existing peer trust. Every op still
+            // re-verifies owner authority server-side.
+            if (token !== null && !tokensMatch(envelope.token, token)) { socket.destroy(); return }
+            const { token: _token, ...request } = envelope
+            const result = await handle(request as DeliverySocketOp)
+            socket.write(encode({ id, ok: true, result: result ?? null }))
+          } catch (error) {
+            socket.write(encode({ id, ok: false, error: error instanceof Error ? error.message : String(error ?? 'Unknown error') }))
+          }
+        })()
+      }
+    })
+  }
+  const server: Server = createServer((socket: Socket) => attach(socket, null))
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(socketPath, () => {
+      server.removeListener('error', reject)
+      resolve()
+    })
+  })
+  // A live sibling relay already owns this agent. Refuse to split-brain.
+  server.on('error', () => {})
+  // A deployment that no longer publishes the endpoint must not leave a stale
+  // token/port behind for host CLIs to dial before failing.
+  if (options.tcpPort === undefined) await rm(path.join(controlDir, endpointFile), { force: true }).catch(() => {})
+  let tcp: Server | null = null
+  let endpoint: DeliveryEndpoint | null = null
+  if (options.tcpPort !== undefined) {
+    if (!Number.isSafeInteger(options.tcpPort) || options.tcpPort < 0 || options.tcpPort > 65535) throw new Error('Invalid delivery TCP port')
+    const token = randomBytes(32).toString('hex')
+    const listener: Server = createServer((socket: Socket) => attach(socket, token))
+    try {
+      await new Promise<void>((resolve, reject) => {
+        listener.once('error', reject)
+        listener.listen(options.tcpPort, '0.0.0.0', () => {
+          listener.removeListener('error', reject)
+          resolve()
+        })
+      })
+    } catch (error) {
+      await new Promise<void>((resolve) => server.close(() => resolve()))
+      throw error
+    }
+    listener.on('error', () => {})
+    const address = listener.address()
+    if (!address || typeof address === 'string') {
+      await new Promise<void>((resolve) => listener.close(() => resolve()))
+      await new Promise<void>((resolve) => server.close(() => resolve()))
+      throw new Error('Delivery TCP listener address unavailable')
+    }
+    tcp = listener
+    endpoint = { host: '127.0.0.1', port: address.port, token }
+    const file = path.join(controlDir, endpointFile)
+    const temporary = `${file}.${process.pid}.tmp`
+    await writeFile(temporary, JSON.stringify(endpoint), { mode: 0o600 })
+    await rename(temporary, file)
+  }
+  const tcpServer = tcp
+  const tcpEndpoint = endpoint
+  return {
+    socketPath,
+    endpoint,
+    stop: async () => {
+      await new Promise<void>((resolve) => server.close(() => resolve()))
+      await rm(socketPath, { force: true }).catch(() => {})
+      if (tcpServer) await new Promise<void>((resolve) => tcpServer.close(() => resolve()))
+      if (tcpEndpoint) await rm(path.join(controlDir, endpointFile), { force: true }).catch(() => {})
+    },
+  }
+}
+
+// Children derive the rendezvous from the agent control directory they were
+// given; EZ_DELIVERY_SOCKET overrides it (tests, custom layouts).
+export const socketPathFor = (controlDir: string, env: NodeJS.ProcessEnv = process.env): string =>
+  env.EZ_DELIVERY_SOCKET?.trim() || deliverySocketPath(controlDir)
+
+export type LedgerHooks = {
+  // Wake the relay outbox pump after an enqueue. Test fixtures pass a noop
+  // when they drive delivery synchronously.
+  wake: () => void
+  // Live relay surface for the status op (polling, transport, version).
+  status: () => Promise<{ polling: boolean; applicationOnly: boolean; telegramConfigured: boolean; version: string }> | { polling: boolean; applicationOnly: boolean; telegramConfigured: boolean; version: string }
+}
+
+// Memory-ledger request handler shared by the relay and by test fixtures.
+// Every op re-verifies ownership server-side; request metadata is never
+// trusted. Unknown IDs, invalid payloads and revoked bindings fail closed.
+export const createLedgerHandler = (controlDir: string, hooks: LedgerHooks): DeliveryHandler => {
+  const runs = new RunStore(controlDir)
+  const approvals = new ApprovalStore(controlDir)
+  const nonEmptyString = (value: unknown): value is string =>
+    typeof value === 'string' && value.trim().length > 0
+  return async (op: DeliverySocketOp): Promise<unknown> => {
+    switch (op.op) {
+      case 'ping': return { ok: true }
+      case 'status': {
+        const all = await runs.list()
+        return {
+          ...(await hooks.status()),
+          at: Date.now(),
+          running: all.filter((run) => run.status === 'running').length,
+          queued: all.filter((run) => run.status === 'queued').length,
+        }
+      }
+      case 'enqueue': {
+        const envelope = (op.payload ?? {}) as Record<string, unknown>
+        if (envelope.kind === 'owner') {
+          if (!envelope.deliveryContext || typeof envelope.deliveryContext !== 'object') throw new Error('Delivery context is required')
+          const type = envelope.type
+          if (type !== 'message' && type !== 'document' && type !== 'voice') throw new Error('Unsupported owner delivery type')
+          const text = envelope.text
+          if (type === 'message' && !nonEmptyString(text)) throw new Error('Message content is required')
+          const item = await runs.enqueueOwnerDelivery(
+            envelope.deliveryContext as never,
+            {
+              type,
+              ...(nonEmptyString(text) ? { text: (text as string).trim() } : {}),
+              ...(typeof envelope.documentPath === 'string' ? { documentPath: envelope.documentPath } : {}),
+              ...(typeof envelope.voiceText === 'string' ? { voiceText: envelope.voiceText } : {}),
+              ...(Number.isSafeInteger(envelope.replyToMessageId) ? { replyToMessageId: envelope.replyToMessageId as number } : {}),
+            },
+          )
+          hooks.wake()
+          return { outbox_id: item.id, id: item.id, type: item.type }
+        }
+        if (typeof envelope.runId !== 'string' || !envelope.runId) throw new Error('Run ID is required')
+        const replyTo = Number.isSafeInteger(envelope.replyToMessageId) ? { replyToMessageId: envelope.replyToMessageId as number } : {}
+        const id = typeof envelope.id === 'string' && envelope.id ? { id: envelope.id } : {}
+        let item
+        switch (envelope.kind) {
+          case 'message': {
+            if (!nonEmptyString(envelope.text)) throw new Error('Message content is required')
+            item = await runs.enqueueMessage(envelope.runId, (envelope.text as string).trim(), { ...replyTo, ...id })
+            break
+          }
+          case 'document': {
+            if (typeof envelope.documentPath !== 'string' || !envelope.documentPath) throw new Error('Document path is required')
+            const caption = nonEmptyString(envelope.text) ? (envelope.text as string).trim() : undefined
+            item = await runs.enqueueDocument(envelope.runId, envelope.documentPath, { ...(caption ? { caption } : {}), ...replyTo })
+            break
+          }
+          case 'voice': {
+            if (!nonEmptyString(envelope.voiceText)) throw new Error('Voice text is required')
+            item = await runs.enqueueVoice(envelope.runId, (envelope.voiceText as string).trim(), replyTo)
+            break
+          }
+          case 'reaction': {
+            if (!nonEmptyString(envelope.emoji)) throw new Error('Reaction emoji is required')
+            item = await runs.enqueueReaction(envelope.runId, envelope.emoji as string)
+            break
+          }
+          case 'approval': {
+            if (!nonEmptyString(envelope.approvalPrompt) || !nonEmptyString(envelope.approvalActionId))
+              throw new Error('Approval prompt and action ID are required')
+            await approvals.requestApproval(envelope.approvalActionId as string, (envelope.approvalPrompt as string).trim(), envelope.runId)
+            item = await runs.enqueueApproval(envelope.runId, (envelope.approvalPrompt as string).trim(), envelope.approvalActionId as string, replyTo)
+            break
+          }
+          default: throw new Error('Unsupported delivery kind')
+        }
+        hooks.wake()
+        return { outbox_id: item.id, id: item.id, type: item.type }
+      }
+      case 'wait': {
+        const { id, timeoutMs } = (op.payload ?? {}) as { id?: unknown; timeoutMs?: unknown }
+        if (typeof id !== 'string' || !id) throw new Error('Outbox ID is required')
+        const receipt = await runs.waitForDelivery(id, typeof timeoutMs === 'number' && timeoutMs > 0 ? Math.min(timeoutMs, 130_000) : 120_000)
+        return { status: 'delivered', receipt }
+      }
+      case 'get': {
+        const runId = (op.payload as { runId?: unknown } | undefined)?.runId
+        if (typeof runId !== 'string' || !runId) throw new Error('Run ID is required')
+        const run = await runs.get(runId)
+        if (!run) throw new Error(`Unknown run ${runId}`)
+        return run
+      }
+      case 'list': return runs.list()
+      case 'patch': {
+        const payload = (op.payload ?? {}) as { runId?: unknown; change?: unknown }
+        if (typeof payload.runId !== 'string' || !payload.runId) throw new Error('Run ID is required')
+        if (!payload.change || typeof payload.change !== 'object') throw new Error('Patch change is required')
+        return runs.patch(payload.runId, payload.change as never)
+      }
+      case 'authorize': {
+        const runId = (op.payload as { runId?: unknown } | undefined)?.runId
+        if (typeof runId !== 'string' || !runId) throw new Error('Run ID is required')
+        return requireOwnerExecution(controlDir, runId)
+      }
+      case 'receipt': {
+        const payload = (op.payload ?? {}) as { context?: unknown; id?: unknown }
+        if (!payload.context || typeof payload.context !== 'object') throw new Error('Delivery context is required')
+        if (typeof payload.id !== 'string' || !payload.id) throw new Error('Outbox ID is required')
+        return runs.ownerDeliveryReceipt(payload.context as never, payload.id)
+      }
+      case 'history': {
+        const payload = (op.payload ?? {}) as { runId?: unknown; limit?: unknown; messageId?: unknown }
+        if (typeof payload.runId !== 'string' || !payload.runId) throw new Error('Run ID is required')
+        return deliveredMessages(controlDir, payload.runId, {
+          ...(payload.limit === undefined ? {} : { limit: payload.limit as number }),
+          ...(payload.messageId === undefined ? {} : { messageId: payload.messageId as number }),
+        })
+      }
+      case 'deliveryStatus': return runs.deliveryStatus()
+      case 'approvalCheck': {
+        const actionId = (op.payload as { actionId?: unknown } | undefined)?.actionId
+        if (typeof actionId !== 'string' || !actionId) throw new Error('Approval action ID is required')
+        const record = await approvals.getDecision(actionId)
+        return {
+          ok: true,
+          actionId,
+          decision: record?.decision || 'pending',
+          decidedAt: record?.decidedAt,
+          decidedBy: record?.decidedBy,
+        }
+      }
+      case 'latestReply': {
+        const owner = telegramOwner(await readOnlyOwner(controlDir))
+        if (!owner) return { reply: null }
+        let reply: { runId: string; messageIds: number[]; deliveredAt: string } | null = null
+        for (const item of sentOutbox(controlDir)) {
+          if (!/^tg_\d+$/.test(item.runId || '') || item.chatId !== owner.telegramChatId ||
+            (item.type && item.type !== 'message') || !Array.isArray((item.receipt as { messageIds?: unknown } | undefined)?.messageIds)) continue
+          const receipt = item.receipt as { messageIds: number[]; deliveredAt: string }
+          if (!receipt.messageIds.length || !receipt.messageIds.every((n) => Number.isSafeInteger(n) && n > 0)) continue
+          const delivered = Date.parse(receipt.deliveredAt)
+          if (!Number.isFinite(delivered) || delivered < Date.parse(owner.pairedAt) || delivered > Date.now()) continue
+          const run = await runs.get(item.runId!)
+          if (run?.status !== 'completed' || run.external || run.chatId !== owner.telegramChatId ||
+            !Number.isSafeInteger(run.telegramUserId) || run.telegramUserId! <= 0 ||
+            (owner.kind !== 'group' && run.telegramUserId !== owner.telegramUserId)) continue
+          if (!reply || delivered > Date.parse(reply.deliveredAt))
+            reply = { runId: item.runId!, messageIds: receipt.messageIds, deliveredAt: receipt.deliveredAt }
+        }
+        return { reply }
+      }
+      default: throw new Error(`Unsupported delivery op ${(op as { op?: unknown }).op}`)
+    }
+  }
+}
+
+export const deliverySocketAlive = (socketPath: string, timeoutMs = 2000): Promise<boolean> =>
+  socketAlive(socketPath, timeoutMs)
+
+// Typed facade over the shared plain-JS client so relay/TS callers keep the
+// closed DeliverySocketOp union.
+export const callDeliverySocket = (socketPath: string, op: DeliverySocketOp, timeoutMs = 130_000): Promise<unknown> =>
+  callSocket(socketPath, op, timeoutMs)
+

package/src/execution-authority.ts

@@ -1,7 +1,8 @@
 import { ApplicationBindings } from './application-channel.js'
-import { ControlStore } from './control-state.js'
 import { RunStore, type RunRecord } from './runs.js'
-import type { Owner } from './control-state.js'
+import { validOwner, type Owner } from './control-state.js'
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
 import { ownsRun } from './identity.js'
 
 export const EXTERNAL_EXECUTION_BLOCK = 'external-execution-unavailable' as const
@@ -14,12 +15,27 @@ export function executionBlockReason(run: RunRecord, owner: Owner | null): strin
   if (run.taskId || run.external || run.id.startsWith('event_')) return EXTERNAL_EXECUTION_BLOCK
 }
 
-// Re-read core state at both launch boundaries. Request metadata and EZ_RUN_ID
-// are not proof of owner identity. Local host administrators remain trusted.
+// Stateless pipe: intake authorizes the sender before spawn. The executor
+// re-verifies owner binding with a read-only control-state.json read: zero
+// control/ writes, fail-closed on missing/corrupt/revoked owner. Request
+// metadata and EZ_RUN_ID are not proof of owner identity. Local host
+// administrators remain trusted.
+export const readOnlyOwner = async (controlDir: string): Promise<Owner | null> => {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(path.join(controlDir, 'control-state.json'), 'utf8'))
+    const owner = (parsed as { owner?: unknown }).owner ?? null
+    return validOwner(owner) ? (owner as Owner) : null
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
+    throw error
+  }
+}
+
 export async function requireOwnerExecution(controlDir: string, runId: string): Promise<RunRecord> {
   const run = await new RunStore(controlDir).get(runId)
   if (!run || run.status !== 'running') throw new Error('No active core run')
-  const owner = (await new ControlStore(controlDir, 900_000).status()).owner
+  if (run.taskId || run.external || run.id.startsWith('event_')) throw new Error(`Execution blocked: ${EXTERNAL_EXECUTION_BLOCK}`)
+  const owner = await readOnlyOwner(controlDir)
   const reason = executionBlockReason(run, owner)
   if (reason) throw new Error(`Execution blocked: ${reason}`)
   if (run.application || run.delivery) await new ApplicationBindings(controlDir).authorize(run)

package/src/executor.ts

@@ -1,9 +1,8 @@
 import { executionDefaults } from './model-policy.js'
-import { Tasks } from './tasks.js'
-import { RunStore } from './runs.js'
 import { startTaskExecutor } from './task-executor.js'
-import { requireOwnerExecution } from './execution-authority.js'
+import { deliverySocketPath } from './delivery-socket.js'
 import { mkdtemp, rm, writeFile, mkdir, symlink, readFile } from 'node:fs/promises'
+import { accessSync, constants as fsConstants } from 'node:fs'
 import { tmpdir, homedir } from 'node:os'
 import path from 'node:path'
 import { spawn, type ChildProcess } from 'node:child_process'
@@ -11,6 +10,7 @@ import { processSnapshot, matchingProcessIds } from './process-tree.js'
 import { createInterface } from 'node:readline'
 import { fileURLToPath } from 'node:url'
 import { DESKTOP_UNAVAILABLE } from './desktop-bridge.js'
+import { macosWorkspaceProfile, workspaceSiblingDenies } from './workspace-confine.js'
 
 export type ExecutorOptions = {
   repairEnabled?: boolean
@@ -19,20 +19,35 @@ export type ExecutorOptions = {
   runId: string
   controlDir: string
   binDir: string
+  // Caller-owned trigger line appended to literal input. The core never reads
+  // the run ledger; admission and authorization happen before launch.
+  promptSuffix?: string
+  // Caller-owned routing flags. The core only spawns and streams.
+  taskRun?: boolean
+  nativeSession?: boolean
   toolsHome?: string
   sharedWorkspace?: string
   additionalWorkspaces?: string[]
   cli?: string
   sessionId?: string
   isResume?: boolean
-  eventSource?: string
   model?: string
   effort?: string
+  provider?: string
   codexSandbox?: 'external'
   codexAutoCompactTokens?: number
+  codexProvider?: CodexProviderBinding
   onSession?: (id: string) => Promise<void>
 }
 
+export type CodexProviderBinding = {
+  id: string
+  name: string
+  baseUrl: string
+  envKey: string
+  models: string[]
+}
+
 const allowedEnvironmentKeys = [
   'HOME',
   'LANG',
@@ -43,6 +58,8 @@ const allowedEnvironmentKeys = [
   'TERM',
   'TMPDIR',
   'USER',
+  'EZ_PLUGIN_BROKER_SOCKET',
+  'EZ_DELIVERY_SOCKET',
 ] as const
 
 export const executorEnvironment = (environment: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv => {
@@ -64,6 +81,7 @@ export const executorJobEnv = (
     PATH: pathValue,
     EZ_RUN_ID: options.runId,
     EZ_CONTROL_DIR: options.controlDir,
+    EZ_DELIVERY_SOCKET: deliverySocketPath(options.controlDir),
     EZ_REPAIR_ENABLED: String(options.repairEnabled !== false),
     ...(options.toolsHome ? {BUILDX_CONFIG:path.join(options.toolsHome,'buildx')} : {}),
   }
@@ -71,12 +89,27 @@ export const executorJobEnv = (
 
 export const grokJobEnv = executorJobEnv
 
+// Package binDir is Ez tools (ezenciel-agents-message). Native CLIs come from the
+// host PATH so one agent's wrapper cannot retarget another agent's CODEX_HOME.
+export const resolveHostCommand = (command: string, pathValue = process.env.PATH): string => {
+  if (!command || command.includes(path.sep) || command.includes('/')) return command
+  for (const directory of (pathValue ?? '').split(path.delimiter)) {
+    if (!directory) continue
+    const candidate = path.join(directory, command)
+    try {
+      accessSync(candidate, fsConstants.X_OK)
+      return candidate
+    } catch { /* try the next PATH entry */ }
+  }
+  throw new Error(`Native CLI ${command} is not executable on the host PATH`)
+}
+
 export type CliAdapter = {
   name: string
   command: string
   description: string
   buildArgs: (
-    options: Pick<ExecutorOptions, 'workspace' | 'sessionId' | 'isResume' | 'model' | 'effort' | 'toolsHome' | 'sharedWorkspace' | 'additionalWorkspaces' | 'codexAutoCompactTokens' | 'codexSandbox'> & { controlDir?: string },
+    options: Pick<ExecutorOptions, 'workspace' | 'sessionId' | 'isResume' | 'model' | 'effort' | 'toolsHome' | 'sharedWorkspace' | 'additionalWorkspaces' | 'codexAutoCompactTokens' | 'codexSandbox' | 'codexProvider'> & { controlDir?: string },
     promptFile: string,
     promptText: string,
   ) => string[]
@@ -88,6 +121,13 @@ export const EXECUTOR_REGISTRY: Record<string, CliAdapter> = {
     buildArgs: (opts, _file, prompt) => {
       if (opts.codexSandbox !== undefined && opts.codexSandbox !== 'external') throw new Error('Invalid Codex sandbox selection')
       const args = ['exec', '--skip-git-repo-check', '--json', '--sandbox', opts.codexSandbox === 'external' ? 'danger-full-access' : 'workspace-write', '--disable', 'memories', '--enable', 'skip_host_skill_discovery', '-c', 'approval_policy="never"']
+      if (opts.codexProvider) {
+        const provider = validateCodexProvider(opts.codexProvider)
+        args.push(
+          '-c', `model_provider=${JSON.stringify(provider.id)}`,
+          '-c', `model_providers.${provider.id}={name=${JSON.stringify(provider.name)},base_url=${JSON.stringify(provider.baseUrl)},env_key=${JSON.stringify(provider.envKey)},wire_api="responses",supports_websockets=false}`,
+        )
+      }
       const limit = opts.codexAutoCompactTokens
       if (limit !== undefined) {
         if (!Number.isSafeInteger(limit) || limit <= 0) throw new Error('Invalid Codex compaction token limit')
@@ -194,6 +234,32 @@ export const executorKey = (name?: string): string => {
   return resolvedKey
 }
 
+const providerToken = (value: unknown, label: string, pattern: RegExp, limit = 160): string => {
+  if (typeof value !== 'string' || value.length > limit || !pattern.test(value)) throw new Error(`Invalid Codex provider ${label}`)
+  return value
+}
+
+export const validateCodexProvider = (value: CodexProviderBinding): CodexProviderBinding => {
+  if (!value || typeof value !== 'object') throw new Error('Invalid Codex provider binding')
+  const id = providerToken(value.id, 'id', /^[a-z][a-z0-9_-]{0,31}$/)
+  const name = providerToken(value.name, 'name', /^[^\r\n\0]{1,80}$/, 80)
+  const envKey = validateCodexProviderEnvironmentKey(value.envKey)
+  let url: URL
+  try { url = new URL(value.baseUrl) } catch { throw new Error('Invalid Codex provider URL') }
+  if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash) throw new Error('Invalid Codex provider URL')
+  const models = value.models?.map(model => providerToken(model, 'model', /^[a-zA-Z0-9_./:-]{1,160}$/))
+  if (!models?.length || models.length > 64 || new Set(models).size !== models.length) throw new Error('Invalid Codex provider models')
+  return {id,name,baseUrl:url.toString().replace(/\/$/,''),envKey,models}
+}
+
+export const validateCodexProviderEnvironmentKey = (value: unknown): string => {
+  const envKey = providerToken(value, 'environment key', /^[A-Z][A-Z0-9_]{1,63}$/, 64)
+  if (allowedEnvironmentKeys.includes(envKey as typeof allowedEnvironmentKeys[number]) || envKey === 'CODEX_HOME' || envKey === 'NODE_OPTIONS' ||
+      envKey.startsWith('EZ_') || envKey.startsWith('TELEGRAM_'))
+    throw new Error('Reserved Codex provider environment key')
+  return envKey
+}
+
 export const resolveExecutor = (name?: string): CliAdapter => EXECUTOR_REGISTRY[executorKey(name)]
 
 export const grokInvocation = (
@@ -234,42 +300,45 @@ export const startExecutorJob = async (
   options: ExecutorOptions,
 ): Promise<{ child: ChildProcess; cleanup: () => Promise<void>; stdout: string }> => {
   options = executionDefaults(executorKey(options.cli), options)
-  if(options.runId.startsWith('r_schedule_') && !/^[a-zA-Z0-9_-]+$/.test(options.runId))throw new Error('Invalid native task run ID')
-  const run = await new RunStore(options.controlDir).get(options.runId)
-  if (options.codexSandbox !== undefined && (options.codexSandbox !== 'external' || process.env.EZ_EXECUTOR_TRANSPORT !== 'local' || !run || run.taskId || executorKey(options.cli) !== 'codex')) throw new Error('External Codex sandbox requires an owner-authorized native local run')
-  if (run?.taskId) {
-    if (run.status !== 'running') throw new Error('No active task run')
-    await new Tasks(options.controlDir).authorize(run, process.env.EZ_EXECUTOR_TRANSPORT === 'host')
-    if (process.env.EZ_EXECUTOR_TRANSPORT !== 'host') return startTaskExecutor(options)
-  } else await requireOwnerExecution(options.controlDir, options.runId)
-  if (!run?.taskId && options.eventSource !== undefined) throw new Error('Execution blocked: external-execution-unavailable')
+  // Routing is caller-owned: a restricted task run goes to the task runner
+  // unless the host transport must ship it across the boundary first.
+  if (options.taskRun && process.env.EZ_EXECUTOR_TRANSPORT !== 'host') return startTaskExecutor(options)
+  if (options.nativeSession && !/^[a-zA-Z0-9_-]+$/.test(options.runId)) throw new Error('Invalid native task run ID')
+  if (options.codexSandbox !== undefined && (options.codexSandbox !== 'external' || process.env.EZ_EXECUTOR_TRANSPORT !== 'local' || options.taskRun || executorKey(options.cli) !== 'codex')) throw new Error('External Codex sandbox requires an owner-authorized native local run')
   const outputDirectory = await mkdtemp(path.join(tmpdir(), 'ezenciel-agents-'))
   const key = executorKey(options.cli)
   const host = process.env.EZ_EXECUTOR_TRANSPORT === 'host'
   const gui = !host && key === 'codex-gui'
-  const nativeSession = !host && key === 'codex' && options.runId.startsWith('r_schedule_')
-  // Chat-mode experiment: only direct chat input at the engine boundary.
-  const applicationReminder = !host && (run?.application || run?.delivery)
-    ? '\n\n[Application channel] This is an owner-authorized application conversation. Send text replies using ezenciel-agents-message; stdout alone is not delivered. Outgoing file delivery, reactions and approval controls are unsupported here. Domain tools can retrieve private context from ezenciel-agents-schedule context under run.application.context; do not expose credentials from that data. The application scope is ' + JSON.stringify((run.application ?? run.delivery)!.scope) + '.'
-    : ''
-  const chatReminder = !host && !run?.taskId && run?.messageId !== undefined
-    ? '\n\n[Chat context] You are replying in chat. Send replies with ezenciel-agents-message --text "..."; your final answer alone is not delivered. Before lengthy tool or repository work, briefly acknowledge through that CLI. Keep chat responsive: use ezenciel-agents-schedule for long-running work and native subagents for useful independent parts. Decide when to delegate and what to send.'
-    : ''
-  const promptText = texts.join('\n\n') + applicationReminder + chatReminder
+  const nativeSession = !host && key === 'codex' && options.nativeSession === true
+  // Literal input plus the caller-provided trigger line. No coaching,
+  // tool/delegate/schedule advice, or workflow guidance.
+  const promptText = texts.join('\n\n') + (options.promptSuffix ?? '')
   const promptFile = path.join(outputDirectory, 'prompt.txt')
   await writeFile(promptFile, promptText, { encoding: 'utf8', mode: 0o600 })
 
   const adapter = resolveExecutor(options.cli)
   const command = adapter.command
-  const args = host || nativeSession || key === 'codex-gui' ? [] : adapter.buildArgs(options, promptFile, promptText)
-  const invocation = host
+  const denies = process.platform === 'darwin' && !host && !gui && options.codexSandbox !== 'external'
+    ? workspaceSiblingDenies(options.workspace) : []
+  // Codex must not apply a nested Seatbelt; this process is already confined.
+  const launchOptions = denies.length && command === 'codex' ? { ...options, codexSandbox: 'external' as const } : options
+  const args = host || nativeSession || key === 'codex-gui' ? [] : adapter.buildArgs(launchOptions, promptFile, promptText)
+  let invocation = host
     ? executorInvocation(process.execPath, ['--import', fileURLToPath(new URL('../node_modules/tsx/dist/loader.mjs', import.meta.url)), fileURLToPath(new URL('./host-executor-client.ts', import.meta.url)), options.controlDir, options.runId])
     : nativeSession
       ? executorInvocation(process.execPath, ['--import', fileURLToPath(new URL('../node_modules/tsx/dist/loader.mjs', import.meta.url)), fileURLToPath(new URL('./codex-session.ts', import.meta.url))])
     : gui
       ? executorInvocation(process.execPath, ['--import', fileURLToPath(new URL('../node_modules/tsx/dist/loader.mjs', import.meta.url)), fileURLToPath(new URL('./desktop-bridge.ts', import.meta.url))])
-      : executorInvocation(command, args)
+      : executorInvocation(resolveHostCommand(command, executorEnvironment().PATH), args)
   const environment = executorJobEnv(options)
+  if (!host && !gui && key === 'codex' && options.provider && !options.codexProvider)
+    throw new Error('Selected Codex provider is not configured for this agent')
+  if (!host && !gui && key === 'codex' && options.codexProvider) {
+    const provider = validateCodexProvider(options.codexProvider)
+    const secret = process.env[provider.envKey]
+    if (!secret) throw new Error(`Missing Codex provider credential ${provider.envKey}`)
+    environment[provider.envKey] = secret
+  }
   if (!host && !gui && command === 'codex') {
     // Share the existing authentication, never the user's memory/config/sessions.
     const base = path.join(options.controlDir, 'cli', 'codex')
@@ -282,16 +351,26 @@ export const startExecutorJob = async (
       try{await writeFile(path.join(home,'config.toml'),await readFile(path.join(base,'config.toml')),{flag:'wx',mode:0o600})}
       catch(error){if(!['ENOENT','EEXIST'].includes((error as NodeJS.ErrnoException).code || ''))throw error}
     }
-    // Tasks inherit this agent's auth binding, including an operator-provisioned
-    // private credential after host migration. Never replace an existing binding.
-    const authLinks = [[path.join(base, 'auth.json'), path.join(homedir(), '.codex', 'auth.json')]]
-    if (nativeSession) authLinks.push([path.join(home, 'auth.json'), path.join(base, 'auth.json')])
+    // Isolated agents keep auth in this CODEX_HOME. Host-capable may link the
+    // installer login. Never replace an existing binding.
+    const authLinks = process.env.EZ_ISOLATION === 'isolated'
+      ? nativeSession ? [[path.join(home, 'auth.json'), path.join(base, 'auth.json')]] : []
+      : [[path.join(base, 'auth.json'), path.join(homedir(), '.codex', 'auth.json')],
+        ...(nativeSession ? [[path.join(home, 'auth.json'), path.join(base, 'auth.json')]] : [])]
     for (const [link, target] of authLinks) {
       try { await symlink(target, link) }
       catch(error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error }
     }
     environment.CODEX_HOME = home
   }
+  if (denies.length) {
+    const profile = path.join(outputDirectory, 'workspace.sb')
+    await writeFile(profile, macosWorkspaceProfile(denies, [
+      options.controlDir, options.binDir, options.toolsHome, options.sharedWorkspace,
+      ...(options.additionalWorkspaces ?? []), outputDirectory,
+    ].filter((value): value is string => Boolean(value))), { mode: 0o600 })
+    invocation = { command: 'sandbox-exec', args: ['-f', profile, invocation.command, ...invocation.args] }
+  }
   const child = spawn(invocation.command, invocation.args, {
     cwd: options.workspace,
     env: environment,
@@ -307,7 +386,7 @@ export const startExecutorJob = async (
   })
   child.stdin?.end(host
     ? JSON.stringify({texts,options:{...options,onSession:undefined,codexSandbox:undefined}})
-    : nativeSession ? JSON.stringify({...options,onSession:undefined,prompt:promptText})
+    : nativeSession ? JSON.stringify({...launchOptions,onSession:undefined,prompt:promptText})
     : gui ? JSON.stringify({prompt:promptText,options:{...options,onSession:undefined}})
     : ['codex', 'claude'].includes(key) ? promptText : undefined)
   const timeout = options.timeoutMs > 0 ? setTimeout(() => terminateJob(child), options.timeoutMs) : undefined