Initial ForgeLM import

.planning/phases/02-lifecycle-command-safety/02-01-SUMMARY.md

@@ -0,0 +1,106 @@
+---
+phase: 02-lifecycle-command-safety
+plan: 01
+subsystem: runtime
+tags: [tauri, rust, lifecycle, runtime, desktop]
+requires:
+  - phase: 01-draft-state-ownership
+    provides: runtime draft/live separation that lifecycle metadata now extends without clobbering edits
+provides:
+  - explicit runtime snapshot lifecycle command metadata
+  - backend guards for conflicting local runtime start and stop requests
+  - restart-required save guidance aligned to backend-owned runtime fields
+affects: [phase-02-02, phase-02-03, runtime-workspace]
+tech-stack:
+  added: []
+  patterns: [snapshot lifecycle transport, centralized runtime command guards]
+key-files:
+  created: []
+  modified:
+    - tauri-app/src-tauri/src/runtime/types.rs
+    - tauri-app/src-tauri/src/runtime/state.rs
+    - tauri-app/src-tauri/src/runtime/mod.rs
+key-decisions:
+  - "Expose active and last lifecycle command data on RuntimeSnapshot so frontend polling can render trustworthy lifecycle feedback without inferring from status alone."
+  - "Centralize duplicate start/stop blocking in runtime state helpers so save, start, and stop flows share the same command-result contract."
+  - "Keep restart-required save enforcement limited to connection_mode, model_path, addr, gpu_layers, and ctx_size to stay aligned with the existing backend runtime boundary."
+patterns-established:
+  - "RuntimeSnapshot includes active_command plus last_command_result for stable in-flight and terminal lifecycle messaging."
+  - "Lifecycle commands update terminal outcomes through helper functions instead of ad-hoc last_error-only handling."
+requirements-completed: [CTRL-01, CTRL-03]
+duration: 6min
+completed: 2026-03-29
+---
+
+# Phase 2 Plan 01: Lifecycle Command Safety Summary
+
+**Runtime snapshot lifecycle metadata and guarded local start/stop/save outcomes at the Tauri runtime boundary**
+
+## Performance
+
+- **Duration:** 6 min
+- **Started:** 2026-03-29T03:45:48Z
+- **Completed:** 2026-03-29T03:51:43Z
+- **Tasks:** 2
+- **Files modified:** 3
+
+## Accomplishments
+- Added serialized lifecycle command metadata to `RuntimeSnapshot` so backend snapshots now report both the active command and the last completed command result.
+- Centralized lifecycle result helpers and guard rules in runtime state so duplicate start/stop requests return stable blocked messages instead of silent no-ops.
+- Routed restart-required saves and lifecycle success/failure paths through one command-result contract while preserving the existing backend restart-impact field list.
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Add explicit lifecycle command metadata to the runtime snapshot** - `217e265` (test)
+2. **Task 1: Add explicit lifecycle command metadata to the runtime snapshot** - `cf73eb2` (feat)
+3. **Task 2: Guard conflicting lifecycle commands and preserve restart-impacting save rules** - `581b81b` (test)
+4. **Task 2: Guard conflicting lifecycle commands and preserve restart-impacting save rules** - `67651bf` (feat)
+
+## Files Created/Modified
+- `tauri-app/src-tauri/src/runtime/types.rs` - defines lifecycle command and result payloads on runtime snapshots.
+- `tauri-app/src-tauri/src/runtime/state.rs` - stores lifecycle metadata, shared guard helpers, and regression tests for blocked command behavior.
+- `tauri-app/src-tauri/src/runtime/mod.rs` - applies guard helpers to save/start/stop commands and records consistent lifecycle outcomes.
+
+## Decisions Made
+- Used snapshot-level lifecycle transport instead of separate command-specific responses so existing polling consumers can adopt the new contract incrementally.
+- Kept blocked lifecycle feedback in `last_command_result` while reserving `last_error` for actual runtime failures such as restart-required, spawn, health, and stop failures.
+- Preserved the restart-required field list exactly as planned and covered non-restart fields with regression tests.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Cleared latched active commands when config persistence fails**
+- **Found during:** Task 2 (Guard conflicting lifecycle commands and preserve restart-impacting save rules)
+- **Issue:** Beginning a save or save-and-start command before persisting config could leave `active_command` stuck if `save_runtime_config` returned an error.
+- **Fix:** Added failure handling that records a failed lifecycle result, stores `save_failed`, and exits without leaving the runtime in an in-flight command state.
+- **Files modified:** `tauri-app/src-tauri/src/runtime/mod.rs`
+- **Verification:** `cargo test --manifest-path "tauri-app/src-tauri/Cargo.toml" runtime::` and `cargo check --manifest-path "tauri-app/src-tauri/Cargo.toml"`
+- **Committed in:** `67651bf` (part of task commit)
+
+---
+
+**Total deviations:** 1 auto-fixed (1 bug)
+**Impact on plan:** The auto-fix kept the new lifecycle contract trustworthy under save failures without expanding scope beyond the planned backend boundary.
+
+## Issues Encountered
+- The plan's verification command used `cargo test -p tauri-app runtime::`, but the Tauri crate is named `forgelm-chat`; verification succeeded via `cargo test --manifest-path "tauri-app/src-tauri/Cargo.toml" runtime::`.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Frontend lifecycle manager work can now read `active_command` and `last_command_result` directly from runtime snapshots.
+- Restart/apply UI work can rely on the backend restart-required contract staying limited to `connection_mode`, `model_path`, `addr`, `gpu_layers`, and `ctx_size`.
+
+## Self-Check: PASSED
+
+- Summary file exists at `.planning/phases/02-lifecycle-command-safety/02-01-SUMMARY.md`.
+- Verified commit hashes `217e265`, `cf73eb2`, `581b81b`, and `67651bf` are present in git history.
+
+---
+*Phase: 02-lifecycle-command-safety*
+*Completed: 2026-03-29*