From b1d5f480d872f1b129e7bdedbe11bc731dd6a228 Mon Sep 17 00:00:00 2001
From: Barney Hussey-Yeo <bh13731@my.bristol.ac.uk>
Date: Tue, 31 Mar 2026 08:55:30 +0100
Subject: [PATCH 01/19] Add Vitest test harness with in-memory SQLite isolation
 and socket mocks

Set up the test infrastructure for integration testing:
- Add vitest, supertest, and @types/supertest as dev dependencies
- Create vitest.config.ts with --experimental-sqlite support
- Create shared test helpers: setupTestDb/cleanupTestDb for fresh :memory:
  databases, createSocketMock for capturing emitted events, and factory
  helpers for projects/workflows/jobs
- Add 11 smoke tests proving DB isolation, socket mocking, fixture
  factories, and WorkflowManager importability all work
- Add "test" and "test:watch" scripts to package.json

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 package-lock.json      | 1474 +++++++++++++++++++++++++++++++++++++++-
 package.json           |    9 +-
 src/test/helpers.ts    |  193 ++++++
 src/test/smoke.test.ts |  187 +++++
 vitest.config.ts       |   19 +
 5 files changed, 1854 insertions(+), 28 deletions(-)
 create mode 100644 src/test/helpers.ts
 create mode 100644 src/test/smoke.test.ts
 create mode 100644 vitest.config.ts

diff --git a/package-lock.json b/package-lock.json
index 53a0f2a..3698cef 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -28,15 +28,18 @@
         "@types/node": "^20.19.35",
         "@types/react": "^18.3.28",
         "@types/react-dom": "^18.3.7",
+        "@types/supertest": "^7.2.0",
         "@types/uuid": "^9.0.8",
         "@vitejs/plugin-react": "^4.7.0",
         "concurrently": "^8.2.2",
         "react": "^18.3.1",
         "react-dom": "^18.3.1",
         "socket.io-client": "^4.8.3",
+        "supertest": "^7.2.2",
         "tsx": "^4.21.0",
         "typescript": "^5.9.3",
-        "vite": "^5.4.21"
+        "vite": "^5.4.21",
+        "vitest": "^4.1.2"
       }
     },
     "node_modules/@anthropic-ai/sdk": {
@@ -350,6 +353,43 @@
         "node": ">=6.9.0"
       }
     },
+    "node_modules/@emnapi/core": {
+      "version": "1.9.1",
+      "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.9.1.tgz",
+      "integrity": "sha512-mukuNALVsoix/w1BJwFzwXBN/dHeejQtuVzcDsfOEsdpCumXb/E9j8w11h5S54tT1xhifGfbbSm/ICrObRb3KA==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "peer": true,
+      "dependencies": {
+        "@emnapi/wasi-threads": "1.2.0",
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@emnapi/runtime": {
+      "version": "1.9.1",
+      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.9.1.tgz",
+      "integrity": "sha512-VYi5+ZVLhpgK4hQ0TAjiQiZ6ol0oe4mBx7mVv7IflsiEp0OWoVsp/+f9Vc1hOhE0TtkORVrI1GvzyreqpgWtkA==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "peer": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@emnapi/wasi-threads": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.0.tgz",
+      "integrity": "sha512-N10dEJNSsUx41Z6pZsXU8FjPjpBEplgH24sfkmITrBED1/U2Esum9F3lfLrMjKHHjmi557zQn7kR9R+XWXu5Rg==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "peer": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
     "node_modules/@esbuild/aix-ppc64": {
       "version": "0.27.3",
       "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.3.tgz",
@@ -1156,6 +1196,331 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/@napi-rs/wasm-runtime": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.2.tgz",
+      "integrity": "sha512-sNXv5oLJ7ob93xkZ1XnxisYhGYXfaG9f65/ZgYuAu3qt7b3NadcOEhLvx28hv31PgX8SZJRYrAIPQilQmFpLVw==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@tybys/wasm-util": "^0.10.1"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/Brooooooklyn"
+      },
+      "peerDependencies": {
+        "@emnapi/core": "^1.7.1",
+        "@emnapi/runtime": "^1.7.1"
+      }
+    },
+    "node_modules/@noble/hashes": {
+      "version": "1.8.0",
+      "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-1.8.0.tgz",
+      "integrity": "sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^14.21.3 || >=16"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/@oxc-project/types": {
+      "version": "0.122.0",
+      "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.122.0.tgz",
+      "integrity": "sha512-oLAl5kBpV4w69UtFZ9xqcmTi+GENWOcPF7FCrczTiBbmC0ibXxCwyvZGbO39rCVEuLGAZM84DH0pUIyyv/YJzA==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/Boshen"
+      }
+    },
+    "node_modules/@paralleldrive/cuid2": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/@paralleldrive/cuid2/-/cuid2-2.3.1.tgz",
+      "integrity": "sha512-XO7cAxhnTZl0Yggq6jOgjiOHhbgcO4NqFqwSmQpjK3b6TEE6Uj/jfSk6wzYyemh3+I0sHirKSetjQwn5cZktFw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@noble/hashes": "^1.1.5"
+      }
+    },
+    "node_modules/@rolldown/binding-android-arm64": {
+      "version": "1.0.0-rc.12",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.0-rc.12.tgz",
+      "integrity": "sha512-pv1y2Fv0JybcykuiiD3qBOBdz6RteYojRFY1d+b95WVuzx211CRh+ytI/+9iVyWQ6koTh5dawe4S/yRfOFjgaA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-darwin-arm64": {
+      "version": "1.0.0-rc.12",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.0-rc.12.tgz",
+      "integrity": "sha512-cFYr6zTG/3PXXF3pUO+umXxt1wkRK/0AYT8lDwuqvRC+LuKYWSAQAQZjCWDQpAH172ZV6ieYrNnFzVVcnSflAg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-darwin-x64": {
+      "version": "1.0.0-rc.12",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.0-rc.12.tgz",
+      "integrity": "sha512-ZCsYknnHzeXYps0lGBz8JrF37GpE9bFVefrlmDrAQhOEi4IOIlcoU1+FwHEtyXGx2VkYAvhu7dyBf75EJQffBw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-freebsd-x64": {
+      "version": "1.0.0-rc.12",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.0-rc.12.tgz",
+      "integrity": "sha512-dMLeprcVsyJsKolRXyoTH3NL6qtsT0Y2xeuEA8WQJquWFXkEC4bcu1rLZZSnZRMtAqwtrF/Ib9Ddtpa/Gkge9Q==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-arm-gnueabihf": {
+      "version": "1.0.0-rc.12",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.0-rc.12.tgz",
+      "integrity": "sha512-YqWjAgGC/9M1lz3GR1r1rP79nMgo3mQiiA+Hfo+pvKFK1fAJ1bCi0ZQVh8noOqNacuY1qIcfyVfP6HoyBRZ85Q==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-arm64-gnu": {
+      "version": "1.0.0-rc.12",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.0-rc.12.tgz",
+      "integrity": "sha512-/I5AS4cIroLpslsmzXfwbe5OmWvSsrFuEw3mwvbQ1kDxJ822hFHIx+vsN/TAzNVyepI/j/GSzrtCIwQPeKCLIg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-arm64-musl": {
+      "version": "1.0.0-rc.12",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.0-rc.12.tgz",
+      "integrity": "sha512-V6/wZztnBqlx5hJQqNWwFdxIKN0m38p8Jas+VoSfgH54HSj9tKTt1dZvG6JRHcjh6D7TvrJPWFGaY9UBVOaWPw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-ppc64-gnu": {
+      "version": "1.0.0-rc.12",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.0-rc.12.tgz",
+      "integrity": "sha512-AP3E9BpcUYliZCxa3w5Kwj9OtEVDYK6sVoUzy4vTOJsjPOgdaJZKFmN4oOlX0Wp0RPV2ETfmIra9x1xuayFB7g==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-s390x-gnu": {
+      "version": "1.0.0-rc.12",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.0-rc.12.tgz",
+      "integrity": "sha512-nWwpvUSPkoFmZo0kQazZYOrT7J5DGOJ/+QHHzjvNlooDZED8oH82Yg67HvehPPLAg5fUff7TfWFHQS8IV1n3og==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-x64-gnu": {
+      "version": "1.0.0-rc.12",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.0-rc.12.tgz",
+      "integrity": "sha512-RNrafz5bcwRy+O9e6P8Z/OCAJW/A+qtBczIqVYwTs14pf4iV1/+eKEjdOUta93q2TsT/FI0XYDP3TCky38LMAg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-x64-musl": {
+      "version": "1.0.0-rc.12",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.0-rc.12.tgz",
+      "integrity": "sha512-Jpw/0iwoKWx3LJ2rc1yjFrj+T7iHZn2JDg1Yny1ma0luviFS4mhAIcd1LFNxK3EYu3DHWCps0ydXQ5i/rrJ2ig==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-openharmony-arm64": {
+      "version": "1.0.0-rc.12",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.0-rc.12.tgz",
+      "integrity": "sha512-vRugONE4yMfVn0+7lUKdKvN4D5YusEiPilaoO2sgUWpCvrncvWgPMzK00ZFFJuiPgLwgFNP5eSiUlv2tfc+lpA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-wasm32-wasi": {
+      "version": "1.0.0-rc.12",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.0-rc.12.tgz",
+      "integrity": "sha512-ykGiLr/6kkiHc0XnBfmFJuCjr5ZYKKofkx+chJWDjitX+KsJuAmrzWhwyOMSHzPhzOHOy7u9HlFoa5MoAOJ/Zg==",
+      "cpu": [
+        "wasm32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@napi-rs/wasm-runtime": "^1.1.1"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/@rolldown/binding-win32-arm64-msvc": {
+      "version": "1.0.0-rc.12",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.0-rc.12.tgz",
+      "integrity": "sha512-5eOND4duWkwx1AzCxadcOrNeighiLwMInEADT0YM7xeEOOFcovWZCq8dadXgcRHSf3Ulh1kFo/qvzoFiCLOL1Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-win32-x64-msvc": {
+      "version": "1.0.0-rc.12",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.0-rc.12.tgz",
+      "integrity": "sha512-PyqoipaswDLAZtot351MLhrlrh6lcZPo2LSYE+VDxbVk24LVKAGOuE4hb8xZQmrPAuEtTZW8E6D2zc5EUZX4Lw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
     "node_modules/@rolldown/pluginutils": {
       "version": "1.0.0-beta.27",
       "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-beta.27.tgz",
@@ -1519,6 +1884,24 @@
       "integrity": "sha512-9BCxFwvbGg/RsZK9tjXd8s4UcwR0MWeFQ1XEKIQVVvAGJyINdrqKMcTRyLoK8Rse1GjzLV9cwjWV1olXRWEXVA==",
       "license": "MIT"
     },
+    "node_modules/@standard-schema/spec": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.1.0.tgz",
+      "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@tybys/wasm-util": {
+      "version": "0.10.1",
+      "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.1.tgz",
+      "integrity": "sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
     "node_modules/@types/babel__core": {
       "version": "7.20.5",
       "resolved": "https://registry.npmjs.org/@types/babel__core/-/babel__core-7.20.5.tgz",
@@ -1574,6 +1957,17 @@
         "@types/node": "*"
       }
     },
+    "node_modules/@types/chai": {
+      "version": "5.2.3",
+      "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",
+      "integrity": "sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/deep-eql": "*",
+        "assertion-error": "^2.0.1"
+      }
+    },
     "node_modules/@types/compression": {
       "version": "1.8.1",
       "resolved": "https://registry.npmjs.org/@types/compression/-/compression-1.8.1.tgz",
@@ -1593,6 +1987,13 @@
         "@types/node": "*"
       }
     },
+    "node_modules/@types/cookiejar": {
+      "version": "2.1.5",
+      "resolved": "https://registry.npmjs.org/@types/cookiejar/-/cookiejar-2.1.5.tgz",
+      "integrity": "sha512-he+DHOWReW0nghN24E1WUqM0efK4kI9oTqDm6XmK8ZPe2djZ90BSNdGnIyCLzCPw7/pogPlGbzI2wHGGmi4O/Q==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/cors": {
       "version": "2.8.19",
       "resolved": "https://registry.npmjs.org/@types/cors/-/cors-2.8.19.tgz",
@@ -1602,6 +2003,13 @@
         "@types/node": "*"
       }
     },
+    "node_modules/@types/deep-eql": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz",
+      "integrity": "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/estree": {
       "version": "1.0.8",
       "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
@@ -1639,6 +2047,13 @@
       "integrity": "sha512-r8Tayk8HJnX0FztbZN7oVqGccWgw98T/0neJphO91KkmOzug1KkofZURD4UaD5uH8AqcFLfdPErnBod0u71/qg==",
       "license": "MIT"
     },
+    "node_modules/@types/methods": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/@types/methods/-/methods-1.1.4.tgz",
+      "integrity": "sha512-ymXWVrDiCxTBE3+RIrrP533E70eA+9qu7zdWoHuOmGujkYtzf4HQF96b8nwHLqhuf4ykX61IGRIB38CC6/sImQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/mime": {
       "version": "1.3.5",
       "resolved": "https://registry.npmjs.org/@types/mime/-/mime-1.3.5.tgz",
@@ -1724,6 +2139,30 @@
         "@types/node": "*"
       }
     },
+    "node_modules/@types/superagent": {
+      "version": "8.1.9",
+      "resolved": "https://registry.npmjs.org/@types/superagent/-/superagent-8.1.9.tgz",
+      "integrity": "sha512-pTVjI73witn+9ILmoJdajHGW2jkSaOzhiFYF1Rd3EQ94kymLqB9PjD9ISg7WaALC7+dCHT0FGe9T2LktLq/3GQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/cookiejar": "^2.1.5",
+        "@types/methods": "^1.1.4",
+        "@types/node": "*",
+        "form-data": "^4.0.0"
+      }
+    },
+    "node_modules/@types/supertest": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/@types/supertest/-/supertest-7.2.0.tgz",
+      "integrity": "sha512-uh2Lv57xvggst6lCqNdFAmDSvoMG7M/HDtX4iUCquxQ5EGPtaPM5PL5Hmi7LCvOG8db7YaCPNJEeoI8s/WzIQw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/methods": "^1.1.4",
+        "@types/superagent": "^8.1.0"
+      }
+    },
     "node_modules/@types/uuid": {
       "version": "9.0.8",
       "resolved": "https://registry.npmjs.org/@types/uuid/-/uuid-9.0.8.tgz",
@@ -1752,6 +2191,92 @@
         "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0"
       }
     },
+    "node_modules/@vitest/expect": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.2.tgz",
+      "integrity": "sha512-gbu+7B0YgUJ2nkdsRJrFFW6X7NTP44WlhiclHniUhxADQJH5Szt9mZ9hWnJPJ8YwOK5zUOSSlSvyzRf0u1DSBQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@standard-schema/spec": "^1.1.0",
+        "@types/chai": "^5.2.2",
+        "@vitest/spy": "4.1.2",
+        "@vitest/utils": "4.1.2",
+        "chai": "^6.2.2",
+        "tinyrainbow": "^3.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/pretty-format": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.2.tgz",
+      "integrity": "sha512-dwQga8aejqeuB+TvXCMzSQemvV9hNEtDDpgUKDzOmNQayl2OG241PSWeJwKRH3CiC+sESrmoFd49rfnq7T4RnA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyrainbow": "^3.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/runner": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.2.tgz",
+      "integrity": "sha512-Gr+FQan34CdiYAwpGJmQG8PgkyFVmARK8/xSijia3eTFgVfpcpztWLuP6FttGNfPLJhaZVP/euvujeNYar36OQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/utils": "4.1.2",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/snapshot": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.2.tgz",
+      "integrity": "sha512-g7yfUmxYS4mNxk31qbOYsSt2F4m1E02LFqO53Xpzg3zKMhLAPZAjjfyl9e6z7HrW6LvUdTwAQR3HHfLjpko16A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "4.1.2",
+        "@vitest/utils": "4.1.2",
+        "magic-string": "^0.30.21",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/spy": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.2.tgz",
+      "integrity": "sha512-DU4fBnbVCJGNBwVA6xSToNXrkZNSiw59H8tcuUspVMsBDBST4nfvsPsEHDHGtWRRnqBERBQu7TrTKskmjqTXKA==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/utils": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.2.tgz",
+      "integrity": "sha512-xw2/TiX82lQHA06cgbqRKFb5lCAy3axQ4H4SoUFhUsg+wztiet+co86IAMDtF6Vm1hc7J6j09oh/rgDn+JdKIQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "4.1.2",
+        "convert-source-map": "^2.0.0",
+        "tinyrainbow": "^3.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
     "node_modules/@xterm/addon-fit": {
       "version": "0.10.0",
       "resolved": "https://registry.npmjs.org/@xterm/addon-fit/-/addon-fit-0.10.0.tgz",
@@ -1845,6 +2370,30 @@
       "integrity": "sha512-PCVAQswWemu6UdxsDFFX/+gVeYqKAod3D3UVm91jHwynguOwAvYPhx8nNlM++NqRcK6CxxpUafjmhIdKiHibqg==",
       "license": "MIT"
     },
+    "node_modules/asap": {
+      "version": "2.0.6",
+      "resolved": "https://registry.npmjs.org/asap/-/asap-2.0.6.tgz",
+      "integrity": "sha512-BSHWgDSAiKs50o2Re8ppvp3seVHXSRM44cdSsT9FfNEUUZLOGWVCsiWaRPWM1Znn+mqZ1OfVZ3z3DWEzSp7hRA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/assertion-error": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
+      "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/asynckit": {
+      "version": "0.4.0",
+      "resolved": "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz",
+      "integrity": "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/base64id": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/base64id/-/base64id-2.0.0.tgz",
@@ -2014,6 +2563,16 @@
       ],
       "license": "CC-BY-4.0"
     },
+    "node_modules/chai": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/chai/-/chai-6.2.2.tgz",
+      "integrity": "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/chalk": {
       "version": "4.1.2",
       "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz",
@@ -2079,6 +2638,29 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/combined-stream": {
+      "version": "1.0.8",
+      "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz",
+      "integrity": "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "delayed-stream": "~1.0.0"
+      },
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/component-emitter": {
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/component-emitter/-/component-emitter-1.3.1.tgz",
+      "integrity": "sha512-T0+barUSQRTUQASh8bx02dl+DhF54GtIDY13Y3m9oWTklKbb3Wv974meRpeZ3lp1JpLVECWWNHC4vaG2XHXouQ==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/compressible": {
       "version": "2.0.18",
       "resolved": "https://registry.npmjs.org/compressible/-/compressible-2.0.18.tgz",
@@ -2204,6 +2786,13 @@
       "integrity": "sha512-NXdYc3dLr47pBkpUCHtKSwIOQXLVn8dZEuywboCOJY/osA0wFSLlSawr3KN8qXJEyX66FcONTH8EIlVuK0yyFA==",
       "license": "MIT"
     },
+    "node_modules/cookiejar": {
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/cookiejar/-/cookiejar-2.1.4.tgz",
+      "integrity": "sha512-LDx6oHrK+PhzLKJU9j5S7/Y3jM/mUHvD/DeI1WQmJn652iPC5Y4TBzC9l+5OMOXlyTTA+SmVUPm0HQUwpD5Jqw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/cors": {
       "version": "2.8.6",
       "resolved": "https://registry.npmjs.org/cors/-/cors-2.8.6.tgz",
@@ -2276,6 +2865,16 @@
         }
       }
     },
+    "node_modules/delayed-stream": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/delayed-stream/-/delayed-stream-1.0.0.tgz",
+      "integrity": "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
     "node_modules/depd": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz",
@@ -2295,6 +2894,27 @@
         "npm": "1.2.8000 || >= 1.4.16"
       }
     },
+    "node_modules/detect-libc": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/dezalgo": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/dezalgo/-/dezalgo-1.0.4.tgz",
+      "integrity": "sha512-rXSP0bf+5n0Qonsb+SVVfNfIsimO4HEtmnIpPHY8Q1UCzKlQrDMfdobr8nJOOsRgWCyMRqeSBQzmWUMq7zvVig==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "asap": "^2.0.0",
+        "wrappy": "1"
+      }
+    },
     "node_modules/dunder-proto": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
@@ -2399,6 +3019,13 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/es-module-lexer": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.0.0.tgz",
+      "integrity": "sha512-5POEcUuZybH7IdmGsD8wlf0AI55wMecM9rVBTI/qEAy2c1kTOm3DjFYjrBdI2K3BaJjJYfYFeRtM0t9ssnRuxw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/es-object-atoms": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.1.tgz",
@@ -2411,6 +3038,22 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/es-set-tostringtag": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/es-set-tostringtag/-/es-set-tostringtag-2.1.0.tgz",
+      "integrity": "sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "es-errors": "^1.3.0",
+        "get-intrinsic": "^1.2.6",
+        "has-tostringtag": "^1.0.2",
+        "hasown": "^2.0.2"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
     "node_modules/esbuild": {
       "version": "0.27.3",
       "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.3.tgz",
@@ -2469,6 +3112,16 @@
       "integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==",
       "license": "MIT"
     },
+    "node_modules/estree-walker": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
+      "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0"
+      }
+    },
     "node_modules/etag": {
       "version": "1.8.1",
       "resolved": "https://registry.npmjs.org/etag/-/etag-1.8.1.tgz",
@@ -2499,6 +3152,16 @@
         "node": ">=18.0.0"
       }
     },
+    "node_modules/expect-type": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.3.0.tgz",
+      "integrity": "sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
     "node_modules/express": {
       "version": "4.22.1",
       "resolved": "https://registry.npmjs.org/express/-/express-4.22.1.tgz",
@@ -2584,6 +3247,13 @@
       "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
       "license": "MIT"
     },
+    "node_modules/fast-safe-stringify": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz",
+      "integrity": "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/fast-uri": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz",
@@ -2600,6 +3270,24 @@
       ],
       "license": "BSD-3-Clause"
     },
+    "node_modules/fdir": {
+      "version": "6.5.0",
+      "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
+      "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "peerDependencies": {
+        "picomatch": "^3 || ^4"
+      },
+      "peerDependenciesMeta": {
+        "picomatch": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/finalhandler": {
       "version": "1.3.2",
       "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-1.3.2.tgz",
@@ -2633,6 +3321,41 @@
       "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==",
       "license": "MIT"
     },
+    "node_modules/form-data": {
+      "version": "4.0.5",
+      "resolved": "https://registry.npmjs.org/form-data/-/form-data-4.0.5.tgz",
+      "integrity": "sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "asynckit": "^0.4.0",
+        "combined-stream": "^1.0.8",
+        "es-set-tostringtag": "^2.1.0",
+        "hasown": "^2.0.2",
+        "mime-types": "^2.1.12"
+      },
+      "engines": {
+        "node": ">= 6"
+      }
+    },
+    "node_modules/formidable": {
+      "version": "3.5.4",
+      "resolved": "https://registry.npmjs.org/formidable/-/formidable-3.5.4.tgz",
+      "integrity": "sha512-YikH+7CUTOtP44ZTnUhR7Ic2UASBPOqmaRkRKxRbywPTe5VxF7RRCck4af9wutiZ/QKM5nME9Bie2fFaPz5Gug==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@paralleldrive/cuid2": "^2.2.2",
+        "dezalgo": "^1.0.4",
+        "once": "^1.4.0"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      },
+      "funding": {
+        "url": "https://ko-fi.com/tunnckoCore/commissions"
+      }
+    },
     "node_modules/forwarded": {
       "version": "0.2.0",
       "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz",
@@ -2779,6 +3502,22 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/has-tostringtag": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/has-tostringtag/-/has-tostringtag-1.0.2.tgz",
+      "integrity": "sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "has-symbols": "^1.0.3"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
     "node_modules/hasown": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.2.tgz",
@@ -2917,32 +3656,305 @@
         "ts-algebra": "^2.0.0"
       },
       "engines": {
-        "node": ">=16"
+        "node": ">=16"
+      }
+    },
+    "node_modules/json-schema-traverse": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
+      "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
+      "license": "MIT"
+    },
+    "node_modules/json-schema-typed": {
+      "version": "8.0.2",
+      "resolved": "https://registry.npmjs.org/json-schema-typed/-/json-schema-typed-8.0.2.tgz",
+      "integrity": "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==",
+      "license": "BSD-2-Clause"
+    },
+    "node_modules/json5": {
+      "version": "2.2.3",
+      "resolved": "https://registry.npmjs.org/json5/-/json5-2.2.3.tgz",
+      "integrity": "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "json5": "lib/cli.js"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/lightningcss": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.32.0.tgz",
+      "integrity": "sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ==",
+      "dev": true,
+      "license": "MPL-2.0",
+      "dependencies": {
+        "detect-libc": "^2.0.3"
+      },
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      },
+      "optionalDependencies": {
+        "lightningcss-android-arm64": "1.32.0",
+        "lightningcss-darwin-arm64": "1.32.0",
+        "lightningcss-darwin-x64": "1.32.0",
+        "lightningcss-freebsd-x64": "1.32.0",
+        "lightningcss-linux-arm-gnueabihf": "1.32.0",
+        "lightningcss-linux-arm64-gnu": "1.32.0",
+        "lightningcss-linux-arm64-musl": "1.32.0",
+        "lightningcss-linux-x64-gnu": "1.32.0",
+        "lightningcss-linux-x64-musl": "1.32.0",
+        "lightningcss-win32-arm64-msvc": "1.32.0",
+        "lightningcss-win32-x64-msvc": "1.32.0"
+      }
+    },
+    "node_modules/lightningcss-android-arm64": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-android-arm64/-/lightningcss-android-arm64-1.32.0.tgz",
+      "integrity": "sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-darwin-arm64": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-darwin-arm64/-/lightningcss-darwin-arm64-1.32.0.tgz",
+      "integrity": "sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-darwin-x64": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-darwin-x64/-/lightningcss-darwin-x64-1.32.0.tgz",
+      "integrity": "sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-freebsd-x64": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-freebsd-x64/-/lightningcss-freebsd-x64-1.32.0.tgz",
+      "integrity": "sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-arm-gnueabihf": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-linux-arm-gnueabihf/-/lightningcss-linux-arm-gnueabihf-1.32.0.tgz",
+      "integrity": "sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-arm64-gnu": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-gnu/-/lightningcss-linux-arm64-gnu-1.32.0.tgz",
+      "integrity": "sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-arm64-musl": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-musl/-/lightningcss-linux-arm64-musl-1.32.0.tgz",
+      "integrity": "sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-x64-gnu": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-gnu/-/lightningcss-linux-x64-gnu-1.32.0.tgz",
+      "integrity": "sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-x64-musl": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-musl/-/lightningcss-linux-x64-musl-1.32.0.tgz",
+      "integrity": "sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-win32-arm64-msvc": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-win32-arm64-msvc/-/lightningcss-win32-arm64-msvc-1.32.0.tgz",
+      "integrity": "sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
       }
     },
-    "node_modules/json-schema-traverse": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
-      "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
-      "license": "MIT"
-    },
-    "node_modules/json-schema-typed": {
-      "version": "8.0.2",
-      "resolved": "https://registry.npmjs.org/json-schema-typed/-/json-schema-typed-8.0.2.tgz",
-      "integrity": "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==",
-      "license": "BSD-2-Clause"
-    },
-    "node_modules/json5": {
-      "version": "2.2.3",
-      "resolved": "https://registry.npmjs.org/json5/-/json5-2.2.3.tgz",
-      "integrity": "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==",
+    "node_modules/lightningcss-win32-x64-msvc": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-win32-x64-msvc/-/lightningcss-win32-x64-msvc-1.32.0.tgz",
+      "integrity": "sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==",
+      "cpu": [
+        "x64"
+      ],
       "dev": true,
-      "license": "MIT",
-      "bin": {
-        "json5": "lib/cli.js"
-      },
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
       "engines": {
-        "node": ">=6"
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
       }
     },
     "node_modules/lodash": {
@@ -2975,6 +3987,16 @@
         "yallist": "^3.0.2"
       }
     },
+    "node_modules/magic-string": {
+      "version": "0.30.21",
+      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
+      "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.5.5"
+      }
+    },
     "node_modules/math-intrinsics": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
@@ -3122,6 +4144,17 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/obug": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/obug/-/obug-2.1.1.tgz",
+      "integrity": "sha512-uTqF9MuPraAQ+IsnPf366RG4cP9RtUi7MLO1N3KEc+wb0a6yKpeL0lmk2IB1jY5KHPAlTc6T/JRdC/YqxHNwkQ==",
+      "dev": true,
+      "funding": [
+        "https://github.com/sponsors/sxzz",
+        "https://opencollective.com/debug"
+      ],
+      "license": "MIT"
+    },
     "node_modules/on-finished": {
       "version": "2.4.1",
       "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz",
@@ -3176,6 +4209,13 @@
       "integrity": "sha512-RA1GjUVMnvYFxuqovrEqZoxxW5NUZqbwKtYz/Tt7nXerk0LbLblQmrsgdeOxV5SFHf0UDggjS/bSeOZwt1pmEQ==",
       "license": "MIT"
     },
+    "node_modules/pathe": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
+      "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/picocolors": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -3183,6 +4223,19 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/picomatch": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
+      "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/jonschlinkert"
+      }
+    },
     "node_modules/pkce-challenge": {
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/pkce-challenge/-/pkce-challenge-5.0.1.tgz",
@@ -3193,9 +4246,9 @@
       }
     },
     "node_modules/postcss": {
-      "version": "8.5.6",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.6.tgz",
-      "integrity": "sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==",
+      "version": "8.5.8",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.8.tgz",
+      "integrity": "sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg==",
       "dev": true,
       "funding": [
         {
@@ -3355,6 +4408,47 @@
         "url": "https://github.com/privatenumber/resolve-pkg-maps?sponsor=1"
       }
     },
+    "node_modules/rolldown": {
+      "version": "1.0.0-rc.12",
+      "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.0-rc.12.tgz",
+      "integrity": "sha512-yP4USLIMYrwpPHEFB5JGH1uxhcslv6/hL0OyvTuY+3qlOSJvZ7ntYnoWpehBxufkgN0cvXxppuTu5hHa/zPh+A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@oxc-project/types": "=0.122.0",
+        "@rolldown/pluginutils": "1.0.0-rc.12"
+      },
+      "bin": {
+        "rolldown": "bin/cli.mjs"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "optionalDependencies": {
+        "@rolldown/binding-android-arm64": "1.0.0-rc.12",
+        "@rolldown/binding-darwin-arm64": "1.0.0-rc.12",
+        "@rolldown/binding-darwin-x64": "1.0.0-rc.12",
+        "@rolldown/binding-freebsd-x64": "1.0.0-rc.12",
+        "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.12",
+        "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.12",
+        "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.12",
+        "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.12",
+        "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.12",
+        "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.12",
+        "@rolldown/binding-linux-x64-musl": "1.0.0-rc.12",
+        "@rolldown/binding-openharmony-arm64": "1.0.0-rc.12",
+        "@rolldown/binding-wasm32-wasi": "1.0.0-rc.12",
+        "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.12",
+        "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.12"
+      }
+    },
+    "node_modules/rolldown/node_modules/@rolldown/pluginutils": {
+      "version": "1.0.0-rc.12",
+      "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.12.tgz",
+      "integrity": "sha512-HHMwmarRKvoFsJorqYlFeFRzXZqCt2ETQlEDOb9aqssrnVBB1/+xgTGtuTrIk5vzLNX1MjMtTf7W9z3tsSbrxw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/rollup": {
       "version": "4.57.1",
       "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.57.1.tgz",
@@ -3648,6 +4742,13 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/siginfo": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
+      "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",
+      "dev": true,
+      "license": "ISC"
+    },
     "node_modules/socket.io": {
       "version": "4.8.3",
       "resolved": "https://registry.npmjs.org/socket.io/-/socket.io-4.8.3.tgz",
@@ -3721,6 +4822,13 @@
       "integrity": "sha512-zC8zGoGkmc8J9ndvml8Xksr1Amk9qBujgbF0JAIWO7kXr43w0h/0GJNM/Vustixu+YE8N/MTrQ7N31FvHUACxQ==",
       "dev": true
     },
+    "node_modules/stackback": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
+      "integrity": "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/statuses": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz",
@@ -3730,6 +4838,13 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/std-env": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/std-env/-/std-env-4.0.0.tgz",
+      "integrity": "sha512-zUMPtQ/HBY3/50VbpkupYHbRroTRZJPRLvreamgErJVys0ceuzMkD44J/QjqhHjOzK42GQ3QZIeFG1OYfOtKqQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/string-width": {
       "version": "4.2.3",
       "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
@@ -3758,6 +4873,65 @@
         "node": ">=8"
       }
     },
+    "node_modules/superagent": {
+      "version": "10.3.0",
+      "resolved": "https://registry.npmjs.org/superagent/-/superagent-10.3.0.tgz",
+      "integrity": "sha512-B+4Ik7ROgVKrQsXTV0Jwp2u+PXYLSlqtDAhYnkkD+zn3yg8s/zjA2MeGayPoY/KICrbitwneDHrjSotxKL+0XQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "component-emitter": "^1.3.1",
+        "cookiejar": "^2.1.4",
+        "debug": "^4.3.7",
+        "fast-safe-stringify": "^2.1.1",
+        "form-data": "^4.0.5",
+        "formidable": "^3.5.4",
+        "methods": "^1.1.2",
+        "mime": "2.6.0",
+        "qs": "^6.14.1"
+      },
+      "engines": {
+        "node": ">=14.18.0"
+      }
+    },
+    "node_modules/superagent/node_modules/mime": {
+      "version": "2.6.0",
+      "resolved": "https://registry.npmjs.org/mime/-/mime-2.6.0.tgz",
+      "integrity": "sha512-USPkMeET31rOMiarsBNIHZKLGgvKc/LrjofAnBlOttf5ajRvqiRA8QsenbcooctK6d6Ts6aqZXBA+XbkKthiQg==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "mime": "cli.js"
+      },
+      "engines": {
+        "node": ">=4.0.0"
+      }
+    },
+    "node_modules/supertest": {
+      "version": "7.2.2",
+      "resolved": "https://registry.npmjs.org/supertest/-/supertest-7.2.2.tgz",
+      "integrity": "sha512-oK8WG9diS3DlhdUkcFn4tkNIiIbBx9lI2ClF8K+b2/m8Eyv47LSawxUzZQSNKUrVb2KsqeTDCcjAAVPYaSLVTA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cookie-signature": "^1.2.2",
+        "methods": "^1.1.2",
+        "superagent": "^10.3.0"
+      },
+      "engines": {
+        "node": ">=14.18.0"
+      }
+    },
+    "node_modules/supertest/node_modules/cookie-signature": {
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.2.2.tgz",
+      "integrity": "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.6.0"
+      }
+    },
     "node_modules/supports-color": {
       "version": "8.1.1",
       "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-8.1.1.tgz",
@@ -3774,6 +4948,50 @@
         "url": "https://github.com/chalk/supports-color?sponsor=1"
       }
     },
+    "node_modules/tinybench": {
+      "version": "2.9.0",
+      "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",
+      "integrity": "sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/tinyexec": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.0.4.tgz",
+      "integrity": "sha512-u9r3uZC0bdpGOXtlxUIdwf9pkmvhqJdrVCH9fapQtgy/OeTTMZ1nqH7agtvEfmGui6e1XxjcdrlxvxJvc3sMqw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tinyglobby": {
+      "version": "0.2.15",
+      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.15.tgz",
+      "integrity": "sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fdir": "^6.5.0",
+        "picomatch": "^4.0.3"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/SuperchupuDev"
+      }
+    },
+    "node_modules/tinyrainbow": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-3.1.0.tgz",
+      "integrity": "sha512-Bf+ILmBgretUrdJxzXM0SgXLZ3XfiaUuOj/IKQHuTXip+05Xn+uyEYdVg0kYDipTBcLrCVyUzAPz7QmArb0mmw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
     "node_modules/toidentifier": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz",
@@ -4420,6 +5638,193 @@
         "@esbuild/win32-x64": "0.21.5"
       }
     },
