@jc_stack/ez-agents 0.1.0-beta.13 → 0.1.0-beta.19

package/docs/plugins.md

@@ -191,7 +191,8 @@ and monitoring subscriptions alone never grant task execution. See
 
 V1 remains supported. V2 adds declared generated `secrets`, service `environment`
 (literal strings or declared secret references with literal prefix/suffix),
-`dependsOn` health dependencies, non-root `user` and bounded `memoryMiB`.
+`dependsOn` health dependencies, non-root `user`, bounded `memoryMiB`, and an
+optional `cpus` limit (0.1–8 cores).
 Cycles, unknown dependencies and host environment interpolation are rejected.
 Secrets persist privately across reinstall and are never included in registry
 responses. Twenty provides a complete v2 backend example.
@@ -228,3 +229,47 @@ main/plugin replacement. See [upgrade setup, tools and recovery](upgrades.md). E
 Find released packages and the agent-owned registration path in the
 [plugin catalog](plugin-catalog.md). This listing does not change the empty
 default installation or connect provider accounts.
+
+## Optional shared worker (deployment schema 3)
+
+Schema 3 adds one optional `sharedServices` entry. It is never built or started by ordinary installation/start. `plugins shared-enable <plugin> <key>` creates or discovers it on the selected Docker daemon and recreates that plugin's clients with a read-only `/inference` socket volume. `shared-disable` removes only the client attachment; `shared-status` is read-only. Default per-agent files, networks and indexes remain unchanged.
+
+A shared entry declares `identity` (stable host resource ID), `buildTarget`, `memoryMiB`, optional `cpus` (default 0.5 CPU core; range 0.1–8), `healthcheck` (literal argv), `clients` (declared service names), `clientEnvironment` (literal environment entries), and `files` (packaged worker implementation/dependency paths). The manager fingerprints those files and the specification. Compatible package changes preserve attachments during managed updates; incompatible worker changes block an attached upgrade before stopping clients. The shared target must initialize `/inference` and `/models` for UID/GID 1000. Only its IPC volume is exposed to clients. The worker runs with dropped capabilities, bounded memory/PIDs and no published ports; outbound networking permits explicit model downloads. Library containers never receive Docker access.
+
+Docker's unique container name arbitrates concurrent first creation. Existing resources must match ownership and implementation labels. Labels assume a trusted Docker administrator; they are not credentials. Different Docker daemons are separate sharing domains. Stopping/uninstalling a plugin never stops or deletes the shared worker or model volume. Automatic shared-worker upgrades and garbage collection are not implemented; coordinate replacement explicitly after detaching all clients. Uninstall/reinstall resets client opt-in.
+
+Shared workers have a hard Docker CPU quota of half a core by default, across all attached agents combined. This leaves capacity even on a one-core host; it is not 50% of every core. The reviewed descriptor can set a different `cpus` value. Discovery refuses a worker whose actual CPU quota has drifted, rather than silently attaching to an unlimited process. Builds are not covered by the runtime quota.
+
+## Existing local folders
+
+Use operator-owned read-only folder bindings when a plugin needs files that
+already exist on the host. Keep indexes and writable metadata in the plugin's
+normal volume. This uses Docker bind mounts; it copies no source bytes and
+starts no provider sync. File edits remain with the host's existing tools.
+
+Stop the plugin before changing a binding:
+
+```sh
+ez plugins stop library
+ez plugins folder-bind library --service library --source /absolute/existing/notes --target /state/libraries/notes/files
+ez plugins folders library
+ez plugins start library
+```
+
+The target must be a child of a volume declared by that service, without
+colliding with another mount. Sources must be real existing directories outside
+the private tools directory. Missing sources fail instead of creating empty
+folders. Bindings are operator configuration, separate from package snapshots;
+compatible upgrades retain them and incompatible target changes fail validation.
+Use `folder-unbind ID --service NAME --target PATH` while stopped to detach a
+folder. Uninstall retains bindings and volumes. Unbinding reveals any underlying
+volume contents; inspect those before restarting to avoid using stale files.
+Never enable another sync writer for an already synchronized host folder.
+
+For Library, create/select the library name first and retain its QMD state while
+binding the host tree at that library's `files` directory. Keep provider bindings
+disabled for that source. Enable the normal shared embedding worker through
+`plugins shared-enable library embeddings`. Verify `library sources`, real search,
+and original readback from the actual executor. Document any differences between
+indexed snapshots and current originals; do not replace Library with private
+QMD runtimes or edit installed Compose/package files to bypass missing support.

