spec: Windows runtime

[passcod]

Establishes the Seedling Windows runtime — a second runtime implementation targeting Windows Server hosts, speaking the same operator interface and language specs so the CLI, web UI, and protocol crates carry over. Conforms to the portable runtime spec (reconciliation, generations, lifecycle, barriers, history, faults, scheduling) and defines the Windows infrastructure those semantics run on. Rule IDs use the wcr[...] namespace, and the log store's use wlog[...].

Design

Each workload runs as a process-isolated Windows container under containerd + the runhcs shim. The artifact is a base-less OCI image (FROM scratch) completed at prepare time by stacking a single runtime-pulled OS base beneath its layers. Networking is per-instance HNS compartments with the mount graph enforced at the compartment boundary. containerd is a seedling-managed infrastructure dependency, started on demand and stopped when the host is idle — so an idle host runs only seedlingd.

The design rests on the property that seedlingd can restart without losing workloads: the runhcs shim owns the container and outlives containerd, and a restarting containerd re-attaches to it. That's what lets containerd be a restartable managed dependency rather than an always-on peer.

Decisions settled in review:

• Base-less FROM scratch artifact — MCR now ships distributable base layers, so "build FROM mcr and omit the base on push" doesn't hold; the base-less path also drops any host-build↔base-tag coupling.
• Process profile carried in the OCI config's Labels (au.bes.seedling.stop-method, au.bes.seedling.reload-event).
• Integrity via the standard OCI layer digest — no bespoke pre-attach verification.
• The reconciler owns restart. containerd has no restart policy and the shim does not restart tasks, so wcr[shim.ownership] does not claim it does. Restarts are recorded at the point the reconciler actions them, their cause is recovery-versus-deliberate rather than which component acted, a terminated container's exit status is read before its record is reaped, and the daemon-down gap is stated as a property rather than left to be found.
• Confinement is the mapping, not the permissions. A container's account is not a host principal, so a volume's host permissions cannot separate instances and a mapped volume is not confidential from the host. Both are stated in the spec rather than implied away.

Contents

Specs

• docs/spec/runtime-windows-containers.md — the runtime spec, 35 wcr[...] rules: platform floor, base image and composition, containers, restarts, networking, infrastructure services, identity, volumes, logs, shutdown and signals, capabilities, actions and shells, artifacts.
• docs/spec/runtime-windows-logs.md — the log store, 20 wlog[...] rules. Separate because Windows has no journald and the semantics are precise enough to be lost inside the runtime spec; the runtime spec cites one rule, so the log engine can be replaced without touching it.

Plans

• docs/plans/windows-runtime-containers.md — implementation approach (containerd versus hand-rolling the compute plane on the Compute* APIs), the base-less producer decision and the two alternatives it rules out, open questions Q1–Q4, spikes S1–S6, rollout, cost ledger.
• docs/plans/windows-log-store.md — the binary-v2 logging driver and why npipe and file each fail on daemon-independence or retention, the tree layout, numbered segments, the rotation split, and what is deferred.
• docs/plans/windows-threat-model.md — why the threat model is deferred until the spikes answer and a workload runs, and what it must cover when written.

Spikes

• docs/plans/windows-spike-containerd.md + spike-containerd — S1, the decider: does a container survive a full containerd restart. Drives the sequence via ctr/sc and checks workload liveness directly by PID, independent of containerd.
• docs/plans/windows-spike-host-filesystem.md + spike-host-fs — S6: whether a host ACL can name a container account's SID, and what a second process can do to a file a writer holds open. The container-free half runs as tests in the Windows CI job; three assert properties the design rests on, and they pass.

Infrastructure

• .github/workflows/rust.yml — Windows CI job, not in the required set since it builds throwaway harnesses.
• .config/tracey/config.styx — both Windows specs registered. Coverage is deliberately red: the specs describe an unbuilt runtime, so partial coverage is the accurate report and converges as implementation lands. The spikes crate is excluded from the impl globs so its mentions of rule ids do not read as coverage.

History

A process-native design (Job Objects, per-instance SCM services + virtual-account SIDs, loopback aliasing + WFP, a supervisor byte-relay, VHDX artifacts) was explored first and then removed as superseded — its analysis and spikes live in the history of the closed #106. What transferred: the Windows Server 2019+/x64 floor, the ConPTY empty-stderr caveat, and the habit of stating a weakened property plainly rather than eliding it.

Supersedes #105 and #106 (both closed).

🤖 Generated with Claude Code

https://claude.ai/code/session_01D5LfrU3ZM4FJ5fMF91wBKh

[github-code-quality]

Code Coverage Overview

Languages: TypeScript, Rust

TypeScript / code-coverage/vitest

The overall coverage in commit 02cab4f in the claude/seedling-oci-... branch remains at 66%, unchanged from commit 6f27fa0 in the main branch.

Rust / code-coverage/rust

The overall coverage in commit 02cab4f in the claude/seedling-oci-... branch remains at 58%, unchanged from commit 6f27fa0 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 6f27fa0	claude/seedling-oci-... 02cab4f	+/-
crates/core/src/oi/server.rs	60%	59%	-1%
crates/spikes/s...e_containerd.rs	0%	0%	0%
crates/spikes/s...pike_host_fs.rs	0%	0%	0%
crates/spikes/src/lib.rs	0%	0%	0%

