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

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,29 @@
 # Changelog
 
+## 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.
+- Keep separate named Codex and Claude native login homes, with account-bound conversations, profile-aware model selection and fail-closed admission.
+- Try ordered saved setups for a scheduled task only after a typed failure before work begins. Hooks, model/tool activity, access denial, cancellation and uncertain transport stop fallback; quota rejection skips the same native CLI/provider scope.
+- Preserve each scheduled attempt's captured auth profile and admit only the active setup on the host transport.
+
+Beta limits: live fresh-host/reboot acceptance, two-real-account channel switching and real exhausted-account/provider rejection remain pending. Fallback applies to scheduled agent tasks only; OpenCode/Pi/Grok advance only when their CLI is unavailable. The fallback command does not select named profiles, and different credentials do not establish independent quota allowances. Publication does not establish an installed-agent upgrade or authorize provider/domain writes.
+
 ## 0.1.0-beta.48
 
 - Skip empty or unchanged scheduled work through owner-configured installed read-only plugin preflight. Invalid or unavailable reads fail closed; saved execution settings and recurring timing remain intact. The bound plugin broker is required.

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/docker/broker-update-smoke.mjs

@@ -6,8 +6,8 @@ import path from 'node:path';
 import assert from 'node:assert/strict';
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { atomic, snapshot } from '../src/plugins/manager.mjs';
-import { execute, refreshBroker } from '../src/updates/runtime.mjs';
+import { atomic, snapshot, publishBrokerPlugins } from '../src/plugins/manager.mjs';
+import { execute, refreshBroker, verifyBroker, brokerNeedsRefresh } from '../src/updates/runtime.mjs';
 const docker=(...args)=>execFileSync('docker',args,{encoding:'utf8',stdio:['ignore','pipe','pipe'],timeout:120000}).trim();
 const hash=bytes=>createHash('sha256').update(bytes).digest('hex');
 if(process.argv[2]!=='--inside') {
@@ -69,6 +69,20 @@ if(process.argv[2]!=='--inside') {
   assert.equal((await mounted()).trim(),ready.hostSha256);assert.equal((await prepare()).trim(),'prepared');
   assert.equal(ready.plugins[0].revision,b.revision);
   console.log(JSON.stringify({stage:'activation',oldBroker,newBroker,relay,hostSha256:ready.hostSha256,registrySha256:ready.registrySha256,revision:b.revision}));
+  // With the current host binding already approving both revisions, plugin-only
+  // activation/rollback must leave the broker socket and relay intact.
+  await publish(a);await publishBrokerPlugins(home,controlDir);
+  const pluginRollback=await verifyBroker(config);
+  assert.equal(pluginRollback.plugins[0].revision,a.revision);
+  assert.equal(await container('plugin-broker'),newBroker);assert.equal(await container('relay'),relay);
+  assert.equal(await brokerNeedsRefresh(config),false);assert.equal((await prepare()).trim(),'prepared');
+  await publish(b);await publishBrokerPlugins(home,controlDir);
+  const pluginActivation=await verifyBroker(config);
+  assert.equal(pluginActivation.plugins[0].revision,b.revision);
+  assert.equal(await container('plugin-broker'),newBroker);assert.equal(await container('relay'),relay);
+  assert.equal((await prepare()).trim(),'prepared');
+  console.log('PASS plugin activation/rollback: current registry accepted; broker and relay IDs preserved');
+
   await atomic(hostConfig,host([a.revision]));
   await assert.rejects(refreshBroker(config),/STRUCTURAL_READINESS_FAILED/);await assert.rejects(prepare(),/not pinned/);
   console.log('PASS unapproved B remains rejected after recreation');

package/docker/upgrade-smoke.mjs

@@ -14,7 +14,7 @@ const exec=promisify(execFile),root=await fs.realpath(await fs.mkdtemp(path.join
 const source=path.join(root,'source'),home=path.join(root,'tools'),mind=path.join(root,'mind'),control=path.join(root,'control');
 const input=path.resolve(process.env.EZ_WHATSAPP_SOURCE||new URL('../../ez_whatsapp',import.meta.url).pathname);
 const bin=new URL('../bin/ezenciel-agents-tools.mjs',import.meta.url).pathname;
-const call=async(...args)=>JSON.parse((await exec(process.execPath,[bin,'--home',home,...args],{maxBuffer:4*1024*1024})).stdout);
+const call=async(...args)=>JSON.parse((await exec(process.execPath,[bin,'--home',home,...args],{cwd:mind,maxBuffer:4*1024*1024})).stdout);
 let record;
 try {
  for(const dir of [source,mind,control])await fs.mkdir(dir);

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
@@ -12,7 +16,11 @@ Each named conversation saves its model and reasoning level. Switching back thro
 `/ai` shows the current choice and saves changes immediately. Changing model or
 reasoning level on the same client and provider preserves the conversation's name
 and native history; subsequent turns pass the new settings to the native engine.
-Changing client or provider starts a separate native conversation. Old bindings
+Changing client, provider or auth profile starts a separate native conversation.
+A conversation records its client and auth profile when created; launch rejects a
+choice for another profile, so a native session never resumes under another
+account. Provisioned profiles appear as additional catalog entries for their
+client (see [auth profiles](../docker-runtime.md#auth-profiles)). Old bindings
 remain available so accepted work can finish and owners can reopen their chats.
 
 Grok/Claude accept caller-selected native UUIDs. Codex/OpenCode generate IDs, so

package/docs/docker-runtime.md

@@ -141,6 +141,18 @@ 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 and deliveries are still dropped, and messages a run
+sends while no relay is up fail and need a retry.
 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 +208,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
@@ -295,6 +311,34 @@ Without any login, Claude turns fail closed with the native "not logged in"
 error. Host-capable agents use the same agent-bound directory but share the
 installer login in place (`CLAUDE_SECURESTORAGE_CONFIG_DIR` empty).
 
+## Auth profiles
+
+One agent can keep several owner-provisioned Codex or Claude logins, for example
+a work and a personal account. Each named profile is a separate native home,
+`control/cli/profiles/<name>/<cli>` (`CODEX_HOME` or `CLAUDE_CONFIG_DIR`), with
+its own credentials, configuration and native sessions. The unnamed default
+keeps the bindings above unchanged. Create the empty home and get the exact
+native login command with:
+
+```sh
+ezenciel-agents-ai profile add --cli claude --auth-profile work
+```
+
+Then the owner logs in once with the printed command, inside the relay for
+isolated agents. Claude may instead use a `claude setup-token` token in that
+home's `oauth-token` (mode `600`). Ez never reads, copies or prints the
+credential. A named profile never links the host login or another home: an
+unprovisioned or logged-out profile fails closed with the native error.
+`ezenciel-agents-ai profiles` reports each home's login status (logged in,
+method, credential file names) from the native CLI without tokens or account
+identifiers.
+
+Select a profile with `ezenciel-agents-ai select --cli claude --auth-profile work`,
+the profile entries in Choose AI, or `ezenciel-agents-schedule create ...
+--auth-profile work`. A conversation is bound to its CLI and profile; changing
+profile starts a new native conversation, and a run whose request names another
+profile than its captured choice is rejected before launch.
+
 ## OpenCode auth
 
 Isolated agents run the image OpenCode with `XDG_DATA_HOME` set to the

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

@@ -55,6 +55,75 @@ Paused, stale-owner, overlapping or held tasks and unmet conditions cannot be
 triggered. Historical deferred tasks keep their source context
 available through `ezenciel-agents-schedule context`.
 
+## Ordered setup fallback
+
+An agent task may list ordered fallback setups after its saved one, for
+example `claude · opus → claude · sonnet → codex · gpt-6-sol`:
+
+```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=sonnet,effort=medium --fallback cli=codex,model=gpt-6-sol
+```
+
+`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), 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
+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.
+
+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`, `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.
+
 ## Registered script schedules
 
 A schedule has one execution type. **Agent** schedules run the saved prompt with
@@ -184,10 +253,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.
 
@@ -269,7 +341,13 @@ The prompt controls diagnosis, authorized recovery and quiet notification behavi
 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),
+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,7 @@ 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.
 
-Queued upgrades leave channel admission open while native work runs. The supervisor pauses admission only after work is idle and releases that pause if a turn raced the check.
+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.
 
 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,9 +153,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. **The agent must finish its turn after
-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.
+`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.
 One job at a time; an unresolved recovery blocks new upgrades. The agent processes
 multiple requested packages over successive update requests.
 
@@ -257,19 +255,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.
@@ -294,12 +288,8 @@ Actual update transactions retain their existing admission, drain and rollback r
 
 ### Isolated broker readiness
 
-Isolated activation and rollback explicitly recreate only `plugin-broker` with
-`--no-deps --force-recreate --no-build --pull never --wait`. Plugin-only refresh
-pins the installed broker image ID; main activation uses the newly built image
-and rollback uses the recorded old image. This refreshes the narrow read-only
-host-configuration file mount after atomic replacement. The relay and native
-sessions are preserved during plugin-only refresh. Host-capable updates do not
+Isolated core activation and rollback explicitly recreate only `plugin-broker` with
+`--no-deps --force-recreate --no-build --pull never --wait`. Core activation uses the newly built image and rollback uses the recorded old image to refresh the single-file host binding. Plugin-only activation and rollback change directory-mounted registry files, verify the existing broker in place, and refresh its generated plugin-version inventory. They preserve the broker socket, relay and native sessions. Host-capable updates do not
 start a broker. Existing update admission and drain remain authoritative.
 
 Socket health is liveness only. Before reporting completion, the updater runs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jc_stack/ez-agents",
-  "version": "0.1.0-beta.48",
+  "version": "0.1.0-beta.50",
   "private": false,
   "type": "module",
   "description": "A lightweight foundation for persistent business AI assistants using existing AI harnesses, workspaces and plugins.",

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)