ralph-prd 3.0.3 → 3.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-prd",
-  "version": "3.0.3",
+  "version": "3.0.5",
   "type": "module",
   "description": "AI-powered phased implementation runner for Claude Code — from PRD to shipped code",
   "bin": {

package/ralph/lib/transport.mjs

@@ -26,7 +26,7 @@ import { relative } from 'path';
 /** Timeout for the preflight check only — should always be fast. */
 const PREFLIGHT_TIMEOUT_MS = 30_000;
 
-/** Default timeout for send() — 20 minutes per CLI session. */
+/** Default timeout for send() — 20 minutes of inactivity per CLI session. */
 const SEND_TIMEOUT_MS = 20 * 60 * 1000;
 
 const CLI_FLAGS = [
@@ -60,6 +60,29 @@ export class TransportError extends Error {
   }
 }
 
+// ─── Retryable stderr detection ───────────────────────────────────────────────
+//
+// Claude CLI writes structured JSON error types to stderr on API failures.
+// These are machine-readable strings that never appear in response prose,
+// so matching them on stderr is safe.
+// Source: https://docs.anthropic.com/en/api/errors
+
+const RETRYABLE_STDERR_TYPES = [
+  'rate_limit_error',      // 429 — account rate limit
+  'overloaded_error',      // 529 — API overloaded
+  'authentication_error',  // 401 — auth/token issue
+  'api_error',             // 500 — internal API error
+  'timeout_error',         // 504 — request timed out
+  'econnrefused',
+  'econnreset',
+  'socket hang up',
+];
+
+export function isRetryableStderr(text) {
+  const lower = (text ?? '').toLowerCase();
+  return RETRYABLE_STDERR_TYPES.some(t => lower.includes(t));
+}
+
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
 function resolveCLI() {
@@ -285,10 +308,15 @@ export async function preflight() {
       if (code === 0 || code === null) {
         resolve();
       } else {
+        // Distinguish rate limit / transient API errors from auth failures so
+        // callers can retry instead of treating it as a credential problem.
+        const errorType = isRetryableStderr(stderr) ? 'rate_limit' : 'auth';
+        const detail = stderr.trim()
+          ? `stderr: ${stderr.trim()}`
+          : (errorType === 'rate_limit' ? 'rate limit or transient API error' : 'Is it installed and authenticated?');
         reject(new TransportError(
-          `\`claude\` CLI preflight exited with code ${code}. ` +
-          (stderr.trim() ? `stderr: ${stderr.trim()}` : 'Is it installed and authenticated?'),
-          'auth'
+          `\`claude\` CLI preflight exited with code ${code}. ${detail}`,
+          errorType
         ));
       }
     });
@@ -343,16 +371,24 @@ export async function send(prompt, { onChunk, signal, timeoutMs } = {}) {
     const child = spawn(cliBin, CLI_FLAGS, { stdio: ['pipe', 'pipe', 'pipe'] });
 
     // ── Timeout: kills the CLI if no output arrives within the timeout window ──
-    const timer = setTimeout(() => {
+    // This is a no-activity timeout, not a hard cap — it resets on every stdout
+    // chunk so long-running tasks that keep producing output are never killed.
+    let timer = setTimeout(onTimeout, timeout);
+    function onTimeout() {
       child.kill();
       done(reject, new TransportError(
-        `\`claude\` CLI timed out after ${(timeout / 1000).toFixed(0)}s with no response. ` +
+        `\`claude\` CLI timed out after ${(timeout / 1000).toFixed(0)}s with no output. ` +
         'The session may have hung or lost connectivity.',
         'timeout'
       ));
-    }, timeout);
+    }
+    function resetTimer() {
+      clearTimeout(timer);
+      timer = setTimeout(onTimeout, timeout);
+    }
 
     child.stdout.on('data', (chunk) => {
+      resetTimer();
       lineBuffer += chunk.toString();
       const lines = lineBuffer.split('\n');
       lineBuffer = lines.pop() ?? '';
@@ -423,13 +459,36 @@ export async function send(prompt, { onChunk, signal, timeoutMs } = {}) {
       if (code !== 0 && code !== null) {
         const errMsg = stderr.trim() || `exited with code ${code}`;
         const hadResult = resultText !== null;
+        // Check stderr for known transient API error types (rate limit, overload, etc.)
+        // and surface them as 'rate_limit' so callers can distinguish retryable
+        // failures from hard errors.
+        const errorType = isRetryableStderr(stderr) ? 'rate_limit' : 'response';
         done(reject, new TransportError(
           `\`claude\` CLI failed (exit ${code}${hadResult ? ', partial result received' : ''}): ${errMsg}`,
-          'response'
+          errorType
         ));
         return;
       }
-      done(resolve, resultText ?? accumulatedText);
+
+      // Exit code 0 with no output means the CLI quit before producing any
+      // response — this happens when a rate limit or transient API error causes
+      // the process to exit cleanly without emitting a result event.
+      // Write a recognisable token to stderr so ralph-afk's retry detector
+      // can mark this run as retryable and restart after a backoff.
+      const finalText = resultText ?? accumulatedText;
+      if (!finalText) {
+        process.stderr.write(
+          '[ralph] rate_limit_error: `claude` CLI exited cleanly with no output — ' +
+          'likely a rate limit or transient API error; will retry.\n'
+        );
+        done(reject, new TransportError(
+          '`claude` CLI exited cleanly but produced no output — possible rate limit or transient API error.',
+          'empty_response'
+        ));
+        return;
+      }
+
+      done(resolve, finalText);
     });
 
     child.on('error', (err) => {

package/ralph/test/transport.test.mjs

@@ -1,6 +1,6 @@
 import { test, describe } from 'node:test';
 import assert from 'node:assert/strict';
-import { TransportError, getCumulativeCost, _addCost, _resetCost } from '../lib/transport.mjs';
+import { TransportError, getCumulativeCost, _addCost, _resetCost, isRetryableStderr } from '../lib/transport.mjs';
 
 describe('TransportError', () => {
 
@@ -20,8 +20,8 @@ describe('TransportError', () => {
     assert.equal(err.type, 'auth');
   });
 
-  test('type can be auth | timeout | response | network | parse', () => {
-    for (const type of ['auth', 'timeout', 'response', 'network', 'parse']) {
+  test('type can be auth | timeout | response | network | parse | empty_response | rate_limit', () => {
+    for (const type of ['auth', 'timeout', 'response', 'network', 'parse', 'empty_response', 'rate_limit']) {
       const err = new TransportError('msg', type);
       assert.equal(err.type, type);
     }
@@ -30,6 +30,45 @@ describe('TransportError', () => {
 });
 
 
+describe('isRetryableStderr', () => {
+
+  test('returns true for rate_limit_error', () => {
+    assert.ok(isRetryableStderr('{"type":"error","error":{"type":"rate_limit_error"}}'));
+  });
+
+  test('returns true for overloaded_error', () => {
+    assert.ok(isRetryableStderr('overloaded_error: API is temporarily overloaded'));
+  });
+
+  test('returns true for econnreset', () => {
+    assert.ok(isRetryableStderr('Error: read ECONNRESET'));
+  });
+
+  test('returns true for socket hang up', () => {
+    assert.ok(isRetryableStderr('Error: socket hang up'));
+  });
+
+  test('returns false for unrelated stderr', () => {
+    assert.ok(!isRetryableStderr('SyntaxError: Unexpected token'));
+  });
+
+  test('returns false for empty string', () => {
+    assert.ok(!isRetryableStderr(''));
+  });
+
+  test('returns false for null/undefined', () => {
+    assert.ok(!isRetryableStderr(null));
+    assert.ok(!isRetryableStderr(undefined));
+  });
+
+  test('is case-insensitive', () => {
+    assert.ok(isRetryableStderr('RATE_LIMIT_ERROR'));
+    assert.ok(isRetryableStderr('Socket Hang Up'));
+  });
+
+});
+
+
 describe('getCumulativeCost', () => {
 
   test('initial cost is 0 (after reset)', () => {