@jc_stack/ez-agents 0.1.0-beta.12

package/test/host-executor.test.ts

@@ -0,0 +1,149 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { mkdtemp, mkdir, readFile, writeFile, rm, realpath } from 'node:fs/promises'
+import path from 'node:path'
+import { tmpdir } from 'node:os'
+import { serveHostExecutor } from '../src/host-executor.js'
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { isHostRunId } from '../src/host-executor-protocol.js'
+import { EXECUTOR_REGISTRY } from '../src/executor.js'
+import { packageVersion } from '../src/version.js'
+
+test('one installed CLI executes two agent bindings with separate minds and sanitized environment', async () => {
+  const root=await mkdtemp(path.join(tmpdir(),'ez-host-'))
+  const abort=new AbortController()
+  const old=EXECUTOR_REGISTRY.grok.command
+  const oldBuild=EXECUTOR_REGISTRY.grok.buildArgs
+  const oldToken=process.env.TELEGRAM_BOT_TOKEN
+  const oldPath=process.env.PATH
+  let server:Promise<void>|undefined
+  try {
+    const binary=path.join(root,'cli')
+    await writeFile(binary,`#!${process.execPath}\nif(process.env.EZ_RUN_ID==='r_hold')setInterval(()=>{},1000);console.log(JSON.stringify({cwd:process.cwd(),home:process.env.HOME,token:process.env.TELEGRAM_BOT_TOKEN,control:process.env.EZ_CONTROL_DIR,run:process.env.EZ_RUN_ID,args:process.argv.slice(2)}));\n`,{mode:0o700})
+    await writeFile(path.join(root,'claude'),await readFile(binary),{mode:0o700})
+    process.env.PATH=root+path.delimiter+oldPath
+    EXECUTOR_REGISTRY.grok.command=binary
+    EXECUTOR_REGISTRY.grok.buildArgs=EXECUTOR_REGISTRY.codex.buildArgs
+    process.env.TELEGRAM_BOT_TOKEN='must-not-reach-host-cli'
+    const agents=await Promise.all(['one','two'].map(async name=>{
+      const workspace=path.join(root,name,'mind'),controlDir=path.join(root,name,'control')
+      await mkdir(workspace,{recursive:true});await mkdir(controlDir,{recursive:true})
+      const toolsHome=path.join(root,name,'tools');await mkdir(toolsHome)
+      await writeFile(path.join(toolsHome,'config.json'),JSON.stringify({schemaVersion:1,workspace:await realpath(workspace)}))
+      return {name,workspace,controlDir,binDir:path.join(root,'bin'),toolsHome}
+    }))
+    server=serveHostExecutor({cli:'grok',agents},abort.signal)
+    for(const agent of agents){
+      const dir=path.join(agent.controlDir,'host-executor')
+      for(let n=0;n<100;n++){try{await readFile(path.join(dir,'heartbeat.json'));break}catch{await new Promise(r=>setTimeout(r,20))}}
+      assert.equal(JSON.parse(await readFile(path.join(dir,'heartbeat.json'),'utf8')).version,packageVersion)
+      await writeFile(path.join(dir,`r_${agent.name}.request.json`),JSON.stringify({texts:['test'],options:{workspace:'/wrong',controlDir:'/wrong',toolsHome:'/wrong',cli:'grok',timeoutMs:5000}}))
+    }
+    for(const agent of agents){
+      const file=path.join(agent.controlDir,'host-executor',`r_${agent.name}.events`)
+      let events:any[]=[]
+      for(let n=0;n<150;n++){try{events=(await readFile(file,'utf8')).trim().split('\n').map(l=>JSON.parse(l));if(events.some(e=>e.stream==='exit'))break}catch{}await new Promise(r=>setTimeout(r,20))}
+      assert.equal(events.find(e=>e.stream==='exit')?.code,0)
+      const result=JSON.parse(events.filter(e=>e.stream==='stdout').map(e=>e.text).join(''))
+      assert.equal(result.cwd,await realpath(agent.workspace))
+      assert.equal(result.control,agent.controlDir)
+      assert.equal(result.token,undefined)
+      assert.ok(result.args.includes(agent.toolsHome))
+      assert.ok(!result.args.includes('/wrong'))
+      assert.equal(result.home,process.env.HOME)
+    }
+    // Exercise the actual client -> file transport -> host CLI path, not a
+    // hand-written smoke request, with the production Telegram batch ID shape.
+    const client=spawn(process.execPath,['--import',fileURLToPath(new URL('../node_modules/tsx/dist/loader.mjs',import.meta.url)),fileURLToPath(new URL('../src/host-executor-client.ts',import.meta.url)),agents[0].controlDir,'tg_6293305'],{stdio:['pipe','pipe','pipe']})
+    let stdout='',stderr=''
+    client.stdout.on('data',chunk=>stdout+=chunk)
+    client.stderr.on('data',chunk=>stderr+=chunk)
+    client.stdin.end(JSON.stringify({texts:['Telegram message'],options:{cli:'grok',timeoutMs:5000}}))
+    assert.equal(await new Promise(resolve=>client.once('close',resolve)),0,stderr)
+    assert.equal(JSON.parse(stdout).run,'tg_6293305')
+    const eventId='event_'+'a'.repeat(64)
+    const eventClient=spawn(process.execPath,['--import',fileURLToPath(new URL('../node_modules/tsx/dist/loader.mjs',import.meta.url)),fileURLToPath(new URL('../src/host-executor-client.ts',import.meta.url)),agents[0].controlDir,eventId],{stdio:['pipe','pipe','pipe']})
+    let eventOutput='',eventError=''
+    eventClient.stdout.on('data',chunk=>eventOutput+=chunk)
+    eventClient.stderr.on('data',chunk=>eventError+=chunk)
+    eventClient.stdin.end(JSON.stringify({texts:['Untrusted plugin event'],options:{cli:'grok',timeoutMs:5000}}))
+    assert.equal(await new Promise(resolve=>eventClient.once('close',resolve)),0,eventError)
+    assert.equal(JSON.parse(eventOutput).run,eventId)
+    const switched=spawn(process.execPath,['--import',fileURLToPath(new URL('../node_modules/tsx/dist/loader.mjs',import.meta.url)),fileURLToPath(new URL('../src/host-executor-client.ts',import.meta.url)),agents[0].controlDir,'tg_6293306'],{stdio:['pipe','pipe','pipe']})
+    let switchedOutput=''
+    switched.stdout.on('data',chunk=>switchedOutput+=chunk)
+    switched.stderr.resume()
+    switched.stdin.end(JSON.stringify({texts:['Explicit CLI change'],options:{cli:'claude',timeoutMs:5000}}))
+    assert.equal(await new Promise(resolve=>switched.once('close',resolve)),0)
+    assert.ok(JSON.parse(switchedOutput).args.includes('--print'))
+    await assert.rejects(serveHostExecutor({cli:'grok',agents},new AbortController().signal),/already running/)
+    const directory=path.join(agents[0].controlDir,'host-executor')
+    const submit=async(id:string)=>writeFile(path.join(directory,id+'.request.json'),JSON.stringify({texts:['test'],options:{cli:'grok',timeoutMs:5000}}))
+    await submit('r_hold')
+    for(let n=0;n<100;n++){try{await readFile(path.join(directory,'r_hold.process.json'));break}catch{await new Promise(r=>setTimeout(r,20))}}
+    await submit('r_queued')
+    await new Promise(r=>setTimeout(r,350))
+    await assert.rejects(readFile(path.join(directory,'r_queued.running.json')),{code:'ENOENT'})
+    await writeFile(path.join(directory,'r_hold.cancel'),'')
+    let output=''
+    for(let n=0;n<200;n++){try{output=await readFile(path.join(directory,'r_queued.events'),'utf8');if(output.includes('"stream":"exit"'))break}catch{}await new Promise(r=>setTimeout(r,20))}
+    assert.match(output, /"stream":"exit","code":0/)
+    assert.match(await readFile(path.join(directory,'r_hold.events'),'utf8'), /"stream":"exit","code":1/)
+  } finally {
+    abort.abort();await server
+    EXECUTOR_REGISTRY.grok.command=old
+    EXECUTOR_REGISTRY.grok.buildArgs=oldBuild
+    process.env.PATH=oldPath
+    if(oldToken===undefined)delete process.env.TELEGRAM_BOT_TOKEN;else process.env.TELEGRAM_BOT_TOKEN=oldToken
+    await rm(root,{recursive:true,force:true})
+  }
+})
+
+
+test('host run IDs accept production formats and reject unsafe paths',()=>{
+  for(const id of ['tg_6293305','r_example_123','event_'+'a'.repeat(64)])assert.equal(isHostRunId(id),true)
+  for(const id of ['../tg_1','tg_1/other','tg_abc','event_bad','event_'+'a'.repeat(63),'event_'+'g'.repeat(64),'tg_1\n','r_',''])assert.equal(isHostRunId(id),false)
+})
+
+test('client tolerates missing heartbeat and consumes completion before checking host health',async()=>{
+ const root=await mkdtemp(path.join(tmpdir(),'ez-heartbeat-'))
+ const directory=path.join(root,'host-executor');await mkdir(directory)
+ const client=spawn(process.execPath,['--import',fileURLToPath(new URL('../node_modules/tsx/dist/loader.mjs',import.meta.url)),fileURLToPath(new URL('../src/host-executor-client.ts',import.meta.url)),root,'tg_99'],{stdio:['pipe','pipe','pipe']})
+ const closed=new Promise(resolve=>client.once('close',resolve))
+ let stderr='';client.stderr.on('data',chunk=>stderr+=chunk);client.stdout.resume()
+ client.stdin.end(JSON.stringify({texts:['test'],options:{}}))
+ try {
+  for(let n=0;n<100;n++){try{await readFile(path.join(directory,'tg_99.request.json'));break}catch{await new Promise(r=>setTimeout(r,20))}}
+  await new Promise(r=>setTimeout(r,400))
+  assert.equal(client.exitCode,null,stderr)
+  await assert.rejects(readFile(path.join(directory,'tg_99.cancel')),{code:'ENOENT'})
+  await writeFile(path.join(directory,'tg_99.events'),JSON.stringify({stream:'exit',code:0})+'\n')
+  assert.equal(await closed,0,stderr)
+ } finally {client.kill();await closed;await rm(root,{recursive:true,force:true})}
+})
+
+test('client cancels on stale or invalid heartbeat instead of waiting indefinitely',async()=>{
+ for(const heartbeat of [{at:Date.now()-60000},{at:'invalid'}]) {
+  const root=await mkdtemp(path.join(tmpdir(),'ez-heartbeat-invalid-'))
+  try {
+   const directory=path.join(root,'host-executor');await mkdir(directory)
+   await writeFile(path.join(directory,'heartbeat.json'),JSON.stringify(heartbeat))
+   const client=spawn(process.execPath,['--import',fileURLToPath(new URL('../node_modules/tsx/dist/loader.mjs',import.meta.url)),fileURLToPath(new URL('../src/host-executor-client.ts',import.meta.url)),root,'tg_98'],{stdio:['pipe','pipe','pipe']})
+   let stderr='';client.stderr.on('data',chunk=>stderr+=chunk);client.stdout.resume()
+   client.stdin.end(JSON.stringify({texts:['test'],options:{}}))
+   assert.equal(await new Promise(resolve=>client.once('close',resolve)),1)
+   assert.match(stderr,/offline|Invalid host CLI heartbeat/)
+   assert.equal(await readFile(path.join(directory,'tg_98.cancel'),'utf8'),'')
+  } finally {await rm(root,{recursive:true,force:true})}
+ }
+})
+
+
+test('host rejects a plugin registry bound to another workspace',async()=>{
+ const root=await mkdtemp(path.join(tmpdir(),'ez-host-plugin-binding-'))
+ try {
+  await writeFile(path.join(root,'config.json'),JSON.stringify({schemaVersion:1,workspace:'/another-agent'}))
+  await assert.rejects(serveHostExecutor({cli:'codex',agents:[{name:'test',workspace:root,controlDir:root,binDir:root,toolsHome:root}]},new AbortController().signal),/another workspace/)
+ } finally {await rm(root,{recursive:true,force:true})}
+})

