@jc_stack/ez-agents 0.1.0-beta.12

package/docker/smoke.mjs

@@ -0,0 +1,47 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+const image = process.env.EZ_RELAY_IMAGE || 'ezenciel-agents:local';
+const dir = mkdtempSync(join(tmpdir(), 'ez-docker-qa-'));
+const holder = `ez-main-lock-qa-${process.pid}`;
+const volume = `${holder}-control`;
+const marker = 'qa-private-secret-never-in-executor';
+writeFileSync(join(dir, 'relay.env'), `TELEGRAM_BOT_TOKEN=${marker}\n`, { mode: 0o600 });
+const run = (args) => spawnSync('docker', args, { encoding: 'utf8', timeout: 60000 });
+try {
+  const probe = `
+    const fs = require('fs'), assert = require('assert/strict');
+    assert.equal(process.getuid(), 1000);
+    assert.equal(process.env.TELEGRAM_BOT_TOKEN, undefined);
+    assert.throws(() => fs.openSync('/proc/'+process.ppid+'/mem', 'r'), {code:'EACCES'});
+    assert.throws(() => fs.readFileSync('/run/secrets/relay_env'), {code:'EACCES'});
+    assert.equal(fs.existsSync('/var/run/docker.sock'), false);
+    for (const pid of ['1', String(process.ppid)]) {
+      try { assert.ok(!fs.readFileSync('/proc/'+pid+'/environ','utf8').includes('${marker}')); }
+      catch (e) { if (e.code !== 'EACCES') throw e; }
+    }
+    console.log(JSON.stringify({uid:process.getuid(), argv:process.argv.slice(1), private:true}));
+  `;
+  const literal = 'space $(touch /tmp/ez-should-not-exist); `echo no`';
+  const result = run(['run', '--rm', '--mount', `type=bind,src=${join(dir,'relay.env')},dst=/run/secrets/relay_env,readonly`, image, 'exec', 'node', '-e', probe, literal]);
+  assert.equal(result.status, 0, result.stderr);
+  assert.deepEqual(JSON.parse(result.stdout).argv, [literal]);
+  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)"]);
+  assert.equal(held.status,0,held.stderr);
+  for (let n=0;n<30;n++) {
+    const probe=run(['exec',holder,'test','-f','/state/control/ready']);
+    if(probe.status===0)break;
+    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)']);
+  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: non-root executor, private secret mount/environment, literal argv, exit code, no Docker socket, duplicate writer rejection and crash lock release.');
+} finally { run(['rm','-f',holder]); run(['volume','rm',volume]); rmSync(dir, {recursive:true, force:true}); }

package/docker/status-smoke.mjs

@@ -0,0 +1,30 @@
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import {tmpdir} from 'node:os';
+import {fileURLToPath} from 'node:url';
+import {randomUUID} from 'node:crypto';
+import assert from 'node:assert/strict';
+import {status} from '../src/updates/status.mjs';
+import {execute} from '../src/updates/runtime.mjs';
+
+const root=await fs.realpath(await fs.mkdtemp(path.join(tmpdir(),'ez-status-smoke-')));
+const home=path.join(root,'tools'),workspace=path.join(root,'mind'),controlDir=path.join(root,'control');
+const project='ez-status-'+randomUUID().slice(0,8),compose=path.join(root,'compose.json');
+const image=process.env.EZ_RELAY_IMAGE||'ezenciel-agents:local';
+const docker=args=>execute('docker',['compose','--project-name',project,'--file',compose,...args]);
+const write=(file,value)=>fs.writeFile(file,JSON.stringify(value),{mode:0o600});
+try {
+  for(const dir of [home,workspace,controlDir])await fs.mkdir(dir,{mode:0o700});
+  await write(path.join(home,'config.json'),{schemaVersion:1,workspace,deploymentDir:root,packageRoot:fileURLToPath(new URL('../',import.meta.url))});
+  await write(path.join(root,'host-executor.json'),{agents:[{workspace,controlDir,toolsHome:home}]});
+  await write(path.join(home,'registry.json'),{plugins:{sample:{manifest:{id:'sample',version:'0.1.2'},project,compose,deployment:{services:{sample:{image}}}}}});
+  await write(compose,{services:{sample:{image,entrypoint:['node','-e','setInterval(()=>{},1000)'],user:'1000:1000',network_mode:'none',cap_drop:['ALL']}}});
+  await docker(['up','-d']);
+  let p=(await status(home)).plugins[0];
+  assert.equal(p.state,'running');assert.equal(p.runningVersion,'0.1.2');assert.equal(p.services[0].imageMatches,true);
+  await docker(['stop']);p=(await status(home)).plugins[0];
+  assert.equal(p.state,'stopped');assert.equal(p.installedVersion,'0.1.2');assert.equal(p.runningVersion,null);
+  console.log('Status Docker smoke passed: running image identity and stopped plugin versions.');
+} finally {
+  try {await docker(['down']);}finally{await fs.rm(root,{recursive:true,force:true});}
+}

