From fac6a2c025d352323a8418179a5e12714dd0ae19 Mon Sep 17 00:00:00 2001
From: Alexey Zimarev <alex@zimarev.com>
Date: Wed, 10 Jun 2026 16:43:27 +0200
Subject: [PATCH 01/16] docs: spec for daemon service supervisor
 (install/uninstall/start/stop)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per-user OS service integration so the daemon auto-restarts after an
external SIGKILL (jetsam/OOM/crash) — the root cause traced on 2026-06-10:
exit 137 with zero death-rattle output = uncatchable kill, reproduced under
detached tmux during a memory-pressure jetsam storm.

launchd LaunchAgent (macOS), systemd --user unit (Linux), Task Scheduler
logon task (Windows), behind an IServiceManager seam with pure unit-text
generators for testing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...-06-10-daemon-service-supervisor-design.md | 282 ++++++++++++++++++
 1 file changed, 282 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-10-daemon-service-supervisor-design.md

diff --git a/docs/superpowers/specs/2026-06-10-daemon-service-supervisor-design.md b/docs/superpowers/specs/2026-06-10-daemon-service-supervisor-design.md
new file mode 100644
index 000000000..e92569bb2
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-10-daemon-service-supervisor-design.md
@@ -0,0 +1,282 @@
+# Daemon service supervisor (install/uninstall/start/stop)
+
+## Problem
+
+The `kcap` daemon is a long-running process, but nothing supervises it. Users
+run it via `kcap daemon start -d` (a one-shot detached spawn) or under tmux, and
+neither survives the process dying.
+
+A debugging session on 2026-06-10 traced a recurring "daemon crashes silently"
+report to its root cause: the daemon exits with code **137 (SIGKILL)** and the
+`death-rattle` instrumentation emits **nothing** — proving the kill comes from
+*outside* the .NET runtime and is uncatchable in-process. The evidence:
+
+- Exit 137 = 128 + 9 (SIGKILL).
+- Zero `[death-rattle]` lines in 4001 log lines (no managed handler ran).
+- The daemon was **idle for 49 minutes** before the kill, so nothing it did
+  triggered it.
+- The macOS unified log showed a `JETSAM_REASON_MEMORY_IDLE_EXIT` storm at the
+  same time (launchd SIGKILLing dozens of idle processes), driven by a
+  concurrent heavy `dotnet` build/test run spiking memory pressure.
+- It happened under **detached tmux**, which falsified the earlier "Warp block
+  recycling" hypothesis — tmux only shields against terminal-driven signals
+  (SIGHUP/SIGTERM), not kernel memory reclamation (jetsam) or the Linux OOM
+  killer.
+
+**There is no in-process fix** — you cannot survive SIGKILL. The fix is
+operational resilience: run the daemon under a real per-user service supervisor
+that auto-restarts it after any death (jetsam, OOM, crash, logout/login), on all
+three platforms.
+
+## Scope
+
+Add a `service` command group under `kcap daemon` that registers, deregisters,
+and controls the daemon as a **per-user** OS service:
+
+```
+kcap daemon service install   [--name N] [--max-agents N] [--server-url URL] [--no-start]
+kcap daemon service uninstall [--name N]
+kcap daemon service start     [--name N]
+kcap daemon service stop      [--name N]
+kcap daemon service status    [--name N]
+```
+
+Per-user / login-session scope on every platform:
+
+| Platform | Mechanism | Unit location |
+|---|---|---|
+| macOS | launchd **LaunchAgent** | `~/Library/LaunchAgents/io.kurrent.kcap.daemon[.<name>].plist` |
+| Linux | systemd **`--user`** unit (templated) | `~/.config/systemd/user/kcap-daemon@.service` |
+| Windows | Task Scheduler **logon task** | task `kcap-daemon[-<name>]` |
+
+The existing ad-hoc lifecycle (`kcap daemon start [-d]`, `stop`, `status`,
+`logs`, `doctor`) is **unchanged**. Service management is additive.
+
+### Out of scope (explicitly deferred)
+
+- **System-wide / boot scope** (LaunchDaemon, systemd system unit, true Windows
+  Service running as SYSTEM). Rejected: the daemon needs the user's `$HOME`,
+  resolved kcap profile, login keychain, and an interactive session to spawn
+  Claude/Codex PTY agents. A session-0 service breaks PTY agent spawning.
+- **systemd linger** (`loginctl enable-linger`) so the unit runs while logged
+  out. Per-user/login scope means "stops at logout" is acceptable; a future
+  `--linger` flag can add it.
+- **Auto-reinstall on `npm update`.** The platform-package binary path is stable
+  across updates; `daemon doctor` will flag a unit whose binary path no longer
+  exists (see below).
+
+## Architecture
+
+### `IServiceManager` seam (in `Capacitor.Cli`)
+
+Lives in `Capacitor.Cli` (not `Capacitor.Cli.Core`): its only consumer is
+`DaemonCommands` (Cli), and the side-effecting apply uses `ProcessHelpers`
+(Cli) — Core must not depend on Cli. `Capacitor.Cli.Tests.Unit` already
+references the Cli project and tests Cli-project classes, so this is unit-testable.
+Mirrors the existing interface seams in the codebase (`IPtyProcessFactory`,
+`IHostedAgentLauncher`). Each implementation splits a **pure unit-text
+generator** (testable) from a **thin side-effecting apply** (shells out to the
+platform tool).
+
+```csharp
+public record ServiceSpec(
+    string Name,
+    string DaemonBinaryPath,           // absolute path to kcap-daemon, resolved at install
+    string LogPath,                    // stable log file passed as --log-file
+    IReadOnlyList<string> ExtraArgs);  // optional baked overrides (--max-agents, --server-url)
+
+public enum ServiceState { NotInstalled, Installed, Running }
+
+public interface IServiceManager {
+    string  Describe();                     // e.g. "launchd LaunchAgent"
+    string  GenerateUnit(ServiceSpec spec); // PURE — the primary tested seam
+    ServiceState Status(string name);
+    void    Install(ServiceSpec spec, bool startNow);
+    void    Uninstall(string name);
+    void    Start(string name);
+    void    Stop(string name);
+}
+```
+
+Selection:
+
+```csharp
+public static class ServiceManagerFactory {
+    public static IServiceManager ForCurrentOs(); // Launchd | Systemd | WindowsScheduledTask
+                                                   // throws PlatformNotSupportedException otherwise
+}
+```
+
+Implementations: `LaunchdServiceManager`, `SystemdServiceManager`,
+`WindowsScheduledTaskServiceManager`.
+
+### What the unit runs
+
+The unit execs the **`kcap-daemon` binary directly** — the OS service manager is
+the sole supervisor (no `kcap daemon start` CLI layer, no PID-file dance; the
+daemon's own `flock` still prevents duplicate names).
+
+The unit **pins only**:
+
+- `--name <name>` — must be deterministic so it matches the `flock` slot.
+- `--log-file <path>` — stable log location (`daemon.log`, or
+  `daemon-<name>.log` for a named instance), via `PathHelpers.ConfigPath`.
+
+Everything else (`server-url`, `max-agents`, claude/codex paths) keeps resolving
+from the active profile + env **at each launch** — `DaemonRunner.RunAsync`
+already does `AppConfig.ResolveActiveProfile(args)` and reads these from the
+resolved profile. So editing the profile does **not** require a reinstall.
+`--max-agents` / `--server-url` on `install` are optional overrides baked into
+`ExtraArgs` for users who want them frozen.
+
+### Restart semantics (the subtle part)
+
+Restart must fire on **crash / SIGKILL** (jetsam, OOM) but **not** on a clean
+stop or clean exit. All three managers distinguish a *failure* from a deliberate
+*stop*:
+
+| Platform | Restart-on-failure config | Clean stop (no restart) |
+|---|---|---|
+| launchd | `KeepAlive = { SuccessfulExit = false }` | `launchctl kill SIGTERM` → daemon cooperatively exits 0 → not restarted |
+| systemd | `Restart=on-failure`, `RestartSec=5` | `systemctl --user stop` → systemd knows it's a stop, not a failure |
+| schtasks | task settings `RestartCount` + `RestartInterval=PT1M` | `schtasks /End` → terminated, not a failure exit |
+
+A SIGKILL is an abnormal exit on all three → it **does** restart (the jetsam/OOM
+case we are fixing). A `service stop` keeps the unit installed but down; it
+returns at next login (launchd `RunAtLoad`, systemd still `enable`d) or via
+`service start`. Only `service uninstall` deregisters.
+
+### Per-verb → platform command mapping
+
+| verb | macOS | Linux | Windows |
+|---|---|---|---|
+| install | write plist; `launchctl bootstrap gui/<uid> <plist>` (`RunAtLoad` starts it); follow with `launchctl kill SIGTERM` if `--no-start` | write unit; `systemctl --user daemon-reload`; `enable --now kcap-daemon@<name>` (or `enable` only if `--no-start`) | `schtasks /Create /TN <task> /XML <f> /F`; `/Run` unless `--no-start` |
+| uninstall | `launchctl bootout gui/<uid>/<label>`; delete plist | `systemctl --user disable --now kcap-daemon@<name>`; delete unit; `daemon-reload` | `schtasks /Delete /TN <task> /F` |
+| start | `launchctl kickstart gui/<uid>/<label>` (bootstrap first if not loaded) | `systemctl --user start kcap-daemon@<name>` | `schtasks /Run /TN <task>` |
+| stop | `launchctl kill SIGTERM gui/<uid>/<label>` | `systemctl --user stop kcap-daemon@<name>` | `schtasks /End /TN <task>` |
+| status | `launchctl print gui/<uid>/<label>` (exit code → state) | `systemctl --user is-active / is-enabled` | `schtasks /Query /TN <task> /FO LIST` |
+
+`<uid>` = `Environment.GetEnvironmentVariable("UID")` fallback `id -u`; `<label>`
+= `io.kurrent.kcap.daemon[.<name>]`.
+
+### macOS plist (generated)
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>              <string>io.kurrent.kcap.daemon.<name></string>
+  <key>ProgramArguments</key>   <array>
+    <string>/abs/path/kcap-daemon</string>
+    <string>--name</string>     <string><name></string>
+    <string>--log-file</string> <string>/Users/<u>/.config/kcap/daemon-<name>.log</string>
+  </array>
+  <key>RunAtLoad</key>          <true/>
+  <key>KeepAlive</key>          <dict><key>SuccessfulExit</key><false/></dict>
+  <key>ProcessType</key>        <string>Adaptive</string>
+  <key>StandardOutPath</key>    <string>…/daemon-<name>.log</string>
+  <key>StandardErrorPath</key>  <string>…/daemon-<name>.log</string>
+</dict>
+</plist>
+```
+
+launchd's default `ThrottleInterval` (10s) is the crash-loop guard.
+
+### Linux systemd templated unit (generated)
+
+```ini
+[Unit]
+Description=kcap daemon (%i)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=/abs/path/kcap-daemon --name %i --log-file %h/.config/kcap/daemon-%i.log
+Restart=on-failure
+RestartSec=5
+StartLimitIntervalSec=60
+StartLimitBurst=5
+
+[Install]
+WantedBy=default.target
+```
+
+Instance name `%i` = the daemon `--name`. `kcap daemon service install --name X`
+operates on `kcap-daemon@X.service`.
+
+### Windows Task Scheduler XML (generated)
+
+Logon trigger for the current user; action runs `kcap-daemon.exe --name … --log-file …`;
+settings: `MultipleInstances=IgnoreNew`, `ExecutionTimeLimit=PT0S` (unlimited),
+`DisallowStartIfOnBatteries=false`, `StopIfGoingOnBatteries=false`,
+`StartWhenAvailable=true`, restart-on-failure (`RestartCount=999`,
+`RestartInterval=PT1M`). Registered via `schtasks /Create /XML` (avoids
+PowerShell quoting; XML is a pure generated string).
+
+### Integration with existing commands
+
+- **`kcap daemon status`** gains a `service:` line per name — `not installed` /
+  `installed (launchd LaunchAgent, runs at login)` / `installed, running` — from
+  `IServiceManager.Status`.
+- **`kcap daemon stop`** (ad-hoc) becomes service-aware: if a unit exists for the
+  name it does **not** raw-kill (which the supervisor would just restart);
+  instead it prints guidance to use `kcap daemon service stop --name N`.
+- **`kcap daemon doctor`** gains a check: for each installed unit, verify the
+  baked `DaemonBinaryPath` still exists; if not, report it and suggest
+  `kcap daemon service install` to refresh the path (covers a moved npm prefix).
+
+## Binary path resolution
+
+`install` resolves the absolute `kcap-daemon` path via the existing
+`ResolveDaemonBinary()` (sibling of the running `kcap` binary) and writes it into
+the unit. The npm platform-package path
+(`…/@kurrent/kcap-<rid>/bin/kcap-daemon`) is stable across `npm update`, so units
+survive upgrades. A prefix change requires `service install` again — surfaced by
+`daemon doctor`, not silently broken.
+
+## Testing
+
+- **Pure generators** (`GenerateUnit`) per OS: TUnit tests assert the output
+  contains the absolute binary path, pinned `--name`/`--log-file` args, the
+  correct label / `@%i` instance / task name, and the restart keys
+  (`KeepAlive`/`Restart=on-failure`/`RestartCount`). Deterministic strings, no OS
+  calls.
+- **Command-vector builders** (the `launchctl`/`systemctl`/`schtasks` argument
+  lists for each verb) are pure helpers → asserted directly.
+- **`ServiceManagerFactory.ForCurrentOs()`** returns the right type per
+  `OperatingSystem.Is*`, throws `PlatformNotSupportedException` otherwise.
+- The thin `Install/Uninstall/Start/Stop` shell-outs are **not** run in CI
+  (can't register real units); they are kept trivial (build vector → run via
+  existing `ProcessHelpers`).
+
+## AOT
+
+AOT-safe throughout: hand-built unit strings (no XML/JSON reflection
+serialization), `Process` shell-out, plain file I/O. Verify with
+`dotnet publish -c Release` and the IL3050/IL2026 grep per CLAUDE.md.
+
+## Docs (same PR — CLAUDE.md mandate)
+
+- `src/Capacitor.Cli.Core/Resources/help-daemon.txt` — add the `service`
+  subcommand group and its options.
+- `README.md` — `## Getting started` gains a "keep the daemon alive" note
+  recommending `kcap daemon service install`; the `## CLI commands` daemon
+  section documents `service install/uninstall/start/stop/status`.
+
+## Files
+
+New:
+
+- `src/Capacitor.Cli/Services/IServiceManager.cs` (interface, `ServiceSpec`, `ServiceState`)
+- `src/Capacitor.Cli/Services/ServiceManagerFactory.cs`
+- `src/Capacitor.Cli/Services/LaunchdServiceManager.cs`
+- `src/Capacitor.Cli/Services/SystemdServiceManager.cs`
+- `src/Capacitor.Cli/Services/WindowsScheduledTaskServiceManager.cs`
+- `test/Capacitor.Cli.Tests.Unit/Services/*ServiceManagerTests.cs`
+
+Modified:
+
+- `src/Capacitor.Cli/Commands/DaemonCommands.cs` — `service` subcommand dispatch; `status`/`stop`/`doctor` service-awareness
+- `src/Capacitor.Cli.Core/Resources/help-daemon.txt`
+- `README.md`

From 21fb091359dca16f524d6f3c798c6b64b9a700e0 Mon Sep 17 00:00:00 2001
From: Alexey Zimarev <alex@zimarev.com>
Date: Wed, 10 Jun 2026 16:57:11 +0200
Subject: [PATCH 02/16] docs: address spec review (env/profile, systemd
 per-instance, escaping)

Revise the daemon-service-supervisor spec for six review findings:

- systemd: per-instance kcap-daemon-<id>.service files instead of one shared
  @.service template (per-instance args + safe single-unit uninstall)
- pin profile via KCAP_PROFILE + capture PATH/KCAP_* into the unit instead of
  baking --server-url (which nulls profile resolution and drops claude/codex
  paths; supervised jobs don't inherit interactive PATH)
- sanitize the daemon name into a portable service id and XML/systemd-escape
  every interpolated value in generated unit text
- add ListInstalled()/ServiceStatus.BinaryPath so installed-but-stopped
  services show in status and doctor can validate the baked binary path
- define idempotent install (replace existing unit, end running)
- add ServiceManagerFactory.ForPlatform so all generators are testable on one OS

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...-06-10-daemon-service-supervisor-design.md | 287 ++++++++++++------
 1 file changed, 202 insertions(+), 85 deletions(-)

diff --git a/docs/superpowers/specs/2026-06-10-daemon-service-supervisor-design.md b/docs/superpowers/specs/2026-06-10-daemon-service-supervisor-design.md
index e92569bb2..3ae730167 100644
--- a/docs/superpowers/specs/2026-06-10-daemon-service-supervisor-design.md
+++ b/docs/superpowers/specs/2026-06-10-daemon-service-supervisor-design.md
@@ -34,23 +34,25 @@ Add a `service` command group under `kcap daemon` that registers, deregisters,
 and controls the daemon as a **per-user** OS service:
 
 ```
-kcap daemon service install   [--name N] [--max-agents N] [--server-url URL] [--no-start]
+kcap daemon service install   [--name N] [--profile P] [--max-agents N] [--no-start]
 kcap daemon service uninstall [--name N]
 kcap daemon service start     [--name N]
 kcap daemon service stop      [--name N]
 kcap daemon service status    [--name N]
 ```
 
-Per-user / login-session scope on every platform:
+Per-user / login-session scope on every platform, **one unit per service id**
+(no shared template):
 
 | Platform | Mechanism | Unit location |
 |---|---|---|
-| macOS | launchd **LaunchAgent** | `~/Library/LaunchAgents/io.kurrent.kcap.daemon[.<name>].plist` |
-| Linux | systemd **`--user`** unit (templated) | `~/.config/systemd/user/kcap-daemon@.service` |
-| Windows | Task Scheduler **logon task** | task `kcap-daemon[-<name>]` |
+| macOS | launchd **LaunchAgent** | `~/Library/LaunchAgents/io.kurrent.kcap.daemon.<id>.plist` |
+| Linux | systemd **`--user`** unit (one file per id) | `~/.config/systemd/user/kcap-daemon-<id>.service` |
+| Windows | Task Scheduler **logon task** | task `kcap-daemon-<id>` |
 
-The existing ad-hoc lifecycle (`kcap daemon start [-d]`, `stop`, `status`,
-`logs`, `doctor`) is **unchanged**. Service management is additive.
+`<id>` is the **sanitized** service id (see *Name handling*). The existing
+ad-hoc lifecycle (`kcap daemon start [-d]`, `stop`, `status`, `logs`, `doctor`)
+is **unchanged**. Service management is additive.
 
 ### Out of scope (explicitly deferred)
 
@@ -62,8 +64,34 @@ The existing ad-hoc lifecycle (`kcap daemon start [-d]`, `stop`, `status`,
   out. Per-user/login scope means "stops at logout" is acceptable; a future
   `--linger` flag can add it.
 - **Auto-reinstall on `npm update`.** The platform-package binary path is stable
-  across updates; `daemon doctor` will flag a unit whose binary path no longer
-  exists (see below).
+  across updates; `daemon doctor` flags a unit whose binary path no longer
+  exists (see below), and `service install` is idempotent so re-running it fixes
+  a moved path.
+
+## Name handling, service id, and escaping
+
+`DaemonNameResolver.Resolve` returns the raw `--name` verbatim — only
+`DaemonLockPaths.Sanitize` (filenames) restricts characters. A daemon name may
+therefore contain spaces or XML/shell metacharacters, which would otherwise be
+interpolated unescaped into plist / unit / Task XML and into the label / instance
+/ task id.
+
+Rules:
+
+1. **Service id** = `DaemonLockPaths.Sanitize(resolvedName)` — lowercase,
+   `[a-z0-9._-]` only, idempotent. This single id is used for the unit filename,
+   launchd `Label`, systemd unit name, Windows task name, **and the `--name`
+   value passed to the daemon**. Passing the sanitized id as `--name` keeps the
+   service id, the daemon's `flock` slot (`Sanitize` is applied again, no-op),
+   and what `kcap daemon status/stop` enumerate all consistent. `install` prints
+   the sanitized id when it differs from the input so the user isn't surprised.
+2. **Every interpolated value** (binary path, log path, env values, the id) is
+   escaped for its target format when generating unit text: XML-escape for plist
+   and Task XML; systemd value-escaping for `.service` lines. Generators never
+   concatenate raw strings into markup.
+
+This keeps the pure generators total (any input produces well-formed output) and
+is the focus of the escaping unit tests.
 
 ## Architecture
 
@@ -80,33 +108,50 @@ platform tool).
 
 ```csharp
 public record ServiceSpec(
-    string Name,
-    string DaemonBinaryPath,           // absolute path to kcap-daemon, resolved at install
-    string LogPath,                    // stable log file passed as --log-file
-    IReadOnlyList<string> ExtraArgs);  // optional baked overrides (--max-agents, --server-url)
+    string ServiceId,                              // sanitized id: filename/label/instance/task AND --name
+    string DaemonBinaryPath,                       // absolute path to kcap-daemon, resolved at install
+    string LogPath,                                // stable log file passed as --log-file
+    IReadOnlyDictionary<string,string> Environment,// captured env baked into the unit (see Environment)
+    IReadOnlyList<string> ExtraArgs);              // optional --max-agents override (NOT --server-url)
 
 public enum ServiceState { NotInstalled, Installed, Running }
 
+public record ServiceStatus(ServiceState State, string? BinaryPath);
+
 public interface IServiceManager {
-    string  Describe();                     // e.g. "launchd LaunchAgent"
-    string  GenerateUnit(ServiceSpec spec); // PURE — the primary tested seam
-    ServiceState Status(string name);
-    void    Install(ServiceSpec spec, bool startNow);
-    void    Uninstall(string name);
-    void    Start(string name);
-    void    Stop(string name);
+    string  Describe();                       // e.g. "launchd LaunchAgent"
+    string  GenerateUnit(ServiceSpec spec);   // PURE — the primary tested seam
+
+    IReadOnlyList<string> ListInstalled();    // service ids with a unit file on disk
+    ServiceStatus Status(string serviceId);   // state + baked binary path (for doctor)
+
+    void Install(ServiceSpec spec, bool startNow); // idempotent: replaces an existing unit
+    void Uninstall(string serviceId);
+    void Start(string serviceId);
+    void Stop(string serviceId);
 }
 ```
 
-Selection:
+`ListInstalled()` + `Status().BinaryPath` are what let `daemon status` show an
+**installed-but-stopped** service (which has no PID file) and let `daemon doctor`
+iterate installed units and validate the baked binary path.
+
+Selection (testable on any host):
 
 ```csharp
+public enum ServicePlatform { Launchd, Systemd, WindowsScheduledTask }
+
 public static class ServiceManagerFactory {
-    public static IServiceManager ForCurrentOs(); // Launchd | Systemd | WindowsScheduledTask
-                                                   // throws PlatformNotSupportedException otherwise
+    public static IServiceManager ForPlatform(ServicePlatform p); // construct any manager
+    public static IServiceManager ForCurrentOs();                 // detect via OperatingSystem.Is*,
+                                                                  // delegate to ForPlatform;
+                                                                  // throws PlatformNotSupportedException
 }
 ```
 
+`ForPlatform` is the seam that lets unit tests exercise all three generators on a
+single CI OS.
+
 Implementations: `LaunchdServiceManager`, `SystemdServiceManager`,
 `WindowsScheduledTaskServiceManager`.
 
@@ -116,18 +161,49 @@ The unit execs the **`kcap-daemon` binary directly** — the OS service manager
 the sole supervisor (no `kcap daemon start` CLI layer, no PID-file dance; the
 daemon's own `flock` still prevents duplicate names).
 
-The unit **pins only**:
-
-- `--name <name>` — must be deterministic so it matches the `flock` slot.
-- `--log-file <path>` — stable log location (`daemon.log`, or
-  `daemon-<name>.log` for a named instance), via `PathHelpers.ConfigPath`.
-
-Everything else (`server-url`, `max-agents`, claude/codex paths) keeps resolving
-from the active profile + env **at each launch** — `DaemonRunner.RunAsync`
-already does `AppConfig.ResolveActiveProfile(args)` and reads these from the
-resolved profile. So editing the profile does **not** require a reinstall.
-`--max-agents` / `--server-url` on `install` are optional overrides baked into
-`ExtraArgs` for users who want them frozen.
+The unit **pins**:
+
+- `--name <id>` — the sanitized service id (deterministic; matches the `flock`
+  slot and the service id).
+- `--log-file <path>` — stable log location (`daemon.log`, or `daemon-<id>.log`
+  for a named instance), via `PathHelpers.ConfigPath`.
+- optional `--max-agents N` (from `ExtraArgs`) when the user passes an explicit
+  override.
+
+Everything else resolves at each launch from the **pinned profile + captured
+env** (below), so editing the profile does not require a reinstall.
+
+### Profile + environment (why not `--server-url`)
+
+Two confirmed interactions in the current code make naïve baking wrong:
+
+1. **`--server-url` (and `KCAP_URL`) disable profile resolution.**
+   `ProfileResolver.Resolve` returns `Profile = null` whenever a CLI server-url
+   or `KCAP_URL` is set, so `DaemonRunner` then skips the profile's
+   `ClaudePath` / `CodexPath` / `MaxAgents`. Baking `--server-url` would silently
+   strip the daemon's agent-path config.
+2. **Supervised jobs don't inherit the interactive shell `PATH`.**
+   `CliResolver.Exists` walks `PATH` for bare `claude` / `codex`. launchd agents
+   and systemd `--user` units start with a minimal `PATH`, so vendor discovery
+   finds nothing and the daemon advertises no spawnable vendors.
+
+So instead of `--server-url`, `install`:
+
+- **Pins the profile by name** via `KCAP_PROFILE=<resolved profile name>` in the
+  unit environment. The daemon (which has no working dir, so repo/remote
+  resolution doesn't apply) then deterministically resolves the **full** profile
+  — server URL *and* `claude_path` / `codex_path` / `max_agents`. `--profile P`
+  overrides which profile is pinned; default is the currently-resolved profile
+  name. If no named profile resolves (server-url-only setup), fall back to baking
+  `KCAP_URL` and require absolute agent paths (next point).
+- **Captures environment** from the installing shell into the unit:
+  `PATH` (so bare `claude`/`codex` resolve exactly as they do in the terminal),
+  plus any set `KCAP_CONFIG_DIR`, `KCAP_PROFILE`, `KCAP_CLAUDE_PATH`,
+  `KCAP_CODEX_PATH`. Mechanism per platform: launchd `EnvironmentVariables` dict,
+  systemd `Environment=` lines, Windows tasks inherit the user env block but get
+  the same keys set for parity/determinism.
+- **`daemon doctor`** additionally warns when neither an absolute agent path nor
+  a `PATH` entry containing `claude`/`codex` is present in a unit's captured env.
 
 ### Restart semantics (the subtle part)
 
@@ -146,53 +222,82 @@ case we are fixing). A `service stop` keeps the unit installed but down; it
 returns at next login (launchd `RunAtLoad`, systemd still `enable`d) or via
 `service start`. Only `service uninstall` deregisters.
 
+### Install idempotency / reinstall
+
+`install` is **idempotent**: running it when a unit already exists replaces the
+unit and ends in the running state (unless `--no-start`), regardless of the prior
+running/stopped state. This is what makes `doctor`'s "re-run `service install` to
+refresh a moved binary path" well-defined.
+
+| Platform | Replace-existing behavior |
+|---|---|
+| launchd | `bootout` the old label (ignore "not loaded"), rewrite plist, `bootstrap`, then start unless `--no-start` |
+| systemd | rewrite unit, `daemon-reload`, `enable`, then `restart` (or `stop` if `--no-start`) |
+| Windows | `schtasks /Create … /F` overwrites in place, then `/Run` unless `--no-start` |
+
 ### Per-verb → platform command mapping
 
+`<uid>` = `id -u`; `<label>` = `io.kurrent.kcap.daemon.<id>`; `<unit>` =
+`kcap-daemon-<id>.service`; `<task>` = `kcap-daemon-<id>`.
+
 | verb | macOS | Linux | Windows |
 |---|---|---|---|
-| install | write plist; `launchctl bootstrap gui/<uid> <plist>` (`RunAtLoad` starts it); follow with `launchctl kill SIGTERM` if `--no-start` | write unit; `systemctl --user daemon-reload`; `enable --now kcap-daemon@<name>` (or `enable` only if `--no-start`) | `schtasks /Create /TN <task> /XML <f> /F`; `/Run` unless `--no-start` |
-| uninstall | `launchctl bootout gui/<uid>/<label>`; delete plist | `systemctl --user disable --now kcap-daemon@<name>`; delete unit; `daemon-reload` | `schtasks /Delete /TN <task> /F` |
-| start | `launchctl kickstart gui/<uid>/<label>` (bootstrap first if not loaded) | `systemctl --user start kcap-daemon@<name>` | `schtasks /Run /TN <task>` |
-| stop | `launchctl kill SIGTERM gui/<uid>/<label>` | `systemctl --user stop kcap-daemon@<name>` | `schtasks /End /TN <task>` |
-| status | `launchctl print gui/<uid>/<label>` (exit code → state) | `systemctl --user is-active / is-enabled` | `schtasks /Query /TN <task> /FO LIST` |
-
-`<uid>` = `Environment.GetEnvironmentVariable("UID")` fallback `id -u`; `<label>`
-= `io.kurrent.kcap.daemon[.<name>]`.
-
-### macOS plist (generated)
+| install | write plist; `launchctl bootout` (if present); `launchctl bootstrap gui/<uid> <plist>` (`RunAtLoad` starts it); `launchctl kill SIGTERM` if `--no-start` | write unit; `systemctl --user daemon-reload`; `enable <unit>`; `restart` (or leave stopped if `--no-start`) | `schtasks /Create /TN <task> /XML <f> /F`; `/Run` unless `--no-start` |
+| uninstall | `launchctl bootout gui/<uid>/<label>`; delete plist | `systemctl --user disable --now <unit>`; delete unit; `daemon-reload` | `schtasks /Delete /TN <task> /F` |
+| start | `launchctl kickstart gui/<uid>/<label>` (bootstrap first if not loaded) | `systemctl --user start <unit>` | `schtasks /Run /TN <task>` |
+| stop | `launchctl kill SIGTERM gui/<uid>/<label>` | `systemctl --user stop <unit>` | `schtasks /End /TN <task>` |
+| status | `launchctl print gui/<uid>/<label>` (exit code → state) | `systemctl --user is-active / is-enabled <unit>` | `schtasks /Query /TN <task> /FO LIST` |
+| list-installed | enumerate `~/Library/LaunchAgents/io.kurrent.kcap.daemon.*.plist` | enumerate `~/.config/systemd/user/kcap-daemon-*.service` | `schtasks /Query` filtered to `kcap-daemon-*` |
+
+> **Windows `/End` vs restart-on-failure:** `/End` reports task result
+> `0x41306` (terminated), which Task Scheduler does **not** treat as a failure
+> exit, so the restart-on-failure setting should not relaunch it. This is the
+> one platform behavior to **verify on a real Windows host** during
+> implementation; if `/End` does trigger a relaunch, fall back to disabling the
+> task (`schtasks /Change /DISABLE`) for `stop` and re-enabling for `start`.
+
+### macOS plist (generated — values XML-escaped)
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
-  <key>Label</key>              <string>io.kurrent.kcap.daemon.<name></string>
+  <key>Label</key>              <string>io.kurrent.kcap.daemon.<id></string>
   <key>ProgramArguments</key>   <array>
     <string>/abs/path/kcap-daemon</string>
-    <string>--name</string>     <string><name></string>
-    <string>--log-file</string> <string>/Users/<u>/.config/kcap/daemon-<name>.log</string>
+    <string>--name</string>     <string><id></string>
+    <string>--log-file</string> <string>/Users/<u>/.config/kcap/daemon-<id>.log</string>
   </array>
+  <key>EnvironmentVariables</key><dict>
+    <key>PATH</key>             <string><captured PATH></string>
+    <key>KCAP_PROFILE</key>     <string><pinned profile></string>
+    <!-- plus any captured KCAP_CONFIG_DIR / KCAP_CLAUDE_PATH / KCAP_CODEX_PATH -->
+  </dict>
   <key>RunAtLoad</key>          <true/>
   <key>KeepAlive</key>          <dict><key>SuccessfulExit</key><false/></dict>
   <key>ProcessType</key>        <string>Adaptive</string>
-  <key>StandardOutPath</key>    <string>…/daemon-<name>.log</string>
-  <key>StandardErrorPath</key>  <string>…/daemon-<name>.log</string>
+  <key>StandardOutPath</key>    <string>…/daemon-<id>.log</string>
+  <key>StandardErrorPath</key>  <string>…/daemon-<id>.log</string>
 </dict>
 </plist>
 ```
 
 launchd's default `ThrottleInterval` (10s) is the crash-loop guard.
 
-### Linux systemd templated unit (generated)
+### Linux systemd per-instance unit (generated — one file per id)
 
 ```ini
 [Unit]
-Description=kcap daemon (%i)
+Description=kcap daemon (<id>)
 After=network-online.target
 Wants=network-online.target
 
 [Service]
-ExecStart=/abs/path/kcap-daemon --name %i --log-file %h/.config/kcap/daemon-%i.log
+Environment=PATH=<captured PATH>
+Environment=KCAP_PROFILE=<pinned profile>
+# plus any captured KCAP_CONFIG_DIR / KCAP_CLAUDE_PATH / KCAP_CODEX_PATH
+ExecStart=/abs/path/kcap-daemon --name <id> --log-file %h/.config/kcap/daemon-<id>.log
 Restart=on-failure
 RestartSec=5
 StartLimitIntervalSec=60
@@ -202,12 +307,13 @@ StartLimitBurst=5
 WantedBy=default.target
 ```
 
-Instance name `%i` = the daemon `--name`. `kcap daemon service install --name X`
-operates on `kcap-daemon@X.service`.
+One concrete file per id (`kcap-daemon-<id>.service`), **not** a shared
+`@.service` template — so per-instance baked args/env are expressible and
+uninstalling one id deletes only its file without touching other instances.
 
-### Windows Task Scheduler XML (generated)
+### Windows Task Scheduler XML (generated — values XML-escaped)
 
-Logon trigger for the current user; action runs `kcap-daemon.exe --name … --log-file …`;
+Logon trigger for the current user; action runs `kcap-daemon.exe --name <id> --log-file …`;
 settings: `MultipleInstances=IgnoreNew`, `ExecutionTimeLimit=PT0S` (unlimited),
 `DisallowStartIfOnBatteries=false`, `StopIfGoingOnBatteries=false`,
 `StartWhenAvailable=true`, restart-on-failure (`RestartCount=999`,
@@ -216,15 +322,17 @@ PowerShell quoting; XML is a pure generated string).
 
 ### Integration with existing commands
 
-- **`kcap daemon status`** gains a `service:` line per name — `not installed` /
-  `installed (launchd LaunchAgent, runs at login)` / `installed, running` — from
-  `IServiceManager.Status`.
+- **`kcap daemon status`** unions the running-PID-file names with
+  `IServiceManager.ListInstalled()`, so an installed-but-stopped service appears.
+  Each line gains a `service:` field — `not installed` /
+  `installed (launchd LaunchAgent, runs at login)` / `installed, running`.
 - **`kcap daemon stop`** (ad-hoc) becomes service-aware: if a unit exists for the
-  name it does **not** raw-kill (which the supervisor would just restart);
-  instead it prints guidance to use `kcap daemon service stop --name N`.
-- **`kcap daemon doctor`** gains a check: for each installed unit, verify the
-  baked `DaemonBinaryPath` still exists; if not, report it and suggest
-  `kcap daemon service install` to refresh the path (covers a moved npm prefix).
+  id it does **not** raw-kill (which the supervisor would just restart); instead
+  it prints guidance to use `kcap daemon service stop --name N`.
+- **`kcap daemon doctor`** iterates `ListInstalled()`; for each unit it reads the
+  baked `Status().BinaryPath` and reports if it no longer exists, suggesting
+  `kcap daemon service install` (idempotent) to refresh it. Also warns on the
+  missing-agent-path env condition above.
 
 ## Binary path resolution
 
@@ -232,51 +340,60 @@ PowerShell quoting; XML is a pure generated string).
 `ResolveDaemonBinary()` (sibling of the running `kcap` binary) and writes it into
 the unit. The npm platform-package path
 (`…/@kurrent/kcap-<rid>/bin/kcap-daemon`) is stable across `npm update`, so units
-survive upgrades. A prefix change requires `service install` again — surfaced by
-`daemon doctor`, not silently broken.
+survive upgrades. A prefix change is fixed by re-running `service install`
+(idempotent) — surfaced by `daemon doctor`, not silently broken.
 
 ## Testing
 
-- **Pure generators** (`GenerateUnit`) per OS: TUnit tests assert the output
-  contains the absolute binary path, pinned `--name`/`--log-file` args, the
-  correct label / `@%i` instance / task name, and the restart keys
-  (`KeepAlive`/`Restart=on-failure`/`RestartCount`). Deterministic strings, no OS
-  calls.
+- **Pure generators** (`GenerateUnit`) per platform via `ForPlatform`: TUnit
+  tests assert the output contains the absolute binary path, pinned `--name`/
+  `--log-file`, the baked `PATH`/`KCAP_PROFILE` env, the correct label / unit
+  name / task id, and the restart keys (`KeepAlive` / `Restart=on-failure` /
+  `RestartCount`).
+- **Escaping tests:** ids and paths containing XML/shell metacharacters and
+  spaces produce well-formed plist / `.service` / Task XML (parse the plist and
+  Task XML with `XDocument` in the test to assert validity).
+- **Sanitization:** `Sanitize` mapping of messy names → ids, and idempotency.
 - **Command-vector builders** (the `launchctl`/`systemctl`/`schtasks` argument
-  lists for each verb) are pure helpers → asserted directly.
-- **`ServiceManagerFactory.ForCurrentOs()`** returns the right type per
-  `OperatingSystem.Is*`, throws `PlatformNotSupportedException` otherwise.
-- The thin `Install/Uninstall/Start/Stop` shell-outs are **not** run in CI
-  (can't register real units); they are kept trivial (build vector → run via
-  existing `ProcessHelpers`).
+  lists for each verb) are pure helpers → asserted directly, including the
+  replace-existing (idempotent install) vectors.
+- **`ServiceManagerFactory.ForPlatform`** constructs each manager on any host;
+  `ForCurrentOs()` maps `OperatingSystem.Is*` correctly and throws otherwise.
+- The thin side-effecting `Install/Uninstall/Start/Stop/ListInstalled` shell-outs
+  are **not** run in CI (can't register real units); they are kept trivial (build
+  vector → run via existing `ProcessHelpers`).
 
 ## AOT
 
 AOT-safe throughout: hand-built unit strings (no XML/JSON reflection
-serialization), `Process` shell-out, plain file I/O. Verify with
-`dotnet publish -c Release` and the IL3050/IL2026 grep per CLAUDE.md.
+serialization), `Process` shell-out, plain file I/O. (`XDocument` is used only in
+tests for validation, not at runtime.) Verify with `dotnet publish -c Release`
+and the IL3050/IL2026 grep per CLAUDE.md.
 
 ## Docs (same PR — CLAUDE.md mandate)
 
 - `src/Capacitor.Cli.Core/Resources/help-daemon.txt` — add the `service`
-  subcommand group and its options.
+  subcommand group and its options (`--name`, `--profile`, `--max-agents`,
+  `--no-start`).
 - `README.md` — `## Getting started` gains a "keep the daemon alive" note
   recommending `kcap daemon service install`; the `## CLI commands` daemon
-  section documents `service install/uninstall/start/stop/status`.
+  section documents `service install/uninstall/start/stop/status` and the
+  profile/env-capture behavior.
 
 ## Files
 
 New:
 
-- `src/Capacitor.Cli/Services/IServiceManager.cs` (interface, `ServiceSpec`, `ServiceState`)
-- `src/Capacitor.Cli/Services/ServiceManagerFactory.cs`
+- `src/Capacitor.Cli/Services/IServiceManager.cs` (interface, `ServiceSpec`, `ServiceState`, `ServiceStatus`)
+- `src/Capacitor.Cli/Services/ServiceManagerFactory.cs` (`ServicePlatform`, `ForPlatform`, `ForCurrentOs`)
 - `src/Capacitor.Cli/Services/LaunchdServiceManager.cs`
 - `src/Capacitor.Cli/Services/SystemdServiceManager.cs`
 - `src/Capacitor.Cli/Services/WindowsScheduledTaskServiceManager.cs`
+- `src/Capacitor.Cli/Services/ServiceEnvironment.cs` (captures PATH + KCAP_* and resolves the pinned profile name)
 - `test/Capacitor.Cli.Tests.Unit/Services/*ServiceManagerTests.cs`
 
 Modified:
 
-- `src/Capacitor.Cli/Commands/DaemonCommands.cs` — `service` subcommand dispatch; `status`/`stop`/`doctor` service-awareness
+- `src/Capacitor.Cli/Commands/DaemonCommands.cs` — `service` subcommand dispatch; `status`/`stop`/`doctor` service-awareness (incl. `ListInstalled` union)
 - `src/Capacitor.Cli.Core/Resources/help-daemon.txt`
 - `README.md`

From 11f6f6e927527ef74d7b880b2d8f7824fbc15b93 Mon Sep 17 00:00:00 2001
From: Alexey Zimarev <alex@zimarev.com>
Date: Wed, 10 Jun 2026 17:06:05 +0200
Subject: [PATCH 03/16] docs: fix Windows env model in service spec (cmd
 wrapper)

Task Scheduler's Exec action has no Environment element (only Command/
Arguments/WorkingDirectory), so the captured PATH/KCAP_* can't be set in the
task XML. Generate a daemon-service-<id>.cmd wrapper that `set`s the env and
execs kcap-daemon.exe; the task runs `cmd /c <wrapper>`. install rewrites it,
uninstall deletes it. Add cmd batch escaping to the escaping rules.

Generalize the pure generator seam from GenerateUnit (single string) to
GenerateFiles -> [(path, content)] so Windows's two artifacts fit.

stop fallback: if /End triggers a relaunch, disable -> /End -> re-enable so the
task stays enabled for next logon instead of being left disabled.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...-06-10-daemon-service-supervisor-design.md | 73 +++++++++++++------
 1 file changed, 51 insertions(+), 22 deletions(-)

diff --git a/docs/superpowers/specs/2026-06-10-daemon-service-supervisor-design.md b/docs/superpowers/specs/2026-06-10-daemon-service-supervisor-design.md
index 3ae730167..d45843f86 100644
--- a/docs/superpowers/specs/2026-06-10-daemon-service-supervisor-design.md
+++ b/docs/superpowers/specs/2026-06-10-daemon-service-supervisor-design.md
@@ -87,8 +87,9 @@ Rules:
    the sanitized id when it differs from the input so the user isn't surprised.
 2. **Every interpolated value** (binary path, log path, env values, the id) is
    escaped for its target format when generating unit text: XML-escape for plist
-   and Task XML; systemd value-escaping for `.service` lines. Generators never
-   concatenate raw strings into markup.
+   and Task XML; systemd value-escaping for `.service` lines; **cmd batch
+   escaping** for the Windows `.cmd` wrapper (e.g. `%` → `%%`, quote handling in
+   `set "KEY=value"`). Generators never concatenate raw strings into markup.
 
 This keeps the pure generators total (any input produces well-formed output) and
 is the focus of the escaping unit tests.
@@ -118,9 +119,12 @@ public enum ServiceState { NotInstalled, Installed, Running }
 
 public record ServiceStatus(ServiceState State, string? BinaryPath);
 
+public record GeneratedFile(string Path, string Content); // absolute target path + content
+
 public interface IServiceManager {
-    string  Describe();                       // e.g. "launchd LaunchAgent"
-    string  GenerateUnit(ServiceSpec spec);   // PURE — the primary tested seam
+    string  Describe();                                    // e.g. "launchd LaunchAgent"
+    IReadOnlyList<GeneratedFile> GenerateFiles(ServiceSpec spec); // PURE — the primary tested seam
+                                                                  // (1 file on macOS/Linux; 2 on Windows: Task XML + .cmd wrapper)
 
     IReadOnlyList<string> ListInstalled();    // service ids with a unit file on disk
     ServiceStatus Status(string serviceId);   // state + baked binary path (for doctor)
@@ -199,9 +203,14 @@ So instead of `--server-url`, `install`:
 - **Captures environment** from the installing shell into the unit:
   `PATH` (so bare `claude`/`codex` resolve exactly as they do in the terminal),
   plus any set `KCAP_CONFIG_DIR`, `KCAP_PROFILE`, `KCAP_CLAUDE_PATH`,
-  `KCAP_CODEX_PATH`. Mechanism per platform: launchd `EnvironmentVariables` dict,
-  systemd `Environment=` lines, Windows tasks inherit the user env block but get
-  the same keys set for parity/determinism.
+  `KCAP_CODEX_PATH`. Mechanism per platform: launchd `EnvironmentVariables`
+  dict; systemd `Environment=` lines; **Windows: a generated `.cmd` wrapper**
+  — the Task Scheduler `Exec` action exposes only `Command` / `Arguments` /
+  `WorkingDirectory` (no environment element in the schema), so the task runs
+  `cmd.exe /c <wrapper>` and the wrapper does `set "KEY=value"` for each captured
+  var, then execs `kcap-daemon.exe`. The wrapper lives at
+  `PathHelpers.ConfigPath("daemon-service-<id>.cmd")`; `install` rewrites it,
+  `uninstall` deletes it alongside the task.
 - **`daemon doctor`** additionally warns when neither an absolute agent path nor
   a `PATH` entry containing `claude`/`codex` is present in a unit's captured env.
 
@@ -242,8 +251,8 @@ refresh a moved binary path" well-defined.
 
 | verb | macOS | Linux | Windows |
 |---|---|---|---|
-| install | write plist; `launchctl bootout` (if present); `launchctl bootstrap gui/<uid> <plist>` (`RunAtLoad` starts it); `launchctl kill SIGTERM` if `--no-start` | write unit; `systemctl --user daemon-reload`; `enable <unit>`; `restart` (or leave stopped if `--no-start`) | `schtasks /Create /TN <task> /XML <f> /F`; `/Run` unless `--no-start` |
-| uninstall | `launchctl bootout gui/<uid>/<label>`; delete plist | `systemctl --user disable --now <unit>`; delete unit; `daemon-reload` | `schtasks /Delete /TN <task> /F` |
+| install | write plist; `launchctl bootout` (if present); `launchctl bootstrap gui/<uid> <plist>` (`RunAtLoad` starts it); `launchctl kill SIGTERM` if `--no-start` | write unit; `systemctl --user daemon-reload`; `enable <unit>`; `restart` (or leave stopped if `--no-start`) | write `.cmd` wrapper; `schtasks /Create /TN <task> /XML <f> /F`; `/Run` unless `--no-start` |
+| uninstall | `launchctl bootout gui/<uid>/<label>`; delete plist | `systemctl --user disable --now <unit>`; delete unit; `daemon-reload` | `schtasks /Delete /TN <task> /F`; delete `.cmd` wrapper |
 | start | `launchctl kickstart gui/<uid>/<label>` (bootstrap first if not loaded) | `systemctl --user start <unit>` | `schtasks /Run /TN <task>` |
 | stop | `launchctl kill SIGTERM gui/<uid>/<label>` | `systemctl --user stop <unit>` | `schtasks /End /TN <task>` |
 | status | `launchctl print gui/<uid>/<label>` (exit code → state) | `systemctl --user is-active / is-enabled <unit>` | `schtasks /Query /TN <task> /FO LIST` |
@@ -253,8 +262,10 @@ refresh a moved binary path" well-defined.
 > `0x41306` (terminated), which Task Scheduler does **not** treat as a failure
 > exit, so the restart-on-failure setting should not relaunch it. This is the
 > one platform behavior to **verify on a real Windows host** during
-> implementation; if `/End` does trigger a relaunch, fall back to disabling the
-> task (`schtasks /Change /DISABLE`) for `stop` and re-enabling for `start`.
+> implementation; if `/End` does trigger a relaunch, `stop` falls back to
+> **disable → `/End` → re-enable** (`schtasks /Change /DISABLE`, `/End`,
+> `/Change /ENABLE`) so the run is ended without an immediate relaunch while the
+> task stays **enabled** for the next logon (no manual `start` required).
 
 ### macOS plist (generated — values XML-escaped)
 
@@ -311,14 +322,29 @@ One concrete file per id (`kcap-daemon-<id>.service`), **not** a shared
 `@.service` template — so per-instance baked args/env are expressible and
 uninstalling one id deletes only its file without touching other instances.
 
-### Windows Task Scheduler XML (generated — values XML-escaped)
-
-Logon trigger for the current user; action runs `kcap-daemon.exe --name <id> --log-file …`;
-settings: `MultipleInstances=IgnoreNew`, `ExecutionTimeLimit=PT0S` (unlimited),
-`DisallowStartIfOnBatteries=false`, `StopIfGoingOnBatteries=false`,
-`StartWhenAvailable=true`, restart-on-failure (`RestartCount=999`,
-`RestartInterval=PT1M`). Registered via `schtasks /Create /XML` (avoids
-PowerShell quoting; XML is a pure generated string).
+### Windows Task Scheduler XML + `.cmd` wrapper (generated)
+
+Two generated artifacts, because the Task Scheduler `Exec` action has no
+environment element:
+
+1. **`daemon-service-<id>.cmd`** (under the kcap config dir, cmd-escaped):
+   ```bat
+   @echo off
+   set "PATH=<captured PATH>"
+   set "KCAP_PROFILE=<pinned profile>"
+   rem plus any captured KCAP_CONFIG_DIR / KCAP_CLAUDE_PATH / KCAP_CODEX_PATH
+   "C:\abs\path\kcap-daemon.exe" --name <id> --log-file "<...>\daemon-<id>.log"
+   ```
+2. **Task XML** (values XML-escaped): logon trigger for the current user; the
+   `Exec` action is `Command = cmd.exe`, `Arguments = /c "<wrapper path>"`;
+   settings `MultipleInstances=IgnoreNew`, `ExecutionTimeLimit=PT0S` (unlimited),
+   `DisallowStartIfOnBatteries=false`, `StopIfGoingOnBatteries=false`,
+   `StartWhenAvailable=true`, restart-on-failure (`RestartCount=999`,
+   `RestartInterval=PT1M`). Registered via `schtasks /Create /XML` (avoids
+   PowerShell quoting; XML is a pure generated string).
+
+`install` writes both (overwriting); `uninstall` deletes the task and the
+wrapper.
 
 ### Integration with existing commands
 
@@ -345,14 +371,17 @@ survive upgrades. A prefix change is fixed by re-running `service install`
 
 ## Testing
 
-- **Pure generators** (`GenerateUnit`) per platform via `ForPlatform`: TUnit
-  tests assert the output contains the absolute binary path, pinned `--name`/
+- **Pure generators** (`GenerateFiles`) per platform via `ForPlatform`: TUnit
+  tests assert the file set (1 file on macOS/Linux; Task XML + `.cmd` wrapper on
+  Windows) and that contents contain the absolute binary path, pinned `--name`/
   `--log-file`, the baked `PATH`/`KCAP_PROFILE` env, the correct label / unit
   name / task id, and the restart keys (`KeepAlive` / `Restart=on-failure` /
   `RestartCount`).
 - **Escaping tests:** ids and paths containing XML/shell metacharacters and
   spaces produce well-formed plist / `.service` / Task XML (parse the plist and
-  Task XML with `XDocument` in the test to assert validity).
+  Task XML with `XDocument` in the test to assert validity), and a Windows
+  `.cmd` wrapper whose `set "KEY=value"` lines and exec line are correctly
+  cmd-escaped (e.g. `%` doubled).
 - **Sanitization:** `Sanitize` mapping of messy names → ids, and idempotency.
 - **Command-vector builders** (the `launchctl`/`systemctl`/`schtasks` argument
   lists for each verb) are pure helpers → asserted directly, including the

From 5d237d75102d0559172d326f8ec3d75143e4de9c Mon Sep 17 00:00:00 2001
From: Alexey Zimarev <alex@zimarev.com>
Date: Wed, 10 Jun 2026 17:15:30 +0200
Subject: [PATCH 04/16] docs: implementation plan for daemon service supervisor

10 TDD tasks: contracts+escaping, three pure unit generators
(launchd/systemd/windows), thin managers + process runner + factory,
env capture + profile pin, `kcap daemon service` dispatch,
status/stop/doctor awareness, docs, AOT verify.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../2026-06-10-daemon-service-supervisor.md   | 1343 +++++++++++++++++
 1 file changed, 1343 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-06-10-daemon-service-supervisor.md

diff --git a/docs/superpowers/plans/2026-06-10-daemon-service-supervisor.md b/docs/superpowers/plans/2026-06-10-daemon-service-supervisor.md
new file mode 100644
index 000000000..81f1bc46f
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-10-daemon-service-supervisor.md
@@ -0,0 +1,1343 @@
+# Daemon Service Supervisor 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:** Add `kcap daemon service install|uninstall|start|stop|status` that registers the daemon as a per-user OS service (launchd / systemd `--user` / Windows Scheduled Task) so it auto-restarts after an external SIGKILL (jetsam/OOM/crash).
+
+**Architecture:** An `IServiceManager` seam in `Capacitor.Cli` with three implementations selected by `ServiceManagerFactory`. Each platform splits a **pure** unit/wrapper text + command-vector + output-parser class (`LaunchdUnit`/`SystemdUnit`/`WindowsTaskUnit`, fully unit-tested) from a **thin** side-effecting manager (`*ServiceManager`, shells out via a small `ServiceProcess` runner, not CI-tested). `DaemonCommands` dispatches the new `service` subcommand and gains service-awareness in `status`/`stop`/`doctor`.
+
+**Tech Stack:** .NET 10, NativeAOT, TUnit. Hand-built unit strings (no reflection serialization). `System.Diagnostics.Process` for shell-outs. `System.Security.SecurityElement.Escape` for XML escaping. Existing helpers: `DaemonLockPaths.Sanitize`, `PathHelpers`, `DaemonNameResolver`, `DaemonCommands.ResolveDaemonBinary`.
+
+**Spec:** `docs/superpowers/specs/2026-06-10-daemon-service-supervisor-design.md`
+
+---
+
+## File structure
+
+New (all under `src/Capacitor.Cli/Services/`):
+
+| File | Responsibility |
+|---|---|
+| `IServiceManager.cs` | Contracts: `IServiceManager`, `ServiceSpec`, `ServiceState`, `ServiceStatus`, `GeneratedFile`, `ServicePlatform` |
+| `ServiceText.cs` | Pure escaping helpers (`Xml`, `CmdValue`, `SystemdValue`) + `ServiceId` derivation |
+| `ServiceProcess.cs` | Tiny shell-out runner (`Run(file, args) -> (int exit, string stdout)`) |
+| `LaunchdUnit.cs` | PURE: plist text, command vectors, status parse, id-from-filename |
+| `LaunchdServiceManager.cs` | Thin launchd `IServiceManager` |
+| `SystemdUnit.cs` | PURE: `.service` text, vectors, status parse, id-from-filename |
+| `SystemdServiceManager.cs` | Thin systemd `IServiceManager` |
+| `WindowsTaskUnit.cs` | PURE: Task XML + `.cmd` wrapper text, vectors, status parse, id-from-name |
+| `WindowsScheduledTaskServiceManager.cs` | Thin Windows `IServiceManager` |
+| `ServiceManagerFactory.cs` | `ForPlatform` / `ForCurrentOs` |
+| `ServiceEnvironment.cs` | Capture `PATH`+`KCAP_*` and resolve the pinned profile name into the env dict |
+
+Modified:
+
+| File | Change |
+|---|---|
+| `src/Capacitor.Cli/Commands/DaemonCommands.cs` | `service` subcommand dispatch; build `ServiceSpec`; `status`/`stop`/`doctor` awareness |
+| `src/Capacitor.Cli.Core/Resources/help-daemon.txt` | document `service` group |
+| `README.md` | getting-started note + `daemon` command section |
+
+Tests (under `test/Capacitor.Cli.Tests.Unit/Services/`): one file per pure class + factory + environment.
+
+All new types are `internal` (the Cli assembly has `InternalsVisibleTo Capacitor.Cli.Tests.Unit`).
+
+---
+
+## Task 1: Contracts + escaping + id helper
+
+**Files:**
+- Create: `src/Capacitor.Cli/Services/IServiceManager.cs`
+- Create: `src/Capacitor.Cli/Services/ServiceText.cs`
+- Test: `test/Capacitor.Cli.Tests.Unit/Services/ServiceTextTests.cs`
+
+- [ ] **Step 1: Write the contracts file** (no test — consumed by later tasks)
+
+`src/Capacitor.Cli/Services/IServiceManager.cs`:
+```csharp
+namespace Capacitor.Cli.Services;
+
+/// <summary>Which OS service backend a manager targets.</summary>
+enum ServicePlatform { Launchd, Systemd, WindowsScheduledTask }
+
+/// <summary>Lifecycle state of an installed service for one id.</summary>
+enum ServiceState { NotInstalled, Installed, Running }
+
+/// <summary>A file the manager writes at install time (absolute path + content).</summary>
+record GeneratedFile(string Path, string Content);
+
+/// <summary>Status plus the binary path baked into the installed unit (for doctor).</summary>
+record ServiceStatus(ServiceState State, string? BinaryPath);
+
+/// <summary>
+/// Everything needed to render and register one per-user service.
+/// <paramref name="ServiceId"/> is the sanitized id (see <see cref="ServiceText.ServiceId"/>)
+/// used for the filename/label/instance/task AND the daemon <c>--name</c>.
+/// </summary>
+record ServiceSpec(
+    string                              ServiceId,
+    string                              DaemonBinaryPath,
+    string                              LogPath,
+    IReadOnlyDictionary<string, string> Environment,
+    IReadOnlyList<string>               ExtraArgs);
+
+interface IServiceManager {
+    string Describe();
+    IReadOnlyList<GeneratedFile> GenerateFiles(ServiceSpec spec);
+    IReadOnlyList<string>        ListInstalled();
+    ServiceStatus                Status(string serviceId);
+    void Install(ServiceSpec spec, bool startNow);
+    void Uninstall(string serviceId);
+    void Start(string serviceId);
+    void Stop(string serviceId);
+}
+```
+
+- [ ] **Step 2: Write the failing test for `ServiceText`**
+
+`test/Capacitor.Cli.Tests.Unit/Services/ServiceTextTests.cs`:
+```csharp
+using Capacitor.Cli.Services;
+
+namespace Capacitor.Cli.Tests.Unit.Services;
+
+public class ServiceTextTests {
+    [Test]
+    public async Task ServiceId_sanitizes_and_lowercases() {
+        await Assert.That(ServiceText.ServiceId("My Laptop")).IsEqualTo("my-laptop");
+    }
+
+    [Test]
+    public async Task ServiceId_is_idempotent() {
+        var once = ServiceText.ServiceId("a/b c");
+        await Assert.That(ServiceText.ServiceId(once)).IsEqualTo(once);
+    }
+
+    [Test]
+    public async Task Xml_escapes_the_five_markup_chars() {
+        await Assert.That(ServiceText.Xml("a&b<c>\"d'")).IsEqualTo("a&amp;b&lt;c&gt;&quot;d&apos;");
+    }
+
+    [Test]
+    public async Task CmdValue_doubles_percent_signs() {
+        await Assert.That(ServiceText.CmdValue("100%PATH%")).IsEqualTo("100%%PATH%%");
+    }
+
+    [Test]
+    public async Task SystemdValue_collapses_newlines_to_spaces() {
+        await Assert.That(ServiceText.SystemdValue("a\nb")).IsEqualTo("a b");
+    }
+}
+```
+
+- [ ] **Step 3: Run the test to verify it fails**
+
+Run: `dotnet run --project test/Capacitor.Cli.Tests.Unit/Capacitor.Cli.Tests.Unit.csproj --treenode-filter "/*/*/ServiceTextTests/*"`
+Expected: FAIL (compile error — `ServiceText` does not exist).
+
+- [ ] **Step 4: Write `ServiceText`**
+
+`src/Capacitor.Cli/Services/ServiceText.cs`:
+```csharp
+using System.Security;
+using Capacitor.Cli.Core;
+
+namespace Capacitor.Cli.Services;
+
+/// <summary>
+/// Pure text helpers for rendering service units. Each value interpolated into
+/// a unit/wrapper is escaped for its target format so generators never emit
+/// malformed markup, regardless of daemon name / path content.
+/// </summary>
+static class ServiceText {
+    /// <summary>Sanitized, portable service id — reuses the daemon lock-file rule.</summary>
+    public static string ServiceId(string name) => DaemonLockPaths.Sanitize(name);
+
+    /// <summary>XML-escape for plist and Task Scheduler XML (escapes &amp; &lt; &gt; " ').</summary>
+    public static string Xml(string value) => SecurityElement.Escape(value) ?? "";
+
+    /// <summary>Escape a value for a batch <c>set "KEY=value"</c> line: percent-signs doubled.</summary>
+    public static string CmdValue(string value) => value.Replace("%", "%%");
+
+    /// <summary>Escape a systemd <c>Environment=</c>/<c>Description=</c> value: no raw newlines.</summary>
+    public static string SystemdValue(string value) =>
+        value.Replace("\r", " ").Replace("\n", " ");
+}
+```
+
+- [ ] **Step 5: Run the test to verify it passes**
+
+Run: `dotnet run --project test/Capacitor.Cli.Tests.Unit/Capacitor.Cli.Tests.Unit.csproj --treenode-filter "/*/*/ServiceTextTests/*"`
+Expected: PASS (5 tests).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/Capacitor.Cli/Services/IServiceManager.cs src/Capacitor.Cli/Services/ServiceText.cs test/Capacitor.Cli.Tests.Unit/Services/ServiceTextTests.cs
+git commit -m "feat(daemon): service contracts + text-escaping helpers"
+```
+
+---
+
+## Task 2: launchd pure unit (`LaunchdUnit`)
+
+**Files:**
+- Create: `src/Capacitor.Cli/Services/LaunchdUnit.cs`
+- Test: `test/Capacitor.Cli.Tests.Unit/Services/LaunchdUnitTests.cs`
+
+- [ ] **Step 1: Write the failing test**
+
+`test/Capacitor.Cli.Tests.Unit/Services/LaunchdUnitTests.cs`:
+```csharp
+using System.Xml.Linq;
+using Capacitor.Cli.Services;
+
+namespace Capacitor.Cli.Tests.Unit.Services;
+
+public class LaunchdUnitTests {
+    static ServiceSpec Spec(string id = "laptop") => new(
+        ServiceId: id,
+        DaemonBinaryPath: "/opt/kcap/kcap-daemon",
+        LogPath: "/home/u/.config/kcap/daemon-laptop.log",
+        Environment: new Dictionary<string, string> { ["PATH"] = "/usr/bin:/bin", ["KCAP_PROFILE"] = "work" },
+        ExtraArgs: ["--max-agents", "8"]);
+
+    [Test]
+    public async Task Label_is_reverse_dns_with_id() {
+        await Assert.That(LaunchdUnit.Label("laptop")).IsEqualTo("io.kurrent.kcap.daemon.laptop");
+    }
+
+    [Test]
+    public async Task Plist_is_well_formed_xml_and_carries_args_and_env() {
+        var plist = LaunchdUnit.Plist(Spec());
+        var doc   = XDocument.Parse(plist); // throws if malformed
+        await Assert.That(doc).IsNotNull();
+        await Assert.That(plist).Contains("<string>/opt/kcap/kcap-daemon</string>");
+        await Assert.That(plist).Contains("<string>--name</string>");
+        await Assert.That(plist).Contains("<string>laptop</string>");
+        await Assert.That(plist).Contains("<string>--max-agents</string>");
+        await Assert.That(plist).Contains("<key>PATH</key>");
+        await Assert.That(plist).Contains("<key>KCAP_PROFILE</key>");
+        await Assert.That(plist).Contains("<key>SuccessfulExit</key>");
+    }
+
+    [Test]
+    public async Task Plist_escapes_metacharacters_in_values() {
+        var spec  = Spec() with { DaemonBinaryPath = "/opt/a&b/kcap-daemon" };
+        var plist = LaunchdUnit.Plist(spec);
+        XDocument.Parse(plist); // must still parse
+        await Assert.That(plist).Contains("/opt/a&amp;b/kcap-daemon");
+    }
+
+    [Test]
+    public async Task IdFromPlistFileName_extracts_the_id() {
+        await Assert.That(LaunchdUnit.IdFromPlistFileName("io.kurrent.kcap.daemon.laptop.plist"))
+            .IsEqualTo("laptop");
+        await Assert.That(LaunchdUnit.IdFromPlistFileName("unrelated.plist")).IsNull();
+    }
+
+    [Test]
+    public async Task StatusFromPrint_maps_exit_and_state() {
+        await Assert.That(LaunchdUnit.StatusFromPrint(exitCode: 1, stdout: "")).IsEqualTo(ServiceState.NotInstalled);
+        await Assert.That(LaunchdUnit.StatusFromPrint(0, "state = running")).IsEqualTo(ServiceState.Running);
+        await Assert.That(LaunchdUnit.StatusFromPrint(0, "state = not running")).IsEqualTo(ServiceState.Installed);
+    }
+}
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `dotnet run --project test/Capacitor.Cli.Tests.Unit/Capacitor.Cli.Tests.Unit.csproj --treenode-filter "/*/*/LaunchdUnitTests/*"`
+Expected: FAIL (compile error — `LaunchdUnit` does not exist).
+
+- [ ] **Step 3: Write `LaunchdUnit`**
+
+`src/Capacitor.Cli/Services/LaunchdUnit.cs`:
+```csharp
+using System.Text;
+using Capacitor.Cli.Core;
+
+namespace Capacitor.Cli.Services;
+
+/// <summary>Pure rendering + command vectors for a per-user launchd LaunchAgent.</summary>
+static class LaunchdUnit {
+    const string LabelPrefix = "io.kurrent.kcap.daemon.";
+
+    public static string Label(string id) => LabelPrefix + id;
+
+    /// <summary>~/Library/LaunchAgents directory for the current user.</summary>
+    public static string AgentsDir() =>
+        Path.Combine(PathHelpers.HomeDirectory, "Library", "LaunchAgents");
+
+    public static string PlistPath(string id) =>
+        Path.Combine(AgentsDir(), Label(id) + ".plist");
+
+    /// <summary>Separate stdout/stderr capture file (keeps the rolling --log-file uncluttered).</summary>
+    static string OutLogPath(ServiceSpec spec) =>
+        Path.ChangeExtension(spec.LogPath, null) + ".out.log";
+
+    public static string Plist(ServiceSpec spec) {
+        var sb = new StringBuilder();
+        sb.Append("""
+            <?xml version="1.0" encoding="UTF-8"?>
+            <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+            <plist version="1.0">
+            <dict>
+
+            """);
+        sb.Append($"  <key>Label</key><string>{ServiceText.Xml(Label(spec.ServiceId))}</string>\n");
+
+        sb.Append("  <key>ProgramArguments</key><array>\n");
+        foreach (var arg in ProgramArguments(spec))
+            sb.Append($"    <string>{ServiceText.Xml(arg)}</string>\n");
+        sb.Append("  </array>\n");
+
+        sb.Append("  <key>EnvironmentVariables</key><dict>\n");
+        foreach (var (k, v) in spec.Environment)
+            sb.Append($"    <key>{ServiceText.Xml(k)}</key><string>{ServiceText.Xml(v)}</string>\n");
+        sb.Append("  </dict>\n");
+
+        sb.Append("  <key>RunAtLoad</key><true/>\n");
+        sb.Append("  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>\n");
+        sb.Append("  <key>ProcessType</key><string>Adaptive</string>\n");
+        sb.Append($"  <key>StandardOutPath</key><string>{ServiceText.Xml(OutLogPath(spec))}</string>\n");
+        sb.Append($"  <key>StandardErrorPath</key><string>{ServiceText.Xml(OutLogPath(spec))}</string>\n");
+        sb.Append("</dict>\n</plist>\n");
+        return sb.ToString();
+    }
+
+    /// <summary>argv the agent runs: binary, pinned --name + --log-file, then extra args.</summary>
+    public static IReadOnlyList<string> ProgramArguments(ServiceSpec spec) =>
+        [spec.DaemonBinaryPath, "--name", spec.ServiceId, "--log-file", spec.LogPath, .. spec.ExtraArgs];
+
+    public static string? IdFromPlistFileName(string fileName) {
+        var name = Path.GetFileNameWithoutExtension(fileName); // strips .plist
+        return name.StartsWith(LabelPrefix[..^1] + ".", StringComparison.Ordinal)
+            ? name[LabelPrefix.Length..]
+            : null;
+    }
+
+    // ── command vectors (uid passed in so these stay pure) ──
+    public static string[] BootstrapArgs(int uid, string plistPath) => ["bootstrap", $"gui/{uid}", plistPath];
+    public static string[] BootoutArgs(int uid, string id)          => ["bootout", $"gui/{uid}/{Label(id)}"];
+    public static string[] KickstartArgs(int uid, string id)        => ["kickstart", $"gui/{uid}/{Label(id)}"];
+    public static string[] KillArgs(int uid, string id)             => ["kill", "SIGTERM", $"gui/{uid}/{Label(id)}"];
+    public static string[] PrintArgs(int uid, string id)            => ["print", $"gui/{uid}/{Label(id)}"];
+
+    public static ServiceState StatusFromPrint(int exitCode, string stdout) {
+        if (exitCode != 0) return ServiceState.NotInstalled;
+        return stdout.Contains("state = running", StringComparison.OrdinalIgnoreCase)
+            ? ServiceState.Running
+            : ServiceState.Installed;
+    }
+}
+```
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run: `dotnet run --project test/Capacitor.Cli.Tests.Unit/Capacitor.Cli.Tests.Unit.csproj --treenode-filter "/*/*/LaunchdUnitTests/*"`
+Expected: PASS (5 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/Capacitor.Cli/Services/LaunchdUnit.cs test/Capacitor.Cli.Tests.Unit/Services/LaunchdUnitTests.cs
+git commit -m "feat(daemon): launchd plist + command vectors (pure)"
+```
+
+---
+
+## Task 3: systemd pure unit (`SystemdUnit`)
+
+**Files:**
+- Create: `src/Capacitor.Cli/Services/SystemdUnit.cs`
+- Test: `test/Capacitor.Cli.Tests.Unit/Services/SystemdUnitTests.cs`
+
+- [ ] **Step 1: Write the failing test**
+
+`test/Capacitor.Cli.Tests.Unit/Services/SystemdUnitTests.cs`:
+```csharp
+using Capacitor.Cli.Services;
+
+namespace Capacitor.Cli.Tests.Unit.Services;
+
+public class SystemdUnitTests {
+    static ServiceSpec Spec(string id = "laptop") => new(
+        id, "/opt/kcap/kcap-daemon", "/home/u/.config/kcap/daemon-laptop.log",
+        new Dictionary<string, string> { ["PATH"] = "/usr/bin", ["KCAP_PROFILE"] = "work" },
+        ["--max-agents", "8"]);
+
+    [Test]
+    public async Task UnitName_is_per_instance() {
+        await Assert.That(SystemdUnit.UnitName("laptop")).IsEqualTo("kcap-daemon-laptop.service");
+    }
+
+    [Test]
+    public async Task Unit_has_execstart_restart_and_env() {
+        var unit = SystemdUnit.Unit(Spec());
+        await Assert.That(unit).Contains("ExecStart=/opt/kcap/kcap-daemon --name laptop --log-file /home/u/.config/kcap/daemon-laptop.log --max-agents 8");
+        await Assert.That(unit).Contains("Restart=on-failure");
+        await Assert.That(unit).Contains("Environment=PATH=/usr/bin");
+        await Assert.That(unit).Contains("Environment=KCAP_PROFILE=work");
+        await Assert.That(unit).Contains("WantedBy=default.target");
+    }
+
+    [Test]
+    public async Task IdFromUnitFileName_extracts_id() {
+        await Assert.That(SystemdUnit.IdFromUnitFileName("kcap-daemon-laptop.service")).IsEqualTo("laptop");
+        await Assert.That(SystemdUnit.IdFromUnitFileName("other.service")).IsNull();
+    }
+
+    [Test]
+    public async Task StatusFrom_maps_active_strings() {
+        await Assert.That(SystemdUnit.StatusFrom(activeOut: "active", enabledExit: 0)).IsEqualTo(ServiceState.Running);
+        await Assert.That(SystemdUnit.StatusFrom("inactive", 0)).IsEqualTo(ServiceState.Installed);
+        await Assert.That(SystemdUnit.StatusFrom("inactive", 1)).IsEqualTo(ServiceState.NotInstalled);
+    }
+}
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `dotnet run --project test/Capacitor.Cli.Tests.Unit/Capacitor.Cli.Tests.Unit.csproj --treenode-filter "/*/*/SystemdUnitTests/*"`
+Expected: FAIL (compile error — `SystemdUnit` does not exist).
+
+- [ ] **Step 3: Write `SystemdUnit`**
+
+`src/Capacitor.Cli/Services/SystemdUnit.cs`:
+```csharp
+using System.Text;
+using Capacitor.Cli.Core;
+
+namespace Capacitor.Cli.Services;
+
+/// <summary>Pure rendering + command vectors for a per-user systemd unit (one file per id).</summary>
+static class SystemdUnit {
+    const string Prefix = "kcap-daemon-";
+
+    public static string UnitName(string id) => $"{Prefix}{id}.service";
+
+    public static string UserUnitDir() =>
+        Path.Combine(PathHelpers.HomeDirectory, ".config", "systemd", "user");
+
+    public static string UnitPath(string id) => Path.Combine(UserUnitDir(), UnitName(id));
+
+    public static string Unit(ServiceSpec spec) {
+        var sb = new StringBuilder();
+        sb.Append("[Unit]\n");
+        sb.Append($"Description=kcap daemon ({ServiceText.SystemdValue(spec.ServiceId)})\n");
+        sb.Append("After=network-online.target\n");
+        sb.Append("Wants=network-online.target\n\n");
+
+        sb.Append("[Service]\n");
+        foreach (var (k, v) in spec.Environment)
+            sb.Append($"Environment={ServiceText.SystemdValue(k)}={ServiceText.SystemdValue(v)}\n");
+
+        var args = string.Join(' ', new[] { "--name", spec.ServiceId, "--log-file", spec.LogPath }.Concat(spec.ExtraArgs));
+        sb.Append($"ExecStart={spec.DaemonBinaryPath} {args}\n");
+        sb.Append("Restart=on-failure\n");
+        sb.Append("RestartSec=5\n");
+        sb.Append("StartLimitIntervalSec=60\n");
+        sb.Append("StartLimitBurst=5\n\n");
+
+        sb.Append("[Install]\n");
+        sb.Append("WantedBy=default.target\n");
+        return sb.ToString();
+    }
+
+    public static string? IdFromUnitFileName(string fileName) =>
+        fileName.StartsWith(Prefix, StringComparison.Ordinal) && fileName.EndsWith(".service", StringComparison.Ordinal)
+            ? fileName[Prefix.Length..^".service".Length]
+            : null;
+
+    // ── command vectors ──
+    public static string[] DaemonReloadArgs()      => ["--user", "daemon-reload"];
+    public static string[] EnableArgs(string id)   => ["--user", "enable", UnitName(id)];
+    public static string[] DisableNowArgs(string id)=> ["--user", "disable", "--now", UnitName(id)];
+    public static string[] StartArgs(string id)    => ["--user", "start", UnitName(id)];
+    public static string[] RestartArgs(string id)  => ["--user", "restart", UnitName(id)];
+    public static string[] StopArgs(string id)     => ["--user", "stop", UnitName(id)];
+    public static string[] IsActiveArgs(string id) => ["--user", "is-active", UnitName(id)];
+    public static string[] IsEnabledArgs(string id)=> ["--user", "is-enabled", UnitName(id)];
+
+    public static ServiceState StatusFrom(string activeOut, int enabledExit) {
+        if (activeOut.Trim().Equals("active", StringComparison.OrdinalIgnoreCase)) return ServiceState.Running;
+        return enabledExit == 0 ? ServiceState.Installed : ServiceState.NotInstalled;
+    }
+}
+```
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run: `dotnet run --project test/Capacitor.Cli.Tests.Unit/Capacitor.Cli.Tests.Unit.csproj --treenode-filter "/*/*/SystemdUnitTests/*"`
+Expected: PASS (4 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/Capacitor.Cli/Services/SystemdUnit.cs test/Capacitor.Cli.Tests.Unit/Services/SystemdUnitTests.cs
+git commit -m "feat(daemon): systemd per-instance unit + vectors (pure)"
+```
+
+---
+
+## Task 4: Windows pure unit (`WindowsTaskUnit`)
+
+**Files:**
+- Create: `src/Capacitor.Cli/Services/WindowsTaskUnit.cs`
+- Test: `test/Capacitor.Cli.Tests.Unit/Services/WindowsTaskUnitTests.cs`
+
+- [ ] **Step 1: Write the failing test**
+
+`test/Capacitor.Cli.Tests.Unit/Services/WindowsTaskUnitTests.cs`:
+```csharp
+using System.Xml.Linq;
+using Capacitor.Cli.Services;
+
+namespace Capacitor.Cli.Tests.Unit.Services;
+
+public class WindowsTaskUnitTests {
+    static ServiceSpec Spec(string id = "laptop") => new(
+        id, @"C:\kcap\kcap-daemon.exe", @"C:\Users\u\.config\kcap\daemon-laptop.log",
+        new Dictionary<string, string> { ["PATH"] = @"C:\bin", ["KCAP_PROFILE"] = "work" },
+        ["--max-agents", "8"]);
+
+    [Test]
+    public async Task TaskName_is_per_id() {
+        await Assert.That(WindowsTaskUnit.TaskName("laptop")).IsEqualTo("kcap-daemon-laptop");
+    }
+
+    [Test]
+    public async Task Wrapper_sets_env_and_execs_daemon() {
+        var cmd = WindowsTaskUnit.Wrapper(Spec());
+        await Assert.That(cmd).Contains("set \"PATH=C:\\bin\"");
+        await Assert.That(cmd).Contains("set \"KCAP_PROFILE=work\"");
+        await Assert.That(cmd).Contains("\"C:\\kcap\\kcap-daemon.exe\" --name laptop --log-file \"C:\\Users\\u\\.config\\kcap\\daemon-laptop.log\" --max-agents 8");
+    }
+
+    [Test]
+    public async Task Wrapper_doubles_percent_in_values() {
+        var spec = Spec() with { Environment = new Dictionary<string, string> { ["X"] = "50%done" } };
+        await Assert.That(WindowsTaskUnit.Wrapper(spec)).Contains("set \"X=50%%done\"");
+    }
+
+    [Test]
+    public async Task TaskXml_is_well_formed_and_runs_cmd_wrapper() {
+        var xml = WindowsTaskUnit.TaskXml(Spec(), @"C:\Users\u\.config\kcap\daemon-service-laptop.cmd");
+        XDocument.Parse(xml); // throws if malformed
+        await Assert.That(xml).Contains("<Command>cmd.exe</Command>");
+        await Assert.That(xml).Contains("/c");
+        await Assert.That(xml).Contains("daemon-service-laptop.cmd");
+        await Assert.That(xml).Contains("<LogonTrigger>");
+    }
+}
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `dotnet run --project test/Capacitor.Cli.Tests.Unit/Capacitor.Cli.Tests.Unit.csproj --treenode-filter "/*/*/WindowsTaskUnitTests/*"`
+Expected: FAIL (compile error — `WindowsTaskUnit` does not exist).
+
+- [ ] **Step 3: Write `WindowsTaskUnit`**
+
+`src/Capacitor.Cli/Services/WindowsTaskUnit.cs`:
+```csharp
+using System.Text;
+using Capacitor.Cli.Core;
+
+namespace Capacitor.Cli.Services;
+
+/// <summary>Pure rendering + command vectors for a per-user Windows logon Scheduled Task.</summary>
+static class WindowsTaskUnit {
+    const string Prefix = "kcap-daemon-";
+
+    public static string TaskName(string id) => Prefix + id;
+
+    public static string WrapperPath(string id) => PathHelpers.ConfigPath($"daemon-service-{id}.cmd");
+
+    /// <summary>.cmd wrapper: set the captured env, then exec the daemon (no Environment element in Task XML).</summary>
+    public static string Wrapper(ServiceSpec spec) {
+        var sb = new StringBuilder();
+        sb.Append("@echo off\r\n");
+        foreach (var (k, v) in spec.Environment)
+            sb.Append($"set \"{ServiceText.CmdValue(k)}={ServiceText.CmdValue(v)}\"\r\n");
+        var args = string.Join(' ',
+            new[] { "--name", spec.ServiceId, "--log-file", Quote(spec.LogPath) }
+                .Concat(spec.ExtraArgs.Select(QuoteIfNeeded)));
+        sb.Append($"{Quote(ServiceText.CmdValue(spec.DaemonBinaryPath))} {args}\r\n");
+        return sb.ToString();
+    }
+
+    static string Quote(string s) => $"\"{s}\"";
+    static string QuoteIfNeeded(string s) => s.Contains(' ') ? Quote(s) : s;
+
+    public static string TaskXml(ServiceSpec spec, string wrapperPath) =>
+        $"""
+        <?xml version="1.0" encoding="UTF-16"?>
+        <Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+          <RegistrationInfo>
+            <Description>kcap daemon ({ServiceText.Xml(spec.ServiceId)})</Description>
+          </RegistrationInfo>
+          <Triggers>
+            <LogonTrigger><Enabled>true</Enabled></LogonTrigger>
+          </Triggers>
+          <Settings>
+            <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+            <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+            <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+            <StartWhenAvailable>true</StartWhenAvailable>
+            <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+            <RestartOnFailure><Interval>PT1M</Interval><Count>999</Count></RestartOnFailure>
+          </Settings>
+          <Actions>
+            <Exec>
+              <Command>cmd.exe</Command>
+              <Arguments>/c "{ServiceText.Xml(wrapperPath)}"</Arguments>
+            </Exec>
+          </Actions>
+        </Task>
+        """;
+
+    public static string? IdFromTaskName(string taskName) =>
+        taskName.StartsWith(Prefix, StringComparison.Ordinal) ? taskName[Prefix.Length..] : null;
+
+    // ── command vectors (schtasks) ──
+    public static string[] CreateArgs(string id, string xmlPath) => ["/Create", "/TN", TaskName(id), "/XML", xmlPath, "/F"];
+    public static string[] DeleteArgs(string id)                 => ["/Delete", "/TN", TaskName(id), "/F"];
+    public static string[] RunArgs(string id)                    => ["/Run", "/TN", TaskName(id)];
+    public static string[] EndArgs(string id)                    => ["/End", "/TN", TaskName(id)];
+    public static string[] QueryArgs(string id)                  => ["/Query", "/TN", TaskName(id), "/FO", "LIST"];
+
+    public static ServiceState StatusFromQuery(int exitCode, string stdout) {
+        if (exitCode != 0) return ServiceState.NotInstalled;
+        return stdout.Contains("Running", StringComparison.OrdinalIgnoreCase)
+            ? ServiceState.Running
+            : ServiceState.Installed;
+    }
+}
+```
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run: `dotnet run --project test/Capacitor.Cli.Tests.Unit/Capacitor.Cli.Tests.Unit.csproj --treenode-filter "/*/*/WindowsTaskUnitTests/*"`
+Expected: PASS (4 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/Capacitor.Cli/Services/WindowsTaskUnit.cs test/Capacitor.Cli.Tests.Unit/Services/WindowsTaskUnitTests.cs
+git commit -m "feat(daemon): windows task xml + cmd wrapper + vectors (pure)"
+```
+
+---
+
+## Task 5: Process runner, thin managers, and factory
+
+**Files:**
+- Create: `src/Capacitor.Cli/Services/ServiceProcess.cs`
+- Create: `src/Capacitor.Cli/Services/LaunchdServiceManager.cs`
+- Create: `src/Capacitor.Cli/Services/SystemdServiceManager.cs`
+- Create: `src/Capacitor.Cli/Services/WindowsScheduledTaskServiceManager.cs`
+- Create: `src/Capacitor.Cli/Services/ServiceManagerFactory.cs`
+- Test: `test/Capacitor.Cli.Tests.Unit/Services/ServiceManagerFactoryTests.cs`
+
+- [ ] **Step 1: Write the failing factory test**
+
+`test/Capacitor.Cli.Tests.Unit/Services/ServiceManagerFactoryTests.cs`:
+```csharp
+using Capacitor.Cli.Services;
+
+namespace Capacitor.Cli.Tests.Unit.Services;
+
+public class ServiceManagerFactoryTests {
+    [Test]
+    public async Task ForPlatform_returns_each_concrete_manager() {
+        await Assert.That(ServiceManagerFactory.ForPlatform(ServicePlatform.Launchd)).IsTypeOf<LaunchdServiceManager>();
+        await Assert.That(ServiceManagerFactory.ForPlatform(ServicePlatform.Systemd)).IsTypeOf<SystemdServiceManager>();
+        await Assert.That(ServiceManagerFactory.ForPlatform(ServicePlatform.WindowsScheduledTask)).IsTypeOf<WindowsScheduledTaskServiceManager>();
+    }
+
+    [Test]
+    public async Task ForCurrentOs_does_not_throw_on_this_host() {
+        var mgr = ServiceManagerFactory.ForCurrentOs();
+        await Assert.That(mgr.Describe()).IsNotNull();
+    }
+
+    [Test]
+    public async Task Launchd_GenerateFiles_returns_one_file() {
+        var spec = new ServiceSpec("laptop", "/opt/kcap/kcap-daemon", "/tmp/daemon-laptop.log",
+            new Dictionary<string, string>(), []);
+        var files = ServiceManagerFactory.ForPlatform(ServicePlatform.Launchd).GenerateFiles(spec);
+        await Assert.That(files.Count).IsEqualTo(1);
+        await Assert.That(files[0].Path).EndsWith("io.kurrent.kcap.daemon.laptop.plist");
+    }
+
+    [Test]
+    public async Task Windows_GenerateFiles_returns_xml_and_wrapper() {
+        var spec = new ServiceSpec("laptop", @"C:\kcap\kcap-daemon.exe", @"C:\tmp\daemon-laptop.log",
+            new Dictionary<string, string>(), []);
+        var files = ServiceManagerFactory.ForPlatform(ServicePlatform.WindowsScheduledTask).GenerateFiles(spec);
+        await Assert.That(files.Count).IsEqualTo(2);
+    }
+}
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `dotnet run --project test/Capacitor.Cli.Tests.Unit/Capacitor.Cli.Tests.Unit.csproj --treenode-filter "/*/*/ServiceManagerFactoryTests/*"`
+Expected: FAIL (compile error — managers/factory don't exist).
+
+- [ ] **Step 3: Write the process runner**
+
+`src/Capacitor.Cli/Services/ServiceProcess.cs`:
+```csharp
+using System.Diagnostics;
+
+namespace Capacitor.Cli.Services;
+
+/// <summary>
+/// Minimal synchronous shell-out for service registration tools
+/// (launchctl/systemctl/schtasks). Not used in tests — managers' side-effecting
+/// methods are the one part not exercised in CI.
+/// </summary>
+static class ServiceProcess {
+    public static (int ExitCode, string StdOut, string StdErr) Run(string file, params string[] args) {
+        var psi = new ProcessStartInfo {
+            FileName               = file,
+            UseShellExecute        = false,
+            RedirectStandardOutput = true,
+            RedirectStandardError  = true,
+            CreateNoWindow         = true,
+        };
+        foreach (var a in args) psi.ArgumentList.Add(a);
+
+        using var p = Process.Start(psi) ?? throw new InvalidOperationException($"Failed to start {file}");
+        var stdout = p.StandardOutput.ReadToEnd();
+        var stderr = p.StandardError.ReadToEnd();
+        p.WaitForExit();
+        return (p.ExitCode, stdout, stderr);
+    }
+
+    /// <summary>Run and throw with captured stderr on non-zero exit.</summary>
+    public static void Check(string file, params string[] args) {
+        var (code, _, err) = Run(file, args);
+        if (code != 0)
+            throw new InvalidOperationException($"{file} {string.Join(' ', args)} failed (exit {code}): {err.Trim()}");
+    }
+}
+```
+
+- [ ] **Step 4: Write the launchd manager**
+
+`src/Capacitor.Cli/Services/LaunchdServiceManager.cs`:
+```csharp
+using System.Runtime.InteropServices;
+
+namespace Capacitor.Cli.Services;
+
+sealed partial class LaunchdServiceManager : IServiceManager {
+    [LibraryImport("libc", EntryPoint = "getuid")]
+    private static partial uint getuid();
+
+    static int Uid() => (int)getuid();
+
+    public string Describe() => "launchd LaunchAgent";
+
+    public IReadOnlyList<GeneratedFile> GenerateFiles(ServiceSpec spec) =>
+        [new GeneratedFile(LaunchdUnit.PlistPath(spec.ServiceId), LaunchdUnit.Plist(spec))];
+
+    public IReadOnlyList<string> ListInstalled() {
+        var dir = LaunchdUnit.AgentsDir();
+        if (!Directory.Exists(dir)) return [];
+        return [.. Directory.EnumerateFiles(dir, "io.kurrent.kcap.daemon.*.plist")
+            .Select(f => LaunchdUnit.IdFromPlistFileName(Path.GetFileName(f)))
+            .Where(id => id is not null).Select(id => id!).Order()];
+    }
+
+    public ServiceStatus Status(string serviceId) {
+        var path = LaunchdUnit.PlistPath(serviceId);
+        if (!File.Exists(path)) return new ServiceStatus(ServiceState.NotInstalled, null);
+        // First <string> in the plist is the daemon binary (ProgramArguments[0]) — for doctor.
+        var bin = System.Xml.Linq.XDocument.Load(path).Descendants("string").FirstOrDefault()?.Value;
+        var (code, stdout, _) = ServiceProcess.Run("launchctl", LaunchdUnit.PrintArgs(Uid(), serviceId));
+        return new ServiceStatus(LaunchdUnit.StatusFromPrint(code, stdout), bin);
+    }
+
+    public void Install(ServiceSpec spec, bool startNow) {
+        Directory.CreateDirectory(LaunchdUnit.AgentsDir());
+        var plistPath = LaunchdUnit.PlistPath(spec.ServiceId);
+        // idempotent: bootout an existing job (ignore failure), then rewrite + bootstrap.
+        ServiceProcess.Run("launchctl", LaunchdUnit.BootoutArgs(Uid(), spec.ServiceId));
+        File.WriteAllText(plistPath, LaunchdUnit.Plist(spec));
+        ServiceProcess.Check("launchctl", LaunchdUnit.BootstrapArgs(Uid(), plistPath)); // RunAtLoad starts it
+        if (!startNow) ServiceProcess.Run("launchctl", LaunchdUnit.KillArgs(Uid(), spec.ServiceId));
+    }
+
+    public void Uninstall(string serviceId) {
+        ServiceProcess.Run("launchctl", LaunchdUnit.BootoutArgs(Uid(), serviceId));
+        var path = LaunchdUnit.PlistPath(serviceId);
+        if (File.Exists(path)) File.Delete(path);
+    }
+
+    public void Start(string serviceId) => ServiceProcess.Check("launchctl", LaunchdUnit.KickstartArgs(Uid(), serviceId));
+    public void Stop(string serviceId)  => ServiceProcess.Check("launchctl", LaunchdUnit.KillArgs(Uid(), serviceId));
+}
+```
+
+- [ ] **Step 5: Write the systemd manager**
+
+`src/Capacitor.Cli/Services/SystemdServiceManager.cs`:
+```csharp
+namespace Capacitor.Cli.Services;
+
+sealed class SystemdServiceManager : IServiceManager {
+    public string Describe() => "systemd --user unit";
+
+    public IReadOnlyList<GeneratedFile> GenerateFiles(ServiceSpec spec) =>
+        [new GeneratedFile(SystemdUnit.UnitPath(spec.ServiceId), SystemdUnit.Unit(spec))];
+
+    public IReadOnlyList<string> ListInstalled() {
+        var dir = SystemdUnit.UserUnitDir();
+        if (!Directory.Exists(dir)) return [];
+        return [.. Directory.EnumerateFiles(dir, "kcap-daemon-*.service")
+            .Select(f => SystemdUnit.IdFromUnitFileName(Path.GetFileName(f)))
+            .Where(id => id is not null).Select(id => id!).Order()];
+    }
+
+    public ServiceStatus Status(string serviceId) {
+        var path = SystemdUnit.UnitPath(serviceId);
+        if (!File.Exists(path)) return new ServiceStatus(ServiceState.NotInstalled, null);
+        var (_, active, _)      = ServiceProcess.Run("systemctl", SystemdUnit.IsActiveArgs(serviceId));
+        var (enabledExit, _, _) = ServiceProcess.Run("systemctl", SystemdUnit.IsEnabledArgs(serviceId));
+        var bin = ExecStartBinary(path);
+        return new ServiceStatus(SystemdUnit.StatusFrom(active, enabledExit), bin);
+    }
+
+    static string? ExecStartBinary(string unitPath) {
+        var line = File.ReadLines(unitPath).FirstOrDefault(l => l.StartsWith("ExecStart=", StringComparison.Ordinal));
+        return line?["ExecStart=".Length..].Split(' ', 2)[0];
+    }
+
+    public void Install(ServiceSpec spec, bool startNow) {
+        Directory.CreateDirectory(SystemdUnit.UserUnitDir());
+        File.WriteAllText(SystemdUnit.UnitPath(spec.ServiceId), SystemdUnit.Unit(spec));
+        ServiceProcess.Check("systemctl", SystemdUnit.DaemonReloadArgs());
+        ServiceProcess.Check("systemctl", SystemdUnit.EnableArgs(spec.ServiceId));
+        if (startNow) ServiceProcess.Check("systemctl", SystemdUnit.RestartArgs(spec.ServiceId));
+    }
+
+    public void Uninstall(string serviceId) {
+        ServiceProcess.Run("systemctl", SystemdUnit.DisableNowArgs(serviceId));
+        var path = SystemdUnit.UnitPath(serviceId);
+        if (File.Exists(path)) File.Delete(path);
+        ServiceProcess.Run("systemctl", SystemdUnit.DaemonReloadArgs());
+    }
+
+    public void Start(string serviceId) => ServiceProcess.Check("systemctl", SystemdUnit.StartArgs(serviceId));
+    public void Stop(string serviceId)  => ServiceProcess.Check("systemctl", SystemdUnit.StopArgs(serviceId));
+}
+```
+
+- [ ] **Step 6: Write the Windows manager**
+
+`src/Capacitor.Cli/Services/WindowsScheduledTaskServiceManager.cs`:
+```csharp
+namespace Capacitor.Cli.Services;
+
+sealed class WindowsScheduledTaskServiceManager : IServiceManager {
+    public string Describe() => "Windows Scheduled Task";
+
+    public IReadOnlyList<GeneratedFile> GenerateFiles(ServiceSpec spec) {
+        var wrapperPath = WindowsTaskUnit.WrapperPath(spec.ServiceId);
+        return [
+            new GeneratedFile(wrapperPath, WindowsTaskUnit.Wrapper(spec)),
+            new GeneratedFile(TaskXmlTempPath(spec.ServiceId), WindowsTaskUnit.TaskXml(spec, wrapperPath)),
+        ];
+    }
+
+    static string TaskXmlTempPath(string id) =>
+        Capacitor.Cli.Core.PathHelpers.ConfigPath($"daemon-service-{id}.task.xml");
+
+    public IReadOnlyList<string> ListInstalled() {
+        var (code, stdout, _) = ServiceProcess.Run("schtasks", "/Query", "/FO", "LIST");
+        if (code != 0) return [];
+        return [.. stdout.Split('\n')
+            .Where(l => l.TrimStart().StartsWith("TaskName:", StringComparison.OrdinalIgnoreCase))
+            .Select(l => WindowsTaskUnit.IdFromTaskName(Path.GetFileName(l.Split(':', 2)[1].Trim())))
+            .Where(id => id is not null).Select(id => id!).Distinct().Order()];
+    }
+
+    public ServiceStatus Status(string serviceId) {
+        var (code, stdout, _) = ServiceProcess.Run("schtasks", WindowsTaskUnit.QueryArgs(serviceId));
+        var bin = File.Exists(WindowsTaskUnit.WrapperPath(serviceId)) ? WindowsTaskUnit.WrapperPath(serviceId) : null;
+        return new ServiceStatus(WindowsTaskUnit.StatusFromQuery(code, stdout), bin);
+    }
+
+    public void Install(ServiceSpec spec, bool startNow) {
+        var files = GenerateFiles(spec);
+        foreach (var f in files) { Directory.CreateDirectory(Path.GetDirectoryName(f.Path)!); File.WriteAllText(f.Path, f.Content); }
+        var xmlPath = files.First(f => f.Path.EndsWith(".task.xml", StringComparison.Ordinal)).Path;
+        ServiceProcess.Check("schtasks", WindowsTaskUnit.CreateArgs(spec.ServiceId, xmlPath));
+        File.Delete(xmlPath); // the task XML is only needed for registration
+        if (startNow) ServiceProcess.Check("schtasks", WindowsTaskUnit.RunArgs(spec.ServiceId));
+    }
+
+    public void Uninstall(string serviceId) {
+        ServiceProcess.Run("schtasks", WindowsTaskUnit.DeleteArgs(serviceId));
+        var wrapper = WindowsTaskUnit.WrapperPath(serviceId);
+        if (File.Exists(wrapper)) File.Delete(wrapper);
+    }
+
+    public void Start(string serviceId) => ServiceProcess.Check("schtasks", WindowsTaskUnit.RunArgs(serviceId));
+    public void Stop(string serviceId)  => ServiceProcess.Check("schtasks", WindowsTaskUnit.EndArgs(serviceId));
+}
+```
+
+- [ ] **Step 7: Write the factory**
+
+`src/Capacitor.Cli/Services/ServiceManagerFactory.cs`:
+```csharp
+namespace Capacitor.Cli.Services;
+
+static class ServiceManagerFactory {
+    public static IServiceManager ForPlatform(ServicePlatform platform) => platform switch {
+        ServicePlatform.Launchd              => new LaunchdServiceManager(),
+        ServicePlatform.Systemd              => new SystemdServiceManager(),
+        ServicePlatform.WindowsScheduledTask => new WindowsScheduledTaskServiceManager(),
+        _ => throw new PlatformNotSupportedException($"No service manager for {platform}"),
+    };
+
+    public static IServiceManager ForCurrentOs() {
+        if (OperatingSystem.IsMacOS())   return ForPlatform(ServicePlatform.Launchd);
+        if (OperatingSystem.IsLinux())   return ForPlatform(ServicePlatform.Systemd);
+        if (OperatingSystem.IsWindows()) return ForPlatform(ServicePlatform.WindowsScheduledTask);
+        throw new PlatformNotSupportedException("kcap daemon service is not supported on this OS.");
+    }
+}
+```
+
+- [ ] **Step 8: Run the factory test to verify it passes**
+
+Run: `dotnet run --project test/Capacitor.Cli.Tests.Unit/Capacitor.Cli.Tests.Unit.csproj --treenode-filter "/*/*/ServiceManagerFactoryTests/*"`
+Expected: PASS (4 tests).
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add src/Capacitor.Cli/Services/ServiceProcess.cs src/Capacitor.Cli/Services/LaunchdServiceManager.cs src/Capacitor.Cli/Services/SystemdServiceManager.cs src/Capacitor.Cli/Services/WindowsScheduledTaskServiceManager.cs src/Capacitor.Cli/Services/ServiceManagerFactory.cs test/Capacitor.Cli.Tests.Unit/Services/ServiceManagerFactoryTests.cs
+git commit -m "feat(daemon): thin service managers + process runner + factory"
+```
+
+---
+
+## Task 6: Environment capture + pinned profile (`ServiceEnvironment`)
+
+**Files:**
+- Create: `src/Capacitor.Cli/Services/ServiceEnvironment.cs`
+- Test: `test/Capacitor.Cli.Tests.Unit/Services/ServiceEnvironmentTests.cs`
+
+- [ ] **Step 1: Write the failing test**
+
+`test/Capacitor.Cli.Tests.Unit/Services/ServiceEnvironmentTests.cs`:
+```csharp
+using Capacitor.Cli.Services;
+
+namespace Capacitor.Cli.Tests.Unit.Services;
+
+public class ServiceEnvironmentTests {
+    [Test]
+    public async Task Build_pins_profile_and_includes_path() {
+        var src = new Dictionary<string, string> {
+            ["PATH"]              = "/usr/local/bin:/usr/bin",
+            ["KCAP_CONFIG_DIR"]   = "/home/u/.config/kcap",
+            ["IRRELEVANT"]        = "x",
+        };
+        var env = ServiceEnvironment.Build(profileName: "work", source: src);
+        await Assert.That(env["PATH"]).IsEqualTo("/usr/local/bin:/usr/bin");
+        await Assert.That(env["KCAP_PROFILE"]).IsEqualTo("work");
+        await Assert.That(env["KCAP_CONFIG_DIR"]).IsEqualTo("/home/u/.config/kcap");
+        await Assert.That(env.ContainsKey("IRRELEVANT")).IsFalse();
+    }
+
+    [Test]
+    public async Task Build_omits_profile_when_null_and_keeps_kcap_url() {
+        var src = new Dictionary<string, string> { ["KCAP_URL"] = "https://x" };
+        var env = ServiceEnvironment.Build(profileName: null, source: src);
+        await Assert.That(env.ContainsKey("KCAP_PROFILE")).IsFalse();
+        await Assert.That(env["KCAP_URL"]).IsEqualTo("https://x");
+    }
+
+    [Test]
+    public async Task Build_explicit_profile_overrides_source_env() {
+        var src = new Dictionary<string, string> { ["KCAP_PROFILE"] = "old" };
+        var env = ServiceEnvironment.Build(profileName: "new", source: src);
+        await Assert.That(env["KCAP_PROFILE"]).IsEqualTo("new");
+    }
+}
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `dotnet run --project test/Capacitor.Cli.Tests.Unit/Capacitor.Cli.Tests.Unit.csproj --treenode-filter "/*/*/ServiceEnvironmentTests/*"`
+Expected: FAIL (compile error — `ServiceEnvironment` does not exist).
+
+- [ ] **Step 3: Write `ServiceEnvironment`**
+
+`src/Capacitor.Cli/Services/ServiceEnvironment.cs`:
+```csharp
+using System.Collections;
+
+namespace Capacitor.Cli.Services;
+
+/// <summary>
+/// Builds the environment baked into a service unit. Supervised jobs don't
+/// inherit the interactive shell PATH (so bare claude/codex lookup fails) and a
+/// baked --server-url would null out profile resolution — so we capture PATH +
+/// the KCAP_* keys and pin the profile via KCAP_PROFILE.
+/// </summary>
+static class ServiceEnvironment {
+    static readonly string[] Keys = ["PATH", "KCAP_CONFIG_DIR", "KCAP_PROFILE", "KCAP_URL", "KCAP_CLAUDE_PATH", "KCAP_CODEX_PATH"];
+
+    /// <summary>Production entry point: capture from the current process env.</summary>
+    public static IReadOnlyDictionary<string, string> Capture(string? profileName) =>
+        Build(profileName, Snapshot());
+
+    static Dictionary<string, string> Snapshot() {
+        var d = new Dictionary<string, string>();
+        foreach (DictionaryEntry e in Environment.GetEnvironmentVariables())
+            if (e.Key is string k && e.Value is string v) d[k] = v;
+        return d;
+    }
+
+    /// <summary>Pure: select the relevant keys from <paramref name="source"/>, pin the profile.</summary>
+    public static IReadOnlyDictionary<string, string> Build(string? profileName, IReadOnlyDictionary<string, string> source) {
+        var env = new Dictionary<string, string>(StringComparer.Ordinal);
+        foreach (var key in Keys)
+            if (source.TryGetValue(key, out var v) && !string.IsNullOrEmpty(v)) env[key] = v;
+        if (!string.IsNullOrEmpty(profileName)) env["KCAP_PROFILE"] = profileName; // explicit pin wins
+        return env;
+    }
+}
+```
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run: `dotnet run --project test/Capacitor.Cli.Tests.Unit/Capacitor.Cli.Tests.Unit.csproj --treenode-filter "/*/*/ServiceEnvironmentTests/*"`
+Expected: PASS (3 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/Capacitor.Cli/Services/ServiceEnvironment.cs test/Capacitor.Cli.Tests.Unit/Services/ServiceEnvironmentTests.cs
+git commit -m "feat(daemon): capture env + pin profile for service units"
+```
+
+---
+
+## Task 7: `kcap daemon service` subcommand dispatch
+
+**Files:**
+- Modify: `src/Capacitor.Cli/Commands/DaemonCommands.cs` (add `service` case + handler)
+- Test: manual smoke (the dispatch is thin glue; pure logic is already covered)
+
+- [ ] **Step 1: Add the `service` dispatch arm**
+
+In `DaemonCommands.HandleAsync`, the `subcommand switch` (around `DaemonCommands.cs:20-27`), add an arm:
+```csharp
+        return subcommand switch {
+            "start"   => await StartAsync(remaining),
+            "stop"    => await StopAsync(remaining),
+            "status"  => await Status(remaining),
+            "logs"    => await Logs(),
+            "doctor"  => await DoctorAsync(remaining),
+            "service" => await ServiceAsync(remaining),
+            _         => PrintUsage()
+        };
+```
+
+- [ ] **Step 2: Add the `ServiceAsync` handler**
+
+Add to `DaemonCommands` (new region near the bottom, before `ResolveDaemonBinary`):
+```csharp
+    // ── service (OS supervisor: launchd / systemd / scheduled task) ───────────
+
+    static async Task<int> ServiceAsync(string[] args) {
+        if (args.Length == 0) return ServiceUsage();
+
+        var action    = args[0];
+        var rest      = args[1..];
+        var noStart   = rest.Contains("--no-start");
+
+        IServiceManager manager;
+        try {
+            manager = ServiceManagerFactory.ForCurrentOs();
+        } catch (PlatformNotSupportedException ex) {
+            await Console.Error.WriteLineAsync(ex.Message);
+            return 1;
+        }
+
+        var id = ServiceText.ServiceId(ResolveName(rest));
+
+        switch (action) {
+            case "install":   return await ServiceInstall(manager, rest, id, startNow: !noStart);
+            case "uninstall": manager.Uninstall(id); await Console.Out.WriteLineAsync($"Service '{id}' uninstalled ({manager.Describe()})."); return 0;
+            case "start":     manager.Start(id);     await Console.Out.WriteLineAsync($"Service '{id}' started.");   return 0;
+            case "stop":      manager.Stop(id);      await Console.Out.WriteLineAsync($"Service '{id}' stopped (still installed)."); return 0;
+            case "status":    return await ServiceStatus(manager, id);
+            default:          return ServiceUsage();
+        }
+    }
+
+    static async Task<int> ServiceInstall(IServiceManager manager, string[] args, string id, bool startNow) {
+        var daemonPath = ResolveDaemonBinary();
+        if (daemonPath is null) { await Console.Error.WriteLineAsync(DaemonNotFoundMessage()); return 1; }
+
+        var profileName = ExtractFlagValue(args, "--profile") ?? AppConfig.ResolvedProfile?.ProfileName;
+        var env         = ServiceEnvironment.Capture(profileName);
+
+        var extra = new List<string>();
+        if (ExtractFlagValue(args, "--max-agents") is { } mx) { extra.Add("--max-agents"); extra.Add(mx); }
+
+        var logPath = PathHelpers.ConfigPath($"daemon-{id}.log");
+        var spec    = new ServiceSpec(id, daemonPath, logPath, env, extra);
+
+        manager.Install(spec, startNow);
+
+        await Console.Out.WriteLineAsync($"Service '{id}' installed ({manager.Describe()}).");
+        await Console.Out.WriteLineAsync($"  Auto-restarts on crash/SIGKILL; starts at login.");
+        await Console.Out.WriteLineAsync($"  Log:       {logPath}");
+        await Console.Out.WriteLineAsync($"  Stop:      kcap daemon service stop --name {id}");
+        await Console.Out.WriteLineAsync($"  Remove:    kcap daemon service uninstall --name {id}");
+        return 0;
+    }
+
+    static async Task<int> ServiceStatus(IServiceManager manager, string id) {
+        var status = manager.Status(id);
+        await Console.Out.WriteLineAsync($"Service '{id}': {status.State} ({manager.Describe()})");
+        if (status.BinaryPath is { } bin) await Console.Out.WriteLineAsync($"  binary: {bin}");
+        return 0;
+    }
+
+    static int ServiceUsage() {
+        Console.Error.WriteLine("Usage: kcap daemon service <install|uninstall|start|stop|status> [--name N]");
+        Console.Error.WriteLine();
+        Console.Error.WriteLine("  install [--name N] [--profile P] [--max-agents N] [--no-start]");
+        Console.Error.WriteLine("  uninstall [--name N]   Stop and remove the service unit");
+        Console.Error.WriteLine("  start [--name N]       Start the installed service now");
+        Console.Error.WriteLine("  stop [--name N]        Stop the running service (stays installed)");
+        Console.Error.WriteLine("  status [--name N]      Show installed/running state");
+        return 1;
+    }
+```
+
+- [ ] **Step 3: Add the using directive**
+
+At the top of `DaemonCommands.cs`, add:
+```csharp
+using Capacitor.Cli.Services;
+```
+
+- [ ] **Step 4: Build and smoke-test usage**
+
+Run: `dotnet build src/Capacitor.Cli/Capacitor.Cli.csproj`
+Expected: build succeeds.
+
+Run: `dotnet run --project src/Capacitor.Cli/Capacitor.Cli.csproj -- daemon service`
+Expected: prints the service usage block, exit 1.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/Capacitor.Cli/Commands/DaemonCommands.cs
+git commit -m "feat(daemon): kcap daemon service install/uninstall/start/stop/status"
+```
+
+---
+
+## Task 8: status / stop / doctor service-awareness
+
+**Files:**
+- Modify: `src/Capacitor.Cli/Commands/DaemonCommands.cs`
+
+- [ ] **Step 1: `status` shows installed-but-stopped services**
+
+In `Status` (`DaemonCommands.cs:308`), after computing `names` from PID files, union with installed service ids and print a `service:` line. Replace the body that builds/uses `names` with:
+```csharp
+        var manager = TryServiceManager();
+        var serviceIds = manager?.ListInstalled() ?? [];
+        var names = explicitName is not null
+            ? new List<string> { explicitName }
+            : EnumerateRunningNames().Concat(serviceIds.Select(id => id)).Distinct().Order().ToList();
+
+        if (names.Count == 0) {
+            await Console.Out.WriteLineAsync("Daemon: not running");
+            return 0;
+        }
+
+        foreach (var name in names) {
+            var id = ServiceText.ServiceId(name);
+            // existing running/stale PID reporting:
+            if (ReadPidFile(name) is { } entry && IsOurDaemon(entry.Pid, entry.StartTicks))
+                await Console.Out.WriteLineAsync($"Daemon '{name}': running (PID {entry.Pid})");
+            else
+                await Console.Out.WriteLineAsync($"Daemon '{name}': not running");
+
+            if (manager is not null) {
+                var st = manager.Status(id).State;
+                if (st != ServiceState.NotInstalled)
+                    await Console.Out.WriteLineAsync($"  service: {st} ({manager.Describe()})");
+            }
+        }
+        return 0;
+```
+
+Add helper near `ResolveDaemonBinary`:
+```csharp
+    static IServiceManager? TryServiceManager() {
+        try { return ServiceManagerFactory.ForCurrentOs(); }
+        catch (PlatformNotSupportedException) { return null; }
+    }
+```
+
+- [ ] **Step 2: `stop` defers to the supervisor for service-managed ids**
+
+In `StopByName` (`DaemonCommands.cs:277`), at the top, add:
+```csharp
+        var manager = TryServiceManager();
+        if (manager is not null && manager.Status(ServiceText.ServiceId(name)).State != ServiceState.NotInstalled) {
+            Console.Out.WriteLine(
+                $"Daemon '{name}' is managed by {manager.Describe()}; a raw stop would be auto-restarted.");
+            Console.Out.WriteLine($"Use: kcap daemon service stop --name {name}  (or uninstall to remove it)");
+            return 0;
+        }
+```
+
+- [ ] **Step 3: `doctor` validates installed-service binary paths**
+
+At the end of `DoctorAsync` (before `return 0;` at `DaemonCommands.cs:464`), add:
+```csharp
+        var svcManager = TryServiceManager();
+        if (svcManager is not null) {
+            var installed = svcManager.ListInstalled();
+            if (installed.Count > 0) {
+                await Console.Out.WriteLineAsync($"\nInstalled services ({svcManager.Describe()}):");
+                foreach (var sid in installed) {
+                    var st  = svcManager.Status(sid);
+                    var bad = st.BinaryPath is { } b && !File.Exists(b);
+                    var note = bad ? "  ⚠ binary missing — re-run `kcap daemon service install`" : "";
+                    await Console.Out.WriteLineAsync($"  {sid,-20}  {st.State}{note}");
+                }
+            }
+        }
+```
+
+- [ ] **Step 4: Build and verify**
+
+Run: `dotnet build src/Capacitor.Cli/Capacitor.Cli.csproj`
+Expected: build succeeds.
+
+Run: `dotnet run --project src/Capacitor.Cli/Capacitor.Cli.csproj -- daemon status`
+Expected: prints daemon status; no crash when no services installed.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/Capacitor.Cli/Commands/DaemonCommands.cs
+git commit -m "feat(daemon): status/stop/doctor awareness of installed services"
+```
+
+---
+
+## Task 9: Docs (help-daemon.txt + README)
+
+**Files:**
+- Modify: `src/Capacitor.Cli.Core/Resources/help-daemon.txt`
+- Modify: `README.md`
+
+- [ ] **Step 1: Add the `service` group to `help-daemon.txt`**
+
+After the `doctor` line in the Subcommands block (`help-daemon.txt:10`), add:
+```
+  service <action>       Manage the OS service (launchd/systemd/Scheduled Task)
+```
+And after the `doctor` options block, append:
+```
+
+Subcommands for service (per-user; auto-restarts on crash/SIGKILL, starts at login):
+  install [--name N] [--profile P] [--max-agents N] [--no-start]
+                          Register the daemon as an OS service and start it.
+                          Pins the profile via KCAP_PROFILE and captures PATH so
+                          claude/codex resolve as they do in your shell.
+  uninstall [--name N]    Stop and remove the service unit.
+  start [--name N]        Start the installed service now.
+  stop [--name N]         Stop the running service (stays installed; returns at
+                          next login or `service start`).
+  status [--name N]       Show installed / running state.
+```
+
+- [ ] **Step 2: Update `README.md` getting-started**
+
+Find the `## Getting started` section. After the daemon-start instructions, add:
+```markdown
+### Keep the daemon running
+
+`kcap daemon start -d` runs until the process dies (a crash, or an OS
+memory-pressure kill — macOS jetsam / Linux OOM). To have it auto-restart and
+start at login, install it as a per-user service:
+
+```bash
+kcap daemon service install
+```
+
+This registers a launchd LaunchAgent (macOS), a systemd `--user` unit (Linux),
+or a logon Scheduled Task (Windows). Manage it with
+`kcap daemon service start|stop|status` and remove it with
+`kcap daemon service uninstall`.
+```
+
+- [ ] **Step 3: Update `README.md` CLI commands → daemon section**
+
+In the `## CLI commands` daemon subsection, add the `service` verbs to the command list (mirror the `help-daemon.txt` wording), including the note that `install` pins `KCAP_PROFILE` and captures `PATH`, and that a service-managed daemon should be stopped with `service stop`/`uninstall` rather than `daemon stop`.
+
+- [ ] **Step 4: Verify the help renders**
+
+Run: `dotnet run --project src/Capacitor.Cli/Capacitor.Cli.csproj -- daemon --help`
+Expected: output includes the `service <action>` line and the service subcommand block.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/Capacitor.Cli.Core/Resources/help-daemon.txt README.md
+git commit -m "docs(daemon): document service install/uninstall/start/stop/status"
+```
+
+---
+
+## Task 10: Full test run + AOT verification
+
+**Files:** none (verification only)
+
+- [ ] **Step 1: Run the full unit suite**
+
+Run: `dotnet run --project test/Capacitor.Cli.Tests.Unit/Capacitor.Cli.Tests.Unit.csproj`
+Expected: all tests pass, including the new `Services/*` tests.
+
+- [ ] **Step 2: AOT publish + warning scan (per CLAUDE.md)**
+
+Run: `dotnet publish src/Capacitor.Cli/Capacitor.Cli.csproj -c Release 2>&1 | grep -E 'IL[23][01][0-9]{2}'`
+Expected: no output (no IL3050/IL2026 warnings). If any appear, they will be from `XDocument.Load` in `LaunchdServiceManager.Status` / `SystemdServiceManager` file reads — replace `XDocument.Load` with a line scan (`File.ReadLines`) if flagged; `XDocument.Parse` is used only in tests, not the publish target.
+
+- [ ] **Step 3: Commit any AOT fixups, then summarize**
+
+```bash
+git add -A
+git commit -m "test(daemon): full suite + AOT-clean for service supervisor" || echo "nothing to commit"
+```
+
+---
+
+## Self-review notes (author)
+
+- **Spec coverage:** install/uninstall/start/stop/status (Tasks 5,7); launchd/systemd/windows units (2,3,4,5); name sanitization + escaping (1,2,3,4); profile-pin + env capture, no `--server-url` (6,7); per-instance systemd units (3,5); idempotent install (5); `ListInstalled`/`Status.BinaryPath` for status+doctor (5,8); `ForPlatform` test seam (5); restart-on-failure vs clean-stop (2,3,4); Windows `.cmd` wrapper + `/End` (4,5); docs (9); AOT (10). The Windows `/End`-vs-restart empirical check is flagged in the spec and must be confirmed on a real Windows host during Task 5/manual QA.
+- **Type consistency:** `ServiceSpec`/`ServiceState`/`ServiceStatus`/`GeneratedFile`/`ServicePlatform` defined in Task 1, used unchanged in Tasks 2-8. `ServiceText.ServiceId`/`Xml`/`CmdValue`/`SystemdValue` used consistently. Manager methods match the interface signatures.
+- **Known thin/untested:** `ServiceProcess` + manager `Install/Uninstall/Start/Stop/Status/ListInstalled` shell-outs are not run in CI; their pure inputs (vectors, parsers, generators) are tested in Tasks 2-6.

From 0e05979daf333e5af398990095052932b3c90214 Mon Sep 17 00:00:00 2001
From: Alexey Zimarev <alex@zimarev.com>
Date: Wed, 10 Jun 2026 17:20:37 +0200
Subject: [PATCH 05/16] feat(daemon): service contracts + text-escaping helpers

---
 src/Capacitor.Cli/Services/IServiceManager.cs | 36 +++++++++++++++++++
 src/Capacitor.Cli/Services/ServiceText.cs     | 24 +++++++++++++
 .../Services/ServiceTextTests.cs              | 31 ++++++++++++++++
 3 files changed, 91 insertions(+)
 create mode 100644 src/Capacitor.Cli/Services/IServiceManager.cs
 create mode 100644 src/Capacitor.Cli/Services/ServiceText.cs
 create mode 100644 test/Capacitor.Cli.Tests.Unit/Services/ServiceTextTests.cs

diff --git a/src/Capacitor.Cli/Services/IServiceManager.cs b/src/Capacitor.Cli/Services/IServiceManager.cs
new file mode 100644
index 000000000..b2a1afa25
--- /dev/null
+++ b/src/Capacitor.Cli/Services/IServiceManager.cs
@@ -0,0 +1,36 @@
+namespace Capacitor.Cli.Services;
+
+/// <summary>Which OS service backend a manager targets.</summary>
+enum ServicePlatform { Launchd, Systemd, WindowsScheduledTask }
+
+/// <summary>Lifecycle state of an installed service for one id.</summary>
+enum ServiceState { NotInstalled, Installed, Running }
+
+/// <summary>A file the manager writes at install time (absolute path + content).</summary>
+record GeneratedFile(string Path, string Content);
+
+/// <summary>Status plus the binary path baked into the installed unit (for doctor).</summary>
+record ServiceStatus(ServiceState State, string? BinaryPath);
+
+/// <summary>
+/// Everything needed to render and register one per-user service.
+/// <paramref name="ServiceId"/> is the sanitized id (see <see cref="ServiceText.ServiceId"/>)
+/// used for the filename/label/instance/task AND the daemon <c>--name</c>.
+/// </summary>
+record ServiceSpec(
+    string                              ServiceId,
+    string                              DaemonBinaryPath,
+    string                              LogPath,
+    IReadOnlyDictionary<string, string> Environment,
+    IReadOnlyList<string>               ExtraArgs);
+
+interface IServiceManager {
+    string Describe();
+    IReadOnlyList<GeneratedFile> GenerateFiles(ServiceSpec spec);
+    IReadOnlyList<string>        ListInstalled();
+    ServiceStatus                Status(string serviceId);
+    void Install(ServiceSpec spec, bool startNow);
+    void Uninstall(string serviceId);
+    void Start(string serviceId);
+    void Stop(string serviceId);
+}
diff --git a/src/Capacitor.Cli/Services/ServiceText.cs b/src/Capacitor.Cli/Services/ServiceText.cs
new file mode 100644
index 000000000..db921a666
--- /dev/null
+++ b/src/Capacitor.Cli/Services/ServiceText.cs
@@ -0,0 +1,24 @@
+using System.Security;
+using Capacitor.Cli.Core;
+
+namespace Capacitor.Cli.Services;
+
+/// <summary>
+/// Pure text helpers for rendering service units. Each value interpolated into
+/// a unit/wrapper is escaped for its target format so generators never emit
+/// malformed markup, regardless of daemon name / path content.
+/// </summary>
+static class ServiceText {
+    /// <summary>Sanitized, portable service id — reuses the daemon lock-file rule.</summary>
+    public static string ServiceId(string name) => DaemonLockPaths.Sanitize(name);
+
+    /// <summary>XML-escape for plist and Task Scheduler XML (escapes &amp; &lt; &gt; " ').</summary>
+    public static string Xml(string value) => SecurityElement.Escape(value) ?? "";
+
+    /// <summary>Escape a value for a batch <c>set "KEY=value"</c> line: percent-signs doubled.</summary>
+    public static string CmdValue(string value) => value.Replace("%", "%%");
+
+    /// <summary>Escape a systemd <c>Environment=</c>/<c>Description=</c> value: no raw newlines.</summary>
+    public static string SystemdValue(string value) =>
+        value.Replace("\r", " ").Replace("\n", " ");
+}
diff --git a/test/Capacitor.Cli.Tests.Unit/Services/ServiceTextTests.cs b/test/Capacitor.Cli.Tests.Unit/Services/ServiceTextTests.cs
new file mode 100644
index 000000000..95fe78cd9
--- /dev/null
+++ b/test/Capacitor.Cli.Tests.Unit/Services/ServiceTextTests.cs
@@ -0,0 +1,31 @@
+using Capacitor.Cli.Services;
+
+namespace Capacitor.Cli.Tests.Unit.Services;
+
+public class ServiceTextTests {
+    [Test]
+    public async Task ServiceId_sanitizes_and_lowercases() {
+        await Assert.That(ServiceText.ServiceId("My Laptop")).IsEqualTo("my-laptop");
+    }
+
+    [Test]
+    public async Task ServiceId_is_idempotent() {
+        var once = ServiceText.ServiceId("a/b c");
+        await Assert.That(ServiceText.ServiceId(once)).IsEqualTo(once);
+    }
+
+    [Test]
+    public async Task Xml_escapes_the_five_markup_chars() {
+        await Assert.That(ServiceText.Xml("a&b<c>\"d'")).IsEqualTo("a&amp;b&lt;c&gt;&quot;d&apos;");
+    }
+
+    [Test]
+    public async Task CmdValue_doubles_percent_signs() {
+        await Assert.That(ServiceText.CmdValue("100%PATH%")).IsEqualTo("100%%PATH%%");
+    }
+
+    [Test]
+    public async Task SystemdValue_collapses_newlines_to_spaces() {
+        await Assert.That(ServiceText.SystemdValue("a\nb")).IsEqualTo("a b");
+    }
+}

From fe2116999ce1dddc8c596777f19e6de5100ae9e1 Mon Sep 17 00:00:00 2001
From: Alexey Zimarev <alex@zimarev.com>
Date: Wed, 10 Jun 2026 17:22:13 +0200
Subject: [PATCH 06/16] feat(daemon): launchd plist + command vectors (pure)

---
 src/Capacitor.Cli/Services/LaunchdUnit.cs     | 77 +++++++++++++++++++
 .../Services/LaunchdUnitTests.cs              | 54 +++++++++++++
 2 files changed, 131 insertions(+)
 create mode 100644 src/Capacitor.Cli/Services/LaunchdUnit.cs
 create mode 100644 test/Capacitor.Cli.Tests.Unit/Services/LaunchdUnitTests.cs

diff --git a/src/Capacitor.Cli/Services/LaunchdUnit.cs b/src/Capacitor.Cli/Services/LaunchdUnit.cs
new file mode 100644
index 000000000..c9ceee3fd
--- /dev/null
+++ b/src/Capacitor.Cli/Services/LaunchdUnit.cs
@@ -0,0 +1,77 @@
+using System.Text;
+using Capacitor.Cli.Core;
+
+namespace Capacitor.Cli.Services;
+
+/// <summary>Pure rendering + command vectors for a per-user launchd LaunchAgent.</summary>
+static class LaunchdUnit {
+    const string LabelPrefix = "io.kurrent.kcap.daemon.";
+
+    public static string Label(string id) => LabelPrefix + id;
+
+    /// <summary>~/Library/LaunchAgents directory for the current user.</summary>
+    public static string AgentsDir() =>
+        Path.Combine(PathHelpers.HomeDirectory, "Library", "LaunchAgents");
+
+    public static string PlistPath(string id) =>
+        Path.Combine(AgentsDir(), Label(id) + ".plist");
+
+    /// <summary>Separate stdout/stderr capture file (keeps the rolling --log-file uncluttered).</summary>
+    static string OutLogPath(ServiceSpec spec) =>
+        Path.ChangeExtension(spec.LogPath, null) + ".out.log";
+
+    public static string Plist(ServiceSpec spec) {
+        var sb = new StringBuilder();
+        sb.Append("""
+            <?xml version="1.0" encoding="UTF-8"?>
+            <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+            <plist version="1.0">
+            <dict>
+
+            """);
+        sb.Append($"  <key>Label</key><string>{ServiceText.Xml(Label(spec.ServiceId))}</string>\n");
+
+        sb.Append("  <key>ProgramArguments</key><array>\n");
+        foreach (var arg in ProgramArguments(spec))
+            sb.Append($"    <string>{ServiceText.Xml(arg)}</string>\n");
+        sb.Append("  </array>\n");
+
+        sb.Append("  <key>EnvironmentVariables</key><dict>\n");
+        foreach (var (k, v) in spec.Environment)
+            sb.Append($"    <key>{ServiceText.Xml(k)}</key><string>{ServiceText.Xml(v)}</string>\n");
+        sb.Append("  </dict>\n");
+
+        sb.Append("  <key>RunAtLoad</key><true/>\n");
+        sb.Append("  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>\n");
+        sb.Append("  <key>ProcessType</key><string>Adaptive</string>\n");
+        sb.Append($"  <key>StandardOutPath</key><string>{ServiceText.Xml(OutLogPath(spec))}</string>\n");
+        sb.Append($"  <key>StandardErrorPath</key><string>{ServiceText.Xml(OutLogPath(spec))}</string>\n");
+        sb.Append("</dict>\n</plist>\n");
+        return sb.ToString();
+    }
+
+    /// <summary>argv the agent runs: binary, pinned --name + --log-file, then extra args.</summary>
+    public static IReadOnlyList<string> ProgramArguments(ServiceSpec spec) =>
+        [spec.DaemonBinaryPath, "--name", spec.ServiceId, "--log-file", spec.LogPath, .. spec.ExtraArgs];
+
+    public static string? IdFromPlistFileName(string fileName) {
+        var name = Path.GetFileNameWithoutExtension(fileName); // strips .plist
+        return name.StartsWith(LabelPrefix, StringComparison.Ordinal)
+            ? name[LabelPrefix.Length..]
+            : null;
+    }
+
+    // ── command vectors (uid passed in so these stay pure) ──
+    public static string[] BootstrapArgs(int uid, string plistPath) => ["bootstrap", $"gui/{uid}", plistPath];
+    public static string[] BootoutArgs(int uid, string id)          => ["bootout", $"gui/{uid}/{Label(id)}"];
+    public static string[] KickstartArgs(int uid, string id)        => ["kickstart", $"gui/{uid}/{Label(id)}"];
+    public static string[] KillArgs(int uid, string id)             => ["kill", "SIGTERM", $"gui/{uid}/{Label(id)}"];
+    public static string[] PrintArgs(int uid, string id)            => ["print", $"gui/{uid}/{Label(id)}"];
+
+    public static ServiceState StatusFromPrint(int exitCode, string stdout) {
+        if (exitCode != 0) return ServiceState.NotInstalled;
+        return stdout.Contains("state = running", StringComparison.OrdinalIgnoreCase)
+            ? ServiceState.Running
+            : ServiceState.Installed;
+    }
+}
diff --git a/test/Capacitor.Cli.Tests.Unit/Services/LaunchdUnitTests.cs b/test/Capacitor.Cli.Tests.Unit/Services/LaunchdUnitTests.cs
new file mode 100644
index 000000000..99c8cc817
--- /dev/null
+++ b/test/Capacitor.Cli.Tests.Unit/Services/LaunchdUnitTests.cs
@@ -0,0 +1,54 @@
+using System.Xml.Linq;
+using Capacitor.Cli.Services;
+
+namespace Capacitor.Cli.Tests.Unit.Services;
+
+public class LaunchdUnitTests {
+    static ServiceSpec Spec(string id = "laptop") => new(
+        ServiceId: id,
+        DaemonBinaryPath: "/opt/kcap/kcap-daemon",
+        LogPath: "/home/u/.config/kcap/daemon-laptop.log",
+        Environment: new Dictionary<string, string> { ["PATH"] = "/usr/bin:/bin", ["KCAP_PROFILE"] = "work" },
+        ExtraArgs: ["--max-agents", "8"]);
+
+    [Test]
+    public async Task Label_is_reverse_dns_with_id() {
+        await Assert.That(LaunchdUnit.Label("laptop")).IsEqualTo("io.kurrent.kcap.daemon.laptop");
+    }
+
+    [Test]
+    public async Task Plist_is_well_formed_xml_and_carries_args_and_env() {
+        var plist = LaunchdUnit.Plist(Spec());
+        var doc   = XDocument.Parse(plist); // throws if malformed
+        await Assert.That(doc).IsNotNull();
+        await Assert.That(plist).Contains("<string>/opt/kcap/kcap-daemon</string>");
+        await Assert.That(plist).Contains("<string>--name</string>");
+        await Assert.That(plist).Contains("<string>laptop</string>");
+        await Assert.That(plist).Contains("<string>--max-agents</string>");
+        await Assert.That(plist).Contains("<key>PATH</key>");
+        await Assert.That(plist).Contains("<key>KCAP_PROFILE</key>");
+        await Assert.That(plist).Contains("<key>SuccessfulExit</key>");
+    }
+
+    [Test]
+    public async Task Plist_escapes_metacharacters_in_values() {
+        var spec  = Spec() with { DaemonBinaryPath = "/opt/a&b/kcap-daemon" };
+        var plist = LaunchdUnit.Plist(spec);
+        XDocument.Parse(plist); // must still parse
+        await Assert.That(plist).Contains("/opt/a&amp;b/kcap-daemon");
+    }
+
+    [Test]
+    public async Task IdFromPlistFileName_extracts_the_id() {
+        await Assert.That(LaunchdUnit.IdFromPlistFileName("io.kurrent.kcap.daemon.laptop.plist"))
+            .IsEqualTo("laptop");
+        await Assert.That(LaunchdUnit.IdFromPlistFileName("unrelated.plist")).IsNull();
+    }
+
+    [Test]
+    public async Task StatusFromPrint_maps_exit_and_state() {
+        await Assert.That(LaunchdUnit.StatusFromPrint(exitCode: 1, stdout: "")).IsEqualTo(ServiceState.NotInstalled);
+        await Assert.That(LaunchdUnit.StatusFromPrint(0, "state = running")).IsEqualTo(ServiceState.Running);
+        await Assert.That(LaunchdUnit.StatusFromPrint(0, "state = not running")).IsEqualTo(ServiceState.Installed);
+    }
+}

From c09cd5e94cc1782e8308937a6c1e1bb6d3eaaf2d Mon Sep 17 00:00:00 2001
From: Alexey Zimarev <alex@zimarev.com>
Date: Wed, 10 Jun 2026 17:23:36 +0200
Subject: [PATCH 07/16] feat(daemon): systemd per-instance unit + vectors
 (pure)

---
 src/Capacitor.Cli/Services/SystemdUnit.cs     | 59 +++++++++++++++++++
 .../Services/SystemdUnitTests.cs              | 38 ++++++++++++
 2 files changed, 97 insertions(+)
 create mode 100644 src/Capacitor.Cli/Services/SystemdUnit.cs
 create mode 100644 test/Capacitor.Cli.Tests.Unit/Services/SystemdUnitTests.cs

diff --git a/src/Capacitor.Cli/Services/SystemdUnit.cs b/src/Capacitor.Cli/Services/SystemdUnit.cs
new file mode 100644
index 000000000..4b70e0d9d
--- /dev/null
+++ b/src/Capacitor.Cli/Services/SystemdUnit.cs
@@ -0,0 +1,59 @@
+using System.Text;
+using Capacitor.Cli.Core;
+
+namespace Capacitor.Cli.Services;
+
+/// <summary>Pure rendering + command vectors for a per-user systemd unit (one file per id).</summary>
+static class SystemdUnit {
+    const string Prefix = "kcap-daemon-";
+
+    public static string UnitName(string id) => $"{Prefix}{id}.service";
+
+    public static string UserUnitDir() =>
+        Path.Combine(PathHelpers.HomeDirectory, ".config", "systemd", "user");
+
+    public static string UnitPath(string id) => Path.Combine(UserUnitDir(), UnitName(id));
+
+    public static string Unit(ServiceSpec spec) {
+        var sb = new StringBuilder();
+        sb.Append("[Unit]\n");
+        sb.Append($"Description=kcap daemon ({ServiceText.SystemdValue(spec.ServiceId)})\n");
+        sb.Append("After=network-online.target\n");
+        sb.Append("Wants=network-online.target\n\n");
+
+        sb.Append("[Service]\n");
+        foreach (var (k, v) in spec.Environment)
+            sb.Append($"Environment={ServiceText.SystemdValue(k)}={ServiceText.SystemdValue(v)}\n");
+
+        var args = string.Join(' ', new[] { "--name", spec.ServiceId, "--log-file", spec.LogPath }.Concat(spec.ExtraArgs));
+        sb.Append($"ExecStart={spec.DaemonBinaryPath} {args}\n");
+        sb.Append("Restart=on-failure\n");
+        sb.Append("RestartSec=5\n");
+        sb.Append("StartLimitIntervalSec=60\n");
+        sb.Append("StartLimitBurst=5\n\n");
+
+        sb.Append("[Install]\n");
+        sb.Append("WantedBy=default.target\n");
+        return sb.ToString();
+    }
+
+    public static string? IdFromUnitFileName(string fileName) =>
+        fileName.StartsWith(Prefix, StringComparison.Ordinal) && fileName.EndsWith(".service", StringComparison.Ordinal)
+            ? fileName[Prefix.Length..^".service".Length]
+            : null;
+
+    // ── command vectors ──
+    public static string[] DaemonReloadArgs()       => ["--user", "daemon-reload"];
+    public static string[] EnableArgs(string id)    => ["--user", "enable", UnitName(id)];
+    public static string[] DisableNowArgs(string id)=> ["--user", "disable", "--now", UnitName(id)];
+    public static string[] StartArgs(string id)     => ["--user", "start", UnitName(id)];
+    public static string[] RestartArgs(string id)   => ["--user", "restart", UnitName(id)];
+    public static string[] StopArgs(string id)      => ["--user", "stop", UnitName(id)];
+    public static string[] IsActiveArgs(string id)  => ["--user", "is-active", UnitName(id)];
+    public static string[] IsEnabledArgs(string id) => ["--user", "is-enabled", UnitName(id)];
+
+    public static ServiceState StatusFrom(string activeOut, int enabledExit) {
+        if (activeOut.Trim().Equals("active", StringComparison.OrdinalIgnoreCase)) return ServiceState.Running;
+        return enabledExit == 0 ? ServiceState.Installed : ServiceState.NotInstalled;
+    }
+}
diff --git a/test/Capacitor.Cli.Tests.Unit/Services/SystemdUnitTests.cs b/test/Capacitor.Cli.Tests.Unit/Services/SystemdUnitTests.cs
new file mode 100644
index 000000000..f2e22a6ed
--- /dev/null
+++ b/test/Capacitor.Cli.Tests.Unit/Services/SystemdUnitTests.cs
@@ -0,0 +1,38 @@
+using Capacitor.Cli.Services;
+
+namespace Capacitor.Cli.Tests.Unit.Services;
+
+public class SystemdUnitTests {
+    static ServiceSpec Spec(string id = "laptop") => new(
+        id, "/opt/kcap/kcap-daemon", "/home/u/.config/kcap/daemon-laptop.log",
+        new Dictionary<string, string> { ["PATH"] = "/usr/bin", ["KCAP_PROFILE"] = "work" },
+        ["--max-agents", "8"]);
+
+    [Test]
+    public async Task UnitName_is_per_instance() {
+        await Assert.That(SystemdUnit.UnitName("laptop")).IsEqualTo("kcap-daemon-laptop.service");
+    }
+
+    [Test]
+    public async Task Unit_has_execstart_restart_and_env() {
+        var unit = SystemdUnit.Unit(Spec());
+        await Assert.That(unit).Contains("ExecStart=/opt/kcap/kcap-daemon --name laptop --log-file /home/u/.config/kcap/daemon-laptop.log --max-agents 8");
+        await Assert.That(unit).Contains("Restart=on-failure");
+        await Assert.That(unit).Contains("Environment=PATH=/usr/bin");
+        await Assert.That(unit).Contains("Environment=KCAP_PROFILE=work");
+        await Assert.That(unit).Contains("WantedBy=default.target");
+    }
+
+    [Test]
+    public async Task IdFromUnitFileName_extracts_id() {
+        await Assert.That(SystemdUnit.IdFromUnitFileName("kcap-daemon-laptop.service")).IsEqualTo("laptop");
+        await Assert.That(SystemdUnit.IdFromUnitFileName("other.service")).IsNull();
+    }
+
+    [Test]
+    public async Task StatusFrom_maps_active_strings() {
+        await Assert.That(SystemdUnit.StatusFrom(activeOut: "active", enabledExit: 0)).IsEqualTo(ServiceState.Running);
+        await Assert.That(SystemdUnit.StatusFrom("inactive", 0)).IsEqualTo(ServiceState.Installed);
+        await Assert.That(SystemdUnit.StatusFrom("inactive", 1)).IsEqualTo(ServiceState.NotInstalled);
+    }
+}

From d0d072bb7102f7bf4d3a306b0b53197e38be4912 Mon Sep 17 00:00:00 2001
From: Alexey Zimarev <alex@zimarev.com>
Date: Wed, 10 Jun 2026 17:25:01 +0200
Subject: [PATCH 08/16] feat(daemon): windows task xml + cmd wrapper + vectors
 (pure)

---
 src/Capacitor.Cli/Services/WindowsTaskUnit.cs | 73 +++++++++++++++++++
 .../Services/WindowsTaskUnitTests.cs          | 40 ++++++++++
 2 files changed, 113 insertions(+)
 create mode 100644 src/Capacitor.Cli/Services/WindowsTaskUnit.cs
 create mode 100644 test/Capacitor.Cli.Tests.Unit/Services/WindowsTaskUnitTests.cs

diff --git a/src/Capacitor.Cli/Services/WindowsTaskUnit.cs b/src/Capacitor.Cli/Services/WindowsTaskUnit.cs
new file mode 100644
index 000000000..7f6ca38d9
--- /dev/null
+++ b/src/Capacitor.Cli/Services/WindowsTaskUnit.cs
@@ -0,0 +1,73 @@
+using System.Text;
+using Capacitor.Cli.Core;
+
+namespace Capacitor.Cli.Services;
+
+/// <summary>Pure rendering + command vectors for a per-user Windows logon Scheduled Task.</summary>
+static class WindowsTaskUnit {
+    const string Prefix = "kcap-daemon-";
+
+    public static string TaskName(string id) => Prefix + id;
+
+    public static string WrapperPath(string id) => PathHelpers.ConfigPath($"daemon-service-{id}.cmd");
+
+    /// <summary>.cmd wrapper: set the captured env, then exec the daemon (no Environment element in Task XML).</summary>
+    public static string Wrapper(ServiceSpec spec) {
+        var sb = new StringBuilder();
+        sb.Append("@echo off\r\n");
+        foreach (var (k, v) in spec.Environment)
+            sb.Append($"set \"{ServiceText.CmdValue(k)}={ServiceText.CmdValue(v)}\"\r\n");
+        var args = string.Join(' ',
+            new[] { "--name", spec.ServiceId, "--log-file", Quote(spec.LogPath) }
+                .Concat(spec.ExtraArgs.Select(QuoteIfNeeded)));
+        sb.Append($"{Quote(ServiceText.CmdValue(spec.DaemonBinaryPath))} {args}\r\n");
+        return sb.ToString();
+    }
+
+    static string Quote(string s) => $"\"{s}\"";
+    static string QuoteIfNeeded(string s) => s.Contains(' ') ? Quote(s) : s;
+
+    public static string TaskXml(ServiceSpec spec, string wrapperPath) =>
+        $"""
+        <?xml version="1.0" encoding="UTF-16"?>
+        <Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+          <RegistrationInfo>
+            <Description>kcap daemon ({ServiceText.Xml(spec.ServiceId)})</Description>
+          </RegistrationInfo>
+          <Triggers>
+            <LogonTrigger><Enabled>true</Enabled></LogonTrigger>
+          </Triggers>
+          <Settings>
+            <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+            <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+            <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+            <StartWhenAvailable>true</StartWhenAvailable>
+            <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+            <RestartOnFailure><Interval>PT1M</Interval><Count>999</Count></RestartOnFailure>
+          </Settings>
+          <Actions>
+            <Exec>
+              <Command>cmd.exe</Command>
+              <Arguments>/c "{ServiceText.Xml(wrapperPath)}"</Arguments>
+            </Exec>
+          </Actions>
+        </Task>
+        """;
+
+    public static string? IdFromTaskName(string taskName) =>
+        taskName.StartsWith(Prefix, StringComparison.Ordinal) ? taskName[Prefix.Length..] : null;
+
+    // ── command vectors (schtasks) ──
+    public static string[] CreateArgs(string id, string xmlPath) => ["/Create", "/TN", TaskName(id), "/XML", xmlPath, "/F"];
+    public static string[] DeleteArgs(string id)                 => ["/Delete", "/TN", TaskName(id), "/F"];
+    public static string[] RunArgs(string id)                    => ["/Run", "/TN", TaskName(id)];
+    public static string[] EndArgs(string id)                    => ["/End", "/TN", TaskName(id)];
+    public static string[] QueryArgs(string id)                  => ["/Query", "/TN", TaskName(id), "/FO", "LIST"];
+
+    public static ServiceState StatusFromQuery(int exitCode, string stdout) {
+        if (exitCode != 0) return ServiceState.NotInstalled;
+        return stdout.Contains("Running", StringComparison.OrdinalIgnoreCase)
+            ? ServiceState.Running
+            : ServiceState.Installed;
+    }
+}
diff --git a/test/Capacitor.Cli.Tests.Unit/Services/WindowsTaskUnitTests.cs b/test/Capacitor.Cli.Tests.Unit/Services/WindowsTaskUnitTests.cs
new file mode 100644
index 000000000..1cfa7529b
--- /dev/null
+++ b/test/Capacitor.Cli.Tests.Unit/Services/WindowsTaskUnitTests.cs
@@ -0,0 +1,40 @@
+using System.Xml.Linq;
+using Capacitor.Cli.Services;
+
+namespace Capacitor.Cli.Tests.Unit.Services;
+
+public class WindowsTaskUnitTests {
+    static ServiceSpec Spec(string id = "laptop") => new(
+        id, @"C:\kcap\kcap-daemon.exe", @"C:\Users\u\.config\kcap\daemon-laptop.log",
+        new Dictionary<string, string> { ["PATH"] = @"C:\bin", ["KCAP_PROFILE"] = "work" },
+        ["--max-agents", "8"]);
+
+    [Test]
+    public async Task TaskName_is_per_id() {
+        await Assert.That(WindowsTaskUnit.TaskName("laptop")).IsEqualTo("kcap-daemon-laptop");
+    }
+
+    [Test]
+    public async Task Wrapper_sets_env_and_execs_daemon() {
+        var cmd = WindowsTaskUnit.Wrapper(Spec());
+        await Assert.That(cmd).Contains("set \"PATH=C:\\bin\"");
+        await Assert.That(cmd).Contains("set \"KCAP_PROFILE=work\"");
+        await Assert.That(cmd).Contains("\"C:\\kcap\\kcap-daemon.exe\" --name laptop --log-file \"C:\\Users\\u\\.config\\kcap\\daemon-laptop.log\" --max-agents 8");
+    }
+
+    [Test]
+    public async Task Wrapper_doubles_percent_in_values() {
+        var spec = Spec() with { Environment = new Dictionary<string, string> { ["X"] = "50%done" } };
+        await Assert.That(WindowsTaskUnit.Wrapper(spec)).Contains("set \"X=50%%done\"");
+    }
+
+    [Test]
+    public async Task TaskXml_is_well_formed_and_runs_cmd_wrapper() {
+        var xml = WindowsTaskUnit.TaskXml(Spec(), @"C:\Users\u\.config\kcap\daemon-service-laptop.cmd");
+        XDocument.Parse(xml); // throws if malformed
+        await Assert.That(xml).Contains("<Command>cmd.exe</Command>");
+        await Assert.That(xml).Contains("/c");
+        await Assert.That(xml).Contains("daemon-service-laptop.cmd");
+        await Assert.That(xml).Contains("<LogonTrigger>");
+    }
+}

From 43980afe3e7f5924f1adb5fe65cd7984520df843 Mon Sep 17 00:00:00 2001
From: Alexey Zimarev <alex@zimarev.com>
Date: Wed, 10 Jun 2026 17:27:25 +0200
Subject: [PATCH 09/16] feat(daemon): thin service managers + process runner +
 factory

---
 .../Services/LaunchdServiceManager.cs         | 52 +++++++++++++++++
 .../Services/ServiceManagerFactory.cs         | 17 ++++++
 src/Capacitor.Cli/Services/ServiceProcess.cs  | 34 +++++++++++
 .../Services/SystemdServiceManager.cs         | 48 ++++++++++++++++
 .../WindowsScheduledTaskServiceManager.cs     | 56 +++++++++++++++++++
 .../Services/ServiceManagerFactoryTests.cs    | 35 ++++++++++++
 6 files changed, 242 insertions(+)
 create mode 100644 src/Capacitor.Cli/Services/LaunchdServiceManager.cs
 create mode 100644 src/Capacitor.Cli/Services/ServiceManagerFactory.cs
 create mode 100644 src/Capacitor.Cli/Services/ServiceProcess.cs
 create mode 100644 src/Capacitor.Cli/Services/SystemdServiceManager.cs
 create mode 100644 src/Capacitor.Cli/Services/WindowsScheduledTaskServiceManager.cs
 create mode 100644 test/Capacitor.Cli.Tests.Unit/Services/ServiceManagerFactoryTests.cs

diff --git a/src/Capacitor.Cli/Services/LaunchdServiceManager.cs b/src/Capacitor.Cli/Services/LaunchdServiceManager.cs
new file mode 100644
index 000000000..bf53a734c
--- /dev/null
+++ b/src/Capacitor.Cli/Services/LaunchdServiceManager.cs
@@ -0,0 +1,52 @@
+using System.Runtime.InteropServices;
+using System.Xml.Linq;
+
+namespace Capacitor.Cli.Services;
+
+sealed partial class LaunchdServiceManager : IServiceManager {
+    [LibraryImport("libc", EntryPoint = "getuid")]
+    private static partial uint getuid();
+
+    static int Uid() => (int)getuid();
+
+    public string Describe() => "launchd LaunchAgent";
+
+    public IReadOnlyList<GeneratedFile> GenerateFiles(ServiceSpec spec) =>
+        [new GeneratedFile(LaunchdUnit.PlistPath(spec.ServiceId), LaunchdUnit.Plist(spec))];
+
+    public IReadOnlyList<string> ListInstalled() {
+        var dir = LaunchdUnit.AgentsDir();
+        if (!Directory.Exists(dir)) return [];
+        return [.. Directory.EnumerateFiles(dir, "io.kurrent.kcap.daemon.*.plist")
+            .Select(f => LaunchdUnit.IdFromPlistFileName(Path.GetFileName(f)))
+            .Where(id => id is not null).Select(id => id!).Order()];
+    }
+
+    public ServiceStatus Status(string serviceId) {
+        var path = LaunchdUnit.PlistPath(serviceId);
+        if (!File.Exists(path)) return new ServiceStatus(ServiceState.NotInstalled, null);
+        // First <string> in the plist is the daemon binary (ProgramArguments[0]) — for doctor.
+        var bin = XDocument.Load(path).Descendants("string").FirstOrDefault()?.Value;
+        var (code, stdout, _) = ServiceProcess.Run("launchctl", LaunchdUnit.PrintArgs(Uid(), serviceId));
+        return new ServiceStatus(LaunchdUnit.StatusFromPrint(code, stdout), bin);
+    }
+
+    public void Install(ServiceSpec spec, bool startNow) {
+        Directory.CreateDirectory(LaunchdUnit.AgentsDir());
+        var plistPath = LaunchdUnit.PlistPath(spec.ServiceId);
+        // idempotent: bootout an existing job (ignore failure), then rewrite + bootstrap.
+        ServiceProcess.Run("launchctl", LaunchdUnit.BootoutArgs(Uid(), spec.ServiceId));
+        File.WriteAllText(plistPath, LaunchdUnit.Plist(spec));
+        ServiceProcess.Check("launchctl", LaunchdUnit.BootstrapArgs(Uid(), plistPath)); // RunAtLoad starts it
+        if (!startNow) ServiceProcess.Run("launchctl", LaunchdUnit.KillArgs(Uid(), spec.ServiceId));
+    }
+
+    public void Uninstall(string serviceId) {
+        ServiceProcess.Run("launchctl", LaunchdUnit.BootoutArgs(Uid(), serviceId));
+        var path = LaunchdUnit.PlistPath(serviceId);
+        if (File.Exists(path)) File.Delete(path);
+    }
+
+    public void Start(string serviceId) => ServiceProcess.Check("launchctl", LaunchdUnit.KickstartArgs(Uid(), serviceId));
+    public void Stop(string serviceId)  => ServiceProcess.Check("launchctl", LaunchdUnit.KillArgs(Uid(), serviceId));
+}
diff --git a/src/Capacitor.Cli/Services/ServiceManagerFactory.cs b/src/Capacitor.Cli/Services/ServiceManagerFactory.cs
new file mode 100644
index 000000000..23a326df6
--- /dev/null
+++ b/src/Capacitor.Cli/Services/ServiceManagerFactory.cs
@@ -0,0 +1,17 @@
+namespace Capacitor.Cli.Services;
+
+static class ServiceManagerFactory {
+    public static IServiceManager ForPlatform(ServicePlatform platform) => platform switch {
+        ServicePlatform.Launchd              => new LaunchdServiceManager(),
+        ServicePlatform.Systemd              => new SystemdServiceManager(),
+        ServicePlatform.WindowsScheduledTask => new WindowsScheduledTaskServiceManager(),
+        _ => throw new PlatformNotSupportedException($"No service manager for {platform}"),
+    };
+
+    public static IServiceManager ForCurrentOs() {
+        if (OperatingSystem.IsMacOS())   return ForPlatform(ServicePlatform.Launchd);
+        if (OperatingSystem.IsLinux())   return ForPlatform(ServicePlatform.Systemd);
+        if (OperatingSystem.IsWindows()) return ForPlatform(ServicePlatform.WindowsScheduledTask);
+        throw new PlatformNotSupportedException("kcap daemon service is not supported on this OS.");
+    }
+}
diff --git a/src/Capacitor.Cli/Services/ServiceProcess.cs b/src/Capacitor.Cli/Services/ServiceProcess.cs
new file mode 100644
index 000000000..c9e38d995
--- /dev/null
+++ b/src/Capacitor.Cli/Services/ServiceProcess.cs
@@ -0,0 +1,34 @@
+using System.Diagnostics;
+
+namespace Capacitor.Cli.Services;
+
+/// <summary>
+/// Minimal synchronous shell-out for service registration tools
+/// (launchctl/systemctl/schtasks). Not used in tests — managers' side-effecting
+/// methods are the one part not exercised in CI.
+/// </summary>
+static class ServiceProcess {
+    public static (int ExitCode, string StdOut, string StdErr) Run(string file, params string[] args) {
+        var psi = new ProcessStartInfo {
+            FileName               = file,
+            UseShellExecute        = false,
+            RedirectStandardOutput = true,
+            RedirectStandardError  = true,
+            CreateNoWindow         = true,
+        };
+        foreach (var a in args) psi.ArgumentList.Add(a);
+
+        using var p = Process.Start(psi) ?? throw new InvalidOperationException($"Failed to start {file}");
+        var stdout = p.StandardOutput.ReadToEnd();
+        var stderr = p.StandardError.ReadToEnd();
+        p.WaitForExit();
+        return (p.ExitCode, stdout, stderr);
+    }
+
+    /// <summary>Run and throw with captured stderr on non-zero exit.</summary>
+    public static void Check(string file, params string[] args) {
+        var (code, _, err) = Run(file, args);
+        if (code != 0)
+            throw new InvalidOperationException($"{file} {string.Join(' ', args)} failed (exit {code}): {err.Trim()}");
+    }
+}
diff --git a/src/Capacitor.Cli/Services/SystemdServiceManager.cs b/src/Capacitor.Cli/Services/SystemdServiceManager.cs
new file mode 100644
index 000000000..ce33a70d1
--- /dev/null
+++ b/src/Capacitor.Cli/Services/SystemdServiceManager.cs
@@ -0,0 +1,48 @@
+namespace Capacitor.Cli.Services;
+
+sealed class SystemdServiceManager : IServiceManager {
+    public string Describe() => "systemd --user unit";
+
+    public IReadOnlyList<GeneratedFile> GenerateFiles(ServiceSpec spec) =>
+        [new GeneratedFile(SystemdUnit.UnitPath(spec.ServiceId), SystemdUnit.Unit(spec))];
+
+    public IReadOnlyList<string> ListInstalled() {
+        var dir = SystemdUnit.UserUnitDir();
+        if (!Directory.Exists(dir)) return [];
+        return [.. Directory.EnumerateFiles(dir, "kcap-daemon-*.service")
+            .Select(f => SystemdUnit.IdFromUnitFileName(Path.GetFileName(f)))
+            .Where(id => id is not null).Select(id => id!).Order()];
+    }
+
+    public ServiceStatus Status(string serviceId) {
+        var path = SystemdUnit.UnitPath(serviceId);
+        if (!File.Exists(path)) return new ServiceStatus(ServiceState.NotInstalled, null);
+        var (_, active, _)      = ServiceProcess.Run("systemctl", SystemdUnit.IsActiveArgs(serviceId));
+        var (enabledExit, _, _) = ServiceProcess.Run("systemctl", SystemdUnit.IsEnabledArgs(serviceId));
+        var bin = ExecStartBinary(path);
+        return new ServiceStatus(SystemdUnit.StatusFrom(active, enabledExit), bin);
+    }
+
+    static string? ExecStartBinary(string unitPath) {
+        var line = File.ReadLines(unitPath).FirstOrDefault(l => l.StartsWith("ExecStart=", StringComparison.Ordinal));
+        return line?["ExecStart=".Length..].Split(' ', 2)[0];
+    }
+
+    public void Install(ServiceSpec spec, bool startNow) {
+        Directory.CreateDirectory(SystemdUnit.UserUnitDir());
+        File.WriteAllText(SystemdUnit.UnitPath(spec.ServiceId), SystemdUnit.Unit(spec));
+        ServiceProcess.Check("systemctl", SystemdUnit.DaemonReloadArgs());
+        ServiceProcess.Check("systemctl", SystemdUnit.EnableArgs(spec.ServiceId));
+        if (startNow) ServiceProcess.Check("systemctl", SystemdUnit.RestartArgs(spec.ServiceId));
+    }
+
+    public void Uninstall(string serviceId) {
+        ServiceProcess.Run("systemctl", SystemdUnit.DisableNowArgs(serviceId));
+        var path = SystemdUnit.UnitPath(serviceId);
+        if (File.Exists(path)) File.Delete(path);
+        ServiceProcess.Run("systemctl", SystemdUnit.DaemonReloadArgs());
+    }
+
+    public void Start(string serviceId) => ServiceProcess.Check("systemctl", SystemdUnit.StartArgs(serviceId));
+    public void Stop(string serviceId)  => ServiceProcess.Check("systemctl", SystemdUnit.StopArgs(serviceId));
+}
diff --git a/src/Capacitor.Cli/Services/WindowsScheduledTaskServiceManager.cs b/src/Capacitor.Cli/Services/WindowsScheduledTaskServiceManager.cs
new file mode 100644
index 000000000..2aa40db03
--- /dev/null
+++ b/src/Capacitor.Cli/Services/WindowsScheduledTaskServiceManager.cs
@@ -0,0 +1,56 @@
+using System.Text;
+using Capacitor.Cli.Core;
+
+namespace Capacitor.Cli.Services;
+
+sealed class WindowsScheduledTaskServiceManager : IServiceManager {
+    public string Describe() => "Windows Scheduled Task";
+
+    public IReadOnlyList<GeneratedFile> GenerateFiles(ServiceSpec spec) {
+        var wrapperPath = WindowsTaskUnit.WrapperPath(spec.ServiceId);
+        return [
+            new GeneratedFile(wrapperPath, WindowsTaskUnit.Wrapper(spec)),
+            new GeneratedFile(TaskXmlTempPath(spec.ServiceId), WindowsTaskUnit.TaskXml(spec, wrapperPath)),
+        ];
+    }
+
+    static string TaskXmlTempPath(string id) => PathHelpers.ConfigPath($"daemon-service-{id}.task.xml");
+
+    public IReadOnlyList<string> ListInstalled() {
+        var (code, stdout, _) = ServiceProcess.Run("schtasks", "/Query", "/FO", "LIST");
+        if (code != 0) return [];
+        return [.. stdout.Split('\n')
+            .Where(l => l.TrimStart().StartsWith("TaskName:", StringComparison.OrdinalIgnoreCase))
+            .Select(l => WindowsTaskUnit.IdFromTaskName(Path.GetFileName(l.Split(':', 2)[1].Trim())))
+            .Where(id => id is not null).Select(id => id!).Distinct().Order()];
+    }
+
+    public ServiceStatus Status(string serviceId) {
+        var (code, stdout, _) = ServiceProcess.Run("schtasks", WindowsTaskUnit.QueryArgs(serviceId));
+        var bin = File.Exists(WindowsTaskUnit.WrapperPath(serviceId)) ? WindowsTaskUnit.WrapperPath(serviceId) : null;
+        return new ServiceStatus(WindowsTaskUnit.StatusFromQuery(code, stdout), bin);
+    }
+
+    public void Install(ServiceSpec spec, bool startNow) {
+        var files = GenerateFiles(spec);
+        foreach (var f in files) {
+            Directory.CreateDirectory(Path.GetDirectoryName(f.Path)!);
+            // schtasks /XML wants UTF-16; the .cmd wrapper is fine as UTF-8.
+            var encoding = f.Path.EndsWith(".task.xml", StringComparison.Ordinal) ? Encoding.Unicode : Encoding.UTF8;
+            File.WriteAllText(f.Path, f.Content, encoding);
+        }
+        var xmlPath = files.First(f => f.Path.EndsWith(".task.xml", StringComparison.Ordinal)).Path;
+        ServiceProcess.Check("schtasks", WindowsTaskUnit.CreateArgs(spec.ServiceId, xmlPath));
+        File.Delete(xmlPath); // the task XML is only needed for registration
+        if (startNow) ServiceProcess.Check("schtasks", WindowsTaskUnit.RunArgs(spec.ServiceId));
+    }
+
+    public void Uninstall(string serviceId) {
+        ServiceProcess.Run("schtasks", WindowsTaskUnit.DeleteArgs(serviceId));
+        var wrapper = WindowsTaskUnit.WrapperPath(serviceId);
+        if (File.Exists(wrapper)) File.Delete(wrapper);
+    }
+
+    public void Start(string serviceId) => ServiceProcess.Check("schtasks", WindowsTaskUnit.RunArgs(serviceId));
+    public void Stop(string serviceId)  => ServiceProcess.Check("schtasks", WindowsTaskUnit.EndArgs(serviceId));
+}
diff --git a/test/Capacitor.Cli.Tests.Unit/Services/ServiceManagerFactoryTests.cs b/test/Capacitor.Cli.Tests.Unit/Services/ServiceManagerFactoryTests.cs
new file mode 100644
index 000000000..6d85e9656
--- /dev/null
+++ b/test/Capacitor.Cli.Tests.Unit/Services/ServiceManagerFactoryTests.cs
@@ -0,0 +1,35 @@
+using Capacitor.Cli.Services;
+
+namespace Capacitor.Cli.Tests.Unit.Services;
+
+public class ServiceManagerFactoryTests {
+    [Test]
+    public async Task ForPlatform_returns_each_concrete_manager() {
+        await Assert.That(ServiceManagerFactory.ForPlatform(ServicePlatform.Launchd)).IsTypeOf<LaunchdServiceManager>();
+        await Assert.That(ServiceManagerFactory.ForPlatform(ServicePlatform.Systemd)).IsTypeOf<SystemdServiceManager>();
+        await Assert.That(ServiceManagerFactory.ForPlatform(ServicePlatform.WindowsScheduledTask)).IsTypeOf<WindowsScheduledTaskServiceManager>();
+    }
+
+    [Test]
+    public async Task ForCurrentOs_does_not_throw_on_this_host() {
+        var mgr = ServiceManagerFactory.ForCurrentOs();
+        await Assert.That(mgr.Describe()).IsNotNull();
+    }
+
+    [Test]
+    public async Task Launchd_GenerateFiles_returns_one_file() {
+        var spec = new ServiceSpec("laptop", "/opt/kcap/kcap-daemon", "/tmp/daemon-laptop.log",
+            new Dictionary<string, string>(), []);
+        var files = ServiceManagerFactory.ForPlatform(ServicePlatform.Launchd).GenerateFiles(spec);
+        await Assert.That(files.Count).IsEqualTo(1);
+        await Assert.That(files[0].Path).EndsWith("io.kurrent.kcap.daemon.laptop.plist");
+    }
+
+    [Test]
+    public async Task Windows_GenerateFiles_returns_xml_and_wrapper() {
+        var spec = new ServiceSpec("laptop", @"C:\kcap\kcap-daemon.exe", @"C:\tmp\daemon-laptop.log",
+            new Dictionary<string, string>(), []);
+        var files = ServiceManagerFactory.ForPlatform(ServicePlatform.WindowsScheduledTask).GenerateFiles(spec);
+        await Assert.That(files.Count).IsEqualTo(2);
+    }
+}

From 26de3227cf08f5d94a5290cbfebd3cddd235eedb Mon Sep 17 00:00:00 2001
From: Alexey Zimarev <alex@zimarev.com>
Date: Wed, 10 Jun 2026 17:28:16 +0200
Subject: [PATCH 10/16] feat(daemon): capture env + pin profile for service
 units

---
 .../Services/ServiceEnvironment.cs            | 33 ++++++++++++++++++
 .../Services/ServiceEnvironmentTests.cs       | 34 +++++++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100644 src/Capacitor.Cli/Services/ServiceEnvironment.cs
 create mode 100644 test/Capacitor.Cli.Tests.Unit/Services/ServiceEnvironmentTests.cs

diff --git a/src/Capacitor.Cli/Services/ServiceEnvironment.cs b/src/Capacitor.Cli/Services/ServiceEnvironment.cs
new file mode 100644
index 000000000..12d2d89f2
--- /dev/null
+++ b/src/Capacitor.Cli/Services/ServiceEnvironment.cs
@@ -0,0 +1,33 @@
+using System.Collections;
+
+namespace Capacitor.Cli.Services;
+
+/// <summary>
+/// Builds the environment baked into a service unit. Supervised jobs don't
+/// inherit the interactive shell PATH (so bare claude/codex lookup fails) and a
+/// baked --server-url would null out profile resolution — so we capture PATH +
+/// the KCAP_* keys and pin the profile via KCAP_PROFILE.
+/// </summary>
+static class ServiceEnvironment {
+    static readonly string[] Keys = ["PATH", "KCAP_CONFIG_DIR", "KCAP_PROFILE", "KCAP_URL", "KCAP_CLAUDE_PATH", "KCAP_CODEX_PATH"];
+
+    /// <summary>Production entry point: capture from the current process env.</summary>
+    public static IReadOnlyDictionary<string, string> Capture(string? profileName) =>
+        Build(profileName, Snapshot());
+
+    static Dictionary<string, string> Snapshot() {
+        var d = new Dictionary<string, string>();
+        foreach (DictionaryEntry e in Environment.GetEnvironmentVariables())
+            if (e.Key is string k && e.Value is string v) d[k] = v;
+        return d;
+    }
+
+    /// <summary>Pure: select the relevant keys from <paramref name="source"/>, pin the profile.</summary>
+    public static IReadOnlyDictionary<string, string> Build(string? profileName, IReadOnlyDictionary<string, string> source) {
+        var env = new Dictionary<string, string>(StringComparer.Ordinal);
+        foreach (var key in Keys)
+            if (source.TryGetValue(key, out var v) && !string.IsNullOrEmpty(v)) env[key] = v;
+        if (!string.IsNullOrEmpty(profileName)) env["KCAP_PROFILE"] = profileName; // explicit pin wins
+        return env;
+    }
+}
diff --git a/test/Capacitor.Cli.Tests.Unit/Services/ServiceEnvironmentTests.cs b/test/Capacitor.Cli.Tests.Unit/Services/ServiceEnvironmentTests.cs
new file mode 100644
index 000000000..81b976f2d
--- /dev/null
+++ b/test/Capacitor.Cli.Tests.Unit/Services/ServiceEnvironmentTests.cs
@@ -0,0 +1,34 @@
+using Capacitor.Cli.Services;
+
+namespace Capacitor.Cli.Tests.Unit.Services;
+
+public class ServiceEnvironmentTests {
+    [Test]
+    public async Task Build_pins_profile_and_includes_path() {
+        var src = new Dictionary<string, string> {
+            ["PATH"]              = "/usr/local/bin:/usr/bin",
+            ["KCAP_CONFIG_DIR"]   = "/home/u/.config/kcap",
+            ["IRRELEVANT"]        = "x",
+        };
+        var env = ServiceEnvironment.Build(profileName: "work", source: src);
+        await Assert.That(env["PATH"]).IsEqualTo("/usr/local/bin:/usr/bin");
+        await Assert.That(env["KCAP_PROFILE"]).IsEqualTo("work");
+        await Assert.That(env["KCAP_CONFIG_DIR"]).IsEqualTo("/home/u/.config/kcap");
+        await Assert.That(env.ContainsKey("IRRELEVANT")).IsFalse();
+    }
+
+    [Test]
+    public async Task Build_omits_profile_when_null_and_keeps_kcap_url() {
+        var src = new Dictionary<string, string> { ["KCAP_URL"] = "https://x" };
+        var env = ServiceEnvironment.Build(profileName: null, source: src);
+        await Assert.That(env.ContainsKey("KCAP_PROFILE")).IsFalse();
+        await Assert.That(env["KCAP_URL"]).IsEqualTo("https://x");
+    }
+
+    [Test]
+    public async Task Build_explicit_profile_overrides_source_env() {
+        var src = new Dictionary<string, string> { ["KCAP_PROFILE"] = "old" };
+        var env = ServiceEnvironment.Build(profileName: "new", source: src);
+        await Assert.That(env["KCAP_PROFILE"]).IsEqualTo("new");
+    }
+}

From f6b9cf3fba20ac32ce27c8f6b40e3d9d68cc276e Mon Sep 17 00:00:00 2001
From: Alexey Zimarev <alex@zimarev.com>
Date: Wed, 10 Jun 2026 17:30:07 +0200
Subject: [PATCH 11/16] feat(daemon): kcap daemon service
 install/uninstall/start/stop/status

---
 src/Capacitor.Cli/Commands/DaemonCommands.cs | 84 ++++++++++++++++++--
 1 file changed, 78 insertions(+), 6 deletions(-)

diff --git a/src/Capacitor.Cli/Commands/DaemonCommands.cs b/src/Capacitor.Cli/Commands/DaemonCommands.cs
index 922bdf301..7c9d804ae 100644
--- a/src/Capacitor.Cli/Commands/DaemonCommands.cs
+++ b/src/Capacitor.Cli/Commands/DaemonCommands.cs
@@ -1,6 +1,7 @@
 using System.Diagnostics;
 using Capacitor.Cli.Core;
 using Capacitor.Cli.Core.Config;
+using Capacitor.Cli.Services;
 
 namespace Capacitor.Cli.Commands;
 
@@ -18,12 +19,13 @@ public static async Task<int> HandleAsync(string[] args) {
         var remaining  = args[2..];
 
         return subcommand switch {
-            "start"  => await StartAsync(remaining),
-            "stop"   => await StopAsync(remaining),
-            "status" => await Status(remaining),
-            "logs"   => await Logs(),
-            "doctor" => await DoctorAsync(remaining),
-            _        => PrintUsage()
+            "start"   => await StartAsync(remaining),
+            "stop"    => await StopAsync(remaining),
+            "status"  => await Status(remaining),
+            "logs"    => await Logs(),
+            "doctor"  => await DoctorAsync(remaining),
+            "service" => await ServiceAsync(remaining),
+            _         => PrintUsage()
         };
     }
 
@@ -613,6 +615,76 @@ static async Task<int> Logs() {
         return 0;
     }
 
+    // ── service (OS supervisor: launchd / systemd / scheduled task) ───────────
+
+    static async Task<int> ServiceAsync(string[] args) {
+        if (args.Length == 0) return ServiceUsage();
+
+        var action  = args[0];
+        var rest    = args[1..];
+        var noStart = rest.Contains("--no-start");
+
+        IServiceManager manager;
+        try {
+            manager = ServiceManagerFactory.ForCurrentOs();
+        } catch (PlatformNotSupportedException ex) {
+            await Console.Error.WriteLineAsync(ex.Message);
+            return 1;
+        }
+
+        var id = ServiceText.ServiceId(ResolveName(rest));
+
+        switch (action) {
+            case "install":   return await ServiceInstall(manager, rest, id, startNow: !noStart);
+            case "uninstall": manager.Uninstall(id); await Console.Out.WriteLineAsync($"Service '{id}' uninstalled ({manager.Describe()})."); return 0;
+            case "start":     manager.Start(id);     await Console.Out.WriteLineAsync($"Service '{id}' started.");   return 0;
+            case "stop":      manager.Stop(id);      await Console.Out.WriteLineAsync($"Service '{id}' stopped (still installed)."); return 0;
+            case "status":    return await ServiceStatus(manager, id);
+            default:          return ServiceUsage();
+        }
+    }
+
+    static async Task<int> ServiceInstall(IServiceManager manager, string[] args, string id, bool startNow) {
+        var daemonPath = ResolveDaemonBinary();
+        if (daemonPath is null) { await Console.Error.WriteLineAsync(DaemonNotFoundMessage()); return 1; }
+
+        var profileName = ExtractFlagValue(args, "--profile") ?? AppConfig.ResolvedProfile?.ProfileName;
+        var env         = ServiceEnvironment.Capture(profileName);
+
+        var extra = new List<string>();
+        if (ExtractFlagValue(args, "--max-agents") is { } mx) { extra.Add("--max-agents"); extra.Add(mx); }
+
+        var logPath = PathHelpers.ConfigPath($"daemon-{id}.log");
+        var spec    = new ServiceSpec(id, daemonPath, logPath, env, extra);
+
+        manager.Install(spec, startNow);
+
+        await Console.Out.WriteLineAsync($"Service '{id}' installed ({manager.Describe()}).");
+        await Console.Out.WriteLineAsync("  Auto-restarts on crash/SIGKILL; starts at login.");
+        await Console.Out.WriteLineAsync($"  Log:       {logPath}");
+        await Console.Out.WriteLineAsync($"  Stop:      kcap daemon service stop --name {id}");
+        await Console.Out.WriteLineAsync($"  Remove:    kcap daemon service uninstall --name {id}");
+        return 0;
+    }
+
+    static async Task<int> ServiceStatus(IServiceManager manager, string id) {
+        var status = manager.Status(id);
+        await Console.Out.WriteLineAsync($"Service '{id}': {status.State} ({manager.Describe()})");
+        if (status.BinaryPath is { } bin) await Console.Out.WriteLineAsync($"  binary: {bin}");
+        return 0;
+    }
+
+    static int ServiceUsage() {
+        Console.Error.WriteLine("Usage: kcap daemon service <install|uninstall|start|stop|status> [--name N]");
+        Console.Error.WriteLine();
+        Console.Error.WriteLine("  install [--name N] [--profile P] [--max-agents N] [--no-start]");
+        Console.Error.WriteLine("  uninstall [--name N]   Stop and remove the service unit");
+        Console.Error.WriteLine("  start [--name N]       Start the installed service now");
+        Console.Error.WriteLine("  stop [--name N]        Stop the running service (stays installed)");
+        Console.Error.WriteLine("  status [--name N]      Show installed/running state");
+        return 1;
+    }
+
     /// <summary>
     /// Resolve the kcap-daemon executable shipped alongside this binary.
     /// </summary>

From 187e1694f4f35cd6a6c3b54159a36dee1c30297a Mon Sep 17 00:00:00 2001
From: Alexey Zimarev <alex@zimarev.com>
Date: Wed, 10 Jun 2026 17:32:33 +0200
Subject: [PATCH 12/16] feat(daemon): status/stop/doctor awareness of installed
 services

---
 src/Capacitor.Cli/Commands/DaemonCommands.cs | 59 ++++++++++++++++++--
 1 file changed, 53 insertions(+), 6 deletions(-)

diff --git a/src/Capacitor.Cli/Commands/DaemonCommands.cs b/src/Capacitor.Cli/Commands/DaemonCommands.cs
index 7c9d804ae..9ba476227 100644
--- a/src/Capacitor.Cli/Commands/DaemonCommands.cs
+++ b/src/Capacitor.Cli/Commands/DaemonCommands.cs
@@ -277,6 +277,15 @@ static async Task<int> StopAsync(string[] args) {
     }
 
     static int StopByName(string name) {
+        var manager = TryServiceManager();
+        if (manager is not null && manager.Status(ServiceText.ServiceId(name)).State != ServiceState.NotInstalled) {
+            Console.Out.WriteLine(
+                $"Daemon '{name}' is managed by {manager.Describe()}; a raw stop would be auto-restarted.");
+            Console.Out.WriteLine($"Use: kcap daemon service stop --name {name}  (or uninstall to remove it)");
+
+            return 0;
+        }
+
         if (ReadPidFile(name) is not { } entry) {
             Console.Error.WriteLine($"No daemon '{name}' running (no PID file found).");
 
@@ -318,7 +327,12 @@ static async Task<int> Status(string[] args) {
             return 1;
         }
 
-        var names = explicitName is not null ? [explicitName] : EnumerateRunningNames();
+        var manager    = TryServiceManager();
+        var serviceIds = manager?.ListInstalled() ?? [];
+
+        var names = explicitName is not null
+            ? new List<string> { explicitName }
+            : EnumerateRunningNames().Concat(serviceIds).Distinct().Order().ToList();
 
         if (names.Count == 0) {
             await Console.Out.WriteLineAsync("Daemon: not running");
@@ -329,11 +343,7 @@ static async Task<int> Status(string[] args) {
         foreach (var name in names) {
             if (ReadPidFile(name) is not { } entry) {
                 await Console.Out.WriteLineAsync($"Daemon '{name}': not running");
-
-                continue;
-            }
-
-            if (IsOurDaemon(entry.Pid, entry.StartTicks)) {
+            } else if (IsOurDaemon(entry.Pid, entry.StartTicks)) {
                 await Console.Out.WriteLineAsync($"Daemon '{name}': running (PID {entry.Pid})");
             } else {
                 await Console.Out.WriteLineAsync($"Daemon '{name}': not running (stale PID file)");
@@ -342,6 +352,12 @@ static async Task<int> Status(string[] args) {
                     /* best-effort */
                 }
             }
+
+            if (manager is not null) {
+                var st = manager.Status(ServiceText.ServiceId(name)).State;
+                if (st != ServiceState.NotInstalled)
+                    await Console.Out.WriteLineAsync($"  service: {st} ({manager.Describe()})");
+            }
         }
 
         return 0;
@@ -366,6 +382,7 @@ static async Task<int> DoctorAsync(string[] args) {
 
         if (names.Count == 0) {
             await Console.Out.WriteLineAsync($"No daemon files found under {DaemonLockPaths.Directory}.");
+            await ReportInstalledServices();
 
             return 0;
         }
@@ -463,6 +480,8 @@ static async Task<int> DoctorAsync(string[] args) {
             await Console.Out.WriteLineAsync("Re-run with --clean to remove stale entries.");
         }
 
+        await ReportInstalledServices();
+
         return 0;
     }
 
@@ -685,6 +704,34 @@ static int ServiceUsage() {
         return 1;
     }
 
+    /// <summary>Service manager for this OS, or null if the OS is unsupported.</summary>
+    static IServiceManager? TryServiceManager() {
+        try { return ServiceManagerFactory.ForCurrentOs(); }
+        catch (PlatformNotSupportedException) { return null; }
+    }
+
+    /// <summary>
+    /// Doctor add-on: list OS-installed services and flag any whose baked binary
+    /// path no longer exists (e.g. a moved npm prefix — fixed by re-running
+    /// <c>kcap daemon service install</c>). No-op on unsupported OSes / when none.
+    /// </summary>
+    static async Task ReportInstalledServices() {
+        var manager = TryServiceManager();
+        if (manager is null) return;
+
+        var installed = manager.ListInstalled();
+        if (installed.Count == 0) return;
+
+        await Console.Out.WriteLineAsync($"\nInstalled services ({manager.Describe()}):");
+
+        foreach (var sid in installed) {
+            var st   = manager.Status(sid);
+            var bad  = st.BinaryPath is { } b && !File.Exists(b);
+            var note = bad ? "  ⚠ binary missing — re-run `kcap daemon service install`" : "";
+            await Console.Out.WriteLineAsync($"  {sid,-20}  {st.State}{note}");
+        }
+    }
+
     /// <summary>
     /// Resolve the kcap-daemon executable shipped alongside this binary.
     /// </summary>

From 9ad65c6b77dd6a61e6c833df7674e35245fdfdb6 Mon Sep 17 00:00:00 2001
From: Alexey Zimarev <alex@zimarev.com>
Date: Wed, 10 Jun 2026 17:34:01 +0200
Subject: [PATCH 13/16] docs(daemon): document service
 install/uninstall/start/stop/status

---
 README.md                                     | 19 +++++++++++++++++++
 .../Resources/help-daemon.txt                 | 12 ++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/README.md b/README.md
index 69452730b..30d5e52b6 100644
--- a/README.md
+++ b/README.md
@@ -77,6 +77,8 @@ In `--no-prompt` mode, the wizard installs hooks for every detected agent by def
 
 > **Need at least one agent to capture sessions:** the setup wizard runs to completion without an agent CLI on `PATH` (it'll still configure your profile, auth, and daemon), but kcap only records work once Claude Code or Codex CLI is installed and the hooks are in place.
 
+> **Keep the daemon running:** `kcap daemon start -d` stops when the process dies (a crash, or an OS memory-pressure kill — macOS jetsam / Linux OOM). To auto-restart it and start it at login, install it as a per-user service: `kcap daemon service install`. See [Daemon](#daemon).
+
 ### 3. Import existing sessions (optional)
 
 ```bash
@@ -310,6 +312,23 @@ kcap daemon doctor --clean          # also remove stale lock/pid files (held ent
 
 `KCAP_DAEMON_NAME` overrides the active profile's daemon name (superseded by an explicit `--name` flag).
 
+#### Run it as a service (auto-restart)
+
+`kcap daemon start -d` runs only until the process dies — a crash, or an OS memory-pressure kill (macOS **jetsam** / Linux **OOM killer**) that sends an uncatchable `SIGKILL`. To have the daemon auto-restart and start at login, install it as a **per-user** OS service:
+
+```bash
+kcap daemon service install                # launchd (macOS) / systemd --user (Linux) / Scheduled Task (Windows)
+kcap daemon service install --name laptop  # a service per daemon name
+kcap daemon service status                 # installed / running state
+kcap daemon service stop                   # stop the running service (stays installed)
+kcap daemon service start                  # start it again
+kcap daemon service uninstall              # stop and remove the service
+```
+
+`install` pins the active profile via `KCAP_PROFILE` and captures your current `PATH` into the unit, so the supervised daemon resolves the same server URL, `claude`/`codex` binaries, and profile settings it would from your shell. Pass `--profile P` to pin a different profile, `--max-agents N` to bake an override, or `--no-start` to register without starting. The service restarts the daemon on crash/`SIGKILL` but **not** on a clean stop.
+
+Because the service auto-restarts, stop a service-managed daemon with `kcap daemon service stop` (or `uninstall`) rather than `kcap daemon stop` — a raw stop would be relaunched immediately. `kcap daemon status` and `kcap daemon doctor` both report installed services.
+
 Each daemon process holds an exclusive `flock` on `~/.config/kcap/daemons/<name>.lock` for its entire lifetime. The kernel releases the lock automatically when the daemon exits (including `SIGKILL` or power-off), so leftover lock files on disk are never a blocker — only a live process holding the kernel-level lock can prevent another daemon from acquiring the same name.
 
 Two daemons with **different** `--name` values can run side-by-side. Two daemons under the **same name** on the same machine collide on the flock and the second one exits with code 2. Even if that guard is bypassed somehow, the server rejects the second daemon's `DaemonConnect` with a typed error and the second daemon exits with code 3 — no more silent slot-displacement oscillation.
diff --git a/src/Capacitor.Cli.Core/Resources/help-daemon.txt b/src/Capacitor.Cli.Core/Resources/help-daemon.txt
index 4854d43ba..9ae9c4a20 100644
--- a/src/Capacitor.Cli.Core/Resources/help-daemon.txt
+++ b/src/Capacitor.Cli.Core/Resources/help-daemon.txt
@@ -8,6 +8,7 @@ Subcommands:
   status [--name N]       Show daemon status (lists all when --name omitted)
   logs                    Show recent daemon log output
   doctor [--clean]        Diagnose lock-file state, optionally clean stale entries
+  service <action>        Manage the OS service (launchd/systemd/Scheduled Task)
 
 Options for start:
   --name <name>           Daemon name (defaults to OS username)
@@ -28,6 +29,17 @@ Options for doctor:
                           gone). Held entries are never touched. Without
                           --clean, doctor reports state without modifying.
 
+Subcommands for service (per-user; auto-restarts on crash/SIGKILL, starts at login):
+  install [--name N] [--profile P] [--max-agents N] [--no-start]
+                          Register the daemon as an OS service and start it.
+                          Pins the profile via KCAP_PROFILE and captures PATH so
+                          claude/codex resolve as they do in your shell.
+  uninstall [--name N]    Stop and remove the service unit.
+  start [--name N]        Start the installed service now.
+  stop [--name N]         Stop the running service (stays installed; returns at
+                          next login or `service start`).
+  status [--name N]       Show installed / running state.
+
 Notes:
   Each daemon holds an exclusive flock on ~/.config/kcap/daemons/<name>.lock
   for its entire lifetime. The kernel releases the lock automatically on

From ff2279f181ed9a946bfa4e41a570656a0fcc4ecc Mon Sep 17 00:00:00 2001
From: Alexey Zimarev <alex@zimarev.com>
Date: Wed, 10 Jun 2026 18:01:22 +0200
Subject: [PATCH 14/16] feat(daemon): synchronous stderr backstop for
 death-rattle messages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The default AddSimpleConsole provider queues writes on a background thread
(ConsoleLoggerProcessor) that can drop messages enqueued during runtime
teardown — so a ProcessExit / signal-handler log line may never reach the
terminal even though the hook fired. Add a DeathRattle() helper that writes
straight to Console.Error (flushed, best-effort) from every exit hook
(lifetime stopping/stopped, AppDomain unhandled/ProcessExit, unobserved
task, POSIX signals), guaranteeing at least one byte lands before the
logging pipeline tears down.

This can't catch an external SIGKILL (jetsam/OOM) — which is what the new
`kcap daemon service` supervisor addresses — but it does surface every
catchable exit reason.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 src/Capacitor.Cli.Daemon/DaemonRunner.cs | 38 ++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 3 deletions(-)

diff --git a/src/Capacitor.Cli.Daemon/DaemonRunner.cs b/src/Capacitor.Cli.Daemon/DaemonRunner.cs
index a374bc8b2..a481ba069 100644
--- a/src/Capacitor.Cli.Daemon/DaemonRunner.cs
+++ b/src/Capacitor.Cli.Daemon/DaemonRunner.cs
@@ -203,8 +203,14 @@ await Console.Error.WriteLineAsync(
         // Lifetime-driven log lines — pair with the AppDomain/signal hooks so
         // we can distinguish a cooperative StopApplication (e.g. NameInUse,
         // Ctrl+C consumed by ConsoleLifetime) from an outside-the-runtime kill.
-        lifetime.ApplicationStopping.Register(() => LogLifetimeStopping(logger));
-        lifetime.ApplicationStopped.Register(() => LogLifetimeStopped(logger));
+        lifetime.ApplicationStopping.Register(() => {
+            DeathRattle("Lifetime: ApplicationStopping fired");
+            LogLifetimeStopping(logger);
+        });
+        lifetime.ApplicationStopped.Register(() => {
+            DeathRattle("Lifetime: ApplicationStopped fired");
+            LogLifetimeStopped(logger);
+        });
 
         // AI-630: if the server rejects our DaemonConnect because another
         // live daemon owns the (owner, name) slot, signal host shutdown
@@ -315,11 +321,13 @@ await Console.Error.WriteLineAsync(
     static void RegisterDeathRattle(ILogger logger, IHostApplicationLifetime lifetime) {
         AppDomain.CurrentDomain.UnhandledException += (_, args) => {
             if (args.ExceptionObject is Exception ex) {
+                DeathRattle($"AppDomain.UnhandledException (terminating={args.IsTerminating}): {ex.GetType().Name}: {ex.Message}");
                 LogUnhandledException(logger, ex, args.IsTerminating);
             }
         };
 
         TaskScheduler.UnobservedTaskException += (_, args) => {
+            DeathRattle($"TaskScheduler.UnobservedTaskException: {args.Exception.GetType().Name}: {args.Exception.Message}");
             LogUnobservedTaskException(logger, args.Exception);
             // Mark observed so the default policy (a no-op in .NET 5+, but a
             // process-killing rethrow on legacy/AOT configurations) can't
@@ -327,7 +335,10 @@ static void RegisterDeathRattle(ILogger logger, IHostApplicationLifetime lifetim
             args.SetObserved();
         };
 
-        AppDomain.CurrentDomain.ProcessExit += (_, _) => LogProcessExit(logger);
+        AppDomain.CurrentDomain.ProcessExit += (_, _) => {
+            DeathRattle("AppDomain.ProcessExit fired (this is the last log line)");
+            LogProcessExit(logger);
+        };
 
         // POSIX signal hooks. ConsoleLifetime already wires SIGINT and SIGTERM
         // to lifetime.StopApplication(); our registration is additive (multiple
@@ -345,6 +356,7 @@ static void RegisterDeathRattle(ILogger logger, IHostApplicationLifetime lifetim
         foreach (var signal in new[] { PosixSignal.SIGINT, PosixSignal.SIGTERM, PosixSignal.SIGHUP, PosixSignal.SIGQUIT }) {
             try {
                 _signalRegistrations.Add(PosixSignalRegistration.Create(signal, ctx => {
+                    DeathRattle($"Received POSIX signal {ctx.Signal} — requesting cooperative shutdown");
                     LogPosixSignal(logger, ctx.Signal);
                     ctx.Cancel = true;
                     lifetime.StopApplication();
@@ -368,4 +380,24 @@ static void RegisterDeathRattle(ILogger logger, IHostApplicationLifetime lifetim
     /// lifetime as the process.
     /// </summary>
     static readonly List<PosixSignalRegistration> _signalRegistrations = [];
+
+    /// <summary>
+    /// Synchronous stderr backstop for death-rattle messages. The default
+    /// <c>AddSimpleConsole</c> provider uses a background-thread queue
+    /// (<c>ConsoleLoggerProcessor</c>) that can drop messages enqueued during
+    /// runtime teardown — so a <c>ProcessExit</c> or signal-handler log line
+    /// may never reach the terminal even though the hook fired. Writing
+    /// directly to <see cref="Console.Error"/> bypasses the queue and lands
+    /// on stderr immediately. Best-effort: a closed terminal or broken pipe
+    /// must not throw out of an exit hook.
+    /// </summary>
+    static void DeathRattle(string message) {
+        try {
+            Console.Error.WriteLine($"{DateTime.Now:yyyy-MM-dd HH:mm:ss.fff} [death-rattle] {message}");
+            Console.Error.Flush();
+        } catch {
+            // Stderr might be redirected to a closed pipe, the terminal
+            // might be gone, etc. Already exiting — nothing useful to do.
+        }
+    }
 }

From 03559f57feadfc89a704451ec9a22e53680fc197 Mon Sep 17 00:00:00 2001
From: Alexey Zimarev <alex@zimarev.com>
Date: Wed, 10 Jun 2026 21:17:51 +0200
Subject: [PATCH 15/16] fix(daemon): address PR #137 review (service teardown,
 escaping, doctor)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- P1: `kcap uninstall` now deregisters installed OS services first
  (ListInstalled → Uninstall) before `daemon stop --yes`. Previously the
  stop-deferral for service-managed daemons left launchd/systemd/Scheduled
  Task units registered while the config dir was deleted.
- P2: systemd Environment= values and ExecStart argv are now double-quoted
  (with \ and " escaped) when they contain whitespace — paths/PATH entries
  with spaces no longer split.
- P2: launchd doctor reads ProgramArguments[0] (LaunchdUnit.BinaryFromPlist)
  instead of the document's first <string>, which was the Label — fixes a
  false "binary missing" for every valid launchd service.
- P2: Windows doctor reads the kcap-daemon.exe path baked inside the .cmd
  wrapper (WindowsTaskUnit.BinaryFromWrapper) instead of the wrapper path, so
  a moved daemon binary is detected even when the wrapper still exists.

+4 unit tests (binary parsers, systemd space-quoting). 1321 pass, AOT clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../Commands/UninstallCommand.cs              | 18 +++++++++++++++
 .../Services/LaunchdServiceManager.cs         |  4 +---
 src/Capacitor.Cli/Services/LaunchdUnit.cs     | 12 ++++++++++
 src/Capacitor.Cli/Services/SystemdUnit.cs     | 23 ++++++++++++++++---
 .../WindowsScheduledTaskServiceManager.cs     |  5 +++-
 src/Capacitor.Cli/Services/WindowsTaskUnit.cs | 13 +++++++++++
 .../Services/LaunchdUnitTests.cs              |  8 +++++++
 .../Services/SystemdUnitTests.cs              | 13 +++++++++++
 .../Services/WindowsTaskUnitTests.cs          | 13 +++++++++++
 9 files changed, 102 insertions(+), 7 deletions(-)

diff --git a/src/Capacitor.Cli/Commands/UninstallCommand.cs b/src/Capacitor.Cli/Commands/UninstallCommand.cs
index 0d4c40508..459a3b268 100644
--- a/src/Capacitor.Cli/Commands/UninstallCommand.cs
+++ b/src/Capacitor.Cli/Commands/UninstallCommand.cs
@@ -1,5 +1,6 @@
 using Capacitor.Cli.Core;
 using Capacitor.Cli.Core.Cursor;
+using Capacitor.Cli.Services;
 
 namespace Capacitor.Cli.Commands;
 
@@ -74,6 +75,23 @@ await Console.Out.WriteLineAsync(
         // — this flag captures the boolean for the final decision only.
         var hadFailures = false;
 
+        // Deregister any OS-managed daemon services FIRST. `daemon stop` defers to
+        // the supervisor for service-managed daemons (a raw kill would be
+        // auto-restarted), so without this the launchd/systemd/Scheduled-Task unit
+        // would survive uninstall and keep relaunching a daemon whose config we're
+        // about to delete. Uninstalling the unit also stops the running instance
+        // (launchctl bootout / systemctl disable --now), after which the plain
+        // `daemon stop --yes` below mops up any non-service daemons.
+        try {
+            var services = ServiceManagerFactory.ForCurrentOs();
+            foreach (var id in services.ListInstalled()) {
+                services.Uninstall(id);
+                await Console.Out.WriteLineAsync($"  • Removed daemon service '{id}' ({services.Describe()})");
+            }
+        } catch (PlatformNotSupportedException) {
+            // No service backend on this OS — nothing to deregister.
+        }
+
         // Stop daemons first — they hold lock files inside the config dir we're
         // about to delete. --yes silences the multi-daemon confirmation so this
         // works non-interactively. A non-zero exit code means at least one
diff --git a/src/Capacitor.Cli/Services/LaunchdServiceManager.cs b/src/Capacitor.Cli/Services/LaunchdServiceManager.cs
index bf53a734c..655d724e3 100644
--- a/src/Capacitor.Cli/Services/LaunchdServiceManager.cs
+++ b/src/Capacitor.Cli/Services/LaunchdServiceManager.cs
@@ -1,5 +1,4 @@
 using System.Runtime.InteropServices;
-using System.Xml.Linq;
 
 namespace Capacitor.Cli.Services;
 
@@ -25,8 +24,7 @@ public IReadOnlyList<string> ListInstalled() {
     public ServiceStatus Status(string serviceId) {
         var path = LaunchdUnit.PlistPath(serviceId);
         if (!File.Exists(path)) return new ServiceStatus(ServiceState.NotInstalled, null);
-        // First <string> in the plist is the daemon binary (ProgramArguments[0]) — for doctor.
-        var bin = XDocument.Load(path).Descendants("string").FirstOrDefault()?.Value;
+        var bin = LaunchdUnit.BinaryFromPlist(File.ReadAllText(path)); // ProgramArguments[0], not the Label
         var (code, stdout, _) = ServiceProcess.Run("launchctl", LaunchdUnit.PrintArgs(Uid(), serviceId));
         return new ServiceStatus(LaunchdUnit.StatusFromPrint(code, stdout), bin);
     }
diff --git a/src/Capacitor.Cli/Services/LaunchdUnit.cs b/src/Capacitor.Cli/Services/LaunchdUnit.cs
index c9ceee3fd..3f2c175af 100644
--- a/src/Capacitor.Cli/Services/LaunchdUnit.cs
+++ b/src/Capacitor.Cli/Services/LaunchdUnit.cs
@@ -1,4 +1,5 @@
 using System.Text;
+using System.Xml.Linq;
 using Capacitor.Cli.Core;
 
 namespace Capacitor.Cli.Services;
@@ -61,6 +62,17 @@ public static IReadOnlyList<string> ProgramArguments(ServiceSpec spec) =>
             : null;
     }
 
+    /// <summary>
+    /// The daemon binary baked into a plist — <c>ProgramArguments[0]</c>, i.e. the
+    /// first <c>&lt;string&gt;</c> inside the (sole) <c>&lt;array&gt;</c>. NOT the
+    /// document's first <c>&lt;string&gt;</c>, which is the <c>Label</c>. Used by
+    /// <c>daemon doctor</c> to detect a moved binary.
+    /// </summary>
+    public static string? BinaryFromPlist(string plistXml) {
+        var array = XDocument.Parse(plistXml).Descendants("array").FirstOrDefault();
+        return array?.Elements("string").FirstOrDefault()?.Value;
+    }
+
     // ── command vectors (uid passed in so these stay pure) ──
     public static string[] BootstrapArgs(int uid, string plistPath) => ["bootstrap", $"gui/{uid}", plistPath];
     public static string[] BootoutArgs(int uid, string id)          => ["bootout", $"gui/{uid}/{Label(id)}"];
diff --git a/src/Capacitor.Cli/Services/SystemdUnit.cs b/src/Capacitor.Cli/Services/SystemdUnit.cs
index 4b70e0d9d..e1947a7be 100644
--- a/src/Capacitor.Cli/Services/SystemdUnit.cs
+++ b/src/Capacitor.Cli/Services/SystemdUnit.cs
@@ -23,10 +23,12 @@ public static string Unit(ServiceSpec spec) {
 
         sb.Append("[Service]\n");
         foreach (var (k, v) in spec.Environment)
-            sb.Append($"Environment={ServiceText.SystemdValue(k)}={ServiceText.SystemdValue(v)}\n");
+            sb.Append($"Environment={EnvAssignment(k, ServiceText.SystemdValue(v))}\n");
 
-        var args = string.Join(' ', new[] { "--name", spec.ServiceId, "--log-file", spec.LogPath }.Concat(spec.ExtraArgs));
-        sb.Append($"ExecStart={spec.DaemonBinaryPath} {args}\n");
+        var parts = new[] { spec.DaemonBinaryPath, "--name", spec.ServiceId, "--log-file", spec.LogPath }
+            .Concat(spec.ExtraArgs)
+            .Select(QuoteArg);
+        sb.Append($"ExecStart={string.Join(' ', parts)}\n");
         sb.Append("Restart=on-failure\n");
         sb.Append("RestartSec=5\n");
         sb.Append("StartLimitIntervalSec=60\n");
@@ -56,4 +58,19 @@ public static ServiceState StatusFrom(string activeOut, int enabledExit) {
         if (activeOut.Trim().Equals("active", StringComparison.OrdinalIgnoreCase)) return ServiceState.Running;
         return enabledExit == 0 ? ServiceState.Installed : ServiceState.NotInstalled;
     }
+
+    // ── systemd value/argument quoting ──
+    // systemd splits Environment= and ExecStart on unquoted whitespace, so any
+    // value/path with a space must be double-quoted (with \ and " escaped).
+    static bool NeedsQuote(string s) =>
+        s.Length == 0 || s.Any(c => char.IsWhiteSpace(c) || c is '"' or '\\');
+
+    static string Esc(string s) => s.Replace("\\", "\\\\").Replace("\"", "\\\"");
+
+    /// <summary>An ExecStart argument, double-quoted only when it contains whitespace/quotes.</summary>
+    static string QuoteArg(string a) => NeedsQuote(a) ? $"\"{Esc(a)}\"" : a;
+
+    /// <summary>An <c>Environment=</c> assignment; the whole <c>KEY=VALUE</c> is quoted when VALUE needs it.</summary>
+    static string EnvAssignment(string key, string value) =>
+        NeedsQuote(value) ? $"\"{key}={Esc(value)}\"" : $"{key}={value}";
 }
diff --git a/src/Capacitor.Cli/Services/WindowsScheduledTaskServiceManager.cs b/src/Capacitor.Cli/Services/WindowsScheduledTaskServiceManager.cs
index 2aa40db03..5e9b2d568 100644
--- a/src/Capacitor.Cli/Services/WindowsScheduledTaskServiceManager.cs
+++ b/src/Capacitor.Cli/Services/WindowsScheduledTaskServiceManager.cs
@@ -27,7 +27,10 @@ public IReadOnlyList<string> ListInstalled() {
 
     public ServiceStatus Status(string serviceId) {
         var (code, stdout, _) = ServiceProcess.Run("schtasks", WindowsTaskUnit.QueryArgs(serviceId));
-        var bin = File.Exists(WindowsTaskUnit.WrapperPath(serviceId)) ? WindowsTaskUnit.WrapperPath(serviceId) : null;
+        var wrapper = WindowsTaskUnit.WrapperPath(serviceId);
+        // Report the daemon binary baked inside the wrapper (not the wrapper itself)
+        // so doctor catches a moved kcap-daemon.exe even when the wrapper still exists.
+        var bin = File.Exists(wrapper) ? WindowsTaskUnit.BinaryFromWrapper(File.ReadAllText(wrapper)) : null;
         return new ServiceStatus(WindowsTaskUnit.StatusFromQuery(code, stdout), bin);
     }
 
diff --git a/src/Capacitor.Cli/Services/WindowsTaskUnit.cs b/src/Capacitor.Cli/Services/WindowsTaskUnit.cs
index 7f6ca38d9..1fc27ba54 100644
--- a/src/Capacitor.Cli/Services/WindowsTaskUnit.cs
+++ b/src/Capacitor.Cli/Services/WindowsTaskUnit.cs
@@ -57,6 +57,19 @@ public static string TaskXml(ServiceSpec spec, string wrapperPath) =>
     public static string? IdFromTaskName(string taskName) =>
         taskName.StartsWith(Prefix, StringComparison.Ordinal) ? taskName[Prefix.Length..] : null;
 
+    /// <summary>
+    /// The daemon binary the wrapper exec's — the first quoted token of its exec
+    /// line. <c>daemon doctor</c> checks THIS (not the wrapper's own existence),
+    /// since the wrapper can survive while the baked kcap-daemon.exe path is stale.
+    /// Reverses the <c>%%</c> cmd-escaping applied at write time.
+    /// </summary>
+    public static string? BinaryFromWrapper(string wrapperText) {
+        var line = wrapperText.Split('\n').Select(l => l.Trim()).LastOrDefault(l => l.StartsWith('"'));
+        if (line is null) return null;
+        var end = line.IndexOf('"', 1);
+        return end > 1 ? line[1..end].Replace("%%", "%") : null;
+    }
+
     // ── command vectors (schtasks) ──
     public static string[] CreateArgs(string id, string xmlPath) => ["/Create", "/TN", TaskName(id), "/XML", xmlPath, "/F"];
     public static string[] DeleteArgs(string id)                 => ["/Delete", "/TN", TaskName(id), "/F"];
diff --git a/test/Capacitor.Cli.Tests.Unit/Services/LaunchdUnitTests.cs b/test/Capacitor.Cli.Tests.Unit/Services/LaunchdUnitTests.cs
index 99c8cc817..804924b1b 100644
--- a/test/Capacitor.Cli.Tests.Unit/Services/LaunchdUnitTests.cs
+++ b/test/Capacitor.Cli.Tests.Unit/Services/LaunchdUnitTests.cs
@@ -45,6 +45,14 @@ await Assert.That(LaunchdUnit.IdFromPlistFileName("io.kurrent.kcap.daemon.laptop
         await Assert.That(LaunchdUnit.IdFromPlistFileName("unrelated.plist")).IsNull();
     }
 
+    [Test]
+    public async Task BinaryFromPlist_returns_program_argument_zero_not_the_label() {
+        var plist = LaunchdUnit.Plist(Spec());
+        // Regression: the Label is the first <string> in the document; the binary
+        // is the first <string> inside <array> (ProgramArguments).
+        await Assert.That(LaunchdUnit.BinaryFromPlist(plist)).IsEqualTo("/opt/kcap/kcap-daemon");
+    }
+
     [Test]
     public async Task StatusFromPrint_maps_exit_and_state() {
         await Assert.That(LaunchdUnit.StatusFromPrint(exitCode: 1, stdout: "")).IsEqualTo(ServiceState.NotInstalled);
diff --git a/test/Capacitor.Cli.Tests.Unit/Services/SystemdUnitTests.cs b/test/Capacitor.Cli.Tests.Unit/Services/SystemdUnitTests.cs
index f2e22a6ed..3178a447e 100644
--- a/test/Capacitor.Cli.Tests.Unit/Services/SystemdUnitTests.cs
+++ b/test/Capacitor.Cli.Tests.Unit/Services/SystemdUnitTests.cs
@@ -23,6 +23,19 @@ public async Task Unit_has_execstart_restart_and_env() {
         await Assert.That(unit).Contains("WantedBy=default.target");
     }
 
+    [Test]
+    public async Task Unit_quotes_values_and_args_with_spaces() {
+        var spec = Spec() with {
+            DaemonBinaryPath = "/opt/k cap/kcap-daemon",
+            LogPath          = "/home/u/my logs/daemon-laptop.log",
+            Environment      = new Dictionary<string, string> { ["PATH"] = "/a b:/c", ["KCAP_PROFILE"] = "work" },
+        };
+        var unit = SystemdUnit.Unit(spec);
+        await Assert.That(unit).Contains("Environment=\"PATH=/a b:/c\"");
+        await Assert.That(unit).Contains("Environment=KCAP_PROFILE=work"); // no space → unquoted
+        await Assert.That(unit).Contains("ExecStart=\"/opt/k cap/kcap-daemon\" --name laptop --log-file \"/home/u/my logs/daemon-laptop.log\" --max-agents 8");
+    }
+
     [Test]
     public async Task IdFromUnitFileName_extracts_id() {
         await Assert.That(SystemdUnit.IdFromUnitFileName("kcap-daemon-laptop.service")).IsEqualTo("laptop");
diff --git a/test/Capacitor.Cli.Tests.Unit/Services/WindowsTaskUnitTests.cs b/test/Capacitor.Cli.Tests.Unit/Services/WindowsTaskUnitTests.cs
index 1cfa7529b..208896134 100644
--- a/test/Capacitor.Cli.Tests.Unit/Services/WindowsTaskUnitTests.cs
+++ b/test/Capacitor.Cli.Tests.Unit/Services/WindowsTaskUnitTests.cs
@@ -28,6 +28,19 @@ public async Task Wrapper_doubles_percent_in_values() {
         await Assert.That(WindowsTaskUnit.Wrapper(spec)).Contains("set \"X=50%%done\"");
     }
 
+    [Test]
+    public async Task BinaryFromWrapper_extracts_daemon_path_not_wrapper() {
+        var bin = WindowsTaskUnit.BinaryFromWrapper(WindowsTaskUnit.Wrapper(Spec()));
+        await Assert.That(bin).IsEqualTo(@"C:\kcap\kcap-daemon.exe");
+    }
+
+    [Test]
+    public async Task BinaryFromWrapper_unescapes_doubled_percent() {
+        var spec = Spec() with { DaemonBinaryPath = @"C:\dir%x\kcap-daemon.exe" };
+        await Assert.That(WindowsTaskUnit.BinaryFromWrapper(WindowsTaskUnit.Wrapper(spec)))
+            .IsEqualTo(@"C:\dir%x\kcap-daemon.exe");
+    }
+
     [Test]
     public async Task TaskXml_is_well_formed_and_runs_cmd_wrapper() {
         var xml = WindowsTaskUnit.TaskXml(Spec(), @"C:\Users\u\.config\kcap\daemon-service-laptop.cmd");

From eaa2c87a7265d15065f5423f3165f87846ba511f Mon Sep 17 00:00:00 2001
From: Alexey Zimarev <alex@zimarev.com>
Date: Wed, 10 Jun 2026 21:25:49 +0200
Subject: [PATCH 16/16] fix(daemon): quote-aware systemd ExecStart binary parse
 for doctor
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Follow-up to the systemd Environment=/ExecStart quoting: the doctor reader
still used Split(' ', 2), so a quoted `ExecStart="/opt/k cap/kcap-daemon" …`
(spaced path) parsed to `"/opt/k`, false-reporting a missing binary. Add a
quote-aware SystemdUnit.BinaryFromUnit (reverses the \\ / \" escaping) and use
it in SystemdServiceManager.Status. +1 test covering the whitespace path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../Services/SystemdServiceManager.cs         |  7 +----
 src/Capacitor.Cli/Services/SystemdUnit.cs     | 28 +++++++++++++++++++
 .../Services/SystemdUnitTests.cs              |  8 ++++++
 3 files changed, 37 insertions(+), 6 deletions(-)

diff --git a/src/Capacitor.Cli/Services/SystemdServiceManager.cs b/src/Capacitor.Cli/Services/SystemdServiceManager.cs
index ce33a70d1..6080e4fb1 100644
--- a/src/Capacitor.Cli/Services/SystemdServiceManager.cs
+++ b/src/Capacitor.Cli/Services/SystemdServiceManager.cs
@@ -19,15 +19,10 @@ public ServiceStatus Status(string serviceId) {
         if (!File.Exists(path)) return new ServiceStatus(ServiceState.NotInstalled, null);
         var (_, active, _)      = ServiceProcess.Run("systemctl", SystemdUnit.IsActiveArgs(serviceId));
         var (enabledExit, _, _) = ServiceProcess.Run("systemctl", SystemdUnit.IsEnabledArgs(serviceId));
-        var bin = ExecStartBinary(path);
+        var bin = SystemdUnit.BinaryFromUnit(File.ReadAllText(path)); // quote-aware ExecStart parse
         return new ServiceStatus(SystemdUnit.StatusFrom(active, enabledExit), bin);
     }
 
-    static string? ExecStartBinary(string unitPath) {
-        var line = File.ReadLines(unitPath).FirstOrDefault(l => l.StartsWith("ExecStart=", StringComparison.Ordinal));
-        return line?["ExecStart=".Length..].Split(' ', 2)[0];
-    }
-
     public void Install(ServiceSpec spec, bool startNow) {
         Directory.CreateDirectory(SystemdUnit.UserUnitDir());
         File.WriteAllText(SystemdUnit.UnitPath(spec.ServiceId), SystemdUnit.Unit(spec));
diff --git a/src/Capacitor.Cli/Services/SystemdUnit.cs b/src/Capacitor.Cli/Services/SystemdUnit.cs
index e1947a7be..78b3e3836 100644
--- a/src/Capacitor.Cli/Services/SystemdUnit.cs
+++ b/src/Capacitor.Cli/Services/SystemdUnit.cs
@@ -59,6 +59,34 @@ public static ServiceState StatusFrom(string activeOut, int enabledExit) {
         return enabledExit == 0 ? ServiceState.Installed : ServiceState.NotInstalled;
     }
 
+    /// <summary>
+    /// The daemon binary from a rendered unit's <c>ExecStart=</c> — quote-aware,
+    /// since <see cref="Unit"/> may emit <c>ExecStart="/opt/k cap/kcap-daemon" …</c>
+    /// for a path with spaces. Used by <c>daemon doctor</c>.
+    /// </summary>
+    public static string? BinaryFromUnit(string unitText) {
+        var line = unitText.Split('\n').Select(l => l.Trim())
+            .FirstOrDefault(l => l.StartsWith("ExecStart=", StringComparison.Ordinal));
+        return line is null ? null : FirstToken(line["ExecStart=".Length..]);
+    }
+
+    /// <summary>First whitespace-delimited token, honoring a leading double-quoted segment (reverses <see cref="Esc"/>).</summary>
+    static string? FirstToken(string s) {
+        if (s.Length == 0) return null;
+        if (s[0] != '"') {
+            var sp = s.IndexOf(' ');
+            return sp < 0 ? s : s[..sp];
+        }
+
+        var sb = new StringBuilder();
+        for (var i = 1; i < s.Length; i++) {
+            if (s[i] == '\\' && i + 1 < s.Length) { sb.Append(s[++i]); continue; } // \\ -> \ , \" -> "
+            if (s[i] == '"') break;
+            sb.Append(s[i]);
+        }
+        return sb.ToString();
+    }
+
     // ── systemd value/argument quoting ──
     // systemd splits Environment= and ExecStart on unquoted whitespace, so any
     // value/path with a space must be double-quoted (with \ and " escaped).
diff --git a/test/Capacitor.Cli.Tests.Unit/Services/SystemdUnitTests.cs b/test/Capacitor.Cli.Tests.Unit/Services/SystemdUnitTests.cs
index 3178a447e..cc9cb093f 100644
--- a/test/Capacitor.Cli.Tests.Unit/Services/SystemdUnitTests.cs
+++ b/test/Capacitor.Cli.Tests.Unit/Services/SystemdUnitTests.cs
@@ -42,6 +42,14 @@ public async Task IdFromUnitFileName_extracts_id() {
         await Assert.That(SystemdUnit.IdFromUnitFileName("other.service")).IsNull();
     }
 
+    [Test]
+    public async Task BinaryFromUnit_parses_unquoted_and_quoted_execstart() {
+        await Assert.That(SystemdUnit.BinaryFromUnit(SystemdUnit.Unit(Spec()))).IsEqualTo("/opt/kcap/kcap-daemon");
+
+        var spaced = Spec() with { DaemonBinaryPath = "/opt/k cap/kcap-daemon" };
+        await Assert.That(SystemdUnit.BinaryFromUnit(SystemdUnit.Unit(spaced))).IsEqualTo("/opt/k cap/kcap-daemon");
+    }
+
     [Test]
     public async Task StatusFrom_maps_active_strings() {
         await Assert.That(SystemdUnit.StatusFrom(activeOut: "active", enabledExit: 0)).IsEqualTo(ServiceState.Running);