arcane-os 0.91.0 → 0.93.0

package/docs/reference/git-text-snapshot.md

@@ -4,8 +4,11 @@
 from one fetched Git revision. It uses a dedicated **bare object cache**, not a
 clone with a working checkout. It never reads uncommitted application files,
 checks out files, modifies a user checkout/index, or creates another worktree.
-Construction performs no I/O. The native host needs Git available on its PATH;
-Git owns remote access, authentication and its actual failures.
+Construction performs no I/O. The native host needs Git available on its PATH
+or an installed Git for Windows registration discoverable by the default
+[process runner](sdk-api.md#runprocess). Discovery extends only that Git child's
+PATH after its existing entries. Git owns remote access, authentication and
+its actual failures; custom process adapters retain their own execution.
 
 ```js
 import {createGitTextSnapshot} from 'arcane-os';
@@ -33,7 +36,7 @@ policy stable for the lifetime of its snapshot owner.
 
 ## API and lifecycle
 
-`createGitTextSnapshot({cacheDirectory,remote,remoteBase,ref,selectPath,gitIdentity,onEvent,run})`
+`createGitTextSnapshot({cacheDirectory,remote,remoteBase,ref,selectPath,allowUnborn=false,gitIdentity,onEvent,run})`
 returns `{refresh,close,drain,dispose}`. `run` defaults to the SDK's existing
 `runProcess`; applications normally omit it. It is the same process adapter
 contract, not a second process supervisor. `onEvent` is the ordinary SDK event
@@ -91,6 +94,47 @@ application owner; this factory does not install a daemon or cross-process lock.
 An empty cache is initialized once. An existing non-bare checkout is rejected
 without repurposing it. The cache is retained when the owner closes.
 
+## Unborn remotes
+
+Optional `allowUnborn:true` adds an explicit no-advertised-revision state:
+
+```javascript
+const snapshot = createGitTextSnapshot({
+    cacheDirectory: applicationCacheDirectory,
+    remote: applicationRepository,
+    ref: 'refs/heads/main',
+    selectPath: applicationSelectPath,
+    allowUnborn: true
+});
+const observed = await snapshot.refresh({signal});
+// Empty advertisement: {revision: null, files: [], unborn: true}.
+// Selected commit: {revision: actualCommit, files: selectedText, unborn: false}.
+```
+
+Each opted-in acquisition first completes unfiltered
+`git ls-remote --symref -- <remote>` with the same captured locator and identity.
+Only successful empty stdout produces the explicit unborn result. No revision
+is invented and no fetch, tree listing or blob process runs on that path.
+The [Git remote advertisement](https://git-scm.com/docs/git-ls-remote) is scoped
+to refs visible to that connection, not hidden refs or unreachable objects.
+
+Any advertised HEAD, branch, tag or other output continues through the ordinary
+selected-ref fetch and commit resolution. A missing selected ref on a populated
+remote remains a Git failure. Failed observations, authentication/transport
+errors and stderr wording never establish an unborn result. A real commit with
+an empty tree or zero selected files retains its actual revision and
+`unborn:false`. Omitting the boolean, or supplying `false`, preserves the
+previous `{revision,files}` result and command sequence without a remote probe.
+
+Bare-cache role discovery still precedes remote observation. Every later
+refresh observes again, so prior empty or committed results cannot hide a
+changed remote or a failure. Caller cancellation, shared acquisition, independent
+result copies and drain remain unchanged. Opted-in completion events add
+`unborn`; `revision:null` and `unborn:true` describe the explicit empty state.
+This option adds one remote command per acquisition; existing revision-based
+text reuse still applies to committed results. For writing the first commit,
+see [first-publication composition](core-repositories.md#first-publication-from-an-unborn-remote).
+
 ## Complete text and observable failures
 
 Content is the exact Git blob text, including whitespace, CRLF, newlines,

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

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.90.0",
+  "sdkVersion": "0.92.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
@@ -311,14 +311,14 @@
       "name": "createRepositoryWorkspace",
       "displayName": "createRepositoryWorkspace()",
       "kind": "function",
-      "signature": "createRepositoryWorkspace({name,directory,dataRoot,remote,remoteBase,branch,longPaths,cloneIdentity,gitIdentity,onEvent,run=runProcess}={})",
+      "signature": "createRepositoryWorkspace({name,directory,dataRoot,remote,remoteBase,branch,initialBranch,longPaths,cloneIdentity,gitIdentity,onEvent,run=runProcess}={})",
       "entrypoints": ["arcane-os/core/repositories"],
       "primaryImport": "arcane-os/core/repositories",
       "group": "Native repository workspaces",
       "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, configuration, pull, push, write and identical close/drain/dispose hooks. Only missing or empty destinations clone; existing roots are preserved. Optional factory remoteBase explicitly selects the initial-clone remote as a local filesystem locator and captures path.resolve(remoteBase, remote) once at construction. A relative base, including an empty string, uses the construction-time working directory. Only the Git argument is derived; the caller's original locator remains unchanged. Omission preserves every Git remote name, URL, SCP-like address and remote-helper string without guessed parsing. Optional longPaths captures a boolean: explicit Windows true/false supplies clone-local core.longpaths before the first checkout, persisting only in the new repository under ordinary Git configuration precedence. Omission preserves configuration; existing repositories and non-Windows clone commands remain unchanged. No global setting or migration. 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,remoteBase?} for current-branch fast-forward pull or non-force current-HEAD selected-ref push; omission retains ordinary configured behavior. An operation's own remoteBase declares local-path intent and captures its native absolute argument once at acceptance, before queueing; factory remote/remoteBase/branch remain independent clone inputs. Targeted pull/push results and writer results/failure outcomes retain the original remote, ref and supplied remoteBase, including relative or empty base text. Unrepresentable base text reports TypeError without transformation. 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 identity selection writes no config file. Optional cloneIdentity captures exact name/email strings and persists only supplied fields through clone --config before the first checkout on every supported platform. Empty strings are explicit; omitted or undefined fields preserve inherited/template configuration. Existing checkouts are never reconfigured. Unrepresentable process arguments fail honestly without transforming them. This option changes no global configuration or credentials and does not identify an authenticated account; command-local gitIdentity remains independent."
+      "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. Optional factory remoteBase explicitly selects the initial-clone remote as a local filesystem locator and captures path.resolve(remoteBase, remote) once at construction. A relative base, including an empty string, uses the construction-time working directory. Only the Git argument is derived; the caller's original locator remains unchanged. Omission preserves every Git remote name, URL, SCP-like address and remote-helper string without guessed parsing. Optional longPaths captures a boolean: explicit Windows true/false supplies clone-local core.longpaths before the first checkout, persisting only in the new repository under ordinary Git configuration precedence. Omission preserves configuration; existing repositories and non-Windows clone commands remain unchanged. No global setting or migration. configuration adds revision and unborn from successful porcelain-v2 branch state, preserving real commits including empty trees; it 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,remoteBase?} for current-branch fast-forward pull or non-force current-HEAD selected-ref push; omission retains ordinary configured behavior. An operation's own remoteBase declares local-path intent and captures its native absolute argument once at acceptance, before queueing; factory remote/remoteBase/branch remain independent clone inputs. Targeted pull/push results and writer results/failure outcomes retain the original remote, ref and supplied remoteBase, including relative or empty base text. Unrepresentable base text reports TypeError without transformation. 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 identity selection writes no config file. Optional cloneIdentity captures exact name/email strings and persists only supplied fields through clone --config before the first checkout on every supported platform. Empty strings are explicit; omitted or undefined fields preserve inherited/template configuration. Existing checkouts are never reconfigured. Unrepresentable process arguments fail honestly without transforming them. This option changes no global configuration or credentials and does not identify an authenticated account; command-local gitIdentity remains independent. Optional initialBranch selects refs/heads/<initialBranch> only for a newly cloned checkout with successful complete empty remote advertisement, explicit local initial state and successful empty local-ref listing; branch remains clone --branch. Any template or hook-supplied local ref preserves HEAD. Existing destinations and committed or advertised clones remain unchanged. Explicit new-clone open adds complete ordered preparation outputs, including observeRefs when performed; later preparation failures retain completed outputs and their original cause. Omission preserves commands and result shape. First publication uses existing exact-file write and explicit target without an implicit pull."
     },
     {
       "id": "core-repositories:readGitIdentity",
@@ -493,14 +493,14 @@
       "name": "createGitTextSnapshot",
       "displayName": "createGitTextSnapshot()",
       "kind": "function",
-      "signature": "createGitTextSnapshot({cacheDirectory,remote,remoteBase,ref,selectPath,gitIdentity,onEvent,run=runProcess}={})",
+      "signature": "createGitTextSnapshot({cacheDirectory,remote,remoteBase,ref,selectPath,allowUnborn=false,gitIdentity,onEvent,run=runProcess}={})",
       "entrypoints": ["arcane-os"],
       "primaryImport": "arcane-os",
       "group": "Workspace, doctor, repository, and server",
       "summary": "Reads complete selected text from one fetched revision using a dedicated bare Git object cache and batched retrieval.",
       "availability": "Node with Git; Android requires a host supplying Git/process capability",
       "protocol": "Git tree and batched blob transport through the shared process owner",
-      "normalization": "Returns {refresh,close,drain,dispose}; refresh yields {revision,files:[{path,content}]}, shares concurrent work, reuses unchanged revisions, preserves exact UTF-8 text, isolates caller cancellation and drains accepted work. Optional remoteBase explicitly selects remote as a local filesystem locator and derives only its Git fetch argument through path.resolve(remoteBase, remote), once at construction independently of the cache location and later working-directory changes. A relative base, including an empty string, uses the construction-time working directory; original locator/options remain unchanged. Omission preserves every Git remote name, URL, SCP-like address and remote-helper string without guessed parsing. Unrepresentable base text reports TypeError without transformation; existing Git failures remain errors. Optional gitIdentity captures name/email/username for child Git commands including bare init and fetch, without changing config files, payloads or shared acquisition lifetime. See git-text-snapshot.md."
+      "normalization": "Returns {refresh,close,drain,dispose}; refresh yields {revision,files:[{path,content}]}, shares concurrent work, reuses unchanged revisions, preserves exact UTF-8 text, isolates caller cancellation and drains accepted work. Optional allowUnborn defaults false, preserving that shape and command sequence. Explicit true first observes the complete remote advertisement; successful empty stdout yields revision:null, files:[], unborn:true. Any advertised HEAD, branch, tag or other output retains normal selected-ref fetch and actual errors; committed results add unborn:false, including a real empty tree. Every acquisition reobserves rather than returning stale empty state; cache role, identity, cancellation and drain remain unchanged. Optional remoteBase explicitly selects remote as a local filesystem locator and derives only its Git remote argument through path.resolve(remoteBase, remote), once at construction independently of the cache location and later working-directory changes. A relative base, including an empty string, uses the construction-time working directory; original locator/options remain unchanged. Omission preserves every Git remote name, URL, SCP-like address and remote-helper string without guessed parsing. Unrepresentable base text reports TypeError without transformation; existing Git failures remain errors. Optional gitIdentity captures name/email/username for child Git commands including bare init and fetch, without changing config files, payloads or shared acquisition lifetime. See git-text-snapshot.md."
     },
     {
       "id": "diarization:createDiarization",
@@ -4304,7 +4304,7 @@
       "summary": "Describes existing Core method input, output and semantic shapes.",
       "availability": "Node and browser/bundler",
       "protocol": "arcane/1 method descriptions",
-      "normalization": "Descriptive data only, including independent localai.devices inventory and localai.resolveTarget physical-selection records; presence does not establish engine support or observed execution. The active host and its registered services remain the authority for method availability"
+      "normalization": "Descriptive data only, including independent localai.devices inventory and localai.resolveTarget physical-selection records; presence does not establish engine support or observed execution. Native notifications.status/show/state/close describe actual host support, exact caller content, retained host-lifetime outcomes and explicit owned removal; native submission does not establish display or human receipt. The active host and its registered services remain the authority for method availability"
     },
     {
       "id": "core-contracts:CoreError",
@@ -4360,7 +4360,7 @@
       "summary": "Projects a Core client into the established application-facing Arcane namespace.",
       "availability": "Browser and native WebView JavaScript hosts with a Core client",
       "protocol": "arcane/1 compatibility facade",
-      "normalization": "Routes namespace methods through client.invoke while retaining operation-specific parameters, correlation, streaming callbacks, timeouts and cancellation; window.state({signal}?) reads the requesting window and window.setState({state},{signal}?) selects normal, maximized or fullscreen. The matching Windows host returns {platform:'windows',supported:true,state}, including observed minimized state, restores normal bounds/frame controls on leaving fullscreen and prevents activation/focus assignment during visible state transitions without changing TopMost, Core, origin or profile. Saved Settings remain application-owned; cancellation does not undo an applied change and unavailable hosts retain their actual errors without fallback. window.setTheme(presentation,{signal}?) forwards the complete per-window backgroundColor/textColor record, with omitted fields unchanged and null reset, and returns the host's actual applied/unsupported result without changing system appearance"
+      "normalization": "Routes namespace methods through client.invoke while retaining operation-specific parameters, correlation, streaming callbacks, timeouts and cancellation; window.state({signal}?) reads the requesting window and window.setState({state},{signal}?) selects normal, maximized or fullscreen. The matching Windows host returns {platform:'windows',supported:true,state}, including observed minimized state, restores normal bounds/frame controls on leaving fullscreen and prevents activation/focus assignment during visible state transitions without changing TopMost, Core, origin or profile. Saved Settings remain application-owned; cancellation does not undo an applied change and unavailable hosts retain their actual errors without fallback. window.setTheme(presentation,{signal}?) forwards the complete per-window backgroundColor/textColor record, with omitted fields unchanged and null reset, and returns the host's actual applied/unsupported result without changing system appearance. notifications.status/show/state/close forward complete caller requests and standard invoke options; status normalizes only METHOD_NOT_ALLOWED with core-namespace-unavailable while retaining the complete original error. Matching native window hosts retain complete notification records and ordered revisions across renderer navigation, with notifications.state events and subscribe-before-snapshot recovery. Submitted means native Show returned, not displayed or read; cancellation after submission does not remove an accepted notice, and explicit close retains its record. Recipient, text, trigger, deduplication and navigation policy remains application-owned"
     },
     {
       "id": "core-client:installCoreClient",

package/docs/reference/native-diagnostics.md

@@ -0,0 +1,167 @@
+# Native application diagnostics
+
+Native diagnostics retain errors from the actual packaged application's top-level
+document in its native host session. Read them through the existing app-control
+connection, without foregrounding a window, desktop input, or arbitrary script
+execution. This is a developer inspection surface, separate from ordinary product
+status and saved conversation history.
+
+The Windows WebView2 host installs the fixed observer at document creation, before
+the ordinary Core client and application scripts. It captures `window.error` and
+`unhandledrejection` events and accepts explicit reports of application-caught
+errors. It leaves the browser's ordinary error behavior intact. It does not
+intercept console output, inspect application state, collect resource/request
+bodies, or capture errors from other applications or frame documents.
+
+## Report a caught application error
+
+```js
+import {reportNativeError} from 'arcane-os/core/native-diagnostics';
+
+const receipt = await reportNativeError(error, {
+    details: {operation: 'source.load', sourceId}
+});
+// receipt: {accepted: true, sessionId, sequence}
+```
+
+`error` is the actual caught value, including non-Error rejection values.
+`details` is optional application-selected diagnostic context. Supply diagnostic
+information only; credentials, secrets, user documents and provider/tool payloads
+do not belong in this report. The SDK adds document/session metadata outside the
+reported values and does not rewrite their text. Reporting does not change the
+application's own handling of the original failure.
+
+The promise resolves after the native host retains the record. A missing document
+observer or native handler rejects with
+`ARCANE_NATIVE_DIAGNOSTICS_UNAVAILABLE`. A negative host acknowledgement rejects
+with `ARCANE_NATIVE_DIAGNOSTIC_REJECTED`, preserving the complete host reply in
+`details` and its error in `cause`. Reflection, encoding and native transport
+failures reject with their actual error. A lost reply can leave the caller's
+outcome unknown; the SDK does not automatically retry and duplicate the report.
+
+Automatic capture observes its own reporting failures through the existing
+console, with the original error, without recursively manufacturing an unhandled
+rejection. Console output remains ordinary console output; it is not retained
+diagnostic history. Applications must observe explicit reporting promises.
+
+## Retrieve retained errors
+
+Use the endpoint of the selected running app from its existing app-control launch
+configuration. Connecting does not launch the application.
+
+```js
+import {connectAppControl} from 'arcane-os/core/app-control';
+
+const control = await connectAppControl({endpoint});
+try {
+    const snapshot = await control.diagnostics();
+    console.dir(snapshot, {depth: null});
+} finally {
+    await control.close();
+}
+```
+
+`control.diagnostics({afterSequence?, documentId?}, {signal?})` invokes
+`app.control.diagnostics`. Omitted filters return every retained error.
+`afterSequence` selects records with a greater session sequence;
+`documentId` selects one actual document. Retrieval is non-consuming: independent
+inspectors can read the same complete records. Connection/cancellation behavior is
+the existing app-control contract. Retrieval does not wait for renderer, Core,
+model or application readiness and does not evaluate a script in the document.
+
+The result is:
+
+```js
+{
+    sessionId,
+    captureStartedAt,
+    captureInstalled,
+    latestSequence,
+    documents: [{documentId, documentUrl, time, receivedAt}],
+    records: [{
+        sequence, receivedAt, documentId, documentUrl, time,
+        kind, error, details, valueFormat, values, location, message
+    }]
+}
+```
+
+`sessionId` identifies this native window/host lifetime. `captureStartedAt` is the
+time its in-memory ledger was created. `captureInstalled` means document-start
+script registration completed; it does not prove that any application failure
+occurred or that a particular operation succeeded. `documents` records actual
+ingress from observed documents. Each document has one identity, shared with app
+control, independent of Core bridge generations. A cancelled navigation that
+leaves the same document alive keeps that identity.
+
+`sequence` is assigned when an error is retained, in host arrival order.
+`latestSequence` describes the whole session even when filters select fewer
+records. `time` comes from document capture; `receivedAt` comes from the host.
+`kind` is `window.error`, `unhandledrejection`, or `application`. Window errors
+include `location: {file, line, column}` when the browser exposes those fields.
+Their browser `message` is retained separately from `error`, preserving a null
+or undefined error value rather than replacing it with that message.
+`details` and `location` are otherwise omitted.
+
+Records survive document navigation and Core transport failure within the host
+session. Closing the inspector leaves them retained. Closing the native host ends
+the session; this API does not persist, migrate, prune, or recover records across
+host restarts. An empty snapshot means no matching records were retained in this
+session, not that earlier failures never occurred. Errors before capture existed,
+handled failures never explicitly reported, errors the browser does not expose,
+and vanished documents whose pending reports never reached the host remain
+unavailable. Earlier never-retained failures cannot be reconstructed through this API.
+
+## Complete error property representation
+
+Each record uses `valueFormat: 'arcane.diagnostic-value/1'`. `error` and optional
+`details` are roots into the single `values` graph. JSON-native primitives remain
+their original values. Undefined, bigint, non-finite numbers and negative zero
+have explicit typed representations. `{ref: id}` identifies a graph node.
+Repeated references and cycles retain the same identity within the record.
+
+Object nodes retain every own property descriptor, including non-enumerable and
+symbol-keyed fields. This includes full Error messages and stacks, `cause`,
+AggregateError members and custom diagnostic details. Standard error fields
+inherited from a prototype appear in `inherited`. Data descriptors contain
+`value`; accessor descriptors contain references for `get` and `set` without
+invoking either function. An accessor supplied as the `details` option is likewise
+represented rather than called. No `toJSON` method on reported content is called.
+Maps and sets retain their entries, dates their numeric time, and regular
+expressions their source and flags, alongside their own properties.
+
+This is a diagnostic property representation, not an executable object snapshot:
+functions retain their property identity, not executable closures; platform-private
+internal state and private class fields are not observable properties. The host
+stores and returns the graph without reconstructing or executing those objects.
+An object that rejects reflection causes an observable reporting failure rather
+than a silently incomplete success. Inspect the complete graph in developer
+diagnostics; do not flatten it into ordinary chat or user-facing status.
+
+## Host ownership and availability
+
+`installNativeDiagnostics(globalThis)` installs one observer per document and
+returns its owner `{documentId, ready, report}`. `ready` resolves after the document
+announcement is accepted, and `report` has the same report contract. Importing
+the ESM module alone installs no observer. The packaged native host owns
+installation and lifetime; ordinary applications use `reportNativeError`.
+
+`createNativeDiagnosticsSource()` from
+`arcane-os/core/native-diagnostics-source` projects that same canonical helper
+into the top-level document-start script. It adds no second observer or serializer.
+Windows binds the script to the dedicated `arcaneDiagnostics.Send` host object.
+This route is independent of `arcaneBridge` and the Core subprocess. Host close
+stops new ingress and removes the object/script during existing shutdown.
+
+The implementation here supplies Windows WebView2 capture and app-control
+retrieval. macOS, Linux and Android require their native host ingress/session and
+app-control adapters; this source change does not claim those adapters exist.
+The helper recognizes the same fixed-name WebKit reply handler when a host
+provides it; that transport seam is not platform availability. A browser preview
+cannot establish actual native acceptance.
+
+Native delivery requires the corresponding rebuilt SDK Windows host asset and
+consumer adoption through the published SDK package. Source inspection, authored
+fixtures and configured capture are distinct from executed built-application
+verification. Existing host stderr/log diagnostics, live Core events, readiness
+replay and `Arcane.diagnostics.recentErrors/get` retain their existing semantics;
+this API does not turn them into a historical error service.

package/docs/reference/sdk-api.md

@@ -5409,7 +5409,7 @@ a dedicated bare Git cache. It does not create or alter a working checkout.
 ### Signature, lifecycle, and result
 
 ```text
-createGitTextSnapshot({cacheDirectory,remote,remoteBase,ref,selectPath,gitIdentity,onEvent,run=runProcess}={})
+createGitTextSnapshot({cacheDirectory,remote,remoteBase,ref,selectPath,allowUnborn=false,gitIdentity,onEvent,run=runProcess}={})
 ```
 
 Import from `arcane-os`. The application owns the cache location, remote, ref,
@@ -5421,6 +5421,14 @@ await accepted refresh/process cleanup. Errors remain observable instead of
 returning stale or partial success. See [Git text snapshots](git-text-snapshot.md)
 for complete inputs, text semantics, errors, events and Core service composition.
 
+Optional `allowUnborn:true` observes the complete remote advertisement on every
+acquisition. Only successful empty output returns
+`{revision:null,files:[],unborn:true}`; committed results add `unborn:false` and
+retain the actual commit even for an empty tree. Any advertised HEAD, branch
+or tag continues through ordinary selected-ref fetch; missing refs and actual
+Git failures remain errors. Omitted/false preserves the prior result and commands.
+See [unborn remotes](git-text-snapshot.md#unborn-remotes).
+
 Optional `remoteBase` explicitly selects `remote` as a local filesystem locator.
 Only its Git fetch argument is derived using `path.resolve(remoteBase, remote)`,
 once at construction, independently of the cache location and later changes to
@@ -5476,6 +5484,28 @@ once and stdin remains open until cancellation or a callback/input failure
 requests shutdown. On Microsoft NT, `npm` and `npx` are normalized to their Node
 CLI entrypoints.
 
+For the literal `git` command on Windows, the default runner reads Git for
+Windows' registered `InstallPath` in the current-user and machine registry
+views. When that installation's `cmd/git.exe` exists, its `cmd` directory is
+appended only to this child's effective PATH. Existing entries and native
+command lookup retain priority; duplicate `Path`/`PATH` spellings follow Node's
+lexical selection. Other environment fields, explicit executable paths,
+custom process adapters, other commands and other platforms keep their existing
+behavior. No global environment or registry setting is changed, and no Git
+download, installation or command retry occurs.
+
+One successful location is retained in memory for this process while its
+executable remains present. A removed executable triggers fresh discovery;
+absent, failed and cancelled lookups are not retained. Concurrent cold callers
+own independent discovery and cancellation. The standard Windows registry
+helper uses the existing process owner; its lifecycle callbacks have
+`process.git.discovery.*` event names, and its captured metadata is separate
+from the requested command's output. Missing registration leaves ordinary
+lookup unchanged. Discovery failure emits `process.git.discovery.unavailable`
+with the complete error before ordinary lookup continues. Cancellation or an
+event-callback failure stops the operation before Git starts. Normal Git
+errors and missing-working-directory errors remain actual command failures.
+
 An `AsyncIterable` input instead feeds stdin with awaited writes and closes it
 when the producer finishes. Its `return()` must cooperate with cancellation of
 an outstanding `next()`; the process owner drains both input and output work.
@@ -8400,7 +8430,7 @@ explicit existing path. The application owns the remote, branch and Core API.
 ### Signature and result
 
 ```text
-createRepositoryWorkspace({name,directory,dataRoot,remote,remoteBase,branch,longPaths,cloneIdentity,gitIdentity,onEvent,run=runProcess}={})
+createRepositoryWorkspace({name,directory,dataRoot,remote,remoteBase,branch,initialBranch,longPaths,cloneIdentity,gitIdentity,onEvent,run=runProcess}={})
 ```
 
 Returns `{directory,open,status,configuration,pull,push,write,close,drain,dispose}`. Construction does
@@ -8411,6 +8441,17 @@ work and preserves the checkout. No CLI cwd, launch state, preference, snapshot
 cache or existing user-data location changes. See the [complete inputs, results,
 errors and lifecycle](core-repositories.md#one-connected-working-checkout).
 
+Optional `initialBranch` selects `refs/heads/<initialBranch>` only after a new
+clone, successful complete empty remote advertisement, explicit local
+initial-state observation and a successful empty local-ref listing. Any local
+ref supplied by a Git template or hook remains unchanged. Existing destinations and committed/advertised
+clones keep their branches; `branch` still means Git's existing-branch/tag clone
+selection. New-clone `open` results with this option add complete ordered
+preparation `outputs`; subsequent failures retain completed outputs and their
+original cause. Omission adds no command or result field. See
+[first-publication composition](core-repositories.md#first-publication-from-an-unborn-remote)
+for the direct first commit/push without an implicit pull.
+
 Optional factory `remoteBase` explicitly selects the initial-clone `remote` as
 a local filesystem locator. Only its Git argument is derived through the host's
 native `path.resolve(remoteBase, remote)`, once at construction. Relative bases,
@@ -8446,13 +8487,17 @@ omitted fields remain inherited. Username remains a credential hint, with
 authentication owned by ordinary Git and its configured helper.
 
 `configuration({signal})` observes an existing working root without clone,
-initialization or fetch. It returns `{repositoryRoot,headRef,origin,upstream}`:
+initialization or fetch. It returns `{repositoryRoot,headRef,revision,unborn,origin,upstream}`:
 full symbolic HEAD (including unborn, null when detached), origin URL/pushURL
 arrays and current branch remote/merge/URL/pushURL arrays. Unset, empty and
-repeated configuration values remain distinct. These are ordinary configured
-values, not authentication or endpoint proof, and are not atomic with later
-operations. Raw stdout is decoded without replacement; unrepresentable text
-reports `ARCANE_GIT_CONFIGURATION_NOT_TEXT` with full diagnostics.
+repeated configuration values remain distinct. `revision:null,unborn:true`
+comes only from Git's explicit porcelain-v2 initial state; committed and
+detached states retain their current revision with `unborn:false`. Missing
+branch-state output reports `ARCANE_REPOSITORY_HEAD_UNAVAILABLE`. These are
+ordinary configured values and local branch observations, not authentication
+or endpoint proof, and are not atomic with later operations. Raw stdout is
+decoded without replacement; unrepresentable text reports
+`ARCANE_GIT_CONFIGURATION_NOT_TEXT` with full diagnostics.
 
 `pull({target,signal})`, `push({target,signal})` and
 `write({files:[{path,content}],message,target,signal})` accept optional

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.91.0",
+  "version": "0.93.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -65,6 +65,8 @@
     "./core/stdio": "./src/core/stdio.mjs",
     "./core/host": "./src/core/host.mjs",
     "./core/app-control": "./src/core/app-control.mjs",
+    "./core/native-diagnostics": "./browser-runtime/core/native-diagnostics.mjs",
+    "./core/native-diagnostics-source": "./src/core-native-diagnostics-source.mjs",
     "./codex/app-server": "./src/codex/app-server.mjs",
     "./mcp/stdio": "./src/mcp/stdio-server.mjs",
     "./core/repositories": "./src/core/repositories.mjs",

package/src/core/app-control.mjs

@@ -15,6 +15,7 @@ export async function connectAppControl({endpoint, signal, onError = reportAppCo
         endpoint,
         closed: connection.closed,
         status(options) { return client.invoke('app.control.status', {}, options); },
+        diagnostics(parameters = {}, options) { return client.invoke('app.control.diagnostics', parameters, options); },
         inspect(parameters = {}, options) { return client.invoke('app.control.inspect', parameters, options); },
         capture(parameters = {}, options) { return client.invoke('app.control.capture', parameters, options); },
         act(parameters, options) { return client.invoke('app.control.act', parameters, options); },

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

@@ -452,7 +452,7 @@ namespace Arcane.Core.Hosts.Windows
                         try
                         {
                             cancellation.Token.ThrowIfCancellationRequested();
-                            if (method != "app.control.status" && method != "app.control.inspect"
+                            if (method != "app.control.status" && method != "app.control.diagnostics" && method != "app.control.inspect"
                                 && method != "app.control.capture" && method != "app.control.act"
                                 && method != "app.control.key" && method != "app.control.resize")
                                 throw new NotSupportedException("The app does not expose " + method + ".");