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

package/docs/plugin-guide.md

@@ -97,7 +97,7 @@ baseline is:
 ```sh
 pnpm install --frozen-lockfile
 pnpm verify
-npm run release:check
+pnpm run release:check
 git diff --check
 ```
 

package/docs/plugins.md

@@ -334,7 +334,7 @@ only to its authoritative service over the reviewed transport.
 
 ## Verification
 
-`npm run verify` runs offline negative/contract tests. Explicit Docker integration:
+`pnpm run verify` runs offline negative/contract tests. Explicit Docker integration:
 `node docker/plugin-smoke.mjs`. It builds the actual WhatsApp package with the
 synthetic transport in an isolated snapshot and tests installation, start,
 registered CLI, literal file paths, idempotency, restart persistence and

package/docs/releasing.md

@@ -11,12 +11,16 @@ separate release bot is not required.
    update plugin manifest version when present. After lockfile changes, copy
    `pnpm-lock.yaml` to `docker/pnpm-lock.yaml` (npm omits the root lockfile; CI
    checks this shipping copy is identical). Never overwrite a published version.
-2. Run `pnpm install --frozen-lockfile`, `pnpm verify`, `npm run release:check`,
+2. Run `pnpm install --frozen-lockfile`, `pnpm verify`, `pnpm run release:check`,
    `git diff --check`. Review `npm audit --omit=dev` and dependency licenses.
    Record accepted risks with a reason; never run an unreviewed audit fix.
 3. Build both Docker targets from a clean checkout:
    `docker build --target test -t ez-release-tests .` and
    `docker build --target runtime -t ez-release-runtime .`.
+   Docker CI pins the reviewed Codex baseline (`TASK_CODEX_VERSION`) with the
+   existing `CODEX_CLI_VERSION` build argument; update that pin when the native
+   audit advances. Baseline CI does not validate a newly published native version.
+   Managed installs and upgrades keep their existing native version selection.
    Main relay: `EZ_RELAY_IMAGE=ez-release-runtime node docker/smoke.mjs`.
    The WhatsApp Compose overlay has no separate relay image; verify its
    provider integration with the synthetic plugin smoke in `docs/plugins.md`.

package/docs/scheduling.md

@@ -13,6 +13,7 @@ ezenciel-agents-schedule create --name Research --now \
   --text '/goal Complete the authorized research objective. Save evidence, verify the outcome, and send the owner the result.'
 ezenciel-agents-schedule list
 ezenciel-agents-schedule runs
+ezenciel-agents-schedule trigger SCHEDULE_ID --key owner-smoke-20261003
 ezenciel-agents-schedule pause SCHEDULE_ID
 ezenciel-agents-schedule resume SCHEDULE_ID
 ezenciel-agents-schedule remove SCHEDULE_ID
@@ -36,11 +37,89 @@ 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 inherit selected engine settings. Explicit `--cli`, `--model` and
-`--effort` override those choices; omitted values use native defaults. Edits
-preserve existing choices. Historical deferred tasks keep their source context
+New tasks capture selected engine settings. Explicit `--cli`, `--model` and
+`--effort` override those choices. Edits preserve existing choices.
+Core always passes the task's concrete saved model. Creation and edits
+require a model in the captured settings or an explicit `--model`; missing models
+are rejected. Legacy tasks with no saved model remain inspectable, but dispatch
+and executor admission refuse to run them until they are explicitly configured.
+Chat changes and native defaults never supply a missing model at run time.
+To run an existing task outside its cadence, use `trigger ID --key REQUEST_KEY`: it queues
+the task's saved instructions, engine, model, effort and delivery binding in a
+fresh session, without changing its definition or next regular occurrence.
+Model/text/trigger overrides are rejected. Reuse the same request key after an
+uncertain response; it reads back the same run while the relay retains it.
+After a relay restart, inspect native history and provider/canonical receipts
+before issuing another request: the run ledger remains intentionally in memory.
+Paused, stale-owner, overlapping or held tasks and unmet conditions cannot be
+triggered. Historical deferred tasks keep their source context
 available through `ezenciel-agents-schedule context`.
 
