@jc_stack/ez-agents 0.1.0-beta.33 → 0.1.0-beta.36

package/src/telegram-provisioning.ts

@@ -0,0 +1,214 @@
+import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import { spawn } from 'node:child_process'
+import { parseEnv } from 'node:util'
+import path from 'node:path'
+
+export type TelegramProvisioningConfig = {
+  version: 1
+  composeFile: string
+  projectDirectory: string
+  projectName: string
+  service: 'relay'
+  relayEnvFile: string
+  overrideFile: string
+}
+
+type ComposeRunner = (args: string[], environment: NodeJS.ProcessEnv) => Promise<void>
+
+const botToken = (value: string) => value.length <= 512 && /^\d{5,}:[A-Za-z0-9_-]{20,}$/.test(value)
+const projectName = (value: string) => /^[a-z0-9][a-z0-9_-]{0,62}$/.test(value)
+const redactToken = (value: string) => value.replace(/\d{5,}:[A-Za-z0-9_-]{20,}/g, '[redacted]')
+
+const containedBy = (parent: string, child: string) => {
+  const relative = path.relative(parent, child)
+  return Boolean(relative) && !relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative)
+}
+
+const resolveInside = async (file: string): Promise<string> => {
+  const tail: string[] = []
+  let current = file
+  for (let depth = 0; depth < 100; depth++) {
+    try {
+      return path.join(await realpath(current), ...tail)
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+      tail.unshift(path.basename(current))
+      const parent = path.dirname(current)
+      if (parent === current) throw error
+      current = parent
+    }
+  }
+  throw new Error('Provisioning path is too deep')
+}
+
+const absoluteRegularFile = async (file: string, ownerOnly = false): Promise<void> => {
+  if (!path.isAbsolute(file) || /[\r\n\0]/.test(file)) throw new Error('Provisioning paths must be absolute single-line paths')
+  const info = await lstat(file)
+  if (!info.isFile() || info.isSymbolicLink()) throw new Error('Provisioning files must be regular files')
+  if (ownerOnly && (info.mode & 0o077)) throw new Error('Provisioning configuration must be owner-only')
+}
+
+const privateWrite = async (file: string, content: string) => {
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 })
+  const temporary = `${file}.${randomUUID()}.tmp`
+  try {
+    await writeFile(temporary, content, { mode: 0o600, flag: 'wx' })
+    await rename(temporary, file)
+  } finally {
+    await rm(temporary, { force: true })
+  }
+}
+
+const previousFile = async (file: string): Promise<string | null> => {
+  try {
+    await absoluteRegularFile(file)
+    return await readFile(file, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
+    throw error
+  }
+}
+
+const restoreFile = async (file: string, previous: string | null) => {
+  if (previous === null) await rm(file, { force: true })
+  else await privateWrite(file, previous)
+}
+
+const parseConfig = (value: unknown): TelegramProvisioningConfig => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid Telegram provisioning configuration')
+  const config = value as Record<string, unknown>
+  if (Object.keys(config).sort().join(',') !== 'composeFile,overrideFile,projectDirectory,projectName,relayEnvFile,service,version')
+    throw new Error('Invalid Telegram provisioning configuration')
+  if (config.version !== 1 || config.service !== 'relay' || ![config.composeFile, config.projectDirectory, config.projectName, config.relayEnvFile, config.overrideFile].every(value => typeof value === 'string'))
+    throw new Error('Invalid Telegram provisioning configuration')
+  const parsed = config as unknown as TelegramProvisioningConfig
+  if (!projectName(parsed.projectName)) throw new Error('Invalid Telegram provisioning configuration')
+  return parsed
+}
+
+// The deployment records its installed relay image and runtime values in its
+// own docker.env; provisioning must use that record instead of a self-set tag.
+const deploymentEnvironment = async (projectDirectory: string): Promise<{ file: string; values: NodeJS.Dict<string> } | null> => {
+  const file = path.join(projectDirectory, 'docker.env')
+  let text: string
+  try {
+    await absoluteRegularFile(file)
+    text = await readFile(file, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
+    throw error
+  }
+  const values = parseEnv(text)
+  if (!values.EZ_RELAY_IMAGE?.trim()) throw new Error('Deployment docker.env must define EZ_RELAY_IMAGE; provisioning never selects an image')
+  return { file, values }
+}
+
+export const readTelegramProvisioningConfig = async (configFile: string): Promise<TelegramProvisioningConfig> => {
+  await absoluteRegularFile(configFile, true)
+  const config = parseConfig(JSON.parse(await readFile(configFile, 'utf8')))
+  if (!path.isAbsolute(config.projectDirectory) || /[\r\n\0]/.test(config.projectDirectory)) throw new Error('Invalid Telegram provisioning configuration')
+  const projectInfo = await lstat(config.projectDirectory).catch(() => { throw new Error('Invalid Telegram provisioning configuration') })
+  if (!projectInfo.isDirectory()) throw new Error('Invalid Telegram provisioning configuration')
+  const projectDirectory = await realpath(config.projectDirectory)
+  await absoluteRegularFile(config.composeFile)
+  for (const file of [config.relayEnvFile, config.overrideFile]) {
+    if (!path.isAbsolute(file) || /[\r\n\0]/.test(file)) throw new Error('Telegram secrets must remain inside the deployment directory')
+    if (!containedBy(projectDirectory, await resolveInside(file))) throw new Error('Telegram secrets must remain inside the deployment directory')
+  }
+  return config
+}
+
+const composeOverride = (config: TelegramProvisioningConfig) => [
+  'services:',
+  '  relay:',
+  '    environment:',
+  '      EZ_TELEGRAM_ENABLED: "true"',
+  '    secrets:',
+  '      - source: relay_env',
+  '        target: relay_env',
+  'secrets:',
+  '  relay_env:',
+  `    file: ${JSON.stringify(config.relayEnvFile)}`,
+  '',
+].join('\n')
+
+const runDockerCompose: ComposeRunner = async (args, environment) => await new Promise<void>((resolve, reject) => {
+  const child = spawn('docker', ['compose', ...args], { env: environment, stdio: ['ignore', 'pipe', 'pipe'] })
+  let output = ''
+  const capture = (chunk: Buffer) => { if (output.length < 4096) output += chunk.toString('utf8').slice(0, 4096 - output.length) }
+  child.stdout.on('data', capture)
+  child.stderr.on('data', capture)
+  child.once('error', reject)
+  child.once('close', (code) => code === 0 ? resolve() : reject(new Error(`Telegram relay could not start (${code ?? 'unknown'}): ${redactToken(output.replace(/\s+/g, ' ').trim()) || 'no diagnostic'}`)))
+})
+
+const composeArguments = (config: TelegramProvisioningConfig, includeOverride: boolean, envFile: string | null) => [
+  '--project-directory', config.projectDirectory,
+  '--project-name', config.projectName,
+  ...(envFile ? ['--env-file', envFile] : []),
+  '-f', config.composeFile,
+  ...(includeOverride ? ['-f', config.overrideFile] : []),
+  'up', '-d', '--wait', config.service,
+]
+
+export const provisionTelegramBot = async (
+  configFile: string,
+  token: string,
+  runCompose: ComposeRunner = runDockerCompose,
+): Promise<void> => {
+  if (!botToken(token)) throw new Error('Invalid Telegram bot token')
+  const config = await readTelegramProvisioningConfig(configFile)
+  const deployment = await deploymentEnvironment(config.projectDirectory)
+  // The deployment's docker.env must win compose interpolation: the shell
+  // takes precedence over --env-file, so a stale exported EZ_RELAY_IMAGE or
+  // EZ_AGENT_WORKSPACE could otherwise restart the relay on the wrong image
+  // or mounts. Compose tooling variables (DOCKER_*, PATH, HOME) stay intact.
+  const runnerEnvironment = { ...process.env }
+  delete runnerEnvironment.TELEGRAM_BOT_TOKEN
+  for (const key of Object.keys(deployment?.values ?? {})) {
+    if (key.startsWith('EZ_') || key.startsWith('COMPOSE_')) delete runnerEnvironment[key]
+  }
+  const envFile = deployment?.file ?? null
+  const lock = path.join(config.projectDirectory, 'telegram-provisioning.lock')
+  try {
+    await writeFile(lock, JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }), { mode: 0o600, flag: 'wx' })
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+    let stale = false
+    try {
+      const prior = JSON.parse(await readFile(lock, 'utf8')) as { pid: unknown; startedAt: unknown }
+      if (Number.isSafeInteger(prior.pid)) {
+        try { process.kill(prior.pid as number, 0) }
+        catch (signal) { if ((signal as NodeJS.ErrnoException).code === 'ESRCH') stale = true }
+      }
+      if (!stale && typeof prior.startedAt === 'string' && Date.now() - Date.parse(prior.startedAt) > 3600_000) stale = true
+    } catch {
+      throw new Error('Telegram setup is already in progress (remove telegram-provisioning.lock if no setup is running)')
+    }
+    if (!stale) throw new Error('Telegram setup is already in progress')
+    await rm(lock, { force: true })
+    await writeFile(lock, JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }), { mode: 0o600, flag: 'wx' })
+  }
+
+  const previousSecret = await previousFile(config.relayEnvFile)
+  const previousOverride = await previousFile(config.overrideFile)
+  try {
+    await privateWrite(config.relayEnvFile, `TELEGRAM_BOT_TOKEN=${token}\n`)
+    await privateWrite(config.overrideFile, composeOverride(config))
+    await runCompose(composeArguments(config, true, envFile), runnerEnvironment)
+  } catch (error) {
+    const restored = await Promise.allSettled([restoreFile(config.relayEnvFile, previousSecret), restoreFile(config.overrideFile, previousOverride)])
+    try {
+      await runCompose(composeArguments(config, previousOverride !== null, envFile), runnerEnvironment)
+    } catch (rollbackError) {
+      console.error(`Telegram rollback restart failed: ${redactToken(rollbackError instanceof Error ? rollbackError.message : String(rollbackError))}`)
+    }
+    for (const result of restored) {
+      if (result.status === 'rejected') console.error(`Telegram rollback restore failed: ${redactToken(result.reason instanceof Error ? result.reason.message : String(result.reason))}`)
+    }
+    throw error
+  } finally {
+    await rm(lock, { force: true })
+  }
+}

