@kal-elsam/kairo-runtime 0.3.0 → 0.4.0

package/README.md

@@ -35,18 +35,22 @@ kairo
 **First run** (no `~/.harness/state.json`): interactive onboarding → safe diagnosis →
 setup with confirmation → full-screen operations cockpit.
 
-**Later runs** (state present): full-screen cockpit with mission control (recommended
-action), navigation, and a system strip. Layout adapts to terminal size:
+**Later runs** (state present): full-screen cockpit Home that explains what Kairo
+does, shows real readiness, and recommends a useful next action. Layout adapts to
+terminal size:
 
 | Mode | Size | Layout |
 |------|------|--------|
-| Wide | ≥100 cols × ≥28 rows | Nav + content + system |
-| Compact | ≥72×20 | Nav + content |
-| Minimal | 60–71 cols or short height | Single panel + nav header |
+| Wide | ≥100 cols × ≥28 rows | Nav + Home/content + system |
+| Compact | ≥72×20 | Nav + Home/content (readiness embedded) |
+| Minimal | 60–71 cols or short height | Selected section + essential readiness/next/recent |
 | Below gate | <60 cols | Explicit TTY fallback (Ink disabled) |
 
-Keys: `↑↓` navigate · `Tab` region · `Enter` open · `R` refresh · `C` cancel run ·
-`?` help · `Esc` back (exit only from Home).
+Keys: `↑↓` navigate (selection explanation updates) · `Enter` open ·
+`Esc` back (exit only from Home) · `R` refresh/retry · `C` cancel run · `?` help.
+`Tab` switches region only when content is interactive (run lists / New run).
+
+Navigation labels: Home · Running now · History · Agents · New run · System health.
 
 Respects `NO_COLOR`, `HARNESS_ASCII=1`, and `HARNESS_INK=0`. Status is always labeled
 in text, never color alone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Kairo Runtime — local agent operating system for Codex, Cursor, Claude, Gemini, Copilot, Engram, and Graphify.",
   "type": "module",
   "homepage": "https://github.com/Kal-elSam/harness#readme",

package/scripts/check-published-release.mjs

