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

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.1.0-beta.37
+
+- List installed OpenCode models with their provider variants as selectable
+  efforts in Choose AI, chat and scheduled tasks. The relay spawns the
+  installed `opencode` CLI with the whitelisted executor environment, so the
+  menu reflects that CLI's reported catalog; variants pass through verbatim as
+  `run --variant` on every platform. Restricted messaging tasks stay on the
+  audited Codex. The relay image now ships pinned OpenCode 1.18.32 for
+  isolated agents; host-capable agents reuse the host installation.
+- Provision authenticated OpenCode providers per agent through
+  `control/cli/opencode/auth.json`: isolated runs resolve it via an
+  agent-bound data home. Paid models may appear in the catalog; execution
+  depends on valid provider authorization. Host runs keep the installer login
+  and the free tier stays the fallback.
+- Scope selectable OpenCode catalog entries with `EZ_OPENCODE_PROVIDERS` (e.g.
+  Go only): unlisted providers, including the free tier, leave the menu.
+  Isolated relays read it from their environment; host transports take
+  `opencodeProviders` on the agent's host binding instead. An existing
+  model-less default still follows the native client's provider choice.
+  Existing deployments need an installer-owned bootstrap for the new Compose
+  environment field before their automatic main updater accepts this release.
+- Allow unbound plugins to run through the isolated broker when a different
+  installed plugin declares a host network binding; bound plugins still fail
+  closed on an isolated deployment.
+- Add a Pi native executor with the exact conversation session ID. It offers
+  its native default when no provider scope is set. Owner-curated model choices
+  require Pi's own provider credentials and are filtered by scope. The relay
+  image installs pinned Pi 0.87.1.
+
 ## 0.1.0-beta.36
 
 - Move relay run/outbox/inbox bookkeeping into relay memory behind the control

package/Dockerfile

@@ -9,10 +9,21 @@ COPY . .
 FROM dependencies AS test
 RUN pnpm verify
 FROM dependencies AS runtime
-# Keep this pin aligned with TASK_CODEX_VERSION. Isolated agents run this CLI
-# in the relay; do not bind-mount the operator's ~/.codex.
+# Isolated agents run this CLI in the relay; do not bind-mount the
+# operator's ~/.codex. Pin the reviewed CLI for repeatable release images.
 ARG CODEX_CLI_VERSION=0.153.4
 RUN npm install -g @openai/codex@${CODEX_CLI_VERSION} && command -v codex
+# Isolated agents run the selected CLI in the relay; host-capable agents reuse
+# the host installation instead. OpenCode carries no task-runner pin because
+# restricted messaging tasks stay on the audited Codex above.
+# Pin the reviewed CLI for repeatable release images.
+ARG OPENCODE_CLI_VERSION=1.18.32
+RUN npm install -g opencode-ai@${OPENCODE_CLI_VERSION} && command -v opencode && opencode --version
+# Isolated agents select pi from the relay menu; the binary must resolve on
+# the relay PATH just like codex/opencode above.
+# Pin the reviewed CLI for repeatable release images.
+ARG PI_CLI_VERSION=0.87.1
+RUN npm install -g @earendil-works/pi-coding-agent@${PI_CLI_VERSION} && command -v pi
 RUN chmod +x docker/entrypoint.sh bin/ez bin/ezenciel-agents* && mkdir -p /state/control /state/home /workspace && chown node:node /state/control /state/home /workspace
 RUN node -e 'for (const [name, target] of Object.entries(require("./package.json").bin)) require("node:fs").symlinkSync("/app/" + target, "/usr/local/bin/" + name); require("node:fs").symlinkSync("/app/bin/ez", "/usr/local/bin/ez")'
 # Build identity for relay status (package version stays release-owned).

package/THIRD_PARTY_NOTICES.md

@@ -8,7 +8,10 @@ The container is built locally; no bundled third-party binary image is promised.
 
 Direct runtime dependencies: grammy (MIT), tsx (MIT). Development dependencies
 include TypeScript (Apache-2.0) and Node type definitions (MIT). The runtime
-image installs ffmpeg, Debian packages, and pinned `@openai/codex` (Apache-2.0):
-redistributing that image requires review of its exact package build, notices and
-corresponding-source obligations. Docker and a host-capable AI CLI remain
-separately installed products, not covered by this repository's MIT license.
+image installs ffmpeg, Debian packages, and these reviewed CLI versions:
+`@openai/codex` 0.153.4 (Apache-2.0), `opencode-ai` 1.18.32 (MIT), and
+`@earendil-works/pi-coding-agent` 0.87.1 (MIT). Redistributing the image
+requires review of its exact package build, notices and corresponding-source
+obligations. Docker and
+host-capable AI CLIs remain separately installed products, not covered by this
+repository's MIT license.

package/compose.yaml

@@ -28,6 +28,7 @@ services:
       EZ_CONTROL_DIR: ${EZ_CONTROL_DIR:?Set this agent control directory}
       EZ_EXECUTOR_CLI: ${EZ_EXECUTOR_CLI:?Set the host installation CLI}
       EZ_CODEX_SANDBOX: ${EZ_CODEX_SANDBOX:-}
+      EZ_OPENCODE_PROVIDERS: ${EZ_OPENCODE_PROVIDERS:-}
       EZ_CODEX_AUTO_COMPACT_TOKENS: ${EZ_CODEX_AUTO_COMPACT_TOKENS:-64000}
       EZ_EXECUTOR_TIMEOUT_SECONDS: ${EZ_EXECUTOR_TIMEOUT_SECONDS:-300}
     secrets: [relay_env]

