arcane-os 0.91.0 → 0.93.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.93.0
+
+- Add native desktop notification status, submission, state and removal through
+  `Arcane.notifications`, with ordered notification state events and an owned
+  Windows adapter. The host reports actual submission and OS errors; submission
+  does not establish that a person saw or activated the notification.
+- Retain complete native document errors in the Windows host session, including
+  `window.error`, `unhandledrejection` and explicit `reportNativeError()` reports.
+  Retrieve non-consuming records through `connectAppControl().diagnostics()`
+  without foregrounding the app or waiting for Core/model readiness. Records
+  survive document navigation within that host session and end with the host.
+- Publish the matching rebuilt Windows host archive with its document-start
+  diagnostic helper. Keep ordinary console output separate from retained error
+  history; console interception and caught console arguments are outside this
+  release. Native notification behavior and application acceptance remain
+  consumer-owned verification, distinct from the selected compile and package.
+
+## 0.92.0
+
+- Add opt-in `allowUnborn` Git text snapshots and `initialBranch` repository
+  preparation for first publication from a remote with no advertised revision.
+  Repository configuration now reports the actual revision and unborn state.
+  Preserve existing checkouts, advertised refs, complete diagnostics and real
+  Git failures; first publication uses the existing explicit non-force writer.
+- Let the default Windows `git` process runner discover an installed Git for
+  Windows registration and append its command directory only to that child's
+  PATH. Existing lookup priority, other platforms, explicit executable paths
+  and custom adapters retain their behavior; no installation, global setting
+  change or command retry is introduced.
+- Reuse the retained Windows host, Whisper and ONNX runtime archives. This
+  release changes shared JavaScript repository/process behavior, not those
+  native binaries; application adoption remains independently owned.
+
 ## 0.91.0
 
 - Persist complete native `modelAssets.prepare()` acquisitions across release,

package/README.md

@@ -25,7 +25,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.91.0` SDK contract. Development applications declare
+This checkout defines the `0.93.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/core/client.mjs

