Session lifecycle

Documentation for version v0.1.0-beta.3View source on GitHub

This page describes how an OmsiLaunch session moves through SessionState from Created to Completed or Failed: which component sets each state, which plugin telemetry events drive the transitions, how the startup timeout works, what stopping means (forced termination), what WaitForAsync returns, which states are terminal, which states are never or barely observable, and which guarantees the CLI owner gives. Everything here is taken from OmsiLaunchService.StartAsync, SuperviseAsync and ApplyTelemetry (src/OmsiLaunch.Core/OmsiLaunchService.cs), PluginRuntime (src/OmsiLaunch.Plugin/PluginRuntime.cs) and OwnerSession (tools/OmsiLaunch.Cli/Program.cs).

Related pages: public API, error codes, transactions and recovery, permanent plugin, runtime control, local control plane, Windows tray, CLI reference, runtime validation status, the .omsilaunch directory.

Overview#

PlanSessionAsync                       (no state; returns a SessionPlan)
StartSessionAsync ─ caller thread ─────────────────────────────────────────────
  Created
  AcquiringInstallationLock            lease Local\OmsiLaunch.Installation.<hash>
  RecoveringPreviousTransaction        stale journal restored before anything is read
  Snapshotting → ApplyingConfiguration journal Prepared, overlays written, deletions removed, Applied
  DeployingRuntime                     journal RuntimeDeployed (plugin is permanent; nothing copied)
  CreatingStartupHandoff               handoff, telemetry slot, runtime mailbox; journal HandoffCreated
  StartingProcess                      CreateProcessW Omsi.exe
  WaitingForPlugin                     journal ProcessStarted (PID, creation time, exe path) → handle returned
SuperviseAsync ─ background task ──────────────────────────────────────────────
  PluginBootstrap                      telemetry plugin.started
  StartingWorld                        telemetry world.starting (NEW_MAP only)
  Running                              telemetry gameplay.entered
  ProcessExited                        OMSI exited or was terminated; journal ProcessExited
  Restoring                            exact restore of every session-owned file
  CleaningRuntime                      restore verified; journal removed; backups removed
  Completed                            stores disposed, lease released
  Failed                               from any point above; restore still runs

SessionState reference#

Values in declaration order. "Set by" names the code that calls Move/Fail; "Observable" says whether GetStatusAsync/WaitForAsync can see it in practice.

Terminal states: Completed and Failed. After either, WaitForAsync returns immediately and CloseAsync returns without requesting a stop.

Verification of "never set": a search of the code base for SessionState.ValidatingPlatform, SessionState.Planning and SessionState.EnteringGameplay finds only the enum declaration; SessionState.Snapshotting appears once, immediately followed by Move(SessionState.ApplyingConfiguration).

Start phase (StartSessionAsync)#

1. Reject a non-runnable plan (OL_E_PLAN_NOT_RUNNABLE), re-plan the spec (re-hashing Omsi.exe, re-resolving content, re-checking the plugin closure) and reject again if it is no longer runnable. Register the live session (Created).
2. Create the host trace <root>\.omsilaunch\diagnostics\<sessionId>-host.log (older session-prefixed files beyond the 50 newest sessions are pruned). Reject StartupTimeoutSeconds outside 1..600 (ArgumentOutOfRangeException; the session is unregistered).
3. AcquiringInstallationLock → lease. RecoveringPreviousTransaction → recover a pending journal (a pre-fingerprint journal that cannot prove ownership is deferred and retried once this session's overlays exist), validate the permanent plugin closure, hash the executable, remove a stale closecheck, build the transaction (overlays: options.cfg patches, managed splash BMPs, Texture\standard.itx; deletions: ITX targets, Texture\standard.ipr, closecheck when it does not exist).
4. Snapshotting → ApplyingConfiguration → DeployingRuntime → CreatingStartupHandoff → StartingProcess → WaitingForPlugin, then the supervisor task starts and the handle is returned.
5. Any exception in steps 3–4 is caught: the session is Failed with OL_E_START_SESSION (inner message), a created process is terminated and awaited, stores are disposed, the transaction is restored (OL_E_RESTORE_FAILED on failure) or, if OMSI's exit could not be confirmed, left pending with OL_E_RESTORE_DEFERRED; the lease is released. StartSessionAsync still returns the handle in this case; read GetStatusAsync.

The re-plan keeps the caller's SessionId, so the id in the handle equals plan.SessionId.

Supervision (SuperviseAsync)#

The supervisor runs on a thread-pool task and loops every 100 ms until OMSI has exited or a stop was requested:

1. Read the latest telemetry sample (a latest-value slot with a producer sequence; torn samples are skipped; identical consecutive events are distinct because the sequence differs). Every new sample is appended to RuntimeEvents and mapped by ApplyTelemetry.
2. If the session is Failed, leave the loop.
3. If the session is not yet Running and the deadline (StartupTimeoutSeconds after supervisor entry) has passed: Fail with OL_E_STARTUP_TIMEOUT when PluginBootstrap was reached, otherwise OL_E_PLUGIN_NOT_LOADED; leave the loop.

After the loop: if OMSI exited before Running and no failure was recorded, Fail with OL_E_PROCESS_EXITED_EARLY. Then, whether or not the session failed: terminate OMSI if it is still alive, wait for exit, mark the journal ProcessExited, move to ProcessExited, restore (Restoring → CleaningRuntime) or record OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED, dispose the process handle, handoff, telemetry slot and runtime mailbox, release the lease, and move to Completed unless the state is Failed. A fault inside the supervisor itself is recorded as OL_E_PROCESS_SUPERVISION (cleanup problems as OL_E_PROCESS_CLEANUP_FAILED) and the same termination/restore path runs.

Because Failed is sticky, the only evidence that a failed session was restored is the absence of OL_E_RESTORE_FAILED/OL_E_RESTORE_DEFERRED in its diagnostics (and the absence of journal.json); restore notes (restore.session-artifact-removed, OL_W_RESTORE_FOREIGN_FILE_RETAINED) appear in either case.

Telemetry events#

The plugin publishes JSON { "name": ..., "data": {...} } samples into the telemetry slot; the host records each new sample as a RuntimeEvent(Type = name, TimestampUtc = host receipt time, Sequence, Data).

Caveats: the slot holds one sample, so events emitted within one 100 ms host poll can be lost (the plugin suppresses lifecycle events for 2 s after gameplay.entered and never publishes a D3D event in the tick that publishes gameplay.entered, so the Running boundary is not missed). RuntimeEvents keeps the 256 most recent events; older ones are dropped. It is not a lossless log. Read events through GetStatusAsync, session.events on the control plane, or events read|watch on the CLI.

Startup timeout#

ShutdownTimeoutSeconds is carried in the spec but not consumed: there is no shutdown wait.

Stop semantics#

Every stop request is the same canonical request: StopAsync(handle) from the API, CloseAsync on a non-terminal session, session.stop on the local control plane (bound to the active session id), "End session" in the tray, Ctrl+C or console close in the CLI owner, and the end of /observe-seconds.

WaitForAsync semantics#

The poll interval is 100 ms, so observed transitions lag the real ones by up to 100 ms.

Owner lifecycle guarantees (CLI)#

OwnerSession.RunAsync in tools/OmsiLaunch.Cli/Program.cs is the reference owner.

Integrators writing their own owner must reproduce the first two guarantees: one StartSessionAsync per installation at a time, and CloseAsync on every path.

Failure map#

Every failure path still attempts termination and restore; a journal that remains is recovered on the next start or by RecoverPendingAsync / /recover (transactions and recovery).