package/test/inbox-burst.test.ts

@@ -0,0 +1,66 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { InboxStore } from '../src/inbox.js'
+
+test('durable debounce resets quiet time and respects the ten-item cap', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'ez-burst-'))
+  let now = 0
+  const inbox = new InboxStore(dir, () => now)
+  try {
+    await inbox.accept({ update_id: 1 })
+    now = 1999
+    assert.equal(await inbox.next(), undefined)
+    await inbox.accept({ update_id: 2 })
+    now = 3998
+    assert.equal(await inbox.next(), undefined)
+    now = 3999
+    const first = (await inbox.next())!
+    assert.deepEqual(
+      first.entries.map((e) => e.update.update_id),
+      [1, 2],
+    )
+    await inbox.finish(first.id)
+    for (let id = 3; id <= 13; id++) await inbox.accept({ update_id: id })
+    const full = (await inbox.next())!
+    assert.equal(full.entries.length, 10)
+    await inbox.finish(full.id)
+    now += 2000
+    assert.equal((await inbox.next())?.entries[0].update.update_id, 13)
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+})
+
+test('restart-aged work flushes at max wait and an album is not split at the cap', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'ez-album-'))
+  let now = 0
+  const inbox = new InboxStore(dir, () => now)
+  try {
+    await inbox.accept({ update_id: 1 })
+    now = 29999
+    await inbox.accept({ update_id: 2 })
+    now = 30000
+    const first = (await inbox.next())!
+    assert.equal(first.entries.length, 2)
+    await inbox.finish(first.id)
+    for (let id = 3; id <= 13; id++)
+      await inbox.accept({
+        update_id: id,
+        message: {
+          message_id: id,
+          from: { id: 101, is_bot: false, first_name: 'Fixture' },
+          date: 0,
+          chat: { id: 101, type: 'private', first_name: 'Fixture' },
+          media_group_id: id >= 11 ? 'fixture_album' : undefined,
+        },
+      })
+    assert.equal(await inbox.next(), undefined)
+    now += 2000
+    assert.equal((await inbox.next())?.entries.length, 11)
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+})

