Diagnostics and recovery

1. What is captured locally

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 — available native/thread diagnostics;
• runtime logs and additional files owned by that crash session.

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.

• 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.
• 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 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 bundle

1. Open the Crash Reports group on the Logging page.
2. 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. If needed, open the logs/crash-report folders and inspect the source files.
4. Export diagnostics bundle creates a local ZIP at a chosen location.

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. Manual submission

• 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.
• 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.
• 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.
• 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.
• 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.
• If the auth token, bundle or network is unavailable, the operation fails explicitly; local export remains available.

4. Project recovery

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.

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.

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.

Saving, Project Manager and autosave →

5. Boundaries

• No crash handler can guarantee capture of every process failure.
• 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.
• 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.
• A bundle aids diagnostics but is not a project backup.
• Restoring an autosave creates a separate project by copying the whole autosave directory; verify source paths, artifacts and unrelated sibling files before continuing.

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.