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

package/src/host-executor.ts

@@ -9,7 +9,7 @@ import { isHostRunId } from './host-executor-protocol.js'
 import { fileURLToPath } from 'node:url'
 import { startExecutorJob, terminateJob, resolveExecutor, validateCodexProvider, type CodexProviderBinding, type ExecutorOptions } from './executor.js'
 import { parseIsolationClass, type IsolationClass } from './isolation.js'
-import { readModels, validateSelection } from './ai.js'
+import { readModels, validateSelection, validateOpencodeProviders, type ModelChoice } from './ai.js'
 import type { ChildProcess } from 'node:child_process'
 import { taskWorkspace } from './task-workspace.js'
 import { packageVersion } from './version.js'
@@ -17,12 +17,30 @@ import { installedPluginVersions } from './software-status.js'
 import { processSnapshot } from './process-tree.js'
 
 export type PluginNetworkRoute = { revisions:string[]; bindings:{service:string;network:string}[] }
-export type HostBinding = { name: string; workspace: string; controlDir: string; binDir: string; toolsHome?: string; sharedWorkspace?: string; additionalWorkspaces?: string[]; pluginNetworkBindings?: Record<string, PluginNetworkRoute>; pluginFolderRoots?: Record<string,string[]>; codexProviders?: CodexProviderBinding[] }
+export type HostBinding = { name: string; workspace: string; controlDir: string; binDir: string; toolsHome?: string; sharedWorkspace?: string; additionalWorkspaces?: string[]; pluginNetworkBindings?: Record<string, PluginNetworkRoute>; pluginFolderRoots?: Record<string,string[]>; codexProviders?: CodexProviderBinding[]; opencodeProviders?: string[] }
 export type HostInstallation = { cli: string; isolation?: IsolationClass; agents: HostBinding[] }
 
+// Periodic refresh body, extracted for testing. Throws on failure; the
+// caller keeps the last-good disk catalog and the host alive.
+export const refreshAgentCatalog = async (agent: HostBinding,
+  readFresh: (agent: HostBinding) => Promise<ModelChoice[]>,
+  seen: Map<HostBinding, string>): Promise<void> => {
+  const catalogModels = await readFresh(agent)
+  // Empty discovery is not an authoritative deletion of the installed catalog.
+  if (!catalogModels.length) return
+  const models = JSON.stringify(catalogModels)
+  if (seen.get(agent) === models) return
+  await new ControlStore(agent.controlDir, 900000).normalizeProviderBindings(catalogModels)
+  const file = path.join(agent.controlDir, 'host-executor/models.json')
+  await writeFile(file + '.tmp', models, { mode: 0o600 })
+  await rename(file + '.tmp', file)
+  seen.set(agent, models)
+}
+
 const processStart = async (pid:number) => (await processSnapshot()).get(pid)?.birth
 
