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

package/docs/selective-monitoring.md

@@ -178,3 +178,16 @@ After revocation/expiry no subsequent reply may dispatch. Keep these checks
 agent-owned: the owner supplies only necessary confirmation, QR scan if needed,
 and the test contact/message. Do not bypass a missing grant by polling the inbox
 in an unrestricted scheduled owner session or sending through the raw CLI.
+
+Task `send` accepts `voice: true` for spoken replies up to 1,000 characters on sources advertising `taskVoice`. It uses the relay’s configured speech renderer, rechecks authorization after generation, and preserves the same uncertain-send key contract. Synthesis failure happens before the provider is contacted: it returns an error, sends no text and stores no operation, so the same key may be retried. Voice and file attachments cannot be combined.
+
+### Incoming files and images
+
+The restricted MCP `read_attachment` tool accepts only an `incomingId` from the
+current run's correspondence. The channel supplies private bounded bytes through
+`task-document`, bound to its account and exact conversation. Core reuses
+`stageChatAttachment` validation (10 MiB) and returns UTF-8 TXT/Markdown or
+PDF text via Poppler, at most 256000 bytes. JPEG/PNG/WebP images return their
+original bounded pixels as MCP image content to the native engine, never an
+extra inference call or a base64 text prompt. It never accepts an owner file path.
+MP4 clips up to 10 MiB and 120 seconds return at most eight sampled JPEG frames, 640 pixels wide and at most 1 MiB combined, through the same native image content. Speech transcripts supplied by the source remain in incoming context. The audited native CLI accepts text and images, not raw video/audio; sampled frames do not capture every motion. Scanned PDFs with no text layer need OCR and return a clear limitation.

package/docs/upgrades.md

@@ -93,6 +93,12 @@ same candidate again and apply the new job; do not edit the old receipt. Only
 Finish the requesting turn after queuing either operation. Verify the main relay
 before requesting a separate plugin upgrade.
 
+Codex version discovery parses machine-readable stdout separately from package
+manager notices on stderr. Invalid stdout fails with a named discovery error;
+it is never repaired by stripping arbitrary lines. A historical generic JSON
+parse error alone does not establish which command or output stream caused it.
+Reconcile the job's completed stages and installed state before retrying.
+
 ## Agent interface
 
 Telegram `/status` shows the relay's loaded version, fresh host version and
@@ -285,3 +291,32 @@ the host or create a repair task. An automatically failed or rolled-back version
 is not retried until a newer version appears or the owner explicitly retries.
 Inspect `ez updates check` and `ez updates status` for target diagnostics.
 Actual update transactions retain their existing admission, drain and rollback rules.
+
+### Isolated broker readiness
+
+Isolated activation and rollback explicitly recreate only `plugin-broker` with
+`--no-deps --force-recreate --no-build --pull never --wait`. Plugin-only refresh
+pins the installed broker image ID; main activation uses the newly built image
+and rollback uses the recorded old image. This refreshes the narrow read-only
+host-configuration file mount after atomic replacement. The relay and native
+sessions are preserved during plugin-only refresh. Host-capable updates do not
+start a broker. Existing update admission and drain remain authoritative.
+
+Socket health is liveness only. Before reporting completion, the updater runs
+`docker/broker-readiness.mjs` inside the actual broker, with expected SHA-256
+fingerprints of the host binding, registry and registry configuration. This
+bounded diagnostic checks socket existence, agent/registry ownership, packaged
+source identity, declared command routes, folder grants and reviewed network
+pins. It reads state without rewriting Compose files, executing a plugin,
+creating authorization or supplying `EZ_RUN_ID`. Fingerprints are checked again
+after validation and on the host; a changed binding fails verification.
+`brokerReadiness` and `rollbackBrokerReadiness` in update status are structural
+readbacks at that transaction, not continuous health or native invocation proof.
+A failed refresh or probe enters the existing rollback/recovery path.
+
+A genuine authorized native invocation through the bound launcher, with its real
+receipt, remains separate acceptance evidence. Structural readiness and Docker
+health cannot prove provider delivery or a successful native command. Do not
+invent a run ID for that evidence. The synthetic regression is
+`EZ_RELAY_IMAGE=<exact runtime image ID> node docker/broker-update-smoke.mjs`;
+it uses disposable Linux state, no credentials or provider calls.

package/docs/work-preflight.md

@@ -0,0 +1,9 @@
+# Plugin-backed scheduled preflight
+
+Empty or unchanged provider work can skip a scheduled session. Eligible work uses the schedule's saved execution settings. Core owns admission; installed read-only plugin commands own provider eligibility. Preflight requires the bound plugin broker used by isolated deployments; unavailable broker or provider reads fail closed.
+
+A schedule's `preflight` is `{ "on": "eligible" | "changed", "checks": [{ "alias": "registered-read-only-command", "args": ["literal", "arguments"] }] }`.
+The plugin emits `{ "schemaVersion": 1, "eligible": boolean, "fingerprint": "sha256 hex", "observedAt": "ISO timestamp", "count": integer }`.
+Any check eligible admits the owning saved task; changed mode additionally requires a new combined fingerprint. No domain rules or DAG execution live in core. Empty/unchanged checks advance the ordinary schedule cursor without a run/session. Errors retain a sanitized preflight receipt and skip the occurrence; no empty-success fallback.
+
+Use `--preflight-file FILE` when creating/editing a native task. Editing preserves its condition unless explicitly replaced; `--clear-preflight` removes it. Preflight receipts remain on the native schedule cursor outside the agent workspace. Manual triggers run the same gate; an ineligible manual request reports unmet preflight and creates no run.