package/test/inbox.test.ts

@@ -0,0 +1,102 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, rm, writeFile, stat, readFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { Update } from 'grammy/types'
+import { InboxStore } from '../src/inbox.js'
+import { RunStore } from '../src/runs.js'
+
+const update = (id: number): Update => ({ update_id: id })
+test('intake survives restart, deduplicates IDs, seals membership and retains cancellation tombstones', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'ez-inbox-'))
+  try {
+    let inbox = new InboxStore(dir)
+    assert.equal(await inbox.accept(update(1)), true)
+    inbox = new InboxStore(dir)
+    assert.equal(await inbox.accept(update(1)), false)
+    await inbox.accept(update(2))
+    assert.equal(await inbox.next(), undefined)
+    const batch = (await inbox.next(true))!
+    assert.deepEqual(
+      batch.entries.map((e) => e.update.update_id),
+      [1, 2],
+    )
+    await inbox.accept(update(3))
+    inbox = new InboxStore(dir)
+    assert.deepEqual(await inbox.next(true), batch)
+    const runs = new RunStore(dir)
+    const input = { id: batch.id, chatId: 101, telegramUserId: 101, texts: ['hello'] }
+    await runs.create(input)
+    // Crash between run creation and inbox completion must not produce a second run.
+    await runs.create(input)
+    assert.equal((await runs.list()).length, 1)
+    await inbox.finish(batch.id)
+    assert.equal((await inbox.next(true))?.id, 'tg_3')
+    assert.equal(await inbox.cancel(), 1)
+    assert.equal(await inbox.accept(update(3)), false)
+    assert.equal(await inbox.next(true), undefined)
+    assert.equal((await stat(join(dir, 'inbox.json'))).mode & 0o777, 0o600)
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+})
+
+test('corrupt intake fails closed without overwriting evidence; invalid identifiers are rejected', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'ez-inbox-corrupt-'))
+  try {
+    await writeFile(join(dir, 'inbox.json'), '{broken')
+    const inbox = new InboxStore(dir)
+    await assert.rejects(inbox.accept(update(4)), /Inbox unreadable/)
+    assert.equal(await readFile(join(dir, 'inbox.json'), 'utf8'), '{broken')
+    assert.throws(() => inbox.accept(update(-1)), /Invalid update ID/)
+    await assert.rejects(
+      new RunStore(dir).create({ id: '../escape', chatId: 101, telegramUserId: 101, texts: [] }),
+    )
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+})
+
+test('failed batches are visible, not automatically retried, and do not block following messages', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'ez-inbox-failed-'))
+  try {
+    const inbox = new InboxStore(dir)
+    await Promise.all([inbox.accept(update(1)), inbox.accept(update(2)), inbox.accept(update(2))])
+    const batch = (await inbox.next(true))!
+    await inbox.finish(batch.id, true)
+    assert.deepEqual(await inbox.status(), { pending: 0, failed: 1 })
+    assert.equal(await inbox.next(true), undefined)
+    await inbox.accept(update(3))
+    assert.equal((await inbox.next(true))?.id, 'tg_3')
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+})
+
+test('manual retry is owner/chat-bound and cannot revive pending or cancelled work', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'ez-inbox-retry-'))
+  try {
+    const inbox = new InboxStore(dir)
+    await inbox.accept({
+      update_id: 1,
+      message: {
+        message_id: 1,
+        date: 0,
+        text: 'Fixture',
+        from: { id: 101, is_bot: false, first_name: 'Fixture' },
+        chat: { id: 101, type: 'private', first_name: 'Fixture' },
+      },
+    })
+    const batch = (await inbox.next(true))!
+    await inbox.finish(batch.id, true)
+    assert.equal(await inbox.retryLatest(202, 101), undefined)
+    assert.equal(await inbox.retryLatest(101, -101), undefined)
+    assert.equal(await inbox.retryLatest(101, 101), batch.id)
+    assert.equal(await inbox.retryLatest(101, 101), undefined)
+    await inbox.cancel()
+    assert.equal(await inbox.retryLatest(101, 101), undefined)
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+})

