arcane-os 0.71.2 → 0.72.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.72.0
+
+- Add optional `native.launchContext` defaults for ordinary packaged launch and
+  public `resolveNativeLaunchContext()` through `arcane-os/core/host`. Native
+  applications and external MCP can select the same app-owned state, workspace,
+  shared endpoint and log without reconstructing platform paths.
+- Extend `readCoreLaunchContext()` with explicit defaults and opt-in native
+  resolution. Preserve complete explicit launch records, selected workspace
+  values, ordinary stdio ownership and the existing no-option entry path.
+- Forward packaged launch defaults through Windows and macOS launchers while
+  preserving window, profile, service and shared-host lifecycle behavior. No
+  stored-data migration or dependency change is introduced.
+
 ## 0.71.2
 
 - Preserve complete browser Kokoro synthesis input through the selected runtime's

package/README.md

@@ -20,7 +20,7 @@ selected SDK projection or an explicit live SDK source mount. Both profiles
 share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.71.2` SDK contract. Development applications declare
+This checkout defines the `0.72.0` SDK contract. Development applications declare
 `arcane-os` as `latest` and retain their lockfile. Exact SDK pins begin when Roshi
 designates a production build. Follow [Consumer updates](docs/consumer-updates.md)
 to refresh and compare the installed SDK and lockfile with the published channel;

package/docs/reference/README.md

@@ -43,6 +43,7 @@ alone does not make bare module names resolve in a browser.
 | Use the `arcane` command | [CLI reference](cli.md) |
 | Install an app and cache selected resources offline | [Progressive web applications](pwa.md) |
 | Disable source PWA generation or explicitly retire confirmed generated output | [Source PWA retirement](pwa.md#disable-source-pwa-generation-and-retire-generated-output) |
+| Retire the prior worker after explicitly disabling standalone source PWA | [Disabled-worker browser lifecycle](pwa.md#disabled-worker-retirement-on-the-source-server) |
 | Generate named browser imports or inspect the selected physical runtime | [`arcane import-map`](cli.md#arcane-import-map) and [browser runtime delivery](protocols.md#browser-runtime-delivery) |
 | Connect an application through the shared WebSocket transport | [Shared WebSocket clients](websocket-client.md) |
 | Choose browser, native, cloud, or cross-host behavior | [Availability and normalization](availability-and-normalization.md) |

package/docs/reference/core-native-packaging.md

@@ -210,6 +210,64 @@ details and [the client contract](core-client.md) for native bridge integration.
 
 ## Launch-time locations
 
+An application can select defaults for ordinary double-click launch in its
+descriptor, without a replacement launcher or a required command-line file:
+
+```json
+{
+  "native": {
+    "launchContext": {
+      "sharedHost": {},
+      "dispatch": {"destination": "Moon Cheese Receiving Dock"}
+    }
+  }
+}
+```
+
+This is the `native` fragment of the application's complete descriptor. The
+optional `native.launchContext` object is copied intact to the portable
+manifest and generated Core entry. Its presence explicitly selects native
+location defaults. `sharedHost:{}` opts into the shared Core endpoint and log;
+omitting `sharedHost` retains stdio-owned Core lifetime. Omitting
+`native.launchContext` retains the previous generated-entry behavior entirely.
+Windows and macOS launchers use the same packaged defaults for native state
+selection, so an ordinary executable launch and external MCP can select the
+same app-owned Core.
+
+`resolveNativeLaunchContext({appId,context={}})` from `arcane-os/core/host` is
+the public, synchronous location owner for native applications and external MCP.
+It returns a new complete context and fills only omitted fields:
+
+| Field | SDK default |
+|---|---|
+| `stateRoot` on Windows | `%LOCALAPPDATA%/Arcane/<appId>`; standard home `AppData/Local` fallback when the environment value is absent |
+| `stateRoot` on macOS | `~/Library/Application Support/Arcane/<appId>` |
+| `stateRoot` on Linux | Absolute `$XDG_DATA_HOME/Arcane/<appId>`, otherwise `~/.local/share/Arcane/<appId>` |
+| `workspaceRoot` | `<resolved stateRoot>/Workspace` |
+| `sharedHost.endpoint`, only when `sharedHost` is selected | Windows named pipe `\\.\pipe\Arcane-` followed by the URL-encoded complete resolved state path; Linux/macOS socket `<resolved stateRoot>/core.sock` |
+| `sharedHost.logFile`, only when `sharedHost` is selected | `<resolved stateRoot>/Core.log` |
+
+Windows/macOS roots retain the existing native host locations. Linux is the
+portable Node host convention; an external composing host supplies its actual
+state root when it selects another location. Android and other host adaptations
+must supply `stateRoot` explicitly and own native IPC/process adaptation.
+The resolver never reads saved preferences, creates directories, changes the
+environment, starts services, or migrates existing data. The generated opted-in
+shared entry creates its selected state directory because its socket/log need
+that parent; application services continue to own workspace I/O. Custom
+endpoint/log parent directories retain the existing shared-host requirements.
+
+Explicit `stateRoot`, `workspaceRoot`, endpoint, log filename and additional
+fields remain authored values; the resolver derives omitted paths from the
+absolute selected state location. Relative explicit paths retain the caller's
+working-directory meaning, so UI and MCP callers must select the same location.
+No hashing, app-local OS path composition, directory scanning, or new repository
+location rule is involved. `resolveArcaneDataPaths()` continues to own its
+separate `ArcaneData/Repos` contract. A selected native context needs a nonempty
+string `appId` and state directory; a selected `sharedHost` must be an object.
+Malformed resolver inputs report `TypeError`; ordinary OS endpoint requirements
+remain at the IPC operation.
+
 For one app-owned Core shared by the native window and a separate MCP process,
 the launch context may explicitly select `sharedHost:{endpoint,logFile}`. The
 generated native child then connects through a stdio bridge, starting an
@@ -224,27 +282,36 @@ or `null`; the shared host replays that current listener to a newly attached
 macOS bridge, without restarting the server or retaining historical events.
 
 The generated Core entry accepts `--arcane-launch-config <path>`. The public
-`readCoreLaunchContext({argv=process.argv.slice(2)}={})` function in
-`arcane-os/core/host` reads that explicitly selected JSON object. A native host
+`readCoreLaunchContext({argv=process.argv.slice(2),defaults={},appId}={})`
+function in `arcane-os/core/host` reads that explicitly selected JSON object.
+Precedence is packaged `defaults`, then the native host's actual state-root
+argument, then every complete top-level field from the explicit JSON object.
+Nested records replace their default field as a whole; they are not deep-merged.
+An `appId` explicitly opts the result into `resolveNativeLaunchContext`; the
+generated entry supplies it only when `native.launchContext` is present.
+A native host
 can separately supply `--arcane-host-state-root <directory>` for the reader's
 `stateRoot` default. Every field in the explicit JSON object takes precedence
 unchanged, including an explicitly present `stateRoot` with a relative, null or
-other application-owned value. With neither argument the reader returns `{}`.
+other application-owned value on the ordinary non-resolving reader. With neither
+argument nor defaults/appId the reader still returns `{}`.
 Missing files, missing argument values and malformed JSON report their actual
 errors; the reader does not search for configuration, resolve or validate the
-state directory, rewrite the file or change the process environment.
+state directory, rewrite the file or change the process environment. The
+explicitly opted-in resolver supplies its documented defaults after this merge.
 
 The generated entry supplies an artifact-derived `appRoot` and then applies the
 complete explicit launch context. Every service factory receives that same
 object as its second argument, preserving its authored first argument. A
 launcher can supply the user's selected `workspaceRoot` and writable
 `stateRoot` at launch instead of embedding this machine's paths in an app
-package. The host owns those selections; the SDK does not choose a product's
-workspace, namespace, saved preferences or models. JSON values and additional
+package. Explicit product selections take precedence over the opted-in SDK
+location defaults. The SDK chooses no saved preference filename or model. JSON values and additional
 application-owned fields remain unchanged, including an app-selected
 `preferencesFile`. The state directory supplies no preference filename and
 triggers no stored-data discovery or migration. Linux and other composing hosts
-may pass the same separate argument; the reader chooses no platform directory.
+may pass the same separate argument; the ordinary reader chooses no platform
+directory until native resolution is explicitly selected.
 
 ## Selected local-AI runtimes
 

package/docs/reference/core-shared-host.md

@@ -146,8 +146,46 @@ events may change; applications own those domain methods and state.
 
 ## Native launch and platforms
 
-The generated portable Core entry keeps ordinary stdio behavior unless the
-explicit launch context contains:
+The generated portable Core entry keeps ordinary stdio behavior unless its
+selected launch context contains `sharedHost`. An application can opt in for
+ordinary packaged executable launch with `native.launchContext:{sharedHost:{}}`
+in its complete descriptor. The SDK supplies the app's platform state root,
+workspace, endpoint and diagnostic log through `resolveNativeLaunchContext`.
+The same public owner is available to external MCP:
+
+```js
+import {readCoreLaunchContext, connectSharedCoreHost} from 'arcane-os/core/host';
+
+const context = await readCoreLaunchContext({
+    appId: appDescriptor.id,
+    defaults: appDescriptor.native.launchContext
+});
+const connection = await connectSharedCoreHost({
+    endpoint: context.sharedHost.endpoint
+});
+// Invoke the application's actual services through connection.client.
+// Disconnect this MCP client without shutting down the application's host.
+await connection.close();
+```
+
+This example connects to a running native/headless host. The existing `start`
+option can start the packaged Core entry explicitly when independent MCP-first
+startup is needed; the entry applies those same packaged defaults. Pass the
+same explicit `--arcane-launch-config` file to both entries for user-selected
+locations. A caller that already owns a complete context can use the pure
+`resolveNativeLaunchContext({appId,context})` directly instead of reading argv.
+For MCP-first startup, prepare the returned `context.stateRoot` with Node's
+`mkdir(context.stateRoot,{recursive:true})` before selecting `start`, because
+the parent's startup diagnostic log opens before the headless child runs.
+This uses the resolved directory directly, without duplicating platform path
+rules. Pass `context.sharedHost.logFile` to that existing `start` record and
+the same launch file to the packaged Core command. Custom endpoint/log parent
+directories remain caller-selected.
+See [launch-time locations](core-native-packaging.md#launch-time-locations) for
+the exact platform defaults, precedence, location override and directory rules.
+No app must reconstruct OS directory rules.
+
+An explicit launch file can also select the existing full endpoint contract:
 
 ```json
 {
@@ -163,8 +201,9 @@ option, the native Core child is a stdio-to-shared-Core bridge. It connects or
 launches the same entry with `--arcane-core-headless`; the headless entry claims
 the endpoint before importing services. Closing the native window ends its
 bridge, while the independent Core host remains available. Service options and
-the complete launch context retain their existing values. There is no implicit
-shared mode or new application descriptor field.
+the complete launch context retain their existing values. Shared mode remains
+explicit: the new descriptor option selects defaults only for that application,
+and the existing no-option stdio path is unchanged.
 
 `startSharedCoreBridge({endpoint,start,input=process.stdin,
 output=process.stdout,signal,onError})` is also public. It returns

package/docs/reference/inventory/package-api.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.71.0",
+  "sdkVersion": "0.71.1",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
@@ -1185,7 +1185,7 @@
       ],
       "primaryImport": "arcane-os",
       "group": "Headless toolchain operations",
