@jc_stack/ez-agents 0.1.0-beta.47 → 0.1.0-beta.48

package/.env.example

@@ -13,6 +13,9 @@ EZ_AGENT_WORKSPACE=./agent
 # Optional. Default is 300.
 # Agent execution has no wall-clock timeout. Use /stop or schedule cancel.
 
+# Maximum concurrent owner-scheduled jobs; foreground chat keeps a separate serial lane.
+# EZ_SCHEDULED_CONCURRENCY=6
+
 # CLI Executor adapter. Supported: codex (default), codex-gui, claude, grok, opencode, pi
 # Switch easily with: pnpm run setup <executor-name>
 EZ_EXECUTOR_CLI=codex

package/AGENTS.md

@@ -120,8 +120,8 @@ round merely to seek more criticism, tests or hypothetical edge cases.
 - **Rate limits:** Avoid spamming bubbles to respect Telegram’s 1 message/sec per-chat rate limit.
 
 ## 6. Concurrency & Workspace Invariants
-- **Responsive owner channels:** One foreground turn and one owner-scheduled turn may run concurrently; each stream stays serial. Separate native sessions isolate history and engine state, while the agent-owned Markdown workspace is shared. The engine coordinates shared file updates and plugins guard canonical record writes. Do not add a second reply agent, scheduler or execution queue.
-- The delivery socket carries every cross-process enqueue/receipt, never control/ files. Host plugin workspace invocations remain excluded until both native turns finish. Scheduled jobs keep separate native CLI sessions and control-side task state. Restricted contact tasks retain their separate authorization boundary. Delegation decisions and goal persistence belong to the agent/executor; there is no automatic planner or canned chat ACK. Production executor runs have no wall-clock timeout; cancellation is explicit.
+- **Responsive owner channels:** One foreground turn and up to `EZ_SCHEDULED_CONCURRENCY` owner-scheduled turns may run concurrently (default six); foreground stays serial. Separate native sessions isolate history and engine state, while the agent-owned Markdown workspace is shared. The engine coordinates shared file updates and plugins guard canonical record writes. Do not add a second reply agent, scheduler or execution queue.
+- The delivery socket carries every cross-process enqueue/receipt, never control/ files. Host plugin workspace invocations remain excluded until all native turns finish. Scheduled jobs keep separate native CLI sessions and control-side task state. Restricted contact tasks retain their separate authorization boundary. Delegation decisions and goal persistence belong to the agent/executor; there is no automatic planner or canned chat ACK. Production executor runs have no wall-clock timeout; cancellation is explicit.
 
 ## 7. Fail-Closed Authority (Channel Access ≠ Execution)
 - Incoming messages outside the approved owner binding must **never** spawn the executor. A first DM or group message records a pending request only. Explicitly approved owner groups grant owner access to all human members in that exact chat; bots and anonymous posts are ignored.

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.1.0-beta.48
+
+- Skip empty or unchanged scheduled work through owner-configured installed read-only plugin preflight. Invalid or unavailable reads fail closed; saved execution settings and recurring timing remain intact. The bound plugin broker is required.
+- Run explicitly registered workspace scripts through the existing native scheduler without starting a model. Preserve registration revision/hash, cancellation, timeout, isolated environment and run receipts.
+- Run Claude Code with an agent-bound configuration and native model/effort discovery. Older Claude sessions need `/new`; host login sharing supports OAuth only, and isolated agents log in separately.
+- Keep owner channels responsive with configurable scheduled concurrency, default six.
+- Expose bounded, sanitized owner run and delivery evidence through native controls.
+- Repair transient plugin admission and isolated broker readiness after atomic binding changes; include isolated executor utilities.
+- Keep Codex version discovery JSON separate from stderr notices.
+- Validate Docker CI against audited Codex 0.160.1 instead of a moving registry tag; managed native version selection is unchanged.
+- Read scoped TXT/PDF and JPEG/PNG/WebP attachments through the shared native MCP path. MP4 attachments supply bounded sampled frames to native vision; speech remains in the provider-sourced incoming transcript.
+
+- Add short-lived browser conversation links for explicitly granted restricted discussions, retaining each task’s context and tool permissions.
+- Preserve the existing runtime file owner when an administrator replaces discussion application grants, keeping private mode 0600 and preventing restricted task startup failures.
+- Forward only the existing broker and delivery socket paths to the trusted task MCP subprocess, allowing scoped browser launch through the isolated installed launcher without exposing a tool registry.
+- Audit restricted native tools on Codex 0.160.1 and retain the exact version gate.
+- Extend the existing speech renderer with OpenRouter TTS and Ogg Opus/WAV encoding.
+- Allow authorized task replies to use core-rendered voice on supporting channels, with post-synthesis authorization and unchanged uncertain-send protection.
+
+Beta limits: live fresh-host/reboot acceptance remains pending. Claude host OAuth login sharing and human voice/media exchanges retain their documented live-QA limitations. Publication does not establish an installed-agent upgrade or activate new schedule gates.
+
 ## 0.1.0-beta.47
 
 - Trigger an existing scheduled task manually with its saved instructions, model,

package/Dockerfile

