@jc_stack/ez-agents 0.1.0-beta.34 → 0.1.0-beta.37

package/src/index.ts

@@ -4,14 +4,15 @@ import { TelegramSource } from './telegram-source.js'
 import { Tasks } from './tasks.js'
 import { taskRequests } from './task-rpc.js'
 import { executionBlockReason } from './execution-authority.js'
+import { serveDeliverySocket, createLedgerHandler, deliverySocketAlive, deliverySocketPath } from './delivery-socket.js'
+import { packageVersion } from './version.js'
 import {authorizeDeliveryContext} from './delivery-context.mjs'
 import { dispatchChannel } from './channel-backend.js'
 import { randomUUID } from 'node:crypto'
 import { stat } from 'node:fs/promises'
 import { Scheduler } from './scheduler.js'
-import { scheduledTasksText } from './scheduled-tasks.js'
+import { ownedScheduledTasks, scheduledTaskDetailText, scheduledTasksText } from './scheduled-tasks.js'
 import { taskWorkspace } from './task-workspace.js'
-import { queueUpdateAttention } from './update-attention.js'
 import { EventSources, eventRunId, batchReady, type SourceEvent } from './event-sources.js'
 import {removeTaskAttachments} from './task-attachments.js'
 import { dirname, join, basename } from 'node:path'
@@ -25,7 +26,7 @@ import { InboxStore, type IncomingItem } from './inbox.js'
 import { loadConfig, type Config } from './config.js'
 import { ControlStore, telegramOwner, ownerId, ownerEpoch } from './control-state.js'
 import { ApprovalStore } from './approval.js'
-import { startExecutorJob, terminateJob } from './executor.js'
+import { startExecutorJob, terminateJob, opencodeDataHome } from './executor.js'
 import { RunStore, type RunRecord } from './runs.js'
 import { splitTelegramText } from './reply.js'
 import { markdownToTelegramHtml, escapeHtml } from './format.js'
@@ -37,14 +38,13 @@ import { createConversationMenu } from './conversation-menu.js'
 import { createAiMenu, mainCommands, mainKeyboard } from './menu.js'
 import { chatPreset, initialPreset, persistedPreset, presetLabel, statusPreset } from './ai.js'
 import { discoverDefaults } from './client-defaults.js'
-import { initializeWorkspace } from './workspace.js'
+import { runPromptSuffix } from './prompt-suffix.js'
 import { softwareStatus } from './software-status.js'
