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

package/test/ai.test.ts

@@ -106,13 +106,17 @@ test('OpenCode keeps same-provider models together and separates providers encod
     const other = { ...first, id: 'other', name: 'Other', model: 'openrouter/other' }
     const choice = await store.captureChoice(first)
     await store.saveNativeSession(choice.sessionId, 'ses_original')
-    const menu = createAiMenu(store, 'opencode', async () => [first, second, other].map(p => ({ ...p, efforts: [] })), dir, undefined, async () => true)
+    const closed: string[] = []
+    const menu = createAiMenu(store, 'opencode', async () => [first, second, other].map(p => ({ ...p, efforts: [] })), dir, undefined, async () => true,
+      undefined, async (session) => { if (session) closed.push(session.sessionId) })
     await store.savePreset(second)
     assert.equal((await menu.select(second, choice.sessionId)).fresh, false)
+    assert.deepEqual(closed, [])
     assert.equal((await store.captureChoice(first)).sessionId, choice.sessionId)
     await store.savePreset(other)
     assert.equal(await store.selectPreset(other.id, choice.sessionId), false)
     assert.equal((await menu.select(other, choice.sessionId)).fresh, true)
+    assert.deepEqual(closed, [choice.sessionId]) // switching provider closes the old conversation once
     const next = await store.captureChoice(first)
     assert.notEqual(next.sessionId, choice.sessionId)
     assert.equal((await store.executionSession(next)).nativeSessionId, undefined)
@@ -519,7 +523,7 @@ test('opencode model and variant selections validate against the installed catal
   await validateSelection({ id: 'default', name: 'Default', cli: 'opencode', model: 'opencode/big-pickle' }, catalog, available)
   await assert.rejects(
     validateSelection({ id: 'bad', name: 'Bad', cli: 'opencode', model: 'opencode/ling-free', effort: 'max' }, catalog, available),
-    /installed client catalog/)
+    /Effort max is not supported.*low, medium/)
   await assert.rejects(
     validateSelection({ id: 'missing', name: 'Missing', cli: 'opencode', model: 'opencode/unknown' }, catalog, available),
     /installed client catalog/)
@@ -672,3 +676,45 @@ test('Claude catalog projects only aliases and efforts from the installed native
   await validateSelection({ id: 'c', name: 'c', cli: 'claude', model: 'opus', effort: 'xhigh' }, models, async () => true)
   await assert.rejects(validateSelection({ id: 'c', name: 'c', cli: 'claude', model: 'opus-guess' }, models, async () => true), /not in the installed client catalog/)
 })
+
+test('Telegram Sonnet choice survives restart and reaches the native launch without Opus substitution', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'ez-sonnet-selection-'))
+  const priorPath = process.env.PATH
+  try {
+    const store = new ControlStore(dir, 1000)
+    await store.captureChoice({id:'opus',name:'Opus',cli:'claude',model:'opus',effort:'xhigh'})
+    const models = [{cli:'claude',model:'opus',name:'Opus',efforts:['xhigh']},
+      {cli:'claude',model:'sonnet',name:'Sonnet',efforts:['low','medium','high']}]
+    const menu = createAiMenu(store, 'claude', async()=>models, dir, undefined, async()=>true)
+    const replies: Array<{text:string; buttons:Array<{text:string;callback_data:string}>}> = []
+    const context = (data?:string) => ({callbackQuery:data ? {data} : undefined,answerCallbackQuery:async()=>({}),
+      reply:async(text:string, options?:{reply_markup?:{inline_keyboard?:Array<Array<{text:string;callback_data:string}>>}})=>{
+        replies.push({text,buttons:options?.reply_markup?.inline_keyboard?.flat() ?? []});return {} as never
+      }})
+    const click = async(text:string) => menu.handle(context(replies.at(-1)!.buttons.find(b=>b.text===text)!.callback_data) as never)
+    await menu.list(context() as never)
+    await click('claude');await click('Sonnet');await click('high')
+    const restarted = new ControlStore(dir,1000)
+    const captured = await restarted.captureChoice(menu.initial)
+    assert.equal(captured.preset.model,'sonnet');assert.equal(captured.preset.effort,'high')
+    const before = await restarted.status()
+    await assert.rejects(menu.saveSelection(models[1], 'xhigh'), /Effort xhigh is not supported.*low, medium, high/)
+    await assert.rejects(validateSelection({id:'s',name:'Sonnet',cli:'claude',model:'sonnet',effort:'high'}, [], async()=>true), /No models advertised for claude.*current selection unchanged/)
+    assert.deepEqual(await restarted.status(), before)
+    const {ownerRun} = await import('./helpers/owner-run.js')
+    const {startExecutorJob} = await import('../src/executor.js')
+    await mkdir(join(dir,'bin'))
+    await writeFile(join(dir,'bin','claude'), `#!${process.execPath}\nrequire('fs').writeFileSync('launched.json',JSON.stringify(process.argv.slice(2)));require('fs').readFileSync(0,'utf8')`, {mode:0o700})
+    process.env.PATH = join(dir,'bin') + ':' + priorPath
+    await ownerRun(dir,'r_sonnet_selected')
+    const job = await startExecutorJob(['synthetic request'], {workspace:dir,controlDir:dir,binDir:join(dir,'bin'),runId:'r_sonnet_selected',timeoutMs:5000,repairEnabled:false,
+      cli:captured.preset.cli,model:captured.preset.model,effort:captured.preset.effort,sessionId:captured.sessionId})
+    const closed = new Promise<number|null>(resolve=>job.child.once('close',resolve))
+    assert.equal(await closed,0)
+    assert.deepEqual(JSON.parse(await readFile(join(dir,'launched.json'),'utf8')).slice(-4), ['--model','sonnet','--effort','high'])
+    await job.cleanup()
+  } finally {
+    if (priorPath === undefined) delete process.env.PATH; else process.env.PATH = priorPath
+    await rm(dir,{recursive:true,force:true})
+  }
+})