package/package.json

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

package/src/ai.ts

@@ -146,7 +146,27 @@ export const readCodexCatalog = async (codexHome: string, run?: (args: string[],
   try { return JSON.parse(await readFile(join(codexHome, 'models_cache.json'), 'utf8')) } catch { return {} }
 }
 
-export const readModels = async (home = homedir(), available = installed, codexHome = join(home, '.codex'), opencodeRunner?: (args: string[]) => Promise<string>, opencodeDataHome?: string, opencodeAllowlist?: string[], curationDir?: string, codexRunner?: (args: string[], env: NodeJS.ProcessEnv) => Promise<string>): Promise<ModelChoice[]> => {
+// Claude has no catalog command; its installed help is the native metadata for
+// the selectable model aliases and effort levels. No session or inference runs.
+// Unparseable or unavailable help keeps the client default, never guessed names.
+export const claudeCatalogModels = async (run?: (args: string[]) => Promise<string>): Promise<ModelChoice[]> => {
+  const fallback = [{ cli: 'claude', name: 'claude · client default', efforts: [] as string[] }]
+  let help: string
+  try {
+    help = run ? await run(['--help']) : await (async () => {
+      const invocation = executorInvocation('claude', ['--help'])
+      return (await promisify(execFile)(invocation.command, invocation.args, { env: executorEnvironment(), timeout: 8000, maxBuffer: 1024 * 1024 })).stdout
+    })()
+  } catch { return fallback }
+  const option = (flag: string) => help.split(/\r?\n(?=\s*(?:-\w, )?--)/).find((block) => block.trimStart().replace(/^-\w, /, '').startsWith(`${flag} `))?.replace(/\s+/g, ' ') ?? ''
+  const aliases = [...(option('--model').match(/\(e\.g\. ([^)]*)\)/)?.[1] ?? '').matchAll(/'([a-z][a-z0-9-]{0,31})'/g)].map((match) => match[1])
+  const levels = (option('--effort').match(/\(([a-z][a-z0-9, -]*)\)\s*$/)?.[1] ?? '').split(',').map((level) => level.trim())
+    .filter((level) => safe(level) && allowedEffort(level, undefined, 'claude'))
+  if (!aliases.length) return fallback
+  return [...fallback, ...[...new Set(aliases)].map((alias) => ({ cli: 'claude', model: alias, name: `claude · ${alias}`, efforts: levels }))]
+}
+
+export const readModels = async (home = homedir(), available = installed, codexHome = join(home, '.codex'), opencodeRunner?: (args: string[]) => Promise<string>, opencodeDataHome?: string, opencodeAllowlist?: string[], curationDir?: string, codexRunner?: (args: string[], env: NodeJS.ProcessEnv) => Promise<string>, claudeRunner?: (args: string[]) => Promise<string>): Promise<ModelChoice[]> => {
   const models: ModelChoice[] = []
   const record = (value: unknown): Record<string, unknown> =>
     value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
@@ -179,8 +199,7 @@ export const readModels = async (home = homedir(), available = installed, codexH
     }))
     models.push(...(desktop.length ? desktop : [{ cli: 'codex-gui', name: 'codex-gui · desktop', efforts: [] }]))
   }
-  // Other adapters expose the authenticated client's default, not a guessed catalog.
-  if (await available('claude')) models.push({ cli: 'claude', name: 'claude · client default', efforts: [] })
+  if (await available('claude')) models.push(...await claudeCatalogModels(claudeRunner))
   const allow = opencodeAllowlist ?? opencodeProviderAllowlist()
   if (await available('opencode')) models.push(...await opencodeCatalogModels(opencodeRunner, opencodeDataHome, allow))
   // Pi has separate provider configuration. OpenCode's catalog cannot

package/src/application-channel.ts

@@ -1,6 +1,6 @@
 import { createServer, type Server, type IncomingMessage, type ServerResponse } from 'node:http'
 import { createHash, randomUUID, timingSafeEqual } from 'node:crypto'
-import { mkdir, readFile, writeFile, rename, open, unlink } from 'node:fs/promises'
+import { mkdir, readFile, writeFile, rename, open, unlink, stat, chown } from 'node:fs/promises'
 import { join } from 'node:path'
 import { ControlStore, sessionTitle, telegramOwner, type ControlGuard, type Owner, sameOwner, validOwner, ownerId, ownerEpoch } from './control-state.js'
 import { RunStore, type RunRecord, type OutboxItem } from './runs.js'
@@ -16,7 +16,11 @@ import { SpeechCreditsDepletedError } from './audio.js'
 
 const hash = (value: string) => createHash('sha256').update(value).digest('hex')
 export const applicationScope = (bindingId: string, scope: string) => hash(JSON.stringify([bindingId, scope]))