package/docs/releasing.md

@@ -3,7 +3,9 @@
 Use the same checks for maintainer and external changes. Each repository versions
 independently with SemVer: patch for compatible fixes, minor for new capabilities;
 before 1.0, breaking CLI/state changes require a minor bump and migration notes.
-No automatic dependency updates, release bot or credentials in pull-request CI.
+No automatic dependency updates or credentials in pull-request CI. The agent
+operates this process under the authorization rules in CONTRIBUTING.md; a
+separate release bot is not required.
 
 1. In an isolated release worktree/PR, finalize package version and CHANGELOG.md;
    update plugin manifest version when present. After lockfile changes, copy
@@ -32,14 +34,20 @@ No automatic dependency updates, release bot or credentials in pull-request CI.
    fill package.json repository, homepage and bugs with the actual public URLs.
    Enable GitHub private vulnerability reporting; verify the route. Protect main
    with CI and independent PR review. Maintainers use the same process.
-7. Record independent review and green CI for the final release PR, then obtain
-   maintainer merge/release authorization for the exact commit, tarball SHA-256,
-   license/third-party obligations and known limits. Merge the release PR and
+7. Record independent review and green CI for the final release PR. The
+   maintainer's release request supplies authorization: do not ask for a second
+   approval. Record the prepared commit, tarball SHA-256, third-party obligations
+   and known limits. If release is outside the request, report readiness without
+   publishing. For an authorized release, merge the release PR and
    verify its tree matches the reviewed source before tagging `v<version>` and
    publishing that tarball:
-   `npm publish /absolute/candidate.tgz --access public --tag beta --registry https://registry.npmjs.org/`
-   for prereleases (use `--tag latest` only for an approved stable release).
-   Use interactive npm authentication with 2FA; never paste tokens into CI or docs.
+   `npm publish /absolute/candidate.tgz --access public --tag latest --registry https://registry.npmjs.org/`
+   for approved beta releases as well: `latest` is the default distribution tag,
+   not a claim that a SemVer prerelease is stable.
+   For unattended beta publication use the [shared trusted publisher](trusted-publishing.md)
+   and its exact-artifact staging/readback contract. Initial package publication
+   requires authenticated npm with 2FA before trust can be enrolled; never paste
+   tokens into CI or docs.
 8. Create the GitHub release from CHANGELOG.md, attach artifact/checksum, and
    install the registry version on a clean host. Verify metadata and the same
    onboarding path before posting launch copy. Stop rollout on failure; publish
@@ -53,13 +61,16 @@ credential revocation; do not delete volumes as a routine rollback.
 ## Beta channel
 
 Use SemVer prereleases (`0.1.0-beta.1`), GitHub's prerelease flag and npm's
-`--tag beta`; never mark a beta latest/stable. For this first beta the maintainer
+`--tag latest` so default installs and the package page advance automatically.
+The version and GitHub release remain prereleases; stable-only update policies
+still exclude them. The legacy npm beta tag is no longer advanced. For this first beta the maintainer
 explicitly deferred real account/reboot acceptance. Keep that limitation in the
 README and release notes. Source/tarball publication is permitted after the
 automated gates; deferred live checks remain required for stable release.
 GitHub repositories use `jdorado`; npm packages use `jc_stack`. Verify
 `npm whoami --registry https://registry.npmjs.org/` returns `jc_stack` before
-publishing. Never infer npm scope ownership from a GitHub login. After publishing,
+interactive publication. OIDC publication instead requires package-owner trust
+enrollment for the exact caller workflow; `whoami` is not its publication gate. Never infer npm scope ownership from a GitHub login. After publishing,
 read back `npm view @jc_stack/ez-agents@0.1.0-beta.12 name version dist-tags --json`
 (using the release being published), download it with `npm pack`, and verify its
 contents/checksum against the reviewed artifact. Keep the npm artifact and

package/docs/repair.md