@@ -113,8 +113,11 @@ export async function verifyPublishedRelease({
   }
 
   const remoteTagLine = runGit(`git ls-remote --tags origin refs/tags/${releaseTag}`).trim();
+  const remotePeeledLine = runGit(`git ls-remote origin refs/tags/${releaseTag}^{}`).trim();
+  const remotePointsAtGitHead = remoteTagLine.startsWith(gitHead)
+    || remotePeeledLine.startsWith(gitHead);
 
-  if (!remoteTagLine.startsWith(gitHead)) {
+  if (!remotePointsAtGitHead) {
     throw new Error(
       `Remote tag ${releaseTag} on origin does not point to npm gitHead (${gitHead})`
     );

package/scripts/cockpit-smoke-test.sh

@@ -14,6 +14,8 @@ node --test \
   test/terminal-capabilities.test.js \
   test/cockpit-models.test.js \
   test/cockpit-controller.test.js \
-  test/cockpit-frame.test.js
+  test/cockpit-frame.test.js \
+  test/cockpit-navigation.test.js \
+  test/cockpit-input-integration.test.js
 
 echo "Kairo cockpit smoke passed"

package/scripts/cockpit-smoke.mjs

@@ -6,13 +6,26 @@ import { fileURLToPath } from "node:url";
 import { resolveLayoutMode, LAYOUT_MODES } from "../src/global/ink/layout.js";
 import { resolveTerminalCapabilities } from "../src/global/ink/terminal-capabilities.js";
 import { createFullscreenSession } from "../src/global/ink/fullscreen-session.js";
-import { buildTopBarModel, buildHomeMissionModel } from "../src/global/ink/cockpit-models.js";
+import {
+  buildFooterModel,
+  buildHomeMissionModel,
+  buildNavModel,
+  buildTopBarModel,
+  COCKPIT_NAV,
+  COCKPIT_REGIONS
+} from "../src/global/ink/cockpit-models.js";
+import {
+  createCockpitUiState,
+  reduceCockpitUi,
+  routeCockpitKey
+} from "../src/global/ink/cockpit-controller.js";
+import { ORCHESTRATOR_VIEWS } from "../src/global/ink/orchestrator-state.js";
 
 const root = join(dirname(fileURLToPath(import.meta.url)), "..");
 const require = createRequire(import.meta.url);
 const pkg = require(join(root, "package.json"));
 
-assert.equal(pkg.version, "0.3.0");
+assert.equal(pkg.version, "0.4.0");
 assert.ok(pkg.dependencies["ansi-escapes"]);
 
 assert.equal(resolveLayoutMode({ columns: 120, rows: 40 }), LAYOUT_MODES.WIDE);
@@ -39,13 +52,78 @@ assert.equal(session.enter(), true);
 assert.equal(session.leave(), true);
 assert.equal(session.leave(), false);
 
-const top = buildTopBarModel({ projectName: "smoke" });
+const top = buildTopBarModel({ projectName: "smoke", unicode: false });
 assert.match(top.status, /ONLINE|Offline/);
 const mission = buildHomeMissionModel({
-  hasGlobalState: false,
-  diagnostics: { diagnostics: { detected: 0 } },
-  dashboard: { providers: [], recentRuns: [] }
+  projectName: "smoke",
+  hasGlobalState: true,
+  diagnostics: {
+    diagnostics: { detected: 2, errors: 0 },
+    intelligence: { summary: { localAvailable: false, cloudAuthenticated: false } },
+    recommendations: []
+  },
+  dashboard: {
+    providers: [{ launchable: true }],
+    recentRuns: [{ runId: "r1", agentId: "codex", state: "failed" }]
+  },
+  layoutMode: LAYOUT_MODES.MINIMAL
 });
-assert.match(mission.title, /MISSION CONTROL/);
+assert.match(mission.title, /HOME — smoke/);
+assert.match(mission.readiness.headline, /LIMITED|READY|NEEDS/i);
+assert.equal(mission.next.targetAction, "launch");
+assert.match(mission.recent.headline, /Codex · Failed/);
+
+const asciiNav = buildNavModel({
+  navIndex: 1,
+  currentView: ORCHESTRATOR_VIEWS.HOME,
+  focused: true,
+  unicode: false,
+  dashboard: { activeRuns: [], recentRuns: [], providers: [{ launchable: true }] },
+  diagnostics: { diagnostics: { detected: 1, errors: 0 } }
+});
+assert.equal(asciiNav.items[1].marker, ">");
+assert.equal(asciiNav.items[0].current, true);
+assert.equal(asciiNav.items[1].selected, true);
+assert.match(asciiNav.explanation, /Supervised runs|Running/i);
+
+function applyKey(state, keyAction) {
+  const routed = routeCockpitKey(state, keyAction);
+  if (!routed) return state;
+  return reduceCockpitUi(state, routed);
+}
+
+function smokeNavigation(layoutMode) {
+  let state = createCockpitUiState({
+    layoutMode,
+    region: layoutMode === LAYOUT_MODES.MINIMAL ? COCKPIT_REGIONS.CONTENT : COCKPIT_REGIONS.NAV
+  });
+  const diagnosticsIndex = COCKPIT_NAV.findIndex((item) => item.id === "diagnostics");
+  while (state.navIndex < diagnosticsIndex) {
+    state = applyKey(state, { type: "arrow", direction: "down" });
+  }
+  state = applyKey(state, { type: "enter" });
+  assert.equal(state.view, ORCHESTRATOR_VIEWS.DIAGNOSTICS);
+  assert.equal(state.region, COCKPIT_REGIONS.NAV);
+
+  state = applyKey(state, { type: "arrow", direction: "up" });
+  state = applyKey(state, { type: "enter" });
+  assert.equal(state.view, ORCHESTRATOR_VIEWS.LAUNCH);
+  assert.equal(state.region, COCKPIT_REGIONS.CONTENT);
+
+  const footer = buildFooterModel({
+    view: ORCHESTRATOR_VIEWS.DIAGNOSTICS,
+    region: COCKPIT_REGIONS.NAV,
+    unicode: false
+  });
+  assert.doesNotMatch(footer.text, /Tab/);
+
+  state = applyKey(state, { type: "escape" });
+  assert.equal(state.view, ORCHESTRATOR_VIEWS.HOME);
+  state = applyKey(state, { type: "escape" });
+  assert.equal(state.shouldExit, true);
+}
+
+smokeNavigation(LAYOUT_MODES.WIDE);
+smokeNavigation(LAYOUT_MODES.COMPACT);
 
 console.log("cockpit smoke OK");

package/src/cli.js

@@ -743,7 +743,8 @@ Scopes:
 Commands:
   shell      Operations cockpit (TTY). Bare ${cli} opens onboarding when ~/.harness/state.json
              is missing, otherwise the cockpit. Explicit ${cli} shell always opens the cockpit.
-             Keys: ↑↓ · Tab region · Enter · R refresh · C cancel · ? help · Esc back/exit.
+             Keys: ↑↓ · Enter · Esc back/exit · R refresh · C cancel · ? help.
+             Tab switches region only when content is interactive (runs/launch).
   run        Launch a managed agent run with local audit trail.
   runs       List, inspect, or cancel agent runs under ~/.harness/runs/.
   orchestrator  Read-only capability registry diagnostics (--json supported).

package/src/global/dashboard-guidance.js

@@ -1,7 +1,15 @@
 import { formatCliCommand } from "./brand/cli.js";
 
+/** Public cockpit destinations for recommended actions (match ORCHESTRATOR_VIEWS). */
+export const RECOMMENDATION_TARGETS = {
+  DIAGNOSTICS: "diagnostics",
+  LAUNCH: "launch",
+  RECENT_RUNS: "recent-runs",
+  PROVIDERS: "providers"
+};
+
 export const DASHBOARD_PURPOSE =
-  "Detects, configures, and coordinates local AI agents — no changes without confirmation.";
+  "Kairo coordinates installed AI agents for this project, with controlled execution and auditable results.";
 
 export const NEXT_STEP_KINDS = {
   CONFIGURE: "configure",
@@ -10,13 +18,117 @@ export const NEXT_STEP_KINDS = {
   REVIEW: "review"
 };
 
+export const READINESS_KINDS = {
+  NEEDS_SETUP: "needs_setup",
+  NEEDS_ATTENTION: "needs_attention",
+  LIMITED: "limited",
+  READY: "ready"
+};
+
+export const READINESS_LABELS = {
+  [READINESS_KINDS.NEEDS_SETUP]: "Needs setup",
+  [READINESS_KINDS.NEEDS_ATTENTION]: "Needs attention",
+  [READINESS_KINDS.LIMITED]: "Limited",
+  [READINESS_KINDS.READY]: "Ready to work"
+};
+
 export function formatDashboardPurpose() {
   return DASHBOARD_PURPOSE;
 }
 
+export function countLaunchableAgents(dashboard = null) {
+  return (dashboard?.providers ?? []).filter((entry) => entry.launchable).length;
+}
+
+export function hasIntelligenceConfigured(diagnostics = null) {
+  const summary = diagnostics?.intelligence?.summary;
+  return Boolean(summary?.localAvailable || summary?.cloudAuthenticated);
+}
+
+function hasBlockingDiagnostics(diagnostics = null) {
+  const summary = diagnostics?.diagnostics ?? { errors: 0 };
+  const hasErrors = (summary.errors ?? 0) > 0;
+  const hasProblemRecommendation = (diagnostics?.recommendations ?? []).some((line) =>
+    /error|fix|drift|not detected|failed|problem/i.test(line)
+  );
+  return hasErrors || hasProblemRecommendation;
+}
+
+/**
+ * Derive project readiness from diagnostics + dashboard.
+ * Intelligence absence is Limited (optional), never Needs attention by itself.
+ */
+export function resolveProjectReadiness({
+  hasGlobalState = false,
+  diagnostics = null,
+  dashboard = null
+} = {}) {
+  const summary = diagnostics?.diagnostics ?? { detected: 0, errors: 0 };
+  const launchableCount = countLaunchableAgents(dashboard);
+  const detected = summary.detected ?? 0;
+  const agentsReady = launchableCount;
+  const activeRuns = dashboard?.activeRuns?.length ?? 0;
+  const intelConfigured = hasIntelligenceConfigured(diagnostics);
+  const summaryLine = `${agentsReady} agents ready · ${detected} detected · ${activeRuns} active runs`;
+
+  if (!hasGlobalState || detected === 0) {
+    return {
+      kind: READINESS_KINDS.NEEDS_SETUP,
+      label: READINESS_LABELS[READINESS_KINDS.NEEDS_SETUP],
+      headline: "NEEDS SETUP",
+      summaryLine,
+      capabilityLines: [
+        "Intelligence: Optional capability not configured"
+      ],
+      healthKind: "warn"
+    };
+  }
+
+  if (hasBlockingDiagnostics(diagnostics) || launchableCount === 0) {
+    return {
+      kind: READINESS_KINDS.NEEDS_ATTENTION,
+      label: READINESS_LABELS[READINESS_KINDS.NEEDS_ATTENTION],
+      headline: "NEEDS ATTENTION",
+      summaryLine,
+      capabilityLines: [
+        intelConfigured
+          ? "Intelligence: Configured"
+          : "Intelligence: Optional capability not configured"
+      ],
+      healthKind: "error"
+    };
+  }
+
+  if (!intelConfigured) {
+    return {
+      kind: READINESS_KINDS.LIMITED,
+      label: READINESS_LABELS[READINESS_KINDS.LIMITED],
+      headline: "LIMITED",
+      summaryLine,
+      capabilityLines: [
+        "Intelligence: Optional capability not configured"
+      ],
+      healthKind: "warn"
+    };
+  }
+
+  return {
+    kind: READINESS_KINDS.READY,
+    label: READINESS_LABELS[READINESS_KINDS.READY],
+    headline: "READY TO WORK",
+    summaryLine,
+    capabilityLines: [
+      "Intelligence: Configured"
+    ],
+    healthKind: "ready"
+  };
+}
+
 /**
  * Contextual next step from existing diagnostics + dashboard snapshot.
- * Priority: configure → review problems → enable intelligence → launch.
+ * Priority: configure → review when blocked → launch when launchable →
+ * enable intelligence → review.
+ * Launchable agents win over missing optional intelligence.
  */
 export function resolveDashboardRecommendation({
   hasGlobalState = false,
@@ -25,42 +137,59 @@ export function resolveDashboardRecommendation({
 } = {}) {
   const summary = diagnostics?.diagnostics ?? { detected: 0, errors: 0 };
   const intelligence = diagnostics?.intelligence?.summary;
-  const launchableCount = (dashboard?.providers ?? []).filter((entry) => entry.launchable).length;
-  const hasErrors = (summary.errors ?? 0) > 0;
-  const hasProblemRecommendation = (diagnostics?.recommendations ?? []).some((line) =>
-    /error|fix|drift|not detected|failed|problem/i.test(line)
-  );
+  const launchableCount = countLaunchableAgents(dashboard);
+  const blocked = hasBlockingDiagnostics(diagnostics);
 
   if (!hasGlobalState || (summary.detected ?? 0) === 0) {
     return {
       kind: NEXT_STEP_KINDS.CONFIGURE,
-      message: `Configure the local environment with ${formatCliCommand("setup")}.`
+      title: "Finish local setup",
+      message: `Configure the local environment with ${formatCliCommand("setup")}.`,
+      detail: "Open System health to review what Kairo detected.",
+      targetView: RECOMMENDATION_TARGETS.DIAGNOSTICS,
+      targetAction: null
     };
   }
 
-  if (hasErrors || hasProblemRecommendation) {
+  if (blocked && launchableCount === 0) {
     return {
       kind: NEXT_STEP_KINDS.REVIEW,
-      message: "Review diagnostics for problems before launching a run."
+      title: "Review system health",
+      message: "Review System health for problems before launching a run.",
+      detail: "Fix agent or configuration issues, then try again.",
+      targetView: RECOMMENDATION_TARGETS.DIAGNOSTICS,
+      targetAction: null
     };
   }
 
-  if (!intelligence?.localAvailable && !intelligence?.cloudAuthenticated) {
+  if (launchableCount > 0) {
     return {
-      kind: NEXT_STEP_KINDS.ENABLE_INTELLIGENCE,
-      message: "Enable intelligence: start Ollama or set OPENROUTER_API_KEY, then retry."
+      kind: NEXT_STEP_KINDS.LAUNCH,
+      title: "Create a new run",
+      message: "Create a new run",
+      detail: "Delegate a task to Cursor, Codex or Claude.",
+      targetView: RECOMMENDATION_TARGETS.LAUNCH,
+      targetAction: "launch"
     };
   }
 
-  if (launchableCount > 0) {
+  if (!intelligence?.localAvailable && !intelligence?.cloudAuthenticated) {
     return {
-      kind: NEXT_STEP_KINDS.LAUNCH,
-      message: "Launch a supervised run from the menu or with kairo run."
+      kind: NEXT_STEP_KINDS.ENABLE_INTELLIGENCE,
+      title: "Enable optional intelligence",
+      message: "Enable intelligence: start Ollama or set OPENROUTER_API_KEY, then retry.",
+      detail: "Agents can still run without this optional capability.",
+      targetView: RECOMMENDATION_TARGETS.DIAGNOSTICS,
+      targetAction: null
     };
   }
 
   return {
     kind: NEXT_STEP_KINDS.REVIEW,
-    message: "Review diagnostics for problems before launching a run."
+    title: "Review system health",
+    message: "Review System health for problems before launching a run.",
+    detail: "Open System health to inspect agents and configuration.",
+    targetView: RECOMMENDATION_TARGETS.DIAGNOSTICS,
+    targetAction: null
   };
 }

package/src/global/ink/cockpit/primitives.js

@@ -47,17 +47,24 @@ export function CockpitTopBar({ model, colorEnabled = true }) {
 
 export function CockpitNav({ model, colorEnabled = true }) {
   return React.createElement(Box, { flexDirection: "column" },
-    model.items.map((item) =>
-      React.createElement(Text, {
+    model.items.map((item) => {
+      const suffix = item.current && !item.selected ? " (open)" : "";
+      const color = item.focused
+        ? (colorEnabled ? COCKPIT_COLORS.primary : undefined)
+        : item.selected
+          ? (colorEnabled ? COCKPIT_COLORS.secondary : undefined)
+          : item.current
+            ? (colorEnabled ? COCKPIT_COLORS.muted : undefined)
+            : undefined;
+      return React.createElement(Text, {
         key: item.id,
         bold: item.focused || item.selected,
-        color: item.focused
-          ? (colorEnabled ? COCKPIT_COLORS.primary : undefined)
-          : item.selected
-            ? (colorEnabled ? COCKPIT_COLORS.secondary : undefined)
-            : undefined
-      }, `${item.marker} ${item.label}`)
-    )
+        color
+      }, `${item.marker} ${item.label}${suffix}`);
+    }),
+    model.explanation && React.createElement(Text, {
+      color: COCKPIT_COLORS.muted
+    }, model.explanation)
   );
 }
 

package/src/global/ink/cockpit-controller.js

@@ -1,21 +1,43 @@
-import { COCKPIT_NAV, COCKPIT_REGIONS, regionsForLayout } from "./cockpit-models.js";
-import { ORCHESTRATOR_VIEWS } from "./orchestrator-state.js";
-import { LAYOUT_MODES } from "./layout.js";
+import {
+  COCKPIT_NAV,
+  COCKPIT_REGIONS,
+  LAYOUT_MODES,
+  ORCHESTRATOR_VIEWS,
+  canTabBetweenRegions,
+  clamp,
+  defaultRegionForView,
+  interactiveRegionsFor,
+  isContentInteractiveView,
+  isNavFocusedView,
+  regionsForLayout,
+  routeCockpitKey
+} from "./cockpit-focus.js";
+
+export {
+  canTabBetweenRegions,
+  defaultRegionForView,
+  isContentInteractiveView,
+  isNavFocusedView,
+  routeCockpitKey
+};
 
 /**
  * Pure cockpit focus / navigation reducer — no I/O, no React.
  */
-
 export function createCockpitUiState({
   layoutMode = LAYOUT_MODES.COMPACT,
   view = ORCHESTRATOR_VIEWS.HOME,
   region = COCKPIT_REGIONS.NAV,
   navIndex = 0,
   listIndex = 0,
-  helpOpen = false
+  helpOpen = false,
+  returnView = null
 } = {}) {
   const regions = regionsForLayout(layoutMode);
-  const safeRegion = regions.includes(region) ? region : regions[0];
+  const preferred = region ?? defaultRegionForView(view, layoutMode);
+  const safeRegion = regions.includes(preferred)
+    ? preferred
+    : defaultRegionForView(view, layoutMode);
   return {
     layoutMode,
     view,
@@ -23,6 +45,7 @@ export function createCockpitUiState({
     navIndex: clamp(navIndex, 0, COCKPIT_NAV.length - 1),
     listIndex: Math.max(0, listIndex),
     helpOpen,
+    returnView,
     shouldExit: false
   };
 }
@@ -31,21 +54,23 @@ export function reduceCockpitUi(state, action) {
   switch (action.type) {
     case "resize": {
       const regions = regionsForLayout(action.layoutMode);
-      const region = regions.includes(state.region) ? state.region : regions[0];
-      return { ...state, layoutMode: action.layoutMode, region };
+      const preferred = regions.includes(state.region)
+        ? state.region
+        : defaultRegionForView(state.view, action.layoutMode);
+      return { ...state, layoutMode: action.layoutMode, region: preferred };
     }
     case "tab": {
-      const regions = regionsForLayout(state.layoutMode);
-      if (regions.length < 2) return state;
+      if (!canTabBetweenRegions(state)) return state;
+      const regions = interactiveRegionsFor(state);
       const index = regions.indexOf(state.region);
-      const next = regions[(index + 1) % regions.length];
+      const next = regions[(Math.max(index, 0) + 1) % regions.length];
       return { ...state, region: next };
     }
     case "arrow": {
-      if (state.helpOpen) return state;
       if (state.region === COCKPIT_REGIONS.SYSTEM) return state;
 
       const navigatesNav = state.region === COCKPIT_REGIONS.NAV
+        || isNavFocusedView(state.view)
         || (state.view === ORCHESTRATOR_VIEWS.HOME
           && state.layoutMode === LAYOUT_MODES.MINIMAL);
 
@@ -57,6 +82,10 @@ export function reduceCockpitUi(state, action) {
         };
       }
 
+      if (!isContentInteractiveView(state.view) || state.view === ORCHESTRATOR_VIEWS.LAUNCH) {
+        return state;
+      }
+
       const delta = action.direction === "up" ? -1 : 1;
       const max = Math.max(0, (action.listLength ?? 1) - 1);
       return { ...state, listIndex: clamp(state.listIndex + delta, 0, max) };
@@ -64,55 +93,58 @@ export function reduceCockpitUi(state, action) {
     case "enter-nav": {
       const item = COCKPIT_NAV[state.navIndex];
       if (!item) return state;
-      if (item.view === ORCHESTRATOR_VIEWS.HOME) {
-        return {
-          ...state,
-          view: ORCHESTRATOR_VIEWS.HOME,
-          listIndex: 0,
-          region: COCKPIT_REGIONS.CONTENT
-        };
-      }
       return {
         ...state,
         view: item.view,
         listIndex: 0,
-        region: COCKPIT_REGIONS.CONTENT,
-        helpOpen: false
+        region: defaultRegionForView(item.view, state.layoutMode),
+        helpOpen: false,
+        returnView: null
       };
     }
-    case "set-view":
+    case "set-view": {
+      const nextView = action.view;
       return {
         ...state,
-        view: action.view,
+        view: nextView,
         listIndex: 0,
-        region: action.region ?? COCKPIT_REGIONS.CONTENT
+        navIndex: action.navIndex == null
+          ? state.navIndex
+          : clamp(action.navIndex, 0, COCKPIT_NAV.length - 1),
+        region: action.region ?? defaultRegionForView(nextView, state.layoutMode),
+        returnView: action.returnView ?? state.returnView,
+        helpOpen: nextView === ORCHESTRATOR_VIEWS.HELP
       };
+    }
     case "toggle-help":
-      if (state.helpOpen) {
-        return {
-          ...state,
-          helpOpen: false,
-          view: state.view === ORCHESTRATOR_VIEWS.HELP
-            ? ORCHESTRATOR_VIEWS.HOME
-            : state.view
-        };
+      if (state.helpOpen || state.view === ORCHESTRATOR_VIEWS.HELP) {
+        return goOverview(state);
       }
-      return { ...state, helpOpen: true, view: ORCHESTRATOR_VIEWS.HELP };
+      return {
+        ...state,
+        helpOpen: true,
+        view: ORCHESTRATOR_VIEWS.HELP,
+        region: defaultRegionForView(ORCHESTRATOR_VIEWS.HELP, state.layoutMode)
+      };
     case "escape": {
-      if (state.helpOpen) {
-        return { ...state, helpOpen: false, view: ORCHESTRATOR_VIEWS.HOME };
+      if (state.helpOpen || state.view === ORCHESTRATOR_VIEWS.HELP) {
+        return goOverview(state);
       }
-      if (state.view !== ORCHESTRATOR_VIEWS.HOME) {
-        const regions = regionsForLayout(state.layoutMode);
+      if (state.view === ORCHESTRATOR_VIEWS.RUN_DETAIL) {
+        const back = state.returnView && isContentInteractiveView(state.returnView)
+          ? state.returnView
+          : ORCHESTRATOR_VIEWS.ACTIVE_RUNS;
         return {
           ...state,
-          view: ORCHESTRATOR_VIEWS.HOME,
+          view: back,
           listIndex: 0,
-          region: regions.includes(COCKPIT_REGIONS.NAV)
-            ? COCKPIT_REGIONS.NAV
-            : COCKPIT_REGIONS.CONTENT
+          region: defaultRegionForView(back, state.layoutMode),
+          returnView: null
         };
       }
+      if (state.view !== ORCHESTRATOR_VIEWS.HOME) {
+        return goOverview(state);
+      }
       return { ...state, shouldExit: true };
     }
     case "clear-exit":
@@ -126,6 +158,14 @@ export function resolveNavAction(navIndex) {
   return COCKPIT_NAV[navIndex] ?? null;
 }
 
-function clamp(value, min, max) {
-  return Math.min(max, Math.max(min, value));
+function goOverview(state) {
+  return {
+    ...state,
+    helpOpen: false,
+    view: ORCHESTRATOR_VIEWS.HOME,
+    navIndex: 0,
+    listIndex: 0,
+    region: defaultRegionForView(ORCHESTRATOR_VIEWS.HOME, state.layoutMode),
+    returnView: null
+  };
 }