-type Binding = { id: string; bindingId: string; tokenHash: string; owner: Owner; shareTelegram?: boolean }
+export type TaskLaunch = { command: string; args: string[]; tasks: "all" | string[] }
+export const validTaskLaunch = (v: unknown): v is TaskLaunch => {
+  const x=v as TaskLaunch; return !!x && Object.keys(x).every(k=>["command","args","tasks"].includes(k)) && /^[a-zA-Z0-9_-]{1,100}$/.test(x.command) && Array.isArray(x.args) && x.args.length>0 && x.args.length<=8 && (x.tasks==="all" || (Array.isArray(x.tasks) && x.tasks.length>0 && x.tasks.length<=128 && x.tasks.every(t=>/^task_[a-f0-9]{32}$/.test(t)))) && x.args.every(a=>typeof a==="string" && a.length<=200 && !/[\x00-\x1f\x7f]/.test(a))
+}
+export type Binding = { id: string; bindingId: string; tokenHash: string; owner: Owner; shareTelegram?: boolean; taskLaunch?: TaskLaunch }
 
 export function validateApplicationRegistration(id: string, token: string | null): void {
   if (!applicationId(id) || (token !== null && !/^[A-Za-z0-9_-]{43,200}$/.test(token))) throw new Error('Use a simple application ID and a random token of at least 256 bits encoded as base64url')
@@ -27,7 +31,7 @@ export class ApplicationBindings {
   async list(): Promise<Binding[]> {
     try {
       const bindings = JSON.parse(await readFile(join(this.controlDir, 'application-bindings.json'), 'utf8'))
-      if (!Array.isArray(bindings) || bindings.some(binding => !applicationId(binding?.id) || !/^[a-f0-9-]{36}$/.test(binding.bindingId) || !/^[a-f0-9]{64}$/.test(binding.tokenHash) || !validOwner(binding.owner) || (binding.shareTelegram !== undefined && typeof binding.shareTelegram !== 'boolean')) || ['tokenHash','id','bindingId'].some(key => new Set(bindings.map(b => b[key])).size !== bindings.length)) throw new Error('Invalid application binding state')
+      if (!Array.isArray(bindings) || bindings.some(binding => !applicationId(binding?.id) || !/^[a-f0-9-]{36}$/.test(binding.bindingId) || !/^[a-f0-9]{64}$/.test(binding.tokenHash) || !validOwner(binding.owner) || (binding.taskLaunch !== undefined && !validTaskLaunch(binding.taskLaunch)) || (binding.shareTelegram !== undefined && typeof binding.shareTelegram !== 'boolean')) || ['tokenHash','id','bindingId'].some(key => new Set(bindings.map(b => b[key])).size !== bindings.length)) throw new Error('Invalid application binding state')
       return bindings
     } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []; throw error }
   }
@@ -51,6 +55,23 @@ export class ApplicationBindings {
       return binding
     } finally { await lock.close(); await unlink(`${file}.lock`) }
   }
+  async taskLaunch(id: string, launch: TaskLaunch | null): Promise<void> {
+    if (launch !== null && !validTaskLaunch(launch)) throw Error('Invalid task launch command')
+    const file=join(this.controlDir,'application-bindings.json'), lock=await open(`${file}.lock`,'wx',0o600)
+    try {
+      const bindings=await this.list(), binding=bindings.find(b=>b.id===id)
+      const owner=(await new ControlStore(this.controlDir,900000).status()).owner
+      if(!binding || !sameOwner(binding.owner,owner))throw Error('Application authority revoked')
+      if(launch)binding.taskLaunch=launch; else delete binding.taskLaunch
+      const previous=await stat(file),tmp=`${file}.${randomUUID()}.tmp`
+      try {
+        await writeFile(tmp,JSON.stringify(bindings),{mode:0o600,flag:'wx'})
+        const created=await stat(tmp)
+        if(created.uid!==previous.uid || created.gid!==previous.gid)await chown(tmp,previous.uid,previous.gid)
+        await rename(tmp,file)
+      }finally{await unlink(tmp).catch(error=>{if((error as NodeJS.ErrnoException).code!=='ENOENT')throw error})}
+    }finally{await lock.close();await unlink(`${file}.lock`)}
+  }
   async authenticate(token: string): Promise<Binding> {
     if (!/^[A-Za-z0-9_-]{43,200}$/.test(token)) throw new Error('Unauthorized application')
     const fingerprint = Buffer.from(hash(token), 'hex')
@@ -65,6 +86,7 @@ export class ApplicationBindings {
     const owner = (await new ControlStore(this.controlDir, 900000).status()).owner
     const binding = (await this.list()).find(item => item.bindingId === origin.bindingId)
     if (!binding || !sameOwner(binding.owner, owner) || !ownsRun(owner, run)) throw new Error('Application authority revoked')
+    if(run.application?.taskAccess)await new Tasks(this.controlDir).applicationAccess(run.application.taskAccess,binding.bindingId)
   }
 }
 
@@ -224,6 +246,17 @@ export class ApplicationChannel {
         if ('followTelegram' in rest) throw new Error('Invalid application request: choose one conversation option')
         input = {...rest, followTelegram: followOwner}
       }
