Stella Ops Windows Host Agent

The Stella Ops Windows host agent is the RuntimeInstrumentation host service for Windows container estates. It shares StellaOps.Agent.Core identity, runtime status, health, configuration, and publisher contracts with the Linux agent, but keeps Windows lifecycle, ACL, and runtime-source behavior inside src/RuntimeInstrumentation/StellaOps.Agent.Windows/.

Current Base

Project: src/RuntimeInstrumentation/StellaOps.Agent.Windows/
Tests: src/RuntimeInstrumentation/StellaOps.Agent.Windows.Tests/
Host model: .NET generic-host service base with Microsoft.Extensions.Hosting.WindowsServices lifetime integration. Package tooling installs it under Windows Service Control Manager.
Windows Service name: Stella Ops RuntimeInstrumentation Agent.
Runtime status baseline: file-backed snapshots and bounded local commands.
Evidence posture: digest-gated Agent.Core evidence publication through IRuntimeEvidencePublisher; when no downstream publisher is configured, the default no-op publisher returns a retry result so entries remain in the bounded spool.
Out of scope: Kubernetes, Helm, DaemonSets, Tetragon, and Linux-only runtime assumptions.

Installation Shape

The base executable is StellaOps.Agent.Windows. Package tooling should install it as a Windows Service running under a least-privilege service account.

Service packaging must preserve:

The stable service name Stella Ops RuntimeInstrumentation Agent.
Read ACLs for %ProgramData%\StellaOps\windows-agent.json.
Read ACLs for configured runtime snapshot files.
Execute ACLs for configured command-backed runtime status tools.
Access to approved Windows runtime named pipes or APIs when those sources are implemented and enabled.

Native Windows Service packaging and installer scripts are not part of this base task. They must not add Kubernetes or Helm packaging.

Configuration

Configuration precedence is deterministic:

Local JSON files: %ProgramData%\StellaOps\windows-agent.json and windows-agent.json
Environment variables prefixed with STELLAOPS_WINDOWS_AGENT_
Optional policy-delivered JSON file referenced by RuntimeInstrumentation:WindowsAgent:PolicyFile

Required settings:

RuntimeInstrumentation:WindowsAgent:AgentId
RuntimeInstrumentation:WindowsAgent:HostId
RuntimeInstrumentation:WindowsAgent:InstallId
RuntimeInstrumentation:WindowsAgent:Environment
At least one runtime status file or command source

Command-backed sources must use a fully qualified executable path, typed arguments, UseShellExecute=false, explicit timeout, and stdout/stderr byte limits. Shell invocation is not allowed.

Runtime Status Sources

The active baseline supports:

File-backed Windows runtime snapshots using WindowsRuntimeStatusDocumentKind.WindowsContainerList or WindowsContainerStatus.
Command-backed snapshots from explicitly configured Windows executables such as approved Docker or containerd-on-Windows tooling.

The parser accepts common Windows/Docker-style fields including container id, image name/reference, image id/digest, observed timestamps, labels, and annotations. It normalizes only valid sha256:<64-hex> digests.

Native Windows runtime APIs and named-pipe clients remain planned until Stella Ops owns or approves the API contract, permission model, fixtures, dependencies, and tests.

Permissions

The Windows service account must be least-privilege. It needs only:

Read access to configuration and runtime snapshot files.
Execute access to configured runtime status commands.
Runtime API or named-pipe access only for explicitly enabled sources.
Write access to future local spool storage when persistent spool files are added.

Permission denied, unavailable runtime source, malformed data, tag-only image identity, stale status, ambiguous status, timed-out commands, over-large command output, and missing sources all fail closed.

Diagnostics And Failure Modes

Each collection cycle produces a WindowsHostAgentSnapshot with:

Agent.Core agent and host identity.
Effective configuration metadata split by file, environment, and policy layers.
Capability declarations.
Health state and reason code.
Publishable digest-backed runtime statuses.
Blocked statuses with deterministic reason codes.
Evidence publication diagnostics for publish attempts, published, retried, quarantined, dropped, duplicate observations, and the last reason code.
Source issues and local diagnostics counters.

Important reason codes:

Reason code	Meaning
`runtime_status.source_failed`	One or more configured sources failed.
`runtime_status.no_publishable_digest`	No collected status had a valid digest.
`runtime_status.some_records_blocked`	At least one status was blocked while another was publishable.
`runtime_status.digest_missing_or_malformed`	Status was tag-only or had a malformed digest.
`runtime_status.stale`	Status exceeded `MaxRuntimeStatusAge`.
`runtime_status.ambiguous`	Multiple records mapped to the same container id.
`runtime_status.permission_denied`	Service account lacks source access.
`runtime_status.runtime_unavailable`	Runtime command/API/named pipe is unavailable.
`runtime_status.command_timeout`	Command-backed source exceeded its timeout.
`runtime_status.command_output_too_large`	Command output exceeded configured bounds.

The bounded spool accepts only digest-valid HostRuntimeStatus records, rejects invalid digests, drops when full, records retry attempts, and removes entries when retry budgets are exhausted.