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

package/.dockerignore

@@ -21,4 +21,5 @@
 !CONTRIBUTING.md
 !CHANGELOG.md
 !scripts/release-check.mjs
+!scripts/stage-qa.mjs
 !default-plugins.json

package/.env.example

@@ -11,7 +11,7 @@ EZ_AGENT_WORKSPACE=./agent
 # EZ_PAIRING_TTL_SECONDS=900
 
 # Optional. Default is 300.
-# EZ_EXECUTOR_TIMEOUT_SECONDS=300
+# Agent execution has no wall-clock timeout. Use /stop or schedule cancel.
 
 # CLI Executor adapter. Supported: agy (default), claude, grok, opencode
 # Switch easily with: pnpm run setup <executor-name>

package/AGENTS.md

@@ -1,5 +1,12 @@
 # ezenciel-agents — Coding Standards & Architectural Invariants
 
+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](docs/standalone-cli.md): no Telegram
+pairing, relay or host executor is required. The main-first Telegram onboarding
+rules below apply only when installing the autonomous relay. When both are
+requested, keep each workspace's authority and registry explicit.
+
 Installed runtime operation uses Docker Compose. Read
 [Docker setup, state and QA](docs/docker-runtime.md). Docker owns relay/plugin services; the existing host CLI and login are shared
 through one generic transport, with separate agent workspaces and sessions.
@@ -56,7 +63,7 @@ This package will be published as an open-source, lightweight Telegram-to-CLI re
 
 ## 6. Concurrency & Workspace Invariants
 - **1 Writer Job per Workspace:** The agent's Markdown folder (`./agent/`) is its mind. Never run concurrent background processes writing to the same workspace simultaneously.
-- Executor jobs queue sequentially in `RunStore`; the poller remains available for cancellation and incoming messages. There is no separate planner or automatic chat ACK lane.
+- Main-conversation jobs queue sequentially in `RunStore`. Scheduled/background work uses separate task directories and native CLI sessions (up to four alongside chat). Never share a mutable task directory. Delegation decisions and goal persistence belong to the agent/executor; there is no automatic planner or canned chat ACK. Production executor runs have no wall-clock timeout; cancellation is explicit.
 
 ## 7. Fail-Closed Authority (Channel Access ≠ Execution)
 - Incoming messages from unapproved senders must **never** spawn the executor. First DM registers an unapproved pairing request, then stops.
@@ -82,3 +89,5 @@ worktree/branch/PR, starting from fetched origin/main. Do not switch or mix work
 another task's checkout. Stage only this task's changes. Keep its worktree through
 review and QA; independent review and green CI precede an authorized merge.
 Never treat task completion as permission to merge or publish.
+
+- In channel-backend mode, the application owns native sessions and actions. Forward normalized inputs with stable run IDs, recover only by idempotent backend submission, and deliver replies through the existing outbox. Never launch a fallback CLI or pass relay credentials into an executor.

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.1.0-beta.13
+
+- Escalate cancelled plugin clients and report container cleanup failures.
+- List the GitHub CLI plugin in the public catalog.
+- Include standalone CLI, native task runtime and integration discovery updates.
+
+- Support incoming-only reply tasks without an opening message; refresh installed
+  guidance for selective setup, implicit follow-up, and quiet account linking.
+
+- Add owner-approved, single-contact messaging tasks, core-bound sends and notes,
+  fresh restricted Codex execution, revocation/expiry, and durable uncertain sends.
+- Task execution requires audited Codex 0.153.4 and a message-v1 event source.
+  Other external events remain blocked; live provider acceptance is pending.
+
+
+- Add optional per-command exposure declarations and `ez tools exposure` with
+  conservative defaults. Declarations do not grant authority.
+- Block registered external events before owner-runtime execution; keep durable
+  blocked records visible in work status. This disables prior external wakeups
+  until an isolated runner exists. Recheck active paired-owner provenance at
+  the local and host launch boundaries.
+
 ## 0.1.0-beta.12 — self-upgrade beta
 
 - Agent-owned main/plugin upgrades with stable-default policy, queued maintenance,

