Idunn/docs/host-actuator.md

# Host actuator: Idunn on a Windows workstation

Idunn on yggdrasil is a Linux control plane whose every driver is a local
actuator: git, docker, `systemd-run`, nginx, a file lock. It has no remote
execution. Muninn runs on Raven, a Windows workstation, inside the logged-on
user's desktop session because it captures that desktop and loops its audio.
Windows `sshd` spawns in session 0, so every remote path into the desktop
session is a hop through a scheduled task, and that hop is where deaths hide.

This document is the authority map for the cut that lets Idunn manage a
target on a host it cannot actuate locally. It is written before the code and
maintained with it.

## Objective

A Muninn deployment to Raven is one Idunn transaction: the same brake, the
same sealed release, the same Expected/activation/presence chain, the same
continuity, as odin on yggdrasil. Nothing on Raven is started by an operator
running a script, and a dead `muninn serve` is seen the tick it dies.

## Authority map

- **Owner:** the yggdrasil Idunn daemon stays the single deployment and
  continuity authority. It seals, brakes, publishes Expected, issues
  activations, admits Odin's correlation, fences, leases and retires. The
  host actuator decides nothing.
- **Host actuator (`idunn-host`):** one process per managed Windows host,
  running in the user session, started at logon by one scheduled task. It
  dials Idunn over CultNet RUDP on the WireGuard mesh and executes the
  consequences of two ports, runner and workload, for that host. It holds
  the host's service identity and signs every report with it. It keeps no
  transaction state; a restarted actuator re-adopts a running workload by
  pid, creation time and executable digest.
- **Inputs to the actuator:** signed requests from Idunn carrying the
  compiled plan, sealed release, Expected, activation and its credential.
  The exact source is fetched by the actuator from the origin at the exact
  revision Idunn froze; the plan's recipe bytes must match the tree.
- **Outputs from the actuator:** `SealedRelease`, installed root, and a
  `HostWorkloadObservation` (pid, creation time, executable path and
  sha256, command line sha256, environment names, runtime bundle, session
  id, user sid, exit code once exited), each signed by the host identity.
- **Transport:** the actuator dials; the host opens no inbound port and
  holds no credential for yggdrasil. Idunn binds its actuator hub on the
  mesh address only. Confidentiality is WireGuard's; authenticity is the
  two service identities (Idunn's, already enrolled; one new profile for
  host actuators). A request Idunn did not sign is dropped; a report the
  bound host anchor did not sign is dropped.
- **Derived state:** the actuator's own logs, the scheduled task's state,
  and Task Manager are evidence, never admission.
- **Forbidden writers:** `restart-muninn.ps1` and its VBS/`schtasks`
  launcher no longer start `serve` on a host with an actuator. The
  actuator install unregisters the Muninn serve task. Operator scripts on
  other Muninn hosts (starfire, nightwing) are untouched until those hosts
  get an actuator.
- **Shared paths:** deploy, continuity restart, and cancel all reach Raven
  through the same two ports the systemd and docker drivers implement.
  There is no second launch path.
- **Deletion line:** `WorkloadDriver` and `RunnerDriver` as single-variant
  enums are gone; the driver is the tag of the binding. The observation is
  a variant per workload kind, not a systemd struct that a Windows process
  would have to counterfeit. The Muninn serve scheduled task, its VBS and
  cmd launchers, and `Register-HiddenVbsTask` for serve leave
  `restart-muninn.ps1` once Raven is admitted.

## Current mechanism versus intended

| Concern | Today | After |
|---|---|---|
| Runner | `DockerRunnerDriver`, concrete field on `Engine` | `RunnerPort` chosen per plan from the binding: docker on yggdrasil, `host-native` through the actuator |
| Workload | `SystemdTransientWorkloadDriver`, concrete field | `WorkloadPort` chosen per plan: `systemd-transient` or `host-actuator` |
| Observation | 47-field systemd/`/proc` struct | `WorkloadObservation::{Systemd, Host}`, untagged on the wire so persisted records decode unchanged |
| Isolation proof | uid, pid ns, mount ns | per variant: Linux as before; host by pid and creation time, which a workstation cannot fake for two live processes |
| Liveness | `systemctl show` per tick | `Observe` request per tick over the session; a closed session is an error, and the error is "dead" |
| Route | nginx stream fragment | none for Muninn: consumers discover its endpoint through Odin's advertisement |
| Presence | Muninn publishes none | Muninn publishes a dual-signed `gamecult.runtime_presence_health.v2` to Odin from the runtime bundle and activation credential the actuator hands it |

