Sequencer

The Sequencer runs unattended imaging. You author a plan — targets, filters, exposures — and a set of policy phases that wrap the imaging run (open the roof, point, focus, then park and close up). The executor walks the plan on a background thread, drives the equipment through the Console, and publishes a live journal you can watch in the UI or read at /api/sequencer/state.

This page describes the executor in core/sequencer/run.py and the plan model in plan.py / structured.py. For the on-disk plan format see the Plans topic; for autofocus internals see Autofocus.

What a run is made of

A compiled plan is a flat list of timeline steps the executor walks in order. Wrapped around that list are five policy phases — ordered action lists that run at lifecycle boundaries (start, error, suspend, resume, end). Plan-wide policy (constraints, focus triggers, cooling, meridian, guiding) rides along in a hidden notes step and is consulted between steps.

So a run looks like:

  1. Guiding precondition (if the plan guides) — a stand-alone run refuses to start unless PHD2 is open and connected, with a clear message telling you to connect the guide camera + mount first.
  2. Cooling on-start (if asked) — set the setpoint, optionally wait to settle.
  3. on_start phase — gates (wait-for-safe, wait-for-darkness, wait-until-time, altitude), then actions (open roof, unpark, precise point, autofocus...).
  4. The timeline — slew / filter / expose / wait / focus / guiding, step by step, with constraint, focus-trigger and meridian checks between exposures, plus optional per-frame quality acceptance.
  5. Cooling on-end (warm up, if asked).
  6. on_end phase — park, close roof, warm camera...

A pause drops into the on_suspend phase and holds; a resume runs on_resume and continues. A failed step runs the on_error phase and ends the run. A stand-alone run also drops a checkpoint at every step so an interrupted night can be resumed.

Timeline steps

Each step has a kind. The full vocabulary (validated in plan.py):

Steps are produced for you by the structured editor; you can also hand-write them in the TOML tab.

Policy phases

A phase is an ordered list of actions plus optional gates. The phase action catalog is the single source of truth, and the editor builds its menus from it. Each action has a fixed domain:

The domain split is what makes a sequence safe to run inside a blockscript. When a run is injected (blockscript-supervised), every obs action is SKIPPED — the blockscript owns the roof/mount/power — and only img actions run. Stand-alone runs execute every action. Unknown action types are dropped on normalise, so a hand-edited plan can't inject an unsupported action.

The phases:

A light frame or a guiding start on a parked mount is refused (the journal says why), and tracking that is off is switched on before a light frame - so a plan whose on_resume restarts the sequence must unpark and slew to its target (in on_start or as steps). Plan validation warns when it does not. A step can opt out with allow_parked_mount = true (a bench test at the park position).

