@rackbops/ac-agent 2.0.0-alpha.39 → 2.0.0-alpha.41

package/data/Get-ToolchainInventory.ps1

@@ -19,6 +19,17 @@
     git repo (artifacts-console/artifact-console/data) -- and, since #320, inside the
     installed package.
 
+    On a Linux side (WSL or an -SshTargets host) that has docker on PATH and can run
+    `docker ps`, also adds a Containers section (issue #721): every RUNNING container's
+    name, image reference, image digest, best-effort package list (dpkg/apk/rpm, or
+    "unknown" when none apply) and catalogued tools found on its own PATH (the same
+    catalog pass, run inside the container). Windows hosts never get this section --
+    no Docker on the Windows boxes today. Every docker call the probe makes is
+    READ-ONLY (`ps`, `inspect`, `exec` running only the package query and the catalog
+    pass) -- nothing here pulls, starts, stops, restarts or removes a container, and a
+    container that vanishes mid-probe is skipped or reported with unknown
+    packages/tools rather than failing the run.
+
 .PARAMETER IncludeEditors
     Also probe editors / IDEs (VS Code, Neovim, Vim, Emacs, Sublime, Helix).
     Off by default. To turn it on permanently, either pass this switch or flip
@@ -568,18 +579,34 @@ function New-ToolchainProbeScript {
     $tsvLines = $(foreach ($t in $Catalog) { "{0}`t{1}`t{2}" -f $t.Name, $t.Exe, ($t.Ver -join ' ') })
     $tsv = ($tsvLines -join "`n")
 
+    # The catalog-pass body (issue #721 decision 2): reused VERBATIM in two places below --
+    # once at top level for this host/side, and again (unchanged text) fed into each running
+    # container via `docker exec -i <id> bash -s` in the Containers block -- reuse, not a
+    # second catalog. A function, not inline, precisely so the SAME text can be dropped in
+    # both places via one `.Replace()` below. `known` is populated as a side effect (every
+    # catalog Exe name, found or not) for the uncatalogued-on-PATH scan further down the HOST
+    # script to reuse; it must already be `declare -A`'d by the CALLER -- a `declare` INSIDE
+    # this function would make it local and the later scan would see an empty array.
+    $catalogPassFn = @'
+catalog_pass() {
+  while IFS=$'\t' read -r name exe verargs; do
+    [ -z "$exe" ] && continue
+    known["$(printf '%s' "$exe" | tr 'A-Z' 'a-z')"]=1
+    loc=$(command -v "$exe" 2>/dev/null) || continue
+    case "$loc" in "${TOOLCHAIN_PROBE_INTEROP_PREFIX:-/mnt/}"*) continue;; esac   # skip Windows tools seen via interop
+    ver=$($exe $verargs 2>&1 | grep -m1 . | tr -d '\r')
+    printf '%s\t%s\t%s\n' "$name" "$ver" "$loc"
+  done
+}
+'@
+    $catalogPassFn = ($catalogPassFn -replace "`r`n", "`n").Trim("`n")
+
     $probeSh = @'
 #!/usr/bin/env bash
 interop="${TOOLCHAIN_PROBE_INTEROP_PREFIX:-/mnt/}"
+__CATALOG_PASS_FN__
 declare -A known
-while IFS=$'\t' read -r name exe verargs; do
-  [ -z "$exe" ] && continue
-  known["$(printf '%s' "$exe" | tr 'A-Z' 'a-z')"]=1
-  loc=$(command -v "$exe" 2>/dev/null) || continue
-  case "$loc" in "$interop"*) continue;; esac   # skip Windows tools seen via interop
-  ver=$($exe $verargs 2>&1 | grep -m1 . | tr -d '\r')
-  printf '%s\t%s\t%s\n' "$name" "$ver" "$loc"
-done <<'__CATALOG__'
+catalog_pass <<'__CATALOG__'
 __TSV__
 __CATALOG__
 echo "===GLOBALS==="
@@ -603,8 +630,126 @@ for d in "$HOME/.cargo/bin" "$gb" "$HOME/.local/bin" "$HOME/.dotnet/tools" /usr/
     printf '%s\t%s\n' "$b" "$f"
   done
 done | sort -u
