@crvouga/dev-fleet 0.0.0-stage → 0.1.0

package/cliproxy/compose.yaml

@@ -0,0 +1,90 @@
+name: cliproxy-fleet
+services:
+  proxy:
+    image: ${CLI_PROXY_IMAGE:?image must be pinned}
+    restart: unless-stopped
+    user: '${CLIPROXY_UID:-1000}:${CLIPROXY_GID:-1000}'
+    working_dir: /state
+    command: ['/CLIProxyAPI/CLIProxyAPI', '-config', '/state/config.yaml']
+    environment:
+      HOME: /state
+      TZ: UTC
+      MANAGEMENT_STATIC_PATH: /state/static
+    ports:
+      - '127.0.0.1:8317:8317'
+    volumes:
+      - ./state/runtime:/state
+      - ./scripts/container-health:/health:ro
+    read_only: true
+    tmpfs:
+      - /tmp:rw,noexec,nosuid,size=64m,mode=1777
+    cap_drop: [ALL]
+    security_opt: [no-new-privileges:true]
+    mem_limit: 2g
+    cpus: 2
+    pids_limit: 256
+    stop_grace_period: 45s
+    healthcheck:
+      test: ['CMD', '/health']
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 30s
+    logging:
+      driver: local
+      options:
+        max-size: '10m'
+        max-file: '3'
+  tailnet:
+    profiles: [portable-endpoint]
+    user: '${CLIPROXY_UID:-1000}:${CLIPROXY_GID:-1000}'
+    image: ${TAILSCALE_IMAGE:?image must be pinned}
+    restart: unless-stopped
+    entrypoint: ['/usr/local/bin/tailscaled']
+    command:
+      [
+        '--tun=userspace-networking',
+        '--state=/var/lib/tailscale/tailscaled.state',
+        '--socket=/tmp/tailscaled.sock',
+      ]
+    volumes:
+      - ./state/tailscale:/var/lib/tailscale
+    cap_drop: [ALL]
+    security_opt: [no-new-privileges:true]
+    mem_limit: 256m
+    cpus: 0.5
+    pids_limit: 128
+    logging:
+      driver: local
+      options:
+        max-size: '5m'
+        max-file: '2'
+  cloudflared:
+    profiles: [public-endpoint]
+    image: ${CLOUDFLARED_IMAGE:?image must be pinned}
+    user: '${CLIPROXY_UID:-1000}:${CLIPROXY_GID:-1000}'
+    restart: unless-stopped
+    command:
+      [
+        'tunnel',
+        '--no-autoupdate',
+        'run',
+        '--token-file',
+        '/run/secrets/tunnel-token',
+      ]
+    volumes:
+      - ./state/secrets/tunnel-token:/run/secrets/tunnel-token:ro
+    depends_on:
+      proxy:
+        condition: service_healthy
+    read_only: true
+    cap_drop: [ALL]
+    security_opt: [no-new-privileges:true]
+    mem_limit: 256m
+    cpus: 0.5
+    pids_limit: 128
+    logging:
+      driver: local
+      options:
+        max-size: '5m'
+        max-file: '2'

package/cliproxy/config.template.yaml

