From 2c07b0cb39bf86108ffc67fc45f5b2a273616331 Mon Sep 17 00:00:00 2001
From: Adam Hall <adam.hall.1992@live.com>
Date: Tue, 30 Jun 2026 17:16:41 +0930
Subject: [PATCH 1/6] feat(install): add chroot-aware Runner + mount/finalize
 stages (Phase A round 1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Foundation for migrating Phase B customization into the Phase A chroot so
first boot lands on an already-set-up system.

- run.Runner: ChrootRoot/AsUser target — when set, Cmd/Root/Shell/RootShell
  transparently wrap in arch-chroot (Root as root, Cmd as the user via
  `sudo -iu <user> --`). Host path stays byte-identical. Adds chroot-safe
  Has/PathExists probes for Round 2 to replace host LookPath/Stat.
- archinstall postInstall now leaves the target mounted; extracted
  ensureTargetMounted (idempotent)/unmountTarget/isMounted.
- New Install-phase stages bracket the chroot: mount(20) opens it and points
  the Runner at /mnt; finalize(99) stages the Phase B binary+config and
  unmounts. Phase A: preflight(0) archinstall(10) mount(20) finalize(99).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 internal/run/run.go            | 149 ++++++++++++++++++++++++++-------
 internal/run/run_test.go       |  63 ++++++++++++++
 internal/stages/archinstall.go | 101 +++++++++++++++-------
 internal/stages/finalize.go    |  37 ++++++++
 internal/stages/mount.go       |  36 ++++++++
 internal/stages/stages_test.go |  29 ++++++-
 6 files changed, 348 insertions(+), 67 deletions(-)
 create mode 100644 internal/stages/finalize.go
 create mode 100644 internal/stages/mount.go

diff --git a/internal/run/run.go b/internal/run/run.go
index fb63d4e..52466bb 100644
--- a/internal/run/run.go
+++ b/internal/run/run.go
@@ -18,6 +18,15 @@ type Runner struct {
 	DryRun bool // print/record commands instead of executing them
 	Sudo   bool // prefix privileged commands with sudo (Phase B as user); false in Phase A (already root)
 
+	// ChrootRoot, when set, routes every command through `arch-chroot <ChrootRoot>`
+	// so a stage's existing Cmd/Root/Shell calls execute inside the installed target
+	// (Phase A customization). AsUser, when set alongside it, runs *unprivileged*
+	// commands (Cmd/Shell) as that user inside the target via `sudo -iu` — root→user
+	// needs no password and -i supplies the user's login env. Both are empty in the
+	// normal (host) execution path, where behaviour is byte-identical to before.
+	ChrootRoot string
+	AsUser     string
+
 	// Env, when non-empty, is layered (key=value) on top of the inherited process
 	// environment for every executed command. Dir, when set, is the working dir.
 	Env map[string]string
@@ -46,8 +55,17 @@ func (r *Runner) prepare(cmd *exec.Cmd) {
 
 // Cmd runs a program with args, streaming its output (we deliberately do not
 // hide it behind a spinner so installer progress and errors stay visible). In
-// dry-run it only logs and records.
+// dry-run it only logs and records. With a chroot target set it runs inside the
+// target (as AsUser when set) — see chrootWrap.
 func (r *Runner) Cmd(name string, args ...string) error {
+	name, args = r.chrootWrap(false, name, args)
+	return r.exec(name, args)
+}
+
+// exec records and runs a fully-resolved command — no privilege or chroot wrapping
+// is applied here. It is the shared tail of Cmd/Root/Chroot once that wrapping has
+// been decided, so the recorded `.Plan` line is exactly what executes.
+func (r *Runner) exec(name string, args []string) error {
 	line := strings.TrimSpace(name + " " + strings.Join(args, " "))
 	r.record(line)
 	ui.Step("%s", line)
@@ -63,32 +81,77 @@ func (r *Runner) Cmd(name string, args ...string) error {
 	return nil
 }
 
-// Root runs a command with root privileges: directly when already root (Phase A,
-// live ISO) or via sudo otherwise (Phase B, as the user).
+// chrootWrap prefixes a command with `arch-chroot <ChrootRoot>` when a chroot
+// target is set. For an unprivileged command (priv=false) with AsUser set it also
+// runs as that user inside the target via `sudo -iu <user> --` (root→user needs no
+// password; -i gives the login env). With no chroot target it returns name/args
+// unchanged — Phase A is already root, so no live-ISO sudo is added here (Root
+// handles the host sudo path separately).
+func (r *Runner) chrootWrap(priv bool, name string, args []string) (string, []string) {
+	if r.ChrootRoot == "" {
+		return name, args
+	}
+	pre := []string{r.ChrootRoot}
+	if !priv && r.AsUser != "" {
+		pre = append(pre, "sudo", "-iu", r.AsUser, "--")
+	}
+	pre = append(pre, name)
+	return "arch-chroot", append(pre, args...)
+}
+
+// Root runs a command with root privileges: inside the chroot target via
+// arch-chroot when one is set (Phase A customization, already root), via sudo when
+// running as the user (Phase B), or directly when already root with no chroot.
 func (r *Runner) Root(name string, args ...string) error {
+	if r.ChrootRoot != "" {
+		name, args = r.chrootWrap(true, name, args)
+		return r.exec(name, args)
+	}
 	if r.Sudo {
-		return r.Cmd("sudo", append([]string{name}, args...)...)
+		return r.exec("sudo", append([]string{name}, args...))
 	}
-	return r.Cmd(name, args...)
+	return r.exec(name, args)
 }
 
-// RootShell runs a shell script with root privileges through `bash -c`: via
-// `sudo bash -c <script>` when not already root (Phase B, as the user) or
-// directly when already root (Phase A, live ISO). This lets a shell pipeline
-// run wholly as root without inner per-command `sudo`. It records/prints the
-// same `sh: <script>` line as Shell so the recorded .Plan stays uniform.
+// RootShell runs a shell script with root privileges through `bash -c`. See shell:
+// it records the plain `sh: <script>` line in the un-chrooted path (uniform with
+// Shell) and the full wrapped command when running in a chroot target.
 func (r *Runner) RootShell(script string) error {
-	r.record("sh: " + script)
-	ui.Step("sh: %s", script)
+	return r.shell(true, script)
+}
+
+// shell is the shared body of Shell (unprivileged) and RootShell (privileged): it
+// resolves the bash invocation — wrapped in arch-chroot (and `sudo -iu <user>` for
+// an unprivileged shell) when a chroot target is set, via sudo when privileged and
+// running as the user, or a bare `bash -c` otherwise — then records and runs it.
+func (r *Runner) shell(priv bool, script string) error {
+	var name string
+	var args []string
+	switch {
+	case r.ChrootRoot != "":
+		a := []string{r.ChrootRoot}
+		if !priv && r.AsUser != "" {
+			a = append(a, "sudo", "-iu", r.AsUser)
+		}
+		name, args = "arch-chroot", append(a, "bash", "-c", script)
+	case priv && r.Sudo:
+		name, args = "sudo", []string{"bash", "-c", script}
+	default:
+		name, args = "bash", []string{"-c", script}
+	}
+	// Record the plain `sh: <script>` line on the host path (keeps existing plans
+	// stable); record the full command when chrooted so the plan shows the
+	// arch-chroot/user prefix that actually runs.
+	rec := "sh: " + script
+	if r.ChrootRoot != "" {
+		rec = "sh: " + strings.TrimSpace(name+" "+strings.Join(args, " "))
+	}
+	r.record(rec)
+	ui.Step("%s", rec)
 	if r.DryRun {
 		return nil
 	}
-	var cmd *exec.Cmd
-	if r.Sudo {
-		cmd = exec.Command("sudo", "bash", "-c", script)
-	} else {
-		cmd = exec.Command("bash", "-c", script)
-	}
+	cmd := exec.Command(name, args...)
 	cmd.Stdout, cmd.Stderr, cmd.Stdin = os.Stdout, os.Stderr, os.Stdin
 	r.prepare(cmd)
 	if err := cmd.Run(); err != nil {
@@ -113,21 +176,43 @@ func (r *Runner) TryRoot(name string, args ...string) {
 // Shell runs a string through `bash -c`, for pipes/redirects/conditionals
 // (genfstab, idempotent sed edits, gpg key import). Prefer Cmd where possible.
 func (r *Runner) Shell(script string) error {
-	r.record("sh: " + script)
-	ui.Step("sh: %s", script)
-	if r.DryRun {
-		return nil
-	}
-	cmd := exec.Command("bash", "-c", script)
-	cmd.Stdout, cmd.Stderr, cmd.Stdin = os.Stdout, os.Stderr, os.Stdin
-	r.prepare(cmd)
-	if err := cmd.Run(); err != nil {
-		return fmt.Errorf("shell: %w", err)
-	}
-	return nil
+	return r.shell(false, script)
 }
 
-// Chroot runs a command inside arch-chroot at root (Phase A live ISO).
+// Chroot runs a command inside arch-chroot at root (Phase A live ISO). It is the
+// explicit-chroot primitive, so it bypasses the ChrootRoot wrapping to avoid
+// double-wrapping when a chroot target happens to be set.
 func (r *Runner) Chroot(root string, args ...string) error {
-	return r.Cmd("arch-chroot", append([]string{root}, args...)...)
+	return r.exec("arch-chroot", append([]string{root}, args...))
+}
+
+// Has reports whether bin is available on PATH in the active execution context —
+// inside the chroot target when set, else on the host. Read-only: it is not
+// recorded in the plan. Under dry-run with a chroot target there is nothing
+// mounted to probe, so it returns false (which makes a stage plan the install
+// branch).
+func (r *Runner) Has(bin string) bool {
+	if r.ChrootRoot != "" {
+		if r.DryRun {
+			return false
+		}
+		return exec.Command("arch-chroot", r.ChrootRoot, "sh", "-c", "command -v "+bin+" >/dev/null 2>&1").Run() == nil
+	}
+	_, err := exec.LookPath(bin)
+	return err == nil
+}
+
+// PathExists reports whether path exists in the active execution context — inside
+// the chroot target when set, else on the host. Read-only: not recorded. Under
+// dry-run with a chroot target it returns false so a stage plans the create/clone
+// branch.
+func (r *Runner) PathExists(path string) bool {
+	if r.ChrootRoot != "" {
+		if r.DryRun {
+			return false
+		}
+		return exec.Command("arch-chroot", r.ChrootRoot, "test", "-e", path).Run() == nil
+	}
+	_, err := os.Stat(path)
+	return err == nil
 }
diff --git a/internal/run/run_test.go b/internal/run/run_test.go
index 4934c6f..62f941b 100644
--- a/internal/run/run_test.go
+++ b/internal/run/run_test.go
@@ -109,3 +109,66 @@ func TestChroot_RecordsArchChrootPrefix(t *testing.T) {
 		t.Errorf("Plan = %v, want %v", r.Plan, want)
 	}
 }
+
+// These tests pin the chroot-target seam the Phase A customization stages rely on:
+// with ChrootRoot set, a stage's existing Cmd/Root/Shell/RootShell calls must be
+// transparently wrapped in arch-chroot — privileged ones as root, unprivileged
+// ones as AsUser via `sudo -iu` — without the stage code changing.
+
+func TestCmd_ChrootAsUserWrapsSudoLogin(t *testing.T) {
+	r := &Runner{DryRun: true, ChrootRoot: "/mnt", AsUser: "adam"}
+	if err := r.Cmd("flatpak", "--user", "install", "-y", "flathub", "org.x"); err != nil {
+		t.Fatalf("dry-run Cmd should not error: %v", err)
+	}
+	want := []string{"arch-chroot /mnt sudo -iu adam -- flatpak --user install -y flathub org.x"}
+	if !reflect.DeepEqual(r.Plan, want) {
+		t.Errorf("Plan = %v, want %v", r.Plan, want)
+	}
+}
+
+func TestRoot_ChrootRunsAsRootNoSudo(t *testing.T) {
+	// Privileged commands run as root inside the chroot — no `sudo -iu`, no live-ISO
+	// sudo (Phase A is already root).
+	r := &Runner{DryRun: true, ChrootRoot: "/mnt", AsUser: "adam"}
+	if err := r.Root("pacman", "-S", "--needed", "--noconfirm", "kwrite"); err != nil {
+		t.Fatalf("dry-run Root should not error: %v", err)
+	}
+	want := []string{"arch-chroot /mnt pacman -S --needed --noconfirm kwrite"}
+	if !reflect.DeepEqual(r.Plan, want) {
+		t.Errorf("Plan = %v, want %v", r.Plan, want)
+	}
+}
+
+func TestShell_ChrootAsUserRecordsWrappedCommand(t *testing.T) {
+	r := &Runner{DryRun: true, ChrootRoot: "/mnt", AsUser: "adam"}
+	if err := r.Shell("curl -fsSL https://x | sh"); err != nil {
+		t.Fatalf("dry-run Shell should not error: %v", err)
+	}
+	want := []string{"sh: arch-chroot /mnt sudo -iu adam bash -c curl -fsSL https://x | sh"}
+	if !reflect.DeepEqual(r.Plan, want) {
+		t.Errorf("Plan = %v, want %v", r.Plan, want)
+	}
+}
+
+func TestRootShell_ChrootRunsAsRoot(t *testing.T) {
+	r := &Runner{DryRun: true, ChrootRoot: "/mnt", AsUser: "adam"}
+	if err := r.RootShell("grub-mkconfig -o /boot/grub/grub.cfg"); err != nil {
+		t.Fatalf("dry-run RootShell should not error: %v", err)
+	}
+	want := []string{"sh: arch-chroot /mnt bash -c grub-mkconfig -o /boot/grub/grub.cfg"}
+	if !reflect.DeepEqual(r.Plan, want) {
+		t.Errorf("Plan = %v, want %v", r.Plan, want)
+	}
+}
+
+func TestHasAndPathExists_DryRunChrootReturnFalse(t *testing.T) {
+	// Under dry-run with a chroot target there is nothing mounted to probe, so the
+	// probes return false (a stage then plans the install/clone branch).
+	r := &Runner{DryRun: true, ChrootRoot: "/mnt"}
+	if r.Has("definitely-not-a-real-binary") {
+		t.Error("Has should be false for a chroot probe under dry-run")
+	}
+	if r.PathExists("/nope/does/not/exist") {
+		t.Error("PathExists should be false for a chroot probe under dry-run")
+	}
+}
diff --git a/internal/stages/archinstall.go b/internal/stages/archinstall.go
index ad37e0d..695a907 100644
--- a/internal/stages/archinstall.go
+++ b/internal/stages/archinstall.go
@@ -94,7 +94,7 @@ func (archinstallStage) Run(ctx *Context) error {
 		return err
 	}
 
-	ui.OK("archinstall complete; Phase B staged in /home/%s", ctx.Cfg.User.Name)
+	ui.OK("archinstall complete; target mounted for Phase A customization")
 	return nil
 }
 
@@ -119,41 +119,16 @@ func postInstall(ctx *Context) error {
 	// This keeps the encrypted path coherent and loud rather than silently wrong.
 	if ctx.Cfg.Disks.Encryption != nil {
 		ui.Warn("encrypted install: custom repos, kernels, locale extras, and swapfile are NOT applied yet (LUKS remount not implemented)")
-		ui.Warn("encrypted install: Phase B binary/config staging is SKIPPED — after first boot, copy the archwright binary + config.yaml into your home and run bootstrap manually")
 		return nil
 	}
 
-	rootDev, err := rootDevice(ctx.Cfg)
-	if err != nil {
-		return err
-	}
-	esp := archinstall.PartDev(ctx.Cfg.Disks.ESP.Device, 1)
-
 	// Remount the target for the chroot work. archinstall unmounts on finish, so we
-	// rebuild the mount tree exactly as the installed system sees it.
-	//
-	// For btrfs the system lives INSIDE the root subvolume (e.g. @), not the
-	// top-level subvolume: archinstall installs into @ and mounts it at /. Mounting
-	// the bare partition would expose only the (empty) top-level subvol — /boot and
-	// /home/<user> would be missing and staging would fail — so we must mount the
-	// root subvolume with subvol=<name>, and mount any non-root subvolumes
-	// (e.g. @home at /home) so staged files land in the right subvolume.
-	mounts, err := targetMounts(ctx.Cfg, rootDev, esp)
-	if err != nil {
+	// rebuild the mount tree exactly as the installed system sees it, and leave it
+	// mounted: the `mount` stage points the Runner at this chroot for the Phase A
+	// customization stages, and `finalize` stages the binary + unmounts.
+	if err := ensureTargetMounted(ctx); err != nil {
 		return err
 	}
-	// Checked mounts (Issue #2): a failed remount must abort, not silently run the
-	// chroot steps against an empty /mnt. (The umounts below stay best-effort.)
-	for _, m := range mounts {
-		var args []string
-		if len(m.opts) > 0 {
-			args = append(args, "-o", strings.Join(m.opts, ","))
-		}
-		args = append(args, m.dev, m.target)
-		if err := ctx.R.Root("mount", args...); err != nil {
-			return err
-		}
-	}
 
 	if err := setupSwapfile(ctx); err != nil {
 		return err
@@ -190,17 +165,79 @@ func postInstall(ctx *Context) error {
 			return err
 		}
 	}
-	if err := stageBinary(ctx); err != nil {
+	// The target is left mounted on purpose: the `mount` stage opens the chroot for
+	// the Phase A customization stages and `finalize` stages the binary + unmounts.
+	return nil
+}
+
+// ensureTargetMounted rebuilds the installed system's mount tree at /mnt for the
+// chroot post-install + customization work, idempotently. archinstall unmounts the
+// target on finish, so the mounts are recreated exactly as the booted system sees
+// them: root at /mnt, ESP at /mnt/boot, plus any separate subvolume/LV mounts (a
+// separate /home etc.) so staged files aren't shadowed once those mount at boot.
+//
+// For btrfs the system lives INSIDE the root subvolume (e.g. @): mounting the bare
+// partition would expose only the empty top-level subvol, so the root subvolume is
+// mounted with subvol=<name>. When /mnt is already a mountpoint (the normal flow,
+// where the archinstall stage mounted it) this is a no-op, so the `mount` stage and
+// a resumed `--from mount` run can call it safely.
+func ensureTargetMounted(ctx *Context) error {
+	if isMounted(ctx, "/mnt") {
+		return nil
+	}
+	rootDev, err := rootDevice(ctx.Cfg)
+	if err != nil {
 		return err
 	}
+	esp := archinstall.PartDev(ctx.Cfg.Disks.ESP.Device, 1)
+	mounts, err := targetMounts(ctx.Cfg, rootDev, esp)
+	if err != nil {
+		return err
+	}
+	// Checked mounts (Issue #2): a failed remount must abort, not silently run the
+	// chroot steps against an empty /mnt.
+	for _, m := range mounts {
+		var args []string
+		if len(m.opts) > 0 {
+			args = append(args, "-o", strings.Join(m.opts, ","))
+		}
+		args = append(args, m.dev, m.target)
+		if err := ctx.R.Root("mount", args...); err != nil {
+			return err
+		}
+	}
+	return nil
+}
 
-	// Unmount in reverse so nested subvolume/ESP mounts come off before /mnt.
+// unmountTarget unmounts the /mnt tree in reverse (deepest mount first) so nested
+// subvolume/ESP mounts come off before /mnt. Best-effort, mirroring the original
+// post-install teardown.
+func unmountTarget(ctx *Context) error {
+	rootDev, err := rootDevice(ctx.Cfg)
+	if err != nil {
+		return err
+	}
+	esp := archinstall.PartDev(ctx.Cfg.Disks.ESP.Device, 1)
+	mounts, err := targetMounts(ctx.Cfg, rootDev, esp)
+	if err != nil {
+		return err
+	}
 	for i := len(mounts) - 1; i >= 0; i-- {
 		ctx.R.Try("umount", mounts[i].target)
 	}
 	return nil
 }
 
+// isMounted reports whether target is currently a mountpoint. Read-only and not
+// recorded. Under dry-run it returns false so the plan still shows the mount
+// commands (nothing is actually mounted during a dry-run).
+func isMounted(ctx *Context, target string) bool {
+	if ctx.R.DryRun {
+		return false
+	}
+	return exec.Command("mountpoint", "-q", target).Run() == nil
+}
+
 // mount is one entry in the target mount tree rebuilt for post-install chroot
 // work: a device mounted at an absolute /mnt path with optional mount options.
 type mount struct {
diff --git a/internal/stages/finalize.go b/internal/stages/finalize.go
new file mode 100644
index 0000000..e538f8e
--- /dev/null
+++ b/internal/stages/finalize.go
@@ -0,0 +1,37 @@
+package stages
+
+import "github.com/AdamJHall/archwright/internal/ui"
+
+// finalizeStage closes out Phase A: it stages the archwright binary + config into
+// the new user's home (so Phase B is available after reboot) and unmounts the
+// target. It runs last (Order 99) so every Phase A customization stage has already
+// completed inside the chroot. Staging copies into /mnt/home/<user> from the live
+// ISO — not inside the chroot — so it clears the Runner's chroot target first.
+type finalizeStage struct{}
+
+func init() { register(finalizeStage{}) }
+
+func (finalizeStage) Order() int   { return 99 }
+func (finalizeStage) Name() string { return "finalize" }
+func (finalizeStage) Phase() Phase { return Install }
+
+func (finalizeStage) Run(ctx *Context) error {
+	// Encrypted installs never opened the chroot (see the mount stage), so there is
+	// nothing mounted to stage into or unmount; warn that Phase B must be set up by
+	// hand, matching the long-standing encrypted-path behaviour.
+	if ctx.Cfg.Disks.Encryption != nil {
+		ui.Warn("encrypted install: Phase B binary/config staging is SKIPPED — after first boot, copy the archwright binary + config.yaml into your home and run bootstrap manually")
+		return nil
+	}
+	// Leave the chroot: the binary/config copies operate on /mnt from the live ISO.
+	ctx.R.ChrootRoot = ""
+	ctx.R.AsUser = ""
+	if err := stageBinary(ctx); err != nil {
+		return err
+	}
+	if err := unmountTarget(ctx); err != nil {
+		return err
+	}
+	ui.OK("Phase B staged in /home/%s", ctx.Cfg.User.Name)
+	return nil
+}
diff --git a/internal/stages/mount.go b/internal/stages/mount.go
new file mode 100644
index 0000000..0fc46ec
--- /dev/null
+++ b/internal/stages/mount.go
@@ -0,0 +1,36 @@
+package stages
+
+import "github.com/AdamJHall/archwright/internal/ui"
+
+// mountStage is the Phase A boundary that opens the chroot for the customization
+// stages that follow it (packages, theming, dotfiles, …). The archinstall stage
+// leaves the freshly installed system mounted at /mnt; this stage idempotently
+// ensures that mount tree exists — so a resumed `--from mount` run re-establishes
+// it — and then points the Runner at the chroot. From here on, a stage's
+// privileged commands run as root via arch-chroot and its unprivileged commands
+// run as the configured user inside the target, with no change to the stage code
+// itself. The matching `finalize` stage tears the chroot down again.
+type mountStage struct{}
+
+func init() { register(mountStage{}) }
+
+func (mountStage) Order() int   { return 20 }
+func (mountStage) Name() string { return "mount" }
+func (mountStage) Phase() Phase { return Install }
+
+func (mountStage) Run(ctx *Context) error {
+	// Encrypted layouts are not supported for chroot customization yet (the LUKS
+	// remount is unimplemented). Leave the Runner un-chrooted so nothing downstream
+	// runs against an unmapped device — mirrors the archinstall stage's guard.
+	if ctx.Cfg.Disks.Encryption != nil {
+		ui.Warn("encrypted install: chroot customization is not supported yet — skipping mount")
+		return nil
+	}
+	if err := ensureTargetMounted(ctx); err != nil {
+		return err
+	}
+	ctx.R.ChrootRoot = "/mnt"
+	ctx.R.AsUser = ctx.Cfg.User.Name
+	ui.OK("target mounted; Phase A customization will run in the chroot")
+	return nil
+}
diff --git a/internal/stages/stages_test.go b/internal/stages/stages_test.go
index eda2175..7b1f3d2 100644
--- a/internal/stages/stages_test.go
+++ b/internal/stages/stages_test.go
@@ -144,8 +144,8 @@ func TestRegistry(t *testing.T) {
 		}
 	}
 	check(Install,
-		[]string{"preflight", "archinstall"},
-		[]int{0, 10})
+		[]string{"preflight", "archinstall", "mount", "finalize"},
+		[]int{0, 10, 20, 99})
 	check(Bootstrap,
 		[]string{"yay", "packages", "snapper", "flatpak", "aur", "grub-theme", "kde", "dotfiles", "setup", "services"},
 		[]int{10, 20, 25, 30, 40, 60, 70, 80, 85, 90})
@@ -179,9 +179,32 @@ func TestPlan_Archinstall(t *testing.T) {
 		"arch-chroot /mnt pacman -Rns --noconfirm linux",
 		`GRUB_TOP_LEVEL="/boot/vmlinuz-linux-cachyos"`,
 		"arch-chroot /mnt grub-mkconfig -o /boot/grub/grub.cfg",
-		// stages the binary + config into the new user's home for Phase B
+	)
+	// Staging the binary + config and unmounting now belong to the finalize stage,
+	// so the archinstall stage's own plan must no longer carry them.
+	mustNotContain(t, plan,
+		"/mnt/home/adam/archwright",
+		"umount /mnt",
+	)
+}
+
+// TestPlan_Mount asserts the mount stage rebuilds the target tree (idempotent under
+// a real run, planned under dry-run) before the customization stages chroot into it.
+func TestPlan_Mount(t *testing.T) {
+	mustContain(t, planFor(t, Install, "mount"),
+		"mount /dev/vg0/root /mnt",
+		"mount /dev/nvme0n1p1 /mnt/boot",
+	)
+}
+
+// TestPlan_Finalize asserts the finalize stage stages the Phase B binary + config
+// into the new user's home and unmounts the target.
+func TestPlan_Finalize(t *testing.T) {
+	mustContain(t, planFor(t, Install, "finalize"),
 		"/mnt/home/adam/archwright",
 		"arch-chroot /mnt chown -R adam:adam /home/adam",
+		"cp /tmp/config.yaml /mnt/home/adam/config.yaml",
+		"umount /mnt",
 	)
 }
 

From 4f39860f884d3408b90ac3f30214444abb675846 Mon Sep 17 00:00:00 2001
From: Adam Hall <adam.hall.1992@live.com>
Date: Tue, 30 Jun 2026 17:32:34 +0930
Subject: [PATCH 2/6] feat(install): run customization in the Phase A chroot
 (round 2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Re-home the Tier 1/2 customization stages from Phase B into Phase A so first
boot is an already-set-up desktop. Each stage flips Phase()->Install with a new
Order between mount(20) and finalize(99); the chroot-aware Runner routes their
existing commands through arch-chroot (root, or the user via sudo -iu).

- packages(30), flatpak(40), grub-theme(50), kde(60), dotfiles(70), setup(80),
  services(90) now run in the chroot. Phase B keeps yay(10), snapper(25),
  aur(40) — aur stays post-boot (makepkg can't run as root).
- ensureTool/dotfiles/setup swap host probes (LookPath/os.Stat/UserHomeDir) for
  the chroot-safe Runner.Has/PathExists and the configured user's /home/<user>.
- grub-theme installs via cloneBuildRoot (root, no inner sudo) since the chroot
  is already root — removes the user->root escalation that needed a password.
- Stage-anchored hooks (e.g. after:packages GPU drivers) now fire in the chroot
  because the stages are real Phase A stages the run loop brackets.
- Tests assert the arch-chroot-wrapped plans via a chroot helper; registry,
  selection, and from/to windows updated to the new topology. README stage
  table + phase docs updated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 README.md                                   | 46 +++++++-------
 internal/stages/dotfiles.go                 | 32 +++++-----
 internal/stages/dotfiles_test.go            | 49 ++++++---------
 internal/stages/flatpak.go                  | 10 +--
 internal/stages/flatpak_test.go             | 34 +++++------
 internal/stages/fromto_test.go              | 43 ++++++-------
 internal/stages/grubtheme.go                | 17 +++---
 internal/stages/grubtheme_screen_bg_test.go | 21 ++++---
 internal/stages/helpers.go                  | 37 +++++++----
 internal/stages/kde.go                      |  4 +-
 internal/stages/kde_lookandfeel_test.go     |  6 +-
 internal/stages/packages.go                 |  9 +--
 internal/stages/selection_test.go           | 20 +++---
 internal/stages/selectors_test.go           | 42 ++++++++++---
 internal/stages/services.go                 | 18 +++---
 internal/stages/services_test.go            | 23 +++----
 internal/stages/setup.go                    | 49 +++++++++------
 internal/stages/stages_test.go              | 68 +++++++++++++--------
 18 files changed, 296 insertions(+), 232 deletions(-)

diff --git a/README.md b/README.md
index eaa9184..e2be698 100644
--- a/README.md
+++ b/README.md
@@ -20,11 +20,13 @@ dry-run-aware stages:
 
 - **`install` (Phase A)** — on the live ISO, as **root**. Renders your `config.yaml` into an
   archinstall config and lets the official installer do partitioning, LVM/btrfs, pacstrap and
-  the bootloader. Then, in the post-install chroot, it sets up custom repos and kernels (so the
-  *first* boot already uses them) and stages the binary + flattened config for Phase B.
-- **`bootstrap` (Phase B)** — on the booted system, as **your user**. Post-install
-  customization: the AUR helper, packages, flatpaks, snapshots, boot splash, GRUB/KDE theming,
-  dotfiles, and a final user-defined `setup` step.
+  the bootloader. Then, in the post-install chroot, it sets up custom repos and kernels and runs
+  the bulk of customization — packages, flatpaks, GRUB/KDE theming, dotfiles and the `setup`
+  steps (user-space steps run as your user via `sudo -iu`) — so your **first boot is already a
+  set-up desktop**. Finally it stages the binary + flattened config for Phase B.
+- **`bootstrap` (Phase B)** — on the booted system, as **your user**. What genuinely needs a
+  booted session: the AUR helper + `aur` packages (`makepkg` can't run as root) and btrfs
+  snapshots. Re-runnable any time to reconcile those.
 
 > **⚠️ archinstall version coupling.** archinstall's JSON config is *not* a stable API; its
 > schema changes between releases. Archwright renders against the version pinned in
@@ -333,12 +335,12 @@ packages at different points:
 
 | Field | When / how | Use for |
 |-------|------------|---------|
-| `pacstrap` | **Phase A**, by archinstall, verbatim | the minimum the system needs to *boot and run Phase B* — base-devel/git (to build the AUR helper), the login shell, `sudo`, `networkmanager`, `efibootmgr`, CPU microcode |
+| `pacstrap` | **Phase A**, by archinstall, verbatim | the minimum the system needs to *boot* — base-devel/git (to build the AUR helper), the login shell, `sudo`, `networkmanager`, `efibootmgr`, CPU microcode |
 | `kernel.base` | **Phase A** pacstrap | the bootable baseline kernel(s) — **official-repo only** (custom repos aren't set up yet) |
 | `kernel.packages` | **Phase A** chroot, after repo setup | extra/custom kernels (e.g. `linux-cachyos`) so the first boot can run them |
-| `packages` | **Phase B**, `pacman -S --needed` | everything else from the official (and custom) repos — the desktop, tools, etc. |
-| `aur` | **Phase B**, via the AUR helper | AUR packages (e.g. `1password`) |
-| `flatpaks` | **Phase B** | Flatpak apps |
+| `packages` | **Phase A** chroot, `pacman -S --needed`, after repos | everything else from the official (and custom) repos — the desktop, tools, etc. |
+| `aur` | **Phase B**, via the AUR helper | AUR packages (e.g. `1password`) — `makepkg` can't run as root, so this stays post-boot |
+| `flatpaks` | **Phase A** chroot, as the user (`--user`) | Flatpak apps |
 
 `pacstrap` is the **complete** Phase-A set, rendered verbatim — nothing is added in code.
 `preflight` only *warns* about recommended-but-absent entries; it never re-adds them.
@@ -430,7 +432,7 @@ stage order.
 
 ### `desktop` & `kde`
 
-`desktop.environment` selects which DE stage runs in Phase B. **Only KDE has a built-in stage**;
+`desktop.environment` selects which DE stage runs (in Phase A's chroot). **Only KDE has a built-in stage**;
 any other value makes the KDE stage a clean no-op — route that DE's setup through
 [`hooks`](#hooks) and your dotfiles instead.
 
@@ -487,9 +489,9 @@ setup:
 
 ### `services`
 
-Runs **last** in Phase B (after `dotfiles` and `setup`). `systemctl enable`s the listed units so
-they start on the **next boot** — the typical case is a login/display-manager unit that should
-take over after reboot rather than be started underneath the current session, so units are
+Runs **last** among the Phase A customization stages (after `dotfiles` and `setup`). `systemctl
+enable`s the listed units so they start on **first boot** — the typical case is a login/display-
+manager unit that should take over on boot rather than be started underneath the live ISO, so units are
 enabled, not `--now`-started. Enabling is idempotent, so the stage is safe to re-run.
 
 `enable` is system units (enabled as root); `user` is per-user units (enabled with
@@ -656,17 +658,19 @@ name **or** number.
 | # | Stage | Phase | What it does |
 |---|-------|-------|--------------|
 | 0  | `preflight`   | A | UEFI + config + archinstall version checks (warns, doesn't block) |
-| 10 | `archinstall` | A | reflector → probe geometry → render JSON (incl. `plymouth` boot splash) → `archinstall --silent` → chroot: repos + kernels → stage the binary for Phase B |
+| 10 | `archinstall` | A | reflector → probe geometry → render JSON (incl. `plymouth` boot splash) → `archinstall --silent` → chroot: repos + kernels → leaves the target mounted |
+| 20 | `mount`       | A | ensure the target mount tree at `/mnt` and open the chroot for the customization stages that follow |
+| 30 | `packages`    | A | `pacman -S --needed` the official/custom-repo packages (in the chroot) |
+| 40 | `flatpak`     | A | register `flatpak_remotes`, install `flatpaks` (as the user, `--user`) |
+| 50 | `grub-theme`  | A | apply the GRUB theme |
+| 60 | `kde`         | A | KDE global theme via `LookAndFeelPackage` in kdeglobals (no-op for other DEs) |
+| 70 | `dotfiles`    | A | apply dotfiles via the configured manager (as the user) |
+| 80 | `setup`       | A | run the ordered `setup.steps` (clones/commands, as the user) |
+| 90 | `services`    | A | `systemctl enable` the `services` units so they start on first boot |
+| 99 | `finalize`    | A | stage the binary + flattened config into the user's home, then unmount |
 | 10 | `yay`         | B | install the AUR helper (`aur_helper`) |
-| 20 | `packages`    | B | `pacman -S --needed` the official/custom-repo packages |
 | 25 | `snapper`     | B | provision Snapper (only when btrfs + `snapshots: snapper`) |
-| 30 | `flatpak`     | B | register `flatpak_remotes`, install `flatpaks` |
 | 40 | `aur`         | B | build/install the `aur` list via the helper |
-| 60 | `grub-theme`  | B | apply the GRUB theme |
-| 70 | `kde`         | B | KDE global theme via `LookAndFeelPackage` in kdeglobals (no-op for other DEs) |
-| 80 | `dotfiles`    | B | apply dotfiles via the configured manager |
-| 85 | `setup`       | B | run the ordered `setup.steps` (clones/commands) |
-| 90 | `services`    | B | `systemctl enable` the `services` units so they start on the next boot |
 
 (Phase A and Phase B each have their own order numbering — that's why both have a `10`.)
 
diff --git a/internal/stages/dotfiles.go b/internal/stages/dotfiles.go
index 41e677a..8895da2 100644
--- a/internal/stages/dotfiles.go
+++ b/internal/stages/dotfiles.go
@@ -2,14 +2,14 @@ package stages
 
 import (
 	"fmt"
-	"os"
-	"path/filepath"
 
 	"github.com/AdamJHall/archwright/internal/ui"
 )
 
-// dotfiles is the Phase B 80-dotfiles stage: install the configured dotfiles
-// manager and apply the dotfiles. Final Phase B step before setup.
+// dotfiles installs the configured dotfiles manager and applies the dotfiles. It
+// runs in the Phase A chroot as the configured user (the Runner routes the manager
+// commands through arch-chroot + sudo -iu), so the dotfiles are in place on first
+// boot.
 //
 // The manager is selectable (chezmoi, yadm, bare-git, none); chezmoi is the
 // default.
@@ -17,9 +17,9 @@ type dotfiles struct{}
 
 func init() { register(dotfiles{}) }
 
-func (dotfiles) Order() int   { return 80 }
+func (dotfiles) Order() int   { return 70 }
 func (dotfiles) Name() string { return "dotfiles" }
-func (dotfiles) Phase() Phase { return Bootstrap }
+func (dotfiles) Phase() Phase { return Install }
 
 // effectiveManager returns dotfiles.manager, defaulting to "chezmoi" when empty.
 func (dotfiles) effectiveManager(ctx *Context) string {
@@ -71,7 +71,7 @@ func (dotfiles) runChezmoi(ctx *Context, repo string) error {
 	}
 
 	// Already initialized? Apply. Otherwise init from the repo.
-	if homeHas(".local/share/chezmoi/.git") {
+	if homeHas(ctx, ".local/share/chezmoi/.git") {
 		return ctx.R.Cmd("chezmoi", "apply")
 	}
 	return ctx.R.Cmd("chezmoi", "init", "--apply", repo)
@@ -84,7 +84,7 @@ func (dotfiles) runYadm(ctx *Context, repo string) error {
 		return err
 	}
 
-	if homeHas(".local/share/yadm/repo.git") {
+	if homeHas(ctx, ".local/share/yadm/repo.git") {
 		ctx.R.Try("yadm", "pull") // best-effort: a clean tree may have nothing to pull
 		return nil
 	}
@@ -101,14 +101,10 @@ func (dotfiles) runBareGit(ctx *Context, repo string) error {
 		repo))
 }
 
-// homeHas reports whether the given path under the user's home directory exists.
-// It is a read-only probe (not recorded in the plan); under dry-run the path
-// usually won't exist, so the init/clone branch is what the plan shows.
-func homeHas(rel string) bool {
-	home, err := os.UserHomeDir()
-	if err != nil {
-		return false
-	}
-	_, err = os.Stat(filepath.Join(home, rel))
-	return err == nil
+// homeHas reports whether rel exists under the configured user's home in the
+// active execution context — inside the chroot target in Phase A. Read-only (not
+// recorded); under dry-run with a chroot target it returns false, so the plan
+// shows the init/clone branch.
+func homeHas(ctx *Context, rel string) bool {
+	return ctx.R.PathExists("/home/" + ctx.Cfg.User.Name + "/" + rel)
 }
diff --git a/internal/stages/dotfiles_test.go b/internal/stages/dotfiles_test.go
index 3d8c3f3..fad0c5a 100644
--- a/internal/stages/dotfiles_test.go
+++ b/internal/stages/dotfiles_test.go
@@ -5,59 +5,43 @@ import (
 	"testing"
 )
 
-// The dotfiles stage (80) selects a dotfiles manager. These tests assert the
-// recorded command plan for each manager. The chezmoi/yadm idempotency probes the
-// real $HOME via os.Stat; in tests that path won't exist, so the init/clone branch
-// is what we assert (we don't depend on the apply/pull branch).
-
-// chezmoiInitialized reports whether the test host already has chezmoi initialized;
-// when it does, the stage takes the `chezmoi apply` branch instead of init, so the
-// init-with-repo assertions are skipped (host-independent, like the AUR/KDE tests).
-func chezmoiInitialized() bool { return homeHas(".local/share/chezmoi/.git") }
+// The dotfiles stage selects a dotfiles manager and runs it as the user in the
+// Phase A chroot. These assert the recorded command plan for each manager. The
+// chezmoi/yadm idempotency probe (Runner.PathExists) returns false under a chroot
+// dry-run, so the init/clone branch is deterministic here.
 
 func TestDotfiles_ChezmoiDefault(t *testing.T) {
 	// Unset manager defaults to chezmoi; the repo comes from dotfiles.repo.
-	plan := planForCfg(t, Bootstrap, "dotfiles", `
+	plan := planForCfgChroot(t, "dotfiles", `
 dotfiles:
   repo: https://github.com/example/dotfiles
 `)
-	if chezmoiInitialized() {
-		mustContain(t, plan, "chezmoi apply")
-		return
-	}
-	mustContain(t, plan, "chezmoi init --apply https://github.com/example/dotfiles")
+	mustContain(t, plan, "arch-chroot /mnt sudo -iu adam -- chezmoi init --apply https://github.com/example/dotfiles")
 }
 
 func TestDotfiles_ChezmoiExplicit(t *testing.T) {
 	// Explicit manager + repo.
-	plan := planForCfg(t, Bootstrap, "dotfiles", `
+	plan := planForCfgChroot(t, "dotfiles", `
 dotfiles:
   manager: chezmoi
   repo: https://github.com/example/df-explicit
 `)
-	if chezmoiInitialized() {
-		mustContain(t, plan, "chezmoi apply")
-		return
-	}
-	mustContain(t, plan, "chezmoi init --apply https://github.com/example/df-explicit")
+	mustContain(t, plan, "arch-chroot /mnt sudo -iu adam -- chezmoi init --apply https://github.com/example/df-explicit")
 }
 
 func TestDotfiles_Yadm(t *testing.T) {
-	// On a host that already has yadm cloned the stage takes the `yadm pull` branch;
-	// skip the clone assertion there (host-independent).
-	if homeHas(".local/share/yadm/repo.git") {
-		t.Skip("yadm already cloned on this host; clone branch not exercised")
-	}
-	plan := planForCfg(t, Bootstrap, "dotfiles", `
+	plan := planForCfgChroot(t, "dotfiles", `
 dotfiles:
   manager: yadm
   repo: https://github.com/example/dotfiles
 `)
-	mustContain(t, plan, "yadm clone https://github.com/example/dotfiles")
+	mustContain(t, plan, "arch-chroot /mnt sudo -iu adam -- yadm clone https://github.com/example/dotfiles")
 }
 
 func TestDotfiles_BareGit(t *testing.T) {
-	plan := planForCfg(t, Bootstrap, "dotfiles", `
+	// bare-git runs as the user via a chroot shell; $HOME resolves to the user's
+	// login home inside the target, so the script keeps its $HOME references.
+	plan := planForCfgChroot(t, "dotfiles", `
 dotfiles:
   manager: bare-git
   repo: https://github.com/example/dotfiles
@@ -69,10 +53,13 @@ dotfiles:
 	if !strings.Contains(j, `git --git-dir="$HOME/.dotfiles" --work-tree="$HOME" checkout -f`) {
 		t.Errorf("bare-git plan should checkout the work-tree, got:\n%s", j)
 	}
+	if !strings.Contains(j, "arch-chroot /mnt sudo -iu adam bash -c") {
+		t.Errorf("bare-git should run as the user inside the chroot, got:\n%s", j)
+	}
 }
 
 func TestDotfiles_NoneIsNoOp(t *testing.T) {
-	plan := planForCfg(t, Bootstrap, "dotfiles", `
+	plan := planForCfgChroot(t, "dotfiles", `
 dotfiles:
   manager: none
   repo: https://github.com/example/dotfiles
@@ -84,7 +71,7 @@ dotfiles:
 
 func TestDotfiles_UnsetRepoSkips(t *testing.T) {
 	// A non-none manager with no repo is a clean skip.
-	plan := planForCfg(t, Bootstrap, "dotfiles", `
+	plan := planForCfgChroot(t, "dotfiles", `
 dotfiles:
   manager: chezmoi
 `)
diff --git a/internal/stages/flatpak.go b/internal/stages/flatpak.go
index 8d85e9c..8d42fa8 100644
--- a/internal/stages/flatpak.go
+++ b/internal/stages/flatpak.go
@@ -6,15 +6,17 @@ import (
 	"github.com/AdamJHall/archwright/internal/ui"
 )
 
-// flatpak is the Phase B 30-flatpak equivalent: ensure flatpak, register the
-// declared remotes, then install each configured app from its named remote.
+// flatpak ensures flatpak, registers the declared remotes, then installs each
+// configured app from its named remote. It runs in the Phase A chroot: the remote
+// + per-user installs run as the configured user (--user, so no polkit/root), and
+// ensureTool's pacman install runs as root — both via the Runner's chroot routing.
 type flatpak struct{}
 
 func init() { register(flatpak{}) }
 
-func (flatpak) Order() int   { return 30 }
+func (flatpak) Order() int   { return 40 }
 func (flatpak) Name() string { return "flatpak" }
-func (flatpak) Phase() Phase { return Bootstrap }
+func (flatpak) Phase() Phase { return Install }
 
 func (flatpak) Run(ctx *Context) error {
 	apps := ctx.Cfg.Flatpaks
diff --git a/internal/stages/flatpak_test.go b/internal/stages/flatpak_test.go
index 067cf64..f0b570a 100644
--- a/internal/stages/flatpak_test.go
+++ b/internal/stages/flatpak_test.go
@@ -5,12 +5,13 @@ import (
 	"testing"
 )
 
-// The flatpak stage (30) registers exactly the declared remotes (nothing
-// implicit) and installs each app from its named remote, parsed from the
-// "remote:appid" reference. These assert the recorded dry-run plan.
+// The flatpak stage registers exactly the declared remotes (nothing implicit) and
+// installs each app from its named remote, parsed from the "remote:appid"
+// reference. It runs in the Phase A chroot as the user (--user). These assert the
+// recorded dry-run plan.
 
 func TestFlatpak_RemotesAndPerAppInstall(t *testing.T) {
-	plan := planForCfg(t, Bootstrap, "flatpak", `
+	plan := planForCfgChroot(t, "flatpak", `
 flatpak_remotes:
   - name: flathub
     url: https://flathub.org/repo/flathub.flatpakrepo
@@ -23,11 +24,11 @@ flatpaks:
 	mustContain(t, plan,
 		// exactly the declared remotes, added verbatim — per-user scope (--user)
 		// so no polkit/root is needed (org.freedesktop.Flatpak.modify-repo hang).
-		"flatpak --user remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo",
-		"flatpak --user remote-add --if-not-exists flathub-beta https://flathub.org/beta-repo/flathub-beta.flatpakrepo",
+		"arch-chroot /mnt sudo -iu adam -- flatpak --user remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo",
+		"arch-chroot /mnt sudo -iu adam -- flatpak --user remote-add --if-not-exists flathub-beta https://flathub.org/beta-repo/flathub-beta.flatpakrepo",
 		// each app installed from its own named remote (per-app), per-user + noninteractive
-		"flatpak --user install -y --noninteractive flathub com.spotify.Client",
-		"flatpak --user install -y --noninteractive flathub-beta org.mozilla.firefox",
+		"arch-chroot /mnt sudo -iu adam -- flatpak --user install -y --noninteractive flathub com.spotify.Client",
+		"arch-chroot /mnt sudo -iu adam -- flatpak --user install -y --noninteractive flathub-beta org.mozilla.firefox",
 	)
 
 	joined := strings.Join(plan, "\n")
@@ -39,16 +40,13 @@ flatpaks:
 		t.Errorf("firefox should install from flathub-beta, not flathub; plan:\n%s", joined)
 	}
 
-	// Every invocation of the flatpak *binary* must stay unprivileged (Cmd, never
-	// Root/sudo): a system-scope flatpak op as the user drops into a polkit
-	// Password: prompt and bootstrap hangs forever in a headless/TTY session. We
-	// match flatpak as the command (after any sudo prefix), not as an argument —
-	// `sudo pacman -S … flatpak` (the ensureTool package install, only recorded
-	// when flatpak is absent) is legitimately privileged and must not trip this.
+	// The flatpak binary must run as the user (sudo -iu), never as root inside the
+	// chroot: a system-scope flatpak op drops into a polkit Password: prompt and
+	// hangs forever in a headless session. The legitimately-privileged pacman
+	// install from ensureTool (`arch-chroot /mnt pacman -S … flatpak`) is fine.
 	for _, line := range plan {
-		cmd := strings.TrimPrefix(line, "sudo ")
-		if cmd != line && strings.HasPrefix(cmd, "flatpak ") {
-			t.Errorf("flatpak must run unprivileged (no sudo) to avoid a polkit hang; got: %q", line)
+		if strings.Contains(line, "arch-chroot /mnt flatpak ") {
+			t.Errorf("flatpak must run as the user (sudo -iu), not as root, to avoid a polkit hang; got: %q", line)
 		}
 	}
 }
@@ -56,7 +54,7 @@ flatpaks:
 func TestFlatpak_NoRemotesNoImplicitFlathub(t *testing.T) {
 	// With no remotes and no apps the stage skips entirely — and in particular
 	// never adds a built-in flathub remote.
-	plan := planForCfg(t, Bootstrap, "flatpak", "{}\n")
+	plan := planForCfgChroot(t, "flatpak", "{}\n")
 	if joined := strings.Join(plan, "\n"); strings.Contains(joined, "remote-add") {
 		t.Errorf("no flatpak remote should be added when none are declared; plan:\n%s", joined)
 	}
diff --git a/internal/stages/fromto_test.go b/internal/stages/fromto_test.go
index 4742244..b02d2fc 100644
--- a/internal/stages/fromto_test.go
+++ b/internal/stages/fromto_test.go
@@ -7,10 +7,11 @@ import (
 
 // TestWithin exercises the --from/--to post-filter applied after Select.
 // It resolves bounds by name OR number (like --only), is inclusive on both
-// ends, and composes with the already-narrowed slice it is handed.
+// ends, and composes with the already-narrowed slice it is handed. Phase A now
+// owns the rich ordered customization set, so the windows are tested against it.
 func TestWithin(t *testing.T) {
-	// The full ordered Bootstrap set, used as the input to most cases.
-	all := names(For(Bootstrap, ""))
+	// The full ordered Install set, used as the input to most cases.
+	all := names(For(Install, ""))
 
 	tests := []struct {
 		name    string
@@ -26,42 +27,42 @@ func TestWithin(t *testing.T) {
 		},
 		{
 			name: "from only by name is inclusive lower bound",
-			from: "flatpak", to: "",
-			want: []string{"flatpak", "aur", "grub-theme", "kde", "dotfiles", "setup", "services"},
+			from: "packages", to: "",
+			want: []string{"packages", "flatpak", "grub-theme", "kde", "dotfiles", "setup", "services", "finalize"},
 		},
 		{
 			name: "from only by number resolves same as name",
 			from: "30", to: "",
-			want: []string{"flatpak", "aur", "grub-theme", "kde", "dotfiles", "setup", "services"},
+			want: []string{"packages", "flatpak", "grub-theme", "kde", "dotfiles", "setup", "services", "finalize"},
 		},
 		{
 			name: "to only by name is inclusive upper bound",
-			from: "", to: "flatpak",
-			want: []string{"yay", "packages", "snapper", "flatpak"},
+			from: "", to: "packages",
+			want: []string{"preflight", "archinstall", "mount", "packages"},
 		},
 		{
 			name: "to only by number resolves same as name",
 			from: "", to: "30",
-			want: []string{"yay", "packages", "snapper", "flatpak"},
+			want: []string{"preflight", "archinstall", "mount", "packages"},
 		},
 		{
 			name: "both bounds inclusive on each end",
-			from: "packages", to: "aur",
-			want: []string{"packages", "snapper", "flatpak", "aur"},
+			from: "packages", to: "kde",
+			want: []string{"packages", "flatpak", "grub-theme", "kde"},
 		},
 		{
 			name: "both bounds mixing name and number",
-			from: "20", to: "kde",
-			want: []string{"packages", "snapper", "flatpak", "aur", "grub-theme", "kde"},
+			from: "30", to: "kde",
+			want: []string{"packages", "flatpak", "grub-theme", "kde"},
 		},
 		{
 			name: "single-stage window when from equals to",
-			from: "aur", to: "aur",
-			want: []string{"aur"},
+			from: "kde", to: "kde",
+			want: []string{"kde"},
 		},
 		{
 			name:    "inverted bounds is an error",
-			from:    "aur",
+			from:    "kde",
 			to:      "packages",
 			wantErr: "from",
 		},
@@ -81,7 +82,7 @@ func TestWithin(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			in := For(Bootstrap, "")
+			in := For(Install, "")
 			got, err := Within(in, tt.from, tt.to)
 			if tt.wantErr != "" {
 				if err == nil {
@@ -105,12 +106,12 @@ func TestWithin(t *testing.T) {
 // TestWithin_ComposesWithSkip confirms the filter operates on whatever Select
 // already produced: a skipped stage stays absent even when inside the window.
 func TestWithin_ComposesWithSkip(t *testing.T) {
-	in := Select(Bootstrap, "", []string{"snapper"}, nil)
-	got, err := Within(in, "packages", "aur")
+	in := Select(Install, "", []string{"flatpak"}, nil)
+	got, err := Within(in, "packages", "kde")
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	want := []string{"packages", "flatpak", "aur"} // snapper removed by --skip
+	want := []string{"packages", "grub-theme", "kde"} // flatpak removed by --skip
 	if g := names(got); !equalStrings(g, want) {
 		t.Fatalf("Within over skipped input = %v, want %v", g, want)
 	}
@@ -118,7 +119,7 @@ func TestWithin_ComposesWithSkip(t *testing.T) {
 
 // TestWithin_EmptyInput is a no-op pass-through, never a panic.
 func TestWithin_EmptyInput(t *testing.T) {
-	got, err := Within(nil, "packages", "aur")
+	got, err := Within(nil, "packages", "kde")
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
diff --git a/internal/stages/grubtheme.go b/internal/stages/grubtheme.go
index b16d604..0b35071 100644
--- a/internal/stages/grubtheme.go
+++ b/internal/stages/grubtheme.go
@@ -7,15 +7,16 @@ import (
 	"github.com/AdamJHall/archwright/internal/ui"
 )
 
-// grubtheme is the Phase B 60-grub-theme equivalent: install and select a GRUB
-// theme. source: vinceliuice | url | none.
+// grubtheme installs and selects a GRUB theme. source: vinceliuice | url | none.
+// It runs in the Phase A chroot, where everything is root — so the vinceliuice
+// installer runs directly (no inner sudo) via cloneBuildRoot.
 type grubtheme struct{}
 
 func init() { register(grubtheme{}) }
 
-func (grubtheme) Order() int   { return 60 }
+func (grubtheme) Order() int   { return 50 }
 func (grubtheme) Name() string { return "grub-theme" }
-func (grubtheme) Phase() Phase { return Bootstrap }
+func (grubtheme) Phase() Phase { return Install }
 
 func (grubtheme) Run(ctx *Context) error {
 	t := ctx.Cfg.GRUB.Theme
@@ -29,9 +30,9 @@ func (grubtheme) Run(ctx *Context) error {
 			return fmt.Errorf("grub.theme.name required for source 'vinceliuice'")
 		}
 		// Clone + run the upstream installer (it sets GRUB_THEME and regenerates).
-		// cloneBuild runs as the user (it mktemp/git-clones into the user's tree),
-		// so install.sh keeps its inner `sudo` to gain root for the system writes.
-		install := fmt.Sprintf("sudo ./install.sh -t %s", t.Name)
+		// cloneBuildRoot runs the whole thing as root, so install.sh needs no inner
+		// sudo to perform its system writes (/boot, /etc/default/grub).
+		install := fmt.Sprintf("./install.sh -t %s", t.Name)
 		if t.Screen != "" {
 			install += " -s " + t.Screen
 		}
@@ -47,7 +48,7 @@ func (grubtheme) Run(ctx *Context) error {
 			}
 			install = fetch + " && " + install
 		}
-		if err := cloneBuild(ctx,
+		if err := cloneBuildRoot(ctx,
 			"--depth 1 https://github.com/vinceliuice/grub2-themes", install); err != nil {
 			return err
 		}
diff --git a/internal/stages/grubtheme_screen_bg_test.go b/internal/stages/grubtheme_screen_bg_test.go
index 672d003..a0f9233 100644
--- a/internal/stages/grubtheme_screen_bg_test.go
+++ b/internal/stages/grubtheme_screen_bg_test.go
@@ -5,22 +5,27 @@ import (
 	"testing"
 )
 
+// The grub-theme stage runs wholly as root in the Phase A chroot (cloneBuildRoot),
+// so the vinceliuice install.sh carries no inner sudo. The clone+install pipeline
+// is recorded as a single `sh: arch-chroot /mnt bash -c …` line, so these assert on
+// substrings of that command.
+
 // screen maps to the installer's -s flag.
 func TestGrubTheme_Screen(t *testing.T) {
-	plan := planForCfg(t, Bootstrap, "grub-theme", `
+	plan := planForCfgChroot(t, "grub-theme", `
 grub:
   theme:
     source: vinceliuice
     name: tela
     screen: 4k
 `)
-	mustContain(t, plan, "sudo ./install.sh -t tela -s 4k")
+	mustContain(t, plan, "./install.sh -t tela -s 4k")
 }
 
 // A background URL is fetched into the checkout root as background.jpg before the
 // installer runs (install.sh picks it up automatically when present).
 func TestGrubTheme_BackgroundURL(t *testing.T) {
-	plan := planForCfg(t, Bootstrap, "grub-theme", `
+	plan := planForCfgChroot(t, "grub-theme", `
 grub:
   theme:
     source: vinceliuice
@@ -28,20 +33,20 @@ grub:
     background: https://raw.githubusercontent.com/me/dotfiles/main/background.jpg
 `)
 	mustContain(t, plan,
-		`curl -fsSL "https://raw.githubusercontent.com/me/dotfiles/main/background.jpg" -o background.jpg && sudo ./install.sh -t tela`,
+		`curl -fsSL "https://raw.githubusercontent.com/me/dotfiles/main/background.jpg" -o background.jpg && ./install.sh -t tela`,
 	)
 }
 
 // A local background path is copied into the checkout root instead of fetched.
 func TestGrubTheme_BackgroundLocalPath(t *testing.T) {
-	plan := planForCfg(t, Bootstrap, "grub-theme", `
+	plan := planForCfgChroot(t, "grub-theme", `
 grub:
   theme:
     source: vinceliuice
     name: tela
     background: /home/me/wallpapers/grub.jpg
 `)
-	mustContain(t, plan, `cp -f "/home/me/wallpapers/grub.jpg" background.jpg && sudo ./install.sh -t tela`)
+	mustContain(t, plan, `cp -f "/home/me/wallpapers/grub.jpg" background.jpg && ./install.sh -t tela`)
 	if j := strings.Join(plan, "\n"); strings.Contains(j, "curl") {
 		t.Errorf("local path should be copied, not curled:\n%s", j)
 	}
@@ -49,14 +54,14 @@ grub:
 
 // With neither set, the command is unchanged from today (default-preserves-behaviour).
 func TestGrubTheme_NoScreenOrBackground(t *testing.T) {
-	plan := planForCfg(t, Bootstrap, "grub-theme", `
+	plan := planForCfgChroot(t, "grub-theme", `
 grub:
   theme:
     source: vinceliuice
     name: tela
 `)
 	j := strings.Join(plan, "\n")
-	mustContain(t, plan, "sudo ./install.sh -t tela")
+	mustContain(t, plan, "./install.sh -t tela")
 	if strings.Contains(j, "-s ") || strings.Contains(j, "background.jpg") {
 		t.Errorf("unset screen/background should not alter the install command:\n%s", j)
 	}
diff --git a/internal/stages/helpers.go b/internal/stages/helpers.go
index 2c0c167..21bb8e1 100644
--- a/internal/stages/helpers.go
+++ b/internal/stages/helpers.go
@@ -2,30 +2,41 @@ package stages
 
 import (
 	"fmt"
-	"os/exec"
 )
 
-// This file holds small helpers shared by the Phase B stages, collapsing patterns
-// that were duplicated across several stages. They emit the same commands the
-// inline code did, so the recorded .Plan (and therefore the stage tests) is
-// unchanged — this is a behaviour-preserving refactor.
+// This file holds small helpers shared by the customization stages, collapsing
+// patterns that were duplicated across several stages.
 
 // ensureTool installs pkg via pacman (--needed --noconfirm) when bin is not
-// already on PATH. The LookPath probe is read-only and not recorded; only the
-// install (when needed) goes through the Runner.
+// already available. The probe (Runner.Has) is read-only and not recorded; it
+// checks the chroot target in Phase A and the host otherwise. Only the install
+// (when needed) goes through the Runner.
 func ensureTool(ctx *Context, bin, pkg string) error {
-	if _, err := exec.LookPath(bin); err == nil {
+	if ctx.R.Has(bin) {
 		return nil
 	}
 	return ctx.R.Root("pacman", "-S", "--needed", "--noconfirm", pkg)
 }
 
 // cloneBuild git-clones a repo into a temp dir, runs inCheckout from within it,
-// and removes the temp dir — the shared "clone, build, clean" idiom. cloneArgs is
-// the git-clone argument string (any flags plus the URL); inCheckout is the shell
-// run from inside the checkout.
+// and removes the temp dir — the shared "clone, build, clean" idiom, run
+// unprivileged (as the user). cloneArgs is the git-clone argument string (any
+// flags plus the URL); inCheckout is the shell run from inside the checkout.
 func cloneBuild(ctx *Context, cloneArgs, inCheckout string) error {
-	return ctx.R.Shell(fmt.Sprintf(
+	return ctx.R.Shell(cloneBuildScript(cloneArgs, inCheckout))
+}
+
+// cloneBuildRoot is the root variant of cloneBuild: the whole clone+build runs as
+// root (RootShell), so the inCheckout step needs no inner sudo. Used where the
+// build writes to system locations (e.g. a GRUB theme installer touching /boot) —
+// in the Phase A chroot we are already root, so escalation from the user is both
+// unnecessary and impossible (no interactive password).
+func cloneBuildRoot(ctx *Context, cloneArgs, inCheckout string) error {
+	return ctx.R.RootShell(cloneBuildScript(cloneArgs, inCheckout))
+}
+
+func cloneBuildScript(cloneArgs, inCheckout string) string {
+	return fmt.Sprintf(
 		`tmp="$(mktemp -d)" && git clone %s "$tmp" && (cd "$tmp" && %s) && rm -rf "$tmp"`,
-		cloneArgs, inCheckout))
+		cloneArgs, inCheckout)
 }
diff --git a/internal/stages/kde.go b/internal/stages/kde.go
index 0f07797..c536a4d 100644
--- a/internal/stages/kde.go
+++ b/internal/stages/kde.go
@@ -20,9 +20,9 @@ type kde struct{}
 
 func init() { register(kde{}) }
 
-func (kde) Order() int   { return 70 }
+func (kde) Order() int   { return 60 }
 func (kde) Name() string { return "kde" }
-func (kde) Phase() Phase { return Bootstrap }
+func (kde) Phase() Phase { return Install }
 
 func (kde) Run(ctx *Context) error {
 	if de := ctx.Cfg.Desktop.Environment; de != "" && de != "kde" {
diff --git a/internal/stages/kde_lookandfeel_test.go b/internal/stages/kde_lookandfeel_test.go
index 2f4d4af..5144c8d 100644
--- a/internal/stages/kde_lookandfeel_test.go
+++ b/internal/stages/kde_lookandfeel_test.go
@@ -8,15 +8,15 @@ import (
 // The kde stage selects the Plasma global theme by writing LookAndFeelPackage into
 // kdeglobals — deterministic and session-free, so the plan is asserted directly.
 func TestKDE_SetsLookAndFeelPackage(t *testing.T) {
-	plan := planForCfg(t, Bootstrap, "kde", "kde:\n  look_and_feel: org.kde.breezedark.desktop\n")
+	plan := planForCfgChroot(t, "kde", "kde:\n  look_and_feel: org.kde.breezedark.desktop\n")
 	mustContain(t, plan,
-		"kwriteconfig6 --file kdeglobals --group KDE --key LookAndFeelPackage org.kde.breezedark.desktop",
+		"arch-chroot /mnt sudo -iu adam -- kwriteconfig6 --file kdeglobals --group KDE --key LookAndFeelPackage org.kde.breezedark.desktop",
 	)
 }
 
 // With no look_and_feel configured the stage is a clean no-op: nothing is written.
 func TestKDE_NoLookAndFeelIsNoOp(t *testing.T) {
-	plan := planForCfg(t, Bootstrap, "kde", "kde: {}\n")
+	plan := planForCfgChroot(t, "kde", "kde: {}\n")
 	if j := strings.Join(plan, "\n"); strings.Contains(j, "kwriteconfig6") {
 		t.Errorf("kde stage should write nothing when look_and_feel is unset, got plan:\n%s", j)
 	}
diff --git a/internal/stages/packages.go b/internal/stages/packages.go
index 13d1b88..72e0bd6 100644
--- a/internal/stages/packages.go
+++ b/internal/stages/packages.go
@@ -2,15 +2,16 @@ package stages
 
 import "github.com/AdamJHall/archwright/internal/ui"
 
-// packages is the Phase B post/20-packages equivalent: install official-repo
-// packages via pacman. Shows how a config slice drives a single command.
+// packages installs the official/custom-repo packages via pacman. It runs in the
+// Phase A chroot (after the repos + mount stages), so the desktop is installed
+// before first boot; the Runner routes the pacman call through arch-chroot.
 type packages struct{}
 
 func init() { register(packages{}) }
 
-func (packages) Order() int   { return 20 }
+func (packages) Order() int   { return 30 }
 func (packages) Name() string { return "packages" }
-func (packages) Phase() Phase { return Bootstrap }
+func (packages) Phase() Phase { return Install }
 
 func (packages) Run(ctx *Context) error {
 	pkgs := ctx.Cfg.Packages
diff --git a/internal/stages/selection_test.go b/internal/stages/selection_test.go
index bdd0c56..8aae89b 100644
--- a/internal/stages/selection_test.go
+++ b/internal/stages/selection_test.go
@@ -24,22 +24,22 @@ func contains(ss []Stage, name string) bool {
 }
 
 func TestSelect_OnlyWins(t *testing.T) {
-	got := names(Select(Bootstrap, "kde", nil, nil))
+	got := names(Select(Install, "kde", nil, nil))
 	if len(got) != 1 || got[0] != "kde" {
 		t.Fatalf("Select only=kde = %v, want [kde]", got)
 	}
 }
 
 func TestSelect_OnlyOverridesDisable(t *testing.T) {
-	got := names(Select(Bootstrap, "kde", nil, []string{"kde"}))
+	got := names(Select(Install, "kde", nil, []string{"kde"}))
 	if len(got) != 1 || got[0] != "kde" {
 		t.Fatalf("Select only=kde disable=[kde] = %v, want [kde]", got)
 	}
 }
 
 func TestSelect_Skip(t *testing.T) {
-	got := Select(Bootstrap, "", []string{"kde"}, nil)
-	all := For(Bootstrap, "")
+	got := Select(Install, "", []string{"kde"}, nil)
+	all := For(Install, "")
 	if len(got) != len(all)-1 {
 		t.Fatalf("skip=[kde] returned %d stages, want %d", len(got), len(all)-1)
 	}
@@ -50,19 +50,19 @@ func TestSelect_Skip(t *testing.T) {
 
 func TestSelect_DisableByNameAndNumber(t *testing.T) {
 	// Disable by name excludes both kde and flatpak.
-	got := Select(Bootstrap, "", nil, []string{"kde", "flatpak"})
+	got := Select(Install, "", nil, []string{"kde", "flatpak"})
 	if contains(got, "kde") || contains(got, "flatpak") {
 		t.Errorf("disable=[kde flatpak] still contains one of them: %v", names(got))
 	}
 
-	// Disable by order number: flatpak is order 30.
-	got = Select(Bootstrap, "", nil, []string{"30"})
+	// Disable by order number: flatpak is order 40.
+	got = Select(Install, "", nil, []string{"40"})
 	if contains(got, "flatpak") {
-		t.Errorf("disable=[30] still contains flatpak (order 30): %v", names(got))
+		t.Errorf("disable=[40] still contains flatpak (order 40): %v", names(got))
 	}
-	all := For(Bootstrap, "")
+	all := For(Install, "")
 	if len(got) != len(all)-1 {
-		t.Fatalf("disable=[30] returned %d stages, want %d", len(got), len(all)-1)
+		t.Fatalf("disable=[40] returned %d stages, want %d", len(got), len(all)-1)
 	}
 }
 
diff --git a/internal/stages/selectors_test.go b/internal/stages/selectors_test.go
index 860875a..74dcdf5 100644
--- a/internal/stages/selectors_test.go
+++ b/internal/stages/selectors_test.go
@@ -31,9 +31,35 @@ func planForCfg(t *testing.T, phase Phase, name, yamlBody string) []string {
 	return r.Plan
 }
 
+// planForCfgChroot is the Phase A variant of planForCfg: it runs an Install-phase
+// customization stage with the chroot target active (as the mount stage leaves it),
+// so the plan is the arch-chroot-wrapped form the stage runs on a fresh install.
+// AsUser defaults to "adam" when the inline config omits user.name.
+func planForCfgChroot(t *testing.T, name, yamlBody string) []string {
+	t.Helper()
+	var c config.Config
+	if err := yaml.Unmarshal([]byte(yamlBody), &c); err != nil {
+		t.Fatalf("unmarshal config: %v", err)
+	}
+	ss := For(Install, name)
+	if len(ss) != 1 {
+		t.Fatalf("expected exactly one stage %q in Install, got %d", name, len(ss))
+	}
+	asUser := c.User.Name
+	if asUser == "" {
+		asUser = "adam"
+	}
+	r := &run.Runner{DryRun: true, ChrootRoot: "/mnt", AsUser: asUser}
+	ctx := &Context{Cfg: &c, R: r, AssumeYes: true, ConfigPath: "/tmp/config.yaml"}
+	if err := ss[0].Run(ctx); err != nil {
+		t.Fatalf("stage %s returned error in dry-run: %v", name, err)
+	}
+	return r.Plan
+}
+
 func TestSelector_KDEGating(t *testing.T) {
 	// A non-kde environment makes the stage a clean no-op: nothing is written.
-	plan := planForCfg(t, Bootstrap, "kde", `
+	plan := planForCfgChroot(t, "kde", `
 desktop:
   environment: gnome
 kde:
@@ -51,8 +77,8 @@ kde:
 		if env != "" {
 			body = "desktop:\n  environment: " + env + "\n" + body
 		}
-		plan := planForCfg(t, Bootstrap, "kde", body)
-		mustContain(t, plan, "kwriteconfig6 --file kdeglobals --group KDE --key LookAndFeelPackage org.kde.breezedark.desktop")
+		plan := planForCfgChroot(t, "kde", body)
+		mustContain(t, plan, "arch-chroot /mnt sudo -iu adam -- kwriteconfig6 --file kdeglobals --group KDE --key LookAndFeelPackage org.kde.breezedark.desktop")
 	}
 }
 
@@ -86,7 +112,7 @@ func TestSelector_AurHelper(t *testing.T) {
 }
 
 func TestSelector_FlatpakRemotes(t *testing.T) {
-	plan := planForCfg(t, Bootstrap, "flatpak", `
+	plan := planForCfgChroot(t, "flatpak", `
 flatpak_remotes:
   - name: flathub
     url: https://flathub.org/repo/flathub.flatpakrepo
@@ -95,10 +121,10 @@ flatpak_remotes:
 flatpaks: [flathub-beta:com.spotify.Client]
 `)
 	mustContain(t, plan,
-		// exactly the declared remotes — no remote is implicit
-		"flatpak --user remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo",
-		"flatpak --user remote-add --if-not-exists flathub-beta https://flathub.org/beta-repo/flathub-beta.flatpakrepo",
+		// exactly the declared remotes — no remote is implicit — as the user in the chroot
+		"arch-chroot /mnt sudo -iu adam -- flatpak --user remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo",
+		"arch-chroot /mnt sudo -iu adam -- flatpak --user remote-add --if-not-exists flathub-beta https://flathub.org/beta-repo/flathub-beta.flatpakrepo",
 		// the app installs from its named remote
-		"flatpak --user install -y --noninteractive flathub-beta com.spotify.Client",
+		"arch-chroot /mnt sudo -iu adam -- flatpak --user install -y --noninteractive flathub-beta com.spotify.Client",
 	)
 }
diff --git a/internal/stages/services.go b/internal/stages/services.go
index 404f20b..bb3fab5 100644
--- a/internal/stages/services.go
+++ b/internal/stages/services.go
@@ -2,22 +2,22 @@ package stages
 
 import "github.com/AdamJHall/archwright/internal/ui"
 
-// services is the Phase B 90-services stage: enable the configured systemd units
-// so they start on the next boot. It runs last (after dotfiles + setup) so any
-// unit a dotfiles/setup step installs is already present to be enabled.
+// services enables the configured systemd units so they start on first boot. It
+// runs late in the Phase A chroot (after dotfiles + setup) so any unit those steps
+// installed is already present to be enabled.
 //
-// System units are enabled as root (`systemctl enable`); user units are enabled
-// unprivileged (`systemctl --user enable`). Enabling is idempotent, so the stage
-// is safe to re-run. We deliberately don't `--now`-start them: the typical case
-// is a login/display-manager unit (e.g. plasmalogin.service) that should take
-// over on the next boot, not be started underneath the current session.
+// System units are enabled as root (`systemctl enable`); user units are enabled as
+// the configured user (`systemctl --user enable`) — both routed through the chroot
+// by the Runner. `enable` only writes symlinks (no running systemd/bus needed), so
+// it works inside the chroot. We deliberately don't `--now`-start them: enabling
+// for the next boot is the whole point, and nothing should start under the live ISO.
 type services struct{}
 
 func init() { register(services{}) }
 
 func (services) Order() int   { return 90 }
 func (services) Name() string { return "services" }
-func (services) Phase() Phase { return Bootstrap }
+func (services) Phase() Phase { return Install }
 
 func (services) Run(ctx *Context) error {
 	sys := ctx.Cfg.Services.Enable
diff --git a/internal/stages/services_test.go b/internal/stages/services_test.go
index a0bd5b5..e9920ae 100644
--- a/internal/stages/services_test.go
+++ b/internal/stages/services_test.go
@@ -5,12 +5,13 @@ import (
 	"testing"
 )
 
-// The services stage (90) enables system units as root and user units with
-// `systemctl --user`, so they start on the next boot. These assert the recorded
-// dry-run plan against an inline config.
+// The services stage enables system units as root and user units with
+// `systemctl --user`, so they start on first boot. It runs in the Phase A chroot,
+// so the calls are arch-chroot-wrapped (system as root, user via sudo -iu). These
+// assert the recorded dry-run plan against an inline config.
 
 func TestServices_SystemAndUser(t *testing.T) {
-	plan := planForCfg(t, Bootstrap, "services", `
+	plan := planForCfgChroot(t, "services", `
 services:
   enable:
     - plasmalogin.service
@@ -19,16 +20,16 @@ services:
     - syncthing.service
 `)
 	mustContain(t, plan,
-		// system units enabled in one privileged systemctl call (Sudo in Phase B)
-		"sudo systemctl enable plasmalogin.service bluetooth.service",
-		// user units enabled unprivileged via --user
-		"systemctl --user enable syncthing.service",
+		// system units enabled in one root systemctl call inside the chroot
+		"arch-chroot /mnt systemctl enable plasmalogin.service bluetooth.service",
+		// user units enabled as the user via --user
+		"arch-chroot /mnt sudo -iu adam -- systemctl --user enable syncthing.service",
 	)
 }
 
 func TestServices_EmptySkips(t *testing.T) {
 	// No services block: the stage is a clean no-op — nothing planned.
-	plan := planForCfg(t, Bootstrap, "services", "{}\n")
+	plan := planForCfgChroot(t, "services", "{}\n")
 	if joined := strings.Join(plan, "\n"); strings.Contains(joined, "systemctl") {
 		t.Errorf("no systemctl call expected when services is unset; plan:\n%s", joined)
 	}
@@ -36,11 +37,11 @@ func TestServices_EmptySkips(t *testing.T) {
 
 func TestServices_SystemOnly(t *testing.T) {
 	// Only system units set: no stray `systemctl --user` call.
-	plan := planForCfg(t, Bootstrap, "services", `
+	plan := planForCfgChroot(t, "services", `
 services:
   enable: [docker.service]
 `)
-	mustContain(t, plan, "sudo systemctl enable docker.service")
+	mustContain(t, plan, "arch-chroot /mnt systemctl enable docker.service")
 	if joined := strings.Join(plan, "\n"); strings.Contains(joined, "--user") {
 		t.Errorf("no --user call expected when only system units set; plan:\n%s", joined)
 	}
diff --git a/internal/stages/setup.go b/internal/stages/setup.go
index b8bbb2b..6cc8f2e 100644
--- a/internal/stages/setup.go
+++ b/internal/stages/setup.go
@@ -9,18 +9,18 @@ import (
 	"github.com/AdamJHall/archwright/internal/ui"
 )
 
-// setup is the Phase B 85-setup stage: run the ordered list of setup steps that
-// install what a dotfiles repo references but can't vendor itself (oh-my-zsh and
-// its custom plugins, tmux's TPM, theme repos). Each step is a git clone or a
-// shell command; they execute in the order written. It runs after dotfiles (80)
-// so the dotfiles dirs the clones target already exist.
+// setup runs the ordered list of setup steps that install what a dotfiles repo
+// references but can't vendor itself (oh-my-zsh and its custom plugins, tmux's TPM,
+// theme repos). Each step is a git clone or a shell command; they execute in the
+// order written. It runs after dotfiles (70) in the Phase A chroot, as the
+// configured user, so the dotfiles dirs the clones target already exist.
 type setup struct{}
 
 func init() { register(setup{}) }
 
-func (setup) Order() int   { return 85 }
+func (setup) Order() int   { return 80 }
 func (setup) Name() string { return "setup" }
-func (setup) Phase() Phase { return Bootstrap }
+func (setup) Phase() Phase { return Install }
 
 func (setup) Run(ctx *Context) error {
 	steps := ctx.Cfg.Setup.Steps
@@ -46,20 +46,20 @@ func (setup) Run(ctx *Context) error {
 }
 
 // cloneRepo clones c into its destination, idempotently: an existing dest is left
-// alone (or `git pull`ed when c.Update is set) so the stage is safe to re-run.
+// alone (or `git pull`ed when c.Update is set) so the stage is safe to re-run. The
+// dest's ~ resolves to the configured user's home inside the chroot, and the
+// presence check runs in that same context (Runner.PathExists).
 func cloneRepo(ctx *Context, c config.Clone) error {
-	dest := expandHome(c.Dest)
+	dest := expandUserHome(ctx, c.Dest)
 
-	// Idempotency depends on host state, which doesn't exist under --dry-run; there
-	// we always plan the clone so the printed plan shows the intended action.
-	if !ctx.R.DryRun {
-		if _, err := os.Stat(dest); err == nil {
-			if c.Update {
-				return ctx.R.Cmd("git", "-C", dest, "pull", "--ff-only")
-			}
-			ui.Info("clone target already present — skipping", "dest", dest)
-			return nil
+	// PathExists is dry-run-aware: under --dry-run it returns false, so the plan
+	// always shows the clone (host/chroot state is irrelevant there).
+	if ctx.R.PathExists(dest) {
+		if c.Update {
+			return ctx.R.Cmd("git", "-C", dest, "pull", "--ff-only")
 		}
+		ui.Info("clone target already present — skipping", "dest", dest)
+		return nil
 	}
 
 	args := []string{"clone", "--depth", "1"}
@@ -70,7 +70,18 @@ func cloneRepo(ctx *Context, c config.Clone) error {
 	return ctx.R.Cmd("git", args...)
 }
 
-// expandHome turns a leading ~ into the user's home directory.
+// expandUserHome turns a leading ~ into the configured user's home directory
+// (/home/<user>). In the Phase A chroot that is the correct home; os.UserHomeDir
+// would wrongly resolve to the live ISO's root home.
+func expandUserHome(ctx *Context, p string) string {
+	if p == "~" || strings.HasPrefix(p, "~/") {
+		return filepath.Join("/home/"+ctx.Cfg.User.Name, strings.TrimPrefix(p, "~"))
+	}
+	return p
+}
+
+// expandHome turns a leading ~ into the host user's home directory. It is used by
+// hook Dir/Script expansion, which resolves against the executing user's home.
 func expandHome(p string) string {
 	if p == "~" || strings.HasPrefix(p, "~/") {
 		if home, err := os.UserHomeDir(); err == nil {
diff --git a/internal/stages/stages_test.go b/internal/stages/stages_test.go
index 7b1f3d2..d0c8831 100644
--- a/internal/stages/stages_test.go
+++ b/internal/stages/stages_test.go
@@ -1,8 +1,6 @@
 package stages
 
 import (
-	"os"
-	"path/filepath"
 	"strings"
 	"testing"
 
@@ -144,11 +142,29 @@ func TestRegistry(t *testing.T) {
 		}
 	}
 	check(Install,
-		[]string{"preflight", "archinstall", "mount", "finalize"},
-		[]int{0, 10, 20, 99})
+		[]string{"preflight", "archinstall", "mount", "packages", "flatpak", "grub-theme", "kde", "dotfiles", "setup", "services", "finalize"},
+		[]int{0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 99})
 	check(Bootstrap,
-		[]string{"yay", "packages", "snapper", "flatpak", "aur", "grub-theme", "kde", "dotfiles", "setup", "services"},
-		[]int{10, 20, 25, 30, 40, 60, 70, 80, 85, 90})
+		[]string{"yay", "snapper", "aur"},
+		[]int{10, 25, 40})
+}
+
+// planForChroot runs a single Phase A customization stage in dry-run with the
+// chroot target active (as the `mount` stage would leave it), so the recorded plan
+// is the real arch-chroot-wrapped form the stage runs on a fresh install.
+func planForChroot(t *testing.T, name string) []string {
+	t.Helper()
+	ss := For(Install, name)
+	if len(ss) != 1 {
+		t.Fatalf("expected exactly one stage %q in Install, got %d", name, len(ss))
+	}
+	cfg := testConfig(t)
+	r := &run.Runner{DryRun: true, ChrootRoot: "/mnt", AsUser: cfg.User.Name}
+	ctx := &Context{Cfg: cfg, R: r, AssumeYes: true, ConfigPath: "/tmp/config.yaml"}
+	if err := ss[0].Run(ctx); err != nil {
+		t.Fatalf("stage %s returned error in dry-run: %v", name, err)
+	}
+	return r.Plan
 }
 
 func TestPlan_Archinstall(t *testing.T) {
@@ -217,47 +233,51 @@ func TestWipedDevices(t *testing.T) {
 }
 
 func TestPlan_Packages(t *testing.T) {
-	mustContain(t, planFor(t, Bootstrap, "packages"),
-		"pacman -S --needed --noconfirm git firefox",
+	// Runs in the Phase A chroot as root, after repos are configured.
+	mustContain(t, planForChroot(t, "packages"),
+		"arch-chroot /mnt pacman -S --needed --noconfirm git firefox",
 	)
 }
 
 func TestPlan_AUR(t *testing.T) {
+	// aur stays in Phase B (makepkg can't run as root; needs a real user session).
 	mustContain(t, planFor(t, Bootstrap, "aur"),
 		"yay -S --needed --noconfirm 1password 1password-cli",
 	)
 }
 
 func TestPlan_Flatpak(t *testing.T) {
-	mustContain(t, planFor(t, Bootstrap, "flatpak"),
-		"flatpak --user remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo",
-		"flatpak --user install -y --noninteractive flathub com.spotify.Client",
+	// Remotes + per-user installs run as the user inside the chroot (--user, so no
+	// polkit/root).
+	mustContain(t, planForChroot(t, "flatpak"),
+		"arch-chroot /mnt sudo -iu adam -- flatpak --user remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo",
+		"arch-chroot /mnt sudo -iu adam -- flatpak --user install -y --noninteractive flathub com.spotify.Client",
 	)
 }
 
 func TestPlan_GrubTheme(t *testing.T) {
-	mustContain(t, planFor(t, Bootstrap, "grub-theme"),
+	// Runs wholly as root in the chroot (cloneBuildRoot) — install.sh has no inner sudo.
+	mustContain(t, planForChroot(t, "grub-theme"),
 		"git clone --depth 1 https://github.com/vinceliuice/grub2-themes",
-		"install.sh -t tela",
+		"./install.sh -t tela",
 	)
 }
 
 func TestPlan_Chezmoi(t *testing.T) {
-	// init or apply depending on host state; both mention the repo or 'chezmoi'.
-	mustContain(t, planFor(t, Bootstrap, "dotfiles"), "chezmoi")
+	// init or apply depending on chroot state; both mention 'chezmoi'.
+	mustContain(t, planForChroot(t, "dotfiles"), "chezmoi")
 }
 
 func TestPlan_Setup(t *testing.T) {
-	// Under --dry-run clones are always planned (host state is irrelevant) and the
-	// command runs verbatim through the shell. (~ is expanded.) The plan must also
-	// preserve the interleaved order the steps were written in.
-	home, _ := os.UserHomeDir()
-	plan := planFor(t, Bootstrap, "setup")
+	// Under --dry-run clones are always planned (state is irrelevant) and commands
+	// run verbatim through the shell, as the user inside the chroot. ~ resolves to
+	// the configured user's home (/home/adam), and the interleaved order is kept.
+	plan := planForChroot(t, "setup")
 	want := []string{
-		"git clone --depth 1 https://github.com/ohmyzsh/ohmyzsh " + filepath.Join(home, ".oh-my-zsh"),
-		"git clone --depth 1 https://github.com/Aloxaf/fzf-tab " + filepath.Join(home, ".oh-my-zsh/custom/plugins/fzf-tab"),
-		"sh: curl -sS https://starship.rs/install.sh | sh -s -- -y",
-		"git clone --depth 1 https://github.com/catppuccin/tmux " + filepath.Join(home, ".config/tmux/plugins/tmux"),
+		"arch-chroot /mnt sudo -iu adam -- git clone --depth 1 https://github.com/ohmyzsh/ohmyzsh /home/adam/.oh-my-zsh",
+		"arch-chroot /mnt sudo -iu adam -- git clone --depth 1 https://github.com/Aloxaf/fzf-tab /home/adam/.oh-my-zsh/custom/plugins/fzf-tab",
+		"sh: arch-chroot /mnt sudo -iu adam bash -c curl -sS https://starship.rs/install.sh | sh -s -- -y",
+		"arch-chroot /mnt sudo -iu adam -- git clone --depth 1 https://github.com/catppuccin/tmux /home/adam/.config/tmux/plugins/tmux",
 	}
 	if strings.Join(plan, "\n") != strings.Join(want, "\n") {
 		t.Errorf("setup plan mismatch.\ngot:\n%s\nwant:\n%s", strings.Join(plan, "\n"), strings.Join(want, "\n"))

From 4ee56978eed9307492834659fd128f175cd4e1d8 Mon Sep 17 00:00:00 2001
From: Adam Hall <adam.hall.1992@live.com>
Date: Tue, 30 Jun 2026 17:39:30 +0930
Subject: [PATCH 3/6] fix(install): skip Phase A customization when the chroot
 isn't open
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The customization stages run only inside the target chroot the mount stage
opens. For an encrypted layout mount skips the (unimplemented) LUKS remount, so
without a guard packages/flatpak/etc. would run against the LIVE ISO — e.g.
`pacman -S` into the ISO. Add requireChroot(): each customization stage no-ops
(with a warning) when ChrootRoot is unset (encrypted layout, or a stage run in
isolation without mount).

Also bump the vm-e2e Phase A install timeout 2400s->3600s: Phase A now carries
the package/flatpak/dotfiles/clone work that used to live in Phase B.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 internal/stages/dotfiles.go    |  3 +++
 internal/stages/flatpak.go     |  3 +++
 internal/stages/grubtheme.go   |  3 +++
 internal/stages/helpers.go     | 16 ++++++++++++++++
 internal/stages/kde.go         |  3 +++
 internal/stages/packages.go    |  3 +++
 internal/stages/services.go    |  3 +++
 internal/stages/setup.go       |  3 +++
 internal/stages/stages_test.go | 15 +++++++++++++++
 test/e2e/vm/e2e.py             |  4 ++--
 10 files changed, 54 insertions(+), 2 deletions(-)

diff --git a/internal/stages/dotfiles.go b/internal/stages/dotfiles.go
index 8895da2..a9923a9 100644
--- a/internal/stages/dotfiles.go
+++ b/internal/stages/dotfiles.go
@@ -30,6 +30,9 @@ func (dotfiles) effectiveManager(ctx *Context) string {
 }
 
 func (d dotfiles) Run(ctx *Context) error {
+	if !requireChroot(ctx, "dotfiles") {
+		return nil
+	}
 	manager := d.effectiveManager(ctx)
 	if manager == "none" {
 		ui.Warn("dotfiles.manager is none — skipping dotfiles")
diff --git a/internal/stages/flatpak.go b/internal/stages/flatpak.go
index 8d42fa8..e1ede48 100644
--- a/internal/stages/flatpak.go
+++ b/internal/stages/flatpak.go
@@ -19,6 +19,9 @@ func (flatpak) Name() string { return "flatpak" }
 func (flatpak) Phase() Phase { return Install }
 
 func (flatpak) Run(ctx *Context) error {
+	if !requireChroot(ctx, "flatpak") {
+		return nil
+	}
 	apps := ctx.Cfg.Flatpaks
 	if len(apps) == 0 {
 		ui.Warn("no flatpaks in config — skipping")
diff --git a/internal/stages/grubtheme.go b/internal/stages/grubtheme.go
index 0b35071..bb3d076 100644
--- a/internal/stages/grubtheme.go
+++ b/internal/stages/grubtheme.go
@@ -19,6 +19,9 @@ func (grubtheme) Name() string { return "grub-theme" }
 func (grubtheme) Phase() Phase { return Install }
 
 func (grubtheme) Run(ctx *Context) error {
+	if !requireChroot(ctx, "grub-theme") {
+		return nil
+	}
 	t := ctx.Cfg.GRUB.Theme
 	switch t.Source {
 	case "", "none":
diff --git a/internal/stages/helpers.go b/internal/stages/helpers.go
index 21bb8e1..07e792c 100644
--- a/internal/stages/helpers.go
+++ b/internal/stages/helpers.go
@@ -2,11 +2,27 @@ package stages
 
 import (
 	"fmt"
+
+	"github.com/AdamJHall/archwright/internal/ui"
 )
 
 // This file holds small helpers shared by the customization stages, collapsing
 // patterns that were duplicated across several stages.
 
+// requireChroot guards every Phase A customization stage: those stages only make
+// sense inside the target chroot the mount stage opens, so if it isn't open they
+// must no-op rather than run against the live ISO. The chroot is closed when the
+// layout is encrypted (mount skips the unimplemented LUKS remount) or when a
+// customization stage is run in isolation without the mount stage (e.g.
+// `install --only packages`). Returns true when it is safe to proceed.
+func requireChroot(ctx *Context, stage string) bool {
+	if ctx.R.ChrootRoot == "" {
+		ui.Warn(stage + ": Phase A chroot not open (encrypted layout, or run without the mount stage) — skipping")
+		return false
+	}
+	return true
+}
+
 // ensureTool installs pkg via pacman (--needed --noconfirm) when bin is not
 // already available. The probe (Runner.Has) is read-only and not recorded; it
 // checks the chroot target in Phase A and the host otherwise. Only the install
diff --git a/internal/stages/kde.go b/internal/stages/kde.go
index c536a4d..d435398 100644
--- a/internal/stages/kde.go
+++ b/internal/stages/kde.go
@@ -25,6 +25,9 @@ func (kde) Name() string { return "kde" }
 func (kde) Phase() Phase { return Install }
 
 func (kde) Run(ctx *Context) error {
+	if !requireChroot(ctx, "kde") {
+		return nil
+	}
 	if de := ctx.Cfg.Desktop.Environment; de != "" && de != "kde" {
 		ui.Info(fmt.Sprintf("desktop.environment is %q — skipping KDE stage", de))
 		return nil
diff --git a/internal/stages/packages.go b/internal/stages/packages.go
index 72e0bd6..86ebfb0 100644
--- a/internal/stages/packages.go
+++ b/internal/stages/packages.go
@@ -14,6 +14,9 @@ func (packages) Name() string { return "packages" }
 func (packages) Phase() Phase { return Install }
 
 func (packages) Run(ctx *Context) error {
+	if !requireChroot(ctx, "packages") {
+		return nil
+	}
 	pkgs := ctx.Cfg.Packages
 	if len(pkgs) == 0 {
 		ui.Warn("no packages in config — skipping")
diff --git a/internal/stages/services.go b/internal/stages/services.go
index bb3fab5..0f9080f 100644
--- a/internal/stages/services.go
+++ b/internal/stages/services.go
@@ -20,6 +20,9 @@ func (services) Name() string { return "services" }
 func (services) Phase() Phase { return Install }
 
 func (services) Run(ctx *Context) error {
+	if !requireChroot(ctx, "services") {
+		return nil
+	}
 	sys := ctx.Cfg.Services.Enable
 	usr := ctx.Cfg.Services.User
 	if len(sys) == 0 && len(usr) == 0 {
diff --git a/internal/stages/setup.go b/internal/stages/setup.go
index 6cc8f2e..f1580f4 100644
--- a/internal/stages/setup.go
+++ b/internal/stages/setup.go
@@ -23,6 +23,9 @@ func (setup) Name() string { return "setup" }
 func (setup) Phase() Phase { return Install }
 
 func (setup) Run(ctx *Context) error {
+	if !requireChroot(ctx, "setup") {
+		return nil
+	}
 	steps := ctx.Cfg.Setup.Steps
 	if len(steps) == 0 {
 		ui.Warn("no setup steps in config — skipping")
diff --git a/internal/stages/stages_test.go b/internal/stages/stages_test.go
index d0c8831..c7bd25b 100644
--- a/internal/stages/stages_test.go
+++ b/internal/stages/stages_test.go
@@ -239,6 +239,21 @@ func TestPlan_Packages(t *testing.T) {
 	)
 }
 
+// When the chroot isn't open (no ChrootRoot — the encrypted-layout case, where the
+// mount stage skips the LUKS remount), a customization stage must no-op rather than
+// run against the live ISO. Asserted on packages as the representative stage.
+func TestCustomization_SkipsWhenChrootNotOpen(t *testing.T) {
+	ss := For(Install, "packages")
+	r := &run.Runner{DryRun: true} // ChrootRoot unset: chroot not open
+	ctx := &Context{Cfg: testConfig(t), R: r, AssumeYes: true}
+	if err := ss[0].Run(ctx); err != nil {
+		t.Fatalf("packages should skip cleanly, got: %v", err)
+	}
+	if len(r.Plan) != 0 {
+		t.Errorf("packages must record nothing when the chroot is not open, got:\n%s", strings.Join(r.Plan, "\n"))
+	}
+}
+
 func TestPlan_AUR(t *testing.T) {
 	// aur stays in Phase B (makepkg can't run as root; needs a real user session).
 	mustContain(t, planFor(t, Bootstrap, "aur"),
diff --git a/test/e2e/vm/e2e.py b/test/e2e/vm/e2e.py
index 4054d40..4f9a0ea 100755
--- a/test/e2e/vm/e2e.py
+++ b/test/e2e/vm/e2e.py
@@ -504,8 +504,8 @@ def _run_descriptor(d: dict, keep: bool, phase_b_only: bool = False) -> bool:
         log("live ISO shell ready; staging binary + config")
         con.run_ok("cp /root/e2e/archwright /root/archwright && chmod +x /root/archwright", timeout=30)
         con.run_ok("cp /root/e2e/config.yaml /root/config.yaml", timeout=30)
-        log("running archwright install --yes (this pacstraps; minutes)")
-        rc = con.run("/root/archwright install --yes --config /root/config.yaml", timeout=2400)
+        log("running archwright install --yes (pacstrap + Phase A customization: packages, flatpaks, dotfiles, theming; many minutes)")
+        rc = con.run("/root/archwright install --yes --config /root/config.yaml", timeout=3600)
         if rc != 0:
             log(f"PHASE A FAILED: archwright install rc={rc} (see {serial_log})")
             return False

From 9682e43502ecdfc2ac9c6e4b3571b61e119edd36 Mon Sep 17 00:00:00 2001
From: Adam Hall <adam.hall.1992@live.com>
Date: Tue, 30 Jun 2026 17:54:03 +0930
Subject: [PATCH 4/6] test(e2e): inject local repo between two install passes
 for dotfiles
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The dotfiles stage moved into Phase A, so a descriptor's injected file:// source
repo must exist in the target home before that stage runs — but the harness used
to inject it in the Phase A→B window, after Phase A. Split the install for
inject_repo descriptors at the mount-stage boundary: pass 1 `--to mount` builds
the base system and leaves /mnt mounted, we inject the repo into the target home,
pass 2 `--from mount` runs the customization stages (mount is idempotent). Drop
the now-redundant inject from inject_phase_b.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 test/e2e/vm/configs/features-dotfiles.yaml |  7 ++--
 test/e2e/vm/e2e.py                         | 48 +++++++++++++++++++---
 2 files changed, 46 insertions(+), 9 deletions(-)

diff --git a/test/e2e/vm/configs/features-dotfiles.yaml b/test/e2e/vm/configs/features-dotfiles.yaml
index 7320c44..6ab5fff 100644
--- a/test/e2e/vm/configs/features-dotfiles.yaml
+++ b/test/e2e/vm/configs/features-dotfiles.yaml
@@ -1,7 +1,8 @@
-# e2e feature coverage: exercises the Phase B dotfiles stage — chezmoi
+# e2e feature coverage: exercises the Phase A dotfiles stage — chezmoi
 # `init --apply` from a tiny LOCAL repo the harness injects into the target
-# (file:///home/e2e/dots), so it's deterministic + offline (no large external
-# clone, no apply scripts that prompt/hang). The injected repo manages a single
+# (file:///home/e2e/dots) between the two install passes, so it's deterministic +
+# offline (no large external clone, no apply scripts that prompt/hang). The injected
+# repo manages a single
 # `dot_e2e-dotfile`, which chezmoi applies to ~/.e2e-dotfile — features.sh's
 # "dotfiles" token asserts that. Disk layout is the minimal single-disk LVM.
 system:
diff --git a/test/e2e/vm/e2e.py b/test/e2e/vm/e2e.py
index 4f9a0ea..764e36f 100755
--- a/test/e2e/vm/e2e.py
+++ b/test/e2e/vm/e2e.py
@@ -364,6 +364,43 @@ def _build_chezmoi_repo(path: str) -> None:
     subprocess.run(["git", "-C", path, "commit", "-q", "-m", "e2e dotfiles"], check=True, env=env)
 
 
+def run_install(con: Serial, d: dict) -> int:
+    """Run `archwright install --yes` on the live ISO and return its exit code.
+
+    Most descriptors are a single invocation. Descriptors that inject a local source
+    repo (e.g. the dotfiles chezmoi source) need that repo present in the *target*
+    home before the Phase A stage that consumes it runs — but the target filesystem
+    only exists once archinstall has run. So split the install at the `mount` stage
+    boundary: pass 1 (`--to mount`) installs the base system and opens the chroot,
+    leaving /mnt mounted; we inject the repo into the now-existing target home; pass 2
+    (`--from mount`) runs the customization stages through finalize (mount is
+    idempotent and re-opens the chroot in the second process)."""
+    base = "/root/archwright install --yes --config /root/config.yaml"
+    if not d.get("inject_repo"):
+        return con.run(base, timeout=3600)
+    log("inject_repo: two-pass install — pass 1 (--to mount: base system + open chroot)")
+    rc = con.run(f"{base} --to mount", timeout=3600)
+    if rc != 0:
+        return rc
+    inject_repo_into_target(con, d)
+    log("inject_repo: two-pass install — pass 2 (--from mount: customization + finalize)")
+    return con.run(f"{base} --from mount", timeout=3600)
+
+
+def inject_repo_into_target(con: Serial, d: dict) -> None:
+    """Copy the harness's local source repo into the target home so a Phase A stage
+    that consumes a file:// repo (dotfiles) resolves offline. Runs between the two
+    install passes: the target is still mounted at /mnt from pass 1, and the user's
+    home exists because archinstall created it. chown runs in the chroot — the live
+    ISO has no such user, only the target does."""
+    user = d["user"]
+    dest = f"/mnt{d['inject_repo']}"
+    log(f"injecting local repo into target at {dest}")
+    con.run_ok(f"mkdir -p \"$(dirname {dest})\"", timeout=30)
+    con.run_ok(f"cp -r /root/e2e/injectrepo {dest}", timeout=60)
+    con.run_ok(f"arch-chroot /mnt chown -R {user}:{user} /home/{user}", timeout=60)
+
+
 def inject_phase_b(con: Serial, d: dict) -> None:
     """As root on the live ISO (target remounted at /mnt), install the harness-only
     Phase-B autorun scaffold into the installed system. The run dir is shared
@@ -407,11 +444,10 @@ def inject_phase_b(con: Serial, d: dict) -> None:
     con.run_ok(f"cp /root/e2e/validate.sh {home}/e2e-validate.sh", timeout=30)
     con.run_ok(f"cp /root/e2e/expect.env {home}/expect.env", timeout=30)
     con.run_ok(f"cp /root/e2e/bash_profile {home}/.bash_profile", timeout=30)
-    # Inject the local chezmoi source repo (for the dotfiles descriptor) under the
-    # user's home so the configured file:// repo resolves offline.
-    if d.get("inject_repo"):
-        con.run_ok(f"cp -r /root/e2e/injectrepo /mnt{d['inject_repo']}", timeout=60)
-    # chown in the chroot — the live ISO has no such user; only the target does.
+    # The local chezmoi source repo (for the dotfiles descriptor) is injected earlier,
+    # between the two install passes (run_install/inject_repo_into_target), because the
+    # dotfiles stage that consumes it now runs in Phase A — not here in the Phase B
+    # window. chown in the chroot — the live ISO has no such user; only the target does.
     con.run_ok(f"arch-chroot /mnt chown -R {user}:{user} /home/{user}", timeout=60)
 
     # Best-effort: surface kernel/systemd boot on serial during the disk phase.
@@ -505,7 +541,7 @@ def _run_descriptor(d: dict, keep: bool, phase_b_only: bool = False) -> bool:
         con.run_ok("cp /root/e2e/archwright /root/archwright && chmod +x /root/archwright", timeout=30)
         con.run_ok("cp /root/e2e/config.yaml /root/config.yaml", timeout=30)
         log("running archwright install --yes (pacstrap + Phase A customization: packages, flatpaks, dotfiles, theming; many minutes)")
-        rc = con.run("/root/archwright install --yes --config /root/config.yaml", timeout=3600)
+        rc = run_install(con, d)
         if rc != 0:
             log(f"PHASE A FAILED: archwright install rc={rc} (see {serial_log})")
             return False

From b077a84fecaa7fc3abbe5811d58cd79a2cfd68b7 Mon Sep 17 00:00:00 2001
From: Adam Hall <adam.hall.1992@live.com>
Date: Sat, 4 Jul 2026 12:32:52 +0930
Subject: [PATCH 5/6] test(e2e): bump ISO_VERSION to 2026.07.01

Pin the QEMU smoke-test live ISO to the 2026.07.01 archive build, in
lockstep with the archinstall 4.4 bump.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 Taskfile.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Taskfile.yml b/Taskfile.yml
index b3150a2..c3e6845 100644
--- a/Taskfile.yml
+++ b/Taskfile.yml
@@ -14,7 +14,7 @@ vars:
   # Arch live ISO for the QEMU smoke test. Cached under the gitignored .iso/ dir
   # and pinned to a dated archive build so the download is reproducible. Bump
   # ISO_VERSION (CLI-overridable) in lockstep with the version in test/vm.sh.
-  ISO_VERSION: '{{.ISO_VERSION | default "2026.06.01"}}'
+  ISO_VERSION: '{{.ISO_VERSION | default "2026.07.01"}}'
   ISO_FILE: 'archlinux-{{.ISO_VERSION}}-x86_64.iso'
   ISO_PATH: '.iso/{{.ISO_FILE}}'
 

From 263b0eb0d6d31db6a1e97037fe26a45510805d94 Mon Sep 17 00:00:00 2001
From: Adam Hall <adam.hall.1992@live.com>
Date: Sat, 4 Jul 2026 12:32:52 +0930
Subject: [PATCH 6/6] fix(e2e): read ESP-mounted /boot via sudo in kernel-zen
 validation

The ESP is mounted at /boot with fmask=0077,dmask=0077 (archinstall's
secure default), so /boot is 0700 root:root. The feature validator runs
as the unprivileged e2e user, which can't traverse /boot, so
`[[ -e /boot/vmlinuz-linux-zen ]]` reported a present kernel image as
missing and failed kernel-zen. Read the kernel image + grub.cfg via
sudo instead. archwright's install was correct throughout; only the
test's permission assumption was wrong.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 test/e2e/vm/lib/features.sh | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/test/e2e/vm/lib/features.sh b/test/e2e/vm/lib/features.sh
index 3217675..ab7379f 100644
--- a/test/e2e/vm/lib/features.sh
+++ b/test/e2e/vm/lib/features.sh
@@ -37,11 +37,15 @@ for feat in $EXPECT_FEATURES; do
 			&& ok "mirrorlist generated by reflector" || fail "mirrorlist has no reflector header"
 		;;
 	kernel-zen)
-		[[ -e /boot/vmlinuz-linux-zen ]] && ok "linux-zen kernel image present" || fail "/boot/vmlinuz-linux-zen missing"
+		# The ESP is mounted at /boot with fmask=0077,dmask=0077 (archinstall's
+		# secure default), so /boot is 0700 root:root and this unprivileged
+		# validation user can't traverse it — read the kernel image + grub.cfg
+		# via sudo, or a present file reads as "missing".
+		sudo test -e /boot/vmlinuz-linux-zen && ok "linux-zen kernel image present" || fail "/boot/vmlinuz-linux-zen missing"
 		pacman -Q linux-zen >/dev/null 2>&1 && ok "linux-zen package installed" || fail "linux-zen not installed"
 		# kernel.default linux-zen -> grub default menuentry references it.
-		if [[ -f /boot/grub/grub.cfg ]]; then
-			grep -q 'linux-zen' /boot/grub/grub.cfg && ok "grub.cfg references linux-zen" || fail "grub.cfg has no linux-zen entry"
+		if sudo test -f /boot/grub/grub.cfg; then
+			sudo grep -q 'linux-zen' /boot/grub/grub.cfg && ok "grub.cfg references linux-zen" || fail "grub.cfg has no linux-zen entry"
 		fi
 		;;
 	plymouth)