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

package/AGENTS.md

@@ -16,11 +16,13 @@ through one generic transport, with separate agent workspaces and sessions.
 
 ## Operating-agent instructions
 
-Do not inject a coding handbook into production agent minds. The package-owned
-workspace locator is the managed `<!-- ez tools -->` block: the bound `ez`
-launcher, `ez --help`, and `ez tools list --details`. Inventory is generated on
-read; do not hardcode command recipes. Purpose lives in that agent's own
-`AGENTS.md`. Coding defaults for this repository stay in this file and
+Do not inject a coding handbook into production agent minds. The only
+package-written `AGENTS.md` text is the initial workspace seed: purpose, a short
+engine-neutral `memory/` note and one static line pointing at
+`ez tools list --details`. After seeding the agent owns `AGENTS.md`; inventory is
+generated on read, so do not hardcode command recipes. The one transport-level
+lifecycle prompt is the silent conversation-close turn (`src/session-close.ts`),
+which runs only for owner conversations. Coding defaults for this repository stay in this file and
 CONTRIBUTING.md.
 
 ## Installing this package
@@ -105,7 +107,7 @@ If no answer identifies a material blocker, finish. Do not start another review
 round merely to seek more criticism, tests or hypothetical edge cases.
 
 ## 3. Crash-Safe Disk State
-- Persistent authority state (`ControlStore` owner/pairing/sessions/presets, application bindings, schedule definitions) stays in disk-backed JSON files. Run/outbox/inbox bookkeeping is relay memory reached through the delivery socket (`src/delivery-socket.ts`): a restart drops in-flight runs and queued deliveries by design, uncertain sends report unknown rather than success, and Telegram redelivery is the replay mechanism. The live delivery socket also replaces the relay flock as the single-relay guard.
+- Persistent authority state (`ControlStore` owner/pairing/sessions/presets, application bindings, schedule definitions) stays in disk-backed JSON files. Run/outbox/inbox bookkeeping is relay memory reached through the delivery socket (`src/delivery-socket.ts`): a restart drops in-flight runs and queued deliveries by design, uncertain sends report unknown rather than success, and Telegram redelivery is the replay mechanism. The one exception: a graceful stop hands running host-transport runs, whose executors outlive the relay, to the next relay through private `control/run-handoff.json`; that relay adopts and watches them and never relaunches one. The live delivery socket also replaces the relay flock as the single-relay guard.
 - **Atomic write pattern:** Never write directly to a state file. Always write to a temporary file (`${target}.${process.pid}.tmp`) with mode `0o600`, then atomically `rename` it over the destination.
 - **Path sanitization:** Every ID parameter (`runId`, `outboxId`, `pairingId`) must be validated against `/^[a-zA-Z0-9_-]+$/` before being joined into paths. Never allow directory traversal (`..`).
 

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.1.0-beta.51
+
+- Keep native runs alive during handoff-compatible core upgrades. The retiring executor finishes existing work while its replacement accepts new requests; the relay adopts runs without replay and preserves schedule holds, cancellation and settled delivery receipts. Isolated agents migrate once while idle to a separate, unprivileged executor container; later compatible upgrades preserve its running generation. Older runtimes without the handoff contract retain the full native-work drain.
+- Prepare compatible-upgrade workspace and native-client backups before pausing admission or stopping the relay, so large histories do not extend the swap outage. Rollback restores code and configuration without rewinding active native state.
+- Make stop requests reach handed-off native work even while its observer is starting. A failed cancellation write leaves the observer active and reports the failed stop request.
+- Show paused schedules in `/tasks` and task details with a paused label and no next run. Editing a paused schedule keeps it paused.
+- Replace the oldest unused saved AI choice when the saved-choice limit is reached, preserving the selected, default and recently used choices.
+- Use the isolated native client's own catalog for AI selection, so available models such as Sonnet appear without relying on a host catalog.
+
+Beta limits: live fresh-host/reboot acceptance and live compatible upgrades during active native work on the VM and Mac remain pending. Synthetic container lifecycle checks and an idle EzStocks OVH private-candidate upgrade passed; these do not establish live active-run or provider acceptance. Publication does not establish an installed-agent upgrade or authorize provider/domain writes.
+
+## 0.1.0-beta.50
+
+- Share memory across engines through the workspace. New workspaces seed a short `## Memory` note (durable facts in `memory/`, one per file, indexed in `memory/MEMORY.md`); every engine loads `AGENTS.md`, so Codex and Claude read the same files. When a chat conversation is replaced (`/new`, the New button, web app new, or an AI/provider switch), its engine gets one silent turn in that native session to save durable facts; nothing is delivered and the engine decides what to write.
+- Drop the managed `<!-- ez tools -->` AGENTS.md footer. The install seed writes one static line ("Tools: run `ez tools list --details`; each plugin's `--help` gives usage."); update binding replaces an existing footer with that line once and otherwise never writes instructions. `ez tools list --details` now prints per plugin `aliases`, `purpose`, `skills`, `skillReads` and one `example` call (optional manifest `example`, else `<alias> --help`).
+- Stop reporting a live plugin call as a stale lease on isolated agents. Leases record their PID namespace; a lease written in the broker container is judged by its call container's running state, so `ez updates apply` no longer refuses during in-flight calls. Apply and recover only queue the job; main activation now drains in-flight calls before switching instead of failing.
+- Keep host-capable native runs alive across a graceful relay restart. The stopping relay hands running host-transport runs to the next relay instead of cancelling them; it adopts and watches each run with its schedule hold, concurrency slot and message delivery, and records its exit status. Nothing is relaunched; a run that cannot be adopted or whose outcome is unknown is recorded failed and interrupted, holding its schedule, and a run that fails adoption is asked to stop. Core upgrades still wait for idle native work; isolated agents, crashes and queued work keep the previous behavior.
+- Continue a scheduled occurrence on its next saved login when Claude stops at a usage/session limit after work began. The next setup starts a fresh native session with the saved prompt plus one factual line naming the run, stopped setup, its native session and reset time. Only a typed quota rejection the run ended on continues; work after a limit, access denial, other failures, cancellation and unknown outcomes still stop without replay. Attempts record `quota-after-work-began` and each Ez-assigned session ID.
+- Stop isolated plugin calls hanging silently before reaching the broker when the caller leaves a socket stdin open (native engine shells, async Node spawns). Pipes and files are still read to EOF; a socket that sends nothing for one second is treated as no input. Remove a uniquely named call container whenever Compose exits non-zero, so a call that stops between create and start no longer strands it in `Created`.
+- Advance scheduled work to its next saved login after a typed authentication rejection before work. Recognize Claude API-error metadata without marking analysis started; account/organization denials, hooks, model/tool work and uncertain outcomes still stop fallback. Preserve the saved chain for the next occurrence.
+- Let scheduled fallback setups name an owner-provisioned native login profile per setup, with no fixed list length. A quota rejection skips later setups on the same login profile while other accounts stay eligible; model/tool/hook work, access denial, cancellation and uncertain failures still stop the chain.
+- Show each scheduled task's frequency and full primary → fallback path (CLI, login profile, provider, model, effort) in Telegram `/tasks` and `/tasks N`.
+- Report the exact AI selection error (missing client models, missing model, unsupported effort) instead of a generic invalid selection, without changing the saved choice.
+
+Beta limits: live fresh-host/reboot acceptance, a live host-capable relay recreate during a running native run, two-real-account channel switching and real exhausted-account/provider rejection remain pending. An adopted scheduled occurrence does not advance to fallback setups, and messages a run sends while no relay is up still fail. The conversation close turn is engine-decided and runs only for owner conversations; existing workspaces do not receive the `## Memory` seed note automatically. Plugin manifests may declare `example`; a plugin that does requires core 0.1.0-beta.50 or newer, and older cores refuse that plugin update (manifest validation) and keep the installed version until core upgrades. Publication does not establish an installed-agent upgrade or authorize provider/domain writes.
+
 ## 0.1.0-beta.49
 
 - Upgrade compatible plugins while native work continues, draining in-flight plugin calls for activation and preserving rollback. Core updates still wait for idle.