@@ -0,0 +1,41 @@
+# Native repair ownership
+
+Every deployed agent is a repairer by default. When an agent finds a core or
+plugin defect, it keeps the context and pursues a tested contribution PR. The
+core injects the same mandate into CLI/native and desktop execution, including
+existing workspaces; it does not replace the agent's mind or implement a repair
+workflow engine. Use native Git/GitHub CLI or the installed GitHub plugin.
+
+The agent searches for the same cause, registers a sanitized issue, requests a
+claim, then works in an isolated contribution checkout after the coordinator's
+grant. It resumes the same issue/branch/PR after interruption. The installed
+runtime is never the repair checkout. Missing credentials or coordination remain
+recorded blockers; the default does not invent repository access. Public reports
+must exclude private runtime data and use the security reporting route when needed.
+
+One coordinator grants claims sequentially per repository. Assignment alone is
+not a lock. All participating agents must use that coordinator; this convention
+cannot prevent an unrelated public contributor from opening a competing PR.
+The discovering agent remains the repairer, including when its work moves to a
+background task. The coordinator reconciles duplicates and stalled claims. The
+maintainer independently reviews and tests, then merges/publishes only within
+separate owner-approved policies. Start from templates/maintainer-purpose.md.
+
+## Disable
+
+Set `EZ_REPAIR_ENABLED=false` in the deployment's Docker environment and recreate
+the relay. The resolved setting crosses the host transport and is included in
+every new execution prompt; the default is true and invalid values fail startup.
+This changes the automatic mandate, not filesystem/GitHub permissions, and does
+not cancel an already running task. Explicitly stop active repair work when needed.
+An owner can also disable repairs globally or for a repository in the agent's
+saved USER.md preferences; carry those restrictions into background task context.
+
+## Setup boundary
+
+The shipped mandate and maintainer purpose do not provision a GitHub account,
+coordinator service or publishing token. Enroll the allowed repositories and
+configure one maintainer execution lane on the owner's host before unattended
+claims. Reuse authenticated GitHub CLI where authorized. Repository push and PR
+permissions are distinct from package-registry publication and protected-branch
+approval. Never put credentials in prompts, issues or test environments.

package/docs/responsive-channels.md

@@ -0,0 +1,57 @@
+# Responsive channels
+
+Ez treats conversational channels as places to answer, clarify and hand off
+work. A simple question uses the current conversation; a small authorized action
+uses its canonical receipt. Substantial work gets a durable task with enough
+context to finish and verify the job. The agent returns to conversation after
+the handoff is saved, instead of waiting for the worker. This is agent guidance,
+not a keyword classifier, automatic acknowledgement, or latency guarantee.
+
+New Codex agents use Sol / medium for chat. Scheduled work defaults independently
+to Terra / high; the agent can choose another model and effort for complex work.
+`ezenciel-agents-schedule create --now --text-file FILE --model MODEL --effort high`
+uses the existing scheduler (include `--name` for a useful task label). Busy owner
+reply sessions expose the same independent model/effort choice through `defer`.
+Its retry returns the first saved schedule; changing arguments does not revise
+an accepted job. `xhigh` is available only for Luna; other models remain capped at high.
+
+A handoff includes the objective, relevant context and paths, constraints,
+authorized actions, acceptance checks and delivery destination. Background
+sessions own verification and final delivery, and may use native subagents.
+One writer per workspace still applies. Shared external resources require
+coordination even when task directories differ. Status must distinguish a saved
+schedule from actual execution and a verified result from a process exit.
+
+The package loads `templates/chat-guidance.md` at each turn for CLI, desktop,
+busy owner replies and approved plugin messaging tasks. Upgrades refresh this
+behavior without rewriting the agent's personal files. Existing model choices
+remain pinned; an upgrade adds Responsive chat as an available selection.
+
+## Channel and authority boundaries
+
+Telegram owner conversations can schedule work under the owner's authority.
+The existing restricted busy-reply session keeps Codex chat available while a
+writer is active. Other executors retain their existing concurrency behavior.
+
+WhatsApp and other plugin contacts use the approved messaging task's isolated
+context and tools. They receive the conversational guidance and Sol / medium
+selection, but cannot invoke owner schedules, shell tools or native subagents.
+They report work outside their capabilities to the owner; that report is not
+an instruction or permission to execute. Full delegation from a plugin contact
+needs an explicitly scoped worker capability and return route; this update does
+not grant one. The plugin name alone never confers owner authority.
+
+An application using `channelBackendUrl` owns its conversation, model and job
+lifecycle. The relay does not inject prompts or override the app's model. Such
+backends (including AI Fit) must adopt the same handoff policy in their own
+runtime to benefit. Reuse their canonical job system; do not create a second
+agent in the transport. Telegram polling and app-side queue waits still count
+toward user-visible latency.
+
+## Verification
+
+Tests cover independent worker settings, preserved selections across upgrades,
+idempotent handoffs, invalid settings, revocation and restricted tool boundaries.
+Existing scheduler/host tests cover a conversational reply while work remains
+active. Measure time to the first useful reply and verified task completion
+separately on the deployed provider before claiming a performance improvement.

