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

package/src/ai.ts

@@ -12,7 +12,6 @@ import { AUTH_PROFILE_CLIS, claudeAuthEnvironment, cliHome, isAuthProfile, listA
 export type AiPreset = { id: string; name: string; cli: string; provider?: string; authProfile?: string; model?: string; effort?: string }
 // Optional ordered fallbacks are tried only for a scheduled occurrence that never started work.
 export type ExecutionChoice = { sessionId: string; preset: AiPreset; fallbacks?: AiPreset[] }
-export const MAX_FALLBACKS = 3
 export type ModelChoice = { cli: string; provider?: string; authProfile?: string; model?: string; name: string; efforts: string[] }
 type Engine = { cli?: string; authProfile?: string }
 // A native conversation belongs to one client and one credential home.
@@ -34,7 +33,7 @@ export const isPreset = (p: unknown): p is AiPreset => {
 export const isExecutionChoice = (v: unknown): v is ExecutionChoice => {
   const c = v as ExecutionChoice | undefined
   return Boolean(c && /^[0-9a-f-]{36}$/i.test(c.sessionId) && isPreset(c.preset) &&
-    (c.fallbacks === undefined || (Array.isArray(c.fallbacks) && c.fallbacks.length > 0 && c.fallbacks.length <= MAX_FALLBACKS && c.fallbacks.every(isPreset))))
+    (c.fallbacks === undefined || (Array.isArray(c.fallbacks) && c.fallbacks.length > 0 && c.fallbacks.every(isPreset))))
 }
 export const presetLabel = (p: AiPreset) => `${p.cli}${p.authProfile ? `@${p.authProfile}` : ''}${p.provider ? ` (${p.provider})` : ''} · ${p.model || 'client default'} · ${p.effort || 'default effort'}`
 // OpenCode encodes its provider in the native provider/model identifier.
@@ -264,6 +263,21 @@ export const opencodeProviderAllowlist = (env: NodeJS.ProcessEnv = process.env):
   return validateOpencodeProviders([...new Set(raw.split(',').map((p) => p.trim()).filter(Boolean))])
 }
 