package/README.md

@@ -172,7 +172,8 @@ transport, with separate agent workspaces and sessions. See
 
 Telegram `/status` shows the running relay and host versions plus installed
 plugin versions. Its read-only **Scheduled tasks** control lists the paired
-owner's active schedules in alphabetical order, with their engine/model/effort,
+owner's active schedules in alphabetical order, with their frequency/timezone
+and ordered CLI/login-profile/model/effort execution path (primary → fallbacks),
 next occurrence or current queued/running state, and a short preview of the
 saved invocation prompt; it never creates, changes or runs a task. The agent's `ez status` adds verified plugin
 runtime states and upgrade job receipts. See [status and upgrades](docs/upgrades.md).
@@ -260,11 +261,14 @@ restart and shutdown. Host-capable agents register the small host CLI transport
 
 The selected host CLI runs in this agent's persistent workspace and owns its
 Markdown/work files. New conversations and AI changes preserve those files.
-One compact `AGENTS.md` is seeded with the installer purpose; `MEMORY.md` is
-optional. The installing LLM authors the initial brief from the owner's request
+One compact `AGENTS.md` is seeded with the installer purpose, a short note to
+keep durable facts in `memory/` (one fact per file, indexed in `memory/MEMORY.md`)
+and one line pointing at `ez tools list --details`. Every engine loads `AGENTS.md`,
+so they share that memory. When a chat conversation is replaced (new conversation
+or AI/provider change), its engine gets one silent turn to save durable facts. The installing LLM authors the initial brief from the owner's request
 and known application context; Ez stores it without trying to infer the product