package/docs/scheduling.md

@@ -32,6 +32,16 @@ the host changes zones. Nonexistent DST wall times are skipped; repeated wall
 times fire once, at the earlier instant. Search is bounded to eight years.
 Public-holiday calendars and arbitrary RRULE syntax are not implemented.
 
+New tasks, including work deferred by a busy reply session, default to Codex
+`gpt-5.6-terra` with `high` reasoning independently of the creating chat.
+New chats use the separate Sol/medium preset. Busy reply `defer` accepts optional
+`model` and `effort` fields; retries preserve the first saved task choice.
+Use `--cli`, `--model`, and `--effort` to specify another choice. `xhigh` is
+available only with Codex `gpt-5.6-luna`; every other model remains capped at
+`high`. Non-Codex adapters inherit native effort when unset. Editing preserves the existing AI
+choice unless those flags override it. Stored choices are checked again at
+launch, including schedules saved before a policy change.
+
 ## Execution and authority
 
 The relay checks due work once per second. Each occurrence enters the durable
@@ -41,7 +51,7 @@ Instructions must include any needed context or source paths; full chat history
 is not copied. Task folders remain for inspection and artifact delivery.
 
 One writer runs per task directory. Up to four background tasks can run alongside
-the sequential main conversation. A recurring schedule has at most one pending
+the main conversation. When a Codex owner message arrives while work is busy, a separate restricted session reads recent messages and run progress and answers through the normal outbox. It can queue requested work through the scheduler, but cannot run shell commands, access plugins, or edit the agent workspace. Only one reply session runs at a time and it releases its slot after a 60-second reply deadline; this deadline does not apply to writer jobs. Its context is a bounded snapshot, not a shared native transcript. Delivered parallel replies are included as historical context in the next normal conversation turn. Codex 0.153.4 and 0.154.0 are supported for this restricted adapter. Other versions fail closed pending tool-surface validation. A recurring schedule has at most one pending
 or active occurrence. Agents should delegate long work with `create --now`, return
 to chat, and inspect `runs` or task progress when asked. Native subagents can be
 used inside the worker. Sharing provider profiles does not make concurrent CRM,
@@ -70,8 +80,8 @@ The foreground chat still uses `codex exec`. That invocation exits after one
 requested turn even if a goal is active, so delegate persistent work to the
 scheduler. Desktop and other executor goal lifecycles need separate validation.
 
-The CLI binds jobs to the paired owner and current AI selection. Queued/scheduled
-work retains that selection after the chat switches AI. Revoking/re-pairing an
+The CLI binds jobs to the paired owner and the task AI choice. Queued/scheduled
+work retains that choice after the chat switches AI. Revoking/re-pairing an
 owner invalidates their old schedules, including re-pairing the same Telegram ID.
 External event turns cannot use the scheduling CLI. Credentials still pass only
 through the existing whitelist and installed host binding.
@@ -88,7 +98,7 @@ queued occurrence; already-running work continues until explicitly cancelled.
 `/stop` stops all active work; `cancel RUN_ID` stops one background task. `/cancel`
 clears queued work. Pause/remove a recurring schedule to prevent future runs.
 Stopping the relay also stops its workers. A crashed or interrupted execution is
-not automatically replayed. Runs found active at startup are marked failed with
+not automatically replayed. Status labels failed runs as history and shows recent reasons; new failures retain their exit code or interruption cause. Typing indicators stop after 30 seconds even when work continues. Runs found active at startup are marked failed with
 `interrupted: true`; their schedule revision stays held until the agent inspects
 the evidence and explicitly edits the schedule. Inspect the task's files, native session and delivery
 receipts before deciding whether to resume. A clock cannot reconstruct an