package/test/application-channel.test.ts

@@ -450,3 +450,27 @@ test('administrator task grant replacement preserves the runtime file owner', {s
     const disabled=await stat(file);assert.equal(disabled.uid,20000);assert.equal(disabled.gid,20000)
   }finally{await rm(dir,{recursive:true,force:true})}
 })
+
+test('empty server Claude catalog rejects Sonnet chat selection without changing Opus xhigh', async t => {
+  const root = await mkdtemp(join(tmpdir(),'ez-app-missing-claude-'))
+  t.after(()=>rm(root,{recursive:true,force:true}))
+  const owned = await owner(root), control = new ControlStore(root,1000)
+  const initial = {id:'opus',name:'Opus',cli:'claude',model:'opus',effort:'xhigh'}
+  await control.captureChoice(initial)
+  const {createAiMenu} = await import('../src/menu.js')
+  let models: import('../src/ai.js').ModelChoice[] = []
+  const menu = createAiMenu(control,'claude',async()=>models,root,undefined,async()=>true)
+  const channel = new ApplicationChannel({controlDir:root,initial,wake:()=>{},cancel:async()=>{},aiControls:menu})
+  const binding = (await channel.bindings.register('app',token(),owned,true))!
+  const before = await control.status()
+  const input = {action:'model',expectedSession:before.activeSession!.sessionId,cli:'claude',model:'sonnet',effort:'high'}
+  await assert.rejects(channel.changeControls(binding.bindingId,input), /No models advertised for claude.*current selection unchanged/)
+  assert.deepEqual(await control.status(),before)
+  models = [{cli:'claude',model:'sonnet',name:'Sonnet',efforts:['low','medium','high']}]
+  await assert.rejects(channel.changeControls(binding.bindingId,{...input,effort:'xhigh'}), /Effort xhigh is not supported.*low, medium, high/)
+  assert.deepEqual(await control.status(),before)
+  await channel.changeControls(binding.bindingId,input)
+  const admitted = await channel.submit(binding.bindingId,{requestId:'sonnet',scope:'chat',text:'Synthetic request',followTelegram:true})
+  assert.equal(admitted.execution!.preset.model,'sonnet')
+  assert.equal(admitted.execution!.preset.effort,'high')
+})

package/test/application-controls.test.ts

@@ -53,7 +53,8 @@ test('private scope reset and model controls preserve running sessions and share
     {cli:'codex',model:'fixture-model',name:'Fixture',efforts:['low','high']},
     {cli:'opencode',model:'fixture-other',name:'Other',efforts:[]},
   ],root,join(root,'native-home'),async()=>true)
-  const channel = new ApplicationChannel({controlDir:root,initial:menu.initial,aiControls:menu,wake:()=>{},cancel:async()=>{}})
+  const closed:string[] = []
+  const channel = new ApplicationChannel({controlDir:root,initial:menu.initial,aiControls:menu,wake:()=>{},cancel:async()=>{},closeSession:async session=>{if(session)closed.push(session.sessionId)}})
   t.after(async()=>{await channel.stop();await rm(root,{recursive:true,force:true})})
   const token = randomBytes(32).toString('base64url')
   const binding = (await channel.bindings.register('private',token,owner))!