-import { PagerDutyStocksMonitor } from './pagerduty.js'
 
 export const createRelay = (config: Config, launch = startExecutorJob) => {
   const safeError = (error: unknown): string => {
     let message = error instanceof Error ? error.message : typeof error === 'string' ? error : 'Unknown error'
-    for (const secret of [config.channelBackendToken, config.telegramBotToken, config.geminiApiKey, config.openaiApiKey, config.pagerDutyRoutingKey]) {
+    for (const secret of [config.channelBackendToken, config.telegramBotToken, config.geminiApiKey, config.openaiApiKey]) {
       if (secret) message = message.replaceAll(secret, '[redacted]')
     }
     return message
@@ -70,19 +70,11 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
   let taskTimer: ReturnType<typeof setInterval> | undefined
   let drainTimer: ReturnType<typeof setInterval> | undefined
   const codexHome = join(config.controlDir, 'cli', 'codex')
-  const conversationMenu = createConversationMenu(control, runs)
-  const aiMenu = createAiMenu(control, config.executorCli, undefined, config.workspace, codexHome)
+  const conversationMenu = createConversationMenu(control)
+  const aiMenu = createAiMenu(control, config.executorCli, undefined, config.workspace, codexHome,
+    undefined, opencodeDataHome(config.controlDir))
   const durableWorkerChoice = () => control.captureChoice(aiMenu.initial)
   const binDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'bin')
-  const pagerDuty = config.pagerDutyRoutingKey && config.pagerDutyStocksHealthUrl
-    ? new PagerDutyStocksMonitor({
-      routingKey: config.pagerDutyRoutingKey,
-      healthUrl: config.pagerDutyStocksHealthUrl,
-      pollMs: config.pagerDutyPollMs!,
-      failureThreshold: config.pagerDutyFailureThreshold!,
-      onError: (error) => console.error('PagerDuty Stocks health check failed', safeError(error)),
-    })
-    : undefined
 
   let activeTypingTimer: ReturnType<typeof setInterval> | null = null
   let activeBackend = false
@@ -112,6 +104,19 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
     controlDir: config.controlDir, workspace: config.workspace, initial: aiMenu.initial,
     aiControls: aiMenu,
     wake: () => { void drainSources().catch(error => console.error('Application queue unavailable', safeError(error))) },
+    createTelegramPairing: async (bindingId, owner) => {
+      const username = bot?.botInfo?.username
+      if (!username || !/^[A-Za-z][A-Za-z0-9_]{4,31}$/.test(username))
+        throw new Error('Telegram connection is unavailable')
+      const pairing = await control.createApplicationTelegramPairing(bindingId, owner)
+      if (!pairing) return { connected: true } as const
+      return {
+        connected: false as const,
+        url: `https://t.me/${username}?start=${pairing.token}`,
+        expiresAt: pairing.expiresAt,
+      }
+    },
+    telegramAvailable: () => Boolean(bot?.botInfo?.username),
     cancel: id => withStartLock(async () => {
       const run = await runs.get(id)
       if (run?.status === 'queued') await runs.patch(id, {status:'cancelled',endedAt:new Date().toISOString()})
@@ -176,7 +181,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
         catch { await runs.patch(run.id, { status: 'cancelled', endedAt: new Date().toISOString() }); await releaseExternal(run); return }
       }
       if (config.channelBackendUrl) {
-        if (run.external || run.taskId || run.scheduled || run.id.startsWith('r_update_')) { await runs.patch(run.id, { status: 'failed' }); await releaseExternal(run); return }
+        if (run.external || run.taskId || run.scheduled) { await runs.patch(run.id, { status: 'failed' }); await releaseExternal(run); return }
         activeBackend = true
         await runs.patch(run.id, { status: 'running', backendSubmitted: true })
         void dispatchChannel(config, run).then(async reply => {
@@ -224,14 +229,13 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
         const launchStarted = performance.now()
         const started = await runs.patch(run.id, { status: 'running', startedAt: new Date().toISOString() })
         if (!started.execution && !run.taskId) throw new Error('Legacy queued work has no pinned AI. Resend the request after /new.')
-        const maintenanceWakeup = run.id.startsWith('r_update_')
-        const startsOwnSession = Boolean(run.external || run.taskId || run.scheduled || maintenanceWakeup)
+        const startsOwnSession = Boolean(run.external || run.taskId || run.scheduled)
         const session = startsOwnSession
           ? { sessionId: randomUUID(), hasStarted: false, nativeSessionId: undefined }
           : await control.executionSession(started.execution!)
         const selected = run.taskId ? (started.execution?.preset.cli === 'codex' ? started.execution.preset : initialPreset('codex')) : started.execution!.preset
         const { child, cleanup } = await launch(texts, {
-          workspace: run.scheduled ? await taskWorkspace(config.workspace,run.id) : config.workspace,
+          workspace: run.scheduled ? await taskWorkspace(config.controlDir,run.id) : config.workspace,
           timeoutMs: config.executorTimeoutMs,
           repairEnabled: config.repairEnabled,
           runId: started.id,
@@ -245,8 +249,10 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
           codexSandbox: !run.taskId && selected.cli === 'codex' ? config.codexSandbox : undefined,
           sessionId: session.nativeSessionId || session.sessionId,
           isResume: session.hasStarted,
-          eventSource: run.external?.sourceId,
-          onSession: run.external || run.taskId || maintenanceWakeup ? undefined : async (id) => { await runs.patch(run.id,{nativeSessionId:id}); if (!run.scheduled) await control.saveNativeSession(session.sessionId,id) },
+          promptSuffix: runPromptSuffix(started),
+          taskRun: Boolean(run.taskId),
+          nativeSession: Boolean(run.scheduled),
+          onSession: run.external || run.taskId ? undefined : async (id) => { await runs.patch(run.id,{nativeSessionId:id}); if (!run.scheduled) await control.saveNativeSession(session.sessionId,id) },
         })
         const executionStarted = performance.now()
         // Attach before disk writes: a fast child can close while PID persistence
@@ -385,7 +391,6 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       for (const task of await tasks.list()) if (task.state === 'pending' || task.state === 'active' || task.unwatchPending) {
         try { await tasks.decide(task.id) } catch { /* Failed or stale grants cannot launch. */ }
       }
-      if (telegramOwner(owner)) await queueUpdateAttention(config.controlDir,owner,runs,await durableWorkerChoice())
       }
       for (const source of config.channelBackendUrl ? [] : await sources.available(owner)) {
         try {
@@ -449,10 +454,6 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
     if (message?.media_group_id) item.text = `[Telegram album: ${message.media_group_id}]\n${item.text}`
     if (message && (message.chat.type === 'group' || message.chat.type === 'supergroup'))
       item.text = `[Telegram sender ${message.from?.id}, name ${JSON.stringify(message.from?.first_name)}]\n${item.text}`
-    if (message && !message.text && message.reply_to_message) {
-      const quoted = message.reply_to_message
-      item.text = `[Quoted message ${quoted.message_id}]: ${quoted.text || quoted.caption || '[media]'}\n\n${item.text}`
-    }
     collected.push(item)
   }
   const scheduleIntake = () => {
@@ -565,7 +566,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
             ])
             console.info('run reaction sent', { run_id: item.runId, emoji })
           } else if (item.type === 'document' && item.documentPath) {
-            const docPath = await workspaceFile(origin?.scheduled ? await taskWorkspace(config.workspace,origin.id) : config.workspace, item.documentPath)
+            const docPath = await workspaceFile(origin?.scheduled ? await taskWorkspace(config.controlDir,origin.id) : config.workspace, item.documentPath)
             await paceSend()
             await authorizeChannelDelivery()
             attemptedDelivery = true
@@ -623,11 +624,34 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
     })().finally(() => { outboxWork = undefined }))
   }
 
+  // Delivery socket: cross-process producers (engine children, plugin
+  // children, host executor, CLIs) enqueue and query the memory ledger
+  // through the shared handler in delivery-socket.ts. The pump below stays
+  // the single delivery executor; the socket only admits work into it.
+  let deliveryServer: { socketPath: string; stop: () => Promise<void> } | null = null
+  const handleDeliveryOp = createLedgerHandler(config.controlDir, {
+    wake: () => { void drainOutbox() },
+    status: () => ({
+      polling: Boolean(bot?.isRunning()),
+      applicationOnly: !telegramEnabled,
+      telegramConfigured: config.telegramBotToken !== '',
+      version: packageVersion,
+    }),
+  })
+
   const checkOwner = async (ctx: Context): Promise<boolean> => {
     if (!ctx.from || ctx.from.is_bot || ctx.message?.sender_chat) return false
     const state = await control.status()
     if (!telegramOwner(state.owner)) {
       if (ctx.chat?.type !== 'private') return false
+      const applicationToken = ctx.message?.text?.trim().match(/^\/start(?:@[A-Za-z0-9_]+)?\s+([A-Za-z0-9_-]{43})$/)?.[1]
+      if (applicationToken) {
+        const linked = await applicationChannel.claimTelegramConnection(applicationToken, ctx.from.id, ctx.chat.id)
+        await ctx.reply(linked
+          ? 'Telegram is connected to your Ez agent. You can keep chatting here.'
+          : 'This Telegram connection link expired or is no longer valid. Create a new one in the connected application.', { link_preview_options: { is_disabled: true } })
+        return false
+      }
       const result = await control.requestPairing(ctx.from.id, ctx.chat.id)
       if (result === 'requested')
         await ctx.reply('Owner approval is pending. Confirm this request through the local setup assistant.')
@@ -654,18 +678,29 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
   const commands = [...mainCommands, ...(launcher ? [{ command: launcher.command, description: launcher.label }] : [])]
   const controlCommand = (text?: string) => /^\/rename(?:@[a-zA-Z0-9_]+)?(?:\s|$)/.test(text?.trim() ?? '')
     ? '/rename' : text?.trim().replace(/@[a-zA-Z0-9_]+$/, '')
+  const tasksCommand = (text?: string): number | undefined | null => {
+    const match = text?.trim().match(/^\/tasks(?:@[a-zA-Z0-9_]+)?(?:\s+([1-9]\d*))?$/)
+    return match ? (match[1] ? Number(match[1]) : undefined) : null
+  }
+  const isTasksCommand = (text?: string): boolean => /^\/tasks(?:@[a-zA-Z0-9_]+)?(?:\s|$)/.test(text?.trim() ?? '')
   const statusKeyboard = () => new InlineKeyboard()
     .text('Stop active work', 'menu:stop').text('Cancel queue', 'menu:cancel').row()
-    .text('Retry failed incoming message', 'menu:retry').row()
-    .text('Scheduled tasks', 'menu:scheduled-tasks')
+    .text('Retry failed incoming message', 'menu:retry')
   const scheduledTasks = async () => {
     const owner = (await control.status()).owner
     if (!owner) return 'Scheduled tasks\n\nNo paired owner.'
     // This intentionally uses the reader that does not create a schedules directory.
-    return scheduledTasksText(await scheduler.listActiveReadOnly(await runs.list()), owner)
+    const active = await scheduler.listActiveReadOnly(await runs.list())
+    return { owner, active, text: scheduledTasksText(active, owner) }
   }
-  const replyScheduledTasks = async (ctx: Context) => {
-    for (const part of splitTelegramText(await scheduledTasks())) await ctx.reply(part)
+  const replyScheduledTasks = async (ctx: Context, number?: number) => {
+    const result = await scheduledTasks()
+    const text = typeof result === 'string' ? result : number === undefined ? result.text : (() => {
+      const owned = ownedScheduledTasks(result.active, result.owner)
+      const schedule = owned[number - 1]
+      return schedule ? scheduledTaskDetailText(schedule, number, owned.length) : `Scheduled task ${number} was not found. Use /tasks to list active tasks.`
+    })()
+    for (const part of splitTelegramText(text)) await ctx.reply(part)
   }
   const statusText = async () => {
     const running = await runs.running(false)
@@ -694,7 +729,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       '🟢 Ez is online',
       '',
       'System',
-      ...await softwareStatus(config.controlDir),
+      ...await softwareStatus(config.controlDir, config.isolation),
       `AI: ${selected.name} (${presetLabel(displayedSelected)})`,
       '',
       'Work',
@@ -771,7 +806,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
     }
     const message = ctx.message
     const command = controlCommand(message?.text)
-    if (command && [...commands, ...aliases].map((c) => `/${c.command}`).concat('/menu', ...retiredCommands).includes(command)) return next()
+    if ((command && [...commands, ...aliases].map((c) => `/${c.command}`).concat('/menu', ...retiredCommands).includes(command)) || tasksCommand(message?.text) !== null || isTasksCommand(message?.text)) return next()
     const ordinary = message && (message.text || message.photo || message.document || message.voice)
     const approval = ctx.callbackQuery?.data?.startsWith('approval:')
     if (!ordinary && !approval) return next()
@@ -815,6 +850,16 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       return
     }
 
+    const taskNumber = tasksCommand(ctx.message.text)
+    if (taskNumber !== null) {
+      await replyScheduledTasks(ctx, taskNumber)
+      return
+    }
+    if (isTasksCommand(ctx.message.text)) {
+      await ctx.reply('Usage: /tasks [number]. Use /tasks to list active tasks.')
+      return
+    }
+
     if (text === '/help') {
       await ctx.reply([...commands, ...aliases.filter((a) => !commands.some((c) => c.command === a.command))]
         .map((c) => `/${c.command} — ${c.description}`).join('\n'))
@@ -881,19 +926,8 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       return
     }
 
-    // Quoted reply context forwarding
-    let promptText = ctx.message.text
-    if (ctx.message.reply_to_message) {
-      const quoted = ctx.message.reply_to_message
-      const quotedText = ('text' in quoted && quoted.text) || ('caption' in quoted && quoted.caption) || ''
-      const quotedSender = quoted.from?.is_bot ? 'Agent' : 'Owner'
-      if (quotedText) {
-        promptText = `[Quoted message from ${quotedSender} (ID: ${quoted.message_id})]: "${quotedText}"\n\n${promptText}`
-      }
-    }
-
     collectItem({
-      text: promptText,
+      text: ctx.message.text,
       messageId: ctx.message.message_id,
       updateId: ctx.update.update_id,
       chatId: ctx.chat.id,
@@ -911,7 +945,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       const fileUrl = `https://api.telegram.org/file/bot${config.telegramBotToken}/${fileInfo.file_path}`
       const buffer = await downloadTelegramFile(fileUrl)
       const fileName = sanitizeFileName(basename(fileInfo.file_path) || 'photo.jpg')
-      const staged = await stageChatAttachment(config.workspace, fileName, buffer, ctx.message.caption ?? '')
+      const staged = await stageChatAttachment(config.controlDir, fileName, buffer, ctx.message.caption ?? '')
       collectItem({
         text: staged.text,
         attachment: staged.attachment,
@@ -938,7 +972,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       const fileUrl = `https://api.telegram.org/file/bot${config.telegramBotToken}/${fileInfo.file_path}`
       const buffer = await downloadTelegramFile(fileUrl)
       const fileName = sanitizeFileName(doc.file_name || basename(fileInfo.file_path) || 'document.bin')
-      const staged = await stageChatAttachment(config.workspace, fileName, buffer, ctx.message.caption ?? '')
+      const staged = await stageChatAttachment(config.controlDir, fileName, buffer, ctx.message.caption ?? '')
       collectItem({
         text: staged.text,
         attachment: staged.attachment,
@@ -1104,6 +1138,8 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
     shuttingDown = true
     runtimeStarted = false
     pollingAbort.abort()
+    await deliveryServer?.stop().catch(() => {})
+    deliveryServer = null
     await applicationChannel.stop()
     wakePollRetry?.()
     if (intakeTimer) clearTimeout(intakeTimer)
@@ -1119,7 +1155,6 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
     })
     await Promise.all(completions)
     await Promise.all([taskWork, outboxWork].map(work => work?.catch(() => {})))
-    pagerDuty?.stop()
     try {
       if (bot?.isRunning()) await bot.stop()
     } finally {
@@ -1130,10 +1165,19 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
   const start = async () => {
     let failed = false
     try {
-      await initializeWorkspace(config.workspace)
+      // Workspace seeding and managed-block replacement happen at install or
+      // upgrade only; relay startup never writes the agent workspace.
+      // The delivery socket is the cross-process ledger transport and the
+      // single-relay guard (replacing relay.lock): a live sibling answers the
+      // ping and this relay refuses to split-brain the agent.
+      if (await deliverySocketAlive(deliverySocketPath(config.controlDir)).catch(() => false))
+        throw new Error(`Another relay owns ${config.controlDir}; stop it before starting a second one`)
+      const deliveryTcpPort = Number(process.env.EZ_DELIVERY_TCP_PORT ?? '')
+      deliveryServer = await serveDeliverySocket(config.controlDir, handleDeliveryOp, {
+        ...(Number.isSafeInteger(deliveryTcpPort) && deliveryTcpPort >= 1024 && deliveryTcpPort <= 65535 ? { tcpPort: deliveryTcpPort } : {}),
+      })
       if (config.applicationPort) await applicationChannel.listen(config.applicationPort, config.applicationHost)
       runtimeStarted = true
-      pagerDuty?.start()
       const owner = (await control.status()).owner
       if (telegramEnabled && telegramOwner(owner) && !config.channelBackendUrl) await telegramSource!.start(owner!)
       await scheduler.recover(runs)
@@ -1210,7 +1254,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       }
     }
   }
-  return { bot: bot!, isRunning: () => telegramEnabled ? Boolean(bot?.isRunning()) : runtimeStarted, start, stop, drainOutbox, drainInbox, drainSources, drainTaskRequests, applicationChannel }
+  return { bot: bot!, telegramEnabled, isRunning: () => telegramEnabled ? Boolean(bot?.isRunning()) : runtimeStarted, start, stop, drainOutbox, drainInbox, drainSources, drainTaskRequests, applicationChannel }
 }
 
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {

package/src/install-tools.mjs

@@ -4,6 +4,10 @@ import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { createHash, randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
+import { createServer } from 'node:net';
+import { parseEnv } from 'node:util';
+import { callDeliverySocket } from './delivery-socket-client.mjs';
+import { ledgerOverlayName, ledgerOverlayYaml } from './ledger-endpoint.mjs';
 
 const root=fileURLToPath(new URL('../',import.meta.url));
 const read=async file=>JSON.parse(await fs.readFile(file,'utf8'));
@@ -52,49 +56,120 @@ export async function installationStatus(deployment) {
   let isolated=false;
   try { isolated=(await read(path.join(deployment,'agent.json'))).isolation==='isolated'; } catch { isolated=false; }
   const runtimeReady=Boolean(relay?.polling&&fresh(relay,20000)&&(isolated||fresh(host,15000)));
+  // Delivery receipts live in relay memory and are re-authorized server-side;
+  // ask the running relay. A restart drops receipts by design.
   let reply=null;
-  if(paired)for(const name of await fs.readdir(path.join(control,'outbox')).catch(e=>{if(e.code==='ENOENT')return [];throw e;})) {
-    if(!name.endsWith('.sent.json'))continue;
-    const item=await read(path.join(control,'outbox',name));
-    if(!/^tg_\d+$/.test(item.runId||'')||item.chatId!==owner.telegramChatId||(item.type&&item.type!=='message')||!Array.isArray(item.receipt?.messageIds)||!item.receipt.messageIds.length||!item.receipt.messageIds.every(n=>Number.isSafeInteger(n)&&n>0))continue;
-    const delivered=Date.parse(item.receipt.deliveredAt);if(!Number.isFinite(delivered)||delivered<Date.parse(owner.pairedAt)||delivered>Date.now())continue;
-    const r=await read(path.join(control,'runs',item.runId+'.json')).catch(absent);
-    if(r?.status==='completed'&&!r.external&&r.chatId===owner.telegramChatId&&Number.isSafeInteger(r.telegramUserId)&&r.telegramUserId>0&&(owner.kind==='group'||r.telegramUserId===owner.telegramUserId)&&(!reply||delivered>Date.parse(reply.deliveredAt)))reply={runId:item.runId,messageIds:item.receipt.messageIds,deliveredAt:item.receipt.deliveredAt};
-  }
+  if(paired)reply=(await callDeliverySocket(path.join(control,'delivery.sock'),{op:'latestReply'},2000).catch(()=>null))?.reply??null;
   return {deployment,configured,runtimeReady,ownerPaired:paired,telegramReplyVerified:Boolean(reply),reply,
     stage:!configured?'not-configured':!runtimeReady?'runtime-offline':!paired?'awaiting-owner':!reply?'awaiting-telegram-reply':'ready-for-telegram-plugin-request',
-    note:'Read-only: a saved receipt is historical delivery evidence, not a fresh live probe or proof of reboot persistence. Request plugins through the working Telegram conversation.'};
+    note:'Read-only: a live receipt from the running relay is delivery evidence; it is not retained across a relay restart. Request plugins through the working Telegram conversation.'};
+}
+// Existing host-capable deployments created before the loopback endpoint need
+// one idempotent migration: a published loopback port in docker.env plus the
+// generated overlay that maps it. New agents receive both at create time.
+const envLine = (text, key, value) => {
+  if (/['\r\n\0]/.test(value)) throw Error('Unsafe deployment value');
+  const line = `${key}='${value}'`;
+  const pattern = new RegExp(`^${key}=.*$`, 'm');
+  return pattern.test(text) ? text.replace(pattern, () => line) : text.replace(/\n*$/, '\n') + line + '\n';
+}
+
+const freeLoopbackPort = async (start = 20000) => {
+  for (let port = start; port < start + 500 && port <= 65535; port++) {
+    const free = await new Promise(resolve => {
+      const probe = createServer();
+      probe.once('error', () => resolve(false));
+      probe.listen(port, '127.0.0.1', () => probe.close(() => resolve(true)));
+    });
+    if (free) return port;
+  }
+  throw Error('No free loopback port in the deployment range');
+};
+
+const ledgerPortStart = name => 20000 + createHash('sha256').update(name).digest().readUInt16BE(0) % 10000;
+
+export async function migrateLedger({ deployment } = {}) {
+  if (!path.isAbsolute(deployment || '')) throw Error('Supply --deployment with the absolute deployment directory');
+  const directory = path.resolve(deployment), envFile = path.join(directory, 'docker.env');
+  const text = await fs.readFile(envFile, 'utf8').catch(error => { if (error.code === 'ENOENT') throw Error('Deployment docker.env not found'); throw error; });
+  const values = parseEnv(text);
+  if (!/^[a-z0-9][a-z0-9_-]{0,62}$/.test(values.COMPOSE_PROJECT_NAME || '')) throw Error('Invalid deployment COMPOSE_PROJECT_NAME');
+  if (values.EZ_ISOLATION === 'isolated' || values.EZ_EXECUTOR_TRANSPORT === 'local')
+    return { ok: true, deployment: directory, changed: false, note: 'Isolated deployment; no host ledger endpoint is needed.' };
+  if (!values.COMPOSE_FILE) throw Error('Deployment COMPOSE_FILE not found');
+  const overlay = path.join(directory, ledgerOverlayName);
+  const files = values.COMPOSE_FILE.split(path.delimiter).filter(Boolean);
+  const configured = values.EZ_DELIVERY_TCP_PORT !== undefined && files.includes(overlay) &&
+    await fs.stat(overlay).then(info => info.isFile(), () => false);
+  if (configured) return { ok: true, deployment: directory, changed: false, port: Number(values.EZ_DELIVERY_TCP_PORT) };
+  const port = values.EZ_DELIVERY_TCP_PORT !== undefined ? Number(values.EZ_DELIVERY_TCP_PORT) : await freeLoopbackPort(ledgerPortStart(values.COMPOSE_PROJECT_NAME));
+  if (!Number.isSafeInteger(port) || port < 1024 || port > 65535) throw Error('Invalid EZ_DELIVERY_TCP_PORT');
+  const next = envLine(envLine(text, 'EZ_DELIVERY_TCP_PORT', String(port)), 'COMPOSE_FILE', [...new Set([...files, overlay])].join(path.delimiter));
+  // Publish the overlay before docker.env references it: a crash in between
+  // leaves an unreferenced file instead of a deployment Compose cannot start.
+  await fs.writeFile(overlay, ledgerOverlayYaml(), { mode: 0o600 });
+  const temporary = `${envFile}.${process.pid}.tmp`;
+  await fs.writeFile(temporary, next, { mode: 0o600 });
+  await fs.rename(temporary, envFile);
+  return { ok: true, deployment: directory, changed: true, port, overlay };
 }
+
 async function fingerprintOf(source,invoke) {
   const listing=JSON.parse(await invoke('npm',['pack','--dry-run','--ignore-scripts','--json'],{cwd:source}));
   const hash=createHash('sha256');
   for(const f of listing[0].files){const file=path.resolve(source,f.path);if(!file.startsWith(source+path.sep))throw Error('Invalid package path');const data=await fs.readFile(file);hash.update(JSON.stringify([f.path,f.mode,data.length]));hash.update(data);}
   return hash.digest('hex');
 }
-export async function build({home=defaultHome(),source=root},invoke=run) {
+// Source-checkout builds are RCs. The reviewed commit is the only SHA that may
+// label an installable image, so a dirty tree can never become one and /status
+// never falls back to the bare package version on a deployment.
+export const rcLabel = /^\d+\.\d+\.\d+-beta\.\d+\.rc\.[1-9]\d*$/;
+async function buildIdentity(source,label,invoke) {
+  const git=async args=>{try{return await invoke('git',['-C',source,...args]);}catch{return undefined;}};
+  // The package root itself must be the checkout root; a tarball unpacked
+  // inside an unrelated repository is not a source checkout.
+  const top=await git(['rev-parse','--show-toplevel']);
+  const atRoot=Boolean(top)&&await fs.realpath(top).then(value=>value===source,()=>false);
+  if(!atRoot) {
+    if(label!==undefined)throw Error('--label requires a git checkout so the RC pins the reviewed commit');
+    return {};
+  }
+  if(label===undefined)throw Error('A source checkout requires --label X.Y.Z-beta.N.rc.M; commit, push and open the PR first');
+  if(!rcLabel.test(label))throw Error('RC label must look like X.Y.Z-beta.N.rc.M');
+  if((await git(['status','--porcelain']))!=='')throw Error('Commit the reviewed source before an RC build; uncommitted work cannot be installed as an RC');
+  const sha=await git(['rev-parse','HEAD']);
+  if(!/^[a-f0-9]{40}$/.test(sha||''))throw Error('RC builds require the reviewed commit SHA');
+  return {label,sha};
+}
+export async function build({home=defaultHome(),source=root,label},invoke=run) {
   source=await fs.realpath(source);
-  const fingerprint=await fingerprintOf(source,invoke),image='ezenciel-agents:install-'+fingerprint.slice(0,24);
-  const dir=path.join(path.resolve(home),'builds',fingerprint);await fs.mkdir(dir,{recursive:true,mode:0o700});
+  const identity=await buildIdentity(source,label,invoke);
+  const fingerprint=await fingerprintOf(source,invoke);
+  const artifact=createHash('sha256').update(JSON.stringify([fingerprint,identity.label??'',identity.sha??''])).digest('hex');
+  const image='ezenciel-agents:install-'+artifact.slice(0,24);
+  const dir=path.join(path.resolve(home),'builds',artifact);await fs.mkdir(dir,{recursive:true,mode:0o700});
   const lock=path.join(dir,'lock'),receipt=path.join(dir,'status.json'),log=path.join(dir,'build.log');
   let handle;
   try{handle=await fs.open(lock,'wx',0o600);}catch(e){if(e.code!=='EEXIST')throw e;return {state:'busy-or-interrupted',image,log,note:'An existing build owns this artifact. Inspect its status/log and owning process; do not start another build or remove a live lock.'};}
   try {
-    await handle.writeFile(JSON.stringify({pid:process.pid,source,image}));
+    await handle.writeFile(JSON.stringify({pid:process.pid,source,image,...identity}));
     const prior=await read(receipt).catch(absent);
     if(prior?.state==='completed')try{if(await invoke('docker',['image','inspect','--format','{{.Id}}',image])===prior.imageId)return {...prior,reused:true};}catch{/* Image was removed; rebuild under the same exclusive lock. */}
-    await atomic(receipt,{state:'building',pid:process.pid,source,image,log});
-    console.error(JSON.stringify({state:'building',image,log}));
+    await atomic(receipt,{state:'building',pid:process.pid,source,image,log,...identity});
+    console.error(JSON.stringify({state:'building',image,log,...identity}));
+    const buildArgs=identity.label?['--build-arg',`BUILD_TAG=${identity.label}`,'--build-arg',`BUILD_SHA=${identity.sha}`]:[];
+    const tags=[image,...(identity.label?[`ezenciel-agents:${identity.label}`]:[])];
     const output=await fs.open(log,'a',0o600);
-    try{await invoke('docker',['build','--progress','plain','--target','runtime','-t',image,source],{log:output.fd,timeout:3600000});}finally{await output.close();}
+    try{await invoke('docker',['build','--progress','plain','--target','runtime',...buildArgs,...tags.flatMap(t=>['-t',t]),source],{log:output.fd,timeout:3600000});}finally{await output.close();}
     if(await fingerprintOf(source,invoke)!==fingerprint)throw Error('Package changed during build; keep the source stable and retry');
-    const result={state:'completed',source,image,imageId:await invoke('docker',['image','inspect','--format','{{.Id}}',image]),log};await atomic(receipt,result);return result;
-  }catch(e){await atomic(receipt,{state:'failed',source,image,log,error:e.message});throw e;}
+    const result={state:'completed',source,image,imageId:await invoke('docker',['image','inspect','--format','{{.Id}}',image]),log,...identity};await atomic(receipt,result);return result;
+  }catch(e){await atomic(receipt,{state:'failed',source,image,log,error:e.message,...identity});throw e;}
   finally{await handle.close();await fs.rm(lock);}
 }
 export async function main(args) {
   const [action,...rest]=args;const options={};
-  if(!action||action==='--help'){console.log(JSON.stringify({commands:['preflight --executor <name-or-absolute-path> [--home PATH]','build [--home PATH]','status --deployment PATH'],note:'Host prerequisites and main-agent diagnostics only. Initialize an empty registry; verify Telegram before asking the installed agent to add plugins.'}));return;}
-  for(let i=0;i<rest.length;i+=2){if(!['--home','--executor','--deployment'].includes(rest[i])||!rest[i+1]||Object.hasOwn(options,rest[i].slice(2)))throw Error('Invalid arguments');options[rest[i].slice(2)]=rest[i+1];}
-  const allowed={preflight:['home','executor'],build:['home'],status:['deployment']};if(!allowed[action]||Object.keys(options).some(k=>!allowed[action].includes(k)))throw Error('Invalid action/options');
-  const result=action==='preflight'?await preflight(options):action==='build'?await build(options):await installationStatus(options.deployment);console.log(JSON.stringify(result));if(result.ok===false)process.exitCode=1;
+  if(!action||action==='--help'){console.log(JSON.stringify({commands:['preflight --executor <name-or-absolute-path> [--home PATH]','build [--home PATH] [--label X.Y.Z-beta.N.rc.M]','migrate-ledger --deployment PATH','status --deployment PATH'],note:'Source checkouts build RCs only: commit and open the PR first, then pass the next --label. migrate-ledger adds the loopback host endpoint to an existing host-capable deployment. Host prerequisites and main-agent diagnostics only; initialize an empty registry and verify Telegram before asking the installed agent to add plugins.'}));return;}
+  for(let i=0;i<rest.length;i+=2){if(!['--home','--executor','--deployment','--label'].includes(rest[i])||!rest[i+1]||Object.hasOwn(options,rest[i].slice(2)))throw Error('Invalid arguments');options[rest[i].slice(2)]=rest[i+1];}
+  const allowed={preflight:['home','executor'],build:['home','label'],'migrate-ledger':['deployment'],status:['deployment']};if(!allowed[action]||Object.keys(options).some(k=>!allowed[action].includes(k)))throw Error('Invalid action/options');
+  const result=action==='preflight'?await preflight(options):action==='build'?await build(options):action==='migrate-ledger'?await migrateLedger(options):await installationStatus(options.deployment);console.log(JSON.stringify(result));if(result.ok===false)process.exitCode=1;
 }

package/src/ledger-endpoint.d.mts

@@ -0,0 +1,2 @@
+export declare const ledgerOverlayName: string
+export declare const ledgerOverlayYaml: () => string

package/src/ledger-endpoint.mjs

@@ -0,0 +1,17 @@
+// One source for the host-capable ledger overlay: agent creation, the
+// deployment migration and its tests must emit the same compose fragment.
+export const ledgerOverlayName = 'ledger.compose.yaml'
+
+export const ledgerOverlayYaml = () => [
+  '# Host-capable execution: on Docker Desktop/OrbStack the control-volume',
+  '# Unix socket is not connectable from the host, so the relay serves its',
+  '# memory ledger on this published loopback port and requests authenticate',
+  '# with the per-run token in the control directory.',
+  'services:',
+  '  relay:',
+  '    environment:',
+  '      EZ_DELIVERY_TCP_PORT: ${EZ_DELIVERY_TCP_PORT:?}',
+  '    ports:',
+  '      - "127.0.0.1:${EZ_DELIVERY_TCP_PORT:?}:${EZ_DELIVERY_TCP_PORT:?}"',
+  '',
+].join('\n')

package/src/menu.ts

@@ -13,12 +13,13 @@ export const mainCommands = [
   { command: 'rename', description: 'Rename current conversation' },
   { command: 'ai', description: 'Choose AI' },
   { command: 'status', description: 'Work status' },
+  { command: 'tasks', description: 'Scheduled tasks' },
 ]
 
 export const mainKeyboard = () => new InlineKeyboard()
   .text('New conversation', 'menu:new').text('Conversations', 'menu:chats').row()
-  .text('Choose AI', 'menu:ai')
-  .text('Work status', 'menu:status')
+  .text('Choose AI', 'menu:ai').row()
+  .text('Work status', 'menu:status').text('Scheduled tasks', 'menu:scheduled-tasks')
 
 const clientLabel = (cli: string) => cli === 'codex-gui' ? 'codex-gui (desktop)' : cli
 
@@ -29,10 +30,14 @@ const matchesModel = (preset: AiPreset, model: ModelChoice) =>
 // Short-lived opaque button IDs: no model names or executable arguments from callbacks.
 // These are operational settings, not a second conversational/agent loop.
 export const createAiMenu = (control: ControlStore, cli: string, catalog = readModels, workspace = process.cwd(), codexHome?: string,
-  isInstalled = installed) => {
+  isInstalled = installed, opencodeDataHome?: string) => {
   const initial = chatPreset(cli)
   const host = process.env.EZ_EXECUTOR_TRANSPORT === 'host'
   if (host) catalog = async () => JSON.parse(await readFile(path.join(process.env.EZ_CONTROL_DIR!, 'host-executor/models.json'),'utf8'))
+  // Local execution runs Codex with CODEX_HOME set to the agent-bound control
+  // directory, but the default catalog probed the process home instead. Bind it
+  // to the same agent-bound home so /ai lists the models Codex can actually run.
+  else if (codexHome && catalog === readModels) catalog = () => readModels(undefined, isInstalled, codexHome, undefined, opencodeDataHome, undefined, process.env.EZ_CONTROL_DIR)
   const refresh = async () => control.syncClientPresets(initial, host ? [] : await discoverDefaults(workspace, { codexHome }))
   const validate = async (preset: AiPreset) => {
     assertEffort(preset.effort, preset.model, preset.cli)

package/src/message-history.ts

@@ -1,11 +1,12 @@
-import { readFile, readdir } from 'node:fs/promises'
-import { join, basename } from 'node:path'
+import { basename } from 'node:path'
 import { requireOwnerExecution } from './execution-authority.js'
 import { ControlStore } from './control-state.js'
 import { ownsRun } from './identity.js'
-import { RunStore } from './runs.js'
+import { RunStore, sentOutbox } from './runs.js'
 
-// Read existing delivery receipts; native sessions still own conversation history.
+// Read existing delivery receipts from the relay memory ledger; native
+// sessions still own conversation history. Explicit tool path only (message
+// history CLI / delivery socket history op), never ambient prompt enrichment.
 export async function deliveredMessages(controlDir: string, runId: string, options: { limit?: number; messageId?: number } = {}) {
   const limit = options.limit ?? 8
   if (!Number.isSafeInteger(limit) || limit < 1 || limit > 50) throw new Error('Limit must be 1..50')
@@ -20,26 +21,20 @@ export async function deliveredMessages(controlDir: string, runId: string, optio
     ownsRun(owner, run) && !run.external && !run.taskId && !run.application &&
     Date.parse(run.createdAt) >= pairedAt && (!run.scheduled || run.scheduled.pairedAt === owner!.pairedAt)
   ).map(run => [run.id, run]))
-  const directory = join(controlDir, 'outbox')
-  const files = await readdir(directory).catch((error: NodeJS.ErrnoException) => {
-    if (error.code === 'ENOENT') return []
-    throw error
-  })
   const messages = []
-  for (const file of files.filter(file => file.endsWith('.sent.json'))) {
-    // Corrupt or incomplete receipts are not delivery evidence.
-    let item
-    try { item = JSON.parse(await readFile(join(directory, file), 'utf8')) } catch { continue }
+  for (const item of sentOutbox(controlDir)) {
+    // Incomplete receipts are not delivery evidence.
     if (!item || typeof item !== 'object') continue
-    const run = runs.get(item.runId)
-    const deliveredAt = Date.parse(item.receipt?.deliveredAt)
-    const ids = item.receipt?.messageIds
+    const run = item.runId === undefined ? undefined : runs.get(item.runId)
+    const receipt = (item.receipt ?? {}) as { deliveredAt?: unknown; messageIds?: unknown }
+    const deliveredAt = Date.parse(receipt.deliveredAt as string)
+    const ids = receipt.messageIds
     if (!run || item.chatId !== caller.chatId || !Number.isFinite(deliveredAt) || deliveredAt < pairedAt ||
       !Array.isArray(ids) || !ids.length || !ids.every(id => Number.isSafeInteger(id) && id > 0)) continue
-    if (options.messageId !== undefined && !ids.includes(options.messageId)) continue
+    if (options.messageId !== undefined && !(ids as number[]).includes(options.messageId)) continue
     messages.push({
       runId: run.id, sessionId: run.execution?.sessionId, nativeSessionId: run.nativeSessionId,
-      scheduleId: run.scheduled?.id, messageIds: ids as number[], deliveredAt: item.receipt.deliveredAt as string,
+      scheduleId: run.scheduled?.id, messageIds: ids as number[], deliveredAt: receipt.deliveredAt as string,
       type: item.type || 'message', text: typeof item.text === 'string' ? item.text
         : typeof item.approvalPrompt === 'string' ? item.approvalPrompt : undefined,
       voiceText: typeof item.voiceText === 'string' ? item.voiceText : undefined,