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

package/src/host-executor-client.ts

@@ -1,17 +1,29 @@
 // File transport across the Docker/host boundary. The host chooses the CLI,
 // workspace and environment; a request cannot choose a command or credentials.
-import { mkdir, readFile, writeFile, rename, rm } from 'node:fs/promises'
+import { mkdir, readFile, writeFile, rename, rm, stat } from 'node:fs/promises'
 import path from 'node:path'
 import { isHostRunId } from './host-executor-protocol.js'
-const [control, id] = process.argv.slice(2)
-if (!control || !isHostRunId(id || '')) throw new Error('Invalid executor binding')
+const [control, id, mode] = process.argv.slice(2)
+if (!control || !isHostRunId(id || '') || (mode !== undefined && mode !== '--attach')) throw new Error('Invalid executor binding')
 const directory = path.join(control, 'host-executor')
 await mkdir(directory, {recursive:true, mode:0o700})
-let input = ''
-for await (const chunk of process.stdin) input += chunk
 const base = path.join(directory, id)
-await writeFile(base+'.tmp', input, {mode:0o600, flag:'wx'})
-await rename(base+'.tmp', base+'.request.json')
+if (mode === '--attach') {
+  // A previous relay submitted this run: watch it, never resubmit. Without a
+  // request, claim or event record its outcome is unknown.
+  // Check in lifecycle order: claim renames the request, and the host writes
+  // the exit event before removing the claim, so a live run is always seen.
+  const exists = (suffix: string) => stat(base+suffix).then(() => true, error => { if (error.code === 'ENOENT') return false; throw error })
+  if (!await exists('.request.json') && !await exists('.running.json') && !await exists('.events')) {
+    console.error('Handed-off host run has no request, claim or result; its outcome is unknown')
+    process.exit(1)
+  }
+} else {
+  let input = ''
+  for await (const chunk of process.stdin) input += chunk
+  await writeFile(base+'.tmp', input, {mode:0o600, flag:'wx'})
+  await rename(base+'.tmp', base+'.request.json')
+}
 let interrupted = false
 for (const signal of ['SIGTERM','SIGINT'] as const) process.once(signal, () => {
   if (interrupted) return

package/src/index.ts

@@ -9,9 +9,9 @@ import { packageVersion } from './version.js'
 import {authorizeDeliveryContext} from './delivery-context.mjs'
 import { dispatchChannel } from './channel-backend.js'
 import { randomUUID } from 'node:crypto'
-import { stat } from 'node:fs/promises'
+import { mkdir, stat, writeFile } from 'node:fs/promises'
 import { Scheduler } from './scheduler.js'
-import { Scripts } from './scripts.js'
+import { Scripts, DEFAULT_SCRIPT_TIMEOUT_SECONDS } from './scripts.js'
 import { redactFailure } from './failure.js'
 import { ownedScheduledTasks, scheduledTaskDetailText, scheduledTasksText } from './scheduled-tasks.js'
 import { EventSources, eventRunId, batchReady, type SourceEvent } from './event-sources.js'
@@ -25,12 +25,12 @@ import { isOwner, ownsRun } from './identity.js'
 import type { Update } from 'grammy/types'
 import { InboxStore, type IncomingItem } from './inbox.js'
 import { loadConfig, type Config } from './config.js'
-import { ControlStore, telegramOwner, ownerId, ownerEpoch } from './control-state.js'
+import { ControlStore, telegramOwner, ownerId, ownerEpoch, type SessionState } from './control-state.js'
 import { ApprovalStore } from './approval.js'
-import { CliUnavailableError, startExecutorJob, terminateJob, opencodeDataHome, claudeConfigHome } from './executor.js'
-import { advances, nextSetup, quotaScope, setupCandidates, startupObserver, unavailableSummary, SetupsUnavailableError, type SetupAttempt } from './setup-fallback.js'
+import { CliUnavailableError, startExecutorJob, attachHostJob, terminateJob, opencodeDataHome, claudeConfigHome } from './executor.js'
+import { attemptFailure, continuationLine, nextSetup, quotaScope, setupCandidates, startupObserver, unavailableSummary, SetupsUnavailableError, type SetupAttempt } from './setup-fallback.js'
 import { assertScheduledModel } from './model-policy.js'
-import { RunStore, type RunRecord } from './runs.js'
+import { RunStore, saveRunHandoff, takeRunHandoff, type RunRecord } from './runs.js'
 import { splitTelegramText } from './reply.js'
 import { markdownToTelegramHtml, escapeHtml } from './format.js'
 import { sanitizeFileName, stageChatAttachment, workspaceFile } from './files.js'
@@ -38,6 +38,7 @@ import { transcribeAudio, synthesizeSpeech } from './audio.js'
 import { normalizeReactionEmoji } from './reaction.js'
 import { downloadTelegramFile } from './read-request.js'
 import { createConversationMenu } from './conversation-menu.js'
+import { queueSessionClose } from './session-close.js'
 import { createAiMenu, mainCommands, mainKeyboard } from './menu.js'
 import { chatPreset, initialPreset, persistedPreset, presetLabel, statusPreset, type AiPreset } from './ai.js'
 import { discoverDefaults } from './client-defaults.js'
@@ -77,13 +78,27 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
   const codexHome = join(config.controlDir, 'cli', 'codex')
   const conversationMenu = createConversationMenu(control)
   const aiMenu = createAiMenu(control, config.executorCli, undefined, config.workspace, codexHome,
-    undefined, opencodeDataHome(config.controlDir))
+    undefined, opencodeDataHome(config.controlDir), (session) => closeSession(session))
   const durableWorkerChoice = () => control.captureChoice(aiMenu.initial)
   const binDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'bin')
