arcane-os 0.71.1 → 0.72.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # 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
+  phonemization and tokenizer. Process every token in ordered model-capacity
+  segments and retain all resulting audio, with one model owner and request-local
+  cancellation. Keep short-input behavior, voice, speed and the public API intact.
+- Include the browser decision runtime entry in an explicitly configured DBOPFS
+  model store. Retain the original resource URL across activations, import the
+  complete stored self-contained module, and join cancellation cleanup before
+  settling callers. Preserve direct loading when no store is configured.
+
 ## 0.71.1
 
 - Correct explicit disabled PWA lifecycle in standalone source development by

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.1` 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/browser-runtime/ai/browser-decisions.mjs

@@ -204,6 +204,9 @@ class BrowserDecisionModel {
             pending: new Map(),
             evaluations: new Set(),
             resources: null,
+            runtimeController: null,
+            runtimePreparation: null,
+            runtimeUrl: null,
             cleanup: null,
             reason: undefined
         };
@@ -263,9 +266,58 @@ class BrowserDecisionModel {
             }
             const id = this.#nextId++;
             activation.pending.set(id, activation.load);
-            worker.postMessage(
-                {id, op: 'load', payload: this.#configuration, storedResources: this.#store !== null}
-            );
+            if (this.#store) {
+                activation.runtimeController = new AbortController();
+                // Retain the operation before a store progress callback can
+                // synchronously unload this activation.
+                activation.runtimePreparation = Promise.resolve().then(
+                    async function prepareDecisionRuntimeEntry() {
+                        if (!model.#isCurrent(activation)) return;
+                        const configuration = model.#configuration;
+                        const sourceUrl = new URL(configuration.runtime.moduleUrl, import.meta.url).href;
+                        const response = await model.#store.fetchResource(sourceUrl, {
+                            signal: activation.runtimeController.signal,
+                            onProgress: function reportRuntimeEntryProgress(progress) {
+                                if (!model.#isCurrent(activation)) return;
+                                model.#progress = progress;
+                                model.#publish();
+                            }
+                        });
+                        if (!model.#isCurrent(activation)) return;
+                        if (response.status < 200 || response.status >= 300) {
+                            const error = new Error(
+                                `The decision runtime returned HTTP ${response.status} ${response.statusText}.`
+                            );
+                            error.code = 'ARCANE_DECISION_RUNTIME_DOWNLOAD_FAILED';
+                            error.response = response;
+                            throw error;
+                        }
+                        // Import the complete stored module without source
+                        // rewriting. This activation owns its URL until stop.
+                        activation.runtimeUrl = URL.createObjectURL(
+                            new Blob([response.file], {type: 'text/javascript'})
+                        );
+                        worker.postMessage({
+                            id,
+                            op: 'load',
+                            payload: {
+                                ...configuration,
+                                runtime: {...configuration.runtime, moduleUrl: activation.runtimeUrl}
+                            },
+                            storedResources: true
+                        });
+                    }
+                );
+                activation.runtimePreparation.catch(
+                    function stopFailedRuntimePreparation(error) {
+                        if (model.#isCurrent(activation)) model.#stop(activation, error, 'error');
+                    }
+                );
+            } else {
+                worker.postMessage(
+                    {id, op: 'load', payload: this.#configuration, storedResources: false}
+                );
+            }
         } catch (error) {
             this.#stop(activation, error, 'error');
         }
@@ -333,11 +385,42 @@ class BrowserDecisionModel {
         this.#state = state;
         this.#progress = null;
         this.#error = reason;
-        if (activation.resources) {
+        const cleanup = [];
+        activation.runtimeController?.abort(reason);
+        if (activation.runtimePreparation) {
+            cleanup.push(activation.runtimePreparation.catch(
+                function preserveRuntimePreparationFailure(error) {
+                    if (error === reason || error?.name === 'AbortError') return;
+                    throw error;
+                }
+            ));
+        }
+        if (activation.resources) cleanup.push(activation.resources.close(reason));
+        if (activation.worker) {
+            for (const [type, listener] of Object.entries(activation.listeners ?? {})) {
+                activation.worker.removeEventListener(type, listener);
+            }
+            activation.worker.terminate();
+        }
+        if (activation.runtimeUrl !== null) {
+            try {
+                URL.revokeObjectURL(activation.runtimeUrl);
+            } catch (error) {
+                cleanup.push(Promise.reject(error));
+            }
+            activation.runtimeUrl = null;
+        }
+        if (cleanup.length > 0) {
             const model = this;
-            activation.cleanup = activation.resources.close(reason).catch(
-                function preserveResourceCleanupFailure(error) {
-                    activation.reason = new AggregateError([reason, error], 'Unable to settle decision model resources.');
+            activation.cleanup = Promise.allSettled(cleanup).then(
+                function settleDecisionResourceCleanup(results) {
+                    const failures = results.filter(function failedCleanup(result) {
+                        return result.status === 'rejected';
+                    }).map(function cleanupReason(result) {
+                        return result.reason;
+                    });
+                    if (failures.length === 0) return;
+                    activation.reason = new AggregateError([reason, ...failures], 'Unable to settle decision model resources.');
                     throw activation.reason;
                 }
             );
@@ -350,12 +433,6 @@ class BrowserDecisionModel {
                 }
             );
         }
-        if (activation.worker) {
-            for (const [type, listener] of Object.entries(activation.listeners ?? {})) {
-                activation.worker.removeEventListener(type, listener);
-            }
-            activation.worker.terminate();
-        }
         activation.load.reject(reason);
         for (const operation of activation.pending.values()) operation.reject(reason);
         activation.pending.clear();

package/browser-runtime/ai/kokoro-complete-input.mjs

@@ -0,0 +1,116 @@
+import Is from '../dependencies/strong-type/index.js';
+
+const is = new Is(false);
+
+function throwIfCancelled(signal) {
+    if (signal?.aborted) {
+        throw signal.reason ?? new DOMException('Speech synthesis was cancelled.', 'AbortError');
+    }
+}
+
+/**
+ * Compose the selected Kokoro public classes without changing loaded instances.
+ * The original synthesizer remains the sole owner of its model and disposal.
+ */
+export async function createCompleteKokoroSynthesis({
+    KokoroTTS,
+    synthesizer,
+    repository,
+    signal,
+    onProgress,
+}) {
+    throwIfCancelled(signal);
+    const Tokenizer = synthesizer.tokenizer.constructor;
+    class CompleteKokoroTokenizer extends Tokenizer {
+        _call(text, options = {}) {
+            return super._call(text, { ...options, truncation: false });
+        }
+    }
+    // Kokoro 1.2.1's factory uses the tokenizer's default revision. Reuse that
+    // same public loading contract through the existing Worker resource router.
+    const tokenizer = await CompleteKokoroTokenizer.from_pretrained(repository, {
+        progress_callback: onProgress,
+    });
+    throwIfCancelled(signal);
+    const contextLength = tokenizer.model_max_length;
+    if (!is.safeInteger(contextLength) || contextLength < 3) {
+        throw new Error('The selected Kokoro tokenizer does not expose its model context length.');
+    }
+    const contentCapacity = contextLength - 2;
+    function boundaryIds(text) {
+        const encoded = tokenizer(text, {
+            add_special_tokens: false,
+            return_tensor: false,
+            truncation: false,
+        });
+        return new Set(encoded.input_ids.map(function tokenId(id) { return BigInt(id); }));
+    }
+    const punctuation = boundaryIds(';:,.!?—…');
+    const spaces = boundaryIds(' ');
+
+    function segmentEnd(tokens, start, limit, contentEnd) {
+        if (limit === contentEnd) return limit;
+        for (const boundaries of [punctuation, spaces]) {
+            for (let index = limit - 1; index >= start; index -= 1) {
+                if (boundaries.has(tokens[index])) return index + 1;
+            }
+        }
+        return limit;
+    }
+
+    class CompleteKokoroTTS extends KokoroTTS {
+        #signal;
+
+        constructor(requestSignal) {
+            super(synthesizer.model, tokenizer);
+            this.#signal = requestSignal;
+        }
+
+        async generate_from_ids(inputIds, options = {}) {
+            throwIfCancelled(this.#signal);
+            if (inputIds.dims.at(-1) <= contextLength) {
+                const output = await super.generate_from_ids(inputIds, options);
+                throwIfCancelled(this.#signal);
+                return output;
+            }
+            const Tensor = inputIds.constructor;
+            const tokens = inputIds.data;
+            const contentEnd = tokens.length - 1;
+            const outputs = [];
+            let sampleCount = 0;
+            for (let start = 1; start < contentEnd;) {
+                throwIfCancelled(this.#signal);
+                const end = segmentEnd(tokens, start, Math.min(start + contentCapacity, contentEnd), contentEnd);
+                // Only the original outer padding positions are replaced. All
+                // content tokens, including boundary punctuation/space, survive.
+                const data = new BigInt64Array(end - start + 2);
+                data[0] = tokens[0];
+                data.set(tokens.subarray(start, end), 1);
+                data[data.length - 1] = tokens[tokens.length - 1];
+                const ids = new Tensor('int64', data, [1, data.length]);
+                const output = await super.generate_from_ids(ids, options);
+                throwIfCancelled(this.#signal);
+                outputs.push(output);
+                sampleCount += output.audio.length;
+                start = end;
+            }
+            const audio = new Float32Array(sampleCount);
+            let offset = 0;
+            for (const output of outputs) {
+                audio.set(output.audio, offset);
+                offset += output.audio.length;
+            }
+            throwIfCancelled(this.#signal);
+            const RawAudio = outputs[0].constructor;
+            return new RawAudio(audio, outputs[0].sampling_rate);
+        }
+    }
+
+    return async function synthesizeCompleteKokoro(text, { voice, speed, signal: requestSignal } = {}) {
+        throwIfCancelled(requestSignal);
+        // Each invocation retains its own signal while sharing the one loaded
+        // model. Inherited generate() still owns all upstream phonemization.
+        const request = new CompleteKokoroTTS(requestSignal);
+        return request.generate(text, { voice, speed });
+    };
+}

package/browser-runtime/ai/speech-worker-runtime.mjs

@@ -1,5 +1,6 @@
 import Is from "../dependencies/strong-type/index.js";
 import { createModelResourceClient, createModelResourceHost } from './model-resource-bridge.mjs';
+import { createCompleteKokoroSynthesis } from './kokoro-complete-input.mjs';
 
 const is = new Is(false);
 
@@ -1493,54 +1494,70 @@ async function createWhisperEngine(namespace, configuration, signal, report) {
 }
 
 async function createKokoroEngine(namespace, configuration, signal, report) {
-  if (!is.function(namespace?.KokoroTTS?.from_pretrained)) {
-    throw workerError(
-      "ARCANE_AI_PROVIDER_UNAVAILABLE",
-      "The Kokoro runtime does not export KokoroTTS.",
-      undefined,
-      "kokoro-tts-constructor-export-missing",
+    if (!is.function(namespace?.KokoroTTS?.from_pretrained)) {
+        throw workerError(
+            'ARCANE_AI_PROVIDER_UNAVAILABLE',
+            'The Kokoro runtime does not export KokoroTTS.',
+            undefined,
+            'kokoro-tts-constructor-export-missing',
+        );
+    }
+    throwIfAborted(signal, 'tts-load-cancelled');
+    const synthesizer = await namespace.KokoroTTS.from_pretrained(
+        configuration.model.repository,
+        {
+            device: configuration.execution?.device ?? 'wasm',
+            dtype: configuration.model.dtype ?? 'q8',
+            revision: configuration.model.revision,
+            progress_callback: report,
+        },
     );
-  }
-  throwIfAborted(signal, "tts-load-cancelled");
-  const synthesizer = await namespace.KokoroTTS.from_pretrained(
-    configuration.model.repository,
-    {
-      device: configuration.execution?.device ?? "wasm",
-      dtype: configuration.model.dtype ?? "q8",
-      revision: configuration.model.revision,
-      progress_callback: report,
-    },
-  );
-  try {
-    throwIfAborted(signal, "tts-load-cancelled");
-  } catch (error) {
+    let synthesize;
     try {
-      await disposeEngine(synthesizer);
-    } catch {
-      // Preserve the cancellation boundary while the owning Worker terminates.
+        throwIfAborted(signal, 'tts-load-cancelled');
+        synthesize = await createCompleteKokoroSynthesis({
+            KokoroTTS: namespace.KokoroTTS,
+            synthesizer,
+            repository: configuration.model.repository,
+            signal,
+            onProgress: report,
+        });
+        throwIfAborted(signal, 'tts-load-cancelled');
+    } catch (error) {
+        try {
+            await disposeEngine(synthesizer);
+        } catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], 'Kokoro preparation and model cleanup failed.', { cause: error });
+        }
+        throwIfAborted(signal, 'tts-load-cancelled');
+        throw error;
     }
-    throw error;
-  }
-  return completeValue({
-    async synthesize(input, { signal: requestSignal } = {}) {
-      throwIfAborted(requestSignal, "tts-synthesis-cancelled");
-      const output = await synthesizer.generate(input.text, {
-        voice: input.voice,
-        speed: input.speed,
-        signal: requestSignal,
-      });
-      throwIfAborted(requestSignal, "tts-synthesis-cancelled");
-      const audio = is.instanceCheck(output?.audio, Float32Array)
-        ? output.audio
-        : new Float32Array(output?.audio ?? []);
-      return completeValue({
-        audio,
-        sampleRate: output?.sampling_rate,
-        voice: input.voice,
-      });
-    },
-    dispose: () => disposeEngine(synthesizer),
-  });
+    return completeValue({
+        async synthesize(input, { signal: requestSignal } = {}) {
+            throwIfAborted(requestSignal, 'tts-synthesis-cancelled');
+            let output;
+            try {
+                output = await synthesize(input.text, {
+                    voice: input.voice,
+                    speed: input.speed,
+                    signal: requestSignal,
+                });
+            } catch (error) {
+                throwIfAborted(requestSignal, 'tts-synthesis-cancelled');
+                throw error;
+            }
+            throwIfAborted(requestSignal, 'tts-synthesis-cancelled');
+            const audio = is.instanceCheck(output?.audio, Float32Array)
+                ? output.audio
+                : new Float32Array(output?.audio ?? []);
+            return completeValue({
+                audio,
+                sampleRate: output?.sampling_rate,
+                voice: input.voice,
+            });
+        },
+        dispose: function disposeKokoroEngine() { return disposeEngine(synthesizer); },
+    });
 }
 
 function callerVoiceIds(configuration) {

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/ai/browser-decisions.md

@@ -68,9 +68,9 @@ it does not substitute a quantized graph or another model.
 | `revision` | Upstream revision, default `main`; select a stable revision when repeatable model selection is needed. |
 | `device` | Transformers.js backend, default `webgpu`; an explicit supported alternative is caller-owned. No automatic backend fallback. |
 | `dtype` | Exact upstream precision selection; defaults to `fp16` for Laya and `fp32` for Julia. For Laya FP32, supply `dtype: 'fp32'`. Unsupported selections fail at the selected upstream loader rather than being replaced. |
-| `runtime.moduleUrl` | Defaults to the self-contained CDN entry `https://cdn.jsdelivr.net/npm/@huggingface/transformers@4.3.0/dist/transformers.min.js`. The `.web.js` build expects a bundler to resolve its bare ONNX Runtime import and is unsuitable for a native module Worker. An explicit compatible public runtime URL may be supplied. |
+| `runtime.moduleUrl` | Defaults to the self-contained CDN entry `https://cdn.jsdelivr.net/npm/@huggingface/transformers@4.3.0/dist/transformers.min.js`. The `.web.js` build expects a bundler to resolve its bare ONNX Runtime import and is unsuitable for a native module Worker. An explicit compatible public runtime URL may be supplied. With `store`, the SDK stores and materializes the complete selected entry for that activation. |
 | `runtime.wasmPaths` | Optional upstream ONNX WASM location passed to the selected runtime's public environment API. |