package/CONTRIBUTING.md

@@ -18,6 +18,9 @@ repository. Public docs describe shipped behavior and explicit limitations.
 
 You are responsible for understanding submitted code, including AI-generated
 code, and having the right to contribute it under this repository's license.
+For unreleased feature testing, follow [local QA](docs/local-qa.md): stage an
+immutable beta candidate and provide a simple PA upgrade instruction and feature
+QA flow. A public release is not required for this handoff.
 Do not upload conversation dumps, credentials, QR codes or customer records.
 Installation authority alone does not authorize messaging another person.
 Use synthetic providers for routine tests; live tests need a dedicated account

package/README.md

@@ -1,12 +1,104 @@
-# ezenciel-agents
+# Ez — AI assistants for small businesses
 
-Telegram `/status` shows the running relay and host
-versions plus installed plugin versions. The agent's `ez status` adds verified
-plugin runtime states and upgrade job receipts. See [status and upgrades](docs/upgrades.md).
+**A lightweight, open-source foundation for persistent AI assistants, powered by
+existing AI harnesses.** Give an assistant a purpose, a workspace and tools for
+your business, then work with it through chat.
+
+Ez is for owners of shops, studios and small teams who want help doing everyday
+work: preparing quotes, maintaining business records, researching decisions or
+following up on an agreed task. Each assistant has its own working context and
+responsibilities. The tools and permissions you configure determine what it can
+do.
+
+An AI harness is the client that lets a model reason, use tools and carry out
+work. Ez uses your chosen host CLI and its existing login. The harness does the
+reasoning; Ez connects it to a persistent workspace, messaging, plugins and
+explicit authority boundaries. Telegram is the current owner interface.
+
+## What makes an Ez assistant
+
+| Part | What it contributes |
+|---|---|
+| **Workspace** | Markdown instructions, business context and working files that persist across conversations and changes of AI. |
+| **Harness** | The existing AI client that plans, chooses tools and executes work. See [AI selection](docs/architecture/ai-selection.md). |
+| **Authority** | A verified owner and explicit limits on delegated work. Receiving a message or installing a tool does not grant permission to act. |
+| **Plugins** | Separately maintained tools and connections, with instructions the agent can discover and use. Provider authentication and receipts belong to the plugin. |
+| **Messaging and continuity** | A way to reach the assistant, return results and continue work in its own environment. |
+
+The design starts with one assistant, one mind and clear responsibilities.
+Business instructions live in the workspace; reusable capabilities live in tools
+and plugins. The agent decides how to do the work using those instructions and
+the capabilities available to it.
+
+Use the harness's native capabilities when they meet the need. Add a standalone
+plugin when a missing integration earns the maintenance. Ez keeps the surrounding
+runtime small, so your files, tools and business knowledge remain useful as AI
+clients improve.
+
+## Plugin catalog
+
+Browse the [available plugins](docs/plugin-catalog.md) for capabilities you can
+add to your assistant. The first released plugin is
+[WhatsApp](https://github.com/jdorado/ez-whatsapp), which connects an existing
+WhatsApp account. Ask your working Ez assistant to set it up in Telegram.
+
+## Start with one useful job
+
+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](docs/standalone-cli.md): no Telegram
+pairing, relay or host executor is required. The main-first Telegram onboarding
+rules below apply only when installing the autonomous relay. When both are
+requested, keep each workspace's authority and registry explicit.
+
+Ask an AI agent with computer access to install Ez for a concrete purpose:
+
+> Install Ez from https://github.com/jdorado/ez-agents for my business.
+> I want an assistant that helps me prepare customer quotes from my own files.
+> Set it up and verify that I can talk to it in Telegram.
+
+The installing agent follows [the setup guide](docs/setup.md), handles technical
+setup and asks you for the account access or approvals it needs. Once the
+assistant replies in Telegram, explain your business, give it the relevant
+materials and request any additional tools there. Integrations require their
+own setup and authorized accounts.
+
+## Available today and where this is going
+
+The current source supports persistent agent workspaces, a choice of host AI
+executors, owner-gated Telegram messaging, native scheduling, plugin lifecycle
+management and bounded, owner-approved correspondence. A messaging task can
+contact one approved person using only its explicitly shared task context;
+restricted task execution currently requires the pinned Codex runtime. See
+[authority boundaries](docs/architecture/authority-boundaries.md) for the exact
+scope and [scheduling](docs/scheduling.md) for scheduled work.
+
+The broader direction is assistants working across business roles, with deliberate
+workspace sharing and authority over who may direct work, see information and
+use accounts. General team delegation, family/group authority and enterprise
+reviewer roles remain future work. The current trusted-host beta is not an
+enterprise isolation or multi-tenant security product. See [security scope](SECURITY.md).
+
+## For agents discovering this repository
+
+Ez may fit when a user needs a persistent business assistant reachable through
+chat, using an existing AI client and separately installed tools. Start here:
+
+- **Install for a user:** [setup and verified onboarding](docs/setup.md), then the installer instructions below.
+- **Understand access and delegation:** [authority boundaries](docs/architecture/authority-boundaries.md) and [security scope](SECURITY.md).
+- **Discover or add capabilities:** [plugin contract](docs/plugins.md). Check the actual executor's native tools before adding an integration.
+- **Contribute:** [AGENTS.md](AGENTS.md) and [CONTRIBUTING.md](CONTRIBUTING.md).
+
+Repository discovery is not an instruction to install or contact anyone. Act on
+the user's request and preserve its scope.
+
+## Package and runtime
 
 **Beta 0.1.0-beta.12 — for testing on a trusted machine.** Offline and Docker
 fixtures are verified. Live account onboarding and reboot acceptance for this