-      "summary": "Starts one owned browser development server for the selected application.",
+      "summary": "Starts one owned browser development server for the selected application, including native worker retirement when standalone source PWA is explicitly disabled and its root worker is absent.",
       "availability": "Node; selected operation may produce browser or native output",
       "protocol": "Shared headless operation API + arcane-cli-events/1",
       "normalization": "SDK-normalized inputs, errors, events, and documented result"
@@ -2446,7 +2446,7 @@
       ],
       "primaryImport": "arcane-os",
       "group": "Workspace, doctor, repository, and server",
-      "summary": "Starts an owned source or packaged browser server with complete selected routes, HTTPS by default, explicit HTTP selection, listener readiness and shutdown.",
+      "summary": "Starts an owned source or packaged browser server with complete selected routes, HTTPS by default, explicit HTTP selection, listener readiness and shutdown; explicitly disabled standalone source PWA retires an absent root worker through its native lifecycle.",
       "availability": "Node control plane; browser data plane",
       "protocol": "Node ESM",
       "normalization": "SDK-normalized inputs, errors, events, and documented result"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.71.2",
+  "version": "0.72.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/schemas/arcane-app.schema.json

@@ -132,6 +132,10 @@
           }
         },
         "localAI": { "$ref": "#/$defs/localAI" },
