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

package/src/index.ts

@@ -11,6 +11,8 @@ import { dispatchChannel } from './channel-backend.js'
 import { randomUUID } from 'node:crypto'
 import { stat } from 'node:fs/promises'
 import { Scheduler } from './scheduler.js'
+import { Scripts } from './scripts.js'
+import { redactFailure } from './failure.js'
 import { ownedScheduledTasks, scheduledTaskDetailText, scheduledTasksText } from './scheduled-tasks.js'
 import { EventSources, eventRunId, batchReady, type SourceEvent } from './event-sources.js'
 import {removeTaskAttachments} from './task-attachments.js'
@@ -25,7 +27,8 @@ import { InboxStore, type IncomingItem } from './inbox.js'
 import { loadConfig, type Config } from './config.js'
 import { ControlStore, telegramOwner, ownerId, ownerEpoch } from './control-state.js'
 import { ApprovalStore } from './approval.js'
-import { startExecutorJob, terminateJob, opencodeDataHome } from './executor.js'
+import { startExecutorJob, terminateJob, opencodeDataHome, claudeConfigHome } from './executor.js'
+import { assertScheduledModel } from './model-policy.js'
 import { RunStore, type RunRecord } from './runs.js'
 import { splitTelegramText } from './reply.js'
 import { markdownToTelegramHtml, escapeHtml } from './format.js'
