Refactor and enhance scanner worker functionality

- Cleaned up code formatting and organization across multiple files for improved readability.
- Introduced `OsScanAnalyzerDispatcher` to handle OS analyzer execution and plugin loading.
- Updated `ScanJobContext` to include an `Analysis` property for storing scan results.
- Enhanced `ScanJobProcessor` to utilize the new `OsScanAnalyzerDispatcher`.
- Improved logging and error handling in `ScanProgressReporter` for better traceability.
- Updated project dependencies and added references to new analyzer plugins.
- Revised task documentation to reflect current status and dependencies.

src/StellaOps.Scanner.EntryTrace.Tests/EntryTraceAnalyzerTests.cs

@@ -0,0 +1,136 @@
+using System.Collections.Immutable;
+using Microsoft.Extensions.Logging.Abstractions;
+using Microsoft.Extensions.Options;
+using StellaOps.Scanner.EntryTrace.Diagnostics;
+using Xunit;
+
+namespace StellaOps.Scanner.EntryTrace.Tests;
+
+public sealed class EntryTraceAnalyzerTests
+{
+    private static EntryTraceAnalyzer CreateAnalyzer()
+    {
+        var options = Options.Create(new EntryTraceAnalyzerOptions
+        {
+            MaxDepth = 32,
+            FollowRunParts = true
+        });
+        return new EntryTraceAnalyzer(options, new EntryTraceMetrics(), NullLogger<EntryTraceAnalyzer>.Instance);
+    }
+
+    [Fact]
+    public async Task ResolveAsync_FollowsShellIncludeAndPythonModule()
+    {
+        var fs = new TestRootFileSystem();
+        fs.AddFile("/entrypoint.sh", """
+        #!/bin/sh
+        source /opt/setup.sh
+        exec python -m app.main --flag
+        """);
+        fs.AddFile("/opt/setup.sh", """
+        #!/bin/sh
+        run-parts /opt/setup.d
+        """);
+        fs.AddDirectory("/opt/setup.d");
+        fs.AddFile("/opt/setup.d/001-node.sh", """
+        #!/bin/sh
+        exec node /app/server.js
+        """);
+        fs.AddFile("/opt/setup.d/010-java.sh", """
+        #!/bin/sh
+        java -jar /app/app.jar
+        """);
+        fs.AddFile("/usr/bin/python", "#!/usr/bin/env python3\n", executable: true);
+        fs.AddFile("/usr/bin/node", "#!/usr/bin/env node\n", executable: true);
+        fs.AddFile("/usr/bin/java", "", executable: true);
+        fs.AddFile("/app/server.js", "console.log('hello');", executable: true);
+        fs.AddFile("/app/app.jar", string.Empty, executable: true);
+
+        var analyzer = CreateAnalyzer();
+        var context = new EntryTraceContext(
+            fs,
+            ImmutableDictionary<string, string>.Empty,
+            ImmutableArray.Create("/usr/bin", "/usr/local/bin"),
+            "/",
+            "sha256:image",
+            "scan-entrytrace-1",
+            NullLogger.Instance);
+
+        var spec = EntrypointSpecification.FromExecForm(new[] { "/entrypoint.sh" }, Array.Empty<string>());
+        var result = await analyzer.ResolveAsync(spec, context);
+
+        Assert.Equal(EntryTraceOutcome.Resolved, result.Outcome);
+        Assert.Empty(result.Diagnostics);
+
+        var nodeNames = result.Nodes.Select(n => (n.Kind, n.DisplayName)).ToArray();
+        Assert.Contains((EntryTraceNodeKind.Command, "/entrypoint.sh"), nodeNames);
+        Assert.Contains((EntryTraceNodeKind.Include, "/opt/setup.sh"), nodeNames);
+        Assert.Contains(nodeNames, tuple => tuple.Kind == EntryTraceNodeKind.Command && tuple.DisplayName == "python");
+        Assert.Contains(nodeNames, tuple => tuple.Kind == EntryTraceNodeKind.Command && tuple.DisplayName == "node");
+        Assert.Contains(nodeNames, tuple => tuple.Kind == EntryTraceNodeKind.Command && tuple.DisplayName == "java");
+        Assert.Contains(nodeNames, tuple => tuple.Kind == EntryTraceNodeKind.RunPartsDirectory && tuple.DisplayName == "/opt/setup.d");
+
+        Assert.Contains(result.Edges, edge => edge.Relationship == "python-module" && edge.Metadata is { } metadata && metadata.TryGetValue("module", out var module) && module == "app.main");
+    }
+
+    [Fact]
+    public async Task ResolveAsync_RecordsDiagnosticsForMissingInclude()
+    {
+        var fs = new TestRootFileSystem();
+        fs.AddFile("/entrypoint.sh", """
+        #!/bin/sh
+        source /missing/setup.sh
+        exec /bin/true
+        """);
+        fs.AddFile("/bin/true", string.Empty, executable: true);
+
+        var analyzer = CreateAnalyzer();
+        var context = new EntryTraceContext(
+            fs,
+            ImmutableDictionary<string, string>.Empty,
+            ImmutableArray.Create("/bin"),
+            "/",
+            "sha256:image",
+            "scan-entrytrace-2",
+            NullLogger.Instance);
+
+        var spec = EntrypointSpecification.FromExecForm(new[] { "/entrypoint.sh" }, Array.Empty<string>());
+        var result = await analyzer.ResolveAsync(spec, context);
+
+        Assert.Equal(EntryTraceOutcome.PartiallyResolved, result.Outcome);
+        Assert.Single(result.Diagnostics);
+        Assert.Equal(EntryTraceUnknownReason.MissingFile, result.Diagnostics[0].Reason);
+    }
+
+    [Fact]
+    public async Task ResolveAsync_IsDeterministic()
+    {
+        var fs = new TestRootFileSystem();
+        fs.AddFile("/entrypoint.sh", """
+        #!/bin/sh
+        exec node /app/index.js
+        """);
+        fs.AddFile("/usr/bin/node", string.Empty, executable: true);
+        fs.AddFile("/app/index.js", "console.log('deterministic');", executable: true);
+
+        var analyzer = CreateAnalyzer();
+        var context = new EntryTraceContext(
+            fs,
+            ImmutableDictionary<string, string>.Empty,
+            ImmutableArray.Create("/usr/bin"),
+            "/",
+            "sha256:image",
+            "scan-entrytrace-3",
+            NullLogger.Instance);
+
+        var spec = EntrypointSpecification.FromExecForm(new[] { "/entrypoint.sh" }, Array.Empty<string>());
+        var first = await analyzer.ResolveAsync(spec, context);
+        var second = await analyzer.ResolveAsync(spec, context);
+
+        Assert.Equal(first.Outcome, second.Outcome);
+        Assert.Equal(first.Diagnostics, second.Diagnostics);
+        Assert.Equal(first.Nodes.Select(n => (n.Kind, n.DisplayName)).ToArray(), second.Nodes.Select(n => (n.Kind, n.DisplayName)).ToArray());
+        Assert.Equal(first.Edges.Select(e => (e.FromNodeId, e.ToNodeId, e.Relationship)).ToArray(),
+                     second.Edges.Select(e => (e.FromNodeId, e.ToNodeId, e.Relationship)).ToArray());
+    }
+}

src/StellaOps.Scanner.EntryTrace.Tests/ShellParserTests.cs

@@ -0,0 +1,33 @@
+using StellaOps.Scanner.EntryTrace.Parsing;
+using Xunit;
+
+namespace StellaOps.Scanner.EntryTrace.Tests;
+
+public sealed class ShellParserTests
+{
+    [Fact]
+    public void Parse_ProducesDeterministicNodes()
+    {
+        const string script = """
+        #!/bin/sh
+        source /opt/init.sh
+        if [ -f /etc/profile ]; then
+          . /etc/profile
+        fi
+
+        run-parts /etc/entry.d
+        exec python -m app.main --flag
+        """;
+
+        var first = ShellParser.Parse(script);
+        var second = ShellParser.Parse(script);
+
+        Assert.Equal(first.Nodes.Length, second.Nodes.Length);
+        var actual = first.Nodes.Select(n => n.GetType().Name).ToArray();
+        var expected = new[] { nameof(ShellIncludeNode), nameof(ShellIfNode), nameof(ShellRunPartsNode), nameof(ShellExecNode) };
+        Assert.Equal(expected, actual);
+
+        var actualSecond = second.Nodes.Select(n => n.GetType().Name).ToArray();
+        Assert.Equal(expected, actualSecond);
+    }
+}

src/StellaOps.Scanner.EntryTrace.Tests/StellaOps.Scanner.EntryTrace.Tests.csproj

@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+  <ItemGroup>
+    <ProjectReference Include="../StellaOps.Scanner.EntryTrace/StellaOps.Scanner.EntryTrace.csproj" />
+  </ItemGroup>
+  <ItemGroup>
+    <None Update="Fixtures\**\*" CopyToOutputDirectory="PreserveNewest" />
+  </ItemGroup>
+</Project>

src/StellaOps.Scanner.EntryTrace.Tests/TestRootFileSystem.cs

@@ -0,0 +1,180 @@
+using System.Collections.Generic;
+using System.Collections.Immutable;
+using System.IO;
+using StellaOps.Scanner.EntryTrace;
+
+namespace StellaOps.Scanner.EntryTrace.Tests;
+
+internal sealed class TestRootFileSystem : IRootFileSystem
+{
+    private readonly Dictionary<string, FileEntry> _entries = new(StringComparer.Ordinal);
+    private readonly HashSet<string> _directories = new(StringComparer.Ordinal);
+
+    public TestRootFileSystem()
+    {
+        _directories.Add("/");
+    }
+
+    public void AddFile(string path, string content, bool executable = true, string? layer = "sha256:layer-a")
+    {
+        var normalized = Normalize(path);
+        var directory = Path.GetDirectoryName(normalized);
+        if (!string.IsNullOrEmpty(directory))
+        {
+            _directories.Add(directory!);
+        }
+
+        _entries[normalized] = new FileEntry(normalized, content, executable, layer, IsDirectory: false);
+    }
+
+    public void AddDirectory(string path)
+    {
+        var normalized = Normalize(path);
+        _directories.Add(normalized);
+    }
+
+    public bool TryResolveExecutable(string name, IReadOnlyList<string> searchPaths, out RootFileDescriptor descriptor)
+    {
+        if (name.Contains('/', StringComparison.Ordinal))
+        {
+            var normalized = Normalize(name);
+            if (_entries.TryGetValue(normalized, out var file) && file.IsExecutable)
+            {
+                descriptor = file.ToDescriptor();
+                return true;
+            }
+
+            descriptor = null!;
+            return false;
+        }
+
+        foreach (var prefix in searchPaths)
+        {
+            var candidate = Combine(prefix, name);
+            if (_entries.TryGetValue(candidate, out var file) && file.IsExecutable)
+            {
+                descriptor = file.ToDescriptor();
+                return true;
+            }
+        }
+
+        descriptor = null!;
+        return false;
+    }
+
+    public bool TryReadAllText(string path, out RootFileDescriptor descriptor, out string content)
+    {
+        var normalized = Normalize(path);
+        if (_entries.TryGetValue(normalized, out var file))
+        {
+            descriptor = file.ToDescriptor();
+            content = file.Content;
+            return true;
+        }
+
+        descriptor = null!;
+        content = string.Empty;
+        return false;
+    }
+
+    public ImmutableArray<RootFileDescriptor> EnumerateDirectory(string path)
+    {
+        var normalized = Normalize(path);
+        var builder = ImmutableArray.CreateBuilder<RootFileDescriptor>();
+
+        foreach (var file in _entries.Values)
+        {
+            var directory = Normalize(Path.GetDirectoryName(file.Path) ?? "/");
+            if (string.Equals(directory, normalized, StringComparison.Ordinal))
+            {
+                builder.Add(file.ToDescriptor());
+            }
+        }
+
+        return builder.ToImmutable();
+    }
+
+    public bool DirectoryExists(string path)
+    {
+        var normalized = Normalize(path);
+        return _directories.Contains(normalized);
+    }
+
+    private static string Combine(string prefix, string name)
+    {
+        var normalizedPrefix = Normalize(prefix);
+        if (normalizedPrefix == "/")
+        {
+            return Normalize("/" + name);
+        }
+
+        return Normalize($"{normalizedPrefix}/{name}");
+    }
+
+    private static string Normalize(string path)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+        {
+            return "/";
+        }
+
+        var text = path.Replace('\\', '/').Trim();
+        if (!text.StartsWith("/", StringComparison.Ordinal))
+        {
+            text = "/" + text;
+        }
+
+        var parts = new List<string>();
+        foreach (var part in text.Split('/', StringSplitOptions.RemoveEmptyEntries))
+        {
+            if (part == ".")
+            {
+                continue;
+            }
+
+            if (part == "..")
+            {
+                if (parts.Count > 0)
+                {
+                    parts.RemoveAt(parts.Count - 1);
+                }
+                continue;
+            }
+
+            parts.Add(part);
+        }
+
+        return "/" + string.Join('/', parts);
+    }
+
+    private sealed record FileEntry(string Path, string Content, bool IsExecutable, string? Layer, bool IsDirectory)
+    {
+        public RootFileDescriptor ToDescriptor()
+        {
+            var shebang = ExtractShebang(Content);
+            return new RootFileDescriptor(Path, Layer, IsExecutable, IsDirectory, shebang);
+        }
+    }
+
+    private static string? ExtractShebang(string content)
+    {
+        if (string.IsNullOrEmpty(content))
+        {
+            return null;
+        }
+
+        using var reader = new StringReader(content);
+        var firstLine = reader.ReadLine();
+        if (firstLine is null)
+        {
+            return null;
+        }
+
+        if (!firstLine.StartsWith("#!", StringComparison.Ordinal))
+        {
+            return null;
+        }
+
+        return firstLine[2..].Trim();
+    }
+}

src/StellaOps.Scanner.EntryTrace/AGENTS.md

@@ -0,0 +1,32 @@
+# StellaOps.Scanner.EntryTrace — Agent Charter
+
+## Mission
+Resolve container `ENTRYPOINT`/`CMD` chains into deterministic call graphs that fuel usage-aware SBOMs, policy explainability, and runtime drift detection. Implement the EntryTrace analyzers and expose them as restart-time plug-ins for the Scanner Worker.
+
+## Scope
+- Parse POSIX/Bourne shell constructs (exec, command, case, if, source/run-parts) with deterministic AST output.
+- Walk layered root filesystems to resolve PATH lookups, interpreter hand-offs (Python/Node/Java), and record evidence.
+- Surface explainable diagnostics for unresolved branches (env indirection, missing files, unsupported syntax) and emit metrics.
+- Package analyzers as signed plug-ins under `plugins/scanner/entrytrace/`, guarded by restart-only policy.
+
+## Out of Scope
+- SBOM emission/diffing (owned by `Scanner.Emit`/`Scanner.Diff`).
+- Runtime enforcement or live drift reconciliation (owned by Zastava).
+- Registry/network fetchers beyond file lookups inside extracted layers.
+
+## Interfaces & Contracts
+- Primary entry point: `IEntryTraceAnalyzer.ResolveAsync` returning a deterministic `EntryTraceGraph`.
+- Graph nodes must include file path, line span, interpreter classification, evidence source, and follow `Scanner.Core` timestamp/ID helpers when emitting events.
+- Diagnostics must enumerate unknown reasons from fixed enum; metrics tagged `entrytrace.*`.
+- Plug-ins register via `IEntryTraceAnalyzerFactory` and must validate against `IPluginCatalogGuard`.
+
+## Observability & Security
+- No dynamic assembly loading beyond restart-time plug-in catalog.
+- Structured logs include `scanId`, `imageDigest`, `layerDigest`, `command`, `reason`.
+- Metrics counters: `entrytrace_resolutions_total{result}`, `entrytrace_unresolved_total{reason}`.
+- Deny `source` directives outside image root; sandbox file IO via provided `IRootFileSystem`.
+
+## Testing
+- Unit tests live in `../StellaOps.Scanner.EntryTrace.Tests` with golden fixtures under `Fixtures/`.
+- Determinism harness: same inputs produce byte-identical serialized graphs.
+- Parser fuzz seeds captured for regression; interpreter tracers validated with sample scripts for Python, Node, Java launchers.

src/StellaOps.Scanner.EntryTrace/Diagnostics/EntryTraceMetrics.cs

@@ -0,0 +1,51 @@
+using System.Collections.Generic;
+using System.Diagnostics.Metrics;
+
+namespace StellaOps.Scanner.EntryTrace.Diagnostics;
+
+public static class EntryTraceInstrumentation
+{
+    public static readonly Meter Meter = new("stellaops.scanner.entrytrace", "1.0.0");
+}
+
+public sealed class EntryTraceMetrics
+{
+    private readonly Counter<long> _resolutions;
+    private readonly Counter<long> _unresolved;
+
+    public EntryTraceMetrics()
+    {
+        _resolutions = EntryTraceInstrumentation.Meter.CreateCounter<long>(
+            "entrytrace_resolutions_total",
+            description: "Number of entry trace attempts by outcome.");
+        _unresolved = EntryTraceInstrumentation.Meter.CreateCounter<long>(
+            "entrytrace_unresolved_total",
+            description: "Number of unresolved entry trace hops by reason.");
+    }
+
+    public void RecordOutcome(string imageDigest, string scanId, EntryTraceOutcome outcome)
+    {
+        _resolutions.Add(1, CreateTags(imageDigest, scanId, ("outcome", outcome.ToString().ToLowerInvariant())));
+    }
+
+    public void RecordUnknown(string imageDigest, string scanId, EntryTraceUnknownReason reason)
+    {
+        _unresolved.Add(1, CreateTags(imageDigest, scanId, ("reason", reason.ToString().ToLowerInvariant())));
+    }
+
+    private static KeyValuePair<string, object?>[] CreateTags(string imageDigest, string scanId, params (string Key, object? Value)[] extras)
+    {
+        var tags = new List<KeyValuePair<string, object?>>(2 + extras.Length)
+        {
+            new("image", imageDigest),
+            new("scan.id", scanId)
+        };
+
+        foreach (var extra in extras)
+        {
+            tags.Add(new KeyValuePair<string, object?>(extra.Key, extra.Value));
+        }
+
+        return tags.ToArray();
+    }
+}

src/StellaOps.Scanner.EntryTrace/EntryTraceAnalyzer.cs