+## Registered script schedules
+
+A schedule has one execution type. **Agent** schedules run the saved prompt with
+their saved engine, model and effort, as described below. **Script** schedules run
+a registered, agent-owned script directly: no model, effort, prompt or native
+session is involved.
+
+```sh
+ezenciel-agents-schedule script register book-freshness \
+  --file scripts/book-freshness.mjs --interpreter node [--arg=VALUE ...] [--timeout-seconds 900]
+ezenciel-agents-schedule create actual-book-freshness-guard \
+  --script book-freshness [--arg=VALUE ...] --cron '15 * * * *' --timezone Asia/Dubai
+ezenciel-agents-schedule script list | show ID | update ID [...] | remove ID
+```
+
+The agent writes, tests and maintains the script; core owns registration,
+scheduling, authorization, process execution, cancellation and run receipts.
+A registration records the owner binding, a workspace-relative entry point, an
+installed interpreter (command name on the executor PATH or absolute path),
+literal arguments, a timeout and the entry point's SHA-256 under a new revision.
+It references the workspace file; core keeps no source copy. Paths outside the
+workspace (including symlink escapes) and shell command strings are rejected.
+Core invokes `interpreter entry registrationArgs... scheduleArgs...` directly,
+without a shell. Missing interpreters fail clearly; nothing is installed.
+
+When an occurrence is queued, the run captures the current registration
+revision and hash. Immediately before spawning, the executor requires that
+revision to be current and the entry-point bytes to match. Changed bytes fail
+the run until the agent explicitly runs `script update`. The hash identifies the
+entry-point file only; it does not certify imported modules or other files.
+
+Script runs use the existing scheduler, admission queue, scheduled concurrency
+limit, one-occurrence-per-schedule rule, run records, delivery binding, manual
+`trigger`, pause/resume/edit/remove and `cancel`. They run in the agent's
+isolated environment (relay or host transport) under its normal identity, with
+the executor environment allowlist plus `EZ_RUN_ID`, `EZ_SCHEDULE_ID`,
+`EZ_SCHEDULE_REVISION`, `EZ_DUE_AT`, `EZ_SCRIPT_ID`, `EZ_SCRIPT_REVISION` and
+`EZ_SCRIPT_SHA256`. Use the run/schedule/due identifiers to form a stable
+occurrence identity. External operations go through the bound plugin CLI; a
+script must not read private databases, call providers directly or acquire
+credentials. A script run can read schedule and script state but cannot change
+registrations or schedules.
+
+A script runs with the agent's runtime identity and file access, but not inside
+a native engine's own sandbox (for example host Codex `workspace-write`); register
+only code the agent would be allowed to run itself. An interpreter inside the
+workspace is rejected because it would be unhashed code.
+
+Each registration has a bounded timeout (default 900 seconds, maximum 21600)
+that does not affect agent runs. Timeout and `cancel` stop the process and its
+children. Failed, timed-out or interrupted script runs are not retried, do not
+fall back to an LLM and do not start a debugging agent. Inspect them with
+`runs`, `run RUN_ID`, `failures` and `evidence`: the run shows the script ID,
+revision and hash, queue/start/finish clocks, exit code, cancellation/timeout,
+failure reason and a 4 KiB redacted tail of stdout/stderr. Those records follow
+the normal relay-memory retention. Stdout is diagnostic only. Process success
+means the script exited 0; domain success still requires the owning plugin's
+validation, receipt and canonical readback, which the script performs and
+records. Notifications use `ezenciel-agents-message` under the normal policy;
+routine unchanged runs should stay quiet.
+
+Editing a schedule replaces it completely, so it may switch execution type.
+When replacing an agent schedule with a script, move any judgment the prompt
+performed to its owning workflow first; the script schedule does not carry it.
+
 ## Execution and authority
 
 Due occurrences enter the durable queue with stable IDs and literal task text.
@@ -49,17 +128,20 @@ No identity files or role instructions are generated. Existing workspace Markdow
 provides context, including native `AGENTS.md` discovery and relative links; the
 engine chooses what to read. Per-run native state stays under `control/`.
 
-One foreground turn and one owner-scheduled turn can run at the same time.
-Foreground inputs queue behind foreground work; scheduled turns queue behind
-scheduled work. A long scheduled goal therefore does not block chat. Both streams
+One foreground turn and up to six owner-scheduled turns can run at the same time.
+Set `EZ_SCHEDULED_CONCURRENCY` to a positive integer to change the scheduled-job
+limit; it defaults to six. For Docker deployments, put this setting in the
+existing private relay environment file (`EZ_RELAY_ENV_FILE`); no Compose
+layout migration is needed. Foreground inputs queue behind foreground work;
+scheduled turns queue only when their limit is occupied. A long scheduled goal therefore does not block chat. Both streams
 use the existing admission and executor path, with separate native sessions.
 They share the agent-owned Markdown workspace: the agent coordinates shared file
 updates, and plugins enforce canonical record-write guards. The host keeps plugin
-workspace invocations excluded until both native turns finish.
+workspace invocations excluded until all native turns finish.
 The agent decides when to send through the message CLI.
 A recurring schedule has at most one pending or active occurrence. Shared
-provider resources still need writer coordination. The former four background
-slots are no longer used for owner schedules.
+provider resources still need writer coordination. This is admission to the existing native executor, not a second queue or
+workflow controller.
 
 Production relay/host execution has no wall-clock timeout. The old
 `EZ_EXECUTOR_TIMEOUT_SECONDS` setting is ignored. Individual network/tool waits
@@ -156,6 +238,32 @@ Create a normal recurring schedule with `--every-seconds 900 --when unreviewed-f
 
 `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, including a failed native Codex turn's error message when supplied. A failure without error details remains explicitly unknown; 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.
 
