@jc_stack/ez-agents 0.1.0-beta.38 → 0.1.0-beta.40

package/.env.example

@@ -19,6 +19,8 @@ EZ_EXECUTOR_CLI=codex
 
 # Optional: Audio transcription (STT) and voice synthesis (TTS)
 # GEMINI_API_KEY=
+# EZ_SPEECH_VOICE_EN=Kore
+# EZ_SPEECH_VOICE_ES=Kore
 # OPENAI_API_KEY=
 
 # Optional: OpenRouter API key for OpenCode CLI (Nemotron 3.5 Lightning)

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.1.0-beta.40
+
+- Apply eligible npm releases under each agent's saved automatic update policy
+  through the existing guarded updater. Queue one update at a time, preserve
+  manual policies, and wait for a newer version after a failed automatic update.
+
+## 0.1.0-beta.39
+
+- Render completed, binding-scoped application replies as WAV speech with
+  configurable English and Spanish voices, while retaining Ogg/Opus for Telegram.
+  Recheck the original application binding after synthesis and report depleted
+  speech credits without provider details.
+- Preserve live delivery sockets during upgrade backups and restart Linux host
+  services after a successful core replacement.
+
 ## 0.1.0-beta.38
 
 - Remove the retired Antigravity CLI integration and its unused engine paths.

package/docs/application-channel.md

@@ -10,6 +10,24 @@ Run admission, status and inbox receipts include the immutable `preset` captured
 for that run so an application can label delivered messages with the engine choice
 that actually produced them.
 