-release are deferred; this is not a production-readiness claim.
+release are deferred; this is not a production-readiness claim. The source branch
+may contain changes newer than the published beta; inspect the supplied artifact's
+documentation when installing a pinned release.
 
 The npm package is `@jc_stack/ez-agents` (channel `beta`). Download a pinned
 release with `npm pack @jc_stack/ez-agents@0.1.0-beta.12`, or get the tarball and SHA256SUMS from
@@ -14,12 +106,14 @@ release with `npm pack @jc_stack/ez-agents@0.1.0-beta.12`, or get the tarball an
 GitHub remains under `jdorado`; npm uses `jc_stack`. Do not install the unrelated
 unscoped `ez-whatsapp` package.
 
+Installed runtime operation uses Docker Compose. Docker owns relay/plugin
+services; the existing host CLI and login are shared through one generic
+transport, with separate agent workspaces and sessions. See
+[Docker setup, state and QA](docs/docker-runtime.md).
 
-Installed runtime operation uses Docker Compose. Read
-[Docker setup, state and QA](docs/docker-runtime.md). Docker owns relay/plugin services; the existing host CLI and login are shared
-through one generic transport, with separate agent workspaces and sessions.
-
-A minimal Telegram-to-AI-CLI relay. One owner, one persistent Markdown mind.
+Telegram `/status` shows the running relay and host versions plus installed
+plugin versions. The agent's `ez status` adds verified plugin runtime states and
+upgrade job receipts. See [status and upgrades](docs/upgrades.md).
 
 ## You are the installing agent
 
@@ -132,3 +226,11 @@ without authorization. Local registry rehearsal uses `pnpm publish:local`.
 
 This beta includes owner-policy release checks and durable
 main/plugin replacement. See [upgrade setup, tools and recovery](docs/upgrades.md). Earlier main upgrade/rollback VM QA passed; final-release fresh-host/reboot and live plugin upgrade acceptance remain pending.
