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

package/docker/run.ts

@@ -4,7 +4,6 @@ import { executorEnvironment, executorInvocation } from '../src/executor.js'
 import { parseEnv } from 'node:util'
 import { writeFile, rm } from 'node:fs/promises'
 import { loadConfig } from '../src/config.js'
-import { recoverInterruptedRuns } from './recovery.js'
 import { createRelay } from '../src/index.js'
 import { packageVersion } from '../src/version.js'
 
@@ -21,18 +20,18 @@ try { privateEnv = parseEnv(readFileSync(3, 'utf8')) } catch (error) {
   if ((error as NodeJS.ErrnoException).code !== 'EINVAL' && (error as NodeJS.ErrnoException).code !== 'EBADF') throw error
 } finally { try { closeSync(3) } catch {} }
 for (const [key, value] of Object.entries(privateEnv)) {
-  if (value !== undefined && ['TELEGRAM_BOT_TOKEN', 'GEMINI_API_KEY', 'OPENAI_API_KEY', 'EZ_CHANNEL_BACKEND_TOKEN', 'PAGERDUTY_ROUTING_KEY'].includes(key)) process.env[key] = value
+  if (value !== undefined && ['TELEGRAM_BOT_TOKEN', 'GEMINI_API_KEY', 'OPENAI_API_KEY', 'EZ_CHANNEL_BACKEND_TOKEN'].includes(key)) process.env[key] = value
 }
 privateEnv = {}
 const [command = 'start', ...args] = process.argv.slice(2)
 process.argv = [process.argv[0], '', ...args]
-if (['start', 'smoke'].includes(command)) await recoverInterruptedRuns(loadConfig().controlDir, Boolean(loadConfig().channelBackendUrl))
 if (command === 'start') {
-  const relay = createRelay(loadConfig())
-  const heartbeat = '/state/control/heartbeat.json'
+  const config = loadConfig()
+  const relay = createRelay(config)
+  const heartbeat = process.env.EZ_HEARTBEAT_FILE || '/tmp/ez-relay-heartbeat.json'
   await rm(heartbeat, { force: true })
   const timer = setInterval(() => {
-    if (relay.isRunning()) void writeFile(heartbeat, JSON.stringify({ at: Date.now(), polling: Boolean(relay.bot?.isRunning()), applicationOnly: process.env.EZ_TELEGRAM_ENABLED === 'false', version: packageVersion }), { mode: 0o600 })
+    if (relay.isRunning()) void writeFile(heartbeat, JSON.stringify({ at: Date.now(), polling: Boolean(relay.bot?.isRunning()), applicationOnly: !relay.telegramEnabled, telegramConfigured: config.telegramBotToken !== '', version: packageVersion }), { mode: 0o600 })
   }, 5000)
   for (const signal of ['SIGINT', 'SIGTERM'] as const) process.once(signal, () => { clearInterval(timer); void relay.stop() })
   try { await relay.start() } finally { clearInterval(timer); await rm(heartbeat, { force: true }) }

package/docker/smoke.mjs

@@ -10,6 +10,7 @@ const volume = `${holder}-control`;
 const application = `${holder}-application`;
 const marker = 'qa-private-secret-never-in-executor';
 writeFileSync(join(dir, 'relay.env'), `TELEGRAM_BOT_TOKEN=${marker}\n`, { mode: 0o600 });
+writeFileSync(join(dir, 'purpose.md'), 'Verify the packaged Ez runtime.\n', { mode: 0o644 });
 writeFileSync(join(dir, 'node'), `#!/bin/sh\nIFS= read -r value <&3\n[ "$value" = "TELEGRAM_BOT_TOKEN=${marker}" ] || exit 91\nexec /usr/local/bin/node "$@"\n`, { mode: 0o555 });
 const run = (args) => spawnSync('docker', args, { encoding: 'utf8', timeout: 60000 });
 try {
@@ -17,17 +18,19 @@ try {
     '--mount',`type=bind,src=${join(dir,'node')},dst=/qa/node,readonly`,'-e','PATH=/qa:/usr/local/bin:/usr/bin:/bin',image,'application','--help']);
   assert.equal(inherited.status,0,inherited.stderr);
   const nonroot = ['--user','20000:20000','--read-only','--cap-drop','ALL','--security-opt','no-new-privileges',
+    '--mount',`type=bind,src=${join(dir,'purpose.md')},dst=/run/agent-purpose.md,readonly`,'-e','EZ_AGENT_PURPOSE_FILE=/run/agent-purpose.md',
     '--tmpfs','/tmp:mode=1777','--tmpfs','/state/control:uid=20000,gid=20000,mode=700',
     '--tmpfs','/state/home:uid=20000,gid=20000,mode=700','--tmpfs','/workspace:uid=20000,gid=20000,mode=700',
-    '-e','EZ_TELEGRAM_ENABLED=false','-e','EZ_APPLICATION_PORT=8110','-e','EZ_EXECUTOR_TRANSPORT=local','-e','EZ_EXECUTOR_CLI=codex'];
+    '-e','EZ_APPLICATION_PORT=8110','-e','EZ_ISOLATION=isolated','-e','EZ_EXECUTOR_TRANSPORT=local','-e','EZ_EXECUTOR_CLI=codex'];
   const help = run(['run','--rm',...nonroot,image,'application','--help']);
   assert.equal(help.status,0,help.stderr);
   assert.match(help.stdout,/ezenciel-agents-application/);
   const login = run(['run','--rm',...nonroot,'--entrypoint','/bin/bash',image,'-lc',
-    'command -v ezenciel-agents-application && command -v ezenciel-agents-message && ezenciel-agents-message --help']);
+    'command -v ezenciel-agents-application && command -v ezenciel-agents-message && command -v codex && ezenciel-agents-message --help && codex --version']);
   assert.equal(login.status,0,login.stderr);
   assert.match(login.stdout,/\/usr\/local\/bin\/ezenciel-agents-application/);
   assert.match(login.stdout,/\/usr\/local\/bin\/ezenciel-agents-message/);
