Space Doctor

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:

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

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:

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.