git-coco 0.51.0 → 0.52.0

package/dist/index.esm.mjs

@@ -61,7 +61,7 @@ import { pathToFileURL } from 'url';
 /**
  * Current build version from package.json
  */
-const BUILD_VERSION = "0.51.0";
+const BUILD_VERSION = "0.52.0";
 
 const isInteractive = (config) => {
     return config?.mode === 'interactive' || !!config?.interactive;
@@ -8212,9 +8212,40 @@ async function getCommitLogAgainstTag({ git, logger, targetTag, }) {
     return [];
 }
 
+async function refExists(git, ref) {
+    try {
+        // `--verify --quiet` suppresses stderr noise on a missing ref and
+        // emits the resolved sha on stdout when it exists. simple-git
+        // returns an empty string (rather than throwing) when git exits
+        // 1 under `--quiet`, so the presence/absence check is on the
+        // output, not on whether the call rejected.
+        const out = await git.raw(['rev-parse', '--verify', '--quiet', ref]);
+        return out.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Retrieves the commit log for the current branch.
  *
+ * Edge states that are not errors and should not be reported as such:
+ *
+ *   - Detached HEAD (including mid-rebase and mid-bisect, which both
+ *     leave HEAD detached). There is no "current branch" to compare
+ *     against; the helper logs a yellow status line and returns [].
+ *   - Comparison ref missing — e.g. the repo has no `origin` remote,
+ *     so `origin/main` does not resolve; or the local comparison
+ *     branch (`main`) simply does not exist. Previously this threw
+ *     and surfaced as a red "Encountered an error" banner. Now we
+ *     probe the ref up front and report a clean status line.
+ *   - Empty rev-list output. The previous yellow "Unable to determine
+ *     first and last commit" wording read like an error; it's just
+ *     "no commits ahead of the comparison ref", which is the normal
+ *     outcome when the branch is at or behind its baseline.
+ *
+ * The catch block is reserved for genuinely unexpected git failures.
+ *
  * @param {Object} options - The options for retrieving the commit log.
  * @param {SimpleGit} options.git - The SimpleGit instance.
  * @param {Logger} options.logger - The logger for logging messages.
@@ -8223,43 +8254,53 @@ async function getCommitLogAgainstTag({ git, logger, targetTag, }) {
  * @returns {Promise<CommitDetails[]>} The array of commit messages in the commit log.
  */
 async function getCommitLogCurrentBranch({ git, logger, comparisonBranch = 'main', comparisonRemote = 'origin', }) {
+    const branchName = await getCurrentBranchName({ git });
+    // Detached HEAD: `git rev-parse --abbrev-ref HEAD` returns the literal
+    // string 'HEAD' in this state. Also covers mid-rebase and mid-bisect,
+    // which both detach HEAD onto the picked / midpoint commit. There's
+    // no branch to compare against, so don't pretend there was an error.
+    if (!branchName || branchName === 'HEAD') {
+        logger?.log('HEAD is detached (or a rebase / bisect is in progress) — no branch context to compare against.', { color: 'yellow' });
+        return [];
+    }
     try {
-        const branchName = await getCurrentBranchName({ git });
-        const hasCommits = (await git.raw(['rev-list', '--count', branchName])) !== '0';
-        if (!hasCommits) {
-            logger?.log('No commits on the current branch.');
-            return [];
-        }
-        let uniqueCommits;
+        let comparisonRef;
         if (comparisonBranch === branchName) {
-            // If the comparison branch is the same as the current branch, we compare against the remote.
-            uniqueCommits = (await git.raw(['rev-list', `${comparisonRemote}/${comparisonBranch}..${branchName}`]))
-                .split('\n')
-                .filter(Boolean)
-                .reverse();
+            // Same branch as the comparison target — compare against the
+            // remote-tracking ref. If the remote (or the ref) does not
+            // exist, fall back to a clean status line rather than throwing.
+            const remoteRef = `${comparisonRemote}/${comparisonBranch}`;
+            if (!(await refExists(git, remoteRef))) {
+                logger?.log(`No "${remoteRef}" ref to compare against — skipping changelog for "${branchName}".`, { color: 'yellow' });
+                return [];
+            }
+            comparisonRef = remoteRef;
         }
         else {
-            // Your existing code for different branches
-            uniqueCommits = (await git.raw(['rev-list', `${comparisonBranch}..${branchName}`]))
-                .split('\n')
-                .filter(Boolean)
-                .reverse();
+            if (!(await refExists(git, comparisonBranch))) {
+                logger?.log(`Comparison branch "${comparisonBranch}" does not exist — skipping changelog for "${branchName}".`, { color: 'yellow' });
+                return [];
+            }
+            comparisonRef = comparisonBranch;
         }
-        logger?.verbose(`Found ${uniqueCommits.length} unique commits on "${branchName}"`, {
-            color: 'blue',
-        });
+        const uniqueCommits = (await git.raw(['rev-list', `${comparisonRef}..${branchName}`]))
+            .split('\n')
+            .filter(Boolean)
+            .reverse();
+        logger?.verbose(`Found ${uniqueCommits.length} unique commits on "${branchName}" vs "${comparisonRef}"`, { color: 'blue' });
         const firstCommit = uniqueCommits[0];
         const lastCommit = uniqueCommits[uniqueCommits.length - 1];
         if (!firstCommit || !lastCommit) {
-            logger?.log('Unable to determine first and last commit on the current branch', {
-                color: 'yellow',
-            });
+            // Empty rev-list output is the normal outcome when the branch is
+            // at or behind its baseline. Not an error.
+            logger?.log(`No commits on "${branchName}" ahead of "${comparisonRef}".`);
             return [];
         }
         return await getCommitLogRangeDetails(firstCommit, lastCommit, { git, noMerges: true });
     }
     catch (error) {
         logger?.log('Encountered an error getting commit log from current branch', { color: 'red' });
+        logger?.verbose(error instanceof Error ? error.message : String(error), { color: 'red' });
     }
     return [];
 }
@@ -14327,7 +14368,13 @@ const handler$9 = async (argv, logger) => {
             return `## Diff for ${data.branch}\n\n${diffSummary}`;
         }
         if (!data.commits || data.commits.length === 0) {
-            return `## ${data.branch}\n\nNo commits found.`;
+            // Short-circuit with an empty context so the review loop drops
+            // into `noResult` instead of spending an LLM call summarising
+            // "No commits found." into a fake changelog entry. The
+            // upstream helper (getCommitLogCurrentBranch) already logged
+            // the reason (detached HEAD, missing comparison ref, branch at
+            // baseline, etc.) in a friendly status line.
+            return '';
         }
         let result = `## ${data.branch}\n\n`;
         result += data.commits.map(commit => {
@@ -14404,10 +14451,15 @@ const handler$9 = async (argv, logger) => {
         },
         noResult: async () => {
             if (config.range) {
-                logger.log(`No commits found in the provided range.`, { color: 'red' });
+                logger.log(`No commits found in the provided range.`, { color: 'yellow' });
                 commandExit(0);
             }
-            logger.log(`No commits found in the current branch.`, { color: 'red' });
+            // Yellow rather than red — for the no-commits-on-current-branch
+            // case the upstream helper has already explained the reason in
+            // a friendly status line (detached HEAD, no comparison ref,
+            // branch at baseline). This is the trailing summary, not an
+            // error.
+            logger.log(`No commits found in the current branch.`, { color: 'yellow' });
             commandExit(0);
         },
     });
@@ -17892,6 +17944,38 @@ const builder$4 = (yargs) => {
     return yargs.options(options$4).usage(getCommandUsageHeader(command$4));
 };
 
+/**
+ * Detect whether the repository has any commits yet.
+ *
+ * A "fresh" repo (one created by `git init` with no commits) has an
+ * **unborn HEAD** — the `main` (or configured-default) branch ref
+ * exists symbolically but doesn't point at any object. Any plumbing
+ * command that tries to resolve HEAD (`git log`, `git show`, `git
+ * rev-list`) fails fatally on such a repo with `fatal: your current
+ * branch '<X>' does not have any commits yet`.
+ *
+ * Without an explicit pre-check, callers crash with that raw error
+ * (see {@link ../utils/commandExecutor} — the generic-error path
+ * just prints whatever was thrown). This helper lets a command
+ * short-circuit to a friendly "no commits yet" message instead.
+ *
+ * Implementation uses `git rev-parse --verify HEAD` because it's the
+ * cheapest "does HEAD resolve?" probe — no log walk, no working-tree
+ * scan. Returns `true` when rev-parse rejects (unborn HEAD) and
+ * `false` when it succeeds.
+ *
+ * @returns `true` when HEAD is unborn (no commits); `false` otherwise.
+ */
+async function isEmptyRepo(git) {
+    try {
+        await git.revparse(['--verify', 'HEAD']);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+
 /**
  * Git LFS pointer parsing + diff summarization (#884).
  *
@@ -18310,6 +18394,19 @@ function buildToggleGraphArgs(argv, fullGraph) {
     return { ...argv, view: argv.view ?? 'compact' };
 }
 async function getLogRows(git, argv, options = {}) {
+    // Unborn HEAD short-circuit. Without this, `git log` on a freshly
+    // `git init`'d repo throws "fatal: your current branch 'main' does
+    // not have any commits yet" — fine when the caller can catch and
+    // translate, painful otherwise (the workstation runtime surfaces it
+    // as "Failed to load commits: fatal: ..." in the status line).
+    //
+    // Returning [] is the natural contract: callers that already render
+    // an empty-history surface (`formatLogInkHistoryEmpty`) get the
+    // right experience automatically; `coco log` retains its own
+    // friendlier message via the handler's isEmptyRepo check.
+    if (await isEmptyRepo(git)) {
+        return [];
+    }
     return parseLogOutput(await git.raw(buildLogArgs(argv, options)));
 }
 async function getCommitDetail(git, commit) {
@@ -18381,6 +18478,7 @@ async function getCommitFilePreview(git, commit, file, limit = 40) {
             deletions: file.deletions,
         },
         hunks: finalHunks,
+        submoduleChange,
     };
 }
 
@@ -21793,6 +21891,56 @@ function formatLogInkBreadcrumb(viewStack) {
     // they're nested deeper than the root view.
     return `${viewStack.join(' › ')}   ← <`;
 }
+/**
+ * Render the nested-repo navigation stack (#931) as a breadcrumb suitable
+ * for the chrome header. Returns an empty string for a root-only stack
+ * so the header stays compact when nothing has been pushed.
+ *
+ * The trailing `← esc` reminds the user that Esc is the way out — same
+ * shape as the view breadcrumb's `← <` so the two read consistently.
+ * The repo breadcrumb shows in addition to the view breadcrumb when
+ * both stacks are non-trivial; the chrome layer is responsible for
+ * laying them out side by side.
+ *
+ * Examples:
+ *   `[root]`                     → ''
+ *   `[coco, vendor/lib]`         → 'coco › vendor/lib   ← esc'
+ *   `[coco, vendor/lib, deep]`   → 'coco › vendor/lib › deep   ← esc'
+ */
+function formatLogInkRepoBreadcrumb(repoStack) {
+    if (repoStack.length <= 1) {
+        return '';
+    }
+    return `${repoStack.map((frame) => frame.label).join(' › ')}   ← esc`;
+}
+/**
+ * Combine the repo-stack and view-stack breadcrumb segments for the
+ * header chrome (#931). Each segment is independently rendered by its
+ * formatter and may be empty; this helper interleaves the leading
+ * spacing so the header builder doesn't have to branch on four cases.
+ *
+ *   repoCrumb=''       viewCrumb=''       → ''
+ *   repoCrumb='X'      viewCrumb=''       → '  X'
+ *   repoCrumb=''       viewCrumb='Y'      → '  Y'
+ *   repoCrumb='X'      viewCrumb='Y'      → '  X    Y'
+ *
+ * Two leading spaces match the existing chrome — they separate the
+ * breadcrumb from the trailing repo/branch segment in the title row.
+ * Four spaces between segments give the repo crumb visual breathing
+ * room before the view crumb begins.
+ */
+function combineLogInkBreadcrumbSegments(repoCrumb, viewCrumb) {
+    if (repoCrumb && viewCrumb) {
+        return `  ${repoCrumb}    ${viewCrumb}`;
+    }
+    if (repoCrumb) {
+        return `  ${repoCrumb}`;
+    }
+    if (viewCrumb) {
+        return `  ${viewCrumb}`;
+    }
+    return '';
+}
 function getLogInkFooterHints(options) {
     if (options.pendingKey) {
         const continuations = getLogInkChordContinuations(options.pendingKey);
@@ -22547,6 +22695,93 @@ function withPoppedView(state) {
         pendingKey: undefined,
     };
 }
+/**
+ * Push a nested-repo frame onto `state.repoStack` (#931). Snapshots
+ * the active view position into the new frame's `parentReturn` so a
+ * subsequent pop lands the user back where they came from, then
+ * resets the per-frame navigation state (active view, view stack,
+ * row / file / submodule cursors, filter) so the nested frame opens
+ * in a clean slate — the mental equivalent of a fresh `coco ui`
+ * launched against the submodule's working dir.
+ *
+ * Carry-over preferences (sidebar tab, branch / tag sort, palette
+ * recents, inspector tab, diff view mode) are intentionally left
+ * untouched. They're user-level choices that should persist across
+ * frames, the same way they persist across view pushes today.
+ *
+ * Live runtime objects (`SimpleGit`, loaded `LogInkContext`) live
+ * outside the reducer in `app.ts`'s parallel ref structure — this
+ * helper only manages the pure view-model side of the push.
+ */
+function withPushedRepoFrame(state, payload) {
+    const newFrame = {
+        label: payload.label,
+        workdir: payload.workdir,
+        entryRange: payload.entryRange,
+        parentReturn: {
+            activeView: state.activeView,
+            selectedIndex: state.selectedIndex,
+            selectedFileIndex: state.selectedFileIndex,
+            selectedSubmoduleIndex: state.selectedSubmoduleIndex,
+            filter: state.filter,
+        },
+    };
+    return {
+        ...state,
+        repoStack: [...state.repoStack, newFrame],
+        activeView: 'history',
+        viewStack: ['history'],
+        selectedIndex: 0,
+        selectedFileIndex: 0,
+        selectedSubmoduleIndex: 0,
+        filter: '',
+        filterMode: false,
+        pendingCommitFocused: false,
+        pendingKey: undefined,
+        pendingConfirmationId: undefined,
+        pendingConfirmationPayload: undefined,
+        pendingMutationConfirmation: undefined,
+    };
+}
+/**
+ * Pop the top repo frame off `state.repoStack` (#931) and restore
+ * the parent's view position from the captured `parentReturn`. A
+ * no-op when the stack is already at its single root frame so this
+ * action is safe to dispatch from generic input handlers (e.g. the
+ * Esc auto-pop wiring that lands in a follow-up PR).
+ *
+ * The defensive `parentReturn` fallback handles the never-supposed-
+ * to-happen case where a non-root frame somehow has no return state
+ * recorded — drop the frame but leave the user's view position
+ * alone rather than crash mid-session.
+ */
+function withPoppedRepoFrame(state) {
+    if (state.repoStack.length <= 1) {
+        return { ...state, pendingKey: undefined };
+    }
+    const topFrame = state.repoStack[state.repoStack.length - 1];
+    const ret = topFrame.parentReturn;
+    const repoStack = state.repoStack.slice(0, -1);
+    if (!ret) {
+        return { ...state, repoStack, pendingKey: undefined };
+    }
+    return {
+        ...state,
+        repoStack,
+        activeView: ret.activeView,
+        viewStack: [ret.activeView],
+        selectedIndex: ret.selectedIndex,
+        selectedFileIndex: ret.selectedFileIndex,
+        selectedSubmoduleIndex: ret.selectedSubmoduleIndex,
+        filter: ret.filter,
+        filterMode: false,
+        pendingCommitFocused: false,
+        pendingKey: undefined,
+        pendingConfirmationId: undefined,
+        pendingConfirmationPayload: undefined,
+        pendingMutationConfirmation: undefined,
+    };
+}
 function withReplacedView(state, value) {
     if (topOfStack(state.viewStack) === value) {
         return { ...state, pendingKey: undefined };
@@ -22691,7 +22926,7 @@ function createLogInkState(rows, options = {}) {
         selectedPullRequestTriageIndex: 0,
         selectedIssueFilter: 'open',
         selectedPullRequestFilter: 'open',
-        repoStack: [{ label: options.repoLabel || 'root' }],
+        repoStack: [{ label: options.repoLabel || 'root', workdir: options.repoWorkdir }],
         branchSort: DEFAULT_BRANCH_SORT_MODE,
         tagSort: DEFAULT_TAG_SORT_MODE,
         paletteFilter: '',
@@ -22704,6 +22939,7 @@ function createLogInkState(rows, options = {}) {
         filterMode: false,
         fullGraph: false,
         showHelp: false,
+        helpScrollOffset: 0,
         showCommandPalette: false,
         workflowActionId: undefined,
         pendingConfirmationId: undefined,
@@ -22711,8 +22947,13 @@ function createLogInkState(rows, options = {}) {
         pendingMutationConfirmation: undefined,
         pendingKey: undefined,
         focus: 'commits',
-        sidebarTab: 'status',
-        userSidebarTab: 'status',
+        // Default first-time tab is 'branches' — it's the most useful
+        // landing surface in the workstation (current branch + recent
+        // branches with ahead/behind, switch target, etc.). Users who
+        // pick a different tab have their choice persisted per-repo via
+        // sidebarPersistence.ts and won't see this default again.
+        sidebarTab: 'branches',
+        userSidebarTab: 'branches',
         sidebarHeaderFocused: false,
         statusGroupHeaderFocused: false,
         statusFilterMask: { ...DEFAULT_LOG_INK_STATUS_FILTER_MASK },
@@ -22733,6 +22974,15 @@ function getSelectedInkCommit(state) {
     }
     return state.filteredCommits[state.selectedIndex];
 }
+/**
+ * True when the user has drilled into a submodule (or deeper).
+ * Drives the chrome breadcrumb's display and any future
+ * frame-aware behavior that wants to know "are we in a nested
+ * frame?" without inspecting the stack directly.
+ */
+function isLogInkNestedRepo(state) {
+    return state.repoStack.length > 1;
+}
 function applyLogInkAction(state, action) {
     switch (action.type) {
         case 'appendRows':
@@ -23155,6 +23405,14 @@ function applyLogInkAction(state, action) {
             return withPoppedView(state);
         case 'replaceView':
             return withReplacedView(state, action.value);
+        case 'pushRepoFrame':
+            return withPushedRepoFrame(state, {
+                label: action.label,
+                workdir: action.workdir,
+                entryRange: action.entryRange,
+            });
+        case 'popRepoFrame':
+            return withPoppedRepoFrame(state);
         case 'navigateHome': {
             if (state.viewStack.length === 1 && topOfStack(state.viewStack) === HOME_VIEW) {
                 return { ...state, pendingKey: undefined };
@@ -23326,6 +23584,7 @@ function applyLogInkAction(state, action) {
                 filterMode: !state.filterMode,
                 showCommandPalette: false,
                 showHelp: false,
+                helpScrollOffset: 0,
                 pendingKey: undefined,
             };
         case 'toggleGraph':
@@ -23334,19 +23593,35 @@ function applyLogInkAction(state, action) {
                 fullGraph: !state.fullGraph,
                 pendingKey: undefined,
             };
-        case 'toggleHelp':
+        case 'toggleHelp': {
+            const opening = !state.showHelp;
             return {
                 ...state,
-                showHelp: !state.showHelp,
+                showHelp: opening,
+                // Reset scroll position when toggling either direction so the
+                // next open always starts at the top — feels more predictable
+                // than picking up where the user last scrolled.
+                helpScrollOffset: 0,
                 showCommandPalette: false,
                 pendingKey: undefined,
             };
+        }
+        case 'scrollHelp':
+            // No upper-bound clamp here — the renderer caps the offset
+            // against the actual content height at render time. The
+            // reducer just prevents going below 0 so callers can safely
+            // pass negative deltas without us going past the top.
+            return {
+                ...state,
+                helpScrollOffset: Math.max(0, state.helpScrollOffset + action.delta),
+            };
         case 'toggleCommandPalette': {
             const opening = !state.showCommandPalette;
             return {
                 ...state,
                 showCommandPalette: opening,
                 showHelp: false,
+                helpScrollOffset: 0,
                 // Reset palette interaction state on every open/close so the next
                 // session starts from a clean slate.
                 paletteFilter: '',
@@ -23993,6 +24268,14 @@ function getLogInkPaletteExecuteEvents(command, state) {
                     value: 'open branches / tags / history and press m on the cursored ref',
                 })];
         case 'navigateBack':
+            // Mirror the Esc / `<` semantics (#931): drain the frame's view
+            // stack first, then pop the frame itself when nested.
+            if (state.viewStack.length > 1) {
+                return [action({ type: 'popView' })];
+            }
+            if (isLogInkNestedRepo(state)) {
+                return [action({ type: 'popRepoFrame' })];
+            }
             return [action({ type: 'popView' })];
         case 'openSelected': {
             // From history → diff for selected commit; from status → diff for
@@ -24540,8 +24823,37 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
         }
         return [];
     }
-    if (key.escape && state.showHelp) {
-        return [action({ type: 'toggleHelp' })];
+    // Help-overlay key handling. While help is open we intercept ALL
+    // keys here and return before they can fall through to scroll /
+    // focus / navigation logic below. Without this, j/k while help is
+    // open routes into `moveDetailFile`-style handlers, which mutates
+    // focus state (`focus: 'detail'` → `'commits'` or `'sidebar'`) —
+    // exactly the "scroll loses focus" bug.
+    //
+    // Allowed: Esc / ? (close), q (quit), j/k/arrows (scroll), Ctrl-d/u
+    // (half-page). Everything else is swallowed by the trailing
+    // `return []` so a stray keypress can't drop the user into the
+    // wrong surface.
+    if (state.showHelp) {
+        if (key.escape || inputValue === '?') {
+            return [action({ type: 'toggleHelp' })];
+        }
+        if (inputValue === 'q') {
+            return [{ type: 'exit' }];
+        }
+        if (key.downArrow || inputValue === 'j') {
+            return [action({ type: 'scrollHelp', delta: 1 })];
+        }
+        if (key.upArrow || inputValue === 'k') {
+            return [action({ type: 'scrollHelp', delta: -1 })];
+        }
+        if (key.ctrl && inputValue === 'd') {
+            return [action({ type: 'scrollHelp', delta: 10 })];
+        }
+        if (key.ctrl && inputValue === 'u') {
+            return [action({ type: 'scrollHelp', delta: -10 })];
+        }
+        return [];
     }
     // #879 item 4 — Esc cancels an in-flight bisect-start wizard. Runs
     // BEFORE the generic `popView` so we both clear the wizard state
@@ -24562,6 +24874,15 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
     if (key.escape && state.viewStack.length > 1) {
         return [action({ type: 'popView' })];
     }
+    // #931 — Esc auto-pop. When the user has drilled into a submodule
+    // (nested repo frame) AND they're at the root of that frame's own
+    // view stack, Esc walks back out to the parent repo. Ordered after
+    // the view-stack pop above so Esc still drains a frame's view stack
+    // before popping the frame itself — the user sees a predictable
+    // "back, back, back" path out.
+    if (key.escape && isLogInkNestedRepo(state)) {
+        return [action({ type: 'popRepoFrame' })];
+    }
     if (inputValue === 'q') {
         if (hasUnsavedComposeDraft(state)) {
             return [action({ type: 'setPendingMutationConfirmation', value: 'discard-draft' })];
@@ -24844,6 +25165,17 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
         return [action({ type: 'toggleGraph' })];
     }
     if (inputValue === '<') {
+        // #931 — `<` is the keymap-driven mirror of Esc auto-pop. When the
+        // view stack has somewhere to go, pop a view; otherwise, if we're
+        // in a nested submodule frame, walk back out to the parent. The
+        // `popView` action is itself a no-op at the root of a frame's
+        // view stack, so this ordering can't double-pop.
+        if (state.viewStack.length > 1) {
+            return [action({ type: 'popView' })];
+        }
+        if (isLogInkNestedRepo(state)) {
+            return [action({ type: 'popRepoFrame' })];
+        }
         return [action({ type: 'popView' })];
     }
     if (inputValue === 'G') {
@@ -25326,6 +25658,48 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
             }
         }
     }
+    // #931 PR 3b — Enter on a submodule file in a commit diff drills into
+    // the submodule's history (the "spawn a coco ui scoped to the
+    // submodule" mental model from the design doc). The runtime decides
+    // whether the cursored file is a drill-in candidate and resolves the
+    // workdir + entryRange ahead of time; the handler here only fires
+    // when that target is populated. Ordered before the generic file-
+    // list Enter handler so the drill-in takes precedence over the
+    // detail-panel diff-refocus path.
+    if (key.return &&
+        state.activeView === 'diff' &&
+        state.diffSource === 'commit' &&
+        context.commitDiffSubmoduleDrillIn) {
+        const target = context.commitDiffSubmoduleDrillIn;
+        return [
+            action({
+                type: 'pushRepoFrame',
+                label: target.label,
+                workdir: target.workdir,
+                entryRange: target.entryRange,
+            }),
+            action({ type: 'setStatus', value: `entering submodule ${target.label}` }),
+        ];
+    }
+    // #931 PR 4 / #932 — Enter on a row in the dedicated submodules view
+    // drills into that submodule's history. Same mental model as the
+    // commit-diff drill-in (PR 3b) — pushing a frame is the equivalent
+    // of `cd vendor/lib && coco ui`. No entry range here; the submodules
+    // view doesn't carry diff context, so the frame lands on the
+    // submodule's full history.
+    if (key.return &&
+        isSubmodulesActionTarget(state) &&
+        context.submoduleViewDrillIn) {
+        const target = context.submoduleViewDrillIn;
+        return [
+            action({
+                type: 'pushRepoFrame',
+                label: target.label,
+                workdir: target.workdir,
+            }),
+            action({ type: 'setStatus', value: `entering submodule ${target.label}` }),
+        ];
+    }
     if (key.return &&
         state.activeView === 'history' &&
         state.focus === 'commits' &&
@@ -26233,6 +26607,199 @@ function pickSpinnerFrame(tick) {
     return SPINNER_FRAMES[Math.max(0, tick) % SPINNER_FRAMES.length];
 }
 
+/**
+ * Build the initial `LogInkContextStatus` for a freshly-created frame
+ * (#931). Every fetched key starts in `'loading'` so surfaces show the
+ * loading hint immediately; `pullRequest` is the exception (#808) —
+ * it's lazy-loaded on entry to the PR view, so we seed it `'idle'`
+ * instead of leaving it stuck as a permanent "loading" flag in the
+ * chrome.
+ *
+ * Extracted so the root runtime (built at boot inside `LogInkApp`) and
+ * the per-frame factory below share one canonical seed. The status
+ * surfaces depend on the exact `'pullRequest' = 'idle'` initialization
+ * to avoid spurious loading hints; locking it down in one helper means
+ * the two code paths can't drift.
+ */
+function createInitialContextStatus() {
+    return updateLogInkContextStatus(createLogInkContextStatus('loading'), 'pullRequest', 'idle');
+}
+/**
+ * Factory that builds a fresh `RepoFrameRuntime` for a newly-pushed
+ * frame (#931). The frame's `workdir` (set by the push action) drives
+ * which working tree the `SimpleGit` instance binds against:
+ *
+ *   - **Has workdir** → `simpleGit(workdir)`. Production case for any
+ *     nested submodule frame.
+ *   - **No workdir** → falls back to `rootGit`. Defensive: only the
+ *     root frame is expected to lack a workdir, and the root frame's
+ *     runtime is built directly from `rootGit` in `LogInkApp`'s state
+ *     initializer — this fallback only kicks in if a future push path
+ *     forgets to pass `workdir`. Binding to the root keeps the session
+ *     functional (the user still sees data) at the cost of the frame
+ *     being a duplicate of the root.
+ *
+ * `context` starts empty; `contextStatus` starts in the same initial
+ * "loading + pullRequest idle" shape the root frame seeds with. The
+ * sync effect in `LogInkApp` is responsible for kicking off the
+ * per-key context loads against the new frame's `git`; we don't do
+ * that here so the factory stays pure and unit-testable without a
+ * real repo on disk.
+ */
+function createRepoFrameRuntime(frame, rootGit) {
+    return {
+        git: frame.workdir ? simpleGit(frame.workdir) : rootGit,
+        context: {},
+        contextStatus: createInitialContextStatus(),
+    };
+}
+
+/**
+ * Pure resolver: given the cursored file + the active frame's
+ * submodule overview + repo root, decide whether a commit-diff Enter
+ * keystroke should drill into a submodule and, if so, what payload
+ * the `pushRepoFrame` action should carry.
+ *
+ * Returns undefined when:
+ *   - We don't know the active repo root yet (boot still in flight).
+ *   - The file's path doesn't correspond to a registered submodule.
+ *   - The submodule overview hasn't loaded yet for the active frame.
+ *
+ * The `submoduleChange` on the file preview is the source of truth
+ * for the entry range; we never need to re-run the diff to populate
+ * the (oldSha, newSha) pair.
+ */
+function resolveCommitDiffDrillInTarget(args) {
+    const { selectedFile, submodules, activeRepoRoot } = args;
+    if (!activeRepoRoot)
+        return undefined;
+    if (!submodules || !submodules.hasSubmodules)
+        return undefined;
+    const entry = findSubmoduleByPath(submodules, selectedFile.path);
+    if (!entry)
+        return undefined;
+    return {
+        label: entry.name,
+        workdir: join$1(activeRepoRoot, entry.path),
+        entryRange: deriveEntryRange(selectedFile.submoduleChange),
+    };
+}
+/**
+ * Convert the structured `SubmoduleChange` (from `extractSubmoduleChange`)
+ * into the `entryRange` shape `LogInkRepoFrame` carries. Modified
+ * submodules surface both shas; added / removed surface only one,
+ * which isn't enough to scope a history range — those cases return
+ * undefined and the frame lands on the submodule's full history.
+ */
+function deriveEntryRange(change) {
+    if (!change)
+        return undefined;
+    if (change.kind === 'modified') {
+        return { oldSha: change.before, newSha: change.after };
+    }
+    return undefined;
+}
+/**
+ * Pure resolver for the submodules-view drill-in (#931 PR 4 / #932).
+ * Given the cursored row index + the submodule overview + the active
+ * frame's repo root, build the `pushRepoFrame` payload Enter should
+ * dispatch. Returns undefined when:
+ *
+ *   - The active repo root hasn't loaded yet.
+ *   - The submodule overview hasn't loaded (or is empty).
+ *   - The cursor is past the end of the entries (race between a
+ *     refresh that removed a submodule and a key press still in
+ *     flight against the old length).
+ *   - The cursored entry has no `path` recorded. The `.gitmodules`
+ *     parser already filters these out upstream, but the resolver
+ *     defends against it so the cursor can't yank the user into a
+ *     workdir-less frame.
+ */
+function resolveSubmoduleViewDrillInTarget(args) {
+    const { selectedIndex, submodules, activeRepoRoot } = args;
+    if (!activeRepoRoot)
+        return undefined;
+    if (!submodules || !submodules.hasSubmodules)
+        return undefined;
+    const entry = submodules.entries[selectedIndex];
+    if (!entry || !entry.path)
+        return undefined;
+    return {
+        label: entry.name,
+        workdir: join$1(activeRepoRoot, entry.path),
+    };
+}
+
+/**
+ * Reconcile the per-frame runtime list against the current view-model
+ * stack. Three cases:
+ *
+ *   - **No change** — same length, returns `prev` unchanged so React
+ *     reference equality skips downstream re-renders.
+ *   - **Pop** — stack shrunk, returns `prev.slice(0, stack.length)`.
+ *     The dropped runtimes are released to the GC; the surviving
+ *     runtimes (root + any intermediate frames) keep their cached
+ *     `git` + `context` so a re-push lands on warm state.
+ *   - **Push** — stack grew, builds a fresh runtime via the supplied
+ *     `createRuntime(frame, depth)` factory for each newly-deeper
+ *     frame. The caller is responsible for the factory's content;
+ *     this module never imports `simple-git` or `loadLogInkContext`
+ *     directly so it stays unit-testable without a real repo on disk.
+ *
+ * Returns `newlyAddedIndices` so the caller's effect knows which
+ * frames need their initial context fetch kicked off. On a no-op or
+ * pop, the list is empty.
+ *
+ * The reducer's `pushRepoFrame` / `popRepoFrame` actions are the only
+ * things that mutate `state.repoStack`; both are monotone — push
+ * appends one, pop drops one — so this helper never needs to handle
+ * "frame at index i changed identity in place." If that invariant ever
+ * loosens, this helper should error rather than silently mis-bind a
+ * `SimpleGit` to the wrong working directory.
+ */
+function syncRepoStackRuntimes(prev, stack, createRuntime) {
+    if (stack.length < prev.length) {
+        return { runtimes: prev.slice(0, stack.length), newlyAddedIndices: [] };
+    }
+    if (stack.length === prev.length) {
+        return { runtimes: prev, newlyAddedIndices: [] };
+    }
+    const next = prev.slice();
+    const newlyAddedIndices = [];
+    for (let i = prev.length; i < stack.length; i += 1) {
+        next.push(createRuntime(stack[i], i));
+        newlyAddedIndices.push(i);
+    }
+    return { runtimes: next, newlyAddedIndices };
+}
+/**
+ * Top-of-stack runtime — the one every active surface, loader, and
+ * action target reads from. Undefined when the runtime list is empty
+ * (which production code never produces — `createLogInkState` always
+ * seeds a root frame, so the corresponding root runtime is built on
+ * mount and the array is non-empty for the lifetime of the session).
+ */
+function getActiveRepoFrameRuntime(runtimes) {
+    return runtimes[runtimes.length - 1];
+}
+/**
+ * Immutably update one frame's runtime entry. Used by the app shell's
+ * loader effects when a frame's `context` or `contextStatus` changes
+ * — replacing the entry in place lets React's referential equality
+ * skip re-renders on unrelated frames.
+ *
+ * Out-of-range indices are no-ops (return `prev` unchanged) so the
+ * caller doesn't have to guard against race-y stack changes between
+ * the load kickoff and the load-complete callback.
+ */
+function updateRepoFrameRuntime(runtimes, index, updater) {
+    if (index < 0 || index >= runtimes.length)
+        return runtimes;
+    const next = runtimes.slice();
+    next[index] = updater(next[index]);
+    return next;
+}
+
 /**
  * Persist the user's preferred diff view mode (unified vs side-by-side
  * split — #785) per repo. Mirrors `inkSidebarPersistence.ts` so the
@@ -28806,7 +29373,13 @@ function renderHeader(h, components, state, context, contextStatus, columns, the
         ? '  loading commits'
         : isLogInkContextLoading(contextStatus) ? '  loading context' : '';
     const breadcrumb = formatLogInkBreadcrumb(state.viewStack);
-    const view = breadcrumb ? `  ${breadcrumb}` : '';
+    const repoCrumb = formatLogInkRepoBreadcrumb(state.repoStack);
+    // Repo breadcrumb (when nested) comes first so the user sees which
+    // submodule they're in at a glance, then the view breadcrumb (when
+    // pushed deeper than the root view). The truncate fallback in the
+    // title row still applies — when both fight for space, the ellipsis
+    // lands at the end of whichever segment overflows.
+    const view = combineLogInkBreadcrumbSegments(repoCrumb, breadcrumb);
     // Mode indicator (P2.2) — surfaces the current input mode so users
     // never wonder why `q` doesn't quit while they're editing or filtering.
     const mode = state.commitCompose.editing
@@ -30454,30 +31027,52 @@ function filterChippedRefs(refs, chip) {
         return true;
     });
 }
-function getBranchTipChip(refs) {
+/**
+ * `remoteNames` lets the caller pass the repository's actual remote
+ * names (e.g. `['origin', 'upstream']`) so refs are classified by
+ * remote-prefix rather than by "contains a slash". Without it a local
+ * feature branch like `feat/x` looks identical to a remote-tracking
+ * `origin/x` and gets the wrong colour. When the list is omitted the
+ * function falls back to the legacy slash-as-remote heuristic — the
+ * sensible default before branch data has loaded and a back-compat
+ * affordance for callers that have no remote data to hand.
+ */
+function getBranchTipChip(refs, remoteNames) {
+    // Empty list is treated the same as omitted: branch data hasn't
+    // loaded yet, so we don't have ground truth and the legacy "slash =
+    // remote" heuristic is the best guess for first paint.
+    const hasRemoteList = Array.isArray(remoteNames) && remoteNames.length > 0;
+    const isRemoteRef = (ref) => {
+        if (!ref.includes('/'))
+            return false;
+        if (!hasRemoteList)
+            return true;
+        return remoteNames.some((remote) => remote && ref.startsWith(`${remote}/`));
+    };
     for (const ref of refs) {
         if (ref.startsWith('HEAD -> ')) {
             const name = ref.slice('HEAD -> '.length).trim();
             if (name)
-                return { name, isHead: true };
+                return { name, isHead: true, kind: 'head' };
         }
     }
     for (const ref of refs) {
         if (ref === 'HEAD' ||
             ref.startsWith('HEAD -> ') ||
             ref.startsWith('tag: ') ||
-            ref.includes('/')) {
+            isRemoteRef(ref)) {
             continue;
         }
-        if (ref.trim())
-            return { name: ref.trim(), isHead: false };
+        if (ref.trim()) {
+            return { name: ref.trim(), isHead: false, kind: 'local' };
+        }
     }
     for (const ref of refs) {
         if (ref.startsWith('tag: ') || ref === 'HEAD' || ref.startsWith('HEAD -> ')) {
             continue;
         }
-        if (ref.includes('/') && ref.trim()) {
-            return { name: ref.trim(), isHead: false };
+        if (isRemoteRef(ref) && ref.trim()) {
+            return { name: ref.trim(), isHead: false, kind: 'remote' };
         }
     }
     return undefined;
@@ -31240,8 +31835,12 @@ const BRANCH_CHIP_MAX_NAME_WIDTH = 20;
  * descriptor so the caller can pass it to `filterChippedRefs` and
  * avoid emitting the same branch a second time in the trailing list.
  */
-function renderBranchTipChip(h, Text, commit, theme, key, selected) {
-    const chip = getBranchTipChip(commit.refs);
+// Exported for unit / snapshot testing in branchTipChipRender.test.ts.
+// The function isn't part of the public surface of this module — the
+// rest of the file is internal — but the chip-rendering logic is
+// dense enough that structural snapshot tests pay for themselves.
+function renderBranchTipChip(h, Text, commit, theme, key, selected, remoteNames) {
+    const chip = getBranchTipChip(commit.refs, remoteNames);
     if (!chip)
         return { node: null, width: 0, chip };
     const truncated = truncateCells(chip.name, BRANCH_CHIP_MAX_NAME_WIDTH);
@@ -31262,7 +31861,23 @@ function renderBranchTipChip(h, Text, commit, theme, key, selected) {
             chip,
         };
     }
-    const accent = chip.isHead ? theme.colors.success : theme.colors.info;
+    // Three-way colour assignment matches `BranchTipChipKind`:
+    //
+    //   - HEAD  → success (the user's current branch — bright green)
+    //   - local → info    (other local branches — calm blue)
+    //   - remote → warning (remote-tracking refs like origin/main —
+    //                      distinct so "where is upstream?" reads at a glance)
+    //
+    // Without the remote/local split, a chip on `origin/main` looked
+    // identical to a local-branch chip, so users couldn't tell from the
+    // commit list where their upstream actually pointed. The warning hue
+    // (typically a muted yellow / orange) is purposeful: not alarming,
+    // but visibly different from the local blue.
+    const accent = chip.kind === 'head'
+        ? theme.colors.success
+        : chip.kind === 'remote'
+            ? theme.colors.warning
+            : theme.colors.info;
     return {
         node: h(Text, {}, h(Text, { key, inverse: true, color: accent, bold: chip.isHead }, body), h(Text, { key: `${key}-pad` }, ' ')),
         width: cellWidth(body) + 1,
@@ -31352,7 +31967,7 @@ function renderLaneSegmentSpans(h, Text, segments, theme, padTo, keyPrefix, opti
  * Truncation is per-segment so the variable-length message field gets
  * the leftover budget after fixed segments are accounted for.
  */
-function renderCommitHistoryRow(h, Text, commit, graph, graphWidth, selected, theme, index, panelWidth, density, fullGraph, bucketed, now, laneSegments, isRecent = false) {
+function renderCommitHistoryRow(h, Text, commit, graph, graphWidth, selected, theme, index, panelWidth, density, fullGraph, bucketed, now, laneSegments, isRecent = false, remoteNames) {
     // Total cells available to the row content. Earlier revisions used a
     // hardcoded 140 here, which let row content overflow whenever the
     // panel was narrower than that — Ink would wrap onto a second visual
@@ -31369,7 +31984,7 @@ function renderCommitHistoryRow(h, Text, commit, graph, graphWidth, selected, th
     // out whatever the chip already shows so the row doesn't print
     // `[main] feat: x [HEAD -> main]` with the same info on both ends.
     const chip = fullGraph
-        ? renderBranchTipChip(h, Text, commit, theme, `${commit.hash}-${index}-chip`, selected)
+        ? renderBranchTipChip(h, Text, commit, theme, `${commit.hash}-${index}-chip`, selected, remoteNames)
         : { node: null, width: 0, chip: undefined };
     const refs = formatInkRefLabels(filterChippedRefs(commit.refs, chip.chip));
     const fixedWidth = graphWidth + 1 + commit.shortHash.length + 1 + dateSegmentWidth + chip.width;
@@ -31431,7 +32046,7 @@ function renderCommitHistoryRow(h, Text, commit, graph, graphWidth, selected, th
  * line stays dim regardless of selection so it doesn't pull the eye
  * away from the subject.
  */
-function renderStackedCommitHistoryRow(h, Text, Box, commit, graph, graphWidth, selected, theme, index, panelWidth, fullGraph, now, laneSegments, isRecent = false) {
+function renderStackedCommitHistoryRow(h, Text, Box, commit, graph, graphWidth, selected, theme, index, panelWidth, fullGraph, now, laneSegments, isRecent = false, remoteNames) {
     const totalWidth = Math.max(20, panelWidth - 4);
     const accent = theme.noColor ? undefined : theme.colors.accent;
     const muted = theme.noColor ? undefined : theme.colors.muted;
@@ -31442,7 +32057,7 @@ function renderStackedCommitHistoryRow(h, Text, Box, commit, graph, graphWidth,
     // same way as the single-line variant, but only in full-graph mode.
     const recentMarkerWidth = isRecent ? 2 : 0;
     const chip = fullGraph
-        ? renderBranchTipChip(h, Text, commit, theme, `${commit.hash}-${index}-stk-chip`, selected)
+        ? renderBranchTipChip(h, Text, commit, theme, `${commit.hash}-${index}-stk-chip`, selected, remoteNames)
         : { node: null, width: 0, chip: undefined };
     const lineOneFixed = graphWidth + 1 + commit.shortHash.length + 1 + recentMarkerWidth + chip.width;
     const subject = truncateCells(commit.message, Math.max(8, totalWidth - lineOneFixed));
@@ -31517,6 +32132,17 @@ function renderHistoryPanel(h, components, state, context, bodyRows, width, them
     const { Box, Text } = components;
     const focused = state.focus === 'commits';
     const worktree = context.worktree;
+    // Distinct remote names seen across the repo's remote-tracking
+    // branches — `['origin']` for a typical fork, `['origin', 'upstream']`
+    // when the user has both. Used to classify branch-tip chips so a
+    // slashed local branch like `feat/x` doesn't get mis-coloured as
+    // remote. When branch data hasn't loaded yet, `undefined` makes the
+    // chip helper fall back to the legacy slash-based heuristic.
+    const remoteNames = context.branches?.remoteBranches
+        ? Array.from(new Set(context.branches.remoteBranches
+            .map((branch) => branch.remote)
+            .filter((remote) => Boolean(remote))))
+        : undefined;
     // Set of just-landed commit hashes for the "new commit" marker.
     // Populated for ~5s after a split-apply or other commit-creating
     // operation; auto-cleared by the runtime so it doesn't linger.
@@ -31625,9 +32251,9 @@ function renderHistoryPanel(h, components, state, context, bodyRows, width, them
                 }, truncateCells(substituteGraphChars(item.graph.padEnd(visible.graphWidth), { ascii: theme.ascii }), Math.max(8, width - 4)));
             }
             if (rowMode === 'stacked') {
-                return renderStackedCommitHistoryRow(h, Text, Box, item.commit, item.graph, visible.graphWidth, Boolean(item.selected) && !realSelectionSuppressed, theme, index, width, state.fullGraph, now, item.laneSegments, recentCommitsSet.has(item.commit.hash));
+                return renderStackedCommitHistoryRow(h, Text, Box, item.commit, item.graph, visible.graphWidth, Boolean(item.selected) && !realSelectionSuppressed, theme, index, width, state.fullGraph, now, item.laneSegments, recentCommitsSet.has(item.commit.hash), remoteNames);
             }
-            return renderCommitHistoryRow(h, Text, item.commit, item.graph, visible.graphWidth, Boolean(item.selected) && !realSelectionSuppressed, theme, index, width, density, state.fullGraph, Boolean(dateBucketingNow), now, item.laneSegments, recentCommitsSet.has(item.commit.hash));
+            return renderCommitHistoryRow(h, Text, item.commit, item.graph, visible.graphWidth, Boolean(item.selected) && !realSelectionSuppressed, theme, index, width, density, state.fullGraph, Boolean(dateBucketingNow), now, item.laneSegments, recentCommitsSet.has(item.commit.hash), remoteNames);
         }));
 }
 
@@ -31783,20 +32409,38 @@ function renderChordOverlay(h, components, state, width, theme, focused) {
 }
 function renderHelpPanel(h, components, state, width, theme, focused) {
     const { Box, Text } = components;
-    const children = [
-        h(Text, { bold: true, key: 'title' }, panelTitle('Help', focused)),
-    ];
+    // Build the full list of body rows (everything below the title).
+    // Splitting into title + body lets us window the body by
+    // `state.helpScrollOffset` while keeping the title pinned.
+    const body = [];
     const sections = getLogInkHelpSections({
         activeView: state.activeView,
         focus: state.focus,
     });
     for (const section of sections) {
-        children.push(h(Text, { key: `${section.title}-spacer` }, ''));
-        children.push(h(Text, { bold: true, key: section.title }, section.title));
+        body.push(h(Text, { key: `${section.title}-spacer` }, ''));
+        body.push(h(Text, { bold: true, key: section.title }, section.title));
         section.bindings.forEach((binding) => {
-            children.push(h(Text, { key: `${section.title}:${binding.id}` }, truncateCells(`${formatBindingKeys(binding).padEnd(14)} ${binding.description}`, width - 4)));
+            body.push(h(Text, { key: `${section.title}:${binding.id}` }, truncateCells(`${formatBindingKeys(binding).padEnd(14)} ${binding.description}`, width - 4)));
         });
     }
+    // Clamp the offset against actual content length. The reducer
+    // only floor-clamps at 0; here we ceiling-clamp so j past EOF
+    // sticks at the last row rather than scrolling into emptiness.
+    // Reserve one row at the bottom so the user can always see the
+    // tail of the last section.
+    const maxOffset = Math.max(0, body.length - 1);
+    const offset = Math.min(state.helpScrollOffset, maxOffset);
+    const children = [
+        h(Text, { bold: true, key: 'title' }, panelTitle('Help', focused)),
+    ];
+    // Visual hint that there's content scrolled above. The dim style
+    // matches the rest of the chrome's "metadata" voice and avoids
+    // stealing attention from the bindings themselves.
+    if (offset > 0) {
+        children.push(h(Text, { key: 'more-above', dimColor: true }, '↑ more above'));
+    }
+    children.push(...body.slice(offset));
     return h(Box, {
         borderColor: focusBorderColor(theme, focused),
         borderStyle: theme.borderStyle,
@@ -34532,7 +35176,7 @@ function enrichFilterActionWithRectification(action, state, context) {
     }
 }
 function LogInkApp(deps) {
-    const { appLabel, clipboardRunner, dateBucketingEnabled, git, idleTipsEnabled, ink, initialView, loadRows, logArgv, React, resumeRef, rows, theme } = deps;
+    const { appLabel, clipboardRunner, dateBucketingEnabled, git: rootGit, idleTipsEnabled, ink, initialView, loadRows, logArgv, React, resumeRef, rows, theme } = deps;
     const { Box, Text, useApp, useInput, useWindowSize } = ink;
     const h = React.createElement;
     const { exit } = useApp();
@@ -34563,16 +35207,98 @@ function LogInkApp(deps) {
         // immediately while the chrome still flags the refresh.
         bootLoading: Boolean(loadRows),
     }));
-    const [context, setContext] = React.useState({});
-    const [contextStatus, setContextStatus] = React.useState(() => {
-        // Boot starts every fetched key in 'loading' so the surfaces show
-        // their loading hints immediately. `pullRequest` is the exception
-        // (#808) — it isn't part of the boot fetch entries; it lazy-loads
-        // when the user enters the PR view. Marking it 'idle' avoids a
-        // permanent "loading" flag in the chrome and lets the dedicated
-        // PR view's own load effect drive its loading state.
-        return updateLogInkContextStatus(createLogInkContextStatus('loading'), 'pullRequest', 'idle');
-    });
+    // Nested-repo runtime stack (#931). Each frame holds the live
+    // `SimpleGit`, the loaded `LogInkContext`, and the per-key load
+    // status the chrome reads. The active (top-of-stack) entry drives
+    // every loader and surface; popping a frame restores the parent's
+    // cached entry so a drill-in / drill-out round trip doesn't re-pay
+    // the context load cost. Seeded with a single root runtime against
+    // the cwd `coco ui` was launched in.
+    const [runtimes, setRuntimes] = React.useState(() => [{
+            git: rootGit,
+            context: {},
+            contextStatus: createInitialContextStatus(),
+        }]);
+    // Sync `runtimes` against the view-model stack on every push / pop.
+    // The sync is monotone — push appends a new runtime via the factory,
+    // pop slices off the top runtime; the parent's cached state survives.
+    // The factory is wrapped to capture `rootGit` so a defensively-pushed
+    // frame without a workdir still has a working `SimpleGit` bound.
+    React.useEffect(() => {
+        setRuntimes((prev) => {
+            const { runtimes: next } = syncRepoStackRuntimes(prev, state.repoStack, (frame) => createRepoFrameRuntime(frame, rootGit));
+            return next;
+        });
+    }, [state.repoStack, rootGit]);
+    // Active-frame projection (#931). `git`, `context`, `contextStatus`
+    // — every existing closure / effect / surface reads these names; the
+    // only thing this PR changes is where they come from. When the user
+    // drills into a submodule, the top-of-stack runtime swaps, every
+    // dep array that lists `git` re-fires, and the loaders refetch
+    // against the submodule's working tree.
+    const activeRuntime = getActiveRepoFrameRuntime(runtimes) ?? {
+        git: rootGit,
+        context: {},
+        contextStatus: createInitialContextStatus(),
+    };
+    const git = activeRuntime.git;
+    const context = activeRuntime.context;
+    const contextStatus = activeRuntime.contextStatus;
+    // Wrappers that delegate to the active frame's runtime entry so the
+    // existing call sites stay byte-identical. Support both function-
+    // updater and value-updater forms (the codebase uses both).
+    const setContext = React.useCallback((arg) => {
+        setRuntimes((prev) => {
+            const depth = prev.length - 1;
+            if (depth < 0)
+                return prev;
+            return updateRepoFrameRuntime(prev, depth, (frame) => ({
+                ...frame,
+                context: typeof arg === 'function'
+                    ? arg(frame.context)
+                    : arg,
+            }));
+        });
+    }, []);
+    const setContextStatus = React.useCallback((arg) => {
+        setRuntimes((prev) => {
+            const depth = prev.length - 1;
+            if (depth < 0)
+                return prev;
+            return updateRepoFrameRuntime(prev, depth, (frame) => ({
+                ...frame,
+                contextStatus: typeof arg === 'function'
+                    ? arg(frame.contextStatus)
+                    : arg,
+            }));
+        });
+    }, []);
+    // #931 PR 3b — Absolute repo root for the active frame's `git`.
+    // Resolved asynchronously after every `git` swap (push / pop /
+    // boot) so the commit-diff drill-in helper can construct absolute
+    // workdirs for submodule paths recorded in `.gitmodules` (which
+    // are repo-relative). Undefined during the brief moment between
+    // git swap and the revparse callback resolving.
+    const [activeRepoRoot, setActiveRepoRoot] = React.useState(undefined);
+    React.useEffect(() => {
+        let cancelled = false;
+        void (async () => {
+            try {
+                const root = (await git.revparse(['--show-toplevel'])).trim();
+                if (!cancelled && root) {
+                    setActiveRepoRoot(root);
+                }
+            }
+            catch {
+                if (!cancelled) {
+                    setActiveRepoRoot(undefined);
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [git]);
     const [detail, setDetail] = React.useState(undefined);
     const [detailLoading, setDetailLoading] = React.useState(false);
     const [filePreview, setFilePreview] = React.useState(undefined);
@@ -35092,9 +35818,26 @@ function LogInkApp(deps) {
         selectedWorktreeFile?.worktreeStatus,
         state.activeView,
     ]);
+    // #931 PR 5 — Cache-aware boot load. The frame's `git` instance is
+    // the dep that drives this effect; on push, the new frame's runtime
+    // starts every key in `'loading'` and we fetch fresh. On pop, the
+    // parent's runtime carries cached context across the drill-out cycle
+    // (`'ready'` for already-loaded keys), and the per-key gate below
+    // skips the fetch so the user's drill-out is instant + flicker-free.
+    //
+    // `contextStatusRef` reads the latest status without putting
+    // `contextStatus` in the effect deps — including it would re-fire
+    // the effect on every per-key 'ready' write the effect itself
+    // produces, causing duplicate in-flight fetches for not-yet-completed
+    // keys. The ref pattern gives us "read latest" semantics with the
+    // effect still gated on git swaps only.
+    const contextStatusRef = React.useRef(contextStatus);
+    contextStatusRef.current = contextStatus;
     React.useEffect(() => {
         let active = true;
         loadLogInkContextEntries(git).forEach(({ key, load }) => {
+            if (contextStatusRef.current[key] === 'ready')
+                return;
             void load().then((value) => {
                 if (!active) {
                     return;
@@ -37509,6 +38252,37 @@ function LogInkApp(deps) {
             commitDiffSelectedSha: state.diffSource === 'commit'
                 ? selected?.hash
                 : undefined,
+            // #931 PR 3b — Submodule drill-in target for the cursored file
+            // in a commit diff. Resolved per-render so the Enter handler in
+            // `inkInput.ts` doesn't have to re-walk the submodule overview;
+            // undefined whenever the cursored file isn't a registered
+            // submodule (or the overview / repo root haven't loaded yet).
+            commitDiffSubmoduleDrillIn: state.diffSource === 'commit' && selectedDetailFile
+                ? resolveCommitDiffDrillInTarget({
+                    selectedFile: {
+                        path: selectedDetailFile.path,
+                        submoduleChange: filePreview?.path === selectedDetailFile.path
+                            ? filePreview.submoduleChange
+                            : undefined,
+                    },
+                    submodules: context.submodules,
+                    activeRepoRoot,
+                })
+                : undefined,
+            // #931 PR 4 / #932 — Submodule drill-in target for the cursored
+            // row in the dedicated submodules view. Resolved per-render so
+            // the Enter handler in `inkInput.ts` doesn't have to re-walk the
+            // submodule overview. Gated on `activeView === 'submodules'` so
+            // a stale resolution from a different view can't accidentally
+            // fire — the runtime only ever populates it when the user is
+            // actually on the view.
+            submoduleViewDrillIn: state.activeView === 'submodules'
+                ? resolveSubmoduleViewDrillInTarget({
+                    selectedIndex: state.selectedSubmoduleIndex,
+                    submodules: context.submodules,
+                    activeRepoRoot,
+                })
+                : undefined,
             worktreeDirty,
             conflictFileCount: context.operation?.conflictedFiles.length,
             conflictSelectedPath: (() => {
@@ -38257,6 +39031,27 @@ function formatCommitDetail(detail, format) {
     ].join('\n');
 }
 
+/**
+ * Friendly empty-repo message for the non-interactive log path.
+ *
+ * In `--json` mode we emit an empty array so machine consumers see a
+ * well-defined "no commits" result without a parse error. In table
+ * mode we print a human one-liner that names the next-step commands
+ * the user is likely after. Either way we exit 0 — "no commits" is
+ * a valid repo state, not a failure.
+ */
+function formatEmptyRepoResult(format) {
+    if (format === 'json') {
+        return '[]';
+    }
+    return [
+        "No commits yet — this looks like a fresh `git init`'d repo.",
+        '',
+        'Get started:',
+        '  • `coco commit` to draft your first commit message with AI',
+        '  • `git commit -m "chore: initial commit"` to commit by hand',
+    ].join('\n');
+}
 const handler$3 = async (argv) => {
     // `--repo <dir>` (alias `--cwd`) — apply the global flag via the
     // shared helper. After this returns, `process.cwd()` and the git
@@ -38272,6 +39067,22 @@ const handler$3 = async (argv) => {
         });
         return;
     }
+    // Empty-repo short-circuit. Without this, the underlying `git log`
+    // crashes the command and the user sees a raw "fatal: your current
+    // branch 'main' does not have any commits yet" + a generic "Failed
+    // to execute command" banner. We catch the unborn-HEAD state and
+    // emit a friendly next-step hint (or an empty array in JSON mode)
+    // and exit 0 — "no commits" is a valid repo state, not an error.
+    //
+    // Only applies to the non-interactive path: the TUI runtime gets
+    // its own empty-state rendering inside the workstation.
+    if (!argv.interactive && (await isEmptyRepo(git))) {
+        await handleResult({
+            result: formatEmptyRepoResult(format),
+            mode: 'stdout',
+        });
+        return;
+    }
     // Interactive path defers the commit log fetch into the runtime
     // (#808) so the TUI mounts immediately with a "Loading commits…"
     // placeholder. The non-interactive (stdout) path still needs rows