@crvouga/dev-fleet 0.0.0-stage → 0.2.0

package/cliproxy/docs/health-workflow.example.yml

@@ -0,0 +1,185 @@
+name: CLI proxy health
+# One workflow, five entry points, deliberately cheap by default:
+#   every 15 min  readiness: free (no inference) + cloud checkpoint freshness
+#   hourly        light: 2 tiny requests per model (about 200 requests a day)
+#   03:41 nightly comprehensive suite (bounded by models.json budgets)
+#   pull request  contract: offline, no credentials, no inference
+#   manual        any profile, one model or one check, optional force-probe
+on:
+  schedule:
+    - cron: '7,22,37,52 * * * *'
+    - cron: '17 * * * *'
+    - cron: '41 3 * * *'
+  pull_request:
+    paths:
+      - cliproxy/**
+      - .github/workflows/cliproxy-health.yml
+  workflow_dispatch:
+    inputs:
+      profile:
+        description: readiness is free; light is the hourly check; nightly is comprehensive; manual adds wrong-key probes and fault simulations.
+        type: choice
+        default: light
+        options: [liveness, readiness, light, nightly, manual]
+      suite:
+        description: Which declared checks to run.
+        type: choice
+        default: all
+        options: [all, core, cursor]
+      model:
+        description: Optional single model id from cliproxy/models.json (partial runs never open or close the tracking issue).
+        type: string
+        default: ''
+      check:
+        description: Optional capability glob such as chat.tools or responses.* (cheap reproduction of one finding).
+        type: string
+        default: ''
+      max_requests:
+        description: Optional lower request budget for this run.
+        type: string
+        default: ''
+      force_probe:
+        description: Probe models even if they were rate limited recently (normally paused to protect quota).
+        type: boolean
+        default: false
+permissions:
+  contents: read
+concurrency:
+  group: cliproxy-model-health-${{ github.event_name == 'pull_request' && format('pr-{0}', github.ref) || github.event_name == 'workflow_dispatch' && inputs.profile || github.event.schedule }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+env:
+  PROFILE: ${{ github.event_name == 'workflow_dispatch' && inputs.profile || github.event.schedule == '41 3 * * *' && 'nightly' || github.event.schedule == '17 * * * *' && 'light' || 'readiness' }}
+jobs:
+  contract:
+    # Pull requests: deterministic protocol, routing and report contracts. No credentials, no inference.
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Install PyYAML for the validate-config contract
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends python3-yaml
+      - name: Lint models.json and run the offline contract tests
+        run: |
+          python3 -B cliproxy/scripts/check.py
+          python3 -B -m unittest discover -s cliproxy/tests -p "test_model_*.py"
+      - name: Run the full declarative suite against the local emulator
+        run: |
+          set +e
+          python3 -B cliproxy/scripts/model_health.py model-suite --target mock --profile manual \
+            --fail-on degraded --output model-health-report --seed 1 > /dev/null
+          code=$?
+          if [ -f model-health-report/model-health.md ]; then cat model-health-report/model-health.md >> "$GITHUB_STEP_SUMMARY"; fi
+          exit $code
+      - name: Keep structured report
+        if: ${{ always() && hashFiles('model-health-report/model-health.json') != '' }}
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: model-health-contract-${{ github.run_id }}
+          path: model-health-report
+          retention-days: 14
+  health:
+    if: github.event_name != 'pull_request' && github.repository == 'crvouga/dev-fleet' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    permissions:
+      contents: read
+      id-token: write
+      issues: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Install read-only backup client
+        if: env.PROFILE == 'readiness'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends restic
+      - name: Read-only Vault login using GitHub OIDC
+        uses: hashicorp/vault-action@892a26828f195e65540a40b4768ae4571f51ebfc # v4.0.0
+        with:
+          url: https://vault.example.com
+          method: jwt
+          path: jwt
+          role: github-actions
+          jwtGithubAudience: https://vault.example.com
+          exportToken: true
+      - name: Verify endpoint and cloud recovery freshness
+        if: env.PROFILE == 'readiness'
+        run: python3 -B cliproxy/scripts/external-health.py
+      - name: Restore last-success and rate-limit state
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: model-health-state.json
+          key: cliproxy-model-health-state-${{ github.run_id }}
+          restore-keys: cliproxy-model-health-state-
+      - name: Validate every required model
+        # Bounded spend: the profile's request/token budget, concurrency and timeouts come from models.json;
+        # inference is never retried; a model rate limited recently is not probed again until its pause ends.
+        # The client key is read in-process from Vault and never printed.
+        if: ${{ !cancelled() }}
+        env:
+          MODEL: ${{ inputs.model }}
+          CHECK: ${{ inputs.check }}
+          MAX_REQUESTS: ${{ inputs.max_requests }}
+          SUITE: ${{ inputs.suite || 'all' }}
+          FORCE_PROBE: ${{ inputs.force_probe }}
+        run: |
+          command=model-health
+          fail_on=unhealthy
+          case "$PROFILE" in nightly | manual) command=model-suite; fail_on=degraded ;; esac
+          args=(--profile "$PROFILE" --suite "$SUITE" --fail-on "$fail_on"
+            --output model-health-report --state model-health-state.json)
+          if [ -n "$MODEL" ]; then args+=(--model "$MODEL"); fi
+          if [ -n "$CHECK" ]; then args+=(--check "$CHECK"); fi
+          if [ -n "$MAX_REQUESTS" ]; then args+=(--max-requests "$MAX_REQUESTS"); fi
+          if [ "$FORCE_PROBE" = "true" ]; then args+=(--force-probe); fi
+          set +e
+          python3 -B cliproxy/scripts/model_health.py "$command" "${args[@]}" > /dev/null
+          code=$?
+          if [ -f model-health-report/agent-brief.md ]; then cat model-health-report/agent-brief.md >> "$GITHUB_STEP_SUMMARY"; fi
+          if [ -f model-health-report/model-health.md ]; then cat model-health-report/model-health.md >> "$GITHUB_STEP_SUMMARY"; fi
+          exit $code
+      - name: Save last-success and rate-limit state
+        if: ${{ always() && hashFiles('model-health-state.json') != '' }}
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: model-health-state.json
+          key: cliproxy-model-health-state-${{ github.run_id }}
+      - name: Keep structured report
+        if: ${{ always() && hashFiles('model-health-report/model-health.json') != '' }}
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: model-health-${{ env.PROFILE }}-${{ github.run_id }}
+          path: model-health-report
+          retention-days: 30
+      - name: Track findings in one issue per scope
+        # Opens or updates a single tracking issue when the findings change, and closes it when a full
+        # run is healthy. The body is the redacted agent brief: structure and numbers, no prompts or keys.
+        if: ${{ always() && hashFiles('model-health-report/model-health.json') != '' && inputs.model == '' && inputs.check == '' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          scope=live
+          case "$PROFILE" in nightly | manual) scope=nightly ;; esac
+          title="[ops] CLI proxy model health ($scope)"
+          report=model-health-report/model-health.json
+          status=$(jq -r .summary.status "$report")
+          fingerprint=$(jq -r .summary.findings.fingerprint "$report")
+          number=$(gh issue list --state open --search "\"$title\" in:title" --json number,title \
+            --jq "map(select(.title==\"$title\"))[0].number // empty")
+          if [ "$status" = unhealthy ] || [ "$status" = degraded ]; then
+            {
+              head -c 58000 model-health-report/agent-brief.md
+              printf '\n\nRun: %s (artifact model-health-%s-%s)\n<!-- fingerprint: %s -->\n' "$RUN_URL" "$PROFILE" "$GITHUB_RUN_ID" "$fingerprint"
+            } > model-health-report/issue.md
+            if [ -z "$number" ]; then
+              gh issue create --title "$title" --body-file model-health-report/issue.md
+            elif ! gh issue view "$number" --json body --jq .body | grep -q "fingerprint: $fingerprint"; then
+              gh issue edit "$number" --body-file model-health-report/issue.md
+              gh issue comment "$number" --body "Findings changed: $RUN_URL"
+            fi
+          elif [ "$status" = healthy ] && [ -n "$number" ]; then
+            gh issue close "$number" --comment "Healthy again: $RUN_URL"
+          fi

package/cliproxy/docs/migration.md

@@ -0,0 +1,131 @@
+# Restore and migration
+
+Exactly one proxy instance runs, on the **manager** (`manager.id` in `fleet.json`). Workers are clients and never host it. Never activate duplicated OAuth or Tailscale identities concurrently. Source code comes from this package at a reviewed Git revision; secrets and state come from Vault and encrypted R2 snapshots.
+
+`INSTALL_ROOT` below is `~/Library/Application Support/cliproxy-fleet` on the manager and `/opt/cliproxy-fleet` on the legacy Linux host. Run every `devfleet cliproxy …` command from a repository checkout on the host named in the step.
+
+## Move the proxy from a Linux worker to the manager
+
+Today the proxy still runs on the worker `worker-one` (legacy systemd, `/opt/cliproxy-fleet`). This one-time, operator-approved move fences that host and recovers its latest checkpoint on the manager `manager-mac`. The acknowledgement flags below are operator fencing, not a distributed lock. Plan a short outage: workers have no proxy between the source stop and the manager health check.
+
+### 1. Prepare the manager (no outage)
+
+On the manager, logged in, on AC power, with Docker Desktop running (enable **Start Docker Desktop when you sign in**):
+
+```bash
+cliproxy/scripts/install-dependencies
+devfleet cliproxy install --prepare-only --revision HEAD
+devfleet cliproxy vault-login
+devfleet cliproxy recover
+devfleet cliproxy snapshots
+```
+
+`install-dependencies` builds the pinned tools directory (mise Python + hash-locked PyYAML, mise `restic`) that the LaunchAgents run with; it never uses sudo or Homebrew. `--prepare-only` creates the worktree and private directories without starting anything. `recover` reads the existing Restic password from Vault and confirms it; it never generates or writes cloud secrets. Do not run `initialize` before recovery.
+
+### 2. Fence the source (outage starts)
+
+On `worker-one`, stop scheduling, drain the dedicated Tailscale Service advertisement, stop and disable the stack, then take the final consistent checkpoint:
+
+```bash
+sudo systemctl disable --now cliproxy-backup.timer cliproxy-backup-check.timer cliproxy-gc.timer
+devfleet cliproxy drain
+devfleet cliproxy stop
+sudo systemctl disable cliproxy-fleet.service
+devfleet cliproxy backup
+devfleet cliproxy snapshots
+sudo systemctl disable --now cliproxy-monitor.timer cliproxy-vault-renew.timer
+```
+
+An already stopped stack remains stopped after backup. Record the **latest successful snapshot ID** from `/opt/cliproxy-fleet/state/status/backup-success.json`; do not choose an incomplete snapshot from a failed backup. Confirm the fence before continuing:
+
+```bash
+systemctl is-active cliproxy-fleet.service   # inactive
+systemctl is-enabled cliproxy-fleet.service  # disabled
+python3 -B cliproxy/scripts/fleet_sync.py --definition fleet.json \
+  --node worker-one --revision "$(git rev-parse HEAD)"   # PROXY_DECOMMISSION_PENDING, not PROXY_DUPLICATE_OWNER
+```
+
+Keep the source powered off or fenced until the move is verified or rolled back.
+
+### 3. Recover and start on the manager
+
+On the manager:
+
+```bash
+devfleet cliproxy restore-cache --previous-node-stopped
+devfleet cliproxy install --revision HEAD
+devfleet cliproxy audit
+devfleet cliproxy health
+devfleet cliproxy activate
+devfleet cliproxy public-endpoint verify
+python3 -B cliproxy/tests/live.py --endpoint https://cli-proxy.example.com --codex
+devfleet cliproxy backup
+```
+
+`restore-cache` downloads the latest modern checkpoint, validates it and populates the empty cache without starting services. `install` (never sudo on macOS) regenerates secret caches from Vault, records the user's UID/GID for Compose, links and loads the `dev.devfleet.cliproxy-*` LaunchAgents in `gui/$UID`, and starts the recovered stack; it refuses missing runtime config and stops with `DOCKER_DESKTOP_NOT_RUNNING` if Docker Desktop is down. `audit` must show clean provenance and loaded agents. `activate` resumes the existing `svc:ai-proxy` advertisement from the restored dedicated identity. A restored `state/public-endpoint-enabled` marker starts the public connector automatically; otherwise run `devfleet cliproxy public-endpoint enable` first.
+
+Then confirm the fleet view and clients:
+
+```bash
+python3 -B cliproxy/scripts/fleet_sync.py --definition fleet.json \
+  --node manager-mac --revision "$(git rev-parse HEAD)"   # ok: true, role manager, backend launchd
+```
+
+From each worker, run the client bootstrap's `--validate` and an actual client/tool request through `https://cli-proxy.example.com` and `https://ai-proxy.tail0a1b2c.ts.net`. Remove temporary plaintext restore copies after verification.
+
+### 4. Decommission the source
+
+After the manager has run cleanly through several scheduled backups, retire the old host's installation. It contains private provider/Tailscale state, so remove it rather than leaving it enabled:
+
+```bash
+sudo docker compose --project-directory /opt/cliproxy-fleet \
+  --profile portable-endpoint --profile public-endpoint down
+sudo rm /etc/systemd/system/cliproxy-*.service /etc/systemd/system/cliproxy-*.timer
+sudo systemctl daemon-reload
+sudo rm -rf /opt/cliproxy-fleet
+git worktree prune
+```
+
+`fleet_sync.py --node worker-one` then reports `PROXY_CLIENT_ROLE`. Fleet-sync never performs these steps itself.
+
+### Rollback a failed move
+
+1. On the manager, stop and unload it, keeping any newer state:
+
+   ```bash
+   devfleet cliproxy drain
+   devfleet cliproxy stop
+   devfleet cliproxy backup   # only if the manager refreshed credentials or changed config
+   for label in fleet monitor vault-renew backup backup-check gc; do
+     launchctl bootout "gui/$(id -u)/dev.devfleet.cliproxy-$label"
+     launchctl disable "gui/$(id -u)/dev.devfleet.cliproxy-$label"
+   done
+   ```
+
+   Move `INSTALL_ROOT/state/runtime`, `state/tailscale` and `state/endpoint.json` into a private directory under `INSTALL_ROOT/recovery/`. With the runtime cache gone, `fleet-sync` reports `PROXY_RECOVERY_REQUIRED` and can never restart the manager copy.
+
+2. On the source, if the manager took a newer backup, move the source's `state/runtime`, `state/tailscale` and `state/endpoint.json` aside the same way and run `devfleet cliproxy restore-cache --previous-node-stopped`; otherwise keep the original source state (old OAuth refresh tokens may be invalid after the manager refreshed them).
+3. Restart the source with `sudo systemctl enable cliproxy-fleet.service`, `devfleet cliproxy install --revision REV` (the revision it ran before), `devfleet cliproxy activate`, then re-enable its timers with `sudo systemctl enable --now cliproxy-monitor.timer cliproxy-vault-renew.timer cliproxy-backup.timer cliproxy-backup-check.timer cliproxy-gc.timer`.
+4. Verify the stable endpoints from fleet clients. Until the move is retried, fleet-sync reports `PROXY_DUPLICATE_OWNER` on the source; that is expected and is never auto-remediated.
+
+## One-command offline recovery
+
+On a host with the tracked package installed and a valid private Vault token, `devfleet cliproxy recover-node NEW_DIRECTORY` builds a complete new cache using fresh Vault secrets and a verified R2 checkpoint. Supply `--vault-token-file FILE` to use an explicit existing login. It refuses existing destinations and never changes or stops the running stack. This is also a safe recovery rehearsal while the manager remains online: the new identity files are never activated. Remove rehearsal caches after inspection, since they contain private credentials.
+
+On a replacement manager without installed tooling, invoke `python3 -B cliproxy/scripts/recover_node.py "$HOME/Library/Application Support/cliproxy-fleet" --vault-token-file FILE` from a full Git clone after `install-dependencies` passes. The destination must not yet exist. After explicitly fencing the old host, `devfleet cliproxy install --revision REV` installs tracked code and activates the recovered cache. This route replaces the separate prepare/login/password/restore steps above when an existing Vault token is already available. It does not obtain a new machine identity or bypass old-node fencing.
+
+## Recovery details
+
+Recovery uses the current trusted Git checkout, validates decrypted data, and preserves the new Vault login and independently recovered Restic password. It never executes backed-up code. To reproduce the original software version, read the recovered checkpoint's `INSTALLATION.json` in an offline restore first and choose that reviewed Git revision instead of HEAD.
+
+`restore-cache` intentionally refuses an existing `runtime`, `tailscale` or endpoint cache. An existing repository pin must match the restored destination. For recovery on the same host, stop the service/agents and move these cache entries to a private rollback directory first. Never move `state/status/operation.lock` while an operation is active. An interrupted recovery leaves `state/recovery-incomplete`; inspect/remove the partial cache before retrying. Keep `state/secrets` (new Vault login/password) and the lock directory intact.
+
+For offline inspection or historical recovery, use `devfleet cliproxy restore SNAPSHOT_ID EMPTY_DIRECTORY`, then `python3 -B INSTALL_ROOT/scripts/restore-verify EMPTY_DIRECTORY`. Modern checkpoints are located automatically despite different source paths. Old snapshots without `CHECKPOINT.json` require the original explicit restored deployment path and manual state recovery. No automatic fallback to an older snapshot occurs when validation fails.
+
+The existing Tailscale Service remains in the cloud. Reuse the restored dedicated identity only while the original is stopped. If a drained identity requires re-advertising, use the pinned Tailscale CLI's `serve advertise` command for `svc:ai-proxy`, then inspect `serve status`. Do not change the manager's ordinary Tailscale identity or assume hostnames transfer. A new tagged identity/service definition requires the platform's OpenTofu-managed enrollment/approval workflow; no cloud provisioning helper exists in this package.
+
+A normal code/image rollback uses `devfleet cliproxy install --rollback`. That restores a recorded Git revision, not application data. For incompatible state migrations, restore a matching pre-upgrade snapshot while stopped.
+
+## Public hostname cutover
+
+The public DNS/tunnel resources remain owned by OpenTofu. A restored `state/public-endpoint-enabled` marker makes service startup fetch the current isolated tunnel credential from Vault and start the connector automatically. The tunnel token itself is excluded from snapshots. If the marker is absent, run `devfleet cliproxy public-endpoint enable` after restoring and stopping the old host. Verify with `devfleet cliproxy public-endpoint verify` and `tests/live.py --endpoint https://cli-proxy.example.com --codex`. Client API and management keys do not change; keep the old host stopped during recovery.

package/cliproxy/docs/model-health-report.schema.json

@@ -0,0 +1,364 @@
+{
+  "$comment": "Subset of JSON Schema checked by scripts/modelhealth/schema.py in tests/test_model_agent_report.py. Report format: cliproxy-model-health/1.",
+  "type": "object",
+  "required": [
+    "schema",
+    "generated_at",
+    "profile",
+    "suite",
+    "target",
+    "seed",
+    "levels",
+    "models",
+    "simulations",
+    "summary",
+    "findings",
+    "routing",
+    "cursor"
+  ],
+  "properties": {
+    "schema": {
+      "type": "string",
+      "const": "cliproxy-model-health/1"
+    },
+    "generated_at": {
+      "type": "string"
+    },
+    "profile": {
+      "type": "string",
+      "enum": ["liveness", "readiness", "light", "nightly", "manual"]
+    },
+    "suite": {
+      "type": "string",
+      "enum": ["core", "cursor", "all"]
+    },
+    "target": {
+      "type": "object",
+      "required": ["kind", "base_url"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": ["live", "mock"]
+        },
+        "base_url": {
+          "type": "string"
+        }
+      }
+    },
+    "seed": {
+      "type": "integer"
+    },
+    "levels": {
+      "type": "object",
+      "required": ["liveness"],
+      "properties": {
+        "liveness": {
+          "type": "object",
+          "required": ["status", "category", "details"],
+          "properties": {
+            "status": {
+              "type": "string",
+              "enum": ["healthy", "degraded", "unhealthy", "unknown"]
+            },
+            "category": {
+              "type": ["string", "null"]
+            },
+            "details": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "readiness": {
+          "type": "object",
+          "required": ["status", "category", "details"],
+          "properties": {
+            "status": {
+              "type": "string",
+              "enum": ["healthy", "degraded", "unhealthy", "unknown"]
+            },
+            "category": {
+              "type": ["string", "null"]
+            },
+            "details": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "models": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "provider",
+          "status",
+          "reasons",
+          "coverage",
+          "capabilities",
+          "checks",
+          "metrics",
+          "rate_limited",
+          "paused",
+          "last_success"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "provider": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["healthy", "degraded", "unhealthy", "unknown"]
+          },
+          "reasons": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "coverage": {
+            "type": "object",
+            "required": ["capabilities", "exercised", "by_result"]
+          },
+          "capabilities": {
+            "type": "object"
+          },
+          "checks": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "id",
+                "capability",
+                "status",
+                "category",
+                "severity",
+                "endpoint",
+                "details",
+                "duration_ms"
+              ],
+              "properties": {
+                "status": {
+                  "type": "string",
+                  "enum": ["pass", "fail", "untested"]
+                },
+                "severity": {
+                  "type": "string",
+                  "enum": ["critical", "major", "minor"]
+                }
+              }
+            }
+          },
+          "metrics": {
+            "type": "object",
+            "required": [
+              "requests",
+              "availability",
+              "success_rate",
+              "ttft_ms",
+              "latency_ms",
+              "streaming_completion_rate",
+              "tool_call_success_rate",
+              "error_categories",
+              "upstream_failures",
+              "resolved_models"
+            ]
+          },
+          "rate_limited": {
+            "type": "boolean"
+          },
+          "paused": {
+            "type": "boolean"
+          },
+          "last_success": {
+            "type": "object"
+          },
+          "rate_limit_detail": {
+            "type": ["string", "null"]
+          }
+        }
+      }
+    },
+    "simulations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "capability", "status", "evidence", "details"],
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": ["pass", "fail"]
+          },
+          "evidence": {
+            "type": "string",
+            "const": "simulated"
+          }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": [
+        "status",
+        "levels",
+        "models",
+        "rate_limited",
+        "simulation_failures",
+        "findings"
+      ],
+      "properties": {
+        "rate_limited": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "status": {
+          "type": "string",
+          "enum": ["healthy", "degraded", "unhealthy", "unknown"]
+        },
+        "findings": {
+          "type": "object",
+          "required": ["total", "operator", "agent", "fingerprint"],
+          "properties": {
+            "total": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "operator": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "agent": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "fingerprint": {
+              "type": "string",
+              "minLength": 8
+            }
+          }
+        }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "status",
+          "severity",
+          "category",
+          "model",
+          "check",
+          "endpoint",
+          "summary",
+          "owner",
+          "resolver",
+          "agent_fixable",
+          "evidence",
+          "reproduce",
+          "fix_hints"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 3
+          },
+          "status": {
+            "type": "string",
+            "enum": ["fail", "paused", "untested"]
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["critical", "major", "minor", "info"]
+          },
+          "category": {
+            "type": "string"
+          },
+          "model": {
+            "type": ["string", "null"]
+          },
+          "check": {
+            "type": ["string", "null"]
+          },
+          "endpoint": {
+            "type": ["string", "null"]
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1
+          },
+          "owner": {
+            "type": "string"
+          },
+          "resolver": {
+            "type": "string",
+            "enum": ["operator", "agent"]
+          },
+          "agent_fixable": {
+            "type": "boolean"
+          },
+          "evidence": {
+            "type": "object",
+            "required": ["details", "trace"],
+            "properties": {
+              "details": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "trace": {
+                "type": "array",
+                "items": {
+                  "type": "object"
+                }
+              }
+            }
+          },
+          "reproduce": {
+            "type": "string",
+            "minLength": 10
+          },
+          "fix_hints": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "routing": {
+      "type": "object",
+      "required": ["declared", "live_verified"],
+      "properties": {
+        "live_verified": {
+          "type": "boolean"
+        }
+      }
+    },
+    "cursor": {
+      "type": "object",
+      "required": ["application_verified"],
+      "properties": {
+        "application_verified": {
+          "type": "boolean",
+          "const": false
+        }
+      }
+    }
+  }
+}