@jc_stack/ez-agents 0.1.0-beta.19 → 0.1.0-beta.23

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.1.0-beta.23
+
+- Identify failed publisher API reads and missing release tags without exposing
+  credentials or signed asset URLs. Document verified tag/artifact staging and
+  recovery before a fresh publication attempt.
+- Include beta.22 incomplete-update-receipt recovery; the earlier unpublished
+  candidate remains preserved. Existing beta acceptance limits remain.
+
+## 0.1.0-beta.22
+
+- Ignore incomplete or malformed update-receipt directories until a valid,
+  atomically committed `job.json` exists. They have no activation authority and
+  must not take the host executor offline.
+
+## 0.1.0-beta.21
+
+- Initialize fresh Telegram bots before reading their identity. Beta.19 could
+  retry forever before polling, causing main upgrades to fail their health gate.
+- Restore the unchanged deployment layout required for upgrades from beta.18
+  and beta.19; extending health grace does not fix the initialization failure.
+- Include beta.20 health diagnostics. Preserve the earlier immutable unpublished
+  candidate; existing beta acceptance limits remain.
+
+## 0.1.0-beta.20
+
+- Retain a bounded, content-free health predicate in a failed main-upgrade
+  receipt before rollback replaces the candidate relay. This distinguishes relay
+  polling and host-executor heartbeat failures without persisting control-state,
+  provider, environment, or Docker diagnostic content.
+
 ## 0.1.0-beta.19
 
 - Preserve host-backed run completion and delivery evidence while the relay

package/docker/healthcheck.mjs

@@ -1,8 +1,15 @@
 import { readFileSync } from 'node:fs';
-const value = JSON.parse(readFileSync('/state/control/heartbeat.json', 'utf8'));
-if (!value.polling || Date.now() - value.at > 20000) process.exit(1);
+const relayControl = process.env.EZ_HEALTH_RELAY_CONTROL_DIR || '/state/control';
+const fail = code => { process.stderr.write(`EZ_HEALTH_${code}\n`); process.exit(1); };
+let value;
+try { value = JSON.parse(readFileSync(relayControl + '/heartbeat.json', 'utf8')); }
+catch { fail('RELAY_UNREADABLE'); }
+if (!value.polling) fail('RELAY_NOT_POLLING');
+if (!Number.isFinite(value.at) || Date.now() - value.at > 20000) fail('RELAY_STALE');
 
 if (process.env.EZ_EXECUTOR_TRANSPORT === 'host') {
-  const host = JSON.parse(readFileSync(process.env.EZ_CONTROL_DIR + '/host-executor/heartbeat.json', 'utf8'));
-  if (Date.now() - host.at > 15000) process.exit(1);
+  let host;
+  try { host = JSON.parse(readFileSync(process.env.EZ_CONTROL_DIR + '/host-executor/heartbeat.json', 'utf8')); }
+  catch { fail('HOST_UNREADABLE'); }
+  if (!Number.isFinite(host.at) || Date.now() - host.at > 15000) fail('HOST_STALE');
 }

package/docs/architecture/ai-selection.md

@@ -28,8 +28,10 @@ offer their own default only in this slice. Refresh by opening the native client
 the relay does not install models, manage subscriptions or guess aliases.
 
 Setup initialization and relay startup seed one default choice per installed client.
-Settings → Refresh available AIs repeats discovery. Active/default presets and
-queued snapshots are preserved; discovery only refreshes unused detected entries.
+Choose AI opens the available installed-model catalog directly; Settings keeps
+saved choices and Refresh available AIs repeats default discovery. Active/default
+presets and queued snapshots are preserved; discovery only refreshes unused
+detected entries.
 Codex uses its native `config/read` interface; Grok reads its documented user
 model/effort settings (or `models` for the default model). Claude reads user and
 workspace JSON settings; OpenCode reports resolved config. Unknown defaults and

package/docs/docker-runtime.md

@@ -61,11 +61,13 @@ Live smoke uses the same host CLI and requires an actual Telegram receipt.
 Restart preserves pairing and files. One kernel lock excludes relay/smoke
 writers; exit 73 means a writer is active. Do not delete its lock to bypass it.
 Health requires recent polling and host-transport heartbeats, not just a process.
-Fatal Telegram polling errors, including `409 Conflict`, stop intake and await
-worker cleanup plus in-flight task/outbox writes before exit. A conflict still
-requires the operator to stop the competing bot poller; the relay does not retry
-around that ownership error. Pending and uncertain deliveries keep their existing
-outbox/receipt semantics; executor stdout is not replayed as a reply.
+Relay replacement retains the existing 30-second startup grace and deployment
+layout, so compatible releases remain eligible for agent-owned upgrades.
+An interrupted Telegram poller keeps authorized work and in-flight outbox writes
+alive while it retries intake. A `409 Conflict` still requires the operator to
+stop the competing poller; it remains unhealthy after the startup grace. Pending
+and uncertain deliveries keep their existing outbox/receipt semantics; executor
+stdout is not replayed as a reply.
 Signal and fatal-error paths share one shutdown; a secondary cleanup error is
 reported without replacing the original startup/polling failure.
 

