guru-connect/docs/specs/SPEC-018-managed-agent-service-host.md

# SPEC-018: Managed-Agent SYSTEM Service Host + Session Broker

**Status:** Proposed
**Priority:** P1 (blocks SPEC-016 Phase B end-to-end runtime and SPEC-013)
**Requested By:** Mike (2026-06-02)
**Estimated Effort:** X-Large

## Overview

Convert the managed/persistent GuruConnect agent from a user-context `HKCU\…\Run` autostart into a
**Windows SYSTEM service** that runs unattended — at the login screen, with no user logged in, across
reboots — and **brokers per-session capture/input worker processes** into the active interactive
desktop. A SYSTEM service lives in the isolated **Session 0** and cannot capture or inject the
interactive desktop directly, so the service spawns a worker into the target user session (the
ScreenConnect architecture).

This is foundational, not cosmetic. It unblocks three things at once:
1. **SPEC-016 Phase B end-to-end runtime** — the per-machine `cak_` store is ACL'd to SYSTEM +
   Administrators; today the agent runs as the interactive *user* and can't read its own store (the
   Phase B C1 *fail-fast guard* exists precisely because of this). Running as SYSTEM makes the store
   readable and removes the guard.
2. **True unattended access** — a user-context agent only runs while that user is logged in. Reaching
   a rebooted server or a machine sitting at the login screen (table-stakes for remote support)
   requires SYSTEM.
3. **SPEC-013 session selection / backstage** — the session-broker primitive built here is the
   substrate SPEC-013's session-switching UX drives.

