Upload 6 files

ARCHITECTURE.md

@@ -0,0 +1,190 @@
+# Architecture
+
+Agentic Space Factory is a Hugging Face-native productization of the workflow described in Victor's ZeroGPU Spaces article: an agent receives a model-card build goal, follows a shared Pi instruction gist, creates a private Gradio Space, validates it, and records the full run.
+
+```text
+User
+  → Docker/FastAPI orchestrator Space with Hugging Face OAuth
+  → per-user private Storage Bucket
+  → ephemeral Hugging Face Job
+  → Pi coding agent + HF Inference Providers model
+  → generated private target Space
+  → live build progress, traces, reports, validation results
+```
+
+## Core components
+
+### Orchestrator Space
+
+The public product UI is a custom Docker/FastAPI dashboard served at `/`. It uses Hugging Face OAuth and does not store a global admin token.
+
+The UI is organized around three responsibilities:
+
+- **Left column** — storage setup, new build launch, and billing/compute readiness links.
+- **Center workspace** — tabbed detail area with `Active Run` for build runs and `Space Test` for validation runs.
+- **Right column** — `Runs Explorer` for compact navigation and `Run Stats` for aggregate history metrics. The Run Explorer uses delegated row events, cached rerender signatures, relative freshness labels, and a compact two-line row layout so polling does not repeatedly attach listeners or redraw unchanged lists.
+
+### Build workflow
+
+A build starts from a Hugging Face model ID or model-card URL. Before launching a paid Job, the orchestrator runs a metadata-only model pre-scan. The pre-scan reads Hub metadata and small repo files such as the model card, `config.json`, and `model_index.json`; it does not download weights. It looks for runnable examples, Diffusers compatibility, safetensors, unsupported tasks, gated/private access, and custom-code risk.
+
+After an acceptable verdict, the orchestrator launches a Hugging Face Job that:
+
+1. reads the model card and model metadata;
+2. creates a private target Space under the signed-in user's namespace;
+3. launches Pi with a generated `GOAL.md`;
+4. instructs Pi to read the configured GitHub gist before coding;
+5. uploads generated Space files;
+6. attempts hardware assignment on a best-effort basis;
+7. runs health/API checks and, when possible, live generation smoke validation;
+8. writes events, traces, report, and structured artifacts to the user's Storage Bucket.
+
+### Pi instruction model
+
+The worker injects the operational gist into the goal sent to Pi. Pi is expected to follow the gist's workflow for Spaces iteration: inspect logs, patch generated code, upload only relevant files, wait for rebuilds, and verify the generated app through Gradio/API calls.
+
+The local worker adds stricter product requirements around that method:
+
+- generated Spaces stay private;
+- placeholders must not be reported as full inference;
+- blockers must be written explicitly when full inference is impossible;
+- `/health` and generation endpoints should be added where possible;
+- ZeroGPU duration should be informed by measured inference latency when applicable.
+
+### Storage Bucket
+
+Runs are stored in the signed-in user's Bucket, normally:
+
+```text
+https://huggingface.co/buckets/<username>/space-factory-runs
+```
+
+Typical run layout:
+
+```text
+runs/<run_id>/launch.json
+runs/<run_id>/state.json
+runs/<run_id>/summary.json
+runs/<run_id>/events.jsonl
+runs/<run_id>/report.md
+runs/<run_id>/generated/
+runs/<run_id>/tests/
+runs/<run_id>/artifacts/
+runs/<run_id>/traces/raw/
+runs/<run_id>/traces/raw/agent_trace.jsonl
+runs/<run_id>/traces/redacted/
+runs/<run_id>/traces/redacted/agent_trace.jsonl
+runs/<run_id>/logs/
+```
+
+The UI exposes the full run folder through the `Artifacts` button and highlights a small curated trace dock in `Active Run`: raw Pi traces, redacted traces, report, smoke result, and blockers when relevant.
+
+### Validation workflow
+
+Validation runs are separate from build runs. Selecting a validation run in the Run Explorer opens the `Space Test` tab, not `Active Run`.
+
+A validation job:
+
+1. waits for the target Space to be reachable;
+2. discovers Gradio API endpoints when possible;
+3. calls the selected endpoint with configured args/kwargs;
+4. checks the returned output type;
+5. measures latency;
+6. stores returned output artifacts;
+7. writes a validation timeline and summary.
+
+The `Space Test` panel displays validation status, latency, Gradio endpoints, selected endpoint parameters, a point-based progress line, and the validation run actions.
+
+### Run discovery and polling
+
+The Run Explorer reads indexed run summaries from the Bucket. It can recover in-progress or partial runs from `launch.json`, `summary.json`, and `state.json`, so a run can appear before all final artifacts exist.
+
+The frontend avoids duplicate `/api/runs` refreshes, uses delegated event listeners for dynamic lists, and keeps the active run panel responsive by rendering lightweight summaries before heavier run details finish loading.
+
+## Result statuses
+
+- `full_inference_success` �� live generation returned the expected output type.
+- `manual_hardware_required` — the Space exists, but hardware must be configured manually before validation.
+- `full_inference_candidate_health_passed` — the Space boots and appears inference-capable, but live generation was not fully validated.
+- `health_only` — the Space boots, but no real inference path was validated.
+- `technical_blocker` — concrete blockers prevent reliable full inference.
+- `failed` — build, runtime, or validation failed.
+
+## Known limits
+
+- Automatic paid hardware assignment is best-effort and may fail because of OAuth, quota, billing, namespace limits, or restricted hardware availability. The app avoids A100/H200 as automatic fallbacks; if those are needed, select them manually in Space Settings only when available for the account or organization.
+- Numeric spend/quota totals are not mirrored in the app; users should use the Hugging Face Billing dashboard for live usage. The Billing & compute card also centralizes the Inference Providers / paid credits / restricted fallback warning so the New Build form stays focused on build configuration.
+- Raw traces can contain sensitive operational details. Redaction is best-effort, not a formal data-loss-prevention guarantee.
+- Some models require Docker, multi-GPU, custom CUDA/FlashAttention, external services, gated licenses, or manual engineering.
+
+
+## Model pre-scan
+
+The custom API exposes `POST /api/models/pre-scan`, which performs a fast metadata-only scan of the selected Hugging Face model before `/api/build` is enabled in the browser. The scan uses Hub metadata and small files such as `config.json`, `model_index.json`, and `README.md`; it avoids downloading weights. This keeps the feature cheap and prevents accidental compute spend on obviously risky or unsupported model cards.
+
+
+## Frontend stability pass
+
+The production-preview UI avoids listener accumulation by binding navigation, action buttons, run rows, pagination, and endpoint chips with one-time or delegated event handlers. Run list refreshes are deduped through a shared in-flight promise and skip DOM rerenders when the visible signature is unchanged.
+
+CSS is organized around the current three-column layout and keeps narrow panels safe through explicit `min-width: 0`, truncation, and responsive fallbacks for run cards, endpoint chips, activity rows, stats, and pre-scan content.
+
+
+### v114 activity feed iconography
+
+The main `Latest events` feed now renders event-type icons as inline SVG, not emoji and not two-letter text badges. The icon selection is deterministic and local to the frontend: steps such as `upload_files`, `hardware`, `create_space`, `generation_smoke`, `traces`, `report_write`, `auth`, and `model_analysis` map to compact vector symbols. Status classes still control color and motion, so running, success, warning, hardware fallback, and error events stay visually distinct without changing the event payload contract.
+
+### v113 UI and caching notes
+
+Run selection now uses a small client-side detail cache. Previously loaded run details are rendered immediately when the user switches between runs, and the app only fetches missing or stale light/heavy details. This keeps the central `Active Run` / `Space Test` panels responsive without changing the backend run bundle API.
+
+The `New Build` form no longer requires a target Space slug. The backend's `normalize_target_space()` remains the source of truth and generates a `space-factory-<run_id>` slug when the user leaves the field empty.
+
+
+## Navigation note
+
+The top bar intentionally does not include a resume-latest action. Run recovery and historical navigation are handled by the Runs Explorer, with cached run-detail hydration for fast repeat selection.
+
+## Pi diagnosis and structured recovery workflow
+
+The recovery path is diagnosis-first. It runs only after live Space validation fails, and it separates **deciding what to do** from **patching code**.
+
+1. Collect HF build logs, runtime logs, Space status, validation errors, available Gradio API information and the current workspace inventory.
+2. Write `repair/INCIDENT_BRIEF.md` and `repair/PI_DIAGNOSIS_GOAL.md`.
+3. Run Pi/Qwen Coder in blockage diagnosis mode. Pi must not edit files in this step. It writes `repair/REPAIR_DECISION.json`.
+4. The Factory validates the decision against budgets and safety rules. Allowed actions are `wait_for_logs`, `inspect_more_logs`, `factory_rebuild_same_code`, `patch_code`, `request_manual_hardware`, and `declare_technical_blocker`.
+5. Empty or no-reason HF failures cannot go directly to code patching. They are routed through wait/rebuild/blocker decisions unless Pi cites concrete actionable evidence.
+6. A same-code factory rebuild re-uploads the same workspace and revalidates the live Space without changing files. This covers common HF build/runtime flakes where logs are delayed or missing.
+7. A patch repair is allowed only after `patch_code` is accepted. Pi then writes `REPAIR_BRIEF.md`, `REPAIR_PLAN.md`, patches minimally, writes `REPAIR_SUMMARY.md`, and the Factory runs sanity checks before re-uploading.
+8. Recovery is bounded: one wait, one same-code rebuild and one patch repair by default. A final failure produces `TECHNICAL_BLOCKERS.json` / `repair/BLOCKAGE.json` rather than an unbounded loop.
+
+The progress timeline groups these stages under the repair/recovery ring while preserving individual events such as `pi_diagnosis`, `repair_decision`, `factory_rebuild`, `repair_patch`, and `repair_validation`. Terminal failures still create an explicit red failure point.
+
+
+## Unified agentic trace journal
+
+The worker keeps Pi session files and stdout logs, but the canonical product trace is the run-level `agent_trace.jsonl` pair. Each record has a `phase` field (`initial_build`, `diagnosis`, `repair_patch`), an `event`, a status, optional artifacts, and redacted data. This lets the UI and bucket artifacts present the whole autonomous loop — build, failure observation, Pi diagnosis, repair decision, optional patch, and revalidation — as one continuous agent run. The redacted version is generated with the same token redaction used elsewhere and is still best-effort, not a formal DLP guarantee.
+
+
+## Agent recovery UI
+
+The v120 UI makes the core blockage protocol visible in the Active Run panel. When the worker writes `repair/REPAIR_DECISION.json`, `repair/BLOCKAGE.json`, or any recovery events, the **Agent recovery** card appears and summarizes:
+
+- the Pi diagnosis action, such as `wait_for_logs`, `factory_rebuild_same_code`, or `patch_code`;
+- failure category, logs quality, and confidence when available;
+- the recovery ladder: diagnose → decide → act → revalidate;
+- evidence and the next step.
+
+This is intentionally separate from the activity feed. The activity feed remains an event stream, while Agent recovery explains the current agentic recovery strategy. The Run traces dock exposes the unified raw/redacted `agent_trace.jsonl` plus `REPAIR_DECISION.json`, the repair folder, and `BLOCKAGE.json` when present.
+
+
+## v122 stability note
+
+The v122 line intentionally rolls back the experimental v121 client-side caching/polling optimizations after real UI testing exposed flicker and broken build/run behavior. The app keeps the v120 Agent recovery UI and the v118/v119 core blockage protocol, but returns to the proven polling and run-selection model for production stability.
+
+## v123 — Critical Job launch + failure timeline fix
+
+- Fixed a production-critical HF Job startup failure where the large embedded worker script could make Python fail before startup with `argument list too long`.
+- The worker script is now persisted as `runs/<run_id>/_worker.py` in the mounted run bucket before launch, and the Job receives only `WORKER_SCRIPT_PATH`.
+- Kept a small `WORKER_SCRIPT_B64` fallback only for compatibility/manual launch paths; normal app launches no longer put the worker source in env/argv.
+- Added a failure-log fallback so pre-worker Job failures such as `argument list too long` still create an explicit failed timeline event and red failure point.

