docs: reflect Startup-shortcut worker autostart

Replace Windows-service/scheduled-task deployment docs with the Startup-folder
shortcut mechanism and the App's connection-failure prompt.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs/open.md

@@ -161,11 +161,13 @@ Voraussetzung: funktionierendes Gitea-Release unter `git.kuns.dev/releases/Claud
 
 ## 4. Service-Deployment
 
-### 4.1 Worker-Autostart als Per-User-Task ✅ (ersetzt Windows-Service)
-- Der Worker läuft **nicht mehr als Windows-Service** (LocalSystem konnte die Claude-CLI-Auth des Users nicht sehen). Stattdessen: per-user **Logon-Scheduled-Task** „ClaudeDoWorker" (`schtasks /Create /XML`), läuft als angemeldeter User, versteckt, mit Restart-on-Failure.
-- Worker ist `WinExe` (kein Konsolenfenster) + Serilog-File-Sink (`~/.todo-app/logs/worker-*.log`) + Single-Instance-Mutex.
-- Installer migriert beim Update den alten Service automatisch weg (`sc stop`/`delete`) und registriert die Task; Uninstall entfernt Task + Worker-Prozess. App startet/neustartet den Worker als Prozess und sorgt beim Start dafür, dass er läuft.
-- Implementiert 2026-05-29, getestet (Build + Unit-Tests grün), **manuelle E2E-Verifikation am Gerät ausstehend** (Update von 1.0.2-alpha → Task, Logoff/Logon-Autostart, Uninstall).
+### 4.1 Worker-Autostart via Startup-Shortcut ✅ (ersetzt Scheduled Task + Windows-Service)
+- Der Worker läuft als `WinExe` (kein Konsolenfenster) + Serilog-File-Sink (`~/.todo-app/logs/worker-*.log`) + Single-Instance-Mutex.
+- Autostart über eine **Startup-Ordner-Verknüpfung** `ClaudeDo Worker.lnk` (`%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\`), die der Installer via `AutostartShortcut`/`ShortcutFactory` COM-Helper anlegt. Kein Scheduled Task, kein Windows-Service.
+- `StartWorkerStep` startet den Worker per `Process.Start`; `StopWorkerStep` beendet ihn per prozessbasiertem Kill.
+- Die App (`IslandsShellViewModel`) startet den Worker nicht selbst. Bei offline-Worker ~12s nach App-Start: einmaliges `WorkerConnectionModal` (Start Worker / Rerun Installer / Dismiss); Connection-Status-Pill in der Fußzeile ist ein Button zum erneuten Öffnen des Modals.
+- `UninstallRunner` löscht die Startup-`.lnk`; migriert ältere Installs durch best-effort-Löschen des Legacy-Scheduled-Tasks „ClaudeDoWorker" und des Legacy-Windows-Service.
+- **Manuelle E2E-Verifikation am Gerät ausstehend** (Logoff/Logon-Autostart, Update-Pfad, Uninstall).
 
 ### 4.2 Pfad-Auflösung absolut ✅
 - `WorkerConfig.Load` expandiert `~`/`%USERPROFILE%` für alle Pfad-Felder.

docs/plan.md

@@ -231,36 +231,21 @@ Beispiel: `feat(lager-app): add barcode scan retry logic`
 
 DB-Zugriff via Microsoft.Data.Sqlite + Repository-Layer (`TaskRepository`, `ListRepository`). Git-Operationen (UI + Worker) über gemeinsamen `GitService` in `ClaudeDo.Data`. MVVM via CommunityToolkit.Mvvm.
 
-## Worker als Windows-Service (Ziel-Deployment)
+## Worker-Deployment (Autostart via Startup-Shortcut)
 
-Initial läuft der Worker als Console-Prozess (lokales Dev-Setup). Im Endzustand soll er als **Windows-Service** automatisch starten.
+Der Worker läuft als **WinExe** (kein Konsolenfenster) — kein Windows-Service, kein Scheduled Task.
 
-**Code-seitig:**
-- Paket `Microsoft.Extensions.Hosting.WindowsServices` referenzieren.
-- In `Program.cs`: `builder.Host.UseWindowsService(o => o.ServiceName = "ClaudeDoWorker")`.
-- Logging zusätzlich über `EventLog` (`builder.Logging.AddEventLog(...)`), damit Service-Fehler im Windows Event Viewer landen.
-- Alle Pfade in `worker.config.json` **absolut** auflösen (`%USERPROFILE%` / `~` expandieren) — der Service-Working-Directory ist standardmäßig `C:\Windows\System32`.
-- `StaleTaskRecovery` (siehe oben) sorgt nach Service-Restart automatisch für das Aufräumen hängender `running`-Tasks.
-- Restart-Verhalten via `sc.exe failure`-Konfig oder beim Install.
+**Autostart:** Der Installer legt eine Verknüpfung `ClaudeDo Worker.lnk` im Startup-Ordner des Users an (`%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\`). Dafür nutzt `ClaudeDo.Installer` den Helper `AutostartShortcut` (mit extrahiertem `ShortcutFactory` COM-Helper). Beim Windows-Logon startet Windows die Verknüpfung automatisch — ohne Elevated-Rechte und mit vollem Zugriff auf die `~/.claude/`-Session des Users.
 
-**Install:**
-- Veröffentlichen mit `dotnet publish -c Release -r win-x64 --self-contained false`.
-- Service registrieren:
-  ```cmd
-  sc.exe create ClaudeDoWorker binPath= "C:\Path\To\ClaudeDo.Worker.exe" start= auto
-  sc.exe failure ClaudeDoWorker reset= 60 actions= restart/5000/restart/10000/restart/30000
-  ```
-- Später optional: kleines `ClaudeDo.Installer`-Projekt (WiX oder MSIX), das das auch macht.
+**Manueller Start (App-seitig):** Der Installer-Step `StartWorkerStep` startet den Worker beim Install/Update via `Process.Start` direkt. Die App (`IslandsShellViewModel`) startet den Worker **nicht** selbst. Stattdessen: ist der Worker ~12 Sekunden nach App-Start noch offline, erscheint einmalig ein `WorkerConnectionModal` mit drei Optionen (Start Worker / Rerun Installer / Dismiss). Der Connection-Status-Pill in der Fußzeile ist ein klickbarer Button, der das Modal auf Anfrage erneut öffnet.
 
-**Auth-Konflikt mit "User-CLI-Session" beachten:**
-Der Worker-Service läuft per Default unter `LocalSystem` — der hat **keinen Zugriff** auf die `~/.claude/`-Session des interaktiven Users, in der der CLI-Login liegt. Optionen:
+**Stop/Uninstall:** `StopWorkerStep` beendet den Worker via prozessbasiertem Kill (kein `schtasks /End` mehr). `UninstallRunner` löscht die Startup-`.lnk`. Als Migrations-Schritt für ältere Installationen löscht der Uninstaller auch den Legacy-Scheduled-Task „ClaudeDoWorker" und den Legacy-Windows-Service (best-effort).
 
-1. **Empfohlen:** Service unter dem **User-Account** laufen lassen (`sc.exe config ClaudeDoWorker obj= ".\<username>" password= "..."` oder via `services.msc` → "Log On As"). Dann greift die bestehende `claude login`-Session des Users. Voraussetzung: User-Account hat das Recht "Log on as a service".
-2. **Fallback:** Wieder auf API-Key wechseln (`ANTHROPIC_API_KEY` als Umgebungsvariable des Service oder im `worker.config.json`). Dann ist der Service unabhängig vom User-Profil — verliert aber den Vorteil "kein Key-Handling".
+**Logging:** Serilog-File-Sink nach `~/.todo-app/logs/worker-*.log`. Single-Instance-Mutex verhindert parallele Instanzen.
 
-Entscheidung wird beim Service-Deployment getroffen, bleibt für die initiale Console-Variante irrelevant. Service-Modus erfordert keine Schema- oder API-Änderungen am Worker.
+**Pfade:** `WorkerConfig.Load` expandiert `~`/`%USERPROFILE%` für alle Pfad-Felder.
 
-**SignalR im Service-Modus:** Bindung bleibt `127.0.0.1:47821`. Da die UI auf demselben Rechner läuft, ist Loopback-Erreichbarkeit gegeben — Windows-Firewall greift bei Loopback nicht.
+**SignalR:** Bindung bleibt `127.0.0.1:47821`. Da die UI auf demselben Rechner läuft, ist Loopback-Erreichbarkeit gegeben — Windows-Firewall greift bei Loopback nicht.
 
 ## Project-Layout (Monorepo)
 
@@ -319,4 +304,4 @@ Vorteil Monorepo: gemeinsames `schema.sql`, atomische Änderungen über UI+Worke
 - Bulk-Discard alter Worktrees.
 - Anzeige der ndjson-Message-Chronik im UI.
 - Windows Job Objects für garantierten Child-Cleanup beim Worker-Crash.
-- Installer-Projekt (`ClaudeDo.Installer`, WiX/MSIX), das den Service registriert + UI shortcut anlegt.
+- Install-Skripte/Doku für manuelles Deployment ohne Installer.

docs/superpowers/plans/2026-06-01-worker-lifecycle.md

@@ -0,0 +1,829 @@
+# Worker Lifecycle Redesign Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make the worker owned by a single external mechanism (a per-user Startup-folder shortcut in production), stop the App from auto-spawning its own worker, and show an actionable prompt when the App can't connect.
+
+**Architecture:** Installer creates a `.lnk` in the Windows Startup folder instead of a Scheduled Task (migrating existing installs by deleting the old task). The App's `IslandsShellViewModel` drops `EnsureWorkerRunningAsync` and instead runs a one-shot grace timer that opens a `WorkerConnectionModal` (Start Worker / Rerun Installer / Dismiss) if still offline; the footer status pill becomes a button that reopens it.
+
+**Tech Stack:** .NET 8, WPF installer (COM `IShellLink` for shortcuts), Avalonia + CommunityToolkit.Mvvm UI, xUnit.
+
+---
+
+## File Structure
+
+**Installer (`src/ClaudeDo.Installer`)**
+- Create: `Core/ShortcutFactory.cs` — shared `IShellLink` COM helper (`CreateShortcut`).
+- Create: `Core/AutostartShortcut.cs` — install/remove the worker Startup-folder `.lnk`.
+- Modify: `Steps/CreateShortcutsStep.cs` — use `ShortcutFactory`, drop embedded COM.
+- Modify: `Steps/RegisterAutostartStep.cs` — Startup shortcut + legacy-task delete (no more task XML).
+- Modify: `Steps/StartWorkerStep.cs` — `Process.Start` instead of `schtasks /Run`.
+- Modify: `Steps/StopWorkerStep.cs` — drop `schtasks /End`.
+- Modify: `Core/UninstallRunner.cs` — remove the Startup `.lnk`.
+- Delete: `Core/ScheduledTaskXml.cs` (and its test).
+
+**App (`src/ClaudeDo.Ui`)**
+- Create: `ViewModels/Modals/WorkerConnectionModalViewModel.cs`.
+- Create: `Views/Modals/WorkerConnectionModalView.axaml` (+ `.axaml.cs`).
+- Modify: `ViewModels/IslandsShellViewModel.cs` — remove auto-spawn; add hook, command, grace timer, decision gate.
+- Modify: `Views/MainWindow.axaml.cs` — wire the new modal.
+- Modify: `Views/MainWindow.axaml` — clickable status pill.
+
+**Tests**
+- Modify: `tests/ClaudeDo.Installer.Tests/` — delete `ScheduledTaskXmlTests.cs`; add `ShortcutFactoryTests.cs`, `AutostartShortcutTests.cs`.
+- Add: `tests/ClaudeDo.Ui.Tests/ConnectionPromptGateTests.cs`.
+
+---
+
+## Task 1: ShortcutFactory (shared COM helper)
+
+**Files:**
+- Create: `src/ClaudeDo.Installer/Core/ShortcutFactory.cs`
+- Modify: `src/ClaudeDo.Installer/Steps/CreateShortcutsStep.cs`
+- Test: `tests/ClaudeDo.Installer.Tests/ShortcutFactoryTests.cs`
+
+- [ ] **Step 1: Write the failing test**
+
+`tests/ClaudeDo.Installer.Tests/ShortcutFactoryTests.cs`:
+```csharp
+using System.IO;
+using ClaudeDo.Installer.Core;
+
+namespace ClaudeDo.Installer.Tests;
+
+public class ShortcutFactoryTests
+{
+    [Fact]
+    public void CreateShortcut_writes_lnk_file()
+    {
+        var dir = Path.Combine(Path.GetTempPath(), "cdshortcut-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(dir);
+        try
+        {
+            var target = Path.Combine(dir, "fake.exe");
+            File.WriteAllText(target, "");
+            var lnk = Path.Combine(dir, "x.lnk");
+
+            ShortcutFactory.CreateShortcut(lnk, target, dir, "desc");
+
+            Assert.True(File.Exists(lnk));
+        }
+        finally { Directory.Delete(dir, recursive: true); }
+    }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `dotnet test tests/ClaudeDo.Installer.Tests --filter ShortcutFactoryTests`
+Expected: FAIL — `ShortcutFactory` does not exist (compile error).
+
+- [ ] **Step 3: Create `ShortcutFactory` (move COM interop out of `CreateShortcutsStep`)**
+
+`src/ClaudeDo.Installer/Core/ShortcutFactory.cs`:
+```csharp
+using System.Runtime.InteropServices;
+using System.Runtime.InteropServices.ComTypes;
+using System.Text;
+
+namespace ClaudeDo.Installer.Core;
+
+public static class ShortcutFactory
+{
+    public static void CreateShortcut(string shortcutPath, string targetPath, string workingDir, string description)
+    {
+        var link = (IShellLink)new ShellLink();
+        link.SetPath(targetPath);
+        link.SetWorkingDirectory(workingDir);
+        link.SetDescription(description);
+        link.SetIconLocation(targetPath, 0);
+
+        var file = (IPersistFile)link;
+        file.Save(shortcutPath, false);
+    }
+
+    [ComImport]
+    [Guid("00021401-0000-0000-C000-000000000046")]
+    private class ShellLink { }
+
+    [ComImport]
+    [InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+    [Guid("000214F9-0000-0000-C000-000000000046")]
+    private interface IShellLink
+    {
+        void GetPath([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder pszFile, int cchMaxPath, IntPtr pfd, int fFlags);
+        void GetIDList(out IntPtr ppidl);
+        void SetIDList(IntPtr pidl);
+        void GetDescription([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder pszName, int cchMaxName);
+        void SetDescription([MarshalAs(UnmanagedType.LPWStr)] string pszName);
+        void GetWorkingDirectory([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder pszDir, int cchMaxPath);
+        void SetWorkingDirectory([MarshalAs(UnmanagedType.LPWStr)] string pszDir);
+        void GetArguments([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder pszArgs, int cchMaxPath);
+        void SetArguments([MarshalAs(UnmanagedType.LPWStr)] string pszArgs);
+        void GetHotkey(out short pwHotkey);
+        void SetHotkey(short wHotkey);
+        void GetShowCmd(out int piShowCmd);
+        void SetShowCmd(int iShowCmd);
+        void GetIconLocation([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder pszIconPath, int cchIconPath, out int piIcon);
+        void SetIconLocation([MarshalAs(UnmanagedType.LPWStr)] string pszIconPath, int iIcon);
+        void SetRelativePath([MarshalAs(UnmanagedType.LPWStr)] string pszPathRel, int dwReserved);
+        void Resolve(IntPtr hwnd, int fFlags);
+        void SetPath([MarshalAs(UnmanagedType.LPWStr)] string pszFile);
+    }
+}
+```
+
+- [ ] **Step 4: Replace the embedded COM in `CreateShortcutsStep` with the helper**
+
+In `src/ClaudeDo.Installer/Steps/CreateShortcutsStep.cs`: delete the private `CreateShortcut` method and the entire `#region COM Interop for IShellLink` block (lines 47-90), remove the now-unused `using System.Runtime.InteropServices;`, `using System.Runtime.InteropServices.ComTypes;`, and `using System.Text;`. Replace the two `CreateShortcut(...)` call sites with `ShortcutFactory.CreateShortcut(...)`:
+```csharp
+ShortcutFactory.CreateShortcut(startMenuPath, appExe, workingDir, "ClaudeDo Task Manager");
+```
+```csharp
+ShortcutFactory.CreateShortcut(desktopPath, appExe, workingDir, "ClaudeDo Task Manager");
+```
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+Run: `dotnet test tests/ClaudeDo.Installer.Tests --filter ShortcutFactoryTests`
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/ClaudeDo.Installer/Core/ShortcutFactory.cs src/ClaudeDo.Installer/Steps/CreateShortcutsStep.cs tests/ClaudeDo.Installer.Tests/ShortcutFactoryTests.cs
+git commit -m "refactor(installer): extract ShortcutFactory COM helper"
+```
+
+---
+
+## Task 2: AutostartShortcut helper
+
+**Files:**
+- Create: `src/ClaudeDo.Installer/Core/AutostartShortcut.cs`
+- Test: `tests/ClaudeDo.Installer.Tests/AutostartShortcutTests.cs`
+
+- [ ] **Step 1: Write the failing tests**
+
+`tests/ClaudeDo.Installer.Tests/AutostartShortcutTests.cs`:
+```csharp
+using System.IO;
+using ClaudeDo.Installer.Core;
+
+namespace ClaudeDo.Installer.Tests;
+
+public class AutostartShortcutTests
+{
+    private static string TempDir()
+    {
+        var dir = Path.Combine(Path.GetTempPath(), "cdautostart-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(dir);
+        return dir;
+    }
+
+    [Fact]
+    public void Install_creates_lnk_with_expected_name()
+    {
+        var startup = TempDir();
+        var workerDir = TempDir();
+        try
+        {
+            var workerExe = Path.Combine(workerDir, "ClaudeDo.Worker.exe");
+            File.WriteAllText(workerExe, "");
+
+            AutostartShortcut.Install(startup, workerExe);
+
+            Assert.True(File.Exists(Path.Combine(startup, AutostartShortcut.FileName)));
+        }
+        finally { Directory.Delete(startup, true); Directory.Delete(workerDir, true); }
+    }
+
+    [Fact]
+    public void Remove_deletes_existing_lnk()
+    {
+        var startup = TempDir();
+        var workerDir = TempDir();
+        try
+        {
+            var workerExe = Path.Combine(workerDir, "ClaudeDo.Worker.exe");
+            File.WriteAllText(workerExe, "");
+            AutostartShortcut.Install(startup, workerExe);
+
+            AutostartShortcut.Remove(startup);
+
+            Assert.False(File.Exists(Path.Combine(startup, AutostartShortcut.FileName)));
+        }
+        finally { Directory.Delete(startup, true); Directory.Delete(workerDir, true); }
+    }
+
+    [Fact]
+    public void Remove_is_noop_when_missing()
+    {
+        var startup = TempDir();
+        try { AutostartShortcut.Remove(startup); } // must not throw
+        finally { Directory.Delete(startup, true); }
+    }
+}
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `dotnet test tests/ClaudeDo.Installer.Tests --filter AutostartShortcutTests`
+Expected: FAIL — `AutostartShortcut` does not exist.
+
+- [ ] **Step 3: Create `AutostartShortcut`**
+
+`src/ClaudeDo.Installer/Core/AutostartShortcut.cs`:
+```csharp
+using System.IO;
+
+namespace ClaudeDo.Installer.Core;
+
+public static class AutostartShortcut
+{
+    public const string FileName = "ClaudeDo Worker.lnk";
+
+    public static string DefaultStartupDir =>
+        Environment.GetFolderPath(Environment.SpecialFolder.Startup);
+
+    public static string PathIn(string startupDir) => Path.Combine(startupDir, FileName);
+
+    public static void Install(string startupDir, string workerExe)
+    {
+        Directory.CreateDirectory(startupDir);
+        var workingDir = Path.GetDirectoryName(workerExe) ?? startupDir;
+        ShortcutFactory.CreateShortcut(PathIn(startupDir), workerExe, workingDir, "ClaudeDo background worker");
+    }
+
+    public static void Remove(string startupDir)
+    {
+        var path = PathIn(startupDir);
+        if (File.Exists(path)) File.Delete(path);
+    }
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `dotnet test tests/ClaudeDo.Installer.Tests --filter AutostartShortcutTests`
+Expected: PASS (3 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ClaudeDo.Installer/Core/AutostartShortcut.cs tests/ClaudeDo.Installer.Tests/AutostartShortcutTests.cs
+git commit -m "feat(installer): add AutostartShortcut helper for Startup-folder lnk"
+```
+
+---
+
+## Task 3: RegisterAutostartStep → Startup shortcut + task migration
+
+**Files:**
+- Modify: `src/ClaudeDo.Installer/Steps/RegisterAutostartStep.cs`
+- Delete: `src/ClaudeDo.Installer/Core/ScheduledTaskXml.cs`
+- Delete: `tests/ClaudeDo.Installer.Tests/ScheduledTaskXmlTests.cs`
+
+- [ ] **Step 1: Replace the step body**
+
+Rewrite `src/ClaudeDo.Installer/Steps/RegisterAutostartStep.cs` to:
+```csharp
+using System.IO;
+using ClaudeDo.Installer.Core;
+
+namespace ClaudeDo.Installer.Steps;
+
+public sealed class RegisterAutostartStep : IInstallStep
+{
+    public const string LegacyTaskName = "ClaudeDoWorker";
+    private const string LegacyServiceName = "ClaudeDoWorker";
+
+    public string Name => "Register Autostart";
+
+    public async Task<StepResult> ExecuteAsync(InstallContext ctx, IProgress<string> progress, CancellationToken ct)
+    {
+        var workerExe = Path.Combine(ctx.InstallDirectory, "worker", "ClaudeDo.Worker.exe");
+        if (!File.Exists(workerExe))
+            return StepResult.Fail($"Worker executable not found: {workerExe}");
+
+        // 1) Migrate away the legacy Windows service if present.
+        progress.Report("Checking for legacy worker service...");
+        var (queryExit, _) = await ProcessRunner.RunAsync("sc.exe", $"query {LegacyServiceName}", null, progress, ct);
+        if (queryExit == 0)
+        {
+            progress.Report("Removing legacy worker service...");
+            await ProcessRunner.RunAsync("sc.exe", $"stop {LegacyServiceName}", null, progress, ct);
+            await ProcessRunner.RunAsync("sc.exe", $"delete {LegacyServiceName}", null, progress, ct);
+            for (var i = 0; i < 30; i++)
+            {
+                ct.ThrowIfCancellationRequested();
+                var (q, _) = await ProcessRunner.RunAsync("sc.exe", $"query {LegacyServiceName}", null, progress, ct);
+                if (q != 0) break;
+                await Task.Delay(1000, ct);
+            }
+        }
+
+        // 2) Migrate away the legacy logon scheduled task if present (best-effort).
+        progress.Report("Removing legacy logon task...");
+        await ProcessRunner.RunAsync("schtasks.exe", $"/Delete /TN \"{LegacyTaskName}\" /F", null, progress, ct);
+
+        // 3) Register per-user autostart via a Startup-folder shortcut.
+        progress.Report("Creating Startup shortcut...");
+        try
+        {
+            AutostartShortcut.Install(AutostartShortcut.DefaultStartupDir, workerExe);
+        }
+        catch (Exception ex)
+        {
+            return StepResult.Fail($"Failed to create Startup shortcut: {ex.Message}");
+        }
+
+        return StepResult.Ok();
+    }
+}
+```
+
+- [ ] **Step 2: Delete the obsolete scheduled-task code and its test**
+
+Run:
+```bash
+git rm src/ClaudeDo.Installer/Core/ScheduledTaskXml.cs tests/ClaudeDo.Installer.Tests/ScheduledTaskXmlTests.cs
+```
+
+- [ ] **Step 3: Build the installer to verify it compiles**
+
+Run: `dotnet build src/ClaudeDo.Installer/ClaudeDo.Installer.csproj`
+Expected: Build succeeded. (If `RegisterAutostartStep.TaskName` was referenced elsewhere, the build will flag it — Task 4 and Task 5 update those references; if the build fails only there, proceed to those tasks before re-running.)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/ClaudeDo.Installer/Steps/RegisterAutostartStep.cs
+git commit -m "feat(installer): register autostart via Startup shortcut, drop scheduled task"
+```
+
+---
+
+## Task 4: StartWorkerStep + StopWorkerStep
+
+**Files:**
+- Modify: `src/ClaudeDo.Installer/Steps/StartWorkerStep.cs`
+- Modify: `src/ClaudeDo.Installer/Steps/StopWorkerStep.cs`
+
+- [ ] **Step 1: Rewrite `StartWorkerStep` to launch the exe directly**
+
+`src/ClaudeDo.Installer/Steps/StartWorkerStep.cs`:
+```csharp
+using System.Diagnostics;
+using System.IO;
+using ClaudeDo.Installer.Core;
+
+namespace ClaudeDo.Installer.Steps;
+
+public sealed class StartWorkerStep : IInstallStep
+{
+    public string Name => "Start Worker";
+
+    public Task<StepResult> ExecuteAsync(InstallContext ctx, IProgress<string> progress, CancellationToken ct)
+    {
+        var workerExe = Path.Combine(ctx.InstallDirectory, "worker", "ClaudeDo.Worker.exe");
+        if (!File.Exists(workerExe))
+            return Task.FromResult(StepResult.Fail($"Worker executable not found: {workerExe}"));
+
+        progress.Report("Starting worker...");
+        try
+        {
+            Process.Start(new ProcessStartInfo(workerExe) { UseShellExecute = true });
+            return Task.FromResult(StepResult.Ok());
+        }
+        catch (Exception ex)
+        {
+            return Task.FromResult(StepResult.Fail($"Failed to start worker: {ex.Message}"));
+        }
+    }
+}
+```
+
+- [ ] **Step 2: Drop the `schtasks /End` call in `StopWorkerStep`**
+
+In `src/ClaudeDo.Installer/Steps/StopWorkerStep.cs`, remove these two lines (the task no longer exists; the process kill below is the real stop):
+```csharp
+        progress.Report("Stopping worker task (if running)...");
+        await ProcessRunner.RunAsync("schtasks.exe", $"/End /TN \"{TaskName}\"", null, progress, ct);
+```
+Keep the `public const string TaskName = "ClaudeDoWorker";` line — `UninstallRunner` still references it for legacy-task cleanup (Task 5). The method keeps its `async` modifier (it still has `await Task.CompletedTask;`).
+
+- [ ] **Step 3: Build to verify it compiles**
+
+Run: `dotnet build src/ClaudeDo.Installer/ClaudeDo.Installer.csproj`
+Expected: Build succeeded.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/ClaudeDo.Installer/Steps/StartWorkerStep.cs src/ClaudeDo.Installer/Steps/StopWorkerStep.cs
+git commit -m "feat(installer): start worker via Process.Start, drop schtasks stop"
+```
+
+---
+
+## Task 5: UninstallRunner removes the Startup shortcut
+
+**Files:**
+- Modify: `src/ClaudeDo.Installer/Core/UninstallRunner.cs`
+
+- [ ] **Step 1: Add Startup `.lnk` removal**
+
+In `src/ClaudeDo.Installer/Core/UninstallRunner.cs`, the shortcut-removal block (step 4, around lines 53-60) currently removes the Desktop and Start Menu `.lnk`s. Add the Startup shortcut removal right after them:
+```csharp
+        // 4) Remove shortcuts (best-effort — a stuck .lnk must not block the rest).
+        progress.Report("Removing shortcuts...");
+        TryDeleteFile(Path.Combine(
+            Environment.GetFolderPath(Environment.SpecialFolder.CommonDesktopDirectory),
+            "ClaudeDo.lnk"));
+        TryDeleteFile(Path.Combine(
+            Environment.GetFolderPath(Environment.SpecialFolder.CommonStartMenu),
+            "Programs", "ClaudeDo.lnk"));
+        TryDeleteFile(AutostartShortcut.PathIn(AutostartShortcut.DefaultStartupDir));
+```
+The existing `schtasks /Delete /TN "{StopWorkerStep.TaskName}" /F` line (step 3) stays — it cleans up the legacy task on machines that still have it.
+
+- [ ] **Step 2: Build to verify it compiles**
+
+Run: `dotnet build src/ClaudeDo.Installer/ClaudeDo.Installer.csproj`
+Expected: Build succeeded.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/ClaudeDo.Installer/Core/UninstallRunner.cs
+git commit -m "feat(installer): remove Startup worker shortcut on uninstall"
+```
+
+---
+
+## Task 6: App stops auto-spawning the worker
+
+**Files:**
+- Modify: `src/ClaudeDo.Ui/ViewModels/IslandsShellViewModel.cs`
+
+- [ ] **Step 1: Remove the auto-spawn call**
+
+In `src/ClaudeDo.Ui/ViewModels/IslandsShellViewModel.cs`, delete this line from the constructor (line 224):
+```csharp
+        _ = EnsureWorkerRunningAsync();
+```
+
+- [ ] **Step 2: Remove the `EnsureWorkerRunningAsync` method and its flag**
+
+Delete the `_ensureRunningAttempted` field (line 308) and the whole `EnsureWorkerRunningAsync` method (lines 310-320):
+```csharp
+    private bool _ensureRunningAttempted;
+
+    private async Task EnsureWorkerRunningAsync()
+    {
+        if (_ensureRunningAttempted) return;
+        _ensureRunningAttempted = true;
+        await Task.Delay(TimeSpan.FromSeconds(4));
+        if (Worker?.IsConnected == true) return;
+        var exe = _workerLocator.Find();
+        if (exe is null) return;
+        try { System.Diagnostics.Process.Start(new System.Diagnostics.ProcessStartInfo(exe) { UseShellExecute = true }); }
+        catch { /* logon task is the primary mechanism; this is a convenience */ }
+    }
+```
+Keep `RestartWorkerAsync` / `RestartWorkerService` (still used by the existing Restart button). `_workerLocator` stays in use (RestartWorkerService + Task 8).
+
+- [ ] **Step 3: Build to verify it compiles**
+
+Run: `dotnet build src/ClaudeDo.App/ClaudeDo.App.csproj`
+Expected: Build succeeded (no remaining references to `EnsureWorkerRunningAsync`).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/ClaudeDo.Ui/ViewModels/IslandsShellViewModel.cs
+git commit -m "refactor(ui): stop auto-spawning the worker on app start"
+```
+
+---
+
+## Task 7: WorkerConnectionModal (VM + View)
+
+**Files:**
+- Create: `src/ClaudeDo.Ui/ViewModels/Modals/WorkerConnectionModalViewModel.cs`
+- Create: `src/ClaudeDo.Ui/Views/Modals/WorkerConnectionModalView.axaml`
+- Create: `src/ClaudeDo.Ui/Views/Modals/WorkerConnectionModalView.axaml.cs`
+
+- [ ] **Step 1: Create the ViewModel**
+
+`src/ClaudeDo.Ui/ViewModels/Modals/WorkerConnectionModalViewModel.cs`:
+```csharp
+using System;
+using System.Diagnostics;
+using ClaudeDo.Ui.Services;
+using CommunityToolkit.Mvvm.Input;
+
+namespace ClaudeDo.Ui.ViewModels.Modals;
+
+public sealed partial class WorkerConnectionModalViewModel : ViewModelBase
+{
+    private readonly WorkerLocator _workerLocator;
+    private readonly InstallerLocator _installerLocator;
+
+    public WorkerConnectionModalViewModel(WorkerLocator workerLocator, InstallerLocator installerLocator)
+    {
+        _workerLocator = workerLocator;
+        _installerLocator = installerLocator;
+    }
+
+    public Action? CloseAction { get; set; }
+
+    [RelayCommand] private void Close() => CloseAction?.Invoke();
+
+    [RelayCommand]
+    private void StartWorker()
+    {
+        var exe = _workerLocator.Find();
+        if (exe is null) return;
+        try { Process.Start(new ProcessStartInfo(exe) { UseShellExecute = true }); }
+        catch { /* nothing useful to show */ }
+        CloseAction?.Invoke();
+    }
+
+    [RelayCommand]
+    private void RerunInstaller()
+    {
+        var path = _installerLocator.Find();
+        if (path is null) return;
+        try
+        {
+            Process.Start(new ProcessStartInfo(path) { UseShellExecute = true });
+            Environment.Exit(0);
+        }
+        catch { /* nothing useful to show */ }
+    }
+}
+```
+
+- [ ] **Step 2: Create the View (mirrors `AboutModalView` + `ModalShell`)**
+
+`src/ClaudeDo.Ui/Views/Modals/WorkerConnectionModalView.axaml`:
+```xml
+<Window xmlns="https://github.com/avaloniaui"
+        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+        xmlns:vm="using:ClaudeDo.Ui.ViewModels.Modals"
+        xmlns:ctl="using:ClaudeDo.Ui.Views.Controls"
+        x:Class="ClaudeDo.Ui.Views.Modals.WorkerConnectionModalView"
+        x:DataType="vm:WorkerConnectionModalViewModel"
+        Title="Worker not reachable"
+        Width="520" Height="240"
+        WindowDecorations="None"
+        ExtendClientAreaToDecorationsHint="True"
+        WindowStartupLocation="CenterOwner"
+        Background="{DynamicResource SurfaceBrush}">
+  <Window.KeyBindings>
+    <KeyBinding Gesture="Escape" Command="{Binding CloseCommand}"/>
+  </Window.KeyBindings>
+
+  <ctl:ModalShell Title="WORKER NOT REACHABLE" CloseCommand="{Binding CloseCommand}">
+    <Grid RowDefinitions="*,Auto" Margin="20,16">
+      <TextBlock Grid.Row="0" Classes="meta" TextWrapping="Wrap"
+                 Text="ClaudeDo can't reach the background worker. It is normally started automatically at logon. You can start it now, or reinstall if the problem persists."/>
+      <StackPanel Grid.Row="1" Orientation="Horizontal" Spacing="8"
+                  HorizontalAlignment="Right" Margin="0,16,0,0">
+        <Button Classes="btn" Content="Dismiss" Command="{Binding CloseCommand}"/>
+        <Button Classes="btn" Content="Rerun Installer" Command="{Binding RerunInstallerCommand}"/>
+        <Button Classes="btn primary" Content="Start Worker" Command="{Binding StartWorkerCommand}"/>
+      </StackPanel>
+    </Grid>
+  </ctl:ModalShell>
+</Window>
+```
+
+`src/ClaudeDo.Ui/Views/Modals/WorkerConnectionModalView.axaml.cs`:
+```csharp
+using Avalonia.Controls;
+using Avalonia.Markup.Xaml;
+
+namespace ClaudeDo.Ui.Views.Modals;
+
+public partial class WorkerConnectionModalView : Window
+{
+    public WorkerConnectionModalView()
+    {
+        InitializeComponent();
+    }
+
+    private void InitializeComponent() => AvaloniaXamlLoader.Load(this);
+}
+```
+
+- [ ] **Step 3: Build to verify it compiles**
+
+Run: `dotnet build src/ClaudeDo.App/ClaudeDo.App.csproj`
+Expected: Build succeeded.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/ClaudeDo.Ui/ViewModels/Modals/WorkerConnectionModalViewModel.cs src/ClaudeDo.Ui/Views/Modals/WorkerConnectionModalView.axaml src/ClaudeDo.Ui/Views/Modals/WorkerConnectionModalView.axaml.cs
+git commit -m "feat(ui): add worker connection help modal"
+```
+
+---
+
+## Task 8: Shell hook, command, grace timer + decision gate
+
+**Files:**
+- Modify: `src/ClaudeDo.Ui/ViewModels/IslandsShellViewModel.cs`
+- Test: `tests/ClaudeDo.Ui.Tests/ConnectionPromptGateTests.cs`
+
+- [ ] **Step 1: Write the failing test for the decision gate**
+
+`tests/ClaudeDo.Ui.Tests/ConnectionPromptGateTests.cs`:
+```csharp
+using ClaudeDo.Ui.ViewModels;
+using Xunit;
+
+namespace ClaudeDo.Ui.Tests;
+
+public class ConnectionPromptGateTests
+{
+    [Fact]
+    public void Shows_once_when_offline()
+    {
+        var vm = new IslandsShellViewModel();
+        Assert.True(vm.DecideShowConnectionPrompt(isOffline: true));
+        Assert.False(vm.DecideShowConnectionPrompt(isOffline: true)); // not a second time
+    }
+
+    [Fact]
+    public void Does_not_show_when_connected_before_grace()
+    {
+        var vm = new IslandsShellViewModel();
+        Assert.False(vm.DecideShowConnectionPrompt(isOffline: false));
+    }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `dotnet test tests/ClaudeDo.Ui.Tests --filter ConnectionPromptGateTests`
+Expected: FAIL — `DecideShowConnectionPrompt` does not exist.
+
+- [ ] **Step 3: Add the hook, command, gate, and grace timer**
+
+In `src/ClaudeDo.Ui/ViewModels/IslandsShellViewModel.cs`:
+
+Add a hook property near the other `Show*Modal` hooks (after line 52):
+```csharp
+    // Set by MainWindow to open the worker-connection help dialog.
+    public Func<Modals.WorkerConnectionModalViewModel, Task>? ShowWorkerConnectionModal { get; set; }
+```
+
+Add the gate field + method and the open command (place near `OpenAbout`, around line 271):
+```csharp
+    private bool _connectionPromptShown;
+
+    internal bool DecideShowConnectionPrompt(bool isOffline)
+    {
+        if (!isOffline) return false;
+        if (_connectionPromptShown) return false;
+        _connectionPromptShown = true;
+        return true;
+    }
+
+    private async Task OpenWorkerConnectionHelpAsync()
+    {
+        var vm = new Modals.WorkerConnectionModalViewModel(_workerLocator, _installerLocator);
+        if (ShowWorkerConnectionModal is not null) await ShowWorkerConnectionModal(vm);
+    }
+
+    [RelayCommand]
+    private Task OpenWorkerConnectionHelp() => OpenWorkerConnectionHelpAsync();
+```
+
+Add the grace timer field near `_clearTimer` (line 74):
+```csharp
+    private readonly System.Timers.Timer _connectTimer = new(12_000) { AutoReset = false };
+```
+
+Wire and start it inside the **public** constructor (after the `_primeStatusTimer.Elapsed` wiring, near line 222 — NOT in the parameterless test constructor):
+```csharp
+        _connectTimer.Elapsed += (_, _) => Dispatcher.UIThread.Post(() =>
+        {
+            if (DecideShowConnectionPrompt(IsOffline)) _ = OpenWorkerConnectionHelpAsync();
+        });
+        _connectTimer.Start();
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `dotnet test tests/ClaudeDo.Ui.Tests --filter ConnectionPromptGateTests`
+Expected: PASS (2 tests).
+
+- [ ] **Step 5: Build the app**
+
+Run: `dotnet build src/ClaudeDo.App/ClaudeDo.App.csproj`
+Expected: Build succeeded.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/ClaudeDo.Ui/ViewModels/IslandsShellViewModel.cs tests/ClaudeDo.Ui.Tests/ConnectionPromptGateTests.cs
+git commit -m "feat(ui): prompt once on worker connection failure with grace timer"
+```
+
+---
+
+## Task 9: Wire the modal in MainWindow + clickable status pill
+
+**Files:**
+- Modify: `src/ClaudeDo.Ui/Views/MainWindow.axaml.cs`
+- Modify: `src/ClaudeDo.Ui/Views/MainWindow.axaml`
+
+- [ ] **Step 1: Wire the dialog hook**
+
+In `src/ClaudeDo.Ui/Views/MainWindow.axaml.cs`, inside `OnDataContextChanged`, after the existing `vm.ShowRepoImportModal = ...` block (line 70), add:
+```csharp
+            vm.ShowWorkerConnectionModal = async (connVm) =>
+            {
+                var dlg = new WorkerConnectionModalView { DataContext = connVm };
+                connVm.CloseAction = () => dlg.Close();
+                await dlg.ShowDialog(this);
+            };
+```
+(`ClaudeDo.Ui.Views.Modals` is already imported at line 10.)
+
+- [ ] **Step 2: Make the status pill a button**
+
+In `src/ClaudeDo.Ui/Views/MainWindow.axaml`, replace the left "connection pill" `StackPanel` (lines 190-202) with a `Button` wrapping the same content:
+```xml
+        <!-- Left: connection pill (click to open worker help) -->
+        <Button DockPanel.Dock="Left"
+                Command="{Binding OpenWorkerConnectionHelpCommand}"
+                Background="Transparent" BorderThickness="0" Padding="0"
+                Cursor="Hand" VerticalAlignment="Center">
+          <StackPanel Orientation="Horizontal" Spacing="7" VerticalAlignment="Center">
+            <Ellipse Width="7" Height="7" Fill="{DynamicResource StatusRunningBrush}"
+                     IsVisible="{Binding Worker.IsConnected}"/>
+            <Ellipse Width="7" Height="7" Fill="{DynamicResource StatusReviewBrush}"
+                     IsVisible="{Binding Worker.IsReconnecting}"/>
+            <Ellipse Width="7" Height="7" Fill="{DynamicResource StatusErrorBrush}"
+                     IsVisible="{Binding IsOffline}"/>
+            <TextBlock Classes="eyebrow"
+                       Text="{Binding ConnectionText, Converter={StaticResource UpperCase}}"
+                       LetterSpacing="1.4"
+                       VerticalAlignment="Center"/>
+          </StackPanel>
+        </Button>
+```
+
+- [ ] **Step 3: Build the app**
+
+Run: `dotnet build src/ClaudeDo.App/ClaudeDo.App.csproj`
+Expected: Build succeeded.
+
+- [ ] **Step 4: Manual verification**
+
+Start the worker (or leave it stopped) and run the App:
+- Worker stopped → after ~12s the "WORKER NOT REACHABLE" dialog appears once. **Start Worker** launches it (footer pill turns ONLINE); **Rerun Installer** launches the installer and exits; **Dismiss** closes and does not reappear automatically.
+- Click the footer status pill anytime → the dialog reopens.
+- Worker running before launch → no dialog appears.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ClaudeDo.Ui/Views/MainWindow.axaml.cs src/ClaudeDo.Ui/Views/MainWindow.axaml
+git commit -m "feat(ui): wire worker connection modal and make status pill clickable"
+```
+
+---
+
+## Task 10: Full build + test sweep
+
+- [ ] **Step 1: Build the touched projects**
+
+Run:
+```bash
+dotnet build src/ClaudeDo.App/ClaudeDo.App.csproj
+dotnet build src/ClaudeDo.Installer/ClaudeDo.Installer.csproj
+```
+Expected: both Build succeeded.
+
+- [ ] **Step 2: Run the affected test suites**
+
+Run:
+```bash
+dotnet test tests/ClaudeDo.Installer.Tests
+dotnet test tests/ClaudeDo.Ui.Tests
+```
+Expected: all pass; no references to the deleted `ScheduledTaskXml`.
+
+- [ ] **Step 3: Final commit (if any stragglers)**
+
+```bash
+git add -A
+git commit -m "chore: worker lifecycle redesign cleanup" || echo "nothing to commit"
+```

docs/superpowers/specs/2026-06-01-worker-lifecycle-design.md

@@ -0,0 +1,153 @@
+# Worker Lifecycle Redesign
+
+**Date:** 2026-06-01
+**Status:** Approved (design)
+
+## Problem
+
+The worker process has multiple competing owners, which collide in development and
+muddy production behavior:
+
+- The App auto-spawns its own worker on startup (`EnsureWorkerRunningAsync`,
+  `IslandsShellViewModel.cs:310`, called at line 224) ~4s after launch if it isn't
+  yet connected. In the IDE "Start Everything" multilaunch — which already runs the
+  worker via the `http` launch profile (`dotnet run`) — this produces a *second*
+  worker that fails to bind to `127.0.0.1:47821` and dies, surfacing a stray console
+  with a "failed to bind to address" error.
+- Production autostart uses a per-user logon **Scheduled Task** (`RegisterAutostartStep`
+  + `ScheduledTaskXml`), which the user wants to replace with a simpler Startup-folder
+  shortcut.
+- When the App can't reach the worker, the only feedback is a silent "Offline" pill in
+  the footer — no guidance to the user.
+
+## Goal
+
+Establish a single owner for the worker lifecycle and make connection failures
+actionable:
+
+1. The worker is owned **externally** — a per-user **Startup-folder shortcut** in
+   production (replacing the Scheduled Task), or the IDE in development.
+2. The App **only connects**; it never auto-spawns a worker.
+3. When the App can't connect, it shows a one-time prompt offering **Start Worker**,
+   **Rerun Installer**, or **Dismiss**, plus a clickable Offline pill to reopen it.
+
+## Non-Goals
+
+- No change to the IDE dev setup. The "Start Everything" multilaunch keeps running the
+  worker via the `http` profile (console with live logs); the duplicate/bind-error
+  worker disappears purely because the App no longer auto-spawns. Rider run configs live
+  in `.idea/.../workspace.xml` (per-user, gitignored) and are out of scope.
+- No change to the SignalR hub URL, port, reconnect policy, or the worker's
+  single-instance mutex.
+
+## Design
+
+### Component 1 — Installer: Scheduled Task → Startup-folder shortcut
+
+**`RegisterAutostartStep`** (`src/ClaudeDo.Installer/Steps/RegisterAutostartStep.cs`)
+- Replace the task-XML build + `schtasks /Create` with creation of a `.lnk` in the
+  per-user Startup folder (`Environment.SpecialFolder.Startup`) targeting
+  `{InstallDirectory}\worker\ClaudeDo.Worker.exe`. The worker is `WinExe`, so it launches
+  with no console window.
+- **Migration:** keep the existing legacy Windows-service removal, and **add** removal of
+  the old scheduled task: `schtasks.exe /Delete /TN "ClaudeDoWorker" /F` (best-effort),
+  so existing installs migrate cleanly to the shortcut model.
+
+**`StartWorkerStep`** (`src/ClaudeDo.Installer/Steps/StartWorkerStep.cs`)
+- Replace `schtasks /Run /TN ClaudeDoWorker` with a direct
+  `Process.Start(new ProcessStartInfo(workerExe) { UseShellExecute = true })`.
+
+**`StopWorkerStep`** (`src/ClaudeDo.Installer/Steps/StopWorkerStep.cs`)
+- Drop the `schtasks /End` call. Keep the existing install-dir-scoped process kill, which
+  is the real stop mechanism.
+
+**`UninstallRunner`** (`src/ClaudeDo.Installer/Core/UninstallRunner.cs`)
+- Keep the existing `schtasks /Delete` and `sc delete` (migration/legacy cleanup).
+- **Add** deletion of the Startup-folder `.lnk` alongside the existing Start Menu /
+  Desktop shortcut removal.
+
+**Shared shortcut helper**
+- Extract the `IShellLink` COM interop currently embedded in `CreateShortcutsStep` into a
+  shared `src/ClaudeDo.Installer/Core/ShortcutFactory.cs` (`CreateShortcut(path, target,
+  workingDir, description)`). Both `CreateShortcutsStep` and `RegisterAutostartStep` use it.
+
+**Cleanup**
+- Delete `src/ClaudeDo.Installer/Core/ScheduledTaskXml.cs` once unreferenced.
+
+The autostart shortcut name and location: `ClaudeDo Worker.lnk` in
+`Environment.SpecialFolder.Startup`, working directory `{InstallDirectory}\worker`.
+
+### Component 2 — App: stop auto-spawning the worker
+
+**`IslandsShellViewModel`** (`src/ClaudeDo.Ui/ViewModels/IslandsShellViewModel.cs`)
+- Remove the `_ = EnsureWorkerRunningAsync();` call (line 224) and the
+  `EnsureWorkerRunningAsync` method + its `_ensureRunningAttempted` flag.
+- Keep the worker-launch logic (`RestartWorkerService`, which finds the worker exe via
+  `WorkerLocator` and starts it) — it becomes the backing action for the prompt's
+  **Start Worker** button. The existing `RestartWorkerAsync` command stays.
+
+### Component 3 — App: connection-failure prompt
+
+**New dialog** `WorkerConnectionModalViewModel`
+(`src/ClaudeDo.Ui/ViewModels/Modals/WorkerConnectionModalViewModel.cs`) +
+`WorkerConnectionModalView` (`src/ClaudeDo.Ui/Views/Modals/`).
+- Buttons: **Start Worker**, **Rerun Installer**, **Dismiss**.
+- Uses the established dialog pattern: a `Func<WorkerConnectionModalViewModel, Task>`
+  hook on `IslandsShellViewModel` set by `MainWindow` (mirroring `ShowAboutModal`), and
+  the dialog resolves a `TaskCompletionSource` on button press.
+- **Start Worker** → `WorkerLocator.Find()` + `Process.Start` (reuse the
+  `RestartWorkerService` path). **Rerun Installer** → `InstallerLocator.Find()` + launch
+  + `Environment.Exit(0)` (same pattern as the existing `UpdateNow` command).
+  **Dismiss** → close.
+
+**Trigger logic** (in `IslandsShellViewModel`)
+- A one-shot grace timer (~12s) started on construction/startup. When it elapses, if the
+  worker is still offline (`IsOffline` — not connected and not reconnecting) and the
+  prompt hasn't been shown yet (`_connectionPromptShown`), show the dialog once and set
+  the flag.
+- If the worker connects before the grace elapses, the prompt is never shown.
+
+**Clickable Offline pill** (`src/ClaudeDo.Ui/Views/MainWindow.axaml`)
+- Turn the footer status pill into a button bound to a command that opens the same dialog
+  on demand (independent of the one-shot flag), so the user can reopen guidance anytime
+  while offline.
+
+### Component 4 — Dev
+
+No code change (see Non-Goals).
+
+## Data Flow
+
+```
+Startup (production):
+  Windows logon -> Startup-folder .lnk -> ClaudeDo.Worker.exe (WinExe, mutex-guarded)
+  App launches -> WorkerClient connects to 127.0.0.1:47821
+    connected within grace      -> Online pill, no prompt
+    still offline after ~12s    -> WorkerConnectionModal (once)
+
+User clicks Offline pill (anytime offline) -> WorkerConnectionModal
+  Start Worker     -> Process.Start(worker exe)
+  Rerun Installer  -> Process.Start(installer), Environment.Exit(0)
+  Dismiss          -> close
+```
+
+## Error Handling
+
+- Worker exe / installer not found (`Locator.Find()` returns null): the corresponding
+  dialog button is a no-op (consistent with existing `UpdateNow` behavior); the dialog
+  stays open so the user can pick another action.
+- Startup-shortcut creation failure in the installer: surfaced as a failed install step
+  (`StepResult.Fail`), same as the current task-registration failure path.
+- Legacy scheduled-task deletion is best-effort and never fails the install.
+
+## Testing
+
+- **`Installer.Tests`**: `RegisterAutostartStep` creates the Startup `.lnk` at the
+  expected path with the correct target, and issues the legacy-task delete command.
+  `UninstallRunner` removes the Startup `.lnk`.
+- **`Ui.Tests`**: prompt trigger logic — grace elapsed while offline shows the prompt
+  exactly once; a connection established before grace suppresses it; the clickable-pill
+  command opens the dialog regardless of the one-shot flag. (Abstract the dialog-show
+  hook so it can be asserted without real UI.)
+- **Manual**: dialog buttons (Start Worker / Rerun Installer / Dismiss) and the clickable
+  Offline pill in a running App.

src/ClaudeDo.Installer/Core/AutostartShortcut.cs

@@ -0,0 +1,26 @@
+using System.IO;
+
+namespace ClaudeDo.Installer.Core;
+
+public static class AutostartShortcut
+{
+    public const string FileName = "ClaudeDo Worker.lnk";
+
+    public static string DefaultStartupDir =>
+        Environment.GetFolderPath(Environment.SpecialFolder.Startup);
+
+    public static string PathIn(string startupDir) => Path.Combine(startupDir, FileName);
+
+    public static void Install(string startupDir, string workerExe)
+    {
+        Directory.CreateDirectory(startupDir);
+        var workingDir = Path.GetDirectoryName(workerExe) ?? startupDir;
+        ShortcutFactory.CreateShortcut(PathIn(startupDir), workerExe, workingDir, "ClaudeDo background worker");
+    }
+
+    public static void Remove(string startupDir)
+    {
+        var path = PathIn(startupDir);
+        if (File.Exists(path)) File.Delete(path);
+    }
+}

src/ClaudeDo.Installer/Core/ScheduledTaskXml.cs

@@ -1,52 +0,0 @@
-using System.Security;
-
-namespace ClaudeDo.Installer.Core;
-
-public static class ScheduledTaskXml
-{
-    public static string Build(string userId, string workerExePath, int restartIntervalMinutes)
-    {
-        var minutes = restartIntervalMinutes < 1 ? 1 : restartIntervalMinutes;
-        var user = SecurityElement.Escape(userId);
-        var cmd = SecurityElement.Escape(workerExePath);
-        return $"""
-        <?xml version="1.0" encoding="UTF-16"?>
-        <Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
-          <RegistrationInfo>
-            <Description>ClaudeDo background worker (per-user).</Description>
-          </RegistrationInfo>
-          <Triggers>
-            <LogonTrigger>
-              <Enabled>true</Enabled>
-              <UserId>{user}</UserId>
-            </LogonTrigger>
-          </Triggers>
-          <Principals>
-            <Principal id="Author">
-              <UserId>{user}</UserId>
-              <LogonType>InteractiveToken</LogonType>
-              <RunLevel>LeastPrivilege</RunLevel>
-            </Principal>
-          </Principals>
-          <Settings>
-            <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
-            <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
-            <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
-            <AllowHardTerminate>true</AllowHardTerminate>
-            <StartWhenAvailable>true</StartWhenAvailable>
-            <Hidden>true</Hidden>
-            <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
-            <RestartOnFailure>
-              <Interval>PT{minutes}M</Interval>
-              <Count>3</Count>
-            </RestartOnFailure>
-          </Settings>
-          <Actions Context="Author">
-            <Exec>
-              <Command>{cmd}</Command>
-            </Exec>
-          </Actions>
-        </Task>
-        """;
-    }
-}

src/ClaudeDo.Installer/Core/ShortcutFactory.cs

@@ -0,0 +1,49 @@
+using System.Runtime.InteropServices;
+using System.Runtime.InteropServices.ComTypes;
+using System.Text;
+
+namespace ClaudeDo.Installer.Core;
+
+public static class ShortcutFactory
+{
+    public static void CreateShortcut(string shortcutPath, string targetPath, string workingDir, string description)
+    {
+        var link = (IShellLink)new ShellLink();
+        link.SetPath(targetPath);
+        link.SetWorkingDirectory(workingDir);
+        link.SetDescription(description);
+        link.SetIconLocation(targetPath, 0);
+
+        var file = (IPersistFile)link;
+        file.Save(shortcutPath, false);
+    }
+
+    [ComImport]
+    [Guid("00021401-0000-0000-C000-000000000046")]
+    private class ShellLink { }
+
+    [ComImport]
+    [InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+    [Guid("000214F9-0000-0000-C000-000000000046")]
+    private interface IShellLink
+    {
+        void GetPath([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder pszFile, int cchMaxPath, IntPtr pfd, int fFlags);
+        void GetIDList(out IntPtr ppidl);
+        void SetIDList(IntPtr pidl);
+        void GetDescription([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder pszName, int cchMaxName);
+        void SetDescription([MarshalAs(UnmanagedType.LPWStr)] string pszName);
+        void GetWorkingDirectory([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder pszDir, int cchMaxPath);
+        void SetWorkingDirectory([MarshalAs(UnmanagedType.LPWStr)] string pszDir);
+        void GetArguments([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder pszArgs, int cchMaxPath);
+        void SetArguments([MarshalAs(UnmanagedType.LPWStr)] string pszArgs);
+        void GetHotkey(out short pwHotkey);
+        void SetHotkey(short wHotkey);
+        void GetShowCmd(out int piShowCmd);
+        void SetShowCmd(int iShowCmd);
+        void GetIconLocation([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder pszIconPath, int cchIconPath, out int piIcon);
+        void SetIconLocation([MarshalAs(UnmanagedType.LPWStr)] string pszIconPath, int iIcon);
+        void SetRelativePath([MarshalAs(UnmanagedType.LPWStr)] string pszPathRel, int dwReserved);
+        void Resolve(IntPtr hwnd, int fFlags);
+        void SetPath([MarshalAs(UnmanagedType.LPWStr)] string pszFile);
+    }
+}

src/ClaudeDo.Installer/Core/UninstallRunner.cs

@@ -34,9 +34,10 @@ public sealed class UninstallRunner
                 $"Cannot uninstall: worker did not stop cleanly. {stopResult.ErrorMessage} " +
                 "Kill the worker manually and re-run uninstall.");
 
-        // 3) Unregister the autostart task, and best-effort remove any legacy service.
-        progress.Report("Removing autostart task...");
-        await ProcessRunner.RunAsync("schtasks.exe", $"/Delete /TN \"{StopWorkerStep.TaskName}\" /F", null, progress, ct);
+        // 3) Best-effort removal of the legacy scheduled task and Windows service
+        //    (older installs; current installs autostart via a Startup-folder shortcut).
+        progress.Report("Removing legacy autostart task...");
+        await ProcessRunner.RunAsync("schtasks.exe", $"/Delete /TN \"{StopWorkerStep.LegacyTaskName}\" /F", null, progress, ct);
         await ProcessRunner.RunAsync("sc.exe", "delete ClaudeDoWorker", null, progress, ct);
 
         // 3b) Remove Apps & Features registry entry (best-effort).
@@ -58,6 +59,7 @@ public sealed class UninstallRunner
         TryDeleteFile(Path.Combine(
             Environment.GetFolderPath(Environment.SpecialFolder.CommonStartMenu),
             "Programs", "ClaudeDo.lnk"));
+        TryDeleteFile(AutostartShortcut.PathIn(AutostartShortcut.DefaultStartupDir));
 
         // 5) Delete install directory. Track success so we can report partial state.
         var failures = new List<string>();

src/ClaudeDo.Installer/Steps/CreateShortcutsStep.cs

@@ -1,7 +1,4 @@
 using System.IO;
-using System.Runtime.InteropServices;
-using System.Runtime.InteropServices.ComTypes;
-using System.Text;
 using ClaudeDo.Installer.Core;
 
 namespace ClaudeDo.Installer.Steps;
@@ -23,7 +20,7 @@ public sealed class CreateShortcutsStep : IInstallStep
                 "Programs");
             Directory.CreateDirectory(startMenuDir);
             var startMenuPath = Path.Combine(startMenuDir, "ClaudeDo.lnk");
-            CreateShortcut(startMenuPath, appExe, workingDir, "ClaudeDo Task Manager");
+            ShortcutFactory.CreateShortcut(startMenuPath, appExe, workingDir, "ClaudeDo Task Manager");
             progress.Report($"Created Start Menu shortcut: {startMenuPath}");
 
             // Desktop shortcut (optional)
@@ -32,7 +29,7 @@ public sealed class CreateShortcutsStep : IInstallStep
                 var desktopPath = Path.Combine(
                     Environment.GetFolderPath(Environment.SpecialFolder.CommonDesktopDirectory),
                     "ClaudeDo.lnk");
-                CreateShortcut(desktopPath, appExe, workingDir, "ClaudeDo Task Manager");
+                ShortcutFactory.CreateShortcut(desktopPath, appExe, workingDir, "ClaudeDo Task Manager");
                 progress.Report($"Created Desktop shortcut: {desktopPath}");
             }
 
@@ -44,48 +41,5 @@ public sealed class CreateShortcutsStep : IInstallStep
         }
     }
 
-    private static void CreateShortcut(string shortcutPath, string targetPath, string workingDir, string description)
-    {
-        var link = (IShellLink)new ShellLink();
-        link.SetPath(targetPath);
-        link.SetWorkingDirectory(workingDir);
-        link.SetDescription(description);
-        link.SetIconLocation(targetPath, 0);
 
-        var file = (IPersistFile)link;
-        file.Save(shortcutPath, false);
-    }
-
-    #region COM Interop for IShellLink
-
-    [ComImport]
-    [Guid("00021401-0000-0000-C000-000000000046")]
-    private class ShellLink { }
-
-    [ComImport]
-    [InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
-    [Guid("000214F9-0000-0000-C000-000000000046")]
-    private interface IShellLink
-    {
-        void GetPath([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder pszFile, int cchMaxPath, IntPtr pfd, int fFlags);
-        void GetIDList(out IntPtr ppidl);
-        void SetIDList(IntPtr pidl);
-        void GetDescription([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder pszName, int cchMaxName);
-        void SetDescription([MarshalAs(UnmanagedType.LPWStr)] string pszName);
-        void GetWorkingDirectory([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder pszDir, int cchMaxPath);
-        void SetWorkingDirectory([MarshalAs(UnmanagedType.LPWStr)] string pszDir);
-        void GetArguments([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder pszArgs, int cchMaxPath);
-        void SetArguments([MarshalAs(UnmanagedType.LPWStr)] string pszArgs);
-        void GetHotkey(out short pwHotkey);
-        void SetHotkey(short wHotkey);
-        void GetShowCmd(out int piShowCmd);
-        void SetShowCmd(int iShowCmd);
-        void GetIconLocation([Out, MarshalAs(UnmanagedType.LPWStr)] StringBuilder pszIconPath, int cchIconPath, out int piIcon);
-        void SetIconLocation([MarshalAs(UnmanagedType.LPWStr)] string pszIconPath, int iIcon);
-        void SetRelativePath([MarshalAs(UnmanagedType.LPWStr)] string pszPathRel, int dwReserved);
-        void Resolve(IntPtr hwnd, int fFlags);
-        void SetPath([MarshalAs(UnmanagedType.LPWStr)] string pszFile);
-    }
-
-    #endregion
 }

src/ClaudeDo.Installer/Steps/RegisterAutostartStep.cs

@@ -1,12 +1,11 @@
 using System.IO;
-using System.Security.Principal;
 using ClaudeDo.Installer.Core;
 
 namespace ClaudeDo.Installer.Steps;
 
 public sealed class RegisterAutostartStep : IInstallStep
 {
-    public const string TaskName = "ClaudeDoWorker";
+    public const string LegacyTaskName = "ClaudeDoWorker";
     private const string LegacyServiceName = "ClaudeDoWorker";
 
     public string Name => "Register Autostart";
@@ -34,24 +33,19 @@ public sealed class RegisterAutostartStep : IInstallStep
             }
         }
 
-        // 2) Register (or replace) the per-user logon task.
-        var userId = WindowsIdentity.GetCurrent().Name;
-        var minutes = Math.Max(1, ctx.RestartDelayMs / 60000);
-        var xml = ScheduledTaskXml.Build(userId, workerExe, minutes);
+        // 2) Migrate away the legacy logon scheduled task if present (best-effort).
+        progress.Report("Removing legacy logon task...");
+        await ProcessRunner.RunAsync("schtasks.exe", $"/Delete /TN \"{LegacyTaskName}\" /F", null, progress, ct);
 
-        var xmlPath = Path.Combine(Path.GetTempPath(), $"ClaudeDoWorker-{Guid.NewGuid():N}.xml");
-        await File.WriteAllTextAsync(xmlPath, xml, new System.Text.UnicodeEncoding(false, true), ct);
+        // 3) Register per-user autostart via a Startup-folder shortcut.
+        progress.Report("Creating Startup shortcut...");
         try
         {
-            progress.Report("Registering logon task...");
-            var (exit, output) = await ProcessRunner.RunAsync(
-                "schtasks.exe", $"/Create /TN \"{TaskName}\" /XML \"{xmlPath}\" /F", null, progress, ct);
-            if (exit != 0)
-                return StepResult.Fail($"schtasks /Create failed (exit {exit}): {output}");
+            AutostartShortcut.Install(AutostartShortcut.DefaultStartupDir, workerExe);
         }
-        finally
+        catch (Exception ex)
         {
-            try { File.Delete(xmlPath); } catch { /* best effort */ }
+            return StepResult.Fail($"Failed to create Startup shortcut: {ex.Message}");
         }
 
         return StepResult.Ok();

src/ClaudeDo.Installer/Steps/StartWorkerStep.cs

@@ -1,19 +1,28 @@
+using System.Diagnostics;
+using System.IO;
 using ClaudeDo.Installer.Core;
 
 namespace ClaudeDo.Installer.Steps;
 
 public sealed class StartWorkerStep : IInstallStep
 {
-    public const string TaskName = "ClaudeDoWorker";
-
     public string Name => "Start Worker";
 
-    public async Task<StepResult> ExecuteAsync(InstallContext ctx, IProgress<string> progress, CancellationToken ct)
+    public Task<StepResult> ExecuteAsync(InstallContext ctx, IProgress<string> progress, CancellationToken ct)
     {
+        var workerExe = Path.Combine(ctx.InstallDirectory, "worker", "ClaudeDo.Worker.exe");
+        if (!File.Exists(workerExe))
+            return Task.FromResult(StepResult.Fail($"Worker executable not found: {workerExe}"));
+
         progress.Report("Starting worker...");
-        var (exit, output) = await ProcessRunner.RunAsync("schtasks.exe", $"/Run /TN \"{TaskName}\"", null, progress, ct);
-        if (exit != 0)
-            return StepResult.Fail($"schtasks /Run failed (exit {exit}): {output}");
-        return StepResult.Ok();
+        try
+        {
+            Process.Start(new ProcessStartInfo(workerExe) { UseShellExecute = true });
+            return Task.FromResult(StepResult.Ok());
+        }
+        catch (Exception ex)
+        {
+            return Task.FromResult(StepResult.Fail($"Failed to start worker: {ex.Message}"));
+        }
     }
 }

src/ClaudeDo.Installer/Steps/StopWorkerStep.cs

@@ -6,16 +6,13 @@ namespace ClaudeDo.Installer.Steps;
 
 public sealed class StopWorkerStep : IInstallStep
 {
-    public const string TaskName = "ClaudeDoWorker";
+    public const string LegacyTaskName = "ClaudeDoWorker";
     public const string ProcessName = "ClaudeDo.Worker";
 
     public string Name => "Stop Worker";
 
     public async Task<StepResult> ExecuteAsync(InstallContext ctx, IProgress<string> progress, CancellationToken ct)
     {
-        progress.Report("Stopping worker task (if running)...");
-        await ProcessRunner.RunAsync("schtasks.exe", $"/End /TN \"{TaskName}\"", null, progress, ct);
-
         progress.Report("Stopping worker process (if running)...");
         var installDir = ctx.InstallDirectory;
         foreach (var p in Process.GetProcessesByName(ProcessName))

src/ClaudeDo.Ui/ViewModels/IslandsShellViewModel.cs

@@ -51,6 +51,9 @@ public sealed partial class IslandsShellViewModel : ViewModelBase
     // Set by MainWindow to open the global worktrees overview dialog.
     public Func<WorktreesOverviewModalViewModel, Task>? ShowWorktreesOverviewModal { get; set; }
 
+    // Set by MainWindow to open the worker-connection help dialog.
+    public Func<WorkerConnectionModalViewModel, Task>? ShowWorkerConnectionModal { get; set; }
+
     [ObservableProperty] private bool _isUpdateBannerVisible;
     [ObservableProperty] private string? _updateBannerLatestVersion;
     [ObservableProperty] private string? _inlineUpdateStatus;
@@ -72,6 +75,7 @@ public sealed partial class IslandsShellViewModel : ViewModelBase
     public bool ShowLists => WindowWidth >= 780;
 
     private readonly System.Timers.Timer _clearTimer = new(30_000) { AutoReset = false };
+    private readonly System.Timers.Timer _connectTimer = new(12_000) { AutoReset = false };
 
     [ObservableProperty] private string? _primeStatus;
     private readonly System.Timers.Timer _primeStatusTimer = new(5_000) { AutoReset = false };
@@ -220,8 +224,12 @@ public sealed partial class IslandsShellViewModel : ViewModelBase
         };
         _primeStatusTimer.Elapsed += (_, _) =>
             Avalonia.Threading.Dispatcher.UIThread.Post(() => PrimeStatus = null);
+        _connectTimer.Elapsed += (_, _) => Dispatcher.UIThread.Post(() =>
+        {
+            if (DecideShowConnectionPrompt(IsOffline)) _ = OpenWorkerConnectionHelpAsync();
+        });
+        _connectTimer.Start();
         _ = Lists.LoadAsync();
-        _ = EnsureWorkerRunningAsync();
         _updateCheck.PropertyChanged += (_, e) =>
         {
             if (e.PropertyName == nameof(UpdateCheckService.LastCheckStatus))
@@ -270,6 +278,25 @@ public sealed partial class IslandsShellViewModel : ViewModelBase
         if (ShowAboutModal is not null) await ShowAboutModal(vm);
     }
 
+    private bool _connectionPromptShown;
+
+    internal bool DecideShowConnectionPrompt(bool isOffline)
+    {
+        if (!isOffline) return false;
+        if (_connectionPromptShown) return false;
+        _connectionPromptShown = true;
+        return true;
+    }
+
+    private async Task OpenWorkerConnectionHelpAsync()
+    {
+        var vm = new WorkerConnectionModalViewModel(_workerLocator, _installerLocator);
+        if (ShowWorkerConnectionModal is not null) await ShowWorkerConnectionModal(vm);
+    }
+
+    [RelayCommand]
+    private Task OpenWorkerConnectionHelp() => OpenWorkerConnectionHelpAsync();
+
     [RelayCommand]
     private async Task OpenRepoImport()
     {
@@ -305,20 +332,6 @@ public sealed partial class IslandsShellViewModel : ViewModelBase
 
     [ObservableProperty] private string? _restartWorkerStatus;
 
-    private bool _ensureRunningAttempted;
-
-    private async Task EnsureWorkerRunningAsync()
-    {
-        if (_ensureRunningAttempted) return;
-        _ensureRunningAttempted = true;
-        await Task.Delay(TimeSpan.FromSeconds(4));
-        if (Worker?.IsConnected == true) return;
-        var exe = _workerLocator.Find();
-        if (exe is null) return;
-        try { System.Diagnostics.Process.Start(new System.Diagnostics.ProcessStartInfo(exe) { UseShellExecute = true }); }
-        catch { /* logon task is the primary mechanism; this is a convenience */ }
-    }
-
     [RelayCommand]
     private async Task RestartWorkerAsync()
     {

src/ClaudeDo.Ui/ViewModels/Modals/WorkerConnectionModalViewModel.cs

@@ -0,0 +1,45 @@
+using System;
+using System.Diagnostics;
+using ClaudeDo.Ui.Services;
+using CommunityToolkit.Mvvm.Input;
+
+namespace ClaudeDo.Ui.ViewModels.Modals;
+
+public sealed partial class WorkerConnectionModalViewModel : ViewModelBase
+{
+    private readonly WorkerLocator _workerLocator;
+    private readonly InstallerLocator _installerLocator;
+
+    public WorkerConnectionModalViewModel(WorkerLocator workerLocator, InstallerLocator installerLocator)
+    {
+        _workerLocator = workerLocator;
+        _installerLocator = installerLocator;
+    }
+
+    public Action? CloseAction { get; set; }
+
+    [RelayCommand] private void Close() => CloseAction?.Invoke();
+
+    [RelayCommand]
+    private void StartWorker()
+    {
+        var exe = _workerLocator.Find();
+        if (exe is null) return;
+        try { Process.Start(new ProcessStartInfo(exe) { UseShellExecute = true }); }
+        catch { /* nothing useful to show */ }
+        CloseAction?.Invoke();
+    }
+
+    [RelayCommand]
+    private void RerunInstaller()
+    {
+        var path = _installerLocator.Find();
+        if (path is null) return;
+        try
+        {
+            Process.Start(new ProcessStartInfo(path) { UseShellExecute = true });
+            Environment.Exit(0);
+        }
+        catch { /* nothing useful to show */ }
+    }
+}

src/ClaudeDo.Ui/Views/MainWindow.axaml

@@ -186,20 +186,24 @@
             BorderBrush="{DynamicResource LineBrush}"
             BorderThickness="0,1,0,0">
       <DockPanel LastChildFill="True" Margin="14,0">
-        <!-- Left: connection pill -->
-        <StackPanel DockPanel.Dock="Left" Orientation="Horizontal" Spacing="7"
-                    VerticalAlignment="Center">
-          <Ellipse Width="7" Height="7" Fill="{DynamicResource StatusRunningBrush}"
-                   IsVisible="{Binding Worker.IsConnected}"/>
-          <Ellipse Width="7" Height="7" Fill="{DynamicResource StatusReviewBrush}"
-                   IsVisible="{Binding Worker.IsReconnecting}"/>
-          <Ellipse Width="7" Height="7" Fill="{DynamicResource StatusErrorBrush}"
-                   IsVisible="{Binding IsOffline}"/>
-          <TextBlock Classes="eyebrow"
-                     Text="{Binding ConnectionText, Converter={StaticResource UpperCase}}"
-                     LetterSpacing="1.4"
-                     VerticalAlignment="Center"/>
-        </StackPanel>
+        <!-- Left: connection pill (click to open worker help) -->
+        <Button DockPanel.Dock="Left"
+                Command="{Binding OpenWorkerConnectionHelpCommand}"
+                Background="Transparent" BorderThickness="0" Padding="0"
+                Cursor="Hand" VerticalAlignment="Center">
+          <StackPanel Orientation="Horizontal" Spacing="7" VerticalAlignment="Center">
+            <Ellipse Width="7" Height="7" Fill="{DynamicResource StatusRunningBrush}"
+                     IsVisible="{Binding Worker.IsConnected}"/>
+            <Ellipse Width="7" Height="7" Fill="{DynamicResource StatusReviewBrush}"
+                     IsVisible="{Binding Worker.IsReconnecting}"/>
+            <Ellipse Width="7" Height="7" Fill="{DynamicResource StatusErrorBrush}"
+                     IsVisible="{Binding IsOffline}"/>
+            <TextBlock Classes="eyebrow"
+                       Text="{Binding ConnectionText, Converter={StaticResource UpperCase}}"
+                       LetterSpacing="1.4"
+                       VerticalAlignment="Center"/>
+          </StackPanel>
+        </Button>
 
         <!-- Right: worker log line -->
         <TextBlock DockPanel.Dock="Right"

src/ClaudeDo.Ui/Views/MainWindow.axaml.cs

@@ -68,6 +68,12 @@ public partial class MainWindow : Window
                 modal.CloseAction = () => dlg.Close();
                 await dlg.ShowDialog(this);
             };
+            vm.ShowWorkerConnectionModal = async (connVm) =>
+            {
+                var dlg = new WorkerConnectionModalView { DataContext = connVm };
+                connVm.CloseAction = () => dlg.Close();
+                await dlg.ShowDialog(this);
+            };
         }
     }
 

src/ClaudeDo.Ui/Views/Modals/WorkerConnectionModalView.axaml

@@ -0,0 +1,29 @@
+<Window xmlns="https://github.com/avaloniaui"
+        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+        xmlns:vm="using:ClaudeDo.Ui.ViewModels.Modals"
+        xmlns:ctl="using:ClaudeDo.Ui.Views.Controls"
+        x:Class="ClaudeDo.Ui.Views.Modals.WorkerConnectionModalView"
+        x:DataType="vm:WorkerConnectionModalViewModel"
+        Title="Worker not reachable"
+        Width="520" Height="240"
+        WindowDecorations="None"
+        ExtendClientAreaToDecorationsHint="True"
+        WindowStartupLocation="CenterOwner"
+        Background="{DynamicResource SurfaceBrush}">
+  <Window.KeyBindings>
+    <KeyBinding Gesture="Escape" Command="{Binding CloseCommand}"/>
+  </Window.KeyBindings>
+
+  <ctl:ModalShell Title="WORKER NOT REACHABLE" CloseCommand="{Binding CloseCommand}">
+    <Grid RowDefinitions="*,Auto" Margin="20,16">
+      <TextBlock Grid.Row="0" Classes="meta" TextWrapping="Wrap"
+                 Text="ClaudeDo can't reach the background worker. It is normally started automatically at logon. You can start it now, or reinstall if the problem persists."/>
+      <StackPanel Grid.Row="1" Orientation="Horizontal" Spacing="8"
+                  HorizontalAlignment="Right" Margin="0,16,0,0">
+        <Button Classes="btn" Content="Dismiss" Command="{Binding CloseCommand}"/>
+        <Button Classes="btn" Content="Rerun Installer" Command="{Binding RerunInstallerCommand}"/>
+        <Button Classes="btn primary" Content="Start Worker" Command="{Binding StartWorkerCommand}"/>
+      </StackPanel>
+    </Grid>
+  </ctl:ModalShell>
+</Window>

src/ClaudeDo.Ui/Views/Modals/WorkerConnectionModalView.axaml.cs

@@ -0,0 +1,10 @@
+using Avalonia.Controls;
+using Avalonia.Markup.Xaml;
+
+namespace ClaudeDo.Ui.Views.Modals;
+
+public partial class WorkerConnectionModalView : Window
+{
+    public WorkerConnectionModalView() => InitializeComponent();
+    private void InitializeComponent() => AvaloniaXamlLoader.Load(this);
+}

tests/ClaudeDo.Installer.Tests/AutostartShortcutTests.cs

@@ -0,0 +1,57 @@
+using System.IO;
+using ClaudeDo.Installer.Core;
+
+namespace ClaudeDo.Installer.Tests;
+
+public class AutostartShortcutTests
+{
+    private static string TempDir()
+    {
+        var dir = Path.Combine(Path.GetTempPath(), "cdautostart-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(dir);
+        return dir;
+    }
+
+    [Fact]
+    public void Install_creates_lnk_with_expected_name()
+    {
+        var startup = TempDir();
+        var workerDir = TempDir();
+        try
+        {
+            var workerExe = Path.Combine(workerDir, "ClaudeDo.Worker.exe");
+            File.WriteAllText(workerExe, "");
+
+            AutostartShortcut.Install(startup, workerExe);
+
+            Assert.True(File.Exists(Path.Combine(startup, AutostartShortcut.FileName)));
+        }
+        finally { Directory.Delete(startup, true); Directory.Delete(workerDir, true); }
+    }
+
+    [Fact]
+    public void Remove_deletes_existing_lnk()
+    {
+        var startup = TempDir();
+        var workerDir = TempDir();
+        try
+        {
+            var workerExe = Path.Combine(workerDir, "ClaudeDo.Worker.exe");
+            File.WriteAllText(workerExe, "");
+            AutostartShortcut.Install(startup, workerExe);
+
+            AutostartShortcut.Remove(startup);
+
+            Assert.False(File.Exists(Path.Combine(startup, AutostartShortcut.FileName)));
+        }
+        finally { Directory.Delete(startup, true); Directory.Delete(workerDir, true); }
+    }
+
+    [Fact]
+    public void Remove_is_noop_when_missing()
+    {
+        var startup = TempDir();
+        try { AutostartShortcut.Remove(startup); } // must not throw
+        finally { Directory.Delete(startup, true); }
+    }
+}

tests/ClaudeDo.Installer.Tests/ScheduledTaskXmlTests.cs

@@ -1,30 +0,0 @@
-using ClaudeDo.Installer.Core;
-
-namespace ClaudeDo.Installer.Tests;
-
-public class ScheduledTaskXmlTests
-{
-    [Fact]
-    public void Build_EmbedsUserExeAndLogonTrigger()
-    {
-        var xml = ScheduledTaskXml.Build(
-            userId: "MACHINE\\mika",
-            workerExePath: @"C:\Program Files\ClaudeDo\worker\ClaudeDo.Worker.exe",
-            restartIntervalMinutes: 1);
-
-        Assert.Contains("<LogonTrigger>", xml);
-        Assert.Contains("<UserId>MACHINE\\mika</UserId>", xml);
-        Assert.Contains("<LogonType>InteractiveToken</LogonType>", xml);
-        Assert.Contains("<Hidden>true</Hidden>", xml);
-        Assert.Contains("<RunLevel>LeastPrivilege</RunLevel>", xml);
-        Assert.Contains(@"C:\Program Files\ClaudeDo\worker\ClaudeDo.Worker.exe", xml);
-        Assert.Contains("<Interval>PT1M</Interval>", xml);
-    }
-
-    [Fact]
-    public void Build_ClampsRestartIntervalToOneMinuteMinimum()
-    {
-        var xml = ScheduledTaskXml.Build("M\\u", @"C:\w.exe", restartIntervalMinutes: 0);
-        Assert.Contains("<Interval>PT1M</Interval>", xml);
-    }
-}

tests/ClaudeDo.Installer.Tests/ShortcutFactoryTests.cs

@@ -0,0 +1,25 @@
+using System.IO;
+using ClaudeDo.Installer.Core;
+
+namespace ClaudeDo.Installer.Tests;
+
+public class ShortcutFactoryTests
+{
+    [Fact]
+    public void CreateShortcut_writes_lnk_file()
+    {
+        var dir = Path.Combine(Path.GetTempPath(), "cdshortcut-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(dir);
+        try
+        {
+            var target = Path.Combine(dir, "fake.exe");
+            File.WriteAllText(target, "");
+            var lnk = Path.Combine(dir, "x.lnk");
+
+            ShortcutFactory.CreateShortcut(lnk, target, dir, "desc");
+
+            Assert.True(File.Exists(lnk));
+        }
+        finally { Directory.Delete(dir, recursive: true); }
+    }
+}

tests/ClaudeDo.Ui.Tests/ConnectionPromptGateTests.cs

@@ -0,0 +1,22 @@
+using ClaudeDo.Ui.ViewModels;
+using Xunit;
+
+namespace ClaudeDo.Ui.Tests;
+
+public class ConnectionPromptGateTests
+{
+    [Fact]
+    public void Shows_once_when_offline()
+    {
+        var vm = new IslandsShellViewModel();
+        Assert.True(vm.DecideShowConnectionPrompt(isOffline: true));
+        Assert.False(vm.DecideShowConnectionPrompt(isOffline: true)); // not a second time
+    }
+
+    [Fact]
+    public void Does_not_show_when_connected_before_grace()
+    {
+        var vm = new IslandsShellViewModel();
+        Assert.False(vm.DecideShowConnectionPrompt(isOffline: false));
+    }
+}