@theia/core 1.76.0-next.6 → 1.76.0

package/src/common/index.ts

@@ -24,6 +24,7 @@ export * from './core-preferences';
 export * from './disposable';
 export * from './event';
 export * from './inversify-utils';
+export * from './launch-arguments';
 export * from './listener';
 export * from './logger';
 export * from './logger-sanitizer';
@@ -44,6 +45,7 @@ export * from './progress-service';
 export * from './progress-service-protocol';
 export * from './quick-pick-service';
 export * from './reference';
+export * from './remote-cli-args-contribution';
 export * from './resource';
 export * from './selection';
 export * from './selection-service';

package/src/common/launch-arguments.ts

@@ -0,0 +1,61 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+/**
+ * The CLI options of a launch, already parsed. A window opened for a *forwarded* launch (see the
+ * `second-instance` handling in `ElectronMainApplication`) receives this rather than a raw `argv`:
+ * the command line is parsed once, in the Electron main process, so that no consumer has to
+ * re-implement the argument grammar and the frontend never sees an unparsed command line.
+ *
+ * @experimental
+ */
+export interface LaunchArguments {
+
+    /**
+     * The values of each (possibly repeated) `--name value` / `--name=value` option, in the order
+     * they appeared on the command line.
+     */
+    readonly values: Readonly<Record<string, readonly string[]>>;
+
+    /** The options that were explicitly negated, i.e. `--no-name` or `--name=false`. */
+    readonly negated: readonly string[];
+}
+
+/** @experimental */
+export namespace LaunchArguments {
+
+    /** A launch that carried no options. */
+    export const EMPTY: LaunchArguments = { values: {}, negated: [] };
+
+    /** Every value of a (possibly repeated) option, or an empty array when the option is absent. */
+    export function values(args: LaunchArguments, name: string): readonly string[] {
+        return args.values[name] ?? [];
+    }
+
+    /**
+     * The last value of an option, or `undefined` when the option is absent. Last wins, so that a
+     * repeated option behaves like it does on a normal command line.
+     */
+    export function lastValue(args: LaunchArguments, name: string): string | undefined {
+        const all = values(args, name);
+        return all.length > 0 ? all[all.length - 1] : undefined;
+    }
+
+    /** Whether a boolean option was explicitly disabled, i.e. `--no-name` or `--name=false`. */
+    export function isNegated(args: LaunchArguments, name: string): boolean {
+        return args.negated.includes(name);
+    }
+}

package/src/common/remote-cli-args-contribution.ts

@@ -0,0 +1,39 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { MaybePromise } from './types';
+
+export const RemoteCliArgsContribution = Symbol('RemoteCliArgsContribution');
+
+/**
+ * Frontend contribution that provides additional CLI arguments to pass to a remote backend
+ * started for the *current* window (e.g. when attaching to a dev container).
+ *
+ * This lets per-window CLI options (such as `--session-preference`) that were forwarded to a
+ * window be re-applied on the remote backend. Unlike the node-side `RemoteCliContribution#enhanceArgs`,
+ * which reads process-global state on the shared backend, this contribution runs in the renderer and
+ * therefore has access to the current window's context.
+ *
+ * @experimental
+ */
+export interface RemoteCliArgsContribution {
+    /**
+     * Returns the extra CLI arguments to append when starting a remote backend for the current
+     * window. Implementations should return an empty array when they have nothing to contribute
+     * (e.g. for a regular cold-start window whose args are already applied by the shared backend).
+     */
+    getRemoteCliArgs(): MaybePromise<string[]>;
+}

package/src/electron-browser/messaging/electron-ipc-connection-source.ts

@@ -15,12 +15,15 @@
 // *****************************************************************************
 
 import { injectable, interfaces } from 'inversify';
-import { RpcProxy } from '../../common/messaging';
-import { AbstractChannel, Channel, Emitter, Event, MaybePromise, WriteBuffer } from '../../common';
+import { RpcProxy } from '../../common/messaging/proxy-factory';
+import { AbstractChannel, Channel } from '../../common/message-rpc/channel';
+import { WriteBuffer } from '../../common/message-rpc/message-buffer';
+import { Emitter, Event } from '../../common/event';
+import { MaybePromise } from '../../common/types';
 import { Uint8ArrayReadBuffer, Uint8ArrayWriteBuffer } from '../../common/message-rpc/uint8-array-message-buffer';
 import { ServiceConnectionProvider } from '../../browser/messaging/service-connection-provider';
 import { ConnectionSource } from '../../browser/messaging/connection-source';