@@ -125,3 +135,21 @@ minutes. Verify `finished.txt` and exactly one completion in Telegram. Separatel
 exercise cancellation, downtime catch-up and an explicitly requested native goal
 that needs more than one turn. Synthetic provider evidence does not prove real
 Telegram delivery, and a sleep test does not prove native goal persistence.
+
+Busy-chat regression probe (real Codex, synthetic Telegram):
+
+```sh
+pnpm exec tsx scripts/smoke-busy-reply.ts --transport
+```
+
+The probe holds a writer on a shared workspace, asks an owner question through
+the relay and host transport, and requires the restricted reply to complete
+while the writer remains active. It sends no real Telegram messages.
+
+## Optional failure review
+
+Create a normal recurring schedule with `--every-seconds 900 --when unreviewed-failures --text-file templates/failure-review.md`. The condition advances empty occurrences without launching an executor. It considers only failures belonging to the paired owner. No separate monitor or automatic retry is introduced.
+
+`failures [--all] [--limit N]` returns failedAt, reason, exit code, native session, captured error and runtime versions. Capture keeps at most 4 KiB of redacted stderr; historical failures are not backfilled. `run RUN_ID` reads an owned run. `review RUN_ID --failed-at ISO --status resolved|attention --diagnosis TEXT --recovery TEXT --outcome TEXT` records the investigation without rewriting execution history. A stale timestamp is rejected; a later failure needs a new review. Restricted reply, external and isolated-task callers cannot review failures. An attention review is handed off, not repeatedly relaunched; another new failure wakes the next review.
+
+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.

package/docs/selective-monitoring.md

@@ -33,7 +33,7 @@ Infer the complete job from ordinary language:
 
 Apply the required core confirmation to the concrete proposal, not an extra
 questionnaire. Use the owner's existing contact, purpose and disclosure limits.
-Avoid claiming indefinite service where v1 is bounded. Explain the expiry only
+For an ongoing incoming-only conversation, use `--until-revoked`; finite tasks remain bounded. Explain the expiry only
 when it matters to that proposed job; never silently expand or renew permission.
 
 ## Three capture modes, separate reply authority
@@ -83,9 +83,17 @@ registered source, canonical contact, purpose, explicitly shareable context file
 and expiry. No need to invent a booking objective: “conversational replies to
 this contact, no private disclosures or commitments” is a legitimate purpose.
 If no private facts may be shared, say so in the context file; do not include
-owner memory. V1 supports at most 72 hours, not indefinite “until stopped.” Offer
-that bounded duration in the exact approval, explaining the limit without asking
-the owner to restate their request. Do not silently renew it.
+owner memory. Finite jobs support at most 72 hours. For an ongoing conversation requested by
+the owner, add `--incoming-only --until-revoked`. This authorizes that exact
+conversation until owner revocation, without a total reply quota. Do not silently
+convert a finite job into an ongoing permission.
+
+For Telegram groups, the relay registers source `telegram` automatically when
+paired. Use the exact negative group ID from discovery, never its display name.
+Keep the shared context limited to what every group member may know. All human
+members of that approved group may converse; this does not grant owner tools.
+The group runs with the existing restricted messaging runner, and its notes are
+separate from private PA memory. Group text is supported; media is not yet.
 
 The core presents the exact proposal for owner confirmation. Ordinary messages
 inside that grant need no repeated confirmations. Incoming-only grants create

package/docs/setup.md

@@ -1,5 +1,27 @@
 # Agent-led setup
 