@@ -0,0 +1,70 @@
+config-version: 8
+server:
+  host: '0.0.0.0'
+  port: 8317
+  max-request-body-bytes: 33554432
+  trusted-proxies: []
+  discovery:
+    enabled: false
+management:
+  allow-remote: true
+  secret-key: REPLACE_MANAGEMENT_KEY
+  disable-control-panel: false
+  disable-auto-update-panel: true
+  panel-github-repository: https://github.com/router-for-me/Cli-Proxy-API-Management-Center
+access:
+  api-keys:
+    - REPLACE_CLIENT_KEY
+oauth:
+  auth-dir: /state/auths
+  # Fleet-owned (applied by `ops declared`): the Antigravity CLI sends its
+  # catalog ids; serve them from the Antigravity account's matching models.
+  model-alias:
+    antigravity:
+      - name: gemini-3.8-flash-high
+        alias: gemini-3.8-flash
+        fork: true
+      - name: gemini-3.1-flash-lite
+        alias: gemini-3.1-flash-lite-preview
+        fork: true
+routing:
+  # Fill first: use one account until its quota is exhausted (it then cools down), then the next.
+  # Sessions stay bound to their account while it is available; new sessions start on the first
+  # available account, so usage is not spread across accounts.
+  strategy: fill-first
+  session-affinity: true
+  retry:
+    request-retry: 2
+    # 0 tries every eligible credential, so exhausting several accounts still reaches the next one.
+    max-retry-credentials: 0
+    max-retry-interval: 30
+  cooldown:
+    disable-cooling: false
+    save-cooldown-status: true
+upstream:
+  claude:
+    # Fleet-owned (applied by `ops declared`): the proxy presents itself to
+    # Anthropic as this Claude Code version, and Anthropic refuses newer models
+    # to an older one. fleet-sync replaces the version with the `claude` pin in
+    # mise.toml on every run, so it follows the harness every node runs.
+    header-defaults:
+      user-agent: 'claude-cli/2.1.314 (external, cli)'
+      # T3 runs Claude Code under its own entrypoint label.
+      native-entrypoints: ['t3-code']
+# Legacy compatibility field intentionally retained: never switch model capability/cost.
+quota-exceeded:
+  switch-project: true
+  switch-preview-model: false
+observability:
+  logs:
+    debug: false
+    logging-to-file: false
+    request-log: false
+    logs-max-total-size-mb: 50
+    error-logs-max-files: 2
+  usage:
+    usage-statistics-enabled: true
+  pprof:
+    enable: false
+plugins:
+  enabled: false

package/cliproxy/docs/cloud-adoption.md

@@ -0,0 +1,16 @@
+# Cloud ownership and initial adoption
+
+The initial workstation setup created runtime/cloud state before this package existed. Its operational code is now maintained here; installed copies are generated from committed blobs. The one-off Tailscale API provisioning and Vault secret-writing helpers are retired and removed during first package installation. They must not return as parallel infrastructure controllers.
+
+Existing external resources are retained:
+
+- Tailscale Service `svc:ai-proxy`, endpoint `tcp:443`, stable MagicDNS origin `https://ai-proxy.tail0a1b2c.ts.net`.
+- Dedicated host tag `tag:ai-proxy` and optional client tag `tag:ai-client`, with owner/service approval and private access rules already in the tailnet. The original workstation identity/SSH/service route was preserved.
+- Existing production R2 bucket and prefix `cliproxy-fleet/restic`; bucket and credentials already belong to the OpenTofu platform.
+- Existing Vault `secret/personal/prd` fields `CLIPROXY_FLEET_RESTIC_PASSWORD`, `CLIPROXY_FLEET_CLIENT_API_KEY`, `CLIPROXY_FLEET_MANAGEMENT_KEY`, and operator-added `TAILSCALE_API_TOKEN`.
+
+The new Vault field names still require reconciliation into `packages/infra/tofu/modules/inventory/inventory.tf.json` and the **complete** OpenTofu `vault_inputs` map before a later Vault apply. Preserve their existing values and every unrelated field. Use the established `bun run vault:fix`/`vault:edit` adoption workflow and a reviewed saved plan; never seed secrets directly from this package. The Tailscale admin token is no longer consumed by the runtime package and is not mounted into containers.
+
+Before changing existing Tailscale cloud resources, adopt their identities and full policy through the platform's OpenTofu workflow. Do not replace the tailnet policy wholesale, recreate the Service/TailVIP, retag the workstation, or delete existing grants. Local `tailscale up` authorization and `serve` advertisement of an already defined resource are runtime operations; policy, tag ownership and Service definitions are infrastructure.
+
+These are outstanding cloud-IaC reconciliation items, not hidden local scripts. Provider/authentication state, source-manifest metadata and the dedicated node identity are encrypted in R2 backups; recovery credentials are independently in Vault. Do not put live state, secrets, provider tokens or infrastructure plans into Git.

package/cliproxy/docs/deployment.svg

