fix: Improve error messages with actionable troubleshooting guidance (#368)

- Manifest load failure now shows specific troubleshooting steps including
  cache directory path for manual cleanup
- Non-TTY mode explains why interactive picker is unavailable and suggests
  the direct launch syntax instead of silently falling through to help
- `spawn update` network failure now includes recovery steps and manual
  update command

Agent: ux-engineer

Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openrouter/spawn",
-  "version": "0.2.26",
+  "version": "0.2.27",
   "type": "module",
   "bin": {
     "spawn": "cli.js"

cli/src/commands.ts

@@ -757,6 +757,10 @@ export async function cmdUpdate(): Promise<void> {
   } catch (err) {
     s.stop(pc.red("Failed to check for updates"));
     console.error("Error:", getErrorMessage(err));
+    console.error(`\nTroubleshooting:`);
+    console.error(`  1. Check your internet connection`);
+    console.error(`  2. Try again in a few moments`);
+    console.error(`  3. Update manually: ${pc.cyan(`curl -fsSL ${RAW_BASE}/cli/install.sh | bash`)}`);
   }
 }
 

cli/src/index.ts

@@ -230,6 +230,8 @@ async function main(): Promise<void> {
       if (isInteractiveTTY()) {
         await cmdInteractive();
       } else {
+        console.error(pc.yellow("Non-interactive terminal detected (no TTY). Showing help instead of interactive picker."));
+        console.error(pc.dim("To launch directly, use: spawn <agent> <cloud>\n"));
         cmdHelp();
       }
       return;

cli/src/manifest.ts

@@ -175,7 +175,15 @@ export async function loadManifest(forceRefresh = false): Promise<Manifest> {
     return stale;
   }
 
-  throw new Error("Cannot load manifest. Check your internet connection.");
+  throw new Error(
+    `Cannot load manifest: failed to fetch from GitHub and no local cache available.\n` +
+    `\n` +
+    `Troubleshooting:\n` +
+    `  1. Check your internet connection\n` +
+    `  2. Try again in a few moments (GitHub may be temporarily unreachable)\n` +
+    `  3. If the problem persists, clear the cache and retry:\n` +
+    `     rm -rf ${CACHE_DIR}`
+  );
 }
 
 export function agentKeys(m: Manifest): string[] {