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

package/src/setup-fallback.ts

@@ -1,11 +1,12 @@
 import { presetLabel, presetProvider, type AiPreset, type ExecutionChoice } from './ai.js'
 
 // Ordered task setups for one scheduled occurrence. Core advances only on typed
-// evidence that the engine never started work: a missing CLI or a provider
-// rejection before any model output or tool item. Anything else stops the chain.
-export type StartupCategory = 'cli-unavailable' | 'quota' | 'provider-rejected' | 'access-denied'
+// evidence: a missing CLI or a provider rejection before any model output or
+// tool item, or a usage limit the run ended on after work began (continued in a
+// fresh session that is told so). Anything else stops the chain.
+export type StartupCategory = 'cli-unavailable' | 'login-unavailable' | 'quota' | 'provider-rejected' | 'access-denied'
 export type StartupRejection = { category: StartupCategory; resetAt?: string }
-export type AttemptCategory = StartupCategory | 'after-work-began' | 'uncertain' | 'same-quota-scope'
+export type AttemptCategory = StartupCategory | 'quota-after-work-began' | 'after-work-began' | 'uncertain' | 'same-quota-scope' | 'same-login-scope'
 export type SetupAttempt = {
   preset: AiPreset
   quotaScope: string
@@ -13,36 +14,54 @@ export type SetupAttempt = {
   category?: AttemptCategory
   resetAt?: string
   exitCode?: number | null
+  sessionId?: string
   startedAt?: string
   endedAt?: string
 }
 
-const categories: StartupCategory[] = ['cli-unavailable', 'quota', 'provider-rejected', 'access-denied']
-export const advances = (rejection?: StartupRejection): boolean => Boolean(rejection && rejection.category !== 'access-denied')
+const categories: StartupCategory[] = ['cli-unavailable', 'login-unavailable', 'quota', 'provider-rejected', 'access-denied']
+
+// A failed attempt's category and reset time, and whether the occurrence
+// continues on the next setup. Once work began only a quota limit the run ended
+// on continues; access denial, other failures and unknown outcomes stop.
+export const attemptFailure = ({ workBegan, rejection }: { workBegan: boolean; rejection?: StartupRejection }): { category: AttemptCategory; resetAt?: string; continues: boolean } => {
+  const resetAt = rejection?.resetAt ? { resetAt: rejection.resetAt } : {}
+  if (!workBegan) return rejection ? { category: rejection.category, ...resetAt, continues: rejection.category !== 'access-denied' } : { category: 'uncertain', continues: false }
+  return rejection?.category === 'quota' ? { category: 'quota-after-work-began', ...resetAt, continues: true } : { category: 'after-work-began', continues: false }
+}
+
+// Transport fact for a setup that continues an occurrence after an earlier setup
+// stopped at its usage limit once work had begun. Facts only, no guidance.
+export const continuationLine = (runId: string, attempts: SetupAttempt[]): string | undefined => {
+  const limited = attempts.filter(a => a.category === 'quota-after-work-began')
+  return limited.length ? `[run ${runId} continues: ${limited.map(a => `${presetLabel(a.preset)} began work in native session ${a.sessionId} and stopped at its usage limit${a.resetAt ? ` (resets ${a.resetAt})` : ''}`).join('; ')}. That work may be partly applied.]` : undefined
+}
 
 export const setupCandidates = (execution: ExecutionChoice): AiPreset[] => [execution.preset, ...(execution.fallbacks ?? [])]
 
-// Allowance is metered per provider account, not per credential file. Setups on
-// the same native client share a scope; OpenCode/Pi share their upstream
-// provider. A different credential alone never proves independent allowance.
+// The owner provisions native profiles for separate provider accounts. Models
+// in one login share its quota scope; another named login may be tried once.
+// OpenCode/Pi still share their upstream provider scope.
 export const quotaScope = (preset: AiPreset): string => {
   if (['opencode', 'pi'].includes(preset.cli)) {
     const provider = preset.cli === 'pi' ? preset.model?.split('/')[0] : presetProvider(preset)
     return provider ? `provider:${provider}` : preset.cli
   }
-  return preset.cli === 'codex-gui' ? 'codex' : preset.cli
+  const cli = preset.cli === 'codex-gui' ? 'codex' : preset.cli
+  return preset.authProfile ? `${cli}@${preset.authProfile}` : cli
 }
 
-// The next untried setup, skipping those whose quota scope already rejected
-// this occurrence. Each candidate is tried at most once.
+// The next untried setup, skipping a login that already rejected authentication
+// or reached its quota in this occurrence. Each candidate is tried at most once.
 export const nextSetup = (candidates: AiPreset[], attempts: SetupAttempt[]): { skipped: SetupAttempt[]; preset?: AiPreset } => {
-  const exhausted = new Set(attempts.filter(a => a.category === 'quota').map(a => a.quotaScope))
+  const exhausted = new Map(attempts.filter(a => ['quota', 'quota-after-work-began', 'login-unavailable'].includes(a.category!))
+    .map(a => [a.quotaScope, a.category === 'login-unavailable' ? 'same-login-scope' as const : 'same-quota-scope' as const]))
   const skipped: SetupAttempt[] = []
   for (const preset of candidates.slice(attempts.length)) {
     const scope = quotaScope(preset)
     if (!exhausted.has(scope)) return { skipped, preset }
     const at = new Date().toISOString()
-    skipped.push({ preset, quotaScope: scope, outcome: 'skipped', category: 'same-quota-scope', startedAt: at, endedAt: at })
+    skipped.push({ preset, quotaScope: scope, outcome: 'skipped', category: exhausted.get(scope), startedAt: at, endedAt: at })
   }
   return { skipped }
 }
@@ -57,20 +76,23 @@ const epochSeconds = (value: unknown): string | undefined =>
 
 const claudeErrors: Record<string, StartupCategory> = {
   rate_limit: 'quota', billing_error: 'quota',
-  authentication_failed: 'access-denied', oauth_org_not_allowed: 'access-denied', account_on_hold: 'access-denied',
+  authentication_failed: 'login-unavailable', oauth_org_not_allowed: 'access-denied', account_on_hold: 'access-denied',
   verification_required: 'access-denied', cloud_credential_error: 'access-denied',
   overloaded: 'provider-rejected', server_error: 'provider-rejected', model_not_found: 'provider-rejected', invalid_request: 'provider-rejected',
 }
 
+const httpRejection = (status: unknown): StartupCategory | undefined =>
+  typeof status !== 'number' ? undefined : status === 401 ? 'login-unavailable' : status === 429 ? 'quota' :
+    status === 403 ? 'access-denied' : [400, 404].includes(status) || status >= 500 ? 'provider-rejected' : undefined
+
 // Codex app-server `codexErrorInfo` of a failed turn.
 export const codexRejection = (info: unknown): StartupCategory | undefined => {
   if (info === 'usageLimitExceeded' || info === 'rateLimitExceeded') return 'quota'
-  if (info === 'unauthorized') return 'access-denied'
+  if (info === 'unauthorized') return 'login-unavailable'
   if (['serverOverloaded', 'internalServerError', 'badRequest', 'flexUnavailable'].includes(info as string)) return 'provider-rejected'
   if (!info || typeof info !== 'object') return undefined
   const status = (Object.values(info)[0] as { httpStatusCode?: unknown } | undefined)?.httpStatusCode
-  if (typeof status !== 'number') return undefined
-  return status === 429 ? 'quota' : [401, 403].includes(status) ? 'access-denied' : [400, 404].includes(status) || status >= 500 ? 'provider-rejected' : undefined
+  return httpRejection(status)
 }
 
 // The latest reset among exhausted Codex rate-limit windows.
@@ -85,29 +107,44 @@ export const startupLine = (state: { workBegan: boolean; rejection?: StartupReje
 // Reads structured stdout only: Ez transport summaries (`ez.startup`) and
 // Claude stream-json envelopes. Model text is never inspected. Any event that
 // is not known pre-work metadata counts as work, so ambiguity never advances.
+// The rejection is the one the run ended on: later work supersedes it, except
+// an access denial, which always stops the chain.
 export const startupObserver = () => {
   let buffer = '', workBegan = false, rejection: StartupRejection | undefined
+  const reject = (value: StartupRejection) => { if (rejection?.category !== 'access-denied') rejection = value }
+  const work = () => { workBegan = true; if (rejection?.category !== 'access-denied') rejection = undefined }
   const line = (text: string) => {
     if (!text.trim()) return
     let event: any
-    try { event = JSON.parse(text) } catch { workBegan = true; return }
+    try { event = JSON.parse(text) } catch { work(); return }
+    // A summary is the sender's current state; one without a rejection means
+    // work superseded an earlier one.
     if (event?.type === 'ez.startup') {
       if (event.workBegan === true) workBegan = true
-      const r = event.rejection
-      if (r && categories.includes(r.category) && (r.resetAt === undefined || Number.isFinite(Date.parse(r.resetAt))))
-        rejection = { category: r.category, ...(r.resetAt ? { resetAt: r.resetAt } : {}) }
+      const r = event.rejection, reset = typeof r?.resetAt === 'string' ? Date.parse(r.resetAt) : NaN
+      // Re-render the reset time: it reaches a continuation prompt, and
+      // Date.parse also accepts arbitrary words around a date.
+      if (r && categories.includes(r.category) && (r.resetAt === undefined || Number.isFinite(reset)))
+        reject({ category: r.category, ...(r.resetAt === undefined ? {} : { resetAt: new Date(reset).toISOString() }) })
+      else if (rejection?.category !== 'access-denied') rejection = undefined
       return
     }
     if (event?.type === 'thread.started' || event?.type === 'result' ||
         (event?.type === 'system' && event.subtype === 'init')) return
     if (event?.type === 'rate_limit_event') {
       const info = event.rate_limit_info
-      if (info?.status === 'rejected') rejection = { category: 'quota', ...(epochSeconds(info.resetsAt) ? { resetAt: epochSeconds(info.resetsAt) } : {}) }
+      if (info?.status === 'rejected') reject({ category: 'quota', ...(epochSeconds(info.resetsAt) ? { resetAt: epochSeconds(info.resetsAt) } : {}) })
       return
     }
+    // Native API retry/error metadata is not model output. Do not inspect error
+    // prose; only typed HTTP status can establish a rejected startup.
+    if (event?.type === 'system' && ['api_error', 'api_retry'].includes(event.subtype)) {
+      const category = httpRejection(event.subtype === 'api_retry' ? event.error_status : event.error?.status)
+      if (category) { reject({ category }); return }
+    }
     const category = event?.type === 'assistant' && typeof event.error === 'string' ? claudeErrors[event.error] : undefined
-    if (category) rejection = { category, ...(category === 'quota' && rejection?.resetAt ? { resetAt: rejection.resetAt } : {}) }
-    else workBegan = true
+    if (category) reject({ category, ...(category === 'quota' && rejection?.resetAt ? { resetAt: rejection.resetAt } : {}) })
+    else work()
   }
   return {
     write: (chunk: string) => {

package/src/tools-line.d.mts

@@ -0,0 +1 @@
+export declare const TOOLS_LINE: string

package/src/tools-line.mjs

@@ -0,0 +1,3 @@
+// The only package-written discovery text: seeded once into a new workspace
+// and left in place of a retired `ez tools` footer. Inventory is generated on read.
+export const TOOLS_LINE = 'Tools: run `ez tools list --details`; each plugin\'s `--help` gives usage.'

package/src/updates/binding.mjs

@@ -1,16 +1,9 @@
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { atomic } from '../plugins/manager.mjs';
+import { fileURLToPath } from 'node:url';
+import { atomic, bindToolDiscovery } from '../plugins/manager.mjs';
 import { read } from './control.mjs';
 
-async function packageToolDiscovery(packageRoot,home,workspace) {
-  const entry=path.join(packageRoot,'src/plugins/manager.mjs');
-  const manager=await import(pathToFileURL(entry).href);
-  if(typeof manager.bindToolDiscovery!=='function')throw Error('Selected package has no tool discovery binding');
-  await manager.bindToolDiscovery(home,workspace);
-}
-
 export async function bindUpdates(home,hostConfig,packageRoot=fileURLToPath(new URL('../../',import.meta.url))) {
   home=await fs.realpath(home);hostConfig=await fs.realpath(hostConfig);
   const config=await read(path.join(home,'config.json')),host=await read(hostConfig),deploymentDir=path.dirname(hostConfig),agent=host.agents[0];
@@ -28,6 +21,7 @@ export async function bindUpdates(home,hostConfig,packageRoot=fileURLToPath(new
     const dest=path.join(bin,name);await fs.rm(dest,{force:true});
     await fs.writeFile(dest,`#!${process.execPath}\nimport fs from 'node:fs';import {spawn} from 'node:child_process';const c=JSON.parse(fs.readFileSync(${configFile}));const child=spawn(c.packageRoot+'/'+${JSON.stringify(entry)},process.argv.slice(2),{stdio:'inherit',env:{...process.env,EZ_DEPLOYMENT_DIR:c.deploymentDir,EZ_CONTROL_DIR:${JSON.stringify(agent.controlDir)}}});for(const s of ['SIGTERM','SIGINT'])process.on(s,()=>child.kill(s));child.on('error',e=>{console.error(e.message);process.exitCode=1});child.on('close',c=>process.exitCode=c??1);\n`,{mode:0o700});
   }
-  await packageToolDiscovery(packageRoot,home,config.workspace);
+  // Idempotent: retires a former `ez tools` footer, never writes guidance.
+  await bindToolDiscovery(home,config.workspace);
   return {ok:true,home,deploymentDir,packageRoot,policy:'Automatic compatible beta-channel updates by default; saved stable-only or manual policies take precedence. Local candidates require an explicit owner request.'};
 }

package/src/updates/control.mjs

@@ -191,7 +191,8 @@ export async function submit(home,id,automatic) {
     if(next.old.root!==job.previousRoot||next.old.pkg.version!==job.previousVersion)throw Error('Installation changed since preparation');
     if(digest(await fs.readFile(path.join(dir,'candidate.tgz')))!==job.sha256)throw Error('Candidate changed');
     job.status='queued';job.automatic=automatic;await atomic(path.join(dir,'job.json'),job);return job;
-  });
+  // Queueing writes only the job; activation drains plugin calls before switching.
+  },{allowInvocations:true,waitMs:5000});
 }
 export async function retryRecovery(home,id) {
   const {directory}=await state(home),dir=jobPath(home,id);
@@ -201,7 +202,7 @@ export async function retryRecovery(home,id) {
     if((await jobs(home)).some(j=>['queued','applying'].includes(j.status)))throw Error('An upgrade is already pending');
     await requireSupervisor(directory);
     job.status='queued';job.recoveryRequested=true;await atomic(path.join(dir,'job.json'),job);return {id,status:job.status,recoveryRequested:true};
-  });
+  },{allowInvocations:true,waitMs:5000});
 }
 export async function command(home,args) {
   const [action,...rest]=args;

package/src/updates/runtime.mjs

@@ -33,8 +33,8 @@ export function execute(command,args,options={}) {
 export async function textAtomic(file,text) {
   const tmp=file+'.update.tmp';await fs.writeFile(tmp,text,{mode:0o600});await fs.rename(tmp,file);
 }
-export async function backupStateDirectory(source,destination) {
-  await fs.cp(source,destination,{recursive:true,filter:async entry=>!(await fs.lstat(entry)).isSocket()});
+export async function backupStateDirectory(source,destination,omit=[]) {
+  await fs.cp(source,destination,{recursive:true,filter:async entry=>!omit.includes(path.relative(source,entry).split(path.sep)[0])&&!(await fs.lstat(entry)).isSocket()});
 }
 export const pluginArgs = record => ['compose','--project-name',record.project,'--file',record.compose];
 export async function packageManager(root,run=execute) {
@@ -159,7 +159,7 @@ export async function perform(home,job,hooks) {
   const root=path.join(dir,'runtime');await fs.rm(root,{recursive:true,force:true});await extract(archive,root);
   const next=await eligibility(home,job.target,root,job.automatic);
   if(next.old.root!==job.previousRoot||next.old.pkg.version!==job.previousVersion)throw Error('Stale upgrade job');
-  job.status='applying';job.root=root;job.startedAt=new Date().toISOString();await save();
+  job.status='applying';job.preserveRuns=hooks.preserveRuns===true;job.root=root;job.startedAt=new Date().toISOString();await save();
   const complete=async()=>{
     job.status='completed';job.endedAt=new Date().toISOString();await save();
     try { job.cleanup=await cleanupStaleBackups(home);await save(); }
@@ -193,17 +193,30 @@ export async function perform(home,job,hooks) {
       });
       const image=`ez-upgrade-${digest(JSON.stringify([job.sha256,buildArgs])).slice(0,24)}`;
       await run('docker',['build','--target','runtime',...buildArgs,'-t',image,root]);
+      const backup=path.join(dir,'backup');
+      const backupState=async()=>{
+        await fs.mkdir(backup,{mode:0o700});
+        await backupStateDirectory(config.workspace,path.join(backup,'workspace'));
+        await backupStateDirectory(agent.controlDir,path.join(backup,'control'),hooks.preserveRuns ? ['host-executor'] : []);
+        for(const name of ['docker.env','host-executor.json','agent.json','purpose.md','relay.env'])await fs.copyFile(path.join(config.deploymentDir,name),path.join(backup,name));
+      };
+      // Native client state can be many gigabytes. This advisory copy never
+      // rewinds live state, so compatible generations keep serving throughout it.
+      if(hooks.preserveRuns)await backupState();
       const envFile=path.join(config.deploymentDir,'docker.env'),oldEnv=await fs.readFile(envFile,'utf8');
       const cid=(await run('docker',[...relayArgs(config),'ps','-q','relay'])).trim();
       if(!cid||/\s/.test(cid))throw Error('Expected one running relay');
       const oldImage=(await run('docker',['inspect','--format','{{.Image}}',cid])).trim();
       if(!/^sha256:[a-f0-9]{64}$/.test(oldImage))throw Error('Cannot pin rollback image');
       job.rollback={env:envValue(oldEnv,'EZ_RELAY_IMAGE',oldImage),packageRoot:config.packageRoot};await save();
-      await run('docker',[...relayArgs(config),'stop','relay']);await hooks.stopHost();
-      const backup=path.join(dir,'backup');await fs.mkdir(backup,{mode:0o700});
-      await backupStateDirectory(config.workspace,path.join(backup,'workspace'));
-      await backupStateDirectory(agent.controlDir,path.join(backup,'control'));
-      for(const name of ['docker.env','host-executor.json','agent.json','purpose.md','relay.env'])await fs.copyFile(path.join(config.deploymentDir,name),path.join(backup,name));
+      const activate=async()=>{
+        const current=await eligibility(home,job.target,root,job.automatic);
+        if(current.old.root!==job.previousRoot||current.old.pkg.version!==job.previousVersion)throw Error('Stale upgrade job');
+        const pause=path.join(agent.controlDir,'upgrade-pause.json');
+        if(hooks.preserveRuns)await atomic(pause,{id:job.id});
+        try {
+      await run('docker',[...relayArgs(config),'stop','relay']);await (hooks.preserveRuns ? hooks.retireHost() : hooks.stopHost());
+      if(!hooks.preserveRuns)await backupState();
       let env=oldEnv.split(job.previousRoot+path.sep).join(root+path.sep);env=envValue(env,'EZ_RELAY_IMAGE',image);
       await textAtomic(envFile,env);
       await bindUpdates(home,path.join(config.deploymentDir,'host-executor.json'),root);
@@ -213,6 +226,9 @@ export async function perform(home,job,hooks) {
         const brokerImage=(await run('docker',['image','inspect','--format','{{.Id}}',image],{stdoutOnly:true})).trim();
         job.brokerReadiness=await refreshBroker(config,run,brokerImage);
       }
+        }finally{if(hooks.preserveRuns)await fs.rm(pause,{force:true});}
+      };
+      if(hooks.preserveRuns)await locked(home,activate,{drainInvocations:true,signal:hooks.signal});else await activate();
     } else {
       const old=next.old.record;
       const secrets=await read(path.join(home,'packages',job.target,'secrets.json')).catch(e=>{if(e.code==='ENOENT')return {};throw e;});
@@ -266,7 +282,7 @@ export async function recover(home,job,hooks) {
           return /^sha256:[a-f0-9]{64}$/.test(pinned||'')&&current.Image===pinned&&current.State?.Running===true&&current.State?.Health?.Status==='healthy';
         })().catch(()=>false);
         if(!retained)await run('docker',[...relayArgs(config),'stop','relay']);
-        await hooks.stopHost();
+        await (hooks.preserveRuns ? hooks.retireHost() : hooks.stopHost());
         await textAtomic(path.join(config.deploymentDir,'docker.env'),job.rollback.env);
         await bindUpdates(home,path.join(config.deploymentDir,'host-executor.json'),job.rollback.packageRoot);
         await hooks.startHost(job.rollback.packageRoot);

package/src/updates/supervisor.mjs

@@ -5,7 +5,7 @@ import { spawn } from 'node:child_process';
 import { atomic, locked } from '../plugins/manager.mjs';
 import { callDeliverySocket } from '../delivery-socket-client.mjs';
 import { state, read, jobs, jobPath, check, prepare, submit, missing, cleanupStaleBackups } from './control.mjs';
-import { perform, environment, brokerNeedsRefresh } from './runtime.mjs';
+import { perform, environment, brokerNeedsRefresh, execute, relayArgs } from './runtime.mjs';
 
 const reservedProviderKeys=new Set(['HOME','LANG','LC_ALL','LOGNAME','PATH','SHELL','TERM','TMPDIR','USER','CODEX_HOME','NODE_OPTIONS']);
 const providerEnvironmentKey=value=>{
@@ -54,7 +54,7 @@ export async function withIdleUpgrade(control,job,signal,apply,{isIdle=idle,wait
 }
 // Plugin replacement drains command leases at activation, not native turns.
 export async function withUpgrade(control,job,signal,apply,options) {
-  if(job.target==='main'||options?.requiresIdle)return withIdleUpgrade(control,job,signal,apply,options);
+  if((job.target==='main'&&!options?.preserveRuns)||options?.requiresIdle)return withIdleUpgrade(control,job,signal,apply,options);
   if(!signal.aborted)return apply();
 }
 export async function queueAutomatic(home,available) {
@@ -84,20 +84,88 @@ export async function supervise(deployment,signal,{discover=check}={}) {
   if(prior&&(!Number.isSafeInteger(prior.pid)||prior.pid<1))throw Error('Corrupt supervisor lock');
   if(prior){try{process.kill(prior.pid,0);throw Error('Supervisor already running');}catch(e){if(e.code!=='ESRCH')throw e;}await fs.rm(lock);}
   await fs.writeFile(lock,JSON.stringify({pid:process.pid}),{flag:'wx',mode:0o600});
-  let child;
+  let child,container;
+  let retirements=[];
+  let reloadPending=false;
+  const generations=new Map();
+  const removeContainer=async id=>{
+    const generation=generations.get(id);
+    if(generation){await execute('docker',['compose','--project-name',generation.project,'--file',generation.file,'down']);await fs.rm(generation.file,{force:true});await fs.rm(generation.configFile,{force:true});generations.delete(id);}
+    else await execute('docker',['rm',id]);
+  };
   const stopHost=async()=>{
+    if(container){await execute('docker',['stop','--time','10',container]);await removeContainer(container);container=undefined;}
     if(!child)return;const running=child;child=undefined;
     if(running.exitCode!==null)return;
     const closed=new Promise(resolve=>running.once('close',resolve));running.kill('SIGTERM');
     const timer=setTimeout(()=>running.kill('SIGKILL'),10000);await closed;clearTimeout(timer);
   };
   const startHost=async root=>{
-    if(host.isolation==='isolated')return
+    if(host.isolation==='isolated') {
+      const pkg=await read(path.join(root,'package.json'));
+      if(pkg.ezRelease?.containerExecutor!==1)return;
+      const lock=path.join(agent.controlDir,'host-executor/worker.lock');
+      const prior=await read(lock).catch(missing);
+      if(prior?.containerId){
+        if(!/^[a-f0-9]{12,64}$/.test(prior.containerId))throw Error('Invalid previous isolated worker identity');
+        const running=await execute('docker',['inspect','--format','{{.State.Running}}',prior.containerId],{stdoutOnly:true}).catch(()=>null);
+        if(running?.trim()==='true')throw Error('Previous isolated worker is still running');
+        // Only the supervisor can prove a foreign container stopped.
+        if(JSON.stringify(await read(lock))!==JSON.stringify(prior))throw Error('Worker lock changed during recovery');
+        await fs.rm(lock);
+      }
+      const config=(await state(home)).config;
+      const deployment=JSON.parse(await execute('docker',[...relayArgs(config),'config','--format','json'],{stdoutOnly:true}));
+      const relay=deployment.services.relay;
+      if(!relay?.image||!Array.isArray(relay.volumes))throw Error('Invalid isolated relay binding');
+      const generation=path.basename(root).replace(/[^a-zA-Z0-9_.-]/g,'-')+'-'+Date.now();
+      const project='ez-executor-'+generation.toLowerCase();
+      const file=path.join(directory,project+'.json');
+      const configFile=path.join(directory,project+'-binding.json');
+      await atomic(configFile,{...host,agents:host.agents.map(a=>({...a,binDir:'/app/bin'}))});
+      const worker={image:relay.image,init:true,restart:'no',user:`${relay.environment.EZ_RUNTIME_UID||1000}:${relay.environment.EZ_RUNTIME_GID||1000}`,
+        cap_drop:['ALL'],security_opt:['no-new-privileges:true'],entrypoint:['node','--import','/app/node_modules/tsx/dist/loader.mjs','/app/src/host-executor.ts','/run/executor.json'],
+        environment:{...relay.environment,EZ_CONTAINER_EXECUTOR:'1',EZ_EXECUTOR_TRANSPORT:'local'},
+        volumes:[...relay.volumes,{type:'bind',source:configFile,target:'/run/executor.json',read_only:true}],tmpfs:['/tmp'],
+        ...Object.fromEntries(['networks','network_mode','extra_hosts','dns','dns_search'].filter(key=>relay[key]!==undefined).map(key=>[key,relay[key]]))};
+      if(worker.networks&&!Array.isArray(worker.networks))worker.networks=Object.fromEntries(Object.keys(worker.networks).map(name=>[name,{}]));
+      const networks=worker.networks?Object.fromEntries(Object.entries(deployment.networks||{}).map(([name,binding])=>[name,{name:binding.name,external:true}])):undefined;
+      await atomic(file,{services:{executor:worker},...(networks?{networks}:{})});
+      await execute('docker',['compose','--project-name',project,'--file',file,'up','-d','--no-build','executor']);
+      container=(await execute('docker',['compose','--project-name',project,'--file',file,'ps','-q','executor'],{stdoutOnly:true})).trim();
+      if(!/^[a-f0-9]{12,64}$/.test(container))throw Error('Missing isolated executor');
+      generations.set(container,{project,file,configFile});
+      for(let n=0;n<300;n++){
+        const running=await execute('docker',['inspect','--format','{{.State.Running}}',container],{stdoutOnly:true});
+        if(running.trim()!=='true')throw Error('Isolated executor exited during startup');
+        const heartbeat=await read(path.join(agent.controlDir,'host-executor/heartbeat.json')).catch(missing);
+        if(heartbeat?.containerExecutor===true&&container.startsWith(heartbeat.containerId||'missing')&&Date.now()-heartbeat.at<1000)return;
+        await sleep(100);
+      }
+      throw Error('Isolated executor heartbeat timeout');
+    }
     child=spawn(process.execPath,['--import',path.join(root,'node_modules/tsx/dist/loader.mjs'),path.join(root,'src/host-executor.ts'),path.join(deployment,'host-executor.json')],
-      {env:{...environment(),...providerEnvironment(host),EZ_HOST_SUPERVISOR_PID:String(process.pid)},stdio:['ignore','inherit','inherit']});
+      {detached:true,env:{...environment(),...providerEnvironment(host),EZ_HOST_SUPERVISOR_PID:String(process.pid)},stdio:['ignore','inherit','inherit']});
     let error;child.once('error',e=>{error=e;});
     await waitForHostHeartbeat(agent.controlDir,child,()=>error);
   };
+  const retireHost=async()=>{
+    if(container){await execute('docker',['kill','--signal','SIGUSR2',container]);retirements.push({container});container=undefined;}
+    if(child){const running=child;child=undefined;if(running.exitCode===null){running.kill('SIGUSR2');retirements.push({child:running});}}
+    // A retiring generation releases its single claim lock before replacement.
+    for(let n=0;n<300;n++){
+      if(!await fs.stat(path.join(agent.controlDir,'host-executor/worker.lock')).then(()=>true,e=>{if(e.code==='ENOENT')return false;throw e;}))return;
+      await sleep(100);
+    }
+    throw Error('Native executor retirement timeout');
+  };
+  const preserveRuns=async job=>{
+    if(job.target!=='main')return false;
+    const old=await read(path.join((await state(home)).config.packageRoot,'package.json'));
+    const candidate=await read(path.join(jobPath(home,job.id),'package/package.json'));
+    return old.ezRelease?.runHandoff===1&&candidate.ezRelease?.runHandoff===1&&
+      (host.isolation!=='isolated'||(container&&old.ezRelease?.containerExecutor===1&&candidate.ezRelease?.containerExecutor===1));
+  };
   const pause=path.join(agent.controlDir,'upgrade-pause.json');
   const refreshRequirement=async job=>{
     if(job.target==='main')return false;
@@ -119,36 +187,56 @@ export async function supervise(deployment,signal,{discover=check}={}) {
     if(owner&&prior&&owner.pid===prior.pid)await fs.rm(registryLock);
     // Wait for an orphaned transport's parent-watch to terminate it first.
     await sleep(1200);
+    const workerOwner=await read(path.join(agent.controlDir,'host-executor/worker.lock')).catch(missing);
+    if(host.isolation==='isolated'&&workerOwner?.containerId){
+      if(!/^[a-f0-9]{12,64}$/.test(workerOwner.containerId))throw Error('Invalid isolated worker identity');
+      if((await execute('docker',['inspect','--format','{{.State.Running}}',workerOwner.containerId],{stdoutOnly:true}).catch(()=>''))?.trim()==='true')container=workerOwner.containerId;
+    }
     const interrupted=(await jobs(home)).find(j=>j.status==='applying');
     if(interrupted){
       const refreshPluginBroker=await refreshRequirement(interrupted);
       const result=refreshPluginBroker===null?undefined:interrupted.target==='main'
-        ? await (async()=>{await atomic(pause,{id:interrupted.id});try{return await locked(home,()=>perform(home,interrupted,{stopHost,startHost}));}finally{await fs.rm(pause,{force:true});}})()
-        : await withUpgrade(agent.controlDir,interrupted,signal,()=>perform(home,interrupted,{stopHost,startHost,signal,refreshPluginBroker}),{requiresIdle:refreshPluginBroker});
-      if(result?.status==='completed'&&interrupted.target==='main')return;
+        ? await (async()=>{await atomic(pause,{id:interrupted.id});try{return await locked(home,()=>perform(home,interrupted,{stopHost,startHost,retireHost,preserveRuns:interrupted.preserveRuns===true}));}finally{await fs.rm(pause,{force:true});}})()
+        : await withUpgrade(agent.controlDir,interrupted,signal,()=>perform(home,interrupted,{stopHost,startHost,retireHost,signal,refreshPluginBroker}),{requiresIdle:refreshPluginBroker});
+      if(['completed','rolled-back'].includes(result?.status)&&interrupted.target==='main')reloadPending=true;
     }
     const isolated=host.isolation==='isolated'
-    if(!isolated && !child)await startHost((await state(home)).config.packageRoot);
+    if(!isolated&&!child)await startHost((await state(home)).config.packageRoot);
+    const initializeIsolated=async()=>{
+      if(!isolated||container)return;
+      const root=(await state(home)).config.packageRoot;
+      if((await read(path.join(root,'package.json'))).ezRelease?.containerExecutor!==1)return;
+      await withIdleUpgrade(agent.controlDir,{id:'executor-migration'},signal,()=>startHost(root));
+    };
+    await initializeIsolated();
     let nextCheck=0;
     while(!signal.aborted) {
       if(!isolated && child?.exitCode!==null&&child?.exitCode!==undefined)throw Error('Host transport exited; supervisor service should restart');
-      const pending=(await jobs(home)).find(j=>j.status==='queued');
+      await initializeIsolated();
+      if(container&&(await execute('docker',['inspect','--format','{{.State.Running}}',container],{stdoutOnly:true})).trim()!=='true')throw Error('Isolated executor exited; supervisor service should restart');
+      if(reloadPending&&await idle(agent.controlDir))return;
+      // Reap retired containers only after their worker exits.
+      for(const item of retirements.filter(r=>r.container)){
+        if((await execute('docker',['inspect','--format','{{.State.Running}}',item.container],{stdoutOnly:true})).trim()==='false'){await removeContainer(item.container);retirements=retirements.filter(r=>r!==item);}
+      }
+      const pending=!reloadPending&&(await jobs(home)).find(j=>j.status==='queued');
       if(pending) {
         const refreshPluginBroker=await refreshRequirement(pending);
         if(refreshPluginBroker===null)continue;
+        const preserve=await preserveRuns(pending);
         const apply=async()=>{
           try {
-            const activate=async()=>{const latest=await read(path.join(jobPath(home,pending.id),'job.json'));return perform(home,latest,{stopHost,startHost,signal,refreshPluginBroker});};
-            return pending.target==='main'?await locked(home,activate):await activate();
+            const activate=async()=>{const latest=await read(path.join(jobPath(home,pending.id),'job.json'));return perform(home,latest,{stopHost,startHost,retireHost,signal,refreshPluginBroker,preserveRuns:preserve});};
+            return pending.target==='main'&&!preserve?await locked(home,activate,{drainInvocations:true,signal}):await activate();
           } catch(error) {
             // A pre-switch rejection is terminal. Applying jobs keep their journal for recovery.
             const latest=await read(path.join(jobPath(home,pending.id),'job.json'));
             if(latest.status==='queued'){latest.status='failed';latest.error=error.message;await atomic(path.join(jobPath(home,pending.id),'job.json'),latest);}else throw error;
           }
         };
-        const result=await withUpgrade(agent.controlDir,pending,signal,apply,{requiresIdle:refreshPluginBroker});
-        if(result?.status==='completed') {
-          if(pending.target==='main')return;
+        const result=await withUpgrade(agent.controlDir,pending,signal,apply,{requiresIdle:refreshPluginBroker,preserveRuns:preserve});
+        if(['completed','rolled-back'].includes(result?.status)) {
+          if(pending.target==='main')reloadPending=true;
           nextCheck=0;
         }
       }
@@ -166,7 +254,8 @@ export async function supervise(deployment,signal,{discover=check}={}) {
       await sleep(500);
     }
   }finally {
-    clearInterval(beat);await stopHost();await fs.rm(lock,{force:true});
+    clearInterval(beat);await stopHost();
+    for(const item of retirements){if(item.container){await execute('docker',['stop','--time','10',item.container]);await removeContainer(item.container);}else if(item.child.exitCode===null)item.child.kill('SIGTERM');}await fs.rm(lock,{force:true});
     if(!(await jobs(home)).some(j=>j.status==='applying'))await fs.rm(pause,{force:true});
   }
 }

package/src/workspace.ts

@@ -2,6 +2,17 @@ import { installAgentGuidance } from './agent-guidance.js'
 import { link, lstat, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { randomUUID } from 'node:crypto'
 import path from 'node:path'
+import { TOOLS_LINE } from './tools-line.mjs'
+
+// Engine-neutral memory: every native CLI loads AGENTS.md, so both read the
+// same plain files. The agent owns the folder and the section after seeding.
+const MEMORY_SEED = `## Memory
+
+Keep durable facts (people, preferences, decisions, standing commitments) in
+\`memory/\`, one fact per file, each listed on one line in \`memory/MEMORY.md\`.
+Read \`memory/MEMORY.md\` when a conversation starts. Save or update a fact as
+soon as you learn something a future conversation will need; skip what other
+workspace files already hold.`
 
 // Publish each complete seed exclusively. Reinstall never replaces the agent's mind.
 export const initializeWorkspace = async (workspace: string, purposeFile: string | undefined = process.env.EZ_AGENT_PURPOSE_FILE): Promise<string[]> => {
@@ -22,7 +33,7 @@ export const initializeWorkspace = async (workspace: string, purposeFile: string
   try {
     const purpose = (await readFile(purposeFile, 'utf8')).trim()
     if (!purpose) throw new Error('Purpose file must not be empty.')
-    await writeFile(temporary, `## Purpose\n\n${purpose}\n`, { mode: 0o600, flag: 'wx' })
+    await writeFile(temporary, `## Purpose\n\n${purpose}\n\n${MEMORY_SEED}\n\n${TOOLS_LINE}\n`, { mode: 0o600, flag: 'wx' })
     try {
       await link(temporary, target)
       created.push(name)

package/test/ai-cli.test.ts

@@ -6,6 +6,7 @@ import path from 'node:path'
 import {spawnSync} from 'node:child_process'
 import {fileURLToPath} from 'node:url'
 import {ControlStore} from '../src/control-state.js'
+import {executorJobEnv} from '../src/executor.js'
 import {initialPreset} from '../src/ai.js'
 
 test('explicit CLI/model selection preserves installation default and rejects unavailable choices',async()=>{
@@ -50,12 +51,33 @@ test('an agent can select a declared provider and model without putting the key
   await writeFile(path.join(binDir,'codex'),'#!/bin/sh\nexit 0\n',{mode:0o700})
   await writeFile(path.join(controlDir,'host-executor','models.json'),JSON.stringify([{cli:'codex',provider:'openrouter',model:'google/gemini-3.8-flash',name:'Gemini',efforts:[]}]))
   const store=new ControlStore(controlDir,900000);await store.aiState(initialPreset('codex'))
-  const env={...process.env,HOME:root,PATH:binDir+path.delimiter+process.env.PATH,EZ_CONTROL_DIR:controlDir,OPENROUTER_API_KEY:'must-not-persist'}
+  const env=executorJobEnv({runId:'fixture',controlDir,binDir,catalogTransport:'host'},{...process.env,HOME:root,PATH:binDir+path.delimiter+process.env.PATH,OPENROUTER_API_KEY:'must-not-persist'})
   const bin=fileURLToPath(new URL('../bin/ezenciel-agents-ai.mjs',import.meta.url))
   const result=spawnSync(process.execPath,[bin,'select','--cli','codex','--provider','openrouter','--model','google/gemini-3.8-flash'],{env,encoding:'utf8'})
   assert.equal(result.status,0,result.stderr)
   const state=await store.status(),selected=state.ai?.presets.find(p=>p.id===state.ai?.selectedId)
   assert.equal(selected?.provider,'openrouter');assert.equal(selected?.model,'google/gemini-3.8-flash')
   assert.equal(JSON.stringify(state).includes('must-not-persist'),false)
+  assert.equal(env.EZ_EXECUTOR_TRANSPORT,undefined)
+  assert.equal(env.EZ_ISOLATION,undefined)
+ }finally{await rm(root,{recursive:true,force:true})}
+})
+
+
+test('isolated AI CLI ignores a legacy host catalog and discovers its own Sonnet',async()=>{
+ const root=await mkdtemp(path.join(tmpdir(),'ez-ai-local-catalog-'))
+ try{
+  const controlDir=path.join(root,'control'),binDir=path.join(root,'bin')
+  await mkdir(path.join(controlDir,'host-executor'),{recursive:true});await mkdir(binDir)
+  const stale=JSON.stringify([{cli:'codex',model:'host-only',name:'Host only',efforts:[]}])
+  await writeFile(path.join(controlDir,'host-executor','models.json'),stale)
+  await writeFile(path.join(binDir,'claude'),"#!/bin/sh\nprintf '%s\n' \"  --model <model> Model (e.g. 'sonnet', 'opus')\" \"  --effort <level> Effort (low, high)\"\n",{mode:0o700})
+  const env={...process.env,HOME:root,PATH:binDir,EZ_CONTROL_DIR:controlDir,EZ_ISOLATION:'isolated',EZ_EXECUTOR_TRANSPORT:'local'}
+  const bin=fileURLToPath(new URL('../bin/ezenciel-agents-ai.mjs',import.meta.url))
+  const result=spawnSync(process.execPath,[bin,'list'],{env,encoding:'utf8'})
+  assert.equal(result.status,0,result.stderr)
+  const catalog=JSON.parse(result.stdout)
+  assert.ok(catalog.some((m:{cli:string;model:string})=>m.cli==='claude'&&m.model==='sonnet'))
+  assert.ok(!catalog.some((m:{model:string})=>m.model==='host-only'))
  }finally{await rm(root,{recursive:true,force:true})}
 })