Add Safe Mode and recovery flows for startup, plugin, layout, metadata, and search failures #78

New issue

Closed

opened 2026-05-22 11:30:30 +00:00 by steve · 0 comments

steve commented

2026-05-22 11:30:30 +00:00

Owner

Implement a user-facing Safe Mode and recovery flow so users can recover from
startup failures without manually editing internal app state.

Problem

Startup currently depends on vault bootstrap, settings load, plugin activation,
layout restore, metadata hydration, search indexing, notebook runtime setup,
and desktop-specific services. As complexity grows, users need a practical way
to recover from a bad plugin, corrupt layout, broken metadata state, or search
startup failure.

Goal

Add Safe Mode and recovery UX that lets Lapis boot with risky or generated
subsystems disabled, while keeping canonical vault data intact.

Sequencing

This is step 3 of the recommended six-issue sequence.
Start this issue after 77 and 82 so recovery work is anchored to the release definition and cleaned backlog guidance.
Complete this issue before 80, 79, and 81.
Later issues should reuse the Safe Mode and recovery semantics defined here instead of inventing parallel fallback behavior.

Scope

Add at least one practical Safe Mode entry point, such as repeated startup
failure fallback, restart action, session flag, or Electron flag.
Support disabling or resetting community plugins, non-core plugins, layout
restore, metadata generated state, search generated state, notebook
execution, and desktop-side sidecars where applicable.
Show a visible in-app indicator when Safe Mode is active.
Record and surface the last startup failure reason where practical.
Let users identify and disable a failing plugin from the recovery flow.
Add documentation and tests for at least one plugin-failure and one
layout-restore failure path.

Non-goals

Full plugin sandboxing.
Automatic repair for arbitrary corrupted markdown.
Guaranteeing compatibility with every Obsidian plugin.
Cloud backup or sync.

Acceptance Criteria

A user can start Lapis with community plugins disabled.
A user can start Lapis without restoring the previous layout.
A user can rebuild metadata and search generated state without deleting notes.
A user can disable notebook execution for recovery.
Safe Mode state is visible in the UI.
Safe Mode does not permanently disable features unless the user explicitly
chooses that outcome.
The app records or displays the last startup failure reason where possible.
A failing plugin can be identified and disabled from the recovery flow.
Tests cover at least one plugin failure and one layout restoration failure.
Documentation explains what Safe Mode does and does not do.

Implementation Notes

Keep canonical vault files separate from generated app state.
Do not delete user markdown files as part of recovery.
Avoid making this Electron-only; browser and PWA users need recovery too.
Prefer wiring into existing startup diagnostics over building a disconnected
recovery path.
Prefer explicit recovery actions over silent resets.

Suggested Files or Specs To Inspect

spec/src/SUMMARY.md
spec/src/20-packages/workspace/
spec/src/30-cross-package-contracts/plugin-system/
spec/src/30-cross-package-contracts/storage-metadata-search.md
spec/src/40-testing/current-state.md

Validation Commands

pnpm check
pnpm test:smoke

Follow-up Tasks

Link this issue from the release-readiness milestone.
Split platform-specific follow-ups only if a single implementation issue
becomes too broad.
After this lands, move directly to 80.

Implementation Summary

Added session-scoped Safe Mode startup recovery with community-plugin, layout-restore, notebook-execution, metadata, and search recovery actions; exposed restart commands and ready-state banner recovery UI; gated notebook execution through Safe Mode context keys; added focused workspace Safe Mode e2e coverage plus notebook unit coverage; synced workspace, API, and notebook spec pages.

Implement a user-facing Safe Mode and recovery flow so users can recover from startup failures without manually editing internal app state. ## Problem Startup currently depends on vault bootstrap, settings load, plugin activation, layout restore, metadata hydration, search indexing, notebook runtime setup, and desktop-specific services. As complexity grows, users need a practical way to recover from a bad plugin, corrupt layout, broken metadata state, or search startup failure. ## Goal Add Safe Mode and recovery UX that lets Lapis boot with risky or generated subsystems disabled, while keeping canonical vault data intact. ## Sequencing - This is step 3 of the recommended six-issue sequence. - Start this issue after [77](77-define-a-complete-daily-use-app-release-milestone-and-acceptance-checklist.md) and [82](82-clean-up-backlog-milestones-and-agent-workflow-guardrails.md) so recovery work is anchored to the release definition and cleaned backlog guidance. - Complete this issue before [80](80-harden-data-export-import-backup-and-generated-state-rebuild-flows.md), [79](79-polish-notebook-v0-into-a-reliable-understandable-feature.md), and [81](81-add-journey-based-e2e-and-smoke-tests-for-the-complete-daily-use-path.md). - Later issues should reuse the Safe Mode and recovery semantics defined here instead of inventing parallel fallback behavior. ## Scope - Add at least one practical Safe Mode entry point, such as repeated startup failure fallback, restart action, session flag, or Electron flag. - Support disabling or resetting community plugins, non-core plugins, layout restore, metadata generated state, search generated state, notebook execution, and desktop-side sidecars where applicable. - Show a visible in-app indicator when Safe Mode is active. - Record and surface the last startup failure reason where practical. - Let users identify and disable a failing plugin from the recovery flow. - Add documentation and tests for at least one plugin-failure and one layout-restore failure path. ## Non-goals - Full plugin sandboxing. - Automatic repair for arbitrary corrupted markdown. - Guaranteeing compatibility with every Obsidian plugin. - Cloud backup or sync. ## Acceptance Criteria - A user can start Lapis with community plugins disabled. - A user can start Lapis without restoring the previous layout. - A user can rebuild metadata and search generated state without deleting notes. - A user can disable notebook execution for recovery. - Safe Mode state is visible in the UI. - Safe Mode does not permanently disable features unless the user explicitly chooses that outcome. - The app records or displays the last startup failure reason where possible. - A failing plugin can be identified and disabled from the recovery flow. - Tests cover at least one plugin failure and one layout restoration failure. - Documentation explains what Safe Mode does and does not do. ## Implementation Notes - Keep canonical vault files separate from generated app state. - Do not delete user markdown files as part of recovery. - Avoid making this Electron-only; browser and PWA users need recovery too. - Prefer wiring into existing startup diagnostics over building a disconnected recovery path. - Prefer explicit recovery actions over silent resets. ## Suggested Files or Specs To Inspect - `spec/src/SUMMARY.md` - `spec/src/20-packages/workspace/` - `spec/src/30-cross-package-contracts/plugin-system/` - `spec/src/30-cross-package-contracts/storage-metadata-search.md` - `spec/src/40-testing/current-state.md` ## Validation Commands - `pnpm check` - `pnpm test:smoke` ## Follow-up Tasks - Link this issue from the release-readiness milestone. - Split platform-specific follow-ups only if a single implementation issue becomes too broad. - After this lands, move directly to [80](80-harden-data-export-import-backup-and-generated-state-rebuild-flows.md). ## Implementation Summary Added session-scoped Safe Mode startup recovery with community-plugin, layout-restore, notebook-execution, metadata, and search recovery actions; exposed restart commands and ready-state banner recovery UI; gated notebook execution through Safe Mode context keys; added focused workspace Safe Mode e2e coverage plus notebook unit coverage; synced workspace, API, and notebook spec pages.

steve added the

labels

2026-05-22 11:30:30 +00:00