+
+# Containers (issue #721): a running container's package list + catalogued tools, on a
+# Linux side only -- Windows never has docker on PATH here, so this whole block is inert
+# there. Emitted ONLY when docker is on PATH and `docker ps` itself succeeds, so an
+# absent/broken docker leaves NO ===CONTAINERS=== marker at all (decision 1: the sidecar
+# then carries no `containers` key) -- distinct from docker present with zero running
+# containers, which DOES print the marker with zero ===CONTAINER=== blocks (sidecar:
+# `containers: []`). Every docker verb below is read-only (ps, inspect, exec) -- decision
+# 4 -- and each container's failure is isolated from every other's (decision 3): `docker
+# inspect` failing (the container vanished between `ps` and here) skips that container
+# entirely, since decision 6 pins `imageId` as ALWAYS present and sha256-shaped, unlike
+# packages/tools, which have an explicit 'unknown' escape hatch.
+if command -v docker >/dev/null 2>&1 && docker ps >/dev/null 2>&1; then
+  echo "===CONTAINERS==="
+  # Process substitution (`< <(...)`), never `docker ps | while read`: this loop's body
+  # feeds heredocs to nested `docker exec -i ... bash -s` calls below, and a `| while`
+  # would redirect the LOOP's own stdin to the `docker ps` pipe -- ambiguous with heredoc
+  # parsing. Process substitution never touches this script's own stdin, so the nested
+  # heredocs (parsed once, at script-parse time, from the ORIGINAL stdin this whole probe
+  # arrived on) stay unambiguous no matter how many containers the loop iterates over.
+  mapfile -t __rb_containers < <(docker ps --no-trunc --format '{{.ID}}'$'\t''{{.Names}}'$'\t''{{.Image}}' 2>/dev/null)
+  for __rb_line in "${__rb_containers[@]}"; do
+    IFS=$'\t' read -r cid cname cimage <<< "$__rb_line"
+    [ -z "$cid" ] && continue
+    image_id=$(docker inspect -f '{{.Image}}' "$cid" 2>/dev/null)
+    [ -z "$image_id" ] && continue   # vanished between ps and inspect: skip, not an error
+    echo "===CONTAINER==="
+    printf '%s\t%s\t%s\n' "$cname" "$cimage" "$image_id"
+
+    # Packages: ONE exec, a three-way query with an exit-code sentinel for "none of the
+    # three" (decision 2). The chosen manager echoes a __PM_*__ marker as its own FIRST
+    # line before its listing, so the caller (below, on the HOST -- never inside the
+    # container) knows which format the rows are in without a second exec. dpkg-query's
+    # and rpm's own format strings already emit name<TAB>version; apk's `-v` output
+    # (`name-ver-rN`) is parsed into the same two-column shape OUTSIDE the container, on
+    # the host, by the sed pass below -- no sed dependency inside the target image. `\$`
+    # (not `$`) before dpkg's `${Package}`/`${Version}` placeholders: this whole query is
+    # single-quoted at the bash level (so THIS script's own shell never touches it), but
+    # `sh -c` still double-quote-parses its one argument, where a bare `$` would try (and
+    # fail) to expand an unset shell variable -- `\$` survives that parse as a literal `$`
+    # for dpkg-query itself to interpret. `\t`/`\n` are not recognised escapes inside
+    # POSIX double quotes, so they reach dpkg-query/rpm untouched, exactly as their own
+    # format-string escapes expect.
+    #
+    # `timeout 20` (round-1 review): a hung package manager inside ONE container (a wedged
+    # dpkg lock, a stuck apk network call despite -no-network commands being used here)
+    # would otherwise hang this exec indefinitely -- and with it the WHOLE remote probe,
+    # every OTHER container and every OTHER SSH target queued after it, since nothing
+    # upstream of this call bounds it. `timeout`'s own 124 exit on expiry is just another
+    # non-zero $pkg_rc to the existing check below -- no new branch, same 'unknown' outcome
+    # a real exec failure already gets.
+    pkg_out=$(timeout 20 docker exec "$cid" sh -c '
+      if command -v dpkg-query >/dev/null 2>&1; then
+        echo "__PM_DPKG__"
+        dpkg-query -W -f="\${Package}\t\${Version}\n" 2>/dev/null
+      elif command -v apk >/dev/null 2>&1; then
+        echo "__PM_APK__"
+        apk info -v 2>/dev/null
+      elif command -v rpm >/dev/null 2>&1; then
+        echo "__PM_RPM__"
+        rpm -qa --qf "%{NAME}\t%{VERSION}\n" 2>/dev/null
+      else
+        exit 7
+      fi
+    ' 2>/dev/null)
+    pkg_rc=$?
+    echo "===PACKAGES==="
+    if [ $pkg_rc -ne 0 ] || [ -z "$pkg_out" ]; then
+      echo "__UNKNOWN__"
+    else
+      pm_marker=$(printf '%s\n' "$pkg_out" | head -1)
+      case "$pm_marker" in
+        __PM_APK__)
+          # name-ver-rN -> name<TAB>version (decision 2): greedy backtracking on the first
+          # group finds the RIGHTMOST hyphen whose remainder looks like a version (starts
+          # with a digit, optionally followed by -rN), so a hyphenated package name (e.g.
+          # ca-certificates-20230506-r0 -> "ca-certificates" / "20230506-r0") splits
+          # correctly without a package database to consult.
+          echo "$pm_marker"
+          printf '%s\n' "$pkg_out" | tail -n +2 | sed -n 's/^\(.*\)-\([0-9][^-]*\(-r[0-9][0-9]*\)\{0,1\}\)$/\1\t\2/p'
+          ;;
+        __PM_DPKG__|__PM_RPM__)
+          printf '%s\n' "$pkg_out"
+          ;;
+        *)
+          echo "__UNKNOWN__"
+          ;;
+      esac
+    fi
+
+    # Tools: the SAME catalog pass, fed the SAME catalog TSV, run inside the container via
+    # `docker exec -i <id> bash -s` (decision 2). No separate "has bash" probe first (that
+    # would be a THIRD exec'd command, past decision 4's "packages query + catalog pass"
+    # allowance) -- a container with no bash just makes this `docker exec` itself fail,
+    # which the exit-code check below treats identically to "vanished" (decision 3:
+    # unknown, run continues). A zero-tools-found container (bash present, nothing on its
+    # PATH is catalogued) is NOT unknown -- exit 0 with empty stdout, kept distinct.
+    # `timeout 20` -- same round-1-review reasoning as the package query above: this pass
+    # runs the full catalog (~70 `command -v` + version-flag checks), so a single wedged
+    # tool inside one container must not be able to hang the whole remote probe.
+    tools_out=$(timeout 20 docker exec -i "$cid" bash -s 2>/dev/null <<'__RB_CONTAINER_PROBE__'
+__CATALOG_PASS_FN__
+declare -A known
+catalog_pass <<'__CATALOG__'
+__TSV__
+__CATALOG__
+__RB_CONTAINER_PROBE__
+)
+    tools_rc=$?
+    echo "===TOOLS==="
+    if [ $tools_rc -ne 0 ]; then
+      echo "__UNKNOWN__"
+    else
+      printf '%s\n' "$tools_out"
+    fi
+    echo "===CONTAINER_END==="
+  done
+fi
 '@
