M9.R.42.1: characterise the sgdisk + udev race via REPRO_DISK_DIAG

PHASE A of M9.R.42 — per the M9.R.41.13 close-out + user's standing
"diagnose before speculating on fixes" principle: instrument
disk_apply.nim with a kernel-state snapshot hook before proposing
ANY fix shape.

When REPRO_DISK_DIAG=<path> is set, applyDiskLayout appends a
labelled snapshot block to <path> around every sgdisk + partprobe
call.  Each block captures:
  - /proc/partitions
  - ls -la /dev/<diskBase>* (the partition device nodes)
  - ls /sys/class/block
  - ls /sys/block/<diskBase>/  + ../size
  - ls /dev/disk/by-partuuid
  - udevadm settle --timeout=10 + its exit code

The snapshots fire at six labelled boundaries per disk:
  before-table-<diskName>  / after-table-<diskName>
  before-sgdisk-n-<partName> / after-sgdisk-n-<partName>  (per part)
  before-partprobe-<diskName> / after-partprobe-<diskName>

This gives the M9.R.41.13 evidence audit the time-series of
kernel state needed to determine whether sgdisk's exit-4 false
alarm is:
  (a) udev hasn't drained when our validation runs       → fix: udevadm settle
  (b) sgdisk genuinely buggy in this kernel/virtio combo → fix: sfdisk swap
  (c) intermittent BLKRRPART race                        → fix: bounded retry

3 unit tests in t_m9r42_1_disk_diag_hook.nim pin the behaviour:
  1. diag OFF (env unset) → no file IO, hot path stays clean
  2. snapshotKernelState renders the label/device header + each
     "$ <cmd>" probe line
  3. diag ON wires through applyDiskLayout: every labelled
     before/after pair lands in the diag file (verified against
     a 2-partition fixture)

Existing t_m9r22b_1 + t_m9r22b_3 tests still pass.  This is
purely additive: no behavior change when REPRO_DISK_DIAG is
unset.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: zah

libs/repro_profile/src/repro_profile/disk_apply.nim

@@ -20,8 +20,16 @@
 ## All operations go through ``./disk_tools.nim`` so the apply path is
 ## uniformly dry-run-able (``REPRO_DISK_DRY_RUN=1``) and uniformly
 ## errors via ``DiskToolError``.
+##
+## M9.R.42.1: when ``REPRO_DISK_DIAG=<path>`` is set, a kernel-state
+## snapshot is appended to ``<path>`` around each sgdisk + partprobe
+## call so the udev/devtmpfs/sgdisk race the M9.R.41 close-out
+## documented can be characterised end-to-end on the live ISO. The
+## snapshot includes ``/proc/partitions``, ``ls /dev/<diskBase>*``,
+## ``ls /sys/class/block``, and an ``udevadm settle --timeout=10`` exit
+## code.
 
-import std/[algorithm, options, os, osproc, sequtils, strutils, tables]
+import std/[algorithm, options, os, osproc, sequtils, strutils, tables, times]
 
 import ./types
 import ./disk_tools
