feat(autorun): schedule an Auto Run to start at a specific date/time

docs/autorun-playbooks.md

@@ -77,6 +77,35 @@ Auto Run supports running multiple documents in sequence:
 5. Enable **Loop Mode** to cycle back to the first document after completing the last
 6. Click **Go** to start running documents
 
+## Scheduling a Run
+
+By default an Auto Run starts as soon as you press **Go**. The **Start** control
+in the Auto Run window switches that to a specific date and time:
+
+| Option            | Description                                                         |
+| ----------------- | ------------------------------------------------------------------- |
+| **Now**           | The default. Press Go and the run starts immediately.               |
+| **At a set time** | Pick a date and time; the run fires once, then the schedule is gone |
+
+When a time is set the **Go** button becomes **Schedule**. The most common use
+is starting a run after your provider's token limit resets, so you wake up to
+finished work rather than a run that stalled at 2am.
+
+A few things worth knowing:
+
+- The time is your local time, and the schedule survives quitting and reopening
+  Maestro.
+- The documents are pinned when you schedule, not when the run fires. Repointing
+  the agent's Auto Run folder afterwards will not swap out what runs.
+- You can schedule while the agent is busy. Readiness is checked when the run
+  actually fires, not when you schedule it.
+- Scheduling is one-shot. For a run that repeats, use a recurring
+  [Maestro Cue](./maestro-cue) task instead.
+
+Scheduled runs are stored as Maestro Cue tasks, so **Start** requires the
+Maestro Cue Encore Feature. Pending runs appear under **Scheduled Tasks** in the
+Cue window, which is also where you cancel one.
+
 ## Model Override
 
 The run configuration modal has **Model** and **Effort** pickers, both defaulting to **Use agent default**. Picking a value runs _this Auto Run only_ on that model: every task spawn in the run uses it, the agent's own configured model is left alone (its interactive tabs keep using the default), and the override is forgotten when the run ends. The pickers reset to the default each time the modal opens, and are hidden for providers that expose no model or effort options. Worktree runs honor the override too, without changing the child worktree agent's own configured model.

docs/maestro-cue-configuration.md

@@ -59,9 +59,10 @@ subscriptions:
     poll_minutes: number # Optional for github.*, task.pending
 
     # Action-specific fields
-    action: string # Optional. One of "prompt" (default), "notify", "command"
+    action: string # Optional. One of "prompt" (default), "notify", "command", "autorun"
     notify: object # Optional. Notify payload when action is "notify" (message, sticky, etc.)
     command: object # Optional. Command spec when action is "command" (mode, shell, cli, etc.)
+    auto_run: object # Optional. Auto Run payload when action is "autorun" (documents, prompt, etc.)
 
 # Global settings (all optional - sensible defaults applied)
 settings:
