Merge pull request #130 from closedloop-ai/PLN-324

PLN-324: Add managed onboarding

Author: shafty023

AGENTS.md

@@ -41,6 +41,14 @@ Tests run with `tsx --test` (Node test runner) via `just desktop-test`.
 - Add or update tests with behavior changes, especially gateway auth, process spawning, and telemetry flows.
 - Before opening a PR, run: `just desktop-lint && just desktop-typecheck && just desktop-test`.
 
+## Breaking Changes
+Migration requirements apply only to contracts consumed by separate repositories or external clients that ship and upgrade independently of the desktop app:
+HTTP gateway routes, cloud relay messages, and persisted store schemas read across downgrade/rollback boundaries.
+
+- Breaking those external contracts requires legacy migration logic at the boundary and a ClosedLoop ticket to track removing the migration path later.
+- Internal contracts that ship as one Electron bundle do not need migration logic: main/renderer IPC bridge messages, internal module interfaces, and types consumed only inside `apps/desktop/`.
+- When reviewing a compatibility issue, first identify whether the caller is independently shipped. If both producer and consumer update atomically in the same desktop build, treat it as an internal refactor unless persisted data or an external client is involved.
+
 ## Commit & Pull Request Guidelines
 Commit format follows `.gitmessage` and recent history:
 

CLAUDE.md

@@ -17,11 +17,13 @@ Run `just` to see all available recipes. Key ones:
 
 ## Breaking Changes
 
-Any breaking change to APIs, contracts, or interfaces (HTTP gateway routes, cloud relay messages, IPC bridge, persisted store schemas, etc.) requires both of the following before merging:
+This rule applies ONLY to contracts consumed by separate repositories or external clients that ship and upgrade independently of the desktop app: HTTP gateway routes (consumed by the web app, CLI, or third-party tools), cloud relay messages (consumed by the cloud control plane), persisted store schemas on disk (read by older app versions during downgrade/rollback). Any breaking change to those contracts requires both of the following before merging:
 
-1. **Legacy migration logic** so existing users are not broken on upgrade. Detect the old shape and translate it to the new shape at the boundary; do not assume users have already migrated.
+1. **Legacy migration logic** so existing external consumers are not broken on upgrade. Detect the old shape and translate it to the new shape at the boundary; do not assume external consumers have already migrated.
 2. **A ClosedLoop ticket** created via the ClosedLoop MCP (`mcp__closedloop__create-feature`) to track removing the legacy migration code at a later date. Reference the ticket ID in a comment next to the migration logic so it can be found and deleted when the ticket is worked.
 
+This rule does NOT apply to internal contracts that ship as a single unit with the app: IPC bridge messages between main and renderer, internal module interfaces, type definitions consumed only within `apps/desktop/`. Both sides of an IPC channel are bundled into the same Electron build, so a breaking change updates the producer and consumer atomically — no migration is needed.
+
 ## Gateway Operations (`apps/desktop/src/server/operations/`)
 
 - **Shared helpers live in dedicated modules.** Before adding a local helper function to an operation file, check if it already exists in a shared module (e.g., `response-utils.ts` for `json()`, `symphony-utils.ts` for `expandHome()`). If a helper is used by more than one operation, extract it into a shared module.

apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "desktop",
-  "version": "0.13.20",
+  "version": "0.13.21",
   "description": "ClosedLoop Desktop",
   "author": "ClosedLoop AI <support@closedloop.ai>",
   "private": true,

apps/desktop/src/main/app-lifecycle.ts

@@ -0,0 +1,21 @@
+/**
+ * Handles Electron lifecycle callbacks that dispatch async Desktop work.
+ *
+ * Electron does not await event listener promises. Keeping the catch inside the
+ * lifecycle helper prevents expected activation-time failures from becoming
+ * process-level unhandled rejections.
+ */
+export async function handleActivateEvent(deps: {
+  handleActivate: () => Promise<void>;
+  log: (message: string) => void;
+}): Promise<void> {
+  try {
+    await deps.handleActivate();
+  } catch (error) {
+    const message =
+      error instanceof Error
+        ? `${error.message}${error.stack ? `\n${error.stack}` : ""}`
+        : String(error);
+    deps.log(`activate handling failed: ${message}`);
+  }
+}