package/docs/trusted-publishing.md

@@ -65,8 +65,28 @@ jobs from its latest attempt. Tag, PR and other workflow runs cannot shadow it;
 failed, pending or incomplete main CI cannot fall back to an older success.
 
 Create the `vVERSION` tag at that exact source commit and a **draft prerelease**
-with these assets, using native `gh release create --draft --prerelease` and
-`gh release upload` under existing release authority:
+with these assets under existing release authority. **Creating a draft release
+with `--target` does not create a Git tag.** Create and push the tag explicitly,
+then use `--verify-tag` to prevent staging against a missing remote tag:
+
+```sh
+# VERSION and SOURCE_SHA identify the reviewed, current-main candidate.
+git tag "v$VERSION" "$SOURCE_SHA"
+git push origin "refs/tags/v$VERSION"
+git ls-remote origin "refs/tags/v$VERSION"
+# Copy the already tested bytes, without rebuilding, to this exact basename.
+cp /absolute/tested-package.tgz /absolute/release/candidate.tgz
+gh release create "v$VERSION" --repo OWNER/REPO --verify-tag --draft --prerelease \
+  --title "v$VERSION" --notes-file /absolute/release/notes.md \
+  /absolute/release/candidate.tgz /absolute/release/release-receipt.json
+```
+
+If the tag already exists, read and verify its commit (peel annotated tags) rather
+than recreating or force-pushing it. Read back the draft by numeric ID and check
+asset names and downloaded SHA-256 before dispatch. `npm pack`'s default filename
+is not the publisher's asset name; GitHub asset labels do not rename the asset.
+Use `gh release upload` only to add a missing asset, never `--clobber` to replace
+candidate bytes or receipts. The required assets are:
 
 - `candidate.tgz`: the exact Mac-tested bytes from `npm pack --ignore-scripts`.
   Do not rebuild it on Actions.
@@ -114,6 +134,22 @@ identity on the release PR. A failed command after the publish call may mean npm
 accepted it: inspect registry state first. A rerun may verify an existing exact
 version; if the version is absent it refuses a second write. Reconcile first,
 then create a fresh authorized dispatch if appropriate. Never repeat or overwrite that version or silently repair tags.
+When validation fails, use the logged GitHub API path to identify the missing
+input. A tag lookup 404 is not evidence of a draft-release permission problem.
+A draft/asset 404 can mean absent evidence or insufficient access; verify with
+the existing authorized identity before diagnosing credentials. Do not broaden
+token permissions based on a generic 404.
+
+For a failure before the publish job starts, confirm that job was skipped and
+read npm for the exact version. If absent, repair missing staging inputs against
+the same approved commit/bytes, verify tag, asset names and digest, and create a
+fresh dispatch. If main or the package changes, prepare a new reviewed version;
+preserve the old draft instead of moving its tag or replacing its artifact.
+If any npm write may have started, use exact registry/artifact reconciliation
+above first. Publication recovery never means rolling back a running agent.
+Runtime upgrades and `failed`/`rolled-back` versus `recovery-required` recovery
+follow [upgrades](upgrades.md) under the installation's saved policy.
+
 Missing trust or registry access is an external dependency, not a reason to use
 a token workaround.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jc_stack/ez-agents",
-  "version": "0.1.0-beta.19",
+  "version": "0.1.0-beta.23",
   "private": false,
   "type": "module",
   "description": "A lightweight foundation for persistent business AI assistants using existing AI harnesses, workspaces and plugins.",

package/scripts/trusted-beta.mjs

@@ -87,8 +87,8 @@ export function tarManifest(path) {
   return JSON.parse(execFileSync('tar', ['-xOf', path, 'package/package.json'], { ...options, maxBuffer: 1024 * 1024 }));
 }
 
