@jc_stack/ez-agents 0.1.0-beta.34 → 0.1.0-beta.36

package/docs/upgrades.md

@@ -16,9 +16,9 @@ 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
-queues an owner-bound maintenance turn only when an automatic channel changes.
-No owner means no maintenance executor. Normal user work and maintenance share
-one serial queue. Checks use the installed scoped npm identity; failures are
+records automatic-channel changes; discovery never wakes the agent or injects
+wrapper state into a session. Updates stay owner-invoked 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
 only, without querying public npm; this does not mean they are up to date.
@@ -144,7 +144,7 @@ rollback is a recovery operation for the previous installation only.
 queuing it.** It must not wait for completion in that same turn. The supervisor
 pauses new run admission, drains already-started work, then consumes the job.
 One job at a time; an unresolved recovery blocks new upgrades. The agent processes
-multiple requested packages over successive maintenance turns.
+multiple requested packages over successive update requests.
 
 The exact archive is reverified and re-extracted before execution; editing a
 prepared tree cannot substitute code. Main dependencies install with the frozen
@@ -164,24 +164,43 @@ running. Failed activation restores the previous code/configuration and checks i
 If recovery itself fails, inspect and fix the reported infrastructure problem,
 then use `ez updates recover <job-id>` and finish the turn. This retries only the
 saved code/configuration recovery, not provider operations.
-Completion or failure wakes the agent to inspect the receipt and report naturally.
+An update never wakes the agent or injects wrapper state into its session; the
+owner or agent inspects receipts with `ez updates` when asked.
 
 Backups contain credentials and must stay private. Main backups cover the
 canonical mind/control and deployment files. Plugins back up existing named
 volumes while their services are stopped, using the previous image's `tar` and
 read-only volume mounts; archive output is written by the host with mode 0600.
-No backup deletes live data or revokes credentials. Retain old package roots and
-images until QA and any recovery window are complete; there is no automatic GC.
+No backup deletes live data or revokes credentials. After a successful update, the
+supervisor retains the newest completed backup per target and removes backup
+directories from older terminal receipts (`completed`, `failed` or
+`rolled-back`). Queued, applying and recovery-required jobs are never pruned. Old
+package roots and images remain available until they are no longer needed for the
+active or immediate rollback path; backup cleanup does not remove them. A cleanup
+failure is recorded on the completed receipt and does not turn a successful
+update into a rollback. The supervisor repeats this reconciliation at startup so
+a release restart also cleans backups left by a crash window or by the release
+that installed the policy.
 
 The updater accepts only matching state-schema and protocol contracts and an
-unchanged deployment layout. Plugins may add command routes to existing services;
-existing routes and all services, privileges, volumes and other deployment
-configuration must remain unchanged. Incompatible changes fail before replacement,
-even for an explicit candidate, and need a separately reviewed migration rather
-than an override flag. Release authors must truthfully declare schema compatibility.
-Code rollback **does not rewind private
-state**, provider cursors or operation receipts; uncertain actions are never
-replayed. Docker health is not proof of live provider identity or delivery.
+unchanged effective deployment layout. The reviewed beta.34 runtime migration
+allows the optional empty `EZ_ISOLATION` passthrough and a changed purpose-file
+fallback when the deployment already binds `EZ_AGENT_PURPOSE_FILE`; the job
+receipt records that migration. Plugins may add command routes to existing
+services; existing routes and all services, privileges, volumes and other
+deployment configuration must remain unchanged. Incompatible changes fail
+before replacement, even for an explicit candidate, and need a separately
+reviewed migration rather than an override flag. Release authors must truthfully
+declare schema compatibility. Code rollback **does not rewind private state**,
+provider cursors or operation receipts; uncertain actions are never replayed.
+Docker health is not proof of live provider identity or delivery.
+
+The updater also records the exact Library beta14 command migration: it removes
+the retired `library-document` route and changes `library-query` from
+`query-context` to `search`, while requiring every other manifest and deployment
+field to remain unchanged. A completed main upgrade exits the active supervisor
+after publishing its receipt; the retained bootstrap is then restarted by the
+host service and loads the new package root.
 
 ## Contributor acceptance
 
@@ -214,12 +233,16 @@ policy selects non-deprecated stable versions, even when latest is a prerelease.
 No eligible version is reported as available:null with newer:false. Older installed
 updaters need an exact-version core update to adopt this discovery behavior.
 
-## Shared agent guidance
+## Operating-agent instructions
 
-Setup and runtime startup install `templates/agent-guidance.md` into a marked
-section of the workspace's native `AGENTS.md` (and existing `AGENTS.override.md`).
-Upgrade refreshes only that section; personal content outside it is preserved
-byte-for-byte. New scheduled task workspaces receive the same shared guidance.
+Setup and the main upgrade step strip any obsolete `<!-- ez shared guidance -->`
+handbook from workspace `AGENTS.md` (and existing `AGENTS.override.md`).
+Personal text outside that block is preserved byte-for-byte. Do not reinsert
+coding, KISS, contribution or repair loops into operating minds.
+
+The package-owned locator is the managed `<!-- ez tools -->` block: the bound
+`ez` launcher, `ez --help`, and `ez tools list --details`. Inventory is
+generated on read. Plugin registry init and update binding refresh that locator.
 Malformed markers and symlinks fail visibly rather than overwriting personal work.
 
 Codex, agy, Grok and OpenCode discover workspace instructions natively. Claude