-| `store` | Optional existing SDK DBOPFS model or speech artifact store exposing `fetchResource()`. The store remains outside Worker configuration; the SDK bridges the loader's actual resource requests to it. |
+| `store` | Optional existing SDK DBOPFS model or speech artifact store exposing `fetchResource()`. The store remains outside Worker configuration; the SDK uses it for the runtime entry and bridges the loader's actual resource requests to it. |
 
 Without `store`, the runtime, tokenizer and weights use normal upstream loading
 and caching. With `store`, the selected loader still owns filenames and model
@@ -110,17 +110,27 @@ await decisions.load();
 ```
 
 The same `store` may serve other SDK model clients. The application supplies no
-tokenizer/configuration/graph manifest and performs no file routing. Inside the
-dedicated decision Worker, Transformers.js's public `env.fetch` hook routes the
+tokenizer/configuration/graph manifest and performs no file routing. Explicit
+activation first opens `runtime.moduleUrl` through `store.fetchResource()`.
+The SDK materializes the complete stored entry as a JavaScript object URL for
+the dedicated Worker, without rewriting its content. The configured source URL
+is retained for later activations, so they reuse the same stored resource rather
+than saving a temporary object URL. Construction still starts no download.
+
+Inside the dedicated decision Worker, Transformers.js's public `env.fetch` hook routes the
 actual selected tokenizer, configuration, ONNX graph and external-data requests
 to `store.fetchResource(input, options)`. Its competing browser, custom and
 filesystem model caches are disabled only for this explicit stored mode. The
 default upstream ONNX WASM binary and factory preloads use this same hook.
 Native support-file fetches in the dedicated Worker also use the store. The
-runtime module itself still loads from `runtime.moduleUrl` through normal module
-loading. Native ESM imports remain browser-owned: an upstream custom factory
-import outside its preload path is not claimed as a DBOPFS resource. No second
-application cache or model substitution is introduced.
+default runtime entry is self-contained. Entry materialization does not rewrite
+dependency imports in custom modules or preserve their original `import.meta.url`
+base. Custom stored entries must work from an object URL; relative imports or
+support-file URLs resolved against that module's original location require a
+compatible self-contained entry. Native absolute ESM dependencies and an upstream
+custom factory import outside its preload path remain browser-owned. No second
+application cache or model substitution is introduced. Without `store`, the
+configured runtime URL keeps its direct native module-loading behavior.
 
 The store returns `{file, status, statusText, headers, url, redirected}`. The
 Worker reconstructs the complete response with its actual HTTP status and
@@ -138,9 +148,14 @@ url}`. `completed` counts closed persistent shards; `total` is `null` until the
 resource finishes. This progress carries no network-size, rate or ETA fields.
 Cancellation aborts the owned fetch and joins reader/writer cleanup before the
 resource owner becomes available to a later request. Interrupted closed shards
