feat(cue): app.startup trigger, pipeline numbering fix, DB error surfacing

docs/maestro-cue-configuration.md

@@ -57,7 +57,7 @@ Each subscription is a trigger-prompt pairing. When the trigger fires, Cue sends
 | Field    | Type   | Description                                                            |
 | -------- | ------ | ---------------------------------------------------------------------- |
 | `name`   | string | Unique identifier. Used in logs, history, and as a reference in chains |
-| `event`  | string | One of the seven [event types](./maestro-cue-events)                   |
+| `event`  | string | One of the eight [event types](./maestro-cue-events)                   |
 | `prompt` | string | The prompt to send, either inline text or a path to a `.md` file       |
 
 ### Optional Fields

docs/maestro-cue-events.md

@@ -1,10 +1,46 @@
 ---
 title: Cue Event Types
-description: Detailed reference for all seven Maestro Cue event types with configuration, payloads, and examples.
+description: Detailed reference for all eight Maestro Cue event types with configuration, payloads, and examples.
 icon: calendar-check
 ---
 
-Cue supports seven event types. Each type watches for a different kind of activity and produces a payload that can be injected into prompts via [template variables](./maestro-cue-advanced#template-variables).
+Cue supports eight event types. Each type watches for a different kind of activity and produces a payload that can be injected into prompts via [template variables](./maestro-cue-advanced#template-variables).
+
+## app.startup
+
+Fires exactly once when the Maestro application launches. Ideal for workspace setup, dependency installation, health checks, or any initialization that should happen once per session.
+
+**Required fields:** None beyond the universal `name`, `event`, and `prompt`.
+
+**Behavior:**
+
+- Fires once per application launch
+- Does NOT re-fire when toggling Cue on/off in Settings
+- Does not re-fire on YAML hot-reload (deduplication by subscription name)
+- Resets on session removal (so re-adding the session fires again on next app launch)
+- Not affected by sleep/wake reconciliation
+- Works with `fan_out`, `filter`, `output_prompt`, and `prompt_file`
+
+**Example:**
+
+```yaml
+subscriptions:
+  - name: init-workspace
+    event: app.startup
+    prompt: |
+      Set up the development environment:
+      1. Run `npm install` if node_modules is missing
+      2. Check that required env vars are set
+      3. Report any issues found
+```
+
+**Payload fields:**
+
+| Field    | Type   | Description               |
+| -------- | ------ | ------------------------- |
+| `reason` | string | Always `"system_startup"` |
+
+---
 
 ## time.heartbeat
 

docs/maestro-cue-examples.md

@@ -6,6 +6,28 @@ icon: lightbulb
 
 Complete, copy-paste-ready `.maestro/cue.yaml` configurations for common workflows. Each example is self-contained — drop it into your project's `.maestro/` directory and adjust agent names to match your Left Bar.
 
+## Workspace Initialization
+
+Run setup tasks once when the Maestro application launches — install dependencies, verify environment, run health checks.
+
+**Agents needed:** `setup-agent`
+
+```yaml
+subscriptions:
+  - name: init-workspace
+    event: app.startup
+    prompt: |
+      Initialize the workspace:
+      1. Run `npm install` if node_modules is missing or outdated
+      2. Verify required environment variables are set
+      3. Run `npm run build` to ensure the project compiles
+      Report any issues found.
+```
+
+This fires exactly once per application launch. Toggling Cue off and back on does NOT re-fire it. Only an application restart triggers it again. Editing the YAML does not re-trigger it.
+
+---
+
 ## CI-Style Pipeline
 
 Lint, test, and deploy in sequence. Each step only runs if the previous one succeeded.

src/__tests__/main/cue/cue-engine.test.ts

@@ -133,7 +133,7 @@ describe('CueEngine', () => {
 			});
 			const deps = createMockDeps();
 			const engine = new CueEngine(deps);
-			engine.start();
+			expect(() => engine.start()).toThrow('DB corrupted');
 			expect(engine.isEnabled()).toBe(false);
 		});
 
@@ -143,7 +143,7 @@ describe('CueEngine', () => {
 			});
 			const deps = createMockDeps();
 			const engine = new CueEngine(deps);
-			engine.start();
+			expect(() => engine.start()).toThrow('DB corrupted');
 			expect(deps.onLog).toHaveBeenCalledWith(
 				'error',
 				expect.stringContaining('Failed to initialize Cue database')
@@ -156,7 +156,7 @@ describe('CueEngine', () => {
 			});
 			const deps = createMockDeps();
 			const engine = new CueEngine(deps);
-			engine.start();
+			expect(() => engine.start()).toThrow('DB corrupted');
 			expect(mockLoadCueConfig).not.toHaveBeenCalled();
 		});
 
@@ -166,7 +166,7 @@ describe('CueEngine', () => {
 			});
 			const deps = createMockDeps();
 			const engine = new CueEngine(deps);
-			engine.start();
+			expect(() => engine.start()).toThrow('DB corrupted');
 			// Engine is not enabled, so getStatus should return empty
 			expect(engine.getStatus()).toEqual([]);
 		});
@@ -181,7 +181,7 @@ describe('CueEngine', () => {
 			const deps = createMockDeps();
 			const engine = new CueEngine(deps);
 
-			engine.start();
+			expect(() => engine.start()).toThrow('DB corrupted');
 			expect(engine.isEnabled()).toBe(false);
 
 			engine.start();

src/__tests__/main/cue/cue-sleep-wake.test.ts

@@ -228,8 +228,8 @@ describe('CueEngine sleep/wake detection', () => {
 		const deps = createMockDeps();
 		const engine = new CueEngine(deps);
 
-		// Should not throw
-		expect(() => engine.start()).not.toThrow();
+		// Should throw so IPC callers can surface the error
+		expect(() => engine.start()).toThrow('DB init failed');
 
 		// Should log the error and not enable the engine
 		expect(deps.onLog).toHaveBeenCalledWith(