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

package/src/approval.ts

@@ -1,5 +1,3 @@
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
-import path from 'node:path'
 import { assertId } from './identity.js'
 import { ownerEpoch, ownerId, type Owner } from './control-state.js'
 
@@ -34,28 +32,32 @@ const isApprovalRecord = (value: unknown): value is ApprovalRecord => {
   )
 }
 
-export class ApprovalStore {
-  private readonly approvalsDir: string
+// Stateless pipe: approvals live in relay memory. Engine children request
+// decisions through the delivery socket (folded into the approval send);
+// callbacks and task arbitration record them in-relay. A restart drops
+// pending approvals by design.
+const approvalsByControl = new Map<string, Map<string, ApprovalRecord>>()
 
-  constructor(controlDir: string) {
-    this.approvalsDir = path.join(controlDir, 'approvals')
-  }
+const approvalsFor = (controlDir: string): Map<string, ApprovalRecord> => {
+  let map = approvalsByControl.get(controlDir)
+  if (!map) { map = new Map(); approvalsByControl.set(controlDir, map) }
+  return map
+}
 
-  private async ensure(): Promise<void> {
-    await mkdir(this.approvalsDir, { recursive: true, mode: 0o700 })
-  }
+export class ApprovalStore {
+  constructor(private readonly controlDir: string) {}
 
-  private filePath(actionId: string): string {
+  private key(actionId: string): string {
     const safe = assertId(actionId)
     if (safe.length > 40) throw new Error('Approval identifier must be at most 40 characters')
-    return path.join(this.approvalsDir, `${safe}.json`)
+    return safe
   }
 
   async requestApproval(actionId: string, prompt: string, runId?: string): Promise<ApprovalRecord> {
     if (!prompt.trim()) throw new Error('Approval prompt is empty')
     if (runId) assertId(runId)
-    await this.ensure()
-    const existing = await this.getDecision(actionId)
+    const store = approvalsFor(this.controlDir)
+    const existing = store.get(this.key(actionId)) ?? null
     if (existing) {
       if (existing.runId !== runId || existing.prompt !== prompt)
         throw new Error('Approval ID already belongs to another request')
@@ -70,10 +72,7 @@ export class ApprovalStore {
       decision: 'pending',
       createdAt: new Date().toISOString(),
     }
-    const file = this.filePath(actionId)
-    const temporary = `${file}.${process.pid}.tmp`
-    await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 })
-    await rename(temporary, file)
+    store.set(this.key(actionId), record)
     return record
   }
 
@@ -83,8 +82,8 @@ export class ApprovalStore {
     decidedBy: number,
     decisionUpdateId?: number,
   ): Promise<ApprovalRecord> {
-    await this.ensure()
-    const existing = await this.getDecision(actionId)
+    const store = approvalsFor(this.controlDir)
+    const existing = store.get(this.key(actionId)) ?? null
     if (!existing) throw new Error('Unknown approval request')
     if (
       decisionUpdateId !== undefined &&
@@ -102,34 +101,25 @@ export class ApprovalStore {
       decidedBy,
       decisionUpdateId,
     }
-    const file = this.filePath(actionId)
-    const temporary = `${file}.${process.pid}.tmp`
-    await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 })
-    await rename(temporary, file)
+    store.set(this.key(actionId), record)
     return record
   }
 
   async recordOwnerDecision(actionId: string, decision: 'approved' | 'denied', owner: Owner): Promise<ApprovalRecord> {
-    await this.ensure()
-    const existing = await this.getDecision(actionId)
+    const store = approvalsFor(this.controlDir)
+    const existing = store.get(this.key(actionId)) ?? null
     if (!existing) throw new Error('Unknown approval request')
     if (existing.decision !== 'pending') throw new Error('Approval already decided')
     if (Date.now() - Date.parse(existing.createdAt) > 900_000) throw new Error('Approval expired')
     const record: ApprovalRecord = {...existing,version:2,decision,decidedAt:new Date().toISOString(),decidedOwnerId:ownerId(owner),decidedOwnerEpoch:ownerEpoch(owner)}
-    const file=this.filePath(actionId),temporary=`${file}.${process.pid}.tmp`
-    await writeFile(temporary,`${JSON.stringify(record,null,2)}\n`,{mode:0o600});await rename(temporary,file)
+    store.set(this.key(actionId), record)
     return record
   }
 
   async getDecision(actionId: string): Promise<ApprovalRecord | null> {
-    try {
-      const parsed: unknown = JSON.parse(await readFile(this.filePath(actionId), 'utf8'))
-      if (!isApprovalRecord(parsed) || parsed.actionId !== actionId)
-        throw new Error('Invalid approval record shape')
-      return parsed
-    } catch (error: unknown) {
-      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
-      throw error
-    }
+    const record = approvalsFor(this.controlDir).get(this.key(actionId)) ?? null
+    if (record && (!isApprovalRecord(record) || record.actionId !== actionId))
+      throw new Error('Invalid approval record shape')
+    return record
   }
 }