**Success criteria:** the managed agent installs as an auto-start SYSTEM service; it holds the relay
connection and performs SPEC-016 enrollment as SYSTEM (reading/writing the SYSTEM-ACL'd `cak_`); it
spawns a capture/input worker into the active interactive session and relays frames; the worker is
respawned/retargeted on logon/logoff/console-connect; and the Phase B fail-fast guard is removed
because the store is now readable in-context.

## Background — why this is needed (confirmed in code)

- The persistent agent autostarts via `HKCU\…\Run` (`agent/src/startup.rs:21`, `STARTUP_KEY` = HKCU)
  → interactive-user token, not SYSTEM. The only SYSTEM service today is the separate `sas_service`
  (Secure Attention Sequence helper).
- SPEC-016 Phase B (`agent/src/credential_store.rs`) ACLs the `cak_` store to `*S-1-5-18` (SYSTEM) +
  `*S-1-5-32-544` (Administrators). In the current user context the agent writes but cannot read it
  back → the Phase B fail-fast guard (`agent/src/main.rs` `resolve_agent_credential`) emits
  "must run as the GuruConnect SYSTEM service (see SPEC-018)" instead of bricking.
- Capture/input live in the agent process (`agent/src/capture/`, `agent/src/input/`); a Session-0
  SYSTEM service cannot drive these against the interactive desktop without a per-session worker.

## Scope

### Included in v1

1. **Windows service install/lifecycle** (`agent/src/install.rs` + a new service module): register the
   managed agent as a **LocalSystem auto-start service** (`CreateServiceW` / a service crate),
   configure failure/recovery (restart on crash), and **replace the HKCU `Run` autostart for managed
   mode** (remove the Run entry on service install). Clean uninstall (stop + delete service).
2. **Service control loop** (Session 0, SYSTEM): owns the persistent WSS connection to the relay,
   performs SPEC-016 enrollment as SYSTEM (now able to read/write the `cak_` store), and dispatches
   session/connect requests to workers. Handles `SERVICE_CONTROL_STOP`/`SHUTDOWN` and
   `SERVICE_CONTROL_SESSIONCHANGE`.
3. **Session broker:** enumerate sessions (`WTSEnumerateSessionsW`), resolve the active interactive
   session (`WTSGetActiveConsoleSessionId`), obtain its user token (`WTSQueryUserToken` →
   `DuplicateTokenEx`), and spawn a **per-session capture/input worker** into that session's desktop
   (`CreateProcessAsUserW`, `winsta0\default`). The worker does DXGI capture + input injection in the
   user's session; the service relays frames over the existing transport.
4. **Service ↔ worker IPC:** a local, ACL'd channel (named pipe `\\.\pipe\guruconnect-<sessionId>`)
   carrying frames/input/control; pipe ACL restricted to SYSTEM + the target session user.
5. **Session-change handling:** on logon/logoff/console-connect/disconnect/lock/unlock, (re)spawn or
   retarget the worker so the active desktop is always the one being served.
6. **Remove the SPEC-016 Phase B fail-fast guard** once the service runs as SYSTEM (the store is
   readable in-context); keep the SYSTEM+Administrators ACL.

### Explicitly out of scope (anticipated, separate specs)

- **Session-selection / backstage UX** — the operator-facing picker and Session-0/secure-desktop
  command surface are **SPEC-013**; this spec only provides the broker primitive it drives.
- **Login-screen / secure-desktop (winlogon) capture** beyond the broker hook — the hard
  Secure-Desktop case is coordinated with SPEC-013; v1 here targets the active interactive session.
- **macOS/Linux service equivalents** — future SPEC-010 (cross-platform agents).

## Architecture

- **Agent splits into two roles:**
  - **service-host** (LocalSystem, Session 0): service lifecycle, relay transport, SPEC-016
    enrollment + `cak_` store, session broker, IPC server.
  - **session-worker** (per interactive session, user token): DXGI/GDI capture, input injection,
    IPC client. Spawned by the service via `CreateProcessAsUserW`.
- **Service install** (`install.rs`): `CreateServiceW` with `SERVICE_AUTO_START`, `SERVICE_WIN32_OWN_PROCESS`,
  recovery actions; uninstall stops + deletes. Replaces managed-mode `HKCU Run`.
- **Token handoff:** `WTSGetActiveConsoleSessionId` → `WTSQueryUserToken` → `DuplicateTokenEx`
  (primary token) → `CreateProcessAsUserW` with `lpDesktop = "winsta0\\default"`.
- **IPC:** named pipe per session, length-prefixed protobuf (reuse `proto/` message types where
  sensible), pipe security descriptor granting only SYSTEM + the session user.
- **Session events:** the service registers for `SERVICE_CONTROL_SESSIONCHANGE` and reacts to
  `WTS_CONSOLE_CONNECT`, `WTS_SESSION_LOGON/LOGOFF`, `WTS_SESSION_LOCK/UNLOCK`.

## Security considerations

- **LocalSystem is maximal privilege** — minimize the service's attack surface; validate every
  relay-delivered command; never spawn a worker except into a legitimately-enumerated active session.
- **IPC pipe must be ACL'd** (SYSTEM + the specific session user only) so a non-admin user can't
  inject capture/input commands by connecting to the pipe.
- **Token hygiene:** close duplicated tokens promptly; don't leak SYSTEM or user primary tokens.
- The SPEC-016 `cak_` store (SYSTEM-ACL'd) is now correctly readable; the fail-fast guard is removed
  but the ACL stays.
- **Audit:** service start/stop, enrollment-as-SYSTEM, worker spawn, session attach/retarget — written
  to the existing event pipeline.

## Implementation details

- New service module (e.g. `agent/src/service/{mod.rs, broker.rs, ipc.rs}`); worker entry split out of
  the current capture path. New `Commands` variants or an internal `--service`/`--session-worker`
  dispatch in `agent/src/main.rs`.
- `install.rs`: service create/recovery/delete; drop the managed-mode HKCU `Run` write.
- `windows` crate features: `Win32_System_Services`, `Win32_System_RemoteDesktop`
  (`WTS*`), `Win32_Security`, `Win32_System_Threading` (`CreateProcessAsUserW`),
  `Win32_System_Pipes`.
- Remove the `resolve_agent_credential` fail-fast guard branch added in SPEC-016 Phase B.

## Testing strategy

- **Service:** install → auto-start on boot → stop → uninstall on a clean VM.
- **`cak_` end-to-end:** SYSTEM service enrolls (SPEC-016), stores + reads the `cak_`, connects — the
  integration test SPEC-016 Phase B currently cannot run.
- **Session broker:** worker spawns into the active session; capture/input work; survives logoff→logon
  (respawn) and console-connect (retarget); fast-user-switch retarget.
- **Security:** non-admin cannot connect to the IPC pipe; worker runs with the user's token (not
  SYSTEM) in the user's desktop.

## Effort estimate & dependencies

- **Size:** X-Large (service host + worker split + token-handoff + IPC + session-change handling +
  install/uninstall).
- **Depends on:** SPEC-016 (enrollment + `cak_` store); the existing capture/input cores.
- **Unblocks:** SPEC-016 Phase B end-to-end runtime (and the parked managed-agent enrollment test on
  the internal beta machines); **SPEC-013** (session selection builds on this broker).

## Open questions

1. **Service vs. SYSTEM scheduled task** — a true Windows service (recovery, SCM integration) is the
   standard, robust choice; recommend service. Lock in planning.
2. **One multi-session worker vs. one worker per session** — per-session worker is simpler to reason
   about and isolates a crash to one session; confirm.
3. **IPC transport** — named pipe (recommended) vs. local TCP/loopback; pipe ACLing is the cleaner
   security story.
4. **Login-screen / Secure-Desktop capture** — how much (if any) in this spec vs. deferred to SPEC-013
   (it needs a worker in the winlogon/secure desktop, a distinct hard problem).
5. **Migration** — on upgrade, cleanly transition existing HKCU-`Run` managed installs to the service
   (remove the Run entry, install the service) without a gap.