NEXT_STEPS.md

@@ -0,0 +1,110 @@
+# Next Steps
+
+The current application is stable enough for a controlled production/public-preview deployment. The remaining work is mostly product hardening, observability, and cost transparency rather than core workflow repair.
+
+## Recommended before broad launch
+
+1. **Production smoke checklist**
+   - Run one build that reaches `full_inference_success` automatically.
+   - Run one build that reaches `manual_hardware_required`, then validate after manual hardware selection.
+   - Verify raw/redacted trace links, report link, smoke link, Space link, Settings link, Job link, and full Artifacts folder link.
+   - Verify billing copy and links with a non-Pro and Pro account if possible.
+   - Verify the pre-scan default `Tongyi-MAI/Z-Image-Turbo` returns a positive verdict and still launches successfully.
+
+2. **Cost guardrails**
+   - Add optional per-launch confirmation when fixed GPU fallback is enabled.
+   - Add clearer copy that Jobs and Inference Providers may consume paid compute.
+   - Consider a local user-configurable max validation attempts / max build duration.
+
+3. **Trace safety review**
+   - Add regression examples for token-like strings in raw traces and expected redacted output.
+   - Keep redacted traces clearly labeled as best-effort.
+
+4. **Repair workflow**
+   - Add a user-triggered repair run that reads Space build/runtime logs, asks Pi for a minimal patch, uploads the patch, and re-runs validation.
+   - Keep repair runs separate from initial build runs in the Run Explorer.
+
+5. **Validation presets**
+   - Add presets per pipeline/task: text-to-image, text-generation, image-to-image, ASR, TTS, embeddings, etc.
+   - Prefill endpoint args/kwargs from discovered Gradio schema when confidence is high.
+
+6. **Run retention controls**
+   - Add bulk cleanup for old failed validation runs.
+   - Add optional retention copy in the Run Stats panel.
+
+7. **Pre-scan quality**
+   - Keep adding known-good and known-risk model-card fixtures.
+   - Use scan results to recommend implementation mode and validation presets.
+   - Add clearer detection for custom Diffusers pipelines that are valid but require special generated code.
+
+## Nice-to-have UI improvements
+
+- Add a compact preview for generated output artifacts when the smoke test returns an image/audio/video/file.
+- Consider optional filters for build runs versus validation runs in the compact Run Explorer if histories become large.
+- Add a “failed only” quick filter from Run Stats.
+- Add keyboard shortcuts for refresh and tab switching.
+
+## Current product workflow
+
+```text
+Build from model card
+→ private generated Space
+→ best-effort ZeroGPU/fixed GPU assignment
+→ live health/API checks
+→ measured inference latency when live smoke succeeds
+→ ZeroGPU duration recommendation when applicable
+→ manual hardware selection if required
+→ Space Test validation
+→ full_inference_success when output type and latency are validated
+```
+
+### v113 follow-up notes
+
+The UI now treats the model pre-scan as the build gate, not the manual Space name. If the user leaves the target Space name empty, the backend generates a safe slug from the run ID. Future work could expose the generated name in the launch confirmation before the Job starts, but it should not block the launch.
+
+The Gradio endpoint picker now mirrors the information we can recover from the validation Job's `gradio_client` schema: endpoint name, inputs, outputs, and parameter hints. The action is intentionally named `Set API name` because it copies the selected endpoint into the validation form rather than launching the validation immediately.
+
+
+### v114 follow-up notes
+
+- The event feed now uses inline SVG icons. A future polish pass can add a full event details drawer, but the compact feed should remain readable and avoid emoji/text marker fallbacks.
+
+
+## Repair workflow follow-ups
+
+- Add richer recovery analytics from `REPAIR_DECISION.json`, same-code rebuild outcomes, and Gradio client traces.
+- Surface `INCIDENT_BRIEF.md`, `REPAIR_DECISION.json`, `REPAIR_PLAN.md`, and `REPAIR_SUMMARY.md` previews directly in the UI when recovery was attempted.
+- Consider allowing a second recovery action only when the first action clearly changed the evidence category and the new decision is strongly justified.
+
+
+### v120 note: Agent recovery visibility
+
+The UI now exposes Pi diagnosis/recovery state through the Active Run **Agent recovery** card and links to recovery decision/blockage artifacts. This helps users understand when the Factory is waiting for HF logs, rebuilding the same code, patching, requesting hardware, or declaring a technical blocker.
+
+
+## v122 stability note
+
+The v122 line intentionally rolls back the experimental v121 client-side caching/polling optimizations after real UI testing exposed flicker and broken build/run behavior. The app keeps the v120 Agent recovery UI and the v118/v119 core blockage protocol, but returns to the proven polling and run-selection model for production stability.
+
+## v123 — Critical Job launch + failure timeline fix
+
+- Fixed a production-critical HF Job startup failure where the large embedded worker script could make Python fail before startup with `argument list too long`.
+- The worker script is now persisted as `runs/<run_id>/_worker.py` in the mounted run bucket before launch, and the Job receives only `WORKER_SCRIPT_PATH`.
+- Kept a small `WORKER_SCRIPT_B64` fallback only for compatibility/manual launch paths; normal app launches no longer put the worker source in env/argv.
+- Added a failure-log fallback so pre-worker Job failures such as `argument list too long` still create an explicit failed timeline event and red failure point.
+
+## v124 — Timeline and Run Explorer stabilization
+
+- Fixed the compact Overall Progress timeline so dynamically visible repair/failure groups cannot wrap dots onto a second row.
+- Removed smooth timeline auto-scroll that could cause visible flicker during polling.
+- Simplified Run Explorer type/status badges to neutral type labels and short status labels such as Success, Failed, Running and Manual.
+- Added regression checks for timeline single-row behavior and compact Run Explorer labels.
+
+## v127 — Billing usefulness + UI event/timeline audit
+
+- Reworked the Billing & compute card into an actionable compute checklist: payment readiness, Pi Inference Providers, build Job cost, generated Space hardware and high-tier GPU guardrails.
+- Kept exact spend/quotas delegated to the Hugging Face Billing dashboard instead of inventing usage totals.
+- Audited JS event bindings for one-shot/delegated listeners across navigation, run rows and timeline scroll.
+- Reduced timeline auto-scroll churn: identical timeline renders no longer force keep-visible scrolling after user interaction.
+- Confirmed run selection keeps the immediate cached/optimistic render path before network hydration.
+