package/src/channel-backend.ts

@@ -1,7 +1,6 @@
-import { readFile } from 'node:fs/promises'
 import type { Config } from './config.js'
 import type { RunRecord } from './runs.js'
-import { workspaceFile } from './files.js'
+import { readStagedAttachment } from './files.js'
 
 // Application-owned jobs; no CLI state, provider credentials or business routing here.
 export async function dispatchChannel(config: Config, run: RunRecord): Promise<string | null> {
@@ -14,7 +13,7 @@ export async function dispatchChannel(config: Config, run: RunRecord): Promise<s
   for (const item of run.items ?? []) {
     let attachment
     if (item.attachment) {
-      const bytes = await readFile(await workspaceFile(config.workspace, item.attachment.path))
+      const bytes = await readStagedAttachment([config.controlDir, config.workspace], item.attachment.path)
       if (bytes.length > 12 * 1024 * 1024) throw new Error('Channel attachment exceeds 12 MB')
       attachment = { type: item.attachment.type, data: bytes.toString('base64') }
     }

package/src/config.ts

@@ -26,10 +26,6 @@ export type Config = ControlConfig & {
   applicationHost?: string
   geminiApiKey?: string
   openaiApiKey?: string
-  pagerDutyRoutingKey?: string
-  pagerDutyStocksHealthUrl?: string
-  pagerDutyPollMs?: number
-  pagerDutyFailureThreshold?: number
 }
 
 const positiveInteger = (value: string | undefined, name: string, fallback?: number): number => {
@@ -49,12 +45,20 @@ export const loadControlConfig = (env: NodeJS.ProcessEnv = process.env): Control
   }
 }
 
+export const telegramToken = (env: NodeJS.ProcessEnv = process.env): string => {
+  const token = env.TELEGRAM_BOT_TOKEN?.trim() || ''
+  if (token && !/^\d{5,}:[A-Za-z0-9_-]{20,}$/.test(token)) throw new Error('TELEGRAM_BOT_TOKEN is malformed; refusing to start Telegram transport')
+  return token
+}
+
 export const loadConfig = (env: NodeJS.ProcessEnv = process.env): Config => {
-  if (env.EZ_TELEGRAM_ENABLED !== undefined && !['true', 'false'].includes(env.EZ_TELEGRAM_ENABLED)) throw new Error('EZ_TELEGRAM_ENABLED must be true or false')
-  const telegramEnabled = env.EZ_TELEGRAM_ENABLED !== 'false'
-  const telegramBotToken = telegramEnabled ? env.TELEGRAM_BOT_TOKEN?.trim() || '' : ''
+  const legacy = env.EZ_TELEGRAM_ENABLED
+  if (legacy !== undefined && legacy !== 'true' && legacy !== 'false') throw new Error('EZ_TELEGRAM_ENABLED must be true or false')
+  const telegramBotToken = telegramToken(env)
+  const telegramEnabled = Boolean(telegramBotToken)
+  if (legacy !== undefined && (legacy === 'false') === telegramEnabled)
+    throw new Error('EZ_TELEGRAM_ENABLED was removed; it contradicts the inferred Telegram transport (a token means enabled). Unset EZ_TELEGRAM_ENABLED, and remove any stale TELEGRAM_BOT_TOKEN to stay application-only.')
   if (!telegramEnabled && !env.EZ_APPLICATION_PORT) throw new Error('Application-only execution requires EZ_APPLICATION_PORT')
-  if (telegramEnabled && !telegramBotToken) throw new Error('TELEGRAM_BOT_TOKEN is required')
 
   if (env.EZ_CHANNEL_BACKEND_URL && !env.EZ_CHANNEL_BACKEND_TOKEN?.trim()) throw new Error('EZ_CHANNEL_BACKEND_TOKEN is required')
   if (env.EZ_APPLICATION_PORT && env.EZ_CHANNEL_BACKEND_URL) throw new Error('Application input requires the native Ez executor, not a channel backend')
@@ -63,17 +67,6 @@ export const loadConfig = (env: NodeJS.ProcessEnv = process.env): Config => {
   const codexSandbox = env.EZ_CODEX_SANDBOX?.trim()
   if (codexSandbox && codexSandbox !== 'external') throw new Error('EZ_CODEX_SANDBOX must be external or unset')
   if (codexSandbox && (env.EZ_CHANNEL_BACKEND_URL || transport !== 'local')) throw new Error('External Codex sandbox requires native local execution')
-  const pagerDutyRoutingKey = env.PAGERDUTY_ROUTING_KEY?.trim()
-  const pagerDutyStocksHealthUrl = env.EZ_PAGERDUTY_STOCKS_HEALTH_URL?.trim()
-  if (pagerDutyStocksHealthUrl && !pagerDutyRoutingKey)
-    throw new Error('PAGERDUTY_ROUTING_KEY is required when EZ_PAGERDUTY_STOCKS_HEALTH_URL is set')
-  if (pagerDutyStocksHealthUrl) {
-    let url: URL
-    try { url = new URL(pagerDutyStocksHealthUrl) }
-    catch { throw new Error('EZ_PAGERDUTY_STOCKS_HEALTH_URL must be an absolute HTTP(S) URL') }
-    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.hash)
-      throw new Error('EZ_PAGERDUTY_STOCKS_HEALTH_URL must be an absolute HTTP(S) URL without credentials or a fragment')
-  }
   return {
     ...loadControlConfig(env),
     telegramEnabled,
@@ -92,13 +85,5 @@ export const loadConfig = (env: NodeJS.ProcessEnv = process.env): Config => {
     channelBackendToken: env.EZ_CHANNEL_BACKEND_TOKEN?.trim(),
     geminiApiKey: env.GEMINI_API_KEY?.trim(),
     openaiApiKey: env.OPENAI_API_KEY?.trim(),
-    pagerDutyRoutingKey,
-    pagerDutyStocksHealthUrl,
-    pagerDutyPollMs: pagerDutyRoutingKey && pagerDutyStocksHealthUrl
-      ? positiveInteger(env.EZ_PAGERDUTY_POLL_SECONDS, 'EZ_PAGERDUTY_POLL_SECONDS', 30) * 1_000
-      : undefined,
-    pagerDutyFailureThreshold: pagerDutyRoutingKey && pagerDutyStocksHealthUrl
-      ? positiveInteger(env.EZ_PAGERDUTY_FAILURE_THRESHOLD, 'EZ_PAGERDUTY_FAILURE_THRESHOLD', 3)
-      : undefined,
   }
 }

package/src/control-state.ts

@@ -1,7 +1,8 @@
 import { assertEffort } from './model-policy.js'
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
 import { mkdir, open, readFile, rename, rm, writeFile } from 'node:fs/promises'
 import path from 'node:path'
-import { isPreset, persistedPreset, type AiPreset, type ExecutionChoice } from './ai.js'
+import { isPreset, persistedPreset, type AiPreset, type ExecutionChoice, type ModelChoice } from './ai.js'
 
 export type Owner = {
   id?: string
@@ -32,7 +33,7 @@ export const validOwner = (owner: unknown): owner is Owner => {
       Number.isSafeInteger(p.telegramChatId) && (p.kind === 'group' ? p.telegramChatId! < 0 : p.kind === undefined && p.telegramChatId! > 0))
 }
 
-export type PairingRequest = {
+type TelegramPairingRequest = {
   kind?: 'group'
   title?: string
   telegramUserId: number
@@ -41,6 +42,18 @@ export type PairingRequest = {
   expiresAt: string
 }
 
+type ApplicationPairingRequest = {
+  application: {
+    bindingId: string
+    tokenHash: string
+    owner: Owner
+  }
+  requestedAt: string
+  expiresAt: string
+}
+
+export type PairingRequest = TelegramPairingRequest | ApplicationPairingRequest
+
 export type SessionState = {
   sessionId: string
   hasStarted: boolean
@@ -71,6 +84,20 @@ const emptyState = (): ControlState => ({ version: 1, owner: null, pending: [] }
 const isPositiveId = (value: unknown): value is number =>
   typeof value === 'number' && Number.isSafeInteger(value) && value > 0
 
+const applicationPairing = (request: PairingRequest): request is ApplicationPairingRequest =>
+  'application' in request
+
+const telegramPairing = (request: PairingRequest): request is TelegramPairingRequest =>
+  !applicationPairing(request)
+
+const applicationBindingId = (value: unknown): value is string =>
+  typeof value === 'string' && /^[a-f0-9-]{36}$/.test(value)
+
+const pairingToken = (value: unknown): value is string =>
+  typeof value === 'string' && /^[A-Za-z0-9_-]{43}$/.test(value)
+
+const pairingDigest = (value: string): string => createHash('sha256').update(value).digest('hex')
+
 const isRecentIds = (value: unknown): value is string[] =>
   Array.isArray(value) && value.length <= 3 && new Set(value).size === value.length &&
   value.every((id) => typeof id === 'string' && /^[a-zA-Z0-9_./:-]{1,160}$/.test(id))
@@ -78,13 +105,25 @@ const isRecentIds = (value: unknown): value is string[] =>
 const isState = (value: unknown): value is ControlState => {
   if (!value || typeof value !== 'object') return false
   const candidate = value as Partial<ControlState>
-  const identity = (person: unknown): boolean => {
+  const telegramIdentity = (person: unknown): boolean => {
     if (!person || typeof person !== 'object') return false
     const p = person as Owner
     return isPositiveId(p.telegramUserId) && (p.kind === 'group'
       ? Number.isSafeInteger(p.telegramChatId) && p.telegramChatId! < 0
       : p.kind === undefined && isPositiveId(p.telegramChatId))
   }
+  const pairing = (request: unknown): request is PairingRequest => {
+    if (!request || typeof request !== 'object') return false
+    const value = request as Partial<ApplicationPairingRequest & TelegramPairingRequest>
+    if (!Number.isFinite(Date.parse(value.expiresAt ?? '')) || !Number.isFinite(Date.parse(value.requestedAt ?? '')))
+      return false
+    if (value.application !== undefined) {
+      const application = value.application
+      return Object.keys(value).every((key) => ['application', 'requestedAt', 'expiresAt'].includes(key)) &&
+        !!application && applicationBindingId(application.bindingId) && /^[a-f0-9]{64}$/.test(application.tokenHash) && validOwner(application.owner)
+    }
+    return telegramIdentity(value)
+  }
   const session = (s: SessionState) => s && /^[0-9a-f-]{36}$/i.test(s.sessionId) && typeof s.hasStarted === 'boolean' &&
     (s.title === undefined || (typeof s.title === 'string' && s.title.length <= 80)) &&
     (s.archived === undefined || typeof s.archived === 'boolean') &&
@@ -94,7 +133,7 @@ const isState = (value: unknown): value is ControlState => {
   return (
     candidate.version === 1 &&
     Array.isArray(candidate.pending) &&
-    candidate.pending.every((p) => identity(p) && Number.isFinite(Date.parse(p.expiresAt))) &&
+    candidate.pending.every(pairing) &&
     (candidate.owner === null || validOwner(candidate.owner)) &&
     (candidate.ai === undefined || (Array.isArray(candidate.ai.presets) &&
       candidate.ai.presets.every(isPreset) &&
@@ -145,6 +184,9 @@ export class ControlStore {
     private readonly clock: Clock = () => Date.now(),
   ) {
     this.statePath = path.join(controlDir, 'control-state.json')
+    // The lock stays on the shared control volume: relay (container) and CLI
+    // children (host) must exclude each other. Hot reads avoid it entirely
+    // (see status/captureChoice fast paths); only real mutations take it.
     this.lockPath = path.join(controlDir, 'control-state.lock')
   }
 
@@ -170,8 +212,16 @@ export class ControlStore {
   }
 
   private async writeState(state: ControlState): Promise<void> {
+    const serialized = `${JSON.stringify(state, null, 2)}\n`
+    // Steady-state reads (owner checks, session pins that already match) must
+    // not churn control/: skip the write when nothing changed.
+    try {
+      if ((await readFile(this.statePath, 'utf8')) === serialized) return
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    }
     const temporary = `${this.statePath}.${process.pid}.tmp`
-    await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 })
+    await writeFile(temporary, serialized, { mode: 0o600 })
     await rename(temporary, this.statePath)
   }
 
@@ -200,6 +250,12 @@ export class ControlStore {
   }
 
   async status(): Promise<ControlState> {
+    // Hot path (owner checks every message and every source tick): when no
+    // pairing expired, the pruned state is returned with zero control/ writes
+    // and without taking the lock. Expiry still converges under the lock.
+    const current = await this.readState()
+    const pruned = this.prune(current)
+    if (pruned.pending.length === current.pending.length) return pruned
     return this.withLock(async () => {
       const state = this.prune(await this.readState())
       await this.writeState(state)
@@ -221,7 +277,7 @@ export class ControlStore {
       if (telegramOwner(state.owner)) return 'owner-exists'
       if (
         state.pending.some(
-          (request) => request.telegramUserId === telegramUserId && request.telegramChatId === telegramChatId,
+          (request) => telegramPairing(request) && request.telegramUserId === telegramUserId && request.telegramChatId === telegramChatId,
         )
       ) {
         await this.writeState(state)
@@ -282,14 +338,75 @@ export class ControlStore {
     })
   }
 
+  async createApplicationTelegramPairing(bindingId: string, expectedOwner: Owner): Promise<{ token: string; expiresAt: string } | null> {
+    if (!applicationBindingId(bindingId) || !validOwner(expectedOwner)) throw new Error('Invalid application Telegram pairing request')
+    return this.withLock(async () => {
+      const state = this.prune(await this.readState())
+      if (!sameOwner(expectedOwner, state.owner)) throw new Error('Application authority revoked')
+      if (telegramOwner(state.owner)) {
+        await this.writeState(state)
+        return null
+      }
+      const retained = state.pending.filter((request) => !applicationPairing(request) || request.application.bindingId !== bindingId)
+      if (retained.length >= 3) throw new Error('Telegram pairing capacity reached')
+      const token = randomBytes(32).toString('base64url')
+      const now = this.clock()
+      const expiresAt = new Date(now + this.pairingTtlMs).toISOString()
+      state.pending = [...retained, {
+        application: { bindingId, tokenHash: pairingDigest(token), owner: expectedOwner },
+        requestedAt: new Date(now).toISOString(),
+        expiresAt,
+      }]
+      await this.writeState(state)
+      return { token, expiresAt }
+    })
+  }
+
+  async claimApplicationTelegramPairing(
+    token: string,
+    telegramUserId: number,
+    telegramChatId: number,
+    authorize: (bindingId: string, owner: Owner) => Promise<boolean>,
+  ): Promise<Owner | null> {
+    if (!pairingToken(token) || !isPositiveId(telegramUserId) || !isPositiveId(telegramChatId)) return null
+    return this.withLock(async () => {
+      const state = this.prune(await this.readState())
+      const request = state.pending.find((candidate): candidate is ApplicationPairingRequest =>
+        applicationPairing(candidate) && /^[a-f0-9]{64}$/.test(candidate.application.tokenHash) &&
+        timingSafeEqual(Buffer.from(candidate.application.tokenHash, 'hex'), Buffer.from(pairingDigest(token), 'hex')))
+      if (!request || telegramOwner(state.owner) || !sameOwner(request.application.owner, state.owner)) {
+        if (request) state.pending = state.pending.filter((candidate) => candidate !== request)
+        await this.writeState(state)
+        return null
+      }
+      if (!await authorize(request.application.bindingId, request.application.owner)) {
+        state.pending = state.pending.filter((candidate) => candidate !== request)
+        await this.writeState(state)
+        return null
+      }
+      const owner: Owner = {
+        id: ownerId(state.owner!),
+        generation: state.owner!.generation,
+        telegramUserId,
+        telegramChatId,
+        telegramLinkedAt: crypto.randomUUID(),
+        pairedAt: state.owner!.pairedAt,
+      }
+      state.owner = owner
+      state.pending = []
+      await this.writeState(state)
+      return owner
+    })
+  }
+
   async approveOwner(telegramUserId: number, group = false): Promise<Owner> {
     if (!(group ? Number.isSafeInteger(telegramUserId) && telegramUserId < 0 : isPositiveId(telegramUserId))) throw new Error('Supply a positive user ID or negative group ID')
     return this.withLock(async () => {
       const state = this.prune(await this.readState())
       if (telegramOwner(state.owner)) throw new Error('An owner is already paired; unlink locally before replacing its Telegram channel')
-      const request = state.pending.find((candidate) => group
+      const request = state.pending.find((candidate): candidate is TelegramPairingRequest => telegramPairing(candidate) && (group
         ? candidate.kind === 'group' && candidate.telegramChatId === telegramUserId
-        : candidate.kind === undefined && candidate.telegramUserId === telegramUserId)
+        : candidate.kind === undefined && candidate.telegramUserId === telegramUserId))
       if (!request) throw new Error('No active pairing request exists for that Telegram user ID')
       const owner: Owner = {
         generation: state.owner ? state.owner.generation : crypto.randomUUID(),
@@ -463,7 +580,57 @@ export class ControlStore {
     })
   }
 
+  async normalizeProviderBindings(catalog: ModelChoice[]): Promise<boolean> {
+    const providerFor = (preset: AiPreset): AiPreset => {
+      if (preset.provider || preset.cli !== 'codex' || !preset.model) return preset
+      const matches = catalog.filter((model) => model.cli === preset.cli && model.model === preset.model && model.provider &&
+        (preset.effort === undefined || model.efforts.includes(preset.effort)))
+      if (matches.length !== 1) return preset
+      const model = matches[0]
+      return persistedPreset({
+        ...preset,
+        provider: model.provider,
+      })
+    }
+    return this.withLock(async () => {
+      const state = await this.readState()
+      if (!state.ai) return false
+      let changed = false
+      const normalize = (preset: AiPreset | undefined): AiPreset | undefined => {
+        if (!preset) return undefined
+        const next = providerFor(preset)
+        if (next !== preset) changed = true
+        return next
+      }
+      state.ai.presets = state.ai.presets.map((preset) => normalize(preset)!)
+      if (state.activeSession?.preset) state.activeSession.preset = normalize(state.activeSession.preset)
+      state.sessions = state.sessions?.map((session) => ({
+        ...session,
+        ...(session.preset ? { preset: normalize(session.preset) } : {}),
+      }))
+      if (changed) await this.writeState(state)
+      return changed
+    })
+  }
+
   async captureChoice(initial: AiPreset, title?: string): Promise<ExecutionChoice> {
+    // Hot path (every inbound message and every source tick): when the pinned
+    // session already matches the selected preset, return it with zero
+    // control/ writes and without taking the lock. Any divergence (missing
+    // session, CLI/provider/model change, untitled fresh session) falls
+    // through to the serializing slow path. A concurrent control edit inside
+    // the microsecond unlocked window fails closed downstream (the execution
+    // session lookup rejects a stale pin; the batch can be retried).
+    const settled = await this.readState()
+    const settledAi = settled.ai
+    const settledPreset = settledAi?.presets.find((p) => p.id === settledAi.selectedId)
+    const session = settled.activeSession
+    if (settledPreset && session && (session.cli || session.hasStarted) &&
+      !(session.cli === settledPreset.cli && session.hasStarted && session.preset &&
+        (session.preset.provider !== settledPreset.provider || session.preset.model !== settledPreset.model)) &&
+      (session.cli !== settledPreset.cli || JSON.stringify(session.preset) === JSON.stringify(settledPreset)) &&
+      Boolean(session.title || session.hasStarted || !title?.trim()))
+      return { sessionId: session.sessionId, preset: settledPreset }
     return this.withLock(async () => {
       const state = await this.readState()
       state.ai ??= { presets: [persistedPreset(initial)], defaultId: initial.id, selectedId: initial.id, recentIds: [] }

package/src/conversation-menu.ts

@@ -1,9 +1,9 @@
 import { InlineKeyboard, type Context } from 'grammy'
 import { ControlStore, sessionTitle } from './control-state.js'
-import type { RunStore } from './runs.js'
 
 // IDs identify existing relay bindings only; the engine still owns all context.
-export const createConversationMenu = (control: ControlStore, runs: Pick<RunStore, 'list'>) => {
+// Titles come from owner renames; no run text or delivery history is read here.
+export const createConversationMenu = (control: ControlStore) => {
   const render = async (ctx: Context, text: string, keyboard: InlineKeyboard) => {
     if (!ctx.callbackQuery?.message) { await ctx.reply(text, { reply_markup: keyboard }); return }
     try { await ctx.editMessageText(text, { reply_markup: keyboard }) }
@@ -13,23 +13,12 @@ export const createConversationMenu = (control: ControlStore, runs: Pick<RunStor
   }
   const sessionsWithNames = async () => {
     const sessions = await control.listSessions()
-    if (sessions.every(s => s.title)) return sessions
-    // Display existing owner input only. Do not create another history store or
-    // ask an engine to generate titles just to render a menu. Commands and JSON
-    // event records (including approval callbacks) are not readable chat names.
-    const history = await runs.list()
+    // Display session bindings only. Titles come from explicit owner renames;
+    // no prompt, run or delivery history is read to derive a menu label.
     return sessions.flatMap((session, index) => {
       if (session.title) return [session]
-      const first = history.find(run => run.execution?.sessionId === session.sessionId &&
-        run.messageId && !run.taskId && !run.scheduled && !run.external && !run.replyOnly &&
-        run.texts[0]?.trim() && !/^[/{]/.test(run.texts[0].trim()))
-      // New only reserves a routing ID. Do not present empty routing placeholders
-      // as engine conversations. Retain the records for already accepted work.
-      if (!session.hasStarted && !session.nativeSessionId && !first) return []
-      const title = first
-        ? `${first.texts[0].replace(/\s+/g, ' ').trim().slice(0, 40)} · ${first.createdAt.slice(0, 16).replace('T', ' ')} UTC`
-        : `Untitled conversation ${index + 1}`
-      return [{ ...session, title }]
+      if (!session.hasStarted && !session.nativeSessionId) return []
+      return [{ ...session, title: `Untitled conversation ${index + 1}` }]
     })
   }
   const list = async (ctx: Context, archived = false, page = 0) => {

package/src/delivery-socket-client.d.mts

@@ -0,0 +1,4 @@
+export type DeliverySocketRequest = { op: string; payload?: unknown }
+export function deliverySocketPath(controlDir: string): string
+export function callDeliverySocket(socketPath: string, op: DeliverySocketRequest, timeoutMs?: number): Promise<unknown>
+export function deliverySocketAlive(socketPath: string, timeoutMs?: number): Promise<boolean>

package/src/delivery-socket-client.mjs

@@ -0,0 +1,104 @@
+import { createConnection } from 'node:net'
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+
+// Plain-JS delivery transport shared by the TypeScript relay and the
+// plain-Node tools (plugin manager, update supervisor, install status). The
+// relay owns run records in memory; every other process reaches them through
+// this socket on the shared control volume. Newline-delimited JSON frames:
+// {id, op, payload} -> {id, ok, result?, error?}.
+//
+// Host-capable deployments publish a loopback TCP endpoint as well: on Docker
+// Desktop/OrbStack the container's Unix socket is not connectable from the
+// macOS host, so host processes fall back to the relay's authenticated
+// loopback listener described by control/delivery-endpoint.json.
+export const deliverySocketPath = controlDir => path.join(controlDir, 'delivery.sock')
+
+const encode = value => `${JSON.stringify(value)}\n`
+const endpointName = 'delivery-endpoint.json'
+const connectFailureCodes = new Set(['ENOENT', 'ECONNREFUSED', 'EACCES', 'EPROTOTYPE'])
+
+const unavailable = (target, cause) => {
+  const error = new Error(`Delivery relay unavailable at ${target}`)
+  if (cause !== undefined) error.cause = cause
+  error.connectFailure = true
+  return error
+}
+
+// A timeout is not a connect failure: the relay may already have processed the
+// request, so replaying the frame elsewhere could duplicate an uncertain write.
+const timedOut = target => new Error(`Delivery relay unavailable at ${target}`)
+
+const exchange = (connect, envelope, timeoutMs, target) => new Promise((resolve, reject) => {
+  let done = false
+  const socket = connect()
+  const timer = setTimeout(() => {
+    if (done) return
+    done = true
+    socket.destroy()
+    reject(timedOut(target))
+  }, timeoutMs)
+  let buffer = ''
+  socket.setEncoding('utf8')
+  socket.once('error', error => {
+    if (done) return
+    done = true
+    clearTimeout(timer)
+    reject(error?.code && connectFailureCodes.has(error.code) ? unavailable(target, error) : error)
+  })
+  socket.on('data', chunk => {
+    buffer += chunk
+    let newline
+    while ((newline = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, newline)
+      buffer = buffer.slice(newline + 1)
+      if (!line.trim()) continue
+      let response
+      try { response = JSON.parse(line) } catch { continue }
+      if (response.id !== envelope.id) continue
+      if (done) return
+      done = true
+      clearTimeout(timer)
+      socket.destroy()
+      if (response.ok) resolve(response.result)
+      else reject(new Error(typeof response.error === 'string' ? response.error : 'Delivery request failed'))
+    }
+  })
+  socket.write(encode(envelope))
+})
+
+const readEndpoint = async controlDir => {
+  try {
+    const value = JSON.parse(await readFile(path.join(controlDir, endpointName), 'utf8'))
+    if (value?.host !== '127.0.0.1' || !Number.isSafeInteger(value.port) || value.port < 1 || value.port > 65535 ||
+      typeof value.token !== 'string' || !/^[a-f0-9]{64}$/.test(value.token)) return null
+    return value
+  } catch { return null }
+}
+
+export const callDeliverySocket = async (socketPath, op, timeoutMs = 130_000) => {
+  const id = `${Date.now().toString(36)}_${Math.floor(Math.random() * 0xffffff).toString(16)}`
+  try {
+    return await exchange(() => createConnection(socketPath), { id, ...op }, timeoutMs, socketPath)
+  } catch (error) {
+    if (!error?.connectFailure) throw error
+  }
+  const endpoint = await readEndpoint(path.dirname(socketPath))
+  if (!endpoint) throw unavailable(socketPath)
+  const target = `${endpoint.host}:${endpoint.port}`
+  try {
+    return await exchange(() => createConnection({ host: endpoint.host, port: endpoint.port }), { id, token: endpoint.token, ...op }, timeoutMs, target)
+  } catch (error) {
+    if (!error?.connectFailure) throw error
+    throw unavailable(`${socketPath} and ${target}`, error)
+  }
+}
+
+export const deliverySocketAlive = async (socketPath, timeoutMs = 2000) => {
+  try {
+    await callDeliverySocket(socketPath, { op: 'ping' }, timeoutMs)
+    return true
+  } catch {
+    return false
+  }
+}