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

package/test/updates.test.mjs

@@ -7,12 +7,21 @@ import { gzipSync } from 'node:zlib';
 import { spawn, execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { extract, digest, version, newer, compatible } from '../src/updates/artifact.mjs';
-import { prepare, submit, command, read, jobPath, eligibility, jobs } from '../src/updates/control.mjs';
+import { prepare, submit, command, read, jobPath, eligibility, jobs, cleanupStaleBackups, reviewedPluginDeploymentMigration } from '../src/updates/control.mjs';
 import { perform, environment, packageManager } from '../src/updates/runtime.mjs';
 import { atomic, snapshot, compose, prepareCommand } from '../src/plugins/manager.mjs';
 import { bindUpdates } from '../src/updates/binding.mjs';
 import { status as runtimeStatus } from '../src/updates/status.mjs';
+import { providerEnvironment } from '../src/updates/supervisor.mjs';
 const exec=promisify(execFile);
+
+test('supervisor forwards only provider keys declared by the agent installation',()=>{
+ const host={agents:[{codexProviders:[{envKey:'OPENROUTER_API_KEY'}]}]};
+ assert.deepEqual(providerEnvironment(host,{OPENROUTER_API_KEY:'provider-secret',TELEGRAM_BOT_TOKEN:'relay-secret'}),{OPENROUTER_API_KEY:'provider-secret'});
+ assert.throws(()=>providerEnvironment({agents:[{codexProviders:[{envKey:'bad-key'}]}]},{}),/environment key/);
+ for(const envKey of ['PATH','HOME','CODEX_HOME','NODE_OPTIONS','EZ_CONTROL_DIR','TELEGRAM_BOT_TOKEN'])
+  assert.throws(()=>providerEnvironment({agents:[{codexProviders:[{envKey}]}]},{}),/Reserved Codex provider environment key/);
+});
 const contract=kind=>({protocol:1,kind,stateSchema:1,mainProtocol:1});
 function tar(entries) {
  const chunks=[];
@@ -83,7 +92,7 @@ test('status distinguishes installed, running, legacy and stale main versions wi
  }
  await fs.writeFile(relay,'broken');s=await command(f.home,['status']);assert.equal(s.main.state,'unknown');
  await fs.rm(relay);s=await command(f.home,['status']);assert.equal(s.main.state,'offline');
- const result=await exec(process.execPath,[new URL('../bin/ezenciel-agents-tools.mjs',import.meta.url).pathname,'--home',f.home,'status']);
+ const result=await exec(process.execPath,[new URL('../bin/ezenciel-agents-tools.mjs',import.meta.url).pathname,'--home',f.home,'status'],{cwd:f.agent.workspace});
  assert.equal(JSON.parse(result.stdout).main.installedVersion,'0.1.0');
 });
 test('relay healthcheck emits bounded predicate evidence without state contents',async t=>{
@@ -98,20 +107,39 @@ test('relay healthcheck emits bounded predicate evidence without state contents'
 });
 test('plugin status verifies images and reports stopped, mismatched and unreachable runtimes honestly',async t=>{
  const f=await fixture(t,'plugin'),id='a'.repeat(64),image='sha256:'+'b'.repeat(64);
- for(const mode of ['running','ndjson','stopped','missing','mismatched','offline']) {
+ for(const mode of ['running','ndjson','warned','stopped','missing','mismatched','offline']) {
   const calls=[];
   const run=async(c,args)=>{
    calls.push([c,...args]);assert.equal(c,'docker');
    if(mode==='offline')throw Error('synthetic secret must not escape');
-   if(args.includes('ps')) {const rows=mode==='missing'?[]:[{Service:'sample',State:mode==='stopped'?'exited':'running',Health:'healthy',ID:id}];return mode==='ndjson'?rows.map(r=>JSON.stringify(r)).join('\n'):JSON.stringify(rows);}
+   if(args.includes('ps')) {const rows=mode==='missing'?[]:[{Service:'sample',State:mode==='stopped'?'exited':'running',Health:'healthy',ID:id}];const lines=mode==='ndjson'?rows.map(r=>JSON.stringify(r)).join('\n'):JSON.stringify(rows);return mode==='warned'?'time="now" level=warning msg="the attribute version is obsolete"\n'+rows.map(r=>JSON.stringify(r)).join('\n'):lines;}
    assert(args.includes('inspect'));return mode==='mismatched'&&args[0]==='image'?'sha256:'+'c'.repeat(64):image;
   };
   const s=await runtimeStatus(f.home,run),p=s.plugins[0];
-  assert.equal(p.installedVersion,'0.1.0');assert.equal(p.runningVersion,['running','ndjson'].includes(mode)?'0.1.0':null);
+  assert.equal(p.installedVersion,'0.1.0');assert.equal(p.runningVersion,['running','ndjson','warned'].includes(mode)?'0.1.0':null);
   assert.equal(p.state,mode==='offline'?'unknown':['stopped','missing'].includes(mode)?'stopped':'running');
   assert(!JSON.stringify(s).includes('synthetic secret'));assert(calls.every(c=>!c.includes('exec')&&!c.includes('start')&&!c.includes('up')));
  }
 });
+test('isolated plugin status uses bundled Compose v1 and inspect readback',async t=>{
+ const f=await fixture(t,'plugin'),id='a'.repeat(64),image='sha256:'+'b'.repeat(64),previous=process.env.EZ_DOCKER_COMPOSE;
+ process.env.EZ_DOCKER_COMPOSE='standalone';
+ try {
+  const calls=[],run=async(c,args)=>{
+   calls.push([c,...args]);assert.equal(c,'docker');
+   if(args.at(-1)==='-q')return id;
+   if(args[0]==='inspect'&&args.length===2)return JSON.stringify([{Config:{Labels:{'com.docker.compose.service':'sample'}},State:{Status:'running',Health:{Status:'healthy'}}}]);
+   if(args[0]==='inspect')return image;
+   if(args[0]==='image')return image;
+   throw Error('unexpected status command');
+  };
+  const p=(await runtimeStatus(f.home,run)).plugins[0];
+  assert.equal(p.state,'running');assert.equal(p.runningVersion,'0.1.0');
+  assert.deepEqual(calls[0].slice(-3),['ps','--all','-q']);
+ } finally {
+  if(previous===undefined)delete process.env.EZ_DOCKER_COMPOSE;else process.env.EZ_DOCKER_COMPOSE=previous;
+ }
+});
 test('SemVer ordering and compatibility reject ranges, malformed values and downgrades',()=>{
  for(const s of ['latest','../1','1.0','01.0.0','1.0.0-01'])assert.throws(()=>version(s));
  assert(newer('0.1.0-beta.10','0.1.0-beta.2'));assert(newer('0.1.0','0.1.0-beta.10'));assert(!newer('0.1.0-beta.2','0.1.0'));assert(!newer('1.0.0','1.0.0'));
@@ -145,6 +173,63 @@ test('identity, state migration, deployment changes and stale candidates fail be
  await mutate({ezRelease:contract('main'),version:'0.0.1'});await assert.rejects(prepare(f.home,'main',{file:await f.pack()}),/newer/);
  await mutate({version:'0.1.1'});await fs.writeFile(path.join(f.source,'compose.yaml'),'privileged: true');await assert.rejects(prepare(f.home,'main',{file:await f.pack()}),/deployment/);
 });
+test('legacy runtime deployment migration compares effective Compose and preserves explicit bindings',async t=>{
+ const f=await fixture(t),oldCompose=`services:
+  relay:
+    environment:
+      EZ_AGENT_PURPOSE_FILE: /run/agent-purpose.md
+      EZ_EXECUTOR_TRANSPORT: \${EZ_EXECUTOR_TRANSPORT:-host}
+configs:
+  agent_purpose:
+    file: \${EZ_AGENT_PURPOSE_FILE:-./templates/agent/SOUL.md}
+`,nextCompose=oldCompose.replace('      EZ_EXECUTOR_TRANSPORT:', '      EZ_ISOLATION: ${EZ_ISOLATION:-}\n      EZ_EXECUTOR_TRANSPORT:').replace('./templates/agent/SOUL.md','./templates/agent-purpose.md');
+ await fs.writeFile(path.join(f.old,'compose.yaml'),oldCompose);await fs.writeFile(path.join(f.source,'compose.yaml'),nextCompose);
+ await fs.writeFile(path.join(f.config.deploymentDir,'docker.env'),`COMPOSE_FILE='${f.old}/compose.yaml'
+COMPOSE_PROJECT_NAME='ez-agent-fixture'
+EZ_AGENT_PURPOSE_FILE='${path.join(f.config.deploymentDir,'purpose.md')}'
+EZ_EXECUTOR_TRANSPORT='host'
+`);
+ const job=await prepare(f.home,'main',{file:await f.pack()});assert.equal(job.deploymentMigration.id,'legacy-runtime-v1');
+ await fs.writeFile(path.join(f.config.deploymentDir,'docker.env'),`COMPOSE_FILE='${f.old}/compose.yaml'
+COMPOSE_PROJECT_NAME='ez-agent-fixture'
+EZ_EXECUTOR_TRANSPORT='host'
+`);await assert.rejects(eligibility(f.home,'main',f.source,false),/deployment/);
+});
+test('legacy runtime migration admits homes without docker.env when purpose fallback is already bound',async t=>{
+  const f=await fixture(t),oldCompose=`services:
+  relay:
+    environment:
+      EZ_AGENT_PURPOSE_FILE: /run/agent-purpose.md
+      EZ_EXECUTOR_TRANSPORT: \${EZ_EXECUTOR_TRANSPORT:-host}
+configs:
+  agent_purpose:
+    file: \${EZ_AGENT_PURPOSE_FILE:-./templates/agent-purpose.md}
+`,nextCompose=oldCompose.replace('      EZ_EXECUTOR_TRANSPORT:', '      EZ_ISOLATION: \${EZ_ISOLATION:-}\n      EZ_EXECUTOR_TRANSPORT:');
+ await fs.writeFile(path.join(f.old,'compose.yaml'),oldCompose);await fs.writeFile(path.join(f.source,'compose.yaml'),nextCompose);
+ await fs.rm(path.join(f.config.deploymentDir,'docker.env'));
+ const job=await prepare(f.home,'main',{file:await f.pack()});assert.equal(job.deploymentMigration.id,'legacy-runtime-v1');
+});
+test('compatibility bridge hands off to the published beta.34 release',async t=>{
+ const f=await fixture(t),prior=await read(path.join(f.old,'package.json')),candidate=await read(path.join(f.source,'package.json'));
+ await atomic(path.join(f.old,'package.json'),{...prior,version:'0.1.0-beta.34.compat.1'});
+ await atomic(path.join(f.source,'package.json'),{...candidate,version:'0.1.0-beta.34'});
+ await assert.doesNotReject(eligibility(f.home,'main',f.source,false));
+});
+test('compatibility bridge hands off any matching canonical beta release',async t=>{
+ const f=await fixture(t),prior=await read(path.join(f.old,'package.json')),candidate=await read(path.join(f.source,'package.json'));
+ await atomic(path.join(f.old,'package.json'),{...prior,version:'0.1.0-beta.35.compat.1'});
+ await atomic(path.join(f.source,'package.json'),{...candidate,version:'0.1.0-beta.35'});
+ await assert.doesNotReject(eligibility(f.home,'main',f.source,false));
+ await atomic(path.join(f.source,'package.json'),{...candidate,version:'0.1.0-beta.34'});
+ await assert.rejects(eligibility(f.home,'main',f.source,false),/newer/);
+});
+test('reviewed Library beta14 command migration is exact and fail-closed',()=>{
+ const manifest=(version,document)=>({schemaVersion:1,id:'library',version,description:'library',commands:{library:{executable:'bin/ez-library.mjs',args:[]},'library-query':{executable:'bin/ez-library.mjs',args:[],channelQuery:true},...(document?{'library-document':{executable:'bin/ez-library.mjs',args:[],channelQuery:true}}:{})},skills:['skills/library/SKILL.md']});
+ const deployment=(query,document)=>({schemaVersion:3,services:{library:{buildTarget:'runtime',volumes:{data:'/state'},healthcheck:['node','/app/bin/ez-library.mjs','--version'],memoryMiB:4096,cpus:2}},commands:{'library-query':{service:'library',argv:['node','/app/bin/ez-library.mjs',query]},...(document?{'library-document':{service:'library',argv:['node','/app/bin/ez-library.mjs','document']}}:{})},sharedServices:{}});
+ const old={manifest:manifest('0.1.0-beta.13.qa.4',true),deployment:deployment('query-context',true)},next={manifest:manifest('0.1.0-beta.14',false),deployment:deployment('search',false)};
+ assert.equal(reviewedPluginDeploymentMigration('library',old,next).id,'library-query-contract-v1');
+ const unsafe=structuredClone(next);unsafe.deployment.services.library.cpus=4;assert.equal(reviewedPluginDeploymentMigration('library',old,unsafe),undefined);
+});
 test('main transaction stages before stopping, pins rollback image, preserves state and rebinds root',async t=>{
  const f=await fixture(t),job=await queued(f),r=runtime(f);
  await fs.writeFile(path.join(f.agent.workspace,'memory.md'),'retain me');
@@ -158,6 +243,13 @@ test('main transaction stages before stopping, pins rollback image, preserves st
  const status=await command(f.home,['status']);assert(!JSON.stringify(status).includes('private-test-token'));assert(!('rollback'in status.jobs[0]));
  assert.equal((await fs.stat(path.join(jobPath(f.home,job.id),'job.json'))).mode&0o777,0o600);
 });
+test('update cleanup keeps the newest backup per target and ignores unfinished jobs',async t=>{
+ const f=await fixture(t),older='11111111-1111-1111-1111-111111111111',latest='22222222-2222-2222-2222-222222222222',queued='33333333-3333-3333-3333-333333333333',rolledBack='44444444-4444-4444-4444-444444444444';
+ const seed=async(id,target,status,endedAt)=>{const dir=jobPath(f.home,id);await fs.mkdir(path.join(dir,'backup'),{recursive:true});await fs.writeFile(path.join(dir,'backup','marker'),'private');await atomic(path.join(dir,'job.json'),{id,target,status,createdAt:endedAt,endedAt});};
+ await seed(older,'main','completed','2026-01-01T00:00:00.000Z');await seed(latest,'main','completed','2026-01-02T00:00:00.000Z');await seed(queued,'sample','queued','2026-01-03T00:00:00.000Z');await seed(rolledBack,'main','rolled-back','2026-01-03T00:00:00.000Z');
+ const result=await cleanupStaleBackups(f.home);assert.deepEqual(result.kept,[latest]);assert.deepEqual(result.removed.sort(),[older,rolledBack].sort());
+ await assert.rejects(fs.access(path.join(jobPath(f.home,older),'backup')));await fs.access(path.join(jobPath(f.home,latest),'backup'));await fs.access(path.join(jobPath(f.home,queued),'backup'));await assert.rejects(fs.access(path.join(jobPath(f.home,rolledBack),'backup')));
+});
 test('failed preparation never stops runtime; failed activation rolls back code without rewinding state',async t=>{
  for(const stage of ['build','health']) {
   const f=await fixture(t),job=await queued(f),r=runtime(f,{fail:(_c,a)=>stage==='build'?a[0]==='build':a.includes('up')});
@@ -294,9 +386,10 @@ for(const provider of ['pnpm','corepack']) test(`supervisor with only ${provider
  await fs.writeFile(wrapper,`import {supervise} from ${JSON.stringify(module)};const a=new AbortController();process.on('SIGTERM',()=>a.abort());await supervise(${JSON.stringify(f.config.deploymentDir)},a.signal,{discover:async()=>{${provider==='pnpm' ? "throw Error('Synthetic discovery failure')" : 'return []'}}});`);
  const start=()=>{const p=spawn(process.execPath,[wrapper],{env:{...process.env,PATH:fake},stdio:['ignore','pipe','pipe']});let output='';p.stdout.on('data',b=>output+=b);p.stderr.on('data',b=>output+=b);return {p,output:()=>output};};
  const wait=async fn=>{for(let i=0;i<150;i++){const result=await fn();if(result)return result;await new Promise(r=>setTimeout(r,100));}throw Error('Timed out');};
- const first=start();t.after(()=>{first.p.kill('SIGTERM');});
+ const first=start(),firstClosed=new Promise(resolve=>first.p.once('close',resolve));t.after(()=>{first.p.kill('SIGTERM');});
  const heartbeat=()=>read(path.join(f.agent.controlDir,'host-executor/heartbeat.json')).catch(()=>null);
  const oldBeat=await wait(heartbeat);
+ if(provider==='pnpm')await wait(()=>first.output().includes('Update discovery failed; host remains running.'));
  const running=path.join(f.agent.controlDir,'host-executor/r_request.running.json');await fs.writeFile(running,'{}');
  const job=await prepare(f.home,'main',{file:await f.pack()});
  const requester=await exec(process.execPath,['--input-type=module','-e',`import {submit} from ${JSON.stringify(new URL('../src/updates/control.mjs',import.meta.url).href)};console.log(JSON.stringify(await submit(${JSON.stringify(f.home)},${JSON.stringify(job.id)},false)));`]);
@@ -304,14 +397,10 @@ for(const provider of ['pnpm','corepack']) test(`supervisor with only ${provider
  await new Promise(r=>setTimeout(r,1800));assert.equal((await read(path.join(jobPath(f.home,job.id),'job.json'))).status,'queued');
  await fs.rm(running);
  await wait(async()=>{const j=await read(path.join(jobPath(f.home,job.id),'job.json'));if(j.status==='failed'||j.status==='rolled-back')throw Error(JSON.stringify(j)+first.output());return j.status==='completed';});
- const newBeat=await heartbeat();assert.notEqual(newBeat.pid,oldBeat.pid);assert(first.p.exitCode===null);
+ const newBeat=await heartbeat();assert.notEqual(newBeat.pid,oldBeat.pid);assert.equal(await firstClosed,0,first.output());
  if(provider==='pnpm'){assert.match(first.output(),/Update discovery failed; host remains running/);assert.doesNotMatch(first.output(),/Synthetic discovery failure/);}
- // Completion is persisted before the supervisor publishes its attention receipt.
- await wait(async()=>{
-  try{return (await read(path.join(f.agent.controlDir,'update-attention.json'))).id===digest(job.id);}
-  catch(error){if(error.code==='ENOENT')return false;throw error;}
- });
- const closed=new Promise(r=>first.p.once('close',r));first.p.kill('SIGTERM');await closed;
+ // Adversarial: a completed update must not publish an agent wakeup notice.
+ await assert.rejects(fs.readFile(path.join(f.agent.controlDir,'update-attention.json')),error=>error.code==='ENOENT');
  const active=(await read(path.join(f.home,'config.json'))).packageRoot;assert(active.endsWith('/runtime'));
  assert.equal((await read(path.join(jobPath(f.home,job.id),'job.json'))).packageManager.command,provider);
  const second=start();t.after(()=>second.p.kill('SIGTERM'));

package/test/workspace-confine.test.ts

@@ -0,0 +1,47 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
+import { spawn } from 'node:child_process'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { macosWorkspaceProfile, workspaceSiblingDenies } from '../src/workspace-confine.js'
+
+test('sibling confinement skips $HOME and filesystem root', () => {
+  assert.deepEqual(workspaceSiblingDenies('/Users/ada/agent', '/Users/ada'), [])
+  assert.deepEqual(workspaceSiblingDenies('/', '/Users/ada'), [])
+})
+
+test('sibling confinement denies the tenant farm, not the bound workspace', () => {
+  assert.deepEqual(workspaceSiblingDenies('/data/tenants/juan', '/Users/ada'), [
+    { deny: '/data/tenants', allow: '/data/tenants/juan' },
+  ])
+})
+
+test('macos profile blocks sibling reads and writes', async (t) => {
+  if (process.platform !== 'darwin') { t.skip(); return }
+  const root = await mkdtemp(path.join(tmpdir(), 'ez-confine-'))
+  t.after(() => rm(root, { recursive: true, force: true }))
+  const mine = path.join(root, 'juan')
+  const other = path.join(root, 'other')
+  const shared = path.join(root, 'shared')
+  const additional = path.join(root, 'additional')
+  await mkdir(mine); await mkdir(other); await mkdir(shared); await mkdir(additional)
+  await writeFile(path.join(mine, 'own.txt'), 'own')
+  await writeFile(path.join(other, 'secret.txt'), 'secret')
+  await writeFile(path.join(shared, 'shared.txt'), 'shared')
+  await writeFile(path.join(additional, 'additional.txt'), 'additional')
+  const profile = path.join(root, 'workspace.sb')
+  await writeFile(profile, macosWorkspaceProfile(workspaceSiblingDenies(mine, '/Users/ada'), [shared, additional]))
+  const run = (file: string) => new Promise<{ code: number | null; stderr: string }>(resolve => {
+    const child = spawn('sandbox-exec', ['-f', profile, '/bin/cat', file], { stdio: ['ignore', 'pipe', 'pipe'] })
+    let stderr = ''
+    child.stderr.on('data', chunk => { stderr += chunk })
+    child.on('close', code => resolve({ code, stderr }))
+  })
+  assert.equal((await run(path.join(mine, 'own.txt'))).code, 0)
+  assert.equal((await run(path.join(shared, 'shared.txt'))).code, 0)
+  assert.equal((await run(path.join(additional, 'additional.txt'))).code, 0)
+  const blocked = await run(path.join(other, 'secret.txt'))
+  assert.notEqual(blocked.code, 0)
+  assert.match(blocked.stderr, /not permitted|Operation not permitted/i)
+})

package/test/workspace.test.ts

@@ -38,42 +38,58 @@ test('fresh mind is private; repeat initialization preserves customization and o
   const root = await mkdtemp(path.join(tmpdir(), 'ez-mind-'))
   const workspace = path.join(root, 'agent')
   try {
-    assert.equal((await initializeWorkspace(workspace)).length, 3)
-    assert.equal((await stat(path.join(workspace, 'SOUL.md'))).mode & 0o777, 0o600)
+    const purpose = path.join(root, 'purpose.md')
+    await writeFile(purpose, 'Research partner\n')
+    assert.deepEqual(await initializeWorkspace(workspace, purpose), ['AGENTS.md'])
+    assert.equal((await stat(path.join(workspace, 'AGENTS.md'))).mode & 0o777, 0o600)
+    assert.ok(!(await readdir(workspace)).includes('SOUL.md'))
+    assert.ok(!(await readdir(workspace)).includes('USER.md'))
     assert.ok(!(await readdir(workspace)).includes('MEMORY.md'))
-    await writeFile(path.join(workspace, 'SOUL.md'), 'A customized research partner')
+    assert.ok(!(await readdir(workspace)).includes('inbox'))
+    assert.ok(!(await readdir(workspace)).includes('work'))
+    await writeFile(path.join(workspace, 'AGENTS.md'), 'A customized research partner')
     await writeFile(path.join(workspace, 'MEMORY.md'), 'Existing knowledge')
     await writeFile(path.join(workspace, 'AGENT.md'), 'Legacy custom guidance')
     assert.deepEqual(await initializeWorkspace(workspace), [])
-    assert.equal(await readFile(path.join(workspace, 'SOUL.md'), 'utf8'), 'A customized research partner')
+    assert.match(await readFile(path.join(workspace, 'AGENTS.md'), 'utf8'), /A customized research partner/)
     assert.equal(await readFile(path.join(workspace, 'MEMORY.md'), 'utf8'), 'Existing knowledge')
     assert.equal(await readFile(path.join(workspace, 'AGENT.md'), 'utf8'), 'Legacy custom guidance')
     assert.ok(!(await readdir(workspace)).some(name => name.endsWith('.tmp')))
-    assert.match(await readFile(path.join(workspace, 'AGENTS.md'), 'utf8'), /ez shared guidance: begin/)
+    assert.doesNotMatch(await readFile(path.join(workspace, 'AGENTS.md'), 'utf8'), /ez shared guidance/)
   } finally { await rm(root, { recursive: true, force: true }) }
 })
 
+test('fresh workspace refuses to invent a generic purpose', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'ez-purpose-required-'))
+  try {
+    await assert.rejects(initializeWorkspace(path.join(root, 'mind'), undefined), /purpose file is required/)
+  } finally { await rm(root, {recursive:true, force:true}) }
+})
+
 test('seed refuses a symlink without overwriting its target', async () => {
   const root = await mkdtemp(path.join(tmpdir(), 'ez-mind-'))
   try {
     const target = path.join(root, 'outside.md')
     await writeFile(target, 'untouched')
-    await symlink(target, path.join(root, 'SOUL.md'))
+    await symlink(target, path.join(root, 'AGENTS.md'))
     await assert.rejects(initializeWorkspace(root), /regular file/)
     assert.equal(await readFile(target, 'utf8'), 'untouched')
   } finally { await rm(root, { recursive: true, force: true }) }
 })
 
-test('new agents seed their own purpose once and preserve subsequent mind edits', async () => {
+test('new agents seed a purpose-scoped AGENTS.md once and preserve subsequent edits', async () => {
   const root = await mkdtemp(path.join(tmpdir(), 'ez-purpose-'))
   try {
     const purpose = path.join(root, 'purpose.md')
     const workspace = path.join(root, 'mind')
-    await writeFile(purpose, 'Family shopping assistant\n')
+    await writeFile(purpose, 'You are the shopping assistant for this family.\n\n### Responsibilities\n\nOrganize confirmed household shopping requests.\n')
     await initializeWorkspace(workspace, purpose)
-    assert.equal(await readFile(path.join(workspace, 'SOUL.md'), 'utf8'), 'Family shopping assistant\n')
-    await writeFile(path.join(workspace, 'SOUL.md'), 'My evolving purpose\n')
+    const agents = await readFile(path.join(workspace, 'AGENTS.md'), 'utf8')
+    assert.doesNotMatch(agents, /inbox\/|work\/|ezenciel-agents-message/)
+    assert.match(agents, /## Purpose\n\nYou are the shopping assistant for this family\./)
+    assert.match(agents, /### Responsibilities\n\nOrganize confirmed household shopping requests\./)
+    await writeFile(path.join(workspace, 'AGENTS.md'), 'My evolving purpose\n')
     await initializeWorkspace(workspace, purpose)
-    assert.equal(await readFile(path.join(workspace, 'SOUL.md'), 'utf8'), 'My evolving purpose\n')
+    assert.match(await readFile(path.join(workspace, 'AGENTS.md'), 'utf8'), /My evolving purpose/)
   } finally { await rm(root, {recursive:true, force:true}) }
 })

package/bin/ezenciel-agents-watch.mjs

@@ -1,8 +0,0 @@
-#!/usr/bin/env node
-import { spawn } from 'node:child_process'
-import { createRequire } from 'node:module'
-import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-const here=dirname(fileURLToPath(import.meta.url)),require=createRequire(import.meta.url),tsx=require.resolve('tsx'),entry=join(here,'..','src','workforce-watch-cli.ts')
-const child=spawn(process.execPath,['--import',tsx,entry],{stdio:'inherit'})
-child.on('exit',(code,signal)=>{if(signal)process.kill(process.pid,signal);process.exit(code??1)})

package/compose.workforce-watch.yaml

@@ -1,33 +0,0 @@
-services:
-  workforce-watch:
-    image: ${EZ_WORKFORCE_WATCH_IMAGE:-ezenciel-agents:local}
-    build:
-      context: .
-      target: workforce-watch
-    init: true
-    restart: unless-stopped
-    read_only: true
-    cap_drop: [ALL]
-    security_opt: [no-new-privileges:true]
-    environment:
-      EZ_WATCH_PORT: 8080
-      EZ_WATCH_ENROLL_TOKEN: ${EZ_WATCH_ENROLL_TOKEN:?Set a private enrollment token}
-      EZ_WATCH_TELEGRAM_CHAT_ID: ${EZ_WATCH_TELEGRAM_CHAT_ID:-}
-      TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN:-}
-    secrets: [workforce_watch_pagerduty]
-    volumes:
-      - workforce-watch-state:/state
-    tmpfs: [/tmp]
-    ports:
-      - ${EZ_WATCH_BIND_ADDRESS:-127.0.0.1}:${EZ_WATCH_PORT:-9919}:8080
-    healthcheck:
-      test: [CMD, node, -e, "fetch('http://127.0.0.1:8080/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
-      interval: 30s
-      timeout: 5s
-      retries: 3
-      start_period: 10s
-volumes:
-  workforce-watch-state:
-secrets:
-  workforce_watch_pagerduty:
-    file: ${EZ_WATCH_PAGERDUTY_SECRET_FILE:?Set EZ_WATCH_PAGERDUTY_SECRET_FILE to the protected workforce PagerDuty routing-key file}

package/docker/recovery.ts

@@ -1,11 +0,0 @@
-import { RunStore } from '../src/runs.js'
-
-// Called only after the deployment's kernel writer lock is held. No worker
-// from a previous container can still own this deployment; PIDs may be reused.
-export const recoverInterruptedRuns = async (controlDir: string, channelBackend = false) => {
-  const store = new RunStore(controlDir)
-  for (const run of await store.list()) {
-    if (run.status === 'running')
-      await store.patch(run.id, { status: channelBackend && !run.pid ? 'queued' : 'failed', endedAt: new Date().toISOString() })
-  }
-}

package/docs/pagerduty.md

@@ -1,42 +0,0 @@
-# PagerDuty critical-outage paging
-
-PagerDuty alerting is an optional core capability. It observes Stocks from the
-Ez runtime and sends Events API v2 trigger and resolve events; Stocks never
-receives the PagerDuty routing key.
-
-Create an Events API v2 integration in the PagerDuty service that should page
-you. Put only its routing key in the deployment's private `relay.env` file:
-
-```dotenv
-PAGERDUTY_ROUTING_KEY=<Events API v2 routing key>
-```
-
-Then add the tunnel-visible endpoint and monitor settings to the deployment's
-non-secret `docker.env` file:
-
-```dotenv
-EZ_PAGERDUTY_STOCKS_HEALTH_URL=http://10.97.0.1:3006/health/critical
-EZ_PAGERDUTY_POLL_SECONDS=30
-EZ_PAGERDUTY_FAILURE_THRESHOLD=3
-```
-
-The core checks the endpoint every 30 seconds by default. Three consecutive
-unhealthy checks trigger one incident with the stable deduplication key
-`ez:stocks:critical-health`; recovery resolves that same incident. A failed
-PagerDuty submission remains eligible for a later trigger. On startup, the first
-healthy check resolves any incident left by the previous process, including an
-uncertain trigger delivery. Failed resolves retry without treating healthy
-Stocks as an outage. No key or health
-response is written to agent workspaces, executor environments, or logs.
-
-`/health/critical` is intentionally narrower than Stocks `/health`: it pages
-only when the Stocks source worker is unavailable. Provider freshness and other
-research-quality degradation remain visible in normal Stocks health/status but
-do not page. The endpoint returns only a status and component summary and must
-be reachable from the core runtime over the private tunnel. Run core outside the
-Stocks VM if you want a VM outage to be page-worthy.
-
-After deployment, use PagerDuty's test/escalation tooling or temporarily point
-the monitor at an intentionally unreachable private test target, then restore
-the real target and confirm the PagerDuty incident resolves. This is an explicit
-operational test and may notify your escalation policy.

package/docs/workforce-watch.md

@@ -1,101 +0,0 @@
-# Workforce Watch
-
-Workforce Watch is a separate, small Docker service for missed agent check-ins
-and explicit terminal failures. It is not an agent, scheduler, log store or
-remote-execution channel. It retains only the five latest compact activity
-records supplied by each enrolled worker.
-
-Run it in a failure domain separate from the workers it watches. In particular,
-it must not rely on the Stocks VM to report a Stocks VM outage, and a separate
-host is required to detect a Mac-wide outage.
-
-## Start the monitor
-
-Set private monitor-only values, never agent-workspace or source-control values:
-
-```text
-EZ_WATCH_ENROLL_TOKEN=<private fleet enrollment secret>
-EZ_WATCH_PAGERDUTY_SECRET_FILE=/absolute/path/to/a-0600-workforce-pagerduty-key
-TELEGRAM_BOT_TOKEN=<alert bot token>
-EZ_WATCH_TELEGRAM_CHAT_ID=<owner chat id>
-```
-
-PagerDuty is the fleet incident owner. Workforce Watch sends a `trigger` for
-each missed check-in or terminal failure, then a `resolve` with the stable
-deduplication key `ez:workforce:<worker-id>` after sustained recovery. Use one
-approved Events API v2 routing key for the fleet; it may be the existing
-PagerDuty integration when that is the desired escalation policy. Never put it
-in a worker's environment. The secret file contains only that key, is mode
-`0600`, and is mounted as `/run/secrets/workforce_watch_pagerduty`; it is never
-a Compose or container environment value. Telegram is optional, supplementary
-owner visibility. PagerDuty is required: a Watch deployment without its
-routing-key secret fails closed rather than silently running without paging.
-
-The owner may explicitly authorize the CTO bot token temporarily. A dedicated
-alert bot remains preferable because it preserves an independent delivery identity.
-
-```sh
-docker compose -f compose.workforce-watch.yaml up -d --build
-curl http://127.0.0.1:9919/healthz
-```
-
-The default bind is loopback. Put private TLS networking or a private reverse
-proxy in front of it before remote workers use it; do not expose enrollment or
-check-in traffic publicly.
-
-## Enroll and check in
-
-The worker selects its monitor through its configured URL. It submits the fleet
-enrollment secret once; the response contains the worker-specific secret. Store
-that response only in the worker's private service environment and discard it
-from shell history and logs.
-
-```sh
-curl --fail-with-body -X POST "$EZ_WATCH_URL/v1/enroll" \
-  -H "Authorization: Bearer $EZ_WATCH_ENROLL_TOKEN" \
-  -H 'content-type: application/json' \
-  --data '{"workerId":"stocks-production","checkInSeconds":300,"graceSeconds":180,"severity":"critical"}'
-```
-
-The supervisor, not the LLM, posts check-ins using the returned worker secret:
-
-```sh
-curl --fail-with-body -X POST "$EZ_WATCH_URL/v1/workers/stocks-production/check-in" \
-  -H "Authorization: Bearer $EZ_WATCH_WORKER_TOKEN" \
-  -H 'content-type: application/json' \
-  --data '{"status":"ok","activity":"strategy receipt delivered","runId":"daily-strategy-2026-09-11"}'
-```
-
-An unrecoverable condition sends `{"status":"failed","terminal":true,...}`.
-Optional `activity`, `error`, `runId`, and `logsHint` fields are size-limited and
-appear in an alert. They must be public-safe operational context, never stdout,
-prompts, holdings, credentials, or provider payloads.
-
-## Inspect
-
-The enrollment token reads redacted state; worker secrets never appear:
-
-```sh
-curl --fail-with-body "$EZ_WATCH_URL/v1/workers" \
-  -H "Authorization: Bearer $EZ_WATCH_ENROLL_TOKEN"
-```
-
-For host replacement or a suspected worker-secret exposure, rotate that worker's
-secret with the enrollment token. The old secret stops working immediately:
-
-```sh
-curl --fail-with-body -X POST "$EZ_WATCH_URL/v1/workers/stocks-production/rotate" \
-  -H "Authorization: Bearer $EZ_WATCH_ENROLL_TOKEN"
-```
-
-Store the returned worker secret in the replacement supervisor before stopping
-the prior one.
-
-The service triggers once for a missed deadline or terminal failure. It sends a
-recovery notice only after two clean check-ins by default to prevent flapping.
-
-If a worker fails again during a partially delivered recovery, channels that
-already accepted recovery receive a fresh trigger. Channels still open retain
-their delivery state, so they do not receive duplicate opening alerts. This
-applies to terminal failures, failed check-ins, and missed check-ins, including
-after a Watch restart.

package/src/pagerduty.ts

@@ -1,109 +0,0 @@
-export type PagerDutyStocksMonitorOptions = {
-  routingKey: string
-  healthUrl: string
-  pollMs: number
-  failureThreshold: number
-  fetcher?: typeof fetch
-  onError?: (error: Error) => void
-}
-
-const PAGERDUTY_EVENTS_URL = 'https://events.pagerduty.com/v2/enqueue'
-const STOCKS_DEDUP_KEY = 'ez:stocks:critical-health'
-
-/**
- * Monitors the deliberately narrow Stocks critical-health endpoint. It keeps
- * state in memory on purpose: PagerDuty's deduplication key is the durable
- * incident authority, while a restart should need a fresh sustained failure.
- */
-export class PagerDutyStocksMonitor {
-  private readonly fetcher: typeof fetch
-  private consecutiveFailures = 0
-  private incidentOpen = false
-  private recoveryPending = true
-  private checking = false
-  private timer?: ReturnType<typeof setInterval>
-
-  constructor(private readonly options: PagerDutyStocksMonitorOptions) {
-    this.fetcher = options.fetcher ?? fetch
-  }
-
-  start(): void {
-    if (this.timer) return
-    void this.check()
-    this.timer = setInterval(() => { void this.check() }, this.options.pollMs)
-    this.timer.unref()
-  }
-
-  stop(): void {
-    if (this.timer) clearInterval(this.timer)
-    this.timer = undefined
-  }
-
-  async check(): Promise<void> {
-    if (this.checking) return
-    this.checking = true
-    try {
-      const response = await this.fetcher(this.options.healthUrl, {
-        headers: { accept: 'application/json' },
-        redirect: 'error',
-        signal: AbortSignal.timeout(5_000),
-      })
-      if (!response.ok) throw new Error(`Stocks health returned HTTP ${response.status}`)
-      const health: unknown = await response.json()
-      if (!health || typeof health !== 'object' || (health as { status?: unknown }).status !== 'ok')
-        throw new Error('Stocks critical health is not ok')
-
-      this.consecutiveFailures = 0
-      if (this.recoveryPending) {
-        try {
-          await this.send('resolve')
-          this.incidentOpen = false
-          this.recoveryPending = false
-        } catch (error) { this.report(error) }
-      }
-    } catch (error) {
-      this.consecutiveFailures += 1
-      if (!this.incidentOpen && this.consecutiveFailures >= this.options.failureThreshold) {
-        try {
-          this.recoveryPending = true
-          await this.send('trigger')
-          this.incidentOpen = true
-        } catch (sendError) {
-          this.report(sendError)
-        }
-      }
-      this.report(error)
-    } finally {
-      this.checking = false
-    }
-  }
-
-  private async send(action: 'trigger' | 'resolve'): Promise<void> {
-    const response = await this.fetcher(PAGERDUTY_EVENTS_URL, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({
-        routing_key: this.options.routingKey,
-        event_action: action,
-        dedup_key: STOCKS_DEDUP_KEY,
-        payload: {
-          summary: action === 'trigger'
-            ? 'Stocks critical health is unavailable'
-            : 'Stocks critical health recovered',
-          source: 'ez-core',
-          severity: 'critical',
-          component: 'stocks',
-          custom_details: { failed_checks: this.consecutiveFailures },
-        },
-      }),
-      redirect: 'error',
-      signal: AbortSignal.timeout(5_000),
-    })
-    if (!response.ok) throw new Error(`PagerDuty Events API returned HTTP ${response.status}`)
-  }
-
-  private report(error: unknown): void {
-    const message = error instanceof Error ? error.message : 'unknown error'
-    this.options.onError?.(new Error(message))
-  }
-}