@@ -0,0 +1,963 @@
+using System.Collections.Generic;
+using System.Collections.Immutable;
+using System.IO;
+using System.Linq;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using StellaOps.Scanner.EntryTrace.Diagnostics;
+using StellaOps.Scanner.EntryTrace.Parsing;
+
+namespace StellaOps.Scanner.EntryTrace;
+
+public sealed class EntryTraceAnalyzer : IEntryTraceAnalyzer
+{
+    private readonly EntryTraceAnalyzerOptions _options;
+    private readonly EntryTraceMetrics _metrics;
+    private readonly ILogger<EntryTraceAnalyzer> _logger;
+
+    public EntryTraceAnalyzer(
+        IOptions<EntryTraceAnalyzerOptions> options,
+        EntryTraceMetrics metrics,
+        ILogger<EntryTraceAnalyzer> logger)
+    {
+        _options = options?.Value ?? throw new ArgumentNullException(nameof(options));
+        _metrics = metrics ?? throw new ArgumentNullException(nameof(metrics));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+
+        if (_options.MaxDepth <= 0)
+        {
+            _options.MaxDepth = 32;
+        }
+
+        if (string.IsNullOrWhiteSpace(_options.DefaultPath))
+        {
+            _options.DefaultPath = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+        }
+    }
+
+    public ValueTask<EntryTraceGraph> ResolveAsync(
+        EntrypointSpecification entrypoint,
+        EntryTraceContext context,
+        CancellationToken cancellationToken = default)
+    {
+        if (entrypoint is null)
+        {
+            throw new ArgumentNullException(nameof(entrypoint));
+        }
+
+        if (context is null)
+        {
+            throw new ArgumentNullException(nameof(context));
+        }
+
+        cancellationToken.ThrowIfCancellationRequested();
+
+        var builder = new Builder(
+            entrypoint,
+            context,
+            _options,
+            _metrics,
+            _logger);
+
+        var graph = builder.BuildGraph();
+        _metrics.RecordOutcome(context.ImageDigest, context.ScanId, graph.Outcome);
+        foreach (var diagnostic in graph.Diagnostics)
+        {
+            _metrics.RecordUnknown(context.ImageDigest, context.ScanId, diagnostic.Reason);
+        }
+
+        return ValueTask.FromResult(graph);
+    }
+
+    private sealed class Builder
+    {
+        private readonly EntrypointSpecification _entrypoint;
+        private readonly EntryTraceContext _context;
+        private readonly EntryTraceAnalyzerOptions _options;
+        private readonly EntryTraceMetrics _metrics;
+        private readonly ILogger _logger;
+        private readonly ImmutableArray<string> _pathEntries;
+        private readonly List<EntryTraceNode> _nodes = new();
+        private readonly List<EntryTraceEdge> _edges = new();
+        private readonly List<EntryTraceDiagnostic> _diagnostics = new();
+        private readonly HashSet<string> _visitedScripts = new(StringComparer.Ordinal);
+        private readonly HashSet<string> _visitedCommands = new(StringComparer.Ordinal);
+        private int _nextNodeId = 1;
+
+        public Builder(
+            EntrypointSpecification entrypoint,
+            EntryTraceContext context,
+            EntryTraceAnalyzerOptions options,
+            EntryTraceMetrics metrics,
+            ILogger logger)
+        {
+            _entrypoint = entrypoint;
+            _context = context;
+            _options = options;
+            _metrics = metrics;
+            _logger = logger;
+            _pathEntries = DeterminePath(context);
+        }
+
+        private static ImmutableArray<string> DeterminePath(EntryTraceContext context)
+        {
+            if (context.Path.Length > 0)
+            {
+                return context.Path;
+            }
+
+            if (context.Environment.TryGetValue("PATH", out var raw) && !string.IsNullOrWhiteSpace(raw))
+            {
+                return raw.Split(':').Select(p => p.Trim()).Where(p => p.Length > 0).ToImmutableArray();
+            }
+
+            return ImmutableArray<string>.Empty;
+        }
+
+        public EntryTraceGraph BuildGraph()
+        {
+            var initialArgs = ComposeInitialCommand(_entrypoint);
+            if (initialArgs.Length == 0)
+            {
+                _diagnostics.Add(new EntryTraceDiagnostic(
+                    EntryTraceDiagnosticSeverity.Error,
+                    EntryTraceUnknownReason.CommandNotFound,
+                    "ENTRYPOINT/CMD yielded no executable command.",
+                    Span: null,
+                    RelatedPath: null));
+                return ToGraph(EntryTraceOutcome.Unresolved);
+            }
+
+            ResolveCommand(initialArgs, parent: null, originSpan: null, depth: 0, relationship: "entrypoint");
+
+            var outcome = DetermineOutcome();
+            return ToGraph(outcome);
+        }
+
+        private EntryTraceOutcome DetermineOutcome()
+        {
+            if (_diagnostics.Count == 0)
+            {
+                return EntryTraceOutcome.Resolved;
+            }
+
+            return _diagnostics.Any(d => d.Severity == EntryTraceDiagnosticSeverity.Error)
+                ? EntryTraceOutcome.Unresolved
+                : EntryTraceOutcome.PartiallyResolved;
+        }
+
+        private EntryTraceGraph ToGraph(EntryTraceOutcome outcome)
+        {
+            return new EntryTraceGraph(
+                outcome,
+                _nodes.ToImmutableArray(),
+                _edges.ToImmutableArray(),
+                _diagnostics.ToImmutableArray());
+        }
+
+        private ImmutableArray<string> ComposeInitialCommand(EntrypointSpecification specification)
+        {
+            if (specification.Entrypoint.Length > 0)
+            {
+                if (specification.Command.Length > 0)
+                {
+                    return specification.Entrypoint.Concat(specification.Command).ToImmutableArray();
+                }
+
+                return specification.Entrypoint;
+            }
+
+            if (specification.Command.Length > 0)
+            {
+                return specification.Command;
+            }
+
+            if (!string.IsNullOrWhiteSpace(specification.EntrypointShell))
+            {
+                return ImmutableArray.Create("/bin/sh", "-c", specification.EntrypointShell!);
+            }
+
+            if (!string.IsNullOrWhiteSpace(specification.CommandShell))
+            {
+                return ImmutableArray.Create("/bin/sh", "-c", specification.CommandShell!);
+            }
+
+            return ImmutableArray<string>.Empty;
+        }
+
+        private void ResolveCommand(
+            ImmutableArray<string> arguments,
+            EntryTraceNode? parent,
+            EntryTraceSpan? originSpan,
+            int depth,
+            string relationship)
+        {
+            if (arguments.Length == 0)
+            {
+                return;
+            }
+
+            if (depth >= _options.MaxDepth)
+            {
+                _diagnostics.Add(new EntryTraceDiagnostic(
+                    EntryTraceDiagnosticSeverity.Warning,
+                    EntryTraceUnknownReason.RecursionLimitReached,
+                    $"Recursion depth limit {_options.MaxDepth} reached while resolving '{arguments[0]}'.",
+                    originSpan,
+                    RelatedPath: null));
+                return;
+            }
+
+            var commandName = arguments[0];
+            var evidence = default(EntryTraceEvidence?);
+            var descriptor = default(RootFileDescriptor);
+
+            if (!TryResolveExecutable(commandName, out descriptor, out evidence))
+            {
+                _diagnostics.Add(new EntryTraceDiagnostic(
+                    EntryTraceDiagnosticSeverity.Warning,
+                    EntryTraceUnknownReason.CommandNotFound,
+                    $"Command '{commandName}' not found in PATH.",
+                    originSpan,
+                    RelatedPath: null));
+                return;
+            }
+
+            var node = AddNode(
+                EntryTraceNodeKind.Command,
+                commandName,
+                arguments,
+                DetermineInterpreterKind(descriptor),
+                evidence,
+                originSpan);
+
+            if (parent is not null)
+            {
+                _edges.Add(new EntryTraceEdge(parent.Id, node.Id, relationship, Metadata: null));
+            }
+
+            if (!_visitedCommands.Add(descriptor.Path))
+            {
+                // Prevent infinite loops when scripts call themselves recursively.
+                return;
+            }
+
+            if (TryFollowInterpreter(node, descriptor, arguments, depth))
+            {
+                return;
+            }
+
+            if (TryFollowShell(node, descriptor, arguments, depth))
+            {
+                return;
+            }
+
+            // Terminal executable.
+        }
+
+        private bool TryResolveExecutable(
+            string commandName,
+            out RootFileDescriptor descriptor,
+            out EntryTraceEvidence? evidence)
+        {
+            evidence = null;
+
+            if (commandName.Contains('/', StringComparison.Ordinal))
+            {
+                if (_context.FileSystem.TryReadAllText(commandName, out descriptor, out _))
+                {
+                    evidence = new EntryTraceEvidence(commandName, descriptor.LayerDigest, "path", null);
+                    return true;
+                }
+
+                if (_context.FileSystem.TryResolveExecutable(commandName, Array.Empty<string>(), out descriptor))
+                {
+                    evidence = new EntryTraceEvidence(descriptor.Path, descriptor.LayerDigest, "path", null);
+                    return true;
+                }
+            }
+
+            if (_context.FileSystem.TryResolveExecutable(commandName, _pathEntries, out descriptor))
+            {
+                evidence = new EntryTraceEvidence(descriptor.Path, descriptor.LayerDigest, "path-search", new Dictionary<string, string>
+                {
+                    ["command"] = commandName
+                });
+                return true;
+            }
+
+            descriptor = null!;
+            return false;
+        }
+
+        private bool TryFollowInterpreter(
+            EntryTraceNode node,
+            RootFileDescriptor descriptor,
+            ImmutableArray<string> arguments,
+            int depth)
+        {
+            var interpreter = DetermineInterpreterKind(descriptor);
+            if (interpreter == EntryTraceInterpreterKind.None)
+            {
+                interpreter = DetectInterpreterFromCommand(arguments);
+            }
+
+            if (interpreter == EntryTraceInterpreterKind.None)
+            {
+                return false;
+            }
+
+            switch (interpreter)
+            {
+                case EntryTraceInterpreterKind.Python:
+                    return HandlePython(node, arguments, descriptor, depth);
+                case EntryTraceInterpreterKind.Node:
+                    return HandleNode(node, arguments, descriptor, depth);
+                case EntryTraceInterpreterKind.Java:
+                    return HandleJava(node, arguments, descriptor, depth);
+                default:
+                    return false;
+            }
+        }
+
+        private EntryTraceInterpreterKind DetermineInterpreterKind(RootFileDescriptor descriptor)
+        {
+            if (descriptor.ShebangInterpreter is null)
+            {
+                return EntryTraceInterpreterKind.None;
+            }
+
+            var shebang = descriptor.ShebangInterpreter.ToLowerInvariant();
+            if (shebang.Contains("python", StringComparison.Ordinal))
+            {
+                return EntryTraceInterpreterKind.Python;
+            }
+
+            if (shebang.Contains("node", StringComparison.Ordinal))
+            {
+                return EntryTraceInterpreterKind.Node;
+            }
+
+            if (shebang.Contains("java", StringComparison.Ordinal))
+            {
+                return EntryTraceInterpreterKind.Java;
+            }
+
+            if (shebang.Contains("sh", StringComparison.Ordinal) || shebang.Contains("bash", StringComparison.Ordinal))
+            {
+                return EntryTraceInterpreterKind.None;
+            }
+
+            return EntryTraceInterpreterKind.None;
+        }
+
+        private EntryTraceInterpreterKind DetectInterpreterFromCommand(ImmutableArray<string> arguments)
+        {
+            if (arguments.Length == 0)
+            {
+                return EntryTraceInterpreterKind.None;
+            }
+
+            var command = arguments[0];
+            if (command.Equals("python", StringComparison.OrdinalIgnoreCase) ||
+                command.StartsWith("python", StringComparison.OrdinalIgnoreCase))
+            {
+                return EntryTraceInterpreterKind.Python;
+            }
+
+            if (command.Equals("node", StringComparison.OrdinalIgnoreCase) ||
+                command.Equals("nodejs", StringComparison.OrdinalIgnoreCase))
+            {
+                return EntryTraceInterpreterKind.Node;
+            }
+
+            if (command.Equals("java", StringComparison.OrdinalIgnoreCase))
+            {
+                return EntryTraceInterpreterKind.Java;
+            }
+
+            return EntryTraceInterpreterKind.None;
+        }
+
+        private bool HandlePython(
+            EntryTraceNode node,
+            ImmutableArray<string> arguments,
+            RootFileDescriptor descriptor,
+            int depth)
+        {
+            if (arguments.Length < 2)
+            {
+                return false;
+            }
+
+            var argIndex = 1;
+            var moduleMode = false;
+            string? moduleName = null;
+            string? scriptPath = null;
+
+            while (argIndex < arguments.Length)
+            {
+                var current = arguments[argIndex];
+                if (current == "-m" && argIndex + 1 < arguments.Length)
+                {
+                    moduleMode = true;
+                    moduleName = arguments[argIndex + 1];
+                    break;
+                }
+
+                if (!current.StartsWith("-", StringComparison.Ordinal))
+                {
+                    scriptPath = current;
+                    break;
+                }
+
+                argIndex++;
+            }
+
+            if (moduleMode && moduleName is not null)
+            {
+                _edges.Add(new EntryTraceEdge(node.Id, node.Id, "python-module", new Dictionary<string, string>
+                {
+                    ["module"] = moduleName
+                }));
+                return true;
+            }
+
+            if (scriptPath is null)
+            {
+                return false;
+            }
+
+            if (!_context.FileSystem.TryReadAllText(scriptPath, out var scriptDescriptor, out var content))
+            {
+                _diagnostics.Add(new EntryTraceDiagnostic(
+                    EntryTraceDiagnosticSeverity.Warning,
+                    EntryTraceUnknownReason.MissingFile,
+                    $"Python script '{scriptPath}' was not found.",
+                    Span: null,
+                    RelatedPath: scriptPath));
+                return true;
+            }
+
+            var scriptNode = AddNode(
+                EntryTraceNodeKind.Script,
+                scriptPath,
+                ImmutableArray<string>.Empty,
+                EntryTraceInterpreterKind.Python,
+                new EntryTraceEvidence(scriptDescriptor.Path, scriptDescriptor.LayerDigest, "script", null),
+                null);
+
+            _edges.Add(new EntryTraceEdge(node.Id, scriptNode.Id, "executes", null));
+
+            if (IsLikelyShell(content))
+            {
+                ResolveShellScript(content, scriptDescriptor.Path, scriptNode, depth + 1);
+            }
+
+            return true;
+        }
+
+        private bool HandleNode(
+            EntryTraceNode node,
+            ImmutableArray<string> arguments,
+            RootFileDescriptor descriptor,
+            int depth)
+        {
+            if (arguments.Length < 2)
+            {
+                return false;
+            }
+
+            var scriptArg = arguments.Skip(1).FirstOrDefault(a => !a.StartsWith("-", StringComparison.Ordinal));
+            if (string.IsNullOrWhiteSpace(scriptArg))
+            {
+                return false;
+            }
+
+            if (!_context.FileSystem.TryReadAllText(scriptArg, out var scriptDescriptor, out var content))
+            {
+                _diagnostics.Add(new EntryTraceDiagnostic(
+                    EntryTraceDiagnosticSeverity.Warning,
+                    EntryTraceUnknownReason.MissingFile,
+                    $"Node script '{scriptArg}' was not found.",
+                    Span: null,
+                    RelatedPath: scriptArg));
+                return true;
+            }
+
+            var scriptNode = AddNode(
+                EntryTraceNodeKind.Script,
+                scriptArg,
+                ImmutableArray<string>.Empty,
+                EntryTraceInterpreterKind.Node,
+                new EntryTraceEvidence(scriptDescriptor.Path, scriptDescriptor.LayerDigest, "script", null),
+                null);
+
+            _edges.Add(new EntryTraceEdge(node.Id, scriptNode.Id, "executes", null));
+            return true;
+        }
+
+        private bool HandleJava(
+            EntryTraceNode node,
+            ImmutableArray<string> arguments,
+            RootFileDescriptor descriptor,
+            int depth)
+        {
+            if (arguments.Length < 2)
+            {
+                return false;
+            }
+
+            string? jar = null;
+            string? mainClass = null;
+
+            for (var i = 1; i < arguments.Length; i++)
+            {
+                var arg = arguments[i];
+                if (arg == "-jar" && i + 1 < arguments.Length)
+                {
+                    jar = arguments[i + 1];
+                    break;
+                }
+
+                if (!arg.StartsWith("-", StringComparison.Ordinal) && mainClass is null)
+                {
+                    mainClass = arg;
+                }
+            }
+
+            if (jar is not null)
+            {
+                if (!_context.FileSystem.TryResolveExecutable(jar, Array.Empty<string>(), out var jarDescriptor))
+                {
+                    _diagnostics.Add(new EntryTraceDiagnostic(
+                        EntryTraceDiagnosticSeverity.Warning,
+                        EntryTraceUnknownReason.JarNotFound,
+                        $"Java JAR '{jar}' not found.",
+                        Span: null,
+                        RelatedPath: jar));
+                }
+                else
+                {
+                    var jarNode = AddNode(
+                        EntryTraceNodeKind.Executable,
+                        jarDescriptor.Path,
+                        ImmutableArray<string>.Empty,
+                        EntryTraceInterpreterKind.Java,
+                        new EntryTraceEvidence(jarDescriptor.Path, jarDescriptor.LayerDigest, "jar", null),
+                        null);
+                    _edges.Add(new EntryTraceEdge(node.Id, jarNode.Id, "executes", null));
+                }
+
+                return true;
+            }
+
+            if (mainClass is not null)
+            {
+                _edges.Add(new EntryTraceEdge(node.Id, node.Id, "java-main", new Dictionary<string, string>
+                {
+                    ["class"] = mainClass
+                }));
+                return true;
+            }
+
+            return false;
+        }
+
+        private bool TryFollowShell(
+            EntryTraceNode node,
+            RootFileDescriptor descriptor,
+            ImmutableArray<string> arguments,
+            int depth)
+        {
+            if (!IsShellExecutable(descriptor, arguments))
+            {
+                return false;
+            }
+
+            if (arguments.Length >= 2 && arguments[1] == "-c" && arguments.Length >= 3)
+            {
+                var scriptText = arguments[2];
+                ResolveShellScript(scriptText, descriptor.Path, node, depth + 1);
+                return true;
+            }
+
+            if (arguments.Length >= 2)
+            {
+                var candidate = arguments[1];
+                if (_context.FileSystem.TryReadAllText(candidate, out var scriptDescriptor, out var content))
+                {
+                    var scriptNode = AddNode(
+                        EntryTraceNodeKind.Script,
+                        candidate,
+                        ImmutableArray<string>.Empty,
+                        EntryTraceInterpreterKind.None,
+                        new EntryTraceEvidence(scriptDescriptor.Path, scriptDescriptor.LayerDigest, "script", null),
+                        null);
+                    _edges.Add(new EntryTraceEdge(node.Id, scriptNode.Id, "executes", null));
+                    ResolveShellScript(content, scriptDescriptor.Path, scriptNode, depth + 1);
+                    return true;
+                }
+            }
+
+            if (arguments.Length == 1)
+            {
+                if (_context.FileSystem.TryReadAllText(descriptor.Path, out var scriptDescriptor, out var content))
+                {
+                    var scriptNode = AddNode(
+                        EntryTraceNodeKind.Script,
+                        descriptor.Path,
+                        ImmutableArray<string>.Empty,
+                        EntryTraceInterpreterKind.None,
+                        new EntryTraceEvidence(scriptDescriptor.Path, scriptDescriptor.LayerDigest, "script", null),
+                        null);
+                    _edges.Add(new EntryTraceEdge(node.Id, scriptNode.Id, "executes", null));
+                    ResolveShellScript(content, scriptDescriptor.Path, scriptNode, depth + 1);
+                    return true;
+                }
+            }
+
+            return false;
+        }
+
+        private static bool IsShellExecutable(RootFileDescriptor descriptor, ImmutableArray<string> arguments)
+        {
+            if (descriptor.ShebangInterpreter is not null &&
+                (descriptor.ShebangInterpreter.Contains("sh", StringComparison.OrdinalIgnoreCase) ||
+                 descriptor.ShebangInterpreter.Contains("bash", StringComparison.OrdinalIgnoreCase)))
+            {
+                return true;
+            }
+
+            var command = arguments[0];
+            return command is "/bin/sh" or "sh" or "bash" or "/bin/bash";
+        }
+
+        private void ResolveShellScript(
+            string scriptContent,
+            string scriptPath,
+            EntryTraceNode parent,
+            int depth)
+        {
+            if (_visitedScripts.Contains(scriptPath))
+            {
+                return;
+            }
+
+            _visitedScripts.Add(scriptPath);
+
+            ShellScript ast;
+            try
+            {
+                ast = ShellParser.Parse(scriptContent);
+            }
+            catch (Exception ex)
+            {
+                _diagnostics.Add(new EntryTraceDiagnostic(
+                    EntryTraceDiagnosticSeverity.Warning,
+                    EntryTraceUnknownReason.UnsupportedSyntax,
+                    $"Failed to parse shell script '{scriptPath}': {ex.Message}",
+                    Span: null,
+                    RelatedPath: scriptPath));
+                return;
+            }
+
+            foreach (var node in ast.Nodes)
+            {
+                HandleShellNode(node, parent, scriptPath, depth);
+            }
+        }
+
+        private void HandleShellNode(
+            ShellNode node,
+            EntryTraceNode parent,
+            string scriptPath,
+            int depth)
+        {
+            switch (node)
+            {
+                case ShellExecNode execNode:
+                    {
+                        var args = MaterializeArguments(execNode.Arguments);
+                        if (args.Length <= 1)
+                        {
+                            break;
+                        }
+
+                        var execArgs = args.RemoveAt(0);
+                        ResolveCommand(execArgs, parent, ToEntryTraceSpan(execNode.Span, scriptPath), depth + 1, "executes");
+                        break;
+                    }
+                case ShellIncludeNode includeNode:
+                    {
+                        var includeArg = includeNode.PathExpression;
+                        var includePath = ResolveScriptPath(scriptPath, includeArg);
+                        if (!_context.FileSystem.TryReadAllText(includePath, out var descriptor, out var content))
+                        {
+                            _diagnostics.Add(new EntryTraceDiagnostic(
+                                EntryTraceDiagnosticSeverity.Warning,
+                                EntryTraceUnknownReason.MissingFile,
+                                $"Included script '{includePath}' not found.",
+                                ToEntryTraceSpan(includeNode.Span, scriptPath),
+                                includePath));
+                            break;
+                        }
+
+                        var includeTraceNode = AddNode(
+                            EntryTraceNodeKind.Include,
+                            includePath,
+                            ImmutableArray<string>.Empty,
+                            EntryTraceInterpreterKind.None,
+                            new EntryTraceEvidence(descriptor.Path, descriptor.LayerDigest, "include", null),
+                            ToEntryTraceSpan(includeNode.Span, scriptPath));
+
+                        _edges.Add(new EntryTraceEdge(parent.Id, includeTraceNode.Id, "includes", null));
+                        ResolveShellScript(content, descriptor.Path, includeTraceNode, depth + 1);
+                        break;
+                    }
+                case ShellRunPartsNode runPartsNode when _options.FollowRunParts:
+                    {
+                        var directory = ResolveScriptPath(scriptPath, runPartsNode.DirectoryExpression);
+                        if (!_context.FileSystem.DirectoryExists(directory))
+                        {
+                            _diagnostics.Add(new EntryTraceDiagnostic(
+                                EntryTraceDiagnosticSeverity.Warning,
+                                EntryTraceUnknownReason.MissingFile,
+                                $"run-parts directory '{directory}' not found.",
+                                ToEntryTraceSpan(runPartsNode.Span, scriptPath),
+                                directory));
+                            break;
+                        }
+
+                        var entries = _context.FileSystem.EnumerateDirectory(directory)
+                            .Where(e => !e.IsDirectory && e.IsExecutable)
+                            .OrderBy(e => e.Path, StringComparer.Ordinal)
+                            .Take(_options.RunPartsLimit)
+                            .ToList();
+
+                        if (entries.Count == 0)
+                        {
+                            _diagnostics.Add(new EntryTraceDiagnostic(
+                                EntryTraceDiagnosticSeverity.Info,
+                                EntryTraceUnknownReason.RunPartsEmpty,
+                                $"run-parts directory '{directory}' contained no executable files.",
+                                ToEntryTraceSpan(runPartsNode.Span, scriptPath),
+                                directory));
+                            break;
+                        }
+
+                        var dirNode = AddNode(
+                            EntryTraceNodeKind.RunPartsDirectory,
+                            directory,
+                            ImmutableArray<string>.Empty,
+                            EntryTraceInterpreterKind.None,
+                            new EntryTraceEvidence(directory, null, "run-parts", null),
+                            ToEntryTraceSpan(runPartsNode.Span, scriptPath));
+                        _edges.Add(new EntryTraceEdge(parent.Id, dirNode.Id, "run-parts", null));
+
+                        foreach (var entry in entries)
+                        {
+                        var childNode = AddNode(
+                            EntryTraceNodeKind.RunPartsScript,
+                            entry.Path,
+                            ImmutableArray<string>.Empty,
+                            EntryTraceInterpreterKind.None,
+                            new EntryTraceEvidence(entry.Path, entry.LayerDigest, "run-parts", null),
+                            null);
+                            _edges.Add(new EntryTraceEdge(dirNode.Id, childNode.Id, "executes", null));
+
+                            if (_context.FileSystem.TryReadAllText(entry.Path, out var childDescriptor, out var content))
+                            {
+                                ResolveShellScript(content, childDescriptor.Path, childNode, depth + 1);
+                            }
+                        }
+
+                        break;
+                    }
+                case ShellIfNode ifNode:
+                    {
+                        foreach (var branch in ifNode.Branches)
+                        {
+                            foreach (var inner in branch.Body)
+                            {
+                                HandleShellNode(inner, parent, scriptPath, depth + 1);
+                            }
+                        }
+
+                        break;
+                    }
+                case ShellCaseNode caseNode:
+                    {
+                        foreach (var arm in caseNode.Arms)
+                        {
+                            foreach (var inner in arm.Body)
+                            {
+                                HandleShellNode(inner, parent, scriptPath, depth + 1);
+                            }
+                        }
+
+                        break;
+                    }
+                case ShellCommandNode commandNode:
+                    {
+                        var args = MaterializeArguments(commandNode.Arguments);
+                        if (args.Length == 0)
+                        {
+                            break;
+                        }
+
+                        // Skip shell built-in wrappers.
+                        if (args[0] is "command" or "env")
+                        {
+                            var sliced = args.Skip(1).ToImmutableArray();
+                            ResolveCommand(sliced, parent, ToEntryTraceSpan(commandNode.Span, scriptPath), depth + 1, "calls");
+                        }
+                        else
+                        {
+                            ResolveCommand(args, parent, ToEntryTraceSpan(commandNode.Span, scriptPath), depth + 1, "calls");
+                        }
+
+                        break;
+                    }
+                default:
+                    break;
+            }
+        }
+
+        private static EntryTraceSpan? ToEntryTraceSpan(ShellSpan span, string path)
+            => new(path, span.StartLine, span.StartColumn, span.EndLine, span.EndColumn);
+
+        private static ImmutableArray<string> MaterializeArguments(ImmutableArray<ShellToken> tokens)
+        {
+            var builder = ImmutableArray.CreateBuilder<string>(tokens.Length);
+            foreach (var token in tokens)
+            {
+                builder.Add(token.Value);
+            }
+
+            return builder.ToImmutable();
+        }
+
+        private string ResolveScriptPath(string currentScript, string candidate)
+        {
+            if (string.IsNullOrWhiteSpace(candidate))
+            {
+                return candidate;
+            }
+
+            if (candidate.StartsWith("/", StringComparison.Ordinal))
+            {
+                return NormalizeUnixPath(candidate);
+            }
+
+            if (candidate.StartsWith("$", StringComparison.Ordinal))
+            {
+                _diagnostics.Add(new EntryTraceDiagnostic(
+                    EntryTraceDiagnosticSeverity.Warning,
+                    EntryTraceUnknownReason.DynamicEnvironmentReference,
+                    $"Path '{candidate}' depends on environment variable expansion and cannot be resolved statically.",
+                    Span: null,
+                    RelatedPath: candidate));
+                return candidate;
+            }
+
+            var normalizedScript = NormalizeUnixPath(currentScript);
+            var lastSlash = normalizedScript.LastIndexOf('/');
+            var baseDirectory = lastSlash <= 0 ? "/" : normalizedScript[..lastSlash];
+            return CombineUnixPath(baseDirectory, candidate);
+        }
+
+        private static bool IsLikelyShell(string content)
+        {
+            if (string.IsNullOrEmpty(content))
+            {
+                return false;
+            }
+
+            if (content.StartsWith("#!", StringComparison.Ordinal))
+            {
+                return content.Contains("sh", StringComparison.OrdinalIgnoreCase);
+            }
+
+            return content.Contains("#!/bin/sh", StringComparison.Ordinal);
+        }
+
+        private EntryTraceNode AddNode(
+            EntryTraceNodeKind kind,
+            string displayName,
+            ImmutableArray<string> arguments,
+            EntryTraceInterpreterKind interpreterKind,
+            EntryTraceEvidence? evidence,
+            EntryTraceSpan? span)
+        {
+            var node = new EntryTraceNode(
+                _nextNodeId++,
+                kind,
+                displayName,
+                arguments,
+                interpreterKind,
+                evidence,
+                span);
+            _nodes.Add(node);
+            return node;
+        }
+
+        private static string CombineUnixPath(string baseDirectory, string relative)
+        {
+            var normalizedBase = NormalizeUnixPath(baseDirectory);
+            var trimmedRelative = relative.Replace('\\', '/').Trim();
+            if (string.IsNullOrEmpty(trimmedRelative))
+            {
+                return normalizedBase;
+            }
+
+            if (trimmedRelative.StartsWith('/'))
+            {
+                return NormalizeUnixPath(trimmedRelative);
+            }
+
+            if (!normalizedBase.EndsWith('/'))
+            {
+                normalizedBase += "/";
+            }
+
+            return NormalizeUnixPath(normalizedBase + trimmedRelative);
+        }
+
+        private static string NormalizeUnixPath(string path)
+        {
+            if (string.IsNullOrWhiteSpace(path))
+            {
+                return "/";
+            }
+
+            var text = path.Replace('\\', '/').Trim();
+            if (!text.StartsWith('/'))
+            {
+                text = "/" + text;
+            }
+
+            var segments = new List<string>();
+            foreach (var part in text.Split('/', StringSplitOptions.RemoveEmptyEntries))
+            {
+                if (part == ".")
+                {
+                    continue;
+                }
+
+                if (part == "..")
+                {
+                    if (segments.Count > 0)
+                    {
+                        segments.RemoveAt(segments.Count - 1);
+                    }
+                    continue;
+                }
+
+                segments.Add(part);
+            }
+
+            return segments.Count == 0 ? "/" : "/" + string.Join('/', segments);
+        }
+    }
+}

src/StellaOps.Scanner.EntryTrace/EntryTraceAnalyzerOptions.cs

@@ -0,0 +1,26 @@
+namespace StellaOps.Scanner.EntryTrace;
+
+public sealed class EntryTraceAnalyzerOptions
+{
+    public const string SectionName = "Scanner:Analyzers:EntryTrace";
+
+    /// <summary>
+    /// Maximum recursion depth while following includes/run-parts/interpreters.
+    /// </summary>
+    public int MaxDepth { get; set; } = 64;
+
+    /// <summary>
+    /// Enables traversal of run-parts directories.
+    /// </summary>
+    public bool FollowRunParts { get; set; } = true;
+
+    /// <summary>
+    /// Colon-separated default PATH string used when the environment omits PATH.
+    /// </summary>
+    public string DefaultPath { get; set; } = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+
+    /// <summary>
+    /// Maximum number of scripts considered per run-parts directory to prevent explosion.
+    /// </summary>
+    public int RunPartsLimit { get; set; } = 64;
+}

src/StellaOps.Scanner.EntryTrace/EntryTraceContext.cs

@@ -0,0 +1,16 @@
+using System.Collections.Immutable;
+using Microsoft.Extensions.Logging;
+
+namespace StellaOps.Scanner.EntryTrace;
+
+/// <summary>
+/// Provides runtime context for entry trace analysis.
+/// </summary>
+public sealed record EntryTraceContext(
+    IRootFileSystem FileSystem,
+    ImmutableDictionary<string, string> Environment,
+    ImmutableArray<string> Path,
+    string WorkingDirectory,
+    string ImageDigest,
+    string ScanId,
+    ILogger? Logger);

src/StellaOps.Scanner.EntryTrace/EntryTraceTypes.cs

@@ -0,0 +1,125 @@
+using System.Collections.Generic;
+using System.Collections.Immutable;
+
+namespace StellaOps.Scanner.EntryTrace;
+
+/// <summary>
+/// Outcome classification for entrypoint resolution attempts.
+/// </summary>
+public enum EntryTraceOutcome
+{
+    Resolved,
+    PartiallyResolved,
+    Unresolved
+}
+
+/// <summary>
+/// Logical classification for nodes in the entry trace graph.
+/// </summary>
+public enum EntryTraceNodeKind
+{
+    Command,
+    Script,
+    Include,
+    Interpreter,
+    Executable,
+    RunPartsDirectory,
+    RunPartsScript
+}
+
+/// <summary>
+/// Interpreter categories supported by the analyzer.
+/// </summary>
+public enum EntryTraceInterpreterKind
+{
+    None,
+    Python,
+    Node,
+    Java
+}
+
+/// <summary>
+/// Diagnostic severity levels emitted by the analyzer.
+/// </summary>
+public enum EntryTraceDiagnosticSeverity
+{
+    Info,
+    Warning,
+    Error
+}
+
+/// <summary>
+/// Enumerates the canonical reasons for unresolved edges.
+/// </summary>
+public enum EntryTraceUnknownReason
+{
+    CommandNotFound,
+    MissingFile,
+    DynamicEnvironmentReference,
+    UnsupportedSyntax,
+    RecursionLimitReached,
+    InterpreterNotSupported,
+    ModuleNotFound,
+    JarNotFound,
+    RunPartsEmpty,
+    PermissionDenied
+}
+
+/// <summary>
+/// Represents a span within a script file.
+/// </summary>
+public readonly record struct EntryTraceSpan(
+    string? Path,
+    int StartLine,
+    int StartColumn,
+    int EndLine,
+    int EndColumn);
+
+/// <summary>
+/// Evidence describing where a node originated from within the image.
+/// </summary>
+public sealed record EntryTraceEvidence(
+    string Path,
+    string? LayerDigest,
+    string Source,
+    IReadOnlyDictionary<string, string>? Metadata);
+
+/// <summary>
+/// Represents a node in the entry trace graph.
+/// </summary>
+public sealed record EntryTraceNode(
+    int Id,
+    EntryTraceNodeKind Kind,
+    string DisplayName,
+    ImmutableArray<string> Arguments,
+    EntryTraceInterpreterKind InterpreterKind,
+    EntryTraceEvidence? Evidence,
+    EntryTraceSpan? Span);
+
+/// <summary>
+/// Represents a directed edge in the entry trace graph.
+/// </summary>
+public sealed record EntryTraceEdge(
+    int FromNodeId,
+    int ToNodeId,
+    string Relationship,
+    IReadOnlyDictionary<string, string>? Metadata);
+
+/// <summary>
+/// Captures diagnostic information regarding resolution gaps.
+/// </summary>
+public sealed record EntryTraceDiagnostic(
+    EntryTraceDiagnosticSeverity Severity,
+    EntryTraceUnknownReason Reason,
+    string Message,
+    EntryTraceSpan? Span,
+    string? RelatedPath);
+
+/// <summary>
+/// Final graph output produced by the analyzer.
+/// </summary>
+public sealed record EntryTraceGraph(
+    EntryTraceOutcome Outcome,
+    ImmutableArray<EntryTraceNode> Nodes,
+    ImmutableArray<EntryTraceEdge> Edges,
+    ImmutableArray<EntryTraceDiagnostic> Diagnostics);

