From 4400bdfcc97ecfeeb84b295f654f3375841a98b4 Mon Sep 17 00:00:00 2001
From: William Valentin <william.valentin.info@gmail.com>
Date: Tue, 17 Feb 2026 09:49:06 -0800
Subject: [PATCH] feat(backends): add retry/backoff controls for external CLI
 execution

---
 README.md                     |  2 ++
 src/backends/external.test.ts | 34 ++++++++++++++++++++++++++++++++++
 src/config/schema.test.ts     | 16 ++++++++++++++--
 src/config/schema.ts          |  8 ++++++++
 src/daemon/index.test.ts      | 12 ++++++------
 5 files changed, 64 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index c23331c..fb59ebc 100644
--- a/README.md
+++ b/README.md
@@ -330,6 +330,8 @@ backends:
   gemini: { enabled: false, path: /usr/local/bin/gemini, args: [], timeout_ms: 120000 }
 ```
 
+Each external backend also supports `retries` and `retry_delay_ms` for transient CLI failures.
+
 When `args` is non-empty:
 - use `{prompt}` in an argument to inject the full generated prompt directly into argv.
 - if `{prompt}` is not present, Flynn writes the prompt to stdin.
diff --git a/src/backends/external.test.ts b/src/backends/external.test.ts
index f46897c..97cda3a 100644
--- a/src/backends/external.test.ts
+++ b/src/backends/external.test.ts
@@ -15,6 +15,19 @@ vi.mock('child_process', () => ({
 
 const mockExecFile = vi.mocked(execFile);
 
+function makeFailChild(stderrText = 'failed'): FakeChild {
+  const child = new EventEmitter() as FakeChild;
+  child.stdout = new EventEmitter();
+  child.stderr = new EventEmitter();
+  child.stdin = { end: vi.fn() };
+  child.kill = vi.fn();
+  setImmediate(() => {
+    child.stderr.emit('data', Buffer.from(stderrText));
+    child.emit('close', 1);
+  });
+  return child;
+}
+
 describe('ExternalCliBackend', () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -104,4 +117,25 @@ describe('ExternalCliBackend', () => {
     expect(opencode.name).toBe('opencode');
     expect(gemini.name).toBe('gemini');
   });
+
+  it('retries failed backend calls when retries are configured', async () => {
+    spawnMock
+      .mockImplementationOnce(() => makeFailChild('transient'))
+      .mockImplementationOnce(() => makeChild('recovered'));
+    const backend = new ExternalCliBackend({
+      name: 'codex',
+      command: 'codex',
+      retries: 1,
+      retryDelayMs: 0,
+    });
+
+    const result = await backend.process({
+      systemPrompt: 'sys',
+      history: [],
+      message: 'retry me',
+    });
+
+    expect(result).toBe('recovered');
+    expect(spawnMock).toHaveBeenCalledTimes(2);
+  });
 });
diff --git a/src/config/schema.test.ts b/src/config/schema.test.ts
index f58cc80..70613a7 100644
--- a/src/config/schema.test.ts
+++ b/src/config/schema.test.ts
@@ -208,15 +208,23 @@ describe('configSchema — backends', () => {
     expect(result.backends.claude_code.enabled).toBe(false);
     expect(result.backends.claude_code.args).toEqual([]);
     expect(result.backends.claude_code.timeout_ms).toBe(120000);
+    expect(result.backends.claude_code.retries).toBe(0);
+    expect(result.backends.claude_code.retry_delay_ms).toBe(300);
     expect(result.backends.opencode.enabled).toBe(false);
     expect(result.backends.opencode.args).toEqual([]);
     expect(result.backends.opencode.timeout_ms).toBe(120000);
+    expect(result.backends.opencode.retries).toBe(0);
+    expect(result.backends.opencode.retry_delay_ms).toBe(300);
     expect(result.backends.codex.enabled).toBe(false);
     expect(result.backends.codex.args).toEqual([]);
     expect(result.backends.codex.timeout_ms).toBe(120000);
+    expect(result.backends.codex.retries).toBe(0);
+    expect(result.backends.codex.retry_delay_ms).toBe(300);
     expect(result.backends.gemini.enabled).toBe(false);
     expect(result.backends.gemini.args).toEqual([]);
     expect(result.backends.gemini.timeout_ms).toBe(120000);
+    expect(result.backends.gemini.retries).toBe(0);
+    expect(result.backends.gemini.retry_delay_ms).toBe(300);
   });
 
   it('accepts explicit external backend configs', () => {
@@ -225,8 +233,8 @@ describe('configSchema — backends', () => {
       backends: {
         default: 'codex',
         native: { enabled: false },
-        codex: { enabled: true, path: '/usr/local/bin/codex', args: ['run'], timeout_ms: 300000 },
-        gemini: { enabled: true, path: '/usr/local/bin/gemini', args: ['chat'], timeout_ms: 60000 },
+        codex: { enabled: true, path: '/usr/local/bin/codex', args: ['run'], timeout_ms: 300000, retries: 2, retry_delay_ms: 1000 },
+        gemini: { enabled: true, path: '/usr/local/bin/gemini', args: ['chat'], timeout_ms: 60000, retries: 1, retry_delay_ms: 500 },
       },
     });
     expect(result.backends.default).toBe('codex');
@@ -235,10 +243,14 @@ describe('configSchema — backends', () => {
     expect(result.backends.codex.path).toBe('/usr/local/bin/codex');
     expect(result.backends.codex.args).toEqual(['run']);
     expect(result.backends.codex.timeout_ms).toBe(300000);
+    expect(result.backends.codex.retries).toBe(2);
+    expect(result.backends.codex.retry_delay_ms).toBe(1000);
     expect(result.backends.gemini.enabled).toBe(true);
     expect(result.backends.gemini.path).toBe('/usr/local/bin/gemini');
     expect(result.backends.gemini.args).toEqual(['chat']);
     expect(result.backends.gemini.timeout_ms).toBe(60000);
+    expect(result.backends.gemini.retries).toBe(1);
+    expect(result.backends.gemini.retry_delay_ms).toBe(500);
   });
 });
 
diff --git a/src/config/schema.ts b/src/config/schema.ts
index aefa329..4e4f7b5 100644
--- a/src/config/schema.ts
+++ b/src/config/schema.ts
@@ -176,24 +176,32 @@ const backendsSchema = z.object({
     path: z.string().optional(),
     args: z.array(z.string()).default([]),
     timeout_ms: z.number().min(1_000).max(600_000).default(120_000),
+    retries: z.number().min(0).max(5).default(0),
+    retry_delay_ms: z.number().min(0).max(30_000).default(300),
   }).default({ enabled: false }),
   opencode: z.object({
     enabled: z.boolean().default(false),
     path: z.string().optional(),
     args: z.array(z.string()).default([]),
     timeout_ms: z.number().min(1_000).max(600_000).default(120_000),
+    retries: z.number().min(0).max(5).default(0),
+    retry_delay_ms: z.number().min(0).max(30_000).default(300),
   }).default({ enabled: false }),
   codex: z.object({
     enabled: z.boolean().default(false),
     path: z.string().optional(),
     args: z.array(z.string()).default([]),
     timeout_ms: z.number().min(1_000).max(600_000).default(120_000),
+    retries: z.number().min(0).max(5).default(0),
+    retry_delay_ms: z.number().min(0).max(30_000).default(300),
   }).default({ enabled: false }),
   gemini: z.object({
     enabled: z.boolean().default(false),
     path: z.string().optional(),
     args: z.array(z.string()).default([]),
     timeout_ms: z.number().min(1_000).max(600_000).default(120_000),
+    retries: z.number().min(0).max(5).default(0),
+    retry_delay_ms: z.number().min(0).max(30_000).default(300),
   }).default({ enabled: false }),
   codex: z.object({
     enabled: z.boolean().default(false),
diff --git a/src/daemon/index.test.ts b/src/daemon/index.test.ts
index f4099b1..dacba5c 100644
--- a/src/daemon/index.test.ts
+++ b/src/daemon/index.test.ts
@@ -19,7 +19,7 @@ describe('createConfiguredExternalBackend', () => {
       ...base,
       backends: {
         ...base.backends,
-        codex: { enabled: true, path: '/usr/bin/codex', args: [], timeout_ms: 120000 },
+        codex: { enabled: true, path: '/usr/bin/codex', args: [], timeout_ms: 120000, retries: 0, retry_delay_ms: 300 },
       },
     };
     const backend = createConfiguredExternalBackend(cfg);
@@ -31,7 +31,7 @@ describe('createConfiguredExternalBackend', () => {
       ...base,
       backends: {
         ...base.backends,
-        gemini: { enabled: true, path: '/usr/bin/gemini', args: [], timeout_ms: 120000 },
+        gemini: { enabled: true, path: '/usr/bin/gemini', args: [], timeout_ms: 120000, retries: 0, retry_delay_ms: 300 },
       },
     };
     const backend = createConfiguredExternalBackend(cfg);
@@ -43,8 +43,8 @@ describe('createConfiguredExternalBackend', () => {
       ...base,
       backends: {
         ...base.backends,
-        codex: { enabled: true, path: '/usr/bin/codex', args: [], timeout_ms: 120000 },
-        gemini: { enabled: true, path: '/usr/bin/gemini', args: [], timeout_ms: 120000 },
+        codex: { enabled: true, path: '/usr/bin/codex', args: [], timeout_ms: 120000, retries: 0, retry_delay_ms: 300 },
+        gemini: { enabled: true, path: '/usr/bin/gemini', args: [], timeout_ms: 120000, retries: 0, retry_delay_ms: 300 },
       },
     };
     const configured = createConfiguredExternalBackends(cfg);
@@ -59,8 +59,8 @@ describe('createConfiguredExternalBackend', () => {
       backends: {
         ...base.backends,
         default: 'gemini' as const,
-        codex: { enabled: true, path: '/usr/bin/codex', args: [], timeout_ms: 120000 },
-        gemini: { enabled: true, path: '/usr/bin/gemini', args: [], timeout_ms: 120000 },
+        codex: { enabled: true, path: '/usr/bin/codex', args: [], timeout_ms: 120000, retries: 0, retry_delay_ms: 300 },
+        gemini: { enabled: true, path: '/usr/bin/gemini', args: [], timeout_ms: 120000, retries: 0, retry_delay_ms: 300 },
       },
     };
     const configured = createConfiguredExternalBackends(cfg);