-itself. Installed plugin snippets and skill paths come from the bound
-`ez tools list --details` locator; no tool inventory file needs maintenance.
+itself. Installed plugin aliases, purposes, skills and examples come from
+`ez tools list --details`; no tool inventory file needs maintenance.
 Credentials and control state stay outside the mind. Isolated agents use relay
 mounts as the filesystem boundary. Host-capable file separation is not OS
 isolation against a process running as the same user.

package/bin/ez

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import { createConnection } from 'node:net';
 import { randomUUID } from 'node:crypto';
+import { fstatSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { installedNativeHelp } from '../src/plugins/native-tasks.mjs';
 
 const MAX_STDIN_BYTES = 1024 * 1024;
+const SOCKET_STDIN_IDLE_MS = 1000;
 const RUN_ID = /^[A-Za-z0-9_-]{1,160}$/;
 const socketPath = process.env.EZ_PLUGIN_BROKER_SOCKET?.trim();
 const runId = process.env.EZ_RUN_ID?.trim();
@@ -50,18 +52,25 @@ const request = (payload, signal = undefined) => new Promise((resolve, reject) =
   socket.on('connect', () => socket.write(JSON.stringify(payload) + '\n'));
 });
 
-const readStdin = async () => {
-  if (process.stdin.isTTY) return '';
+// Pipes and files always end, so read them to EOF. A socket is how Node-based
+// parents (native engine shells, agent scripts) wire child stdio, and they
+// often pass it on without ever closing it. Waiting for that EOF hung calls
+// before the broker was contacted, so a socket that stays silent means no input.
+const readStdin = () => new Promise((resolve, reject) => {
+  if (process.stdin.isTTY) return resolve('');
   const chunks = [];
   let bytes = 0;
-  for await (const chunk of process.stdin) {
+  const idle = fstatSync(0).isSocket() ? setTimeout(() => { process.stdin.destroy(); resolve(''); }, SOCKET_STDIN_IDLE_MS) : undefined;
+  process.stdin.on('data', chunk => {
+    clearTimeout(idle);
     const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
     bytes += value.length;
-    if (bytes > MAX_STDIN_BYTES) throw Error('plugin stdin exceeds the broker limit');
+    if (bytes > MAX_STDIN_BYTES) { process.stdin.destroy(); return reject(Error('plugin stdin exceeds the broker limit')); }
     chunks.push(value);
-  }
-  return Buffer.concat(chunks).toString('utf8');
-};
+  });
+  process.stdin.once('end', () => { clearTimeout(idle); resolve(Buffer.concat(chunks).toString('utf8')); });
+  process.stdin.once('error', error => { clearTimeout(idle); reject(error); });
+});
 
 const invoke = async (args, stdin) => {
   if (!runId || !RUN_ID.test(runId)) throw Error('EZ_RUN_ID is required for an isolated plugin command');

package/docs/architecture/ai-selection.md

@@ -3,6 +3,10 @@
 `menu.ts` owns Telegram controls; `ai.ts` projects installed-client metadata.
 `ControlStore` stores saved presets, the next-conversation default and current choice.
 No provider SDK, model fallback, history migration, or second execution loop.
+A missing catalog entry rejects selection without changing the conversation.
+An unsupported effort reports the exact installed model's advertised levels.
+Missing selectable models do not establish that the active native session is
+unavailable, and editing a scheduled task does not change the chat selection.
 
 At intake each journal entry receives an immutable preset and conversation ID.
 Batches cannot cross that boundary. The run copies that choice and invokes the

package/docs/docker-runtime.md

@@ -141,6 +141,17 @@ An interrupted Telegram poller keeps authorized work and in-flight deliveries
 alive while it retries intake. Run and delivery records are relay memory: a
 relay process restart drops in-flight work by design, Telegram redelivery is the
 intake replay path, and uncertain sends report unknown instead of success.
+Host-capable agents are the exception for running work: their native CLIs run under
+the host transport, so a graceful relay stop (Compose recreate, Docker restart)
+writes those running runs to private `control/run-handoff.json` instead of
+cancelling them. The next relay adopts each one, keeps its concurrency slot and
+schedule hold, accepts its messages and records its exit status; it never
+relaunches a run. A run whose outcome is unknown (no request, claim or result
+record, or an adoption failure) is recorded failed and interrupted, which holds
+its schedule until an explicit edit; the host is asked to cancel it. A request
+the host had not claimed before the relay stopped is failed by the host without
+starting. Records older than 24 hours are ignored, and the file is removed on
+every start. Queued runs are still dropped. Accepted deliveries are drained before listener shutdown completes; settled receipts for handed-off runs move with the handoff. A connection failure during a declared upgrade swap waits for the relay; an accepted timeout is never retried.
 A `409 Conflict` still requires the operator to stop the competing poller; it
 remains unhealthy after the startup grace. Pending and uncertain deliveries keep
 their existing receipt semantics; executor stdout is not replayed as a reply.
@@ -196,8 +207,12 @@ The image pins modern Docker Compose, including its standalone executable, so
 existing operator-created volumes retain their data and driver bindings.
 
 The relay-side `ez` client sends only declared aliases, literal argument arrays,
-bounded stdin, and the active run ID to the broker. The broker re-reads owner
-authority and the registry before every call, pins the discovered revision, and
+bounded stdin, and the active run ID to the broker. It reads a piped or
+redirected stdin to EOF. A socket stdin, which native engine shells and Node
+child processes often leave open, counts as no input unless data arrives within
+one second; write and close it immediately when a command needs input. The
+broker re-reads owner authority and the registry before every call, pins the
+discovered revision, and
 passes only the installed plugin's `run.application.context.plugins[plugin-id]`
 object as `EZ_PLUGIN_CONTEXT`. Missing, revoked, cross-agent, expired, or reused
 admissions fail closed. Timeouts, cancellation and bounded output produce a
@@ -376,3 +391,14 @@ The isolated executor image includes Node, jq and Python 3 (`python` and
 remain behind installed plugins. Registered command admission waits up to five
 seconds for the short registry lock; lifecycle changes still fail closed, and
 no caller removes an existing lock. Serialize calls when a plugin requires it.
+
+## Isolated executor generations
+
+A handoff-capable supervisor runs the existing native file transport in a separate
+unprivileged per-agent container. It derives workspace/control mounts and the image
+from the owning relay deployment, adds only a read-only executor binding, and gives
+the worker no relay secrets, provider secret environment or Docker socket. Native
+credential homes stay in the existing control volume. Only the active generation
+claims work; retired generations keep cancellation and per-run liveness until
+their last process exits. The supervisor removes their temporary Compose resources.
+The first upgrade from an embedded isolated executor drains before this migration.

package/docs/plugin-guide.md

@@ -57,14 +57,14 @@ At minimum, provide:
   machine-readable commands, stable exit codes, and readback for writes.
 
 The manager snapshots the package according to `package.json.files` plus the
-required manifests and Docker inputs. `ez tools list --details` includes
+required manifests and Docker inputs. `ez tools list --details` prints aliases, purpose, skill paths, one example call
+(the optional manifest `example`, else `<alias> --help`) and
 `skillReads`: literal command argument arrays for reading each installed skill.
 Use `ez tools skill <plugin> <declared-path>` to return its text and pinned
 revision. The isolated executor cannot open private host package paths directly;
 the authorized broker reads only manifest-declared regular skill files, without
 copying them into the agent workspace. Skill reads reject symlinks and files over
-64 KiB. The existing generic discovery footer remains accurate; no plugin-specific
-usage snippet or per-turn instruction is needed for this read contract.
+64 KiB. No AGENTS.md text or per-turn instruction is needed for this read contract.
 
 Keep one canonical checkout; do not keep
 permanent packaged copies or a second registry. See the full

package/docs/plugins.md

@@ -27,8 +27,7 @@ node /absolute/ezenciel_agents/bin/ezenciel-agents-tools.mjs init \
 Without `--catalog`, init loads an empty packaged catalog. Keep it empty for
 initial main onboarding; no sibling repository, broker or provider account is
 needed. Finish owner pairing and verify an actual Telegram agent reply first.
-Init creates a private registry and `tools/bin/ez`, adds a
-managed AGENTS.md registry locator, and binds the matching host executor to that bin
+Init creates a private registry and `tools/bin/ez` and binds the matching host executor to that bin
 folder. Native binaries are linked through; the package's own `bin/ez` is replaced
 by that bound launcher, while an unrelated existing `ez` collision fails.
 Both host-bound and isolated `ez --help` list installed native scheduling and delivery helpers
@@ -307,8 +306,10 @@ never a source of network attachment authority.
 
 Commands run in one-shot client containers against their own service's volumes;
 stdin, stdout, stderr, literal arguments and exit codes are preserved. SIGINT/
-SIGTERM cancel the Docker call and remove its unique client container. The manager
-never retries a provider operation. Service startup/restart is explicit; commands
+SIGTERM cancel the Docker call and remove its unique client container; a Compose
+exit with a non-zero status also removes it, so a call that stopped between
+create and start never remains `Created`. The manager never retries a provider
+operation. Service startup/restart is explicit; commands
 never implicitly start a stopped provider service. Plugin data does not enter the
 relay. The manager sends only a whitelist of Docker client environment variables.
 
@@ -412,10 +413,12 @@ QMD runtimes or edit installed Compose/package files to bypass missing support.
 
 ## Generated capability discovery
 
-`ez tools list --details` generates a compact index directly from installed
-`ez-plugin.json` manifests: each plugin supplies its `description`, command aliases
-and `skills`. Descriptions are limited to 200 characters in this view; full
-instructions stay in the skill. Installation, replacement and removal are reflected
+`ez tools list --details` generates a self-sufficient index directly from
+installed `ez-plugin.json` manifests. Per plugin it prints `aliases`, a one-line
+`purpose` (the manifest `description`, at most 200 characters), absolute `skills`
+paths and one `example` call. The optional manifest `example` is one line of at
+most 160 characters starting with a declared command alias; without it the
+example is `ez <first alias> --help`. Full instructions stay in the skill. Installation, replacement and removal are reflected
 on the next read, without hooks, LLM calls or a cached inventory file.
 
 The additive `skillReads` field supplies literal argument arrays for
@@ -424,8 +427,8 @@ installed plugin revision, declared path and skill content. Use it in isolated
 agents, where host package paths are private. It reads only the installed
 manifest's skills; arbitrary files, symlinks and files over 64 KiB are rejected.
 
-`ez tools list` retains its alias mapping for existing clients. Native AGENTS.md
-contains only the agent-bound discovery shortcut. New workspaces do not seed
+`ez tools list` retains its alias mapping for existing clients. The workspace
+seed writes one static line pointing here; nothing else is written. New workspaces do not seed
 TOOLS.md, SOUL.md, USER.md, or an `inbox/`/`work/` layout; upgrades preserve
 legacy notes without rewriting them. Keep owner/account policies in agent
 instructions or linked policy files, separate from plugin metadata.

package/docs/scheduling.md

@@ -21,7 +21,8 @@ ezenciel-agents-schedule cancel RUN_ID
 ```
 
 Use `--text-file` for longer instructions. `edit ID` replaces the complete schedule
-with a new revision; use the same trigger/name/text flags as `create`.
+with a new revision; use the same trigger/name/text flags as `create`. It keeps
+the paused/enabled state: an edited paused task stays paused until `resume`.
 An edit keeps a future pending occurrence when its trigger is unchanged;
 otherwise the edited rule begins at its next future occurrence. Editing does
 not replay missed work from an old start date. Use `--now` to request a new
@@ -57,7 +58,7 @@ available through `ezenciel-agents-schedule context`.
 
 ## Ordered setup fallback
 
-An agent task may list up to three fallback setups after its saved one, for
+An agent task may list ordered fallback setups after its saved one, for
 example `claude · opus → claude · sonnet → codex · gpt-6-sol`:
 
 ```sh
@@ -68,30 +69,58 @@ ezenciel-agents-schedule create --name Daily --cli claude --model opus \
 
 `edit` keeps the saved fallbacks unless `--fallback` replaces them or
 `--clear-fallbacks` removes them. Setups must be distinct and each needs a model.
+There is no fixed list-length limit. Each setup captures its own supported CLI,
+model, effort and optional provider; the installed native client owns valid model
+and effort values. The existing failure rules below apply to every setup.
+Each fallback may include `auth-profile=NAME` to select its own owner-provisioned
+Codex or Claude account. Omitting it selects the default login, independently of
+the primary setup. For four separate Claude accounts, provision and log into
+`claude2`, `claude3` and `claude4`, then use:
+
+```sh
+ezenciel-agents-schedule create --name Daily --cli claude --model opus \
+  --cron '0 9 * * *' --timezone Asia/Dubai --text 'Prepare the daily report.' \
+  --fallback cli=claude,model=opus,auth-profile=claude2 \
+  --fallback cli=claude,model=opus,auth-profile=claude3 \
+  --fallback cli=claude,model=opus,auth-profile=claude4
+```
 
 Core advances to the next setup only with typed evidence that nothing ran: the
 CLI is not installed or executable, or the provider rejected the turn before any
 model output, tool or hook item (quota/rate limit, billing, overload, server
-error, unavailable model or bad request). It stops, without replay, on access
-denial (authentication, account or organization), cancellation, relay shutdown,
+error, unavailable model or bad request), including a missing, expired or revoked
+login (typed authentication failure or HTTP401). Native API-error metadata does
+not count as model/tool work. It stops, without replay, on access
+denial (HTTP403, account or organization restriction), cancellation, relay shutdown,
 a schedule edit, a policy or unknown error, an interrupted transport, or any
-failure after work began. Evidence comes from structured events only: Codex
+other failure after work began. Evidence comes from structured events only: Codex
 native-session `codexErrorInfo` and Claude `stream-json` error fields (scheduled
 Claude runs use `--output-format stream-json`; the host forwards only a compact
 startup summary). Other engines advance only when their CLI is unavailable.
 
-A quota rejection skips the remaining setups in the same quota scope: the native
-client (`claude`, `codex` including desktop and custom Codex providers, `grok`)
-or the upstream provider for OpenCode/Pi models. A different credential alone is
-never treated as an independent allowance. Each setup runs at most once per
-occurrence.
+The one failure after work began that continues is a Claude usage limit the run
+ended on (for example "You've hit your session limit"): a typed quota rejection
+with no model, tool or hook activity after it. A native session cannot be resumed
+under another login's configuration home, so the next eligible setup starts a fresh
+session with the saved prompt plus one factual line naming the run, the stopped
+setup, its native session and reset time, and that its work may be partly applied.
+The agent reconciles from its own records; core replays nothing else.
+
+A login or quota rejection skips the remaining setups in the same scope: the native
+client and login profile (`claude`, `codex` including desktop and custom Codex
+providers), `grok`, or the upstream provider for OpenCode/Pi models. A named
+profile selects a separate owner-provisioned account and is eligible for its own
+attempt; changing only the model in the same profile does not reset its scope.
+Do not provision aliases of the same account to obtain more allowance. Ez does
+not infer account independence from credentials or promise that a shared
+organization's allowance is separate. Each setup runs at most once per occurrence.
 
 Every attempt keeps the same run ID, occurrence, schedule revision, workspace,
 delivery binding and scheduled concurrency slot, in a fresh native session.
 `run RUN_ID` shows `attempts`: each setup, quota scope, outcome, failure category
-(`cli-unavailable`, `quota`, `provider-rejected`, `access-denied`,
-`after-work-began`, `uncertain`, or `same-quota-scope` for a skipped setup), exit
-code and reported reset time. If every setup is unavailable the run fails with
+(`cli-unavailable`, `login-unavailable`, `quota`, `provider-rejected`, `access-denied`,
+`quota-after-work-began`, `after-work-began`, `uncertain`, or `same-login-scope`/`same-quota-scope`
+for a skipped setup), exit code, reported reset time and the session ID Ez assigned. If every setup is unavailable the run fails with
 reason `setups-unavailable`, a summary of each setup, and an owner notice on
 Telegram-bound tasks. Core never purchases credits, enables overage or consumes
 reset credits; the next regular occurrence runs normally.
@@ -225,10 +254,13 @@ 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. 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
+Stopping the relay also stops its workers, except on host-capable agents: a
+graceful relay stop hands running host-transport runs to the next relay, which
+adopts them without relaunching (see [Docker runtime](docker-runtime.md)). A
+request the host had not yet claimed when the relay stopped is failed by the host
+without starting. Run and delivery records are otherwise 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.
 
@@ -307,10 +339,18 @@ messages, read private sessions, trigger work or certify owning results.
 
 The prompt controls diagnosis, authorized recovery and quiet notification behavior. Inspect prior effects and receipts before retrying anything. A failed review run itself remains visible as a new failure for the next occurrence.
 
-The Telegram Scheduled tasks menu lists enabled schedules that still have a pending
-occurrence or a queued/running occurrence. Finished one-time tasks, paused
-schedules and revisions stopped for review are hidden. Each entry shows the
-effective engine/model/effort, next occurrence in UTC (or queued/running state),
+The Telegram Scheduled tasks menu lists paused schedules alongside enabled schedules
+that still have a pending occurrence or a queued/running occurrence. Paused tasks
+are labeled Paused and have no next run; an existing queued/running occurrence
+keeps its execution state visible. Finished enabled one-time tasks and enabled
+revisions stopped for review are hidden. Each entry shows the
+frequency with the cron timezone, the saved primary and fallback setups in order
+(CLI, login profile, model and effort), next occurrence in UTC (or queued/running state),
 and the first sentence of its saved invocation
 prompt, limited to 140 characters. This is a read-only view; history and full
-prompts remain available through the scheduling CLI.
+prompts remain available through the scheduling CLI. `/tasks N` shows the same
+frequency and execution path with the saved instructions. Common minute/hourly,
+daily and weekday rules have plain-language labels; other calendar rules show
+the exact cron expression and timezone. Interval rules show their fixed period,
+and one-time tasks show `Once`. This describes the schedule, not a guarantee of
+work when admission/preflight conditions are unmet.

package/docs/setup.md

@@ -261,8 +261,8 @@ node /absolute/ezenciel_agents/bin/ezenciel-agents-tools.mjs init \
 
 This binds a private `ez` and preserves native command access. The default catalog
 is empty. Do not supply a plugin catalog during first-time main onboarding.
-Initialization
-adds discovery instructions to the mind's AGENTS.md. Verify `tools/bin/ez plugins
+The seeded
+AGENTS.md already points at `ez tools list --details`. Verify `tools/bin/ez plugins
 available` before the first agent turn. Also execute the agent-bound
 `ezenciel-agents-message --help` through the selected CLI sandbox and verify
 its actual tool output, so absent launchers or blocked execution are detected

package/docs/standalone-cli.md

@@ -22,14 +22,14 @@ node /absolute/package/bin/ezenciel-agents-tools.mjs init --standalone \
 /absolute/private/company-tools/bin/ez plugins list
 ```
 
-Init starts nothing, uses an empty catalog by default, preserves existing
-workspace notes and adds a managed registry locator to AGENTS.md. A registry
+Init starts nothing, uses an empty catalog by default and never writes
+workspace instructions. A registry
 cannot be replaced by rerunning init. Keep the package at its original path:
 the launcher imports it. Status reports `main: null` without a relay binding;
 automated software upgrades currently require a relay deployment.
 
-Use `ez tools list --details` for generated installed-plugin descriptions, help shortcuts and absolute skill paths. Read only the relevant skill.
-Add that instruction to its existing project instructions without replacing them.
+Use `ez tools list --details` for each installed plugin's aliases, purpose, skill paths and one example call. Read only the relevant skill.
+Add "Tools: run `ez tools list --details`; each plugin's `--help` gives usage." to the project's existing instructions, with `ez` resolving to the returned launcher.
 Use the absolute launcher, or prepend its bin directory to that session's PATH.
 Never overwrite another global `ez`; it may belong to a different installation.
 A standalone company registry remains explicit even when invoked from a different

package/docs/upgrades.md

@@ -16,7 +16,12 @@ automatic channel for core and plugins without a saved policy. Existing explicit
 stable or manual policies are preserved. The owner may select either per target.
 The main target and installed plugins version independently.
 
-Core upgrades leave channel admission open while native work runs, then pause it after work is idle and recheck races. Plugin upgrades build while native work continues. Activation closes the existing registry admission lock, drains in-flight plugin command leases, and replaces the plugin under that lock. New native plugin calls wait for admission; an outdated revision fails before provider execution and must be rediscovered. No admitted provider operation is replayed. The shared broker and native sessions remain running. Core upgrades still require the full native-work drain. A plugin update also retains that drain if an operator replaced the broker’s single-file host binding (for example to approve new network pins), because that case still requires broker recreation.
+Handoff-compatible core upgrades build while native work continues and pause admission only for activation. The current native executor retires from claiming new work; the replacement claims new requests while the retiring generation finishes its existing runs. The relay adopts those runs without replay, preserving their schedule holds, cancellation and settled delivery receipts. The supervisor reloads only after native work is idle, so OS service process-group cleanup cannot kill a retiring generation. Plugin upgrades build while native work continues. Activation closes the existing registry admission lock, drains in-flight plugin command leases, and replaces the plugin under that lock. New native plugin calls wait for admission; an outdated revision fails before provider execution and must be rediscovered. No admitted provider operation is replayed. The shared broker and native sessions remain running. Older runtimes without the handoff contract retain the full native-work drain. Isolated agents migrate once while idle to a separate, unprivileged executor container using the same file transport; later relay/runtime upgrades preserve that executor generation. No native CLI or provider credentials move to the host. A plugin update also retains that drain if an operator replaced the broker’s single-file host binding (for example to approve new network pins), because that case still requires broker recreation.
+
+Compatible main upgrades also finish their advisory workspace/native-client
+backup before closing admission or stopping the relay. Large native histories do
+not extend the swap's delivery outage. These live-state copies are best effort;
+rollback restores code and configuration, never the backup over active state.
 
 The owner chooses the saved update policy. The host supervisor owns
 interruption-safe replacement. There is one host service per agent, not a second
@@ -153,7 +158,7 @@ is required. Stable automation excludes prereleases, major changes and 0.x minor
 changes. Beta policy permits compatible prereleases. Downgrades are rejected;
 rollback is a recovery operation for the previous installation only.
 
-`apply` records one durable queued job. **For a core upgrade, the agent must finish its turn after queuing it** so the supervisor can drain native work. A plugin upgrade can complete while that turn continues; only plugin-call admission is held during activation. Calls already executing finish first.
+`apply` records one durable queued job. **For a core upgrade from a runtime without the handoff contract, the agent must finish its turn after queuing it** so the supervisor can drain native work. New compatible runtimes can swap while native work continues. A plugin upgrade can complete while that turn continues; only plugin-call admission is held during activation. Calls already executing finish first.
 One job at a time; an unresolved recovery blocks new upgrades. The agent processes
 multiple requested packages over successive update requests.
 
@@ -255,19 +260,15 @@ 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 guidance is the managed `<!-- ez tools -->` block: the bound
-`ez` launcher, `ez --help`, `ez tools list --details`, and one routing hint for
-foreground owner turns to prefer `ezenciel-agents-schedule create --now` when work
-can continue independently without blocking interaction. The hint tells scheduled
-turns to execute their assigned work directly instead of rescheduling themselves.
-Inventory and full scheduler usage are generated on read. Plugin registry init and update binding refresh that block.
-Malformed markers and symlinks fail visibly rather than overwriting personal work.
-Upgrade and rollback render the block through the exact package root being activated,
-so an already-running package cannot leave stale guidance behind.
-
-Codex, Grok and OpenCode discover workspace instructions natively. Claude
-receives the native `--append-system-prompt-file` binding to `AGENTS.md`, alongside
-its own normal instructions. Fresh and resumed owner input is literal; ez does
+Ez writes no managed guidance after the initial workspace seed. Update binding
+(init with a host config, `enable-updates`, upgrade and rollback) replaces a former
+`<!-- ez tools -->` footer once with the seeded static line
+"Tools: run `ez tools list --details`; each plugin's `--help` gives usage." and
+otherwise leaves `AGENTS.md` untouched. Malformed markers and symlinks fail visibly
+rather than overwriting personal work. Inventory and usage are generated on read.
+
+Codex, Grok, OpenCode and Claude Code discover workspace `AGENTS.md` natively
+(Claude Code loads it when the workspace has no `CLAUDE.md`). Fresh and resumed owner input is literal; ez does
 not surround it with policies, tool recipes, repair instructions or history.
 The native engine owns instruction loading and its context/token overhead.
 Already running sessions retain their current context until native reload.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jc_stack/ez-agents",
-  "version": "0.1.0-beta.49",
+  "version": "0.1.0-beta.51",
   "private": false,
   "type": "module",
   "description": "A lightweight foundation for persistent business AI assistants using existing AI harnesses, workspaces and plugins.",
@@ -112,7 +112,9 @@
     "protocol": 1,
     "kind": "main",
     "stateSchema": 1,
-    "mainProtocol": 1
+    "mainProtocol": 1,
+    "runHandoff": 1,
+    "containerExecutor": 1
   },
   "exports": {
     "./application-client": "./src/application-client.mjs",

package/src/agent-guidance.ts

@@ -5,8 +5,8 @@ import path from 'node:path'
 const start = '<!-- ez shared guidance: begin -->'
 const end = '<!-- ez shared guidance: end -->'
 
-// Drop the obsolete package-owned handbook. Discovery lives in the managed
-// ez tools locator. Personal text outside the markers stays byte-for-byte.
+// Drop the obsolete package-owned handbook. Discovery is seeded once and
+// generated by `ez tools list --details`. 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)

package/src/ai-cli.ts

@@ -5,6 +5,7 @@ import { mkdir, readFile } from 'node:fs/promises'
 import { authProfileStatus, readModels, presetProvider, sameChoice, sameEngine, validateSelection, type AiPreset, type ModelChoice } from './ai.js'
 import { cliHome } from './auth-profile.js'
 import { ControlStore } from './control-state.js'
+import { resolveIsolation } from './isolation.js'
 
 const usage='Usage: ezenciel-agents-ai list | select --cli <installed-cli> [--auth-profile <name>] [--provider <provider>] [--model <model>] [--effort <effort>] | default | profiles | profile add --cli codex|claude --auth-profile <name>'
 const {values,positionals}=parseArgs({allowPositionals:true,options:{help:{type:'boolean'},cli:{type:'string'},'auth-profile':{type:'string'},provider:{type:'string'},model:{type:'string'},effort:{type:'string'}}})
@@ -15,8 +16,9 @@ if(values.help){
 if (!process.env.EZ_CONTROL_DIR) throw new Error('Use this agent’s bound control directory')
 const controlDir=process.env.EZ_CONTROL_DIR
 const authProfile=values['auth-profile']
-const catalog=():Promise<ModelChoice[]>=>readFile(join(controlDir,'host-executor','models.json'),'utf8')
-  .then(text=>JSON.parse(text)).catch(()=>readModels(undefined,undefined,join(controlDir,'cli','codex'),undefined,undefined,undefined,controlDir))
+const catalog=():Promise<ModelChoice[]>=>(process.env.EZ_AI_CATALOG==='host'||(process.env.EZ_AI_CATALOG===undefined&&resolveIsolation(process.env)==='host-capable'))
+  ? readFile(join(controlDir,'host-executor','models.json'),'utf8').then(text=>JSON.parse(text))
+  : readModels(undefined,undefined,join(controlDir,'cli','codex'),undefined,undefined,undefined,controlDir)
 if(positionals[0]==='list')console.log(JSON.stringify(await catalog()))
 else if(positionals[0]==='profiles')console.log(JSON.stringify(await authProfileStatus(controlDir)))
 else if(positionals[0]==='profile' && positionals[1]==='add'){