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

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,6 +150,7 @@ export class RunStore {
     taskId?: string
     application?: ApplicationOrigin
     delivery?: { bindingId: string; scope: string }
+    script?: ScriptRunRef
   }, exclusiveSchedule = false): Promise<RunRecord> {
     const store = runsFor(this.controlDir)
     if (input.id) {
@@ -172,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(),
     }
@@ -187,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)

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,26 +10,44 @@ 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'}, key:{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 capture the selected engine settings; edit preserves existing settings unless overridden.
@@ -66,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']>>)=>{
@@ -73,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')
@@ -108,14 +158,24 @@ Cron uses numeric five-field syntax, lists/ranges/steps, and traditional day/wee
     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)
@@ -123,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,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'
@@ -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,11 +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')
-    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')
+      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')
@@ -129,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.
@@ -163,7 +205,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 +220,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 +256,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 +265,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 {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') }
     }
   }