True Two-Step Setup Fixes

1. Problem Statement

The target onboarding experience for Agent Orchestrator is truly two commands from a fresh machine:

npm install -g @composio/ao && ao start

This does not work. Multiple bugs cause ao start to fail after a global npm install. Beyond the bugs, there is an architectural issue: ao start hardcodes runtime: "tmux" in the generated config, making tmux a hidden prerequisite that breaks the "two commands" promise.

The failure chain on a fresh machine:

1. "Dependencies not installed" — checkBuilt() hardcoded path fails for npm hoisted layout
2. "posix_spawnp: Operation not permitted" — node-pty spawn-helper missing execute bit
3. tmux is a hidden prerequisite — config always sets runtime: "tmux", orchestrator creation fails hard if tmux is missing, kills the dashboard
4. Terminal server crash is permanent — no auto-restart after crash

Two-Command Setup Workflow

2. Bug Analysis

3. Fix 1 — checkBuilt() Walk-Up Resolution

Root Cause

preflight.ts verifies @composio/ao-core exists using a single hardcoded path:

// BEFORE: only checks one level deep
const nodeModules = resolve(webDir, "node_modules", "@composio", "ao-core");

npm hoists dependencies to a parent node_modules/. The check always fails for global installs because ao-core lives one or more levels up from ao-web.

packages/web/
  node_modules/
    @composio/ao-core -> ../../core

/usr/lib/node_modules/@composio/
  ao-web/          # webDir
  ao-core/         # sibling, not child

Fix

Replace with findPackageUp() — walks up directories checking node_modules/@composio/ao-core at each level, mirroring Node's own resolution:

function findPackageUp(startDir: string, ...segments: string[]): string | null {
  let dir = resolve(startDir);
  while (true) {
    const candidate = resolve(dir, "node_modules", ...segments);
    if (existsSync(candidate)) return candidate;
    const parent = dirname(dir);
    if (parent === dir) break;
    dir = parent;
  }
  return null;
}

Error messages distinguish install method:

• Path contains node_modules → "npm install -g @composio/ao@latest"
• Otherwise → "pnpm install && pnpm build"

4. Fix 2 — node-pty spawn-helper Postinstall

Root Cause

node-pty@1.1.0 ships spawn-helper without the execute bit. The monorepo's scripts/rebuild-node-pty.js fixes this via node-gyp rebuild, but it hardcodes pnpm paths and never runs for npm global installs. Upstream fix (microsoft/node-pty#866) is only in 1.2.0-beta.

Fix

New packages/ao/bin/postinstall.js runs after npm install -g @composio/ao. Uses the same findPackageUp pattern to locate node-pty, then chmod 0o755 on spawn-helper. Skips on Windows, silent on failure.

5. Fix 3 — Startup Preflight: tmux + Interactive Prerequisites

Root Cause

This was the biggest gap in the "two-step" promise. Three compounding issues:

• Config generation hardcodes runtime: "tmux"
• Orchestrator creation fails hard if tmux runtime fails, then kills the dashboard
• tmux checks were not enforced consistently across all ao start entry paths (URL start and existing-config retries could bypass friendly remediation)

On a fresh machine without tmux, the user saw:

$ ao start
✓ Config created: agent-orchestrator.yaml
⚠ tmux not found — install with: brew install tmux
...
✗ Failed to setup orchestrator: tmux: command not found

Fix: Centralized Startup Gate with User Consent

Two-Layer Install Architecture

Install logic lives in two layers, each with a clear responsibility:

• preflight.checkTmux() — low-level check-only guard used by ao spawn preflight. It validates tmux -V and throws platform-specific manual install instructions when missing (no install attempts).
• ensureTmux() in start.ts — interactive wrapper. Uses askYesNo() to get user consent before running tryInstallWithAttempts() with tmuxInstallAttempts(). Matches the existing ensureGit() pattern. Non-interactive callers default to skip install and print manual hints.

// start.ts — interactive install with user consent
async function ensureTmux(): Promise<void> {
  const hasTmux = (await execSilent("tmux", ["-V"])) !== null;
  if (hasTmux) return;

  console.log("⚠ tmux is required for runtime \"tmux\".");
  const shouldInstall = await askYesNo("Install tmux now?", true, false);
  if (shouldInstall) {
    const installed = await tryInstallWithAttempts(
      tmuxInstallAttempts(),
      async () => (await execSilent("tmux", ["-V"])) !== null,
    );
    if (installed) return; // ✓ tmux installed successfully
  }

  // Print platform-specific hints and exit
  for (const hint of tmuxInstallHints()) console.log(hint);
  process.exit(1);
}

All-Path Enforcement

start.ts centralizes tmux enforcement in runStartup(), so all start entry paths are covered (normal start, URL start, and retries with existing config):

async function runStartup(...) {
  const runtime = config.defaults?.runtime ?? "tmux";
  if (runtime === "tmux") {
    await ensureTmux();
  }
  // continue dashboard + orchestrator startup...
}

Interactive Prerequisite Prompts (TTY)

When ao start detects a missing prerequisite on a fresh machine, it prompts the user before attempting any install. This ensures no surprises — no silent sudo, no unexpected package manager invocations.

Prerequisite Matrix

Key Behaviors

• Always asks first — uses askYesNo() before running any install command. No silent sudo or background package manager invocations.
• Logs each command — shows "Running: brew install tmux" (via tryInstallWithAttempts()) so the user knows exactly what's executing.
• Blocks on required failures — for tmux and git, prints platform-specific manual install instructions and exits rather than silently degrading the experience.
• Non-interactive fallback — when not a TTY (CI, piped scripts, agent callers), canPromptForInstall() returns false and askYesNo() returns its non-interactive default without prompting. Required and optional tools both default to false (skip), then print manual instructions when required tools are missing.
• Consistent pattern — all prerequisite helpers (ensureTmux(), ensureGit(), promptInstallAgentRuntime()) follow the same structure: detect → prompt → install → verify → block or skip.

Example: Fresh Machine Flow

$ ao start
  Detecting environment...
  ✓ Agent runtime: claude-code
  ✓ Config created: agent-orchestrator.yaml
  ⚠ tmux not found — will prompt to install at startup

  ⚠ tmux is required for runtime "tmux".
  Install tmux now? [Y/n]: y
    Running: brew install tmux
  ✓ tmux installed successfully

  Starting dashboard on port 3000...
  ✓ Dashboard: http://localhost:3000

If the user declines or install fails:

  Install tmux now? [Y/n]: n

  ✗ tmux is required but is not installed.

  Install tmux manually, then re-run ao start:

    brew install tmux          # macOS
    sudo apt install tmux      # Debian/Ubuntu
    sudo dnf install tmux      # Fedora/RHEL

6. Fix 4 — Terminal Server Crash Recovery

Root Cause

start-all.ts spawns three child processes. If a terminal server crashes, it logs the exit and never restarts.

Fix

Auto-restart logic with correct bookkeeping:

• Terminal servers restart up to 3 times on non-zero exit
• Next.js is not restarted
• No restart during graceful shutdown

Bookkeeping: Slot-Based Child Tracking

The initial version had a bug: launch() always called children.push(child), creating duplicate entries on restart. The cleanup() function counts children.length and waits for exits, so stale handles would skew the alive count and trigger the 5-second force-shutdown timer.

Fix: each process gets a slot index assigned on first launch. Restarts replace in-place:

let slotIndex = -1;

function launch(): ChildProcess {
  const child = spawn(command, args, { ... });

  child.on("exit", (code) => {
    if (!shuttingDown && opts?.restart && code !== 0 && restarts < maxRestarts) {
      restarts++;
      const replacement = launch();
      children[slotIndex] = replacement; // replace in-place
    }
  });

  // Only push on first launch; restarts replace the existing slot
  if (slotIndex === -1) {
    slotIndex = children.length;
    children.push(child);
  }

  return child;
}

7. Files Changed

• packages/cli/src/lib/preflight.ts — walk-up resolver, check-only tmux preflight + platform messages
• packages/cli/src/commands/start.ts — centralized ensureTmux() gate + interactive install prompts for git/tmux/agent runtimes (+ optional gh)
• packages/cli/src/lib/detect-agent.ts — shared runtime selection with optional pre-detected list (avoids redundant plugin scan)
• packages/ao/bin/postinstall.js — node-pty spawn-helper chmod
• packages/ao/package.json — postinstall script registration
• packages/web/server/start-all.ts — restart logic with slot-based bookkeeping
• eslint.config.js — packages/ao/bin globals override
• packages/cli/__tests__/lib/preflight.test.ts — expanded tests

8. What Was Already Working

Investigated but not broken:

9. Post-Merge: True Two-Step Matrix

After this PR, npm install -g @composio/ao && ao start:

Key improvement: Missing prerequisites are handled with explicit user consent in ao start. If install is declined or fails, the CLI prints one-line commands to run manually, then exits clearly.

10. Testing

New/Updated Test Cases

11. Design Decisions