@jc_stack/ez-agents 0.1.0-beta.42 → 0.1.0-beta.44

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.1.0-beta.44
+
+- Let isolated native agents read declared installed plugin skills through the
+  existing authorized broker. Discovery supplies literal skill-read commands,
+  so tools such as EzStudy work without copying package instructions into the
+  agent workspace or rebuilding native context.
+- Keep skill reads bound to the installed revision and active authorized run;
+  reject undeclared paths, traversal, symlinks and oversized files.
+
+## 0.1.0-beta.43
+
+- Keep model and reasoning settings with each named conversation and preserve
+  native history across supported model changes. Save the selected AI as the
+  default for new conversations.
+- Keep private application-channel AI choices separate from owner preset slots.
+- Honor current-owner-authorized messaging tasks without a second approval;
+  retain bounded task authority across restart without replaying uncertain sends.
+- Expose installed native controls through Ez help and preserve operator CLI pins,
+  isolated credentials, plugin volumes and private broker ownership on Linux.
+- Reuse the exact healthy pinned relay during failed-update recovery.
+- Legacy deployments need the reviewed installer migration in
+  docs/application-channel.md for the trusted broker capability change; ordinary
+  updater compatibility guards remain in force.
+
 ## 0.1.0-beta.42
 
 - Keep recurring schedule edits at their next pending or future occurrence, so

package/Dockerfile

@@ -1,6 +1,8 @@
+FROM docker/compose-bin:v5.5.1@sha256:14162382692aae43977f79effa64a499d61de19d4645461881daaf88773f7e74 AS compose-bin
 FROM node:22.22.0-bookworm-slim@sha256:dd9d21971ec4395903fa6143c2b9267d048ae01ca6d3ea96f16cb30df6187d94 AS dependencies
 WORKDIR /app
-RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates git util-linux ffmpeg docker.io docker-compose && rm -rf /var/lib/apt/lists/*
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates git util-linux ffmpeg docker.io && rm -rf /var/lib/apt/lists/*
+COPY --from=compose-bin /docker-compose /usr/local/bin/docker-compose
 RUN corepack enable && corepack prepare pnpm@10.30.3 --activate
 COPY package.json ./
 COPY docker/pnpm-lock.yaml ./pnpm-lock.yaml

package/bin/ez

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { createConnection } from 'node:net';
 import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { installedNativeHelp } from '../src/plugins/native-tasks.mjs';
 
 const MAX_STDIN_BYTES = 1024 * 1024;
 const RUN_ID = /^[A-Za-z0-9_-]{1,160}$/;
@@ -86,7 +88,7 @@ const manager = async args => {
 const main = async () => {
   const args = process.argv.slice(2);
   if (!args.length || args[0] === '--help' || args[0] === '-h') {
-    process.stdout.write('Use `ez tools list` to discover installed plugins, then `ez <alias> ...` for a declared command.\n');
+    process.stdout.write(JSON.stringify({commands:['tools list [--details]','tools skill <plugin> <declared-path>','<registered CLI> ...'],native:await installedNativeHelp(fileURLToPath(new URL('.',import.meta.url)))})+'\n');
     return;
   }
   const stdin = ['plugins', 'tools', 'updates', 'status'].includes(args[0]) ? '' : await readStdin();

package/compose.yaml

@@ -58,6 +58,8 @@ services:
     stop_grace_period: 10s
     user: "0:0"
     cap_drop: [ALL]
+    # The trusted broker maintains private files owned by the installer UID.
+    cap_add: [DAC_OVERRIDE, CHOWN]
     security_opt: [no-new-privileges:true]
     network_mode: none
     environment:

package/docker/entrypoint.sh

@@ -21,7 +21,10 @@ if [ "$(id -u)" = 0 ]; then
   chmod 700 /run/secrets
   chown "$runtime_uid:$runtime_gid" /state/control /state/home /workspace
   if [ -f /run/secrets/relay_env ]; then exec 3</run/secrets/relay_env; else exec 3</dev/null; fi
-  exec setpriv --ruid="$relay_uid" --euid="$runtime_uid" --regid="$runtime_gid" --clear-groups --bounding-set=-all --no-new-privs /app/docker/entrypoint.sh "$@"
+  # Some Linux security modules normalize differing real/effective UIDs during
+  # an exec under no_new_privs. Preserve the relay's split identity here; the
+  # executor applies no_new_privs after normalizing its own IDs.
+  exec setpriv --ruid="$relay_uid" --euid="$runtime_uid" --regid="$runtime_gid" --clear-groups --bounding-set=-all /app/docker/entrypoint.sh "$@"
 fi
 # Reserve the private environment descriptor before Node can use it for libuv.
 # Root startup already opened it; preserve that inherited secret descriptor.

package/docker/smoke.mjs

@@ -8,6 +8,10 @@ const dir = mkdtempSync(join(tmpdir(), 'ez-docker-qa-'));
 const holder = `ez-main-lock-qa-${process.pid}`;
 const volume = `${holder}-control`;
 const application = `${holder}-application`;
+const privateVolume = `${holder}-private`;
+const boundProject = `${holder}-bound`;
+const boundVolume = `${boundProject}_data`;
+const broker = `${holder}-broker`;
 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 });
@@ -48,6 +52,7 @@ try {
     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);
+    assert.match(fs.readFileSync('/proc/self/status','utf8'), /^NoNewPrivs:\\s+1$/m);
     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; }
@@ -70,6 +75,92 @@ try {
     '--mount',`type=bind,src=${join(dir,'relay.env')},dst=/run/secrets/relay_env,readonly`,image,'exec','node','-e',customProbe]);
   assert.equal(custom.status,0,custom.stderr);
   assert.equal(JSON.parse(custom.stdout).uid,20001);
+  // Real Linux ownership, including pre-existing mode-600 control/registry
+  // files. Host bind mounts on desktop Docker can mask these failures.
+  const seed = run(['run','--rm','-v',`${privateVolume}:/qa`,'--entrypoint','node',image,'-e',`
+    const fs=require('fs');
+    for(const name of ['home','control','mind']) {
+      fs.mkdirSync('/qa/'+name,{recursive:true,mode:0o700});
+      fs.chownSync('/qa/'+name,20001,20002);
+    }
+    const files={
+      '/qa/control/control-state.json':{version:1,owner:null,pending:[]},
+      '/qa/home/config.json':{schemaVersion:1,workspace:'/qa/mind',hostConfig:'/qa/host-executor.json'},
+      '/qa/home/registry.json':{schemaVersion:1,owner:'/qa/home',plugins:{},commands:{}},
+      '/qa/host-executor.json':{isolation:'isolated',agents:[{name:'qa',toolsHome:'/qa/home',workspace:'/qa/mind',controlDir:'/qa/control'}]},
+    };
+    for(const [file,value] of Object.entries(files)) {
+      fs.writeFileSync(file,JSON.stringify(value),{mode:0o600});fs.chownSync(file,20001,20002);
+    }
+  `]);
+  assert.equal(seed.status,0,seed.stderr);
+  // Compose must reuse an existing operator-owned bind volume without
+  // recreating it or rejecting its driver options (legacy Compose v1 did).
+  const mountpoint = run(['volume','inspect','--format','{{.Mountpoint}}',privateVolume]).stdout.trim();
+  assert.ok(mountpoint.startsWith('/'));
+  const bind = run(['volume','create','--driver','local','--opt','type=none','--opt','o=bind','--opt',`device=${mountpoint}`,boundVolume]);
+  assert.equal(bind.status,0,bind.stderr);
+  const boundConfig = {services:{probe:{image,network_mode:'none',entrypoint:['node','-e',
+    `const fs=require('fs'),assert=require('assert/strict');assert.equal(JSON.parse(fs.readFileSync('/state/host-executor.json')).isolation,'isolated');console.log('bound-volume-preserved');`],
+    volumes:['data:/state:ro']}},volumes:{data:{}}};
+  const reused = spawnSync('docker',['run','--rm','-i','--network','none','-v','/var/run/docker.sock:/var/run/docker.sock',
+    '--entrypoint','docker-compose',image,'--project-name',boundProject,'--file','-','run','--rm','--no-deps','probe'],
+    {encoding:'utf8',timeout:60000,input:JSON.stringify(boundConfig)});
+  assert.equal(reused.status,0,reused.stderr);
+  assert.match(reused.stdout,/bound-volume-preserved/);
+  assert.equal(run(['volume','inspect','--format','{{index .Options "device"}}',boundVolume]).stdout.trim(),mountpoint);
+  const privateState = run(['run','--rm','-v',`${privateVolume}:/qa`,
+    '-e','EZ_CONTROL_DIR=/qa/control','-e','EZ_RUNTIME_UID=20001','-e','EZ_RUNTIME_GID=20002','-e','EZ_RELAY_UID=20003',
+    image,'owner','status']);
+  assert.equal(privateState.status,0,privateState.stderr);
+  assert.equal(JSON.parse(privateState.stdout).owner,null);
+  const brokerStarted = run(['run','-d','--name',broker,'--user','0:0','--cap-drop','ALL',
+    '--cap-add','DAC_OVERRIDE','--cap-add','CHOWN','--security-opt','no-new-privileges','--network','none',
+    '-v',`${privateVolume}:/qa`,'--entrypoint','node',image,'--import','/app/node_modules/tsx/dist/loader.mjs',
+    '/app/src/plugin-broker.mjs','--home','/qa/home','--workspace','/qa/mind','--control-dir','/qa/control',
+    '--socket','/qa/control/plugin-broker.sock','--host-config','/qa/host-executor.json']);
+  assert.equal(brokerStarted.status,0,brokerStarted.stderr);
+  let brokerReady=false;
+  for(let n=0;n<30;n++) {
+    const check=run(['exec','--user','20001:20002',broker,'node','-e',`
+      const fs=require('fs'),assert=require('assert/strict');
+      assert.ok(fs.statSync('/qa/control/plugin-broker.sock').isSocket());
+      const file='/qa/control/plugin-broker-plugins.json';
+      assert.equal(fs.statSync(file).uid,20001);assert.deepEqual(JSON.parse(fs.readFileSync(file)).plugins,[]);
+    `]);
+    if(check.status===0){brokerReady=true;break;}
+    await new Promise(resolve=>setTimeout(resolve,100));
+  }
+  assert.ok(brokerReady,run(['logs',broker]).stderr);
+  const prepare = run(['exec',broker,'node','--input-type=module','-e',`
+    import fs from 'node:fs/promises';
+    import {snapshot,install,prepareCommand} from '/app/src/plugins/manager.mjs';
+    const home='/qa/home',source='/qa/source';
+    await fs.mkdir(source);
+    const manifest={schemaVersion:1,id:'sample',version:'0.1.0',description:'Synthetic',commands:{sample:{executable:'client.mjs',args:[]}},skills:['SKILL.md']};
+    const deployment={schemaVersion:1,services:{sample:{buildTarget:'runtime',volumes:{},healthcheck:['node','--version']}},commands:{sample:{service:'sample',argv:['node','/app/client.mjs']}}};
+    for(const [name,value] of Object.entries({'package.json':JSON.stringify({files:['client.mjs','SKILL.md']}),'ez-plugin.json':JSON.stringify(manifest),'ez-deployment.json':JSON.stringify(deployment),'Dockerfile':'FROM scratch AS runtime','.dockerignore':'','client.mjs':'','SKILL.md':'Synthetic'}))await fs.writeFile(source+'/'+name,value);
+    // Only the Docker build effect is stubbed; real installation and private
+    // filesystem operations execute with the production broker capabilities.
+    await fs.writeFile('/qa/docker','#!/bin/sh\\nexit 0\\n',{mode:0o755});
+    process.env.PATH='/qa:'+process.env.PATH;
+    delete process.env.EZ_DOCKER_COMPOSE;
+    const pkg=await snapshot(source),config=JSON.parse(await fs.readFile(home+'/config.json'));
+    await install(home,config,'sample',source,pkg.revision);
+    const command=await prepareCommand(home,'sample',[],{invocation:true,environment:{}});
+    await command.release();
+  `]);
+  assert.equal(prepare.status,0,prepare.stderr);
+  const steward = run(['exec','--user','20001:20002',broker,'node','-e',`
+    const fs=require('fs'),assert=require('assert/strict');
+    for(const dir of ['packages','packages/sample','command-invocations']) {
+      const stat=fs.statSync('/qa/home/'+dir);
+      assert.equal(stat.uid,20001);assert.equal(stat.gid,20002);assert.equal(stat.mode&511,448);
+      fs.readdirSync('/qa/home/'+dir);
+    }
+    fs.readFileSync('/qa/home/packages/sample/compose.json');
+  `]);
+  assert.equal(steward.status,0,steward.stderr);
   const failed = run(['run','--rm',image,'exec','node','-e','process.exit(23)']);
   assert.equal(failed.status, 23, failed.stderr);
   // The live delivery socket is the single-relay guard (it replaced the kernel
@@ -108,4 +199,4 @@ try {
   }
   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}); }
+} finally { run(['rm','-f',holder,application,broker]); run(['volume','rm',boundVolume,volume,privateVolume]); rmSync(dir, {recursive:true, force:true}); }

package/docs/application-channel.md

@@ -296,8 +296,9 @@ 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.
+Model and reasoning changes on the same client and provider preserve the native
+conversation; client or provider changes start a separate conversation.
+Already-queued work keeps its captured AI choice.
 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.
@@ -444,3 +445,6 @@ partial request. Separate owner runtimes must retain separate workspace mounts.
 
 This is inbound file support. Application replies currently deliver text only;
 outgoing file downloads remain unsupported by this HTTP channel.
+
+Private scope model selections are stored on that scope’s native-session binding.
+They do not add entries to the owner’s saved AI menu or consume its preset limit.

package/docs/architecture/ai-selection.md

@@ -7,10 +7,13 @@ 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. 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.
+Each named conversation saves its model and reasoning level. Switching back through
+`/chats` restores that choice and the exact native session, including after restart.
+`/ai` shows the current choice and saves changes immediately. Changing model or
+reasoning level on the same client and provider preserves the conversation's name
+and native history; subsequent turns pass the new settings to the native engine.
+Changing client or provider starts a separate native conversation. Old bindings
+remain available so accepted work can finish and owners can reopen their chats.
 
 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

@@ -9,13 +9,17 @@ marking it internal does not confer owner authority.
 ## Messaging v1
 
 The owner asks the agent to contact one person for a bounded purpose. The owner
-agent prepares a proposal with `ezenciel-agents-task propose`: registered source,
+agent uses `ezenciel-agents-task start`: registered source,
 exact canonical contact, purpose, explicitly shareable context, and expiry (up to
-72 hours). Telegram displays that exact proposal for approval. The core binds it
+72 hours). A current authenticated owner turn can start work already authorized
+by that request, without another approval click. The native engine interprets
+the request; core does not infer authority from keywords. `propose` remains for
+scope needing a new owner decision. Scheduled and external runs cannot use either.
+The core binds the grant
 to the verified owner, current source registration, and connected account. The
 owner does not edit JSON. The agent uses `list` and `revoke` when asked.
 
-After approval the relay starts a restricted task, including the initial outgoing
+After activation the relay starts a restricted task, including the initial outgoing
 message. Incoming-only tasks instead wait for new correspondence and never create
 an opening run. Their task records use version 2 so older task readers fail closed. Matching new correspondence resumes that task in a fresh native session.
 Other contacts remain blocked unless an owner-approved any-conversation grant is
@@ -25,6 +29,13 @@ settings changes, or access to owner memory. A contact can have one active or
 pending task at a time. Completed, revoked, expired, replaced-source, and changed-
 account grants cannot dispatch further messages.
 
+Activated grants persist in the protected task record with a digest of all
+immutable scope fields. Transient approval requests are not the continuing
+authority store. Owner replacement, scope mutation, expiry and revocation still
+invalidate authorization. The initial dispatch marker also persists: relay
+restart does not replay an uncertain opener. Pending or legacy records without
+a grant need their original live approval and are never auto-authorized.
+
 The worker receives only the approved dossier, its notes, its operation receipts,
 and rechecked correspondence for its contact. All dossier contents may be shared
 with that contact. The agent judges how to pursue the purpose; code does not prove
@@ -55,7 +66,7 @@ exact registered `ez` command plus fixed arguments ending in literal
 `-- {input}`. The restricted broker replaces only `{input}` with the
 correspondent's string; the model cannot select a command, prepend flags, choose
 a recipient, access a shell or change the fixed arguments. The full command
-vector and disclosure scope appear in the immutable owner approval. Core rechecks
+vector and disclosure scope are bound by the immutable owner grant. Core rechecks
 the grant immediately before and after invocation and before every reply. The
 installed alias must declare `channelQuery: true` and explicitly declare that it
 accepts external input without external sends, record changes, or interactive

package/docs/docker-runtime.md

@@ -22,6 +22,8 @@ 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.
+Only isolated deployments configure the plugin-broker socket and Compose profile;
+host-capable deployments use their bound host transport and registry.
 
 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
@@ -84,6 +86,22 @@ 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.
 
+The trusted broker has only `DAC_OVERRIDE` and `CHOWN` in addition to its
+Docker socket, so it can read private installer-owned registry files and preserve
+their ownership. The relay drops all capabilities before loading its secrets.
+It retains distinct real/effective UIDs; `no_new_privs` is applied to the native
+executor after normalizing those IDs. Applying it earlier can cause Linux
+security modules to discard the relay's effective UID during exec.
+Private native credentials and skills are checked using that effective UID;
+`access(2)` checks the distinct real UID and can incorrectly hide a valid binding.
+Runtime updates preserve explicit relay build arguments from the operator's
+Compose deployment, including native CLI version pins.
+New private broker directories and update archives inherit the installer's
+ownership. Existing installations need the reviewed deployment migration in
+[application-channel.md](application-channel.md#reviewed-deployment-migration)
+for this Compose capability change; ordinary updates retain their compatibility
+guard. Preserve the existing runtime UID/GID and private state during migration.
+
 ## Operate and verify
 
 Root-started containers default to executor UID/GID `1000:1000` and relay real
@@ -164,6 +182,9 @@ an already connected account. Monitoring and sends require their own authority.
 
 ### Isolated plugin commands
 
+The image pins modern Docker Compose, including its standalone executable, so
+existing operator-created volumes retain their data and driver bindings.
+
 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
@@ -176,8 +197,10 @@ Source-based `plugins inspect`, `catalog-add`, and `install` management calls ar
 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
+plugin `updates prepare/apply/recover`; plugin candidate archives must also be inside the
+workspace. Local main-runtime archives require operator preparation outside the
+agent, because the runtime contains the privileged broker. The agent can apply
+an operator-prepared candidate. 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.
 

package/docs/local-qa.md

@@ -6,6 +6,11 @@ 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.
 
+For isolated agents, the operator prepares main-runtime archives through the
+host-bound launcher outside the agent. The isolated agent may apply that prepared
+job; its broker rejects agent-supplied main-runtime archives. Plugin candidates
+retain the workspace-scoped preparation flow below.
+
 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

package/docs/plugin-guide.md

@@ -57,7 +57,16 @@ At minimum, provide:
   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
+required manifests and Docker inputs. `ez tools list --details` includes
+`skillReads`: literal command argument arrays for reading each installed skill.
+Use `ez tools skill <plugin> <declared-path>` to return its text and pinned
+revision. The isolated executor cannot open private host package paths directly;
+the authorized broker reads only manifest-declared regular skill files, without
+copying them into the agent workspace. Skill reads reject symlinks and files over
+64 KiB. The existing generic discovery footer remains accurate; no plugin-specific
+usage snippet or per-turn instruction is needed for this read contract.
+
+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).
@@ -199,4 +208,3 @@ hash.
 
 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

@@ -29,7 +29,14 @@ initial main onboarding; no sibling repository, broker or provider account is
 needed. Finish owner pairing and verify an actual Telegram agent reply first.
 Init creates a private registry and `tools/bin/ez`, adds a
 managed AGENTS.md registry locator, and binds the matching host executor to that bin
-folder. Native binaries are linked through; an existing `ez` collision fails.
+folder. Native binaries are linked through; the package's own `bin/ez` is replaced
+by that bound launcher, while an unrelated existing `ez` collision fails.
+Both host-bound and isolated `ez --help` list installed native scheduling and delivery helpers
+under `native`, with literal `argv` entries for their help. These are existing
+native executables, not plugin aliases; discovery does not grant authority.
+Standalone registries omit helpers they do not have installed. The managed
+workspace locator remains unchanged: core help discovers native controls and
+`tools list --details` discovers registered plugins.
 Run before starting the host executor. For an already running installation,
 place a symlink to the returned launcher in that agent's existing private bin
 directory and set that binding's `toolsHome` to the absolute registry directory.
@@ -52,6 +59,10 @@ 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
+access. Operator-owned private network grants also work through the broker:
+each grant binds an exact reviewed plugin revision and declared service, and
+never attaches the relay or broker itself to that network. The host binding
+must remain outside the agent's writable mounts. The client has no 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
@@ -68,7 +79,10 @@ 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.
+`plugins uninstall` and the local-file plugin `updates prepare/apply/recover` lifecycle.
+Local main-runtime archives require operator preparation outside the agent:
+the agent cannot author replacement code for its privileged broker. It may
+apply an already prepared operator candidate through the normal update queue.
 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.
@@ -386,6 +400,12 @@ and `skills`. Descriptions are limited to 200 characters in this view; full
 instructions stay in the skill. Installation, replacement and removal are reflected
 on the next read, without hooks, LLM calls or a cached inventory file.
 
+The additive `skillReads` field supplies literal argument arrays for
+`ez tools skill <plugin> <declared-path>`. This read returns JSON with the
+installed plugin revision, declared path and skill content. Use it in isolated
+agents, where host package paths are private. It reads only the installed
+manifest's skills; arbitrary files, symlinks and files over 64 KiB are rejected.
+
 `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, SOUL.md, USER.md, or an `inbox/`/`work/` layout; upgrades preserve

package/docs/selective-monitoring.md

@@ -32,8 +32,13 @@ Infer the complete job from ordinary language:
   leaves action intent unclear, ask one plain question: “Should I reply for you,
   or just keep the messages for you to review?” Do not ask when the job resolves it.
 
-Apply the required core confirmation to the concrete proposal, not an extra
-questionnaire. Use the owner's existing contact, purpose and disclosure limits.
+Use `ezenciel-agents-task start` when the owner's request already authorizes the
+job. The current owner turn grants the concrete contact, purpose, shareable
+context and expiry; no second confirmation is needed. The native engine judges
+the owner's intent. Core validates the owner binding and enforces that scope.
+Use `propose` only when a new owner decision is needed, such as additional
+disclosure or commitments outside the request. Never derive authority from
+correspondence, a scheduled run or the tool's availability.
 For an ongoing incoming-only conversation, use `--until-revoked`; finite tasks remain bounded. Explain the expiry only
 when it matters to that proposed job; never silently expand or renew permission.
 
@@ -76,11 +81,11 @@ provider command container is not proof the relay can reach it. Do not edit core
 source/grant JSON directly. Other adapters use their declared socket paths;
 provider names do not change authority checks.
 
-## Propose, confirm, verify
+## Start the authorized task and verify
 
-For an outbound job such as a booking, use `ezenciel-agents-task propose` WITHOUT
+For an outbound job such as a booking, use `ezenciel-agents-task start` WITHOUT
 `--incoming-only`: it starts the inquiry and then watches replies. For “answer if
-they message,” use `ezenciel-agents-task propose --incoming-only` with the
+they message,” use `ezenciel-agents-task start --incoming-only` with the
 registered source, canonical contact, purpose, explicitly shareable context file
 and expiry. No need to invent a booking objective: “conversational replies to
 this contact, no private disclosures or commitments” is a legitimate purpose.
@@ -99,7 +104,7 @@ separate from private PA memory. Group text is supported; media is not yet.
 
 ## Everyone on an enabled channel
 
-When the owner explicitly asks to answer anyone on one channel, propose one
+When the owner explicitly asks to answer anyone on one channel, start one
 incoming-only `--any-conversation` grant for that registered source. The flag
 also selects `--until-revoked` and contact `*`. Do not widen “this group,” “this
 person,” or “customers in this list” into everyone. The source must support a
@@ -129,16 +134,16 @@ Library source:
 The registered alias must declare `channelQuery: true` with explicit exposure
 metadata showing that it accepts external input but cannot send, change records,
 or require interactive review. Core verifies that installed declaration on every
-invocation. Verify the selected source and query alias first, then propose:
+invocation. Verify the selected source and query alias first, then start:
 
 ```sh
-ezenciel-agents-task propose --source telegram --any-conversation \
+ezenciel-agents-task start --source telegram --any-conversation \
   --purpose "Answer questions using approved public knowledge" \
   --context-file work/public-answer-policy.txt \
   --capability-file work/public-answer-capabilities.json
 ```
 
-The approval names the audience, disclosure context and exact command vectors.
+The grant binds the audience, disclosure context and exact command vectors.
 Command output may be shown to anyone in that audience. External writes need
 their own bounded tool contract and receipts. Revocation stops new capture,
 cancels queued replies and rechecks every tool/send. Public Telegram groups must
@@ -147,17 +152,26 @@ and the source-wide public backlog is bounded. Core admits at most 60 public
 conversations and 60 replies per hour. A grant revokes after 1,000 conversations
 or replies so the owner must review continued broad access.
 
-The core presents the exact proposal for owner confirmation. Ordinary messages
-inside that grant need no repeated confirmations. Incoming-only grants create
+`start` returns active only after the provider accepts the watch and core saves
+the scoped grant. `propose` instead presents the exact scope for owner confirmation.
+Ordinary messages inside an active grant need no repeated confirmations. Incoming-only grants create
 no initial run or opening message. They remain active across replies until expiry
 or owner revocation; the worker cannot close a watch by calling `complete`.
-After handling a message, save a task note and finish the run. After approval, verify active core state,
+After handling a message, save a task note and finish the run. After activation, verify active core state,
 contact and expiry, source reachability, and the provider's task watch. With
 `--incoming-only`, an empty conversation is correctly idle until a new message.
 If approval is still pending, say pending; if setup failed, name the actual
 failure and continue repair within scope. Never report “active” based on notes,
 installation, connected status or subscription alone.
 
+Active grants survive relay restarts independently of transient approval messages.
+An initial outgoing run is dispatched at most once; a restart may lose an in-flight
+run, and core never blindly repeats its opener. New matching correspondence can
+still resume the task. Legacy tasks without a persisted grant still require their
+original live approval; if that was lost on restart, revoke and recreate within
+the owner's existing authority. Pending proposals never become active merely
+because their approval record disappeared.
+
 After an authorized test message, inspect the corresponding task run and send
 receipt and compare recipient readback. An accepted send is not proof of delivery.
 After revocation/expiry no subsequent reply may dispatch. Keep these checks

package/docs/upgrades.md

@@ -164,7 +164,11 @@ applying job before resuming normal work. A failed build leaves the old runtime
 running. Failed activation restores the previous code/configuration and checks it.
 If recovery itself fails, inspect and fix the reported infrastructure problem,
 then use `ez updates recover <job-id>` and finish the turn. This retries only the
-saved code/configuration recovery, not provider operations.
+saved code/configuration recovery, not provider operations. If the original relay
+is already running and healthy with the exact saved immutable image, recovery
+keeps it while restoring the host and bindings. This also works when Docker
+has removed that image index but retained the original container. Other images
+and unhealthy relays still require the normal Compose replacement.
 An update never wakes the agent or injects wrapper state into its session; the
 owner or agent inspects receipts with `ez updates` when asked.
 

package/package.json

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

package/src/agent-install.ts

@@ -79,9 +79,11 @@ export const createAgent = async (options: {
       EZ_AGENT_WORKSPACE: join(deploymentDir, 'mind'),
       EZ_CONTROL_DIR: join(deploymentDir, 'control'),
       EZ_TOOLS_HOME: join(deploymentDir, 'tools'),
-      EZ_PLUGIN_BROKER_SOCKET: join(deploymentDir, 'control', 'plugin-broker.sock'),
-      EZ_PLUGIN_BROKER_HOST_CONFIG: join(deploymentDir, 'host-executor.json'),
-      ...(isolation === 'isolated' ? { COMPOSE_PROFILES: 'isolated' } : {}),
+      ...(isolation === 'isolated' ? {
+        EZ_PLUGIN_BROKER_SOCKET: join(deploymentDir, 'control', 'plugin-broker.sock'),
+        EZ_PLUGIN_BROKER_HOST_CONFIG: join(deploymentDir, 'host-executor.json'),
+        COMPOSE_PROFILES: 'isolated',
+      } : {}),
       EZ_WHATSAPP_IPC_VOLUME: `${project}-whatsapp-ipc`,
       EZ_WHATSAPP_CLIENT_VOLUME: `${project}-whatsapp-client`,
     }

package/src/ai-cli.ts

@@ -2,18 +2,27 @@ import { parseArgs } from 'node:util'
 import { randomBytes } from 'node:crypto'
 import { join } from 'node:path'
 import { readFile } from 'node:fs/promises'
-import { readModels, validateSelection, type AiPreset } from './ai.js'
+import { readModels, presetProvider, validateSelection, type AiPreset } from './ai.js'
 import { ControlStore } from './control-state.js'
 
 const {values,positionals}=parseArgs({allowPositionals:true,options:{help:{type:'boolean'},cli:{type:'string'},provider:{type:'string'},model:{type:'string'},effort:{type:'string'}}})
 if(values.help){
-  console.log('Usage: ezenciel-agents-ai list | select --cli <installed-cli> [--provider <provider>] [--model <model>] [--effort <effort>]\nChoose only values returned by list. Selection affects subsequent messages; queued work and the installation default are unchanged.')
+  console.log('Usage: ezenciel-agents-ai list | select --cli <installed-cli> [--provider <provider>] [--model <model>] [--effort <effort>] | default\nChoose only values returned by list. Selection affects subsequent messages; default makes the selected AI the choice for new conversations. Queued work is unchanged.')
   process.exit(0)
 }
 if (!process.env.EZ_CONTROL_DIR) throw new Error('Use this agent’s bound control directory')
 const catalog=await readFile(join(process.env.EZ_CONTROL_DIR,'host-executor','models.json'),'utf8')
   .then(text=>JSON.parse(text)).catch(()=>readModels(undefined,undefined,join(process.env.EZ_CONTROL_DIR!,'cli','codex'),undefined,undefined,undefined,process.env.EZ_CONTROL_DIR))
 if(positionals[0]==='list')console.log(JSON.stringify(catalog))
+else if(positionals[0]==='default'){
+  const control=new ControlStore(process.env.EZ_CONTROL_DIR,900000)
+  const state=await control.status()
+  const selected=state.ai?.presets.find(p=>p.id===state.ai?.selectedId)
+  if(!selected)throw new Error('No selected AI')
+  await validateSelection(selected,catalog)
+  await control.defaultPreset(selected.id)
+  console.log(JSON.stringify({default:selected,applies:'new conversations; current and queued work unchanged'}))
+}
 else if(positionals[0]==='select'){
   const preset:AiPreset={id:randomBytes(8).toString('hex'),name:[values.provider,values.model||values.cli,values.effort].filter(Boolean).join(' · '),cli:values.cli||'',provider:values.provider,model:values.model,effort:values.effort}
   await validateSelection(preset,catalog)
@@ -24,6 +33,6 @@ else if(positionals[0]==='select'){
   const selected=existing||preset
   if(!existing)await control.savePreset(selected)
   const current=state.ai.presets.find(p=>p.id===state.ai!.selectedId)!
-  await control.selectPreset(selected.id,state.activeSession?.sessionId??null,current.cli!==selected.cli||current.provider!==selected.provider||Boolean(state.activeSession&&!state.activeSession.cli))
+  await control.selectPreset(selected.id,state.activeSession?.sessionId??null,current.cli!==selected.cli||presetProvider(current)!==presetProvider(selected)||Boolean(state.activeSession&&!state.activeSession.cli))
   console.log(JSON.stringify({selected,defaultUnchanged:true,applies:'subsequent messages; queued work keeps its captured choice'}))
-}else throw new Error('Use list or select --cli <installed-cli> [--provider <provider>] [--model <model>] [--effort <effort>]')
+}else throw new Error('Use list, select --cli <installed-cli> [--provider <provider>] [--model <model>] [--effort <effort>], or default')