gflows 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.3] - 2026-07-25
+
+### Fixed
+
+- Hub interactive actions no longer freeze/exit after Ink unmount (`stdin.ref` before dispatch; Clack cancel no longer `process.exit`s the hub)
+- `/switch`, `/init`, `/bump` wizards run inside Ink (same as start/list)
+
+### Changed
+
+- Local `bun run g` script invokes `src/cli.ts` so the hub gets a real TTY
+
+## [1.0.2] - 2026-07-25
+
+### Changed
+
+- Hub read-only screens stay in Ink: `/doctor`, `/help`, `/status`, `/config`, `/version` (enter/esc return)
+
 ## [1.0.1] - 2026-07-25
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gflows",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "author": "Ali AlNaghmoush (https://github.com/alialnaghmoush)",
   "repository": {
     "type": "git",
@@ -39,7 +39,8 @@
     "gflows": "bun run src/cli.ts",
     "publish:all": "bun run scripts/publish.ts",
     "publish:npm": "bun run scripts/publish.ts -- --npm-only",
-    "publish:jsr": "bun run scripts/publish.ts -- --jsr-only"
+    "publish:jsr": "bun run scripts/publish.ts -- --jsr-only",
+    "g": "bun run src/cli.ts"
   },
   "type": "module",
   "dependencies": {

package/src/cli.ts

@@ -9,6 +9,7 @@
 import { EXIT_GIT, EXIT_OK, EXIT_USER } from "./constants.js";
 import { exitCodeForError, printError } from "./errors.js";
 import { parse } from "./parse.js";
+import { PromptCancelledError } from "./prompts.js";
 import type { ParsedArgs } from "./types.js";
 
 /** Last parsed args, set at start of run(); used by catch/rejection to respect -v for stack trace. */
@@ -27,7 +28,10 @@ async function run(): Promise<void> {
       await runHub(process.cwd());
       return;
     }
-    console.error("gflows: missing command. Use 'gflows help' for usage.");
+    console.error(
+      "gflows: no interactive TTY. Run `gflows` directly (or `alias g=gflows`), not via a bun/npm script that swallows stdin.",
+    );
+    console.error("Or pass a command: gflows help");
     process.exit(EXIT_USER);
   }
 
@@ -76,6 +80,10 @@ function main(): void {
     })
     .catch((err: unknown) => {
       if (exitCode !== null) return;
+      if (err instanceof PromptCancelledError) {
+        process.exit(EXIT_OK);
+        return;
+      }
       printError(err);
       const verbose = lastParsedArgs?.verbose ?? !!process.env.GFLOWS_VERBOSE;
       if (verbose && err instanceof Error && err.stack) {

package/src/commands/doctor.ts

@@ -17,34 +17,30 @@ import { hint, success } from "../out.js";
 import { readActiveRun } from "../run-state.js";
 import type { ParsedArgs } from "../types.js";
 
-interface Check {
+/** One doctor health check row. */
+export interface DoctorCheck {
   ok: boolean;
   name: string;
   detail: string;
 }
 
+/** Structured doctor report (CLI + hub). */
+export interface DoctorReport {
+  ok: boolean;
+  checks: DoctorCheck[];
+}
+
 /**
- * Runs health checks and prints a report (or JSON).
+ * Collects repo health checks without printing or exiting.
  */
-export async function run(args: ParsedArgs): Promise<void> {
-  let repoRoot: string;
-  try {
-    repoRoot = await resolveRepoRoot(args.cwd);
-  } catch (err) {
-    if (args.json) {
-      console.log(JSON.stringify({ ok: false, error: String(err) }, null, 2));
-      process.exit(2);
-    }
-    throw err;
-  }
-
-  const config = resolveConfig(
-    repoRoot,
-    { main: args.main, dev: args.dev, remote: args.remote },
-    { verbose: args.verbose },
-  );
+export async function collectDoctorReport(
+  cwd: string,
+  overrides?: { main?: string; dev?: string; remote?: string },
+): Promise<DoctorReport> {
+  const repoRoot = await resolveRepoRoot(cwd);
+  const config = resolveConfig(repoRoot, overrides ?? {}, {});
   const cfgRead = readConfigFile(repoRoot);
-  const checks: Check[] = [];
+  const checks: DoctorCheck[] = [];
 
   checks.push({
     ok: true,
@@ -121,9 +117,37 @@ export async function run(args: ParsedArgs): Promise<void> {
     detail: clean ? "clean" : "dirty (uncommitted changes)",
   });
 
-  const ok = checks.every((c) => c.ok);
+  return { ok: checks.every((c) => c.ok), checks };
+}
+
+/**
+ * Runs health checks and prints a report (or JSON).
+ */
+export async function run(args: ParsedArgs): Promise<void> {
+  let report: DoctorReport;
+  try {
+    report = await collectDoctorReport(args.cwd, {
+      main: args.main,
+      dev: args.dev,
+      remote: args.remote,
+    });
+  } catch (err) {
+    if (args.json) {
+      console.log(JSON.stringify({ ok: false, error: String(err) }, null, 2));
+      process.exit(2);
+    }
+    throw err;
+  }
+
+  const { ok, checks } = report;
 
   if (args.json) {
+    const repoRoot = await resolveRepoRoot(args.cwd);
+    const config = resolveConfig(
+      repoRoot,
+      { main: args.main, dev: args.dev, remote: args.remote },
+      { verbose: args.verbose },
+    );
     console.log(JSON.stringify({ ok, config, checks }, null, 2));
     if (!ok) process.exit(2);
     return;

package/src/commands/help.ts

@@ -6,10 +6,10 @@
 import type { ParsedArgs } from "../types.js";
 
 /**
- * Runs the help command: prints usage, commands, types, flags, and exit codes to stdout.
+ * Full help text (CLI stdout + hub scroll panel).
  */
-export async function run(_args: ParsedArgs): Promise<void> {
-  const out = `
+export function getHelpText(): string {
+  return `
 gflows — Modern Git branching workflow CLI
 
 Usage: gflows <command> [type] [name] [flags]
@@ -68,6 +68,12 @@ Exit codes: 0 success, 1 usage/validation, 2 Git or system error.
 
 Stuck?  gflows continue | gflows abort | gflows undo | gflows doctor
 Agents: see AGENTS.md, gflows schema, gflows mcp
-`;
-  console.log(out.trim());
+`.trim();
+}
+
+/**
+ * Runs the help command: prints usage, commands, types, flags, and exit codes to stdout.
+ */
+export async function run(_args: ParsedArgs): Promise<void> {
+  console.log(getHelpText());
 }

package/src/commands/status-lines.ts

@@ -0,0 +1,92 @@
+/**
+ * Structured status lines for CLI-adjacent hub panels.
+ * Kept separate so `status.ts` stays focused on CLI printing.
+ * @module commands/status-lines
+ */
+
+import { resolveConfig } from "../config.js";
+import {
+  classifyBranch,
+  formatMergeTarget,
+  getBaseBranchName,
+  resolveMergeTarget,
+} from "../flow.js";
+import { getAheadBehind, getCurrentBranch, resolveRepoRoot } from "../git.js";
+import { readActiveRun } from "../run-state.js";
+
+/** One status line with optional tone for the hub panel. */
+export interface StatusLine {
+  text: string;
+  tone?: "default" | "ok" | "bad" | "muted" | "accent";
+}
+
+/**
+ * Collects human-readable status rows for the current branch.
+ */
+export async function collectStatusLines(cwd: string): Promise<StatusLine[]> {
+  const root = await resolveRepoRoot(cwd);
+  const config = resolveConfig(root, {}, {});
+  const current = await getCurrentBranch(root, {});
+  const active = readActiveRun(root);
+  const lines: StatusLine[] = [];
+
+  if (active) {
+    lines.push({
+      text: `Suspended: ${active.command} (${active.status})`,
+      tone: "bad",
+    });
+    lines.push({
+      text: "Run /continue after conflicts, or gflows abort / undo",
+      tone: "muted",
+    });
+  }
+
+  if (current === null) {
+    lines.push({ text: "HEAD is detached.", tone: "bad" });
+    lines.push({ text: "Try: git checkout dev", tone: "muted" });
+    return lines;
+  }
+
+  lines.push({ text: `Branch: ${current}`, tone: "accent" });
+
+  const classification = classifyBranch(current, config);
+
+  if (classification === "main") {
+    lines.push({ text: "Type: long-lived (main)" });
+    lines.push({ text: "Next: /start feature <name> or hotfix", tone: "muted" });
+    return lines;
+  }
+
+  if (classification === "dev") {
+    lines.push({ text: "Type: long-lived (dev)" });
+    lines.push({ text: "Next: /start feature <name>", tone: "muted" });
+    return lines;
+  }
+
+  if (classification === null) {
+    lines.push({ text: "Type: unknown" });
+    lines.push({ text: "Use a typed prefix or /start …", tone: "muted" });
+    return lines;
+  }
+
+  const mergeTarget = await resolveMergeTarget(root, current, classification, config, {});
+  const baseBranch = getBaseBranchName(
+    classification,
+    mergeTarget === "main-then-dev" && classification === "bugfix",
+    config,
+  );
+  const mergeTargetDisplay = formatMergeTarget(mergeTarget, config);
+  const { ahead, behind } = await getAheadBehind(root, baseBranch, current, {});
+
+  lines.push({ text: `Type: ${classification}` });
+  lines.push({ text: `Base: ${baseBranch}` });
+  lines.push({ text: `Merge target(s): ${mergeTargetDisplay}` });
+  lines.push({ text: `Ahead/behind: ${ahead} ahead, ${behind} behind` });
+  lines.push({
+    text:
+      ahead === 0 ? "No commits to finish yet — commit first" : `Next: /finish ${classification}`,
+    tone: ahead === 0 ? "muted" : "ok",
+  });
+
+  return lines;
+}

package/src/prompts.ts

@@ -6,12 +6,26 @@
 import * as clack from "@clack/prompts";
 
 /**
- * Exits the process when the user cancels a prompt (Ctrl+C / Escape).
+ * Thrown when the user cancels a Clack prompt (Ctrl+C / Escape).
+ * Callers (CLI / hub) should treat this as a soft abort — do not kill the hub loop via process.exit.
+ */
+export class PromptCancelledError extends Error {
+  /**
+   * Creates a cancellation error.
+   */
+  constructor() {
+    super("Cancelled.");
+    this.name = "PromptCancelledError";
+  }
+}
+
+/**
+ * Converts Clack cancel symbols into {@link PromptCancelledError}.
  */
 function exitIfCancel<T>(value: T | symbol): asserts value is T {
   if (clack.isCancel(value)) {
     clack.cancel("Cancelled.");
-    process.exit(0);
+    throw new PromptCancelledError();
   }
 }
 

package/src/tui/HubShell.tsx

@@ -6,10 +6,19 @@
 import { Box, Text, useApp, useInput } from "ink";
 import type React from "react";
 import { useState } from "react";
-import { FinishFlow, ListFlow, StartFlow, SyncFlow } from "./flows.js";
+import {
+  BumpFlow,
+  FinishFlow,
+  InitFlow,
+  ListFlow,
+  StartFlow,
+  SwitchFlow,
+  SyncFlow,
+} from "./flows.js";
 import { HubHome } from "./HubHome.js";
 import { WizardFrame } from "./prompts.js";
 import { SLASH_COMMANDS } from "./slash.js";
+import { ConfigView, DoctorView, HelpView, StatusView, VersionView } from "./views.js";
 
 const ACCENT = "#E88C4A";
 const MUTED = "#8A8A8A";
@@ -24,13 +33,27 @@ type Screen =
   | { id: "finish" }
   | { id: "sync" }
   | { id: "list" }
+  | { id: "switch" }
+  | { id: "init" }
+  | { id: "bump" }
+  | { id: "doctor" }
+  | { id: "help" }
+  | { id: "status" }
+  | { id: "config" }
+  | { id: "version" }
   | { id: "notice"; message: string };
 
-const DISPATCH_COMMANDS = new Set(
-  SLASH_COMMANDS.map((c) => c.name).filter(
-    (name) => !["start", "finish", "sync", "list", "viz", "quit", "exit", "q"].includes(name),
-  ),
-);
+/** Commands that leave Ink for git / side effects (no interactive Clack). */
+const DISPATCH_COMMANDS = new Set([
+  "pr",
+  "continue",
+  "delete",
+  "undo",
+  "abort",
+  "schema",
+  "mcp",
+  "completion",
+]);
 
 /**
  * Props for the hub shell.
@@ -55,6 +78,52 @@ export function HubShell({ cwd, onDone }: HubShellProps): React.ReactElement {
   const cancelWizard = () => setScreen({ id: "home" });
   const runArgv = (argv: string[]) => finish({ kind: "run", argv });
 
+  const openInHub = (cmd: string): boolean => {
+    switch (cmd) {
+      case "start":
+        setScreen({ id: "start" });
+        return true;
+      case "finish":
+        setScreen({ id: "finish" });
+        return true;
+      case "sync":
+        setScreen({ id: "sync" });
+        return true;
+      case "list":
+        setScreen({ id: "list" });
+        return true;
+      case "switch":
+        setScreen({ id: "switch" });
+        return true;
+      case "init":
+        setScreen({ id: "init" });
+        return true;
+      case "bump":
+        setScreen({ id: "bump" });
+        return true;
+      case "doctor":
+        setScreen({ id: "doctor" });
+        return true;
+      case "help":
+        setScreen({ id: "help" });
+        return true;
+      case "status":
+        setScreen({ id: "status" });
+        return true;
+      case "config":
+        setScreen({ id: "config" });
+        return true;
+      case "version":
+        setScreen({ id: "version" });
+        return true;
+      case "viz":
+        setScreen({ id: "home", flash: "Branch map is shown on this screen." });
+        return true;
+      default:
+        return false;
+    }
+  };
+
   const handleSlash = (raw: string) => {
     const parts = raw.slice(1).trim().split(/\s+/);
     const cmd = (parts[0] ?? "").toLowerCase();
@@ -91,16 +160,26 @@ export function HubShell({ cwd, onDone }: HubShellProps): React.ReactElement {
       setScreen({ id: "sync" });
       return;
     }
-    if (cmd === "list") {
-      setScreen({ id: "list" });
+    if (cmd === "config" && rest.length > 0) {
+      runArgv(["config", ...rest]);
+      return;
+    }
+    if (cmd === "switch" && rest.length > 0) {
+      runArgv(["switch", ...rest]);
       return;
     }
-    if (cmd === "viz") {
-      setScreen({ id: "home", flash: "Branch map is shown on this screen." });
+    if (cmd === "bump" && rest.length > 0) {
+      runArgv(["bump", ...rest]);
+      return;
+    }
+    if (cmd === "init" && rest.length > 0) {
+      runArgv(["init", ...rest]);
       return;
     }
 
-    if (!DISPATCH_COMMANDS.has(cmd)) {
+    if (openInHub(cmd)) return;
+
+    if (!DISPATCH_COMMANDS.has(cmd) && !SLASH_COMMANDS.some((c) => c.name === cmd)) {
       setScreen({
         id: "notice",
         message: `Unknown /${cmd} — type / for command hints.`,
@@ -108,6 +187,14 @@ export function HubShell({ cwd, onDone }: HubShellProps): React.ReactElement {
       return;
     }
 
+    if (!DISPATCH_COMMANDS.has(cmd)) {
+      setScreen({
+        id: "notice",
+        message: `/${cmd} is not available from the hub yet.`,
+      });
+      return;
+    }
+
     runArgv([cmd, ...rest]);
   };
 
@@ -116,22 +203,7 @@ export function HubShell({ cwd, onDone }: HubShellProps): React.ReactElement {
       finish({ kind: "quit" });
       return;
     }
-    if (action === "start") {
-      setScreen({ id: "start" });
-      return;
-    }
-    if (action === "finish") {
-      setScreen({ id: "finish" });
-      return;
-    }
-    if (action === "sync") {
-      setScreen({ id: "sync" });
-      return;
-    }
-    if (action === "list") {
-      setScreen({ id: "list" });
-      return;
-    }
+    if (openInHub(action)) return;
     runArgv([action]);
   };
 
@@ -147,6 +219,30 @@ export function HubShell({ cwd, onDone }: HubShellProps): React.ReactElement {
   if (screen.id === "list") {
     return <ListFlow cwd={cwd} onDone={cancelWizard} />;
   }
+  if (screen.id === "switch") {
+    return <SwitchFlow cwd={cwd} onCancel={cancelWizard} onDone={runArgv} />;
+  }
+  if (screen.id === "init") {
+    return <InitFlow onCancel={cancelWizard} onDone={runArgv} />;
+  }
+  if (screen.id === "bump") {
+    return <BumpFlow onCancel={cancelWizard} onDone={runArgv} />;
+  }
+  if (screen.id === "doctor") {
+    return <DoctorView cwd={cwd} onDone={cancelWizard} />;
+  }
+  if (screen.id === "help") {
+    return <HelpView onDone={cancelWizard} />;
+  }
+  if (screen.id === "status") {
+    return <StatusView cwd={cwd} onDone={cancelWizard} />;
+  }
+  if (screen.id === "config") {
+    return <ConfigView cwd={cwd} onDone={cancelWizard} />;
+  }
+  if (screen.id === "version") {
+    return <VersionView onDone={cancelWizard} />;
+  }
   if (screen.id === "notice") {
     return (
       <PressEnter

package/src/tui/flows.tsx

@@ -1,22 +1,24 @@
 /**
- * Multi-step Ink wizards for hub actions (start / finish / sync / list).
+ * Multi-step Ink wizards for hub actions (start / finish / sync / list / switch / …).
  * @module tui/flows
  */
 
-import { Box, Text, useInput } from "ink";
+import { Text } from "ink";
 import type React from "react";
 import { useEffect, useState } from "react";
+import { resolveConfig } from "../config.js";
+import { branchList, getCurrentBranch, isClean, resolveRepoRoot } from "../git.js";
 import type { BranchType } from "../types.js";
 import { collectVizSnapshot, type VizSnapshot } from "../viz.js";
+import { type HubPanelLine, HubScrollPanel } from "./panels.js";
 import { InkConfirm, InkSelect, InkText, WizardFrame } from "./prompts.js";
 
 const MUTED = "#8A8A8A";
-const FG = "#E6E6E6";
-const GREEN = "#78C88C";
-const ACCENT = "#E88C4A";
 
 const BRANCH_TYPES: BranchType[] = ["feature", "bugfix", "chore", "release", "hotfix", "spike"];
 
+type SwitchMode = "move" | "restore" | "clean" | "destroy" | "cancel";
+
 /**
  * Collects argv for `gflows start …` entirely inside Ink.
  */
@@ -147,22 +149,53 @@ export function SyncFlow({
 }
 
 /**
- * Styled branch list inside the hub (no drop-out to plain stdout).
+ * Switch-branch wizard entirely inside Ink (avoids dead Clack after Ink unmount).
  */
-export function ListFlow({ cwd, onDone }: { cwd: string; onDone: () => void }): React.ReactElement {
-  const [lines, setLines] = useState<string[] | null>(null);
+export function SwitchFlow({
+  cwd,
+  onDone,
+  onCancel,
+}: {
+  cwd: string;
+  onDone: (argv: string[]) => void;
+  onCancel: () => void;
+}): React.ReactElement {
+  const [step, setStep] = useState<"load" | "pick" | "dirty" | "error">("load");
+  const [choices, setChoices] = useState<{ value: string; label: string }[]>([]);
+  const [target, setTarget] = useState("");
   const [error, setError] = useState<string | null>(null);
+  const [initialIndex, setInitialIndex] = useState(0);
 
   useEffect(() => {
     let cancelled = false;
     void (async () => {
       try {
-        const snap = await collectVizSnapshot(cwd);
-        if (!cancelled) setLines(formatListLines(snap));
+        const root = await resolveRepoRoot(cwd);
+        const config = resolveConfig(root, {}, {});
+        const allLocal = await branchList(root, { dryRun: false, verbose: false });
+        const workflow = BRANCH_TYPES.map((t) => config.prefixes[t])
+          .filter(Boolean)
+          .flatMap((prefix) => allLocal.filter((b) => b.startsWith(prefix)));
+        const mainAndDev = [config.main, config.dev].filter((b) => allLocal.includes(b));
+        const names = [...mainAndDev, ...[...new Set(workflow)].sort()];
+        const current = await getCurrentBranch(root, {});
+        if (cancelled) return;
+        if (names.length === 0) {
+          setError("No branches found.");
+          setStep("error");
+          return;
+        }
+        const opts = names.map((b) => ({
+          value: b,
+          label: current && b === current ? `${b} (current)` : b,
+        }));
+        setChoices(opts);
+        setInitialIndex(Math.max(0, current ? names.indexOf(current) : 0));
+        setStep("pick");
       } catch (err) {
         if (!cancelled) {
           setError(err instanceof Error ? err.message : String(err));
-          setLines([]);
+          setStep("error");
         }
       }
     })();
@@ -171,36 +204,248 @@ export function ListFlow({ cwd, onDone }: { cwd: string; onDone: () => void }):
     };
   }, [cwd]);
 
-  useInput((_ch, key) => {
-    if (key.return || key.escape || (key.ctrl && _ch === "c")) onDone();
-  });
+  if (step === "load") {
+    return (
+      <WizardFrame title="Switch branch">
+        <Text color={MUTED}>Loading…</Text>
+      </WizardFrame>
+    );
+  }
 
+  if (step === "error") {
+    return (
+      <HubScrollPanel
+        title="Switch branch"
+        lines={[{ id: "e", text: error ?? "Unknown error", tone: "bad" }]}
+        onDone={onCancel}
+      />
+    );
+  }
+
+  if (step === "pick") {
+    return (
+      <WizardFrame title="Switch branch">
+        <InkSelect
+          message="Switch to branch"
+          options={choices}
+          initialIndex={initialIndex}
+          onCancel={onCancel}
+          onSubmit={(branch) => {
+            void (async () => {
+              setTarget(branch);
+              try {
+                const root = await resolveRepoRoot(cwd);
+                const clean = await isClean(root, {});
+                if (clean) {
+                  onDone(["switch", branch]);
+                  return;
+                }
+                setStep("dirty");
+              } catch (err) {
+                setError(err instanceof Error ? err.message : String(err));
+                setStep("error");
+              }
+            })();
+          }}
+        />
+      </WizardFrame>
+    );
+  }
+
+  // dirty
   return (
-    <WizardFrame title="Branches">
-      {lines === null ? (
-        <Text color={MUTED}>Loading…</Text>
-      ) : error ? (
-        <Text color={FG}>{error}</Text>
-      ) : (
-        <Box flexDirection="column">
-          {lines.map((line) => {
-            const current = line.includes("●");
-            return (
-              <Text key={line} color={current ? GREEN : FG} bold={current}>
-                {line}
-              </Text>
-            );
-          })}
-        </Box>
-      )}
-      <Box marginTop={1}>
-        <Text color={MUTED}>enter / esc return to hub</Text>
-        <Text color={ACCENT}> █</Text>
-      </Box>
+    <WizardFrame title={`Switch · ${target}`}>
+      <InkSelect<SwitchMode>
+        message="Working tree has uncommitted changes"
+        options={[
+          { value: "move", label: "Move", hint: "carry changes to target" },
+          { value: "restore", label: "Restore", hint: "stash here, restore target" },
+          { value: "clean", label: "Clean", hint: "discard changes" },
+          { value: "destroy", label: "Destroy", hint: "delete current branch" },
+          { value: "cancel", label: "Cancel", hint: "abort switch" },
+        ]}
+        onCancel={onCancel}
+        onSubmit={(mode) => {
+          if (mode === "cancel") {
+            onCancel();
+            return;
+          }
+          onDone(["switch", target, `--${mode}`]);
+        }}
+      />
     </WizardFrame>
   );
 }
 
+/**
+ * Init wizard inside Ink; dispatches with -y so CLI skips Clack prompts.
+ */
+export function InitFlow({
+  onDone,
+  onCancel,
+}: {
+  onDone: (argv: string[]) => void;
+  onCancel: () => void;
+}): React.ReactElement {
+  const [step, setStep] = useState<"main" | "dev" | "remote" | "alias">("main");
+  const [main, setMain] = useState("main");
+  const [dev, setDev] = useState("dev");
+  const [remote, setRemote] = useState("origin");
+
+  if (step === "main") {
+    return (
+      <WizardFrame title="Initialize repo">
+        <InkText
+          message="Main branch name"
+          placeholder="main"
+          initialValue="main"
+          onCancel={onCancel}
+          onSubmit={(v) => {
+            setMain(v || "main");
+            setStep("dev");
+          }}
+        />
+      </WizardFrame>
+    );
+  }
+  if (step === "dev") {
+    return (
+      <WizardFrame title="Initialize repo">
+        <InkText
+          message="Dev branch name"
+          placeholder="dev"
+          initialValue="dev"
+          onCancel={onCancel}
+          onSubmit={(v) => {
+            setDev(v || "dev");
+            setStep("remote");
+          }}
+        />
+      </WizardFrame>
+    );
+  }
+  if (step === "remote") {
+    return (
+      <WizardFrame title="Initialize repo">
+        <InkText
+          message="Remote name"
+          placeholder="origin"
+          initialValue="origin"
+          onCancel={onCancel}
+          onSubmit={(v) => {
+            setRemote(v || "origin");
+            setStep("alias");
+          }}
+        />
+      </WizardFrame>
+    );
+  }
+
+  return (
+    <WizardFrame title="Initialize repo">
+      <InkSelect
+        message="Add package.json script alias?"
+        options={[
+          { value: "g", label: 'script "g"', hint: "prefer: alias g=gflows in shell" },
+          { value: "gflows", label: 'script "gflows"' },
+          { value: "skip", label: "Skip", hint: "shell alias is best for hub TTY" },
+        ]}
+        onCancel={onCancel}
+        onSubmit={(alias) => {
+          const argv = ["init", "-y", "-P", "--main", main, "--dev", dev, "--remote", remote];
+          if (alias === "skip") argv.push("--no-script-alias");
+          else argv.push("--script-alias", alias);
+          onDone(argv);
+        }}
+      />
+    </WizardFrame>
+  );
+}
+
+/**
+ * Bump wizard inside Ink.
+ */
+export function BumpFlow({
+  onDone,
+  onCancel,
+}: {
+  onDone: (argv: string[]) => void;
+  onCancel: () => void;
+}): React.ReactElement {
+  const [step, setStep] = useState<"dir" | "type">("dir");
+  const [direction, setDirection] = useState<"up" | "down">("up");
+
+  if (step === "dir") {
+    return (
+      <WizardFrame title="Bump version">
+        <InkSelect<"up" | "down">
+          message="Direction"
+          options={[
+            { value: "up", label: "Up (bump)" },
+            { value: "down", label: "Down (rollback)" },
+          ]}
+          onCancel={onCancel}
+          onSubmit={(d) => {
+            setDirection(d);
+            setStep("type");
+          }}
+        />
+      </WizardFrame>
+    );
+  }
+
+  return (
+    <WizardFrame title={`Bump · ${direction}`}>
+      <InkSelect<"patch" | "minor" | "major">
+        message="Semver part"
+        options={[
+          { value: "patch", label: "patch" },
+          { value: "minor", label: "minor" },
+          { value: "major", label: "major" },
+        ]}
+        onCancel={onCancel}
+        onSubmit={(type) => onDone(["bump", direction, type])}
+      />
+    </WizardFrame>
+  );
+}
+
+/**
+ * Styled branch list inside the hub (no drop-out to plain stdout).
+ */
+export function ListFlow({ cwd, onDone }: { cwd: string; onDone: () => void }): React.ReactElement {
+  const [lines, setLines] = useState<HubPanelLine[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const snap = await collectVizSnapshot(cwd);
+        if (!cancelled) {
+          setLines(
+            formatListLines(snap).map((text, i) => ({
+              id: `b${i}`,
+              text,
+              tone: text.includes("●") ? ("ok" as const) : ("default" as const),
+            })),
+          );
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : String(err));
+          setLines([]);
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [cwd]);
+
+  return <HubScrollPanel title="Branches" lines={lines} error={error} onDone={onDone} />;
+}
+
 /**
  * Formats a viz snapshot into hub list rows.
  */

package/src/tui/hub.ts

@@ -6,7 +6,9 @@
 import { render } from "ink";
 import React from "react";
 import { dispatch } from "../dispatch.js";
+import { PromptCancelledError } from "../prompts.js";
 import { type HubSessionResult, HubShell } from "./HubShell.js";
+import { prepareStdinAfterInk } from "./stdin.js";
 
 /**
  * Whether stdin/stdout can host the Ink hub.
@@ -27,11 +29,15 @@ export async function runTuiHub(cwd: string): Promise<boolean> {
     if (result.kind === "quit") break;
 
     if (result.kind === "run") {
+      // Ink unrefs stdin on unmount — re-arm before Clack / git prompts.
+      prepareStdinAfterInk();
       console.log("");
       try {
         await dispatch(cwd, result.argv);
       } catch (err) {
-        console.error("gflows:", err instanceof Error ? err.message : String(err));
+        if (!(err instanceof PromptCancelledError)) {
+          console.error("gflows:", err instanceof Error ? err.message : String(err));
+        }
       }
       console.log("");
       await waitEnterRaw("Press enter to return to hub…");

package/src/tui/panels.tsx

@@ -0,0 +1,111 @@
+/**
+ * Shared Ink panels for in-hub result screens (doctor / help / status / …).
+ * @module tui/panels
+ */
+
+import { Box, Text, useInput, useStdout } from "ink";
+import type React from "react";
+import { useState } from "react";
+import { WizardFrame } from "./prompts.js";
+
+const ACCENT = "#E88C4A";
+const MUTED = "#8A8A8A";
+const FG = "#E6E6E6";
+const GREEN = "#78C88C";
+const RED = "#E06C75";
+
+/** One styled line for {@link HubScrollPanel}. */
+export interface HubPanelLine {
+  /** Stable React key for the row. */
+  id: string;
+  text: string;
+  tone?: "default" | "ok" | "bad" | "muted" | "accent";
+}
+
+/**
+ * Scrollable framed panel that returns to the hub on enter/esc.
+ */
+export function HubScrollPanel({
+  title,
+  lines,
+  loading,
+  error,
+  onDone,
+}: {
+  title: string;
+  lines: HubPanelLine[] | null;
+  loading?: boolean;
+  error?: string | null;
+  onDone: () => void;
+}): React.ReactElement {
+  const { stdout } = useStdout();
+  const rows = stdout?.rows ?? 24;
+  const lineCount = lines?.length ?? 0;
+  const budget = Math.max(6, Math.min(lineCount || 6, rows - 8));
+  const [offset, setOffset] = useState(0);
+  const maxOffset = Math.max(0, lineCount - budget);
+  const safeOffset = Math.min(offset, maxOffset);
+  const visible = lines?.slice(safeOffset, safeOffset + budget) ?? [];
+
+  useInput((ch, key) => {
+    if (key.return || key.escape || (key.ctrl && ch === "c")) {
+      onDone();
+      return;
+    }
+    if (key.upArrow || ch === "k") {
+      setOffset((o) => Math.max(0, o - 1));
+      return;
+    }
+    if (key.downArrow || ch === "j") {
+      setOffset((o) => Math.min(maxOffset, o + 1));
+      return;
+    }
+    if (key.pageUp) {
+      setOffset((o) => Math.max(0, o - budget));
+      return;
+    }
+    if (key.pageDown) {
+      setOffset((o) => Math.min(maxOffset, o + budget));
+    }
+  });
+
+  return (
+    <WizardFrame title={title}>
+      {loading || lines === null ? (
+        <Text color={MUTED}>Loading…</Text>
+      ) : error ? (
+        <Text color={RED}>{error}</Text>
+      ) : (
+        <Box flexDirection="column">
+          {visible.map((line) => (
+            <Text key={line.id} color={toneColor(line.tone)} bold={line.tone === "ok"}>
+              {line.text}
+            </Text>
+          ))}
+        </Box>
+      )}
+      <Box marginTop={1}>
+        <Text color={MUTED}>
+          {maxOffset > 0 ? "↑↓ scroll · " : ""}
+          enter / esc return to hub
+        </Text>
+        <Text color={ACCENT}> █</Text>
+      </Box>
+    </WizardFrame>
+  );
+}
+
+function toneColor(tone: HubPanelLine["tone"]): string {
+  switch (tone) {
+    case "ok":
+      return GREEN;
+    case "bad":
+      return RED;
+    case "muted":
+      return MUTED;
+    case "accent":
+      return ACCENT;
+    default:
+      return FG;
+  }
+}

package/src/tui/slash.ts

@@ -27,6 +27,7 @@ export const SLASH_COMMANDS: readonly SlashCommand[] = [
   { name: "help", hint: "Show help" },
   { name: "status", hint: "Repo status" },
   { name: "config", hint: "Show config" },
+  { name: "version", hint: "Show version" },
   { name: "bump", hint: "Bump version" },
   { name: "viz", hint: "Branch map (on home)" },
   { name: "quit", hint: "Leave hub" },

package/src/tui/stdin.ts

@@ -0,0 +1,28 @@
+/**
+ * Stdin helpers for surviving Ink teardown before Clack / dispatch.
+ * @module tui/stdin
+ */
+
+/**
+ * Re-arm process.stdin after Ink unmounts (Ink calls `stdin.unref()`).
+ * Without this, interactive Clack prompts paint once then the process exits.
+ */
+export function prepareStdinAfterInk(): void {
+  const stdin = process.stdin;
+  if (typeof stdin.setRawMode === "function") {
+    try {
+      stdin.setRawMode(false);
+    } catch {
+      // ignore — may already be non-raw / closed
+    }
+  }
+  stdin.resume();
+  stdin.ref();
+
+  if (typeof stdin.read === "function") {
+    for (;;) {
+      const pending = stdin.read();
+      if (pending === null) break;
+    }
+  }
+}

package/src/tui/views.tsx

@@ -0,0 +1,182 @@
+/**
+ * Read-only Ink screens that stay inside the hub (doctor / help / status / config).
+ * @module tui/views
+ */
+
+import type React from "react";
+import { useEffect, useState } from "react";
+import { collectDoctorReport } from "../commands/doctor.js";
+import { getHelpText } from "../commands/help.js";
+import { collectStatusLines } from "../commands/status-lines.js";
+import { resolveConfig } from "../config.js";
+import { resolveRepoRoot } from "../git.js";
+import { getVersion } from "../version.js";
+import { type HubPanelLine, HubScrollPanel } from "./panels.js";
+
+/**
+ * Doctor checks inside the hub.
+ */
+export function DoctorView({
+  cwd,
+  onDone,
+}: {
+  cwd: string;
+  onDone: () => void;
+}): React.ReactElement {
+  const [lines, setLines] = useState<HubPanelLine[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const report = await collectDoctorReport(cwd);
+        if (cancelled) return;
+        const rows: HubPanelLine[] = report.checks.map((c) => ({
+          id: c.name,
+          text: `${c.ok ? "✓" : "✗"} ${c.name}: ${c.detail}`,
+          tone: c.ok ? "ok" : "bad",
+        }));
+        rows.push({
+          id: "summary",
+          text: report.ok
+            ? "gflows doctor: all critical checks passed."
+            : "gflows doctor: some checks failed.",
+          tone: report.ok ? "ok" : "bad",
+        });
+        setLines(rows);
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : String(err));
+          setLines([]);
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [cwd]);
+
+  return <HubScrollPanel title="Doctor" lines={lines} error={error} onDone={onDone} />;
+}
+
+/**
+ * Scrollable help inside the hub.
+ */
+export function HelpView({ onDone }: { onDone: () => void }): React.ReactElement {
+  const lines: HubPanelLine[] = getHelpText()
+    .split("\n")
+    .map((text, i) => ({
+      id: `h${i}`,
+      text: text.length === 0 ? " " : text,
+      tone: text.endsWith(":") || text.startsWith("gflows") ? "accent" : "default",
+    }));
+
+  return <HubScrollPanel title="Help" lines={lines} onDone={onDone} />;
+}
+
+/**
+ * Branch status inside the hub.
+ */
+export function StatusView({
+  cwd,
+  onDone,
+}: {
+  cwd: string;
+  onDone: () => void;
+}): React.ReactElement {
+  const [lines, setLines] = useState<HubPanelLine[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const rows = await collectStatusLines(cwd);
+        if (!cancelled) {
+          setLines(
+            rows.map((row, i) => ({
+              id: `s${i}`,
+              text: row.text,
+              tone: row.tone,
+            })),
+          );
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : String(err));
+          setLines([]);
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [cwd]);
+
+  return <HubScrollPanel title="Status" lines={lines} error={error} onDone={onDone} />;
+}
+
+/**
+ * Resolved config snapshot inside the hub (read-only).
+ */
+export function ConfigView({
+  cwd,
+  onDone,
+}: {
+  cwd: string;
+  onDone: () => void;
+}): React.ReactElement {
+  const [lines, setLines] = useState<HubPanelLine[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const root = await resolveRepoRoot(cwd);
+        const config = resolveConfig(root, {}, {});
+        if (cancelled) return;
+        setLines([
+          { id: "main", text: `main: ${config.main}`, tone: "accent" },
+          { id: "dev", text: `dev: ${config.dev}` },
+          { id: "remote", text: `remote: ${config.remote}` },
+          { id: "prefixes", text: "prefixes:", tone: "muted" },
+          ...Object.entries(config.prefixes).map(([type, prefix]) => ({
+            id: `p-${type}`,
+            text: `  ${type}: ${prefix}`,
+          })),
+          { id: "blank", text: " ", tone: "muted" },
+          {
+            id: "hint",
+            text: "Use: gflows config set <key> <value>",
+            tone: "muted",
+          },
+        ]);
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : String(err));
+          setLines([]);
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [cwd]);
+
+  return <HubScrollPanel title="Config" lines={lines} error={error} onDone={onDone} />;
+}
+
+/**
+ * Version chip inside the hub.
+ */
+export function VersionView({ onDone }: { onDone: () => void }): React.ReactElement {
+  return (
+    <HubScrollPanel
+      title="Version"
+      lines={[{ id: "v", text: `gflows v${getVersion()}`, tone: "accent" }]}
+      onDone={onDone}
+    />
+  );
+}