@jc_stack/ez-agents 0.1.0-beta.47 → 0.1.0-beta.49

package/docs/scheduling.md

@@ -55,6 +55,112 @@ Paused, stale-owner, overlapping or held tasks and unmet conditions cannot be
 triggered. Historical deferred tasks keep their source context
 available through `ezenciel-agents-schedule context`.
 
+## Ordered setup fallback
+
+An agent task may list up to three fallback setups after its saved one, for
+example `claude · opus → claude · sonnet → codex · gpt-6-sol`:
+
+```sh
+ezenciel-agents-schedule create --name Daily --cli claude --model opus \
+  --cron '0 9 * * *' --timezone Asia/Dubai --text 'Prepare the daily report.' \
+  --fallback cli=claude,model=sonnet,effort=medium --fallback cli=codex,model=gpt-6-sol
+```
+
+`edit` keeps the saved fallbacks unless `--fallback` replaces them or
+`--clear-fallbacks` removes them. Setups must be distinct and each needs a model.
+
+Core advances to the next setup only with typed evidence that nothing ran: the
+CLI is not installed or executable, or the provider rejected the turn before any
+model output, tool or hook item (quota/rate limit, billing, overload, server
+error, unavailable model or bad request). It stops, without replay, on access
+denial (authentication, account or organization), cancellation, relay shutdown,
+a schedule edit, a policy or unknown error, an interrupted transport, or any
+failure after work began. Evidence comes from structured events only: Codex
+native-session `codexErrorInfo` and Claude `stream-json` error fields (scheduled
+Claude runs use `--output-format stream-json`; the host forwards only a compact
+startup summary). Other engines advance only when their CLI is unavailable.
+
+A quota rejection skips the remaining setups in the same quota scope: the native
+client (`claude`, `codex` including desktop and custom Codex providers, `grok`)
+or the upstream provider for OpenCode/Pi models. A different credential alone is
+never treated as an independent allowance. Each setup runs at most once per
+occurrence.
+
+Every attempt keeps the same run ID, occurrence, schedule revision, workspace,
+delivery binding and scheduled concurrency slot, in a fresh native session.
+`run RUN_ID` shows `attempts`: each setup, quota scope, outcome, failure category
+(`cli-unavailable`, `quota`, `provider-rejected`, `access-denied`,
+`after-work-began`, `uncertain`, or `same-quota-scope` for a skipped setup), exit
+code and reported reset time. If every setup is unavailable the run fails with
+reason `setups-unavailable`, a summary of each setup, and an owner notice on
+Telegram-bound tasks. Core never purchases credits, enables overage or consumes
+reset credits; the next regular occurrence runs normally.
+
+## Registered script schedules
+
+A schedule has one execution type. **Agent** schedules run the saved prompt with
+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.
@@ -63,17 +169,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
@@ -170,6 +279,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,7 +16,7 @@ automatic channel for core and plugins without a saved policy. Existing explicit
 stable or manual policies are preserved. The owner may select either per target.
 The main target and installed plugins version independently.
 
-Queued upgrades leave channel admission open while native work runs. The supervisor pauses admission only after work is idle and releases that pause if a turn raced the check.
+Core upgrades leave channel admission open while native work runs, then pause it after work is idle and recheck races. Plugin upgrades build while native work continues. Activation closes the existing registry admission lock, drains in-flight plugin command leases, and replaces the plugin under that lock. New native plugin calls wait for admission; an outdated revision fails before provider execution and must be rediscovered. No admitted provider operation is replayed. The shared broker and native sessions remain running. Core upgrades still require the full native-work drain. A plugin update also retains that drain if an operator replaced the broker’s single-file host binding (for example to approve new network pins), because that case still requires broker recreation.
 
 The owner chooses the saved update policy. The host supervisor owns
 interruption-safe replacement. There is one host service per agent, not a second
@@ -93,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
@@ -147,9 +153,7 @@ is required. Stable automation excludes prereleases, major changes and 0.x minor
 changes. Beta policy permits compatible prereleases. Downgrades are rejected;
 rollback is a recovery operation for the previous installation only.
 
-`apply` records one durable queued job. **The agent must finish its turn after
-queuing it.** It must not wait for completion in that same turn. The supervisor
-pauses new run admission, drains already-started work, then consumes the job.
+`apply` records one durable queued job. **For a core upgrade, the agent must finish its turn after queuing it** so the supervisor can drain native work. A plugin upgrade can complete while that turn continues; only plugin-call admission is held during activation. Calls already executing finish first.
 One job at a time; an unresolved recovery blocks new upgrades. The agent processes
 multiple requested packages over successive update requests.
 