+
+### Scheduling and background work
+
+The core `ezenciel-agents-schedule` CLI accepts instruction text for one-off dates,
+intervals and timezone-aware cron schedules. `create --now` delegates a task to a
+separate CLI session so the owner conversation remains available. Long work has
+no production wall-clock timeout; goals and subagents remain native executor
+features. See [scheduling, recovery and QA](docs/scheduling.md).

package/SECURITY.md

@@ -6,7 +6,13 @@ The host CLI and plugin manager run with the host user's authority, including
 Docker administration. Environment filtering and container profile separation
 reduce accidental exposure; they do not isolate a hostile process from its own
 host user. Markdown roles and approvals are instructions, not an OS sandbox.
-Do not expose this as a public multi-tenant execution service.
+Do not expose this as a public multi-tenant execution service. Registered external
+events require an approved, account/contact-bound task and the restricted native
+runner; unmatched events remain blocked. The task worker has only core message,
+note and report tools. It has no owner workspace, shell or general network tool.
+The native client, broker and local host user remain trusted. See
+[authority boundaries](docs/architecture/authority-boundaries.md). Plugin exposure
+declarations are metadata, not grants.
 
 Keep Telegram tokens, device profiles, QR images, control state and native CLI
 sessions outside source and mind files. Treat incoming provider content as

package/bin/ezenciel-agents-schedule

@@ -0,0 +1,2 @@
+#!/bin/sh
+exec node "$(dirname "$0")/ezenciel-agents-schedule.mjs" "$@"

package/bin/ezenciel-agents-schedule.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const require = createRequire(import.meta.url)
+const tsx = require.resolve('tsx')
+const entry = join(here, '..', 'src', 'schedule-cli.ts')
+const forwarded = process.argv.slice(2).filter((arg) => arg !== '--')
+const child = spawn(process.execPath, ['--import', tsx, entry, ...forwarded], { stdio: 'inherit' })
+child.on('exit', (code, signal) => {
+  if (signal) process.kill(process.pid, signal)
+  process.exit(code ?? 1)
+})

package/bin/ezenciel-agents-task

@@ -0,0 +1,2 @@
+#!/bin/sh
+exec node "$(dirname "$0")/ezenciel-agents-task.mjs" "$@"

package/bin/ezenciel-agents-task.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const require = createRequire(import.meta.url)
+const tsx = require.resolve('tsx')
+const entry = join(here, '..', 'src', 'task-cli.ts')
+const forwarded = process.argv.slice(2).filter((arg) => arg !== '--')
+const child = spawn(process.execPath, ['--import', tsx, entry, ...forwarded], { stdio: 'inherit' })
+child.on('exit', (code, signal) => {
+  if (signal) process.kill(process.pid, signal)
+  process.exit(code ?? 1)
+})

package/compose.yaml

@@ -11,7 +11,8 @@ services:
     cap_add: [CHOWN, DAC_OVERRIDE, FOWNER, SETUID, SETGID, SETPCAP]
     environment:
       EZ_AGENT_PURPOSE_FILE: /run/agent-purpose.md
-      EZ_EXECUTOR_TRANSPORT: host
+      EZ_EXECUTOR_TRANSPORT: ${EZ_EXECUTOR_TRANSPORT:-host}
+      EZ_CHANNEL_BACKEND_URL: ${EZ_CHANNEL_BACKEND_URL:-}
       EZ_AGENT_WORKSPACE: ${EZ_AGENT_WORKSPACE:?Set this agent workspace}
       EZ_CONTROL_DIR: ${EZ_CONTROL_DIR:?Set this agent control directory}
       EZ_EXECUTOR_CLI: ${EZ_EXECUTOR_CLI:?Set the host installation CLI}

package/docker/recovery.ts

@@ -2,10 +2,10 @@ import { RunStore } from '../src/runs.js'
 
 // Called only after the deployment's kernel writer lock is held. No worker
 // from a previous container can still own this deployment; PIDs may be reused.