+      if(input && typeof input==='object' && 'taskToken' in input) {
+        const v=input as Record<string,unknown>
+        if(Object.keys(v).some(k=>!['requestId','scope','text','taskToken'].includes(k)) || !applicationId(v.requestId) || typeof v.text!=='string' || !v.text.trim() || v.text.length>16000 || typeof v.taskToken!=='string' || !/^[a-f0-9]{64}$/.test(v.taskToken))throw Error('Invalid application task request')
+        const ticketHash=hash(v.taskToken), access=await new Tasks(this.options.controlDir).applicationAccess(ticketHash,bindingId)
+        const scope='task:'+access.task.id
+        if(v.scope!==scope)throw Error('Invalid application task scope')
+        const id=`r_app_${hash(JSON.stringify([bindingId,v.requestId]))}`, existing=await this.runs.get(id)
+        if(existing){await this.bindings.authorize(existing);if(existing.application?.taskAccess!==ticketHash || existing.texts[0]!==v.text || existing.taskId!==access.task.id)throw Error('Application request ID conflicts with prior task');return existing}
+        const run=await this.runs.create({id,ownerId:ownerId(access.task.owner),ownerEpoch:ownerEpoch(access.task.owner),taskId:access.task.id,texts:[v.text],execution:access.execution,application:{bindingId,scope,requestId:v.requestId,taskAccess:ticketHash}})
+        this.options.wake();return run
+      }
       const value = input as { requestId?: unknown; scope?: unknown; text?: unknown; attachment?: { name?: unknown; data?: unknown }; context?: Record<string, unknown>; expectedNativeSessionId?: unknown; activateTelegram?: unknown; followTelegram?: unknown; ai?: { cli?: unknown; provider?: unknown; model?: unknown; effort?: unknown } }
       if (!value || !applicationId(value.requestId) || !applicationId(value.scope) || typeof value.text !== 'string' || (!value.text.trim() && value.attachment === undefined) || value.text.length > 16000 || Object.keys(value).some(key => !['requestId','scope','text','attachment','context','expectedNativeSessionId','activateTelegram','followTelegram','ai'].includes(key))) throw new Error('Invalid application request')
       if (value.expectedNativeSessionId !== undefined && (typeof value.expectedNativeSessionId !== 'string' || !/^[a-zA-Z0-9_-]{1,160}$/.test(value.expectedNativeSessionId))) throw new Error('Invalid application native session assertion')