@@ -285,3 +289,28 @@ 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 core activation and rollback explicitly recreate only `plugin-broker` with
+`--no-deps --force-recreate --no-build --pull never --wait`. Core activation uses the newly built image and rollback uses the recorded old image to refresh the single-file host binding. Plugin-only activation and rollback change directory-mounted registry files, verify the existing broker in place, and refresh its generated plugin-version inventory. They preserve the broker socket, relay and native sessions. Host-capable updates do not
+start a broker. Existing update admission and drain remain authoritative.
+
+Socket health is liveness only. Before reporting completion, the updater runs
+`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.47",
+  "version": "0.1.0-beta.49",
   "private": false,
   "type": "module",
   "description": "A lightweight foundation for persistent business AI assistants using existing AI harnesses, workspaces and plugins.",

package/src/ai-cli.ts

@@ -1,38 +1,51 @@
 import { parseArgs } from 'node:util'
 import { randomBytes } from 'node:crypto'
 import { join } from 'node:path'
-import { readFile } from 'node:fs/promises'
-import { readModels, presetProvider, validateSelection, type AiPreset } from './ai.js'
+import { mkdir, readFile } from 'node:fs/promises'
+import { authProfileStatus, readModels, presetProvider, sameChoice, sameEngine, validateSelection, type AiPreset, type ModelChoice } from './ai.js'
+import { cliHome } from './auth-profile.js'
 import { ControlStore } from './control-state.js'
 
-const {values,positionals}=parseArgs({allowPositionals:true,options:{help:{type:'boolean'},cli:{type:'string'},provider:{type:'string'},model:{type:'string'},effort:{type:'string'}}})
+const usage='Usage: ezenciel-agents-ai list | select --cli <installed-cli> [--auth-profile <name>] [--provider <provider>] [--model <model>] [--effort <effort>] | default | profiles | profile add --cli codex|claude --auth-profile <name>'
+const {values,positionals}=parseArgs({allowPositionals:true,options:{help:{type:'boolean'},cli:{type:'string'},'auth-profile':{type:'string'},provider:{type:'string'},model:{type:'string'},effort:{type:'string'}}})
 if(values.help){
-  console.log('Usage: ezenciel-agents-ai list | select --cli <installed-cli> [--provider <provider>] [--model <model>] [--effort <effort>] | default\nChoose only values returned by list. Selection affects subsequent messages; default makes the selected AI the choice for new conversations. Queued work is unchanged.')
+  console.log(`${usage}\nChoose only values returned by list. Selection affects subsequent messages; default makes the selected AI the choice for new conversations. Queued work is unchanged.\nAuth profiles are separate owner-provisioned Codex/Claude logins with their own configuration and sessions; changing profile starts a new conversation. profile add creates an empty home and prints the native login command for the owner to run; profiles reports read-only login status without secrets.`)
   process.exit(0)
 }
 if (!process.env.EZ_CONTROL_DIR) throw new Error('Use this agent’s bound control directory')
-const catalog=await readFile(join(process.env.EZ_CONTROL_DIR,'host-executor','models.json'),'utf8')
-  .then(text=>JSON.parse(text)).catch(()=>readModels(undefined,undefined,join(process.env.EZ_CONTROL_DIR!,'cli','codex'),undefined,undefined,undefined,process.env.EZ_CONTROL_DIR))
-if(positionals[0]==='list')console.log(JSON.stringify(catalog))
+const controlDir=process.env.EZ_CONTROL_DIR
+const authProfile=values['auth-profile']
+const catalog=():Promise<ModelChoice[]>=>readFile(join(controlDir,'host-executor','models.json'),'utf8')
+  .then(text=>JSON.parse(text)).catch(()=>readModels(undefined,undefined,join(controlDir,'cli','codex'),undefined,undefined,undefined,controlDir))
+if(positionals[0]==='list')console.log(JSON.stringify(await catalog()))
+else if(positionals[0]==='profiles')console.log(JSON.stringify(await authProfileStatus(controlDir)))
+else if(positionals[0]==='profile' && positionals[1]==='add'){
+  if(!authProfile)throw new Error('profile add requires --auth-profile <name>')
+  const home=cliHome(controlDir,values.cli||'',authProfile)
+  const created=await mkdir(home,{recursive:true,mode:0o700})
+  const login=values.cli==='codex' ? `CODEX_HOME=${home} codex login`
+    : `CLAUDE_CONFIG_DIR=${home} claude auth login (or store a \`claude setup-token\` token in ${home}/oauth-token, mode 600)`
+  console.log(JSON.stringify({cli:values.cli,authProfile,home,created:created!==undefined,ownerLogin:login}))
+}
 else if(positionals[0]==='default'){
-  const control=new ControlStore(process.env.EZ_CONTROL_DIR,900000)
+  const control=new ControlStore(controlDir,900000)
   const state=await control.status()
   const selected=state.ai?.presets.find(p=>p.id===state.ai?.selectedId)
   if(!selected)throw new Error('No selected AI')
-  await validateSelection(selected,catalog)
+  await validateSelection(selected,await catalog())
   await control.defaultPreset(selected.id)
   console.log(JSON.stringify({default:selected,applies:'new conversations; current and queued work unchanged'}))
 }
 else if(positionals[0]==='select'){
-  const preset:AiPreset={id:randomBytes(8).toString('hex'),name:[values.provider,values.model||values.cli,values.effort].filter(Boolean).join(' · '),cli:values.cli||'',provider:values.provider,model:values.model,effort:values.effort}
-  await validateSelection(preset,catalog)
-  const control=new ControlStore(process.env.EZ_CONTROL_DIR,900000)
+  const preset:AiPreset={id:randomBytes(8).toString('hex'),name:[values.provider,values.model||values.cli,values.effort].filter(Boolean).join(' · ')+(authProfile ? ` @${authProfile}` : ''),cli:values.cli||'',provider:values.provider,...(authProfile ? {authProfile} : {}),model:values.model,effort:values.effort}
+  await validateSelection(preset,await catalog())
+  const control=new ControlStore(controlDir,900000)
   const state=await control.status()
   if(!state.ai)throw new Error('Agent AI settings are not initialized')
-  const existing=state.ai.presets.find(p=>p.cli===preset.cli&&p.provider===preset.provider&&p.model===preset.model&&p.effort===preset.effort)
+  const existing=state.ai.presets.find(p=>sameChoice(p,preset))
   const selected=existing||preset
   if(!existing)await control.savePreset(selected)
   const current=state.ai.presets.find(p=>p.id===state.ai!.selectedId)!
-  await control.selectPreset(selected.id,state.activeSession?.sessionId??null,current.cli!==selected.cli||presetProvider(current)!==presetProvider(selected)||Boolean(state.activeSession&&!state.activeSession.cli))
+  await control.selectPreset(selected.id,state.activeSession?.sessionId??null,!sameEngine(current,selected)||presetProvider(current)!==presetProvider(selected)||Boolean(state.activeSession&&!state.activeSession.cli))
   console.log(JSON.stringify({selected,defaultUnchanged:true,applies:'subsequent messages; queued work keeps its captured choice'}))
-}else throw new Error('Use list, select --cli <installed-cli> [--provider <provider>] [--model <model>] [--effort <effort>], or default')
+}else throw new Error(usage)

