fix: 5 edge-case bugs from parallel QA (67 tests, 3 agents)

Found by 3 parallel sub-agents testing 67 edge cases:

1. Gateway returns 400 (not 502) for validation errors like missing
   required fields. 502 now only for actual upstream failures.

2. `agent run --timeout 0` now rejects with clear error instead of
   being silently ignored.

3. `agent run --thread-id bad` now validates UUID format locally
   instead of forwarding to server and getting cryptic "Value error".

4. `agent run` validates empty agent-id and message locally.

5. `paperclip deploy --role janitor` now rejects with the list of
   valid roles instead of sending invalid role to Paperclip.

Edge case pass rate: 75% → 82% (5 of 16 bugs fixed, 7 are server-side)

Author: seanphan

packages/cli/src/cli/gateway/server.ts

@@ -182,7 +182,11 @@ export function createGatewayHandler(
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         log(config, `[${name}] Error: ${msg}`);
-        return json({ error: msg }, 502);
+        // Distinguish client errors from runtime errors
+        const isValidation = msg.includes("Required") || msg.includes("Missing") || msg.includes("missing");
+        const isNotFound = msg.includes("404") || msg.includes("not found") || msg.includes("Not Found");
+        const status = isValidation ? 400 : isNotFound ? 404 : 502;
+        return json({ error: msg }, status);
       }
     }
 

packages/cli/src/cli/main.ts

@@ -3660,6 +3660,24 @@ export function createProgram(): Command {
     .option("--timeout <seconds>", "Max seconds to wait for result", "120")
     .option("--poll-interval <seconds>", "Seconds between status checks", "2")
     .action(async (opts) => {
+      // Input validation
+      if (!opts.agentId || !opts.agentId.trim()) {
+        fail("invalid_option_value", "agent-id cannot be empty");
+      }
+      if (!opts.message || !opts.message.trim()) {
+        fail("invalid_option_value", "message cannot be empty");
+      }
+      const timeout = Number.parseInt(opts.timeout, 10);
+      if (timeout <= 0) {
+        fail("invalid_option_value", `Invalid --timeout: ${opts.timeout}. Must be a positive number of seconds.`);
+      }
+      if (opts.threadId) {
+        const uuidRe = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+        if (!uuidRe.test(opts.threadId)) {
+          fail("invalid_option_value", `Invalid --thread-id: "${opts.threadId}". Must be a UUID.`);
+        }
+      }
+
       const client = buildClient(program.opts());
 
       if (!isJsonFlagEnabled()) {
@@ -4505,6 +4523,11 @@ export function createProgram(): Command {
     .option("--heartbeat-interval <seconds>", "Auto-heartbeat interval in seconds (0 = on-demand only)", "0")
     .option("--reports-to <id>", "Paperclip agent ID this agent reports to")
     .action(async (opts) => {
+      const VALID_ROLES = ["ceo", "cto", "cmo", "cfo", "engineer", "designer", "pm", "qa", "devops", "researcher", "general"];
+      if (opts.role && !VALID_ROLES.includes(opts.role)) {
+        fail("invalid_option_value", `Invalid --role: "${opts.role}"`, `Valid roles: ${VALID_ROLES.join(", ")}`);
+      }
+
       const client = buildClient(program.opts());
       const paperclipUrl = resolvePaperclipUrl(opts.paperclipUrl);
       const pc = new PaperclipResource({ baseUrl: paperclipUrl });