Integrate the real Olympus application

Overview · Architecture · Service contract · Build and release

This page is a contract for the team maintaining the real Olympus application, in its separate solution. The launcher and MSI implement their side. That does not prove Olympus already implements its side. samples/DummyOlympus demonstrates IPC behavior only; it is not the production application.

Required: set the process taskbar identity

The exact permanent identity is:

EPS.Olympus

The real Olympus process must call SetCurrentProcessExplicitAppUserModelID("EPS.Olympus") before it creates any Windows UI. Set it at the start of the application's entry point, before forms, splash windows, shell/recent-document integration, or a custom per-window taskbar identity is created. See Microsoft's AppUserModelID guidance.

The launcher sets its own process identity before configuring WinForms. The installer sets the same ID on the stable Start menu shortcut. The launcher's process identity is not automatically assigned to the child Olympus process. The OLYMPUS_APP_USER_MODEL_ID environment variable is integration metadata; receiving it does not set Windows properties.

Keep the ID identical across x64/ARM64 and application/bootstrap versions. Do not rename it to match new display branding or append a version number. The displayed publisher is CODE Group; the EPS.Olympus string remains a compatibility identifier for taskbar association.

C# example, including .NET Framework 4.8

Put this ordinary helper class in its own main code file. Call it as the first action in the existing application startup path. It uses APIs available to legacy Framework applications and does not require handwritten partial classes.

using System.Runtime.InteropServices;

internal static class OlympusShellIdentity
{
    internal const string AppUserModelId = "EPS.Olympus";

    internal static void Initialize()
    {
        Marshal.ThrowExceptionForHR(
            SetCurrentProcessExplicitAppUserModelID(AppUserModelId));
    }