package/src/ai.ts

@@ -5,12 +5,20 @@ import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
 import { homedir } from 'node:os'
 import { join, delimiter } from 'node:path'
-import { executorEnvironment, executorInvocation, executorKey, resolveExecutor } from './executor.js'
+import { CliUnavailableError, executorEnvironment, executorInvocation, executorKey, resolveExecutor } from './executor.js'
 import { desktopCodexPath } from './desktop-bridge.js'
+import { AUTH_PROFILE_CLIS, claudeAuthEnvironment, cliHome, isAuthProfile, listAuthProfiles } from './auth-profile.js'
 
-export type AiPreset = { id: string; name: string; cli: string; provider?: string; model?: string; effort?: string }
-export type ExecutionChoice = { sessionId: string; preset: AiPreset }
-export type ModelChoice = { cli: string; provider?: string; model?: string; name: string; efforts: string[] }
+export type AiPreset = { id: string; name: string; cli: string; provider?: string; authProfile?: string; model?: string; effort?: string }
+// Optional ordered fallbacks are tried only for a scheduled occurrence that never started work.
+export type ExecutionChoice = { sessionId: string; preset: AiPreset; fallbacks?: AiPreset[] }
+export const MAX_FALLBACKS = 3
+export type ModelChoice = { cli: string; provider?: string; authProfile?: string; model?: string; name: string; efforts: string[] }
+type Engine = { cli?: string; authProfile?: string }
+// A native conversation belongs to one client and one credential home.
+export const sameEngine = (a: Engine, b: Engine) => a.cli === b.cli && a.authProfile === b.authProfile
+export const sameChoice = (a: Omit<AiPreset, 'id' | 'name'>, b: Omit<AiPreset, 'id' | 'name'>) =>
+  sameEngine(a, b) && a.provider === b.provider && a.model === b.model && a.effort === b.effort
 const safe = (s: unknown): s is string => typeof s === 'string' && /^[a-zA-Z0-9_./:-]{1,160}$/.test(s)
 const knownClis = ['grok', 'codex', 'codex-gui', 'claude', 'opencode', 'pi']
 const nativeEffort = (cli: string, effort: string) =>
