arcane-os 0.66.0 → 0.67.0

package/browser-runtime/ai/core-onnx.mjs

@@ -1,4 +1,4 @@
-import {getInstalledCoreClient} from '../core/client.mjs';
+import {subscribeCoreClient} from '../core/client.mjs';
 import {createArcaneEventSource} from '../event-manager.mjs';
 import {encodeTensorMap, decodeTensorMap, encodeTensorFetches} from './onnx-tensors.mjs';
 
@@ -9,16 +9,26 @@ function unavailable(message) {
 }
 
 /** Optional system ONNX access. Construction neither connects nor installs. */
-export function createCoreONNXRuntime({client = getInstalledCoreClient()} = {}) {
+export function createCoreONNXRuntime({client: suppliedClient} = {}) {
     const owner = {};
     const events = createArcaneEventSource(owner, {source: 'core-onnx', eventTypes: ['onnx.state']});
     const lifetime = new AbortController();
     const pending = new Set();
+    let client = null;
+    let connection = null;
+    let stopInstallation;
     let state = {id: 'onnx', installed: false, available: false, state: 'unknown', models: []};
     let revision = 0;
     let closed = false;
 
-    function current() { return {...state, busy: pending.size > 0, closed}; }
+    function current() {
+        const busy = [...pending].some(
+            function currentRequest(request) {
+                return request.connection === connection && !request.signal.aborted;
+            }
+        );
+        return {...state, busy, closed};
+    }
     function publish() { events.dispatch('onnx.state', current()); }
     function accept(value) {
         state = value ?? {id: 'onnx', installed: false, available: false, state: 'unavailable', models: []};
@@ -26,30 +36,66 @@ export function createCoreONNXRuntime({client = getInstalledCoreClient()} = {})
         publish();
     }
 
-    const unsubscribe = client?.events.on('localai.state', function localStateChanged(snapshot) {
-        if (!closed) accept(snapshot?.runtimes?.find(function onnxRuntime(runtime) { return runtime.id === 'onnx'; }));
-    }) ?? function noCoreSubscription() {};
+    function bindClient({client: nextClient, error = null}) {
+        if (closed || (connection && nextClient === client)) return;
+        const previous = connection;
+        client = nextClient;
+        const currentConnection = {client, controller: new AbortController(), unsubscribe: null};
+        connection = currentConnection;
+        revision += 1;
+        state = {id: 'onnx', installed: false, available: false, state: client ? 'unknown' : 'unavailable', models: [], error};
+        previous?.unsubscribe?.();
+        previous?.controller.abort();
+        if (client) {
+            currentConnection.unsubscribe = client.events.on(
+                'localai.state',
+                function localStateChanged(snapshot) {
+                    if (!closed && connection === currentConnection) {
+                        accept(snapshot?.runtimes?.find(function onnxRuntime(runtime) { return runtime.id === 'onnx'; }));
+                    }
+                }
+            );
+        }
+        publish();
+        if (!closed && connection === currentConnection && client && suppliedClient === undefined) {
+            inspect().catch(
+                function initialONNXStateUnavailable(error) {
+                    if (!closed && connection === currentConnection && !currentConnection.controller.signal.aborted) {
+                        globalThis.console?.error('Core ONNX initial state unavailable.', error);
+                    }
+                }
+            );
+        }
+    }
 
     async function invoke(method, parameters, {signal, timeoutMs = 0} = {}) {
         if (closed) throw unavailable('The Core ONNX accessor is closed.');
         if (!client) throw unavailable('Local ONNX requires an available Core connection.');
-        const request = {};
-        const operationSignal = signal ? AbortSignal.any([signal, lifetime.signal]) : lifetime.signal;
+        const currentConnection = connection;
+        const operationSignal = AbortSignal.any(
+            [lifetime.signal, currentConnection.controller.signal, ...(signal ? [signal] : [])]
+        );
+        const request = {connection: currentConnection, signal: operationSignal};
         operationSignal.throwIfAborted();
         pending.add(request);
         publish();
         try {
-            return await client.invoke(method, parameters, {signal: operationSignal, timeoutMs});
+            operationSignal.throwIfAborted();
+            const result = await currentConnection.client.invoke(method, parameters, {signal: operationSignal, timeoutMs});
+            operationSignal.throwIfAborted();
+            return result;
         } finally {
             pending.delete(request);
-            if (!closed) publish();
+            if (!closed && connection === currentConnection) publish();
         }
     }
 
     async function inspect(options) {
         const before = revision;
+        const currentConnection = connection;
         try {
             const result = await invoke('onnx.status', {}, options);
+            currentConnection.controller.signal.throwIfAborted();
             if (!closed && revision === before) accept(result);
             return current();
         } catch (error) {
@@ -61,14 +107,19 @@ export function createCoreONNXRuntime({client = getInstalledCoreClient()} = {})
     }
 
     async function load({id, model, sessionOptions, signal, timeoutMs} = {}) {
-        return invoke('onnx.load', {id, model, sessionOptions}, {signal, timeoutMs});
+        const currentConnection = connection;
+        const result = await invoke('onnx.load', {id, model, sessionOptions}, {signal, timeoutMs});
+        currentConnection.controller.signal.throwIfAborted();
+        return result;
     }
 
     async function run({id, feeds, fetches, runOptions, signal, timeoutMs} = {}) {
+        const currentConnection = connection;
         const result = await invoke('onnx.run', {
             id, feeds: encodeTensorMap(feeds),
             fetches: encodeTensorFetches(fetches), runOptions
         }, {signal, timeoutMs});
+        currentConnection.controller.signal.throwIfAborted();
         return decodeTensorMap(result);
     }
 
@@ -86,11 +137,19 @@ export function createCoreONNXRuntime({client = getInstalledCoreClient()} = {})
         if (closed) return;
         closed = true;
         lifetime.abort();
-        unsubscribe();
+        stopInstallation?.();
+        connection?.unsubscribe?.();
+        connection?.controller.abort();
         state = {...state, available: false, state: 'closed'};
         publish();
         events.dispose();
     }
 
+    if (suppliedClient === undefined) {
+        stopInstallation = subscribeCoreClient(bindClient, {signal: lifetime.signal});
+    } else {
+        bindClient({client: suppliedClient});
+    }
+
     return {load, run, unload, inspect, current, subscribe, close};
 }

package/docs/reference/README.md

@@ -70,6 +70,7 @@ alone does not make bare module names resolve in a browser.
 | Persist application-selected preferences through Core | [Core preferences service](core-preferences.md) |
 | Read complete selected Git text without changing a checkout | [Git text snapshots](git-text-snapshot.md) |
 | Own a native working checkout under per-user ArcaneData/Repos | [Native repository workspaces](core-repositories.md) |
+| Read Git identity defaults or select child-only author and credential hints | [Git identity configuration](core-repositories.md#git-identity-configuration) |
 | Write, commit and push complete selected repository text | [Selected-text repository writing](core-repositories.md#write-commit-and-push-selected-text) |
 | Build an installed-SDK portable Core payload | [Portable Core packaging](core-native-packaging.md) |
 | Pass host-selected state defaults and unchanged explicit launch values to services | [Launch-time locations](core-native-packaging.md#launch-time-locations) |

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

@@ -261,10 +261,17 @@ service exposes retained worker sessions through `onnx.load/run/unload/status`;
 model files remain caller-selected application resources. See
 [native ONNX sessions](local-ai.md#native-onnx-sessions).
 
-Selected `stable-diffusion.cpp` additionally composes
-`createLocalImageService` from `arcane-os/core/image` and one shared
-`createModelAssetService` from `arcane-os/core/model-assets`. The image factory
-receives the full authored selection plus that same model-assets instance.
+Selecting ONNX, image generation, or both composes one shared
+`createModelAssetService` from `arcane-os/core/model-assets`. Native application
+services obtain that same definition with `await context.getService('model-assets')`.
+They obtain the selected local-AI owner with `await context.getService('local-ai')`
+and its current native ONNX handle with `getONNXRuntime()`. These lookups await
+only their selected service startup, independently of renderer readiness. See
+[native service ownership and cleanup](local-ai.md#native-service-owners).
+
+Selected `stable-diffusion.cpp` additionally composes `createLocalImageService`
+from `arcane-os/core/image`. The image factory receives the full authored
+selection plus that same model-assets instance.
 Library, Koffi binding and variant paths resolve from the artifact root;
 ordinary browser imports use `arcane-os/ai/core-image` and
 `arcane-os/ai/core-model-assets` through the managed import map.

package/docs/reference/core-repositories.md

@@ -24,7 +24,8 @@ The Android host also supplies Git/process execution through the existing
 process-adapter contract; this module does not install Git or choose shared
 Android storage.
 
-The factory's first actual operation creates necessary parent directories.
+The factory's first operation that prepares a checkout creates necessary parent
+directories. The read-only `configuration` operation never prepares one.
 No existing data is moved, copied, deleted, renamed or migrated. `appRoot`,
 `stateRoot`, preferences, OPFS and the existing CLI/workspace defaults remain
 independent and unchanged.
@@ -47,7 +48,7 @@ await repository.close();
 ```
 
 `createRepositoryWorkspace({name,directory,dataRoot,remote,branch,gitIdentity,onEvent,run}={})`
-returns `{directory,open,status,pull,push,write,close,drain,dispose}`. The `directory`
+returns `{directory,open,status,configuration,pull,push,write,close,drain,dispose}`. The `directory`
 property is the absolute selected working path.
 
 - Omit `directory` to select `<repositoriesRoot>/<name>`. The application supplies
@@ -67,15 +68,17 @@ property is the absolute selected working path.
   authentication remain with Git and the native host. The SDK adds no download,
   credential store, polling, network retry or process supervisor.
 
-The open/status/pull/push methods accept `{signal}={}` and return promises;
+The open/status/configuration methods accept `{signal}={}` and return promises;
+pull/push accept `{target,signal}={}` with an optional captured destination.
 `write` accepts the complete file/message request described below:
 
 | Method | Result and side effect |
 |---|---|
 | `open` | For a missing/empty destination, runs one clone and returns `{directory,cloned:true,stdout,stderr}` with complete process output. For an existing working repository root, returns `{directory,cloned:false}` after read-only inspection. Later opens on that owner reuse preparation. |
 | `status` | Prepares the checkout if needed, then returns the existing `repositoryStatus` result unchanged. |
-| `pull` | Prepares the checkout if needed, then runs the existing clean-checkout, fast-forward-only `repositoryPull` operation unchanged. |
-| `push` | Prepares the checkout if needed, then runs the existing `repositoryPush` operation unchanged, preserving its support for unrelated uncommitted working files. |
+| `configuration` | Observes the existing working root, symbolic HEAD, origin and configured upstream. It never clones, initializes or fetches. |
+| `pull` | Prepares the checkout if needed, then runs clean-checkout, fast-forward-only `repositoryPull`, optionally using the operation's selected target. |
+| `push` | Prepares the checkout if needed, then runs `repositoryPush`, optionally using the operation's selected target, preserving support for unrelated uncommitted working files. |
 | `write` | Writes exact caller-selected text files, stages and commits only their literal paths, then performs one ordinary non-force push. Returns confirmed operation outcomes; see below. |
 | `close`, `drain`, `dispose` | The same idempotent operation: stop accepting new calls and await accepted work and its process/event cleanup. They retain the repository on disk. |
 
@@ -87,6 +90,83 @@ A failed or cancelled clone reports the actual failure; any remaining directory
 is retained for application-owned inspection. There is no automatic deletion or
 destructive retry. Filesystem failures and complete Git diagnostics propagate.
 
+## Existing checkout configuration and selected targets
+
+`configuration({signal}={})` observes an existing checkout without invoking
+`open`, creating directories, cloning, initializing, fetching or changing Git
+configuration. A missing repository reports the actual Git failure. A bare
+cache or nested checkout directory reports `ARCANE_REPOSITORY_DIRECTORY_INVALID`.
+Its result is:
+
+```text
+{
+    repositoryRoot,
+    headRef: fullSymbolicRef | null,
+    origin: {urls: [...], pushUrls: [...]},
+    upstream: {remoteNames: [...], mergeRefs: [...], urls: [...], pushUrls: [...]} | null
+}
+```
+
+`repositoryRoot` is this owner's absolute selected working root. `headRef` is
+the complete symbolic HEAD, including an unborn branch, or `null` for detached
+HEAD. `upstream` is `null` when HEAD does not name a local branch. Otherwise its
+arrays contain that branch's configured `remote` and `merge` values; `urls` and
+`pushUrls` observe the effective last configured remote name. A `.` remote
+means the local repository and has no remote URL arrays. Origin is observed
+independently, even when it is not the upstream.
+
+Arrays retain configured order, repeated values, complete UTF-8 strings and
+empty strings. `[]` means unset; `['']` means an explicit empty value. The
+reader honors configured includes and ordinary Git configuration precedence.
+Unset push URLs do not imply that Git cannot push: Git retains its normal URL
+fallback and rewrite behavior. These are configuration observations, not
+resolved endpoints, authentication, account identity or ownership proof.
+The SDK neither queries a credential helper nor changes configuration here.
+
+Metadata uses the shared raw-Git-text reader. Lifecycle/stderr events remain
+with the process owner, raw stdout remains parser-owned, and undecodable text
+reports `ARCANE_GIT_CONFIGURATION_NOT_TEXT`. Failures retain complete raw
+stdout, process diagnostics and causal errors using the identity reader's
+documented attachment behavior. One observation uses four read-only Git
+commands for an attached local branch, or three otherwise. Results are not a
+transaction with later work or external Git activity. The app owns any decision
+that the current checkout corresponds to its selected repository and branch.
+
+The optional `target:{remote,ref}` on `pull`, `push` and `write` selects that
+operation's Git destination. Both fields are nonempty strings representable by
+the native process transport. The SDK captures their exact strings when the
+call is accepted; later edits to the target object or UI selection cannot
+redirect queued or active work. Git owns ref parsing, URL interpretation,
+credentials, hooks and remote outcomes. This target is independent of the
+factory's `remote`/`branch`, which remain initial-clone inputs only.
+
+```javascript
+const observed = await repository.configuration({signal});
+// The app decides whether observed.headRef and configured URLs match its choice.
+const target = {remote: connection.locator, ref: connection.ref};
+await repository.pull({target, signal});
+const result = await repository.write({files: selectedFiles, message, target, signal});
+```
+
+A targeted pull uses `git pull --ff-only -- <remote> <ref>:`. The trailing colon
+is Git's source-only fetch framing; the fetched history is integrated into the
+current branch. It does not switch branches or reset files/history. The existing
+clean-checkout requirement remains. A targeted push uses
+`git push --no-follow-tags -- <remote> HEAD:<ref>`: current HEAD is published to
+the selected ref, without force or implicit configured tag following. Existing
+history is still sent when Git needs it. Ordinary conflicting Git settings or
+remote rejection remain actual failures; no settings are rewritten.
+
+Omitting `target` preserves ordinary configured pull/push behavior and its
+existing result shape. Targeted pull/push results add the captured `target` and
+complete `stdout`/`stderr` alongside the existing `action`, `repositoryRoot`,
+`branch` and compatibility `output` field. Writer results and failure outcomes
+add that same captured `target`. There is no hidden pre-write pull, branch
+selection, retry, reset, force, reversal or recommit. The app decides when to
+observe, refresh, write and publish. See Git's [pull](https://git-scm.com/docs/git-pull),
+[push](https://git-scm.com/docs/git-push) and [configuration](https://git-scm.com/docs/git-config)
+contracts.
+
 ## Git identity configuration
 
 ```javascript
@@ -215,7 +295,7 @@ const result = await repository.write({
 });
 ```
 
-`write({files:[{path,content}],message,signal}={})` requires at least one explicit
+`write({files:[{path,content}],message,target,signal}={})` requires at least one explicit
 file, a nonempty commit message and string content (including an empty string).
 Paths name working files relative to this repository, not its root, outside
 paths or Git-owned `.git` metadata. Strings must be representable as UTF-8;
@@ -239,9 +319,10 @@ native host.
 One `git --literal-pathspecs add -- <paths>` stages only those exact names.
 One `git --literal-pathspecs commit --only --cleanup=verbatim --file - -- <paths>`
 commits only those paths, leaving unrelated staged paths staged. The original
-message is streamed unchanged through standard input. One ordinary `git push`
-then uses that repository's existing remote/ref configuration, the optional
+message is streamed unchanged through standard input. Without `target`, one
+ordinary `git push` then uses that repository's existing remote/ref configuration, the optional
 process-local identity selection above, existing credentials and hooks.
+With `target`, the final push uses the selected current-HEAD mapping above.
 There is no implicit pull, branch switch, forced push,
 hook bypass, automatic retry, rollback or reset. If Git reports no changes to
 commit, that actual failure is returned; the SDK creates no empty commit.
@@ -252,7 +333,8 @@ Existing Git attributes, clean filters, EOL settings and hooks continue to apply
 when Git stages/commits content. The filesystem write preserves the original
 text; this API does not claim that repository-configured filters leave Git blob
 text identical. It preserves those settings. A push may also send existing history or other
-refs selected by the repository's ordinary push configuration.
+refs selected by the repository's ordinary push configuration when no explicit
+target is supplied.
 
 ### Result and failure outcomes
 
@@ -275,6 +357,8 @@ Successful completion returns:
 
 Each output record retains complete stdout/stderr. `code` and the process
 termination `signal` are included when a completed process result is available.
+When supplied, `target:{remote,ref}` is included in the result or failure outcome
+with the original accepted strings.
 An in-progress write also records its current `path` on a failure outcome.
 `writtenPaths` records successful filesystem writes in input order; `written`
 becomes true only after every requested write succeeds. The other booleans

package/docs/reference/core-runtime.md

@@ -66,11 +66,34 @@ service's startup before invoking its handler. State errors use the shared
 complete diagnostic serialization; the startup promise retains its original
 rejection value.
 
-Each lifecycle hook receives `{application, service, emit}`. Each request handler
-receives `(parameters, {application, service, emit, requestId, signal})`, with
+Each lifecycle hook receives `{application, service, emit, getService}`. Each request handler
+receives `(parameters, {application, service, emit, getService, requestId, signal})`, with
 `this` bound to its service definition. A hook or handler may publish a complete
 service-owned event through `emit(event, data)`.
 
+### Native service composition
+
+`await runtime.getService(name)` and `await context.getService(name)` return the
+actual registered service definition after that service's shared startup
+promise. A lookup can start its selected dependency before `runtime.start()`;
+it waits for that dependency alone, with no renderer, transport request or
+all-service readiness barrier. Concurrent lookups reuse the same startup and
+return the same object. Applications keep their service dependencies acyclic.
+
+Use the returned service's documented native members, such as
+[`getONNXRuntime()`](local-ai.md#native-service-owners), for same-process
+composition. RPC handlers remain owned by the dispatcher; calling entries in
+`service.methods` directly does not supply request tracking or cancellation.
+No service lookup is exposed over the browser protocol.
+
+An unregistered name rejects with `CORE_SERVICE_UNAVAILABLE`. Startup failure
+rejects with the original error. New lookups reject with `CORE_CLOSING` once
+shutdown begins; an already accepted lookup still settles with its startup.
+Lookup provides readiness, not a lifetime lease or ownership transfer. Retain
+each acquired native owner according to its own documented cleanup contract,
+and use that retained handle during disposal rather than requesting a new one.
+Independent services still dispose concurrently.
+
 ## State and frames
 
 `runtime.current()` returns dispatcher state, application, version, per-service
@@ -133,9 +156,13 @@ the handler runs. A service that does not finish or respond to cancellation is
 still unfinished; the SDK does not report a forced timeout as successful cleanup.
 
 Use `lifetime:'service'` for accepted work, such as a save, that must survive a
-renderer cancellation or disconnect. These operations are not aborted by the
-request cancellation controls or by normal Core shutdown. The service still
-owns its persistence, queueing and failure semantics.
+renderer cancellation or disconnect. The dispatcher does not abort these
+operations through request cancellation controls or its own shutdown. The
+service still owns its persistence, queueing and failure semantics. A composing
+host or native service can abort its own lifetime signal during shutdown;
+in-flight native inference can therefore be cancelled even when the dispatcher
+retains a service-lifetime response. Service lifetime does not promise survival
+of native host shutdown.
 
 `runtime.close()` is idempotent and retains the same completion promise. It stops
 accepting new requests, cancels request-lifetime operations, waits for accepted

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

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.65.0",
+  "sdkVersion": "0.66.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
@@ -164,7 +164,7 @@
       "summary": "Owns one selected native working checkout with ArcaneData/Repos defaults and existing Git/process lifecycle.",
       "availability": "Node with Git on Windows, Linux and macOS; Android requires host process adaptation",
       "protocol": "Git working repository and SDK process adapter",
-      "normalization": "Returns directory, open, status, pull, push, write and identical close/drain/dispose hooks. Only missing or empty destinations clone; existing roots are inspected without rewriting, resetting or pulling. Explicit paths remain selected. Same-directory operations serialize within the process; cancellation and shutdown join accepted process work. write snapshots exact selected text and paths, writes files, stages/commits only literal owned paths and non-force pushes, preserving unrelated staged files and ordinary Git filters. Complete outputs and causal failures retain confirmed local/committed/pushed and uncertain outcomes. Optional gitIdentity captures name/email/username for child Git operations only; omitted fields remain inherited and no config file is written."
+      "normalization": "Returns directory, open, status, configuration, pull, push, write and identical close/drain/dispose hooks. Only missing or empty destinations clone; existing roots are preserved. configuration observes the existing root, symbolic HEAD, origin URL/pushURL arrays and branch remote/merge/upstream URL arrays without clone/init/fetch, preserving unset, empty and repeated values. Explicit paths remain selected. Same-directory operations serialize within the process; cancellation and shutdown join accepted process work. pull/push/write accept a captured target {remote,ref} for current-branch fast-forward pull or non-force current-HEAD selected-ref push; omission retains ordinary configured behavior. write snapshots exact text and paths, stages/commits only literal owned paths and preserves unrelated staged files and Git filters. Complete outputs and causal failures retain confirmed local/committed/pushed and uncertain outcomes plus the supplied target. Optional gitIdentity captures name/email/username for child Git operations only; omitted fields remain inherited and no config file is written."
     },
     {
       "id": "core-repositories:readGitIdentity",
@@ -493,14 +493,14 @@
       "name": "createBrowserDecisionModel",
       "displayName": "createBrowserDecisionModel()",
       "kind": "function",
-      "signature": "createBrowserDecisionModel({family,model,revision,device,runtime})",
+      "signature": "createBrowserDecisionModel({family,model,revision,device,dtype,runtime}={})",
       "entrypoints": ["arcane-os/ai/browser-decisions"],
       "primaryImport": "arcane-os/ai/browser-decisions",
       "group": "Browser typed decisions",
-      "summary": "Explicit-load Laya FP16 and Julia-1 FP32 decisions with complete inputs and graph results.",
+      "summary": "Explicit-load Laya and Julia-1 decisions with caller-selected precision, complete inputs and graph results.",
       "availability": "Browser module Workers and the selected Transformers.js backend; import/construction starts no model load",
       "protocol": "Caller-owned state/question/options rows; five-input decision graph; native Worker request/result lifecycle",
-      "normalization": "Full field tokenization, raw logits and unrounded softmax; no policy thresholds, storage or precision fallback"
+      "normalization": "Full field tokenization, raw logits and unrounded softmax; dtype defaults to fp16 for Laya and fp32 for Julia, with explicit values forwarded unchanged to the upstream loader; no policy thresholds, storage or precision fallback"
     },
     {
       "id": "root:acceptWebSocket",
@@ -2106,13 +2106,13 @@
       "name": "repositoryPull",
       "displayName": "repositoryPull()",
       "kind": "function",
-      "signature": "async repositoryPull({ workspaceRoot=process.cwd(), signal, onEvent, run=runProcess }={})",
+      "signature": "async repositoryPull({ workspaceRoot=process.cwd(), target, signal, onEvent, run=runProcess }={})",
       "entrypoints": [
         "arcane-os"
       ],
       "primaryImport": "arcane-os",
       "group": "Workspace, doctor, repository, and server",
-      "summary": "Runs one fast-forward-only pull after proving the selected repository worktree is clean.",
+      "summary": "Runs one fast-forward-only pull into the selected clean worktree, optionally from a captured remote/ref target.",
       "availability": "Node; network-assisted Git",
       "protocol": "Node ESM",
       "normalization": "SDK-normalized inputs, errors, events, and documented result"
@@ -2122,13 +2122,13 @@
       "name": "repositoryPush",
       "displayName": "repositoryPush()",
       "kind": "function",
-      "signature": "async repositoryPush({ workspaceRoot=process.cwd(), signal, onEvent, run=runProcess }={})",
+      "signature": "async repositoryPush({ workspaceRoot=process.cwd(), target, signal, onEvent, run=runProcess }={})",
       "entrypoints": [
         "arcane-os"
       ],
       "primaryImport": "arcane-os",
       "group": "Workspace, doctor, repository, and server",
-      "summary": "Pushes the selected attached branch through the repository's configured remote and credentials.",
+      "summary": "Pushes the attached branch through ordinary configured Git or an explicit captured current-HEAD destination without force.",
       "availability": "Node; network-assisted Git",
       "protocol": "Node ESM",
       "normalization": "SDK-normalized inputs, errors, events, and documented result"

package/docs/reference/local-ai.md

@@ -174,6 +174,34 @@ This factory accepts chat/ONNX requirements; the separate
 owns image requirements. The development and generated native composition
 split the shared application record accordingly.
 
+### Native service owners
+
+A native application service uses its Core lifecycle or request context to
+obtain the existing selected owner:
+
+```js
+const localAI = await context.getService('local-ai');
+const onnx = localAI.getONNXRuntime();
+const modelAssets = await context.getService('model-assets');
+```
+
+`getService()` awaits only that service's existing startup. The synchronous
+`getONNXRuntime()` returns its actual `load/run/unload/current/subscribe/close`
+owner; it neither prepares another runtime nor loads a model. An unselected
+engine reports `LOCAL_AI_RUNTIME_NOT_SELECTED`; an unavailable or recovering
+owner reports `LOCAL_AI_RUNTIME_UNAVAILABLE`, and an aborted service lifetime
+retains its abort reason. Development and generated native compositions register
+one shared model-assets service when ONNX or image generation is selected.
+
+Reacquire `getONNXRuntime()` on each explicit model load because runtime recovery
+replaces that owner. Retain the acquired handle for that session's cleanup and
+await its `unload({id})` without an already-aborted request signal before releasing
+the corresponding model-assets retain handle. The native ONNX owner joins actual
+worker exit; a cancelled request's rejection alone does not establish that exit.
+Core closes services concurrently, and the host can cancel in-flight native work
+at shutdown. These native members require no renderer readiness and introduce no
+second inference engine. See [native Core composition](core-runtime.md#native-service-composition).
+
 `localai.status` returns `{runtimes}` and, when Ollama is selected, the existing
 `ollama` and `models.ollama` catalog fields. Runtime records distinguish
 `installed`, `available`, `state`, `models`, ownership and errors. A listening
@@ -198,6 +226,14 @@ background health polling.
 | `llama.unload` | `{model}` | Current state after release |
 | `llama.chat` | `{model,payload,stream?,streamId?}` | Complete OpenAI-shaped completion |
 
+`llama.status` and `llama.models` observe the selected service without loading,
+restarting or waiting for it. Starting, loading, stopped and failed services
+return their retained state/catalog; an available service supplies a fresh
+catalog observation. The llama.cpp runtime record includes `released: true`
+only after Core successfully closes its owned single-model server. Explicit
+load, inference or recovery can resume that engine; observation cannot.
+Status observation adds no background polling.
+
 The `payload` is the complete request. SDK option names are translated only at
 the upstream protocol boundary; messages, tool definitions and documents remain
 unchanged. An explicit `payload.model` selects that request's model. Core waits
@@ -213,7 +249,8 @@ observe load, sleep and unload changes. Direct servers expose readiness at
 request boundaries; they do not offer the router's passive model event stream.
 
 Unloading a model from an owned single-model server closes that owned process;
-a subsequent load can start it again. Releasing an externally owned direct
+a subsequent load can start it again. Repeating that unload returns the released
+state without restarting the process. Releasing an externally owned direct
 server returns `released: true, unloaded: false`, retaining the real catalog
 and leaving that server running.
 
@@ -289,6 +326,38 @@ does not install software or select a model. A missing Core connection reports
 unavailability, leaving browser Wllama/ONNX routes available for the application
 to select.
 
+Omit `client` to follow the installed Core client through
+[`subscribeCoreClient`](core-client.md): construction may precede installation.
+Each installation reads `llama.status` without selecting, downloading or loading
+a model. Retirement or replacement synchronously revokes this provider's
+`status().loaded`, cancels its owned operations and detaches the old lifecycle
+listener. Late results cannot restore the retired selection. Explicitly load
+the selection against the replacement client before inference. Passing a
+`client`, including `null`, keeps that caller-supplied connection fixed.
+
+`status()` is this provider's current state. The `arcane-ai-provider/2` contract
+does not provide a provider-state subscription, so this installation handling
+alone does not update an idle AI runtime's retained role state. The provider
+runtime still reconciles the provider at its existing operation boundaries.
+`inspect()` reports whether an explicit load can proceed, separately from
+`status().loaded`. A genuine `starting` or `loading` service without an error
+permits that load preflight even before its catalog arrives; Core's `llama.load`
+waits for startup and verifies the exact requested model. An owned, successfully
+released service permits loading only a model retained in its actual catalog.
+An available service still requires that catalog membership. These observations
+do not fabricate model records or readiness, and unavailable external services,
+closed services and actual errors remain unavailable.
+
+`dispose()` removes installation and service subscriptions and cancels owned
+operations synchronously, then attempts its actually retained model's release
+through its captured client. A configured selection alone does not own a native
+model: disposing before load or after successful unload sends no native release,
+including when the caller explicitly supplied `client: null`. A failed release
+rejects with the actual error even though the provider is disposed; disposal
+does not establish successful native unload.
+It never unloads a retired selection through a replacement client or closes the
+shared Core client.
+
 If a router evicts the primary model while serving a request-specific model,
 reload the primary selection before its next request. The provider does not
 silently change the application's saved model choice. Release registration
@@ -316,13 +385,45 @@ try {
 ```
 
 The factory accepts `{modulePath,signal?,onEvent?}` and starts no worker until
-`load({id,model,sessionOptions?,signal?})`. The model path is absolute for this
+`load({id,model,sessionOptions?,executionPreference?,signal?})`. The model path is absolute for this
 direct Node API. Session creation defaults to the CPU execution provider;
 explicit native session options remain caller-owned. The returned session
 record contains `id`, `model`, `state`, `loaded`, `error`, input/output names and
 metadata. A live ID requires explicit unload before replacement. An ID may be
 loaded again once its previous worker exits after a failed load or unload.
 A run error retains the loaded session so a corrected request can use it.
+`current().sessions[].stopping` becomes `true` when terminal shutdown begins,
+including worker failure or explicit cancellation/unload. The session is then
+unavailable for new runs even while `loaded` remains `true` until actual exit.
+A recoverable run error keeps `stopping:false` and the loaded session usable.
+`current().sessions[].exited` reports actual worker exit, independently of a
+rejected load or inference. Unload joins worker exit and output delivery even
+when requesting termination fails; complete cleanup errors remain observable.
+
+Select `executionPreference: 'gpu'` to try the installed runtime's advertised
+CUDA, TensorRT, DirectML, CoreML and WebGPU providers in that order, followed by
+CPU when no accelerator session can be created. Discovery runs once per load;
+each advertised candidate receives one actual session-creation attempt with CPU
+available for graph nodes that the accelerator cannot handle. No provider is
+downloaded by selection. The upstream `bundled` flag describes packaging and
+does not exclude separately installed CUDA or TensorRT libraries. An explicit
+`sessionOptions.executionProviders`, including an empty array, takes precedence
+and is passed unchanged without automatic discovery or retries. Automatic
+DirectML attempts default `enableMemPattern` to `false` and `executionMode` to
+`'sequential'` as required by that provider; explicit caller values remain
+unchanged, including on the final CPU attempt.
+
+Automatic GPU selection adds an `execution` record to the loaded session and
+its ordinary state events: `preference`, complete `supportedBackends`,
+`selectedProviders`, ordered `attempts` with their full errors, `fallback`, and
+`discoveryError`. Each attempt records `executionProviders`, `status`
+(`configured` or `failed`), and `error`. `fallback: true` means the SDK created
+the final CPU session after GPU preference, including when no GPU candidate was
+advertised. Successful creation establishes an accepted provider configuration;
+it does not establish that a GPU executed any graph nodes. If every attempt
+fails, the load error retains the complete attempt errors and `execution`
+record. Inference failures retain their existing behavior and do not replay
+inference on another provider.
 
 `run({id,feeds,fetches?,runOptions?,signal?})` returns the complete output-name
 map of `{type,dims,data}` tensors. Input records use that same shape with native
@@ -383,6 +484,15 @@ Closing the accessor cancels its requests and subscriptions; model unloading
 is explicit because other accessors may share the Core session. It never
 closes the shared Core client.
 
+Omitting `client` follows Core installation events with current-client replay,
+including installation after construction. Each new connection reads
+`onnx.status`; it does not install a runtime or load a model. Retirement or
+replacement immediately clears retained session readiness and cancels this
+accessor's operations. Late old-client state and results are ignored. Passing
+an explicit `client`, including `null`, retains caller ownership and does not
+follow global installation changes. `close()` also removes the installation
+subscription.
+
 Construction neither opens a connection nor installs a runtime. A browser needs
 an already available native Core service or the explicit development bridge.
 Unavailable native ONNX leaves browser ONNX/Wllama under the application's