Диагностика и восстановлениеDiagnostics and recovery

1. Что фиксируется локально1. What is captured locally

При включённом crash reporting единый manager обрабатывает необработанные Python/thread exceptions и включает faulthandler для части native failures. В runtime-каталоге логов сохраняются:When crash reporting is enabled, a shared manager handles unhandled Python/thread exceptions and enables faulthandler for some native failures. The runtime log directory may contain:

• session.json — идентификатор и состояние сессии;session identity and state;
• exception.json — структурированное исключение, если оно было;a structured exception, when present;
• faulthandler.log — доступная native/thread диагностика;available native/thread diagnostics;
• runtime logs и дополнительные файлы конкретной crash session.runtime logs and additional files owned by that crash session.

Настройки РАЗРАБОТЧИКУ → Логирование имеют разное время применения. Root level, module-prefix filters и основной file handler перестраиваются сразу для текущего desktop-процесса. Параметры crash manager — enabled, native/all-thread capture, session log и retention — читаются при инициализации и полностью вступают в силу после перезапуска. Startup prompt тоже относится к следующему запуску.Controls under DEVELOPER → Logging have different application timing. The root level, module-prefix filters and main file handler are rebuilt immediately for the current desktop process. Crash-manager settings—enabled, native/all-thread capture, session logging and retention—are read during initialization and take full effect after restart. The startup prompt setting also applies on the next launch.

• Применять автоматически по умолчанию включён при каждом создании страницы и не сохраняется. Если его выключить, controls остаются черновиком до Применить сейчас; Перечитать из файла отбрасывает черновик.Apply automatically starts enabled each time the page is created and is not persisted. If disabled, controls remain a draft until Apply now; Reload from file discards that draft.
• Основной logging.to_file и crash-session session.log — разные handlers. Выключение первого в текущем запуске не закрывает уже установленный session handler.Main logging.to_file and crash-session session.log are separate handlers. Disabling the former during the current run does not close an already installed session handler.
• Module flags фильтруют logger-name prefixes, а не выключают функцию программы. Они применяются к текущему process; отдельные tools/children имеют собственную startup logging configuration.Module flags filter logger-name prefixes; they do not disable product functionality. They apply to the current process, while separate tools and child processes have their own startup logging configuration.

2. Diagnostics bundle2. Diagnostics bundle

1. Откройте блок Crash Reports на странице «Логирование».Open the Crash Reports group on the Logging page.
2. Нажмите Обновить состав. Preview показывает источник, число файлов, общий размер и до 200 archive paths; это manifest, а не просмотр содержимого. Если элементов больше, ZIP всё равно включает полный список.Press Refresh contents. The preview shows the source, file count, total size and up to 200 archive paths; it is a manifest, not a content viewer. If more entries exist, the ZIP still includes the complete set.
3. При необходимости откройте каталоги logs/crash reports и изучите исходные файлы.If needed, open the logs/crash-report folders and inspect the source files.
4. Экспортировать diagnostics bundle создаёт локальный ZIP в выбранном месте.Export diagnostics bundle creates a local ZIP at a chosen location.

В архив добавляется diagnostics_report.json с json_role=diagnostics_report, version и списком файлов/размеров. При наличии незакрытого прошлого report страница выбирает его раньше текущей session. Bundle включает дерево выбранного crash-report и top-level .log/.txt из ScrephData/logs. Проект, autosave, models и вложенные каталоги других компонентов автоматически не прикладываются, хотя логи могут содержать их пути или имена.The archive includes diagnostics_report.json with json_role=diagnostics_report, a version and a file/size manifest. When an unresolved saved report exists, the page selects it before the current session. The bundle contains the selected crash-report tree and top-level .log/.txt files from ScrephData/logs. Projects, autosaves, models and nested directories owned by other components are not attached automatically, although logs may contain their paths or names.

3. Ручная отправка3. Manual submission