PUBLIC_PREVIEW.md

@@ -0,0 +1,79 @@
+# Public Preview
+
+Agentic Space Factory turns Hugging Face model cards into private, testable Gradio Spaces using Hugging Face Jobs, Pi, Inference Providers, and per-user Storage Buckets.
+
+## What it does
+
+- Creates private Spaces from model cards.
+- Runs the build inside an ephemeral Hugging Face Job.
+- Uses Pi with an Inference Providers coding model.
+- Injects the shared GitHub gist as Pi's operational instruction source.
+- Stores state, events, raw/redacted traces, reports, generated files, validation results, and output artifacts in a private user Bucket.
+- Attempts ZeroGPU first when requested, then optional fixed-GPU fallback.
+- Supports manual hardware selection when automatic hardware assignment is unavailable.
+- Runs a separate Space validation job with endpoint discovery, output-type checks, latency measurement, and generated artifact capture.
+
+## Current UI
+
+The dashboard is split into three working areas:
+
+1. **Left column** — Run storage setup, model pre-scan, New Build form, Billing & compute readiness.
+2. **Center tabs** — `Active Run` for build details and `Space Test` for validation details.
+3. **Right column** — Run Explorer for navigation and Run Stats for aggregate history.
+
+The Run Explorer is navigation-only. Build run details live in `Active Run`; validation run details live in `Space Test`.
+
+## Recommended demo path
+
+1. Sign in with Hugging Face OAuth.
+2. Check or create the private run Bucket.
+3. Review the default `Tongyi-MAI/Z-Image-Turbo` example or enter another model card, then run the model pre-scan.
+4. Launch only after the scan returns `safe`/`caution` or after explicitly acknowledging a `risky` verdict.
+5. Watch `Active Run`: progress timeline, latest events, latency when available, Space/Settings/Artifacts links, and trace documents.
+6. If hardware is manual, open Space Settings and select the recommended hardware.
+7. Open `Space Test`, prefill from the build, inspect available Gradio endpoints, click an endpoint to use it, and launch validation.
+8. Confirm `full_inference_success`, measured latency, and saved output artifact.
+
+## What it does not promise
+
+The app does not guarantee that every model card can become a working Space. Some models require large or unusual hardware, Docker, multi-GPU execution, custom kernels, external services, accepted gated licenses, or manual fixes.
+
+## Production-readiness note
+
+The app is suitable for a controlled public-preview or internal production deployment when deployed with OAuth enabled, per-user Buckets, private generated Spaces, and clear billing expectations.
+
+Before broad public launch, keep monitoring:
+
+- Job cost and user quota expectations;
+- token redaction in traces;
+- failed build/validation rates;
+- hardware assignment failure modes;
+- latency and ZeroGPU duration recommendations.
+
+
+## Additional preview checklist
+
+- Pre-scan a few representative model cards before launching Jobs.
+- Confirm that `risky` models require acknowledgement and `unsupported` models stay blocked.
+
+## UI reliability checks
+
+For preview deployments, verify that repeated refreshes do not duplicate click handlers: endpoint chips should update one API field once, run pagination should move one page per click, and run explorer selection/delete should remain independent.
+
+- Repair is one bounded automated retry with visible artifacts and no unbounded loop.
+
+
+## Recovery behavior
+
+If a generated Space fails with HF build/runtime errors, especially empty logs or no-reason runtime errors, the Factory asks Pi to diagnose the blockage before any code patch is allowed. The system may wait for logs, re-upload the same workspace to force a rebuild, patch code once, request manual hardware, or stop with an auditable technical blocker.
+
+
+### v120 note: Agent recovery visibility
+
+The UI now exposes Pi diagnosis/recovery state through the Active Run **Agent recovery** card and links to recovery decision/blockage artifacts. This helps users understand when the Factory is waiting for HF logs, rebuilding the same code, patching, requesting hardware, or declaring a technical blocker.
+
+
+## v122 stability note
+
+The v122 line intentionally rolls back the experimental v121 client-side caching/polling optimizations after real UI testing exposed flicker and broken build/run behavior. The app keeps the v120 Agent recovery UI and the v118/v119 core blockage protocol, but returns to the proven polling and run-selection model for production stability.
+