package/src/updates/control.mjs

@@ -1,6 +1,7 @@
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { parseEnv } from 'node:util';
 import { atomic, locked, snapshot } from '../plugins/manager.mjs';
 import { digest, extract, newer, compatible, version, releaseContract, registryVersion, registryCandidate, download } from './artifact.mjs';
 
@@ -8,6 +9,11 @@ export const read = async file => JSON.parse(await fs.readFile(file,'utf8'));
 export const missing = error => {if(error.code!=='ENOENT')throw error;return null;};
 export const targetId = value => {if(value!=='main'&&!/^[a-z][a-z0-9-]{0,39}$/.test(value))throw Error('Invalid update target');return value;};
 const jobId=/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const compatibilityBuild=/^(.+)\.compat\.\d+$/;
+const upgradeable=(candidate,installed)=>{
+  const match=compatibilityBuild.exec(installed);
+  return newer(candidate,installed)||Boolean(match&&match[1]===candidate);
+};
 export const updateHome = home => path.join(home,'updates');
 export async function state(home) {
   const config=await read(path.join(home,'config.json'));
@@ -39,7 +45,7 @@ export async function check(home) {
         continue;
       }
       const candidate=await registryCandidate(old.pkg.name,p.channel);
-      results.push({target,installed:old.pkg.version,available:candidate?.version??null,newer:Boolean(candidate&&newer(candidate.version,old.pkg.version)),policy:p,package:old.pkg.name});
+      results.push({target,installed:old.pkg.version,available:candidate?.version??null,newer:Boolean(candidate&&upgradeable(candidate.version,old.pkg.version)),policy:p,package:old.pkg.name});
     }catch(error){results.push({target,error:error.message});}
   }
   return results;