+## A group as owner
+
+An installer can explicitly approve one Telegram group as the agent's owner.
+Every human member in that group then has owner access, including settings,
+approvals and scheduling. The conversation and replies are shared in that group.
+New members inherit this access. Bots and anonymous sender-chat posts are ignored.
+
+Add the bot to the intended group and send it a message addressed to its username.
+`ezenciel-agents-owner status` shows the pending group title and negative chat ID;
+verify the exact group with the installer, then run
+`ezenciel-agents-owner approve-group <negative-chat-id>`. Pairing never happens
+automatically. The existing `approve <user-id>` command approves DMs only.
+An existing owner must be explicitly revoked before replacement; use a fresh
+deployment when its existing workspace contains information unsuitable for the group.
+
+Make the bot a group admin so Telegram delivers ordinary member messages and
+allows membership verification for approval and control buttons. Group ownership only authorizes
+the exact approved chat, not other groups or members' private DMs. Telegram group
+migration to a new chat ID requires a new explicit binding. Verify a real group
+reply before considering setup complete. All other groups retain their existing
+restricted conversation-grant behavior.
+
 Ez supports two independent, composable uses: an autonomous Telegram agent and
 workspace-scoped plugins called by your existing local CLI/GUI executor.
 For CLI-only requests, follow [standalone setup](standalone-cli.md): no Telegram
@@ -30,6 +52,27 @@ owner request for standalone plugin development is a separate workflow.
 
 ## Defaults and host prerequisites
 
+New agents using `codex` or `codex-gui` start with `gpt-5.6-sol` and `medium`
+reasoning, including when initialized with `ezenciel-agents-setup init`. This
+Ez default takes precedence over discovered host client defaults. Saved agent
+selections permitted by the current policy are preserved; use the AI settings to choose another model or effort.
+Ez accepts `xhigh` only for `gpt-5.6-luna`; every other model rejects explicit
+reasoning above `high` at selection and execution, including old saved or queued choices.
+Unset Codex model/effort resolves to
+Terra/high at launch. This governs Ez-managed launches; it is not an account-wide
+limit on independently launched native clients or executor-created native subagents.
+Other adapters inherit their native effort when none is selected in Ez. That
+inherited configuration is not capped by Ez; explicit above-high Ez selections
+are rejected unless they are Codex Luna/xhigh. Conversation presets pin Sol/medium; the lower-level
+Codex fallback remains Terra/high for work without an explicit choice.
+
+New scheduled and one-off background tasks default to Codex Terra/high independently
+of the creating chat. Use scheduler `--cli`, `--model`, and `--effort` flags for
+explicit overrides. Editing a schedule preserves its settings unless overridden.
+Restricted messaging tasks use Sol/medium while retaining their approved tool
+and context boundaries. Upgrades add Responsive chat to saved choices without
+replacing the selected/default preset. See [responsive channels](responsive-channels.md).
+
 Use the existing owner's host account. Unless a layout was supplied, use
 `${XDG_DATA_HOME:-$HOME/.local/share}/ez/packages/<version>/` for extracted main
 packages and `${XDG_DATA_HOME:-$HOME/.local/share}/ez/agents/` for private deployments.

package/docs/trusted-publishing.md