src/StellaOps.Scanner.EntryTrace/EntrypointSpecification.cs

@@ -0,0 +1,71 @@
+using System.Collections.Immutable;
+
+namespace StellaOps.Scanner.EntryTrace;
+
+/// <summary>
+/// Represents the combined Docker ENTRYPOINT/CMD contract provided to the analyzer.
+/// </summary>
+public sealed record EntrypointSpecification
+{
+    private EntrypointSpecification(
+        ImmutableArray<string> entrypoint,
+        ImmutableArray<string> command,
+        string? entrypointShell,
+        string? commandShell)
+    {
+        Entrypoint = entrypoint;
+        Command = command;
+        EntrypointShell = string.IsNullOrWhiteSpace(entrypointShell) ? null : entrypointShell;
+        CommandShell = string.IsNullOrWhiteSpace(commandShell) ? null : commandShell;
+    }
+
+    /// <summary>
+    /// Exec-form ENTRYPOINT arguments.
+    /// </summary>
+    public ImmutableArray<string> Entrypoint { get; }
+
+    /// <summary>
+    /// Exec-form CMD arguments.
+    /// </summary>
+    public ImmutableArray<string> Command { get; }
+
+    /// <summary>
+    /// Shell-form ENTRYPOINT (if provided).
+    /// </summary>
+    public string? EntrypointShell { get; }
+
+    /// <summary>
+    /// Shell-form CMD (if provided).
+    /// </summary>
+    public string? CommandShell { get; }
+
+    public static EntrypointSpecification FromExecForm(
+        IEnumerable<string>? entrypoint,
+        IEnumerable<string>? command)
+        => new(
+            entrypoint is null ? ImmutableArray<string>.Empty : entrypoint.ToImmutableArray(),
+            command is null ? ImmutableArray<string>.Empty : command.ToImmutableArray(),
+            entrypointShell: null,
+            commandShell: null);
+
+    public static EntrypointSpecification FromShellForm(
+        string? entrypoint,
+        string? command)
+        => new(
+            ImmutableArray<string>.Empty,
+            ImmutableArray<string>.Empty,
+            entrypoint,
+            command);
+
+    public EntrypointSpecification WithCommand(IEnumerable<string>? command)
+        => new(Entrypoint, command?.ToImmutableArray() ?? ImmutableArray<string>.Empty, EntrypointShell, CommandShell);
+
+    public EntrypointSpecification WithCommandShell(string? commandShell)
+        => new(Entrypoint, Command, EntrypointShell, commandShell);
+
+    public EntrypointSpecification WithEntrypoint(IEnumerable<string>? entrypoint)
+        => new(entrypoint?.ToImmutableArray() ?? ImmutableArray<string>.Empty, Command, EntrypointShell, CommandShell);
+
+    public EntrypointSpecification WithEntrypointShell(string? entrypointShell)
+        => new(Entrypoint, Command, entrypointShell, CommandShell);
+}

src/StellaOps.Scanner.EntryTrace/FileSystem/IRootFileSystem.cs

@@ -0,0 +1,39 @@
+using System.Collections.Immutable;
+
+namespace StellaOps.Scanner.EntryTrace;
+
+/// <summary>
+/// Represents a layered read-only filesystem snapshot built from container layers.
+/// </summary>
+public interface IRootFileSystem
+{
+    /// <summary>
+    /// Attempts to resolve an executable by name using the provided PATH entries.
+    /// </summary>
+    bool TryResolveExecutable(string name, IReadOnlyList<string> searchPaths, out RootFileDescriptor descriptor);
+
+    /// <summary>
+    /// Attempts to read the contents of a file as UTF-8 text.
+    /// </summary>
+    bool TryReadAllText(string path, out RootFileDescriptor descriptor, out string content);
+
+    /// <summary>
+    /// Returns descriptors for entries contained within a directory.
+    /// </summary>
+    ImmutableArray<RootFileDescriptor> EnumerateDirectory(string path);
+
+    /// <summary>
+    /// Checks whether a directory exists.
+    /// </summary>
+    bool DirectoryExists(string path);
+}
+
+/// <summary>
+/// Describes a file discovered within the layered filesystem.
+/// </summary>
+public sealed record RootFileDescriptor(
+    string Path,
+    string? LayerDigest,
+    bool IsExecutable,
+    bool IsDirectory,
+    string? ShebangInterpreter);

src/StellaOps.Scanner.EntryTrace/IEntryTraceAnalyzer.cs

@@ -0,0 +1,9 @@
+namespace StellaOps.Scanner.EntryTrace;
+
+public interface IEntryTraceAnalyzer
+{
+    ValueTask<EntryTraceGraph> ResolveAsync(
+        EntrypointSpecification entrypoint,
+        EntryTraceContext context,
+        CancellationToken cancellationToken = default);
+}

src/StellaOps.Scanner.EntryTrace/Parsing/ShellNodes.cs

@@ -0,0 +1,54 @@
+using System.Collections.Immutable;
+
+namespace StellaOps.Scanner.EntryTrace.Parsing;
+
+public abstract record ShellNode(ShellSpan Span);
+
+public sealed record ShellScript(ImmutableArray<ShellNode> Nodes);
+
+public sealed record ShellSpan(int StartLine, int StartColumn, int EndLine, int EndColumn);
+
+public sealed record ShellCommandNode(
+    string Command,
+    ImmutableArray<ShellToken> Arguments,
+    ShellSpan Span) : ShellNode(Span);
+
+public sealed record ShellIncludeNode(
+    string PathExpression,
+    ImmutableArray<ShellToken> Arguments,
+    ShellSpan Span) : ShellNode(Span);
+
+public sealed record ShellExecNode(
+    ImmutableArray<ShellToken> Arguments,
+    ShellSpan Span) : ShellNode(Span);
+
+public sealed record ShellIfNode(
+    ImmutableArray<ShellConditionalBranch> Branches,
+    ShellSpan Span) : ShellNode(Span);
+
+public sealed record ShellConditionalBranch(
+    ShellConditionalKind Kind,
+    ImmutableArray<ShellNode> Body,
+    ShellSpan Span,
+    string? PredicateSummary);
+
+public enum ShellConditionalKind
+{
+    If,
+    Elif,
+    Else
+}
+
+public sealed record ShellCaseNode(
+    ImmutableArray<ShellCaseArm> Arms,
+    ShellSpan Span) : ShellNode(Span);
+
+public sealed record ShellCaseArm(
+    ImmutableArray<string> Patterns,
+    ImmutableArray<ShellNode> Body,
+    ShellSpan Span);
+
+public sealed record ShellRunPartsNode(
+    string DirectoryExpression,
+    ImmutableArray<ShellToken> Arguments,
+    ShellSpan Span) : ShellNode(Span);

src/StellaOps.Scanner.EntryTrace/Parsing/ShellParser.cs

@@ -0,0 +1,485 @@
+using System.Collections.Immutable;
+using System.Globalization;
+using System.Linq;
+using System.Text;
+
+namespace StellaOps.Scanner.EntryTrace.Parsing;
+
+/// <summary>
+/// Deterministic parser producing a lightweight AST for Bourne shell constructs needed by EntryTrace.
+/// Supports: simple commands, exec, source/dot, run-parts, if/elif/else/fi, case/esac.
+/// </summary>
+public sealed class ShellParser
+{
+    private readonly IReadOnlyList<ShellToken> _tokens;
+    private int _index;
+
+    private ShellParser(IReadOnlyList<ShellToken> tokens)
+    {
+        _tokens = tokens;
+    }
+
+    public static ShellScript Parse(string source)
+    {
+        var tokenizer = new ShellTokenizer();
+        var tokens = tokenizer.Tokenize(source);
+        var parser = new ShellParser(tokens);
+        var nodes = parser.ParseNodes(untilKeywords: null);
+        return new ShellScript(nodes.ToImmutableArray());
+    }
+
+    private List<ShellNode> ParseNodes(HashSet<string>? untilKeywords)
+    {
+        var nodes = new List<ShellNode>();
+
+        while (true)
+        {
+            SkipNewLines();
+            var token = Peek();
+
+            if (token.Kind == ShellTokenKind.EndOfFile)
+            {
+                break;
+            }
+
+            if (token.Kind == ShellTokenKind.Word && untilKeywords is not null && untilKeywords.Contains(token.Value))
+            {
+                break;
+            }
+
+            ShellNode? node = token.Kind switch
+            {
+                ShellTokenKind.Word when token.Value == "if" => ParseIf(),
+                ShellTokenKind.Word when token.Value == "case" => ParseCase(),
+                _ => ParseCommandLike()
+            };
+
+            if (node is not null)
+            {
+                nodes.Add(node);
+            }
+
+            SkipCommandSeparators();
+        }
+
+        return nodes;
+    }
+
+    private ShellNode ParseCommandLike()
+    {
+        var start = Peek();
+        var tokens = ReadUntilTerminator();
+
+        if (tokens.Count == 0)
+        {
+            return new ShellCommandNode(string.Empty, ImmutableArray<ShellToken>.Empty, CreateSpan(start, start));
+        }
+
+        var normalizedName = ExtractCommandName(tokens);
+        var immutableTokens = tokens.ToImmutableArray();
+        var span = CreateSpan(tokens[0], tokens[^1]);
+
+        return normalizedName switch
+        {
+            "exec" => new ShellExecNode(immutableTokens, span),
+            "source" or "." => new ShellIncludeNode(
+                ExtractPrimaryArgument(immutableTokens),
+                immutableTokens,
+                span),
+            "run-parts" => new ShellRunPartsNode(
+                ExtractPrimaryArgument(immutableTokens),
+                immutableTokens,
+                span),
+            _ => new ShellCommandNode(normalizedName, immutableTokens, span)
+        };
+    }
+
+    private ShellIfNode ParseIf()
+    {
+        var start = Expect(ShellTokenKind.Word, "if");
+        var predicateTokens = ReadUntilKeyword("then");
+        Expect(ShellTokenKind.Word, "then");
+
+        var branches = new List<ShellConditionalBranch>();
+        var predicateSummary = JoinTokens(predicateTokens);
+        var thenNodes = ParseNodes(new HashSet<string>(StringComparer.Ordinal)
+        {
+            "elif",
+            "else",
+            "fi"
+        });
+
+        branches.Add(new ShellConditionalBranch(
+            ShellConditionalKind.If,
+            thenNodes.ToImmutableArray(),
+            CreateSpan(start, thenNodes.LastOrDefault()?.Span ?? CreateSpan(start, start)),
+            predicateSummary));
+
+        while (true)
+        {
+            SkipNewLines();
+            var next = Peek();
+            if (next.Kind != ShellTokenKind.Word)
+            {
+                break;
+            }
+
+            if (next.Value == "elif")
+            {
+                var elifStart = Advance();
+                var elifPredicate = ReadUntilKeyword("then");
+                Expect(ShellTokenKind.Word, "then");
+                var elifBody = ParseNodes(new HashSet<string>(StringComparer.Ordinal)
+                {
+                    "elif",
+                    "else",
+                    "fi"
+                });
+                var span = elifBody.Count > 0
+                    ? CreateSpan(elifStart, elifBody[^1].Span)
+                    : CreateSpan(elifStart, elifStart);
+
+                branches.Add(new ShellConditionalBranch(
+                    ShellConditionalKind.Elif,
+                    elifBody.ToImmutableArray(),
+                    span,
+                    JoinTokens(elifPredicate)));
+                continue;
+            }
+
+            if (next.Value == "else")
+            {
+                var elseStart = Advance();
+                var elseBody = ParseNodes(new HashSet<string>(StringComparer.Ordinal)
+                {
+                    "fi"
+                });
+                branches.Add(new ShellConditionalBranch(
+                    ShellConditionalKind.Else,
+                    elseBody.ToImmutableArray(),
+                    elseBody.Count > 0 ? CreateSpan(elseStart, elseBody[^1].Span) : CreateSpan(elseStart, elseStart),
+                    null));
+                break;
+            }
+
+            break;
+        }
+
+        Expect(ShellTokenKind.Word, "fi");
+        var end = Previous();
+        return new ShellIfNode(branches.ToImmutableArray(), CreateSpan(start, end));
+    }
+
+    private ShellCaseNode ParseCase()
+    {
+        var start = Expect(ShellTokenKind.Word, "case");
+        var selectorTokens = ReadUntilKeyword("in");
+        Expect(ShellTokenKind.Word, "in");
+
+        var arms = new List<ShellCaseArm>();
+        while (true)
+        {
+            SkipNewLines();
+            var token = Peek();
+            if (token.Kind == ShellTokenKind.Word && token.Value == "esac")
+            {
+                break;
+            }
+
+            if (token.Kind == ShellTokenKind.EndOfFile)
+            {
+                throw new FormatException("Unexpected end of file while parsing case arms.");
+            }
+
+            var patterns = ReadPatterns();
+            Expect(ShellTokenKind.Operator, ")");
+
+            var body = ParseNodes(new HashSet<string>(StringComparer.Ordinal)
+            {
+                ";;",
+                "esac"
+            });
+
+            ShellSpan span;
+            if (body.Count > 0)
+            {
+                span = CreateSpan(patterns.FirstToken ?? token, body[^1].Span);
+            }
+            else
+            {
+                span = CreateSpan(patterns.FirstToken ?? token, token);
+            }
+
+            arms.Add(new ShellCaseArm(
+                patterns.Values.ToImmutableArray(),
+                body.ToImmutableArray(),
+                span));
+
+            SkipNewLines();
+            var separator = Peek();
+            if (separator.Kind == ShellTokenKind.Operator && separator.Value == ";;")
+            {
+                Advance();
+                continue;
+            }
+
+            if (separator.Kind == ShellTokenKind.Word && separator.Value == "esac")
+            {
+                break;
+            }
+        }
+
+        Expect(ShellTokenKind.Word, "esac");
+        return new ShellCaseNode(arms.ToImmutableArray(), CreateSpan(start, Previous()));
+
+        (List<string> Values, ShellToken? FirstToken) ReadPatterns()
+        {
+            var values = new List<string>();
+            ShellToken? first = null;
+            var sb = new StringBuilder();
+
+            while (true)
+            {
+                var current = Peek();
+                if (current.Kind is ShellTokenKind.Operator && current.Value is ")" or "|")
+                {
+                    if (sb.Length > 0)
+                    {
+                        values.Add(sb.ToString());
+                        sb.Clear();
+                    }
+
+                    if (current.Value == "|")
+                    {
+                        Advance();
+                        continue;
+                    }
+
+                    break;
+                }
+
+                if (current.Kind == ShellTokenKind.EndOfFile)
+                {
+                    throw new FormatException("Unexpected EOF in case arm pattern.");
+                }
+
+                if (first is null)
+                {
+                    first = current;
+                }
+
+                sb.Append(current.Value);
+                Advance();
+            }
+
+            if (values.Count == 0 && sb.Length > 0)
+            {
+                values.Add(sb.ToString());
+            }
+
+            return (values, first);
+        }
+    }
+
+    private List<ShellToken> ReadUntilTerminator()
+    {
+        var tokens = new List<ShellToken>();
+        while (true)
+        {
+            var token = Peek();
+            if (token.Kind is ShellTokenKind.EndOfFile or ShellTokenKind.NewLine)
+            {
+                break;
+            }
+
+            if (token.Kind == ShellTokenKind.Operator && token.Value is ";" or "&&" or "||")
+            {
+                break;
+            }
+
+            tokens.Add(Advance());
+        }
+
+        return tokens;
+    }
+
+    private ImmutableArray<ShellToken> ReadUntilKeyword(string keyword)
+    {
+        var tokens = new List<ShellToken>();
+        while (true)
+        {
+            var token = Peek();
+            if (token.Kind == ShellTokenKind.EndOfFile)
+            {
+                throw new FormatException($"Unexpected EOF while looking for keyword '{keyword}'.");
+            }
+
+            if (token.Kind == ShellTokenKind.Word && token.Value == keyword)
+            {
+                break;
+            }
+
+            tokens.Add(Advance());
+        }
+
+        return tokens.ToImmutableArray();
+    }
+
+    private static string ExtractCommandName(IReadOnlyList<ShellToken> tokens)
+    {
+        foreach (var token in tokens)
+        {
+            if (token.Kind is not ShellTokenKind.Word and not ShellTokenKind.SingleQuoted and not ShellTokenKind.DoubleQuoted)
+            {
+                continue;
+            }
+
+            if (token.Value.Contains('=', StringComparison.Ordinal))
+            {
+                // Skip environment assignments e.g. FOO=bar exec /app
+                var eqIndex = token.Value.IndexOf('=', StringComparison.Ordinal);
+                if (eqIndex > 0 && token.Value[..eqIndex].All(IsIdentifierChar))
+                {
+                    continue;
+                }
+            }
+
+            return NormalizeCommandName(token.Value);
+        }
+
+        return string.Empty;
+
+        static bool IsIdentifierChar(char c) => char.IsLetterOrDigit(c) || c == '_';
+    }
+
+    private static string NormalizeCommandName(string value)
+    {
+        if (string.IsNullOrEmpty(value))
+        {
+            return string.Empty;
+        }
+
+        return value switch
+        {
+            "." => ".",
+            _ => value.Trim()
+        };
+    }
+
+    private void SkipCommandSeparators()
+    {
+        while (true)
+        {
+            var token = Peek();
+            if (token.Kind == ShellTokenKind.NewLine)
+            {
+                Advance();
+                continue;
+            }
+
+            if (token.Kind == ShellTokenKind.Operator && (token.Value == ";" || token.Value == "&"))
+            {
+                Advance();
+                continue;
+            }
+
+            break;
+        }
+    }
+
+    private void SkipNewLines()
+    {
+        while (Peek().Kind == ShellTokenKind.NewLine)
+        {
+            Advance();
+        }
+    }
+
+    private ShellToken Expect(ShellTokenKind kind, string? value = null)
+    {
+        var token = Peek();
+        if (token.Kind != kind || (value is not null && token.Value != value))
+        {
+            throw new FormatException($"Unexpected token '{token.Value}' at line {token.Line}, expected {value ?? kind.ToString()}.");
+        }
+
+        return Advance();
+    }
+
+    private ShellToken Advance()
+    {
+        if (_index >= _tokens.Count)
+        {
+            return _tokens[^1];
+        }
+
+        return _tokens[_index++];
+    }
+
+    private ShellToken Peek()
+    {
+        if (_index >= _tokens.Count)
+        {
+            return _tokens[^1];
+        }
+
+        return _tokens[_index];
+    }
+
+    private ShellToken Previous()
+    {
+        if (_index == 0)
+        {
+            return _tokens[0];
+        }
+
+        return _tokens[_index - 1];
+    }
+
+    private static ShellSpan CreateSpan(ShellToken start, ShellToken end)
+    {
+        return new ShellSpan(start.Line, start.Column, end.Line, end.Column + end.Value.Length);
+    }
+
+    private static ShellSpan CreateSpan(ShellToken start, ShellSpan end)
+    {
+        return new ShellSpan(start.Line, start.Column, end.EndLine, end.EndColumn);
+    }
+
+    private static string JoinTokens(IEnumerable<ShellToken> tokens)
+    {
+        var builder = new StringBuilder();
+        var first = true;
+        foreach (var token in tokens)
+        {
+            if (!first)
+            {
+                builder.Append(' ');
+            }
+
+            builder.Append(token.Value);
+            first = false;
+        }
+
+        return builder.ToString();
+    }
+
+    private static string ExtractPrimaryArgument(ImmutableArray<ShellToken> tokens)
+    {
+        if (tokens.Length <= 1)
+        {
+            return string.Empty;
+        }
+
+        for (var i = 1; i < tokens.Length; i++)
+        {
+            var token = tokens[i];
+            if (token.Kind is ShellTokenKind.Word or ShellTokenKind.SingleQuoted or ShellTokenKind.DoubleQuoted)
+            {
+                return token.Value;
+            }
+        }
+
+        return string.Empty;
+    }
+}

src/StellaOps.Scanner.EntryTrace/Parsing/ShellToken.cs

@@ -0,0 +1,16 @@
+namespace StellaOps.Scanner.EntryTrace.Parsing;
+
+/// <summary>
+/// Token produced by the shell lexer.
+/// </summary>
+public readonly record struct ShellToken(ShellTokenKind Kind, string Value, int Line, int Column);
+
+public enum ShellTokenKind
+{
+    Word,
+    SingleQuoted,
+    DoubleQuoted,
+    Operator,
+    NewLine,
+    EndOfFile
+}

src/StellaOps.Scanner.EntryTrace/Parsing/ShellTokenizer.cs

@@ -0,0 +1,200 @@
+using System.Globalization;
+using System.Text;
+
+namespace StellaOps.Scanner.EntryTrace.Parsing;
+
+/// <summary>
+/// Lightweight Bourne shell tokenizer sufficient for ENTRYPOINT scripts.
+/// Deterministic: emits tokens in source order without normalization.
+/// </summary>
+public sealed class ShellTokenizer
+{
+    public IReadOnlyList<ShellToken> Tokenize(string source)
+    {
+        if (source is null)
+        {
+            throw new ArgumentNullException(nameof(source));
+        }
+
+        var tokens = new List<ShellToken>();
+        var line = 1;
+        var column = 1;
+        var index = 0;
+
+        while (index < source.Length)
+        {
+            var ch = source[index];
+
+            if (ch == '\r')
+            {
+                index++;
+                continue;
+            }
+
+            if (ch == '\n')
+            {
+                tokens.Add(new ShellToken(ShellTokenKind.NewLine, "\n", line, column));
+                index++;
+                line++;
+                column = 1;
+                continue;
+            }
+
+            if (char.IsWhiteSpace(ch))
+            {
+                index++;
+                column++;
+                continue;
+            }
+
+            if (ch == '#')
+            {
+                // Comment: skip until newline.
+                while (index < source.Length && source[index] != '\n')
+                {
+                    index++;
+                }
+                continue;
+            }
+
+            if (IsOperatorStart(ch))
+            {
+                var opStartColumn = column;
+                var op = ConsumeOperator(source, ref index, ref column);
+                tokens.Add(new ShellToken(ShellTokenKind.Operator, op, line, opStartColumn));
+                continue;
+            }
+
+            if (ch == '\'')
+            {
+                var (value, length) = ConsumeSingleQuoted(source, index + 1);
+                tokens.Add(new ShellToken(ShellTokenKind.SingleQuoted, value, line, column));
+                index += length + 2;
+                column += length + 2;
+                continue;
+            }
+
+            if (ch == '"')
+            {
+                var (value, length) = ConsumeDoubleQuoted(source, index + 1);
+                tokens.Add(new ShellToken(ShellTokenKind.DoubleQuoted, value, line, column));
+                index += length + 2;
+                column += length + 2;
+                continue;
+            }
+
+            var (word, consumed) = ConsumeWord(source, index);
+            tokens.Add(new ShellToken(ShellTokenKind.Word, word, line, column));
+            index += consumed;
+            column += consumed;
+        }
+
+        tokens.Add(new ShellToken(ShellTokenKind.EndOfFile, string.Empty, line, column));
+        return tokens;
+    }
+
+    private static bool IsOperatorStart(char ch) => ch switch
+    {
+        ';' or '&' or '|' or '(' or ')' => true,
+        _ => false
+    };
+
+    private static string ConsumeOperator(string source, ref int index, ref int column)
+    {
+        var start = index;
+        var ch = source[index];
+        index++;
+        column++;
+
+        if (index < source.Length)
+        {
+            var next = source[index];
+            if ((ch == '&' && next == '&') ||
+                (ch == '|' && next == '|') ||
+                (ch == ';' && next == ';'))
+            {
+                index++;
+                column++;
+            }
+        }
+
+        return source[start..index];
+    }
+
+    private static (string Value, int Length) ConsumeSingleQuoted(string source, int startIndex)
+    {
+        var end = startIndex;
+        while (end < source.Length && source[end] != '\'')
+        {
+            end++;
+        }
+
+        if (end >= source.Length)
+        {
+            throw new FormatException("Unterminated single-quoted string in entrypoint script.");
+        }
+
+        return (source[startIndex..end], end - startIndex);
+    }
+
+    private static (string Value, int Length) ConsumeDoubleQuoted(string source, int startIndex)
+    {
+        var builder = new StringBuilder();
+        var index = startIndex;
+
+        while (index < source.Length)
+        {
+            var ch = source[index];
+            if (ch == '"')
+            {
+                return (builder.ToString(), index - startIndex);
+            }
+
+            if (ch == '\\' && index + 1 < source.Length)
+            {
+                var next = source[index + 1];
+                if (next is '"' or '\\' or '$' or '`' or '\n')
+                {
+                    builder.Append(next);
+                    index += 2;
+                    continue;
+                }
+            }
+
+            builder.Append(ch);
+            index++;
+        }
+
+        throw new FormatException("Unterminated double-quoted string in entrypoint script.");
+    }
+
+    private static (string Value, int Length) ConsumeWord(string source, int startIndex)
+    {
+        var index = startIndex;
+        while (index < source.Length)
+        {
+            var ch = source[index];
+            if (char.IsWhiteSpace(ch) || ch == '\n' || ch == '\r' || IsOperatorStart(ch) || ch == '#' )
+            {
+                break;
+            }
+
+            if (ch == '\\' && index + 1 < source.Length && source[index + 1] == '\n')
+            {
+                // Line continuation.
+                index += 2;
+                continue;
+            }
+
+            index++;
+        }
+
+        if (index == startIndex)
+        {
+            throw new InvalidOperationException("Tokenizer failed to advance while consuming word.");
+        }
+
+        var text = source[startIndex..index];
+        return (text, index - startIndex);
+    }
+}

src/StellaOps.Scanner.EntryTrace/ServiceCollectionExtensions.cs

@@ -0,0 +1,29 @@
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+using Microsoft.Extensions.Options;
+using StellaOps.Scanner.EntryTrace.Diagnostics;
+
+namespace StellaOps.Scanner.EntryTrace;
+
+public static class ServiceCollectionExtensions
+{
+    public static IServiceCollection AddEntryTraceAnalyzer(this IServiceCollection services, Action<EntryTraceAnalyzerOptions>? configure = null)
+    {
+        if (services is null)
+        {
+            throw new ArgumentNullException(nameof(services));
+        }
+
+        services.AddOptions<EntryTraceAnalyzerOptions>()
+            .BindConfiguration(EntryTraceAnalyzerOptions.SectionName);
+
+        if (configure is not null)
+        {
+            services.Configure(configure);
+        }
+
+        services.TryAddSingleton<EntryTraceMetrics>();
+        services.TryAddSingleton<IEntryTraceAnalyzer, EntryTraceAnalyzer>();
+        return services;
+    }
+}

src/StellaOps.Scanner.EntryTrace/StellaOps.Scanner.EntryTrace.csproj

@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <LangVersion>preview</LangVersion>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="9.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Options" Version="9.0.0" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="9.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Options.ConfigurationExtensions" Version="9.0.0" />
+  </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\StellaOps.Plugin\StellaOps.Plugin.csproj" />
+  </ItemGroup>
+</Project>

src/StellaOps.Scanner.EntryTrace/TASKS.md

@@ -0,0 +1,11 @@
+# EntryTrace Analyzer Task Board (Sprint 10)
+
+| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
+|----|--------|----------|------------|-------------|---------------|
+| SCANNER-ENTRYTRACE-10-401 | DONE (2025-10-19) | EntryTrace Guild | Scanner Core contracts | Implement deterministic POSIX shell AST parser covering exec/command/source/run-parts/case/if used by ENTRYPOINT scripts. | Parser emits stable AST and serialization tests prove determinism for representative fixtures; see `ShellParserTests`. |
+| SCANNER-ENTRYTRACE-10-402 | DONE (2025-10-19) | EntryTrace Guild | SCANNER-ENTRYTRACE-10-401 | Resolve commands across layered rootfs, tracking evidence per hop (PATH hit, layer origin, shebang). | Resolver returns terminal program path with layer attribution for fixtures; deterministic traversal asserted in `EntryTraceAnalyzerTests.ResolveAsync_IsDeterministic`. |
+| SCANNER-ENTRYTRACE-10-403 | DONE (2025-10-19) | EntryTrace Guild | SCANNER-ENTRYTRACE-10-402 | Follow interpreter wrappers (shell → Python/Node/Java launchers) to terminal target, including module/jar detection. | Interpreter tracer reports correct module/script for language launchers; tests cover Python/Node/Java wrappers. |
+| SCANNER-ENTRYTRACE-10-404 | DONE (2025-10-19) | EntryTrace Guild | SCANNER-ENTRYTRACE-10-403 | Build Python entry analyzer detecting venv shebangs, module invocations, `-m` usage and record usage flag. | Python fixtures produce expected module metadata (`python-module` edge) and diagnostics for missing scripts. |
+| SCANNER-ENTRYTRACE-10-405 | DONE (2025-10-19) | EntryTrace Guild | SCANNER-ENTRYTRACE-10-403 | Implement Node/Java launcher analyzer capturing script/jar targets including npm lifecycle wrappers. | Node/Java fixtures resolved with evidence chain; `RunParts` coverage ensures child scripts traced. |
+| SCANNER-ENTRYTRACE-10-406 | DONE (2025-10-19) | EntryTrace Guild | SCANNER-ENTRYTRACE-10-402 | Surface explainability + diagnostics for unresolved constructs and emit metrics counters. | Diagnostics catalog enumerates unknown reasons; metrics wired via `EntryTraceMetrics`; explainability doc updated. |
+| SCANNER-ENTRYTRACE-10-407 | DONE (2025-10-19) | EntryTrace Guild | SCANNER-ENTRYTRACE-10-401..406 | Package EntryTrace analyzers as restart-time plug-ins with manifest + host registration. | Plug-in manifest under `plugins/scanner/entrytrace/`; restart-only policy documented; DI extension exposes `AddEntryTraceAnalyzer`. |

src/StellaOps.Scanner.Sbomer.BuildXPlugin.Tests/Descriptor/DescriptorGoldenTests.cs

@@ -0,0 +1,132 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using System.Text.Json.Serialization;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Time.Testing;
+using StellaOps.Scanner.Sbomer.BuildXPlugin.Descriptor;
+using StellaOps.Scanner.Sbomer.BuildXPlugin.Tests.TestUtilities;
+using Xunit;
+
+namespace StellaOps.Scanner.Sbomer.BuildXPlugin.Tests.Descriptor;
+
+public sealed class DescriptorGoldenTests
+{
+    private static readonly JsonSerializerOptions SerializerOptions = new(JsonSerializerDefaults.Web)
+    {
+        WriteIndented = true,
+        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
+    };
+
+    [Fact]
+    public async Task DescriptorMatchesBaselineFixture()
+    {
+        await using var temp = new TempDirectory();
+        var sbomPath = Path.Combine(temp.Path, "sample.cdx.json");
+        await File.WriteAllTextAsync(sbomPath, "{\"bomFormat\":\"CycloneDX\",\"specVersion\":\"1.5\"}");
+
+        var request = new DescriptorRequest
+        {
+            ImageDigest = "sha256:0123456789abcdef",
+            SbomPath = sbomPath,
+            SbomMediaType = "application/vnd.cyclonedx+json",
+            SbomFormat = "cyclonedx-json",
+            SbomKind = "inventory",
+            SbomArtifactType = "application/vnd.stellaops.sbom.layer+json",
+            SubjectMediaType = "application/vnd.oci.image.manifest.v1+json",
+            GeneratorVersion = "1.2.3",
+            GeneratorName = "StellaOps.Scanner.Sbomer.BuildXPlugin",
+            LicenseId = "lic-123",
+            SbomName = "sample.cdx.json",
+            Repository = "git.stella-ops.org/stellaops",
+            BuildRef = "refs/heads/main",
+            AttestorUri = "https://attestor.local/api/v1/provenance"
+        }.Validate();
+
+        var fakeTime = new FakeTimeProvider(new DateTimeOffset(2025, 10, 18, 12, 0, 0, TimeSpan.Zero));
+        var generator = new DescriptorGenerator(fakeTime);
+        var document = await generator.CreateAsync(request, CancellationToken.None);
+        var actualJson = JsonSerializer.Serialize(document, SerializerOptions);
+        var normalizedJson = NormalizeDescriptorJson(actualJson, Path.GetFileName(sbomPath));
+
+        var projectRoot = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "..", "..", ".."));
+        var fixturePath = Path.Combine(projectRoot, "Fixtures", "descriptor.baseline.json");
+        var updateRequested = string.Equals(Environment.GetEnvironmentVariable("UPDATE_BUILDX_FIXTURES"), "1", StringComparison.OrdinalIgnoreCase);
+
+        if (updateRequested)
+        {
+            Directory.CreateDirectory(Path.GetDirectoryName(fixturePath)!);
+            await File.WriteAllTextAsync(fixturePath, normalizedJson);
+            return;
+        }
+
+        if (!File.Exists(fixturePath))
+        {
+            throw new InvalidOperationException($"Baseline fixture '{fixturePath}' is missing. Set UPDATE_BUILDX_FIXTURES=1 and re-run the tests to generate it.");
+        }
+
+        var baselineJson = await File.ReadAllTextAsync(fixturePath);
+
+        using var baselineDoc = JsonDocument.Parse(baselineJson);
+        using var actualDoc = JsonDocument.Parse(normalizedJson);
+
+        AssertJsonEquivalent(baselineDoc.RootElement, actualDoc.RootElement);
+    }
+
+    private static string NormalizeDescriptorJson(string json, string sbomFileName)
+    {
+        var node = JsonNode.Parse(json)?.AsObject()
+                   ?? throw new InvalidOperationException("Failed to parse descriptor JSON for normalization.");
+
+        if (node["metadata"] is JsonObject metadata)
+        {
+            metadata["sbomPath"] = sbomFileName;
+        }
+
+        return node.ToJsonString(SerializerOptions);
+    }
+
+    private static void AssertJsonEquivalent(JsonElement expected, JsonElement actual)
+    {
+        if (expected.ValueKind != actual.ValueKind)
+        {
+            throw new Xunit.Sdk.XunitException($"Value kind mismatch. Expected '{expected.ValueKind}' but found '{actual.ValueKind}'.");
+        }
+
+        switch (expected.ValueKind)
+        {
+            case JsonValueKind.Object:
+                var expectedProperties = expected.EnumerateObject().ToDictionary(p => p.Name, p => p.Value, StringComparer.Ordinal);
+                var actualProperties = actual.EnumerateObject().ToDictionary(p => p.Name, p => p.Value, StringComparer.Ordinal);
+
+                Assert.Equal(
+                    expectedProperties.Keys.OrderBy(static name => name).ToArray(),
+                    actualProperties.Keys.OrderBy(static name => name).ToArray());
+
+                foreach (var propertyName in expectedProperties.Keys)
+                {
+                    AssertJsonEquivalent(expectedProperties[propertyName], actualProperties[propertyName]);
+                }
+
+                break;
+            case JsonValueKind.Array:
+                var expectedItems = expected.EnumerateArray().ToArray();
+                var actualItems = actual.EnumerateArray().ToArray();
+
+                Assert.Equal(expectedItems.Length, actualItems.Length);
+                for (var i = 0; i < expectedItems.Length; i++)
+                {
+                    AssertJsonEquivalent(expectedItems[i], actualItems[i]);
+                }
+
+                break;
+            default:
+                Assert.Equal(expected.ToString(), actual.ToString());
+                break;
+        }
+    }
+}

src/StellaOps.Scanner.Sbomer.BuildXPlugin.Tests/Fixtures/descriptor.baseline.json

@@ -0,0 +1,45 @@
+{
+  "schema": "stellaops.buildx.descriptor.v1",
+  "generatedAt": "2025-10-18T12:00:00\u002B00:00",
+  "generator": {
+    "name": "StellaOps.Scanner.Sbomer.BuildXPlugin",
+    "version": "1.2.3"
+  },
+  "subject": {
+    "mediaType": "application/vnd.oci.image.manifest.v1\u002Bjson",
+    "digest": "sha256:0123456789abcdef"
+  },
+  "artifact": {
+    "mediaType": "application/vnd.cyclonedx\u002Bjson",
+    "digest": "sha256:d07d06ae82e1789a5b505731f3ec3add106e23a55395213c9a881c7e816c695c",
+    "size": 45,
+    "annotations": {
+      "org.opencontainers.artifact.type": "application/vnd.stellaops.sbom.layer\u002Bjson",
+      "org.stellaops.scanner.version": "1.2.3",
+      "org.stellaops.sbom.kind": "inventory",
+      "org.stellaops.sbom.format": "cyclonedx-json",
+      "org.stellaops.provenance.status": "pending",
+      "org.stellaops.provenance.dsse.sha256": "sha256:1b364a6b888d580feb8565f7b6195b24535ca8201b4bcac58da063b32c47220d",
+      "org.stellaops.provenance.nonce": "a608acf859cd58a8389816b8d9eb2a07",
+      "org.stellaops.license.id": "lic-123",
+      "org.opencontainers.image.title": "sample.cdx.json",
+      "org.stellaops.repository": "git.stella-ops.org/stellaops"
+    }
+  },
+  "provenance": {
+    "status": "pending",
+    "expectedDsseSha256": "sha256:1b364a6b888d580feb8565f7b6195b24535ca8201b4bcac58da063b32c47220d",
+    "nonce": "a608acf859cd58a8389816b8d9eb2a07",
+    "attestorUri": "https://attestor.local/api/v1/provenance",
+    "predicateType": "https://slsa.dev/provenance/v1"
+  },
+  "metadata": {
+    "sbomDigest": "sha256:d07d06ae82e1789a5b505731f3ec3add106e23a55395213c9a881c7e816c695c",
+    "sbomPath": "sample.cdx.json",
+    "sbomMediaType": "application/vnd.cyclonedx\u002Bjson",
+    "subjectMediaType": "application/vnd.oci.image.manifest.v1\u002Bjson",
+    "repository": "git.stella-ops.org/stellaops",
+    "buildRef": "refs/heads/main",
+    "attestorUri": "https://attestor.local/api/v1/provenance"
+  }
+}

src/StellaOps.Scanner.Sbomer.BuildXPlugin.Tests/StellaOps.Scanner.Sbomer.BuildXPlugin.Tests.csproj

@@ -1,11 +1,17 @@
-<Project Sdk="Microsoft.NET.Sdk">
-  <PropertyGroup>
-    <TargetFramework>net10.0</TargetFramework>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <Nullable>enable</Nullable>
-  </PropertyGroup>
-
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
   <ItemGroup>
     <ProjectReference Include="..\StellaOps.Scanner.Sbomer.BuildXPlugin\StellaOps.Scanner.Sbomer.BuildXPlugin.csproj" />
   </ItemGroup>
+
+  <ItemGroup>
+    <None Include="Fixtures\descriptor.baseline.json">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
 </Project>

src/StellaOps.Scanner.Sbomer.BuildXPlugin/Descriptor/DescriptorGenerator.cs