@@ -52,27 +58,74 @@ function additiveCommands(previous,next) {
   for(const [name,command] of Object.entries(previous.commands||{}))if(!same(next.commands?.[name],command))return false;
   return Object.values(next.commands||{}).every(command=>next.services?.[command.service]);
 }
+function normalizedLibraryManifest(value) {
+  const result=JSON.parse(JSON.stringify(value));delete result.version;delete result.commands?.['library-document'];return result;
+}
+function normalizedLibraryDeployment(value) {
+  const result=JSON.parse(JSON.stringify(value));delete result.commands?.['library-document'];
+  if(result.commands?.['library-query'])result.commands['library-query'].argv=['node','/app/bin/ez-library.mjs','search'];
+  return result;
+}
+export function reviewedPluginDeploymentMigration(target,old,next) {
+  if(target!=='library'||old?.manifest?.id!=='library'||old.manifest.version!=='0.1.0-beta.13.qa.4'||next?.manifest?.id!=='library'||next.manifest.version!=='0.1.0-beta.14')return undefined;
+  const oldQuery=old.deployment?.commands?.['library-query'],nextQuery=next.deployment?.commands?.['library-query'];
+  const expected=['node','/app/bin/ez-library.mjs'];
+  if(!same(oldQuery?.argv,[...expected,'query-context'])||!same(nextQuery?.argv,[...expected,'search']))return undefined;
+  if(!old.deployment?.commands?.['library-document']||next.deployment?.commands?.['library-document']!==undefined||!old.manifest?.commands?.['library-document']||next.manifest?.commands?.['library-document']!==undefined)return undefined;
+  if(!same(normalizedLibraryManifest(old.manifest),normalizedLibraryManifest(next.manifest))||!same(normalizedLibraryDeployment(old.deployment),normalizedLibraryDeployment(next.deployment)))return undefined;
+  return {id:'library-query-contract-v1',files:['ez-plugin.json','ez-deployment.json'],changes:['remove library-document','route library-query through search']};
+}
+// Beta.34 added an optional isolation variable and moved a Compose fallback
+// behind the already-bound purpose-file variable. Existing deployments must
+// retain their effective runtime, while future service/volume/privilege changes
+// remain a separately reviewed migration.
+const compatibleRuntimeMigration='legacy-runtime-v1';
+function effectiveCompose(text,env) {
+  const lines=text.split(/\r?\n/);
+  return lines.filter((line,index)=>{
+    const match=/^(\s+)EZ_ISOLATION: \$\{EZ_ISOLATION:-\}\s*$/.exec(line);
+    return !(match&&!env.EZ_ISOLATION?.trim()&&lines[index-1]?.trim()==='EZ_AGENT_PURPOSE_FILE: /run/agent-purpose.md');
+  }).map(line=>line.replace(/^(\s*file:\s*)\$\{EZ_AGENT_PURPOSE_FILE:-(\.\/templates\/agent\/SOUL\.md|\.\/templates\/agent-purpose\.md)\}(\s*)$/,(whole,prefix,_fallback,suffix)=>
+    env.EZ_AGENT_PURPOSE_FILE?.trim()?`${prefix}\${EZ_AGENT_PURPOSE_FILE}${suffix}`:whole)).join('\n');
+}
+async function mainDeployment(home,oldRoot,nextRoot) {
+  const oldCompose=await fs.readFile(path.join(oldRoot,'compose.yaml'),'utf8'),nextCompose=await fs.readFile(path.join(nextRoot,'compose.yaml'),'utf8');
+  const oldWhatsApp=await fs.readFile(path.join(oldRoot,'compose.whatsapp.yaml')),nextWhatsApp=await fs.readFile(path.join(nextRoot,'compose.whatsapp.yaml'));
+  if(oldCompose===nextCompose&&oldWhatsApp.compare(nextWhatsApp)===0)return undefined;
+  const {config}=await state(home);
+  // Legacy QA homes may predate docker.env. Treat that file as empty while
+  // keeping all other read failures fatal; explicit runtime bindings still
+  // come from the deployment environment when the file exists.
+  const envText=await fs.readFile(path.join(config.deploymentDir,'docker.env'),'utf8').catch(error=>{
+    if(error.code==='ENOENT')return '';
+    throw error;
+  });
+  const env=parseEnv(envText);
+  if(oldWhatsApp.compare(nextWhatsApp)!==0||effectiveCompose(oldCompose,env)!==effectiveCompose(nextCompose,env))throw Error('Runtime deployment changed; a separately reviewed migration is required');
+  return {id:compatibleRuntimeMigration,files:['compose.yaml']};
+}
 export async function eligibility(home,target,root,automatic) {
   const old=await installed(home,target),pkg=await read(path.join(root,'package.json')),kind=target==='main'?'main':'plugin';
   if(pkg.name!==old.pkg.name)throw Error('Package identity mismatch');
   const next=releaseContract(pkg,kind),prior=releaseContract(old.pkg,kind);
   if(next.stateSchema!==prior.stateSchema)throw Error('State migration is unsupported by this updater; do not replace the installation');
-  if(!newer(pkg.version,old.pkg.version))throw Error('Candidate must be newer than the installed version');
-  let revision;
+  if(!upgradeable(pkg.version,old.pkg.version))throw Error('Candidate must be newer than the installed version');
+  let revision,deploymentMigration;
   if(kind==='plugin') {
     const s=await snapshot(root);revision=s.revision;
     if(s.manifest.id!==target||s.manifest.version!==pkg.version)throw Error('Plugin identity/version mismatch');
-    if(!additiveCommands(old.record.deployment,s.deployment))throw Error('Deployment permissions/layout changed; a separately reviewed migration is required');
+    deploymentMigration=reviewedPluginDeploymentMigration(target,old.record,{manifest:s.manifest,deployment:s.deployment});
+    if(!additiveCommands(old.record.deployment,s.deployment)&&!deploymentMigration)throw Error('Deployment permissions/layout changed; a separately reviewed migration is required');
     const registry=await read(path.join(home,'registry.json'));
     for(const alias of Object.keys(s.manifest.commands))if(registry.commands[alias]&&registry.commands[alias]!==target)throw Error('CLI alias collision');
   }else {
-    for(const file of ['compose.yaml','compose.whatsapp.yaml'])if(!Buffer.from(await fs.readFile(path.join(root,file))).equals(await fs.readFile(path.join(old.root,file))))throw Error('Runtime deployment changed; a separately reviewed migration is required');
+    deploymentMigration=await mainDeployment(home,old.root,root);
   }
   if(automatic) {
     const p=await policy(home,target);
     if(!p.automatic||!compatible(pkg.version,old.pkg.version)||(p.channel==='stable'&&version(pkg.version).pre))throw Error('Candidate is outside automatic update policy');
   }
-  return {old,pkg,revision};
+  return {old,pkg,revision,deploymentMigration};
 }
 export async function prepare(home,target,{file,release}) {
   targetId(target);if(Boolean(file)===Boolean(release))throw Error('Supply one --file tarball or --version exact-version');
@@ -87,7 +140,7 @@ export async function prepare(home,target,{file,release}) {
     const next=await eligibility(home,target,root,false);
     if(origin.type==='npm'&&next.pkg.version!==origin.version)throw Error('Artifact version differs from registry metadata');
     await fs.writeFile(path.join(dir,'candidate.tgz'),data,{mode:0o600,flag:'wx'});
-    const job={id,target,source:root,releaseNotes:path.join(root,'CHANGELOG.md'),status:'prepared',version:next.pkg.version,previousVersion:next.old.pkg.version,previousRoot:next.old.root,sha256:digest(data),origin,createdAt:new Date().toISOString()};
+    const job={id,target,source:root,releaseNotes:path.join(root,'CHANGELOG.md'),status:'prepared',version:next.pkg.version,previousVersion:next.old.pkg.version,previousRoot:next.old.root,sha256:digest(data),origin,...(next.deploymentMigration?{deploymentMigration:next.deploymentMigration}:{}),createdAt:new Date().toISOString()};
     await atomic(path.join(dir,'job.json'),job);return job;
   } catch(error){await fs.rm(dir,{recursive:true,force:true});throw error;}
 }