+## Speech playback
+
+`POST /v1/runs/<id>/speech` renders the last delivered text reply of a completed
+application run as `audio/wav` (24 kHz mono). It uses the same binding/owner
+authorization as run readback, rechecked after synthesis, and accepts no client
+text or provider credentials. Replies are limited to 8,000 characters. An
+unfinished run returns 409, missing speech configuration 503, and provider
+failure 502. Depleted Gemini credits return 503 with
+`code: speech_credits_depleted`. Audio responses have `Cache-Control: no-store`.
+
+Configure `GEMINI_API_KEY` on the relay. The existing speech renderer uses
+`gemini-3.8-flash-lite-tts`; Telegram still receives Ogg Opus. Applications should
+send `{"language":"en"}` or `{"language":"es"}` to select
+`EZ_SPEECH_VOICE_EN` or `EZ_SPEECH_VOICE_ES` (both default to Kore). Telegram
+voice notes use the English voice setting. Applications should retain the returned
+audio for local replay; each POST generates fresh audio.
+Speech is a rendering operation and does not start another agent turn.
+
 ## Shared runtime controls
 
 Register with `--share-owner` (the existing `--share-telegram` spelling is an

package/docs/host-service.md

@@ -24,7 +24,7 @@ Environment=EZ_DEPLOYMENT_DIR=/absolute/private/agents/family
 Environment=PATH=/absolute/node/bin:/absolute/package-manager/bin:/absolute/cli/bin:/usr/local/bin:/usr/bin:/bin
 EnvironmentFile=-%h/.config/ez/family-provider.env
 ExecStart=/absolute/ez-package/package/bin/ezenciel-agents-host
-Restart=on-failure
+Restart=always
 RestartSec=5
 
 [Install]

package/docs/upgrades.md

@@ -12,12 +12,13 @@ automatic channel for core and plugins without a saved policy. Existing explicit
 stable or manual policies are preserved. The owner may select either per target.
 The main target and installed plugins version independently.
 
-The agent owns release review, policy decisions and communication. The host
-supervisor owns interruption-safe replacement. There is one host service per
-agent, not a second agent or an additional updater daemon. Its replaceable child
-runs the normal CLI transport. It checks npm every six hours while running and
-records automatic-channel changes; discovery never wakes the agent or injects
-wrapper state into a session. Updates stay owner-invoked through `ez updates`.
+The owner chooses the saved update policy. The host supervisor owns
+interruption-safe replacement. There is one host service per agent, not a second
+agent or an additional updater daemon. Its replaceable child runs the normal CLI
+transport. It checks npm every six hours while running and queues one eligible
+release at a time when the policy is automatic. Discovery and replacement never
+wake the agent or inject wrapper state into a session. Manual policies retain
+owner-invoked updates through `ez updates`.
 Checks use the installed scoped npm identity; failures are
 visible in `updates check` and private `tools/updates/available.json`. Plugins marked
 `private: true` in their package metadata are reported as local-source updates
@@ -265,5 +266,7 @@ execution authority.
 
 Update discovery runs independently of active host work. A discovery failure is
 logged locally and retried at the next regular six-hour check; it does not stop
-the host or create a repair task. Inspect `ez updates check` for target diagnostics.
+the host or create a repair task. An automatically failed or rolled-back version
+is not retried until a newer version appears or the owner explicitly retries.
+Inspect `ez updates check` and `ez updates status` for target diagnostics.
 Actual update transactions retain their existing admission, drain and rollback rules.

package/package.json

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

package/src/application-channel.ts

@@ -11,6 +11,7 @@ import { MAX_INCOMING_ATTACHMENT_BYTES, stageChatAttachment } from './files.js'
 import { assertEffort } from './model-policy.js'
 import { ApprovalStore } from './approval.js'
 import { Tasks } from './tasks.js'
+import { SpeechCreditsDepletedError } from './audio.js'
 
 const hash = (value: string) => createHash('sha256').update(value).digest('hex')
 export const applicationScope = (bindingId: string, scope: string) => hash(JSON.stringify([bindingId, scope]))
@@ -74,6 +75,7 @@ export class ApplicationChannel {
     controlDir: string; workspace?: string; initial: AiPreset
     wake: () => void
     cancel: (id: string) => Promise<void>
+    speech?: (text: string, language: 'en' | 'es') => Promise<{ buffer: Buffer; mimeType: string }>
     createTelegramPairing?: (bindingId: string, owner: Owner) => Promise<{ connected: true } | { connected: false; url: string; expiresAt: string }>
     telegramAvailable?: () => boolean
     aiControls?: {
@@ -385,6 +387,31 @@ export class ApplicationChannel {
         const admitted = await this.runs.attachTelegramApplication(target.id, application)
         send(200, { id: admitted.id, scope, status: admitted.status }); return
       }
+      const speechMatch = path.match(/^\/v1\/runs\/(r_(?:app|schedule)_[a-f0-9]{64})\/speech$/)
+      if (speechMatch && request.method === 'POST') {
+        const chunks: Buffer[] = []; let size = 0
+        for await (const chunk of request) { size += chunk.length; if (size > 128) throw new Error('Invalid speech request'); chunks.push(chunk) }
+        const input = Buffer.concat(chunks).toString('utf8').trim()
+        const language = input ? (JSON.parse(input) as { language?: unknown }).language : 'en'
+        if (language !== 'en' && language !== 'es') { send(400, { error: 'Invalid speech language' }); return }
+        const snapshot = await this.snapshot(binding.bindingId, speechMatch[1])
+        if (snapshot.status !== 'completed') { send(409, { error: 'Speech requires a completed reply' }); return }
+        const text = snapshot.messages.at(-1)?.text?.trim()
+        if (!text || text.length > 8000) { send(400, { error: 'Speech requires a reply of 1–8000 characters' }); return }
+        if (!this.options.speech) { send(503, { error: 'Speech is not configured' }); return }
+        let audio: { buffer: Buffer; mimeType: string }
+        try { audio = await this.options.speech(text, language) }
+        catch (error) {
+          if (error instanceof SpeechCreditsDepletedError) { send(503, { error: 'Speech credits are depleted', code: 'speech_credits_depleted' }); return }
+          send(502, { error: 'Speech generation failed' }); return
+        }
+        // A binding can be revoked while the provider is generating audio.
+        const currentBinding = await this.bindings.authenticate(request.headers.authorization!.slice(7))
+        if (currentBinding.bindingId !== binding.bindingId) throw new Error('Application authority revoked')
+        await this.snapshot(binding.bindingId, speechMatch[1])
+        response.writeHead(200, { 'content-type': audio.mimeType, 'cache-control': 'no-store' })
+        response.end(audio.buffer); return
+      }
       const match = path.match(/^\/v1\/runs\/(r_(?:app|schedule)_[a-f0-9]{64})(\/cancel)?$/)
       if (match && ((!match[2] && request.method === 'GET') || (match[2] && request.method === 'POST'))) {
         await this.snapshot(binding.bindingId, match[1])

package/src/audio.ts

@@ -7,6 +7,10 @@ export type AudioOptions = {
   voice?: string
 }
 
+export class SpeechCreditsDepletedError extends Error {
+  constructor() { super('Gemini speech credits are depleted') }
+}
+
 export const pcmToWav = (pcm: Buffer, sampleRate = 24000, channels = 1): Buffer => {
   const header = Buffer.alloc(44)
   const byteRate = sampleRate * channels * 2
@@ -135,7 +139,7 @@ export const transcribeAudio = async (
 
 export const synthesizeSpeech = async (
   text: string,
-  options: AudioOptions = {},
+  options: AudioOptions & { format?: 'wav' | 'ogg' } = {},
 ): Promise<{ buffer: Buffer; mimeType: string }> => {
   const trimmed = text.trim()
   if (!trimmed) throw new Error('Cannot synthesize speech for empty text')
@@ -143,7 +147,7 @@ export const synthesizeSpeech = async (
   const geminiKey = (options.geminiApiKey ?? process.env.GEMINI_API_KEY)?.trim()
   if (geminiKey) {
     const url =
-      'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-preview-tts:generateContent'
+      'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash-lite-tts:generateContent'
     const voiceName = options.voice || 'Kore'
     const response = await fetch(url, {
       method: 'POST',
@@ -153,14 +157,15 @@ export const synthesizeSpeech = async (
         contents: [{ parts: [{ text: trimmed }] }],
         generationConfig: {
           responseModalities: ['AUDIO'],
-          speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName } } },
+          responseFormat: { audio: { mimeType: 'AUDIO_L16', sampleRate: 24000 } },
+          speechConfig: { voiceConfig: { voice: voiceName } },
         },
       }),
     })
 
     if (!response.ok) {
-      const err = await response.text().catch(() => '')
-      throw new Error(`Gemini speech synthesis error ${response.status}: ${err}`)
+      if (response.status === 402) throw new SpeechCreditsDepletedError()
+      throw new Error(`Gemini speech synthesis error ${response.status}`)
     }
 
     const payload = (await response.json()) as any
@@ -173,6 +178,9 @@ export const synthesizeSpeech = async (
       throw new Error(`Gemini returned no audio data (${candidate?.finishReason || 'no candidate'})`)
 
     const rawPcm = Buffer.from(inline.data, 'base64')
+    if (!/^audio\/l16(?:;|$)/i.test(inline.mimeType) || !rawPcm.length || rawPcm.length % 2)
+      throw new Error('Gemini returned an unsupported speech format')
+    if (options.format === 'wav') return { buffer: pcmToWav(rawPcm), mimeType: 'audio/wav' }
     const encoded = await encodeOggOpus(rawPcm, 24000, 1)
     return {
       buffer: encoded,

package/src/config.ts

@@ -25,6 +25,8 @@ export type Config = ControlConfig & {
   applicationPort?: number
   applicationHost?: string
   geminiApiKey?: string
+  speechVoiceEn?: string
+  speechVoiceEs?: string
   openaiApiKey?: string
 }
 
@@ -84,6 +86,8 @@ export const loadConfig = (env: NodeJS.ProcessEnv = process.env): Config => {
     channelBackendUrl: env.EZ_CHANNEL_BACKEND_URL?.trim(),
     channelBackendToken: env.EZ_CHANNEL_BACKEND_TOKEN?.trim(),
     geminiApiKey: env.GEMINI_API_KEY?.trim(),
+    speechVoiceEn: env.EZ_SPEECH_VOICE_EN?.trim(),
+    speechVoiceEs: env.EZ_SPEECH_VOICE_ES?.trim(),
     openaiApiKey: env.OPENAI_API_KEY?.trim(),
   }
 }

package/src/index.ts

@@ -103,6 +103,11 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
   const applicationChannel = new ApplicationChannel({
     controlDir: config.controlDir, workspace: config.workspace, initial: aiMenu.initial,
     aiControls: aiMenu,
+    speech: config.geminiApiKey ? (text, language) => synthesizeSpeech(text, {
+      geminiApiKey: config.geminiApiKey,
+      voice: language === 'es' ? config.speechVoiceEs : config.speechVoiceEn,
+      format: 'wav',
+    }) : undefined,
     wake: () => { void drainSources().catch(error => console.error('Application queue unavailable', safeError(error))) },
     createTelegramPairing: async (bindingId, owner) => {
       const username = bot?.botInfo?.username
@@ -581,6 +586,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
             const { buffer } = await synthesizeSpeech(item.voiceText, {
               geminiApiKey: config.geminiApiKey,
               openaiApiKey: config.openaiApiKey,
+              voice: config.speechVoiceEn,
             })
             await paceSend()
             await authorizeChannelDelivery()

package/src/updates/runtime.mjs

@@ -31,6 +31,9 @@ export function execute(command,args,options={}) {
 export async function textAtomic(file,text) {
   const tmp=file+'.update.tmp';await fs.writeFile(tmp,text,{mode:0o600});await fs.rename(tmp,file);
 }
+export async function backupStateDirectory(source,destination) {
+  await fs.cp(source,destination,{recursive:true,filter:async entry=>!(await fs.lstat(entry)).isSocket()});
+}
 export const pluginArgs = record => ['compose','--project-name',record.project,'--file',record.compose];
 export async function packageManager(root,run=execute) {
   const {packageManager:required}=await read(path.join(root,'package.json'));
@@ -116,7 +119,7 @@ export async function perform(home,job,hooks) {
       job.rollback={env:envValue(oldEnv,'EZ_RELAY_IMAGE',oldImage),packageRoot:config.packageRoot};await save();
       await run('docker',[...relayArgs(config),'stop','relay']);await hooks.stopHost();
       const backup=path.join(dir,'backup');await fs.mkdir(backup,{mode:0o700});
-      for(const name of ['mind','control'])await fs.cp(path.join(config.deploymentDir,name),path.join(backup,name),{recursive:true});
+      for(const name of ['mind','control'])await backupStateDirectory(path.join(config.deploymentDir,name),path.join(backup,name));
       for(const name of ['docker.env','host-executor.json','agent.json','purpose.md','relay.env'])await fs.copyFile(path.join(config.deploymentDir,name),path.join(backup,name));
       let env=oldEnv.split(job.previousRoot+path.sep).join(root+path.sep);env=envValue(env,'EZ_RELAY_IMAGE',image);
       await textAtomic(envFile,env);

package/src/updates/supervisor.mjs

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { spawn } from 'node:child_process';
 import { atomic, locked } from '../plugins/manager.mjs';
 import { callDeliverySocket } from '../delivery-socket-client.mjs';
-import { state, read, jobs, jobPath, check, missing, cleanupStaleBackups } from './control.mjs';
+import { state, read, jobs, jobPath, check, prepare, submit, missing, cleanupStaleBackups } from './control.mjs';
 import { perform, environment } from './runtime.mjs';
 
 const reservedProviderKeys=new Set(['HOME','LANG','LC_ALL','LOGNAME','PATH','SHELL','TERM','TMPDIR','USER','CODEX_HOME','NODE_OPTIONS']);
@@ -28,6 +28,22 @@ export async function idle(control) {
   const status=await callDeliverySocket(path.join(control,'delivery.sock'),{op:'status'},2000).catch(()=>null);
   return !status||status.running===0;
 }
+export async function queueAutomatic(home,available) {
+  const existing=await jobs(home);
+  if(existing.some(job=>['queued','applying','recovery-required'].includes(job.status)))return null;
+  for(const candidate of available) {
+    if(!candidate.newer||!candidate.policy?.automatic||!candidate.available)continue;
+    // A failed release needs a newer version or an explicit owner retry.
+    if(existing.some(job=>job.target===candidate.target&&job.version===candidate.available&&['failed','rolled-back'].includes(job.status)))continue;
+    try {
+      const job=await prepare(home,candidate.target,{release:candidate.available});
+      return await submit(home,job.id,true);
+    }catch {
+      console.error(`Automatic update of ${candidate.target} failed; inspect ez updates check/status.`);
+    }
+  }
+  return null;
+}
 export async function supervise(deployment,signal,{discover=check}={}) {
   const host=await read(path.join(deployment,'host-executor.json'));
   if(host.agents.length!==1||!host.agents[0].toolsHome)throw Error('Initialize a single deployment plugin registry before starting the supervisor');
@@ -96,12 +112,16 @@ export async function supervise(deployment,signal,{discover=check}={}) {
           const latest=await read(path.join(jobPath(home,pending.id),'job.json'));
           if(latest.status==='queued'){latest.status='failed';latest.error=error.message;await atomic(path.join(jobPath(home,pending.id),'job.json'),latest);}else throw error;
         } finally {await fs.rm(pause,{force:true});}
-        if(result?.status==='completed'&&pending.target==='main')return;
+        if(result?.status==='completed') {
+          if(pending.target==='main')return;
+          nextCheck=0;
+        }
       }
       if(Date.now()>=nextCheck) {
         nextCheck=Date.now()+6*60*60*1000;
         try {
           const results=await discover(home);await atomic(path.join(directory,'available.json'),results);
+          await queueAutomatic(home,results);
         } catch {
           // Discovery is optional; its failure must not terminate the host.
           // Do not expose registry response bodies or credentials in logs.

package/test/application-channel.test.ts

@@ -100,6 +100,58 @@ test('HTTP auth, idempotency, origin/context isolation, revocation and persisted
   assert.equal((await request('/v1/runs',secondToken,input)).status,401)
 })
 
+test('speech renders only a completed bound reply and rechecks authority after generation', async t => {
+  const root = await mkdtemp(join(tmpdir(), 'ez-app-speech-'))
+  const owned = await owner(root), runs = new RunStore(root)
+  const firstToken = token(), secondToken = token()
+  const spoken: string[] = []
+  let revoke = false, reassign = false
+  const channel = new ApplicationChannel({
+    controlDir: root, initial: initialPreset('codex'), wake: () => {}, cancel: async () => {},
+    speech: async text => {
+      spoken.push(text)
+      if (revoke) await channel.bindings.register('first', null, owned)
+      if (reassign) {
+        await channel.bindings.register('first', token(), owned, false, true)
+        await channel.bindings.register('second', firstToken, owned, false, true)
+      }
+      return { buffer: Buffer.from('audio-fixture'), mimeType: 'audio/wav' }
+    },
+  })
+  t.after(async () => { await channel.stop(); await rm(root, { recursive: true, force: true }) })
+  const first = (await channel.bindings.register('first', firstToken, owned))!
+  await channel.bindings.register('second', secondToken, owned)
+  const run = await channel.submit(first.bindingId, { requestId: 'speech', scope: 'exercise', text: 'Explain this' })
+  const address = await channel.listen(0) as { port: number }
+  const request = (bearer: string) => fetch(`http://127.0.0.1:${address.port}/v1/runs/${run.id}/speech`, {
+    method: 'POST', headers: { Authorization: `Bearer ${bearer}` },
+  })
+  assert.equal((await request(secondToken)).status, 404)
+  assert.equal((await request(firstToken)).status, 409)
+  assert.deepEqual(spoken, [])
+  for (const text of ['Progress', 'Keep the movement controlled.']) {
+    const item = await runs.enqueueMessage(run.id, text)
+    await runs.claimOutbox(item.id)
+    await channel.deliver(run, item)
+  }
+  await runs.patch(run.id, { status: 'completed' })
+  const audio = await request(firstToken)
+  assert.equal(audio.status, 200)
+  assert.equal(audio.headers.get('content-type'), 'audio/wav')
+  assert.equal(audio.headers.get('cache-control'), 'no-store')
+  assert.equal(await audio.text(), 'audio-fixture')
+  assert.deepEqual(spoken, ['Keep the movement controlled.'])
+  reassign = true
+  const beforeReassign = spoken.length
+  assert.notEqual((await request(firstToken)).status, 200)
+  assert.equal(spoken.length, beforeReassign + 1)
+  reassign = false
+  await channel.bindings.register('second', secondToken, owned, false, true)
+  await channel.bindings.register('first', firstToken, owned, false, true)
+  revoke = true
+  assert.notEqual((await request(firstToken)).status, 200)
+})
+
 test('owner replacement invalidates binding and client secrets never enter native environment',async t=>{
   const root=await mkdtemp(join(tmpdir(),'ez-app-owner-'))
   t.after(()=>rm(root,{recursive:true,force:true}))

package/test/audio.test.ts

@@ -1,6 +1,11 @@
 import test from 'node:test'
 import assert from 'node:assert/strict'
-import { pcmToWav, encodeOggOpus, transcribeAudio, synthesizeSpeech } from '../src/audio.js'
+import { pcmToWav, encodeOggOpus, transcribeAudio, synthesizeSpeech, SpeechCreditsDepletedError } from '../src/audio.js'
+
+test('speech reports depleted credits without exposing provider details', async (t) => {
+  t.mock.method(globalThis, 'fetch', async () => new Response('', { status: 402 }))
+  await assert.rejects(synthesizeSpeech('Fixture', { geminiApiKey: 'fixture-key' }), SpeechCreditsDepletedError)
+})
 
 test('speech provider failure stays a failure, never a text or WAV success', async (t) => {
   t.mock.method(
@@ -13,9 +18,15 @@ test('speech provider failure stays a failure, never a text or WAV success', asy
 })
 
 test('speech finds audio beyond the first response part and keeps credentials out of URLs', async (t) => {
+  let calls = 0
   t.mock.method(globalThis, 'fetch', async (url: string, options: RequestInit) => {
+    calls += 1
+    assert.match(url, /gemini-3\.8-flash-lite-tts:generateContent$/)
     assert.equal(url.includes('fixture-key'), false)
     assert.equal(new Headers(options.headers).get('x-goog-api-key'), 'fixture-key')
+    const config = JSON.parse(String(options.body)).generationConfig
+    assert.deepEqual(config.responseFormat, { audio: { mimeType: 'AUDIO_L16', sampleRate: 24000 } })
+    assert.deepEqual(config.speechConfig.voiceConfig, { voice: calls === 3 ? 'voice_r3yhwvxvihxg' : 'Kore' })
     return new Response(
       JSON.stringify({
         candidates: [
@@ -39,6 +50,11 @@ test('speech finds audio beyond the first response part and keeps credentials ou
   const speech = await synthesizeSpeech('Fixture', { geminiApiKey: 'fixture-key' })
   assert.equal(speech.mimeType, 'audio/ogg')
   assert.equal(speech.buffer.subarray(0, 4).toString(), 'OggS')
+  const wav = await synthesizeSpeech('Fixture', { geminiApiKey: 'fixture-key', format: 'wav' })
+  assert.equal(wav.mimeType, 'audio/wav')
+  assert.equal(wav.buffer.subarray(0, 4).toString(), 'RIFF')
+  assert.equal(wav.buffer.length, 24044)
+  await synthesizeSpeech('Fixture', { geminiApiKey: 'fixture-key', voice: 'voice_r3yhwvxvihxg', format: 'wav' })
 })
 
 test('pcmToWav generates a valid 44-byte WAV header', () => {

package/test/updates.test.mjs

@@ -5,16 +5,30 @@ import path from 'node:path';
 import { tmpdir } from 'node:os';
 import { gzipSync } from 'node:zlib';
 import { spawn, execFile } from 'node:child_process';
+import { createServer } from 'node:net';
 import { promisify } from 'node:util';
 import { extract, digest, version, newer, compatible } from '../src/updates/artifact.mjs';
 import { prepare, submit, command, read, jobPath, eligibility, jobs, cleanupStaleBackups, reviewedPluginDeploymentMigration } from '../src/updates/control.mjs';
-import { perform, environment, packageManager } from '../src/updates/runtime.mjs';
+import { perform, environment, packageManager, backupStateDirectory } from '../src/updates/runtime.mjs';
 import { atomic, snapshot, compose, prepareCommand } from '../src/plugins/manager.mjs';
 import { bindUpdates } from '../src/updates/binding.mjs';
 import { status as runtimeStatus } from '../src/updates/status.mjs';
-import { providerEnvironment } from '../src/updates/supervisor.mjs';
+import { providerEnvironment, queueAutomatic } from '../src/updates/supervisor.mjs';
 const exec=promisify(execFile);
 
+test('main upgrade backup omits a live plugin socket and keeps private files',async t=>{
+ const root=await fs.mkdtemp('/tmp/ez-upgrade-socket-');
+ t.after(()=>fs.rm(root,{recursive:true,force:true}));
+ const source=path.join(root,'control'),destination=path.join(root,'backup');
+ await fs.mkdir(source);await fs.writeFile(path.join(source,'state.json'),'private state');
+ const socket=path.join(source,'plugin-broker.sock'),server=createServer();
+ await new Promise((resolve,reject)=>server.once('error',reject).listen(socket,resolve));
+ t.after(()=>new Promise(resolve=>server.close(resolve)));
+ await backupStateDirectory(source,destination);
+ assert.equal(await fs.readFile(path.join(destination,'state.json'),'utf8'),'private state');
+ assert.deepEqual(await fs.readdir(destination),['state.json']);
+});
+
 test('supervisor forwards only provider keys declared by the agent installation',()=>{
  const host={agents:[{codexProviders:[{envKey:'OPENROUTER_API_KEY'}]}]};
  assert.deepEqual(providerEnvironment(host,{OPENROUTER_API_KEY:'provider-secret',TELEGRAM_BOT_TOKEN:'relay-secret'}),{OPENROUTER_API_KEY:'provider-secret'});
@@ -428,6 +442,29 @@ test('npm candidates verify exact version and integrity; automatic policy is enf
  pkg.version='0.1.2';await assert.rejects(prepare(f.home,'main',{release:'0.1.1'}),/version mismatch/);
 });
 
+test('supervisor queues an eligible release once and preserves manual and failed-version gates',async t=>{
+ const f=await fixture(t),data=await fs.readFile(await f.pack());
+ const {createHash}=await import('node:crypto');
+ const pkg={name:'@ez-test/example',version:'0.1.1',dist:{tarball:'https://registry.npmjs.org/@ez-test/example/-/example-0.1.1.tgz',integrity:'sha512-'+createHash('sha512').update(data).digest('base64')}};
+ const original=globalThis.fetch;
+ globalThis.fetch=async url=>new Response(String(url).endsWith('.tgz')?data:JSON.stringify(String(url).endsWith('/0.1.1')?pkg:{name:pkg.name,'dist-tags':{latest:pkg.version},versions:{[pkg.version]:pkg}}));
+ t.after(()=>globalThis.fetch=original);
+ await atomic(path.join(f.home,'updates/supervisor.json'),{at:Date.now()});
+ await command(f.home,['policy','main','manual']);
+ assert.equal(await queueAutomatic(f.home,await command(f.home,['check'])),null);
+ assert.deepEqual(await jobs(f.home),[]);
+ await command(f.home,['policy','main','beta']);
+ const queued=await queueAutomatic(f.home,await command(f.home,['check']));
+ assert.equal(queued.status,'queued');assert.equal(queued.automatic,true);
+ assert.equal(queued.origin.type,'npm');assert.equal(queued.sha256,digest(data));
+ assert.equal(await queueAutomatic(f.home,await command(f.home,['check'])),null);
+ assert.equal((await jobs(f.home)).length,1);
+ queued.status='failed';await atomic(path.join(jobPath(f.home,queued.id),'job.json'),queued);
+ assert.equal(await queueAutomatic(f.home,await command(f.home,['check'])),null);
+ assert.equal((await jobs(f.home)).length,1);
+ await assert.rejects(fs.readFile(path.join(f.agent.controlDir,'update-attention.json')),error=>error.code==='ENOENT');
+});
+
 test('update discovery follows latest while preserving legacy beta and stable-only policies',async t=>{
  const {registryCandidate}=await import('../src/updates/artifact.mjs');
  const name='@ez-test/example',pkg=v=>({name,version:v});