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

package/docker/smoke.mjs

@@ -21,7 +21,7 @@ try {
     '--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_ISOLATION=isolated','-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/);
@@ -72,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']);
@@ -80,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, isolated Codex on PATH, 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

@@ -277,13 +277,30 @@ 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
@@ -325,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:
@@ -385,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

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

@@ -23,6 +23,18 @@ on the same CLI. Each agent gets its own purpose and native conversation IDs.
 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
@@ -34,8 +46,19 @@ 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
 ```
 
+`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. Isolated agents do not
@@ -52,10 +75,14 @@ Only that agent's directories are mounted into its relay. Host-capable CLI reuse
 state home with linked authentication; global memory/configuration is excluded.
 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. 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.
+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
 
@@ -86,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
@@ -126,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
@@ -171,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/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.

package/docs/plugin-guide.md

@@ -0,0 +1,202 @@
+# Build, install, and publish an Ez plugin
+
+This is the shareable guide for open-source Ez plugin authors. It covers the
+smallest path from a plugin checkout to a working private installation, and
+the separate path for publishing and listing a public product.
+
+The detailed documents linked below remain the normative references for release
+and security edge cases. This page is the front door.
+
+## The important distinction
+
+An Ez plugin can be useful before it is published. These are separate states:
+
+| State | What it means | What is required |
+| --- | --- | --- |
+| Local-only | You install your own reviewed checkout or tarball on your agent. | A valid package, an inspected content hash, and real executor verification. No npm publication or catalog entry. |
+| Catalog-listed | Ez publicly records the plugin as a product capability. | A catalog PR with the canonical repository, package identity, capability, and release links. Registration does not prove that a release exists. |
+| Released | Other users can install an immutable package from npm/GitHub. | Release checks, exact artifact/hash readback, a tagged GitHub release, registry publication, and clean-host verification. |
+
+Do not treat a catalog entry, a GitHub workflow, or a package name as proof that
+an artifact was published. Read back the actual npm and GitHub release records.
+
+## 1. Define the plugin boundary
+
+Use a plugin when the capability needs provider or domain authentication,
+deterministic validation, private state, or provider receipts. The native AI
+engine owns inference, sessions, context, reasoning, tool choice, and
+continuation. Ez core owns authorization, transport, scheduling, cancellation,
+session binding, and delivery receipts.
+
+Keep provider behavior out of the relay and do not add another agent runner,
+model router, conversation engine, prompt-history store, or competing queue.
+General plugins live in the Ez plugin repositories; a product-specific plugin
+stays with the product that owns its canonical data and policy. See the
+[plugin architecture](../../planning/docs/architecture-plugins.md).
+
+## 2. Build the smallest valid package
+
+At minimum, provide:
+
+- `package.json` with a unique scoped package name, SemVer version, repository
+  URLs, `files` allowlist, and supported Node/package-manager versions.
+- A frozen lockfile, `LICENSE`, and `THIRD_PARTY_NOTICES.md`.
+- `README.md` explaining purpose, requirements, exact install/start/onboarding
+  commands, one working read example, identity/account binding, limitations,
+  and troubleshooting.
+- `Dockerfile` and `.dockerignore` when the plugin has a managed service.
+- `ez-plugin.json` with the stable plugin id, matching version, commands, and
+  skill paths. Declare command exposure for external content, external sends,
+  record changes, and requested review.
+- `ez-deployment.json` when the plugin has managed services, volumes,
+  healthchecks, exports, or deployment dependencies.
+- A skill such as `skills/<plugin>/SKILL.md` covering required inputs, private
+  credential handling, external handoffs, resumption/recovery, and readiness
+  evidence.
+- Offline contract/negative tests, `--help`, a read-only doctor, bounded
+  machine-readable commands, stable exit codes, and readback for writes.
+
+The manager snapshots the package according to `package.json.files` plus the
+required manifests and Docker inputs. Keep one canonical checkout; do not keep
+permanent packaged copies or a second registry. See the full
+[plugin contribution requirements](plugin-contributions.md) and the
+[plugin manager contract](plugins.md#deployment-descriptors).
+
+A typical package layout is:
+
+```text
+plugin/
+├── bin/                    # executable entry points
+├── skills/<plugin>/SKILL.md
+├── src/
+├── test/
+├── Dockerfile              # if a service is managed
+├── ez-plugin.json
+├── ez-deployment.json      # if a service is managed
+├── package.json
+├── pnpm-lock.yaml
+├── README.md
+├── LICENSE
+└── THIRD_PARTY_NOTICES.md
+```
+
+## 3. Test and install it before publishing
+
+From the plugin checkout, run the package's documented checks. The standard
+baseline is:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm verify
+npm run release:check
+git diff --check
+```
+
+Run the plugin's Docker/manager smoke test when it has a managed service.
+Verify installation, start/stop, the registered command, restart persistence,
+and non-destructive uninstall using synthetic data. Then run one authorized,
+supported operation through the actual bound executor and verify its canonical
+result or provider receipt.
+
+### Install from local source or an unpublished tarball
+
+Publication is not required. Inspect the exact source first:
+
+```sh
+ez plugins inspect <id> --source /absolute/plugin
+```
+
+Use the returned revision for either a one-off install:
+
+```sh
+ez plugins install <id> --source /absolute/plugin --revision sha256:<inspected-hash>
+ez plugins start <id>
+```
+
+Or save the reviewed source in the agent's local catalog, then install it by
+the catalog entry:
+
+```sh
+ez plugins catalog-add <id> --source /absolute/plugin --revision sha256:<inspected-hash>
+ez plugins install <id>
+ez plugins start <id>
+```
+
+After startup, verify the installed command from the actual executor:
+
+```sh
+ez plugins status <id>
+ez tools list
+ez <command> doctor --json
+```
+
+Use the plugin's real supported operation as the acceptance test. Health,
+registration, or a successful `--help` command alone is not completion. A
+changed source must be inspected again; never install a stale catalog hash.
+
+## 4. Prepare a public release
+
+Use an isolated release worktree and reviewed PR. Then:
+
+1. Bump the package and plugin manifest to the same new SemVer version. Add
+   changelog and migration notes for breaking CLI or state changes.
+2. Run frozen dependency installation, package tests, release checks, Docker
+   checks, `git diff --check`, dependency/license review, and the actual manager
+   smoke test.
+3. Create the candidate with `npm pack --ignore-scripts`. Inspect its file list,
+   compute and record its SHA-256, extract it into a fresh directory, reinstall
+   from the artifact, and repeat the CLI/runtime checks there.
+4. For a first release or onboarding change, install that exact candidate on a
+   disposable clean host and verify the real executor, restart/boot behavior,
+   account binding, and first supported operation.
+5. With explicit release authorization, tag the reviewed source, publish the
+   exact tested artifact, create the matching GitHub prerelease/release, and
+   read back npm metadata, the downloaded tarball hash, release assets, and
+   source/tag identity.
+6. Install the published version on a clean host and repeat the relevant
+   verification before calling the release complete.
+
+For the complete release checklist, use [Releasing](releasing.md). For
+unattended beta publication, use [Verified beta publication](trusted-publishing.md);
+it defines the immutable GitHub asset, sanitized receipt, OIDC trust, dispatch,
+and failure-reconciliation rules. Do not put npm tokens in CI or publish merely
+to test authentication.
+
+## 5. List it as a public product
+
+Catalog registration is a discovery and product step, not installation
+authority. Open a PR updating [Available plugins](plugin-catalog.md) with:
+
+- the product name and one concrete capability description;
+- the canonical public source repository;
+- the exact npm package identity; and
+- canonical npm and GitHub release links.
+
+Only advertise a version as installable after verifying that it exists in the
+registry and in the matching GitHub release. A public catalog entry may exist
+while its first release is still pending; label that state clearly and do not
+present it as an installable version. Keep local/private plugins out of the
+public catalog; they can still be installed by reviewed source and an inspected
+hash.
+
+## The short checklist
+
+### Own agent / unpublished
+
+- [ ] Package, manifests, skill, README, license/notices, and tests exist.
+- [ ] `pnpm verify`, release checks, and the manager/Docker smoke pass.
+- [ ] Source or tarball is inspected and installed with its returned hash.
+- [ ] The actual bound executor performs a real supported operation.
+
+### Public product
+
+- [ ] The exact candidate is packed, inspected, hashed, and clean-host tested.
+- [ ] Release authorization, tag, GitHub asset, npm publication, and readback
+      all refer to the same source and bytes.
+- [ ] A clean installation of the published version is verified.
+- [ ] The public catalog is updated only with verified repository/package/release
+      records.
+
+For contribution, security, and removal details, follow the links above and the
+plugin's own `CONTRIBUTING.md`, `SECURITY.md`, and README.
+

package/docs/plugins.md

@@ -48,6 +48,31 @@ Job requests cannot override this host binding. Filesystem access remains
 `workspace-write`; other agents' directories are not added. Docker access is
 host administration under the existing trusted-host model, not OS isolation.
 
+For an isolated Codex agent, this binding is consumed by the per-agent
+`plugin-broker` service, not by a host executor. Start the deployment only after
+initialization with `COMPOSE_PROFILES=isolated`; Compose then starts the relay
+and broker together. The relay-side `ez` command has no tools-home or Docker
+socket mount. It sends a declared alias, literal arguments, bounded stdin and
+the active run ID over the private control-directory Unix socket. The broker
+revalidates the exact registry/host/workspace ownership, pinned revision and
+owner-authorized run before launching the plugin container.
+
+The broker writes bounded invocation metadata to
+`control/plugin-receipts/<run-id>/`. Plugin stdout/stderr and exit status remain
+available to the native command, including provider/API receipts. Application
+context is narrowed to the installed plugin ID and forwarded as opaque
+`EZ_PLUGIN_CONTEXT`; it is absent from ordinary native commands. No registry,
+plugin container, shared worker, Library index or embedding store is shared
+across agents unless an operator adds an explicit reviewed binding.
+
+The same broker accepts source-based `plugins inspect`, `catalog-add`, and
+`install` only when the source is an existing path under the bound workspace and
+the revision is literal and pinned. It also exposes data-preserving
+`plugins uninstall` and the local-file `updates prepare/apply/recover` lifecycle.
+Candidate archives must be staged inside the bound workspace; public registry
+discovery remains host-supervisor work because the broker has no network. Paths
+outside that workspace are rejected.
+
 ## Installation completion contract
 
 For initial Ez onboarding, plugin requests happen in the working Telegram
@@ -255,6 +280,26 @@ never retries a provider operation. Service startup/restart is explicit; command
 never implicitly start a stopped provider service. Plugin data does not enter the
 relay. The manager sends only a whitelist of Docker client environment variables.
 
+### Application plugin context
+
+An authenticated application can attach opaque domain data under
+`context.plugins.<plugin-id>` when it submits a run. During that active,
+authorized application run, the matching plugin command container receives only
+that object as JSON in `EZ_PLUGIN_CONTEXT`. No other plugin context, core control
+state, owner identity, or application context is forwarded. Ordinary native runs
+and commands launched outside an application run receive no such environment
+variable. The manager authorizes the active run and application binding at command
+admission (prepare time) and rejects revoked authority there; revocation between
+admission and container start is a documented residual window. Transport is a
+`0o600` one-shot compose override consumed via `--file` that sets the command
+service environment directly, never process arguments; the value remains
+visible in `docker inspect` while the container runs.
+
+Use this for a short-lived, domain-scoped capability or an application service
+address. It is not prompt text, a general secret channel, or an environment
+override. Plugin code must validate the object, avoid printing it, and send it
+only to its authoritative service over the reviewed transport.
+
 ## Verification
 
 `npm run verify` runs offline negative/contract tests. Explicit Docker integration:
@@ -343,8 +388,9 @@ on the next read, without hooks, LLM calls or a cached inventory file.
 
 `ez tools list` retains its alias mapping for existing clients. Native AGENTS.md
 contains only the agent-bound discovery shortcut. New workspaces do not seed
-TOOLS.md; upgrades preserve legacy notes without rewriting them. Keep owner/account
-policies in agent instructions or linked policy files, separate from plugin metadata.
+TOOLS.md, SOUL.md, USER.md, or an `inbox/`/`work/` layout; upgrades preserve
+legacy notes without rewriting them. Keep owner/account policies in agent
+instructions or linked policy files, separate from plugin metadata.
 
 Folder bindings default to read-only. For an explicitly authorized plugin that
 updates the existing source, add `--writable` to `folder-bind` while the plugin