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:
- 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.
- Cooling on-start (if asked) — set the setpoint, optionally wait to settle.
- on_start phase — gates (wait-for-safe, wait-for-darkness, wait-until-time, altitude), then actions (open roof, unpark, precise point, autofocus...).
- 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.
- Cooling on-end (warm up, if asked).
- 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):
- slew — move the mount. Either a named target (
to = "M42", resolved via the planetarium send/fetch) or explicitra_h/dec_deg. After the blind slew the executor applies a settle dwell ([mount].settle_after_slew_s). Withprecise = trueit then runs a plate-solve / sync / re-slew pass to tolerance. - rotate — rotate to a sky position angle (
pa_deg) via the plate-solve loop. Emitted per target when you set a PA. - filter — select a filter by
name(looked up in the wheel's reported names, case-insensitive) or bypositionindex. An optional dwell ([camera].additional_safe_time_after_filter_s) follows the change. - expose — take
countframes ofexposure_sseconds. Carriesbinning(omit to use[camera].default_binning),gain,offset,light(true for lights, false for darks/bias),object_name,filter_name. Each frame is one Console capture job, awaited before the next. Auto-dither (if the plan's guiding policy enables it) fires between subs. - wait — sleep
seconds(interruptible; pause doesn't count against it). - wait_until — hold until a condition. Modes, first match wins:
safe = true(SafetySupervisor reports not-actionable-unsafe),alt_min_deg+ra_h/dec_deg(target rises above an altitude — needs[site]),time_local = "HH:MM"(next local wall-clock occurrence), ortime/when(absolute ISO8601).timeout_minbounds the wait; on timeout the step FAILS so itson_errordecides. - focus — move the focuser to
position(optionallyrelative), or withautofocus = truerun a refocus right there — the same refocus as theautofocusphase action. A failed refocus whose own sweep shows the current focus is good keeps the position with a warning; otherwise the step'son_errordecides. Scheduled refocusing during a run is driven by the Focus policy triggers below. - start_guiding / stop_guiding — start PHD2 guiding + wait for settle / stop it. No-ops unless the plan's guiding policy is enabled and PHD2 control is allowed. Guiding a run started is stopped when the run ends however it ends (finished,
end_by, dawn, Stop, a meridian halt or an error), before the make-safe park — even when the plan's ownstop_guidingstep was skipped. A slew (a target slew or a re-centre) stops PHD2 first, whoever started it, because a slew breaks the lock anyway; a guided plan restarts it on the new field afterwards (unless its ownstart_guiding/stop_guidingstep comes next, or a weather suspend is under way), an unguided plan leaves it stopped. The slewing phase actions (precise_point,slew_radec,blind_solve) stop it too. - dither — explicit dither request. Commands PHD2 when guiding+dither are enabled and control is allowed; otherwise records the request and no-ops honestly.
- track — tracking on/off (
on = true|false). - park / unpark — mount park state.
- flat_cover — open or close a CoverCalibrator flat panel (
action = "open"|"close"). - warm_camera — run the cooler warm-up ramp (used at end-of-plan without a full on_end phase).
- run_script — run an external command at any body point via the sandboxed script executor (
command— the script path plus inline args — with optionalargs,timeout(ortimeout_s),fail_ok,cwd,shell).$filterin the command or its args becomes the name of the filter in place. Withfail_ok = truea failed script is noted and the step counts as done. Honours the[scripts]policy and the Stop flag, so a Stop aborts a long-running script promptly. Off unless you've opted into external scripts. - set — assign a variable into the scope. notes — comment / no-op (also the carrier for plan policy).
- repeat — repeat a body N times (
countmust be a literal at compile time). loop_targets — iterate atargetslist, binding$target_name,$target_ra_h,$target_dec_degper iteration.
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:
- obs (observatory):
open_roof,close_roof,park,unpark,find_home,power_on/power_off(need achannelswitch id),connect_power/disconnect_power,slave_dome/unslave_dome,dome_park,dome_find_home,dome_goto(azimuth),open_flat_cover/close_flat_cover,connect_all/disconnect_all(bring every configured device up or down; with PHD2 control on, connect_all also brings PHD2 up last - launching it when[phd2] auto_startis on - and disconnect_all first has PHD2 stop guiding and disconnect its guide camera + mount). - img (imaging):
precise_point(slew + solve + center),slew_radec(ra_hours,dec_deg),autofocus,blind_solve(solve the current field and sync the pointing model),blind_resync(whole-sky hint-free solve + sync — recovers a mount that's lost where it's pointing),cool_camera(setpoint_c, optionalramp_minutesfor a gentle ramp,wait_settle),warm_camera,start_guiding,stop_guiding,abort_exposure,run_script(command,timeoutortimeout_s,fail_ok;$filterin the command becomes the filter in place - see the External scripts topic),notify(message,severityinfo|warn|critical — journals AND sends via the configured alerts channel, best-effort; safe in any phase).
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:
- on_start — gates then setup. A failure of a gating or imaging action here returns an error and ABORTS before any capture (then on_error runs to leave the rig safe).
precise_point/blind_solvehere point at the plan's first coordinate-bearing target (on a resumed run, at the resume target's field). - on_error — runs when a timeline step aborts the sequence: park, close roof, warm camera, leave it safe.
- on_suspend — runs the moment a pause drops the run into PAUSED (stop guiding, abort exposure, park...). Author it in the editor's On Suspend tab like any other phase. An operator pause can keep the rig as it is instead (
POST /api/sequencer/pausewith{"make_safe": false}): on_suspend is not run, the hold still runs it at once if the weather turns UNSAFE, the plan's end time still ends the run, and the resume skips on_resume because nothing was closed. - on_resume — runs on the way back to RUNNING after a pause (reopen, unpark, re-cool, blind solve, restart guiding).
- on_end — park, close roof, warm camera, etc. Runs whether the sequence finished naturally OR was stopped, so the rig is always left safe. The one exception is an operator stop that asks for it:
POST /api/sequencer/stopwith{"skip_end_phase": true}leaves the rig exactly as it is (no on_end, no warm-up) - for switching to another plan mid-night without closing and reopening the observatory. The journal records it.
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):
- wait_for_safe — hold until the Safety supervisor reports SAFE (a WARNING/UNSAFE/UNKNOWN verdict keeps waiting; no supervisor configured = don't block).
- wait_safe_dark — hold until the Sun drops below the darkness threshold (
dark_sun_alt_deg, default −18° astronomical), optionally plus an extra offset (dark_offset_minutes). Needs your[site]coordinates; skipped if the site is unset. - wait_until_utc — hold until an absolute ISO8601 time.
- altitude_min_deg — advisory at the phase level; the per-target altitude constraint still enforces it during the run.
- max_wait_minutes — caps the total gate wait; exceeding it fails the gate (which aborts on_start).
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):
- status — poll the device's reported end-state:
open_roof/close_roof(shutter open/closed, 60 s timeout),park/unpark(AtPark, 120 / 30 s),find_home(180 s),cool_camera(cooler settled, 300 s). The command methods return on command-accepted, so polling is what proves the action finished. - job — poll a background job to succeeded/failed, then settle:
precise_point,slew_radec,autofocus,blind_solve,blind_resync(300 s, 5 s settle for slews). - dwell — no reliable end signal, so wait a fixed time:
warm_camera,power_on/power_off,connect_power/disconnect_power,abort_exposure, guiding,connect_all/disconnect_all,notify.
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):
mode = "cancel"(default) — cancel the phase. In on_start this aborts the run; elsewhere it propagates.mode = "pass"— log it and move to the next action. The journal says so in one line:precise_point: FAILED (on_fail pass) - <reason>.mode = "retry"withretries(1–99) — retry up to N times, resuming fromretry_from("self","phase_start", or an earlier action index). When retries are exhausted, fall through tothen:cancel/pass/go_to_end(a pass then readsFAILED (on_fail retry xN, then pass)).then = "go_to_end"abandons the remaining timeline steps and falls through to the on_end phase (the run still ends as FAILED).
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:
altitude_min_deg/altitude_max_deg— skip the target when outside the band.hour_angle_min_h/hour_angle_max_h— HA = sidereal_time − RA, wrapped to ±12 h.end_by_utc— absolute ISO8601 time; once passed, the whole sequence ends.
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.
wait_for_rise_max_minutes(default 120) is the longest it waits. After that the target is skipped as before.- It waits only for a target east of the meridian (rising). A target past the meridian is getting lower and is skipped at once.
- It never waits past
end_by_utcor the dawn gate, and a pause or a weather suspend during the wait is honoured. - The journal says
target at …° is below its minimum …° but rising - waiting up to … min for it (wait_for_rise).
Focus
Refocus triggers, checked before an expose (_should_refocus):
every_n_frames— refocus after N captured frames (counter resets per target).every_x_minutes— refocus on a wall-clock interval.delta_temp_c— refocus when the focuser temperature drifts this many degrees.on_filter_change— schedule a refocus on the next expose after a filter change.repoint_after_refocus— after every refocus one of these triggers fires, plate-solve and re-centre on the current target (precise pointing). Off by default. In the editor: Focus > Precise point on the target again after each refocus. It keeps a long run on one target from drifting (dithers and the refocus itself move the picture a little); it adds about a minute per refocus, and guiding stops for the slew and restarts by itself. A re-point that does not converge keeps the pointing it reached; a slew the mount refuses is journalled and the run carries on.focuser_position— fallback position when autofocus isn't available.
Since v23:
- A refocus that comes due is run between subs. The frame-count, time and temperature triggers (and the HFR-drift trigger below) are also checked between the subs of one expose step. When one is due the step stops after the current sub, the refocus runs, and the step carries on with the subs it still owes. Before v23 a refocus waited for the end of the whole block.
- A refocus near the end of the run is skipped. When the plan's
end_by_utcor its dawn gate is less than 10 minutes away, a due time, temperature, frame-count or drift refocus is not run, and the run images to the end at the current focus. The journal says so once per run. A filter-change refocus is never skipped: the new filter needs its focus. - Refocus on HFR drift (opt-in, new in v23).
[autofocus] refocus_on_hfr_drift_pct(default 0 = off): refocus when the median HFR of the lastrefocus_hfr_drift_framessubs (default 5, at least 2) is this many percent worse than the median of the first subs after the last focus. It needs the masterrefocus_enabledswitch and frame acceptance on ([frame_acceptance] enabled), because the HFR comes from the frame grading. A new target, a new filter or a refocus starts a new baseline. - Temperature compensation (opt-in, new in v23).
[autofocus] temp_comp_steps_per_c(default 0 = off): between subs, the focuser is moved this many steps for each degree C of change since the last focus. The sign is the direction. Only whole steps are moved, and only once the correction reachestemp_comp_min_steps(default 1). A refocus is the new zero. A temperature jump of more than 5 °C between two reads is taken as a sensor glitch and nothing moves. A failed move is journalled once and never holds a sub. It needs a focuser that reports its temperature. Measure the coefficient on your own telescope before you use it.
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
enable_at_start— set the setpoint and turn the cooler on before the first capture.setpoint_c— override[cooling].default_setpoint_c.wait_for_settle(default true) — wait for the camera to reach setpoint. If true and cooling fails, the run is ABORTED; if false, the run proceeds without waiting.warm_up_at_end— run the cooler warm-up ramp at the end (best-effort, never changes the outcome).
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:
inherit(the editor default; the same as nomeridianblock, and as the legacyignore) - the mount setting decides.off- never act at the meridian in this plan, even when the mount is armed.halt/flip- this plan's choice OVERRIDES the mount setting.[mount].flip_mode = "off"is not a master switch: a plan set toflipwill flip. When a plan widens the mount setting (planflipover mountoff) the run logs a WARNING, journals onemeridian.overrideevent, and the run monitor shows a banner for the whole run. Set the plan toinheritif the mount should decide. Withinheritthe clamps below come from[mount].max_minutes_past— only act once the target is this many minutes past the meridian.pause_before_min— hold exposures for this window BEFORE the meridian so a sub can't straddle the flip, then wait for the target to cross and reach the action point.recenter_after_flip— plate-solve / sync / re-slew after the flip.
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):
- Each target auto-starts guiding once centred (waits for settle) and stops it after that target's exposures, so the next slew isn't fighting the guider.
- Auto-dither fires between subs on the
dither_everycadence (dither_px, optionaldither_ra_only), using the plan's settle gate (settle_px,settle_time_s,settle_timeout_s). The cadence counter is sequence-wide and resets per target, so it works for single-sub events and interleaved LRGB rotation alike and never wastes a dither after the last sub. - Guiding enforcement — a plan that requires guiding will NOT start a sub while PHD2 reports a non-Guiding state (looping / stopped / star-lost). It holds for up to 60 s for PHD2 to recover by itself (
[guiding_watchdog] hold_timeout_s; with the watchdog enabled itsrecover_timeout_s, default 120 s, is used instead). If guiding has not come back it stops and restarts guiding with a fresh star, up to 3 times 30 s apart (reacquire_attempts,reacquire_wait_s), with a warning alert. If that fails too, the target is skipped and the run moves to the next target; it does not fail the run, and it won't quietly shoot unguided subs. A weather suspend or a due meridian flip takes priority over the re-acquire.
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:
- the guide RMS exceeded
[guiding_watchdog] rms_max_px(watchdog on only — the same tolerance it holds the next sub on); - one axis ran away: 3 or more guide pulses in a row that PHD2 clipped at its maximum duration (its
RALimited/DecLimited) — the guider could not keep up. This needs no tolerance: in rig 1's guide logs (~48,700 steps) such runs come only with faults (Dec runaways, an 18 px jump), normal guiding shows at most 2 in a row; - the guide star was lost, or guiding was not running, for at least half the exposure in one stretch (and at least 15 s — a short sub barely needs guiding). Frames PHD2 drops here and there (its "Star lost - low HFD" on a bright star) do not add up to a lost star; a cloud, a bump or a star gone from the search box is one long gap.
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):
min_star_count— too few detected stars (clouds, dew, a bump).max_hfr_px— soft focus / seeing blow-up.max_eccentricity— elongated stars (trailing, poor guiding), 0 = round … 1 = a line.max_background_adu— sky too bright (moon, light, an accidental short warm-up).
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:
- The frame is journaled as rejected (with the reason) and, when
move_rejectsis on, moved into a siblingrejected/folder so it leaves your light stack. - With
reshoot_max > 0, the sub is re-shot up to N times (a rejected re-shoot doesn't count toward the plan's frame count). - With
abort_after_consecutive > 0, N rejects in a row fail the exposure step (the sky has gone) so its on_error decides.
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.
- Pause — takes effect between subs (v23). The exposure in flight completes (photons aren't wasted), then the run enters PAUSED, runs on_suspend, and blocks until resume. Resume runs on_resume, unparks a mount the pause left parked, and carries on with the subs the step still owes. Before v23 a pause waited for the whole expose step, so inside a block of 15 subs it could stay pending for many minutes.
- Stop — requests abort: sets the stop flag, unblocks a pause, and calls
Console.halt_all()to stand the equipment down (idempotent). In-flight captures/slews/AF are cancelled via their cancel hooks. on_end still runs so the rig is parked/warmed. - Start with a Windows restart pending — a stand-alone plan with an end time or a dawn gate is refused while Windows has a restart pending, until you confirm (v23). See the Windows restarts and crashes topic.
- Only one run at a time;
start()raises if a run is already alive.injected = truemarks a blockscript-supervised run (obs actions skipped). When a blockscript's ownrun_sequenceaction launches the plan and it SUCCEEDS, the sequencer signalsbody_done, moving the blockscript RUNNING → SHUTDOWN so the night packs up. A scheduler CHUNK runs injected too but does NOT signal body_done, so a many-chunk night isn't ended after the first chunk.
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):
abort(default) — failure runs the on_error phase and FAILS the run.skip— log it and continue to the next step.retrywithretry_count— retry up to N times (with a short backoff), then skip.
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
- An
autofocusaction that fails in a phase (on_start included) no longer ends the plan when the failed sweep itself measured a good focus at the current position (compared with the in-focus HFR the Adaptive First Light wizard recorded), or when the sweep still saw stars and a refocus found focus at this position within the last hour: the position is kept, the journal says WARNING and an alert goes out. Without that evidence — no stars, a blurred field, no wizard reference — the action fails as before. An explicit on-fail policy on the action still decides for itself. repeat.countmust be a literal number at compile time; variable references there are rejected.- Altitude/HA constraints rely on the mount exposing live properties (altitude, sidereal_time, RA). No mount, no enforcement — the check is skipped, not failed.
- A meridian
flipthat can't confirm the pier side changed STOPS the run for safety rather than continuing blind. - Guiding/dither only act when PHD2 control is explicitly enabled; otherwise start/stop/dither are honest no-ops. A guiding-enabled stand-alone run refuses to start if PHD2 isn't connected.
- Per-frame acceptance and the guiding watchdog are off by default; turn them on in config. Acceptance grades light frames only and fails open (keeps the frame) on any grading error.
- Resume is refused if the plan was edited after the interrupted run, and only stand-alone runs checkpoint (blockscript/scheduler runs don't).
on_suspendis fully authorable from the editor's On Suspend tab (fixed in v20.89 — earlier builds silently dropped what you authored there; re-save any plan that relied on a hand-added TOML list).
How it ties in
- Console is the single command surface the executor drives (mount, camera, filter wheel, focuser, roof, power, plate-solve, autofocus) — see the Console topic.
- Plans documents the on-disk TOML format and the hidden policy step.
- Autofocus covers First Light (once, at set-up) and Refocus (every time after), and the
focus_recipe.jsonsidecar with the refocus formula that the focus triggers use. - Blockscript runs can host a sequence as an injected run; the obs/img domain split keeps the two from fighting over the observatory.
- The Safety supervisor backs the
wait_for_safegate and thesafewait_until mode.