package/test/install-config.test.ts

@@ -0,0 +1,75 @@
+import assert from 'node:assert/strict'
+import { mkdtemp, readFile, rm, stat, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { parseEnv } from 'node:util'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import test from 'node:test'
+import { configureInstallation } from '../src/install-config.js'
+import { readActiveExecutor } from '../src/setup.js'
+import { serviceDefinition } from '../src/service.js'
+
+test('configure preserves custom paths and unknown settings, keeps token private, and never resets the mind', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'ez-configure-'))
+  try {
+    await writeFile(path.join(root, '.env'), 'EZ_AGENT_WORKSPACE="my mind"\nEZ_CONTROL_DIR="private control"\nEXTRA="keep me"\n')
+    const token = '123456789:' + 'a'.repeat(30)
+    const result = await configureInstallation(root, 'codex', token)
+    assert.equal(result.tokenConfigured, true)
+    assert.equal(JSON.stringify(result).includes(token), false)
+    const env = parseEnv(await readFile(result.envFile, 'utf8'))
+    assert.equal(env.EXTRA, 'keep me')
+    assert.equal(env.TELEGRAM_BOT_TOKEN, token)
+    assert.equal(env.EZ_AGENT_WORKSPACE, path.join(root, 'my mind'))
+    assert.equal((await stat(result.envFile)).mode & 0o777, 0o600)
+    assert.equal(await readActiveExecutor(result.envFile), 'codex')
+    const soul = path.join(result.workspace, 'SOUL.md')
+    await writeFile(soul, 'Customized purpose')
+    const repeated = await configureInstallation(root, 'codex')
+    assert.deepEqual(repeated.created, [])
+    assert.equal(repeated.tokenConfigured, true)
+    assert.equal(await readFile(soul, 'utf8'), 'Customized purpose')
+    await assert.rejects(stat(result.controlDir), { code: 'ENOENT' }) // No control/owner mutation.
+  } finally { await rm(root, { recursive: true, force: true }) }
+})
+
+test('configure rejects secret/path hazards without replacing existing configuration', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'ez-configure-'))
+  try {
+    const env = path.join(root, '.env')
+    const original = 'EZ_AGENT_WORKSPACE="."\n'
+    await writeFile(env, original)
+    await assert.rejects(configureInstallation(root, 'codex'), /separate/)
+    await assert.rejects(configureInstallation(root, 'codex', 'do-not-print-me'), error => !String(error).includes('do-not-print-me'))
+    assert.equal(await readFile(env, 'utf8'), original)
+    await rm(env)
+    const target = path.join(root, 'private-file')
+    await writeFile(target, 'preserve')
+    await symlink(target, env)
+    await assert.rejects(configureInstallation(root, 'codex'), /regular file/)
+    assert.equal(await readFile(target, 'utf8'), 'preserve')
+  } finally { await rm(root, { recursive: true, force: true }) }
+})
+
+test('packaged configure accepts token through stdin without echo or extra initialization', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'ez-configure-cli-'))
+  try {
+    const token = '123456789:' + 'b'.repeat(30)
+    const bin = fileURLToPath(new URL('../bin/ezenciel-agents-setup.mjs', import.meta.url))
+    const result = spawnSync(process.execPath, [bin, 'configure', 'codex', '--token-stdin'], { cwd: root, input: token, encoding: 'utf8', timeout: 10000 })
+    assert.equal(result.status, 0, result.stderr)
+    assert.equal((result.stdout + result.stderr).includes(token), false)
+    assert.equal(JSON.parse(result.stdout).created.length, 4)
+    assert.equal(parseEnv(await readFile(path.join(root, '.env'), 'utf8')).TELEGRAM_BOT_TOKEN, token)
+  } finally { await rm(root, { recursive: true, force: true }) }
+})
+
+test('Docker startup uses explicit deployment binding and literal paths without secrets or host supervisors', () => {
+  const definition = serviceDefinition('/tmp/my agent $literal')
+  assert.equal(definition.command, 'docker')
+  assert.ok(definition.args.includes('/tmp/my agent $literal/docker.env'))
+  assert.deepEqual(definition.args.slice(-4), ['up', '-d', '--wait', 'relay'])
+  assert.doesNotMatch(JSON.stringify(definition), /TELEGRAM_BOT_TOKEN|launchctl|systemctl/)
+  assert.throws(() => serviceDefinition('/tmp/\nbad'), /single-line/)
+})

