oh-my-space 0.13.0 → 0.14.1

package/README.md

@@ -21,7 +21,7 @@ OMS automates routine, deterministic preparation and bounded recovery whenever i
 
 - [Node.js](https://nodejs.org) `>=20.19.0` to run `oms`.
 - git `>=2.40` for `git switch` and the submodule commands `oms` relies on.
-- Run `oms` from a Git repository. For a new workspace, run `git init` first, since sources are tracked as submodules of it.
+- Submodule commands require `oms.yaml` at the root Git top-level. `oms init` can scaffold outside Git, but run `git init` at that same workspace root before syncing sources.
 
 ## Install
 
@@ -70,12 +70,20 @@ oms/
 
 `oms.yaml` is your declaration, `.gitmodules` and each `oms/<alias>` gitlink are tracked in your project history, and every directory under `oms/` is a normal checked-out repository you can branch, edit, and commit in.
 
+## Command locations and workspace discovery
+
+Workspace-aware commands search from the current directory toward the filesystem root and use the nearest `oms.yaml`. The first `oms.yaml` entry encountered is authoritative. It must be a regular file, or a symbolic link whose target is a regular file. A directory, broken link, link to a non-file target, or invalid nearest manifest causes the command to fail; OMS does not skip it and fall back to an outer workspace.
+
+You can run workspace-aware commands at the workspace root or below it. When the current directory is inside `oms/<alias>/` for an alias declared by the selected manifest, `oms status --json` reports that alias and commands such as `oms commit` and `oms record` can infer it. An alias supplied on the command line always takes precedence over the inferred current alias. Arbitrary descendants and undeclared `oms/<name>/` paths can discover the workspace but do not become a current alias.
+
+Commands that inspect or change submodule state require the selected manifest directory to be the root Git top-level. A nested `oms.yaml` below an enclosing Git root is rejected before `.gitmodules`, the root index, `oms/`, or the manifest can change. Repair that layout by either moving `oms.yaml` to the enclosing Git root or initializing a separate Git repository at the intended nested workspace root. `oms sync --list` is manifest-only and remains available before Git initialization.
+
 ## Typical branch flow
 
 Start a branch, commit inside the submodule, push it, then record the pointer move in your project history. Each command stays in a single Git scope:
 
 ```bash
-oms switch api feature/login         # local branch, no remote needed
+oms branch switch api feature/login  # local branch, no remote needed
 oms commit api -m "feat: add login"  # commit inside oms/api (submodule only)
 oms push api                         # creates origin/feature/login (submodule branch only)
 oms record api                       # commit the moved oms/api pointer in your project history
@@ -83,7 +91,7 @@ oms record api                       # commit the moved oms/api pointer in your
 
 `oms commit` and `oms push` stay inside the submodule and never touch the root gitlink; `oms record` is the only command that commits an existing root pointer update. After a successful `oms commit`/`oms pull`/`oms push`, `oms` prints an `oms record <alias>` hint when the pointer has moved. Run `oms status --json` for a machine-readable view of which scope changed.
 
-Omit the alias or branch on `oms switch` and `oms checkout` to pick one interactively — synced submodules, and local or `origin/*` branches respectively.
+Omit the alias or branch on `oms branch switch` and `oms branch checkout` to pick one interactively — synced submodules, and local or `origin/*` branches respectively.
 
 ## Listing branches
 
@@ -92,7 +100,7 @@ Omit the alias or branch on `oms switch` and `oms checkout` to pick one interact
 ```bash
 oms branch list api
 oms branch list
-oms branch # choose list or delete interactively
+oms branch # choose list, switch, checkout, or delete interactively
 ```
 
 Before listing, OMS safely initializes an existing registered submodule when needed, reconciles every remote declared for that alias in `oms.yaml`, and runs `git fetch <remote> --prune` sequentially in manifest order. A failed fetch is retried once. If both attempts fail, cached refs remain visible as `stale`; a failed remote without usable refs is `unavailable`. These degraded states still exit 0 when local refs can be inspected. Extra local remotes are not fetched or included in the remote inventory, although an actual configured upstream on one of them remains visible for its local branch.
@@ -113,7 +121,7 @@ When `branch` is omitted from `oms.yaml`, a successful origin fetch refreshes `o
 oms branch delete api feature/login        # safe delete (git branch -d)
 oms branch delete api feature/login --force # force delete (git branch -D)
 oms branch delete                           # pick alias, then branch, interactively
-oms branch                                  # interactive list/delete action selector
+oms branch                                  # interactive list/switch/checkout/delete action selector
 ```
 
 - **Local only.** It never deletes a remote branch or a remote-tracking ref, never fetches or pushes, and never stages or commits the root gitlink. A missing local branch whose name exists on `origin` is reported as local-only.
@@ -133,7 +141,7 @@ oms branch                                  # interactive list/delete action sel
 
 `oms` does not replace Git submodules. It adds a small command layer for the workflow details that make submodules awkward. Submodules already give you a reproducible pin (the parent records each source's exact commit), visibility (`git status` shows when a pointer moved), and history (the pointer travels with your commits). The friction is in everyday branch work, and that is what `oms` smooths over:
 
-- **Start branches locally.** `oms switch <alias> <branch>` starts a local branch right away, even before it exists on the remote. `oms checkout <alias> <branch>` fetches origin and checks out an existing remote branch as a tracking branch. The remote branch is created lazily on your first `oms push`.
+- **Start branches locally.** `oms branch switch <alias> <branch>` starts a local branch right away, even before it exists on the remote. `oms branch checkout <alias> <branch>` fetches origin and checks out an existing remote branch as a tracking branch. The remote branch is created lazily on your first `oms push`.
 - **Stay on a branch.** `oms sync` attaches the baseline branch at the pinned commit instead of leaving a detached HEAD, so everyday submodule work never strands you off a branch.
 - **Keep pointer moves visible, commit them explicitly.** `oms pull` and `oms push` synchronize only the submodule branch — they never stage or commit the root gitlink. The moved pointer shows up in `git status`, `oms status` flags when a submodule has drifted from the recorded pointer, and `oms record <alias>` commits that pointer update in the parent repo.
 
@@ -173,7 +181,7 @@ The three skills are named by the Git domain each manages:
 | --- | --- | --- |
 | `oms-workspace` | Scope-ambiguous Git work in the workspace — committing from the root, a moved `oms status` pointer, a push, or adding/removing a repo with `oms sync`/`oms unsync`. | Establishes workspace state and root-versus-submodule scope before acting, and separates repo add/remove topology from recording a moved pointer. |
 | `oms-pointer` | After `oms commit` or `oms pull` moves a submodule's commit. | Records the moved root pointer with `oms record`, so a submodule change is not left without a recorded pointer and the root pointer is not committed by mistake. |
-| `oms-branch` | Starting or switching a branch inside a submodule. | Chooses `oms switch` (new local branch) versus `oms checkout` (track a remote branch) and avoids detached HEAD. |
+| `oms-branch` | Starting or switching a branch inside a submodule. | Chooses `oms branch switch` (new local branch) versus `oms branch checkout` (track a remote branch) and avoids detached HEAD. |
 
 Skill firing is best-effort — an agent loads a skill only when it judges the skill's description relevant — so the skills complement, rather than replace, `oms <command> --help` and the always-on marker block inside `oms/`. Each skill defers exact `oms status --json` field semantics to `oms status --help`, the version-matched authoritative source that ships with the installed CLI.
 
@@ -183,14 +191,14 @@ Skill firing is best-effort — an agent loads a skill only when it judges the s
 
 | Command | Runs in | Does | Notes |
 | --- | --- | --- | --- |
-| `oms init` | current directory | Writes a starter `oms.yaml`. | Refuses if `oms.yaml` exists; use `--force`. Does not gitignore `oms/`. |
-| `oms doctor` | project root or child path | Checks `oms.yaml`, git availability, that the workspace is a git repo, and each alias's submodule state. | Returns exit 2 if any warning is raised. |
+| `oms init` | current directory | Writes a starter `oms.yaml`. | The directory must be outside Git or the root Git top-level. A nested Git-work-tree directory is rejected before writes, even with `--force`. Otherwise refuses an existing manifest unless `--force` is used. Does not gitignore `oms/`. |
+| `oms doctor` | workspace root or child path | Checks the nearest `oms.yaml`, Git root identity, and each alias's submodule state. | Diagnoses a nested manifest directly instead of treating it as a valid root. Returns exit 2 if any warning is raised. |
 | `oms sync <alias>` / `--all` | workspace root | Registers missing repos with `git submodule add`, initializes registered-but-uninitialized ones, fetches, and attaches the baseline branch. | Reproduces the recorded pointer on a fresh clone. Topology changes (`.gitmodules`, `oms/<alias>`) are left unstaged by default; commit them via the prompt or `--commit` (`chore(oms): add ...`). |
 | `oms status [alias...]` / `--all` | anywhere under root | Prints branch, pointer state (`ok`/`moved`/`uninit`/`missing`/`conflict`), dirtiness, and ahead/behind for each submodule. | `moved` means the working commit differs from the recorded pointer — record it with `oms record`. `--json` prints one machine-readable object on stdout for tooling and agents. |
-| `oms commit [alias]` | workspace root or inside `oms/<alias>/` | Commits source changes inside the selected submodule only; never the root gitlink. | `-m <message>` is required (repeatable). Commits existing staged changes as-is, otherwise stages all with `git add -A`. Infers the alias from the current `oms/<alias>/` directory. |
-| `oms record [alias]` | workspace root or inside `oms/<alias>/` | Commits an existing root gitlink pointer update for one alias (`chore(oms): update <alias> submodule to <sha>`). | Root repo only, path-limited to `oms/<alias>`; refuses unrelated staged changes. Not for adds/removals — use `oms sync`/`oms unsync`. |
-| `oms switch [alias] [branch]` | workspace root | `git switch` to a LOCAL branch, creating it locally if it does not exist yet (no remote required). | `--from <ref>` sets the start point for a new branch. Omit alias/branch to pick interactively (or create a new branch). |
-| `oms checkout [alias] [branch]` | workspace root | `git fetch origin --prune`, then check out a REMOTE branch (`origin/*`) as a local tracking branch (or switch to an existing local counterpart). | Omit alias/branch to pick interactively. To create a brand-new local branch, use `oms switch`. |
+| `oms commit [alias]` | workspace root or inside `oms/<alias>/` | Commits source changes inside the selected submodule only; never the root gitlink. | `-m <message>` is required (repeatable). Commits existing staged changes as-is, otherwise stages all with `git add -A`. Infers a configured alias from the current `oms/<alias>/` directory; an explicit alias wins. |
+| `oms record [alias]` | workspace root or inside `oms/<alias>/` | Commits an existing root gitlink pointer update for one alias (`chore(oms): update <alias> submodule to <sha>`). | Root repo only, path-limited to `oms/<alias>`; refuses unrelated staged changes. An explicit alias wins over current-path inference. Not for adds/removals — use `oms sync`/`oms unsync`. |
+| `oms branch switch [alias] [branch]` | workspace root | `git switch` to a LOCAL branch, creating it locally if it does not exist yet (no remote required). | `--from <ref>` sets the start point for a new branch. Omit alias/branch to pick interactively (or create a new branch). |
+| `oms branch checkout [alias] [branch]` | workspace root | `git fetch origin --prune`, then check out a REMOTE branch (`origin/*`) as a local tracking branch (or switch to an existing local counterpart). | Omit alias/branch to pick interactively. To create a brand-new local branch, use `oms branch switch`. |
 | `oms branch list [alias]` | workspace root | Safely prepares one declared submodule, refreshes all declared remotes, and lists local and remote-tracking branches. | Shows baseline certainty, current/baseline flags, exact upstream divergence, detached HEAD, and per-remote `fresh`/`stale`/`unavailable` state. Never switches a branch or changes a root gitlink outside an explicitly accepted `oms sync`. |
 | `oms branch delete [alias] [branch]` | workspace root | Deletes one LOCAL branch inside one initialized submodule with `git branch -d` (safe) or `-D` (`--force`). | Local only — never deletes a remote or remote-tracking ref, never touches the root gitlink. Protects the current branch and every resolved baseline (see below). Omit alias/branch to pick interactively; a registered-but-uninitialized alias is initialized first. Exit 0 on success, 1 on input/precondition errors, 2 on a declined/failed/concurrent deletion. |
 | `oms fetch ...` | workspace root | `git fetch <remote> --prune` in each submodule. | `--remote <name>` (repeatable) picks the remote(s); omit to choose interactively, defaults to `origin`. |
@@ -256,6 +264,7 @@ JSON schema: [`oms.schema.json`](./oms.schema.json) (also reachable at `https://
 
 Detailed migration steps are organized per version under [`docs/migrations/`](./docs/migrations/).
 
+- [0.13.x → 0.14.0](./docs/migrations/0.13.x-to-0.14.0.md) — relocates `oms switch` / `oms checkout` under the `oms branch` group as `oms branch switch` / `oms branch checkout` (top-level commands removed, no aliases)
 - [0.11.x → 0.12.0](./docs/migrations/0.11.x-to-0.12.0.md) — adds `oms branch delete` and makes `oms sync` reconcile declarative `.gitmodules` metadata with stricter baseline validation and a durable finalization recovery preflight
 - [0.9.x → 0.10.0](./docs/migrations/0.9.x-to-0.10.0.md) — scopes each command to a single Git boundary and makes root pointer commits explicit via `oms record`
 - [0.7.x → 0.8.0](./docs/migrations/0.7.x-to-0.8.0.md) — splits `oms checkout` into `oms switch` (local branches) and `oms checkout` (remote branches)

package/dist/build-info.json

@@ -1 +1 @@
-{"commit":"be1d798a55c5e7fae0b33ef6057661a1ac25a5d7"}
+{"commit":"9ab3e6b650acac13d9fff4b8b091b07721d427ac"}

package/dist/oms.js

@@ -14197,7 +14197,7 @@ import { join as join3 } from "node:path";
 
 // scripts/lib/git.ts
 import { spawnSync } from "node:child_process";
-import { existsSync as existsSync2 } from "node:fs";
+import { existsSync as existsSync2, lstatSync, realpathSync, statSync } from "node:fs";
 import { dirname as dirname2, join as join2, resolve as resolve2 } from "node:path";
 function redactSensitiveUrls(value) {
   return value.replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+(?::[^\s/@]*)?@/gi, "$1[redacted]@").replace(/([?&](?:(?:access|auth|bearer|id|oauth|refresh)?[_-]?token|(?:api|private)?[_-]?key|auth(?:orization)?|(?:client|consumer)?[_-]?secret|credential|jwt|pass(?:word|wd)?|signature)=)[^&\s]+/gi, "$1[redacted]");
@@ -14241,15 +14241,54 @@ function isGitVersionSupported(v2) {
   return v2.minor >= MIN_GIT_MINOR;
 }
 __name(isGitVersionSupported, "isGitVersionSupported");
-function findWorkspaceRoot(options = {}) {
+function resolveWorkspaceManifest(options = {}) {
   let current = resolve2(options.cwd ?? process.cwd());
   while (true) {
-    if (existsSync2(join2(current, MANIFEST_FILENAME))) return current;
-    const parent = dirname2(current);
-    if (parent === current) return null;
-    current = parent;
+    const manifestPath = join2(current, MANIFEST_FILENAME);
+    let entry;
+    try {
+      entry = lstatSync(manifestPath);
+    } catch (error) {
+      const code = error instanceof Error && "code" in error ? error.code : void 0;
+      if (code === "ENOENT") {
+        const parent = dirname2(current);
+        if (parent === current) return { kind: "missing" };
+        current = parent;
+        continue;
+      }
+      return {
+        kind: "invalid",
+        manifestPath,
+        reason: error instanceof Error ? error.message : String(error)
+      };
+    }
+    try {
+      if (entry.isFile() || entry.isSymbolicLink() && statSync(manifestPath).isFile()) {
+        return { kind: "found", manifestPath, repoRoot: current };
+      }
+    } catch {
+      return {
+        kind: "invalid",
+        manifestPath,
+        reason: "it is a broken symbolic link or does not resolve to a regular file"
+      };
+    }
+    return {
+      kind: "invalid",
+      manifestPath,
+      reason: "it is not a regular file or a symbolic link to a regular file"
+    };
   }
 }
+__name(resolveWorkspaceManifest, "resolveWorkspaceManifest");
+function findWorkspaceRoot(options = {}) {
+  const resolution = resolveWorkspaceManifest(options);
+  if (resolution.kind === "found") return resolution.repoRoot;
+  if (resolution.kind === "missing") return null;
+  throw new Error(
+    `Found ${MANIFEST_FILENAME} at ${resolution.manifestPath}, but ${resolution.reason}. Replace that entry with a regular file; OMS will not fall back to an ancestor manifest.`
+  );
+}
 __name(findWorkspaceRoot, "findWorkspaceRoot");
 function aliasDir(repoRoot, alias) {
   return join2(repoRoot, DATA_DIRNAME, alias);
@@ -14259,10 +14298,34 @@ function submodulePath(alias) {
   return `${DATA_DIRNAME}/${alias}`;
 }
 __name(submodulePath, "submodulePath");
-function isGitRepo(repoRoot) {
-  return runGit(repoRoot, ["rev-parse", "--is-inside-work-tree"]).stdout.trim() === "true";
+function inspectWorkspaceGitIdentity(workspaceRoot) {
+  const topLevel = runGit(workspaceRoot, ["rev-parse", "--show-toplevel"], false, {
+    ...process.env,
+    LANG: "C",
+    LC_ALL: "C"
+  });
+  if (!topLevel.success) {
+    const diagnostic = topLevel.stderr.trim();
+    if (/not a git repository|not a git work tree/i.test(diagnostic)) return { kind: "no-work-tree" };
+    return {
+      kind: "indeterminate",
+      reason: diagnostic || "Git did not return a repository top-level"
+    };
+  }
+  const gitTopLevel = process.platform === "win32" ? topLevel.stdout.replace(/\r?\n$/, "") : topLevel.stdout.replace(/\n$/, "");
+  if (!gitTopLevel) {
+    return { kind: "indeterminate", reason: "Git returned an empty repository top-level" };
+  }
+  try {
+    return realpathSync(workspaceRoot) === realpathSync(gitTopLevel) ? { kind: "match", gitTopLevel } : { kind: "mismatch", gitTopLevel };
+  } catch (error) {
+    return {
+      kind: "indeterminate",
+      reason: error instanceof Error ? error.message : String(error)
+    };
+  }
 }
-__name(isGitRepo, "isGitRepo");
+__name(inspectWorkspaceGitIdentity, "inspectWorkspaceGitIdentity");
 function registeredSubmodulePaths(repoRoot) {
   if (!existsSync2(join2(repoRoot, ".gitmodules"))) return [];
   const result = runGit(repoRoot, [
@@ -14650,6 +14713,7 @@ function abortOnLegacyRenameAt(repoRoot) {
 }
 __name(abortOnLegacyRenameAt, "abortOnLegacyRenameAt");
 function emitLegacyRenameHintWalkUp(options = {}) {
+  if (resolveWorkspaceManifest(options).kind !== "missing") return false;
   let current = resolve3(options.cwd ?? process.cwd());
   while (true) {
     if (existsSync4(join4(current, LEGACY_MANIFEST))) {
@@ -14676,22 +14740,51 @@ function abortOnLegacyWorktree(repoRoot, repos) {
 }
 __name(abortOnLegacyWorktree, "abortOnLegacyWorktree");
 function loadRepos(options = {}) {
-  const repoRoot = findWorkspaceRoot(options);
-  if (!repoRoot) {
+  const resolution = resolveWorkspaceManifest(options);
+  if (resolution.kind === "missing") {
     R2.error(
       `Could not find ${MANIFEST_FILENAME} in the current directory or its parents. Create a ${MANIFEST_FILENAME} in this project, then retry.`
     );
     return null;
   }
+  if (resolution.kind === "invalid") {
+    R2.error(
+      `Found ${MANIFEST_FILENAME} at ${resolution.manifestPath}, but ${resolution.reason}. Replace that entry with a regular file; OMS will not fall back to an ancestor manifest.`
+    );
+    return null;
+  }
   try {
-    const manifestPath = join4(repoRoot, MANIFEST_FILENAME);
-    return { repos: validateSources((0, import_yaml.parse)(readFileSync3(manifestPath, "utf8"))), repoRoot };
+    return {
+      repos: validateSources((0, import_yaml.parse)(readFileSync3(resolution.manifestPath, "utf8"))),
+      repoRoot: resolution.repoRoot
+    };
   } catch (e2) {
     R2.error(e2 instanceof Error ? e2.message : String(e2));
     return null;
   }
 }
 __name(loadRepos, "loadRepos");
+function emitWorkspaceGitIdentityError(repoRoot) {
+  const identity = inspectWorkspaceGitIdentity(repoRoot);
+  if (identity.kind === "match") return false;
+  if (identity.kind === "no-work-tree") {
+    R2.error(
+      `${repoRoot} is not a git repository. oh-my-space manages sources as git submodules; run "git init" at the workspace root first.`
+    );
+    return true;
+  }
+  if (identity.kind === "mismatch") {
+    R2.error(
+      `Workspace manifest directory ${repoRoot} does not match the root Git top-level ${identity.gitTopLevel}. Move ${MANIFEST_FILENAME} to ${identity.gitTopLevel}, or initialize a separate Git repository at ${repoRoot}.`
+    );
+    return true;
+  }
+  R2.error(
+    `Could not verify that workspace ${repoRoot} is the root Git top-level: ${identity.reason}. Retry after the workspace path and Git repository are accessible.`
+  );
+  return true;
+}
+__name(emitWorkspaceGitIdentityError, "emitWorkspaceGitIdentityError");
 function loadForSubmodules() {
   const loaded = loadRepos();
   if (!loaded) {
@@ -14700,19 +14793,14 @@ function loadForSubmodules() {
   }
   const { repoRoot, repos } = loaded;
   if (abortOnLegacyRenameAt(repoRoot)) return null;
-  if (!isGitRepo(repoRoot)) {
-    R2.error(
-      `${repoRoot} is not a git repository. oh-my-space 0.6.0 manages sources as git submodules; run "git init" at the workspace root first.`
-    );
-    return null;
-  }
+  if (emitWorkspaceGitIdentityError(repoRoot)) return null;
   if (abortOnLegacyWorktree(repoRoot, repos)) return null;
   return loaded;
 }
 __name(loadForSubmodules, "loadForSubmodules");
 
 // scripts/lib/status.ts
-import { existsSync as existsSync5, lstatSync, readdirSync } from "node:fs";
+import { existsSync as existsSync5, lstatSync as lstatSync2, readdirSync } from "node:fs";
 import { relative, resolve as resolve4 } from "node:path";
 function pinState(repoRoot, alias) {
   const r = runGit(repoRoot, ["submodule", "status", "--", submodulePath(alias)]);
@@ -14883,7 +14971,7 @@ __name(partialRemovalTopology, "partialRemovalTopology");
 function readAliasDirEntries(repoRoot, alias) {
   const dir = aliasDir(repoRoot, alias);
   try {
-    if (!lstatSync(dir).isDirectory()) return { exists: true, kind: "file" };
+    if (!lstatSync2(dir).isDirectory()) return { exists: true, kind: "file" };
     return { exists: true, kind: "dir", entries: readdirSync(dir) };
   } catch (error) {
     if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
@@ -15305,7 +15393,7 @@ import {
   constants as fsConstants,
   copyFileSync,
   fsyncSync,
-  lstatSync as lstatSync2,
+  lstatSync as lstatSync3,
   mkdirSync as mkdirSync2,
   openSync as openSync2,
   readFileSync as readFileSync6,
@@ -15318,7 +15406,7 @@ import {
 import { dirname as dirname4, join as join7 } from "node:path";
 
 // scripts/lib/gitmodules-reconcile.ts
-import { chmodSync, closeSync, existsSync as existsSync7, openSync, readFileSync as readFileSync5, renameSync, rmSync as rmSync2, statSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { chmodSync, closeSync, existsSync as existsSync7, openSync, readFileSync as readFileSync5, renameSync, rmSync as rmSync2, statSync as statSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { join as join6 } from "node:path";
 function shq(arg) {
   return `'${arg.replace(/'/g, "'\\''")}'`;
@@ -15401,7 +15489,7 @@ function reconcileGitmodules(repoRoot, plans, snapshot) {
   if (changedFields.size === 0) return { ok: true, changedFields };
   let originalMode;
   try {
-    originalMode = statSync(gitmodules).mode & 511;
+    originalMode = statSync2(gitmodules).mode & 511;
   } catch {
     return { ok: false, retained: "original", reason: "could not read .gitmodules file mode", unapplied: aliases };
   }
@@ -15447,7 +15535,7 @@ __name(gitDir, "gitDir");
 function omsStateDir(repoRoot) {
   const dir = join7(gitDir(repoRoot), "oms");
   if (pathExists(dir)) {
-    const stat = lstatSync2(dir);
+    const stat = lstatSync3(dir);
     if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`unsafe OMS state directory: ${dir}`);
   } else {
     mkdirSync2(dir, { recursive: true, mode: 448 });
@@ -15461,7 +15549,7 @@ function markerPath(repoRoot) {
 __name(markerPath, "markerPath");
 function pathExists(path) {
   try {
-    lstatSync2(path);
+    lstatSync3(path);
     return true;
   } catch (error) {
     if (error.code === "ENOENT") return false;
@@ -15471,7 +15559,7 @@ function pathExists(path) {
 __name(pathExists, "pathExists");
 function pathIsSymlink(path) {
   try {
-    return lstatSync2(path).isSymbolicLink();
+    return lstatSync3(path).isSymbolicLink();
   } catch {
     return false;
   }
@@ -15837,7 +15925,7 @@ function buildRecoveryIndex(repoRoot, realIndex, recoveryIndex, newHead, committ
 __name(buildRecoveryIndex, "buildRecoveryIndex");
 function installRecoveryIndex(realIndex, recoveryIndex, expectedHash) {
   try {
-    if (!lstatSync2(recoveryIndex).isFile() || lstatSync2(recoveryIndex).isSymbolicLink()) return false;
+    if (!lstatSync3(recoveryIndex).isFile() || lstatSync3(recoveryIndex).isSymbolicLink()) return false;
   } catch {
     return false;
   }
@@ -15900,7 +15988,7 @@ function recoveryPreflight(repoRoot) {
   const stateDir = join7(gitDir(repoRoot), "oms");
   let stateExists = false;
   try {
-    const stat = lstatSync2(stateDir);
+    const stat = lstatSync3(stateDir);
     if (!stat.isDirectory() || stat.isSymbolicLink()) {
       return { ok: false, reason: `unsafe OMS state directory: ${stateDir}` };
     }
@@ -16033,7 +16121,7 @@ async function resolveInitializedAlias(repos, repoRoot, alias, actionLabel) {
   }
   const initialized2 = repos.filter((r) => submoduleInitialized(repoRoot, r.alias));
   if (initialized2.length === 0) {
-    R2.error(`No synced submodules to ${actionLabel}. Run "oms sync" first.`);
+    R2.error(`No synced submodules available for "oms ${actionLabel}". Run "oms sync" first.`);
     return null;
   }
   if (!process.stdin.isTTY) {
@@ -16041,7 +16129,7 @@ async function resolveInitializedAlias(repos, repoRoot, alias, actionLabel) {
     return null;
   }
   const choice = await xe({
-    message: `Select a source repo to ${actionLabel}`,
+    message: `Select a source repo for "oms ${actionLabel}"`,
     options: initialized2.map((r) => ({
       value: r.alias,
       label: r.alias,
@@ -16723,12 +16811,7 @@ async function runSync(aliases, options) {
     printList(repos);
     return 0;
   }
-  if (!isGitRepo(repoRoot)) {
-    R2.error(
-      `${repoRoot} is not a git repository. oh-my-space 0.6.0 manages sources as git submodules; run "git init" at the workspace root first.`
-    );
-    return 1;
-  }
+  if (emitWorkspaceGitIdentityError(repoRoot)) return 1;
   if (abortOnLegacyWorktree(repoRoot, repos)) return 1;
   const picked = await selectRepos(repos, aliases, options, "sync");
   if (!picked || picked.length === 0) return 1;
@@ -17118,6 +17201,72 @@ async function runBranchList(aliasArg) {
 }
 __name(runBranchList, "runBranchList");
 
+// scripts/lib/branch-ops.ts
+async function runSwitch(alias, branch, options) {
+  const loaded = loadForSubmodules();
+  if (!loaded) return 1;
+  const { repos, repoRoot } = loaded;
+  const repo = await resolveInitializedAlias(repos, repoRoot, alias, "branch switch");
+  if (!repo) return 1;
+  const dir = aliasDir(repoRoot, repo.alias);
+  let target = branch;
+  if (!target) {
+    const picked = await pickBranch(listLocalBranches(dir), `${repo.alias}: select a local branch`, true);
+    if (!picked) return 1;
+    target = picked;
+  }
+  if (localBranchExists(dir, target)) {
+    R2.step(`${repo.alias}: git switch ${target}`);
+    const r2 = runSub(repoRoot, repo.alias, ["switch", target], true);
+    if (!r2.success) return 2;
+    R2.success(`${repo.alias}: on ${target}`);
+    return 0;
+  }
+  const args = ["switch", "-c", target, ...options.from ? [options.from] : []];
+  R2.step(`${repo.alias}: git ${args.join(" ")}`);
+  const r = runSub(repoRoot, repo.alias, args, true);
+  if (!r.success) return 2;
+  R2.success(`${repo.alias}: created new local branch ${target}. Push it with "oms push ${repo.alias}".`);
+  return 0;
+}
+__name(runSwitch, "runSwitch");
+async function runCheckout(alias, branch) {
+  const loaded = loadForSubmodules();
+  if (!loaded) return 1;
+  const { repos, repoRoot } = loaded;
+  const repo = await resolveInitializedAlias(repos, repoRoot, alias, "branch checkout");
+  if (!repo) return 1;
+  const dir = aliasDir(repoRoot, repo.alias);
+  R2.step(`${repo.alias}: git fetch origin --prune`);
+  const fetch2 = runSub(repoRoot, repo.alias, ["fetch", "origin", "--prune"], true);
+  if (!fetch2.success) return 2;
+  let target = branch;
+  if (!target) {
+    const picked = await pickBranch(listRemoteBranches(dir), `${repo.alias}: select a remote branch (origin/*)`, false);
+    if (!picked) return 1;
+    target = picked;
+  }
+  if (localBranchExists(dir, target)) {
+    R2.step(`${repo.alias}: git switch ${target}`);
+    const r = runSub(repoRoot, repo.alias, ["switch", target], true);
+    if (!r.success) return 2;
+    R2.success(`${repo.alias}: on ${target}`);
+    return 0;
+  }
+  if (remoteBranchExists(dir, target)) {
+    R2.step(`${repo.alias}: git switch -c ${target} origin/${target}`);
+    const r = runSub(repoRoot, repo.alias, ["switch", "-c", target, `origin/${target}`], true);
+    if (!r.success) return 2;
+    R2.success(`${repo.alias}: on ${target} (tracking origin/${target})`);
+    return 0;
+  }
+  R2.error(
+    `${repo.alias}: "${target}" not found on origin. To create a new local branch, run "oms branch switch ${repo.alias} ${target}".`
+  );
+  return 1;
+}
+__name(runCheckout, "runCheckout");
+
 // scripts/lib/branch-delete.ts
 function interactive2() {
   return Boolean(process.stdin.isTTY) || promptQueueActive();
@@ -17136,6 +17285,8 @@ async function runBranch(command) {
     message: "Select a branch action",
     options: [
       { value: "list", label: "list branches in a submodule" },
+      { value: "switch", label: "switch to or create a local branch in a submodule" },
+      { value: "checkout", label: "check out a remote branch in a submodule" },
       { value: "delete", label: "delete a local branch in a submodule" }
     ]
   });
@@ -17144,6 +17295,8 @@ async function runBranch(command) {
     return 1;
   }
   if (action === "list") return runBranchList(void 0);
+  if (action === "switch") return runSwitch(void 0, void 0, {});
+  if (action === "checkout") return runCheckout(void 0, void 0);
   if (action === "delete") return runBranchDelete(void 0, void 0, {});
   return 1;
 }
@@ -17218,7 +17371,7 @@ function checkSubmodulePreconditions(repoRoot, repo) {
     if (!anchored) {
       return {
         ok: false,
-        reason: `${repo.alias}: submodule HEAD is detached and not anchored to the recorded gitlink. Attach it with "oms switch ${repo.alias} <branch>" first.`
+        reason: `${repo.alias}: submodule HEAD is detached and not anchored to the recorded gitlink. Attach it with "oms branch switch ${repo.alias} <branch>" first.`
       };
     }
   }
@@ -17408,72 +17561,6 @@ async function runBranchDelete(aliasArg, branchArg, options) {
 }
 __name(runBranchDelete, "runBranchDelete");
 
-// scripts/lib/branch-ops.ts
-async function runSwitch(alias, branch, options) {
-  const loaded = loadForSubmodules();
-  if (!loaded) return 1;
-  const { repos, repoRoot } = loaded;
-  const repo = await resolveInitializedAlias(repos, repoRoot, alias, "switch");
-  if (!repo) return 1;
-  const dir = aliasDir(repoRoot, repo.alias);
-  let target = branch;
-  if (!target) {
-    const picked = await pickBranch(listLocalBranches(dir), `${repo.alias}: select a local branch`, true);
-    if (!picked) return 1;
-    target = picked;
-  }
-  if (localBranchExists(dir, target)) {
-    R2.step(`${repo.alias}: git switch ${target}`);
-    const r2 = runSub(repoRoot, repo.alias, ["switch", target], true);
-    if (!r2.success) return 2;
-    R2.success(`${repo.alias}: on ${target}`);
-    return 0;
-  }
-  const args = ["switch", "-c", target, ...options.from ? [options.from] : []];
-  R2.step(`${repo.alias}: git ${args.join(" ")}`);
-  const r = runSub(repoRoot, repo.alias, args, true);
-  if (!r.success) return 2;
-  R2.success(`${repo.alias}: created new local branch ${target}. Push it with "oms push ${repo.alias}".`);
-  return 0;
-}
-__name(runSwitch, "runSwitch");
-async function runCheckout(alias, branch) {
-  const loaded = loadForSubmodules();
-  if (!loaded) return 1;
-  const { repos, repoRoot } = loaded;
-  const repo = await resolveInitializedAlias(repos, repoRoot, alias, "checkout");
-  if (!repo) return 1;
-  const dir = aliasDir(repoRoot, repo.alias);
-  R2.step(`${repo.alias}: git fetch origin --prune`);
-  const fetch2 = runSub(repoRoot, repo.alias, ["fetch", "origin", "--prune"], true);
-  if (!fetch2.success) return 2;
-  let target = branch;
-  if (!target) {
-    const picked = await pickBranch(listRemoteBranches(dir), `${repo.alias}: select a remote branch (origin/*)`, false);
-    if (!picked) return 1;
-    target = picked;
-  }
-  if (localBranchExists(dir, target)) {
-    R2.step(`${repo.alias}: git switch ${target}`);
-    const r = runSub(repoRoot, repo.alias, ["switch", target], true);
-    if (!r.success) return 2;
-    R2.success(`${repo.alias}: on ${target}`);
-    return 0;
-  }
-  if (remoteBranchExists(dir, target)) {
-    R2.step(`${repo.alias}: git switch -c ${target} origin/${target}`);
-    const r = runSub(repoRoot, repo.alias, ["switch", "-c", target, `origin/${target}`], true);
-    if (!r.success) return 2;
-    R2.success(`${repo.alias}: on ${target} (tracking origin/${target})`);
-    return 0;
-  }
-  R2.error(
-    `${repo.alias}: "${target}" not found on origin. To create a new local branch, run "oms switch ${repo.alias} ${target}".`
-  );
-  return 1;
-}
-__name(runCheckout, "runCheckout");
-
 // scripts/lib/commit.ts
 async function runCommit(alias, options) {
   const loaded = loadForSubmodules();
@@ -17496,7 +17583,7 @@ async function runCommit(alias, options) {
     return 1;
   }
   if (currentBranch(dir) === null) {
-    R2.error(`${selected}: detached HEAD. Run "oms switch ${selected} <branch>" before committing.`);
+    R2.error(`${selected}: detached HEAD. Run "oms branch switch ${selected} <branch>" before committing.`);
     return 1;
   }
   const messages = options.message ?? [];
@@ -17609,7 +17696,7 @@ async function runDoctor() {
   }
   const { repos, repoRoot } = loaded;
   if (abortOnLegacyRenameAt(repoRoot)) return 1;
-  R2.success(`Workspace root: ${repoRoot}`);
+  R2.success(`Workspace manifest directory: ${repoRoot}`);
   R2.success(`${MANIFEST_FILENAME}: ${repos.length} repo(s) configured`);
   const git = spawnSync3("git", ["--version"], {
     encoding: "utf8",
@@ -17633,12 +17720,26 @@ async function runDoctor() {
     );
     warnings++;
   }
-  if (!isGitRepo(repoRoot)) {
+  const identity = inspectWorkspaceGitIdentity(repoRoot);
+  if (identity.kind === "no-work-tree") {
     R2.warn(
       `workspace is not a git repository. oms manages sources as submodules; run "git init" at ${repoRoot}.`
     );
-    warnings++;
+    return 2;
+  }
+  if (identity.kind === "mismatch") {
+    R2.error(
+      `Workspace manifest directory ${repoRoot} does not match the root Git top-level ${identity.gitTopLevel}. Move ${MANIFEST_FILENAME} to ${identity.gitTopLevel}, or initialize a separate Git repository at ${repoRoot}.`
+    );
+    return 1;
   }
+  if (identity.kind === "indeterminate") {
+    R2.error(
+      `Could not verify that workspace ${repoRoot} is the root Git top-level: ${identity.reason}. Retry after the workspace path and Git repository are accessible.`
+    );
+    return 1;
+  }
+  R2.success(`Workspace root: ${repoRoot}`);
   if (abortOnLegacyWorktree(repoRoot, repos)) return 1;
   if (gitignoreIgnoresOms(repoRoot)) {
     R2.warn(`.gitignore excludes ${GITIGNORE_ENTRY}, but submodules must be tracked. Run "oms sync" to remove it.`);
@@ -17657,7 +17758,7 @@ async function runDoctor() {
     const dir = aliasDir(repoRoot, repo.alias);
     const branch = currentBranch(dir);
     if (!branch) {
-      R2.warn(`${repo.alias}: detached HEAD. Run "oms switch ${repo.alias} <branch>" to get on a branch.`);
+      R2.warn(`${repo.alias}: detached HEAD. Run "oms branch switch ${repo.alias} <branch>" to get on a branch.`);
       warnings++;
     } else {
       R2.success(`${repo.alias}: submodule OK (branch=${branch})`);
@@ -17672,6 +17773,16 @@ __name(runDoctor, "runDoctor");
 
 // scripts/lib/help.ts
 var exitHelp = "\nExit codes: 0 ok | 1 usage/config error | 2 one or more git operations failed.";
+var workspaceContextHelp = `
+Workspace discovery uses the nearest oms.yaml from the current directory upward. An invalid nearest
+candidate is an error; OMS never falls back to a more distant manifest. Commands that inspect or change
+submodules require that manifest directory to be the root Git top-level. Move a nested manifest to the
+Git root, or initialize a separate Git repository at the intended workspace root.
+`;
+var initHelp = `
+The current directory must be outside a Git work tree or be its root top-level. Init refuses a child of
+an existing Git work tree before changing any file, including with --force.
+`;
 var statusHelp = `
 Machine-readable mode prints exactly one JSON object on stdout. The schemaVersion 1 payload has seven
 top-level keys: schemaVersion, toolVersion, workspaceRoot, currentAlias, root, repos, and errors.
@@ -17686,6 +17797,7 @@ Examples:
 var commitHelp = `
 Scope: commits inside the selected oms/<alias>/ submodule only \u2014 never the root gitlink. Existing staged
 changes are committed as-is (staged-first); otherwise all changes are staged with git add -A.
+An explicit alias takes precedence over an alias inferred from the current configured oms/<alias>/ path.
 Examples:
   $ oms commit api -m "feat: add login"   # commit submodule source changes
   $ oms commit -m "fix: typo"             # infer the alias from the current oms/<alias>/ directory
@@ -17693,6 +17805,7 @@ Examples:
 var recordHelp = `
 Scope: commits an existing root gitlink pointer update for one alias in the ROOT repository only
 (chore(oms): update <alias> submodule to <sha>). It never adds or removes a submodule registration.
+An explicit alias takes precedence over an alias inferred from the current configured oms/<alias>/ path.
 Example:
   $ oms record api
 `;
@@ -17760,15 +17873,29 @@ repos:
     branch: main
 `;
 async function runInit(options) {
-  const target = join11(process.cwd(), MANIFEST_FILENAME);
+  const cwd = process.cwd();
+  const target = join11(cwd, MANIFEST_FILENAME);
+  const identity = inspectWorkspaceGitIdentity(cwd);
+  if (identity.kind === "mismatch") {
+    R2.error(
+      `Cannot initialize a workspace at ${cwd} because it is below the root Git top-level ${identity.gitTopLevel}. Run "oms init" at ${identity.gitTopLevel}, or initialize a separate Git repository at ${cwd}.`
+    );
+    return 1;
+  }
+  if (identity.kind === "indeterminate") {
+    R2.error(
+      `Could not verify the workspace target ${cwd}: ${identity.reason}. No files were changed; retry after the path and Git repository are accessible.`
+    );
+    return 1;
+  }
   if (existsSync11(target) && !options.force) {
     R2.error(`${MANIFEST_FILENAME} already exists at ${target}. Use --force to overwrite.`);
     return 1;
   }
   writeFileSync6(target, INIT_TEMPLATE);
   R2.success(`created ${MANIFEST_FILENAME} at ${target}`);
-  ensureOmsNotIgnored(process.cwd());
-  if (!isGitRepo(process.cwd())) {
+  ensureOmsNotIgnored(cwd);
+  if (identity.kind === "no-work-tree") {
     R2.info(`oms manages sources as git submodules; run "git init" here if this is not a git repo yet.`);
   }
   R2.info(`edit alias/remotes/branch, then run "oms sync".`);
@@ -17805,7 +17932,7 @@ function pullRepo(repo, repoRoot, remote) {
   const branch = currentBranch(aliasDir(repoRoot, repo.alias));
   if (!branch) {
     R2.error(
-      `${repo.alias}: detached HEAD. Run "oms switch ${repo.alias} <branch>" before pulling.`
+      `${repo.alias}: detached HEAD. Run "oms branch switch ${repo.alias} <branch>" before pulling.`
     );
     return "failed";
   }
@@ -17834,7 +17961,7 @@ function pushRepo(repo, repoRoot, remotes) {
   const branch = currentBranch(aliasDir(repoRoot, repo.alias));
   if (!branch) {
     R2.error(
-      `${repo.alias}: detached HEAD. Run "oms switch ${repo.alias} <branch>" before pushing.`
+      `${repo.alias}: detached HEAD. Run "oms branch switch ${repo.alias} <branch>" before pushing.`
     );
     return "failed";
   }
@@ -17932,7 +18059,7 @@ import { spawnSync as spawnSync5 } from "node:child_process";
 var import_semver = __toESM(require_semver2(), 1);
 
 // scripts/lib/install-context.ts
-import { existsSync as existsSync12, realpathSync } from "node:fs";
+import { existsSync as existsSync12, realpathSync as realpathSync2 } from "node:fs";
 import { delimiter, dirname as dirname5, join as join12, resolve as resolve5 } from "node:path";
 function formatCommand(command) {
   return [command.executable, ...command.args].join(" ");
@@ -17947,7 +18074,7 @@ function globalUpdateCommand(manager) {
 __name(globalUpdateCommand, "globalUpdateCommand");
 function safeRealpath(path) {
   try {
-    return realpathSync(path);
+    return realpathSync2(path);
   } catch {
     return path;
   }
@@ -18438,8 +18565,6 @@ var commandNames = /* @__PURE__ */ new Set([
   "status",
   "commit",
   "record",
-  "switch",
-  "checkout",
   "branch",
   "fetch",
   "pull",
@@ -18454,42 +18579,42 @@ var collectRepeatable = /* @__PURE__ */ __name((value, acc) => [...acc, value],
 var program2 = new Command();
 program2.name("oms").description(
   `Manage source repositories listed in ${MANIFEST_FILENAME} as git submodules under ${DATA_DIRNAME}/<alias>/.`
-).version(readPackageVersion()).addHelpText("after", exitHelp);
-program2.command("init").description(`Create a starter ${MANIFEST_FILENAME} in the current directory.`).option("--force", `overwrite an existing ${MANIFEST_FILENAME}`).addHelpText("after", exitHelp).action(async (options) => {
+).version(readPackageVersion()).addHelpText("after", `${workspaceContextHelp}${exitHelp}`);
+program2.command("init").description(`Create a starter ${MANIFEST_FILENAME} in the current directory.`).option("--force", `overwrite an existing ${MANIFEST_FILENAME}`).addHelpText("after", `${initHelp}${exitHelp}`).action(async (options) => {
   await exitWith(runInit(options));
 });
 program2.command("doctor").description(
   `Check ${MANIFEST_FILENAME}, git availability, and the submodule state of each registered alias.`
-).addHelpText("after", exitHelp).action(async () => {
+).addHelpText("after", `${workspaceContextHelp}${exitHelp}`).action(async () => {
   await exitWith(runDoctor());
 });
 program2.command("sync").description(
   `Register each repo as a submodule at ${DATA_DIRNAME}/<alias>/ (or initialize and refresh an existing one), checked out on its baseline branch.`
-).argument("[aliases...]", "repo aliases to sync (omit for interactive multi-select)").option("--all", "sync every registered source repo").option("--list", "print registered repos").option("--commit", "create the root topology commit (chore(oms): add ...) without prompting").addHelpText("after", `${syncHelp}${exitHelp}`).action(async (aliases, options) => {
+).argument("[aliases...]", "repo aliases to sync (omit for interactive multi-select)").option("--all", "sync every registered source repo").option("--list", "print registered repos").option("--commit", "create the root topology commit (chore(oms): add ...) without prompting").addHelpText("after", `${syncHelp}${workspaceContextHelp}${exitHelp}`).action(async (aliases, options) => {
   await exitWith(runSync(aliases, options));
 });
-program2.command("status").description("Show each submodule's branch, pointer state, dirtiness, and ahead/behind counts.").argument("[aliases...]", "repo aliases to inspect (omit for all)").option("--all", "inspect every registered source repo").option("--json", "print machine-readable workspace state (one JSON object on stdout)").addHelpText("after", `${statusHelp}${exitHelp}`).action(async (aliases, options) => {
+program2.command("status").description("Show each submodule's branch, pointer state, dirtiness, and ahead/behind counts.").argument("[aliases...]", "repo aliases to inspect (omit for all)").option("--all", "inspect every registered source repo").option("--json", "print machine-readable workspace state (one JSON object on stdout)").addHelpText("after", `${statusHelp}${workspaceContextHelp}${exitHelp}`).action(async (aliases, options) => {
   await exitWith(runStatus(aliases, options));
 });
-program2.command("commit").description("Commit source changes inside the selected submodule only (never the root gitlink).").argument("[alias]", "registered source alias (omit to infer from the current oms/<alias>/ directory)").option("-m, --message <message>", "commit message (repeatable; required only to create a commit)", collectRepeatable, []).addHelpText("after", `${commitHelp}${exitHelp}`).action(async (alias, options) => {
+program2.command("commit").description("Commit source changes inside the selected submodule only (never the root gitlink).").argument("[alias]", "registered source alias (omit to infer from the current oms/<alias>/ directory)").option("-m, --message <message>", "commit message (repeatable; required only to create a commit)", collectRepeatable, []).addHelpText("after", `${commitHelp}${workspaceContextHelp}${exitHelp}`).action(async (alias, options) => {
   await exitWith(runCommit(alias, options));
 });
-program2.command("record").description("Commit an existing root gitlink pointer update for the selected submodule (root repo only).").argument("[alias]", "registered source alias (omit to infer from the current oms/<alias>/ directory)").addHelpText("after", `${recordHelp}${exitHelp}`).action(async (alias) => {
+program2.command("record").description("Commit an existing root gitlink pointer update for the selected submodule (root repo only).").argument("[alias]", "registered source alias (omit to infer from the current oms/<alias>/ directory)").addHelpText("after", `${recordHelp}${workspaceContextHelp}${exitHelp}`).action(async (alias) => {
   await exitWith(runRecord(alias));
 });
-program2.command("switch").description(
+var branchCommand = program2.command("branch").description("Inspect, switch, checkout, or delete submodule branches (interactive action selector).").addHelpText("after", `${workspaceContextHelp}${exitHelp}`).action(async () => {
+  await exitWith(runBranch(branchCommand));
+});
+branchCommand.command("switch").description(
   "Switch a submodule to a LOCAL branch, creating it locally if it does not exist yet (no remote required)."
-).argument("[alias]", "registered source alias (omit to pick interactively)").argument("[branch]", "local branch name (omit to pick from local branches or create one)").option("--from <ref>", "start point for a new branch (default: current HEAD)").addHelpText("after", exitHelp).action(async (alias, branch, options) => {
+).argument("[alias]", "registered source alias (omit to pick interactively)").argument("[branch]", "local branch name (omit to pick from local branches or create one)").option("--from <ref>", "start point for a new branch (default: current HEAD)").addHelpText("after", `${workspaceContextHelp}${exitHelp}`).action(async (alias, branch, options) => {
   await exitWith(runSwitch(alias, branch, options));
 });
-program2.command("checkout").description(
+branchCommand.command("checkout").description(
   "Fetch origin, then check out a REMOTE branch (origin/*) as a local tracking branch."
-).argument("[alias]", "registered source alias (omit to pick interactively)").argument("[branch]", "remote branch name (omit to pick from origin/* branches)").addHelpText("after", exitHelp).action(async (alias, branch) => {
+).argument("[alias]", "registered source alias (omit to pick interactively)").argument("[branch]", "remote branch name (omit to pick from origin/* branches)").addHelpText("after", `${workspaceContextHelp}${exitHelp}`).action(async (alias, branch) => {
   await exitWith(runCheckout(alias, branch));
 });
-var branchCommand = program2.command("branch").description("Inspect or delete submodule branches (interactive action selector).").addHelpText("after", exitHelp).action(async () => {
-  await exitWith(runBranch(branchCommand));
-});
 branchCommand.command("list").description("Prepare one submodule, refresh declared remotes, and list local and remote branches.").argument("[alias]", "declared source alias (the sole alias is selected automatically)").addHelpText(
   "after",
   `
@@ -18502,31 +18627,31 @@ Behavior:
 Examples:
   $ oms branch list api
   $ oms branch list
-${exitHelp}`
+${workspaceContextHelp}${exitHelp}`
 ).action(async (alias) => {
   await exitWith(runBranchList(alias));
 });
 branchCommand.command("delete").description(
   "Delete a LOCAL branch inside one initialized submodule (never a remote branch or the root gitlink)."
-).argument("[alias]", "registered source alias (omit to pick interactively)").argument("[branch]", "local branch name (omit to pick from deletable local branches)").option("-f, --force", "force-delete with git branch -D (still respects protected branches)").addHelpText("after", exitHelp).action(async (alias, branch, options) => {
+).argument("[alias]", "registered source alias (omit to pick interactively)").argument("[branch]", "local branch name (omit to pick from deletable local branches)").option("-f, --force", "force-delete with git branch -D (still respects protected branches)").addHelpText("after", `${workspaceContextHelp}${exitHelp}`).action(async (alias, branch, options) => {
   await exitWith(runBranchDelete(alias, branch, options));
 });
-program2.command("fetch").description("Run git fetch <remote> --prune in each submodule (defaults to origin).").argument("[aliases...]", "repo aliases to fetch (omit for interactive multi-select)").option("--all", "fetch every registered source repo").option("--remote <name>", "remote to fetch (repeatable; omit to choose interactively)", collectRepeatable, []).addHelpText("after", exitHelp).action(async (aliases, options) => {
+program2.command("fetch").description("Run git fetch <remote> --prune in each submodule (defaults to origin).").argument("[aliases...]", "repo aliases to fetch (omit for interactive multi-select)").option("--all", "fetch every registered source repo").option("--remote <name>", "remote to fetch (repeatable; omit to choose interactively)", collectRepeatable, []).addHelpText("after", `${workspaceContextHelp}${exitHelp}`).action(async (aliases, options) => {
   await exitWith(runManage("fetch", aliases, options));
 });
 program2.command("pull").description(
   "Pull the submodule branch only (git pull --ff-only <remote>); never stages or commits the root gitlink (defaults to origin)."
-).argument("[aliases...]", "repo aliases to pull (omit for interactive multi-select)").option("--all", "pull every registered source repo").option("--remote <name>", "remote to pull from (single; omit to choose interactively)", collectRepeatable, []).addHelpText("after", `${pullHelp}${exitHelp}`).action(async (aliases, options) => {
+).argument("[aliases...]", "repo aliases to pull (omit for interactive multi-select)").option("--all", "pull every registered source repo").option("--remote <name>", "remote to pull from (single; omit to choose interactively)", collectRepeatable, []).addHelpText("after", `${pullHelp}${workspaceContextHelp}${exitHelp}`).action(async (aliases, options) => {
   await exitWith(runManage("pull", aliases, options));
 });
 program2.command("push").description(
   'Push the submodule branch only (creating the remote branch on first push); never stages or commits the root gitlink. Use "oms record <alias>" for root pointer commits (defaults to origin).'
-).argument("<aliases...>", "repo aliases to push").option("--commit", 'unsupported: use "oms record <alias>" after pushing').option("--record", 'unsupported: use "oms record <alias>" after pushing').option("--remote <name>", "remote to push to (repeatable; omit to choose interactively)", collectRepeatable, []).addHelpText("after", `${pushHelp}${exitHelp}`).action(async (aliases, options) => {
+).argument("<aliases...>", "repo aliases to push").option("--commit", 'unsupported: use "oms record <alias>" after pushing').option("--record", 'unsupported: use "oms record <alias>" after pushing').option("--remote <name>", "remote to push to (repeatable; omit to choose interactively)", collectRepeatable, []).addHelpText("after", `${pushHelp}${workspaceContextHelp}${exitHelp}`).action(async (aliases, options) => {
   await exitWith(runManage("push", aliases, options));
 });
 program2.command("unsync").description(
   `Deinitialize and remove the submodule for each alias (keeps ${MANIFEST_FILENAME} entry).`
-).argument("[aliases...]", "repo aliases to unsync (omit for interactive multi-select)").option("--all", "unsync every registered source repo").option("--force", "discard uncommitted changes in the submodule").option("--commit", "create the root topology commit (chore(oms): remove ...) without prompting").addHelpText("after", `${unsyncHelp}${exitHelp}`).action(async (aliases, options) => {
+).argument("[aliases...]", "repo aliases to unsync (omit for interactive multi-select)").option("--all", "unsync every registered source repo").option("--force", "discard uncommitted changes in the submodule").option("--commit", "create the root topology commit (chore(oms): remove ...) without prompting").addHelpText("after", `${unsyncHelp}${workspaceContextHelp}${exitHelp}`).action(async (aliases, options) => {
   await exitWith(runUnsync(aliases, options));
 });
 var agentCommand = program2.command("agent").description(`Manage OMS agent instruction blocks under ${DATA_DIRNAME}/ (AGENTS.md, CLAUDE.md).`).addHelpText("after", exitHelp);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-space",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "Manage multi-repo workspaces with Git submodules.",
   "license": "MIT",
   "homepage": "https://github.com/divlook/oh-my-space",