@jc_stack/ez-agents 0.1.0-beta.34 → 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,8 +1,6 @@
 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'
@@ -21,13 +19,18 @@ 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
@@ -55,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 => {
@@ -76,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')} : {}),
   }
@@ -249,7 +255,7 @@ export const validateCodexProvider = (value: CodexProviderBinding): CodexProvide
 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_') || envKey.startsWith('PAGERDUTY_'))
+      envKey.startsWith('EZ_') || envKey.startsWith('TELEGRAM_'))
     throw new Error('Reserved Codex provider environment key')
   return envKey
 }
@@ -294,28 +300,19 @@ 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 })
 

package/src/files.ts

@@ -1,4 +1,4 @@
-import { mkdir, writeFile, realpath, stat } from 'node:fs/promises'
+import { mkdir, readFile, writeFile, realpath, stat } from 'node:fs/promises'
 import { randomUUID } from 'node:crypto'
 import path from 'node:path'
 
@@ -43,28 +43,55 @@ export const sanitizeFileName = (name: string): string => {
   return base || 'file'
 }
 
+// Runtime inbound staging lives under the agent control directory, never the
+// workspace mind folder. The engine resolves the absolute path regardless of
+// its working directory; the prompt carries no workspace-relative prefix.
 export const stageIncomingFile = async (
-  workspaceDir: string,
+  stagingRoot: string,
   fileName: string,
   bytes: Buffer,
 ): Promise<{ relativePath: string; fullPath: string; fileType: DetectedFileType }> => {
   const fileType = detectFileType(bytes)
   if (fileType === 'unknown' || bytes.length > 20 * 1024 * 1024)
     throw new Error('Unsupported or oversized attachment')
-  const inboxDir = path.join(workspaceDir, 'inbox')
-  await mkdir(inboxDir, { recursive: true, mode: 0o700 })
+  const attachmentsDir = path.join(stagingRoot, 'attachments')
+  await mkdir(attachmentsDir, { recursive: true, mode: 0o700 })
   const sanitized = sanitizeFileName(fileName)
   const targetName = `${randomUUID()}_${sanitized}`
-  await workspaceFile(workspaceDir, 'inbox', false)
-  const fullPath = path.join(inboxDir, targetName)
+  await workspaceFile(stagingRoot, 'attachments', false)
+  const fullPath = path.join(attachmentsDir, targetName)
   await writeFile(fullPath, bytes, { mode: 0o600 })
   return {
-    relativePath: path.join('inbox', targetName),
+    relativePath: path.join('attachments', targetName),
     fullPath,
     fileType,
   }
 }
 
+// Reads a staged attachment produced by stageIncomingFile. Relative paths
+// resolve under the first containing root (backward compatible with
+// workspace inbox staging); absolute paths must stay inside one of the roots.
+export const readStagedAttachment = async (roots: (string | undefined)[], file: string): Promise<Buffer> => {
+  const candidates = [...new Set(roots.filter((root): root is string => Boolean(root)))]
+  if (!path.isAbsolute(file)) {
+    for (const root of candidates) {
+      try { return await readFile(await workspaceFile(root, file)) } catch {}
+    }
+    throw new Error('File is outside the workspace')
+  }
+  const target = await realpath(file).catch(() => { throw new Error('File is outside the workspace') })
+  for (const root of candidates) {
+    const base = await realpath(root).catch(() => null)
+    if (!base) continue
+    const relative = path.relative(base, target)
+    if (!relative.startsWith('..') && !path.isAbsolute(relative) && relative !== '') {
+      if (!(await stat(target)).isFile()) throw new Error('Expected a regular file')
+      return readFile(target)
+    }
+  }
+  throw new Error('File is outside the workspace')
+}
+
 export const workspaceFile = async (workspace: string, file: string, regular = true): Promise<string> => {
   const root = await realpath(workspace)
   const target = await realpath(path.resolve(root, file))
@@ -76,12 +103,12 @@ export const workspaceFile = async (workspace: string, file: string, regular = t
 
 // Canonical native-engine attachment metadata for every inbound channel.
 export const MAX_INCOMING_ATTACHMENT_BYTES = 10 * 1024 * 1024
-export const stageChatAttachment = async (workspace: string, name: string, bytes: Buffer, comment: string) => {
+export const stageChatAttachment = async (stagingRoot: string, name: string, bytes: Buffer, comment: string) => {
   const type = detectFileType(bytes)
   if (!bytes.length || bytes.length > MAX_INCOMING_ATTACHMENT_BYTES || type === 'unknown' ||
     (type === 'text' && !/\.(txt|md|markdown)$/i.test(name))) throw new Error('Invalid application attachment: unsupported type or size')
-  const staged = await stageIncomingFile(workspace, name, bytes)
+  const staged = await stageIncomingFile(stagingRoot, name, bytes)
   const kind = ['jpeg', 'png', 'webp'].includes(staged.fileType) ? 'image' : 'document'
-  return { text: `[Attached ${kind} staged at ${staged.relativePath} (type: ${staged.fileType}, size: ${bytes.length} bytes)]${comment ? `\n\nCaption: ${comment}` : ''}`,
-    attachment: {path: staged.relativePath, type: staged.fileType}, fullPath: staged.fullPath }
+  return { text: `[Attached ${kind} staged at ${staged.fullPath} (type: ${staged.fileType}, size: ${bytes.length} bytes)]${comment ? `\n\nCaption: ${comment}` : ''}`,
+    attachment: {path: staged.fullPath, type: staged.fileType}, fullPath: staged.fullPath }
 }