package/test/install-tools.test.mjs

@@ -0,0 +1,59 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import path from 'node:path';
+import {preflight,installationStatus,build,hostEnvironment} from '../src/install-tools.mjs';
+
+async function fixture(t){const root=await fs.mkdtemp(path.join(tmpdir(),'ez-install-tools-'));t.after(()=>fs.rm(root,{recursive:true,force:true}));return root;}
+test('preflight checks the selected executable and reports missing prerequisites without credentials',async t=>{
+  const home=await fixture(t),binary=path.join(home,'codex');await fs.writeFile(binary,'#!/bin/sh\nexit 0',{mode:0o755});
+  const invoke=async(cmd)=>{if(cmd==='pnpm')return '10.30.3';if(cmd==='docker')throw Error('Docker unavailable');return 'codex fixture';};
+  const result=await preflight({home,executor:binary},invoke);assert.equal(result.ok,false);
+  assert.equal(result.checks.find(c=>c.name==='executor').path,binary);assert.equal(result.checks.find(c=>c.name==='executor').sandboxVerified,false);
+  assert.equal(result.checks.find(c=>c.name==='docker').ok,false);
+  const absent=await preflight({home,executor:path.join(home,'missing')},invoke);assert.equal(absent.checks.find(c=>c.name==='executor').ok,false);
+  const previous=process.env.TELEGRAM_BOT_TOKEN;process.env.TELEGRAM_BOT_TOKEN='must-not-leak';
+  try{assert.equal(hostEnvironment().TELEGRAM_BOT_TOKEN,undefined);}finally{if(previous===undefined)delete process.env.TELEGRAM_BOT_TOKEN;else process.env.TELEGRAM_BOT_TOKEN=previous;}
+});
+test('installation status separates files, pairing and current-owner Telegram delivery evidence',async t=>{
+  const root=await fixture(t),control=path.join(root,'control');
+  assert.equal((await installationStatus(root)).stage,'not-configured');
+  for(const dir of ['host-executor','outbox','runs'])await fs.mkdir(path.join(control,dir),{recursive:true});
+  for(const name of ['agent.json','host-executor.json','docker.env','relay.env'])await fs.writeFile(path.join(root,name),'private');
+  const write=(name,obj)=>fs.writeFile(path.join(control,name),JSON.stringify(obj));
+  await write('heartbeat.json',{at:Date.now(),polling:true});await write('host-executor/heartbeat.json',{at:Date.now()});
+  assert.equal((await installationStatus(root)).stage,'awaiting-owner');
+  const owner={telegramUserId:123,telegramChatId:123,pairedAt:new Date(Date.now()-10000).toISOString()};await write('control-state.json',{owner});
+  assert.equal((await installationStatus(root)).stage,'awaiting-telegram-reply');
+  const item={runId:'tg_12',chatId:123,receipt:{messageIds:[42],deliveredAt:new Date().toISOString()}};
+  await write('outbox/test.sent.json',item);await write('runs/tg_12.json',{status:'completed',chatId:123,telegramUserId:999});
+  assert.equal((await installationStatus(root)).telegramReplyVerified,false);
+  await write('runs/tg_12.json',{status:'completed',chatId:123,telegramUserId:123});
+  assert.equal((await installationStatus(root)).stage,'ready-for-telegram-plugin-request');
+  await write('heartbeat.json',{at:0,polling:true});assert.equal((await installationStatus(root)).stage,'runtime-offline');
+  await write('outbox/test.sent.json',{...item,runId:'../../escape'});assert.equal((await installationStatus(root)).telegramReplyVerified,false);
+  await fs.writeFile(path.join(control,'control-state.json'),'{');await assert.rejects(installationStatus(root));
+});
+test('same-artifact build retries do not spawn a second Docker build and reuse verified completed image',async t=>{
+  const home=await fixture(t),source=path.join(home,'source');await fs.mkdir(source);await fs.writeFile(path.join(source,'package.json'),'{}');
+  let started,finish,count=0;const running=new Promise(r=>started=r),held=new Promise(r=>finish=r);
+  const invoke=async(cmd,args)=>{if(cmd==='npm')return JSON.stringify([{files:[{path:'package.json'}]}]);if(args[0]==='build'){count++;started();await held;}return 'sha256:fixture';};
+  const first=build({home,source},invoke);await running;
+  assert.equal((await build({home,source},invoke)).state,'busy-or-interrupted');assert.equal(count,1);
+  finish();const result=await first;assert.equal(result.state,'completed');
+  assert.equal((await build({home,source},invoke)).reused,true);assert.equal(count,1);
+  await fs.writeFile(path.join(source,'package.json'),'{"changed":true}');await build({home,source},invoke);assert.equal(count,2);
+});
+test('a failed build releases its own lock and leaves a failure receipt for diagnosis',async t=>{
+  const home=await fixture(t),source=path.join(home,'source');await fs.mkdir(source);await fs.writeFile(path.join(source,'package.json'),'{}');
+  const invoke=async(cmd)=>{if(cmd==='npm')return JSON.stringify([{files:[{path:'package.json'}]}]);throw Error('Synthetic build failed');};
+  await assert.rejects(build({home,source},invoke),/Synthetic/);
+  const [id]=await fs.readdir(path.join(home,'builds'));const dir=path.join(home,'builds',id);
+  assert.equal(JSON.parse(await fs.readFile(path.join(dir,'status.json'))).state,'failed');await assert.rejects(fs.access(path.join(dir,'lock')));
+});
+test('source changes during a build cannot produce a reusable success receipt',async t=>{
+  const home=await fixture(t),source=path.join(home,'source');await fs.mkdir(source);await fs.writeFile(path.join(source,'package.json'),'{}');
+  const invoke=async(cmd,args)=>{if(cmd==='npm')return JSON.stringify([{files:[{path:'package.json'}]}]);if(args[0]==='build')await fs.writeFile(path.join(source,'package.json'),'{"changed":true}');return 'image';};
+  await assert.rejects(build({home,source},invoke),/changed during build/);
+});