@jc_stack/ez-agents 0.1.0-beta.52 → 0.1.0-beta.58

package/src/run-telemetry.ts

@@ -0,0 +1,163 @@
+// Opt-in per-attempt run telemetry read from structured native client events:
+// reported model, token counts, tool counts/durations and error categories.
+// Only counts, tool names and category codes are kept. Prompts, model text,
+// tool arguments/results, credentials and reasoning are never read into it,
+// and no cost is derived. Missing or partial coverage is labelled, not guessed.
+export type TokenCounts = { input: number; output: number; cacheRead: number; cacheWrite: number }
+export type ToolStats = { calls: number; completed: number; errors: number; durationMs: number }
+export type AttemptTelemetry = {
+  coverage: 'complete' | 'partial' | 'none'
+  gaps?: string[]
+  model?: string
+  // native-total: the client's own cumulative total for this invocation;
+  // message-sum: deduplicated per-message usage when no total was reported.
+  tokens?: TokenCounts & { source: 'native-total' | 'message-sum' }
+  // Durations are observed stream intervals between a tool's start and result.
+  tools?: ToolStats & { byName: Record<string, ToolStats> }
+  errors?: string[]
+}
+
+const MAX_NAMES = 32
+const count = (value: unknown): number => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0
+const code = (value: unknown): string | undefined => typeof value === 'string' && /^[A-Za-z0-9_.:@/-]{1,80}$/.test(value) ? value : undefined
+const toolName = (value: unknown): string => code(value) ?? 'unnamed'
+const isCounts = (v: any): boolean => v && ['input', 'output', 'cacheRead', 'cacheWrite'].every(key => Number.isSafeInteger(v[key]) && v[key] >= 0)
+const isStats = (v: any): boolean => v && ['calls', 'completed', 'errors', 'durationMs'].every(key => Number.isSafeInteger(v[key]) && v[key] >= 0)
+
+// Revalidates a forwarded summary; anything outside the closed shape is dropped.
+export const validTelemetry = (value: unknown): AttemptTelemetry | undefined => {
+  const v = value as AttemptTelemetry
+  if (!v || typeof v !== 'object' || !['complete', 'partial', 'none'].includes(v.coverage)) return undefined
+  if (v.gaps !== undefined && !(Array.isArray(v.gaps) && v.gaps.length <= 16 && v.gaps.every(g => code(g)))) return undefined
+  if (v.errors !== undefined && !(Array.isArray(v.errors) && v.errors.length <= 16 && v.errors.every(e => code(e)))) return undefined
+  if (v.model !== undefined && !code(v.model)) return undefined
+  if (v.tokens !== undefined && !(isCounts(v.tokens) && ['native-total', 'message-sum'].includes(v.tokens.source))) return undefined
+  if (v.tools !== undefined && !(isStats(v.tools) && v.tools.byName && typeof v.tools.byName === 'object' &&
+    Object.keys(v.tools.byName).length <= MAX_NAMES + 1 && Object.entries(v.tools.byName).every(([name, stats]) => code(name) && isStats(stats)))) return undefined
+  const { coverage, gaps, model, tokens, tools, errors } = v
+  return JSON.parse(JSON.stringify({ coverage, gaps, model, tokens, tools, errors }))
+}
+
+export const telemetryLine = (telemetry: AttemptTelemetry): string => JSON.stringify({ type: 'ez.telemetry', telemetry })
+
+// Codex reports input including cached input; Claude reports them separately.
+// Both are normalized to uncached input plus cache reads/writes.
+const codexCounts = (usage: any): TokenCounts => {
+  const cached = count(usage?.cached_input_tokens)
+  return { input: Math.max(0, count(usage?.input_tokens) - cached), output: count(usage?.output_tokens), cacheRead: cached, cacheWrite: 0 }
+}
+const claudeCounts = (usage: any): TokenCounts => ({ input: count(usage?.input_tokens), output: count(usage?.output_tokens),
+  cacheRead: count(usage?.cache_read_input_tokens), cacheWrite: count(usage?.cache_creation_input_tokens) })
+const codexTools: Record<string, string> = { command_execution: 'command', file_change: 'file_change', web_search: 'web_search', mcp_tool_call: 'mcp' }
+
+// Repeated and cumulative events are deduplicated: Claude repeats one
+// message's usage per content block (keyed by message ID), native totals
+// replace earlier totals, tools are keyed by their call ID, and a forwarded
+// `ez.telemetry` summary from the producing side replaces local observation.
+// `cumulativeSession` marks a resumed client whose total may span earlier turns.
+export const telemetryObserver = (options: { cumulativeSession?: boolean } = {}, now = () => Date.now()) => {
+  let buffer = '', observed = false, model: string | undefined, total: TokenCounts | undefined
+  let forwarded: AttemptTelemetry | undefined
+  const messages = new Map<string, TokenCounts>()
+  const tools = new Map<string, { name: string; startedAt?: number; endedAt?: number; error: boolean }>()
+  const errors = new Set<string>()
+  const start = (id: unknown, name: string) => {
+    const key = code(id)
+    if (key && !tools.has(key)) tools.set(key, { name, startedAt: now(), error: false })
+  }
+  const end = (id: unknown, name: string, error: boolean) => {
+    const key = code(id)
+    if (!key) return
+    const tool = tools.get(key) ?? { name, error: false }
+    if (tool.endedAt !== undefined) return
+    tools.set(key, { ...tool, endedAt: now(), error })
+  }
+  const line = (text: string) => {
+    if (!text.trim()) return
+    let event: any
+    try { event = JSON.parse(text) } catch { return }
+    if (!event || typeof event !== 'object') return
+    if (event.type === 'ez.telemetry') { const summary = validTelemetry(event.telemetry); if (summary) forwarded = summary; return }
+    if (event.type === 'ez.startup') return
+    observed = true
+    // Claude Code stream-json.
+    if (event.type === 'system' && event.subtype === 'init') model = code(event.model) ?? model
+    else if (event.type === 'system' && ['api_error', 'api_retry'].includes(event.subtype)) errors.add(event.subtype === 'api_retry' ? 'api-retry' : 'api-error')
+    else if (event.type === 'rate_limit_event' && event.rate_limit_info?.status === 'rejected') errors.add('quota')
+    else if (event.type === 'assistant') {
+      const error = code(event.error)
+      if (error) errors.add(error)
+      const id = code(event.message?.id)
+      if (id && event.message?.usage && !event.isApiErrorMessage) messages.set(id, claudeCounts(event.message.usage))
+      for (const block of Array.isArray(event.message?.content) ? event.message.content : [])
+        if (block?.type === 'tool_use') start(block.id, toolName(block.name))
+    } else if (event.type === 'user') {
+      for (const block of Array.isArray(event.message?.content) ? event.message.content : [])
+        if (block?.type === 'tool_result') end(block.tool_use_id, tools.get(code(block.tool_use_id) ?? '')?.name ?? 'unnamed', block.is_error === true)
+    } else if (event.type === 'result') {
+      if (event.usage) total = claudeCounts(event.usage)
+      if (event.is_error === true) errors.add(code(event.subtype) ?? 'result-error')
+    }
+    // Codex exec --json (also the shape codex-session.ts forwards for app-server items).
+    else if ((event.type === 'item.started' || event.type === 'item.completed') && codexTools[event.item?.type]) {
+      const name = event.item.type === 'mcp_tool_call' ? toolName(`mcp:${event.item.server}/${event.item.tool}`) : codexTools[event.item.type]
+      if (event.type === 'item.started') start(event.item.id, name)
+      else end(event.item.id, name, event.item.status === 'failed')
+    } else if (event.type === 'turn.completed' && event.usage) total = codexCounts(event.usage)
+    else if (event.type === 'turn.failed') errors.add('turn-failed')
+    else if (event.type === 'error') errors.add('native-error')
+  }
+  const result = (): AttemptTelemetry => {
+    if (forwarded) return forwarded
+    const gaps: string[] = []
+    let tokens: AttemptTelemetry['tokens']
+    if (total) tokens = { ...total, source: 'native-total' }
+    else if (messages.size) {
+      const sum = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
+      for (const usage of messages.values()) for (const key of Object.keys(sum) as (keyof TokenCounts)[]) sum[key] += usage[key]
+      tokens = { ...sum, source: 'message-sum' }
+      gaps.push('tokens-without-native-total')
+    } else gaps.push('tokens')
+    if (tokens && options.cumulativeSession) gaps.push('tokens-may-include-earlier-session-turns')
+    if (!model) gaps.push('reported-model')
+    const byName: Record<string, ToolStats> = {}
+    const totals: ToolStats = { calls: 0, completed: 0, errors: 0, durationMs: 0 }
+    let unmeasured = false
+    for (const tool of tools.values()) {
+      const name = byName[tool.name] || Object.keys(byName).length < MAX_NAMES ? tool.name : 'other'
+      const stats = byName[name] ??= { calls: 0, completed: 0, errors: 0, durationMs: 0 }
+      const done = tool.endedAt !== undefined
+      const duration = done && tool.startedAt !== undefined ? Math.max(0, tool.endedAt! - tool.startedAt) : 0
+      if (done && tool.startedAt === undefined) unmeasured = true
+      for (const target of [stats, totals]) {
+        target.calls++
+        if (done) target.completed++
+        if (tool.error) target.errors++
+        target.durationMs += duration
+      }
+    }
+    if (totals.completed < totals.calls) gaps.push('tools-incomplete')
+    if (unmeasured) gaps.push('tool-durations-partial')
+    const telemetry: AttemptTelemetry = {
+      coverage: !observed ? 'none' : gaps.length ? 'partial' : 'complete',
+      ...(gaps.length ? { gaps } : {}),
+      ...(model ? { model } : {}),
+      ...(tokens ? { tokens } : {}),
+      ...(observed ? { tools: { ...totals, byName } } : {}),
+      ...(errors.size ? { errors: [...errors].slice(0, 16) } : {}),
+    }
+    return telemetry
+  }
+  return {
+    write: (chunk: string) => {
+      buffer += chunk
+      const lines = buffer.split('\n')
+      buffer = lines.pop() ?? ''
+      for (const text of lines) line(text)
+    },
+    // A client that reports its model outside the event stream (Codex app-server).
+    model: (name: unknown) => { model = code(name) ?? model },
+    result: () => { line(buffer); buffer = ''; return result() },
+    summary: () => telemetryLine(result()),
+  }
+}