@@ -61,6 +69,82 @@ proc newApplyContext*(layout: DiskLayout;
 proc recordOperation(ctx: ApplyContext; ex: ExecResult) =
   ctx.result.operations.add ex
 
+# ---------------------------------------------------------------------
+# M9.R.42.1 — kernel-state diagnostic hook around sgdisk + partprobe.
+# ---------------------------------------------------------------------
+
+proc diagPath*(): string {.inline.} =
+  ## Returns the value of ``REPRO_DISK_DIAG`` or an empty string when
+  ## diagnostics are off. The env-var is read on every call so the
+  ## installer / test harness can flip it at runtime without restarting.
+  getEnv("REPRO_DISK_DIAG")
+
+proc diagAppend(text: string) =
+  ## Append ``text`` to the diag file. Best-effort: if writing fails
+  ## (e.g. the path is unwritable) we silently swallow — the diag
+  ## channel must never crash the apply driver, only inform.
+  let p = diagPath()
+  if p.len == 0: return
+  try:
+    let f = open(p, fmAppend)
+    defer: f.close()
+    f.write(text)
+  except CatchableError:
+    discard
+
+proc diagCmd(label, cmd: string): string =
+  ## Run ``cmd`` via ``execCmdEx``, capture stdout+stderr+exit, and
+  ## render a labelled block for the diag file. Never raises.
+  result = "  $ " & cmd & "\n"
+  try:
+    let pair = execCmdEx(cmd)
+    result.add "    [exit=" & $pair.exitCode & "]\n"
+    if pair.output.len > 0:
+      var lineCount = 0
+      for ln in pair.output.splitLines():
+        if lineCount >= 40:
+          result.add "    ... (truncated)\n"
+          break
+        result.add "    " & ln & "\n"
+        inc lineCount
+  except CatchableError as e:
+    result.add "    [exec-failed: " & e.msg & "]\n"
+
+proc snapshotKernelState*(label, device: string): string =
+  ## Render a labelled snapshot of /proc/partitions, /sys/class/block,
+  ## /dev/<diskBase>*, and the most recent udev/kobject events visible
+  ## to userspace. Returns the rendered block as a string. Called
+  ## twice around each sgdisk invocation (before + after) when
+  ## ``REPRO_DISK_DIAG`` is set so the time-series of kernel state can
+  ## be inspected post-mortem.
+  let ts = $now()
+  result = "\n=== M9.R.42.1 SNAPSHOT label=" & label & " device=" &
+    device & " ts=" & ts & " ===\n"
+  let base = extractFilename(device)
+  result.add diagCmd("cat /proc/partitions",
+    "cat /proc/partitions 2>&1")
+  result.add diagCmd("ls -la /dev/" & base & "*",
+    "ls -la /dev/" & base & "* 2>&1")
+  result.add diagCmd("ls /sys/class/block",
+    "ls /sys/class/block 2>&1")
+  result.add diagCmd("ls /sys/block/" & base & "/",
+    "ls /sys/block/" & base & "/ 2>&1")
+  result.add diagCmd("cat /sys/block/" & base & "/size",
+    "cat /sys/block/" & base & "/size 2>&1")
+  result.add diagCmd("ls /dev/disk/by-partuuid",
+    "ls /dev/disk/by-partuuid 2>&1")
+  # Force udev to drain its queue and report how long it took. If udev
+  # is the source of the /dev/<base>1 absence this exit will be non-
+  # zero or take a long time.
+  result.add diagCmd("udevadm settle --timeout=10 + status",
+    "udevadm settle --timeout=10 2>&1; echo settle-exit=$?")
+
+proc diagSnapshot*(label, device: string) =
+  ## Emit a labelled snapshot to ``REPRO_DISK_DIAG`` (if set). No-op
+  ## when diag is off — the apply-driver hot path stays clean.
+  if diagPath().len == 0: return
+  diagAppend(snapshotKernelState(label, device))
+
 # Forward declarations for the content-walker so applyDiskLayout can
 # call applyContentNode and applyContentNode can call its variants.
 proc applyContentNode*(ctx: ApplyContext; device, ctxKey: string;
@@ -124,6 +208,7 @@ proc applyDiskLayout*(layout: DiskLayout;
     # (which sgdisk supports via its MBR mode).
     for diskName, d in ctx.layout.disks:
       let tableKind = if d.`type`.len == 0: "gpt" else: d.`type`
+      diagSnapshot("before-table-" & diskName, d.device)
       if tableKind == "gpt":
         # `sgdisk -o` zaps any existing GPT and creates a fresh empty
         # GPT in one operation, which avoids the parted-then-sgdisk
@@ -133,6 +218,7 @@ proc applyDiskLayout*(layout: DiskLayout;
       else:
         # MBR path: parted is the right tool for the label.
         ctx.recordOperation(partedMklabel(d.device, tableKind))
+      diagSnapshot("after-table-" & diskName, d.device)
       var num = 1
       for pName, p in d.partitions:
         let gptType = gptTypeCodeFor(p.`type`)
@@ -148,16 +234,20 @@ proc applyDiskLayout*(layout: DiskLayout;
           # aligned sector); subsequent partitions start at "0"
           # which is sgdisk's "first available sector".
           "0"
+        diagSnapshot("before-sgdisk-n-" & pName, d.device)
         ctx.recordOperation(sgdiskCreatePartition(d.device, num,
           startArg, sizeArg, gptType, pName))
+        diagSnapshot("after-sgdisk-n-" & pName, d.device)
         if p.bootable:
           ctx.recordOperation(partedSetBootable(d.device, num, true))
         inc num
       # After writing partitions, ask the kernel to re-read the table
       # so /dev/<disk>pN show up for the mkfs / cryptsetup steps.
       if findExe("partprobe").len > 0:
+        diagSnapshot("before-partprobe-" & diskName, d.device)
         ctx.recordOperation(execTool("partprobe",
           @["partprobe", d.device]))
+        diagSnapshot("after-partprobe-" & diskName, d.device)
 
     # Step 5 + 6 + 7 + 8: walk each partition's content recursively.
     for diskName, d in ctx.layout.disks:

tests/unit/t_m9r42_1_disk_diag_hook.nim

@@ -0,0 +1,138 @@
+## M9.R.42.1 — pin the ``REPRO_DISK_DIAG`` kernel-state snapshot hook.
+##
+## Spec: ``recipes/reproos-iso/run-evidence/m9r41_complete.txt`` PHASE G
+## (the Phase 2 race characterisation handoff).
+##
+## The M9.R.41.13 close-out documented an sgdisk false-alarm + a
+## /dev/vda1 absence race on the M9.R.41 base-rootfs (Debian Trixie
+## kernel 6.12.86 + virtio-blk + systemd-udev 257.13).  M9.R.41.8-12
+## attempted 5 pragmatic workarounds (partprobe + sync, alignment,
+## explicit start sector, tolerate exit 4, retry the probe) and all
+## five were REVERTED because none actually closed the gap.
+##
+## M9.R.42.1 starts with characterisation BEFORE proposing a fix:
+## ``REPRO_DISK_DIAG=<path>`` causes ``disk_apply.nim`` to append a
+## kernel-state snapshot to ``<path>`` before AND after each sgdisk +
+## partprobe call.  The snapshot captures /proc/partitions, /dev/<base>*,
+## /sys/block, /dev/disk/by-partuuid, and an ``udevadm settle`` exit
+## so the time-series of state can be inspected post-mortem inside
+## the launcher diag tarball.
+##
+## This test pins:
+##   1. The diag hook is OFF when REPRO_DISK_DIAG is unset (the
+##      hot path stays clean — no file IO, no diag block emitted).
+##   2. The diag hook fires when REPRO_DISK_DIAG is set: the diag
+##      file is created + each labelled snapshot block lands.
+##   3. The ``snapshotKernelState`` renderer emits the expected
+##      label/device header + the ``$ <cmd>`` form per probe.
+
+import std/[os, strutils, tables, unittest]
+
+import repro_profile
+import repro_cli_support/disk as cli_disk
+
+const TmpRoot = "build/m9r42_1_tmp"
+
+proc resetDir(sub: string): string =
+  let dir = TmpRoot / sub
+  if dirExists(dir): removeDir(dir)
+  createDir(dir)
+  dir
+
+const FixtureSource = """
+import repro_profile
+
+hardware "01M9R42-DIAG":
+  cpu:
+    arch: "x86_64"
+  disko:
+    disks:
+      "main":
+        device: "/dev/loop99"
+        table: gpt
+        partitions:
+          "esp":
+            kind: esp
+            size: "512M"
+            bootable: true
+            content:
+              filesystem:
+                format: "vfat"
+                mountpoint: "/boot"
+          "root":
+            kind: linux
+            size: "100%"
+            content:
+              filesystem:
+                format: "ext4"
+                mountpoint: "/"
+"""
+
+suite "M9.R.42.1: disk-apply kernel-state diag hook":
+
+  setup:
+    putEnv("REPRO_DISK_DRY_RUN", "1")
+
+  teardown:
+    delEnv("REPRO_DISK_DRY_RUN")
+    delEnv("REPRO_DISK_DIAG")
+
+  test "Test#1: diag OFF when REPRO_DISK_DIAG unset (no file IO)":
+    delEnv("REPRO_DISK_DIAG")
+    check diagPath() == ""
+    # Calling diagSnapshot when off must not create any file.
+    let dir = resetDir("test1")
+    let probePath = dir / "should-not-exist.diag"
+    # Tactically point REPRO_DISK_DIAG at a path and unset it again to
+    # prove a stale env var doesn't leak.
+    putEnv("REPRO_DISK_DIAG", probePath)
+    delEnv("REPRO_DISK_DIAG")
+    diagSnapshot("test1-label", "/dev/loop99")
+    check not fileExists(probePath)
+
+  test "Test#2: snapshotKernelState renders label + device header":
+    # Pure-render test: the snapshot block is a string we can
+    # introspect even without a real /proc on Windows.
+    let s = snapshotKernelState("before-sgdisk-n-esp", "/dev/loop99")
+    check s.contains(
+      "=== M9.R.42.1 SNAPSHOT label=before-sgdisk-n-esp " &
+      "device=/dev/loop99 ts=")
+    # Each probe renders as a "$ <cmd>" line.
+    check s.contains("$ cat /proc/partitions 2>&1")
+    check s.contains("$ ls -la /dev/loop99* 2>&1")
+    check s.contains("$ ls /sys/class/block 2>&1")
+    check s.contains("$ udevadm settle --timeout=10 2>&1")
+
+  test "Test#3: diag ON wires through applyDiskLayout":
+    let dir = resetDir("test3")
+    let diagFile = dir / "diag.log"
+    putEnv("REPRO_DISK_DIAG", diagFile)
+    check diagPath() == diagFile
+    # Build a layout fixture via the source path the CLI uses.
+    let src = dir / "hardware.nim"
+    writeFile(src, FixtureSource)
+    # Drive the apply via the CLI under DRY_RUN so no real subprocess
+    # spawns, but the diag-hook calls still fire around each sgdisk +
+    # partprobe step.
+    let rc = runDiskCommand(@["apply", src, "--confirm"])
+    check rc == 0
+    # The diag file must exist and carry at least the snapshot block
+    # labels we wired in (one BEFORE + one AFTER for the gpt table,
+    # and one BEFORE + one AFTER for each partition + partprobe).
+    check fileExists(diagFile)
+    let body = readFile(diagFile)
+    check body.contains("label=before-table-main")
+    check body.contains("label=after-table-main")
+    check body.contains("label=before-sgdisk-n-esp")
+    check body.contains("label=after-sgdisk-n-esp")
+    check body.contains("label=before-sgdisk-n-root")
+    check body.contains("label=after-sgdisk-n-root")
+    # partprobe-around snapshots fire only when partprobe is in PATH;
+    # on the Windows test host findExe returns "" so we expect either
+    # both partprobe-snapshot blocks or neither — gate on
+    # before+after consistency.
+    let hasBeforePartprobe = body.contains(
+      "label=before-partprobe-main")
+    let hasAfterPartprobe = body.contains(
+      "label=after-partprobe-main")
+    check hasBeforePartprobe == hasAfterPartprobe