firmwareloop 0.0.8__py3-none-any.whl

tools/reset.ps1

@@ -0,0 +1,141 @@
+<#
+.SYNOPSIS
+    DUT reset (Spec §26 M2). Preferred backend is Agentic HIL; the
+    simulator backend is a no-op acknowledgement (the HIL harness owns the
+    simulated DUT process and resets it in-test).
+
+    Usage:
+        .\tools\reset.ps1 -Backend simulator -Json
+        .\tools\reset.ps1 -Backend agentic-hil -Json
+
+    Exit codes: 0 ok, 1 backend failure, 2 config/identity error.
+#>
+[CmdletBinding()]
+param(
+    [ValidateSet('simulator', 'agentic-hil', 'openocd', 'vendor')]
+    [string]$Backend = 'simulator',
+    [string]$ExpectedTarget,          # verify probe identity before reset (Spec §9)
+    [switch]$Json
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+Import-Module (Join-Path $PSScriptRoot 'common\fw.psm1') -Force
+
+$repoRoot = Get-FwRepoRoot
+
+function Exit-WithError {
+    param([string]$Class, [string]$Message, [string]$Detail)
+    $body = New-FwError -ErrorClass $Class -Message $Message -Detail $Detail
+    if ($Json) { Write-FwJson $body -Compact } else { Write-FwJson $body; Write-Error "$Class : $Message" -ErrorAction Continue }
+    exit 2
+}
+
+$stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
+$logFile = Join-Path $repoRoot "artifacts\logs\reset-$stamp.log"
+New-Item -ItemType Directory -Force -Path (Split-Path $logFile) | Out-Null
+
+switch ($Backend) {
+    'simulator' {
+        Save-FwLog -Path $logFile -Content "simulator backend: reset is managed by the HIL harness (pytest conftest SimulatedDut.reset)."
+        $result = [ordered]@{
+            schema      = 'firmware-reset-result/v1'
+            ok          = $true
+            backend     = 'simulator'
+            target      = 'simulated-dut'
+            log         = (Resolve-Path -LiteralPath $logFile).Path
+            generated_at = Get-FwTimestamp
+        }
+        if ($Json) { Write-FwJson ([pscustomobject]$result) -Compact } else { Write-FwJson ([pscustomobject]$result) }
+        exit 0
+    }
+    'pyocd' {
+        $pyocdExe = Join-Path $repoRoot '.venv\Scripts\pyocd.exe'
+        if (-not (Test-Path -LiteralPath $pyocdExe)) {
+            $cmd = Get-Command pyocd -ErrorAction SilentlyContinue
+            if ($cmd) { $pyocdExe = $cmd.Source }
+        }
+        if (-not (Test-Path -LiteralPath $pyocdExe)) {
+            Exit-WithError -Class 'TOOLCHAIN_NOT_FOUND' -Message 'pyocd 未找到。请在 Python 环境中安装 pyocd (`uv pip install pyocd`)。' -Detail 'pyOCD 用于通过 ST-LINK / CMSIS-DAP 复位芯片。'
+        }
+        $targetChip = if ($ExpectedTarget) { $ExpectedTarget } else { 'stm32f103rc' }
+        $res = Invoke-FwProcess -FilePath $pyocdExe -Arguments @('reset', '-t', $targetChip.ToLowerInvariant()) -WorkingDirectory $repoRoot -TimeoutMs 30000 -StdoutFile $logFile
+        if ($res.timed_out) {
+            Exit-WithError -Class 'TIMEOUT' -Message 'pyocd 芯片复位超时。' -Detail $logFile
+        }
+        if ($res.exit_code -ne 0) {
+            Exit-WithError -Class 'RESET_ERROR' -Message "pyocd 硬件复位失败：探针未连接或目标 MCU 无响应。" -Detail ($res.stdout + "`n" + $res.stderr)
+        }
+        $result = [ordered]@{
+            schema      = 'firmware-reset-result/v1'
+            ok          = $true
+            backend     = 'pyocd'
+            target      = $targetChip
+            log         = (Resolve-Path -LiteralPath $logFile).Path
+            generated_at = Get-FwTimestamp
+        }
+        if ($Json) { Write-FwJson ([pscustomobject]$result) -Compact } else { Write-FwJson ([pscustomobject]$result) }
+        exit 0
+    }
+    'jlink' {
+        $jlinkExe = (Get-Command JLink.exe -ErrorAction SilentlyContinue)?.Source
+        if (-not $jlinkExe) {
+            $candidates = @(
+                "C:\Program Files\SEGGER\JLink\JLink.exe",
+                "C:\Program Files (x86)\SEGGER\JLink\JLink.exe"
+            )
+            foreach ($c in $candidates) {
+                if (Test-Path -LiteralPath $c) { $jlinkExe = $c; break }
+            }
+        }
+        if (-not $jlinkExe) {
+            Exit-WithError -Class 'TOOLCHAIN_NOT_FOUND' -Message '未找到 SEGGER JLink.exe。' -Detail '请安装官方 SEGGER J-Link 驱动。'
+        }
+        $cmdScript = Join-Path $repoRoot "artifacts\logs\jlink_reset_$stamp.jlink"
+        Set-Content -LiteralPath $cmdScript -Value "r`ng`nq`n" -Encoding ASCII
+        $targetChip = if ($ExpectedTarget) { $ExpectedTarget } else { 'STM32F103C8' }
+        $res = Invoke-FwProcess -FilePath $jlinkExe -Arguments @('-device', $targetChip, '-if', 'SWD', '-speed', '4000', '-autoconnect', '1', '-CommanderScript', $cmdScript) -WorkingDirectory $repoRoot -TimeoutMs 30000 -StdoutFile $logFile
+        if ($res.timed_out) {
+            Exit-WithError -Class 'TIMEOUT' -Message 'J-Link 芯片复位超时。' -Detail $logFile
+        }
+        if ($res.exit_code -ne 0) {
+            Exit-WithError -Class 'RESET_ERROR' -Message "J-Link 硬件复位失败：探针未连接或板卡未供电。" -Detail ($res.stdout + "`n" + $res.stderr)
+        }
+        $result = [ordered]@{
+            schema      = 'firmware-reset-result/v1'
+            ok          = $true
+            backend     = 'jlink'
+            target      = $targetChip
+            log         = (Resolve-Path -LiteralPath $logFile).Path
+            generated_at = Get-FwTimestamp
+        }
+        if ($Json) { Write-FwJson ([pscustomobject]$result) -Compact } else { Write-FwJson ([pscustomobject]$result) }
+        exit 0
+    }
+    'agentic-hil' {
+        $cmd = Get-Command agentic-hil -ErrorAction SilentlyContinue
+        if (-not $cmd) {
+            Exit-WithError -Class 'PROBE_NOT_FOUND' -Message "'agentic-hil' 未安装；请安装 Agentic HIL。" -Detail 'See README.md -> M2'
+        }
+        $res = Invoke-FwProcess -FilePath $cmd.Source -Arguments @('reset', '--target', $ExpectedTarget, '--json') -WorkingDirectory $repoRoot -TimeoutMs 120000 -StdoutFile $logFile
+        if ($res.timed_out) {
+            Exit-WithError -Class 'RESET_ERROR' -Message 'reset backend timed out and was killed.' -Detail $logFile
+        }
+        if ($res.exit_code -ne 0) {
+            Exit-WithError -Class 'RESET_ERROR' -Message 'reset backend reported failure.' -Detail ($res.stdout + $res.stderr)
+        }
+        $result = [ordered]@{
+            schema      = 'firmware-reset-result/v1'
+            ok          = $true
+            backend     = 'agentic-hil'
+            target      = $ExpectedTarget
+            log         = (Resolve-Path -LiteralPath $logFile).Path
+            generated_at = Get-FwTimestamp
+        }
+        if ($Json) { Write-FwJson ([pscustomobject]$result) -Compact } else { Write-FwJson ([pscustomobject]$result) }
+        exit 0
+    }
+    default {
+        Exit-WithError -Class 'CONFIG_ERROR' -Message "复位后端 '$Backend' 尚未在本机配置。" -Detail '请在 lab/lab.yaml 中配置有效的复位后端。'
+    }
+}

tools/setup-agent-mcp.ps1

@@ -0,0 +1,147 @@
+<#
+.SYNOPSIS
+    Dual-Tier MCP setup and registration helper (v0.0.8).
+    Inspects installed AI coding agents (Qoder, Claude Code, Antigravity, Cursor)
+    and prints/generates exact registration commands and workspace configuration.
+
+    Usage:
+        .\tools\setup-agent-mcp.ps1
+        .\tools\setup-agent-mcp.ps1 -Json
+        .\tools\setup-agent-mcp.ps1 -WriteWorkspaceMcp
+#>
+[CmdletBinding()]
+param(
+    [switch]$Json,
+    [switch]$WriteWorkspaceMcp
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+Import-Module (Join-Path $PSScriptRoot 'common\fw.psm1') -Force
+
+$repoRoot = Get-FwRepoRoot
+$python = Resolve-FwPython -RepoRoot $repoRoot
+$fwMcpServer = Join-Path $repoRoot 'tools\fw_mcp_server.py'
+$ahilExe = Join-Path $repoRoot '.venv\Scripts\agentic-hil.exe'
+
+$report = [ordered]@{
+    schema = 'firmwareloop-mcp-setup/v1'
+    repo_root = $repoRoot
+    servers = [ordered]@{
+        firmwareloop = [ordered]@{
+            command = $python
+            args = @($fwMcpServer)
+            description = 'Upper-tier firmware engineering workflow MCP'
+        }
+        agentic_hil = [ordered]@{
+            command = $ahilExe
+            args = @('mcp-stdio')
+            description = 'Lower-tier physical hardware & probe MCP'
+        }
+    }
+    agents = [ordered]@{}
+}
+
+# 1. Claude Code CLI
+$claudeCmd = Get-Command claude -ErrorAction SilentlyContinue
+$report.agents.claude_code = [ordered]@{
+    detected = ($null -ne $claudeCmd)
+    path = if ($claudeCmd) { $claudeCmd.Source } else { $null }
+    registration_commands = @(
+        "claude mcp add firmwareloop -- `"$python`" `"$fwMcpServer`"",
+        "claude mcp add agentic-hil -- `"$ahilExe`" mcp-stdio"
+    )
+}
+
+# 2. Qoder IDE / CLI
+$qoderCmd = $null
+foreach ($name in @('qoder', 'qodercli')) {
+    $c = Get-Command $name -ErrorAction SilentlyContinue
+    if ($c) { $qoderCmd = $c; break }
+}
+$report.agents.qoder = [ordered]@{
+    detected = ($null -ne $qoderCmd)
+    path = if ($qoderCmd) { $qoderCmd.Source } else { $null }
+    registration_commands = if ($qoderCmd) {
+        @(
+            "$($qoderCmd.Name) mcp add firmwareloop -- `"$python`" `"$fwMcpServer`"",
+            "$($qoderCmd.Name) mcp add agentic-hil -- `"$ahilExe`" mcp-stdio"
+        )
+    } else {
+        @(
+            "qoder mcp add firmwareloop -- `"$python`" `"$fwMcpServer`"",
+            "qoder mcp add agentic-hil -- `"$ahilExe`" mcp-stdio"
+        )
+    }
+}
+
+# 3. Antigravity CLI / Gemini Code
+$antigravitySkillsRoot = Join-Path $env:USERPROFILE '.gemini\antigravity-cli\skills'
+$targetGlobalSkillDir = Join-Path $antigravitySkillsRoot 'firmwareloop'
+$sourceSkill = Join-Path $repoRoot 'skills\firmwareloop\SKILL.md'
+
+$skillInstalled = $false
+if (Test-Path -LiteralPath (Split-Path $antigravitySkillsRoot)) {
+    if (Test-Path -LiteralPath $sourceSkill) {
+        New-Item -ItemType Directory -Force -Path $targetGlobalSkillDir | Out-Null
+        Copy-Item -LiteralPath $sourceSkill -Destination (Join-Path $targetGlobalSkillDir 'SKILL.md') -Force
+        $skillInstalled = $true
+    }
+}
+
+$report.agents.antigravity = [ordered]@{
+    mcp_config_path = (Join-Path $repoRoot '.mcp.json')
+    global_skill_installed = $skillInstalled
+    global_skill_path = if ($skillInstalled) { Join-Path $targetGlobalSkillDir 'SKILL.md' } else { $null }
+    note = "Antigravity automatically discovers project-level .mcp.json and global skills."
+}
+
+# Optional: write project-level .mcp.json
+if ($WriteWorkspaceMcp) {
+    $mcpJsonPath = Join-Path $repoRoot '.mcp.json'
+    $mcpConfig = [ordered]@{
+        mcpServers = [ordered]@{
+            firmwareloop = [ordered]@{
+                type = 'stdio'
+                command = $python
+                args = @($fwMcpServer)
+                timeout = 300000
+            }
+            "agentic-hil" = [ordered]@{
+                type = 'stdio'
+                command = $ahilExe
+                args = @('mcp-stdio')
+                timeout = 120000
+            }
+        }
+    }
+    $jsonContent = ConvertTo-Json -InputObject $mcpConfig -Depth 10
+    [System.IO.File]::WriteAllText($mcpJsonPath, $jsonContent, [System.Text.Encoding]::UTF8)
+    $report.workspace_mcp_written = $mcpJsonPath
+}
+
+if ($Json) {
+    Write-FwJson ([pscustomobject]$report)
+} else {
+    Write-Host "============================================================" -ForegroundColor Cyan
+    Write-Host "FirmwareLoop v0.0.8 - Dual-Tier MCP & Skill Setup Helper" -ForegroundColor Green
+    Write-Host "============================================================" -ForegroundColor Cyan
+    Write-Host ""
+    Write-Host "[1] Claude Code CLI Registration:" -ForegroundColor Yellow
+    Write-Host "    $($report.agents.claude_code.registration_commands[0])"
+    Write-Host "    $($report.agents.claude_code.registration_commands[1])"
+    Write-Host ""
+    Write-Host "[2] Qoder IDE (Official GUI & Workspace .mcp.json):" -ForegroundColor Yellow
+    Write-Host "    - GUI: Press 'Ctrl + Shift + ,' -> MCP -> My Services -> '+ Add', paste the JSON config"
+    Write-Host "    - Workspace: Qoder automatically detects '.mcp.json' in your workspace root"
+    Write-Host "    - CLI: $($report.agents.qoder.registration_commands[0])"
+    Write-Host "           $($report.agents.qoder.registration_commands[1])"
+    Write-Host ""
+    Write-Host "[3] Antigravity CLI / Cursor / VS Code:" -ForegroundColor Yellow
+    Write-Host "    - MCP: Automatically reads '.mcp.json' in workspace root"
+    if ($skillInstalled) {
+        Write-Host "    - Global Skill: [OK] Successfully registered to: $targetGlobalSkillDir\SKILL.md" -ForegroundColor Green
+    }
+    Write-Host "    - Generate workspace config: .\tools\setup-agent-mcp.ps1 -WriteWorkspaceMcp"
+    Write-Host ""
+}

tools/test-backends.ps1

@@ -0,0 +1,100 @@
+<#
+.SYNOPSIS
+    Backend command tests (Spec GAP-002). Verifies:
+      - command construction for all 7 backends (dry-run)
+      - execution + log capture through fake executables (keil/iar/west/idf.py)
+      - artifact detection failure is reported (no fabricated artifacts)
+    Runs in CI without Keil/IAR licenses (Spec §27: fake executable).
+
+    Usage: .\tools\test-backends.ps1 -Json
+#>
+[CmdletBinding()]
+param([switch]$Json)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+Import-Module (Join-Path $PSScriptRoot 'common\fw.psm1') -Force
+
+$repoRoot = Get-FwRepoRoot
+$fake = Join-Path $repoRoot 'tests\backend\fake-build-tools'
+$results = [System.Collections.Generic.List[object]]::new()
+
+function Assert {
+    param([string]$Name, [bool]$Ok, [string]$Detail)
+    $results.Add([pscustomobject]@{ name = $Name; ok = $Ok; detail = $Detail })
+    if (-not $Ok) { Write-Warning "FAIL: $Name - $Detail" }
+}
+
+function Invoke-Build {
+    param([string[]]$ToolArgs)
+    $argsList = @('-NoProfile', '-NonInteractive', '-File', (Join-Path $PSScriptRoot 'build.ps1')) + $ToolArgs
+    return Invoke-FwProcess -FilePath 'pwsh' -Arguments $argsList `
+        -WorkingDirectory $repoRoot -TimeoutMs 120000
+}
+
+# ---- 1. dry-run command construction (all backends) ---------------------------
+$cases = @(
+    @{ name = 'cmake';        args = @('-Backend', 'cmake', '-SourceDir', 'demo-firmware', '-DryRun', '-Json') ; expect = 'cmake -S' },
+    @{ name = 'make';         args = @('-Backend', 'make', '-SourceDir', 'demo-make', '-DryRun', '-Json')      ; expect = 'make -C' },
+    @{ name = 'platformio';   args = @('-Backend', 'platformio', '-SourceDir', 'demo-firmware', '-DryRun', '-Json') ; expect = 'pio run' },
+    @{ name = 'keil';         args = @('-Backend', 'keil', '-SourceDir', 'tests/backend/fixtures/keil-proj', '-DryRun', '-Json') ; expect = 'UV4 -b' },
+    @{ name = 'iar';          args = @('-Backend', 'iar', '-SourceDir', 'tests/backend/fixtures/iar-proj', '-DryRun', '-Json') ; expect = 'IarBuild' },
+    @{ name = 'zephyr';       args = @('-Backend', 'zephyr', '-DryRun', '-Json') ; expect = 'west build' },
+    @{ name = 'esp-idf';      args = @('-Backend', 'esp-idf', '-DryRun', '-Json') ; expect = 'idf.py build' }
+)
+
+# zephyr needs ZEPHYR_BOARD only for construction
+$env:ZEPHYR_BOARD = 'native_sim'
+
+foreach ($c in $cases) {
+    $r = Invoke-Build -ToolArgs $c.args
+    $jsonLine = ($r.stdout -split "`r?`n" | Where-Object { $_.TrimStart().StartsWith('{') } | Select-Object -Last 1)
+    $ok = $false
+    $detail = $r.stderr
+    if ($jsonLine) {
+        try { $j = $jsonLine | ConvertFrom-Json } catch { $j = $null }
+        if ($j -and $j.ok -and $j.dry_run -and $j.command -like "*$($c.expect)*") {
+            $ok = $true
+            $detail = "command: $($j.command)"
+        } else {
+            $detail = "unexpected: $jsonLine"
+        }
+    }
+    Assert -Name "construct.$($c.name)" -Ok $ok -Detail $detail
+}
+
+# ---- 2. fake executable execution (keil / iar / west / esp-idf) ----------------
+$execCases = @(
+    @{ name = 'keil';  args = @('-Backend', 'keil', '-SourceDir', 'tests/backend/fixtures/keil-proj', '-BackendTool', (Join-Path $fake 'UV4.cmd'), '-Json') },
+    @{ name = 'iar';   args = @('-Backend', 'iar', '-SourceDir', 'tests/backend/fixtures/iar-proj', '-BackendTool', (Join-Path $fake 'IarBuild.cmd'), '-Json') },
+    @{ name = 'zephyr'; args = @('-Backend', 'zephyr', '-BackendTool', (Join-Path $fake 'west.cmd'), '-Json') },
+    @{ name = 'esp-idf'; args = @('-Backend', 'esp-idf', '-BackendTool', (Join-Path $fake 'idf.py.cmd'), '-Json') }
+)
+foreach ($c in $execCases) {
+    $r = Invoke-Build -ToolArgs $c.args
+    $log = Get-Content -LiteralPath (Join-Path $repoRoot 'artifacts\logs\build.log') -Raw -ErrorAction SilentlyContinue
+    # fake tool ran (log captured) AND artifact absence was detected honestly
+    $ran = $log -match 'FAKE_BACKEND_OK'
+    $honest = $r.exit_code -eq 2 -and $r.stdout -match 'ARTIFACT_NOT_FOUND'
+    Assert -Name "execute.$($c.name)" -Ok ($ran -and $honest) -Detail "ran=$ran honest=$honest exit=$($r.exit_code) log_tail=$($log.Substring(0,[Math]::Min(120,$log.Length)))"
+}
+
+# ---- 3. cmake real build still green -------------------------------------------
+$r = Invoke-Build -ToolArgs @('-Configuration', 'Debug', '-Clean', '-Json')
+$jsonLine = ($r.stdout -split "`r?`n" | Where-Object { $_.TrimStart().StartsWith('{') } | Select-Object -Last 1)
+$j = $jsonLine | ConvertFrom-Json
+Assert -Name 'real.cmake' -Ok ($r.exit_code -eq 0 -and $j.ok -and $j.artifacts.primary.path -like '*firmware.elf*') `
+    -Detail "exit=$($r.exit_code) artifact=$($j.artifacts.primary.path)"
+
+# ---- summary -------------------------------------------------------------------
+$failed = @($results | Where-Object { -not $_.ok }).Count
+$summary = [ordered]@{
+    schema     = 'backend-test-result/v1'
+    ok         = ($failed -eq 0)
+    total      = $results.Count
+    failed     = $failed
+    tests      = @($results)
+    generated_at = Get-FwTimestamp
+}
+if ($Json) { Write-FwJson ([pscustomobject]$summary) -Compact } else { Write-FwJson ([pscustomobject]$summary) }
+exit $(if ($failed -eq 0) { 0 } else { 1 })

tools/test.ps1

@@ -0,0 +1,194 @@
+<#
+.SYNOPSIS
+    HIL test runner (Spec §18/19/23). Runs pytest under the project venv,
+    produces JUnit XML, a firmware-hil-result/v1 summary and a per-run audit
+    directory under artifacts/runs/<run_id>/.
+
+    Usage:
+        .\tools\test.ps1 -Json
+        .\tools\test.ps1 -TestPath tests/hil -RunId my-run -Json
+
+    Exit codes:
+        0  all tests passed (or skipped)
+        1  at least one test failed
+        2  configuration/runner error
+#>
+[CmdletBinding()]
+param(
+    [string]$TestPath = 'tests/hil',
+    [string]$RunId,
+    [switch]$Json,
+    [switch]$NoBuild,
+    [ValidateSet('simulator', 'real')]
+    [string]$Mode = 'simulator'
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+Import-Module (Join-Path $PSScriptRoot 'common\fw.psm1') -Force
+
+$repoRoot = Get-FwRepoRoot
+$python = Resolve-FwPython -RepoRoot $repoRoot
+if (-not $python) {
+    $err = New-FwError -ErrorClass 'CONFIG_ERROR' -Message 'No Python found. Run tools/doctor.ps1.'
+    if ($Json) { Write-FwJson $err -Compact } else { Write-FwJson $err; Write-Error $err.error }
+    exit 2
+}
+
+# --- run identity & audit dir -------------------------------------------------
+$runId = if ($RunId) { $RunId } else { Get-FwRunId }
+$runsDir = Join-Path $repoRoot "artifacts\runs\$runId"
+New-Item -ItemType Directory -Force -Path $runsDir | Out-Null
+$env:FW_RUN_DIR = $runsDir
+
+# --- evidence: environment.json + dependencies.json (Spec §25) -----------------
+$doctor = Invoke-FwProcess -FilePath 'pwsh' -Arguments @('-NoProfile', '-NonInteractive', '-File', (Join-Path $PSScriptRoot 'doctor.ps1'), '-Json') -WorkingDirectory $repoRoot -TimeoutMs 120000
+if ($doctor.exit_code -in @(0, 1)) {
+    try {
+        $d = $doctor.stdout | ConvertFrom-Json
+        if ($d.checks) {
+            $deps = [ordered]@{}
+            foreach ($p in $d.checks.PSObject.Properties) {
+                $v = $p.Value
+                $verProp = $v.PSObject.Properties['version']
+                $deps[$p.Name] = if ($v.status -eq 'ok' -and $verProp) { $v.version } else { $v.status }
+            }
+            $deps | ConvertTo-Json -Depth 4 | Set-Content -LiteralPath (Join-Path $runsDir 'dependencies.json') -Encoding utf8
+        }
+        if ($d.host) {
+            $d.host | ConvertTo-Json -Depth 4 | Set-Content -LiteralPath (Join-Path $runsDir 'environment.json') -Encoding utf8
+        }
+    } catch {
+        Write-Warning "evidence block failed: $($_.Exception.Message)"
+    }
+}
+# --- firmware identity --------------------------------------------------------
+$artifact = Join-Path $repoRoot 'artifacts\build\firmware.elf'
+$firmwareInfo = [ordered]@{
+    artifact      = $null
+    artifact_sha256 = $null
+    git_commit    = $null
+}
+if (Test-Path -LiteralPath $artifact) {
+    $firmwareInfo.artifact = (Resolve-Path -LiteralPath $artifact).Path
+    $firmwareInfo.artifact_sha256 = (Get-FileHash -LiteralPath $artifact -Algorithm SHA256).Hash.ToLowerInvariant()
+}
+$git = Get-FwGitInfo -RepoRoot $repoRoot
+$firmwareInfo.git_commit = $git.commit
+
+# repo state at run start for the audit trail (Spec §23 modified files)
+$modifiedFiles = @()
+$statusLines = git -C $repoRoot status --porcelain 2>$null
+foreach ($line in $statusLines) {
+    if ($line -match '^..\s+(.+)$') {
+        $p = $Matches[1].Trim('"')
+        if ($p) { $modifiedFiles += $p }
+    }
+}
+
+# --- run pytest ---------------------------------------------------------------
+# Pass --junitxml as a SEPARATE token with a relative path: pytest 9.x on this
+# platform mis-parses the "--junitxml=<absolute or relative path>" fused form
+# (the value is wrongly treated as a collect argument -> exit 4, "no match").
+$xmlRel = (Join-Path 'artifacts\runs' "$runId\pytest.xml").Replace('\', '/')
+$xmlNative = Join-Path $repoRoot $xmlRel.Replace('/', '\')
+New-Item -ItemType File -Force -Path $xmlNative | Out-Null
+$pytestArgs = @('-m', 'pytest', $TestPath, '--junitxml', $xmlRel, '--tb=short', '-p', 'no:cacheprovider', '-rA')
+$res = Invoke-FwProcess -FilePath $python -Arguments $pytestArgs -WorkingDirectory $repoRoot -TimeoutMs 900000
+Save-FwLog -Path (Join-Path $runsDir 'pytest.stdout.log') -Content $res.stdout
+Save-FwLog -Path (Join-Path $runsDir 'pytest.stderr.log') -Content $res.stderr
+
+if ($res.timed_out) {
+    $err = New-FwError -ErrorClass 'INSTRUMENT_TIMEOUT' -Message 'pytest run timed out and was killed.' -Detail $xmlReport
+    if ($Json) { Write-FwJson $err -Compact } else { Write-FwJson $err; Write-Error $err.error }
+    exit 2
+}
+if ($res.exit_code -eq 4) {
+    # usage error: pytest rejected the invocation - configuration problem
+    $err = New-FwError -ErrorClass 'CONFIG_ERROR' -Message 'pytest rejected the invocation (usage error, exit 4).' -Detail $res.stdout
+    if ($Json) { Write-FwJson $err -Compact } else { Write-FwJson $err; Write-Error $err.error }
+    exit 2
+}
+
+# --- parse JUnit XML ----------------------------------------------------------
+$tests = @()
+$failures = 0
+$skippedAsFailure = $false
+if (Test-Path -LiteralPath $xmlNative) {
+    [xml]$xml = Get-Content -LiteralPath $xmlNative -Raw
+    foreach ($tc in $xml.testsuites.testsuite.testcase) {
+        $entry = [ordered]@{
+            name     = $tc.name
+            status   = 'passed'
+            expected = $null
+            actual   = $null
+            evidence = @()
+        }
+        $failNode = $tc.SelectSingleNode('failure')
+        $skipNode = $tc.SelectSingleNode('skipped')
+        if ($failNode) {
+            $entry.status = 'failed'
+            $failures++
+            $msg = [string]$failNode.message
+            $expected = $null; $actual = $null
+            if ($msg -match 'expected (.+?), actual (.+?)(?::|$)') {
+                $expected = $Matches[1]; $actual = $Matches[2]
+            }
+            if (-not $expected -and $msg -match "expected (.+)") { $expected = $Matches[1] }
+            $entry.expected = $expected
+            $entry.actual = $actual
+            $entry.failure = ([string]$failNode.InnerText)
+        } elseif ($skipNode) {
+            $entry.status = 'skipped'
+            $entry.reason = [string]$skipNode.message
+            # REAL mode: a skipped required HIL test is a failure, never PASS
+            # (release-fix: simulator/skip must not masquerade as real success)
+            if ($Mode -eq 'real') {
+                $entry.status = 'failed'
+                $entry.expected = 'executed on real hardware'
+                $entry.actual = "skipped: $($entry.reason)"
+                $failures++
+                $skippedAsFailure = $true
+            }
+        }
+        # evidence artifacts copied into the run dir by fixtures
+        $tests += [pscustomobject]$entry
+    }
+}
+
+# --- evidence inventory -------------------------------------------------------
+$evidence = @()
+foreach ($f in @('uart.log', 'measurements.json')) {
+    $p = Join-Path $runsDir $f
+    if (Test-Path -LiteralPath $p) { $evidence += (Resolve-Path -LiteralPath $p).Path }
+}
+
+$summary = [ordered]@{
+    schema    = 'firmware-hil-result/v1'
+    run_id    = $runId
+    execution_mode = $Mode
+    simulated = ($Mode -ne 'real')
+    hardware_validated = ($Mode -eq 'real' -and $failures -eq 0)
+    ok        = ($failures -eq 0)
+    firmware  = $firmwareInfo
+    tests     = $tests
+    evidence  = $evidence
+    audit     = [ordered]@{
+        git_commit     = $git.commit
+        git_dirty      = $git.dirty
+        modified_files = $modifiedFiles
+        generated_at   = Get-FwTimestamp
+    }
+    hardware  = [ordered]@{
+        target_identity = $null   # set when a real probe is configured (M2)
+        probe_serial    = $null
+        com_port        = $null
+    }
+    generated_at = Get-FwTimestamp
+}
+$summaryPath = Join-Path $runsDir 'summary.json'
+$summary | ConvertTo-Json -Depth 12 | Set-Content -LiteralPath $summaryPath -Encoding utf8
+
+if ($Json) { Write-FwJson ([pscustomobject]$summary) -Compact } else { Write-FwJson ([pscustomobject]$summary) }
+
+exit $(if ($failures -eq 0) { 0 } else { 1 })