-export const recoverInterruptedRuns = async (controlDir: string) => {
+export const recoverInterruptedRuns = async (controlDir: string, channelBackend = false) => {
   const store = new RunStore(controlDir)
   for (const run of await store.list()) {
     if (run.status === 'running')
-      await store.patch(run.id, { status: 'failed', endedAt: new Date().toISOString() })
+      await store.patch(run.id, { status: channelBackend && !run.pid ? 'queued' : 'failed', endedAt: new Date().toISOString() })
   }
 }

package/docker/run.ts

@@ -21,12 +21,12 @@ try { privateEnv = parseEnv(readFileSync(3, 'utf8')) } catch (error) {
   if ((error as NodeJS.ErrnoException).code !== 'EINVAL' && (error as NodeJS.ErrnoException).code !== 'EBADF') throw error
 } finally { try { closeSync(3) } catch {} }
 for (const [key, value] of Object.entries(privateEnv)) {
-  if (value !== undefined && ['TELEGRAM_BOT_TOKEN', 'GEMINI_API_KEY', 'OPENAI_API_KEY'].includes(key)) process.env[key] = value
+  if (value !== undefined && ['TELEGRAM_BOT_TOKEN', 'GEMINI_API_KEY', 'OPENAI_API_KEY', 'EZ_CHANNEL_BACKEND_TOKEN'].includes(key)) process.env[key] = value
 }
 privateEnv = {}
 const [command = 'start', ...args] = process.argv.slice(2)
 process.argv = [process.argv[0], '', ...args]
-if (['start', 'smoke'].includes(command)) await recoverInterruptedRuns(loadConfig().controlDir)
+if (['start', 'smoke'].includes(command)) await recoverInterruptedRuns(loadConfig().controlDir, Boolean(loadConfig().channelBackendUrl))
 if (command === 'start') {
   const relay = createRelay(loadConfig())
   const heartbeat = '/state/control/heartbeat.json'

package/docs/architecture/authority-boundaries.md

@@ -1,14 +1,116 @@
 # Authority boundaries
 
-The relay pairs one verified Telegram owner before execution; foreign senders
-and groups do not acquire execution rights. Replies use the run-bound source
-chat. Plugin events are untrusted content, queued in the same single-writer lane;
-subscription permission is not permission to reply or execute incoming demands.
-
-The host CLI runs as the trusted installing user. Its Markdown role, confirmation
-tools, environment filtering and private state layout do not create adversarial
-OS isolation. The plugin manager has Docker administration access. Container
-profile separation does not protect against a hostile host administrator.
-
-See [SECURITY.md](../../SECURITY.md) for the supported security scope and
-[Docker runtime](../docker-runtime.md) for the actual process/storage boundary.
+The core pairs one Telegram owner and owns authority across providers. Plugins
+provide transport, authentication, capture, and receipts. Their exposure metadata
+is discovery information, never a grant. A CRM can contain external text too;
+marking it internal does not confer owner authority.
+
+## Messaging v1
+
+The owner asks the agent to contact one person for a bounded purpose. The owner
+agent prepares a proposal with `ezenciel-agents-task propose`: registered source,
+exact canonical contact, purpose, explicitly shareable context, and expiry (up to
+72 hours). Telegram displays that exact proposal for approval. The core binds it
+to the verified owner, current source registration, and connected account. The
+owner does not edit JSON. The agent uses `list` and `revoke` when asked.
+
+After approval the relay starts a restricted task, including the initial outgoing
+message. Incoming-only tasks instead wait for new correspondence and never create
+an opening run. Their task records use version 2 so older task readers fail closed. Matching new correspondence resumes that task in a fresh native session.
+Other contacts remain blocked. Each task has at most 30 distinct text sends;
+there are no payments, attachments, extra recipients, plugin installation,
+settings changes, or access to owner memory. A contact can have one active or
+pending task at a time. Completed, revoked, expired, replaced-source, and changed-
+account grants cannot dispatch further messages.
+
+The worker receives only the approved dossier, its notes, its operation receipts,
+and rechecked correspondence for its contact. All dossier contents may be shared
+with that contact. The agent judges how to pursue the purpose; code does not prove
+that each sentence serves the booking or that a correspondent is truthful. A
+prompt injection can still derail a task or elicit its shared context. It cannot
+use the provided tools to read owner files or select another destination.
+
+## Native execution and core tools
+
+V1 uses audited Codex CLI **0.153.4** for task work, regardless of the owner's
+selected executor. Missing or different versions fail closed; upgrading this pin
+requires repeating the native tool inventory test. Owner work retains its normal
+executor. The task runner creates a fresh ephemeral home/session, skips user
+config, rules and ancestor project instructions, and disables shell, file/image,
+browser, apps, hooks, memory and agent spawning tools. A native permissions
+profile denies general filesystem access and tool network access. No owner
+workspace or conversation is passed to this runner. The runner uses the pinned
+CLI's bundled model catalog with task-specific tool defaults: direct MCP calls,
+no model-added patch tools, experimental tools or collaboration, and no deferred
+tool discovery. Model metadata can override feature flags, so flags alone are
+insufficient. The native inventory test uses a real bundled model entry and must
+prove the five bounded task tools work without additional action tools.
+
+A core stdio MCP broker exposes `context`, `send`, `note`, `report`, and `complete`.
+The native client also lists resource helpers, but the broker serves no resources.
+Only these five tools have native approval bypass configured: the core rechecks
+the grant on each call. Broker requests cross host/relay through private atomic
+control files; only the relay dispatches provider writes. Model tool arguments
+never choose a recipient, account, control path, shell command, or permission.
+The native harness and broker are trusted processes; this is model-tool
+containment, not isolation from a malicious native executable or local host user.
+Native configuration reference: [Codex configuration](https://learn.chatgpt.com/docs/config-file/config-reference).
+
+Task notes live under protected `control/tasks/`, separate from the owner mind.
+Reports go to the owner's Telegram outbox, visibly labelled as task reports;
+they are not inserted as owner instructions or trusted memory. The owner mind
+keeps its existing `inbox/` and `work/` organization. No database or general memory
+index is introduced.
+
+## Provider protocol
+
+A registered Unix event source advertises `taskProtocol: "message-v1"` and a
+stable string `accountId` in `events-head`. The core calls `task-watch` with that
+account, exact `conversationId`, and expiry to request bounded capture attention.
+The existing events/events-check protocol supplies incoming messages. This
+subscription grants attention only; execution still requires the core grant.
+
+For sends the core supplies `task-send` with those same bound IDs, text, and a
+core-prefixed idempotency key. The adapter checks account consistency immediately
+before provider dispatch and returns `{accountId, conversationId, key, state:
+"accepted", receiptId}`. Acceptance is not delivery or booking confirmation.
+The WhatsApp adapter implements this protocol for individual contacts. Another
+provider, including a Gmail/Composio adapter, can implement the same transport
+contract without implementing authority policy; those adapters are not supplied
+by this change.
+
+Before dispatch the core durably records an uncertain operation. A validated
+receipt changes it to accepted. Crashes, timeouts, malformed receipts and lost
+responses remain uncertain; replaying the same key does not send again, and a
+changed payload under the same key is rejected. The agent must report uncertainty
+for owner inspection. V1 has no automatic uncertain-send reconciliation. Core
+revocation and send acceptance are serialized; revocation cannot undo a message
+already dispatched. Expired task watches may still leave captured provider
+records, but cannot launch task work.
+
+## Compatibility and limits
+
+Unmatched events retain terminal `cancelled` plus
+`external-execution-unavailable`. Task runs use record version 2; older readers
+reject/skip them instead of executing them with owner access. Existing version-1
+owner runs remain readable. Package state schema stays 1, but rollback suspends
+task processing until a task-aware version returns; rollback does not replay
+messages or erase task receipts. Update host and relay together. A missing or
+outdated host fails task launch closed.
+
+The installing host user remains trusted and can modify local control state.
+Owner runs can use the plugin manager and Docker administration; content read
+inside owner work still depends on native protections and agent judgment. This
+is not a public multi-tenant execution service. Family delegation, payments,
+enterprise reviewer agents, arbitrary file sharing, and other restricted native
+executors are deferred.
+
+Verify with `pnpm verify`, Docker test/runtime targets and smoke fixtures.
+`EZ_TEST_NATIVE_TASKS=1 pnpm exec tsx --test test/task-native.test.ts` checks the
+actual pinned native tool inventory and executes a synthetic model/broker/provider
+conversation without real credentials or external sends. Real Telegram-owner to
+WhatsApp-correspondent acceptance remains separate live QA requiring an
+authorized account/contact.
+
+For plain-language intent, onboarding defaults and source setup see
+[selective monitoring](../selective-monitoring.md).

package/docs/architecture/event-sources.md

@@ -1,11 +1,12 @@
 # Local event sources
 
-A plugin owns capture, authentication and eligibility. The relay owns execution.
+A plugin owns capture, authentication and subscription filtering. The core owns
+authority and execution; subscription filtering cannot grant permissions.
 Register through `ezenciel-agents-source --name NAME --socket /absolute/service.sock`;
 inspect with `--list`, remove with `--name NAME --remove`. Registration pins the
 paired owner, assigns a new binding ID and starts at the provider's current head.
-Same-user plugins are trusted installed code; private Unix sockets are the boundary,
-not a sandbox against other programs running as that user.
+Registered plugins are trusted installed code. Private Unix sockets bind a local
+transport, not an authorization claim from message content or an adversarial sandbox.
 
 POST JSON `{ "command": "...", "args": {} }` to `/` over the Unix socket.
 Return HTTP 200 with `{ "ok": true, "data": ... }`:
@@ -19,7 +20,8 @@ Return HTTP 200 with `{ "ok": true, "data": ... }`:
 Each event is `{id, conversationId, receivedAt, text}`. IDs are at most 100 ASCII
 letters/digits/underscore/hyphen; conversation IDs at most 200 characters;
 receivedAt is epoch milliseconds; text at most 16000 characters. Responses are
-bounded to 256 KiB and three seconds. Plugin-specific policy stays in the plugin.
+bounded to 256 KiB and three seconds. Provider capture/filtering stays in the plugin;
+execution authority stays in the core.
 
 The host polls each second and waits for two seconds of quiet, ten seconds of
 age, or ten events. It groups by conversation and persists the batch before
@@ -29,6 +31,9 @@ creation; it does not promise exactly-once external actions after executor failu
 
 Before starting queued work, recheck binding, owner and provider eligibility.
 Unavailable sources keep work queued; removed subscriptions cancel empty runs.
-No check can retract work already started. External observations use fresh executor
-sessions and explicitly carry no owner-instruction or send authority. They share
-the existing one-writer queue and secret whitelist. No provider SDK is imported.
+No check can retract work already started. Eligible external runs are now recorded
+as blocked (`external-execution-unavailable`), with no executor launch. They do
+not borrow the owner workspace, session or tools. The existing source cursor and
+deduplication remain intact; blocked work does not retry automatically. Work status
+shows the blocked count. No provider SDK or provider-specific authority is imported.
+See [authority boundaries](authority-boundaries.md).

package/docs/channel-backend.md

@@ -0,0 +1,36 @@
+# Application channel backend
+
+An optional backend receives owner-authorized Telegram turns instead of a CLI.
+The existing private-chat gate, inbox batching, media downloads and outbox remain
+in use. This is still one approved owner per bot, not shared-bot tenant routing.
+
+Set `EZ_CHANNEL_BACKEND_URL` to an HTTPS endpoint and put
+`EZ_CHANNEL_BACKEND_TOKEN` in the private relay env file. For Compose also set
+`EZ_EXECUTOR_TRANSPORT=backend`; no host CLI heartbeat is required. The existing
+workspace/control paths and pairing remain mandatory. Loopback HTTP is allowed
+for isolated local tests. Redirects and URL credentials are rejected.
+
+POST carries version 1, channel `telegram`, stable `event_id`, numeric strings
+`sender_id` / `chat_id`, and `items` with text, message_id, sent_at, album_id and
+optional attachment `{type,data}` (base64, at most 12 MB decoded per item).
+The application must bound and validate the whole body, bind sender identity to
+its authenticated account, and deduplicate the stable event ID before actions.
+It must support up to ten normalized items, including a received album.
+
+The response is `{status,reply}`. `queued` or `running` yields and resubmits the
+same event after four seconds. `complete` or `failed` supplies a final string
+reply, queued once with a deterministic outbox ID. Backend completion and
+Telegram delivery are separate; an uncertain send never replays the operation.
+Restart resubmits interrupted backend runs using the original ID. Permanent
+4xx responses leave a failed relay run for operator inspection; transient
+failures back off. No response body or credential is logged.
+
+Native `/new` and AI settings belong to the application. `/stop` cannot cancel
+an application job and explicitly reports that limitation. `/cancel` removes
+pending relay work only; it does not undo work already accepted by a backend.
+External plugin/maintenance wakes do not dispatch through this channel backend.
+
+Backend mode handles owner Telegram intake only. Existing native schedules,
+restricted messaging tasks, plugin events and maintenance prompts are not
+forwarded to the application and cannot launch a fallback CLI. Their scheduling
+and authority remain separate from the application's own job lifecycle.

package/docs/local-qa.md

@@ -0,0 +1,45 @@
+# Local feature QA
+
+Use the existing local-tarball updater for unreleased features. No npm publication,
+registry server, new daemon or runtime upgrade flow is needed. A developer stages
+an immutable candidate in the PA's local tools directory. The agent reads its
+manifest and uses `ez updates prepare main --file ...` and `apply` on the owner's
+request. Automatic public update policy stays unchanged.
+
+Stage from a clean, reviewed feature checkout:
+
+```sh
+node scripts/stage-qa.mjs --source /absolute/feature-checkout \
+  --catalog /absolute/deployment/tools/qa --label beta-12 \
+  --version 0.1.0-beta.12.qa.1 --flow /absolute/feature-QA.md
+```
+
+`beta-12` is a local catalog label, distinct from public `0.1.0-beta.12`. The
+manifest records the private version, source commit and archive SHA-256. Only
+package version and `ezQa` provenance metadata differ from the source npm package.
+Do not publish these private archives. Each new candidate gets a new label and a
+version newer than the PA's installed version; labels are never overwritten.
+
+Add the catalog path and the following instructions to the PA's local TOOLS.md:
+
+> When the owner requests a beta number, first inspect the matching beta-N entry
+> in the local QA catalog. Read manifest.json and QA.md. Check the archive SHA-256
+> against the manifest, then prepare that local file using the existing updater.
+> Verify the returned version and hash match. Apply only on the owner's explicit
+> upgrade request, without --automatic, and finish the turn so the supervisor can
+> replace the runtime. On completion, inspect the receipt and both loaded host and
+> relay versions before reporting success. Provide the feature's short QA flow.
+> If no local entry exists, report that; do not silently substitute a public beta.
+> Follow an explicit request for a public npm release separately.
+
+For every feature, the developer handoff includes the beta label, exact private
+version, source commit, checks completed and a short user-facing QA flow with
+expected results. Include any limitations. A prepared archive or healthy service
+does not prove the feature works; read back its result through the PA.
+
+Before handing off a candidate, extract it into a fresh directory, copy
+docker/pnpm-lock.yaml to pnpm-lock.yaml, run frozen install and applicable tests,
+and prepare it through the target PA's updater. Preparation validates admission
+without stopping services. Preserve that receipt for the agent to inspect, and
+leave application to the owner's chat request. If deployment/schema compatibility
+fails, fix or review the migration; never bypass the updater's checks.