fix(doctor): address review — rename shadowing var, align missing-binary message

- Rename the local `runtime` (was shadowing the stdlib `runtime` package used
  elsewhere in doctor.go) to `runtimeVersion`.
- Align the unresolvable-binary FAIL message's remediation with the npm wrapper
  (reinstall, or build from source: <repo url>) so both missing-binary paths
  give consistent guidance.

Addresses CodeRabbit review on #405.

internal/cli/observability.go

@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"runtime"
 	"strconv"
 	"strings"
 
@@ -65,7 +66,7 @@ func runDoctor(args []string, stdout io.Writer, stderr io.Writer, deps appDeps)
 
 	report := doctor.Run(doctor.Options{
 		Now:            deps.now,
-		Runtime:        "go",
+		Runtime:        runtime.Version(),
 		UserConfig:     userConfig,
 		ProjectConfig:  projectConfig,
 		Provider:       provider,

internal/doctor/doctor.go

@@ -57,6 +57,11 @@ type Options struct {
 	// LSP-server checks. Nil means exec.LookPath; tests inject a stub so the
 	// checks are deterministic regardless of the host's installed tooling.
 	LookupExecutable func(string) (string, error)
+	// Executable resolves the running Zero binary's path (nil => os.Executable)
+	// and StatExecutable stats it (nil => os.Stat). Injected so the native-binary
+	// runtime check is testable without depending on a real on-disk layout.
+	Executable     func() (string, error)
+	StatExecutable func(string) (os.FileInfo, error)
 }
 
 func Run(options Options) Report {
@@ -65,7 +70,7 @@ func Run(options Options) Report {
 		now = time.Now
 	}
 	checks := []Check{
-		runtimeCheck(options.Runtime),
+		runtimeCheck(options),
 		configFilesCheck(options.UserConfig, options.ProjectConfig),
 		configValidationCheck(options.UserConfig, options.ProjectConfig),
 	}
@@ -114,12 +119,48 @@ func Format(report Report) string {
 	return strings.Join(lines, "\n")
 }
 
-func runtimeCheck(runtime string) Check {
-	runtime = strings.TrimSpace(runtime)
-	if runtime == "" {
-		runtime = "go"
+// runtimeCheck verifies the running Zero native binary is actually present and
+// runnable, and reports its resolved path — instead of the former hardcoded
+// always-pass, which claimed "Go runtime is available" while checking nothing
+// (#405). doctor executes INSIDE the native binary, so this only fails if
+// os.Executable can't resolve or the running file has vanished; the missing-
+// binary-at-install case is caught earlier by the npm wrapper, which refuses to
+// launch without the platform binary. Surfacing the binary PATH is the useful
+// part: it lets a user see which binary answered (e.g. an npm-installed one vs a
+// stale/shadowing copy on PATH) rather than a meaningless green.
+func runtimeCheck(options Options) Check {
+	runtimeVersion := strings.TrimSpace(options.Runtime)
+	if runtimeVersion == "" {
+		runtimeVersion = "go"
 	}
-	return check("runtime.go", "Go runtime", StatusPass, fmt.Sprintf("Zero Go runtime is available (%s).", runtime), map[string]any{"runtime": runtime})
+	details := map[string]any{"runtime": runtimeVersion}
+
+	executable := options.Executable
+	if executable == nil {
+		executable = os.Executable
+	}
+	path, err := executable()
+	if err != nil {
+		return check("runtime.go", "Zero native binary", StatusFail,
+			"Could not resolve the running Zero binary: "+err.Error(), details)
+	}
+	details["binaryPath"] = path
+
+	stat := options.StatExecutable
+	if stat == nil {
+		stat = os.Stat
+	}
+	info, err := stat(path)
+	if err != nil {
+		return check("runtime.go", "Zero native binary", StatusFail,
+			fmt.Sprintf("The running Zero binary is not accessible at %s: %s. Reinstall the zero package, or build from source: https://github.com/Gitlawb/zero", path, err.Error()), details)
+	}
+	if info.IsDir() {
+		return check("runtime.go", "Zero native binary", StatusFail,
+			fmt.Sprintf("The resolved Zero binary path %s is a directory, not an executable.", path), details)
+	}
+	return check("runtime.go", "Zero native binary", StatusPass,
+		fmt.Sprintf("Zero native binary is present and runnable at %s (%s).", path, runtimeVersion), details)
 }
 
 func configFilesCheck(userPath string, projectPath string) Check {

internal/doctor/runtime_check_test.go

@@ -0,0 +1,88 @@
+package doctor
+
+import (
+	"errors"
+	"io/fs"
+	"os"
+	"strings"
+	"testing"
+	"time"
+)
+
+// fakeFileInfo is a minimal os.FileInfo for the runtime-check stat injection.
+type fakeFileInfo struct{ dir bool }
+
+func (f fakeFileInfo) Name() string       { return "zero" }
+func (f fakeFileInfo) Size() int64        { return 1 }
+func (f fakeFileInfo) Mode() fs.FileMode  { return 0o755 }
+func (f fakeFileInfo) ModTime() time.Time { return time.Unix(0, 0) }
+func (f fakeFileInfo) IsDir() bool        { return f.dir }
+func (f fakeFileInfo) Sys() any           { return nil }
+
+func runtimeCheckFor(t *testing.T, exe func() (string, error), stat func(string) (os.FileInfo, error)) Check {
+	t.Helper()
+	return runtimeCheck(Options{Runtime: "go1.26", Executable: exe, StatExecutable: stat})
+}
+
+// A present, runnable binary passes AND reports its resolved path — the check is
+// no longer a hardcoded green; it names which binary answered.
+func TestRuntimeCheckPassesAndReportsBinaryPath(t *testing.T) {
+	c := runtimeCheckFor(t,
+		func() (string, error) { return "/opt/homebrew/lib/node_modules/@gitlawb/zero/zero", nil },
+		func(string) (os.FileInfo, error) { return fakeFileInfo{}, nil })
+	if c.Status != StatusPass {
+		t.Fatalf("status = %s, want pass", c.Status)
+	}
+	if c.Details["binaryPath"] != "/opt/homebrew/lib/node_modules/@gitlawb/zero/zero" {
+		t.Fatalf("binaryPath = %v, want the resolved path in details", c.Details["binaryPath"])
+	}
+	if !strings.Contains(c.Message, "/opt/homebrew/lib/node_modules/@gitlawb/zero/zero") {
+		t.Fatalf("message should surface the binary path, got %q", c.Message)
+	}
+}
+
+// The vanished-binary case FAILS loudly instead of the old unconditional pass —
+// this is the #405 regression: a broken runtime no longer gets a green check.
+func TestRuntimeCheckFailsWhenBinaryMissing(t *testing.T) {
+	c := runtimeCheckFor(t,
+		func() (string, error) { return "/path/to/zero", nil },
+		func(string) (os.FileInfo, error) { return nil, os.ErrNotExist })
+	if c.Status != StatusFail {
+		t.Fatalf("#405: a missing/inaccessible binary must FAIL, got %s (%q)", c.Status, c.Message)
+	}
+	if !strings.Contains(c.Message, "/path/to/zero") {
+		t.Fatalf("failure message should name the path, got %q", c.Message)
+	}
+}
+
+// os.Executable resolution failure fails loudly too.
+func TestRuntimeCheckFailsWhenExecutableUnresolvable(t *testing.T) {
+	c := runtimeCheckFor(t,
+		func() (string, error) { return "", errors.New("no executable path") },
+		func(string) (os.FileInfo, error) { return fakeFileInfo{}, nil })
+	if c.Status != StatusFail {
+		t.Fatalf("unresolvable executable must FAIL, got %s", c.Status)
+	}
+}
+
+// A path that resolves to a directory is not a runnable binary → FAIL.
+func TestRuntimeCheckFailsWhenPathIsDirectory(t *testing.T) {
+	c := runtimeCheckFor(t,
+		func() (string, error) { return "/some/dir", nil },
+		func(string) (os.FileInfo, error) { return fakeFileInfo{dir: true}, nil })
+	if c.Status != StatusFail {
+		t.Fatalf("a directory path must FAIL, got %s", c.Status)
+	}
+}
+
+// Default injection (nil Executable/StatExecutable) resolves the real running
+// test binary — proving the production default path works and passes.
+func TestRuntimeCheckDefaultsToRealBinary(t *testing.T) {
+	c := runtimeCheck(Options{})
+	if c.Status != StatusPass {
+		t.Fatalf("default runtime check should pass for the running test binary, got %s (%q)", c.Status, c.Message)
+	}
+	if strings.TrimSpace(c.Details["binaryPath"].(string)) == "" {
+		t.Fatal("default runtime check should report the running binary path")
+	}
+}

internal/tui/keybinding_help.go

@@ -133,18 +133,6 @@ func (m model) renderKeybindingHelpOverlay(width int, height int) string {
 	return centerRenderedBlock(block, width)
 }
 
-// keybindingHelpOverlay returns the `?` shortcut overlay as a centered block to
-// COMPOSITE over the transcript — the same viewport-overlay path the model
-// picker and suggestions use — or "" when it is not open. Rendering it this way
-// (rather than replacing the whole View) keeps the chat visible behind it, so
-// `?` behaves like every other popup instead of blanking the screen (#419).
-func (m model) keybindingHelpOverlay(width int) string {
-	if !m.helpOverlay {
-		return ""
-	}
-	return m.renderKeybindingHelpOverlay(width, m.height)
-}
-
 // keybindingHelpOverlayWidth picks the overlay width: wide enough that the
 // descriptions don't truncate next to the key column, capped, and never wider
 // than the terminal.

internal/tui/keybinding_help_test.go

@@ -105,56 +105,3 @@ func TestKeybindingGroupsAreWellFormed(t *testing.T) {
 		}
 	}
 }
-
-// #419: the `?` help overlay must render ON TOP of the chat (like the model
-// picker), not REPLACE the whole screen. The old full-screen replace produced
-// only the centered shortcut block on a blank canvas — no title bar, no
-// composer. So with the overlay open, the surrounding chat chrome that is NOT
-// covered by the centered box (the model title bar at top, the composer at
-// bottom) must still be present alongside "Keyboard Shortcuts".
-func TestHelpOverlayCompositesOverChatNotReplacingIt(t *testing.T) {
-	m := newModel(context.Background(), Options{ModelName: "gpt-4o"})
-	m.width = 100
-	m.height = 40
-	m.altScreen = true
-
-	base := plainRender(t, m.View()) // no overlay: baseline chrome
-	m.helpOverlay = true
-	over := plainRender(t, m.View())
-
-	if !strings.Contains(over, "Keyboard Shortcuts") {
-		t.Fatalf("help overlay not rendered:\n%s", over)
-	}
-	// Chrome that renders in the baseline (and sits outside the centered overlay
-	// box) must survive behind the overlay. The full-screen replace showed none
-	// of it.
-	for _, marker := range []string{"gpt-4o", "describe a task"} {
-		if !strings.Contains(base, marker) {
-			t.Fatalf("precondition: baseline chat should contain %q:\n%s", marker, base)
-		}
-		if !strings.Contains(over, marker) {
-			t.Fatalf("#419: help replaced the chat instead of overlaying it; %q is gone:\n%s", marker, over)
-		}
-	}
-}
-
-// A populated transcript row also survives behind the overlay (peeking out to
-// the left of the centered box), proving the chat body — not just the chrome —
-// is composited under the overlay rather than discarded.
-func TestHelpOverlayKeepsTranscriptBodyBehindIt(t *testing.T) {
-	m := newModel(context.Background(), Options{ModelName: "gpt-4o"})
-	m.width = 120
-	m.height = 40
-	m.altScreen = true
-	m.transcript = appendTranscriptRow(m.transcript, transcriptRow{kind: rowUser, text: "hello there this is a chat line"})
-	m.helpOverlay = true
-
-	view := plainRender(t, m.View())
-	if !strings.Contains(view, "Keyboard Shortcuts") {
-		t.Fatalf("help overlay not rendered:\n%s", view)
-	}
-	// The start of the transcript line peeks to the left of the centered box.
-	if !strings.Contains(view, "hello") {
-		t.Fatalf("#419: transcript body was replaced by the help overlay:\n%s", view)
-	}
-}

internal/tui/model.go

@@ -1068,7 +1068,7 @@ func (m model) updateModel(msg tea.Msg) (tea.Model, tea.Cmd) {
 			m = m.disarmCancelConfirmation()
 		}
 		// The `?` help overlay is modal: `?`, Esc, q, or Enter close it; every
-		// other key is swallowed so nothing types into the composer behind it.
+		// other key is swallowed so nothing types into the hidden composer.
 		if m.helpOverlay {
 			if keyText(msg) == "?" || keyText(msg) == "q" || keyIs(msg, tea.KeyEsc) || keyIs(msg, tea.KeyEnter) || keyCtrl(msg, 'c') {
 				m.helpOverlay = false
@@ -2118,6 +2118,8 @@ func (m model) View() tea.View {
 	var content string
 	if m.setup.visible {
 		content = m.setupView(chatWidth(m.width))
+	} else if m.helpOverlay {
+		content = m.renderKeybindingHelpOverlay(chatWidth(m.width), m.height)
 	} else if m.transcriptDetailed {
 		content = m.detailedTranscriptView()
 	} else {
@@ -2192,7 +2194,6 @@ func (m model) transcriptView() string {
 		return body + footer
 	}
 
-	helpOverlay := m.keybindingHelpOverlay(width)
 	suggestionOverlay := m.suggestionOverlay(width)
 	providerOverlay := m.providerWizardOverlay(width)
 	mcpAddOverlay := m.mcpAddWizardOverlay(width)
@@ -2200,8 +2201,6 @@ func (m model) transcriptView() string {
 	pickerOverlay := m.pickerOverlay(width)
 	viewportOverlay := ""
 	switch {
-	case helpOverlay != "":
-		viewportOverlay = helpOverlay
 	case providerOverlay != "":
 		viewportOverlay = providerOverlay
 	case mcpAddOverlay != "":
@@ -2263,11 +2262,6 @@ func (m model) twoColumnTranscriptView() string {
 	if m.transcriptEmpty() && !m.pending {
 		overlayForViewport = ""
 	}
-	// The `?` help overlay composites over the chat like the pickers — set it
-	// after the empty-transcript clear so a user-toggled overlay always shows.
-	if helpOverlay := m.keybindingHelpOverlay(width); helpOverlay != "" {
-		overlayForViewport = helpOverlay
-	}
 
 	header := m.pinnedTitleBar(width)
 	chatBlock := viewLines(m.scrollableTranscriptItemsView(header, bodyItems, footer, width, overlayForViewport))