+    "node_modules/vitest": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.2.tgz",
+      "integrity": "sha512-xjR1dMTVHlFLh98JE3i/f/WePqJsah4A0FK9cc8Ehp9Udk0AZk6ccpIZhh1qJ/yxVWRZ+Q54ocnD8TXmkhspGg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/expect": "4.1.2",
+        "@vitest/mocker": "4.1.2",
+        "@vitest/pretty-format": "4.1.2",
+        "@vitest/runner": "4.1.2",
+        "@vitest/snapshot": "4.1.2",
+        "@vitest/spy": "4.1.2",
+        "@vitest/utils": "4.1.2",
+        "es-module-lexer": "^2.0.0",
+        "expect-type": "^1.3.0",
+        "magic-string": "^0.30.21",
+        "obug": "^2.1.1",
+        "pathe": "^2.0.3",
+        "picomatch": "^4.0.3",
+        "std-env": "^4.0.0-rc.1",
+        "tinybench": "^2.9.0",
+        "tinyexec": "^1.0.2",
+        "tinyglobby": "^0.2.15",
+        "tinyrainbow": "^3.1.0",
+        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0",
+        "why-is-node-running": "^2.3.0"
+      },
+      "bin": {
+        "vitest": "vitest.mjs"
+      },
+      "engines": {
+        "node": "^20.0.0 || ^22.0.0 || >=24.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@edge-runtime/vm": "*",
+        "@opentelemetry/api": "^1.9.0",
+        "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0",
+        "@vitest/browser-playwright": "4.1.2",
+        "@vitest/browser-preview": "4.1.2",
+        "@vitest/browser-webdriverio": "4.1.2",
+        "@vitest/ui": "4.1.2",
+        "happy-dom": "*",
+        "jsdom": "*",
+        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@edge-runtime/vm": {
+          "optional": true
+        },
+        "@opentelemetry/api": {
+          "optional": true
+        },
+        "@types/node": {
+          "optional": true
+        },
+        "@vitest/browser-playwright": {
+          "optional": true
+        },
+        "@vitest/browser-preview": {
+          "optional": true
+        },
+        "@vitest/browser-webdriverio": {
+          "optional": true
+        },
+        "@vitest/ui": {
+          "optional": true
+        },
+        "happy-dom": {
+          "optional": true
+        },
+        "jsdom": {
+          "optional": true
+        },
+        "vite": {
+          "optional": false
+        }
+      }
+    },
+    "node_modules/vitest/node_modules/@vitest/mocker": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.2.tgz",
+      "integrity": "sha512-Ize4iQtEALHDttPRCmN+FKqOl2vxTiNUhzobQFFt/BM1lRUTG7zRCLOykG/6Vo4E4hnUdfVLo5/eqKPukcWW7Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/spy": "4.1.2",
+        "estree-walker": "^3.0.3",
+        "magic-string": "^0.30.21"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "msw": "^2.4.9",
+        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "msw": {
+          "optional": true
+        },
+        "vite": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/vitest/node_modules/vite": {
+      "version": "8.0.3",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-8.0.3.tgz",
+      "integrity": "sha512-B9ifbFudT1TFhfltfaIPgjo9Z3mDynBTJSUYxTjOQruf/zHH+ezCQKcoqO+h7a9Pw9Nm/OtlXAiGT1axBgwqrQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "lightningcss": "^1.32.0",
+        "picomatch": "^4.0.4",
+        "postcss": "^8.5.8",
+        "rolldown": "1.0.0-rc.12",
+        "tinyglobby": "^0.2.15"
+      },
+      "bin": {
+        "vite": "bin/vite.js"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "funding": {
+        "url": "https://github.com/vitejs/vite?sponsor=1"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      },
+      "peerDependencies": {
+        "@types/node": "^20.19.0 || >=22.12.0",
+        "@vitejs/devtools": "^0.1.0",
+        "esbuild": "^0.27.0",
+        "jiti": ">=1.21.0",
+        "less": "^4.0.0",
+        "sass": "^1.70.0",
+        "sass-embedded": "^1.70.0",
+        "stylus": ">=0.54.8",
+        "sugarss": "^5.0.0",
+        "terser": "^5.16.0",
+        "tsx": "^4.8.1",
+        "yaml": "^2.4.2"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        },
+        "@vitejs/devtools": {
+          "optional": true
+        },
+        "esbuild": {
+          "optional": true
+        },
+        "jiti": {
+          "optional": true
+        },
+        "less": {
+          "optional": true
+        },
+        "sass": {
+          "optional": true
+        },
+        "sass-embedded": {
+          "optional": true
+        },
+        "stylus": {
+          "optional": true
+        },
+        "sugarss": {
+          "optional": true
+        },
+        "terser": {
+          "optional": true
+        },
+        "tsx": {
+          "optional": true
+        },
+        "yaml": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/which": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
@@ -4435,6 +5840,23 @@
         "node": ">= 8"
       }
     },
+    "node_modules/why-is-node-running": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
+      "integrity": "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "siginfo": "^2.0.0",
+        "stackback": "0.0.2"
+      },
+      "bin": {
+        "why-is-node-running": "cli.js"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/wrap-ansi": {
       "version": "7.0.0",
       "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz",
diff --git a/package.json b/package.json
index 12a80da..8bbf43d 100644
--- a/package.json
+++ b/package.json
@@ -9,7 +9,9 @@
     "server:dev": "NODE_OPTIONS='--experimental-sqlite' tsx watch --ignore './data/**' src/server/index.ts",
     "client:dev": "vite",
     "build": "tsc -p tsconfig.server.json && vite build",
-    "server:start": "node dist/server/index.js"
+    "server:start": "node dist/server/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.78.0",
@@ -31,14 +33,17 @@
     "@types/node": "^20.19.35",
     "@types/react": "^18.3.28",
     "@types/react-dom": "^18.3.7",
+    "@types/supertest": "^7.2.0",
     "@types/uuid": "^9.0.8",
     "@vitejs/plugin-react": "^4.7.0",
     "concurrently": "^8.2.2",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "socket.io-client": "^4.8.3",
+    "supertest": "^7.2.2",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vite": "^5.4.21"
+    "vite": "^5.4.21",
+    "vitest": "^4.1.2"
   }
 }
diff --git a/src/test/helpers.ts b/src/test/helpers.ts
new file mode 100644
index 0000000..3cbce61
--- /dev/null
+++ b/src/test/helpers.ts
@@ -0,0 +1,193 @@
+/**
+ * Shared test helpers for Hurlicane integration tests.
+ *
+ * Provides:
+ * - Fresh in-memory SQLite database per test via setupTestDb / cleanupTestDb
+ * - SocketManager mock that captures all emitted events
+ * - Factory helpers for inserting test fixtures
+ */
+import { vi } from 'vitest';
+import { randomUUID } from 'crypto';
+
+// ─── Database Helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Initialize a fresh in-memory database with the full schema + migrations.
+ * This calls the real initDb() from database.ts with ':memory:' which works
+ * because path.dirname(':memory:') returns '.' and mkdirSync('.', {recursive:true})
+ * is a no-op.
+ *
+ * Call cleanupTestDb() in afterEach to tear it down.
+ */
+export async function setupTestDb() {
+  const { initDb } = await import('../server/db/database.js');
+  return initDb(':memory:');
+}
+
+/**
+ * Close and discard the current in-memory database.
+ */
+export async function cleanupTestDb() {
+  const { closeDb } = await import('../server/db/database.js');
+  closeDb();
+}
+
+// ─── Socket Mock ──────────────────────────────────────────────────────────────
+
+export interface SocketMockCalls {
+  emitJobNew: any[];
+  emitJobUpdate: any[];
+  emitWorkflowNew: any[];
+  emitWorkflowUpdate: any[];
+  emitDebateNew: any[];
+  emitDebateUpdate: any[];
+  emitSnapshot: any[];
+  emitAgentNew: any[];
+  emitAgentUpdate: any[];
+  emitProjectNew: any[];
+  [key: string]: any[];
+}
+
+/**
+ * Create a vi.mock factory for '../socket/SocketManager.js' (or the path you
+ * need). Returns an object whose keys are the emit function names and values
+ * are arrays of call arguments — so you can assert exactly what was emitted.
+ *
+ * Usage in a test file:
+ * ```ts
+ * vi.mock('../server/socket/SocketManager.js', () => createSocketMock());
+ * ```
+ *
+ * Access the mock's recorded calls via the returned object, or via
+ * `vi.mocked(socket.emitJobNew).mock.calls`.
+ */
+export function createSocketMock() {
+  return {
+    initSocketManager: vi.fn(),
+    getIo: vi.fn(() => ({ emit: vi.fn() })),
+    emitSnapshot: vi.fn(),
+    emitAgentNew: vi.fn(),
+    emitAgentUpdate: vi.fn(),
+    emitAgentOutput: vi.fn(),
+    emitQuestionNew: vi.fn(),
+    emitQuestionAnswered: vi.fn(),
+    emitLockAcquired: vi.fn(),
+    emitLockReleased: vi.fn(),
+    emitProjectNew: vi.fn(),
+    emitJobNew: vi.fn(),
+    emitJobUpdate: vi.fn(),
+    emitPtyData: vi.fn(),
+    emitPtyClosed: vi.fn(),
+    emitDebateNew: vi.fn(),
+    emitDebateUpdate: vi.fn(),
+    emitWorkflowNew: vi.fn(),
+    emitWorkflowUpdate: vi.fn(),
+    emitWarningNew: vi.fn(),
+    emitDiscussionNew: vi.fn(),
+    emitDiscussionMessage: vi.fn(),
+    emitDiscussionUpdate: vi.fn(),
+    emitProposalNew: vi.fn(),
+    emitProposalUpdate: vi.fn(),
+    emitProposalMessage: vi.fn(),
+    emitPrNew: vi.fn(),
+    emitPrReviewNew: vi.fn(),
+    emitPrReviewUpdate: vi.fn(),
+    emitPrReviewMessage: vi.fn(),
+  };
+}
+
+// ─── Fixture Factories ────────────────────────────────────────────────────────
+
+/**
+ * Insert a minimal project into the DB and return its id.
+ */
+export async function insertTestProject(overrides: { id?: string; name?: string } = {}) {
+  const { insertProject } = await import('../server/db/queries.js');
+  const id = overrides.id ?? randomUUID();
+  return insertProject({
+    id,
+    name: overrides.name ?? 'Test Project',
+    description: 'test project',
+    created_at: Date.now(),
+    updated_at: Date.now(),
+  });
+}
+
+/**
+ * Insert a minimal workflow into the DB and return it.
+ */
+export async function insertTestWorkflow(overrides: Partial<{
+  id: string;
+  title: string;
+  task: string;
+  work_dir: string | null;
+  implementer_model: string;
+  reviewer_model: string;
+  max_cycles: number;
+  current_cycle: number;
+  current_phase: string;
+  status: string;
+  milestones_total: number;
+  milestones_done: number;
+  project_id: string | null;
+  template_id: string | null;
+  use_worktree: number;
+}> = {}) {
+  const { insertWorkflow } = await import('../server/db/queries.js');
+  const id = overrides.id ?? randomUUID();
+  return insertWorkflow({
+    id,
+    title: overrides.title ?? 'Test Workflow',
+    task: overrides.task ?? 'Test task',
+    work_dir: overrides.work_dir ?? '/tmp/test',
+    implementer_model: overrides.implementer_model ?? 'claude-sonnet-4-6',
+    reviewer_model: overrides.reviewer_model ?? 'codex',
+    max_cycles: overrides.max_cycles ?? 10,
+    current_cycle: overrides.current_cycle ?? 0,
+    current_phase: (overrides.current_phase ?? 'idle') as any,
+    status: (overrides.status ?? 'running') as any,
+    milestones_total: overrides.milestones_total ?? 0,
+    milestones_done: overrides.milestones_done ?? 0,
+    project_id: overrides.project_id ?? null,
+    max_turns_assess: 50,
+    max_turns_review: 30,
+    max_turns_implement: 100,
+    template_id: overrides.template_id ?? null,
+    use_worktree: overrides.use_worktree ?? 0,
+    created_at: Date.now(),
+    updated_at: Date.now(),
+  });
+}
+
+/**
+ * Insert a minimal job into the DB and return it.
+ */
+export async function insertTestJob(overrides: Partial<{
+  id: string;
+  title: string;
+  description: string;
+  status: string;
+  priority: number;
+  workflow_id: string | null;
+  workflow_cycle: number | null;
+  workflow_phase: string | null;
+  project_id: string | null;
+  work_dir: string | null;
+  model: string | null;
+}> = {}) {
+  const { insertJob } = await import('../server/db/queries.js');
+  return insertJob({
+    id: overrides.id ?? randomUUID(),
+    title: overrides.title ?? 'Test Job',
+    description: overrides.description ?? 'Test job description',
+    context: null,
+    priority: overrides.priority ?? 0,
+    status: (overrides.status ?? 'queued') as any,
+    workflow_id: overrides.workflow_id ?? null,
+    workflow_cycle: overrides.workflow_cycle ?? null,
+    workflow_phase: (overrides.workflow_phase ?? null) as any,
+    project_id: overrides.project_id ?? null,
+    work_dir: overrides.work_dir ?? null,
+    model: overrides.model ?? null,
+  });
+}
diff --git a/src/test/smoke.test.ts b/src/test/smoke.test.ts
new file mode 100644
index 0000000..a8433d9
--- /dev/null
+++ b/src/test/smoke.test.ts
@@ -0,0 +1,187 @@
+/**
+ * Smoke tests proving the test harness works:
+ * - In-memory SQLite DB initializes with full schema
+ * - Queries work against the in-memory DB
+ * - Each test gets an isolated DB (no cross-test state leakage)
+ * - SocketManager mock captures emitted events
+ * - Module-level singleton state can be reset between tests
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { setupTestDb, cleanupTestDb, createSocketMock, insertTestProject, insertTestWorkflow, insertTestJob } from './helpers.js';
+
+// Mock SocketManager before any module that imports it
+vi.mock('../server/socket/SocketManager.js', () => createSocketMock());
+
+describe('Test Harness: In-memory DB', () => {
+  beforeEach(async () => {
+    await setupTestDb();
+  });
+
+  afterEach(async () => {
+    await cleanupTestDb();
+  });
+
+  it('initializes the full schema in :memory:', async () => {
+    const { getDb } = await import('../server/db/database.js');
+    const db = getDb();
+    // Verify key tables exist
+    const tables = db.prepare(
+      "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name"
+    ).all() as { name: string }[];
+    const tableNames = tables.map((t) => t.name);
+    expect(tableNames).toContain('jobs');
+    expect(tableNames).toContain('agents');
+    expect(tableNames).toContain('workflows');
+    expect(tableNames).toContain('notes');
+    expect(tableNames).toContain('debates');
+    expect(tableNames).toContain('projects');
+  });
+
+  it('inserts and retrieves a job via queries module', async () => {
+    const { insertJob, getJobById } = await import('../server/db/queries.js');
+    const job = insertJob({
+      id: 'test-job-1',
+      title: 'Smoke Test Job',
+      description: 'A job for testing',
+      context: null,
+      priority: 5,
+    });
+    expect(job.id).toBe('test-job-1');
+    expect(job.title).toBe('Smoke Test Job');
+    expect(job.status).toBe('queued');
+    expect(job.priority).toBe(5);
+
+    const fetched = getJobById('test-job-1');
+    expect(fetched).not.toBeNull();
+    expect(fetched!.title).toBe('Smoke Test Job');
+  });
+
+  it('inserts and retrieves a workflow', async () => {
+    const project = await insertTestProject();
+    const workflow = await insertTestWorkflow({ project_id: project.id });
+    expect(workflow.id).toBeTruthy();
+    expect(workflow.status).toBe('running');
+    expect(workflow.current_phase).toBe('idle');
+
+    const { getWorkflowById } = await import('../server/db/queries.js');
+    const fetched = getWorkflowById(workflow.id);
+    expect(fetched).not.toBeNull();
+    expect(fetched!.title).toBe('Test Workflow');
+  });
+
+  it('provides isolation between tests (no leftover data)', async () => {
+    const { getJobById } = await import('../server/db/queries.js');
+    // This job was inserted in the previous test — it should not exist here
+    const ghost = getJobById('test-job-1');
+    expect(ghost).toBeNull();
+  });
+});
+
+describe('Test Harness: Socket Mock', () => {
+  beforeEach(async () => {
+    await setupTestDb();
+    vi.clearAllMocks();
+  });
+
+  afterEach(async () => {
+    await cleanupTestDb();
+  });
+
+  it('captures emitJobNew calls', async () => {
+    const socket = await import('../server/socket/SocketManager.js');
+    const { insertJob } = await import('../server/db/queries.js');
+
+    const job = insertJob({
+      id: 'mock-test-job',
+      title: 'Mock Test',
+      description: 'Testing socket mock',
+      context: null,
+      priority: 0,
+    });
+    socket.emitJobNew(job);
+
+    expect(socket.emitJobNew).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(socket.emitJobNew).mock.calls[0][0].id).toBe('mock-test-job');
+  });
+
+  it('captures emitWorkflowUpdate calls', async () => {
+    const socket = await import('../server/socket/SocketManager.js');
+    const project = await insertTestProject();
+    const workflow = await insertTestWorkflow({ project_id: project.id });
+
+    socket.emitWorkflowUpdate(workflow);
+
+    expect(socket.emitWorkflowUpdate).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(socket.emitWorkflowUpdate).mock.calls[0][0].id).toBe(workflow.id);
+  });
+});
+
+describe('Test Harness: Fixture Factories', () => {
+  beforeEach(async () => {
+    await setupTestDb();
+  });
+
+  afterEach(async () => {
+    await cleanupTestDb();
+  });
+
+  it('insertTestJob creates a job with overrides', async () => {
+    const job = await insertTestJob({
+      title: 'Custom Job',
+      status: 'running',
+      priority: 10,
+    });
+    expect(job.title).toBe('Custom Job');
+    expect(job.status).toBe('running');
+    expect(job.priority).toBe(10);
+  });
+
+  it('insertTestWorkflow creates a workflow linked to a project', async () => {
+    const project = await insertTestProject({ name: 'My Project' });
+    const workflow = await insertTestWorkflow({
+      project_id: project.id,
+      max_cycles: 5,
+      current_phase: 'assess',
+    });
+    expect(workflow.project_id).toBe(project.id);
+    expect(workflow.max_cycles).toBe(5);
+    expect(workflow.current_phase).toBe('assess');
+  });
+
+  it('insertTestJob supports workflow fields', async () => {
+    const project = await insertTestProject();
+    const workflow = await insertTestWorkflow({ project_id: project.id });
+    const job = await insertTestJob({
+      workflow_id: workflow.id,
+      workflow_cycle: 1,
+      workflow_phase: 'review',
+    });
+    expect(job.workflow_id).toBe(workflow.id);
+    expect(job.workflow_cycle).toBe(1);
+    expect(job.workflow_phase).toBe('review');
+  });
+});
+
+describe('Test Harness: Module state reset', () => {
+  beforeEach(async () => {
+    await setupTestDb();
+  });
+
+  afterEach(async () => {
+    await cleanupTestDb();
+  });
+
+  it('parseMilestones is importable and works with test data', async () => {
+    const { parseMilestones } = await import('../server/orchestrator/WorkflowManager.js');
+    const result = parseMilestones('- [x] Done\n- [ ] Not done\n- [ ] Also not done');
+    expect(result.total).toBe(3);
+    expect(result.done).toBe(1);
+  });
+
+  it('parseMilestones returns zeros for empty input', async () => {
+    const { parseMilestones } = await import('../server/orchestrator/WorkflowManager.js');
+    const result = parseMilestones('');
+    expect(result.total).toBe(0);
+    expect(result.done).toBe(0);
+  });
+});
diff --git a/vitest.config.ts b/vitest.config.ts
new file mode 100644
index 0000000..6803bd5
--- /dev/null
+++ b/vitest.config.ts
@@ -0,0 +1,19 @@
+import { defineConfig } from 'vitest/config';
+import path from 'path';
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@shared': path.resolve(__dirname, 'src/shared'),
+    },
+  },
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/test/**/*.test.ts'],
+    // Each test file gets a fresh module graph so singleton state doesn't leak
+    isolate: true,
+    // node:sqlite requires this flag (vitest v4 top-level config)
+    execArgv: ['--experimental-sqlite'],
+  },
+});

From f7cb787537dbf49c6e74523c37cabf8662b73de5 Mon Sep 17 00:00:00 2001
From: Barney Hussey-Yeo <bh13731@my.bristol.ac.uk>
Date: Tue, 31 Mar 2026 09:07:55 +0100
Subject: [PATCH 02/19] =?UTF-8?q?feat:=20add=20autonomous=20agent=20workfl?=
 =?UTF-8?q?ow=20system=20(assess=20=E2=86=92=20review=20=E2=86=92=20implem?=
 =?UTF-8?q?ent=20cycle)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ports the structured plan/review/implement cycle from autonomous-coding-agents
into Hurlicane as a first-class feature. Each workflow runs Claude as implementer
and Codex as reviewer in a repeating cycle until all milestones are complete.

Key changes:
- New workflows table + job columns (workflow_id, workflow_cycle, workflow_phase)
- WorkflowManager: event-driven orchestrator modelled after DebateManager
- WorkflowPrompts: phase-specific prompts using notes as shared artifacts
- Single shared worktree per workflow (created once at start, all phases share
  one branch so changes accumulate linearly across cycles)
- Auto PR creation + worktree cleanup on workflow completion via gh CLI
- Codex review phase (cycle 2+) does full code review via git diff before
  updating the plan — adds Fix: milestones for any quality issues found
- isAutoExitJob() helper replaces debate_role checks across 8 call sites so
  workflow phase jobs also exit cleanly without calling finish_job
- PtyManager: PTY attach failure is a warning (not job failure) for auto-exit
  jobs since tailing already captures output
- REST API: GET/POST /api/workflows, cancel, resume endpoints
- UI: Autonomous Agents button, WorkflowForm, WorkflowDetailModal with
  milestone progress bar, plan/worklog/jobs tabs, View PR link

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/client/App.tsx                            |  44 +-
 src/client/components/Header.tsx              |  34 +-
 src/client/components/WorkflowDetailModal.tsx | 256 +++++++++++
 src/client/components/WorkflowForm.tsx        | 195 ++++++++
 src/client/hooks/useSocket.ts                 |   6 +-
 src/client/hooks/useWorkflows.ts              |  20 +
 src/server/api/router.ts                      |   2 +
 src/server/api/workflows.ts                   | 143 ++++++
 src/server/db/database.ts                     |  52 ++-
 src/server/db/queries.ts                      |  66 ++-
 src/server/index.ts                           |   1 +
 src/server/orchestrator/AgentRunner.ts        |   2 +
 src/server/orchestrator/PtyManager.ts         |  21 +-
 src/server/orchestrator/StuckJobWatchdog.ts   |   6 +-
 src/server/orchestrator/WorkQueueManager.ts   |   6 +-
 src/server/orchestrator/WorkflowManager.ts    | 417 ++++++++++++++++++
 src/server/orchestrator/WorkflowPrompts.ts    | 215 +++++++++
 src/server/orchestrator/recovery.ts           |   8 +-
 src/server/socket/SocketManager.ts            |  10 +-
 src/shared/types.ts                           |  62 +++
 20 files changed, 1539 insertions(+), 27 deletions(-)
 create mode 100644 src/client/components/WorkflowDetailModal.tsx
 create mode 100644 src/client/components/WorkflowForm.tsx
 create mode 100644 src/client/hooks/useWorkflows.ts
 create mode 100644 src/server/api/workflows.ts
 create mode 100644 src/server/orchestrator/WorkflowManager.ts
 create mode 100644 src/server/orchestrator/WorkflowPrompts.ts