@@ -236,9 +259,9 @@ preserved. Restricted contact tasks retain their separate
 bounded instruction scopes. For delivered busy replies absent from the native
 conversation, the owner engine can call `ezenciel-agents-schedule context`.
 
-Keep general defaults in the shipped shared file and identity/preferences in
-workspace personal files. Instructions cannot grant permissions; explicit owner
-requests take precedence within existing execution authority.
+Keep identity and purpose in the agent's own `AGENTS.md`. Instructions cannot
+grant permissions; explicit owner requests take precedence within existing
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jc_stack/ez-agents",
-  "version": "0.1.0-beta.34",
+  "version": "0.1.0-beta.36",
   "private": false,
   "type": "module",
   "description": "A lightweight foundation for persistent business AI assistants using existing AI harnesses, workspaces and plugins.",
@@ -21,8 +21,9 @@
     "ezenciel-agents-host": "bin/ezenciel-agents-host",
     "ezenciel-agents-tools": "bin/ezenciel-agents-tools.mjs",
     "ezenciel-agents-ai": "bin/ezenciel-agents-ai.mjs",
-    "ezenciel-agents-watch": "bin/ezenciel-agents-watch.mjs",
-    "ezenciel-agents-application": "bin/ezenciel-agents-application.mjs"
+    "ezenciel-agents-application": "bin/ezenciel-agents-application.mjs",
+    "ezenciel-agents-provision-telegram": "bin/ezenciel-agents-provision-telegram.mjs",
+    "ezenciel-agents-plugin-broker": "bin/ezenciel-agents-plugin-broker.mjs"
   },
   "files": [
     "default-plugins.json",
@@ -37,7 +38,6 @@
     "CONTRIBUTING.md",
     "Dockerfile",
     "compose.yaml",
-    "compose.workforce-watch.yaml",
     "docker",
     "compose.whatsapp.yaml",
     "scripts/smoke.ts",
@@ -61,7 +61,7 @@
   "scripts": {
     "setup": "tsx --env-file-if-exists=.env src/setup.ts",
     "dev": "EZ_DEVELOPMENT=1 tsx watch --clear-screen=false --exclude 'agent/**' --exclude 'test/**' --env-file=.env src/index.ts",
-    "start": "./bin/ezenciel-agents-docker up -d --wait relay",
+    "start": "./bin/ezenciel-agents-docker up -d --wait",
     "owner": "tsx --env-file=.env src/owner.ts",
     "message": "tsx src/message.ts",
     "react": "tsx src/react.ts",

package/scripts/smoke-scheduler.ts

@@ -7,6 +7,8 @@ import { createRelay } from '../src/index.js'
 import { ControlStore } from '../src/control-state.js'
 import { Scheduler } from '../src/scheduler.js'
 import { RunStore } from '../src/runs.js'
+import { serveDeliverySocket, createLedgerHandler } from '../src/delivery-socket.js'
+import { packageVersion } from '../src/version.js'
 import { initialPreset } from '../src/ai.js'
 import { initializeWorkspace } from '../src/workspace.js'
 import type { Update } from 'grammy/types'
@@ -22,6 +24,11 @@ await control.requestPairing(101,101);await control.approveOwner(101)
 const owner=(await control.status()).owner!,execution=await control.captureChoice(initialPreset(cli))
 const replies:{at:number;text:string}[]=[]
 const relay=createRelay({workspace,controlDir,pairingTtlMs:1000,executorTimeoutMs:0,executorCli:cli,telegramBotToken:'fixture'})
+// Engine children reach this process's memory ledger through the socket.
+const ledger=await serveDeliverySocket(controlDir,createLedgerHandler(controlDir,{
+ wake:()=>{void relay.drainOutbox()},
+ status:()=>({polling:false,applicationOnly:!relay.telegramEnabled,telegramConfigured:true,version:packageVersion}),
+}))
 relay.bot.botInfo={id:999,is_bot:true,first_name:'Fixture',username:'fixture_bot'} as typeof relay.bot.botInfo
 relay.bot.api.config.use(async(_previous,method,payload)=>{
  if(method==='sendMessage') {const reply={at:Date.now(),text:(payload as {text:string}).text};replies.push(reply);console.log(JSON.stringify({reply}))}
@@ -59,11 +66,11 @@ try{
  await relay.drainOutbox()
  const status=(await runs.get(background.id))?.status
  if(status!=='completed' || replies.filter(r=>r.text.includes('BACKGROUND_DONE')).length!==1)throw new Error('Missing completed run or exactly one delivered result')
- const finished=await readFile(join(workspace,'work/tasks',background.id,'finished.txt'),'utf8')
+ const finished=await readFile(join(controlDir,'work/tasks',background.id,'finished.txt'),'utf8')
  if(finished.trim()!=='DONE')throw new Error('Missing finished.txt artifact')
  if(nativeGoal){
   for(const [file,expected] of [['phase1.txt','ONE'],['phase2.txt','TWO']])
-   if((await readFile(join(workspace,'work/tasks',background.id,file),'utf8')).trim()!==expected)throw new Error(`Missing native goal artifact: ${file}`)
+   if((await readFile(join(controlDir,'work/tasks',background.id,file),'utf8')).trim()!==expected)throw new Error(`Missing native goal artifact: ${file}`)
  }
  const record=(await runs.get(background.id))!
  if(Date.parse(record.endedAt!)-Date.parse(record.startedAt!) < duration*1000)throw new Error('Worker completed before requested duration')
@@ -88,4 +95,4 @@ try{
  const evidence={duration,cli,nativeGoal,goalEvidence,status,replies,run:await runs.get(background.id)}
  await writeFile(join(root,'evidence.json'),JSON.stringify(evidence,null,2),{mode:0o600})
  console.log(JSON.stringify({passed:true,evidence:join(root,'evidence.json')}))
-}finally{clearInterval(tick);while(draining)await new Promise(r=>setTimeout(r,50));await relay.stop()}
+}finally{clearInterval(tick);while(draining)await new Promise(r=>setTimeout(r,50));await relay.stop();await ledger.stop()}

package/scripts/smoke.ts

@@ -1,12 +1,13 @@
 import { dirname, join } from 'node:path'
-import { readdir, readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { randomUUID } from 'node:crypto'
 import { loadConfig } from '../src/config.js'
 import { ControlStore } from '../src/control-state.js'
 import { startExecutorJob, terminateJob } from '../src/executor.js'
-import { RunStore } from '../src/runs.js'
+import { RunStore, sentOutbox } from '../src/runs.js'
 import { createRelay } from '../src/index.js'
+import { serveDeliverySocket, createLedgerHandler } from '../src/delivery-socket.js'
+import { packageVersion } from '../src/version.js'
 
 // Outbound integration test, not proof of Telegram intake or UI interactions.
 // Run while the polling relay is stopped; the owner must already be paired.
@@ -39,6 +40,11 @@ async function main() {
     texts: [prompt],
   })
   await runs.patch(run.id, { status: 'running', startedAt: new Date().toISOString() })
+  // The engine child reaches the smoke-process memory ledger through the socket.
+  const ledger = await serveDeliverySocket(config.controlDir, createLedgerHandler(config.controlDir, {
+    wake: () => { void relay.drainOutbox(run.id) },
+    status: () => ({ polling: false, applicationOnly: !relay.telegramEnabled, telegramConfigured: config.telegramBotToken !== '', version: packageVersion }),
+  }))
   const job = await startExecutorJob(run.texts, {
     workspace: config.workspace,
     timeoutMs: config.executorTimeoutMs,
@@ -72,18 +78,14 @@ async function main() {
       status: code === 0 ? 'completed' : 'failed',
       endedAt: new Date().toISOString(),
     })
-    const names = (await readdir(join(config.controlDir, 'outbox'))).filter((name) =>
-      name.startsWith(run.id + '_'),
-    )
-    const receipts = []
-    for (const name of names.filter((name) => name.endsWith('.sent.json'))) {
-      const item = JSON.parse(await readFile(join(config.controlDir, 'outbox', name), 'utf8'))
-      if (item.receipt) receipts.push(item.receipt)
-    }
+    const receipts = sentOutbox(config.controlDir)
+      .filter((item) => item.runId === run.id && item.receipt)
+      .map((item) => item.receipt)
+    const delivery = await runs.deliveryStatus()
     console.log(
       JSON.stringify({ runId: run.id, executor: config.executorCli, model: choice?.model, effort: choice?.effort, exitCode: code, receipts }, null, 2),
     )
-    if (code !== 0 || !receipts.length || names.some((name) => !name.endsWith('.sent.json'))) {
+    if (code !== 0 || !receipts.length || (await runs.pendingOutbox()).length || delivery.failed || delivery.unknown) {
       throw new Error('Smoke failed: executor failure, missing receipt, or undelivered outbox item')
     }
     console.log('Outbound smoke passed. Telegram intake and button/media UI still require a live chat test.')
@@ -93,6 +95,7 @@ async function main() {
     process.removeListener('SIGTERM', stop)
     await job.cleanup()
     await relay.stop()
+    await ledger.stop()
   }
 }
 

package/src/agent-guidance.ts

@@ -1,17 +1,12 @@
 import { lstat, readFile, rename, rm, writeFile } from 'node:fs/promises'
 import { randomUUID } from 'node:crypto'
 import path from 'node:path'
-import { readFileSync } from 'node:fs'
-
-// Resolve against the installed package, never the agent's editable workspace.
-export const agentGuidance = (): string =>
-  readFileSync(new URL('../templates/agent-guidance.md', import.meta.url), 'utf8').trim()
 
 const start = '<!-- ez shared guidance: begin -->'
 const end = '<!-- ez shared guidance: end -->'
 
-// Native instruction installation, refreshed at setup/runtime upgrade, not per turn.
-// Personal instructions outside this one managed block remain byte-for-byte intact.
+// Drop the obsolete package-owned handbook. Discovery lives in the managed
+// ez tools locator. Personal text outside the markers stays byte-for-byte.
 export async function installAgentGuidance(workspace: string): Promise<void> {
   for (const name of ['AGENTS.md', 'AGENTS.override.md']) {
     const file = path.join(workspace, name)
@@ -23,11 +18,13 @@ export async function installAgentGuidance(workspace: string): Promise<void> {
       if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue
       throw error
     }
-    const block = `${start}\n${agentGuidance()}\n${end}\n\n`
     const from = original.indexOf(start), to = original.indexOf(end)
     if ((from < 0) !== (to < 0) || (from >= 0 && (to < from || original.indexOf(start, from + start.length) >= 0 || original.indexOf(end, to + end.length) >= 0)))
       throw new Error(`Malformed shared guidance block: ${file}`)
-    const updated = from < 0 ? block + original : original.slice(0, from) + block.trimEnd() + original.slice(to + end.length)
+    if (from < 0) continue
+    let rest = original.slice(to + end.length)
+    if (from === 0 && rest.startsWith('\n')) rest = rest.slice(1)
+    const updated = original.slice(0, from) + rest
     if (updated === original) continue
     const temporary = `${file}.${randomUUID()}.tmp`
     try {

package/src/agent-install.ts

@@ -1,8 +1,11 @@
-import { mkdir, readFile, writeFile, rm, readdir } from 'node:fs/promises'
-import { isAbsolute, join, resolve, dirname } from 'node:path'
+import { chmod, mkdir, readFile, writeFile, rm, readdir } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
+import { isAbsolute, join, resolve, dirname, delimiter } from 'node:path'
 import { parseArgs } from 'node:util'
 import { executorKey } from './executor.js'
 import { isolationTransport, parseIsolationClass, type IsolationClass } from './isolation.js'
+import { ledgerOverlayName, ledgerOverlayYaml } from './ledger-endpoint.mjs'
+import { initializeWorkspace } from './workspace.js'
 import { fileURLToPath } from 'node:url'
 import { validateCodexProvider, type CodexProviderBinding } from './executor.js'
 
@@ -32,7 +35,7 @@ export const installationCli = async (root: string, installerCli?: string): Prom
 }
 
 export const createAgent = async (options: {
-  root: string; hostRoot: string; composeFile: string; name: string; purpose: string; token: string; cli?: string; image?: string; isolation?: string; codexProvider?: CodexProviderBinding
+  root: string; hostRoot: string; composeFile: string; name: string; purpose: string; token: string; cli?: string; image?: string; isolation?: string; codexProvider?: CodexProviderBinding; ledgerPort?: number
 }) => {
   const { root, hostRoot, composeFile, name, purpose, token } = options
   const requestedIsolation = options.isolation?.trim()
@@ -49,6 +52,11 @@ export const createAgent = async (options: {
   const isolation: IsolationClass = requestedIsolation ? parseIsolationClass(requestedIsolation) : cli === 'codex' ? 'isolated' : 'host-capable'
   if (isolation === 'isolated' && cli !== 'codex') throw new Error(`Isolated execution is unavailable for ${cli}; use host-capable isolation`)
   const transport = isolationTransport(isolation)
+  const ledgerPort = isolation === 'host-capable'
+    ? options.ledgerPort ?? 20000 + (createHash('sha256').update(name).digest().readUInt16BE(0) % 10000)
+    : undefined
+  if (isolation === 'host-capable' && (!Number.isSafeInteger(ledgerPort) || ledgerPort! < 1024 || ledgerPort! > 65535))
+    throw new Error('Host-capable agents require a free loopback ledger port for host CLI access')
   const codexProvider = options.codexProvider ? validateCodexProvider(options.codexProvider) : undefined
   if (codexProvider && cli !== 'codex') throw new Error('A Codex provider requires the Codex installation CLI')
   const directory = join(root, name), deploymentDir = join(hostRoot, name)
@@ -56,28 +64,41 @@ export const createAgent = async (options: {
   await mkdir(directory, {mode:0o700})
   try {
     const project = `ez-agent-${name}`
+    const ledgerOverlay = join(deploymentDir, ledgerOverlayName)
     const values = {
       COMPOSE_PROJECT_NAME: project,
-      COMPOSE_FILE: composeFile,
+      COMPOSE_FILE: [composeFile, ...(ledgerPort ? [ledgerOverlay] : [])].join(delimiter),
       EZ_RELAY_IMAGE: image,
       EZ_RELAY_ENV_FILE: join(deploymentDir, 'relay.env'),
       EZ_AGENT_PURPOSE_FILE: join(deploymentDir, 'purpose.md'),
       EZ_EXECUTOR_CLI: cli,
       EZ_ISOLATION: isolation,
       EZ_EXECUTOR_TRANSPORT: transport,
+      ...(ledgerPort ? { EZ_DELIVERY_TCP_PORT: String(ledgerPort) } : {}),
       ...(isolation === 'isolated' && cli === 'codex' ? { EZ_CODEX_SANDBOX: 'external' } : {}),
       EZ_AGENT_WORKSPACE: join(deploymentDir, 'mind'),
       EZ_CONTROL_DIR: join(deploymentDir, 'control'),
+      EZ_TOOLS_HOME: join(deploymentDir, 'tools'),
+      EZ_PLUGIN_BROKER_SOCKET: join(deploymentDir, 'control', 'plugin-broker.sock'),
+      EZ_PLUGIN_BROKER_HOST_CONFIG: join(deploymentDir, 'host-executor.json'),
+      ...(isolation === 'isolated' ? { COMPOSE_PROFILES: 'isolated' } : {}),
       EZ_WHATSAPP_IPC_VOLUME: `${project}-whatsapp-ipc`,
       EZ_WHATSAPP_CLIENT_VOLUME: `${project}-whatsapp-client`,
     }
     await writeFile(join(directory, 'docker.env'), Object.entries(values).map(([k,v]) => `${k}='${v}'\n`).join(''), {mode:0o600, flag:'wx'})
+    if (ledgerPort) await writeFile(join(directory, ledgerOverlayName), ledgerOverlayYaml(), {mode:0o600, flag:'wx'})
     await writeFile(join(directory, 'relay.env'), `TELEGRAM_BOT_TOKEN=${token}\n`, {mode:0o600, flag:'wx'})
     await writeFile(join(directory, 'purpose.md'), purpose.trim()+'\n', {mode:0o644, flag:'wx'})
     await mkdir(join(directory,'mind'),{mode:0o700})
+    // Install-time seed: the relay never writes the workspace at startup.
+    // Readable beyond the installer UID so a mismatched runtime UID still
+    // loads its own purpose; the 0700 deployment directory keeps it private.
+    const seeded = await initializeWorkspace(join(directory,'mind'), join(directory,'purpose.md'))
+    if (seeded.includes('AGENTS.md')) await chmod(join(directory,'mind','AGENTS.md'), 0o644)
     await mkdir(join(directory,'control'),{mode:0o700})
+    await mkdir(join(directory,'tools'),{mode:0o700})
     const agent = {name, project, deploymentDir, purpose:purpose.trim(), executor:cli, isolation}
-    const host = {cli,isolation,agents:[{name,workspace:join(deploymentDir,'mind'),controlDir:join(deploymentDir,'control'),binDir:join(dirname(composeFile),'bin'),...(codexProvider?{codexProviders:[codexProvider]}:{})}]}
+    const host = {cli,isolation,agents:[{name,workspace:join(deploymentDir,'mind'),controlDir:join(deploymentDir,'control'),binDir:join(dirname(composeFile),'bin'),...(isolation === 'isolated' ? {toolsHome:join(deploymentDir,'tools')} : {}),...(codexProvider?{codexProviders:[codexProvider]}:{})}]}
     await writeFile(join(directory,'host-executor.json'),JSON.stringify(host,null,2)+'\n',{mode:0o600,flag:'wx'})
     await writeFile(join(directory, 'agent.json'), JSON.stringify(agent,null,2)+'\n', {mode:0o600, flag:'wx'})
     return agent
@@ -96,7 +117,7 @@ export const listAgents = async (root: string) => {
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   try {
-    const {values:v} = parseArgs({options:{name:{type:'string'},purpose:{type:'string'},isolation:{type:'string'},'host-root':{type:'string'},'compose-file':{type:'string'},'relay-image':{type:'string'},list:{type:'boolean'},cli:{type:'string'},'register-cli':{type:'string'},'codex-provider':{type:'string'},'codex-provider-name':{type:'string'},'codex-base-url':{type:'string'},'codex-env-key':{type:'string'},'codex-model':{type:'string',multiple:true}}})
+    const {values:v} = parseArgs({options:{name:{type:'string'},purpose:{type:'string'},isolation:{type:'string'},'host-root':{type:'string'},'compose-file':{type:'string'},'relay-image':{type:'string'},'ledger-port':{type:'string'},list:{type:'boolean'},cli:{type:'string'},'register-cli':{type:'string'},'codex-provider':{type:'string'},'codex-provider-name':{type:'string'},'codex-base-url':{type:'string'},'codex-env-key':{type:'string'},'codex-model':{type:'string',multiple:true}}})
     if (v['register-cli']) console.log(JSON.stringify({cli:await installationCli('/installations',v['register-cli'])}))
     else if (v.list) console.log(JSON.stringify(await listAgents('/installations')))
     else {
@@ -104,7 +125,7 @@ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.ur
       for await (const chunk of process.stdin) { token+=chunk; if(token.length>512) throw new Error('Token input is too long.') }
       const providerValues=[v['codex-provider'],v['codex-provider-name'],v['codex-base-url'],v['codex-env-key'],v['codex-model']]
       const codexProvider=providerValues.some(Boolean)?validateCodexProvider({id:v['codex-provider']||'',name:v['codex-provider-name']||v['codex-provider']||'',baseUrl:v['codex-base-url']||'',envKey:v['codex-env-key']||'',models:v['codex-model']||[]}):undefined
-      console.log(JSON.stringify(await createAgent({root:'/installations',hostRoot:v['host-root']||'',composeFile:v['compose-file']||'',name:v.name||'',purpose:v.purpose||'',token:token.trim(),cli:v.cli||'',image:v['relay-image'],isolation:v.isolation,codexProvider})))
+      console.log(JSON.stringify(await createAgent({root:'/installations',hostRoot:v['host-root']||'',composeFile:v['compose-file']||'',name:v.name||'',purpose:v.purpose||'',token:token.trim(),cli:v.cli||'',image:v['relay-image'],isolation:v.isolation,codexProvider,ledgerPort:v['ledger-port']===undefined?undefined:Number(v['ledger-port'])})))
     }
   } catch (error) { console.error((error as Error).message); process.exitCode=1 }
 }

package/src/application-channel.ts

@@ -2,7 +2,7 @@ import { createServer, type Server, type IncomingMessage, type ServerResponse }
 import { createHash, randomUUID, timingSafeEqual } from 'node:crypto'
 import { mkdir, readFile, writeFile, rename, open, unlink } from 'node:fs/promises'
 import { join } from 'node:path'
-import { ControlStore, sessionTitle, type ControlGuard, type Owner, sameOwner, validOwner, ownerId, ownerEpoch } from './control-state.js'
+import { ControlStore, sessionTitle, telegramOwner, type ControlGuard, type Owner, 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'
@@ -74,6 +74,8 @@ export class ApplicationChannel {
     controlDir: string; workspace?: string; initial: AiPreset
     wake: () => void
     cancel: (id: string) => Promise<void>
+    createTelegramPairing?: (bindingId: string, owner: Owner) => Promise<{ connected: true } | { connected: false; url: string; expiresAt: string }>
+    telegramAvailable?: () => boolean
     aiControls?: {
       catalog: () => Promise<ModelChoice[]>
       select: (preset: AiPreset, expectedSession: string | null, guard?: ControlGuard) => Promise<unknown>
@@ -88,6 +90,29 @@ export class ApplicationChannel {
     if (!binding || (shared && !binding.shareTelegram) || !sameOwner(binding.owner, state.owner)) throw new Error('Application authority does not permit controls')
     return binding.owner
   }
+  private async telegramConnection(bindingId: string) {
+    await this.sharedBinding(bindingId)
+    const owner = (await new ControlStore(this.options.controlDir, 900000).status()).owner
+    const connected = Boolean(telegramOwner(owner))
+    return this.options.telegramAvailable
+      ? { connected, ready: this.options.telegramAvailable() }
+      : { connected }
+  }
+  private async createTelegramConnection(bindingId: string) {
+    const owner = await this.sharedBinding(bindingId)
+    const current = (await new ControlStore(this.options.controlDir, 900000).status()).owner
+    if (telegramOwner(current)) return { connected: true } as const
+    if (!this.options.createTelegramPairing) throw new Error('Telegram connection is unavailable')
+    return this.options.createTelegramPairing(bindingId, owner)
+  }
+  async claimTelegramConnection(token: string, telegramUserId: number, telegramChatId: number): Promise<boolean> {
+    const control = new ControlStore(this.options.controlDir, 900000)
+    const owner = await control.claimApplicationTelegramPairing(token, telegramUserId, telegramChatId, async (bindingId, expectedOwner) => {
+      const binding = (await this.bindings.list()).find(item => item.bindingId === bindingId)
+      return Boolean(binding?.shareTelegram && sameOwner(binding.owner, expectedOwner))
+    })
+    return Boolean(owner)
+  }
   async controls(bindingId: string) {
     await this.sharedBinding(bindingId)
     if (!this.options.aiControls) throw new Error('Application controls unavailable')
@@ -233,8 +258,8 @@ export class ApplicationChannel {
       }
       const control = new ControlStore(this.options.controlDir, 900000)
       if (!sameOwner(binding.owner, (await control.status()).owner)) throw new Error('Application authority revoked')
-      if (bytes && !this.options.workspace) throw new Error('Invalid application attachment: workspace unavailable')
-      const staged = bytes ? await stageChatAttachment(this.options.workspace!, value.attachment!.name as string, bytes, value.text) : undefined
+      if (bytes && !this.options.controlDir) throw new Error('Invalid application attachment: control unavailable')
+      const staged = bytes ? await stageChatAttachment(this.options.controlDir, value.attachment!.name as string, bytes, value.text) : undefined
       let run: RunRecord
       try {
       const execution = value.followTelegram ? await control.captureChoice(this.options.initial) : await control.captureApplicationChoice(this.options.initial, applicationScope(bindingId, value.scope), binding.shareTelegram === true && value.activateTelegram === true, requestedPreset, value.expectedNativeSessionId as string | undefined)
@@ -270,13 +295,33 @@ export class ApplicationChannel {
       if (request.method === 'GET' && path === '/v1/registration') {
         send(200, {ownerId: ownerId(binding.owner), bindingId: binding.bindingId, channel: binding.id}); return
       }
+      if (path === '/v1/telegram' && request.method === 'GET') {
+        if ([...url.searchParams.keys()].length) throw new Error('Invalid application Telegram request')
+        if (!binding.shareTelegram) { send(403, { error: 'Application authority does not permit Telegram connection' }); return }
+        send(200, await this.telegramConnection(binding.bindingId)); return
+      }
+      if (path === '/v1/telegram/link' && request.method === 'POST') {
+        const chunks: Buffer[] = []; let size = 0
+        for await (const chunk of request) { size += chunk.length; if (size > 1024) throw new Error('Invalid application Telegram request'); chunks.push(chunk) }
+        if (Buffer.concat(chunks).toString('utf8').trim()) throw new Error('Invalid application Telegram request')
+        if (!binding.shareTelegram) { send(403, { error: 'Application authority does not permit Telegram connection' }); return }
+        send(200, await this.createTelegramConnection(binding.bindingId)); return
+      }
       if (request.method === 'GET' && path === '/v1/runs') {
-        const all = (await this.runs.list()).filter(run => (run.application ?? run.delivery)?.bindingId === binding.bindingId)
+        const owned = await this.runs.list()
+        const all = owned.filter(run => (run.application ?? run.delivery)?.bindingId === binding.bindingId)
+        const currentOwner = binding.shareTelegram ? telegramOwner((await new ControlStore(this.options.controlDir, 900000).status()).owner) : null
+        const telegram = currentOwner
+          ? owned.filter(run => run.application === undefined && run.delivery === undefined && run.taskId === undefined && run.external === undefined && run.scheduled === undefined && run.telegramUserId === currentOwner.telegramUserId && run.ownerId === ownerId(currentOwner) && run.ownerEpoch === ownerEpoch(currentOwner) && (run.telegramApplication === undefined || run.telegramApplication.bindingId === binding.bindingId) && !all.some(item => item.id === run.id))
+          : []
+        const visible = [...all, ...telegram]
         const before = url.searchParams.get('before')
-        const end = before ? all.findIndex(run => run.id === before) : all.length
+        const end = before ? visible.findIndex(run => run.id === before) : visible.length
         if (end < 0) throw new Error('Invalid application inbox cursor')
-        const records = all.slice(Math.max(0,end-100),end)
-        send(200, {runs: await Promise.all(records.map(run => this.snapshot(binding.bindingId, run.id))), nextCursor:end>100?records[0].id:null}); return
+        const records = visible.slice(Math.max(0,end-100),end)
+        send(200, {runs: await Promise.all(records.map(run => (run.application ?? run.delivery)
+          ? this.snapshot(binding.bindingId, run.id)
+          : Promise.resolve({id: run.id, scope: 'telegram', status: run.status, texts: run.texts, telegramUserId: run.telegramUserId, createdAt: run.createdAt}))), nextCursor:end>100?records[0].id:null}); return
       }
       if (path==='/v1/scope-control' && ['GET','POST'].includes(request.method ?? '')) {
         const scope = url.searchParams.get('scope')
@@ -314,6 +359,32 @@ export class ApplicationChannel {
         if(!await new Tasks(this.options.controlDir).decide(approvalMatch[1]))throw new Error('Unknown application approval')
         send(200,{id:approvalMatch[1],decision:input.decision});return
       }
+      const attachMatch = path.match(/^\/v1\/runs\/([A-Za-z0-9_-]{1,160})\/application$/)
+      if (attachMatch && request.method === 'POST') {
+        if (!binding.shareTelegram) { send(403, { error: 'Application authority does not permit Telegram admission' }); return }
+        const chunks: Buffer[] = []; let size = 0
+        for await (const chunk of request) { size += chunk.length; if (size > 65536) throw new Error('Invalid application admission size'); chunks.push(chunk) }
+        const input = JSON.parse(Buffer.concat(chunks).toString('utf8')) as { context?: unknown; scope?: unknown }
+        if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).some(key => key !== 'context' && key !== 'scope')) throw new Error('Invalid application admission')
+        const scope = input.scope === undefined ? 'telegram' : input.scope
+        if (typeof scope !== 'string') throw new Error('Invalid application admission')
+        const target = await this.runs.get(attachMatch[1])
+        if (target?.telegramApplication?.bindingId === binding.bindingId) {
+          const same = target.telegramApplication.scope === scope &&
+            JSON.stringify(target.telegramApplication.context ?? null) === JSON.stringify(input.context ?? null)
+          if (same) { send(200, { id: target.id, scope: target.telegramApplication.scope, status: target.status }); return }
+          throw new Error('Application admission conflicts with prior context')
+        }
+        if (!target || target.application || target.telegramApplication || target.taskId || target.external || target.scheduled || target.telegramUserId === undefined) throw new Error('Unknown application run')
+        const state = await new ControlStore(this.options.controlDir, 900000).status()
+        const linked = telegramOwner(state.owner)
+        if (!linked || target.telegramUserId !== linked.telegramUserId || !sameOwner(binding.owner, state.owner)) throw new Error('Application authority does not permit Telegram admission')
+        if (target.status !== 'queued' && target.status !== 'running') throw new Error('Application admission conflicts with finished run')
+        const application = { bindingId: binding.bindingId, scope, requestId: target.id, context: input.context as Record<string, unknown> }
+        if (!validApplicationOrigin(application)) throw new Error('Invalid application admission')
+        const admitted = await this.runs.attachTelegramApplication(target.id, application)
+        send(200, { id: admitted.id, scope, status: admitted.status }); 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/application-cli.ts

@@ -1,6 +1,6 @@
 import { parseArgs } from 'node:util'
 import { readFile } from 'node:fs/promises'
-import { loadControlConfig } from './config.js'
+import { loadControlConfig, telegramToken } from './config.js'
 import { ControlStore, sameOwner, ownerId } from './control-state.js'
 import { ApplicationBindings, applicationScope, validateApplicationRegistration } from './application-channel.js'
 import { initialPreset } from './ai.js'
@@ -17,7 +17,7 @@ async function main() {
   const config = loadControlConfig(), control = new ControlStore(config.controlDir, config.pairingTtlMs)
   if (values.owner && values['owner-id']) throw new Error('Choose one owner registration form')
   if (values['owner-id'] && (!values.id || !values['token-file'] || values.revoke || values.list || values['import-scope'])) throw new Error('--owner-id requires channel registration')
-  if (values.owner && (process.env.EZ_TELEGRAM_ENABLED !== 'false' || !values.id || !values['token-file'] || values.revoke || values.list || values['import-scope'])) throw new Error('--owner bootstrap requires explicit application-only registration')
+  if (values.owner && (telegramToken(process.env) || !values.id || !values['token-file'] || values.revoke || values.list || values['import-scope'])) throw new Error('--owner bootstrap requires an agent without a Telegram bot')
   const registrationToken = values['token-file'] ? (await readFile(values['token-file'], 'utf8')).trim() : null
   if (values.owner || values['owner-id']) validateApplicationRegistration(values.id!, registrationToken)
   const owner = values['owner-id'] ? await control.registerOwner(values['owner-id']) : values.owner ? await control.bootstrapApplicationOwner(Number(values.owner)) : (await control.status()).owner

package/src/approval-cli.ts

@@ -1,6 +1,5 @@
 import { loadControlConfig } from './config.js'
-import { ApprovalStore } from './approval.js'
-import { RunStore } from './runs.js'
+import { callDeliverySocket, socketPathFor } from './delivery-socket.js'
 
 const args = process.argv.slice(2).filter((arg) => arg !== '--')
 if (args.includes('--help') || args.includes('-h')) {
@@ -27,10 +26,12 @@ for (let i = 0; i < args.length; i++) {
 }
 
 const config = loadControlConfig()
-const approvalStore = new ApprovalStore(config.controlDir)
+const socketPath = socketPathFor(config.controlDir)
 
 if (checkId) {
-  const record = await approvalStore.getDecision(checkId)
+  const record = await callDeliverySocket(socketPath, { op: 'approvalCheck', payload: { actionId: checkId } }) as {
+    actionId: string; decision: string; decidedAt?: string; decidedBy?: number
+  }
   console.log(JSON.stringify({
     ok: true,
     actionId: checkId,
@@ -53,7 +54,13 @@ if (!runId) {
   process.exit(1)
 }
 
-const runStore = new RunStore(config.controlDir)
-await approvalStore.requestApproval(actionId, prompt, runId)
-const item = await runStore.enqueueApproval(runId, prompt, actionId, { replyToMessageId: replyTo })
+// The relay records the approval request and delivers its card; the decision
+// arrives later through Telegram and is read back with --check.
+const item = await callDeliverySocket(socketPath, {
+  op: 'enqueue',
+  payload: {
+    kind: 'approval', runId, approvalPrompt: prompt, approvalActionId: actionId,
+    ...(replyTo !== undefined ? { replyToMessageId: replyTo } : {}),
+  },
+}) as { outbox_id: string; id: string }
 console.log(JSON.stringify({ ok: true, run: runId, actionId, outbox_id: item.id, status: 'requested' }))