+// Shared by native menus and application controls; a rejected choice never mutates state.
+export const catalogSelection = (p: {cli?: unknown; provider?: unknown; authProfile?: unknown; model?: unknown; effort?: unknown}, catalog: ModelChoice[]): ModelChoice => {
+  const candidate = {...p, id: 'selection', name: 'Selection'}
+  if (!isPreset(candidate)) throw new Error('Invalid AI selection fields')
+  const model = catalog.find(m => sameEngine(m, candidate) && m.provider === candidate.provider && m.model === candidate.model)
+  if (!model) {
+    if (!catalog.some(m => sameEngine(m, candidate)))
+      throw new Error(`No models advertised for ${candidate.cli}${candidate.authProfile ? `@${candidate.authProfile}` : ''} in the installed client catalog; current selection unchanged.`)
+    throw new Error(`Model ${candidate.model ?? '(client default)'} is not in the installed client catalog for ${candidate.cli}; current selection unchanged.`)
+  }
+  if (candidate.effort !== undefined && !model.efforts.includes(candidate.effort))
+    throw new Error(`Effort ${candidate.effort} is not supported for ${candidate.cli} ${candidate.model ?? '(client default)'}. Supported efforts: ${model.efforts.join(', ') || 'none (omit effort)'}; current selection unchanged.`)
+  return model
+}
+
 export const validateSelection = async (p: AiPreset, catalog: ModelChoice[], available = installed): Promise<void> => {
   assertEffort(p.effort, p.model, p.cli)
   if (!isPreset(p)) throw new Error('This CLI is not installed.')
@@ -273,9 +287,7 @@ export const validateSelection = async (p: AiPreset, catalog: ModelChoice[], ava
     if (!catalog.some((m) => sameEngine(m, p))) throw new Error('This auth profile is not provisioned for the selected CLI.')
     return
   }
-  const model = catalog.find((m) => sameEngine(m, p) && m.provider === p.provider && m.model === p.model)
-  if (!model || (p.effort && !model.efforts.includes(p.effort)))
-    throw new Error('This model/effort is not in the installed client catalog. Refresh the client and try again; no fallback was selected.')
+  catalogSelection(p, catalog)
 }
 
 export type AuthProfileStatus = { cli: string; authProfile: string | null; provisioned: boolean; sharesHostLogin: boolean

package/src/application-channel.ts

@@ -2,11 +2,11 @@ import { createServer, type Server, type IncomingMessage, type ServerResponse }
 import { createHash, randomUUID, timingSafeEqual } from 'node:crypto'
 import { mkdir, readFile, writeFile, rename, open, unlink, stat, chown } from 'node:fs/promises'
 import { join } from 'node:path'
-import { ControlStore, sessionTitle, telegramOwner, type ControlGuard, type Owner, sameOwner, validOwner, ownerId, ownerEpoch } from './control-state.js'
+import { ControlStore, sessionTitle, telegramOwner, type ControlGuard, type Owner, type SessionState, sameOwner, validOwner, ownerId, ownerEpoch } from './control-state.js'
 import { RunStore, type RunRecord, type OutboxItem } from './runs.js'
 import { ownsRun } from './identity.js'
 import { applicationId, validApplicationOrigin } from './application-origin.js'
-import { isPreset, sameChoice, sameEngine, type AiPreset, type ModelChoice } from './ai.js'
+import { isPreset, sameChoice, catalogSelection, type AiPreset, type ModelChoice } from './ai.js'
 import { MAX_INCOMING_ATTACHMENT_BYTES, stageChatAttachment } from './files.js'
 import { assertEffort } from './model-policy.js'
 import { ApprovalStore } from './approval.js'
@@ -97,6 +97,8 @@ export class ApplicationChannel {
   constructor(private options: {
     controlDir: string; workspace?: string; isolation?: string; initial: AiPreset
     wake: () => void
+    // Queues the replaced conversation's silent close turn (session-close.ts).
+    closeSession?: (session: SessionState | null) => Promise<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 }>
@@ -155,7 +157,7 @@ export class ApplicationChannel {
     const owner = await this.sharedBinding(bindingId)
     const controls = this.options.aiControls
     if (!controls) throw new Error('Application controls unavailable')
-    const value = input as {action?: unknown; expectedSession?: unknown; sessionId?: unknown; presetId?: unknown; cli?: unknown; provider?: unknown; model?: unknown; effort?: unknown}
+    const value = input as {action?: unknown; expectedSession?: unknown; sessionId?: unknown; presetId?: unknown; cli?: unknown; provider?: unknown; authProfile?: unknown; model?: unknown; effort?: unknown}
     if (!value || !['new','switch','select','model'].includes(String(value.action)) ||
       !(value.expectedSession === null || (typeof value.expectedSession === 'string' && /^[a-f0-9-]{36}$/.test(value.expectedSession)))) throw new Error('Invalid application control request')
     const fields = {new:[],switch:['sessionId'],select:['presetId'],model:['cli','provider','authProfile','model','effort']}[value.action as 'new'|'switch'|'select'|'model']!
@@ -168,7 +170,11 @@ export class ApplicationChannel {
       const live = (await this.bindings.list()).find(item=>item.bindingId===bindingId)
       if (!live?.shareTelegram || !sameOwner(owner, live.owner)) throw new Error('Application authority revoked')
     }}
-    if (value.action === 'new') await control.resetSession(expected, guard)
+    if (value.action === 'new') {
+      const previous = await control.getActiveSession()
+      await control.resetSession(expected, guard)
+      await this.options.closeSession?.(previous)
+    }
     if (value.action === 'switch') {
       if (typeof value.sessionId !== 'string') throw new Error('Invalid application conversation')
       // switchSession enforces the same visibility/engine restrictions as /chats.
@@ -181,8 +187,7 @@ export class ApplicationChannel {
       await controls.select(preset, expected, guard)
     }
     if (value.action === 'model') {
-      const model = (await controls.catalog()).find(item => sameEngine(item, value as {cli?:string;authProfile?:string}) && item.provider === value.provider && item.model === value.model)
-      if (!model || (value.effort !== undefined && (typeof value.effort !== 'string' || !model.efforts.includes(value.effort)))) throw new Error('Invalid application model selection')
+      const model = catalogSelection(value, await controls.catalog())
       await this.sharedBinding(bindingId)
       const preset = await controls.saveSelection(model, value.effort as string | undefined, guard)
       await this.sharedBinding(bindingId)
@@ -231,8 +236,7 @@ export class ApplicationChannel {
       await controls.validate(preset)
     }
     if (value.action==='model') {
-      const model = (await controls.catalog()).find(item=>sameEngine(item,value as {cli?:string;authProfile?:string}) && item.provider===value.provider && item.model===value.model)
-      if (!model || (value.effort!==undefined && (typeof value.effort!=='string' || !model.efforts.includes(value.effort)))) throw new Error('Invalid application model selection')
+      const model = catalogSelection(value, await controls.catalog())
       preset = await controls.saveSelection(model,value.effort as string|undefined,guard)
     }
     await control.changeApplicationSession(hashedScope,guard,preset)

package/src/control-state.ts

@@ -763,10 +763,16 @@ export class ControlStore {
       await requireControlGuard(state, guard)
       if (!state.ai) throw new Error('AI settings not initialized')
       // Auto-detected client defaults come and go with installed clients; only
-      // owner-saved choices count toward the cap.
-      if (state.ai.presets.filter((p) => !p.id.startsWith('detected_')).length >= 12 && !state.ai.presets.some((p) => p.id === preset.id))
-        throw new Error('Keep it small: at most 12 saved AIs.')
-      state.ai.presets = [...state.ai.presets.filter((p) => p.id !== preset.id), persistedPreset(preset)]
+      // owner-saved choices count toward the cap. Conversations keep their own
+      // preset copy, so at the cap the oldest unreferenced choice makes room.
+      const ai = state.ai
+      const saved = ai.presets.filter((p) => !p.id.startsWith('detected_'))
+      if (saved.length >= 12 && !ai.presets.some((p) => p.id === preset.id)) {
+        const kept = new Set([ai.selectedId, ai.defaultId, ...(ai.recentIds ?? [])])
+        const oldest = saved.find((p) => !kept.has(p.id))!
+        ai.presets = ai.presets.filter((p) => p.id !== oldest.id)
+      }
+      ai.presets = [...ai.presets.filter((p) => p.id !== preset.id), persistedPreset(preset)]
       await this.writeState(state)
     })
   }

package/src/delivery-socket-client.mjs

@@ -78,7 +78,7 @@ const readEndpoint = async controlDir => {
   } catch { return null }
 }
 
-export const callDeliverySocket = async (socketPath, op, timeoutMs = 130_000) => {
+const callOnce = async (socketPath, op, timeoutMs) => {
   const id = `${Date.now().toString(36)}_${Math.floor(Math.random() * 0xffffff).toString(16)}`
   try {
     return await exchange(() => createConnection(socketPath), { id, ...op }, timeoutMs, socketPath)
@@ -104,3 +104,17 @@ export const deliverySocketAlive = async (socketPath, timeoutMs = 2000) => {
     return false
   }
 }
+
+// Only retry connection failures during a declared runtime swap. No frame was
+// accepted in that case. Timeouts, provider failures and uncertain writes fail.
+export const callDeliverySocket = async (socketPath, op, timeoutMs = 130_000) => {
+  const until=Date.now()+120000;
+  for(;;){
+    try{return await callOnce(socketPath,op,timeoutMs);}
+    catch(error){
+      if(!error?.connectFailure||op.op!=='enqueue'||Date.now()>=until)throw error;
+      try{await readFile(path.join(path.dirname(socketPath),'upgrade-pause.json'),'utf8');}catch{throw error;}
+      await new Promise(resolve=>setTimeout(resolve,250));
+    }
+  }
+};

package/src/delivery-socket.ts

@@ -83,7 +83,7 @@ export const authorizeRun = async (controlDir: string, runId: string): Promise<R
 const encode = (value: unknown): string => `${JSON.stringify(value)}\n`
 
 export type DeliveryEndpoint = { host: '127.0.0.1'; port: number; token: string }
-export type DeliveryServeOptions = { tcpPort?: number }
+export type DeliveryServeOptions = { tcpPort?: number; beforeClose?: () => Promise<void> }
 const endpointFile = 'delivery-endpoint.json'
 const tokensMatch = (candidate: unknown, token: string): boolean =>
   typeof candidate === 'string' && candidate.length === token.length && timingSafeEqual(Buffer.from(candidate), Buffer.from(token))
@@ -94,6 +94,8 @@ export const serveDeliverySocket = async (
   options: DeliveryServeOptions = {},
 ): Promise<{ socketPath: string; endpoint: DeliveryEndpoint | null; stop: () => Promise<void> }> => {
   const socketPath = deliverySocketPath(controlDir)
+  let closing=false
+  const admissions=new Set<Promise<void>>()
   await rm(socketPath, { force: true }).catch(() => {})
   const attach = (socket: Socket, token: string | null): void => {
     let buffer = ''
@@ -105,7 +107,8 @@ export const serveDeliverySocket = async (
         const line = buffer.slice(0, newline)
         buffer = buffer.slice(newline + 1)
         if (!line.trim()) continue
-        void (async () => {
+        let admission=false
+        const work=(async () => {
           let id: unknown = null
           try {
             const envelope = JSON.parse(line) as { id?: unknown; token?: unknown; op?: unknown; payload?: unknown }
@@ -116,12 +119,19 @@ export const serveDeliverySocket = async (
             // re-verifies owner authority server-side.
             if (token !== null && !tokensMatch(envelope.token, token)) { socket.destroy(); return }
             const { token: _token, ...request } = envelope
+            if(request.op==='enqueue'){
+              if(closing)throw Error('Delivery relay is shutting down; message was not accepted')
+              admission=true
+            }
             const result = await handle(request as DeliverySocketOp)
             socket.write(encode({ id, ok: true, result: result ?? null }))
           } catch (error) {
             socket.write(encode({ id, ok: false, error: error instanceof Error ? error.message : String(error ?? 'Unknown error') }))
           }
         })()
+        // Only finite admission handlers are a drain barrier; a receipt wait
+        // completes after the relay's delivery pump flushes the accepted items.
+        if(admission){admissions.add(work);void work.finally(()=>admissions.delete(work))}
       }
     })
   }
@@ -176,9 +186,13 @@ export const serveDeliverySocket = async (
     socketPath,
     endpoint,
     stop: async () => {
-      await new Promise<void>((resolve) => server.close(() => resolve()))
+      closing=true
+      const closed=Promise.all([new Promise<void>((resolve) => server.close(() => resolve())),
+        ...(tcpServer ? [new Promise<void>((resolve) => tcpServer!.close(() => resolve()))] : [])])
+      await Promise.all(admissions)
+      await options.beforeClose?.()
+      await closed
       await rm(socketPath, { force: true }).catch(() => {})
-      if (tcpServer) await new Promise<void>((resolve) => tcpServer.close(() => resolve()))
       if (tcpEndpoint) await rm(path.join(controlDir, endpointFile), { force: true }).catch(() => {})
     },
   }

package/src/executor.ts

@@ -1,7 +1,8 @@
 import { executionDefaults } from './model-policy.js'
 import { startTaskExecutor } from './task-executor.js'
 import { deliverySocketPath } from './delivery-socket.js'
-import { mkdtemp, rm, writeFile, mkdir, symlink, readFile } from 'node:fs/promises'
+import { mkdtemp, rm, writeFile, mkdir, symlink, readFile, rename } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
 import { accessSync, openSync, closeSync, constants as fsConstants } from 'node:fs'
 import { tmpdir, homedir } from 'node:os'
 import path from 'node:path'
@@ -13,9 +14,17 @@ import { DESKTOP_UNAVAILABLE } from './desktop-bridge.js'
 import { macosWorkspaceProfile, workspaceSiblingDenies } from './workspace-confine.js'
 import { Scripts, type ScriptRunRef } from './scripts.js'
 import { claudeAuthEnvironment, cliHome, provisionedHome } from './auth-profile.js'
+import { isHostRunId } from './host-executor-protocol.js'
+
+const hostCancelFiles = new WeakMap<ChildProcess, string>()
+const hostCancelFile = (controlDir: string, runId: string): string => {
+  if (!isHostRunId(runId)) throw new Error('Invalid host executor run ID')
+  return path.join(controlDir, 'host-executor', runId + '.cancel')
+}
 
 export type ExecutorOptions = {
   repairEnabled?: boolean
+  catalogTransport?: 'host' | 'local'
   workspace: string
   timeoutMs: number
   runId: string
@@ -79,7 +88,7 @@ export const executorEnvironment = (environment: NodeJS.ProcessEnv = process.env
 }
 
 export const executorJobEnv = (
-  options: Pick<ExecutorOptions, 'runId' | 'controlDir' | 'binDir' | 'toolsHome' | 'repairEnabled'> & { workspace?: string },
+  options: Pick<ExecutorOptions, 'runId' | 'controlDir' | 'binDir' | 'toolsHome' | 'repairEnabled' | 'catalogTransport'> & { workspace?: string },
   environment: NodeJS.ProcessEnv = process.env,
 ): NodeJS.ProcessEnv => {
   const base = executorEnvironment(environment)
@@ -88,6 +97,7 @@ export const executorJobEnv = (
     ...base,
     PATH: pathValue,
     EZ_RUN_ID: options.runId,
+    EZ_AI_CATALOG: options.catalogTransport ?? (environment.EZ_EXECUTOR_TRANSPORT==='host' ? 'host' : 'local'),
     EZ_CONTROL_DIR: options.controlDir,
     ...(options.workspace ? { EZ_AGENT_WORKSPACE: options.workspace } : {}),
     EZ_DELIVERY_SOCKET: deliverySocketPath(options.controlDir),
@@ -340,22 +350,33 @@ export const executorInvocation = (command: string, args: string[]) => {
     : { command, args }
 }
 
+// The isolated worker uses the same file transport as the host worker, but
+// stays in its own container. A published worker binding must never fall back
+// to local execution when its heartbeat expires.
+export const usesFileTransport = async (controlDir: string, env: NodeJS.ProcessEnv = process.env): Promise<boolean> => {
+  if (env.EZ_CONTAINER_EXECUTOR === '1') return false
+  if (env.EZ_EXECUTOR_TRANSPORT === 'host') return true
+  try { return JSON.parse(await readFile(path.join(controlDir,'host-executor/heartbeat.json'),'utf8')).containerExecutor === true }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; return false }
+}
+
 export const startExecutorJob = async (
   texts: string[],
   options: ExecutorOptions,
 ): Promise<{ child: ChildProcess; cleanup: () => Promise<void>; stdout: string }> => {
-  if (options.script && process.env.EZ_EXECUTOR_TRANSPORT !== 'host') return startScriptJob(options as ExecutorOptions & { script: ScriptLaunch })
+  const host = await usesFileTransport(options.controlDir)
+  const cancelFile = host ? hostCancelFile(options.controlDir, options.runId) : undefined
+  if (options.script && !host) return startScriptJob(options as ExecutorOptions & { script: ScriptLaunch })
   options = executionDefaults(executorKey(options.cli), options)
   // Named credential homes are owner-provisioned; fail closed before any launch state.
   if (options.authProfile !== undefined) await provisionedHome(options.controlDir, executorKey(options.cli), options.authProfile)
   // Routing is caller-owned: a restricted task run goes to the task runner
   // unless the host transport must ship it across the boundary first.
-  if (options.taskRun && process.env.EZ_EXECUTOR_TRANSPORT !== 'host') return startTaskExecutor(options)
+  if (options.taskRun && !host) return startTaskExecutor(options)
   if (options.nativeSession && !/^[a-zA-Z0-9_-]+$/.test(options.runId)) throw new Error('Invalid native task run ID')
   if (options.codexSandbox !== undefined && (options.codexSandbox !== 'external' || process.env.EZ_EXECUTOR_TRANSPORT !== 'local' || options.taskRun || executorKey(options.cli) !== 'codex')) throw new Error('External Codex sandbox requires an owner-authorized native local run')
   const outputDirectory = await mkdtemp(path.join(tmpdir(), 'ezenciel-agents-'))
   const key = executorKey(options.cli)
-  const host = process.env.EZ_EXECUTOR_TRANSPORT === 'host'
   const gui = !host && key === 'codex-gui'
   const nativeSession = !host && key === 'codex' && options.nativeSession === true
   // Literal input plus the caller-provided trigger line. No coaching,
@@ -458,6 +479,7 @@ export const startExecutorJob = async (
     stdio: ['pipe', 'pipe', 'pipe'],
     detached: process.platform !== 'win32',
   })
+  if (cancelFile) hostCancelFiles.set(child, cancelFile)
   await new Promise<void>((resolve, reject) => {
     child.once('spawn', resolve)
     child.once('error', reject)
@@ -500,6 +522,17 @@ export const startExecutorJob = async (
 
 export const startGrokJob = startExecutorJob
 
+// Watch a host-transport run a previous relay submitted; it is never resubmitted.
+export const attachHostJob = async (controlDir: string, runId: string): Promise<ChildProcess> => {
+  const cancelFile = hostCancelFile(controlDir, runId)
+  const invocation = executorInvocation(process.execPath, ['--import', fileURLToPath(new URL('../node_modules/tsx/dist/loader.mjs', import.meta.url)),
+    fileURLToPath(new URL('./host-executor-client.ts', import.meta.url)), controlDir, runId, '--attach'])
+  const child = spawn(invocation.command, invocation.args, { env: executorEnvironment(), stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32' })
+  hostCancelFiles.set(child, cancelFile)
+  await new Promise<void>((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject) })
+  return child
+}
+
 // Spawn a verified registered script with the executor identity, environment
 // allowlist and workspace confinement. No shell, model, prompt or native session.
 export const startScriptJob = async (
@@ -543,11 +576,27 @@ export const nativeSessionId = (cli: string, line: string): string | undefined =
   } catch {}
 }
 
-const terminating = new WeakSet<ChildProcess>()
-export const terminateJob = (child: ChildProcess, inspect = processSnapshot): void => {
-  if (!child.pid || child.exitCode !== null || child.signalCode !== null || terminating.has(child)) return
-  terminating.add(child)
-  void (async () => {
+const terminating = new WeakMap<ChildProcess, Promise<boolean>>()
+export const terminateJob = (child: ChildProcess, inspect = processSnapshot): Promise<boolean> => {
+  const pending = terminating.get(child)
+  if (pending) return pending
+  if (!child.pid || child.exitCode !== null || child.signalCode !== null) return Promise.resolve(true)
+  const work = (async () => {
+    const cancelFile = hostCancelFiles.get(child)
+    if (cancelFile) {
+      // The observer may still be loading, or unable to handle a signal. Commit
+      // the native worker's stop request before terminating that observer.
+      const temporary = cancelFile + '.' + process.pid + '.' + randomUUID() + '.tmp'
+      try {
+        await mkdir(path.dirname(cancelFile), { recursive: true, mode: 0o700 })
+        await writeFile(temporary, '', { mode: 0o600, flag: 'wx' })
+        await rename(temporary, cancelFile)
+      } catch (error) {
+        await rm(temporary, { force: true }).catch(() => {})
+        console.error('Cannot request host executor cancellation; observer remains active', error)
+        return false
+      }
+    }
     const targets = new Set([child.pid!])
     // Native tool terminals can start separate process groups. Capture ancestry
     // before stopping the CLI, while those children still have their parent.
@@ -575,5 +624,9 @@ export const terminateJob = (child: ChildProcess, inspect = processSnapshot): vo
       void processSnapshot().then(current => signal(matchingProcessIds(identities, current), 'SIGKILL'))
         .catch(error => console.error('Cannot inspect executor descendants for escalation', error))
     }, 3000)
+    return true
   })()
+  terminating.set(child, work)
+  void work.then(stopped => { if (!stopped) terminating.delete(child) })
+  return work
 }

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
@@ -38,7 +50,10 @@ try {
     // Drain completion first. A brief missing file at the shared-filesystem
     // boundary must not cancel a healthy job or hide its terminal result.
     try {
-      const heartbeat = JSON.parse(await readFile(path.join(directory,'heartbeat.json'),'utf8'))
+      const claimed = await stat(base+'.running.json').then(()=>true,error=>{if(error.code==='ENOENT')return false;throw error})
+      const heartbeat = claimed
+        ? {at:(await stat(base+'.events')).mtimeMs}
+        : JSON.parse(await readFile(path.join(directory,'heartbeat.json'),'utf8'))
       if (!Number.isFinite(heartbeat.at)) throw new Error('Invalid host CLI heartbeat')
       lastHeartbeat = heartbeat.at
     } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }