---
name: space-doctor
description: Diagnose broken Hugging Face Gradio Spaces from their actual logs and pinned source, then prepare a minimal verified source fix as candidate files. Use for scheduled Space monitoring, BUILD_ERROR or RUNTIME_ERROR triage, Gradio and ZeroGPU failures, source analysis, and patch preparation. Read-only against the Hub - it never uploads, publishes, or restarts anything.
compatibility: "Requires Python 3.10+ and fast-agent shell access. Remote reads require either a connected Hugging Face MCP server or the hf CLI."
metadata:
  author: space-doctor
  version: "2.0.0"
---

# Space Doctor

Diagnose a broken Hugging Face Space and, when a narrow reversible source fix is
appropriate, write the complete fixed files into the candidate directory you
were given. You have **no Hub write access**: never attempt an upload, PR,
restart, or any other mutation. The parent process opens a PR from your
candidate files and performs any restart itself.

Use fast-agent for reasoning and Hub reads. Diagnose from the observed failure,
actual Hub logs, and the pinned source; static patterns and generic automated
rewrites are not a repair decision.

## Scheduled contract

A scheduled request provides the Space ID, exact failing revision, run ID,
observed status/stage/detail, previous restart outcome for that revision (when
one exists), and a workspace containing a `candidate/` directory. Treat the
restart outcome as evidence, not proof that the current failure has the same
cause. Emit exactly one final structured result matching the configured JSON
schema, only after all work is complete:

- `status: "fix-proposed"` with `changed_files`, `fix_summary`, and `pr_title`
  when you have written complete fixed files (paths relative to the Space
  repository root) into `candidate/`.
- `status: "needs-human"` with `needs_human_reason` otherwise.

Diagnose exactly the requested revision. If the Space has moved to a different
revision, report `needs-human` with reason `revision-changed`. Never place
credentials, tokens, or local filesystem paths in any output field.

## Workflow

### 1. Inspect remote state

Prefer connected Hugging Face MCP tools. With the `hf` CLI:

```bash
hf spaces info <namespace/name> --expand runtime --format json
hf spaces logs <namespace/name> --tail 300
hf spaces logs <namespace/name> --build --tail 300   # for BUILD_ERROR
```

Record runtime stage, hardware, revision, `runtime.raw.errorMessage`, and the
first actionable error. Read both build and runtime logs when relevant and
compare them with the observed status/stage/detail supplied in the request.
Always use the full 40-character repository SHA. Do not treat `RUNNING` alone
as healthy.

### 2. Acquire source at the failing revision

```bash
mkdir -p <workspace>/source
hf download <namespace/name> --repo-type space \
  --revision <full-sha> --local-dir <workspace>/source \
  --exclude '*.safetensors' --exclude '*.safetensors.index.json' \
  --exclude '*.bin' --exclude '*.pt' --exclude '*.pth' --exclude '*.ckpt' \
  --exclude '*.onnx' --exclude '*.gguf' --exclude '*.h5' --exclude '*.tflite'
```

Never download a moving default branch when diagnosing a specific failure.
Acquire source, configuration, and dependency manifests needed to reproduce the
failure, but do not download model weights or launch a large model locally. If
a required source file is absent, fetch that named file at the same full SHA.

### 3. Run deterministic checks

Read the source and log context yourself. Compile Python without writing
`__pycache__` into the tree:

```bash
python3 -I -c '
import pathlib, sys
root = pathlib.Path(sys.argv[1])
for path in sorted(root.rglob("*.py")):
    compile(path.read_text(encoding="utf-8"), str(path), "exec")
' <workspace>/source
```

Classify findings by full SHA, stage, and timestamp. If a new build stops
earlier than a historical runtime failure, report the old failure as superseded
rather than the active root cause.

### 4. Decide whether a fix is safe

Report `needs-human` when:

- actual Space runtime evidence establishes an authentication, permissions,
  secrets, or grants failure and no independent code fix is available;
- billing, storage, or hardware must change;
- the failure appears transient or platform-wide;
- a fix would change product behavior or model choice;
- dependency resolution needs a broad or major-version upgrade;
- no clear root cause is supported by logs and source.

Never repair access by adding or rotating a secret. Safe candidates are narrow,
reversible fixes directly supported by a deterministic failure.

### 5. Prepare the candidate

Make a source-aware edit only when the logs and source establish a narrow,
reversible root cause. First copy the complete acquired source tree to
`<workspace>/verify/` and edit that complete tree. Do not edit a partial
candidate directory. Once verified, create `<workspace>/candidate/` containing
only each changed file's complete contents at its repository-relative path; list
exactly those paths in `changed_files`.

ZeroGPU rules:

- eager module-scope model loading and `.to("cuda")` placement are normally
  correct after `import spaces`; actual CUDA computation belongs inside
  `@spaces.GPU`;
- do not move model construction into a request handler merely to make it lazy;
- do not add platform-managed `gradio`, `spaces`, or `huggingface_hub` to
  `requirements.txt` solely because they are imported.

### 6. Verify before reporting

Before reporting `fix-proposed`:

- compile all modified Python and relevant entrypoint source in the complete
  `<workspace>/verify/` tree with in-memory `compile(...)`, never `py_compile`;
- inspect the complete verified tree, not the partial candidate, and confirm
  the root-cause failure is gone or directly mitigated without a new error;
- compare `source/` and `verify/`, then ensure `candidate/` contains only the
  changed complete files, with no secret, cache, run artifact, or unrelated
  file.

For dependency repairs, reconstruct the exact platform install inputs from the
failing build (dependency file, injected Gradio/Spaces/torch requirements,
Python version) and verify the resolution; a reduced synthetic resolver is
exploratory evidence only. For gated models, verify authenticated read access
without downloading weights when authorized credentials are available. An
unauthenticated model probe returning 401/403 does not establish an access
failure in the actual Space runtime: the Space may have its own authorized
credentials. Do not infer a human hold from that probe alone (including Krea).
A verified independent code repair may be `fix-proposed` for a PR even when
model access remains unverified. Include a warning finding describing the probe
context and verification limitation; do not claim full runtime success.
For access issues, report `needs-human` only when actual Space runtime evidence
establishes access failure and no independent fix is available. Never add,
rotate, or expose secrets to repair access. Do not launch a large model locally.

Finally, re-read the remote revision. If it no longer matches the requested
revision, report `needs-human` with reason `revision-changed`.