## Invariants that must hold across the cut

1. A persisted transaction or admitted generation written by the previous
   Idunn decodes unchanged. Verified by decoding a systemd observation
   encoded alone as the enum.
2. No path on yggdrasil can start, stop or observe a host workload except
   through the actuator session bound to that host's anchor.
3. A host with no attached actuator is a failed observation, which
   continuity counts as a charged attempt and retries on its capped backoff
   (it never gives up; six in an hour only pages), exactly like a unit that
   will not start.
4. The actuator cannot be told to run a program the recipe did not declare;
   `allowed_programs` on the host-native runner is enforced on the host.

## What the cut taught, same day

Each of these was found by running the pipe against Raven, not by reading.

- **Fixed host resources cannot overlap.** Muninn owns the desktop, the
  capture device and two advertised ports; candidate-then-promote failed at
  bind time. `rollout.strategy = "stop-then-start"` exists for exactly a
  route-less host-actuator workload: the admitted incumbent is stopped at
  Starting, before the candidate starts, and supervision leaves the target
  alone from Starting on: the transaction takes the target there (one
  `take_target` CAS) rather than at Fencing. A systemd-transient workload may not declare it.
- **An unobservable host is silence.** The hub returns a typed
  `HostUnobservable` for not-attached, detached, reconnected and unanswered.
  Supervision skips that tick and logs it. Before this, an Idunn restart
  burned all three continuity attempts inside the actuator's 15-second
  reattach window and demoted a healthy Muninn.
- **The hub is serviced on its own thread.** A tick that blocked on odin's
  docker build for a minute starved every attached host into a timeout.
- **A binding path is absolute by its own shape.** The actuator re-parses
  the Linux binding on Windows; `/var/...` must not fail there.
- **The actuator's git never rewrites line endings.** The frozen tree is
  byte-exact; Windows git's autocrlf made the recipe bytes differ from the
  plan's.
- **The actuator must be rebuilt when the binding vocabulary grows.** It
  parses the same TOML the daemon does, from the same crate; an older
  actuator refuses a plan whose binding it cannot decode, which is the
  right refusal and a deploy step to remember.
- **A provider's presence sequence must survive its restart.** Odin admits
  only above the sequence it last stored for a signer; Muninn now uses the
  observation clock.
- **Odin (not this repo) died on a stale provider presence.** A continuity
  restart of raven-muninn left the previous presence in Odin's store; Odin
  treated a stored presence that no longer authenticated as tampering and
  exited, on every restart, until Idunn gave up on it. Fixed in Odin
  `aaaa8ed`: stale, logged, not fatal. Recorded here because this cut is
  what made a provider restart under Idunn a routine event.

Measured on Raven: cold build 1 m 20 s, warm 50 s; seal to admitted about
90 s including the brake release; a killed `serve` is observed on the next
tick and restarted by continuity in 6 s; reattach after an Idunn restart
about 20 s, during which the target is logged unobservable and untouched.

## Subtraction budget

Removed: `WorkloadDriver`, `RunnerDriver` enums; the Muninn serve launcher
body in `restart-muninn.ps1` and its `repair-raven-muninn-task-actions.ps1`
once Raven is admitted. Added: one binary target (`idunn-host`, Windows),
one module of wire records shared by both binaries, one identity profile,
`windows-sys` behind `cfg(windows)`. Net additive, bought by the capability
the operator ordered: a Windows host inside Idunn's authority.

## Build budget

`idunn` and `idunn-provision` are built for yggdrasil in docker
(`rust:latest`, `CARGO_TARGET_DIR=target/linux`; the test suite needs an
`/etc/machine-id` in the container) and installed with
`gamecult-ops/scripts/install-idunn-yggdrasil-release.sh`. `idunn-host`
builds on a Windows host with the stable toolchain and runs on Raven; it is
not built on yggdrasil. The library compiles on both; unix-only code is
`cfg(unix)`, and the Linux-shaped test fixtures pass on a Windows checkout
except the one parent-only-descriptor test.

Invoke Cargo directly as the container command or through a non-login shell.
A login shell can reset `PATH` and hide the Rust toolchain installed in the
build image.