@@ -43,7 +46,7 @@ import { softwareStatus } from './software-status.js'
 export const createRelay = (config: Config, launch = startExecutorJob) => {
   const safeError = (error: unknown): string => {
     let message = error instanceof Error ? error.message : typeof error === 'string' ? error : 'Unknown error'
-    for (const secret of [config.channelBackendToken, config.telegramBotToken, config.geminiApiKey, config.openaiApiKey]) {
+    for (const secret of [config.channelBackendToken, config.telegramBotToken, config.geminiApiKey, config.openaiApiKey, config.openrouterApiKey]) {
       if (secret) message = message.replaceAll(secret, '[redacted]')
     }
     return message
@@ -59,7 +62,9 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
   const scheduler = new Scheduler(config.controlDir)
   const background = new Map<string, ChildProcess>()
   const completions = new Set<Promise<void>>()
-  const tasks = new Tasks(config.controlDir)
+  const speechOptions = { geminiApiKey: config.geminiApiKey, openrouterApiKey: config.openrouterApiKey, speechProvider: config.speechProvider, speechModel: config.speechModel }
+  const speechConfigured = config.speechProvider === 'openrouter' ? Boolean(config.openrouterApiKey) : Boolean(config.geminiApiKey)
+  const tasks = new Tasks(config.controlDir, speechConfigured ? (text) => synthesizeSpeech(text, { ...speechOptions, voice: config.speechVoiceEn, signal: AbortSignal.timeout(20000) }) : undefined)
   const processTaskRequests = taskRequests(tasks)
   let taskWork: Promise<void> | undefined
   const drainTaskRequests = (): Promise<void> => {
@@ -102,8 +107,8 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
   const applicationChannel = new ApplicationChannel({
     controlDir: config.controlDir, workspace: config.workspace, isolation: config.isolation, initial: aiMenu.initial,
     aiControls: aiMenu,
-    speech: config.geminiApiKey ? (text, language) => synthesizeSpeech(text, {
-      geminiApiKey: config.geminiApiKey,
+    speech: speechConfigured ? (text, language) => synthesizeSpeech(text, {
+      ...speechOptions,
       voice: language === 'es' ? config.speechVoiceEs : config.speechVoiceEn,
       format: 'wav',
     }) : undefined,
@@ -206,8 +211,8 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       }
       if (run.scheduled && !(await scheduler.get(run.scheduled.id)).enabled) return
       // A long scheduled turn must not occupy the owner's chat stream.
-      // Each stream remains serial, with separate native sessions.
-      if (run.scheduled ? background.size > 0 : activeChild !== null) return
+      // Foreground stays serial; scheduled jobs have independent native sessions.
+      if (run.scheduled ? background.size >= (config.scheduledConcurrency ?? 6) : activeChild !== null) return
       let texts = run.texts
       if (run.external) {
         // Availability failures leave durable queued work for a later check.
@@ -234,13 +239,23 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       try {
         const launchStarted = performance.now()
         const started = await runs.patch(run.id, { status: 'running', startedAt: new Date().toISOString() })
-        if (!started.execution && !run.taskId) throw new Error('Legacy queued work has no pinned AI. Resend the request after /new.')
+        // A registered script occurrence: no model, prompt or native session.
+        const script = run.script && run.scheduled
+          ? { registration: await new Scripts(config.controlDir).owned(run.script.id, owner), ref: run.script, scheduled: run.scheduled }
+          : undefined
+        if (run.script && !script) throw new Error('Script runs require a scheduled occurrence')
+        if (!started.execution && !run.taskId && !script) throw new Error('Legacy queued work has no pinned AI. Resend the request after /new.')
         const startsOwnSession = Boolean(run.external || run.taskId || run.scheduled)
         const session = startsOwnSession
           ? { sessionId: randomUUID(), hasStarted: false, nativeSessionId: undefined }
           : await control.executionSession(started.execution!)
-        const selected = run.taskId ? (started.execution?.preset.cli === 'codex' ? started.execution.preset : initialPreset('codex')) : started.execution!.preset
-        const { child, cleanup } = await launch(texts, {
+        const selected = script ? initialPreset('codex') : run.taskId ? (started.execution?.preset.cli === 'codex' ? started.execution.preset : initialPreset('codex')) : started.execution!.preset
+        if (run.scheduled && !script) assertScheduledModel(selected.model)
+        const { child, cleanup } = await launch(texts, script ? {
+          workspace: config.workspace, timeoutMs: 0, repairEnabled: config.repairEnabled, runId: started.id,
+          controlDir: config.controlDir, binDir,
+          script: { ...script.ref, scheduleId: script.scheduled.id, scheduleRevision: script.scheduled.revision, dueAt: script.scheduled.dueAt },
+        } : {
           workspace: config.workspace,
           timeoutMs: config.executorTimeoutMs,
           repairEnabled: config.repairEnabled,
@@ -263,9 +278,14 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
         const executionStarted = performance.now()
         // Attach before disk writes: a fast child can close while PID persistence
         // is pending, and Node drains its remaining pipes during process close.
-        let failureReason = 'executor-exit', errorTail = '', interrupted = false
+        let failureReason = 'executor-exit', errorTail = '', interrupted = false, outputTail = '', timedOut = false
+        // Script output is bounded diagnostics for run inspection, never chat.
+        if (script) child.stdout?.setEncoding('utf8').on('data', (chunk: string) => { outputTail = (outputTail + chunk).slice(-16384) })
+        const scriptTimer = script ? setTimeout(() => { timedOut = true; terminateJob(child) }, script.registration.timeoutSeconds * 1000) : undefined
+        child.once('close', () => clearTimeout(scriptTimer))
         child.stderr?.setEncoding('utf8').on('data', (chunk: string) => {
           errorTail = (errorTail + chunk).slice(-16384)
+          if (script) outputTail = (outputTail + chunk).slice(-16384)
           if (chunk.includes('Host CLI executor is offline')) failureReason = 'host-executor-offline'
           if (chunk.includes('Host executor client interrupted by')) {
             failureReason = 'host-executor-transport-interrupted'
@@ -286,7 +306,8 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
         console.info('run started', {
           run_id: started.id,
           pid: child.pid,
-          cli: selected.cli,
+          cli: script ? 'script' : selected.cli,
+          ...(script ? { script: script.ref.id, script_revision: script.ref.revision } : {}),
           session: session.sessionId,
           isResume: session.hasStarted,
         })
@@ -304,8 +325,12 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
               try {
                 await cleanup()
                 if (code === 0 && !run.external && !run.taskId && !run.scheduled) await control.markSessionStarted(session.sessionId)
-                const cancelled = ownerStopped.has(child) || Boolean(run.scheduled && await scheduler.cancelled(run.id))
-                await runs.patch(started.id, { status: cancelled ? 'cancelled' : code === 0 ? 'completed' : 'failed', endedAt: new Date().toISOString(), exitCode: code, ...(code !== 0 && !cancelled ? { failureReason, interrupted, failure: await failureEvidence(config.controlDir, safeError(errorTail || `Executor exited with ${code === null ? 'a signal' : `code ${code}`}`)) } : {}) })
+                const cancelled = !timedOut && (ownerStopped.has(child) || Boolean(run.scheduled && await scheduler.cancelled(run.id)))
+                if (timedOut) failureReason = 'script-timeout'
+                const failed = !cancelled && (code !== 0 || timedOut)
+                await runs.patch(started.id, { status: cancelled ? 'cancelled' : failed ? 'failed' : 'completed', endedAt: new Date().toISOString(), exitCode: code,
+                  ...(script ? { output: redactFailure(safeError(outputTail)), ...(timedOut ? { timedOut } : {}) } : {}),
+                  ...(failed ? { failureReason, interrupted, failure: await failureEvidence(config.controlDir, safeError(timedOut ? `Script exceeded its ${script!.registration.timeoutSeconds}s timeout and was terminated` : errorTail || `Executor exited with ${code === null ? 'a signal' : `code ${code}`}`)) } : {}) })
                 await releaseExternal(run)
               } catch (error) {
                 await runs.patch(started.id, { status: ownerStopped.has(child) ? 'cancelled' : 'failed', failureReason: 'session-finalization', failure: await failureEvidence(config.controlDir, safeError(error)), endedAt: new Date().toISOString() })
@@ -585,8 +610,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
           } else if (item.type === 'voice' && item.voiceText) {
             await bot!.api.sendChatAction(item.chatId, 'record_voice')
             const { buffer } = await synthesizeSpeech(item.voiceText, {
-              geminiApiKey: config.geminiApiKey,
-              openaiApiKey: config.openaiApiKey,
+              ...speechOptions,
               voice: config.speechVoiceEn,
             })
             await paceSend()
@@ -717,7 +741,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
     const delivery = await runs.deliveryStatus()
     const ai = await control.aiState(aiMenu.initial)
     const selected = ai.presets.find((p) => p.id === ai.selectedId)!
-    const discovered = await discoverDefaults(config.workspace, { codexHome, nativeCodexFallback: true })
+    const discovered = await discoverDefaults(config.workspace, { codexHome, claudeHome: claudeConfigHome(config.controlDir), nativeCodexFallback: true })
     const displayedSelected = statusPreset(selected, discovered)
     const scheduled = all.filter(run => run.scheduled && run.status === 'running').length
     const queued = all.filter(run => run.status === 'queued').length
@@ -741,6 +765,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       '',
       'Work',
       `Current: ${running ? (waitingForHost ? 'waiting for the workspace' : 'running') : 'idle'}`,
+      `Scheduled limit: ${config.scheduledConcurrency ?? 6}`,
       `Background: ${scheduled ? `${scheduled} scheduled task${scheduled === 1 ? '' : 's'} running` : 'none'}`,
       `Queue: ${queued || incoming.pending ? `${queued} run${queued === 1 ? '' : 's'}; ${incoming.pending} incoming message${incoming.pending === 1 ? '' : 's'}` : 'empty'}`,
       ...(attention.length ? ['', 'Needs attention', ...attention] : []),

package/src/install-tools.mjs

@@ -16,13 +16,14 @@ export const hostEnvironment=()=>Object.fromEntries(['HOME','PATH','LANG','LC_AL
 async function atomic(file,value) {
   const tmp=file+'.'+randomUUID()+'.tmp';await fs.writeFile(tmp,JSON.stringify(value)+'\n',{mode:0o600,flag:'wx'});await fs.rename(tmp,file);
 }
-export function run(command,args,{cwd,log,timeout=15000}={}) {
+export function run(command,args,{cwd,log,timeout=15000,stdoutOnly=false}={}) {
   return new Promise((resolve,reject)=>{
-    const child=spawn(command,args,{cwd,env:hostEnvironment(),stdio:['ignore',log??'pipe',log??'pipe']});let output='';
-    for(const stream of [child.stdout,child.stderr])stream?.on('data',b=>output=(output+b).slice(-200000));
+    const child=spawn(command,args,{cwd,env:hostEnvironment(),stdio:['ignore',log??'pipe',log??'pipe']});let output='',stdout='';
+    child.stdout?.on('data',b=>{output=(output+b).slice(-200000);if(stdoutOnly)stdout=(stdout+b).slice(-200000);});
+    child.stderr?.on('data',b=>output=(output+b).slice(-200000));
     const timer=setTimeout(()=>child.kill('SIGTERM'),timeout);
     child.once('error',e=>{clearTimeout(timer);reject(e);});
-    child.once('close',code=>{clearTimeout(timer);if(code!==0)reject(Error(`${command} failed (${code})${log===undefined?': '+output.trim():''}`));else resolve(output.trim());});
+    child.once('close',code=>{clearTimeout(timer);if(code!==0)reject(Error(`${command} failed (${code})${log===undefined?': '+output.trim():''}`));else resolve((stdoutOnly?stdout:output).trim());});
   });
 }
 export const defaultHome=()=>path.join(process.env.XDG_DATA_HOME||path.join(homedir(),'.local/share'),'ez');
@@ -114,6 +115,13 @@ export async function migrateLedger({ deployment } = {}) {
   return { ok: true, deployment: directory, changed: true, port, overlay };
 }
 
+export async function latestCodexVersion(invoke,manager={command:"npm",args:[]}) {
+  const output=await invoke(manager.command,[...manager.args,'view','@openai/codex@latest','version','--json','--registry','https://registry.npmjs.org/'],{stdoutOnly:true});
+  let version;
+  try {version=JSON.parse(output);}catch {throw Error('Codex version discovery returned invalid JSON on stdout');}
+  if(typeof version!=='string'||!/^\d+\.\d+\.\d+$/.test(version))throw Error('Invalid latest Codex version');
+  return version;
+}
 async function fingerprintOf(source,invoke) {
   const listing=JSON.parse(await invoke('npm',['pack','--dry-run','--ignore-scripts','--json'],{cwd:source}));
   const hash=createHash('sha256');
@@ -144,8 +152,9 @@ async function buildIdentity(source,label,invoke) {
 export async function build({home=defaultHome(),source=root,label},invoke=run) {
   source=await fs.realpath(source);
   const identity=await buildIdentity(source,label,invoke);
+  const codexVersion=await latestCodexVersion(invoke);
   const fingerprint=await fingerprintOf(source,invoke);
-  const artifact=createHash('sha256').update(JSON.stringify([fingerprint,identity.label??'',identity.sha??''])).digest('hex');
+  const artifact=createHash('sha256').update(JSON.stringify([fingerprint,identity.label??'',identity.sha??'',codexVersion])).digest('hex');
   const image='ezenciel-agents:install-'+artifact.slice(0,24);
   const dir=path.join(path.resolve(home),'builds',artifact);await fs.mkdir(dir,{recursive:true,mode:0o700});
   const lock=path.join(dir,'lock'),receipt=path.join(dir,'status.json'),log=path.join(dir,'build.log');
@@ -155,14 +164,14 @@ export async function build({home=defaultHome(),source=root,label},invoke=run) {
     await handle.writeFile(JSON.stringify({pid:process.pid,source,image,...identity}));
     const prior=await read(receipt).catch(absent);
     if(prior?.state==='completed')try{if(await invoke('docker',['image','inspect','--format','{{.Id}}',image])===prior.imageId)return {...prior,reused:true};}catch{/* Image was removed; rebuild under the same exclusive lock. */}
-    await atomic(receipt,{state:'building',pid:process.pid,source,image,log,...identity});
-    console.error(JSON.stringify({state:'building',image,log,...identity}));
-    const buildArgs=identity.label?['--build-arg',`BUILD_TAG=${identity.label}`,'--build-arg',`BUILD_SHA=${identity.sha}`]:[];
+    await atomic(receipt,{state:'building',pid:process.pid,source,image,log,codexVersion,...identity});
+    console.error(JSON.stringify({state:'building',image,log,codexVersion,...identity}));
+    const buildArgs=['--build-arg',`CODEX_CLI_VERSION=${codexVersion}`,...(identity.label?['--build-arg',`BUILD_TAG=${identity.label}`,'--build-arg',`BUILD_SHA=${identity.sha}`]:[])];
     const tags=[image,...(identity.label?[`ezenciel-agents:${identity.label}`]:[])];
     const output=await fs.open(log,'a',0o600);
     try{await invoke('docker',['build','--progress','plain','--target','runtime',...buildArgs,...tags.flatMap(t=>['-t',t]),source],{log:output.fd,timeout:3600000});}finally{await output.close();}
     if(await fingerprintOf(source,invoke)!==fingerprint)throw Error('Package changed during build; keep the source stable and retry');
-    const result={state:'completed',source,image,imageId:await invoke('docker',['image','inspect','--format','{{.Id}}',image]),log,...identity};await atomic(receipt,result);return result;
+    const result={state:'completed',source,image,imageId:await invoke('docker',['image','inspect','--format','{{.Id}}',image]),log,codexVersion,...identity};await atomic(receipt,result);return result;
   }catch(e){await atomic(receipt,{state:'failed',source,image,log,error:e.message,...identity});throw e;}
   finally{await handle.close();await fs.rm(lock);}
 }

package/src/menu.ts

@@ -6,6 +6,7 @@ import { InlineKeyboard, type Context } from 'grammy'
 import { ControlStore, type ControlGuard } from './control-state.js'
 import { chatPreset, installed, persistedPreset, presetLabel, presetProvider, readModels, validateSelection, type AiPreset, type ModelChoice } from './ai.js'
 import { discoverDefaults } from './client-defaults.js'
+import { claudeConfigHome } from './executor.js'
 
 export const mainCommands = [
   { command: 'new', description: 'New conversation' },
@@ -38,14 +39,15 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
   // directory, but the default catalog probed the process home instead. Bind it
   // to the same agent-bound home so /ai lists the models Codex can actually run.
   else if (codexHome && catalog === readModels) catalog = () => readModels(undefined, isInstalled, codexHome, undefined, opencodeDataHome, undefined, process.env.EZ_CONTROL_DIR)
-  const refresh = async () => control.syncClientPresets(initial, host ? [] : await discoverDefaults(workspace, { codexHome }))
+  const claudeHome = process.env.EZ_CONTROL_DIR ? claudeConfigHome(process.env.EZ_CONTROL_DIR) : undefined
+  const refresh = async () => control.syncClientPresets(initial, host ? [] : await discoverDefaults(workspace, { codexHome, claudeHome }))
   const validate = async (preset: AiPreset) => {
     assertEffort(preset.effort, preset.model, preset.cli)
     if (preset.id === initial.id) return
     if (preset.id.startsWith('detected_')) {
       if (host) await validateSelection(preset, await catalog(), async name => (await catalog()).some(model => model.cli === name))
       else {
-        const detected = await discoverDefaults(workspace, { codexHome })
+        const detected = await discoverDefaults(workspace, { codexHome, claudeHome })
         if (!detected.some((p) => p.id === preset.id)) throw new Error('Client settings changed. Refresh available AIs and select the updated choice.')
       }
     } else await validateSelection(preset, await catalog(), host ? async name => (await catalog()).some(model => model.cli === name) : isInstalled)

package/src/model-policy.ts

@@ -3,6 +3,10 @@ export const allowedEffort = (effort?: string, _model?: string, _cli?: string) =
 export function assertEffort(effort?: string, model?: string, cli?: string) {
   if (!allowedEffort(effort,model,cli)) throw new Error('Invalid reasoning effort')
 }
+export function assertScheduledModel(model: unknown): asserts model is string {
+  if (typeof model !== 'string' || !/^[a-zA-Z0-9_./:-]{1,160}$/.test(model))
+    throw new Error('Scheduled tasks require a saved explicit model; configure the task with --model')
+}
 export function executionDefaults<T extends { model?: string; effort?: string }>(cli: string, options: T): T {
   assertEffort(options.effort,options.model,cli)
   return options

package/src/plugin-broker.mjs

@@ -1,4 +1,6 @@
+import { combinePreflight } from './schedule-preflight.js';
 import * as fs from 'node:fs/promises';
+import {callDeliverySocket} from './delivery-socket-client.mjs';
 import path from 'node:path';
 import { createServer } from 'node:net';
 import { randomBytes, randomUUID, createHash } from 'node:crypto';
@@ -223,23 +225,37 @@ const managerCommand = async (binding, args, signal, runId) => new Promise((reso
   });
 });
 
-const invokePlugin = async (binding, request, signal) => {
+const authorizeTaskLaunch=async(binding,request)=>{
+  const input=JSON.parse(request.stdin)
+  if(Object.keys(input).some(k=>!['taskId','taskToken','expiresAt'].includes(k)) || typeof input.taskToken!=='string' || !/^[a-f0-9]{64}$/.test(input.taskToken))throw Error('Invalid task launch input')
+  const ticketHash=createHash('sha256').update(input.taskToken).digest('hex')
+  const grant=await callDeliverySocket(deliverySocketPath(binding.controlDir),{op:'taskApplication',payload:{runId:request.runId,ticketHash}})
+  if(input.taskId!==grant.taskId || input.expiresAt!==grant.expiresAt)throw Error('Task launch authority mismatch')
+  return grant.launch
+}
+const invokePlugin = async (binding, request, signal, scheduledPreflight = false) => {
   const startedAt = new Date().toISOString();
   let plugin = request.alias;
   let revision = request.revision;
   let result;
   let failure;
   try {
-    await authorize(binding, request.runId);
+    if (!scheduledPreflight) {
+      if(request.operation==='task-launch') {
+        const launch=await authorizeTaskLaunch(binding,request)
+        if(launch.command!==request.alias || JSON.stringify(launch.args)!==JSON.stringify(request.args))throw Error('Task launch command changed')
+      }else await authorize(binding, request.runId);
+    }
     const current = await registry(binding.home);
     const selected = recordForAlias(current, request.alias);
+    if (scheduledPreflight && (!selected.command.exposure || selected.command.exposure.changesRecords !== false || selected.command.exposure.sendsExternally !== false)) throw Error('Scheduled preflight requires an explicitly read-only plugin command');
     plugin = selected.plugin;
     revision = selected.record.revision;
     if (selected.record.revision !== request.revision) throw Error('Plugin changed; discover again');
     const command = await prepareCommand(binding.home, request.alias, request.args, {
       revision: request.revision,
       invocation: true,
-      environment: { EZ_CONTROL_DIR: binding.controlDir, EZ_RUN_ID: request.runId, EZ_DELIVERY_SOCKET: process.env.EZ_DELIVERY_SOCKET ?? deliverySocketPath(binding.controlDir) },
+      environment: { EZ_CONTROL_DIR: binding.controlDir, ...(scheduledPreflight ? {} : {EZ_RUN_ID: request.runId}), EZ_DELIVERY_SOCKET: process.env.EZ_DELIVERY_SOCKET ?? deliverySocketPath(binding.controlDir) },
     });
     try {
       result = await dockerRun(command.argv, {
@@ -282,8 +298,17 @@ const invokePlugin = async (binding, request, signal) => {
 
 export async function validateBrokerRequest(request, workspace) {
   if (!request || typeof request !== 'object' || request.version !== 1 || !REQUEST_ID.test(request.id)) throw Error('Invalid plugin broker request');
-  if (!['resolve', 'invoke', 'manager'].includes(request.operation)) throw Error('Unknown plugin broker operation');
+  if(request.operation === 'preflight') {
+    validId(request.scheduleId,RUN_ID,'schedule ID'); validId(request.revision,/^[a-f0-9-]{36}$/,'schedule revision');
+    if(Object.keys(request).some(k=>!['version','id','operation','scheduleId','revision'].includes(k))) throw Error('Unexpected schedule preflight field');
+    return request;
+  }
+  if (!['resolve', 'invoke', 'manager','task-launch'].includes(request.operation)) throw Error('Unknown plugin broker operation');
   validId(request.runId, RUN_ID, 'plugin run ID');
+  if(request.operation==='task-launch') {
+    if(Object.keys(request).some(k=>!['version','id','operation','runId','stdin'].includes(k)))throw Error('Unexpected task launch field')
+    boundedString(request.stdin,1024,'task launch stdin');return request
+  }
   if (request.operation === 'manager') {
     await validateManagerArgs(request.args, workspace);
     if (Object.keys(request).some(key => !['version', 'id', 'operation', 'runId', 'args'].includes(key))) throw Error('Unexpected broker management field');
@@ -328,6 +353,18 @@ export async function servePluginBroker(binding, signal = new AbortController().
       (async () => {
         try {
           await validateBrokerRequest(request, binding.workspace);
+          if (request.operation === 'preflight') {
+            const condition=await (await import('./delivery-socket-client.mjs')).callDeliverySocket(deliverySocketPath(binding.controlDir),{op:'schedulePreflight',payload:{scheduleId:request.scheduleId,revision:request.revision}});
+            const values=[];
+            for(const check of condition.checks) {
+              const selected=recordForAlias(await registry(binding.home),check.alias);
+              const result=await invokePlugin(binding,{alias:check.alias,args:check.args,revision:selected.record.revision,runId:`preflight_${request.scheduleId}`,id:randomUUID()},abort.signal,true);
+              if(!result.ok || result.code!==0) throw Error('Scheduled plugin preflight unavailable');
+              values.push(JSON.parse(result.stdout));
+            }
+            response(socket,{version:1,id:request.id,ok:true,result:combinePreflight(values)});
+            return;
+          }
           if (request.operation === 'resolve') {
             await authorize(binding, request.runId);
             const selected = recordForAlias(await registry(binding.home), request.alias);
@@ -338,6 +375,12 @@ export async function servePluginBroker(binding, signal = new AbortController().
             response(socket, { version: 1, id: request.id, ok: true, plugin: selected.plugin, alias: request.alias, revision: selected.record.revision, capability });
             return;
           }
+          if(request.operation==='task-launch') {
+            const launch=await authorizeTaskLaunch(binding,request)
+            const selected=recordForAlias(await registry(binding.home),launch.command)
+            const result=await invokePlugin(binding,{...request,alias:launch.command,args:launch.args,revision:selected.record.revision},abort.signal)
+            response(socket,{version:1,id:request.id,...result});return
+          }
           if (request.operation === 'manager') {
             await authorize(binding, request.runId);
             const result = await managerCommand(binding, request.args, abort.signal, request.runId);

package/src/plugins/manager.mjs

@@ -94,11 +94,18 @@ async function invocationLease(home,container) {
   await stewardOwned(file);
   return async()=>{await fs.rm(file,{force:true});};
 }
-export async function locked(home, fn, {allowInvocations=false}={}) {
+export async function locked(home, fn, {allowInvocations=false, waitMs=0}={}) {
   const lock = path.join(home,'registry.lock');
   let handle;
-  try { handle=await fs.open(lock,'wx',0o600); }
-  catch(error) { if(error.code==='EEXIST') throw Error('Registry busy; inspect registry.lock before recovering an interrupted manager'); throw error; }
+  const deadline=Date.now()+waitMs;
+  while(!handle) {
+    try { handle=await fs.open(lock,'wx',0o600); }
+    catch(error) {
+      if(error.code!=='EEXIST')throw error;
+      if(Date.now()>=deadline)throw Error('Registry busy; inspect registry.lock before recovering an interrupted manager');
+      await new Promise(resolve=>setTimeout(resolve,25));
+    }
+  }
   try {
     await handle.writeFile(JSON.stringify({pid:process.pid}));
     if(!allowInvocations&&await activeInvocations(home))throw Error('Plugin commands are active; retry the registry or lifecycle change after they finish');
@@ -498,7 +505,7 @@ export async function prepareCommand(home,alias,args,{revision,exclude,publish,i
     const invocationRelease=invocation?await invocationLease(home,container):undefined;
     const release=(invocationRelease||contextFile)?(async()=>{try{if(contextFile)await fs.rm(contextFile,{force:true});}finally{await invocationRelease?.();}}):undefined;
     return {container,plugin:record.manifest.id,revision:record.revision,contextFile,argv:[...composeArgs(record),...(contextFile?['--file',contextFile]:[]),'run','--rm','--no-deps','-T','--name',container,...(publish?['--publish',publish]:[]),'--entrypoint',binding.argv[0],binding.service,...binding.argv.slice(1),...record.manifest.commands[alias].args,...args,...(binding.suffix||[])],release};
-  },{allowInvocations:true});
+  },{allowInvocations:true,waitMs:5000});
 }
 export async function init(home,workspace,catalogFile,hostConfig,standalone=false) {
   if(standalone && hostConfig) throw Error('Standalone setup cannot bind a relay host config');

package/src/run-evidence.ts

@@ -0,0 +1,78 @@
+import { createHash } from 'node:crypto'
+import { readOnlyOwner, requireOwnerExecution } from './execution-authority.js'
+import { ownsRun, assertId } from './identity.js'
+import { RunStore, retainedOutbox, type RunRecord, type StoredOutboxItem } from './runs.js'
+import type { Owner } from './control-state.js'
+
+const sha256 = (value: string) => createHash('sha256').update(value).digest('hex')
+const version = (value?: string) => value && /^[0-9A-Za-z.+-]{1,80}$/.test(value) ? value : undefined
+
+function delivery(item: StoredOutboxItem) {
+  const receipt = item.receipt as { messageIds?: unknown; deliveredAt?: unknown } | undefined
+  const valid = item.state === 'sent' && !item.deliveryUnknown &&
+    Array.isArray(receipt?.messageIds) && receipt.messageIds.length > 0 &&
+    receipt.messageIds.every(id => Number.isSafeInteger(id) && id > 0) &&
+    typeof receipt.deliveredAt === 'string' && Number.isFinite(Date.parse(receipt.deliveredAt))
+  const field = typeof item.text === 'string' ? 'text' : typeof item.voiceText === 'string' ? 'voiceText' : undefined
+  const content = field === 'text' ? item.text : field === 'voiceText' ? item.voiceText : undefined
+  return { id: item.id, createdAt: item.createdAt, type: item.type ?? 'message',
+    state: item.deliveryUnknown ? 'unknown' : item.state ?? 'queued', receiptVerified: Boolean(valid),
+    ...(valid ? { deliveredAt: receipt!.deliveredAt, messageCount: (receipt!.messageIds as number[]).length } : {}),
+    ...(content === undefined ? {} : { content: { field, sha256: sha256(content), bytes: Buffer.byteLength(content), representation: 'submitted UTF-8' } }),
+    recipientContentReadback: 'unavailable', attachmentContent: 'not exported' }
+}
+
+// Projection only: never read native sessions, tool arguments/results or model text.
+export function projectRunEvidence(runs: RunRecord[], outbox: StoredOutboxItem[], owner: Owner) {
+  return runs.filter(run => ownsRun(owner, run) && Date.parse(run.createdAt) >= Date.parse(owner.pairedAt) &&
+    !run.external && !run.taskId && !run.application && !run.delivery &&
+    (!run.scheduled || run.scheduled.pairedAt === owner.pairedAt))
+    .sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id))
+    .map(run => ({ id: run.id, status: run.status, createdAt: run.createdAt,
+      startedAt: run.startedAt, endedAt: run.endedAt, exitCode: run.exitCode, interrupted: run.interrupted,
+      scheduled: run.scheduled ? { id: run.scheduled.id, revision: run.scheduled.revision, dueAt: run.scheduled.dueAt } : undefined,
+      executionType: run.script ? 'script' : 'agent',
+      script: run.script ? { id: run.script.id, revision: run.script.revision, sha256: run.script.sha256, timedOut: Boolean(run.timedOut),
+        outputSha256: run.output ? sha256(run.output) : undefined } : undefined,
+      preset: run.execution ? { cli: run.execution.preset.cli, model: run.execution.preset.model, effort: run.execution.preset.effort } : undefined,
+      failure: run.failure ? { recorded: true, errorSha256: sha256(run.failure.error), relayVersion: version(run.failure.relayVersion), hostVersion: version(run.failure.hostVersion) } : undefined,
+      failureReasonRecorded: Boolean(run.failureReason), blockReasonRecorded: Boolean(run.blockReason),
+      failureReview: run.failureReview ? { failedAt: run.failureReview.failedAt, reviewedAt: run.failureReview.reviewedAt, status: run.failureReview.status } : undefined,
+      nativeSessionRecorded: Boolean(run.nativeSessionId),
+      toolDelegationMetadata: { state: 'unavailable', reason: 'The relay does not retain native tool or delegation events.' },
+      deliveries: outbox.filter(item => item.runId === run.id && item.chatId === owner.telegramChatId &&
+        Date.parse(item.createdAt) >= Date.parse(owner.telegramLinkedAt ?? owner.pairedAt))
+        .sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id)).map(delivery),
+    }))
+}
+
+export type EvidenceOptions = { callerRunId?: string; runId?: string; offset?: number; limit?: number; expected?: string }
+
+export async function runEvidence(controlDir: string, options: EvidenceOptions = {}) {
+  const readStartedAt = new Date().toISOString()
+  const offset = options.offset ?? 0, limit = options.limit ?? 100
+  if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+    throw new Error('Offset must be nonnegative; limit must be 1..100')
+  if (offset > 0 && !options.expected) throw new Error('Continuation requires --expected snapshot SHA-256')
+  if (options.expected !== undefined && !/^[a-f0-9]{64}$/.test(options.expected)) throw new Error('Invalid expected snapshot SHA-256')
+  if (options.callerRunId !== undefined) {
+    const caller = await requireOwnerExecution(controlDir, options.callerRunId)
+    if (caller.application || caller.delivery || caller.replyOnly) throw new Error('Evidence requires Telegram owner execution or the bound operator')
+  }
+  const owner = await readOnlyOwner(controlDir)
+  if (!owner) throw new Error('No authorized owner')
+  const records = projectRunEvidence(await new RunStore(controlDir).list(), retainedOutbox(controlDir), owner)
+    .filter(run => options.runId === undefined || run.id === assertId(options.runId))
+  if (options.runId !== undefined && !records.length) throw new Error('Unknown owner run')
+  const snapshotSha256 = sha256(JSON.stringify(records))
+  if (options.expected !== undefined && options.expected !== snapshotSha256) throw new Error('Evidence changed; restart at offset zero')
+  if (offset > records.length) throw new Error('Offset exceeds retained coverage')
+  const page = records.slice(offset, offset + limit)
+  return { schemaVersion: 1, readStartedAt, observedAt: new Date().toISOString(), snapshotSha256,
+    coverage: { scope: 'current-owner Telegram foreground and scheduled runs', total: records.length, offset, limit, returned: page.length,
+      nextOffset: offset + page.length < records.length ? offset + page.length : null,
+      history: 'relay memory; resets on restart; at most 2000 terminal runs and 2000 terminal outbox items retained',
+      completeness: 'retained records only; older history and unassociated deliveries unknown',
+      excluded: ['external tasks', 'isolated tasks', 'application/channel runs', 'native sessions', 'tool/delegation events', 'failure/review prose', 'message content', 'recipient-side content readback'] },
+    runs: page }
+}

package/src/runs.ts

@@ -7,6 +7,7 @@ import { validScheduledOrigin, type ScheduledOrigin } from './scheduler.js'
 import type { IncomingItem } from './inbox.js'
 import { assertId } from './identity.js'
 import { isExecutionChoice, type ExecutionChoice } from './ai.js'
+import type { ScriptRunRef } from './scripts.js'
 import {authorizeDeliveryContext,currentDeliveryOwner,type DeliveryContext} from './delivery-context.mjs'
 
 export type RunStatus = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled'
@@ -44,6 +45,11 @@ export type RunRecord = {
   application?: ApplicationOrigin
   telegramApplication?: ApplicationOrigin
   delivery?: { bindingId: string; scope: string }
+  // Registered script occurrence (no execution preset or native session).
+  script?: ScriptRunRef
+  // Bounded, redacted script stdout/stderr tail; diagnostic, never delivered.
+  output?: string
+  timedOut?: boolean
 }
 
 export type OutboxItemType = 'message' | 'reaction' | 'document' | 'voice' | 'approval'
@@ -71,6 +77,9 @@ export type StoredOutboxItem = OutboxItem & { state?: 'queued' | 'sending' | 'se
 export const sentOutbox = (controlDir: string): StoredOutboxItem[] =>
   [...outboxFor(controlDir).values()].filter(item => item.state === 'sent')
 
+// Explicit operational evidence reads; the projection verifies owner/run scope.
+export const retainedOutbox = (controlDir: string): StoredOutboxItem[] => [...outboxFor(controlDir).values()]
+
 // Stateless pipe: the relay owns the ledger in process memory. Cross-process
 // producers (engine children, plugin children, host executor) reach it through
 // the delivery socket (see delivery-socket.ts), never through control/ files.
@@ -141,7 +150,8 @@ export class RunStore {
     taskId?: string
     application?: ApplicationOrigin
     delivery?: { bindingId: string; scope: string }
-  }): Promise<RunRecord> {
+    script?: ScriptRunRef
+  }, exclusiveSchedule = false): Promise<RunRecord> {
     const store = runsFor(this.controlDir)
     if (input.id) {
       assertId(input.id)
@@ -152,6 +162,9 @@ export class RunStore {
         return existing
       }
     }
+    if (exclusiveSchedule && input.scheduled && [...store.values()].some(run =>
+      run.scheduled?.id === input.scheduled!.id && ['queued','running'].includes(run.status)))
+      throw new Error('Schedule already has a queued or running occurrence')
     const run: RunRecord = {
       version: input.taskId ? 2 : 1,
       taskId: input.taskId,
@@ -169,6 +182,7 @@ export class RunStore {
       application: input.application,
       delivery: input.delivery,
       scheduled: input.scheduled,
+      ...(input.script ? { script: input.script } : {}),
       status: 'queued',
       createdAt: new Date().toISOString(),
     }
@@ -184,7 +198,7 @@ export class RunStore {
 
   async patch(
     id: string,
-    change: Partial<Pick<RunRecord, 'status' | 'startedAt' | 'endedAt' | 'pid' | 'nativeSessionId' | 'interrupted' | 'blockReason' | 'backendSubmitted' | 'replyOnly' | 'exitCode' | 'failureReason' | 'failure' | 'failureReview' | 'externalReleased'>>,
+    change: Partial<Pick<RunRecord, 'status' | 'startedAt' | 'endedAt' | 'pid' | 'nativeSessionId' | 'interrupted' | 'blockReason' | 'backendSubmitted' | 'replyOnly' | 'exitCode' | 'failureReason' | 'failure' | 'failureReview' | 'externalReleased' | 'output' | 'timedOut'>>,
   ): Promise<RunRecord> {
     const store = runsFor(this.controlDir)
     const run = store.get(id)