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

package/src/scheduler.ts

@@ -8,7 +8,7 @@ import { type Owner, sameOwner, validOwner, ownerId, ownerEpoch } from './contro
 import { validApplicationOrigin } from './application-origin.js'
 import { ApplicationBindings } from './application-channel.js'
 import { assertId, ownsRun } from './identity.js'
-import { type ExecutionChoice, isExecutionChoice, persistedPreset } from './ai.js'
+import { type AiPreset, type ExecutionChoice, isExecutionChoice, persistedPreset } from './ai.js'
 import { type Trigger, validateTrigger, nextOccurrence } from './schedule-time.js'
 import { RunStore, type RunRecord } from './runs.js'
 import { Scripts, assertScriptArgs, assertScriptId, type ScriptRunRef } from './scripts.js'
@@ -139,8 +139,13 @@ export class Scheduler {
       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)
+      const setups = [execution.preset, ...execution.fallbacks ?? []]
+      for (const preset of setups) {
+        assertScheduledModel(preset.model)
+        assertEffort(preset.effort, preset.model, preset.cli)
+      }
+      const key = (p: AiPreset) => JSON.stringify([p.cli, p.authProfile, p.provider, p.model, p.effort])
+      if (new Set(setups.map(key)).size !== setups.length) throw new Error('Task setups must be distinct')
       s = {...input, execution, trigger:validateTrigger(input.trigger),version:1,revision:randomUUID()}
     }
     const now = Date.now()
@@ -272,7 +277,7 @@ export class Scheduler {
             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}