package/docs/architecture/ai-selection.md

@@ -34,8 +34,16 @@ References used for the adapter contract:
 - [OpenCode native run events](https://github.com/anomalyco/opencode/blob/dev/packages/opencode/src/cli/cmd/run.ts)
 
 The catalog is local metadata, not an authentication or billing health check.
-Grok/Codex support explicit listed model/effort choices. Other installed clients
-offer their own default only in this slice. Refresh by opening the native client;
+Grok/Codex/OpenCode support explicit listed model/effort choices. Other installed clients
+offer their own default only in this slice. OpenCode lists the installed `opencode models`
+catalog with the whitelisted executor environment, so only models the relay can actually
+run are offered; provider variants become selectable efforts (`--variant`).
+Authenticated providers appear only when the agent-bound
+`control/cli/opencode/auth.json` binding exists (host runs keep the installer
+login); otherwise the free tier lists. `EZ_OPENCODE_PROVIDERS` optionally
+restricts the catalog to named providers (e.g. `opencode-go`); a set
+allowlist that matches nothing offers no OpenCode choice rather than falling
+back outside it. Refresh by opening the native client;
 the relay does not install models, manage subscriptions or guess aliases.
 
 Setup initialization and relay startup seed one default choice per installed client.

package/docs/docker-runtime.md

@@ -239,6 +239,25 @@ workspace (a tenant farm), while allowing explicitly shared and additional
 workspace grants and leaving `$HOME` readable for the host CLI.
 Codex then uses `danger-full-access` so it does not apply a nested Seatbelt.
 
+## OpenCode auth
+
+Isolated agents run the image OpenCode with `XDG_DATA_HOME` set to the
+agent-bound `control/cli` directory only when the owner provisioned
+`control/cli/opencode/auth.json` there (mode `600`, copied once from the host
+`opencode auth login`). Authenticated providers then list and run; otherwise
+only the free tier is offered and paid turns fail closed with the provider
+error. Only the directory path crosses into the executor environment, never a
+secret. Host-capable agents reuse the host login and ignore the binding.
+
+`EZ_OPENCODE_PROVIDERS` optionally restricts the catalog to named providers,
+e.g. `opencode-go` for Go credentials only. Isolated relays read it from
+their environment (`docker.env` through the relay `environment`); the host
+transport is spawned with a scrubbed environment, so host-capable agents set
+`opencodeProviders` on the agent's `host-executor.json` binding instead
+(validated the same way, unknown fields ignored by older releases). Unset or
+absent means unfiltered; a set scope that matches nothing offers no OpenCode
+choice rather than falling back outside it.
+
 ## Chat latency
 
 Interactive Codex CLI turns resume the existing native session and use native

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jc_stack/ez-agents",
-  "version": "0.1.0-beta.36",
+  "version": "0.1.0-beta.37",
   "private": false,
   "type": "module",
   "description": "A lightweight foundation for persistent business AI assistants using existing AI harnesses, workspaces and plugins.",

package/src/ai-cli.ts

@@ -12,7 +12,7 @@ if(values.help){
 }
 if (!process.env.EZ_CONTROL_DIR) throw new Error('Use this agent’s bound control directory')
 const catalog=await readFile(join(process.env.EZ_CONTROL_DIR,'host-executor','models.json'),'utf8')
-  .then(text=>JSON.parse(text)).catch(()=>readModels(undefined,undefined,join(process.env.EZ_CONTROL_DIR!,'cli','codex')))
+  .then(text=>JSON.parse(text)).catch(()=>readModels(undefined,undefined,join(process.env.EZ_CONTROL_DIR!,'cli','codex'),undefined,undefined,undefined,process.env.EZ_CONTROL_DIR))
 if(positionals[0]==='list')console.log(JSON.stringify(catalog))
 else if(positionals[0]==='select'){
   const preset:AiPreset={id:randomBytes(8).toString('hex'),name:[values.provider,values.model||values.cli,values.effort].filter(Boolean).join(' · '),cli:values.cli||'',provider:values.provider,model:values.model,effort:values.effort}

package/src/ai.ts

@@ -1,20 +1,25 @@
 import { assertEffort, allowedEffort } from './model-policy.js'
 import { access, readFile } from 'node:fs/promises'
 import { constants } from 'node:fs'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
 import { homedir } from 'node:os'
 import { join, delimiter } from 'node:path'
-import { executorKey, resolveExecutor } from './executor.js'
+import { executorEnvironment, executorKey, resolveExecutor } from './executor.js'
 import { desktopCodexPath } from './desktop-bridge.js'
 
 export type AiPreset = { id: string; name: string; cli: string; provider?: string; model?: string; effort?: string }
 export type ExecutionChoice = { sessionId: string; preset: AiPreset }
 export type ModelChoice = { cli: string; provider?: string; model?: string; name: string; efforts: string[] }
 const safe = (s: unknown): s is string => typeof s === 'string' && /^[a-zA-Z0-9_./:-]{1,160}$/.test(s)
+const knownClis = ['grok', 'codex', 'codex-gui', 'claude', 'opencode', 'agy', 'pi']
+const nativeEffort = (cli: string, effort: string) =>
+  cli === 'pi' ? ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'].includes(effort) : true
 export const isPreset = (p: unknown): p is AiPreset => {
   if (!p || typeof p !== 'object') return false
   const v = p as AiPreset
   return safe(v.id) && typeof v.name === 'string' && v.name.length > 0 && v.name.length <= 80 &&
-    ['grok', 'codex', 'codex-gui', 'claude', 'opencode', 'agy'].includes(v.cli) &&
+    knownClis.includes(v.cli) &&
     (v.provider === undefined || safe(v.provider)) && (v.model === undefined || safe(v.model)) && (v.effort === undefined || safe(v.effort))
 }
 export const isExecutionChoice = (v: unknown): v is ExecutionChoice => {
@@ -45,7 +50,81 @@ export const installed = async (cli: string): Promise<boolean> => {
 
 // Read only metadata from native client catalogs. Never import prompts, credentials,
 // provider configuration, or model instructions into relay context.
-export const readModels = async (home = homedir(), available = installed, codexHome = join(home, '.codex')): Promise<ModelChoice[]> => {
+// The optional runner injects `opencode models` output in tests; production
+// spawns the installed CLI with the whitelisted executor environment.
+export const readOpencodeModels = async (run?: (args: string[]) => Promise<string>, dataHome?: string): Promise<ModelChoice[]> => {
+  const exec = run ?? (async (args: string[]) =>
+    (await promisify(execFile)('opencode', args, { env: { ...executorEnvironment(), ...(dataHome ? { XDG_DATA_HOME: dataHome } : {}) }, timeout: 8000, maxBuffer: 4 * 1024 * 1024 })).stdout)
+  const record = (value: unknown): Record<string, unknown> =>
+    value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
+  try {
+    const stdout = await exec(['models', '--verbose'])
+    // Verbose output alternates a `provider/model` identifier line with its
+    // pretty-printed JSON metadata (name, variants). Split on identifier lines
+    // so variant keys can be projected as selectable efforts.
+    const segments = stdout.split(/^([A-Za-z0-9_.\-]+\/[A-Za-z0-9_./:~\-]+)$/m)
+    const entries: ModelChoice[] = []
+    for (let index = 1; index + 1 < segments.length; index += 2) {
+      const id = segments[index].trim()
+      if (!safe(id)) continue
+      let meta: Record<string, unknown>
+      try { meta = record(JSON.parse(segments[index + 1])) } catch { continue }
+      const friendly = typeof meta.name === 'string' ? meta.name.trim() : ''
+      const efforts = Object.keys(record(meta.variants))
+        .filter((effort) => safe(effort) && allowedEffort(effort, id, 'opencode'))
+      entries.push({ cli: 'opencode', model: id,
+        name: (friendly ? `${friendly} · ${id}` : id).slice(0, 80), efforts })
+    }
+    if (entries.length) return entries
+  } catch { /* fall through to the plain list, then the client default */ }
+  try {
+    const stdout = await exec(['models'])
+    const entries: ModelChoice[] = []
+    for (const line of stdout.split(/\r?\n/)) {
+      const id = line.trim()
+      if (!id || !safe(id)) continue
+      entries.push({ cli: 'opencode', model: id, name: id.slice(0, 80), efforts: [] })
+    }
+    if (entries.length) return entries
+  } catch { /* unavailable metadata stays client default */ }
+  return []
+}
+
+// User-curated entries live in the agent's own setup (control/ai-models.json),
+// never in the repo. They pin models the native catalogs may not currently
+// serve (e.g. paid tiers) and merge ahead of discovered entries, so selection
+// validation accepts them.
+export const readCuratedModels = async (controlDir?: string): Promise<ModelChoice[]> => {
+  if (!controlDir) return []
+  const curated: ModelChoice[] = []
+  const seen = new Set<string>()
+  try {
+    const raw = JSON.parse(await readFile(join(controlDir, 'ai-models.json'), 'utf8'))
+    if (!Array.isArray(raw)) return []
+    for (const candidate of raw) {
+      if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) continue
+      const entry = candidate as Record<string, unknown>
+      if (typeof entry.cli !== 'string' || !knownClis.includes(entry.cli)) continue
+      if (entry.provider !== undefined && !safe(entry.provider)) continue
+      if (entry.model !== undefined && !safe(entry.model)) continue
+      const key = `${entry.cli}‖${entry.provider ?? ''}‖${entry.model ?? ''}`
+      if (seen.has(key)) continue
+      seen.add(key)
+      curated.push({
+        cli: entry.cli,
+        ...(entry.provider !== undefined ? { provider: entry.provider as string } : {}),
+        ...(entry.model !== undefined ? { model: entry.model as string } : {}),
+        name: (typeof entry.name === 'string' && entry.name ? entry.name : String(entry.model ?? entry.cli)).slice(0, 80),
+        efforts: (Array.isArray(entry.efforts) ? entry.efforts : [])
+          .filter((effort): effort is string => safe(effort))
+          .filter((effort) => allowedEffort(effort, typeof entry.model === 'string' ? entry.model : undefined, entry.cli as string) && nativeEffort(entry.cli as string, effort)),
+      })
+    }
+  } catch { return [] }
+  return curated
+}
+
+export const readModels = async (home = homedir(), available = installed, codexHome = join(home, '.codex'), opencodeRunner?: (args: string[]) => Promise<string>, opencodeDataHome?: string, opencodeAllowlist?: string[], curationDir?: string): Promise<ModelChoice[]> => {
   const models: ModelChoice[] = []
   const record = (value: unknown): Record<string, unknown> =>
     value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
@@ -79,9 +158,56 @@ export const readModels = async (home = homedir(), available = installed, codexH
     models.push(...(desktop.length ? desktop : [{ cli: 'codex-gui', name: 'codex-gui · desktop', efforts: [] }]))
   }
   // Other adapters expose the authenticated client's default, not a guessed catalog.
-  for (const cli of ['claude', 'opencode', 'agy'])
+  for (const cli of ['claude', 'agy'])
     if (await available(cli)) models.push({ cli, name: `${cli} · client default`, efforts: [] })
-  return models
+  const allow = opencodeAllowlist ?? opencodeProviderAllowlist()
+  if (await available('opencode')) models.push(...await opencodeCatalogModels(opencodeRunner, opencodeDataHome, allow))
+  // Pi has separate provider configuration. OpenCode's catalog cannot
+  // establish which models Pi can execute.
+  if (!allow && await available('pi')) models.push({ cli: 'pi', name: 'Pi · client default', efforts: [] })
+  const curated = await readCuratedModels(curationDir)
+  if (!curated.length) return models
+  const scoped: ModelChoice[] = []
+  for (const entry of curated) {
+    if (!(await available(entry.cli))) continue
+    if (['opencode', 'pi'].includes(entry.cli) && allow &&
+        (entry.model === undefined || !allow.includes(entry.model.split('/')[0]))) continue
+    scoped.push(entry)
+  }
+  const key = (m: { cli: string; provider?: string; model?: string }) => `${m.cli}‖${m.provider ?? ''}‖${m.model ?? ''}`
+  const curatedKeys = new Set(scoped.map(key))
+  return [...scoped, ...models.filter((m) => !curatedKeys.has(key(m)))]
+}
+export const opencodeCatalogModels = async (
+  opencodeRunner?: (args: string[]) => Promise<string>,
+  opencodeDataHome?: string,
+  opencodeAllowlist?: string[],
+): Promise<ModelChoice[]> => {
+  const discovered = await readOpencodeModels(opencodeRunner, opencodeDataHome)
+  const allow = opencodeAllowlist ?? opencodeProviderAllowlist()
+  const scoped = allow ? discovered.filter((m) => m.model && allow.includes(m.model.split('/')[0])) : discovered
+  if (scoped.length) return scoped
+  // A set allowlist that matches nothing offers no choice rather than falling
+  // back outside the allowed providers.
+  if (allow) return []
+  return [{ cli: 'opencode', name: 'opencode · client default', efforts: [] as string[] }]
+}
+
+// Optional deployment-scoped restriction of the OpenCode catalog to named
+// providers (e.g. EZ_OPENCODE_PROVIDERS=opencode-go). Unset means unfiltered.
+// Reads process env directly like OPENCODE_MODEL; malformed values fail fast
+// so /ai reports the misconfiguration instead of a silently wrong list.
+const providerId = (p: unknown): p is string => typeof p === 'string' && /^[a-z][a-z0-9_-]{0,31}$/.test(p)
+export const validateOpencodeProviders = (value: unknown): string[] | undefined => {
+  if (value === undefined) return undefined
+  if (!Array.isArray(value) || !value.length || value.length > 16 || new Set(value).size !== value.length || value.some((p) => !providerId(p)))
+    throw new Error('opencode provider allowlist must be one to sixteen unique provider IDs')
+  return value as string[]
+}
+export const opencodeProviderAllowlist = (env: NodeJS.ProcessEnv = process.env): string[] | undefined => {
+  const raw = env.EZ_OPENCODE_PROVIDERS?.trim()
+  if (!raw) return undefined
+  return validateOpencodeProviders([...new Set(raw.split(',').map((p) => p.trim()).filter(Boolean))])
 }
 
 export const validateSelection = async (p: AiPreset, catalog: ModelChoice[], available = installed): Promise<void> => {

package/src/executor.ts

@@ -103,7 +103,6 @@ export const resolveHostCommand = (command: string, pathValue = process.env.PATH
   }
   throw new Error(`Native CLI ${command} is not executable on the host PATH`)
 }
-
 export type CliAdapter = {
   name: string
   command: string
@@ -210,6 +209,30 @@ export const EXECUTOR_REGISTRY: Record<string, CliAdapter> = {
       return args
     },
   },
+  pi: {
+    name: 'pi',
+    command: 'pi',
+    description: 'Pi coding agent',
+    buildArgs: (opts, _promptFile, promptText) => {
+      if (!opts.controlDir) throw new Error('Pi runs require a bound control directory for sessions')
+      if (opts.effort && !['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'].includes(opts.effort)) throw new Error('Invalid Pi thinking level')
+      const args = ['-p', '--mode', 'json', '--session-dir', path.join(opts.controlDir, 'cli', 'pi', 'sessions')]
+      // Owner-provisioned delivery skill (control/cli/pi/skills/ez-delivery).
+      // Loaded by path, never by prompt text, so the model cannot miss it.
+      try {
+        const skill = path.join(opts.controlDir, 'cli', 'pi', 'skills', 'ez-delivery', 'SKILL.md')
+        accessSync(skill, fsConstants.R_OK)
+        args.push('--skill', path.dirname(skill))
+      } catch { /* runs without the skill exactly as before */ }
+      // Bind Pi to this conversation, not the most recently used session in
+      // the shared directory. --session-id creates or resumes that exact ID.
+      if (opts.sessionId) args.push('--session-id', opts.sessionId)
+      if (opts.model) args.push('--model', opts.model)
+      if (opts.effort) args.push('--thinking', opts.effort)
+      args.push('--', promptText)
+      return args
+    },
+  },
   'codex-gui': {
     name: 'codex-gui',
     command: 'codex',
@@ -262,6 +285,27 @@ export const validateCodexProviderEnvironmentKey = (value: unknown): string => {
 
 export const resolveExecutor = (name?: string): CliAdapter => EXECUTOR_REGISTRY[executorKey(name)]
 
+// Agent-bound OpenCode credentials live at cli/opencode/auth.json, mirroring
+// the Codex binding. Returns the XDG data home (cli/) only when that binding
+// exists; otherwise the host login (host transport) or the unauthenticated
+// free tier (isolated relay) applies. Only a path is ever returned, never a
+// secret.
+export const opencodeDataHome = (controlDir: string): string | undefined => {
+  try {
+    accessSync(path.join(controlDir, 'cli', 'opencode', 'auth.json'), fsConstants.R_OK)
+    return path.join(controlDir, 'cli')
+  } catch { return undefined }
+}
+
+// Pi resolves its provider/model catalog from an agent dir (settings.json,
+// auth.json). Only a path is ever returned, never a secret.
+export const piAgentDir = (controlDir: string): string | undefined => {
+  try {
+    accessSync(path.join(controlDir, 'cli', 'pi', 'agent', 'auth.json'), fsConstants.R_OK)
+    return path.join(controlDir, 'cli', 'pi', 'agent')
+  } catch { return undefined }
+}
+
 export const grokInvocation = (
   options: Pick<ExecutorOptions, 'workspace' | 'isResume'>,
   promptFile: string,
@@ -363,6 +407,22 @@ export const startExecutorJob = async (
     }
     environment.CODEX_HOME = home
   }
+  if (!host && !gui && key === 'opencode') {
+    // Point OpenCode at the agent-bound data home (cli/opencode/auth.json)
+    // when the owner provisioned it. Host runs keep the installer login;
+    // without a binding the CLI falls back to its free tier. Fail closed at
+    // runtime with the provider error, never with a guessed credential.
+    const dataHome = opencodeDataHome(options.controlDir)
+    if (dataHome) environment.XDG_DATA_HOME = dataHome
+  }
+  if (!host && !gui && key === 'pi') {
+    // Point Pi at the agent-bound config dir (cli/pi/agent/auth.json) when
+    // the owner provisioned it. Without a binding Pi falls back to the relay
+    // home config. Fail closed at runtime with the provider error, never with
+    // a guessed credential.
+    const agentDir = piAgentDir(options.controlDir)
+    if (agentDir) environment.PI_CODING_AGENT_DIR = agentDir
+  }
   if (denies.length) {
     const profile = path.join(outputDirectory, 'workspace.sb')
     await writeFile(profile, macosWorkspaceProfile(denies, [

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 } from './ai.js'
 import type { ChildProcess } from 'node:child_process'
 import { taskWorkspace } from './task-workspace.js'
 import { packageVersion } from './version.js'
@@ -17,7 +17,7 @@ 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[] }
 
 const processStart = async (pid:number) => (await processSnapshot()).get(pid)?.birth
@@ -35,7 +35,8 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
   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)
@@ -51,6 +52,7 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
       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) {

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/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

@@ -105,6 +105,7 @@ const printStatus = (status: { active: string; items: ExecutorStatus[] }): void
   console.log('            pnpm run setup agy')
   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,180 @@ 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)
+  assert.equal(isPreset({ id: 'x', name: 'Unavailable', cli: 'unreal-agent' }), 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/executor.test.ts

@@ -6,7 +6,7 @@ import { mkdtemp, mkdir, rm, writeFile, readFile } from 'node:fs/promises'
 import { spawn } from 'node:child_process'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
-import { EXECUTOR_REGISTRY, antigravityInvocation, executorEnvironment, grokInvocation, grokJobEnv, opencodeInvocation, resolveExecutor, resolveHostCommand, startExecutorJob, terminateJob, validateCodexProvider } from '../src/executor.js'
+import { EXECUTOR_REGISTRY, antigravityInvocation, executorEnvironment, grokInvocation, grokJobEnv, opencodeDataHome, opencodeInvocation, piAgentDir, resolveExecutor, resolveHostCommand, startExecutorJob, terminateJob, validateCodexProvider } from '../src/executor.js'
 import { requireOwnerExecution } from '../src/execution-authority.js'
 import { splitTelegramText } from '../src/reply.js'
 import { matchingProcessIds, processSnapshot } from '../src/process-tree.js'
@@ -125,6 +125,7 @@ test('resolveExecutor correctly maps keys and aliases', () => {
   assert.equal(resolveExecutor('grok').command, 'grok')
   assert.equal(resolveExecutor('opencode').command, 'opencode')
   assert.equal(resolveExecutor('oc').command, 'opencode')
+  assert.throws(() => resolveExecutor('unreal-agent'), /Unsupported executor CLI/)
   assert.equal(resolveExecutor('codex-gui').name, 'codex-gui')
   assert.notEqual(resolveExecutor('codex-gui').name, resolveExecutor('codex').name)
   assert.equal(resolveExecutor(undefined).command, 'agy')
@@ -177,6 +178,114 @@ test('Codex custom providers use declared runtime state and an environment key r
   assert.throws(()=>validateCodexProvider({...provider,models:[]}),/provider models/)
 })
 
+test('opencode jobs use the agent-bound data home only when its auth binding exists', async t => {
+  const root=await mkdtemp(path.join(tmpdir(),'ez-opencode-auth-'));t.after(()=>rm(root,{recursive:true,force:true}))
+  const bin=path.join(root,'bin');await mkdir(bin)
+  await writeFile(path.join(bin,'opencode'),`#!${process.execPath}\nconst fs=require('fs');fs.writeFileSync(${JSON.stringify(path.join(root,'observed.json'))},JSON.stringify({args:process.argv.slice(2),xdg:process.env.XDG_DATA_HOME,telegram:process.env.TELEGRAM_BOT_TOKEN}));`,{mode:0o755})
+  assert.equal(opencodeDataHome(root),undefined)
+  await mkdir(path.join(root,'cli','opencode'),{recursive:true})
+  assert.equal(opencodeDataHome(root),undefined)
+  await writeFile(path.join(root,'cli','opencode','auth.json'),'{}',{mode:0o600})
+  assert.equal(opencodeDataHome(root),path.join(root,'cli'))
+  const prior={path:process.env.PATH,telegram:process.env.TELEGRAM_BOT_TOKEN,transport:process.env.EZ_EXECUTOR_TRANSPORT}
+  const launch=async(runId:string)=>{
+    await ownerRun(root,runId)
+    process.env.PATH=bin+path.delimiter+prior.path;process.env.TELEGRAM_BOT_TOKEN='relay-secret';delete process.env.EZ_EXECUTOR_TRANSPORT
+    const job=await startExecutorJob(['hello'],{workspace:root,controlDir:root,binDir:bin,runId,timeoutMs:0,cli:'opencode',model:'opencode-go/muse-spark-1.3-contributor',effort:'xhigh'})
+    assert.equal(await new Promise(resolve=>job.child.once('close',resolve)),0);await job.cleanup()
+    return JSON.parse(await readFile(path.join(root,'observed.json'),'utf8'))
+  }
+  try {
+    const bound=await launch('r_ocbound')
+    assert.equal(bound.xdg,path.join(root,'cli'))
+    assert.equal(bound.telegram,undefined)
+    assert.equal(bound.args[bound.args.indexOf('-m')+1],'opencode-go/muse-spark-1.3-contributor')
+    assert.equal(bound.args[bound.args.indexOf('--variant')+1],'xhigh')
+    await rm(path.join(root,'cli','opencode','auth.json'))
+    const free=await launch('r_ocfree')
+    assert.equal(free.xdg,undefined)
+    assert.equal(free.telegram,undefined)
+  } finally {
+    if(prior.path===undefined)delete process.env.PATH;else process.env.PATH=prior.path
+    if(prior.telegram===undefined)delete process.env.TELEGRAM_BOT_TOKEN;else process.env.TELEGRAM_BOT_TOKEN=prior.telegram
+    if(prior.transport===undefined)delete process.env.EZ_EXECUTOR_TRANSPORT;else process.env.EZ_EXECUTOR_TRANSPORT=prior.transport
+  }
+})
+
+test('pi jobs use the agent-bound config dir only when its auth binding exists', async t => {
+  const root=await mkdtemp(path.join(tmpdir(),'ez-pi-auth-'));t.after(()=>rm(root,{recursive:true,force:true}))
+  const bin=path.join(root,'bin');await mkdir(bin)
+  await writeFile(path.join(bin,'pi'),`#!${process.execPath}\nconst fs=require('fs');fs.writeFileSync(${JSON.stringify(path.join(root,'observed.json'))},JSON.stringify({args:process.argv.slice(2),agentDir:process.env.PI_CODING_AGENT_DIR,telegram:process.env.TELEGRAM_BOT_TOKEN}));`,{mode:0o755})
+  assert.equal(piAgentDir(root),undefined)
+  await mkdir(path.join(root,'cli','pi','agent'),{recursive:true})
+  assert.equal(piAgentDir(root),undefined)
+  await writeFile(path.join(root,'cli','pi','agent','auth.json'),'{}',{mode:0o600})
+  assert.equal(piAgentDir(root),path.join(root,'cli','pi','agent'))
+  const prior={path:process.env.PATH,telegram:process.env.TELEGRAM_BOT_TOKEN,transport:process.env.EZ_EXECUTOR_TRANSPORT,agentDir:process.env.PI_CODING_AGENT_DIR}
+  const launch=async(runId:string)=>{
+    await ownerRun(root,runId)
+    process.env.PATH=bin+path.delimiter+prior.path;process.env.TELEGRAM_BOT_TOKEN='relay-secret';delete process.env.EZ_EXECUTOR_TRANSPORT;delete process.env.PI_CODING_AGENT_DIR
+    const job=await startExecutorJob(['hello'],{workspace:root,controlDir:root,binDir:bin,runId,timeoutMs:0,cli:'pi',model:'opencode-go/muse-spark-1.3-contributor',effort:'xhigh'})
+    assert.equal(await new Promise(resolve=>job.child.once('close',resolve)),0);await job.cleanup()
+    return JSON.parse(await readFile(path.join(root,'observed.json'),'utf8'))
+  }
+  try {
+    const bound=await launch('r_pibound')
+    assert.equal(bound.agentDir,path.join(root,'cli','pi','agent'))
+    assert.equal(bound.telegram,undefined)
+    assert.equal(bound.args[bound.args.indexOf('--model')+1],'opencode-go/muse-spark-1.3-contributor')
+    assert.equal(bound.args[bound.args.indexOf('--thinking')+1],'xhigh')
+    await rm(path.join(root,'cli','pi','agent','auth.json'))
+    const free=await launch('r_pifree')
+    assert.equal(free.agentDir,undefined)
+    assert.equal(free.telegram,undefined)
+    // Owner-provisioned delivery skill loads by path; absence keeps prior args.
+    assert.ok(!bound.args.includes('--skill'))
+    await mkdir(path.join(root,'cli','pi','skills','ez-delivery'),{recursive:true})
+    await writeFile(path.join(root,'cli','pi','skills','ez-delivery','SKILL.md'),'# delivery',{mode:0o644})
+    const skilled=await launch('r_piskilled')
+    assert.equal(skilled.args[skilled.args.indexOf('--skill')+1],path.join(root,'cli','pi','skills','ez-delivery'))
+  } finally {
+    if(prior.path===undefined)delete process.env.PATH;else process.env.PATH=prior.path
+    if(prior.telegram===undefined)delete process.env.TELEGRAM_BOT_TOKEN;else process.env.TELEGRAM_BOT_TOKEN=prior.telegram
+    if(prior.transport===undefined)delete process.env.EZ_EXECUTOR_TRANSPORT;else process.env.EZ_EXECUTOR_TRANSPORT=prior.transport
+    if(prior.agentDir===undefined)delete process.env.PI_CODING_AGENT_DIR;else process.env.PI_CODING_AGENT_DIR=prior.agentDir
+  }
+})
+
+test('the pi invocation pins control sessions, model, and thinking level', () => {
+  assert.equal(resolveExecutor('pi').command, 'pi')
+  const args = EXECUTOR_REGISTRY.pi.buildArgs(
+    { workspace: '/agent/mind', controlDir: '/agent/control', sessionId: 'ez-session', isResume: true, model: 'opencode-go/muse-spark-1.3-contributor', effort: 'xhigh' },
+    '/prompt', 'review CAMT')
+  assert.deepEqual(args, ['-p', '--mode', 'json', '--session-dir', '/agent/control/cli/pi/sessions', '--session-id', 'ez-session',
+    '--model', 'opencode-go/muse-spark-1.3-contributor', '--thinking', 'xhigh', '--', 'review CAMT'])
+  const other = EXECUTOR_REGISTRY.pi.buildArgs({ workspace: '/agent/mind', controlDir: '/agent/control', sessionId: 'other-session', isResume: true }, '/prompt', 'other')
+  assert.equal(other[other.indexOf('--session-id') + 1], 'other-session')
+  assert.ok(!other.includes('--continue'))
+  assert.throws(() => EXECUTOR_REGISTRY.pi.buildArgs({ workspace: '/agent' }, '/prompt', 'hi'), /bound control directory/)
+})
+
+test('pi jobs run with control-bound sessions and no secret leakage', async t => {
+  const root = await mkdtemp(path.join(tmpdir(), 'ez-pi-auth-')); t.after(() => rm(root, { recursive: true, force: true }))
+  const bin = path.join(root, 'bin'); await mkdir(bin)
+  await writeFile(path.join(bin, 'pi'), `#!${process.execPath}\nconst fs=require('fs');fs.writeFileSync(${JSON.stringify(path.join(root, 'observed.json'))},JSON.stringify({args:process.argv.slice(2),telegram:process.env.TELEGRAM_BOT_TOKEN}));`, { mode: 0o755 })
+  const prior = { path: process.env.PATH, telegram: process.env.TELEGRAM_BOT_TOKEN, transport: process.env.EZ_EXECUTOR_TRANSPORT }
+  try {
+    await ownerRun(root, 'r_pibound')
+    process.env.PATH = bin + path.delimiter + prior.path; process.env.TELEGRAM_BOT_TOKEN = 'relay-secret'; delete process.env.EZ_EXECUTOR_TRANSPORT
+    const job = await startExecutorJob(['review CAMT'], { workspace: root, controlDir: root, binDir: bin, runId: 'r_pibound', timeoutMs: 0, cli: 'pi', model: 'opencode-go/muse-spark-1.3-contributor', effort: 'xhigh' })
+    assert.equal(await new Promise(resolve => job.child.once('close', resolve)), 0); await job.cleanup()
+    const observed = JSON.parse(await readFile(path.join(root, 'observed.json'), 'utf8'))
+    assert.deepEqual(observed.args, ['-p', '--mode', 'json', '--session-dir', path.join(root, 'cli', 'pi', 'sessions'),
+      '--model', 'opencode-go/muse-spark-1.3-contributor', '--thinking', 'xhigh', '--', 'review CAMT'])
+    assert.equal(observed.telegram, undefined)
+  } finally {
+    if (prior.path === undefined) delete process.env.PATH; else process.env.PATH = prior.path
+    if (prior.telegram === undefined) delete process.env.TELEGRAM_BOT_TOKEN; else process.env.TELEGRAM_BOT_TOKEN = prior.telegram
+    if (prior.transport === undefined) delete process.env.EZ_EXECUTOR_TRANSPORT; else process.env.EZ_EXECUTOR_TRANSPORT = prior.transport
+  }
+})
 test('a configured Codex provider receives only its declared key and runtime selection', async t => {
   const root=await mkdtemp(path.join(tmpdir(),'ez-codex-provider-'));t.after(()=>rm(root,{recursive:true,force:true}))
   const bin=path.join(root,'bin');await mkdir(bin)

package/test/host-executor.test.ts

@@ -22,7 +22,7 @@ test('host restart replaces a lock whose PID was reused by another process',asyn
     await mkdir(workspace);await mkdir(directory,{recursive:true})
     await writeFile(path.join(directory,'worker.lock'),JSON.stringify({pid:process.pid,started:'reused-pid'}))
     server=serveHostExecutor({cli:'grok',agents:[{name:'test',workspace,controlDir,binDir:root}]},abort.signal)
-    for(let n=0;n<100;n++){try{await readFile(path.join(directory,'heartbeat.json'));break}catch{await new Promise(r=>setTimeout(r,20))}}
+    for(let n=0;n<300;n++){try{await readFile(path.join(directory,'heartbeat.json'));break}catch{await new Promise(r=>setTimeout(r,20))}}
     await readFile(path.join(directory,'heartbeat.json'))
     const lock=JSON.parse(await readFile(path.join(directory,'worker.lock'),'utf8'))
     assert.equal(lock.pid,process.pid)
@@ -47,6 +47,16 @@ test('isolated installations cannot start host transport', async () => {
   abort.abort()
 })
 
+test('host bindings reject invalid opencode provider scopes before touching state', async () => {
+  const abort=new AbortController()
+  for (const opencodeProviders of [['BAD NAME'], [], ['ok', 'ok'], new Array(17).fill('ok')]) {
+    await assert.rejects(serveHostExecutor({cli:'grok',agents:[{
+      name:'t',workspace:'/tmp/ez-scope-x',controlDir:'/tmp/ez-scope-y',binDir:'/tmp/ez-scope-z',opencodeProviders} as never]},abort.signal),
+      /one to sixteen unique provider IDs/)
+  }
+  abort.abort()
+})
+
 test('host restart clears dead native lease only after proving previous CLI stopped',async()=>{
   const root=await mkdtemp(path.join(tmpdir(),'ez-native-recovery-'));
   const workspace=path.join(root,'mind'),controlDir=path.join(root,'control'),toolsHome=path.join(root,'tools'),directory=path.join(controlDir,'host-executor');
@@ -63,7 +73,7 @@ test('host restart clears dead native lease only after proving previous CLI stop
     await readFile(path.join(toolsHome,'workspace-writer.lock'));
     await writeFile(path.join(directory,'r_old.process.json'),JSON.stringify({pid:deadPid}));
     server=serveHostExecutor(installation,abort.signal);
-    for(let n=0;n<100;n++){try{await readFile(path.join(directory,'heartbeat.json'));break}catch{await new Promise(r=>setTimeout(r,20))}}
+    for(let n=0;n<300;n++){try{await readFile(path.join(directory,'heartbeat.json'));break}catch{await new Promise(r=>setTimeout(r,20))}}
     await readFile(path.join(directory,'heartbeat.json'));
     await assert.rejects(readFile(path.join(toolsHome,'workspace-writer.lock')),{code:'ENOENT'});
   }finally{abort.abort();await server;await rm(root,{recursive:true,force:true});}
@@ -173,7 +183,7 @@ test('one installed CLI executes two agent bindings with separate minds and sani
     server=serveHostExecutor({cli:'grok',agents},abort.signal)
     for(const agent of agents){
       const dir=path.join(agent.controlDir,'host-executor')
-      for(let n=0;n<100;n++){try{await readFile(path.join(dir,'heartbeat.json'));break}catch{await new Promise(r=>setTimeout(r,20))}}
+      for(let n=0;n<300;n++){try{await readFile(path.join(dir,'heartbeat.json'));break}catch{await new Promise(r=>setTimeout(r,20))}}
       assert.equal(JSON.parse(await readFile(path.join(dir,'heartbeat.json'),'utf8')).version,packageVersion)
       const release = await workspaceLease(agent.toolsHome)
       await ownerRun(agent.controlDir, `r_${agent.name}`)

package/test/plugin-manager.test.mjs

@@ -276,6 +276,23 @@ test('isolated broker host binding validates exact mounts without deployment sym
   if(previous===undefined)delete process.env.EZ_DOCKER_COMPOSE;else process.env.EZ_DOCKER_COMPOSE=previous;
  }
 });
+test('isolated broker allows unbound plugins when another plugin has host binding',async t=>{
+ const f=await fixture(t),p=await snapshot(f.source),isolated=path.join(f.root,'isolated-other'),workspace=path.join(isolated,'workspace'),control=path.join(isolated,'control'),hostConfig=path.join(isolated,'host-executor.json'),previous=process.env.EZ_DOCKER_COMPOSE;
+ await fs.mkdir(f.home,{recursive:true});await fs.mkdir(workspace,{recursive:true});await fs.mkdir(control,{recursive:true});
+ await fs.writeFile(hostConfig,JSON.stringify({cli:'codex',isolation:'isolated',agents:[{name:'sample',workspace,controlDir:control,binDir:path.join(f.root,'bin'),toolsHome:f.home}]}));
+ const record={source:p.source,project:'ezp-synthetic',revision:p.revision,manifest:p.manifest,deployment:p.deployment};
+ const config={workspace:await fs.realpath(workspace),hostConfig:await fs.realpath(hostConfig)};
+ await fs.writeFile(hostConfig,JSON.stringify({cli:'codex',isolation:'isolated',agents:[{name:'sample',workspace,controlDir:control,binDir:path.join(f.root,'bin'),toolsHome:f.home,pluginNetworkBindings:{voice:{revisions:[p.revision],bindings:[{service:'sample',network:'voice_default'}]}}}]}));
+ process.env.EZ_DOCKER_COMPOSE='standalone';
+ try {
+  const c=await compose(config,record,{},f.home);
+  assert.equal(c.version,'3.8');assert.equal(c.networks,undefined);
+  await fs.writeFile(hostConfig,JSON.stringify({cli:'codex',isolation:'isolated',agents:[{name:'sample',workspace,controlDir:control,binDir:path.join(f.root,'bin'),toolsHome:f.home,pluginNetworkBindings:{sample:{revisions:[p.revision],bindings:[{service:'sample',network:'sample_default'}]}}}]}));
+  await assert.rejects(compose(config,record,{},f.home),/Isolated broker cannot use host network bindings/);
+ } finally {
+  if(previous===undefined)delete process.env.EZ_DOCKER_COMPOSE;else process.env.EZ_DOCKER_COMPOSE=previous;
+ }
+});
 test('host-owned private networks survive registered-call Compose regeneration',async t=>{
  const f=await fixture(t),p=await snapshot(f.source);await init(f.home,f.workspace);
  await f.call('plugins','install','sample','--source',f.source,'--revision',p.revision);