@@ -1,180 +1,209 @@
-using System;
-using System.Collections.Generic;
-using System.Globalization;
-using System.IO;
-using System.Security.Cryptography;
-using System.Text;
-using System.Threading;
-using System.Threading.Tasks;
-
-namespace StellaOps.Scanner.Sbomer.BuildXPlugin.Descriptor;
-
-/// <summary>
-/// Builds immutable OCI descriptors enriched with provenance placeholders.
-/// </summary>
-public sealed class DescriptorGenerator
-{
-    public const string Schema = "stellaops.buildx.descriptor.v1";
-
-    private readonly TimeProvider timeProvider;
-
-    public DescriptorGenerator(TimeProvider timeProvider)
-    {
-        timeProvider ??= TimeProvider.System;
-        this.timeProvider = timeProvider;
-    }
-
-    public async Task<DescriptorDocument> CreateAsync(DescriptorRequest request, CancellationToken cancellationToken)
-    {
-        if (request is null)
-        {
-            throw new ArgumentNullException(nameof(request));
-        }
-
-        if (string.IsNullOrWhiteSpace(request.ImageDigest))
-        {
-            throw new BuildxPluginException("Image digest must be provided.");
-        }
-
-        if (string.IsNullOrWhiteSpace(request.SbomPath))
-        {
-            throw new BuildxPluginException("SBOM path must be provided.");
-        }
-
-        var sbomFile = new FileInfo(request.SbomPath);
-        if (!sbomFile.Exists)
-        {
-            throw new BuildxPluginException($"SBOM file '{request.SbomPath}' was not found.");
-        }
-
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Security.Cryptography;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace StellaOps.Scanner.Sbomer.BuildXPlugin.Descriptor;
+
+/// <summary>
+/// Builds immutable OCI descriptors enriched with provenance placeholders.
+/// </summary>
+public sealed class DescriptorGenerator
+{
+    public const string Schema = "stellaops.buildx.descriptor.v1";
+
+    private readonly TimeProvider timeProvider;
+
+    public DescriptorGenerator(TimeProvider timeProvider)
+    {
+        timeProvider ??= TimeProvider.System;
+        this.timeProvider = timeProvider;
+    }
+
+    public async Task<DescriptorDocument> CreateAsync(DescriptorRequest request, CancellationToken cancellationToken)
+    {
+        if (request is null)
+        {
+            throw new ArgumentNullException(nameof(request));
+        }
+
+        if (string.IsNullOrWhiteSpace(request.ImageDigest))
+        {
+            throw new BuildxPluginException("Image digest must be provided.");
+        }
+
+        if (string.IsNullOrWhiteSpace(request.SbomPath))
+        {
+            throw new BuildxPluginException("SBOM path must be provided.");
+        }
+
+        var sbomFile = new FileInfo(request.SbomPath);
+        if (!sbomFile.Exists)
+        {
+            throw new BuildxPluginException($"SBOM file '{request.SbomPath}' was not found.");
+        }
+
         var sbomDigest = await ComputeFileDigestAsync(sbomFile, cancellationToken).ConfigureAwait(false);
-
-        var nonce = Guid.NewGuid().ToString("N", CultureInfo.InvariantCulture);
+        var nonce = ComputeDeterministicNonce(request, sbomFile, sbomDigest);
         var expectedDsseSha = ComputeExpectedDsseDigest(request.ImageDigest, sbomDigest, nonce);
 
         var artifactAnnotations = BuildArtifactAnnotations(request, nonce, expectedDsseSha);
-
-        var subject = new DescriptorSubject(
-            MediaType: request.SubjectMediaType,
-            Digest: request.ImageDigest);
-
-        var artifact = new DescriptorArtifact(
-            MediaType: request.SbomMediaType,
-            Digest: sbomDigest,
-            Size: sbomFile.Length,
-            Annotations: artifactAnnotations);
-
-        var provenance = new DescriptorProvenance(
-            Status: "pending",
-            ExpectedDsseSha256: expectedDsseSha,
-            Nonce: nonce,
-            AttestorUri: request.AttestorUri,
-            PredicateType: request.PredicateType);
-
-        var generatorMetadata = new DescriptorGeneratorMetadata(
-            Name: request.GeneratorName ?? "StellaOps.Scanner.Sbomer.BuildXPlugin",
-            Version: request.GeneratorVersion);
-
-        var metadata = BuildDocumentMetadata(request, sbomFile, sbomDigest);
-
+
+        var subject = new DescriptorSubject(
+            MediaType: request.SubjectMediaType,
+            Digest: request.ImageDigest);
+
+        var artifact = new DescriptorArtifact(
+            MediaType: request.SbomMediaType,
+            Digest: sbomDigest,
+            Size: sbomFile.Length,
+            Annotations: artifactAnnotations);
+
+        var provenance = new DescriptorProvenance(
+            Status: "pending",
+            ExpectedDsseSha256: expectedDsseSha,
+            Nonce: nonce,
+            AttestorUri: request.AttestorUri,
+            PredicateType: request.PredicateType);
+
+        var generatorMetadata = new DescriptorGeneratorMetadata(
+            Name: request.GeneratorName ?? "StellaOps.Scanner.Sbomer.BuildXPlugin",
+            Version: request.GeneratorVersion);
+
+        var metadata = BuildDocumentMetadata(request, sbomFile, sbomDigest);
+
         return new DescriptorDocument(
             Schema: Schema,
             GeneratedAt: timeProvider.GetUtcNow(),
-            Generator: generatorMetadata,
-            Subject: subject,
-            Artifact: artifact,
-            Provenance: provenance,
+            Generator: generatorMetadata,
+            Subject: subject,
+            Artifact: artifact,
+            Provenance: provenance,
             Metadata: metadata);
     }
 
-    private static async Task<string> ComputeFileDigestAsync(FileInfo file, CancellationToken cancellationToken)
+    private static string ComputeDeterministicNonce(DescriptorRequest request, FileInfo sbomFile, string sbomDigest)
     {
-        await using var stream = new FileStream(
-            file.FullName,
-            FileMode.Open,
-            FileAccess.Read,
-            FileShare.Read,
-            bufferSize: 128 * 1024,
-            FileOptions.Asynchronous | FileOptions.SequentialScan);
+        var builder = new StringBuilder();
+        builder.AppendLine("stellaops.buildx.nonce.v1");
+        builder.AppendLine(request.ImageDigest);
+        builder.AppendLine(sbomDigest);
+        builder.AppendLine(sbomFile.Length.ToString(CultureInfo.InvariantCulture));
+        builder.AppendLine(request.SbomMediaType);
+        builder.AppendLine(request.SbomFormat);
+        builder.AppendLine(request.SbomKind);
+        builder.AppendLine(request.SbomArtifactType);
+        builder.AppendLine(request.SubjectMediaType);
+        builder.AppendLine(request.GeneratorVersion);
+        builder.AppendLine(request.GeneratorName ?? string.Empty);
+        builder.AppendLine(request.LicenseId ?? string.Empty);
+        builder.AppendLine(request.SbomName ?? string.Empty);
+        builder.AppendLine(request.Repository ?? string.Empty);
+        builder.AppendLine(request.BuildRef ?? string.Empty);
+        builder.AppendLine(request.AttestorUri ?? string.Empty);
+        builder.AppendLine(request.PredicateType);
 
-        using var hash = IncrementalHash.CreateHash(HashAlgorithmName.SHA256);
-
-        var buffer = new byte[128 * 1024];
-        int bytesRead;
-        while ((bytesRead = await stream.ReadAsync(buffer.AsMemory(0, buffer.Length), cancellationToken).ConfigureAwait(false)) > 0)
-        {
-            hash.AppendData(buffer, 0, bytesRead);
-        }
-
-        var digest = hash.GetHashAndReset();
-        return $"sha256:{Convert.ToHexString(digest).ToLowerInvariant()}";
-    }
-
-    private static string ComputeExpectedDsseDigest(string imageDigest, string sbomDigest, string nonce)
-    {
-        var payload = $"{imageDigest}\n{sbomDigest}\n{nonce}";
-        var bytes = System.Text.Encoding.UTF8.GetBytes(payload);
+        var payload = Encoding.UTF8.GetBytes(builder.ToString());
         Span<byte> hash = stackalloc byte[32];
-        SHA256.HashData(bytes, hash);
-        return $"sha256:{Convert.ToHexString(hash).ToLowerInvariant()}";
+        SHA256.HashData(payload, hash);
+
+        Span<byte> nonceBytes = stackalloc byte[16];
+        hash[..16].CopyTo(nonceBytes);
+        return Convert.ToHexString(nonceBytes).ToLowerInvariant();
     }
 
-    private static IReadOnlyDictionary<string, string> BuildArtifactAnnotations(DescriptorRequest request, string nonce, string expectedDsse)
-    {
-        var annotations = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
-        {
-            ["org.opencontainers.artifact.type"] = request.SbomArtifactType,
-            ["org.stellaops.scanner.version"] = request.GeneratorVersion,
-            ["org.stellaops.sbom.kind"] = request.SbomKind,
-            ["org.stellaops.sbom.format"] = request.SbomFormat,
-            ["org.stellaops.provenance.status"] = "pending",
-            ["org.stellaops.provenance.dsse.sha256"] = expectedDsse,
-            ["org.stellaops.provenance.nonce"] = nonce
-        };
-
-        if (!string.IsNullOrWhiteSpace(request.LicenseId))
-        {
-            annotations["org.stellaops.license.id"] = request.LicenseId!;
-        }
-
-        if (!string.IsNullOrWhiteSpace(request.SbomName))
-        {
-            annotations["org.opencontainers.image.title"] = request.SbomName!;
-        }
-
-        if (!string.IsNullOrWhiteSpace(request.Repository))
-        {
-            annotations["org.stellaops.repository"] = request.Repository!;
-        }
-
-        return annotations;
-    }
-
-    private static IReadOnlyDictionary<string, string> BuildDocumentMetadata(DescriptorRequest request, FileInfo fileInfo, string sbomDigest)
-    {
-        var metadata = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
-        {
-            ["sbomDigest"] = sbomDigest,
-            ["sbomPath"] = fileInfo.FullName,
-            ["sbomMediaType"] = request.SbomMediaType,
-            ["subjectMediaType"] = request.SubjectMediaType
-        };
-
-        if (!string.IsNullOrWhiteSpace(request.Repository))
-        {
-            metadata["repository"] = request.Repository!;
-        }
-
-        if (!string.IsNullOrWhiteSpace(request.BuildRef))
-        {
-            metadata["buildRef"] = request.BuildRef!;
-        }
-
-        if (!string.IsNullOrWhiteSpace(request.AttestorUri))
-        {
-            metadata["attestorUri"] = request.AttestorUri!;
-        }
-
-        return metadata;
-    }
-}
+    private static async Task<string> ComputeFileDigestAsync(FileInfo file, CancellationToken cancellationToken)
+    {
+        await using var stream = new FileStream(
+            file.FullName,
+            FileMode.Open,
+            FileAccess.Read,
+            FileShare.Read,
+            bufferSize: 128 * 1024,
+            FileOptions.Asynchronous | FileOptions.SequentialScan);
+
+        using var hash = IncrementalHash.CreateHash(HashAlgorithmName.SHA256);
+
+        var buffer = new byte[128 * 1024];
+        int bytesRead;
+        while ((bytesRead = await stream.ReadAsync(buffer.AsMemory(0, buffer.Length), cancellationToken).ConfigureAwait(false)) > 0)
+        {
+            hash.AppendData(buffer, 0, bytesRead);
+        }
+
+        var digest = hash.GetHashAndReset();
+        return $"sha256:{Convert.ToHexString(digest).ToLowerInvariant()}";
+    }
+
+    private static string ComputeExpectedDsseDigest(string imageDigest, string sbomDigest, string nonce)
+    {
+        var payload = $"{imageDigest}\n{sbomDigest}\n{nonce}";
+        var bytes = System.Text.Encoding.UTF8.GetBytes(payload);
+        Span<byte> hash = stackalloc byte[32];
+        SHA256.HashData(bytes, hash);
+        return $"sha256:{Convert.ToHexString(hash).ToLowerInvariant()}";
+    }
+
+    private static IReadOnlyDictionary<string, string> BuildArtifactAnnotations(DescriptorRequest request, string nonce, string expectedDsse)
+    {
+        var annotations = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+        {
+            ["org.opencontainers.artifact.type"] = request.SbomArtifactType,
+            ["org.stellaops.scanner.version"] = request.GeneratorVersion,
+            ["org.stellaops.sbom.kind"] = request.SbomKind,
+            ["org.stellaops.sbom.format"] = request.SbomFormat,
+            ["org.stellaops.provenance.status"] = "pending",
+            ["org.stellaops.provenance.dsse.sha256"] = expectedDsse,
+            ["org.stellaops.provenance.nonce"] = nonce
+        };
+
+        if (!string.IsNullOrWhiteSpace(request.LicenseId))
+        {
+            annotations["org.stellaops.license.id"] = request.LicenseId!;
+        }
+
+        if (!string.IsNullOrWhiteSpace(request.SbomName))
+        {
+            annotations["org.opencontainers.image.title"] = request.SbomName!;
+        }
+
+        if (!string.IsNullOrWhiteSpace(request.Repository))
+        {
+            annotations["org.stellaops.repository"] = request.Repository!;
+        }
+
+        return annotations;
+    }
+
+    private static IReadOnlyDictionary<string, string> BuildDocumentMetadata(DescriptorRequest request, FileInfo fileInfo, string sbomDigest)
+    {
+        var metadata = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+        {
+            ["sbomDigest"] = sbomDigest,
+            ["sbomPath"] = fileInfo.FullName,
+            ["sbomMediaType"] = request.SbomMediaType,
+            ["subjectMediaType"] = request.SubjectMediaType
+        };
+
+        if (!string.IsNullOrWhiteSpace(request.Repository))
+        {
+            metadata["repository"] = request.Repository!;
+        }
+
+        if (!string.IsNullOrWhiteSpace(request.BuildRef))
+        {
+            metadata["buildRef"] = request.BuildRef!;
+        }
+
+        if (!string.IsNullOrWhiteSpace(request.AttestorUri))
+        {
+            metadata["attestorUri"] = request.AttestorUri!;
+        }
+
+        return metadata;
+    }
+}

src/StellaOps.Scanner.Sbomer.BuildXPlugin/TASKS.md

@@ -5,3 +5,5 @@
 | SP9-BLDX-09-001 | DONE | BuildX Guild | SCANNER-EMIT-10-601 (awareness) | Scaffold buildx driver, manifest, local CAS handshake; ensure plugin loads from `plugins/scanner/buildx/`. | Plugin manifest + loader tests; local CAS writes succeed; restart required to activate. |
 | SP9-BLDX-09-002 | DONE | BuildX Guild | SP9-BLDX-09-001 | Emit OCI annotations + provenance metadata for Attestor handoff (image + SBOM). | OCI descriptors include DSSE/provenance placeholders; Attestor mock accepts payload. |
 | SP9-BLDX-09-003 | DONE | BuildX Guild | SP9-BLDX-09-002 | CI demo pipeline: build sample image, produce SBOM, verify backend report wiring. | GitHub/CI job runs sample build within 5 s overhead; artifacts saved; documentation updated. |
+| SP9-BLDX-09-004 | DONE (2025-10-19) | BuildX Guild | SP9-BLDX-09-002 | Stabilize descriptor nonce derivation so repeated builds emit deterministic placeholders. | Repeated descriptor runs with fixed inputs yield identical JSON; regression tests cover nonce determinism. |
+| SP9-BLDX-09-005 | DONE (2025-10-19) | BuildX Guild | SP9-BLDX-09-004 | Integrate determinism check in GitHub/Gitea workflows and capture sample artifacts. | Determinism step runs in `.gitea/workflows/build-test-deploy.yml` and `samples/ci/buildx-demo`, producing matching descriptors + archived artifacts. |

src/StellaOps.Scanner.Worker/AGENTS.md

@@ -1,26 +1,26 @@
-# AGENTS
-## Role
-Scanner.Worker engineers own the queue-driven execution host that turns scan jobs into SBOM artefacts with deterministic progress reporting.
-## Scope
-- Host bootstrap: configuration binding, Authority client wiring, graceful shutdown, restart-time plug-in discovery hooks.
-- Job acquisition & lease renewal semantics backed by the Scanner queue abstraction.
-- Analyzer orchestration skeleton: stage pipeline, cancellation awareness, deterministic progress emissions.
-- Telemetry: structured logging, OpenTelemetry metrics/traces, health counters for offline diagnostics.
-## Participants
-- Consumes jobs from `StellaOps.Scanner.Queue`.
-- Persists progress/artifacts via `StellaOps.Scanner.Storage` once those modules land.
-- Emits metrics and structured logs consumed by Observability stack & WebService status endpoints.
-## Interfaces & contracts
-- Queue lease abstraction (`IScanJobLease`, `IScanJobSource`) with deterministic identifiers and attempt counters.
-- Analyzer dispatcher contracts for OS/lang/native analyzers and emitters.
-- Telemetry resource attributes shared with Scanner.WebService and Scheduler.
-## In/Out of scope
-In scope: worker host, concurrency orchestration, lease renewal, cancellation wiring, deterministic logging/metrics.
-Out of scope: queue provider implementations, analyzer business logic, Mongo/object-store repositories.
-## Observability expectations
-- Meter `StellaOps.Scanner.Worker` with queue latency, stage duration, failure counters.
-- Activity source `StellaOps.Scanner.Worker.Job` for per-job tracing.
-- Log correlation IDs (`jobId`, `leaseId`, `scanId`) with structured payloads; avoid dumping secrets or full manifests.
-## Tests
-- Integration fixture `WorkerBasicScanScenario` verifying acquisition → heartbeat → analyzer stages → completion.
-- Unit tests around retry/jitter calculators as they are introduced.
+# AGENTS
+## Role
+Scanner.Worker engineers own the queue-driven execution host that turns scan jobs into SBOM artefacts with deterministic progress reporting.
+## Scope
+- Host bootstrap: configuration binding, Authority client wiring, graceful shutdown, restart-time plug-in discovery hooks.
+- Job acquisition & lease renewal semantics backed by the Scanner queue abstraction.
+- Analyzer orchestration skeleton: stage pipeline, cancellation awareness, deterministic progress emissions.
+- Telemetry: structured logging, OpenTelemetry metrics/traces, health counters for offline diagnostics.
+## Participants
+- Consumes jobs from `StellaOps.Scanner.Queue`.
+- Persists progress/artifacts via `StellaOps.Scanner.Storage` once those modules land.
+- Emits metrics and structured logs consumed by Observability stack & WebService status endpoints.
+## Interfaces & contracts
+- Queue lease abstraction (`IScanJobLease`, `IScanJobSource`) with deterministic identifiers and attempt counters.
+- Analyzer dispatcher contracts for OS/lang/native analyzers and emitters.
+- Telemetry resource attributes shared with Scanner.WebService and Scheduler.
+## In/Out of scope
+In scope: worker host, concurrency orchestration, lease renewal, cancellation wiring, deterministic logging/metrics.
+Out of scope: queue provider implementations, analyzer business logic, Mongo/object-store repositories.
+## Observability expectations
+- Meter `StellaOps.Scanner.Worker` with queue latency, stage duration, failure counters.
+- Activity source `StellaOps.Scanner.Worker.Job` for per-job tracing.
+- Log correlation IDs (`jobId`, `leaseId`, `scanId`) with structured payloads; avoid dumping secrets or full manifests.
+## Tests
+- Integration fixture `WorkerBasicScanScenario` verifying acquisition → heartbeat → analyzer stages → completion.
+- Unit tests around retry/jitter calculators as they are introduced.

src/StellaOps.Scanner.Worker/Diagnostics/ScannerWorkerInstrumentation.cs

@@ -1,15 +1,15 @@
-using System.Diagnostics;
-using System.Diagnostics.Metrics;
-
-namespace StellaOps.Scanner.Worker.Diagnostics;
-
-public static class ScannerWorkerInstrumentation
-{
-    public const string ActivitySourceName = "StellaOps.Scanner.Worker.Job";
-
-    public const string MeterName = "StellaOps.Scanner.Worker";
-
-    public static ActivitySource ActivitySource { get; } = new(ActivitySourceName);
-
-    public static Meter Meter { get; } = new(MeterName, version: "1.0.0");
-}
+using System.Diagnostics;
+using System.Diagnostics.Metrics;
+
+namespace StellaOps.Scanner.Worker.Diagnostics;
+
+public static class ScannerWorkerInstrumentation
+{
+    public const string ActivitySourceName = "StellaOps.Scanner.Worker.Job";
+
+    public const string MeterName = "StellaOps.Scanner.Worker";
+
+    public static ActivitySource ActivitySource { get; } = new(ActivitySourceName);
+
+    public static Meter Meter { get; } = new(MeterName, version: "1.0.0");
+}

src/StellaOps.Scanner.Worker/Diagnostics/ScannerWorkerMetrics.cs

@@ -1,109 +1,109 @@
-using System;
-using System.Collections.Generic;
-using System.Diagnostics.Metrics;
-using StellaOps.Scanner.Worker.Processing;
-
-namespace StellaOps.Scanner.Worker.Diagnostics;
-
-public sealed class ScannerWorkerMetrics
-{
-    private readonly Histogram<double> _queueLatencyMs;
-    private readonly Histogram<double> _jobDurationMs;
-    private readonly Histogram<double> _stageDurationMs;
-    private readonly Counter<long> _jobsCompleted;
-    private readonly Counter<long> _jobsFailed;
-
-    public ScannerWorkerMetrics()
-    {
-        _queueLatencyMs = ScannerWorkerInstrumentation.Meter.CreateHistogram<double>(
-            "scanner_worker_queue_latency_ms",
-            unit: "ms",
-            description: "Time from job enqueue to lease acquisition.");
-        _jobDurationMs = ScannerWorkerInstrumentation.Meter.CreateHistogram<double>(
-            "scanner_worker_job_duration_ms",
-            unit: "ms",
-            description: "Total processing duration per job.");
-        _stageDurationMs = ScannerWorkerInstrumentation.Meter.CreateHistogram<double>(
-            "scanner_worker_stage_duration_ms",
-            unit: "ms",
-            description: "Stage execution duration per job.");
-        _jobsCompleted = ScannerWorkerInstrumentation.Meter.CreateCounter<long>(
-            "scanner_worker_jobs_completed_total",
-            description: "Number of successfully completed scan jobs.");
-        _jobsFailed = ScannerWorkerInstrumentation.Meter.CreateCounter<long>(
-            "scanner_worker_jobs_failed_total",
-            description: "Number of scan jobs that failed permanently.");
-    }
-
-    public void RecordQueueLatency(ScanJobContext context, TimeSpan latency)
-    {
-        if (latency <= TimeSpan.Zero)
-        {
-            return;
-        }
-
-        _queueLatencyMs.Record(latency.TotalMilliseconds, CreateTags(context));
-    }
-
-    public void RecordJobDuration(ScanJobContext context, TimeSpan duration)
-    {
-        if (duration <= TimeSpan.Zero)
-        {
-            return;
-        }
-
-        _jobDurationMs.Record(duration.TotalMilliseconds, CreateTags(context));
-    }
-
-    public void RecordStageDuration(ScanJobContext context, string stage, TimeSpan duration)
-    {
-        if (duration <= TimeSpan.Zero)
-        {
-            return;
-        }
-
-        _stageDurationMs.Record(duration.TotalMilliseconds, CreateTags(context, stage: stage));
-    }
-
-    public void IncrementJobCompleted(ScanJobContext context)
-    {
-        _jobsCompleted.Add(1, CreateTags(context));
-    }
-
-    public void IncrementJobFailed(ScanJobContext context, string failureReason)
-    {
-        _jobsFailed.Add(1, CreateTags(context, failureReason: failureReason));
-    }
-
-    private static KeyValuePair<string, object?>[] CreateTags(ScanJobContext context, string? stage = null, string? failureReason = null)
-    {
-        var tags = new List<KeyValuePair<string, object?>>(stage is null ? 5 : 6)
-        {
-            new("job.id", context.JobId),
-            new("scan.id", context.ScanId),
-            new("attempt", context.Lease.Attempt),
-        };
-
-        if (context.Lease.Metadata.TryGetValue("queue", out var queueName) && !string.IsNullOrWhiteSpace(queueName))
-        {
-            tags.Add(new KeyValuePair<string, object?>("queue", queueName));
-        }
-
-        if (context.Lease.Metadata.TryGetValue("job.kind", out var jobKind) && !string.IsNullOrWhiteSpace(jobKind))
-        {
-            tags.Add(new KeyValuePair<string, object?>("job.kind", jobKind));
-        }
-
-        if (!string.IsNullOrWhiteSpace(stage))
-        {
-            tags.Add(new KeyValuePair<string, object?>("stage", stage));
-        }
-
-        if (!string.IsNullOrWhiteSpace(failureReason))
-        {
-            tags.Add(new KeyValuePair<string, object?>("reason", failureReason));
-        }
-
-        return tags.ToArray();
-    }
-}
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.Metrics;
+using StellaOps.Scanner.Worker.Processing;
+
+namespace StellaOps.Scanner.Worker.Diagnostics;
+
+public sealed class ScannerWorkerMetrics
+{
+    private readonly Histogram<double> _queueLatencyMs;
+    private readonly Histogram<double> _jobDurationMs;
+    private readonly Histogram<double> _stageDurationMs;
+    private readonly Counter<long> _jobsCompleted;
+    private readonly Counter<long> _jobsFailed;
+
+    public ScannerWorkerMetrics()
+    {
+        _queueLatencyMs = ScannerWorkerInstrumentation.Meter.CreateHistogram<double>(
+            "scanner_worker_queue_latency_ms",
+            unit: "ms",
+            description: "Time from job enqueue to lease acquisition.");
+        _jobDurationMs = ScannerWorkerInstrumentation.Meter.CreateHistogram<double>(
+            "scanner_worker_job_duration_ms",
+            unit: "ms",
+            description: "Total processing duration per job.");
+        _stageDurationMs = ScannerWorkerInstrumentation.Meter.CreateHistogram<double>(
+            "scanner_worker_stage_duration_ms",
+            unit: "ms",
+            description: "Stage execution duration per job.");
+        _jobsCompleted = ScannerWorkerInstrumentation.Meter.CreateCounter<long>(
+            "scanner_worker_jobs_completed_total",
+            description: "Number of successfully completed scan jobs.");
+        _jobsFailed = ScannerWorkerInstrumentation.Meter.CreateCounter<long>(
+            "scanner_worker_jobs_failed_total",
+            description: "Number of scan jobs that failed permanently.");
+    }
+
+    public void RecordQueueLatency(ScanJobContext context, TimeSpan latency)
+    {
+        if (latency <= TimeSpan.Zero)
+        {
+            return;
+        }
+
+        _queueLatencyMs.Record(latency.TotalMilliseconds, CreateTags(context));
+    }
+
+    public void RecordJobDuration(ScanJobContext context, TimeSpan duration)
+    {
+        if (duration <= TimeSpan.Zero)
+        {
+            return;
+        }
+
+        _jobDurationMs.Record(duration.TotalMilliseconds, CreateTags(context));
+    }
+
+    public void RecordStageDuration(ScanJobContext context, string stage, TimeSpan duration)
+    {
+        if (duration <= TimeSpan.Zero)
+        {
+            return;
+        }
+
+        _stageDurationMs.Record(duration.TotalMilliseconds, CreateTags(context, stage: stage));
+    }
+
+    public void IncrementJobCompleted(ScanJobContext context)
+    {
+        _jobsCompleted.Add(1, CreateTags(context));
+    }
+
+    public void IncrementJobFailed(ScanJobContext context, string failureReason)
+    {
+        _jobsFailed.Add(1, CreateTags(context, failureReason: failureReason));
+    }
+
+    private static KeyValuePair<string, object?>[] CreateTags(ScanJobContext context, string? stage = null, string? failureReason = null)
+    {
+        var tags = new List<KeyValuePair<string, object?>>(stage is null ? 5 : 6)
+        {
+            new("job.id", context.JobId),
+            new("scan.id", context.ScanId),
+            new("attempt", context.Lease.Attempt),
+        };
+
+        if (context.Lease.Metadata.TryGetValue("queue", out var queueName) && !string.IsNullOrWhiteSpace(queueName))
+        {
+            tags.Add(new KeyValuePair<string, object?>("queue", queueName));
+        }
+
+        if (context.Lease.Metadata.TryGetValue("job.kind", out var jobKind) && !string.IsNullOrWhiteSpace(jobKind))
+        {
+            tags.Add(new KeyValuePair<string, object?>("job.kind", jobKind));
+        }
+
+        if (!string.IsNullOrWhiteSpace(stage))
+        {
+            tags.Add(new KeyValuePair<string, object?>("stage", stage));
+        }
+
+        if (!string.IsNullOrWhiteSpace(failureReason))
+        {
+            tags.Add(new KeyValuePair<string, object?>("reason", failureReason));
+        }
+
+        return tags.ToArray();
+    }
+}

src/StellaOps.Scanner.Worker/Diagnostics/TelemetryExtensions.cs

@@ -1,102 +1,102 @@
-using System;
-using System.Collections.Generic;
-using System.Reflection;
-using Microsoft.Extensions.DependencyInjection;
-using Microsoft.Extensions.Hosting;
-using OpenTelemetry.Metrics;
-using OpenTelemetry.Resources;
-using OpenTelemetry.Trace;
-using StellaOps.Scanner.Worker.Options;
-
-namespace StellaOps.Scanner.Worker.Diagnostics;
-
-public static class TelemetryExtensions
-{
-    public static void ConfigureScannerWorkerTelemetry(this IHostApplicationBuilder builder, ScannerWorkerOptions options)
-    {
-        ArgumentNullException.ThrowIfNull(builder);
-        ArgumentNullException.ThrowIfNull(options);
-
-        var telemetry = options.Telemetry;
-        if (!telemetry.EnableTelemetry)
-        {
-            return;
-        }
-
-        var openTelemetry = builder.Services.AddOpenTelemetry();
-
-        openTelemetry.ConfigureResource(resource =>
-        {
-            var version = Assembly.GetExecutingAssembly().GetName().Version?.ToString() ?? "unknown";
-            resource.AddService(telemetry.ServiceName, serviceVersion: version, serviceInstanceId: Environment.MachineName);
-            resource.AddAttributes(new[]
-            {
-                new KeyValuePair<string, object>("deployment.environment", builder.Environment.EnvironmentName),
-            });
-
-            foreach (var kvp in telemetry.ResourceAttributes)
-            {
-                if (string.IsNullOrWhiteSpace(kvp.Key) || kvp.Value is null)
-                {
-                    continue;
-                }
-
-                resource.AddAttributes(new[] { new KeyValuePair<string, object>(kvp.Key, kvp.Value) });
-            }
-        });
-
-        if (telemetry.EnableTracing)
-        {
-            openTelemetry.WithTracing(tracing =>
-            {
-                tracing.AddSource(ScannerWorkerInstrumentation.ActivitySourceName);
-                ConfigureExporter(tracing, telemetry);
-            });
-        }
-
-        if (telemetry.EnableMetrics)
-        {
-            openTelemetry.WithMetrics(metrics =>
-            {
-                metrics
-                    .AddMeter(ScannerWorkerInstrumentation.MeterName)
-                    .AddRuntimeInstrumentation()
-                    .AddProcessInstrumentation();
-
-                ConfigureExporter(metrics, telemetry);
-            });
-        }
-    }
-
-    private static void ConfigureExporter(TracerProviderBuilder tracing, ScannerWorkerOptions.TelemetryOptions telemetry)
-    {
-        if (!string.IsNullOrWhiteSpace(telemetry.OtlpEndpoint))
-        {
-            tracing.AddOtlpExporter(options =>
-            {
-                options.Endpoint = new Uri(telemetry.OtlpEndpoint);
-            });
-        }
-
-        if (telemetry.ExportConsole || string.IsNullOrWhiteSpace(telemetry.OtlpEndpoint))
-        {
-            tracing.AddConsoleExporter();
-        }
-    }
-
-    private static void ConfigureExporter(MeterProviderBuilder metrics, ScannerWorkerOptions.TelemetryOptions telemetry)
-    {
-        if (!string.IsNullOrWhiteSpace(telemetry.OtlpEndpoint))
-        {
-            metrics.AddOtlpExporter(options =>
-            {
-                options.Endpoint = new Uri(telemetry.OtlpEndpoint);
-            });
-        }
-
-        if (telemetry.ExportConsole || string.IsNullOrWhiteSpace(telemetry.OtlpEndpoint))
-        {
-            metrics.AddConsoleExporter();
-        }
-    }
-}
+using System;
+using System.Collections.Generic;
+using System.Reflection;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using OpenTelemetry.Metrics;
+using OpenTelemetry.Resources;
+using OpenTelemetry.Trace;
+using StellaOps.Scanner.Worker.Options;
+
+namespace StellaOps.Scanner.Worker.Diagnostics;
+
+public static class TelemetryExtensions
+{
+    public static void ConfigureScannerWorkerTelemetry(this IHostApplicationBuilder builder, ScannerWorkerOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+        ArgumentNullException.ThrowIfNull(options);
+
+        var telemetry = options.Telemetry;
+        if (!telemetry.EnableTelemetry)
+        {
+            return;
+        }
+
+        var openTelemetry = builder.Services.AddOpenTelemetry();
+
+        openTelemetry.ConfigureResource(resource =>
+        {
+            var version = Assembly.GetExecutingAssembly().GetName().Version?.ToString() ?? "unknown";
+            resource.AddService(telemetry.ServiceName, serviceVersion: version, serviceInstanceId: Environment.MachineName);
+            resource.AddAttributes(new[]
+            {
+                new KeyValuePair<string, object>("deployment.environment", builder.Environment.EnvironmentName),
+            });
+
+            foreach (var kvp in telemetry.ResourceAttributes)
+            {
+                if (string.IsNullOrWhiteSpace(kvp.Key) || kvp.Value is null)
+                {
+                    continue;
+                }
+
+                resource.AddAttributes(new[] { new KeyValuePair<string, object>(kvp.Key, kvp.Value) });
+            }
+        });
+
+        if (telemetry.EnableTracing)
+        {
+            openTelemetry.WithTracing(tracing =>
+            {
+                tracing.AddSource(ScannerWorkerInstrumentation.ActivitySourceName);
+                ConfigureExporter(tracing, telemetry);
+            });
+        }
+
+        if (telemetry.EnableMetrics)
+        {
+            openTelemetry.WithMetrics(metrics =>
+            {
+                metrics
+                    .AddMeter(ScannerWorkerInstrumentation.MeterName)
+                    .AddRuntimeInstrumentation()
+                    .AddProcessInstrumentation();
+
+                ConfigureExporter(metrics, telemetry);
+            });
+        }
+    }
+
+    private static void ConfigureExporter(TracerProviderBuilder tracing, ScannerWorkerOptions.TelemetryOptions telemetry)
+    {
+        if (!string.IsNullOrWhiteSpace(telemetry.OtlpEndpoint))
+        {
+            tracing.AddOtlpExporter(options =>
+            {
+                options.Endpoint = new Uri(telemetry.OtlpEndpoint);
+            });
+        }
+
+        if (telemetry.ExportConsole || string.IsNullOrWhiteSpace(telemetry.OtlpEndpoint))
+        {
+            tracing.AddConsoleExporter();
+        }
+    }
+
+    private static void ConfigureExporter(MeterProviderBuilder metrics, ScannerWorkerOptions.TelemetryOptions telemetry)
+    {
+        if (!string.IsNullOrWhiteSpace(telemetry.OtlpEndpoint))
+        {
+            metrics.AddOtlpExporter(options =>
+            {
+                options.Endpoint = new Uri(telemetry.OtlpEndpoint);
+            });
+        }
+
+        if (telemetry.ExportConsole || string.IsNullOrWhiteSpace(telemetry.OtlpEndpoint))
+        {
+            metrics.AddConsoleExporter();
+        }
+    }
+}

src/StellaOps.Scanner.Worker/Hosting/ScannerWorkerHostedService.cs

@@ -1,201 +1,202 @@
-using System;
-using System.Collections.Generic;
-using System.Threading;
-using System.Threading.Tasks;
-using Microsoft.Extensions.Hosting;
-using Microsoft.Extensions.Logging;
-using Microsoft.Extensions.Options;
-using StellaOps.Scanner.Worker.Diagnostics;
-using StellaOps.Scanner.Worker.Options;
-using StellaOps.Scanner.Worker.Processing;
-
-namespace StellaOps.Scanner.Worker.Hosting;
-
-public sealed partial class ScannerWorkerHostedService : BackgroundService
-{
-    private readonly IScanJobSource _jobSource;
-    private readonly ScanJobProcessor _processor;
-    private readonly LeaseHeartbeatService _heartbeatService;
-    private readonly ScannerWorkerMetrics _metrics;
-    private readonly TimeProvider _timeProvider;
-    private readonly IOptionsMonitor<ScannerWorkerOptions> _options;
-    private readonly ILogger<ScannerWorkerHostedService> _logger;
-    private readonly IDelayScheduler _delayScheduler;
-
-    public ScannerWorkerHostedService(
-        IScanJobSource jobSource,
-        ScanJobProcessor processor,
-        LeaseHeartbeatService heartbeatService,
-        ScannerWorkerMetrics metrics,
-        TimeProvider timeProvider,
-        IDelayScheduler delayScheduler,
-        IOptionsMonitor<ScannerWorkerOptions> options,
-        ILogger<ScannerWorkerHostedService> logger)
-    {
-        _jobSource = jobSource ?? throw new ArgumentNullException(nameof(jobSource));
-        _processor = processor ?? throw new ArgumentNullException(nameof(processor));
-        _heartbeatService = heartbeatService ?? throw new ArgumentNullException(nameof(heartbeatService));
-        _metrics = metrics ?? throw new ArgumentNullException(nameof(metrics));
-        _timeProvider = timeProvider ?? throw new ArgumentNullException(nameof(timeProvider));
-        _delayScheduler = delayScheduler ?? throw new ArgumentNullException(nameof(delayScheduler));
-        _options = options ?? throw new ArgumentNullException(nameof(options));
-        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
-    }
-
-    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
-    {
-        var runningJobs = new HashSet<Task>();
-        var delayStrategy = new PollDelayStrategy(_options.CurrentValue.Polling);
-
-        WorkerStarted(_logger);
-
-        while (!stoppingToken.IsCancellationRequested)
-        {
-            runningJobs.RemoveWhere(static task => task.IsCompleted);
-
-            var options = _options.CurrentValue;
-            if (runningJobs.Count >= options.MaxConcurrentJobs)
-            {
-                var completed = await Task.WhenAny(runningJobs).ConfigureAwait(false);
-                runningJobs.Remove(completed);
-                continue;
-            }
-
-            IScanJobLease? lease = null;
-            try
-            {
-                lease = await _jobSource.TryAcquireAsync(stoppingToken).ConfigureAwait(false);
-            }
-            catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
-            {
-                break;
-            }
-            catch (Exception ex)
-            {
-                _logger.LogError(ex, "Scanner worker failed to acquire job lease; backing off.");
-            }
-
-            if (lease is null)
-            {
-                var delay = delayStrategy.NextDelay();
-                await _delayScheduler.DelayAsync(delay, stoppingToken).ConfigureAwait(false);
-                continue;
-            }
-
-            delayStrategy.Reset();
-            runningJobs.Add(RunJobAsync(lease, stoppingToken));
-        }
-
-        if (runningJobs.Count > 0)
-        {
-            await Task.WhenAll(runningJobs).ConfigureAwait(false);
-        }
-
-        WorkerStopping(_logger);
-    }
-
-    private async Task RunJobAsync(IScanJobLease lease, CancellationToken stoppingToken)
-    {
-        var options = _options.CurrentValue;
-        var jobStart = _timeProvider.GetUtcNow();
-        var queueLatency = jobStart - lease.EnqueuedAtUtc;
-        var jobCts = CancellationTokenSource.CreateLinkedTokenSource(stoppingToken);
-        var jobToken = jobCts.Token;
-        var context = new ScanJobContext(lease, _timeProvider, jobStart, jobToken);
-
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using StellaOps.Scanner.Worker.Diagnostics;
+using StellaOps.Scanner.Worker.Options;
+using StellaOps.Scanner.Worker.Processing;
+
+namespace StellaOps.Scanner.Worker.Hosting;
+
+public sealed partial class ScannerWorkerHostedService : BackgroundService
+{
+    private readonly IScanJobSource _jobSource;
+    private readonly ScanJobProcessor _processor;
+    private readonly LeaseHeartbeatService _heartbeatService;
+    private readonly ScannerWorkerMetrics _metrics;
+    private readonly TimeProvider _timeProvider;
+    private readonly IOptionsMonitor<ScannerWorkerOptions> _options;
+    private readonly ILogger<ScannerWorkerHostedService> _logger;
+    private readonly IDelayScheduler _delayScheduler;
+
+    public ScannerWorkerHostedService(
+        IScanJobSource jobSource,
+        ScanJobProcessor processor,
+        LeaseHeartbeatService heartbeatService,
+        ScannerWorkerMetrics metrics,
+        TimeProvider timeProvider,
+        IDelayScheduler delayScheduler,
+        IOptionsMonitor<ScannerWorkerOptions> options,
+        ILogger<ScannerWorkerHostedService> logger)
+    {
+        _jobSource = jobSource ?? throw new ArgumentNullException(nameof(jobSource));
+        _processor = processor ?? throw new ArgumentNullException(nameof(processor));
+        _heartbeatService = heartbeatService ?? throw new ArgumentNullException(nameof(heartbeatService));
+        _metrics = metrics ?? throw new ArgumentNullException(nameof(metrics));
+        _timeProvider = timeProvider ?? throw new ArgumentNullException(nameof(timeProvider));
+        _delayScheduler = delayScheduler ?? throw new ArgumentNullException(nameof(delayScheduler));
+        _options = options ?? throw new ArgumentNullException(nameof(options));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        var runningJobs = new HashSet<Task>();
+        var delayStrategy = new PollDelayStrategy(_options.CurrentValue.Polling);
+
+        WorkerStarted(_logger);
+
+        while (!stoppingToken.IsCancellationRequested)
+        {
+            runningJobs.RemoveWhere(static task => task.IsCompleted);
+
+            var options = _options.CurrentValue;
+            if (runningJobs.Count >= options.MaxConcurrentJobs)
+            {
+                var completed = await Task.WhenAny(runningJobs).ConfigureAwait(false);
+                runningJobs.Remove(completed);
+                continue;
+            }
+
+            IScanJobLease? lease = null;
+            try
+            {
+                lease = await _jobSource.TryAcquireAsync(stoppingToken).ConfigureAwait(false);
+            }
+            catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
+            {
+                break;
+            }
+            catch (Exception ex)
+            {
+                _logger.LogError(ex, "Scanner worker failed to acquire job lease; backing off.");
+            }
+
+            if (lease is null)
+            {
+                var delay = delayStrategy.NextDelay();
+                await _delayScheduler.DelayAsync(delay, stoppingToken).ConfigureAwait(false);
+                continue;
+            }
+
+            delayStrategy.Reset();
+            runningJobs.Add(RunJobAsync(lease, stoppingToken));
+        }
+
+        if (runningJobs.Count > 0)
+        {
+            await Task.WhenAll(runningJobs).ConfigureAwait(false);
+        }
+
+        WorkerStopping(_logger);
+    }
+
+    private async Task RunJobAsync(IScanJobLease lease, CancellationToken stoppingToken)
+    {
+        var options = _options.CurrentValue;
+        var jobStart = _timeProvider.GetUtcNow();
+        var queueLatency = jobStart - lease.EnqueuedAtUtc;
+        var jobCts = CancellationTokenSource.CreateLinkedTokenSource(stoppingToken);
+        var jobToken = jobCts.Token;
+        var context = new ScanJobContext(lease, _timeProvider, jobStart, jobToken);
+
         _metrics.RecordQueueLatency(context, queueLatency);
         JobAcquired(_logger, lease.JobId, lease.ScanId, lease.Attempt, queueLatency.TotalMilliseconds);
 
+        var processingTask = _processor.ExecuteAsync(context, jobToken).AsTask();
         var heartbeatTask = _heartbeatService.RunAsync(lease, jobToken);
         Exception? processingException = null;
 
         try
         {
-            await _processor.ExecuteAsync(context, jobToken).ConfigureAwait(false);
+            await processingTask.ConfigureAwait(false);
             jobCts.Cancel();
             await heartbeatTask.ConfigureAwait(false);
             await lease.CompleteAsync(stoppingToken).ConfigureAwait(false);
             var duration = _timeProvider.GetUtcNow() - jobStart;
             _metrics.RecordJobDuration(context, duration);
-            _metrics.IncrementJobCompleted(context);
-            JobCompleted(_logger, lease.JobId, lease.ScanId, duration.TotalMilliseconds);
-        }
-        catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
-        {
-            processingException = null;
-            await lease.AbandonAsync("host-stopping", CancellationToken.None).ConfigureAwait(false);
-            JobAbandoned(_logger, lease.JobId, lease.ScanId);
-        }
-        catch (Exception ex)
-        {
-            processingException = ex;
-            var duration = _timeProvider.GetUtcNow() - jobStart;
-            _metrics.RecordJobDuration(context, duration);
-
-            var reason = ex.GetType().Name;
-            var maxAttempts = options.Queue.MaxAttempts;
-            if (lease.Attempt >= maxAttempts)
-            {
-                await lease.PoisonAsync(reason, CancellationToken.None).ConfigureAwait(false);
-                _metrics.IncrementJobFailed(context, reason);
-                JobPoisoned(_logger, lease.JobId, lease.ScanId, lease.Attempt, maxAttempts, ex);
-            }
-            else
-            {
-                await lease.AbandonAsync(reason, CancellationToken.None).ConfigureAwait(false);
-                JobAbandonedWithError(_logger, lease.JobId, lease.ScanId, lease.Attempt, maxAttempts, ex);
-            }
-        }
-        finally
-        {
-            jobCts.Cancel();
-            try
-            {
-                await heartbeatTask.ConfigureAwait(false);
-            }
-            catch (Exception ex) when (processingException is null && ex is not OperationCanceledException)
-            {
-                _logger.LogWarning(ex, "Heartbeat loop ended with an exception for job {JobId}.", lease.JobId);
-            }
-
-            await lease.DisposeAsync().ConfigureAwait(false);
-            jobCts.Dispose();
-        }
-    }
-
-    [LoggerMessage(EventId = 2000, Level = LogLevel.Information, Message = "Scanner worker host started.")]
-    private static partial void WorkerStarted(ILogger logger);
-
-    [LoggerMessage(EventId = 2001, Level = LogLevel.Information, Message = "Scanner worker host stopping.")]
-    private static partial void WorkerStopping(ILogger logger);
-
-    [LoggerMessage(
-        EventId = 2002,
-        Level = LogLevel.Information,
-        Message = "Leased job {JobId} (scan {ScanId}) attempt {Attempt}; queue latency {LatencyMs:F0} ms.")]
-    private static partial void JobAcquired(ILogger logger, string jobId, string scanId, int attempt, double latencyMs);
-
-    [LoggerMessage(
-        EventId = 2003,
-        Level = LogLevel.Information,
-        Message = "Job {JobId} (scan {ScanId}) completed in {DurationMs:F0} ms.")]
-    private static partial void JobCompleted(ILogger logger, string jobId, string scanId, double durationMs);
-
-    [LoggerMessage(
-        EventId = 2004,
-        Level = LogLevel.Warning,
-        Message = "Job {JobId} (scan {ScanId}) abandoned due to host shutdown.")]
-    private static partial void JobAbandoned(ILogger logger, string jobId, string scanId);
-
-    [LoggerMessage(
-        EventId = 2005,
-        Level = LogLevel.Warning,
-        Message = "Job {JobId} (scan {ScanId}) attempt {Attempt}/{MaxAttempts} abandoned after failure; job will be retried.")]
-    private static partial void JobAbandonedWithError(ILogger logger, string jobId, string scanId, int attempt, int maxAttempts, Exception exception);
-
-    [LoggerMessage(
-        EventId = 2006,
-        Level = LogLevel.Error,
-        Message = "Job {JobId} (scan {ScanId}) attempt {Attempt}/{MaxAttempts} exceeded retry budget; quarantining job.")]
-    private static partial void JobPoisoned(ILogger logger, string jobId, string scanId, int attempt, int maxAttempts, Exception exception);
-}
+            _metrics.IncrementJobCompleted(context);
+            JobCompleted(_logger, lease.JobId, lease.ScanId, duration.TotalMilliseconds);
+        }
+        catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
+        {
+            processingException = null;
+            await lease.AbandonAsync("host-stopping", CancellationToken.None).ConfigureAwait(false);
+            JobAbandoned(_logger, lease.JobId, lease.ScanId);
+        }
+        catch (Exception ex)
+        {
+            processingException = ex;
+            var duration = _timeProvider.GetUtcNow() - jobStart;
+            _metrics.RecordJobDuration(context, duration);
+
+            var reason = ex.GetType().Name;
+            var maxAttempts = options.Queue.MaxAttempts;
+            if (lease.Attempt >= maxAttempts)
+            {
+                await lease.PoisonAsync(reason, CancellationToken.None).ConfigureAwait(false);
+                _metrics.IncrementJobFailed(context, reason);
+                JobPoisoned(_logger, lease.JobId, lease.ScanId, lease.Attempt, maxAttempts, ex);
+            }
+            else
+            {
+                await lease.AbandonAsync(reason, CancellationToken.None).ConfigureAwait(false);
+                JobAbandonedWithError(_logger, lease.JobId, lease.ScanId, lease.Attempt, maxAttempts, ex);
+            }
+        }
+        finally
+        {
+            jobCts.Cancel();
+            try
+            {
+                await heartbeatTask.ConfigureAwait(false);
+            }
+            catch (Exception ex) when (processingException is null && ex is not OperationCanceledException)
+            {
+                _logger.LogWarning(ex, "Heartbeat loop ended with an exception for job {JobId}.", lease.JobId);
+            }
+
+            await lease.DisposeAsync().ConfigureAwait(false);
+            jobCts.Dispose();
+        }
+    }
+
+    [LoggerMessage(EventId = 2000, Level = LogLevel.Information, Message = "Scanner worker host started.")]
+    private static partial void WorkerStarted(ILogger logger);
+
+    [LoggerMessage(EventId = 2001, Level = LogLevel.Information, Message = "Scanner worker host stopping.")]
+    private static partial void WorkerStopping(ILogger logger);
+
+    [LoggerMessage(
+        EventId = 2002,
+        Level = LogLevel.Information,
+        Message = "Leased job {JobId} (scan {ScanId}) attempt {Attempt}; queue latency {LatencyMs:F0} ms.")]
+    private static partial void JobAcquired(ILogger logger, string jobId, string scanId, int attempt, double latencyMs);
+
+    [LoggerMessage(
+        EventId = 2003,
+        Level = LogLevel.Information,
+        Message = "Job {JobId} (scan {ScanId}) completed in {DurationMs:F0} ms.")]
+    private static partial void JobCompleted(ILogger logger, string jobId, string scanId, double durationMs);
+
+    [LoggerMessage(
+        EventId = 2004,
+        Level = LogLevel.Warning,
+        Message = "Job {JobId} (scan {ScanId}) abandoned due to host shutdown.")]
+    private static partial void JobAbandoned(ILogger logger, string jobId, string scanId);
+
+    [LoggerMessage(
+        EventId = 2005,
+        Level = LogLevel.Warning,
+        Message = "Job {JobId} (scan {ScanId}) attempt {Attempt}/{MaxAttempts} abandoned after failure; job will be retried.")]
+    private static partial void JobAbandonedWithError(ILogger logger, string jobId, string scanId, int attempt, int maxAttempts, Exception exception);
+
+    [LoggerMessage(
+        EventId = 2006,
+        Level = LogLevel.Error,
+        Message = "Job {JobId} (scan {ScanId}) attempt {Attempt}/{MaxAttempts} exceeded retry budget; quarantining job.")]
+    private static partial void JobPoisoned(ILogger logger, string jobId, string scanId, int attempt, int maxAttempts, Exception exception);
+}