@@ -0,0 +1,140 @@
+# Verified beta publication
+
+The Mac prepares and independently tests the release. GitHub-hosted Actions
+publishes the exact approved tarball using npm OIDC. The shared implementation
+is `.github/workflows/npm-beta-shared.yml` in this repository; each package has a
+small manually dispatched `publish-beta.yml` caller. This setup does not grant
+release authority or establish npm trust automatically.
+
+## Enroll a repository once
+
+1. Verify the source is public and explicitly registered in the current
+   [public catalog](plugin-catalog.md), or is core itself. Registration does not
+   prove a registry release exists. Excluded or private repositories cannot use
+   this publisher.
+2. Review and merge the shared publisher first. Generate the caller using its
+   full immutable commit SHA and the repository's required CI check names:
+
+   ```sh
+   node scripts/generate-publish-caller.mjs jdorado/ez-whatsapp \
+     @jc_stack/ez-whatsapp FULL_SHARED_COMMIT_SHA \
+     '["test (ubuntu-latest, 22)","test (ubuntu-latest, 24)","test (macos-latest, 22)","test (macos-latest, 24)","docker"]' > publish-beta.yml
+   ```
+
+   Put that file in the plugin's `.github/workflows/` through its own reviewed
+   PR. Inspect the actual CI names; the example does not establish the policy.
+   Keep the reusable workflow reference and `publisher-sha` on the same reviewed
+   commit. Core uses a local reusable workflow at the dispatch commit. The
+   generator writes stdout only; it never grants repository scope or edits npm.
+3. The npm package owner authenticates separately and enrolls the exact caller
+   repository and filename `publish-beta.yml` as a trusted publisher. Enable
+   **direct publication** explicitly; new trust configurations can default to
+   staged publication only. If an environment is configured on npm, add that
+   exact environment to the shared publishing job through review before use.
+   This workflow currently uses no environment.
+4. Verify enrollment through npm settings or `npm trust list PACKAGE`. npm
+   validates the **calling** workflow for reusable workflows. Both caller and
+   publishing job need `id-token: write`; test/validation jobs do not receive it. GitHub requires `contents: write`
+   to read unpublished draft assets: only the validation job receives that
+   capability and makes GET requests only. The separate OIDC job has
+   `contents: read`. No package code or lifecycle scripts run in validation.
+   Do not add `NODE_AUTH_TOKEN`, npm tokens, or private profiles to these jobs.
+
+An npm package must already exist before trust enrollment. If a registered
+plugin has no registry package, the owner must perform a real, approved initial
+beta publication using authenticated npm, with all release checks and exact
+artifact readback. Then enroll trust. Do not create a dummy release to test
+login. A missing GitHub release likewise remains missing until actually created
+and read back; a catalog link or workflow PR is not publication evidence.
+
+Current npm requirements and enrollment fields are documented in
+[npm trusted publishers](https://docs.npmjs.com/trusted-publishers/) and
+[npm trust](https://docs.npmjs.com/cli/v11/commands/npm-trust/).
+The workflow uses Node 24 and npm 11.19.1 on GitHub-hosted Ubuntu runners.
+
+## Prepare and dispatch one beta
+
+Follow [releasing](releasing.md), including isolated Mac tests, packed artifact
+inspection, independent review, required CI and authorized merge. The source
+must be the exact current `main` commit; after a merge, verify that its tree
+matches the tested source and renew invalidated evidence. Wait for that commit's
+CI from `.github/workflows/ci.yml`, triggered by a push on `main`. The caller's reviewed list of required checks is a fail-closed minimum;
+update it when repository policy adds checks. The validator selects the newest
+main-push CI run for that source before checking success, then requires the named
+jobs from its latest attempt. Tag, PR and other workflow runs cannot shadow it;
+failed, pending or incomplete main CI cannot fall back to an older success.
+
+Create the `vVERSION` tag at that exact source commit and a **draft prerelease**
+with these assets, using native `gh release create --draft --prerelease` and
+`gh release upload` under existing release authority:
+
+- `candidate.tgz`: the exact Mac-tested bytes from `npm pack --ignore-scripts`.
+  Do not rebuild it on Actions.
+- `release-receipt.json`: a sanitized record with this shape:
+
+  ```json
+  {
+    "repository": "jdorado/ez-agents",
+    "package": "@jc_stack/ez-agents",
+    "version": "0.1.0-beta.14",
+    "sourceSha": "FULL_TESTED_MAIN_COMMIT_SHA",
+    "sha256": "SHA256_OF_CANDIDATE_TGZ",
+    "independentReviewUrl": "https://github.com/jdorado/ez-agents/pull/PR_NUMBER#issuecomment-ID",
+    "testEvidenceUrls": ["https://github.com/jdorado/ez-agents/actions/runs/RUN_ID"]
+  }
+  ```
+
+The maintainer verifies those evidence links substantiate independent final-diff
+review, artifact tests and accepted beta limitations before dispatch. The receipt
+binds that attestation to the commit and digest; a syntactically valid URL alone
+cannot prove review quality or release authority.
+
+Read the draft's numeric `id` with `gh api repos/OWNER/REPO/releases` (the
+release-by-tag API only returns published releases). Dispatch `publish-beta.yml`
+on `main` with `release-id`, `version`, `source-sha` and
+`artifact-sha256`. Copy the digest from the independently verified Mac receipt,
+not an unreviewed replacement release asset. The validator checks current public
+scope, source/tag identity, required GitHub Actions checks, receipt identity,
+package metadata and tarball hash. It transfers the validated bytes using an
+immutable Actions artifact ID. A fresh job revalidates before publication and
+runs npm from a clean directory without package lifecycle scripts.
+
+Only `X.Y.Z-beta.N` versions are supported. Publish to npm `latest` so the
+package page and default installs show the newest approved release. Manifests
+must use `publishConfig.tag: "latest"` (or omit the tag). The version remains a
+SemVer prerelease and the GitHub release remains a prerelease. Private
+packages, wrong package/repository identities and stable versions fail before
+publication. No npm login smoke publication or stable-version release occurs.
+
+## Readback, failure and release completion
+
+The publisher reads registry metadata, checks that `latest` identifies the released version and downloads the
+published tarball to compare its SHA-256. Preserve the workflow's readback receipt, run URL and source/artifact
+identity on the release PR. A failed command after the publish call may mean npm
+accepted it: inspect registry state first. A rerun may verify an existing exact
+version; if the version is absent it refuses a second write. Reconcile first,
+then create a fresh authorized dispatch if appropriate. Never repeat or overwrite that version or silently repair tags.
+Missing trust or registry access is an external dependency, not a reason to use
+a token workaround.
+
+After successful registry readback, finish the GitHub prerelease with the tested
+artifact/checksum and verify its public availability. Perform the clean-host
+installation and runtime/provider checks required by the package's release
+rules. Actions success proves registry delivery only; it does not prove a
+running agent was upgraded. Respect each installation's saved update policy.
+
+## Migration from the legacy beta tag
+
+Existing plugin callers are SHA-pinned: regenerate each caller against the merged
+shared-publisher revision and update its package publishConfig together through
+review. Old pins retain the old behavior. Do not mutate an already staged or
+published artifact; prepare a new version when package metadata changes.
+
+The publisher uses one native npm publish operation with OIDC and `--tag latest`.
+It does not synchronize the legacy `beta` tag: npm trusted publishing does not
+support standalone dist-tag changes. No extra registry token is needed. Ez beta
+update discovery considers both latest and legacy beta during migration; stable-only
+policies select non-deprecated stable versions and cannot automatically install a
+prerelease. Older installed updaters still following only beta require an explicit
+exact-version update to a core release containing this discovery change. Existing
+registry versions/tags are not changed by merging the publisher.

package/docs/upgrades.md

@@ -2,8 +2,9 @@
 
 Available in this beta. Earlier main upgrade/rollback VM QA passed; final-release
 fresh-host/reboot and live plugin upgrade acceptance remain pending. npm
-publication is not required to test this feature. Stable releases are the default
-automatic channel. The existing owner may select beta or manual policy per target.
+publication is not required to test this feature. The beta channel is the default
+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.
 
 The agent owns release review, policy decisions and communication. The host
@@ -109,8 +110,8 @@ live. A healthy container alone does not prove a Telegram or plugin reply.
 
 ```sh
 ez updates check
-ez updates policy main                 # defaults: automatic, stable
-ez updates policy whatsapp beta        # only under owner authorization
+ez updates policy main                 # defaults: automatic, beta
+ez updates policy whatsapp stable      # opt into stable-only updates
 ez updates policy main manual          # disable unattended upgrades
 ez updates prepare main --version 0.1.0-beta.4
 # Or a local candidate, independently of npm:
@@ -191,3 +192,22 @@ changes also need supervisor restart and requesting-process-exit tests. Run
 `node docker/upgrade-smoke.mjs` with a local `EZ_WHATSAPP_SOURCE` containing the
 WhatsApp fixture. The smoke uses synthetic transport only. VM installation,
 agent-led upgrades, restart and real account acceptance remain separate QA gates.
+
+Beta policy discovers the newer of npm latest and the legacy beta tag. Stable-only
+policy selects non-deprecated stable versions, even when latest is a prerelease.
+No eligible version is reported as available:null with newer:false. Older installed
+updaters need an exact-version core update to adopt this discovery behavior.
+
+## Shared agent guidance
+
+Ez includes `templates/agent-guidance.md` from the running package in every
+owner-worker prompt, including resumed CLI and desktop conversations and scheduled
+owner work. After the runtime upgrades, the next turn receives the new guidance.
+An already running turn keeps its original prompt. Restricted contact tasks and
+reply-only workers retain their separate, bounded instructions.
+
+Keep general operating defaults in this package-owned file. Keep agent purpose,
+preferences and local conventions in the workspace's `AGENTS.md`, `SOUL.md`,
+`USER.md` and memory files; upgrades preserve them. Shared guidance does not
+grant permissions, and explicit owner instructions take precedence over its
+defaults within existing execution permissions.