fix: repair npm global install — walk-up dep resolution, spawn-helper chmod, platform-aware messages

[suraj-markup]

Summary

Fixes P0 blockers preventing npm install -g @composio/ao && ao start from working. Addresses 4 issues: npm dependency hoisting resolution, node-pty spawn-helper permissions, interactive tmux/git install with user consent, and terminal server crash recovery.

• Bug 1 (fix: ao start fails with 'Dependencies not installed' on npm global installs #619): checkBuilt uses a hardcoded single-level path that doesn't account for npm's dependency hoisting — always fails with "Dependencies not installed"
• Bug 2 (ao start fails with posix_spawnp: Operation not permitted after npm install -g @composio/ao #624): node-pty's spawn-helper binary ships without the execute bit — posix_spawnp fails with Operation not permitted when opening a terminal panel
• Bug 3: tmux install error message hardcodes brew install tmux — unhelpful on Linux/Windows
• Bug 4: Terminal server crashes (e.g. node-pty on linux-arm64) are permanent — no auto-restart

Changes

packages/cli/src/lib/preflight.ts

Replace the single-level existsSync check with findPackageUp() — a walk-up resolver that checks node_modules/@composio/ao-core at every ancestor directory, mirroring Node's own module resolution. Error messages now distinguish between npm (npm install -g @composio/ao@latest) and pnpm (pnpm install && pnpm build) users.

checkTmux() now attempts auto-install (brew/apt/dnf) with a log line before each attempt, then falls back to platform-specific error messages.

packages/cli/src/commands/start.ts

• ensureTmux() in runStartup() — centralized tmux enforcement covering ALL ao start paths (normal, URL quick-start, retry with existing config). No silent sudo — uses askYesNo() to get user consent before attempting install, matching the existing ensureGit() pattern.
• Uses tryInstallWithAttempts() + tmuxInstallAttempts() for consistent install flow with progress logging.
• Blocks with clear platform-specific instructions on failure (no degraded runtime: "process" fallback).

packages/ao/bin/postinstall.js (new)

Runs after npm install -g @composio/ao. Locates node-pty via the same walk-up pattern, finds spawn-helper in prebuilds/<platform>-<arch>/, and chmod 0o755. Skips silently on Windows and when no prebuild exists. Non-fatal on failure.

packages/web/server/start-all.ts

Terminal WebSocket servers now auto-restart on crash (up to 3 attempts) with slot-based bookkeeping — restarts replace the existing child process slot in-place, preventing duplicate entries that would break the cleanup countdown.

eslint.config.js

Added packages/ao/bin override for Node.js globals (process, console) — matches existing scripts/** pattern.

packages/cli/__tests__/lib/preflight.test.ts

Expanded checkBuilt tests from 3 to 5, covering pnpm layout, npm hoisted layout (walk-up), npm/pnpm error hints, and missing dist. Updated tmux tests for auto-install and platform-aware messages.

Test plan

• pnpm typecheck passes
• All 15 preflight tests pass (5 new/updated for checkBuilt)
• 222/223 CLI tests pass (1 failure = pre-existing flaky doctor-script.test.ts)
• pnpm lint — no new errors on changed files
• Web server typecheck passes (tsc -p tsconfig.server.json --noEmit)

Closes #619, closes #624

🤖 Generated with Claude Code

[fireddd]

I had also raised a pr regarding tmux fix, whether in the installation we can indicate the user about tmux not present in the error, https://github.com/ComposioHQ/agent-orchestrator/pull/250/changes, not sure we should be directly installing as a forceful install can cause problems in existing projects

[suraj-markup]

@fireddd thank you for mentioning the issue. I have fixed the auto install without interactive mode and now for any install we have interactive mode in our cli.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}