package/docker/upgrade-smoke.mjs

@@ -0,0 +1,58 @@
+// Real Docker replacement using WhatsApp's synthetic transport. No provider calls.
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import {tmpdir} from 'node:os';
+import {execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+import assert from 'node:assert/strict';
+import {snapshot,init,atomic} from '../src/plugins/manager.mjs';
+import {bindUpdates} from '../src/updates/binding.mjs';
+import {prepare,submit,jobPath,read} from '../src/updates/control.mjs';
+import {perform} from '../src/updates/runtime.mjs';
+import {version} from '../src/updates/artifact.mjs';
+const exec=promisify(execFile),root=await fs.realpath(await fs.mkdtemp(path.join(tmpdir(),'ez-upgrade-docker-')));
+const source=path.join(root,'source'),home=path.join(root,'tools'),mind=path.join(root,'mind'),control=path.join(root,'control');
+const input=path.resolve(process.env.EZ_WHATSAPP_SOURCE||new URL('../../ez_whatsapp',import.meta.url).pathname);
+const bin=new URL('../bin/ezenciel-agents-tools.mjs',import.meta.url).pathname;
+const call=async(...args)=>JSON.parse((await exec(process.execPath,[bin,'--home',home,...args],{maxBuffer:4*1024*1024})).stdout);
+let record;
+try {
+ for(const dir of [source,mind,control])await fs.mkdir(dir);
+ const original=await snapshot(input);
+ const [major,minor,patch]=version(original.manifest.version).numbers;
+ const upgradedVersion=`${major}.${minor}.${patch+1}-qa.1`,brokenVersion=`${major}.${minor}.${patch+2}-qa.1`;
+ for(const [name,f]of original.files){await fs.mkdir(path.dirname(path.join(source,name)),{recursive:true});await fs.writeFile(path.join(source,name),f.data,{mode:f.mode});}
+ await fs.copyFile(path.join(input,'docker/fixture.mjs'),path.join(source,'src/transport.mjs'));
+ await init(home,mind);await atomic(path.join(root,'host-executor.json'),{cli:'grok',agents:[{name:'qa',workspace:mind,controlDir:control,toolsHome:home,binDir:path.join(home,'bin')}]});
+ await bindUpdates(home,path.join(root,'host-executor.json'));
+ const initial=await snapshot(source);await call('plugins','install','whatsapp','--source',source,'--revision',initial.revision);
+ record=(await read(path.join(home,'registry.json'))).plugins.whatsapp;
+ await call('plugins','start','whatsapp');
+ const identity=await call('whatsapp','doctor');const before=await call('whatsapp','inbox');
+ const message=path.join(mind,'test-message.txt');await fs.writeFile(message,'Synthetic upgrade fixture');
+ const sent=await call('whatsapp','send','--to','+15551230000','--text-file',message,'--idempotency-key','upgrade:fixture');
+ const build=async(version,broken=false)=>{
+  const pkg=await read(path.join(source,'package.json'));pkg.version=version;await atomic(path.join(source,'package.json'),pkg);
+  const manifest=await read(path.join(source,'ez-plugin.json'));manifest.version=version;await atomic(path.join(source,'ez-plugin.json'),manifest);
+  if(broken)await fs.writeFile(path.join(source,'src/transport.mjs'),'throw Error("Synthetic broken candidate")');
+  const [pack]=JSON.parse((await exec('npm',['pack','--ignore-scripts','--json','--pack-destination',root],{cwd:source})).stdout);
+  const job=await prepare(home,'whatsapp',{file:path.join(root,pack.filename)});
+  await atomic(path.join(home,'updates/supervisor.json'),{at:Date.now()});await submit(home,job.id,false);
+  return perform(home,await read(path.join(jobPath(home,job.id),'job.json')),{startHost:()=>{throw Error('Plugin touched host');},stopHost:()=>{throw Error('Plugin touched host');}});
+ };
+ assert.equal((await build(upgradedVersion)).status,'completed');
+ assert.equal((await call('whatsapp','doctor')).data.connected,identity.data.connected);
+ assert.equal((await call('whatsapp','inbox')).data.nextCursor,before.data.nextCursor);
+ assert.equal((await call('whatsapp','operation','--idempotency-key','upgrade:fixture')).data.providerMessageId,sent.data.providerMessageId);
+ assert.equal((await build(brokenVersion,true)).status,'rolled-back');
+ assert.equal((await call('whatsapp','doctor')).data.connected,true);
+ assert.equal((await call('whatsapp','operation','--idempotency-key','upgrade:fixture')).data.providerMessageId,sent.data.providerMessageId);
+ const current=(await read(path.join(home,'registry.json'))).plugins.whatsapp;
+ assert.equal(current.project,record.project);assert.equal(current.manifest.version,upgradedVersion);
+ console.log('PASS: Docker plugin upgrade, private volume backup, retained identity/cursor/operation receipt, failed-health rollback. Synthetic provider only.');
+} finally {
+ if(record)await exec('docker',['compose','-p',record.project,'-f',record.compose,'down','--volumes']).catch(()=>{});
+ // Delete only fixture-owned images and state.
+ if(record){const images=(await exec('docker',['image','ls','--filter',`reference=${record.project}-*`,'-q'])).stdout.trim().split('\n').filter(Boolean);if(images.length)await exec('docker',['image','rm',...images]).catch(()=>{});}
+ await fs.rm(root,{recursive:true,force:true});
+}

package/docs/architecture/ai-selection.md

@@ -0,0 +1,37 @@
+# AI selection
+
+`menu.ts` owns Telegram controls; `ai.ts` projects installed-client metadata.
+`ControlStore` stores saved presets, the next-conversation default and current choice.
+No provider SDK, model fallback, history migration, or second execution loop.
+
+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.
+
+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
+Telegram reply. `codex-gui` is a separate desktop adapter: it submits a dedicated
+app-server thread/turn and waits for that turn to finish. It does not run
+`codex exec`. A missing or mismatched native session fails closed, not `--last`.
+Legacy unbound sessions require the owner's explicit `/new`.
+
+References used for the adapter contract:
+
+- [Codex non-interactive execution](https://learn.chatgpt.com/docs/non-interactive-mode)
+- [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;
+the relay does not install models, manage subscriptions or guess aliases.
+
+Setup initialization and relay startup seed one default choice per installed client.
+Settings → Refresh available AIs repeats discovery. Active/default presets and
+queued snapshots are preserved; discovery only refreshes unused detected entries.
+Codex uses its native `config/read` interface; Grok reads its documented user
+model/effort settings (or `models` for the default model). Claude reads user and
+workspace JSON settings; OpenCode reports resolved config. Unknown defaults and
+opaque wrappers remain explicitly “client default”. No credentials are stored,
+no inference runs, no new dependency, and no cross-CLI session transfer.

package/docs/architecture/authority-boundaries.md

@@ -0,0 +1,14 @@
+# Authority boundaries
+
+The relay pairs one verified Telegram owner before execution; foreign senders
+and groups do not acquire execution rights. Replies use the run-bound source
+chat. Plugin events are untrusted content, queued in the same single-writer lane;
+subscription permission is not permission to reply or execute incoming demands.
+
+The host CLI runs as the trusted installing user. Its Markdown role, confirmation
+tools, environment filtering and private state layout do not create adversarial
+OS isolation. The plugin manager has Docker administration access. Container
+profile separation does not protect against a hostile host administrator.
+
+See [SECURITY.md](../../SECURITY.md) for the supported security scope and
+[Docker runtime](../docker-runtime.md) for the actual process/storage boundary.

package/docs/architecture/event-sources.md

@@ -0,0 +1,34 @@
+# Local event sources
+
+A plugin owns capture, authentication and eligibility. The relay owns execution.
+Register through `ezenciel-agents-source --name NAME --socket /absolute/service.sock`;
+inspect with `--list`, remove with `--name NAME --remove`. Registration pins the
+paired owner, assigns a new binding ID and starts at the provider's current head.
+Same-user plugins are trusted installed code; private Unix sockets are the boundary,
+not a sandbox against other programs running as that user.
+
+POST JSON `{ "command": "...", "args": {} }` to `/` over the Unix socket.
+Return HTTP 200 with `{ "ok": true, "data": ... }`:
+
+- `events-head`: `{cursor: <nonnegative integer>}`.
+- `events`, args `{after: <cursor>}`: `{cursor, events}`. Advance over excluded
+  events too. IDs must remain stable; return at most ten events in capture order.
+- `events-check`, args `{ids: [<string IDs>]}`: `{events}` containing only those
+  IDs still eligible now, with current canonical content.
+
+Each event is `{id, conversationId, receivedAt, text}`. IDs are at most 100 ASCII
+letters/digits/underscore/hyphen; conversation IDs at most 200 characters;
+receivedAt is epoch milliseconds; text at most 16000 characters. Responses are
+bounded to 256 KiB and three seconds. Plugin-specific policy stays in the plugin.
+
+The host polls each second and waits for two seconds of quiet, ten seconds of
+age, or ten events. It groups by conversation and persists the batch before
+creating deterministic run IDs. Cursor acknowledgement follows durable run
+creation. Crash replay reuses the batch and run IDs. This deduplicates queue
+creation; it does not promise exactly-once external actions after executor failure.
+
+Before starting queued work, recheck binding, owner and provider eligibility.
+Unavailable sources keep work queued; removed subscriptions cancel empty runs.
+No check can retract work already started. External observations use fresh executor
+sessions and explicitly carry no owner-instruction or send authority. They share
+the existing one-writer queue and secret whitelist. No provider SDK is imported.

package/docs/architecture/telegram-intake.md

@@ -0,0 +1,29 @@
+# Telegram intake and recovery
+
+One owner, one bot, one relay writer per control directory. No database, extra agent, or executor loop.
+
+1. Gate the sender and private chat before accepting work.
+2. Atomically save the raw update and deduplicate its Telegram update ID in `EZ_CONTROL_DIR/inbox.json`.
+3. Collect a short burst before downloading/transcribing. Seal batch membership on disk, then normalize in receive order. Captions, album IDs and quoted context travel with the media.
+4. Create one durable run using the batch's stable ID. A restart between run creation and intake completion finds that same run; it does not create a second job.
+5. The selected CLI executes. Replies still come through the messaging CLI and the receipt-backed outbox.
+
+The polling handler does not wait for media processing or execution. Native controls bypass the work queue, but not the owner gate. Buffered work is checked against the current owner again before processing and execution.
+
+## Recovery boundaries
+
+- Process restart recovers accepted, unstarted messages. Stopping the relay does not discard its intake buffer.
+- Attachment downloads and transcription retry transient network errors, timeouts, HTTP 408/429 and selected 5xx responses up to three total attempts. Backoff starts at one second, then two; Retry-After is honored up to thirty seconds, with longer cooldowns left for explicit recovery. Each request has a sixty-second timeout, including body reads. Authentication, certificate and invalid-input errors are not automatically retried. Transcription retries can incur additional provider charges; there is no provider/model fallback.
+- Exhausted or permanent normalization failures quarantine the whole batch; later batches can proceed. `/status` exposes the failure and owner-only `/retry` requeues the latest failed incoming batch with its original stable run ID and context. No incomplete-context execution, replay of executed jobs, or automatic retry of external actions/chat sends. Errors identify the request stage and network code without logging credential-bearing URLs or provider payloads.
+- `/cancel` cancels buffered/normalizing intake and queued runs, not active execution. A download already in progress may finish staging a file, but its cancelled batch cannot launch.
+- `/stop` requests termination of active execution only. It neither clears the queue nor promises a successful same-session resume in the CLI.
+- Existing running records are not blindly replayed. Unknown execution/delivery outcomes require local inspection; this is not an exactly-once guarantee for external side effects.
+- `/new` preserves files and queued work. It is not a cancellation command.
+- Approval decisions are replay-idempotent only for the same authenticated Telegram update. Another click cannot replay consent. Buttons record consent; they do not constrain a full-access executor's tools.
+- A broken intake journal fails closed, preserving the file. Polling must not acknowledge work it could not persist. Repair it locally before restarting.
+
+## Deliberate limits
+
+The quiet window is two seconds, bounded by thirty seconds/ten messages. Received album items remain together, including at the cap; arbitrarily late attachments cannot be guaranteed to join an earlier turn.
+
+The local JSON journal retains update-ID deduplication tombstones and failed/cancelled batches. It is not a high-volume multi-tenant queue; retention/compaction and automatic service startup belong to later installation work. Use separate control directories for separate bots. Machine-level isolation and disk power-loss durability are not claimed.

package/docs/development-and-testing.md

@@ -0,0 +1,18 @@
+# Development and testing
+
+Use Node 22+ and pnpm 10.30.3: `pnpm install --frozen-lockfile`, then
+`pnpm verify`. Tests use temporary synthetic state; TypeScript checks source and
+tests. Use `npm run release:check` for package contents. See CONTRIBUTING.md for
+PR expectations and [release checks](releasing.md) for Docker and clean-host QA.
+
+For the cross-repository fixture, place the reviewed WhatsApp source beside this
+repository as `ez_whatsapp` and run `node docker/plugin-smoke.mjs`. For another
+location, set `EZ_WHATSAPP_SOURCE=/absolute/reviewed/whatsapp/package`. It installs
+through the real manager with synthetic provider data, checks dispatch,
+operation replay, restart and retained data on uninstall, then removes its own
+fixture resources. It never uses an existing linked account.
+
+`pnpm smoke` contacts Telegram and invokes the selected AI. It proves outbound
+reply delivery, not incoming onboarding. Stop the exact poller first, use a
+dedicated authorized account, and follow docs/setup.md for the full incoming
+path. Never revoke a working owner or reuse production profiles as fixtures.

package/docs/docker-runtime.md

@@ -0,0 +1,118 @@
+# 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.
+
+## Agent binding
+
+Use [agent-led setup](setup.md). `ezenciel-agents-create` accepts a name, purpose,
+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.
+
+`docker.env` contains explicit absolute paths, never token values:
+
+```dotenv
+COMPOSE_PROJECT_NAME=ez-agent-family
+EZ_EXECUTOR_CLI=grok
+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
+```
+
+The installing agent runs `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 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
+listener, Docker socket in containers, new provider API or per-CLI service shim
+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
+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.
+
+## Operate and verify
+
+```sh
+export EZ_DEPLOYMENT_DIR=/absolute/private/agents/family
+bin/ezenciel-agents-docker up -d --wait
+bin/ezenciel-agents-docker run --rm relay owner status
+bin/ezenciel-agents-docker run --rm relay owner approve <verified-numeric-id>
+bin/ezenciel-agents-docker stop relay
+bin/ezenciel-agents-docker run --rm relay smoke
+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.
+Health requires recent polling and host-transport heartbeats, not just a process.
+Model catalog metadata is exported from the selected host CLI without credentials.
+The AI menu stays within that CLI. No automatic executor fallback is performed.
+
+## Secrets and plugins
+
+The relay secret file is private and outside the mind. A short root bootstrap
+opens it, protects `/run/secrets`, and drops capabilities. The relay runs with
+distinct real/effective UIDs to deny process-memory reads; local container tool
+processes normalize to UID 1000. Relay secrets never enter configured container
+environment or host CLI environment. Container isolation tests cover these
+boundaries; the trusted host account can still administer installation files.
+
+Each plugin owns its Docker image, dependencies, private profile, onboarding
+and receipts. The agent-bound `ez` registry is the only plugin authority:
+`ez plugins list`, `ez plugins install`, `ez plugins start|stop|status`, and
+`ez <alias> ...`. Its reviewed deployment descriptor supplies literal command
+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.
+
+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
+the plugin profile. Keep this event mount aligned with the registry-owned project.
+
+## Migration and rollback
+
+Stop and disable the exact old poller/profile service. Back up mind, control,
+plugin profile and relevant native sessions first. Copy canonical relay state to
+its per-agent bind directories and plugin state into its own volume. Preserve
+pending/uncertain operations without replay. Never run two copies of a bot token
+or linked profile. Keep the same selected host CLI and its existing login.
+
+To roll back, stop Docker and the host transport first, deliberately reconcile
+newer state, then restore the recorded old service. Never use `down -v` on a live
+profile. Docker smoke uses fixtures; it is not proof of provider delivery, phone
+UI, voice or buttons. Run the explicit real smoke separately while the poller is
+stopped. A previously containerized native session needs deliberate history/path
+migration before `--resume`; do not silently reset it.
+
+The installing CLI is an initial default, not a permanent restriction. An explicit
+owner selection may use any supported CLI/model installed on the host. Native
+`ezenciel-agents-ai list` and `select` expose this choice. A cross-CLI switch
+starts a fresh native conversation and preserves the mind and installation
+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
+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.

package/docs/host-service.md

@@ -0,0 +1,80 @@
+# 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
+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.
+Docker Compose owns the relay/plugins; this service only runs the host transport.
+`ezenciel-agents-setup service` starts only the Docker relay; it does not register
+or start this host service.
+
+## Linux
+
+Save `~/.config/systemd/user/ez-family.service` with a unique agent name:
+
+```ini
+[Unit]
+Description=Ez family host CLI transport
+
+[Service]
+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
+ExecStart=/absolute/ez-package/package/bin/ezenciel-agents-host
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+```
+
+```sh
+systemctl --user daemon-reload
+systemctl --user enable --now ez-family.service
+systemctl --user status ez-family.service
+journalctl --user -u ez-family.service -n 50 --no-pager
+```
+
+Startup before login additionally needs administrator-enabled user lingering
+(`loginctl enable-linger <host-user>`); verify `loginctl show-user <host-user> -p
+Linger`. Docker must start at boot too. Verify the real CLI tool call under this
+service environment. Stop/disable only this unit when removing this agent.
+
+## macOS
+
+Save `~/Library/LaunchAgents/local.ez.family.plist` with a unique agent label:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<plist version="1.0"><dict>
+<key>Label</key><string>local.ez.family</string>
+<key>ProgramArguments</key><array><string>/absolute/ez-package/package/bin/ezenciel-agents-host</string></array>
+<key>EnvironmentVariables</key><dict>
+<key>EZ_DEPLOYMENT_DIR</key><string>/absolute/private/agents/family</string>
+<key>PATH</key><string>/absolute/node/bin:/absolute/package-manager/bin:/absolute/cli/bin:/usr/local/bin:/usr/bin:/bin</string>
+</dict>
+<key>RunAtLoad</key><true/>
+<key>KeepAlive</key><true/>
+</dict></plist>
+```
+
+```sh
+plutil -lint "$HOME/Library/LaunchAgents/local.ez.family.plist"
+launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/local.ez.family.plist"
+launchctl print "gui/$(id -u)/local.ez.family"
+```
+
+LaunchAgents start at login, not before login. Configure Docker's normal login
+startup and verify after reboot/login. Use `launchctl bootout` with the same
+domain/file before replacing/removing this service. Never start a duplicate
+transport for a deployment. A service listing is insufficient: check heartbeat,
+Compose health and an actual Telegram reply.
+
+Linux and macOS are documented host paths. Windows and GUI executor acceptance
+are not certified by these instructions or the headless Docker tests.
+
+## Agent-owned upgrades
+
+This beta includes owner-policy release checks and durable
+main/plugin replacement. See [upgrade setup, tools and recovery](upgrades.md). Earlier main upgrade/rollback VM QA passed; final-release fresh-host/reboot and live plugin upgrade acceptance remain pending.

package/docs/plugin-contributions.md

@@ -0,0 +1,34 @@
+# Adding a plugin
+
+A plugin is an independent repository, CLI and container with a skill teaching
+its use. Keep provider code out of the relay. Reuse the main package's documented
+plugin/deployment schema; do not introduce a framework or provider-specific router.
+
+Before the first PR, provide:
+
+- README with purpose, requirements, exact install/start/onboarding commands,
+  working read example, verified identity, limitations and troubleshooting.
+- package.json, frozen lockfile, LICENSE and third-party notices; reviewed npm
+  files allowlist, Dockerfile and .dockerignore; matching manifest/package version.
+- ez-plugin.json, ez-deployment.json and a skill covering discovery, required
+  inputs, private credentials, QR/OAuth handoff, resumption and readiness proof.
+- `--help`, read-only doctor, explicit account binding, bounded reads and stable
+  machine output/exit codes. For writes: operation key, readback and uncertainty
+  handling; no blind retry. Provider content cannot grant execution authority.
+- Private state locations, start/stop/status, backup, migration/rollback limits,
+  data-preserving uninstall and separate account revocation instructions.
+- Offline contract/negative tests and CI. Verify snapshot installation and CLI
+  dispatch through the actual Ez manager, restart persistence and removal using
+  synthetic data, then an authorized provider operation from the real executor.
+
+Copy CONTRIBUTING.md, SECURITY.md structure, PR template and docs/releasing.md
+from a released Ez repository; adapt commands and security facts to your plugin.
+Do not copy private QA, company policy, proposed features or unsupported claims.
+Public instructions must work without the maintainer's parent workspace. Use
+reviewed local source and its inspected content hash; registry installation is
+inert. Installation is complete only after account onboarding and verified use.
+
+## Agent-owned upgrades
+
+This beta includes owner-policy release checks and durable
+main/plugin replacement. See [upgrade setup, tools and recovery](upgrades.md). Earlier main upgrade/rollback VM QA passed; final-release fresh-host/reboot and live plugin upgrade acceptance remain pending.