• Upload не выполняется молча. Нужны авторизованный аккаунт и нажатие Отправить на сервер либо отдельное согласие в startup prompt. Ручная кнопка сама собирает временный ZIP; предварительный локальный export не обязателен.Upload does not happen silently. It requires an authenticated account and pressing Send to server, or separate consent in the startup prompt. The manual button builds a temporary ZIP itself; a prior local export is not required.
• Logging page показывает manifest. Startup prompt показывает тип/текст ошибки, время и локальный report path, но не список файлов или размер; после «Да» сразу начинается сборка и отправка. Для проверки выберите «Нет», откройте Logging и отправьте вручную. Один и тот же report после показанного prompt повторно автоматически не предлагается.The Logging page displays a manifest. The startup prompt shows the error type/text, time and local report path, but not a file list or size; choosing Yes immediately starts bundle creation and submission. To inspect first, choose No, open Logging and submit manually. The same report is not offered automatically again after the prompt has been shown.
• В multipart входят ZIP, необязательная note, source и metadata среды: platform, Python version, mode, current working directory, session ID и полный local report path. Поле client_version присутствует в protocol, но текущие desktop callers оставляют его пустым; app version находится в session.json.The multipart request contains the ZIP, an optional note, source and environment metadata: platform, Python version, mode, current working directory, session ID and the full local report path. A client_version protocol field exists, but current desktop callers leave it empty; the app version is recorded in session.json.
• Сервер принимает только непустой файл с именем .zip до 25 MB, сохраняет исходный archive и SHA-256, а также записывает account, IP и User-Agent. Автоматического срока удаления server diagnostics сейчас нет.The server accepts only a non-empty file named with a .zip suffix up to 25 MB, stores the original archive and SHA-256, and records the account, IP and User-Agent. There is currently no automatic server-side diagnostics deletion period.
• Перед ручной отправкой просмотрите preview и при необходимости исходные файлы: runtime logs или crash artifacts могут содержать пути, названия проектов и другие сведения рабочего окружения.Before manual submission, review the preview and, when needed, the source files: runtime logs or crash artifacts may contain paths, project names and other workspace details.
• При отсутствии auth token, bundle или сети операция завершается явной ошибкой; локальный экспорт остаётся доступным.If the auth token, bundle or network is unavailable, the operation fails explicitly; local export remains available.

4. Восстановление проекта4. Project recovery

Crash report не заменяет autosave проекта. Selector ведёт отдельный канонический autosave_session.json, а Capture — собственный recording autosave. При старте Selector принимает autosave, если восстановились elements/edges или хотя бы base image. Capture сначала пытается вернуть saved media timeline, затем newest close_autosave_*, и ничего не подменяет, если timeline уже непустой.A crash report does not replace project autosave. Selector maintains a separate canonical autosave_session.json, while Capture owns its recording autosave. At startup, Selector accepts the autosave when elements or edges, or at least a base image, are restored. Capture first attempts to restore the saved media timeline, then the newest close_autosave_*, and replaces nothing when the timeline is already populated.

Через Файл → Загрузить проект можно открыть Project Manager, выбрать вкладку Автосейвы и скопировать всю папку autosave в отдельный проект под новым именем. Но Manager разрешает это только для autosave с ненулевым domain count; screenshot-only recovery остаётся startup-only границей текущего UI.Through File → Load Project, Project Manager can open the Autosaves tab and copy the whole autosave directory into a separate project under a new name. Manager only permits this for an autosave with a non-zero domain count, however; screenshot-only recovery remains a startup-only boundary in the current UI.

Если autosave при закрытии не записался, Screph не скрывает ошибку и запрашивает решение о закрытии. Project Manager отделяет неоткрываемые exports и повреждённые JSON в «Проблемные», но его pre-open diagnostics не являются свежей полной artifact-integrity проверкой. После загрузки более подробный domain load report и сохранённые save diagnostics появляются в InfoPanel.If autosave cannot be written during close, Screph reports the failure and asks whether to close. Project Manager separates non-openable exports and damaged JSON under Problems, but its pre-open diagnostics are not a fresh full artifact-integrity scan. After loading, a more detailed domain load report and saved save diagnostics appear in InfoPanel.

Сохранение, Project Manager и autosave →Saving, Project Manager and autosave →

5. Границы5. Boundaries

• Ни один crash handler не гарантирует перехват любого аварийного завершения.No crash handler can guarantee capture of every process failure.
• Support helper и Screph Code/Pro Agent используют отдельные процессы. Automation Manager UI в обычном Selector flow создаётся внутри desktop-процесса, но запускаемый им сценарий — отдельный Python child. stderr/stdout и журналы child могут отличаться от main desktop log; сбой child не обязательно создаёт crash session главного окна.The support helper and Screph Code/Pro Agent use separate processes. In the normal Selector flow, the Automation Manager UI is created inside the desktop process, while the workflow it starts is a separate Python child. Child stderr/stdout and logs may differ from the main desktop log, and a child failure does not necessarily create a main-window crash session.
• Остановка прямого Automation Manager child не гарантирует завершение процессов, которые запустил сам сценарий. После аварии проверьте Task Manager, целевые приложения и неожиданные loopback listeners.Stopping the direct Automation Manager child does not guarantee termination of processes spawned by the workflow. After a failure, check Task Manager, target applications and unexpected loopback listeners.
• Bundle помогает диагностике, но не является backup проекта.A bundle aids diagnostics but is not a project backup.
• Restore autosave создаёт отдельный проект копированием всей autosave directory; проверьте source paths, artifacts и лишние соседние файлы перед продолжением.Restoring an autosave creates a separate project by copying the whole autosave directory; verify source paths, artifacts and unrelated sibling files before continuing.

Если отдельный компонент не запускается, сначала зафиксируйте его command/runtime readiness, PID или exit code и соответствующий log, а уже затем перезапускайте main desktop. Карта process boundaries приведена в архитектурной справке.If a separate component will not start, first record its command/runtime readiness, PID or exit code and matching log before restarting the main desktop. See the architecture guide for the process-boundary map.