@@ -149,9 +150,10 @@ Either `prompt` or `prompt_file` must be provided. If both are present, `prompt_
 | `output_prompt`            | string            | -        | Follow-up prompt sent after the main run completes successfully                                                                                                                                                                           |
 | `output_prompt_file`       | string            | -        | Path to a `.md` file for the output prompt (alternative to inline)                                                                                                                                                                        |
 | `label`                    | string            | -        | Human-readable label displayed in the Cue dashboard and pipeline editor                                                                                                                                                                   |
-| `action`                   | string            | `prompt` | Action to dispatch when the event fires: `prompt` (run the agent), `notify` (surface a toast through the owning agent - clicking it jumps there), or `command` (shell/cli call)                                                           |
+| `action`                   | string            | `prompt` | Action to dispatch when the event fires: `prompt` (run the agent), `notify` (surface a toast through the owning agent - clicking it jumps there), `command` (shell/cli call), or `autorun` (launch an Auto Run in the owning agent)       |
 | `notify`                   | object            | -        | Notify payload when `action: notify`. Fields: `message` (string, required), `sticky` (boolean), `level` (`info` \| `success` \| `warning` \| `error`). The toast renders through the owning agent; clicking it jumps there                |
 | `command`                  | object            | -        | Command spec when `action: command`. Fields include `mode` (`shell` \| `cli`), `shell`/`cli` invocation, and related options (see [Command Nodes](./maestro-cue-advanced))                                                                |
+| `auto_run`                 | object            | -        | Auto Run payload when `action: autorun`. Fields: `documents` (list of absolute `.md` paths, required), `reset_on_completion` (list of booleans, one per document), `prompt`, `loop_enabled`, `max_loops`, `model`, `effort`               |
 
 ### Prompt Field
 

src/__tests__/main/cue/config/cue-config-validator.test.ts

@@ -242,7 +242,78 @@ describe('validateSubscription - action: notify', () => {
 	it('rejects unknown action values', () => {
 		const found = errs({ ...base, action: 'explode' });
 		expect(
-			found.some((e) => /"action" must be "prompt", "command", or "notify" when provided/.test(e))
+			found.some((e) =>
+				/"action" must be "prompt", "command", "notify", or "autorun" when provided/.test(e)
+			)
+		).toBe(true);
+	});
+});
+
+describe('validateSubscription - action: autorun', () => {
+	const base = {
+		name: 'autorun-1',
+		event: 'time.once',
+		action: 'autorun' as const,
+		agent_id: 'agent-xyz',
+		fire_at: '2026-05-22T14:30:00-05:00',
+		auto_run: { documents: ['/proj/Auto Run Docs/ship.md'] },
+	};
+
+	it('accepts action: autorun without a prompt field', () => {
+		// An autorun subscription's work is its document list; `prompt` is
+		// deliberately absent.
+		expect(errs(base)).toEqual([]);
+	});
+
+	it('requires auto_run', () => {
+		const { auto_run: _omitted, ...withoutAutoRun } = base;
+		expect(
+			errs(withoutAutoRun).some((e) =>
+				/"auto_run" is required and must be an object when action is "autorun"/.test(e)
+			)
+		).toBe(true);
+	});
+
+	it('rejects an empty document list', () => {
+		expect(
+			errs({ ...base, auto_run: { documents: [] } }).some((e) =>
+				/"auto_run\.documents" is required and must be a non-empty array/.test(e)
+			)
+		).toBe(true);
+	});
+
+	it('rejects a reset_on_completion array that does not align with documents', () => {
+		// Misaligned flags would reset the wrong document.
+		expect(
+			errs({
+				...base,
+				auto_run: { documents: ['/a.md', '/b.md'], reset_on_completion: [true] },
+			}).some((e) => /must have one entry per "auto_run\.documents" entry/.test(e))
+		).toBe(true);
+	});
+
+	it('requires agent_id', () => {
+		const { agent_id: _omitted, ...withoutAgent } = base;
+		expect(
+			errs(withoutAgent).some((e) =>
+				/"agent_id" is required and must be a non-empty string when action is "autorun"/.test(e)
+			)
+		).toBe(true);
+	});
+
+	it('rejects fan_out - one Auto Run belongs to one agent', () => {
+		expect(
+			errs({ ...base, fan_out: ['other-agent'] }).some((e) =>
+				/"fan_out" is not supported when action is "autorun"/.test(e)
+			)
+		).toBe(true);
+	});
+
+	it('rejects a non-positive max_loops', () => {
+		expect(
+			errs({ ...base, auto_run: { documents: ['/a.md'], max_loops: 0 } }).some((e) =>
+				/"auto_run\.max_loops" must be a positive integer when provided/.test(e)
+			)
 		).toBe(true);
 	});
 });

src/__tests__/main/cue/cue-autorun-executor.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Tests for cue-autorun-executor.
+ *
+ * The status this executor returns is load-bearing rather than cosmetic: a
+ * `time.once` subscription is consumed on any terminal status, so `completed`
+ * vs `failed` decides whether a scheduled run that did NOT start survives on
+ * disk for the user to find. These tests pin that behavior, plus the fact that
+ * the documents launched are the ones captured at schedule time.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { BrowserWindow } from 'electron';
+import type { CueEvent, CueSubscription } from '../../../main/cue/cue-types';
+import type { SessionInfo } from '../../../shared/types';
+
+const launchCueAutoRunMock = vi.fn();
+vi.mock('../../../main/cue/cue-autorun-bridge', () => ({
+	launchCueAutoRun: (...args: unknown[]) => launchCueAutoRunMock(...args),
+}));
+
+import { executeCueAutoRun } from '../../../main/cue/cue-autorun-executor';
+
+function createSession(): SessionInfo {
+	return {
+		id: 'session-1',
+		name: 'Nightly',
+		toolType: 'claude-code',
+		cwd: '/tmp/project',
+		projectRoot: '/tmp/project',
+	};
+}
+
+function createSubscription(overrides: Partial<CueSubscription> = {}): CueSubscription {
+	return {
+		name: 'run-at-6am',
+		event: 'time.once',
+		enabled: true,
+		prompt: '',
+		action: 'autorun',
+		agent_id: 'session-1',
+		auto_run: { documents: ['/proj/Auto Run Docs/ship.md'] },
+		...overrides,
+	} as CueSubscription;
+}
+
+const event = { type: 'time.once', payload: {} } as unknown as CueEvent;
+const mainWindow = {} as BrowserWindow;
+
+describe('executeCueAutoRun', () => {
+	beforeEach(() => {
+		launchCueAutoRunMock.mockReset();
+	});
+
+	it('launches the documents captured on the subscription', async () => {
+		launchCueAutoRunMock.mockResolvedValue({ success: true });
+
+		const result = await executeCueAutoRun({
+			runId: 'run-1',
+			session: createSession(),
+			subscription: createSubscription(),
+			event,
+			autoRun: {
+				documents: ['/proj/Auto Run Docs/a.md', '/proj/Auto Run Docs/b.md'],
+				reset_on_completion: [false, true],
+				prompt: 'Work the tasks',
+				loop_enabled: true,
+				max_loops: 2,
+			},
+			mainWindow,
+			onLog: vi.fn(),
+		});
+
+		expect(launchCueAutoRunMock).toHaveBeenCalledWith(
+			mainWindow,
+			expect.objectContaining({
+				sessionId: 'session-1',
+				documents: [
+					{ filename: '/proj/Auto Run Docs/a.md', resetOnCompletion: false },
+					{ filename: '/proj/Auto Run Docs/b.md', resetOnCompletion: true },
+				],
+				prompt: 'Work the tasks',
+				loopEnabled: true,
+				maxLoops: 2,
+			})
+		);
+		expect(result.status).toBe('completed');
+		expect(result.exitCode).toBe(0);
+	});
+
+	it('defaults resetOnCompletion to false when no flags were captured', async () => {
+		launchCueAutoRunMock.mockResolvedValue({ success: true });
+
+		await executeCueAutoRun({
+			runId: 'run-1',
+			session: createSession(),
+			subscription: createSubscription(),
+			event,
+			autoRun: { documents: ['/proj/a.md'] },
+			mainWindow,
+			onLog: vi.fn(),
+		});
+
+		expect(launchCueAutoRunMock.mock.calls[0][1].documents).toEqual([
+			{ filename: '/proj/a.md', resetOnCompletion: false },
+		]);
+	});
+
+	it('reports `failed` when the renderer does not accept the launch', async () => {
+		// This is the case the status semantics exist for: paired with
+		// `self_destruct_on_failure: false`, a `failed` status keeps the
+		// subscription on disk instead of silently consuming the user's
+		// scheduled run.
+		launchCueAutoRunMock.mockResolvedValue({
+			success: false,
+			error: 'renderer webContents not available',
+		});
+
+		const result = await executeCueAutoRun({
+			runId: 'run-1',
+			session: createSession(),
+			subscription: createSubscription(),
+			event,
+			autoRun: { documents: ['/proj/a.md'] },
+			mainWindow,
+			onLog: vi.fn(),
+		});
+
+		expect(result.status).toBe('failed');
+		expect(result.exitCode).toBe(1);
+		expect(result.stderr).toContain('renderer webContents not available');
+	});
+
+	it('logs an explanation when the launch fails so the failure is triageable', async () => {
+		launchCueAutoRunMock.mockResolvedValue({ success: false, error: 'boom' });
+		const onLog = vi.fn();
+
+		await executeCueAutoRun({
+			runId: 'run-1',
+			session: createSession(),
+			subscription: createSubscription(),
+			event,
+			autoRun: { documents: ['/proj/a.md'] },
+			mainWindow,
+			onLog,
+		});
+
+		const errorLogs = onLog.mock.calls.filter(([level]) => level === 'error');
+		expect(errorLogs).toHaveLength(1);
+		expect(errorLogs[0][1]).toContain('boom');
+	});
+});

src/__tests__/main/cue/cue-dispatch-service.test.ts

@@ -87,11 +87,43 @@ describe('createCueDispatchService', () => {
 				undefined,
 				undefined, // chainRootId
 				undefined, // parentEventId
-				undefined // notify
+				undefined, // notify
+				undefined // autoRun
 			);
 		});
 	});
 
+	describe('action: autorun', () => {
+		it('threads the captured auto_run payload to executeRun', () => {
+			const { deps, executeRun } = makeDeps();
+			const svc = createCueDispatchService(deps);
+			const autoRun = { documents: ['/proj/a.md'] };
+			const sub = makeSub({ prompt: '', action: 'autorun', auto_run: autoRun });
+			const event = createCueEvent('time.once', 'my-sub');
+
+			expect(svc.dispatchSubscription('owner', sub, event, 'src')).toBe(1);
+			// autoRun rides in the trailing positional slot, after notify.
+			const call = executeRun.mock.calls[0];
+			expect(call[13]).toEqual(autoRun);
+			// The prompt slot is back-filled so the "no prompt -> skip" gate
+			// cannot silently drop a scheduled run.
+			expect(call[1]).toBe('/proj/a.md');
+		});
+
+		it('refuses to dispatch an autorun subscription with no documents', () => {
+			const { deps, executeRun, logs } = makeDeps();
+			const svc = createCueDispatchService(deps);
+			const sub = makeSub({ prompt: '', action: 'autorun', auto_run: { documents: [] } });
+			const event = createCueEvent('time.once', 'my-sub');
+
+			expect(svc.dispatchSubscription('owner', sub, event, 'src')).toBe(0);
+			expect(executeRun).not.toHaveBeenCalled();
+			// A scheduled run fires unattended, so a silent no-op is
+			// indistinguishable from never having fired at all.
+			expect(logs.some(([level, msg]) => level === 'error' && /no documents/.test(msg))).toBe(true);
+		});
+	});
+
 	describe('fan-out', () => {
 		it('returns 2 when both targets have prompts', () => {
 			const { deps, executeRun } = makeDeps();