feat: improve local run reliability and coverage

Add agent readiness probing, interrupted-run recovery, stable finding review keys, expanded dashboard review controls, local packaging assets, and usage-focused integration coverage.

Author: matthiasmatt

.github/workflows/ci.yml

@@ -30,3 +30,5 @@ jobs:
       - name: Test
         run: cargo test
 
+      - name: Packaging Smoke
+        run: scripts/check-packaging.sh

.github/workflows/release.yml

@@ -46,6 +46,9 @@ jobs:
           cp "target/release/${{ matrix.binary }}" "dist/vuln-daemon-${{ matrix.name }}"
           chmod +x "dist/vuln-daemon-${{ matrix.name }}"
           tar -C dist -czf "dist/vuln-daemon-${{ matrix.name }}.tar.gz" "vuln-daemon-${{ matrix.name }}"
+          if [[ "${{ matrix.os }}" == macos-* ]]; then
+            ./scripts/package-macos-app.sh "target/release/${{ matrix.binary }}" dist "Vulnerability Daemon-${{ matrix.name }}.app"
+          fi
 
       - name: Upload artifact
         uses: actions/upload-artifact@v4
@@ -67,4 +70,3 @@ jobs:
         uses: softprops/action-gh-release@v2
         with:
           files: dist/**/*.tar.gz
-

README.md

@@ -22,6 +22,7 @@ brand mark, and the top-right review queue button:
 - Rotates across configured targets.
 - Uses local agent CLIs: `codex`, `claude`, or `cursor-agent`.
 - Randomizes agents when `agent` is set to `random`.
+- Probes agent readiness and excludes non-ready agents from random selection.
 - Stores markdown reports, normalized findings, raw logs, run metadata, and SARIF.
 - Tracks critical review state: `new`, `reviewed`, `accepted`, `false_positive`, `fixed`.
 - Serves a local dashboard and JSON API on `127.0.0.1`.
@@ -51,8 +52,10 @@ cargo install --path .
 
 During development, use `cargo run --` in place of `vuln-daemon`.
 
-This is still a source install. Packaged `.app`, Homebrew, and signed release
-binaries are planned so users do not need Rust installed.
+Release automation builds platform tarballs, and macOS release jobs also produce
+a `.app` bundle. A Homebrew formula template lives at
+[packaging/homebrew/vulnerability-daemon.rb.template](./packaging/homebrew/vulnerability-daemon.rb.template).
+Signed release binaries are still planned.
 
 ## Quick Start
 