+          } catch (error) {console.error('Schedule preflight unavailable',s.id,error instanceof Error ? error.message : 'Unknown error');const prior=await readFile(cursor,'utf8').then(v=>JSON.parse(v)).catch(e=>{if(e.code==='ENOENT')return {};throw e});await atomic(cursor,{next:future,preflight:{...prior.preflight,state:'unavailable',observedAt:new Date().toISOString()}});continue}
         }
         const dueAt = new Date(next).toISOString()
         await runs.create({id:scheduledRunId(s,next),

package/src/session-close.ts

@@ -0,0 +1,17 @@
+import type { SessionState, Owner } from './control-state.js'
+import { ownerId, ownerEpoch } from './control-state.js'
+import type { RunStore, RunRecord } from './runs.js'
+
+// A chat conversation has no native end. Before one is replaced, its engine
+// gets one silent turn in that same native session to keep durable facts in
+// the workspace. Ez only transports this literal; the engine decides whether
+// anything is written. No reply mechanism is offered, so nothing is delivered.
+// Owner conversations only: a close turn carries owner authority, so a private
+// application scope (which runs under its binding's narrower authority) gets none.
+export const SESSION_CLOSE_PROMPT = '[conversation closing] This conversation is ending. Save anything a future conversation will need where AGENTS.md says to keep memory; otherwise do nothing.'
+
+export async function queueSessionClose(runs: RunStore, owner: Owner | null, session: SessionState | null | undefined): Promise<RunRecord | undefined> {
+  if (!owner || !session?.hasStarted || !session.preset || session.applicationScope) return undefined
+  return runs.create({ ownerId: ownerId(owner), ownerEpoch: ownerEpoch(owner), texts: [SESSION_CLOSE_PROMPT],
+    execution: { sessionId: session.sessionId, preset: session.preset }, sessionClose: true })
+}

package/src/setup-fallback.ts

@@ -0,0 +1,159 @@
+import { presetLabel, presetProvider, type AiPreset, type ExecutionChoice } from './ai.js'
+
+// Ordered task setups for one scheduled occurrence. Core advances only on typed
+// 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 | 'quota-after-work-began' | 'after-work-began' | 'uncertain' | 'same-quota-scope' | 'same-login-scope'
+export type SetupAttempt = {
+  preset: AiPreset
+  quotaScope: string
+  outcome: 'running' | 'completed' | 'failed' | 'cancelled' | 'skipped'
+  category?: AttemptCategory
+  resetAt?: string
+  exitCode?: number | null
+  sessionId?: string
+  startedAt?: string
+  endedAt?: string
+}
+
+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 ?? [])]
+
+// 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
+  }
+  const cli = preset.cli === 'codex-gui' ? 'codex' : preset.cli
+  return preset.authProfile ? `${cli}@${preset.authProfile}` : cli
+}
+
+// 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 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: exhausted.get(scope), startedAt: at, endedAt: at })
+  }
+  return { skipped }
+}
+
+export class SetupsUnavailableError extends Error {}
+
+export const unavailableSummary = (attempts: SetupAttempt[]): string =>
+  `Every task setup was unavailable: ${attempts.map(a => `${presetLabel(a.preset)} (${a.category}${a.resetAt ? `, resets ${a.resetAt}` : ''})`).join('; ')}`
+
+const epochSeconds = (value: unknown): string | undefined =>
+  typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? new Date(value * 1000).toISOString() : undefined
+
+const claudeErrors: Record<string, StartupCategory> = {
+  rate_limit: 'quota', billing_error: 'quota',
+  authentication_failed: '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 '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
+  return httpRejection(status)
+}
+
+// The latest reset among exhausted Codex rate-limit windows.
+export const codexResetAt = (limits: any): string | undefined => {
+  const resets = [limits?.primary, limits?.secondary].filter(w => w && w.usedPercent >= 100 && typeof w.resetsAt === 'number').map(w => w.resetsAt as number)
+  return resets.length ? epochSeconds(Math.max(...resets)) : undefined
+}
+
+export const startupLine = (state: { workBegan: boolean; rejection?: StartupRejection }): string =>
+  JSON.stringify({ type: 'ez.startup', workBegan: state.workBegan, ...(state.rejection ? { rejection: state.rejection } : {}) })
+
+// Reads structured stdout only: Ez transport summaries (`ez.startup`) and
+// Claude stream-json envelopes. Model text is never inspected. Any event that
+// is not known pre-work metadata counts as work, so ambiguity never advances.
+// 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 { 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, 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') 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) reject({ category, ...(category === 'quota' && rejection?.resetAt ? { resetAt: rejection.resetAt } : {}) })
+    else work()
+  }
+  return {
+    write: (chunk: string) => {
+      buffer += chunk
+      const lines = buffer.split('\n')
+      buffer = lines.pop() ?? ''
+      for (const text of lines) line(text)
+    },
+    result: () => { line(buffer); buffer = ''; return { workBegan, rejection } },
+    summary: () => startupLine({ workBegan, rejection }),
+  }
+}

package/src/task-executor.ts

@@ -8,6 +8,7 @@ import { promisify } from 'node:util'
 import { readRun } from './delivery-socket.js'
 import {ApplicationBindings} from './application-channel.js'
 import { Tasks } from './tasks.js'
+import { provisionedHome } from './auth-profile.js'
 import { executorEnvironment, executorInvocation, terminateJob, type ExecutorOptions } from './executor.js'
 
 // This adapter is deliberately version-pinned: a new native tool default needs
