Add persistent global runtime overrides without changing the default runtime #40

Problem

pboss --runtime should allow the runtime to be overridden at execution time without changing the default runtime configured in .runtime.

The important distinction is that this is a global PBoss runtime override, not the same thing as the app-level runtime setting.

A runtime override supplied from the CLI must also be persistent for the process/ecosystem it was used to start. If that process is restarted, reloaded, or PBoss itself reboots, it must continue using the overridden runtime.

Expected behavior

When PBoss is started with a runtime override:

pboss start --runtime=bun ./script.ts

the process must permanently remember that bun was explicitly selected.

Subsequent operations such as:

pboss restart <process>
pboss restart <config>

must continue using:

bun

even if .runtime contains a different runtime.

The override must also survive:

• PBoss restarts
• machine/server reboots
• process restarts
• ecosystem/config restarts
• reloads

The override should not modify the existing .runtime default.

Runtime precedence

The effective runtime should be resolved in this order:

1. runtime_overrides
2. .runtime
3. normal runtime detection/fallback

runtime_overrides contains the runtime explicitly selected for a process or ecosystem.

For example:

.runtime
  → node

runtime_overrides
  → my-api: bun

Running my-api should always use Bun, while every process without an override continues to use Node.

Important: do not mutate .runtime

Running:

pboss start --runtime=bun ./script.ts

must not change:

.runtime

from:

node

to:

bun

The --runtime flag is an override, not a change to the default runtime.

Changing the default runtime remains the responsibility of:

pboss runtime change

or the appropriate runtime-management command/function.

CLI processes

A per-process runtime override is only created when the process is explicitly started from the CLI with --runtime:

pboss start --runtime=bun ./script.ts

That process gets a persistent runtime override.

A normal CLI start without --runtime:

pboss start ./script.ts

does not create an override and should use the default runtime from .runtime.

Ecosystem/config files

For an ecosystem/config file, the runtime override applies to the entire ecosystem/config, and all processes inside it.

For example:

pboss start --runtime=deno ecosystem.config.ts

means every process belonging to that ecosystem runs with Deno.

The ecosystem should remember that override and continue using Deno for:

pboss restart ecosystem.config.ts

even after a reboot.

If the ecosystem was started without --runtime, all processes in that ecosystem use the configured/default runtime according to the normal runtime resolution rules.

Launcher/runtime resolution

There is an additional requirement because the shell/PowerShell launcher must determine the runtime before it invokes the PBoss JavaScript entry point.

The launcher should therefore load the saved runtime override information first.

Conceptually:

shell/powershell launcher
        │
        ├── read runtime_overrides
        │
        ├── if override exists
        │      → use override
        │
        └── otherwise
               → read .runtime
                  → use default runtime

This is important because the launcher cannot wait for the PBoss JS code to decide the runtime; the runtime must already be known when the JS entry point is launched.

Empty or missing .runtime

--runtime should still work when .runtime is missing or empty.

In that case, the explicitly supplied --runtime value is used for the invocation and saved as the persistent override where applicable.

However, an existing .runtime file must not be overwritten or changed merely because --runtime was supplied.

Examples

Default runtime

.runtime = node

pboss start ./api.js

→ uses Node.

Temporary/persistent process override

pboss start --runtime=bun ./api.js

→ process uses Bun.

.runtime remains:

node

After:

pboss restart api

→ still uses Bun.

After a server reboot:

→ still uses Bun.

Ecosystem override

.runtime = node

pboss start --runtime=deno ecosystem.config.ts

→ every process in that ecosystem uses Deno.

Restarting the ecosystem:

pboss restart ecosystem.config.ts

→ still uses Deno.

Other ecosystems/processes without an override continue using the default Node runtime.

Scope

This should be treated as a global PBoss runtime override mechanism.

It is separate from the existing app-level runtime setting, which has more limited scope/features.

The global override is intended specifically for selecting the runtime used by PBoss-managed processes/ecosystems while preserving the system-wide default runtime.

Acceptance criteria

• pboss start --runtime=<runtime> <process> stores a persistent runtime override for that process.
• pboss start --runtime=<runtime> <ecosystem/config> stores a persistent override for that ecosystem.
• A saved override is reused for restart/reload/reboot.
• --runtime never changes an existing .runtime default.
• Missing/empty .runtime does not prevent --runtime from working.
• Processes/configs without an override continue using .runtime.
• Shell and PowerShell launchers resolve runtime_overrides before .runtime.
• Ecosystem-level overrides apply consistently to all processes in that ecosystem.
• pboss runtime change remains the mechanism for changing the default runtime.
• The global runtime override mechanism remains distinct from the app-level runtime setting.