-export const serveHostExecutor = async (installation: HostInstallation, signal: AbortSignal, launch = startExecutorJob) => {
+export const serveHostExecutor = async (installation: HostInstallation, signal: AbortSignal, launch = startExecutorJob,
+  readCatalog?: (agent: HostBinding) => Promise<ModelChoice[]>) => {
   if (installation.isolation !== undefined) parseIsolationClass(installation.isolation)
   if (installation.isolation === 'isolated') throw new Error('Isolated agents run the native CLI in the relay; do not start host transport')
   resolveExecutor(installation.cli)
@@ -31,11 +49,13 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
     throw new Error('Each agent requires a separate workspace and control directory')
   const active = new Map<string, ChildProcess>()
   const tasks = new Set<Promise<void>>()
+  let catalogRefresh: Promise<void> | undefined
   const locks: string[] = []
   const sharedWorkspaces = new Map<HostBinding, string>()
   const additionalWorkspaces = new Map<HostBinding, string[]>()
   const catalog = async (agent: HostBinding) => {
-    const discovered = await readModels(undefined, undefined, path.join(agent.controlDir, 'cli', 'codex'))
+    const discovered = await readModels(undefined, undefined, path.join(agent.controlDir, 'cli', 'codex'),
+      undefined, undefined, validateOpencodeProviders(agent.opencodeProviders), agent.controlDir)
     const providers = (agent.codexProviders ?? []).map(validateCodexProvider)
     const declared = providers.flatMap(provider => provider.models.map(model => {
       const native = discovered.find(candidate => candidate.cli === 'codex' && !candidate.provider && candidate.model === model)
@@ -46,11 +66,18 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
       model.model !== undefined && declaredModels.has(model.model) && model.cli === 'codex'
     return [...discovered.filter(model => !isReplacedByProvider(model)), ...declared]
   }
+  const freshCatalog = readCatalog ?? catalog
+  const beat = async (agent: HostBinding) => {
+    const directory = path.join(agent.controlDir, 'host-executor')
+    await writeFile(path.join(directory, 'heartbeat.tmp'), JSON.stringify({ at: Date.now(), pid: process.pid, version: packageVersion, platform: process.platform, arch: process.arch, plugins: await installedPluginVersions(agent.toolsHome) }), { mode: 0o600 })
+    await rename(path.join(directory, 'heartbeat.tmp'), path.join(directory, 'heartbeat.json'))
+  }
   try {
     for (const agent of installation.agents) {
       if (![agent.workspace,agent.controlDir,agent.binDir].every(path.isAbsolute)) throw new Error('Host bindings require absolute paths')
       const providers=(agent.codexProviders ?? []).map(validateCodexProvider)
       if (new Set(providers.map(provider=>provider.id)).size !== providers.length) throw new Error('Codex provider IDs must be unique')
+      validateOpencodeProviders(agent.opencodeProviders)
       if (agent.sharedWorkspace && !path.isAbsolute(agent.sharedWorkspace)) throw new Error('Shared workspace requires an absolute path')
       if (agent.sharedWorkspace) sharedWorkspaces.set(agent, await realpath(agent.sharedWorkspace))
       if (agent.additionalWorkspaces) {
@@ -77,7 +104,7 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
       catch(error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
       await writeFile(lock,JSON.stringify({pid:process.pid,started:await processStart(process.pid)}),{mode:0o600,flag:'wx'})
       locks.push(lock)
-      const models = await catalog(agent)
+      const models = await freshCatalog(agent)
       await new ControlStore(agent.controlDir, 900000).normalizeProviderBindings(models)
       const modelsFile=path.join(directory,'models.json')
       await writeFile(modelsFile+'.tmp',JSON.stringify(models),{mode:0o600});await rename(modelsFile+'.tmp',modelsFile)
@@ -100,22 +127,23 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
     while (!signal.aborted) {
       const parent=Number(process.env.EZ_HOST_SUPERVISOR_PID)
       if(parent) { try { process.kill(parent,0) } catch { break } }
-      if(Date.now()-catalogAt>30000){
-        for(const agent of installation.agents){
-          const catalogModels = await catalog(agent)
-          const models=JSON.stringify(catalogModels)
-          if(catalogSeen.get(agent)===models)continue
-          await new ControlStore(agent.controlDir, 900000).normalizeProviderBindings(catalogModels)
-          const file=path.join(agent.controlDir,'host-executor/models.json')
-          await writeFile(file+'.tmp',models,{mode:0o600});await rename(file+'.tmp',file)
-          catalogSeen.set(agent,models)
-        }
+      // Keep transport liveness independent of native catalog I/O.
+      for (const agent of installation.agents) await beat(agent)
+      if(!catalogRefresh && Date.now()-catalogAt>30000){
         catalogAt=Date.now()
+        catalogRefresh=(async()=>{
+          for(const agent of installation.agents){
+            if(signal.aborted)break
+            try {
+              await refreshAgentCatalog(agent, freshCatalog, catalogSeen)
+            } catch (error) {
+              console.error('Host catalog refresh failed, keeping last-good models', error instanceof Error ? error.message : error)
+            }
+          }
+        })().finally(()=>{catalogRefresh=undefined})
       }
       for (const agent of installation.agents) {
         const directory=path.join(agent.controlDir,'host-executor')
-        await writeFile(path.join(directory,'heartbeat.tmp'),JSON.stringify({at:Date.now(),pid:process.pid,version:packageVersion,platform:process.platform,arch:process.arch,plugins:await installedPluginVersions(agent.toolsHome)}),{mode:0o600})
-        await rename(path.join(directory,'heartbeat.tmp'),path.join(directory,'heartbeat.json'))
         for (const file of await readdir(directory)) {
           if (!file.endsWith('.request.json') || !isHostRunId(file.slice(0,-13))) continue
           const id=file.slice(0,-13)
@@ -161,7 +189,10 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
               if (provider && model && !provider.models.includes(model)) throw new Error('Selected model is not declared for this Codex provider')
               if (!provider && model && (agent.codexProviders ?? []).some(binding=>binding.models.includes(model)))
                 throw new Error('Selected Codex provider is required for this model')
-              if (cli !== installation.cli) await validateSelection({id:'selected',name:'Selected model',cli,provider:opts.provider,model,effort:opts.effort},await catalog(agent))
+              // Admission and execution must use the same catalog snapshot. A
+              // transient native-client probe failure must not reject a model
+              // that the host just advertised to the relay and application.
+              if (cli !== installation.cli) await validateSelection({id:'selected',name:'Selected model',cli,provider:opts.provider,model,effort:opts.effort},JSON.parse(await readFile(path.join(directory,'models.json'),'utf8')))
               const options:ExecutorOptions={workspace:run?.scheduled ? await taskWorkspace(agent.controlDir,id) : agent.workspace,controlDir:agent.controlDir,binDir:agent.binDir,toolsHome:agent.toolsHome,sharedWorkspace,additionalWorkspaces:additionalWorkspaces.get(agent),cli,
                 runId:path.basename(base),timeoutMs:0,repairEnabled:opts.repairEnabled,
                 sessionId:opts.sessionId,isResume:opts.isResume,model,effort:opts.effort,provider:opts.provider,codexAutoCompactTokens:opts.codexAutoCompactTokens,codexProvider:provider,
@@ -198,6 +229,7 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
   } finally {
     for(const child of active.values())terminateJob(child)
     await Promise.allSettled(tasks)
+    await catalogRefresh
     for(const lock of locks)await rm(lock,{force:true})
   }
 }

package/src/index.ts

@@ -26,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'
@@ -71,7 +71,8 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
   let drainTimer: ReturnType<typeof setInterval> | undefined
   const codexHome = join(config.controlDir, 'cli', 'codex')
   const conversationMenu = createConversationMenu(control)
-  const aiMenu = createAiMenu(control, config.executorCli, undefined, config.workspace, codexHome)
+  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')
 

package/src/menu.ts

@@ -30,14 +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)
+  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

@@ -13,7 +13,25 @@ export async function deliveredMessages(controlDir: string, runId: string, optio
   if (options.messageId !== undefined && (!Number.isSafeInteger(options.messageId) || options.messageId < 1))
     throw new Error('Message ID must be a positive integer')
   const caller = await requireOwnerExecution(controlDir, runId)
-  if (caller.application || caller.delivery) throw new Error('History requires a Telegram owner run')
+  const application = caller.application ?? caller.delivery
+  if (application) {
+    if (options.messageId !== undefined) throw new Error('Message ID filter is only available for Telegram history')
+    const owner = (await new ControlStore(controlDir, 900_000).status()).owner
+    const runs = new Map((await new RunStore(controlDir).list()).filter(run => {
+      const origin = run.application ?? run.delivery
+      return origin?.bindingId === application.bindingId && origin.scope === application.scope &&
+        !run.external && !run.taskId && ownsRun(owner, run)
+    }).map(run => [run.id, run]))
+    const messages = sentOutbox(controlDir).flatMap(item => {
+      const run = item.runId === undefined ? undefined : runs.get(item.runId)
+      return run && (!item.type || item.type === 'message') && typeof item.text === 'string'
+        ? [{ runId: run.id, id: item.id, text: item.text, createdAt: item.createdAt }]
+        : []
+    })
+    messages.sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id))
+    return { scope: application.scope, messages: messages.slice(-limit), hasMore: messages.length > limit,
+      note: 'Delivered messages in the current application binding and scope; relay history is bounded and resets on restart.' }
+  }
   const owner = (await new ControlStore(controlDir, 900_000).status()).owner
   if (!ownsRun(owner, caller)) throw new Error('Owner binding changed')
   const pairedAt = Date.parse(owner!.pairedAt)

package/src/message.ts

@@ -13,8 +13,8 @@ if (rawArgs.includes('--help') || rawArgs.includes('-h')) {
   console.log(
     'Usage: ezenciel-agents-message [--text-file <path> | --text <text>] [--document <path>] [--voice <text>] [--reply-to <id>]',
   )
-  console.log('History: ezenciel-agents-message history [--limit 1..50] [--message-id ID] (read-only, bound Telegram chat, across sessions)')
-  console.log("Authenticated channel: sends go directly to the paired owner's Telegram chat. receipt OUTBOX_ID reads delivery status; sends return queued ID then Telegram delivery receipt or unknown outcome. Never resend an uncertain operation.")
+  console.log('History: ezenciel-agents-message history [--limit 1..50] [--message-id ID] (read-only; current application binding and scope, or bound Telegram chat). --message-id is Telegram-only.')
+  console.log('Authenticated run: sends use its bound channel (application inbox or paired Telegram chat). Delivery receipts confirm that destination; uncertain sends must not be retried without readback.')
   console.log('Text: --text decodes \\n as a newline and \\\\ as a literal backslash; --text-file preserves file content.')
   process.exit(0)
 }

package/src/plugins/manager.mjs

@@ -278,15 +278,14 @@ export async function hostNetworkBindings(config, record, home) {
   const configured = agent.pluginNetworkBindings;
   if (configured !== undefined && (!configured || typeof configured !== 'object' || Array.isArray(configured)))
     throw Error('Invalid host network bindings');
+  const route = configured?.[record.manifest?.id];
+  if (route === undefined) return [];
   if (process.env.EZ_DOCKER_COMPOSE === 'standalone') {
-    if (configured && Object.keys(configured).length) throw Error('Isolated broker cannot use host network bindings');
-    return [];
+    throw Error('Isolated broker cannot use host network bindings');
   }
   if (realpathSync(path.join(deployment, 'mind')) !== config.workspace ||
       realpathSync(path.join(deployment, 'control')) !== realpathSync(agent.controlDir))
     throw Error('Invalid host network binding deployment');
-  const route = configured?.[record.manifest?.id];
-  if (route === undefined) return [];
   keys(route, ['revisions', 'bindings']);
   const trusted = await snapshot(record.source);
   if (record.revision !== trusted.revision || record.source !== trusted.source ||

package/src/setup.ts

@@ -37,7 +37,7 @@ export const readActiveExecutor = async (envFilePath: string): Promise<string> =
   } catch {
     // env file doesn't exist yet
   }
-  return process.env.EZ_EXECUTOR_CLI?.trim() || 'agy'
+  return process.env.EZ_EXECUTOR_CLI?.trim() || 'codex'
 }
 
 export const setExecutorInEnv = async (envFilePath: string, cliName: string): Promise<void> => {
@@ -102,9 +102,10 @@ const printStatus = (status: { active: string; items: ExecutorStatus[] }): void
   console.log('\nTo switch executor:')
   console.log('  pnpm run setup <executor-name>')
   console.log('  Examples: pnpm run setup claude')
-  console.log('            pnpm run setup agy')
+  console.log('            pnpm run setup codex')
   console.log('            pnpm run setup grok')
   console.log('            pnpm run setup opencode')
+  console.log('            pnpm run setup pi')
   console.log('            pnpm run setup codex-gui\n')
 }
 

package/test/ai.test.ts

@@ -4,7 +4,7 @@ import { mkdtemp, mkdir, writeFile, readFile, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { ControlStore } from '../src/control-state.js'
-import { initialPreset, chatPreset, readModels, isPreset } from '../src/ai.js'
+import { initialPreset, chatPreset, readModels, isPreset, readOpencodeModels, readCuratedModels, validateSelection, opencodeProviderAllowlist } from '../src/ai.js'
 import { createAiMenu } from '../src/menu.js'
 import { EXECUTOR_REGISTRY, nativeSessionId } from '../src/executor.js'
 import { InboxStore } from '../src/inbox.js'
@@ -287,6 +287,12 @@ test('native executor flags carry the exact model and effort; only structured me
   const codex = EXECUTOR_REGISTRY.codex.buildArgs(opts, '', 'fixture')
   assert.ok(codex.includes('model_reasoning_effort="medium"'))
   assert.deepEqual(codex.slice(-3), ['resume', opts.sessionId, '-'])
+  // Opencode variants pass through verbatim on every platform; there is no
+  // OS-specific effort mapping between the catalog and `run --variant`.
+  const opencode = EXECUTOR_REGISTRY.opencode.buildArgs(
+    { workspace: '/tmp/fixture', model: 'opencode/muse-spark-1.3-contributor-free', effort: 'xhigh' }, '', 'fixture')
+  assert.equal(opencode[opencode.indexOf('-m') + 1], 'opencode/muse-spark-1.3-contributor-free')
+  assert.equal(opencode[opencode.indexOf('--variant') + 1], 'xhigh')
   assert.equal(nativeSessionId('codex', JSON.stringify({ type: 'thread.started', thread_id: opts.sessionId })), opts.sessionId)
   assert.equal(nativeSessionId('opencode', JSON.stringify({ type: 'step_start', sessionID: 'ses_fixture' })), 'ses_fixture')
   assert.equal(nativeSessionId('codex', JSON.stringify({ type: 'text', thread_id: opts.sessionId })), undefined)
@@ -353,3 +359,181 @@ test('upgrades expose responsive chat without replacing an existing default or q
     assert.ok(state.presets.some(p => p.id === 'chat-default'))
   } finally { await rm(dir, { recursive: true, force: true }) }
 })
+
+test('opencode catalog projects installed models with variants as efforts', async () => {
+  const verbose = [
+    'opencode/big-pickle',
+    JSON.stringify({ id: 'big-pickle', providerID: 'opencode', name: 'Big Pickle', variants: {} }),
+    'opencode/ling-free',
+    JSON.stringify({ id: 'ling-free', providerID: 'opencode', name: 'Ling Free',
+      variants: { low: { reasoningEffort: 'low' }, medium: { reasoningEffort: 'medium' }, 'bad option': {} } }),
+    'openrouter/~aliased/model',
+    JSON.stringify({ id: 'model', providerID: 'openrouter', name: 'Aliased', variants: {} }),
+  ].join('\n')
+  const catalog = await readOpencodeModels(async (args) => {
+    assert.deepEqual(args, ['models', '--verbose'])
+    return verbose
+  })
+  assert.deepEqual(catalog, [
+    { cli: 'opencode', model: 'opencode/big-pickle', name: 'Big Pickle · opencode/big-pickle', efforts: [] },
+    { cli: 'opencode', model: 'opencode/ling-free', name: 'Ling Free · opencode/ling-free', efforts: ['low', 'medium'] },
+  ])
+})
+
+test('opencode catalog falls back to the plain list, then to the client default', async () => {
+  const plain = await readOpencodeModels(async (args) => {
+    if (args.includes('--verbose')) throw new Error('no verbose metadata')
+    return 'opencode/alpha\nopenrouter/~aliased/model\nnot a model line\n'
+  })
+  assert.deepEqual(plain, [{ cli: 'opencode', model: 'opencode/alpha', name: 'opencode/alpha', efforts: [] }])
+  assert.deepEqual(await readOpencodeModels(async () => { throw new Error('opencode unavailable') }), [])
+  const fallback = await readModels(undefined, async (cli) => cli === 'opencode', undefined as never,
+    async () => { throw new Error('opencode unavailable') })
+  assert.deepEqual(fallback, [{ cli: 'opencode', name: 'opencode · client default', efforts: [] }])
+  const listed = await readModels(undefined, async (cli) => cli === 'opencode', undefined as never,
+    async () => 'opencode/alpha\n')
+  assert.deepEqual(listed, [{ cli: 'opencode', model: 'opencode/alpha', name: 'opencode/alpha', efforts: [] }])
+})
+
+test('opencode provider allowlist scopes the catalog to Go and never falls back outside it', async () => {
+  assert.equal(opencodeProviderAllowlist({}), undefined)
+  assert.equal(opencodeProviderAllowlist({ EZ_OPENCODE_PROVIDERS: '  ' }), undefined)
+  assert.deepEqual(opencodeProviderAllowlist({ EZ_OPENCODE_PROVIDERS: 'opencode-go' }), ['opencode-go'])
+  assert.deepEqual(opencodeProviderAllowlist({ EZ_OPENCODE_PROVIDERS: ' opencode-go ,openrouter,opencode-go ' }), ['opencode-go', 'openrouter'])
+  for (const bad of ['Bad Name!', 'has space', 'UPPER', 'a'.repeat(33), ',,,', 'ok,,bad name'])
+    assert.throws(() => opencodeProviderAllowlist({ EZ_OPENCODE_PROVIDERS: bad }), /one to sixteen unique provider IDs/)
+  const verbose = [
+    'opencode/mimo-free',
+    JSON.stringify({ id: 'mimo-free', providerID: 'opencode', name: 'Mimo Free', variants: {} }),
+    'opencode-go/muse-spark-1.3-contributor',
+    JSON.stringify({ id: 'muse-spark-1.3-contributor', providerID: 'opencode-go', name: 'Muse Spark 1.3 Contributor',
+      variants: { high: {}, xhigh: {} } }),
+    'openrouter/some/model',
+    JSON.stringify({ id: 'some/model', providerID: 'openrouter', name: 'Some', variants: {} }),
+  ].join('\n')
+  const runner = async () => verbose
+  const prior = process.env.EZ_OPENCODE_PROVIDERS
+  try {
+    process.env.EZ_OPENCODE_PROVIDERS = 'opencode-go'
+    const scoped = await readModels(undefined, async (cli) => cli === 'opencode', undefined as never, runner)
+    assert.deepEqual(scoped.map((m) => m.model), ['opencode-go/muse-spark-1.3-contributor'])
+    await assert.rejects(
+      validateSelection({ id: 'free', name: 'Free', cli: 'opencode', model: 'opencode/mimo-free' }, scoped, async () => true),
+      /installed client catalog/)
+    process.env.EZ_OPENCODE_PROVIDERS = 'missing-provider'
+    assert.deepEqual(await readModels(undefined, async (cli) => cli === 'opencode', undefined as never, runner), [])
+    delete process.env.EZ_OPENCODE_PROVIDERS
+    assert.equal((await readModels(undefined, async (cli) => cli === 'opencode', undefined as never, runner)).length, 3)
+  } finally {
+    if (prior === undefined) delete process.env.EZ_OPENCODE_PROVIDERS
+    else process.env.EZ_OPENCODE_PROVIDERS = prior
+  }
+})
+test('explicit host binding allowlist overrides the process environment', async () => {
+  const runner = async () => 'opencode/a\nopencode-go/b\n'
+  const only = (models: { cli: string; model?: string }[]) => models.filter((m) => m.cli === 'opencode').map((m) => m.model)
+  const prior = process.env.EZ_OPENCODE_PROVIDERS
+  try {
+    process.env.EZ_OPENCODE_PROVIDERS = 'opencode'
+    assert.deepEqual(only(await readModels(undefined, async () => true, undefined as never, runner)), ['opencode/a'])
+    assert.deepEqual(only(await readModels(undefined, async () => true, undefined as never, runner, undefined, ['opencode-go'])), ['opencode-go/b'])
+    assert.deepEqual(only(await readModels(undefined, async () => true, undefined as never, runner, undefined, undefined)), ['opencode/a'])
+  } finally {
+    if (prior === undefined) delete process.env.EZ_OPENCODE_PROVIDERS
+    else process.env.EZ_OPENCODE_PROVIDERS = prior
+  }
+})
+
+test('opencode model and variant selections validate against the installed catalog', async () => {
+  const catalog = [
+    { cli: 'opencode', model: 'opencode/ling-free', name: 'Ling Free · opencode/ling-free', efforts: ['low', 'medium'] },
+    { cli: 'opencode', model: 'opencode/big-pickle', name: 'Big Pickle · opencode/big-pickle', efforts: [] },
+  ]
+  const available = async (cli: string) => cli === 'opencode'
+  await validateSelection({ id: 'choice', name: 'Ling', cli: 'opencode', model: 'opencode/ling-free', effort: 'low' }, catalog, available)
+  await validateSelection({ id: 'default', name: 'Default', cli: 'opencode', model: 'opencode/big-pickle' }, catalog, available)
+  await assert.rejects(
+    validateSelection({ id: 'bad', name: 'Bad', cli: 'opencode', model: 'opencode/ling-free', effort: 'max' }, catalog, available),
+    /installed client catalog/)
+  await assert.rejects(
+    validateSelection({ id: 'missing', name: 'Missing', cli: 'opencode', model: 'opencode/unknown' }, catalog, available),
+    /installed client catalog/)
+})
+
+test('pi does not borrow an unrelated OpenCode catalog', async () => {
+  const runner = async () => [
+    'opencode-go/muse-spark-1.3-contributor',
+    JSON.stringify({ id: 'muse-spark-1.3-contributor', providerID: 'opencode-go', name: 'Muse Spark 1.3 Contributor', variants: { high: {}, xhigh: {} } }),
+  ].join('\n')
+  const catalog = await readModels(undefined, async (cli) => cli === 'pi', undefined as never, runner)
+  assert.deepEqual(catalog, [{ cli: 'pi', name: 'Pi · client default', efforts: [] }])
+  assert.equal(isPreset({ id: 'x', name: 'Pi', cli: 'pi' }), true)
+  for (const cli of ['unreal-agent', 'antigravity', 'agy'])
+    assert.equal(isPreset({ id: 'x', name: 'Unavailable', cli }), false)
+  await validateSelection({ id: 'choice', name: 'Default', cli: 'pi' }, catalog, async (cli) => cli === 'pi')
+  await assert.rejects(
+    validateSelection(
+      { id: 'bad', name: 'Bad', cli: 'pi', model: 'opencode-go/muse-spark-1.3-contributor', effort: 'max' },
+      catalog, async (cli) => cli === 'pi'),
+    /installed client catalog/)
+})
+
+test('model catalog merges user-curated entries ahead of discovered ones', async () => {
+  const control = await mkdtemp(join(tmpdir(), 'ez-catalog-curated-'))
+  const home = await mkdtemp(join(tmpdir(), 'ez-catalog-curated-home-'))
+  try {
+    await mkdir(join(home, '.codex'))
+    await writeFile(join(home, '.codex/models_cache.json'), JSON.stringify({ models: [
+      { slug: 'fixture-model', display_name: 'Fixture', visibility: 'list',
+        supported_reasoning_levels: [{ effort: 'medium' }] },
+    ] }))
+    await writeFile(join(control, 'ai-models.json'), JSON.stringify([
+      { cli: 'pi', model: 'opencode-go/muse-spark-1.3-contributor', name: 'Pi · Muse Spark 1.3', efforts: ['xhigh'] },
+      { cli: 'pi', model: 'opencode-go/muse-spark-1.3-contributor', name: 'Dupe', efforts: [] },
+      { cli: 'codex', model: 'fixture-model', name: 'Curated Fixture', efforts: ['medium'] },
+      { cli: 'nope', model: 'x' },
+      'not-an-entry',
+    ]))
+    const installedOnly = async (cli: string) => cli === 'codex' || cli === 'pi'
+    const noRunner = async (_args: string[]): Promise<string> => { throw new Error('no native CLI in test') }
+    const catalog = await readModels(home, installedOnly, join(home, '.codex'),
+      noRunner, undefined, undefined, control)
+    assert.deepEqual(catalog.filter((m) => m.cli === 'pi'), [
+      { cli: 'pi', model: 'opencode-go/muse-spark-1.3-contributor', name: 'Pi · Muse Spark 1.3', efforts: ['xhigh'] },
+      { cli: 'pi', name: 'Pi · client default', efforts: [] },
+    ])
+    // Curated entries win over the same discovered id and validate for selection.
+    assert.deepEqual(catalog.filter((m) => m.cli === 'codex'), [
+      { cli: 'codex', model: 'fixture-model', name: 'Curated Fixture', efforts: ['medium'] },
+    ])
+    await validateSelection(
+      { id: 'choice', name: 'Spark', cli: 'pi', model: 'opencode-go/muse-spark-1.3-contributor', effort: 'xhigh' },
+      catalog, async (cli) => cli === 'pi')
+    // Missing or malformed curation files fall back to discovery alone.
+    assert.deepEqual(await readCuratedModels(join(control, 'missing-dir')), [])
+    await writeFile(join(control, 'ai-models.json'), 'not json')
+    assert.deepEqual(await readModels(home, async (cli) => cli === 'codex', join(home, '.codex'),
+      noRunner, undefined, undefined, control), [
+      { cli: 'codex', model: 'fixture-model', name: 'Fixture', efforts: ['medium'] },
+    ])
+  } finally {
+    await rm(control, { recursive: true, force: true })
+    await rm(home, { recursive: true, force: true })
+  }
+})
+
+test('curated models respect installed clients and provider scope', async () => {
+  const control = await mkdtemp(join(tmpdir(), 'ez-catalog-scope-'))
+  try {
+    await writeFile(join(control, 'ai-models.json'), JSON.stringify([
+      { cli: 'pi', model: 'opencode-go/allowed', efforts: ['xhigh'] },
+      { cli: 'pi', model: 'other/blocked' },
+      { cli: 'opencode', model: 'other/blocked' },
+      { cli: 'claude', model: 'uninstalled' },
+    ]))
+    const catalog = await readModels(undefined, async (cli) => cli === 'pi', undefined as never,
+      async () => { throw new Error('no OpenCode catalog') }, undefined, ['opencode-go'], control)
+    assert.deepEqual(catalog.filter(entry => entry.model).map(entry => entry.model), ['opencode-go/allowed'])
+    assert.equal(catalog.some(entry => entry.cli === 'pi' && !entry.model), false)
+  } finally { await rm(control, { recursive: true, force: true }) }
+})

package/test/config.test.ts

@@ -23,9 +23,9 @@ test('rejects malformed timeouts', () => {
   assert.throws(() => loadConfig({ TELEGRAM_BOT_TOKEN: '110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsY', EZ_PAIRING_TTL_SECONDS: 'bad' }), /positive integer/)
 })
 
-test('loads executor CLI configuration with agy fallback', () => {
+test('loads executor CLI configuration with codex fallback', () => {
   const defaultConfig = loadConfig({ TELEGRAM_BOT_TOKEN: '110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsY' })
-  assert.equal(defaultConfig.executorCli, 'agy')
+  assert.equal(defaultConfig.executorCli, 'codex')
 
   const customConfig = loadConfig({ TELEGRAM_BOT_TOKEN: '110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsY', EZ_EXECUTOR_CLI: 'claude' })
   assert.equal(customConfig.executorCli, 'claude')

package/test/conversations.test.ts

@@ -66,7 +66,7 @@ test('titles are bounded and rename is durable; malformed IDs and unsupported me
   await assert.rejects(store.listSessions(), /unsupported shape/)
 }))
 
-test('legacy sessions retain IDs; unbound and latest-only engines cannot resume a different context', async () => fixture(async (store, dir) => {
+test('legacy sessions retain IDs; unbound sessions cannot resume a different context', async () => fixture(async (store, dir) => {
   const legacy = await store.ensureActiveSession()
   await store.markSessionStarted(legacy.sessionId)
   await store.captureChoice(initialPreset('grok'))
@@ -74,11 +74,5 @@ test('legacy sessions retain IDs; unbound and latest-only engines cannot resume
   await assert.rejects(store.switchSession(legacy.sessionId), /binding/)
   assert.match(sessionTitle((await store.listSessions()).find(s => s.sessionId === legacy.sessionId)!), /Conversation /)
   await store.archiveSession(legacy.sessionId, true)
-  const agy = { id: 'agy-test', name: 'AGY', cli: 'agy' }
-  await store.savePreset(agy)
-  await store.selectPreset(agy.id, (await store.getActiveSession())!.sessionId, true)
-  const old = await store.captureChoice(agy)
-  await store.markSessionStarted(old.sessionId)
-  await store.resetSession()
-  await assert.rejects(store.switchSession(old.sessionId), /latest conversation/)
+
 }))

package/test/engine-handoff.test.ts

@@ -31,13 +31,13 @@ if(args[0]==='app-server'){
  }
  if(q.method==='thread/goal/get')send({id:q.id,result:{goal:null}});
  });
-}else capture(args.includes('--prompt-file')?fs.readFileSync(args[args.indexOf('--prompt-file')+1],'utf8'):args.some(a=>a.startsWith('--print='))?args.find(a=>a.startsWith('--print=')).slice(8):args.includes('--print')||(args[0]==='exec'&&args.at(-1)==='-')?fs.readFileSync(0,'utf8'):args.at(-1));
+}else capture(args.includes('--prompt-file')?fs.readFileSync(args[args.indexOf('--prompt-file')+1],'utf8'):args.includes('--print')||(args[0]==='exec'&&args.at(-1)==='-')?fs.readFileSync(0,'utf8'):args.at(-1));
 `
- for(const name of ['codex','grok','agy','claude','opencode'])await writeFile(path.join(bin,name),fixture,{mode:0o700})
+ for(const name of ['codex','grok','claude','opencode'])await writeFile(path.join(bin,name),fixture,{mode:0o700})
  const previous={PATH:process.env.PATH,TELEGRAM_BOT_TOKEN:process.env.TELEGRAM_BOT_TOKEN,EZ_EXECUTOR_TRANSPORT:process.env.EZ_EXECUTOR_TRANSPORT}
  process.env.PATH=bin+path.delimiter+process.env.PATH;process.env.TELEGRAM_BOT_TOKEN='do-not-inherit';delete process.env.EZ_EXECUTOR_TRANSPORT
  try {
-  for(const cli of ['codex','grok','agy','claude','opencode'])for(const isResume of [false,true])for(const text of ['  /goal audit list of files and give me a simple list with filenames\n','--help','-','resume']) {
+  for(const cli of ['codex','grok','claude','opencode'])for(const isResume of [false,true])for(const text of ['  /goal audit list of files and give me a simple list with filenames\n','--help','-','resume']) {
    const runId='r_'+cli+'_'+String(isResume)+'_'+Buffer.from(text).toString('hex').slice(0,20)
    await ownerRun(controlDir,runId)
    const job=await startExecutorJob([text],{workspace,controlDir,binDir:bin,cli,runId,timeoutMs:5000,isResume,sessionId:'native-existing',repairEnabled:false})
@@ -51,7 +51,6 @@ if(args[0]==='app-server'){
    }
    if(['codex','claude'].includes(cli))assert.ok(!captured.args.includes('--help'))
    if(cli==='opencode')assert.equal(captured.args.at(-2),'--')
-   if(cli==='agy')assert.ok(captured.args.includes('--print='+text))
    if(cli==='claude')assert.ok(!captured.args.includes('--append-system-prompt-file'))
   }
   for(const [runId,texts] of [['r_schedule_literal',['/goal audit list of files and give me a simple list with filenames']],['r_batch',['first\nline','  second  ']]] as const) {