fix: add TTY detection before TUI fallbacks to prevent agent/CI hangs (#949)

jesseturner21 · web-flow · commit c30ed548a52c · 2026-04-24T15:10:29.000-04:00
* fix: add TTY detection before TUI fallbacks to prevent agent/CI hangs When commands are invoked without flags in non-interactive environments (CI, piped stdin, agent automation), the CLI falls through to Ink TUI rendering which hangs indefinitely. Add a requireTTY() guard at every TUI entry point that checks process.stdout.isTTY and exits with a helpful error message directing users to --help for non-interactive flags. Closes #685 * fix: check both stdin and stdout isTTY in requireTTY guard The hang from #685 is caused by stdin not being a TTY (Ink reads keyboard input from stdin), not stdout. Check both stdin and stdout so the guard fires for piped stdin, redirected stdout, and CI environments where both are non-TTY.
diff --git a/src/cli/cli.ts b/src/cli/cli.ts
@@ -26,6 +26,7 @@ import { LayoutProvider } from './tui/context';
 import { COMMAND_DESCRIPTIONS } from './tui/copy';
 import { clearExitAction, getExitAction } from './tui/exit-action';
 import { clearExitMessage, getExitMessage } from './tui/exit-message';
+import { requireTTY } from './tui/guards';
 import { CommandListScreen } from './tui/screens/home';
 import { getCommandsForUI } from './tui/utils';
 import { type UpdateCheckResult, checkForUpdate, printUpdateNotification } from './update-notifier';
@@ -212,6 +213,7 @@ export const main = async (argv: string[]) => {
 
   // Show TUI for no arguments, commander handles --help via configureHelp()
   if (args.length === 0) {
+    requireTTY();
     renderTUI(updateCheck, isFirstRun);
     return;
   }
diff --git a/src/cli/commands/add/command.tsx b/src/cli/commands/add/command.tsx
@@ -1,5 +1,5 @@
 import { COMMAND_DESCRIPTIONS } from '../../tui/copy';
-import { requireProject } from '../../tui/guards';
+import { requireProject, requireTTY } from '../../tui/guards';
 import { AddFlow } from '../../tui/screens/add/AddFlow';
 import type { Command } from '@commander-js/extra-typings';
 import { render } from 'ink';
@@ -21,6 +21,7 @@ export function registerAdd(program: Command): Command {
     }
 
     requireProject();
+    requireTTY();
 
     const { clear, unmount } = render(
       <AddFlow
diff --git a/src/cli/commands/create/command.tsx b/src/cli/commands/create/command.tsx
@@ -10,6 +10,7 @@ import type {
 import { LIFECYCLE_TIMEOUT_MAX, LIFECYCLE_TIMEOUT_MIN } from '../../../schema';
 import { getErrorMessage } from '../../errors';
 import { COMMAND_DESCRIPTIONS } from '../../tui/copy';
+import { requireTTY } from '../../tui/guards';
 import { CreateScreen } from '../../tui/screens/create';
 import { parseCommaSeparatedList } from '../shared/vpc-utils';
 import { type ProgressCallback, createProject, createProjectWithAgent, getDryRunInfo } from './action';
@@ -245,6 +246,7 @@ export const registerCreate = (program: Command) => {
           options.language = options.language ?? 'Python';
           await handleCreateCLI(options as CreateOptions);
         } else {
+          requireTTY();
           handleCreateTUI();
         }
       } catch (error) {
diff --git a/src/cli/commands/deploy/command.tsx b/src/cli/commands/deploy/command.tsx
@@ -1,6 +1,6 @@
 import { getErrorMessage } from '../../errors';
 import { COMMAND_DESCRIPTIONS } from '../../tui/copy';
-import { requireProject } from '../../tui/guards';
+import { requireProject, requireTTY } from '../../tui/guards';
 import { DeployScreen } from '../../tui/screens/deploy/DeployScreen';
 import { handleDeploy } from './actions';
 import type { DeployOptions } from './types';
@@ -160,8 +160,10 @@ export const registerDeploy = (program: Command) => {
             await handleDeployCLI(options as DeployOptions);
           } else if (cliOptions.diff) {
             // Diff-only: use TUI with diff mode
+            requireTTY();
             handleDeployTUI({ diffMode: true });
           } else {
+            requireTTY();
             handleDeployTUI();
           }
         } catch (error) {
diff --git a/src/cli/commands/dev/command.tsx b/src/cli/commands/dev/command.tsx
@@ -21,7 +21,7 @@ import { OtelCollector, startOtelCollector } from '../../operations/dev/otel';
 import { FatalError } from '../../tui/components';
 import { LayoutProvider } from '../../tui/context';
 import { COMMAND_DESCRIPTIONS } from '../../tui/copy';
-import { requireProject } from '../../tui/guards';
+import { requireProject, requireTTY } from '../../tui/guards';
 import { parseHeaderFlags } from '../shared/header-utils';
 import { runBrowserMode } from './browser-mode';
 import type { Command } from '@commander-js/extra-typings';
@@ -383,6 +383,7 @@ export const registerDev = (program: Command) => {
 
         // If --no-browser provided, launch terminal TUI mode
         if (!opts.browser) {
+          requireTTY();
           // Enter alternate screen buffer for fullscreen mode
           process.stdout.write(ENTER_ALT_SCREEN);
 
diff --git a/src/cli/commands/invoke/command.tsx b/src/cli/commands/invoke/command.tsx
@@ -1,6 +1,6 @@
 import { getErrorMessage } from '../../errors';
 import { COMMAND_DESCRIPTIONS } from '../../tui/copy';
-import { requireProject } from '../../tui/guards';
+import { requireProject, requireTTY } from '../../tui/guards';
 import { InvokeScreen } from '../../tui/screens/invoke';
 import { parseHeaderFlags } from '../shared/header-utils';
 import { handleInvoke, loadInvokeConfig } from './action';
@@ -168,6 +168,7 @@ export const registerInvoke = (program: Command) => {
             });
           } else {
             // No CLI options - interactive TUI mode (headers still passed if provided)
+            requireTTY();
             const { waitUntilExit, unmount } = render(
               <InvokeScreen
                 isInteractive={true}
diff --git a/src/cli/commands/remove/command.tsx b/src/cli/commands/remove/command.tsx
@@ -1,7 +1,7 @@
 import { ConfigIO } from '../../../lib';
 import { getErrorMessage } from '../../errors';
 import { COMMAND_DESCRIPTIONS } from '../../tui/copy';
-import { requireProject } from '../../tui/guards';
+import { requireProject, requireTTY } from '../../tui/guards';
 import { RemoveAllScreen, RemoveFlow } from '../../tui/screens/remove';
 import type { RemoveAllOptions, RemoveResult } from './types';
 import { validateRemoveAllOptions } from './validate';
@@ -76,6 +76,7 @@ export const registerRemove = (program: Command): Command => {
             json: cliOptions.json,
           });
         } else {
+          requireTTY();
           const { unmount } = render(
             <RemoveAllScreen
               isInteractive={false}
@@ -112,6 +113,7 @@ export const registerRemove = (program: Command): Command => {
       }
 
       requireProject();
+      requireTTY();
 
       const { clear, unmount } = render(
         <RemoveFlow
diff --git a/src/cli/primitives/AgentPrimitive.tsx b/src/cli/primitives/AgentPrimitive.tsx
@@ -35,6 +35,7 @@ import { executeImportAgent } from '../operations/agent/import';
 import { setupPythonProject } from '../operations/python';
 import type { RemovalPreview, RemovalResult, SchemaChange } from '../operations/remove/types';
 import { createRenderer } from '../templates';
+import { requireTTY } from '../tui/guards/tty';
 import type { GenerateConfig, MemoryOption } from '../tui/screens/generate/types';
 import { BasePrimitive } from './BasePrimitive';
 import { CredentialPrimitive } from './CredentialPrimitive';
@@ -332,6 +333,7 @@ export class AgentPrimitive extends BasePrimitive<AddAgentOptions, RemovableReso
           process.exit(result.success ? 0 : 1);
         } else {
           // TUI fallback — dynamic imports to avoid pulling ink (async) into registry
+          requireTTY();
           const [{ render }, { default: React }, { AddFlow }] = await Promise.all([
             import('ink'),
             import('react'),
diff --git a/src/cli/primitives/BasePrimitive.ts b/src/cli/primitives/BasePrimitive.ts
@@ -2,6 +2,7 @@ import { ConfigIO, findConfigRoot } from '../../lib';
 import type { AgentCoreProjectSpec } from '../../schema';
 import type { ResourceType } from '../commands/remove/types';
 import { getErrorMessage } from '../errors';
+import { requireTTY } from '../tui/guards/tty';
 import { SOURCE_CODE_NOTE } from './constants';
 import type { AddResult, AddScreenComponent, RemovableResource, RemovalPreview, RemovalResult } from './types';
 import type { Command } from '@commander-js/extra-typings';
@@ -133,6 +134,7 @@ export abstract class BasePrimitive<
             process.exit(result.success ? 0 : 1);
           } else {
             // TUI fallback — dynamic imports to avoid pulling ink (async) into registry
+            requireTTY();
             const [{ render }, { default: React }, { RemoveFlow }] = await Promise.all([
               import('ink'),
               import('react'),
diff --git a/src/cli/primitives/CredentialPrimitive.tsx b/src/cli/primitives/CredentialPrimitive.tsx
@@ -4,6 +4,7 @@ import { CredentialSchema } from '../../schema';
 import { validateAddCredentialOptions } from '../commands/add/validate';
 import { getErrorMessage } from '../errors';
 import type { RemovalPreview, RemovalResult, SchemaChange } from '../operations/remove/types';
+import { requireTTY } from '../tui/guards/tty';
 import { BasePrimitive } from './BasePrimitive';
 import { computeDefaultCredentialEnvVarName } from './credential-utils';
 import type { AddResult, AddScreenComponent, RemovableResource } from './types';
@@ -339,6 +340,7 @@ export class CredentialPrimitive extends BasePrimitive<AddCredentialOptions, Rem
               process.exit(result.success ? 0 : 1);
             } else {
               // TUI fallback — dynamic imports to avoid pulling ink (async) into registry
+              requireTTY();
               const [{ render }, { default: React }, { AddFlow }] = await Promise.all([
                 import('ink'),
                 import('react'),
diff --git a/src/cli/primitives/EvaluatorPrimitive.ts b/src/cli/primitives/EvaluatorPrimitive.ts
@@ -4,6 +4,7 @@ import { EvaluationLevelSchema, EvaluatorSchema } from '../../schema';
 import { getErrorMessage } from '../errors';
 import type { RemovalPreview, RemovalResult, SchemaChange } from '../operations/remove/types';
 import { renderCodeBasedEvaluatorTemplate } from '../templates/EvaluatorRenderer';
+import { requireTTY } from '../tui/guards/tty';
 import {
   LEVEL_PLACEHOLDERS,
   RATING_SCALE_PRESETS,
@@ -316,6 +317,7 @@ export class EvaluatorPrimitive extends BasePrimitive<AddEvaluatorOptions, Remov
               process.exit(result.success ? 0 : 1);
             } else {
               // TUI fallback
+              requireTTY();
               const [{ render }, { default: React }, { AddFlow }] = await Promise.all([
                 import('ink'),
                 import('react'),
diff --git a/src/cli/primitives/GatewayPrimitive.ts b/src/cli/primitives/GatewayPrimitive.ts
@@ -12,6 +12,7 @@ import type { AddGatewayOptions as CLIAddGatewayOptions } from '../commands/add/
 import { validateAddGatewayOptions } from '../commands/add/validate';
 import { getErrorMessage } from '../errors';
 import type { RemovalPreview, RemovalResult, SchemaChange } from '../operations/remove/types';
+import { requireTTY } from '../tui/guards/tty';
 import type { AddGatewayConfig } from '../tui/screens/mcp/types';
 import { BasePrimitive } from './BasePrimitive';
 import { buildAuthorizerConfigFromJwtConfig, createManagedOAuthCredential } from './auth-utils';
@@ -271,6 +272,7 @@ export class GatewayPrimitive extends BasePrimitive<AddGatewayOptions, Removable
             );
             process.exit(result.success ? 0 : 1);
           } else {
+            requireTTY();
             const [{ render }, { default: React }, { RemoveFlow }] = await Promise.all([
               import('ink'),
               import('react'),
diff --git a/src/cli/primitives/GatewayTargetPrimitive.ts b/src/cli/primitives/GatewayTargetPrimitive.ts
@@ -15,6 +15,7 @@ import { getErrorMessage } from '../errors';
 import type { RemovableGatewayTarget } from '../operations/remove/remove-gateway-target';
 import type { RemovalPreview, RemovalResult, SchemaChange } from '../operations/remove/types';
 import { getTemplateToolDefinitions, renderGatewayTargetTemplate } from '../templates/GatewayTargetRenderer';
+import { requireTTY } from '../tui/guards/tty';
 import type {
   ApiGatewayTargetConfig,
   GatewayTargetWizardState,
@@ -508,6 +509,7 @@ export class GatewayTargetPrimitive extends BasePrimitive<AddGatewayTargetOption
             );
             process.exit(result.success ? 0 : 1);
           } else {
+            requireTTY();
             const [{ render }, { default: React }, { RemoveFlow }] = await Promise.all([
               import('ink'),
               import('react'),
diff --git a/src/cli/primitives/MemoryPrimitive.tsx b/src/cli/primitives/MemoryPrimitive.tsx
@@ -17,6 +17,7 @@ import {
 import { DEFAULT_DELIVERY_TYPE, validateAddMemoryOptions } from '../commands/add/validate';
 import { getErrorMessage } from '../errors';
 import type { RemovalPreview, RemovalResult, SchemaChange } from '../operations/remove/types';
+import { requireTTY } from '../tui/guards/tty';
 import { DEFAULT_EVENT_EXPIRY } from '../tui/screens/memory/types';
 import { BasePrimitive } from './BasePrimitive';
 import type { AddResult, AddScreenComponent, RemovableResource } from './types';
@@ -230,6 +231,7 @@ export class MemoryPrimitive extends BasePrimitive<AddMemoryOptions, RemovableMe
               process.exit(result.success ? 0 : 1);
             } else {
               // TUI fallback — dynamic imports to avoid pulling ink (async) into registry
+              requireTTY();
               const [{ render }, { default: React }, { AddFlow }] = await Promise.all([
                 import('ink'),
                 import('react'),
diff --git a/src/cli/primitives/OnlineEvalConfigPrimitive.ts b/src/cli/primitives/OnlineEvalConfigPrimitive.ts
@@ -3,6 +3,7 @@ import type { OnlineEvalConfig } from '../../schema';
 import { OnlineEvalConfigSchema } from '../../schema';
 import { getErrorMessage } from '../errors';
 import type { RemovalPreview, RemovalResult, SchemaChange } from '../operations/remove/types';
+import { requireTTY } from '../tui/guards/tty';
 import { BasePrimitive } from './BasePrimitive';
 import type { AddResult, AddScreenComponent, RemovableResource } from './types';
 import type { Command } from '@commander-js/extra-typings';
@@ -171,6 +172,7 @@ export class OnlineEvalConfigPrimitive extends BasePrimitive<AddOnlineEvalConfig
               process.exit(result.success ? 0 : 1);
             } else {
               // TUI fallback
+              requireTTY();
               const [{ render }, { default: React }, { AddFlow }] = await Promise.all([
                 import('ink'),
                 import('react'),
diff --git a/src/cli/primitives/PolicyEnginePrimitive.ts b/src/cli/primitives/PolicyEnginePrimitive.ts
@@ -3,6 +3,7 @@ import type { AgentCoreProjectSpec, PolicyEngine } from '../../schema';
 import { PolicyEngineModeSchema, PolicyEngineSchema } from '../../schema';
 import { getErrorMessage } from '../errors';
 import type { RemovalPreview, RemovalResult, SchemaChange } from '../operations/remove/types';
+import { requireTTY } from '../tui/guards/tty';
 import { BasePrimitive } from './BasePrimitive';
 import { SOURCE_CODE_NOTE } from './constants';
 import type { AddResult, AddScreenComponent, RemovableResource } from './types';
@@ -261,6 +262,7 @@ export class PolicyEnginePrimitive extends BasePrimitive<AddPolicyEngineOptions,
               }
               process.exit(result.success ? 0 : 1);
             } else {
+              requireTTY();
               const [{ render }, { default: React }, { AddFlow }] = await Promise.all([
                 import('ink'),
                 import('react'),
@@ -326,6 +328,7 @@ export class PolicyEnginePrimitive extends BasePrimitive<AddPolicyEngineOptions,
             }
             process.exit(result.success ? 0 : 1);
           } else {
+            requireTTY();
             const [{ render }, { default: React }, { RemoveFlow }] = await Promise.all([
               import('ink'),
               import('react'),
diff --git a/src/cli/primitives/PolicyPrimitive.ts b/src/cli/primitives/PolicyPrimitive.ts
@@ -5,6 +5,7 @@ import { detectRegion } from '../aws';
 import { getPolicyGeneration, startPolicyGeneration } from '../aws/policy-generation';
 import { getErrorMessage } from '../errors';
 import type { RemovalPreview, RemovalResult, SchemaChange } from '../operations/remove/types';
+import { requireTTY } from '../tui/guards/tty';
 import { BasePrimitive } from './BasePrimitive';
 import { SOURCE_CODE_NOTE } from './constants';
 import type { AddResult, AddScreenComponent, RemovableResource } from './types';
@@ -343,6 +344,7 @@ export class PolicyPrimitive extends BasePrimitive<AddPolicyOptions, RemovablePo
               }
               process.exit(result.success ? 0 : 1);
             } else {
+              requireTTY();
               const [{ render }, { default: React }, { AddFlow }] = await Promise.all([
                 import('ink'),
                 import('react'),
@@ -417,6 +419,7 @@ export class PolicyPrimitive extends BasePrimitive<AddPolicyOptions, RemovablePo
             }
             process.exit(result.success ? 0 : 1);
           } else {
+            requireTTY();
             const [{ render }, { default: React }, { RemoveFlow }] = await Promise.all([
               import('ink'),
               import('react'),
diff --git a/src/cli/tui/guards/index.ts b/src/cli/tui/guards/index.ts
@@ -5,3 +5,4 @@ export {
   MissingProjectMessage,
   WrongDirectoryMessage,
 } from './project';
+export { requireTTY } from './tty';
diff --git a/src/cli/tui/guards/tty.ts b/src/cli/tui/guards/tty.ts
@@ -0,0 +1,13 @@
+/**
+ * Guard that checks for an interactive terminal and exits if not found.
+ * Prevents TUI flows from hanging in CI, piped stdin, or agent automation.
+ *
+ * Checks both stdin (Ink reads keyboard input) and stdout (Ink renders TUI output).
+ * Either being non-TTY means the TUI cannot function.
+ */
+export function requireTTY(): void {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.error('Error: This command requires an interactive terminal. Use --help to see non-interactive flags.');
+    process.exit(1);
+  }
+}
