audience: AI coding agents first.

# Factory supervisor producer — request

**Goal:** make current factory durably supervised, checkpoint-resumable, and bounded in target-code resolution without allowing runs to edit their judge.

**Execution authority:** trusted independent agent only. NEVER launch this request through current factory; it modifies `modules/harness/factory/**`.

**Canonical design:** `docs/specs/2026-08-09-factory-supervision-and-resolution-design.md`. Its invariants and seams are mandatory.

## Context

Current factory foreground-execs ADWs, persists traces/process identity, manually reconciles dead sessions, and joins `--adw-id` without workflow resume. `agents.execute()` aborts on `status=fail` even after useful changes. Preserve trace/account/preset behavior.

## Files

- Create `modules/harness/factory/adw_modules/contracts.py` — `TaskContractV1`, workflow, checkpoint, lease, policy, and budget runtime schemas.
- Create `modules/harness/factory/adw_modules/supervisor.py` — local IPC, fenced run ownership, stable worker units, reconciliation.
- Create `modules/harness/factory/adw_modules/workflow.py` — versioned phase definitions, typed checkpoint hydration, compatible resume.
- Create `modules/harness/factory/adw_modules/resolution.py` — resolver chain, transactional budget ledger, progress/circuit breakers.
- Create `modules/harness/factory/adw_modules/failure_classifier.py` — deterministic failure classes and protected-path routing.
- Create `modules/workstation/systemd/user/overdeck-factory-supervisor.service` — deployed user service.
- Modify `modules/harness/factory/adw_modules/tracer.py` — additive migrations and generation-checked state/checkpoint/control/budget records.
- Modify `modules/harness/factory/adw_modules/session.py` — worker generation, stable unit/boot/process identity, durable receipts.
- Modify `modules/harness/factory/adw_modules/runner.py` — explicit program counter and phase checkpoint ordering.
- Modify `modules/harness/factory/adw_modules/control.py` — supervisor-backed submit/stop/reconcile/resume.
- Modify `modules/harness/factory/adw_modules/agents.py` — persist non-success envelopes; controller, not envelope status alone, decides escalation.
- Modify `modules/harness/factory/adw_modules/data_types.py` — shared typed output/policy envelopes.
- Modify `modules/harness/factory/adw_modules/config.py` — `resolution` precedence and finite validation.
- Modify `modules/harness/factory/sssf.config.yaml` — shipped finite safety ceilings.
- Modify `modules/harness/factory/presets/fast.yaml` and `modules/harness/factory/presets/deep.yaml` — finite resolver policy overlays.
- Modify `modules/harness/factory/adw_plan_build_test_quality.py` and `modules/harness/factory/adw_sdlc.py` — `WorkflowDefinitionV1` phase IDs, dependencies, loop state, hydration.
- Modify `modules/harness/factory/bin/factory` — submit-and-attach CLI plus supervisor-backed resume/reconcile.
- Modify `packaging/deploy-local.sh` — install/enable service and deploy current factory bytes.
- Create/modify focused tests under `modules/harness/factory/tests/` for every contract below.

## Contract

Copy these types verbatim from canonical design:

- `RunState`, `RunStopReason`, `RunLease`, `RunCheckpointIndex`, `RunControlEvent`.
- `WorkflowDefinitionV1`, `PhaseDefinitionV1`, `PhaseCheckpointV1`.
- `TaskContractV1`, `TaskContractRevisionV1`, `AcceptanceCriterionV1`.
- `ResolverSeat`, `ResolutionBudget`, `ResolutionPolicy`.

Implement `resume_run(adw_id, checkpoint_sequence, resolution_epoch) -> RunResumeReceipt`.

Use SQLite additive migrations only. Canonical state writes are transactional; JSONL/console/UI are projections.

## Behavior

- CLI submission receives durable `{adwId, leaseGeneration, acceptedAt}` then attaches. Client death does not affect ownership.
- Stable unit identity includes boot ID, PID/start ticks, argv digest, and generation.
- Expired live worker resumes only after higher-generation re-fence acknowledgment; otherwise terminate verified identity and hydrate new worker from compatible checkpoint.
- Convert `adw_plan_build_test_quality` and `adw_sdlc` to stable phase IDs with typed persisted outputs and loop state. No downstream Python local may be unavailable after resume.
- Contract revision compatibility uses declared field digests. Incompatible phase and descendants invalidate; ambiguous dependency restarts from admission baseline.
- Policy precedence: central ceiling → shipped config → project config → preset → permitted run override → admitted snapshot.
- Ship `fast` and `deep` budgets exactly as canonical design, including `sameFingerprintLimit=2` and `unsafe:false`.
- Budget ledger reserves before dispatch, reconciles actual usage, and blocks subsequent calls after any ceiling.
- Useful `status=fail` attempt evidence remains available. Gate-set shrink may continue; no diff, regression, repeated fingerprint, protected-path edit, divergence, identity mismatch, or exhausted budget escalates/stops.
- Protected failure never enters target resolver; emit typed incident intent for trusted coordinator.
- Map legacy status values without breaking old traces.

## Out of scope

- Incident coordinator, Kanboard writes, signing keys, `/incidents` UI/API.
- Harness v1/v2.
- Any raw reset/clean/stash recovery.
- Browser/dev-server work.

## Acceptance

- Run `python3 -m pytest modules/harness/factory/tests/ -q`.
- Expected: clean PASS, including launcher disconnect, supervisor restart, re-fencing, checkpoint hydration, contract incompatibility, budget dimensions, progress breakers, and protected failure routing.
- Deploy with `bash packaging/deploy-local.sh`.
- Verify real `/home/user/.local/bin/factory` submits through active `overdeck-factory-supervisor.service`.
- Provider-free canary: disconnect launcher, kill/restart supervisor between phases, resume same `adw_id`, skip only compatible completed phases, finish visibly terminal.