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

package/src/plugin-broker.mjs

@@ -6,7 +6,7 @@ import { createServer } from 'node:net';
 import { randomBytes, randomUUID, createHash } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { prepareCommand, registry, run as dockerRun, stewardOwned } from './plugins/manager.mjs';
+import { prepareCommand, registry, run as dockerRun, stewardOwned, publishBrokerPlugins } from './plugins/manager.mjs';
 
 const MAX_FRAME = 4 * 1024 * 1024;
 const MAX_ARGS = 100;
@@ -165,15 +165,7 @@ const writeReceipt = async (binding, receipt) => {
 // Installed plugin versions for relay status. Rewritten on broker start and
 // after every management call; the relay reads it without Docker access.
 // Failures stay local so a status snapshot never breaks plugin operations.
-const refreshBrokerPlugins = async binding => {
-  const r = await registry(binding.home);
-  const plugins = Object.values(r.plugins).map(record => ({ id: record.manifest.id, version: record.manifest.version }));
-  const file = path.join(binding.controlDir, 'plugin-broker-plugins.json');
-  const temporary = `${file}.${randomUUID()}.tmp`;
-  await fs.writeFile(temporary, JSON.stringify({ version: 1, at: new Date().toISOString(), plugins }) + '\n', { mode: 0o600, flag: 'wx' });
-  await fs.rename(temporary, file);
-  await stewardOwned(file);
-};
+const refreshBrokerPlugins = binding => publishBrokerPlugins(binding.home,binding.controlDir);
 
 const response = (socket, value) => {
   if (socket.destroyed || !socket.writable) return;
@@ -255,6 +247,7 @@ const invokePlugin = async (binding, request, signal, scheduledPreflight = false
     const command = await prepareCommand(binding.home, request.alias, request.args, {
       revision: request.revision,
       invocation: true,
+      signal,
       environment: { EZ_CONTROL_DIR: binding.controlDir, ...(scheduledPreflight ? {} : {EZ_RUN_ID: request.runId}), EZ_DELIVERY_SOCKET: process.env.EZ_DELIVERY_SOCKET ?? deliverySocketPath(binding.controlDir) },
     });
     try {
@@ -360,7 +353,7 @@ export async function servePluginBroker(binding, signal = new AbortController().
               const selected=recordForAlias(await registry(binding.home),check.alias);
               const result=await invokePlugin(binding,{alias:check.alias,args:check.args,revision:selected.record.revision,runId:`preflight_${request.scheduleId}`,id:randomUUID()},abort.signal,true);
               if(!result.ok || result.code!==0) throw Error('Scheduled plugin preflight unavailable');
-              values.push(JSON.parse(result.stdout));
+              try { values.push(JSON.parse(result.stdout)); } catch { throw Error('Scheduled plugin preflight returned invalid output'); }
             }
             response(socket,{version:1,id:request.id,ok:true,result:combinePreflight(values)});
             return;

package/src/plugins/manager.mjs

@@ -7,7 +7,8 @@ import { fileURLToPath } from 'node:url';
 import { createHash, randomUUID, randomBytes } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { callDeliverySocket } from '../delivery-socket-client.mjs';
-import { readFileSync, realpathSync } from 'node:fs';
+import { TOOLS_LINE } from '../tools-line.mjs';
+import { readFileSync, readlinkSync, realpathSync } from 'node:fs';
 
 const reserved = new Set(['status','updates','plugins','tools','message','owner','approval','react','setup','help','version']);
 const id = value => { if(typeof value !== 'string' || !/^[a-z][a-z0-9-]{0,39}$/.test(value)) throw Error('Invalid identifier'); return value; };
@@ -41,47 +42,43 @@ export async function stewardOwned(file) {
   const parent = await fs.stat(path.dirname(file));
   await fs.chown(file, parent.uid, parent.gid);
 }
-// Native instructions keep only the registry locator and one crucial routing
-// hint. Inventory and full scheduler usage are generated on read.
-export async function toolDiscoveryBlock(home,hostConfig) {
-  home=await fs.realpath(home);
-  let launcher=path.join(home,'bin','ez');
-  const config=hostConfig?{hostConfig}:await json(path.join(home,'config.json')).catch(error=>{if(error.code==='ENOENT')return undefined;throw error;});
-  if(config?.hostConfig) {
-    const host=await json(config.hostConfig);
-    if(host.isolation==='isolated') launcher='ez';
-  }
+// Retire the former `ez tools` footer once: replace the marked block with
+// TOOLS_LINE and leave every other byte untouched. The name is kept because
+// upgraders released before this change call it on the target package;
+// remove it when no installed core predates the change.
+export async function bindToolDiscovery(_home,workspace) {
+  workspace=await fs.realpath(workspace);
   const start='<!-- ez tools: begin -->',end='<!-- ez tools: end -->';
-  const block=start+'\nUse `'+launcher+'`; run it with `--help` or `tools list --details` to discover installed capabilities, and read the matching skill when needed.\nKeep the channel responsive: during a foreground owner turn, prefer `ezenciel-agents-schedule create --now ...` when work can continue independently. A `[schedule ...]` turn executes its assigned work directly and must not schedule it again.\n'+end;
-  if(Buffer.byteLength(block)>600)throw Error('Tool discovery guidance exceeds the 600-byte core budget');
-  return {block,start,end};
-}
-export async function bindToolDiscovery(home,workspace) {
-  home=await fs.realpath(home);workspace=await fs.realpath(workspace);
-  const {block,start,end}=await toolDiscoveryBlock(home);
   for(const name of ['AGENTS.md','AGENTS.override.md']) {
     const file=path.join(workspace,name);
     const stat=await fs.lstat(file).catch(e=>{if(e.code==='ENOENT')return null;throw e;});
-    if(!stat && name!=='AGENTS.md')continue;
-    if(stat && !stat.isFile())throw Error('Tool instructions must be a regular file');
-    const prior=stat?await fs.readFile(file,'utf8'):'';
+    if(!stat)continue;
+    if(!stat.isFile())throw Error('Tool instructions must be a regular file');
+    const prior=await fs.readFile(file,'utf8');
     const from=prior.indexOf(start),to=prior.indexOf(end);
-    if((from<0)!==(to<0)||(from>=0&&(to<from||prior.indexOf(start,from+start.length)>=0||prior.indexOf(end,to+end.length)>=0)))throw Error('Malformed tool discovery block');
-    const next=from<0?prior+'\n'+block+'\n':prior.slice(0,from)+block+prior.slice(to+end.length);
-    if(next===prior)continue;
+    if(from<0&&to<0)continue;
+    if((from<0)!==(to<0)||to<from||prior.indexOf(start,from+start.length)>=0||prior.indexOf(end,to+end.length)>=0)throw Error('Malformed tool discovery block');
+    const next=prior.slice(0,from)+(prior.includes(TOOLS_LINE)?'':TOOLS_LINE)+prior.slice(to+end.length);
     const tmp=file+'.'+randomUUID()+'.tmp';
     try {await fs.writeFile(tmp,next,{mode:0o600,flag:'wx'});await fs.rename(tmp,file);}finally{await fs.rm(tmp,{force:true});}
   }
 }
 const invocationDirectory = home => path.join(home,'command-invocations');
+// A lease pid is only meaningful inside the PID namespace that wrote it. The
+// isolated broker writes leases from its container, which the host cannot probe.
+const pidNamespace=(()=>{try{return readlinkSync('/proc/self/ns/pid');}catch{return undefined;}})();
 async function activeInvocations(home) {
   const directory=invocationDirectory(home),files=await fs.readdir(directory).catch(error=>{if(error.code==='ENOENT')return [];throw error;});
   for(const file of files) {
     if(!/^[0-9a-f-]{36}\.json$/.test(file))throw Error('Invalid command invocation lease; inspect before recovery');
-    const lease=await json(path.join(directory,file));
+    const lease=await json(path.join(directory,file)).catch(error=>{if(error.code==='ENOENT')return null;throw error;});
+    if(!lease)continue;
     if(!Number.isSafeInteger(lease.pid)||lease.pid<1||typeof lease.container!=='string'||!lease.container)throw Error('Invalid command invocation lease; inspect before recovery');
-    try {process.kill(lease.pid,0);return true;} catch(error) {if(error.code!=='ESRCH'&&error.code!=='EPERM')throw error;}
-    const state=await run(['container','inspect',lease.container],{capture:true});
+    const foreign=typeof lease.pidNamespace==='string'&&lease.pidNamespace!==pidNamespace;
+    if(!foreign) {try {process.kill(lease.pid,0);return true;} catch(error) {if(error.code!=='ESRCH'&&error.code!=='EPERM')throw error;}}
+    const state=await run(['container','inspect','--format','{{.State.Running}}',lease.container],{capture:true});
+    // Foreign leases: the call container's own state is the only liveness signal.
+    if(state.code===0&&foreign&&state.stdout.trim()==='true')return true;
     if(state.code===0)throw Error(`Stale command invocation lease; inspect container ${lease.container} before recovery`);
     if(!/No such (?:object|container)/i.test(state.stderr+state.stdout))throw Error('Unable to verify a stale command invocation lease; inspect Docker before recovery');
     await fs.rm(path.join(directory,file));
@@ -90,25 +87,35 @@ async function activeInvocations(home) {
 }
 async function invocationLease(home,container) {
   const directory=invocationDirectory(home);await privateDir(directory);
-  const file=path.join(directory,randomUUID()+'.json');await fs.writeFile(file,JSON.stringify({pid:process.pid,container}),{mode:0o600,flag:'wx'});
+  const file=path.join(directory,randomUUID()+'.json');await fs.writeFile(file,JSON.stringify({pid:process.pid,container,...(pidNamespace?{pidNamespace}:{})}),{mode:0o600,flag:'wx'});
   await stewardOwned(file);
   return async()=>{await fs.rm(file,{force:true});};
 }
-export async function locked(home, fn, {allowInvocations=false, waitMs=0}={}) {
+export async function locked(home, fn, {allowInvocations=false, waitMs=0, upgradeWaitMs=0, drainInvocations=false, signal}={}) {
   const lock = path.join(home,'registry.lock');
   let handle;
-  const deadline=Date.now()+waitMs;
+  const started=Date.now();
   while(!handle) {
+    signal?.throwIfAborted();
     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');
+      const owner=await json(lock).catch(()=>null);
+      const limit=owner?.kind==='plugin-upgrade'&&upgradeWaitMs?upgradeWaitMs:waitMs;
+      if(Date.now()-started>=limit)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');
+    await handle.writeFile(JSON.stringify({pid:process.pid,...(drainInvocations?{kind:'plugin-upgrade'}:{})}));
+    // Keep admission closed while already-started calls release their leases.
+    // This is a lifecycle barrier, not an agent-turn drain or a command retry.
+    while(!allowInvocations&&await activeInvocations(home)) {
+      if(!drainInvocations)throw Error('Plugin commands are active; retry the registry or lifecycle change after they finish');
+      signal?.throwIfAborted();
+      await new Promise(resolve=>setTimeout(resolve,25));
+    }
+    signal?.throwIfAborted();
     return await fn();
   }
   finally { await handle.close(); await fs.rm(lock); }
@@ -139,9 +146,11 @@ export async function snapshot(source) {
   return {source,files,manifest,deployment,sharedRevisions,revision:`sha256:${digest.digest('hex')}`};
 }
 export function validate(m,d,files) {
-  keys(m,['schemaVersion','id','version','description','commands','skills']);
+  keys(m,['schemaVersion','id','version','description','commands','skills','example']);
   if(m.schemaVersion!==1 || (typeof m.version!=='string' || !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(m.version))) throw Error('Unsupported manifest version');
   id(m.id); strings(m.skills);
+  // One representative call shown by `tools list --details`; usage stays in --help/skill.
+  if(m.example!==undefined && (typeof m.example!=='string' || m.example.length>160 || /[\0-\x1f\x7f]/.test(m.example) || !Object.hasOwn(m.commands||{},m.example.split(' ')[0]))) throw Error('Manifest example must be one line of at most 160 characters starting with a declared command');
   keys(d,['schemaVersion','services','commands','exports',...(d.schemaVersion>=2?['secrets']:[]),...(d.schemaVersion===3?['sharedServices']:[])]);
   if(![1,2,3].includes(d.schemaVersion) || !d.services || !d.commands) throw Error('Unsupported deployment descriptor');
   for(const [name,s] of Object.entries(d.services)) {
@@ -386,11 +395,13 @@ export function run(argv,{capture=false,container,signal,stdin,onStdout,onStart,
     child.once('close',async(code,childSignal)=>{process.off('SIGTERM',term);process.off('SIGINT',int);
       clearTimeout(killTimer);
       clearTimeout(timeout);signal?.removeEventListener('abort',term);
-      if(cancelled&&container) {
+      // --rm only removes a container that ran. Compose stopping between
+      // create and start (cancelled, signalled or failed) strands it Created.
+      if(container&&(cancelled||code!==0)) {
         try {
           await removeCommandContainer(container);
         } catch(error) {
-          const uncertain=error instanceof Error?error:Error('Cancelled command container cleanup failed');
+          const uncertain=error instanceof Error?error:Error('Command container cleanup failed');
           uncertain.containerCleanupUncertain=true;return reject(uncertain);
         }
       }
@@ -398,7 +409,7 @@ export function run(argv,{capture=false,container,signal,stdin,onStdout,onStart,
       resolve({code:cancelled?130:code??(childSignal?130:1),stdout,stderr});});
   });
 }
-// Compose --rm can race cancellation. Confirm disappearance instead of treating
+// Compose --rm can race this cleanup. Confirm disappearance instead of treating
 // Docker's in-progress removal as either failure or completed cleanup.
 export async function removeCommandContainer(container,execute=run) {
   const cleanup=await execute(['container','rm','--force',container],{capture:true});
@@ -411,7 +422,7 @@ export async function removeCommandContainer(container,execute=run) {
       await new Promise(resolve=>setTimeout(resolve,100));
     }
   }
-  throw Error(`Cancelled command container cleanup failed: ${cleanup.stderr||cleanup.stdout}`);
+  throw Error(`Command container cleanup failed: ${cleanup.stderr||cleanup.stdout}`);
 }
 
 async function checked(args) {
@@ -474,8 +485,16 @@ export async function registry(home) {
   for(const [alias,plugin] of Object.entries(r.commands)) if(!r.plugins[plugin]?.deployment?.commands?.[alias]) throw Error('Corrupt command registry');
   return r;
 }
+// Relay status reads this generated inventory without Docker/registry access.
+export async function publishBrokerPlugins(home,controlDir) {
+  const r=await registry(home);
+  const plugins=Object.values(r.plugins).map(record=>({id:record.manifest.id,version:record.manifest.version}));
+  const file=path.join(controlDir,'plugin-broker-plugins.json');
+  await atomic(file,{version:1,at:new Date().toISOString(),plugins});
+  await stewardOwned(file);
+}
 // The lock protects admission and compose refresh, never a persistent connection.
-export async function prepareCommand(home,alias,args,{revision,exclude,publish,invocation=false,environment=process.env}={}) {
+export async function prepareCommand(home,alias,args,{revision,exclude,publish,invocation=false,environment=process.env,signal}={}) {
   strings(args);
   return locked(home,async()=>{
     const config=await json(path.join(home,'config.json')),r=await registry(home);
@@ -505,13 +524,12 @@ 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,waitMs:5000});
+  },{allowInvocations:true,waitMs:5000,upgradeWaitMs:invocation?300000:0,signal});
 }
 export async function init(home,workspace,catalogFile,hostConfig,standalone=false) {
   if(standalone && hostConfig) throw Error('Standalone setup cannot bind a relay host config');
   if(typeof home!=='string'||typeof workspace!=='string'||!path.isAbsolute(home)||!path.isAbsolute(workspace)||/[\r\n\0$:,]/.test(home+workspace)) throw Error('Explicit absolute home/workspace required');
   workspace=await fs.realpath(workspace);await privateDir(home);home=await fs.realpath(home);if(hostConfig)hostConfig=await fs.realpath(hostConfig);
-  await toolDiscoveryBlock(home,hostConfig);
   if(await fs.lstat(path.join(home,'registry.json')).catch(()=>null)) throw Error('Registry already exists; refusing replacement');
   catalogFile=path.resolve(catalogFile||fileURLToPath(new URL('../../default-plugins.json',import.meta.url)));
   const sources=await json(catalogFile);
@@ -544,7 +562,6 @@ export async function init(home,workspace,catalogFile,hostConfig,standalone=fals
       agent.binDir=bin;agent.toolsHome=home;await atomic(hostConfig,host);
     }
   });
-  await bindToolDiscovery(home,workspace);
   if(hostConfig && path.basename(hostConfig)==='host-executor.json') await (await import('../updates/binding.mjs')).bindUpdates(home,hostConfig);
   return {ok:true,launcher:path.join(home,'bin','ez'),workspace};
 }
@@ -632,12 +649,17 @@ export async function main(args) {
       return emit({plugin:name,revision:record.revision,path:skill,content:await fs.readFile(file,'utf8')});
     }
     if(action==='list') {
-      if(group==='tools' && args.length===1 && args[0]==='--details')return emit(Object.fromEntries(Object.entries(r.plugins).map(([name,p])=>[name,{
-        description:typeof p.manifest.description==='string'?p.manifest.description.replace(/\s+/g,' ').trim().slice(0,200):'',
-        commands:Object.keys(p.manifest.commands).map(alias=>`ez ${alias} --help`),
-        skills:p.manifest.skills.map(skill=>path.join(p.source,skill)),
-        skillReads:p.manifest.skills.map(skill=>['ez','tools','skill',name,skill]),
-      }])));
+      // Self-sufficient index: aliases, purpose, skill and one call per plugin.
+      if(group==='tools' && args.length===1 && args[0]==='--details')return emit(Object.fromEntries(Object.entries(r.plugins).map(([name,p])=>{
+        const aliases=Object.keys(p.manifest.commands);
+        return [name,{
+          aliases,
+          purpose:typeof p.manifest.description==='string'?p.manifest.description.replace(/\s+/g,' ').trim().slice(0,200):'',
+          skills:p.manifest.skills.map(skill=>path.join(p.source,skill)),
+          skillReads:p.manifest.skills.map(skill=>['ez','tools','skill',name,skill]),
+          example:`ez ${p.manifest.example ?? `${aliases[0]} --help`}`,
+        }];
+      })));
       if(args.length)throw Error('Use tools list [--details] or plugins list');
       return emit(group==='tools'?r.commands:r.plugins);
     }

package/src/runs.ts

@@ -1,12 +1,16 @@
 import { validApplicationOrigin, type ApplicationOrigin } from './application-origin.js'
 import { type FailureEvidence, type FailureReview, validFailureReview, failureStamp, failureEvidence } from './failure.js'
 import { randomBytes } from 'node:crypto'
+import { readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { isHostRunId } from './host-executor-protocol.js'
 import { validOrigin, type ExternalOrigin } from './event-sources.js'
 import { normalizeReactionEmoji } from './reaction.js'
 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 { isExecutionChoice, type AiPreset, type ExecutionChoice } from './ai.js'
+import type { SetupAttempt } from './setup-fallback.js'
 import type { ScriptRunRef } from './scripts.js'
 import {authorizeDeliveryContext,currentDeliveryOwner,type DeliveryContext} from './delivery-context.mjs'
 
@@ -32,7 +36,11 @@ export type RunRecord = {
   pid?: number
   blockReason?: string
   execution?: ExecutionChoice
+  // Ordered task setups tried for this occurrence; the last one is active.
+  attempts?: SetupAttempt[]
   replyOnly?: boolean
+  // Silent end-of-conversation turn in a replaced chat session (session-close.ts).
+  sessionClose?: true
   exitCode?: number | null
   failureReason?: string
   failure?: FailureEvidence
@@ -83,9 +91,10 @@ export const retainedOutbox = (controlDir: string): StoredOutboxItem[] => [...ou
 // 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.
-// A restart drops in-flight runs and queued items by design; in-flight sends
-// report unknown rather than claiming success. Long-lived relays cap retained
-// terminal records so memory stays bounded.
+// A restart drops in-flight runs and queued items by design (except handed-off
+// host-transport runs, below); in-flight sends report unknown rather than
+// claiming success. Long-lived relays cap retained terminal records so memory
+// stays bounded.
 const MAX_TERMINAL_RUNS = 2000
 const MAX_TERMINAL_OUTBOX = 2000
 
@@ -129,8 +138,57 @@ const pruneTerminals = (controlDir: string): void => {
   }
 }
 
+// The setup the current attempt runs with: the latest recorded attempt, else the
+// saved choice. Only a setup saved on the task itself is ever admitted.
+export const activeSetup = (run: Pick<RunRecord, 'attempts' | 'execution'>): AiPreset | undefined => {
+  if (!run.execution) return undefined
+  const preset = [...run.attempts ?? []].reverse().find(attempt => attempt.outcome !== 'skipped')?.preset ?? run.execution.preset
+  return [run.execution.preset, ...run.execution.fallbacks ?? []].find(candidate => JSON.stringify(candidate) === JSON.stringify(preset))
+}
+
 export const newRunId = (): string => `r_${Date.now().toString(36)}_${randomBytes(3).toString('hex')}`
 
+// The one exception to memory-only runs: a graceful relay stop hands its
+// running host-transport runs to the next relay, whose executors outlive it.
+// The next relay adopts and watches them; it never relaunches one.
+const handoffFile = (controlDir: string): string => join(controlDir, 'run-handoff.json')
+const handedRun = (value: unknown): value is RunRecord => {
+  const run = value as RunRecord
+  return Boolean(run && typeof run === 'object' && (run.version === 1 || run.version === 2) && typeof run.id === 'string' && isHostRunId(run.id) &&
+    run.status === 'running' && Array.isArray(run.texts) && run.texts.every(text => typeof text === 'string') && Number.isFinite(Date.parse(run.createdAt)) &&
+    (run.execution === undefined || isExecutionChoice(run.execution)) && (run.scheduled === undefined || validScheduledOrigin(run.scheduled)) &&
+    (run.external === undefined || validOrigin(run.external)) && (run.application === undefined || validApplicationOrigin(run.application)))
+}
+
+export const saveRunHandoff = async (controlDir: string, records: RunRecord[]): Promise<void> => {
+  const file = handoffFile(controlDir), temporary = `${file}.${process.pid}.tmp`
+  await writeFile(temporary, JSON.stringify({ version: 1, writtenAt: new Date().toISOString(), runs: records }), { mode: 0o600 })
+  await rename(temporary, file)
+}
+
+const HANDOFF_MAX_AGE_MS = 24 * 60 * 60 * 1000
+
+// Reads and removes the record. An unreadable, corrupt or stale record adopts
+// nothing: those executors finish unobserved, like a restart without handoff.
+export const takeRunHandoff = async (controlDir: string, now = Date.now()): Promise<RunRecord[]> => {
+  try {
+    let raw: string
+    try { raw = await readFile(handoffFile(controlDir), 'utf8') }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []; throw error }
+    await rm(handoffFile(controlDir))
+    const value = JSON.parse(raw) as { version?: unknown; writtenAt?: unknown; runs?: unknown }
+    const age = now - Date.parse(typeof value.writtenAt === 'string' ? value.writtenAt : '')
+    if (value.version !== 1 || !(age >= -60_000 && age <= HANDOFF_MAX_AGE_MS)) throw new Error('Invalid or stale run handoff')
+    if (!Array.isArray(value.runs) || value.runs.length > 100) throw new Error('Invalid run handoff')
+    const valid = value.runs.filter(handedRun)
+    if (valid.length !== value.runs.length) console.error('Ignoring invalid handed-off runs', value.runs.length - valid.length)
+    return [...new Map(valid.map(run => [run.id, run])).values()]
+  } catch (error) {
+    console.error('Ignoring unreadable run handoff', error instanceof Error ? error.message : 'Unknown error')
+    return []
+  }
+}
+
 export class RunStore {
   constructor(private readonly controlDir: string) {}
 
@@ -151,6 +209,7 @@ export class RunStore {
     application?: ApplicationOrigin
     delivery?: { bindingId: string; scope: string }
     script?: ScriptRunRef
+    sessionClose?: true
   }, exclusiveSchedule = false): Promise<RunRecord> {
     const store = runsFor(this.controlDir)
     if (input.id) {
@@ -183,6 +242,7 @@ export class RunStore {
       delivery: input.delivery,
       scheduled: input.scheduled,
       ...(input.script ? { script: input.script } : {}),
+      ...(input.sessionClose ? { sessionClose: true as const } : {}),
       status: 'queued',
       createdAt: new Date().toISOString(),
     }
@@ -196,9 +256,18 @@ export class RunStore {
     return runsFor(this.controlDir).get(id) ?? null
   }
 
+  // Re-admit a run from the previous relay's handoff; its executor is already running.
+  async adopt(run: RunRecord): Promise<RunRecord> {
+    if (!handedRun(run)) throw new Error('Invalid handed-off run')
+    const existing = runsFor(this.controlDir).get(run.id)
+    if (existing && existing.status !== 'running') throw new Error('Handed-off run already settled')
+    runsFor(this.controlDir).set(run.id, run)
+    return run
+  }
+
   async patch(
     id: string,
-    change: Partial<Pick<RunRecord, 'status' | 'startedAt' | 'endedAt' | 'pid' | 'nativeSessionId' | 'interrupted' | 'blockReason' | 'backendSubmitted' | 'replyOnly' | 'exitCode' | 'failureReason' | 'failure' | 'failureReview' | 'externalReleased' | 'output' | 'timedOut'>>,
+    change: Partial<Pick<RunRecord, 'status' | 'startedAt' | 'endedAt' | 'pid' | 'nativeSessionId' | 'interrupted' | 'blockReason' | 'backendSubmitted' | 'replyOnly' | 'exitCode' | 'failureReason' | 'failure' | 'failureReview' | 'externalReleased' | 'output' | 'timedOut' | 'attempts'>>,
   ): Promise<RunRecord> {
     const store = runsFor(this.controlDir)
     const run = store.get(id)

package/src/schedule-cli.ts

@@ -8,18 +8,36 @@ import { ControlStore, sameOwner } from './control-state.js'
 import { ApplicationBindings } from './application-channel.js'
 import type { RunRecord } from './runs.js'
 import { callDeliverySocket, socketPathFor } from './delivery-socket.js'
-import { initialPreset, isPreset } from './ai.js'
+import { initialPreset, isPreset, presetLabel, type AiPreset } from './ai.js'
 import { executionOverrides } from './model-policy.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 { provisionedHome } from './auth-profile.js'
 import { ownsRun } from './identity.js'
 import { type Trigger } from './schedule-time.js'
 
+// Each fallback selects its own native engine, credential home and model.
+const fallbackSetup = (spec: string, index: number): AiPreset => {
+  const fields = Object.fromEntries(spec.split(',').map(part => {
+    const at = part.indexOf('=')
+    if (at < 1) throw new Error('Fallback uses cli=EXECUTOR,model=MODEL[,auth-profile=NAME][,effort=EFFORT][,provider=ID]')
+    return [part.slice(0, at), part.slice(at + 1)]
+  }))
+  if (Object.keys(fields).some(key => !['cli','model','auth-profile','effort','provider'].includes(key)) || !fields.cli || !fields.model)
+    throw new Error('Fallback uses cli=EXECUTOR,model=MODEL[,auth-profile=NAME][,effort=EFFORT][,provider=ID]')
+  const base = initialPreset(fields.cli)
+  const preset = executionOverrides(base.cli, {...base, ...(fields.provider ? {provider: fields.provider} : {}),
+    ...(fields['auth-profile'] !== undefined ? {authProfile: fields['auth-profile']} : {})}, fields.model, fields.effort)
+  const named = {...preset, id: `fallback-${index + 1}`, name: presetLabel(preset).slice(0, 80)}
+  if (!isPreset(named)) throw new Error('Invalid fallback setup')
+  return named
+}
+
 async function main() {
   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'},
+    cli:{type:'string'}, 'auth-profile':{type:'string'}, model:{type:'string'}, effort:{type:'string'}, fallback:{type:'string',multiple:true}, 'clear-fallbacks':{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'},
@@ -31,12 +49,14 @@ async function main() {
   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 | --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>]
+    [--cli EXECUTOR] [--auth-profile NAME] [--model MODEL] [--effort <native-effort>]
+    [--fallback cli=EXECUTOR,model=MODEL[,auth-profile=NAME][,effort=EFFORT][,provider=ID] ... | --clear-fallbacks]
     [--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).
+Execution types: agent (prompt, engine, auth profile, model, effort) or script (registered script ID and saved arguments).
+--auth-profile runs a Codex/Claude task under that provisioned login (ezenciel-agents-ai profiles); --cli alone uses the default login.
 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.
@@ -52,6 +72,14 @@ Failures default to unreviewed owner runs. Review records a diagnosis; it never
 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.
 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.
+Fallbacks run in the saved order only when the previous setup's CLI is unavailable or its provider
+rejected the turn before any work began, including an unavailable login. A Claude usage limit the run ended on
+after work began continues on the next setup in a fresh session, told the stopped session and that its work may be
+partly applied. Account/organization access denial, unknown errors, cancellation and other failures after work
+began stop the chain; nothing is replayed.
+A login or quota rejection skips later setups of the same native login profile
+or upstream provider. Named profiles must be owner-provisioned logins for separate accounts; Ez never enables overage.
+The run records each attempt, setup, failure category and any reported reset time.
 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.
@@ -159,7 +187,8 @@ Cron uses numeric five-field syntax, lists/ranges/steps, and traditional day/wee
     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([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.script && (v.cli || v['auth-profile'] || v.model || v.effort || v.fallback || v['clear-fallbacks']))throw new Error('Script schedules run no model; --cli, --auth-profile, --model, --effort and --fallback do not apply')
+    if(v.fallback && v['clear-fallbacks'])throw new Error('Choose --fallback or --clear-fallbacks')
     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} :
@@ -180,12 +209,15 @@ Cron uses numeric five-field syntax, lists/ranges/steps, and traditional day/wee
     const state = await control.status()
     const selected = state.ai?.presets.find(p => p.id === state.ai!.selectedId)
     const base = v.cli ? initialPreset(v.cli) : previous?.preset || selected || initialPreset(process.env.EZ_EXECUTOR_CLI || 'codex')
-    const preset = executionOverrides(base.cli, base, v.model, v.effort)
+    const preset = executionOverrides(base.cli, v['auth-profile'] === undefined ? base : {...base, authProfile:v['auth-profile']}, v.model, v.effort)
     if (!isPreset(preset)) throw new Error('Invalid task AI selection')
+    const fallbacks = v['clear-fallbacks'] ? undefined : v.fallback ? v.fallback.map(fallbackSetup) : previous?.fallbacks
+    for (const setup of [preset, ...fallbacks ?? []])
+      if (setup.authProfile !== undefined) await provisionedHome(config.controlDir, setup.cli, setup.authProfile)
     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'))
+      execution:{sessionId:previous?.sessionId || randomUUID(),preset,...(fallbacks ? {fallbacks} : {})}},action==='create'))
   }else{
     if(!id)throw new Error('ID required')
     if(action==='cancel'){

package/src/scheduled-tasks.ts

@@ -1,5 +1,6 @@
 import { executionDefaults } from './model-policy.js'
-import { presetLabel } from './ai.js'
+import { presetLabel, type AiPreset } from './ai.js'
+import { AUTH_PROFILE_CLIS } from './auth-profile.js'
 import type { Owner } from './control-state.js'
 import type { Schedule, ActiveSchedule } from './scheduler.js'
 
@@ -11,15 +12,45 @@ 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 = (execution: NonNullable<Schedule['execution']>) => {
-  try { return executionDefaults(execution.preset.cli, execution.preset) }
-  catch { return execution.preset }
+const displayedPreset = (preset: AiPreset) => {
+  try { return executionDefaults(preset.cli, preset) }
+  catch { return preset }
+}
+
+const setupLabel = (preset: AiPreset) => {
+  const label = presetLabel(displayedPreset(preset))
+  return AUTH_PROFILE_CLIS.includes(preset.cli) && preset.authProfile === undefined
+    ? `${preset.cli} (default login)${label.slice(preset.cli.length)}` : label
 }
 
 // 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!))
+  : [schedule.execution!.preset, ...schedule.execution!.fallbacks ?? []].map(setupLabel).join(' → ')
+
+const every = (count: number, unit: string) => `Every ${count === 1 ? '' : `${count} `}${unit}${count === 1 ? '' : 's'}`
+const frequency = (schedule: Schedule) => {
+  const trigger = schedule.trigger
+  if ('at' in trigger) return 'Once'
+  if ('everySeconds' in trigger) {
+    const seconds = trigger.everySeconds
+    for (const [size, unit] of [[86400,'day'],[3600,'hour'],[60,'minute']] as const)
+      if (seconds % size === 0) return every(seconds / size, unit)
+    return every(seconds, 'second')
+  }
+  const cron = trigger.cron.trim().replace(/\s+/g, ' ')
+  const [minute, hour, day, month, weekday] = cron.split(' ')
+  let label = `Cron ${cron}`
+  if (`${hour} ${day} ${month} ${weekday}` === '* * * *') {
+    const step = /^\*\/(\d+)$/.exec(minute)
+    if (minute === '*') label = 'Every minute'
+    else if (step && Number(step[1]) > 0 && 60 % Number(step[1]) === 0) label = every(Number(step[1]), 'minute')
+    else if (/^\d+$/.test(minute)) label = `Hourly at :${minute.padStart(2,'0')}`
+  } else if (/^\d+$/.test(minute) && /^\d+$/.test(hour) && day === '*' && month === '*' && ['*','1-5'].includes(weekday)) {
+    label = `${weekday === '*' ? 'Daily' : 'Weekdays'} at ${hour.padStart(2,'0')}:${minute.padStart(2,'0')}`
+  }
+  return `${label} · ${trigger.timezone}`
+}
 
 const weekdays = ['Sun','Mon','Tue','Wed','Thu','Fri','Sat']
 const months = ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec']
@@ -52,8 +83,8 @@ 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) =>
-    `${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)}`
+  return [`📅 Scheduled tasks · ${owned.length} active`, 'Next/last times UTC. Use /tasks 1 for task details.', ...owned.map((schedule, index) =>
+    `${index + 1} · ${schedule.name}\n  ${currentState(schedule)}\n  Schedule · ${frequency(schedule)}\n  Next · ${schedule.nextAt === null ? '—' : time(schedule.nextAt)}\n  Last · ${lastRun(schedule)}\n  Execution · ${engineLabel(schedule)}\n  ${preview(schedule)}`
   )].join('\n\n')
 }
 
@@ -64,13 +95,16 @@ export const scheduledTaskDetailText = (schedule: ActiveSchedule, number: number
     `📅 ${number}${total === undefined ? '' : ` of ${total}`} · ${schedule.name}`,
     currentState(schedule),
     '',
+    'Schedule',
+    frequency(schedule),
+    '',
     'Next run',
     schedule.nextAt === null ? '—' : time(schedule.nextAt),
     '',
     'Last run',
     lastRun(schedule),
     '',
-    schedule.script ? 'Execution' : 'Engine',
+    'Execution path',
     engineLabel(schedule),
     '',
     schedule.script ? 'Script arguments' : 'Instructions',