arcane-os 0.91.0 → 0.92.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 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.92.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/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.

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.91.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",

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.92.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/src/core/repositories.mjs

@@ -5,7 +5,7 @@ import Is from 'strong-type';
 import {ArcaneError, throwIfAborted} from '../errors.mjs';
 import {runProcess} from '../process.mjs';
 import {captureRepositoryRemote, captureRepositoryTarget, repositoryConfiguration, pullRepositoryTarget, pushRepositoryTarget,
-    repositoryPushArguments, repositoryStatus} from '../repository.mjs';
+    repositoryHeadArguments, repositoryHeadState, repositoryPushArguments, repositoryStatus} from '../repository.mjs';
 import {createGitIdentityRunner} from '../git-identity.mjs';
 
 export {readGitIdentity} from '../git-identity.mjs';
@@ -45,7 +45,7 @@ export function resolveArcaneDataPaths({dataRoot} = {}) {
 
 /** One connected checkout, composed into an application's own Core service. */
 export function createRepositoryWorkspace(
-    {name, directory, dataRoot, remote, remoteBase, branch, longPaths, cloneIdentity = {}, gitIdentity, onEvent, run = runProcess} = {}
+    {name, directory, dataRoot, remote, remoteBase, branch, initialBranch, longPaths, cloneIdentity = {}, gitIdentity, onEvent, run = runProcess} = {}
 ) {
     let selected = directory;
     if (selected === undefined) {
@@ -59,6 +59,12 @@ export function createRepositoryWorkspace(
     if (remote !== undefined) requireString(remote, 'remote');
     const remoteArgument = captureRepositoryRemote(remote, remoteBase);
     if (branch !== undefined) requireString(branch, 'branch');
+    if (initialBranch !== undefined) {
+        requireString(initialBranch, 'initialBranch');
+        if (!initialBranch.isWellFormed() || initialBranch.includes('\0')) {
+            throw new TypeError('initialBranch must be text representable as a native process argument.');
+        }
+    }
     if (longPaths !== undefined && !is.boolean(longPaths)) {
         throw new TypeError('longPaths must be a boolean when supplied.');
     }
@@ -126,9 +132,60 @@ export function createRepositoryWorkspace(
             arguments_,
             {cwd: path.dirname(repositoryDirectory), signal, onEvent}
         );
+        let outputs;
+        if (initialBranch !== undefined) {
+            const options = {cwd: repositoryDirectory, signal, onEvent};
+            outputs = [];
+            function completed(operation, observation) {
+                outputs.push({operation, stdout: observation.stdout, stderr: observation.stderr,
+                    code: observation.code, signal: observation.signal ?? null});
+            }
+            completed('clone', result);
+            try {
+                throwIfAborted(signal);
+                const advertised = await prepareRun('git', ['ls-remote', '--symref', '--', remoteArgument],
+                    {cwd: path.dirname(repositoryDirectory), signal, onEvent});
+                completed('observeRemote', advertised);
+                throwIfAborted(signal);
+                if (advertised.code !== 0) {
+                    throw new ArcaneError('ARCANE_OPERATION_FAILED', 'Git remote observation failed.', {details: advertised});
+                }
+                if (advertised.stdout === '') {
+                    const state = await prepareRun('git', [...repositoryHeadArguments], options);
+                    completed('observeHead', state);
+                    throwIfAborted(signal);
+                    if (state.code !== 0) {
+                        throw new ArcaneError('ARCANE_OPERATION_FAILED', 'Git branch state observation failed.', {details: state});
+                    }
+                    if (repositoryHeadState(state.stdout, state).unborn) {
+                        const references = await prepareRun('git', ['for-each-ref', '--format=%(refname)'], options);
+                        completed('observeRefs', references);
+                        throwIfAborted(signal);
+                        if (references.code !== 0) {
+                            throw new ArcaneError('ARCANE_OPERATION_FAILED', 'Git local ref observation failed.', {details: references});
+                        }
+                        // Git templates or hooks can supply local refs even
+                        // when the remote and this checkout's HEAD are unborn.
+                        if (references.stdout === '') {
+                            const selection = await prepareRun('git', ['symbolic-ref', 'HEAD', `refs/heads/${initialBranch}`], options);
+                            completed('selectInitialBranch', selection);
+                            throwIfAborted(signal);
+                            if (selection.code !== 0) {
+                                throw new ArcaneError('ARCANE_OPERATION_FAILED', 'Git initial branch selection failed.', {details: selection});
+                            }
+                        }
+                    }
+                }
+            } catch (cause) {
+                throw new ArcaneError(cause?.code ?? 'ARCANE_REPOSITORY_PREPARE_FAILED',
+                    cause instanceof Error ? cause.message : String(cause),
+                    {cause, details: {directory: repositoryDirectory, cloned: true, outputs}, exitCode: cause?.exitCode});
+            }
+        }
         throwIfAborted(signal);
         opened = true;
-        return {directory: repositoryDirectory, cloned: true, stdout: result.stdout, stderr: result.stderr};
+        return {directory: repositoryDirectory, cloned: true, stdout: result.stdout, stderr: result.stderr,
+            ...(outputs === undefined ? {} : {outputs})};
     }
 
     function accept(operation, signal) {

package/src/git-text-snapshot.mjs

@@ -15,11 +15,12 @@ const snapshotRef = 'refs/arcane/text-snapshot';
  * One application service owns each dedicated cache directory. Construction
  * performs no I/O; refresh coalesces callers and close drains accepted work.
  */
-export function createGitTextSnapshot({cacheDirectory, remote, remoteBase, ref, selectPath, gitIdentity, onEvent, run = runProcess} = {}) {
+export function createGitTextSnapshot({cacheDirectory, remote, remoteBase, ref, selectPath, allowUnborn = false, gitIdentity, onEvent, run = runProcess} = {}) {
     for (const [name, value] of Object.entries({cacheDirectory, remote, ref})) {
         if (!is.string(value) || value === '') throw new TypeError(`${name} must be a nonempty string.`);
     }
     if (!is.function(selectPath)) throw new TypeError('selectPath must be a function.');
+    if (!is.boolean(allowUnborn)) throw new TypeError('allowUnborn must be a boolean.');
     const remoteArgument = captureRepositoryRemote(remote, remoteBase);
     const execute = createGitIdentityRunner(run, gitIdentity);
     const directory = path.resolve(cacheDirectory);
@@ -70,11 +71,28 @@ export function createGitTextSnapshot({cacheDirectory, remote, remoteBase, ref,
         try {
             await events.send({type: 'git.snapshot.refreshing', message: 'Refreshing the selected repository revision.', data: {ref}});
             await prepare(events);
+            if (allowUnborn) {
+                // No ref pattern or --exit-code: a successful complete empty
+                // advertisement is distinct from a missing selected ref.
+                const advertised = await git(['ls-remote', '--symref', '--', remoteArgument], {onEvent: events.send});
+                if (advertised.code !== 0) {
+                    throw new ArcaneError(ERROR_CODES.operationFailed, 'Git remote observation failed.', {details: advertised});
+                }
+                if (advertised.stdout === '') {
+                    const result = {revision: null, files: [], unborn: true};
+                    await events.send({type: 'git.snapshot.completed', message: 'The remote advertises no revision.',
+                        data: {revision: null, unborn: true, reused: retained?.unborn === true}});
+                    await events.drain();
+                    retained = result;
+                    return result;
+                }
+            }
             await git(['fetch', '--no-tags', '--no-write-fetch-head', '--', remoteArgument, `+${ref}:${snapshotRef}`], {onEvent: events.send});
             const selected = await git(['rev-parse', '--verify', `${snapshotRef}^{commit}`], {onEvent: events.send});
             const revision = selected.stdout.trim();
             if (retained?.revision === revision) {
-                await events.send({type: 'git.snapshot.completed', message: 'The selected repository revision is unchanged.', data: {revision, reused: true}});
+                await events.send({type: 'git.snapshot.completed', message: 'The selected repository revision is unchanged.',
+                    data: {revision, reused: true, ...(allowUnborn ? {unborn: false} : {})}});
                 await events.drain();
                 return retained;
             }
@@ -125,8 +143,9 @@ export function createGitTextSnapshot({cacheDirectory, remote, remoteBase, ref,
                     }
                 });
             }
-            const result = {revision, files: reader.finish()};
-            await events.send({type: 'git.snapshot.completed', message: 'Repository text snapshot is ready.', data: {revision, reused: false}});
+            const result = {revision, files: reader.finish(), ...(allowUnborn ? {unborn: false} : {})};
+            await events.send({type: 'git.snapshot.completed', message: 'Repository text snapshot is ready.',
+                data: {revision, reused: false, ...(allowUnborn ? {unborn: false} : {})}});
             await events.drain();
             retained = result;
             return result;
@@ -156,7 +175,8 @@ export function createGitTextSnapshot({cacheDirectory, remote, remoteBase, ref,
             accepted.then(settled, settled);
         }
         return waitForSnapshot(active, signal).then(function copyResult(snapshot) {
-            return {revision: snapshot.revision, files: snapshot.files.map(function copyFile(file) { return {...file}; })};
+            return {revision: snapshot.revision, files: snapshot.files.map(function copyFile(file) { return {...file}; }),
+                ...(allowUnborn ? {unborn: snapshot.unborn} : {})};
         });
     }
 

package/src/process.mjs

@@ -3,6 +3,7 @@ import {spawn} from 'node:child_process';
 import path from 'node:path';
 import {ArcaneError,ERROR_CODES,throwIfAborted} from './errors.mjs';
 import {createEventQueue} from './event-queue.mjs';
+import {windowsGitEnvironment} from './windows-git-executable.mjs';
 
 const is = new Is(false);
 
@@ -195,6 +196,29 @@ export async function runProcess(command,args=[],{
     });
     throwIfAborted(signal);
 
+    let childEnvironment=env?{...process.env,...env}:process.env;
+    if(process.platform==='win32'&&command==='git'){
+        try{
+            childEnvironment=await windowsGitEnvironment(childEnvironment,{
+                run:runProcess,signal,
+                onEvent:function discoveryEvent(event){
+                    return events.send({
+                        ...event,type:event.type.replace(/^process\./u,'process.git.discovery.')
+                    });
+                }
+            });
+        }catch(error){
+            throwIfAborted(signal);
+            if(events.error)throw events.error;
+            await events.send({
+                type:'process.git.discovery.unavailable',
+                message:'Registered Git discovery was unavailable; using the existing command environment.',
+                data:{error}
+            });
+        }
+        throwIfAborted(signal);
+    }
+
     return new Promise((resolve,reject)=>{
         let stdout=outputEncodings.stdout!==null&&outputSelected(captureOutput,'stdout')?'':null;
         let stderr=outputEncodings.stderr!==null&&outputSelected(captureOutput,'stderr')?'':null;
@@ -369,7 +393,7 @@ export async function runProcess(command,args=[],{
         try{
             child=spawn(executable,executableArgs,{
                 cwd,
-                env:env?{...process.env,...env}:process.env,
+                env:childEnvironment,
                 shell:false,
                 detached:process.platform!=='win32',
                 windowsHide:true,

package/src/repository.mjs

@@ -85,6 +85,25 @@ export function repositoryPushArguments(selection) {
         : ['push', '--no-follow-tags', '--', selection.remoteArgument, `HEAD:${selection.target.ref}`];
 }
 
+// Both configuration and new-clone preparation consume Git's explicit initial
+// state. NUL framing keeps unusual working filenames outside these headers.
+export const repositoryHeadArguments = [
+    '--no-optional-locks', 'status', '--porcelain=v2', '-z', '--branch', '--untracked-files=no'
+];
+
+export function repositoryHeadState(output, details) {
+    const prefix = '# branch.oid ';
+    const record = output.split('\0').find(function branchCommit(value) {
+        return value.startsWith(prefix);
+    });
+    const revision = record?.slice(prefix.length);
+    if (!revision) {
+        throw new ArcaneError('ARCANE_REPOSITORY_HEAD_UNAVAILABLE',
+            'Git did not report its current commit or initial branch state.', {details});
+    }
+    return revision === '(initial)' ? {revision: null, unborn: true} : {revision, unborn: false};
+}
+
 /** Observe an existing workspace without initializing or refreshing it. */
 export async function repositoryConfiguration({workspaceRoot = process.cwd(), signal, onEvent, run = runProcess} = {}) {
     const repositoryRoot = path.resolve(workspaceRoot);
@@ -147,7 +166,12 @@ export async function repositoryConfiguration({workspaceRoot = process.cwd(), si
         upstream.urls = remotes.get(`remote.${remoteName}.url`) ?? [];
         upstream.pushUrls = remotes.get(`remote.${remoteName}.pushurl`) ?? [];
     }
-    return {repositoryRoot, headRef, origin, upstream};
+    const state = await readGitText([...repositoryHeadArguments], options);
+    if (state.result.code !== 0) throw processFailure(state, 'Git branch state observation failed.');
+    let headState;
+    try { headState = repositoryHeadState(state.output, state.result); }
+    catch (error) { error.rawStdout = state.rawStdout; throw error; }
+    return {repositoryRoot, headRef, ...headState, origin, upstream};
 }
 
 export async function repositoryStatus({

package/src/windows-git-executable.mjs

@@ -0,0 +1,103 @@
+import Is from 'strong-type';
+import {stat} from 'node:fs/promises';
+import path from 'node:path';
+import {throwIfAborted} from './errors.mjs';
+
+const is=new Is(false);
+let installedDirectory=null;
+
+// Git for Windows records its chosen location for third-party integrations.
+// Read both installation scopes/views in one owned Windows process. No guessed
+// installation paths or changes to the registry/environment are needed.
+const READ_INSTALLATIONS=String.raw`
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+$installations = [System.Collections.Generic.List[string]]::new()
+$views = @([Microsoft.Win32.RegistryView]::Registry32)
+if ([Environment]::Is64BitOperatingSystem) {
+    $views = @([Microsoft.Win32.RegistryView]::Registry64, [Microsoft.Win32.RegistryView]::Registry32)
+}
+foreach ($hive in @([Microsoft.Win32.RegistryHive]::CurrentUser, [Microsoft.Win32.RegistryHive]::LocalMachine)) {
+    foreach ($view in $views) {
+        $base = [Microsoft.Win32.RegistryKey]::OpenBaseKey($hive, $view)
+        try {
+            $key = $base.OpenSubKey('Software\GitForWindows')
+            if ($null -ne $key) {
+                try {
+                    $location = $key.GetValue('InstallPath')
+                    if ($location -is [string] -and $location.Length -gt 0 -and -not $installations.Contains($location)) {
+                        $installations.Add($location)
+                    }
+                } finally { $key.Dispose() }
+            }
+        } finally { $base.Dispose() }
+    }
+}
+ConvertTo-Json -InputObject @($installations.ToArray()) -Compress
+`;
+
+function environmentKey(environment,name){
+    return Object.keys(environment).sort().find(function matchingKey(key){
+        return key.toLowerCase()===name;
+    });
+}
+
+export function appendWindowsGitDirectory(environment,directory){
+    const keys=Object.keys(environment).filter(function pathKey(key){
+        return key.toLowerCase()==='path';
+    }).sort();
+    const selectedKey=keys[0]??'Path';
+    // Node chooses the first case-insensitive key before omitting undefined.
+    // libuv uses the parent's PATH if the child has none; null becomes 'null'.
+    const selected=environment[selectedKey];
+    const original=selected===undefined
+        ?process.env[environmentKey(process.env,'path')]??'':selected;
+    const result={...environment};
+    for(const key of keys)delete result[key];
+    const originalPath=`${original}`;
+    result[selectedKey]=`${originalPath}${originalPath?';':''}"${directory}"`;
+    return result;
+}
+
+async function installedGitExists(directory){
+    try{
+        return (await stat(path.win32.join(directory,'git.exe'))).isFile();
+    }catch(error){
+        if(error.code==='ENOENT'||error.code==='ENOTDIR')return false;
+        throw error;
+    }
+}
+
+export async function windowsGitEnvironment(environment,{run,signal,onEvent}={}){
+    throwIfAborted(signal);
+    const retained=installedDirectory;
+    if(retained){
+        const available=await installedGitExists(retained);
+        throwIfAborted(signal);
+        if(available)return appendWindowsGitDirectory(environment,retained);
+        if(installedDirectory===retained)installedDirectory=null;
+    }
+
+    const systemRoot=process.env[environmentKey(process.env,'systemroot')];
+    if(!systemRoot)return environment;
+    const powershell=path.win32.join(systemRoot,'System32','WindowsPowerShell','v1.0','powershell.exe');
+    const result=await run(powershell,['-NoProfile','-NonInteractive','-Command',READ_INSTALLATIONS],{
+        signal,onEvent,emitOutputEvents:false
+    });
+    throwIfAborted(signal);
+    const locations=JSON.parse(result.stdout);
+    if(!is.array(locations))throw new TypeError('Git installation discovery did not return a location list.');
+    for(const location of locations){
+        if(!is.string(location)||!path.win32.isAbsolute(location))continue;
+        const directory=path.win32.join(location,'cmd');
+        const available=await installedGitExists(directory);
+        throwIfAborted(signal);
+        if(available){
+            // Only successful, still-present discovery is retained. Concurrent
+            // first callers own separate lookups and cancellation independently.
+            installedDirectory=directory;
+            return appendWindowsGitDirectory(environment,directory);
+        }
+    }
+    return environment;
+}