Crash Recovery

When AI agents write PHP code to the sandbox, that code runs on every subsequent WordPress request. If the code contains a fatal error, it could take down the entire site. Novamira’s crash recovery system detects this and automatically recovers.

How crash detection works

The sandbox loader uses a marker file to track whether sandbox files are loading successfully:

  1. Before loading: The loader creates a .loading marker file in the sandbox directory.
  2. Loading: Each sandbox PHP file is loaded via require_once.
  3. After loading: If all files loaded without a fatal error, the .loading marker is deleted.

If a fatal error occurs during step 2, PHP execution stops immediately. The .loading marker is never deleted because step 3 never runs.

Automatic recovery

On the next request, the loader checks for the .loading marker:

  1. If .loading exists (meaning the previous request crashed), it renames it to .crashed.
  2. The presence of .crashed triggers safe mode: all sandbox files are skipped.
  3. WordPress loads normally. The MCP server is available. The admin dashboard works.

This means: even if an AI agent writes PHP code that causes a fatal error, the site automatically recovers on the next request. The MCP tools remain available, so the AI agent can read, fix, or delete the broken file.

Safe mode

When safe mode is active:

  • No sandbox files are loaded. All custom functionality from the sandbox is suspended.
  • A prominent admin notice appears: “Novamira Sandbox: Safe mode is active. A sandbox plugin caused a fatal error.”
  • All Novamira abilities (Execute PHP, Read File, Write File, etc.) continue to work normally. The AI agent can still operate.

Exiting safe mode

There are three ways to exit safe mode:

1. From the WordPress admin

Go to Novamira > Sandbox and click Exit Safe Mode. This deletes the .crashed file and sandbox files will load on the next request.

2. Via an AI agent

The AI agent can delete the crash marker using the Delete File ability:

// Delete the crash marker
path: "wp-content/novamira-sandbox/.crashed"

3. Manual safe mode via URL

You can force safe mode on any request by adding ?novamira_safe_mode=1 to the URL. This is useful if the site is crashing and you need to access the admin without waiting for automatic recovery.

When crash recovery is active

Crash detection only runs when AI abilities are enabled. When abilities are disabled, sandbox files are loaded without the .loading/.crashed marker overhead. This means if you disable AI abilities and a sandbox file has a fatal error, the normal WordPress fatal error handler takes over instead.

Limitations

  • Crash recovery detects fatal errors, but it does not identify which sandbox file caused the crash. You need to review the sandbox files manually or use the AI agent to inspect them.
  • It does not roll back changes. The broken file stays on disk. You need to fix it, disable it, or delete it.
  • Execute PHP errors (from eval()) do not trigger crash recovery because they do not involve the sandbox loader. Execute PHP has its own error handling that catches exceptions and returns them in the response.