From d2316c1d97921f48505c193311bd6f2aec3c85d1 Mon Sep 17 00:00:00 2001
From: Hoang Nguyen <hoangnn93@gmail.com>
Date: Thu, 3 Sep 2026 10:33:11 +0000
Subject: [PATCH] fix(cli): surface tmux guidance after setup output

---
 .../cli/src/__tests__/commands/setup.test.ts  | 15 +++++++++++--
 packages/cli/src/commands/setup.ts            | 21 +++++++++++--------
 2 files changed, 25 insertions(+), 11 deletions(-)

diff --git a/packages/cli/src/__tests__/commands/setup.test.ts b/packages/cli/src/__tests__/commands/setup.test.ts
index 474dfb81..2b6b278b 100644
--- a/packages/cli/src/__tests__/commands/setup.test.ts
+++ b/packages/cli/src/__tests__/commands/setup.test.ts
@@ -105,7 +105,13 @@ describe('setup command', () => {
 
     await program.parseAsync(['node', 'test', 'setup']);
 
-    expect(mockUi.warning).toHaveBeenCalledWith(expect.stringContaining('sudo apt-get install tmux'));
+    expect(mockUi.text).toHaveBeenCalledWith('Next steps');
+    expect(mockUi.warning).toHaveBeenCalledWith(
+      'Next step: install tmux (sudo apt-get update && sudo apt-get install tmux), then run ai-devkit setup again to start managed agents.',
+    );
+    expect(mockInspectTmux.mock.invocationCallOrder[0]).toBeLessThan(mockSetupService.run.mock.invocationCallOrder[0]);
+    expect(mockUi.table.mock.invocationCallOrder[0]).toBeLessThan(mockUi.text.mock.invocationCallOrder[0]);
+    expect(mockUi.table.mock.invocationCallOrder[0]).toBeLessThan(mockUi.warning.mock.invocationCallOrder[0]);
     expect(mockSetupService.run).toHaveBeenCalledOnce();
     expect(process.exitCode).toBe(0);
   });
@@ -117,7 +123,12 @@ describe('setup command', () => {
 
     await program.parseAsync(['node', 'test', 'setup']);
 
-    expect(mockUi.warning).toHaveBeenCalledWith(expect.stringContaining('permission denied'));
+    expect(mockUi.text).toHaveBeenCalledWith('Next steps');
+    expect(mockUi.warning).toHaveBeenCalledWith(
+      'tmux check could not run (permission denied) — verify tmux works before starting agents.',
+    );
+    expect(mockInspectTmux.mock.invocationCallOrder[0]).toBeLessThan(mockSetupService.run.mock.invocationCallOrder[0]);
+    expect(mockUi.table.mock.invocationCallOrder[0]).toBeLessThan(mockUi.warning.mock.invocationCallOrder[0]);
     expect(mockSetupService.run).toHaveBeenCalledOnce();
     expect(process.exitCode).toBe(0);
   });
diff --git a/packages/cli/src/commands/setup.ts b/packages/cli/src/commands/setup.ts
index 67cde505..5a1d45d1 100644
--- a/packages/cli/src/commands/setup.ts
+++ b/packages/cli/src/commands/setup.ts
@@ -31,15 +31,6 @@ export async function setupCommand(options: SetupCommandOptions = {}): Promise<v
 
   const tmuxDeps = createTmuxInspectionDeps();
   const tmux = await inspectTmux(tmuxDeps);
-  ui.text('Host Prerequisites');
-  if (tmux.state === 'available') {
-    ui.success(tmux.version ? `tmux ${tmux.version} available` : `${tmux.rawVersion} available`);
-  } else if (tmux.state === 'missing') {
-    const instructions = await resolveTmuxInstallInstructions(tmuxDeps);
-    ui.warning(`tmux is required for interactive managed agents. ${instructions.message} Setup will continue.`);
-  } else {
-    ui.warning(`Could not run tmux -V (${tmux.rawVersion}). Setup will continue.`);
-  }
 
   const report = await createSetupService().run({ agents });
   const counts = countStatuses(report.results.map(result => result.status));
@@ -63,6 +54,18 @@ export async function setupCommand(options: SetupCommandOptions = {}): Promise<v
     ]),
   });
 
+  if (tmux.state === 'available') {
+    ui.text('Host Prerequisites');
+    ui.success(tmux.version ? `tmux ${tmux.version} available` : `${tmux.rawVersion} available`);
+  } else if (tmux.state === 'missing') {
+    const instructions = await resolveTmuxInstallInstructions(tmuxDeps);
+    ui.text('Next steps');
+    ui.warning(`Next step: install tmux (${instructions.command}), then run ai-devkit setup again to start managed agents.`);
+  } else {
+    ui.text('Next steps');
+    ui.warning(`tmux check could not run (${tmux.rawVersion}) — verify tmux works before starting agents.`);
+  }
+
   process.exitCode = counts.failed > 0 ? 1 : 0;
 }