@@ -102,6 +155,23 @@ export async function jobs(home) {
   const found=await Promise.all(entries.filter(e=>e.isDirectory()&&jobId.test(e.name)).map(e=>read(path.join(jobPath(home,e.name),'job.json')).catch(missing)));
   return found.filter(Boolean);
 }
+const jobTime=job=>{const value=Date.parse(job.endedAt||job.createdAt||'');return Number.isFinite(value)?value:0;};
+const laterJob=(a,b)=>jobTime(a)>jobTime(b)||(jobTime(a)===jobTime(b)&&a.id>b.id);
+const terminalStatuses=new Set(['completed','failed','rolled-back']);
+export async function cleanupStaleBackups(home) {
+  const records=await jobs(home),latest=new Map();
+  for(const job of records.filter(item=>item.status==='completed')) {
+    const prior=latest.get(job.target);if(!prior||laterJob(job,prior))latest.set(job.target,job);
+  }
+  const removed=[];
+  for(const job of records) {
+    const current=latest.get(job.target);
+    if(!terminalStatuses.has(job.status)||!current||current.id===job.id)continue;
+    const backup=path.join(jobPath(home,job.id),'backup');
+    if(await fs.stat(backup).catch(missing)){await fs.rm(backup,{recursive:true,force:true});removed.push(job.id);}
+  }
+  return {kept:[...latest.values()].map(job=>job.id),removed};
+}
 async function requireSupervisor(directory) {
   const h=await read(path.join(directory,'supervisor.json'));
   if(!Number.isFinite(h.at)||Date.now()-h.at>10000||h.at>Date.now()+5000)throw Error('Upgrade supervisor is offline or heartbeat is invalid');

package/src/updates/runtime.mjs

@@ -2,18 +2,22 @@ import { sharedIdentity } from '../plugins/shared.mjs';
 import * as fs from 'node:fs/promises';
 import { createWriteStream } from 'node:fs';
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { spawn } from 'node:child_process';
+import { parseEnv } from 'node:util';
 import { atomic, compose, snapshot, checkFolders } from '../plugins/manager.mjs';
-import { read, state, eligibility, jobPath } from './control.mjs';
+import { read, state, eligibility, jobPath, cleanupStaleBackups } from './control.mjs';
 import { bindUpdates } from './binding.mjs';
 import { extract, digest } from './artifact.mjs';
 
 export function environment() {
-  return Object.fromEntries(['HOME','PATH','LANG','LC_ALL','TMPDIR','DOCKER_HOST','DOCKER_CONTEXT','DOCKER_CONFIG','BUILDX_CONFIG'].filter(k=>process.env[k]!==undefined).map(k=>[k,process.env[k]]));
+  return Object.fromEntries(['HOME','PATH','LANG','LC_ALL','TMPDIR','DOCKER_HOST','DOCKER_CONTEXT','DOCKER_CONFIG','BUILDX_CONFIG','EZ_DOCKER_COMPOSE'].filter(k=>process.env[k]!==undefined).map(k=>[k,process.env[k]]));
 }
 export function execute(command,args,options={}) {
   return new Promise((resolve,reject)=>{
-    const child=spawn(command,args,{cwd:options.cwd,env:environment(),stdio:['ignore','pipe','pipe']});let output='';
+    const invocation=process.env.EZ_DOCKER_COMPOSE==='standalone'&&command==='docker'&&args[0]==='compose'
+      ? {command:'docker-compose',args:args.slice(1)} : {command,args};
+    const child=spawn(invocation.command,invocation.args,{cwd:options.cwd,env:environment(),stdio:['ignore','pipe','pipe']});let output='';
     const timer=setTimeout(()=>child.kill('SIGKILL'),options.timeout||600000);
     const file=options.outputFile?createWriteStream(options.outputFile,{flags:'wx',mode:0o600}):null;
     const written=file?new Promise((resolve,reject)=>{file.once('finish',resolve);file.once('error',reject);}):Promise.resolve();
@@ -21,7 +25,7 @@ export function execute(command,args,options={}) {
     child.stderr.on('data',b=>{output=(output+b).slice(-16000);});
     void written.catch(()=>child.kill('SIGKILL'));
     child.once('error',error=>{clearTimeout(timer);reject(error);});
-    child.once('close',async code=>{clearTimeout(timer);try{await written;if(code!==0)throw Error(`${command} failed (${code}): ${output}`);resolve(output);}catch(error){reject(error);}});
+    child.once('close',async code=>{clearTimeout(timer);try{await written;if(code!==0)throw Error(`${invocation.command} failed (${code}): ${output}`);resolve(output);}catch(error){reject(error);}});
   });
 }
 export async function textAtomic(file,text) {
@@ -43,7 +47,18 @@ export async function packageManager(root,run=execute) {
   throw Error(`Upgrade prerequisite unavailable: ${required}. ${failures.join('; ')}. Check the host supervisor service PATH (shell aliases do not count). Reuse its installed pnpm or Corepack; expose the launcher directory to that service and restart it after the current turn. If neither exists, provision the pinned manager first. Do not substitute npm install or reinstall the agent. After repair, prepare/apply a new job when status is failed; recover is only for recovery-required.`);
 }
 export const relayArgs = config => ['compose','--env-file',path.join(config.deploymentDir,'docker.env')];
-const healthCodes = new Set(['RELAY_UNREADABLE','RELAY_NOT_POLLING','RELAY_STALE','HOST_UNREADABLE','HOST_STALE']);
+// The managed guidance block is replaced only during an upgrade, never by
+// relay/host startup. Malformed personal text stays untouched and only logs.
+async function replaceGuidance(root, workspace, run) {
+  const entry = path.join(root, 'src', 'agent-guidance.ts');
+  const script = `const m = await import(${JSON.stringify(pathToFileURL(entry).href)}); await m.installAgentGuidance(${JSON.stringify(workspace)});`;
+  await run(process.execPath, ['--import', path.join(root, 'node_modules/tsx/dist/loader.mjs'), '--input-type=module', '-e', script], { cwd: root, timeout: 60000 });
+}
+export async function relayServices(config) {
+  const env = await fs.readFile(path.join(config.deploymentDir,'docker.env'),'utf8').catch(() => '');
+  return parseEnv(env).EZ_EXECUTOR_TRANSPORT === 'local' ? ['relay','plugin-broker'] : ['relay'];
+}
+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();
   if(!/^[a-f0-9]{12,64}$/i.test(id))return '';
@@ -89,6 +104,8 @@ export async function perform(home,job,hooks) {
       await fs.copyFile(path.join(root,'docker/pnpm-lock.yaml'),path.join(root,'pnpm-lock.yaml'));
       await run(job.packageManager.command,[...job.packageManager.args,'install','--frozen-lockfile','--ignore-scripts'],{cwd:root});
       await run(process.execPath,['--import',path.join(root,'node_modules/tsx/dist/loader.mjs'),path.join(root,'bin/ezenciel-agents.mjs'),'--version'],{cwd:root});
+      try { await replaceGuidance(root, config.workspace, run); }
+      catch(error) { console.error(`Workspace guidance replacement failed; upgrade continues: ${error.message}`); }
       const image=`ez-upgrade-${job.sha256.slice(0,24)}`;
       await run('docker',['build','--target','runtime','-t',image,root]);
       const envFile=path.join(config.deploymentDir,'docker.env'),oldEnv=await fs.readFile(envFile,'utf8');
@@ -105,13 +122,13 @@ export async function perform(home,job,hooks) {
       await textAtomic(envFile,env);
       await bindUpdates(home,path.join(config.deploymentDir,'host-executor.json'),root);
       await hooks.startHost(root);
-      await run('docker',[...relayArgs(config),'up','-d','--wait','--wait-timeout','90','--no-build','relay']);
+      await run('docker',[...relayArgs(config),'up','-d','--wait','--wait-timeout','90','--no-build',...(await relayServices(config))]);
     } else {
       const old=next.old.record,r=await read(path.join(home,'registry.json'));
       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);
+      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','-q'])).trim());
@@ -127,7 +144,10 @@ export async function perform(home,job,hooks) {
       await atomic(path.join(home,'registry.json'),r);
       job.runtimeVerified=running;
     }
-    job.status='completed';job.endedAt=new Date().toISOString();await save();return job;
+    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(()=> '');
@@ -143,7 +163,7 @@ export async function recover(home,job,hooks) {
         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);
-        await run('docker',[...relayArgs(config),'up','-d','--wait','--wait-timeout','90','--no-build','relay']);
+        await run('docker',[...relayArgs(config),'up','-d','--wait','--wait-timeout','90','--no-build',...(await relayServices(config))]);
       } else {
         const b=job.rollback;
         await run('docker',[...pluginArgs(b.record),'stop']);

package/src/updates/status.mjs

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { read, state, jobs } from './control.mjs';
 import { execute, pluginArgs } from './runtime.mjs';
+import { callDeliverySocket } from '../delivery-socket-client.mjs';
 
 async function heartbeat(file,maxAge,polling=false) {
   try {
@@ -10,11 +11,32 @@ async function heartbeat(file,maxAge,polling=false) {
   }catch(error){return {state:error.code==='ENOENT'?'offline':'unknown',runningVersion:null};}
 }
 
+// The relay owns liveness in memory and answers through the control-volume
+// socket; the legacy heartbeat file remains the fallback when it is offline.
+async function relay(control) {
+  const status=await callDeliverySocket(path.join(control,'delivery.sock'),{op:'status'},2000).catch(()=>null);
+  if(status)return {state:status.polling===true?'running':'offline',runningVersion:typeof status.version==='string'?status.version:null};
+  return heartbeat(path.join(control,'heartbeat.json'),20000,true);
+}
+
 async function plugin(record,run) {
   const result={id:record.manifest.id,installedVersion:record.manifest.version,runningVersion:null,state:'unknown',services:[]};
   try {
-    const output=(await run('docker',[...pluginArgs(record),'ps','--all','--format','json'],{timeout:15000})).trim();
-    const rows=output?output.startsWith('[')?JSON.parse(output):output.split('\n').map(line=>JSON.parse(line)):[];
+    let rows;
+    if(process.env.EZ_DOCKER_COMPOSE==='standalone') {
+      const output=(await run('docker',[...pluginArgs(record),'ps','--all','-q'],{timeout:15000})).trim();
+      const ids=output?output.split('\n').filter(Boolean):[];
+      rows=await Promise.all(ids.map(async id=>{
+        if(!/^[a-f0-9]{12,64}$/i.test(id))throw Error('Invalid container identity');
+        const inspected=JSON.parse(await run('docker',['inspect',id],{timeout:15000}))[0];
+        const labels=inspected?.Config?.Labels||{},state=inspected?.State||{};
+        return {ID:id,Service:labels['com.docker.compose.service'],State:state.Status,Health:state.Health?.Status||null};
+      }));
+    } else {
+      const output=(await run('docker',[...pluginArgs(record),'ps','--all','--format','json'],{timeout:15000})).trim();
+      const json=output.slice(output.search(/^[[{]/m));
+      rows=!json?[]:json.startsWith('[')?JSON.parse(json):json.split('\n').map(line=>line.trim()).filter(line=>line.startsWith('{')).map(line=>JSON.parse(line));
+    }
     for(const [service,spec] of Object.entries(record.deployment.services)) {
       const containers=rows.filter(row=>row.Service===service);
       if(!containers.length){result.services.push({service,state:'not-created',health:null,imageMatches:false});continue;}
@@ -47,7 +69,7 @@ export async function status(home,run=execute) {
   let installedVersion=null;
   try {installedVersion=(await read(path.join(config.packageRoot,'package.json'))).version;}catch {}
   return {
-    main:{installedVersion,...await heartbeat(path.join(agent.controlDir,'heartbeat.json'),20000,true),
+    main:{installedVersion,...await relay(agent.controlDir),
       host:await heartbeat(path.join(agent.controlDir,'host-executor/heartbeat.json'),15000)},
     plugins:await Promise.all(Object.values(registry.plugins).map(record=>plugin(record,run))),
     jobs:(await jobs(home)).map(({rollback,...job})=>job)

package/src/updates/supervisor.mjs

@@ -3,21 +3,30 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawn } from 'node:child_process';
 import { atomic, locked } from '../plugins/manager.mjs';
-import { state, read, jobs, jobPath, check, missing } from './control.mjs';
+import { callDeliverySocket } from '../delivery-socket-client.mjs';
+import { state, read, jobs, jobPath, check, missing, cleanupStaleBackups } from './control.mjs';
 import { perform, environment } from './runtime.mjs';
-import { digest } from './artifact.mjs';
+
+const reservedProviderKeys=new Set(['HOME','LANG','LC_ALL','LOGNAME','PATH','SHELL','TERM','TMPDIR','USER','CODEX_HOME','NODE_OPTIONS']);
+const providerEnvironmentKey=value=>{
+  if(typeof value!=='string'||value.length>64||!/^[A-Z][A-Z0-9_]{1,63}$/.test(value))throw Error('Invalid Codex provider environment key');
+  if(reservedProviderKeys.has(value)||value.startsWith('EZ_')||value.startsWith('TELEGRAM_'))throw Error('Reserved Codex provider environment key');
+  return value;
+};
+
+export function providerEnvironment(host, environment=process.env) {
+  const names=(host.agents||[]).flatMap(agent=>(agent.codexProviders||[]).map(provider=>providerEnvironmentKey(provider.envKey)));
+  return Object.fromEntries([...new Set(names)].flatMap(name=>environment[name]===undefined?[]:[[name,environment[name]]]));
+}
 
 const sleep=ms=>new Promise(resolve=>setTimeout(resolve,ms));
 export async function idle(control) {
   const host=await fs.readdir(path.join(control,'host-executor')).catch(e=>{if(e.code==='ENOENT')return [];throw e;});
   if(host.some(f=>f.endsWith('.running.json')||f.endsWith('.request.json')))return false;
-  for(const file of await fs.readdir(path.join(control,'runs')).catch(e=>{if(e.code==='ENOENT')return [];throw e;})) {
-    if(file.endsWith('.json')&&(await read(path.join(control,'runs',file))).status==='running')return false;
-  }
-  return true;
-}
-export async function notice(control,key) {
-  await atomic(path.join(control,'update-attention.json'),{id:digest(key)});
+  // Run records live in relay memory: the live socket status is the only
+  // cross-process view of active work. A down relay cannot own a run.
+  const status=await callDeliverySocket(path.join(control,'delivery.sock'),{op:'status'},2000).catch(()=>null);
+  return !status||status.running===0;
 }
 export async function supervise(deployment,signal,{discover=check}={}) {
   const host=await read(path.join(deployment,'host-executor.json'));
@@ -38,8 +47,9 @@ export async function supervise(deployment,signal,{discover=check}={}) {
     const timer=setTimeout(()=>running.kill('SIGKILL'),10000);await closed;clearTimeout(timer);
   };
   const startHost=async root=>{
+    if(host.isolation==='isolated')return
     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(),EZ_HOST_SUPERVISOR_PID:String(process.pid)},stdio:['ignore','inherit','inherit']});
+      {env:{...environment(),...providerEnvironment(host),EZ_HOST_SUPERVISOR_PID:String(process.pid)},stdio:['ignore','inherit','inherit']});
     let error;child.once('error',e=>{error=e;});
     for(let n=0;n<100;n++) {
       if(error||child.exitCode!==null)throw error||Error('Host transport failed to start');
@@ -53,6 +63,8 @@ export async function supervise(deployment,signal,{discover=check}={}) {
   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()});
+    try { await cleanupStaleBackups(home); }
+    catch(error) { console.error(`Update backup cleanup failed; host remains running: ${error.message}`); }
     // Reclaim only a lock left by this deployment's dead supervisor, including
     // a crash between queue claim and the first transaction journal write.
     const registryLock=path.join(home,'registry.lock'),owner=await read(registryLock).catch(missing);
@@ -61,11 +73,14 @@ 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});await locked(home,()=>perform(home,interrupted,{stopHost,startHost}));await fs.rm(pause,{force:true});await notice(agent.controlDir,interrupted.id);}
-    if(!child)await startHost((await state(home)).config.packageRoot);
+      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 isolated=host.isolation==='isolated'
+    if(!isolated && !child)await startHost((await state(home)).config.packageRoot);
     let nextCheck=0;
     while(!signal.aborted) {
-      if(child?.exitCode!==null&&child?.exitCode!==undefined)throw Error('Host transport exited; supervisor service should restart');
+      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) {
         await atomic(pause,{id:pending.id});
@@ -73,22 +88,20 @@ export async function supervise(deployment,signal,{discover=check}={}) {
         let quiet=0;
         while(!signal.aborted&&quiet<3){quiet=await idle(agent.controlDir)?quiet+1:0;await sleep(500);}
         if(signal.aborted)break;
+        let result;
         try {
-          await locked(home,async()=>{const latest=await read(path.join(jobPath(home,pending.id),'job.json'));await perform(home,latest,{stopHost,startHost});});
+          result=await locked(home,async()=>{const latest=await read(path.join(jobPath(home,pending.id),'job.json'));return perform(home,latest,{stopHost,startHost});});
         } 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;
         } finally {await fs.rm(pause,{force:true});}
-        await notice(agent.controlDir,pending.id);
+        if(result?.status==='completed'&&pending.target==='main')return;
       }
       if(Date.now()>=nextCheck) {
         nextCheck=Date.now()+6*60*60*1000;
         try {
           const results=await discover(home);await atomic(path.join(directory,'available.json'),results);
-          const available=results.filter(r=>r.newer&&r.policy.automatic);
-          const key=digest(JSON.stringify(available)),saved=await read(path.join(directory,'discovery.json')).catch(missing);
-          if(available.length&&saved?.key!==key){await notice(agent.controlDir,key);await atomic(path.join(directory,'discovery.json'),{key});}
         } catch {
           // Discovery is optional; its failure must not terminate the host.
           // Do not expose registry response bodies or credentials in logs.

package/src/version.ts

@@ -2,3 +2,23 @@ import { readFileSync } from 'node:fs'
 
 // Capture the loaded package version once; an upgrade must not relabel old processes.
 export const packageVersion: string = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+
+// Optional image build identity (tag + commit), baked by Docker builds that pass
+// BUILD_TAG/BUILD_SHA. Absent for source checkouts and CI builds without args.
+export const buildInfo: { tag?: string; sha?: string } = (() => {
+  try {
+    const info = JSON.parse(readFileSync(new URL('../build.json', import.meta.url), 'utf8'))
+    const tag = typeof info.tag === 'string' && info.tag ? info.tag : undefined
+    const sha = typeof info.sha === 'string' && info.sha ? info.sha : undefined
+    return { ...(tag ? { tag } : {}), ...(sha ? { sha } : {}) }
+  } catch { return {} }
+})()
+
+export const formatRelayLabel = (version: string, tag?: string, sha?: string): string => {
+  const short = sha && sha.length > 12 ? sha.slice(0, 12) : sha
+  if (tag) return `${tag} (v${version}${short ? ` · ${short}` : ''})`
+  return short ? `v${version} (${short})` : `v${version}`
+}
+
+export const relayVersionLabel = (): string =>
+  formatRelayLabel(packageVersion, buildInfo.tag, buildInfo.sha)