-    $probeSh = ($probeSh -replace "`r`n", "`n").Replace('__TSV__', $tsv)
+    $probeSh = ($probeSh -replace "`r`n", "`n").Replace('__CATALOG_PASS_FN__', $catalogPassFn).Replace('__TSV__', $tsv)
     return $probeSh
 }
 
@@ -623,10 +768,16 @@ function Invoke-ToolchainProbe {
 
 function ConvertFrom-ToolchainProbeOutput {
     <#
-    Parses one probe run's raw stdout into catalogued rows, the globals text and the
-    uncatalogued-tool list -- the `===GLOBALS===` / `===UNKNOWN===` sentinel split that
-    used to live inline in the WSL block. Same shapes as before: Rows carry
-    Cat/Name/Version/Path/Source (Source via Get-WslSource); Unknown carries Name/Path.
+    Parses one probe run's raw stdout into catalogued rows, the globals text, the
+    uncatalogued-tool list and (issue #721) the containers list -- the `===GLOBALS===` /
+    `===UNKNOWN===` / `===CONTAINERS===` sentinel split that used to live inline in the WSL
+    block. Same shapes as before: Rows carry Cat/Name/Version/Path/Source (Source via
+    Get-WslSource); Unknown carries Name/Path. `Containers` carries
+    Name/Image/ImageId/PackageManager/Packages/Tools (see ConvertFrom-ToolchainContainersOutput);
+    `ContainersReported` is $true only when a `===CONTAINERS===` marker appeared at all --
+    distinct from an empty `Containers` array, which can ALSO mean "no docker on this side"
+    (decision 1: the caller must tell those two apart to decide whether the sidecar carries
+    a `containers` key at all).
     #>
     param(
         [Parameter(Mandatory)][AllowEmptyString()][string]$Raw,
@@ -641,7 +792,12 @@ function ConvertFrom-ToolchainProbeOutput {
     $rest = if ($g.Count -gt 1) { $g[1] } else { '' }
     $u = $rest -split '===UNKNOWN==='
     $globalsText = $u[0].Trim()
-    $unknownOut = if ($u.Count -gt 1) { $u[1] } else { '' }
+    $afterUnknown = if ($u.Count -gt 1) { $u[1] } else { '' }
+
+    $c = $afterUnknown -split '===CONTAINERS==='
+    $unknownOut = $c[0]
+    $containersReported = $c.Count -gt 1
+    $containersOut = if ($containersReported) { $c[1] } else { '' }
 
     foreach ($line in ($toolOut -split "`n")) {
         if (-not $line.Trim()) { continue }
@@ -662,7 +818,117 @@ function ConvertFrom-ToolchainProbeOutput {
         $unknown += @{ Name = $p[0].Trim(); Path = $p[1].Trim() }
     }
 
-    return @{ Rows = @($rows); GlobalsText = $globalsText; Unknown = @($unknown) }
+    $containers = if ($containersReported) { ConvertFrom-ToolchainContainersOutput -Raw $containersOut -Catalog $Catalog } else { @() }
+
+    return @{
+        Rows = @($rows); GlobalsText = $globalsText; Unknown = @($unknown)
+        Containers = @($containers); ContainersReported = $containersReported
+    }
+}
+
+function ConvertFrom-ToolchainContainerPackages([string]$Raw) {
+    <#
+    The `===PACKAGES===` block for ONE container -> @{ PackageManager; Packages }.
+    PackageManager is 'dpkg' | 'apk' | 'rpm' | 'unknown' (decision 6); Packages is the
+    string 'unknown' (mirroring PackageManager) or an array of @{Name;Version}. The probe
+    script (New-ToolchainProbeScript) already normalises apk's `name-ver-rN` into
+    name<TAB>version on the host side, so every known manager's rows share one shape here.
+    #>
+    $lines = @($Raw -split "`n" | Where-Object { $_.Trim() -ne '' })
+    if (-not $lines.Count -or $lines[0].Trim() -eq '__UNKNOWN__') {
+        return @{ PackageManager = 'unknown'; Packages = 'unknown' }
+    }
+    $pm = switch ($lines[0].Trim()) {
+        '__PM_DPKG__' { 'dpkg' }
+        '__PM_APK__'  { 'apk' }
+        '__PM_RPM__'  { 'rpm' }
+        default       { $null }
+    }
+    if (-not $pm) { return @{ PackageManager = 'unknown'; Packages = 'unknown' } }
+    $out = @()
+    foreach ($line in ($lines | Select-Object -Skip 1)) {
+        $p = $line -split "`t", 2
+        if ($p.Count -lt 2) { continue }
+        $out += @{ Name = $p[0].Trim(); Version = $p[1].Trim() }
+    }
+    # No leading comma here, unlike this file's other ConvertTo-*/ConvertFrom-* functions'
+    # OWN bare `return , @(...)`: THIS array is a plain hashtable-literal VALUE, not itself
+    # the function's top-level return -- PowerShell's auto-unwrap-a-single-element-stream
+    # quirk (what the comma trick compensates for) only fires at a function-call boundary,
+    # and constructing @($out) directly inside a `return @{ ... }` hashtable literal is not
+    # one -- confirmed by this file's OWN `return @{ Rows = @($rows); ... }` a few functions
+    # up, which uses no comma at this exact same position. A leading comma here double-wraps
+    # into an array-of-one-array instead (caught in review: Packages came back as
+    # `[[{...}]]`).
+    return @{ PackageManager = $pm; Packages = @($out) }
+}
+
+function ConvertFrom-ToolchainContainerTools {
+    <#
+    The `===TOOLS===` block for ONE container -> the string 'unknown' (no bash in the
+    container, decision 3) or an array shaped exactly like ConvertFrom-ToolchainProbeOutput's
+    own Rows (Cat/Name/Version/Path/Source, matched against -Catalog) -- the SAME catalog
+    pass, so a container's catalogued tools carry the same category/refLinks-ready Name the
+    rest of the report does. `Source` is always '' here (Get-WslSource's heuristics are
+    host-filesystem-shaped, e.g. WSL mount prefixes -- meaningless for a container's own
+    rootfs), matching ConvertTo-ToolchainSidecarTools's own '(present)'/'' fallbacks.
+    #>
+    param([string]$Raw, [array]$Catalog)
+    $lines = @($Raw -split "`n" | Where-Object { $_.Trim() -ne '' })
+    if (-not $lines.Count -or $lines[0].Trim() -eq '__UNKNOWN__') { return 'unknown' }
+    $out = @()
+    foreach ($line in $lines) {
+        $parts = $line -split "`t"
+        if ($parts.Count -lt 3) { continue }
+        $tname = $parts[0].Trim(); $ver = Get-CleanVersion $parts[1]; $loc = $parts[2].Trim()
+        $catEntry = $Catalog | Where-Object { $_.Name -eq $tname } | Select-Object -First 1
+        if (-not $catEntry) { continue }
+        $out += @{ Cat = $catEntry.Cat; Name = $tname; Version = $ver; Path = $loc; Source = '' }
+    }
+    return , @($out)
+}
+
+function ConvertFrom-ToolchainContainersOutput {
+    <#
+    Parses the `===CONTAINERS===` block (issue #721) into an array of container hashtables:
+    @{ Name; Image; ImageId; PackageManager; Packages; Tools }. One `===CONTAINER===` block
+    per running container; a container whose `docker inspect` failed between `ps` and the
+    probe reaching it is never emitted at all (skipped upstream, in bash) rather than
+    reported with a missing/invalid ImageId -- decision 6 pins the digest as ALWAYS present
+    and sha256-shaped, unlike Packages/Tools, which have an explicit 'unknown' escape hatch.
+    #>
+    param(
+        [Parameter(Mandatory)][AllowEmptyString()][string]$Raw,
+        [Parameter(Mandatory)][array]$Catalog
+    )
+
+    $out = @()
+    $blocks = $Raw -split '===CONTAINER==='
+    foreach ($block in $blocks) {
+        if (-not $block.Trim()) { continue }
+
+        $afterHeader = $block -split '===PACKAGES==='
+        if ($afterHeader.Count -lt 2) { continue }
+        $headerLine = ($afterHeader[0] -split "`n" | Where-Object { $_.Trim() -ne '' } | Select-Object -First 1)
+        if (-not $headerLine) { continue }
+        $hp = $headerLine -split "`t"
+        if ($hp.Count -lt 3) { continue }
+        $name = $hp[0].Trim(); $image = $hp[1].Trim(); $imageId = $hp[2].Trim()
+
+        $afterPackages = $afterHeader[1] -split '===TOOLS==='
+        $packagesRaw = $afterPackages[0]
+        $toolsSection = if ($afterPackages.Count -gt 1) { $afterPackages[1] } else { '' }
+        $toolsRaw = ($toolsSection -split '===CONTAINER_END===')[0]
+
+        $pkgResult = ConvertFrom-ToolchainContainerPackages $packagesRaw
+        $tools = ConvertFrom-ToolchainContainerTools -Raw $toolsRaw -Catalog $Catalog
+
+        $out += @{
+            Name = $name; Image = $image; ImageId = $imageId
+            PackageManager = $pkgResult.PackageManager; Packages = $pkgResult.Packages; Tools = $tools
+        }
+    }
+    return , @($out)
 }
 
 # Change detection: ignore only the volatile _Generated: line, so a no-change run does not
@@ -780,6 +1046,109 @@ function ConvertTo-ToolchainSidecarUnknown($items) {
     return , @($out)
 }
 
+function ConvertTo-ToolchainSidecarContainers($containers) {
+    <#
+    Container list (Name/Image/ImageId/PackageManager/Packages/Tools) -> the sidecar's
+    top-level `containers` array (issue #721 decision 6): {name, image, imageId,
+    packageManager, packages, tools}. `packages`/`tools` are each either the literal
+    string 'unknown' or a list -- `packages` of {name, version}, `tools` of the SAME shape
+    ConvertTo-ToolchainSidecarTools's own `tools` entries use (name/category/version/path/
+    source), so a container's catalogued tools round-trip through the identical field set
+    the per-side tools already carry. `containers` is its OWN top-level key, not nested
+    under any side, since a container isn't scoped to "windows"/"wsl:<distro>"/"linux" the
+    way a side is -- it's a fact about the host as a whole.
+    #>
+    $out = @()
+    foreach ($c in $containers) {
+        $packagesOut = if ($c.Packages -eq 'unknown') { 'unknown' } else {
+            , @($c.Packages | ForEach-Object { [ordered]@{ name = $_.Name; version = $_.Version } })
+        }
+        $toolsOut = if ($c.Tools -eq 'unknown') { 'unknown' } else {
+            , @($c.Tools | ForEach-Object {
+                $ver = if ($_.Version) { $_.Version } else { '(present)' }
+                [ordered]@{ name = $_.Name; category = $_.Cat; version = $ver; path = $_.Path; source = $(if ($_.Source) { $_.Source } else { '' }) }
+            })
+        }
+        $out += [ordered]@{
+            name           = $c.Name
+            image          = $c.Image
+            imageId        = $c.ImageId
+            packageManager = $c.PackageManager
+            packages       = $packagesOut
+            tools          = $toolsOut
+        }
+    }
+    return , @($out)
+}
+
+function Format-ContainersSection {
+    <#
+    Renders the #721 `## Containers` section: one summary table (name, image, image ID --
+    the first 12 hex chars after `sha256:` -- package manager, package count and tools
+    found), then one `<details><summary>container name</summary>` block per container
+    holding its full package table (name, version) and catalogued-tools table. Full lists
+    stay in the Markdown, not sidecar-only: Publish-ToolchainReport's change detection
+    compares the .md text (ignoring only `_Generated:`), and the sidecar is rewritten only
+    when the .md changed or was missing -- a sidecar-only package list would freeze the
+    moment the .md stopped changing for an unrelated reason (the #721 plan's own caught
+    trap). Called only when the probe actually reported a Containers section (docker was on
+    PATH and `docker ps` succeeded) -- an empty array still renders the "_none running_"
+    line, distinct from the caller skipping this function entirely (no docker at all).
+    #>
+    param([array]$Containers)
+
+    $sb = New-Object System.Text.StringBuilder
+    [void]$sb.AppendLine('## Containers')
+    [void]$sb.AppendLine('')
+    if (-not $Containers -or $Containers.Count -eq 0) {
+        [void]$sb.AppendLine('_none running_')
+        [void]$sb.AppendLine('')
+        return $sb.ToString()
+    }
+
+    [void]$sb.AppendLine('| Name | Image | Image ID | Package manager | Packages | Tools |')
+    [void]$sb.AppendLine('|------|-------|----------|------------------|----------|-------|')
+    foreach ($c in ($Containers | Sort-Object Name)) {
+        $shortId = if ($c.ImageId -match '^sha256:(.{12})') { $Matches[1] } else { $c.ImageId }
+        $pkgCount = if ($c.Packages -eq 'unknown') { 'unknown' } else { "$(@($c.Packages).Count)" }
+        $toolCount = if ($c.Tools -eq 'unknown') { 'unknown' } else { "$(@($c.Tools).Count)" }
+        [void]$sb.AppendLine("| $($c.Name) | ``$($c.Image)`` | ``$shortId`` | $($c.PackageManager) | $pkgCount | $toolCount |")
+    }
+    [void]$sb.AppendLine('')
+
+    foreach ($c in ($Containers | Sort-Object Name)) {
+        [void]$sb.AppendLine("<details><summary>$($c.Name)</summary>")
+        [void]$sb.AppendLine('')
+        if ($c.Packages -eq 'unknown') {
+            [void]$sb.AppendLine('_packages: unknown (no dpkg/apk/rpm found)_')
+        } elseif (@($c.Packages).Count -eq 0) {
+            [void]$sb.AppendLine('_no packages reported_')
+        } else {
+            [void]$sb.AppendLine('| Package | Version |')
+            [void]$sb.AppendLine('|---------|---------|')
+            foreach ($p in ($c.Packages | Sort-Object Name)) {
+                [void]$sb.AppendLine("| $($p.Name) | $($p.Version) |")
+            }
+        }
+        [void]$sb.AppendLine('')
+        if ($c.Tools -eq 'unknown') {
+            [void]$sb.AppendLine('_tools: unknown (no bash in the container)_')
+        } elseif (@($c.Tools).Count -eq 0) {
+            [void]$sb.AppendLine('_no catalogued tools found_')
+        } else {
+            [void]$sb.AppendLine('| Tool | Version | Path |')
+            [void]$sb.AppendLine('|------|---------|------|')
+            foreach ($t in ($c.Tools | Sort-Object Name)) {
+                [void]$sb.AppendLine("| $($t.Name) | $($t.Version) | ``$($t.Path)`` |")
+            }
+        }
+        [void]$sb.AppendLine('')
+        [void]$sb.AppendLine('</details>')
+        [void]$sb.AppendLine('')
+    }
+    return $sb.ToString()
+}
+
 function New-ToolchainReport {
     <#
     Assembles ONE report's full Markdown text AND its JSON sidecar (#716, TC-4) from the
@@ -804,6 +1173,16 @@ function New-ToolchainReport {
     (`hostname`); -Os is 'windows' or 'linux'; -GeneratedIso is the run's UTC timestamp,
     second precision, e.g. '2026-09-15T14:02:11Z' (the sidecar's `generated` -- distinct
     from -Now, the local-time display string the Markdown's `_Generated:` line uses).
+
+    -Containers / -ContainersReported (issue #721) are REPORT-level, not per-Side: a
+    container isn't scoped to one side's identity the way tools/uncatalogued are, so a
+    `## Containers` section (Format-ContainersSection) renders once, after every -Sides
+    entry, and the sidecar's `containers` key is added once, top-level -- only when
+    -ContainersReported is $true (docker was on PATH and `docker ps` succeeded on
+    whichever side actually ran the bash probe). -ContainersReported $false must NOT add
+    the key at all, even with -Containers empty -- that is how a host/side with no docker
+    stays indistinguishable from before this feature (no `containers` key), while docker
+    present with zero running containers still gets `containers: []`.
     #>
     param(
         [Parameter(Mandatory)][string]$HostLabel,
@@ -815,7 +1194,9 @@ function New-ToolchainReport {
         [Parameter(Mandatory)][string]$HostId,
         [Parameter(Mandatory)][string]$Hostname,
         [Parameter(Mandatory)][ValidateSet('windows', 'linux')][string]$Os,
-        [Parameter(Mandatory)][string]$GeneratedIso
+        [Parameter(Mandatory)][string]$GeneratedIso,
+        [array]$Containers = @(),
+        [bool]$ContainersReported = $false
     )
 
     $md = New-Object System.Text.StringBuilder
@@ -847,6 +1228,9 @@ function New-ToolchainReport {
             uncatalogued = (ConvertTo-ToolchainSidecarUnknown $side.Unknown)
         }
     }
+    if ($ContainersReported) {
+        [void]$md.Append((Format-ContainersSection $Containers))
+    }
     $sidecar = [ordered]@{
         schemaVersion = 1
         host          = $HostId
@@ -855,6 +1239,9 @@ function New-ToolchainReport {
         generated     = $GeneratedIso
         sides         = @($sidecarSides)
     }
+    if ($ContainersReported) {
+        $sidecar['containers'] = (ConvertTo-ToolchainSidecarContainers $Containers)
+    }
     return @{
         Markdown = ($md.ToString() -replace "`r`n", "`n")
         Sidecar  = $sidecar
@@ -995,9 +1382,25 @@ function Resolve-ToolchainSshExe {
     optional feature shipped in-box) over whatever `ssh` a `Get-Command` search turns up,
     for the same reason Register-InventoryTask.ps1 resolves pwsh explicitly rather than
     trusting PATH.
+
+    `$env:SystemRoot` is skipped entirely when it's null/empty (issue #636 review round
+    2: `Join-Path $null ...` throws "Cannot bind argument to parameter 'Path'", which
+    this function did unguarded before this fix, real on Linux where SystemRoot is never
+    set. This script is Windows/WSL-shaped throughout and every env var it reads
+    (SystemRoot here, LOCALAPPDATA/USERPROFILE/APPDATA elsewhere) is real in production,
+    so this guard changes nothing on an actual Windows box -- it was added because this
+    function was reached by a cross-platform test (the tools-site push, #636), the first
+    thing in this file to call this function outside a fake -Transport/-SshExe. That test
+    was retired with the push itself (Rackbops/Tooling#667 C3); the guard stays since
+    it's still correct and free. The other env reads in this script are NOT similarly
+    guarded (LOCALAPPDATA in $stateDir, USERPROFILE/APPDATA in Get-UncataloguedWin) --
+    fixing those is out of scope here since nothing currently reaches them from a
+    non-Windows test either.
     #>
-    $sshExe = Join-Path $env:SystemRoot 'System32\OpenSSH\ssh.exe'
-    if (Test-Path -LiteralPath $sshExe) { return $sshExe }
+    if ($env:SystemRoot) {
+        $sshExe = Join-Path $env:SystemRoot 'System32\OpenSSH\ssh.exe'
+        if (Test-Path -LiteralPath $sshExe) { return $sshExe }
+    }
     $cmd = Get-Command ssh -ErrorAction SilentlyContinue
     if ($cmd) { return $cmd.Source }
     return $null
@@ -1128,6 +1531,13 @@ function Invoke-RemoteToolchainInventory {
     single-`linux`-side report, and published under `-Label '<alias>: '`. A failure at any
     step for one target is caught, printed as `! <alias>: unreachable (<reason>)`, and does
     NOT stop the loop -- the local report and every other target still publish.
+
+    Returns `{Written, Unchanged, Failed, RenderFailed, ExitCode}`. `RenderFailed` is the
+    subset of `Failed` whose underlying `Publish-ToolchainReport` result was specifically
+    `'render-failed'`, not a genuinely unreachable host -- the report DID reach the store
+    even though build.py's render/land step failed. Kept as its own bucket for diagnostic
+    value even though the one consumer that needed the distinction (the tools-site
+    page-data push's change detection) was retired in Rackbops/Tooling#667, E2/C3.
     #>
     param(
         [Parameter(Mandatory)][array]$Targets,
@@ -1141,6 +1551,7 @@ function Invoke-RemoteToolchainInventory {
     $written = @()
     $unchanged = @()
     $failed = @()
+    $renderFailed = @()
 
     foreach ($pair in $Targets) {
         $alias, $target = $pair
@@ -1161,7 +1572,8 @@ function Invoke-RemoteToolchainInventory {
             }
             $report = New-ToolchainReport -HostLabel "$remoteHostName ($alias)" `
                 -GeneratedOn "$remoteHostName via ssh from $LocalHost" -Now $Now -Sides @($side) `
-                -HostId $alias -Hostname $remoteHostName -Os 'linux' -GeneratedIso $NowIso
+                -HostId $alias -Hostname $remoteHostName -Os 'linux' -GeneratedIso $NowIso `
+                -Containers $parsed.Containers -ContainersReported $parsed.ContainersReported
 
             $remoteFileName = "toolchain-inventory-$alias.md"
             $remoteOutPath = if ($storeAvailable) { Join-Path $storeDir $remoteFileName } else { Join-Path $stateDir $remoteFileName }
@@ -1171,10 +1583,17 @@ function Invoke-RemoteToolchainInventory {
                 -Sidecar $report.Sidecar -Rel $remoteRel -Label "${alias}: " -NoRender:$NoRender
             # 'render-failed' (build.py exited non-zero) is isolated exactly like an
             # unreachable host: the report DID reach the store, but is not counted as a
-            # clean success, and this alias must not stop the loop for the others.
+            # clean success, and this alias must not stop the loop for the others. It
+            # still joins $failed (every existing caller's "not a clean success" meaning
+            # is unchanged) but ALSO its own $renderFailed bucket, because unlike a
+            # genuinely unreachable host it DID just write a fresh sidecar to the store --
+            # kept as diagnostic detail (see this function's own docstring).
             if ($result -eq 'written') { $written += $alias }
             elseif ($result -eq 'unchanged') { $unchanged += $alias }
-            else { $failed += $alias }
+            else {
+                $failed += $alias
+                if ($result -eq 'render-failed') { $renderFailed += $alias }
+            }
         } catch {
             Write-Host "! ${alias}: unreachable ($($_.Exception.Message))" -ForegroundColor Yellow
             $failed += $alias
@@ -1182,10 +1601,11 @@ function Invoke-RemoteToolchainInventory {
     }
 
     return @{
-        Written   = $written
-        Unchanged = $unchanged
-        Failed    = $failed
-        ExitCode  = $(if ($failed.Count -gt 0) { 2 } else { 0 })
+        Written      = $written
+        Unchanged    = $unchanged
+        Failed       = $failed
+        RenderFailed = $renderFailed
+        ExitCode     = $(if ($failed.Count -gt 0) { 2 } else { 0 })
     }
 }
 
@@ -1258,6 +1678,8 @@ if ($MyInvocation.InvocationName -ne '.') {
     $wslRows = @()
     $wslGlobalsText = ''
     $wslUnknown = @()
+    $wslContainers = @()
+    $wslContainersReported = $false
     $wslAvailable = $false
     if ($WslDistro) {
         $wslExe = Get-Command wsl.exe -ErrorAction SilentlyContinue
@@ -1291,6 +1713,8 @@ if ($MyInvocation.InvocationName -ne '.') {
                 $wslRows = $parsed.Rows
                 $wslGlobalsText = $parsed.GlobalsText
                 $wslUnknown = $parsed.Unknown
+                $wslContainers = $parsed.Containers
+                $wslContainersReported = $parsed.ContainersReported
                 foreach ($r in $wslRows) { Write-Host ("  + {0,-16} {1}" -f $r.Name, $r.Version) }
                 if ($wslUnknown.Count) { Write-Host ("  ~ {0} uncatalogued on PATH" -f $wslUnknown.Count) -ForegroundColor DarkYellow }
             } else {
@@ -1321,7 +1745,8 @@ if ($MyInvocation.InvocationName -ne '.') {
         -GeneratedOn "$hostName (editors: $(if($includeEd){'included'}else{'excluded'}))" -Now $now `
         -SummaryLine "**Windows:** $($winRows.Count) tools &middot; **$wslCountLabel**" `
         -HistoryRel "$ArtifactCategory/$fileName" -Sides $sides `
-        -HostId $machine -Hostname $hostName -Os 'windows' -GeneratedIso $nowIso
+        -HostId $machine -Hostname $hostName -Os 'windows' -GeneratedIso $nowIso `
+        -Containers $wslContainers -ContainersReported $wslContainersReported
     $mdText = $localReport.Markdown
 
     # Always record the last run time (out-of-repo state, untracked).
@@ -1388,7 +1813,11 @@ if ($MyInvocation.InvocationName -ne '.') {
     # A remote failure (2) outranks a local-only render failure (1, the pre-#715 behaviour
     # of exiting non-zero when build.py fails) -- both are folded in HERE, after SSH
     # probing has already run to completion, never as an early `exit` from inside
-    # Publish-ToolchainReport (which would abort probing before it started).
+    # Publish-ToolchainReport (which would abort probing before it started). The ranking
+    # only decides what this run's Last Result shows, not whether work happened. (Exit
+    # code 3 was the tools-site page-data push's failure signal, retired along with the
+    # push itself -- Rackbops/Tooling#667, E2/C3 -- now that the page reads the store
+    # directly; 1 and 2 keep their pre-existing meanings unchanged.)
     $exitCode = 0
     if ($localResult -eq 'render-failed') { $exitCode = 1 }
     if ($sshTargetsAllMalformed) { $exitCode = 2 }