diff --git a/src/client/App.tsx b/src/client/App.tsx
index a90f61a..cb3b99d 100644
--- a/src/client/App.tsx
+++ b/src/client/App.tsx
@@ -20,6 +20,8 @@ const ProjectSelector = lazy(() => import('./components/ProjectSelector').then(m
 const SettingsModal = lazy(() => import('./components/SettingsModal').then(m => ({ default: m.SettingsModal })));
 const DebateForm = lazy(() => import('./components/DebateForm').then(m => ({ default: m.DebateForm })));
 const DebateDetailModal = lazy(() => import('./components/DebateDetailModal').then(m => ({ default: m.DebateDetailModal })));
+const WorkflowForm = lazy(() => import('./components/WorkflowForm').then(m => ({ default: m.WorkflowForm })));
+const WorkflowDetailModal = lazy(() => import('./components/WorkflowDetailModal').then(m => ({ default: m.WorkflowDetailModal })));
 const KnowledgeBaseModal = lazy(() => import('./components/KnowledgeBaseModal').then(m => ({ default: m.KnowledgeBaseModal })));
 import { useSocket } from './hooks/useSocket';
 import { useAgents } from './hooks/useAgents';
@@ -27,10 +29,11 @@ import { useJobs } from './hooks/useJobs';
 import { useLocks } from './hooks/useLocks';
 import { useProjects } from './hooks/useProjects';
 import { useDebates } from './hooks/useDebates';
+import { useWorkflows } from './hooks/useWorkflows';
 import { useToasts } from './hooks/useToasts';
 import { ToastFeed } from './components/ToastFeed';
 import socket from './socket';
-import type { AgentWithJob, AgentOutput, CreateJobRequest, CreateDebateRequest, Debate, Job, Template, BatchTemplate, Discussion, Proposal } from '@shared/types';
+import type { AgentWithJob, AgentOutput, CreateJobRequest, CreateDebateRequest, CreateWorkflowRequest, Debate, Workflow, Job, Template, BatchTemplate, Discussion, Proposal } from '@shared/types';
 
 export default function App() {
   const { agents, setInitial: setInitialAgents, addAgent, updateAgent } = useAgents();
@@ -38,6 +41,7 @@ export default function App() {
   const { locks, setInitial: setInitialLocks, addLock, removeLock } = useLocks();
   const { projects, setInitial: setInitialProjects, addProject, updateProject, removeProject } = useProjects();
   const { debates, setInitial: setInitialDebates, addDebate, updateDebate: updateDebateState } = useDebates();
+  const { workflows, setInitial: setInitialWorkflows, addWorkflow, updateWorkflow: updateWorkflowState } = useWorkflows();
   const { toasts, dismiss: dismissToast } = useToasts();
   const [templates, setTemplates] = useState<Template[]>([]);
 
@@ -54,6 +58,8 @@ export default function App() {
   const [showDebateForm, setShowDebateForm] = useState(false);
   const [debateFormInitial, setDebateFormInitial] = useState<Partial<CreateDebateRequest> | undefined>();
   const [selectedDebate, setSelectedDebate] = useState<Debate | null>(null);
+  const [showWorkflowForm, setShowWorkflowForm] = useState(false);
+  const [selectedWorkflow, setSelectedWorkflow] = useState<Workflow | null>(null);
   const [showKnowledgeBase, setShowKnowledgeBase] = useState(false);
   const [activeProjectId, setActiveProjectId] = useState<string | null>(null);
   const [archivedJobs, setArchivedJobs] = useState<Job[]>([]);
@@ -153,6 +159,7 @@ export default function App() {
       setTemplates(snapshot.templates ?? []);
       setInitialProjects(snapshot.projects ?? []);
       setInitialDebates(snapshot.debates ?? []);
+      setInitialWorkflows(snapshot.workflows ?? []);
       setDiscussions(snapshot.discussions ?? []);
       setProposals(snapshot.proposals ?? []);
     },
@@ -174,6 +181,8 @@ export default function App() {
     onProjectNew: addProject,
     onDebateNew: addDebate,
     onDebateUpdate: updateDebateState,
+    onWorkflowNew: addWorkflow,
+    onWorkflowUpdate: updateWorkflowState,
     onDiscussionNew: (discussion: Discussion) => setDiscussions(prev => [discussion, ...prev.filter(d => d.id !== discussion.id)]),
     onDiscussionUpdate: (discussion: Discussion) => setDiscussions(prev => prev.map(d => d.id === discussion.id ? discussion : d)),
     onProposalNew: (proposal: Proposal) => setProposals(prev => [proposal, ...prev.filter(p => p.id !== proposal.id)]),
@@ -328,6 +337,21 @@ export default function App() {
     }
   }, [activeProjectId]);
 
+  const handleSubmitWorkflow = useCallback(async (req: CreateWorkflowRequest) => {
+    const res = await fetch('/api/workflows', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(req),
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(err.error ?? 'Failed to create workflow');
+    }
+    const data = await res.json();
+    addProject(data.project);
+    setActiveProjectId(data.project.id);
+  }, [addProject]);
+
   const handleSubmitDebate = useCallback(async (req: CreateDebateRequest) => {
     const res = await fetch('/api/debates', {
       method: 'POST',
@@ -381,7 +405,7 @@ export default function App() {
 
   return (
     <div className="app">
-      <Header onNewJob={() => setShowJobForm(true)} onTemplates={() => setShowTemplates(true)} onBatchTemplates={() => setShowBatchTemplates(true)} onUsage={() => setShowUsage(true)} onSearch={() => setShowSearch(true)} onTimeline={() => setShowGantt(true)} onDag={() => setShowDag(true)} onProjects={() => setShowProjects(true)} onSettings={() => setShowSettings(true)} onDebate={() => { setDebateFormInitial(undefined); setShowDebateForm(true); }} onDebates={debates.length > 0 ? debates : undefined} onSelectDebate={(d) => setSelectedDebate(d)} onKnowledgeBase={() => setShowKnowledgeBase(true)} onEye={() => setShowEye(v => !v)} eyeEnabled={eyeEnabled} eyeActive={showEye} eyeBadgeCount={showEye ? 0 : discussions.filter(d => d.needs_reply).length + proposals.filter(p => p.needs_reply).length} onHome={() => { setSelectedAgent(null); setActiveProjectId(null); setShowJobForm(false); setShowTemplates(false); setShowBatchTemplates(false); setShowUsage(false); setShowSearch(false); setShowGantt(false); setShowDag(false); setShowProjects(false); setShowSettings(false); setShowDebateForm(false); setShowKnowledgeBase(false); setShowEye(false); }} currentProjectName={activeProjectName} onClearProject={() => setActiveProjectId(null)} todayClaudeCost={todayClaudeCost ?? undefined} todayCodexCost={todayCodexCost ?? undefined} costAutoUpdate={costAutoUpdate} onToggleCostAutoUpdate={() => setCostAutoUpdate(v => !v)} />
+      <Header onNewJob={() => setShowJobForm(true)} onTemplates={() => setShowTemplates(true)} onBatchTemplates={() => setShowBatchTemplates(true)} onUsage={() => setShowUsage(true)} onSearch={() => setShowSearch(true)} onTimeline={() => setShowGantt(true)} onDag={() => setShowDag(true)} onProjects={() => setShowProjects(true)} onSettings={() => setShowSettings(true)} onDebate={() => { setDebateFormInitial(undefined); setShowDebateForm(true); }} onDebates={debates.length > 0 ? debates : undefined} onSelectDebate={(d) => setSelectedDebate(d)} onWorkflow={() => setShowWorkflowForm(true)} onWorkflows={workflows.length > 0 ? workflows : undefined} onSelectWorkflow={(w) => setSelectedWorkflow(w)} onKnowledgeBase={() => setShowKnowledgeBase(true)} onEye={() => setShowEye(v => !v)} eyeEnabled={eyeEnabled} eyeActive={showEye} eyeBadgeCount={showEye ? 0 : discussions.filter(d => d.needs_reply).length + proposals.filter(p => p.needs_reply).length} onHome={() => { setSelectedAgent(null); setActiveProjectId(null); setShowJobForm(false); setShowTemplates(false); setShowBatchTemplates(false); setShowUsage(false); setShowSearch(false); setShowGantt(false); setShowDag(false); setShowProjects(false); setShowSettings(false); setShowDebateForm(false); setShowWorkflowForm(false); setShowKnowledgeBase(false); setShowEye(false); }} currentProjectName={activeProjectName} onClearProject={() => setActiveProjectId(null)} todayClaudeCost={todayClaudeCost ?? undefined} todayCodexCost={todayCodexCost ?? undefined} costAutoUpdate={costAutoUpdate} onToggleCostAutoUpdate={() => setCostAutoUpdate(v => !v)} />
 
       <div className="main-layout">
         <div className={`left-sidebar-stack ${leftTab === 'lineage' && selectedAgent ? '' : 'left-sidebar-stack--narrow'}`}>
@@ -504,6 +528,22 @@ export default function App() {
         <SettingsModal onClose={() => setShowSettings(false)} eyeEnabled={eyeEnabled} onEyeEnabledChange={setEyeEnabled} />
       )}
 
+      {showWorkflowForm && (
+        <WorkflowForm
+          onSubmit={handleSubmitWorkflow}
+          onClose={() => setShowWorkflowForm(false)}
+        />
+      )}
+
+      {selectedWorkflow && (
+        <WorkflowDetailModal
+          workflow={workflows.find(w => w.id === selectedWorkflow.id) ?? selectedWorkflow}
+          agents={agents}
+          onClose={() => setSelectedWorkflow(null)}
+          onWorkflowUpdate={updateWorkflowState}
+        />
+      )}
+
       {showDebateForm && (
         <DebateForm
           onSubmit={handleSubmitDebate}
diff --git a/src/client/components/Header.tsx b/src/client/components/Header.tsx
index b3e82f9..5372006 100644
--- a/src/client/components/Header.tsx
+++ b/src/client/components/Header.tsx
@@ -1,5 +1,5 @@
 import React, { useState, useRef, useEffect } from 'react';
-import type { Debate } from '@shared/types';
+import type { Debate, Workflow } from '@shared/types';
 
 interface HeaderProps {
   onNewJob: () => void;
@@ -14,6 +14,9 @@ interface HeaderProps {
   onDebate: () => void;
   onDebates?: Debate[];
   onSelectDebate?: (debate: Debate) => void;
+  onWorkflow: () => void;
+  onWorkflows?: Workflow[];
+  onSelectWorkflow?: (workflow: Workflow) => void;
   onKnowledgeBase: () => void;
   onEye: () => void;
   eyeActive?: boolean;
@@ -53,12 +56,14 @@ function HurlicaLogo() {
   );
 }
 
-export function Header({ onNewJob, onTemplates, onBatchTemplates, onUsage, onSearch, onTimeline, onDag, onProjects, onSettings, onDebate, onDebates, onSelectDebate, onKnowledgeBase, onEye, eyeActive, eyeBadgeCount, eyeEnabled, onHome, currentProjectName, onClearProject, todayClaudeCost, todayCodexCost, costAutoUpdate, onToggleCostAutoUpdate }: HeaderProps) {
+export function Header({ onNewJob, onTemplates, onBatchTemplates, onUsage, onSearch, onTimeline, onDag, onProjects, onSettings, onDebate, onDebates, onSelectDebate, onWorkflow, onWorkflows, onSelectWorkflow, onKnowledgeBase, onEye, eyeActive, eyeBadgeCount, eyeEnabled, onHome, currentProjectName, onClearProject, todayClaudeCost, todayCodexCost, costAutoUpdate, onToggleCostAutoUpdate }: HeaderProps) {
   const hasCost = (todayClaudeCost != null && todayClaudeCost > 0) || (todayCodexCost != null && todayCodexCost > 0);
   const [moreOpen, setMoreOpen] = useState(false);
   const moreRef = useRef<HTMLDivElement>(null);
   const [debateMenuOpen, setDebateMenuOpen] = useState(false);
   const debateMenuRef = useRef<HTMLDivElement>(null);
+  const [workflowMenuOpen, setWorkflowMenuOpen] = useState(false);
+  const workflowMenuRef = useRef<HTMLDivElement>(null);
   useEffect(() => {
     if (!moreOpen) return;
     const handler = (e: MouseEvent) => { if (!moreRef.current?.contains(e.target as Node)) setMoreOpen(false); };
@@ -124,6 +129,31 @@ export function Header({ onNewJob, onTemplates, onBatchTemplates, onUsage, onSea
             )}
           </button>
         )}
+        <div style={{ display: 'flex', alignItems: 'center', gap: 1, background: 'var(--border)', borderRadius: 6, overflow: 'visible' }}>
+          <button className="header-btn" onClick={onWorkflow} style={{ borderRadius: onWorkflows && onWorkflows.length > 0 ? '6px 0 0 6px' : '6px' }}>Autonomous Agents</button>
+          {onWorkflows && onWorkflows.length > 0 && (
+            <div ref={workflowMenuRef} style={{ position: 'relative' }}>
+              <button className="header-btn" style={{ padding: '5px 6px', borderRadius: '0 6px 6px 0' }} onClick={() => setWorkflowMenuOpen(v => !v)} title="View workflows">&#x25be;</button>
+              {workflowMenuOpen && (
+                <div style={{ position: 'absolute', top: '100%', right: 0, zIndex: 200, marginTop: 4, background: 'var(--bg-elevated)', border: '1px solid var(--border)', borderRadius: 8, boxShadow: '0 8px 24px rgba(0,0,0,0.4)', minWidth: 280, maxWidth: 400, maxHeight: 360, overflowY: 'auto' }}>
+                  <div style={{ padding: '8px 12px', fontSize: 11, fontWeight: 600, color: 'var(--text-dim)', textTransform: 'uppercase', letterSpacing: '0.08em', borderBottom: '1px solid var(--border)' }}>Autonomous Agents</div>
+                  {[...onWorkflows].sort((a, b) => b.updated_at - a.updated_at).map(w => {
+                    const statusColor = w.status === 'running' ? 'var(--status-running)' : w.status === 'complete' ? 'var(--status-done)' : w.status === 'blocked' ? '#f59e0b' : 'var(--status-failed)';
+                    return (
+                      <button key={w.id} onClick={() => { setWorkflowMenuOpen(false); onSelectWorkflow?.(w); }}
+                        style={{ display: 'flex', alignItems: 'center', gap: 8, width: '100%', padding: '8px 12px', background: 'none', border: 'none', cursor: 'pointer', color: 'inherit', textAlign: 'left', borderBottom: '1px solid var(--border)' }}
+                        onMouseEnter={e => (e.currentTarget.style.background = 'var(--border)')} onMouseLeave={e => (e.currentTarget.style.background = 'none')}>
+                        <span style={{ width: 7, height: 7, borderRadius: '50%', background: statusColor, flexShrink: 0, display: 'inline-block' }} />
+                        <span style={{ flex: 1, fontSize: 13, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>{w.title}</span>
+                        <span style={{ fontSize: 11, color: 'var(--text-dim)', flexShrink: 0 }}>C{w.current_cycle}/{w.max_cycles}</span>
+                      </button>
+                    );
+                  })}
+                </div>
+              )}
+            </div>
+          )}
+        </div>
         <div style={{ display: 'flex', alignItems: 'center', gap: 1, background: 'var(--border)', borderRadius: 6, overflow: 'visible' }}>
           <button className="header-btn" onClick={onDebate} style={{ borderRadius: '6px 0 0 6px' }}>Debate</button>
           {onDebates && onDebates.length > 0 && (
diff --git a/src/client/components/WorkflowDetailModal.tsx b/src/client/components/WorkflowDetailModal.tsx
new file mode 100644
index 0000000..ee6eff1
--- /dev/null
+++ b/src/client/components/WorkflowDetailModal.tsx
@@ -0,0 +1,256 @@
+import React, { useState, useEffect, useCallback } from 'react';
+import type { Workflow, Job, AgentWithJob } from '@shared/types';
+
+interface WorkflowDetail extends Workflow {
+  plan: string | null;
+  contract: string | null;
+  worklogs: Array<{ key: string; value: string; updated_at: number }>;
+}
+
+interface WorkflowDetailModalProps {
+  workflow: Workflow;
+  agents: AgentWithJob[];
+  onClose: () => void;
+  onWorkflowUpdate: (workflow: Workflow) => void;
+}
+
+const STATUS_COLORS: Record<string, string> = {
+  running: '#22c55e',
+  complete: '#3b82f6',
+  blocked: '#f59e0b',
+  failed: '#ef4444',
+  cancelled: '#6b7280',
+};
+
+const PHASE_LABELS: Record<string, string> = {
+  idle: 'Idle',
+  assess: 'Assess',
+  review: 'Review',
+  implement: 'Implement',
+};
+
+export function WorkflowDetailModal({ workflow, agents, onClose, onWorkflowUpdate }: WorkflowDetailModalProps) {
+  const [detail, setDetail] = useState<WorkflowDetail | null>(null);
+  const [jobs, setJobs] = useState<Job[]>([]);
+  const [activeTab, setActiveTab] = useState<'progress' | 'plan' | 'worklog' | 'jobs'>('progress');
+  const [loading, setLoading] = useState(true);
+  const [acting, setActing] = useState(false);
+
+  const fetchDetail = useCallback(async () => {
+    try {
+      const [detailRes, jobsRes] = await Promise.all([
+        fetch(`/api/workflows/${workflow.id}`),
+        fetch(`/api/workflows/${workflow.id}/jobs`),
+      ]);
+      if (detailRes.ok) setDetail(await detailRes.json());
+      if (jobsRes.ok) setJobs(await jobsRes.json());
+    } catch { /* ignore */ } finally {
+      setLoading(false);
+    }
+  }, [workflow.id]);
+
+  useEffect(() => { fetchDetail(); }, [fetchDetail]);
+
+  const handleCancel = async () => {
+    if (!confirm('Cancel this workflow?')) return;
+    setActing(true);
+    try {
+      const res = await fetch(`/api/workflows/${workflow.id}/cancel`, { method: 'POST' });
+      if (res.ok) {
+        const updated = await res.json();
+        onWorkflowUpdate(updated);
+        onClose();
+      }
+    } finally { setActing(false); }
+  };
+
+  const handleResume = async () => {
+    setActing(true);
+    try {
+      const res = await fetch(`/api/workflows/${workflow.id}/resume`, { method: 'POST' });
+      if (res.ok) {
+        const data = await res.json();
+        onWorkflowUpdate(data.workflow);
+        await fetchDetail();
+      }
+    } finally { setActing(false); }
+  };
+
+  const milestonePercent = workflow.milestones_total > 0
+    ? Math.round((workflow.milestones_done / workflow.milestones_total) * 100)
+    : 0;
+
+  const statusColor = STATUS_COLORS[workflow.status] ?? '#6b7280';
+
+  return (
+    <div className="modal-overlay" onClick={onClose}>
+      <div className="modal" style={{ width: '80vw', maxWidth: 900, maxHeight: '85vh', display: 'flex', flexDirection: 'column' }} onClick={e => e.stopPropagation()}>
+        <div className="modal-header">
+          <div style={{ flex: 1 }}>
+            <h2 style={{ margin: 0 }}>{workflow.title}</h2>
+            <div style={{ display: 'flex', gap: 12, alignItems: 'center', marginTop: 6, fontSize: 13, color: '#aaa' }}>
+              <span style={{ color: statusColor, fontWeight: 600 }}>{workflow.status.toUpperCase()}</span>
+              <span>Cycle {workflow.current_cycle}/{workflow.max_cycles}</span>
+              <span style={{ color: '#888' }}>Phase: {PHASE_LABELS[workflow.current_phase] ?? workflow.current_phase}</span>
+              <span style={{ color: '#888' }}>{workflow.implementer_model} + {workflow.reviewer_model}</span>
+            </div>
+          </div>
+          <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+            {workflow.pr_url && (
+              <a href={workflow.pr_url} target="_blank" rel="noopener noreferrer" className="btn btn-primary" style={{ textDecoration: 'none' }}>
+                View PR ↗
+              </a>
+            )}
+            {workflow.status === 'blocked' && (
+              <button className="btn btn-primary" onClick={handleResume} disabled={acting}>
+                Resume
+              </button>
+            )}
+            {(workflow.status === 'running' || workflow.status === 'blocked') && (
+              <button className="btn btn-secondary" onClick={handleCancel} disabled={acting}>
+                Cancel
+              </button>
+            )}
+            <button className="btn-icon" onClick={onClose}>&#x2715;</button>
+          </div>
+        </div>
+
+        {/* Milestone progress bar */}
+        <div style={{ padding: '12px 20px', borderBottom: '1px solid #333' }}>
+          <div style={{ display: 'flex', justifyContent: 'space-between', fontSize: 12, color: '#aaa', marginBottom: 6 }}>
+            <span>Milestones: {workflow.milestones_done}/{workflow.milestones_total}</span>
+            <span>{milestonePercent}%</span>
+          </div>
+          <div style={{ height: 6, background: '#333', borderRadius: 3, overflow: 'hidden' }}>
+            <div style={{ height: '100%', width: `${milestonePercent}%`, background: statusColor, borderRadius: 3, transition: 'width 0.3s ease' }} />
+          </div>
+        </div>
+
+        {/* Tabs */}
+        <div style={{ display: 'flex', gap: 0, borderBottom: '1px solid #333' }}>
+          {(['progress', 'plan', 'worklog', 'jobs'] as const).map(tab => (
+            <button
+              key={tab}
+              onClick={() => setActiveTab(tab)}
+              style={{
+                padding: '8px 16px', border: 'none', background: 'none', cursor: 'pointer',
+                color: activeTab === tab ? '#fff' : '#888',
+                borderBottom: activeTab === tab ? '2px solid #3b82f6' : '2px solid transparent',
+                fontSize: 13, fontWeight: activeTab === tab ? 600 : 400,
+                textTransform: 'capitalize',
+              }}
+            >
+              {tab}
+            </button>
+          ))}
+        </div>
+
+        <div style={{ flex: 1, overflowY: 'auto', padding: 20 }}>
+          {loading ? (
+            <div style={{ color: '#888', textAlign: 'center', padding: 40 }}>Loading...</div>
+          ) : (
+            <>
+              {activeTab === 'progress' && (
+                <div>
+                  <div style={{ marginBottom: 16 }}>
+                    <h3 style={{ margin: '0 0 8px', fontSize: 14, color: '#aaa' }}>Task</h3>
+                    <div style={{ background: '#1a1a1a', border: '1px solid #333', borderRadius: 6, padding: 12, fontSize: 13, whiteSpace: 'pre-wrap' }}>
+                      {workflow.task}
+                    </div>
+                  </div>
+
+                  <h3 style={{ margin: '0 0 8px', fontSize: 14, color: '#aaa' }}>Phase Timeline</h3>
+                  <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+                    {jobs.map(job => {
+                      const agent = agents.find(a => a.job_id === job.id);
+                      const statusDot: Record<string, string> = { done: '#22c55e', failed: '#ef4444', running: '#3b82f6', queued: '#6b7280', assigned: '#f59e0b', cancelled: '#6b7280' };
+                      return (
+                        <div key={job.id} style={{ display: 'flex', gap: 12, alignItems: 'center', padding: '6px 10px', background: '#1a1a1a', border: '1px solid #2a2a2a', borderRadius: 4, fontSize: 12 }}>
+                          <span style={{ width: 8, height: 8, borderRadius: '50%', background: statusDot[job.status] ?? '#6b7280', flexShrink: 0 }} />
+                          <span style={{ fontWeight: 600, minWidth: 180 }}>{job.title}</span>
+                          <span style={{ color: '#888' }}>{job.status}</span>
+                          {agent?.cost_usd != null && <span style={{ color: '#888', marginLeft: 'auto' }}>${agent.cost_usd.toFixed(4)}</span>}
+                        </div>
+                      );
+                    })}
+                    {jobs.length === 0 && <div style={{ color: '#888', fontSize: 13 }}>No jobs yet.</div>}
+                  </div>
+                </div>
+              )}
+
+              {activeTab === 'plan' && (
+                <div>
+                  {detail?.plan ? (
+                    <pre style={{ margin: 0, fontFamily: 'monospace', fontSize: 13, whiteSpace: 'pre-wrap', color: '#ddd' }}>
+                      {detail.plan}
+                    </pre>
+                  ) : (
+                    <div style={{ color: '#888', fontSize: 13 }}>
+                      No plan written yet. The assess phase will create it.
+                    </div>
+                  )}
+                </div>
+              )}
+
+              {activeTab === 'worklog' && (
+                <div>
+                  {detail?.worklogs && detail.worklogs.length > 0 ? (
+                    detail.worklogs.map(entry => (
+                      <div key={entry.key} style={{ marginBottom: 20 }}>
+                        <div style={{ fontSize: 11, color: '#666', marginBottom: 4 }}>
+                          {entry.key.split('/').pop()} — {new Date(entry.updated_at).toLocaleString()}
+                        </div>
+                        <pre style={{ margin: 0, fontFamily: 'monospace', fontSize: 12, whiteSpace: 'pre-wrap', color: '#ccc', background: '#1a1a1a', border: '1px solid #333', borderRadius: 6, padding: 12 }}>
+                          {entry.value}
+                        </pre>
+                      </div>
+                    ))
+                  ) : (
+                    <div style={{ color: '#888', fontSize: 13 }}>
+                      No worklog entries yet. The implement phase will write them.
+                    </div>
+                  )}
+                </div>
+              )}
+
+              {activeTab === 'jobs' && (
+                <div>
+                  <table style={{ width: '100%', borderCollapse: 'collapse', fontSize: 12 }}>
+                    <thead>
+                      <tr style={{ color: '#888', textAlign: 'left' }}>
+                        <th style={{ padding: '4px 8px' }}>Job</th>
+                        <th style={{ padding: '4px 8px' }}>Phase</th>
+                        <th style={{ padding: '4px 8px' }}>Cycle</th>
+                        <th style={{ padding: '4px 8px' }}>Status</th>
+                        <th style={{ padding: '4px 8px' }}>Model</th>
+                        <th style={{ padding: '4px 8px' }}>Cost</th>
+                      </tr>
+                    </thead>
+                    <tbody>
+                      {jobs.map(job => {
+                        const agent = agents.find(a => a.job_id === job.id);
+                        return (
+                          <tr key={job.id} style={{ borderTop: '1px solid #2a2a2a' }}>
+                            <td style={{ padding: '6px 8px' }}>{job.title}</td>
+                            <td style={{ padding: '6px 8px', color: '#aaa' }}>{job.workflow_phase ?? '-'}</td>
+                            <td style={{ padding: '6px 8px', color: '#aaa' }}>{job.workflow_cycle ?? '-'}</td>
+                            <td style={{ padding: '6px 8px', color: STATUS_COLORS[job.status] ?? '#aaa' }}>{job.status}</td>
+                            <td style={{ padding: '6px 8px', color: '#888' }}>{job.model ?? 'auto'}</td>
+                            <td style={{ padding: '6px 8px', color: '#888' }}>{agent?.cost_usd != null ? `$${agent.cost_usd.toFixed(4)}` : '-'}</td>
+                          </tr>
+                        );
+                      })}
+                      {jobs.length === 0 && (
+                        <tr><td colSpan={6} style={{ padding: 20, color: '#888', textAlign: 'center' }}>No jobs yet</td></tr>
+                      )}
+                    </tbody>
+                  </table>
+                </div>
+              )}
+            </>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/src/client/components/WorkflowForm.tsx b/src/client/components/WorkflowForm.tsx
new file mode 100644
index 0000000..6f71004
--- /dev/null
+++ b/src/client/components/WorkflowForm.tsx
@@ -0,0 +1,195 @@
+import React, { useState, useEffect } from 'react';
+import type { CreateWorkflowRequest, Template } from '@shared/types';
+import { useModels } from '../hooks/useModels';
+
+interface WorkflowFormProps {
+  onSubmit: (req: CreateWorkflowRequest) => Promise<void>;
+  onClose: () => void;
+}
+
+export function WorkflowForm({ onSubmit, onClose }: WorkflowFormProps) {
+  const { claude: claudeModels, codex: codexModels } = useModels();
+  const [title, setTitle] = useState('');
+  const [task, setTask] = useState('');
+  const [workDir, setWorkDir] = useState('');
+  const [implementerModel, setImplementerModel] = useState('claude-sonnet-4-6[1m]');
+  const [reviewerModel, setReviewerModel] = useState('codex');
+  const [maxCycles, setMaxCycles] = useState(10);
+  const [templateId, setTemplateId] = useState('');
+  const [useWorktree, setUseWorktree] = useState(true);
+  const [showAdvanced, setShowAdvanced] = useState(false);
+  const [maxTurnsAssess, setMaxTurnsAssess] = useState(50);
+  const [maxTurnsReview, setMaxTurnsReview] = useState(30);
+  const [maxTurnsImplement, setMaxTurnsImplement] = useState(100);
+  const [templates, setTemplates] = useState<Template[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+
+  useEffect(() => {
+    fetch('/api/templates').then(r => r.json()).then(setTemplates).catch(console.error);
+  }, []);
+
+  const handleTemplateChange = (newTemplateId: string) => {
+    setTemplateId(newTemplateId);
+    const tpl = templates.find(t => t.id === newTemplateId);
+    if (tpl?.work_dir) setWorkDir(tpl.work_dir);
+    if (tpl?.model) setImplementerModel(tpl.model);
+  };
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!task.trim()) return;
+    setLoading(true);
+    setError('');
+    try {
+      await onSubmit({
+        title: title.trim() || undefined,
+        task: task.trim(),
+        workDir: workDir.trim() || undefined,
+        implementerModel,
+        reviewerModel,
+        maxCycles,
+        templateId: templateId || undefined,
+        useWorktree,
+        maxTurnsAssess,
+        maxTurnsReview,
+        maxTurnsImplement,
+      });
+      onClose();
+    } catch (err: any) {
+      setError(err.message ?? 'Failed to create workflow');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="modal-overlay" onClick={onClose}>
+      <div className="modal" onClick={e => e.stopPropagation()}>
+        <div className="modal-header">
+          <h2>New Autonomous Agent Run</h2>
+          <button className="btn-icon" onClick={onClose}>&#x2715;</button>
+        </div>
+        <form onSubmit={handleSubmit} className="job-form">
+          <div className="form-group">
+            <label htmlFor="wf-title">Title <span className="form-label-hint">(optional)</span></label>
+            <input
+              id="wf-title"
+              type="text"
+              value={title}
+              onChange={e => setTitle(e.target.value)}
+              placeholder="Auto-generated from task if blank"
+              autoFocus
+            />
+          </div>
+
+          <div className="form-group">
+            <label htmlFor="wf-task">Task <span className="form-label-hint">(required)</span></label>
+            <textarea
+              id="wf-task"
+              value={task}
+              onChange={e => setTask(e.target.value)}
+              placeholder="Describe what the agents should accomplish across multiple cycles..."
+              rows={5}
+              required
+            />
+          </div>
+
+          <div className="form-group">
+            <label htmlFor="wf-workdir">Working Directory</label>
+            <input
+              id="wf-workdir"
+              type="text"
+              value={workDir}
+              onChange={e => setWorkDir(e.target.value)}
+              placeholder="/path/to/repo"
+            />
+          </div>
+
+          <div className="form-row">
+            <div className="form-group">
+              <label htmlFor="wf-implementer">Implementer Model</label>
+              <select id="wf-implementer" value={implementerModel} onChange={e => setImplementerModel(e.target.value)}>
+                {claudeModels.map(m => <option key={m.value} value={m.value}>{m.label}</option>)}
+              </select>
+            </div>
+            <div className="form-group">
+              <label htmlFor="wf-reviewer">Reviewer Model</label>
+              <select id="wf-reviewer" value={reviewerModel} onChange={e => setReviewerModel(e.target.value)}>
+                {codexModels.map(m => <option key={m.value} value={m.value}>{m.label}</option>)}
+                {claudeModels.map(m => <option key={`c-${m.value}`} value={m.value}>{m.label}</option>)}
+              </select>
+            </div>
+          </div>
+
+          <div className="form-row">
+            <div className="form-group">
+              <label htmlFor="wf-maxcycles">Max Cycles</label>
+              <input
+                id="wf-maxcycles"
+                type="number"
+                min={1}
+                max={50}
+                value={maxCycles}
+                onChange={e => setMaxCycles(Number(e.target.value))}
+              />
+            </div>
+            <div className="form-group">
+              <label htmlFor="wf-template">Template <span className="form-label-hint">(optional)</span></label>
+              <select id="wf-template" value={templateId} onChange={e => handleTemplateChange(e.target.value)}>
+                <option value="">No template</option>
+                {templates.map(t => <option key={t.id} value={t.id}>{t.name}</option>)}
+              </select>
+            </div>
+          </div>
+
+          <div className="form-group">
+            <label className="checkbox-label">
+              <input
+                type="checkbox"
+                checked={useWorktree}
+                onChange={e => setUseWorktree(e.target.checked)}
+              />
+              Use git worktree (recommended — isolates each phase in its own branch)
+            </label>
+          </div>
+
+          <button
+            type="button"
+            className="btn btn-ghost"
+            style={{ fontSize: 12, padding: '4px 0', marginBottom: 8 }}
+            onClick={() => setShowAdvanced(v => !v)}
+          >
+            {showAdvanced ? '▾' : '▸'} Advanced settings
+          </button>
+
+          {showAdvanced && (
+            <div className="form-row">
+              <div className="form-group">
+                <label htmlFor="wf-assess-turns">Assess max turns</label>
+                <input id="wf-assess-turns" type="number" min={10} max={200} value={maxTurnsAssess} onChange={e => setMaxTurnsAssess(Number(e.target.value))} />
+              </div>
+              <div className="form-group">
+                <label htmlFor="wf-review-turns">Review max turns</label>
+                <input id="wf-review-turns" type="number" min={10} max={200} value={maxTurnsReview} onChange={e => setMaxTurnsReview(Number(e.target.value))} />
+              </div>
+              <div className="form-group">
+                <label htmlFor="wf-impl-turns">Implement max turns</label>
+                <input id="wf-impl-turns" type="number" min={10} max={500} value={maxTurnsImplement} onChange={e => setMaxTurnsImplement(Number(e.target.value))} />
+              </div>
+            </div>
+          )}
+
+          {error && <div className="form-error">{error}</div>}
+
+          <div className="form-actions">
+            <button type="button" className="btn btn-secondary" onClick={onClose}>Cancel</button>
+            <button type="submit" className="btn btn-primary" disabled={loading || !task.trim()}>
+              {loading ? 'Starting...' : 'Start Workflow'}
+            </button>
+          </div>
+        </form>
+      </div>
+    </div>
+  );
+}
diff --git a/src/client/hooks/useSocket.ts b/src/client/hooks/useSocket.ts
index d40693b..ef4c7ad 100644
--- a/src/client/hooks/useSocket.ts
+++ b/src/client/hooks/useSocket.ts
@@ -1,6 +1,6 @@
 import { useEffect, useRef } from 'react';
 import socket from '../socket';
-import type { AgentWithJob, Job, Project, Question, FileLock, AgentOutput, QueueSnapshot, Debate, Discussion, Proposal } from '@shared/types';
+import type { AgentWithJob, Job, Project, Question, FileLock, AgentOutput, QueueSnapshot, Debate, Workflow, Discussion, Proposal } from '@shared/types';
 
 interface SocketHandlers {
   onSnapshot: (snapshot: QueueSnapshot) => void;
@@ -16,6 +16,8 @@ interface SocketHandlers {
   onProjectNew?: (project: Project) => void;
   onDebateNew?: (debate: Debate) => void;
   onDebateUpdate?: (debate: Debate) => void;
+  onWorkflowNew?: (workflow: Workflow) => void;
+  onWorkflowUpdate?: (workflow: Workflow) => void;
   onDiscussionNew?: (discussion: Discussion) => void;
   onDiscussionUpdate?: (discussion: Discussion) => void;
   onProposalNew?: (proposal: Proposal) => void;
@@ -47,6 +49,8 @@ export function useSocket(handlers: SocketHandlers): void {
       h('project:new', ({ project }: { project: Project }) => ref.current.onProjectNew?.(project)),
       h('debate:new', ({ debate }: { debate: Debate }) => ref.current.onDebateNew?.(debate)),
       h('debate:update', ({ debate }: { debate: Debate }) => ref.current.onDebateUpdate?.(debate)),
+      h('workflow:new', ({ workflow }: { workflow: Workflow }) => ref.current.onWorkflowNew?.(workflow)),
+      h('workflow:update', ({ workflow }: { workflow: Workflow }) => ref.current.onWorkflowUpdate?.(workflow)),
       h('warning:new', (payload: any) => (ref.current as any).onWarningNew?.(payload)),
       h('eye:discussion:new', ({ discussion }: { discussion: Discussion }) => ref.current.onDiscussionNew?.(discussion)),
       h('eye:discussion:update', ({ discussion }: { discussion: Discussion }) => ref.current.onDiscussionUpdate?.(discussion)),
diff --git a/src/client/hooks/useWorkflows.ts b/src/client/hooks/useWorkflows.ts
new file mode 100644
index 0000000..ef97566
--- /dev/null
+++ b/src/client/hooks/useWorkflows.ts
@@ -0,0 +1,20 @@
+import { useState, useCallback } from 'react';
+import type { Workflow } from '@shared/types';
+
+export function useWorkflows() {
+  const [workflows, setWorkflows] = useState<Workflow[]>([]);
+
+  const setInitial = useCallback((initial: Workflow[]) => {
+    setWorkflows(initial);
+  }, []);
+
+  const addWorkflow = useCallback((workflow: Workflow) => {
+    setWorkflows(prev => [workflow, ...prev]);
+  }, []);
+
+  const updateWorkflow = useCallback((workflow: Workflow) => {
+    setWorkflows(prev => prev.map(w => w.id === workflow.id ? workflow : w));
+  }, []);
+
+  return { workflows, setInitial, addWorkflow, updateWorkflow };
+}
diff --git a/src/server/api/router.ts b/src/server/api/router.ts
index ef8baca..76881be 100644
--- a/src/server/api/router.ts
+++ b/src/server/api/router.ts
@@ -10,6 +10,7 @@ import searchRouter from './search.js';
 import batchTemplatesRouter from './batchTemplates.js';
 import settingsRouter from './settings.js';
 import debatesRouter from './debates.js';
+import workflowsRouter from './workflows.js';
 import worktreesRouter from './worktrees.js';
 import statsRouter from './stats.js';
 import knowledgeBaseRouter from './knowledgeBase.js';
@@ -30,6 +31,7 @@ router.use('/search', searchRouter);
 router.use('/batch-templates', batchTemplatesRouter);
 router.use('/settings', settingsRouter);
 router.use('/debates', debatesRouter);
+router.use('/workflows', workflowsRouter);
 router.use('/worktrees', worktreesRouter);
 router.use('/stats', statsRouter);
 router.use('/knowledge-base', knowledgeBaseRouter);
diff --git a/src/server/api/workflows.ts b/src/server/api/workflows.ts
new file mode 100644
index 0000000..6ba1696
--- /dev/null
+++ b/src/server/api/workflows.ts
@@ -0,0 +1,143 @@
+import { Router } from 'express';
+import { randomUUID } from 'crypto';
+import * as queries from '../db/queries.js';
+import * as socket from '../socket/SocketManager.js';
+import { startWorkflow, resumeWorkflow, cleanupWorktree } from '../orchestrator/WorkflowManager.js';
+import type { CreateWorkflowRequest, Workflow } from '../../shared/types.js';
+
+const router = Router();
+
+// GET /api/workflows — list all workflows
+router.get('/', (_req, res) => {
+  res.json(queries.listWorkflows());
+});
+
+// GET /api/workflows/:id — get single workflow with plan/worklog content
+router.get('/:id', (req, res) => {
+  const workflow = queries.getWorkflowById(req.params.id);
+  if (!workflow) { res.status(404).json({ error: 'not found' }); return; }
+
+  // Include plan and worklog notes in the response
+  const planNote = queries.getNote(`workflow/${workflow.id}/plan`);
+  const contractNote = queries.getNote(`workflow/${workflow.id}/contract`);
+  const worklogNotes = queries.listNotes(`workflow/${workflow.id}/worklog/`);
+  const worklogs: Array<{ key: string; value: string; updated_at: number }> = [];
+  for (const n of worklogNotes) {
+    const full = queries.getNote(n.key);
+    if (full) worklogs.push({ key: n.key, value: full.value, updated_at: full.updated_at });
+  }
+
+  res.json({
+    ...workflow,
+    plan: planNote?.value ?? null,
+    contract: contractNote?.value ?? null,
+    worklogs,
+  });
+});
+
+// GET /api/workflows/:id/jobs — list all jobs for a workflow
+router.get('/:id/jobs', (req, res) => {
+  const workflow = queries.getWorkflowById(req.params.id);
+  if (!workflow) { res.status(404).json({ error: 'not found' }); return; }
+  res.json(queries.getJobsForWorkflow(req.params.id));
+});
+
+// POST /api/workflows — create + start a new workflow
+router.post('/', (req, res) => {
+  const body = req.body as CreateWorkflowRequest;
+  if (!body.task?.trim()) {
+    res.status(400).json({ error: 'task is required' });
+    return;
+  }
+
+  const workflowId = randomUUID();
+  const now = Date.now();
+  const title = body.title?.trim() || `Workflow: ${body.task.trim().slice(0, 50)}`;
+  const maxCycles = Math.min(Math.max(body.maxCycles ?? 10, 1), 50);
+
+  // Create a project for this workflow
+  const project = queries.insertProject({
+    id: randomUUID(),
+    name: title,
+    description: `Plan/review/implement workflow`,
+    created_at: now,
+    updated_at: now,
+  });
+
+  const workflow: Workflow = {
+    id: workflowId,
+    title,
+    task: body.task.trim(),
+    work_dir: body.workDir?.trim() || null,
+    implementer_model: body.implementerModel?.trim() || 'claude-sonnet-4-6',
+    reviewer_model: body.reviewerModel?.trim() || 'codex',
+    max_cycles: maxCycles,
+    current_cycle: 0,
+    current_phase: 'idle',
+    status: 'running',
+    milestones_total: 0,
+    milestones_done: 0,
+    project_id: project.id,
+    max_turns_assess: body.maxTurnsAssess ?? 50,
+    max_turns_review: body.maxTurnsReview ?? 30,
+    max_turns_implement: body.maxTurnsImplement ?? 100,
+    template_id: body.templateId?.trim() || null,
+    use_worktree: body.useWorktree === false ? 0 : 1,
+    worktree_path: null,
+    worktree_branch: null,
+    pr_url: null,
+    created_at: now,
+    updated_at: now,
+  };
+  queries.insertWorkflow(workflow);
+
+  const assessJob = startWorkflow(workflow);
+
+  socket.emitWorkflowNew(workflow);
+
+  res.status(201).json({ workflow, project, jobs: [assessJob] });
+});
+
+// POST /api/workflows/:id/cancel — cancel a running workflow
+router.post('/:id/cancel', (req, res) => {
+  const workflow = queries.getWorkflowById(req.params.id);
+  if (!workflow) { res.status(404).json({ error: 'not found' }); return; }
+  if (workflow.status !== 'running' && workflow.status !== 'blocked') {
+    res.status(400).json({ error: `Workflow is ${workflow.status}, cannot cancel` });
+    return;
+  }
+
+  const updated = queries.updateWorkflow(workflow.id, { status: 'cancelled' });
+  if (updated) socket.emitWorkflowUpdate(updated);
+
+  // Cancel any queued/running workflow jobs
+  const jobs = queries.getJobsForWorkflow(workflow.id);
+  for (const job of jobs) {
+    if (job.status === 'queued' || job.status === 'assigned') {
+      queries.updateJobStatus(job.id, 'cancelled');
+      const updatedJob = queries.getJobById(job.id);
+      if (updatedJob) socket.emitJobUpdate(updatedJob);
+    }
+  }
+
+  // Clean up the worktree (no PR for cancellations)
+  if (updated) cleanupWorktree(updated);
+
+  res.json(updated);
+});
+
+// POST /api/workflows/:id/resume — resume a blocked workflow
+router.post('/:id/resume', (req, res) => {
+  const workflow = queries.getWorkflowById(req.params.id);
+  if (!workflow) { res.status(404).json({ error: 'not found' }); return; }
+  if (workflow.status !== 'blocked') {
+    res.status(400).json({ error: `Workflow is ${workflow.status}, can only resume blocked workflows` });
+    return;
+  }
+
+  const job = resumeWorkflow(workflow);
+  const updated = queries.getWorkflowById(workflow.id);
+  res.json({ workflow: updated, jobs: [job] });
+});
+
+export default router;
diff --git a/src/server/db/database.ts b/src/server/db/database.ts
index 999e9ca..ed342ec 100644
--- a/src/server/db/database.ts
+++ b/src/server/db/database.ts
@@ -64,7 +64,6 @@ export function initDb(dbPath: string): DatabaseSync {
     db.exec('ALTER TABLE jobs ADD COLUMN project_id TEXT REFERENCES projects(id)');
   }
   db.exec('CREATE INDEX IF NOT EXISTS idx_jobs_project ON jobs(project_id)');
-  db.exec('CREATE INDEX IF NOT EXISTS idx_jobs_archived ON jobs(archived_at)');
 
   const agentCols: string[] = (db.prepare('PRAGMA table_info(agents)').all() as any[]).map((r: any) => r.name);
   if (!agentCols.includes('parent_agent_id')) {
@@ -312,6 +311,7 @@ export function initDb(dbPath: string): DatabaseSync {
   if (!jobCols.includes('archived_at')) {
     db.exec('ALTER TABLE jobs ADD COLUMN archived_at INTEGER');
   }
+  db.exec('CREATE INDEX IF NOT EXISTS idx_jobs_archived ON jobs(archived_at)');
   if (!jobCols.includes('created_by_agent_id')) {
     db.exec('ALTER TABLE jobs ADD COLUMN created_by_agent_id TEXT');
   }
@@ -387,6 +387,56 @@ export function initDb(dbPath: string): DatabaseSync {
   )`);
   db.exec('CREATE INDEX IF NOT EXISTS idx_pr_review_msgs_review ON pr_review_messages(review_id)');
 
+  // ── Workflows (structured plan/review/implement cycles) ─────────────────────
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS workflows (
+      id                  TEXT PRIMARY KEY,
+      title               TEXT NOT NULL,
+      task                TEXT NOT NULL,
+      work_dir            TEXT,
+      implementer_model   TEXT NOT NULL DEFAULT 'claude-sonnet-4-6',
+      reviewer_model      TEXT NOT NULL DEFAULT 'codex',
+      max_cycles          INTEGER NOT NULL DEFAULT 10,
+      current_cycle       INTEGER NOT NULL DEFAULT 0,
+      current_phase       TEXT NOT NULL DEFAULT 'idle',
+      status              TEXT NOT NULL DEFAULT 'running',
+      milestones_total    INTEGER NOT NULL DEFAULT 0,
+      milestones_done     INTEGER NOT NULL DEFAULT 0,
+      project_id          TEXT REFERENCES projects(id),
+      max_turns_assess    INTEGER NOT NULL DEFAULT 50,
+      max_turns_review    INTEGER NOT NULL DEFAULT 30,
+      max_turns_implement INTEGER NOT NULL DEFAULT 100,
+      template_id         TEXT REFERENCES templates(id),
+      use_worktree        INTEGER NOT NULL DEFAULT 1,
+      created_at          INTEGER NOT NULL,
+      updated_at          INTEGER NOT NULL
+    )
+  `);
+  db.exec('CREATE INDEX IF NOT EXISTS idx_workflows_status ON workflows(status)');
+
+  if (!jobCols.includes('workflow_id')) {
+    db.exec('ALTER TABLE jobs ADD COLUMN workflow_id TEXT REFERENCES workflows(id)');
+  }
+  if (!jobCols.includes('workflow_cycle')) {
+    db.exec('ALTER TABLE jobs ADD COLUMN workflow_cycle INTEGER');
+  }
+  if (!jobCols.includes('workflow_phase')) {
+    db.exec('ALTER TABLE jobs ADD COLUMN workflow_phase TEXT');
+  }
+  db.exec('CREATE INDEX IF NOT EXISTS idx_jobs_workflow ON jobs(workflow_id, workflow_cycle)');
+
+  // Workflow-level worktree columns (single worktree shared across all phases)
+  const workflowCols = db.prepare('PRAGMA table_info(workflows)').all().map((c: any) => c.name);
+  if (!workflowCols.includes('worktree_path')) {
+    db.exec('ALTER TABLE workflows ADD COLUMN worktree_path TEXT');
+  }
+  if (!workflowCols.includes('worktree_branch')) {
+    db.exec('ALTER TABLE workflows ADD COLUMN worktree_branch TEXT');
+  }
+  if (!workflowCols.includes('pr_url')) {
+    db.exec('ALTER TABLE workflows ADD COLUMN pr_url TEXT');
+  }
+
   // ── Performance indexes ────────────────────────────────────────────────────
   db.exec('CREATE INDEX IF NOT EXISTS idx_agents_job_id ON agents(job_id)');
   db.exec("CREATE INDEX IF NOT EXISTS idx_jobs_context_eye ON jobs(status) WHERE json_extract(context, '$.eye') = 1");
diff --git a/src/server/db/queries.ts b/src/server/db/queries.ts
index 09bb1e2..cf45f9d 100644
--- a/src/server/db/queries.ts
+++ b/src/server/db/queries.ts
@@ -1,6 +1,6 @@
 import { randomUUID } from 'crypto';
 import { getDb } from './database.js';
-import type { Job, Agent, AgentWithJob, ChildAgentSummary, Question, FileLock, AgentOutput, AgentOutputSegment, Template, Note, Project, BatchTemplate, Debate, DebateStatus, DebateRole, RetryPolicy, JobStatus, AgentStatus, SearchResult, AgentWarning, Worktree, Nudge, KBEntry, Review, TemplateModelStat, ReviewStatus, Discussion, DiscussionMessage, DiscussionStatus, DiscussionCategory, DiscussionPriority, Proposal, ProposalMessage, ProposalStatus, ProposalCategory, ProposalComplexity } from '../../shared/types.js';
+import type { Job, Agent, AgentWithJob, ChildAgentSummary, Question, FileLock, AgentOutput, AgentOutputSegment, Template, Note, Project, BatchTemplate, Debate, DebateStatus, DebateRole, RetryPolicy, JobStatus, AgentStatus, SearchResult, AgentWarning, Worktree, Nudge, KBEntry, Review, TemplateModelStat, ReviewStatus, Discussion, DiscussionMessage, DiscussionStatus, DiscussionCategory, DiscussionPriority, Proposal, ProposalMessage, ProposalStatus, ProposalCategory, ProposalComplexity, Workflow, WorkflowStatus, WorkflowPhase } from '../../shared/types.js';
 
 // node:sqlite returns null-prototype objects; shallow-copy to a regular object.
 // SQLite rows are always flat scalars so a shallow copy is sufficient and far
@@ -43,12 +43,15 @@ export function insertJob(job: {
   created_by_agent_id?: string | null;
   pre_debate_id?: string | null;
   pre_debate_summary?: string | null;
+  workflow_id?: string | null;
+  workflow_cycle?: number | null;
+  workflow_phase?: WorkflowPhase | null;
 }): Job {
   const db = getDb();
   const now = Date.now();
   db.prepare(`
-    INSERT INTO jobs (id, title, description, context, status, priority, work_dir, max_turns, model, template_id, depends_on, is_interactive, use_worktree, project_id, debate_id, debate_loop, debate_round, debate_role, scheduled_at, repeat_interval_ms, retry_policy, max_retries, retry_count, original_job_id, completion_checks, review_config, review_status, review_parent_job_id, created_by_agent_id, pre_debate_id, pre_debate_summary, created_at, updated_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO jobs (id, title, description, context, status, priority, work_dir, max_turns, model, template_id, depends_on, is_interactive, use_worktree, project_id, debate_id, debate_loop, debate_round, debate_role, scheduled_at, repeat_interval_ms, retry_policy, max_retries, retry_count, original_job_id, completion_checks, review_config, review_status, review_parent_job_id, created_by_agent_id, pre_debate_id, pre_debate_summary, workflow_id, workflow_cycle, workflow_phase, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(
     job.id, job.title, job.description, job.context,
     job.status ?? 'queued', job.priority,
@@ -76,6 +79,9 @@ export function insertJob(job: {
     job.created_by_agent_id ?? null,
     job.pre_debate_id ?? null,
     job.pre_debate_summary ?? null,
+    job.workflow_id ?? null,
+    job.workflow_cycle ?? null,
+    job.workflow_phase ?? null,
     now, now
   );
   return getJobById(job.id)!;
@@ -647,7 +653,7 @@ function enrichAgent(agent: Agent): AgentWithJob {
   const jobRow = db.prepare('SELECT * FROM jobs WHERE id = ?').get(agent.job_id);
   if (!jobRow) {
     // Job was deleted while agent still references it — return a stub
-    const stub: Job = { id: agent.job_id, title: '(deleted job)', description: '', context: null, status: 'failed', priority: 0, model: null, template_id: null, depends_on: null, is_interactive: 0, use_worktree: 0, project_id: null, flagged: 0, debate_id: null, debate_loop: null, debate_round: null, debate_role: null, scheduled_at: null, repeat_interval_ms: null, retry_policy: 'none', max_retries: 0, retry_count: 0, original_job_id: null, completion_checks: null, review_config: null, review_status: null, review_parent_job_id: null, created_by_agent_id: null, pre_debate_id: null, pre_debate_summary: null, archived_at: null, created_at: 0, updated_at: 0 };
+    const stub: Job = { id: agent.job_id, title: '(deleted job)', description: '', context: null, status: 'failed', priority: 0, model: null, template_id: null, depends_on: null, is_interactive: 0, use_worktree: 0, project_id: null, flagged: 0, debate_id: null, debate_loop: null, debate_round: null, debate_role: null, scheduled_at: null, repeat_interval_ms: null, retry_policy: 'none', max_retries: 0, retry_count: 0, original_job_id: null, completion_checks: null, review_config: null, review_status: null, review_parent_job_id: null, created_by_agent_id: null, pre_debate_id: null, pre_debate_summary: null, workflow_id: null, workflow_cycle: null, workflow_phase: null, archived_at: null, created_at: 0, updated_at: 0 };
     return { ...agent, job: stub, template_name: null, pending_question: null, active_locks: [], child_agents: [], warnings: [] };
   }
   const job = cast<Job>(jobRow);
@@ -2070,3 +2076,55 @@ export function getPrReviewsWithNewUserReplies(): any[] {
     ) ORDER BY pr.updated_at DESC
   `).all().map((r: any) => cast<any>(r));
 }
+
+// ─── Workflows ────────────────────────────────────────────────────────────────
+
+export function insertWorkflow(workflow: Workflow): Workflow {
+  const db = getDb();
+  db.prepare(`
+    INSERT INTO workflows (id, title, task, work_dir, implementer_model, reviewer_model, max_cycles, current_cycle, current_phase, status, milestones_total, milestones_done, project_id, max_turns_assess, max_turns_review, max_turns_implement, template_id, use_worktree, worktree_path, worktree_branch, pr_url, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    workflow.id, workflow.title, workflow.task, workflow.work_dir,
+    workflow.implementer_model, workflow.reviewer_model,
+    workflow.max_cycles, workflow.current_cycle, workflow.current_phase, workflow.status,
+    workflow.milestones_total, workflow.milestones_done,
+    workflow.project_id,
+    workflow.max_turns_assess, workflow.max_turns_review, workflow.max_turns_implement,
+    workflow.template_id, workflow.use_worktree,
+    workflow.worktree_path ?? null, workflow.worktree_branch ?? null, workflow.pr_url ?? null,
+    workflow.created_at, workflow.updated_at
+  );
+  return getWorkflowById(workflow.id)!;
+}
+
+export function getWorkflowById(id: string): Workflow | null {
+  const db = getDb();
+  const row = db.prepare('SELECT * FROM workflows WHERE id = ?').get(id);
+  return row ? cast<Workflow>(row) : null;
+}
+
+export function listWorkflows(): Workflow[] {
+  const db = getDb();
+  const rows = db.prepare('SELECT * FROM workflows ORDER BY created_at DESC').all();
+  return rows.map((r: any) => cast<Workflow>(r));
+}
+
+export function updateWorkflow(id: string, fields: Partial<Pick<Workflow, 'current_cycle' | 'current_phase' | 'status' | 'milestones_total' | 'milestones_done' | 'worktree_path' | 'worktree_branch' | 'pr_url'>>): Workflow | null {
+  const db = getDb();
+  const sets: string[] = ['updated_at = ?'];
+  const values: unknown[] = [Date.now()];
+  for (const [k, v] of Object.entries(fields)) {
+    sets.push(`${k} = ?`);
+    values.push(v);
+  }
+  values.push(id);
+  db.prepare(`UPDATE workflows SET ${sets.join(', ')} WHERE id = ?`).run(...values);
+  return getWorkflowById(id);
+}
+
+export function getJobsForWorkflow(workflowId: string): Job[] {
+  const db = getDb();
+  const rows = db.prepare('SELECT * FROM jobs WHERE workflow_id = ? ORDER BY workflow_cycle ASC, created_at ASC').all(workflowId);
+  return rows.map((r: any) => cast<Job>(r));
+}
diff --git a/src/server/index.ts b/src/server/index.ts
index 1dfe13a..4778e1b 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -86,6 +86,7 @@ async function main() {
       projects: queries.listProjects(),
       batchTemplates: queries.listBatchTemplates(),
       debates: queries.listDebates(),
+      workflows: queries.listWorkflows(),
       discussions: queries.listDiscussions(),
       proposals: queries.listProposals(),
     };
diff --git a/src/server/orchestrator/AgentRunner.ts b/src/server/orchestrator/AgentRunner.ts
index 2efd962..8182e7b 100644
--- a/src/server/orchestrator/AgentRunner.ts
+++ b/src/server/orchestrator/AgentRunner.ts
@@ -6,6 +6,7 @@ import * as queries from '../db/queries.js';
 import * as socket from '../socket/SocketManager.js';
 import { getFileLockRegistry } from './FileLockRegistry.js';
 import { onJobCompleted as debateOnJobCompleted } from './DebateManager.js';
+import { onJobCompleted as workflowOnJobCompleted } from './WorkflowManager.js';
 import { runCompletionChecks } from './CompletionChecks.js';
 import { handleRetry } from './RetryManager.js';
 import { triageLearnings } from './MemoryTriager.js';
@@ -523,6 +524,7 @@ export async function handleJobCompletion(
     try { socket.emitJobUpdate(updatedJob); } catch (err) { console.error(`[agent ${agentId}] emitJobUpdate error:`, err); }
     // If this job is part of a debate, check if the round is complete
     try { debateOnJobCompleted(updatedJob); } catch (err) { console.error(`[agent ${agentId}] debateOnJobCompleted error:`, err); }
+    try { workflowOnJobCompleted(updatedJob); } catch (err) { console.error(`[agent ${agentId}] workflowOnJobCompleted error:`, err); }
     // If the job has a repeat interval, queue the next run regardless of success/failure
     if (updatedJob.repeat_interval_ms) {
       try {
diff --git a/src/server/orchestrator/PtyManager.ts b/src/server/orchestrator/PtyManager.ts
index 8dec190..a8be0c0 100644
--- a/src/server/orchestrator/PtyManager.ts
+++ b/src/server/orchestrator/PtyManager.ts
@@ -7,7 +7,7 @@ import * as queries from '../db/queries.js';
 import * as socket from '../socket/SocketManager.js';
 import { SYSTEM_PROMPT, HOOK_SETTINGS, handleJobCompletion, cancelledAgents, startTailing, stopTailing, readClaudeMd, buildMemorySection } from './AgentRunner.js';
 import type { Job } from '../../shared/types.js';
-import { isCodexModel, codexModelName } from '../../shared/types.js';
+import { isCodexModel, codexModelName, isAutoExitJob } from '../../shared/types.js';
 
 const CLAUDE = process.env.CLAUDE_BIN ?? 'claude';
 const CODEX = process.env.CODEX_BIN ?? 'codex';
@@ -187,9 +187,9 @@ export function startInteractiveAgent({ agentId, job, cols = 100, rows = 50, res
   const useCodex = isCodexModel(model);
   if (useCodex) ensureCodexTrusted(workDir);
 
-  // Debate-stage jobs (post_action, verification_*) run Claude with --print so the process
-  // exits automatically when the task is done, triggering the next verification stage.
-  const isDebateStage = !!(job as any).debate_role;
+  // Debate-stage and workflow-phase jobs run Claude with --print so the process
+  // exits automatically when the task is done, triggering the next stage.
+  const isDebateStage = isAutoExitJob(job as any);
 
   let execLine: string;
   if (useCodex) {
@@ -365,7 +365,7 @@ export function attachPty(agentId: string, job: Job, cols = 100, rows = 50): voi
 
   // For debate-stage agents running --print, start tailing the tee'd .ndjson file so
   // agent_output is populated live and the UI streams output as it arrives.
-  if (!!(job as any).debate_role) {
+  if (isAutoExitJob(job as any)) {
     const ndjsonPath = path.join(PTY_LOG_DIR, `${agentId}.ndjson`);
     startTailing(agentId, job, ndjsonPath, 0, null);
   }
@@ -404,6 +404,13 @@ export function attachPty(agentId: string, job: Job, cols = 100, rows = 50): voi
       })(),
     });
   } catch (err: any) {
+    // For auto-exit jobs (workflow/debate phases), tailing is already running above —
+    // the job will complete naturally when Claude finishes and calls finish_job.
+    // PTY attachment is visual-only for these jobs, so log a warning and carry on.
+    if (isAutoExitJob(job as any)) {
+      console.warn(`[pty ${agentId}] PTY attach failed (tailing continues):`, err.message);
+      return;
+    }
     console.error(`[pty ${agentId}] failed to spawn PTY:`, err.message);
     queries.updateAgent(agentId, { status: 'failed', error_message: err.message, finished_at: Date.now() });
     queries.updateJobStatus(job.id, 'failed');
@@ -455,11 +462,11 @@ export function attachPty(agentId: string, job: Job, cols = 100, rows = 50): voi
         // For interactive agents: user ended the session = done
         // For debate-stage jobs: --print mode exits naturally = done
         // For other non-interactive agents: tmux exit without finish_job = failed
-        const isDebateStage = !!(job as any).debate_role;
+        const isDebateStage = isAutoExitJob(job as any);
         const status = (job.is_interactive || isDebateStage) ? 'done' : 'failed';
         const errorMsg = (job.is_interactive || isDebateStage) ? null : 'Agent session ended without calling finish_job.';
 
-        // For debate-stage agents, stop the live tailer then flush any lines it missed
+        // For auto-exit agents, stop the live tailer then flush any lines it missed
         // in the small race window between the last poll and the PTY exit.
         if (isDebateStage) {
           stopTailing(agentId);
diff --git a/src/server/orchestrator/StuckJobWatchdog.ts b/src/server/orchestrator/StuckJobWatchdog.ts
index e789ccd..8ad2ee5 100644
--- a/src/server/orchestrator/StuckJobWatchdog.ts
+++ b/src/server/orchestrator/StuckJobWatchdog.ts
@@ -24,7 +24,7 @@ import { getFileLockRegistry } from './FileLockRegistry.js';
 import { isTmuxSessionAlive, startInteractiveAgent, saveSnapshot } from './PtyManager.js';
 import { handleRetry } from './RetryManager.js';
 import { orphanedWaits, hasActiveTransport } from '../mcp/McpServer.js';
-import { isCodexModel } from '../../shared/types.js';
+import { isCodexModel, isAutoExitJob } from '../../shared/types.js';
 
 const WATCHDOG_INTERVAL_MS = 30_000;
 
@@ -106,7 +106,7 @@ function check(): void {
       const IDLE_THRESHOLD_MS = 90 * 60 * 1000; // 90 minutes
       if (tmuxAlive && agent.pid == null && !agent.pending_wait_ids) {
         const idleJob = queries.getJobById(agent.job_id);
-        const isStuckCandidate = idleJob && !idleJob.is_interactive && !(idleJob as any).debate_role;
+        const isStuckCandidate = idleJob && !idleJob.is_interactive && !isAutoExitJob(idleJob as any);
         const idleMs = Date.now() - agent.updated_at;
         if (isStuckCandidate && idleMs > IDLE_THRESHOLD_MS) {
           console.warn(`[watchdog] non-interactive tmux agent ${agent.id} idle ${Math.round(idleMs / 60000)}min without MCP activity — killing stale session`);
@@ -215,7 +215,7 @@ function check(): void {
     } else {
       // Tmux-based agent: session ended without finish_job being called.
       // Interactive or debate-stage → done; other non-interactive → failed.
-      const isDebateStage = !!(job as any)?.debate_role;
+      const isDebateStage = job ? isAutoExitJob(job as any) : false;
       const finalStatus = (job?.is_interactive || isDebateStage) ? 'done' : 'failed';
       console.log(
         `[watchdog] agent ${agent.id} (tmux-based) — session gone, marking ${finalStatus}`
diff --git a/src/server/orchestrator/WorkQueueManager.ts b/src/server/orchestrator/WorkQueueManager.ts
index 0eddd4f..c8af319 100644
--- a/src/server/orchestrator/WorkQueueManager.ts
+++ b/src/server/orchestrator/WorkQueueManager.ts
@@ -7,7 +7,7 @@ import { runAgent } from './AgentRunner.js';
 import { startInteractiveAgent } from './PtyManager.js';
 import { resolveModel } from './ModelClassifier.js';
 import type { Job } from '../../shared/types.js';
-import { isCodexModel } from '../../shared/types.js';
+import { isCodexModel, isAutoExitJob } from '../../shared/types.js';
 
 let _maxConcurrent = Number(process.env.MAX_CONCURRENT_AGENTS ?? 20);
 const POLL_INTERVAL_MS = 2000;
@@ -83,9 +83,9 @@ async function tick(): Promise<void> {
     // Debate-stage jobs use --print inside tmux (piped through tee to .ndjson for UI display)
     // and exit naturally — no finish_job needed.
     const useCodexBatch = isCodexModel((dispatchJob as any).model ?? null) && !dispatchJob.is_interactive;
-    const isDebateStage = !!(dispatchJob as any).debate_role;
+    const isDebateStage = isAutoExitJob(dispatchJob as any);
     const autoFinish = !dispatchJob.is_interactive && !isDebateStage;
-    console.log(`[queue] dispatching "${job.title}" → agent ${agentId} (model: ${model}, interactive: ${!!readyJob.is_interactive}${readyJob.use_worktree ? ', worktree' : ''}${useCodexBatch ? ', codex-batch' : ''}${isDebateStage ? ', debate-stage' : ''})`);
+    console.log(`[queue] dispatching "${job.title}" → agent ${agentId} (model: ${model}, interactive: ${!!readyJob.is_interactive}${readyJob.use_worktree ? ', worktree' : ''}${useCodexBatch ? ', codex-batch' : ''}${isDebateStage ? ', auto-exit' : ''})`);
     if (useCodexBatch) {
       runAgent({ agentId, job: dispatchJob });
     } else {
diff --git a/src/server/orchestrator/WorkflowManager.ts b/src/server/orchestrator/WorkflowManager.ts
new file mode 100644
index 0000000..4c08b29
--- /dev/null
+++ b/src/server/orchestrator/WorkflowManager.ts
@@ -0,0 +1,417 @@
+import { randomUUID } from 'crypto';
+import { execSync } from 'child_process';
+import path from 'path';
+import * as queries from '../db/queries.js';
+import * as socket from '../socket/SocketManager.js';
+import type { Job, Workflow, WorkflowPhase } from '../../shared/types.js';
+import { buildAssessPrompt, buildReviewPrompt, buildImplementPrompt } from './WorkflowPrompts.js';
+
+// Track jobs we've already processed to prevent double-exit race from triggering
+// duplicate spawns. Same pattern as DebateManager.
+const _processedJobs = new Set<string>();
+
+/**
+ * Called from AgentRunner.handleJobCompletion after a job's status is finalized.
+ * If the job belongs to a workflow, advances to the next phase or completes the workflow.
+ */
+export function onJobCompleted(job: Job): void {
+  if (!job.workflow_id) return;
+  if (_processedJobs.has(job.id)) return;
+  _processedJobs.add(job.id);
+  // Prevent unbounded growth
+  if (_processedJobs.size > 500) {
+    const iter = _processedJobs.values();
+    for (let i = 0; i < 250; i++) iter.next();
+    // Keep the newer half
+    const keep = new Set<string>();
+    for (const v of iter) keep.add(v);
+    _processedJobs.clear();
+    for (const v of keep) _processedJobs.add(v);
+  }
+
+  try {
+    _onJobCompleted(job);
+  } catch (err) {
+    console.error(`[workflow] error handling job completion for job ${job.id}:`, err);
+  }
+}
+
+function _onJobCompleted(job: Job): void {
+  const workflow = queries.getWorkflowById(job.workflow_id!);
+  if (!workflow || workflow.status !== 'running') return;
+
+  // If the phase job failed or was cancelled, mark workflow as blocked
+  if (job.status === 'failed' || job.status === 'cancelled') {
+    console.log(`[workflow ${workflow.id}] phase '${job.workflow_phase}' job ${job.id} ${job.status} — marking workflow blocked`);
+    updateAndEmit(workflow.id, {
+      status: 'blocked',
+      current_phase: job.workflow_phase ?? 'idle',
+    });
+    return;
+  }
+
+  // Parse milestones from the plan note
+  const planNote = queries.getNote(`workflow/${workflow.id}/plan`);
+  const milestones = parseMilestones(planNote?.value ?? '');
+
+  // Phase-specific transitions
+  switch (job.workflow_phase) {
+    case 'assess': {
+      // After assess: validate plan was written, then move to review
+      if (!planNote?.value) {
+        console.log(`[workflow ${workflow.id}] assess phase completed but no plan note found — marking blocked`);
+        updateAndEmit(workflow.id, { status: 'blocked', current_phase: 'assess' as WorkflowPhase });
+        return;
+      }
+      updateAndEmit(workflow.id, {
+        milestones_total: milestones.total,
+        milestones_done: milestones.done,
+        current_cycle: 1,
+      });
+      spawnPhaseJob(queries.getWorkflowById(workflow.id)!, 'review', 1);
+      break;
+    }
+
+    case 'review': {
+      // After review: update milestones (reviewer may have added/removed), then implement
+      updateAndEmit(workflow.id, {
+        milestones_total: milestones.total,
+        milestones_done: milestones.done,
+      });
+      const updated = queries.getWorkflowById(workflow.id)!;
+      if (milestones.total > 0 && milestones.done >= milestones.total) {
+        console.log(`[workflow ${workflow.id}] all milestones complete after review — marking complete`);
+        updateAndEmit(workflow.id, { status: 'complete', current_phase: 'idle' as WorkflowPhase });
+        finalizeWorkflow(queries.getWorkflowById(workflow.id)!);
+      } else {
+        spawnPhaseJob(updated, 'implement', updated.current_cycle);
+      }
+      break;
+    }
+
+    case 'implement': {
+      // After implement: update milestones, check if done or advance to next cycle
+      updateAndEmit(workflow.id, {
+        milestones_total: milestones.total,
+        milestones_done: milestones.done,
+      });
+      const updated = queries.getWorkflowById(workflow.id)!;
+
+      if (milestones.total > 0 && milestones.done >= milestones.total) {
+        console.log(`[workflow ${workflow.id}] all ${milestones.total} milestones complete — marking complete`);
+        updateAndEmit(workflow.id, { status: 'complete', current_phase: 'idle' as WorkflowPhase });
+        finalizeWorkflow(queries.getWorkflowById(workflow.id)!);
+      } else if (updated.current_cycle >= updated.max_cycles) {
+        console.log(`[workflow ${workflow.id}] reached max cycles (${updated.max_cycles}) — marking complete`);
+        updateAndEmit(workflow.id, { status: 'complete', current_phase: 'idle' as WorkflowPhase });
+        finalizeWorkflow(queries.getWorkflowById(workflow.id)!);
+      } else {
+        // Advance to next cycle's review phase
+        const nextCycle = updated.current_cycle + 1;
+        updateAndEmit(workflow.id, { current_cycle: nextCycle });
+        spawnPhaseJob(queries.getWorkflowById(workflow.id)!, 'review', nextCycle);
+      }
+      break;
+    }
+
+    default:
+      console.warn(`[workflow ${workflow.id}] unknown phase '${job.workflow_phase}' on job ${job.id}`);
+  }
+}
+
+// ─── Milestone Parsing ────────────────────────────────────────────────────────
+
+const CHECKBOX_CHECKED = /^[\t ]*[-*][\t ]+\[[xX]\]/;
+const CHECKBOX_UNCHECKED = /^[\t ]*[-*][\t ]+\[\s?\]/;
+
+export function parseMilestones(planText: string): { total: number; done: number } {
+  let done = 0;
+  let unchecked = 0;
+  for (const line of planText.split('\n')) {
+    if (CHECKBOX_CHECKED.test(line)) done++;
+    else if (CHECKBOX_UNCHECKED.test(line)) unchecked++;
+  }
+  return { total: done + unchecked, done };
+}
+
+// ─── Phase Job Spawning ─────────────────────────────────────────────────────
+
+function spawnPhaseJob(workflow: Workflow, phase: WorkflowPhase, cycle: number): void {
+  const phaseLabels: Record<string, string> = { assess: 'Assess', review: 'Review', implement: 'Implement' };
+  const label = phaseLabels[phase] ?? phase;
+
+  // Choose model and max_turns based on phase
+  let model: string;
+  let maxTurns: number;
+  let prompt: string;
+
+  switch (phase) {
+    case 'assess':
+      model = workflow.implementer_model;
+      maxTurns = workflow.max_turns_assess;
+      prompt = buildAssessPrompt(workflow);
+      break;
+    case 'review':
+      model = workflow.reviewer_model;
+      maxTurns = workflow.max_turns_review;
+      prompt = buildReviewPrompt(workflow, cycle);
+      break;
+    case 'implement':
+      model = workflow.implementer_model;
+      maxTurns = workflow.max_turns_implement;
+      prompt = buildImplementPrompt(workflow, cycle);
+      break;
+    default:
+      throw new Error(`Invalid phase: ${phase}`);
+  }
+
+  const job = queries.insertJob({
+    id: randomUUID(),
+    title: `[Workflow C${cycle}] ${label}`,
+    description: prompt,
+    context: null,
+    priority: 0,
+    model,
+    template_id: workflow.template_id,
+    // All phases share the single workflow-level worktree (created at startWorkflow).
+    // use_worktree=0 tells WorkQueueManager not to create another one.
+    work_dir: workflow.worktree_path ?? workflow.work_dir,
+    max_turns: maxTurns,
+    project_id: workflow.project_id,
+    use_worktree: 0,
+    workflow_id: workflow.id,
+    workflow_cycle: cycle,
+    workflow_phase: phase,
+  });
+
+  socket.emitJobNew(job);
+
+  // Update workflow state
+  updateAndEmit(workflow.id, {
+    current_phase: phase,
+    current_cycle: cycle,
+  });
+
+  console.log(`[workflow ${workflow.id}] spawned ${phase} job ${job.id.slice(0, 8)} (cycle ${cycle}, model: ${model})`);
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Start a workflow by spawning the assess phase job.
+ * Called from the API route when a workflow is created.
+ */
+export function startWorkflow(workflow: Workflow): Job {
+  // Create a single worktree for the entire workflow so all phases share one branch.
+  // Changes accumulate linearly: assess → review → implement → review → ...
+  let activeWorkflow = workflow;
+  if (workflow.use_worktree && workflow.work_dir) {
+    try {
+      const shortId = workflow.id.slice(0, 8);
+      const slug = workflow.title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 40);
+      const branchName = `workflow/${slug}-${shortId}`;
+      const worktreePath = path.resolve(workflow.work_dir, '..', '.orchestrator-worktrees', `wf-${shortId}`);
+      execSync(`git worktree add ${JSON.stringify(worktreePath)} -b ${JSON.stringify(branchName)}`, {
+        cwd: workflow.work_dir,
+        timeout: 30000,
+        stdio: 'pipe',
+      });
+      activeWorkflow = queries.updateWorkflow(workflow.id, {
+        worktree_path: worktreePath,
+        worktree_branch: branchName,
+      }) ?? workflow;
+      console.log(`[workflow ${workflow.id}] created worktree at ${worktreePath} (branch: ${branchName})`);
+    } catch (err: any) {
+      console.warn(`[workflow ${workflow.id}] worktree creation failed, using work_dir directly:`, err.message);
+    }
+  }
+
+  const prompt = buildAssessPrompt(activeWorkflow);
+  const job = queries.insertJob({
+    id: randomUUID(),
+    title: `[Workflow C0] Assess`,
+    description: prompt,
+    context: null,
+    priority: 0,
+    model: activeWorkflow.implementer_model,
+    template_id: activeWorkflow.template_id,
+    work_dir: activeWorkflow.worktree_path ?? activeWorkflow.work_dir,
+    max_turns: activeWorkflow.max_turns_assess,
+    project_id: activeWorkflow.project_id,
+    use_worktree: 0,
+    workflow_id: activeWorkflow.id,
+    workflow_cycle: 0,
+    workflow_phase: 'assess',
+  });
+
+  socket.emitJobNew(job);
+  updateAndEmit(activeWorkflow.id, { current_phase: 'assess' as WorkflowPhase, current_cycle: 0 });
+  console.log(`[workflow ${activeWorkflow.id}] started — assess job ${job.id.slice(0, 8)}`);
+  return job;
+}
+
+/**
+ * Resume a blocked workflow by re-spawning the phase that failed.
+ */
+export function resumeWorkflow(workflow: Workflow): Job {
+  if (workflow.status !== 'blocked') {
+    throw new Error(`Cannot resume workflow in status '${workflow.status}'`);
+  }
+
+  updateAndEmit(workflow.id, { status: 'running' });
+  const updated = queries.getWorkflowById(workflow.id)!;
+
+  // Re-spawn the phase that was blocked
+  const phase = updated.current_phase === 'idle' ? 'assess' : updated.current_phase;
+  const cycle = updated.current_cycle;
+
+  let model: string;
+  let maxTurns: number;
+  let prompt: string;
+
+  switch (phase) {
+    case 'assess':
+      model = updated.implementer_model;
+      maxTurns = updated.max_turns_assess;
+      prompt = buildAssessPrompt(updated);
+      break;
+    case 'review':
+      model = updated.reviewer_model;
+      maxTurns = updated.max_turns_review;
+      prompt = buildReviewPrompt(updated, cycle);
+      break;
+    case 'implement':
+      model = updated.implementer_model;
+      maxTurns = updated.max_turns_implement;
+      prompt = buildImplementPrompt(updated, cycle);
+      break;
+    default:
+      throw new Error(`Cannot resume from phase '${phase}'`);
+  }
+
+  const job = queries.insertJob({
+    id: randomUUID(),
+    title: `[Workflow C${cycle}] ${phase.charAt(0).toUpperCase() + phase.slice(1)} (resumed)`,
+    description: prompt,
+    context: null,
+    priority: 0,
+    model,
+    template_id: updated.template_id,
+    work_dir: updated.worktree_path ?? updated.work_dir,
+    max_turns: maxTurns,
+    project_id: updated.project_id,
+    use_worktree: 0,
+    workflow_id: updated.id,
+    workflow_cycle: cycle,
+    workflow_phase: phase as WorkflowPhase,
+  });
+
+  socket.emitJobNew(job);
+  console.log(`[workflow ${workflow.id}] resumed — ${phase} job ${job.id.slice(0, 8)} (cycle ${cycle})`);
+  return job;
+}
+
+// ─── Finalization & Cleanup ──────────────────────────────────────────────────
+
+/**
+ * Called when a workflow completes successfully.
+ * Pushes the worktree branch, opens a GitHub PR, then removes the local worktree.
+ */
+export function finalizeWorkflow(workflow: Workflow): void {
+  const { worktree_path, worktree_branch, work_dir } = workflow;
+  if (!worktree_path || !work_dir) return;
+
+  try {
+    // Count commits on the branch that aren't on the remote default branch
+    let hasCommits = false;
+    try {
+      const n = execSync(
+        'git rev-list --count HEAD ^origin/HEAD 2>/dev/null || git rev-list --count HEAD',
+        { cwd: worktree_path, stdio: 'pipe', timeout: 10000, shell: true }
+      ).toString().trim();
+      hasCommits = parseInt(n, 10) > 0;
+    } catch { /* not a git repo or no remote — skip PR */ }
+
+    if (hasCommits && worktree_branch) {
+      try {
+        // Push branch to remote
+        execSync(`git push -u origin ${JSON.stringify(worktree_branch)}`, {
+          cwd: worktree_path, stdio: 'pipe', timeout: 30000,
+        });
+
+        // Build PR body from plan note milestones
+        const planNote = queries.getNote(`workflow/${workflow.id}/plan`);
+        const body = _buildPrBody(workflow, planNote?.value ?? null);
+        const title = `[Workflow] ${workflow.title}`;
+
+        // Create PR via gh CLI
+        const prUrl = execSync(
+          `gh pr create --title ${JSON.stringify(title)} --body ${JSON.stringify(body)} --head ${JSON.stringify(worktree_branch)}`,
+          { cwd: worktree_path, stdio: 'pipe', timeout: 30000 }
+        ).toString().trim();
+
+        updateAndEmit(workflow.id, { pr_url: prUrl });
+        console.log(`[workflow ${workflow.id}] PR created: ${prUrl}`);
+      } catch (err: any) {
+        console.warn(`[workflow ${workflow.id}] push/PR failed (worktree branch preserved locally):`, err.message);
+      }
+    } else {
+      console.log(`[workflow ${workflow.id}] no commits on branch — skipping PR`);
+    }
+  } finally {
+    _removeWorktree(workflow);
+  }
+}
+
+/**
+ * Called when a workflow is cancelled — skip the PR, just clean up the worktree.
+ */
+export function cleanupWorktree(workflow: Workflow): void {
+  _removeWorktree(workflow);
+}
+
+function _removeWorktree(workflow: Workflow): void {
+  const { worktree_path, work_dir } = workflow;
+  if (!worktree_path || !work_dir) return;
+  try {
+    execSync(`git worktree remove --force ${JSON.stringify(worktree_path)}`, {
+      cwd: work_dir, stdio: 'pipe', timeout: 15000,
+    });
+    execSync('git worktree prune', { cwd: work_dir, stdio: 'pipe', timeout: 10000 });
+    console.log(`[workflow ${workflow.id}] worktree removed`);
+  } catch (err: any) {
+    console.warn(`[workflow ${workflow.id}] worktree removal failed:`, err.message);
+  }
+}
+
+function _buildPrBody(workflow: Workflow, planText: string | null): string {
+  const { total, done } = parseMilestones(planText ?? '');
+  const checkboxLines = planText
+    ? planText.split('\n').filter(l => /^\s*[-*]\s+\[/.test(l)).map(l => l.trim()).join('\n')
+    : '';
+  return [
+    `## ${workflow.title}`,
+    '',
+    `**Task:** ${workflow.task}`,
+    '',
+    `**Cycles:** ${workflow.current_cycle}/${workflow.max_cycles} · **Milestones:** ${done}/${total} complete`,
+    '',
+    '## Milestones',
+    checkboxLines || '_No plan available_',
+    '',
+    '---',
+    `🤖 Generated by Hurlicane autonomous agent workflow`,
+    `Implementer: \`${workflow.implementer_model}\` · Reviewer: \`${workflow.reviewer_model}\``,
+  ].join('\n');
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function updateAndEmit(id: string, fields: Parameters<typeof queries.updateWorkflow>[1]): void {
+  const updated = queries.updateWorkflow(id, fields);
+  if (updated) socket.emitWorkflowUpdate(updated);
+}
diff --git a/src/server/orchestrator/WorkflowPrompts.ts b/src/server/orchestrator/WorkflowPrompts.ts
new file mode 100644
index 0000000..0368464
--- /dev/null
+++ b/src/server/orchestrator/WorkflowPrompts.ts
@@ -0,0 +1,215 @@
+import type { Workflow } from '../../shared/types.js';
+
+/**
+ * Build the assess phase prompt (cycle 0 only).
+ * The agent scans the codebase, writes a plan with checkbox milestones, and stores it as a note.
+ */
+export function buildAssessPrompt(workflow: Workflow): string {
+  const planKey = `workflow/${workflow.id}/plan`;
+  const contractKey = `workflow/${workflow.id}/contract`;
+  return `# Workflow: Assess Phase (Cycle 0)
+
+You are the IMPLEMENTER agent in a structured plan/review/implement workflow.
+Your task in this phase is to **assess the codebase and propose a plan**.
+
+## Task
+${workflow.task}
+
+## Working Directory
+${workflow.work_dir ?? '(not specified)'}
+
+## Instructions
+
+1. **Read the codebase** — scan the project structure, key files, tests, dependencies, and configuration.
+2. **Assess quality** — note any issues, patterns, tech debt, missing tests, or areas for improvement relevant to the task.
+3. **Write a plan** with concrete milestones as markdown checkboxes. Each milestone should be achievable in a single implementation cycle.
+
+## Plan Format
+
+Write the plan to the shared scratchpad using \`write_note\` with key \`${planKey}\`. Use this exact format:
+
+\`\`\`markdown
+# Plan
+
+## Goal
+<one-line description of what this workflow aims to achieve>
+
+## Assessment
+<brief assessment of current state relevant to the task>
+
+## Milestones
+- [ ] **M1: <title>** — <description with clear acceptance criteria>
+- [ ] **M2: <title>** — <description with clear acceptance criteria>
+- [ ] **M3: <title>** — <description with clear acceptance criteria>
+(add as many as needed, but keep each achievable in one cycle)
+
+## Priority Order
+<which milestone to tackle first and why>
+
+## Risks
+<known risks, dependencies between milestones, or blockers>
+\`\`\`
+
+## Contract
+
+Also write the operating contract using \`write_note\` with key \`${contractKey}\`:
+
+\`\`\`markdown
+# Workflow Contract
+- One agent works at a time (no concurrent edits)
+- Plan milestones use checkbox format: \`- [ ]\` unchecked, \`- [x]\` checked
+- Worklog entries are append-only
+- If blocked, explain clearly so the next agent can resolve it
+- All existing tests must pass before marking a milestone complete
+- Changes must be committed with descriptive messages
+\`\`\`
+
+## Important
+- Use \`write_note("${planKey}", <plan content>)\` to store the plan.
+- Use \`write_note("${contractKey}", <contract content>)\` to store the contract.
+- Do NOT implement anything yet — this is assessment and planning only.
+- Call \`report_status\` to update your progress.`;
+}
+
+/**
+ * Build the review phase prompt.
+ * Cycle 1: plan quality review only (no code yet).
+ * Cycle 2+: code quality review of the last implementation + plan update.
+ */
+export function buildReviewPrompt(workflow: Workflow, cycle: number): string {
+  const planKey = `workflow/${workflow.id}/plan`;
+  const contractKey = `workflow/${workflow.id}/contract`;
+  const worklogKey = `workflow/${workflow.id}/worklog/cycle-${cycle - 1}`;
+  const worklogPrefix = `workflow/${workflow.id}/worklog/`;
+  const isFirstReview = cycle === 1;
+
+  const codeReviewSection = isFirstReview ? '' : `
+## Step 2: Code Review (MOST IMPORTANT)
+
+The implementer just completed cycle ${cycle - 1}. You must review the actual code changes before touching the plan.
+
+1. Read the worklog for what was changed: \`read_note("${worklogKey}")\`
+2. In the working directory (${workflow.work_dir ?? 'project root'}), inspect the implementation:
+   - Run \`git log --oneline -10\` to see recent commits
+   - Run \`git diff HEAD~1\` (or \`git diff HEAD~<n>\` to cover all commits from this cycle) to see exact code changes
+   - Read any new or heavily modified files in full
+   - Run the test suite to check for regressions
+3. **Assess code quality** — look for:
+   - Correctness: does it actually satisfy the milestone's acceptance criteria?
+   - Edge cases: null/undefined handling, empty arrays, concurrency, off-by-one errors
+   - Error handling: are failures surfaced properly or silently swallowed?
+   - Test coverage: are the new code paths tested? Are tests meaningful or just for coverage?
+   - Code style and consistency with the surrounding codebase
+   - Security: injection, unvalidated inputs, secrets in code
+   - Performance: N+1 queries, unnecessary re-renders, blocking operations
+4. **For every issue found**, add a new unchecked milestone to the plan:
+   \`- [ ] **Fix: <short title>** — <specific description of what needs to change and why>\`
+
+These fix milestones will be implemented in the next cycle. Be specific — vague feedback like "improve error handling" is not actionable.
+`;
+
+  return `# Workflow: Review Phase (Cycle ${cycle})
+
+You are the REVIEWER agent in a structured plan/review/implement workflow.
+${isFirstReview
+    ? 'This is the first review — no code has been written yet. Your job is to validate and improve the initial plan.'
+    : `Your primary job this cycle is to **review the code Claude just wrote** and add fix milestones for any issues. Then update the plan for the next cycle.`}
+
+## Task
+${workflow.task}
+
+## Working Directory
+${workflow.work_dir ?? '(not specified)'}
+
+## Step 1: Read Context
+
+1. Read the current plan: \`read_note("${planKey}")\`
+2. Read the operating contract: \`read_note("${contractKey}")\`
+3. Read all worklog entries: \`list_notes("${worklogPrefix}")\` then read each one.
+${codeReviewSection}
+## Step ${isFirstReview ? 2 : 3}: Update the Plan
+
+Rewrite the plan to reflect your review:
+- Keep all checked-off milestones (\`- [x]\`) exactly as-is
+- Reorder remaining unchecked milestones for maximum impact
+- Remove milestones made redundant by what's been implemented
+- Sharpen acceptance criteria where they were vague
+- Add any new fix or improvement milestones you identified in your code review (numbered sequentially)
+- Each milestone must be achievable in a single implementation cycle
+
+Write the updated plan back: \`write_note("${planKey}", <updated plan>)\`
+
+## Rules
+- Do NOT implement anything — review and planning only.
+- If the implementation was poor quality, add multiple specific fix milestones rather than vague notes.
+- The implementer reads your plan directly — be precise and actionable.
+- Call \`report_status\` to update your progress.`;
+}
+
+/**
+ * Build the implement phase prompt.
+ * The agent reads the plan, implements the top unchecked milestone, and writes a worklog entry.
+ */
+export function buildImplementPrompt(workflow: Workflow, cycle: number): string {
+  const planKey = `workflow/${workflow.id}/plan`;
+  const contractKey = `workflow/${workflow.id}/contract`;
+  const worklogKey = `workflow/${workflow.id}/worklog/cycle-${cycle}`;
+  const worklogPrefix = `workflow/${workflow.id}/worklog/`;
+  return `# Workflow: Implement Phase (Cycle ${cycle})
+
+You are the IMPLEMENTER agent in a structured plan/review/implement workflow.
+Your task is to **implement the top unchecked milestone** from the plan.
+
+## Task
+${workflow.task}
+
+## Working Directory
+${workflow.work_dir ?? '(not specified)'}
+
+## Instructions
+
+1. **Read the current plan**: \`read_note("${planKey}")\`
+2. **Read the operating contract**: \`read_note("${contractKey}")\`
+3. **Read previous worklog entries**: \`list_notes("${worklogPrefix}")\` then read each one to understand prior work.
+4. **Find the first unchecked milestone** (\`- [ ]\`) in the plan.
+5. **Implement it**:
+   - Make the necessary code changes
+   - Run tests and fix any issues you introduce
+   - Ensure all existing tests still pass
+   - Commit with descriptive messages
+6. **Check off the milestone** — update the plan, changing \`- [ ]\` to \`- [x]\` for the completed milestone:
+   \`write_note("${planKey}", <updated plan with milestone checked off>)\`
+7. **Write a worklog entry** using \`write_note("${worklogKey}", <worklog entry>)\`
+
+## Worklog Entry Format
+
+\`\`\`markdown
+## Cycle ${cycle} — <milestone name>
+**Owner:** Implementer
+**Timestamp:** <current UTC timestamp>
+
+### What changed
+- <file or area>: <description of change>
+
+### Commits
+- \`<short hash>\` <commit message>
+
+### Test results
+- <test suite>: <pass count> passed, <fail count> failed
+
+### Blockers
+- <blocker description> (or "None")
+
+### Next step
+<What should happen next, or "All milestones complete" if done>
+\`\`\`
+
+## Rules
+- Implement only ONE milestone per cycle.
+- Always lock files before editing (\`lock_files\`) and release when done (\`release_files\`).
+- Use \`git add <specific files>\` — never \`git add -A\` or \`git add .\`
+- If blocked, explain clearly in the worklog and set the "Next step" to describe what needs to happen.
+- Call \`report_status\` regularly to update your progress.
+- Call \`search_kb\` at the start for relevant prior knowledge.
+- Call \`report_learnings\` near the end with anything useful you discovered.`;
+}
diff --git a/src/server/orchestrator/recovery.ts b/src/server/orchestrator/recovery.ts
index f5c4e1a..d552eff 100644
--- a/src/server/orchestrator/recovery.ts
+++ b/src/server/orchestrator/recovery.ts
@@ -4,9 +4,10 @@ import { reattachAgent, getLogPath } from './AgentRunner.js';
 import { execFileSync } from 'child_process';
 import { isTmuxSessionAlive, attachPty } from './PtyManager.js';
 import { onJobCompleted as debateOnJobCompleted } from './DebateManager.js';
+import { onJobCompleted as workflowOnJobCompleted } from './WorkflowManager.js';
 import { orphanedWaits } from '../mcp/McpServer.js';
 import type { ClaudeStreamEvent } from '../../shared/types.js';
-import { isCodexModel } from '../../shared/types.js';
+import { isCodexModel, isAutoExitJob } from '../../shared/types.js';
 import { handleRetry } from './RetryManager.js';
 
 function isPidAlive(pid: number): boolean {
@@ -128,7 +129,7 @@ export function runRecovery(): void {
       } else {
         // Tmux-based path (all Claude agents, interactive or not)
         if (isTmuxSessionAlive(agent.id)) {
-          const isDebateStage = !!(job as any).debate_role;
+          const isDebateStage = isAutoExitJob(job as any);
 
           if (!job.is_interactive && !isDebateStage) {
             // Non-interactive automated agent (e.g. Eye, verification agents).
@@ -194,7 +195,7 @@ export function runRecovery(): void {
           }
         } else {
           // Interactive or debate-stage → done; other non-interactive → failed (no finish_job called)
-          const isDebateStage = !!(job as any).debate_role;
+          const isDebateStage = isAutoExitJob(job as any);
           const finalStatus = (job.is_interactive || isDebateStage) ? 'done' : 'failed';
           console.log(`[recovery] tmux agent ${agent.id} — session gone, marking ${finalStatus}`);
 
@@ -219,6 +220,7 @@ export function runRecovery(): void {
             const doneJob = queries.getJobById(agent.job_id);
             if (doneJob) {
               try { debateOnJobCompleted(doneJob); } catch (err) { console.error(`[recovery] debateOnJobCompleted error for agent ${agent.id}:`, err); }
+              try { workflowOnJobCompleted(doneJob); } catch (err) { console.error(`[recovery] workflowOnJobCompleted error for agent ${agent.id}:`, err); }
             }
             tmuxRecovered++;
           } else {
diff --git a/src/server/socket/SocketManager.ts b/src/server/socket/SocketManager.ts
index 6834492..fe37b28 100644
--- a/src/server/socket/SocketManager.ts
+++ b/src/server/socket/SocketManager.ts
@@ -1,6 +1,6 @@
 import { Server as HttpServer } from 'http';
 import { Server as SocketIoServer } from 'socket.io';
-import type { ServerToClientEvents, ClientToServerEvents, AgentWithJob, Job, Question, FileLock, AgentOutput, QueueSnapshot, Debate, AgentWarning, Discussion, DiscussionMessage, Proposal, ProposalMessage } from '../../shared/types.js';
+import type { ServerToClientEvents, ClientToServerEvents, AgentWithJob, Job, Question, FileLock, AgentOutput, QueueSnapshot, Debate, AgentWarning, Discussion, DiscussionMessage, Proposal, ProposalMessage, Workflow } from '../../shared/types.js';
 
 let _io: SocketIoServer<ClientToServerEvents, ServerToClientEvents> | null = null;
 
@@ -85,6 +85,14 @@ export function emitDebateUpdate(debate: Debate): void {
   getIo().emit('debate:update', { debate });
 }
 
+export function emitWorkflowNew(workflow: Workflow): void {
+  getIo().emit('workflow:new', { workflow });
+}
+
+export function emitWorkflowUpdate(workflow: Workflow): void {
+  getIo().emit('workflow:update', { workflow });
+}
+
 export function emitWarningNew(warning: AgentWarning): void {
   getIo().emit('warning:new', { warning });
 }
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 6544d3b..55d311b 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -8,6 +8,8 @@ export type DebateRole = 'claude' | 'codex' | 'post_action' | 'verification_revi
 export type RetryPolicy = 'none' | 'same' | 'analyze';
 export type WarningType = 'stalled' | 'high_turns' | 'long_running';
 export type ReviewStatus = 'pending_review' | 'approved' | 'needs_revision';
+export type WorkflowStatus = 'running' | 'complete' | 'blocked' | 'failed' | 'cancelled';
+export type WorkflowPhase = 'idle' | 'assess' | 'review' | 'implement';
 
 export interface Job {
   id: string;
@@ -40,6 +42,9 @@ export interface Job {
   created_by_agent_id: string | null;   // agent that created this job via create_job MCP tool
   pre_debate_id: string | null;         // FK → debates.id — job blocked until this debate finishes
   pre_debate_summary: string | null;    // debate outcome stored separately; composed at dispatch
+  workflow_id: string | null;           // FK → workflows.id
+  workflow_cycle: number | null;        // which cycle this job belongs to (0-based)
+  workflow_phase: WorkflowPhase | null; // 'assess' | 'review' | 'implement'
   archived_at: number | null;
   created_at: number;
   updated_at: number;
@@ -72,6 +77,32 @@ export interface Debate {
   updated_at: number;
 }
 
+export interface Workflow {
+  id: string;
+  title: string;
+  task: string;
+  work_dir: string | null;
+  implementer_model: string;
+  reviewer_model: string;
+  max_cycles: number;
+  current_cycle: number;
+  current_phase: WorkflowPhase;
+  status: WorkflowStatus;
+  milestones_total: number;
+  milestones_done: number;
+  project_id: string | null;
+  max_turns_assess: number;
+  max_turns_review: number;
+  max_turns_implement: number;
+  template_id: string | null;
+  use_worktree: number;
+  worktree_path: string | null;
+  worktree_branch: string | null;
+  pr_url: string | null;
+  created_at: number;
+  updated_at: number;
+}
+
 export interface Agent {
   id: string;
   job_id: string;
@@ -158,6 +189,7 @@ export interface QueueSnapshot {
   projects: Project[];
   batchTemplates: BatchTemplate[];
   debates: Debate[];
+  workflows: Workflow[];
   discussions: Discussion[];
   proposals: Proposal[];
 }
@@ -178,6 +210,8 @@ export interface ServerToClientEvents {
   'pty:snapshot-refresh': (payload: { agent_id: string; snapshot: string }) => void;
   'debate:new': (payload: { debate: Debate }) => void;
   'debate:update': (payload: { debate: Debate }) => void;
+  'workflow:new': (payload: { workflow: Workflow }) => void;
+  'workflow:update': (payload: { workflow: Workflow }) => void;
   'warning:new': (payload: { warning: AgentWarning }) => void;
   'project:new': (payload: { project: Project }) => void;
   'eye:discussion:new': (payload: { discussion: Discussion; message: DiscussionMessage }) => void;
@@ -250,6 +284,11 @@ export interface CodexStreamEvent {
   message?: string;
 }
 
+/** Returns true for jobs that run with --print and exit naturally (no finish_job needed). */
+export function isAutoExitJob(job: Pick<Job, 'debate_role' | 'workflow_phase'>): boolean {
+  return !!(job.debate_role || job.workflow_phase);
+}
+
 export function isCodexModel(model: string | null): boolean {
   return model === 'codex' || (model != null && model.startsWith('codex-'));
 }
@@ -417,6 +456,29 @@ export interface CreateDebateResponse {
   jobs: Job[];
 }
 
+// ─── Workflows ───────────────────────────────────────────────────────────────
+
+export interface CreateWorkflowRequest {
+  title?: string;
+  task: string;
+  workDir?: string;
+  implementerModel?: string;
+  reviewerModel?: string;
+  maxCycles?: number;
+  maxTurnsAssess?: number;
+  maxTurnsReview?: number;
+  maxTurnsImplement?: number;
+  templateId?: string;
+  useWorktree?: boolean;
+  projectId?: string;
+}
+
+export interface CreateWorkflowResponse {
+  workflow: Workflow;
+  project: Project;
+  jobs: Job[];
+}
+
 // ─── Agent Warnings (Feature 6) ──────────────────────────────────────────────
 
 export interface AgentWarning {

From 0d1b90c82154dbdcf70e37d8651133fe8bdf3f60 Mon Sep 17 00:00:00 2001
From: Barney Hussey-Yeo <bh13731@my.bristol.ac.uk>
Date: Tue, 31 Mar 2026 09:15:27 +0100
Subject: [PATCH 03/19] fix: ensure .orchestrator-worktrees parent dir exists
 before git worktree add

Without mkdir -p the worktree creation silently fails on fresh installs
or when the directory has been removed, falling back to work_dir directly
and allowing WorkQueueManager to create per-phase worktrees again.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/server/orchestrator/WorkflowManager.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/server/orchestrator/WorkflowManager.ts b/src/server/orchestrator/WorkflowManager.ts
index 4c08b29..4afa3c2 100644
--- a/src/server/orchestrator/WorkflowManager.ts
+++ b/src/server/orchestrator/WorkflowManager.ts
@@ -1,5 +1,6 @@
 import { randomUUID } from 'crypto';
 import { execSync } from 'child_process';
+import { mkdirSync } from 'fs';
 import path from 'path';
 import * as queries from '../db/queries.js';
 import * as socket from '../socket/SocketManager.js';
@@ -215,6 +216,7 @@ export function startWorkflow(workflow: Workflow): Job {
         .slice(0, 40);
       const branchName = `workflow/${slug}-${shortId}`;
       const worktreePath = path.resolve(workflow.work_dir, '..', '.orchestrator-worktrees', `wf-${shortId}`);
+      mkdirSync(path.dirname(worktreePath), { recursive: true });
       execSync(`git worktree add ${JSON.stringify(worktreePath)} -b ${JSON.stringify(branchName)}`, {
         cwd: workflow.work_dir,
         timeout: 30000,

From cfe26a75b8f7b55ceb4cf78283eb9baea5d36ba2 Mon Sep 17 00:00:00 2001
From: Barney Hussey-Yeo <bh13731@my.bristol.ac.uk>
Date: Tue, 31 Mar 2026 09:20:06 +0100
Subject: [PATCH 04/19] Fix TypeScript build errors: add missing Job fields, PR
 event types, and query type annotations

- Add work_dir and max_turns to Job interface in types.ts (columns exist in DB but were missing from type)
- Add eye:pr:* and eye:pr-review:* events to ServerToClientEvents (used by SocketManager but not typed)
- Add explicit :any annotations to db.prepare().all().map() callbacks in queries.ts (noImplicitAny)
- Use Map<string, Job> generic for jobMap constructors to fix tuple inference (fixes template_id and AgentWithJob errors)
- Complete missing fields in Job stub literals (debate_loop, workflow_id, etc.)
- Remove invalid shell: true from execSync in WorkflowManager (ExecSyncOptions.shell is string-only; execSync uses a shell by default)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/server/db/queries.ts                   | 14 +++++++-------
 src/server/orchestrator/WorkflowManager.ts |  2 +-
 src/shared/types.ts                        |  6 ++++++
 3 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/src/server/db/queries.ts b/src/server/db/queries.ts
index cf45f9d..47edd5a 100644
--- a/src/server/db/queries.ts
+++ b/src/server/db/queries.ts
@@ -128,7 +128,7 @@ export function listArchivedJobs(limit?: number, offset?: number): Job[] {
     }
   }
   const rows = db.prepare(sql).all(...args);
-  return rows.map(r => cast<Job>(r));
+  return rows.map((r: any) => cast<Job>(r));
 }
 
 export function listArchivedJobsSlim(limit?: number, offset?: number): Job[] {
@@ -176,7 +176,7 @@ export function listEyeJobs(): Job[] {
     ORDER BY created_at DESC
     LIMIT 200
   `).all();
-  return rows.map(r => cast<Job>(r));
+  return rows.map((r: any) => cast<Job>(r));
 }
 
 /**
@@ -503,7 +503,7 @@ export function getAgentsWithJobForSnapshot(): AgentWithJob[] {
 
   // Jobs — one query
   const jobRows = db.prepare(`SELECT * FROM jobs WHERE id IN (${ph(jobIds.length)})`).all(...jobIds);
-  const jobMap = new Map(jobRows.map(r => { const j = cast<Job>(r); return [j.id, j]; }));
+  const jobMap = new Map<string, Job>(jobRows.map((r: any) => { const j = cast<Job>(r); return [j.id, j]; }));
 
   // Pending questions — one query
   const qRows = db.prepare(`SELECT * FROM questions WHERE agent_id IN (${ph(agentIds.length)}) AND status = 'pending'`).all(...agentIds);
@@ -556,7 +556,7 @@ export function getAgentsWithJobForSnapshot(): AgentWithJob[] {
   return agents.map(agent => {
     const job = jobMap.get(agent.job_id);
     if (!job) {
-      const stub: Job = { id: agent.job_id, title: '(deleted job)', description: '', context: null, status: 'failed', priority: 0, work_dir: null, max_turns: 0, model: null, template_id: null, depends_on: null, is_interactive: 0, use_worktree: 0, project_id: null, flagged: 0, debate_id: null, debate_round: null, debate_role: null, scheduled_at: null, repeat_interval_ms: null, retry_policy: 'none', max_retries: 0, retry_count: 0, original_job_id: null, completion_checks: null, review_config: null, review_status: null, review_parent_job_id: null, archived_at: null, created_at: 0, updated_at: 0 };
+      const stub: Job = { id: agent.job_id, title: '(deleted job)', description: '', context: null, status: 'failed', priority: 0, work_dir: null, max_turns: 0, model: null, template_id: null, depends_on: null, is_interactive: 0, use_worktree: 0, project_id: null, flagged: 0, debate_id: null, debate_loop: null, debate_round: null, debate_role: null, scheduled_at: null, repeat_interval_ms: null, retry_policy: 'none', max_retries: 0, retry_count: 0, original_job_id: null, completion_checks: null, review_config: null, review_status: null, review_parent_job_id: null, created_by_agent_id: null, pre_debate_id: null, pre_debate_summary: null, workflow_id: null, workflow_cycle: null, workflow_phase: null, archived_at: null, created_at: 0, updated_at: 0 };
       return { ...agent, diff: null, job: stub, template_name: null, pending_question: null, active_locks: [], child_agents: [], warnings: [] } as AgentWithJob;
     }
     return {
@@ -599,7 +599,7 @@ export function getAgentsForJobIds(jobIds: string[]): AgentWithJob[] {
   // Enrich with job data (same pattern as getAgentsWithJobForSnapshot)
   const agentJobIds = [...new Set(agents.map(a => a.job_id))];
   const jobRows = db.prepare(`SELECT * FROM jobs WHERE id IN (${ph(agentJobIds.length)})`).all(...agentJobIds);
-  const jobMap = new Map(jobRows.map(r => { const j = cast<Job>(r); return [j.id, j]; }));
+  const jobMap = new Map<string, Job>(jobRows.map((r: any) => { const j = cast<Job>(r); return [j.id, j]; }));
 
   const templateIds = [...new Set(jobRows.map((r: any) => r.template_id).filter(Boolean))];
   const templateMap = new Map<string, string>();
@@ -653,7 +653,7 @@ function enrichAgent(agent: Agent): AgentWithJob {
   const jobRow = db.prepare('SELECT * FROM jobs WHERE id = ?').get(agent.job_id);
   if (!jobRow) {
     // Job was deleted while agent still references it — return a stub
-    const stub: Job = { id: agent.job_id, title: '(deleted job)', description: '', context: null, status: 'failed', priority: 0, model: null, template_id: null, depends_on: null, is_interactive: 0, use_worktree: 0, project_id: null, flagged: 0, debate_id: null, debate_loop: null, debate_round: null, debate_role: null, scheduled_at: null, repeat_interval_ms: null, retry_policy: 'none', max_retries: 0, retry_count: 0, original_job_id: null, completion_checks: null, review_config: null, review_status: null, review_parent_job_id: null, created_by_agent_id: null, pre_debate_id: null, pre_debate_summary: null, workflow_id: null, workflow_cycle: null, workflow_phase: null, archived_at: null, created_at: 0, updated_at: 0 };
+    const stub: Job = { id: agent.job_id, title: '(deleted job)', description: '', context: null, status: 'failed', priority: 0, work_dir: null, max_turns: 0, model: null, template_id: null, depends_on: null, is_interactive: 0, use_worktree: 0, project_id: null, flagged: 0, debate_id: null, debate_loop: null, debate_round: null, debate_role: null, scheduled_at: null, repeat_interval_ms: null, retry_policy: 'none', max_retries: 0, retry_count: 0, original_job_id: null, completion_checks: null, review_config: null, review_status: null, review_parent_job_id: null, created_by_agent_id: null, pre_debate_id: null, pre_debate_summary: null, workflow_id: null, workflow_cycle: null, workflow_phase: null, archived_at: null, created_at: 0, updated_at: 0 };
     return { ...agent, job: stub, template_name: null, pending_question: null, active_locks: [], child_agents: [], warnings: [] };
   }
   const job = cast<Job>(jobRow);
@@ -1402,7 +1402,7 @@ export function updateDebate(id: string, fields: Partial<Pick<Debate, 'current_r
 export function getJobsForDebate(debateId: string): Job[] {
   const db = getDb();
   const rows = db.prepare('SELECT * FROM jobs WHERE debate_id = ? ORDER BY debate_loop ASC, debate_round ASC, created_at ASC').all(debateId);
-  return rows.map(r => cast<Job>(r));
+  return rows.map((r: any) => cast<Job>(r));
 }
 
 export function getJobsForDebateRound(debateId: string, loop: number, round: number): Job[] {
diff --git a/src/server/orchestrator/WorkflowManager.ts b/src/server/orchestrator/WorkflowManager.ts
index 4afa3c2..a51ee62 100644
--- a/src/server/orchestrator/WorkflowManager.ts
+++ b/src/server/orchestrator/WorkflowManager.ts
@@ -333,7 +333,7 @@ export function finalizeWorkflow(workflow: Workflow): void {
     try {
       const n = execSync(
         'git rev-list --count HEAD ^origin/HEAD 2>/dev/null || git rev-list --count HEAD',
-        { cwd: worktree_path, stdio: 'pipe', timeout: 10000, shell: true }
+        { cwd: worktree_path, stdio: 'pipe', timeout: 10000 }
       ).toString().trim();
       hasCommits = parseInt(n, 10) > 0;
     } catch { /* not a git repo or no remote — skip PR */ }
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 55d311b..0249a5e 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -18,6 +18,8 @@ export interface Job {
   context: string | null; // JSON string of extra k/v context
   status: JobStatus;
   priority: number;
+  work_dir: string | null;
+  max_turns: number;
   model: string | null;       // e.g. "claude-opus-4-6", null = auto-classify
   template_id: string | null; // FK → templates.id
   depends_on: string | null;  // JSON array of job IDs this job must wait for
@@ -220,6 +222,10 @@ export interface ServerToClientEvents {
   'eye:proposal:new': (payload: { proposal: Proposal }) => void;
   'eye:proposal:update': (payload: { proposal: Proposal }) => void;
   'eye:proposal:message': (payload: { message: ProposalMessage }) => void;
+  'eye:pr:new': (payload: { pr: Record<string, unknown> }) => void;
+  'eye:pr-review:new': (payload: { review: Record<string, unknown> }) => void;
+  'eye:pr-review:update': (payload: { review: Record<string, unknown> }) => void;
+  'eye:pr-review:message': (payload: { message: Record<string, unknown> }) => void;
 }
 
 export interface ClientToServerEvents {

From 78164dcdea1d971c776404e85e7f784a14a9efe2 Mon Sep 17 00:00:00 2001
From: Barney Hussey-Yeo <bh13731@my.bristol.ac.uk>
Date: Tue, 31 Mar 2026 09:30:59 +0100
Subject: [PATCH 05/19] fix: detect and re-fire stuck workflows on startup, fix
 worktree label
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Recovery now scans for running workflows whose current-phase job is
done but no next-phase job was spawned — happens when the server
restarts between finish_job and onJobCompleted. The gap detector
correctly advances assess→review, review→implement, implement→review
without double-spawning.

Also fix the worktree checkbox label to accurately describe shared-branch
behavior (not per-phase isolation).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/client/components/WorkflowForm.tsx |  2 +-
 src/server/orchestrator/recovery.ts    | 28 ++++++++++++++++++++++++++
 2 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/src/client/components/WorkflowForm.tsx b/src/client/components/WorkflowForm.tsx
index 6f71004..eec7860 100644
--- a/src/client/components/WorkflowForm.tsx
+++ b/src/client/components/WorkflowForm.tsx
@@ -150,7 +150,7 @@ export function WorkflowForm({ onSubmit, onClose }: WorkflowFormProps) {
                 checked={useWorktree}
                 onChange={e => setUseWorktree(e.target.checked)}
               />
-              Use git worktree (recommended — isolates each phase in its own branch)
+              Use git worktree (recommended — all phases share one branch, changes accumulate linearly)
             </label>
           </div>
 
diff --git a/src/server/orchestrator/recovery.ts b/src/server/orchestrator/recovery.ts
index d552eff..e52cbc8 100644
--- a/src/server/orchestrator/recovery.ts
+++ b/src/server/orchestrator/recovery.ts
@@ -251,4 +251,32 @@ export function runRecovery(): void {
   if (tmuxReattached > 0) console.log(`[recovery] reattached ${tmuxReattached} tmux agents`);
   if (tmuxRecovered > 0) console.log(`[recovery] recovered ${tmuxRecovered} completed tmux agents`);
   if (tmuxFailed > 0) console.log(`[recovery] failed ${tmuxFailed} dead tmux agents`);
+
+  // Gap detector: find running workflows whose current-phase job is done but no next phase was spawned.
+  // This happens when the server restarts between finish_job and onJobCompleted.
+  _recoverStuckWorkflows();
+}
+
+function _recoverStuckWorkflows(): void {
+  const runningWorkflows = queries.listWorkflows().filter(w => w.status === 'running');
+  for (const workflow of runningWorkflows) {
+    if (workflow.current_phase === 'idle') continue;
+    const jobs = queries.getJobsForWorkflow(workflow.id);
+    // Find the most recent job for the current phase+cycle
+    const phaseJob = jobs
+      .filter(j => j.workflow_phase === workflow.current_phase && j.workflow_cycle === workflow.current_cycle)
+      .sort((a, b) => b.created_at - a.created_at)[0];
+    if (!phaseJob || phaseJob.status !== 'done') continue;
+    // Check if the expected next-phase job already exists.
+    // Progression: assess→review(C1), review→implement(Cn), implement→review(Cn+1)
+    const cycle = workflow.current_cycle;
+    const hasNext = workflow.current_phase === 'implement'
+      ? jobs.some(j => j.workflow_phase === 'review' && j.workflow_cycle === cycle + 1)
+      : workflow.current_phase === 'review'
+        ? jobs.some(j => j.workflow_phase === 'implement' && j.workflow_cycle === cycle)
+        : jobs.some(j => j.workflow_phase === 'review' && j.workflow_cycle === 1);
+    if (hasNext) continue;
+    console.log(`[recovery] workflow ${workflow.id} stuck — ${workflow.current_phase} C${workflow.current_cycle} done but no next phase; re-firing onJobCompleted`);
+    try { workflowOnJobCompleted(phaseJob); } catch (err) { console.error(`[recovery] stuck workflow re-fire error:`, err); }
+  }
 }

From bd41b1df1501d08924677f375b160ba3c45a7f27 Mon Sep 17 00:00:00 2001
From: Barney Hussey-Yeo <bh13731@my.bristol.ac.uk>
Date: Tue, 31 Mar 2026 09:37:14 +0100
Subject: [PATCH 06/19] fix: stop WorktreeCleanup from deleting workflow
 worktrees for other repos
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two bugs caused the ea-ops-copilot workflow worktree to be deleted 5 min
after creation, making all subsequent phase jobs fail with ENOENT:

1. cleanupOrphanedWorktrees() deleted any .orchestrator-worktrees/ dir
   not in the DB — but workflow shared worktrees (wf-*) were never
   inserted into the worktrees table. Fix: only remove directories that
   appear in `git worktree list` for the current (Hurlicane) repo.
   Other repos' worktrees share the same parent dir and must not be touched.

2. startWorkflow() didn't register the shared worktree in the DB.
   Fix: attempt insertWorktree() after creation as a secondary guard
   (wrapped in try/catch since job_id FK may reject the sentinel value).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/server/orchestrator/WorkflowManager.ts | 12 ++++++++++++
 src/server/orchestrator/WorktreeCleanup.ts | 16 +++++++++++++++-
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/src/server/orchestrator/WorkflowManager.ts b/src/server/orchestrator/WorkflowManager.ts
index a51ee62..4fae242 100644
--- a/src/server/orchestrator/WorkflowManager.ts
+++ b/src/server/orchestrator/WorkflowManager.ts
@@ -226,6 +226,18 @@ export function startWorkflow(workflow: Workflow): Job {
         worktree_path: worktreePath,
         worktree_branch: branchName,
       }) ?? workflow;
+      // Register in worktrees table so WorktreeCleanup doesn't treat it as an orphan.
+      // Use a placeholder job_id (the assess job hasn't been inserted yet); cleanup
+      // checks path membership, not job status, for the tracked-set guard.
+      try {
+        queries.insertWorktree({
+          id: randomUUID(),
+          agent_id: workflow.id, // workflow id as sentinel
+          job_id: workflow.id,   // workflow id as sentinel
+          path: worktreePath,
+          branch: branchName,
+        });
+      } catch { /* ignore — DB constraint may reject non-job IDs; ownership fix is the real guard */ }
       console.log(`[workflow ${workflow.id}] created worktree at ${worktreePath} (branch: ${branchName})`);
     } catch (err: any) {
       console.warn(`[workflow ${workflow.id}] worktree creation failed, using work_dir directly:`, err.message);
diff --git a/src/server/orchestrator/WorktreeCleanup.ts b/src/server/orchestrator/WorktreeCleanup.ts
index d4e0241..3b4d7eb 100644
--- a/src/server/orchestrator/WorktreeCleanup.ts
+++ b/src/server/orchestrator/WorktreeCleanup.ts
@@ -80,6 +80,19 @@ function cleanupOrphanedWorktrees(): void {
 
   if (!fs.existsSync(worktreeBase)) return;
 
+  // Only touch directories that are registered as worktrees of THIS repo.
+  // Workflow-level worktrees (wf-*) belong to other repos and must not be deleted here.
+  let ownedPaths: Set<string>;
+  try {
+    const lines = execSync('git worktree list --porcelain', { cwd: repoDir, timeout: 10000, stdio: 'pipe' })
+      .toString().split('\n');
+    ownedPaths = new Set(
+      lines.filter(l => l.startsWith('worktree ')).map(l => l.slice(9).trim())
+    );
+  } catch {
+    return; // can't determine ownership — skip cleanup entirely
+  }
+
   const tracked = new Set(queries.listActiveWorktrees().map(w => w.path));
   let cleaned = 0;
 
@@ -89,8 +102,9 @@ function cleanupOrphanedWorktrees(): void {
       const fullPath = path.join(worktreeBase, entry);
       if (!fs.statSync(fullPath).isDirectory()) continue;
       if (tracked.has(fullPath)) continue;
+      if (!ownedPaths.has(fullPath)) continue; // not our worktree — leave it alone
 
-      // Orphaned directory — remove it
+      // Orphaned directory owned by this repo — remove it
       try {
         execSync(`git worktree remove --force ${JSON.stringify(fullPath)}`, {
           cwd: repoDir,

From fa64104f104b4a48e5c78721e6aef9299a26f009 Mon Sep 17 00:00:00 2001
From: Barney Hussey-Yeo <bh13731@my.bristol.ac.uk>
Date: Tue, 31 Mar 2026 09:37:29 +0100
Subject: [PATCH 07/19] fix: replace opaque Record<string, unknown> PR event
 types with concrete shared interfaces

Add Pr interface to shared types and use PrReview/PrReviewMessage for
all four PR-related socket events (eye:pr:new, eye:pr-review:new,
eye:pr-review:update, eye:pr-review:message) in ServerToClientEvents
and SocketManager emit functions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/server/mcp/tools/eye.ts        |  2 +-
 src/server/socket/SocketManager.ts | 10 +++++-----
 src/shared/types.ts                | 20 ++++++++++++++++----
 3 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/src/server/mcp/tools/eye.ts b/src/server/mcp/tools/eye.ts
index 24c9873..31ae8a7 100644
--- a/src/server/mcp/tools/eye.ts
+++ b/src/server/mcp/tools/eye.ts
@@ -235,7 +235,7 @@ export async function reportPrHandler(agentId: string, input: z.infer<typeof rep
   const { url, title, description, proposal_id } = input;
 
   const id = randomUUID();
-  const pr = { id, url, title, description: description ?? null, proposal_id: proposal_id ?? null, status: 'draft', created_at: Date.now() };
+  const pr: import('../../../shared/types.js').Pr = { id, url, title, description: description ?? null, proposal_id: proposal_id ?? null, status: 'draft', created_at: Date.now() };
   queries.upsertNote(`pr:${id}`, JSON.stringify(pr), agentId);
   socket.emitPrNew(pr);
 
diff --git a/src/server/socket/SocketManager.ts b/src/server/socket/SocketManager.ts
index fe37b28..2ae002f 100644
--- a/src/server/socket/SocketManager.ts
+++ b/src/server/socket/SocketManager.ts
@@ -1,6 +1,6 @@
 import { Server as HttpServer } from 'http';
 import { Server as SocketIoServer } from 'socket.io';
-import type { ServerToClientEvents, ClientToServerEvents, AgentWithJob, Job, Question, FileLock, AgentOutput, QueueSnapshot, Debate, AgentWarning, Discussion, DiscussionMessage, Proposal, ProposalMessage, Workflow } from '../../shared/types.js';
+import type { ServerToClientEvents, ClientToServerEvents, AgentWithJob, Job, Question, FileLock, AgentOutput, QueueSnapshot, Debate, AgentWarning, Discussion, DiscussionMessage, Proposal, ProposalMessage, Workflow, Pr, PrReview, PrReviewMessage } from '../../shared/types.js';
 
 let _io: SocketIoServer<ClientToServerEvents, ServerToClientEvents> | null = null;
 
@@ -103,7 +103,7 @@ export function emitDiscussionUpdate(discussion: Discussion): void { getIo().emi
 export function emitProposalNew(proposal: Proposal): void { getIo().emit('eye:proposal:new', { proposal }); }
 export function emitProposalUpdate(proposal: Proposal): void { getIo().emit('eye:proposal:update', { proposal }); }
 export function emitProposalMessage(message: ProposalMessage): void { getIo().emit('eye:proposal:message', { message }); }
-export function emitPrNew(pr: Record<string, unknown>): void { getIo().emit('eye:pr:new', { pr }); }
-export function emitPrReviewNew(review: Record<string, unknown>): void { getIo().emit('eye:pr-review:new', { review }); }
-export function emitPrReviewUpdate(review: Record<string, unknown>): void { getIo().emit('eye:pr-review:update', { review }); }
-export function emitPrReviewMessage(message: Record<string, unknown>): void { getIo().emit('eye:pr-review:message', { message }); }
+export function emitPrNew(pr: Pr): void { getIo().emit('eye:pr:new', { pr }); }
+export function emitPrReviewNew(review: PrReview): void { getIo().emit('eye:pr-review:new', { review }); }
+export function emitPrReviewUpdate(review: PrReview): void { getIo().emit('eye:pr-review:update', { review }); }
+export function emitPrReviewMessage(message: PrReviewMessage): void { getIo().emit('eye:pr-review:message', { message }); }
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 0249a5e..592d1e4 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -222,10 +222,10 @@ export interface ServerToClientEvents {
   'eye:proposal:new': (payload: { proposal: Proposal }) => void;
   'eye:proposal:update': (payload: { proposal: Proposal }) => void;
   'eye:proposal:message': (payload: { message: ProposalMessage }) => void;
-  'eye:pr:new': (payload: { pr: Record<string, unknown> }) => void;
-  'eye:pr-review:new': (payload: { review: Record<string, unknown> }) => void;
-  'eye:pr-review:update': (payload: { review: Record<string, unknown> }) => void;
-  'eye:pr-review:message': (payload: { message: Record<string, unknown> }) => void;
+  'eye:pr:new': (payload: { pr: Pr }) => void;
+  'eye:pr-review:new': (payload: { review: PrReview }) => void;
+  'eye:pr-review:update': (payload: { review: PrReview }) => void;
+  'eye:pr-review:message': (payload: { message: PrReviewMessage }) => void;
 }
 
 export interface ClientToServerEvents {
@@ -629,6 +629,18 @@ export interface ProposalMessage {
   created_at: number;
 }
 
+// ─── PRs ────────────────────────────────────────────────────────────────────
+
+export interface Pr {
+  id: string;
+  url: string;
+  title: string;
+  description: string | null;
+  proposal_id: string | null;
+  status: 'draft' | 'open' | 'merged' | 'closed';
+  created_at: number;
+}
+
 // ─── PR Reviews ──────────────────────────────────────────────────────────────
 
 export interface PrReviewComment {

From 0a10078d83910b929badf6c03a13e58cc2de3774 Mon Sep 17 00:00:00 2001
From: Barney Hussey-Yeo <bh13731@my.bristol.ac.uk>
Date: Tue, 31 Mar 2026 09:40:07 +0100
Subject: [PATCH 08/19] fix: close remaining gaps in stuck-workflow recovery
 and worktree cleanup
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bug 1 (stuck workflow on restart) — two gaps remained:
- Gap detector used workflow.current_cycle to find the assess job, but
  onJobCompleted bumps current_cycle to 1 *before* spawnPhaseJob, so after
  a crash the assess job (cycle=0) was never found. Fix: look at cycle 0
  when current_phase='assess', regardless of current_cycle.
- created_at comparison was unguarded against undefined; added ?? 0 fallback.

Bug 2 (worktree deleted by cleanup) — previous fix was incomplete:
- insertWorktree(workflow.id) silently failed due to FK constraints (FK=ON),
  so Hurlicane-targeting workflow worktrees were still unprotected. Removed
  the broken sentinel approach entirely.
- cleanupOrphanedWorktrees() now builds the protected set from both the
  per-job worktrees table AND active/blocked workflow worktree_paths, so
  workflow shared worktrees are never treated as orphans regardless of which
  repo they belong to.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/server/orchestrator/WorkflowManager.ts | 12 ------------
 src/server/orchestrator/WorktreeCleanup.ts |  8 +++++++-
 src/server/orchestrator/recovery.ts        | 17 ++++++++++++-----
 3 files changed, 19 insertions(+), 18 deletions(-)

diff --git a/src/server/orchestrator/WorkflowManager.ts b/src/server/orchestrator/WorkflowManager.ts
index 4fae242..a51ee62 100644
--- a/src/server/orchestrator/WorkflowManager.ts
+++ b/src/server/orchestrator/WorkflowManager.ts
@@ -226,18 +226,6 @@ export function startWorkflow(workflow: Workflow): Job {
         worktree_path: worktreePath,
         worktree_branch: branchName,
       }) ?? workflow;
-      // Register in worktrees table so WorktreeCleanup doesn't treat it as an orphan.
-      // Use a placeholder job_id (the assess job hasn't been inserted yet); cleanup
-      // checks path membership, not job status, for the tracked-set guard.
-      try {
-        queries.insertWorktree({
-          id: randomUUID(),
-          agent_id: workflow.id, // workflow id as sentinel
-          job_id: workflow.id,   // workflow id as sentinel
-          path: worktreePath,
-          branch: branchName,
-        });
-      } catch { /* ignore — DB constraint may reject non-job IDs; ownership fix is the real guard */ }
       console.log(`[workflow ${workflow.id}] created worktree at ${worktreePath} (branch: ${branchName})`);
     } catch (err: any) {
       console.warn(`[workflow ${workflow.id}] worktree creation failed, using work_dir directly:`, err.message);
diff --git a/src/server/orchestrator/WorktreeCleanup.ts b/src/server/orchestrator/WorktreeCleanup.ts
index 3b4d7eb..2b930d3 100644
--- a/src/server/orchestrator/WorktreeCleanup.ts
+++ b/src/server/orchestrator/WorktreeCleanup.ts
@@ -93,7 +93,13 @@ function cleanupOrphanedWorktrees(): void {
     return; // can't determine ownership — skip cleanup entirely
   }
 
-  const tracked = new Set(queries.listActiveWorktrees().map(w => w.path));
+  // Protect both DB-tracked per-job worktrees AND workflow shared worktrees (wf-*)
+  const tracked = new Set([
+    ...queries.listActiveWorktrees().map(w => w.path),
+    ...queries.listWorkflows()
+      .filter(w => w.worktree_path && (w.status === 'running' || w.status === 'blocked'))
+      .map(w => w.worktree_path!),
+  ]);
   let cleaned = 0;
 
   try {
diff --git a/src/server/orchestrator/recovery.ts b/src/server/orchestrator/recovery.ts
index e52cbc8..d4e277a 100644
--- a/src/server/orchestrator/recovery.ts
+++ b/src/server/orchestrator/recovery.ts
@@ -262,11 +262,17 @@ function _recoverStuckWorkflows(): void {
   for (const workflow of runningWorkflows) {
     if (workflow.current_phase === 'idle') continue;
     const jobs = queries.getJobsForWorkflow(workflow.id);
-    // Find the most recent job for the current phase+cycle
+
+    // Assess always runs at cycle 0, but onJobCompleted bumps current_cycle to 1
+    // before calling spawnPhaseJob — so look for cycle 0 when stuck in assess.
+    const jobCycle = workflow.current_phase === 'assess' ? 0 : workflow.current_cycle;
+
+    // Find the most recent completed job for this phase
     const phaseJob = jobs
-      .filter(j => j.workflow_phase === workflow.current_phase && j.workflow_cycle === workflow.current_cycle)
-      .sort((a, b) => b.created_at - a.created_at)[0];
+      .filter(j => j.workflow_phase === workflow.current_phase && j.workflow_cycle === jobCycle)
+      .sort((a, b) => (b.created_at ?? 0) - (a.created_at ?? 0))[0];
     if (!phaseJob || phaseJob.status !== 'done') continue;
+
     // Check if the expected next-phase job already exists.
     // Progression: assess→review(C1), review→implement(Cn), implement→review(Cn+1)
     const cycle = workflow.current_cycle;
@@ -274,9 +280,10 @@ function _recoverStuckWorkflows(): void {
       ? jobs.some(j => j.workflow_phase === 'review' && j.workflow_cycle === cycle + 1)
       : workflow.current_phase === 'review'
         ? jobs.some(j => j.workflow_phase === 'implement' && j.workflow_cycle === cycle)
-        : jobs.some(j => j.workflow_phase === 'review' && j.workflow_cycle === 1);
+        : jobs.some(j => j.workflow_phase === 'review' && j.workflow_cycle === 1); // assess stuck
+
     if (hasNext) continue;
-    console.log(`[recovery] workflow ${workflow.id} stuck — ${workflow.current_phase} C${workflow.current_cycle} done but no next phase; re-firing onJobCompleted`);
+    console.log(`[recovery] workflow ${workflow.id} stuck — ${workflow.current_phase} C${jobCycle} done but no next phase; re-firing onJobCompleted`);
     try { workflowOnJobCompleted(phaseJob); } catch (err) { console.error(`[recovery] stuck workflow re-fire error:`, err); }
   }
 }

From bc92eed77ff273354fc05a12f6e97e1db6b9a960 Mon Sep 17 00:00:00 2001
From: Barney Hussey-Yeo <bh13731@my.bristol.ac.uk>
Date: Tue, 31 Mar 2026 09:46:35 +0100
Subject: [PATCH 09/19] fix: run workflow gap detector every 60s, not just at
 startup
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Workflows could get stuck mid-transition if onJobCompleted threw after
finish_job but before spawnPhaseJob — recovery at startup catches this,
but jobs completing *after* startup had no periodic catch. Now
startWorkflowGapDetector() polls every 60s so any stuck workflow
recovers within a minute regardless of when it got stuck.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/server/index.ts                 |  4 +++-
 src/server/orchestrator/recovery.ts | 15 +++++++++++++++
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/src/server/index.ts b/src/server/index.ts
index 4778e1b..62cae1f 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -14,7 +14,7 @@ import { startHealthMonitor, stopHealthMonitor } from './orchestrator/HealthMoni
 import { startWorktreeCleanup, stopWorktreeCleanup } from './orchestrator/WorktreeCleanup.js';
 import { startKBConsolidator, stopKBConsolidator } from './orchestrator/KBConsolidator.js';
 import { startGitHubPoller, stopGitHubPoller } from './integrations/GitHubPoller.js';
-import { runRecovery } from './orchestrator/recovery.js';
+import { runRecovery, startWorkflowGapDetector, stopWorkflowGapDetector } from './orchestrator/recovery.js';
 import { writeInput, resizePty, resizeAndSnapshot } from './orchestrator/PtyManager.js';
 import * as queries from './db/queries.js';
 
@@ -137,6 +137,7 @@ async function main() {
   startWatchdog();
   startHealthMonitor();
   startWorktreeCleanup();
+  startWorkflowGapDetector();
   startKBConsolidator();
   startGitHubPoller();
 
@@ -169,6 +170,7 @@ async function main() {
     stopWatchdog();
     stopHealthMonitor();
     stopWorktreeCleanup();
+    stopWorkflowGapDetector();
     stopKBConsolidator();
     stopGitHubPoller();
 
diff --git a/src/server/orchestrator/recovery.ts b/src/server/orchestrator/recovery.ts
index d4e277a..79ecaa2 100644
--- a/src/server/orchestrator/recovery.ts
+++ b/src/server/orchestrator/recovery.ts
@@ -257,6 +257,21 @@ export function runRecovery(): void {
   _recoverStuckWorkflows();
 }
 
+let _gapDetectorTimer: NodeJS.Timeout | null = null;
+
+/** Start a periodic gap detector that re-fires onJobCompleted for any workflow stuck mid-transition. */
+export function startWorkflowGapDetector(): void {
+  if (_gapDetectorTimer) return;
+  // Run every 60 seconds so stuck workflows recover within a minute of getting stuck.
+  _gapDetectorTimer = setInterval(() => {
+    try { _recoverStuckWorkflows(); } catch (err) { console.error('[workflow-gap] tick error:', err); }
+  }, 60_000);
+}
+
+export function stopWorkflowGapDetector(): void {
+  if (_gapDetectorTimer) { clearInterval(_gapDetectorTimer); _gapDetectorTimer = null; }
+}
+
 function _recoverStuckWorkflows(): void {
   const runningWorkflows = queries.listWorkflows().filter(w => w.status === 'running');
   for (const workflow of runningWorkflows) {

From 1a1dd73c83b4ec94b708e59cb347f8b3eba4ee66 Mon Sep 17 00:00:00 2001
From: Barney Hussey-Yeo <bh13731@my.bristol.ac.uk>
Date: Tue, 31 Mar 2026 09:51:52 +0100
Subject: [PATCH 10/19] test: add singleton-reset and dedup coverage for
 WorkflowManager.onJobCompleted()

Add _resetForTest() exports to WorkflowManager and DebateManager that clear
module-level _processedJobs dedup Sets. Add resetManagerState() helper to
test helpers. Create workflow-dedup.test.ts with 6 tests proving:
- dedup guard blocks duplicate job ID within a single test
- _resetForTest() enables same job ID across separate tests (per-test independence)
- assess completion spawns review job with correct DB state + socket emissions
- failed phase job marks workflow as blocked
- non-workflow jobs are silently ignored

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/server/orchestrator/DebateManager.ts   |   5 +
 src/server/orchestrator/WorkflowManager.ts |   5 +
 src/test/helpers.ts                        |  13 ++
 src/test/workflow-dedup.test.ts            | 250 +++++++++++++++++++++
 4 files changed, 273 insertions(+)
 create mode 100644 src/test/workflow-dedup.test.ts

diff --git a/src/server/orchestrator/DebateManager.ts b/src/server/orchestrator/DebateManager.ts
index 99ddd48..0c4ca78 100644
--- a/src/server/orchestrator/DebateManager.ts
+++ b/src/server/orchestrator/DebateManager.ts
@@ -25,6 +25,11 @@ export function onJobCompleted(job: Job): void {
 // since all calls happen in the same Node.js process (single-threaded).
 const _processedJobs = new Set<string>();
 
+/** Clear module-level dedup state. Test-only — call in beforeEach to ensure per-test independence. */
+export function _resetForTest(): void {
+  _processedJobs.clear();
+}
+
 function _onJobCompleted(job: Job): void {
   // Guard against double-call from PID poll + PTY onExit race
   if (_processedJobs.has(job.id)) return;
diff --git a/src/server/orchestrator/WorkflowManager.ts b/src/server/orchestrator/WorkflowManager.ts
index a51ee62..5be82d4 100644
--- a/src/server/orchestrator/WorkflowManager.ts
+++ b/src/server/orchestrator/WorkflowManager.ts
@@ -413,6 +413,11 @@ function _buildPrBody(workflow: Workflow, planText: string | null): string {
 
 // ─── Helpers ────────────────────────────────────────────────────────────────
 
+/** Clear module-level dedup state. Test-only — call in beforeEach to ensure per-test independence. */
+export function _resetForTest(): void {
+  _processedJobs.clear();
+}
+
 function updateAndEmit(id: string, fields: Parameters<typeof queries.updateWorkflow>[1]): void {
   const updated = queries.updateWorkflow(id, fields);
   if (updated) socket.emitWorkflowUpdate(updated);
diff --git a/src/test/helpers.ts b/src/test/helpers.ts
index 3cbce61..46d5a57 100644
--- a/src/test/helpers.ts
+++ b/src/test/helpers.ts
@@ -32,6 +32,19 @@ export async function cleanupTestDb() {
   closeDb();
 }
 
+// ─── Manager Reset ───────────────────────────────────────────────────────────
+
+/**
+ * Reset module-level dedup state in all managers that use a _processedJobs Set.
+ * Call in beforeEach so each test starts with a clean slate.
+ */
+export async function resetManagerState() {
+  const { _resetForTest: resetWorkflow } = await import('../server/orchestrator/WorkflowManager.js');
+  const { _resetForTest: resetDebate } = await import('../server/orchestrator/DebateManager.js');
+  resetWorkflow();
+  resetDebate();
+}
+
 // ─── Socket Mock ──────────────────────────────────────────────────────────────
 
 export interface SocketMockCalls {
diff --git a/src/test/workflow-dedup.test.ts b/src/test/workflow-dedup.test.ts
new file mode 100644
index 0000000..5cd37cb
--- /dev/null
+++ b/src/test/workflow-dedup.test.ts
@@ -0,0 +1,250 @@
+/**
+ * WorkflowManager dedup and phase-transition tests.
+ *
+ * Proves:
+ * 1. _resetForTest() clears module-level dedup state between tests
+ * 2. Same job ID processed twice within one test is a no-op (dedup guard)
+ * 3. Same job ID works across separate tests (per-test independence via reset)
+ * 4. onJobCompleted() drives a real assess→review phase transition with DB + socket assertions
+ * 5. A failed phase job marks the workflow as blocked
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  setupTestDb,
+  cleanupTestDb,
+  createSocketMock,
+  resetManagerState,
+  insertTestProject,
+  insertTestWorkflow,
+  insertTestJob,
+} from './helpers.js';
+
+// Mock SocketManager before any module that imports it
+vi.mock('../server/socket/SocketManager.js', () => createSocketMock());
+
+// Mock WorkflowPrompts so we don't need to exercise complex prompt generation
+vi.mock('../server/orchestrator/WorkflowPrompts.js', () => ({
+  buildAssessPrompt: vi.fn(() => 'mock assess prompt'),
+  buildReviewPrompt: vi.fn(() => 'mock review prompt'),
+  buildImplementPrompt: vi.fn(() => 'mock implement prompt'),
+}));
+
+// Shared job ID used to prove cross-test dedup independence
+const SHARED_JOB_ID = 'dedup-test-shared-job-id';
+
+describe('WorkflowManager: dedup guard', () => {
+  beforeEach(async () => {
+    await setupTestDb();
+    await resetManagerState();
+    vi.clearAllMocks();
+  });
+
+  afterEach(async () => {
+    await cleanupTestDb();
+  });
+
+  it('processes a job the first time and ignores the second call (dedup within one test)', async () => {
+    const socket = await import('../server/socket/SocketManager.js');
+    const { onJobCompleted } = await import('../server/orchestrator/WorkflowManager.js');
+    const { upsertNote, getWorkflowById } = await import('../server/db/queries.js');
+
+    // Set up workflow + plan note + assess job
+    const project = await insertTestProject();
+    const workflow = await insertTestWorkflow({
+      project_id: project.id,
+      status: 'running',
+      current_phase: 'assess',
+      current_cycle: 0,
+    });
+    upsertNote(`workflow/${workflow.id}/plan`, '- [ ] M1\n- [ ] M2', null);
+
+    const job = await insertTestJob({
+      id: 'dedup-within-test',
+      workflow_id: workflow.id,
+      workflow_cycle: 0,
+      workflow_phase: 'assess',
+      status: 'done',
+    });
+
+    // First call: should trigger assess→review transition
+    onJobCompleted(job);
+    const callsAfterFirst = vi.mocked(socket.emitWorkflowUpdate).mock.calls.length;
+    expect(callsAfterFirst).toBeGreaterThan(0);
+
+    // Verify a review job was spawned
+    const emitJobNewCalls = vi.mocked(socket.emitJobNew).mock.calls;
+    expect(emitJobNewCalls.length).toBe(1);
+    expect(emitJobNewCalls[0][0].workflow_phase).toBe('review');
+
+    // Second call with same job: should be a complete no-op
+    vi.clearAllMocks();
+    onJobCompleted(job);
+    expect(vi.mocked(socket.emitWorkflowUpdate).mock.calls.length).toBe(0);
+    expect(vi.mocked(socket.emitJobNew).mock.calls.length).toBe(0);
+
+    // DB state unchanged from first call
+    const updated = getWorkflowById(workflow.id)!;
+    expect(updated.current_phase).toBe('review');
+    expect(updated.current_cycle).toBe(1);
+  });
+
+  it('processes the SHARED_JOB_ID (first test — proves reset clears dedup set)', async () => {
+    const socket = await import('../server/socket/SocketManager.js');
+    const { onJobCompleted } = await import('../server/orchestrator/WorkflowManager.js');
+    const { upsertNote, getWorkflowById } = await import('../server/db/queries.js');
+
+    const project = await insertTestProject();
+    const workflow = await insertTestWorkflow({
+      project_id: project.id,
+      status: 'running',
+      current_phase: 'assess',
+      current_cycle: 0,
+    });
+    upsertNote(`workflow/${workflow.id}/plan`, '- [ ] M1', null);
+
+    const job = await insertTestJob({
+      id: SHARED_JOB_ID,
+      workflow_id: workflow.id,
+      workflow_cycle: 0,
+      workflow_phase: 'assess',
+      status: 'done',
+    });
+
+    onJobCompleted(job);
+
+    // Should have processed the job (not dedup-blocked)
+    expect(vi.mocked(socket.emitWorkflowUpdate).mock.calls.length).toBeGreaterThan(0);
+    const updated = getWorkflowById(workflow.id)!;
+    expect(updated.current_phase).toBe('review');
+  });
+
+  it('processes the SHARED_JOB_ID again (second test — proves per-test independence)', async () => {
+    const socket = await import('../server/socket/SocketManager.js');
+    const { onJobCompleted } = await import('../server/orchestrator/WorkflowManager.js');
+    const { upsertNote, getWorkflowById } = await import('../server/db/queries.js');
+
+    const project = await insertTestProject();
+    const workflow = await insertTestWorkflow({
+      project_id: project.id,
+      status: 'running',
+      current_phase: 'assess',
+      current_cycle: 0,
+    });
+    upsertNote(`workflow/${workflow.id}/plan`, '- [ ] M1', null);
+
+    const job = await insertTestJob({
+      id: SHARED_JOB_ID,
+      workflow_id: workflow.id,
+      workflow_cycle: 0,
+      workflow_phase: 'assess',
+      status: 'done',
+    });
+
+    // If _resetForTest didn't clear the set, this would be silently deduped
+    onJobCompleted(job);
+
+    expect(vi.mocked(socket.emitWorkflowUpdate).mock.calls.length).toBeGreaterThan(0);
+    const updated = getWorkflowById(workflow.id)!;
+    expect(updated.current_phase).toBe('review');
+  });
+});
+
+describe('WorkflowManager: onJobCompleted phase transitions', () => {
+  beforeEach(async () => {
+    await setupTestDb();
+    await resetManagerState();
+    vi.clearAllMocks();
+  });
+
+  afterEach(async () => {
+    await cleanupTestDb();
+  });
+
+  it('assess completion spawns a review job and updates workflow phase', async () => {
+    const socket = await import('../server/socket/SocketManager.js');
+    const { onJobCompleted } = await import('../server/orchestrator/WorkflowManager.js');
+    const { upsertNote, getWorkflowById } = await import('../server/db/queries.js');
+
+    const project = await insertTestProject();
+    const workflow = await insertTestWorkflow({
+      project_id: project.id,
+      status: 'running',
+      current_phase: 'assess',
+      current_cycle: 0,
+    });
+    upsertNote(`workflow/${workflow.id}/plan`, '- [ ] M1\n- [ ] M2\n- [x] M3', null);
+
+    const job = await insertTestJob({
+      workflow_id: workflow.id,
+      workflow_cycle: 0,
+      workflow_phase: 'assess',
+      status: 'done',
+    });
+
+    onJobCompleted(job);
+
+    // Workflow state updated
+    const updated = getWorkflowById(workflow.id)!;
+    expect(updated.current_phase).toBe('review');
+    expect(updated.current_cycle).toBe(1);
+    expect(updated.milestones_total).toBe(3);
+    expect(updated.milestones_done).toBe(1);
+
+    // Review job was spawned
+    const emitJobNewCalls = vi.mocked(socket.emitJobNew).mock.calls;
+    expect(emitJobNewCalls.length).toBe(1);
+    const reviewJob = emitJobNewCalls[0][0];
+    expect(reviewJob.workflow_id).toBe(workflow.id);
+    expect(reviewJob.workflow_phase).toBe('review');
+    expect(reviewJob.workflow_cycle).toBe(1);
+  });
+
+  it('failed phase job marks workflow as blocked', async () => {
+    const socket = await import('../server/socket/SocketManager.js');
+    const { onJobCompleted } = await import('../server/orchestrator/WorkflowManager.js');
+    const { upsertNote, getWorkflowById } = await import('../server/db/queries.js');
+
+    const project = await insertTestProject();
+    const workflow = await insertTestWorkflow({
+      project_id: project.id,
+      status: 'running',
+      current_phase: 'implement',
+      current_cycle: 2,
+    });
+    upsertNote(`workflow/${workflow.id}/plan`, '- [x] M1\n- [ ] M2', null);
+
+    const job = await insertTestJob({
+      workflow_id: workflow.id,
+      workflow_cycle: 2,
+      workflow_phase: 'implement',
+      status: 'failed',
+    });
+
+    onJobCompleted(job);
+
+    const updated = getWorkflowById(workflow.id)!;
+    expect(updated.status).toBe('blocked');
+    expect(updated.current_phase).toBe('implement');
+
+    // Socket should have emitted the blocked state
+    const updateCalls = vi.mocked(socket.emitWorkflowUpdate).mock.calls;
+    expect(updateCalls.length).toBeGreaterThan(0);
+    const lastUpdate = updateCalls[updateCalls.length - 1][0];
+    expect(lastUpdate.status).toBe('blocked');
+  });
+
+  it('non-workflow job is silently ignored', async () => {
+    const socket = await import('../server/socket/SocketManager.js');
+    const { onJobCompleted } = await import('../server/orchestrator/WorkflowManager.js');
+
+    const job = await insertTestJob({
+      workflow_id: null,
+      status: 'done',
+    });
+
+    onJobCompleted(job);
+
+    expect(vi.mocked(socket.emitWorkflowUpdate).mock.calls.length).toBe(0);
+    expect(vi.mocked(socket.emitJobNew).mock.calls.length).toBe(0);
+  });
+});

From 69839065a6aee97626cd1fc5fc94c31f5c1ce332 Mon Sep 17 00:00:00 2001
From: Barney Hussey-Yeo <bh13731@my.bristol.ac.uk>
Date: Tue, 31 Mar 2026 10:43:16 +0100
Subject: [PATCH 11/19] fix: detect and recover MCP-disconnected agents within
 2 minutes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Agents that lost their MCP connection outside of wait_for_jobs had no
recovery path except a 90-minute idle timeout. This caused agents to
enter sleep-retry loops burning turn budget while the server was already
back up.

- Track MCP-disconnected agents in a new disconnectedAgents map
- Add watchdog Check 3: kill and restart disconnected agents after 2min
- Extend idle timeout from tmux-only to all agent types, reduce 90→20min
- Call workflowOnJobCompleted from watchdog so workflows advance immediately
- Add force param to WorkflowManager.onJobCompleted so gap detector can
  bypass _processedJobs dedup and actually recover stuck workflows

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/server/mcp/McpServer.ts                 |  20 +++-
 src/server/orchestrator/StuckJobWatchdog.ts | 122 +++++++++++++++++---
 src/server/orchestrator/WorkflowManager.ts  |   4 +-
 src/server/orchestrator/recovery.ts         |   2 +-
 4 files changed, 123 insertions(+), 25 deletions(-)

diff --git a/src/server/mcp/McpServer.ts b/src/server/mcp/McpServer.ts
index 6825b47..66343fa 100644
--- a/src/server/mcp/McpServer.ts
+++ b/src/server/mcp/McpServer.ts
@@ -29,6 +29,15 @@ const agentTransports: Map<string, Map<string, StreamableHTTPServerTransport>> =
  */
 export const orphanedWaits = new Map<string, { job_ids: string[]; disconnected_at: number }>();
 
+/**
+ * Agents whose MCP connection dropped while NOT in wait_for_jobs.
+ * agentId → timestamp of disconnect.
+ * Consumed by StuckJobWatchdog: if an agent stays disconnected for more than
+ * a grace period and is still "running", it's stuck (e.g. sleeping in a retry
+ * loop) and should be killed + restarted.
+ */
+export const disconnectedAgents = new Map<string, number>();
+
 export function hasActiveTransport(agentId: string): boolean {
   return agentTransports.has(agentId);
 }
@@ -46,6 +55,7 @@ export async function closeAllMcpSessions(): Promise<void> {
   }
   await Promise.all(promises);
   agentTransports.clear();
+  disconnectedAgents.clear();
 }
 
 function makeOnClose(agentId: string, transportMap: Map<string, StreamableHTTPServerTransport>, transport: { sessionId?: string }) {
@@ -60,7 +70,8 @@ function makeOnClose(agentId: string, transportMap: Map<string, StreamableHTTPSe
       abortAgentWait(agentId);
       orphanedWaits.set(agentId, { job_ids: [...waitingOn], disconnected_at: Date.now() });
     } else {
-      console.log(`[mcp] session closed: agent ${agentId}`);
+      console.warn(`[mcp] session closed: agent ${agentId} — registering as disconnected`);
+      disconnectedAgents.set(agentId, Date.now());
     }
   };
 }
@@ -112,8 +123,9 @@ export function createMcpApp(): express.Application {
         transport = transportMap.get(sessionId)!;
       } else if (!sessionId && isInitializeRequest(req.body)) {
         console.log(`[mcp] new session: agent ${agentId}`);
-        // Clear any orphaned wait — agent has reconnected
+        // Clear any orphaned wait / disconnect — agent has reconnected
         orphanedWaits.delete(agentId);
+        disconnectedAgents.delete(agentId);
         transport = new StreamableHTTPServerTransport({
           sessionIdGenerator: () => randomUUID(),
           enableJsonResponse: true,
@@ -129,8 +141,9 @@ export function createMcpApp(): express.Application {
       } else if (isInitializeRequest(req.body)) {
         // Re-initialization with a stale session ID (e.g. after server restart) — create fresh session
         console.log(`[mcp] re-initialize: agent ${agentId} (stale session)`);
-        // Clear any orphaned wait — agent has reconnected
+        // Clear any orphaned wait / disconnect — agent has reconnected
         orphanedWaits.delete(agentId);
+        disconnectedAgents.delete(agentId);
         transport = new StreamableHTTPServerTransport({
           sessionIdGenerator: () => randomUUID(),
           enableJsonResponse: true,
@@ -157,6 +170,7 @@ export function createMcpApp(): express.Application {
 
         console.warn(`[mcp] unknown session: agent ${agentId} session ${sessionId} — auto-recovering transport (server restart?)`);
         orphanedWaits.delete(agentId);
+        disconnectedAgents.delete(agentId);
 
         transport = new StreamableHTTPServerTransport({
           sessionIdGenerator: () => sessionId!,
diff --git a/src/server/orchestrator/StuckJobWatchdog.ts b/src/server/orchestrator/StuckJobWatchdog.ts
index 8ad2ee5..b19b0c7 100644
--- a/src/server/orchestrator/StuckJobWatchdog.ts
+++ b/src/server/orchestrator/StuckJobWatchdog.ts
@@ -1,7 +1,7 @@
 /**
  * StuckJobWatchdog — periodic runtime monitor for stuck/inconsistent agent state.
  *
- * Runs every 30 seconds and handles three failure modes:
+ * Runs every 30 seconds and handles four failure modes:
  *
  * 1. Dead agents: an agent's tmux session (or legacy PID) has died but the DB
  *    still shows it as running. Mark done/failed and release locks.
@@ -9,7 +9,10 @@
  * 2. Orphaned waits: agent MCP connection dropped while wait_for_jobs was active,
  *    and all waited jobs have since finished. Kill session and re-queue.
  *
- * 3. Job/agent inconsistency: a job is marked terminal but an agent row still
+ * 3. MCP-disconnected agents: agent lost MCP connection outside of wait_for_jobs
+ *    and hasn't reconnected within the grace period. Kill and re-queue.
+ *
+ * 4. Job/agent inconsistency: a job is marked terminal but an agent row still
  *    shows 'running'. Clean up the stale row.
  */
 
@@ -20,10 +23,11 @@ import * as queries from '../db/queries.js';
 import * as socket from '../socket/SocketManager.js';
 import { runAgent, getLogPath } from './AgentRunner.js';
 import { onJobCompleted as debateOnJobCompleted } from './DebateManager.js';
+import { onJobCompleted as workflowOnJobCompleted } from './WorkflowManager.js';
 import { getFileLockRegistry } from './FileLockRegistry.js';
 import { isTmuxSessionAlive, startInteractiveAgent, saveSnapshot } from './PtyManager.js';
 import { handleRetry } from './RetryManager.js';
-import { orphanedWaits, hasActiveTransport } from '../mcp/McpServer.js';
+import { orphanedWaits, disconnectedAgents, hasActiveTransport } from '../mcp/McpServer.js';
 import { isCodexModel, isAutoExitJob } from '../../shared/types.js';
 
 const WATCHDOG_INTERVAL_MS = 30_000;
@@ -99,33 +103,35 @@ function check(): void {
     const pidAlive = agent.pid != null && isPidAlive(agent.pid);
 
     if (tmuxAlive || pidAlive) {
-      // Idle timeout: non-interactive tmux agents (Eye, worker agents) should be making
-      // MCP calls regularly. If updated_at hasn't changed in IDLE_THRESHOLD_MS and there's
-      // no active wait_for_jobs, the agent is likely stuck at Claude's ❯ prompt and will
-      // never call finish_job — kill and restart.
-      const IDLE_THRESHOLD_MS = 90 * 60 * 1000; // 90 minutes
-      if (tmuxAlive && agent.pid == null && !agent.pending_wait_ids) {
+      // Idle timeout: non-interactive agents should be making MCP calls regularly.
+      // If updated_at hasn't changed in IDLE_THRESHOLD_MS and there's no active
+      // wait_for_jobs, the agent is likely stuck (e.g. at Claude's ❯ prompt, or in
+      // a sleep-retry loop after MCP disconnect) — kill and restart.
+      const IDLE_THRESHOLD_MS = 20 * 60 * 1000; // 20 minutes
+      if ((tmuxAlive || pidAlive) && !agent.pending_wait_ids) {
         const idleJob = queries.getJobById(agent.job_id);
         const isStuckCandidate = idleJob && !idleJob.is_interactive && !isAutoExitJob(idleJob as any);
         const idleMs = Date.now() - agent.updated_at;
         if (isStuckCandidate && idleMs > IDLE_THRESHOLD_MS) {
-          console.warn(`[watchdog] non-interactive tmux agent ${agent.id} idle ${Math.round(idleMs / 60000)}min without MCP activity — killing stale session`);
-          saveSnapshot(agent.id);
-          try {
-            execFileSync('tmux', ['kill-session', '-t', `orchestrator-${agent.id}`], { stdio: 'pipe' });
-          } catch { /* already gone */ }
+          console.warn(`[watchdog] non-interactive agent ${agent.id} idle ${Math.round(idleMs / 60000)}min without MCP activity — killing`);
+          if (tmuxAlive) {
+            saveSnapshot(agent.id);
+            try { execFileSync('tmux', ['kill-session', '-t', `orchestrator-${agent.id}`], { stdio: 'pipe' }); } catch { /* already gone */ }
+          }
+          if (agent.pid != null) killProcess(agent.pid);
           queries.updateAgent(agent.id, {
             status: 'failed',
-            error_message: `Agent idle ${Math.round(idleMs / 60000)}min without MCP activity; watchdog killed stale session.`,
+            error_message: `Agent idle ${Math.round(idleMs / 60000)}min without MCP activity; watchdog killed.`,
             finished_at: Date.now(),
           });
           queries.updateJobStatus(agent.job_id, 'failed');
           getFileLockRegistry().releaseAll(agent.id);
+          disconnectedAgents.delete(agent.id);
           const pendingQ = queries.getPendingQuestion(agent.id);
           if (pendingQ) {
             queries.updateQuestion(pendingQ.id, {
               status: 'timeout',
-              answer: '[TIMEOUT] Agent went idle; watchdog killed stale session.',
+              answer: '[TIMEOUT] Agent went idle; watchdog killed.',
               answered_at: Date.now(),
             });
           }
@@ -134,6 +140,7 @@ function check(): void {
           const idleJobFresh = queries.getJobById(agent.job_id);
           if (idleJobFresh) {
             try { socket.emitJobUpdate(idleJobFresh); } catch { /* ignore */ }
+            try { workflowOnJobCompleted(idleJobFresh); } catch { /* ignore */ }
             if (idleJobFresh.repeat_interval_ms) {
               try {
                 const nextJob = queries.scheduleRepeatJob(idleJobFresh);
@@ -243,11 +250,12 @@ function check(): void {
     const updatedAgent = queries.getAgentWithJob(agent.id);
     if (updatedAgent) socket.emitAgentUpdate(updatedAgent);
 
-    // If this job belongs to a debate, trigger the debate state machine
+    // Trigger debate/workflow state machines for the completed job
     const updatedJob = queries.getJobById(agent.job_id);
     if (updatedJob) {
       try { socket.emitJobUpdate(updatedJob); } catch (err) { console.error(`[watchdog] emitJobUpdate error:`, err); }
       try { debateOnJobCompleted(updatedJob); } catch (err) { console.error(`[watchdog] debateOnJobCompleted error:`, err); }
+      try { workflowOnJobCompleted(updatedJob); } catch (err) { console.error(`[watchdog] workflowOnJobCompleted error:`, err); }
       // For repeat jobs (e.g. Eye cycles), schedule the next run so the cycle continues
       if (updatedJob.repeat_interval_ms) {
         try {
@@ -350,7 +358,83 @@ function check(): void {
     console.log(`[watchdog] re-spawned agent ${newAgentId} for job ${job.id}`);
   }
 
-  // ── Check 3: Job/agent inconsistency ───────────────────────────────────────
+  // ── Check 3: MCP-disconnected agents (not in wait_for_jobs) ────────────────
+  // When an MCP session closes and the agent was NOT in wait_for_jobs, it's
+  // tracked in disconnectedAgents. If the agent hasn't reconnected within the
+  // grace period, it's stuck in a sleep-retry loop and should be killed + restarted.
+  const MCP_DISCONNECT_GRACE_MS = 120_000; // 2 minutes
+  for (const [agentId, disconnectedAt] of disconnectedAgents) {
+    if (Date.now() - disconnectedAt < MCP_DISCONNECT_GRACE_MS) continue;
+
+    // Agent reconnected? Clear and skip
+    if (hasActiveTransport(agentId)) {
+      disconnectedAgents.delete(agentId);
+      continue;
+    }
+
+    const agent = queries.getAgentById(agentId);
+    if (!agent || agent.status !== 'running') {
+      disconnectedAgents.delete(agentId);
+      continue;
+    }
+
+    const job = queries.getJobById(agent.job_id);
+    if (!job || TERMINAL.includes(job.status)) {
+      disconnectedAgents.delete(agentId);
+      continue;
+    }
+
+    const stuckMs = Date.now() - disconnectedAt;
+    console.warn(`[watchdog] agent ${agentId} MCP-disconnected ${Math.round(stuckMs / 1000)}s without reconnecting — killing and restarting job ${job.id}`);
+    disconnectedAgents.delete(agentId);
+
+    // Kill the session/process
+    if (isTmuxSessionAlive(agentId)) {
+      saveSnapshot(agentId);
+      try { execFileSync('tmux', ['kill-session', '-t', `orchestrator-${agentId}`], { stdio: 'pipe' }); } catch { /* already gone */ }
+    }
+    if (agent.pid != null) killProcess(agent.pid);
+
+    // Mark old agent failed
+    queries.updateAgent(agent.id, {
+      status: 'failed',
+      error_message: `MCP connection lost (not in wait_for_jobs); watchdog restarted after ${Math.round(stuckMs / 1000)}s.`,
+      finished_at: Date.now(),
+    });
+    queries.updateJobStatus(agent.job_id, 'failed');
+    getFileLockRegistry().releaseAll(agent.id);
+
+    const pendingQ = queries.getPendingQuestion(agent.id);
+    if (pendingQ) {
+      queries.updateQuestion(pendingQ.id, {
+        status: 'timeout',
+        answer: '[TIMEOUT] MCP connection lost; watchdog restarted agent.',
+        answered_at: Date.now(),
+      });
+    }
+
+    const updatedAgent = queries.getAgentWithJob(agent.id);
+    if (updatedAgent) socket.emitAgentUpdate(updatedAgent);
+
+    // Re-queue with a new agent
+    const newAgentId = randomUUID();
+    queries.insertAgent({ id: newAgentId, job_id: job.id, status: 'starting' });
+    queries.updateJobStatus(job.id, 'assigned');
+
+    const newAgentWithJob = queries.getAgentWithJob(newAgentId);
+    if (newAgentWithJob) socket.emitAgentNew(newAgentWithJob);
+    const updatedJob = queries.getJobById(job.id);
+    if (updatedJob) socket.emitJobUpdate(updatedJob);
+
+    if (job.is_interactive) {
+      startInteractiveAgent({ agentId: newAgentId, job });
+    } else {
+      runAgent({ agentId: newAgentId, job, resumeSessionId: agent.session_id ?? undefined });
+    }
+    console.log(`[watchdog] re-spawned agent ${newAgentId} for job ${job.id} (MCP disconnect recovery)`);
+  }
+
+  // ── Check 4: Job/agent inconsistency ───────────────────────────────────────
   // A job is in a terminal state but an agent row still shows 'running'.
   for (const agent of queries.listAllRunningAgents()) {
     const job = queries.getJobById(agent.job_id);
@@ -373,7 +457,7 @@ function check(): void {
     if (updatedAgent) socket.emitAgentUpdate(updatedAgent);
   }
 
-  // ── Check 5: Debates stuck in 'running' with no active jobs ─────────────────
+  // ── Check 6: Debates stuck in 'running' with no active jobs ─────────────────
   // Can happen when the server restarts after debate jobs finish but before the
   // state machine fires — recovery skips agents already in a terminal state so
   // the debate record is never advanced.
diff --git a/src/server/orchestrator/WorkflowManager.ts b/src/server/orchestrator/WorkflowManager.ts
index 5be82d4..c7fa487 100644
--- a/src/server/orchestrator/WorkflowManager.ts
+++ b/src/server/orchestrator/WorkflowManager.ts
@@ -15,9 +15,9 @@ const _processedJobs = new Set<string>();
  * Called from AgentRunner.handleJobCompletion after a job's status is finalized.
  * If the job belongs to a workflow, advances to the next phase or completes the workflow.
  */
-export function onJobCompleted(job: Job): void {
+export function onJobCompleted(job: Job, { force = false }: { force?: boolean } = {}): void {
   if (!job.workflow_id) return;
-  if (_processedJobs.has(job.id)) return;
+  if (!force && _processedJobs.has(job.id)) return;
   _processedJobs.add(job.id);
   // Prevent unbounded growth
   if (_processedJobs.size > 500) {
diff --git a/src/server/orchestrator/recovery.ts b/src/server/orchestrator/recovery.ts
index 79ecaa2..98307b7 100644
--- a/src/server/orchestrator/recovery.ts
+++ b/src/server/orchestrator/recovery.ts
@@ -299,6 +299,6 @@ function _recoverStuckWorkflows(): void {
 
     if (hasNext) continue;
     console.log(`[recovery] workflow ${workflow.id} stuck — ${workflow.current_phase} C${jobCycle} done but no next phase; re-firing onJobCompleted`);
-    try { workflowOnJobCompleted(phaseJob); } catch (err) { console.error(`[recovery] stuck workflow re-fire error:`, err); }
+    try { workflowOnJobCompleted(phaseJob, { force: true }); } catch (err) { console.error(`[recovery] stuck workflow re-fire error:`, err); }
   }
 }

From f51787bd1dd377d00f9da7fb34875f9cc6314f07 Mon Sep 17 00:00:00 2001
From: Barney Hussey-Yeo <bh13731@my.bristol.ac.uk>
Date: Tue, 31 Mar 2026 19:02:00 +0100
Subject: [PATCH 12/19] feat: add StopMode types, DB migration, and query
 support for flexible stopping conditions

Introduces stop_mode ('turns' | 'budget' | 'time' | 'completion') and stop_value
columns on jobs and workflows (per-phase). Adds token accumulator columns on agents.
Backfills existing rows with stop_mode='turns' and stop_value=max_turns.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/server/api/workflows.ts |  6 ++++++
 src/server/db/database.ts   | 26 ++++++++++++++++++++++++++
 src/server/db/queries.ts    | 37 ++++++++++++++++++++++++++++---------
 src/shared/types.ts         | 30 +++++++++++++++++++++++++++++-
 src/test/helpers.ts         |  8 +++++++-
 5 files changed, 96 insertions(+), 11 deletions(-)

diff --git a/src/server/api/workflows.ts b/src/server/api/workflows.ts
index 6ba1696..10fac0b 100644
--- a/src/server/api/workflows.ts
+++ b/src/server/api/workflows.ts
@@ -81,6 +81,12 @@ router.post('/', (req, res) => {
     max_turns_assess: body.maxTurnsAssess ?? 50,
     max_turns_review: body.maxTurnsReview ?? 30,
     max_turns_implement: body.maxTurnsImplement ?? 100,
+    stop_mode_assess: body.stopModeAssess ?? 'turns',
+    stop_value_assess: body.stopValueAssess ?? (body.maxTurnsAssess ?? 50),
+    stop_mode_review: body.stopModeReview ?? 'turns',
+    stop_value_review: body.stopValueReview ?? (body.maxTurnsReview ?? 30),
+    stop_mode_implement: body.stopModeImplement ?? 'turns',
+    stop_value_implement: body.stopValueImplement ?? (body.maxTurnsImplement ?? 100),
     template_id: body.templateId?.trim() || null,
     use_worktree: body.useWorktree === false ? 0 : 1,
     worktree_path: null,
diff --git a/src/server/db/database.ts b/src/server/db/database.ts
index ed342ec..b5b55ca 100644
--- a/src/server/db/database.ts
+++ b/src/server/db/database.ts
@@ -87,6 +87,12 @@ export function initDb(dbPath: string): DatabaseSync {
   if (!agentCols.includes('pending_wait_ids')) {
     db.exec('ALTER TABLE agents ADD COLUMN pending_wait_ids TEXT');
   }
+  if (!agentCols.includes('estimated_input_tokens')) {
+    db.exec('ALTER TABLE agents ADD COLUMN estimated_input_tokens INTEGER');
+  }
+  if (!agentCols.includes('estimated_output_tokens')) {
+    db.exec('ALTER TABLE agents ADD COLUMN estimated_output_tokens INTEGER');
+  }
 
   // FTS5 virtual table for full-text search across agent output
   db.exec(`
@@ -321,6 +327,14 @@ export function initDb(dbPath: string): DatabaseSync {
   if (!jobCols.includes('pre_debate_summary')) {
     db.exec('ALTER TABLE jobs ADD COLUMN pre_debate_summary TEXT');
   }
+  if (!jobCols.includes('stop_mode')) {
+    db.exec("ALTER TABLE jobs ADD COLUMN stop_mode TEXT NOT NULL DEFAULT 'turns'");
+  }
+  if (!jobCols.includes('stop_value')) {
+    db.exec('ALTER TABLE jobs ADD COLUMN stop_value REAL');
+    // Backfill: existing rows get stop_value = max_turns
+    db.exec("UPDATE jobs SET stop_value = max_turns WHERE stop_mode = 'turns' AND stop_value IS NULL");
+  }
 
   // ── Eye: Discussions ───────────────────────────────────────────────────────
   db.exec(`CREATE TABLE IF NOT EXISTS discussions (
@@ -427,6 +441,18 @@ export function initDb(dbPath: string): DatabaseSync {
 
   // Workflow-level worktree columns (single worktree shared across all phases)
   const workflowCols = db.prepare('PRAGMA table_info(workflows)').all().map((c: any) => c.name);
+  if (!workflowCols.includes('stop_mode_assess')) {
+    db.exec("ALTER TABLE workflows ADD COLUMN stop_mode_assess TEXT NOT NULL DEFAULT 'turns'");
+    db.exec('ALTER TABLE workflows ADD COLUMN stop_value_assess REAL');
+    db.exec("ALTER TABLE workflows ADD COLUMN stop_mode_review TEXT NOT NULL DEFAULT 'turns'");
+    db.exec('ALTER TABLE workflows ADD COLUMN stop_value_review REAL');
+    db.exec("ALTER TABLE workflows ADD COLUMN stop_mode_implement TEXT NOT NULL DEFAULT 'turns'");
+    db.exec('ALTER TABLE workflows ADD COLUMN stop_value_implement REAL');
+    // Backfill: existing rows get stop_value = max_turns per phase
+    db.exec("UPDATE workflows SET stop_value_assess = max_turns_assess WHERE stop_mode_assess = 'turns' AND stop_value_assess IS NULL");
+    db.exec("UPDATE workflows SET stop_value_review = max_turns_review WHERE stop_mode_review = 'turns' AND stop_value_review IS NULL");
+    db.exec("UPDATE workflows SET stop_value_implement = max_turns_implement WHERE stop_mode_implement = 'turns' AND stop_value_implement IS NULL");
+  }
   if (!workflowCols.includes('worktree_path')) {
     db.exec('ALTER TABLE workflows ADD COLUMN worktree_path TEXT');
   }
diff --git a/src/server/db/queries.ts b/src/server/db/queries.ts
index 47edd5a..e0f21a1 100644
--- a/src/server/db/queries.ts
+++ b/src/server/db/queries.ts
@@ -1,6 +1,6 @@
 import { randomUUID } from 'crypto';
 import { getDb } from './database.js';
-import type { Job, Agent, AgentWithJob, ChildAgentSummary, Question, FileLock, AgentOutput, AgentOutputSegment, Template, Note, Project, BatchTemplate, Debate, DebateStatus, DebateRole, RetryPolicy, JobStatus, AgentStatus, SearchResult, AgentWarning, Worktree, Nudge, KBEntry, Review, TemplateModelStat, ReviewStatus, Discussion, DiscussionMessage, DiscussionStatus, DiscussionCategory, DiscussionPriority, Proposal, ProposalMessage, ProposalStatus, ProposalCategory, ProposalComplexity, Workflow, WorkflowStatus, WorkflowPhase } from '../../shared/types.js';
+import type { Job, Agent, AgentWithJob, ChildAgentSummary, Question, FileLock, AgentOutput, AgentOutputSegment, Template, Note, Project, BatchTemplate, Debate, DebateStatus, DebateRole, RetryPolicy, JobStatus, AgentStatus, SearchResult, AgentWarning, Worktree, Nudge, KBEntry, Review, TemplateModelStat, ReviewStatus, Discussion, DiscussionMessage, DiscussionStatus, DiscussionCategory, DiscussionPriority, Proposal, ProposalMessage, ProposalStatus, ProposalCategory, ProposalComplexity, Workflow, WorkflowStatus, WorkflowPhase, StopMode } from '../../shared/types.js';
 
 // node:sqlite returns null-prototype objects; shallow-copy to a regular object.
 // SQLite rows are always flat scalars so a shallow copy is sufficient and far
@@ -20,6 +20,8 @@ export function insertJob(job: {
   status?: JobStatus;
   work_dir?: string | null;
   max_turns?: number;
+  stop_mode?: StopMode;
+  stop_value?: number | null;
   model?: string | null;
   template_id?: string | null;
   depends_on?: string | null;
@@ -50,12 +52,14 @@ export function insertJob(job: {
   const db = getDb();
   const now = Date.now();
   db.prepare(`
-    INSERT INTO jobs (id, title, description, context, status, priority, work_dir, max_turns, model, template_id, depends_on, is_interactive, use_worktree, project_id, debate_id, debate_loop, debate_round, debate_role, scheduled_at, repeat_interval_ms, retry_policy, max_retries, retry_count, original_job_id, completion_checks, review_config, review_status, review_parent_job_id, created_by_agent_id, pre_debate_id, pre_debate_summary, workflow_id, workflow_cycle, workflow_phase, created_at, updated_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO jobs (id, title, description, context, status, priority, work_dir, max_turns, stop_mode, stop_value, model, template_id, depends_on, is_interactive, use_worktree, project_id, debate_id, debate_loop, debate_round, debate_role, scheduled_at, repeat_interval_ms, retry_policy, max_retries, retry_count, original_job_id, completion_checks, review_config, review_status, review_parent_job_id, created_by_agent_id, pre_debate_id, pre_debate_summary, workflow_id, workflow_cycle, workflow_phase, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(
     job.id, job.title, job.description, job.context,
     job.status ?? 'queued', job.priority,
     job.work_dir ?? null, job.max_turns ?? 50,
+    job.stop_mode ?? 'turns',
+    job.stop_value ?? null,
     job.model ?? null,
     job.template_id ?? null,
     job.depends_on ?? null,
@@ -405,7 +409,7 @@ export function listAgents(status?: AgentStatus): Agent[] {
   return rows.map((r: any) => cast<Agent>(r));
 }
 
-export function updateAgent(id: string, fields: Partial<Pick<Agent, 'status' | 'pid' | 'session_id' | 'exit_code' | 'error_message' | 'status_message' | 'output_read' | 'base_sha' | 'diff' | 'cost_usd' | 'duration_ms' | 'num_turns' | 'finished_at' | 'pending_wait_ids'>>): void {
+export function updateAgent(id: string, fields: Partial<Pick<Agent, 'status' | 'pid' | 'session_id' | 'exit_code' | 'error_message' | 'status_message' | 'output_read' | 'base_sha' | 'diff' | 'cost_usd' | 'duration_ms' | 'num_turns' | 'estimated_input_tokens' | 'estimated_output_tokens' | 'finished_at' | 'pending_wait_ids'>>): void {
   const db = getDb();
   const sets: string[] = ['updated_at = ?'];
   const values: unknown[] = [Date.now()];
@@ -417,6 +421,18 @@ export function updateAgent(id: string, fields: Partial<Pick<Agent, 'status' | '
   db.prepare(`UPDATE agents SET ${sets.join(', ')} WHERE id = ?`).run(...values);
 }
 
+/** Atomically add token counts to an agent's running totals. */
+export function accumulateAgentTokens(agentId: string, inputTokens: number, outputTokens: number): void {
+  const db = getDb();
+  db.prepare(`
+    UPDATE agents SET
+      estimated_input_tokens = COALESCE(estimated_input_tokens, 0) + ?,
+      estimated_output_tokens = COALESCE(estimated_output_tokens, 0) + ?,
+      updated_at = ?
+    WHERE id = ?
+  `).run(inputTokens, outputTokens, Date.now(), agentId);
+}
+
 export function listBatchAgents(status?: AgentStatus): Agent[] {
   const db = getDb();
   let rows: unknown[];
@@ -556,7 +572,7 @@ export function getAgentsWithJobForSnapshot(): AgentWithJob[] {
   return agents.map(agent => {
     const job = jobMap.get(agent.job_id);
     if (!job) {
-      const stub: Job = { id: agent.job_id, title: '(deleted job)', description: '', context: null, status: 'failed', priority: 0, work_dir: null, max_turns: 0, model: null, template_id: null, depends_on: null, is_interactive: 0, use_worktree: 0, project_id: null, flagged: 0, debate_id: null, debate_loop: null, debate_round: null, debate_role: null, scheduled_at: null, repeat_interval_ms: null, retry_policy: 'none', max_retries: 0, retry_count: 0, original_job_id: null, completion_checks: null, review_config: null, review_status: null, review_parent_job_id: null, created_by_agent_id: null, pre_debate_id: null, pre_debate_summary: null, workflow_id: null, workflow_cycle: null, workflow_phase: null, archived_at: null, created_at: 0, updated_at: 0 };
+      const stub: Job = { id: agent.job_id, title: '(deleted job)', description: '', context: null, status: 'failed', priority: 0, work_dir: null, max_turns: 0, stop_mode: 'turns', stop_value: null, model: null, template_id: null, depends_on: null, is_interactive: 0, use_worktree: 0, project_id: null, flagged: 0, debate_id: null, debate_loop: null, debate_round: null, debate_role: null, scheduled_at: null, repeat_interval_ms: null, retry_policy: 'none', max_retries: 0, retry_count: 0, original_job_id: null, completion_checks: null, review_config: null, review_status: null, review_parent_job_id: null, created_by_agent_id: null, pre_debate_id: null, pre_debate_summary: null, workflow_id: null, workflow_cycle: null, workflow_phase: null, archived_at: null, created_at: 0, updated_at: 0 };
       return { ...agent, diff: null, job: stub, template_name: null, pending_question: null, active_locks: [], child_agents: [], warnings: [] } as AgentWithJob;
     }
     return {
@@ -653,7 +669,7 @@ function enrichAgent(agent: Agent): AgentWithJob {
   const jobRow = db.prepare('SELECT * FROM jobs WHERE id = ?').get(agent.job_id);
   if (!jobRow) {
     // Job was deleted while agent still references it — return a stub
-    const stub: Job = { id: agent.job_id, title: '(deleted job)', description: '', context: null, status: 'failed', priority: 0, work_dir: null, max_turns: 0, model: null, template_id: null, depends_on: null, is_interactive: 0, use_worktree: 0, project_id: null, flagged: 0, debate_id: null, debate_loop: null, debate_round: null, debate_role: null, scheduled_at: null, repeat_interval_ms: null, retry_policy: 'none', max_retries: 0, retry_count: 0, original_job_id: null, completion_checks: null, review_config: null, review_status: null, review_parent_job_id: null, created_by_agent_id: null, pre_debate_id: null, pre_debate_summary: null, workflow_id: null, workflow_cycle: null, workflow_phase: null, archived_at: null, created_at: 0, updated_at: 0 };
+    const stub: Job = { id: agent.job_id, title: '(deleted job)', description: '', context: null, status: 'failed', priority: 0, work_dir: null, max_turns: 0, stop_mode: 'turns', stop_value: null, model: null, template_id: null, depends_on: null, is_interactive: 0, use_worktree: 0, project_id: null, flagged: 0, debate_id: null, debate_loop: null, debate_round: null, debate_role: null, scheduled_at: null, repeat_interval_ms: null, retry_policy: 'none', max_retries: 0, retry_count: 0, original_job_id: null, completion_checks: null, review_config: null, review_status: null, review_parent_job_id: null, created_by_agent_id: null, pre_debate_id: null, pre_debate_summary: null, workflow_id: null, workflow_cycle: null, workflow_phase: null, archived_at: null, created_at: 0, updated_at: 0 };
     return { ...agent, job: stub, template_name: null, pending_question: null, active_locks: [], child_agents: [], warnings: [] };
   }
   const job = cast<Job>(jobRow);
@@ -2082,8 +2098,8 @@ export function getPrReviewsWithNewUserReplies(): any[] {
 export function insertWorkflow(workflow: Workflow): Workflow {
   const db = getDb();
   db.prepare(`
-    INSERT INTO workflows (id, title, task, work_dir, implementer_model, reviewer_model, max_cycles, current_cycle, current_phase, status, milestones_total, milestones_done, project_id, max_turns_assess, max_turns_review, max_turns_implement, template_id, use_worktree, worktree_path, worktree_branch, pr_url, created_at, updated_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO workflows (id, title, task, work_dir, implementer_model, reviewer_model, max_cycles, current_cycle, current_phase, status, milestones_total, milestones_done, project_id, max_turns_assess, max_turns_review, max_turns_implement, stop_mode_assess, stop_value_assess, stop_mode_review, stop_value_review, stop_mode_implement, stop_value_implement, template_id, use_worktree, worktree_path, worktree_branch, pr_url, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(
     workflow.id, workflow.title, workflow.task, workflow.work_dir,
     workflow.implementer_model, workflow.reviewer_model,
@@ -2091,6 +2107,9 @@ export function insertWorkflow(workflow: Workflow): Workflow {
     workflow.milestones_total, workflow.milestones_done,
     workflow.project_id,
     workflow.max_turns_assess, workflow.max_turns_review, workflow.max_turns_implement,
+    workflow.stop_mode_assess, workflow.stop_value_assess ?? null,
+    workflow.stop_mode_review, workflow.stop_value_review ?? null,
+    workflow.stop_mode_implement, workflow.stop_value_implement ?? null,
     workflow.template_id, workflow.use_worktree,
     workflow.worktree_path ?? null, workflow.worktree_branch ?? null, workflow.pr_url ?? null,
     workflow.created_at, workflow.updated_at
@@ -2110,7 +2129,7 @@ export function listWorkflows(): Workflow[] {
   return rows.map((r: any) => cast<Workflow>(r));
 }
 
-export function updateWorkflow(id: string, fields: Partial<Pick<Workflow, 'current_cycle' | 'current_phase' | 'status' | 'milestones_total' | 'milestones_done' | 'worktree_path' | 'worktree_branch' | 'pr_url'>>): Workflow | null {
+export function updateWorkflow(id: string, fields: Partial<Pick<Workflow, 'current_cycle' | 'current_phase' | 'status' | 'milestones_total' | 'milestones_done' | 'worktree_path' | 'worktree_branch' | 'pr_url' | 'stop_mode_assess' | 'stop_value_assess' | 'stop_mode_review' | 'stop_value_review' | 'stop_mode_implement' | 'stop_value_implement'>>): Workflow | null {
   const db = getDb();
   const sets: string[] = ['updated_at = ?'];
   const values: unknown[] = [Date.now()];
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 592d1e4..46d62db 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -6,7 +6,8 @@ export type QuestionStatus = 'pending' | 'answered' | 'timeout';
 export type DebateStatus = 'running' | 'consensus' | 'disagreement' | 'failed' | 'cancelled';
 export type DebateRole = 'claude' | 'codex' | 'post_action' | 'verification_review' | 'verification_response';
 export type RetryPolicy = 'none' | 'same' | 'analyze';
-export type WarningType = 'stalled' | 'high_turns' | 'long_running';
+export type WarningType = 'stalled' | 'high_turns' | 'long_running' | 'budget_warning' | 'time_warning';
+export type StopMode = 'turns' | 'budget' | 'time' | 'completion';
 export type ReviewStatus = 'pending_review' | 'approved' | 'needs_revision';
 export type WorkflowStatus = 'running' | 'complete' | 'blocked' | 'failed' | 'cancelled';
 export type WorkflowPhase = 'idle' | 'assess' | 'review' | 'implement';
@@ -20,6 +21,8 @@ export interface Job {
   priority: number;
   work_dir: string | null;
   max_turns: number;
+  stop_mode: StopMode;
+  stop_value: number | null;  // meaning depends on stop_mode: turns count, dollars, minutes, or null for completion
   model: string | null;       // e.g. "claude-opus-4-6", null = auto-classify
   template_id: string | null; // FK → templates.id
   depends_on: string | null;  // JSON array of job IDs this job must wait for
@@ -96,6 +99,12 @@ export interface Workflow {
   max_turns_assess: number;
   max_turns_review: number;
   max_turns_implement: number;
+  stop_mode_assess: StopMode;
+  stop_value_assess: number | null;
+  stop_mode_review: StopMode;
+  stop_value_review: number | null;
+  stop_mode_implement: StopMode;
+  stop_value_implement: number | null;
   template_id: string | null;
   use_worktree: number;
   worktree_path: string | null;
@@ -121,6 +130,8 @@ export interface Agent {
   cost_usd: number | null;    // total_cost_usd from result event
   duration_ms: number | null; // duration_ms from result event
   num_turns: number | null;   // num_turns from result event
+  estimated_input_tokens: number | null;
+  estimated_output_tokens: number | null;
   pending_wait_ids: string | null; // JSON array of job IDs being waited on (cleared when done)
   started_at: number;
   updated_at: number;
@@ -290,6 +301,15 @@ export interface CodexStreamEvent {
   message?: string;
 }
 
+/** Safety cap for --max-turns when using budget/time/completion modes. */
+export const SAFETY_CAP_TURNS = 1000;
+
+/** Compute the effective --max-turns value for a given stop mode. */
+export function effectiveMaxTurns(mode: StopMode, value: number | null): number {
+  if (mode === 'turns' && value != null) return value;
+  return SAFETY_CAP_TURNS;
+}
+
 /** Returns true for jobs that run with --print and exit naturally (no finish_job needed). */
 export function isAutoExitJob(job: Pick<Job, 'debate_role' | 'workflow_phase'>): boolean {
   return !!(job.debate_role || job.workflow_phase);
@@ -314,6 +334,8 @@ export interface CreateJobRequest {
   priority?: number;
   workDir?: string;
   maxTurns?: number;
+  stopMode?: StopMode;
+  stopValue?: number;
   model?: string;
   templateId?: string;
   dependsOn?: string[]; // job IDs this job must wait for before running
@@ -474,6 +496,12 @@ export interface CreateWorkflowRequest {
   maxTurnsAssess?: number;
   maxTurnsReview?: number;
   maxTurnsImplement?: number;
+  stopModeAssess?: StopMode;
+  stopValueAssess?: number;
+  stopModeReview?: StopMode;
+  stopValueReview?: number;
+  stopModeImplement?: StopMode;
+  stopValueImplement?: number;
   templateId?: string;
   useWorktree?: boolean;
   projectId?: string;
diff --git a/src/test/helpers.ts b/src/test/helpers.ts
index 46d5a57..382d83b 100644
--- a/src/test/helpers.ts
+++ b/src/test/helpers.ts
@@ -165,11 +165,17 @@ export async function insertTestWorkflow(overrides: Partial<{
     max_turns_assess: 50,
     max_turns_review: 30,
     max_turns_implement: 100,
+    stop_mode_assess: 'turns',
+    stop_value_assess: 50,
+    stop_mode_review: 'turns',
+    stop_value_review: 30,
+    stop_mode_implement: 'turns',
+    stop_value_implement: 100,
     template_id: overrides.template_id ?? null,
     use_worktree: overrides.use_worktree ?? 0,
     created_at: Date.now(),
     updated_at: Date.now(),
-  });
+  } as any);
 }
 
 /**

From 6d5feca3f74b86e592b562a3b6b711b30c994257 Mon Sep 17 00:00:00 2001
From: Barney Hussey-Yeo <bh13731@my.bristol.ac.uk>
Date: Tue, 31 Mar 2026 19:03:19 +0100
Subject: [PATCH 13/19] feat: add CostEstimator and token accumulation for
 budget-based stopping

CostEstimator maps model + token counts to estimated USD using a pricing lookup
table. AgentRunner now extracts usage blocks from Claude/Codex stream events and
accumulates token counts on the agent row. Also uses effectiveMaxTurns() to set
--max-turns based on stop_mode (1000 safety cap for budget/time/completion).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/server/orchestrator/AgentRunner.ts   | 43 ++++++++++++++++++++++--
 src/server/orchestrator/CostEstimator.ts | 42 +++++++++++++++++++++++
 2 files changed, 83 insertions(+), 2 deletions(-)
 create mode 100644 src/server/orchestrator/CostEstimator.ts

diff --git a/src/server/orchestrator/AgentRunner.ts b/src/server/orchestrator/AgentRunner.ts
index 8182e7b..555e38d 100644
--- a/src/server/orchestrator/AgentRunner.ts
+++ b/src/server/orchestrator/AgentRunner.ts
@@ -11,7 +11,7 @@ import { runCompletionChecks } from './CompletionChecks.js';
 import { handleRetry } from './RetryManager.js';
 import { triageLearnings } from './MemoryTriager.js';
 import type { Job, ClaudeStreamEvent, CodexStreamEvent } from '../../shared/types.js';
-import { isCodexModel, codexModelName } from '../../shared/types.js';
+import { isCodexModel, codexModelName, effectiveMaxTurns } from '../../shared/types.js';
 import { buildEyePrompt, isEyeJob } from './EyeConfig.js';
 import { ensureCodexTrusted } from './PtyManager.js';
 
@@ -182,7 +182,9 @@ export function runAgent(options: RunOptions): void {
   const errFd = fs.openSync(errPath, 'w');
 
   const workDir = (job as any).work_dir ?? process.cwd();
-  const maxTurns = (job as any).max_turns ?? 50;
+  const stopMode = (job as any).stop_mode ?? 'turns';
+  const stopValue = (job as any).stop_value ?? null;
+  const maxTurns = effectiveMaxTurns(stopMode, stopValue);
   const model: string | null = (job as any).model ?? null;
   const useCodex = isCodexModel(model);
   if (useCodex) ensureCodexTrusted(workDir);
@@ -730,10 +732,47 @@ function handleStreamEvent(agentId: string, event: ClaudeStreamEvent | CodexStre
     queries.updateAgent(agentId, { session_id: (event as CodexStreamEvent).thread_id });
   }
 
+  // Token accumulation for cost estimation (budget stop mode)
+  extractAndAccumulateTokens(agentId, event, raw);
+
   const latestRow = queries.getLatestAgentOutput(agentId);
   if (latestRow) socket.emitAgentOutput(agentId, latestRow);
 }
 
+/**
+ * Extract token usage from Claude assistant events and Codex usage events,
+ * then accumulate on the agent row for cost estimation.
+ */
+function extractAndAccumulateTokens(agentId: string, event: ClaudeStreamEvent | CodexStreamEvent, raw: string): void {
+  let inputTokens = 0;
+  let outputTokens = 0;
+
+  if (event.type === 'assistant') {
+    // Claude assistant events carry usage in the raw JSON (not on the typed interface)
+    try {
+      const parsed = JSON.parse(raw);
+      const usage = parsed.usage;
+      if (usage) {
+        inputTokens = (usage.input_tokens ?? 0)
+          + (usage.cache_creation_input_tokens ?? 0)
+          + (usage.cache_read_input_tokens ?? 0);
+        outputTokens = usage.output_tokens ?? 0;
+      }
+    } catch { /* malformed JSON — skip */ }
+  }
+
+  // Codex emits a top-level usage object on certain events
+  const codexUsage = (event as CodexStreamEvent).usage;
+  if (codexUsage) {
+    inputTokens = (codexUsage.input_tokens ?? 0) + (codexUsage.cached_input_tokens ?? 0);
+    outputTokens = codexUsage.output_tokens ?? 0;
+  }
+
+  if (inputTokens > 0 || outputTokens > 0) {
+    queries.accumulateAgentTokens(agentId, inputTokens, outputTokens);
+  }
+}
+
 function storeOutput(agentId: string, seq: number, eventType: string, content: string): void {
   queries.insertAgentOutput({
     agent_id: agentId,
diff --git a/src/server/orchestrator/CostEstimator.ts b/src/server/orchestrator/CostEstimator.ts
new file mode 100644
index 0000000..9a9fae0
--- /dev/null
+++ b/src/server/orchestrator/CostEstimator.ts
@@ -0,0 +1,42 @@
+/**
+ * Estimate USD cost from model + token counts.
+ *
+ * Pricing is per million tokens. We use regular (non-cached) input pricing
+ * which slightly overestimates when cache reads are involved — safe direction
+ * for budget enforcement.
+ */
+
+interface ModelPricing {
+  inputPerMillion: number;
+  outputPerMillion: number;
+}
+
+// Pricing as of May 2025 — update when Anthropic changes rates.
+const PRICING: Record<string, ModelPricing> = {
+  'claude-opus-4-6':         { inputPerMillion: 15,  outputPerMillion: 75 },
+  'claude-opus-4-6[1m]':     { inputPerMillion: 15,  outputPerMillion: 75 },
+  'claude-sonnet-4-6':       { inputPerMillion: 3,   outputPerMillion: 15 },
+  'claude-sonnet-4-6[1m]':   { inputPerMillion: 3,   outputPerMillion: 15 },
+  'claude-haiku-4-5-20251001': { inputPerMillion: 0.80, outputPerMillion: 4 },
+};
+
+// Default fallback — Sonnet pricing
+const DEFAULT_PRICING: ModelPricing = { inputPerMillion: 3, outputPerMillion: 15 };
+
+function getPricing(model: string | null): ModelPricing {
+  if (!model) return DEFAULT_PRICING;
+  return PRICING[model] ?? DEFAULT_PRICING;
+}
+
+/**
+ * Estimate cost in USD given a model and accumulated token counts.
+ */
+export function estimateCostUsd(
+  model: string | null,
+  inputTokens: number,
+  outputTokens: number,
+): number {
+  const p = getPricing(model);
+  return (inputTokens / 1_000_000) * p.inputPerMillion
+       + (outputTokens / 1_000_000) * p.outputPerMillion;
+}

From 9fb6a9c66619652542e0525d1097262d90d892c6 Mon Sep 17 00:00:00 2001
From: Barney Hussey-Yeo <bh13731@my.bristol.ac.uk>
Date: Tue, 31 Mar 2026 19:14:31 +0100
Subject: [PATCH 14/19] feat: enforce budget and time stopping conditions in
 HealthMonitor

HealthMonitor tick() now checks agents with stop_mode='budget' or 'time':
- Budget: estimates cost from accumulated tokens, warns at 80%, kills at 100%
- Time: compares elapsed time against limit, warns at 80%, kills at 100%
- Agents are stopped gracefully (marked done, not failed) since hitting a
  configured limit is expected behavior, not an error.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/server/orchestrator/HealthMonitor.ts | 80 ++++++++++++++++++++++++
 1 file changed, 80 insertions(+)

diff --git a/src/server/orchestrator/HealthMonitor.ts b/src/server/orchestrator/HealthMonitor.ts
index 0599841..16f0bcd 100644
--- a/src/server/orchestrator/HealthMonitor.ts
+++ b/src/server/orchestrator/HealthMonitor.ts
@@ -3,6 +3,9 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as queries from '../db/queries.js';
 import * as socket from '../socket/SocketManager.js';
+import { estimateCostUsd } from './CostEstimator.js';
+import { getFileLockRegistry } from './FileLockRegistry.js';
+import type { StopMode } from '../../shared/types.js';
 
 const PTY_LOG_DIR = path.join(process.cwd(), 'data', 'agent-logs');
 
@@ -10,6 +13,7 @@ const TICK_INTERVAL_MS = 30_000;
 const STALL_THRESHOLD_MS = 10 * 60 * 1000;  // 10 minutes
 const LONG_RUNNING_THRESHOLD_MS = 60 * 60 * 1000;  // 60 minutes
 const TURN_WARNING_RATIO = 0.8;  // warn at 80% of max_turns
+const LIMIT_WARNING_RATIO = 0.8;  // warn at 80% of budget/time limit
 
 let _timer: NodeJS.Timeout | null = null;
 
@@ -89,7 +93,83 @@ function tick(): void {
         emitWarning(agent.id, 'long_running', `Running for ${mins} minutes`);
       }
     }
+
+    // ── Budget enforcement (stop_mode === 'budget') ──────────────────────
+    const stopMode: StopMode = (job as any).stop_mode ?? 'turns';
+    const stopValue: number | null = (job as any).stop_value ?? null;
+
+    if (stopMode === 'budget' && stopValue != null) {
+      const inputTokens = agent.estimated_input_tokens ?? 0;
+      const outputTokens = agent.estimated_output_tokens ?? 0;
+      const model: string | null = (job as any).model ?? null;
+      const estimated = estimateCostUsd(model, inputTokens, outputTokens);
+      const ratio = estimated / stopValue;
+
+      if (ratio >= 1.0) {
+        console.log(`[health] agent ${agent.id.slice(0, 6)} hit budget limit ($${estimated.toFixed(2)} >= $${stopValue.toFixed(2)}) — stopping gracefully`);
+        killAgentGracefully(agent.id, `Budget limit reached ($${estimated.toFixed(2)}/$${stopValue.toFixed(2)})`);
+      } else if (ratio >= LIMIT_WARNING_RATIO && !queries.hasUndismissedWarning(agent.id, 'budget_warning')) {
+        emitWarning(agent.id, 'budget_warning', `Estimated cost $${estimated.toFixed(2)} (${Math.round(ratio * 100)}% of $${stopValue.toFixed(2)} limit)`);
+      }
+    }
+
+    // ── Time enforcement (stop_mode === 'time') ──────────────────────────
+    if (stopMode === 'time' && stopValue != null && agent.started_at) {
+      const limitMs = stopValue * 60 * 1000; // stopValue is in minutes
+      const elapsed = now - agent.started_at;
+      const ratio = elapsed / limitMs;
+
+      if (ratio >= 1.0) {
+        const mins = Math.round(elapsed / 60_000);
+        console.log(`[health] agent ${agent.id.slice(0, 6)} hit time limit (${mins}min >= ${stopValue}min) — stopping gracefully`);
+        killAgentGracefully(agent.id, `Time limit reached (${mins}/${stopValue} minutes)`);
+      } else if (ratio >= LIMIT_WARNING_RATIO && !queries.hasUndismissedWarning(agent.id, 'time_warning')) {
+        const mins = Math.round(elapsed / 60_000);
+        emitWarning(agent.id, 'time_warning', `Running ${mins} minutes (${Math.round(ratio * 100)}% of ${stopValue}min limit)`);
+      }
+    }
+  }
+}
+
+/**
+ * Gracefully stop an agent that has hit a budget or time limit.
+ * Marks as done (not failed) — the limit was expected, not an error.
+ */
+function killAgentGracefully(agentId: string, reason: string): void {
+  const agent = queries.getAgentById(agentId);
+  if (!agent) return;
+
+  // Kill the process
+  if (agent.pid != null) {
+    try {
+      process.kill(-agent.pid, 'SIGTERM');
+    } catch { /* already gone */ }
+  }
+
+  // Mark agent as done with a status message explaining the stop
+  queries.updateAgent(agentId, {
+    status: 'done',
+    status_message: reason,
+    finished_at: Date.now(),
+  });
+
+  // Mark job as done (limit reached is a successful stop, not a failure)
+  queries.updateJobStatus(agent.job_id, 'done');
+
+  // Release all file locks held by this agent
+  getFileLockRegistry().releaseAll(agentId);
+
+  // Emit updates
+  const agentWithJob = queries.getAgentWithJob(agentId);
+  if (agentWithJob) {
+    try { socket.emitAgentUpdate(agentWithJob); } catch { /* ignore */ }
+  }
+  const updatedJob = queries.getJobById(agent.job_id);
+  if (updatedJob) {
+    try { socket.emitJobUpdate(updatedJob); } catch { /* ignore */ }
   }
+
+  console.log(`[health] agent ${agentId.slice(0, 6)} stopped: ${reason}`);
 }
 
 function emitWarning(agentId: string, type: string, message: string): void {

From 40623f2a6cf26e59857d4330bd524dd5e605a233 Mon Sep 17 00:00:00 2001
From: Barney Hussey-Yeo <bh13731@my.bristol.ac.uk>
Date: Tue, 31 Mar 2026 19:16:25 +0100
Subject: [PATCH 15/19] feat: wire stop_mode/stop_value through
 WorkflowManager, API routes, and MCP tools

WorkflowManager now propagates per-phase stop config (stop_mode, stop_value) to
phase jobs in spawnPhaseJob, startWorkflow, and resumeWorkflow.

API routes (jobs.ts, workflows.ts) accept stopMode/stopValue from clients.
MCP create_job tool gains stop_mode and stop_value parameters.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/server/api/jobs.ts                     |  2 ++
 src/server/mcp/tools/createJob.ts          |  8 ++++--
 src/server/orchestrator/WorkflowManager.ts | 33 ++++++++++++++++++----
 3 files changed, 36 insertions(+), 7 deletions(-)

diff --git a/src/server/api/jobs.ts b/src/server/api/jobs.ts
index e0642db..6b9a088 100644
--- a/src/server/api/jobs.ts
+++ b/src/server/api/jobs.ts
@@ -124,6 +124,8 @@ router.post('/', (req, res) => {
     priority: body.priority ?? 0,
     work_dir: body.workDir ?? null,
     max_turns: body.maxTurns ?? 50,
+    stop_mode: body.stopMode ?? 'turns',
+    stop_value: body.stopValue ?? (body.maxTurns ?? 50),
     model: body.model ?? null,
     template_id: body.templateId ?? null,
     depends_on: body.dependsOn?.length ? JSON.stringify(body.dependsOn) : null,
diff --git a/src/server/mcp/tools/createJob.ts b/src/server/mcp/tools/createJob.ts
index e5233b5..094dcb0 100644
--- a/src/server/mcp/tools/createJob.ts
+++ b/src/server/mcp/tools/createJob.ts
@@ -9,7 +9,9 @@ export const createJobSchema = z.object({
   title: z.string().optional().describe('Short title (auto-generated from first line if omitted)'),
   priority: z.number().optional().describe('Priority 0–10; higher runs sooner (default: 0)'),
   work_dir: z.string().optional().describe("Working directory (defaults to this agent's working directory)"),
-  max_turns: z.number().optional().describe('Max agent turns (default: 50)'),
+  max_turns: z.number().optional().describe('Max agent turns (default: 50). Ignored when stop_mode is not "turns".'),
+  stop_mode: z.enum(['turns', 'budget', 'time', 'completion']).optional().describe('How to stop the agent: "turns" (default), "budget" (dollar limit), "time" (minute limit), or "completion" (run to natural finish)'),
+  stop_value: z.number().optional().describe('Limit value for the stop mode: turn count, dollar amount, or minutes. Not used for "completion".'),
   model: z.string().optional().describe('Model override, e.g. "claude-opus-4-6" (default: auto-classify)'),
   depends_on: z.array(z.string()).optional().describe('Job IDs that must complete before this job runs'),
   use_worktree: z.boolean().optional().describe('Create a git worktree so the agent works in an isolated checkout'),
@@ -17,7 +19,7 @@ export const createJobSchema = z.object({
 });
 
 export async function createJobHandler(agentId: string, input: z.infer<typeof createJobSchema>): Promise<string> {
-  const { description, title, priority, work_dir, max_turns, model, depends_on, use_worktree, repeat_interval_ms } = input;
+  const { description, title, priority, work_dir, max_turns, stop_mode, stop_value, model, depends_on, use_worktree, repeat_interval_ms } = input;
 
   // Inherit work_dir, project_id, and model from calling agent's job if not specified
   let resolvedWorkDir = work_dir ?? null;
@@ -73,6 +75,8 @@ export async function createJobHandler(agentId: string, input: z.infer<typeof cr
     priority: priority ?? 0,
     work_dir: resolvedWorkDir,
     max_turns: max_turns ?? 50,
+    stop_mode: stop_mode ?? 'turns',
+    stop_value: stop_value ?? (max_turns ?? 50),
     model: model ?? inheritedModel,
     template_id: null,
     depends_on: depends_on?.length ? JSON.stringify(depends_on) : null,
diff --git a/src/server/orchestrator/WorkflowManager.ts b/src/server/orchestrator/WorkflowManager.ts
index c7fa487..6a16442 100644
--- a/src/server/orchestrator/WorkflowManager.ts
+++ b/src/server/orchestrator/WorkflowManager.ts
@@ -4,7 +4,8 @@ import { mkdirSync } from 'fs';
 import path from 'path';
 import * as queries from '../db/queries.js';
 import * as socket from '../socket/SocketManager.js';
-import type { Job, Workflow, WorkflowPhase } from '../../shared/types.js';
+import type { Job, Workflow, WorkflowPhase, StopMode } from '../../shared/types.js';
+import { effectiveMaxTurns } from '../../shared/types.js';
 import { buildAssessPrompt, buildReviewPrompt, buildImplementPrompt } from './WorkflowPrompts.js';
 
 // Track jobs we've already processed to prevent double-exit race from triggering
@@ -141,25 +142,33 @@ function spawnPhaseJob(workflow: Workflow, phase: WorkflowPhase, cycle: number):
   const phaseLabels: Record<string, string> = { assess: 'Assess', review: 'Review', implement: 'Implement' };
   const label = phaseLabels[phase] ?? phase;
 
-  // Choose model and max_turns based on phase
+  // Choose model, max_turns, and stop config based on phase
   let model: string;
   let maxTurns: number;
+  let stopMode: StopMode;
+  let stopValue: number | null;
   let prompt: string;
 
   switch (phase) {
     case 'assess':
       model = workflow.implementer_model;
       maxTurns = workflow.max_turns_assess;
+      stopMode = workflow.stop_mode_assess;
+      stopValue = workflow.stop_value_assess;
       prompt = buildAssessPrompt(workflow);
       break;
     case 'review':
       model = workflow.reviewer_model;
       maxTurns = workflow.max_turns_review;
+      stopMode = workflow.stop_mode_review;
+      stopValue = workflow.stop_value_review;
       prompt = buildReviewPrompt(workflow, cycle);
       break;
     case 'implement':
       model = workflow.implementer_model;
       maxTurns = workflow.max_turns_implement;
+      stopMode = workflow.stop_mode_implement;
+      stopValue = workflow.stop_value_implement;
       prompt = buildImplementPrompt(workflow, cycle);
       break;
     default:
@@ -177,7 +186,9 @@ function spawnPhaseJob(workflow: Workflow, phase: WorkflowPhase, cycle: number):
     // All phases share the single workflow-level worktree (created at startWorkflow).
     // use_worktree=0 tells WorkQueueManager not to create another one.
     work_dir: workflow.worktree_path ?? workflow.work_dir,
-    max_turns: maxTurns,
+    max_turns: effectiveMaxTurns(stopMode, stopValue),
+    stop_mode: stopMode,
+    stop_value: stopValue,
     project_id: workflow.project_id,
     use_worktree: 0,
     workflow_id: workflow.id,
@@ -242,7 +253,9 @@ export function startWorkflow(workflow: Workflow): Job {
     model: activeWorkflow.implementer_model,
     template_id: activeWorkflow.template_id,
     work_dir: activeWorkflow.worktree_path ?? activeWorkflow.work_dir,
-    max_turns: activeWorkflow.max_turns_assess,
+    max_turns: effectiveMaxTurns(activeWorkflow.stop_mode_assess, activeWorkflow.stop_value_assess),
+    stop_mode: activeWorkflow.stop_mode_assess,
+    stop_value: activeWorkflow.stop_value_assess,
     project_id: activeWorkflow.project_id,
     use_worktree: 0,
     workflow_id: activeWorkflow.id,
@@ -273,22 +286,30 @@ export function resumeWorkflow(workflow: Workflow): Job {
 
   let model: string;
   let maxTurns: number;
+  let stopMode: StopMode;
+  let stopValue: number | null;
   let prompt: string;
 
   switch (phase) {
     case 'assess':
       model = updated.implementer_model;
       maxTurns = updated.max_turns_assess;
+      stopMode = updated.stop_mode_assess;
+      stopValue = updated.stop_value_assess;
       prompt = buildAssessPrompt(updated);
       break;
     case 'review':
       model = updated.reviewer_model;
       maxTurns = updated.max_turns_review;
+      stopMode = updated.stop_mode_review;
+      stopValue = updated.stop_value_review;
       prompt = buildReviewPrompt(updated, cycle);
       break;
     case 'implement':
       model = updated.implementer_model;
       maxTurns = updated.max_turns_implement;
+      stopMode = updated.stop_mode_implement;
+      stopValue = updated.stop_value_implement;
       prompt = buildImplementPrompt(updated, cycle);
       break;
     default:
@@ -304,7 +325,9 @@ export function resumeWorkflow(workflow: Workflow): Job {
     model,
     template_id: updated.template_id,
     work_dir: updated.worktree_path ?? updated.work_dir,
-    max_turns: maxTurns,
+    max_turns: effectiveMaxTurns(stopMode, stopValue),
+    stop_mode: stopMode,
+    stop_value: stopValue,
     project_id: updated.project_id,
     use_worktree: 0,
     workflow_id: updated.id,

From df9285f11b03db8d4360a7d387f2ed7f43c77a2c Mon Sep 17 00:00:00 2001
From: Barney Hussey-Yeo <bh13731@my.bristol.ac.uk>
Date: Tue, 31 Mar 2026 19:35:39 +0100
Subject: [PATCH 16/19] feat: add StopModePicker UI component and integrate
 into JobForm and WorkflowForm

New StopModePicker component provides a segmented button group for selecting
between Turns, Budget, Time, and Run to Completion modes with contextual
input fields (number for turns, dollar amount for budget, minutes for time).

WorkflowForm: replaces 3 max_turns number inputs with 3 StopModePicker instances.
JobForm: adds a StopModePicker (defaults to 'completion' for ad-hoc jobs).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/client/components/JobForm.tsx        | 15 ++++-
 src/client/components/StopModePicker.tsx | 82 ++++++++++++++++++++++++
 src/client/components/WorkflowForm.tsx   | 56 ++++++++++------
 src/client/styles/globals.css            | 48 ++++++++++++++
 4 files changed, 180 insertions(+), 21 deletions(-)
 create mode 100644 src/client/components/StopModePicker.tsx

diff --git a/src/client/components/JobForm.tsx b/src/client/components/JobForm.tsx
index 26bd3c2..5a3b53a 100644
--- a/src/client/components/JobForm.tsx
+++ b/src/client/components/JobForm.tsx
@@ -1,6 +1,7 @@
 import React, { useState, useEffect } from 'react';
-import type { CreateJobRequest, Job, Template, RetryPolicy, ReviewConfig } from '@shared/types';
+import type { CreateJobRequest, Job, Template, RetryPolicy, ReviewConfig, StopMode } from '@shared/types';
 import { TemplateModelStats } from './TemplateModelStats';
+import { StopModePicker } from './StopModePicker';
 import { useModels } from '../hooks/useModels';
 
 interface JobFormProps {
@@ -21,6 +22,8 @@ export function JobForm({ onSubmit, onClose, availableJobs = [] }: JobFormProps)
   const [dependsOn, setDependsOn] = useState<string[]>([]);
   const [interactive, setInteractive] = useState(true);
   const [useWorktree, setUseWorktree] = useState(false);
+  const [stopMode, setStopMode] = useState<StopMode>('completion');
+  const [stopValue, setStopValue] = useState<number | null>(null);
   const [repeatSeconds, setRepeatSeconds] = useState<number | ''>('');
   const [retryPolicy, setRetryPolicy] = useState<RetryPolicy>('none');
   const [maxRetries, setMaxRetries] = useState(3);
@@ -87,6 +90,8 @@ export function JobForm({ onSubmit, onClose, availableJobs = [] }: JobFormProps)
         dependsOn: dependsOn.length > 0 ? dependsOn : undefined,
         interactive: interactive || undefined,
         useWorktree: useWorktree || undefined,
+        stopMode,
+        stopValue: stopValue ?? undefined,
         repeatIntervalMs: repeatSeconds ? (repeatSeconds as number) * 1000 : undefined,
         retryPolicy: retryPolicy !== 'none' ? retryPolicy : undefined,
         maxRetries: retryPolicy !== 'none' ? maxRetries : undefined,
@@ -251,6 +256,14 @@ export function JobForm({ onSubmit, onClose, availableJobs = [] }: JobFormProps)
             </label>
           </div>
 
+          <StopModePicker
+            label="Stopping condition"
+            mode={stopMode}
+            value={stopValue}
+            onModeChange={setStopMode}
+            onValueChange={setStopValue}
+          />
+
           <div className="form-group">
             <label htmlFor="repeatSeconds">
               Repeat every
diff --git a/src/client/components/StopModePicker.tsx b/src/client/components/StopModePicker.tsx
new file mode 100644
index 0000000..2a67a0f
--- /dev/null
+++ b/src/client/components/StopModePicker.tsx
@@ -0,0 +1,82 @@
+import React from 'react';
+import type { StopMode } from '@shared/types';
+
+interface StopModePickerProps {
+  mode: StopMode;
+  value: number | null;
+  onModeChange: (mode: StopMode) => void;
+  onValueChange: (value: number | null) => void;
+  label?: string;
+}
+
+const MODES: { key: StopMode; label: string }[] = [
+  { key: 'turns', label: 'Turns' },
+  { key: 'budget', label: 'Budget' },
+  { key: 'time', label: 'Time' },
+  { key: 'completion', label: 'Run to Completion' },
+];
+
+export function StopModePicker({ mode, value, onModeChange, onValueChange, label }: StopModePickerProps) {
+  return (
+    <div className="form-group">
+      {label && <label>{label}</label>}
+      <div className="stop-mode-buttons">
+        {MODES.map(m => (
+          <button
+            key={m.key}
+            type="button"
+            className={`stop-mode-btn${mode === m.key ? ' active' : ''}`}
+            onClick={() => {
+              onModeChange(m.key);
+              if (m.key === 'completion') onValueChange(null);
+            }}
+          >
+            {m.label}
+          </button>
+        ))}
+      </div>
+      <div className="stop-mode-input">
+        {mode === 'turns' && (
+          <input
+            type="number"
+            min={10}
+            max={500}
+            value={value ?? ''}
+            onChange={e => onValueChange(Number(e.target.value))}
+            placeholder="50"
+          />
+        )}
+        {mode === 'budget' && (
+          <div className="stop-mode-prefixed-input">
+            <span className="stop-mode-prefix">$</span>
+            <input
+              type="number"
+              min={0.5}
+              max={100}
+              step={0.5}
+              value={value ?? ''}
+              onChange={e => onValueChange(Number(e.target.value))}
+              placeholder="5.00"
+            />
+          </div>
+        )}
+        {mode === 'time' && (
+          <div className="stop-mode-prefixed-input">
+            <input
+              type="number"
+              min={5}
+              max={480}
+              value={value ?? ''}
+              onChange={e => onValueChange(Number(e.target.value))}
+              placeholder="60"
+            />
+            <span className="stop-mode-suffix">min</span>
+          </div>
+        )}
+        {mode === 'completion' && (
+          <span className="stop-mode-hint">Runs until done (safety cap: 1000 turns)</span>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/src/client/components/WorkflowForm.tsx b/src/client/components/WorkflowForm.tsx
index eec7860..083624d 100644
--- a/src/client/components/WorkflowForm.tsx
+++ b/src/client/components/WorkflowForm.tsx
@@ -1,6 +1,7 @@
 import React, { useState, useEffect } from 'react';
-import type { CreateWorkflowRequest, Template } from '@shared/types';
+import type { CreateWorkflowRequest, Template, StopMode } from '@shared/types';
 import { useModels } from '../hooks/useModels';
+import { StopModePicker } from './StopModePicker';
 
 interface WorkflowFormProps {
   onSubmit: (req: CreateWorkflowRequest) => Promise<void>;
@@ -18,9 +19,12 @@ export function WorkflowForm({ onSubmit, onClose }: WorkflowFormProps) {
   const [templateId, setTemplateId] = useState('');
   const [useWorktree, setUseWorktree] = useState(true);
   const [showAdvanced, setShowAdvanced] = useState(false);
-  const [maxTurnsAssess, setMaxTurnsAssess] = useState(50);
-  const [maxTurnsReview, setMaxTurnsReview] = useState(30);
-  const [maxTurnsImplement, setMaxTurnsImplement] = useState(100);
+  const [stopModeAssess, setStopModeAssess] = useState<StopMode>('turns');
+  const [stopValueAssess, setStopValueAssess] = useState<number | null>(50);
+  const [stopModeReview, setStopModeReview] = useState<StopMode>('turns');
+  const [stopValueReview, setStopValueReview] = useState<number | null>(30);
+  const [stopModeImplement, setStopModeImplement] = useState<StopMode>('turns');
+  const [stopValueImplement, setStopValueImplement] = useState<number | null>(100);
   const [templates, setTemplates] = useState<Template[]>([]);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState('');
@@ -51,9 +55,12 @@ export function WorkflowForm({ onSubmit, onClose }: WorkflowFormProps) {
         maxCycles,
         templateId: templateId || undefined,
         useWorktree,
-        maxTurnsAssess,
-        maxTurnsReview,
-        maxTurnsImplement,
+        stopModeAssess,
+        stopValueAssess: stopValueAssess ?? undefined,
+        stopModeReview,
+        stopValueReview: stopValueReview ?? undefined,
+        stopModeImplement,
+        stopValueImplement: stopValueImplement ?? undefined,
       });
       onClose();
     } catch (err: any) {
@@ -164,19 +171,28 @@ export function WorkflowForm({ onSubmit, onClose }: WorkflowFormProps) {
           </button>
 
           {showAdvanced && (
-            <div className="form-row">
-              <div className="form-group">
-                <label htmlFor="wf-assess-turns">Assess max turns</label>
-                <input id="wf-assess-turns" type="number" min={10} max={200} value={maxTurnsAssess} onChange={e => setMaxTurnsAssess(Number(e.target.value))} />
-              </div>
-              <div className="form-group">
-                <label htmlFor="wf-review-turns">Review max turns</label>
-                <input id="wf-review-turns" type="number" min={10} max={200} value={maxTurnsReview} onChange={e => setMaxTurnsReview(Number(e.target.value))} />
-              </div>
-              <div className="form-group">
-                <label htmlFor="wf-impl-turns">Implement max turns</label>
-                <input id="wf-impl-turns" type="number" min={10} max={500} value={maxTurnsImplement} onChange={e => setMaxTurnsImplement(Number(e.target.value))} />
-              </div>
+            <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
+              <StopModePicker
+                label="Assess stopping condition"
+                mode={stopModeAssess}
+                value={stopValueAssess}
+                onModeChange={setStopModeAssess}
+                onValueChange={setStopValueAssess}
+              />
+              <StopModePicker
+                label="Review stopping condition"
+                mode={stopModeReview}
+                value={stopValueReview}
+                onModeChange={setStopModeReview}
+                onValueChange={setStopValueReview}
+              />
+              <StopModePicker
+                label="Implement stopping condition"
+                mode={stopModeImplement}
+                value={stopValueImplement}
+                onModeChange={setStopModeImplement}
+                onValueChange={setStopValueImplement}
+              />
             </div>
           )}
 
diff --git a/src/client/styles/globals.css b/src/client/styles/globals.css
index c5db0ce..2877bf8 100644
--- a/src/client/styles/globals.css
+++ b/src/client/styles/globals.css
@@ -2803,3 +2803,51 @@ body {
 .eye-btn-approve:hover { background: var(--btn-primary-hover) !important; }
 .eye-btn-reject { background: none !important; color: var(--danger) !important; border: 1px solid var(--danger) !important; }
 .eye-btn-reject:hover { background: var(--danger-bg) !important; }
+
+/* ─── StopModePicker ──────────────────────────────────────────────────── */
+.stop-mode-buttons {
+  display: flex;
+  gap: 0;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  overflow: hidden;
+  margin-bottom: 8px;
+}
+.stop-mode-btn {
+  flex: 1;
+  padding: 6px 10px;
+  font-size: 12px;
+  background: var(--bg-secondary);
+  color: var(--text-body);
+  border: none;
+  border-right: 1px solid var(--border);
+  cursor: pointer;
+  transition: background 0.15s, color 0.15s;
+}
+.stop-mode-btn:last-child { border-right: none; }
+.stop-mode-btn:hover { background: var(--bg-hover); }
+.stop-mode-btn.active {
+  background: var(--btn-primary-bg);
+  color: white;
+  font-weight: 600;
+}
+.stop-mode-input { min-height: 32px; }
+.stop-mode-input input[type="number"] { width: 100%; }
+.stop-mode-prefixed-input {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+.stop-mode-prefix,
+.stop-mode-suffix {
+  font-size: 13px;
+  color: var(--text-muted);
+  font-weight: 500;
+  flex-shrink: 0;
+}
+.stop-mode-prefixed-input input { flex: 1; }
+.stop-mode-hint {
+  font-size: 12px;
+  color: var(--text-muted);
+  font-style: italic;
+}

From df7786dd074d745b841ab4646f9fcdd8f1856e7c Mon Sep 17 00:00:00 2001
From: Barney Hussey-Yeo <bh13731@my.bristol.ac.uk>
Date: Tue, 31 Mar 2026 20:51:39 +0100
Subject: [PATCH 17/19] fix: trigger workflow/debate handlers when budget/time
 limit stops an agent

Without this, a workflow phase job killed by budget or time limit would
leave the workflow stuck until the periodic gap detector caught it (~60s).
Now killAgentGracefully calls debateOnJobCompleted and workflowOnJobCompleted
immediately, same as the normal exit path in AgentRunner.handleJobCompletion.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/server/orchestrator/HealthMonitor.ts | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/server/orchestrator/HealthMonitor.ts b/src/server/orchestrator/HealthMonitor.ts
index 16f0bcd..1bbb5da 100644
--- a/src/server/orchestrator/HealthMonitor.ts
+++ b/src/server/orchestrator/HealthMonitor.ts
@@ -5,6 +5,8 @@ import * as queries from '../db/queries.js';
 import * as socket from '../socket/SocketManager.js';
 import { estimateCostUsd } from './CostEstimator.js';
 import { getFileLockRegistry } from './FileLockRegistry.js';
+import { onJobCompleted as debateOnJobCompleted } from './DebateManager.js';
+import { onJobCompleted as workflowOnJobCompleted } from './WorkflowManager.js';
 import type { StopMode } from '../../shared/types.js';
 
 const PTY_LOG_DIR = path.join(process.cwd(), 'data', 'agent-logs');
@@ -167,6 +169,9 @@ function killAgentGracefully(agentId: string, reason: string): void {
   const updatedJob = queries.getJobById(agent.job_id);
   if (updatedJob) {
     try { socket.emitJobUpdate(updatedJob); } catch { /* ignore */ }
+    // Trigger workflow/debate handlers so phases advance immediately
+    try { debateOnJobCompleted(updatedJob); } catch { /* ignore */ }
+    try { workflowOnJobCompleted(updatedJob); } catch { /* ignore */ }
   }
 
   console.log(`[health] agent ${agentId.slice(0, 6)} stopped: ${reason}`);

From 0c3c946a4935dc87f9dc93c7eada36b8fd84fe79 Mon Sep 17 00:00:00 2001
From: Barney Hussey-Yeo <bh13731@my.bristol.ac.uk>
Date: Tue, 31 Mar 2026 21:45:01 +0100
Subject: [PATCH 18/19] fix: remove stale module-level jobs list cache
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The jobsCache Map in jobs.ts cached GET /api/jobs responses for 1.5s
with no invalidation on job mutation. This caused cross-test state
leakage (stale rows from a previous test's DB appeared in subsequent
fresh-DB tests) and was also a production correctness bug where create
or update operations would not be reflected in list responses for up
to 1.5s.

Remove the cache entirely — it was not providing meaningful benefit
relative to the correctness risk.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
---
 src/server/api/jobs.ts | 20 --------------------
 1 file changed, 20 deletions(-)

diff --git a/src/server/api/jobs.ts b/src/server/api/jobs.ts
index 6b9a088..ece21bd 100644
--- a/src/server/api/jobs.ts
+++ b/src/server/api/jobs.ts
@@ -159,19 +159,7 @@ router.post('/', (req, res) => {
   }
 });
 
-// Short-TTL cache — when CPU is contended, prevents duplicate heavy work
-const jobsCache = new Map<string, { data: any; expires: number }>();
-const JOBS_CACHE_TTL = 1500; // 1.5s
-
 router.get('/', (req, res) => {
-  const now = Date.now();
-  const cacheKey = req.originalUrl;
-  const cached = jobsCache.get(cacheKey);
-  if (cached && now < cached.expires) {
-    res.json(cached.data);
-    return;
-  }
-
   let data: any;
   if (req.query.archived === '1' || req.query.archived === 'true') {
     const limit = req.query.limit ? parseInt(req.query.limit as string, 10) : undefined;
@@ -184,14 +172,6 @@ router.get('/', (req, res) => {
     const status = req.query.status as string | undefined;
     data = queries.listJobsSlim(status as any);
   }
-
-  jobsCache.set(cacheKey, { data, expires: now + JOBS_CACHE_TTL });
-  // Evict stale entries to prevent unbounded growth
-  if (jobsCache.size > 20) {
-    for (const [k, v] of jobsCache) {
-      if (now >= v.expires) jobsCache.delete(k);
-    }
-  }
   res.json(data);
 });
 

From e5c2087123efc15ebd313b18a02a24f3a6cfb3b4 Mon Sep 17 00:00:00 2001
From: Barney Hussey-Yeo <bh13731@my.bristol.ac.uk>
Date: Wed, 1 Apr 2026 07:58:58 +0100
Subject: [PATCH 19/19] Add rate limit model fallback and PTY resilience

When Claude API rate limits (429) or overload errors (529) are hit,
the system now automatically detects and recovers:

ModelClassifier: Add a model fallback chain (opus -> sonnet[1m] ->
sonnet -> haiku). Track per-model rate limit cooldowns in both memory
and DB. resolveModel() checks rate limits before assigning models and
falls through the chain to find an available one.

StuckJobWatchdog: Add Check 5 that periodically scans tmux sessions
for rate limit error strings. When an agent has been stuck for >3min,
marks the model as rate-limited, kills the session, and re-queues the
job with a fallback model.

models API: Add GET/POST/DELETE /api/models/rate-limits endpoints for
viewing and managing rate limit state manually.

PtyManager: When node-pty fails to attach (posix_spawnp) but the tmux
session is alive, set up a fallback poll to detect session exit instead
of immediately marking the agent as failed. This lets agents complete
via MCP finish_job despite the PTY viewer being unavailable.

Made-with: Cursor
---
 src/server/api/models.ts                    |  21 ++++
 src/server/orchestrator/ModelClassifier.ts  | 101 ++++++++++++++++++--
 src/server/orchestrator/PtyManager.ts       |  33 +++++--
 src/server/orchestrator/StuckJobWatchdog.ts |  78 +++++++++++++++
 4 files changed, 215 insertions(+), 18 deletions(-)

diff --git a/src/server/api/models.ts b/src/server/api/models.ts
index 5413045..3dffd8b 100644
--- a/src/server/api/models.ts
+++ b/src/server/api/models.ts
@@ -3,6 +3,7 @@ import { readFileSync } from 'fs';
 import { join } from 'path';
 import type { ModelOption } from '../../shared/models.js';
 import { CODEX_MODEL_OPTIONS_FALLBACK, CLAUDE_MODEL_OPTIONS } from '../../shared/models.js';
+import { getRateLimitStatus, markModelRateLimited, clearModelRateLimit } from '../orchestrator/ModelClassifier.js';
 
 const router = Router();
 
@@ -72,7 +73,27 @@ router.get('/', (_req, res) => {
     claude: CLAUDE_MODEL_OPTIONS,
     codex: cachedCodexModels,
     lastFetchedAt,
+    rateLimits: getRateLimitStatus(),
   });
 });
 
+router.get('/rate-limits', (_req, res) => {
+  res.json(getRateLimitStatus());
+});
+
+router.post('/rate-limits', (req, res) => {
+  const { model, cooldownMs } = req.body;
+  if (!model || typeof model !== 'string') {
+    res.status(400).json({ error: 'model is required' });
+    return;
+  }
+  markModelRateLimited(model, cooldownMs ?? 300_000);
+  res.json(getRateLimitStatus());
+});
+
+router.delete('/rate-limits/:model', (req, res) => {
+  clearModelRateLimit(decodeURIComponent(req.params.model));
+  res.json(getRateLimitStatus());
+});
+
 export default router;
diff --git a/src/server/orchestrator/ModelClassifier.ts b/src/server/orchestrator/ModelClassifier.ts
index bc1af77..9b5fea3 100644
--- a/src/server/orchestrator/ModelClassifier.ts
+++ b/src/server/orchestrator/ModelClassifier.ts
@@ -11,24 +11,106 @@ const COMPLEXITY_TO_MODEL: Record<string, string> = {
   complex: 'claude-opus-4-6[1m]',
 };
 
+// ─── Rate Limit Fallback Chain ──────────────────────────────────────────────
+// When a model is rate-limited, fall through to the next available model.
+const MODEL_FALLBACK_CHAIN: string[] = [
+  'claude-opus-4-6[1m]',
+  'claude-sonnet-4-6[1m]',
+  'claude-sonnet-4-6',
+  'claude-haiku-4-5-20251001',
+];
+
+const DEFAULT_COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
+
+const _rateLimitCooldowns = new Map<string, number>();
+
+export function markModelRateLimited(model: string, cooldownMs = DEFAULT_COOLDOWN_MS): void {
+  const expiry = Date.now() + cooldownMs;
+  _rateLimitCooldowns.set(model, expiry);
+  queries.upsertNote(`ratelimit:${model}`, String(expiry), null);
+  console.log(`[classifier] marked ${model} as rate-limited for ${Math.round(cooldownMs / 1000)}s (until ${new Date(expiry).toISOString()})`);
+}
+
+export function clearModelRateLimit(model: string): void {
+  _rateLimitCooldowns.delete(model);
+  try { queries.upsertNote(`ratelimit:${model}`, '0', null); } catch { /* ignore */ }
+}
+
+export function isModelRateLimited(model: string): boolean {
+  const memExpiry = _rateLimitCooldowns.get(model);
+  if (memExpiry) {
+    if (Date.now() < memExpiry) return true;
+    _rateLimitCooldowns.delete(model);
+  }
+  const note = queries.getNote(`ratelimit:${model}`);
+  if (note) {
+    const exp = parseInt(note.value, 10);
+    if (!isNaN(exp) && Date.now() < exp) {
+      _rateLimitCooldowns.set(model, exp);
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Given a preferred model, return the best available model that isn't
+ * currently rate-limited. Falls through MODEL_FALLBACK_CHAIN in order.
+ * If the preferred model isn't in the chain, returns it as-is.
+ */
+export function getFallbackModel(preferredModel: string): string {
+  if (!isModelRateLimited(preferredModel)) return preferredModel;
+  const idx = MODEL_FALLBACK_CHAIN.indexOf(preferredModel);
+  if (idx < 0) return preferredModel;
+  for (let i = idx + 1; i < MODEL_FALLBACK_CHAIN.length; i++) {
+    if (!isModelRateLimited(MODEL_FALLBACK_CHAIN[i])) {
+      console.log(`[classifier] ${preferredModel} rate-limited → falling back to ${MODEL_FALLBACK_CHAIN[i]}`);
+      return MODEL_FALLBACK_CHAIN[i];
+    }
+  }
+  const last = MODEL_FALLBACK_CHAIN[MODEL_FALLBACK_CHAIN.length - 1];
+  console.log(`[classifier] all models rate-limited → using ${last} (lowest tier)`);
+  return last;
+}
+
+export function getRateLimitStatus(): Array<{ model: string; rateLimited: boolean; expiresAt: number | null }> {
+  return MODEL_FALLBACK_CHAIN.map(model => {
+    const memExpiry = _rateLimitCooldowns.get(model);
+    const noteExpiry = (() => {
+      const note = queries.getNote(`ratelimit:${model}`);
+      return note ? parseInt(note.value, 10) : 0;
+    })();
+    const expiry = Math.max(memExpiry ?? 0, noteExpiry);
+    const limited = expiry > Date.now();
+    return { model, rateLimited: limited, expiresAt: limited ? expiry : null };
+  });
+}
+
 /**
  * If the job has no model set (null), ask Haiku to classify it as
  * simple/medium/complex, then map that to haiku/sonnet/opus and persist
  * the result on the job row.
  *
- * If ANTHROPIC_API_KEY is absent or the API call fails, falls back to sonnet
- * so the job still runs.
+ * If the selected model is rate-limited, falls through the fallback chain.
+ * If ANTHROPIC_API_KEY is absent or the API call fails, falls back to sonnet.
  *
  * Returns the model string that should be passed to the agent.
  */
 export async function resolveModel(job: Job): Promise<string> {
-  // Explicit model chosen by user — respect it
-  if (job.model !== null) return job.model;
+  // Explicit model chosen by user — respect it, but check rate limits
+  if (job.model !== null) {
+    const effective = getFallbackModel(job.model);
+    if (effective !== job.model) {
+      queries.updateJobModel(job.id, effective);
+      socket.emitJobUpdate(queries.getJobById(job.id)!);
+    }
+    return effective;
+  }
 
   const apiKey = process.env.ANTHROPIC_API_KEY;
   if (!apiKey) {
-    const fallback = 'claude-sonnet-4-6[1m]';
-    console.warn('[classifier] ANTHROPIC_API_KEY not set — defaulting to sonnet');
+    const fallback = getFallbackModel('claude-sonnet-4-6[1m]');
+    console.warn(`[classifier] ANTHROPIC_API_KEY not set — defaulting to ${fallback}`);
     queries.updateJobModel(job.id, fallback);
     socket.emitJobUpdate(queries.getJobById(job.id)!);
     return fallback;
@@ -62,16 +144,17 @@ export async function resolveModel(job: Job): Promise<string> {
     const data = await response.json() as any;
     const word = (data.content?.[0]?.text ?? '').trim().toLowerCase();
     const complexity = (['simple', 'medium', 'complex'] as const).find(c => word.includes(c)) ?? 'medium';
-    const model = COMPLEXITY_TO_MODEL[complexity];
+    const classified = COMPLEXITY_TO_MODEL[complexity];
+    const model = getFallbackModel(classified);
 
-    console.log(`[classifier] "${job.title}" → ${complexity} → ${model}`);
+    console.log(`[classifier] "${job.title}" → ${complexity} → ${classified}${model !== classified ? ` → ${model} (fallback)` : ''}`);
 
     queries.updateJobModel(job.id, model);
     socket.emitJobUpdate(queries.getJobById(job.id)!);
 
     return model;
   } catch (err) {
-    const fallback = 'claude-sonnet-4-6[1m]';
+    const fallback = getFallbackModel('claude-sonnet-4-6[1m]');
     console.error(`[classifier] failed, falling back to ${fallback}:`, err);
     queries.updateJobModel(job.id, fallback);
     socket.emitJobUpdate(queries.getJobById(job.id)!);
diff --git a/src/server/orchestrator/PtyManager.ts b/src/server/orchestrator/PtyManager.ts
index a8be0c0..c9dc476 100644
--- a/src/server/orchestrator/PtyManager.ts
+++ b/src/server/orchestrator/PtyManager.ts
@@ -404,18 +404,33 @@ export function attachPty(agentId: string, job: Job, cols = 100, rows = 50): voi
       })(),
     });
   } catch (err: any) {
-    // For auto-exit jobs (workflow/debate phases), tailing is already running above —
-    // the job will complete naturally when Claude finishes and calls finish_job.
-    // PTY attachment is visual-only for these jobs, so log a warning and carry on.
+    // PTY viewer failed but the tmux session (and Claude process) may still be running.
+    // For auto-exit jobs, tailing is already set up above.
+    // For all jobs, set up a tmux poll to detect when the agent exits.
     if (isAutoExitJob(job as any)) {
       console.warn(`[pty ${agentId}] PTY attach failed (tailing continues):`, err.message);
-      return;
+    } else {
+      console.warn(`[pty ${agentId}] PTY attach failed (agent may still be running):`, err.message);
+    }
+    if (isTmuxSessionAlive(agentId)) {
+      const exitPoll = setInterval(() => {
+        if (isTmuxSessionAlive(agentId)) return;
+        clearInterval(exitPoll);
+        const agentRec = queries.getAgentById(agentId);
+        const TERMINAL = ['done', 'failed', 'cancelled'];
+        if (agentRec && TERMINAL.includes(agentRec.status)) return;
+        console.log(`[pty ${agentId}] tmux session ended (detected via fallback poll)`);
+        handleJobCompletion(agentId, job, 'done').catch(err2 =>
+          console.error(`[pty ${agentId}] handleJobCompletion error:`, err2)
+        );
+      }, 5000);
+    } else if (!isAutoExitJob(job as any)) {
+      // Tmux session didn't start — genuinely failed
+      queries.updateAgent(agentId, { status: 'failed', error_message: err.message, finished_at: Date.now() });
+      queries.updateJobStatus(job.id, 'failed');
+      const updated = queries.getAgentWithJob(agentId);
+      if (updated) socket.emitAgentUpdate(updated);
     }
-    console.error(`[pty ${agentId}] failed to spawn PTY:`, err.message);
-    queries.updateAgent(agentId, { status: 'failed', error_message: err.message, finished_at: Date.now() });
-    queries.updateJobStatus(job.id, 'failed');
-    const updated = queries.getAgentWithJob(agentId);
-    if (updated) socket.emitAgentUpdate(updated);
     return;
   }
 
diff --git a/src/server/orchestrator/StuckJobWatchdog.ts b/src/server/orchestrator/StuckJobWatchdog.ts
index b19b0c7..f26afb5 100644
--- a/src/server/orchestrator/StuckJobWatchdog.ts
+++ b/src/server/orchestrator/StuckJobWatchdog.ts
@@ -29,6 +29,7 @@ import { isTmuxSessionAlive, startInteractiveAgent, saveSnapshot } from './PtyMa
 import { handleRetry } from './RetryManager.js';
 import { orphanedWaits, disconnectedAgents, hasActiveTransport } from '../mcp/McpServer.js';
 import { isCodexModel, isAutoExitJob } from '../../shared/types.js';
+import { markModelRateLimited, getFallbackModel } from './ModelClassifier.js';
 
 const WATCHDOG_INTERVAL_MS = 30_000;
 
@@ -481,6 +482,83 @@ function check(): void {
     try { debateOnJobCompleted(lastJob); } catch (err) { console.error(`[watchdog] stuck-debate recovery error for debate ${debate.id}:`, err); }
   }
 
+  // ── Check 5: Rate-limited agents in tmux ──────────────────────────────────
+  // Scan all orchestrator tmux sessions for rate limit errors (429/529).
+  // When detected, mark the model as rate-limited, kill the stuck agent,
+  // and restart the job with a fallback model.
+  const RATE_LIMIT_STUCK_THRESHOLD_MS = 3 * 60 * 1000; // 3 minutes stuck on rate limit
+  try {
+    const sessionsRaw = execFileSync('tmux', ['list-sessions', '-F', '#{session_name}'], {
+      encoding: 'utf8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    for (const session of sessionsRaw.split('\n')) {
+      if (!session.startsWith('orchestrator-')) continue;
+      const agentId = session.replace('orchestrator-', '');
+
+      const agent = queries.getAgentById(agentId);
+      if (!agent) continue;
+      // Check agents that are running OR were marked failed by PTY posix_spawnp
+      // (those are actually running in tmux despite the DB status)
+      if (!['running', 'starting', 'failed'].includes(agent.status)) continue;
+
+      const job = queries.getJobById(agent.job_id);
+      if (!job) continue;
+      // Skip if job is already terminal and agent isn't in the PTY-failed state
+      if (TERMINAL.includes(job.status) && agent.status !== 'failed') continue;
+
+      let output: string;
+      try {
+        output = execFileSync('tmux', [
+          'capture-pane', '-t', session, '-p', '-S', '-30',
+        ], { encoding: 'utf8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] });
+      } catch { continue; }
+
+      const hasRateLimit = output.includes('rate_limit_error') || output.includes('overloaded_error');
+      if (!hasRateLimit) continue;
+
+      // Check how long the agent has been stuck (last MCP heartbeat)
+      const stuckMs = Date.now() - agent.updated_at;
+      if (stuckMs < RATE_LIMIT_STUCK_THRESHOLD_MS) continue;
+
+      const currentModel = (job as any).model ?? null;
+      if (!currentModel) continue;
+
+      markModelRateLimited(currentModel, 5 * 60 * 1000);
+      const fallbackModel = getFallbackModel(currentModel);
+
+      if (fallbackModel === currentModel) {
+        console.log(`[watchdog] agent ${agentId.slice(0, 8)} rate-limited on ${currentModel} but no fallback available — letting it retry`);
+        continue;
+      }
+
+      console.warn(`[watchdog] agent ${agentId.slice(0, 8)} stuck on rate limit (${currentModel}, ${Math.round(stuckMs / 60000)}min) → restarting with ${fallbackModel}`);
+
+      saveSnapshot(agentId);
+      try { execFileSync('tmux', ['kill-session', '-t', session], { stdio: 'pipe' }); } catch { /* already gone */ }
+
+      queries.updateAgent(agentId, {
+        status: 'failed',
+        error_message: `Rate-limited on ${currentModel}; watchdog restarting with ${fallbackModel}.`,
+        finished_at: Date.now(),
+      });
+      getFileLockRegistry().releaseAll(agentId);
+
+      // Update the job's model and re-queue it
+      queries.updateJobModel(job.id, fallbackModel);
+      queries.updateJobStatus(job.id, 'queued');
+      const updatedJob = queries.getJobById(job.id);
+      if (updatedJob) socket.emitJobUpdate(updatedJob);
+      const updatedAgent = queries.getAgentWithJob(agentId);
+      if (updatedAgent) socket.emitAgentUpdate(updatedAgent);
+
+      console.log(`[watchdog] re-queued job "${job.title}" with model ${fallbackModel}`);
+    }
+  } catch (err: any) {
+    if (!err.message?.includes('no server running')) {
+      console.warn('[watchdog] rate-limit scan error:', err.message);
+    }
+  }
+
   // ── Check 4: Orphaned locks from terminal agents ────────────────────────────
   const orphaned = queries.getActiveLocksForTerminalAgents();
   if (orphaned.length > 0) {