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

package/src/schedule-cli.ts

@@ -1,6 +1,7 @@
 import { needsFailureReview, failureStamp, redactFailure } from './failure.js'
 import { parseArgs } from 'node:util'
 import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
 import { randomUUID } from 'node:crypto'
 import { loadControlConfig } from './config.js'
 import { ControlStore, sameOwner } from './control-state.js'
@@ -9,28 +10,49 @@ import type { RunRecord } from './runs.js'
 import { callDeliverySocket, socketPathFor } from './delivery-socket.js'
 import { initialPreset, isPreset } from './ai.js'
 import { executionOverrides } from './model-policy.js'
-import { holdsSchedule, Scheduler } from './scheduler.js'
+import { holdsSchedule, Scheduler, executionType } from './scheduler.js'
+import { Scripts, fileSha256, workspaceEntry, DEFAULT_SCRIPT_TIMEOUT_SECONDS } from './scripts.js'
+import { executorEnvironment } from './executor.js'
 import { ownsRun } from './identity.js'
 import { type Trigger } from './schedule-time.js'
 
 async function main() {
-  const { values:v, positionals:[action='list',id] } = parseArgs({allowPositionals:true,options:{
+  const { values:v, positionals:[action='list',id,scriptId] } = parseArgs({allowPositionals:true,options:{
+    script:{type:'string'}, arg:{type:'string',multiple:true}, file:{type:'string'}, interpreter:{type:'string'}, 'timeout-seconds':{type:'string'},
     cli:{type:'string'}, model:{type:'string'}, effort:{type:'string'},
-    all:{type:'boolean'}, limit:{type:'string'}, when:{type:'string'}, status:{type:'string'}, diagnosis:{type:'string'}, recovery:{type:'string'}, outcome:{type:'string'}, 'failed-at':{type:'string'},
-    name:{type:'string'}, text:{type:'string'}, 'text-file':{type:'string'}, at:{type:'string'}, now:{type:'boolean'},
+    all:{type:'boolean'}, limit:{type:'string'}, offset:{type:'string'}, expected:{type:'string'}, key:{type:'string'}, when:{type:'string'}, status:{type:'string'}, diagnosis:{type:'string'}, recovery:{type:'string'}, outcome:{type:'string'}, 'failed-at':{type:'string'},
+    'preflight-file':{type:'string'},'clear-preflight':{type:'boolean'},name:{type:'string'}, text:{type:'string'}, 'text-file':{type:'string'}, at:{type:'string'}, now:{type:'boolean'},
     cron:{type:'string'}, timezone:{type:'string'}, 'every-seconds':{type:'string'}, start:{type:'string'}, until:{type:'string'}, help:{type:'boolean'},
   }})
   if(v.help){console.log(`ezenciel-agents-schedule list | runs | show ID | pause ID | resume ID | remove ID | cancel RUN_ID
   failures [--all] [--limit N] | run RUN_ID | context
+  evidence [RUN_ID] [--offset N --limit N --expected SNAPSHOT_SHA256]
+  trigger SCHEDULE_ID --key REQUEST_KEY
   review RUN_ID --failed-at ISO --status resolved|attention --diagnosis TEXT --recovery TEXT --outcome TEXT
-  create [ID] | edit ID --name NAME (--text TEXT | --text-file FILE)
+  create [ID] | edit ID --name NAME (--text TEXT | --text-file FILE | --script SCRIPT_ID [--arg=VALUE ...])
     --now | --at ISO_WITH_OFFSET | --every-seconds N | --cron 'MIN HOUR DAY MONTH WEEKDAY' --timezone IANA
     [--cli EXECUTOR] [--model MODEL] [--effort <native-effort>]
+    [--preflight-file FILE | --clear-preflight]
     [--start ISO_WITH_OFFSET] [--until ISO_WITH_OFFSET] [--when unreviewed-failures]
+  script list | show SCRIPT_ID | remove SCRIPT_ID
+  script register|update SCRIPT_ID --file WORKSPACE_PATH --interpreter COMMAND [--arg=VALUE ...] [--timeout-seconds N]
+Execution types: agent (prompt, engine, model, effort) or script (registered script ID and saved arguments).
+A script registration references an entry point inside the agent workspace and records its SHA-256. Core invokes
+the installed interpreter with the entry point and arguments directly, without a shell or a model. Changed entry-point
+bytes refuse to run until an explicit script update. The hash covers that file only, not imported dependencies.
+Script runs receive EZ_RUN_ID, EZ_SCHEDULE_ID, EZ_SCHEDULE_REVISION, EZ_DUE_AT, EZ_SCRIPT_ID, EZ_SCRIPT_REVISION and
+EZ_SCRIPT_SHA256 plus the normal executor allowlist. Stdout/stderr are bounded diagnostics in run, never owner messages.
+Script runs have a timeout (default ${DEFAULT_SCRIPT_TIMEOUT_SECONDS}s) and are never retried automatically.
 Context reads the current run only.
+Evidence exports sanitized current-owner Telegram operational metadata only.
+Follow nextOffset with --expected; a changed snapshot requires restarting.
+Relay retention is incomplete. Content hashes identify submitted text, not recipient content.
+Native sessions, tool/delegation events and failure/review prose are not exported.
 Failures default to unreviewed owner runs. Review records a diagnosis; it never changes execution status or retries work.
 A conditional review schedule consumes no model run when there are no unreviewed failures.
-New tasks inherit the selected engine settings. Omitted model/effort uses native defaults; edit preserves existing settings unless overridden.
+New tasks capture the selected engine settings; edit preserves existing settings unless overridden.
+Every task requires a concrete saved model. Supply --model if the selected settings have none; existing tasks never fall back to chat or client defaults.
+Trigger runs an existing task once with its saved instructions, AI and delivery binding in a fresh session. Reuse the request key after an uncertain result; the regular schedule is unchanged.
 Creates a scheduled task. Instructions are text, never shell commands.
 Use --now to run once. Run completion is not delivery proof.
 Edit replaces the full schedule. Pause/remove affect future work; cancel stops a particular run.
@@ -63,6 +85,10 @@ Cron uses numeric five-field syntax, lists/ranges/steps, and traditional day/wee
   if(process.env.EZ_RUN_ID && (!caller || caller.status!=='running' || caller.external || caller.taskId || caller.replyOnly ||
     !ownsRun(owner, caller) ||
     (caller.scheduled && caller.scheduled.pairedAt!==owner.pairedAt)))throw new Error('Scheduling requires an active owner-authorized run')
+  // A script occurrence may read state and deliver through bound plugins; it
+  // cannot change registrations or schedules, including its own.
+  const readOnly=['list','runs','show','run','context','failures','evidence'].includes(action) || (action==='script' && ['list','show'].includes(id ?? ''))
+  if(caller?.script && !readOnly)throw new Error('Script runs cannot change scripts or schedules')
   const owned=(s:{owner:typeof owner})=>sameOwner(s.owner,owner)
   const ownsFailureRun=(r:RunRecord | null)=>r && ownsRun(owner,r) && (!r.scheduled || r.scheduled.pairedAt===owner.pairedAt)
   const show=async(s:Awaited<ReturnType<Scheduler['get']>>)=>{
@@ -70,11 +96,38 @@ Cron uses numeric five-field syntax, lists/ranges/steps, and traditional day/wee
     const interruptedRunIds=held.filter(r=>r.interrupted).map(r=>r.id)
     const failedReviewRunIds=held.filter(r=>!r.interrupted).map(r=>r.id)
     const next=s.enabled && !held.length ? await scheduler.pendingOccurrence(s) : null
-    return {...s,interruptedRunIds,failedReviewRunIds,nextEligibleAt:next===null ? null : new Date(next).toISOString(),
+    return {...s,executionType:executionType(s),preflightReceipt:await scheduler.preflightReceipt(s),interruptedRunIds,failedReviewRunIds,nextEligibleAt:next===null ? null : new Date(next).toISOString(),
       ...(held.length ? {recovery:'Inspect the failed run and explicitly edit this schedule to resume; pause/resume does not clear the stop.'} : {})}
   }
+  const scripts=new Scripts(config.controlDir)
   let result:unknown
-  if(action==='context'){
+  if(action==='script'){
+    const workspace=process.env.EZ_AGENT_WORKSPACE?.trim() || process.cwd()
+    if(id==='list')result=await scripts.list(owner)
+    else if(!scriptId)throw new Error('Script ID required')
+    else if(id==='show'){
+      const registration=await scripts.owned(scriptId,owner)
+      let current:string|null=null
+      try{current=await fileSha256((await workspaceEntry(workspace,registration.entry)).file)}catch{}
+      result={...registration,currentSha256:current,matchesRegistration:current===registration.sha256,
+        schedules:(await scheduler.list()).filter(s=>owned(s) && s.script?.id===scriptId).map(s=>s.id)}
+    }else if(id==='remove'){
+      const users=(await scheduler.list()).filter(s=>owned(s) && s.script?.id===scriptId).map(s=>s.id)
+      if(users.length)throw new Error(`Script is used by schedules ${users.join(', ')}; edit or remove them first`)
+      await scripts.remove(scriptId,owner);result={removed:scriptId}
+    }else if(id==='register' || id==='update'){
+      const previous=id==='update' ? await scripts.owned(scriptId,owner) : undefined
+      if(id==='register' && (!v.file || !v.interpreter))throw new Error('Register requires --file and --interpreter')
+      const timeout=v['timeout-seconds']===undefined ? previous?.timeoutSeconds ?? DEFAULT_SCRIPT_TIMEOUT_SECONDS : Number(v['timeout-seconds'])
+      result=await scripts.save({id:scriptId,owner,workspace,entry:v.file ? resolve(v.file) : previous!.entry,interpreter:v.interpreter ?? previous!.interpreter,
+        args:v.arg ?? previous?.args ?? [],timeoutSeconds:timeout,pathValue:executorEnvironment().PATH},id==='register')
+    }else throw new Error('Unknown script action; use --help')
+  }else if(action==='evidence'){
+    result=await callDeliverySocket(socketPath,{op:'evidence',payload:{
+      ...(caller ? {callerRunId:caller.id} : {}), ...(id ? {runId:id} : {}),
+      offset:Number(v.offset ?? 0),limit:Number(v.limit ?? 100),expected:v.expected,
+    }})
+  }else if(action==='context'){
     if(!caller)throw new Error('Context requires an active owner run')
     const origin=caller.scheduled?.originRunId ? await runs.get(caller.scheduled.originRunId) : null
     if(origin && !ownsFailureRun(origin))throw new Error('Source context is outside this owner binding')
@@ -95,18 +148,34 @@ Cron uses numeric five-field syntax, lists/ranges/steps, and traditional day/wee
     }
   }else if(action==='list')result=await Promise.all((await scheduler.list()).filter(owned).map(show))
   else if(action==='runs')result=(await runs.list()).filter(r=>r.scheduled && r.scheduled.pairedAt===owner.pairedAt && ownsRun(owner,r))
-  else if(action==='create' || action==='edit'){
+  else if(action==='trigger'){
+    if(!id || !v.key)throw new Error('Trigger requires SCHEDULE_ID and --key REQUEST_KEY')
+    if(Object.keys(v).some(key=>key!=='key'))throw new Error('Trigger uses saved task settings; overrides are not allowed')
+    const schedule=await scheduler.get(id)
+    if(!owned(schedule))throw new Error('Schedule ownership mismatch')
+    result=await callDeliverySocket(socketPath,{op:'triggerSchedule',payload:{scheduleId:id,revision:schedule.revision,key:v.key,...(caller ? {callerRunId:caller.id} : {})}})
+  }else if(action==='create' || action==='edit'){
     if(action==='edit' && (!id || !owned(await scheduler.get(id))))throw new Error('Unknown schedule')
     if(action==='create' && id && (await scheduler.list()).some(s=>s.id===id))throw new Error('Schedule exists; use edit')
     if([v.now,v.at,v.cron,v['every-seconds']].filter(Boolean).length!==1)throw new Error('Choose exactly one trigger')
-    if(Boolean(v.text)===Boolean(v['text-file']))throw new Error('Choose --text or --text-file')
+    if([v.text,v['text-file'],v.script].filter(Boolean).length!==1)throw new Error('Choose --text, --text-file or --script')
+    if(v.script && (v.cli || v.model || v.effort))throw new Error('Script schedules run no model; --cli, --model and --effort do not apply')
+    if(v.arg && !v.script)throw new Error('--arg applies to script schedules only')
     const start=v.start || new Date(Date.now()+1000).toISOString()
     const trigger:Trigger=v.now ? {at:new Date(Date.now()+1000).toISOString()} : v.at ? {at:v.at} :
       v.cron ? {cron:v.cron,timezone:v.timezone!,start,until:v.until} : {everySeconds:Number(v['every-seconds']),start,until:v.until}
+    if(v['clear-preflight'] && v['preflight-file']) throw Error('Choose one preflight operation')
     const previousSchedule = action === 'edit' ? await scheduler.get(id!) : undefined
+    const preflight = v['clear-preflight'] ? undefined : v['preflight-file'] ? JSON.parse(await readFile(v['preflight-file'],'utf8')) : previousSchedule?.preflight
     const origin = caller?.application ?? caller?.delivery
     const delivery = previousSchedule ? previousSchedule.delivery : (origin ? {bindingId:origin.bindingId,scope:origin.scope} : undefined)
     if (!delivery && !owner.telegramChatId) throw new Error('Create the schedule from an authenticated channel turn to bind its reply destination')
+    if (v.script) {
+      result=await show(await scheduler.save({id:id || 's_'+randomUUID(),name:v.name || v.script,preflight,
+        originRunId:previousSchedule?.originRunId ?? caller?.scheduled?.originRunId ?? caller?.id,delivery,text:'',when:v.when as 'unreviewed-failures' | undefined,trigger,enabled:true,owner,
+        script:{id:v.script,args:v.arg ?? []}},action==='create'))
+      console.log(JSON.stringify(result,null,2));return
+    }
     const previous = previousSchedule?.execution
     const state = await control.status()
     const selected = state.ai?.presets.find(p => p.id === state.ai!.selectedId)
@@ -114,6 +183,7 @@ Cron uses numeric five-field syntax, lists/ranges/steps, and traditional day/wee
     const preset = executionOverrides(base.cli, base, v.model, v.effort)
     if (!isPreset(preset)) throw new Error('Invalid task AI selection')
     result=await show(await scheduler.save({id:id || 's_'+randomUUID(),name:v.name || 'Task',
+      preflight,
       originRunId:previousSchedule?.originRunId ?? caller?.scheduled?.originRunId ?? caller?.id,delivery,text:v.text || await readFile(v['text-file']!,'utf8'),when:v.when as 'unreviewed-failures' | undefined,trigger,enabled:true,owner,
       execution:{sessionId:previous?.sessionId || randomUUID(),preset}},action==='create'))
   }else{

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,4 +1,5 @@
-import { assertEffort } from './model-policy.js'
+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'
 import { randomUUID, createHash } from 'node:crypto'
@@ -10,12 +11,17 @@ import { assertId, ownsRun } from './identity.js'
 import { 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,10 +128,21 @@ 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')
-    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')
+      assertScheduledModel(execution.preset.model)
+      assertEffort(execution.preset.effort, execution.preset.model, execution.preset.cli)
+      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')
@@ -128,12 +157,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.
@@ -159,6 +202,39 @@ export class Scheduler {
     try { await readFile(join(this.dir,assertId(runId)+'.cancel')); return true }
     catch (e) { if ((e as NodeJS.ErrnoException).code === 'ENOENT') return false; throw e }
   }
+  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')
+    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')
+    } else if (!owner.telegramChatId || owner.telegramChatId !== s.owner.telegramChatId || owner.telegramUserId !== s.owner.telegramUserId || (owner.telegramLinkedAt ?? owner.pairedAt) !== (s.owner.telegramLinkedAt ?? s.owner.pairedAt)) throw new Error('Schedule Telegram binding is unavailable')
+    const runId='r_schedule_manual_'+createHash('sha256').update(JSON.stringify([s.id,ownerId(owner),ownerEpoch(owner),assertId(key)])).digest('hex')
+    const existing=await runs.get(runId)
+    if (existing) {
+      if (!ownsRun(owner,existing) || existing.scheduled?.revision !== s.revision) throw new Error('Request key belongs to a different task revision or owner')
+      return existing
+    }
+    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()
+    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: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()) {
       if (!run.scheduled || run.status !== 'running') continue
@@ -180,6 +256,7 @@ export class Scheduler {
       try {
         const next = await this.pendingOccurrence(s)
         if (next === null || next > now) continue
+        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 &&
@@ -188,15 +265,24 @@ 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 {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,
-          scheduled:{id:s.id,revision:s.revision,dueAt,pairedAt:s.owner.pairedAt,...(s.originRunId?{originRunId:s.originRunId}:{})}})
+          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})
-      } catch { console.error('Schedule dispatch failed',s.id) }
+        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 }
+  }
+}