fix: skip non-essential health checks for signup and show clear errors on outages (#413)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: MattBro

bin.ts

@@ -510,6 +510,7 @@ function runWizard(
 
       await tui.store.runReadyHooks();
       await tui.store.getGate('intro');
+      await tui.store.getGate('health-check');
 
       const skipAgent = config.run == null;
 

src/lib/agent/agent-runner.ts

@@ -37,6 +37,9 @@ import { getCloudUrlFromRegion } from '../../utils/urls';
 import {
   evaluateWizardReadiness,
   WizardReadiness,
+  SIGNUP_WIZARD_READINESS_CONFIG,
+  getBlockingServiceKeys,
+  SERVICE_LABELS,
 } from '../health-checks/readiness';
 import { enableDebugLogs, initLogFile, logToFile } from '../../utils/debug';
 import { createBenchmarkPipeline } from '../middleware/benchmark';
@@ -178,10 +181,29 @@ export async function runWorkflow(
   // 2. Health check (guarded — skip if TUI already ran it)
   if (!session.readinessResult) {
     logToFile('[agent-runner] evaluating wizard readiness');
-    const readiness = await evaluateWizardReadiness();
+    const readinessConfig = session.signup
+      ? SIGNUP_WIZARD_READINESS_CONFIG
+      : undefined;
+    const readiness = await evaluateWizardReadiness(readinessConfig);
     logToFile(`[agent-runner] readiness=${readiness.decision}`);
     if (readiness.decision === WizardReadiness.No) {
+      const blockingKeys = getBlockingServiceKeys(
+        readiness.health,
+        readinessConfig,
+      );
+      const blockingLabels = blockingKeys.map(
+        (k) => `${SERVICE_LABELS[k]} (${readiness.health[k].status})`,
+      );
+      logToFile(`[agent-runner] blocked by: ${blockingLabels.join(', ')}`);
+
       await getUI().showBlockingOutage(readiness);
+
+      await wizardAbort({
+        message:
+          'Cannot start — external services are down:\n' +
+          blockingLabels.map((l) => `  - ${l}`).join('\n') +
+          '\n\nPlease try again later.',
+      });
     } else if (readiness.decision === WizardReadiness.YesWithWarnings) {
       getUI().setReadinessWarnings(readiness);
     }

src/lib/health-checks/readiness.ts

@@ -68,6 +68,16 @@ export const DEFAULT_WIZARD_READINESS_CONFIG: WizardReadinessConfig = {
   degradedBlocksRun: ['anthropic'],
 };
 
+/**
+ * Reduced readiness config for --signup provisioning flows.
+ *
+ * Provisioning only needs PostHog and the LLM Gateway - it doesn't
+ * use Anthropic directly, npm, GitHub Releases, or MCP.
+ */
+export const SIGNUP_WIZARD_READINESS_CONFIG: WizardReadinessConfig = {
+  downBlocksRun: ['posthogOverall', 'llmGateway'],
+};
+
 // ---------------------------------------------------------------------------
 // Aggregate check
 // ---------------------------------------------------------------------------

src/lib/workflows/posthog-integration/steps.ts

@@ -12,6 +12,8 @@ import { RunPhase } from '../../wizard-session.js';
 import {
   evaluateWizardReadiness,
   WizardReadiness,
+  SIGNUP_WIZARD_READINESS_CONFIG,
+  getBlockingServiceKeys,
 } from '../../health-checks/readiness.js';
 import { detectPostHogIntegration } from './detect.js';
 
@@ -26,8 +28,22 @@ function needsSetup(session: WizardSession): boolean {
 
 function healthCheckReady(session: WizardSession): boolean {
   if (!session.readinessResult) return false;
-  if (session.readinessResult.decision === WizardReadiness.No)
+
+  if (session.signup) {
+    const hardBlocking = getBlockingServiceKeys(
+      session.readinessResult.health,
+      SIGNUP_WIZARD_READINESS_CONFIG,
+    );
+    const defaultBlocking = getBlockingServiceKeys(
+      session.readinessResult.health,
+    );
+    if (hardBlocking.length === 0 && defaultBlocking.length === 0) return true;
+    return session.outageDismissed;
+  }
+
+  if (session.readinessResult.decision === WizardReadiness.No) {
     return session.outageDismissed;
+  }
   return true;
 }
 

src/ui/logging-ui.ts

@@ -6,7 +6,11 @@
 
 import { TaskStatus, type WizardUI, type SpinnerHandle } from './wizard-ui';
 import type { SettingsConflict } from '../lib/agent/agent-interface';
-import type { WizardReadinessResult } from '../lib/health-checks/readiness.js';
+import {
+  type WizardReadinessResult,
+  getBlockingServiceKeys,
+  SERVICE_LABELS,
+} from '../lib/health-checks/readiness.js';
 import type { OutroData } from '../lib/wizard-session';
 
 export class LoggingUI implements WizardUI {
@@ -91,12 +95,23 @@ export class LoggingUI implements WizardUI {
 
   showBlockingOutage(result: WizardReadinessResult): Promise<void> {
     console.log(`▲  Service health issues detected — blocking outage.`);
+    const blockingKeys = getBlockingServiceKeys(result.health);
+    if (blockingKeys.length > 0) {
+      console.log(`│`);
+      console.log(`│  Blocking services:`);
+      for (const key of blockingKeys) {
+        const status = result.health[key].status;
+        const error = result.health[key].error;
+        const label = SERVICE_LABELS[key];
+        const detail = error ? ` — ${error}` : '';
+        console.log(`│    ✖ ${label}: ${status}${detail}`);
+      }
+      console.log(`│`);
+    }
     for (const reason of result.reasons) {
       console.log(`│  ${reason}`);
     }
-    console.log(
-      `│  The wizard may not work reliably while services are affected.`,
-    );
+    console.log(`│  The wizard cannot start while these services are down.`);
     return Promise.resolve();
   }
 

src/ui/tui/screens/health/HealthCheckScreen.tsx

@@ -17,7 +17,10 @@ import {
 } from '../../primitives/index.js';
 import { Colors, Icons } from '../../styles.js';
 import { ServiceHealthList } from '../../components/ServiceHealthList.js';
-import { getBlockingServiceKeys } from '../../../../lib/health-checks/readiness.js';
+import {
+  getBlockingServiceKeys,
+  SIGNUP_WIZARD_READINESS_CONFIG,
+} from '../../../../lib/health-checks/readiness.js';
 import { ServiceHealthStatus } from '../../../../lib/health-checks/types.js';
 import { wizardAbort } from '../../../../utils/wizard-abort.js';
 import { fetchSkillMenu, downloadSkill } from '../../../../lib/wizard-tools.js';
@@ -86,22 +89,41 @@ export const HealthCheckScreen = ({ store }: HealthCheckScreenProps) => {
     );
   }
 
-  // Healthy or warnings — isComplete returns true, router skips past.
-  // This branch only renders for a single frame before advancing.
-  const blockingKeys = getBlockingServiceKeys(result.health);
-  if (blockingKeys.length === 0) return null;
+  const isSignup = store.session.signup;
+  const blockingKeys = getBlockingServiceKeys(
+    result.health,
+    isSignup ? SIGNUP_WIZARD_READINESS_CONFIG : undefined,
+  );
 
-  const isGithubReleasesDown = blockingKeys.includes('githubReleases');
+  // Signup has a narrower block list (only posthog + llm-gateway), so
+  // services like Anthropic can be degraded without blocking. Surface
+  // those as dismissable warnings instead of silently proceeding.
+  const warningKeys = isSignup
+    ? getBlockingServiceKeys(result.health).filter(
+        (k) => !blockingKeys.includes(k),
+      )
+    : [];
+
+  const hasHardBlock = blockingKeys.length > 0;
+  const displayKeys = hasHardBlock ? blockingKeys : warningKeys;
+  if (displayKeys.length === 0) return null;
+
+  const isGithubReleasesDown =
+    hasHardBlock && blockingKeys.includes('githubReleases');
   const canDownloadSkills =
     result.health.githubReleases.status === ServiceHealthStatus.Healthy;
   const integration = store.session.integration;
 
-  const title = `Ongoing service disruptions`;
+  const title = hasHardBlock
+    ? 'Ongoing service disruptions'
+    : 'Service disruption detected';
 
   const docsUrl = store.session.frameworkConfig?.metadata.docsUrl;
   const description = isGithubReleasesDown
     ? "The Wizard can't download necessary skills from GitHub Releases right now."
-    : 'The Wizard may not work reliably while services are affected.';
+    : hasHardBlock
+    ? 'The Wizard cannot start while these services are down.'
+    : 'Some services are degraded. You can continue, but parts of the wizard may not work reliably.';
 
   const handleDownloadAndExit = async () => {
     if (downloading) return;
@@ -131,10 +153,9 @@ export const HealthCheckScreen = ({ store }: HealthCheckScreenProps) => {
         : 'Download skills & Exit [Esc]'
       : 'Exit [Esc]';
 
-  // Blocking outage — show service list with Continue/Exit
   return (
     <ModalOverlay
-      borderColor="red"
+      borderColor={hasHardBlock ? 'red' : 'yellow'}
       title={title}
       width={72}
       footer={
@@ -173,7 +194,7 @@ export const HealthCheckScreen = ({ store }: HealthCheckScreenProps) => {
 
         <ServiceHealthList
           health={result.health}
-          filterKeys={blockingKeys}
+          filterKeys={displayKeys}
           showHealthy={false}
         />
       </Box>