git-coco 0.51.0 → 0.53.0

package/dist/index.js

@@ -78,7 +78,7 @@ var readline__namespace = /*#__PURE__*/_interopNamespaceDefault(readline);
 /**
  * Current build version from package.json
  */
-const BUILD_VERSION = "0.51.0";
+const BUILD_VERSION = "0.53.0";
 
 const isInteractive = (config) => {
     return config?.mode === 'interactive' || !!config?.interactive;
@@ -8229,9 +8229,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.
@@ -8240,43 +8271,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 [];
 }
@@ -14344,7 +14385,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 => {
@@ -14421,10 +14468,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);
         },
     });
@@ -15577,6 +15629,7 @@ Structural rules:
 - Only use hunk IDs LITERALLY copied from the "Staged hunk inventory" section below. Do not invent or guess hunk IDs.
 - If the hunk inventory says "No hunk-level inventory available" then EVERY group's "hunks" array MUST be empty (use only "files"). Do not write hunk IDs like "path::hunk-1" when no hunk inventory exists — those are not valid.
 - Prefer 2-5 commits unless the changes are truly all one topic.
+- Order the groups in the sequence they would logically be built — foundational changes first, consumers after. If group B uses a symbol, function, type, or file introduced in group A, A MUST appear before B in the array. The applier commits in array order, so this order becomes the git history. Example: a "feat: add helpers" group that introduces \`formatX()\` must come before a "feat: wire helpers into renderer" group that calls \`formatX()\`, even if the staged diff is presented in the opposite order. When two groups have no dependency relationship, prefer the one closer to a "scaffold" (types, config, new files) before the one closer to a "use site" (existing files modified to consume the new code).
 
 Commit message style:
 - Write each "title" in the imperative mood ("add", not "added"), under 72 chars.
@@ -17909,6 +17962,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).
  *
@@ -18327,6 +18412,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) {
@@ -18398,6 +18496,7 @@ async function getCommitFilePreview(git, commit, file, limit = 40) {
             deletions: file.deletions,
         },
         hunks: finalHunks,
+        submoduleChange,
     };
 }
 
@@ -20987,6 +21086,37 @@ function getLogInkWorkflowActions() {
             kind: 'normal',
             requiresConfirmation: false,
         },
+        // Per-view variants of fetch / pull / push that act on the
+        // cursored branch instead of the current one. Empty `key` keeps
+        // them palette-discoverable without registering a global hotkey —
+        // inkInput.ts dispatches them contextually when the user presses
+        // F / U / P while the branches sidebar is focused. Outside that
+        // context, the F / U / P keys still fire the global *-current-*
+        // / fetch-remotes variants above.
+        {
+            id: 'fetch-selected-branch',
+            key: '',
+            label: 'Fetch selected branch',
+            description: 'Run `git fetch <remote> <branch>` for the cursored branch in the branches view / sidebar.',
+            kind: 'normal',
+            requiresConfirmation: false,
+        },
+        {
+            id: 'pull-selected-branch',
+            key: '',
+            label: 'Pull selected branch',
+            description: 'Pull the cursored branch in the branches view / sidebar. Falls back to a fast-forward-only refspec fetch when the branch is not currently checked out; refuses non-FF.',
+            kind: 'normal',
+            requiresConfirmation: false,
+        },
+        {
+            id: 'push-selected-branch',
+            key: '',
+            label: 'Push selected branch',
+            description: 'Run `git push <remote> <branch>` for the cursored branch in the branches view / sidebar.',
+            kind: 'normal',
+            requiresConfirmation: false,
+        },
         {
             // Per-view-only — the inkInput handler scopes this to the tags
             // surface so we don't expose `R` as a remote-delete from elsewhere.
@@ -21810,6 +21940,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);
@@ -21877,8 +22057,22 @@ function getLogInkFooterHints(options) {
         // "enter open" hint that drills into the dedicated view.
         const itemsPresent = (options.sidebarItemCount ?? 0) > 0;
         if (itemsPresent && options.sidebarTab === 'branches') {
+            // P / U / F fire the global pull-current-branch, push-current-branch,
+            // fetch-remotes workflows — already implemented, just not visible in
+            // the footer before. Surfacing them here matters because the user's
+            // attention is on a branch when the branches sidebar is focused;
+            // pull / push / fetch are the next obvious actions.
+            //
+            // Note: `U` and `P` currently operate on the CURRENT branch, not the
+            // cursored one. Task #5 will extend them to act on the cursored row;
+            // until then the labels read as "current-branch ops" by virtue of
+            // matching the workflow descriptions.
             return {
-                contextual: ['↑/↓ branches', '←/→ tab', 'enter checkout', 'D delete', 'R rename', 'u upstream'],
+                contextual: [
+                    '↑/↓ branches', '←/→ tab', 'enter checkout',
+                    'F fetch', 'U pull', 'P push',
+                    'D delete', 'R rename', 'u upstream',
+                ],
                 global: NORMAL_GLOBAL_HINTS,
             };
         }
@@ -22564,6 +22758,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 };
@@ -22708,7 +22989,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: '',
@@ -22721,6 +23002,7 @@ function createLogInkState(rows, options = {}) {
         filterMode: false,
         fullGraph: false,
         showHelp: false,
+        helpScrollOffset: 0,
         showCommandPalette: false,
         workflowActionId: undefined,
         pendingConfirmationId: undefined,
@@ -22728,8 +23010,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 },
@@ -22750,6 +23037,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':
@@ -23172,6 +23468,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 };
@@ -23343,6 +23647,7 @@ function applyLogInkAction(state, action) {
                 filterMode: !state.filterMode,
                 showCommandPalette: false,
                 showHelp: false,
+                helpScrollOffset: 0,
                 pendingKey: undefined,
             };
         case 'toggleGraph':
@@ -23351,19 +23656,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: '',
@@ -24010,6 +24331,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
@@ -24557,8 +24886,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
@@ -24579,6 +24937,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' })];
@@ -24861,6 +25228,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') {
@@ -25343,6 +25721,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' &&
@@ -26081,6 +26501,27 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
         events.push({ type: 'createManualCommit' });
         return events;
     }
+    // Context-sensitive per-branch variants of F / U / P. When the
+    // user has the branches sidebar / view focused with at least one
+    // branch, F / U / P should act on the cursored row, not on the
+    // current branch. This intercept fires BEFORE the generic
+    // workflow-by-key lookup below so the global *-current-branch
+    // variants don't shadow the contextual ones.
+    //
+    // Outside the branches context, the generic lookup runs and the
+    // F / U / P keys hit the global `fetch-remotes` / `pull-current-branch`
+    // / `push-current-branch` workflows as before.
+    if (isBranchActionTarget(state) && context.branchCount) {
+        if (inputValue === 'F') {
+            return [{ type: 'runWorkflowAction', id: 'fetch-selected-branch' }];
+        }
+        if (inputValue === 'U') {
+            return [{ type: 'runWorkflowAction', id: 'pull-selected-branch' }];
+        }
+        if (inputValue === 'P') {
+            return [{ type: 'runWorkflowAction', id: 'push-selected-branch' }];
+        }
+    }
     const workflowAction = getLogInkWorkflowActionByKey(inputValue);
     if (workflowAction?.requiresConfirmation) {
         return [action({ type: 'setPendingConfirmation', value: workflowAction.id })];
@@ -26250,6 +26691,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.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: path.join(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: path.join(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
@@ -26990,6 +27624,106 @@ function pushCurrentBranch(git) {
 function setUpstream(git, localBranch, upstreamBranch) {
     return runAction$5(() => git.raw(['branch', '--set-upstream-to', upstreamBranch, localBranch]), `Set ${localBranch} upstream to ${upstreamBranch}`);
 }
+/**
+ * Push an arbitrary local branch (need not be the current branch) to
+ * its remote. Refuses when the branch has no upstream and no remote
+ * defaulting is configured — that branch needs a `git push -u …` from
+ * the shell first.
+ *
+ * Pairs with `pushCurrentBranch` (no-arg variant); the workstation
+ * dispatcher picks one or the other based on where the cursor is.
+ */
+function pushBranch(git, branch) {
+    if (branch.type !== 'local') {
+        return Promise.resolve({
+            ok: false,
+            message: 'Only local branches can be pushed.',
+        });
+    }
+    if (!branch.upstream || !branch.remote) {
+        return Promise.resolve({
+            ok: false,
+            message: `${branch.shortName} has no upstream — checkout the branch and run \`git push -u <remote> ${branch.shortName}\` first.`,
+        });
+    }
+    return runAction$5(() => git.raw(['push', branch.remote, branch.shortName]), `Pushed ${branch.shortName} to ${branch.upstream}`);
+}
+/**
+ * Fetch the cursored branch's upstream from its remote. Side-effect
+ * free on the working tree — just updates the remote-tracking ref.
+ * Works for any branch with an upstream regardless of checkout state.
+ *
+ * Falls back to a clean error when the branch has no upstream
+ * configured (`git fetch <remote> <name>` would assume an unrelated
+ * default refspec and surprise the user).
+ */
+function fetchBranch(git, branch) {
+    if (branch.type !== 'local') {
+        return Promise.resolve({
+            ok: false,
+            message: 'Only local branches can be fetched per-branch — use F to fetch all remotes.',
+        });
+    }
+    if (!branch.upstream || !branch.remote) {
+        return Promise.resolve({
+            ok: false,
+            message: `${branch.shortName} has no upstream — nothing to fetch.`,
+        });
+    }
+    // `branch.upstream` is the short form (e.g. `origin/main`); the
+    // ref name after the remote prefix is what fetch wants as the
+    // refspec source. For a remote `origin` and upstream `origin/main`
+    // we run `git fetch origin main`.
+    const upstreamRef = branch.upstream.startsWith(`${branch.remote}/`)
+        ? branch.upstream.slice(branch.remote.length + 1)
+        : branch.upstream;
+    return runAction$5(() => git.raw(['fetch', branch.remote, upstreamRef]), `Fetched ${branch.upstream}`);
+}
+/**
+ * Pull the cursored branch. Branches into two paths based on whether
+ * the branch is currently checked out:
+ *
+ *   - **Current branch**: defer to `pullCurrentBranch` (standard
+ *     `git pull --ff-only`).
+ *   - **Non-current branch**: use the refspec form
+ *     `git fetch <remote> <branch>:<branch>` which advances the local
+ *     ref to match the remote ref ONLY if the update is fast-forward.
+ *     Returns non-zero on non-FF without touching the working tree.
+ *     Diverged branches need a checkout + `pull --rebase` from the
+ *     user; we refuse rather than try to do that for them.
+ *
+ * `currentBranchName` lets the dispatcher compare without re-querying
+ * git — it already has the value in `context.branches.currentBranch`.
+ */
+function pullBranch(git, branch, currentBranchName) {
+    if (branch.type !== 'local') {
+        return Promise.resolve({
+            ok: false,
+            message: 'Only local branches can be pulled.',
+        });
+    }
+    if (!branch.upstream || !branch.remote) {
+        return Promise.resolve({
+            ok: false,
+            message: `${branch.shortName} has no upstream — nothing to pull.`,
+        });
+    }
+    // Current branch — defer to the in-place workflow.
+    if (branch.shortName === currentBranchName) {
+        return pullCurrentBranch(git);
+    }
+    // Non-current branch — refspec-based fast-forward refusing non-FF.
+    // `branch.upstream` is `<remote>/<ref>`; strip the remote prefix to
+    // get the upstream ref name to fetch.
+    const upstreamRef = branch.upstream.startsWith(`${branch.remote}/`)
+        ? branch.upstream.slice(branch.remote.length + 1)
+        : branch.upstream;
+    return runAction$5(() => git.raw([
+        'fetch',
+        branch.remote,
+        `${upstreamRef}:${branch.shortName}`,
+    ]), `Fast-forwarded ${branch.shortName} to ${branch.upstream}`);
+}
 
 async function runAction$4(action, successMessage) {
     try {
@@ -28513,29 +29247,81 @@ function formatBranchDivergence(branch, options = {}) {
         parts.push(`↓${branch.behind}`);
     return `${parts.join(' ')} ${branch.upstream}`;
 }
-/**
- * Single-cell marker shown to the left of a branch name in lists.
- *
- * - `*` — current branch (regardless of remote state)
- * - `◌` — no upstream
- * - `≡` — has upstream + synced (ahead === 0 && behind === 0)
- * - `↕` — has upstream + diverged (any non-zero ahead/behind)
- * - ` ` — fallback / no info
- *
- * ASCII fallbacks (legible without box-drawing/arrow glyphs):
- * - `?` for "no upstream", `=` for synced, `~` for diverged.
- */
+function formatUpstreamAheadBanner(branch, options = {}) {
+    if (!branch?.upstream || branch.behind <= 0) {
+        return undefined;
+    }
+    const sep = options.ascii ? '.' : '·';
+    if (branch.ahead > 0) {
+        // Diverged — local has work too, fast-forward pull is impossible.
+        // Suggest pull --rebase as the cleaner-history default; users who
+        // prefer merge can do that themselves.
+        const symbols = options.ascii
+            ? `+${branch.ahead} -${branch.behind}`
+            : `↑${branch.ahead} ↓${branch.behind}`;
+        return `${symbols} diverged from ${branch.upstream} ${sep} F fetch ${sep} U pull --rebase`;
+    }
+    // Behind-only — fast-forward pull works.
+    const arrow = options.ascii ? 'v' : '↓';
+    const noun = branch.behind === 1 ? 'commit' : 'commits';
+    return `${arrow} ${branch.behind} ${noun} behind ${branch.upstream} ${sep} F fetch ${sep} U pull`;
+}
 function branchRowMarker(branch, options = {}) {
-    if (branch.current)
-        return '*';
-    if (!branch.upstream)
-        return options.ascii ? '?' : '◌';
+    if (branch.current) {
+        return { glyph: '*', kind: 'head' };
+    }
+    if (!branch.upstream) {
+        return { glyph: options.ascii ? '?' : '◌', kind: 'no-upstream' };
+    }
     const ahead = branch.ahead ?? 0;
     const behind = branch.behind ?? 0;
     if (ahead === 0 && behind === 0) {
-        return options.ascii ? '=' : '≡';
+        return { glyph: options.ascii ? '=' : '≡', kind: 'synced' };
+    }
+    if (ahead > 0 && behind > 0) {
+        return { glyph: options.ascii ? '~' : '⇅', kind: 'diverged' };
+    }
+    if (behind > 0) {
+        return { glyph: options.ascii ? 'v' : '↓', kind: 'behind' };
+    }
+    // ahead > 0 (the only remaining case after the guards above)
+    return { glyph: options.ascii ? '^' : '↑', kind: 'ahead' };
+}
+/**
+ * Theme-aware colour picker for a `BranchRowMarker.kind`.
+ *
+ * Reuses the existing chip / banner colour semantic so the workstation
+ * speaks one visual language across history (chips, "behind upstream"
+ * banner) and the branches list:
+ *
+ *   - `head`        → success green (matches HEAD chip)
+ *   - `behind`      → warning yellow (matches "behind upstream" banner)
+ *   - `diverged`    → warning yellow (same: action needed inbound)
+ *   - `ahead`       → info blue (you have work to push)
+ *   - `synced`      → undefined (neutral; inherit row's existing dim)
+ *   - `no-upstream` → undefined (neutral; same)
+ *
+ * Returns `undefined` under `noColor` / `ascii` for the muted cases so
+ * the row renderer skips the colour wrap entirely; the glyph alone
+ * carries the meaning.
+ */
+function getBranchRowMarkerColor(kind, theme) {
+    if (theme.noColor)
+        return undefined;
+    switch (kind) {
+        case 'head':
+            return theme.colors.success;
+        case 'behind':
+        case 'diverged':
+            return theme.colors.warning;
+        case 'ahead':
+            return theme.colors.info;
+        case 'synced':
+        case 'no-upstream':
+            return undefined;
+        default:
+            return undefined;
     }
-    return options.ascii ? '~' : '↕';
 }
 /**
  * Compact, human-friendly relative timestamp for the branch row.
@@ -28823,7 +29609,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
@@ -29137,7 +29929,7 @@ function renderActiveSidebarContent(h, Text, tab, state, context, contextStatus,
         ];
         return [
             ...headerRows,
-            ...renderSelectableSidebarRows(h, Text, sortedBranches, state.selectedBranchIndex, focused, width, theme, (branch) => `${branchRowMarker(branch, { ascii: theme.ascii })} ${branch.shortName}`, 'tab-branches', visibleListCount),
+            ...renderSelectableSidebarRows(h, Text, sortedBranches, state.selectedBranchIndex, focused, width, theme, (branch) => `${branchRowMarker(branch, { ascii: theme.ascii }).glyph} ${branch.shortName}`, 'tab-branches', visibleListCount),
         ];
     }
     if (tab === 'tags') {
@@ -29600,21 +30392,22 @@ function renderBranchesSurface(h, components, state, context, contextStatus, bod
                 const isSelected = index === selected;
                 const cursor = isSelected ? '>' : ' ';
                 const marker = branchRowMarker(branch, { ascii: theme.ascii });
+                const markerColor = getBranchRowMarkerColor(marker.kind, theme);
                 const divergence = formatBranchDivergence(branch, { ascii: theme.ascii });
                 const lastTouched = formatBranchLastTouched(branch.date, new Date());
                 // Split the row into spans so the timestamp stays dim even on the
-                // currently-selected (bold) row. The leading marker + name keep
-                // their per-window-derived column widths; the timestamp is
-                // right-padded so the divergence column stays aligned across rows.
+                // currently-selected (bold) row, and the sync-state marker keeps
+                // its own colour even when the surrounding row text is dimmed.
                 const namePadded = truncateCells(branch.shortName, nameColWidth).padEnd(nameColWidth);
                 const timestampPadded = lastTouched.padEnd(8);
                 const lineDim = !isSelected && !branch.current;
-                const head = `${cursor} ${marker} ${namePadded} `;
+                const cursorAndPad = `${cursor} `;
+                const trailingName = ` ${namePadded} `;
                 const trailingDivergence = divergence ? ` ${divergence}` : '';
                 // Truncate the assembled line to the actual panel width so a
                 // narrow inspector / sidebar focus doesn't push branch rows
                 // onto a second visual line (#830).
-                const fullText = `${head}${timestampPadded}${trailingDivergence}`;
+                const fullText = `${cursorAndPad}${marker.glyph}${trailingName}${timestampPadded}${trailingDivergence}`;
                 const truncated = truncateCells(fullText, Math.max(20, width - 4));
                 // If truncation chopped into the timestamp/divergence portion,
                 // fall back to a single Text to keep the visible width honest.
@@ -29629,7 +30422,15 @@ function renderBranchesSurface(h, components, state, context, contextStatus, bod
                     key: `branch-${index}`,
                     bold: isSelected,
                     dimColor: lineDim,
-                }, head, h(Text, { dimColor: true }, timestampPadded), trailingDivergence);
+                }, cursorAndPad, 
+                // The marker carries the sync-state colour; an explicit
+                // `dimColor: false` on this span keeps the colour bright even
+                // when the surrounding row is dim (other branches in the list
+                // dim out under the existing `lineDim` rule). The synced /
+                // no-upstream kinds return undefined from
+                // `getBranchRowMarkerColor`, so those markers inherit the
+                // row's dim and read as quiet chrome.
+                h(Text, { color: markerColor, dimColor: markerColor ? false : undefined }, marker.glyph), trailingName, h(Text, { dimColor: true }, timestampPadded), trailingDivergence);
             });
     return h(Box, {
         borderColor: focusBorderColor(theme, focused),
@@ -30471,30 +31272,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;
@@ -31257,8 +32080,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);
@@ -31279,7 +32106,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,
@@ -31369,7 +32212,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
@@ -31386,7 +32229,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;
@@ -31448,7 +32291,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;
@@ -31459,7 +32302,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));
@@ -31534,6 +32377,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.
@@ -31588,6 +32442,25 @@ function renderHistoryPanel(h, components, state, context, bodyRows, width, them
         paddingX: 1,
         width,
     }, h(Box, { justifyContent: 'space-between' }, h(Text, { bold: true }, panelTitle('Commits', focused)), h(Text, { dimColor: true }, `${title} | ${graphMode} | ${loadState}`)), 
+    // Upstream-ahead banner. Surfaces "the remote has work you don't"
+    // for the current branch — distinct from the chip work in 0.52.0
+    // which colours remote refs IN the row set. On a behind branch the
+    // upstream commits aren't reachable from local HEAD, so the chips
+    // alone can't signal "fetch / pull needed." This single line does.
+    //
+    // Two wording variants (behind-only vs diverged) live in the
+    // helper; render is identical aside from the formatted string.
+    // Warning yellow = same semantic as the remote-tracking chip kind.
+    ...((() => {
+        const currentBranchRef = context.branches?.localBranches.find((branch) => branch.current);
+        const banner = formatUpstreamAheadBanner(currentBranchRef, { ascii: theme.ascii });
+        if (!banner)
+            return [];
+        return [h(Text, {
+                key: 'upstream-ahead-banner',
+                color: theme.noColor ? undefined : theme.colors.warning,
+            }, banner)];
+    })()), 
     // Server-side filter indicator (#776). Only rendered when the user
     // has an active path:/author: prefix; clears when they Ctrl+U.
     ...(state.historyFetchArgs
@@ -31642,9 +32515,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);
         }));
 }
 
@@ -31800,20 +32673,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,
@@ -34549,7 +35440,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();
@@ -34580,16 +35471,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);
@@ -35109,9 +36082,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;
@@ -36151,16 +37141,20 @@ function LogInkApp(deps) {
             return;
         }
         // Success — close the overlay, reset compose (the staged set is
-        // now empty since the plan committed everything), and pop the
-        // compose view so the user lands on whatever was beneath (usually
-        // status, sometimes history).
+        // now empty since the plan committed everything), and route the
+        // user to the history view so they see the just-landed commits
+        // with the recent-commit marker firing on each row that was
+        // created. Previous behavior popped compose to whatever was
+        // beneath (often status — which now reads "clean worktree" and
+        // gives the user no signal that anything just happened);
+        // history is the natural follow-on surface.
+        //
+        // navigateHome nukes the rest of the stack so `<` after apply
+        // doesn't walk back into the now-empty compose / status state
+        // the user just left behind.
         dispatch({ type: 'clearSplitPlan' });
         dispatch({ type: 'commitCompose', action: { type: 'reset' } });
-        // Only pop if compose is on top — the apply could have been
-        // invoked from a deeper stack and we don't want to over-pop.
-        if (state.activeView === 'compose' && state.viewStack.length > 1) {
-            dispatch({ type: 'popView' });
-        }
+        dispatch({ type: 'navigateHome' });
         // Refresh BEFORE setting the final status so we can peek at the
         // post-apply worktree state and craft a directive next-step hint
         // ("X unstaged + Y untracked remaining — press gs to stage / I
@@ -36210,7 +37204,7 @@ function LogInkApp(deps) {
         }
         const successMessage = formatSplitApplySuccess(commitHashes.length, unstaged, untracked);
         dispatch({ type: 'setStatus', value: successMessage, kind: 'success' });
-    }, [dispatch, git, refreshContext, refreshHistoryRows, refreshWorktreeContext, state.activeView, state.splitPlan, state.viewStack.length]);
+    }, [dispatch, git, refreshContext, refreshHistoryRows, refreshWorktreeContext, state.splitPlan]);
     // Esc inside the overlay — close without applying. Status line gets
     // a confirmation so the user knows the operation was abandoned.
     const cancelCommitSplit = React.useCallback(() => {
@@ -36717,6 +37711,41 @@ function LogInkApp(deps) {
             'fetch-remotes': async () => fetchRemotes(git),
             'pull-current-branch': async () => pullCurrentBranch(git),
             'push-current-branch': async () => pushCurrentBranch(git),
+            // Per-branch fetch / pull / push that operate on the cursored
+            // row in the branches sidebar. inkInput.ts dispatches these
+            // when F / U / P fire from the sidebar; the *-current-branch
+            // / fetch-remotes variants above still handle the same keys
+            // from any other context.
+            'fetch-selected-branch': async () => {
+                const all = sortBranches(context.branches?.localBranches || [], state.branchSort);
+                const visible = state.filter
+                    ? all.filter((b) => matchesPromotedFilter([b.shortName, b.upstream || ''], state.filter))
+                    : all;
+                const branch = visible[Math.min(state.selectedBranchIndex, visible.length - 1)];
+                if (!branch)
+                    return { ok: false, message: 'No branch selected' };
+                return fetchBranch(git, branch);
+            },
+            'pull-selected-branch': async () => {
+                const all = sortBranches(context.branches?.localBranches || [], state.branchSort);
+                const visible = state.filter
+                    ? all.filter((b) => matchesPromotedFilter([b.shortName, b.upstream || ''], state.filter))
+                    : all;
+                const branch = visible[Math.min(state.selectedBranchIndex, visible.length - 1)];
+                if (!branch)
+                    return { ok: false, message: 'No branch selected' };
+                return pullBranch(git, branch, context.branches?.currentBranch);
+            },
+            'push-selected-branch': async () => {
+                const all = sortBranches(context.branches?.localBranches || [], state.branchSort);
+                const visible = state.filter
+                    ? all.filter((b) => matchesPromotedFilter([b.shortName, b.upstream || ''], state.filter))
+                    : all;
+                const branch = visible[Math.min(state.selectedBranchIndex, visible.length - 1)];
+                if (!branch)
+                    return { ok: false, message: 'No branch selected' };
+                return pushBranch(git, branch);
+            },
             'rename-branch': async () => {
                 const newName = payload?.trim();
                 if (!newName)
@@ -37526,6 +38555,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: (() => {
@@ -38274,6 +39334,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
@@ -38289,6 +39370,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