+For a shareable operational projection, use `evidence [RUN_ID] --offset 0 --limit 100`.
+This reads the live relay through its existing authenticated socket, under the
+bound operator or an active unrestricted Telegram owner run. Application/channel,
+external and isolated-task callers cannot use it. It exposes only current-owner
+Telegram foreground/scheduled runs, stable IDs, clocks/status/presets, failure
+metadata without prose, and retained run-associated outbox metadata. No native
+session, prompt, reasoning, tool arguments/results, message text or channel identity
+is returned. Failure text is represented by its SHA-256, not copied or diagnosed.
+
+The response carries exact `readStartedAt`/`observedAt`, `snapshotSha256`, and
+coverage total/offset/limit/returned/nextOffset. Follow `nextOffset` with the same
+`--expected SNAPSHOT_SHA256`; changed retained evidence fails closed and requires
+a fresh traversal. Each page recomputes the projection; no snapshot store or
+background capture is added. History resets on relay restart and is bounded to
+2000 terminal runs and 2000 terminal outbox items; full historical coverage cannot
+be inferred. Unassociated deliveries and excluded scopes remain unknown.
+
+Delivery records identify queued/sent/failed/unknown state and whether a retained
+Telegram receipt contains a valid clock and returned message IDs (only their count
+is exported). The submitted UTF-8 text/voice-text hash can be compared to an exact
+canonical source. It does not prove rendered or current recipient-side content;
+attachments are not exported. Empty receipt lists never prove that no delivery
+occurred. The relay does not retain native tool/delegation events, so that coverage
+is explicitly unavailable. This command does not mark failures reviewed, send
+messages, read private sessions, trigger work or certify owning results.
+
 The prompt controls diagnosis, authorized recovery and quiet notification behavior. Inspect prior effects and receipts before retrying anything. A failed review run itself remains visible as a new failure for the next occurrence.
 
 The Telegram Scheduled tasks menu lists enabled schedules that still have a pending

package/docs/selective-monitoring.md

@@ -178,3 +178,16 @@ After revocation/expiry no subsequent reply may dispatch. Keep these checks
 agent-owned: the owner supplies only necessary confirmation, QR scan if needed,
 and the test contact/message. Do not bypass a missing grant by polling the inbox
 in an unrestricted scheduled owner session or sending through the raw CLI.
+
+Task `send` accepts `voice: true` for spoken replies up to 1,000 characters on sources advertising `taskVoice`. It uses the relay’s configured speech renderer, rechecks authorization after generation, and preserves the same uncertain-send key contract. Synthesis failure happens before the provider is contacted: it returns an error, sends no text and stores no operation, so the same key may be retried. Voice and file attachments cannot be combined.
+
+### Incoming files and images
+
+The restricted MCP `read_attachment` tool accepts only an `incomingId` from the
+current run's correspondence. The channel supplies private bounded bytes through
+`task-document`, bound to its account and exact conversation. Core reuses
+`stageChatAttachment` validation (10 MiB) and returns UTF-8 TXT/Markdown or
+PDF text via Poppler, at most 256000 bytes. JPEG/PNG/WebP images return their
+original bounded pixels as MCP image content to the native engine, never an
+extra inference call or a base64 text prompt. It never accepts an owner file path.
+MP4 clips up to 10 MiB and 120 seconds return at most eight sampled JPEG frames, 640 pixels wide and at most 1 MiB combined, through the same native image content. Speech transcripts supplied by the source remain in incoming context. The audited native CLI accepts text and images, not raw video/audio; sampled frames do not capture every motion. Scanned PDFs with no text layer need OCR and return a clear limitation.

package/docs/upgrades.md

@@ -16,6 +16,8 @@ automatic channel for core and plugins without a saved policy. Existing explicit
 stable or manual policies are preserved. The owner may select either per target.
 The main target and installed plugins version independently.
 
+Queued upgrades leave channel admission open while native work runs. The supervisor pauses admission only after work is idle and releases that pause if a turn raced the check.
+
 The owner chooses the saved update policy. The host supervisor owns
 interruption-safe replacement. There is one host service per agent, not a second
 agent or an additional updater daemon. Its replaceable child runs the normal CLI
@@ -91,6 +93,12 @@ same candidate again and apply the new job; do not edit the old receipt. Only
 Finish the requesting turn after queuing either operation. Verify the main relay
 before requesting a separate plugin upgrade.
 
+Codex version discovery parses machine-readable stdout separately from package
+manager notices on stderr. Invalid stdout fails with a named discovery error;
+it is never repaired by stripping arbitrary lines. A historical generic JSON
+parse error alone does not establish which command or output stream caused it.
+Reconcile the job's completed stages and installed state before retrying.
+
 ## Agent interface
 
 Telegram `/status` shows the relay's loaded version, fresh host version and
@@ -232,7 +240,7 @@ Upgrading does not invent an explicit setting for an omitted field.
 Verify upgrade from the previous supported artifact, retained identity/state,
 failed-health rollback, and rejection of incompatible candidates. Main runtime
 changes also need supervisor restart and requesting-process-exit tests. Run