    [DllImport("shell32.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
    private static extern int SetCurrentProcessExplicitAppUserModelID(string appId);
}

For an existing WinForms Main, the relevant order is:

// First action in Main, before any forms or Windows shell interaction:
OlympusShellIdentity.Initialize();

// Then the application's existing WinForms initialization and Application.Run(...).

For WPF, call the helper in the earliest application startup path before creating windows. Keep the existing application/generated startup arrangement; do not add a second entry point or an unrelated handwritten partial class just for this helper.

VB.NET example for a legacy application

Imports System.Runtime.InteropServices

Friend Module OlympusShellIdentity
    Friend Const AppUserModelId As String = "EPS.Olympus"

    <DllImport("shell32.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
    Private Function SetCurrentProcessExplicitAppUserModelID(appId As String) As Integer
    End Function

    Friend Sub Initialize()
        Marshal.ThrowExceptionForHR(SetCurrentProcessExplicitAppUserModelID(AppUserModelId))
    End Sub
End Module

Call OlympusShellIdentity.Initialize() at the beginning of the existing application startup handler/entry point, before any application-owned splash or main form is created. With the VB Application Framework, review the automatic splash-screen startup sequence; setting it after an automatic splash has appeared is too late.

Stable relaunch and pinning

The installed shortcut targets:

%LocalAppData%\Olympus\Launcher\Olympus.Launcher.exe

Shortcuts, file/protocol associations, user-facing restart commands, and any relaunch metadata must use this stable launcher rather than Versions\<version>\Olympus.exe. Otherwise a pin can bypass update selection and fail after changes to version directories.

If Olympus explicitly supplies window taskbar/relaunch properties, use its window property store to set:

These optional window properties need deliberate application implementation. Do not set only the command: Windows requires the matching display-name resource for that relaunch information. See Microsoft's relaunch command documentation. The process ID plus installed shortcut does not by itself prove every pin-from-running-window scenario uses the stable target.

Test both pinning the installed shortcut and pinning the running application. Existing pins to old versioned EXEs may need to be removed and recreated through a documented support procedure; the launcher does not rewrite users' pins.

Required: consume the launch environment

Treat these as local integration values, not authentication or proof of a trusted caller. Validate inputs according to the application's security model. Direct development launches may not supply them; define explicit development defaults, and never silently redirect production data into a version directory.

The process working directory is the selected version directory. Read-only resources can be resolved there. Mutable preferences, caches, databases, and documents must use the agreed data location or other application-owned user storage. Launch-time verification rejects extra or changed files in Versions, so writing logs or settings beside Olympus.exe can make the next launch fail integrity checks.

Required for forwarding and update UI: own the pipe

The application primary owns one local, asynchronous byte-mode pipe per interactive user/session:

CODE.Olympus.v1.<user-SID-with-hyphens-replaced-by-underscores>.<session-id>

Prefer the exact OLYMPUS_DEPLOYMENT_PIPE value supplied by the launcher. The pipe is not scoped to a development root. Use a current-user-only ACL/PipeOptions.CurrentUserOnly where available and reject remote clients. This is same-user coordination, not protection against malicious same-user processes.

Wire framing

1. Read exactly four bytes, interpreted as a little-endian signed 32-bit payload length.
2. Reject lengths outside 1–65,536 bytes.
3. Read exactly that many bytes of UTF-8 JSON; there is no newline delimiter or terminator.
4. Validate protocolVersion, message type, correlation ID, and payload.
5. Send a framed acknowledgement promptly. The entire client connect/write/read budget is two seconds; queue UI/save operations rather than waiting for them before acknowledging.

The Core Ipc helpers implement framing for compatible targets. Framework 4.8 applications can implement the same protocol without referencing the .NET 10 Core assembly.

Forward an application launch

{
  "protocolVersion": 1,
  "type": "launch",
  "requestId": "example-launch-001",
  "arguments": ["olympus://document/42", "argument with spaces"]
}

{
  "protocolVersion": 1,
  "type": "ack",
  "requestId": "example-launch-001",
  "accepted": true
}

An accepted acknowledgement means the request is queued for handling, not that the document is loaded or the window is foreground. Olympus owns argument/URL validation, UI dispatch, and foreground behavior. Retain request IDs briefly to avoid duplicate handling. Reject unknown protocols/types or invalid input with an appropriate refusal; an optional error string can explain a declined request.

Without a working listener, the launcher detects managed running Olympus processes and avoids starting another instance. It cannot reliably forward arguments or activate the existing UI. If arguments were supplied, it reports that they could not be accepted; this is an integration failure, not an excuse to open duplicate application instances.

Receive an update notification

{
  "protocolVersion": 1,
  "type": "updateReady",
  "requestId": "example-update-001",
  "version": "2026.10.5",
  "policy": "critical",
  "deadlineUtc": "2026-10-25T00:00:00Z"
}

Use the same acknowledgement envelope, echoing this request ID. accepted acknowledges receipt, not a completed restart and not permission to terminate the application.

The agent sends notifications to sessions with managed Olympus processes. It does not listen for an application restart command and does not kill Olympus at a deadline. Without IPC, notifications remain in deployment logs and the update waits for a later launch; no implemented agent tray UI replaces the missing application flow.

Restart safely

1. Acknowledge and queue the update request promptly.
2. Let the user save or defer. Complete application-owned work and migrations under the application's rules.
3. Close all Olympus windows and end the old primary process.
4. Invoke the stable launcher after the primary has ended, for example through an application-owned short-lived restart helper. Starting the launcher too early can forward straight back to the still-running old instance.
5. Let the launcher verify/select the pending version. Do not open the versioned EXE directly or edit deployment state to force selection.

Activation also waits for managed Olympus processes in other sessions. The current agent/launcher do not automate a complete save/exit/relaunch workflow. DummyOlympus exits for required/critical notifications and relies on a later launcher invocation; it does not demonstrate a finished user-facing restart design.

Data compatibility and readiness

dataCompatibilityId is an application data-format epoch. Automatic activation and rollback refuse to cross epochs. Coordinate a migration/recovery design before changing it; shipping a new string is not a migration implementation.

Current startup readiness is main-window visibility, with a ten-second legacy fallback for processes that remain windowless. There is no separate application-ready/healthy IPC message. Keep this limitation in mind when validating initialization failures; a late crash does not automatically mark the application release failed or reopen the splash.

Acceptance checklist for the application team

• Set the ID before any UI and verify one taskbar grouping with the installed shortcut.
• Pin the shortcut, close/reopen, update Olympus, and confirm the pin still starts the stable launcher.
• Pin from a running Olympus window and inspect relaunch behavior after an application update.
• Handle olympus:// and space-containing arguments on both initial process launch and forwarded requests.
• Store all mutable data outside Versions; confirm opening/saving does not invalidate the receipt.
• Verify two-second acknowledgements while the UI is busy and duplicate request handling is suppressed.
• Exercise normal, required, critical, declined/deferred, and repeated notifications with unsaved work.
• Verify restart timing when more than one window/session is open.
• Test missing environment values in an explicitly supported development startup path.

Track the real application's completion/revision independently from this repository. Documenting these requirements does not certify that they are implemented in every existing Olympus build.