@vellumai/cli 0.4.1 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/adapters/install.sh

@@ -14,13 +14,23 @@ success() { printf "${GREEN}${BOLD}==>${RESET} ${BOLD}%s${RESET}\n" "$1"; }
 error() { printf "${RED}error:${RESET} %s\n" "$1" >&2; }
 
 ensure_git() {
-    if command -v git >/dev/null 2>&1; then
+    # On macOS, /usr/bin/git is a shim that triggers an "Install Command Line
+    # Developer Tools" popup instead of running git. Check that git actually
+    # works, not just that the binary exists.
+    if command -v git >/dev/null 2>&1 && git --version >/dev/null 2>&1; then
         success "git already installed ($(git --version))"
         return
     fi
 
     info "Installing git..."
-    if command -v apt-get >/dev/null 2>&1; then
+    if [ "$(uname -s)" = "Darwin" ]; then
+        if command -v brew >/dev/null 2>&1; then
+            brew install git
+        else
+            error "git is required. Install Homebrew (https://brew.sh) then run: brew install git"
+            exit 1
+        fi
+    elif command -v apt-get >/dev/null 2>&1; then
         sudo apt-get update -qq && sudo apt-get install -y -qq git
     elif command -v yum >/dev/null 2>&1; then
         sudo yum install -y git
@@ -31,7 +41,11 @@ ensure_git() {
         exit 1
     fi
 
-    if ! command -v git >/dev/null 2>&1; then
+    # Clear bash's command hash so it finds the newly installed git binary
+    # instead of the cached path to the macOS /usr/bin/git shim.
+    hash -r 2>/dev/null || true
+
+    if ! git --version >/dev/null 2>&1; then
         error "git installation failed. Please install manually."
         exit 1
     fi
@@ -79,6 +93,98 @@ ensure_bun() {
     success "bun installed ($(bun --version))"
 }
 
+# Ensure ~/.bun/bin is in the user's shell profile so bun and vellum are
+# available in new terminal sessions. The bun installer sometimes skips
+# this (e.g. when stdin is piped via curl | bash).
+configure_shell_profile() {
+    local bun_line='export BUN_INSTALL="$HOME/.bun"'
+    local path_line='export PATH="$BUN_INSTALL/bin:$PATH"'
+    local snippet
+    snippet=$(printf '\n# bun\n%s\n%s\n' "$bun_line" "$path_line")
+
+    local profiles=()
+    local shell_name="${SHELL:-}"
+
+    if [[ "$shell_name" == */zsh ]]; then
+        profiles+=("$HOME/.zshrc")
+    elif [[ "$shell_name" == */bash ]]; then
+        # Write to both .bashrc (non-login shells, e.g. new terminal on Linux)
+        # and .bash_profile (login shells, e.g. macOS Terminal.app)
+        profiles+=("$HOME/.bashrc")
+        [ -f "$HOME/.bash_profile" ] && profiles+=("$HOME/.bash_profile")
+    else
+        # Unknown shell — try both
+        profiles+=("$HOME/.bashrc")
+        [ -f "$HOME/.zshrc" ] && profiles+=("$HOME/.zshrc")
+    fi
+
+    for profile in "${profiles[@]}"; do
+        if [ -f "$profile" ] && grep -q 'BUN_INSTALL' "$profile" 2>/dev/null; then
+            continue
+        fi
+        printf '%s\n' "$snippet" >> "$profile"
+        success "Added bun to PATH in $profile"
+    done
+}
+
+# Create a symlink so `vellum` is available without ~/.bun/bin in PATH.
+# Tries /usr/local/bin first (works on most systems), falls back to
+# ~/.local/bin (user-writable, no sudo needed).
+# This is best-effort — failure must not abort the install script.
+symlink_vellum() {
+    local vellum_bin="$HOME/.bun/bin/vellum"
+    if [ ! -f "$vellum_bin" ]; then
+        return 0
+    fi
+
+    # Skip if vellum is already resolvable outside of ~/.bun/bin
+    local resolved
+    resolved=$(command -v vellum 2>/dev/null || true)
+    if [ -n "$resolved" ] && [ "$resolved" != "$vellum_bin" ]; then
+        return 0
+    fi
+
+    # Try /usr/local/bin (may need sudo on some systems)
+    if [ -d "/usr/local/bin" ] && [ -w "/usr/local/bin" ]; then
+        if ln -sf "$vellum_bin" /usr/local/bin/vellum 2>/dev/null; then
+            success "Symlinked /usr/local/bin/vellum → $vellum_bin"
+            return 0
+        fi
+    fi
+
+    # Fallback: ~/.local/bin
+    local local_bin="$HOME/.local/bin"
+    mkdir -p "$local_bin" 2>/dev/null || true
+    if ln -sf "$vellum_bin" "$local_bin/vellum" 2>/dev/null; then
+        success "Symlinked $local_bin/vellum → $vellum_bin"
+        # Ensure ~/.local/bin is in PATH in shell profile
+        for profile in "$HOME/.zshrc" "$HOME/.bashrc" "$HOME/.bash_profile"; do
+            if [ -f "$profile" ] && ! grep -q "$local_bin" "$profile" 2>/dev/null; then
+                printf '\nexport PATH="%s:$PATH"\n' "$local_bin" >> "$profile"
+            fi
+        done
+        return 0
+    fi
+
+    return 0
+}
+
+# Write a small sourceable env file to ~/.config/vellum/env so callers can
+# pick up PATH changes without restarting their shell:
+#   curl -fsSL https://assistant.vellum.ai/install.sh | bash && . ~/.config/vellum/env
+write_env_file() {
+    local env_dir="${XDG_CONFIG_HOME:-$HOME/.config}/vellum"
+    local env_file="$env_dir/env"
+    mkdir -p "$env_dir"
+    cat > "$env_file" <<'ENVEOF'
+export BUN_INSTALL="$HOME/.bun"
+case ":$PATH:" in
+  *":$BUN_INSTALL/bin:"*) ;;
+  *) export PATH="$BUN_INSTALL/bin:$PATH" ;;
+esac
+ENVEOF
+}
+
 install_vellum() {
     if command -v vellum >/dev/null 2>&1; then
         info "Updating vellum to latest..."
@@ -103,7 +209,20 @@ main() {
 
     ensure_git
     ensure_bun
+    configure_shell_profile
     install_vellum
+    symlink_vellum
+
+    # Write a sourceable env file so the quickstart one-liner can pick up
+    # PATH changes in the caller's shell:
+    #   curl ... | bash && . ~/.config/vellum/env
+    write_env_file
+
+    # Source the shell profile so vellum hatch runs with the correct PATH
+    # in this session (the profile changes only take effect in new shells
+    # otherwise).
+    export BUN_INSTALL="$HOME/.bun"
+    export PATH="$BUN_INSTALL/bin:$PATH"
 
     info "Running vellum hatch..."
     printf "\n"

package/src/commands/hatch.ts

@@ -13,6 +13,7 @@ import { loadAllAssistants, saveAssistantEntry, syncConfigToLockfile } from "../
 import type { AssistantEntry } from "../lib/assistant-config";
 import { hatchAws } from "../lib/aws";
 import {
+  GATEWAY_PORT,
   SPECIES_CONFIG,
   VALID_REMOTE_HOSTS,
   VALID_SPECIES,
@@ -21,6 +22,7 @@ import type { RemoteHost, Species } from "../lib/constants";
 import { hatchGcp } from "../lib/gcp";
 import type { PollResult, WatchHatchingResult } from "../lib/gcp";
 import { startLocalDaemon, startGateway, stopLocalProcesses } from "../lib/local";
+import { probePort } from "../lib/port-probe";
 import { isProcessAlive } from "../lib/process";
 import { generateRandomSuffix } from "../lib/random-name";
 import { validateAssistantName } from "../lib/retire-archive";
@@ -155,7 +157,22 @@ function parseArgs(): HatchArgs {
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
-    if (arg === "-d") {
+    if (arg === "--help" || arg === "-h") {
+      console.log("Usage: vellum hatch [species] [options]");
+      console.log("");
+      console.log("Create a new assistant instance.");
+      console.log("");
+      console.log("Species:");
+      console.log("  vellum       Default assistant (default)");
+      console.log("  openclaw     OpenClaw adapter");
+      console.log("");
+      console.log("Options:");
+      console.log("  -d                        Run in detached mode");
+      console.log("  --name <name>             Custom instance name");
+      console.log("  --remote <host>           Remote host (local, gcp, aws, custom)");
+      console.log("  --daemon-only             Start daemon only, skip gateway");
+      process.exit(0);
+    } else if (arg === "-d") {
       detached = true;
     } else if (arg === "--daemon-only") {
       daemonOnly = true;
@@ -496,6 +513,8 @@ async function displayPairingQRCode(runtimeUrl: string, bearerToken: string | un
     });
 
     if (!registerRes.ok) {
+      const body = await registerRes.text().catch(() => "");
+      console.warn(`⚠ Could not register pairing request: ${registerRes.status} ${registerRes.statusText}${body ? ` — ${body}` : ""}. Run \`vellum pair\` to try again.\n`);
       return;
     }
 
@@ -519,8 +538,10 @@ async function displayPairingQRCode(runtimeUrl: string, bearerToken: string | un
     console.log(qrString);
     console.log("This pairing request expires in 5 minutes.");
     console.log("Run `vellum pair` to generate a new one.\n");
-  } catch {
+  } catch (err) {
     // Non-fatal — pairing is optional
+    const reason = err instanceof Error ? err.message : String(err);
+    console.warn(`⚠ Could not generate pairing QR code: ${reason}. Run \`vellum pair\` to try again.\n`);
   }
 }
 
@@ -540,6 +561,32 @@ async function hatchLocal(species: Species, name: string | null, daemonOnly: boo
       console.log("🧹 Cleaning up stale local processes (no lock file entry)...\n");
       await stopLocalProcesses();
     }
+
+    // Verify required ports are available before starting any services.
+    // Only check when no local assistants exist — if there are existing local
+    // assistants, their daemon/gateway/qdrant legitimately own these ports.
+    const RUNTIME_HTTP_PORT = Number(process.env.RUNTIME_HTTP_PORT) || 7821;
+    const QDRANT_PORT = 6333;
+    const requiredPorts = [
+      { name: "daemon", port: RUNTIME_HTTP_PORT },
+      { name: "gateway", port: GATEWAY_PORT },
+      { name: "qdrant", port: QDRANT_PORT },
+    ];
+    const conflicts: string[] = [];
+    await Promise.all(
+      requiredPorts.map(async ({ name, port }) => {
+        if (await probePort(port)) {
+          conflicts.push(`  - Port ${port} (${name}) is already in use`);
+        }
+      }),
+    );
+    if (conflicts.length > 0) {
+      throw new Error(
+        `Cannot hatch — required ports are already in use:\n${conflicts.join("\n")}\n\n` +
+          "Stop the conflicting processes or use environment variables to configure alternative ports " +
+          "(RUNTIME_HTTP_PORT, GATEWAY_PORT).",
+      );
+    }
   }
 
   const baseDataDir = join(process.env.BASE_DATA_DIR?.trim() || (process.env.HOME ?? userInfo().homedir), ".vellum");

package/src/commands/login.ts

@@ -7,6 +7,17 @@ import {
 
 export async function login(): Promise<void> {
   const args = process.argv.slice(3);
+
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum login --token <session-token>");
+    console.log("");
+    console.log("Log in to the Vellum platform.");
+    console.log("");
+    console.log("Options:");
+    console.log("  --token <token>    Session token from the Vellum platform");
+    process.exit(0);
+  }
+
   let token: string | null = null;
 
   for (let i = 0; i < args.length; i++) {
@@ -43,11 +54,27 @@ export async function login(): Promise<void> {
 }
 
 export async function logout(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum logout");
+    console.log("");
+    console.log("Log out of the Vellum platform and remove the stored session token.");
+    process.exit(0);
+  }
+
   clearPlatformToken();
   console.log("Logged out. Platform token removed.");
 }
 
 export async function whoami(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum whoami");
+    console.log("");
+    console.log("Show the currently logged-in Vellum platform user.");
+    process.exit(0);
+  }
+
   const token = readPlatformToken();
   if (!token) {
     console.error("Not logged in. Run `vellum login --token <token>` first.");

package/src/commands/pair.ts

@@ -72,6 +72,14 @@ async function pollForApproval(
 
 export async function pair(): Promise<void> {
   const args = process.argv.slice(3);
+
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum pair <path-to-qrcode.png>");
+    console.log("");
+    console.log("Pair with a remote assistant by scanning the QR code PNG generated during setup.");
+    process.exit(0);
+  }
+
   const qrCodePath = args[0] || process.env.VELLUM_CUSTOM_QR_CODE_PATH;
 
   if (!qrCodePath) {

package/src/commands/ps.ts

@@ -409,6 +409,17 @@ async function listAllAssistants(): Promise<void> {
 // ── Entry point ─────────────────────────────────────────────────
 
 export async function ps(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum ps [<name>]");
+    console.log("");
+    console.log("List all assistants, or show processes for a specific assistant.");
+    console.log("");
+    console.log("Arguments:");
+    console.log("  <name>    Show processes for the named assistant");
+    process.exit(0);
+  }
+
   const assistantId = process.argv[3];
 
   if (!assistantId) {

package/src/commands/recover.ts

@@ -9,6 +9,17 @@ import { getArchivePath, getMetadataPath } from "../lib/retire-archive";
 import { exec } from "../lib/step-runner";
 
 export async function recover(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum recover <name>");
+    console.log("");
+    console.log("Restore a previously retired local assistant from its archive.");
+    console.log("");
+    console.log("Arguments:");
+    console.log("  <name>    Name of the retired assistant to recover");
+    process.exit(0);
+  }
+
   const name = process.argv[3];
   if (!name) {
     console.error("Usage: vellum recover <name>");

package/src/commands/retire.ts

@@ -121,6 +121,20 @@ function parseSource(): string | undefined {
 }
 
 export async function retire(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum retire <name> [--source <source>]");
+    console.log("");
+    console.log("Delete an assistant instance and archive its data.");
+    console.log("");
+    console.log("Arguments:");
+    console.log("  <name>               Name of the assistant to retire");
+    console.log("");
+    console.log("Options:");
+    console.log("  --source <source>    Source identifier for the retirement");
+    process.exit(0);
+  }
+
   const name = process.argv[3];
 
   if (!name) {

package/src/commands/sleep.ts

@@ -5,6 +5,14 @@ import { loadAllAssistants } from "../lib/assistant-config";
 import { stopProcessByPidFile } from "../lib/process";
 
 export async function sleep(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum sleep");
+    console.log("");
+    console.log("Stop the daemon and gateway processes.");
+    process.exit(0);
+  }
+
   const assistants = loadAllAssistants();
   const hasLocal = assistants.some((a) => a.cloud === "local");
   if (!hasLocal) {

package/src/commands/ssh.ts

@@ -33,6 +33,17 @@ function extractHostFromUrl(url: string): string {
 }
 
 export async function ssh(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum ssh [<name>]");
+    console.log("");
+    console.log("SSH into a remote assistant instance.");
+    console.log("");
+    console.log("Arguments:");
+    console.log("  <name>    Name of the assistant to connect to (defaults to latest)");
+    process.exit(0);
+  }
+
   const name = process.argv[3];
   const entry = name ? findAssistantByName(name) : loadLatestAssistant();
 

package/src/commands/wake.ts

@@ -7,6 +7,14 @@ import { isProcessAlive } from "../lib/process";
 import { startLocalDaemon, startGateway } from "../lib/local";
 
 export async function wake(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum wake");
+    console.log("");
+    console.log("Start the daemon and gateway processes.");
+    process.exit(0);
+  }
+
   const assistants = loadAllAssistants();
   const hasLocal = assistants.some((a) => a.cloud === "local");
   if (!hasLocal) {

package/src/components/DefaultMainScreen.tsx

@@ -32,6 +32,51 @@ const POLL_INTERVAL_MS = 3000;
 const SEND_TIMEOUT_MS = 5000;
 const RESPONSE_POLL_INTERVAL_MS = 1000;
 
+// ── Layout constants ──────────────────────────────────────
+const MAX_TOTAL_WIDTH = 72;
+const DEFAULT_TERMINAL_COLUMNS = 80;
+const DEFAULT_TERMINAL_ROWS = 24;
+const LEFT_PANEL_WIDTH = 36;
+
+const HEADER_PREFIX = "── Vellum ";
+
+// Left panel structure: HEADER lines + art + FOOTER lines
+const LEFT_HEADER_LINES = 3; // spacer + heading + spacer
+const LEFT_FOOTER_LINES = 3; // spacer + runtimeUrl + dirName
+
+// Right panel structure
+const TIPS = ["Send a message to start chatting", "Use /help to see available commands"];
+const RIGHT_PANEL_INFO_SECTIONS = 3; // Assistant, Species, Status — each with heading + value
+const RIGHT_PANEL_SPACERS = 2; // top spacer + spacer between tips and info
+const RIGHT_PANEL_TIPS_HEADING = 1;
+const RIGHT_PANEL_LINE_COUNT =
+  RIGHT_PANEL_SPACERS + RIGHT_PANEL_TIPS_HEADING + TIPS.length + RIGHT_PANEL_INFO_SECTIONS * 2;
+
+// Header chrome (borders around panel content)
+const HEADER_TOP_BORDER_LINES = 1; // "── Vellum ───..." line
+const HEADER_BOTTOM_BORDER_LINES = 2; // bottom rule + blank line
+const HEADER_CHROME_LINES = HEADER_TOP_BORDER_LINES + HEADER_BOTTOM_BORDER_LINES;
+
+// Selection / Secret windows
+const DIALOG_WINDOW_WIDTH = 60;
+const DIALOG_TITLE_CHROME = 5; // "┌─ " (3) + " " (1) + "┐" (1)
+const DIALOG_BORDER_CORNERS = 2; // └ and ┘
+const SELECTION_OPTION_CHROME = 6; // "│ " (2) + marker (1) + " " (1) + padding‐adjust + "│" (1)
+const SECRET_CONTENT_CHROME = 4; // "│ " (2) + padding + "│" (1) + adjustment
+
+// Chat area heights
+const TOOLTIP_HEIGHT = 3;
+const INPUT_AREA_HEIGHT = 4; // separator + input row + separator + hint
+const SELECTION_CHROME_LINES = 3; // title bar + bottom border + spacing
+const SECRET_INPUT_HEIGHT = 5; // title bar + content row + bottom border + tooltip chrome
+const SPINNER_HEIGHT = 1;
+const MIN_FEED_ROWS = 3;
+
+// Feed item height estimation
+const TOOL_CALL_CHROME_LINES = 2; // header (┌) + footer (└)
+const MESSAGE_SPACING = 1;
+const HELP_DISPLAY_HEIGHT = 6;
+
 interface ListMessagesResponse {
   messages: RuntimeMessage[];
   nextCursor?: string;
@@ -598,12 +643,10 @@ function DefaultMainScreen({
   const accentColor = species === "openclaw" ? "red" : "magenta";
 
   const { stdout } = useStdout();
-  const terminalColumns = stdout.columns || 80;
-  const totalWidth = Math.min(72, terminalColumns);
+  const terminalColumns = stdout.columns || DEFAULT_TERMINAL_COLUMNS;
+  const totalWidth = Math.min(MAX_TOTAL_WIDTH, terminalColumns);
   const rightPanelWidth = Math.max(1, totalWidth - LEFT_PANEL_WIDTH);
 
-  const tips = ["Send a message to start chatting", "Use /help to see available commands"];
-
   const leftLines = [
     " ",
     "    Meet your Assistant!",
@@ -617,7 +660,7 @@ function DefaultMainScreen({
   const rightLines: StyledLine[] = [
     { text: " ", style: "normal" },
     { text: "Tips for getting started", style: "heading" },
-    ...tips.map((t) => ({ text: t, style: "normal" as const })),
+    ...TIPS.map((t) => ({ text: t, style: "normal" as const })),
     { text: " ", style: "normal" },
     { text: "Assistant", style: "heading" },
     { text: assistantId, style: "dim" },
@@ -631,7 +674,7 @@ function DefaultMainScreen({
 
   return (
     <Box flexDirection="column" width={totalWidth}>
-      <Text dimColor>{"── Vellum " + "─".repeat(Math.max(0, totalWidth - 10))}</Text>
+      <Text dimColor>{HEADER_PREFIX + "─".repeat(Math.max(0, totalWidth - HEADER_PREFIX.length))}</Text>
       <Box flexDirection="row">
         <Box flexDirection="column" width={LEFT_PANEL_WIDTH}>
           {Array.from({ length: maxLines }, (_, i) => {
@@ -684,15 +727,10 @@ function DefaultMainScreen({
       </Box>
       <Text dimColor>{"─".repeat(totalWidth)}</Text>
       <Text> </Text>
-      <Tooltip text="Type ? or /help for available commands" delay={1000}>
-        <Text dimColor> ? for shortcuts</Text>
-      </Tooltip>
-      <Text> </Text>
     </Box>
   );
 }
 
-const LEFT_PANEL_WIDTH = 36;
 
 export interface SelectionRequest {
   title: string;
@@ -737,13 +775,21 @@ function estimateItemHeight(item: FeedItem, terminalColumns: number): number {
       for (const tc of item.toolCalls) {
         const paramCount =
           typeof tc.input === "object" && tc.input ? Object.keys(tc.input).length : 0;
-        lines += 2 + paramCount + (tc.result !== undefined ? 1 : 0);
+        lines += TOOL_CALL_CHROME_LINES + paramCount + (tc.result !== undefined ? 1 : 0);
       }
     }
-    return lines + 1;
+    return lines + MESSAGE_SPACING;
   }
   if (item.type === "help") {
-    return 6;
+    return HELP_DISPLAY_HEIGHT;
+  }
+  if (item.type === "status" || item.type === "error") {
+    const cols = Math.max(1, terminalColumns);
+    let lines = 0;
+    for (const line of item.text.split("\n")) {
+      lines += Math.max(1, Math.ceil(line.length / cols));
+    }
+    return lines;
   }
   return 1;
 }
@@ -751,10 +797,9 @@ function estimateItemHeight(item: FeedItem, terminalColumns: number): number {
 function calculateHeaderHeight(species: Species): number {
   const config = SPECIES_CONFIG[species];
   const artLength = config.art.length;
-  const leftLineCount = 3 + artLength + 3;
-  const rightLineCount = 11;
-  const maxLines = Math.max(leftLineCount, rightLineCount);
-  return maxLines + 5;
+  const leftLineCount = LEFT_HEADER_LINES + artLength + LEFT_FOOTER_LINES;
+  const maxLines = Math.max(leftLineCount, RIGHT_PANEL_LINE_COUNT);
+  return maxLines + HEADER_CHROME_LINES;
 }
 
 const SCROLL_STEP = 5;
@@ -763,9 +808,8 @@ export function render(runtimeUrl: string, assistantId: string, species: Species
   const config = SPECIES_CONFIG[species];
   const art = config.art;
 
-  const leftLineCount = 3 + art.length + 3;
-  const rightLineCount = 11;
-  const maxLines = Math.max(leftLineCount, rightLineCount);
+  const leftLineCount = LEFT_HEADER_LINES + art.length + LEFT_FOOTER_LINES;
+  const maxLines = Math.max(leftLineCount, RIGHT_PANEL_LINE_COUNT);
 
   const { unmount } = inkRender(
     <DefaultMainScreen runtimeUrl={runtimeUrl} assistantId={assistantId} species={species} />,
@@ -773,7 +817,7 @@ export function render(runtimeUrl: string, assistantId: string, species: Species
   );
   unmount();
 
-  const statusCanvasLine = rightLineCount + 1;
+  const statusCanvasLine = RIGHT_PANEL_LINE_COUNT + HEADER_TOP_BORDER_LINES;
   const statusCol = LEFT_PANEL_WIDTH + 1;
   checkHealth(runtimeUrl)
     .then((health) => {
@@ -784,7 +828,7 @@ export function render(runtimeUrl: string, assistantId: string, species: Species
     })
     .catch(() => {});
 
-  return 1 + maxLines + 4;
+  return maxLines + HEADER_CHROME_LINES;
 }
 
 interface SelectionWindowProps {
@@ -825,15 +869,14 @@ function SelectionWindow({
     },
   );
 
-  const windowWidth = 60;
-  const borderH = "\u2500".repeat(Math.max(0, windowWidth - title.length - 5));
+  const borderH = "\u2500".repeat(Math.max(0, DIALOG_WINDOW_WIDTH - title.length - DIALOG_TITLE_CHROME));
 
   return (
-    <Box flexDirection="column" width={windowWidth}>
+    <Box flexDirection="column" width={DIALOG_WINDOW_WIDTH}>
       <Text>{"\u250C\u2500 " + title + " " + borderH + "\u2510"}</Text>
       {options.map((option, i) => {
         const marker = i === selectedIndex ? "\u276F" : " ";
-        const padding = " ".repeat(Math.max(0, windowWidth - option.length - 6));
+        const padding = " ".repeat(Math.max(0, DIALOG_WINDOW_WIDTH - option.length - SELECTION_OPTION_CHROME));
         return (
           <Text key={i}>
             {"\u2502 "}
@@ -844,7 +887,7 @@ function SelectionWindow({
           </Text>
         );
       })}
-      <Text>{"\u2514" + "\u2500".repeat(windowWidth - 2) + "\u2518"}</Text>
+      <Text>{"\u2514" + "\u2500".repeat(DIALOG_WINDOW_WIDTH - DIALOG_BORDER_CORNERS) + "\u2518"}</Text>
       <Tooltip text="\u2191/\u2193 navigate  Enter select  Esc cancel" delay={1000} />
     </Box>
   );
@@ -888,15 +931,14 @@ function SecretInputWindow({
     },
   );
 
-  const windowWidth = 60;
-  const borderH = "\u2500".repeat(Math.max(0, windowWidth - label.length - 5));
+  const borderH = "\u2500".repeat(Math.max(0, DIALOG_WINDOW_WIDTH - label.length - DIALOG_TITLE_CHROME));
   const masked = "\u2022".repeat(value.length);
   const displayText = value.length > 0 ? masked : (placeholder ?? "Enter secret...");
   const displayColor = value.length > 0 ? undefined : "gray";
-  const contentPad = " ".repeat(Math.max(0, windowWidth - displayText.length - 4));
+  const contentPad = " ".repeat(Math.max(0, DIALOG_WINDOW_WIDTH - displayText.length - SECRET_CONTENT_CHROME));
 
   return (
-    <Box flexDirection="column" width={windowWidth}>
+    <Box flexDirection="column" width={DIALOG_WINDOW_WIDTH}>
       <Text>{"\u250C\u2500 " + label + " " + borderH + "\u2510"}</Text>
       <Text>
         {"\u2502 "}
@@ -904,7 +946,7 @@ function SecretInputWindow({
         {contentPad}
         {"\u2502"}
       </Text>
-      <Text>{"\u2514" + "\u2500".repeat(windowWidth - 2) + "\u2518"}</Text>
+      <Text>{"\u2514" + "\u2500".repeat(DIALOG_WINDOW_WIDTH - DIALOG_BORDER_CORNERS) + "\u2518"}</Text>
       <Tooltip text="Enter submit  Esc cancel" delay={1000} />
     </Box>
   );
@@ -985,20 +1027,18 @@ function ChatApp({
   const handleRef_ = useRef<ChatAppHandle | null>(null);
 
   const { stdout } = useStdout();
-  const terminalRows = stdout.rows || 24;
-  const terminalColumns = stdout.columns || 80;
+  const terminalRows = stdout.rows || DEFAULT_TERMINAL_ROWS;
+  const terminalColumns = stdout.columns || DEFAULT_TERMINAL_COLUMNS;
   const headerHeight = calculateHeaderHeight(species);
-  const tooltipBubbleHeight = 3;
-  const showTooltip = inputFocused && inputValue.length === 0;
-  const tooltipHeight = showTooltip ? tooltipBubbleHeight : 0;
+
   const bottomHeight = selection
-    ? selection.options.length + 3 + tooltipBubbleHeight
+    ? selection.options.length + SELECTION_CHROME_LINES + TOOLTIP_HEIGHT
     : secretInput
-      ? 5 + tooltipBubbleHeight
+      ? SECRET_INPUT_HEIGHT + TOOLTIP_HEIGHT
       : spinnerText
-        ? 4
-        : 3 + tooltipHeight;
-  const availableRows = Math.max(3, terminalRows - headerHeight - bottomHeight);
+        ? SPINNER_HEIGHT + INPUT_AREA_HEIGHT
+        : INPUT_AREA_HEIGHT;
+  const availableRows = Math.max(MIN_FEED_ROWS, terminalRows - headerHeight - bottomHeight);
 
   const addMessage = useCallback((msg: RuntimeMessage) => {
     setFeed((prev) => [...prev, msg]);
@@ -1823,12 +1863,6 @@ function ChatApp({
 
       {!selection && !secretInput ? (
         <Box flexDirection="column">
-          <Tooltip
-            text="Type a message or /help for commands"
-            visible={inputFocused && inputValue.length === 0}
-            position="above"
-            delay={1000}
-          />
           <Text dimColor>{"\u2500".repeat(terminalColumns)}</Text>
           <Box paddingLeft={1}>
             <Text color="green" bold>
@@ -1843,6 +1877,7 @@ function ChatApp({
           />
           </Box>
           <Text dimColor>{"\u2500".repeat(terminalColumns)}</Text>
+          <Text dimColor> ? for shortcuts</Text>
         </Box>
       ) : null}
     </Box>

package/src/index.ts

@@ -31,8 +31,8 @@ const commands = {
   email,
   hatch,
   login,
-  pair,
   logout,
+  pair,
   ps,
   recover,
   retire,
@@ -90,9 +90,9 @@ async function main() {
     console.log("  contacts Manage the contact graph");
     console.log("  email    Email operations (status, create inbox)");
     console.log("  hatch    Create a new assistant instance");
-    console.log("  pair     Pair with a remote assistant via QR code");
     console.log("  login    Log in to the Vellum platform");
     console.log("  logout   Log out of the Vellum platform");
+    console.log("  pair     Pair with a remote assistant via QR code");
     console.log("  ps       List assistants (or processes for a specific assistant)");
     console.log("  recover  Restore a previously retired local assistant");
     console.log("  retire   Delete an assistant instance");

package/src/lib/local.ts

@@ -557,8 +557,35 @@ export async function startGateway(assistantId?: string): Promise<string> {
     writeFileSync(join(vellumDir, "gateway.pid"), String(gateway.pid), "utf-8");
   }
 
+  const gatewayUrl = publicUrl || `http://localhost:${GATEWAY_PORT}`;
+
+  // Wait for the gateway to be responsive before returning. Without this,
+  // callers (e.g. displayPairingQRCode) may try to connect before the HTTP
+  // server is listening and get connection-refused errors.
+  const start = Date.now();
+  const timeoutMs = 30000;
+  let ready = false;
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch(`http://localhost:${GATEWAY_PORT}/healthz`, {
+        signal: AbortSignal.timeout(2000),
+      });
+      if (res.ok) {
+        ready = true;
+        break;
+      }
+    } catch {
+      // Gateway not ready yet
+    }
+    await new Promise((r) => setTimeout(r, 250));
+  }
+
+  if (!ready) {
+    console.warn("⚠ Gateway started but health check did not respond within 30s");
+  }
+
   console.log("✅ Gateway started\n");
-  return publicUrl || `http://localhost:${GATEWAY_PORT}`;
+  return gatewayUrl;
 }
 
 /**