# treadle A Tangled CI runner (spindle) on Cloudflare Workers. It runs `engine: buildkite` workflows as Buildkite builds and `engine: cloudflare` workflows in Cloudflare Containers (the Runner Durable Object). It serves `org.tangled.ci.*` and `org.tangled.secret.*` XRPC, `GET /docs`, and a read-only MCP server at `/mcp`. ## Rules - Single-tenant: act only on repos owned by `OWNER_DID`. Every entry point that acts on a repo goes through `admitRepo` or `servedRepo`. - Untrusted runs (PRs from others before Approve) never get secrets or the trusted snapshot. - No special cases for one workflow or repo. A rule applies to all workflows, or a workflow field configures it. - Rate-limit unauthenticated endpoints that make upstream requests. XRPC methods that start work call `claimToken`. - MCP tools are read-only and expose only what XRPC and the log stream already serve. ## References - Wire contract: `lexicons/org/tangled` in `tangled.org/core`. Behavior: its `spindle/` and `web/`. Buildkite: buildkite.com/docs/apis (REST API and webhooks). - Workflow format: `docs/workflows.md`, served at `/docs`. Update it when workflow files change. - Containers: developers.cloudflare.com/containers, and the `ctx.container` API in github.com/cloudflare/workerd. - `ROADMAP.md` lists only upstream features that treadle lacks. ## Pitfalls - Deploys roll out with mixed versions, so a new Worker can call an old Durable Object for minutes. Keep RPCs and schema additive. A later alarm must repair state that a failed call leaves. - Durable Objects are in the wrangler `exports` map (no migrations) and reached through `ctx.exports`. The Store keeps its schema version in `ctx.storage.kv`, because `PRAGMA user_version` is not allowed. - Buildkite does not retry webhooks (the Store alarm checks open builds), and allows 50 requests a minute for all callers. Back off on `RateLimit-*`. - Containers: `start()` returns at once and the first `exec()` is the readiness check. `destroy()` is SIGKILL; stop gracefully with `signal(15)` and `monitor()`. A container lives only as long as its Durable Object, and each run starts a fresh one. `cloudflare/debian-trixie` has no git, curl or CA certificates. - After `close()`, a hibernated WebSocket stays in `getWebSockets()` until the peer answers, and `send()` on it throws. Check `readyState`. - Outbound WebSockets do not hibernate and drop on deploy. Use short connections from an alarm with a stored cursor. - Web Crypto has no secp256k1. Use `@noble/curves`. ## Workflow - Use Durable Object tests only for storage and alarm logic. - Tests are hermetic: no network, no host tools. `vitest.config.ts` answers unstubbed requests with 599. Create mock `Response` objects inside the fetch handler. `assertOutput` checks XRPC outputs against `test/fixtures/lexicons`. - Run `pnpm check` before you finish, and `pnpm types` after you change `wrangler.jsonc`. - Push only `master`. A push to `master` deploys through treadle's own `deploy.yml`; a manual `pnpm wrangler deploy` is only a fallback. The deployed treadle runs the workflows of each pushed commit, so a workflow change that needs new code goes in a later commit. - Debug production with Workers Observability, service `treadle`.