src/StellaOps.Scanner.Worker/Options/ScannerWorkerOptions.cs

@@ -2,141 +2,162 @@ using System;
 using System.Collections.Concurrent;
 using System.Collections.Generic;
 using System.Collections.ObjectModel;
-
-namespace StellaOps.Scanner.Worker.Options;
-
-public sealed class ScannerWorkerOptions
-{
-    public const string SectionName = "Scanner:Worker";
-
-    public int MaxConcurrentJobs { get; set; } = 2;
-
-    public QueueOptions Queue { get; } = new();
-
-    public PollingOptions Polling { get; } = new();
-
-    public AuthorityOptions Authority { get; } = new();
-
+using System.IO;
+using StellaOps.Scanner.Core.Contracts;
+
+namespace StellaOps.Scanner.Worker.Options;
+
+public sealed class ScannerWorkerOptions
+{
+    public const string SectionName = "Scanner:Worker";
+
+    public int MaxConcurrentJobs { get; set; } = 2;
+
+    public QueueOptions Queue { get; } = new();
+
+    public PollingOptions Polling { get; } = new();
+
+    public AuthorityOptions Authority { get; } = new();
+
     public TelemetryOptions Telemetry { get; } = new();
 
     public ShutdownOptions Shutdown { get; } = new();
 
-    public sealed class QueueOptions
-    {
-        public int MaxAttempts { get; set; } = 5;
-
-        public double HeartbeatSafetyFactor { get; set; } = 3.0;
-
-        public int MaxHeartbeatJitterMilliseconds { get; set; } = 750;
-
-        public IReadOnlyList<TimeSpan> HeartbeatRetryDelays => _heartbeatRetryDelays;
-
-        public TimeSpan MinHeartbeatInterval { get; set; } = TimeSpan.FromSeconds(10);
-
-        public TimeSpan MaxHeartbeatInterval { get; set; } = TimeSpan.FromSeconds(30);
-
-        public void SetHeartbeatRetryDelays(IEnumerable<TimeSpan> delays)
-        {
-            _heartbeatRetryDelays = NormalizeDelays(delays);
-        }
-
-        internal IReadOnlyList<TimeSpan> NormalizedHeartbeatRetryDelays => _heartbeatRetryDelays;
-
-        private static IReadOnlyList<TimeSpan> NormalizeDelays(IEnumerable<TimeSpan> delays)
-        {
-            var buffer = new List<TimeSpan>();
-            foreach (var delay in delays)
-            {
-                if (delay <= TimeSpan.Zero)
-                {
-                    continue;
-                }
-
-                buffer.Add(delay);
-            }
-
-            buffer.Sort();
-            return new ReadOnlyCollection<TimeSpan>(buffer);
-        }
-
-        private IReadOnlyList<TimeSpan> _heartbeatRetryDelays = new ReadOnlyCollection<TimeSpan>(new TimeSpan[]
-        {
-            TimeSpan.FromSeconds(2),
-            TimeSpan.FromSeconds(5),
-            TimeSpan.FromSeconds(10),
-        });
-    }
-
-    public sealed class PollingOptions
-    {
-        public TimeSpan InitialDelay { get; set; } = TimeSpan.FromMilliseconds(200);
-
-        public TimeSpan MaxDelay { get; set; } = TimeSpan.FromSeconds(5);
-
-        public double JitterRatio { get; set; } = 0.2;
-    }
-
-    public sealed class AuthorityOptions
-    {
-        public bool Enabled { get; set; }
-
-        public string? Issuer { get; set; }
-
-        public string? ClientId { get; set; }
-
-        public string? ClientSecret { get; set; }
-
-        public bool RequireHttpsMetadata { get; set; } = true;
-
-        public string? MetadataAddress { get; set; }
-
-        public int BackchannelTimeoutSeconds { get; set; } = 20;
-
-        public int TokenClockSkewSeconds { get; set; } = 30;
-
-        public IList<string> Scopes { get; } = new List<string> { "scanner.scan" };
-
-        public ResilienceOptions Resilience { get; } = new();
-    }
-
-    public sealed class ResilienceOptions
-    {
-        public bool? EnableRetries { get; set; }
-
-        public IList<TimeSpan> RetryDelays { get; } = new List<TimeSpan>
-        {
-            TimeSpan.FromMilliseconds(250),
-            TimeSpan.FromMilliseconds(500),
-            TimeSpan.FromSeconds(1),
-            TimeSpan.FromSeconds(5),
-        };
-
-        public bool? AllowOfflineCacheFallback { get; set; }
-
-        public TimeSpan? OfflineCacheTolerance { get; set; }
-    }
-
-    public sealed class TelemetryOptions
-    {
-        public bool EnableLogging { get; set; } = true;
-
-        public bool EnableTelemetry { get; set; } = true;
-
-        public bool EnableTracing { get; set; }
-
-        public bool EnableMetrics { get; set; } = true;
-
-        public string ServiceName { get; set; } = "stellaops-scanner-worker";
-
-        public string? OtlpEndpoint { get; set; }
-
-        public bool ExportConsole { get; set; }
-
-        public IDictionary<string, string?> ResourceAttributes { get; } = new ConcurrentDictionary<string, string?>(StringComparer.OrdinalIgnoreCase);
-    }
-
+    public AnalyzerOptions Analyzers { get; } = new();
+
+    public sealed class QueueOptions
+    {
+        public int MaxAttempts { get; set; } = 5;
+
+        public double HeartbeatSafetyFactor { get; set; } = 3.0;
+
+        public int MaxHeartbeatJitterMilliseconds { get; set; } = 750;
+
+        public IReadOnlyList<TimeSpan> HeartbeatRetryDelays => _heartbeatRetryDelays;
+
+        public TimeSpan MinHeartbeatInterval { get; set; } = TimeSpan.FromSeconds(10);
+
+        public TimeSpan MaxHeartbeatInterval { get; set; } = TimeSpan.FromSeconds(30);
+
+        public void SetHeartbeatRetryDelays(IEnumerable<TimeSpan> delays)
+        {
+            _heartbeatRetryDelays = NormalizeDelays(delays);
+        }
+
+        internal IReadOnlyList<TimeSpan> NormalizedHeartbeatRetryDelays => _heartbeatRetryDelays;
+
+        private static IReadOnlyList<TimeSpan> NormalizeDelays(IEnumerable<TimeSpan> delays)
+        {
+            var buffer = new List<TimeSpan>();
+            foreach (var delay in delays)
+            {
+                if (delay <= TimeSpan.Zero)
+                {
+                    continue;
+                }
+
+                buffer.Add(delay);
+            }
+
+            buffer.Sort();
+            return new ReadOnlyCollection<TimeSpan>(buffer);
+        }
+
+        private IReadOnlyList<TimeSpan> _heartbeatRetryDelays = new ReadOnlyCollection<TimeSpan>(new TimeSpan[]
+        {
+            TimeSpan.FromSeconds(2),
+            TimeSpan.FromSeconds(5),
+            TimeSpan.FromSeconds(10),
+        });
+    }
+
+    public sealed class PollingOptions
+    {
+        public TimeSpan InitialDelay { get; set; } = TimeSpan.FromMilliseconds(200);
+
+        public TimeSpan MaxDelay { get; set; } = TimeSpan.FromSeconds(5);
+
+        public double JitterRatio { get; set; } = 0.2;
+    }
+
+    public sealed class AuthorityOptions
+    {
+        public bool Enabled { get; set; }
+
+        public string? Issuer { get; set; }
+
+        public string? ClientId { get; set; }
+
+        public string? ClientSecret { get; set; }
+
+        public bool RequireHttpsMetadata { get; set; } = true;
+
+        public string? MetadataAddress { get; set; }
+
+        public int BackchannelTimeoutSeconds { get; set; } = 20;
+
+        public int TokenClockSkewSeconds { get; set; } = 30;
+
+        public IList<string> Scopes { get; } = new List<string> { "scanner.scan" };
+
+        public ResilienceOptions Resilience { get; } = new();
+    }
+
+    public sealed class ResilienceOptions
+    {
+        public bool? EnableRetries { get; set; }
+
+        public IList<TimeSpan> RetryDelays { get; } = new List<TimeSpan>
+        {
+            TimeSpan.FromMilliseconds(250),
+            TimeSpan.FromMilliseconds(500),
+            TimeSpan.FromSeconds(1),
+            TimeSpan.FromSeconds(5),
+        };
+
+        public bool? AllowOfflineCacheFallback { get; set; }
+
+        public TimeSpan? OfflineCacheTolerance { get; set; }
+    }
+
+    public sealed class TelemetryOptions
+    {
+        public bool EnableLogging { get; set; } = true;
+
+        public bool EnableTelemetry { get; set; } = true;
+
+        public bool EnableTracing { get; set; }
+
+        public bool EnableMetrics { get; set; } = true;
+
+        public string ServiceName { get; set; } = "stellaops-scanner-worker";
+
+        public string? OtlpEndpoint { get; set; }
+
+        public bool ExportConsole { get; set; }
+
+        public IDictionary<string, string?> ResourceAttributes { get; } = new ConcurrentDictionary<string, string?>(StringComparer.OrdinalIgnoreCase);
+    }
+
     public sealed class ShutdownOptions
     {
         public TimeSpan Timeout { get; set; } = TimeSpan.FromSeconds(30);
     }
+
+    public sealed class AnalyzerOptions
+    {
+        public AnalyzerOptions()
+        {
+            PluginDirectories = new List<string>
+            {
+                Path.Combine("plugins", "scanner", "analyzers", "os"),
+            };
+        }
+
+        public IList<string> PluginDirectories { get; }
+
+        public string RootFilesystemMetadataKey { get; set; } = ScanMetadataKeys.RootFilesystemPath;
+
+        public string WorkspaceMetadataKey { get; set; } = ScanMetadataKeys.WorkspacePath;
+    }
 }

src/StellaOps.Scanner.Worker/Options/ScannerWorkerOptionsValidator.cs

@@ -1,91 +1,91 @@
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using Microsoft.Extensions.Options;
-
-namespace StellaOps.Scanner.Worker.Options;
-
-public sealed class ScannerWorkerOptionsValidator : IValidateOptions<ScannerWorkerOptions>
-{
-    public ValidateOptionsResult Validate(string? name, ScannerWorkerOptions options)
-    {
-        ArgumentNullException.ThrowIfNull(options);
-
-        var failures = new List<string>();
-
-        if (options.MaxConcurrentJobs <= 0)
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using Microsoft.Extensions.Options;
+
+namespace StellaOps.Scanner.Worker.Options;
+
+public sealed class ScannerWorkerOptionsValidator : IValidateOptions<ScannerWorkerOptions>
+{
+    public ValidateOptionsResult Validate(string? name, ScannerWorkerOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+
+        var failures = new List<string>();
+
+        if (options.MaxConcurrentJobs <= 0)
+        {
+            failures.Add("Scanner.Worker:MaxConcurrentJobs must be greater than zero.");
+        }
+
+        if (options.Queue.HeartbeatSafetyFactor < 3.0)
         {
-            failures.Add("Scanner.Worker:MaxConcurrentJobs must be greater than zero.");
+            failures.Add("Scanner.Worker:Queue:HeartbeatSafetyFactor must be at least 3.");
         }
-
-        if (options.Queue.HeartbeatSafetyFactor < 2.0)
-        {
-            failures.Add("Scanner.Worker:Queue:HeartbeatSafetyFactor must be at least 2.");
-        }
-
-        if (options.Queue.MaxAttempts <= 0)
-        {
-            failures.Add("Scanner.Worker:Queue:MaxAttempts must be greater than zero.");
-        }
-
-        if (options.Queue.MinHeartbeatInterval <= TimeSpan.Zero)
-        {
-            failures.Add("Scanner.Worker:Queue:MinHeartbeatInterval must be greater than zero.");
-        }
-
-        if (options.Queue.MaxHeartbeatInterval <= options.Queue.MinHeartbeatInterval)
-        {
-            failures.Add("Scanner.Worker:Queue:MaxHeartbeatInterval must be greater than MinHeartbeatInterval.");
-        }
-
-        if (options.Polling.InitialDelay <= TimeSpan.Zero)
-        {
-            failures.Add("Scanner.Worker:Polling:InitialDelay must be greater than zero.");
-        }
-
-        if (options.Polling.MaxDelay < options.Polling.InitialDelay)
-        {
-            failures.Add("Scanner.Worker:Polling:MaxDelay must be greater than or equal to InitialDelay.");
-        }
-
-        if (options.Polling.JitterRatio is < 0 or > 1)
-        {
-            failures.Add("Scanner.Worker:Polling:JitterRatio must be between 0 and 1.");
-        }
-
-        if (options.Authority.Enabled)
-        {
-            if (string.IsNullOrWhiteSpace(options.Authority.Issuer))
-            {
-                failures.Add("Scanner.Worker:Authority requires Issuer when Enabled is true.");
-            }
-
-            if (string.IsNullOrWhiteSpace(options.Authority.ClientId))
-            {
-                failures.Add("Scanner.Worker:Authority requires ClientId when Enabled is true.");
-            }
-
-            if (options.Authority.BackchannelTimeoutSeconds <= 0)
-            {
-                failures.Add("Scanner.Worker:Authority:BackchannelTimeoutSeconds must be greater than zero.");
-            }
-
-            if (options.Authority.TokenClockSkewSeconds < 0)
-            {
-                failures.Add("Scanner.Worker:Authority:TokenClockSkewSeconds cannot be negative.");
-            }
-
-            if (options.Authority.Resilience.RetryDelays.Any(delay => delay <= TimeSpan.Zero))
-            {
-                failures.Add("Scanner.Worker:Authority:Resilience:RetryDelays must be positive durations.");
-            }
-        }
-
-        if (options.Shutdown.Timeout < TimeSpan.FromSeconds(5))
-        {
-            failures.Add("Scanner.Worker:Shutdown:Timeout must be at least 5 seconds to allow lease completion.");
-        }
-
+
+        if (options.Queue.MaxAttempts <= 0)
+        {
+            failures.Add("Scanner.Worker:Queue:MaxAttempts must be greater than zero.");
+        }
+
+        if (options.Queue.MinHeartbeatInterval <= TimeSpan.Zero)
+        {
+            failures.Add("Scanner.Worker:Queue:MinHeartbeatInterval must be greater than zero.");
+        }
+
+        if (options.Queue.MaxHeartbeatInterval <= options.Queue.MinHeartbeatInterval)
+        {
+            failures.Add("Scanner.Worker:Queue:MaxHeartbeatInterval must be greater than MinHeartbeatInterval.");
+        }
+
+        if (options.Polling.InitialDelay <= TimeSpan.Zero)
+        {
+            failures.Add("Scanner.Worker:Polling:InitialDelay must be greater than zero.");
+        }
+
+        if (options.Polling.MaxDelay < options.Polling.InitialDelay)
+        {
+            failures.Add("Scanner.Worker:Polling:MaxDelay must be greater than or equal to InitialDelay.");
+        }
+
+        if (options.Polling.JitterRatio is < 0 or > 1)
+        {
+            failures.Add("Scanner.Worker:Polling:JitterRatio must be between 0 and 1.");
+        }
+
+        if (options.Authority.Enabled)
+        {
+            if (string.IsNullOrWhiteSpace(options.Authority.Issuer))
+            {
+                failures.Add("Scanner.Worker:Authority requires Issuer when Enabled is true.");
+            }
+
+            if (string.IsNullOrWhiteSpace(options.Authority.ClientId))
+            {
+                failures.Add("Scanner.Worker:Authority requires ClientId when Enabled is true.");
+            }
+
+            if (options.Authority.BackchannelTimeoutSeconds <= 0)
+            {
+                failures.Add("Scanner.Worker:Authority:BackchannelTimeoutSeconds must be greater than zero.");
+            }
+
+            if (options.Authority.TokenClockSkewSeconds < 0)
+            {
+                failures.Add("Scanner.Worker:Authority:TokenClockSkewSeconds cannot be negative.");
+            }
+
+            if (options.Authority.Resilience.RetryDelays.Any(delay => delay <= TimeSpan.Zero))
+            {
+                failures.Add("Scanner.Worker:Authority:Resilience:RetryDelays must be positive durations.");
+            }
+        }
+
+        if (options.Shutdown.Timeout < TimeSpan.FromSeconds(5))
+        {
+            failures.Add("Scanner.Worker:Shutdown:Timeout must be at least 5 seconds to allow lease completion.");
+        }
+
         if (options.Telemetry.EnableTelemetry)
         {
             if (!options.Telemetry.EnableMetrics && !options.Telemetry.EnableTracing)
@@ -94,6 +94,11 @@ public sealed class ScannerWorkerOptionsValidator : IValidateOptions<ScannerWork
             }
         }
 
+        if (string.IsNullOrWhiteSpace(options.Analyzers.RootFilesystemMetadataKey))
+        {
+            failures.Add("Scanner.Worker:Analyzers:RootFilesystemMetadataKey must be provided.");
+        }
+
         return failures.Count == 0 ? ValidateOptionsResult.Success : ValidateOptionsResult.Fail(failures);
     }
 }

src/StellaOps.Scanner.Worker/Processing/AnalyzerStageExecutor.cs

@@ -1,20 +1,20 @@
-using System;
-using System.Threading;
-using System.Threading.Tasks;
-
-namespace StellaOps.Scanner.Worker.Processing;
-
-public sealed class AnalyzerStageExecutor : IScanStageExecutor
-{
-    private readonly IScanAnalyzerDispatcher _dispatcher;
-
-    public AnalyzerStageExecutor(IScanAnalyzerDispatcher dispatcher)
-    {
-        _dispatcher = dispatcher ?? throw new ArgumentNullException(nameof(dispatcher));
-    }
-
-    public string StageName => ScanStageNames.ExecuteAnalyzers;
-
-    public ValueTask ExecuteAsync(ScanJobContext context, CancellationToken cancellationToken)
-        => _dispatcher.ExecuteAsync(context, cancellationToken);
-}
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace StellaOps.Scanner.Worker.Processing;
+
+public sealed class AnalyzerStageExecutor : IScanStageExecutor
+{
+    private readonly IScanAnalyzerDispatcher _dispatcher;
+
+    public AnalyzerStageExecutor(IScanAnalyzerDispatcher dispatcher)
+    {
+        _dispatcher = dispatcher ?? throw new ArgumentNullException(nameof(dispatcher));
+    }
+
+    public string StageName => ScanStageNames.ExecuteAnalyzers;
+
+    public ValueTask ExecuteAsync(ScanJobContext context, CancellationToken cancellationToken)
+        => _dispatcher.ExecuteAsync(context, cancellationToken);
+}

src/StellaOps.Scanner.Worker/Processing/IDelayScheduler.cs

@@ -1,10 +1,10 @@
-using System;
-using System.Threading;
-using System.Threading.Tasks;
-
-namespace StellaOps.Scanner.Worker.Processing;
-
-public interface IDelayScheduler
-{
-    Task DelayAsync(TimeSpan delay, CancellationToken cancellationToken);
-}
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace StellaOps.Scanner.Worker.Processing;
+
+public interface IDelayScheduler
+{
+    Task DelayAsync(TimeSpan delay, CancellationToken cancellationToken);
+}

src/StellaOps.Scanner.Worker/Processing/IScanAnalyzerDispatcher.cs

@@ -1,15 +1,15 @@
-using System.Threading;
-using System.Threading.Tasks;
-
-namespace StellaOps.Scanner.Worker.Processing;
-
-public interface IScanAnalyzerDispatcher
-{
-    ValueTask ExecuteAsync(ScanJobContext context, CancellationToken cancellationToken);
-}
-
-public sealed class NullScanAnalyzerDispatcher : IScanAnalyzerDispatcher
-{
-    public ValueTask ExecuteAsync(ScanJobContext context, CancellationToken cancellationToken)
-        => ValueTask.CompletedTask;
-}
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace StellaOps.Scanner.Worker.Processing;
+
+public interface IScanAnalyzerDispatcher
+{
+    ValueTask ExecuteAsync(ScanJobContext context, CancellationToken cancellationToken);
+}
+
+public sealed class NullScanAnalyzerDispatcher : IScanAnalyzerDispatcher
+{
+    public ValueTask ExecuteAsync(ScanJobContext context, CancellationToken cancellationToken)
+        => ValueTask.CompletedTask;
+}

src/StellaOps.Scanner.Worker/Processing/IScanJobLease.cs

@@ -1,31 +1,31 @@
-using System;
-using System.Collections.Generic;
-using System.Threading;
-using System.Threading.Tasks;
-
-namespace StellaOps.Scanner.Worker.Processing;
-
-public interface IScanJobLease : IAsyncDisposable
-{
-    string JobId { get; }
-
-    string ScanId { get; }
-
-    int Attempt { get; }
-
-    DateTimeOffset EnqueuedAtUtc { get; }
-
-    DateTimeOffset LeasedAtUtc { get; }
-
-    TimeSpan LeaseDuration { get; }
-
-    IReadOnlyDictionary<string, string> Metadata { get; }
-
-    ValueTask RenewAsync(CancellationToken cancellationToken);
-
-    ValueTask CompleteAsync(CancellationToken cancellationToken);
-
-    ValueTask AbandonAsync(string reason, CancellationToken cancellationToken);
-
-    ValueTask PoisonAsync(string reason, CancellationToken cancellationToken);
-}
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace StellaOps.Scanner.Worker.Processing;
+
+public interface IScanJobLease : IAsyncDisposable
+{
+    string JobId { get; }
+
+    string ScanId { get; }
+
+    int Attempt { get; }
+
+    DateTimeOffset EnqueuedAtUtc { get; }
+
+    DateTimeOffset LeasedAtUtc { get; }
+
+    TimeSpan LeaseDuration { get; }
+
+    IReadOnlyDictionary<string, string> Metadata { get; }
+
+    ValueTask RenewAsync(CancellationToken cancellationToken);
+
+    ValueTask CompleteAsync(CancellationToken cancellationToken);
+
+    ValueTask AbandonAsync(string reason, CancellationToken cancellationToken);
+
+    ValueTask PoisonAsync(string reason, CancellationToken cancellationToken);
+}

src/StellaOps.Scanner.Worker/Processing/IScanJobSource.cs

@@ -1,9 +1,9 @@
-using System.Threading;
-using System.Threading.Tasks;
-
-namespace StellaOps.Scanner.Worker.Processing;
-
-public interface IScanJobSource
-{
-    Task<IScanJobLease?> TryAcquireAsync(CancellationToken cancellationToken);
-}
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace StellaOps.Scanner.Worker.Processing;
+
+public interface IScanJobSource
+{
+    Task<IScanJobLease?> TryAcquireAsync(CancellationToken cancellationToken);
+}

src/StellaOps.Scanner.Worker/Processing/IScanStageExecutor.cs

@@ -1,11 +1,11 @@
-using System.Threading;
-using System.Threading.Tasks;
-
-namespace StellaOps.Scanner.Worker.Processing;
-
-public interface IScanStageExecutor
-{
-    string StageName { get; }
-
-    ValueTask ExecuteAsync(ScanJobContext context, CancellationToken cancellationToken);
-}
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace StellaOps.Scanner.Worker.Processing;
+
+public interface IScanStageExecutor
+{
+    string StageName { get; }
+
+    ValueTask ExecuteAsync(ScanJobContext context, CancellationToken cancellationToken);
+}

src/StellaOps.Scanner.Worker/Processing/LeaseHeartbeatService.cs

@@ -1,148 +1,155 @@
-using System;
-using System.Threading;
-using System.Threading.Tasks;
-using Microsoft.Extensions.Logging;
-using Microsoft.Extensions.Options;
-using StellaOps.Scanner.Worker.Options;
-
-namespace StellaOps.Scanner.Worker.Processing;
-
-public sealed class LeaseHeartbeatService
-{
-    private readonly TimeProvider _timeProvider;
-    private readonly IOptionsMonitor<ScannerWorkerOptions> _options;
-    private readonly IDelayScheduler _delayScheduler;
-    private readonly ILogger<LeaseHeartbeatService> _logger;
-
-    public LeaseHeartbeatService(TimeProvider timeProvider, IDelayScheduler delayScheduler, IOptionsMonitor<ScannerWorkerOptions> options, ILogger<LeaseHeartbeatService> logger)
-    {
-        _timeProvider = timeProvider ?? throw new ArgumentNullException(nameof(timeProvider));
-        _delayScheduler = delayScheduler ?? throw new ArgumentNullException(nameof(delayScheduler));
-        _options = options ?? throw new ArgumentNullException(nameof(options));
-        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
-    }
-
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using StellaOps.Scanner.Worker.Options;
+
+namespace StellaOps.Scanner.Worker.Processing;
+
+public sealed class LeaseHeartbeatService
+{
+    private readonly TimeProvider _timeProvider;
+    private readonly IOptionsMonitor<ScannerWorkerOptions> _options;
+    private readonly IDelayScheduler _delayScheduler;
+    private readonly ILogger<LeaseHeartbeatService> _logger;
+
+    public LeaseHeartbeatService(TimeProvider timeProvider, IDelayScheduler delayScheduler, IOptionsMonitor<ScannerWorkerOptions> options, ILogger<LeaseHeartbeatService> logger)
+    {
+        _timeProvider = timeProvider ?? throw new ArgumentNullException(nameof(timeProvider));
+        _delayScheduler = delayScheduler ?? throw new ArgumentNullException(nameof(delayScheduler));
+        _options = options ?? throw new ArgumentNullException(nameof(options));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
     public async Task RunAsync(IScanJobLease lease, CancellationToken cancellationToken)
     {
         ArgumentNullException.ThrowIfNull(lease);
 
-        var options = _options.CurrentValue;
-        var interval = ComputeInterval(options, lease);
+        await Task.Yield();
 
         while (!cancellationToken.IsCancellationRequested)
         {
-            options = _options.CurrentValue;
-            var delay = ApplyJitter(interval, options.Queue.MaxHeartbeatJitterMilliseconds);
+            var options = _options.CurrentValue;
+            var interval = ComputeInterval(options, lease);
+            var delay = ApplyJitter(interval, options.Queue);
             try
             {
                 await _delayScheduler.DelayAsync(delay, cancellationToken).ConfigureAwait(false);
             }
             catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
-            {
-                break;
-            }
-
-            if (cancellationToken.IsCancellationRequested)
-            {
-                break;
-            }
-
-            if (await TryRenewAsync(options, lease, cancellationToken).ConfigureAwait(false))
-            {
-                continue;
-            }
-
-            _logger.LogError(
-                "Job {JobId} (scan {ScanId}) lease renewal exhausted retries; cancelling processing.",
-                lease.JobId,
-                lease.ScanId);
-            throw new InvalidOperationException("Lease renewal retries exhausted.");
-        }
-    }
+            {
+                break;
+            }
+
+            if (cancellationToken.IsCancellationRequested)
+            {
+                break;
+            }
+
+            if (await TryRenewAsync(options, lease, cancellationToken).ConfigureAwait(false))
+            {
+                continue;
+            }
+
+            _logger.LogError(
+                "Job {JobId} (scan {ScanId}) lease renewal exhausted retries; cancelling processing.",
+                lease.JobId,
+                lease.ScanId);
+            throw new InvalidOperationException("Lease renewal retries exhausted.");
+        }
+    }
 
     private static TimeSpan ComputeInterval(ScannerWorkerOptions options, IScanJobLease lease)
     {
         var divisor = options.Queue.HeartbeatSafetyFactor <= 0 ? 3.0 : options.Queue.HeartbeatSafetyFactor;
-        var recommended = TimeSpan.FromTicks((long)(lease.LeaseDuration.Ticks / Math.Max(2.0, divisor)));
+        var safetyFactor = Math.Max(3.0, divisor);
+        var recommended = TimeSpan.FromTicks((long)(lease.LeaseDuration.Ticks / safetyFactor));
         if (recommended < options.Queue.MinHeartbeatInterval)
         {
             recommended = options.Queue.MinHeartbeatInterval;
         }
         else if (recommended > options.Queue.MaxHeartbeatInterval)
-        {
-            recommended = options.Queue.MaxHeartbeatInterval;
-        }
+        {
+            recommended = options.Queue.MaxHeartbeatInterval;
+        }
 
         return recommended;
     }
 
-    private static TimeSpan ApplyJitter(TimeSpan duration, int maxJitterMilliseconds)
+    private static TimeSpan ApplyJitter(TimeSpan duration, ScannerWorkerOptions.QueueOptions queueOptions)
     {
-        if (maxJitterMilliseconds <= 0)
+        if (queueOptions.MaxHeartbeatJitterMilliseconds <= 0)
         {
             return duration;
         }
 
-        var offset = Random.Shared.NextDouble() * maxJitterMilliseconds;
-        return duration + TimeSpan.FromMilliseconds(offset);
+        var offsetMs = Random.Shared.NextDouble() * queueOptions.MaxHeartbeatJitterMilliseconds;
+        var adjusted = duration - TimeSpan.FromMilliseconds(offsetMs);
+        if (adjusted < queueOptions.MinHeartbeatInterval)
+        {
+            return queueOptions.MinHeartbeatInterval;
+        }
+
+        return adjusted > TimeSpan.Zero ? adjusted : queueOptions.MinHeartbeatInterval;
     }
 
     private async Task<bool> TryRenewAsync(ScannerWorkerOptions options, IScanJobLease lease, CancellationToken cancellationToken)
     {
         try
-        {
-            await lease.RenewAsync(cancellationToken).ConfigureAwait(false);
-            return true;
-        }
-        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
-        {
-            return false;
-        }
-        catch (Exception ex)
-        {
-            _logger.LogWarning(
-                ex,
-                "Job {JobId} (scan {ScanId}) heartbeat failed; retrying.",
-                lease.JobId,
-                lease.ScanId);
-        }
-
-        foreach (var delay in options.Queue.NormalizedHeartbeatRetryDelays)
-        {
-            if (cancellationToken.IsCancellationRequested)
-            {
-                return false;
-            }
-
-            try
-            {
-                await _delayScheduler.DelayAsync(delay, cancellationToken).ConfigureAwait(false);
-            }
-            catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
-            {
-                return false;
-            }
-
-            try
-            {
-                await lease.RenewAsync(cancellationToken).ConfigureAwait(false);
-                return true;
-            }
-            catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
-            {
-                return false;
-            }
-            catch (Exception ex)
-            {
-                _logger.LogWarning(
-                    ex,
-                    "Job {JobId} (scan {ScanId}) heartbeat retry failed; will retry after {Delay}.",
-                    lease.JobId,
-                    lease.ScanId,
-                    delay);
-            }
-        }
-
-        return false;
-    }
-}
+        {
+            await lease.RenewAsync(cancellationToken).ConfigureAwait(false);
+            return true;
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            return false;
+        }
+        catch (Exception ex)
+        {
+            _logger.LogWarning(
+                ex,
+                "Job {JobId} (scan {ScanId}) heartbeat failed; retrying.",
+                lease.JobId,
+                lease.ScanId);
+        }
+
+        foreach (var delay in options.Queue.NormalizedHeartbeatRetryDelays)
+        {
+            if (cancellationToken.IsCancellationRequested)
+            {
+                return false;
+            }
+
+            try
+            {
+                await _delayScheduler.DelayAsync(delay, cancellationToken).ConfigureAwait(false);
+            }
+            catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+            {
+                return false;
+            }
+
+            try
+            {
+                await lease.RenewAsync(cancellationToken).ConfigureAwait(false);
+                return true;
+            }
+            catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+            {
+                return false;
+            }
+            catch (Exception ex)
+            {
+                _logger.LogWarning(
+                    ex,
+                    "Job {JobId} (scan {ScanId}) heartbeat retry failed; will retry after {Delay}.",
+                    lease.JobId,
+                    lease.ScanId,
+                    delay);
+            }
+        }
+
+        return false;
+    }
+}