@@ -0,0 +1,109 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1440" height="1120" viewBox="0 0 1440 1120" role="img" aria-labelledby="title description">
+  <title id="title">CLIProxyAPI deployment and integrations</title>
+  <desc id="description">Clients reach Cloudflare HTTPS with API keys. An outbound tunnel connects to cloudflared and CLIProxyAPI on the workstation. CLIProxyAPI calls the upstream AI provider. GitHub supplies tracked runtime code and OpenTofu cloud configuration. Vault supplies credentials; Restic sends encrypted backups to R2. A private Tailscale endpoint also reaches the proxy.</desc>
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="#667897"/></marker>
+    <marker id="blue-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="#2563eb"/></marker>
+    <style>
+      text { font-family: Inter, Arial, sans-serif; fill: #15243b; }
+      .heading { font-size: 32px; font-weight: 700; }
+      .subtitle { font-size: 16px; fill: #53637b; }
+      .label { font-size: 18px; font-weight: 700; }
+      .detail { font-size: 15px; fill: #53637b; }
+      .edge-label { font-size: 14px; fill: #53637b; }
+      .box { fill: white; stroke: #ccd7e6; stroke-width: 1.5; }
+      .traffic { fill: none; stroke: #2563eb; stroke-width: 3; marker-end: url(#blue-arrow); }
+      .control { fill: none; stroke: #667897; stroke-width: 2; stroke-dasharray: 7 6; marker-end: url(#arrow); }
+      .storage { fill: none; stroke: #667897; stroke-width: 2; marker-end: url(#arrow); }
+    </style>
+  </defs>
+  <rect width="1440" height="1120" rx="24" fill="#f5f8fc"/>
+  <text x="54" y="65" class="heading">CLIProxyAPI · deployment &amp; integrations</text>
+  <text x="54" y="96" class="subtitle">Stable public HTTPS · API-key authentication · GitHub-owned configuration</text>
+
+  <rect x="54" y="130" width="1332" height="104" rx="16" class="box"/>
+  <text x="80" y="164" class="label">YOUR CLIENTS</text>
+  <text x="80" y="196" class="detail">Codex CLI · Claude Code · OpenCode · other API clients</text>
+  <text x="900" y="164" class="label">MANAGEMENT DASHBOARD</text>
+  <text x="900" y="196" class="detail">Browser + separate management key</text>
+
+  <path d="M 720 234 V 290" class="traffic"/>
+  <text x="742" y="269" class="edge-label">HTTPS + client API key / management key</text>
+  <rect x="395" y="290" width="650" height="110" rx="16" fill="#eaf1ff" stroke="#9dbaf5" stroke-width="1.5"/>
+  <text x="720" y="328" text-anchor="middle" class="label">cli-proxy.example.com</text>
+  <text x="720" y="359" text-anchor="middle" class="detail">Cloudflare DNS + HTTPS + managed Tunnel</text>
+  <text x="720" y="383" text-anchor="middle" class="detail">API: /v1 · Dashboard: /management.html</text>
+
+  <rect x="330" y="462" width="770" height="392" rx="20" fill="#edf5ff" stroke="#9dbaf5" stroke-width="1.5"/>
+  <text x="356" y="499" class="label">THIS WORKSTATION</text>
+  <text x="356" y="523" class="detail">systemd + Docker Compose · pinned Git code</text>
+
+  <path d="M 720 400 V 560" class="traffic"/>
+  <rect x="550" y="419" width="340" height="27" rx="6" fill="#f5f8fc"/>
+  <text x="720" y="438" text-anchor="middle" class="edge-label">Encrypted tunnel · initiated outbound by host</text>
+  <rect x="550" y="560" width="330" height="82" rx="13" class="box"/>
+  <text x="715" y="592" text-anchor="middle" class="label">cloudflared container</text>
+  <text x="715" y="619" text-anchor="middle" class="detail">Private token file · no added host port</text>
+  <path d="M 715 642 V 686" class="traffic"/>
+  <text x="735" y="669" class="edge-label">Docker network</text>
+  <rect x="550" y="686" width="330" height="85" rx="13" fill="#2563eb"/>
+  <text x="715" y="720" text-anchor="middle" style="fill:white;font-size:21px;font-weight:700">CLIProxyAPI</text>
+  <text x="715" y="748" text-anchor="middle" style="fill:#dbeafe;font-size:15px">Port 8317 · authentication + API routing</text>
+  <rect x="355" y="686" width="161" height="85" rx="13" class="box"/>
+  <text x="435" y="720" text-anchor="middle" class="label">Working cache</text>
+  <text x="435" y="746" text-anchor="middle" class="detail">OAuth + config</text>
+  <path d="M 550 728 H 516" class="storage" marker-start="url(#arrow)"/>
+  <text x="356" y="818" class="detail">Health monitoring · Vault renewal · cloud checkpoint every 15 minutes</text>
+
+  <rect x="1140" y="686" width="246" height="104" rx="15" class="box"/>
+  <text x="1263" y="719" text-anchor="middle" class="label">AI provider</text>
+  <text x="1263" y="746" text-anchor="middle" class="detail">Currently: Codex OAuth</text>
+  <text x="1263" y="771" text-anchor="middle" class="detail">Streaming + tool calls</text>
+  <path d="M 880 729 H 1140" class="traffic" marker-start="url(#blue-arrow)"/>
+  <text x="1008" y="714" text-anchor="middle" class="edge-label">Provider authentication</text>
+
+  <rect x="54" y="540" width="235" height="110" rx="15" class="box"/>
+  <text x="171" y="574" text-anchor="middle" class="label">Vault</text>
+  <text x="171" y="601" text-anchor="middle" class="detail">Tunnel, API + backup keys</text>
+  <text x="171" y="626" text-anchor="middle" class="detail">Current S3 credentials</text>
+  <path d="M 289 580 H 550" class="control"/>
+  <rect x="345" y="557" width="170" height="24" rx="5" fill="#edf5ff"/>
+  <text x="430" y="574" text-anchor="middle" class="edge-label">Token on startup</text>
+
+  <rect x="1140" y="540" width="246" height="110" rx="15" class="box"/>
+  <text x="1263" y="574" text-anchor="middle" class="label">Tailscale endpoint</text>
+  <text x="1263" y="601" text-anchor="middle" class="detail">Existing private alternative</text>
+  <text x="1263" y="626" text-anchor="middle" class="detail">ai-proxy.tail0a1b2c.ts.net</text>
+  <path d="M 1140 600 H 1048 V 704 H 880" class="storage"/>
+
+  <rect x="54" y="903" width="330" height="112" rx="15" class="box"/>
+  <text x="219" y="938" text-anchor="middle" class="label">GitHub · crvouga/dev-fleet</text>
+  <text x="219" y="967" text-anchor="middle" class="detail">Tracked runtime code + OpenTofu</text>
+  <text x="219" y="992" text-anchor="middle" class="detail">Reviewed main-branch CI deployment</text>
+  <path d="M 384 935 H 470 V 854" class="control"/>
+  <text x="488" y="900" class="edge-label">Pinned code install</text>
+  <path d="M 105 903 H 35 V 345 H 395" class="control"/>
+  <text x="122" y="330" class="edge-label">OpenTofu owns DNS + tunnel</text>
+  <path d="M 219 903 V 650" class="control"/>
+  <rect x="129" y="828" width="179" height="43" rx="6" fill="#f5f8fc"/>
+  <text x="219" y="847" text-anchor="middle" class="edge-label">OpenTofu owns</text>
+  <text x="219" y="865" text-anchor="middle" class="edge-label">credential delivery</text>
+
+  <rect x="680" y="903" width="220" height="112" rx="15" class="box"/>
+  <text x="790" y="938" text-anchor="middle" class="label">Restic</text>
+  <text x="790" y="967" text-anchor="middle" class="detail">15-minute checkpoints</text>
+  <text x="790" y="992" text-anchor="middle" class="detail">Runtime state + revision</text>
+  <path d="M 790 854 V 903" class="storage"/>
+  <rect x="1140" y="903" width="246" height="112" rx="15" class="box"/>
+  <text x="1263" y="938" text-anchor="middle" class="label">Cloudflare R2</text>
+  <text x="1263" y="967" text-anchor="middle" class="detail">Durable recovery source</text>
+  <text x="1263" y="992" text-anchor="middle" class="detail">cliproxy-fleet/restic</text>
+  <path d="M 900 959 H 1140" class="storage"/>
+  <text x="1020" y="941" text-anchor="middle" class="edge-label">S3-compatible API</text>
+
+  <path d="M 55 1065 H 107" class="traffic"/>
+  <text x="120" y="1070" class="detail">Inference traffic · responses return along the same path</text>
+  <path d="M 710 1065 H 762" class="control"/>
+  <text x="775" y="1070" class="detail">Configuration / credential delivery</text>
+  <text x="54" y="1100" class="detail">The public URL stays stable when the primary host moves. This workstation must remain online to serve requests.</text>
+</svg>

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.