A resume unparks a parked mount (v23). When a pause parked the mount (the plan's on_suspend) and on_resume does not unpark it, the resume does: the re-point at the current target unparks first, and when there is no target to re-point at but the plan's next move is a slew, the mount is unparked before that slew. The park state is read back; an unpark that cannot be confirmed stops the run. A plan that goes straight on exposing with no slew stays parked, and its light frames are refused as above.

(The structured plan normaliser defines on_start, on_error, on_suspend, on_resume, on_end. Legacy on_end bool flags — park / warm_up_camera — are synthesised into an on_end action list when no new-style list exists.)

On-start / on-resume gates

Before a phase's actions run, its optional gates hold until preconditions are met (used mostly on on_start and on_resume):

Per-action completion and wait

Each action is issued, then waited on until it actually completes before the next runs — never fire-and-forget, never parallel. Completion is confirmed three ways (from _WAIT_SPEC):

Override per action via its params: wait_s (dwell / extra settle), settle_s, timeout_s.

Per-action on-fail policy

When an action fails or times out, its optional on_fail policy decides (_apply_on_fail):

With no policy, a failed action cancels the phase. Injected runs always cancel, so the blockscript's error handling takes over. An exec-count safety cap guarantees the retry loop terminates.

The start prompt (v23). A stand-alone sequence can ask you instead of cancelling at once. Set Settings → Sequencer defaults → When a start-up step fails, wait for an answer for (s) ([performance] start_prompt_timeout_s; default 0 = do not ask). Then a failed on_start action with no on-fail policy shows a prompt in the run view: Try again, Cancel, or Let it pass. A failed roof action never offers Let it pass. Try again may be answered up to three times for one action. No answer within the time, or a Stop, is a Cancel. Only on_start asks; the make-safe phases never wait for a person. The API equivalent is POST /api/sequencer/prompt; the pending question is in /api/sequencer/state as prompt.

A pointing action (precise_point, slew_radec, blind_solve, blind_resync) whose plate solve fails or does not converge still finishes its job "succeeded" — the failure is in the job's result. Since v22.2.17 the phase reads it: with an on-fail policy that policy decides (pass, or retry the pointing); without one the phase carries on with the blind pointing, as it always did, and the journal says precise_point: FAILED - <reason> - carrying on (no on-fail policy). Until then the journal read precise_point: ok (rig 1, 2026-10-18).

Plan-wide policy (between-step checks)

These ride in the hidden notes policy step and are consulted by the run loop, mostly before each expose.

Constraints

Altitude/hour-angle/time gates, read from the mount's live properties:

A tripped altitude/HA constraint skips the current target (all its steps until the next slew) and continues — it does not abort the run. If no mount reports properties, the check is skipped rather than blocking.

Waiting for a rising target (wait_for_rise, new in v23, off by default). A target under altitude_min_deg is normally skipped for good, even when it is still rising. With wait_for_rise = true in the plan's constraints the run waits for it instead, mount on the target and tracking, and carries on once it clears the minimum.

Focus

Refocus triggers, checked before an expose (_should_refocus):

Since v23:

When a trigger fires, _do_policy_focus runs: if [autofocus].enabled AND a calibration exists, it runs Refocus via _run_sequence_refocus — the always-inward run_refocus from the Autofocus topic. With First Light's formula in focus_recipe.json it measures the stars where the focuser stands and sweeps +/- refocus_range_factor x star size / the V's slope around it, fits the hyperbola and lands on the vertex; without it (no First Light yet) it is the older recipe sweep, and the journal says once per run that First Light has not been run. A plan never runs First Light — that is a set-up step, done once from the Console. It runs synchronously and cancelably (a watchdog ties the sequence Stop flag to the focus run's cancel, so Stop / Halt-all actually abort an in-progress refocus) and restores full-frame / bin 1 afterwards so science subs don't inherit the AF binning. If autofocus is off or uncalibrated it moves to focuser_position; otherwise it journals a no-op. AF failures during a run are fail-soft — journaled, never abort the sequence.

The global [autofocus].refocus_ triggers (refocus_enabled + every_n_frames / every_n_minutes / temp_delta_c / on_filter_change) overlay under* the plan's focus block (plan keys win) and route through this same Refocus path. With [autofocus].filter_offsets mapped, a filter change moves the focuser by the per-filter chromatic delta instead of triggering a full refocus. After a successful refocus, an optional [autofocus].focus_final_offset_steps nudges the focuser a fixed number of steps off the measured best-focus (for a known camera/imaging-train offset); it's fail-soft — a failed nudge is journaled, never aborts the run.

Cooling

Cooling does nothing if [cooling].temp_control_supported is false.

Meridian

For German equatorial mounts. The plan's mode is resolved against [mount].flip_mode:

Checked before each expose. halt ends the sequence cleanly when past the meridian. flip re-slews to the same RA/Dec to force the mount to swap pier sides, settles ([mount].flip_settle_s), and — when the driver reports side-of-pier — VERIFIES the side actually changed; if it didn't, it errors and stops rather than imaging on the wrong side. It refuses to flip if the mount won't report RA/Dec (it never defaults a missing Dec to 0). A flip won't refire within 5 minutes of the last one.

Guiding

The guiding policy (exposure_s, binning, dither cadence, settle gate) round-trips through the plan. When the plan enables guiding AND PHD2 control is allowed (phd2.allow_control):

If PHD2 control is off, guiding start/stop/dither become honest no-ops (they don't silently claim success). Set guide exposure/binning inside PHD2 directly if you don't drive it from the plan.

An optional guiding watchdog ([guiding_watchdog], default off) layers quality gates on top while guiding: it holds the next sub when the guide star is lost or RMS exceeds rms_max_px, waiting up to recover_timeout_s (polled every poll_interval_s) before failing the step.

An unguided plan is never judged or held on guiding (v23). When the plan's guiding policy is off, PHD2's state does not matter: no sub is held, delayed, rejected or failed for it, whatever [guiding_watchdog] says and whether or not PHD2 was guiding earlier in the session. Before v23, with the watchdog on and PHD2 idle after an earlier guided run, every sub of an unguided plan was rejected as "guiding stopped".

Guiding during the sub (v22.2.17). The checks above only prove guiding was right when a sub STARTED. Every guided light sub is now also judged, after it is saved, on what PHD2 reported while its shutter was open (the driver keeps a time-stamped history of guide steps, lost stars and PHD2 alerts). The sub is rejected when, during the exposure:

A rejected sub is booked like a frame-acceptance reject: journaled (frame.reject, with the RMS, the runaway axis, the largest excursion), counted as rejected, never counted in frames_accepted (so the scheduler never credits it to a goal), moved to rejected/ when [frame_acceptance] move_rejects is on (its default, even with frame acceptance off), and re-shot — up to [frame_acceptance] reshoot_max times when frame acceptance is on, else twice. A re-shoot goes through the same gates as the next sub: a due meridian action or the plan's end time ends the step (the sub is still owed), and the pre-sub guiding check holds until guiding is right. On a guided plan a runaway is stopped and re-acquired at once (PHD2 would keep driving the mount off target), and a watchdog hold that sees the guider running away re-acquires without waiting out recover_timeout_s. Fail-soft: an unguided plan (watchdog on or off), PHD2 not under control, a guider that reports nothing for the window, or any error keeps the sub exactly as before.

Systematic guiding fault (v22.2.17). When guiding settles after a (re)start and then, within 5 minutes, runs away again (max-length pulses) or trips the watchdog's RMS — a lost star alone does not count, that is clouds — it is a relapse. The second relapse on the same target, each after its own recovery, is a systematic fault: a calibration problem, or PHD2's "Reverse Dec output after meridian flip" setting after a flip. The target is skipped the way an exhausted re-acquire ladder skips it (the run moves on; one critical alert per target), the guider is stopped, and the journal and the alert say what happened, the likely cause, and PHD2's own alert text when PHD2 sent one. PHD2 does not send an alert you ticked "don't show this again" for — on rig 1 the Dec one was suppressed that night (52 "Suppressed alert" lines in its debug log). A recovery that holds (a new settle without a relapse in between) starts the count again. Rig 1, 2026-10-18: the hold and the ladder cycled for 35 min instead, every "attempt 1/3" succeeding at the settle.

Per-frame quality acceptance

An optional grader ([frame_acceptance], default off) inspects each light sub the moment it's saved and decides whether to keep it. Bias/dark/flat frames and non-light captures are always kept.

Each configured gate rejects a frame that fails it (set to 0 to disable that gate):

The grade is measured on a centred crop (central_region_pct, near the optical axis, for speed). A per_filter_json map lets you loosen the gates per filter — narrowband frames have far fewer stars and larger HFR than broadband, so a single global min_star_count would be wrong for them; any gate not overridden falls back to the global value.

On a reject:

Grading fails open: any error while grading keeps the frame, so a glitch never silently drops data. The running tallies (accepted / rejected / re-shot) appear in the sequencer status.

Every kept sub counts as accepted (v23). A sub that is kept without being graded (frame acceptance off, a non-light frame, a grading error) is counted in the accepted tally too. Before v23 a run with grading off reported "0 accepted" with all its subs on disk.

A light sub can also be rejected for its guiding while the shutter was open (see Guiding during the sub above) — booked, moved aside, counted and re-shot the same way, with frame acceptance on or off; such a sub is not graded.

Run states and controls

idle → running → succeeded (happy path). Other terminals: failed (a step aborted, or on_start failed, or a go-to-end policy fired), stopped (Stop). running ↔ paused for pause/resume; stopping is the transient after Stop.

Checkpoint and resume

A stand-alone run drops a checkpoint at every step boundary (and per-sub inside an exposure), so if a night is cut short — a crash, a power loss, an app restart — you don't lose the whole session. The checkpoint is kept on a crash / FAILED / STOPPED run and dropped on a clean SUCCEEDED completion, so re-running a finished plan always starts fresh.

Resume is target-level: on resume, the on_start phase re-runs (re-establishing pointing / focus / guiding after the downtime), completed targets are skipped, and the run restarts at the in-progress target's slew so it re-acquires and re-shoots that field (resuming mid-target without re-slewing would image the wrong sky). Subs already captured in the resume target are skipped, so you don't re-shoot what you already have.

One checkpoint is kept per plan. A resume is refused if you've edited the plan since the interrupted run (the step list no longer matches) — start fresh instead. Supervised runs (blockscript / scheduler) don't checkpoint; the blockscript or scheduler owns night-level completion.

Resume by itself after a restart (opt-in, new in v23). With [sequencer] auto_resume_after_restart = true (Settings → Sequencer defaults; default off), Starship looks once at start for a stand-alone run that was cut short because Starship or the PC went down, and resumes it the same way Resume does. It does this only when the interruption is recent (auto_resume_max_age_h, default 6 hours), the plan is unchanged, it is dark and SAFE, the plan's end time has not passed, no blockscript owns the night and Windows has no restart pending. A run you stopped, a run that failed or reached its end time, and a run that was going when you shut Starship down on purpose are never resumed. The full list is in the Windows restarts and crashes topic.

Per-step error handling

Every timeline step carries an on_error policy (plan.py):

The structured compiler picks sensible defaults: expose defaults to retry × 2; filter changes, track, guiding start/stop, per-target start conditions and end-of-plan park all default to skip (a sticky wheel or a missed start window shouldn't kill the run); slews default to abort.

Journal and status

Every step and synthetic action appends a StepEvent (timestamp, seq, kind, label, state, message, detail) to the journal and publishes it on the bus (sequencer.event). state is one of started / ok / skipped / failed / retrying (steps) or paused. Top-level status (sequencer.state) carries the run id, plan name, state, current/total step, progress fraction, error, and the last 200 journal events. It also reports the live frame-acceptance tallies (accepted / rejected / re-shot) and, while a refocus runs, a live autofocus V-curve so the run view can draw the focus graph as it happens.

Gotchas

How it ties in

Astroworx Starship v23.1.2 · this page is the in-app help of that buildDownload · HTTP API