dimcode-darwin-x64 0.1.0-alpha.15 → 0.1.0-alpha.16

package/plugins/scheduler/data.ts

@@ -0,0 +1,114 @@
+import { CronExpressionParser } from 'cron-parser'
+import { z } from 'zod'
+import type { PermissionPolicy } from '../../../npm/plugin.js'
+
+export class ScheduleError extends Error {
+  readonly code: string
+  constructor(code: string, message = code) { super(message); this.code = code }
+}
+
+export const id = z.string().min(1)
+export const preset = z.enum(['read-only', 'workspace-write', 'full-access'])
+const fileAccess = z.enum(['read-only', 'workspace-read-write', 'unrestricted'])
+export const policy = z.strictObject({ preset, fileAccess: fileAccess.optional(),
+  toolApproval: z.enum(['ask', 'bypass']).optional(),
+  allowedTools: z.array(z.string()), disallowedTools: z.array(z.string()) }) satisfies z.ZodType<PermissionPolicy>
+export const timestamp = z.iso.datetime({ precision: 3 }).max(24)
+export const address = z.strictObject({ session_id: id, branch_id: id })
+const cronField = '[0-9*/,-]+'
+export const schedule = z.union([
+  z.strictObject({ every_minutes: z.number().int().min(1) }),
+  z.strictObject({ at: z.iso.datetime({ offset: true }) }),
+  z.strictObject({ cron: z.string().regex(new RegExp(`^${Array(5).fill(cronField).join(' +')}$`)), tz: id.optional() }),
+])
+export const fields = z.strictObject({
+  name: id, schedule, prompt: z.string().max(32 * 1024), cwd: id,
+  model: z.strictObject({ providerId: id, modelId: id }).optional(),
+  mode: z.enum(['create', 'reuse']), policy: preset.optional(), max_run_minutes: z.number().int().min(1),
+})
+export const jobSchema = fields.extend({
+  id, agent_id: id.optional(), session_id: id.optional(),
+  policy_cap: policy, created_by: z.union([z.literal('user'), z.strictObject({ tool: address })]),
+  enabled: z.boolean(), enabled_at: timestamp.optional(), revision: z.number().int().min(1),
+  max_run_minutes: fields.shape.max_run_minutes.default(60),
+})
+export type Job = z.infer<typeof jobSchema>
+export type Schedule = z.infer<typeof schedule>
+export interface ScheduleSettings { jobs: Job[]; max_concurrent_runs: number }
+export interface Caller { sessionId: string; branchId: string; cwd: string }
+
+export const patchSchema = fields.partial()
+export const managementJob = patchSchema.extend({
+  id: id.optional(), enabled: z.boolean().optional(), session_id: id.optional(), agent_id: id.optional(),
+})
+export type JobPatch = z.infer<typeof managementJob>
+
+/** The same conservative policy cap used by S2; lists are sets. */
+export function cap(requested: PermissionPolicy, bound: PermissionPolicy) {
+  const ranks = preset.options
+  const legacyReadOnly = [requested, bound].some(value => approval(value) === 'legacy-read-only')
+  if (legacyReadOnly && [requested, bound].some(value => value.toolApproval === 'ask')) {
+    throw new ScheduleError('schedule_invalid', 'Explicit Ask cannot be capped by legacy read-only tool rules')
+  }
+  const disallowedTools = [...new Set([...requested.disallowedTools, ...bound.disallowedTools])]
+  const allowedTools = [...new Set([...requested.allowedTools, ...bound.allowedTools])].filter(name =>
+    (approval(requested) === 'bypass' || requested.allowedTools.includes(name))
+    && (approval(bound) === 'bypass' || bound.allowedTools.includes(name)) && !disallowedTools.includes(name))
+  return { preset: ranks[Math.min(ranks.indexOf(requested.preset), ranks.indexOf(bound.preset))],
+    ...(requested.fileAccess !== undefined || bound.fileAccess !== undefined ? {
+      fileAccess: fileAccess.options[Math.min(fileRank(requested), fileRank(bound))],
+    } : {}),
+    ...(!legacyReadOnly && (requested.toolApproval !== undefined || bound.toolApproval !== undefined) ? {
+      toolApproval: approval(requested) === 'bypass' && approval(bound) === 'bypass' ? 'bypass' as const : 'ask' as const,
+    } : {}), allowedTools, disallowedTools } satisfies PermissionPolicy
+}
+
+function fileRank(value: PermissionPolicy): number {
+  return value.fileAccess === undefined ? preset.options.indexOf(value.preset) : fileAccess.options.indexOf(value.fileAccess)
+}
+
+function approval(value: PermissionPolicy) {
+  return value.toolApproval ?? (value.preset === 'full-access' ? 'bypass' : value.preset === 'read-only' ? 'legacy-read-only' : 'ask')
+}
+
+export function within(actual: PermissionPolicy, bound: PermissionPolicy): boolean {
+  let capped: PermissionPolicy
+  try { capped = cap(actual, bound) }
+  catch (error) { if (error instanceof ScheduleError) return false; throw error }
+  return actual.preset === capped.preset
+    && fileRank(actual) === fileRank(capped) && approval(actual) === approval(capped)
+    && [actual.allowedTools, actual.disallowedTools].every((names, index) => {
+      const result = index === 0 ? capped.allowedTools : capped.disallowedTools
+      return new Set(names).size === result.length && names.every(name => result.includes(name))
+    })
+}
+
+export function effective(job: Job) {
+  const requested = job.policy ? { preset: job.policy, allowedTools: [], disallowedTools: [] }
+    : job.created_by === 'user' ? { preset: 'read-only' as const, allowedTools: [], disallowedTools: [] } : job.policy_cap
+  return cap(requested, job.policy_cap)
+}
+
+/** Business validation of a candidate authorizing save, before its document CAS. */
+export function validateJob(job: Job): void {
+  if (Buffer.byteLength(job.prompt) > 32 * 1024) throw new ScheduleError('schedule_invalid', 'Prompt exceeds 32 KiB')
+  if (Date.now() + job.max_run_minutes * 60_000 > Date.parse('9999-12-31T23:59:59.999Z')) {
+    throw new ScheduleError('schedule_invalid', 'Run deadline exceeds the persisted timestamp range')
+  }
+  if (job.policy && preset.options.indexOf(job.policy) > preset.options.indexOf(job.policy_cap.preset)) {
+    throw new ScheduleError('schedule_invalid', 'Job policy exceeds the saving authority')
+  }
+  effective(job)
+  if (job.session_id && job.mode !== 'reuse') throw new ScheduleError('schedule_invalid', 'Only reuse jobs bind an existing Session')
+  if ('cron' in job.schedule) {
+    try {
+      if (job.schedule.tz) new Intl.DateTimeFormat('en', { timeZone: job.schedule.tz }).format(0)
+      CronExpressionParser.parse(job.schedule.cron, { tz: job.schedule.tz }).next()
+    } catch { throw new ScheduleError('schedule_invalid', 'Invalid cron expression or time zone') }
+  }
+}
+
+export function authority(job: Job | undefined) {
+  return job ? { origin: job.created_by, cap: job.policy_cap, effective_policy: effective(job),
+    report_to: job.created_by === 'user' ? null : job.created_by.tool } : null
+}