-`pnpm verify`, `npm run release:check`, packed Docker builds and
+`pnpm verify`, `pnpm run release:check`, packed Docker builds and
 `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.
@@ -283,3 +291,32 @@ the host or create a repair task. An automatically failed or rolled-back version
 is not retried until a newer version appears or the owner explicitly retries.
 Inspect `ez updates check` and `ez updates status` for target diagnostics.
 Actual update transactions retain their existing admission, drain and rollback rules.
+
+### Isolated broker readiness
+
+Isolated activation and rollback explicitly recreate only `plugin-broker` with
+`--no-deps --force-recreate --no-build --pull never --wait`. Plugin-only refresh
+pins the installed broker image ID; main activation uses the newly built image
+and rollback uses the recorded old image. This refreshes the narrow read-only
+host-configuration file mount after atomic replacement. The relay and native
+sessions are preserved during plugin-only refresh. Host-capable updates do not
+start a broker. Existing update admission and drain remain authoritative.
+
+Socket health is liveness only. Before reporting completion, the updater runs
+`docker/broker-readiness.mjs` inside the actual broker, with expected SHA-256
+fingerprints of the host binding, registry and registry configuration. This
+bounded diagnostic checks socket existence, agent/registry ownership, packaged
+source identity, declared command routes, folder grants and reviewed network
+pins. It reads state without rewriting Compose files, executing a plugin,
+creating authorization or supplying `EZ_RUN_ID`. Fingerprints are checked again
+after validation and on the host; a changed binding fails verification.
+`brokerReadiness` and `rollbackBrokerReadiness` in update status are structural
+readbacks at that transaction, not continuous health or native invocation proof.
+A failed refresh or probe enters the existing rollback/recovery path.
+
+A genuine authorized native invocation through the bound launcher, with its real
+receipt, remains separate acceptance evidence. Structural readiness and Docker
+health cannot prove provider delivery or a successful native command. Do not
+invent a run ID for that evidence. The synthetic regression is
+`EZ_RELAY_IMAGE=<exact runtime image ID> node docker/broker-update-smoke.mjs`;
+it uses disposable Linux state, no credentials or provider calls.

package/docs/work-preflight.md

@@ -0,0 +1,9 @@
+# Plugin-backed scheduled preflight
+
+Empty or unchanged provider work can skip a scheduled session. Eligible work uses the schedule's saved execution settings. Core owns admission; installed read-only plugin commands own provider eligibility. Preflight requires the bound plugin broker used by isolated deployments; unavailable broker or provider reads fail closed.
+
+A schedule's `preflight` is `{ "on": "eligible" | "changed", "checks": [{ "alias": "registered-read-only-command", "args": ["literal", "arguments"] }] }`.
+The plugin emits `{ "schemaVersion": 1, "eligible": boolean, "fingerprint": "sha256 hex", "observedAt": "ISO timestamp", "count": integer }`.
+Any check eligible admits the owning saved task; changed mode additionally requires a new combined fingerprint. No domain rules or DAG execution live in core. Empty/unchanged checks advance the ordinary schedule cursor without a run/session. Errors retain a sanitized preflight receipt and skip the occurrence; no empty-success fallback.
+
+Use `--preflight-file FILE` when creating/editing a native task. Editing preserves its condition unless explicitly replaced; `--clear-preflight` removes it. Preflight receipts remain on the native schedule cursor outside the agent workspace. Manual triggers run the same gate; an ineligible manual request reports unmet preflight and creates no run.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jc_stack/ez-agents",
-  "version": "0.1.0-beta.46",
+  "version": "0.1.0-beta.48",
   "private": false,
   "type": "module",
   "description": "A lightweight foundation for persistent business AI assistants using existing AI harnesses, workspaces and plugins.",
@@ -52,7 +52,8 @@
     "scripts/assert-local-registry.mjs",
     ".dockerignore",
     "scripts/trusted-beta.mjs",
-    "scripts/generate-publish-caller.mjs"
+    "scripts/generate-publish-caller.mjs",
+    "pnpm-workspace.yaml"
   ],
   "publishConfig": {
     "access": "public",
@@ -70,7 +71,7 @@
     "verify": "pnpm test && pnpm build",
     "smoke:scheduler": "tsx scripts/smoke-scheduler.ts",
     "smoke": "./bin/ezenciel-agents-docker run --rm --no-deps relay smoke",
-    "prepublishOnly": "npm run verify",
+    "prepublishOnly": "pnpm run verify",
     "registry:up": "docker compose -f registry/docker-compose.yml up -d",
     "registry:down": "docker compose -f registry/docker-compose.yml down",
     "publish:local": "node scripts/publish-local.mjs",

package/pnpm-workspace.yaml

@@ -0,0 +1,7 @@
+# Hold third-party updates for seven days; reviewed first-party releases are exempt.
+minimumReleaseAge: 10080
+minimumReleaseAgeExclude:
+  - "@jc_stack/*"
+  - "@aifit/*"
+trustPolicy: no-downgrade
+blockExoticSubdeps: true

package/scripts/smoke-scheduler.ts

@@ -10,6 +10,7 @@ import { RunStore } from '../src/runs.js'
 import { serveDeliverySocket, createLedgerHandler } from '../src/delivery-socket.js'
 import { packageVersion } from '../src/version.js'
 import { initialPreset } from '../src/ai.js'
+import { discoverDefaults } from '../src/client-defaults.js'
 import { initializeWorkspace } from '../src/workspace.js'
 import type { Update } from 'grammy/types'
 
@@ -21,7 +22,9 @@ const purpose=join(root,'purpose.md');await writeFile(purpose,'Verify native sch
 await initializeWorkspace(workspace,purpose)
 const control=new ControlStore(controlDir,1000),scheduler=new Scheduler(controlDir),runs=new RunStore(controlDir)
 await control.requestPairing(101,101);await control.approveOwner(101)
-const owner=(await control.status()).owner!,execution=await control.captureChoice(initialPreset(cli))
+const initial=initialPreset(cli)
+const defaults=initial.model ? initial : (await discoverDefaults(workspace,{nativeCodexFallback:true})).find(p=>p.cli===cli)
+const owner=(await control.status()).owner!,execution=await control.captureChoice({...initial,model:defaults?.model,effort:defaults?.effort})
 const replies:{at:number;text:string}[]=[]
 const relay=createRelay({workspace,controlDir,pairingTtlMs:1000,executorTimeoutMs:0,executorCli:cli,telegramBotToken:'fixture'})
 // Engine children reach this process's memory ledger through the socket.

package/src/ai.ts

@@ -128,7 +128,45 @@ export const readCuratedModels = async (controlDir?: string): Promise<ModelChoic
   return curated
 }
 
-export const readModels = async (home = homedir(), available = installed, codexHome = join(home, '.codex'), opencodeRunner?: (args: string[]) => Promise<string>, opencodeDataHome?: string, opencodeAllowlist?: string[], curationDir?: string): Promise<ModelChoice[]> => {
+// Let the installed native client refresh its own catalog. No conversation or
+// prompt is submitted; CODEX_HOME is the same agent binding used for execution.
+export const readCodexCatalog = async (codexHome: string, run?: (args: string[], env: NodeJS.ProcessEnv) => Promise<string>): Promise<unknown> => {
+  const env = { ...executorEnvironment(), CODEX_HOME: codexHome }
+  const args = ['debug', 'models']
+  try {
+    const stdout = run ? await run(args, env) : await (async () => {
+      const invocation = executorInvocation('codex', args)
+      return (await promisify(execFile)(invocation.command, invocation.args, {
+        cwd: codexHome, env, timeout: 8000, maxBuffer: 4 * 1024 * 1024,
+      })).stdout
+    })()
+    const catalog = JSON.parse(stdout)
+    if (catalog && Array.isArray(catalog.models) && catalog.models.length) return catalog
+  } catch { /* Older/offline native clients retain their last known catalog. */ }
+  try { return JSON.parse(await readFile(join(codexHome, 'models_cache.json'), 'utf8')) } catch { return {} }
+}
+
+// Claude has no catalog command; its installed help is the native metadata for
+// the selectable model aliases and effort levels. No session or inference runs.
+// Unparseable or unavailable help keeps the client default, never guessed names.
+export const claudeCatalogModels = async (run?: (args: string[]) => Promise<string>): Promise<ModelChoice[]> => {
+  const fallback = [{ cli: 'claude', name: 'claude · client default', efforts: [] as string[] }]
+  let help: string
+  try {
+    help = run ? await run(['--help']) : await (async () => {
+      const invocation = executorInvocation('claude', ['--help'])
+      return (await promisify(execFile)(invocation.command, invocation.args, { env: executorEnvironment(), timeout: 8000, maxBuffer: 1024 * 1024 })).stdout
+    })()
+  } catch { return fallback }
+  const option = (flag: string) => help.split(/\r?\n(?=\s*(?:-\w, )?--)/).find((block) => block.trimStart().replace(/^-\w, /, '').startsWith(`${flag} `))?.replace(/\s+/g, ' ') ?? ''
+  const aliases = [...(option('--model').match(/\(e\.g\. ([^)]*)\)/)?.[1] ?? '').matchAll(/'([a-z][a-z0-9-]{0,31})'/g)].map((match) => match[1])
+  const levels = (option('--effort').match(/\(([a-z][a-z0-9, -]*)\)\s*$/)?.[1] ?? '').split(',').map((level) => level.trim())
+    .filter((level) => safe(level) && allowedEffort(level, undefined, 'claude'))
+  if (!aliases.length) return fallback
+  return [...fallback, ...[...new Set(aliases)].map((alias) => ({ cli: 'claude', model: alias, name: `claude · ${alias}`, efforts: levels }))]
+}
+
+export const readModels = async (home = homedir(), available = installed, codexHome = join(home, '.codex'), opencodeRunner?: (args: string[]) => Promise<string>, opencodeDataHome?: string, opencodeAllowlist?: string[], curationDir?: string, codexRunner?: (args: string[], env: NodeJS.ProcessEnv) => Promise<string>, claudeRunner?: (args: string[]) => Promise<string>): Promise<ModelChoice[]> => {
   const models: ModelChoice[] = []
   const record = (value: unknown): Record<string, unknown> =>
     value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
@@ -147,7 +185,7 @@ export const readModels = async (home = homedir(), available = installed, codexH
     }
   }
   if (await available('codex')) {
-    const cache = await json(join(codexHome, 'models_cache.json'))
+    const cache = record(await readCodexCatalog(codexHome, codexRunner))
     for (const entry of Array.isArray(cache.models) ? cache.models : []) {
       const info = record(entry)
       if (info.visibility !== 'list' || !safe(info.slug)) continue
@@ -161,8 +199,7 @@ export const readModels = async (home = homedir(), available = installed, codexH
     }))
     models.push(...(desktop.length ? desktop : [{ cli: 'codex-gui', name: 'codex-gui · desktop', efforts: [] }]))
   }
-  // Other adapters expose the authenticated client's default, not a guessed catalog.
-  if (await available('claude')) models.push({ cli: 'claude', name: 'claude · client default', efforts: [] })
+  if (await available('claude')) models.push(...await claudeCatalogModels(claudeRunner))
   const allow = opencodeAllowlist ?? opencodeProviderAllowlist()
   if (await available('opencode')) models.push(...await opencodeCatalogModels(opencodeRunner, opencodeDataHome, allow))
   // Pi has separate provider configuration. OpenCode's catalog cannot

package/src/application-channel.ts

@@ -1,6 +1,6 @@
 import { createServer, type Server, type IncomingMessage, type ServerResponse } from 'node:http'
 import { createHash, randomUUID, timingSafeEqual } from 'node:crypto'
-import { mkdir, readFile, writeFile, rename, open, unlink } from 'node:fs/promises'
+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 { RunStore, type RunRecord, type OutboxItem } from './runs.js'
@@ -16,7 +16,11 @@ import { SpeechCreditsDepletedError } from './audio.js'
 
 const hash = (value: string) => createHash('sha256').update(value).digest('hex')
 export const applicationScope = (bindingId: string, scope: string) => hash(JSON.stringify([bindingId, scope]))
-type Binding = { id: string; bindingId: string; tokenHash: string; owner: Owner; shareTelegram?: boolean }
+export type TaskLaunch = { command: string; args: string[]; tasks: "all" | string[] }
+export const validTaskLaunch = (v: unknown): v is TaskLaunch => {
+  const x=v as TaskLaunch; return !!x && Object.keys(x).every(k=>["command","args","tasks"].includes(k)) && /^[a-zA-Z0-9_-]{1,100}$/.test(x.command) && Array.isArray(x.args) && x.args.length>0 && x.args.length<=8 && (x.tasks==="all" || (Array.isArray(x.tasks) && x.tasks.length>0 && x.tasks.length<=128 && x.tasks.every(t=>/^task_[a-f0-9]{32}$/.test(t)))) && x.args.every(a=>typeof a==="string" && a.length<=200 && !/[\x00-\x1f\x7f]/.test(a))
+}
+export type Binding = { id: string; bindingId: string; tokenHash: string; owner: Owner; shareTelegram?: boolean; taskLaunch?: TaskLaunch }
 
 export function validateApplicationRegistration(id: string, token: string | null): void {
   if (!applicationId(id) || (token !== null && !/^[A-Za-z0-9_-]{43,200}$/.test(token))) throw new Error('Use a simple application ID and a random token of at least 256 bits encoded as base64url')
@@ -27,7 +31,7 @@ export class ApplicationBindings {
   async list(): Promise<Binding[]> {
     try {
       const bindings = JSON.parse(await readFile(join(this.controlDir, 'application-bindings.json'), 'utf8'))
-      if (!Array.isArray(bindings) || bindings.some(binding => !applicationId(binding?.id) || !/^[a-f0-9-]{36}$/.test(binding.bindingId) || !/^[a-f0-9]{64}$/.test(binding.tokenHash) || !validOwner(binding.owner) || (binding.shareTelegram !== undefined && typeof binding.shareTelegram !== 'boolean')) || ['tokenHash','id','bindingId'].some(key => new Set(bindings.map(b => b[key])).size !== bindings.length)) throw new Error('Invalid application binding state')
+      if (!Array.isArray(bindings) || bindings.some(binding => !applicationId(binding?.id) || !/^[a-f0-9-]{36}$/.test(binding.bindingId) || !/^[a-f0-9]{64}$/.test(binding.tokenHash) || !validOwner(binding.owner) || (binding.taskLaunch !== undefined && !validTaskLaunch(binding.taskLaunch)) || (binding.shareTelegram !== undefined && typeof binding.shareTelegram !== 'boolean')) || ['tokenHash','id','bindingId'].some(key => new Set(bindings.map(b => b[key])).size !== bindings.length)) throw new Error('Invalid application binding state')
       return bindings
     } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []; throw error }
   }
@@ -51,6 +55,23 @@ export class ApplicationBindings {
       return binding
     } finally { await lock.close(); await unlink(`${file}.lock`) }
   }
+  async taskLaunch(id: string, launch: TaskLaunch | null): Promise<void> {
+    if (launch !== null && !validTaskLaunch(launch)) throw Error('Invalid task launch command')
+    const file=join(this.controlDir,'application-bindings.json'), lock=await open(`${file}.lock`,'wx',0o600)
+    try {
+      const bindings=await this.list(), binding=bindings.find(b=>b.id===id)
+      const owner=(await new ControlStore(this.controlDir,900000).status()).owner
+      if(!binding || !sameOwner(binding.owner,owner))throw Error('Application authority revoked')
+      if(launch)binding.taskLaunch=launch; else delete binding.taskLaunch
+      const previous=await stat(file),tmp=`${file}.${randomUUID()}.tmp`
+      try {
+        await writeFile(tmp,JSON.stringify(bindings),{mode:0o600,flag:'wx'})
+        const created=await stat(tmp)
+        if(created.uid!==previous.uid || created.gid!==previous.gid)await chown(tmp,previous.uid,previous.gid)
+        await rename(tmp,file)
+      }finally{await unlink(tmp).catch(error=>{if((error as NodeJS.ErrnoException).code!=='ENOENT')throw error})}
+    }finally{await lock.close();await unlink(`${file}.lock`)}
+  }
   async authenticate(token: string): Promise<Binding> {
     if (!/^[A-Za-z0-9_-]{43,200}$/.test(token)) throw new Error('Unauthorized application')
     const fingerprint = Buffer.from(hash(token), 'hex')
@@ -65,6 +86,7 @@ export class ApplicationBindings {
     const owner = (await new ControlStore(this.controlDir, 900000).status()).owner
     const binding = (await this.list()).find(item => item.bindingId === origin.bindingId)
     if (!binding || !sameOwner(binding.owner, owner) || !ownsRun(owner, run)) throw new Error('Application authority revoked')
+    if(run.application?.taskAccess)await new Tasks(this.controlDir).applicationAccess(run.application.taskAccess,binding.bindingId)
   }
 }
 
@@ -224,6 +246,17 @@ export class ApplicationChannel {
         if ('followTelegram' in rest) throw new Error('Invalid application request: choose one conversation option')
         input = {...rest, followTelegram: followOwner}
       }
+      if(input && typeof input==='object' && 'taskToken' in input) {
+        const v=input as Record<string,unknown>
+        if(Object.keys(v).some(k=>!['requestId','scope','text','taskToken'].includes(k)) || !applicationId(v.requestId) || typeof v.text!=='string' || !v.text.trim() || v.text.length>16000 || typeof v.taskToken!=='string' || !/^[a-f0-9]{64}$/.test(v.taskToken))throw Error('Invalid application task request')
+        const ticketHash=hash(v.taskToken), access=await new Tasks(this.options.controlDir).applicationAccess(ticketHash,bindingId)
+        const scope='task:'+access.task.id
+        if(v.scope!==scope)throw Error('Invalid application task scope')
+        const id=`r_app_${hash(JSON.stringify([bindingId,v.requestId]))}`, existing=await this.runs.get(id)
+        if(existing){await this.bindings.authorize(existing);if(existing.application?.taskAccess!==ticketHash || existing.texts[0]!==v.text || existing.taskId!==access.task.id)throw Error('Application request ID conflicts with prior task');return existing}
+        const run=await this.runs.create({id,ownerId:ownerId(access.task.owner),ownerEpoch:ownerEpoch(access.task.owner),taskId:access.task.id,texts:[v.text],execution:access.execution,application:{bindingId,scope,requestId:v.requestId,taskAccess:ticketHash}})
+        this.options.wake();return run
+      }
       const value = input as { requestId?: unknown; scope?: unknown; text?: unknown; attachment?: { name?: unknown; data?: unknown }; context?: Record<string, unknown>; expectedNativeSessionId?: unknown; activateTelegram?: unknown; followTelegram?: unknown; ai?: { cli?: unknown; provider?: unknown; model?: unknown; effort?: unknown } }
       if (!value || !applicationId(value.requestId) || !applicationId(value.scope) || typeof value.text !== 'string' || (!value.text.trim() && value.attachment === undefined) || value.text.length > 16000 || Object.keys(value).some(key => !['requestId','scope','text','attachment','context','expectedNativeSessionId','activateTelegram','followTelegram','ai'].includes(key))) throw new Error('Invalid application request')
       if (value.expectedNativeSessionId !== undefined && (typeof value.expectedNativeSessionId !== 'string' || !/^[a-zA-Z0-9_-]{1,160}$/.test(value.expectedNativeSessionId))) throw new Error('Invalid application native session assertion')
@@ -299,6 +332,13 @@ export class ApplicationChannel {
       if (request.method === 'GET' && path === '/v1/registration') {
         send(200, {ownerId: ownerId(binding.owner), bindingId: binding.bindingId, channel: binding.id}); return
       }
+      if(request.method==='POST' && path==='/v1/registration') {
+        let raw='';for await(const chunk of request){raw+=chunk;if(Buffer.byteLength(raw)>1024)throw Error('Invalid application task request')}
+        const v=JSON.parse(raw)
+        if(Object.keys(v).length!==1 || typeof v.taskToken!=='string' || !/^[a-f0-9]{64}$/.test(v.taskToken))throw Error('Invalid application task request')
+        const access=await new Tasks(this.options.controlDir).applicationAccess(hash(v.taskToken),binding.bindingId)
+        send(200,{taskId:access.task.id,expiresAt:access.expiresAt,purpose:access.task.purpose});return
+      }
       if (path === '/v1/telegram' && request.method === 'GET') {
         if ([...url.searchParams.keys()].length) throw new Error('Invalid application Telegram request')
         if (!binding.shareTelegram) { send(403, { error: 'Application authority does not permit Telegram connection' }); return }

package/src/application-cli.ts

@@ -8,11 +8,12 @@ import { applicationId } from './application-origin.js'
 
 async function main() {
   const { values } = parseArgs({ options: {
+    'task-launch-command': {type:'string'}, 'task-launch-args':{type:'string'}, 'task-launch-tasks':{type:'string'}, 'disable-task-launch':{type:'boolean'},
     owner: {type:'string'}, id: {type:'string'}, 'token-file': {type:'string'}, revoke: {type:'boolean'}, list: {type:'boolean'}, help: {type:'boolean'},
     'owner-id': {type:'string'}, rotate: {type:'boolean'}, 'share-owner': {type:'boolean'}, 'share-active': {type:'boolean'},
     'import-scope': {type:'string'}, 'native-session': {type:'string'}, cli: {type:'string'}, 'share-telegram': {type:'boolean'},
   } })
-  if (values.help) { console.log('ezenciel-agents-application --id CHANNEL --token-file PRIVATE_FILE [--owner-id VERIFIED_OWNER_ID] [--share-owner] [--rotate] | --id CHANNEL --revoke | --list | --id CHANNEL --import-scope SCOPE --native-session ID --cli CLI'); return }
+  if (values.help) { console.log('ezenciel-agents-application --id CHANNEL --token-file PRIVATE_FILE [--owner-id VERIFIED_OWNER_ID] [--share-owner] [--rotate] | --id CHANNEL --task-launch-command COMMAND --task-launch-args JSON --task-launch-tasks JSON | --id CHANNEL --disable-task-launch | --id CHANNEL --revoke | --list | --id CHANNEL --import-scope SCOPE --native-session ID --cli CLI'); return }
   if (process.env.EZ_RUN_ID) throw new Error('Application authority is configured by the installing administrator outside agent turns')
   const config = loadControlConfig(), control = new ControlStore(config.controlDir, config.pairingTtlMs)
   if (values.owner && values['owner-id']) throw new Error('Choose one owner registration form')
@@ -25,6 +26,11 @@ async function main() {
   const bindings = new ApplicationBindings(config.controlDir)
   if (values.list) { console.log(JSON.stringify((await bindings.list()).map(({id,bindingId}) => ({id,bindingId})))); return }
   if (!values.id || !applicationId(values.id)) throw new Error('Application ID required')
+  if(values['task-launch-command'] || values['disable-task-launch']) {
+    if(values['token-file'] || values.revoke || values.rotate || values['import-scope'] || (values['task-launch-command'] && values['disable-task-launch']))throw Error('Task launch settings cannot be combined with registration')
+    await bindings.taskLaunch(values.id,values['disable-task-launch'] ? null : {command:values['task-launch-command']!,args:JSON.parse(values['task-launch-args'] ?? '[]'),tasks:JSON.parse(values['task-launch-tasks'] ?? 'null')})
+    console.log(JSON.stringify({ok:true,id:values.id,taskLaunch:!values['disable-task-launch']}));return
+  }
   if (values['import-scope']) {
     const binding = (await bindings.list()).find(item => item.id === values.id)
     if (!binding || !sameOwner(binding.owner, owner) || !applicationId(values['import-scope']) || !values['native-session'] || !/^[a-zA-Z0-9_-]{1,160}$/.test(values['native-session']) || !values.cli) throw new Error('Current application binding, scope, native session and CLI required')

package/src/application-origin.ts

@@ -2,6 +2,7 @@ export type ApplicationOrigin = {
   bindingId: string
   scope: string
   requestId: string
+  taskAccess?: string
   followTelegram?: boolean
   inputText?: string
   attachmentHash?: string
@@ -12,6 +13,7 @@ export const applicationId = (value: unknown): value is string =>
 export const validApplicationOrigin = (value: unknown): value is ApplicationOrigin => {
   const origin = value as ApplicationOrigin | undefined
   return !!origin && /^[a-f0-9-]{36}$/.test(origin.bindingId) && applicationId(origin.scope) && applicationId(origin.requestId) &&
+    (origin.taskAccess === undefined || /^[a-f0-9]{64}$/.test(origin.taskAccess)) &&
     (origin.followTelegram === undefined || typeof origin.followTelegram === 'boolean') &&
     (origin.inputText === undefined || (typeof origin.inputText === 'string' && origin.inputText.length <= 16000)) &&
     (origin.attachmentHash === undefined || /^[a-f0-9]{64}$/.test(origin.attachmentHash)) &&