@@ -20,13 +28,15 @@ export const isPreset = (p: unknown): p is AiPreset => {
   const v = p as AiPreset
   return safe(v.id) && typeof v.name === 'string' && v.name.length > 0 && v.name.length <= 80 &&
     knownClis.includes(v.cli) &&
-    (v.provider === undefined || safe(v.provider)) && (v.model === undefined || safe(v.model)) && (v.effort === undefined || safe(v.effort))
+    (v.provider === undefined || safe(v.provider)) && (v.model === undefined || safe(v.model)) && (v.effort === undefined || safe(v.effort)) &&
+    (v.authProfile === undefined || (isAuthProfile(v.authProfile) && AUTH_PROFILE_CLIS.includes(v.cli)))
 }
 export const isExecutionChoice = (v: unknown): v is ExecutionChoice => {
   const c = v as ExecutionChoice | undefined
-  return Boolean(c && /^[0-9a-f-]{36}$/i.test(c.sessionId) && isPreset(c.preset))
+  return Boolean(c && /^[0-9a-f-]{36}$/i.test(c.sessionId) && isPreset(c.preset) &&
+    (c.fallbacks === undefined || (Array.isArray(c.fallbacks) && c.fallbacks.length > 0 && c.fallbacks.length <= MAX_FALLBACKS && c.fallbacks.every(isPreset))))
 }
-export const presetLabel = (p: AiPreset) => `${p.cli}${p.provider ? ` (${p.provider})` : ''} · ${p.model || 'client default'} · ${p.effort || 'default effort'}`
+export const presetLabel = (p: AiPreset) => `${p.cli}${p.authProfile ? `@${p.authProfile}` : ''}${p.provider ? ` (${p.provider})` : ''} · ${p.model || 'client default'} · ${p.effort || 'default effort'}`
 // OpenCode encodes its provider in the native provider/model identifier.
 export const presetProvider = (p: AiPreset) => p.cli === 'opencode' ? p.model?.split('/')[0] : p.provider
 // The seed delegates model selection to the native client. Project its resolved
