RECOVERY_ALGORITHM.md

# Recovery algorithm

Agentic Space Factory uses the Factory as an observer and guardrail layer, and Pi as the repair agent.

## Roles

### Factory

The Factory is responsible for deterministic observation and state management:

1. poll the Hugging Face Job and generated Space;
2. read `get_space_runtime()` and Space logs;
3. detect terminal build/runtime failures instead of waiting blindly;
4. collect raw evidence into artifacts;
5. give Pi a complete repair context;
6. enforce safe action budgets and cooldowns;
7. re-upload/revalidate after Pi changes the workspace.

The Factory should not solve arbitrary dependency or application bugs by hardcoding fixes.

### Pi

Pi is responsible for the actual agentic repair work:

1. read the HF Spaces gist rules;
2. read `INCIDENT_BRIEF.md`;
3. read `DEPENDENCY_ERROR_BRIEF.md` when present;
4. inspect build/runtime logs and the current workspace;
5. identify the first actionable error;
6. patch the minimal file(s), usually `requirements.txt` for pip failures;
7. explain the patch in `REPAIR_SUMMARY.md`;
8. let the Factory upload and validate the repaired Space.

## Main recovery flow

```text
live validation fails or Space enters BUILD_ERROR/RUNTIME_ERROR
→ Factory collects Space runtime + logs
→ Factory writes build_error_observation.json when applicable
→ Factory writes INCIDENT_BRIEF.md
→ Factory asks Pi for diagnosis
→ Pi writes REPAIR_DECISION.json
→ Factory normalizes unsafe decisions
→ if patch_code:
   Pi receives REPAIR_BRIEF.md + logs + gist + workspace
   Pi patches the existing workspace
   Pi writes REPAIR_SUMMARY.md
   Factory uploads and validates
→ if wait_for_logs / factory_rebuild_same_code:
   Factory applies budget/cooldown guardrails
→ if manual_hardware / technical_blocker:
   UI shows explicit action/blocker
```

## Dependency errors

Dependency errors are not handled by a giant table of hardcoded pins.

The Factory only extracts the first useful pip error and writes `DEPENDENCY_ERROR_BRIEF.md`, for example:

```text
ResolutionImpossible
Cannot install ...
No matching distribution found ...
metadata-generation-failed
```

Then Pi must apply the gist method:

```text
read first actionable error
patch once, surgically
rebuild
validate live
```

## Safety guarantees

- Pi receives `HF_TOKEN` / `HUGGING_FACE_HUB_TOKEN` inside the Job as secrets.
- Token context is recorded only as redacted metadata in `token_context.json`.
- The Factory blocks same-code rebuild loops with budgets and cooldowns.
- The Factory does not continue waiting when the Space is already in `BUILD_ERROR`.
- Repair phases are part of the same run and unified in trace artifacts.