@@ -646,6 +646,24 @@ export function createCoreFacade(client){
         storage:{list:()=>invoke('storage.list'),get:key=>invoke('storage.get',{key}),set:(key,value)=>invoke('storage.set',{key,value}),delete:key=>invoke('storage.delete',{key})},
         preferences:{list:()=>invoke('preferences.list'),get:key=>invoke('preferences.get',{key}),set:(key,value)=>invoke('preferences.set',{key,value}),
             setMany:entries=>invoke('preferences.setMany',{entries}),delete:key=>invoke('preferences.delete',{key})},
+        notifications: {
+            status(options) {
+                return invoke('notifications.status', {}, options).catch(function notificationStatusUnavailable(error) {
+                    if (error?.code !== 'METHOD_NOT_ALLOWED' || error?.reason !== 'core-namespace-unavailable') throw error;
+                    return {supported: false, available: false, permissionDisabled: null,
+                        reason: 'host-notifications-unavailable', error};
+                });
+            },
+            show(request, options) {
+                return invoke('notifications.show', request, options);
+            },
+            state(selection = {}, options) {
+                return invoke('notifications.state', selection, options);
+            },
+            close(selection, options) {
+                return invoke('notifications.close', selection, options);
+            }
+        },
         window: {
             state(options) {
                 return invoke('window.state', {}, {signal: options?.signal});

package/browser-runtime/core/contracts.mjs

@@ -43,6 +43,26 @@ export const CORE_METHOD_CONTRACTS={
         output: '{requestedTarget,resolvedDevice,resolution,reason}',
         meaning: 'Resolve a saved physical identity. Explicit null selects engine-owned automatic resolution; it does not claim a configured or observed device.'
     },
+    'notifications.status': {
+        input: '{}',
+        output: '{supported,available,permissionDisabled,reason?,error?}',
+        meaning: 'Actual native host support and OS permission state; no preference changes or browser/audio substitution.'
+    },
+    'notifications.show': {
+        input: '{id,title,body,data}',
+        output: 'notification-record-v1',
+        meaning: 'Submit one exact application notification. Submitted means native Show returned, not display or human receipt. Caller IDs cannot be reused during this host lifetime.'
+    },
+    'notifications.state': {
+        input: '{id?}',
+        output: '{revision,notifications:notification-record-v1[]}',
+        meaning: 'Retained complete records for this application host lifetime, including actual terminal outcomes; accepted notices survive renderer navigation.'
+    },
+    'notifications.close': {
+        input: '{id}',
+        output: 'notification-record-v1',
+        meaning: 'Remove only the exact owned notice and retain its record. Cancellation after submission does not reverse human interaction.'
+    },
     'window.state': {
         input: '{}',
         output: '{platform,supported,state}',

package/browser-runtime/core/native-diagnostics.mjs

@@ -0,0 +1,217 @@
+const NATIVE_DIAGNOSTICS_KEY = Symbol.for('arcane-os.native-diagnostics');
+const NATIVE_DOCUMENT_KEY = Symbol.for('arcane-os.app-control.document');
+
+/** Report an application-caught error to this document's native host ledger. */
+export async function reportNativeError(error, options = {}) {
+    const owner = globalThis[NATIVE_DIAGNOSTICS_KEY];
+    if (!owner) throw nativeDiagnosticsUnavailable();
+    return owner.report(error, options);
+}
+
+/** The native host installs this once, at document creation, before app scripts. */
+export function installNativeDiagnostics(global = globalThis) {
+    if (global[NATIVE_DIAGNOSTICS_KEY]) return global[NATIVE_DIAGNOSTICS_KEY];
+
+    const documentId = global[NATIVE_DOCUMENT_KEY] ??= global.crypto.randomUUID();
+    let delivery = Promise.resolve();
+    const owner = {
+        documentId,
+        ready: null,
+        report(error, options = {}) {
+            return capture('application', error, options);
+        }
+    };
+    global[NATIVE_DIAGNOSTICS_KEY] = owner;
+    global.addEventListener('error', captureWindowError);
+    global.addEventListener('unhandledrejection', captureUnhandledRejection);
+    owner.ready = transmit(envelope('document'));
+    owner.ready.catch(reportCaptureFailure);
+    return owner;
+
+    function envelope(type, record) {
+        return {
+            protocol: 'arcane.native-diagnostics/1',
+            type,
+            documentId,
+            documentUrl: global.location.href,
+            time: new Date().toISOString(),
+            ...(record === undefined ? {} : {record})
+        };
+    }
+
+    async function capture(kind, error, options = {}, observation) {
+        // Snapshot synchronously at the reported failure, before any bridge wait.
+        const record = {kind, ...encodeDiagnosticValues(error, options)};
+        if (observation !== undefined) {
+            record.location = observation.location;
+            record.message = observation.message;
+        }
+        return transmit(envelope('error', record));
+    }
+
+    function transmit(frame) {
+        // This document has one ordered ingress. A failed write is observed by
+        // its caller and does not prevent subsequent independent reports.
+        const text = JSON.stringify(frame);
+        const pending = delivery.then(async function sendDiagnostic() {
+            const windows = global.chrome?.webview?.hostObjects?.arcaneDiagnostics;
+            const webkit = global.webkit?.messageHandlers?.arcaneDiagnostics;
+            let reply;
+            if (windows) reply = await windows.Send(text);
+            else if (webkit) reply = await webkit.postMessage(text);
+            else throw nativeDiagnosticsUnavailable();
+            const result = typeof reply === 'string' ? JSON.parse(reply) : reply;
+            if (result?.accepted !== true) {
+                const error = new Error('The native host did not retain the diagnostic.', {cause: result?.error});
+                error.code = 'ARCANE_NATIVE_DIAGNOSTIC_REJECTED';
+                error.details = result;
+                throw error;
+            }
+            return result;
+        });
+        delivery = pending.catch(function observeOrderedFailure() {});
+        return pending;
+    }
+
+    function captureWindowError(event) {
+        // Resource-element load failures are a different observation boundary;
+        // this listener does not inspect their DOM or request payloads.
+        if (event.target !== global) return;
+        capture('window.error', event.error, {},
+            {message: event.message, location: {file: event.filename, line: event.lineno, column: event.colno}}
+        ).catch(function failedWindowCapture(failure) {
+            reportCaptureFailure(failure, event.error);
+        });
+    }
+
+    function captureUnhandledRejection(event) {
+        capture('unhandledrejection', event.reason).catch(function failedRejectionCapture(failure) {
+            reportCaptureFailure(failure, event.reason);
+        });
+    }
+
+    function reportCaptureFailure(failure, original) {
+        // Observe our own asynchronous failure without manufacturing another
+        // unhandled rejection. The browser's ordinary error behavior continues.
+        global.console.error('Arcane native diagnostic capture failed.', failure, original);
+    }
+}
+
+function nativeDiagnosticsUnavailable() {
+    const error = new Error('This document has no native diagnostic capture host.');
+    error.code = 'ARCANE_NATIVE_DIAGNOSTICS_UNAVAILABLE';
+    return error;
+}
+
+/**
+ * Transport-local property graph, not JSON.stringify(error). Descriptor values
+ * preserve non-enumerable Error fields, symbols, cycles and shared references.
+ * Accessors remain descriptors; inspection never calls their get/set functions.
+ * An object that rejects reflection fails the report with that original error.
+ */
+function encodeDiagnosticValues(error, options) {
+    const references = new Map();
+    const pending = [];
+    const values = [];
+    const record = {valueFormat: 'arcane.diagnostic-value/1', error: encode(error), values};
+    const details = Object.getOwnPropertyDescriptor(options, 'details');
+    if (details) {
+        record.details = Object.hasOwn(details, 'value') ? encode(details.value)
+            : {type: 'accessor', get: encode(details.get), set: encode(details.set)};
+    }
+
+    for (let index = 0; index < pending.length; index += 1) {
+        const value = pending[index];
+        const node = values[index];
+        if (typeof value === 'symbol') {
+            node.description = encode(value.description);
+            node.globalKey = encode(Symbol.keyFor(value));
+            continue;
+        }
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        node.properties = Reflect.ownKeys(descriptors).map(function describeProperty(key) {
+            return {key: encode(key), ...encodeDescriptor(descriptors[key])};
+        });
+        const prototype = Object.getPrototypeOf(value);
+        const names = prototypeNames(prototype);
+        if (names.length) node.constructorName = names[0];
+
+        // Error subclasses may supply these on a prototype, including custom
+        // accessors. Preserve the descriptor without reading through it.
+        node.inherited = [];
+        for (const key of ['name', 'message', 'stack', 'cause', 'errors', 'code', 'details']) {
+            if (Object.hasOwn(descriptors, key)) continue;
+            const descriptor = findDescriptor(prototype, key);
+            if (descriptor) node.inherited.push({key, ...encodeDescriptor(descriptor)});
+        }
+        if (names.includes('Map')) {
+            node.entries = Array.from(Map.prototype.entries.call(value), function encodeEntry([key, item]) {
+                return [encode(key), encode(item)];
+            });
+        } else if (names.includes('Set')) {
+            node.entries = Array.from(Set.prototype.values.call(value), encode);
+        } else if (names.includes('Date')) {
+            node.time = encode(Date.prototype.getTime.call(value));
+        } else if (names.includes('RegExp')) {
+            node.source = Object.getOwnPropertyDescriptor(RegExp.prototype, 'source').get.call(value);
+            node.flags = {};
+            for (const key of ['hasIndices', 'global', 'ignoreCase', 'multiline', 'dotAll', 'unicode', 'unicodeSets', 'sticky']) {
+                const getter = Object.getOwnPropertyDescriptor(RegExp.prototype, key)?.get;
+                if (getter) node.flags[key] = getter.call(value);
+            }
+        }
+    }
+    return record;
+
+    function encode(value) {
+        const type = typeof value;
+        if (value === null || type === 'string' || type === 'boolean') return value;
+        if (type === 'number') {
+            return Number.isFinite(value) && !Object.is(value, -0)
+                ? value : {type, value: Object.is(value, -0) ? '-0' : String(value)};
+        }
+        if (type === 'undefined') return {type};
+        if (type === 'bigint') return {type, value: String(value)};
+        if (!references.has(value)) {
+            const id = values.length + 1;
+            references.set(value, id);
+            pending.push(value);
+            values.push({id, type: Array.isArray(value) ? 'array' : type});
+        }
+        return {ref: references.get(value)};
+    }
+
+    function encodeDescriptor(descriptor) {
+        const result = {enumerable: descriptor.enumerable, configurable: descriptor.configurable};
+        if (Object.hasOwn(descriptor, 'value')) {
+            return {...result, value: encode(descriptor.value), writable: descriptor.writable};
+        }
+        return {...result, get: encode(descriptor.get), set: encode(descriptor.set)};
+    }
+
+    function findDescriptor(prototype, key) {
+        const visited = new Set();
+        while (prototype && !visited.has(prototype)) {
+            visited.add(prototype);
+            const descriptor = Object.getOwnPropertyDescriptor(prototype, key);
+            if (descriptor) return descriptor;
+            prototype = Object.getPrototypeOf(prototype);
+        }
+        return undefined;
+    }
+
+    function prototypeNames(prototype) {
+        const names = [];
+        const visited = new Set();
+        while (prototype && !visited.has(prototype)) {
+            visited.add(prototype);
+            const constructor = Object.getOwnPropertyDescriptor(prototype, 'constructor')?.value;
+            if (typeof constructor === 'function') {
+                const name = Object.getOwnPropertyDescriptor(constructor, 'name')?.value;
+                if (typeof name === 'string') names.push(name);
+            }
+            prototype = Object.getPrototypeOf(prototype);
+        }
+        return names;
+    }
+}

package/docs/reference/core/arcane-api.md

@@ -49,6 +49,7 @@ This inventory covers every enumerable, non-method member exposed directly or th
 | `Arcane.storage` | Namespace | App-scoped native key/value storage. |
 | `Arcane.preferences` | Namespace | App-scoped preference reads and atomic writes. |
 | `Arcane.window` | Namespace | SDK host window presentation for the calling document; adapter availability is independent of the OS-user appearance service. |
+| `Arcane.notifications` | Namespace | Native app-scoped desktop notifications and retained host-lifetime outcomes; see the [notification contract](../core-client.md#native-desktop-notifications). |
 | `Arcane.appearance` | Namespace | Native appearance state and application. |
 | `Arcane.session` | Namespace | Current Arcane session lifecycle. |
 | `Arcane.provisioning` | Namespace | Provisioning-plan operations. |
@@ -394,6 +395,37 @@ product-neutral reference.
 
 Terminal output and lifecycle changes are event-driven. The canonical [Arcane event inventory](arcane-events.md#event-inventory) defines `terminal.output`, `terminal.exit`, and the Android `terminal.error` payload. The shared `TerminalClient` adapter correlates those deliveries with owned sessions and re-emits DOM events for reusable UI code.
 
+## Native desktop notifications
+
+These methods use the actual application's native window bridge. Windows source
+support is pending selected native build and OS delivery verification. Direct
+shared-Core listeners and other unimplemented host adapters are unavailable;
+there is no browser or audio substitute. The [complete contract](../core-client.md#native-desktop-notifications)
+defines records, cancellation, duplicate IDs, permission reporting and recovery.
+
+| Method | Parameters | Return | Description |
+| --- | --- | --- | --- |
+| `Arcane.notifications.status(options?)` | `options`: standard `signal`, `timeoutMs`, `onRequest` request options | `Promise<{supported,available,permissionDisabled,reason?,error?}>` | Reports actual host support and permission state without changing preferences. Only an exact unavailable Core namespace is normalized, retaining its original complete error. |
+| `Arcane.notifications.show(request, options?)` | `request`: `{id,title,body,data}`; `options`: standard request options | `Promise<NotificationRecord>` | Submits exact title/body and opaque JSON-compatible data for the application's stable ID. Native submission is distinct from visual display or human receipt; a reused ID rejects with the existing record. |
+| `Arcane.notifications.state(selection?, options?)` | `selection`: `{id?}`, defaults to `{}`; `options`: standard request options | `Promise<{revision,notifications:NotificationRecord[]}>` | Returns complete retained records for the current host lifetime. Subscribe to `notifications.state` first and merge by revision. |
+| `Arcane.notifications.close(selection, options?)` | `selection`: `{id}`; `options`: standard request options | `Promise<NotificationRecord>` | Removes the exact owned notice and retains its record; no implicit resend or replacement. |
+
+`NotificationRecord` contains `{id,title,body,data,state,revision}` plus actual
+timestamps, reasons and complete errors. `event` identifies the latest observed
+event and `events` retains its ordered history; activation can race removal
+without changing an already `closed` state. Accepted notices survive renderer
+navigation. Terminal callbacks remain retained; timeout dismissal does not mean
+Notification Center removal. Recipients, triggers, text, deduplication and
+navigation belong to the application. Cross-process persistence and cold-start
+activation are outside this contract.
+
+Windows keeps a stable native identity per WebView profile so the OS retains
+that profile's notification preferences. The SDK persists registration metadata
+only; its notification text/data records remain in host memory. A second
+simultaneous notifier for the same profile reports
+`notification-owner-already-running`; distinct profiles remain independent.
+Live COM ownership and notices drain at host shutdown.
+
 ## Platform, installation, users, and system
 
 | Method | Parameters | Return | Description |

package/docs/reference/core/arcane-events.md

@@ -26,6 +26,31 @@ Every subscription method returns an unsubscribe function. Call it when the owni
 | `terminal.exit` | Live, future-only terminal session notification. | Core-backed Arcane Terminal and Android Arcane Terminal hosts. | A terminal process exits and the host removes its session. | `sessionId` identifies the terminal session; `exitCode` is the process exit code when available; `signal` is the terminating signal name or `null`. |
 | `terminal.error` | Live, future-only terminal session notification. | Android Arcane Terminal hosts. | Android stops a session at its output limit or cannot read one of its output streams. | `sessionId` identifies the terminal session; `message` explains the output-limit or stream-reading failure. |
 | `appearance.changed` | Live, future-only host notification. | Microsoft NT WebView2 hosts. | The host observes an operating-system appearance change. | `scheme` is the configured host scheme; `effectiveScheme` is the resolved `dark` or `light` scheme; `source` is `windows`. |
+| `notifications.state` | Live, future-only complete notification record; retained state is read separately. | SDK Windows application-window adapter; native build and OS delivery verification pending. Other unimplemented hosts and direct shared-Core listeners are unavailable. | An owned native notification changes submission, activation, dismissal, closure or failure state. | Complete `{id,title,body,data,state,revision}` record plus actual timestamps, reasons and errors. Caller `id` correlates the record; `revision` orders updates. Native submission is not a display or human-receipt acknowledgement. |
+
+### Recover native notification state
+
+Subscribe to `notifications.state` before calling `Arcane.notifications.state()`
+and merge each record by revision. The event is not a durable completion event
+for `when()`. A later renderer reads the host's retained records, including
+actual terminal outcomes; accepted notices survive navigation. Retire old-client
+subscriptions and pending snapshots when the installed client changes.
+The record's `event` names its latest observation and `events` retains complete
+ordered history. A raced `event:'activated'` can accompany `state:'closed'`;
+the application decides how to route that actual activation.
+
+Windows profile identity/shortcut registration persists across launches to
+preserve OS preferences; the SDK's notification text, data and event records
+remain in host memory for the current lifetime. A second simultaneous notifier
+for that profile is unavailable with `notification-owner-already-running`;
+other profiles are independent. Shutdown drains owned notices and live COM
+ownership.
+
+`submitted` means native `Show` returned. Later failure remains possible, and a
+timeout dismissal does not establish removal from Notification Center. Explicit
+`Arcane.notifications.close({id})` removes the owned notice while retaining its
+record. See the [complete notification contract](../core-client.md#native-desktop-notifications)
+for cancellation, permissions, exact content and host-lifetime limits.
 
 ### Subscribe and clean up
 

package/docs/reference/core-client.md

@@ -284,6 +284,105 @@ forwards the app's computed `--background` and `--text-color` in native hosts.
 Applications using that owner need no duplicate theme listener. Ordinary
 browsers keep their CSS presentation without making a native request.
 
+## Native desktop notifications
+
+`Arcane.notifications` uses the existing Core request transport to the actual
+application window's native host. The Windows adapter is source implementation;
+selected native build and actual OS delivery verification remain pending. A
+matching published host is required for delivery. The portable facade is the
+same on Windows, Linux and macOS, with Android requiring a host adapter; other
+unimplemented hosts and direct shared-Core listener connections are unavailable.
+Those listener connections bypass the window bridge. There is no browser
+`Notification`, audio or simulated delivery substitute.
+
+| Method | Parameters | Result |
+| --- | --- | --- |
+| `status(options?)` | Request options only | Actual native `supported`, `available` and `permissionDisabled`, with the host's reason/error when present |
+| `show(request, options?)` | `{id,title,body,data}` | Complete notification record for the actual submission outcome |
+| `state(selection = {}, options?)` | Optional `{id}` selects one owned ID; omission selects all retained records | `{revision,notifications:[complete records]}` |
+| `close(selection, options?)` | `{id}` | Complete record after the exact owned notice's removal operation |
+
+Every method accepts the standard `invoke` options `signal`, `timeoutMs` and
+`onRequest({requestId})`. Requests, title/body strings and opaque JSON-compatible
+`data` pass through unchanged. The application owns recipients, triggers, text,
+deduplication and navigation. The OS controls presentation; preserving the
+complete request does not establish that every character was visibly displayed.
+
+`status()` changes no OS permissions or preferences. Only the exact Core error
+`METHOD_NOT_ALLOWED` with `reason:'core-namespace-unavailable'` becomes
+`{supported:false,available:false,permissionDisabled:null,
+reason:'host-notifications-unavailable',error}`; `error` is the original complete
+error and no platform is invented. All other invocation rejections propagate
+unchanged. The native adapter can return an unavailable result with the complete
+OS initialization or settings error. `permissionDisabled:null` means the permission state is
+unknown. Use this status operation to discover the window adapter; Core's
+service capability list does not describe host-intercepted notification methods.
+Native `supported:null` means initialization could not establish OS support;
+`available:false` retains its actual reason and complete error when supplied.
+
+A retained record contains `{id,title,body,data,state,revision}` and the actual
+timestamps, reasons and complete errors supplied by its owner. `submitted` means
+the native `Show` call returned. It does not establish visible display or human
+receipt. Later activation, dismissal and failure remain observable and retained.
+A dismissal due to timeout does not establish removal from Notification Center.
+Use `close({id})` for explicit OS removal. Closing retains the record; showing
+the same caller ID again during this host lifetime rejects with its existing
+record instead of resending or replacing it.
+The top-level `event` names the latest observation, while `events` retains the
+complete ordered history. An activation racing successful removal can report
+`event:'activated'` with `state:'closed'`; the application owns action routing.
+
+The live `notifications.state` event carries one complete updated record. It is
+future-only. Subscribe before requesting the snapshot, then merge records by
+their revisions so a delayed snapshot cannot overwrite a newer event:
+
+```js
+const records = new Map();
+function receiveNotification(record) {
+    const previous = records.get(record.id);
+    if (!previous || record.revision >= previous.revision) records.set(record.id, record);
+}
+const stop = Arcane.events.on('notifications.state', receiveNotification);
+try {
+    const snapshot = await Arcane.notifications.state();
+    for (const record of snapshot.notifications) receiveNotification(record);
+} catch (error) {
+    stop();
+    throw error;
+}
+// Call stop() when this observation ends; it does not remove native notices.
+```
+
+When the installed Core client changes, detach the old event listener and ignore
+its outstanding snapshot response. Recreate the records map for the new
+client/host lifetime so an earlier host's revisions cannot suppress its records.
+Subscribe and read the new client's snapshot
+through [installation observation](#observe-installation-and-retirement).
+Accepted notices and their records survive renderer navigation within the same
+native host. There is no persisted cross-process recovery or cold-process
+activation contract.
+
+Windows reuses an SDK-created native identity and shortcut for the existing
+WebView profile across launches, preserving that profile's OS notification
+preferences. Its owned `AppUserModelId` registration stores the application's
+display name, icon and live activator identity without changing notification
+preferences or registering a cold-start launch command.
+The SDK persists registration metadata only; its notification text
+and data records remain in host memory. OS notification retention remains
+platform-owned.
+Distinct profiles have independent notification settings. One live notifier
+owns a profile's COM activation registration; a second simultaneous host using
+that profile reports `available:false` with
+`reason:'notification-owner-already-running'` and may retry explicitly later.
+Shutdown releases live COM ownership and owned notices while preserving the
+identity registration for a later launch.
+
+Cancellation observed before submission prevents that pending show from
+submitting. After submission, request cancellation or renderer retirement cannot
+reverse human interaction and does not remove the accepted notice; `close` is
+explicit. Host shutdown drains owned operations, removes owned notices and
+detaches callbacks, surfacing complete cleanup errors.
+
 ## Events and request lifetime
 
 `events.on(name, listener)`, `once(name, listener)` and

package/docs/reference/core-repositories.md

@@ -47,7 +47,7 @@ const status = await repository.status({signal});
 await repository.close();
 ```
 
-`createRepositoryWorkspace({name,directory,dataRoot,remote,remoteBase,branch,longPaths,cloneIdentity,gitIdentity,onEvent,run}={})`
+`createRepositoryWorkspace({name,directory,dataRoot,remote,remoteBase,branch,initialBranch,longPaths,cloneIdentity,gitIdentity,onEvent,run}={})`
 returns `{directory,open,status,configuration,pull,push,write,close,drain,dispose}`. The `directory`
 property is the absolute selected working path.
 
@@ -63,6 +63,10 @@ property is the absolute selected working path.
   `branch`, when supplied, is passed unchanged to Git's `clone --branch` option;
   otherwise Git selects the remote's default branch. Existing checkouts keep
   their own branch, remote, tracked files, untracked files and local changes.
+- Optional `initialBranch` names the branch for first publication from a new
+  unborn clone. It is separate from `branch`, which selects an existing remote
+  branch or tag. Omit `branch` when the remote has no advertised revision.
+  See [first publication](#first-publication-from-an-unborn-remote).
 - Supplying `remoteBase` explicitly declares this initial-clone `remote` to be
   a local filesystem locator. Its native absolute command argument is captured
   during construction. Omission leaves Git's original string interpretation
@@ -77,7 +81,11 @@ property is the absolute selected working path.
   keep Git's ordinary inheritance; existing checkouts retain their configuration.
   See [clone-local author selection](#clone-local-author-selection).
 - `onEvent` and optional `run` use the existing SDK process owner. The default
-  adapter is `runProcess`; Git must be available on PATH. Credentials and
+  adapter is `runProcess`; Git can be available on PATH or through an installed
+  Git for Windows registration. The default Windows runner appends that
+  installation's `cmd` directory only to the Git child's PATH, preserving
+  existing command lookup priority. See [Windows Git discovery](sdk-api.md#runprocess).
+  Custom `run` adapters retain their own execution behavior. Credentials and
   authentication remain with Git and the native host. The SDK adds no download,
   credential store, polling, network retry or process supervisor.
 
@@ -147,6 +155,8 @@ Its result is:
 {
     repositoryRoot,
     headRef: fullSymbolicRef | null,
+    revision: currentCommit | null,
+    unborn: boolean,
     origin: {urls: [...], pushUrls: [...]},
     upstream: {remoteNames: [...], mergeRefs: [...], urls: [...], pushUrls: [...]} | null
 }
@@ -160,6 +170,16 @@ arrays contain that branch's configured `remote` and `merge` values; `urls` and
 means the local repository and has no remote URL arrays. Origin is observed
 independently, even when it is not the upstream.
 
+`revision` and `unborn` come from Git's successful
+[porcelain-v2 branch observation](https://git-scm.com/docs/git-status#_porcelain_format_version_2):
+`(initial)` yields `revision:null, unborn:true`; a current commit yields that
+opaque revision and `unborn:false`, including a commit with an empty tree and
+detached HEAD. Symbolic HEAD alone does not establish an unborn branch.
+The command uses `--no-optional-locks` and omits untracked-file discovery, so
+this observation does not refresh the index on disk. A missing branch-state
+record reports `ARCANE_REPOSITORY_HEAD_UNAVAILABLE`; unsuccessful commands
+retain their actual failures rather than becoming an initial state.
+
 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.
@@ -172,8 +192,8 @@ 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
+documented attachment behavior. One observation uses five read-only Git
+commands for an attached local branch, or four 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.
 
@@ -212,6 +232,69 @@ observe, refresh, write and publish. See Git's [pull](https://git-scm.com/docs/g
 [push](https://git-scm.com/docs/git-push) and [configuration](https://git-scm.com/docs/git-config)
 contracts.
 
+### First publication from an unborn remote
+
+An opt-in [snapshot refresh](git-text-snapshot.md#unborn-remotes) can report
+`{revision:null,files:[],unborn:true}` after a successful complete empty remote
+advertisement. This means no revision was advertised to this connection; it
+does not assert that hidden refs or unreachable objects cannot exist.
+The application retains that explicit state instead of inventing a commit.
+
+For an application-selected new connection with that state, prepare its first
+branch without passing the existing-branch `clone --branch` option:
+
+```javascript
+const repository = createRepositoryWorkspace({
+    name: connection.name,
+    remote: connection.locator,
+    remoteBase: connection.localBaseDirectory,
+    initialBranch: 'main'
+});
+await repository.open({signal});
+const observed = await repository.configuration({signal});
+// The application matches observed.headRef, unborn and configured URLs to its connection.
+const publication = await repository.write({
+    files: selectedFiles,
+    message: authoredCommitMessage,
+    target: {remote: connection.locator, remoteBase: connection.localBaseDirectory, ref: 'refs/heads/main'},
+    signal
+});
+```
+
+`initialBranch` is captured during construction. After a successful new clone,
+the SDK observes the complete remote advertisement using the clone's original
+working-directory context and captured remote argument. Only empty successful
+output followed by the new checkout's explicit initial state and successful
+empty `git for-each-ref --format=%(refname)` observation selects
+`HEAD` as `refs/heads/<initialBranch>` through
+[Git symbolic-ref](https://git-scm.com/docs/git-symbolic-ref). Git owns branch-name
+validity. Advertised HEAD, branches or tags keep ordinary clone selection;
+an already committed clone and every existing destination remain unchanged.
+Any local ref supplied by Git's template or hook behavior is preserved and
+leaves HEAD unchanged, even when the remote advertises nothing.
+Omission adds no process and preserves the previous open result.
+
+For a new clone with `initialBranch`, `open` retains its clone `stdout`/`stderr`
+and adds ordered `outputs:[{operation,stdout,stderr,code,signal}]`. Operations
+are `clone`, `observeRemote`, `observeHead`, `observeRefs` and `selectInitialBranch`, only as
+performed. A later preparation failure preserves completed outputs in
+`error.details:{directory,cloned:true,outputs}` and the original complete
+failure as `cause`; cancellation retains completed observations too. A writer
+that prepares first retains these processes in its existing `stage:'prepare'`
+output records. Failed preparation leaves the actual directory intact and does
+not retry initialization or rename an existing checkout on the next call.
+
+There is nothing to pull before the first commit of a confirmed new unborn
+connection. Use the existing exact-file `write` and explicit non-force
+`HEAD:refs/heads/main` publication directly. For a committed remote, retain the
+ordinary selected-branch clone and targeted pull/write composition. An existing
+local checkout, different local branch or intervening remote change needs the
+application's own connection decision; an unborn observation is not permission
+to discard or switch it. Observations and publication are not transactional:
+concurrent remote changes, authentication failures and rejected pushes remain
+actual errors. No pull failure is converted into success, and no retry, force,
+rollback, global setting or fabricated revision is introduced.
+
 ### Relative local repository locators
 
 `remoteBase` is an explicit local-path choice, not a hint for a URL parser.