RECOVERY_ALGORITHM.md

@@ -0,0 +1,83 @@
+# 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.

RELEASE_VALIDATION.md

@@ -0,0 +1,51 @@
+# Release Candidate Validation — v133
+
+This archive is based on `agentic-space-factory-v132-prescan-output-type-sync` and contains no runtime feature changes beyond this validation report.
+
+## Validation date
+
+2026-06-05
+
+## Automated checks
+
+- Pytest suite: `342 passed, 2 warnings`
+- JavaScript syntax:
+  - `web/static/app.js`
+  - `web/static/runs.js`
+  - `web/static/progress.js`
+  - `web/static/api.js`
+  - `web/static/components.js`
+- Python compile check: passed
+- HTML parse check: passed
+
+## Critical demo-path checks
+
+- Job launch uses bucket-mounted worker file via `WORKER_SCRIPT_PATH`, avoiding the previous `argument list too long` failure.
+- Build flow keeps `Qwen/Qwen3-Coder-Next` as the default Pi model.
+- Pi blockage protocol is present:
+  - `INCIDENT_BRIEF.md`
+  - `PI_DIAGNOSIS_GOAL.md`
+  - `REPAIR_DECISION.json`
+  - allowed actions such as `wait_for_logs`, `factory_rebuild_same_code`, `patch_code`, `declare_technical_blocker`
+- Unified agent traces are present via `agent_trace.jsonl`.
+- Agent recovery panel is gated and does not show for normal Pi build steps.
+- Run delete is gated until the run is finished, cancelled, failed, blocked, stale, or manual-action.
+- Space Test prefill is gated until validation results exist.
+- Run trace buttons stay disabled until bucket files exist.
+- Overall progress timeline uses product-facing labels while preserving internal step mapping.
+- Space Test endpoint UI no longer shows the confusing `Set API name` banner.
+- Model pre-scan can infer and sync `Expected output type` when clear.
+
+## Manual demo recommendation
+
+For the safest live demo, use:
+
+- Model: `Tongyi-MAI/Z-Image-Turbo`
+- Expected output: should auto-sync to `Image` after pre-scan
+- Implementation mode: `Strict inference`
+- Hardware: ZeroGPU first, fixed fallback allowed
+- Confirm Billing dashboard before launch
+
+## Known non-blocking warnings
+
+The local test environment emits Hugging Face OAuth experimental/local warnings. These are expected outside a Space environment and do not indicate a failing app test.

