arcane-os 0.83.1 → 0.85.0

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

@@ -1,17 +1,59 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.82.0",
+  "sdkVersion": "0.83.1",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 302,
+  "memberCount": 306,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
   },
   "members": [
+    {
+      "id": "core-model-observation:createModelObservationService",
+      "name": "createModelObservationService",
+      "displayName": "createModelObservationService()",
+      "kind": "function",
+      "signature": "createModelObservationService({runtime,localAI=null,image=null,decisions=null}={})",
+      "entrypoints": ["arcane-os/core/model-observation"],
+      "primaryImport": "arcane-os/core/model-observation",
+      "group": "Existing model observation",
+      "summary": "Observes an existing Core runtime and supplied actual native model service owners without creating or starting them.",
+      "availability": "Node with an existing Core runtime and optional existing native model services",
+      "protocol": "arcane/1 model.observation current, watch, renderer.attach and renderer.publish methods",
+      "normalization": "Returns name:model-observation, current(), dispose() and four methods. Complete current snapshots retain core, optional native localAI/image/decisions and request-owned renderer attachments. Missing owners are null; watch diagnostics defaults false and explicit true exposes complete live failed response frames for supplied native method keys without retained failure history. Actual clientRequestId identifies acknowledgements; coreRequestId keys renderer lifetime. Disposal cancels only observation requests/subscriptions, never models or the supplied runtime. No getService, readiness barrier, model creation, inference, polling or fabricated operation identities."
+    },
+    {
+      "id": "ai-model-observation:attachModelObservation",
+      "name": "attachModelObservation",
+      "displayName": "attachModelObservation()",
+      "kind": "function",
+      "signature": "attachModelObservation({client,aiRuntimeState=null,imageRuntime=null,decisionModel=null,modelController=null,signal,onError}={})",
+      "entrypoints": ["arcane-os/ai/model-observation"],
+      "primaryImport": "arcane-os/ai/model-observation",
+      "group": "Existing model observation",
+      "summary": "Attaches the application's existing renderer model owners through its existing Core client.",
+      "availability": "JavaScript with an existing Core client and optional existing renderer owners",
+      "protocol": "Request-owned model.observation.renderer attachment and complete snapshot publication",
+      "normalization": "Returns ready, closed, current() and close(). Ready acknowledges actual attachmentRequestId/coreRequestId; subscriptions publish complete current owner snapshots and reread after acknowledgement. Existing Core serialization encodes owner Error fields at the JSON boundary without changing other fields. Abort, page retirement, exact installed-client retirement, transport failure or explicit close retires only observation RPCs/subscriptions and leaves models/client owned by the caller. Normal cancellation closes cleanly; pre-acknowledgement cancellation rejects ready. Other failures reject public promises and reach onError or complete console diagnostics. No automatic reattachment, owner creation, model work or page-render barrier."
+    },
+    {
+      "id": "ai-model-observation:subscribeModelObservation",
+      "name": "subscribeModelObservation",
+      "displayName": "subscribeModelObservation()",
+      "kind": "function",
+      "signature": "subscribeModelObservation({client,signal,onState,onDiagnostic,onError}={})",
+      "entrypoints": ["arcane-os/ai/model-observation"],
+      "primaryImport": "arcane-os/ai/model-observation",
+      "group": "Existing model observation",
+      "summary": "Subscribes to complete existing model-owner snapshots and explicitly selected live Core diagnostics.",
+      "availability": "JavaScript with an existing Core client and composed observation service",
+      "protocol": "Request-owned model.observation.watch with targeted state and optional error events",
+      "normalization": "Requires onState; returns ready, closed, current() and close(). Ready resolves the first current snapshot; onDiagnostic explicitly selects diagnostics:true and receives complete correlated live failed Core response frames, without recovered history or inferred model IDs. Closing, abort, page/client retirement and transport failures retire only observation work. Normal cancellation closes cleanly; other errors reach onError and reject public promises. Callback errors close the observation while callback promises remain caller-owned. No model refresh, inference, polling, host launch, endpoint discovery, reconnect or saved conversation content."
+    },
     {
       "id": "core-app-control:connectAppControl",
       "name": "connectAppControl",
@@ -4374,7 +4416,7 @@
       "summary": "Creates an app-neutral Core dispatcher with explicit services, request lifetimes, events and graceful drain.",
       "availability": "Node on Windows, Linux and macOS native hosts; Android requires its host adaptation",
       "protocol": "arcane/1 dispatcher and service lifecycle",
-      "normalization": "Starts services independently; runtime.getService(name) and context.getService(name) return the same registered object after only its shared startup, without a renderer or global barrier. Lookup is readiness, not a lifetime lease; new lookups reject during shutdown. Preserves complete results/errors, cancels request-lifetime work and drains accepted service work; runtime.replay publishes current dispatcher/service state without restart and preserves reentrant lifecycle publication order. Missing dispatch retains METHOD_NOT_ALLOWED with exact method/namespace and core-namespace-unavailable or core-method-unavailable; named services, registered methods and built-in namespaces establish presence. Handler/startup/permission errors remain unchanged."
+      "normalization": "Starts services independently; runtime.getService(name) and context.getService(name) return the same registered object after only its shared startup, without a renderer or global barrier. Lookup is readiness, not a lifetime lease; new lookups reject during shutdown. runtime.handle(frame,{contextRequestId,contextClientRequestId}) sets requestId=contextRequestId??frame.id, clientRequestId=contextClientRequestId??contextRequestId??frame.id and coreRequestId=frame.id; omitted metadata exposes all three equal. Transports always supply the actual client ID separately, preserving the owning shared-host internal requestId contract. Internal IDs continue to own cancellation/state/event envelopes and payloads remain unchanged. Preserves complete results/errors, cancels request-lifetime work and drains accepted service work; runtime.replay publishes current dispatcher/service state without restart and preserves reentrant lifecycle publication order. Missing dispatch retains METHOD_NOT_ALLOWED with exact method/namespace and core-namespace-unavailable or core-method-unavailable; named services, registered methods and built-in namespaces establish presence. Handler/startup/permission errors remain unchanged."
     },
     {
       "id": "core-stdio:encodeCoreFrame",
@@ -4416,7 +4458,7 @@
       "summary": "Attaches an existing Core runtime to framed input and output with concurrent dispatch and graceful shutdown.",
       "availability": "Node with readable input and writable output streams",
       "protocol": "Content-Length framed arcane/1 stdio",
-      "normalization": "Returns {runtime,closed,close}; preserves queued output order, reports parser and stream failures, drains accepted runtime work on EOF and never exits the host or ends caller-owned output"
+      "normalization": "Returns {runtime,closed,close}; scopes responses/request events, cancellation and current-state replay to its connection, preserving original service-facing requestId/clientRequestId and complete payloads while coreRequestId identifies unique internal dispatch. Preserves queued output order, reports parser and stream failures, drains accepted runtime work on EOF and never exits the host or ends caller-owned output"
     },
     {
       "id": "native-portable-provider:createPortableNativeProvider",
@@ -4430,7 +4472,7 @@
       "summary": "Creates the SDK-owned provider that assembles one selected app and explicit services into a portable Core payload.",
       "availability": "Node; produces a portable payload rather than an executable host",
       "protocol": "arcane-native-builder/1 portable provider",
-      "normalization": "Preserves complete selected app and dependency releases; an explicit services selection overrides appDescriptor.native.services, otherwise the descriptor selection is used; optional appDescriptor.native.window carries positive integral logical client width/height and optional resizable into manifest.window with omitted fields preserved; reports executable:false and never substitutes for an unavailable platform host"
+      "normalization": "Preserves complete selected app and dependency releases; an explicit services selection overrides appDescriptor.native.services, otherwise the descriptor selection is used; optional appDescriptor.native.window carries positive integral logical client width/height and optional resizable into manifest.window with omitted fields preserved. Generated coreListener opt-in composes one passive model-observation service from the existing host.runtime and actual services exposing localai.status/image.status/decisions.status before listener binding, with absent owners null and renderer attachment separate. Ordinary stdio and sharedHost/headless behavior remains unchanged; no model creation, getService or readiness barrier. Reports executable:false and never substitutes for an unavailable platform host"
     },
     {
       "id": "native-portable-provider:arcaneNativeBuilderProvider",
@@ -4598,7 +4640,7 @@
       "summary": "Resolves matching per-app native state, workspace and optional shared endpoint defaults for packaged UI and external MCP.",
       "availability": "Node native locations on Windows/Linux/macOS; Android and other hosts supply stateRoot and native adaptation",
       "protocol": "Pure native launch-context resolution and existing local IPC",
-      "normalization": "Returns a new complete context with only omitted stateRoot/workspaceRoot and selected sharedHost endpoint/log fields filled; preserves explicit values and additional payloads. Native launchContext presence opts generated entry into resolution; omitted sharedHost retains stdio. No I/O, saved-state discovery, process startup, migration or ArcaneData/Repos change. Malformed selected appId/stateRoot/sharedHost inputs report TypeError; platform IPC errors remain operation-owned."
+      "normalization": "Returns a new complete context with only omitted stateRoot/workspaceRoot and selected sharedHost endpoint/log fields filled; preserves explicit values and additional payloads. Native launchContext presence opts generated entry into resolution; omitted sharedHost retains stdio. Optional coreListener:{endpoint} is preserved without endpoint defaults and attaches to that same window-owned runtime in the generated entry; selecting it together with sharedHost reports TypeError there. No I/O, saved-state discovery, process startup, migration or ArcaneData/Repos change. Malformed selected appId/stateRoot/sharedHost inputs report TypeError; platform IPC errors remain operation-owned."
     },
     {
       "id": "core-host:readCoreLaunchContext",
@@ -4628,6 +4670,20 @@
       "protocol": "arcane/1 over Content-Length framed stdio",
       "normalization": "Returns the existing {runtime,closed,close} transport owner; an optional abort signal invokes the same idempotent drain without killing the process, replacing service readiness or cancelling accepted service-lifetime work"
     },
+    {
+      "id": "core-host:startCoreListener",
+      "name": "startCoreListener",
+      "displayName": "startCoreListener()",
+      "kind": "function",
+      "signature": "startCoreListener({runtime,endpoint,onError}={})",
+      "entrypoints": ["arcane-os/core/host"],
+      "primaryImport": "arcane-os/core/host",
+      "group": "Shared Core host",
+      "summary": "Attaches local IPC to an existing window-owned Core runtime without changing its services or lifetime.",
+      "availability": "Node named pipes on Windows and Unix-domain sockets on Linux/macOS; Android requires its host adaptation",
+      "protocol": "arcane/1 over local IPC with per-connection correlation, cancellation and current-state replay",
+      "normalization": "Returns {endpoint,closed,close}; never constructs, starts or closes the supplied runtime or registers services. Explicit close flushes queued output and disconnects its clients while accepted service work remains runtime-owned. Runtime shutdown retains the endpoint through service drain then closes the listener. Preserves parameters/results/event data, original handler requestId/clientRequestId and internal coreRequestId; no host shutdown RPC. Bind errors reject startup; transport errors reach onError and terminal errors reject closed. Native launchContext.coreListener:{endpoint} selects the existing stdio branch and its existing-instance observation composition; no sharedHost/headless selection or inferred endpoint."
+    },
     {
       "id": "core-host:startSharedCoreHost",
       "name": "startSharedCoreHost",
@@ -4640,7 +4696,7 @@
       "summary": "Claims an app-selected local endpoint before composing one shared Core runtime.",
       "availability": "Node named pipes on Windows and Unix-domain sockets on Linux/macOS; Android requires its host adaptation",
       "protocol": "arcane/1 over local IPC with per-connection request correlation and current-state replay",
-      "normalization": "Returns {runtime,endpoint,closed,close}; configure(runtime,{signal}) registers independently started services after the endpoint claim. Close joins composition, accepted service work, disposal and queued frames before releasing the endpoint. Complete transport/startup/shutdown errors remain observable; an occupied endpoint never invokes the factory"
+      "normalization": "Returns {runtime,endpoint,closed,close}; configure(runtime,{signal}) registers independently started services after the endpoint claim. Preserves internal handler requestId/coreRequestId and the existing matching data.requestId adapter mapping while additive clientRequestId exposes the actual client ID independently. Other payload fields remain unchanged. Close joins composition, accepted service work, disposal and queued frames before releasing the endpoint. Complete transport/startup/shutdown errors remain observable; an occupied endpoint never invokes the factory"
     },
     {
       "id": "core-host:connectSharedCoreHost",
@@ -4654,7 +4710,7 @@
       "summary": "Connects to one selected host and optionally starts an explicit headless entry when absent.",
       "availability": "Node local IPC and optional explicit child process with diagnostic file",
       "protocol": "arcane/1 Core client; optional Node startup IPC handshake",
-      "normalization": "Returns {client,endpoint,closed,close,shutdown}. Only ENOENT/ECONNREFUSED selects start {command,args,cwd,env,logFile}; no request retry. Close cancels this connection's request work while preserving the host and accepted service work. Explicit shutdown drains all clients' shared host; cancelling a launch wait does not kill the host"
+      "normalization": "Returns {client,endpoint,closed,close,shutdown}. Only ENOENT/ECONNREFUSED selects start {command,args,cwd,env,logFile}; no request retry. Close cancels this connection's request work while preserving the host and accepted service work. Explicit shutdown drains an owning shared host for all clients; cancelling a launch wait does not kill the host. Connect to startCoreListener with start omitted; that borrowed listener implements no core.host.shutdown operation and its runtime owner retains shutdown."
     },
     {
       "id": "core-host:runSharedCoreHost",

package/docs/reference/model-observation.md

@@ -0,0 +1,220 @@
+# Existing model observation
+
+Model observation reads the existing renderer and Core owners selected by the
+application. It exposes their current lifecycle, progress, retained errors and
+actual operation identities to an explicitly selected developer observer.
+Model loading, inference, selection, cancellation and saved application state
+remain with those owners. Observation creates no model, accessor or Core runtime.
+
+## Compose the existing Core
+
+```js
+import {createModelObservationService} from 'arcane-os/core/model-observation';
+
+const observation = createModelObservationService({
+    runtime: host.runtime,
+    localAI: existingLocalAIService,
+    image: existingImageService,
+    decisions: existingDecisionService
+});
+host.runtime.registerService(observation);
+```
+
+`host` and the three services in this example are the application's existing
+instances. `localAI`, `image` and `decisions` are optional and default to `null`.
+Supply their actual service definitions, including `current()` and `methods`.
+The constructor neither looks up nor starts a service. Registration can follow
+`startCoreHost()` on its returned runtime, before opening an additional listener;
+it requires no model readiness barrier.
+
+The service is named `model-observation` and exposes `current()`, `dispose()` and
+the fixed Core methods below. `dispose()` retires only its observation requests
+and subscriptions. The host continues to own the Core and model services.
+
+An external local caller can connect through the explicitly selected
+[`startCoreListener`](core-shared-host.md) endpoint on that same runtime.
+For a packaged window, `native.launchContext.coreListener: {endpoint}` selects
+that same-runtime listener. Before binding it, the generated Core entry registers
+`model-observation` with the actual existing `services` definitions that expose
+`localai.status`, `image.status` and `decisions.status`; absent owners are `null`.
+The observer reuses those model-service owners and creates no accessor or model.
+The application supplies its renderer attachment separately.
+The observation module does not discover endpoints, launch a host, reconnect,
+change a profile, or create a second runtime. Native DOM inspection and actions
+retain their separate [app-control contract](native-app-control.md).
+
+## Attach existing renderer owners
+
+```js
+import * as aiRuntimeState from 'arcane-os/ai-runtime-state';
+import {attachModelObservation} from 'arcane-os/ai/model-observation';
+
+const attachment = attachModelObservation({
+    client: existingCoreClient,
+    aiRuntimeState,
+    imageRuntime: existingImageAccessor,
+    decisionModel: existingBrowserDecisionModel,
+    modelController: existingModelController,
+    signal: pageLifetime.signal,
+    onError: function reportObservationFailure(error) {
+        developerDiagnostics.report(error);
+    }
+});
+await attachment.ready;
+```
+
+Each optional owner defaults to `null`. Pass the instances already used by the
+application. Creating another image accessor would describe that new accessor's
+requests rather than the existing work. The supported owner methods are:
+
+| Input | Read | Subscribe |
+|---|---|---|
+| `aiRuntimeState` | `getAIRuntimeState()` | `subscribeAIRuntimeState()` |
+| `imageRuntime` | `current()` | `subscribe()` |
+| `decisionModel` | `status()` | `subscribe()` |
+| `modelController` | `status()` | `on('statechange')`, `on('progress')` |
+
+The attachment returns `{ready, closed, current, close}`. `ready` resolves with
+`{attachmentRequestId, coreRequestId}` after Core acknowledges the attachment.
+`current()` returns the latest complete renderer snapshot read by this
+attachment, or `null` when it was cancelled before reading. Subscriptions begin
+after acknowledgement; the attachment then reads and publishes current state
+again to cover changes during that handshake.
+
+Caller abort, `pagehide`, retirement of the exact installed Core client,
+transport failure, or `close()` removes the observation subscriptions and
+cancels only this attachment's observation RPCs. A supplied client remains
+caller-owned. The attachment never follows a replacement client or automatically
+reattaches. Native document retirement also cancels its long-lived Core request.
+Core then removes the renderer record; late publication to that retired
+attachment fails honestly. Detachment does not unload or cancel a model.
+
+`close()` returns `closed`, which settles after the attachment's observation
+RPC promises settle locally. It does not claim that a remote model or host has
+closed. Transport and observation errors remain available through `onError`
+and the rejected public promises. With `onError` omitted they reach the developer
+console. Normal cancellation, including cancellation initiated by the existing
+client or native document owner, closes observation without a model error. When
+cancellation precedes acknowledgement, `ready` rejects with the cancellation
+while `closed` resolves after the observation RPCs settle.
+
+## Read or subscribe from an existing client
+
+```js
+import {subscribeModelObservation} from 'arcane-os/ai/model-observation';
+
+const current = await client.invoke('model.observation.current', {}, {signal});
+const observation = subscribeModelObservation({
+    client,
+    signal,
+    onState: function showRetainedOwners(snapshot) {
+        developerDiagnostics.show(snapshot);
+    },
+    onDiagnostic: function showModelFailure(record) {
+        developerDiagnostics.report(record);
+    },
+    onError: function showObservationFailure(error) {
+        developerDiagnostics.report(error);
+    }
+});
+await observation.ready;
+```
+
+`onState` is required. The returned `{ready, closed, current, close}` has the same
+observation-only lifecycle as the renderer attachment. `ready` resolves with
+the first current-state replay; `current()` holds the latest complete snapshot,
+initially `null`. `onDiagnostic` explicitly selects live correlated Core model
+failure frames. Omitting it requests state observation only. Callback failures
+close that observation and reach `onError`; callback promises remain
+caller-owned and may await `close()` without becoming its completion barrier.
+
+Every snapshot is:
+
+```js
+{
+    core: existingCoreRuntime.current(),
+    native: {localAI, image, decisions},
+    renderers: [{attachmentRequestId, coreRequestId, owners: {
+        aiRuntimeState, imageRuntime, decisionModel, modelController
+    }}]
+}
+```
+
+The values represent complete supplied-owner snapshots. Absent optional owners
+are `null`; absent renderer attachments produce an empty array. Core state also
+contains its real active observation requests, identified by their actual
+methods, alongside other active requests. Observation does not relabel them as
+model work. Snapshots are current observations of independent owners, rather
+than an atomic transaction across all owners.
+
+## Fixed transport and correlation
+
+| Method/event | Contract |
+|---|---|
+| `model.observation.current` | Empty parameters; returns the current snapshot without model refresh or readiness waits. |
+| `model.observation.watch` | `{diagnostics:false}` by default; remains pending until cancellation. |
+| `model.observation.state` | Targeted watch event `{watchRequestId,snapshot}`; the first event acknowledges the watch and replays current state. |
+| `model.observation.error` | Targeted diagnostic `{watchRequestId,source:'core',method,frame}` preserving the complete original failed response frame. |
+| `model.observation.renderer.attach` | `{snapshot}`; remains pending to own the renderer publication lifetime. |
+| `model.observation.renderer.attached` | Targeted acknowledgement `{attachmentRequestId,coreRequestId}`. |
+| `model.observation.renderer.publish` | `{attachmentRequestId,coreRequestId,snapshot}`; replaces that attachment's current snapshot and returns both attachment identities. |
+
+Both helpers register listeners before invoking. Existing
+[`client.invoke`](core-client.md) supplies `onRequest({requestId})` before send;
+long-lived observation requests use `timeoutMs:0`. Their acknowledgement is a
+targeted request event, while the invocation promise remains pending.
+
+`attachmentRequestId` and `watchRequestId` are the actual client-visible Core
+request identities supplied by service context `clientRequestId`.
+`coreRequestId` is the actual internal Core frame identity;
+renderer attachments are keyed by that value so clients with identical local
+request IDs cannot collide. The renderer echoes both values when publishing.
+`snapshot.core.activeRequests[].id` and diagnostic `frame.id` use internal Core
+identities. They can differ from client-visible IDs under connection routing.
+None of these observation/transport IDs is a model-operation ID.
+
+Core supplies both metadata fields for direct runtime calls, stdio connections,
+`startCoreListener()` connections and the existing `startSharedCoreHost()` path.
+Each connection preserves the original incoming request ID as `clientRequestId`
+independently of its established `requestId` mapping. Direct calls use the
+incoming frame ID for both identities. Observation requires these actual
+context fields; it does not infer them from `requestId` or rewrite event
+payloads to manufacture correlation.
+
+The exact `methods` keys on the supplied native service definitions select the
+Core operations whose live failures can be observed. The observer tracks their
+actual active request IDs while a watch exists. Core publishes request removal
+before emitting its response; the observer retains that correlation until the
+response arrives, then removes it. Removing the final watcher releases frame
+observation and remaining transient correlation. It retains no failure history.
+
+## Evidence and lifecycle limits
+
+- AIRuntimeState exposes its existing llm/stt/tts records, including the reported
+  operation ID. Its retained errors contain only code/message. Concurrent role
+  work is not a complete request enumeration in this snapshot.
+- The existing image accessor exposes its own active method, stream ID, status
+  and progress records. Its retained error is preserved; that error has no
+  reliable explicit stream association. Constructor-only diagnostic callbacks
+  cannot be retroactively attached through this API.
+- Browser and native decision snapshots retain their existing errors and active
+  request counts. A count does not supply missing per-evaluation IDs.
+- ModelController status exposes its existing state/progress and code/message
+  error. Its load/unload event IDs are not retained by `status()`, and are not
+  presented as inference IDs or reconstructed history here.
+- Core supplies its real active request identities and complete live failed
+  response frames. A watch cannot recover responses that settled before it
+  observed them. Retained owner errors remain available in current snapshots.
+
+Renderer `Error` values in owner error fields use the existing Core error
+serializer at the JSON boundary; other owner fields remain unchanged. A value
+the selected transport cannot encode fails through the observation error path
+rather than being replaced with shortened or invented content. Observation
+does not alter model inputs, outputs, prompts or their persistence policy.
+
+The shared JavaScript contract is portable wherever the existing Core client
+and supplied owners are available. Endpoint and native-host availability belong
+to their documented adapters. Developer observation remains separate from
+ordinary user status, app-owned stage/avatar association and actual model
+execution verification. This capability does not establish that an inference
+failure has been corrected.

package/docs/reference/sdk-api.md

@@ -55,6 +55,8 @@ runtime layouts.
 | `arcane-os/core/contracts` | Shared Core protocol, frame, method and diagnostic error contracts. |
 | `arcane-os/core/classic-source` | Node generator for the canonical classic-script Core client projection. |
 | `arcane-os/core/runtime` | App-neutral native Core dispatcher and service lifecycle. |
+| `arcane-os/core/model-observation` | Passive observation of an existing Core and its actual native model service owners. |
+| `arcane-os/ai/model-observation` | Attach existing renderer model owners and subscribe through an existing Core client. |
 | `arcane-os/core/development` | App-service composition and document-owned Core transport during source development, independently of local AI. |
 | `arcane-os/core/stdio` | Framed Node stdio transport with graceful runtime drain. |
 | `arcane-os/core/host` | Node-only reusable Core host lifecycle, app-selected native launch defaults and shared native location resolution. |
@@ -420,6 +422,9 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 | `McpProtocolError` | class | `arcane-os/mcp/stdio` | MCP STDIO | Node |
 | `createCoreClassicSource()` | function | `arcane-os/core/classic-source` | Core classic client projection | Node; generated source runs in browser and native WebView renderers |
 | `createCoreRuntime()` | function | `arcane-os/core/runtime` | Native Core runtime | Node on Windows, Linux and macOS native hosts; Android requires host adaptation |
+| `createModelObservationService()` | function | `arcane-os/core/model-observation` | Existing model observation | Node with an existing Core runtime and optional existing native model services |
+| `attachModelObservation()` | function | `arcane-os/ai/model-observation` | Existing model observation | JavaScript with an existing Core client and optional existing renderer owners |
+| `subscribeModelObservation()` | function | `arcane-os/ai/model-observation` | Existing model observation | JavaScript with an existing Core client and composed observation service |
 | `encodeCoreFrame()` | function | `arcane-os/core/stdio` | Native Core stdio transport | Node |
 | `createCoreFrameDecoder()` | function | `arcane-os/core/stdio` | Native Core stdio transport | Node |
 | `startCoreStdio()` | function | `arcane-os/core/stdio` | Native Core stdio transport | Node |
@@ -427,6 +432,7 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 | `arcaneNativeBuilderProvider` | singleton | `arcane-os/native/portable-provider` | Portable native provider | Node; produces a portable payload rather than an executable host |
 | `arcaneNativeBuilderProvider default export` | singleton | `arcane-os/native/portable-provider` | Portable native provider | Node; produces a portable payload rather than an executable host |
 | `startCoreHost()` | function | `arcane-os/core/host` | Native Core host composition | Node with readable input and writable output streams |
+| `startCoreListener()` | function | `arcane-os/core/host` | Shared Core host | Node local IPC attached to an existing runtime |
 | `startSharedCoreHost()` | function | `arcane-os/core/host` | Shared Core host | Node local IPC on Windows, Linux and macOS |
 | `connectSharedCoreHost()` | function | `arcane-os/core/host` | Shared Core host | Node local IPC and optional explicit headless startup |
 | `connectAppControl()` | function | `arcane-os/core/app-control` | Native application control | Node local IPC; current window adapter is Windows WebView2 |
@@ -7394,6 +7400,18 @@ Import it from `arcane-os/core/runtime`. The runtime exposes `current()`,
 `subscribe()`, `onFrame()`, `emit()`, `registerService()`, `getService()`, `start()`, `handle()`
 and idempotent `close()`.
 
+`runtime.handle(frame, {contextRequestId, contextClientRequestId})` accepts
+optional nonempty transport metadata strings. Handler `requestId` remains
+`contextRequestId ?? frame.id`; additive `clientRequestId` is
+`contextClientRequestId ?? contextRequestId ?? frame.id`; `coreRequestId` always
+exposes the actual internal `frame.id`. Direct `handle(frame)` exposes all three
+equal. Stdio and both IPC paths supply the actual client identity separately,
+preserving the owning shared-host adapter's established internal `requestId`.
+Active requests, cancellation, response IDs and request-event envelopes retain
+the internal ID. Parameters, results and event data stay unchanged; transports
+own client-facing protocol correlation. See
+[the runtime contract](core-runtime.md#state-and-frames).
+
 `await runtime.getService(name)` and service `context.getService(name)` return
 the actual registered service after its shared startup. They wait for that
 dependency alone, may start it before `runtime.start()`, and add no renderer or
@@ -7551,6 +7569,13 @@ Import it from `arcane-os/core/stdio`. The result is
 `{runtime, closed, close}`. EOF or input close starts graceful shutdown;
 `closed` settles only after accepted runtime work and queued output settle.
 
+Responses, request events, cancellation controls and current-state replay are
+connection-scoped even when an additional IPC listener shares the runtime.
+Stdio preserves original handler `requestId` values while routing fresh internal
+IDs; uncorrelated service events remain shared. EOF retains its existing
+runtime-wide shutdown ownership. Additional clients attach through
+[`startCoreListener()`](#startcorelistener).
+
 ### Availability and normalization
 
 **Node with readable input and writable output streams.** Parser, input, output
@@ -7572,6 +7597,80 @@ const transport = startCoreStdio({runtime});
 await transport.closed;
 ```
 
+## createModelObservationService()
+
+```text
+createModelObservationService({runtime,localAI=null,image=null,decisions=null}={})
+```
+
+Import from `arcane-os/core/model-observation`. Supply the existing Core runtime
+and actual native service definitions, including their `current()` and `methods`.
+Returns `{name:'model-observation',current,dispose,methods}`. Register it on that
+runtime after ordinary host creation and before opening an additional listener.
+Construction starts no service, model, worker or readiness wait.
+
+The four methods are `model.observation.current`, `model.observation.watch`,
+`model.observation.renderer.attach` and `model.observation.renderer.publish`.
+`current()` returns `{core,native:{localAI,image,decisions},renderers}` from the
+supplied owners. Absent model owners are `null`; absent attachments produce `[]`.
+The watch replays current state and remains pending until cancellation. Its
+`diagnostics:false` default excludes live failure frames; explicit `true`
+observes complete failed Core responses for the supplied owners' method keys.
+It retains no failure history and invents no model-operation identities.
+
+Renderer attachment and watch acknowledgements use actual `clientRequestId`;
+attachments are keyed by the actual `coreRequestId` to distinguish clients with
+equal local IDs. `dispose()` retires observation requests/subscriptions only.
+Core still owns model services and shutdown. See
+[complete methods, events and evidence limits](model-observation.md).
+
+## attachModelObservation()
+
+```text
+attachModelObservation({client,aiRuntimeState=null,imageRuntime=null,decisionModel=null,modelController=null,signal,onError}={})
+```
+
+Import from `arcane-os/ai/model-observation`. Pass the existing Core client and
+the application-owned instances already doing the work. Supported owner methods
+are AIRuntimeState's `getAIRuntimeState/subscribeAIRuntimeState`, image runtime's
+`current/subscribe`, decision model's `status/subscribe`, and ModelController's
+`status/on`. It creates no replacement owner or transport.
+
+Returns `{ready,closed,current,close}`. `ready` resolves with the Core-supplied
+`{attachmentRequestId,coreRequestId}` acknowledgement. Subscriptions then publish
+complete current owner snapshots, including a fresh read after acknowledgement.
+`current()` returns the latest renderer snapshot, initially `null`. The existing
+Core error serializer represents owner `Error` fields at the JSON boundary;
+other fields remain unchanged.
+
+Caller abort, page retirement, retirement of the exact installed client,
+transport failure or `close()` retires only observation RPCs/subscriptions.
+`close()` returns `closed`; it never closes the supplied client or unloads models.
+Normal cancellation closes cleanly; cancellation before acknowledgement rejects
+`ready`. Other errors reject public promises and reach `onError`, defaulting to
+complete console diagnostics. A replacement client requires a new explicit
+attachment. Keep attachment readiness independent of page rendering. See
+[renderer ownership and lifecycle](model-observation.md#attach-existing-renderer-owners).
+
+## subscribeModelObservation()
+
+```text
+subscribeModelObservation({client,signal,onState,onDiagnostic,onError}={})
+```
+
+Import from `arcane-os/ai/model-observation`. Requires an existing client and
+`onState`; returns `{ready,closed,current,close}`. `ready` resolves with the first
+current-state snapshot and `current()` retains the latest snapshot, initially
+`null`. Providing `onDiagnostic` explicitly selects live complete correlated Core
+model failure frames; omission selects state only. These are developer
+diagnostics, not ordinary user status or saved conversation content.
+
+The observer uses the same observation-only cancellation/error lifecycle as
+the attachment. Callback failures retire it and reach `onError`; callback
+promises may await `close()` without becoming its completion barrier. It starts
+no model, refresh, polling, endpoint discovery, host or reconnect. See
+[observation records and limits](model-observation.md#read-or-subscribe-from-an-existing-client).
+
 ## createPortableNativeProvider()
 
 ### Overview
@@ -7605,6 +7704,13 @@ published SDK/runtime dependencies and the canonical Core entry/client into a
 fresh output directory. Service factories are imported only when a real native
 host later launches the generated Core entry, never during packaging.
 
+Explicit `native.launchContext.coreListener:{endpoint}` also composes one passive
+model observation service after `startCoreHost()` and before listener binding,
+using that runtime and existing services exposing `localai.status`, `image.status`
+and `decisions.status`. Missing owners remain `null`; renderer attachment stays
+application-owned. Ordinary stdio and shared/headless branches gain no model
+startup or readiness barrier. See [native observation composition](core-native-packaging.md#launch-time-locations).
+
 An optional `appDescriptor.native.window` record carries `width`, `height` and
 `resizable` into `manifest.window`. Dimensions are positive integral logical
 client units; `resizable` is an optional boolean. Omitted fields remain omitted.
@@ -7995,6 +8101,14 @@ the caller's working-directory meaning. `appId` and the selected state path
 must be nonempty strings; a selected `sharedHost` must be an object. Malformed
 inputs report `TypeError`; native endpoint failures belong to the IPC operation.
 
+`native.launchContext.coreListener:{endpoint}` instead attaches local IPC to
+the existing window/stdio runtime. Its endpoint remains explicit and receives
+no default. The generated entry rejects simultaneous `coreListener` and
+`sharedHost` selections. Client disconnect affects that connection; window
+shutdown still drains Core and closes the additional listener. See
+[`startCoreListener()`](#startcorelistener) and
+[native launch locations](core-native-packaging.md#launch-time-locations).
+
 ```javascript
 import {resolveNativeLaunchContext} from 'arcane-os/core/host';
 
@@ -8793,6 +8907,62 @@ async function bundleMoonCheeseRuntime(outputRoot){
 The ordinary provider invokes this owner only for an explicit native local-AI
 selection. See [selected local-AI runtimes](core-native-packaging.md#selected-local-ai-runtimes).
 
+## startCoreListener()
+
+### Overview and signature
+
+Attaches a local IPC listener to an existing Core runtime, without creating,
+starting or taking ownership of that runtime or its services.
+
+```text
+startCoreListener({runtime,endpoint,onError}={})
+```
+
+Import from `arcane-os/core/host`. Resolves `{endpoint,closed,close}` after the
+selected endpoint binds. `close()` is idempotent, cancels the listener's
+request-lifetime work, flushes queued output and closes its connections. It
+does not call `runtime.close()` or wait for accepted service-lifetime work;
+that work remains tracked by the existing runtime. Runtime shutdown rejects
+new listener requests, retains the endpoint through service drain/disposal,
+and closes the listener automatically. Observe both owners' `closed` promises.
+Bind errors reject startup without closing the supplied runtime. Transport
+errors reach `onError`, with complete console diagnostics by default; terminal
+listener errors reject `closed`. Attaching to a draining/closed runtime reports
+`CORE_CLOSING`.
+
+Node supports named pipes on Windows and Unix-domain sockets on Linux/macOS;
+Android requires its host adaptation. Supply a nonempty endpoint and an existing
+parent directory where required. Connect with `connectSharedCoreHost({endpoint})`
+and omit `start`. Its current-runtime replay does not replay requests. The
+borrowed listener implements no `core.host.shutdown` operation; use client
+`close()` for disconnection and the existing runtime's owner for host shutdown.
+
+Each connection owns response/event correlation and request cancellation.
+Handler `requestId` and `clientRequestId` preserve the client ID; `coreRequestId` is the distinct
+internal dispatch ID. Parameters, results and event data, including
+`data.requestId`, remain unchanged. Runtime-state snapshots retain internal
+active IDs; no service event is invented or retained for later replay.
+
+```js
+import {startCoreListener} from 'arcane-os/core/host';
+
+const listener = await startCoreListener({runtime: host.runtime, endpoint: selectedEndpoint});
+try {
+    await host.closed;
+} finally {
+    await listener.close();
+}
+```
+
+`host` is the application's existing stdio host. Generated native entries
+select this attachment with `native.launchContext.coreListener:{endpoint}`,
+preserving their actual runtime, service set, profile, origin and state root.
+That generated opt-in registers the passive observation service from existing
+native model owners before binding; direct `startCoreListener()` itself never
+registers services. Renderer owners are attached separately by the application.
+Omit `sharedHost`; the two options describe alternative lifetimes. Full
+contract: [existing-runtime listener](core-shared-host.md#attach-to-an-existing-window-owned-core).
+
 ## startSharedCoreHost()
 
 ### Overview
@@ -8817,6 +8987,11 @@ service-owned. The supplied signal begins the same shutdown. `closed` rejects
 on shutdown failure; `onError` observes transport/background failures, with
 complete console diagnostics by default.
 
+The owning adapter preserves its existing internal handler `requestId`, equal
+to `coreRequestId`, and its matching `data.requestId` compatibility mapping.
+Additive `clientRequestId` exposes the original client ID independently; other
+parameters, results and event data remain unchanged.
+
 ### Availability and example
 
 Node supports app-selected named pipes on Windows and Unix-domain sockets on
@@ -8871,6 +9046,12 @@ not kill a host another client may use. No startup timeout is imposed; supply
 before disconnecting. It affects every client; cancellation after acceptance
 does not reverse it. A drain failure returns the full Core error.
 
+The same connector can attach to `startCoreListener()` with `start` omitted.
+There, `close()` still disconnects only this client, and `shutdown()` has no
+listener-owned operation: absent an application method of that name, the
+ordinary dispatcher returns `METHOD_NOT_ALLOWED`. The existing window/runtime
+owner remains responsible for shutdown.
+
 ```js
 import {connectSharedCoreHost} from 'arcane-os/core/host';
 
@@ -8967,9 +9148,10 @@ stdio-owned Core lifetime. See [native shared-host launch](core-shared-host.md#n
 
 ## startCoreHost()
 
-For independent UI and MCP processes sharing one application runtime, use the
-[shared host functions](#startsharedcorehost) above. Ordinary `startCoreHost()`
-retains its existing stdio-owned lifetime.
+For an external client of the actual window-owned runtime, attach
+[`startCoreListener()`](#startcorelistener) to `host.runtime`. For an explicitly
+independent headless lifetime, use the [shared host functions](#startsharedcorehost).
+Ordinary `startCoreHost()` retains its existing stdio-owned lifetime.
 
 ### Overview