+  assert.match(login.stdout,/codex-cli 0\.153\.4/);
   const started = run(['run','-d','--name',application,...nonroot,image,'start']);
   assert.equal(started.status,0,started.stderr);
   let ready = false;
@@ -69,7 +72,23 @@ try {
   assert.equal(JSON.parse(custom.stdout).uid,20001);
   const failed = run(['run','--rm',image,'exec','node','-e','process.exit(23)']);
   assert.equal(failed.status, 23, failed.stderr);
-  const held = run(['run','-d','--name',holder,'-v',`${volume}:/state/control`,image,'exec','node','-e',"require('fs').writeFileSync('/state/control/ready','yes');setInterval(()=>{},1000)"]);
+  // The live delivery socket is the single-relay guard (it replaced the kernel
+  // flock). This mirrors the relay's own start check: an answering address
+  // refuses the second owner; a stale file is removed before binding.
+  const guardScript = `
+    const net=require('net'),fs=require('fs'),stay=process.argv[1]==='hold',path='/state/control/delivery.sock';
+    const probe=net.createConnection(path);
+    const bind=()=>{
+      fs.rmSync(path,{force:true});
+      const s=net.createServer(()=>{});
+      s.on('error',()=>process.exit(1));
+      s.listen(path,()=>{if(stay){fs.writeFileSync('/state/control/ready','yes');setInterval(()=>{},1000)}else s.close(()=>process.exit(0))});
+    };
+    probe.on('connect',()=>{probe.destroy();process.exit(73)});
+    probe.on('error',bind);
+    probe.setTimeout(3000,()=>{probe.destroy();process.exit(1)});
+  `;
+  const held = run(['run','-d','--name',holder,'-v',`${volume}:/state/control`,image,'exec','node','-e',guardScript,'hold']);
   assert.equal(held.status,0,held.stderr);
   for (let n=0;n<30;n++) {
     const probe=run(['exec',holder,'test','-f','/state/control/ready']);
@@ -77,10 +96,16 @@ try {
     await new Promise(resolve=>setTimeout(resolve,100));
   }
   assert.equal(run(['exec',holder,'test','-f','/state/control/ready']).status,0);
-  const duplicate=run(['run','--rm','-v',`${volume}:/state/control`,image,'exec','node','-e','process.exit(0)']);
+  const duplicate=run(['run','--rm','-v',`${volume}:/state/control`,image,'exec','node','-e',guardScript]);
   assert.equal(duplicate.status,73,duplicate.stderr);
   assert.equal(run(['kill',holder]).status,0);
-  const recovered=run(['run','--rm','-v',`${volume}:/state/control`,image,'exec','node','-e','process.exit(0)']);
-  assert.equal(recovered.status,0,recovered.stderr);
-  console.log('Docker smoke passed: direct non-root application help/start/health/stop, inherited private descriptor, non-root executor, private secret isolation, literal argv, exit code, no Docker socket, duplicate writer rejection and crash lock release.');
+  let released=1;
+  for (let n=0;n<50;n++) {
+    const recovered=run(['run','--rm','-v',`${volume}:/state/control`,image,'exec','node','-e',guardScript]);
+    released=recovered.status;
+    if(released===0)break;
+    await new Promise(resolve=>setTimeout(resolve,100));
+  }
+  assert.equal(released,0,'a dead relay must release the delivery socket');
+  console.log('Docker smoke passed: direct non-root application help/start/health/stop, inherited private descriptor, non-root executor, isolated Codex on PATH, private secret isolation, literal argv, exit code, no Docker socket, live delivery-socket guard and crash release.');
 } finally { run(['rm','-f',holder,application]); run(['volume','rm',volume]); rmSync(dir, {recursive:true, force:true}); }

package/docs/application-channel.md

@@ -6,6 +6,10 @@ outbox. The application supplies domain tools and keeps its UI/content API; it
 can remove its own model runner, continuation loop and engine authentication.
 This is separate from the older outbound channel-backend integration.
 
+Run admission, status and inbox receipts include the immutable `preset` captured
+for that run so an application can label delivered messages with the engine choice
+that actually produced them.
+
 ## Shared runtime controls
 
 Register with `--share-owner` (the existing `--share-telegram` spelling is an
@@ -267,17 +271,36 @@ separate CLI histories. A retry cannot change an admitted turn's AI choice.
 
 Register owner-chat channels with `--share-owner` and submit `followOwner:true`.
 Web, phone and Telegram then use the same selected native conversation and AI.
+A later same-client provider or model change starts a new native conversation for the next
+admitted turn; already-queued work keeps its original engine.
 This works without Telegram and requires no transcript replay or new runner.
 Scoped application conversations remain separate when the flag is omitted.
 Owner identity does not automatically merge histories or grant learner access.
 
-To link Telegram, enable its ordinary bot configuration, send a real DM, then
-approve the observed pending identity using `ezenciel-agents-owner approve ID`.
+To link Telegram, enable its ordinary bot configuration, then use the
+application-initiated handoff below or send a real DM and approve the observed
+pending identity using `ezenciel-agents-owner approve ID`.
 `ezenciel-agents-owner unlink-telegram` removes that channel without removing the
 owner, application bindings or native sessions. Relinking does not authorize old
 Telegram deliveries. Linking other providers requires an authenticated adapter;
 registering the label `phone` does not install a phone service.
 
+### Application-initiated Telegram handoff
+
+An already-authorized `--share-owner` application binding can make the ordinary
+Telegram link easy without becoming a Telegram backend. `GET /v1/telegram`
+returns the current `connected` state. `POST /v1/telegram/link` either returns
+`{connected:true}` or a single-use, short-lived `https://t.me/BOT?start=TOKEN`
+link. The bot accepts that token only from the matching application's current
+owner, then persists the normal Telegram owner/channel record and consumes the
+ticket. The raw token is never stored in control state.
+
+This is a launch handoff, not a UI-owned connection: the application does not
+store Telegram identity, bot credentials, or the ticket, and the Ez agent keeps
+working when that application is unavailable. There is deliberately no
+application disconnect endpoint. Administrative unlink remains the explicit
+owner control above.
+
 The legacy `--share-telegram`, `--share-active` and `followTelegram:true` spellings remain supported.
 
 ### Existing scoped Telegram sharing
@@ -319,12 +342,17 @@ a generic HTTP error or revoked credential alone is not proof of termination.
 
 ## Application-only deployment (no Telegram bot)
 
-For a private per-user native runtime, set `EZ_TELEGRAM_ENABLED=false` and
+For a private per-user native runtime, omit `TELEGRAM_BOT_TOKEN` and set
 `EZ_APPLICATION_PORT` (plus `EZ_APPLICATION_HOST` when other containers connect).
-No bot token is required or used. This mode runs the existing native executor,
+This mode runs the existing native executor,
 application queue and application outbox without creating a Telegram client,
-starting Telegram sources/polling, or registering bot commands. Default deployments
-still enable Telegram and require its token.
+starting Telegram sources/polling, or registering bot commands. Telegram becomes
+active as soon as the agent receives its private bot token.
+
+Upgrade note: the removed `EZ_TELEGRAM_ENABLED` flag is no longer read. A stale
+flag that contradicts the token (disabled flag with a token present, or enabled
+flag with no token) refuses to start — unset the flag, and remove any stale
+`TELEGRAM_BOT_TOKEN` to stay application-only.
 
 The installing administrator can initialize empty control authority and register
 an application in one local command:
@@ -379,14 +407,14 @@ up to 10 MiB decoded; empty files and other types are rejected. Core detects fil
 content rather than trusting a client MIME label. This same limit and staging
 contract apply to Telegram photo/document input.
 
-Authentication precedes staging. Core stages the file privately in the ordinary
-workspace inbox and uses the same attachment metadata and literal comment as
-Telegram. The existing run queue, native executor, selected AI and native session
+Authentication precedes staging. Core stages the file privately under the
+deployment control directory and uses the same attachment metadata and literal
+comment as Telegram. The existing run queue, native executor, selected AI and native session
 remain authoritative; applications must not extract, summarize, convert or build
 attachment prompts. Use `followOwner:true` for the shared owner conversation.
 Retry the same request ID, filename, bytes and literal comment; conflicts return
 409 and successful retries do not stage another file. A failed admission removes
-its staged file; a process crash may leave an unused inbox file, never a runnable
+its staged file; a process crash may leave an unused staged file, never a runnable
 partial request. Separate owner runtimes must retain separate workspace mounts.
 
 This is inbound file support. Application replies currently deliver text only;

package/docs/architecture/ai-selection.md

@@ -8,7 +8,9 @@ At intake each journal entry receives an immutable preset and conversation ID.
 Batches cannot cross that boundary. The run copies that choice and invokes the
 native adapter with its exact model/effort. A later menu change cannot reroute it.
 Old conversation metadata is retained only so accepted work can finish; selecting
-a different CLI never restores that CLI's old history.
+a different CLI never restores that CLI's old history. Selecting a different provider
+or model on the same client does not resume the previous selection's native thread; the next
+admitted turn starts a new native conversation.
 
 Grok/Claude accept caller-selected native UUIDs. Codex/OpenCode generate IDs, so
 the adapter reads only their typed JSONL session metadata; stdout never becomes a

package/docs/architecture/authority-boundaries.md

@@ -127,8 +127,8 @@ Native configuration reference: [Codex configuration](https://learn.chatgpt.com/
 Task notes live under protected `control/tasks/`, separate from the owner mind.
 Exact-contact task reports currently use the linked Telegram owner outbox and
 are visibly labelled; any-conversation runs have no report tool. Reports are not
-inserted as owner instructions or trusted memory. The owner mind
-keeps its existing `inbox/` and `work/` organization. No database or general memory
+inserted as owner instructions or trusted memory. The owner mind is the workspace `AGENTS.md` and files the agent creates.
+No prescribed `inbox/` or `work/` layout is required. No database or general memory
 index is introduced.
 
 ## Provider protocol

package/docs/channel-backend.md

@@ -21,16 +21,17 @@ The response is `{status,reply}`. `queued` or `running` yields and resubmits the
 same event after four seconds. `complete` or `failed` supplies a final string
 reply, queued once with a deterministic outbox ID. Backend completion and
 Telegram delivery are separate; an uncertain send never replays the operation.
-Restart resubmits interrupted backend runs using the original ID. Permanent
+A relay restart drops in-flight relay runs by design; the backend's resubmit of
+the same event is the recovery path. Permanent
 4xx responses leave a failed relay run for operator inspection; transient
 failures back off. No response body or credential is logged.
 
 Native `/new` and AI settings belong to the application. `/stop` cannot cancel
 an application job and explicitly reports that limitation. `/cancel` removes
 pending relay work only; it does not undo work already accepted by a backend.
-External plugin/maintenance wakes do not dispatch through this channel backend.
+External plugin wakes do not dispatch through this channel backend.
 
 Backend mode handles owner Telegram intake only. Existing native schedules,
-restricted messaging tasks, plugin events and maintenance prompts are not
+restricted messaging tasks and plugin events are not
 forwarded to the application and cannot launch a fallback CLI. Their scheduling
 and authority remain separate from the application's own job lifecycle.

package/docs/docker-runtime.md

@@ -1,9 +1,9 @@
 # Docker runtime and shared host CLI
 
-Docker Compose owns each relay and executable plugin. The CLI the user installs
-Ez from stays on the host, with its existing authentication. All agents in that
-installation use that CLI; there is no second CLI installation or agent-specific
-CLI login. The relay image contains Node, relay dependencies and ffmpeg.
+Docker Compose owns each relay and executable plugin. Isolated agents run the
+native CLI from the relay image (pinned Codex). Host-capable agents reuse the
+CLI the user installed Ez from, with its existing authentication. The relay
+image contains Node, relay dependencies, ffmpeg and that pinned Codex CLI.
 The runtime image exposes Ez commands through the wrappers in `/app/bin`, including
 `ezenciel-agents-application`; application images do not need to link Ez themselves.
 The image also installs package-manifest commands in `/usr/local/bin`, so native
@@ -13,26 +13,56 @@ belongs to Ez packaging, not an application image or an engine-specific prompt.
 ## Agent binding
 
 Use [agent-led setup](setup.md). `ezenciel-agents-create` accepts a name, purpose,
+optional `--isolation isolated|host-capable` (default `isolated`),
 a bot token through stdin; the CLI defaults to the one recorded at package
 installation by `--register-cli <current-cli>`. It creates a private deployment
 with a unique Compose project, mind, control directory and secret file. Names
 cannot overwrite existing agents. `installation.json` keeps subsequent agents
 on the same CLI. Each agent gets its own purpose and native conversation IDs.
+`isolated` sets `EZ_EXECUTOR_TRANSPORT=local` and runs the native CLI in the
+relay. `host-capable` sets `host` and reuses the installer UID; unlabeled
+existing host transports stay host-capable so they are not flipped.
+
+On Docker Desktop/OrbStack the control volume's Unix socket is not connectable
+from the macOS host, so a host-capable agent also publishes an authenticated
+loopback ledger endpoint (generated `ledger.compose.yaml` plus
+`EZ_DELIVERY_TCP_PORT` in `docker.env`). The relay writes
+`control/delivery-endpoint.json` (mode 600) with the port and per-start token;
+host CLIs fall back to it when the socket is unreachable, and every request is
+still re-authorized server-side. Isolated agents publish no endpoint. Existing
+host-capable deployments created before this endpoint run
+`ezenciel-agents-install migrate-ledger --deployment <absolute-directory>` once;
+it is idempotent and does not restart services. If the chosen port is taken,
+recreate the agent or edit `EZ_DELIVERY_TCP_PORT` and re-run Compose.
 
 `docker.env` contains explicit absolute paths, never token values:
 
 ```dotenv
 COMPOSE_PROJECT_NAME=ez-agent-family
 EZ_EXECUTOR_CLI=grok
+EZ_ISOLATION=isolated
+EZ_EXECUTOR_TRANSPORT=local
 EZ_AGENT_WORKSPACE=/absolute/private/agents/family/mind
 EZ_CONTROL_DIR=/absolute/private/agents/family/control
 EZ_RELAY_ENV_FILE=/absolute/private/agents/family/relay.env
 EZ_AGENT_PURPOSE_FILE=/absolute/private/agents/family/purpose.md
+EZ_TOOLS_HOME=/absolute/private/agents/family/tools
+EZ_PLUGIN_BROKER_SOCKET=/absolute/private/agents/family/control/plugin-broker.sock
+EZ_PLUGIN_BROKER_HOST_CONFIG=/absolute/private/agents/family/host-executor.json
 ```
 
-The installing agent runs `ezenciel-agents-host` under the host's service manager
+`ezenciel-agents-provision-telegram --config <private-config>` attaches Telegram
+to an existing deployment. The private config names only the compose file,
+project, secret and override paths; it never selects a relay image. The command
+loads the deployment's own `docker.env`, so the relay restarts on its installed
+image and version, then writes only the bot-token secret and a small override
+that enables Telegram. That file must define `EZ_RELAY_IMAGE`; a shell export
+never overrides it, and an incomplete record fails closed.
+
+Host-capable agents run `ezenciel-agents-host` under the host's service manager
 with `EZ_DEPLOYMENT_DIR` bound to that deployment. This small transport invokes
-the existing CLI; it is not a second relay or model loop. It reads requests from
+the existing CLI; it is not a second relay or model loop. Isolated agents do not
+start it. It reads requests from
 the agent's control directory, fixes cwd/control/tool paths from its installation
 binding, strips environment secrets, forwards native output and exit status, and
 propagates cancellation. Requests cannot select another executable. No network
@@ -41,13 +71,18 @@ is required. Host Node 22+ and the package dependencies run this transport.
 
 Mount mind and control at identical absolute paths in Docker and on the host,
 so incoming files, message attachments and CLI outputs need no path translation.
-Only that agent's directories are mounted into its relay. The host CLI reuses the existing login. Codex receives a private per-agent
+Only that agent's directories are mounted into its relay. Host-capable CLI reuses the existing login. Codex receives a private per-agent
 state home with linked authentication; global memory/configuration is excluded.
-This is not an OS security boundary between agents running as the same user.
-Plugin setup also binds `toolsHome` in the host configuration. Codex receives
-write access to that registry and network access for the Docker client; the host
-rejects registries belonging to a different workspace. Restart the host worker
-between jobs after adding a registry binding.
+Host-capable is not an OS security boundary between agents running as the same user.
+Isolated agents use the relay mounts; sibling host paths are not present.
+Plugin setup also binds `toolsHome` in the host configuration. The isolated
+runtime uses a separate `plugin-broker` Compose service: the relay receives only
+the socket client and its normal mind/control mounts, while the broker receives
+that agent's exact tools/workspace/control paths and the Docker socket. The
+broker has no network, validates the host binding and registry owner, and is the
+only service allowed to launch plugin containers. The relay never receives the
+Docker socket or a tools registry mount. Host-capable agents keep the existing
+host executor path instead.
 
 ## Operate and verify
 
@@ -78,19 +113,28 @@ bin/ezenciel-agents-docker up -d --wait
 
 The owner supplies a real DM; verify the pending numeric sender before pairing.
 Live smoke uses the same host CLI and requires an actual Telegram receipt.
-Restart preserves pairing and files. One kernel lock excludes relay/smoke
-writers; exit 73 means a writer is active. Do not delete its lock to bypass it.
+Restart preserves pairing and files. On boot the relay binds the live delivery
+socket as the single-relay guard: a second relay refuses to start while that
+address answers. Do not remove a live socket to bypass the guard.
 Health requires recent polling and host-transport heartbeats, not just a process.
 Relay replacement retains the existing 30-second startup grace and deployment
 layout, so compatible releases remain eligible for agent-owned upgrades.
-An interrupted Telegram poller keeps authorized work and in-flight outbox writes
-alive while it retries intake. A `409 Conflict` still requires the operator to
-stop the competing poller; it remains unhealthy after the startup grace. Pending
-and uncertain deliveries keep their existing outbox/receipt semantics; executor
-stdout is not replayed as a reply.
+An interrupted Telegram poller keeps authorized work and in-flight deliveries
+alive while it retries intake. Run and delivery records are relay memory: a
+relay process restart drops in-flight work by design, Telegram redelivery is the
+intake replay path, and uncertain sends report unknown instead of success.
+A `409 Conflict` still requires the operator to stop the competing poller; it
+remains unhealthy after the startup grace. Pending and uncertain deliveries keep
+their existing receipt semantics; executor stdout is not replayed as a reply.
 Signal and fatal-error paths share one shutdown; a secondary cleanup error is
 reported without replacing the original startup/polling failure.
 
+For an isolated agent, `COMPOSE_PROFILES=isolated` starts both `relay` and
+`plugin-broker`; the `up` command above must not be narrowed to `relay`. The
+broker socket is private to the agent's control directory. Its per-run receipt
+is written under `control/plugin-receipts/<run-id>/`; a plugin's stdout remains
+the provider/API receipt and is not treated as a relay message.
+
 The separate `control-state.lock` serializes authority JSON updates across CLI
 processes. A forced kill or host crash can orphan this exclusive-create sentinel.
 It deliberately has no age/PID-based auto-reclamation: expiry cannot prove that a
@@ -118,6 +162,38 @@ and volume bindings. Never add standalone provider launchers or deployments.
 Read the installed skill from the registry before onboarding; do not re-pair
 an already connected account. Monitoring and sends require their own authority.
 
+### Isolated plugin commands
+
+The relay-side `ez` client sends only declared aliases, literal argument arrays,
+bounded stdin, and the active run ID to the broker. The broker re-reads owner
+authority and the registry before every call, pins the discovered revision, and
+passes only the installed plugin's `run.application.context.plugins[plugin-id]`
+object as `EZ_PLUGIN_CONTEXT`. Missing, revoked, cross-agent, expired, or reused
+admissions fail closed. Timeouts, cancellation and bounded output produce a
+failed broker receipt rather than a retry.
+
+Source-based `plugins inspect`, `catalog-add`, and `install` management calls are
+accepted only for an existing path inside that agent's mounted workspace, with a
+literal SHA-256 revision where the command requires one. The same management
+surface permits data-preserving `plugins uninstall` and local candidate
+`updates prepare/apply/recover`; candidate archives must also be inside the
+workspace. Public update discovery stays with the host supervisor because the
+broker has no network. The broker never turns an arbitrary host path into a
+plugin mount.
+
+Each agent has one registry and one broker binding. Registries, plugin source
+snapshots, shared workers and Library/embedding state are not implicitly shared
+between agents or organizations. A reviewed shared worker or an application
+backend must be attached through its own explicit per-agent binding; it does not
+grant the relay or Library containers Docker access.
+
+An isolated agent created before this change has no `tools/` directory, broker
+socket environment, or `COMPOSE_PROFILES` entry: recreate the agent (or backfill
+`tools/`, `EZ_TOOLS_HOME`, `EZ_PLUGIN_BROKER_SOCKET`,
+`EZ_PLUGIN_BROKER_HOST_CONFIG`, and the isolated profile) before its plugins
+will run. Until then the broker refuses to start and health reports
+`PLUGIN_BROKER_UNREADABLE` — fail-closed, never half-provisioned.
+
 For event intake, mount only the registered plugin project's socket/client
 exports into the relay, read-only. The event source stores a cursor and policy
 binding; it is not a second plugin installation. Provider credentials remain in
@@ -146,13 +222,22 @@ default. Existing queued jobs retain their captured execution choice.
 
 ## Codex context isolation
 
-The host Codex binary and existing login are reused, but each agent has its own
-`control/cli/codex` state directory. Only authentication is linked to the host
+Isolated agents run the image Codex with `EZ_CODEX_SANDBOX=external`. Auth is a
+real file at that agent's `control/cli/codex/auth.json`. Do not bind-mount the
+operator `~/.codex` or `$HOME` into an isolated relay. Host-capable agents reuse
+the host Codex binary and login, with a
+`control/cli/codex` state directory. The native CLI is resolved from the host
+PATH, not the package `binDir`, so a shared runtime or one agent's wrapper cannot
+retarget another agent's `CODEX_HOME`. Only authentication is linked to the host
 login; global configuration, sessions and memories are not imported. Global
 memory and host skill discovery are disabled for relay jobs. A conversation
 that already received unrelated global context must be replaced with a fresh
 native conversation; disabling injection does not remove prior turn content.
 This prevents automatic context sharing, not adversarial access by the host user.
+On macOS host jobs, Seatbelt also denies sibling directories of the bound
+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.
 
 ## Chat latency
 

package/docs/host-service.md

@@ -1,7 +1,8 @@
 # Host transport startup
 
-Register one service per deployment after initializing its tools. Substitute the
-exact absolute paths below. Use the existing authenticated host user and include
+Register one service per **host-capable** deployment after initializing its tools.
+Isolated agents run the native CLI in the relay and must not start this service.
+Substitute the exact absolute paths below. Use the existing authenticated host user and include
 its Node 22+, pnpm (or Corepack), Docker and CLI directories in PATH. Resolve the
 actual installed launchers first; shell aliases and interactive shell startup
 files are not available to services. No bot token goes in these service files.
@@ -21,6 +22,7 @@ Description=Ez family host CLI transport
 Type=simple
 Environment=EZ_DEPLOYMENT_DIR=/absolute/private/agents/family
 Environment=PATH=/absolute/node/bin:/absolute/package-manager/bin:/absolute/cli/bin:/usr/local/bin:/usr/bin:/bin
+EnvironmentFile=-%h/.config/ez/family-provider.env
 ExecStart=/absolute/ez-package/package/bin/ezenciel-agents-host
 Restart=on-failure
 RestartSec=5
@@ -29,6 +31,13 @@ RestartSec=5
 WantedBy=default.target
 ```
 
+When the installation declares a custom Codex provider, create that private
+environment file with mode `0600` and only the referenced key, for example
+`OPENROUTER_API_KEY=...`. Provider and model selection do not belong in the
+environment; they remain agent runtime state. The supervisor forwards only keys
+explicitly named by the agent's provider binding, and the Codex subprocess still
+receives none of the relay or plugin secrets.
+
 ```sh
 systemctl --user daemon-reload
 systemctl --user enable --now ez-family.service
@@ -81,10 +90,12 @@ main/plugin replacement. See [upgrade setup, tools and recovery](upgrades.md). E
 
 ## Shared application workspace
 
-Codex tasks inherit the agent's `control/cli/codex/auth.json` binding. Its default
-is a link to the host user's existing login. An operator may provision a private
-agent credential there during migration; new task homes link to that binding,
-preserving it rather than reverting to a different or expired host login.
+Codex tasks inherit the agent's `control/cli/codex/auth.json` binding. Host-capable
+default is a link to the host user's existing login. Isolated agents use a real
+file in that directory and the image Codex; they do not link `~/.codex`. An
+operator may provision a private agent credential there during migration; new
+task homes link to that binding, preserving it rather than reverting to a
+different or expired host login.
 
 An agent binding may set `sharedWorkspace` to an absolute canonical application
 repository. The host resolves its canonical path, adds that directory to Codex

package/docs/local-qa.md

@@ -6,7 +6,7 @@ an immutable candidate in the PA's local tools directory. The agent reads its
 manifest and uses `ez updates prepare main --file ...` and `apply` on the owner's
 request. Automatic public update policy stays unchanged.
 
-Stage from a clean, reviewed feature checkout:
+Commit, push and open a PR first — then stage only from that PR's exact commit. The staging script refuses dirty checkouts, so uncommitted work can never become a candidate. If QA finds issues, fix forward in the same PR (or a new PR) and stage a new versioned candidate; never leave a QA-only copy lingering outside the PR:
 
 ```sh
 node scripts/stage-qa.mjs --source /absolute/feature-checkout \
@@ -32,7 +32,7 @@ Add the catalog path and the following instructions to the PA's local policy fil
 > If no local entry exists, report that; do not silently substitute a public beta.
 > Follow an explicit request for a public npm release separately.
 
-For every feature, the developer handoff includes the beta label, exact private
+For every feature, the developer handoff includes the PR URL, beta label, exact private
 version, source commit, checks completed and a short user-facing QA flow with
 expected results. Include any limitations. A prepared archive or healthy service
 does not prove the feature works; read back its result through the PA.