-async function responseBytes(response, max = MAX_ARTIFACT) {
-  assert(response.ok, `HTTP ${response.status} while reading release evidence`);
+async function responseBytes(response, max = MAX_ARTIFACT, context = 'release evidence') {
+  assert(response.ok, `HTTP ${response.status} while reading ${context}`);
   assert(Number(response.headers.get('content-length') || 0) <= max, 'Response too large');
   let size = 0; const chunks = [];
   for await (const chunk of response.body) { size += chunk.length; assert(size <= max, 'Response too large'); chunks.push(chunk); }
@@ -98,6 +98,8 @@ async function responseBytes(response, max = MAX_ARTIFACT) {
 export function githubClient(token, fetcher = fetch) {
   return async (path, binary = false) => {
     assert(path.startsWith('/repos/'), 'Invalid GitHub API path');
+    // Identify the failed read without logging tokens, response bodies or signed URLs.
+    const context = `GitHub GET ${path.split('?')[0]}`;
     const response = await fetcher(`https://api.github.com${path}`, {
       headers: { Accept: binary ? 'application/octet-stream' : 'application/vnd.github+json', ...(token ? { Authorization: `Bearer ${token}` } : {}), 'X-GitHub-Api-Version': '2022-11-28' },
       redirect: 'manual', signal: AbortSignal.timeout(30_000),
@@ -105,9 +107,12 @@ export function githubClient(token, fetcher = fetch) {
     if (binary && [301, 302, 303, 307, 308].includes(response.status)) {
       const location = new URL(response.headers.get('location'));
       assert(location.protocol === 'https:' && (location.hostname === 'release-assets.githubusercontent.com' || location.hostname === 'objects.githubusercontent.com'), 'Unexpected asset redirect');
-      return responseBytes(await fetcher(location, { signal: AbortSignal.timeout(60_000), redirect: 'error' }));
+      return responseBytes(await fetcher(location, { signal: AbortSignal.timeout(60_000), redirect: 'error' }), MAX_ARTIFACT, `${context} asset download`);
     }
-    const bytes = await responseBytes(response, binary ? MAX_ARTIFACT : 8 * 1024 * 1024);
+    if (response.status === 404 && path.includes('/git/ref/tags/')) {
+      throw new Error(`HTTP 404 while reading ${context}: release tag is missing or inaccessible; a draft release does not create its Git tag. Verify the remote tag at the reviewed source before dispatch.`);
+    }
+    const bytes = await responseBytes(response, binary ? MAX_ARTIFACT : 8 * 1024 * 1024, context);
     return binary ? bytes : JSON.parse(bytes.toString());
   };
 }

package/src/index.ts

@@ -1029,7 +1029,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
           await bot.api.deleteWebhook({ drop_pending_updates: false })
           await bot.api.setMyCommands(commands)
           await bot.api.setMyCommands(commands, { scope: { type: 'all_private_chats' } })
-          if (!bot.botInfo) await bot.init()
+          await bot.init()
           await bot.start({
             drop_pending_updates: false,
             onStart: (botInfo) => console.log(`✓ Bot @${botInfo.username} polling for messages...`),

package/src/menu.ts

@@ -53,9 +53,14 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
       : 'Selected for this conversation. Queued work unchanged.'}`)
   }
   const list = async (ctx: Context, settings = false) => {
+    if (!settings) {
+      const models = await catalog()
+      if (models.length) return available(ctx, 0, models)
+    }
     const state = await control.aiState(initial)
     const keyboard = new InlineKeyboard()
-    for (const preset of state.presets) button(keyboard,
+    const presets = settings ? state.presets : state.presets.filter((preset) => preset.id === initial.id)
+    for (const preset of presets) button(keyboard,
       `${preset.id === (settings ? state.defaultId : state.selectedId) ? '✓ ' : ''}${preset.name}`,
       async (next) => {
         if (settings) {
@@ -64,16 +69,17 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
           await next.reply(`Default: ${preset.name}. Applies to new conversations only.`)
         } else await choose(next, preset)
       })
-    button(keyboard, 'Add AI…', (next) => available(next))
-    if (settings) button(keyboard, 'Refresh available AIs', async (next) => {
+    button(keyboard, 'Browse available models', (next) => available(next))
+    button(keyboard, 'Refresh available AIs', async (next) => {
       await refresh()
       await list(next, true)
     })
-    await ctx.reply(settings ? 'Default for new conversations\nChoose a saved AI. Current work will not change.'
-      : 'Choose AI\nChanging CLI starts a fresh conversation; files stay.', { reply_markup: keyboard })
+    await ctx.reply(settings
+      ? 'Default for new conversations\nChoose a saved AI. Current work will not change.'
+      : 'Choose AI\nNo client catalog available. Showing the current client setup only.', { reply_markup: keyboard })
   }
-  const available = async (ctx: Context, page = 0) => {
-    const models = await catalog()
+  const available = async (ctx: Context, page = 0, listed?: ModelChoice[]) => {
+    const models = listed ?? await catalog()
     const keyboard = new InlineKeyboard()
     for (const model of models.slice(page * 8, page * 8 + 8)) {
       button(keyboard, `${model.cli} · ${model.name}`, async (next) => {
@@ -86,7 +92,7 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
     if (page > 0) button(keyboard, 'Previous', (next) => available(next, page - 1))
     if (models.length > (page + 1) * 8) button(keyboard, 'Next', (next) => available(next, page + 1))
     await ctx.reply(models.length
-      ? 'Installed client choices. Grok/Codex use their local model catalog; other clients use their own default. Adding saves the choice; it does not switch AI.'
+      ? 'Choose AI\nAvailable models are populated automatically from the installed clients. Grok/Codex use their local catalog; other clients use their own default. Choosing one saves it; it does not switch AI.'
       : 'No client catalog available. Open the installed CLI once, then try again.', { reply_markup: keyboard })
   }
   const save = async (ctx: Context, model: ModelChoice, effort?: string) => {

package/src/updates/control.mjs

@@ -7,6 +7,7 @@ import { digest, extract, newer, compatible, version, releaseContract, registryV
 export const read = async file => JSON.parse(await fs.readFile(file,'utf8'));
 export const missing = error => {if(error.code!=='ENOENT')throw error;return null;};
 export const targetId = value => {if(value!=='main'&&!/^[a-z][a-z0-9-]{0,39}$/.test(value))throw Error('Invalid update target');return value;};
+const jobId=/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
 export const updateHome = home => path.join(home,'updates');
 export async function state(home) {
   const config=await read(path.join(home,'config.json'));
@@ -77,12 +78,15 @@ export async function prepare(home,target,{file,release}) {
   } catch(error){await fs.rm(dir,{recursive:true,force:true});throw error;}
 }
 export function jobPath(home,id) {
-  if(!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(id))throw Error('Invalid upgrade job ID');
+  if(!jobId.test(id))throw Error('Invalid upgrade job ID');
   return path.join(updateHome(home),id);
 }
 export async function jobs(home) {
   const entries=await fs.readdir(updateHome(home),{withFileTypes:true}).catch(error=>{if(error.code==='ENOENT')return [];throw error;});
-  return Promise.all(entries.filter(e=>e.isDirectory()&&/^[a-f0-9-]{36}$/.test(e.name)).map(e=>read(path.join(jobPath(home,e.name),'job.json'))));
+  // A job becomes visible only when its receipt is atomically committed. A crash
+  // before that point leaves no activation authority and must not stop the host.
+  const found=await Promise.all(entries.filter(e=>e.isDirectory()&&jobId.test(e.name)).map(e=>read(path.join(jobPath(home,e.name),'job.json')).catch(missing)));
+  return found.filter(Boolean);
 }
 async function requireSupervisor(directory) {
   const h=await read(path.join(directory,'supervisor.json'));

package/src/updates/runtime.mjs

@@ -43,6 +43,14 @@ export async function packageManager(root,run=execute) {
   throw Error(`Upgrade prerequisite unavailable: ${required}. ${failures.join('; ')}. Check the host supervisor service PATH (shell aliases do not count). Reuse its installed pnpm or Corepack; expose the launcher directory to that service and restart it after the current turn. If neither exists, provision the pinned manager first. Do not substitute npm install or reinstall the agent. After repair, prepare/apply a new job when status is failed; recover is only for recovery-required.`);
 }
 export const relayArgs = config => ['compose','--env-file',path.join(config.deploymentDir,'docker.env')];
+const healthCodes = new Set(['RELAY_UNREADABLE','RELAY_NOT_POLLING','RELAY_STALE','HOST_UNREADABLE','HOST_STALE']);
+async function healthEvidence(config,run) {
+  const id=(await run('docker',[...relayArgs(config),'ps','-q','relay'])).trim();
+  if(!/^[a-f0-9]{12,64}$/i.test(id))return '';
+  const raw=await run('docker',['inspect','--format','{{json .State.Health}}',id]);
+  const health=JSON.parse(raw),entry=health?.Log?.at(-1),match=typeof entry?.Output==='string'&&entry.Output.match(/^EZ_HEALTH_([A-Z_]+)\s*$/);
+  return match&&healthCodes.has(match[1])?` (health=${match[1].toLowerCase().replaceAll('_','-')})`:'';
+}
 function envValue(text,key,value) {
   if(/[\r\n\0']/.test(value))throw Error('Unsafe deployment value');
   const line=`${key}='${value}'`;
@@ -118,7 +126,11 @@ export async function perform(home,job,hooks) {
       job.runtimeVerified=running;
     }
     job.status='completed';job.endedAt=new Date().toISOString();await save();return job;
-  }catch(error){job.error=error.message;await save();return recover(home,job,hooks);}
+  }catch(error){
+    let message=error.message;
+    if(job.target==='main'&&job.rollback&&/is unhealthy/.test(message))message+=await healthEvidence(config,run).catch(()=> '');
+    job.error=message;await save();return recover(home,job,hooks);
+  }
 }
 export async function recover(home,job,hooks) {
   const run=hooks.execute||execute,{config}=await state(home);

package/templates/agent-guidance.md

@@ -12,6 +12,19 @@ delegation, model, and effort from the task—not a fixed routing rule. Keep one
 writer per workspace; the primary agent owns integration, verification, and
 external actions.
 
+## AI selection
+
+An explicit owner request to change this conversation's AI or reasoning effort
+is a supported Ez control, not a request to edit the host Codex configuration,
+inspect a native session record, or restart the runtime. Run
+`ezenciel-agents-ai list`, then select only a returned choice with
+`ezenciel-agents-ai select --cli <cli> --model <model> --effort <effort>`.
+This changes subsequent owner messages only; a running or queued job retains
+its captured choice, and the installation default is unchanged. Switching CLI
+starts a fresh native conversation while preserving the workspace. Report the
+confirmed selected choice from the command output; do not infer it from a
+host-level setting or the current native session.
+
 ## Telegram replies
 
 Use the messaging CLI for the current run's source chat, normally the paired

package/test/agent-guidance.test.ts

@@ -45,6 +45,19 @@ test('shared guidance teaches source-chat delivery and real Telegram line breaks
   assert.ok(shared.includes('ezenciel-agents-message --text-file ./work/reply.md'))
 })
 
+test('shared guidance makes owner AI selection a relay control, not host configuration', async () => {
+  const shared = await readFile(sharedGuidancePath, 'utf8')
+  for (const prompt of [
+    executorJobPrompt('tg_owner', ['change to Terra medium']),
+    desktopJobPrompt('tg_owner_gui', ['change to Terra medium'], undefined, '/tmp/bin', '/tmp/control'),
+  ]) {
+    assert.ok(prompt.includes('`ezenciel-agents-ai list`'))
+    assert.ok(prompt.includes('`ezenciel-agents-ai select --cli <cli> --model <model> --effort <effort>`'))
+    assert.ok(prompt.includes('not a request to edit the host Codex configuration'))
+    assert.match(prompt, /a running or queued job retains\s+its captured choice/)
+  }
+})
+
 test('package guidance resolution ignores a workspace shadow file', async () => {
   const root = path.join(tmpdir(), `ez-guidance-${randomUUID()}`)
   await mkdir(root, { recursive: true })

package/test/ai.test.ts

@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { ControlStore } from '../src/control-state.js'
 import { initialPreset, chatPreset, readModels, isPreset } from '../src/ai.js'
+import { createAiMenu } from '../src/menu.js'
 import { EXECUTOR_REGISTRY, nativeSessionId } from '../src/executor.js'
 import { InboxStore } from '../src/inbox.js'
 import type { Update } from 'grammy/types'
@@ -92,6 +93,45 @@ test('model catalog projects native metadata only, excluding hidden entries and
   } finally { await rm(home, { recursive: true, force: true }) }
 })
 
+test('Choose AI opens the available installed-model catalog without an Add AI step', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'ez-ai-menu-'))
+  try {
+    const menu = createAiMenu(new ControlStore(dir, 1000), 'grok', async () => [{
+      cli: 'codex', model: 'fixture-model', name: 'Fixture', efforts: ['medium'],
+    }])
+    let reply = ''
+    let keyboard: { inline_keyboard?: Array<Array<{ text: string }>> } | undefined
+    await menu.list({ reply: async (text: string, options?: { reply_markup?: unknown }) => {
+      reply = text
+      keyboard = options?.reply_markup as typeof keyboard
+      return {} as never
+    } } as never)
+    assert.match(reply, /Available models are populated automatically/)
+    assert.deepEqual(keyboard?.inline_keyboard?.flat().map((button) => button.text), ['codex · Fixture'])
+  } finally { await rm(dir, { recursive: true, force: true }) }
+})
+
+test('Choose AI does not expose saved model choices without a catalog to validate them', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'ez-ai-menu-empty-'))
+  try {
+    const store = new ControlStore(dir, 1000)
+    await store.aiState(initialPreset('grok'))
+    await store.savePreset({ id: 'saved', name: 'Saved model', cli: 'codex', model: 'fixture-model', effort: 'medium' })
+    await store.savePreset({ id: 'saved-default', name: 'Saved client default', cli: 'claude' })
+    const menu = createAiMenu(store, 'grok', async () => [])
+    let reply = ''
+    let keyboard: { inline_keyboard?: Array<Array<{ text: string }>> } | undefined
+    await menu.list({ reply: async (text: string, options?: { reply_markup?: unknown }) => {
+      reply = text
+      keyboard = options?.reply_markup as typeof keyboard
+      return {} as never
+    } } as never)
+    assert.match(reply, /current client setup only/)
+    assert.ok(!keyboard?.inline_keyboard?.flat().some((button) => button.text.includes('Saved model')))
+    assert.ok(!keyboard?.inline_keyboard?.flat().some((button) => button.text.includes('Saved client default')))
+  } finally { await rm(dir, { recursive: true, force: true }) }
+})
+
 test('model catalog can read an agent-bound Codex home', async () => {
   const home = await mkdtemp(join(tmpdir(), 'ez-catalog-home-'))
   const codexHome = await mkdtemp(join(tmpdir(), 'ez-catalog-codex-'))

package/test/failure.test.ts

@@ -17,7 +17,10 @@ import { TelegramSource } from '../src/telegram-source.js'
 import { packageVersion } from '../src/version.js'
 import type { Update } from 'grammy/types'
 const exec=promisify(execFile),bin=fileURLToPath(new URL('../bin/ezenciel-agents-schedule.mjs',import.meta.url))
-const until=async(check:()=>Promise<boolean>)=>{for(let n=0;n<200;n++){if(await check())return;await new Promise(r=>setTimeout(r,20))}throw new Error('Timed out')}
+// This integration test starts subprocesses, persists their receipts, and invokes
+// the schedule CLI. Give a busy CI worker time to settle without changing the
+// production recovery deadline.
+const until=async(check:()=>Promise<boolean>,timeoutMs=15_000)=>{const deadline=Date.now()+timeoutMs;while(!(await check())){if(Date.now()>=deadline)throw new Error(`Timed out after ${timeoutMs}ms`);await new Promise(r=>setTimeout(r,20))}}
 
 test('failure evidence is bounded and redacts configured credentials, headers, tokens, URLs and keys',()=>{
  const token='123456789:abcdefghijklmnopqrstuvwxyz123456789'
@@ -137,6 +140,29 @@ test('relay shutdown waits for executor cleanup and final run state', async () =
  } finally {release();await relay.stop();await rm(dir,{recursive:true,force:true})}
 })
 
+test('a fresh relay initializes its bot identity before polling', async () => {
+ const dir=await mkdtemp(join(tmpdir(),'ez-cold-start-'))
+ const relay=createRelay({workspace:dir,controlDir:dir,pairingTtlMs:1000,executorTimeoutMs:0,executorCli:'grok',telegramBotToken:'fixture'},async()=>{throw new Error('No executor expected')})
+ const methods:string[]=[]
+ relay.bot.api.config.use(async(_prev,method,_payload,signal)=>{
+  methods.push(method)
+  if(method==='getMe') return {ok:true,result:{id:999,is_bot:true,first_name:'Fixture',username:'fixture_bot'}} as any
+  if(method==='getUpdates') {
+   if(signal && !signal.aborted) await new Promise<void>(resolve=>signal.addEventListener('abort',()=>resolve(),{once:true}))
+   return {ok:true,result:[]} as any
+  }
+  return {ok:true,result:true} as any
+ })
+ const started=relay.start()
+ try {
+  await until(async()=>methods.includes('getUpdates'))
+  assert.equal(relay.bot.isRunning(),true)
+  assert.equal(methods.filter(method=>method==='getMe').length,1)
+  assert.ok(methods.indexOf('getMe')<methods.indexOf('getUpdates'))
+ } finally {await relay.stop();await started;await rm(dir,{recursive:true,force:true})}
+ assert.equal(relay.bot.isRunning(),false)
+})
+
 for (const cleanupFails of [false,true]) test(`polling conflict preserves work until an explicit shutdown (cleanup fails: ${cleanupFails})`, async t => {
  const dir=await mkdtemp(join(tmpdir(),'ez-polling-conflict-')),control=new ControlStore(dir,1000),runs=new RunStore(dir)
  let release!:()=>void,entered!:()=>void,releaseDelivery!:()=>void,sending!:()=>void,child:ReturnType<typeof spawn>|undefined,polls=0

package/test/intake-relay.test.ts

@@ -201,7 +201,7 @@ test('owner group discovery routes only to the private chat and rechecks identit
   } finally { await f.close() }
 })
 
-test('four-item menu is owner-only; saved AI buttons work and forged/stale buttons cannot change settings', async () => {
+test('four-item menu is owner-only; available AI choices work and forged/stale buttons cannot change settings', async () => {
   const f = await fixture()
   const callback = (id: number, data: string, user = 101): Update => ({
     update_id: id,
@@ -220,10 +220,18 @@ test('four-item menu is owner-only; saved AI buttons work and forged/stale butto
     await f.relay.bot.handleUpdate(callback(4, 'ai:forged'))
     assert.equal(await store.getActiveSession(), null)
     await f.relay.bot.handleUpdate(callback(5, pick))
+    if (!(await store.getActiveSession())) {
+      let useNow = f.keyboards.at(-1)!.flat().find((button) => button.text === 'Use now')?.callback_data
+      if (!useNow) {
+        await f.relay.bot.handleUpdate(callback(6, f.keyboards.at(-1)!.flat()[0].callback_data))
+        useNow = f.keyboards.at(-1)!.flat().find((button) => button.text === 'Use now')!.callback_data
+      }
+      await f.relay.bot.handleUpdate(callback(7, useNow))
+    }
     assert.ok(await store.getActiveSession())
-    await f.relay.bot.handleUpdate(callback(6, pick))
+    await f.relay.bot.handleUpdate(callback(8, pick))
     assert.match(f.replies.at(-1)!, /Menu expired/)
-    await f.relay.bot.handleUpdate(message(7, '/settings'))
+    await f.relay.bot.handleUpdate(message(9, '/settings'))
     assert.match(f.replies.at(-1)!, /Default for new conversations/)
     await f.relay.bot.handleUpdate(message(8, '/status'))
     assert.ok(f.keyboards.at(-1)!.flat().some((button) => button.text === 'Scheduled tasks'))

package/test/trusted-beta.test.mjs

@@ -222,3 +222,63 @@ test('workflow runs and attempt jobs are paginated before selecting required evi
     [jobsPath.replace('&page=1', '&page=2')]: { jobs: [job] },
   }));
 });
+
+test('GitHub errors identify the failed read without exposing credentials or signed URLs', async () => {
+  const missing = githubClient('private-token', async () => new Response('private-body', { status: 404 }));
+  await assert.rejects(missing('/repos/jdorado/ez-agents/git/ref/tags/v1.2.3-beta.1'), /GitHub GET .*\/git\/ref\/tags\/v1\.2\.3-beta\.1: release tag is missing or inaccessible/);
+  await assert.rejects(missing('/repos/jdorado/ez-agents/releases/123'), error => {
+    assert.match(error.message, /HTTP 404.*GitHub GET .*\/releases\/123/);
+    assert.doesNotMatch(error.message, /private-token|private-body|release tag/);
+    return true;
+  });
+  let request = 0;
+  const download = githubClient('private-token', async () => request++ === 0
+    ? new Response('', { status: 302, headers: { location: 'https://release-assets.githubusercontent.com/file?signature=private-signature' } })
+    : new Response('private-body', { status: 403 }));
+  await assert.rejects(download('/repos/jdorado/ez-agents/releases/assets/456', true), error => {
+    assert.match(error.message, /HTTP 403.*\/releases\/assets\/456 asset download/);
+    assert.doesNotMatch(error.message, /private-token|private-body|private-signature|signature=/);
+    return true;
+  });
+});
+
+test('staging recovery requires a real source tag and canonical asset before validating exact bytes', async t => {
+  const { validate } = await import('../scripts/trusted-beta.mjs');
+  const { readFile } = await import('node:fs/promises');
+  const dir = await mkdtemp(join(tmpdir(), 'beta-staging-recovery-'));
+  t.after(() => rm(dir, { recursive: true, force: true }));
+  await mkdir(join(dir, 'package'));
+  await writeFile(join(dir, 'package/package.json'), JSON.stringify(manifest));
+  execFileSync('tar', ['-czf', join(dir, 'candidate.tgz'), '-C', dir, 'package/package.json']);
+  const bytes = await readFile(join(dir, 'candidate.tgz'));
+  const candidateEnv = { ...env, RELEASE_SHA256: sha256(bytes) };
+  let tagExists = false, assetName = 'jc_stack-ez-agents-1.2.3-beta.1.tgz';
+  const reads = [];
+  const source = sourceApi();
+  const api = async path => {
+    reads.push(path);
+    if (path.includes('/git/ref/tags/') && !tagExists) {
+      return githubClient('test', async () => new Response('', { status: 404 }))(path);
+    }
+    if (path.endsWith('/releases/123')) return { id: 123, draft: true, prerelease: true, tag_name: `v${expected.version}`, assets: [
+      { id: 456, name: assetName, state: 'uploaded' }, { id: 457, name: 'release-receipt.json', state: 'uploaded' },
+    ] };
+    if (path.endsWith('/releases/assets/456')) return bytes;
+    if (path.endsWith('/releases/assets/457')) return Buffer.from(JSON.stringify({ ...receipt, sha256: candidateEnv.RELEASE_SHA256 }));
+    if (path.endsWith('/pulls/41')) return { merged: true, base: { repo: { full_name: expected.repository }, ref: 'main' }, merge_commit_sha: expected.sourceSha };
+    return source(path);
+  };
+  const output = join(dir, 'validated');
+  await assert.rejects(validate(output, candidateEnv, api), /release tag is missing/);
+  assert.ok(!reads.some(path => path.includes('/releases/')));
+  tagExists = true;
+  await assert.rejects(validate(output, candidateEnv, api), /Missing or ambiguous asset: candidate.tgz/);
+  assert.ok(!reads.some(path => path.includes('/releases/assets/')));
+  assetName = 'candidate.tgz';
+  await assert.rejects(validate(output, { ...candidateEnv, RELEASE_SHA256: '0'.repeat(64) }, api), /SHA256 mismatch/);
+  const result = await validate(output, candidateEnv, api);
+  assert.equal(result.sha256, sha256(bytes));
+  assert.deepEqual(await readFile(join(output, 'candidate.tgz')), bytes);
+  // Retry cannot silently replace an existing validated bundle.
+  await assert.rejects(validate(output, candidateEnv, api), /EEXIST/);
+});

package/test/updates.test.mjs

@@ -7,7 +7,7 @@ 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 } from '../src/updates/control.mjs';
+import { prepare, submit, command, read, jobPath, eligibility, jobs } from '../src/updates/control.mjs';
 import { perform, environment, packageManager } from '../src/updates/runtime.mjs';
 import { atomic, snapshot, compose } from '../src/plugins/manager.mjs';
 import { bindUpdates } from '../src/updates/binding.mjs';
@@ -86,6 +86,16 @@ test('status distinguishes installed, running, legacy and stale main versions wi
  const result=await exec(process.execPath,[new URL('../bin/ezenciel-agents-tools.mjs',import.meta.url).pathname,'--home',f.home,'status']);
  assert.equal(JSON.parse(result.stdout).main.installedVersion,'0.1.0');
 });
+test('relay healthcheck emits bounded predicate evidence without state contents',async t=>{
+ const root=await fs.realpath(await fs.mkdtemp(path.join(tmpdir(),'ez-healthcheck-')));t.after(()=>fs.rm(root,{recursive:true,force:true}));
+ const relay=path.join(root,'relay'),host=path.join(root,'host');await fs.mkdir(relay,{recursive:true});await fs.mkdir(path.join(host,'host-executor'),{recursive:true});
+ const check=async()=>exec(process.execPath,[new URL('../docker/healthcheck.mjs',import.meta.url).pathname],{env:{...process.env,EZ_HEALTH_RELAY_CONTROL_DIR:relay,EZ_EXECUTOR_TRANSPORT:'host',EZ_CONTROL_DIR:host}});
+ await fs.writeFile(path.join(relay,'heartbeat.json'),JSON.stringify({polling:true,at:Date.now()}));await fs.writeFile(path.join(host,'host-executor/heartbeat.json'),JSON.stringify({at:Date.now()}));await check();
+ await fs.writeFile(path.join(relay,'heartbeat.json'),JSON.stringify({polling:false,at:Date.now(),private:'must-not-appear'}));
+ await assert.rejects(check(),error=>{assert.match(error.stderr,/EZ_HEALTH_RELAY_NOT_POLLING/);assert.doesNotMatch(error.stderr,/must-not-appear/);return true;});
+ await fs.writeFile(path.join(relay,'heartbeat.json'),JSON.stringify({polling:true,at:Date.now()}));await fs.writeFile(path.join(host,'host-executor/heartbeat.json'),JSON.stringify({at:Date.now()-20000}));
+ await assert.rejects(check(),error=>{assert.match(error.stderr,/EZ_HEALTH_HOST_STALE/);return true;});
+});
 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']) {
@@ -157,6 +167,11 @@ test('failed preparation never stops runtime; failed activation rolls back code
   else assert((await fs.readFile(path.join(f.config.deploymentDir,'docker.env'),'utf8')).includes('sha256:'+'a'.repeat(64)));
  }
 });
+test('main health-gate rollback retains only the recognized sanitized predicate',async t=>{
+ const f=await fixture(t),job=await queued(f),base=runtime(f);let failed=false;
+ const r={...base,execute:async(c,a,o)=>{if(a.includes('up')&&!failed){failed=true;throw Error('container relay is unhealthy');}return a.includes('ps')?'a'.repeat(64):a[0]==='inspect'&&a[2]==='{{json .State.Health}}'?JSON.stringify({Log:[{Output:'EZ_HEALTH_HOST_STALE\n'}]}):base.execute(c,a,o);}};
+ const result=await perform(f.home,job,r);assert.equal(result.status,'rolled-back');assert.match(result.error,/health=host-stale/);assert.doesNotMatch(result.error,/private-test-token/);
+});
 test('plugin transaction preserves named volumes, backs up stopped data and rolls back failed health',async t=>{
  for(const failed of [false,true]) {
   const f=await fixture(t,'plugin'),job=await queued(f),r=runtime(f,{fail:(_c,a)=>failed&&a.includes('up')});
@@ -237,6 +252,11 @@ test('missing or broken managers fail with repair guidance before installing or
 
 for(const provider of ['pnpm','corepack']) test(`supervisor with only ${provider} drains work, replaces host PID and recovers after restart`,async t=>{
  const f=await fixture(t),fake=path.join(f.root,'fake');await fs.mkdir(fake);
+ // A process may die after creating a job directory but before atomically
+ // committing its receipt. That directory must not block transport startup.
+ await fs.mkdir(path.join(f.home,'updates','d18e847a-bb59-49c6-96f3-27fdc43ca44f'));
+ await fs.mkdir(path.join(f.home,'updates','a'.repeat(36)));
+ assert.deepEqual(await jobs(f.home),[]);
  const hostCode=`import fs from 'node:fs';import path from 'node:path';const c=JSON.parse(fs.readFileSync(process.argv[2])).agents[0];const d=path.join(c.controlDir,'host-executor');fs.mkdirSync(d,{recursive:true});const beat=()=>{fs.writeFileSync(path.join(d,'heartbeat.json'),JSON.stringify({pid:process.pid,at:Date.now()}));};beat();const timer=setInterval(()=>{try{process.kill(Number(process.env.EZ_HOST_SUPERVISOR_PID),0)}catch{process.exit(0)}beat()},100);process.on('SIGTERM',()=>{clearInterval(timer);process.exit(0)});`;
  for(const dir of [f.old,f.source]) {
   await fs.mkdir(path.join(dir,'node_modules/tsx/dist'),{recursive:true});await fs.writeFile(path.join(dir,'node_modules/tsx/dist/loader.mjs'),'');