---

_{Updated August 01, 2026 22:59 UTC}

[Copilot]

Pull request overview

Copilot reviewed 14 out of 15 changed files in this pull request and generated no new comments.

Suppressed comments (3)

crates/spikes/src/bin/spike_host_fs.rs:167

• ctr run --mount here uses Linux bind-propagation flags (options=rbind:rw). For Windows process-isolated containers those options aren’t supported, so the mount is likely to fail (breaking Q1’s container-side access experiments). Use a Windows-compatible mount option set (e.g. just rw) or omit options entirely.

        let mount = format!(
            "type=bind,src={},dst={},options=rbind:rw",
            dir.display(),
            GUEST_MOUNT
        );

crates/spikes/src/bin/spike_host_fs.rs:285

• try_external_ops renames the segment and then immediately tries to delete the renamed path. If the delete succeeds, the later check that reads renamed to see whether appends followed the rename becomes impossible and can produce a misleading “did not follow” conclusion. Don’t delete the renamed file before the append-following check; handle delete as a separate sub-experiment if needed.

    fn try_external_ops(path: &Path, renamed: &Path) -> (bool, bool) {
        let rename_ok = fs::rename(path, renamed).is_ok();
        // Delete whichever name currently exists.
        let target = if rename_ok { renamed } else { path };
        let delete_ok = fs::remove_file(target).is_ok();
        (rename_ok, delete_ok)

crates/spikes/src/bin/spike_containerd.rs:131

• The harness step numbering doesn’t match the plan it claims to mirror: the plan’s experiment 2 includes recording the PID/shim, but the harness prints that as step 3, shifting subsequent headings by +1 (plan 3→harness 4, etc.). This makes it harder to paste harness output back into docs/plans/windows-spike-containerd.md verbatim. Consider folding the PID/shim recording under step 2 and renumbering later steps to match the plan.

        step(2, "Start a long-lived process-isolated container");
        cleanup();
        let (pull_ok, pull) = sh("ctr", &["image", "pull", &image])?;
        if !pull_ok {
            observe(pull);
            observe(
                "pull failed; a base matching the host build must be available (wcr[base.image])",
            );
            return Ok(());
        }
        let (run_ok, run_out) = sh(
            "ctr",
            &["run", "-d", &image, CONTAINER_ID, "ping", "-t", "127.0.0.1"],
        )?;
        observe(run_out);
        if !run_ok {
            observe("container failed to start; check the base tag matches the host build");
            return Ok(());
        }

        step(3, "Record the workload PID and its shim");
        let (_, tasks) = sh("ctr", &["task", "ls"])?;
        observe(&tasks);

[Copilot]

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated no new comments.

Suppressed comments (2)

crates/spikes/src/bin/spike_containerd.rs:151

• After sc stop containerd, the harness immediately declares containerd "down" and checks the workload PID. sc stop can return while the service is still STOP_PENDING, so this can produce a false PASS without ever observing a full daemon stop/restart. Poll until the service is actually STOPPED (and confirm ctr cannot connect) before evaluating the survival property.

        let (_, stop) = sh("sc", &["stop", SERVICE])?;
        observe(stop);
        observe(
            "containerd is down; ctr can no longer reach it, but the container must keep running",
        );

crates/spikes/src/bin/spike_host_fs.rs:167

• ctr --mount uses options=rbind:rw, but rbind is a Linux-specific recursive bind option and is not supported for Windows containers. This can make the container-side ACL experiments fail for reasons unrelated to the ACL (mount parse failure / unsupported option). Use a plain read-write bind mount option instead.

        let mount = format!(
            "type=bind,src={},dst={},options=rbind:rw",
            dir.display(),
            GUEST_MOUNT
        );

[Copilot]

Pull request overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated no new comments.

Suppressed comments (3)

crates/spikes/src/bin/spike_host_fs.rs:215

• In the Q1 negative-control setup, the icacls result is also ignored. If that command fails, the “CONTROL FAILED” outcome can be a false positive (directory never actually confined), and the spike won’t surface the real root cause. Check the exit status and fail early on non-zero.

        let (_, out) = sh(
            "icacls",
            &[
                &path,
                "/inheritance:r",

crates/spikes/src/bin/spike_host_fs.rs:152

• q1_apply ignores the icacls exit status for both the DACL write and the readback. If icacls fails (non-elevated run, bad args, etc), the spike can proceed and interpret default/inherited ACLs as evidence, which makes experiment 3+ results unreliable. Capture and check the success flag, and fail the step if it’s false.

This issue also appears on line 211 of the same file.

        let (_, out) = sh(
            "icacls",
            &[
                &path,
                "/inheritance:r",

crates/spikes/src/bin/spike_host_fs.rs:346

• try_external_ops attempts rename and then delete. When both succeed, fs::read_to_string(&renamed) will fail and followed becomes false, which is then interpreted as “appends did not follow the rename”. That’s a false conclusion because the file may simply have been unlinked. Avoid inferring “not followed” in the delete-ok case.

        if rename_ok {
            let followed = fs::read_to_string(&renamed)
                .map(|s| s.contains("\"seq\":2"))
                .unwrap_or(false);
            record("appends followed the file to its new name", followed);

[passcod]

Carrying over the "What Windows inherits" section from the restart-accounting plan, which #134 implements and deletes. Nothing in-tree would otherwise hold this, and it is guidance for this PR rather than that one.

Restart accounting landed in #134: seedling records every container restart per instance with its exit status and a cause of recovery or deliberate, and files crash_loop when the recovery rate reaches an operator-settable threshold within a window. systemd's start limit is demoted to a secondary trigger.

The spec rules are deliberately platform-neutral, so this runtime inherits them:

• r[autonomous.restart.record] — record every restart, its exit status where the platform reports one, and its cause.
• r[autonomous.restart.rate] — crash_loop is a function of the recorded recovery-restart rate.
• r[autonomous.restart.rate.settings] — the threshold and window are operator-settable.
• r[gc.restarts] — records bounded per instance (default 50), dropped with their instance.
• r[autonomous.restart.backoff] — now scoped to "where the platform's supervisor actions restarts", so it does not bind here.

What changes for wcr[shim.ownership]

It drops its restart clause. The reconciler owns restart, pacing, and the start limit, and records each attempt at the point it actions one — no counter inference needed, which is the awkward part of the Linux implementation and the part this runtime gets to skip.

Two Windows-specific requirements come with it:

• The exit observation must be folded into history before the exited task is reaped. containerd requires deletion before the container ID is reusable, so the exit status is gone once the task is deleted — it has to be read and recorded first, or the records are a tally with no diagnostic value.
• The daemon-down gap should be stated as a property rather than left to be discovered. A workload that crashes while seedlingd is down stays down until it returns, bounded by SCM restart. On Linux systemd covers that gap; here nothing does.

One thing to be careful of

cause is recovery | deliberate — why the restart happened, not who performed it. That distinction exists because of this runtime: an earlier revision of #134 had initiator: supervisor | runtime, which works on Linux only because systemd happens to action recovery there. Here seedlingd actions both kinds, so an actor-shaped field would mark every restart runtime, leave the rate counting nothing, and kill the primary crash-loop trigger — with no failed/start-limit-hit equivalent to fall back on.

So when this runtime records a restart, the question to answer is whether the workload exited unexpectedly (recovery) or whether seedlingd restarted it on purpose (deliberate), regardless of the fact that seedlingd performed both.

---

Generated by Claude Code

[Copilot]

Pull request overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

crates/spikes/src/bin/spike_host_fs.rs:335

• This "name reusable" probe uses open_writer() which sets create(true) and can succeed by opening an existing file, so it doesn’t actually prove the original name is free for a new file. That can mis-record reuse semantics and make the spike’s conclusion unreliable.

        let name_reusable = open_writer(&seg, FILE_SHARE_READ | FILE_SHARE_WRITE).is_ok();
        record(
            "original name reusable while the handle is open",
            name_reusable,
        );

crates/spikes/src/bin/spike_host_fs.rs:346

• When try_external_ops succeeds in both renaming and deleting, renamed no longer exists, but the code still runs read_to_string(&renamed) and records followed = false. That mixes up “writer didn’t follow rename” with “file was deleted”, so the recorded observation is ambiguous.

        if rename_ok {
            let followed = fs::read_to_string(&renamed)
                .map(|s| s.contains("\"seq\":2"))
                .unwrap_or(false);
            record("appends followed the file to its new name", followed);

[Copilot]

Pull request overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated no new comments.

Suppressed comments (1)

crates/spikes/src/bin/spike_host_fs.rs:346

• The Q2 “original name reusable while the handle is open” probe is currently misleading: open_writer() uses create(true) so it can succeed even when neither rename nor delete worked (the name was never freed). Also, if both rename and delete succeed, the subsequent read_to_string(renamed) will fail and incorrectly report that appends didn’t follow the rename.

        let name_reusable = open_writer(&seg, FILE_SHARE_READ | FILE_SHARE_WRITE).is_ok();
        record(
            "original name reusable while the handle is open",
            name_reusable,
        );

[Copilot]

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated no new comments.

Suppressed comments (2)

crates/spikes/src/bin/spike_host_fs.rs:167

• The mount spec uses options=rbind:rw, but rbind is a Linux-only recursive bind option and is not meaningful/supported for Windows container mounts. This can cause ctr run to fail on Windows, preventing the Q1 container-side access checks from running.

        let mount = format!(
            "type=bind,src={},dst={},options=rbind:rw",
            dir.display(),
            GUEST_MOUNT
        );

crates/spikes/src/bin/spike_host_fs.rs:145

• In q1_apply, the icacls call’s success flag is discarded. If icacls fails (not elevated, missing feature, etc.), the harness can incorrectly proceed and potentially treat an error message as a persisted ACE, producing misleading spike results. Capture the ok boolean and fail fast when it’s false (same for the subsequent icacls read-back).

        let (_, out) = sh(
            "icacls",
            &[
                &path,
                "/inheritance:r",