@adhdev/daemon-core 0.9.82-rc.457 → 0.9.82-rc.458

package/dist/logging/debug-config.d.ts

@@ -14,6 +14,22 @@ export interface DebugRuntimeConfig {
     traceBufferSize: number;
     traceCategories: string[];
 }
+/**
+ * ALWAYS-ON trace categories. These bypass the `collectDebugTrace` master switch
+ * (and category selection) so they are collected in production daemons where
+ * `--trace` is unset. They exist so mesh completion diagnostics — the FSM-transition
+ * and completion-gate snapshots that explain an early / missing agent:generating_completed
+ * notification — are retrievable via mesh_read_debug (chat_debug_bundle) without asking
+ * an operator to relaunch the daemon with tracing on.
+ *
+ * SAFETY: only add a category here after confirming every record() call site for it
+ * carries a content-free payload (statuses, epochs, timestamps, deltas, lengths, roles,
+ * enum-like reasons — never transcript / prompt / bubble text). Always-on collection makes
+ * such payloads unconditional, so a content-bearing field would leak into the ring buffer
+ * in production.
+ */
+export declare const ALWAYS_ON_TRACE_CATEGORIES: readonly string[];
+export declare function isAlwaysOnTraceCategory(category?: string | null): boolean;
 export declare function resolveDebugRuntimeConfig(options?: DebugRuntimeOptions): DebugRuntimeConfig;
 export declare function setDebugRuntimeConfig(config: DebugRuntimeConfig): void;
 export declare function getDebugRuntimeConfig(): DebugRuntimeConfig;

package/dist/mesh/worktree-bootstrap-config.d.ts

@@ -38,6 +38,51 @@ export declare const WORKTREE_BOOTSTRAP_STALE_RUNNING_MS: number;
  * lookup fails — callers must then treat any change as dirty (conservative).
  */
 export declare function getRegisteredSubmodulePaths(workspace: string): Set<string>;