@@ -146,7 +156,27 @@ export const readCodexCatalog = async (codexHome: string, run?: (args: string[],
   try { return JSON.parse(await readFile(join(codexHome, 'models_cache.json'), 'utf8')) } catch { return {} }
 }
 
-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>): Promise<ModelChoice[]> => {
+// 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> : {}
@@ -179,15 +209,18 @@ 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
   // establish which models Pi can execute.
   if (!allow && await available('pi')) models.push({ cli: 'pi', name: 'Pi · client default', efforts: [] })
   const curated = await readCuratedModels(curationDir)
-  if (!curated.length) return models
+  const profiles = await listAuthProfiles(curationDir)
+  // Each provisioned profile offers its client's entries under its own home.
+  const withProfiles = (listed: ModelChoice[]) => [...listed, ...profiles.flatMap(({ cli, authProfile }) =>
+    listed.filter((model) => model.cli === cli).map((model) => ({ ...model, authProfile, name: `${authProfile} · ${model.name}`.slice(0, 80) })))]
+  if (!curated.length) return withProfiles(models)
   const scoped: ModelChoice[] = []
   for (const entry of curated) {
     if (!(await available(entry.cli))) continue
@@ -197,7 +230,7 @@ export const readModels = async (home = homedir(), available = installed, codexH
   }
   const key = (m: { cli: string; provider?: string; model?: string }) => `${m.cli}‖${m.provider ?? ''}‖${m.model ?? ''}`
   const curatedKeys = new Set(scoped.map(key))
-  return [...scoped, ...models.filter((m) => !curatedKeys.has(key(m)))]
+  return withProfiles([...scoped, ...models.filter((m) => !curatedKeys.has(key(m)))])
 }
 export const opencodeCatalogModels = async (
   opencodeRunner?: (args: string[]) => Promise<string>,
@@ -233,9 +266,59 @@ export const opencodeProviderAllowlist = (env: NodeJS.ProcessEnv = process.env):
 
 export const validateSelection = async (p: AiPreset, catalog: ModelChoice[], available = installed): Promise<void> => {
   assertEffort(p.effort, p.model, p.cli)
-  if (!isPreset(p) || !(await available(p.cli))) throw new Error('This CLI is not installed.')
-  if (!p.provider && !p.model && !p.effort) return
-  const model = catalog.find((m) => m.cli === p.cli && m.provider === p.provider && m.model === p.model)
+  if (!isPreset(p)) throw new Error('This CLI is not installed.')
+  if (!(await available(p.cli))) throw new CliUnavailableError('This CLI is not installed.')
+  if (!p.provider && !p.authProfile && !p.model && !p.effort) return
+  if (p.authProfile && !p.provider && !p.model && !p.effort) {
+    if (!catalog.some((m) => sameEngine(m, p))) throw new Error('This auth profile is not provisioned for the selected CLI.')
+    return
+  }
+  const model = catalog.find((m) => sameEngine(m, p) && m.provider === p.provider && m.model === p.model)
   if (!model || (p.effort && !model.efforts.includes(p.effort)))
     throw new Error('This model/effort is not in the installed client catalog. Refresh the client and try again; no fallback was selected.')
 }
+
+export type AuthProfileStatus = { cli: string; authProfile: string | null; provisioned: boolean; sharesHostLogin: boolean
+  credentialFiles: string[]; loggedIn: boolean | null; method: string | null }
+type StatusRunner = (command: string, args: string[], env: NodeJS.ProcessEnv, cwd: string) => Promise<{ code: number | null; stdout: string; stderr: string }>
+const nativeStatus: StatusRunner = (command, args, env, cwd) => new Promise((resolve) => {
+  const invocation = executorInvocation(command, args)
+  execFile(invocation.command, invocation.args, { env, cwd, timeout: 8000, maxBuffer: 1024 * 1024 }, (error, stdout, stderr) =>
+    resolve({ code: error ? (typeof error.code === 'number' ? error.code : null) : 0, stdout: String(stdout), stderr: String(stderr) }))
+})
+const credentialNames: Record<string, string[]> = { codex: ['auth.json'], claude: ['oauth-token', '.credentials.json'] }
+
+// Read-only auth diagnostics per credential home. Native status runs with the
+// same home and credential environment as execution; only whitelisted fields
+// are projected, never tokens, account identifiers or raw native output.
+export const authProfileStatus = async (controlDir: string, available = installed, run = nativeStatus,
+  isolated = process.env.EZ_ISOLATION === 'isolated'): Promise<AuthProfileStatus[]> => {
+  const homes: { cli: string; authProfile?: string }[] = [...AUTH_PROFILE_CLIS.map((cli) => ({ cli })), ...await listAuthProfiles(controlDir)]
+  const statuses: AuthProfileStatus[] = []
+  for (const { cli, authProfile } of homes) {
+    if (!authProfile && !(await available(cli))) continue
+    const home = cliHome(controlDir, cli, authProfile)
+    const provisioned = await access(home).then(() => true, () => false)
+    const credentialFiles: string[] = []
+    for (const name of credentialNames[cli]) if (await access(join(home, name)).then(() => true, () => false)) credentialFiles.push(name)
+    let loggedIn: boolean | null = null, method: string | null = null
+    if (provisioned) {
+      try {
+        if (cli === 'codex') {
+          const result = await run('codex', ['login', 'status'], { ...executorEnvironment(), CODEX_HOME: home }, home)
+          loggedIn = result.code === null ? null : result.code === 0
+          // Codex prints its login status on stderr.
+          const text = result.stdout + result.stderr
+          method = loggedIn ? /chatgpt/i.test(text) ? 'chatgpt' : /api key/i.test(text) ? 'api-key' : 'other' : null
+        } else {
+          const result = await run('claude', ['auth', 'status', '--json'], { ...executorEnvironment(), ...await claudeAuthEnvironment(home, authProfile, isolated) }, home)
+          const status = result.code === null ? undefined : JSON.parse(result.stdout) as { loggedIn?: unknown; authMethod?: unknown }
+          loggedIn = status ? status.loggedIn === true : null
+          method = loggedIn && safe(status?.authMethod) ? status.authMethod : null
+        }
+      } catch { loggedIn = false }
+    }
+    statuses.push({ cli, authProfile: authProfile ?? null, provisioned, sharesHostLogin: !isolated && !authProfile, credentialFiles, loggedIn, method })
+  }
+  return statuses
+}