@@ -58,8 +59,8 @@ export async function startTaskExecutor(options: ExecutorOptions) {
     const catalogInvocation = executorInvocation('codex', ['debug', 'models', '--bundled'])
     const catalog = await promisify(execFile)(catalogInvocation.command, catalogInvocation.args, { env: environment, maxBuffer: 4 * 1024 * 1024 })
     await writeFile(join(temporary, 'models.json'), JSON.stringify(taskModelCatalog(JSON.parse(catalog.stdout))), { mode: 0o600 })
-    const auth = process.env.EZ_ISOLATION === 'isolated'
-      ? join(options.controlDir, 'cli', 'codex', 'auth.json')
+    const auth = process.env.EZ_ISOLATION === 'isolated' || options.authProfile !== undefined
+      ? join(await provisionedHome(options.controlDir, 'codex', options.authProfile), 'auth.json')
       : join(homedir(), '.codex', 'auth.json')
     await symlink(auth, join(home, 'auth.json'))
     const broker = [process.execPath, '--import', fileURLToPath(new URL('../node_modules/tsx/dist/loader.mjs', import.meta.url)),

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

@@ -7,7 +7,7 @@ import { pathToFileURL } from 'node:url';
 import { spawn } from 'node:child_process';
 import { parseEnv } from 'node:util';
 import { tmpdir } from 'node:os';
-import { atomic, compose, snapshot, checkFolders } from '../plugins/manager.mjs';
+import { atomic, compose, snapshot, checkFolders, locked, publishBrokerPlugins } from '../plugins/manager.mjs';
 import { read, state, eligibility, jobPath, cleanupStaleBackups } from './control.mjs';
 import { bindUpdates } from './binding.mjs';
 import { extract, digest } from './artifact.mjs';
@@ -82,24 +82,44 @@ export async function refreshBroker(config, run=execute, image) {
     const current=(await run('docker',[...args,'ps','-q','plugin-broker'],{stdoutOnly:true,timeout:15000})).trim();
     if(!/^[a-f0-9]{12,64}$/i.test(current)||(await run('docker',['inspect','--format','{{.Image}}',current],{stdoutOnly:true,timeout:15000})).trim()!==image)
       throw Error('Recreated broker image does not match the intended installed image');
-    const hostConfig=config.hostConfig||path.join(config.deploymentDir,'host-executor.json');
-    const home=path.dirname(hostConfig)===config.deploymentDir
-      ? (await read(hostConfig)).agents?.find(agent=>agent.workspace===config.workspace)?.toolsHome : undefined;
-    if(typeof home!=='string'||!path.isAbsolute(home))throw Error('Missing broker registry binding');
-    const files=[hostConfig,path.join(home,'registry.json'),path.join(home,'config.json')];
-    const hashes=await Promise.all(files.map(async file=>digest(await fs.readFile(file))));
-    // Supply trusted read-only code so rollback can check an older image that
-    // predates this diagnostic. Its validators still come from that image.
-    const diagnostic=await fs.readFile(new URL('../../docker/broker-readiness.mjs',import.meta.url),'utf8');
-    const probe=JSON.parse(await run('docker',[...args,'exec','-T','plugin-broker','node','--import','/app/node_modules/tsx/dist/loader.mjs',
-      '--input-type=module','-e',diagnostic,...hashes],{stdoutOnly:true,timeout:60000}));
-    if(probe.version!==1||probe.ready!==true||probe.hostSha256!==hashes[0]||probe.registrySha256!==hashes[1]||probe.configSha256!==hashes[2])
-      throw Error('Invalid isolated broker readiness readback');
-    // A concurrent writer invalidates the readback; never silently accept it.
-    for(let i=0;i<files.length;i++)if(digest(await fs.readFile(files[i]))!==hashes[i])throw Error('Broker binding changed during verification');
-    return probe;
+    return verifyBroker(config,run);
   }finally {await fs.rm(temporary,{recursive:true,force:true});}
 }
+// A plugin update normally leaves this single-file binding unchanged. If an
+// operator replaced it (for example to approve new network pins), recreation
+// remains necessary and must retain the existing full-turn drain.
+export async function brokerNeedsRefresh(config,run=execute) {
+  if (!(await relayServices(config)).includes('plugin-broker')) return false;
+  const hostConfig=config.hostConfig||path.join(config.deploymentDir,'host-executor.json');
+  const expected=digest(await fs.readFile(hostConfig));
+  const script="const fs=require('fs'),crypto=require('crypto');console.log(crypto.createHash('sha256').update(fs.readFileSync(process.env.EZ_PLUGIN_BROKER_HOST_CONFIG)).digest('hex'));";
+  const mounted=(await run('docker',[...relayArgs(config),'exec','-T','plugin-broker','node','-e',script],{stdoutOnly:true,timeout:15000})).trim();
+  if(!/^[a-f0-9]{64}$/.test(mounted))throw Error('Invalid broker host binding fingerprint');
+  return mounted!==expected;
+}
+// Plugin upgrades change the directory-mounted registry, not the broker's
+// single-file host binding. Verify the live broker without replacing its socket.
+export async function verifyBroker(config,run=execute) {
+  if (!(await relayServices(config)).includes('plugin-broker')) return null;
+  const args=relayArgs(config);
+  const hostConfig=config.hostConfig||path.join(config.deploymentDir,'host-executor.json');
+  const home=path.dirname(hostConfig)===config.deploymentDir
+    ? (await read(hostConfig)).agents?.find(agent=>agent.workspace===config.workspace)?.toolsHome : undefined;
+  if(typeof home!=='string'||!path.isAbsolute(home))throw Error('Missing broker registry binding');
+  const files=[hostConfig,path.join(home,'registry.json'),path.join(home,'config.json')];
+  const hashes=await Promise.all(files.map(async file=>digest(await fs.readFile(file))));
+  // Supply trusted read-only code so rollback can check an older image that
+  // predates this diagnostic. Its validators still come from that image.
+  const diagnostic=await fs.readFile(new URL('../../docker/broker-readiness.mjs',import.meta.url),'utf8');
+  const probe=JSON.parse(await run('docker',[...args,'exec','-T','plugin-broker','node','--import','/app/node_modules/tsx/dist/loader.mjs',
+    '--input-type=module','-e',diagnostic,...hashes],{stdoutOnly:true,timeout:60000}));
+  if(probe.version!==1||probe.ready!==true||probe.hostSha256!==hashes[0]||probe.registrySha256!==hashes[1]||probe.configSha256!==hashes[2])
+    throw Error('Invalid isolated broker readiness readback');
+  // A concurrent writer invalidates the readback; never silently accept it.
+  for(let i=0;i<files.length;i++)if(digest(await fs.readFile(files[i]))!==hashes[i])throw Error('Broker binding changed during verification');
+  return probe;
+}
+
 const healthCodes = new Set(['RELAY_UNREADABLE','RELAY_NOT_POLLING','RELAY_STALE','HOST_UNREADABLE','HOST_STALE','PLUGIN_BROKER_UNREADABLE']);
 async function healthEvidence(config,run) {
   const id=(await run('docker',[...relayArgs(config),'ps','-q','relay'])).trim();
@@ -140,6 +160,17 @@ export async function perform(home,job,hooks) {
   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();
+  const complete=async()=>{
+    job.status='completed';job.endedAt=new Date().toISOString();await save();
+    try { job.cleanup=await cleanupStaleBackups(home);await save(); }
+    catch(error) { job.cleanupError=error.message;await save().catch(()=>{}); }
+    return job;
+  };
+  const fail=async(error,recoveryHooks)=>{
+    let message=error.message;
+    if(job.target==='main'&&job.rollback&&/is unhealthy/.test(message))message+=await healthEvidence(config,run).catch(()=> '');
+    job.error=message;await save();return recover(home,job,recoveryHooks);
+  };
   try {
     if(job.target==='main') {
       job.packageManager=await packageManager(root,run);await save();
@@ -183,38 +214,44 @@ export async function perform(home,job,hooks) {
         job.brokerReadiness=await refreshBroker(config,run,brokerImage);
       }
     } else {
-      const old=next.old.record,r=await read(path.join(home,'registry.json'));
+      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;});
       const s=await snapshot(root),candidate={...old,source:root,revision:s.revision,manifest:s.manifest,deployment:s.deployment,sharedRevisions:s.sharedRevisions};
       for (const key of old.sharedEnabled || []) if (sharedIdentity(old, key).fingerprint !== sharedIdentity(candidate, key).fingerprint) throw Error('Shared worker changed; disable this client and coordinate an explicit shared worker upgrade before updating');
       await checkFolders(config,candidate,home);
       const stage={...candidate,compose:path.join(dir,'compose.json')};await atomic(stage.compose,await compose(config,stage,secrets,home));
       for(const [service,spec] of Object.entries(stage.deployment.services))await run('docker',[...pluginArgs(stage),spec.image?'pull':'build',service]);
-      const running=Boolean((await run('docker',[...pluginArgs(old),'ps','--status','running','-q'])).trim());
-      job.rollback={record:old,registry:structuredClone(r),compose:await read(old.compose),running};await save();
-      await run('docker',[...pluginArgs(old),'stop']);
-      const backup=path.join(dir,'backup');await fs.mkdir(backup,{mode:0o700});
-      const volumes=new Set(Object.values(old.deployment.services).flatMap(s=>Object.keys(s.volumes||{})));
-      for(const name of volumes)await backupVolume(run,old,name,backup);
-      await atomic(old.compose,await compose(config,candidate,secrets,home));
-      if(running)await run('docker',[...pluginArgs(candidate),'up','-d','--wait','--wait-timeout','90','--no-build']);
-      r.plugins[job.target]=candidate;
-      for(const alias of Object.keys(candidate.manifest.commands))r.commands[alias]=job.target;
-      await atomic(path.join(home,'registry.json'),r);
-      job.brokerReadiness=await refreshBroker(config,run);
-      job.runtimeVerified=running;
+      return await locked(home,async()=>{
+        try {
+          const current=await eligibility(home,job.target,root,job.automatic);
+          if(current.old.root!==job.previousRoot||current.old.pkg.version!==job.previousVersion||JSON.stringify(current.old.record)!==JSON.stringify(old)||JSON.stringify((await state(home)).config)!==JSON.stringify(config))throw Error('Stale upgrade job');
+          if(await brokerNeedsRefresh(config,run)&&!hooks.refreshPluginBroker)throw Error('Broker host binding changed; retry the plugin update after native work drains');
+          const r=await read(path.join(home,'registry.json'));
+          const running=Boolean((await run('docker',[...pluginArgs(old),'ps','--status','running','-q'])).trim());
+          job.rollback={record:old,registry:structuredClone(r),compose:await read(old.compose),running};await save();
+          await run('docker',[...pluginArgs(old),'stop']);
+          const backup=path.join(dir,'backup');await fs.mkdir(backup,{mode:0o700});
+          const volumes=new Set(Object.values(old.deployment.services).flatMap(s=>Object.keys(s.volumes||{})));
+          for(const name of volumes)await backupVolume(run,old,name,backup);
+          await atomic(old.compose,await compose(config,candidate,secrets,home));
+          if(running)await run('docker',[...pluginArgs(candidate),'up','-d','--wait','--wait-timeout','90','--no-build']);
+          r.plugins[job.target]=candidate;
+          for(const alias of Object.keys(candidate.manifest.commands))r.commands[alias]=job.target;
+          await atomic(path.join(home,'registry.json'),r);
+          job.brokerReadiness=hooks.refreshPluginBroker?await refreshBroker(config,run):await verifyBroker(config,run);
+          await publishBrokerPlugins(home,agent.controlDir);
+          job.runtimeVerified=running;
+          return await complete();
+        } catch(error) { return fail(error,{...hooks,registryLocked:true}); }
+      },{drainInvocations:true,signal:hooks.signal});
     }
-    job.status='completed';job.endedAt=new Date().toISOString();await save();
-    try { job.cleanup=await cleanupStaleBackups(home);await save(); }
-    catch(error) { job.cleanupError=error.message;await save().catch(()=>{}); }
-    return job;
-  }catch(error){
-    let message=error.message;
-    if(job.target==='main'&&job.rollback&&/is unhealthy/.test(message))message+=await healthEvidence(config,run).catch(()=> '');
-    job.error=message;await save();return recover(home,job,hooks);
-  }
+    return await complete();
+  }catch(error){return fail(error,hooks);}
+
 }
 export async function recover(home,job,hooks) {
+  if(job.target!=='main'&&job.rollback&&!hooks.registryLocked)
+    return locked(home,()=>recover(home,job,{...hooks,registryLocked:true}),{drainInvocations:true,signal:hooks.signal});
   const run=hooks.execute||execute,{config}=await state(home);
   try {
     if(job.rollback) {
@@ -239,7 +276,8 @@ export async function recover(home,job,hooks) {
         const b=job.rollback;
         await run('docker',[...pluginArgs(b.record),'stop']);
         await atomic(b.record.compose,b.compose);await atomic(path.join(home,'registry.json'),b.registry);
-        job.rollbackBrokerReadiness=await refreshBroker(config,run);
+        job.rollbackBrokerReadiness=hooks.refreshPluginBroker?await refreshBroker(config,run):await verifyBroker(config,run);
+        await publishBrokerPlugins(home,(await state(home)).agent.controlDir);
         if(b.running)await run('docker',[...pluginArgs(b.record),'up','-d','--wait','--wait-timeout','90','--no-build']);
       }
       job.status='rolled-back';

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 } from './runtime.mjs';
+import { perform, environment, brokerNeedsRefresh } from './runtime.mjs';
 
 const reservedProviderKeys=new Set(['HOME','LANG','LC_ALL','LOGNAME','PATH','SHELL','TERM','TMPDIR','USER','CODEX_HOME','NODE_OPTIONS']);
 const providerEnvironmentKey=value=>{
@@ -52,6 +52,11 @@ export async function withIdleUpgrade(control,job,signal,apply,{isIdle=idle,wait
     if(!signal.aborted)return await apply();
   } finally {await fs.rm(pause,{force:true});}
 }
+// 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(!signal.aborted)return apply();
+}
 export async function queueAutomatic(home,available) {
   const existing=await jobs(home);
   if(existing.some(job=>['queued','applying','recovery-required'].includes(job.status)))return null;
@@ -94,6 +99,15 @@ export async function supervise(deployment,signal,{discover=check}={}) {
     await waitForHostHeartbeat(agent.controlDir,child,()=>error);
   };
   const pause=path.join(agent.controlDir,'upgrade-pause.json');
+  const refreshRequirement=async job=>{
+    if(job.target==='main')return false;
+    try {return await brokerNeedsRefresh((await state(home)).config);}
+    catch(error) {
+      job.status=job.status==='applying'?'recovery-required':'failed';job.error=error.message;
+      await atomic(path.join(jobPath(home,job.id),'job.json'),job);
+      return null;
+    }
+  };
   const beat=setInterval(()=>{void atomic(path.join(directory,'supervisor.json'),{pid:process.pid,at:Date.now()}).catch(()=>{});},1000);
   try {
     await atomic(path.join(directory,'supervisor.json'),{pid:process.pid,at:Date.now()});
@@ -107,8 +121,11 @@ export async function supervise(deployment,signal,{discover=check}={}) {
     await sleep(1200);
     const interrupted=(await jobs(home)).find(j=>j.status==='applying');
     if(interrupted){
-      await atomic(pause,{id:interrupted.id});const result=await locked(home,()=>perform(home,interrupted,{stopHost,startHost}));await fs.rm(pause,{force:true});
-      if(result.status==='completed'&&interrupted.target==='main')return;
+      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;
     }
     const isolated=host.isolation==='isolated'
     if(!isolated && !child)await startHost((await state(home)).config.packageRoot);
@@ -117,15 +134,19 @@ export async function supervise(deployment,signal,{discover=check}={}) {
       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');
       if(pending) {
-        const result=await withIdleUpgrade(agent.controlDir,pending,signal,async()=>{
+        const refreshPluginBroker=await refreshRequirement(pending);
+        if(refreshPluginBroker===null)continue;
+        const apply=async()=>{
           try {
-            return await locked(home,async()=>{const latest=await read(path.join(jobPath(home,pending.id),'job.json'));return perform(home,latest,{stopHost,startHost});});
+            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,{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;
           nextCheck=0;

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)