+/**
+ * Read each registered submodule's configured `branch` from `.gitmodules`, keyed
+ * by the submodule's normalized path (matching {@link getRegisteredSubmodulePaths}).
+ *
+ * `.gitmodules` stores `submodule.<name>.path` and (optionally)
+ * `submodule.<name>.branch`; this joins the two on `<name>`. The special branch
+ * value `.` ("track the superproject's branch") is deliberately OMITTED so callers
+ * fall through to remote-HEAD detection instead of treating `.` as a literal branch
+ * name. Returns an empty map when there are no submodules, no `.gitmodules`, or the
+ * lookup fails (conservative — callers then detect or fall back).
+ */
+export declare function getSubmoduleConfiguredBranches(workspace: string): Map<string, string>;
+/** Fallback submodule branch when no configured/detected default can be resolved. */
+export declare const SUBMODULE_DEFAULT_BRANCH_FALLBACK = "main";
+/**
+ * Resolve the default branch a submodule's commits are published to / checked for
+ * reachability against. Generalizes the previously hardcoded `main` so a submodule
+ * whose default branch is `master`/`trunk`/etc. is handled. Priority (each tier
+ * falls through to the next on miss/error):
+ *
+ *   1. `.gitmodules` `submodule.<name>.branch` (via {@link getSubmoduleConfiguredBranches};
+ *      `.` is ignored) — an explicit, local, zero-cost declaration.
+ *   2. the submodule checkout's LOCAL remote HEAD: `git symbolic-ref --short
+ *      refs/remotes/<remote>/HEAD` → strip the `<remote>/` prefix (no network).
+ *   3. the submodule remote's advertised HEAD: `git ls-remote --symref <remote> HEAD`
+ *      → `ref: refs/heads/<branch>` (one network round-trip).
+ *   4. fallback {@link SUBMODULE_DEFAULT_BRANCH_FALLBACK} (`'main'`).
+ *
+ * Because the final fallback is `'main'` and every earlier tier that resolves `'main'`
+ * yields the same string, a repo whose submodules default to `main` (the common case)
+ * produces byte-identical downstream fetch/merge-base/push ref targets — only a
+ * read-only resolution probe is added.
+ */
+export declare function resolveSubmoduleDefaultBranch(opts: {
+    /** The submodule's local checkout — cwd for symbolic-ref / ls-remote. */
+    submoduleRepoPath: string;
+    /** The superproject workspace — for the `.gitmodules` branch lookup (tier 1). */
+    superprojectWorkspace?: string;
+    /** The submodule's path relative to the superproject (key into `.gitmodules`). */
+    submodulePath?: string;
+    /** Remote name (default `origin`). */
+    remote?: string;
+    /** Timeout for the local probe (tier 2); the network probe (tier 3) gets max(this, 30s). */
+    timeoutMs?: number;
+}): Promise<string>;
 export declare function isWorktreeBootstrapStaleRunning(node: {
     worktreeBootstrap?: {
         status?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.457",
+  "version": "0.9.82-rc.458",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,8 +46,8 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "0.9.82-rc.457",
-    "@adhdev/session-host-core": "0.9.82-rc.457",
+    "@adhdev/mesh-shared": "0.9.82-rc.458",
+    "@adhdev/session-host-core": "0.9.82-rc.458",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",

package/src/index.ts

@@ -394,6 +394,8 @@ export {
     getDebugRuntimeConfig,
     resetDebugRuntimeConfig,
     shouldCollectTraceCategory,
+    isAlwaysOnTraceCategory,
+    ALWAYS_ON_TRACE_CATEGORIES,
 } from './logging/debug-config.js';
 export type { DebugRuntimeOptions, DebugRuntimeConfig } from './logging/debug-config.js';
 export {

package/src/logging/debug-config.ts

@@ -20,6 +20,26 @@ export interface DebugRuntimeConfig {
 const NORMAL_TRACE_BUFFER_SIZE = 200
 const DEV_TRACE_BUFFER_SIZE = 1000
 
+/**
+ * ALWAYS-ON trace categories. These bypass the `collectDebugTrace` master switch
+ * (and category selection) so they are collected in production daemons where
+ * `--trace` is unset. They exist so mesh completion diagnostics — the FSM-transition
+ * and completion-gate snapshots that explain an early / missing agent:generating_completed
+ * notification — are retrievable via mesh_read_debug (chat_debug_bundle) without asking
+ * an operator to relaunch the daemon with tracing on.
+ *
+ * SAFETY: only add a category here after confirming every record() call site for it
+ * carries a content-free payload (statuses, epochs, timestamps, deltas, lengths, roles,
+ * enum-like reasons — never transcript / prompt / bubble text). Always-on collection makes
+ * such payloads unconditional, so a content-bearing field would leak into the ring buffer
+ * in production.
+ */
+export const ALWAYS_ON_TRACE_CATEGORIES: readonly string[] = ['completion-gate', 'fsm-transition']
+
+export function isAlwaysOnTraceCategory(category?: string | null): boolean {
+  return !!category && ALWAYS_ON_TRACE_CATEGORIES.includes(category)
+}
+
 const DEFAULT_CONFIG: DebugRuntimeConfig = {
   logLevel: 'info',
   collectDebugTrace: false,
@@ -68,6 +88,11 @@ export function resetDebugRuntimeConfig(): void {
 
 export function shouldCollectTraceCategory(category?: string | null): boolean {
   const config = currentConfig
+  // Always-on categories are collected regardless of the collectDebugTrace master switch
+  // and regardless of any explicit traceCategories selection (they form a superset on top of
+  // whatever the operator requested), so an explicit --trace / --trace-categories run still
+  // includes them with its existing behavior unchanged.
+  if (isAlwaysOnTraceCategory(category)) return true
   if (!config.collectDebugTrace) return false
   if (!category) return true
   if (config.traceCategories.length === 0) return true

package/src/logging/debug-trace.ts

@@ -1,4 +1,4 @@
-import { getDebugRuntimeConfig, shouldCollectTraceCategory } from './debug-config.js'
+import { getDebugRuntimeConfig, isAlwaysOnTraceCategory, shouldCollectTraceCategory } from './debug-config.js'
 
 export type DebugTraceLevel = 'debug' | 'info' | 'warn' | 'error'
 
@@ -80,7 +80,12 @@ export function createDebugTraceStore(options: DebugTraceStoreOptions): DebugTra
 
   return {
     record(event: DebugTraceEvent): DebugTraceEntry | null {
-      if (!options.enabled) return null
+      // The store's `enabled` flag mirrors collectDebugTrace (set by configureDebugTraceStore),
+      // so it is false on a production daemon. Always-on categories must still land in the ring
+      // even then — otherwise the second gate here would swallow what shouldCollectTraceCategory
+      // just admitted. They share the same fixed-capacity buffer, so heavy always-on traffic can
+      // evict older opt-in entries; that is accepted (no separate ring).
+      if (!options.enabled && !isAlwaysOnTraceCategory(event.category)) return null
       const entry = createEntry(event)
       entries.push(entry)
       if (entries.length > capacity) {

package/src/mesh/coordinator-prompt.ts

@@ -577,7 +577,7 @@ function buildRulesSection(coordinatorCliType?: string): string {
 - **Verify via git, not source.** Use \`mesh_git_status\` to confirm side effects. Treat agent summaries as self-reports, not verification.
 - **Limit parallelism.** Start with 1–2 tasks; scale only on success. Never duplicate a session because \`mesh_read_chat\` shows no final message while tool/terminal activity is ongoing. This caps *concurrent* load — it does not mean serialize independent work: when a new, independent request arrives and there is headroom under \`maxParallelTasks\`, dispatch it right away rather than waiting for an in-flight task or a user nudge (read-only diagnosis especially, since it has no merge cost).
 - **Check history first.** Call \`mesh_task_history\` at session start to avoid duplicate work and inform recovery. On failure, read task history before retrying.
-- **Sequence shared-base-moving merges.** Parallel dispatch is encouraged, but merging one worktree can advance another in-flight worktree's base — especially the oss submodule pointer — turning a clean fast-forward into a diverged rebase (patch-equivalence correctly blocks this). Before merging an in-flight worktree while siblings are also in flight, land in an intentional order, re-clone long-running worktrees from the advanced base, or expect to manually rebase + ff-only the laggards; merging an independent fix mid-flight can strand siblings into a rebase.
+- **Sequence shared-base-moving merges.** Parallel dispatch is encouraged, but merging one worktree can advance another in-flight worktree's base — especially a shared submodule pointer — turning a clean fast-forward into a diverged rebase (patch-equivalence correctly blocks this). Before merging an in-flight worktree while siblings are also in flight, land in an intentional order, re-clone long-running worktrees from the advanced base, or expect to manually rebase + ff-only the laggards; merging an independent fix mid-flight can strand siblings into a rebase.
 - **Converge branches.** After worktree tasks: refine/fast-forward, or classify as \`pushed_feature_branch_needs_merge\` / \`blocked_review\` / \`cleanup_candidate\` / \`not_mergeable\`. Clean up with \`mesh_remove_node\`.
 - **Refinery is config-driven.** \`mesh_refine_node\` must run validation from \`.adhdev/refine.{json,yaml,yml}\` or \`repo-mesh.refine.*\`. Heuristics are scaffolding only.
 - **Submodule reachability = publish-needed.** \`submodule_reachability_failed\` → classify as \`blocked_review\`, request user approval to push to submodule main, then rerun \`mesh_refine_node\`.

package/src/mesh/mesh-fast-forward.ts

@@ -1,6 +1,7 @@
 import type { GitRepoStatus, GitSubmoduleStatus } from '../git/git-types.js';
 import { getGitRepoStatus } from '../git/git-status.js';
 import { GitCommandError, runGit } from '../git/git-executor.js';
+import { resolveSubmoduleDefaultBranch } from './worktree-bootstrap-config.js';
 
 export interface MeshFastForwardNodeArgs {
   nodeId?: string;
@@ -521,31 +522,43 @@ async function resolveSubmodulePushes(
       results.push({ ...base, code: 'submodule_status_incomplete' });
       continue;
     }
-    // Refresh the submodule's origin/main, then require it to be an ancestor of
+    // Generalize the submodule's default branch (F18): '.gitmodules' branch →
+    // local remote HEAD → remote-advertised HEAD → 'main'. On a main-default
+    // submodule this resolves to 'main', keeping every ref below byte-identical.
+    const remoteBranch = await resolveSubmoduleDefaultBranch({
+      submoduleRepoPath: repoPath,
+      superprojectWorkspace: status.repoRoot ?? status.workspace,
+      submodulePath: submodule.path,
+      timeoutMs,
+    });
+    base.remoteBranch = remoteBranch;
+    const remoteRef = `refs/remotes/origin/${remoteBranch}`;
+    const fetchRefspec = `refs/heads/${remoteBranch}:${remoteRef}`;
+    // Refresh the submodule's origin/<branch>, then require it to be an ancestor of
     // the gitlink commit (strict ff-only).
     try {
-      await runGit(repoPath, ['-c', 'protocol.file.allow=always', 'fetch', 'origin', 'refs/heads/main:refs/remotes/origin/main'], { timeoutMs: timeoutMs ?? 30_000 });
+      await runGit(repoPath, ['-c', 'protocol.file.allow=always', 'fetch', 'origin', fetchRefspec], { timeoutMs: timeoutMs ?? 30_000 });
     } catch (error) {
       results.push({ ...base, code: 'submodule_fetch_failed', error: formatGitError(error) });
       continue;
     }
     let alreadyReachable = false;
     try {
-      await runGit(repoPath, ['merge-base', '--is-ancestor', submodule.commit, 'refs/remotes/origin/main'], { timeoutMs: timeoutMs ?? 15_000 });
+      await runGit(repoPath, ['merge-base', '--is-ancestor', submodule.commit, remoteRef], { timeoutMs: timeoutMs ?? 15_000 });
       alreadyReachable = true;
-    } catch { /* not yet on origin/main — candidate for push */ }
+    } catch { /* not yet on origin/<branch> — candidate for push */ }
     if (alreadyReachable) {
       results.push({ ...base, pushed: false, skipped: true, code: 'submodule_already_reachable' });
       continue;
     }
-    // Strict ff-only: origin/main must be an ancestor of the commit we publish.
+    // Strict ff-only: origin/<branch> must be an ancestor of the commit we publish.
     try {
-      await runGit(repoPath, ['merge-base', '--is-ancestor', 'refs/remotes/origin/main', submodule.commit], { timeoutMs: timeoutMs ?? 15_000 });
+      await runGit(repoPath, ['merge-base', '--is-ancestor', remoteRef, submodule.commit], { timeoutMs: timeoutMs ?? 15_000 });
     } catch (error) {
       results.push({ ...base, pushed: false, skipped: false, code: 'submodule_non_fast_forward', error: formatGitError(error) });
       continue;
     }
-    const refspec = `${submodule.commit}:refs/heads/main`;
+    const refspec = `${submodule.commit}:refs/heads/${remoteBranch}`;
     if (!execute) {
       results.push({ ...base, pushed: false, skipped: false, code: 'submodule_push_available', refspec });
       continue;
@@ -553,8 +566,8 @@ async function resolveSubmodulePushes(
     try {
       await runGit(repoPath, ['push', 'origin', refspec], { timeoutMs: timeoutMs ?? 30_000 });
       // Verify reachability after the push.
-      await runGit(repoPath, ['-c', 'protocol.file.allow=always', 'fetch', 'origin', 'refs/heads/main:refs/remotes/origin/main'], { timeoutMs: timeoutMs ?? 30_000 });
-      await runGit(repoPath, ['merge-base', '--is-ancestor', submodule.commit, 'refs/remotes/origin/main'], { timeoutMs: timeoutMs ?? 15_000 });
+      await runGit(repoPath, ['-c', 'protocol.file.allow=always', 'fetch', 'origin', fetchRefspec], { timeoutMs: timeoutMs ?? 30_000 });
+      await runGit(repoPath, ['merge-base', '--is-ancestor', submodule.commit, remoteRef], { timeoutMs: timeoutMs ?? 15_000 });
       results.push({ ...base, pushed: true, skipped: false, code: 'submodule_pushed', refspec });
     } catch (error) {
       results.push({ ...base, pushed: false, skipped: false, code: 'submodule_push_failed', refspec, error: formatGitError(error) });

package/src/mesh/mesh-refine-gates.ts

@@ -16,7 +16,7 @@ import { getGitRepoStatus } from '../git/git-status.js';
 import * as yaml from 'js-yaml';
 import { loadMeshRefineConfig, resolveMeshRefineValidationPlan } from '../mesh/refine-config.js';
 import type { MeshRefineValidationCommandPlan } from '../mesh/refine-config.js';
-import { evaluateWorktreeBootstrapState, loadMeshWorktreeBootstrapConfig, runMeshWorktreeBootstrap } from '../mesh/worktree-bootstrap-config.js';
+import { evaluateWorktreeBootstrapState, loadMeshWorktreeBootstrapConfig, runMeshWorktreeBootstrap, resolveSubmoduleDefaultBranch } from '../mesh/worktree-bootstrap-config.js';
 import type { WorktreeBootstrapState } from '../mesh/worktree-bootstrap-config.js';
 import { basename as pathBasename, join as pathJoin, resolve as pathResolve } from 'path';
 import * as fs from 'fs';
@@ -1295,6 +1295,10 @@ export async function runMeshRefineSubmoduleReachabilityGate(
                 commit: gitlink.commit,
                 reachable: false,
             };
+            // Resolved lazily once the submodule checkout/remote are confirmed; defaults
+            // to 'main' so error messages emitted before resolution stay byte-identical
+            // to the pre-generalization behavior on a main-default repo.
+            let submoduleDefaultBranch = 'main';
             try {
                 if (!fs.existsSync(submodulePath)) {
                     entry.error = `Submodule checkout missing at ${gitlink.path}`;
@@ -1350,9 +1354,18 @@ export async function runMeshRefineSubmoduleReachabilityGate(
                         entries.push(entry);
                         continue;
                     }
-                    entry.remoteMainBranch = 'main';
+                    // Generalize the submodule's default branch (F18): '.gitmodules'
+                    // branch → local remote HEAD → remote-advertised HEAD → 'main'. On a
+                    // main-default submodule this resolves to 'main' and every ref target
+                    // below is byte-identical to the prior hardcoded path.
+                    submoduleDefaultBranch = await resolveSubmoduleDefaultBranch({
+                        submoduleRepoPath: submodulePath,
+                        superprojectWorkspace: repoRoot,
+                        submodulePath: gitlink.path,
+                    });
+                    entry.remoteMainBranch = submoduleDefaultBranch;
                     try {
-                        await verifyRemoteMainContainsCommit(submodulePath, gitlink.commit, 'main');
+                        await verifyRemoteMainContainsCommit(submodulePath, gitlink.commit, submoduleDefaultBranch);
                         entry.fetchedFromOrigin = true;
                         entry.remoteReachable = true;
                         entry.remoteMainReachable = true;
@@ -1362,17 +1375,17 @@ export async function runMeshRefineSubmoduleReachabilityGate(
                         entry.remoteMainReachable = false;
                         entry.publishRequired = true;
                         const details = truncateValidationOutput(e?.stderr || e?.message || String(e));
-                        entry.error = `Submodule remote main reachability check failed for origin/main: ${details}`;
+                        entry.error = `Submodule remote main reachability check failed for origin/${submoduleDefaultBranch}: ${details}`;
                         if (options.allowAutoPublishSubmoduleMainCommits === true && entry.localReachable === true) {
                             entry.autoPublishAllowed = true;
                             entry.autoPublishAttempted = true;
                             try {
-                                const publish = await publishCommitToRemoteMain(submodulePath, gitlink.commit, 'main');
+                                const publish = await publishCommitToRemoteMain(submodulePath, gitlink.commit, submoduleDefaultBranch);
                                 entry.autoPublishRefspec = publish.refspec;
                                 entry.publishStdout = truncateValidationOutput(publish.stdout);
                                 entry.publishStderr = truncateValidationOutput(publish.stderr);
                                 entry.autoPublishSucceeded = true;
-                                await verifyRemoteMainContainsCommit(submodulePath, gitlink.commit, 'main');
+                                await verifyRemoteMainContainsCommit(submodulePath, gitlink.commit, submoduleDefaultBranch);
                                 entry.fetchedFromOrigin = true;
                                 entry.remoteReachable = true;
                                 entry.remoteMainReachable = true;
@@ -1384,13 +1397,13 @@ export async function runMeshRefineSubmoduleReachabilityGate(
                                 entry.autoPublishSucceeded = false;
                                 entry.autoPublishVerified = false;
                                 const publishDetails = truncateValidationOutput(publishError?.stderr || publishError?.message || String(publishError));
-                                entry.error = `Submodule auto-publish to origin/main failed or could not be verified: ${publishDetails}`;
+                                entry.error = `Submodule auto-publish to origin/${submoduleDefaultBranch} failed or could not be verified: ${publishDetails}`;
                             }
                         } else if (options.allowAutoPublishSubmoduleMainCommits === true) {
                             entry.autoPublishAllowed = true;
                             entry.autoPublishAttempted = false;
                             entry.autoPublishSkippedReason = entry.autoPublishSkippedReason
-                                || 'candidate commit is not reachable in the source checkout or worktree submodule, so Refinery cannot push it to origin/main';
+                                || `candidate commit is not reachable in the source checkout or worktree submodule, so Refinery cannot push it to origin/${submoduleDefaultBranch}`;
                         }
                     }
                 } catch (e: any) {
@@ -1398,7 +1411,7 @@ export async function runMeshRefineSubmoduleReachabilityGate(
                     entry.remoteMainReachable = false;
                     entry.publishRequired = true;
                     const details = truncateValidationOutput(e?.stderr || e?.message || String(e));
-                    entry.error = `Submodule remote main reachability check failed for origin/main: ${details}`;
+                    entry.error = `Submodule remote main reachability check failed for origin/${submoduleDefaultBranch}: ${details}`;
                 }
             } catch (e: any) {
                 entry.error = truncateValidationOutput(e?.message || String(e));

package/src/mesh/worktree-bootstrap-config.ts

@@ -92,6 +92,136 @@ export function getRegisteredSubmodulePaths(workspace: string): Set<string> {
     return paths;
 }
 
+/**
+ * Read each registered submodule's configured `branch` from `.gitmodules`, keyed
+ * by the submodule's normalized path (matching {@link getRegisteredSubmodulePaths}).
+ *
+ * `.gitmodules` stores `submodule.<name>.path` and (optionally)
+ * `submodule.<name>.branch`; this joins the two on `<name>`. The special branch
+ * value `.` ("track the superproject's branch") is deliberately OMITTED so callers
+ * fall through to remote-HEAD detection instead of treating `.` as a literal branch
+ * name. Returns an empty map when there are no submodules, no `.gitmodules`, or the
+ * lookup fails (conservative — callers then detect or fall back).
+ */
+export function getSubmoduleConfiguredBranches(workspace: string): Map<string, string> {
+    const branchesByPath = new Map<string, string>();
+    try {
+        const out = execFileSync(
+            resolveWin32Executable('git'),
+            ['config', '--file', '.gitmodules', '--list'],
+            { cwd: workspace, encoding: 'utf8', timeout: 10_000, windowsHide: true },
+        );
+        // Join `submodule.<name>.path` with `submodule.<name>.branch` on <name>.
+        const pathByName = new Map<string, string>();
+        const branchByName = new Map<string, string>();
+        for (const line of String(out).split(/\r?\n/)) {
+            const trimmed = line.trim();
+            if (!trimmed) continue;
+            const eq = trimmed.indexOf('=');
+            if (eq < 0) continue;
+            const key = trimmed.slice(0, eq);
+            const value = trimmed.slice(eq + 1).trim();
+            // key: submodule.<name>.<field>; <name> may itself contain dots, so match
+            // the leading `submodule.` and trailing `.<field>` and take the middle.
+            const match = /^submodule\.(.+)\.(path|branch)$/.exec(key);
+            if (!match) continue;
+            const name = match[1];
+            if (match[2] === 'path') {
+                const norm = value.replace(/\\/g, '/').replace(/\/+$/, '');
+                if (norm) pathByName.set(name, norm);
+            } else if (value) {
+                branchByName.set(name, value);
+            }
+        }
+        for (const [name, submodulePath] of pathByName) {
+            const branch = branchByName.get(name);
+            if (branch && branch !== '.') branchesByPath.set(submodulePath, branch);
+        }
+    } catch {
+        // No .gitmodules / git error → no configured branches.
+    }
+    return branchesByPath;
+}
+
+/** Fallback submodule branch when no configured/detected default can be resolved. */
+export const SUBMODULE_DEFAULT_BRANCH_FALLBACK = 'main';
+
+function isPlausibleBranchName(name: unknown): name is string {
+    return typeof name === 'string' && name.length > 0 && !/\s/.test(name) && name !== 'HEAD';
+}
+
+/**
+ * Resolve the default branch a submodule's commits are published to / checked for
+ * reachability against. Generalizes the previously hardcoded `main` so a submodule
+ * whose default branch is `master`/`trunk`/etc. is handled. Priority (each tier
+ * falls through to the next on miss/error):
+ *
+ *   1. `.gitmodules` `submodule.<name>.branch` (via {@link getSubmoduleConfiguredBranches};
+ *      `.` is ignored) — an explicit, local, zero-cost declaration.
+ *   2. the submodule checkout's LOCAL remote HEAD: `git symbolic-ref --short
+ *      refs/remotes/<remote>/HEAD` → strip the `<remote>/` prefix (no network).
+ *   3. the submodule remote's advertised HEAD: `git ls-remote --symref <remote> HEAD`
+ *      → `ref: refs/heads/<branch>` (one network round-trip).
+ *   4. fallback {@link SUBMODULE_DEFAULT_BRANCH_FALLBACK} (`'main'`).
+ *
+ * Because the final fallback is `'main'` and every earlier tier that resolves `'main'`
+ * yields the same string, a repo whose submodules default to `main` (the common case)
+ * produces byte-identical downstream fetch/merge-base/push ref targets — only a
+ * read-only resolution probe is added.
+ */
+export async function resolveSubmoduleDefaultBranch(opts: {
+    /** The submodule's local checkout — cwd for symbolic-ref / ls-remote. */
+    submoduleRepoPath: string;
+    /** The superproject workspace — for the `.gitmodules` branch lookup (tier 1). */
+    superprojectWorkspace?: string;
+    /** The submodule's path relative to the superproject (key into `.gitmodules`). */
+    submodulePath?: string;
+    /** Remote name (default `origin`). */
+    remote?: string;
+    /** Timeout for the local probe (tier 2); the network probe (tier 3) gets max(this, 30s). */
+    timeoutMs?: number;
+}): Promise<string> {
+    const remote = opts.remote?.trim() || 'origin';
+    const localTimeout = opts.timeoutMs ?? 10_000;
+    const git = resolveWin32Executable('git');
+    const execFileAsync = promisify(execFile);
+
+    // Tier 1: .gitmodules configured branch (local, zero-cost).
+    if (opts.superprojectWorkspace && opts.submodulePath) {
+        try {
+            const normalized = opts.submodulePath.replace(/\\/g, '/').replace(/\/+$/, '');
+            const configured = getSubmoduleConfiguredBranches(opts.superprojectWorkspace).get(normalized);
+            if (isPlausibleBranchName(configured)) return configured;
+        } catch { /* fall through */ }
+    }
+
+    // Tier 2: the local remote HEAD (no network) — set by clone/`git remote set-head`.
+    try {
+        const { stdout } = await execFileAsync(
+            git,
+            ['symbolic-ref', '--short', `refs/remotes/${remote}/HEAD`],
+            { cwd: opts.submoduleRepoPath, encoding: 'utf8', timeout: localTimeout, windowsHide: true },
+        );
+        const short = String(stdout || '').trim();
+        const prefix = `${remote}/`;
+        const branch = short.startsWith(prefix) ? short.slice(prefix.length) : short;
+        if (isPlausibleBranchName(branch)) return branch;
+    } catch { /* fall through */ }
+
+    // Tier 3: the remote's advertised HEAD (one network round-trip).
+    try {
+        const { stdout } = await execFileAsync(
+            git,
+            ['ls-remote', '--symref', remote, 'HEAD'],
+            { cwd: opts.submoduleRepoPath, encoding: 'utf8', timeout: Math.max(localTimeout, 30_000), windowsHide: true },
+        );
+        const match = /^ref:\s+refs\/heads\/(\S+)\s+HEAD/m.exec(String(stdout || ''));
+        if (match && isPlausibleBranchName(match[1])) return match[1];
+    } catch { /* fall through */ }
+
+    return SUBMODULE_DEFAULT_BRANCH_FALLBACK;
+}
+
 /**
  * True when `git status --porcelain` output represents a worktree that is clean
  * EXCEPT for submodule-gitlink-pointer moves. A worktree task that commits inside a