@@ -77,6 +78,7 @@ test('private scope reset and model controls preserve running sessions and share
   assert.equal((await call({action:'new',expectedSession:before.activeSessionId})).status,200)
   const next = await channel.scopeControls(binding.bindingId,'exercise')
   assert.notEqual(next.activeSessionId,before.activeSessionId)
+  assert.deepEqual(closed,[]) // a private scope runs under its binding, so no owner-authority close turn
   assert.equal(next.ai.selectedId,menu.initial.id)
   assert.equal((await call({action:'new',expectedSession:before.activeSessionId})).status,400)
   assert.equal((await control.executionSession(run.execution!)).nativeSessionId,'native-private')
@@ -89,6 +91,7 @@ test('private scope reset and model controls preserve running sessions and share
   assert.deepEqual((await control.status()).ai!.presets,presets)
   assert.equal((await call({action:'model',expectedSession:next.activeSessionId,cli:'codex',model:'fixture-model',effort:'high'})).status,200)
   const updated = await channel.submit(binding.bindingId,{requestId:'updated-model',scope:'exercise',text:'same engine'})
+  assert.deepEqual(closed,[])
   assert.equal(updated.execution!.sessionId,next.activeSessionId)
   assert.equal(updated.execution!.preset.effort,'high')
   assert.deepEqual((await new RunStore(root).get(after.id))!.execution,after.execution)

package/test/intake-relay.test.ts

@@ -1,6 +1,6 @@
 import test from 'node:test'
 import assert from 'node:assert/strict'
-import { randomBytes } from 'node:crypto'
+import { randomBytes, randomUUID } from 'node:crypto'
 import { mkdtemp, readdir, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -17,6 +17,8 @@ import { atomicTaskFile, Tasks } from '../src/tasks.js'
 import { EventSources } from '../src/event-sources.js'
 import { ownerRun } from './helpers/owner-run.js'
 import { packageVersion } from '../src/version.js'
+import { SESSION_CLOSE_PROMPT } from '../src/session-close.js'
+import type { ExecutorOptions } from '../src/executor.js'
 import type { Config } from '../src/config.js'
 
 const message = (id: number, text = 'hello'): Update => ({
@@ -32,6 +34,7 @@ const message = (id: number, text = 'hello'): Update => ({
 const fixture = async (overrides: Partial<Config> = {}) => {
   const dir = await mkdtemp(join(tmpdir(), 'ez-intake-relay-'))
   const launched: string[][] = []
+  const launchOptions: ExecutorOptions[] = []
   const replies: string[] = []
   const members = new Map<number, string>()
   const keyboards: { text: string; callback_data: string }[][][] = []
@@ -47,8 +50,9 @@ const fixture = async (overrides: Partial<Config> = {}) => {
     ...overrides,
   }
   const make = () => {
-    const relay = createRelay(config, async (texts) => {
+    const relay = createRelay(config, async (texts, options) => {
       launched.push(texts)
+      launchOptions.push(options)
       const child = spawn(process.execPath, ['-e', 'setTimeout(() => {}, 50)'])
       children.push(child)
       await once(child, 'spawn')
@@ -79,6 +83,7 @@ const fixture = async (overrides: Partial<Config> = {}) => {
   return {
     dir,
     launched,
+    launchOptions,
     replies,
     members,
     keyboards,
@@ -336,6 +341,35 @@ test('new conversation leaves already accepted messages pinned to the old conver
   } finally { await f.close() }
 })
 
+test('new conversation gives the started one a single silent close turn in its own native session', async () => {
+  const f = await fixture()
+  try {
+    const runs = new RunStore(f.dir), store = new ControlStore(f.dir, 1000)
+    const settled = async () => {
+      for (let i = 0; i < 200 && (await runs.list()).some((r) => ['queued', 'running'].includes(r.status)); i++)
+        await new Promise((resolve) => setTimeout(resolve, 10))
+    }
+    await f.relay.bot.handleUpdate(message(1, '/new'))
+    assert.equal(f.launched.length, 0) // an unstarted conversation has nothing to keep
+    await f.relay.bot.handleUpdate(message(2, 'My sister is called Ana'))
+    await f.relay.drainInbox(true)
+    await settled()
+    const first = (await store.getActiveSession())!
+    assert.equal(first.hasStarted, true)
+    await f.relay.bot.handleUpdate(message(3, '/new'))
+    await settled()
+    assert.deepEqual(f.launched.at(-1), [SESSION_CLOSE_PROMPT])
+    const close = (await runs.list()).find((r) => r.sessionClose)!
+    assert.equal(close.execution!.sessionId, first.sessionId)
+    assert.equal(close.chatId, undefined); assert.equal(close.messageId, undefined)
+    const options = f.launchOptions.at(-1)!
+    assert.equal(options.isResume, true)
+    assert.equal(options.promptSuffix, '') // no reply mechanism: nothing is delivered
+    assert.notEqual((await store.getActiveSession())!.sessionId, first.sessionId)
+    assert.equal((await runs.list()).filter((r) => r.sessionClose).length, 1)
+  } finally { await f.close() }
+})
+
 test('accepted DM survives relay restart and duplicate delivery creates exactly one run', async () => {
   const f = await fixture()
   try {
@@ -752,3 +786,30 @@ test('tasks command never reaches the executor on invalid input or foreign sende
     assert.equal(f.launched.length, 0)
   } finally { await f.close() }
 })
+
+test('tasks list and detail show saved frequency and ordered setup path without changing or launching work',async()=>{
+  const f=await fixture()
+  try{
+    const {Scheduler}=await import('../src/scheduler.js')
+    const control=new ControlStore(f.dir,1000),scheduler=new Scheduler(f.dir)
+    const preset={id:'primary',name:'Primary',cli:'claude',model:'opus',effort:'high'}
+    const fallbacks=[
+      {...preset,id:'second',authProfile:'claude2'},
+      {id:'third',name:'Third',cli:'codex',authProfile:'work',model:'gpt-6-sol',effort:'xhigh'},
+      {id:'fourth',name:'Fourth',cli:'pi',model:'anthropic/claude-sonnet',effort:'medium'}]
+    const saved=await scheduler.save({id:'analyst',name:'Analyst',text:'Read the saved role.',owner:(await control.status()).owner!,
+      execution:{sessionId:randomUUID(),preset,fallbacks},
+      enabled:true,trigger:{cron:'*/30 * * * *',timezone:'America/New_York',start:'2027-01-01T00:00:00Z'}})
+    const path='claude (default login) · opus · high → claude@claude2 · opus · high → codex@work · gpt-6-sol · xhigh → pi · anthropic/claude-sonnet · medium'
+    await f.relay.bot.handleUpdate(message(1,'/tasks'))
+    const list=f.replies.at(-1)!
+    assert.ok(list.includes('Schedule · Every 30 minutes · America/New_York'))
+    assert.ok(list.includes(`Execution · ${path}`))
+    await f.relay.bot.handleUpdate(message(2,'/tasks 1'))
+    const detail=f.replies.at(-1)!
+    assert.ok(detail.includes('Schedule\nEvery 30 minutes · America/New_York'))
+    assert.ok(detail.includes(`Execution path\n${path}`))
+    assert.deepEqual(await scheduler.get(saved.id),saved)
+    assert.equal(f.launched.length,0)
+  }finally{await f.close()}
+})

package/test/model-policy.test.ts

@@ -17,7 +17,7 @@ test('engine defaults stay omitted and explicit native settings survive every ad
   const preset={id:'chosen',name:'Chosen',cli,model:'native-model',effort:'ultra'}
   assert.deepEqual(executionDefaults(cli,preset),preset)
   await validateSelection(preset,[{cli,model:'native-model',name:'Native',efforts:['ultra']}],async()=>true)
-  await assert.rejects(validateSelection({...preset,effort:'unsupported'},[{cli,model:'native-model',name:'Native',efforts:['ultra']}],async()=>true),/installed client catalog/)
+  await assert.rejects(validateSelection({...preset,effort:'unsupported'},[{cli,model:'native-model',name:'Native',efforts:['ultra']}],async()=>true),/Effort unsupported is not supported.*Supported efforts: ultra/)
   assert.throws(()=>executionDefaults(cli,{effort:'bad option'}),/Invalid reasoning effort/)
  }
  assert.deepEqual(executionOverrides('codex',{model:'old',effort:'max'},'new'),{model:'new',effort:undefined})

package/test/plugin-broker.test.mjs

@@ -103,7 +103,8 @@ test('isolated broker authenticates an owned run, pins plugin revision, and writ
     assert.deepEqual(JSON.parse(listed.stdout), { sample: 'sample' });
     const detailed = await request(f.socket, { version: 1, id: randomUUID(), operation: 'manager', runId: f.runId, args: ['tools', 'list', '--details'] });
     assert.equal(detailed.ok, true);
-    assert.deepEqual(JSON.parse(detailed.stdout).sample.commands, ['ez sample --help']);
+    assert.deepEqual(JSON.parse(detailed.stdout).sample.aliases, ['sample']);
+    assert.equal(JSON.parse(detailed.stdout).sample.example, 'ez sample --help');
     assert.deepEqual(JSON.parse(detailed.stdout).sample.skillReads, [['ez', 'tools', 'skill', 'sample', 'SKILL.md']]);
     const skill = await request(f.socket, { version: 1, id: randomUUID(), operation: 'manager', runId: f.runId, args: ['tools', 'skill', 'sample', 'SKILL.md'] });
     assert.equal(skill.code, 0);
@@ -249,3 +250,49 @@ test('task launch broker admits only its fixed application command and writes no
     const revoked=await request(f.socket,{version:1,id:randomUUID(),operation:'task-launch',runId:taskRun,stdin:JSON.stringify(input)});assert.equal(revoked.ok,false);
   }finally{abort.abort();await serving;process.env.PATH=oldPath;await ledger.stop();provider.closeAllConnections();await new Promise(r=>provider.close(r));}
 });
+
+// Native engines and Node scripts wire child stdin as a socket they may never
+// close. The isolated client must reach the broker instead of waiting for EOF,
+// while pipes and files still deliver their complete input.
+test('isolated client does not wait forever on an inherited open stdin socket', async t => {
+  const { createServer: createSocketServer } = await import('node:net');
+  const { spawn } = await import('node:child_process');
+  const { once } = await import('node:events');
+  const root = await fs.realpath(await fs.mkdtemp(path.join(tmpdir(), 'e-')));
+  t.after(() => fs.rm(root, { recursive: true, force: true }));
+  const socket = path.join(root, 'b.sock'), invokes = [];
+  const broker = createSocketServer(connection => {
+    let buffer = '';
+    connection.on('data', chunk => {
+      buffer += chunk;
+      if (!buffer.includes('\n')) return;
+      const frame = JSON.parse(buffer);
+      if (frame.operation === 'invoke') invokes.push(frame);
+      connection.end(JSON.stringify(frame.operation === 'resolve' ? { ok: true, revision, capability: 'c'.repeat(64) } : { ok: true, code: 0, stdout: 'ok' }) + '\n');
+    });
+  });
+  await new Promise(resolve => broker.listen(socket, resolve));
+  t.after(() => broker.close());
+  const client = new URL('../bin/ez', import.meta.url).pathname;
+  const env = { PATH: process.env.PATH, EZ_PLUGIN_BROKER_SOCKET: socket, EZ_RUN_ID: 'r_client' };
+  const finish = async child => {
+    let stdout = '';
+    child.stdout.on('data', chunk => stdout += chunk);
+    const timer = setTimeout(() => child.kill('SIGKILL'), 10_000);
+    const [code, signal] = await once(child, 'close');
+    clearTimeout(timer);
+    return { code, signal, stdout };
+  };
+  const open = spawn(process.execPath, [client, 'sample', 'read'], { env });
+  t.after(() => open.kill('SIGKILL'));
+  assert.deepEqual(await finish(open), { code: 0, signal: null, stdout: 'ok' });
+  assert.deepEqual(invokes.at(-1).args, ['read']);
+  assert.equal(invokes.at(-1).stdin, undefined);
+  const supplied = spawn(process.execPath, [client, 'sample', 'write'], { env });
+  supplied.stdin.end('payload');
+  assert.equal((await finish(supplied)).code, 0);
+  assert.equal(invokes.at(-1).stdin, 'payload');
+  const piped = spawn('/bin/sh', ['-c', '(sleep 1.5; printf late) | "$0" "$1" sample pipe', process.execPath, client], { env, stdio: ['ignore', 'pipe', 'inherit'] });
+  assert.equal((await finish(piped)).code, 0);
+  assert.equal(invokes.at(-1).stdin, 'late');
+});

package/test/plugin-manager.test.mjs

@@ -7,6 +7,7 @@ import {execFile,spawn} from 'node:child_process';
 import {once} from 'node:events';
 import {promisify} from 'node:util';
 import {snapshot,init as initManager,validate,compose,locked,bindToolDiscovery,prepareCommand} from '../src/plugins/manager.mjs';
+import {TOOLS_LINE} from '../src/tools-line.mjs';
 import { ControlStore, ownerId, ownerEpoch } from '../src/control-state.js';
 import { ApplicationBindings } from '../src/application-channel.js';
 import { RunStore } from '../src/runs.js';
@@ -33,6 +34,16 @@ for(const cleanup of ['success','failure','already-removed']) test(`cancel remov
  if(cleanup==='failure')assert.match(stderr,/cleanup failed/);
  assert.deepEqual((await fs.readFile(log,'utf8')).trim().split('\n').map(JSON.parse),[['run'],['container','rm','--force','exact-test-container']]);
 });
+// Compose --rm only removes a container that ran. Compose dying between create
+// and start (signal, broken output pipe, error) must not strand it in Created.
+for(const exit of ['signal','failure','success']) test(`compose exit by ${exit} without manager cancellation ${exit==='success'?'leaves no cleanup call':'removes its created container'}`,async t=>{
+ const root=await fs.mkdtemp(path.join(tmpdir(),'ez-exit-'));t.after(()=>fs.rm(root,{recursive:true,force:true}));
+ const log=path.join(root,'calls.jsonl');
+ await fs.writeFile(path.join(root,'docker'),`#!${process.execPath}\nconst fs=require('fs'),a=process.argv.slice(2);fs.appendFileSync(${JSON.stringify(log)},JSON.stringify(a)+'\\n');if(a[0]==='container')process.exit(0);console.error('Container exact-test-container Created');${exit==='signal'?"process.kill(process.pid,'SIGKILL')":exit==='failure'?'process.exit(1)':'process.exit(0)'}\n`,{mode:0o700});
+ const {stdout}=await exec(process.execPath,['--input-type=module','-e',`import {run} from ${JSON.stringify(new URL('../src/plugins/manager.mjs',import.meta.url).href)};console.log((await run(['run'],{container:'exact-test-container',capture:true})).code)`],{env:{...process.env,PATH:root+path.delimiter+process.env.PATH}});
+ assert.equal(stdout.trim(),exit==='signal'?'130':exit==='failure'?'1':'0');
+ assert.deepEqual((await fs.readFile(log,'utf8')).trim().split('\n').map(JSON.parse),[['run'],...(exit==='success'?[]:[['container','rm','--force','exact-test-container']])]);
+});
 async function fixture(t) {
  const root=await fs.mkdtemp(path.join(tmpdir(),'ez-tools-'));t.after(()=>fs.rm(root,{recursive:true,force:true}));
  const source=path.join(root,'source'),home=path.join(root,'tools'),deploymentDir=path.join(root,'deployment'),workspace=path.join(deploymentDir,'mind'),control=path.join(deploymentDir,'control'),hostConfig=path.join(deploymentDir,'host-executor.json'),fake=path.join(root,'fake');
@@ -83,56 +94,43 @@ test('catalog paths resolve relative to the catalog and pin each new agent indep
  assert.notEqual(first.sample.revision,next.catalog.sample.revision);
  assert.deepEqual(JSON.parse((await f.call('plugins','available')).stdout),first);
 });
-test('native discovery binding preserves notes and adds bounded nonblocking routing guidance',async t=>{
- const f=await fixture(t),instructions=path.join(f.workspace,'AGENTS.md'),notes=path.join(f.workspace,'TOOLS.md');
- await fs.writeFile(instructions,'Owner mandate\n');
+test('init never writes native instructions; the retired footer becomes the static tools line once',async t=>{
+ const f=await fixture(t),instructions=path.join(f.workspace,'AGENTS.md'),override=path.join(f.workspace,'AGENTS.override.md');
  await init(f.home,f.workspace);
- await assert.rejects(fs.access(notes),{code:'ENOENT'});
- const first=await fs.readFile(instructions,'utf8');assert(first.startsWith('Owner mandate\n'));assert(first.includes(f.home+'/bin/ez'));
- assert.match(first,/tools list --details/);assert.match(first,/`--help`/);assert.match(first,/during a foreground owner turn, prefer `ezenciel-agents-schedule create --now \.\.\.`/);assert.match(first,/A `\[schedule \.\.\.\]` turn executes its assigned work directly and must not schedule it again/);assert.doesNotMatch(first,/ezenciel-agents-message|KISS/);
- const managed=first.slice(first.indexOf('<!-- ez tools: begin -->'),first.indexOf('<!-- ez tools: end -->')+'<!-- ez tools: end -->'.length);
- assert.ok(Buffer.byteLength(managed)<=600);
- await bindToolDiscovery(f.home,f.workspace);assert.equal(await fs.readFile(instructions,'utf8'),first);
- await fs.writeFile(notes,'Legacy policy');
- await bindToolDiscovery(f.home,f.workspace);assert.equal(await fs.readFile(notes,'utf8'),'Legacy policy');
- await fs.writeFile(path.join(f.workspace,'AGENTS.override.md'),'Override mandate');
- await bindToolDiscovery(f.home,f.workspace);assert.match(await fs.readFile(path.join(f.workspace,'AGENTS.override.md'),'utf8'),/Override mandate/);
+ await assert.rejects(fs.access(instructions),{code:'ENOENT'});
+ const footer='<!-- ez tools: begin -->\nUse `/x/bin/ez`.\n<!-- ez tools: end -->';
+ await fs.writeFile(instructions,`Owner mandate\n\n${footer}\n\nOwner tail\n`);await fs.writeFile(override,`Override mandate\n${footer}\n`);
+ await bindToolDiscovery(f.home,f.workspace);
+ const retired=await fs.readFile(instructions,'utf8');
+ assert.equal(retired,`Owner mandate\n\n${TOOLS_LINE}\n\nOwner tail\n`);
+ assert.equal(await fs.readFile(override,'utf8'),`Override mandate\n${TOOLS_LINE}\n`);
+ await bindToolDiscovery(f.home,f.workspace);assert.equal(await fs.readFile(instructions,'utf8'),retired); // once: idempotent
+ await fs.writeFile(instructions,`${TOOLS_LINE}\n${footer}\n`);await bindToolDiscovery(f.home,f.workspace);
+ assert.equal(await fs.readFile(instructions,'utf8'),`${TOOLS_LINE}\n\n`); // never duplicates the line
  await fs.writeFile(instructions,'<!-- ez tools: begin -->broken');
  await assert.rejects(bindToolDiscovery(f.home,f.workspace),/Malformed/);
  assert.equal(await fs.readFile(instructions,'utf8'),'<!-- ez tools: begin -->broken');
+ const notes=path.join(f.workspace,'TOOLS.md');await fs.writeFile(notes,footer);
  await fs.rm(instructions);await fs.symlink(notes,instructions);
  await assert.rejects(bindToolDiscovery(f.home,f.workspace),/regular file/);
- assert.equal(await fs.readFile(notes,'utf8'),'Legacy policy');
-});
-test('isolated discovery uses the relay-bound ez client without exposing toolsHome',async t=>{
- const f=await fixture(t);await fs.mkdir(f.home);const workspace=await fs.realpath(f.workspace),controlDir=await fs.realpath(f.control),toolsHome=await fs.realpath(f.home),host={cli:'codex',isolation:'isolated',agents:[{name:'sample',workspace,controlDir,binDir:path.join(f.root,'bin'),toolsHome}]};
- await fs.mkdir(path.join(f.root,'bin'));await fs.writeFile(f.hostConfig,JSON.stringify(host));
- await init(f.home,f.workspace,undefined,f.hostConfig);
- const instructions=await fs.readFile(path.join(f.workspace,'AGENTS.md'),'utf8');assert.match(instructions,/Use `ez`/);assert.match(instructions,/`tools list --details`/);assert.doesNotMatch(instructions,new RegExp(f.home.replace(/[.*+?^${}()|[\]\\]/g,'\\$&')));
-});
-test('discovery rejects an over-budget launcher before rewriting instructions',async t=>{
- const f=await fixture(t),instructions=path.join(f.workspace,'AGENTS.md'),longHome=path.join(f.root,'h'.repeat(200),'n'.repeat(200));
- await fs.mkdir(longHome,{recursive:true});await fs.writeFile(instructions,'Owner mandate\n');
- await assert.rejects(bindToolDiscovery(longHome,f.workspace),/600-byte core budget/);
- assert.equal(await fs.readFile(instructions,'utf8'),'Owner mandate\n');
-});
-test('standalone init rejects over-budget guidance before creating activation state',async t=>{
- const f=await fixture(t),instructions=path.join(f.workspace,'AGENTS.md'),longHome=path.join(f.root,'i'.repeat(200),'j'.repeat(200)),catalog=path.join(f.root,'empty-catalog.json');
- await fs.writeFile(catalog,'{}');await fs.writeFile(instructions,'Owner mandate\n');
- await assert.rejects(initManager(longHome,f.workspace,catalog,undefined,true),/600-byte core budget/);
- assert.deepEqual(await fs.readdir(longHome),[]);
- assert.equal(await fs.readFile(instructions,'utf8'),'Owner mandate\n');
+ assert.equal(await fs.readFile(notes,'utf8'),footer);
+});
+test('manifest example is one line starting with a declared command',async t=>{
+ const f=await fixture(t),p=await snapshot(f.source);
+ assert.doesNotThrow(()=>validate({...f.manifest,example:'sample search "q" --limit 3'},f.deployment,p.files));
+ for(const example of ['other --help','sample\nsecond','x'.repeat(161),3]) assert.throws(()=>validate({...f.manifest,example},f.deployment,p.files),/Manifest example/);
 });
 test('installed snippets follow install, upgrade and uninstall without files or Docker reads',async t=>{
  const f=await fixture(t);await init(f.home,f.workspace);
  const details=async()=>JSON.parse((await f.call('tools','list','--details')).stdout);
  assert.deepEqual(await details(),{});
  for(const description of ['Synthetic capability','Updated capability']) {
-  await fs.writeFile(path.join(f.source,'ez-plugin.json'),JSON.stringify({...f.manifest,description}));
+  const example=description==='Updated capability'?'sample run --json':undefined;
+  await fs.writeFile(path.join(f.source,'ez-plugin.json'),JSON.stringify({...f.manifest,description,example}));
   const p=await snapshot(f.source);
   await f.call('plugins','install','sample','--source',f.source,'--revision',p.revision);
   const before=await fs.readFile(f.log,'utf8'),index=await details();
-  assert.equal(index.sample.description,description);assert.deepEqual(index.sample.commands,['ez sample --help']);
+  assert.deepEqual(index.sample.aliases,['sample']);assert.equal(index.sample.purpose,description);assert.equal(index.sample.example,`ez ${example??'sample --help'}`);
   assert.equal(await fs.readFile(index.sample.skills[0],'utf8'),'Synthetic');
   assert.deepEqual(index.sample.skillReads,[['ez','tools','skill','sample','SKILL.md']]);
   assert.deepEqual(JSON.parse((await f.call('tools','skill','sample','SKILL.md')).stdout),{plugin:'sample',revision:p.revision,path:'SKILL.md',content:'Synthetic'});
@@ -278,6 +276,24 @@ test('an unreadable invocation lease pid falls through to container verification
   await assert.rejects(locked(f.home,async()=>{}),/Stale command invocation lease/);
  } finally {process.kill=kill0;process.env.PATH=path0;}
 });
+test('a lease from another PID namespace is live while its call container runs, then drains',async t=>{
+ const f=await fixture(t);
+ const directory=path.join(f.home,'command-invocations');await fs.mkdir(directory,{recursive:true});
+ const lease=path.join(directory,'00000000-0000-4000-8000-000000000001.json');
+ // Isolated broker lease: its pid means nothing in this namespace (EPERM/ESRCH or an unrelated process).
+ await fs.writeFile(lease,JSON.stringify({pid:1,container:'broker-call',pidNamespace:'pid:[4026531999]'}),{mode:0o600});
+ const path0=process.env.PATH;process.env.PATH=f.fake+path.delimiter+path0;t.after(()=>{process.env.PATH=path0;});
+ const docker=state=>fs.writeFile(path.join(f.fake,'docker'),`#!${process.execPath}\nconst a=process.argv.slice(2);if(a[0]==='container'&&a[1]==='inspect'){${state}}\n`,{mode:0o700});
+ await docker(`console.log('true')`);
+ await assert.rejects(locked(f.home,async()=>{}),/commands are active/); // never misreported as stale
+ let activated=false;const drain=locked(f.home,async()=>{activated=true;},{drainInvocations:true});
+ await new Promise(resolve=>setTimeout(resolve,100));assert.equal(activated,false);
+ await docker(`console.error('Error: No such object: broker-call');process.exit(1)`);
+ await drain;assert.equal(activated,true);await assert.rejects(fs.access(lease),{code:'ENOENT'});
+ await fs.writeFile(lease,JSON.stringify({pid:1,container:'broker-call',pidNamespace:'pid:[4026531999]'}),{mode:0o600});
+ await docker(`console.log('false')`);
+ await assert.rejects(locked(f.home,async()=>{}),/Stale command invocation lease/); // stopped but not removed: inspect first
+});
 test('changed source, symlinks, reserved aliases, arbitrary Docker fields rejected',async t=>{
  const f=await fixture(t),p=await snapshot(f.source);await init(f.home,f.workspace);
  await fs.writeFile(path.join(f.source,'client.mjs'),'changed');await assert.rejects(f.call('plugins','install','sample','--source',f.source,'--revision',p.revision));
@@ -532,9 +548,7 @@ test('standalone CLI has discoverable setup, independent guidance and status wit
  const help=JSON.parse((await exec(process.execPath,[bin,'--help'])).stdout);
  assert.match(help.usage,/--standalone/);
  await exec(process.execPath,[bin,'init','--standalone','--home',f.home,'--workspace',f.workspace],{env:f.env});
- const notes=await fs.readFile(path.join(f.workspace,'AGENTS.md'),'utf8');
- assert.match(notes,/tools list --details/);
- assert.doesNotMatch(notes,/Finish the main Telegram|ezenciel-agents-message/);
+ await assert.rejects(fs.access(path.join(f.workspace,'AGENTS.md')),{code:'ENOENT'}); // instructions stay owner-written
  const launcher=path.join(f.home,'bin','ez');
  const status=JSON.parse((await exec(launcher,['status'],{cwd:f.root,env:f.env})).stdout);
  assert.equal(status.main,null);assert.deepEqual(status.plugins,[]);

package/test/run-handoff.test.ts

@@ -0,0 +1,132 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { appendFile, mkdir, mkdtemp, readdir, readFile, rename, rm, stat, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { Update } from 'grammy/types'
+import { createRelay } from '../src/index.js'
+import { ControlStore } from '../src/control-state.js'
+import { RunStore } from '../src/runs.js'
+import { Scheduler, holdsSchedule } from '../src/scheduler.js'
+import { initialPreset } from '../src/ai.js'
+
+const until = async (check: () => Promise<boolean>) => {
+  for (let i = 0; i < 400; i++) { if (await check()) return; await new Promise(r => setTimeout(r, 25)) }
+  throw new Error('Timed out')
+}
+const config = (controlDir: string, workspace: string) =>
+  ({ workspace, controlDir, pairingTtlMs: 1000, executorTimeoutMs: 0, executorCli: 'grok', telegramBotToken: 'fixture' })
+
+// The test is the host transport: it claims requests, streams events and
+// keeps the heartbeat fresh. A second path to the same control directory gives
+// the next relay an empty memory ledger, as a replacement process would have.
+const fixture = async (t: test.TestContext) => {
+  const root = await mkdtemp(join(tmpdir(), 'ez-run-handoff-')), dir = join(root, 'control'), next = join(root, 'next-control')
+  const host = join(dir, 'host-executor')
+  await mkdir(host, { recursive: true, mode: 0o700 }); await symlink(dir, next)
+  const transport = process.env.EZ_EXECUTOR_TRANSPORT
+  process.env.EZ_EXECUTOR_TRANSPORT = 'host'
+  const beat = setInterval(() => void writeFile(join(host, 'beat.tmp'), JSON.stringify({ at: Date.now() }))
+    .then(() => rename(join(host, 'beat.tmp'), join(host, 'heartbeat.json'))).catch(() => {}), 200)
+  t.after(async () => {
+    clearInterval(beat)
+    if (transport === undefined) delete process.env.EZ_EXECUTOR_TRANSPORT; else process.env.EZ_EXECUTOR_TRANSPORT = transport
+    await rm(root, { recursive: true, force: true })
+  })
+  const files = async () => (await readdir(host)).filter(file => file !== 'heartbeat.json' && !file.endsWith('.tmp')).sort()
+  const control = new ControlStore(dir, 1000)
+  await control.requestPairing(101, 101); await control.approveOwner(101)
+  return { root, dir, next, host, files, control, owner: (await control.status()).owner! }
+}
+
+test('a graceful relay stop hands running host work to the next relay, which records it without relaunching', async t => {
+  const { root, dir, next, host, files, control, owner } = await fixture(t)
+  const scheduler = new Scheduler(dir), first = new RunStore(dir)
+  const execution = await control.captureChoice({ ...initialPreset('grok'), model: 'fixture-model' })
+  const due = Date.now() + 1000
+  const saved = await scheduler.save({ id: 'long', name: 'Long', text: 'Long work', owner, execution, enabled: true,
+    trigger: { everySeconds: 60, start: new Date(due).toISOString() } }, true)
+  await scheduler.tick(owner, first, due)
+  const foreground = await first.create({ chatId: 101, telegramUserId: 101, texts: ['chat'], execution })
+  const before = createRelay(config(dir, root))
+  await before.drainSources()
+  const scheduled = (await first.list()).find(run => run.scheduled)!
+  for (const id of [foreground.id, scheduled.id]) {
+    await until(async () => (await files()).includes(id + '.request.json'))
+    await rename(join(host, id + '.request.json'), join(host, id + '.running.json'))
+    await appendFile(join(host, id + '.events'), JSON.stringify({ stream: 'stdout', text: 'working\n' }) + '\n')
+  }
+  await before.stop()
+  assert.equal((await stat(join(dir, 'run-handoff.json'))).mode & 0o777, 0o600)
+  const handoff = JSON.parse(await readFile(join(dir, 'run-handoff.json'), 'utf8'))
+  assert.ok(Date.now() - Date.parse(handoff.writtenAt) < 60_000)
+  assert.deepEqual(handoff.runs.map((run: { id: string; status: string }) => [run.id, run.status]).sort(),
+    [[foreground.id, 'running'], [scheduled.id, 'running']].sort())
+  assert.deepEqual(await files(), [foreground.id + '.events', foreground.id + '.running.json', scheduled.id + '.events', scheduled.id + '.running.json'].sort(),
+    'the stop must not cancel, finish or resubmit host work')
+
+  const after = createRelay(config(next, root)), runs = new RunStore(next)
+  after.bot.botInfo = { id: 999, is_bot: true, first_name: 'Fixture', username: 'fixture_bot' } as typeof after.bot.botInfo
+  after.bot.api.config.use(async () => ({ ok: true, result: { message_id: 42 } }) as never)
+  try {
+    await after.adoptHandoff()
+    await assert.rejects(readFile(join(dir, 'run-handoff.json')), { code: 'ENOENT' })
+    assert.deepEqual((await runs.list()).map(run => run.status), ['running', 'running'])
+    // The new ledger accepts the run's result delivery and holds its recurring schedule.
+    assert.ok(await runs.enqueueMessage(scheduled.id, 'Result after replacement'))
+    await scheduler.tick(owner, runs, due + 60_000); await after.drainSources()
+    assert.equal((await runs.list()).length, 2, 'the next recurrence waits for the adopted occurrence')
+    await new Promise(resolve => setTimeout(resolve, 300))
+    assert.ok(!(await files()).some(file => file.endsWith('.request.json') || file.endsWith('.cancel')), 'adoption never resubmits or cancels')
+    await appendFile(join(host, foreground.id + '.events'), JSON.stringify({ stream: 'exit', code: 0 }) + '\n')
+    await rm(join(host, foreground.id + '.running.json'))
+    await until(async () => (await runs.get(foreground.id))?.status === 'completed')
+    assert.equal((await new ControlStore(next, 1000).executionSession(execution)).hasStarted, true)
+    // /stop reaches the adopted run through the existing cancel path.
+    await after.bot.handleUpdate({ update_id: 1, message: { message_id: 1, date: 0, text: '/stop', from: { id: 101, is_bot: false, first_name: 'Owner' }, chat: { id: 101, type: 'private', first_name: 'Owner' } } } as Update)
+    await until(async () => (await runs.get(scheduled.id))?.status === 'cancelled')
+    assert.ok((await files()).includes(scheduled.id + '.cancel'), 'the host is asked to stop the adopted executor')
+    assert.equal(holdsSchedule(saved, (await runs.get(scheduled.id))!), false)
+  } finally { await after.stop() }
+})
+
+test('adoption fails closed for unknown, invalid, stale or corrupt handoff records and never launches', async t => {
+  const { root, dir, files, owner } = await fixture(t)
+  const scheduler = new Scheduler(dir)
+  const saved = await scheduler.save({ id: 'gone', name: 'Gone', text: 'work', owner, enabled: true, trigger: { everySeconds: 60, start: new Date(Date.now() + 1000).toISOString() },
+    execution: { sessionId: '00000000-0000-4000-8000-000000000000', preset: { ...initialPreset('grok'), model: 'fixture-model' } } }, true)
+  const lost = { version: 1, id: 'r_schedule_lost', chatId: 101, telegramUserId: 101, texts: ['work'], status: 'running', createdAt: new Date().toISOString(),
+    scheduled: { id: saved.id, revision: saved.revision, dueAt: new Date().toISOString(), pairedAt: owner.pairedAt } }
+  const write = (runs: unknown[], writtenAt = new Date().toISOString()) => writeFile(join(dir, 'run-handoff.json'), JSON.stringify({ version: 1, writtenAt, runs }))
+  await write([lost, { ...lost, id: '../escape' }, { ...lost, id: 'r_done', status: 'completed' }])
+  let launches = 0
+  const relay = createRelay(config(dir, root), async () => { launches++; throw new Error('Must not launch') }), runs = new RunStore(dir)
+  try {
+    await relay.adoptHandoff()
+    await until(async () => (await runs.get(lost.id))?.status === 'failed')
+    const failed = (await runs.get(lost.id))!
+    assert.match(failed.failure?.error ?? '', /outcome is unknown/)
+    assert.equal(failed.failureReason, 'handoff-outcome-unknown')
+    assert.equal(failed.interrupted, true)
+    assert.equal(holdsSchedule(saved, failed), true, 'an unknown outcome holds its schedule until an explicit edit')
+    assert.deepEqual((await runs.list()).map(run => run.id), [lost.id])
+    for (const stale of [() => write([{ ...lost, id: 'r_schedule_stale' }], new Date(Date.now() - 25 * 3600_000).toISOString()), () => writeFile(join(dir, 'run-handoff.json'), '{not json')]) {
+      await stale()
+      await relay.adoptHandoff()
+      await assert.rejects(readFile(join(dir, 'run-handoff.json')), { code: 'ENOENT' })
+    }
+    await relay.drainSources()
+    assert.equal(launches, 0)
+    assert.deepEqual((await runs.list()).map(run => run.id), [lost.id])
+    assert.deepEqual(await files(), [])
+  } finally { await relay.stop() }
+  // A relay without host transport removes a record it cannot adopt.
+  delete process.env.EZ_EXECUTOR_TRANSPORT
+  await write([{ ...lost, id: 'r_schedule_local' }])
+  const local = createRelay(config(dir, root))
+  try {
+    await local.adoptHandoff()
+    await assert.rejects(readFile(join(dir, 'run-handoff.json')), { code: 'ENOENT' })
+    assert.equal(await runs.get('r_schedule_local'), null)
+  } finally { await local.stop() }
+})