+  // Queue the replaced chat session's silent close turn (session-close.ts).
+  // A busy relay starts it after the active run, ahead of newer chat input.
+  const closeSession = async (session: SessionState | null): Promise<void> => {
+    if (config.channelBackendUrl) return
+    // The replacement is already saved; a failed close must not fail that reply.
+    try {
+      const run = await queueSessionClose(runs, (await control.status()).owner, session)
+      if (run) void startJob(run).catch((error) => console.error('Conversation close failed to start', safeError(error)))
+    } catch (error) { console.error('Conversation close failed to queue', safeError(error)) }
+  }
 
   let activeTypingTimer: ReturnType<typeof setInterval> | null = null
   let activeBackend = false
   const ownerStopped = new WeakSet<ChildProcess>()
+  // Host-transport executors outlive this relay; a graceful stop hands them off.
+  const hostTransport = process.env.EZ_EXECUTOR_TRANSPORT === 'host' && !config.channelBackendUrl
+  const childRuns = new WeakMap<ChildProcess, string>()
+  const handedOff = new WeakSet<ChildProcess>()
   let activeChild: ChildProcess | null = null
   let runtimeStarted = false
   let shuttingDown = false
@@ -114,6 +129,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       format: 'wav',
     }) : undefined,
     wake: () => { void drainSources().catch(error => console.error('Application queue unavailable', safeError(error))) },
+    closeSession: (session) => closeSession(session),
     createTelegramPairing: async (bindingId, owner) => {
       const username = bot?.botInfo?.username
       if (!username || !/^[A-Za-z][A-Za-z0-9_]{4,31}$/.test(username))
@@ -178,7 +194,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       // stat uses the effective UID; access uses the relay's isolated real UID.
       if (await stat(join(config.controlDir,'upgrade-pause.json')).then(()=>true,e=>{if(e.code==='ENOENT')return false;throw e})) return
       if ((await runs.get(run.id))?.status !== 'queued') return
-      if (!telegramEnabled && !run.application && !run.delivery && !run.scheduled && !run.external) return
+      if (!telegramEnabled && !run.application && !run.delivery && !run.scheduled && !run.external && !run.sessionClose) return
       if (!run.scheduled && await runs.running(false)) return
       const owner = (await control.status()).owner
       if (!owner || !ownsRun(owner, run)) {
@@ -280,8 +296,8 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
         const settle = (change: Partial<SetupAttempt>) => {
           attempts = [...attempts.slice(0, -1), { ...attempts[attempts.length - 1], ...change, endedAt: new Date().toISOString() }]
         }
-        // Advance only after an eligible pre-work failure of a current, uncancelled
-        // occurrence. Setups in an exhausted quota scope are skipped and recorded.
+        // Advance only after an eligible failure (see attemptFailure) of a current,
+        // uncancelled occurrence. Setups in an exhausted scope are skipped and recorded.
         const advance = async (): Promise<AiPreset | undefined> => {
           let preset: AiPreset | undefined
           const current = !shuttingDown && !await scheduler.cancelled(run.id) ? (await control.status()).owner : undefined
@@ -297,16 +313,18 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
           await runs.patch(run.id, { attempts })
           return preset
         }
-        // Each attempt is a fresh native session; a rejected Claude attempt already claimed its ID.
+        // Each attempt is a fresh native session: a rejected Claude attempt already
+        // claimed its ID, and a session cannot resume under another login's home.
         const launchSetup = async (preset: AiPreset): Promise<{ child: ChildProcess; cleanup: () => Promise<void>; preset: AiPreset }> => {
           for (;;) {
             const sessionId = attempts.length ? randomUUID() : session.nativeSessionId || session.sessionId
+            const continuation = continuationLine(started.id, attempts)
             if (ordered) {
-              attempts = [...attempts, { preset, quotaScope: quotaScope(preset), outcome: 'running', startedAt: new Date().toISOString() }]
+              attempts = [...attempts, { preset, quotaScope: quotaScope(preset), outcome: 'running', sessionId, startedAt: new Date().toISOString() }]
               await runs.patch(run.id, { attempts })
             }
             try {
-              return { ...await launch(texts, script ? {
+              return { ...await launch(continuation ? [...texts, continuation] : texts, script ? {
                 workspace: config.workspace, timeoutMs: 0, repairEnabled: config.repairEnabled, runId: started.id,
                 controlDir: config.controlDir, binDir,
                 script: { ...script.ref, scheduleId: script.scheduled.id, scheduleRevision: script.scheduled.revision, dueAt: script.scheduled.dueAt },
@@ -371,6 +389,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
             startup_ms: Math.round(executionStarted - launchStarted), resumed: session.hasStarted })
           if (run.scheduled) background.set(run.id,child)
           else activeChild = child
+          childRuns.set(child, run.id)
           const finished = new Promise<number | null>((resolve) => {
             if (child.exitCode !== null || child.signalCode !== null) resolve(child.exitCode)
             else child.once('close', resolve)
@@ -413,6 +432,8 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
               await withStartLock(async () => {
                 try {
                   await cleanup()
+                  // The next relay records a handed-off run's result.
+                  if (handedOff.has(child)) return
                   if (code === 0 && !run.external && !run.taskId && !run.scheduled) await control.markSessionStarted(session.sessionId)
                   const cancelled = !timedOut && (ownerStopped.has(child) || Boolean(run.scheduled && await scheduler.cancelled(run.id)))
                   if (timedOut) failureReason = 'script-timeout'
@@ -421,11 +442,10 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
                   // A rejection before work is a failure even when the CLI exits 0.
                   const failed = !cancelled && (code !== 0 || timedOut || Boolean(rejected))
                   if (startup) {
-                    settle({ outcome: cancelled ? 'cancelled' : failed ? 'failed' : 'completed', exitCode: code,
-                      ...(failed ? { category: rejected?.category ?? (observed!.workBegan ? 'after-work-began' : 'uncertain') } : {}),
-                      ...(failed && rejected?.resetAt ? { resetAt: rejected.resetAt } : {}) })
+                    const { continues, ...failure } = failed ? attemptFailure(observed!) : { continues: false }
+                    settle({ outcome: cancelled ? 'cancelled' : failed ? 'failed' : 'completed', exitCode: code, ...failure })
                     await runs.patch(run.id, { attempts })
-                    eligible = failed && !interrupted && advances(rejected)
+                    eligible = continues && !interrupted
                   }
                   if (!eligible) await finalize(code, cancelled, failed)
                 } catch (error) {
@@ -1029,7 +1049,9 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
 
     if (text === '/new') {
       await control.aiState(aiMenu.initial)
+      const previous = await control.getActiveSession()
       const next = await control.resetSession()
+      await closeSession(previous)
       await ctx.reply(
         `🔄 Started fresh conversation session (<code>${next.sessionId.slice(0, 8)}</code>). Agent files and memory preserved.`,
         { parse_mode: 'HTML' },
@@ -1217,7 +1239,9 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
         await ctx.reply(id ? `Incoming batch ${id} queued for retry.` : 'No failed incoming batch to retry.')
       } else if (action === 'new') {
         await control.aiState(aiMenu.initial)
+        const previous = await control.getActiveSession()
         const next = await control.resetSession()
+        await closeSession(previous)
         await ctx.answerCallbackQuery({ text: 'New session started' })
         await ctx.reply(
           `🔄 Started fresh conversation session (<code>${next.sessionId.slice(0, 8)}</code>).`,
@@ -1259,11 +1283,90 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
   })
   }
 
+  // Watch runs a previous relay handed off until they finish, with the normal
+  // receipts. Never relaunch; existing loops still revoke and cancel them. An
+  // unknown outcome is recorded interrupted, which holds its schedule.
+  const adoptHandoff = async (): Promise<void> => {
+    const handed = await takeRunHandoff(config.controlDir)
+    if (!hostTransport) { if (handed.length) console.error('Ignoring run handoff without host transport', handed.length); return }
+    // Admit every record before the first attach, so no trigger races a hold.
+    const admitted = (await Promise.all(handed.map(run => runs.adopt(run).catch(() => null)))).filter((run): run is RunRecord => run !== null)
+    for (const run of admitted) await withStartLock(async () => {
+      let child: ChildProcess
+      try {
+        // The foreground lane is serial; a second foreground handoff is corrupt.
+        if (!run.scheduled && activeChild) throw new Error('A second handed-off foreground run was cancelled; its outcome is unknown')
+        child = await attachHostJob(config.controlDir, run.id)
+      } catch (error) {
+        // Never leave an unobserved executor: ask the host to stop it.
+        await mkdir(join(config.controlDir, 'host-executor'), { recursive: true, mode: 0o700 })
+          .then(() => writeFile(join(config.controlDir, 'host-executor', run.id + '.cancel'), '', { mode: 0o600 })).catch(() => {})
+        await runs.patch(run.id, { status: 'failed', endedAt: new Date().toISOString(), interrupted: true, failureReason: 'handoff-outcome-unknown', failure: await failureEvidence(config.controlDir, safeError(error)) })
+        return
+      }
+      // Listen before any await so a fast exit cannot be missed.
+      const closed = new Promise<number | null>(resolve => child.once('close', resolve))
+      let errorTail = '', outputTail = '', timedOut = false
+      child.stdout?.setEncoding('utf8').on('data', (chunk: string) => { if (run.script) outputTail = (outputTail + chunk).slice(-16384) })
+      child.stderr?.setEncoding('utf8').on('data', (chunk: string) => {
+        errorTail = (errorTail + chunk).slice(-16384)
+        if (run.script) outputTail = (outputTail + chunk).slice(-16384)
+      })
+      if (run.scheduled) background.set(run.id, child)
+      else activeChild = child
+      childRuns.set(child, run.id)
+      await runs.patch(run.id, { pid: child.pid })
+      console.info('run adopted', { run_id: run.id, pid: child.pid })
+      // A script keeps its registered bound from its original start.
+      const limit = run.script ? await new Scripts(config.controlDir).get(run.script.id).then(script => script.timeoutSeconds, () => DEFAULT_SCRIPT_TIMEOUT_SECONDS) : 0
+      const timer = limit ? setTimeout(() => { timedOut = true; terminateJob(child) }, Math.max(0, Date.parse(run.startedAt ?? run.createdAt) + limit * 1000 - Date.now())) : undefined
+      const completion = closed.then(code => withStartLock(async () => {
+        clearTimeout(timer)
+        if (run.scheduled) background.delete(run.id)
+        else if (activeChild === child) activeChild = null
+        if (handedOff.has(child)) return
+        const cancelled = !timedOut && (ownerStopped.has(child) || Boolean(run.scheduled && await scheduler.cancelled(run.id)))
+        const failed = !cancelled && code !== 0
+        const status = cancelled ? 'cancelled' : failed ? 'failed' : 'completed'
+        const unknown = errorTail.includes('outcome is unknown'), transport = errorTail.includes('Host executor client interrupted by')
+        const failureReason = timedOut ? 'script-timeout' : unknown ? 'handoff-outcome-unknown' : transport ? 'host-executor-transport-interrupted'
+          : errorTail.includes('Host CLI executor is offline') ? 'host-executor-offline' : 'executor-exit'
+        if (code === 0 && run.execution && !run.external && !run.taskId && !run.scheduled) await control.markSessionStarted(run.execution.sessionId)
+        const at = new Date().toISOString(), last = run.attempts?.at(-1)
+        await runs.patch(run.id, { status, endedAt: at, exitCode: code,
+          ...(last?.outcome === 'running' ? { attempts: [...run.attempts!.slice(0, -1), { ...last, outcome: status, exitCode: code, endedAt: at }] } : {}),
+          ...(run.script ? { output: redactFailure(safeError(outputTail)), ...(timedOut ? { timedOut } : {}) } : {}),
+          ...(failed ? { failureReason, interrupted: unknown || transport, failure: await failureEvidence(config.controlDir, safeError(errorTail || `Executor exited with ${code === null ? 'a signal' : `code ${code}`}`)) } : {}) })
+        await releaseExternal(run)
+        console.info('run ended', { run_id: run.id, code, adopted: true })
+      })).then(async () => {
+        const next = await runs.nextQueued()
+        if (next && !shuttingDown) await startJob(next)
+      }).catch(error => console.error('Adopted run completion failed', safeError(error)))
+      completions.add(completion)
+      void completion.finally(() => completions.delete(completion))
+    }).catch(error => console.error('Run adoption failed', run.id, safeError(error)))
+  }
+
   let stopWork: Promise<void> | undefined
   const stop = (): Promise<void> => stopWork ?? (stopWork = (async () => {
     shuttingDown = true
     runtimeStarted = false
     pollingAbort.abort()
+    // Hand off running host work before any wait can outlast the stop grace
+    // period. The lock lets an in-flight launch register; later ones see shutdown.
+    if (hostTransport) await withStartLock(async () => {
+      const handoff = new Map<ChildProcess, RunRecord>()
+      for (const child of [...(activeChild ? [activeChild] : []), ...background.values()]) {
+        const run = childRuns.has(child) ? await runs.get(childRuns.get(child)!) : null
+        if (run?.status === 'running' && !ownerStopped.has(child) && child.exitCode === null && child.signalCode === null) handoff.set(child, run)
+      }
+      if (!handoff.size) return
+      try { await saveRunHandoff(config.controlDir, [...handoff.values()]) }
+      catch (error) { console.error('Run handoff failed; stopping host work', safeError(error)); return }
+      // SIGKILL leaves no cancel marker, so the host keeps each executor running.
+      for (const child of handoff.keys()) { handedOff.add(child); child.kill('SIGKILL') }
+    })
     await deliveryServer?.stop().catch(() => {})
     deliveryServer = null
     await applicationChannel.stop()
@@ -1275,8 +1378,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
     await Promise.all([sourceWork, intakeWork].map(work => work?.catch(() => {})))
     // Finish registering in-flight launches before taking the child snapshot.
     await withStartLock(async () => {
-      if (activeChild) terminateJob(activeChild)
-      for (const child of background.values()) terminateJob(child)
+      for (const child of [...(activeChild ? [activeChild] : []), ...background.values()]) if (!handedOff.has(child)) terminateJob(child)
       if (activeTypingTimer) clearInterval(activeTypingTimer)
     })
     await Promise.all(completions)
@@ -1302,11 +1404,13 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       deliveryServer = await serveDeliverySocket(config.controlDir, handleDeliveryOp, {
         ...(Number.isSafeInteger(deliveryTcpPort) && deliveryTcpPort >= 1024 && deliveryTcpPort <= 65535 ? { tcpPort: deliveryTcpPort } : {}),
       })
+      // Reconcile, then adopt handed-off runs, before any intake can launch work.
+      await scheduler.recover(runs)
+      await adoptHandoff()
       if (config.applicationPort) await applicationChannel.listen(config.applicationPort, config.applicationHost)
       runtimeStarted = true
       const owner = (await control.status()).owner
       if (telegramEnabled && telegramOwner(owner) && !config.channelBackendUrl) await telegramSource!.start(owner!)
-      await scheduler.recover(runs)
       sourceTimer = setInterval(() => {
         void drainSources().catch(error => console.error('Event-source drain failed', safeError(error)))
       }, 1000)
@@ -1380,7 +1484,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       }
     }
   }
-  return { bot: bot!, telegramEnabled, isRunning: () => telegramEnabled ? Boolean(bot?.isRunning()) : runtimeStarted, start, stop, drainOutbox, drainInbox, drainSources, drainTaskRequests, applicationChannel }
+  return { bot: bot!, telegramEnabled, isRunning: () => telegramEnabled ? Boolean(bot?.isRunning()) : runtimeStarted, start, stop, drainOutbox, drainInbox, drainSources, drainTaskRequests, adoptHandoff, applicationChannel }
 }
 
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {

package/src/menu.ts

@@ -3,7 +3,7 @@ import { readFile } from 'node:fs/promises'
 import path from 'node:path'
 import { randomBytes } from 'node:crypto'
 import { InlineKeyboard, type Context } from 'grammy'
-import { ControlStore, type ControlGuard } from './control-state.js'
+import { ControlStore, type ControlGuard, type SessionState } from './control-state.js'
 import { chatPreset, installed, persistedPreset, presetLabel, presetProvider, readModels, sameChoice, sameEngine, validateSelection, type AiPreset, type ModelChoice } from './ai.js'
 import { discoverDefaults } from './client-defaults.js'
 import { claudeConfigHome } from './executor.js'
@@ -31,7 +31,7 @@ const matchesModel = (preset: AiPreset, model: ModelChoice) =>
 // Short-lived opaque button IDs: no model names or executable arguments from callbacks.
 // These are operational settings, not a second conversational/agent loop.
 export const createAiMenu = (control: ControlStore, cli: string, catalog = readModels, workspace = process.cwd(), codexHome?: string,
-  isInstalled = installed, opencodeDataHome?: string) => {
+  isInstalled = installed, opencodeDataHome?: string, closeSession?: (session: SessionState | null) => Promise<void>) => {
   const initial = chatPreset(cli)
   const host = process.env.EZ_EXECUTOR_TRANSPORT === 'host'
   if (host) catalog = async () => JSON.parse(await readFile(path.join(process.env.EZ_CONTROL_DIR!, 'host-executor/models.json'),'utf8'))
@@ -68,6 +68,7 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
     const current = state.presets.find((p) => p.id === state.selectedId)!
     const fresh = !sameEngine(current, preset) || presetProvider(current) !== presetProvider(preset) || Boolean(session && !session.cli)
     if (!await control.selectPreset(preset.id, expectedSession, fresh, guard)) throw new Error('AI binding changed. Refresh available AIs before trying again.')
+    if (fresh) await closeSession?.(session)
     return { preset, fresh }
   }
   const choose = async (ctx: Context, preset: AiPreset) => {

package/src/plugins/manager.mjs

@@ -7,7 +7,8 @@ import { fileURLToPath } from 'node:url';
 import { createHash, randomUUID, randomBytes } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { callDeliverySocket } from '../delivery-socket-client.mjs';
-import { readFileSync, realpathSync } from 'node:fs';
+import { TOOLS_LINE } from '../tools-line.mjs';
+import { readFileSync, readlinkSync, realpathSync } from 'node:fs';
 
 const reserved = new Set(['status','updates','plugins','tools','message','owner','approval','react','setup','help','version']);
 const id = value => { if(typeof value !== 'string' || !/^[a-z][a-z0-9-]{0,39}$/.test(value)) throw Error('Invalid identifier'); return value; };
@@ -41,39 +42,31 @@ export async function stewardOwned(file) {
   const parent = await fs.stat(path.dirname(file));
   await fs.chown(file, parent.uid, parent.gid);
 }
-// Native instructions keep only the registry locator and one crucial routing
-// hint. Inventory and full scheduler usage are generated on read.
-export async function toolDiscoveryBlock(home,hostConfig) {
-  home=await fs.realpath(home);
-  let launcher=path.join(home,'bin','ez');
-  const config=hostConfig?{hostConfig}:await json(path.join(home,'config.json')).catch(error=>{if(error.code==='ENOENT')return undefined;throw error;});
-  if(config?.hostConfig) {
-    const host=await json(config.hostConfig);
-    if(host.isolation==='isolated') launcher='ez';
-  }
+// Retire the former `ez tools` footer once: replace the marked block with
+// TOOLS_LINE and leave every other byte untouched. The name is kept because
+// upgraders released before this change call it on the target package;
+// remove it when no installed core predates the change.
+export async function bindToolDiscovery(_home,workspace) {
+  workspace=await fs.realpath(workspace);
   const start='<!-- ez tools: begin -->',end='<!-- ez tools: end -->';
-  const block=start+'\nUse `'+launcher+'`; run it with `--help` or `tools list --details` to discover installed capabilities, and read the matching skill when needed.\nKeep the channel responsive: during a foreground owner turn, prefer `ezenciel-agents-schedule create --now ...` when work can continue independently. A `[schedule ...]` turn executes its assigned work directly and must not schedule it again.\n'+end;
-  if(Buffer.byteLength(block)>600)throw Error('Tool discovery guidance exceeds the 600-byte core budget');
-  return {block,start,end};
-}
-export async function bindToolDiscovery(home,workspace) {
-  home=await fs.realpath(home);workspace=await fs.realpath(workspace);
-  const {block,start,end}=await toolDiscoveryBlock(home);
   for(const name of ['AGENTS.md','AGENTS.override.md']) {
     const file=path.join(workspace,name);
     const stat=await fs.lstat(file).catch(e=>{if(e.code==='ENOENT')return null;throw e;});
-    if(!stat && name!=='AGENTS.md')continue;
-    if(stat && !stat.isFile())throw Error('Tool instructions must be a regular file');
-    const prior=stat?await fs.readFile(file,'utf8'):'';
+    if(!stat)continue;
+    if(!stat.isFile())throw Error('Tool instructions must be a regular file');
+    const prior=await fs.readFile(file,'utf8');
     const from=prior.indexOf(start),to=prior.indexOf(end);
-    if((from<0)!==(to<0)||(from>=0&&(to<from||prior.indexOf(start,from+start.length)>=0||prior.indexOf(end,to+end.length)>=0)))throw Error('Malformed tool discovery block');
-    const next=from<0?prior+'\n'+block+'\n':prior.slice(0,from)+block+prior.slice(to+end.length);
-    if(next===prior)continue;
+    if(from<0&&to<0)continue;
+    if((from<0)!==(to<0)||to<from||prior.indexOf(start,from+start.length)>=0||prior.indexOf(end,to+end.length)>=0)throw Error('Malformed tool discovery block');
+    const next=prior.slice(0,from)+(prior.includes(TOOLS_LINE)?'':TOOLS_LINE)+prior.slice(to+end.length);
     const tmp=file+'.'+randomUUID()+'.tmp';
     try {await fs.writeFile(tmp,next,{mode:0o600,flag:'wx'});await fs.rename(tmp,file);}finally{await fs.rm(tmp,{force:true});}
   }
 }
 const invocationDirectory = home => path.join(home,'command-invocations');
+// A lease pid is only meaningful inside the PID namespace that wrote it. The
+// isolated broker writes leases from its container, which the host cannot probe.
+const pidNamespace=(()=>{try{return readlinkSync('/proc/self/ns/pid');}catch{return undefined;}})();
 async function activeInvocations(home) {
   const directory=invocationDirectory(home),files=await fs.readdir(directory).catch(error=>{if(error.code==='ENOENT')return [];throw error;});
   for(const file of files) {
@@ -81,8 +74,11 @@ async function activeInvocations(home) {
     const lease=await json(path.join(directory,file)).catch(error=>{if(error.code==='ENOENT')return null;throw error;});
     if(!lease)continue;
     if(!Number.isSafeInteger(lease.pid)||lease.pid<1||typeof lease.container!=='string'||!lease.container)throw Error('Invalid command invocation lease; inspect before recovery');
-    try {process.kill(lease.pid,0);return true;} catch(error) {if(error.code!=='ESRCH'&&error.code!=='EPERM')throw error;}
-    const state=await run(['container','inspect',lease.container],{capture:true});
+    const foreign=typeof lease.pidNamespace==='string'&&lease.pidNamespace!==pidNamespace;
+    if(!foreign) {try {process.kill(lease.pid,0);return true;} catch(error) {if(error.code!=='ESRCH'&&error.code!=='EPERM')throw error;}}
+    const state=await run(['container','inspect','--format','{{.State.Running}}',lease.container],{capture:true});
+    // Foreign leases: the call container's own state is the only liveness signal.
+    if(state.code===0&&foreign&&state.stdout.trim()==='true')return true;
     if(state.code===0)throw Error(`Stale command invocation lease; inspect container ${lease.container} before recovery`);
     if(!/No such (?:object|container)/i.test(state.stderr+state.stdout))throw Error('Unable to verify a stale command invocation lease; inspect Docker before recovery');
     await fs.rm(path.join(directory,file));
@@ -91,7 +87,7 @@ async function activeInvocations(home) {
 }
 async function invocationLease(home,container) {
   const directory=invocationDirectory(home);await privateDir(directory);
-  const file=path.join(directory,randomUUID()+'.json');await fs.writeFile(file,JSON.stringify({pid:process.pid,container}),{mode:0o600,flag:'wx'});
+  const file=path.join(directory,randomUUID()+'.json');await fs.writeFile(file,JSON.stringify({pid:process.pid,container,...(pidNamespace?{pidNamespace}:{})}),{mode:0o600,flag:'wx'});
   await stewardOwned(file);
   return async()=>{await fs.rm(file,{force:true});};
 }
@@ -150,9 +146,11 @@ export async function snapshot(source) {
   return {source,files,manifest,deployment,sharedRevisions,revision:`sha256:${digest.digest('hex')}`};
 }
 export function validate(m,d,files) {
-  keys(m,['schemaVersion','id','version','description','commands','skills']);
+  keys(m,['schemaVersion','id','version','description','commands','skills','example']);
   if(m.schemaVersion!==1 || (typeof m.version!=='string' || !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(m.version))) throw Error('Unsupported manifest version');
   id(m.id); strings(m.skills);
+  // One representative call shown by `tools list --details`; usage stays in --help/skill.
+  if(m.example!==undefined && (typeof m.example!=='string' || m.example.length>160 || /[\0-\x1f\x7f]/.test(m.example) || !Object.hasOwn(m.commands||{},m.example.split(' ')[0]))) throw Error('Manifest example must be one line of at most 160 characters starting with a declared command');
   keys(d,['schemaVersion','services','commands','exports',...(d.schemaVersion>=2?['secrets']:[]),...(d.schemaVersion===3?['sharedServices']:[])]);
   if(![1,2,3].includes(d.schemaVersion) || !d.services || !d.commands) throw Error('Unsupported deployment descriptor');
   for(const [name,s] of Object.entries(d.services)) {
@@ -397,11 +395,13 @@ export function run(argv,{capture=false,container,signal,stdin,onStdout,onStart,
     child.once('close',async(code,childSignal)=>{process.off('SIGTERM',term);process.off('SIGINT',int);
       clearTimeout(killTimer);
       clearTimeout(timeout);signal?.removeEventListener('abort',term);
-      if(cancelled&&container) {
+      // --rm only removes a container that ran. Compose stopping between
+      // create and start (cancelled, signalled or failed) strands it Created.
+      if(container&&(cancelled||code!==0)) {
         try {
           await removeCommandContainer(container);
         } catch(error) {
-          const uncertain=error instanceof Error?error:Error('Cancelled command container cleanup failed');
+          const uncertain=error instanceof Error?error:Error('Command container cleanup failed');
           uncertain.containerCleanupUncertain=true;return reject(uncertain);
         }
       }
@@ -409,7 +409,7 @@ export function run(argv,{capture=false,container,signal,stdin,onStdout,onStart,
       resolve({code:cancelled?130:code??(childSignal?130:1),stdout,stderr});});
   });
 }
-// Compose --rm can race cancellation. Confirm disappearance instead of treating
+// Compose --rm can race this cleanup. Confirm disappearance instead of treating
 // Docker's in-progress removal as either failure or completed cleanup.
 export async function removeCommandContainer(container,execute=run) {
   const cleanup=await execute(['container','rm','--force',container],{capture:true});
@@ -422,7 +422,7 @@ export async function removeCommandContainer(container,execute=run) {
       await new Promise(resolve=>setTimeout(resolve,100));
     }
   }
-  throw Error(`Cancelled command container cleanup failed: ${cleanup.stderr||cleanup.stdout}`);
+  throw Error(`Command container cleanup failed: ${cleanup.stderr||cleanup.stdout}`);
 }
 
 async function checked(args) {
@@ -530,7 +530,6 @@ export async function init(home,workspace,catalogFile,hostConfig,standalone=fals
   if(standalone && hostConfig) throw Error('Standalone setup cannot bind a relay host config');
   if(typeof home!=='string'||typeof workspace!=='string'||!path.isAbsolute(home)||!path.isAbsolute(workspace)||/[\r\n\0$:,]/.test(home+workspace)) throw Error('Explicit absolute home/workspace required');
   workspace=await fs.realpath(workspace);await privateDir(home);home=await fs.realpath(home);if(hostConfig)hostConfig=await fs.realpath(hostConfig);
-  await toolDiscoveryBlock(home,hostConfig);
   if(await fs.lstat(path.join(home,'registry.json')).catch(()=>null)) throw Error('Registry already exists; refusing replacement');
   catalogFile=path.resolve(catalogFile||fileURLToPath(new URL('../../default-plugins.json',import.meta.url)));
   const sources=await json(catalogFile);
@@ -563,7 +562,6 @@ export async function init(home,workspace,catalogFile,hostConfig,standalone=fals
       agent.binDir=bin;agent.toolsHome=home;await atomic(hostConfig,host);
     }
   });
-  await bindToolDiscovery(home,workspace);
   if(hostConfig && path.basename(hostConfig)==='host-executor.json') await (await import('../updates/binding.mjs')).bindUpdates(home,hostConfig);
   return {ok:true,launcher:path.join(home,'bin','ez'),workspace};
 }
@@ -651,12 +649,17 @@ export async function main(args) {
       return emit({plugin:name,revision:record.revision,path:skill,content:await fs.readFile(file,'utf8')});
     }
     if(action==='list') {
-      if(group==='tools' && args.length===1 && args[0]==='--details')return emit(Object.fromEntries(Object.entries(r.plugins).map(([name,p])=>[name,{
-        description:typeof p.manifest.description==='string'?p.manifest.description.replace(/\s+/g,' ').trim().slice(0,200):'',
-        commands:Object.keys(p.manifest.commands).map(alias=>`ez ${alias} --help`),
-        skills:p.manifest.skills.map(skill=>path.join(p.source,skill)),
-        skillReads:p.manifest.skills.map(skill=>['ez','tools','skill',name,skill]),
-      }])));
+      // Self-sufficient index: aliases, purpose, skill and one call per plugin.
+      if(group==='tools' && args.length===1 && args[0]==='--details')return emit(Object.fromEntries(Object.entries(r.plugins).map(([name,p])=>{
+        const aliases=Object.keys(p.manifest.commands);
+        return [name,{
+          aliases,
+          purpose:typeof p.manifest.description==='string'?p.manifest.description.replace(/\s+/g,' ').trim().slice(0,200):'',
+          skills:p.manifest.skills.map(skill=>path.join(p.source,skill)),
+          skillReads:p.manifest.skills.map(skill=>['ez','tools','skill',name,skill]),
+          example:`ez ${p.manifest.example ?? `${aliases[0]} --help`}`,
+        }];
+      })));
       if(args.length)throw Error('Use tools list [--details] or plugins list');
       return emit(group==='tools'?r.commands:r.plugins);
     }