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

package/src/schedule-preflight.ts

@@ -0,0 +1,23 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { callLocalSocket } from './delivery-socket-client.mjs'
+
+export type Preflight = {on: 'eligible' | 'changed'; checks: {alias: string; args: string[]}[]}
+export type PreflightReceipt = {eligible: boolean; fingerprint: string; observedAt: string; count: number}
+export function validPreflight(v: unknown): v is Preflight {
+ const p=v as Preflight
+ return Boolean(p && !Array.isArray(p) && Object.keys(p).every(k=>['on','checks'].includes(k)) && ['eligible','changed'].includes(p.on) &&
+ Array.isArray(p.checks) && p.checks.length>0 && p.checks.length<=8 && p.checks.every(c=>c && Object.keys(c).every(k=>['alias','args'].includes(k)) &&
+ /^[a-z][a-z0-9-]{0,39}$/.test(c.alias) && Array.isArray(c.args) && c.args.length<=100 && c.args.every(a=>typeof a==='string' && !/[\0\r\n]/.test(a) && Buffer.byteLength(a)<=8192)))
+}
+export function combinePreflight(results: unknown[]): PreflightReceipt {
+ const values=results as (PreflightReceipt & {schemaVersion:number})[]
+ if(!values.length || values.some(v=>!v || v.schemaVersion!==1 || typeof v.eligible!=='boolean' || !/^[a-f0-9]{64}$/.test(v.fingerprint) ||
+ !Number.isSafeInteger(v.count) || v.count<0 || typeof v.observedAt!=='string' || !Number.isFinite(Date.parse(v.observedAt)) || Date.parse(v.observedAt)>Date.now()+1000 || Date.now()-Date.parse(v.observedAt)>300000)) throw Error('Invalid or stale plugin preflight result')
+ return {eligible:values.some(v=>v.eligible),fingerprint:createHash('sha256').update(JSON.stringify(values.map(v=>v.fingerprint))).digest('hex'),
+ observedAt:new Date().toISOString(),count:values.reduce((n,v)=>n+v.count,0)}
+}
+export async function installedPreflight(scheduleId:string, revision:string): Promise<PreflightReceipt> {
+ const socket=process.env.EZ_PLUGIN_BROKER_SOCKET
+ if(!socket) throw Error('Scheduled preflight requires the bound plugin broker')
+ return await callLocalSocket(socket,{version:1,id:randomUUID(),operation:'preflight',scheduleId,revision},120000) as PreflightReceipt
+}

package/src/scheduled-tasks.ts

@@ -11,11 +11,16 @@ const ownsSchedule = (owner: Owner, schedule: Schedule) =>
 // Saved schedules created under an earlier model policy remain inspectable. The
 // executor will apply the same defaults (and enforce its current policy) when
 // it starts the run; an outdated saved selection must not hide every menu row.
