@jc_stack/ez-agents 0.1.0-beta.49 → 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,20 @@
 # 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.

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,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

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

@@ -57,7 +57,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 +68,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 +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.
 
@@ -310,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

@@ -255,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jc_stack/ez-agents",
-  "version": "0.1.0-beta.49",
+  "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)

package/src/ai.ts

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

package/src/application-channel.ts

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

package/src/executor.ts

@@ -500,6 +500,15 @@ export const startExecutorJob = async (
 
 export const startGrokJob = startExecutorJob
 
+// Watch a host-transport run a previous relay submitted; it is never resubmitted.
+export const attachHostJob = async (controlDir: string, runId: string): Promise<ChildProcess> => {
+  const invocation = executorInvocation(process.execPath, ['--import', fileURLToPath(new URL('../node_modules/tsx/dist/loader.mjs', import.meta.url)),
+    fileURLToPath(new URL('./host-executor-client.ts', import.meta.url)), controlDir, runId, '--attach'])
+  const child = spawn(invocation.command, invocation.args, { env: executorEnvironment(), stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32' })
+  await new Promise<void>((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject) })
+  return child
+}
+
 // Spawn a verified registered script with the executor identity, environment
 // allowlist and workspace confinement. No shell, model, prompt or native session.
 export const startScriptJob = async (