> ## Documentation Index
> Fetch the complete documentation index at: https://oxy.tech/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cron Scheduling, Orchestrator Dashboard, and Semantic Pre-Aggregation

> Schedule workflows, pipelines, and agents on a cron, monitor them in a redesigned Orchestrator dashboard, and serve semantic queries from local Parquet rollups.

<Icon icon="calendar" iconType="regular" size={16} /> **May 28, 2026** · v0.5.58

### New Features

#### Cron Scheduling for Workflows, Pipelines, and Agents

Workflows, Airway ELT pipelines, and analytics agents can now run on a cron schedule, with a full CRUD surface in workspace settings. Previously, every run was tied to an explicit HTTP request — now Oxy ships a durable standalone consumer that drives scheduled jobs across replicas.

* **Schedules settings panel** — A new **Schedules** section under Settings → Workspace lists every schedule with its next and last run, enable toggle, run-now, edit, and delete actions. The create/edit dialog includes a hand-built **visual cron builder** with a populated target picker (workflow files, Airway pipelines, agents) and an IANA timezone select.
* **Cron-driven targets across the platform** — A schedule can target a workflow file, an Airway ELT pipeline, or an analytics agent. Agent schedules carry a required `question` field, so each tick fires the agent with a fixed prompt and threads results into the run history.
* **Exactly-once across replicas** — Schedules tick through a CAS-based `next_run_at` claim, so multiple Oxy processes can run side by side without double-firing. Missed runs from extended downtime collapse to a single execution rather than replaying.
* **Per-schedule observability** — Each schedule surfaces its last error (with a destructive icon and tooltip when set) and clears it on success. A per-schedule duration-spike anomaly feed surfaces runs that take meaningfully longer than the recent baseline.
* **Cross-process cancel** — Cancelling a scheduled run from the dashboard works even when the run is executing on a different process. A persistent `cancel_requested_at` flag is polled by the executing worker, so cancels are no longer tied to the originating HTTP connection.
* **Workspace-scoped** — Schedules and the runs they produce are scoped per workspace; tenants see only their own schedules even on shared deployments.
* **Inert by default** — Scheduled firing is gated behind the `OXY_INPROC_GLOBAL_WORKER` environment flag. With the flag off, behavior matches today's release — schedule CRUD still works (defining a schedule is harmless), but the periodic loop, latency worker, and tick do nothing.

#### Orchestrator Dashboard (Coordinator Redesign)

The Coordinator surface is rebuilt as a three-tab **Orchestrator** dashboard, giving a single place to see job health, manage schedules, and inspect individual runs across workflows, ELT pipelines, and agents.

* **Overview tab** — Health cards, a swimlane timeline (lanes for each run type with a "now" marker) with a board toggle, and an anomaly feed for failures and duration spikes.
* **Jobs tab** — Catalog of every schedule with filter, search, enable toggle, run-now (with confirm), edit, and delete actions. A **Job Detail** view shows the schedule definition with the next five runs in its timezone, a health card with a missed-run audit and a **Backfill** button, and per-job run history. The backfill dialog computes a live blast radius before queuing.
* **Runs tab** — URL-synced filters (copy the URL → filters survive), a trigger column labeling each run as `scheduled` / `manual` / `backfill` / `retry`, list-level cost hints on agent rows with LLM activity, bulk retry and cancel respecting actionable counts, and a `System: off/on` toggle that hides preagg cycles and other system-managed runs from the feed by default.
* **Polymorphic Run Detail** — Each run type shows the right view at the top of its detail page:
  * **Agent runs** — an LLM Usage card with tokens in/out/cache, dollar cost, and model list.
  * **Workflow runs** — a per-step timing card with hot-spot marker.
  * **ELT runs** — a per-table row-count card with extract/load phase durations and drop warnings.
* **Bulk retry** — Bulk retry on the Runs tab clones the failed runs as new attempts, so backfills and recoveries don't require manual one-at-a-time replays.
* **Per-tenant correctness** — Every coordinator endpoint (list, active, tree, retry, recovery, queue, live SSE) is now scoped by `workspace_id` from the URL. Multi-tenant deployments no longer expose runs across workspace boundaries.

#### Semantic Pre-Aggregation Rollups

Semantic-layer queries can now be served from locally-materialized Parquet rollups instead of round-tripping to the warehouse, with a background worker that keeps them fresh.

* **Background pre-aggregation worker** — A coordinator-driven worker evaluates each rollup's `refresh_key`, rebuilds stale rollups in parallel, and materializes results to local Parquet via a hot-swap rename. Empty rollups don't poison the manifest, and crash-recovered cycles are retried from scratch on the next tick.
* **Fast path on every semantic query surface** — The local Parquet path is wired into every place semantic queries execute: workflow and procedure `semantic_query` steps, the IDE **Run** button on `/semantic`, the analytics agent pipeline (both serial and fan-out execution), and the Builder's `semantic_compiler` tool. When a query matches a fresh rollup, it serves from Parquet via an in-process DuckDB instance; otherwise it falls back to the warehouse.
* **Three-layer freshness** — Per-query freshness is verified by an in-memory cache, the on-disk manifest's `build_date` (which survives restarts), and a SQL `refresh_key` check against the warehouse. The operator-configurable `pre_aggregations.refresh_worker.renewal_threshold` controls how aggressively the worker rebuilds.
* **Pre-aggregation badge in the UI** — `QueryExecuted` events now carry an `is_preagg` flag. Analytics agent thread SQL blocks, workflow `semantic_query` results, and procedure runs all surface a **Pre-aggregated** badge so users can see at a glance which queries served from a rollup.
* **Rollup explorer integration** — The semantic explorer surfaces rollup detail with click-to-apply dimensions and measures, so it's easy to see which rollups feed which questions.

#### Workspaces in Git Subdirectories

Oxy now supports git repositories where the workspace lives in a subdirectory, not at the repo root — a common pattern when several Oxy workspaces share a single repo.

* **Automatic git root discovery** — Workspace tooling now walks up from the workspace directory to find the actual `.git` entry, mirroring git's own discovery behavior. Git operations resolve to the correct repo regardless of where in the tree the workspace lives.
* **Correct GitHub URLs from the IDE header** — Links from the IDE now include the subdirectory path (`/tree/<branch>/packages/my-app`) so they jump to the right folder on GitHub. Workspaces at the repo root continue to work unchanged.

***

### Platform Improvements

#### Pre-Aggregation Reliability

* **Crash-recovery for stuck pre-aggregation cycles** — Any pre-aggregation runs left in `running` at startup are now marked failed so the next tick can retry from scratch, instead of blocking the worker indefinitely. Database errors during recovery are logged rather than silently swallowed.
* **Workspace-scoped pre-aggregation runs** — Pre-aggregation runs now carry a `workspace_id` so the worker schedules and tracks them per tenant. Fixes a compile-time regression where the background worker hadn't been updated to the new run-insertion signature.
* **Defensive overflow handling on `Every` intervals** — Extremely large `Every` interval values no longer cause spurious continuous rebuilds. The overflow case is logged with the interval and rollup hash and treated as "always fresh" until the misconfiguration is corrected.

#### Workspace Examples

* **Missing example view restored** — The starter workspace shipped without one of its expected example `.view.yml` files, which broke a downstream example dashboard. The missing view is now included again so `oxy init` workspaces work end-to-end out of the box.