package/plugins/scheduler/dim-plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "scheduler",
+  "description": "Scheduled jobs that run prompts",
+  "code": {
+    "entry": "index.ts",
+    "inject": [
+      "sessions",
+      "sessionPermissions",
+      "settings",
+      "pluginFiles",
+      "managementMethods",
+      "partRegistry"
+    ],
+    "provides": {
+      "scheduleJobs": {
+        "call": "async"
+      }
+    }
+  }
+}

package/plugins/scheduler/engine.ts

@@ -0,0 +1,436 @@
+import { randomUUID } from 'node:crypto'
+import type { Sessions } from '../../../npm/plugin.js'
+import { effective, ScheduleError, within, type Job } from './data.ts'
+import { RunHistory } from './history.ts'
+import { SettingsReadError, type Jobs } from './jobs.ts'
+import { unloadingBeforeCall } from './requests.ts'
+import { terminal, type Run, type RunStore } from './store.ts'
+import { latestWindow, windowAfter } from './windows.ts'
+
+const pause = (milliseconds: number) => new Promise<void>(resolve => setTimeout(resolve, milliseconds))
+const escaped = (text: string) => text.replace(/[&<>"']/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[character]!)
+
+export class Scheduler {
+  readonly jobs: Jobs
+  readonly sessions: Sessions
+  readonly store: RunStore
+  closing = false
+  fault: unknown
+  readonly work = new Map<string, Promise<unknown>>()
+  private pruning = false
+  private retryPruneAt: number | undefined
+  private nextWindowAt: number | undefined
+  private rewake = false
+  /// The report's guidance line: the factory configuration's text or
+  /// the built-in one.
+  private readonly reportGuidance: string
+
+  constructor(jobs: Jobs, sessions: Sessions, store: RunStore, reportGuidance = 'Inspect schedule.history for this job.') {
+    this.jobs = jobs; this.sessions = sessions; this.store = store; this.reportGuidance = reportGuidance
+  }
+
+  async track<T>(operation: () => Promise<T>, key: string = randomUUID()): Promise<T> {
+    if (this.closing) throw new ScheduleError('service_reloading', unloadingBeforeCall)
+    if (this.fault) throw this.fault
+    const work = operation()
+    this.work.set(key, work)
+    try { return await work }
+    finally { this.work.delete(key) }
+  }
+
+  async restore() {
+    const runs = await this.store.read()
+    for (const run of runs.filter(run => !terminal(run))) {
+      this.background(run.run_id, () => this.resume(run))
+    }
+    this.requestPrune()
+  }
+
+  startTimer() {
+    this.background('timer', async () => {
+      let minute: number | undefined
+      while (!this.closing && !this.fault) {
+        const now = Date.now(), currentMinute = Math.floor(now / 60_000)
+        if (minute !== currentMinute || this.nextWindowAt !== undefined && now >= this.nextWindowAt) {
+          minute = currentMinute
+          this.nextWindowAt = undefined
+          this.changed()
+        }
+        if (this.retryPruneAt !== undefined && Date.now() >= this.retryPruneAt) this.requestPrune()
+        await pause(1000)
+      }
+    })
+  }
+
+  changed() {
+    if (this.closing || this.fault) return
+    if (this.work.has('wake')) this.rewake = true
+    else this.background('wake', async () => { this.nextWindowAt = await this.tick() })
+  }
+
+  private background(key: string, operation: () => Promise<unknown>) {
+    void this.track(operation, key).catch(error => {
+      if (key !== 'wake' && !(error instanceof SettingsReadError)) this.fault = error
+      console.error('Scheduler', error instanceof Error ? error.message : String(error))
+    }).finally(() => {
+      if (key === 'wake' && this.rewake) {
+        this.rewake = false
+        this.changed()
+      }
+      if (!['timer', 'retention', 'wake'].includes(key) && !this.closing && !this.fault) {
+        this.requestPrune()
+        this.changed()
+      }
+    })
+  }
+
+  private requestPrune() {
+    if (this.pruning) this.retryPruneAt ??= Date.now()
+    else this.background('retention', () => this.prune())
+  }
+
+  async close() {
+    this.closing = true
+    while (this.work.size) await Promise.allSettled([...this.work.values()])
+    await this.store.scope.close()
+  }
+
+  async tick() {
+    const { document } = await this.jobs.read()
+    const runs = await this.store.read()
+    let nextWindow: number | undefined
+    for (const job of document.jobs.filter(job => job.enabled)) {
+      if (this.closing || this.fault) break
+      try {
+        const schedule = job.schedule
+        if ('at' in schedule && runs.some(run => run.job_id === job.id && run.window === new Date(schedule.at).toISOString()
+          && (terminal(run) || run.input_event_id))) {
+          await this.jobs.settleWindow(job)
+          continue
+        }
+        const windows = runs.filter(run => run.job_id === job.id && run.window !== 'manual').map(run => run.window)
+        const previous = windows.length ? Date.parse(windows.sort().at(-1)!)
+          : 'at' in schedule ? Number.NEGATIVE_INFINITY : Date.parse(job.enabled_at!) - 1
+        const next = windowAfter(job, previous)
+        if (next === undefined) continue
+        if (next > Date.now()) {
+          if (next < (Math.floor(Date.now() / 60_000) + 1) * 60_000) {
+            nextWindow = Math.min(nextWindow ?? next, next)
+          }
+          continue
+        }
+        const window = Date.now() - next >= 60_000 ? latestWindow(job, Date.now()) : next
+        await this.accept(job.id, new Date(window).toISOString(), Date.now() - window >= 60_000)
+      } catch (error) {
+        console.error('Scheduler job', job.id, error instanceof Error ? error.message : String(error))
+      }
+    }
+    return nextWindow
+  }
+
+  async accept(jobId: string, window = 'manual', missed = false): Promise<Run> {
+    const { document } = await this.jobs.read()
+    const snapshot = document.jobs.find(job => job.id === jobId)
+    if (!snapshot) throw new ScheduleError('schedule_not_found')
+    const accepted = await this.store.update(runs => {
+      const existing = window === 'manual' ? undefined : runs.find(run => run.job_id === jobId && run.window === window)
+      if (existing) return { run: existing, fresh: false }
+      const now = new Date(Date.now()).toISOString()
+      const reason = missed ? 'missed' : !snapshot.enabled ? 'disabled'
+        : runs.some(run => run.job_id === jobId && !terminal(run)) ? 'overlap'
+        : runs.filter(run => !terminal(run)).length >= document.max_concurrent_runs ? 'capacity' : undefined
+      const deadline = new Date(Date.now() + snapshot.max_run_minutes * 60_000)
+      if (!reason && (!Number.isFinite(deadline.getTime()) || deadline.getUTCFullYear() > 9999)) {
+        throw new ScheduleError('schedule_invalid', 'Run deadline exceeds the persisted timestamp range')
+      }
+      const runId = randomUUID()
+      const run: Run = { run_id: runId, job_id: jobId, window, state: reason ? missed ? 'missed' : 'skipped' : 'launching',
+        created_at: now, submission_id: `scheduler:${runId}`, detail: reason ?? '',
+        ...(reason ? { ended_at: now } : {
+          deadline_at: deadline.toISOString(),
+          ...(snapshot.created_by === 'user' ? {} : { report_to: snapshot.created_by.tool }),
+        }),
+      }
+      runs.push(run)
+      return { run, fresh: true }
+    })
+    if (accepted.fresh && !terminal(accepted.run)) this.background(accepted.run.run_id, () => this.execute(snapshot, accepted.run))
+    else if (accepted.fresh) {
+      if (window !== 'manual' && 'at' in snapshot.schedule) await this.jobs.settleWindow(snapshot)
+      this.requestPrune()
+    }
+    return accepted.run
+  }
+
+  private async check(snapshot: Job, runId: string, revision = snapshot.revision,
+    binding = snapshot.session_id): Promise<Run | undefined> {
+    let current: Job | undefined
+    try { current = (await this.jobs.read()).document.jobs.find(job => job.id === snapshot.id) }
+    catch (error) {
+      if (!(error instanceof SettingsReadError)) throw error
+      await this.finish(runId, 'skipped', 'settings_read_failed')
+      return undefined
+    }
+    const run = (await this.store.read()).find(run => run.run_id === runId)!
+    if (terminal(run) || this.closing || this.fault) return undefined
+    if (Date.now() >= Date.parse(run.deadline_at!)) {
+      await this.finish(runId, 'timed_out', 'deadline_before_input')
+      return undefined
+    }
+    if (!current || current.revision !== revision || !current.enabled
+      || current.mode !== snapshot.mode || current.session_id !== binding) {
+      await this.finish(runId, 'skipped', current && !current.enabled ? 'disabled' : 'changed')
+      return undefined
+    }
+    return run
+  }
+
+  private async execute(snapshot: Job, accepted: Run) {
+    const submitted = await this.submit(snapshot, accepted)
+    if (submitted) await this.follow({ ...accepted, session_id: submitted.sessionId, input_event_id: submitted.receipt.inputId }, submitted.receipt.sequence)
+  }
+
+  private async bind(snapshot: Job, runId: string, sessionId: string): Promise<number | 'unbound' | undefined> {
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const run = (await this.store.read()).find(run => run.run_id === runId)!
+      if (terminal(run) || this.closing || this.fault) return
+      let result
+      try {
+        result = await this.jobs.bind(snapshot, sessionId)
+      } catch (error) {
+        if (error instanceof SettingsReadError) await this.finish(runId, 'skipped', 'settings_read_failed')
+        else if (error instanceof ScheduleError && error.code === 'schedule_conflict') {
+          if (attempt === 0) continue
+          await this.store.update(runs => { runs.find(run => run.run_id === runId)!.detail = 'binding_conflict' })
+          return 'unbound'
+        } else if (error instanceof ScheduleError && ['user_only_field', 'invalid_document'].includes(error.code)) {
+          await this.finish(runId, 'failed', `binding_rejected: ${error.code}`)
+        } else await this.finish(runId, 'skipped', 'binding_unconfirmed')
+        return
+      }
+      if (typeof result === 'number') return result
+      await this.finish(runId, 'skipped', result)
+      return
+    }
+  }
+
+  private async submit(snapshot: Job, accepted: Run) {
+    if (!await this.check(snapshot, accepted.run_id)) return
+    let requested
+    try { requested = effective(snapshot) }
+    catch (error) {
+      if (!(error instanceof ScheduleError)) throw error
+      await this.finish(accepted.run_id, 'failed', error.code)
+      return
+    }
+    let sessionId: string
+    if (snapshot.mode === 'create' || !snapshot.session_id) {
+      let reply
+      try {
+        reply = await this.sessions.launch({ cwd: snapshot.cwd, policy: requested,
+          ...(snapshot.agent_id ? { agent: snapshot.agent_id } : {}), ...(snapshot.model ? { model: snapshot.model } : {}),
+          ...(snapshot.created_by === 'user' ? {} : { starter: {
+            sessionId: snapshot.created_by.tool.session_id, branchId: snapshot.created_by.tool.branch_id,
+          } }),
+        })
+      } catch {
+        await this.finish(accepted.run_id, 'lost', 'launch_reply_unknown')
+        return
+      }
+      if (!reply.ok) {
+        await this.finish(accepted.run_id, 'failed', reply.error.code)
+        return
+      }
+      sessionId = reply.value.sessionId
+      await this.store.update(runs => Object.assign(runs.find(run => run.run_id === accepted.run_id)!, {
+        session_id: sessionId, session_origin: 'launch', policy: reply.value.policy,
+      }))
+    } else {
+      let live, actual
+      try {
+        live = snapshot.created_by === 'user' ? await this.jobs.permissions.permissionDefaults({})
+          : (await this.jobs.permissions.permission({ sessionId: snapshot.created_by.tool.session_id, branchId: snapshot.created_by.tool.branch_id })).policy
+      } catch {
+        if (await this.check(snapshot, accepted.run_id)) await this.finish(accepted.run_id, 'skipped', 'policy_read_failed')
+        return
+      }
+      try {
+        actual = (await this.jobs.permissions.permission({ sessionId: snapshot.session_id, branchId: 'main' })).policy
+      } catch (error) {
+        const missing = error !== null && typeof error === 'object' && 'code' in error
+          && (error.code === 'session_closed' || error.code === 'branch_missing') ? error.code : undefined
+        if (await this.check(snapshot, accepted.run_id)) await this.finish(accepted.run_id,
+          missing ? 'failed' : 'skipped', missing ?? 'policy_read_failed')
+        return
+      }
+      if (!within(actual, requested) || !within(actual, live)) {
+        if (await this.check(snapshot, accepted.run_id)) await this.finish(accepted.run_id, 'skipped', 'policy')
+        return
+      }
+      sessionId = snapshot.session_id
+      await this.store.update(runs => Object.assign(runs.find(run => run.run_id === accepted.run_id)!, {
+        session_id: sessionId, session_origin: 'reuse', policy: actual,
+      }))
+    }
+    let revision = snapshot.revision, binding = snapshot.session_id
+    if (snapshot.mode === 'reuse' && !snapshot.session_id) {
+      const bound = await this.bind(snapshot, accepted.run_id, sessionId)
+      if (bound === undefined) return
+      if (bound !== 'unbound') { revision = bound; binding = sessionId }
+    }
+    if (!await this.check(snapshot, accepted.run_id, revision, binding)) return
+    let receipt, inputReply
+    try {
+      inputReply = await this.sessions.input({ sessionId, branchId: 'main', mode: 'queue', submissionId: accepted.submission_id,
+        rawBlocks: [{ text: `<dim-scheduler kind="scheduled-run" job="${escaped(snapshot.id)}" run="${escaped(accepted.run_id)}">${escaped(snapshot.name)}</dim-scheduler>` }],
+        content: [{ type: 'text', text: snapshot.prompt }],
+      })
+ } catch { }
+    if (inputReply?.ok) receipt = inputReply.value
+    else if (inputReply && !['reloading', 'publication_unknown', 'ambiguous'].includes(inputReply.error.code)) {
+      await this.finish(accepted.run_id, 'failed', inputReply.error.code)
+      return
+    }
+    if (!receipt) {
+      const current = (await this.store.read()).find(run => run.run_id === accepted.run_id)!
+      receipt = await this.lookup(current)
+      if (!receipt) return
+    }
+    await this.store.update(runs => Object.assign(runs.find(run => run.run_id === accepted.run_id)!, {
+      state: 'submitted', input_event_id: receipt.inputId,
+    }))
+    return { sessionId, receipt }
+  }
+
+  private async lookup(run: Run) {
+    while (!this.closing) {
+      let reply
+      try { reply = await this.sessions.lookup({ sessionId: run.session_id!, branchId: 'main', submissionId: run.submission_id }) }
+      catch { await pause(1000); continue }
+      if (reply.ok) {
+        if (reply.value.status === 'accepted') return reply.value
+        await this.finish(run.run_id, 'lost', 'input_unknown')
+        return
+      }
+      if (reply.error.code !== 'reloading') { await this.finish(run.run_id, 'lost', reply.error.code); return }
+      await pause(1000)
+    }
+  }
+
+  private async resume(run: Run) {
+    if (!run.session_id) { await this.finish(run.run_id, 'lost', 'launch_identity_unknown'); return }
+    if (!run.input_event_id) {
+      const found = await this.lookup(run)
+      if (!found) return
+      await this.store.update(runs => Object.assign(runs.find(value => value.run_id === run.run_id)!, { state: 'submitted', input_event_id: found.inputId }))
+      await this.follow({ ...run, input_event_id: found.inputId }, found.sequence)
+    } else await this.follow(run)
+  }
+
+  private async follow(run: Run, after = 0) {
+    const history = new RunHistory(this.sessions, run.session_id!, run.input_event_id!, after)
+    let stopIssued = false
+    while (!this.closing && !this.fault) {
+      if (!await history.read()) { await pause(1000); continue }
+      if (history.outcome) {
+        await this.finish(run.run_id, stopIssued && history.outcome.state === 'cancelled' ? 'timed_out' : history.outcome.state, history.outcome.detail)
+        return
+      }
+      if (Date.now() >= Date.parse(run.deadline_at!)) {
+        if (history.applied && history.interrupted && !history.consumed) {
+          await this.finish(run.run_id, 'timed_out', 'interrupted_before_consumption')
+          return
+        }
+        if (!history.applied && !history.consumed) {
+          let withdrawn
+          try { withdrawn = await this.sessions.withdraw({ sessionId: run.session_id!, branchId: 'main', inputId: run.input_event_id!, reason: 'scheduled run timed out' }) }
+ catch { }
+          if (withdrawn?.ok && withdrawn.value.status === 'deleted') { await this.finish(run.run_id, 'timed_out', 'withdrawn_at_deadline'); return }
+          await history.read()
+        } else if (history.consumed && !stopIssued) {
+          stopIssued = true
+          try {
+            const stopped = await this.sessions.stop({ sessionId: run.session_id!, branchId: 'main', reason: 'scheduled run timed out' })
+            if (!stopped.ok && stopped.error.code === 'reloading') stopIssued = false
+          }
+ catch { }
+        }
+      } else if (history.consumed && run.state !== 'running') {
+        await this.store.update(runs => { runs.find(value => value.run_id === run.run_id)!.state = 'running' })
+        run.state = 'running'
+      }
+      const remaining = Date.parse(run.deadline_at!) - Date.now()
+      await pause(remaining > 0 ? Math.min(1000, remaining) : 1000)
+    }
+  }
+
+  private async finish(runId: string, state: Run['state'], detail: string) {
+    const run = await this.store.update(runs => {
+      const run = runs.find(run => run.run_id === runId)!
+      if (terminal(run)) return undefined
+      run.state = state
+      run.detail = run.detail === 'binding_conflict' ? `binding_conflict${detail ? `; ${detail}` : ''}` : detail
+      run.ended_at = new Date(Date.now()).toISOString()
+      return run
+    })
+    if (!run?.report_to || !['completed', 'failed', 'cancelled', 'timed_out', 'lost'].includes(run.state)) return
+    let failure: string | undefined
+    try {
+      const body = `Scheduled job ${run.job_id}, run ${run.run_id}: ${run.state} (${run.detail}).${run.session_id ? ` Session ${run.session_id}.` : ''}\n${this.reportGuidance}`
+      const reply = await this.sessions.input({ sessionId: run.report_to.session_id, branchId: run.report_to.branch_id,
+        mode: 'steer', submissionId: `scheduler-report:${run.run_id}`, rawBlocks: [{ text:
+          `<dim-scheduler kind="report" job="${escaped(run.job_id)}" run="${escaped(run.run_id)}">${escaped(body)}</dim-scheduler>`,
+        }], content: [],
+      })
+      if (!reply.ok) failure = reply.error.code
+    } catch { failure = 'bridge_error' }
+    if (failure) await this.store.update(runs => {
+      runs.find(value => value.run_id === runId)!.detail += `; report_failed: ${failure}`
+    })
+  }
+
+  async prune() {
+    if (this.pruning) {
+      this.retryPruneAt ??= Date.now()
+      return
+    }
+    this.pruning = true
+    this.retryPruneAt = undefined
+    try {
+      const runs = await this.store.read()
+      const { document } = await this.jobs.read()
+      const keep = new Set(runs.filter(run => !terminal(run) || this.work.has(run.run_id)).map(run => run.run_id))
+      for (const job of document.jobs) {
+        const newest = runs.filter(run => run.job_id === job.id && terminal(run))
+          .sort((a, b) => b.ended_at!.localeCompare(a.ended_at!) || b.run_id.localeCompare(a.run_id)).slice(0, 100)
+        for (const run of newest) keep.add(run.run_id)
+      }
+      const references = new Set([...document.jobs.filter(job => job.mode === 'reuse').map(job => job.session_id),
+        ...runs.filter(run => keep.has(run.run_id)).map(run => run.session_id)].filter((id): id is string => id !== undefined))
+      for (const sessionId of references) {
+        const ownership = runs.filter(run => run.session_id === sessionId && run.session_origin === 'launch')
+          .sort((a, b) => b.created_at.localeCompare(a.created_at) || b.run_id.localeCompare(a.run_id))[0]
+        if (ownership) keep.add(ownership.run_id)
+      }
+      const expired = runs.filter(run => !keep.has(run.run_id))
+      const deletions = new Set(expired.filter(run => run.session_origin === 'launch' && !references.has(run.session_id!)).map(run => run.session_id!))
+      for (const sessionId of deletions) {
+        try {
+          const reply = await this.sessions.delete({ sessionId })
+          if (!reply.ok) throw new ScheduleError(reply.error.code)
+        } catch (error) {
+          this.retryPruneAt = Date.now() + 60_000
+          for (const run of expired.filter(run => run.session_id === sessionId && run.session_origin === 'launch')) keep.add(run.run_id)
+          console.error('Scheduler cleanup', error instanceof Error ? error.message : String(error))
+        }
+      }
+      const remove = new Set(expired.filter(run => !keep.has(run.run_id)).map(run => run.run_id))
+      if (remove.size) await this.store.update(current => {
+        for (let index = current.length - 1; index >= 0; index--) if (remove.has(current[index].run_id) && !this.work.has(current[index].run_id)) current.splice(index, 1)
+      })
+    } catch (error) {
+      this.retryPruneAt = Date.now() + 60_000
+      console.error('Scheduler retention', error instanceof Error ? error.message : String(error))
+    } finally { this.pruning = false }
+  }
+}

package/plugins/scheduler/history.ts

@@ -0,0 +1,60 @@
+import type { Sessions } from '../../../npm/plugin.js'
+import type { Run } from './store.ts'
+
+/** The published prefix following this run's own input; no idle wait or cross-Session subscription. */
+export class RunHistory {
+  readonly sessions: Sessions
+  readonly sessionId: string
+  readonly inputId: string
+  after: number
+  through: number | undefined
+  applied = false
+  consumed = false
+  deleted = false
+  interrupted = false
+  outcome: Pick<Run, 'state' | 'detail'> | undefined
+
+  constructor(sessions: Sessions, sessionId: string, inputId: string, after = 0) {
+    this.sessions = sessions; this.sessionId = sessionId; this.inputId = inputId; this.after = after
+  }
+
+  async read(): Promise<boolean> {
+    for (;;) {
+      let page
+      try {
+        page = await this.sessions.history({ sessionId: this.sessionId, branchId: 'main', after: this.after,
+          ...(this.through === undefined ? {} : { through: this.through }), limit: 256,
+        })
+      } catch (error) {
+        console.error('Scheduler history', this.sessionId, error instanceof Error ? error.message : String(error))
+        return false
+      }
+      if (!page.ok) {
+        if (page.error.code === 'reloading') return false
+        this.outcome ??= { state: 'failed', detail: page.error.code }
+        return true
+      }
+      this.through = page.value.through
+      for (const event of page.value.events) {
+        this.after = event.sequence
+        if (event.type === 'input' && event.data.input_id === this.inputId) {
+          if (event.name === 'applied') this.applied = true
+          if (event.name === 'consumed') this.consumed = true
+          if (event.name === 'deleted') this.deleted = true
+        }
+        if (this.applied && !this.consumed && event.type === 'stop' && event.name === 'interrupt') this.interrupted = true
+        if (this.consumed && !this.outcome && event.type === 'turn' && event.name === 'end') {
+          this.outcome = event.data.status === 'completed' ? { state: 'completed', detail: 'completed' }
+            : event.data.status === 'failed' ? { state: 'failed', detail: 'turn_failed' }
+            : { state: 'cancelled', detail: 'interrupted' }
+        }
+      }
+      if (!page.value.events.length || this.after >= this.through) {
+        this.after = this.through
+        this.through = undefined
+        if (this.deleted && !this.consumed) this.outcome = { state: 'cancelled', detail: 'withdrawn' }
+        return true
+      }
+    }
+  }
+}