@@ -135,6 +138,12 @@ Reparse existing reports after upgrading parser logic:
 vuln-daemon reindex --config ./vuln-daemon.config.json
 ```
 
+Check local agent readiness and config posture:
+
+```bash
+vuln-daemon doctor --config ./vuln-daemon.config.json
+```
+
 ## Config
 
 See [config.example.json](./config.example.json).
@@ -152,7 +161,7 @@ Important fields:
 - `targets[].prompt_pack`: one of `generic`, `webapp`, `backend`, `smart-contract`, or `chain`.
 
 `agent: "random"` chooses one installed agent from `codex`, `claude`, and
-`cursor-agent`.
+`cursor-agent` after a non-interactive readiness probe succeeds.
 
 Set `model` only when you want to force a provider-specific model flag. Leave it
 as `null` to let each local agent use its own default model.
@@ -173,8 +182,11 @@ The daemon binds only to `127.0.0.1`.
 - `GET /api/runs/<run_id>/report`
 - `GET /api/findings`
 - `GET /api/sarif`
+- `GET /api/agent-health`
+- `GET /api/config`
 - `POST /api/run`
 - `POST /api/cancel`
+- `POST /api/open-config`
 - `POST /api/findings/<finding_id>/review`
 
 Review request body:
@@ -263,5 +275,5 @@ private or sensitive repositories.
 - redacted public mode
 - per-project report retention policies
 - signed run metadata
-- direct GitHub/GitLab issue creation
+- local-first GitHub/GitLab handoff that makes network export explicit
 - prompt-pack marketplace

docs/product-v0.2.md

@@ -0,0 +1,51 @@
+# Product Plan v0.2
+
+## Positioning
+
+Vulnerability Daemon is a local operator tool for protocol team leads who want
+recurring AI-assisted security review over local protocol repositories.
+
+The product metric is accepted findings: a run is useful when it produces
+findings the team accepts as worth fixing, documenting, or explicitly rejecting.
+
+## Policy Decisions
+
+- Primary user: protocol team lead.
+- Agent policy: random among ready local agents by default; configurable to a
+  specific agent.
+- Confidence policy: prefer `confirmed_by_code`; strong suspicious leads are
+  allowed only when labelled `hypothesis`.
+- Privacy policy: strict local dashboard and artifact storage. External
+  integrations stay opt-in and off by default.
+- Distribution priority: macOS app bundle and Homebrew formula.
+
+## v0.2 Scope
+
+1. Run trust
+   - Probe local agents before use.
+   - Exclude non-ready agents from random selection.
+   - Recover long-stale `running` run metadata as `interrupted`.
+   - Keep the HTTP dashboard bound to `127.0.0.1`.
+
+2. Triage trust
+   - Add stable finding fingerprints per target.
+   - Preserve review state across reruns when the same finding reappears.
+   - Track accepted findings in the dashboard.
+   - Review all severities, not only criticals.
+
+3. Local operations
+   - Surface config path and agent health in the dashboard.
+   - Keep source, reports, reviews, and issue drafts on local disk by default.
+
+4. Distribution
+   - Produce a macOS `.app` bundle from release builds.
+   - Maintain a Homebrew formula template for tap publication.
+
+## Deferred
+
+- Hosted storage or hosted scheduling.
+- Multi-user auth.
+- Public redacted dashboard mode.
+- Direct GitHub/GitLab issue creation that sends vulnerability details off the
+  machine.
+- Prompt-pack marketplace.

packaging/homebrew/vulnerability-daemon.rb.template

@@ -0,0 +1,24 @@
+class VulnerabilityDaemon < Formula
+  desc "Local-first AI vulnerability research daemon for recurring audits"
+  homepage "https://github.com/NibiruChain/vulnerability-daemon"
+  url "https://github.com/NibiruChain/vulnerability-daemon/archive/refs/tags/vVERSION.tar.gz"
+  sha256 "SHA256"
+  license "MIT"
+
+  depends_on "rust" => :build
+
+  def install
+    system "cargo", "install", "--locked", "--path", ".", "--root", prefix
+  end
+
+  service do
+    run [opt_bin/"vuln-daemon", "serve", "--config", etc/"vulnerability-daemon/config.json"]
+    keep_alive true
+    log_path var/"log/vulnerability-daemon.stdout.log"
+    error_log_path var/"log/vulnerability-daemon.stderr.log"
+  end
+
+  test do
+    assert_match "Local-first AI vulnerability research daemon", shell_output("#{bin}/vuln-daemon --help")
+  end
+end

scripts/check-packaging.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+binary="${1:-target/debug/vuln-daemon}"
+
+if [[ ! -x "$binary" ]]; then
+  cargo build
+fi
+
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "$tmpdir"' EXIT
+
+bash -n scripts/package-macos-app.sh
+artifact="$(scripts/package-macos-app.sh "$binary" "$tmpdir" "Vulnerability Daemon-smoke.app")"
+
+test -f "$artifact"
+tar -tzf "$artifact" | grep -F "Vulnerability Daemon-smoke.app/Contents/Info.plist" >/dev/null
+tar -tzf "$artifact" | grep -F "Vulnerability Daemon-smoke.app/Contents/MacOS/vuln-daemon" >/dev/null
+tar -tzf "$artifact" | grep -F "Vulnerability Daemon-smoke.app/Contents/Resources/vulnerability-daemon-icon.svg" >/dev/null
+
+formula="packaging/homebrew/vulnerability-daemon.rb.template"
+grep -F "class VulnerabilityDaemon < Formula" "$formula" >/dev/null
+grep -F "service do" "$formula" >/dev/null
+grep -F "test do" "$formula" >/dev/null
+
+if command -v ruby >/dev/null 2>&1; then
+  ruby -c "$formula" >/dev/null
+fi
+
+echo "Packaging smoke checks passed"

scripts/package-macos-app.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+binary="${1:-target/release/vuln-daemon}"
+dist_dir="${2:-dist}"
+app_name="${3:-Vulnerability Daemon.app}"
+
+if [[ ! -x "$binary" ]]; then
+  echo "binary is not executable: $binary" >&2
+  exit 1
+fi
+
+app_dir="$dist_dir/$app_name"
+contents_dir="$app_dir/Contents"
+macos_dir="$contents_dir/MacOS"
+resources_dir="$contents_dir/Resources"
+
+rm -rf "$app_dir"
+mkdir -p "$macos_dir" "$resources_dir"
+
+cp "$binary" "$macos_dir/vuln-daemon"
+chmod +x "$macos_dir/vuln-daemon"
+cp "docs/assets/vulnerability-daemon-icon.svg" "$resources_dir/vulnerability-daemon-icon.svg"
+
+cat > "$contents_dir/Info.plist" <<'PLIST'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleDevelopmentRegion</key>
+  <string>en</string>
+  <key>CFBundleExecutable</key>
+  <string>vuln-daemon</string>
+  <key>CFBundleIdentifier</key>
+  <string>com.vulnerability-daemon.app</string>
+  <key>CFBundleInfoDictionaryVersion</key>
+  <string>6.0</string>
+  <key>CFBundleName</key>
+  <string>Vulnerability Daemon</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>CFBundleShortVersionString</key>
+  <string>0.1.0</string>
+  <key>CFBundleVersion</key>
+  <string>0.1.0</string>
+  <key>LSMinimumSystemVersion</key>
+  <string>12.0</string>
+  <key>LSUIElement</key>
+  <true/>
+  <key>NSHighResolutionCapable</key>
+  <true/>
+</dict>
+</plist>
+PLIST
+
+tar -C "$dist_dir" -czf "$dist_dir/vulnerability-daemon-macos-app.tar.gz" "$app_name"
+echo "$dist_dir/vulnerability-daemon-macos-app.tar.gz"