-import { FrontendApplicationContribution } from '../../browser';
+import { FrontendApplicationContribution } from '../../browser/frontend-application-contribution';
 
 export interface ElectronIpcOptions {
 }

package/src/electron-browser/preload.ts

@@ -269,7 +269,9 @@ export function preload(): void {
             }
         }
     });
-    api.WindowMetadata.webcontentId = ipcRenderer.sendSync(CHANNEL_WC_METADATA);
+    // Synchronous, so the metadata (including the parsed options of a forwarded launch) is in place
+    // before any frontend code runs.
+    api.WindowMetadata = ipcRenderer.sendSync(CHANNEL_WC_METADATA);
 
     contextBridge.exposeInMainWorld('electronTheiaCore', api);
 }

package/src/electron-browser/window/electron-window-launch-args.spec.ts

@@ -0,0 +1,45 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { expect } from 'chai';
+import { LaunchArguments } from '../../common/launch-arguments';
+import { ElectronWindowLaunchArgs } from './electron-window-launch-args';
+
+class TestElectronWindowLaunchArgs extends ElectronWindowLaunchArgs {
+    constructor(protected readonly metadata: { webcontentId: string, launchArgs?: LaunchArguments }) {
+        super();
+    }
+
+    override getLaunchArgs(): LaunchArguments | undefined {
+        return this.metadata.launchArgs;
+    }
+}
+
+describe('ElectronWindowLaunchArgs', () => {
+
+    it('returns undefined for a cold-start window (main attached no options)', () => {
+        const service = new TestElectronWindowLaunchArgs({ webcontentId: '1' });
+        expect(service.getLaunchArgs()).to.equal(undefined);
+    });
+
+    it('returns the options attached to the window metadata', () => {
+        const launchArgs: LaunchArguments = { values: { 'attach-container': ['B'], 'session-preference': ['foo=1'] }, negated: [] };
+        const service = new TestElectronWindowLaunchArgs({ webcontentId: '1', launchArgs });
+        const args = service.getLaunchArgs()!;
+        expect(LaunchArguments.lastValue(args, 'attach-container')).to.equal('B');
+        expect(LaunchArguments.values(args, 'session-preference')).to.deep.equal(['foo=1']);
+    });
+});

package/src/electron-browser/window/electron-window-launch-args.ts

@@ -0,0 +1,38 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { injectable } from 'inversify';
+import { LaunchArguments } from '../../common/launch-arguments';
+import { WindowLaunchArgs } from '../../browser/window/window-launch-args';
+
+/**
+ * Electron implementation of {@link WindowLaunchArgs}. Reads the options the main process attached
+ * to this window's metadata, which the preload script fetches synchronously before any frontend code
+ * runs, and which main keys by the IPC sender rather than by any value from the URL (see
+ * `LaunchArgsStore`).
+ *
+ * @experimental
+ */
+@injectable()
+export class ElectronWindowLaunchArgs implements WindowLaunchArgs {
+
+    getLaunchArgs(): LaunchArguments | undefined {
+        // `undefined` for a cold-start window, letting callers fall back to the shared backend, and
+        // the stored options for a forwarded window (kept for as long as the window shows the
+        // frontend the launch opened, so a plain reload still sees them).
+        return window.electronTheiaCore.WindowMetadata.launchArgs;
+    }
+}

package/src/electron-browser/window/electron-window-module.ts

@@ -33,6 +33,8 @@ import { ElectronUriHandlerContribution } from '../electron-uri-handler';
 import { bindRootContributionProvider } from '../../common';
 import { WindowTitleContribution } from '../../browser/window/window-title-service';
 import { WindowFocusService } from '../../browser/window/window-focus-service';
+import { WindowLaunchArgs } from '../../browser/window/window-launch-args';
+import { ElectronWindowLaunchArgs } from './electron-window-launch-args';
 import { WindowZoomStatusBarItem } from './window-zoom-status-bar-item';
 import '../../../src/electron-browser/style/window-zoom-action-bar.css';
 