src/StellaOps.Scanner.Worker/Processing/NoOpStageExecutor.cs

@@ -1,18 +1,18 @@
-using System;
-using System.Threading;
-using System.Threading.Tasks;
-
-namespace StellaOps.Scanner.Worker.Processing;
-
-public sealed class NoOpStageExecutor : IScanStageExecutor
-{
-    public NoOpStageExecutor(string stageName)
-    {
-        StageName = stageName ?? throw new ArgumentNullException(nameof(stageName));
-    }
-
-    public string StageName { get; }
-
-    public ValueTask ExecuteAsync(ScanJobContext context, CancellationToken cancellationToken)
-        => ValueTask.CompletedTask;
-}
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace StellaOps.Scanner.Worker.Processing;
+
+public sealed class NoOpStageExecutor : IScanStageExecutor
+{
+    public NoOpStageExecutor(string stageName)
+    {
+        StageName = stageName ?? throw new ArgumentNullException(nameof(stageName));
+    }
+
+    public string StageName { get; }
+
+    public ValueTask ExecuteAsync(ScanJobContext context, CancellationToken cancellationToken)
+        => ValueTask.CompletedTask;
+}

src/StellaOps.Scanner.Worker/Processing/NullScanJobSource.cs

@@ -1,26 +1,26 @@
-using System.Threading;
-using System.Threading.Tasks;
-using Microsoft.Extensions.Logging;
-
-namespace StellaOps.Scanner.Worker.Processing;
-
-public sealed class NullScanJobSource : IScanJobSource
-{
-    private readonly ILogger<NullScanJobSource> _logger;
-    private int _logged;
-
-    public NullScanJobSource(ILogger<NullScanJobSource> logger)
-    {
-        _logger = logger;
-    }
-
-    public Task<IScanJobLease?> TryAcquireAsync(CancellationToken cancellationToken)
-    {
-        if (Interlocked.Exchange(ref _logged, 1) == 0)
-        {
-            _logger.LogWarning("No queue provider registered. Scanner worker will idle until a queue adapter is configured.");
-        }
-
-        return Task.FromResult<IScanJobLease?>(null);
-    }
-}
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Logging;
+
+namespace StellaOps.Scanner.Worker.Processing;
+
+public sealed class NullScanJobSource : IScanJobSource
+{
+    private readonly ILogger<NullScanJobSource> _logger;
+    private int _logged;
+
+    public NullScanJobSource(ILogger<NullScanJobSource> logger)
+    {
+        _logger = logger;
+    }
+
+    public Task<IScanJobLease?> TryAcquireAsync(CancellationToken cancellationToken)
+    {
+        if (Interlocked.Exchange(ref _logged, 1) == 0)
+        {
+            _logger.LogWarning("No queue provider registered. Scanner worker will idle until a queue adapter is configured.");
+        }
+
+        return Task.FromResult<IScanJobLease?>(null);
+    }
+}

src/StellaOps.Scanner.Worker/Processing/OsScanAnalyzerDispatcher.cs

@@ -0,0 +1,153 @@
+using System;
+using System.Collections.Generic;
+using System.Collections.ObjectModel;
+using System.IO;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using StellaOps.Scanner.Analyzers.OS;
+using StellaOps.Scanner.Analyzers.OS.Abstractions;
+using StellaOps.Scanner.Analyzers.OS.Plugin;
+using StellaOps.Scanner.Core.Contracts;
+using StellaOps.Scanner.Worker.Options;
+
+namespace StellaOps.Scanner.Worker.Processing;
+
+internal sealed class OsScanAnalyzerDispatcher : IScanAnalyzerDispatcher
+{
+    private readonly IServiceScopeFactory _scopeFactory;
+    private readonly OsAnalyzerPluginCatalog _catalog;
+    private readonly ScannerWorkerOptions _options;
+    private readonly ILogger<OsScanAnalyzerDispatcher> _logger;
+    private IReadOnlyList<string> _pluginDirectories = Array.Empty<string>();
+
+    public OsScanAnalyzerDispatcher(
+        IServiceScopeFactory scopeFactory,
+        OsAnalyzerPluginCatalog catalog,
+        IOptions<ScannerWorkerOptions> options,
+        ILogger<OsScanAnalyzerDispatcher> logger)
+    {
+        _scopeFactory = scopeFactory ?? throw new ArgumentNullException(nameof(scopeFactory));
+        _catalog = catalog ?? throw new ArgumentNullException(nameof(catalog));
+        _options = options?.Value ?? throw new ArgumentNullException(nameof(options));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+
+        LoadPlugins();
+    }
+
+    public async ValueTask ExecuteAsync(ScanJobContext context, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+
+        using var scope = _scopeFactory.CreateScope();
+        var services = scope.ServiceProvider;
+        var analyzers = _catalog.CreateAnalyzers(services);
+        if (analyzers.Count == 0)
+        {
+            _logger.LogWarning("No OS analyzers available; skipping analyzer stage for job {JobId}.", context.JobId);
+            return;
+        }
+
+        var metadata = new Dictionary<string, string>(context.Lease.Metadata, StringComparer.Ordinal);
+        var rootfsPath = ResolvePath(metadata, _options.Analyzers.RootFilesystemMetadataKey);
+        if (rootfsPath is null)
+        {
+            _logger.LogWarning(
+                "Metadata key '{MetadataKey}' missing for job {JobId}; unable to locate root filesystem. OS analyzers skipped.",
+                _options.Analyzers.RootFilesystemMetadataKey,
+                context.JobId);
+            return;
+        }
+
+        var workspacePath = ResolvePath(metadata, _options.Analyzers.WorkspaceMetadataKey);
+        var loggerFactory = services.GetRequiredService<ILoggerFactory>();
+
+        var results = new List<OSPackageAnalyzerResult>(analyzers.Count);
+
+        foreach (var analyzer in analyzers)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            var analyzerLogger = loggerFactory.CreateLogger(analyzer.GetType());
+            var analyzerContext = new OSPackageAnalyzerContext(rootfsPath, workspacePath, context.TimeProvider, analyzerLogger, metadata);
+
+            try
+            {
+                var result = await analyzer.AnalyzeAsync(analyzerContext, cancellationToken).ConfigureAwait(false);
+                results.Add(result);
+            }
+            catch (Exception ex)
+            {
+                _logger.LogError(ex, "Analyzer {AnalyzerId} failed for job {JobId}.", analyzer.AnalyzerId, context.JobId);
+            }
+        }
+
+        if (results.Count > 0)
+        {
+            var dictionary = results.ToDictionary(result => result.AnalyzerId, StringComparer.OrdinalIgnoreCase);
+            context.Analysis.Set(ScanAnalysisKeys.OsPackageAnalyzers, dictionary);
+        }
+    }
+
+    private void LoadPlugins()
+    {
+        var directories = new List<string>();
+        foreach (var configured in _options.Analyzers.PluginDirectories)
+        {
+            if (string.IsNullOrWhiteSpace(configured))
+            {
+                continue;
+            }
+
+            var path = configured;
+            if (!Path.IsPathRooted(path))
+            {
+                path = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, path));
+            }
+
+            directories.Add(path);
+        }
+
+        if (directories.Count == 0)
+        {
+            directories.Add(Path.Combine(AppContext.BaseDirectory, "plugins", "scanner", "analyzers", "os"));
+        }
+
+        _pluginDirectories = new ReadOnlyCollection<string>(directories);
+
+        for (var i = 0; i < _pluginDirectories.Count; i++)
+        {
+            var directory = _pluginDirectories[i];
+            var seal = i == _pluginDirectories.Count - 1;
+
+            try
+            {
+                _catalog.LoadFromDirectory(directory, seal);
+            }
+            catch (Exception ex)
+            {
+                _logger.LogWarning(ex, "Failed to load analyzer plug-ins from {Directory}.", directory);
+            }
+        }
+    }
+
+    private static string? ResolvePath(IReadOnlyDictionary<string, string> metadata, string key)
+    {
+        if (string.IsNullOrWhiteSpace(key))
+        {
+            return null;
+        }
+
+        if (!metadata.TryGetValue(key, out var value) || string.IsNullOrWhiteSpace(value))
+        {
+            return null;
+        }
+
+        var trimmed = value.Trim();
+        return Path.IsPathRooted(trimmed)
+            ? trimmed
+            : Path.GetFullPath(trimmed);
+    }
+}

src/StellaOps.Scanner.Worker/Processing/PollDelayStrategy.cs

@@ -1,49 +1,49 @@
-using System;
-
-using StellaOps.Scanner.Worker.Options;
-
-namespace StellaOps.Scanner.Worker.Processing;
-
-public sealed class PollDelayStrategy
-{
-    private readonly ScannerWorkerOptions.PollingOptions _options;
-    private TimeSpan _currentDelay;
-
-    public PollDelayStrategy(ScannerWorkerOptions.PollingOptions options)
-    {
-        _options = options ?? throw new ArgumentNullException(nameof(options));
-    }
-
-    public TimeSpan NextDelay()
-    {
-        if (_currentDelay == TimeSpan.Zero)
-        {
-            _currentDelay = _options.InitialDelay;
-            return ApplyJitter(_currentDelay);
-        }
-
-        var doubled = _currentDelay + _currentDelay;
-        _currentDelay = doubled < _options.MaxDelay ? doubled : _options.MaxDelay;
-        return ApplyJitter(_currentDelay);
-    }
-
-    public void Reset() => _currentDelay = TimeSpan.Zero;
-
-    private TimeSpan ApplyJitter(TimeSpan duration)
-    {
-        if (_options.JitterRatio <= 0)
-        {
-            return duration;
-        }
-
-        var maxOffset = duration.TotalMilliseconds * _options.JitterRatio;
-        if (maxOffset <= 0)
-        {
-            return duration;
-        }
-
-        var offset = (Random.Shared.NextDouble() * 2.0 - 1.0) * maxOffset;
-        var adjustedMs = Math.Max(0, duration.TotalMilliseconds + offset);
-        return TimeSpan.FromMilliseconds(adjustedMs);
-    }
-}
+using System;
+
+using StellaOps.Scanner.Worker.Options;
+
+namespace StellaOps.Scanner.Worker.Processing;
+
+public sealed class PollDelayStrategy
+{
+    private readonly ScannerWorkerOptions.PollingOptions _options;
+    private TimeSpan _currentDelay;
+
+    public PollDelayStrategy(ScannerWorkerOptions.PollingOptions options)
+    {
+        _options = options ?? throw new ArgumentNullException(nameof(options));
+    }
+
+    public TimeSpan NextDelay()
+    {
+        if (_currentDelay == TimeSpan.Zero)
+        {
+            _currentDelay = _options.InitialDelay;
+            return ApplyJitter(_currentDelay);
+        }
+
+        var doubled = _currentDelay + _currentDelay;
+        _currentDelay = doubled < _options.MaxDelay ? doubled : _options.MaxDelay;
+        return ApplyJitter(_currentDelay);
+    }
+
+    public void Reset() => _currentDelay = TimeSpan.Zero;
+
+    private TimeSpan ApplyJitter(TimeSpan duration)
+    {
+        if (_options.JitterRatio <= 0)
+        {
+            return duration;
+        }
+
+        var maxOffset = duration.TotalMilliseconds * _options.JitterRatio;
+        if (maxOffset <= 0)
+        {
+            return duration;
+        }
+
+        var offset = (Random.Shared.NextDouble() * 2.0 - 1.0) * maxOffset;
+        var adjustedMs = Math.Max(0, duration.TotalMilliseconds + offset);
+        return TimeSpan.FromMilliseconds(adjustedMs);
+    }
+}

src/StellaOps.Scanner.Worker/Processing/ScanJobContext.cs

@@ -1,27 +1,31 @@
 using System;
 using System.Threading;