-are retained. `unload()` and `dispose()` still acknowledge their lifecycle
-transition synchronously; outstanding `load()`/`evaluate()` calls settle after
-their resource cleanup.
+are retained. Each activation owns its runtime object URL and revokes it after
+terminating the Worker on cancellation, failure, unload or disposal. A cancelled
+runtime-entry fetch is joined before its waiting calls settle; a late response
+cannot activate a replacement Worker. Runtime-entry HTTP failures retain the
+complete stored response in `error.response` for developer diagnostics.
+`unload()` and `dispose()` still acknowledge their lifecycle transition
+synchronously; outstanding `load()`/`evaluate()` calls settle after their
+resource cleanup.
 
 ## Complete rows and results
 

package/docs/reference/ai/browser-speech.md

@@ -1065,11 +1065,32 @@ owners. Only `'plain'` selects exact input; omission and other values retain
 the existing narration cleanup. Applications never supply the internal
 `speechInputPrepared` argument.
 
-This selection governs SDK text treatment, not the selected engine's input
-capacity or pronunciation. [Kokoro.js 1.2.1](https://github.com/hexgrad/kokoro/blob/664c76a704021239ba59c84dcbaa4d3dece01fe9/kokoro.js/src/kokoro.js)
-still tokenizes with truncation in both `generate()` and `stream()`; plain input
-does not establish complete audio for an oversized engine input. The SDK's existing complete-text forwarding
-fixture does not prove upstream synthesis completeness.
+This selection governs SDK text treatment, not pronunciation. The browser Kokoro
+adapter preserves the selected runtime's own text normalization and phonemization,
+then uses a genuine tokenizer subclass with truncation disabled. Its Kokoro
+subclass sends every resulting content token through the public
+`generate_from_ids()` method. Short inputs retain one inference; longer inputs
+use ordered segments within the selected engine's inference capacity and return
+all audio in order. This is token-based engine transport, not a character limit,
+text estimate, summary, or input discard.
+
+The [selected Kokoro model](https://huggingface.co/onnx-community/Kokoro-82M-v1.0-ONNX/blob/1939ad2a8e416c0acfeecc08a694d14ef25f2231/README.md#python)
+accepts 510 content tokens plus its two outer padding positions per inference.
+Each segment receives that padding independently. Upstream voice-style selection,
+speed, waveform generation and sample rate remain upstream-owned. The SDK reuses
+one loaded model; it does not copy the private phonemizer, replace instance methods,
+load a second model, or import another Transformers runtime. Its tokenizer
+reconstruction uses the same effective selection as the
+[Kokoro 1.2.1 factory](https://github.com/hexgrad/kokoro/blob/664c76a704021239ba59c84dcbaa4d3dece01fe9/kokoro.js/src/kokoro.js).
+That factory ignores a `revision` option; this change does not establish revision
+pinning that the upstream factory does not implement.
+
+Cancellation is request-local and checked between inference segments and before
+returning audio. As with the existing Worker contract, cancellation prevents later
+work and output while an already-running upstream inference may finish. Unload
+and disposal retain their existing Worker-termination boundary. Source and
+controlled-fixture coverage of token/audio preservation are distinct from speech
+quality or execution evidence for a particular model, browser and device.
 
 ## Choose a device or reduce memory use
 

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.1",
+  "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",
@@ -123,7 +123,7 @@
     "test": "npm run test:unit && npm run test:functional && npm run test:integration && npm run test:regression",
     "test:release": "node ./bin/arcane-test.mjs test/npm-release.test.mjs",
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/conversation-closing-report.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/native-windows-icon.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
-    "test:functional": "node ./bin/arcane-test.mjs test/ai-ollama-readiness.test.mjs test/core-ollama-lifecycle.test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-decisions.test.mjs test/browser-speech-providers.test.mjs test/browser-speech-artifacts.test.mjs test/browser-speech-resource-bridge.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-input.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/chat-transient-retention.test.mjs test/cli.test.mjs test/continuous-voice-capture.test.mjs test/codex-app-server.test.mjs test/mcp-stdio-server.test.mjs test/core-classic-source.test.mjs test/core-client.test.mjs test/core-client-installation.test.mjs test/core-ai-installation.test.mjs test/core-llama-lifecycle.test.mjs test/core-development.test.mjs test/core-host.test.mjs test/core-shared-host.test.mjs test/core-model-assets.test.mjs test/core-native-services.test.mjs test/core-packaged-web.test.mjs test/core-runtime.test.mjs test/core-stdio.test.mjs test/dbopfs-committed-events.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs-model-resources.test.mjs test/dbopfs-png.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/file-preview.test.mjs test/import-map.test.mjs test/local-image-editing.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/markdown-editor.test.mjs test/markdown-media.test.mjs test/markdown-source-map.test.mjs test/modal.test.mjs test/model-resource-bridge.test.mjs test/native-decisions.test.mjs test/native-onnx.test.mjs test/native-module-packaging.test.mjs test/native-module-resource-references.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/rendered-print.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/theme-manager.test.mjs test/twin-cloud-images.test.mjs test/twin-cloud.test.mjs test/websocket-client-import-map.test.mjs test/websocket.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
+    "test:functional": "node ./bin/arcane-test.mjs test/ai-ollama-readiness.test.mjs test/core-ollama-lifecycle.test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-decisions.test.mjs test/browser-kokoro-complete-input.test.mjs test/browser-speech-providers.test.mjs test/browser-speech-artifacts.test.mjs test/browser-speech-resource-bridge.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-input.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/chat-transient-retention.test.mjs test/cli.test.mjs test/continuous-voice-capture.test.mjs test/codex-app-server.test.mjs test/mcp-stdio-server.test.mjs test/core-classic-source.test.mjs test/core-client.test.mjs test/core-client-installation.test.mjs test/core-ai-installation.test.mjs test/core-llama-lifecycle.test.mjs test/core-development.test.mjs test/core-host.test.mjs test/core-shared-host.test.mjs test/core-model-assets.test.mjs test/core-native-services.test.mjs test/core-packaged-web.test.mjs test/core-runtime.test.mjs test/core-stdio.test.mjs test/dbopfs-committed-events.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs-model-resources.test.mjs test/dbopfs-png.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/file-preview.test.mjs test/import-map.test.mjs test/local-image-editing.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/markdown-editor.test.mjs test/markdown-media.test.mjs test/markdown-source-map.test.mjs test/modal.test.mjs test/model-resource-bridge.test.mjs test/native-decisions.test.mjs test/native-onnx.test.mjs test/native-module-packaging.test.mjs test/native-module-resource-references.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/rendered-print.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/theme-manager.test.mjs test/twin-cloud-images.test.mjs test/twin-cloud.test.mjs test/websocket-client-import-map.test.mjs test/websocket.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
     "test:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.test.mjs test/root-app-layout.test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-macos-provider.test.mjs test/native-plan.test.mjs test/native-portable-provider.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
     "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/html-import-packaged-script.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",

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})