# Tasks — `@suaveplan/api-worker-host`

> Every checkbox MUST reflect work actually done in this change.

## 0. Pre-flight (non-negotiable)

- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.

## 1. Spec authoring

- [x] 1.1 Read design doc §2.2, §4 (`crashed`), §5.2a, §8.5
- [x] 1.2 Read umbrella
- [x] 1.3 Read `openspec/AGENTS.md` Sections 13 and 14
- [x] 1.4 Draft `proposal.md`
- [x] 1.5 Draft `specs/api-worker-host/spec.md`
- [ ] 1.6 Every requirement carries `**Verified by:**`

## 2. Implementation

- [ ] 2.1 Scaffold `packages/api/api-worker-host/` (`0.1.0`, server-tier `engines.node`, deps: `@suaveplan/api-worker-rpc`, `@suaveplan/api-types`, `@suaveplan/error`, `@suaveplan/logger`, `zod`)
- [ ] 2.2 `src/worker-boot/` — entry script reading `workerData`; imports module; wires capability proxies; emits readiness
- [ ] 2.3 `src/lifecycle-receiver/` — control-port command dispatch (install/start/stop/uninstall/reload)
- [ ] 2.4 `src/crash-detector/` — `uncaughtException` + `unhandledRejection` → `WORKER_CRASHED` envelope + `process.exit(1)`
- [ ] 2.5 `src/budget-guard/` — heap / CPU / wall-clock; configurable thresholds; controlled exit on exceed
- [ ] 2.6 `src/request-dispatcher/` — decode handler invocation, run with `AbortSignal`, encode response
- [ ] 2.7 `src/error-codes.ts` — every `WORKER_*` code
- [ ] 2.8 `src/testing/` — `MessageChannel`-based simulator (no real `Worker` spawn)
- [ ] 2.9 `src/index.ts` — namespace re-exports
- [ ] 2.10 `package.json` `bin` entry for the worker-boot script (so `api-host` can spawn it by name)

## 3. Tests

- [ ] 3.1 `src/worker-boot/worker-boot.test.ts` — simulator boots; readiness emitted; capability proxies wired
- [ ] 3.2 `src/lifecycle-receiver/lifecycle-receiver.test.ts` — each command dispatches; hook throw propagates as `SuaveplanError`
- [ ] 3.3 `src/crash-detector/crash-detector.test.ts` — `uncaughtException` → envelope + non-zero exit code
- [ ] 3.4 `src/budget-guard/budget-guard.test.ts` — heap / CPU / wall-clock each tested independently
- [ ] 3.5 `src/request-dispatcher/request-dispatcher.test.ts` — abort signal fires on main-side cancel
- [ ] 3.6 `tests/integration/real-worker.test.ts` — spawn real `Worker`; end-to-end boot → lifecycle → crash (timeout 30000; `INTEGRATION=1`)
- [ ] 3.7 Every `it(...)` carries `{ timeout: 5000 }` (30000 for integration)

## 4. Documentation

- [ ] 4.1 Sibling `.md` for every implementation `.ts` (≥200 words, basic + advanced examples)
- [ ] 4.2 README links every co-located `.md`
- [ ] 4.3 Update CLAUDE.md

## 5. Pre-archive verification (the 5-gate triple)

- [ ] 5.1 `bun run check` — Biome 0/0/0
- [ ] 5.2 `bunx turbo lint typecheck test --filter=@suaveplan/api-worker-host` — green
- [ ] 5.3 `bunx turbo test:coverage --filter=@suaveplan/api-worker-host` — 100/100/100/100
- [ ] 5.4 `bun scripts/openspec-conformance.ts @suaveplan/api-worker-host` — exit 0
- [ ] 5.5 `bunx turbo build --filter=@suaveplan/api-worker-host` — green

## 6. Pre-archive 7-row checklist

- [ ] 6.1 Generics — `PluginContext<Caps>` flows through worker boot
- [ ] 6.2 Zod at every wire boundary (control-port envelopes)
- [ ] 6.3 Every `WORKER_*` code thrown by at least one path
- [ ] 6.4 Strict-mode behaviors (budget thresholds configurable; off-by-default vs on)
- [ ] 6.5 OTel — N/A (main-host emits crash metrics; worker only signals)
- [ ] 6.6 Lifecycle dedup — N/A (main host owns FSM mutex)
- [ ] 6.7 No retroactive tick

## 7. Archive

- [ ] 7.1 Fold spec delta into `openspec/specs/api-worker-host/spec.md`
- [ ] 7.2 Move to `openspec/archive/<yyyy-mm-dd>-api-worker-host/`
- [ ] 7.3 Tick Stage-3 row in umbrella
- [ ] 7.4 Refresh `MANIFEST.md`