SECURITY.md

@@ -0,0 +1,77 @@
+# Security Notes
+
+## Token model
+
+The orchestrator uses Hugging Face OAuth. Do not store a global admin `HF_TOKEN` in the Space.
+
+The signed-in user's OAuth token is passed to Hugging Face Jobs as a secret named `HF_TOKEN`. The worker must not write this token to the Bucket, traces, reports, generated files, events, or logs.
+
+## Resource ownership
+
+Generated Spaces are constrained to the signed-in user's namespace and are private by default.
+
+Validation is limited to Spaces under the signed-in user's namespace. This prevents one user from using the validation workflow to probe arbitrary Spaces.
+
+## Storage Buckets
+
+Each user should use their own private `space-factory-runs` Bucket. Run artifacts can include prompts, generated code, logs, traces, model IDs, endpoint schemas, and output samples.
+
+Bucket links in the UI point to `tree/runs/<run_id>/...` paths. Raw run folders remain available through the `Artifacts` button, while the UI exposes a smaller trace/document dock for common review files.
+
+## Traces
+
+Pi traces are stored in two forms:
+
+- `traces/raw/` — full internal trace. Treat as private.
+- `traces/redacted/` — best-effort redacted trace. Useful for review, but not a formal DLP guarantee.
+
+Never assume redacted traces are safe for public release without review.
+
+## Billing and compute
+
+The product launches Hugging Face Jobs and uses Inference Providers. Both can consume paid compute depending on the user's account, plan, quota, and selected hardware.
+
+The app can display payment/billing readiness signals and links to HF Billing, but does not mirror live spend/quota totals. Users should review live usage in the Hugging Face Billing dashboard.
+
+## Generated Spaces
+
+The app never publishes generated Spaces automatically. Users should review:
+
+- generated code;
+- model license and gated access requirements;
+- dependency and hardware requirements;
+- validation results;
+- raw/redacted traces;
+- any output artifacts;
+
+before making a generated Space public.
+
+## Operational recommendations
+
+For production or public-preview deployment:
+
+- keep generated Spaces private by default;
+- keep per-user Bucket isolation;
+- monitor Job failures and cost surprises;
+- periodically review redaction coverage;
+- avoid broad admin tokens;
+- document that automatic hardware assignment is best-effort.
+
+
+## Model pre-scan security boundary
+
+The fast pre-scan is a risk heuristic, not a full sandbox audit. It reads metadata and small text/config files from the Hub without downloading weights. It can flag obvious concerns such as missing model-card guidance, custom-code indicators, unsafe weight formats, gated/private access, or unsupported tasks, but it does not prove that a model or generated Space is safe.
+
+Treat `safe` as “good enough to launch the controlled build workflow”, not as a security certification.
+
+- Repair artifacts may include log excerpts. Raw traces and repair briefs should be treated as internal unless reviewed/redacted.
+
+
+## Recovery and repair safety
+
+Recovery is diagnosis-first. Pi writes `REPAIR_DECISION.json` before any patch is allowed, and the Factory refuses speculative code repair for empty/no-reason logs. In Strict inference mode, patch repair still runs sanity checks to prevent obvious placeholder or fake-inference substitutions. Repair, incident and blockage artifacts may contain log excerpts and should be treated as internal unless reviewed and redacted.
+
+
+### v120 note: Agent recovery visibility
+
+The UI now exposes Pi diagnosis/recovery state through the Active Run **Agent recovery** card and links to recovery decision/blockage artifacts. This helps users understand when the Factory is waiting for HF logs, rebuilding the same code, patching, requesting hardware, or declaring a technical blocker.