System design records

4 records, all cited

Real design decisions from the subagentjobs monorepo — the one repo behind the subagent*.com Cloudflare Workers fleet. Each record states the problem as the cited source documents it, the design that shipped, and where it lives in the repo. No hypotheticals: every number here came from a command run at authoring time (2026-07-09; the .build-lock.json count re-run 2026-07-10) or from the cited file's own audit tables.

The shared-kit extraction

problem

A 2026-07-02 grep audit across workers/*/src/index.ts (67 files, 32,437 total lines) found the same hand-rolled code in nearly every worker: function shell( in 65/67 files, sharedCss() in 56/67, the min-width:0 grid-overflow bugfix copy-pasted into 54/67, D1 prepare() boilerplate in 60/67 — a conservative 9,000-15,000 lines of near-identical, independently-driftable boilerplate. Same root cause as the grid-overflow incident, at file level.

design

Extract one shared kit (workers/_shared/kit/: css, shell, http, wellknown, d1crud — 301 lines at iteration 1) imported by relative path, no npm publish step. The extraction has a pass/fail rubric per migrated worker: byte-for-byte behavioral parity (curl diff empty), 30%+ line reduction, clean typecheck, successful deploy, no new deps, accent preserved. A worker is “kit-migrated” only when all six pass — anything short stays flagged, not silently claimed.

where it lives

• workers/_shared/kit/RUBRIC.md
• workers/_shared/kit/*.ts

The build-graph + kit-hash drift gate

problem

wrangler bundles kit imports INTO each worker at deploy time — so editing a kit file silently makes every already-deployed importer stale until it is rebuilt and redeployed. Nothing made that drift loud.

design

Per-worker lock files: each workers/<name>/.build-lock.json records the sha256:16 hash of every kit file that worker was last built+deployed against (90 locks as of 2026-07-10 — find workers -name .build-lock.json | wc -l). scripts/worker-build.sh re-resolves kit deps every run by grepping the worker's own src for ../../_shared/kit/ imports (following kit-internal imports transitively), typechecks, then fails loudly on hash mismatch; --stale reports the whole fleet grouped by kit file. scripts/build-graph.py writes workers/build-graph.json — kit_import edges plus runtime_fetch vs reference edges between sibling sites — so a kit edit's blast radius is queryable, not guessed. This is why a kit edit mid-batch is treated as a fleet relock event.

where it lives

• scripts/worker-build.sh
• scripts/build-graph.py
• workers/*/.build-lock.json

The deploy-runner wedge fix

problem

Deploy sessions died mid-deploy on long foreground terminal calls (the incident band: ≥61s — a first-time npm install, a cold wrangler deploy). Two theories for the session-corruption mechanism were tried and BOTH were falsified by re-checking the data — so any fix depending on a guessed mechanism (“make timeout_ms bigger”) was fragile by construction.

design

A duration-agnostic fix: never run a long foreground call at all. deploy-runner (a uv-managed Python package, 43 tests) renders a step-logging bash script, launches it backgrounded via one short call, and reads success/failure from an explicit log marker (RUN_EXIT=0) rather than from session liveness. Proven with a synthetic 75-second step that completed cleanly while its own launching terminal session had already wedged. It generates and interprets artifacts only — it executes no wrangler/npm itself and bypasses no gate.

where it lives

• plugins/cwc-deploy/skills/deploy-runner/SKILL.md
• plugins/cwc-deploy/memory (incident + dogfood runs)

The fleet-expansion wave protocol

problem

Launching many sites at once invents failure modes single-site deploys don't have: shared-file write races, accent collisions, un-resumable half-finished batches, and closeout reports assembled from agents' memories instead of recorded state. As of 2026-07-09: 108 owned zones, 70 served, 38 unserved.

design

Three rules (new 2026-07-09, born with the 24-site + 1-redirect-worker batch this site is part of): (1) a typed fleet-manifest.toml is the ONLY source of truth — every scaffold field, accent, and verification expectation comes from it, accents allocated in one wave-0 event; (2) parallel authoring but SERIALIZED deploys through exactly one backgrounded deploy-runner script at a time, with shared registration surfaces touched by exactly one agent in the final wave; (3) the ledger is the state — one fact_fleet_deploy Postgres row per domain (pending → deploying → deployed → verified), driven only through scripts/ledger.sh, so a crashed run resumes from SQL, never recall.

where it lives

• plugins/cwc-deploy/skills/fleet-expansion/SKILL.md
• plugins/cwc-deploy/skills/fleet-expansion/fleet-manifest.toml
• crates/durable-store/migrations/postgres/008_fleet_deploy_ledger.sql

Twin fold

agentsystemdesigns.com 301-redirects here — the agent*.com twin of this domain is served by the fleet's redirect worker rather than a duplicate site (see [redirects.agentsystemdesigns] in plugins/cwc-deploy/skills/fleet-expansion/fleet-manifest.toml).

Honest scope

These 4 records are the fleet-level decisions with a written, checkable source. Per-site PRD/ARCHITECTURE records exist for some workers (e.g. workers/subagenttasks/PRD.md) but are not cataloged here yet — this page documents what it has verified, not everything that exists. Every number here is a repo-only fact, a dated snapshot baked at authoring time — nothing on this page is fetched per-request.