@@ -47,6 +49,11 @@ export default new ContainerModule((bind, unbind, isBound, rebind) => {
     bind(FrontendApplicationContribution).toService(ElectronUriHandlerContribution);
     bind(ClipboardService).to(ElectronClipboardService).inSingletonScope();
     rebind(FrontendApplicationStateService).to(ElectronFrontendApplicationStateService).inSingletonScope();
+    // `browser-window-module` (which binds `WindowLaunchArgs`) is not loaded in Electron, since the
+    // `window` extension provides `electron-window-module` as its `frontendElectron` replacement.
+    // Bind here directly, mirroring how `WindowService` is bound in each of the two modules.
+    bind(ElectronWindowLaunchArgs).toSelf().inSingletonScope();
+    bind(WindowLaunchArgs).toService(ElectronWindowLaunchArgs);
     bind(SecondaryWindowService).to(ElectronSecondaryWindowService).inSingletonScope();
     bind(ExternalAppOpenHandler).toSelf().inSingletonScope();
     bind(OpenHandler).toService(ExternalAppOpenHandler);

package/src/electron-common/electron-api.ts

@@ -18,6 +18,7 @@ import { NativeKeyboardLayout } from '../common/keyboard/keyboard-layout-provide
 import { Disposable } from '../common';
 import { FrontendApplicationState, StopReason } from '../common/frontend-application-state';
 import { ThemeMode } from '../common/theme';
+import { LaunchArguments } from '../common/launch-arguments';
 
 export type MenuRole = ('undo' | 'redo' | 'cut' | 'copy' | 'paste' | 'selectAll' | 'about' | 'services' | 'hide' | 'hideOthers' | 'unhide' | 'quit');
 
@@ -44,6 +45,15 @@ export type WindowEvent = 'maximize' | 'unmaximize' | 'focus';
 export interface TheiaCoreAPI {
     WindowMetadata: {
         webcontentId: string;
+        /**
+         * The parsed CLI options of a *forwarded* launch (see the `second-instance` handling in
+         * `ElectronMainApplication`), or `undefined` for a cold-start window. Provided synchronously
+         * by the preload script, so a frontend contribution can act on it from the first paint.
+         * The options never ride on the window URL; see `LaunchArgsStore` for the rationale.
+         *
+         * @experimental
+         */
+        launchArgs?: LaunchArguments;
     }
     getSecurityToken: () => string;
     attachSecurityToken: (endpoint: string) => Promise<void>;

package/src/electron-main/electron-api-main.ts

@@ -76,7 +76,13 @@ export class TheiaMainApi implements ElectronMainApplicationContribution {
 
     onStart(application: ElectronMainApplication): MaybePromise<void> {
         ipcMain.on(CHANNEL_WC_METADATA, event => {
-            event.returnValue = event.sender.id.toString();
+            // Answered synchronously, so the window has its metadata — including the parsed options
+            // of a forwarded launch — before any frontend code runs. The window is identified by the
+            // IPC sender, so it can only ever read its own.
+            event.returnValue = {
+                webcontentId: event.sender.id.toString(),
+                launchArgs: application.getLaunchArgs(event.sender.id)
+            };
         });
 
         // electron security token

package/src/electron-main/electron-main-application-module.ts

@@ -23,6 +23,7 @@ import { RpcConnectionHandler } from '../common/messaging/proxy-factory';
 import { ElectronSecurityToken } from '../electron-common/electron-token';
 import { ElectronMainWindowService, electronMainWindowServicePath } from '../electron-common/electron-main-window-service';
 import { ElectronMainApplication, ElectronMainApplicationContribution, ElectronMainProcessArgv } from './electron-main-application';
+import { LaunchArgsStore } from './launch-args-store';
 import { ElectronMainWindowServiceImpl } from './electron-main-window-service-impl';
 import { TheiaBrowserWindowOptions, TheiaElectronWindow, TheiaElectronWindowFactory, WindowApplicationConfig } from './theia-electron-window';
 import { TheiaMainApi } from './electron-api-main';
@@ -37,6 +38,7 @@ const electronSecurityToken: ElectronSecurityToken = { value: generateUuid() };
 
 export default new ContainerModule(bind => {
     bind(Stopwatch).toConstantValue(new SimpleStopwatch('electron main', () => performance.now()));
+    bind(LaunchArgsStore).toSelf().inSingletonScope();
     bind(ElectronMainApplication).toSelf().inSingletonScope();
     bind(ElectronMessagingContribution).toSelf().inSingletonScope();
     bind(ElectronMainApplicationContribution).toService(ElectronMessagingContribution);

package/src/electron-main/electron-main-application.ts

@@ -37,6 +37,9 @@ import { ElectronSecurityToken } from '../electron-common/electron-token';
 import Storage = require('electron-store');
 import { CancellationTokenSource, Disposable, DisposableCollection, Path, isOSX, isWindows } from '../common';
 import { DEFAULT_WINDOW_HASH, WindowSearchParams } from '../common/window';
+import { LaunchArguments } from '../common/launch-arguments';
+import { LaunchArgvParser } from './launch-argv-parser';
+import { LaunchArgsStore } from './launch-args-store';
 import { TheiaBrowserWindowOptions, TheiaElectronWindow, TheiaElectronWindowFactory } from './theia-electron-window';
 import { ElectronMainApplicationGlobals } from './electron-main-constants';
 import { createDisposableListener } from './event-utils';
@@ -69,6 +72,25 @@ export interface ElectronMainCommandOptions {
      * If the app is already running but user relaunches it, `secondInstance` is true.
      */
     readonly secondInstance: boolean;
+
+    /**
+     * The parsed CLI options of a forwarded launch. Set for `second-instance` launches so that
+     * per-window options (e.g. `--attach-container`, `--session-preference`) are carried to the
+     * newly created window rather than being dropped.
+     *
+     * @experimental
+     */
+    readonly launchArgs?: LaunchArguments;
+
+    /**
+     * Whether an {@link ElectronMainApplicationContribution} has *claimed* this launch via its
+     * `claimsWindow` hook (e.g. a `--attach-container` launch claimed by `@theia/dev-container`).
+     * When set, an empty window is opened instead of restoring the last workspace, since the window
+     * is about to be replaced by whatever the claiming contribution attaches to.
+     *
+     * @experimental
+     */
+    readonly claimed?: boolean;
 }
 
 /**
@@ -103,6 +125,17 @@ export interface ElectronMainApplicationContribution {
      * The application is stopping. Contributions must perform only synchronous operations.
      */
     onStop?(application: ElectronMainApplication): void;
+    /**
+     * Whether this contribution *claims* responsibility for a window opened for the given launch,
+     * e.g. a `--attach-container` launch claimed by `@theia/dev-container`. A claimed launch opens
+     * an empty window rather than restoring the last workspace, since the window is about to be
+     * replaced by whatever the claiming contribution attaches to. Core itself stays agnostic of the
+     * concrete CLI options. The frontend receives the same options (see `LaunchArgsStore`), so the
+     * corresponding frontend contribution can show a placeholder from the first paint.
+     *
+     * @experimental
+     */
+    claimsWindow?(args: LaunchArguments): MaybePromise<boolean>;
 }
 
 // Extracted and modified the functionality from `yargs@15.4.0-beta.0`.
@@ -177,6 +210,9 @@ export class ElectronMainApplication {
     @inject(Stopwatch)
     protected readonly stopwatch: Stopwatch;
 
+    @inject(LaunchArgsStore)
+    protected readonly launchArgsStore: LaunchArgsStore;
+
     protected isPortable = this.makePortable();
 
     protected readonly electronStore = new Storage<{
@@ -252,10 +288,12 @@ export class ElectronMainApplication {
                         () => this.startContributions());
                     startupMeasurement.info('Startup sequence completed');
 
+                    const launchArgs = LaunchArgvParser.parse(argv);
                     this.handleMainCommand({
                         file: args.file,
                         cwd: process.cwd(),
-                        secondInstance: false
+                        secondInstance: false,
+                        claimed: await this.isWindowClaimed(launchArgs)
                     });
                 },
             ).parse();
@@ -445,6 +483,7 @@ export class ElectronMainApplication {
                 this.activeWindowStack.splice(stackIndex, 1);
             }
             this.windows.delete(id);
+            this.launchArgsStore.delete(id);
         });
         electronWindow.window.on('maximize', () => TheiaRendererAPI.sendWindowEvent(electronWindow.window.webContents, 'maximize'));
         electronWindow.window.on('unmaximize', () => TheiaRendererAPI.sendWindowEvent(electronWindow.window.webContents, 'unmaximize'));
@@ -524,20 +563,35 @@ export class ElectronMainApplication {
         }
     }
 
-    async openDefaultWindow(params?: WindowSearchParams): Promise<BrowserWindow> {
+    async openDefaultWindow(params?: WindowSearchParams, launchArgs?: LaunchArguments): Promise<BrowserWindow> {
         const options = this.getDefaultTheiaWindowOptions();
         const [uri, electronWindow] = await Promise.all([this.createWindowUri(params), this.reuseOrCreateWindow(options)]);
+        this.stashLaunchArgs(electronWindow, launchArgs);
         electronWindow.loadURL(uri.withFragment(DEFAULT_WINDOW_HASH).toString(true));
         return electronWindow;
     }
 
-    protected async openWindowWithWorkspace(workspacePath: string): Promise<BrowserWindow> {
+    protected async openWindowWithWorkspace(workspacePath: string, launchArgs?: LaunchArguments): Promise<BrowserWindow> {
         const options = await this.getLastWindowOptions();
         const [uri, electronWindow] = await Promise.all([this.createWindowUri(), this.reuseOrCreateWindow(options)]);
+        this.stashLaunchArgs(electronWindow, launchArgs);
         electronWindow.loadURL(uri.withFragment(encodeURI(workspacePath)).toString(true));
         return electronWindow;
     }
 
+    /**
+     * Associates the parsed options of a forwarded launch with the target window before it loads its
+     * URL, so that the preload script cannot ask for them before they are stored. No-op for a
+     * cold-start launch, which carries none.
+     *
+     * @experimental
+     */
+    protected stashLaunchArgs(window: BrowserWindow, launchArgs?: LaunchArguments): void {
+        if (launchArgs) {
+            this.launchArgsStore.store(window.webContents.id, launchArgs);
+        }
+    }
+
     protected async reuseOrCreateWindow(asyncOptions: MaybePromise<TheiaBrowserWindowOptions>): Promise<BrowserWindow> {
         if (!this.initialWindow) {
             return this.createWindow(asyncOptions);
@@ -556,6 +610,14 @@ export class ElectronMainApplication {
     }
 
     protected async handleMainCommand(options: ElectronMainCommandOptions): Promise<void> {
+        // A claimed launch (e.g. a CLI attach) opens an empty window rather than restoring the last
+        // workspace: the local workbench would only be discarded when the window reloads into the
+        // claimed target, so loading a real workspace behind the placeholder wastes work and can
+        // trigger side effects.
+        if (options.claimed) {
+            await this.openDefaultWindow(undefined, options.launchArgs);
+            return;
+        }
         let workspacePath: string | undefined;
         if (options.file) {
             try {
@@ -565,14 +627,41 @@ export class ElectronMainApplication {
             }
         }
         if (workspacePath !== undefined) {
-            await this.openWindowWithWorkspace(workspacePath);
+            await this.openWindowWithWorkspace(workspacePath, options.launchArgs);
         } else {
             if (options.secondInstance === false) {
-                await this.openWindowWithWorkspace(''); // restore previous workspace.
+                await this.openWindowWithWorkspace('', options.launchArgs); // restore previous workspace.
             } else if (options.file === undefined) {
-                await this.openDefaultWindow();
+                await this.openDefaultWindow(undefined, options.launchArgs);
+            }
+        }
+    }
+
+    /**
+     * Returns the parsed launch options stored for the window with the given `webContents` id, or
+     * `undefined` for a cold-start window. Read from the per-window metadata channel, where the
+     * caller is identified by the IPC sender, so a window can only ever see its own options.
+     *
+     * @experimental
+     */
+    getLaunchArgs(windowId: number): LaunchArguments | undefined {
+        return this.launchArgsStore.get(windowId);
+    }
+
+    /**
+     * Whether any {@link ElectronMainApplicationContribution} claims responsibility for a window
+     * opened for the given launch (see its `claimsWindow` hook). Core stays agnostic of the concrete
+     * CLI options; e.g. `@theia/dev-container` claims `--attach-container` launches.
+     *
+     * @experimental
+     */
+    protected async isWindowClaimed(args: LaunchArguments): Promise<boolean> {
+        for (const contribution of this.contributions.getContributions()) {
+            if (await contribution.claimsWindow?.(args)) {
+                return true;
             }
         }
+        return false;
     }
 
     async openUrl(url: string): Promise<void> {
@@ -833,16 +922,20 @@ export class ElectronMainApplication {
         if (originalArgv.includes('--open-url')) {
             this.openUrl(originalArgv[originalArgv.length - 1]);
         } else {
-            createYargs(this.processArgv.getProcessArgvWithoutBin(originalArgv), cwd)
+            const argv = this.processArgv.getProcessArgvWithoutBin(originalArgv);
+            createYargs(argv, cwd)
                 .help(false)
                 .command('$0 [file]', false,
                     cmd => cmd
                         .positional('file', { type: 'string' }),
                     async args => {
+                        const launchArgs = LaunchArgvParser.parse(argv);
                         await this.handleMainCommand({
                             file: args.file,
                             cwd: cwd,
-                            secondInstance: true
+                            secondInstance: true,
+                            launchArgs,
+                            claimed: await this.isWindowClaimed(launchArgs)
                         });
                     },
                 ).parse();

package/src/electron-main/launch-args-store.spec.ts

@@ -0,0 +1,59 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { expect } from 'chai';
+import { LaunchArguments } from '../common/launch-arguments';
+import { LaunchArgsStore } from './launch-args-store';
+
+const args = (name: string, value: string): LaunchArguments => ({ values: { [name]: [value] }, negated: [] });
+
+describe('LaunchArgsStore', () => {
+
+    it('returns the stored argv for its window id', () => {
+        const store = new LaunchArgsStore();
+        const launchArgs: LaunchArguments = { values: { 'attach-container': ['B'], 'session-preference': ['foo=1'] }, negated: [] };
+        store.store(1, launchArgs);
+        expect(store.get(1)).to.deep.equal(launchArgs);
+    });
+
+    it('keeps the argv for the window lifetime, so a reload still sees it', () => {
+        const store = new LaunchArgsStore();
+        store.store(1, args('attach-container', 'B'));
+        expect(store.get(1)).to.deep.equal(args('attach-container', 'B'));
+        // a second read (e.g. after a reload) still returns the options
+        expect(store.get(1)).to.deep.equal(args('attach-container', 'B'));
+    });
+
+    it('returns undefined for an unknown (cold-start) window id', () => {
+        const store = new LaunchArgsStore();
+        expect(store.get(42)).to.equal(undefined);
+    });
+
+    it('drops the argv once the window is deleted', () => {
+        const store = new LaunchArgsStore();
+        store.store(1, args('attach-container', 'A'));
+        store.delete(1);
+        expect(store.get(1)).to.equal(undefined);
+    });
+
+    it('keeps entries independent per window id', () => {
+        const store = new LaunchArgsStore();
+        store.store(1, args('attach-container', 'A'));
+        store.store(2, args('attach-container', 'B'));
+        expect(store.get(2)).to.deep.equal(args('attach-container', 'B'));
+        expect(store.get(1)).to.deep.equal(args('attach-container', 'A'));
+    });
+});

package/src/electron-main/launch-args-store.ts

@@ -0,0 +1,73 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { injectable } from 'inversify';
+import { LaunchArguments } from '../common/launch-arguments';
+
+/**
+ * Holds the parsed CLI options of *forwarded* launches (see the `second-instance` handling in
+ * `ElectronMainApplication`) in the trusted Electron main process, keyed by the `webContents` id of
+ * the window that was opened for them.
+ *
+ * ### Why the arguments never travel on the window URL
+ *
+ * The URL is the one channel in the system that carries no trust: in a browser deployment it is
+ * attacker-writable, so putting per-window options such as `--session-preference` there would let a
+ * crafted link inject settings (some of which persist to the User scope). The arguments therefore
+ * stay here in the main process and are handed to the window over the per-window metadata channel
+ * (`CHANNEL_WC_METADATA`), where main identifies the calling window by `event.sender.id` rather than
+ * by any value from the URL. This is the single place that documents that rationale; other files
+ * point here.
+ *
+ * The entry is not consumed on first read, so that a plain `Reload Window`, which re-runs the
+ * renderer against the same window, still observes the arguments. It is removed when the window is
+ * closed, and when the window is redirected to a *different* frontend (e.g. into a dev container
+ * after a CLI attach), since the arguments describe the launch rather than whatever the window is
+ * navigated to afterwards. See `TheiaElectronWindow.reload`.
+ *
+ * @experimental
+ */
+@injectable()
+export class LaunchArgsStore {
+
+    protected readonly argsByWindowId = new Map<number, LaunchArguments>();
+
+    /**
+     * Associates the parsed options of a forwarded launch with the window identified by `windowId` (its
+     * `webContents` id). Must be called before the window loads its URL, so that the preload script
+     * cannot ask for the arguments before they are stored.
+     */
+    store(windowId: number, args: LaunchArguments): void {
+        this.argsByWindowId.set(windowId, args);
+    }
+
+    /**
+     * Returns the parsed launch options for the window identified by `windowId`, or `undefined`
+     * for a window that was not opened by a forwarded launch (a cold-start window), or one whose
+     * arguments were dropped. Repeatable, so a plain reload still sees the arguments.
+     */
+    get(windowId: number): LaunchArguments | undefined {
+        return this.argsByWindowId.get(windowId);
+    }
+
+    /**
+     * Drops the arguments stored for `windowId`. Called when the window is closed, and when it is
+     * redirected to a different frontend.
+     */
+    delete(windowId: number): void {
+        this.argsByWindowId.delete(windowId);
+    }
+}