@openvcs/git-plugin 0.1.0-nightly.20260421.19 → 0.2.0-beta.40

package/README.md

@@ -65,11 +65,13 @@ The npm package can be consumed from prerelease channels published by CI:
 
 - `latest`: stable releases
 - `beta`: builds from the `Beta` branch
+- `edge`: working builds from `Dev` push commits
 - `nightly`: scheduled builds from `Dev` when there are changes since the last nightly
 
 Examples:
 
 ```bash
+npm install @openvcs/git-plugin@edge
 npm install @openvcs/git-plugin@beta
 npm install @openvcs/git-plugin@nightly
 ```

package/bin/git.js

@@ -163,26 +163,41 @@ export class GitCommand {
         const args = buildPullFfOnlyArgs(options);
         return this.runChecked(args, 'git-pull-failed');
     }
-    commit(message) {
-        return this.runChecked(['commit', '-m', message], 'git-commit-failed');
+    /** Returns the current HEAD commit id. */
+    currentHead() {
+        return this.runChecked(['rev-parse', 'HEAD'], 'git-head-failed').stdout.trim();
     }
-    commitIndex(message, name, email, paths) {
-        const args = ['commit'];
-        if (paths && paths.length > 0) {
-            args.push('--', ...paths);
-        }
-        else {
-            args.push('-a');
-        }
+    /** Creates a commit, optionally limited to the provided paths. */
+    commit(message, name, email, paths) {
+        const execArgs = [
+            ...(name ? ['-c', `user.name=${name}`] : []),
+            ...(email ? ['-c', `user.email=${email}`] : []),
+            'commit',
+            '-m',
+            message,
+            ...(paths && paths.length > 0 ? ['--', ...paths] : []),
+        ];
+        return this.runChecked(execArgs, 'git-commit-failed');
+    }
+    /** Creates a commit from the current index only. */
+    commitIndex(message, name, email) {
         const commitMessage = message || 'Stage changes';
         const execArgs = [
             ...(name ? ['-c', `user.name=${name}`] : []),
             ...(email ? ['-c', `user.email=${email}`] : []),
-            ...args,
-            '-m', commitMessage,
+            'commit',
+            '-m',
+            commitMessage,
         ];
         return this.runChecked(execArgs, 'git-commit-failed');
     }
+    /** Stages the provided repository-relative paths into the index. */
+    stagePaths(paths) {
+        if (paths.length === 0) {
+            return;
+        }
+        this.runChecked(['add', '-A', '--', ...paths], 'git-stage-paths-failed');
+    }
     listCommits(options = {}) {
         const args = ['log', '--all'];
         if (options.topo_order) {
@@ -206,7 +221,7 @@ export class GitCommand {
         if (options.until_utc) {
             args.push(`--until=${options.until_utc}`);
         }
-        args.push('--pretty=format:%H%f%x00%aN%x00%aI%x00%P%x1e');
+        args.push('--pretty=format:%H%x00%s%x00%aN%x00%aI%x00%P%x1e');
         if (options.branch) {
             args.push(options.branch);
         }
@@ -371,8 +386,11 @@ export class GitCommand {
     hashObject(content) {
         return this.run(['hash-object', '-w', '--stdin'], { stdin: content }).stdout.trim();
     }
+    /** Stages a textual patch into the index without requiring worktree/index parity. */
     stagePatch(patch) {
-        this.runChecked(['apply', '--3way', '--index'], 'git-stage-patch-failed', { stdin: patch });
+        this.runChecked(['apply', '--cached', '--unidiff-zero'], 'git-stage-patch-failed', {
+            stdin: patch,
+        });
     }
     applyReversePatch(patch) {
         this.runChecked(['apply', '-R', patch], 'git-apply-reverse-failed');
@@ -383,9 +401,10 @@ export class GitCommand {
     resetSoftTo(ref) {
         this.runChecked(['reset', '--soft', ref], 'git-reset-soft-failed');
     }
+    /** Reads the effective Git commit identity from config. */
     getIdentity() {
-        const nameResult = this.run(['config', '--local', 'user.name']);
-        const emailResult = this.run(['config', '--local', 'user.email']);
+        const nameResult = this.run(['config', '--get', 'user.name']);
+        const emailResult = this.run(['config', '--get', 'user.email']);
         if (nameResult.status !== 0 || emailResult.status !== 0) {
             return null;
         }
@@ -394,6 +413,7 @@ export class GitCommand {
             email: emailResult.stdout.trim(),
         };
     }
+    /** Stores repository-local commit identity in Git config. */
     setIdentityLocal(name, email) {
         this.runChecked(['config', '--local', 'user.name', name], 'git-identity-set-failed');
         this.runChecked(['config', '--local', 'user.email', email], 'git-identity-set-failed');

package/bin/plugin-request-handler.js

@@ -3,6 +3,10 @@
 import { VcsDelegateBase, pluginError, } from '@openvcs/sdk/runtime';
 import { asNumber, asRecord, asString, asStringArray, asTrimmedString, buildCloneArgs, parseStatusOutput, } from './plugin-helpers.js';
 import { GitCommand } from './git.js';
+/** Returns an optional boolean only when the input is already a boolean. */
+function asOptionalBoolean(value) {
+    return typeof value === 'boolean' ? value : undefined;
+}
 /** Reduces a file status string to the primary status code needed for discard routing. */
 function getPrimaryDiscardStatus(status) {
     const normalized = asTrimmedString(status);
@@ -214,15 +218,13 @@ export class GitVcsDelegates extends VcsDelegateBase {
     }
     commit(params, _context) {
         const git = this.requireGit(params.session_id);
-        const result = git.runChecked(['rev-parse', 'HEAD'], 'git-commit-failed');
-        git.commit(asTrimmedString(params.message));
-        return result.stdout.trim();
+        git.commit(asTrimmedString(params.message), asTrimmedString(params.name), asTrimmedString(params.email), asStringArray(params.paths));
+        return git.currentHead();
     }
     commitIndex(params, _context) {
         const git = this.requireGit(params.session_id);
-        const result = git.runChecked(['rev-parse', 'HEAD'], 'git-commit-failed');
-        git.commitIndex(asTrimmedString(params.message), asTrimmedString(params.name), asTrimmedString(params.email), asStringArray(params.paths));
-        return result.stdout.trim();
+        git.commitIndex(asTrimmedString(params.message), asTrimmedString(params.name), asTrimmedString(params.email));
+        return git.currentHead();
     }
     getStatusSummary(params, _context) {
         const git = this.requireGit(params.session_id);
@@ -239,8 +241,8 @@ export class GitVcsDelegates extends VcsDelegateBase {
             branch: asTrimmedString(query.rev) || undefined,
             skip: asNumber(query.skip, 0) || undefined,
             limit: asNumber(query.limit, 0),
-            topo_order: query.topo_order ?? undefined,
-            include_merges: query.include_merges ?? undefined,
+            topo_order: asOptionalBoolean(query.topo_order),
+            include_merges: asOptionalBoolean(query.include_merges),
             author_contains: asTrimmedString(query.author_contains) || undefined,
             since_utc: asTrimmedString(query.since_utc) || undefined,
             until_utc: asTrimmedString(query.until_utc) || undefined,
@@ -280,6 +282,11 @@ export class GitVcsDelegates extends VcsDelegateBase {
         git.stagePatch(asString(params.patch));
         return null;
     }
+    stagePaths(params, _context) {
+        const git = this.requireGit(params.session_id);
+        git.stagePaths(asStringArray(params.paths));
+        return null;
+    }
     discardPaths(params, _context) {
         const git = this.requireGit(params.session_id);
         const paths = asStringArray(params.paths);
@@ -288,15 +295,29 @@ export class GitVcsDelegates extends VcsDelegateBase {
         }
         const status = git.runChecked(['status', '--porcelain=1', '-z', '-uall', '--', ...paths], 'git-discard-paths-failed');
         const discardPlan = planDiscardPaths(status.stdout);
+        let failure;
         if (discardPlan.unstageThenRemove.length > 0) {
-            git.runChecked(['rm', '-f', '--cached', '--', ...discardPlan.unstageThenRemove], 'git-discard-paths-failed');
+            try {
+                git.runChecked(['rm', '-f', '--cached', '--', ...discardPlan.unstageThenRemove], 'git-discard-paths-failed');
+            }
+            catch (error) {
+                failure = error;
+            }
         }
-        if (discardPlan.restore.length > 0) {
-            git.runChecked(['restore', '--source=HEAD', '--staged', '--worktree', '--', ...discardPlan.restore], 'git-discard-paths-failed');
+        if (!failure && discardPlan.restore.length > 0) {
+            try {
+                git.runChecked(['restore', '--source=HEAD', '--staged', '--worktree', '--', ...discardPlan.restore], 'git-discard-paths-failed');
+            }
+            catch (error) {
+                failure = error;
+            }
         }
-        if (discardPlan.clean.length > 0) {
+        if (!failure && discardPlan.clean.length > 0) {
             git.runChecked(['clean', '-f', '--', ...discardPlan.clean], 'git-discard-paths-failed');
         }
+        if (failure) {
+            throw failure;
+        }
         return null;
     }
     applyReversePatch(params, _context) {

package/bin/plugin.js

@@ -38,7 +38,7 @@ export function OnPluginStart() {
     }
     const delegates = new GitVcsDelegates(createGitRuntimeDependencies());
     PluginDefinition.vcs = delegates.toDelegates();
-    const repoMenu = getOrCreateMenu('repository', 'Repository');
+    const repoMenu = getOrCreateMenu('repository', 'Repository', { surface: 'menubar' });
     if (repoMenu) {
         repoMenu.addItem({ label: 'Edit .gitignore', action: 'repo-edit-gitignore' });
         repoMenu.addItem({ label: 'Edit .gitattributes', action: 'repo-edit-gitattributes' });

package/bin/submodules.js

@@ -18,7 +18,7 @@ function payloadString(payload, key) {
     return String(payload[key] ?? '').trim();
 }
 /** Builds one modal row for a submodule entry. */
-function buildSubmoduleRow(entry) {
+export function buildSubmoduleRow(entry) {
     const metaBits = [entry.commit ? `commit ${entry.commit}` : '', entry.branch ? `branch ${entry.branch}` : '']
         .map((part) => String(part || '').trim())
         .filter(Boolean);
@@ -51,12 +51,44 @@ function buildSubmoduleRow(entry) {
         ],
     };
 }
+/** Builds an error fallback modal with a descriptive message. */
+function buildErrorModal(message) {
+    return new ModalBuilder('Error').text(message).text('Please try again or check the Git repository state.');
+}
+/** Opens a fallback modal for a submodule UI failure and preserves the original error on fallback failure. */
+export async function handleSubmoduleModalError(prefix, error, openFallback = (message) => buildErrorModal(message).open()) {
+    const message = error instanceof Error ? error.message : String(error);
+    const fullMessage = `${prefix}: ${message}`;
+    console.error(`Git submodules: ${fullMessage}`);
+    try {
+        return await openFallback(fullMessage);
+    }
+    catch {
+        throw error;
+    }
+}
 /** Builds and opens the submodule manager modal. */
 async function openSubmodulesModal() {
     const git = createGitCommand();
-    const entries = git.listSubmodules();
+    let entries;
+    try {
+        entries = git.listSubmodules();
+    }
+    catch (error) {
+        return handleSubmoduleModalError('failed to list submodules', error);
+    }
     console.log('Git submodules: building modal', { count: entries.length });
-    const modal = new ModalBuilder('Manage Submodules')
+    const modal = buildSubmodulesModal(entries);
+    try {
+        return await modal.open();
+    }
+    catch (error) {
+        return handleSubmoduleModalError('failed to open modal', error);
+    }
+}
+/** Builds the submodule manager modal with given entries. */
+function buildSubmodulesModal(entries) {
+    return new ModalBuilder('Manage Submodules')
         .text('Review, add, update, sync, and remove submodules without leaving Git.')
         .text('Use Update Remote to follow each submodule branch configured in .gitmodules.')
         .separator()
@@ -109,7 +141,6 @@ async function openSubmodulesModal() {
         emptyText: 'This repository has no submodules yet.',
         items: entries.map((entry) => buildSubmoduleRow(entry)),
     });
-    return modal.open();
 }
 /** Builds and opens the remove confirmation modal for one submodule. */
 async function openRemoveConfirmationModal(path, name) {
@@ -129,7 +160,12 @@ async function openRemoveConfirmationModal(path, name) {
             payload: { path: submodulePath, name: String(name || '').trim() || undefined },
         },
     ], { gap: '.5rem', align: 'centered', wrap: true });
-    return modal.open();
+    try {
+        return await modal.open();
+    }
+    catch (error) {
+        return handleSubmoduleModalError('failed to open remove confirmation modal', error);
+    }
 }
 /** Removes one submodule and refreshes the toolkit modal. */
 async function removeSubmodule(payload) {
@@ -200,7 +236,7 @@ async function syncAllSubmodules() {
 }
 /** Registers the Git submodule toolkit menu and action handlers. */
 export function registerSubmoduleToolkit() {
-    const repoMenu = getOrCreateMenu('repository', 'Repository');
+    const repoMenu = getOrCreateMenu('repository', 'Repository', { surface: 'menubar' });
     repoMenu?.addItem({ label: 'Submodules', action: 'repo-submodules' });
     registerAction('repo-submodules', async () => {
         console.log('Git submodules: repo-submodules action invoked');

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@openvcs/git-plugin",
-  "version": "0.1.0-nightly.20260421.19",
+  "version": "0.2.0-beta.40",
   "description": "OpenVCS Git plugin - Node.js runtime",
   "license": "GPL-3.0-or-later",
   "homepage": "https://github.com/Open-VCS/OpenVCS-Plugin-Git",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Open-VCS/OpenVCS-Plugin-Git"
+    "url": "git+https://github.com/Open-VCS/OpenVCS-Plugin-Git.git"
   },
   "bugs": {
     "url": "https://github.com/Open-VCS/OpenVCS-Plugin-Git/issues"
@@ -18,7 +18,7 @@
   "openvcs": {
     "id": "openvcs.git",
     "name": "Git",
-    "version": "0.1.0-nightly.20260421.19",
+    "version": "0.2.0-beta.40",
     "author": "OpenVCS Contributors",
     "description": "Git VCS backend plugin for OpenVCS",
     "default_enabled": true,

package/src/git.ts

@@ -274,31 +274,49 @@ export class GitCommand {
     return this.runChecked(args, 'git-pull-failed');
   }
 
-  commit(message: string): GitCommandResult {
-    return this.runChecked(['commit', '-m', message], 'git-commit-failed');
+  /** Returns the current HEAD commit id. */
+  currentHead(): string {
+    return this.runChecked(['rev-parse', 'HEAD'], 'git-head-failed').stdout.trim();
   }
 
-  commitIndex(message?: string, name?: string, email?: string, paths?: string[]): GitCommandResult {
-    const args = ['commit'];
-    
-    if (paths && paths.length > 0) {
-      args.push('--', ...paths);
-    } else {
-      args.push('-a');
-    }
-    
+  /** Creates a commit, optionally limited to the provided paths. */
+  commit(message: string, name?: string, email?: string, paths?: string[]): GitCommandResult {
+    const execArgs = [
+      ...(name ? ['-c', `user.name=${name}`] : []),
+      ...(email ? ['-c', `user.email=${email}`] : []),
+      'commit',
+      '-m',
+      message,
+      ...(paths && paths.length > 0 ? ['--', ...paths] : []),
+    ];
+
+    return this.runChecked(execArgs, 'git-commit-failed');
+  }
+
+  /** Creates a commit from the current index only. */
+  commitIndex(message?: string, name?: string, email?: string): GitCommandResult {
     const commitMessage = message || 'Stage changes';
-    
+
     const execArgs = [
       ...(name ? ['-c', `user.name=${name}`] : []),
       ...(email ? ['-c', `user.email=${email}`] : []),
-      ...args,
-      '-m', commitMessage,
+      'commit',
+      '-m',
+      commitMessage,
     ];
-    
+
     return this.runChecked(execArgs, 'git-commit-failed');
   }
 
+  /** Stages the provided repository-relative paths into the index. */
+  stagePaths(paths: string[]): void {
+    if (paths.length === 0) {
+      return;
+    }
+
+    this.runChecked(['add', '-A', '--', ...paths], 'git-stage-paths-failed');
+  }
+
   listCommits(options: ListCommitsOptions = {}): { commits: CommitEntry[]; exitCode: number } {
     const args = ['log', '--all'];
 
@@ -330,7 +348,7 @@ export class GitCommand {
       args.push(`--until=${options.until_utc}`);
     }
 
-    args.push('--pretty=format:%H%f%x00%aN%x00%aI%x00%P%x1e');
+    args.push('--pretty=format:%H%x00%s%x00%aN%x00%aI%x00%P%x1e');
 
     if (options.branch) {
       args.push(options.branch);
@@ -525,8 +543,11 @@ export class GitCommand {
     return this.run(['hash-object', '-w', '--stdin'], { stdin: content }).stdout.trim();
   }
 
+  /** Stages a textual patch into the index without requiring worktree/index parity. */
   stagePatch(patch: string): void {
-    this.runChecked(['apply', '--3way', '--index'], 'git-stage-patch-failed', { stdin: patch });
+    this.runChecked(['apply', '--cached', '--unidiff-zero'], 'git-stage-patch-failed', {
+      stdin: patch,
+    });
   }
 
   applyReversePatch(patch: string): void {
@@ -541,9 +562,10 @@ export class GitCommand {
     this.runChecked(['reset', '--soft', ref], 'git-reset-soft-failed');
   }
 
+  /** Reads the effective Git commit identity from config. */
   getIdentity(): { name: string; email: string } | null {
-    const nameResult = this.run(['config', '--local', 'user.name']);
-    const emailResult = this.run(['config', '--local', 'user.email']);
+    const nameResult = this.run(['config', '--get', 'user.name']);
+    const emailResult = this.run(['config', '--get', 'user.email']);
 
     if (nameResult.status !== 0 || emailResult.status !== 0) {
       return null;
@@ -555,6 +577,7 @@ export class GitCommand {
     };
   }
 
+  /** Stores repository-local commit identity in Git config. */
   setIdentityLocal(name: string, email: string): void {
     this.runChecked(['config', '--local', 'user.name', name], 'git-identity-set-failed');
     this.runChecked(['config', '--local', 'user.email', email], 'git-identity-set-failed');

package/src/plugin-request-handler.ts

@@ -30,6 +30,11 @@ export interface DiscardPathPlan {
   clean: string[];
 }
 
+/** Returns an optional boolean only when the input is already a boolean. */
+function asOptionalBoolean(value: unknown): boolean | undefined {
+  return typeof value === 'boolean' ? value : undefined;
+}
+
 /** Reduces a file status string to the primary status code needed for discard routing. */
 function getPrimaryDiscardStatus(status: string): string {
   const normalized = asTrimmedString(status);
@@ -348,9 +353,13 @@ export class GitVcsDelegates extends VcsDelegateBase<GitRuntimeDependencies> {
     _context: PluginRuntimeContext,
   ): string {
     const git = this.requireGit(params.session_id);
-    const result = git.runChecked(['rev-parse', 'HEAD'], 'git-commit-failed');
-    git.commit(asTrimmedString(params.message));
-    return result.stdout.trim();
+    git.commit(
+      asTrimmedString(params.message),
+      asTrimmedString(params.name),
+      asTrimmedString(params.email),
+      asStringArray(params.paths),
+    );
+    return git.currentHead();
   }
 
   override commitIndex(
@@ -358,14 +367,12 @@ export class GitVcsDelegates extends VcsDelegateBase<GitRuntimeDependencies> {
     _context: PluginRuntimeContext,
   ): string {
     const git = this.requireGit(params.session_id);
-    const result = git.runChecked(['rev-parse', 'HEAD'], 'git-commit-failed');
     git.commitIndex(
       asTrimmedString(params.message),
       asTrimmedString(params.name),
       asTrimmedString(params.email),
-      asStringArray(params.paths),
     );
-    return result.stdout.trim();
+    return git.currentHead();
   }
 
   override getStatusSummary(
@@ -394,8 +401,8 @@ export class GitVcsDelegates extends VcsDelegateBase<GitRuntimeDependencies> {
       branch: asTrimmedString(query.rev) || undefined,
       skip: asNumber(query.skip, 0) || undefined,
       limit: asNumber(query.limit, 0),
-      topo_order: query.topo_order as boolean ?? undefined,
-      include_merges: query.include_merges as boolean ?? undefined,
+      topo_order: asOptionalBoolean(query.topo_order),
+      include_merges: asOptionalBoolean(query.include_merges),
       author_contains: asTrimmedString(query.author_contains) || undefined,
       since_utc: asTrimmedString(query.since_utc) || undefined,
       until_utc: asTrimmedString(query.until_utc) || undefined,
@@ -463,6 +470,15 @@ export class GitVcsDelegates extends VcsDelegateBase<GitRuntimeDependencies> {
     return null;
   }
 
+  override stagePaths(
+    params: OpenVcs.VcsStagePathsParams,
+    _context: PluginRuntimeContext,
+  ): null {
+    const git = this.requireGit(params.session_id);
+    git.stagePaths(asStringArray(params.paths));
+    return null;
+  }
+
   override discardPaths(
     params: OpenVcs.VcsDiscardPathsParams,
     _context: PluginRuntimeContext,
@@ -479,23 +495,38 @@ export class GitVcsDelegates extends VcsDelegateBase<GitRuntimeDependencies> {
     );
     const discardPlan = planDiscardPaths(status.stdout);
 
+    let failure: unknown;
+
     if (discardPlan.unstageThenRemove.length > 0) {
-      git.runChecked(
-        ['rm', '-f', '--cached', '--', ...discardPlan.unstageThenRemove],
-        'git-discard-paths-failed',
-      );
+      try {
+        git.runChecked(
+          ['rm', '-f', '--cached', '--', ...discardPlan.unstageThenRemove],
+          'git-discard-paths-failed',
+        );
+      } catch (error) {
+        failure = error;
+      }
     }
 
-    if (discardPlan.restore.length > 0) {
-      git.runChecked(
-        ['restore', '--source=HEAD', '--staged', '--worktree', '--', ...discardPlan.restore],
-        'git-discard-paths-failed',
-      );
+    if (!failure && discardPlan.restore.length > 0) {
+      try {
+        git.runChecked(
+          ['restore', '--source=HEAD', '--staged', '--worktree', '--', ...discardPlan.restore],
+          'git-discard-paths-failed',
+        );
+      } catch (error) {
+        failure = error;
+      }
     }
 
-    if (discardPlan.clean.length > 0) {
+    if (!failure && discardPlan.clean.length > 0) {
       git.runChecked(['clean', '-f', '--', ...discardPlan.clean], 'git-discard-paths-failed');
     }
+
+    if (failure) {
+      throw failure;
+    }
+
     return null;
   }
 

package/src/plugin.ts

@@ -58,7 +58,7 @@ export function OnPluginStart(): void {
   const delegates = new GitVcsDelegates(createGitRuntimeDependencies());
   PluginDefinition.vcs = delegates.toDelegates();
 
-  const repoMenu = getOrCreateMenu('repository', 'Repository');
+  const repoMenu = getOrCreateMenu('repository', 'Repository', { surface: 'menubar' });
   if (repoMenu) {
     repoMenu.addItem({ label: 'Edit .gitignore', action: 'repo-edit-gitignore' });
     repoMenu.addItem({ label: 'Edit .gitattributes', action: 'repo-edit-gitattributes' });

package/src/submodules.ts

@@ -26,7 +26,7 @@ function payloadString(payload: ModalActionPayload, key: string): string {
 }
 
 /** Builds one modal row for a submodule entry. */
-function buildSubmoduleRow(entry: SubmoduleEntry) {
+export function buildSubmoduleRow(entry: SubmoduleEntry) {
   const metaBits = [entry.commit ? `commit ${entry.commit}` : '', entry.branch ? `branch ${entry.branch}` : '']
     .map((part) => String(part || '').trim())
     .filter(Boolean);
@@ -62,13 +62,52 @@ function buildSubmoduleRow(entry: SubmoduleEntry) {
   };
 }
 
+/** Builds an error fallback modal with a descriptive message. */
+function buildErrorModal(message: string): ModalBuilder {
+  return new ModalBuilder('Error').text(message).text('Please try again or check the Git repository state.');
+}
+
+/** Opens a fallback modal for a submodule UI failure and preserves the original error on fallback failure. */
+export async function handleSubmoduleModalError(
+  prefix: string,
+  error: unknown,
+  openFallback: (message: string) => Promise<unknown> = (message) => buildErrorModal(message).open(),
+): Promise<unknown> {
+  const message = error instanceof Error ? error.message : String(error);
+  const fullMessage = `${prefix}: ${message}`;
+  console.error(`Git submodules: ${fullMessage}`);
+
+  try {
+    return await openFallback(fullMessage);
+  } catch {
+    throw error;
+  }
+}
+
 /** Builds and opens the submodule manager modal. */
 async function openSubmodulesModal(): Promise<unknown> {
   const git = createGitCommand();
-  const entries = git.listSubmodules();
+
+  let entries: SubmoduleEntry[];
+  try {
+    entries = git.listSubmodules();
+  } catch (error) {
+    return handleSubmoduleModalError('failed to list submodules', error);
+  }
+
   console.log('Git submodules: building modal', { count: entries.length });
 
-  const modal = new ModalBuilder('Manage Submodules')
+  const modal = buildSubmodulesModal(entries);
+  try {
+    return await modal.open();
+  } catch (error) {
+    return handleSubmoduleModalError('failed to open modal', error);
+  }
+}
+
+/** Builds the submodule manager modal with given entries. */
+function buildSubmodulesModal(entries: SubmoduleEntry[]): ModalBuilder {
+  return new ModalBuilder('Manage Submodules')
     .text('Review, add, update, sync, and remove submodules without leaving Git.')
     .text('Use Update Remote to follow each submodule branch configured in .gitmodules.')
     .separator()
@@ -130,14 +169,13 @@ async function openSubmodulesModal(): Promise<unknown> {
       emptyText: 'This repository has no submodules yet.',
       items: entries.map((entry) => buildSubmoduleRow(entry)),
     });
-
-  return modal.open();
 }
 
 /** Builds and opens the remove confirmation modal for one submodule. */
 async function openRemoveConfirmationModal(path: string, name?: string): Promise<unknown> {
   const submodulePath = String(path || '').trim();
   if (!submodulePath) return;
+
   console.log('Git submodules: building remove confirmation', { path: submodulePath, name });
 
   const modal = new ModalBuilder('Confirm Submodule Removal')
@@ -156,7 +194,11 @@ async function openRemoveConfirmationModal(path: string, name?: string): Promise
       { gap: '.5rem', align: 'centered', wrap: true },
     );
 
-  return modal.open();
+  try {
+    return await modal.open();
+  } catch (error) {
+    return handleSubmoduleModalError('failed to open remove confirmation modal', error);
+  }
 }
 
 /** Removes one submodule and refreshes the toolkit modal. */
@@ -234,7 +276,7 @@ async function syncAllSubmodules(): Promise<void> {
 
 /** Registers the Git submodule toolkit menu and action handlers. */
 export function registerSubmoduleToolkit(): void {
-  const repoMenu = getOrCreateMenu('repository', 'Repository');
+  const repoMenu = getOrCreateMenu('repository', 'Repository', { surface: 'menubar' });
   repoMenu?.addItem({ label: 'Submodules', action: 'repo-submodules' });
 
   registerAction('repo-submodules', async () => {