+        "launchContext": {
+          "type": "object",
+          "description": "Optional complete native launch defaults. Presence opts into SDK per-app native locations; sharedHost:{} explicitly selects the shared endpoint. Explicit launch JSON fields take precedence unchanged."
+        },
         "window": {
           "type": "object",
           "additionalProperties": false,

package/src/app-descriptor.mjs

@@ -254,7 +254,7 @@ function validateNativeWindow(value){
 }
 
 function validateNative(value,appId){
-    assertOnlyKeys(value,new Set(['type','icon','order','bundledApps','documentCatalog','localAI','services','window']),'descriptor.native');
+    assertOnlyKeys(value,new Set(['type','icon','order','bundledApps','documentCatalog','localAI','services','window','launchContext']),'descriptor.native');
     if(!NATIVE_TYPES.has(value.type))fail('descriptor.native.type is unsupported.');
     const icon=value.icon===null?null:normalizeRelativePath(value.icon,'descriptor.native.icon');
     if(!is.integer(value.order)||value.order<0){
@@ -265,6 +265,9 @@ function validateNative(value,appId){
     });
     const documentCatalog=validateDocumentCatalog(value.documentCatalog);
     const window=validateNativeWindow(value.window);
+    if(value.launchContext!==undefined&&!isObject(value.launchContext)){
+        fail('descriptor.native.launchContext must be an object.');
+    }
     let services;
     if(value.services!==undefined){
         if(!is.array(value.services))fail('descriptor.native.services must be an array.');
@@ -279,6 +282,7 @@ function validateNative(value,appId){
         order:value.order,
         bundledApps,
         ...(window===undefined?{}:{window}),
+        ...(value.launchContext===undefined?{}:{launchContext:value.launchContext}),
         ...(services===undefined?{}:{services}),
         ...(value.localAI===undefined?{}:{localAI:normalizeLocalAIConfig(value.localAI)}),
         ...(documentCatalog?{documentCatalog}:{})
@@ -416,6 +420,7 @@ export function projectNativeDescriptor(descriptor,{source}={}){
         ...(value.native.documentCatalog?{documentCatalog:value.native.documentCatalog}:{}),
         ...(value.native.services===undefined?{}:{services:value.native.services}),
         ...(value.native.window===undefined?{}:{window:value.native.window}),
+        ...(value.native.launchContext===undefined?{}:{launchContext:value.native.launchContext}),
         ...(value.native.localAI===undefined?{}:{localAI:value.native.localAI}),
         include:[...value.package.include]
     };
@@ -462,6 +467,7 @@ function synthesizedDescriptor(packageManifest,nativeDescriptor){
             bundledApps:[...(native.bundledApps??[])],
             ...(native.services===undefined?{}:{services:native.services}),
             ...(native.window===undefined?{}:{window:native.window}),
+            ...(native.launchContext===undefined?{}:{launchContext:native.launchContext}),
             ...((packageManifest.localAI??native.localAI)===undefined?{}:{localAI:packageManifest.localAI??native.localAI}),
             ...(native.documentCatalog?{documentCatalog:native.documentCatalog}:{})
         },

package/src/core/host.mjs

@@ -1,4 +1,6 @@
 import {readFile} from 'node:fs/promises';
+import {homedir} from 'node:os';
+import path from 'node:path';
 import Is from 'strong-type';
 import {createCoreRuntime} from './runtime.mjs';
 import {startCoreStdio} from './stdio.mjs';
@@ -7,32 +9,90 @@ export {startSharedCoreHost, connectSharedCoreHost, runSharedCoreHost, startShar
 
 const is = new Is(false);
 
+/** Resolve one app's native locations without creating or migrating data. */
+export function resolveNativeLaunchContext({appId, context = {}} = {}) {
+    if (!is.string(appId) || !appId) throw new TypeError('Native launch resolution requires an appId.');
+    if (context === null || !is.object(context) || is.array(context)) {
+        throw new TypeError('Native launch context must be an object.');
+    }
+    let stateRoot = context.stateRoot;
+    if (stateRoot === undefined) {
+        const home = homedir();
+        switch (process.platform) {
+            case 'win32':
+                stateRoot = path.join(process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'Arcane', appId);
+                break;
+            case 'darwin':
+                stateRoot = path.join(home, 'Library', 'Application Support', 'Arcane', appId);
+                break;
+            case 'linux': {
+                const xdg = process.env.XDG_DATA_HOME;
+                stateRoot = path.join(xdg && path.isAbsolute(xdg) ? xdg : path.join(home, '.local', 'share'), 'Arcane', appId);
+                break;
+            }
+            default:
+                throw new TypeError('This native host must supply its persistent stateRoot.');
+        }
+    }
+    if (!is.string(stateRoot) || !stateRoot) throw new TypeError('Native stateRoot must be a nonempty directory path.');
+    const root = path.resolve(stateRoot);
+    const resolved = {
+        ...context,
+        stateRoot,
+        workspaceRoot: context.workspaceRoot === undefined ? path.join(root, 'Workspace') : context.workspaceRoot
+    };
+    if (context.sharedHost !== undefined) {
+        if (context.sharedHost === null || !is.object(context.sharedHost) || is.array(context.sharedHost)) {
+            throw new TypeError('Native sharedHost must be an object.');
+        }
+        // Encode the complete selected Windows path as a pipe-name component;
+        // Unix IPC uses an ordinary file in that same persistent app directory.
+        const endpoint = process.platform === 'win32'
+            ? '\\\\.\\pipe\\Arcane-' + encodeURIComponent(root)
+            : path.join(root, 'core.sock');
+        resolved.sharedHost = {
+            ...context.sharedHost,
+            endpoint: context.sharedHost.endpoint === undefined ? endpoint : context.sharedHost.endpoint,
+            logFile: context.sharedHost.logFile === undefined ? path.join(root, 'Core.log') : context.sharedHost.logFile
+        };
+    }
+    return resolved;
+}
+
 /**
- * The host's separate state-root argument supplies a launch-context default.
+ * Packaged defaults precede the host's actual state-root argument.
  * Every field in an explicitly selected launch JSON object takes precedence
  * unchanged; field meanings belong to the launch owner and individual services.
+ * appId explicitly selects native location resolution; ordinary calls keep the
+ * existing read-only launch-file contract without choosing any locations.
  */
-export async function readCoreLaunchContext({argv = process.argv.slice(2)} = {}) {
+export async function readCoreLaunchContext({argv = process.argv.slice(2), defaults = {}, appId} = {}) {
+    if (defaults === null || !is.object(defaults) || is.array(defaults)) {
+        throw new TypeError('Core launch defaults must be an object.');
+    }
     const stateFlag = argv.indexOf('--arcane-host-state-root');
-    const defaults = {};
+    const context = {...defaults};
     if (stateFlag !== -1) {
         const stateRoot = argv[stateFlag + 1];
         if (stateRoot === undefined || stateRoot === '') {
             throw new TypeError('--arcane-host-state-root requires a directory.');
         }
-        defaults.stateRoot = stateRoot;
+        context.stateRoot = stateRoot;
     }
     const flag = argv.indexOf('--arcane-launch-config');
-    if (flag === -1) return defaults;
-    const filename = argv[flag + 1];
-    if (filename === undefined || filename === '') {
-        throw new TypeError('--arcane-launch-config requires a filename.');
-    }
-    const context = JSON.parse(await readFile(filename, 'utf8'));
-    if (context === null || !is.object(context) || is.array(context)) {
-        throw new TypeError('Core launch configuration must be a JSON object.');
+    let selected = context;
+    if (flag !== -1) {
+        const filename = argv[flag + 1];
+        if (filename === undefined || filename === '') {
+            throw new TypeError('--arcane-launch-config requires a filename.');
+        }
+        const explicit = JSON.parse(await readFile(filename, 'utf8'));
+        if (explicit === null || !is.object(explicit) || is.array(explicit)) {
+            throw new TypeError('Core launch configuration must be a JSON object.');
+        }
+        selected = {...context, ...explicit};
     }
-    return {...defaults, ...context};
+    return appId === undefined ? selected : resolveNativeLaunchContext({appId, context: selected});
 }
 
 /** Compose app services with the shared dispatcher and draining transport. */

package/src/core/hosts/macos/ArcaneLauncher.m

@@ -231,14 +231,25 @@ typedef NS_ENUM(NSUInteger, ArcaneDiagnosticStream) {
     NSString *appID = ArcaneRequiredString(app, @"id", error);
     if (!appID) return NO;
     _title = [app[@"displayName"] isKindOfClass:NSString.class] ? app[@"displayName"] : appID;
+    id defaults = manifest[@"launchContext"];
+    if (defaults && ![defaults isKindOfClass:NSDictionary.class]) {
+        *error = ArcaneLauncherError(@"CORE_LAUNCH_MANIFEST_INVALID", @"The native launchContext must be an object.", defaults);
+        return NO;
+    }
+    NSMutableDictionary *launchContext = defaults ? [defaults mutableCopy] : [NSMutableDictionary dictionary];
     if (_launchFilename) {
-        _launchContext = ArcaneReadRecord([NSURL fileURLWithPath:_launchFilename], error);
-        if (!_launchContext) return NO;
+        NSDictionary *explicitContext = ArcaneReadRecord([NSURL fileURLWithPath:_launchFilename], error);
+        if (!explicitContext) return NO;
+        [launchContext addEntriesFromDictionary:explicitContext];
     }
+    _launchContext = launchContext;
+    // The opted-in Node resolver uses HOME when supplied; retain the previous
+    // native default unchanged for applications without launchContext.
+    NSString *nativeHome = defaults ? (NSProcessInfo.processInfo.environment[@"HOME"] ?: NSHomeDirectory()) : NSHomeDirectory();
     id selectedState = _launchContext[@"stateRoot"];
     _stateRoot = [selectedState isKindOfClass:NSString.class]
         ? ArcaneAbsolutePath(selectedState, _workingDirectory)
-        : [[NSHomeDirectory() stringByAppendingPathComponent:@"Library/Application Support/Arcane"] stringByAppendingPathComponent:appID];
+        : [[nativeHome stringByAppendingPathComponent:@"Library/Application Support/Arcane"] stringByAppendingPathComponent:appID];
     [self scheduleDiagnostics];
     NSString *clientPath = ArcaneRequiredString(client, @"source", error);
     if (!clientPath) return NO;

package/src/core/hosts/windows/ArcaneLauncher.cs

@@ -57,13 +57,33 @@ namespace Arcane.Core.Hosts.Windows
                 Dictionary<string, object> host = manifest.TryGetValue("host", out hostValue) ? hostValue as Dictionary<string, object> : null;
                 string icon = host != null && host.TryGetValue("icon", out iconValue) ? iconValue as string : null;
 
-                // Core rereads this exact selected file. Do not normalize,
-                // rewrite, filter or copy the application's launch record.
-                Dictionary<string, object> launchContext = launchFilename == null ? null : ReadRecord(launchFilename);
+                // Native UI and generated Core use the same packaged defaults.
+                // Core rereads the explicit file; every explicit field wins.
+                Dictionary<string, object> launchContext = manifest.ContainsKey("launchContext")
+                    ? new Dictionary<string, object>(RequiredRecord(manifest, "launchContext"))
+                    : new Dictionary<string, object>();
+                if (launchFilename != null)
+                {
+                    foreach (KeyValuePair<string, object> field in ReadRecord(launchFilename))
+                        launchContext[field.Key] = field.Value;
+                }
+                string defaultStateBase = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData);
+                if (manifest.ContainsKey("launchContext"))
+                {
+                    // Match the public Node resolver for this opt-in contract,
+                    // including an explicitly selected process environment.
+                    defaultStateBase = Environment.GetEnvironmentVariable("LOCALAPPDATA");
+                    if (String.IsNullOrEmpty(defaultStateBase))
+                    {
+                        string home = Environment.GetEnvironmentVariable("USERPROFILE");
+                        if (String.IsNullOrEmpty(home)) home = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile);
+                        defaultStateBase = Path.Combine(home, "AppData", "Local");
+                    }
+                }
                 object stateRoot;
-                string profileParent = launchContext != null && launchContext.TryGetValue("stateRoot", out stateRoot) && stateRoot is string
+                string profileParent = launchContext.TryGetValue("stateRoot", out stateRoot) && stateRoot is string
                     ? Path.GetFullPath((string)stateRoot)
-                    : Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "Arcane", appId);
+                    : Path.Combine(defaultStateBase, "Arcane", appId);
                 OpenDiagnostics(Path.Combine(profileParent, "Diagnostics"));
                 ArcaneHostOptions options = new ArcaneHostOptions
                 {

package/src/native/portable-layout.mjs

@@ -151,6 +151,7 @@ export async function copyCoreRuntime(root, files, signal, {
 }
 
 export function coreEntrySource(application, version, services, {localAI, runtimes = [], packagedWeb = false} = {}) {
+    const launchDefaults = application.native?.launchContext;
     const imageSelected = localAI?.runtimes?.some(function selectedImage(requirement) {
         return (typeof requirement === 'string' ? requirement : requirement.id) === 'stable-diffusion.cpp';
     }) ?? false;
@@ -199,6 +200,7 @@ export function coreEntrySource(application, version, services, {localAI, runtim
         "import {fileURLToPath} from 'node:url';",
         "import path from 'node:path';",
         "import {isSea} from 'node:sea';",
+        ...(launchDefaults === undefined ? [] : ["import {mkdir} from 'node:fs/promises';"]),
         "import {readCoreLaunchContext, startCoreHost, runSharedCoreHost, startSharedCoreBridge} from 'arcane-os/core/host';",
         '',
         ...(localAI === undefined ? [] : [
@@ -241,9 +243,15 @@ export function coreEntrySource(application, version, services, {localAI, runtim
             '        return resolved;',
             '    }),'
         ]),
-        '    ...await readCoreLaunchContext()',
+        launchDefaults === undefined ? '    ...await readCoreLaunchContext()'
+            : `    ...await readCoreLaunchContext({appId: ${JSON.stringify(application.id)}, defaults: JSON.parse(${JSON.stringify(JSON.stringify(launchDefaults))})})`,
         '};',
         '',
+        ...(launchDefaults === undefined ? [] : [
+            '// The shared endpoint and diagnostic log require their selected state directory.',
+            'if (context.sharedHost !== undefined) await mkdir(context.stateRoot, {recursive: true});',
+            ''
+        ]),
         ...(packagedWeb ? ['let packagedWeb;', ''] : []),
         'async function createServices(register) {',
         `    const [${imports.map(function binding(selection) { return selection.binding; }).join(', ')}] = await Promise.all([`,

package/src/native/portable-provider.mjs

@@ -197,6 +197,7 @@ export function createPortableNativeProvider({services, packagedWeb = false, web
                     webRoot: 'app',
                     start: release.manifest?.app?.start ?? './index.html',
                     ...(appDescriptor.native?.window === undefined ? {} : {window: {...appDescriptor.native.window}}),
+                    ...(appDescriptor.native?.launchContext === undefined ? {} : {launchContext: appDescriptor.native.launchContext}),
                     core: {
                         entry: 'runtime/arcane-core.mjs', transport: 'stdio', protocol: 'arcane/1', services: selectedServices,
                         ...(localAI === undefined ? {} : {localAIRuntimes: bundled.runtimes})