audience: AI coding agents first.

# Factory resolution integration — request

**Goal:** prove supervised runs, bounded target repair, independent protected-machinery repair, live install, incident resolution, and owner contract decisions end-to-end with provider-free canaries.

**Execution authority:** trusted independent agent only. This track validates and installs machinery judging other tracks.

**Canonical design:** `docs/specs/2026-08-09-factory-supervision-and-resolution-design.md`.

## Prerequisites

All producer, coordinator, app API, UI, incident selector, Astryx, and `DiffView` tracks landed and individually green.

## Files

- Create provider-free fixtures under `modules/harness/factory/tests/fixtures/supervision_resolution/`.
- Create end-to-end tests under `modules/harness/factory/tests/test_supervision_resolution_e2e.py`.
- Create incident coordinator fault fixtures beside coordinator tests under `collector/src/incidents/`.
- Modify `packaging/deploy-local.sh` only for final integrated service ordering/health checks.
- Modify existing live smoke scripts under `packaging/` rather than creating duplicate deploy wrappers.
- Add browser probe artifacts inside repo-owned test output paths; run only through `e2e-remote`.

## Contract

Canary must exercise exact production entrypoints and schemas. It may stub provider output, never supervisor/lease/checkpoint/ledger/outbox/artifact/decision machinery.

Required sequence:

1. submit run through `/home/user/.local/bin/factory` and disconnect launcher;
2. worker reaches deterministic target-code failure;
3. resolver rung 1 makes no progress; rung 2 fixes; run resumes and succeeds;
4. separate run reaches deterministic `gate-defective` failure;
5. one factory-sourced incident files idempotently;
6. independent resolver uses isolated worktree, repairs fixture machinery, passes immutable canary, installs live, and lands;
7. original run resumes across original failed gate;
8. verified signed artifact resolves incident only after gate passes;
9. task-contract defect emits complete proposal and pauses;
10. reject-feedback produces exactly one new proposal after simulated coordinator restart;
11. approve later proposal invalidates incompatible checkpoints, refreshes finite epoch, resumes same `adw_id`;
12. reject-and-fail path terminalizes without dispatch.

## Behavior

Run required sequence through real installed entrypoints. Persist one evidence bundle per boundary with run/incident/proposal ids, generation, checkpoint, expected state, actual state, and trace references. Replaying after each injected crash MUST continue same logical run/incident/proposal rather than creating replacements.

## Fault boundaries

Inject one crash after each durable boundary:

- run lease claim;
- worker unit launch before admission receipt;
- phase output before checkpoint commit;
- resolution budget reservation before provider result;
- incident dispatch claim;
- incident launch intent before admission;
- outbox commit before Kanboard delivery;
- live install before artifact signing;
- artifact verification before provisional resolution;
- owner feedback decision before proposal worker admission;
- original-run resume before original-gate result.

Every replay MUST converge idempotently with one active generation, one terminal result, and no duplicate incident/proposal/resolver.

## Safety

- No fork/OOM/PID exhaustion/disk-fill/stress testing on workstation.
- No raw PID kill; use stable test units and verified identity.
- No destructive data-safety fixture.
- No real provider quota; deterministic wrapper only.
- No force/no-verify/reset/clean/stash.

## Out of scope

- Feature implementation not required by integration faults.
- Real-provider quality evaluation or quota consumption.
- Destructive safety testing, performance stress, or production data mutation.
- New deploy/test wrappers when existing packaging entrypoints can own the seam.

## Acceptance

- `python3 -m pytest modules/harness/factory/tests/ -q` clean PASS.
- `bun test` in `collector/` clean PASS.
- `pnpm --filter @overdeck/deck-ui test && pnpm --filter @overdeck/deck-ui typecheck` clean PASS.
- `pnpm --filter web test && pnpm --filter web typecheck && pnpm --filter web build` clean PASS.
- Install live with `bash packaging/deploy-local.sh` before landing integration changes.
- Assert both user services active, real CLI supervised, real collector routes durable across restart, and deployed bytes match tested commits.
- Use `e2e-remote` to verify `/factory/<adwId>` and `/incidents` show exact canary ownership, budgets, attempts, incident, artifact, proposal diff, decisions, resume, and terminal states in both themes.