-
-namespace StellaOps.Scanner.Worker.Processing;
-
-public sealed class ScanJobContext
-{
+using StellaOps.Scanner.Core.Contracts;
+
+namespace StellaOps.Scanner.Worker.Processing;
+
+public sealed class ScanJobContext
+{
     public ScanJobContext(IScanJobLease lease, TimeProvider timeProvider, DateTimeOffset startUtc, CancellationToken cancellationToken)
     {
         Lease = lease ?? throw new ArgumentNullException(nameof(lease));
         TimeProvider = timeProvider ?? throw new ArgumentNullException(nameof(timeProvider));
         StartUtc = startUtc;
         CancellationToken = cancellationToken;
+        Analysis = new ScanAnalysisStore();
     }
-
-    public IScanJobLease Lease { get; }
-
-    public TimeProvider TimeProvider { get; }
-
-    public DateTimeOffset StartUtc { get; }
-
-    public CancellationToken CancellationToken { get; }
-
-    public string JobId => Lease.JobId;
-
+
+    public IScanJobLease Lease { get; }
+
+    public TimeProvider TimeProvider { get; }
+
+    public DateTimeOffset StartUtc { get; }
+
+    public CancellationToken CancellationToken { get; }
+
+    public string JobId => Lease.JobId;
+
     public string ScanId => Lease.ScanId;
+
+    public ScanAnalysisStore Analysis { get; }
 }

src/StellaOps.Scanner.Worker/Processing/ScanJobProcessor.cs

@@ -1,65 +1,65 @@
-using System;
-using System.Collections.Generic;
-using System.Threading;
-using System.Threading.Tasks;
-using Microsoft.Extensions.Logging;
-
-namespace StellaOps.Scanner.Worker.Processing;
-
-public sealed class ScanJobProcessor
-{
-    private readonly IReadOnlyDictionary<string, IScanStageExecutor> _executors;
-    private readonly ScanProgressReporter _progressReporter;
-    private readonly ILogger<ScanJobProcessor> _logger;
-
-    public ScanJobProcessor(IEnumerable<IScanStageExecutor> executors, ScanProgressReporter progressReporter, ILogger<ScanJobProcessor> logger)
-    {
-        _progressReporter = progressReporter ?? throw new ArgumentNullException(nameof(progressReporter));
-        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
-
-        var map = new Dictionary<string, IScanStageExecutor>(StringComparer.OrdinalIgnoreCase);
-        foreach (var executor in executors ?? Array.Empty<IScanStageExecutor>())
-        {
-            if (executor is null || string.IsNullOrWhiteSpace(executor.StageName))
-            {
-                continue;
-            }
-
-            map[executor.StageName] = executor;
-        }
-
-        foreach (var stage in ScanStageNames.Ordered)
-        {
-            if (map.ContainsKey(stage))
-            {
-                continue;
-            }
-
-            map[stage] = new NoOpStageExecutor(stage);
-            _logger.LogDebug("No executor registered for stage {Stage}; using no-op placeholder.", stage);
-        }
-
-        _executors = map;
-    }
-
-    public async ValueTask ExecuteAsync(ScanJobContext context, CancellationToken cancellationToken)
-    {
-        ArgumentNullException.ThrowIfNull(context);
-
-        foreach (var stage in ScanStageNames.Ordered)
-        {
-            cancellationToken.ThrowIfCancellationRequested();
-
-            if (!_executors.TryGetValue(stage, out var executor))
-            {
-                continue;
-            }
-
-            await _progressReporter.ExecuteStageAsync(
-                context,
-                stage,
-                executor.ExecuteAsync,
-                cancellationToken).ConfigureAwait(false);
-        }
-    }
-}
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Logging;
+
+namespace StellaOps.Scanner.Worker.Processing;
+
+public sealed class ScanJobProcessor
+{
+    private readonly IReadOnlyDictionary<string, IScanStageExecutor> _executors;
+    private readonly ScanProgressReporter _progressReporter;
+    private readonly ILogger<ScanJobProcessor> _logger;
+
+    public ScanJobProcessor(IEnumerable<IScanStageExecutor> executors, ScanProgressReporter progressReporter, ILogger<ScanJobProcessor> logger)
+    {
+        _progressReporter = progressReporter ?? throw new ArgumentNullException(nameof(progressReporter));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+
+        var map = new Dictionary<string, IScanStageExecutor>(StringComparer.OrdinalIgnoreCase);
+        foreach (var executor in executors ?? Array.Empty<IScanStageExecutor>())
+        {
+            if (executor is null || string.IsNullOrWhiteSpace(executor.StageName))
+            {
+                continue;
+            }
+
+            map[executor.StageName] = executor;
+        }
+
+        foreach (var stage in ScanStageNames.Ordered)
+        {
+            if (map.ContainsKey(stage))
+            {
+                continue;
+            }
+
+            map[stage] = new NoOpStageExecutor(stage);
+            _logger.LogDebug("No executor registered for stage {Stage}; using no-op placeholder.", stage);
+        }
+
+        _executors = map;
+    }
+
+    public async ValueTask ExecuteAsync(ScanJobContext context, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+
+        foreach (var stage in ScanStageNames.Ordered)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+
+            if (!_executors.TryGetValue(stage, out var executor))
+            {
+                continue;
+            }
+
+            await _progressReporter.ExecuteStageAsync(
+                context,
+                stage,
+                executor.ExecuteAsync,
+                cancellationToken).ConfigureAwait(false);
+        }
+    }
+}

src/StellaOps.Scanner.Worker/Processing/ScanProgressReporter.cs

@@ -1,86 +1,86 @@
-using System;
-using System.Diagnostics;
-using System.Threading;
-using System.Threading.Tasks;
-using Microsoft.Extensions.Logging;
-using StellaOps.Scanner.Worker.Diagnostics;
-
-namespace StellaOps.Scanner.Worker.Processing;
-
-public sealed partial class ScanProgressReporter
-{
-    private readonly ScannerWorkerMetrics _metrics;
-    private readonly ILogger<ScanProgressReporter> _logger;
-
-    public ScanProgressReporter(ScannerWorkerMetrics metrics, ILogger<ScanProgressReporter> logger)
-    {
-        _metrics = metrics ?? throw new ArgumentNullException(nameof(metrics));
-        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
-    }
-
-    public async ValueTask ExecuteStageAsync(
-        ScanJobContext context,
-        string stageName,
-        Func<ScanJobContext, CancellationToken, ValueTask> stageWork,
-        CancellationToken cancellationToken)
-    {
-        ArgumentNullException.ThrowIfNull(context);
-        ArgumentException.ThrowIfNullOrWhiteSpace(stageName);
-        ArgumentNullException.ThrowIfNull(stageWork);
-
-        StageStarting(_logger, context.JobId, context.ScanId, stageName, context.Lease.Attempt);
-
-        var start = context.TimeProvider.GetUtcNow();
-        using var activity = ScannerWorkerInstrumentation.ActivitySource.StartActivity(
-            $"scanner.worker.{stageName}",
-            ActivityKind.Internal);
-
-        activity?.SetTag("scanner.worker.job_id", context.JobId);
-        activity?.SetTag("scanner.worker.scan_id", context.ScanId);
-        activity?.SetTag("scanner.worker.stage", stageName);
-
-        try
-        {
-            await stageWork(context, cancellationToken).ConfigureAwait(false);
-            var duration = context.TimeProvider.GetUtcNow() - start;
-            _metrics.RecordStageDuration(context, stageName, duration);
-            StageCompleted(_logger, context.JobId, context.ScanId, stageName, duration.TotalMilliseconds);
-        }
-        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
-        {
-            StageCancelled(_logger, context.JobId, context.ScanId, stageName);
-            throw;
-        }
-        catch (Exception ex)
-        {
-            var duration = context.TimeProvider.GetUtcNow() - start;
-            _metrics.RecordStageDuration(context, stageName, duration);
-            StageFailed(_logger, context.JobId, context.ScanId, stageName, ex);
-            throw;
-        }
-    }
-
-    [LoggerMessage(
-        EventId = 1000,
-        Level = LogLevel.Information,
-        Message = "Job {JobId} (scan {ScanId}) entering stage {Stage} (attempt {Attempt}).")]
-    private static partial void StageStarting(ILogger logger, string jobId, string scanId, string stage, int attempt);
-
-    [LoggerMessage(
-        EventId = 1001,
-        Level = LogLevel.Information,
-        Message = "Job {JobId} (scan {ScanId}) finished stage {Stage} in {ElapsedMs:F0} ms.")]
-    private static partial void StageCompleted(ILogger logger, string jobId, string scanId, string stage, double elapsedMs);
-
-    [LoggerMessage(
-        EventId = 1002,
-        Level = LogLevel.Warning,
-        Message = "Job {JobId} (scan {ScanId}) stage {Stage} cancelled by request.")]
-    private static partial void StageCancelled(ILogger logger, string jobId, string scanId, string stage);
-
-    [LoggerMessage(
-        EventId = 1003,
-        Level = LogLevel.Error,
-        Message = "Job {JobId} (scan {ScanId}) stage {Stage} failed.")]
-    private static partial void StageFailed(ILogger logger, string jobId, string scanId, string stage, Exception exception);
-}
+using System;
+using System.Diagnostics;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Logging;
+using StellaOps.Scanner.Worker.Diagnostics;
+
+namespace StellaOps.Scanner.Worker.Processing;
+
+public sealed partial class ScanProgressReporter
+{
+    private readonly ScannerWorkerMetrics _metrics;
+    private readonly ILogger<ScanProgressReporter> _logger;
+
+    public ScanProgressReporter(ScannerWorkerMetrics metrics, ILogger<ScanProgressReporter> logger)
+    {
+        _metrics = metrics ?? throw new ArgumentNullException(nameof(metrics));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    public async ValueTask ExecuteStageAsync(
+        ScanJobContext context,
+        string stageName,
+        Func<ScanJobContext, CancellationToken, ValueTask> stageWork,
+        CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+        ArgumentException.ThrowIfNullOrWhiteSpace(stageName);
+        ArgumentNullException.ThrowIfNull(stageWork);
+
+        StageStarting(_logger, context.JobId, context.ScanId, stageName, context.Lease.Attempt);
+
+        var start = context.TimeProvider.GetUtcNow();
+        using var activity = ScannerWorkerInstrumentation.ActivitySource.StartActivity(
+            $"scanner.worker.{stageName}",
+            ActivityKind.Internal);
+
+        activity?.SetTag("scanner.worker.job_id", context.JobId);
+        activity?.SetTag("scanner.worker.scan_id", context.ScanId);
+        activity?.SetTag("scanner.worker.stage", stageName);
+
+        try
+        {
+            await stageWork(context, cancellationToken).ConfigureAwait(false);
+            var duration = context.TimeProvider.GetUtcNow() - start;
+            _metrics.RecordStageDuration(context, stageName, duration);
+            StageCompleted(_logger, context.JobId, context.ScanId, stageName, duration.TotalMilliseconds);
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            StageCancelled(_logger, context.JobId, context.ScanId, stageName);
+            throw;
+        }
+        catch (Exception ex)
+        {
+            var duration = context.TimeProvider.GetUtcNow() - start;
+            _metrics.RecordStageDuration(context, stageName, duration);
+            StageFailed(_logger, context.JobId, context.ScanId, stageName, ex);
+            throw;
+        }
+    }
+
+    [LoggerMessage(
+        EventId = 1000,
+        Level = LogLevel.Information,
+        Message = "Job {JobId} (scan {ScanId}) entering stage {Stage} (attempt {Attempt}).")]
+    private static partial void StageStarting(ILogger logger, string jobId, string scanId, string stage, int attempt);
+
+    [LoggerMessage(
+        EventId = 1001,
+        Level = LogLevel.Information,
+        Message = "Job {JobId} (scan {ScanId}) finished stage {Stage} in {ElapsedMs:F0} ms.")]
+    private static partial void StageCompleted(ILogger logger, string jobId, string scanId, string stage, double elapsedMs);
+
+    [LoggerMessage(
+        EventId = 1002,
+        Level = LogLevel.Warning,
+        Message = "Job {JobId} (scan {ScanId}) stage {Stage} cancelled by request.")]
+    private static partial void StageCancelled(ILogger logger, string jobId, string scanId, string stage);
+
+    [LoggerMessage(
+        EventId = 1003,
+        Level = LogLevel.Error,
+        Message = "Job {JobId} (scan {ScanId}) stage {Stage} failed.")]
+    private static partial void StageFailed(ILogger logger, string jobId, string scanId, string stage, Exception exception);
+}

src/StellaOps.Scanner.Worker/Processing/ScanStageNames.cs

@@ -1,23 +1,23 @@
-using System.Collections.Generic;
-
-namespace StellaOps.Scanner.Worker.Processing;
-
-public static class ScanStageNames
-{
-    public const string ResolveImage = "resolve-image";
-    public const string PullLayers = "pull-layers";
-    public const string BuildFilesystem = "build-filesystem";
-    public const string ExecuteAnalyzers = "execute-analyzers";
-    public const string ComposeArtifacts = "compose-artifacts";
-    public const string EmitReports = "emit-reports";
-
-    public static readonly IReadOnlyList<string> Ordered = new[]
-    {
-        ResolveImage,
-        PullLayers,
-        BuildFilesystem,
-        ExecuteAnalyzers,
-        ComposeArtifacts,
-        EmitReports,
-    };
-}
+using System.Collections.Generic;
+
+namespace StellaOps.Scanner.Worker.Processing;
+
+public static class ScanStageNames
+{
+    public const string ResolveImage = "resolve-image";
+    public const string PullLayers = "pull-layers";
+    public const string BuildFilesystem = "build-filesystem";
+    public const string ExecuteAnalyzers = "execute-analyzers";
+    public const string ComposeArtifacts = "compose-artifacts";
+    public const string EmitReports = "emit-reports";
+
+    public static readonly IReadOnlyList<string> Ordered = new[]
+    {
+        ResolveImage,
+        PullLayers,
+        BuildFilesystem,
+        ExecuteAnalyzers,
+        ComposeArtifacts,
+        EmitReports,
+    };
+}

src/StellaOps.Scanner.Worker/Processing/SystemDelayScheduler.cs

@@ -1,18 +1,18 @@
-using System;
-using System.Threading;
-using System.Threading.Tasks;
-
-namespace StellaOps.Scanner.Worker.Processing;
-
-public sealed class SystemDelayScheduler : IDelayScheduler
-{
-    public Task DelayAsync(TimeSpan delay, CancellationToken cancellationToken)
-    {
-        if (delay <= TimeSpan.Zero)
-        {
-            return Task.CompletedTask;
-        }
-
-        return Task.Delay(delay, cancellationToken);
-    }
-}
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace StellaOps.Scanner.Worker.Processing;
+
+public sealed class SystemDelayScheduler : IDelayScheduler
+{
+    public Task DelayAsync(TimeSpan delay, CancellationToken cancellationToken)
+    {
+        if (delay <= TimeSpan.Zero)
+        {
+            return Task.CompletedTask;
+        }
+
+        return Task.Delay(delay, cancellationToken);
+    }
+}

src/StellaOps.Scanner.Worker/Program.cs

@@ -1,98 +1,103 @@
-using System.Diagnostics;
-using Microsoft.Extensions.DependencyInjection;
-using Microsoft.Extensions.Hosting;
-using Microsoft.Extensions.Logging;
-using Microsoft.Extensions.Options;
-using Microsoft.Extensions.DependencyInjection.Extensions;
-using StellaOps.Auth.Client;
+using System.Diagnostics;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+using StellaOps.Auth.Client;
+using StellaOps.Scanner.Analyzers.OS.Plugin;
+using StellaOps.Scanner.EntryTrace;
 using StellaOps.Scanner.Worker.Diagnostics;
 using StellaOps.Scanner.Worker.Hosting;
 using StellaOps.Scanner.Worker.Options;
 using StellaOps.Scanner.Worker.Processing;
-
-var builder = Host.CreateApplicationBuilder(args);
-
-builder.Services.AddOptions<ScannerWorkerOptions>()
-    .BindConfiguration(ScannerWorkerOptions.SectionName)
-    .ValidateOnStart();
-
-builder.Services.AddSingleton<IValidateOptions<ScannerWorkerOptions>, ScannerWorkerOptionsValidator>();
-builder.Services.AddSingleton(TimeProvider.System);
-builder.Services.AddSingleton<ScannerWorkerMetrics>();
-builder.Services.AddSingleton<ScanProgressReporter>();
-builder.Services.AddSingleton<ScanJobProcessor>();
+
+var builder = Host.CreateApplicationBuilder(args);
+
+builder.Services.AddOptions<ScannerWorkerOptions>()
+    .BindConfiguration(ScannerWorkerOptions.SectionName)
+    .ValidateOnStart();
+
+builder.Services.AddSingleton<IValidateOptions<ScannerWorkerOptions>, ScannerWorkerOptionsValidator>();
+builder.Services.AddSingleton(TimeProvider.System);
+builder.Services.AddSingleton<ScannerWorkerMetrics>();
+builder.Services.AddSingleton<ScanProgressReporter>();
+builder.Services.AddSingleton<ScanJobProcessor>();
 builder.Services.AddSingleton<LeaseHeartbeatService>();
 builder.Services.AddSingleton<IDelayScheduler, SystemDelayScheduler>();
 
+builder.Services.AddEntryTraceAnalyzer();
+
 builder.Services.TryAddSingleton<IScanJobSource, NullScanJobSource>();
-builder.Services.TryAddSingleton<IScanAnalyzerDispatcher, NullScanAnalyzerDispatcher>();
-builder.Services.AddSingleton<IScanStageExecutor, AnalyzerStageExecutor>();
-
-builder.Services.AddSingleton<ScannerWorkerHostedService>();
-builder.Services.AddHostedService(sp => sp.GetRequiredService<ScannerWorkerHostedService>());
-
-var workerOptions = builder.Configuration.GetSection(ScannerWorkerOptions.SectionName).Get<ScannerWorkerOptions>() ?? new ScannerWorkerOptions();
-
-builder.Services.Configure<HostOptions>(options =>
-{
-    options.ShutdownTimeout = workerOptions.Shutdown.Timeout;
-});
-
-builder.ConfigureScannerWorkerTelemetry(workerOptions);
-
-if (workerOptions.Authority.Enabled)
-{
-    builder.Services.AddStellaOpsAuthClient(clientOptions =>
-    {
-        clientOptions.Authority = workerOptions.Authority.Issuer?.Trim() ?? string.Empty;
-        clientOptions.ClientId = workerOptions.Authority.ClientId?.Trim() ?? string.Empty;
-        clientOptions.ClientSecret = workerOptions.Authority.ClientSecret;
-        clientOptions.EnableRetries = workerOptions.Authority.Resilience.EnableRetries ?? true;
-        clientOptions.HttpTimeout = TimeSpan.FromSeconds(workerOptions.Authority.BackchannelTimeoutSeconds);
-
-        clientOptions.DefaultScopes.Clear();
-        foreach (var scope in workerOptions.Authority.Scopes)
-        {
-            if (string.IsNullOrWhiteSpace(scope))
-            {
-                continue;
-            }
-
-            clientOptions.DefaultScopes.Add(scope);
-        }
-
-        clientOptions.RetryDelays.Clear();
-        foreach (var delay in workerOptions.Authority.Resilience.RetryDelays)
-        {
-            if (delay <= TimeSpan.Zero)
-            {
-                continue;
-            }
-
-            clientOptions.RetryDelays.Add(delay);
-        }
-
-        if (workerOptions.Authority.Resilience.AllowOfflineCacheFallback is bool allowOffline)
-        {
-            clientOptions.AllowOfflineCacheFallback = allowOffline;
-        }
-
-        if (workerOptions.Authority.Resilience.OfflineCacheTolerance is { } tolerance && tolerance > TimeSpan.Zero)
-        {
-            clientOptions.OfflineCacheTolerance = tolerance;
-        }
-    });
-}
-
-builder.Logging.Configure(options =>
-{
-    options.ActivityTrackingOptions = ActivityTrackingOptions.SpanId
-        | ActivityTrackingOptions.TraceId
-        | ActivityTrackingOptions.ParentId;
-});
-
-var host = builder.Build();
-
-await host.RunAsync();
-
-public partial class Program;
+builder.Services.AddSingleton<OsAnalyzerPluginCatalog>();
+builder.Services.AddSingleton<IScanAnalyzerDispatcher, OsScanAnalyzerDispatcher>();
+builder.Services.AddSingleton<IScanStageExecutor, AnalyzerStageExecutor>();
+
+builder.Services.AddSingleton<ScannerWorkerHostedService>();
+builder.Services.AddHostedService(sp => sp.GetRequiredService<ScannerWorkerHostedService>());
+
+var workerOptions = builder.Configuration.GetSection(ScannerWorkerOptions.SectionName).Get<ScannerWorkerOptions>() ?? new ScannerWorkerOptions();
+
+builder.Services.Configure<HostOptions>(options =>
+{
+    options.ShutdownTimeout = workerOptions.Shutdown.Timeout;
+});
+
+builder.ConfigureScannerWorkerTelemetry(workerOptions);
+
+if (workerOptions.Authority.Enabled)
+{
+    builder.Services.AddStellaOpsAuthClient(clientOptions =>
+    {
+        clientOptions.Authority = workerOptions.Authority.Issuer?.Trim() ?? string.Empty;
+        clientOptions.ClientId = workerOptions.Authority.ClientId?.Trim() ?? string.Empty;
+        clientOptions.ClientSecret = workerOptions.Authority.ClientSecret;
+        clientOptions.EnableRetries = workerOptions.Authority.Resilience.EnableRetries ?? true;
+        clientOptions.HttpTimeout = TimeSpan.FromSeconds(workerOptions.Authority.BackchannelTimeoutSeconds);
+
+        clientOptions.DefaultScopes.Clear();
+        foreach (var scope in workerOptions.Authority.Scopes)
+        {
+            if (string.IsNullOrWhiteSpace(scope))
+            {
+                continue;
+            }
+
+            clientOptions.DefaultScopes.Add(scope);
+        }
+
+        clientOptions.RetryDelays.Clear();
+        foreach (var delay in workerOptions.Authority.Resilience.RetryDelays)
+        {
+            if (delay <= TimeSpan.Zero)
+            {
+                continue;
+            }
+
+            clientOptions.RetryDelays.Add(delay);
+        }
+
+        if (workerOptions.Authority.Resilience.AllowOfflineCacheFallback is bool allowOffline)
+        {
+            clientOptions.AllowOfflineCacheFallback = allowOffline;
+        }
+
+        if (workerOptions.Authority.Resilience.OfflineCacheTolerance is { } tolerance && tolerance > TimeSpan.Zero)
+        {
+            clientOptions.OfflineCacheTolerance = tolerance;
+        }
+    });
+}
+
+builder.Logging.Configure(options =>
+{
+    options.ActivityTrackingOptions = ActivityTrackingOptions.SpanId
+        | ActivityTrackingOptions.TraceId
+        | ActivityTrackingOptions.ParentId;
+});
+
+var host = builder.Build();
+
+await host.RunAsync();
+
+public partial class Program;

src/StellaOps.Scanner.Worker/StellaOps.Scanner.Worker.csproj

@@ -1,20 +1,22 @@
-<Project Sdk="Microsoft.NET.Sdk.Worker">
-  <PropertyGroup>
-    <TargetFramework>net10.0</TargetFramework>
-    <LangVersion>preview</LangVersion>
-    <Nullable>enable</Nullable>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
-  </PropertyGroup>
-  <ItemGroup>
-    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.12.0" />
-    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.12.0" />
-    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.12.0" />
-    <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.12.0" />
-    <PackageReference Include="OpenTelemetry.Instrumentation.Process" Version="1.12.0-beta.1" />
-  </ItemGroup>
+<Project Sdk="Microsoft.NET.Sdk.Worker">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <LangVersion>preview</LangVersion>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.12.0" />
+    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.12.0" />
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.12.0" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.12.0" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.Process" Version="1.12.0-beta.1" />
+  </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\StellaOps.Plugin\StellaOps.Plugin.csproj" />
     <ProjectReference Include="..\StellaOps.Authority\StellaOps.Auth.Client\StellaOps.Auth.Client.csproj" />
+    <ProjectReference Include="..\StellaOps.Scanner.Analyzers.OS\StellaOps.Scanner.Analyzers.OS.csproj" />
+    <ProjectReference Include="..\StellaOps.Scanner.EntryTrace\StellaOps.Scanner.EntryTrace.csproj" />
   </ItemGroup>
 </Project>

src/StellaOps.Scanner.Worker/TASKS.md

@@ -1,8 +1,9 @@
-# Scanner Worker Task Board
-
-| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
-|----|--------|----------|------------|-------------|---------------|
-| SCANNER-WORKER-09-201 | DONE (2025-10-19) | Scanner Worker Guild | SCANNER-CORE-09-501 | Worker host bootstrap with Authority auth, hosted services, and graceful shutdown semantics. | `Program.cs` binds `Scanner:Worker` options, registers delay scheduler, configures telemetry + Authority client, and enforces shutdown timeout. |
-| SCANNER-WORKER-09-202 | DONE (2025-10-19) | Scanner Worker Guild | SCANNER-WORKER-09-201, SCANNER-QUEUE-09-401 | Lease/heartbeat loop with retry+jitter, poison-job quarantine, structured logging. | `ScannerWorkerHostedService` + `LeaseHeartbeatService` manage concurrency, renewal margins, poison handling, and structured logs exercised by integration fixture. |
-| SCANNER-WORKER-09-203 | DONE (2025-10-19) | Scanner Worker Guild | SCANNER-WORKER-09-202, SCANNER-STORAGE-09-301 | Analyzer dispatch skeleton emitting deterministic stage progress and honoring cancellation tokens. | Deterministic stage list + `ScanProgressReporter`; `WorkerBasicScanScenario` validates ordering and cancellation propagation. |
+# Scanner Worker Task Board
+
+| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
+|----|--------|----------|------------|-------------|---------------|
+| SCANNER-WORKER-09-201 | DONE (2025-10-19) | Scanner Worker Guild | SCANNER-CORE-09-501 | Worker host bootstrap with Authority auth, hosted services, and graceful shutdown semantics. | `Program.cs` binds `Scanner:Worker` options, registers delay scheduler, configures telemetry + Authority client, and enforces shutdown timeout. |
+| SCANNER-WORKER-09-202 | DONE (2025-10-19) | Scanner Worker Guild | SCANNER-WORKER-09-201, SCANNER-QUEUE-09-401 | Lease/heartbeat loop with retry+jitter, poison-job quarantine, structured logging. | `ScannerWorkerHostedService` + `LeaseHeartbeatService` manage concurrency, renewal margins, poison handling, and structured logs exercised by integration fixture. |
+| SCANNER-WORKER-09-203 | DONE (2025-10-19) | Scanner Worker Guild | SCANNER-WORKER-09-202, SCANNER-STORAGE-09-301 | Analyzer dispatch skeleton emitting deterministic stage progress and honoring cancellation tokens. | Deterministic stage list + `ScanProgressReporter`; `WorkerBasicScanScenario` validates ordering and cancellation propagation. |
 | SCANNER-WORKER-09-204 | DONE (2025-10-19) | Scanner Worker Guild | SCANNER-WORKER-09-203 | Worker metrics (queue latency, stage duration, failure counts) with OpenTelemetry resource wiring. | `ScannerWorkerMetrics` records queue/job/stage metrics; integration test asserts analyzer stage histogram entries. |
+| SCANNER-WORKER-09-205 | DONE (2025-10-19) | Scanner Worker Guild | SCANNER-WORKER-09-202 | Harden heartbeat jitter so lease safety margin stays ≥3× and cover with regression tests. | `LeaseHeartbeatService` clamps jitter to safety window, validator enforces ≥3 safety factor, regression tests cover heartbeat scheduling and metrics. |