package/src/running-work.ts

@@ -0,0 +1,123 @@
+import type { Owner } from './control-state.js'
+import { sameOwner } from './control-state.js'
+import { readOnlyOwner, requireOwnerExecution } from './execution-authority.js'
+import { redactFailure } from './failure.js'
+import { ownsRun } from './identity.js'
+import { activeSetup, retainedOutbox, RunStore, type RunRecord, type StoredOutboxItem } from './runs.js'
+import { Scheduler, occurrenceOf, type Schedule } from './scheduler.js'
+
+const timestamp = (value?: string): string | null =>
+  value && Number.isFinite(Date.parse(value)) ? new Date(value).toISOString() : null
+const secondsSince = (value: string | null, now: number): number | null =>
+  value && Date.parse(value) <= now ? Math.floor((now - Date.parse(value)) / 1000) : null
+const label = (value: string): string => redactFailure(value).replace(/[\p{Cc}\p{Cf}]/gu, ' ').slice(0, 120)
+
+// Current-owner relay records only, without application/channel request context.
+// Nothing here queries native sessions, processes or provider state, or exports prompts.
+const visible = (run: RunRecord, owner: Owner): boolean =>
+  ownsRun(owner, run) && Date.parse(run.createdAt) >= Date.parse(owner.pairedAt) &&
+  !run.external && !run.taskId &&
+  (!run.scheduled || run.scheduled.pairedAt === owner.pairedAt)
+
+export function projectRunningWork(records: RunRecord[], outbox: StoredOutboxItem[], schedules: Schedule[], owner: Owner, now = Date.now()) {
+  const owned = records.filter(run => visible(run, owner))
+  const active = owned.filter(run => run.status === 'running' || run.status === 'queued')
+    .sort((a, b) => Number(b.status === 'running') - Number(a.status === 'running') ||
+      a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id))
+  const runs = active.map(run => {
+    const preset = activeSetup(run)
+    const attempt = [...run.attempts ?? []].reverse().find(item => item.outcome !== 'skipped')
+    const schedule = schedules.find(item => occurrenceOf(item, run) && sameOwner(item.owner, owner))
+    const originId = run.scheduled?.originRunId
+    const origin = owned.find(item => item.id === originId)
+    const events = [
+      { at: timestamp(run.createdAt), kind: 'queued' },
+      { at: timestamp(run.startedAt), kind: 'relay-started' },
+      ...run.attempts?.flatMap(item => [
+        { at: timestamp(item.startedAt), kind: item.outcome === 'skipped' ? 'setup-skipped' : 'setup-attempt-started' },
+        { at: timestamp(item.endedAt), kind: item.outcome === 'skipped' ? 'setup-skipped' : 'setup-attempt-ended' },
+      ]) ?? [],
+      ...outbox.filter(item => item.runId === run.id && item.chatId === owner.telegramChatId &&
+        Date.parse(item.createdAt) >= Date.parse(owner.telegramLinkedAt ?? owner.pairedAt))
+        .map(item => ({ at: timestamp(item.createdAt), kind: 'delivery-enqueued' })),
+    ].filter((item): item is { at: string; kind: string } => item.at !== null && Date.parse(item.at) <= now)
+      .sort((a, b) => b.at.localeCompare(a.at))
+    const latest = events[0]
+    return {
+      id: run.id, status: run.status,
+      ...(run.status === 'queued' && run.quotaWait ? { quotaWait: { retryAt: timestamp(run.quotaWait.retryAt) } } : {}),
+      kind: run.script ? 'scheduled-script' : run.scheduled ? 'scheduled-agent' : run.sessionClose ? 'session-close' : run.application || run.telegramApplication ? 'application-foreground' : 'foreground',
+      schedule: run.scheduled ? { id: run.scheduled.id, revision: run.scheduled.revision,
+        name: schedule ? label(schedule.name) : null, dueAt: timestamp(run.scheduled.dueAt) } : null,
+      script: run.script ? { id: run.script.id, revision: run.script.revision ?? null } : null,
+      execution: run.script ? null : preset ? { cli: preset.cli, model: preset.model ?? null,
+        effort: preset.effort ?? null, provider: preset.provider ?? null,
+        source: attempt ? 'latest-attempt' : 'saved', attemptOutcome: attempt?.outcome ?? null } : null,
+      createdAt: timestamp(run.createdAt), startedAt: timestamp(run.startedAt),
+      elapsedSeconds: run.status === 'running' ? secondsSince(timestamp(run.startedAt), now) : null,
+      queuedSeconds: run.status === 'queued' ? secondsSince(timestamp(run.createdAt), now) : null,
+      lastObservedActivity: latest ? { ...latest, ageSeconds: secondsSince(latest.at, now) } : null,
+      // This is request provenance, not proof of native parent/child delegation.
+      origin: originId ? { runId: originId, relation: 'schedule-origin',
+        status: origin?.status ?? null, retained: Boolean(origin) } : null,
+      scheduledChildren: active.filter(item => item.scheduled?.originRunId === run.id)
+        .map(item => ({ id: item.id, status: item.status })),
+      nativeChildren: { state: 'unavailable' },
+    }
+  })
+  return { schemaVersion: 1, observedAt: new Date(now).toISOString(),
+    counts: { running: runs.filter(run => run.status === 'running').length, queued: runs.filter(run => run.status === 'queued').length },
+    coverage: {
+      scope: 'current-owner foreground and scheduled runs in this relay',
+      retention: 'relay memory; resets on restart except adopted host runs; older origin records may be absent',
+      activity: 'relay lifecycle, setup attempts and delivery enqueue times only; silence is not idle or completion',
+      nativeActivity: 'unavailable; native tool and delegation events are not retained',
+      relationships: 'schedule-origin links only; native child status is unknown',
+      excluded: ['standalone CLI/desktop work', 'other installations', 'external/isolated tasks', 'prompts, messages, application context and raw engine output'],
+    }, runs }
+}
+
+export type RunningWorkView = ReturnType<typeof projectRunningWork>
+
+export async function runningWork(controlDir: string, options: { callerRunId?: string } = {}): Promise<RunningWorkView> {
+  if (options.callerRunId !== undefined) {
+    const caller = await new RunStore(controlDir).get(options.callerRunId)
+    if (caller?.application || caller?.delivery || caller?.replyOnly)
+      throw new Error('Running work requires Telegram owner execution or the bound operator')
+    await requireOwnerExecution(controlDir, options.callerRunId)
+  }
+  const owner = await readOnlyOwner(controlDir)
+  if (!owner) throw new Error('No authorized owner')
+  const schedules = await new Scheduler(controlDir).listReadOnly()
+  return projectRunningWork(await new RunStore(controlDir).list(), retainedOutbox(controlDir),
+    schedules, owner)
+}
+
+const duration = (seconds: number | null): string => {
+  if (seconds === null) return 'unknown'
+  if (seconds < 60) return `${seconds}s`
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ${seconds % 60}s`
+  return `${Math.floor(seconds / 3600)}h ${Math.floor(seconds % 3600 / 60)}m`
+}
+
+export function formatRunningWork(view: RunningWorkView): string {
+  const lines = [`Queued and running work: ${view.counts.running} running, ${view.counts.queued} queued`, `Observed: ${view.observedAt}`]
+  if (!view.runs.length) lines.push('No queued or running work observed in the retained relay ledger.')
+  for (const run of view.runs) {
+    lines.push('', `${run.id}  ${run.status}  ${run.kind}`)
+    if (run.schedule) lines.push(`  Schedule: ${run.schedule.name ?? '(name unavailable)'} (${run.schedule.id}, revision ${run.schedule.revision}); due ${run.schedule.dueAt ?? 'unknown'}`)
+    if (run.quotaWait) lines.push(`  Waiting for quota: ${run.quotaWait.retryAt ? `next check ${run.quotaWait.retryAt}` : 'awaiting availability or manual retry'}; /retry_quota ${run.id}`)
+    if (run.script) lines.push(`  Script: ${run.script.id}; engine/model: not applicable`)
+    else lines.push(`  Engine/model: ${run.execution?.cli ?? 'unknown'} / ${run.execution?.model ?? 'unknown'}${run.execution?.effort ? `; effort ${run.execution.effort}` : ''}${run.execution ? ` (${run.execution.source}${run.execution.attemptOutcome ? `: ${run.execution.attemptOutcome}` : ''})` : ''}`)
+    lines.push(`  Started: ${run.startedAt ?? (run.status === 'queued' ? 'not started' : 'unknown')}; elapsed: ${run.status === 'queued' ? 'not applicable' : duration(run.elapsedSeconds)}${run.status === 'queued' ? `; queued for ${duration(run.queuedSeconds)}` : ''}`)
+    const activity = run.lastObservedActivity
+    lines.push(`  Last observed: ${activity ? `${activity.at} (${duration(activity.ageSeconds)} ago; ${activity.kind})` : 'unknown'}`)
+    if (run.origin) lines.push(`  Schedule origin: ${run.origin.runId} (${run.origin.status ?? 'status unknown; record unavailable'})`)
+    if (run.scheduledChildren.length) lines.push(`  Active scheduled children: ${run.scheduledChildren.map(item => `${item.id} (${item.status})`).join(', ')}`)
+    lines.push('  Native children: unavailable')
+  }
+  lines.push('', `Visibility: ${view.coverage.scope}.`, view.coverage.retention + '.', view.coverage.activity + '.',
+    'Native tool activity and child status are unavailable. Schedule origins are request provenance.',
+    'Standalone CLI/desktop work, other installations and external/isolated runs are outside this view.')
+  return lines.join('\n')
+}

package/src/runs.ts

@@ -10,7 +10,7 @@ import { validScheduledOrigin, type ScheduledOrigin } from './scheduler.js'
 import type { IncomingItem } from './inbox.js'
 import { assertId } from './identity.js'
 import { isExecutionChoice, type AiPreset, type ExecutionChoice } from './ai.js'
-import type { SetupAttempt } from './setup-fallback.js'
+import type { SetupAttempt, QuotaWait } from './setup-fallback.js'
 import type { ScriptRunRef } from './scripts.js'
 import {authorizeDeliveryContext,currentDeliveryOwner,type DeliveryContext} from './delivery-context.mjs'
 
@@ -38,6 +38,11 @@ export type RunRecord = {
   execution?: ExecutionChoice
   // Ordered task setups tried for this occurrence; the last one is active.
   attempts?: SetupAttempt[]
+  // Queued quota wait, also retained while its availability probe starts.
+  quotaWait?: QuotaWait
+  attemptRound?: number
+  // Owner-enabled run telemetry, fixed when the run starts.
+  telemetry?: true
   replyOnly?: boolean
   // Silent end-of-conversation turn in a replaced chat session (session-close.ts).
   sessionClose?: true
@@ -273,7 +278,7 @@ export class RunStore {
 
   async patch(
     id: string,
-    change: Partial<Pick<RunRecord, 'status' | 'startedAt' | 'endedAt' | 'pid' | 'nativeSessionId' | 'interrupted' | 'blockReason' | 'backendSubmitted' | 'replyOnly' | 'exitCode' | 'failureReason' | 'failure' | 'failureReview' | 'externalReleased' | 'output' | 'timedOut' | 'attempts'>>,
+    change: Partial<Pick<RunRecord, 'status' | 'startedAt' | 'endedAt' | 'pid' | 'nativeSessionId' | 'interrupted' | 'blockReason' | 'backendSubmitted' | 'replyOnly' | 'exitCode' | 'failureReason' | 'failure' | 'failureReview' | 'externalReleased' | 'output' | 'timedOut' | 'attempts' | 'quotaWait' | 'attemptRound' | 'telemetry'>>,
   ): Promise<RunRecord> {
     const store = runsFor(this.controlDir)
     const run = store.get(id)

package/src/schedule-cli.ts

@@ -1,6 +1,7 @@
 import { needsFailureReview, failureStamp, redactFailure } from './failure.js'
 import { parseArgs } from 'node:util'
 import { readFile } from 'node:fs/promises'
+import { statSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { randomUUID } from 'node:crypto'
 import { loadControlConfig } from './config.js'
@@ -16,6 +17,7 @@ import { executorEnvironment } from './executor.js'
 import { provisionedHome } from './auth-profile.js'
 import { ownsRun } from './identity.js'
 import { type Trigger } from './schedule-time.js'
+import { formatRunningWork, type RunningWorkView } from './running-work.js'
 
 // Each fallback selects its own native engine, credential home and model.
 const fallbackSetup = (spec: string, index: number): AiPreset => {
@@ -38,16 +40,20 @@ async function main() {
   const { values:v, positionals:[action='list',id,scriptId] } = parseArgs({allowPositionals:true,options:{
     script:{type:'string'}, arg:{type:'string',multiple:true}, file:{type:'string'}, interpreter:{type:'string'}, 'timeout-seconds':{type:'string'},
     cli:{type:'string'}, 'auth-profile':{type:'string'}, model:{type:'string'}, effort:{type:'string'}, fallback:{type:'string',multiple:true}, 'clear-fallbacks':{type:'boolean'},
-    all:{type:'boolean'}, limit:{type:'string'}, offset:{type:'string'}, expected:{type:'string'}, key:{type:'string'}, when:{type:'string'}, status:{type:'string'}, diagnosis:{type:'string'}, recovery:{type:'string'}, outcome:{type:'string'}, 'failed-at':{type:'string'},
+    'expected-revision':{type:'string'}, stage:{type:'boolean'},
+    json:{type:'boolean'}, all:{type:'boolean'}, limit:{type:'string'}, offset:{type:'string'}, expected:{type:'string'}, key:{type:'string'}, when:{type:'string'}, status:{type:'string'}, diagnosis:{type:'string'}, recovery:{type:'string'}, outcome:{type:'string'}, 'failed-at':{type:'string'},
     'preflight-file':{type:'string'},'clear-preflight':{type:'boolean'},name:{type:'string'}, text:{type:'string'}, 'text-file':{type:'string'}, at:{type:'string'}, now:{type:'boolean'},
     cron:{type:'string'}, timezone:{type:'string'}, 'every-seconds':{type:'string'}, start:{type:'string'}, until:{type:'string'}, help:{type:'boolean'},
   }})
   if(v.help){console.log(`ezenciel-agents-schedule list | runs | show ID | pause ID | resume ID | remove ID | cancel RUN_ID
+  running [--json]   Read queued/running foreground and scheduled work in this relay
+  retry [RUN_ID] — retry quota-blocked work after resetting a limit or adding credits
   failures [--all] [--limit N] | run RUN_ID | context
   evidence [RUN_ID] [--offset N --limit N --expected SNAPSHOT_SHA256]
   trigger SCHEDULE_ID --key REQUEST_KEY
   review RUN_ID --failed-at ISO --status resolved|attention --diagnosis TEXT --recovery TEXT --outcome TEXT
-  create [ID] | edit ID --name NAME (--text TEXT | --text-file FILE | --script SCRIPT_ID [--arg=VALUE ...])
+  create [ID] | edit ID --expected-revision REVISION [--stage]
+    --name NAME (--text TEXT | --text-file FILE | --script SCRIPT_ID [--arg=VALUE ...])
     --now | --at ISO_WITH_OFFSET | --every-seconds N | --cron 'MIN HOUR DAY MONTH WEEKDAY' --timezone IANA
     [--cli EXECUTOR] [--auth-profile NAME] [--model MODEL] [--effort <native-effort>]
     [--fallback cli=EXECUTOR,model=MODEL[,auth-profile=NAME][,effort=EFFORT][,provider=ID] ... | --clear-fallbacks]
@@ -64,6 +70,10 @@ Script runs receive EZ_RUN_ID, EZ_SCHEDULE_ID, EZ_SCHEDULE_REVISION, EZ_DUE_AT,
 EZ_SCRIPT_SHA256 plus the normal executor allowlist. Stdout/stderr are bounded diagnostics in run, never owner messages.
 Script runs have a timeout (default ${DEFAULT_SCRIPT_TIMEOUT_SECONDS}s) and are never retried automatically.
 Context reads the current run only.
+Running is read-only and defaults to readable output; --json exports sanitized metadata.
+It includes current-owner foreground turns (Telegram/application) and schedules, with recorded setup, times and schedule-origin links.
+Activity covers relay lifecycle, setup attempts and delivery enqueue times; native tools and child status are unavailable.
+Missing or old observations never mean idle or complete. Standalone CLI/desktop and external/isolated work are outside this view.
 Evidence exports sanitized current-owner Telegram operational metadata only.
 Follow nextOffset with --expected; a changed snapshot requires restarting.
 Relay retention is incomplete. Content hashes identify submitted text, not recipient content.
@@ -72,7 +82,9 @@ Failures default to unreviewed owner runs. Review records a diagnosis; it never
 A conditional review schedule consumes no model run when there are no unreviewed failures.
 New tasks capture the selected engine settings; edit preserves existing settings unless overridden.
 Every task requires a concrete saved model. Supply --model if the selected settings have none; existing tasks never fall back to chat or client defaults.
-Fallbacks run in the saved order only when the previous setup's CLI is unavailable or its provider
+Tasks reuse the last successful login among the leading saved setups with the same engine, provider,
+model and effort, and skip logins until any reported quota reset. Other setup priority stays as saved.
+Fallbacks continue only when the previous setup's CLI is unavailable or its provider
 rejected the turn before any work began, including an unavailable login. A Claude usage limit the run ended on
 after work began continues on the next setup in a fresh session, told the stopped session and that its work may be
 partly applied. Account/organization access denial, unknown errors, cancellation and other failures after work
@@ -83,16 +95,32 @@ The run records each attempt, setup, failure category and any reported reset tim
 Trigger runs an existing task once with its saved instructions, AI and delivery binding in a fresh session. Reuse the request key after an uncertain result; the regular schedule is unchanged.
 Creates a scheduled task. Instructions are text, never shell commands.
 Use --now to run once. Run completion is not delivery proof.
-Edit replaces the full schedule but keeps its paused/enabled state; only pause/resume toggle it.
+Edit replaces the full schedule from the revision you read (show prints it); a changed revision is rejected.
+It applies only while the task has no queued or running occurrence. --stage applies it to future occurrences
+and lets those occurrences finish with their captured instructions and settings. Edit needs the running relay.
+Edit keeps the paused/enabled state; only pause/resume toggle it.
 Pause/remove affect future work; cancel stops a particular run.
 Cron uses numeric five-field syntax, lists/ranges/steps, and traditional day/weekday OR semantics.`);return}
-  const config=loadControlConfig(), control=new ControlStore(config.controlDir,config.pairingTtlMs)
+  const config=loadControlConfig()
+  // A root operator command (for example `docker compose exec relay ...`) acts as
+  // the runtime user that owns the control directory: saved definitions stay
+  // readable by the relay, and root never writes through agent-owned paths.
+  if(process.geteuid?.()===0){
+    const {uid,gid}=statSync(config.controlDir)
+    process.setgroups!([gid]);process.setgid!(gid);process.setuid!(uid)
+  }
+  const socketPath=socketPathFor(config.controlDir)
+  if(action==='running'){
+    if(id || scriptId || Object.keys(v).some(key=>key!=='json'))throw new Error('Running accepts only --json')
+    const result=await callDeliverySocket(socketPath,{op:'runningWork',payload:{callerRunId:process.env.EZ_RUN_ID || undefined}}) as RunningWorkView
+    console.log(v.json ? JSON.stringify(result,null,2) : formatRunningWork(result));return
+  }
+  const control=new ControlStore(config.controlDir,config.pairingTtlMs)
   const owner=(await control.status()).owner
   if(!owner)throw new Error('Pair an owner before scheduling')
-  const socketPath=socketPathFor(config.controlDir)
   // Run records live in the relay memory ledger, reached through the delivery
-  // socket. Schedule files stay on disk, so list/show/create/edit/pause/
-  // resume/remove keep working with the relay stopped; run-inspecting actions
+  // socket. Schedule files stay on disk, so list/show/create/pause/resume/remove
+  // keep working with the relay stopped; edit and run-inspecting actions
   // (context/failures/run/review/runs/cancel) require the running relay.
   const socketUnavailable = (error: unknown): boolean =>
     error instanceof Error && /Delivery relay unavailable/.test(error.message)
@@ -177,6 +205,10 @@ Cron uses numeric five-field syntax, lists/ranges/steps, and traditional day/wee
     }
   }else if(action==='list')result=await Promise.all((await scheduler.list()).filter(owned).map(show))
   else if(action==='runs')result=(await runs.list()).filter(r=>r.scheduled && r.scheduled.pairedAt===owner.pairedAt && ownsRun(owner,r))
+  else if(action==='retry'){
+    if(Object.keys(v).length || scriptId)throw new Error('Retry takes only an optional quota-blocked run ID')
+    result=await callDeliverySocket(socketPath,{op:'retryScheduleQuota',payload:{...(id ? {runId:id} : {}),...(caller ? {callerRunId:caller.id} : {})}})
+  }
   else if(action==='trigger'){
     if(!id || !v.key)throw new Error('Trigger requires SCHEDULE_ID and --key REQUEST_KEY')
     if(Object.keys(v).some(key=>key!=='key'))throw new Error('Trigger uses saved task settings; overrides are not allowed')
@@ -185,6 +217,8 @@ Cron uses numeric five-field syntax, lists/ranges/steps, and traditional day/wee
     result=await callDeliverySocket(socketPath,{op:'triggerSchedule',payload:{scheduleId:id,revision:schedule.revision,key:v.key,...(caller ? {callerRunId:caller.id} : {})}})
   }else if(action==='create' || action==='edit'){
     if(action==='edit' && (!id || !owned(await scheduler.get(id))))throw new Error('Unknown schedule')
+    if(action==='edit' && !v['expected-revision'])throw new Error('Edit requires --expected-revision REVISION (the revision shown by show ID)')
+    if(action==='create' && (v['expected-revision'] || v.stage))throw new Error('--expected-revision and --stage apply to edit only')
     if(action==='create' && id && (await scheduler.list()).some(s=>s.id===id))throw new Error('Schedule exists; use edit')
     if([v.now,v.at,v.cron,v['every-seconds']].filter(Boolean).length!==1)throw new Error('Choose exactly one trigger')
     if([v.text,v['text-file'],v.script].filter(Boolean).length!==1)throw new Error('Choose --text, --text-file or --script')
@@ -196,16 +230,21 @@ Cron uses numeric five-field syntax, lists/ranges/steps, and traditional day/wee
       v.cron ? {cron:v.cron,timezone:v.timezone!,start,until:v.until} : {everySeconds:Number(v['every-seconds']),start,until:v.until}
     if(v['clear-preflight'] && v['preflight-file']) throw Error('Choose one preflight operation')
     const previousSchedule = action === 'edit' ? await scheduler.get(id!) : undefined
-    // Edit keeps the paused/enabled state; only pause/resume toggle it.
-    const enabled = previousSchedule?.enabled ?? true
+    // New tasks start enabled; edit compares the revision and keeps the paused/enabled state under the schedule lock.
+    const write = (input: Parameters<Scheduler['save']>[0]) => action === 'create' ? scheduler.save(input, true) :
+      // A bounded ledger read keeps the schedule lock short.
+      scheduler.edit(input, v['expected-revision']!, () => callDeliverySocket(socketPath, { op: 'list' }, 10_000).then(r => r as RunRecord[]).catch(error => {
+        if (socketUnavailable(error)) throw new Error('Relay unavailable: edit needs the running relay to confirm which occurrences are queued or running')
+        throw error
+      }), v.stage)
     const preflight = v['clear-preflight'] ? undefined : v['preflight-file'] ? JSON.parse(await readFile(v['preflight-file'],'utf8')) : previousSchedule?.preflight
     const origin = caller?.application ?? caller?.delivery
     const delivery = previousSchedule ? previousSchedule.delivery : (origin ? {bindingId:origin.bindingId,scope:origin.scope} : undefined)
     if (!delivery && !owner.telegramChatId) throw new Error('Create the schedule from an authenticated channel turn to bind its reply destination')
     if (v.script) {
-      result=await show(await scheduler.save({id:id || 's_'+randomUUID(),name:v.name || v.script,preflight,
-        originRunId:previousSchedule?.originRunId ?? caller?.scheduled?.originRunId ?? caller?.id,delivery,text:'',when:v.when as 'unreviewed-failures' | undefined,trigger,enabled,owner,
-        script:{id:v.script,args:v.arg ?? []}},action==='create'))
+      result=await show(await write({id:id || 's_'+randomUUID(),name:v.name || v.script,preflight,
+        originRunId:previousSchedule?.originRunId ?? caller?.scheduled?.originRunId ?? caller?.id,delivery,text:'',when:v.when as 'unreviewed-failures' | undefined,trigger,enabled:true,owner,
+        script:{id:v.script,args:v.arg ?? []}}))
       console.log(JSON.stringify(result,null,2));return
     }
     const previous = previousSchedule?.execution
@@ -217,10 +256,10 @@ Cron uses numeric five-field syntax, lists/ranges/steps, and traditional day/wee
     const fallbacks = v['clear-fallbacks'] ? undefined : v.fallback ? v.fallback.map(fallbackSetup) : previous?.fallbacks
     for (const setup of [preset, ...fallbacks ?? []])
       if (setup.authProfile !== undefined) await provisionedHome(config.controlDir, setup.cli, setup.authProfile)
-    result=await show(await scheduler.save({id:id || 's_'+randomUUID(),name:v.name || 'Task',
+    result=await show(await write({id:id || 's_'+randomUUID(),name:v.name || 'Task',
       preflight,
-      originRunId:previousSchedule?.originRunId ?? caller?.scheduled?.originRunId ?? caller?.id,delivery,text:v.text || await readFile(v['text-file']!,'utf8'),when:v.when as 'unreviewed-failures' | undefined,trigger,enabled,owner,
-      execution:{sessionId:previous?.sessionId || randomUUID(),preset,...(fallbacks ? {fallbacks} : {})}},action==='create'))
+      originRunId:previousSchedule?.originRunId ?? caller?.scheduled?.originRunId ?? caller?.id,delivery,text:v.text || await readFile(v['text-file']!,'utf8'),when:v.when as 'unreviewed-failures' | undefined,trigger,enabled:true,owner,
+      execution:{sessionId:previous?.sessionId || randomUUID(),preset,...(fallbacks ? {fallbacks} : {})}}))
   }else{
     if(!id)throw new Error('ID required')
     if(action==='cancel'){