@@ -1,7 +1,7 @@
 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 && rm -rf /var/lib/apt/lists/*
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates git util-linux ffmpeg poppler-utils docker.io jq python3 python-is-python3 && rm -rf /var/lib/apt/lists/*
 COPY --from=compose-bin /docker-compose /usr/local/bin/docker-compose
 ENV PNPM_HOME=/opt/pnpm COREPACK_HOME=/opt/corepack COREPACK_DEFAULT_TO_LATEST=0
 ENV PATH=/opt/pnpm:$PATH
@@ -30,6 +30,10 @@ RUN pnpm add --global --allow-build=opencode-ai@${OPENCODE_CLI_VERSION} opencode
 # Pin the reviewed CLI for repeatable release images.
 ARG PI_CLI_VERSION=0.87.1
 RUN pnpm add --global --ignore-scripts @earendil-works/pi-coding-agent@${PI_CLI_VERSION} && command -v pi
+# Isolated agents select Claude Code from the relay menu with an agent-bound
+# CLAUDE_CONFIG_DIR login (control/cli/claude). Pin the reviewed CLI.
+ARG CLAUDE_CLI_VERSION=2.1.286
+RUN pnpm add --global --allow-build=@anthropic-ai/claude-code@${CLAUDE_CLI_VERSION} @anthropic-ai/claude-code@${CLAUDE_CLI_VERSION} && command -v claude && claude --version
 RUN chmod +x docker/entrypoint.sh bin/ez bin/ezenciel-agents* && mkdir -p /state/control /state/home /workspace && chown node:node /state/control /state/home /workspace
 RUN node -e 'for (const [name, target] of Object.entries(require("./package.json").bin)) require("node:fs").symlinkSync("/app/" + target, "/usr/local/bin/" + name); require("node:fs").symlinkSync("/app/bin/ez", "/usr/local/bin/ez")'
 # Build identity for relay status (package version stays release-owned).

package/THIRD_PARTY_NOTICES.md

@@ -8,9 +8,12 @@ The container is built locally; no bundled third-party binary image is promised.
 
 Direct runtime dependencies: grammy (MIT), tsx (MIT). Development dependencies
 include TypeScript (Apache-2.0) and Node type definitions (MIT). The runtime
-image installs ffmpeg, Debian packages, and these reviewed CLI versions:
-`@openai/codex` 0.153.4 (Apache-2.0), `opencode-ai` 1.18.32 (MIT), and
-`@earendil-works/pi-coding-agent` 0.87.1 (MIT). Redistributing the image
+image installs ffmpeg, Poppler (`poppler-utils`, GPL-2.0-or-later), Debian packages, and these reviewed CLI versions:
+`@openai/codex` (Apache-2.0; the build resolves and records the selected version),
+`opencode-ai` 1.18.32 (MIT), `@earendil-works/pi-coding-agent` 0.87.1 (MIT), and
+`@anthropic-ai/claude-code` 2.1.286 (proprietary; Anthropic's legal agreements,
+as referenced by its installed LICENSE.md, govern use). Preserve its installed
+license and README; it is not covered by this repository's MIT license. Redistributing the image
 requires review of its exact package build, notices and corresponding-source
 obligations. Docker and
 host-capable AI CLIs remain separately installed products, not covered by this

package/bin/ez

@@ -91,6 +91,13 @@ const main = async () => {
     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;
   }
+  if(args[0]==='--task-application') {
+    if(args.length!==1 || !runId || !RUN_ID.test(runId))throw Error('Active task run required')
+    const result=await request({version:1,id:randomUUID(),operation:'task-launch',runId,stdin:await readStdin()})
+    if(!result?.ok)throw Error(result?.error || 'Task launch failed')
+    if(result.stdout)process.stdout.write(result.stdout)
+    process.exitCode=result.code;return
+  }
   const stdin = ['plugins', 'tools', 'updates', 'status'].includes(args[0]) ? '' : await readStdin();
   if (['plugins', 'tools', 'updates', 'status'].includes(args[0])) await manager(args);
   else await invoke(args, stdin);

package/docker/broker-readiness.mjs

@@ -0,0 +1,54 @@
+// Trusted operator diagnostic, executed inside the installed broker. Never a
+// socket operation or native-run substitute; no command execution or writes.
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { loadPluginBrokerBinding } from '/app/src/plugin-broker.mjs';
+import { registry, snapshot, checkFolders, hostNetworkBindings } from '/app/src/plugins/manager.mjs';
+
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+export async function brokerReadiness(input, expected) {
+  if (!Array.isArray(expected) || expected.length !== 3 || expected.some(value => !/^[a-f0-9]{64}$/.test(value)))
+    throw Error('Expected host, registry and configuration fingerprints');
+  const binding = await loadPluginBrokerBinding(input);
+  const files = [binding.hostConfig, path.join(binding.home, 'registry.json'), path.join(binding.home, 'config.json')];
+  const verify = async () => {
+    for (let i = 0; i < files.length; i++) if (hash(await fs.readFile(files[i])) !== expected[i])
+      throw Error('Isolated broker configuration fingerprint mismatch');
+  };
+  await verify();
+  if (!(await fs.stat(binding.socket)).isSocket()) throw Error('Isolated broker socket unavailable');
+  const config = JSON.parse(await fs.readFile(files[2], 'utf8'));
+  const r = await registry(binding.home), plugins = [];
+  for (const [id, record] of Object.entries(r.plugins)) {
+    const trusted = await snapshot(record.source);
+    if (trusted.manifest.id !== id || record.source !== trusted.source || record.revision !== trusted.revision ||
+        JSON.stringify(record.manifest) !== JSON.stringify(trusted.manifest) ||
+        JSON.stringify(record.deployment) !== JSON.stringify(trusted.deployment) ||
+        JSON.stringify(record.sharedRevisions || {}) !== JSON.stringify(trusted.sharedRevisions))
+      throw Error('Registry plugin identity is not the reviewed source');
+    for (const alias of Object.keys(record.manifest.commands))
+      if (r.commands[alias] !== id || !record.deployment.commands[alias]) throw Error('Corrupt command registry');
+    await checkFolders(config, record, binding.home);
+    await hostNetworkBindings(config, record, binding.home);
+    plugins.push({ id, revision: record.revision });
+  }
+  await verify();
+  return { version: 1, ready: true, hostSha256: expected[0], registrySha256: expected[1], configSha256: expected[2], plugins };
+}
+{
+  const args = process.argv.slice(process.argv[1]?.endsWith('/broker-readiness.mjs') ? 2 : 1);
+  try {
+    const result = await brokerReadiness({
+      home: process.env.EZ_PLUGIN_BROKER_HOME, workspace: process.env.EZ_PLUGIN_BROKER_WORKSPACE,
+      controlDir: process.env.EZ_PLUGIN_BROKER_CONTROL_DIR, socket: process.env.EZ_PLUGIN_BROKER_SOCKET,
+      hostConfig: process.env.EZ_PLUGIN_BROKER_HOST_CONFIG,
+    }, args);
+    console.log(JSON.stringify(result));
+  } catch {
+    // Validation exceptions can contain private paths. Keep operator/public
+    // readback content-free; updater still retains failure and rollback state.
+    console.error('EZ_BROKER_STRUCTURAL_READINESS_FAILED');
+    process.exitCode = 1;
+  }
+}

package/docker/broker-update-smoke.mjs

@@ -0,0 +1,86 @@
+// Explicit synthetic Linux mount regression. No credentials, native identities,
+// provider calls or existing deployments. Run against the exact reviewed image:
+// EZ_RELAY_IMAGE=<immutable image ID> node docker/broker-update-smoke.mjs
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { atomic, snapshot } from '../src/plugins/manager.mjs';
+import { execute, refreshBroker } from '../src/updates/runtime.mjs';
+const docker=(...args)=>execFileSync('docker',args,{encoding:'utf8',stdio:['ignore','pipe','pipe'],timeout:120000}).trim();
+const hash=bytes=>createHash('sha256').update(bytes).digest('hex');
+if(process.argv[2]!=='--inside') {
+ const image=process.env.EZ_RELAY_IMAGE;
+ if(!/^sha256:[a-f0-9]{64}$/.test(image||''))throw Error('Supply the exact reviewed runtime image ID');
+ const volume=`e245-${process.pid}`;
+ try {
+  docker('volume','create',volume);
+  const root=JSON.parse(docker('volume','inspect',volume))[0].Mountpoint;
+  const output=docker('run','--rm','--network','none','--mount',`type=volume,source=${volume},target=${root}`,
+   '--mount','type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock',
+   '--env','EZ_DOCKER_COMPOSE=standalone','--entrypoint','node',image,'--import','/app/node_modules/tsx/dist/loader.mjs',
+   '/app/docker/broker-update-smoke.mjs','--inside',root,image);
+  console.log(output);
+ }finally {docker('volume','rm',volume);}
+} else {
+ const root=process.argv[3],image=process.argv[4],home=path.join(root,'tools'),workspace=path.join(root,'mind'),controlDir=path.join(root,'control');
+ const hostConfig=path.join(root,'host-executor.json'),socket=path.join(controlDir,'b.sock'),project=`e245-${hash(root).slice(0,12)}`;
+ const config={schemaVersion:1,workspace,hostConfig,deploymentDir:root};
+ const args=['compose','--env-file',path.join(root,'docker.env')];
+ const call=(tail)=>execute('docker',[...args,...tail],{stdoutOnly:true,timeout:120000});
+ const container=async name=>(await call(['ps','-q',name])).trim();
+ const inside=async script=>call(['exec','-T','plugin-broker','node','--input-type=module','-e',script]);
+ const prepare=()=>inside(`import {prepareCommand} from '/app/src/plugins/manager.mjs'; await prepareCommand(${JSON.stringify(home)},'sample',[]); console.log('prepared');`);
+ const mounted=()=>inside(`import fs from 'node:fs'; import {createHash} from 'node:crypto'; console.log(createHash('sha256').update(fs.readFileSync(${JSON.stringify(hostConfig)})).digest('hex'));`);
+ const fingerprints=async()=>Promise.all([hostConfig,path.join(home,'registry.json'),path.join(home,'config.json')].map(async f=>hash(await fs.readFile(f))));
+ const probe=async()=>call(['exec','-T','plugin-broker','node','--import','/app/node_modules/tsx/dist/loader.mjs','/app/docker/broker-readiness.mjs',...await fingerprints()]);
+ const agent={name:'synthetic',toolsHome:home,workspace,controlDir};
+ const host=(revisions)=>({isolation:'isolated',agents:[{...agent,pluginNetworkBindings:{sample:{revisions,bindings:[{service:'sample',network:'synthetic-reviewed-network'}]}}}]});
+ const records=[];
+ for(const directory of [home,workspace,controlDir])await fs.mkdir(directory,{recursive:true});
+ for(const version of ['1.0.0','1.0.1']) {
+  const source=path.join(home,'packages','sample',version);
+  await fs.mkdir(path.join(source,'bin'),{recursive:true});
+  const manifest={schemaVersion:1,id:'sample',version,commands:{sample:{executable:'bin/example.mjs',args:[]}},skills:[]};
+  const deployment={schemaVersion:1,services:{sample:{buildTarget:'runtime',volumes:{},healthcheck:['node','--version']}},commands:{sample:{service:'sample',argv:['node','/app/bin/example.mjs']}},exports:{}};
+  for(const [name,body] of Object.entries({'package.json':JSON.stringify({name:'synthetic-plugin',version,files:['bin']}),'ez-plugin.json':JSON.stringify(manifest),'ez-deployment.json':JSON.stringify(deployment),'Dockerfile':'FROM scratch AS runtime','.dockerignore':'','bin/example.mjs':'console.log("synthetic")'}))await fs.writeFile(path.join(source,name),body);
+  const s=await snapshot(source);
+  records.push({source,revision:s.revision,manifest:s.manifest,deployment:s.deployment,sharedRevisions:s.sharedRevisions,project:`ezp-${hash(home).slice(0,16)}-sample`,compose:path.join(home,'packages','sample','compose.json')});
+ }
+ const [a,b]=records;
+ const publish=record=>atomic(path.join(home,'registry.json'),{schemaVersion:1,owner:home,plugins:{sample:record},commands:{sample:'sample'}});
+ await atomic(path.join(home,'config.json'),config);await atomic(hostConfig,host([a.revision]));await publish(a);
+ const brokerEnv={EZ_PLUGIN_BROKER_HOME:home,EZ_PLUGIN_BROKER_WORKSPACE:workspace,EZ_PLUGIN_BROKER_CONTROL_DIR:controlDir,EZ_PLUGIN_BROKER_HOST_CONFIG:hostConfig,EZ_PLUGIN_BROKER_SOCKET:socket,EZ_DOCKER_COMPOSE:'standalone'};
+ const sleep=['node','-e','setInterval(()=>{},1000)'];
+ const compose={services:{relay:{image,network_mode:'none',entrypoint:sleep},'plugin-broker':{image,network_mode:'none',entrypoint:['node','--import','/app/node_modules/tsx/dist/loader.mjs','/app/src/plugin-broker.mjs'],environment:brokerEnv,volumes:[`${home}:${home}`,`${workspace}:${workspace}:ro`,`${controlDir}:${controlDir}`,`${hostConfig}:${hostConfig}:ro`,'/var/run/docker.sock:/var/run/docker.sock'],healthcheck:{test:['CMD','node','-e',`process.exit(require('fs').statSync(${JSON.stringify(socket)}).isSocket()?0:1)`],interval:'1s',timeout:'5s',retries:15}}}};
+ await atomic(path.join(root,'compose.json'),compose);
+ await fs.writeFile(path.join(root,'docker.env'),`COMPOSE_PROJECT_NAME=${project}\nCOMPOSE_FILE=${path.join(root,'compose.json')}\nEZ_EXECUTOR_TRANSPORT=local\n`);
+ try {
+  await call(['up','-d','--no-build','--pull','never','--wait','--wait-timeout','30']);
+  const relay=await container('relay'),oldBroker=await container('plugin-broker'),oldHash=(await mounted()).trim();
+  assert.equal(JSON.parse(await probe()).ready,true);assert.equal((await prepare()).trim(),'prepared');
+  await atomic(hostConfig,host([a.revision,b.revision]));await publish(b);
+  assert.equal((await mounted()).trim(),oldHash);assert.notEqual(oldHash,(await fingerprints())[0]);
+  await assert.rejects(prepare(),/not pinned/);await assert.rejects(probe(),/STRUCTURAL_READINESS_FAILED/);
+  console.log('PASS stale inode: live socket; mounted A; registry B rejected; structural probe rejected');
+  const ready=await refreshBroker(config);
+  const newBroker=await container('plugin-broker');assert.notEqual(newBroker,oldBroker);assert.equal(await container('relay'),relay);
+  assert.equal((await mounted()).trim(),ready.hostSha256);assert.equal((await prepare()).trim(),'prepared');
+  assert.equal(ready.plugins[0].revision,b.revision);
+  console.log(JSON.stringify({stage:'activation',oldBroker,newBroker,relay,hostSha256:ready.hostSha256,registrySha256:ready.registrySha256,revision:b.revision}));
+  await atomic(hostConfig,host([a.revision]));
+  await assert.rejects(refreshBroker(config),/STRUCTURAL_READINESS_FAILED/);await assert.rejects(prepare(),/not pinned/);
+  console.log('PASS unapproved B remains rejected after recreation');
+  await publish(a);const rolledBack=await refreshBroker(config);
+  assert.equal((await mounted()).trim(),rolledBack.hostSha256);assert.equal(rolledBack.plugins[0].revision,a.revision);assert.equal((await prepare()).trim(),'prepared');assert.equal(await container('relay'),relay);
+  console.log(JSON.stringify({stage:'rollback',broker:await container('plugin-broker'),relay,hostSha256:rolledBack.hostSha256,registrySha256:rolledBack.registrySha256,revision:a.revision}));
+  // Read-only probe must neither repair a tampered snapshot nor create leases.
+  await fs.appendFile(path.join(a.source,'bin/example.mjs'),'\n// unreviewed');await assert.rejects(probe(),/STRUCTURAL_READINESS_FAILED/);
+  await fs.writeFile(path.join(a.source,'bin/example.mjs'),'console.log("synthetic")');
+  await assert.rejects(call(['exec','-T','--env',`EZ_PLUGIN_BROKER_HOST_CONFIG=${root}/missing.json`,'plugin-broker','node','--import','/app/node_modules/tsx/dist/loader.mjs','/app/docker/broker-readiness.mjs',...await fingerprints()]),/STRUCTURAL_READINESS_FAILED/);
+  await fs.rm(hostConfig);await assert.rejects(probe(),{code:'ENOENT'});
+  await atomic(hostConfig,host([a.revision]));await refreshBroker(config);
+  console.log('PASS source tamper and missing host file fail; no provider command or native run identity used');
+ }finally {await call(['down','--volumes','--remove-orphans']);}
+}

package/docker/run.ts

@@ -20,7 +20,7 @@ try { privateEnv = parseEnv(readFileSync(3, 'utf8')) } catch (error) {
   if ((error as NodeJS.ErrnoException).code !== 'EINVAL' && (error as NodeJS.ErrnoException).code !== 'EBADF') throw error
 } finally { try { closeSync(3) } catch {} }
 for (const [key, value] of Object.entries(privateEnv)) {
-  if (value !== undefined && ['TELEGRAM_BOT_TOKEN', 'GEMINI_API_KEY', 'OPENAI_API_KEY', 'EZ_CHANNEL_BACKEND_TOKEN'].includes(key)) process.env[key] = value
+  if (value !== undefined && ['TELEGRAM_BOT_TOKEN', 'GEMINI_API_KEY', 'OPENAI_API_KEY', 'OPENROUTER_API_KEY', 'EZ_SPEECH_PROVIDER', 'EZ_SPEECH_MODEL', 'EZ_SPEECH_VOICE_EN', 'EZ_SPEECH_VOICE_ES', 'EZ_CHANNEL_BACKEND_TOKEN', 'EZ_SCHEDULED_CONCURRENCY'].includes(key)) process.env[key] = value
 }
 privateEnv = {}
 const [command = 'start', ...args] = process.argv.slice(2)

package/docs/application-channel.md

@@ -20,7 +20,7 @@ unfinished run returns 409, missing speech configuration 503, and provider
 failure 502. Depleted Gemini credits return 503 with
 `code: speech_credits_depleted`. Audio responses have `Cache-Control: no-store`.
 
-Configure `GEMINI_API_KEY` on the relay. The existing speech renderer uses
+Configure `GEMINI_API_KEY` on the relay. Alternatively select `EZ_SPEECH_PROVIDER=openrouter`, supply `OPENROUTER_API_KEY` privately on the relay, and set `EZ_SPEECH_MODEL` (default `fish-audio/s2.1-pro-free:free`). The same renderer converts provider MP3 to the channel’s WAV or Ogg Opus format; provider failures do not select another provider. The existing speech renderer uses
 `gemini-3.8-flash-lite-tts`; Telegram still receives Ogg Opus. Applications should
 send `{"language":"en"}` or `{"language":"es"}` to select
 `EZ_SPEECH_VOICE_EN` or `EZ_SPEECH_VOICE_ES` (both default to Kore). Telegram
@@ -451,3 +451,34 @@ 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.
+
+## Restricted discussion browser handoff
+
+A trusted application may host a browser conversation for existing exact-contact
+tasks without inheriting the owner’s workspace or general tools. Outside native
+turns, the installing administrator explicitly grants an installed launch command:
+
+```sh
+ezenciel-agents-application --id browser --task-launch-command voice \
+  --task-launch-args '["launch","--task"]' --task-launch-tasks '["task_0123456789abcdef0123456789abcdef"]'
+```
+
+Use `--task-launch-tasks '"all"'` only with owner approval for all active
+exact-contact discussions. `--disable-task-launch` revokes this handoff while
+keeping the application binding. Wildcard public tasks cannot launch links.
+The restricted native model sees `browser_link` with the approved application
+names; it cannot choose another task, command arguments or identity. The trusted
+broker executes the installed command with a 20-minute task bearer through private
+stdin. The model receives only the resulting short-lived HTTPS browser link.
+This is an explicit mutating capability, separate from read-only channel queries.
+
+The backend checks its task bearer with `POST /v1/registration` and
+`{taskToken}`. It submits `{requestId,scope:"task:TASK_ID",text,taskToken}` to
+`/v1/runs`. Core derives the exact task and contact, binds the original grant and
+application, rechecks owner/source/account/expiry/revocation, and uses the same
+restricted native task executor and task notes. Task requests cannot select
+owner history, AI, files or native sessions. `send` replies to the application
+inbox as text; it does not send an additional channel message. The task bearer
+is hashed in core storage, stays in the trusted backend and expires no later
+than the task. Changed retries and cross-task/application use fail closed.
+No contributor becomes an installation owner.

package/docs/architecture/ai-selection.md

@@ -31,6 +31,16 @@ cross-turn, command, file and unrelated requests are declined rather than being
 guessed or forwarded to a hidden task UI.
 Legacy unbound sessions require the owner's explicit `/new`.
 
+Like Codex's `CODEX_HOME`, Claude runs with an agent-bound `CLAUDE_CONFIG_DIR`
+(`control/cli/claude`): settings, memory, plugins and sessions belong to the
+agent, never the operator's `~/.claude`. Host-capable agents share only the
+installer's OAuth/subscription login by setting `CLAUDE_SECURESTORAGE_CONFIG_DIR`
+empty, so Claude reads and refreshes its default credential store in place. API
+key, `apiKeyHelper` or provider `env` setups in the operator's `~/.claude` are
+not shared; put them in the agent-bound directory instead. Isolated agents log in
+inside their own config directory. Claude conversations started before this
+binding live in the operator's `~/.claude` and need `/new`.
+
 References used for the adapter contract:
 
 - [Codex non-interactive execution](https://learn.chatgpt.com/docs/non-interactive-mode)
@@ -42,7 +52,12 @@ environment and the execution-bound `CODEX_HOME`; discovery starts no session
 or inference. Only visible model names and supported efforts are projected.
 Unavailable discovery retains the native cache. The installed native version
 still owns which models it advertises; Core never guesses newly released aliases.
-Grok/Codex/OpenCode support explicit listed model/effort choices. Other installed clients
+Grok/Codex/OpenCode/Claude support explicit listed model/effort choices. Claude has
+no catalog command, so the installed `claude --help` is its native metadata: the
+documented model aliases and `--effort` levels are listed alongside the client
+default; unparseable help keeps the client default only. A versioned model name (for example
+`claude-sonnet-5-5`) is offered by adding a `claude` entry to the agent's curated
+`control/ai-models.json`; the alias `sonnet` always means the client's current Sonnet. 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`).
@@ -64,8 +79,8 @@ Refresh available AIs repeats default 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
+model/effort settings (or `models` for the default model). Claude reads the agent-bound
+user settings 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/docker-runtime.md

@@ -272,6 +272,29 @@ 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.
 
+## Claude Code auth
+
+Isolated agents run the image Claude Code with `CLAUDE_CONFIG_DIR` set to the
+agent-bound `control/cli/claude`; settings, memory, plugins and sessions stay
+there. Log the agent in once inside its relay, which writes its own
+`.credentials.json` there and never shares or copies the operator login:
+
+```sh
+docker compose exec -it -u "${EZ_RUNTIME_UID:-1000}:${EZ_RUNTIME_GID:-1000}" relay \
+  sh -c 'CLAUDE_CONFIG_DIR="$EZ_CONTROL_DIR/cli/claude" claude auth login'
+```
+
+To share one login across many agents without logging in one by one, create a
+long-lived token once with `claude setup-token` and copy it to each agent's
+`control/cli/claude/oauth-token` (mode `600`). It does not refresh, so agents
+cannot invalidate each other's session the way copied `.credentials.json`
+files can. The file's contents reach only the Claude process as
+`CLAUDE_CODE_OAUTH_TOKEN`; a malformed file fails the run closed.
+
+Without any login, Claude turns fail closed with the native "not logged in"
+error. Host-capable agents use the same agent-bound directory but share the
+installer login in place (`CLAUDE_SECURESTORAGE_CONFIG_DIR` empty).
+
 ## OpenCode auth
 
 Isolated agents run the image OpenCode with `XDG_DATA_HOME` set to the
@@ -319,3 +342,9 @@ restart after repair. Existing authorized work and outbox draining remain active
 polling health remains unhealthy. Transient HTTP, rate-limit and server errors
 may reconnect. grammY still owns reconnect behavior inside its poller; ez does
 not override private library methods or implement a replacement poller.
+
+The isolated executor image includes Node, jq and Python 3 (`python` and
+`python3`) for task-local JSON/text processing. Domain calculations and writes
+remain behind installed plugins. Registered command admission waits up to five
+seconds for the short registry lock; lifecycle changes still fail closed, and
+no caller removes an existing lock. Serialize calls when a plugin requires it.

package/docs/isolated-plugin-update-readiness.md

@@ -0,0 +1,66 @@
+# Isolated plugin update readiness
+Status: proposed acceptance contract; not a claim of installed behavior.
+Source baseline: f192d57d8b1ea2748fe31544ffdb968c827b891e.
+Scope: one causal repair to isolated broker activation and verification.
+
+## Objective and boundaries
+An authorized plugin update must leave the isolated native execution path able to resolve and prepare the exact reviewed plugin revision, or report failure with the existing recovery path. A successful host-side command, running container or socket is insufficient.
+
+Constraints:
+1. Preserve reviewed-revision, host-network, folder, owner and per-run authorization checks. Never authorize a revision merely to make a probe pass.
+2. Keep one registry, broker and updater; no new daemon, retry controller, scheduler or financial workflow.
+3. Preserve the relay, native sessions, unrelated plugins and persistent state during plugin-only refresh.
+4. No credentials, customer data or production run identities in tests or public receipts.
+5. Existing update serialization, active-work admission and uncertain-write reconciliation remain binding.
+
+Owner: updater/broker boundary, principally src/updates/runtime.mjs and existing plugin validation. This does not change domain procedures or models.
+
+## Observed mechanism and confidence
+compose.yaml bind-mounts the host configuration as a single read-only file into plugin-broker. Configuration writers use temporary-file plus rename. A single-file bind mount can retain the prior inode after host-side atomic replacement. The plugin registry can therefore select the new reviewed revision while the broker still sees the old revision list. hostNetworkBindings in src/plugins/manager.mjs correctly rejects that mismatch.
+
+refreshBroker currently invokes Compose restart after plugin registry activation and rollback. That does not explicitly recreate the container/mount. The current broker health check only verifies socket existence. The existing updater regression test confirms restart and inventory version, not mounted configuration identity or executable readiness.
+
+Production diagnosis observed different host and mounted revision authorization, and targeted broker recreation restored the failing boundary. This supports the stale-mount mechanism; the exact historical writer/commit that first replaced the file is not yet established. Do not invent that provenance or attribute every domain deferral to this incident.
+
+## Smallest implementation
+First reproduce the failure with a synthetic deployment. Prefer fixing lifecycle of the existing narrowly scoped mount rather than broadening the mount or making authorization mutable inside the broker.
+
+1. After approved activation changes and registry publication, refresh the isolated broker using the deployment's existing Compose identity and exact installed image. Recreate only plugin-broker, without dependencies/build/pull or relay replacement, and wait for readiness. Use supported equivalent Compose flags rather than hardcoding another project or image.
+2. Apply the same mount-refresh rule to rollback. Restore the old registry/config state owned by the existing transaction, then verify the old revision is again usable. Never restore provider journals or silently erase subsequent unrelated state.
+3. Ensure every updater path that replaces a relevant host file and retains an unchanged broker image cannot skip mount refresh merely because Compose sees the same image/configuration. Include main-update activation/rollback where relevant; do not gratuitously recreate healthy relay processes.
+4. Before completed, compare broker-visible configuration identity with the intended host configuration and verify installed registry/source revision consistency and existing host-network/folder validation. The check must execute inside the actual isolated broker environment, be read-only and bounded, and expose no configuration contents or secrets.
+5. Separate structural readiness from real native invocation evidence. A structural probe must not fabricate EZ_RUN_ID, borrow another run, create permanent authorization, or invoke an arbitrary plugin command that might mutate. Prefer existing prepare/validation primitives with a narrowly scoped trusted diagnostic if no supported read-only probe exists. An actual harmless command through a genuine authorized native run is a separate acceptance step.
+6. A mismatched pin, missing mounted file, failed recreate or failed verification must prevent completed. Use current failed/rollback/recovery-required states and preserve error evidence. Do not swallow probe failures.
+7. Keep socket liveness distinguishable from functional readiness in existing status/diagnostics. Do not build an expensive provider poll into a high-frequency health check or restart endlessly. Document exactly what each level proves.
+
+If code inspection finds a simpler existing supported mechanism meeting all these requirements, use it and explain the equivalence in the PR. Do not bypass pinning, rewrite authorized revisions, mount the entire private deployment directory, or switch execution transport.
+
+## Regression evidence
+Use synthetic, isolated state and real Docker bind-mount behavior where required:
+- Start with approved revision A and a single-file read-only host binding.
+- Atomically replace host configuration with independently approved revision B and activate registry B; reproduce old mounted bytes and rejection in the uncorrected harness.
+- Apply corrected refresh; prove broker sees exact new file identity/content hash and prepares B successfully. Record container identity change and unchanged relay identity.
+- Prove a still-unapproved B remains rejected. Recreate is not authorization.
+- Cover rollback B to A, including mounted bytes, registry identity and readiness.
+- Recreate failure and readback/probe failure must not return completed.
+- A socket that exists while configuration is stale or invalid must not count as functional-ready.
+- Host-capable updates should not start an isolated broker.
+- Preserve existing invalid owner/run, canceled/revoked admission, folder/network mismatch and secret-isolation tests relevant to changed code.
+- Respect active work through existing updater admission. Do not manufacture a second drain/queue mechanism.
+
+Update the existing restart-only test to assert the meaningful behavior. Mocked Compose argument assertions alone cannot prove Linux bind-mount recovery. No test should require customer credentials or invoke a financial command.
+
+## Verification and review
+Run required repository checks on final source: pnpm verify, pnpm run release:check, git diff --check and applicable Docker/packed-artifact checks in docs/releasing.md. Identify test counts, skipped/unrun checks and exact commit/artifact hash honestly. Keep one focused PR and do not include unrelated media work.
+
+The implementation author supplies the final diff, root-cause reproduction, before/after evidence and limits. The assigned reviewer personally checks architecture, correctness, negative cases and exact-head CI, then merges using expected-head protection. Changes after review require affected revalidation. This specification is authored by the reviewer; its authorship is disclosed, and implementation verification must not be described as independent review of the reviewer's own design.
+
+## Direct VM acceptance after merge
+Use the deployment's supported updater on the reviewed artifact. Before activation, record non-secret installed revision/image identities, native active-work state and baseline read-only access; preserve ongoing work and use the updater's normal drain. Never force a restart during an active call.
+
+Verify exact installed commit/artifact and broker/relay identities, mounted configuration fingerprint, reviewed registry identity and structural readiness. Then inspect a genuine native invocation using the same bound launcher, with a harmless help/manifest read and its real run receipt. Do not trigger scores, leverage, trades or other investment workflows as a smoke test. If no authorized diagnostic invocation exists, retain native proof pending the next natural invocation rather than inventing identity.
+
+Success: the corrected lifecycle demonstrably handles atomic binding replacement and rollback, and the installed isolated path accepts the already authorized revision without operator recreation. Source merge, service health and a host-side doctor alone are not success.
+
+## Separate subsequent work
+Outage-to-engineering acknowledgement, recovery/resumption ownership, large-file archive transfer and shared daily-ledger contention are separate causes. They remain follow-up investigations; do not add automatic domain replay, broaden stdin limits, change schedules or rewrite record ownership in this PR.

package/docs/releasing.md

@@ -17,6 +17,10 @@ separate release bot is not required.
 3. Build both Docker targets from a clean checkout:
    `docker build --target test -t ez-release-tests .` and
    `docker build --target runtime -t ez-release-runtime .`.
+   Docker CI pins the reviewed Codex baseline (`TASK_CODEX_VERSION`) with the
+   existing `CODEX_CLI_VERSION` build argument; update that pin when the native
+   audit advances. Baseline CI does not validate a newly published native version.
+   Managed installs and upgrades keep their existing native version selection.
    Main relay: `EZ_RELAY_IMAGE=ez-release-runtime node docker/smoke.mjs`.
    The WhatsApp Compose overlay has no separate relay image; verify its
    provider integration with the synthetic plugin smoke in `docs/plugins.md`.

package/docs/scheduling.md

@@ -55,6 +55,71 @@ Paused, stale-owner, overlapping or held tasks and unmet conditions cannot be
 triggered. Historical deferred tasks keep their source context
 available through `ezenciel-agents-schedule context`.
 
+## Registered script schedules
+
+A schedule has one execution type. **Agent** schedules run the saved prompt with
+their saved engine, model and effort, as described below. **Script** schedules run
+a registered, agent-owned script directly: no model, effort, prompt or native
+session is involved.
+
+```sh
+ezenciel-agents-schedule script register book-freshness \
+  --file scripts/book-freshness.mjs --interpreter node [--arg=VALUE ...] [--timeout-seconds 900]
+ezenciel-agents-schedule create actual-book-freshness-guard \
+  --script book-freshness [--arg=VALUE ...] --cron '15 * * * *' --timezone Asia/Dubai
+ezenciel-agents-schedule script list | show ID | update ID [...] | remove ID
+```
+
+The agent writes, tests and maintains the script; core owns registration,
+scheduling, authorization, process execution, cancellation and run receipts.
+A registration records the owner binding, a workspace-relative entry point, an
+installed interpreter (command name on the executor PATH or absolute path),
+literal arguments, a timeout and the entry point's SHA-256 under a new revision.
+It references the workspace file; core keeps no source copy. Paths outside the
+workspace (including symlink escapes) and shell command strings are rejected.
+Core invokes `interpreter entry registrationArgs... scheduleArgs...` directly,
+without a shell. Missing interpreters fail clearly; nothing is installed.
+
+When an occurrence is queued, the run captures the current registration
+revision and hash. Immediately before spawning, the executor requires that
+revision to be current and the entry-point bytes to match. Changed bytes fail
+the run until the agent explicitly runs `script update`. The hash identifies the
+entry-point file only; it does not certify imported modules or other files.
+
+Script runs use the existing scheduler, admission queue, scheduled concurrency
+limit, one-occurrence-per-schedule rule, run records, delivery binding, manual
+`trigger`, pause/resume/edit/remove and `cancel`. They run in the agent's
+isolated environment (relay or host transport) under its normal identity, with
+the executor environment allowlist plus `EZ_RUN_ID`, `EZ_SCHEDULE_ID`,
+`EZ_SCHEDULE_REVISION`, `EZ_DUE_AT`, `EZ_SCRIPT_ID`, `EZ_SCRIPT_REVISION` and
+`EZ_SCRIPT_SHA256`. Use the run/schedule/due identifiers to form a stable
+occurrence identity. External operations go through the bound plugin CLI; a
+script must not read private databases, call providers directly or acquire
+credentials. A script run can read schedule and script state but cannot change
+registrations or schedules.
+
+A script runs with the agent's runtime identity and file access, but not inside
+a native engine's own sandbox (for example host Codex `workspace-write`); register
+only code the agent would be allowed to run itself. An interpreter inside the
+workspace is rejected because it would be unhashed code.
+
+Each registration has a bounded timeout (default 900 seconds, maximum 21600)
+that does not affect agent runs. Timeout and `cancel` stop the process and its
+children. Failed, timed-out or interrupted script runs are not retried, do not
+fall back to an LLM and do not start a debugging agent. Inspect them with
+`runs`, `run RUN_ID`, `failures` and `evidence`: the run shows the script ID,
+revision and hash, queue/start/finish clocks, exit code, cancellation/timeout,
+failure reason and a 4 KiB redacted tail of stdout/stderr. Those records follow
+the normal relay-memory retention. Stdout is diagnostic only. Process success
+means the script exited 0; domain success still requires the owning plugin's
+validation, receipt and canonical readback, which the script performs and
+records. Notifications use `ezenciel-agents-message` under the normal policy;
+routine unchanged runs should stay quiet.
+
+Editing a schedule replaces it completely, so it may switch execution type.
+When replacing an agent schedule with a script, move any judgment the prompt
+performed to its owning workflow first; the script schedule does not carry it.
+
 ## Execution and authority
 
 Due occurrences enter the durable queue with stable IDs and literal task text.
@@ -63,17 +128,20 @@ No identity files or role instructions are generated. Existing workspace Markdow
 provides context, including native `AGENTS.md` discovery and relative links; the
 engine chooses what to read. Per-run native state stays under `control/`.
 
-One foreground turn and one owner-scheduled turn can run at the same time.
-Foreground inputs queue behind foreground work; scheduled turns queue behind
-scheduled work. A long scheduled goal therefore does not block chat. Both streams
+One foreground turn and up to six owner-scheduled turns can run at the same time.
+Set `EZ_SCHEDULED_CONCURRENCY` to a positive integer to change the scheduled-job
+limit; it defaults to six. For Docker deployments, put this setting in the
+existing private relay environment file (`EZ_RELAY_ENV_FILE`); no Compose
+layout migration is needed. Foreground inputs queue behind foreground work;
+scheduled turns queue only when their limit is occupied. A long scheduled goal therefore does not block chat. Both streams
 use the existing admission and executor path, with separate native sessions.
 They share the agent-owned Markdown workspace: the agent coordinates shared file
 updates, and plugins enforce canonical record-write guards. The host keeps plugin
-workspace invocations excluded until both native turns finish.
+workspace invocations excluded until all native turns finish.
 The agent decides when to send through the message CLI.
 A recurring schedule has at most one pending or active occurrence. Shared
-provider resources still need writer coordination. The former four background
-slots are no longer used for owner schedules.
+provider resources still need writer coordination. This is admission to the existing native executor, not a second queue or
+workflow controller.
 
 Production relay/host execution has no wall-clock timeout. The old
 `EZ_EXECUTOR_TIMEOUT_SECONDS` setting is ignored. Individual network/tool waits
@@ -170,6 +238,32 @@ Create a normal recurring schedule with `--every-seconds 900 --when unreviewed-f
 
 `failures [--all] [--limit N]` returns failedAt, reason, exit code, native session, captured error and runtime versions. Capture keeps at most 4 KiB of redacted stderr, including a failed native Codex turn's error message when supplied. A failure without error details remains explicitly unknown; historical failures are not backfilled. `run RUN_ID` reads an owned run. `review RUN_ID --failed-at ISO --status resolved|attention --diagnosis TEXT --recovery TEXT --outcome TEXT` records the investigation without rewriting execution history. A stale timestamp is rejected; a later failure needs a new review. Restricted reply, external and isolated-task callers cannot review failures. An attention review is handed off, not repeatedly relaunched; another new failure wakes the next review.
 
+For a shareable operational projection, use `evidence [RUN_ID] --offset 0 --limit 100`.
+This reads the live relay through its existing authenticated socket, under the
+bound operator or an active unrestricted Telegram owner run. Application/channel,
+external and isolated-task callers cannot use it. It exposes only current-owner
+Telegram foreground/scheduled runs, stable IDs, clocks/status/presets, failure
+metadata without prose, and retained run-associated outbox metadata. No native
+session, prompt, reasoning, tool arguments/results, message text or channel identity
+is returned. Failure text is represented by its SHA-256, not copied or diagnosed.
+
+The response carries exact `readStartedAt`/`observedAt`, `snapshotSha256`, and
+coverage total/offset/limit/returned/nextOffset. Follow `nextOffset` with the same
+`--expected SNAPSHOT_SHA256`; changed retained evidence fails closed and requires
+a fresh traversal. Each page recomputes the projection; no snapshot store or
+background capture is added. History resets on relay restart and is bounded to
+2000 terminal runs and 2000 terminal outbox items; full historical coverage cannot
+be inferred. Unassociated deliveries and excluded scopes remain unknown.
+
+Delivery records identify queued/sent/failed/unknown state and whether a retained
+Telegram receipt contains a valid clock and returned message IDs (only their count
+is exported). The submitted UTF-8 text/voice-text hash can be compared to an exact
+canonical source. It does not prove rendered or current recipient-side content;
+attachments are not exported. Empty receipt lists never prove that no delivery
+occurred. The relay does not retain native tool/delegation events, so that coverage
+is explicitly unavailable. This command does not mark failures reviewed, send
+messages, read private sessions, trigger work or certify owning results.
+
 The prompt controls diagnosis, authorized recovery and quiet notification behavior. Inspect prior effects and receipts before retrying anything. A failed review run itself remains visible as a new failure for the next occurrence.
 
 The Telegram Scheduled tasks menu lists enabled schedules that still have a pending