@@ -299,6 +332,13 @@ export class ApplicationChannel {
       if (request.method === 'GET' && path === '/v1/registration') {
         send(200, {ownerId: ownerId(binding.owner), bindingId: binding.bindingId, channel: binding.id}); return
       }
+      if(request.method==='POST' && path==='/v1/registration') {
+        let raw='';for await(const chunk of request){raw+=chunk;if(Buffer.byteLength(raw)>1024)throw Error('Invalid application task request')}
+        const v=JSON.parse(raw)
+        if(Object.keys(v).length!==1 || typeof v.taskToken!=='string' || !/^[a-f0-9]{64}$/.test(v.taskToken))throw Error('Invalid application task request')
+        const access=await new Tasks(this.options.controlDir).applicationAccess(hash(v.taskToken),binding.bindingId)
+        send(200,{taskId:access.task.id,expiresAt:access.expiresAt,purpose:access.task.purpose});return
+      }
       if (path === '/v1/telegram' && request.method === 'GET') {
         if ([...url.searchParams.keys()].length) throw new Error('Invalid application Telegram request')
         if (!binding.shareTelegram) { send(403, { error: 'Application authority does not permit Telegram connection' }); return }

package/src/application-cli.ts

@@ -8,11 +8,12 @@ import { applicationId } from './application-origin.js'
 
 async function main() {
   const { values } = parseArgs({ options: {
+    'task-launch-command': {type:'string'}, 'task-launch-args':{type:'string'}, 'task-launch-tasks':{type:'string'}, 'disable-task-launch':{type:'boolean'},
     owner: {type:'string'}, id: {type:'string'}, 'token-file': {type:'string'}, revoke: {type:'boolean'}, list: {type:'boolean'}, help: {type:'boolean'},
     'owner-id': {type:'string'}, rotate: {type:'boolean'}, 'share-owner': {type:'boolean'}, 'share-active': {type:'boolean'},
     'import-scope': {type:'string'}, 'native-session': {type:'string'}, cli: {type:'string'}, 'share-telegram': {type:'boolean'},
   } })
-  if (values.help) { console.log('ezenciel-agents-application --id CHANNEL --token-file PRIVATE_FILE [--owner-id VERIFIED_OWNER_ID] [--share-owner] [--rotate] | --id CHANNEL --revoke | --list | --id CHANNEL --import-scope SCOPE --native-session ID --cli CLI'); return }
+  if (values.help) { console.log('ezenciel-agents-application --id CHANNEL --token-file PRIVATE_FILE [--owner-id VERIFIED_OWNER_ID] [--share-owner] [--rotate] | --id CHANNEL --task-launch-command COMMAND --task-launch-args JSON --task-launch-tasks JSON | --id CHANNEL --disable-task-launch | --id CHANNEL --revoke | --list | --id CHANNEL --import-scope SCOPE --native-session ID --cli CLI'); return }
   if (process.env.EZ_RUN_ID) throw new Error('Application authority is configured by the installing administrator outside agent turns')
   const config = loadControlConfig(), control = new ControlStore(config.controlDir, config.pairingTtlMs)
   if (values.owner && values['owner-id']) throw new Error('Choose one owner registration form')
@@ -25,6 +26,11 @@ async function main() {
   const bindings = new ApplicationBindings(config.controlDir)
   if (values.list) { console.log(JSON.stringify((await bindings.list()).map(({id,bindingId}) => ({id,bindingId})))); return }
   if (!values.id || !applicationId(values.id)) throw new Error('Application ID required')
+  if(values['task-launch-command'] || values['disable-task-launch']) {
+    if(values['token-file'] || values.revoke || values.rotate || values['import-scope'] || (values['task-launch-command'] && values['disable-task-launch']))throw Error('Task launch settings cannot be combined with registration')
+    await bindings.taskLaunch(values.id,values['disable-task-launch'] ? null : {command:values['task-launch-command']!,args:JSON.parse(values['task-launch-args'] ?? '[]'),tasks:JSON.parse(values['task-launch-tasks'] ?? 'null')})
+    console.log(JSON.stringify({ok:true,id:values.id,taskLaunch:!values['disable-task-launch']}));return
+  }
   if (values['import-scope']) {
     const binding = (await bindings.list()).find(item => item.id === values.id)
     if (!binding || !sameOwner(binding.owner, owner) || !applicationId(values['import-scope']) || !values['native-session'] || !/^[a-zA-Z0-9_-]{1,160}$/.test(values['native-session']) || !values.cli) throw new Error('Current application binding, scope, native session and CLI required')

package/src/application-origin.ts

@@ -2,6 +2,7 @@ export type ApplicationOrigin = {
   bindingId: string
   scope: string
   requestId: string
+  taskAccess?: string
   followTelegram?: boolean
   inputText?: string
   attachmentHash?: string
@@ -12,6 +13,7 @@ export const applicationId = (value: unknown): value is string =>
 export const validApplicationOrigin = (value: unknown): value is ApplicationOrigin => {
   const origin = value as ApplicationOrigin | undefined
   return !!origin && /^[a-f0-9-]{36}$/.test(origin.bindingId) && applicationId(origin.scope) && applicationId(origin.requestId) &&
+    (origin.taskAccess === undefined || /^[a-f0-9]{64}$/.test(origin.taskAccess)) &&
     (origin.followTelegram === undefined || typeof origin.followTelegram === 'boolean') &&
     (origin.inputText === undefined || (typeof origin.inputText === 'string' && origin.inputText.length <= 16000)) &&
     (origin.attachmentHash === undefined || /^[a-f0-9]{64}$/.test(origin.attachmentHash)) &&

package/src/audio.ts

@@ -6,6 +6,10 @@ export type AudioOptions = {
   geminiApiKey?: string
   openaiApiKey?: string
   voice?: string
+  speechProvider?: 'gemini' | 'openrouter'
+  speechModel?: string
+  openrouterApiKey?: string
+  signal?: AbortSignal
 }
 
 export class SpeechCreditsDepletedError extends Error {
@@ -32,27 +36,12 @@ export const pcmToWav = (pcm: Buffer, sampleRate = 24000, channels = 1): Buffer
   return Buffer.concat([header, pcm])
 }
 
-export const encodeOggOpus = (pcm: Buffer, sampleRate = 24000, channels = 1): Promise<Buffer> => {
+const convertSpeech = (audio: Buffer, input: 's16le' | 'mp3', format: 'wav' | 'ogg', sampleRate = 24000, channels = 1): Promise<Buffer> => {
   return new Promise((resolve, reject) => {
     const invocation = executorInvocation(
       'ffmpeg',
-      [
-        '-f',
-        's16le',
-        '-ar',
-        String(sampleRate),
-        '-ac',
-        String(channels),
-        '-i',
-        '-',
-        '-c:a',
-        'libopus',
-        '-b:a',
-        '32k',
-        '-f',
-        'ogg',
-        '-',
-      ],
+      [...(input === 's16le' ? ['-f', 's16le', '-ar', String(sampleRate), '-ac', String(channels)] : ['-f', 'mp3']),
+        '-i', '-', ...(format === 'ogg' ? ['-c:a', 'libopus', '-b:a', '32k', '-f', 'ogg'] : ['-ar', '24000', '-ac', '1', '-f', 's16le']), '-'],
     )
     const child = spawn(invocation.command, invocation.args,
       { env: executorEnvironment(), stdio: ['pipe', 'pipe', 'pipe'] })
@@ -60,7 +49,8 @@ export const encodeOggOpus = (pcm: Buffer, sampleRate = 24000, channels = 1): Pr
     const output: Buffer[] = []
     let error = ''
 
-    child.stdout.on('data', (chunk) => output.push(chunk))
+    let outputBytes = 0
+    child.stdout.on('data', (chunk) => { outputBytes += chunk.length; if(outputBytes > 16 * 1024 * 1024) { child.kill('SIGKILL'); reject(new Error('Encoded speech exceeds limit')) } else output.push(chunk) })
     child.stderr.on('data', (chunk) => {
       error = (error + chunk.toString()).slice(-2048)
     })
@@ -70,16 +60,18 @@ export const encodeOggOpus = (pcm: Buffer, sampleRate = 24000, channels = 1): Pr
 
     child.on('close', (code) => {
       if (code === 0 && output.length > 0) {
-        resolve(Buffer.concat(output))
+        resolve(format === 'wav' ? pcmToWav(Buffer.concat(output)) : Buffer.concat(output))
       } else {
         reject(new Error(`Voice encoding failed (${code}): ${error}`))
       }
     })
 
-    child.stdin.end(pcm)
+    child.stdin.end(audio)
   })
 }
 
+export const encodeOggOpus = (pcm: Buffer, sampleRate = 24000, channels = 1) => convertSpeech(pcm, 's16le', 'ogg', sampleRate, channels)
+
 export const transcribeAudio = async (
   audioBytes: Buffer,
   mimeType: string,
@@ -146,6 +138,29 @@ export const synthesizeSpeech = async (
   const trimmed = text.trim()
   if (!trimmed) throw new Error('Cannot synthesize speech for empty text')
 
+  if ((options.speechProvider ?? process.env.EZ_SPEECH_PROVIDER) === 'openrouter') {
+    const key = (options.openrouterApiKey ?? process.env.OPENROUTER_API_KEY)?.trim()
+    if (!key) throw new Error('OpenRouter speech is not configured')
+    const response = await fetch('https://openrouter.ai/api/v1/audio/speech', {
+      method: 'POST', signal: options.signal ?? AbortSignal.timeout(60000),
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
+      body: JSON.stringify({ model: options.speechModel ?? process.env.EZ_SPEECH_MODEL ?? 'fish-audio/s2.1-pro-free:free',
+        input: trimmed, response_format: 'mp3', ...(options.voice ? { voice: options.voice } : {}) })
+    })
+    if (!response.ok) { await response.body?.cancel(); throw new Error(`OpenRouter speech synthesis error ${response.status}`) }
+    const chunks: Buffer[] = []; let size = 0
+    const reader = response.body?.getReader()
+    if (!reader) throw new Error('OpenRouter returned no audio')
+    try {
+      for (;;) { const {done,value} = await reader.read(); if(done) break
+        size += value.length; if(size > 16 * 1024 * 1024) throw new Error('Speech audio exceeds limit')
+        chunks.push(Buffer.from(value)) }
+    } finally { await reader.cancel() }
+    if (!size) throw new Error('OpenRouter returned no audio')
+    const buffer = await convertSpeech(Buffer.concat(chunks), 'mp3', options.format ?? 'ogg')
+    return { buffer, mimeType: options.format === 'wav' ? 'audio/wav' : 'audio/ogg' }
+  }
+
   const geminiKey = (options.geminiApiKey ?? process.env.GEMINI_API_KEY)?.trim()
   if (geminiKey) {
     const url =
@@ -154,7 +169,7 @@ export const synthesizeSpeech = async (
     const response = await fetch(url, {
       method: 'POST',
       headers: { 'content-type': 'application/json', 'x-goog-api-key': geminiKey },
-      signal: AbortSignal.timeout(60_000),
+      signal: options.signal ?? AbortSignal.timeout(60_000),
       body: JSON.stringify({
         contents: [{ parts: [{ text: trimmed }] }],
         generationConfig: {

package/src/client-defaults.ts

@@ -78,7 +78,7 @@ export const grokSettings = (text: string): { model?: string; effort?: string }
 }
 
 export const discoverDefaults = async (cwd: string, options: {
-  home?: string; codexHome?: string; nativeCodexFallback?: boolean; available?: typeof installed; run?: typeof command; codex?: typeof codexDefaults
+  home?: string; codexHome?: string; claudeHome?: string; nativeCodexFallback?: boolean; available?: typeof installed; run?: typeof command; codex?: typeof codexDefaults
 } = {}): Promise<AiPreset[]> => {
   const home = options.home ?? homedir()
   const available = options.available ?? installed
@@ -99,7 +99,8 @@ export const discoverDefaults = async (cwd: string, options: {
         model = value(config.model); effort = value(config.effort)
       } else if (cli === 'claude') {
         // Match Claude's documented user -> project -> local settings precedence.
-        const settings = Object.assign({}, await json(join(home, '.claude/settings.json')),
+        // User settings come from the agent-bound CLAUDE_CONFIG_DIR when bound.
+        const settings = Object.assign({}, await json(join(options.claudeHome ?? join(home, '.claude'), 'settings.json')),
           await json(join(cwd, '.claude/settings.json')), await json(join(cwd, '.claude/settings.local.json')))
         model = value(settings.model); effort = value(settings.effortLevel)
       } else if (cli === 'opencode') {

package/src/config.ts

@@ -19,12 +19,16 @@ export type Config = ControlConfig & {
   isolation?: IsolationClass
   codexSandbox?: 'external'
   codexAutoCompactTokens?: number
+  scheduledConcurrency?: number
   executorCli: string
   channelBackendUrl?: string
   channelBackendToken?: string
   applicationPort?: number
   applicationHost?: string
   geminiApiKey?: string
+  speechProvider?: 'gemini' | 'openrouter'
+  speechModel?: string
+  openrouterApiKey?: string
   speechVoiceEn?: string
   speechVoiceEs?: string
   openaiApiKey?: string
@@ -69,6 +73,7 @@ export const loadConfig = (env: NodeJS.ProcessEnv = process.env): Config => {
   const codexSandbox = env.EZ_CODEX_SANDBOX?.trim()
   if (codexSandbox && codexSandbox !== 'external') throw new Error('EZ_CODEX_SANDBOX must be external or unset')
   if (codexSandbox && (env.EZ_CHANNEL_BACKEND_URL || transport !== 'local')) throw new Error('External Codex sandbox requires native local execution')
+  if (env.EZ_SPEECH_PROVIDER && !['gemini','openrouter'].includes(env.EZ_SPEECH_PROVIDER)) throw new Error('Invalid EZ_SPEECH_PROVIDER')
   return {
     ...loadControlConfig(env),
     telegramEnabled,
@@ -80,12 +85,16 @@ export const loadConfig = (env: NodeJS.ProcessEnv = process.env): Config => {
     isolation,
     codexSandbox: codexSandbox === 'external' ? 'external' : undefined,
     codexAutoCompactTokens: !env.EZ_CODEX_AUTO_COMPACT_TOKENS?.trim() ? undefined : positiveInteger(env.EZ_CODEX_AUTO_COMPACT_TOKENS, 'EZ_CODEX_AUTO_COMPACT_TOKENS'),
+    scheduledConcurrency: positiveInteger(env.EZ_SCHEDULED_CONCURRENCY, 'EZ_SCHEDULED_CONCURRENCY', 6),
     executorCli: env.EZ_EXECUTOR_CLI?.trim() || 'codex',
     applicationPort: env.EZ_APPLICATION_PORT ? positiveInteger(env.EZ_APPLICATION_PORT, 'EZ_APPLICATION_PORT') : undefined,
     applicationHost: env.EZ_APPLICATION_HOST?.trim() || '127.0.0.1',
     channelBackendUrl: env.EZ_CHANNEL_BACKEND_URL?.trim(),
     channelBackendToken: env.EZ_CHANNEL_BACKEND_TOKEN?.trim(),
     geminiApiKey: env.GEMINI_API_KEY?.trim(),
+    speechProvider: env.EZ_SPEECH_PROVIDER as Config['speechProvider'],
+    speechModel: env.EZ_SPEECH_MODEL?.trim(),
+    openrouterApiKey: env.OPENROUTER_API_KEY?.trim(),
     speechVoiceEn: env.EZ_SPEECH_VOICE_EN?.trim(),
     speechVoiceEs: env.EZ_SPEECH_VOICE_ES?.trim(),
     openaiApiKey: env.OPENAI_API_KEY?.trim(),

package/src/control-state.ts

@@ -755,7 +755,9 @@ export class ControlStore {
       const state = await this.readState()
       await requireControlGuard(state, guard)
       if (!state.ai) throw new Error('AI settings not initialized')
-      if (state.ai.presets.length >= 12 && !state.ai.presets.some((p) => p.id === preset.id))
+      // Auto-detected client defaults come and go with installed clients; only
+      // owner-saved choices count toward the cap.
+      if (state.ai.presets.filter((p) => !p.id.startsWith('detected_')).length >= 12 && !state.ai.presets.some((p) => p.id === preset.id))
         throw new Error('Keep it small: at most 12 saved AIs.')
       state.ai.presets = [...state.ai.presets.filter((p) => p.id !== preset.id), persistedPreset(preset)]
       await this.writeState(state)

package/src/delivery-socket-client.d.mts

@@ -2,3 +2,5 @@ export type DeliverySocketRequest = { op: string; payload?: unknown }
 export function deliverySocketPath(controlDir: string): string
 export function callDeliverySocket(socketPath: string, op: DeliverySocketRequest, timeoutMs?: number): Promise<unknown>
 export function deliverySocketAlive(socketPath: string, timeoutMs?: number): Promise<boolean>
+
+export function callLocalSocket(socketPath:string, envelope:Record<string,unknown>, timeoutMs?:number):Promise<unknown>

package/src/delivery-socket-client.mjs

@@ -67,6 +67,8 @@ const exchange = (connect, envelope, timeoutMs, target) => new Promise((resolve,
   socket.write(encode(envelope))
 })
 
+export const callLocalSocket = (socketPath, envelope, timeoutMs = 130000) => exchange(() => createConnection(socketPath), envelope, timeoutMs, socketPath)
+
 const readEndpoint = async controlDir => {
   try {
     const value = JSON.parse(await readFile(path.join(controlDir, endpointName), 'utf8'))

package/src/delivery-socket.ts

@@ -1,3 +1,5 @@
+import { sameOwner } from './control-state.js'
+import { ApplicationBindings } from './application-channel.js'
 import { createServer, type Server, type Socket } from 'node:net'
 import { randomBytes, timingSafeEqual } from 'node:crypto'
 import { rename, rm, writeFile } from 'node:fs/promises'
@@ -9,6 +11,8 @@ import { deliveredMessages } from './message-history.js'
 import { readOnlyOwner, requireOwnerExecution } from './execution-authority.js'
 import { telegramOwner } from './control-state.js'
 import { Scheduler } from './scheduler.js'
+import {Tasks} from './tasks.js'
+import { runEvidence, type EvidenceOptions } from './run-evidence.js'
 
 // Stateless pipe transport. The relay owns the runs/outbox ledger in process
 // memory; engine children, plugin children and the host executor reach it
@@ -28,16 +32,19 @@ export { deliverySocketPath }
 export type DeliverySocketOp =
   | { op: 'ping' }
   | { op: 'status' }
+  | { op: 'schedulePreflight'; payload?: Record<string, unknown> }
   | { op: 'triggerSchedule'; payload: { scheduleId: string; revision: string; key: string; callerRunId?: string } }
   | { op: 'enqueue'; payload: Record<string, unknown> }
   | { op: 'wait'; payload: { id: string; timeoutMs?: number } }
   | { op: 'get'; payload: { runId: string } }
   | { op: 'list'; payload?: Record<string, never> }
   | { op: 'patch'; payload: { runId: string; change: Record<string, unknown> } }
+  | { op: 'taskApplication'; payload: {runId:string;ticketHash:string} }
   | { op: 'authorize'; payload: { runId: string } }
   | { op: 'receipt'; payload: { context: unknown; id: string } }
   | { op: 'history'; payload: { runId: string; limit?: number; messageId?: number } }
   | { op: 'deliveryStatus'; payload?: Record<string, never> }
+  | { op: 'evidence'; payload: EvidenceOptions }
   | { op: 'approvalCheck'; payload: { actionId: string } }
   | { op: 'latestReply'; payload?: Record<string, never> }
 
@@ -210,12 +217,23 @@ export const createLedgerHandler = (controlDir: string, hooks: LedgerHooks): Del
           queued: all.filter((run) => run.status === 'queued').length,
         }
       }
+      case 'schedulePreflight': {
+        const {scheduleId,revision}=op.payload ?? {}
+        if(!nonEmptyString(scheduleId) || !nonEmptyString(revision)) throw Error('Schedule preflight identity required')
+        const scheduler=new Scheduler(controlDir),s=await scheduler.get(scheduleId),owner=await readOnlyOwner(controlDir)
+        if(!owner || !sameOwner(owner,s.owner) || !s.enabled || s.revision!==revision || !s.preflight) throw Error('Schedule preflight binding unavailable')
+        if(s.delivery) {
+          const binding=(await new ApplicationBindings(controlDir).list()).find(b=>b.bindingId===s.delivery!.bindingId)
+          if(!binding || !sameOwner(owner,binding.owner)) throw Error('Schedule preflight delivery revoked')
+        }
+        return s.preflight
+      }
       case 'triggerSchedule': {
         const {scheduleId,revision,key,callerRunId}=op.payload ?? {}
         if (!nonEmptyString(scheduleId) || !nonEmptyString(revision) || !nonEmptyString(key)) throw new Error('Task ID, revision and request key are required')
         if (callerRunId !== undefined) {
           const caller=await requireOwnerExecution(controlDir,callerRunId)
-          if (caller.replyOnly || (caller.scheduled && caller.scheduled.pairedAt !== (await readOnlyOwner(controlDir))?.pairedAt)) throw new Error('Scheduling requires an active owner-authorized run')
+          if (caller.replyOnly || caller.script || (caller.scheduled && caller.scheduled.pairedAt !== (await readOnlyOwner(controlDir))?.pairedAt)) throw new Error('Scheduling requires an active owner-authorized run')
         }
         const owner=await readOnlyOwner(controlDir)
         if (!owner) throw new Error('Pair an owner before scheduling')
@@ -302,6 +320,10 @@ export const createLedgerHandler = (controlDir: string, hooks: LedgerHooks): Del
         if (!payload.change || typeof payload.change !== 'object') throw new Error('Patch change is required')
         return runs.patch(payload.runId, payload.change as never)
       }
+      case 'taskApplication': {
+        const p=op.payload as {runId:string;ticketHash:string}
+        return new Tasks(controlDir).authorizeApplicationLaunch(p.runId,p.ticketHash)
+      }
       case 'authorize': {
         const runId = (op.payload as { runId?: unknown } | undefined)?.runId
         if (typeof runId !== 'string' || !runId) throw new Error('Run ID is required')
@@ -321,6 +343,7 @@ export const createLedgerHandler = (controlDir: string, hooks: LedgerHooks): Del
           ...(payload.messageId === undefined ? {} : { messageId: payload.messageId as number }),
         })
       }
+      case 'evidence': return runEvidence(controlDir, op.payload ?? {})
       case 'deliveryStatus': return runs.deliveryStatus()
       case 'approvalCheck': {
         const actionId = (op.payload as { actionId?: unknown } | undefined)?.actionId

package/src/event-sources.ts

@@ -27,11 +27,11 @@ async function atomic(path: string, data: unknown) {
   try { await fd.writeFile(JSON.stringify(data)); await fd.sync() } finally { await fd.close() }
   await rename(tmp, path)
 }
-export function sourceCall(socketPath: string, command: string, args = {}): Promise<any> {
+export function sourceCall(socketPath: string, command: string, args = {}, maxResponseBytes = 256000): Promise<any> {
   return new Promise((resolve, reject) => {
     const req = request({ socketPath, path: '/', method: 'POST', timeout: 3000 }, res => {
       let body = ''
-      res.on('data', chunk => { body += chunk; if (Buffer.byteLength(body) > 256000) req.destroy(new Error('Event-source response too large')) })
+      res.on('data', chunk => { body += chunk; if (Buffer.byteLength(body) > maxResponseBytes) req.destroy(new Error('Event-source response too large')) })
       res.on('error', () => reject(new Error('Event-source response interrupted')))
       res.on('end', () => {
         try { const result = JSON.parse(body); if (res.statusCode !== 200 || result.ok !== true) throw new Error(); resolve(result.data) }