-const displayedPreset = (schedule: Schedule) => {
-  try { return executionDefaults(schedule.execution.preset.cli, schedule.execution.preset) }
-  catch { return schedule.execution.preset }
+const displayedPreset = (execution: NonNullable<Schedule['execution']>) => {
+  try { return executionDefaults(execution.preset.cli, execution.preset) }
+  catch { return execution.preset }
 }
 
+// Script schedules have no AI preset; show what core actually invokes.
+const engineLabel = (schedule: ActiveSchedule) => schedule.script
+  ? `Script · ${schedule.script.id} · ${schedule.scriptRevision ? `rev ${schedule.scriptRevision.slice(0, 8)}` : 'not registered'}`
+  : presetLabel(displayedPreset(schedule.execution!))
+
 const weekdays = ['Sun','Mon','Tue','Wed','Thu','Fri','Sat']
 const months = ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec']
 const time = (value: number | string) => {
@@ -25,6 +30,7 @@ const time = (value: number | string) => {
 }
 
 const preview = (schedule: Schedule) => {
+  if (schedule.script) return schedule.script.args.length ? `Arguments: ${schedule.script.args.join(' ')}`.slice(0, 140) : 'No saved arguments'
   const sentence = schedule.text.trim().replace(/\s+/gu,' ').split(/(?<=[.!?])\s/u)[0]
   const chars = Array.from(sentence)
   return chars.length > 140 ? chars.slice(0,139).join('')+'…' : sentence
@@ -46,15 +52,13 @@ export const ownedScheduledTasks = (schedules: ActiveSchedule[], owner: Owner) =
 export const scheduledTasksText = (schedules: ActiveSchedule[], owner: Owner) => {
   const owned = ownedScheduledTasks(schedules, owner)
   if (!owned.length) return '📅 Scheduled tasks\n\nNo active scheduled tasks.'
-  return [`📅 Scheduled tasks · ${owned.length} active`, 'All times UTC. Use /tasks 1 for task details.', ...owned.map((schedule, index) => {
-    const preset = displayedPreset(schedule)
-    return `${index + 1} · ${schedule.name}\n  ${currentState(schedule)}\n  Next · ${schedule.nextAt === null ? '—' : time(schedule.nextAt)}\n  Last · ${lastRun(schedule)}\n  ${presetLabel(preset)}\n  ${preview(schedule)}`
-  })].join('\n\n')
+  return [`📅 Scheduled tasks · ${owned.length} active`, 'All times UTC. Use /tasks 1 for task details.', ...owned.map((schedule, index) =>
+    `${index + 1} · ${schedule.name}\n  ${currentState(schedule)}\n  Next · ${schedule.nextAt === null ? '—' : time(schedule.nextAt)}\n  Last · ${lastRun(schedule)}\n  ${engineLabel(schedule)}\n  ${preview(schedule)}`
+  )].join('\n\n')
 }
 
 export const scheduledTaskDetailText = (schedule: ActiveSchedule, number: number, total?: number) => {
-  const preset = displayedPreset(schedule)
-  const instructions = schedule.text.trim()
+  const instructions = schedule.script ? preview(schedule) : schedule.text.trim()
   const capped = instructions.length > 2000 ? instructions.slice(0, 2000) + '… (truncated; full text lives in the workspace)' : instructions
   return [
     `📅 ${number}${total === undefined ? '' : ` of ${total}`} · ${schedule.name}`,
@@ -66,10 +70,10 @@ export const scheduledTaskDetailText = (schedule: ActiveSchedule, number: number
     'Last run',
     lastRun(schedule),
     '',
-    'Engine',
-    presetLabel(preset),
+    schedule.script ? 'Execution' : 'Engine',
+    engineLabel(schedule),
     '',
-    'Instructions',
+    schedule.script ? 'Script arguments' : 'Instructions',
     capped,
   ].join('\n')
 }

package/src/scheduler.ts

@@ -1,3 +1,4 @@
+import { validPreflight, installedPreflight, type Preflight, type PreflightReceipt } from './schedule-preflight.js'
 import { assertEffort, assertScheduledModel } from './model-policy.js'
 import { needsFailureReview } from './failure.js'
 import { mkdir, readFile, readdir, writeFile, rename, link, rm } from 'node:fs/promises'
@@ -7,15 +8,20 @@ import { type Owner, sameOwner, validOwner, ownerId, ownerEpoch } from './contro
 import { validApplicationOrigin } from './application-origin.js'
 import { ApplicationBindings } from './application-channel.js'
 import { assertId, ownsRun } from './identity.js'
-import { type ExecutionChoice, isExecutionChoice, persistedPreset } from './ai.js'
+import { type AiPreset, type ExecutionChoice, isExecutionChoice, persistedPreset } from './ai.js'
 import { type Trigger, validateTrigger, nextOccurrence } from './schedule-time.js'
 import { RunStore, type RunRecord } from './runs.js'
+import { Scripts, assertScriptArgs, assertScriptId, type ScriptRunRef } from './scripts.js'
 
 export type Schedule = {
   originRunId?: string
   when?: 'unreviewed-failures'
+  preflight?: Preflight
   version: 1; id: string; revision: string; name: string; text: string; trigger: Trigger; enabled: boolean
-  owner: Owner; execution: ExecutionChoice
+  owner: Owner
+  // Exactly one execution type: an agent turn (execution) or a registered script.
+  execution?: ExecutionChoice
+  script?: { id: string; args: string[] }
   delivery?: { bindingId: string; scope: string }
 }
 export type ScheduledRunSummary = {
@@ -23,13 +29,24 @@ export type ScheduledRunSummary = {
   at: string
   currentRevision: boolean
 }
-export type ActiveSchedule = Schedule & { nextAt: number | null; runState?: 'queued' | 'running'; lastRun?: ScheduledRunSummary }
+export type ActiveSchedule = Schedule & { nextAt: number | null; runState?: 'queued' | 'running'; lastRun?: ScheduledRunSummary; scriptRevision?: string }
 export type ScheduledOrigin = { id: string; revision: string; dueAt: string; pairedAt: string; originRunId?: string }
 export const validScheduledOrigin = (v: unknown): v is ScheduledOrigin => {
   const s = v as ScheduledOrigin
   return Boolean(s && /^[a-zA-Z0-9_-]+$/.test(s.id) && /^[a-zA-Z0-9_-]+$/.test(s.revision) &&
     Number.isFinite(Date.parse(s.dueAt)) && typeof s.pairedAt === 'string' && (s.originRunId === undefined || /^[a-zA-Z0-9_-]+$/.test(s.originRunId)))
 }
+export const executionType = (s: Pick<Schedule,'script'>): 'agent' | 'script' => s.script ? 'script' : 'agent'
+const validExecution = (s: Pick<Schedule,'execution'|'script'|'text'>) => s.script
+  ? s.execution === undefined && (() => { try { assertScriptId(s.script!.id); assertScriptArgs(s.script!.args); return true } catch { return false } })()
+  : isExecutionChoice(s.execution) && typeof s.text === 'string' && Boolean(s.text.trim())
+// The run carries the registration revision/hash current when it was queued.
+const scriptRef = async (controlDir: string, s: Schedule, owner: Owner): Promise<ScriptRunRef> => {
+  const ref: ScriptRunRef = { id: s.script!.id, args: s.script!.args }
+  try { const r = await new Scripts(controlDir).owned(s.script!.id, owner); return { ...ref, revision: r.revision, sha256: r.sha256 } }
+  catch { return ref }
+}
+const runTexts = (s: Schedule, dueAt: string) => s.script ? [`[schedule ${s.id} due ${dueAt}] script ${s.script.id}`] : [`[schedule ${s.id} due ${dueAt}]`, s.text]
 export const scheduledRunId = (s: Schedule, due: number) => 'r_schedule_' + createHash('sha256')
   .update(JSON.stringify([s.id,s.revision,due])).digest('hex')
 export const holdsSchedule = (s: Schedule, r: RunRecord): boolean =>
@@ -45,13 +62,13 @@ const atomic = async (file: string, value: unknown, exclusive = false) => {
 }
 export class Scheduler {
   private dir: string
-  constructor(private controlDir: string) { this.dir = join(controlDir,'schedules') }
+  constructor(private controlDir: string, private checkPreflight = installedPreflight) { this.dir = join(controlDir,'schedules') }
   private async ensure() { await mkdir(this.dir,{recursive:true,mode:0o700}) }
   async get(id: string): Promise<Schedule> {
     const s = JSON.parse(await readFile(join(this.dir,assertId(id)+'.json'),'utf8')) as Schedule
     if (s.version !== 1 || s.id !== id || !validScheduledOrigin({id:s.id,revision:s.revision,dueAt:new Date().toISOString(),pairedAt:s.owner?.pairedAt,originRunId:s.originRunId}) ||
-      (s.when !== undefined && s.when !== 'unreviewed-failures') || typeof s.enabled !== 'boolean' || !s.name || typeof s.text !== 'string' || !s.text.trim() ||
-      !validOwner(s.owner) || !isExecutionChoice(s.execution) ||
+      (s.when !== undefined && s.when !== 'unreviewed-failures') || (s.preflight !== undefined && !validPreflight(s.preflight)) || typeof s.enabled !== 'boolean' || !s.name || typeof s.text !== 'string' ||
+      !validOwner(s.owner) || !validExecution(s) ||
       (s.delivery !== undefined && !validApplicationOrigin({...s.delivery, requestId: s.id})))
       throw new Error('Invalid schedule record')
     validateTrigger(s.trigger)
@@ -99,7 +116,8 @@ export class Scheduler {
       if (!runState && current.some(r => holdsSchedule(s,r))) continue
       try {
         const nextAt = await this.pendingOccurrence(s)
-        if (runState || nextAt !== null) active.push({...s,nextAt,runState,...(last ? {
+        const scriptRevision = s.script ? await new Scripts(this.controlDir).get(s.script.id).then(r => r.revision, () => undefined) : undefined
+        if (runState || nextAt !== null) active.push({...s,nextAt,runState,...(scriptRevision ? {scriptRevision} : {}),...(last ? {
           lastRun: {status:last.status,at:last.endedAt ?? last.startedAt ?? last.createdAt,currentRevision:last.scheduled!.revision===s.revision},
         } : {})})
       }
@@ -110,11 +128,26 @@ export class Scheduler {
   async save(input: Omit<Schedule,'version'|'revision'>, exclusive = false): Promise<Schedule> {
     await this.ensure(); assertId(input.id)
     if (input.when !== undefined && input.when !== 'unreviewed-failures') throw new Error('Unknown schedule condition')
-    const execution: ExecutionChoice = {...input.execution, preset: persistedPreset(input.execution.preset)}
-    if (!input.name || !input.text?.trim() || !isExecutionChoice(execution)) throw new Error('Schedule needs name, text and an AI selection')
-    assertScheduledModel(execution.preset.model)
-    assertEffort(execution.preset.effort, execution.preset.model, execution.preset.cli)
-    const s: Schedule = {...input, execution, trigger:validateTrigger(input.trigger),version:1,revision:randomUUID()}
+    if(input.preflight !== undefined && !validPreflight(input.preflight)) throw Error('Invalid schedule preflight')
+    let s: Schedule
+    if (input.script) {
+      if (input.execution !== undefined || !input.name) throw new Error('Script schedules need a name and no AI selection')
+      const script = {id:assertScriptId(input.script.id),args:assertScriptArgs(input.script.args)}
+      await new Scripts(this.controlDir).owned(script.id, input.owner)
+      s = {...input, text:'', script, trigger:validateTrigger(input.trigger),version:1,revision:randomUUID()}
+    } else {
+      if (!input.execution) throw new Error('Schedule needs name, text and an AI selection')
+      const execution: ExecutionChoice = {...input.execution, preset: persistedPreset(input.execution.preset)}
+      if (!input.name || !input.text?.trim() || !isExecutionChoice(execution)) throw new Error('Schedule needs name, text and an AI selection')
+      const setups = [execution.preset, ...execution.fallbacks ?? []]
+      for (const preset of setups) {
+        assertScheduledModel(preset.model)
+        assertEffort(preset.effort, preset.model, preset.cli)
+      }
+      const key = (p: AiPreset) => JSON.stringify([p.cli, p.provider, p.model, p.effort])
+      if (new Set(setups.map(key)).size !== setups.length) throw new Error('Task setups must be distinct')
+      s = {...input, execution, trigger:validateTrigger(input.trigger),version:1,revision:randomUUID()}
+    }
     const now = Date.now()
     let next = nextOccurrence(s.trigger,now-1)
     if (next === null) throw new Error('Schedule has no future occurrence within eight years')
@@ -129,12 +162,26 @@ export class Scheduler {
         }
         // Publish the cursor first so a crash cannot expose a new revision with
         // a missing cursor that falls back to the trigger's historical start.
-        await atomic(join(this.dir,`${s.id}.${s.revision}.cursor`),{next})
+        const prior=await this.preflightReceipt(previous)
+        await atomic(join(this.dir,`${s.id}.${s.revision}.cursor`),{next,...(JSON.stringify(previous.preflight)===JSON.stringify(s.preflight) && prior ? {preflight:prior} : {})})
       }
     }
     await atomic(join(this.dir,s.id+'.json'),s,exclusive)
     return s
   }
+  async preflight(id:string, revision:string) {
+    const s=await this.get(id)
+    if(s.revision!==revision || !s.enabled || !s.preflight) throw Error('Schedule preflight is unavailable')
+    const receipt=await this.checkPreflight(id,revision)
+    const cursor=join(this.dir,`${s.id}.${s.revision}.cursor`)
+    const previous=await readFile(cursor,'utf8').then(v=>JSON.parse(v)).catch(async e=>{if(e.code==='ENOENT')return {next:await this.pendingOccurrence(s)};throw e})
+    const admitted=receipt.eligible && (s.preflight.on!=='changed' || previous.preflight?.fingerprint!==receipt.fingerprint)
+    return {receipt,admitted,previous,cursor}
+  }
+  async preflightReceipt(s:Schedule) {
+    try {return JSON.parse(await readFile(join(this.dir,`${s.id}.${s.revision}.cursor`),'utf8')).preflight}
+    catch(e) {if((e as NodeJS.ErrnoException).code==='ENOENT')return undefined;throw e}
+  }
   async enable(id: string, enabled: boolean): Promise<Schedule> {
     const s = await this.get(id)
     // Pausing preserves the cursor. Resuming coalesces missed recurrences like restart.
@@ -163,7 +210,8 @@ export class Scheduler {
   async trigger(id: string, revision: string, key: string, owner: Owner, runs: RunStore): Promise<RunRecord> {
     const s=await this.get(id)
     if (!sameOwner(s.owner,owner) || !s.enabled || s.revision !== revision) throw new Error('Schedule is disabled, changed or outside this owner binding')
-    assertScheduledModel(s.execution.preset.model)
+    if (s.script) await new Scripts(this.controlDir).owned(s.script.id, owner)
+    else assertScheduledModel(s.execution!.preset.model)
     if (s.delivery) {
       const binding=(await new ApplicationBindings(this.controlDir).list()).find(b=>b.bindingId===s.delivery!.bindingId)
       if (!binding || !sameOwner(binding.owner,owner)) throw new Error('Schedule delivery binding is unavailable')
@@ -177,11 +225,20 @@ export class Scheduler {
     const all=await runs.list()
     if (all.some(r=>holdsSchedule(s,r))) throw new Error('Inspect the held occurrence and edit the schedule before retrying')
     if (s.when === 'unreviewed-failures' && !all.some(r=>needsFailureReview(r) && ownsRun(owner,r) && (!r.scheduled || r.scheduled.pairedAt===owner.pairedAt))) throw new Error('Schedule condition is not met')
+    let checked: Awaited<ReturnType<Scheduler['preflight']>> | undefined
+    if(s.preflight) {
+      checked=await this.preflight(s.id,s.revision)
+      if(!checked.receipt.eligible) throw Error('Schedule preflight has no eligible work')
+      const current=await this.get(s.id)
+      if(!current.enabled || current.revision!==s.revision) throw Error('Schedule changed during preflight')
+    }
     const dueAt=new Date().toISOString()
-    return runs.create({id:runId,ownerId:ownerId(owner),ownerEpoch:ownerEpoch(owner),
+    const run=await runs.create({id:runId,ownerId:ownerId(owner),ownerEpoch:ownerEpoch(owner),
       ...(s.delivery ? {delivery:s.delivery} : {chatId:s.owner.telegramChatId,telegramUserId:s.owner.telegramUserId,telegramEpoch:s.owner.telegramLinkedAt ?? s.owner.pairedAt}),
-      texts:[`[schedule ${s.id} due ${dueAt}]`,s.text],execution:{...s.execution,sessionId:randomUUID()},
+      texts:runTexts(s,dueAt),...(s.script ? {script:await scriptRef(this.controlDir,s,owner)} : {execution:{...s.execution!,sessionId:randomUUID()}}),
       scheduled:{id:s.id,revision:s.revision,dueAt,pairedAt:s.owner.pairedAt,...(s.originRunId ? {originRunId:s.originRunId} : {})}},true)
+    if(checked) await atomic(checked.cursor,{...checked.previous,preflight:checked.receipt})
+    return run
   }
   async recover(runs: RunStore) {
     for (const run of await runs.list()) {
@@ -204,7 +261,7 @@ export class Scheduler {
       try {
         const next = await this.pendingOccurrence(s)
         if (next === null || next > now) continue
-        assertScheduledModel(s.execution.preset.model)
+        if (!s.script) assertScheduledModel(s.execution!.preset.model)
         // One occurrence at a time. A failed reviewer stops this revision just like
         // interrupted work: retain its receipt until an explicit schedule edit.
         if ((await runs.list()).some(r => r.scheduled?.id === s.id &&
@@ -213,14 +270,23 @@ export class Scheduler {
         if (s.when === 'unreviewed-failures' && !(await runs.list()).some(r => needsFailureReview(r) && ownsRun(owner, r) && (!r.scheduled || r.scheduled.pairedAt === owner.pairedAt))) {
           await atomic(cursor,{next:future}); continue
         }
+        let preflight: PreflightReceipt | undefined
+        if(s.preflight) {
+          try {
+            const checked=await this.preflight(s.id,s.revision)
+            preflight=checked.receipt
+            if(!checked.admitted) {await atomic(cursor,{next:future,preflight});continue}
+            const current=await this.get(s.id);if(!current.enabled || current.revision!==s.revision)continue
+          } catch (error) {console.error('Schedule preflight unavailable',s.id,error instanceof Error ? error.message : 'Unknown error');const prior=await readFile(cursor,'utf8').then(v=>JSON.parse(v)).catch(e=>{if(e.code==='ENOENT')return {};throw e});await atomic(cursor,{next:future,preflight:{...prior.preflight,state:'unavailable',observedAt:new Date().toISOString()}});continue}
+        }
         const dueAt = new Date(next).toISOString()
         await runs.create({id:scheduledRunId(s,next),
           ownerId:ownerId(owner),ownerEpoch:ownerEpoch(owner),
           ...(s.delivery ? {delivery:s.delivery} : {chatId:s.owner.telegramChatId,telegramUserId:s.owner.telegramUserId,telegramEpoch:s.owner.telegramLinkedAt ?? s.owner.pairedAt}),
-          texts:[`[schedule ${s.id} due ${dueAt}]`, s.text],execution:s.execution,
+          texts:runTexts(s,dueAt),...(s.script ? {script:await scriptRef(this.controlDir,s,owner)} : {execution:s.execution}),
           scheduled:{id:s.id,revision:s.revision,dueAt,pairedAt:s.owner.pairedAt,...(s.originRunId?{originRunId:s.originRunId}:{})}},true)
         // A restart between run creation and this cursor write sees the same occurrence ID.
-        await atomic(cursor,{next:future})
+        await atomic(cursor,{next:future,...(preflight ? {preflight} : {})})
       } catch (error) { console.error('Schedule dispatch failed',s.id,error instanceof Error ? error.message : 'Unknown error') }
     }
   }

package/src/scripts.ts

@@ -0,0 +1,167 @@
+import { mkdir, readFile, readdir, writeFile, rename, link, rm, realpath, stat, access } from 'node:fs/promises'
+import { constants as fsConstants } from 'node:fs'
+import { randomUUID, createHash } from 'node:crypto'
+import path from 'node:path'
+import { type Owner, sameOwner, validOwner } from './control-state.js'
+import { assertId } from './identity.js'
+
+// Registered scripts reference agent-owned code in the workspace. Core keeps
+// only the registration: no second source copy, interpreter or dependency setup.
+export type ScriptRegistration = {
+  version: 1; id: string; revision: string; owner: Owner
+  entry: string; interpreter: string; args: string[]; sha256: string
+  timeoutSeconds: number; registeredAt: string; updatedAt: string
+}
+// Captured on the run when an occurrence is queued; the launcher verifies it.
+export type ScriptRunRef = { id: string; revision?: string; sha256?: string; args: string[] }
+
+export const DEFAULT_SCRIPT_TIMEOUT_SECONDS = 900
+export const MAX_SCRIPT_TIMEOUT_SECONDS = 21600
+const SCRIPT_ID = /^[a-z0-9][a-z0-9_-]{0,63}$/
+const COMMAND = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/
+
+export const assertScriptId = (id: unknown): string => {
+  if (typeof id !== 'string' || !SCRIPT_ID.test(id)) throw new Error('Script ID must be 1-64 lowercase letters, digits, _ or -')
+  return id
+}
+
+export const assertScriptArgs = (args: unknown): string[] => {
+  if (!Array.isArray(args) || args.length > 64 || args.some(arg => typeof arg !== 'string' || arg.length > 4096 || arg.includes('\0')))
+    throw new Error('Script arguments must be at most 64 literal strings')
+  return args as string[]
+}
+
+// An installed interpreter is a bare command resolved on the executor PATH or an
+// absolute path. Anything with whitespace or shell syntax is a command string.
+export const assertInterpreter = (value: unknown): string => {
+  if (typeof value !== 'string' || !(COMMAND.test(value) || (path.isAbsolute(value) && !/[\s\0;&|`$<>()'"\\*?]/.test(value))))
+    throw new Error('Interpreter must be an installed command name or absolute path, not a shell command')
+  return value
+}
+
+export const assertTimeout = (value: unknown): number => {
+  if (!Number.isSafeInteger(value) || (value as number) < 1 || (value as number) > MAX_SCRIPT_TIMEOUT_SECONDS)
+    throw new Error(`Script timeout must be 1..${MAX_SCRIPT_TIMEOUT_SECONDS} seconds`)
+  return value as number
+}
+
+export const validScriptRunRef = (value: unknown): value is ScriptRunRef => {
+  const ref = value as ScriptRunRef
+  try {
+    return Boolean(ref) && assertScriptId(ref.id) === ref.id && assertScriptArgs(ref.args) === ref.args &&
+      (ref.revision === undefined || (typeof ref.revision === 'string' && /^[a-zA-Z0-9_-]+$/.test(ref.revision))) &&
+      (ref.sha256 === undefined || (typeof ref.sha256 === 'string' && /^[a-f0-9]{64}$/.test(ref.sha256)))
+  } catch { return false }
+}
+
+// The interpreter must be an installed runtime, not unhashed workspace code.
+export const resolveInterpreter = async (interpreter: string, pathValue = process.env.PATH, workspace?: string): Promise<string> => {
+  assertInterpreter(interpreter)
+  const candidates = path.isAbsolute(interpreter) ? [interpreter]
+    // Relative PATH entries would resolve against a different cwd at spawn time.
+    : (pathValue ?? '').split(path.delimiter).filter(directory => path.isAbsolute(directory)).map(directory => path.join(directory, interpreter))
+  for (const candidate of candidates) {
+    let real: string
+    try { await access(candidate, fsConstants.X_OK); if (!(await stat(candidate)).isFile()) continue; real = await realpath(candidate) } catch { continue }
+    if (workspace && real.startsWith(await realpath(workspace) + path.sep)) throw new Error('Interpreter must be an installed runtime outside the agent workspace')
+    return candidate
+  }
+  throw new Error(`Interpreter ${interpreter} is not installed on the executor PATH`)
+}
+
+// Resolve a workspace-relative entry point to its real file inside the workspace.
+export const workspaceEntry = async (workspace: string, entry: string): Promise<{ file: string; relative: string }> => {
+  if (typeof entry !== 'string' || !entry || entry.includes('\0')) throw new Error('Script entry point is required')
+  const root = await realpath(workspace)
+  let file: string
+  try { file = await realpath(path.resolve(root, entry)) }
+  catch { throw new Error('Script entry point does not exist in the agent workspace') }
+  if (!file.startsWith(root + path.sep) || !(await stat(file)).isFile()) throw new Error('Script entry point must be a file inside the agent workspace')
+  return { file, relative: path.relative(root, file) }
+}
+
+export const fileSha256 = async (file: string) => createHash('sha256').update(await readFile(file)).digest('hex')
+
+const atomic = async (file: string, value: unknown, exclusive = false) => {
+  const tmp = `${file}.${randomUUID()}.tmp`
+  try {
+    await writeFile(tmp, JSON.stringify(value) + '\n', { mode: 0o600, flag: 'wx' })
+    if (exclusive) await link(tmp, file)
+    else await rename(tmp, file)
+  } finally { await rm(tmp, { force: true }) }
+}
+
+export class Scripts {
+  private dir: string
+  constructor(controlDir: string) { this.dir = path.join(controlDir, 'scripts') }
+
+  async get(id: string): Promise<ScriptRegistration> {
+    const s = JSON.parse(await readFile(path.join(this.dir, assertId(assertScriptId(id)) + '.json'), 'utf8')) as ScriptRegistration
+    if (s.version !== 1 || s.id !== id || typeof s.revision !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(s.revision) || !validOwner(s.owner) ||
+      typeof s.entry !== 'string' || !s.entry || path.isAbsolute(s.entry) || s.entry.split(/[\\/]/).includes('..') ||
+      !/^[a-f0-9]{64}$/.test(s.sha256)) throw new Error('Invalid script registration')
+    assertInterpreter(s.interpreter); assertScriptArgs(s.args); assertTimeout(s.timeoutSeconds)
+    return s
+  }
+
+  async owned(id: string, owner: Owner): Promise<ScriptRegistration> {
+    let s: ScriptRegistration
+    try { s = await this.get(id) }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') throw new Error(`Script ${id} is not registered`)
+      throw error
+    }
+    if (!sameOwner(s.owner, owner)) throw new Error('Script registration is outside this owner binding')
+    return s
+  }
+
+  async list(owner: Owner): Promise<ScriptRegistration[]> {
+    let names: string[]
+    try { names = await readdir(this.dir) }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []; throw error }
+    const result: ScriptRegistration[] = []
+    for (const name of names.filter(name => /^[a-z0-9][a-z0-9_-]*\.json$/.test(name)).sort()) {
+      try { const s = await this.get(name.slice(0, -5)); if (sameOwner(s.owner, owner)) result.push(s) }
+      catch { console.error('Unreadable script registration', name) }
+    }
+    return result
+  }
+
+  // Register or explicitly update: hashes the current entry-point bytes.
+  async save(input: { id: string; owner: Owner; workspace: string; entry: string; interpreter: string; args: string[]; timeoutSeconds: number; pathValue?: string }, create: boolean): Promise<ScriptRegistration> {
+    assertScriptId(input.id)
+    if (!validOwner(input.owner)) throw new Error('Script registration requires the paired owner')
+    const previous = create ? undefined : await this.owned(input.id, input.owner)
+    const { file, relative } = await workspaceEntry(input.workspace, input.entry)
+    await resolveInterpreter(assertInterpreter(input.interpreter), input.pathValue, input.workspace)
+    const now = new Date().toISOString()
+    const s: ScriptRegistration = { version: 1, id: input.id, revision: randomUUID(), owner: input.owner, entry: relative,
+      interpreter: input.interpreter, args: assertScriptArgs(input.args), sha256: await fileSha256(file),
+      timeoutSeconds: assertTimeout(input.timeoutSeconds), registeredAt: previous?.registeredAt ?? now, updatedAt: now }
+    await mkdir(this.dir, { recursive: true, mode: 0o700 })
+    try { await atomic(path.join(this.dir, s.id + '.json'), s, create) }
+    catch (error) {
+      if (create && (error as NodeJS.ErrnoException).code === 'EEXIST') throw new Error('Script is already registered; use update')
+      throw error
+    }
+    return s
+  }
+
+  async remove(id: string, owner: Owner) {
+    await this.owned(id, owner)
+    await rm(path.join(this.dir, assertScriptId(id) + '.json'))
+  }
+
+  // Executor-side check, immediately before spawn: the queued registration
+  // revision must still be current and the entry-point bytes must match it.
+  async verifiedInvocation(ref: ScriptRunRef, workspace: string, pathValue?: string) {
+    if (!validScriptRunRef(ref) || !ref.revision || !ref.sha256) throw new Error(`Script ${ref?.id ?? ''} was not registered when queued`)
+    let s: ScriptRegistration
+    try { s = await this.get(ref.id) } catch { throw new Error(`Script ${ref.id} registration is unavailable`) }
+    if (s.revision !== ref.revision || s.sha256 !== ref.sha256) throw new Error(`Script ${ref.id} registration changed after this run was queued`)
+    const { file } = await workspaceEntry(workspace, s.entry)
+    if (await fileSha256(file) !== s.sha256) throw new Error(`Script ${ref.id} entry point changed since registration; inspect it and run an explicit registration update`)
+    const command = await resolveInterpreter(s.interpreter, pathValue, workspace)
+    return { command, args: [file, ...s.args, ...ref.args], registration: s }
+  }
+}

package/src/setup-fallback.ts

@@ -0,0 +1,122 @@
+import { presetLabel, presetProvider, type AiPreset, type ExecutionChoice } from './ai.js'
+
+// Ordered task setups for one scheduled occurrence. Core advances only on typed
+// evidence that the engine never started work: a missing CLI or a provider
+// rejection before any model output or tool item. Anything else stops the chain.
+export type StartupCategory = 'cli-unavailable' | 'quota' | 'provider-rejected' | 'access-denied'
+export type StartupRejection = { category: StartupCategory; resetAt?: string }
+export type AttemptCategory = StartupCategory | 'after-work-began' | 'uncertain' | 'same-quota-scope'
+export type SetupAttempt = {
+  preset: AiPreset
+  quotaScope: string
+  outcome: 'running' | 'completed' | 'failed' | 'cancelled' | 'skipped'
+  category?: AttemptCategory
+  resetAt?: string
+  exitCode?: number | null
+  startedAt?: string
+  endedAt?: string
+}
+
+const categories: StartupCategory[] = ['cli-unavailable', 'quota', 'provider-rejected', 'access-denied']
+export const advances = (rejection?: StartupRejection): boolean => Boolean(rejection && rejection.category !== 'access-denied')
+
+export const setupCandidates = (execution: ExecutionChoice): AiPreset[] => [execution.preset, ...(execution.fallbacks ?? [])]
+
+// Allowance is metered per provider account, not per credential file. Setups on
+// the same native client share a scope; OpenCode/Pi share their upstream
+// provider. A different credential alone never proves independent allowance.
+export const quotaScope = (preset: AiPreset): string => {
+  if (['opencode', 'pi'].includes(preset.cli)) {
+    const provider = preset.cli === 'pi' ? preset.model?.split('/')[0] : presetProvider(preset)
+    return provider ? `provider:${provider}` : preset.cli
+  }
+  return preset.cli === 'codex-gui' ? 'codex' : preset.cli
+}
+
+// The next untried setup, skipping those whose quota scope already rejected
+// this occurrence. Each candidate is tried at most once.
+export const nextSetup = (candidates: AiPreset[], attempts: SetupAttempt[]): { skipped: SetupAttempt[]; preset?: AiPreset } => {
+  const exhausted = new Set(attempts.filter(a => a.category === 'quota').map(a => a.quotaScope))
+  const skipped: SetupAttempt[] = []
+  for (const preset of candidates.slice(attempts.length)) {
+    const scope = quotaScope(preset)
+    if (!exhausted.has(scope)) return { skipped, preset }
+    const at = new Date().toISOString()
+    skipped.push({ preset, quotaScope: scope, outcome: 'skipped', category: 'same-quota-scope', startedAt: at, endedAt: at })
+  }
+  return { skipped }
+}
+
+export class SetupsUnavailableError extends Error {}
+
+export const unavailableSummary = (attempts: SetupAttempt[]): string =>
+  `Every task setup was unavailable: ${attempts.map(a => `${presetLabel(a.preset)} (${a.category}${a.resetAt ? `, resets ${a.resetAt}` : ''})`).join('; ')}`
+
+const epochSeconds = (value: unknown): string | undefined =>
+  typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? new Date(value * 1000).toISOString() : undefined
+
+const claudeErrors: Record<string, StartupCategory> = {
+  rate_limit: 'quota', billing_error: 'quota',
+  authentication_failed: 'access-denied', oauth_org_not_allowed: 'access-denied', account_on_hold: 'access-denied',
+  verification_required: 'access-denied', cloud_credential_error: 'access-denied',
+  overloaded: 'provider-rejected', server_error: 'provider-rejected', model_not_found: 'provider-rejected', invalid_request: 'provider-rejected',
+}
+
+// Codex app-server `codexErrorInfo` of a failed turn.
+export const codexRejection = (info: unknown): StartupCategory | undefined => {
+  if (info === 'usageLimitExceeded' || info === 'rateLimitExceeded') return 'quota'
+  if (info === 'unauthorized') return 'access-denied'
+  if (['serverOverloaded', 'internalServerError', 'badRequest', 'flexUnavailable'].includes(info as string)) return 'provider-rejected'
+  if (!info || typeof info !== 'object') return undefined
+  const status = (Object.values(info)[0] as { httpStatusCode?: unknown } | undefined)?.httpStatusCode
+  if (typeof status !== 'number') return undefined
+  return status === 429 ? 'quota' : [401, 403].includes(status) ? 'access-denied' : [400, 404].includes(status) || status >= 500 ? 'provider-rejected' : undefined
+}
+
+// The latest reset among exhausted Codex rate-limit windows.
+export const codexResetAt = (limits: any): string | undefined => {
+  const resets = [limits?.primary, limits?.secondary].filter(w => w && w.usedPercent >= 100 && typeof w.resetsAt === 'number').map(w => w.resetsAt as number)
+  return resets.length ? epochSeconds(Math.max(...resets)) : undefined
+}
+
+export const startupLine = (state: { workBegan: boolean; rejection?: StartupRejection }): string =>
+  JSON.stringify({ type: 'ez.startup', workBegan: state.workBegan, ...(state.rejection ? { rejection: state.rejection } : {}) })
+
+// Reads structured stdout only: Ez transport summaries (`ez.startup`) and
+// Claude stream-json envelopes. Model text is never inspected. Any event that
+// is not known pre-work metadata counts as work, so ambiguity never advances.
+export const startupObserver = () => {
+  let buffer = '', workBegan = false, rejection: StartupRejection | undefined
+  const line = (text: string) => {
+    if (!text.trim()) return
+    let event: any
+    try { event = JSON.parse(text) } catch { workBegan = true; return }
+    if (event?.type === 'ez.startup') {
+      if (event.workBegan === true) workBegan = true
+      const r = event.rejection
+      if (r && categories.includes(r.category) && (r.resetAt === undefined || Number.isFinite(Date.parse(r.resetAt))))
+        rejection = { category: r.category, ...(r.resetAt ? { resetAt: r.resetAt } : {}) }
+      return
+    }
+    if (event?.type === 'thread.started' || event?.type === 'result' ||
+        (event?.type === 'system' && event.subtype === 'init')) return
+    if (event?.type === 'rate_limit_event') {
+      const info = event.rate_limit_info
+      if (info?.status === 'rejected') rejection = { category: 'quota', ...(epochSeconds(info.resetsAt) ? { resetAt: epochSeconds(info.resetsAt) } : {}) }
+      return
+    }
+    const category = event?.type === 'assistant' && typeof event.error === 'string' ? claudeErrors[event.error] : undefined
+    if (category) rejection = { category, ...(category === 'quota' && rejection?.resetAt ? { resetAt: rejection.resetAt } : {}) }
+    else workBegan = true
+  }
+  return {
+    write: (chunk: string) => {
+      buffer += chunk
+      const lines = buffer.split('\n')
+      buffer = lines.pop() ?? ''
+      for (const text of lines) line(text)
+    },
+    result: () => { line(buffer); buffer = ''; return { workBegan, rejection } },
+    summary: () => startupLine({ workBegan, rejection }),
+  }
+}

package/src/setup.ts

@@ -9,7 +9,7 @@ import { discoverDefaults } from './client-defaults.js'
 import { chatPreset } from './ai.js'
 import { ControlStore } from './control-state.js'
 import { loadControlConfig } from './config.js'
-import { EXECUTOR_REGISTRY, resolveExecutor, executorKey } from './executor.js'
+import { EXECUTOR_REGISTRY, resolveExecutor, executorKey, claudeConfigHome } from './executor.js'
 import { desktopCodexPath } from './desktop-bridge.js'
 
 export const findExecutableInPath = async (
@@ -152,7 +152,7 @@ export const runCli = async (): Promise<void> => {
     const config = loadControlConfig()
     await new ControlStore(config.controlDir, config.pairingTtlMs).syncClientPresets(
       chatPreset(await readActiveExecutor(envFilePath)), await discoverDefaults(workspace,
-        { codexHome: path.join(config.controlDir, 'cli', 'codex') }))
+        { codexHome: path.join(config.controlDir, 'cli', 'codex'), claudeHome: claudeConfigHome(config.controlDir) }))
     console.log(JSON.stringify({ workspace, created }))
     return
   }

package/src/task-capability.ts

@@ -1,7 +1,8 @@
-import { execFile } from 'node:child_process'
+import { execFile, spawn } from 'node:child_process'
 import { promisify } from 'node:util'
 import { readFile } from 'node:fs/promises'
 import path from 'node:path'
+import {fileURLToPath} from 'node:url'
 import { executorEnvironment } from './executor.js'
 import type { TaskCapability } from './tasks.js'
 import {attachmentLimit,stageTaskAttachment,type TaskAttachment} from './task-attachments.js'
@@ -43,3 +44,18 @@ export async function runTaskCapability(toolsHome: string | undefined, capabilit
   if (code !== 0 || !stdout.trim()) throw new Error(`Channel capability failed with exit ${code}`)
   return {output:stdout}
 }
+
+export async function launchTaskApplication(toolsHome: string | undefined, launch:{command:string;args:string[]}, input:unknown, runId:string):Promise<unknown> {
+  const isolated=!!process.env.EZ_PLUGIN_BROKER_SOCKET
+  if(!isolated && (!toolsHome || !path.isAbsolute(toolsHome)))throw Error('Installed tool registry required')
+  const config=!isolated ? JSON.parse(await readFile(path.join(toolsHome!,'config.json'),'utf8')) : undefined
+  // Fixed owner-configured command; literal private stdin, never a shell or model-selected args.
+  return new Promise((resolve,reject)=>{
+    const child=spawn(isolated ? process.execPath : path.join(toolsHome!,'bin','ez'),isolated ? [fileURLToPath(new URL('../bin/ez',import.meta.url)),'--task-application'] : [launch.command,...launch.args],{env:{...executorEnvironment(),EZ_RUN_ID:runId},...(config ? {cwd:config.workspace} : {}),stdio:['pipe','pipe','pipe']})
+    let output='';const timer=setTimeout(()=>{child.kill();reject(Error('Application launch timed out'))},30000)
+    child.stdout.on('data',chunk=>{output+=chunk;if(Buffer.byteLength(output)>16000){child.kill();reject(Error('Application launch output too large'))}})
+    child.stderr.resume();child.on('error',reject)
+    child.on('close',code=>{clearTimeout(timer);try{if(code!==0)throw Error('Application launch failed');const value=JSON.parse(output);const url=new URL(value.launch?.url);if(url.protocol!=='https:' || url.username || url.password || typeof value.launch?.expiresAt!=='number')throw Error('Invalid application launch receipt');resolve(value.launch)}catch(e){reject(e)}})
+    child.stdin.end(JSON.stringify(input))
+  })
+}