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

package/docs/releasing.md

@@ -77,7 +77,20 @@ read back `npm view @jc_stack/ez-agents@0.1.0-beta.12 name version dist-tags --j
 contents/checksum against the reviewed artifact. Keep the npm artifact and
 GitHub tag on the same reviewed commit. Do not create a new token to bypass 2FA.
 
+Source-checkout images for a deployment are RC builds of the unreleased commit:
+`ezenciel-agents-install build --label X.Y.Z-beta.N.rc.M` (increasing `.rc.N`)
+from the clean reviewed commit after the PR is open. The label and commit SHA are
+baked into the image; `/status` shows the RC tag first. Never install an
+unlabeled source build or reuse an RC label for different contents.
+
 ## Agent-owned upgrades
 
 This beta includes owner-policy release checks and durable
 main/plugin replacement. See [upgrade setup, tools and recovery](upgrades.md). Earlier main upgrade/rollback VM QA passed; final-release fresh-host/reboot and live plugin upgrade acceptance remain pending.
+
+Automatic main upgrades are gated on deployment compatibility: the candidate's
+`compose.yaml` and `compose.whatsapp.yaml` must match the release the agent
+already runs, or that installed release must carry the reviewed migration.
+Before publishing a release, confirm no compose change slipped in since the
+previous tag; otherwise bootstrap the agents or ship the migration in the
+release they already run.

package/docs/responsive-channels.md

@@ -15,4 +15,4 @@ Authorization, sandboxing and tool handlers enforce contact and lifecycle limits
 An owner-approved channel capability adds only a fixed installed alias declared
 as a read-only channel query; it does not expose the workspace, shell, owner
 session or other installed tools.
-Maintenance and group notifications carry event data; CLI help owns operations.
+Group notifications carry event data; CLI help owns operations.

package/docs/scheduling.md

@@ -94,10 +94,10 @@ queued occurrence; already-running work continues until explicitly cancelled.
 
 `/stop` stops all active work; `cancel RUN_ID` stops one background task. `/cancel`
 clears queued work. Pause/remove a recurring schedule to prevent future runs.
-Stopping the relay also stops its workers. A crashed or interrupted execution is
-not automatically replayed. Status labels failed runs as history and shows recent reasons; new failures retain their exit code or interruption cause. Typing indicators stop after 30 seconds even when work continues. Runs found active at startup are marked failed with
-`interrupted: true`; their schedule revision stays held until the agent inspects
-the evidence and explicitly edits the schedule. Inspect the task's files, native session and delivery
+Stopping the relay also stops its workers. Run and delivery records are relay
+memory: a process restart drops in-flight runs and queued deliveries by design,
+so the next eligible occurrence dispatches normally and nothing is replayed from
+disk. Status labels failed runs as history and shows recent reasons; new failures retain their exit code or interruption cause. Typing indicators stop after 30 seconds even when work continues. A failed run that cannot prove whether an external side effect happened stays visible until the agent inspects the evidence and explicitly edits the schedule. Inspect the task's files, native session and delivery
 receipts before deciding whether to resume. A clock cannot reconstruct an
 in-flight process or prove whether an external side effect happened.
 

package/docs/setup.md

@@ -125,6 +125,8 @@ pnpm install --frozen-lockfile
 export PATH="$PWD/bin:$PATH"
 export EZ_AGENTS_HOME=/absolute/private/agents
 node bin/ezenciel-agents-install build
+# Source checkout only: commit, open the PR, then build
+# node bin/ezenciel-agents-install build --label X.Y.Z-beta.N.rc.M
 # Set EZ_RELAY_IMAGE to the exact image returned by build for create/start.
 export EZ_RELAY_IMAGE='<returned-image>'
 ```
@@ -132,7 +134,10 @@ export EZ_RELAY_IMAGE='<returned-image>'
 Node 22+ and pnpm 10.30.3 are needed by the host transport. The tarball carries
 its lockfile under docker/ because npm excludes the root pnpm lockfile. Do not
 move this package directory after binding a service to its absolute paths.
-For a source checkout the root lockfile is already present. Do not run a second
+For a source checkout the root lockfile is already present. A source checkout is
+an RC: commit and open the PR first, then `build --label X.Y.Z-beta.N.rc.M`; the
+command refuses a dirty tree and bakes the RC tag and commit into the image so
+`/status` never reports the bare package version. Do not run a second
 copy of an existing bot token. Continue with the per-agent configuration below.
 
 Verify the tarball against its adjacent `.sha256` or the kit's `SHA256SUMS` before
@@ -270,8 +275,9 @@ the plugin skill through onboarding and verified use under that same request.
 Never silently reuse a global `ez` from the old sandbox runtime.
 
 4. Isolated agents skip host transport. Run `bin/ezenciel-agents-docker up -d --wait`
-   from the deployment directory. Do not register `ezenciel-agents-host` for them;
-   starting it fails closed.
+   from the deployment directory. This starts the local relay and its per-agent
+   isolated plugin broker; do not narrow the command to `relay`. Do not register
+   `ezenciel-agents-host` for them; starting it fails closed.
 
    Host-capable agents follow [host startup templates](host-service.md). Register
    `bin/ezenciel-agents-host` with the host's native service manager, binding
@@ -330,9 +336,9 @@ default. Existing queued jobs retain their captured execution choice.
 | Symptom | Inspect and recover |
 |---|---|
 | Docker unavailable | Check engine and Compose, start the supported installation; complete any required OS consent. |
-| Bot stays silent | Check pending owner identity, relay health, host heartbeat (host-capable only) and outbox; approve only the verified owner. |
+| Bot stays silent | Check pending owner identity, relay health, host heartbeat (host-capable only) and delivery receipts; approve only the verified owner. |
 | CLI exits without reply | Inspect the actual tool result and delivery receipt; stdout is not Telegram output. |
-| Exit 73 | An existing writer holds this deployment; stop the exact duplicate, never delete the kernel lock. |
+| Second relay refuses to start | A live relay already owns this deployment's delivery socket; stop the exact duplicate, never remove a live socket. |
 | Plugin absent | Check the bound catalog and install/start the reviewed package explicitly; no plugin ships by default. |
 | Plugin revision mismatch | Reinspect stable source, review the changed hash and explicitly update its catalog pin. |
 | Interrupted CLI cannot resume | Use the explicit new-conversation command after inspecting the failure; no automatic fallback. |

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.37",
   "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/ai-cli.ts

@@ -12,7 +12,7 @@ if(values.help){
 }
 if (!process.env.EZ_CONTROL_DIR) throw new Error('Use this agent’s bound control directory')
 const catalog=await readFile(join(process.env.EZ_CONTROL_DIR,'host-executor','models.json'),'utf8')
-  .then(text=>JSON.parse(text)).catch(()=>readModels(undefined,undefined,join(process.env.EZ_CONTROL_DIR!,'cli','codex')))
+  .then(text=>JSON.parse(text)).catch(()=>readModels(undefined,undefined,join(process.env.EZ_CONTROL_DIR!,'cli','codex'),undefined,undefined,undefined,process.env.EZ_CONTROL_DIR))
 if(positionals[0]==='list')console.log(JSON.stringify(catalog))
 else if(positionals[0]==='select'){
   const preset:AiPreset={id:randomBytes(8).toString('hex'),name:[values.provider,values.model||values.cli,values.effort].filter(Boolean).join(' · '),cli:values.cli||'',provider:values.provider,model:values.model,effort:values.effort}