deps: luxfi/consensus v1.36.2 -> v1.36.3 — the v1.36.2 tag was re-pushed

Cold builds fail sumdb verification against the moved tag (downloaded
eKzasq4O... vs sealed IbeWQF1w...). v1.36.3 is the immutable successor;
never re-tag a published version.

.github/workflows/cicd.yml

@@ -0,0 +1,12 @@
+# ~7-line canonical caller — all real config lives in /hanzo.yml.
+# Test gate on OUR arc pool; release.yml owns the image + v* tags.
+name: CI/CD
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  cicd:
+    uses: hanzoai/ci/.github/workflows/build.yml@v1
+    secrets: inherit

.github/workflows/containment.yml

@@ -0,0 +1,133 @@
+name: containment
+
+# Guards the Stage-1 byzantine ceremony containment (clients/controlplane,
+# build tag `controlplane`). Its increment-1 crypto is stub/forgeable BY
+# DESIGN (SHA256-of-public-inputs commitments, symmetric-HMAC
+# proof-of-possession, seed-derived threshold shares — see
+# clients/controlplane/doc.go) and MUST NEVER reach a release/serve binary.
+# Three independent checks; any one failing blocks the PR:
+#
+#   1. grep (tag)    — no build/release invocation anywhere in the repo
+#      (Dockerfile, Makefile, shell scripts, any workflow) may pass a `-tags`
+#      value containing `controlplane` to go build/vet/run/install. The
+#      package's own `//go:build controlplane` tag declarations
+#      (clients/controlplane/*) are the thing being guarded, not a violation,
+#      and are excluded by path.
+#   2. grep (spoof)  — no build/release invocation may pass
+#      `-X testing.testBinary=1` (or any -ldflags containing it) to a REAL
+#      `go build`. That linker flag is what `go test` itself uses to make
+#      testing.Testing() report true (cmd/go/internal/load/test.go) — the
+#      runtime guard in containment.go trusts that signal, so this is the one
+#      concrete way to spoof it in a non-test binary. This grep is what turns
+#      "someone could type this" into "CI fails the PR that types it".
+#   3. build         — `go build ./...` (no tag — exactly what the Dockerfile
+#      and Makefile run) must not link clients/controlplane into any cmd/
+#      main, and `go build ./clients/controlplane/...` with no tag must match
+#      zero buildable packages (proves the tag still gates every file in it).
+#
+# Runtime belt-and-suspenders (defense in depth, not a substitute for the
+# above): clients/controlplane/containment.go fail-closed panics if its stub
+# crypto is ever constructed outside a go-test binary (testing.Testing()==
+# false) — see TestContainment_NonHarnessProcessRefuses in
+# containment_test.go. KNOWN RESIDUAL: testing.Testing() is a linker-set
+# string var (testing.testBinary), not cryptographically bound to "actually
+# is a test" — `-ldflags="-X testing.testBinary=1"` spoofs it in a real
+# binary. Check #2 above is the mitigation: it fails the PR that would ship
+# that flag. Closing the residual for real needs a signal `go build` cannot
+# produce at all (increment-2, tracked in doc.go) rather than one merely
+# absent by convention.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  controlplane-containment:
+    runs-on: [hanzo-build-linux-amd64]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: grep — no build/release path may set -tags controlplane, or spoof testing.Testing()
+        run: |
+          set -euo pipefail
+          hits=0
+
+          # NOTE: exclusions are plain substring matches on the path (not
+          # anchored to a leading "./") so this is robust across grep
+          # implementations that format recursive-search paths differently.
+          # char class includes `!` so a build-constraint negation form
+          # (`-tags '!x,controlplane'`) cannot slip the grep. (Belt only: the
+          # positive-proof step below is the syntax-agnostic guarantee — the
+          # package has zero untagged files, so importing it into serve code
+          # fails the untagged `go build ./...` regardless of any -tags syntax.)
+          if grep -RnE -- '-tags[= ]*["'"'"']?[!A-Za-z0-9_, ]*\bcontrolplane\b' \
+               --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=.claude --exclude-dir=vendor \
+               . 2>/dev/null \
+               | grep -v '\.git/' \
+               | grep -v 'clients/controlplane/' \
+               | grep -v '.github/workflows/containment.yml:'; then
+            echo "::error::found a build/release invocation passing -tags controlplane — clients/controlplane's stub crypto must never enter a release/serve binary (see clients/controlplane/doc.go)"
+            hits=1
+          fi
+
+          if grep -RnE -- 'testing\.testBinary' \
+               --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=.claude --exclude-dir=vendor \
+               . 2>/dev/null \
+               | grep -v '.github/workflows/containment.yml:'; then
+            echo "::error::found a reference to testing.testBinary outside the Go toolchain itself — this is the linker var that spoofs testing.Testing() in a real (non go-test) binary; the containment.go runtime guard trusts that signal, so setting it anywhere in a real build path defeats it (see doc.go)"
+            hits=1
+          fi
+
+          if [ "$hits" -ne 0 ]; then exit 1; fi
+          echo "OK: no build/release path sets -tags controlplane or spoofs testing.Testing()"
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: go env for private modules
+        env:
+          GH_PAT: ${{ secrets.GH_PAT }}
+        # GOPRIVATE names exactly the namespace that is private. github.com/hanzoai/*
+        # is: ai, account, commerce, orm, xorm, beego, csqlite and ~30 more are
+        # private repos, so they must resolve direct+authenticated and skip a sumdb
+        # that cannot see them. Everything else stays on the public proxy + checksum
+        # db, which is what makes a module hash immutable: zap-proto (all 55 repos)
+        # and luxfi (all 37 deps here) are public and proxy-served.
+        #
+        # This previously named zap-proto — public, and never the reason anything
+        # here was direct — and then set GOSUMDB=off to compensate for hanzoai/*
+        # being absent, which disabled checksum verification for EVERY module in the
+        # build, public ones included. Naming the private namespace is what the off
+        # switch was standing in for.
+        run: |
+          git config --global url."https://x-access-token:${GH_PAT}@github.com/".insteadOf "https://github.com/"
+          {
+            echo "GOPRIVATE=github.com/hanzoai/*"
+            echo "GOPROXY=https://proxy.golang.org,direct"
+          } >> "$GITHUB_ENV"
+
+      - name: positive proof — clients/controlplane is unreachable from the default build
+        run: |
+          set -euo pipefail
+
+          go build ./...
+
+          for m in $(go list ./cmd/...); do
+            if go list -deps "$m" | grep -qx 'github.com/hanzoai/cloud/clients/controlplane'; then
+              echo "::error::$m links clients/controlplane into a real binary — containment breach"
+              exit 1
+            fi
+          done
+
+          out="$(go build ./clients/controlplane/... 2>&1 || true)"
+          if ! printf '%s' "$out" | grep -q 'matched no packages'; then
+            echo "::error::clients/controlplane built successfully WITHOUT -tags controlplane (containment breach): $out"
+            exit 1
+          fi
+
+          echo "OK: containment holds — clients/controlplane has zero buildable files by default and is linked into no cmd/ binary"

.github/workflows/release.yml

@@ -67,8 +67,12 @@ jobs:
     # ARC ephemeral runners match jobs targeting the scale-set NAME as a label.
     runs-on: [hanzo-build-linux-amd64]
     outputs:
-      version: ${{ steps.ver.outputs.version }}
-      version_v: ${{ steps.ver.outputs.version_v }}
+      # The FINAL assigned version comes from the Tag step (atomic free-version
+      # assignment), NOT the compute step — under concurrency the compute value may
+      # have been superseded. notify-universe must roll the version that was actually
+      # tagged + whose image was actually retagged.
+      version: ${{ steps.tag.outputs.version }}
+      version_v: ${{ steps.tag.outputs.version_v }}
     steps:
       - name: Checkout (full history + all tags — the version floor is read from tags)
         uses: actions/checkout@v4
@@ -92,9 +96,9 @@ jobs:
           # an image (even from a run that died before tagging) is never reused.
           cont_max=""
           if command -v gh >/dev/null 2>&1; then
-            cont_max="$(GH_TOKEN="$GH_PAT" gh api --paginate \
-              '/orgs/hanzoai/packages/container/cloud/versions' \
-              --jq '.[].metadata.container.tags[]' 2>/dev/null \
+            cont_max="$(GH_TOKEN="$GH_PAT" gh api \
+              '/orgs/hanzoai/packages/container/cloud/versions?per_page=100' \
+              --jq '.[].metadata.container.tags[]?' 2>/dev/null \
               | sed 's/^v//' | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1 || true)"
           fi
 
@@ -106,12 +110,12 @@ jobs:
           major="${max%%.*}"; rest="${max#*.}"; minor="${rest%%.*}"; patch="${rest##*.}"
           version="${major}.${minor}.$((patch + 1))"
 
-          # Refuse to proceed if the number we intend to mint already exists as a
-          # git tag (a concurrent run beat us — the serialized lane makes this a
-          # can't-happen, but fail loud rather than clobber).
+          # This version is a STARTING HINT only. It labels the smoke-built image and
+          # seeds the OCI metadata; the FINAL version is assigned atomically in the Tag
+          # step (which recomputes + retries on collision), so a taken number here is
+          # NOT fatal — the Tag step finds the next free one. Just note it and proceed.
           if git rev-parse -q --verify "refs/tags/v${version}" >/dev/null; then
-            echo "::error::computed v${version} already exists as a git tag — aborting to avoid collision"
-            exit 1
+            echo "note: hint v${version} already tagged — the Tag step will assign the next free version"
           fi
 
           echo "version=${version}"     >> "$GITHUB_OUTPUT"
@@ -120,12 +124,65 @@ jobs:
           echo "sha_short=$(git rev-parse --short "$GITHUB_SHA")" >> "$GITHUB_OUTPUT"
           echo "Next release: v${version} (git_max='${git_max:-none}' container_max='${cont_max:-none}')"
 
+          # Console-embed cachebust. The console clone+build layer is keyed on this;
+          # prefer hanzoai/console main HEAD so a CONSOLE-ONLY change re-embeds without
+          # needing a cloud commit (cloud-sha alone froze the embed between cloud pushes).
+          # git ls-remote must CLEAR the extraheader actions/checkout installs (it carries
+          # THIS repo's GITHUB_TOKEN, which 404s the cross-repo console lookup); gh is not
+          # on the runner. If resolution yields nothing, fall back to the cloud sha — still
+          # unique per cloud commit, so the embed is never frozen. Either way THIS build
+          # busts (new value) and re-clones console main fresh.
+          console_head="$(git -c 'http.https://github.com/.extraheader=' ls-remote \
+            "https://x-access-token:${GH_PAT}@github.com/hanzoai/console.git" refs/heads/main 2>/dev/null | cut -f1 || true)"
+          cachebust="${console_head:-$GITHUB_SHA}"
+          echo "cachebust=${cachebust}" >> "$GITHUB_OUTPUT"
+          echo "console cachebust: ${cachebust} (console_head='${console_head:-none}')"
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
         with:
           driver: docker-container
           driver-opts: network=host
 
+      - name: Mirror credential (registry.hanzo.ai)
+        # Dual-host: pull the KMS deploy kubeconfig (same Universal Auth flow
+        # the hanzoai/ci reusable uses), read the cluster-synced
+        # registry-credentials dockerconfig, and log in. Best-effort: absent
+        # creds → GHCR-only release, never a blocked tag.
+        env:
+          KMS_CLIENT_ID: ${{ secrets.KMS_CLIENT_ID }}
+          KMS_CLIENT_SECRET: ${{ secrets.KMS_CLIENT_SECRET }}
+          KMS_ENDPOINT: ${{ vars.KMS_ENDPOINT || 'https://kms.hanzo.ai' }}
+          REGISTRY_USER: ${{ secrets.REGISTRY_USER }}
+          REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
+        run: |
+          set -uo pipefail
+          # Direct credential first (repo/org secret — works on private repos,
+          # where the Free plan hides org KMS secrets); KMS kubeconfig fallback.
+          if [ -n "${REGISTRY_USER:-}" ] && [ -n "${REGISTRY_PASSWORD:-}" ]; then
+            echo "$REGISTRY_PASSWORD" | docker login registry.hanzo.ai -u "$REGISTRY_USER" --password-stdin
+            echo "MIRROR_OK=1" >> "$GITHUB_ENV"; exit 0
+          fi
+          [ -z "${KMS_CLIENT_ID:-}" ] && { echo "no KMS creds — mirror skipped"; exit 0; }
+          TOKEN=$(curl -sf "$KMS_ENDPOINT/v1/kms/auth/login" -H 'Content-Type: application/json'             -d "{\"clientId\":\"$KMS_CLIENT_ID\",\"clientSecret\":\"$KMS_CLIENT_SECRET\"}" | jq -r '.accessToken // empty')
+          [ -z "$TOKEN" ] && { echo "KMS login failed — mirror skipped"; exit 0; }
+          KC=$(curl -sf "$KMS_ENDPOINT/v1/kms/orgs/hanzo/secrets/deploy/KUBECONFIG?env=prod"                 -H "Authorization: Bearer $TOKEN" | jq -r '.secret.value // empty')
+          [ -z "$KC" ] && { echo "no KUBECONFIG in KMS — mirror skipped"; exit 0; }
+          echo "$KC" | base64 -d > "$RUNNER_TEMP/kubeconfig"
+          command -v kubectl >/dev/null 2>&1 || {
+            KVER=$(curl -fsSL https://dl.k8s.io/release/stable.txt)
+            mkdir -p "$HOME/.local/bin"
+            curl -fsSL "https://dl.k8s.io/release/${KVER}/bin/linux/amd64/kubectl" -o "$HOME/.local/bin/kubectl" && chmod +x "$HOME/.local/bin/kubectl"
+            export PATH="$HOME/.local/bin:$PATH"
+          }
+          CFG=$(KUBECONFIG="$RUNNER_TEMP/kubeconfig" kubectl -n hanzo get secret registry-credentials                   -o jsonpath='{.data.\.dockerconfigjson}' 2>/dev/null | base64 -d || true)
+          [ -z "$CFG" ] && { echo "registry-credentials unreadable — mirror skipped"; exit 0; }
+          UP=$(echo "$CFG" | jq -r '.auths["registry.hanzo.ai"].auth // empty' | base64 -d)
+          [ -z "$UP" ] && { echo "no registry auth — mirror skipped"; exit 0; }
+          echo "::add-mask::${UP#*:}"
+          echo "${UP#*:}" | docker login registry.hanzo.ai -u "${UP%%:*}" --password-stdin
+          echo "MIRROR_OK=1" >> "$GITHUB_ENV"
+
       - name: Log in to ghcr.io (GH_PAT — writes the cloud package despite its ai-repo linkage)
         uses: docker/login-action@v3
         with:
@@ -159,10 +216,15 @@ jobs:
           load: true
           tags: cloud:smoke
           labels: ${{ steps.meta.outputs.labels }}
-          # gh_token: BuildKit secret the Dockerfile consumes to fetch private
+          # Bust the console clone+build layer every release (the cloud commit sha is
+          # unique per push) so the embed re-fetches console main HEAD fresh — never the
+          # frozen snapshot the persistent BuildKit cache would otherwise serve forever.
+          build-args: |
+            CONSOLE_CACHEBUST=${{ steps.ver.outputs.cachebust }}
+          # GIT_AUTH_TOKEN: BuildKit secret the Dockerfile consumes to fetch private
           # cross-org Go modules (hanzoai/*, luxfi/*) over authenticated git.
           secrets: |
-            gh_token=${{ secrets.GH_PAT }}
+            GIT_AUTH_TOKEN=${{ secrets.GH_PAT }}
 
       - name: Smoke test — the binary MUST boot to "listening" with no crash signature
         run: |
@@ -231,6 +293,158 @@ jobs:
 
           echo "SMOKE PASS: cloud:smoke booted to \"listening\" with no crash signature"
 
+      # ── Functional smoke — authenticated per-subsystem probe (the REAL gate) ─────
+      # The boot check above proves the process REACHES "listening"; this proves the
+      # mounted HTTP surface actually WORKS. /smoke (cmd/smoke, baked into the image)
+      # hits ONE side-effect-free read per core subsystem and FAILS the release on any
+      # broken code — above all a 402 on a READ (the balance-gate-over-blocks-reads
+      # regression) or a 5xx (a crash, e.g. the /v1/billing/usage self-dispatch 500).
+      # So a release can never ship with chat/billing/projects/kms/... down.
+      - name: Functional smoke — per-subsystem probe (fails the release if a core endpoint is broken)
+        env:
+          KMS_CLIENT_ID: ${{ secrets.KMS_CLIENT_ID }}
+          KMS_CLIENT_SECRET: ${{ secrets.KMS_CLIENT_SECRET }}
+          KMS_ENDPOINT: ${{ vars.KMS_ENDPOINT || 'https://kms.hanzo.ai' }}
+          # A KMS-provisioned short-lived smoke bearer, injected as a secret (NEVER
+          # hardcoded). Absent → the anonymous matrix still gates public/authed and
+          # catches every 402-on-read / 5xx.
+          SMOKE_TOKEN: ${{ secrets.SMOKE_TOKEN }}
+        run: |
+          set -euo pipefail
+          IMAGE=cloud:smoke
+          CID=""
+          cleanup() { [ -n "$CID" ] && docker rm -f "$CID" >/dev/null 2>&1 || true; }
+          trap cleanup EXIT
+
+          KEY="$(head -c 32 /dev/urandom | base64 | tr -d '\n')"
+          CID="$(docker run -d \
+            --tmpfs /data:rw,size=64m \
+            -e CLOUD_DATA_DIR=/data -e CLOUD_ENV=smoke -e CLOUD_KMS_MASTER_KEY_REF="$KEY" \
+            "$IMAGE")"
+
+          # Wait for the HTTP listener to bind (or the process to die).
+          up=0
+          for _ in $(seq 1 60); do
+            lg="$(docker logs "$CID" 2>&1 || true)"
+            printf '%s' "$lg" | grep -q '"message":"listening"' && { up=1; break; }
+            [ "$(docker inspect -f '{{.State.Running}}' "$CID" 2>/dev/null || echo false)" != "true" ] && break
+            sleep 1
+          done
+          if [ "$up" != 1 ]; then
+            echo "::group::boot logs"; docker logs "$CID" 2>&1 || true; echo "::endgroup::"
+            echo "FUNCTIONAL SMOKE INFRA FAIL: image never reached \"listening\""
+            exit 1
+          fi
+
+          # Token: prefer the injected secret; else mint from KMS (a provisioned smoke
+          # identity); else run the anonymous matrix. Never hardcoded.
+          if [ -z "${SMOKE_TOKEN:-}" ] && [ -n "${KMS_CLIENT_ID:-}" ]; then
+            KT=$(curl -sf "$KMS_ENDPOINT/v1/kms/auth/login" -H 'Content-Type: application/json' \
+              -d "{\"clientId\":\"$KMS_CLIENT_ID\",\"clientSecret\":\"$KMS_CLIENT_SECRET\"}" | jq -r '.accessToken // empty' || true)
+            [ -n "$KT" ] && SMOKE_TOKEN=$(curl -sf "$KMS_ENDPOINT/v1/kms/orgs/hanzo/secrets/smoke/TOKEN?env=prod" \
+              -H "Authorization: Bearer $KT" | jq -r '.secret.value // empty' || true)
+          fi
+          if [ -n "${SMOKE_TOKEN:-}" ]; then echo "::add-mask::$SMOKE_TOKEN"; echo "smoke: AUTHENTICATED matrix"; else echo "smoke: ANONYMOUS matrix (no SMOKE_TOKEN wired)"; fi
+
+          # /smoke is baked into the image (Dockerfile) — exec it INSIDE the container,
+          # so it probes the real mounted surface at localhost:8080 with no port/network
+          # plumbing. A non-zero exit here fails the release BEFORE any image is pushed.
+          docker exec \
+            -e SMOKE_BASE_URL=http://127.0.0.1:8080 \
+            -e SMOKE_TOKEN="${SMOKE_TOKEN:-}" \
+            "$CID" /smoke
+
+      # ── Migration smoke — the gate the v1.800.1 crashloop would have tripped ─────
+      # The plain smoke above boots on a FRESH /data, so every subsystem's migrate()
+      # takes its CREATE-TABLE path and no forward-migration is exercised — which is
+      # exactly why a DDL valid on a fresh store but broken on a pre-existing one (an
+      # index over a not-yet-ADDed column: affiliates referrer_org in v1.800.1, wallets
+      # project/agent before it) sailed through CI and took api.hanzo.ai down. This
+      # step reproduces the REAL prod upgrade path: boot the PRIOR released image to lay
+      # its on-disk (cek-encrypted) SQLite schema into a persistent volume, then boot
+      # the candidate over that SAME volume and require it to still reach "listening".
+      # A migrate() that assumes a fresh store dies here, before any image is pushed.
+      - name: Migration smoke — candidate MUST boot over the PRIOR release's on-disk schema
+        env:
+          # The image whose on-disk schema a prod upgrade migrates FROM — the tag the
+          # fleet runs today. Bump to the last-DEPLOYED tag as releases roll (override
+          # without a code change via the SMOKE_MIGRATION_BASELINE repo/org variable).
+          BASELINE: ${{ vars.SMOKE_MIGRATION_BASELINE }}
+        run: |
+          set -euo pipefail
+          BASELINE="${BASELINE:-ghcr.io/hanzoai/cloud:v1.799.19}"
+          CANDIDATE=cloud:smoke
+          VOL="cloudmig-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+          B1=""; B2=""
+          cleanup() { docker rm -f "$B1" "$B2" >/dev/null 2>&1 || true; docker volume rm "$VOL" >/dev/null 2>&1 || true; }
+          trap cleanup EXIT
+          docker volume create "$VOL" >/dev/null
+
+          # ONE throwaway 32-byte master key for BOTH boots: cek seals each per-db DEK
+          # under it on the baseline boot and unwraps it on the candidate boot. A
+          # mismatched key fails closed (never opens), so sharing it is what puts the
+          # MIGRATE path — not a decrypt error — under test.
+          KEY="$(head -c 32 /dev/urandom | base64 | tr -d '\n')"
+
+          boot() { # $1=image $2=name -> prints container id
+            docker run -d --name "$2" \
+              -v "$VOL":/data \
+              -e CLOUD_DATA_DIR=/data \
+              -e CLOUD_ENV=smoke \
+              -e CLOUD_KMS_MASTER_KEY_REF="$KEY" \
+              "$1"
+          }
+          wait_listen() { # $1=container -> 0 if "listening", 1 if it died / timed out
+            for _ in $(seq 1 90); do
+              lg="$(docker logs "$1" 2>&1 || true)"
+              printf '%s' "$lg" | grep -q '"message":"listening"' && return 0
+              [ "$(docker inspect -f '{{.State.Running}}' "$1" 2>/dev/null || echo false)" != "true" ] && return 1
+              sleep 1
+            done
+            return 1
+          }
+          # A fresh docker named volume is root:root 0755, but the cloud image runs
+          # NON-ROOT, so it cannot create cek's <db>.cek.lock under /data (the single-boot
+          # smoke only worked because --tmpfs is world-writable). Make the shared volume
+          # writable for BOTH boots, re-opening it between them so the candidate can read
+          # the baseline's files even if their runtime UIDs differ.
+          chmod_vol() { docker run --rm --user 0 -v "$VOL":/data --entrypoint sh "$CANDIDATE" -c 'chmod -R 0777 /data'; }
+
+          # Boot 1 — the prior release writes its real schema into the volume. It must
+          # reach "listening" (proof every subsystem migrated + its DB is on disk); if
+          # the pinned baseline can't boot in this env the gate is blind, so fail loud.
+          echo "migration baseline: $BASELINE"
+          pulled=0; for _ in 1 2 3; do if docker pull "$BASELINE"; then pulled=1; break; fi; sleep 5; done
+          [ "$pulled" = 1 ] || { echo "MIGRATION SMOKE INFRA FAIL: cannot pull baseline $BASELINE"; exit 1; }
+          chmod_vol
+          B1="$(boot "$BASELINE" cloudmig_base)"
+          if ! wait_listen "$B1"; then
+            echo "::group::baseline boot logs"; docker logs "$B1" 2>&1 || true; echo "::endgroup::"
+            echo "MIGRATION SMOKE INFRA FAIL: baseline $BASELINE did not reach \"listening\" — cannot stage the prior schema (inspect/bump SMOKE_MIGRATION_BASELINE)"
+            exit 1
+          fi
+          docker stop "$B1" >/dev/null
+          chmod_vol
+
+          # Boot 2 — the candidate migrates that on-disk schema IN PLACE. This is the gate.
+          B2="$(boot "$CANDIDATE" cloudmig_cand)"
+          listening=0; wait_listen "$B2" && listening=1
+          logs="$(docker logs "$B2" 2>&1 || true)"
+          echo "::group::candidate migration boot logs"; printf '%s\n' "$logs"; echo "::endgroup::"
+
+          # 'no such column'/'no such table' is the exact index-before-ADD-COLUMN crash;
+          # 'panic' catches any generic Mount failure. The load-bearing check is the
+          # "listening" assertion below — a migrate() crash exits before it.
+          if printf '%s' "$logs" | grep -Eiq 'panic|no such column|no such table'; then
+            echo "MIGRATION SMOKE FAIL: candidate logged a DDL/migration error over the prior schema (the v1.800.1-class regression)"
+            exit 1
+          fi
+          if [ "$listening" -ne 1 ]; then
+            echo "MIGRATION SMOKE FAIL: candidate did NOT reach \"listening\" over the $BASELINE schema — a subsystem's migrate() crashes on a pre-existing store"
+            exit 1
+          fi
+          echo "MIGRATION SMOKE PASS: candidate booted to \"listening\" over the $BASELINE on-disk schema"
+
       - name: Push (cache hit from the smoke build — publishes the tested image)
         id: push
         uses: docker/build-push-action@v6
@@ -238,49 +452,109 @@ jobs:
           context: .
           platforms: linux/amd64
           push: true
+          # Push ONLY the immutable, per-commit sha- tag (always unique — never races)
+          # and the floating latest. The v<X.Y.Z> version is NOT pushed here: the
+          # compute-step version may be claimed by a concurrent release between compute
+          # and now, and pushing it would clobber that release's :vX image (mutable tag
+          # corruption). The version is assigned + the proven sha-image retagged to it
+          # ATOMICALLY in the Tag step below, so :vX exists iff its git tag exists.
           tags: |
-            ghcr.io/hanzoai/cloud:${{ steps.ver.outputs.version_v }}
-            ghcr.io/hanzoai/cloud:${{ steps.ver.outputs.version }}
-            ghcr.io/hanzoai/cloud:${{ steps.ver.outputs.major_minor }}
             ghcr.io/hanzoai/cloud:sha-${{ steps.ver.outputs.sha_short }}
             ghcr.io/hanzoai/cloud:latest
           labels: ${{ steps.meta.outputs.labels }}
+          # SAME cachebust as the smoke build → every layer is a cache hit from step 1
+          # and the pushed image is byte-identical to the one the smoke test proved.
+          build-args: |
+            CONSOLE_CACHEBUST=${{ steps.ver.outputs.cachebust }}
           secrets: |
-            gh_token=${{ secrets.GH_PAT }}
+            GIT_AUTH_TOKEN=${{ secrets.GH_PAT }}
 
-      # THE RECEIPT: reached only because build + smoke + push all succeeded. If
-      # any of them failed the job already stopped and no tag was minted.
-      - name: Tag the proven image (git tag = receipt for a pushed, smoke-passed image)
+      # THE RECEIPT + ATOMIC VERSION ASSIGNMENT (race-safe). Reached only because
+      # build + smoke + push all succeeded, so a proven image exists under the unique
+      # sha- tag. Here we assign the next FREE v<X.Y.Z> and retag that proven image to
+      # it — atomically, with the git-tag push as the serialization point:
+      #   * Recompute the next version FRESH (compute-step's value may have been claimed
+      #     by a concurrent release in the build window).
+      #   * If that version's git tag already exists, bump and retry.
+      #   * Retag the proven sha-image → :vX (+ :X.Y.Z + :X.Y) via imagetools (metadata
+      #     only, NO rebuild — byte-identical to the smoke-passed image).
+      #   * Push the git tag; the FIRST pusher of vX wins, a loser deletes its local tag
+      #     and recomputes. So concurrent releases each grab a distinct free number and
+      #     the invariant "git tag vX ⇔ image :vX pushed+smoke-passed" holds under race.
+      - name: Tag the proven image (atomic free-version assignment — race-safe)
+        id: tag
         env:
           GH_PAT: ${{ secrets.GH_PAT }}
         run: |
           set -euo pipefail
-          V="${{ steps.ver.outputs.version_v }}"
           git config user.name  "hanzo-dev"
           git config user.email "dev@hanzo.ai"
-          git tag -a "$V" -m "release $V — image ghcr.io/hanzoai/cloud:$V pushed and smoke-passed (${GITHUB_SHA})"
-          git push "https://x-access-token:${GH_PAT}@github.com/${GITHUB_REPOSITORY}.git" "$V"
-          echo "Tagged $V → ghcr.io/hanzoai/cloud:$V"
+          SHA_IMG="ghcr.io/hanzoai/cloud:sha-${{ steps.ver.outputs.sha_short }}"
+          PUSH_URL="https://x-access-token:${GH_PAT}@github.com/${GITHUB_REPOSITORY}.git"
+          for attempt in $(seq 1 8); do
+            git fetch --tags --force --quiet
+            git_max="$(git tag -l 'v[0-9]*.[0-9]*.[0-9]*' \
+              | sed 's/^v//' | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1 || true)"
+            # Newest page only — NOT --paginate. Container versions are created
+            # newest-first and version tags are monotonic, so the highest version
+            # is always among the most-recent versions; paginating the WHOLE
+            # registry history is what livelocked this step as tags accumulated.
+            cont_max=""
+            if command -v gh >/dev/null 2>&1; then
+              cont_max="$(GH_TOKEN="$GH_PAT" gh api \
+                '/orgs/hanzoai/packages/container/cloud/versions?per_page=100' \
+                --jq '.[].metadata.container.tags[]?' 2>/dev/null \
+                | sed 's/^v//' | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1 || true)"
+            fi
+            max="$(printf '%s\n%s\n%s\n' "1.786.0" "$git_max" "$cont_max" \
+              | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)"
+            major="${max%%.*}"; rest="${max#*.}"; minor="${rest%%.*}"; patch="${rest##*.}"
+            VER="${major}.${minor}.$((patch + 1))"; V="v${VER}"
+            if git rev-parse -q --verify "refs/tags/$V" >/dev/null; then
+              echo "  $V already tagged — recomputing (attempt $attempt)"; sleep 3; continue
+            fi
+            docker buildx imagetools create \
+              -t "ghcr.io/hanzoai/cloud:${V}" \
+              -t "ghcr.io/hanzoai/cloud:${VER}" \
+              -t "ghcr.io/hanzoai/cloud:${major}.${minor}" \
+              "$SHA_IMG"
+            # Dual-host: mirror the release tags to OUR fleet registry (server-
+            # side copy) so the cluster never depends on GHCR to deploy. crane,
+            # not buildx imagetools: the IAM token realm doesn't answer buildx's
+            # multi-scope token request (spec gap, tracked), crane's single-scope
+            # flow works. Best-effort — a mirror hiccup never blocks the receipt.
+            if [ "${MIRROR_OK:-}" = "1" ]; then
+              command -v crane >/dev/null 2>&1 || {
+                curl -fsSL https://github.com/google/go-containerregistry/releases/download/v0.20.2/go-containerregistry_Linux_x86_64.tar.gz \
+                  | tar -xz -C "$HOME/.local/bin" crane 2>/dev/null || {
+                    mkdir -p "$HOME/.local/bin"
+                    curl -fsSL https://github.com/google/go-containerregistry/releases/download/v0.20.2/go-containerregistry_Linux_x86_64.tar.gz \
+                      | tar -xz -C "$HOME/.local/bin" crane
+                  }
+                export PATH="$HOME/.local/bin:$PATH"
+              }
+              for MT in "${V}" "${VER}" "${major}.${minor}"; do
+                crane copy "$SHA_IMG" "registry.hanzo.ai/hanzoai/cloud:${MT}" \
+                  || echo "::warning::mirror registry.hanzo.ai/hanzoai/cloud:${MT} failed"
+              done
+            fi
+            git tag -a "$V" -m "release $V — image ghcr.io/hanzoai/cloud:$V (retagged from sha-${{ steps.ver.outputs.sha_short }}, smoke-passed ${GITHUB_SHA})"
+            if git push "$PUSH_URL" "$V" 2>/dev/null; then
+              echo "Tagged $V → ghcr.io/hanzoai/cloud:$V"
+              echo "version=${VER}"    >> "$GITHUB_OUTPUT"
+              echo "version_v=${V}"    >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+            echo "  push of $V lost the race — recomputing (attempt $attempt)"
+            git tag -d "$V" >/dev/null 2>&1 || true
+            sleep 3
+          done
+          echo "::error::could not acquire a free version tag after 8 attempts"
+          exit 1
 
-  # Notify universe so the GitOps pipeline rolls the new image to prod — same
-  # image-update contract every service uses (gateway, iam, …). Runs ONLY after
-  # build-amd64 succeeds, i.e. only for a version whose image is proven pushed and
-  # tagged. A failed release never reaches here, so universe is never asked to
-  # deploy a phantom tag.
-  notify-universe:
-    needs: build-amd64
-    runs-on: [hanzo-build-linux-amd64]
-    steps:
-      - name: Repository dispatch (image-update)
-        uses: peter-evans/repository-dispatch@v3
-        with:
-          token: ${{ secrets.UNIVERSE_DISPATCH_TOKEN }}
-          repository: hanzoai/universe
-          event-type: image-update
-          client-payload: |
-            {
-              "service": "cloud",
-              "image":   "ghcr.io/hanzoai/cloud:${{ needs.build-amd64.outputs.version_v }}",
-              "sha":     "${{ github.sha }}",
-              "env":     "all"
-            }
+  # Deploy = a declared-tag bump in hanzoai/universe crs/cloud.yaml — Hanzo CD
+  # (the ArgoCD instance in ns hanzo-cd) syncs universe→cluster and the operator
+  # reconciles the CR. The old notify-universe repository_dispatch hub is retired
+  # (its flagged-sender dispatches were silently suppressed anyway); the native
+  # release path (release.go rolloutRelease) and deliberate promote commits own
+  # the bump.

.gitignore

@@ -34,3 +34,4 @@ Thumbs.db
 .shots/
 
 .claude/
+native/flags/target

AUTH_BILLING_CONTRACT.md

@@ -0,0 +1,208 @@
+# Unified IAM Auth + Tenant Billing Contract
+
+The ONE way every Hanzo product surface authenticates a user and bills their
+usage. hanzo.chat, hanzo.app, studio.hanzo.ai, and console.hanzo.ai all
+implement THIS contract against `hanzoai/cloud` (api.hanzo.ai). There is no
+per-app billing, no shared API key, and no second way to do any of it.
+
+## The chain, end to end
+
+```
+  Browser (a surface)
+    │  1. OIDC Authorization Code + PKCE, PUBLIC client (no client secret)
+    ▼
+  IAM  (hanzo.id / lux.id / zoolabs.id / pars.id …)
+    │  2. issues user tokens. owner claim = the user's org (the tenant).
+    ▼
+  Surface backend / SPA
+    │  3. holds the user's IAM token server-side (session / httpOnly cookie).
+    │     UI's actively-selected (org, project) = the tenant context.
+    │  4. EVERY call to cloud forwards THAT user's IAM bearer, unchanged:
+    │        Authorization: Bearer <user IAM token>
+    │        X-Project-Id:  <active project>     (optional; org comes from token)
+    ▼
+  cloud (api.hanzo.ai)  — SanitizeIdentity → BillingGate
+    │  5. validates the JWT (JWKS sig + issuer-set + audience + exp).
+    │  6. derives (org, project): org is PINNED from the verified `owner`
+    │     claim (client-supplied X-Org-Id is stripped); project is the
+    │     claim-bound X-Project-Id (else soft-scoped).
+    │  7. meters against the org's shared plan allowance; overflow →
+    │     pay-as-you-go on the org's linked billing account.
+    ▼
+  commerce (billing/pricing) — ONE ledger, keyed on (org, project)
+```
+
+One identity (the user's IAM token), one tenant key (org from the token's
+`owner`, project from the active selection), one ledger. Every surface is a thin
+client of this; none of them holds a shared key or bills anything itself.
+
+## 1. Login — OIDC Authorization Code + PKCE, PUBLIC client
+
+- **Public client, no client secret.** The token endpoint auth method is `none`;
+  security comes from PKCE (`code_challenge_method=S256`) + the signed `state`,
+  not a shared secret baked into a browser-delivered app. A public client cannot
+  leak a secret it does not have.
+- Strategy registration MUST NOT be conditioned on a client secret. (The chat
+  login outage was exactly this: `configureOpenId` was gated on
+  `OPENID_CLIENT_SECRET`, so a secretless public client never registered the
+  `openid` passport strategy → "OpenID strategy not registered".)
+- The `owner` claim is the tenant org. `sub` is the user. A surface reads the org
+  from `owner` (fallback `organization`), never from a client-set field.
+- Reference implementation: `studio/middleware/iam_auth_middleware.py`
+  (`_authorize_redirect` builds the PKCE authorize URL; `handle_callback` adds a
+  `client_secret` to the token exchange ONLY if one is configured — public by
+  default).
+
+## 2. Tenant context — active (org, project)
+
+- A user belongs to one or more orgs; the token's `owner` is the home org, and
+  IAM may carry the full set (`organizations`/`orgs`/`groups`).
+- The UI's actively-selected org + project is the tenant context for the session.
+  Studio carries the active org in the `studio_active_org` cookie and validates
+  it against the token's org set (`middleware/session.py: resolve_org`) — a user
+  can only ever select an org their token authorizes.
+- cloud pins the billing org from the VERIFIED `owner` claim, so even a forged
+  active-org header cannot move spend to another tenant. The active project is
+  forwarded as `X-Project-Id` and is honored as a hard scope only when it is
+  claim-bound; otherwise it degrades to a soft scope (cannot hard-stop, cannot be
+  evaded). See `middleware_billing.go: identityFromCtx`.
+
+## 3. Forwarding to cloud — the user's token, never a shared key
+
+- EVERY request to cloud carries `Authorization: Bearer <the signed-in user's IAM
+  token>`. The token is held server-side (session / httpOnly cookie) and is never
+  exposed to the browser JS.
+- The forwarded token MUST be principal-bound to the authenticated user (`sub`
+  equals the session principal) and unexpired. Fail secure: if no such token is
+  available, DENY (401 / "sign in") — never fall back to an ambient or service
+  credential, which would run as the wrong principal or drain a shared org.
+- NO shared keys. NO per-app keys. NO per-user minted `hk-` keys for chat. The
+  IAM token IS the credential and the billing identity.
+- Reference implementations:
+  - `chat/api/server/routes/agents/cloud.js` +
+    `chat/packages/api/src/endpoints/custom/tenantBearer.ts` — the ONE resolver
+    (`resolveTenantBearer`) both the agents path and the chat-completion path use.
+  - The chat-completion endpoints declare `apiKey: "{{LIBRECHAT_OPENID_TOKEN}}"`;
+    the custom-endpoint initializer substitutes the resolved session bearer at
+    request time (`chat/packages/api/src/endpoints/custom/initialize.ts`).
+
+## 4. Billing — ONE path keyed on (org, project)
+
+cloud is the single meter and gate. `SanitizeIdentity` (mirrored in-binary by
+`auth_identity.go`) validates the token and exposes `c.Org()` / `c.User()` /
+`ValidatedProject(c)`. `BillingGate` (`middleware_billing.go`) then:
+
+- **Billing key = org.** Prepaid balance is per-org: one org credit covers the
+  whole org. `identityFromCtx` sets `User = org` (bare `sub` only when org is
+  absent). Keying per-user would 402 a fully funded org.
+- **Scope axes = (project, service).** `project` is the caller's claim-bound
+  `X-Project-Id`; `service` is SERVER-derived from the route (`/v1/ai/*` → `ai`),
+  never a client field, so a caller cannot spoof another service's cap.
+- **Shared plan, then PAYG.** `AuthorizeVerdict` checks the org's shared plan
+  allowance and per-scope spend caps in one round trip; overflow bills
+  pay-as-you-go against the org's linked billing account. Outcomes map to a frozen
+  HTTP contract:
+  - `200` allowed (with `X-Spend-Warn: <pct>` at a soft cap threshold),
+  - `402 insufficient_balance` — add credits at console.hanzo.ai,
+  - `402 spend_cap_exceeded` — raise the scope cap at console.hanzo.ai/limits,
+  - `503 balance_unavailable` — commerce unreachable, fail-closed.
+- **Single charge.** `/v1/ai/*`, `/v1/agents/*`, and the other self-metering
+  subsystems record their own per-org usage; the edge gate returns price 0 for
+  them so nothing is billed twice (`DefaultPrice` / `selfMeteredPrefixes`).
+
+## 4a. Per-product metering + the product/agent cost axes
+
+Two metering seams share the ONE commerce ledger (`Deps.Metering`):
+
+- **`BillingGate`** (`middleware_billing.go`) — the request EDGE, priced by PATH
+  (`DefaultPrice`). `/v1/ai/*` self-meters token spend upstream (gateway/ai), so it
+  is price-0 here to avoid double-billing.
+
+  **Auto-routing binds to the resolved model.** ai serves a virtual `auto`
+  (alias `zen-router`) model that it resolves to a concrete model id *before*
+  pricing/billing, then meters its own token cost keyed on the SERVED model and
+  reports it via the `X-Routed-Model` response header (echoed in the body
+  `model`). Because the edge prices `/v1/ai/*` by PATH (0), never by the request
+  model, `auto` bills as whatever it resolved to — the ai per-token meter is the
+  single source of the charge. The edge passes `X-Routed-Model` through untouched,
+  so the model reported to the client equals the model billed. Proven end-to-end:
+  `auto_routing_billing_test.go` (`TestAutoRoutingBillsAsResolvedModel`,
+  `TestDefaultPriceAiPathModelAgnostic`).
+- **`ResourceMeter`** (`resource_billing.go`) — IN-HANDLER, priced per-org after the
+  caller's org is resolved. Every non-LLM product uses it: `Gate` (fail-closed
+  pre-auth, `available >= fee`, default fee $1.00 / `DefaultResourceFeeCents`) then
+  `Meter`/`MeterUsage` (debit-on-success, `provider = <product>`). Balance floor is
+  enforced BY DEFAULT — a zero/negative-balance priced call → **402** (proven:
+  `clients/{functions,s3,agents,ml,provisioning}/billing_test.go` `*RefusesUnfundedOrg`).
+
+Metering+gating coverage (each meters its OWN org, debits on success):
+
+| Product | provider label | fee knob | code |
+|---|---|---|---|
+| functions | `functions` | `CLOUD_FUNCTIONS_FEE_CENTS` | `clients/functions/invoke.go` |
+| s3 | `s3` | `S3_*` | `clients/s3/s3.go` |
+| agents | `agent` | `CLOUD_AGENT_FEE_CENTS` | `clients/agents/agents.go` |
+| compute / GPU | `compute` | provision knobs | `clients/ml/ml.go`, `clients/visor/*` |
+| provisioning (sql/kv/vector/docdb) | `provisioning` | `CLOUD_PROVISION_FEE_CENTS[_KIND]` | `clients/provisioning/*` |
+| automations | `automations` | `CLOUD_AUTOMATIONS_FEE_CENTS` | `clients/automations/automations.go` |
+| tracker | `tracker` | fee knob | `clients/tracker/tracker.go` |
+| security | `security.scan` | — | `clients/security/security.go` |
+
+**Product/agent read axes.** The console's per-product Metrics dashboard groups on
+`metadata.product` (and `metadata.agent`). Commerce's `RecordUsage` persists the
+metering SURFACE (`provider`) and billed UNIT (`model`) but has **no `product`
+field** (its `usageRequest` drops `project`/`service`/`product`/`agent`). So the
+customer read handler `clients/billing/usage.go` is the ONE read-side adapter:
+`usage()` fetches the org-scoped ledger and, on 200, injects a canonical
+`metadata.product` onto every row (`productOf`: `agent→agents`,
+`provisioning→<kind>`, token-metered→`inference`, else `provider`) so the
+breakdowns POPULATE from the SAME charged ledger. It also honors, server-side (was
+silently ignored):
+
+- `GET /v1/billing/usage?product=<id>` — filter to one product,
+- `GET /v1/billing/usage?groupBy=product` — per-product rollup
+  `{product,requests,amountCents}`.
+
+A row that already carries `metadata.product`/`agent` wins, so this degrades to a
+no-op when the meter/commerce persist them natively (forward-compatible).
+
+**Remaining checklist** (each is the same seam):
+
+1. **Native `product`/`agent` fields** — add `Product`/`Agent` to
+   `commerce/metering.Usage` + `commerce` `usageRequest`/metadata, have each
+   `ResourceMeter` caller pass its product id, and drop the read-side `productOf`
+   derivation (decomplect: the meter KNOWS its product; record it, don't re-derive).
+   Cross-repo (commerce) — additive/backward-compatible.
+2. **Agent-NAME axis** — needs (1): the agent run debit records `provider=agent` +
+   `model=<llm>` but not the agent name, so `metadata.agent` stays honest-empty
+   until commerce persists an `agent` field the agents meter sets to `a.Name`.
+3. **compute split** — `ml` (predict) and `visor` (GPU) both meter `provider=compute`;
+   read-side can't split `inference` vs `gpus`. Needs (1) so each sets its product id.
+4. **exec / containers** (`clients/exec`, Code Interpreter) — authed by a shared
+   service key (X-API-Key), NO per-org identity, so it can't meter per-org; its
+   compute is billed upstream at the chat/agent layer that invokes it.
+5. **playground** — routes to `/v1/ai/*`, already metered as AI inference.
+
+## 5. Secrets
+
+- Per-tenant, KMS-managed only (`kms.hanzo.ai`, KMSSecret CRDs). No shared
+  service key stands in for a user. The only service tokens that exist are
+  narrow, per-tenant, and never used to impersonate a user for LLM spend.
+- A surface's own OIDC registration is a PUBLIC client — there is no client
+  secret to store.
+
+## Surface conformance (as of this contract)
+
+| Surface | Login (PKCE public) | Forwards user token | Org from `owner` | Billed via cloud (org,project) |
+|---|---|---|---|---|
+| **studio.hanzo.ai** | ✅ reference | ✅ (validates locally) | ✅ | ⚠️ renders run on studio's own GPU workers and self-report to commerce keyed by org via a per-tenant commerce token — org-keyed, but not the forward-bearer-to-gateway path (studio does not call the cloud LLM gateway for its core renders) |
+| **console.hanzo.ai** | ✅ | ✅ same-origin `/v1` through the gateway | ✅ | ✅ (it IS the canonical consumer) |
+| **hanzo.chat** | ✅ (this change) | ✅ (this change: `resolveTenantBearer`) | ✅ | ✅ (this change: forwards bearer to `/v1/ai/*`) |
+| **hanzo.app** | ❌ confidential client (`IAM_CLIENT_SECRET`, userinfo/introspect) | ✅ to its own backend; org from token `owner` | ✅ | ❌ builder AI runs on OpenRouter with an apiKey (`lib/llm/generation-api.ts`), NOT the cloud gateway — off the unified meter |
+
+hanzo.app is the remaining gap: it needs the same treatment chat just got — switch
+its IAM registration to a PKCE public client, and route its builder AI generation
+through api.hanzo.ai forwarding the user's IAM bearer so usage meters against the
+org plan instead of a shared OpenRouter key.
+</content>
+</invoke>

Dockerfile

@@ -2,112 +2,177 @@
 #
 # This image is a SINGLE artifact that serves BOTH the /v1 API AND the console
 # UI from one process: the console is compiled into the Go binary via
-# //go:embed (see webui.go). The pipeline is:
+# //go:embed (see webui.go). The final `/cloud` binary already carries the UI —
+# no separate console Service, no second origin; the embedded console calls /v1
+# on its own host.
 #
-#   1. console  stage → build the hanzoai/console2 static bundle
-#   2. (copied) → into  webui/dist/  of the Go build context
-#   3. build    stage → `go build` bakes webui/dist into the binary (go:embed)
-#
-# so the final `/cloud` binary already carries the UI. No separate console
-# Service, no second origin — the embedded console calls /v1 on its own host.
-#
-# ── console UI stage ─────────────────────────────────────────────────────────
-# Builds the console2 SPA and emits a STATIC bundle at /out. console2 is fetched
-# at a pinned ref (CONSOLE2_REF) using the same gh_token BuildKit secret the Go
-# build uses for private modules.
-#
-# console2 exposes `npm run build:embed` (scripts/build-embed.mjs): it prunes the
-# Next server route handlers (BFF proxies — they collapse to the cloud /v1/* the
-# SPA calls same-origin), wraps the client catch-all pages for output:'export',
-# and neutralizes the root layout's request-time headers() read (the per-host
-# <title>, resolved client-side in the embed) so the STATIC export prerenders
-# clean — emitting out/. This stage runs it and copies out/ into /out, which the
-# Go build drops into webui/dist so //go:embed bakes the FULL @hanzo/gui console
-# into the ONE binary. The stage still degrades to the committed fallback shell,
-# non-fatally, if build:embed is ever absent or fails (a console2 export
-# regression must never take down the cloud backend image) — but the intended,
-# working path is the real bundle.
-FROM public.ecr.aws/docker/library/node:24-alpine AS console
-ARG CONSOLE2_REPO=https://github.com/hanzoai/console2.git
-ARG CONSOLE2_REF=main
-RUN apk add --no-cache git
-WORKDIR /console
-# The static export prerenders every page (webpack compile + export prerender);
-# give the heap headroom so a large @hanzo/gui build never OOMs into the stub.
-ENV NEXT_TELEMETRY_DISABLED=1 NODE_OPTIONS=--max-old-space-size=8192
-RUN --mount=type=secret,id=gh_token \
-    if [ -s /run/secrets/gh_token ]; then \
-      git config --global url."https://x-access-token:$(cat /run/secrets/gh_token)@github.com/".insteadOf "https://github.com/"; \
-    fi && \
-    git clone --depth 1 --branch "${CONSOLE2_REF}" "${CONSOLE2_REPO}" . && \
-    npm install --no-audit --no-fund --fetch-retries=5 --fetch-retry-mintimeout=20000 --fetch-timeout=120000
-# Always emit /out. When console2 exposes a static-embed target AND it builds, /out
-# holds the real bundle; otherwise /out stays EMPTY so the Go build keeps the
-# committed fallback shell. Never fail the image — a static target that is missing
-# OR that fails to build is a degrade, not an error (the standalone console2
-# Deployment is the primary console; this embed is a same-origin convenience). A
-# console2 prerender/export crash (e.g. /signin Server-Components error) must NOT
-# take down the cloud backend image.
-RUN mkdir -p /out && \
-    if npm run 2>/dev/null | grep -q ' build:embed'; then \
-      echo ">> console2 build:embed → static bundle"; \
-      if npm run build:embed && [ -d out ]; then \
-        cp -r out/. /out/; \
-        echo ">> embedded console2 static bundle"; \
-      else \
-        echo ">> console2 build:embed FAILED — degrading to committed fallback shell (non-fatal)"; \
-      fi; \
-    else \
-      echo ">> console2 has no static-embed target yet; cloud embeds the fallback shell"; \
-    fi
+# ── prebuilt decomplection artifacts (cloud compiles ONLY Go) ────────────────
+# The console SPA, the agent-skills catalog, and the native flags staticlib are
+# each built by THEIR OWN CI as a versioned immutable image and PULLED here,
+# instead of rebuilding node + python + rust from scratch every cloud release.
+# The heavy one (console: a cold `npm install` + full Next.js static export,
+# force-cache-busted every build) used to dominate the ~20-min build; it is now
+# a registry pull.
+#   console-embed (hanzoai/console Dockerfile.embed)  → /dist             → webui/dist                  (go:embed)
+#   agent-skills  (hanzoai/openapi Dockerfile.skills) → /catalog          → clients/agentskills/catalog (go:embed)
+#   cloud-flags   (native/flags    Dockerfile)        → /libhanzo_flags.a → CGO link (clients/featureflags)
+# Pinned to ghcr.io so BOTH buildx lanes (release.yml + platform arcbuild) pull
+# it directly; the SAME tags are mirrored to registry.hanzo.ai (S3-backed) for
+# GET-flow consumers (docker/kaniko/crane). Override any pin with
+# --build-arg <NAME>_IMAGE=…  — release.yml resolves CONSOLE_IMAGE to a fresh
+# console-embed digest, exactly as CONSOLE_CACHEBUST re-fetched console before.
+ARG CONSOLE_IMAGE=ghcr.io/hanzoai/console-embed:latest
+ARG SKILLS_IMAGE=ghcr.io/hanzoai/agent-skills:latest
+ARG FLAGS_IMAGE=ghcr.io/hanzoai/cloud-flags:latest
 
-# ── Go build stage ───────────────────────────────────────────────────────────
-# ECR Public mirror of the Docker library image — Docker Hub's unauthenticated
-# pull rate-limit (429 toomanyrequests) fails the build on shared CI runners.
-FROM public.ecr.aws/docker/library/golang:1.26-alpine AS build
-RUN apk add --no-cache ca-certificates tzdata git
+# ── toolchain base images: the golang + alpine FROMs below pull from our own
+# GHCR mirror (ghcr.io/hanzoai/mirror/*), pinned by digest. WHY: public.ecr.aws
+# rate-limits anonymous pulls (HTTP 429) on shared CI runners and a 429 on ANY
+# base pull aborts the release. The mirror packages are 1:1 amd64 copies of the
+# upstream public images, digest-pinned for immutability; release.yml logs the
+# build into ghcr.io (GH_PAT) before building so they resolve. REFRESH on a
+# toolchain bump: crane/regctl copy the new upstream into
+# ghcr.io/hanzoai/mirror/<name>:<tag> and repoint the digest below. Canonical
+# long-term home is registry.hanzo.ai/hanzoai/mirror/* — repoint once the runners
+# carry its IAM pull credentials (follow-up).
+
+# ── console SPA static export (prebuilt → /dist) ─────────────────────────────
+FROM ${CONSOLE_IMAGE} AS console
+
+# ── agent-skills catalog (prebuilt → /catalog) ──────────────────────────────
+FROM ${SKILLS_IMAGE} AS skills
+
+# ── native flags evaluator staticlib (prebuilt → /libhanzo_flags.a) ──────────
+FROM ${FLAGS_IMAGE} AS flagslib
+
+FROM ghcr.io/hanzoai/mirror/golang:1.26-alpine3.22@sha256:47d47cb5cc3c7dac409dcb6c3a98a6263571218046cd02d709527feef804a77c AS build
+# CIPHER-FORMAT FREEZE (cek depends on this). The data-plane stores are
+# SQLCipher pages in a fixed on-disk format (cipher_compatibility 4). An at-open
+# compat pin is infeasible (mattn keys via URI before any pragma), so the format
+# is frozen by pinning sqlcipher-dev to an EXACT version. A repo bump then fails
+# the build LOUDLY (never a silent prod brick); on such a failure, bump the pin
+# AND confirm cek's frozen-fixture test still opens (format unchanged)
+# before shipping. A MAJOR bump (4.x → 5.x) changes the default format and would
+# orphan existing encrypted stores — migrate/rewrap them first.
+RUN apk add --no-cache ca-certificates tzdata git gcc musl-dev sqlcipher-dev=4.6.1-r0 pkgconfig binutils
 RUN addgroup -g 65532 -S nonroot && adduser -u 65532 -S nonroot -G nonroot
+# mattn/go-sqlite3's `libsqlite3` tag hard-codes `-lsqlite3`, but alpine's
+# sqlcipher-dev ships ONLY libsqlcipher (no libsqlite3.so). Symlink so the link
+# resolves -lsqlite3 to libsqlcipher — REAL encryption. Do NOT `apk add sqlite-dev`
+# (a plaintext libsqlite3 would silently disable the codec; the gate below catches it).
+RUN set -eux; \
+    SC="$(find /usr/lib /lib -name 'libsqlcipher.so*' 2>/dev/null | sort | head -1)"; \
+    test -n "$SC"; \
+    ln -sf "$SC" /usr/lib/libsqlite3.so; \
+    ln -sf "$SC" /usr/lib/libsqlite3.so.0
 WORKDIR /src
-# hanzoai/* and luxfi/* are PUBLIC and resolve via the IMMUTABLE public proxy +
-# sumdb — go.sum pins those canonical hashes, so a force-re-pointed tag can never
-# break the build. Routing them DIRECT (the old GOPRIVATE approach) re-fetches a
-# re-tagged tree (e.g. luxfi/age@v1.5.0) whose hash differs from go.sum's proxy
-# hash → "checksum mismatch / SECURITY ERROR". This matches the drop-GOPRIVATE
-# fix already shipped in hanzoai/iam + luxfi/kms. Only zap-proto/* stays first-
-# party-direct (kept in GOPRIVATE) — authenticated git via gh_token. GOPROXY
-# still routes nested-path monorepo tags (e.g. tencentcloud-sdk-go) through the
-# proxy. The committed go.sum is the single source of truth.
-ENV GOPRIVATE=github.com/zap-proto/* \
-    GONOSUMDB=github.com/zap-proto/* \
-    GOSUMDB=off \
+# zap-proto/* (all 55 repos) and luxfi/* (all 37 deps here) are PUBLIC and resolve
+# via the IMMUTABLE public proxy + sumdb — go.sum pins those canonical hashes, so a
+# force-re-pointed tag can never break the build. GOSUMDB stays ON (a money image
+# must not blanket-disable the checksum database); github.com/hanzoai/* is the
+# exempt namespace — ai, account, commerce, orm, xorm, beego, csqlite and ~30 more
+# are PRIVATE repos, so they resolve direct+authenticated (git over gh_token) and
+# skip a sumdb that cannot see them. GOPRIVATE named zap-proto until now, which is
+# public and was never the reason anything was direct; the private namespace it
+# stood for went unnamed and worked only on the GOPROXY `direct` fallback.
+# -mod=readonly means the committed go.sum is the SOLE source of truth: any drift
+# (a needed hash not present) FAILS the build instead of being silently
+# re-recorded. CGO_CFLAGS/LDFLAGS enable the SQLCipher codec + URI keying.
+ENV CGO_CFLAGS="-DSQLITE_HAS_CODEC -DSQLITE_USE_URI=1 -I/usr/include/sqlcipher" \
+    CGO_LDFLAGS="-lsqlcipher" \
+    GOPRIVATE=github.com/hanzoai/* \
     GOPROXY=https://proxy.golang.org,direct \
-    GOFLAGS=-mod=mod
+    GOFLAGS=-mod=readonly
 COPY go.mod go.sum ./
-# With go.sum recorded against live tag content and our orgs routed direct, this
-# verifies cleanly — no runtime go.sum regeneration. (The old `rm -f go.sum`
-# self-heal masked a stale go.sum and silently re-recorded unverified hashes on
-# ANY transient error; removed in favor of a correct, committed go.sum.)
-RUN --mount=type=secret,id=gh_token \
-    if [ -s /run/secrets/gh_token ]; then \
-      git config --global url."https://x-access-token:$(cat /run/secrets/gh_token)@github.com/".insteadOf "https://github.com/"; \
+# The cache mounts carry an EXPLICIT id so they can be busted. Without one,
+# BuildKit keys the cache by target path alone, and a poisoned entry is immortal:
+# a module resolved while its tag did not yet exist is remembered as "unknown
+# revision" forever, so `go mod download` keeps failing on a tag that now exists
+# and resolves fine from a clean cache. That is exactly what wedged the release
+# on otel-collector v0.144.10. BUMP THE SUFFIX (-v4 -> -v5) to force a cold
+# module cache the next time a phantom pin poisons it.
+RUN --mount=type=secret,id=GIT_AUTH_TOKEN \
+    --mount=type=cache,id=cloud-gomod-v4,target=/go/pkg/mod,sharing=locked \
+    if [ -s /run/secrets/GIT_AUTH_TOKEN ]; then \
+      git config --global url."https://x-access-token:$(cat /run/secrets/GIT_AUTH_TOKEN)@github.com/".insteadOf "https://github.com/"; \
     fi && \
     go mod download
 COPY . .
 # Drop the console static bundle into the embed path BEFORE `go build`, so
-# //go:embed all:webui/dist bakes it into the binary. /out from the console stage
-# is either the real static build (then it overlays the committed fallback shell)
-# or empty (then webui/dist keeps the shell that `COPY . .` already brought). The
-# committed assets/.gitkeep keeps the embed's assets/ dir present either way.
-COPY --from=console /out/ /src/webui/dist/
-RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /cloud ./cmd/cloud
+# //go:embed all:webui/dist bakes it into the binary (same-origin console).
+COPY --from=console /dist/ /src/webui/dist/
+# Overlay the FULL agent-skills catalog before `go build` so //go:embed all:catalog
+# bakes the complete set (all services × brands), not the committed `ai` fallback.
+COPY --from=skills /catalog/ /src/clients/agentskills/catalog/
+# The native flags staticlib at the exact ${SRCDIR}-relative path the cgo
+# directive in clients/featureflags/engine.go links.
+COPY --from=flagslib /libhanzo_flags.a /src/native/flags/target/release/libhanzo_flags.a
+# RED gate — modernc double-registration guard: 0 modernc under CGO=1, else the
+# "sqlite" driver is registered twice (mattn + modernc) → panic at init.
+RUN --mount=type=cache,id=cloud-gomod-v4,target=/go/pkg/mod,sharing=locked \
+    --mount=type=cache,id=cloud-gobuild-v4,target=/root/.cache/go-build,sharing=locked \
+    MODERNC="$(CGO_ENABLED=1 go list -tags "libsqlite3 sqlite_fts5" -deps ./cmd/cloud 2>/dev/null | grep -c 'modernc.org/sqlite' || true)"; \
+    [ "$MODERNC" = "0" ] || { echo "SQLITE-GATE FAIL: cmd/cloud links modernc.org/sqlite ($MODERNC pkgs) under CGO=1 — double-registers \"sqlite\" with hanzoai/sqlite(mattn) and panics at init."; exit 1; }
+# RED gate — ENCRYPTION PROOF + the cek.go GOLDEN-VECTOR KAT, under the SAME CGO +
+# libsqlcipher build this image ships. TestEncryptionProof asserts real
+# ciphertext-at-rest (SQLITE_REQUIRE_CODEC=1 makes a plaintext link FAIL → NO
+# image). TestUnwrapGoldenFixture asserts a FROZEN pre-luxfi-swap 61-byte DEK
+# sidecar still decrypts under the shipped luxfi/crypto-AEAD code — existing
+# encrypted stores stay readable, or NO image.
+RUN --mount=type=cache,id=cloud-gomod-v4,target=/go/pkg/mod,sharing=locked \
+    --mount=type=cache,id=cloud-gobuild-v4,target=/root/.cache/go-build,sharing=locked \
+    SQLITE_REQUIRE_CODEC=1 CGO_ENABLED=1 go test -count=1 -tags "libsqlite3 sqlite_fts5" \
+      -run 'TestEncryptionProof|TestUnwrapGoldenFixture|TestWrapUnwrapRoundTripPinsLayout' \
+      github.com/hanzoai/sqlite
+# RED gate — cek FROZEN-FORMAT guard, run INSIDE the image under the pinned Alpine
+# libsqlcipher: opens the committed encrypted fixture and reads its canary row. A
+# sqlcipher-dev pin/base bump that changes the on-disk format fails the IMAGE build
+# HERE (not only Go CI) → a silent prod brick of existing stores becomes a red build.
+RUN --mount=type=cache,id=cloud-gomod-v4,target=/go/pkg/mod,sharing=locked \
+    --mount=type=cache,id=cloud-gobuild-v4,target=/root/.cache/go-build,sharing=locked \
+    SQLITE_REQUIRE_CODEC=1 CGO_ENABLED=1 go test -count=1 -run TestFrozenFixtureOpens \
+      -tags "libsqlite3 sqlite_fts5" ./cek
+RUN --mount=type=cache,id=cloud-gomod-v4,target=/go/pkg/mod,sharing=locked \
+    --mount=type=cache,id=cloud-gobuild-v4,target=/root/.cache/go-build,sharing=locked \
+    CGO_ENABLED=1 go build -tags "libsqlite3 sqlite_fts5" -ldflags="-s -w" -o /cloud ./cmd/cloud
+# The functional smoke prober (cmd/smoke) — a stdlib-only, static binary shipped
+# alongside /cloud so the release gate can `docker exec` it against the freshly-built
+# image (and any deployment can be smoked via `docker run --entrypoint /smoke ...`).
+RUN --mount=type=cache,id=cloud-gomod-v4,target=/go/pkg/mod,sharing=locked \
+    --mount=type=cache,id=cloud-gobuild-v4,target=/root/.cache/go-build,sharing=locked \
+    CGO_ENABLED=0 go build -ldflags="-s -w" -o /smoke ./cmd/smoke
+# Prove the SHIPPED binary binds sqlite3_* to libsqlcipher, not a plaintext libsqlite3.
+RUN readelf -d /cloud | grep -qE 'NEEDED.*(sqlcipher|sqlite3)' || { echo "FATAL: /cloud links no sqlite/sqlcipher .so"; exit 1; }; \
+    ! ldd /cloud 2>/dev/null | grep -E 'libsqlite3' | grep -vq 'libsqlcipher' || { echo "FATAL: /cloud resolves a NON-sqlcipher libsqlite3 (plaintext risk)"; exit 1; }
 
-# ── final image ──────────────────────────────────────────────────────────────
-FROM scratch
+# ── final image (alpine, NOT scratch — CGO needs libc + libsqlcipher) ─────────
+FROM ghcr.io/hanzoai/mirror/alpine:3.22@sha256:7c8cb692ae09657cbc4a3f3cbd0e8d5a2690ba38386aaaf252dbb060bf5eb2e6
+ARG REVISION=unknown
+LABEL org.opencontainers.image.revision="${REVISION}" \
+      org.opencontainers.image.source="https://github.com/hanzoai/cloud"
+# Runtime needs libsqlcipher (the codec the binary links). It must NOT also carry
+# a plaintext libsqlite3 — the binary's -lsqlite3 DT_NEEDED would then bind to
+# plaintext sqlite and silently no-op PRAGMA key. sqlcipher-libs ships
+# libsqlcipher.so.0; alias libsqlite3.so.0 to it so sqlite3_* binds there.
+#
+# `git` backs the git object plane (clients/git): the heavy paths — clone/fetch
+# serve, push receive, mirror-in — shell out to the streaming git CLI
+# (upload-pack / receive-pack --stateless-rpc / fetch) so multi-GB packs stream
+# to and from disk with bounded memory instead of buffering whole packs in RAM.
+# The `git` apk package carries upload-pack/receive-pack/http-backend/git-remote-https.
+# libgcc: the hanzo-flags Rust staticlib (clients/featureflags FFI) references the
+# _Unwind_* unwinder symbols; musl needs libgcc_s at load time or the binary fails
+# relocation ("Error relocating /cloud: _Unwind_GetIP: symbol not found").
+RUN apk add --no-cache ca-certificates tzdata sqlcipher-libs git libgcc \
+    && SC="$(find /usr/lib /lib -name 'libsqlcipher.so*' 2>/dev/null | sort | head -1)" \
+    && test -n "$SC" \
+    && ln -sf "$SC" /usr/lib/libsqlite3.so.0
 COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
 COPY --from=build /usr/share/zoneinfo /usr/share/zoneinfo
 COPY --from=build /etc/passwd /etc/passwd
 COPY --from=build /etc/group /etc/group
 COPY --from=build /cloud /cloud
+COPY --from=build /smoke /smoke
 EXPOSE 8080 9090 9653
 USER 65532:65532
 ENTRYPOINT ["/cloud"]

LLM.md

@@ -0,0 +1,186 @@
+# LLM.md — hanzoai/cloud
+
+Guidance for AI agents working in this repo. `hanzoai/cloud` (HIP-0106) is ONE Go
+binary + CLI that mounts every Hanzo subsystem into a single process; the same
+artifact serves `api.hanzo.ai`, `api.lux.cloud`, `api.zoo.cloud`, `api.osage.cloud`
+and every white-label reseller. Brand, enabled subsystems, and org scope are
+deployment configuration.
+
+## Framework doctrine
+
+One way to do everything. Composable, orthogonal, DRY. A new subsystem is a
+package under `clients/<name>` that obeys these seams — nothing more.
+
+- **Subsystem shape.** A subsystem exposes `func Mount(app *zip.App, deps cloud.Deps) error`
+  and is listed in `apps.Wire()` as a `cloud.MountSpec{Name, Mount: cloud.Typed(Mount)}`
+  (plus `Shutdown`/`OwnsHealth` where it owns them). `Mount` wires that subsystem's
+  `/v1/<name>/*` routes onto the shared `*zip.App`; `cloud.Deps` carries the
+  process-wide handles (Logger, DataDir, the subsystem `Client` seams). No
+  subsystem reaches into another's internals. There is no init()-registry and no
+  `cloud.Register` — subsystems do NOT self-register.
+- **Client seams.** Cross-subsystem calls go through a narrow in-process interface
+  published in `types` and aliased at the provider, e.g. `commerce.Client =
+  types.CommerceClient` (`GetOrgConfig` + `CheckEntitlement`). Consumers depend on
+  the interface, never the implementation; the seam rides zap-proto/zip. Keep each
+  interface minimal — add a method only when a consumer needs it.
+- **Composition root.** `apps/apps.go:Wire()` returns `[]cloud.MountSpec` — every
+  linked subsystem, in mount order, as ONE explicit slice read top-to-bottom.
+  Slice position IS the order: there is no `Order` field and `MountAll`
+  (build.go) does NOT sort; it iterates as-given and mounts each ENABLED spec
+  (`cfg.Enabled`). To add a subsystem you add one line to `Wire()`.
+  `apps/wire_test.go` freezes the sequence, so a reorder/drop/add fails there.
+- **Route precedence.** The router is zap-proto/fiber (zip v1.8.3). Most-specific
+  route wins regardless of mount order, so subsystems may mount in any order and
+  still compose deterministically. But precedence is NOT a conflict guard: two
+  registrations of a byte-identical pattern do NOT panic — fiber MERGES them into
+  ONE route with both handlers chained, resolving by first-registration. That is
+  invisible to a `GetRoutes()` entry count (see the bots note below), and it is
+  NOT distinguishable from a legitimate middleware chain: `app.Post(path, mw1,
+  mw2, mw3, handler)` is one registration with four handlers (apps/commerce.go:151),
+  and the whole `/v1/store/*` surface is that shape. A high handler count is
+  therefore evidence of nothing on its own; only a subsystem that never chains
+  middleware (bots/visor/runtime) can read `len(Handlers) > 1` as a collision.
+- **Per-org data.** The ONE way any subsystem opens a per-org SQLite file is
+  `cloud.OrgDB(dataDir, org, project, sub)` — or the cached `cloud.OrgStore[T]`
+  (`NewOrgStore` + `For(org, project)`). Path convention:
+  `{DataDir}/orgs/{org}/{sub}.db`, or `{DataDir}/orgs/{org}/projects/{project}/{sub}.db`
+  when project-scoped. Isolation is PHYSICAL: a distinct `(org[, project])` is a
+  distinct file. `org`/`project` MUST be the VALIDATED principal values
+  (`principal.Org(c)`, `principal.Project(c)`) — never a raw body/header — and are
+  folded through `SanitizeOrg`, the ONE injective org slugger. hanzoai/sqlite is
+  the SOLE driver (blank-imported once, in orgdb.go); subsystems never import a
+  SQLite driver themselves. The caller owns its schema/migration and Close.
+
+## The route table has three projections, and the router is the source
+
+`serve.go` composes ONE route table and projects it three ways, all after
+`MountAll` so each sees a complete table: `/zap` REPLAYS the /v1 handlers
+(zapface), the console RENDERS them, and `GET /v1/openapi.json` DESCRIBES them
+(`openapi.Mount`). None holds a second copy of anything; none can drift.
+
+- **The spec IS the router.** `openapi.Live(app)` reads
+  `app.Fiber().GetRoutes(true)` — fiber's own filter drops `Use()` middleware —
+  and every other function in `openapi/` is a pure function of that `[]Route`.
+  There is NO checked-in spec file to hand-maintain and no second registry. The
+  drift guard is `cmd/cloud/openapi_test.go`: a BIJECTION over the fully-mounted
+  `apps.Wire()` (983 operations / 692 paths / 109 products) — every live route
+  appears as an operation, every operation is backed by a live route. It is the
+  only test whose failure means the document lies.
+- **Reading the LIVE router is the only total source.** `POST /v1/kms/auth/login`
+  is registered as `Group("/v1/kms/auth").Post("/login")` — no grep can find that
+  path; only the assembled router knows it. And the route set is a function of
+  deployment config (`cfg.Enabled`, plus internal gates like kms's `if kc != nil`),
+  so **the spec VARIES PER DEPLOYMENT** — correctly: a deployment that does not
+  mount admin does not advertise it. That is why the document is generated
+  per-process at request time, not built once in CI.
+- **The product axis is mechanical.** The first path segment after `/v1/` IS the
+  product (`openapi.Product`), tagged onto each operation so a CLI can build
+  `hanzo <product> <resource> <verb>` with no judgment. It is deliberately NOT the
+  subsystem name: `clients/billing` also serves `/v1/finance/*`.
+- **What the router CANNOT tell you — do not try to fix this in the generator.**
+  Method, path, path params, and product are derivable; request/response schemas,
+  query/header params, status codes, and auth are NOT. The router holds a
+  `func(*zip.Ctx) error`; the request type is a LOCAL inside the handler
+  (`var req secretPutRequest; json.Unmarshal(ctx.Body(), &req)`), and Go cannot
+  reflect from a func value into its body. `cloud.Handle[S]` does not help — `S`
+  is the SERVICE (service.go:90), not the payload; `cloud.Typed` is an
+  `any→*zip.App` mount adapter. The ONE path to schemas is zip's typed ops
+  (`zip.Get[In,Out]`), which carry the In/Out types and also yield an MCP tool
+  from the same registry (zip/openapi.go, zip/mcp.go — today `len(a.ops) == 0`,
+  so zip's own generator emits nothing here). `GetRoutes()` is a superset of
+  `app.ops`, so migrating a handler to a typed op adds schema without changing
+  this pipeline.
+- **Catch-alls are opaque, by construction.** `app.Post("/v1/billing/*")` proxies
+  to another service, so `POST /v1/billing/deposit` is NOT a route in this process
+  and cannot appear. Measured on the live table: 3 products are wholly opaque
+  (`bot`, `licensing`, `sentry` — the catch-all IS the product) and 12 more mix
+  concrete ops with a catch-all hiding an unknown remainder.
+
+## Cross-subsystem seams that are values, not places
+
+- **The per-principal MCP plane is callable in-process.** `clients/automations`
+  decomplects tool dispatch from its front doors: `dispatchTool` is the ONE core
+  (resolve `<connector>_<action>` → run with a Token bound to the VALIDATED org),
+  and TWO doors share it — the HTTP JSON-RPC handler (`POST /v1/automations/mcp`)
+  and the exported `automations.InvokeTool(ctx, org, tool, args)`. A sibling
+  subsystem that must ACT AS a caller (the Business AI guide's "do it for me")
+  calls `InvokeTool` with `principal.Org(c)` — same 403 gate, per-org concurrency
+  bound, one metered unit, one audit record as the HTTP door — so it can never
+  exceed the caller's authority. Use this seam; never re-implement tool dispatch.
+- **"Bot" is three values; each has one home and one namespace.** Do not merge
+  them and do not let them share a route prefix — they did once, and the router
+  resolves byte-identical patterns by first-registration with no panic (it MERGES
+  the handlers, so counting `GetRoutes()` entries cannot see it), and visor's
+  machine list silently answered the console's run list.
+  (1) A bot RUN — a task the runtime executes on a surface — is `clients/bots` at
+  `/v1/bots`. (2) A bot MACHINE — visor-provisioned compute of kind=bot plus its
+  agent binding — is `clients/visor` at `/v1/compute/bots`; what it rents you is
+  compute, so it nests in visor's domain. (3) The runtime SERVICE — the TS bot
+  (channels/skills), never reimplemented in Go — is reached through
+  `clients/runtime`, which is a TRANSPORT, not a domain: base address, identity,
+  framing, cleartext policy, and the `/v1/bot/*` ops face. It is named for what it
+  does, not for the host it dials, and it must never import `bots`/`coding` — each
+  of those owns its own wire stub (`bots/wire.go`, `coding/task.go`) and speaks
+  through the seam. That isolation is what makes the HIP-0106/HIP-0120 ZAP swap a
+  seam swap instead of a rewrite.
+- **Cloud owns policy; the runtime owns the run. Do not copy state you do not
+  own.** `clients/bots` holds NO store. The sandbox lives in the bot runtime,
+  keyed in the runtime's own tenant store, which is the only thing that knows
+  whether a run is alive — so list and stop PROXY it, gated by cloud's
+  principal/org. A cloud-side registry was tried and was wrong: it minted an id
+  the runtime had never heard of, so it listed runs that did not exist and
+  "stopped" runs that were never started. Isolation holds because the org is the
+  validated one cloud sends, never a client's, and the runtime keys every run
+  under `tenants/{org}/`.
+- **Absence is only meaningful from a callee that could have said otherwise.**
+  `runtime.ErrNotFound` (the operation ANSWERED "no such target") is separate from
+  `runtime.ErrNotServed` (the operation does not exist). Conflating them makes a
+  stop that cannot fail: a runtime without the route reports absent for EVERY run,
+  so "already gone" becomes permanently true. A bare 404 is 502, never success.
+- **The Business AI Guide (`clients/guide`, `/v1/guide/*`)** is the on-site launch
+  checklist: a pure engine (`curriculum.go` — parse/validate/next-step/dependency
+  gating over plain data) + per-org progress (`cloud.OrgStore[*Store]`) + an
+  injectable auto-detect registry (`detect.go` — `acted` reads the agent action
+  ledger, `analytics` probes the shared warehouse) + the agent (`agent.go` — drafts
+  with `deps.AI`, executes the step's bound tool via `automations.InvokeTool`). The
+  curriculum is a machine-readable contract (embedded `default.yaml`; org-custom via
+  PUT replaces it) so `hanzoai/marketing` can author the full `checklist.yaml`
+  against the same `Step`/`Curriculum` shape.
+
+## Identity vocabulary is IAM-native
+
+Identity is expressed ONLY in IAM-native nouns: **org, user, project, billing
+account**. The word **"tenant" is banned** in cloud identifiers, strings,
+comments, and filenames. Resolve org/project scope through `clients/principal`
+(`principal.Org(c)`, `principal.Project(c)`) and user identity through `c.User()`
+— all gateway-minted, JWT-validated values (X-Org-Id / X-Project-Id / X-User-Id,
+HIP-0026); never read a raw request header for scope.
+
+- **The one gated exception.** `clients/platform` derives customer-app Kubernetes
+  namespaces, registry image refs, and quota/limit objects from a live `tenant-<org>`
+  string prefix. Renaming that prefix orphans deployed namespaces + built images,
+  so the literal `"tenant-"` string (and its directly-adjacent comment) is retained
+  behind a `// NAMING(gated)` note in `clients/platform/k8s.go`. The surrounding
+  identity vocabulary is org-native regardless; only the on-cluster string waits on
+  an infrastructure migration.
+
+## Hanzo Company (`clients/company`, `/v1/company`)
+
+The Stripe-Atlas-class incorporation + fundraising product: ONE formation state
+machine per org. `machine.go` is the PURE core — a `transitions` table with a guard
+per edge, `Advance(f, to)` the only mutator — so transitions, the payment gate, and
+the skip path are unit-testable with no I/O. The HTTP surface is decomplected: ACTION
+endpoints populate data (structure/founders/kyc/payment/documents/esign/genesis/
+import), and ONE `POST /v1/company/advance {to}` runs the guarded transition.
+
+Every external dependency is a narrow provider interface (`providers.go`) so the
+machine composes them identically in prod and tests: billing → the shared
+`ResourceMeter` ($999 one-time fee); documents → `dataroom.Ingest` (new in-proc
+facade); cap table → `captable.*` (new in-proc facades: SetIncorporation /
+AddStakeholders / EnsureShareClass / IssueShares / RecordRound); equity genesis →
+a KMS-signed Hanzo-L1 anchor mirroring `clients/treasury` (honest pending when
+unwired); KYC + state filing → honest stubs (no fabricated verification/filing).
+Import path (already-incorporated orgs): Google Drive → data room, a Google Sheet →
+captable, via the `google` OAuth provider now completed in `clients/integrations`
+(token custodied in KMS; the automations `google` connector shares the same token).
+Runbook: `docs/company-dogfood.md`.

Makefile

@@ -7,8 +7,10 @@ PKG             ?= ./cmd/cloud
 DOCKER_IMAGE    ?= ghcr.io/hanzoai/cloud
 DOCKER_TAG      ?= dev
 LDFLAGS         ?= -s -w
-# Path to a hanzoai/console2 checkout used to build the embedded console bundle.
-CONSOLE2_DIR    ?= ../console2
+# Path to a hanzoai/console checkout used to build the embedded console bundle.
+CONSOLE_DIR    ?= ../console
+# Path to a hanzoai/openapi checkout — the SOT the agent-skills catalog is generated from.
+OPENAPI_DIR    ?= ../openapi
 
 # The shipped binary is pure Go (Dockerfile: CGO_ENABLED=0 → scratch). Default all
 # build/test targets to that mode so `make build`/`make test` exercise exactly
@@ -22,27 +24,38 @@ CONSOLE2_DIR    ?= ../console2
 # forces the fork to modernc too so the whole binary registers "sqlite" once.
 CGO_ENABLED     ?= 0
 
-.PHONY: help webui build build-standalone run smoke test test-cgo vet tidy docker docker-push clean
+.PHONY: help native webui agentskills build build-standalone hanzo run smoke test test-cgo vet tidy docker docker-push clean
 
 help: ## Show this help.
 	@awk 'BEGIN{FS=":.*##";printf "\nUsage: make <target>\n\nTargets:\n"} /^[a-zA-Z_-]+:.*##/{printf "  \033[36m%-16s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
 
-webui: ## Build the real console2 static bundle into webui/dist (go:embed source). CONSOLE2_DIR=<path to console2>.
+webui: ## Build the real console static bundle into webui/dist (go:embed source). CONSOLE_DIR=<path to console>.
 	@command -v npm >/dev/null 2>&1 || { echo "npm is required to build the console bundle"; exit 1; }
-	@test -f "$(CONSOLE2_DIR)/package.json" || { echo "console2 checkout not found at $(CONSOLE2_DIR) — set CONSOLE2_DIR=<path>"; exit 1; }
-	@test -d "$(CONSOLE2_DIR)/node_modules" || (cd "$(CONSOLE2_DIR)" && npm install --no-audit --no-fund)
-	cd "$(CONSOLE2_DIR)" && NEXT_TELEMETRY_DISABLED=1 NODE_OPTIONS=--max-old-space-size=8192 npm run build:embed
+	@test -f "$(CONSOLE_DIR)/package.json" || { echo "console checkout not found at $(CONSOLE_DIR) — set CONSOLE_DIR=<path>"; exit 1; }
+	@test -d "$(CONSOLE_DIR)/node_modules" || (cd "$(CONSOLE_DIR)" && npm install --no-audit --no-fund)
+	cd "$(CONSOLE_DIR)" && NEXT_TELEMETRY_DISABLED=1 NODE_OPTIONS=--max-old-space-size=8192 npm run build:embed
 	# Overlay the fresh static export onto webui/dist, keeping only the tracked
 	# fallbacks (.gitignore + assets/.gitkeep); the real bundle is build-time-only.
 	find webui/dist -mindepth 1 -maxdepth 1 ! -name .gitignore ! -name assets -exec rm -rf {} +
-	cp -r "$(CONSOLE2_DIR)/out/." webui/dist/
-	@echo ">> embedded real console2 bundle into webui/dist (index.html $$(wc -c < webui/dist/index.html) bytes)"
+	cp -r "$(CONSOLE_DIR)/out/." webui/dist/
+	@echo ">> embedded real console bundle into webui/dist (index.html $$(wc -c < webui/dist/index.html) bytes)"
+
+agentskills: ## Regenerate the FULL agent-skills catalog into clients/agentskills/catalog (go:embed source) from the openapi SOT. OPENAPI_DIR=<path to openapi>.
+	@test -f "$(OPENAPI_DIR)/skills.py" || { echo "openapi checkout not found at $(OPENAPI_DIR) — set OPENAPI_DIR=<path> or clone hanzoai/openapi"; exit 1; }
+	# skills.py rewrites the whole catalog dir; the .gitignore keeps only the tiny
+	# `ai` fallback tracked, so the full set is embedded at build but never committed.
+	python3 "$(OPENAPI_DIR)/skills.py" --no-services --out clients/agentskills/catalog
+	@echo ">> embedded FULL agent-skills catalog ($$(jq -r .skill_count clients/agentskills/catalog/hanzo/index.json) skills/brand)"
 
 build: ## Build the unified cloud binary into ./bin/cloud (embeds whatever webui/dist holds — run `webui` first for the real console).
 	@mkdir -p bin
 	CGO_ENABLED=$(CGO_ENABLED) $(GO) build -ldflags="$(LDFLAGS)" -o bin/$(BIN) $(PKG)
 
-build-standalone: webui build ## Build the REAL 1-binary console: console2 build:embed → webui/dist → go build.
+build-standalone: webui build ## Build the REAL 1-binary console: console build:embed → webui/dist → go build.
+
+hanzo: ## Build the hanzo control-plane CLI into ./bin/hanzo (pure Go, same mode as cmd/cloud — registers the ONE "sqlite" driver exactly once; a plain CGO_ENABLED=1 `go build ./cmd/hanzo` links the fork's mattn backend alongside the embedded modernc importers and panics, see header).
+	@mkdir -p bin
+	CGO_ENABLED=$(CGO_ENABLED) $(GO) build -ldflags="$(LDFLAGS)" -o bin/hanzo ./cmd/hanzo
 
 run: build ## Run with iam,base,kms,gateway,o11y enabled (matches README quickstart).
 	./bin/$(BIN) --enable=iam,base,kms,gateway,o11y --brand=hanzo --domain=api.hanzo.ai
@@ -71,3 +84,6 @@ docker-push: docker ## Push the Docker image to ghcr.io. Requires docker login.
 
 clean: ## Remove built artifacts.
 	rm -rf bin
+
+native: ## Build the native flags evaluator staticlib (required for CGO=1 builds/tests).
+	cargo build --release --manifest-path native/flags/Cargo.toml

README.md

@@ -15,7 +15,7 @@ docker run -p 8080:8080 ghcr.io/hanzoai/cloud:latest
 
 ## What this is
 
-`hanzoai/cloud` is one Go binary that mounts every Hanzo subsystem (iam, kms, base, gateway, ai, commerce, vfs, mq, dns, amqp, mcp, o11y, ...) into a single multi-tenant process. Same artifact serves `api.hanzo.ai`, `api.osage.cloud`, `api.lux.cloud`, `api.zoo.cloud`, and every white-label reseller. Brand, enabled subsystems, and tenant scope are deployment configuration.
+`hanzoai/cloud` is one Go binary that mounts every Hanzo subsystem (iam, kms, base, gateway, ai, commerce, vfs, mq, dns, amqp, mcp, o11y, ...) into a single multi-org process. Same artifact serves `api.hanzo.ai`, `api.osage.cloud`, `api.lux.cloud`, `api.zoo.cloud`, and every white-label reseller. Brand, enabled subsystems, and org scope are deployment configuration.
 
 ## `hanzo` — cloud control CLI
 
@@ -61,7 +61,7 @@ Implements:
 ## Architecture
 
 ```
-                 api.{tenant}.{brand}
+                 api.{org}.{brand}
                           |
                    hanzoai/cloud (one Go binary)
                           |
@@ -69,7 +69,7 @@ Implements:
    |    iam   |   base   |   kms    |    ai    | gateway  | ...
    |  Mount() |  Mount() |  Mount() |  Mount() |  Mount() |
    +----------+----------+----------+----------+----------+
-   per-tenant SQLite (HIP-0302)   |   Hanzo IAM JWKS (HIP-0026)
+   per-org SQLite (HIP-0302)   |   Hanzo IAM JWKS (HIP-0026)
    replicate -> S3 (HIP-0107)     |   ZAP inter-subsystem RPC
 ```
 
@@ -88,7 +88,7 @@ Per [HIP-0106](https://github.com/hanzoai/HIPs/blob/main/HIPs/hip-0106-unified-h
 ## Subsystems mounted
 
 - `iam` — identity & access
-- `base` — per-tenant SQLite + extension runtimes (per HIP-0105)
+- `base` — per-org SQLite + extension runtimes (per HIP-0105)
 - `kms` — secrets
 - `commerce` — checkout, billing, pricing, invoicing (light router; NOT in PCI-DSS scope)
 - `ai` — LLM control plane / RAG / model hub / MCP management (was hanzoai/cloud pre-rename)
@@ -122,7 +122,7 @@ built on Fiber v3. The ONE Go web framework. No `.Fast` escape hatch.
 
 ## Console UI — embedded in the ONE binary
 
-The same `hanzoai/cloud` binary serves the [console](https://github.com/hanzoai/console2)
+The same `hanzoai/cloud` binary serves the [console](https://github.com/hanzoai/console)
 (`@hanzo/gui`) UI at the web root AND the `/v1` API from one process — one
 artifact, one origin, no separate console Service. The UI is compiled in via
 `//go:embed` (see `webui.go`).
@@ -130,7 +130,7 @@ artifact, one origin, no separate console Service. The UI is compiled in via
 Pipeline (in the `Dockerfile`, before `go build`):
 
 ```
-console stage  →  build console2 static bundle  →  /out
+console stage  →  build console static bundle  →  /out
       COPY --from=console /out/ → src/webui/dist/     (overlays the fallback shell)
 build stage    →  go build   →  //go:embed all:webui/dist bakes it into /cloud
 ```
@@ -153,14 +153,16 @@ even without the Node toolchain. The image build overwrites `webui/dist` with th
 real console bundle. See `webui_test.go` for the boot-and-assert tests
 (`/` → shell, deep link → shell 200, `/v1/*` → API, unmatched `/v1` → 404).
 
-> Honest current state: console2 ships 15 Next server route handlers
-> (`app/**/route.ts`) that hold KMS-sourced service tokens and mint short-lived
-> user tokens, so it emits a Node server bundle, not a static export
-> (`output: export` would fail). Until console2 exposes a `build:embed` static
-> target — or those handlers land here as native `/v1` endpoints — the image
-> embeds the fallback shell, and the separate console2 Service stays up. The Go
-> embed/serve plumbing is complete and needs no further change to light up the
-> full console the moment the static bundle exists.
+Current state: `hanzoai/console` exposes `build:embed` (`scripts/build-embed.mjs`),
+which stashes its Next server route handlers (BFF proxies that collapse to the
+cloud `/v1/*` the SPA calls same-origin), wraps the client catch-all pages for
+`output: 'export'`, neutralizes the root layout's request-time `headers()` read,
+and emits a real static export at `out/` (a ~360 KB `index.html` + `_next/`
+chunks). The image build (and `make webui`) run it and overlay `webui/dist`, so
+`//go:embed` bakes the FULL `@hanzo/gui` console into the ONE binary. The
+Dockerfile console stage FAILS HARD if that bundle is missing or degenerate —
+the placeholder shell can never silently ship to prod (escape hatch:
+`--build-arg ALLOW_PLACEHOLDER=1` for a pure-Go dev image).
 
 ## Status
 

apps/apps.go

@@ -0,0 +1,431 @@
+// Package apps is the composition root: the single, explicit list of which
+// Hanzo cloud subsystems are linked into the binary AND the order they mount in.
+//
+// Wire() returns []cloud.MountSpec in mount order (slice position == order). There
+// is no init()-registry and no order-int: adding, removing, or reordering a
+// subsystem is a one-line edit to Wire(), read top-to-bottom. cmd/cloud and
+// cmd/hanzo both call Wire() and thread the slice into cloud.Serve — the set is
+// defined ONCE, here.
+//
+// (This package must NOT live in package cloud: the subsystems import cloud for
+// Deps + Typed, so a root-package bundle would form an import cycle. As a sibling
+// subpackage it composes them without one.)
+//
+// HIP-0106: the unified cloud binary is the APPLICATION layer plus the embedded KMS
+// secrets plane and the embedded IAM identity plane ("one Go binary embeds IAM +
+// KMS + o11y"). The edge/infra tier (mcp, gateway, ingress-edge) runs as its own
+// deployments for blast-radius isolation; several application folds (iam, base,
+// commerce, captable, dataroom, sign, ingress) are STAGED — linked here but mounted
+// only when the operator names them in CLOUD_ENABLE.
+//
+// Ordering provenance: order-int ascending; ties in the exact order the
+// pre-refactor init()-registry mounted them, captured empirically from origin/main
+// @c504d2b (68 self-registering specs) and frozen by TestWireOrderMatchesFrozen
+// (wire_test.go). ai (@150) and the hanzoai/o11y module wildcard (@70) are NOT in
+// that dump: on their wave-2 tags (ai v1.805.2, o11y v1.5.12) they no longer
+// self-register, so origin/main currently DROPS them (a latent regression this
+// composition root fixes). They are wired back at their order-int slots — o11y-ext
+// kept adjacent to the in-repo o11y read-plane (@69); ai as the last /v1/* catch-all
+// before plugins (@900). Do not re-sort; edit positions deliberately.
+//
+//go:generate go run ../cmd/gen-app-cmds
+package apps
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	"github.com/hanzoai/cloud"
+	"github.com/zap-proto/zip"
+
+	// External subsystem modules. As of the atomic wave-2 bump they NO LONGER
+	// self-register (no cloud.Register in their init) — the composition root wires
+	// each one explicitly below, so removing an entry here is the ONLY way to drop it.
+	"github.com/hanzoai/ai"
+	"github.com/hanzoai/authz"
+	"github.com/hanzoai/licensing"
+	"github.com/hanzoai/metrics"
+
+	// In-repo subsystem packages (clients/*). Each exports a Mount (and, where it
+	// owns process-lifetime resources, a Shutdown); Wire references them directly.
+	"github.com/hanzoai/cloud/clients/account"
+	"github.com/hanzoai/cloud/clients/admin"
+	"github.com/hanzoai/cloud/clients/ads"
+	"github.com/hanzoai/cloud/clients/affiliates"
+	"github.com/hanzoai/cloud/clients/agent"
+	"github.com/hanzoai/cloud/clients/agents"
+	"github.com/hanzoai/cloud/clients/agentskills"
+	"github.com/hanzoai/cloud/clients/analytics"
+	"github.com/hanzoai/cloud/clients/auditlog"
+	"github.com/hanzoai/cloud/clients/authors"
+	"github.com/hanzoai/cloud/clients/automations"
+	"github.com/hanzoai/cloud/clients/base"
+	"github.com/hanzoai/cloud/clients/billing"
+	"github.com/hanzoai/cloud/clients/bots"
+	"github.com/hanzoai/cloud/clients/captable"
+	"github.com/hanzoai/cloud/clients/catalogsync"
+	"github.com/hanzoai/cloud/clients/code"
+	"github.com/hanzoai/cloud/clients/company"
+	"github.com/hanzoai/cloud/clients/connectorruntime"
+	"github.com/hanzoai/cloud/clients/content"
+	"github.com/hanzoai/cloud/clients/crm"
+	"github.com/hanzoai/cloud/clients/cron"
+	"github.com/hanzoai/cloud/clients/dataroom"
+	"github.com/hanzoai/cloud/clients/deploy"
+	"github.com/hanzoai/cloud/clients/do"
+	"github.com/hanzoai/cloud/clients/entitlements"
+	"github.com/hanzoai/cloud/clients/eval"
+	"github.com/hanzoai/cloud/clients/exec"
+	"github.com/hanzoai/cloud/clients/flags"
+	"github.com/hanzoai/cloud/clients/framework"
+	"github.com/hanzoai/cloud/clients/functions"
+	"github.com/hanzoai/cloud/clients/gateway"
+	"github.com/hanzoai/cloud/clients/git"
+	"github.com/hanzoai/cloud/clients/graph"
+	"github.com/hanzoai/cloud/clients/guide"
+	"github.com/hanzoai/cloud/clients/iam"
+	"github.com/hanzoai/cloud/clients/iam2"
+	"github.com/hanzoai/cloud/clients/ingress"
+	"github.com/hanzoai/cloud/clients/integrations"
+	"github.com/hanzoai/cloud/clients/kafka"
+	"github.com/hanzoai/cloud/clients/kms"
+	"github.com/hanzoai/cloud/clients/knowledge"
+	"github.com/hanzoai/cloud/clients/link"
+	"github.com/hanzoai/cloud/clients/marketing"
+	"github.com/hanzoai/cloud/clients/marketplace"
+	"github.com/hanzoai/cloud/clients/ml"
+	"github.com/hanzoai/cloud/clients/notify"
+	"github.com/hanzoai/cloud/clients/o11y"
+	"github.com/hanzoai/cloud/clients/paas"
+	"github.com/hanzoai/cloud/clients/plan"
+	"github.com/hanzoai/cloud/clients/platform"
+	"github.com/hanzoai/cloud/clients/plugin"
+	"github.com/hanzoai/cloud/clients/pricing"
+	"github.com/hanzoai/cloud/clients/product"
+	"github.com/hanzoai/cloud/clients/projects"
+	"github.com/hanzoai/cloud/clients/prompts"
+	"github.com/hanzoai/cloud/clients/provisioning"
+	"github.com/hanzoai/cloud/clients/pubsub"
+	"github.com/hanzoai/cloud/clients/referrals"
+	"github.com/hanzoai/cloud/clients/runtime"
+	"github.com/hanzoai/cloud/clients/sbom"
+	"github.com/hanzoai/cloud/clients/security"
+	"github.com/hanzoai/cloud/clients/settings"
+	"github.com/hanzoai/cloud/clients/sign"
+	"github.com/hanzoai/cloud/clients/social"
+	"github.com/hanzoai/cloud/clients/storage"
+	"github.com/hanzoai/cloud/clients/sync"
+	"github.com/hanzoai/cloud/clients/tasks"
+	"github.com/hanzoai/cloud/clients/team"
+	"github.com/hanzoai/cloud/clients/templates"
+	"github.com/hanzoai/cloud/clients/tools"
+	"github.com/hanzoai/cloud/clients/tracker"
+	"github.com/hanzoai/cloud/clients/treasury"
+	"github.com/hanzoai/cloud/clients/usage"
+	"github.com/hanzoai/cloud/clients/visor"
+	"github.com/hanzoai/cloud/clients/wallets"
+	"github.com/hanzoai/cloud/clients/websearch"
+	"github.com/hanzoai/cloud/clients/world"
+	"github.com/hanzoai/cloud/clients/x402"
+	"github.com/hanzoai/cloud/clients/zt"
+
+	// Framework CONTENT modules — NOT mount subsystems (they carry no HTTP surface
+	// and are absent from Wire()). Each registers its DocType fixtures and, for erp,
+	// its ledger-posting lifecycle hooks into the clients/framework DocType engine
+	// from a package init() (framework.RegisterModule) — the idiomatic
+	// register-into-a-registry pattern (cf. database/sql drivers). The framework
+	// engine is mounted (always-on, /v1/framework/*) but its module registry is
+	// populated ONLY by these blank imports. Dropping one silently strips that
+	// lane's DocTypes and hooks — for erp, the immutable ledger postings — from the
+	// binary with NO mount change and NO failing mount test. #248 dropped them;
+	// TestFrameworkContentModulesLinked now guards against a recurrence. Keep.
+	_ "github.com/hanzoai/cloud/clients/cms"
+	_ "github.com/hanzoai/cloud/clients/erp"
+	_ "github.com/hanzoai/cloud/clients/help"
+)
+
+// init wires the cross-subsystem func seams — the composition root is the one place
+// that may import two leaf subsystems at once, so a connection neither can express
+// alone lives here. git's push→index reactor calls the code index without git
+// importing code: the adapter converts git's IndexedFile to code's File and drops the
+// result (the reactor only needs success/failure). Stored once at load; invoked on
+// push, long after mount, so there is no ordering dependency. Same
+// register-into-a-registry idiom the framework content modules use above.
+func init() {
+	git.SetIndexer(func(ctx context.Context, org, billingOrg, project, repo string, files []git.IndexedFile) error {
+		in := make([]code.File, len(files))
+		for i, f := range files {
+			in[i] = code.File{Path: f.Path, Content: f.Content}
+		}
+		_, err := code.IndexFiles(ctx, org, billingOrg, project, repo, in)
+		return err
+	})
+}
+
+// identitySpec selects the ONE identity backend that owns /v1/iam/* (+ /login/oauth/*)
+// for this boot. CLOUD_IAM_IMPL=iam2 picks the clean-room iam2 (zip+orm, beego-free);
+// anything else — including unset, the production default — keeps the legacy beego
+// Casdoor embed, byte-for-byte today's behavior. The two impls register the SAME
+// absolute prefixes and therefore cannot co-mount, so selection (this func) stays
+// separate from activation (cfg.Enabled): exactly one spec occupies the identity slot
+// in Wire, preserving mount order either way. os.Getenv (not the unexported
+// cloud.getenv, which is unreachable from package apps) is the read — CLOUD_IAM_IMPL is
+// the deliberate, off-by-default opt-in that keeps iam2 inert until a canary flips it.
+func identitySpec() cloud.MountSpec {
+	if os.Getenv("CLOUD_IAM_IMPL") == "iam2" {
+		return cloud.MountSpec{Name: "iam2", Mount: iam2.Mount}
+	}
+	return cloud.MountSpec{Name: "iam", Mount: iam.Mount}
+}
+
+// Wire returns every linked subsystem as a cloud.MountSpec, in mount order. The
+// slice position IS the order: cloud.MountAll iterates it as-given, registering each
+// subsystem's teardown as a zip shutdown hook so teardown runs in reverse (LIFO).
+// Enablement is a separate axis: cloud.Serve mounts only the specs cfg.Enabled(name)
+// admits, so a STAGED subsystem is linked but inert until named.
+func Wire() []cloud.MountSpec {
+	return []cloud.MountSpec{
+		// embedded NATS :4222 + JetStream.
+		{Name: "pubsub", Mount: pubsub.Mount, Shutdown: pubsub.Shutdown},
+		// embedded Kafka adaptor :9092.
+		{Name: "kafka", Mount: kafka.Mount, Shutdown: kafka.Shutdown},
+		// /.well-known/agent-skills/* — before IAM's /.well-known/* wildcard (50).
+		{Name: "agentskills", Mount: agentskills.Mount},
+		// Insights feature-flag evaluation seam (no routes; a hot value plane).
+		{Name: "flags", Mount: flags.Mount, Shutdown: flags.Shutdown, OwnsHealth: true},
+		// Embedded KMS secrets plane /v1/kms/*. OwnsHealth: serves its own fail-closed
+		// /v1/kms/health (the generic always-ok route must not shadow it). Fails closed
+		// until the operator injects CLOUD_KMS_MASTER_KEY_REF. (Its in-process client
+		// factory is registered separately via cloud.RegisterKMSClientFactory.)
+		{Name: "kms", Mount: kms.Mount, OwnsHealth: true},
+		// hanzoai/metrics — native o11y. It declares its OWN narrow metrics.Deps (no
+		// hanzoai/cloud import), so Typed cannot adapt it; mountMetrics builds that Deps
+		// from cloud.Deps and calls metrics.Mount explicitly.
+		{Name: "metrics", Mount: mountMetrics},
+		// Embedded runtime edge (/v1/ingress/*). STAGED — edge listeners stay off unless
+		// the operator names "ingress" in CLOUD_ENABLE.
+		{Name: "ingress", Mount: ingress.Mount, Shutdown: ingress.Shutdown},
+		// SPECIFIC self-service routes (/v1/iam/{keys,onboard}, /v1/csrf, /v1/embed-status,
+		// /v1/commerce/topup/wallet). MUST mount before the IAM /v1/iam/* wildcard (50) so
+		// they win Fiber's first-match scan (framework-guaranteed since zip v1.3.0).
+		{Name: "account", Mount: account.MountAccount},
+		// Embedded IAM identity plane (/v1/iam/*, /.well-known/*, /login/oauth/*, /_/iam/*,
+		// /cas/*, /scim/*) — the identity authority, mounts before its dependents. STAGED:
+		// the operator adds "iam" to --enable only after IAM config + the fold are verified.
+		// Which IMPLEMENTATION owns these prefixes is selected by CLOUD_IAM_IMPL
+		// (identitySpec): the clean-room iam2 (zip+orm, beego-free) when =="iam2", else the
+		// legacy beego Casdoor embed — the default (unset = today's behavior, byte-for-byte).
+		// Both register the SAME absolute paths and cannot co-mount, so this is an either/or
+		// switch at this ONE slot, never a shadow prefix.
+		identitySpec(),
+		// Embedded Base app engine + viral waitlist (/v1/waitlist/*). STAGED behind
+		// CLOUD_BASE_EMBED. OwnsHealth: native /v1/base/health.
+		{Name: "base", Mount: base.Mount, Shutdown: base.Shutdown, OwnsHealth: true},
+		// The ONE observability subsystem: the in-repo o11y READ plane + runtime-handler
+		// install (o11y.SetHandler), with the hanzoai/o11y module wildcard /v1/o11y/*
+		// folded in as the TERMINAL sub-mount INSIDE o11y.MountO11y. Every specific
+		// /v1/o11y/* route registers before that wildcard, so Fiber's in-order match gives
+		// them precedence. NOT OwnsHealth: /v1/o11y/health stays the generic always-ok
+		// route (registered before MountAll), exactly as when the former module co-entry —
+		// which also set OwnsHealth=false — triggered it.
+		{Name: "o11y", Mount: o11y.MountO11y, Shutdown: o11y.ShutdownO11y},
+		{Name: "authz", Mount: authz.Mount},
+		// Embedded commerce plane /v1/commerce/*, /_/commerce/* — the hanzoai/commerce
+		// MODULE via the adapter in commerce.go (un-forked; the in-process
+		// CommerceClient is wired directly in pickCommerceClient).
+		{Name: "commerce", Mount: mountCommerce},
+		{Name: "licensing", Mount: licensing.Mount},
+		{Name: "plans", Mount: plan.Mount, OwnsHealth: true},
+		{Name: "pricing", Mount: pricing.Mount, OwnsHealth: true},
+		// /v1/s3/buckets/* + /v1/s3/health. Mounts BEFORE provisioning (120) so its static
+		// routes win over provisioning's /v1/s3/:name. OwnsHealth (real fail-closed probe).
+		{Name: "storage", Mount: storage.Mount, OwnsHealth: true},
+		// Provisioning control plane: /v1/sql,/v1/vector,/v1/datastore,/v1/kv,/v1/search,/v1/s3,/v1/docdb.
+		{Name: "provisioning", Mount: provisioning.Mount},
+		{Name: "billing", Mount: billing.Mount},
+		// CATCH-ALL /v1/billing/* + /v1/commerce/* data bridges — AFTER clients/billing
+		// (121) + the commerce embed (100). Same clients/account package as "account" (48).
+		{Name: "account-bridge", Mount: account.MountBridge},
+		{Name: "do", Mount: do.Mount},
+		{Name: "platform", Mount: platform.Mount, OwnsHealth: true},
+		{Name: "projects", Mount: projects.Mount},
+		{Name: "prompts", Mount: prompts.Mount},
+		{Name: "agents", Mount: agents.Mount, Shutdown: agents.Shutdown},
+		// The unified AI login manager registry (/v1/links). Mounts AFTER agents so
+		// a link revoke can stop the affected agent sessions in-process.
+		{Name: "link", Mount: link.Mount, Shutdown: link.Shutdown},
+		{Name: "wallets", Mount: wallets.Mount, Shutdown: ctxShutdown(wallets.Shutdown)},
+		// x402 pay-per-use: settles a signed ERC-3009 authorization to a recipient
+		// wallet through the metering spine. Mounts AFTER wallets (it resolves the
+		// recipient via wallets.ResolvePaymentTarget) and provides the Enforce
+		// middleware a marketplace applies to its priced routes.
+		{Name: "x402", Mount: x402.Mount, Shutdown: ctxShutdown(x402.Shutdown)},
+		{Name: "paas", Mount: paas.Mount, OwnsHealth: true},
+		// GitOps deploy dashboard /v1/deploy/* (the ArgoCD-grade fleet view over the
+		// operator App CRs). After paas so the release seam paas installs is registered
+		// before a gitops rollback delegates to it; owns its own /v1/deploy/health.
+		{Name: "deploy", Mount: deploy.Mount, OwnsHealth: true},
+		{Name: "functions", Mount: functions.Mount},
+		{Name: "tracker", Mount: tracker.Mount},
+		{Name: "templates", Mount: templates.Mount},
+		{Name: "framework", Mount: framework.Mount, Shutdown: ctxShutdown(framework.Shutdown)},
+		{Name: "knowledge", Mount: knowledge.Mount},
+		// Marketing content loop /v1/content/* (generate → CMS → transition → publish).
+		// After framework (its DocType store the ops read/write) + knowledge (the sibling
+		// framework lane); before the AI /v1/* catch-all so /v1/content/* resolves here.
+		// CRUD/tenancy/install are framework's; this adds the board, lifecycle transition,
+		// and the generate/publish orchestration over the zen5 + studio + social edges.
+		{Name: "content", Mount: content.Mount, Shutdown: ctxShutdown(content.Shutdown)},
+		// Reverse storefront loop: consume the commerce COMMERCE stream (product.created)
+		// → content.EnsureCatalogAsset (render the new product's ecom asset, design==slug).
+		// After content (whose EnsureCatalogAsset it drives). Inert until CLOUD_COMMERCE_NATS_URL
+		// names the NATS carrying commerce catalog events — the reverse of the forward edge.
+		{Name: "catalogsync", Mount: catalogsync.Mount, Shutdown: catalogsync.Shutdown},
+		{Name: "ml", Mount: ml.Mount, OwnsHealth: true},
+		{Name: "usage", Mount: usage.Mount},
+		{Name: "crm", Mount: crm.Mount},
+		// Native /v1/marketing/* — the in-process fold of github.com/hanzoai/marketing
+		// (per-org campaign store on Base/SQLite), twin of crm. Owns a DB handle, so
+		// its Shutdown closes it cleanly on SIGTERM (ctxShutdown adapts func() error).
+		{Name: "marketing", Mount: marketing.Mount, Shutdown: ctxShutdown(marketing.Shutdown)},
+		// Native /v1/ads/* — the net-new per-org ad-campaign store on Base/SQLite,
+		// twin of crm/marketing. Owns a DB handle, so its Shutdown closes it cleanly
+		// on SIGTERM (ctxShutdown adapts func() error).
+		{Name: "ads", Mount: ads.Mount, Shutdown: ctxShutdown(ads.Shutdown)},
+		// Native /v1/social/* — the in-process fold of the live social stack
+		// (github.com/hanzoai/social: social-backend/frontend/orchestrator, a Postiz-style
+		// scheduler), a per-org accounts+posts store on Base/SQLite, twin of crm. Owns a DB
+		// handle, so its Shutdown closes it cleanly on SIGTERM (ctxShutdown adapts func() error).
+		{Name: "social", Mount: social.Mount, Shutdown: ctxShutdown(social.Shutdown)},
+		{Name: "analytics", Mount: analytics.Mount, OwnsHealth: true},
+		{Name: "git", Mount: git.Mount},
+		// Universal sync (/v1/sync/links + engine). Registers the cloud.SyncEngine the
+		// GitHub/Gitea webhooks enqueue to; git is its first provider. Owns per-org
+		// DB handles, so its Shutdown closes them on SIGTERM.
+		{Name: "sync", Mount: sync.Mount, Shutdown: ctxShutdown(sync.Shutdown)},
+		{Name: "visor", Mount: visor.Mount},
+		// Cap table on Base via goja. STAGED behind CLOUD_ENABLE.
+		{Name: "captable", Mount: captable.Mount, Shutdown: captable.Shutdown},
+		{Name: "code", Mount: code.Mount, Shutdown: code.Shutdown},
+		{Name: "zero-trust", Mount: zt.Mount},
+		// Data rooms via goja + per-tenant Base. STAGED behind CLOUD_ENABLE. OwnsHealth.
+		{Name: "dataroom", Mount: dataroom.Mount, Shutdown: dataroom.Shutdown, OwnsHealth: true},
+		{Name: "graph", Mount: graph.Mount},
+		{Name: "security", Mount: security.Mount, Shutdown: ctxShutdown(security.Shutdown), OwnsHealth: true},
+		{Name: "integrations", Mount: integrations.Mount, Shutdown: integrations.Shutdown},
+		{Name: "sbom", Mount: sbom.Mount, OwnsHealth: true},
+		{Name: "team", Mount: team.Mount, Shutdown: ctxShutdown(team.Shutdown)},
+		{Name: "settings", Mount: settings.Mount, Shutdown: settings.Shutdown},
+		{Name: "notify", Mount: notify.Mount, OwnsHealth: true},
+		{Name: "gateway", Mount: gateway.Mount},
+		{Name: "entitlements", Mount: entitlements.Mount, Shutdown: entitlements.Shutdown},
+		{Name: "exec", Mount: exec.Mount},
+		{Name: "websearch", Mount: websearch.Mount},
+		{Name: "world", Mount: world.Mount, Shutdown: ctxShutdown(world.Shutdown)},
+		// The bot runtime's ops face (/v1/bot/*). The transport itself is domain-free;
+		// the run control plane is "bots" below.
+		{Name: "runtime", Mount: runtime.Mount},
+		{Name: "authors", Mount: authors.Mount, Shutdown: ctxShutdown(authors.Shutdown)},
+		{Name: "bots", Mount: bots.Mount},
+		{Name: "audit", Mount: auditlog.Mount},
+		{Name: "affiliates", Mount: affiliates.Mount},
+		// Hanzo Sign (e-signature) via goja + per-tenant Base. STAGED behind CLOUD_ENABLE. OwnsHealth.
+		{Name: "sign", Mount: sign.Mount, Shutdown: sign.Shutdown, OwnsHealth: true},
+		{Name: "product", Mount: product.Mount},
+		{Name: "evals", Mount: eval.Mount},
+		{Name: "treasury", Mount: treasury.Mount, Shutdown: ctxShutdown(treasury.Shutdown)},
+		{Name: "admin", Mount: admin.Mount},
+		// Launch-control (per-service waitlist mode) folded into the flags engine: the
+		// mode IS the switch waitlist.<svc>, the board is the /v1/admin/services lens,
+		// and /v1/featuregate/mode is served by flags. featuregate is no longer a mounted
+		// subsystem — it exposes only the native Enforce middleware (wired in serve.go),
+		// a consumer of flags.WaitlistModeForHost.
+		{Name: "tasks", Mount: tasks.Mount},
+		// Platform cron: durable schedules on the shared tasks engine replacing
+		// every k8s CronJob — entries are cron.hanzo.ai ConfigMaps (universe git),
+		// runs visible in the Tasks console. Mounts no routes; starts after the
+		// engine is wired.
+		{Name: "cron", Mount: cron.Mount},
+		{Name: "automations", Mount: automations.Mount, Shutdown: automations.Shutdown},
+		// Native single-connector execution (HIP-0126): runs an ActivePieces JS
+		// connector action in-process via goja (clients/connectorruntime), retiring
+		// the standalone auto Node engine. Mounts POST /v1/automations/connectors/:id/run,
+		// paired with the automations catalogue above; STAGED like the rest.
+		{Name: "connectorruntime", Mount: connectorruntime.Mount},
+		// Unified tool plane: /v1/tools/* — the ONE registry (connectors, functions,
+		// agents, skills, external MCP servers, full-cloud-control /v1 routes), per-org
+		// activation, and the unified MCP endpoint. Sources register into it from their
+		// own Mounts, so mount position is not load-bearing (List/Dispatch run at request
+		// time); placed after automations, before the zen/ai catch-all so /v1/tools wins.
+		{Name: "tools", Mount: tools.Mount, Shutdown: tools.Shutdown},
+		// Marketplace: /v1/marketplace/* — listing/discovery/install over the tool plane,
+		// with x402-priced monetized listings. Mounts after tools (it fills the price seam).
+		{Name: "marketplace", Mount: marketplace.Mount, Shutdown: marketplace.Shutdown},
+		{Name: "referrals", Mount: referrals.Mount},
+		// Business AI Guide /v1/guide/* — the interactive launch checklist engine +
+		// the agent that executes a step through the per-principal MCP plane. After
+		// automations (whose InvokeTool it drives) and referrals; before the ai
+		// catch-all. Owns per-org SQLite, so its Shutdown closes the stores.
+		{Name: "guide", Mount: guide.Mount, Shutdown: ctxShutdown(guide.Shutdown)},
+		// Hanzo Company — the incorporation + fundraising state machine
+		// (/v1/company/*). Mounts after the seams it composes (integrations for the
+		// google token custody; captable/dataroom facades) and before the /v1/* AI
+		// catch-all so its routes resolve here.
+		{Name: "company", Mount: company.Mount, Shutdown: company.Shutdown},
+		// Chat orchestrator — POST /v1/chat: ONE LLM tool-calling round over the tool
+		// plane. It COMPOSES the ai completion path (in-process, so per-org billing
+		// runs) + the unified tool registry, and splits the model's tool calls into
+		// server-executed actions and client-applied ops. Mounts BEFORE the zen/ai
+		// catch-all so /v1/chat resolves here (Fiber first-match); the ai module's
+		// beego /v1/chat alias behind its /v1/* glob is thereby shadowed, while ai
+		// keeps /v1/chat/completions + /v1/completions.
+		{Name: "agent", Mount: agent.Mount},
+		// The bare /v1/* AI catch-all — the LAST route position. Every owning subsystem above
+		// wins its own namespace (Fiber first-match); AI is the fallback for the rest of /v1/*.
+		// zen mounts as a /v1-scoped Claim middleware BEFORE ai: it routes zen* models
+		// to zen's serving layer in-process (identity, tools, 1M ladder, codec) and
+		// c.Next()s everything else to ai. zen owns the zen family; ai owns every
+		// other model and the /v1/models list. Order is load-bearing — Claim must
+		// run before ai's catch-all. (See hip-00NN.)
+		{Name: "zen", Mount: mountZen},
+		{Name: "ai", Mount: ai.Mount},
+		// Runtime wasm/proxy plugins — mounts dead last.
+		{Name: "plugins", Mount: plugin.Mount},
+	}
+}
+
+// ServeSingle is the ONE way to run a single app standalone: validate `name`
+// against Wire(), then serve exactly it (cloud.Serve with a one-name enable
+// list — MountAll mounts only it). It is the path `hanzo <name>` already uses;
+// promoting it here lets each cmd/<app>/main.go stub reuse it instead of
+// re-implementing the dispatch, so adding an app in Wire() is still the one edit
+// and its standalone binary comes for free (generated). Returns an error for an
+// unknown name rather than booting a no-op.
+func ServeSingle(name string) error {
+	if name == "" {
+		return fmt.Errorf("ServeSingle: empty app name")
+	}
+	for _, spec := range Wire() {
+		if spec.Name == name {
+			return cloud.Serve(Wire(), []string{name})
+		}
+	}
+	return fmt.Errorf("ServeSingle: unknown app %q — run `hanzo code ls`/`hanzo` for the list", name)
+}
+
+// mountMetrics adapts hanzoai/metrics into a cloud.MountFunc. Unlike the other
+// externals, metrics declares its OWN narrow Deps (Logger, DataDir, Brand) and does
+// not import hanzoai/cloud, so cloud.Typed cannot bridge it: the composition root
+// builds metrics.Deps from cloud.Deps and calls metrics.Mount explicitly here.
+func mountMetrics(a *zip.App, deps cloud.Deps) error {
+	return metrics.Mount(a, metrics.Deps{Logger: deps.Logger, DataDir: deps.DataDir, Brand: deps.Brand})
+}
+
+// ctxShutdown adapts a subsystem's zero-arg Shutdown() error to the
+// cloud.ShutdownFunc(ctx) signature. Several subsystems expose the simpler form
+// (their teardown ignores the deadline); this bridges the impedance mismatch in ONE
+// place so the Wire entries stay declarative — no inline closures.
+func ctxShutdown(f func() error) cloud.ShutdownFunc {
+	return func(context.Context) error { return f() }
+}

apps/commerce.go

@@ -0,0 +1,217 @@
+// Copyright © 2026 Hanzo AI. MIT License.
+
+// commerce.go mounts the hanzoai/commerce MODULE into the unified cloud binary
+// (HIP-0106) via the NATIVE co-residence contract: commerce registers its routes
+// directly on the HOST's zip app (EmbedConfig.App) — one router, one specificity
+// space, zero handler adaptation. This adapter narrows cloud.Deps, boots the
+// embed, and wires the in-process seams. Direction is one-way: cloud → commerce.
+//
+// PCI SCOPE. Commerce is a LIGHT ROUTER, NOT in PCI-DSS scope: tokens + intent IDs
+// only, NEVER a PAN. PAN-touching paths call the out-of-process Payments / Vault
+// (ZAP-RPC); when those clients are absent the payment handlers fail closed while
+// tenant config + admin stay served — mountCommerce warns loudly at startup.
+//
+// FAIL-SOFT. A broken Embed does NOT crash the binary: commerce degrades to a 503
+// on its own prefixes while every co-resident subsystem stays up.
+package apps
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"path/filepath"
+	"strings"
+
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/commerceclient"
+	"github.com/hanzoai/cloud/clients/commerceinproc"
+	"github.com/hanzoai/commerce"
+	commercebilling "github.com/hanzoai/commerce/api/billing"
+	commercestore "github.com/hanzoai/commerce/api/store"
+	commercemid "github.com/hanzoai/commerce/middleware"
+	"github.com/hanzoai/commerce/middleware/iammiddleware"
+	log "github.com/luxfi/log"
+	"github.com/zap-proto/zip"
+)
+
+func init() {
+	// In-process CommerceClient factory — pickCommerceClient calls it when the
+	// commerce subsystem is enabled. Registered HERE (not called directly from
+	// package cloud) because commerceclient's entitlement client imports
+	// clients/plan, which imports cloud: the hook keeps the package graph acyclic.
+	cloud.RegisterCommerceClientFactory(func(cfg *cloud.Config, _ log.Logger) cloud.CommerceClient {
+		return commerceclient.InProcessClient(cfg.Brand)
+	})
+}
+
+// commercePrefixes is every root path the commerce surface owns on the shared
+// app. Under the native SharedApp contract most of these are registered by
+// commerce's own setupRoutes; the list is the fail-closed 503 set AND the wire
+// contract commerce_prefix_test pins — the route families a session gate or the
+// AI /v1/* catch-all must never swallow:
+var commercePrefixes = []string{
+	"/v1/commerce", // public checkout + tenant + catalog + deposits
+	"/_/commerce",  // tenant-admin surface
+	// The BARE store surface: GET /v1/store/current (the org-scoped default
+	// store the admin dashboard AND the content storefront edge resolve), the
+	// per-listing upsert /v1/store/:id/listing/:slug the publish edge writes,
+	// and the public storefront reads karma.style serves at runtime. Without
+	// this owner, /v1/store/* fell through to the bare /v1/* AI catch-all —
+	// whose prepaid BALANCE gate 402'd every store read (a store-metadata read
+	// must never require an LLM balance).
+	"/v1/store",
+	// Payment-provider webhook receiver (POST /v1/billing/webhooks/:provider —
+	// Square et al). The provider's HMAC over the registered notification URL +
+	// body IS the auth; a bearer gate is impossible for provider callbacks.
+	"/v1/billing/webhooks",
+	// The platform auto-recharge sweep (PlatformOnly, POST .../run-all). The
+	// durable cron's poke carries the COMMERCE_SERVICE_TOKEN bearer; without
+	// this owner it lands on the account-bridge /v1/billing/* catch-all, whose
+	// session gate 403s a service token. (Landed 5x before the unfork — #274 —
+	// and the pin test lives beside THIS list so it can't silently regress.)
+	"/v1/billing/auto-recharge",
+}
+
+// mountCommerce boots commerce ON the shared zip app (native co-residence).
+// commerce's own setupRoutes registers /v1/commerce/* and /_/commerce/*
+// directly; the standalone-only surfaces (bare /healthz, legacy /admin SPA,
+// checkout SPA root catch-all, Listen) are skipped by the SharedApp contract.
+// This adapter registers the remaining wire-contract families with commerce's
+// own gate chains (see commercePrefixes).
+func mountCommerce(app *zip.App, deps cloud.Deps) error {
+	if app == nil {
+		return fmt.Errorf("commerce: nil zip.App")
+	}
+	if deps.Logger == nil {
+		return fmt.Errorf("commerce: nil deps.Logger")
+	}
+	lg := deps.Logger.New("subsystem", "commerce")
+	if deps.Payments == nil {
+		lg.Warn("commerce: deps.Payments is nil — payment intent paths will fail; tenant config + admin still served")
+	}
+	if deps.Vault == nil {
+		lg.Warn("commerce: deps.Vault is nil — vault charge paths unavailable; tenant config + admin still served")
+	}
+
+	// Native zip health endpoint — registered FIRST so probes answer even when
+	// the embed fails below.
+	app.Get("/_/commerce/healthz", func(c *zip.Ctx) error {
+		return c.JSON(http.StatusOK, map[string]string{"status": "ok", "service": "commerce"})
+	})
+
+	// commerce persists its per-org SQLite + `base` tree under <DataDir>/commerce,
+	// NEVER at DataDir directly: cloud already owns DataDir/orgs and DataDir/base,
+	// and commerce also writes orgs/ + base/ — sharing the root would collide two
+	// apps on the same SQLite files and corrupt them.
+	dataDir := "/var/lib/cloud/commerce"
+	if deps.DataDir != "" {
+		dataDir = filepath.Join(deps.DataDir, "commerce")
+	}
+
+	embedded, err := commerce.Embed(context.Background(), commerce.EmbedConfig{
+		DataDir: dataDir,
+		// RequireIdentity stays gateway-owned: the gateway in front of the cloud
+		// binary is the trust boundary per HIP-0026.
+		RequireIdentity: false,
+		// THE native co-residence contract: commerce registers its routes on
+		// cloud's own app — no second engine, no net/http adaptation.
+		App: app,
+		// ONE LEDGER: commerce's POST /v1/billing/credit mints into cloud's native
+		// finance ledger (the SAME per-org account the AI spend-gate reads), so a
+		// granted credit is immediately spendable. commerce.Embed calls
+		// creditledger.Set(this) before routes register; nil would leave commerce on
+		// its own datastore (standalone), but in this unified binary finance is
+		// co-resident, so we inject the finance-backed ledger adapter.
+		Ledger: ledger{},
+	})
+	if err != nil {
+		lg.Error("commerce embed failed — serving fail-closed 503 (cloud stays up)", "err", err)
+		mountCommerceFailClosed(app)
+		return nil
+	}
+
+	// The BARE /v1/store surface (see commercePrefixes). Group-scoped chain
+	// mirrors the standalone /v1 bundle: gated request context, host, IAM
+	// resolution; store.Route's own tokenRequired arg gates the CRUD.
+	storeV1 := app.Group("/v1")
+	storeV1.Use(commercemid.AddHost(), commercemid.RequestContext(), commerceErrorScope())
+	// Unconditional, exactly like the standalone bundle: IAMTokenRequired
+	// no-ops gracefully when IAM is not initialized.
+	storeV1.Use(iammiddleware.IAMTokenRequired())
+	commercestore.Route(storeV1, commercemid.TokenRequired())
+
+	// Provider webhook intake at the LIVE registered path. Chain mirrors the
+	// commerce-standalone posture: gated request context, then the sessionless
+	// HMAC-verified handler.
+	app.Post("/v1/billing/webhooks/:provider", commercemid.RequestContext(), commercebilling.HandleProviderWebhook)
+
+	// Durable-cron auto-recharge poke (COMMERCE_SERVICE_TOKEN bearer) at its
+	// live path — the bridge's session gate would 403 the poke. Same gate
+	// chain the commerce route table uses: TokenRequired authenticates the
+	// service token, PlatformOnly authorizes the mint.
+	app.Post("/v1/billing/auto-recharge/run-all",
+		commercemid.RequestContext(),
+		commercemid.TokenRequired(),
+		commercemid.PlatformOnly(),
+		commercebilling.RunAutoRechargeAllOrgs,
+	)
+
+	// In-process seams:
+	//   - commerceinproc routes the S2S billing byte-stream into the co-resident
+	//     app (the metering debit path) instead of a socket to a standalone pod.
+	//   - commerceclient reads the Embedded's datastore DIRECTLY (entitlements +
+	//     BalanceCents) — no HTTP shape at all.
+	commerceinproc.SetApp(app)
+	commerceclient.PublishEmbedded(embedded)
+
+	lg.Info("commerce embedded natively (hanzoai/commerce module on the shared zip app)",
+		"data_dir", dataDir,
+		"brand", deps.Brand,
+		"env", deps.Env,
+	)
+	return nil
+}
+
+// mountCommerceFailClosed serves an honest JSON 503 on every commerce prefix when
+// the embed cannot boot, so /v1/commerce/* answers "commerce unavailable" instead
+// commerceErrorScope confines commerce's JSON error envelope to commerce's OWN
+// routes. commercemid.ErrorHandlerJSON is a `/v1` GROUP middleware, and fiber
+// matches group middleware by PREFIX, not by the handle a route registered on —
+// so on the shared `/v1` it wraps every subsystem mounted AFTER commerce and
+// flattens their typed zip.HTTPError (403/400/…) into a blanket 500 (the store
+// envelope always renders 500). Guarded by commercePrefixes, the envelope stays on
+// commerce and every other subsystem renders its own status via zip's default
+// handler — the pre-commerce subsystems (kms, o11y, …) already do; this makes the
+// post-commerce ones (projects, agents, wallets, …) match.
+func commerceErrorScope() zip.Handler {
+	envelope := commercemid.ErrorHandlerJSON()
+	return func(c *zip.Ctx) error {
+		if hasCommercePrefix(c.Path()) {
+			return envelope(c)
+		}
+		return c.Next()
+	}
+}
+
+// hasCommercePrefix reports whether path is a commerce-owned root (an exact prefix
+// or a child of one), the SAME ownership commercePrefixes encodes for the
+// fail-closed mount.
+func hasCommercePrefix(path string) bool {
+	for _, p := range commercePrefixes {
+		if path == p || strings.HasPrefix(path, p+"/") {
+			return true
+		}
+	}
+	return false
+}
+
+// of falling through to another subsystem's catch-all.
+func mountCommerceFailClosed(app *zip.App) {
+	failed := func(c *zip.Ctx) error {
+		c.SetHeader("Content-Type", "application/json")
+		return c.Bytes(http.StatusServiceUnavailable, []byte(`{"error":"commerce unavailable","code":503}`))
+	}
+	for _, p := range commercePrefixes {
+		app.All(p+"/*", failed)
+	}
+}

apps/commerce_errorscope_test.go

@@ -0,0 +1,82 @@
+package apps
+
+import (
+	"io"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	commercemid "github.com/hanzoai/commerce/middleware"
+	"github.com/zap-proto/zip"
+)
+
+// TestCommerceErrorScope proves commerceErrorScope() confines commerce's always-500
+// JSON envelope to commerce-owned prefixes: a post-commerce subsystem route
+// (/v1/projects) that returns a typed 403 renders 403 (zip default), while a
+// commerce route (/v1/store/...) still gets commerce's envelope. Mirrors the frozen
+// order: kms (before commerce) → commerce /v1 group chain → projects + store (after).
+// Regression for the release-smoke failure where 14 post-commerce endpoints 500'd.
+func TestCommerceErrorScope(t *testing.T) {
+	app := zip.New(zip.Config{})
+
+	// kms (before commerce) — a clean 403 baseline (never wrapped by commerce).
+	app.Get("/v1/kms/health", func(c *zip.Ctx) error { return zip.ErrForbidden("kms says no") })
+
+	// commerce (position 39): the REAL group chain, now with the scoped envelope.
+	sv1 := app.Group("/v1")
+	sv1.Use(commercemid.AddHost(), commercemid.RequestContext(), commerceErrorScope())
+
+	// projects (after commerce) — typed 403; must NOT be clobbered to 500.
+	app.Get("/v1/projects", func(c *zip.Ctx) error { return zip.ErrForbidden("X-Org-Id required") })
+	// a commerce store route (after commerce) — typed 403; commerce envelope applies.
+	app.Get("/v1/store/current", func(c *zip.Ctx) error { return zip.ErrForbidden("store needs org") })
+
+	probe := func(path string) (int, string) {
+		req := httptest.NewRequest("GET", path, nil)
+		resp, err := app.Fiber().Test(req)
+		if err != nil {
+			t.Fatalf("%s: %v", path, err)
+		}
+		defer resp.Body.Close()
+		b, _ := io.ReadAll(resp.Body)
+		return resp.StatusCode, string(b)
+	}
+
+	// The invariant the scope guards: a typed zip.HTTPError (403) a subsystem returns
+	// is NEVER flattened to a 500 — not before commerce, not after it. (commerce
+	// >=1.48.10 honors the status itself; the scope keeps commerce's error handler off
+	// other subsystems' routes regardless, so a future commerce regression can't
+	// re-clobber them.)
+	for _, tc := range []struct {
+		path     string
+		wantCode int
+	}{
+		{"/v1/kms/health", 403},    // before commerce
+		{"/v1/projects", 403},      // after commerce — must NOT be clobbered to 500
+		{"/v1/store/current", 403}, // commerce's own route — its handler still honors 403
+	} {
+		code, body := probe(tc.path)
+		t.Logf("%-20s -> %d  %s", tc.path, code, body)
+		if code != tc.wantCode {
+			t.Errorf("%s: got %d, want %d (%s)", tc.path, code, tc.wantCode, body)
+		}
+		if strings.Contains(body, "\"status\":5") || code >= 500 {
+			t.Errorf("%s: a typed 403 was flattened to a 5xx (%s)", tc.path, body)
+		}
+	}
+
+	for _, p := range []struct {
+		path string
+		own  bool
+	}{
+		{"/v1/store/current", true},
+		{"/v1/commerce/checkout", true},
+		{"/v1/projects", false},
+		{"/v1/agent/presets", false},
+		{"/v1/agents", false},
+	} {
+		if got := hasCommercePrefix(p.path); got != p.own {
+			t.Errorf("hasCommercePrefix(%q) = %v, want %v", p.path, got, p.own)
+		}
+	}
+}

apps/commerce_prefix_test.go

@@ -0,0 +1,99 @@
+// Copyright © 2026 Hanzo AI. MIT License.
+
+package apps
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	luxlog "github.com/luxfi/log"
+	"github.com/zap-proto/zip"
+)
+
+// TestCommercePrefixesPinned pins the wire paths that MUST reach the commerce gin
+// handler — the ones a missing prefix silently regresses because they otherwise
+// fall through to another owner (the account-bridge /v1/billing/* catch-all, or
+// the bare /v1/* AI catch-all) that answers with the wrong contract:
+//
+//   - /v1/billing/webhooks       provider HMAC is the auth (Square et al); the
+//     session-gated bridge would 403 it.
+//   - /v1/billing/auto-recharge  the durable cron's billing-autorecharge poke
+//     (COMMERCE_SERVICE_TOKEN bearer); without the prefix the poke 403s at the
+//     bridge ("sign in to view billing") — exactly how the first live fires
+//     failed, and how the commerce unfork regressed it once already.
+//   - /v1/store                  the bare storefront surface (GET /v1/store/current +
+//     the listing upsert/reads). Dropped by the unfork, it matched no owner and fell
+//     to the /v1/* AI balance gate, which 402'd every store read for a commerce-funded
+//     org (the karma /v1/store/current outage). It is metadata, never LLM inference.
+func TestCommercePrefixesPinned(t *testing.T) {
+	want := map[string]bool{
+		"/v1/billing/auto-recharge": false,
+		"/v1/billing/webhooks":      false,
+		"/v1/store":                 false,
+	}
+	for _, p := range commercePrefixes {
+		if _, ok := want[p]; ok {
+			want[p] = true
+		}
+	}
+	for p, ok := range want {
+		if !ok {
+			t.Errorf("commercePrefixes missing %q — the route falls through to the wrong owner", p)
+		}
+	}
+}
+
+// TestStoreSurfaceRoutedToCommerceNotAIGate is the regression guard for the karma
+// GET /v1/store/current → 402 outage. Because "/v1/store" is a commercePrefix, a
+// store read is mounted on the commerce handler AHEAD of the bare /v1/* AI catch-all
+// (Wire order: commerce@191 < ai@321; Fiber matches first-registered), so it resolves
+// on commerce and NEVER reaches the LLM prepaid-balance gate that denied every store
+// read for an org funded in commerce but $0 in the ai ledger.
+func TestStoreSurfaceRoutedToCommerceNotAIGate(t *testing.T) {
+	app := zip.New(zip.Config{Logger: luxlog.New("test")})
+
+	// Mirror mountCommerce EXACTLY: app.All(prefix+"/*", handler) for each commerce
+	// prefix. The stub stands in for the embedded commerce gin handler that serves
+	// getCurrent (200 with the org's store).
+	commerce := zip.AdaptNetHTTP(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"store":{"id":"karma-store"}}`)
+	}))
+	for _, p := range commercePrefixes {
+		app.All(p+"/*", commerce)
+	}
+
+	// The bare /v1/* AI catch-all, mounted LAST like the real Wire, gates every
+	// non-exempt /v1/* path on the caller's LLM prepaid balance → 402 for a
+	// commerce-funded-but-ai-$0 org. This is the exact gate that produced the outage.
+	app.Get("/v1/*", func(c *zip.Ctx) error {
+		return c.JSON(http.StatusPaymentRequired, map[string]any{
+			"error": map[string]string{"code": "insufficient_balance"},
+		})
+	})
+
+	// The store read must resolve on the commerce handler (200), never 402 at the AI gate.
+	code, body := doReq(t, app, http.MethodGet, "/v1/store/current")
+	if code != http.StatusOK {
+		t.Fatalf("GET /v1/store/current hit the AI balance gate (got %d, body %s) — /v1/store must be a commercePrefix so it reaches commerce, not the /v1/* catch-all", code, body)
+	}
+
+	// And a sibling store path (the listing upsert the publish edge writes) is owned too.
+	if code, _ := doReq(t, app, http.MethodPut, "/v1/store/karma-store/listing/valentina"); code == http.StatusPaymentRequired {
+		t.Fatalf("PUT /v1/store/:id/listing/:slug fell through to the AI balance gate (402) — the whole store surface must be commerce-owned")
+	}
+}
+
+// doReq drives one request through the mounted app and returns (status, body).
+func doReq(t *testing.T, app *zip.App, method, path string) (int, []byte) {
+	t.Helper()
+	resp, err := app.Fiber().Test(httptest.NewRequest(method, path, nil))
+	if err != nil {
+		t.Fatalf("Test %s %s: %v", method, path, err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	b, _ := io.ReadAll(resp.Body)
+	return resp.StatusCode, b
+}

apps/framework_content_test.go

@@ -0,0 +1,33 @@
+package apps
+
+import (
+	"testing"
+
+	"github.com/hanzoai/cloud/clients/framework"
+)
+
+// TestFrameworkContentModulesLinked guards the framework CONTENT modules
+// (cms/erp/help) against silent removal. They are not mount subsystems, so they
+// never appear in Wire(); they register their DocTypes and — for erp — the
+// ledger-posting lifecycle hooks into the framework engine from a package
+// init(), reached ONLY via the blank imports in apps.go. #248 dropped
+// those imports, which stripped the erp ledger hooks from the binary with no
+// mount change and no failing mount test. This asserts the engine's module
+// registry carries each lane, so that money-adjacent regression cannot recur.
+func TestFrameworkContentModulesLinked(t *testing.T) {
+	got := make(map[string]bool)
+	for _, m := range framework.RegisteredModules() {
+		got[m] = true
+	}
+	for _, want := range []string{"cms", "erp", "help"} {
+		if !got[want] {
+			t.Errorf("framework content module %q not registered — a blank import in apps.go is missing (erp drop = ledger hooks gone from the binary)", want)
+		}
+	}
+	// The module registry proves DocTypes are linked, but erp's ledger-posting
+	// HOOKS register in a separate init() step; assert them directly so the guard
+	// survives a future split of registerHooks() out of erp's module init().
+	if framework.RegisteredHookCount() == 0 {
+		t.Error("no framework lifecycle hooks registered — erp's ledger-posting hooks (computeJournalTotals, journalEntry/paymentEntry submit+cancel, …) are not linked into the binary")
+	}
+}

apps/ledger.go

@@ -0,0 +1,81 @@
+// Copyright © 2026 Hanzo AI. MIT License.
+
+package apps
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/hanzoai/cloud/clients/finance"
+	"github.com/hanzoai/cloud/clients/money"
+	"github.com/hanzoai/cloud/types"
+	"github.com/hanzoai/commerce/billing/creditledger"
+)
+
+// ledger implements commerce's creditledger.CreditLedger over cloud's native
+// finance ledger — the SAME per-org account (finance.Current()) the AI spend-gate
+// reads and the edge meter debits. Injected at mountCommerce (EmbedConfig.Ledger),
+// it makes commerce's POST /v1/billing/credit mint into the ONE ledger: a granted
+// credit is immediately visible to the gate (one ledger, no split). This is the
+// cloud half of the one-ledger seam — commerce defines the interface, cloud
+// implements it once here, the compiler enforces the match.
+//
+// Fails closed when no finance ledger is co-resident; in the unified cloud binary
+// finance is always published, so Get() != nil ⇒ credit routes here.
+type ledger struct{}
+
+// compile-time proof the adapter satisfies commerce's exported seam.
+var _ creditledger.CreditLedger = ledger{}
+
+// Credit posts a balanced deposit (funding:platform → wallet) to the org's POOL
+// account (Subject == Org, the wallet the gate reads) and returns the ledger entry
+// id + the org's new available balance in cents. Idempotent on IdempotencyKey:
+// finance dedups on Ref, so the same key credits AT MOST once.
+func (ledger) Credit(ctx context.Context, in creditledger.CreditInput) (string, int64, error) {
+	fin := finance.Current()
+	if fin == nil {
+		return "", 0, fmt.Errorf("commerce credit: no finance ledger co-resident")
+	}
+	cur := in.Currency
+	if cur == "" {
+		cur = "usd"
+	}
+	tag := in.Tag
+	if tag == "" {
+		tag = "grant:admin" // non-cash grant bucket (finance is a single wallet; Tags is a memo)
+	}
+	id, err := fin.Deposit(ctx, types.DepositInput{
+		Org:      in.Org,
+		Subject:  in.Org, // org-pool wallet == the account the AI gate reads
+		Amount:   money.FromCents(in.AmountCents),
+		Currency: cur,
+		Notes:    in.Reason,
+		Tags:     tag,
+		Ref:      in.IdempotencyKey,
+	})
+	if err != nil {
+		return "", 0, err
+	}
+	bal, berr := fin.Balance(ctx, in.Org, in.Org, cur, false)
+	if berr != nil {
+		return id, 0, berr
+	}
+	return id, bal.Cents(), nil
+}
+
+// Balance returns the org pool's available balance in cents for currency — the
+// same read the AI gate performs, so GET /v1/billing/balance and the gate agree.
+func (ledger) Balance(ctx context.Context, org, currency string) (int64, error) {
+	fin := finance.Current()
+	if fin == nil {
+		return 0, fmt.Errorf("commerce balance: no finance ledger co-resident")
+	}
+	if currency == "" {
+		currency = "usd"
+	}
+	bal, err := fin.Balance(ctx, org, org, currency, false)
+	if err != nil {
+		return 0, err
+	}
+	return bal.Cents(), nil
+}

apps/wire_seams.go

@@ -0,0 +1,23 @@
+package apps
+
+import (
+	"github.com/hanzoai/cloud/clients/coding"
+	"github.com/hanzoai/cloud/clients/git"
+	"github.com/hanzoai/cloud/clients/integrations"
+)
+
+// wire_seams.go wires cross-subsystem in-process seams that cannot be a MountSpec
+// because they compose functions ACROSS packages that must not import each other.
+//
+// The coding orchestrator (clients/coding) needs git's CloneURL + VerifyRef, but
+// clients/git imports clients/integrations (Slack-notify), and integrations calls
+// coding — so coding -> git would cycle (integrations -> coding -> git ->
+// integrations). The composition root is the ONE place that imports all three, so
+// it assembles the coding Dispatcher here (git seams + agents/tracker/bot adapters)
+// and injects it into the Slack trigger surface. init() runs once at load, before
+// cloud.Serve; the git functions are plain reads that resolve their state at call
+// time, so no mount ordering is required. The mirror-failure logger is nil (those
+// failures are non-fatal and dropped).
+func init() {
+	integrations.SetCodingDispatcher(coding.NewDispatcher(git.CloneURL, git.VerifyRef, nil))
+}

apps/wire_test.go

@@ -0,0 +1,152 @@
+package apps
+
+import "testing"
+
+// frozen is the EXACT subsystem mount sequence of the PRE-refactor binary —
+// name, OwnsHealth, and whether it has a Shutdown — one row per mounted spec, in
+// mount order. It was captured empirically from the pre-refactor cloud binary by
+// cmd/dumpregistry (a throwaway tool that blank-imported the old init()-registry
+// and replayed the legacy MountAll bubble-sort: ascending order-int, ties broken by
+// the non-stable sort over init-registration order). The "was order N" trailing
+// comment records each spec's deleted order-int for provenance.
+//
+// This is the SOLE guardian of mount order now that the order-ints are gone:
+// Wire() must reproduce this sequence byte-for-byte (the func pointers aside), so a
+// reorder, drop, add, or flag change in the composition root fails HERE. Captured on
+// origin/main @c504d2b: 68 specs from the live init()-registry, PLUS the two the
+// wave-2 external bumps (ai v1.805.2, o11y v1.5.12) stopped self-registering — ai
+// (@150 catch-all) and the hanzoai/o11y module wildcard (@70), which main currently
+// DROPS and this PR restores. The module wildcard (order 70) is now folded in as the
+// terminal sub-mount of the in-repo o11y read plane (order 69), so "o11y" is ONE spec.
+var frozen = []struct {
+	name        string
+	ownsHealth  bool
+	hasShutdown bool
+}{
+	{"pubsub", false, true},            // was order 5
+	{"kafka", false, true},             // was order 6
+	{"agentskills", false, false},      // was order 8
+	{"flags", true, true},              // was order 9; native engine: /v1/flags health + store shutdown
+	{"kms", true, false},               // was order 10
+	{"metrics", false, false},          // was order 40
+	{"ingress", false, true},           // was order 42
+	{"account", false, false},          // was order 48
+	{"iam", false, false},              // was order 50
+	{"base", true, true},               // was order 60; per-org embed added Shutdown (#298)
+	{"o11y", false, true},              // ONE observability subsystem (was co-owned orders 69+70): read plane + the hanzoai/o11y module wildcard folded in as MountO11y's terminal sub-mount. OwnsHealth=false keeps /v1/o11y/health the generic always-ok route the module co-entry used to trigger.
+	{"authz", false, false},            // was order 70
+	{"commerce", false, false},         // was order 100
+	{"licensing", false, false},        // was order 110
+	{"plans", true, false},             // was order 111
+	{"pricing", true, false},           // was order 112
+	{"storage", true, false},           // was order 118
+	{"provisioning", false, false},     // was order 120
+	{"billing", false, false},          // was order 121
+	{"account-bridge", false, false},   // was order 122
+	{"do", false, false},               // was order 123
+	{"platform", true, false},          // was order 124
+	{"projects", false, false},         // was order 125
+	{"prompts", false, false},          // was order 126
+	{"agents", false, true},            // was order 127
+	{"link", false, true},              // new: unified AI login manager (/v1/links), after agents
+	{"wallets", false, true},           // was order 127
+	{"x402", false, true},              // new: x402 pay-per-use settlement (after wallets)
+	{"paas", true, false},              // was order 128
+	{"deploy", true, false},            // after paas (release seam), before functions
+	{"functions", false, false},        // was order 128
+	{"tracker", false, false},          // was order 129
+	{"templates", false, false},        // was order 129
+	{"framework", false, true},         // was order 129
+	{"knowledge", false, false},        // was order 130
+	{"content", false, true},           // new: marketing content loop (after knowledge)
+	{"catalogsync", false, true},       // new: reverse loop (product.created → render) after content
+	{"ml", true, false},                // was order 130
+	{"usage", false, false},            // was order 131
+	{"crm", false, false},              // was order 131
+	{"marketing", false, true},         // new: marketing domain fold (after crm)
+	{"ads", false, true},               // new: ads domain fold (after crm)
+	{"social", false, true},            // new: /v1/social fold (after crm)
+	{"analytics", true, false},         // was order 132
+	{"git", false, false},              // was order 132
+	{"sync", false, true},              // /v1/sync engine (owns per-org DB handles → Shutdown)
+	{"visor", false, false},            // was order 133
+	{"captable", false, true},          // was order 133
+	{"code", false, true},              // was order 134
+	{"zero-trust", false, false},       // was order 134
+	{"dataroom", true, true},           // was order 134
+	{"graph", false, false},            // was order 135
+	{"security", true, true},           // was order 136
+	{"integrations", false, true},      // was order 137
+	{"sbom", true, false},              // was order 137
+	{"team", false, true},              // was order 138
+	{"settings", false, true},          // was order 138
+	{"notify", true, false},            // was order 139
+	{"gateway", false, false},          // was order 139
+	{"entitlements", false, true},      // was order 139
+	{"exec", false, false},             // was order 140
+	{"websearch", false, false},        // was order 141
+	{"world", false, true},             // was order 142
+	{"runtime", false, false},          // was order 143; was "bot" until the transport was named for what it is
+	{"authors", false, true},           // was order 143
+	{"bots", false, false},             // was order 143
+	{"audit", false, false},            // was order 144
+	{"affiliates", false, false},       // was order 144
+	{"sign", true, true},               // was order 145
+	{"product", false, false},          // was order 145
+	{"evals", false, false},            // was order 145
+	{"treasury", false, true},          // was order 146
+	{"admin", false, false},            // was order 146
+	{"tasks", false, false},            // was order 147
+	{"cron", false, false},             // durable platform cron on the shared engine (post-freeze add)
+	{"automations", false, true},       // was order 148
+	{"connectorruntime", false, false}, // new: native single-connector exec via goja (after automations, HIP-0126)
+	{"tools", false, true},             // new: unified tool plane (after automations)
+	{"marketplace", false, true},       // new: marketplace over the tool plane (after tools)
+	{"referrals", false, false},        // was order 149
+	{"guide", false, true},             // new: Business AI Guide (after referrals, before ai)
+	{"company", false, true},           // new: Hanzo Company formation state machine (after guide)
+	{"agent", false, false},             // new: /v1/agent tool-calling round (before zen/ai catch-all)
+	{"zen", false, false},              // zen* claim middleware before ai's catch-all (hip-00NN)
+	{"ai", false, false},               // was order 150
+	{"plugins", false, false},          // was order 900
+}
+
+// TestWireOrderMatchesFrozen proves the composition root's mount order is
+// byte-identical to the legacy init()-registry's, position by position.
+func TestWireOrderMatchesFrozen(t *testing.T) {
+	wire := Wire()
+	if len(wire) != len(frozen) {
+		t.Fatalf("Wire() has %d specs, frozen sequence has %d", len(wire), len(frozen))
+	}
+	for i, s := range wire {
+		w := frozen[i]
+		if s.Name != w.name {
+			t.Errorf("position %d: Wire() = %q, frozen = %q (mount ORDER changed)", i, s.Name, w.name)
+		}
+		if s.OwnsHealth != w.ownsHealth {
+			t.Errorf("position %d (%s): OwnsHealth = %v, frozen = %v", i, s.Name, s.OwnsHealth, w.ownsHealth)
+		}
+		if (s.Shutdown != nil) != w.hasShutdown {
+			t.Errorf("position %d (%s): hasShutdown = %v, frozen = %v", i, s.Name, s.Shutdown != nil, w.hasShutdown)
+		}
+		if s.Mount == nil {
+			t.Errorf("position %d (%s): Mount is nil", i, s.Name)
+		}
+	}
+}
+
+// TestWireNoDuplicateEnablement guards that every subsystem name is unique: a name
+// maps 1:1 to an enable id, so a duplicate would mount two specs under one id. (The
+// former o11y co-ownership was collapsed — the module wildcard is now a sub-mount of
+// the in-repo o11y read plane — so there is no longer any exempt duplicate.)
+func TestWireNoDuplicateEnablement(t *testing.T) {
+	seen := map[string]int{}
+	for _, s := range Wire() {
+		seen[s.Name]++
+	}
+	for name, n := range seen {
+		if n > 1 {
+			t.Errorf("subsystem %q wired %d times (each enable id must be unique)", name, n)
+		}
+	}
+}

apps/zen.go

@@ -0,0 +1,304 @@
+// Copyright 2026 Hanzo AI Inc. All Rights Reserved.
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"math/big"
+	"os"
+	"strings"
+
+	aicontrollers "github.com/hanzoai/ai/controllers"
+	aiobject "github.com/hanzoai/ai/object"
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/metering"
+	cloudmoney "github.com/hanzoai/cloud/clients/money"
+	"github.com/hanzoai/cloud/clients/principal"
+	hmoney "github.com/hanzoai/money"
+	"github.com/hanzoai/zen"
+	"github.com/zap-proto/zip"
+)
+
+// mountZen mounts zen co-resident in the unified cloud binary. zen is the ONE
+// serving layer for the zen model family; it owns identity, routing, the 1M
+// context ladder, vision, tools, and the Anthropic↔OpenAI codec. ai stays the
+// auth+billing+discovery seam and the /v1/models authority; it no longer carries
+// a parallel zen table or identity prompts. (See hip-00NN.)
+//
+// zen mounts as a MIDDLEWARE, not a route owner: Claim is scoped to /v1/* and
+// routes every request whose model is a zen SKU to zen's pipeline in-process,
+// calling c.Next() for everything else so ai's /v1/* catch-all serves non-zen
+// models. ONE mount mechanism; the host owns the routes, zen owns the family.
+//
+// Billing. cloud's edge middleware (serve.go) runs IdentityMiddleware,
+// AuditTrail, ScopeRateLimit, and BillingGate app-wide BEFORE MountAll, so a
+// zen-claimed request is already authenticated, audited, and rate-limited at the
+// edge. But the edge BillingGate prices bare /v1/messages, /v1/chat/completions,
+// and /v1/embeddings at 0 (they are not under /v1/ai/ in selfMeteredPrefixes), and
+// ai's OWN in-handler metering — which used to bill zen* — is SKIPPED because
+// zen's Claim runs before ai's beego catch-all. zen therefore bills zen* itself,
+// through the same commerce metering client the edge gate uses, so there is ONE
+// billing source for zen* (never double-billed, never free): zen's Gate
+// authorizes the estimate before the upstream call, zen's Meter records the
+// exact served cost after. zen's Meter/Gate are wired here; ai's edge gate stays
+// 0 for these paths.
+//
+// Billing granularity is org / project / user, mirroring the edge gate's
+// identityFromCtx exactly:
+//   - the HOME org (principal.BillingOrg) is the balance key — who PAYS. An admin
+//     acting in another org bills the admin's home org, never the org acted on.
+//   - the project (principal.ValidatedProject) scopes spend caps; a project may
+//     carry its own billing account, resolved server-side by commerce from the
+//     org's project binding (the X-Billing-Account-Id header only attributes,
+//     never redirects spend). Empty is the org-wide default.
+//   - the user (c.User) is the actor for the audit trail.
+//
+// It is wired BEFORE ai in Wire() so Claim's c.Next() falls through to ai's
+// catch-all. zen's catalog reads its upstream keys from KMS via the Key resolver.
+func mountZen(a *zip.App, deps cloud.Deps) error {
+	z, err := zen.New(zen.Config{
+		Logger: deps.Logger,
+		Key:    zenKeyResolver(deps.KMS),
+		Tenant: cloudTenantResolver,
+		Gate:   commerceGate(deps.Metering),
+		Meter:  commerceMeter(deps.Metering),
+	})
+	if err != nil {
+		return fmt.Errorf("zen: %w", err)
+	}
+	// The one mount: Claim scoped to /v1, ahead of ai's catch-all.
+	a.Group("/v1", z.Claim())
+	return nil
+}
+
+// cloudTenantResolver is the multi-tenant billing-identity resolver: it keys
+// the balance on the validated HOME org (who pays), resolves the project scope
+// from a validated claim, and attributes the user. It mirrors the edge gate's
+// identityFromCtx so a zen* debit lands on the SAME ledger axes the edge gate
+// would have used — home-org balance, project+service scope, user actor — and a
+// masquerading admin bills their own home org, never the org acted on. A request
+// with no validated principal resolves to an empty Tenant, which zen's Valid()
+// gate refuses (no free, anonymous usage).
+func cloudTenantResolver(c *zip.Ctx) zen.Tenant {
+	home, _ := principal.BillingOrg(c)
+	project, _ := principal.ValidatedProject(c)
+	return zen.Tenant{
+		Org:        c.Org(),
+		User:       c.User(),
+		BillingOrg: home,
+		Project:    project,
+	}
+}
+
+// commerceGate is zen's pre-serve authorization backed by cloud commerce. It
+// asks the metering client whether the home org can cover the request's
+// estimated cost (priced at the tier that WILL serve, so an overflow is gated
+// against its real cost). The balance key is the home org (User); the project
+// scopes the spend cap. The estimate is exact 18-dp atto-USD from zen, folded to
+// whole cents for the balance check (a sub-cent estimate gates as "any positive
+// balance", the same contract as the edge gate's AmountCents). An unconfigured
+// metering client (nil) admits everything — zen's own tenant gate still refuses
+// anonymous traffic, and the edge BillingGate + ScopeRateLimit already ran. A
+// denied verdict returns the metering reason so zen surfaces it as its 402.
+func commerceGate(m *metering.Client) zen.Gate {
+	if m == nil || !m.Enabled() {
+		return nil
+	}
+	return func(ctx context.Context, t zen.Tenant, model string, est hmoney.Amount) error {
+		if t.BillingOrg == "" {
+			return fmt.Errorf("a billable tenant is required (no anonymous usage)")
+		}
+		// zen's estimate is an exact 18-dp USD value. Fold it to whole cents for
+		// the balance check via cloud's typed money.Amount.Cents() — a sub-cent
+		// estimate gates as 0 (any-positive-balance), matching the edge gate's
+		// AmountCents contract. The post-serve Meter debits the exact 18-dp.
+		//
+		// The fold is Cents() on the CREDIT amount, never Minor() on the zen one:
+		// Minor() renders money.USD's 2 decimals, so it returned cents that FromInt
+		// then read as atto — every estimate came back 0, and AuthorizeVerdict skips
+		// its `available >= AmountCents` check when AmountCents is 0, admitting a
+		// request of ANY size against any positive balance.
+		cents := credit(est).Cents()
+		v, err := m.AuthorizeVerdict(ctx, metering.AuthInput{
+			User:        t.BillingOrg,
+			Org:         t.BillingOrg,
+			AmountCents: cents,
+			Project:     t.Project,
+			Service:     zenService,
+		})
+		if err != nil {
+			// Balance unknown -> fail-closed (mirrors the edge gate's 503).
+			return fmt.Errorf("billing unavailable")
+		}
+		if !v.Allow {
+			if v.Reason == "spend_cap" {
+				return fmt.Errorf("spend cap reached for this scope")
+			}
+			return fmt.Errorf("insufficient balance")
+		}
+		return nil
+	}
+}
+
+// commerceMeter is zen's post-serve usage recorder backed by cloud commerce.
+// It debits the home org for the EXACT served cost as a typed money.Amount
+// (native 18-dp USD — the same precision the co-resident finance ledger holds),
+// so an exact per-token cost is never floored to cents or micros. Attributed to
+// the requested zen SKU with real token counts. The debit is detached (background
+// context) so a client disconnect cannot cancel it and recording never blocks the
+// reply — the same contract as the edge gate's post-request record. An
+// unconfigured client is a no-op (zen's logMeter still ran as the default, so the
+// audit trail is never empty).
+func commerceMeter(m *metering.Client) zen.Meter {
+	if m == nil || !m.Enabled() {
+		return nil
+	}
+	return commerceMeterImpl{m}
+}
+
+type commerceMeterImpl struct{ m *metering.Client }
+
+func (g commerceMeterImpl) Record(ctx context.Context, u zen.Usage) {
+	if u.Tenant.BillingOrg == "" {
+		return // never debit an unattributable request
+	}
+	// Beside the commerce debit, land the SAME warehouse row + gen_ai span every
+	// native ai path writes (TraceServedUsage = recordTrace WITHOUT recordUsage —
+	// the debit below is the one billing source, never doubled). zen knows its
+	// EXACT per-tier retail (Charge) and upstream COGS (Cost), so the row carries
+	// true margin (credit → nano). Without this, zen* traffic is
+	// warehouse/o11y-blind exactly where prod runs (the unified binary).
+	aicontrollers.TraceServedUsage(context.Background(), aicontrollers.ServedUsage{
+		Owner:            u.Tenant.BillingOrg,
+		User:             u.Tenant.User,
+		Model:            u.Model,
+		Provider:         zenProvider,
+		RequestID:        u.RequestID,
+		Status:           "success",
+		PromptTokens:     u.PromptTokens,
+		CompletionTokens: u.CompletionTokens,
+		BilledNano:       nano(credit(u.Charge)),
+		CostNano:         nano(credit(u.Cost)),
+	})
+	// Detached: the request context is recycled once the handler returns, so a
+	// background context carries the debit to commerce without racing the reply.
+	usage := meterUsage(u)
+	go func() { _, _ = g.m.Record(context.Background(), usage) }()
+
+	// Enso learning ledger: the embedded zen mount serves the zen catalog in-process
+	// and never reaches ai's pipeToFamily, so ai's family-event writer never runs for
+	// zen traffic. Write the SAME RoutingEvent here (source="family") through the ONE
+	// shared writer, keyed on the client-visible response id (zen.Usage.ResponseID), so
+	// zen* calls land in the same ledger — stats, world, spark retrain, and /v1/feedback
+	// all read these rows. No prompt text; no shadow (zen.Usage carries no request
+	// text — that stays the auto/enso-proxy path's job). Fire-and-forget.
+	owner := u.Tenant.Org
+	if owner == "" {
+		owner = u.Tenant.BillingOrg
+	}
+	go aiobject.RecordFamilyRouting(aiobject.FamilyRoutingInput{
+		Owner:            owner,
+		User:             u.Tenant.User,
+		RequestedModel:   u.Model,
+		RoutedModel:      u.Upstream,
+		ResponseId:       u.ResponseID,
+		PromptTokens:     u.PromptTokens,
+		CompletionTokens: u.CompletionTokens,
+		CostCents:        credit(u.Charge).Cents(),
+		RouterEndpoint:   os.Getenv("ROUTER_ENDPOINT"),
+	})
+}
+
+// meterUsage projects a served zen.Usage onto the commerce debit. It is the ONE
+// place the debit's amount is chosen, and it is pure — no ledger, no warehouse —
+// so the money property is a unit test rather than an integration.
+//
+// The amount is the RETAIL Charge: what the caller pays. Cost is the upstream
+// COGS we pay to serve the call; it is never the debit. It rides only the
+// warehouse row (CostNano), where margin = Charge − Cost stays exact. Debiting
+// Cost would collect our own COGS and book zero margin on every zen call — and
+// because the affiliate and OSS payout bases read this debit, it would fund
+// their shares out of principal. This mirrors ai, whose debit is likewise the
+// customer price (usageBilledCents), never its CostIn/CostOut COGS.
+func meterUsage(u zen.Usage) metering.Usage {
+	return metering.Usage{
+		User:             u.Tenant.BillingOrg,
+		Org:              u.Tenant.BillingOrg,
+		Actor:            u.Tenant.User,
+		Model:            u.Model,
+		Provider:         zenProvider,
+		Service:          zenService,
+		Project:          u.Tenant.Project,
+		PromptTokens:     u.PromptTokens,
+		CompletionTokens: u.CompletionTokens,
+		TotalTokens:      u.PromptTokens + u.CompletionTokens,
+		Amount:           credit(u.Charge), // exact 18-dp USD, no floor
+		RequestID:        u.RequestID,
+		Currency:         "usd",
+		Status:           "success",
+	}
+}
+
+// credit re-denominates a zen price into cloud's credit unit. It is the ONE
+// conversion at this seam — every site below goes through it, so the unit is
+// decided once rather than re-derived per call site.
+//
+// zen prices every SKU as an exact 18-dp value tagged money.USD (meter.go:
+// money.New(<18-dp decimal>, money.USD)), and cloud's credit unit is the SAME USD
+// value at 18-dp storage scale. So the conversion carries the exact decimal across
+// and changes only the minor-unit convention: no rescale, no rounding, no factor.
+// It is right by construction because the decimal is the value — the currency's
+// Decimals is a rendering convention, not part of it.
+//
+// It must NEVER go through Amount.Minor(). money.USD declares 2 decimals, so
+// Minor() rescales zen's 18-dp value to CENTS; feeding cents to the 18-dp
+// FromInt understates the debit by 10^16 (a $17.376 charge debits $0.0000000000000017),
+// and folds every sub-cent charge to a zero the ledger drops entirely.
+func credit(a hmoney.Amount) cloudmoney.Amount { return cloudmoney.FromDecimal(a.Decimal()) }
+
+// nano folds an exact credit Amount to nano-USD (1e-9) for the warehouse margin
+// columns. It takes the typed Amount rather than a bare *big.Int so the unit is
+// carried by the type: a cents integer is not a cloudmoney.Amount and can no
+// longer be passed here. A single request's cost always fits int64 at nano.
+func nano(a cloudmoney.Amount) int64 {
+	return new(big.Int).Div(a.Atto(), big.NewInt(1_000_000_000)).Int64()
+}
+
+// zenService is the commerce service axis zen* spend attributes to. zen serves
+// the same LLM product ai does, so it shares ai's service label — a per-scope
+// spend cap on "ai" binds both surfaces, and Observe reconciles them together.
+const zenService = "ai"
+
+// zenProvider is the metering provider label that marks a debit as zen-served
+// (the LLM family zen owns) for internal cost reconciliation vs the raw upstream.
+const zenProvider = "zen"
+
+// zenKeyResolver is zen's upstream-credential resolver. zen's catalog names each
+// provider's key by an env-var convention (DO_AI_API_KEY, ANTHROPIC_API_KEY, …);
+// the resolver turns that name into a concrete secret. It reads the ENVIRONMENT
+// FIRST, then falls back to KMS — the SAME order ai uses (object/kms.go: "the prod
+// hot path resolves DO_AI_API_KEY from the env before any live KMS"). The operator
+// injects these provider keys as env from the KMS-synced K8s secret
+// (cloud-api-llm-keys), so the env is the live value; the embedded KMS store is a
+// fallback that is not always seeded with the provider keys. Reading KMS-only made
+// zen send an EMPTY key whenever the store lacked it, and the upstream (DO GenAI)
+// answered 401 "Unable to authenticate you" — surfacing to the caller as a failed
+// chat while ai (which reads env) worked. Env-first fixes that with one source of
+// truth shared across both zen and ai. An empty result on both still returns "" so
+// the upstream call fails fast (never silent free usage).
+func zenKeyResolver(kms cloud.KMSClient) func(context.Context, string) string {
+	return func(ctx context.Context, envName string) string {
+		if v := strings.TrimSpace(os.Getenv(envName)); v != "" {
+			return v
+		}
+		if kms == nil {
+			return ""
+		}
+		b, err := kms.GetSecret(ctx, envName)
+		if err != nil || len(b) == 0 {
+			return ""
+		}
+		return string(b)
+	}
+}

apps/zen_test.go

@@ -0,0 +1,305 @@
+// Copyright 2026 Hanzo AI Inc. All Rights Reserved.
+
+package apps
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"sync/atomic"
+	"testing"
+
+	"github.com/hanzoai/cloud/clients/metering"
+	cloudmoney "github.com/hanzoai/cloud/clients/money"
+	"github.com/hanzoai/decimal"
+	hmoney "github.com/hanzoai/money"
+	"github.com/hanzoai/zen"
+)
+
+// usd builds an exact USD amount from a decimal string, the way zen prices a
+// call (18-dp native, never through float).
+//
+// The decimal here must be hanzoai/decimal, the one hmoney.New takes and the one
+// zen prices with — not shopspring's identically-named type. Money has exactly one
+// decimal; a second one that merely LOOKS like it is how a price silently becomes
+// a different number.
+func usd(t *testing.T, s string) hmoney.Amount {
+	t.Helper()
+	d, err := decimal.Parse(s)
+	if err != nil {
+		t.Fatalf("parse %q: %v", s, err)
+	}
+	return hmoney.New(d, hmoney.USD)
+}
+
+// zen5Usage is one served call at zen5's live rates: 1M in + 1M out, priced at
+// the family's 3× margin (retail = cost × margin).
+//
+//	in : cost 1.392 → retail 4.176
+//	out: cost 4.40  → retail 13.20
+func zen5Usage(t *testing.T) zen.Usage {
+	t.Helper()
+	return zen.Usage{
+		Tenant:           zen.Tenant{BillingOrg: "acme", User: "acme/alice", Project: "p1"},
+		Model:            "zen5",
+		PromptTokens:     1_000_000,
+		CompletionTokens: 1_000_000,
+		Charge:           usd(t, "17.376"), // 4.176 + 13.20 — what the caller pays
+		Cost:             usd(t, "5.792"),  // 1.392 + 4.40  — what we pay upstream
+		RequestID:        "req-1",
+	}
+}
+
+// dollars is the EXPECTED money, built from a plain dollar literal through cloud's
+// OWN ParseUSD — deliberately a DIFFERENT constructor than the code under test uses.
+//
+// That is what pins the UNIT. These tests once asserted meterUsage(u).Amount.Int()
+// against u.Charge.Minor(): both sides re-derived the number through the same
+// conversion, so the assertion only proved an integer round-tripped and was blind
+// to what the integer MEANT. It passed while every zen debit was 10^16 too small.
+// Comparing money to a known dollar amount cannot be blind that way: if the debit
+// is off by any factor, it is not $17.376 and the test fails.
+func dollars(t *testing.T, s string) cloudmoney.Amount {
+	t.Helper()
+	a, err := cloudmoney.ParseUSD(s)
+	if err != nil {
+		t.Fatalf("parse %q: %v", s, err)
+	}
+	return a
+}
+
+// The debit is the RETAIL Charge — what the caller pays — never the upstream
+// COGS. This is the money property: it fails if the Amount is built from
+// u.Cost. The tier is margin-bearing (retail != cost), so the two values are
+// distinguishable and the assertion cannot pass by coincidence.
+func TestMeterUsageDebitsRetailNotCost(t *testing.T) {
+	u := zen5Usage(t)
+
+	if u.Charge.Cmp(u.Cost) == 0 {
+		t.Fatal("fixture is not margin-bearing: retail == cost, so the test could not tell them apart")
+	}
+
+	got := meterUsage(u).Amount
+
+	// The known dollar value the fixture charges — a $17.376 call debits $17.376.
+	if want := dollars(t, "17.376"); got.Cmp(want) != 0 {
+		t.Errorf("debit = $%s, want the retail Charge $%s", got, want)
+	}
+	if cogs := dollars(t, "5.792"); got.Cmp(cogs) == 0 {
+		t.Errorf("debit = $%s, which is the upstream COGS — the caller must be billed retail, not our cost", got)
+	}
+}
+
+// At the family's 3× margin the debit is exactly 3× the COGS: we collect the
+// full retail price, not the wholesale one. Debiting Cost would collect 1/3 —
+// our own COGS — and book zero margin.
+func TestMeterUsageCollectsTheFullMargin(t *testing.T) {
+	u := zen5Usage(t)
+
+	debit := meterUsage(u).Amount
+	// 3x the COGS in the SAME unit as the debit — $5.792 + $5.792 + $5.792.
+	// Summing the credit Amount keeps the comparison in exact dollars; the old
+	// version multiplied Cost.Minor() (cents, 579 after rounding away 5.792's
+	// third decimal) and compared it to a debit that was not cents at all.
+	cogs := dollars(t, "5.792")
+	thriceCOGS := cogs.Add(cogs).Add(cogs)
+
+	if debit.Cmp(thriceCOGS) != 0 {
+		t.Errorf("debit = $%s, want 3x COGS = $%s (retail = cost x margin, margin 3.0)", debit, thriceCOGS)
+	}
+	if want := dollars(t, "17.376"); debit.Cmp(want) != 0 {
+		t.Errorf("debit = $%s, want $%s", debit, want)
+	}
+}
+
+// The debit carries zen's exact 18-dp value with no floor: a sub-cent call must
+// not round to zero on the way to the ledger.
+func TestMeterUsageKeepsExactSubCentCharge(t *testing.T) {
+	u := zen5Usage(t)
+	u.Charge = usd(t, "0.004176") // 1k input tokens at 4.176/MTok — well under a cent
+	u.Cost = usd(t, "0.001392")
+
+	got := meterUsage(u).Amount
+
+	if want := dollars(t, "0.004176"); got.Cmp(want) != 0 {
+		t.Errorf("debit = $%s, want the exact sub-cent charge $%s", got, want)
+	}
+	// metering.Record drops a zero Amount before it ever reaches the ledger
+	// (`if !c.Enabled() || amt.IsZero() ...  return nil`), so a floored sub-cent
+	// charge is not a small debit — it is NO DEBIT ROW, and the call is free.
+	if got.IsZero() {
+		t.Error("sub-cent charge floored to zero — Record drops a zero Amount, so the call is served free with no debit row")
+	}
+}
+
+// The unit trap this seam shipped with, pinned so it cannot come back. zen prices
+// an exact 18-dp value but tags it money.USD, whose Currency declares 2 decimals —
+// so Charge.Minor() renders CENTS, while cloudmoney.FromInt reads its argument as
+// 18-dp. Composing them silently divides every debit by 10^16.
+//
+// The tests above already fail if credit() regresses to that composition; this one
+// names WHY, and proves the two conversions are still distinguishable — an
+// assertion that cannot tell right from wrong is worse than no assertion.
+func TestCreditIsNotTheMinorUnit(t *testing.T) {
+	charge := usd(t, "17.376")
+
+	if got, want := credit(charge), dollars(t, "17.376"); got.Cmp(want) != 0 {
+		t.Fatalf("credit($17.376) = $%s, want $%s", got, want)
+	}
+
+	// The conversion that shipped, spelled out.
+	old := cloudmoney.FromAtto(charge.Minor())
+	if old.Cmp(credit(charge)) == 0 {
+		t.Fatal("FromInt(Minor()) agrees with credit() — the fixture can no longer tell the units apart, so these tests prove nothing")
+	}
+	if old.Cents() != 0 {
+		t.Errorf("FromInt(Minor()).Cents() = %d, want 0 — that this was ALWAYS 0 is what made the spend gate admit every request", old.Cents())
+	}
+}
+
+// The identity fields ride with the debit unchanged: the debit lands on the org
+// that PAYS (BillingOrg), scoped to its project, with the actor for the audit
+// trail.
+func TestMeterUsageAttribution(t *testing.T) {
+	u := zen5Usage(t)
+	m := meterUsage(u)
+
+	for _, c := range []struct{ name, got, want string }{
+		{"User", m.User, "acme"},
+		{"Org", m.Org, "acme"},
+		{"Actor", m.Actor, "acme/alice"},
+		{"Project", m.Project, "p1"},
+		{"Model", m.Model, "zen5"},
+		{"Provider", m.Provider, zenProvider},
+		{"Service", m.Service, zenService},
+		{"Currency", m.Currency, "usd"},
+	} {
+		if c.got != c.want {
+			t.Errorf("%s = %q, want %q", c.name, c.got, c.want)
+		}
+	}
+	if m.TotalTokens != 2_000_000 {
+		t.Errorf("TotalTokens = %d, want 2000000", m.TotalTokens)
+	}
+}
+
+// The spend gate must REFUSE a request whose estimate exceeds the balance.
+//
+// This is the sharpest edge of the unit bug and the reason it is a security
+// finding, not only a revenue one. AuthorizeVerdict gates size like this:
+//
+//	funded := available > 0
+//	if in.AmountCents > 0 { funded = available >= in.AmountCents }
+//
+// The estimate reached it as FromInt(est.Minor()).Cents(), which is ALWAYS 0 —
+// so the size branch was DEAD and every request rode `available > 0`. Any org
+// with a single cent of balance could draw an unbounded call. The debits were
+// dust too, so the balance never fell and the cap could never trip.
+func TestCommerceGateRefusesAnOverCapRequest(t *testing.T) {
+	const availableCents = 500 // the org holds $5.00
+
+	var authorized atomic.Bool
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/v1/billing/balance":
+			_, _ = io.WriteString(w, `{"available":`+strconv.Itoa(availableCents)+`}`)
+		case "/v1/billing/spend-alerts/authorize":
+			authorized.Store(true)
+			_, _ = io.WriteString(w, `{"allow":true}`)
+		default:
+			_, _ = io.WriteString(w, `[]`)
+		}
+	}))
+	defer srv.Close()
+
+	m, err := metering.New(metering.Config{BaseURL: srv.URL, Token: "t", Org: "acme"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	gate := commerceGate(m)
+	if gate == nil {
+		t.Fatal("gate is nil — the client must be enabled for this proof to mean anything")
+	}
+	tenant := zen.Tenant{BillingOrg: "acme", User: "acme/alice", Project: "p1"}
+
+	// $17.376 against a $5.00 balance: over cap, must be refused.
+	if err := gate(context.Background(), tenant, "zen5", usd(t, "17.376")); err == nil {
+		t.Error("gate ADMITTED a $17.376 request against a $5.00 balance — the estimate is reaching AuthorizeVerdict as 0 cents, so the size check never runs")
+	}
+
+	// The same balance must still admit a request it can actually cover, or the
+	// test would pass by refusing everything.
+	if err := gate(context.Background(), tenant, "zen5", usd(t, "1.00")); err != nil {
+		t.Errorf("gate refused an affordable $1.00 request against a $5.00 balance: %v", err)
+	}
+	if !authorized.Load() {
+		t.Error("the affordable request never reached the spend-cap authorize step")
+	}
+}
+
+// The estimate must reach the balance check as the RIGHT number of cents. The
+// refusal test above proves the gate says no; this proves it says no for the
+// right reason — that $17.376 is folded to 1738 cents, not to 0.
+func TestCommerceGateFoldsTheEstimateToRealCents(t *testing.T) {
+	for _, c := range []struct {
+		charge string
+		want   int64
+	}{
+		{"17.376", 1738}, // rounds half-away-from-zero at the cent
+		{"1000.00", 100000},
+		{"1.00", 100},
+		{"0.004176", 0}, // sub-cent gates as "any positive balance"
+	} {
+		if got := credit(usd(t, c.charge)).Cents(); got != c.want {
+			t.Errorf("$%s folds to %d cents, want %d", c.charge, got, c.want)
+		}
+	}
+}
+
+// A zero-value zen price must convert and fold without panicking. zen leaves
+// Charge/Cost as the zero Amount for a free SKU, and that value carries the
+// EMPTY currency code, not "USD" — so this also pins that credit() reads the
+// decimal rather than dispatching on the currency. The old attoToNano guarded a
+// nil *big.Int here; nano() needs no guard because decimal.Coef() returns a real
+// zero big.Int, never nil, but the property is worth holding.
+func TestCreditAndNanoHandleTheZeroPrice(t *testing.T) {
+	var free hmoney.Amount // zero value: no currency, no coefficient
+
+	got := credit(free)
+	if !got.IsZero() {
+		t.Errorf("credit(zero) = $%s, want $0", got)
+	}
+	if n := nano(got); n != 0 {
+		t.Errorf("nano(credit(zero)) = %d, want 0", n)
+	}
+	if c := got.Cents(); c != 0 {
+		t.Errorf("credit(zero).Cents() = %d, want 0", c)
+	}
+	// And a free call books no debit row, which is correct — nothing is owed.
+	u := zen5Usage(t)
+	u.Charge, u.Cost = free, free
+	if amt := meterUsage(u).Amount; !amt.IsZero() {
+		t.Errorf("free call debits $%s, want $0", amt)
+	}
+}
+
+// nano carries real money to the warehouse margin columns. It is the last place
+// the unit could silently collapse: attoToNano(cents) divided a cents integer by
+// 1e9 and produced 0 for every charge under $10,000,000.
+func TestNanoFoldsCreditToRealNano(t *testing.T) {
+	for _, c := range []struct {
+		charge string
+		want   int64
+	}{
+		{"17.376", 17_376_000_000},
+		{"5.792", 5_792_000_000},
+		{"0.004176", 4_176_000},
+		{"1000.00", 1_000_000_000_000},
+	} {
+		if got := nano(credit(usd(t, c.charge))); got != c.want {
+			t.Errorf("nano($%s) = %d, want %d", c.charge, got, c.want)
+		}
+	}
+}

audience_admin_guard_test.go

@@ -0,0 +1,50 @@
+// Copyright 2026 The Hanzo Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cloud
+
+import (
+	"os"
+	"testing"
+)
+
+// TestJWTAudiences_AcceptsAdminGuard is the operator-cockpit keystone. The
+// admin.hanzo.ai forward-auth guard is the confidential client `hanzo-admin-guard`,
+// so IAM mints its access tokens with aud=hanzo-admin-guard (each app's aud is its
+// client_id). The guard forwards that bearer to cloud-api /v1/admin/*; the identity
+// sanitizer only grants SuperAdmin (owner==adminOrg) to a VALIDATED principal, and
+// validation enforces this audience allowlist. If hanzo-admin-guard is not accepted
+// the token resolves anonymous and the SuperAdmin gate reads false -> 403, even
+// though the token's owner IS admin. Pin the client_id into the baked default so the
+// forwarded bearer validates.
+func TestJWTAudiences_AcceptsAdminGuard(t *testing.T) {
+	os.Unsetenv("CLOUD_JWT_AUDIENCES")
+	os.Unsetenv("GATEWAY_ALLOWED_AUDIENCES")
+
+	has := func(list []string, v string) bool {
+		for _, s := range list {
+			if s == v {
+				return true
+			}
+		}
+		return false
+	}
+
+	if !has(defaultJWTAudiences, "hanzo-admin-guard") {
+		t.Fatalf("defaultJWTAudiences must include hanzo-admin-guard (the admin-cockpit guard client_id); got %v", defaultJWTAudiences)
+	}
+	if !has(jwtAudiencesFromEnv(), "hanzo-admin-guard") {
+		t.Fatalf("resolved JWT audiences must include hanzo-admin-guard; got %v", jwtAudiencesFromEnv())
+	}
+}

audience_hanzo_world_test.go

@@ -0,0 +1,47 @@
+// Copyright 2026 The Hanzo Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cloud
+
+import (
+	"os"
+	"testing"
+)
+
+// TestJWTAudiences_AcceptsHanzoWorld pins the world.hanzo.ai OIDC client. IAM
+// mints world's access tokens with aud=hanzo-world (each app's aud is its
+// client_id). Those bearers hit cloud-api; the identity sanitizer only trusts a
+// principal whose aud is in this allowlist. If hanzo-world is not accepted the
+// token resolves anonymous and the analyst's api.hanzo.ai calls 401. Pin the
+// client_id into the baked default so the forwarded bearer validates.
+func TestJWTAudiences_AcceptsHanzoWorld(t *testing.T) {
+	os.Unsetenv("CLOUD_JWT_AUDIENCES")
+	os.Unsetenv("GATEWAY_ALLOWED_AUDIENCES")
+
+	has := func(list []string, v string) bool {
+		for _, s := range list {
+			if s == v {
+				return true
+			}
+		}
+		return false
+	}
+
+	if !has(defaultJWTAudiences, "hanzo-world") {
+		t.Fatalf("defaultJWTAudiences must include hanzo-world (the world.hanzo.ai client_id); got %v", defaultJWTAudiences)
+	}
+	if !has(jwtAudiencesFromEnv(), "hanzo-world") {
+		t.Fatalf("resolved JWT audiences must include hanzo-world; got %v", jwtAudiencesFromEnv())
+	}
+}

audit/audit_test.go

@@ -31,7 +31,7 @@ func openTemp(t *testing.T) (*Recorder, string) {
 	return rec, path
 }
 
-// sampleRecord is a representative security event (a global-admin org deletion).
+// sampleRecord is a representative security event (a SuperAdmin org deletion).
 func sampleRecord(action string) Record {
 	return Record{
 		Time:      time.Date(2026, 7, 1, 12, 0, 0, 0, time.UTC),
@@ -41,7 +41,7 @@ func sampleRecord(action string) Record {
 		Auth:      AuthContext{Method: "jwt", IsAdmin: true},
 		Outcome:   Outcome{Result: "success", Status: 200},
 		SourceIP:  "203.0.113.7",
-		UserAgent: "console2",
+		UserAgent: "console",
 		RequestID: "req-123",
 		Method:    "DELETE",
 		Path:      "/v1/admin/orgs/acme",

audit/query.go

@@ -18,15 +18,16 @@ import (
 // and compared against the RFC3339Nano ts column lexicographically (RFC3339 is
 // order-preserving as text, so a string range is a correct time range).
 type Filter struct {
-	Org      string    // actor_org exact match (tenant scope)
-	Sub      string    // actor_sub exact match (a specific user)
-	Action   string    // action exact match
-	Resource string    // res_type exact match
-	Result   string    // outcome result: success|deny|error
-	Since    time.Time // ts >= Since (UTC)
-	Until    time.Time // ts <= Until (UTC)
-	Limit    int       // max rows (default 100, cap 1000)
-	Offset   int       // pagination offset
+	Org        string    // actor_org exact match (tenant scope)
+	Sub        string    // actor_sub exact match (a specific user)
+	Action     string    // action exact match
+	Resource   string    // res_type exact match
+	ResourceID string    // res_id exact match (a specific resource instance)
+	Result     string    // outcome result: success|deny|error
+	Since      time.Time // ts >= Since (UTC)
+	Until      time.Time // ts <= Until (UTC)
+	Limit      int       // max rows (default 100, cap 1000)
+	Offset     int       // pagination offset
 }
 
 // Query returns records matching f, newest first, and the total count matching
@@ -93,6 +94,9 @@ func (f Filter) build() (string, []any) {
 	if f.Resource != "" {
 		add("res_type = ?", f.Resource)
 	}
+	if f.ResourceID != "" {
+		add("res_id = ?", f.ResourceID)
+	}
 	if f.Result != "" {
 		add("result = ?", f.Result)
 	}

audit/record.go

@@ -54,9 +54,9 @@ type Resource struct {
 }
 
 // AuthContext records HOW the actor authenticated and what authority they held
-// at decision time — the AC-* evidence (was this a global admin? by what
+// at decision time — the AC-* evidence (was this a SuperAdmin? by what
 // credential?). Method is "jwt" | "api-key" | "none". IsAdmin is the VALIDATED
-// global-admin bit (owner == AdminOrg), never a raw X-User-IsAdmin.
+// SuperAdmin bit (owner == AdminOrg), never a raw X-User-IsAdmin.
 type AuthContext struct {
 	Method  string `json:"method"`
 	IsAdmin bool   `json:"isAdmin"`
@@ -65,7 +65,7 @@ type AuthContext struct {
 // Outcome is the result of the action: whether it was allowed and what
 // happened. Result is "success" | "deny" | "error". Status is the HTTP status.
 // Reason is a short, non-sensitive explanation for a deny/error (e.g.
-// "global admin required", "insufficient_balance") — never a secret, never a
+// "SuperAdmin required", "insufficient_balance") — never a secret, never a
 // raw upstream error body.
 type Outcome struct {
 	Result string `json:"result"`

audit/shareability_probe_test.go

@@ -0,0 +1,107 @@
+package audit
+
+// Shareability probe (HA carve evidence, NOT a shipped feature).
+//
+// Proves the audit SQLite store is SHAREABLE by a read-only second opener while
+// the single writer is live-appending — the exact reader/writer split the HA
+// carve needs. A reader opened with ?mode=ro:
+//   - never takes the write lock, so it cannot contend with or corrupt the
+//     writer's serialized appends (no chain-head fork: the reader never appends),
+//   - sees the writer's committed records via the shared WAL (concurrent reads),
+//   - and on "promotion" a fresh RW open recovers the head from disk == the
+//     writer's last synchronously-persisted record (no gap, no fork).
+//
+// This is the audit-store analog of clients/kms TestReaderReadOnlyRoundTrip
+// (which proves the same for the KMS ZapDB store). Run:
+//   CGO_ENABLED=0 GOWORK=off GOFLAGS=-mod=mod go test ./audit/ -run Shareability -v
+
+import (
+	"context"
+	"database/sql"
+	"sync"
+	"testing"
+	"time"
+
+	_ "github.com/hanzoai/sqlite"
+)
+
+func TestShareability_ReaderSharesLiveWriterStore(t *testing.T) {
+	dir := t.TempDir()
+	path := dir + "/audit.db"
+
+	// Writer: the real serialized Recorder (WAL, MaxOpenConns(1)).
+	w, err := Open(path, nil)
+	if err != nil {
+		t.Fatalf("writer Open: %v", err)
+	}
+	defer w.Close()
+
+	const total = 200
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		for i := 0; i < total; i++ {
+			if _, err := w.Append(context.Background(), Record{Action: "POST /v1/probe"}); err != nil {
+				t.Errorf("append %d: %v", i, err)
+				return
+			}
+			time.Sleep(200 * time.Microsecond)
+		}
+	}()
+
+	// Reader: a SECOND, independent connection opened READ-ONLY against the SAME
+	// files while the writer appends. This is what a reader-role pod does.
+	ro, err := sql.Open("sqlite", "file:"+path+"?mode=ro")
+	if err != nil {
+		t.Fatalf("reader Open(ro): %v", err)
+	}
+	defer ro.Close()
+
+	// Poll the reader's view of the head while the writer runs. It must (a) never
+	// error, (b) be monotonic, and (c) eventually observe the writer's records —
+	// concurrent cross-connection RO reads over a live WAL writer.
+	var lastSeen int64 = -1
+	deadline := time.Now().Add(5 * time.Second)
+	for time.Now().Before(deadline) {
+		var maxSeq sql.NullInt64
+		if err := ro.QueryRow(`SELECT MAX(seq) FROM audit_log`).Scan(&maxSeq); err != nil {
+			t.Fatalf("reader concurrent read failed (store NOT shareable): %v", err)
+		}
+		if maxSeq.Valid {
+			if maxSeq.Int64 < lastSeen {
+				t.Fatalf("reader head regressed %d -> %d (not monotonic)", lastSeen, maxSeq.Int64)
+			}
+			lastSeen = maxSeq.Int64
+		}
+		if lastSeen >= total-1 {
+			break
+		}
+		time.Sleep(2 * time.Millisecond)
+	}
+	wg.Wait()
+
+	if lastSeen < total-1 {
+		t.Fatalf("reader never caught up: saw head %d, writer wrote %d", lastSeen, total-1)
+	}
+
+	// Writer chain is intact and complete AFTER concurrent reader activity.
+	gotCount, _ := w.Head()
+	if gotCount != total {
+		t.Fatalf("writer head count = %d, want %d", gotCount, total)
+	}
+
+	// "Promotion": a fresh RW opener (the reader taking over) recovers the head
+	// from disk == the writer's last synchronously-persisted record. No fork.
+	promoted, err := Open(path, nil)
+	if err != nil {
+		t.Fatalf("promotion RW re-open: %v", err)
+	}
+	defer promoted.Close()
+	pc, _ := promoted.Head()
+	if pc != total {
+		t.Fatalf("promoted writer recovered head %d, want %d (chain gap/fork)", pc, total)
+	}
+	t.Logf("SHAREABLE: reader observed %d records concurrently; writer chain=%d; promotion recovered head=%d",
+		lastSeen+1, gotCount, pc)
+}

audit/store.go

@@ -2,7 +2,7 @@ package audit
 
 // The append-only sink + the serialized Recorder that owns the hash-chain head.
 //
-// WHY SQLITE IS THE PRIMARY, DURABLE STORE (not ClickHouse). The chain is only
+// WHY SQLITE IS THE PRIMARY, DURABLE STORE (not datastore). The chain is only
 // tamper-EVIDENT if records are appended in a strict, gapless total order and
 // each record's PrevHash is the immediately-preceding record's Hash. That demands
 // a single serializing writer with a synchronous, read-your-write head. cloud's
@@ -14,8 +14,8 @@ package audit
 // app issues no UPDATE/DELETE, and the hash-chain detects any out-of-band edit to
 // the file. That is the compliance-grade primary control.
 //
-// THE CLICKHOUSE MIRROR IS A PROJECTION, NOT THE SOURCE OF TRUTH. The datastore
-// (ClickHouse MergeTree — insert-only, mutation-rejected at parse time) is the
+// THE DATASTORE MIRROR IS A PROJECTION, NOT THE SOURCE OF TRUTH. The datastore
+// (datastore MergeTree — insert-only, mutation-rejected at parse time) is the
 // fleet-wide OLAP mirror for long-retention, cross-deployment query. It is
 // best-effort and asynchronous: a mirror outage must never block or fail an
 // audited request, and the local chain remains the authority the verifier walks.
@@ -39,12 +39,13 @@ import (
 	// mattn+SQLCipher, encrypted at rest; !cgo → pure-Go modernc). Importing
 	// modernc directly instead would double-register "sqlite" under CGO and
 	// panic at init. Blank import registers the driver.
+	"github.com/hanzoai/cloud/cek"
 	_ "github.com/hanzoai/sqlite"
 )
 
-// Mirror is the optional OLAP projection sink (the datastore/ClickHouse). It is
+// Mirror is the optional OLAP projection sink (the datastore/datastore). It is
 // deliberately a tiny interface, not a concrete client, so the Recorder has no
-// compile-time dependency on ClickHouse and tests can supply a fake. Append is
+// compile-time dependency on datastore and tests can supply a fake. Append is
 // called best-effort, asynchronously, off the request path.
 type Mirror interface {
 	// Append writes one sealed record to the projection. A returned error is
@@ -111,7 +112,7 @@ type CheckpointFunc func(cp Checkpoint)
 // the file lock — the same single-writer discipline pricing/provisioning use,
 // here doubling as the chain's serialization guarantee.
 func Open(path string, mirror Mirror) (*Recorder, error) {
-	db, err := sql.Open("sqlite", path)
+	db, err := cek.Open(path)
 	if err != nil {
 		return nil, fmt.Errorf("audit: open sqlite %q: %w", path, err)
 	}

audit/wire.go

@@ -0,0 +1,60 @@
+package audit
+
+import "time"
+
+// Wire is the JSON shape of one audit record on the operator/console contract. It
+// is cloud's OWN record projection — richer than the IAM record it supersedes: it
+// carries the outcome, the validated auth context, and the hash-chain linkage
+// (Hash/PrevHash) so a console can show tamper-evidence per row. The JSON tags ARE
+// the contract; both the admin god-view (/v1/admin/audit) and the org-scoped trail
+// (/v1/audit) serialize this ONE shape so a single console adapter reads either.
+type Wire struct {
+	Seq        uint64 `json:"seq"`
+	Time       string `json:"time"`
+	Org        string `json:"org"`
+	Sub        string `json:"sub"`
+	Email      string `json:"email,omitempty"`
+	Action     string `json:"action"`
+	Resource   string `json:"resource"`
+	ResourceID string `json:"resourceId,omitempty"`
+	Method     string `json:"method,omitempty"`
+	Path       string `json:"path,omitempty"`
+	Result     string `json:"result"`
+	Status     int    `json:"status"`
+	Reason     string `json:"reason,omitempty"`
+	SourceIP   string `json:"sourceIp,omitempty"`
+	UserAgent  string `json:"userAgent,omitempty"`
+	RequestID  string `json:"requestId,omitempty"`
+	IsAdmin    bool   `json:"isAdmin"`
+	Auth       string `json:"authMethod,omitempty"`
+	Hash       string `json:"hash"`
+	PrevHash   string `json:"prevHash"`
+}
+
+// ToWire projects a stored Record onto the console wire shape. Time is emitted as
+// RFC3339Nano (UTC) — the same nanosecond-precise, order-preserving format the ts
+// column stores — so a client can sort/range on it verbatim.
+func (r Record) ToWire() Wire {
+	return Wire{
+		Seq:        r.Seq,
+		Time:       r.Time.UTC().Format(time.RFC3339Nano),
+		Org:        r.Actor.Org,
+		Sub:        r.Actor.Sub,
+		Email:      r.Actor.Email,
+		Action:     r.Action,
+		Resource:   r.Resource.Type,
+		ResourceID: r.Resource.ID,
+		Method:     r.Method,
+		Path:       r.Path,
+		Result:     r.Outcome.Result,
+		Status:     r.Outcome.Status,
+		Reason:     r.Outcome.Reason,
+		SourceIP:   r.SourceIP,
+		UserAgent:  r.UserAgent,
+		RequestID:  r.RequestID,
+		IsAdmin:    r.Auth.IsAdmin,
+		Auth:       r.Auth.Method,
+		Hash:       r.Hash,
+		PrevHash:   r.PrevHash,
+	}
+}

audit/wire_test.go

@@ -0,0 +1,73 @@
+package audit
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func TestToWire_MapsEveryField(t *testing.T) {
+	r := Record{
+		Seq:      7,
+		Time:     time.Date(2026, 7, 4, 12, 30, 0, 0, time.UTC),
+		Actor:    Actor{Org: "maxpower", Sub: "dave", Email: "dave@maxpower.ai"},
+		Action:   "machine.create",
+		Resource: Resource{Type: "machine", ID: "m-1"},
+		Auth:     AuthContext{Method: "jwt", IsAdmin: true},
+		Outcome:  Outcome{Result: "success", Status: 201, Reason: "ok"},
+		SourceIP: "1.2.3.4", UserAgent: "test-agent", RequestID: "req-1",
+		Method: "POST", Path: "/v1/machines",
+		PrevHash: "aa", Hash: "bb",
+	}
+	w := r.ToWire()
+	if w.Seq != 7 || w.Time != "2026-07-04T12:30:00Z" {
+		t.Fatalf("seq/time: %+v", w)
+	}
+	if w.Org != "maxpower" || w.Sub != "dave" || w.Email != "dave@maxpower.ai" {
+		t.Fatalf("actor: %+v", w)
+	}
+	if w.Action != "machine.create" || w.Resource != "machine" || w.ResourceID != "m-1" {
+		t.Fatalf("action/resource: %+v", w)
+	}
+	if w.Auth != "jwt" || !w.IsAdmin {
+		t.Fatalf("auth: %+v", w)
+	}
+	if w.Result != "success" || w.Status != 201 || w.Reason != "ok" {
+		t.Fatalf("outcome: %+v", w)
+	}
+	if w.Method != "POST" || w.Path != "/v1/machines" || w.SourceIP != "1.2.3.4" {
+		t.Fatalf("request: %+v", w)
+	}
+	if w.Hash != "bb" || w.PrevHash != "aa" {
+		t.Fatalf("chain: %+v", w)
+	}
+}
+
+func TestQuery_ResourceIDFilter(t *testing.T) {
+	rec, err := Open(":memory:", nil)
+	if err != nil {
+		t.Fatalf("Open: %v", err)
+	}
+	defer func() { _ = rec.Close() }()
+	ctx := context.Background()
+	for _, id := range []string{"m-1", "m-1", "m-2"} {
+		if _, err := rec.Append(ctx, Record{
+			Actor: Actor{Org: "o"}, Action: "machine.op",
+			Resource: Resource{Type: "machine", ID: id}, Outcome: Outcome{Result: "success"},
+		}); err != nil {
+			t.Fatalf("append: %v", err)
+		}
+	}
+	rows, total, err := rec.Query(ctx, Filter{ResourceID: "m-1"})
+	if err != nil {
+		t.Fatalf("Query: %v", err)
+	}
+	if total != 2 || len(rows) != 2 {
+		t.Fatalf("resourceId filter: want 2 rows on m-1, got %d rows total %d", len(rows), total)
+	}
+	for _, r := range rows {
+		if r.Resource.ID != "m-1" {
+			t.Fatalf("filter leaked %q", r.Resource.ID)
+		}
+	}
+}

audit_middleware.go

@@ -208,7 +208,7 @@ func actorFromCtx(c *zip.Ctx) audit.Actor {
 
 // authFromCtx records HOW the caller authenticated and the VALIDATED admin bit.
 // IsAdmin comes from c.IsAdmin() (the sanitized X-User-IsAdmin, true only for a
-// verified global admin), never a raw header. Method is inferred from the
+// verified SuperAdmin), never a raw header. Method is inferred from the
 // presence/shape of a credential: an Authorization/X-Authorization bearer or a
 // session cookie ⇒ "jwt" (or "api-key" for an opaque hk-/sk- token); none ⇒
 // "none".

audit_middleware_test.go

@@ -52,7 +52,7 @@ func newAuditApp(t *testing.T) (*zip.App, *audit.Recorder) {
 	// security event and MUST be audited even though it is a GET.
 	app.Get("/v1/admin/orgs", func(c *zip.Ctx) error {
 		if !c.IsAdmin() {
-			return zip.ErrForbidden("global admin required")
+			return zip.ErrForbidden("SuperAdmin required")
 		}
 		return c.JSON(http.StatusOK, map[string]string{"ok": "true"})
 	})
@@ -65,7 +65,7 @@ func newAuditApp(t *testing.T) (*zip.App, *audit.Recorder) {
 	return app, rec
 }
 
-// asAdmin sets the sanitized identity headers a VALIDATED global admin would
+// asAdmin sets the sanitized identity headers a VALIDATED SuperAdmin would
 // carry after SanitizeIdentity (X-User-IsAdmin=true, org=admin).
 func asAdmin(req *http.Request) {
 	req.Header.Set("X-User-Id", "z@hanzo.ai")
@@ -435,7 +435,7 @@ func TestScrubToken_RedReviewBypassClasses(t *testing.T) {
 	}
 	// Normal UAs must be byte-identical (no false scrub).
 	for _, ua := range []string{
-		"console2", "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
+		"console", "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
 		"curl/8.1.2", "Go-http-client/2.0",
 	} {
 		if got := scrubFreeText(ua); got != ua {

audit_mirror.go

@@ -1,15 +1,15 @@
 package cloud
 
-// The datastore (ClickHouse) OLAP mirror — a best-effort projection of the audit
+// The datastore OLAP mirror — a best-effort projection of the audit
 // trail for fleet-wide, long-retention, cross-deployment query. It implements
 // audit.Mirror.
 //
 // The datastore is the natural OLAP audit sink: the table is a MergeTree, which
-// is INSERT-ONLY by engine — ClickHouse rejects UPDATE/DELETE against it at parse
+// is INSERT-ONLY by engine — datastore rejects UPDATE/DELETE against it at parse
 // time ("MergeTree does not support mutations"), so the mirror is append-only at
 // the storage layer, matching the local chain's discipline. We create the table
 // idempotently on first connect (CREATE TABLE IF NOT EXISTS) and insert via the
-// canonical clickhouse-go PrepareBatch → Append → Send idiom (the same the
+// canonical datastore-go PrepareBatch → Append → Send idiom (the same the
 // provisioning subsystem uses; the driver is already in cloud's module graph, so
 // this adds no dependency).
 //
@@ -26,14 +26,14 @@ import (
 	"strings"
 	"time"
 
-	clickhouse "github.com/ClickHouse/clickhouse-go/v2"
+	datastore "github.com/hanzo-ds/go"
 	"github.com/hanzoai/cloud/audit"
 	luxlog "github.com/luxfi/log"
 )
 
-// clickhouseMirror writes audit records to a ClickHouse MergeTree table.
-type clickhouseMirror struct {
-	conn  clickhouse.Conn
+// datastoreMirror writes audit records to a datastore MergeTree table.
+type datastoreMirror struct {
+	conn  datastore.Conn
 	table string
 	log   luxlog.Logger
 }
@@ -44,25 +44,38 @@ type clickhouseMirror struct {
 //
 // Config (all from env / KMS-injected secrets, never hard-coded):
 //
-//	CLOUD_AUDIT_CLICKHOUSE_ADDR   host:9000 of the datastore native port
-//	CLOUD_AUDIT_CLICKHOUSE_DB     database (default "hanzo")
-//	CLOUD_AUDIT_CLICKHOUSE_TABLE  table (default "audit_log")
-//	CLOUD_AUDIT_CLICKHOUSE_USER   user
-//	CLOUD_AUDIT_CLICKHOUSE_PASSWORD  password (KMS-backed secret)
+//	CLOUD_AUDIT_DATASTORE_ADDR      host:9000 of the datastore native port
+//	CLOUD_AUDIT_DATASTORE_DB        database (default "hanzo")
+//	CLOUD_AUDIT_DATASTORE_TABLE     table (default "audit_log")
+//	CLOUD_AUDIT_DATASTORE_USER      user
+//	CLOUD_AUDIT_DATASTORE_PASSWORD  password (KMS-backed secret)
+//
+// auditEnv reads CLOUD_AUDIT_DATASTORE_<suffix>; auditEnvOr adds a default when unset.
+func auditEnv(suffix string) string {
+	return os.Getenv("CLOUD_AUDIT_DATASTORE_" + suffix)
+}
+
+func auditEnvOr(suffix, def string) string {
+	if v := auditEnv(suffix); v != "" {
+		return v
+	}
+	return def
+}
+
 func newAuditMirror(log luxlog.Logger) (audit.Mirror, error) {
-	addr := strings.TrimSpace(os.Getenv("CLOUD_AUDIT_CLICKHOUSE_ADDR"))
+	addr := strings.TrimSpace(auditEnv("ADDR"))
 	if addr == "" {
 		return nil, nil // no datastore configured — local chain only.
 	}
-	db := getenv("CLOUD_AUDIT_CLICKHOUSE_DB", "hanzo")
-	table := getenv("CLOUD_AUDIT_CLICKHOUSE_TABLE", "audit_log")
+	db := auditEnvOr("DB", "hanzo")
+	table := auditEnvOr("TABLE", "audit_log")
 
-	conn, err := clickhouse.Open(&clickhouse.Options{
+	conn, err := datastore.Open(&datastore.Options{
 		Addr: []string{addr},
-		Auth: clickhouse.Auth{
+		Auth: datastore.Auth{
 			Database: db,
-			Username: os.Getenv("CLOUD_AUDIT_CLICKHOUSE_USER"),
-			Password: os.Getenv("CLOUD_AUDIT_CLICKHOUSE_PASSWORD"),
+			Username: auditEnv("USER"),
+			Password: auditEnv("PASSWORD"),
 		},
 		DialTimeout: 5 * time.Second,
 	})
@@ -77,7 +90,7 @@ func newAuditMirror(log luxlog.Logger) (audit.Mirror, error) {
 	}
 
 	qualified := db + "." + table
-	m := &clickhouseMirror{conn: conn, table: qualified, log: log}
+	m := &datastoreMirror{conn: conn, table: qualified, log: log}
 	if err := m.ensureTable(ctx); err != nil {
 		_ = conn.Close()
 		return nil, err
@@ -92,7 +105,7 @@ func newAuditMirror(log luxlog.Logger) (audit.Mirror, error) {
 // = insert-only (mutations rejected at parse time). Partitioned by month and
 // ordered for the (org, time) query pattern; seq + hash are carried so the OLAP
 // copy is cross-checkable against the local chain.
-func (m *clickhouseMirror) ensureTable(ctx context.Context) error {
+func (m *datastoreMirror) ensureTable(ctx context.Context) error {
 	ddl := fmt.Sprintf(`
 CREATE TABLE IF NOT EXISTS %s (
   seq        UInt64,
@@ -130,7 +143,7 @@ ORDER BY (actor_org, ts, seq)`, m.table)
 // still payload-bearing) diffs out of the fleet warehouse minimizes the blast
 // radius of a warehouse compromise. The full record (with diffs) lives only in
 // the local, access-controlled chain.
-func (m *clickhouseMirror) Append(ctx context.Context, r audit.Record) error {
+func (m *datastoreMirror) Append(ctx context.Context, r audit.Record) error {
 	batch, err := m.conn.PrepareBatch(ctx, "INSERT INTO "+m.table+` (
   seq, ts, actor_org, actor_sub, actor_email, action, res_type, res_id,
   auth_method, is_admin, result, status, reason, source_ip, user_agent,
@@ -159,7 +172,7 @@ func (m *clickhouseMirror) Append(ctx context.Context, r audit.Record) error {
 // series and alerts on any regression. Best-effort; a failure is dropped by the
 // Recorder (the structured log carries the same digest). Implements
 // audit.CheckpointSink.
-func (m *clickhouseMirror) Checkpoint(ctx context.Context, cp audit.Checkpoint) error {
+func (m *datastoreMirror) Checkpoint(ctx context.Context, cp audit.Checkpoint) error {
 	if err := m.ensureCheckpointTable(ctx); err != nil {
 		return err
 	}
@@ -177,7 +190,7 @@ func (m *clickhouseMirror) Checkpoint(ctx context.Context, cp audit.Checkpoint)
 // ensureCheckpointTable creates the append-only checkpoint digest table. A plain
 // MergeTree ordered by time — the monitor reads the latest rows and checks that
 // count never decreases.
-func (m *clickhouseMirror) ensureCheckpointTable(ctx context.Context) error {
+func (m *datastoreMirror) ensureCheckpointTable(ctx context.Context) error {
 	ddl := fmt.Sprintf(`
 CREATE TABLE IF NOT EXISTS %s_checkpoints (
   ts    DateTime64(3, 'UTC'),

audit_serve.go

@@ -15,6 +15,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strings"
 	"time"
 
 	"github.com/hanzoai/cloud/audit"
@@ -22,7 +23,7 @@ import (
 )
 
 // buildAuditRecorder constructs the audit Recorder from cfg: the append-only
-// SQLite chain at {DataDir}/audit.db plus a best-effort ClickHouse OLAP mirror
+// SQLite chain at {DataDir}/audit.db plus a best-effort datastore OLAP mirror
 // when a datastore is configured. Returns (nil, nil) only when the trail is
 // explicitly disabled — the caller then wires a no-op middleware.
 func buildAuditRecorder(cfg *Config, logger luxlog.Logger) (*audit.Recorder, error) {
@@ -57,6 +58,18 @@ func buildAuditRecorder(cfg *Config, logger luxlog.Logger) (*audit.Recorder, err
 		return nil, fmt.Errorf("open audit store: %w", err)
 	}
 
+	// PER-SHARD audit under horizontal scale. The trail lives at {DataDir}/audit.db on
+	// THIS pod's own RWO PVC, so under shard routing each pod's chain covers ONLY the
+	// tenants routed to it (its shard) — and org-scoped audit queries route to the
+	// owning shard where those records live. Soundness: the chain is a per-FILE hash
+	// chain whose head is recovered at open; because no two pods share the file, there
+	// is no cross-pod head to fork (the very failure that pinned cloud to replicas:1 was
+	// two pods on ONE audit file). Integrity is preserved WITHIN each partition; a
+	// deployment-wide view is the union of the N per-shard chains. The shard id is
+	// stamped on the AU-9 checkpoint stream below so the external tail-truncation monitor
+	// tracks N heads (one per shard) rather than expecting a single global head.
+	shard := strings.TrimSpace(cfg.ShardSelf) // "" when single-pod — a harmless empty tag
+
 	// AU-9 tail-truncation anchor: emit a periodic head-digest checkpoint to the
 	// append-only observability log (and, when a mirror supports it, an
 	// independent digest store). An external o11y monitor compares consecutive
@@ -67,7 +80,7 @@ func buildAuditRecorder(cfg *Config, logger luxlog.Logger) (*audit.Recorder, err
 	if logger != nil {
 		rec.StartCheckpoints(interval, func(cp audit.Checkpoint) {
 			logger.Info("audit_head_checkpoint",
-				"count", cp.Count, "head", cp.Head, "ts", cp.Time.Format(time.RFC3339Nano))
+				"shard", shard, "count", cp.Count, "head", cp.Head, "ts", cp.Time.Format(time.RFC3339Nano))
 		})
 	} else {
 		rec.StartCheckpoints(interval, nil)
@@ -76,7 +89,7 @@ func buildAuditRecorder(cfg *Config, logger luxlog.Logger) (*audit.Recorder, err
 	if logger != nil {
 		count, head := rec.Head()
 		logger.Info("audit trail ready (tamper-evident, append-only)",
-			"store", dbPath, "records", count, "head", head,
+			"store", dbPath, "shard", shard, "records", count, "head", head,
 			"mirror", mirror != nil, "checkpoint_interval", interval.String())
 	}
 	return rec, nil

auth_apikey.go

@@ -0,0 +1,173 @@
+// Copyright 2026 Hanzo AI Inc. All Rights Reserved.
+
+package cloud
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+	"sync"
+	"time"
+)
+
+// The identity boundary (SanitizeIdentity) validates a JWT and mints the identity
+// headers every subsystem trusts. An opaque API key (hk-/sk-/pk-/fw_/hz_) is not a
+// JWT, so it yielded no principal — and a subsystem that gates on the minted
+// identity (zen's billing gate) refused an API-key request as anonymous, though the
+// key is a first-class credential. keyResolver closes that gap: it turns a key into
+// the SAME idClaims a JWT yields, so ONE minting path serves both credentials and
+// key auth and session auth can never disagree on who a request is.
+
+// keyResolver turns an opaque API key into the principal it authenticates, or nil
+// for an unknown key or an unconfigured resolver (the request stays anonymous — a
+// bad key never grants trust).
+type keyResolver interface {
+	resolve(ctx context.Context, key string) *idClaims
+}
+
+// iamKeys resolves an `hk-` key against IAM's get-user?accessKey endpoint,
+// authenticating as the confidential `hanzo-console` client (the credential
+// clients/account already uses). The resolved user is exactly what a JWT for that
+// user carries, so SanitizeIdentity mints identical headers for a key and a session.
+// A brief cache keeps the hot auth path off the network; it caches misses too, so a
+// bad key cannot hammer IAM.
+type iamKeys struct {
+	base   string
+	auth   string // client_secret_basic, or "" when unconfigured
+	http   *http.Client
+	cache  cache[string, *idClaims]
+}
+
+// newIAMKeys reads the same IAM env clients/account does. With no confidential
+// credential it returns a resolver that resolves nothing (keys stay anonymous —
+// never a fabricated principal), so a deployment lacking the credential is safe.
+func newIAMKeys() *iamKeys {
+	return &iamKeys{
+		base:  iamHost(),
+		auth:  iamCred(),
+		http:  &http.Client{Timeout: 5 * time.Second},
+		cache: newCache[string, *idClaims](60 * time.Second),
+	}
+}
+
+// iamHost is the standalone IAM origin cloud talks to; iamCred is the service
+// credential (client_secret_basic) it presents — the ONE IAM identity, shared by
+// the API-key resolver here and the /v1/iam edge (iam_edge.go), so both
+// authenticate to IAM the same way. Empty cred → a deployment lacking the
+// credential stays safe (the caller treats "" as unconfigured).
+func iamHost() string { return strings.TrimRight(env("IAM_URL", "IAM_INTERNAL_URL"), "/") }
+
+func iamCred() string {
+	id := strings.TrimSpace(os.Getenv("IAM_MINT_CLIENT_ID"))
+	secret := strings.TrimSpace(os.Getenv("IAM_MINT_CLIENT_SECRET"))
+	if id == "" || secret == "" {
+		return ""
+	}
+	return "Basic " + base64.StdEncoding.EncodeToString([]byte(id+":"+secret))
+}
+
+func env(names ...string) string {
+	for _, n := range names {
+		if v := strings.TrimSpace(os.Getenv(n)); v != "" {
+			return v
+		}
+	}
+	return ""
+}
+
+func (k *iamKeys) resolve(ctx context.Context, key string) *idClaims {
+	if k.auth == "" || k.base == "" || key == "" {
+		return nil
+	}
+	if c, ok := k.cache.get(key); ok {
+		return c // may be a cached nil — a valid "anonymous" answer
+	}
+	c := k.lookup(ctx, key)
+	k.cache.put(key, c)
+	return c
+}
+
+// lookup performs the authenticated get-user?accessKey call and maps the user row
+// to idClaims. Any failure (unreachable, denied, unknown key) yields nil. Name is
+// both the username IAM's owner/name lookups parse and the id fallback: a key has
+// no UUID subject, so userID() falls through to name — the gateway's historical
+// X-User-Id==name behavior the owner/name path expects.
+func (k *iamKeys) lookup(ctx context.Context, key string) *idClaims {
+	u := k.base + "/v1/iam/get-user?" + url.Values{"accessKey": {key}}.Encode()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
+	if err != nil {
+		return nil
+	}
+	req.Header.Set("Authorization", k.auth)
+	req.Header.Set("Accept", "application/json")
+	resp, err := k.http.Do(req)
+	if err != nil {
+		return nil
+	}
+	defer resp.Body.Close()
+	raw, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return nil
+	}
+	var env struct {
+		Status string `json:"status"`
+		Data   *struct {
+			Owner   string `json:"owner"`
+			Name    string `json:"name"`
+			Email   string `json:"email"`
+			IsAdmin bool   `json:"isAdmin"`
+		} `json:"data"`
+	}
+	if json.Unmarshal(raw, &env) != nil || env.Status != "ok" || env.Data == nil {
+		return nil
+	}
+	if strings.TrimSpace(env.Data.Owner) == "" {
+		return nil
+	}
+	return &idClaims{
+		Owner:             strings.TrimSpace(env.Data.Owner),
+		Name:              strings.TrimSpace(env.Data.Name),
+		PreferredUsername: strings.TrimSpace(env.Data.Name),
+		Email:             strings.TrimSpace(env.Data.Email),
+		IsAdmin:           env.Data.IsAdmin,
+	}
+}
+
+// cache is a tiny concurrency-safe TTL map — one generic type for every
+// resolve-once-reuse-briefly lookup, so no bespoke cache is hand-rolled per caller.
+type cache[K comparable, V any] struct {
+	ttl time.Duration
+	mu  sync.Mutex
+	m   map[K]entry[V]
+}
+
+type entry[V any] struct {
+	v   V
+	exp time.Time
+}
+
+func newCache[K comparable, V any](ttl time.Duration) cache[K, V] {
+	return cache[K, V]{ttl: ttl, m: make(map[K]entry[V])}
+}
+
+func (c *cache[K, V]) get(k K) (V, bool) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	e, ok := c.m[k]
+	if !ok || time.Now().After(e.exp) {
+		var zero V
+		return zero, false
+	}
+	return e.v, true
+}
+
+func (c *cache[K, V]) put(k K, v V) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.m[k] = entry[V]{v: v, exp: time.Now().Add(c.ttl)}
+}

auth_apikey_test.go

@@ -0,0 +1,86 @@
+// Copyright 2026 Hanzo AI Inc. All Rights Reserved.
+
+package cloud
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+)
+
+// iamKeys.lookup maps an IAM get-user?accessKey row to the SAME idClaims a JWT
+// yields, so the one minting path serves a key and a session identically.
+func TestIAMKeysLookup(t *testing.T) {
+	var gotKey, gotAuth string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotKey = r.URL.Query().Get("accessKey")
+		gotAuth = r.Header.Get("Authorization")
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"status":"ok","data":{"owner":"hanzo","name":"z","email":"z@hanzo.ai","isAdmin":true}}`))
+	}))
+	defer srv.Close()
+
+	k := &iamKeys{base: srv.URL, auth: "Basic test", http: srv.Client(), cache: newCache[string, *idClaims](time.Minute)}
+	c := k.resolve(context.Background(), "hk-abc123")
+	if c == nil {
+		t.Fatal("resolve returned nil for a valid key")
+	}
+	if c.Owner != "hanzo" || c.Name != "z" || c.Email != "z@hanzo.ai" || !c.IsAdmin {
+		t.Fatalf("claims = %+v, want owner=hanzo name=z email=z@hanzo.ai isAdmin=true", c)
+	}
+	// The key is passed as accessKey and the confidential credential is sent.
+	if gotKey != "hk-abc123" {
+		t.Errorf("IAM got accessKey=%q, want hk-abc123", gotKey)
+	}
+	if gotAuth != "Basic test" {
+		t.Errorf("IAM got auth=%q, want the confidential Basic credential", gotAuth)
+	}
+	// userID falls through to name (a key has no UUID subject) — the owner/name
+	// path IAM's privileged lookups expect.
+	if c.userID() != "z" || c.username() != "z" {
+		t.Errorf("userID=%q username=%q, want both z", c.userID(), c.username())
+	}
+}
+
+// An unconfigured resolver (no confidential credential) resolves nothing, so an
+// API key stays anonymous rather than mis-resolved.
+func TestIAMKeysUnconfigured(t *testing.T) {
+	k := &iamKeys{base: "http://iam", auth: "", cache: newCache[string, *idClaims](time.Minute)}
+	if c := k.resolve(context.Background(), "hk-abc"); c != nil {
+		t.Fatalf("unconfigured resolver returned %+v, want nil", c)
+	}
+}
+
+// An unknown key (IAM status != ok) resolves to nil — a bad key never grants trust.
+func TestIAMKeysUnknown(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte(`{"status":"error","msg":"Unauthorized operation"}`))
+	}))
+	defer srv.Close()
+	k := &iamKeys{base: srv.URL, auth: "Basic test", http: srv.Client(), cache: newCache[string, *idClaims](time.Minute)}
+	if c := k.resolve(context.Background(), "hk-bad"); c != nil {
+		t.Fatalf("unknown key resolved to %+v, want nil", c)
+	}
+}
+
+// The cache serves a resolved key without a second IAM call (and caches a miss too,
+// so a bad key cannot hammer IAM).
+func TestIAMKeysCache(t *testing.T) {
+	var calls int
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		calls++
+		_, _ = w.Write([]byte(`{"status":"ok","data":{"owner":"hanzo","name":"z"}}`))
+	}))
+	defer srv.Close()
+	k := &iamKeys{base: srv.URL, auth: "Basic test", http: srv.Client(), cache: newCache[string, *idClaims](time.Minute)}
+	for i := 0; i < 3; i++ {
+		if k.resolve(context.Background(), "hk-x") == nil {
+			t.Fatal("resolve nil")
+		}
+	}
+	if calls != 1 {
+		t.Fatalf("IAM called %d times, want 1 (cached)", calls)
+	}
+}

auth_identity.go

@@ -31,6 +31,8 @@ import (
 
 	gojose "github.com/go-jose/go-jose/v4"
 	"github.com/go-jose/go-jose/v4/jwt"
+
+	"github.com/hanzoai/cloud/clients/principal"
 )
 
 // idClaims is the subset of Hanzo IAM JWT claims the identity sanitizer needs.
@@ -38,15 +40,31 @@ import (
 type idClaims struct {
 	jwt.Claims
 
-	Owner             string `json:"owner"`              // org slug (the tenant)
+	Owner             string `json:"owner"`              // org slug (the org)
+	Project           string `json:"project"`            // org SUB-SCOPE within owner (empty ⟹ default project)
 	Name              string `json:"name"`               // display name (id fallback)
 	PreferredUsername string `json:"preferred_username"` // id fallback
 	Email             string `json:"email"`
 	IsAdmin           bool   `json:"isAdmin"`
 }
 
+// mintedProject returns the project id to stamp into X-Project-Id, or "" when the
+// header must be OMITTED. The project rides in the validated JWT `project` claim,
+// scoped to the caller's org exactly like `owner` — trusted, not forgeable. The
+// default project (absent claim, or the literal principal.DefaultProject) mints
+// nothing, so X-Project-Id is present iff a non-default project is in scope. This
+// mirrors the edge (iamauth.Claims.MintedProject) byte-for-byte, so the in-binary
+// path binds the same header the gateway would.
+func (c *idClaims) mintedProject() string {
+	if principal.IsDefaultProject(c.Project) {
+		return ""
+	}
+	return strings.TrimSpace(c.Project)
+}
+
 // userID resolves the canonical user id: sub, then preferred_username, then
-// name. IAM may leave sub empty.
+// name. IAM may leave sub empty. This is the STABLE identifier (a UUID when IAM
+// sets sub) stamped as X-User-Id and consumed as the attribution key everywhere.
 func (c *idClaims) userID() string {
 	if c.Subject != "" {
 		return c.Subject
@@ -57,6 +75,21 @@ func (c *idClaims) userID() string {
 	return c.Name
 }
 
+// username resolves the IAM USERNAME — the `name` half of the `<owner>/<name>`
+// key IAM's privileged ops (mint-user-keys, get-user) parse. Prefers the `name`
+// claim (IAM's canonical username, e.g. "z"), then preferred_username. It NEVER
+// returns the subject: sub is a UUID, and `<owner>/<uuid>` fails IAM's
+// GetOwnerAndNameFromId user lookup ("password or code is incorrect"). This is
+// the distinct-from-userID() value stamped as X-User-Name so the direct-Bearer
+// path builds owner/name correctly — the gateway historically minted
+// X-User-Id==name, which userID() (sub-first) breaks on the in-binary path.
+func (c *idClaims) username() string {
+	if c.Name != "" {
+		return c.Name
+	}
+	return c.PreferredUsername
+}
+
 // jwtSigAlgs is the accepted signature-algorithm allowlist passed to
 // jwt.ParseSigned (go-jose v4 requires it explicitly). RSA + ECDSA + PSS, the
 // set IAM may sign with — never "none".
@@ -78,6 +111,7 @@ type identityValidator struct {
 	issuers   []string
 	audiences []string
 	cache     *jwksCache
+	keys      keyResolver // resolves an opaque API key to a principal; nil ⟹ keys stay anonymous
 }
 
 // newIdentityValidator builds a validator whose trusted-issuer set is the primary
@@ -89,11 +123,12 @@ func newIdentityValidator(issuer, jwksURL string, audiences []string, ttl time.D
 		issuers:   trustedIssuers(issuer),
 		audiences: audiences,
 		cache:     newJWKSCache(jwksURL, ttl),
+		keys:      newIAMKeys(),
 	}
 }
 
-// kmsMachineAudSuffix is the fixed suffix of a per-tenant PaaS-KMS sync machine
-// identity's audience. Each tenant's KMS sync authenticates as a dedicated,
+// kmsMachineAudSuffix is the fixed suffix of a per-org PaaS-KMS sync machine
+// identity's audience. Each org's KMS sync authenticates as a dedicated,
 // NON-shared IAM application named "<org>-platform-kms" (Organization=<org>,
 // client_credentials grant), so IAM stamps the token's aud == the app's own
 // clientId == "<org>-platform-kms" (a non-shared app's audience is its clientId,
@@ -101,18 +136,18 @@ func newIdentityValidator(issuer, jwksURL string, audiences []string, ttl time.D
 // (object/token_oauth.go GetClientCredentialsToken sets owner = app.Organization).
 //
 // That audience is, by construction, absent from CLOUD_JWT_AUDIENCES — it is
-// per-tenant, not a fixed app — which is EXACTLY why the sync stayed pending: the
+// per-org, not a fixed app — which is EXACTLY why the sync stayed pending: the
 // machine token failed the audience check below, SanitizeIdentity treated it as
 // anonymous, and the /v1/kms org-scope guard 403'd it before the store. The fix is
 // to accept this one audience, but ONLY when it equals the token's OWN owner claim
 // plus this suffix, so it certifies "the KMS sync identity for its own org" and
-// grants nothing wider. Tenancy is still enforced downstream by owner at the guard
+// grants nothing wider. Org-scoping is still enforced downstream by owner at the guard
 // (owner == :org); this only lets a legitimately-minted, owner-scoped machine token
-// clear validation. A per-tenant application means a per-tenant clientSecret — never
-// a shared platform-wide reader, which would be a cross-tenant hole.
+// clear validation. A per-org application means a per-org clientSecret — never
+// a shared platform-wide reader, which would be a cross-org hole.
 const kmsMachineAudSuffix = "-platform-kms"
 
-// kmsMachineAudience returns the audience a tenant org's PaaS-KMS sync identity
+// kmsMachineAudience returns the audience an org org's PaaS-KMS sync identity
 // carries: "<owner>-platform-kms". An empty owner yields empty — no machine
 // audience is ever granted to an org-less token (fail closed).
 func kmsMachineAudience(owner string) string {
@@ -122,13 +157,13 @@ func kmsMachineAudience(owner string) string {
 	return owner + kmsMachineAudSuffix
 }
 
-// isKMSMachinePrincipal reports whether a validated token is a per-tenant KMS-sync
+// isKMSMachinePrincipal reports whether a validated token is a per-org KMS-sync
 // machine identity: its audience set contains the owner-bound machine audience
 // (<owner>-platform-kms). Such a principal is a client_credentials machine identity
-// scoped to exactly one org. SanitizeIdentity uses this to DENY it global-admin
+// scoped to exactly one org. SanitizeIdentity uses this to DENY it SuperAdmin
 // authority even if it somehow carries isAdmin=true and owner==adminOrg, so V6's
 // audience widening can never be leveraged (via an admin-org machine token) into a
-// cross-tenant read. Its org-scoped data access is unaffected — this gates ONLY the
+// cross-org read. Its org-scoped data access is unaffected — this gates ONLY the
 // admin grant, keeping the machine path decoupled from admin inside cloud (rather
 // than resting on the external invariant "IAM never stamps isAdmin=true on a
 // machine-aud token", which cloud cannot see or enforce).
@@ -179,12 +214,12 @@ func (v *identityValidator) validate(raw string) (*idClaims, error) {
 		return nil, fmt.Errorf("untrusted issuer %q", claims.Issuer)
 	}
 	// Audience: the static allowlist (CLOUD_JWT_AUDIENCES / brand app client_ids)
-	// PLUS the per-tenant PaaS-KMS sync machine audience bound to THIS token's own
+	// PLUS the per-org PaaS-KMS sync machine audience bound to THIS token's own
 	// owner (<owner>-platform-kms). The machine audience is added only when the
 	// allowlist is active (non-empty — always so in production) and only for the
-	// token's own org, so accepting it never widens tenancy: the /v1/kms guard still
+	// token's own org, so accepting it never widens org-scoping: the /v1/kms guard still
 	// gates on owner == :org. Without this, a real client_credentials machine token
-	// (aud == its per-tenant clientId, never in the allowlist) fails here and the
+	// (aud == its per-org clientId, never in the allowlist) fails here and the
 	// sync silently stays pending — the activation blocker.
 	expected := jwt.Expected{}
 	if len(v.audiences) > 0 {

auth_identity_kms_test.go

@@ -1,14 +1,14 @@
 package cloud
 
-// V6 (the activation blocker) — the identity validator must accept a per-tenant
-// PaaS-KMS sync machine token: a client_credentials JWT whose aud is the tenant's
-// own IAM application clientId "<owner>-platform-kms" (a per-tenant value, NEVER in
+// V6 (the activation blocker) — the identity validator must accept a per-org
+// PaaS-KMS sync machine token: a client_credentials JWT whose aud is the org's
+// own IAM application clientId "<owner>-platform-kms" (a per-org value, NEVER in
 // CLOUD_JWT_AUDIENCES) — but ONLY when that audience is bound to the token's OWN
 // owner claim. Before the fix the machine token failed the audience check,
 // SanitizeIdentity resolved anonymous, and the /v1/kms guard 403'd it, so the sync
 // silently stayed pending. These are white-box unit tests of validate() itself;
 // the end-to-end proof through SanitizeIdentity + the real guard lives in
-// clients/kmssvc (v6_aud_e2e_test.go). Reuses the jwksServer/signWith/tokenClaims
+// clients/kms (v6_aud_e2e_test.go). Reuses the jwksServer/signWith/tokenClaims
 // helpers from middleware_identity_test.go (same package).
 
 import (

auto_routing_billing_test.go

@@ -0,0 +1,102 @@
+// Copyright 2023-2025 Hanzo AI Inc. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cloud
+
+// Auto-routing billing binding at the cloud edge.
+//
+// The ai subsystem serves a virtual `auto`/`zen-router` model: it resolves the
+// request to a concrete model id BEFORE pricing/billing, meters its own LLM
+// token cost to commerce keyed on the SERVED model, and reports that id via the
+// `X-Routed-Model` response header (and the response body `model` field).
+//
+// The cloud edge must therefore do two things for an `auto` request, both
+// verified here end-to-end through the real BillingGate + DefaultPrice:
+//  1. NOT re-price it by the (virtual) request model — /v1/ai/* is self-metered,
+//     so the edge gate delegates all LLM billing to the ai subsystem. That
+//     subsystem bills the resolved model, so `auto` bills as what served it.
+//  2. Pass the `X-Routed-Model` header through untouched, so the model the
+//     client sees reported is exactly the model that was billed.
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/zap-proto/zip"
+)
+
+// TestAutoRoutingBillsAsResolvedModel drives an `auto` chat request through the
+// real edge gate (BillingGate + DefaultPrice) in front of a handler that
+// simulates the ai subsystem after it resolved auto→zen4-coder.
+func TestAutoRoutingBillsAsResolvedModel(t *testing.T) {
+	fc := &fakeCommerce{balanceBody: `{"available":5000}`}
+	srv := fc.server(t)
+	m := mustClient(t, srv.URL, false /* fail-closed */)
+
+	app := zip.New(zip.Config{})
+	// The genuine edge gate with the genuine price function.
+	app.Use(BillingGate(m, DefaultPrice))
+	// Stand-in for the mounted ai subsystem: auto already resolved to zen4-coder,
+	// which it reports on the header + body (and meters itself — not modeled here).
+	app.Post("/v1/ai/chat/completions", func(c *zip.Ctx) error {
+		c.SetHeader("X-Routed-Model", "zen4-coder")
+		return c.JSON(http.StatusOK, map[string]string{"model": "zen4-coder"})
+	})
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/ai/chat/completions",
+		strings.NewReader(`{"model":"auto","messages":[{"role":"user","content":"refactor this"}]}`))
+	req.Header.Set("X-Org-Id", "hanzo")
+	req.Header.Set("X-User-Id", "alice")
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := app.Fiber().Test(req)
+	if err != nil {
+		t.Fatalf("Test request: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200", resp.StatusCode)
+	}
+
+	// (1) The edge did NOT bill: /v1/ai/* is self-metered (DefaultPrice 0), so the
+	// gate short-circuits before Authorize/Record. Billing is delegated to the ai
+	// subsystem, which meters the RESOLVED model — never the virtual `auto`.
+	// (Give any erroneous async Record a moment to land before asserting zero.)
+	if fc.usages() != 0 {
+		t.Fatalf("edge recorded %d usage(s) for /v1/ai/*, want 0 (self-metered by ai)", fc.usages())
+	}
+	if waitFor(func() bool { return fc.usages() > 0 }, 50*time.Millisecond) {
+		t.Fatalf("edge double-billed an ai request (usages=%d): auto must be billed by the ai meter, not the edge", fc.usages())
+	}
+
+	// (2) Header pass-through: the resolved model the ai meter billed reaches the
+	// client, so what's reported == what's billed.
+	if got := resp.Header.Get("X-Routed-Model"); got != "zen4-coder" {
+		t.Errorf("X-Routed-Model = %q, want zen4-coder (must pass through the edge)", got)
+	}
+}
+
+// TestDefaultPriceAiPathModelAgnostic documents the binding at the pricing layer:
+// the edge price for the ai chat path is 0 regardless of the request model, so
+// `auto` and a concrete model are treated identically — the ai subsystem's own
+// per-token meter (keyed on the resolved model) is the single source of the
+// charge. Path-based, never request-model-based, pricing is what makes `auto`
+// bill as the model that served it.
+func TestDefaultPriceAiPathModelAgnostic(t *testing.T) {
+	if got := priceForPath(t, "/v1/ai/chat/completions"); got != 0 {
+		t.Errorf("DefaultPrice(/v1/ai/chat/completions) = %d, want 0 — ai self-meters the resolved model", got)
+	}
+}

body_limit_test.go

@@ -0,0 +1,62 @@
+package cloud
+
+import "testing"
+
+// The context window is a BODY-SIZE fact, not just a model fact.
+//
+// A chat request carries its whole prompt in the request body, so the edge's
+// BodyLimit is a hard ceiling on the context window no matter what the model
+// catalog advertises. The zip/fiber framework default is 4 MiB; a 1M-token
+// prompt serializes to roughly 4.3 MB of JSON (measured on prod: 2 MB of body
+// carried 466,148 prompt tokens, ~4.5 bytes/token). Left at the default, every
+// 1M-context route — deepseek-v4-pro, and anything glm-5.2 overflows into once
+// a prompt passes its 262,144 cap — was unreachable: fasthttp rejected the body
+// before any handler ran and answered the opaque 400 "Error when parsing
+// request", which reads like a malformed payload rather than a size cap.
+//
+// This pins the ceiling above a real 1M-token prompt so the regression cannot
+// come back silently.
+
+// oneMillionTokenBody is a conservative byte estimate for a 1M-token prompt.
+// Measured ~4.5 bytes/token; 4.3 keeps the floor conservative.
+const oneMillionTokenBody = 1_000_000 * 43 / 10 // ~4.3 MB
+
+// zipFrameworkDefault is the zip/fiber BodyLimit applied when Config.BodyLimit
+// is left at 0 (zip.go: `if cfg.BodyLimit == 0 { cfg.BodyLimit = 4 << 20 }`) —
+// the exact cap that made 1M context unreachable.
+const zipFrameworkDefault = 4 << 20
+
+// LoadConfig registers process flags, so it may only be called ONCE per test
+// binary (a second call panics with "flag redefined"). Both invariants are
+// therefore asserted against a single load, and the env-override path is
+// exercised through the getenvInt helper that LoadConfig itself uses.
+func TestBodyLimit_FitsAMillionTokenPrompt(t *testing.T) {
+	cfg := LoadConfig()
+
+	if cfg.BodyLimit == 0 || cfg.BodyLimit == zipFrameworkDefault {
+		t.Fatalf("BodyLimit = %d — this is the zip/fiber 4 MiB default, the exact cap "+
+			"that made 1M context unreachable", cfg.BodyLimit)
+	}
+
+	if cfg.BodyLimit <= oneMillionTokenBody {
+		t.Fatalf("BodyLimit = %d bytes, which cannot hold a 1M-token prompt (~%d bytes); "+
+			"the 1M-context models would 400 with fasthttp's opaque "+
+			"%q", cfg.BodyLimit, oneMillionTokenBody, "Error when parsing request")
+	}
+}
+
+func TestBodyLimit_EnvOverride(t *testing.T) {
+	t.Setenv("GATEWAY_BODY_LIMIT", "33554432") // 32 MiB
+
+	if got := getenvInt("GATEWAY_BODY_LIMIT", 16<<20); got != 32<<20 {
+		t.Fatalf("getenvInt(GATEWAY_BODY_LIMIT) = %d, want %d — the limit must stay tunable", got, 32<<20)
+	}
+}
+
+func TestBodyLimit_DefaultsWhenEnvUnset(t *testing.T) {
+	t.Setenv("GATEWAY_BODY_LIMIT", "")
+
+	if got := getenvInt("GATEWAY_BODY_LIMIT", 16<<20); got != 16<<20 {
+		t.Fatalf("getenvInt fallback = %d, want the 16 MiB default", got)
+	}
+}

brand.go

@@ -24,8 +24,16 @@ type BrandInfo struct {
 	// IAMIssuer is the OIDC issuer (JWKS source) for this brand — the value the
 	// JWT `iss` claim must equal and whose /v1/iam/.well-known/jwks signs tokens.
 	IAMIssuer string
-	// Domain is the brand's primary marketing/site domain (for response scoping).
+	// Domain is the brand's primary marketing/site domain (for response scoping
+	// and base-URL derivation, e.g. api.<Domain>).
 	Domain string
+	// AltDomains are additional registrable domains that ALSO belong to this
+	// brand, used ONLY for hostname→brand white-label detection (BrandForHostOK).
+	// A brand's real serving surfaces span more than its marketing domain — the
+	// cloud console runs on <brand>.cloud hosts (console.lux.cloud,
+	// console.zoo.cloud), and a request Host there must brand as Lux/Zoo, never
+	// fall through to Hanzo. Base-URL/issuer scoping still uses the primary Domain.
+	AltDomains []string
 }
 
 // brands is the brand→IAM registry. Keys are the canonical brand IDs accepted
@@ -38,13 +46,13 @@ type BrandInfo struct {
 // https://hanzo.id/v1/iam/.well-known/jwks (iam.hanzo.ai is a routing alias, not
 // the issuer), and the cloud CLI already defaults to hanzo.id. Pinning
 // iam.hanzo.ai here would fail the issuer check on every real token, anonymizing
-// every principal — global admin would 403 platform-wide (fail-secure, but
+// every principal — SuperAdmin would 403 platform-wide (fail-secure, but
 // broken). lux/zoo/pars already correctly point at their own .id issuers.
 var brands = map[string]BrandInfo{
-	"hanzo":    {ID: "hanzo", IAMIssuer: "https://hanzo.id", Domain: "hanzo.ai"},
-	"lux":      {ID: "lux", IAMIssuer: "https://lux.id", Domain: "lux.network"},
-	"zoo":      {ID: "zoo", IAMIssuer: "https://zoo.id", Domain: "zoo.ngo"},
-	"pars":     {ID: "pars", IAMIssuer: "https://pars.id", Domain: "pars.network"},
+	"hanzo":    {ID: "hanzo", IAMIssuer: "https://hanzo.id", Domain: "hanzo.ai", AltDomains: []string{"hanzo.cloud", "hanzo.app"}},
+	"lux":      {ID: "lux", IAMIssuer: "https://lux.id", Domain: "lux.network", AltDomains: []string{"lux.cloud"}},
+	"zoo":      {ID: "zoo", IAMIssuer: "https://zoo.id", Domain: "zoo.ngo", AltDomains: []string{"zoo.network", "zoo.cloud"}},
+	"pars":     {ID: "pars", IAMIssuer: "https://pars.id", Domain: "pars.network", AltDomains: []string{"pars.ai"}},
 	"bootnode": {ID: "bootnode", IAMIssuer: "https://id.bootno.de", Domain: "bootno.de"},
 }
 
@@ -65,6 +73,57 @@ func IssuerForBrand(id string) string {
 	return BrandFor(id).IAMIssuer
 }
 
+// BrandForHostOK resolves a request Host to a brand id from the same `brands`
+// registry, mirroring the hostname→brand semantics of platform.ts's
+// getWhiteLabelBrand: a Host at or under a brand's Domain (api.lux.network,
+// lux.network) is that brand. The port is stripped and the compare is
+// case-insensitive; the longest matching Domain wins so a nested brand domain is
+// never shadowed by a shorter one. ok is false when NO brand domain matches, so
+// the caller can choose its own fallback (the deployment brand) rather than
+// silently emitting Hanzo branding on, say, a Zoo pod hit with an odd Host.
+func BrandForHostOK(host string) (string, bool) {
+	host = strings.ToLower(strings.TrimSpace(host))
+	if i := strings.IndexByte(host, ':'); i >= 0 {
+		host = host[:i]
+	}
+	// A fully-qualified Host may carry a trailing root dot ("api.lux.network.");
+	// strip it so the suffix match still resolves the brand instead of failing to
+	// neutral.
+	host = strings.TrimSuffix(host, ".")
+	best, bestLen := "", -1
+	for id, b := range brands {
+		for _, d := range append([]string{b.Domain}, b.AltDomains...) {
+			d = strings.ToLower(d)
+			if d == "" {
+				continue
+			}
+			if (host == d || strings.HasSuffix(host, "."+d)) && len(d) > bestLen {
+				best, bestLen = id, len(d)
+			}
+		}
+	}
+	return best, best != ""
+}
+
+// BrandForHost is BrandForHostOK with the Hanzo default for an unmatched Host.
+func BrandForHost(host string) string {
+	if b, ok := BrandForHostOK(host); ok {
+		return b
+	}
+	return DefaultBrand
+}
+
+// brandDisplay is a brand id's human display name: the id with an upper-cased
+// first letter (lux → "Lux", hanzo → "Hanzo"). Derived from the id — one source
+// of truth with the brands registry, no hand-maintained display list. Used to
+// build the white-label console <title> (webui.go).
+func brandDisplay(id string) string {
+	if id == "" {
+		id = DefaultBrand
+	}
+	return strings.ToUpper(id[:1]) + id[1:]
+}
+
 // BrandIssuers returns the OIDC issuer of every configured white-label brand. The
 // in-binary identity validator (auth_identity.go) trusts a token whose `iss` is
 // any of these, so ONE cloud binary validates hanzo AND lux/zoo/pars tokens. One

brand_test.go

@@ -29,6 +29,46 @@ func TestBrandFor(t *testing.T) {
 	}
 }
 
+func TestBrandForHost(t *testing.T) {
+	match := map[string]string{
+		"api.hanzo.ai":        "hanzo",
+		"hanzo.ai":            "hanzo",
+		"api.lux.network":     "lux",
+		"lux.network":         "lux",
+		"API.LUX.NETWORK":     "lux", // case-insensitive
+		"api.lux.network:443": "lux", // port stripped
+		"api.zoo.ngo":         "zoo",
+		"chat.zoo.ngo":        "zoo",
+		"api.pars.network":    "pars",
+		// AltDomains: the real cloud console surfaces run on <brand>.cloud /
+		// <brand>.network — a Host there must brand as Lux/Zoo, never Hanzo.
+		"console.lux.cloud":   "lux",
+		"console.zoo.cloud":   "zoo",
+		"foo.zoo.network":     "zoo",
+		"console.hanzo.cloud": "hanzo",
+		"app.hanzo.app":       "hanzo",
+	}
+	for host, want := range match {
+		if got, ok := BrandForHostOK(host); !ok || got != want {
+			t.Errorf("BrandForHostOK(%q) = %q,%v; want %q,true", host, got, ok, want)
+		}
+		if got := BrandForHost(host); got != want {
+			t.Errorf("BrandForHost(%q) = %q; want %q", host, got, want)
+		}
+	}
+	// No brand domain matches → not ok, and BrandForHost defaults to hanzo. The
+	// caller (agentskills) uses the not-ok signal to fall back to the DEPLOYMENT
+	// brand instead of blindly emitting Hanzo on a non-hanzo pod.
+	for _, host := range []string{"example.com", "localhost", "", "10.0.0.1"} {
+		if _, ok := BrandForHostOK(host); ok {
+			t.Errorf("BrandForHostOK(%q) matched a brand, want no match", host)
+		}
+		if got := BrandForHost(host); got != DefaultBrand {
+			t.Errorf("BrandForHost(%q) = %q, want %q", host, got, DefaultBrand)
+		}
+	}
+}
+
 // TestLoadConfig_IssuerDerivedFromBrand asserts that when CLOUD_IAM_ISSUER is
 // unset, the issuer is derived from CLOUD_BRAND — so a non-hanzo brand does not
 // silently validate against iam.hanzo.ai.

build.go

@@ -3,13 +3,21 @@ package cloud
 import (
 	"context"
 	"fmt"
+	"os"
 	"strings"
 
-	"github.com/hanzoai/commerce/metering"
+	aiobject "github.com/hanzoai/ai/object"
+	"github.com/hanzoai/cloud/clients/commerceinproc"
+	"github.com/hanzoai/cloud/clients/metering"
 	luxlog "github.com/luxfi/log"
+	"github.com/zap-proto/zip"
 
 	"github.com/hanzoai/cloud/clients"
-	"github.com/hanzoai/cloud/clients/kms"
+	"github.com/hanzoai/cloud/clients/finance"
+	"github.com/hanzoai/cloud/clients/gatewaypolicy"
+	"github.com/hanzoai/cloud/clients/money"
+	"github.com/hanzoai/cloud/clients/s3admin"
+	"github.com/hanzoai/cloud/types"
 )
 
 // BuildDeps constructs the Deps used by every subsystem's Mount(app, deps).
@@ -45,7 +53,8 @@ import (
 // when no endpoint is configured.
 func BuildDeps(cfg *Config) Deps {
 	logger := luxlog.New("cloud")
-	logger.Info("building deps",
+	logger.Info(
+		"building deps",
 		"brand", cfg.Brand,
 		"domain", cfg.Domain,
 		"iam_issuer", cfg.IAMIssuer,
@@ -54,50 +63,105 @@ func BuildDeps(cfg *Config) Deps {
 	)
 
 	deps := Deps{
-		Logger:    logger,
-		Brand:     cfg.Brand,
-		Env:       cfg.Env,
-		Domain:    cfg.Domain,
-		IAMIssuer: cfg.IAMIssuer,
-		DataDir:   cfg.DataDir,
+		Logger:         logger,
+		Brand:          cfg.Brand,
+		Version:        cfg.Version,
+		Env:            cfg.Env,
+		Domain:         cfg.Domain,
+		IAMIssuer:      cfg.IAMIssuer,
+		DataDir:        cfg.DataDir,
+		AIDefaultModel: cfg.AIDefaultModel,
 	}
 
 	// For each subsystem: enabled → leave nil (Mount fills it); not
 	// enabled + endpoint → RPC client; not enabled + no endpoint →
-	// disabled stub.
-	deps.IAM = pickIAMClient(cfg, logger)
+	// disabled stub. The plain co-resident-or-RPC-or-disabled clients share
+	// ONE resolver (pick); KMS/AI/VFS keep bespoke pickers because their
+	// construction genuinely differs (embedded store / gateway preference /
+	// S3-admin backend). O11y's disabled stub is a no-op (telemetry going
+	// nowhere is normal), not fail-closed.
+	deps.IAM = pick(cfg, logger, "iam", "IAM", cfg.IAMZAPAddr, clients.IAMRPCAt, clients.DisabledIAM)
 	deps.KMS = pickKMSClient(cfg, logger)
-	deps.Base = pickBaseClient(cfg, logger)
+	deps.Base = pick(cfg, logger, "base", "Base", cfg.BaseZAPAddr, clients.BaseRPCAt, clients.DisabledBase)
 	deps.Commerce = pickCommerceClient(cfg, logger)
-	deps.AI = pickAIClient(cfg, logger)
-	deps.O11y = pickO11yClient(cfg, logger)
+	// Metering client BEFORE the AI client: deps.AI is wrapped in the metering
+	// decorator (the ONE inference gate+meter — no exempt path, no bypass, no
+	// side-channel key), which needs deps.Metering. nil-safe — an unconfigured
+	// commerce URL yields a !Enabled() client, so the wrap is a transparent
+	// pass-through and a dev deployment is never blocked.
+	deps.Metering = buildMeteringClient(cfg, logger)
+	deps.AI = meteredAIClient(pickAIClient(cfg, logger), deps)
+	wireFinance(cfg, logger)
+	deps.O11y = pick(cfg, logger, "o11y", "O11y", cfg.O11yZAPAddr, clients.O11yRPCAt, clients.DisabledO11y)
 	deps.VFS = pickVFSClient(cfg, logger)
-	deps.MQ = pickMQClient(cfg, logger)
+	deps.MQ = pick(cfg, logger, "mq", "MQ", cfg.MQZAPAddr, clients.MQRPCAt, clients.DisabledMQ)
 
 	// Payments and Vault never co-resident. Disabled stub when no
 	// endpoint, otherwise RPC.
 	deps.Payments = pickPaymentsClient(cfg, logger)
 	deps.Vault = pickVaultClient(cfg, logger)
 
-	// Billing metering client for the request-edge gate. nil-safe: when no
-	// commerce URL is configured the resulting client is !Enabled() and the
-	// gate is a no-op.
-	deps.Metering = buildMeteringClient(cfg, logger)
+	// Runtime-mutable edge-policy store (/v1/gateway config plane), layered over
+	// the static env/flag defaults so an un-provisioned deployment behaves exactly
+	// as the static config until an operator PUTs an override. New always returns a
+	// working *Store (static-only if the SQLite file can't open), so the edge
+	// middleware is never left without a policy source — a store-open error is
+	// logged, not fatal.
+	gp, err := gatewaypolicy.New(cfg.DataDir, cfg.AdminOrg, staticEdgePolicy(cfg))
+	if err != nil {
+		logger.Warn("gateway policy store degraded to static-only", "err", err)
+	}
+	deps.GatewayPolicy = gp
 
 	return deps
 }
 
-// buildMeteringClient constructs the commerce metering client for BillingGate.
-// An empty CommerceHTTPURL yields a not-Enabled() client (allow + no-op),
-// matching the metering package's "not configured" mode, so an unconfigured
-// deployment is never blocked. The token is a KMS-sourced secret supplied via
-// config; it is never logged.
+// staticEdgePolicy projects the static env/flag edge config into the boot-default
+// policy the gatewaypolicy.Store layers runtime overrides on top of. A disabled
+// per-IP limiter (CLOUD_EDGE_RATELIMIT=false) maps to PerIPRPM 0 (a live no-op).
+func staticEdgePolicy(cfg *Config) gatewaypolicy.Policy {
+	p := gatewaypolicy.Policy{
+		CORSOrigins: cfg.CORSOrigins,
+		WindowSec:   cfg.EdgeRateWindowSec,
+	}
+	if cfg.EdgeRateEnabled {
+		p.PerIPRPM = cfg.EdgeRatePerIP
+	}
+	return p
+}
+
+// buildMeteringClient constructs the commerce metering client for BillingGate —
+// the request-edge debit on every paid AI call.
+//
+// CO-RESIDENT (task #111): when commerce is folded in-process (Enabled("commerce")),
+// the gate DEBITS the in-process commerce handler over commerceinproc's self-routing
+// transport — a direct Go call, no socket to commerce.hanzo.svc:8001. The base is
+// pinned NON-EMPTY (real CLOUD_COMMERCE_HTTP_URL, else the in-process placeholder) so
+// the gate stays ENABLED even after the standalone + its env are retired — a metering
+// gate that silently no-ops is a free-money hole, so it must never drop to
+// "not configured" while commerce is co-resident. The transport resolves the handler
+// lazily (published by commerce.Mount before any request), so building the client
+// here (pre-MountAll) is fine.
+//
+// SPLIT-DEPLOY (unchanged): without co-residency an empty CommerceHTTPURL yields a
+// not-Enabled() client (allow + no-op) and a set one speaks plain HTTP to the
+// standalone, exactly as before. The token is KMS-sourced; never logged.
 func buildMeteringClient(cfg *Config, log luxlog.Logger) *metering.Client {
+	base := cfg.CommerceHTTPURL
+	var httpClient metering.HTTPDoer
+	inProcess := cfg.Enabled("commerce")
+	if inProcess {
+		if base == "" {
+			base = commerceinproc.PlaceholderBase
+		}
+		httpClient = commerceinproc.Client(0) // in-process dispatch; no network timeout
+	}
 	m, err := metering.New(metering.Config{
-		BaseURL:  cfg.CommerceHTTPURL,
-		Token:    cfg.CommerceServiceToken,
-		Org:      cfg.Brand, // X-Org-Id default for S2S; per-request org overrides.
-		FailOpen: cfg.BillingFailOpen,
+		BaseURL:    base,
+		Token:      cfg.CommerceServiceToken,
+		Org:        cfg.Brand, // X-Org-Id default for S2S; per-request org overrides.
+		FailOpen:   cfg.BillingFailOpen,
+		HTTPClient: httpClient, // nil off the co-resident path → metering builds its own
 	})
 	if err != nil {
 		// Only an unparseable URL reaches here. Fall back to a not-configured
@@ -106,51 +170,122 @@ func buildMeteringClient(cfg *Config, log luxlog.Logger) *metering.Client {
 		m, _ = metering.New(metering.Config{})
 	}
 	if m.Enabled() {
-		log.Info("billing gate enabled", "commerce_url", cfg.CommerceHTTPURL, "fail_open", cfg.BillingFailOpen)
+		log.Info("billing gate enabled", "commerce", boolStr(inProcess, "in-process", "http:"+base), "fail_open", cfg.BillingFailOpen)
 	} else {
 		log.Info("billing gate disabled (no commerce URL)")
 	}
 	return m
 }
 
-// pickIAMClient returns the canonical IAMClient for this process.
-// nil = enabled here, Mount will fill it. RPC = remote endpoint
-// configured. Disabled = not enabled, no endpoint.
-func pickIAMClient(cfg *Config, log luxlog.Logger) IAMClient {
-	if cfg.Enabled("iam") {
-		return nil
+func boolStr(b bool, t, f string) string {
+	if b {
+		return t
 	}
-	if cfg.IAMZAPAddr != "" {
-		log.Info("deps.IAM → ZAP RPC", "addr", cfg.IAMZAPAddr)
-		return clients.IAMRPCAt(cfg.IAMZAPAddr)
+	return f
+}
+
+// wireFinance constructs the ONE in-process finance ledger (per-org SQLite
+// double-entry prepaid wallet), publishes it for every money consumer to resolve by
+// the narrow finance.Client, and installs the embedded ai router's balance-read +
+// usage-debit hooks so the PREPAID gate dispatches DIRECTLY to it — a typed in-proc
+// call, no HTTP, no socket. There is NO exempt path (hanzoai/ai >= v1.805.8): every
+// principal is gated on a positive prepaid balance, fail-closed. MUST run before
+// ai.Mount (the ai gate reads the hook per request; the hook must be installed first)
+// — which BuildDeps guarantees (deps are built before MountAll).
+func wireFinance(cfg *Config, log luxlog.Logger) {
+	if !cfg.Enabled("commerce") {
+		return // money layer not co-resident (split-deploy); ai falls back to HTTP.
 	}
-	return clients.DisabledIAM()
+	fin := finance.New(cfg.DataDir)
+	finance.Publish(fin)
+	// Money is billed to the SUBJECT's wallet, inside the org's ledger.
+	//
+	// org  = which ledger (the tenant's books)
+	// subject = which wallet in it (ai resolves it: a person => "org/name", an
+	//           org-owned application/service key => the org's own account)
+	//
+	// So a personal account has a PERSONAL balance and a personal plan, and an org
+	// pays for what its applications and service keys spend — which is the product:
+	// sign up as yourself, then stand up an org whose users are your customers.
+	//
+	// Keying both hooks on the org collapsed every member onto the tenant's pool
+	// wallet: every new signup lives in "hanzo", so a brand-new $0 account read
+	// HANZO's balance and sailed through the gate — we enforced our own wallet.
+	//
+	// The invariant that must never break: the gate READ and the usage DEBIT key on
+	// the SAME wallet, or spend can outrun the balance that admitted it. Both use
+	// subject; keep them together. The gate reads a coarse cents balance (a >0
+	// threshold only); the DEBIT is 18-decimal-exact.
+	aiobject.SetBalanceReader(func(ctx context.Context, subject, namespace, currency string) (int64, error) {
+		bal, err := fin.Balance(ctx, namespace, subject, currency, false)
+		if err != nil {
+			return 0, err
+		}
+		return bal.Cents(), nil
+	})
+	// The DEBIT is exact: the ai module emits the cost as a decimal-USD string, parsed
+	// here to 18-decimal USD (1e-18) so a sub-cent call bills precisely and is never floored.
+	aiobject.SetUsageRecorder(func(ctx context.Context, u aiobject.UsageEvent) error {
+		amt, err := money.ParseUSD(u.USD)
+		if err != nil {
+			return err
+		}
+		return fin.RecordUsage(ctx, types.UsageInput{
+			Org: u.Namespace, Subject: u.Subject, Amount: amt,
+			Currency: u.Currency, Model: u.Model, Provider: u.Provider, RequestID: u.RequestID,
+		})
+	})
+	log.Info("finance ledger wired (per-subject wallet in the org ledger, 18-decimal-exact, fail-closed)", "dataDir", cfg.DataDir)
+}
+
+// pick resolves one inter-subsystem client under the HIP-0106 wiring rule shared
+// by every co-resident-capable dependency: enabled in THIS process → zero value
+// (nil) so the subsystem's own Mount installs the in-process client; not enabled
+// but a ZAP endpoint is configured → an RPC client at that endpoint; neither →
+// the fail-closed/no-op disabled stub. name is the enable-list id; label is the
+// deps.<X> log tag; rpc/disabled are the client's typed constructors. This is the
+// ONE implementation of that rule — KMS/AI/VFS opt out with bespoke pickers only
+// because their construction genuinely differs.
+func pick[T any](cfg *Config, log luxlog.Logger, name, label, zapAddr string, rpc func(string) T, disabled func() T) T {
+	if cfg.Enabled(name) {
+		var zero T // enabled here → Mount fills deps.<label>
+		return zero
+	}
+	if zapAddr != "" {
+		log.Info("deps."+label+" → ZAP RPC", "addr", zapAddr)
+		return rpc(zapAddr)
+	}
+	return disabled()
 }
 
 // pickKMSClient resolves deps.KMS. When the kms subsystem is co-resident
-// (Enabled("kmssvc")) it returns the IN-PROCESS Client backed by the embedded
+// (Enabled("kms")) it returns the IN-PROCESS Client backed by the embedded
 // luxfi/kms SecretStore under CLOUD_DATA_DIR — no external RPC. A store-open
 // failure is NOT fatal to the whole binary: it falls back to the disabled stub
 // (fail-closed) and logs, so a bad data dir degrades KMS rather than crashing
 // every subsystem. Absent co-residency the legacy ZAP-RPC + disabled fallbacks
 // apply (out-of-process KMS, or not wired).
 //
-// The internal subsystem name is "kmssvc" (see clients/kmssvc.init — it avoids the
-// serve.go generic-health shadow on /v1/kms/health); the client gate keys on the
-// same name so "enabled" is one concept.
+// The subsystem id is "kms" (clients/kms registers it with cloud.HealthOwner so
+// the generic liveness route never shadows its real /v1/kms/health, and registers
+// the client factory this gate calls); this gate keys on the same id so "enabled"
+// is one concept.
 func pickKMSClient(cfg *Config, log luxlog.Logger) KMSClient {
-	if cfg.Enabled("kmssvc") {
-		c, err := kms.New(kms.Config{
-			DataDir:      cfg.DataDir,
-			MasterKeyB64: cfg.KMSMasterKeyRef,
-			MPCAddr:      cfg.KMSMPCAddr,
-			MPCVaultID:   cfg.KMSMPCVaultID,
-		}, log)
+	if cfg.Enabled("kms") {
+		// The embedded-client constructor is registered by clients/kms in init()
+		// (RegisterKMSClientFactory). cloud never imports clients/kms, so the KMS
+		// library and its /v1/kms subsystem live in one package with no cloud⇄kms
+		// import cycle. Absent the registration (clients/kms not linked into this
+		// binary) KMS fails closed rather than pretending to host secrets.
+		if kmsClientFactory == nil {
+			log.Error("deps.KMS: kms enabled but no client factory registered (clients/kms not linked); failing closed")
+			return clients.DisabledKMS()
+		}
+		c, err := kmsClientFactory(cfg, log)
 		if err != nil {
 			log.Error("deps.KMS: embedded KMS unavailable, failing closed", "err", err)
 			return clients.DisabledKMS()
 		}
-		log.Info("deps.KMS → in-process (embedded luxfi/kms)", "ready", c.Ready(), "signing", c.SigningConfigured())
 		return c
 	}
 	if cfg.KMSZAPAddr != "" {
@@ -160,20 +295,235 @@ func pickKMSClient(cfg *Config, log luxlog.Logger) KMSClient {
 	return clients.DisabledKMS()
 }
 
-func pickBaseClient(cfg *Config, log luxlog.Logger) BaseClient {
-	if cfg.Enabled("base") {
-		return nil
-	}
-	if cfg.BaseZAPAddr != "" {
-		log.Info("deps.Base → ZAP RPC", "addr", cfg.BaseZAPAddr)
-		return clients.BaseRPCAt(cfg.BaseZAPAddr)
-	}
-	return clients.DisabledBase()
+// kmsClientFactory constructs the embedded in-process KMS client from cloud
+// Config. clients/kms registers it in init(); pickKMSClient calls it so cloud
+// depends on the KMSClient interface + this hook, never the concrete kms package
+// — the same inversion the subsystem Registry already uses (cloud mounts every
+// subsystem it never imports). Exactly one registration.
+var kmsClientFactory func(cfg *Config, log luxlog.Logger) (KMSClient, error)
+
+// RegisterKMSClientFactory installs the embedded-KMS constructor. clients/kms
+// calls this from its init(); it is the ONE inversion point that lets the KMS
+// library and its /v1/kms subsystem share one package with no cloud⇄kms cycle.
+func RegisterKMSClientFactory(f func(cfg *Config, log luxlog.Logger) (KMSClient, error)) {
+	kmsClientFactory = f
 }
 
+// ---- git-push-to-deploy ----
+
+// GitPushEvent describes a push that just landed on the embedded git server: the
+// org, the repo, the branch that moved, and its new tip commit. CloneURL is the
+// canonical clone URL of that repo (https://<host>/v1/git/<org>/<repo>.git) — the
+// exact value an Application's RepoURL carries — so the builder can resolve which
+// app (if any) tracks this branch and needs a rebuild.
+type GitPushEvent struct {
+	Org      string
+	Project  string
+	Repo     string
+	Branch   string
+	Commit   string
+	CloneURL string
+}
+
+// pushBuilder is the registered git-push-to-deploy trigger. clients/platform
+// installs it in Mount; clients/git calls OnGitPush after a push lands. The
+// inversion keeps git⇄platform decoupled — git never imports platform — exactly
+// like kmsClientFactory and the subsystem Registry. Exactly one registration.
+var pushBuilder func(ctx context.Context, ev GitPushEvent) error
+
+// RegisterPushBuilder installs the git-push-to-deploy trigger. clients/platform
+// calls this from its Mount when co-resident; it is the ONE inversion point that
+// lets the embedded git server launch a platform build with no git⇄platform cycle.
+func RegisterPushBuilder(f func(ctx context.Context, ev GitPushEvent) error) {
+	pushBuilder = f
+}
+
+// OnGitPush fires the registered push-to-deploy trigger for a landed push. It is a
+// no-op when no builder is registered (git server running without the platform
+// subsystem co-resident). Best-effort by contract: the caller must never fail the
+// push the client already committed just because a build could not be triggered.
+func OnGitPush(ctx context.Context, ev GitPushEvent) error {
+	if pushBuilder == nil {
+		return nil
+	}
+	return pushBuilder(ctx, ev)
+}
+
+// ---- first-party service release (push→build→image→CR rollout) ----
+
+// ServiceReleaseEvent describes a proven, clean-semver image ready to roll live on
+// an operator-managed first-party service. It is the payload of the release seam
+// that closes push→build→image→CR: after a build produces the image, the CR for
+// this service is patched to it and the operator reconciles the Deployment.
+//
+//   - Service is the target CR metadata.name (the repo/service name ⇒ CR name,
+//     mirroring universe's image-update.yml convention).
+//   - Image is the full registry ref (repository:tag); the tag MUST be clean
+//     semver (vX.Y.Z) — the releaser refuses every mutable/sha/suffixed form.
+//   - SHA is the source commit for provenance (optional; logged, never gated on).
+type ServiceReleaseEvent struct {
+	Service string
+	Image   string
+	SHA     string
+}
+
+// serviceReleaser is the registered first-party CR-rollout seam. clients/paas
+// (the owner of the hanzo.ai/v1 Service CR control plane) installs it in Mount; a
+// proven build calls OnServiceRelease, which patches spec.image on the matching
+// CR. The inversion keeps package cloud from importing clients/paas (which imports
+// cloud) — the same idiom as pushBuilder / kmsClientFactory. Exactly one
+// registration.
+var serviceReleaser func(ctx context.Context, ev ServiceReleaseEvent) error
+
+// RegisterServiceReleaser installs the first-party CR-rollout hook. clients/paas
+// calls this from its Mount when co-resident; it is the ONE inversion point that
+// lets a build-completion path roll a proven image onto its operator Service CR
+// with no cloud⇄paas import cycle.
+func RegisterServiceReleaser(f func(ctx context.Context, ev ServiceReleaseEvent) error) {
+	serviceReleaser = f
+}
+
+// ServiceReleaserRegistered reports whether a first-party CR-rollout hook is
+// installed (the paas control plane is co-resident). A caller uses it to know
+// whether OnServiceRelease actually patches a CR or is a no-op, so it can be
+// honest about which rollout path took effect.
+func ServiceReleaserRegistered() bool { return serviceReleaser != nil }
+
+// OnServiceRelease rolls a proven image live by patching the matching hanzo.ai/v1
+// Service CR's spec.image (the operator then reconciles the Deployment). It is a
+// no-op when no releaser is registered (a binary without the paas control plane
+// co-resident). The releaser enforces the clean-semver gate and CR-name
+// resolution; this is only the dispatch seam.
+func OnServiceRelease(ctx context.Context, ev ServiceReleaseEvent) error {
+	if serviceReleaser == nil {
+		return nil
+	}
+	return serviceReleaser(ctx, ev)
+}
+
+// ---- git lifecycle event stream ----
+//
+// One event, many subscribers. push-to-deploy (OnGitPush) is the deploy
+// subscriber-of-record and stays exactly as it is; this seam generalizes the SAME
+// inversion to N reactors (mirror-out, Slack-notify, …) so git/platform EMIT a
+// lifecycle fact and never import the subscribers. It is deliberately SEPARATE
+// from OnGitPush — the deploy path is single-registrant and synchronous, this
+// stream is many-registrant and best-effort — so adding a reactor can never
+// perturb push→deploy.
+
+// LifecycleKind classifies a git lifecycle event. The value IS the wire name a
+// subscription filters on.
+type LifecycleKind string
+
+const (
+	LifecyclePushLanded   LifecycleKind = "push.landed"
+	LifecycleBuildStarted LifecycleKind = "build.started"
+	LifecycleDeployLive   LifecycleKind = "deploy.live"
+	LifecycleDeployFailed LifecycleKind = "deploy.failed"
+)
+
+// LifecycleEvent is one git lifecycle fact fanned out to every registered
+// subscriber. A plain data value — values, not places:
+//   - Org/Project/Repo    the tenant + repo the fact happened in (the routing key).
+//   - Branch/Before/After  the ref that moved and its old→new tip (a push).
+//   - Pusher              who pushed (best-effort; "" for a client-less push).
+//   - DeployID/Detail     the deployment id + a human one-liner (a deploy transition).
+//   - Origin              "" for a native push; the source host when the refs
+//     arrived via an inbound mirror sync — the loop-prevention seam that lets the
+//     outbound mirror subscriber suppress a re-mirror of refs it just pulled in.
+type LifecycleEvent struct {
+	Kind     LifecycleKind
+	Org      string
+	Project  string
+	Repo     string
+	Branch   string
+	Before   string
+	After    string
+	Pusher   string
+	DeployID string
+	Detail   string
+	Origin   string
+}
+
+// RepoFromCloneURL extracts the repo name from a git clone URL (last path segment,
+// ".git" stripped) — the repo component of the (org,project,repo) routing key that
+// a deploy emitter derives from an app/project's linked RepoURL. The ONE place this
+// derivation lives, shared by the platform + projects deploy paths (no per-package
+// copy).
+func RepoFromCloneURL(u string) string {
+	u = strings.TrimSuffix(strings.TrimSpace(u), "/")
+	u = strings.TrimSuffix(u, ".git")
+	if i := strings.LastIndexByte(u, '/'); i >= 0 {
+		return u[i+1:]
+	}
+	return u
+}
+
+// lifecycleSubscribers is the fan-out list. Registration happens at Mount
+// (single-threaded, before any request is served), so a plain slice is correct:
+// EmitLifecycle only ever ranges it after every subsystem's Mount has run.
+var lifecycleSubscribers []func(ctx context.Context, ev LifecycleEvent)
+
+// RegisterLifecycleSubscriber adds a git-lifecycle reactor. Every subsystem that
+// reacts to a push/deploy (mirror-out, Slack-notify) registers ONE here at Mount;
+// git/platform EMIT via EmitLifecycle. The inversion keeps the emitters from
+// importing the subscribers — the same pattern as RegisterPushBuilder, but
+// many-registrant.
+func RegisterLifecycleSubscriber(fn func(ctx context.Context, ev LifecycleEvent)) {
+	if fn == nil {
+		return
+	}
+	lifecycleSubscribers = append(lifecycleSubscribers, fn)
+}
+
+// ResetLifecycleSubscribers clears the registry. TEST-ONLY seam (a test mounts and
+// unmounts repeatedly); production registers once at Mount and never resets.
+func ResetLifecycleSubscribers() { lifecycleSubscribers = nil }
+
+// EmitLifecycle fans one event out to every registered subscriber, best-effort and
+// NON-BLOCKING: each subscriber runs in its own goroutine on a cancel-immune
+// context (the fact already happened — a request cancel must not abort the
+// notify/mirror), so a slow reactor (a mirror push) can never delay the git/deploy
+// path or another reactor. A panicking subscriber is contained so one bad reactor
+// can neither crash the shared multi-tenant process nor starve the others; each
+// subscriber logs its own errors.
+func EmitLifecycle(ctx context.Context, ev LifecycleEvent) {
+	subs := lifecycleSubscribers
+	if len(subs) == 0 {
+		return
+	}
+	bg := context.WithoutCancel(ctx)
+	for _, fn := range subs {
+		go func(fn func(context.Context, LifecycleEvent)) {
+			defer func() { _ = recover() }()
+			fn(bg, ev)
+		}(fn)
+	}
+}
+
+// pickCommerceClient resolves deps.Commerce — the typed inter-subsystem client the
+// entitlements/licensing tier calls (GetOrgConfig, CheckEntitlement). When the
+// commerce subsystem is co-resident (Enabled("commerce")) it returns the IN-PROCESS
+// client via the factory apps/commerce.go registers in init() — a direct Go
+// call that reads the embedded commerce datastore (hanzoai/commerce MODULE, since
+// the un-fork) + the @hanzo/plans vocabulary, no network hop (the HIP-0106
+// co-resident default). The factory inversion stays because the concrete client
+// (clients/commerceinproc) imports clients/plan, which imports cloud — a direct
+// call here would be a package cycle. Absent the registration it fails closed
+// rather than pretending.
+//
+// NETWORK PATH PRESERVED: absent co-residency the ZAP-RPC + disabled fallbacks apply
+// (out-of-process commerce, or not wired), so the remote proxy seam
+// (CLOUD_COMMERCE_ZAP_ADDR) is unchanged — the live default still selects the
+// network client when commerce is not enabled in this process.
 func pickCommerceClient(cfg *Config, log luxlog.Logger) CommerceClient {
 	if cfg.Enabled("commerce") {
-		return nil
+		if commerceClientFactory == nil {
+			log.Error("deps.Commerce: commerce enabled but no client factory registered (subsystems not linked); failing closed")
+			return clients.DisabledCommerce()
+		}
+		log.Info("deps.Commerce → in-process (embedded commerce)", "brand", cfg.Brand)
+		return commerceClientFactory(cfg, log)
 	}
 	if cfg.CommerceZAPAddr != "" {
 		log.Info("deps.Commerce → ZAP RPC", "addr", cfg.CommerceZAPAddr)
@@ -182,6 +532,19 @@ func pickCommerceClient(cfg *Config, log luxlog.Logger) CommerceClient {
 	return clients.DisabledCommerce()
 }
 
+// commerceClientFactory constructs the embedded in-process Commerce client.
+// apps/commerce.go registers it in init(); pickCommerceClient calls it so
+// package cloud depends on the CommerceClient interface + this hook, never the
+// concrete commerceinproc package (whose entitlement client pulls clients/plan,
+// which imports cloud — the hook is what keeps the package graph acyclic).
+var commerceClientFactory func(cfg *Config, log luxlog.Logger) CommerceClient
+
+// RegisterCommerceClientFactory installs the embedded-Commerce client constructor.
+// apps/commerce.go calls this from its init(); exactly one registration.
+func RegisterCommerceClientFactory(f func(cfg *Config, log luxlog.Logger) CommerceClient) {
+	commerceClientFactory = f
+}
+
 // pickAIClient resolves deps.AI — the client the agents subsystem runs chat
 // completions through. Unlike the co-resident subsystems, there is NO in-process
 // "ai" mount that fills a nil deps.AI: inference is an external gateway, so this
@@ -204,11 +567,13 @@ func pickAIClient(cfg *Config, log luxlog.Logger) AIClient {
 		log.Info("deps.AI → HTTP gateway (static key)", "base_url", cfg.AIBaseURL, "default_model", cfg.AIDefaultModel)
 		return clients.AIHTTPAt(cfg.AIBaseURL, cfg.AIAPIKey, cfg.AIDefaultModel)
 	}
-	if cfg.AIBaseURL != "" && cfg.AIAuthClientID != "" && cfg.AIAuthClientSecret != "" && cfg.IAMIssuer != "" {
-		tokenURL := strings.TrimRight(cfg.IAMIssuer, "/") + "/v1/iam/oauth/token"
-		log.Info("deps.AI → HTTP gateway (IAM M2M)", "base_url", cfg.AIBaseURL,
-			"token_url", tokenURL, "client_id", cfg.AIAuthClientID, "default_model", cfg.AIDefaultModel)
-		return clients.AIHTTPM2M(cfg.AIBaseURL, tokenURL, cfg.AIAuthClientID, cfg.AIAuthClientSecret, cfg.AIDefaultModel)
+	if cfg.AIBaseURL != "" && cfg.AIAuthClientID != "" && cfg.AIAuthClientSecret != "" {
+		tokenURL := aiM2MTokenURL(cfg)
+		if tokenURL != "" {
+			log.Info("deps.AI → HTTP gateway (IAM M2M)", "base_url", cfg.AIBaseURL,
+				"token_url", tokenURL, "client_id", cfg.AIAuthClientID, "default_model", cfg.AIDefaultModel)
+			return clients.AIHTTPM2M(cfg.AIBaseURL, tokenURL, cfg.AIAuthClientID, cfg.AIAuthClientSecret, cfg.AIDefaultModel)
+		}
 	}
 	if cfg.AIZAPAddr != "" {
 		log.Info("deps.AI → ZAP RPC", "addr", cfg.AIZAPAddr)
@@ -218,41 +583,63 @@ func pickAIClient(cfg *Config, log luxlog.Logger) AIClient {
 	return clients.DisabledAI()
 }
 
-func pickO11yClient(cfg *Config, log luxlog.Logger) O11yClient {
-	if cfg.Enabled("o11y") {
-		return nil
+// aiM2MTokenURL resolves IAM's client_credentials endpoint the agent runner mints
+// its M2M inference token at. It MUST be reachable FROM INSIDE THE CLUSTER: the
+// runner runs in-cluster and the public issuer host (https://hanzo.id) is fronted
+// by Cloudflare, which 403s a server-side (non-browser) loopback POST with edge
+// error 1006 — so minting against the PUBLIC issuer URL fails and every
+// POST /v1/agents/:ref/run 502s (root-caused 2026-07-04: in-cluster POST to
+// https://hanzo.id/v1/iam/oauth/token → 403/1006, while http://iam.hanzo.svc/... → 200).
+// This mirrors the KMS login-broker resolution (clients/kms) exactly — one
+// split-horizon policy, no drift. Prefer, in order: an explicit override
+// (CLOUD_AI_IAM_TOKEN_URL), the in-cluster IAM service base (IAM_URL — already
+// wired to http://iam.hanzo.svc for JWKS), then the public issuer as a last resort
+// (single-process / no split-horizon deploys). Returns "" only when no identity is
+// resolvable, which keeps the M2M branch off (caller falls through to the stub).
+func aiM2MTokenURL(cfg *Config) string {
+	if override := strings.TrimSpace(os.Getenv("CLOUD_AI_IAM_TOKEN_URL")); override != "" {
+		return override
 	}
-	if cfg.O11yZAPAddr != "" {
-		log.Info("deps.O11y → ZAP RPC", "addr", cfg.O11yZAPAddr)
-		return clients.O11yRPCAt(cfg.O11yZAPAddr)
+	if base := strings.TrimRight(strings.TrimSpace(os.Getenv("IAM_URL")), "/"); base != "" {
+		return base + "/v1/iam/oauth/token"
 	}
-	// O11y disabled-stub is no-op (not fail-closed) — telemetry
-	// going nowhere is a normal mode.
-	return clients.DisabledO11y()
+	if iss := strings.TrimRight(strings.TrimSpace(cfg.IAMIssuer), "/"); iss != "" {
+		return iss + "/v1/iam/oauth/token"
+	}
+	return ""
 }
 
 func pickVFSClient(cfg *Config, log luxlog.Logger) VFSClient {
-	if cfg.Enabled("vfs") {
-		return nil
-	}
+	// deps.VFS must NEVER be nil (R-7): files.go and any other VFS consumer call
+	// s.vfs.Put/Get/Delete unconditionally, so a nil here is a per-request 500
+	// (dishonest degradation) instead of a fail-closed 502. Unlike the
+	// nil-then-Mount-fills convention other subsystems use, nothing fills deps.VFS
+	// after MountAll (Mount receives deps by value), so we ALWAYS hand back a
+	// concrete client.
 	if cfg.VFSZAPAddr != "" {
 		log.Info("deps.VFS → ZAP RPC", "addr", cfg.VFSZAPAddr)
 		return clients.VFSRPCAt(cfg.VFSZAPAddr)
 	}
+	// Real blob backend (.97): the shared SeaweedFS S3 gateway — the canonical,
+	// key-based object store, reached with the SAME S3_ADMIN_* admin identity
+	// clients/s3 uses (s3admin, one construction). Present only when those creds
+	// are injected; a construction failure degrades to fail-closed rather than a
+	// nil deref. Team blobs (avatars/attachments) round-trip through this to the
+	// team-blobs bucket, org-scoped by the caller-built key prefix.
+	if admin := s3admin.New(); admin.Configured() {
+		v, err := clients.NewS3VFS(admin)
+		if err != nil {
+			log.Error("deps.VFS → S3 construction failed; falling back to fail-closed", "err", err)
+			return clients.DisabledVFS()
+		}
+		log.Info("deps.VFS → SeaweedFS S3", "bucket", clients.TeamBlobBucket)
+		return v
+	}
+	// No VFS endpoint and no S3 admin creds → fail-closed stub (R-7): Put/Get/Delete
+	// return a non-nil error → files answer 502, never a nil-deref 500.
 	return clients.DisabledVFS()
 }
 
-func pickMQClient(cfg *Config, log luxlog.Logger) MQClient {
-	if cfg.Enabled("mq") {
-		return nil
-	}
-	if cfg.MQZAPAddr != "" {
-		log.Info("deps.MQ → ZAP RPC", "addr", cfg.MQZAPAddr)
-		return clients.MQRPCAt(cfg.MQZAPAddr)
-	}
-	return clients.DisabledMQ()
-}
-
 func pickPaymentsClient(cfg *Config, log luxlog.Logger) PaymentsClient {
 	if cfg.PaymentsZAPAddr != "" {
 		log.Info("deps.Payments → ZAP RPC", "addr", cfg.PaymentsZAPAddr)
@@ -269,11 +656,17 @@ func pickVaultClient(cfg *Config, log luxlog.Logger) VaultClient {
 	return clients.DisabledVault()
 }
 
-// MountFunc is the canonical signature every subsystem exposes per
-// HIP-0106. Each Hanzo Go service ships a top-level `Mount` symbol
-// matching this signature; cmd/cloud/main.go imports the package and
-// calls it.
-type MountFunc func(app any, deps Deps) error // app is *zip.App; using any here to avoid an import cycle in pkg/cloud
+// MountFunc is a subsystem's mount contract: register your routes on app, using
+// deps for everything shared. Every subsystem in the fleet exports exactly this
+// signature, so Wire references each one directly and the compiler checks it.
+//
+// app was once `any`, on the stated grounds that an external module (licensing)
+// exposed func(any, Deps) error and narrowing would break it — while licensing
+// said it used `any` to avoid an import cycle in pkg/cloud. Each cited the other,
+// and the cycle could not exist: this package already imports zip, and zip does
+// not import cloud. The `any` bought nothing and cost every subsystem a Typed()
+// wrapper plus a runtime type assertion whose failure branch was unreachable.
+type MountFunc func(app *zip.App, deps Deps) error
 
 // ShutdownFunc releases a subsystem's process-lifetime resources (background
 // goroutines, open DB handles) on graceful shutdown. It must be idempotent and
@@ -281,66 +674,35 @@ type MountFunc func(app any, deps Deps) error // app is *zip.App; using any here
 // deadline so a slow teardown is cut off rather than hanging SIGTERM.
 type ShutdownFunc func(ctx context.Context) error
 
-// MountSpec describes one subsystem registered for mounting. The Order
-// is used when ordering matters for inter-subsystem deps (e.g. iam
-// before authz before commerce).
+// MountSpec describes one subsystem to mount. There is NO Order field: the slice
+// position in apps.Wire() IS the mount order — the composition root lists
+// subsystems in the exact sequence they mount (and, reversed, tear down), so order
+// is data read top-to-bottom in one file, not ints scattered across the tree.
 type MountSpec struct {
 	Name     string
-	Order    int
 	Mount    MountFunc
 	Shutdown ShutdownFunc // optional; nil means the subsystem has nothing to tear down.
+
+	// OwnsHealth marks a subsystem that serves its OWN GET /v1/<name>/health
+	// (a real, fail-closed probe). Serve's generic liveness loop skips these so
+	// its always-ok route never shadows the subsystem's real probe.
+	OwnsHealth bool
 }
 
-// Registry is the in-process subsystem registry. Subsystems register via
-// init() functions in their respective packages OR cmd/cloud/main.go can
-// explicitly enumerate them. Either pattern works.
-var Registry []MountSpec
-
-// Register adds a subsystem to the in-process registry.
-func Register(name string, order int, mount MountFunc) {
-	Registry = append(Registry, MountSpec{Name: name, Order: order, Mount: mount})
-}
-
-// RegisterWithShutdown adds a subsystem that owns process-lifetime resources: a
-// background worker (e.g. the agents scheduler) or a DB handle that must be
-// flushed. shutdown is invoked by ShutdownAll on graceful stop. This is the ONE
-// way a subsystem gets a teardown — Register stays the zero-teardown default.
-func RegisterWithShutdown(name string, order int, mount MountFunc, shutdown ShutdownFunc) {
-	Registry = append(Registry, MountSpec{Name: name, Order: order, Mount: mount, Shutdown: shutdown})
-}
-
-// ShutdownAll tears down every ENABLED subsystem that registered a ShutdownFunc,
-// in REVERSE mount order (a dependency is torn down after its dependents), best
-// effort: a failure is collected and the rest still run, so one stuck subsystem
-// can't strand another's flush. Serve calls this inside the shutdown deadline.
-func ShutdownAll(ctx context.Context, cfg *Config) error {
-	var firstErr error
-	for i := len(Registry) - 1; i >= 0; i-- {
-		spec := Registry[i]
-		if spec.Shutdown == nil || !cfg.Enabled(spec.Name) {
-			continue
-		}
-		if err := spec.Shutdown(ctx); err != nil && firstErr == nil {
-			firstErr = fmt.Errorf("shutdown %s: %w", spec.Name, err)
-		}
-	}
-	return firstErr
-}
-
-// MountAll iterates the registry in order and calls Mount() on each
-// enabled subsystem.
-func MountAll(app any, cfg *Config, deps Deps) error {
-	// Sort registry by order — bubble sort, registry is tiny.
-	for i := 0; i < len(Registry); i++ {
-		for j := i + 1; j < len(Registry); j++ {
-			if Registry[j].Order < Registry[i].Order {
-				Registry[i], Registry[j] = Registry[j], Registry[i]
-			}
-		}
-	}
-
+// MountAll mounts every ENABLED subsystem in specs, in slice order — the order is
+// the composition root's (apps.Wire()); MountAll does NOT sort. app is the
+// concrete *zip.App from Serve, handed to each MountFunc as itself.
+//
+// Teardown is wired HERE, at mount time: right after a subsystem mounts, its
+// ShutdownFunc (if any) is registered via app.OnShutdown. zip drains those hooks
+// LIFO — AFTER the listeners stop accepting and in-flight requests drain — so
+// registration-at-mount yields reverse-mount teardown (a dependency mounted before
+// its dependents is torn down after them) with no subsystem torn down while a
+// request still uses it. Only ENABLED specs mount, so only they register a hook;
+// teardown needs no separate enablement gate.
+func MountAll(app *zip.App, specs []MountSpec, cfg *Config, deps Deps) error {
 	logger := deps.Logger
-	for _, spec := range Registry {
+	for _, spec := range specs {
 		if !cfg.Enabled(spec.Name) {
 			logger.Debug("subsystem disabled", "name", spec.Name)
 			continue
@@ -348,6 +710,12 @@ func MountAll(app any, cfg *Config, deps Deps) error {
 		if err := spec.Mount(app, deps); err != nil {
 			return fmt.Errorf("mount %s: %w", spec.Name, err)
 		}
+		// Register teardown as a zip shutdown hook. zip runs hooks LIFO after the
+		// drain (zip.App.Shutdown), so this reproduces the reverse-mount order the
+		// hand-rolled reverse-loop gave — without the teardown-before-drain race.
+		if spec.Shutdown != nil {
+			app.OnShutdown(spec.Shutdown)
+		}
 		logger.Info("mounted subsystem", "name", spec.Name)
 	}
 	return nil

build_aitoken_internal_test.go

@@ -0,0 +1,62 @@
+package cloud
+
+import "testing"
+
+// TestAIM2MTokenURL pins the split-horizon resolution order for the agent-runner
+// M2M token endpoint (the GAP that 502'd every POST /v1/agents/:ref/run: the
+// public issuer host is Cloudflare-fronted and 403s an in-cluster loopback with
+// edge error 1006). The runner must mint its token from an IN-CLUSTER URL. Order:
+// explicit override → in-cluster IAM_URL → public IAMIssuer fallback.
+func TestAIM2MTokenURL(t *testing.T) {
+	const tokenPath = "/v1/iam/oauth/token"
+
+	cases := []struct {
+		name      string
+		override  string // CLOUD_AI_IAM_TOKEN_URL
+		iamURL    string // IAM_URL
+		iamIssuer string // cfg.IAMIssuer
+		want      string
+	}{
+		{
+			name:     "explicit override wins over everything",
+			override: "http://iam.internal:1234/custom/token",
+			iamURL:   "http://iam.hanzo.svc",
+			// even a public issuer present must not be chosen
+			iamIssuer: "https://hanzo.id",
+			want:      "http://iam.internal:1234/custom/token",
+		},
+		{
+			name:      "in-cluster IAM_URL preferred over public issuer",
+			iamURL:    "http://iam.hanzo.svc",
+			iamIssuer: "https://hanzo.id",
+			want:      "http://iam.hanzo.svc" + tokenPath,
+		},
+		{
+			name:      "trailing slash on IAM_URL is trimmed",
+			iamURL:    "http://iam.hanzo.svc/",
+			iamIssuer: "https://hanzo.id",
+			want:      "http://iam.hanzo.svc" + tokenPath,
+		},
+		{
+			name:      "falls back to public issuer only when no in-cluster URL",
+			iamIssuer: "https://hanzo.id",
+			want:      "https://hanzo.id" + tokenPath,
+		},
+		{
+			name: "empty when no identity is resolvable (keeps M2M branch off)",
+			want: "",
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			// t.Setenv restores prior values + prevents parallel interference.
+			t.Setenv("CLOUD_AI_IAM_TOKEN_URL", tc.override)
+			t.Setenv("IAM_URL", tc.iamURL)
+			cfg := &Config{IAMIssuer: tc.iamIssuer}
+			if got := aiM2MTokenURL(cfg); got != tc.want {
+				t.Fatalf("aiM2MTokenURL() = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}

build_onshutdown_test.go

@@ -0,0 +1,203 @@
+package cloud_test
+
+import (
+	"context"
+	"net"
+	"net/http"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/hanzoai/cloud"
+	luxlog "github.com/luxfi/log"
+	"github.com/zap-proto/zip"
+)
+
+// noopMount mounts nothing: the fake specs below carry the behavior under test in
+// their Shutdown, not their Mount.
+func noopMount(*zip.App, cloud.Deps) error { return nil }
+
+// freeAddr reserves an ephemeral loopback port and hands back its address; the
+// listener is closed so the app under test can bind it.
+func freeAddr(t *testing.T) string {
+	t.Helper()
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("reserve port: %v", err)
+	}
+	addr := ln.Addr().String()
+	_ = ln.Close()
+	return addr
+}
+
+// waitListening blocks until addr accepts a TCP connection (the app's Listen
+// goroutine has bound it) or a short deadline elapses.
+func waitListening(t *testing.T, addr string) {
+	t.Helper()
+	deadline := time.Now().Add(3 * time.Second)
+	for time.Now().Before(deadline) {
+		if c, err := net.DialTimeout("tcp", addr, 100*time.Millisecond); err == nil {
+			_ = c.Close()
+			return
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	t.Fatalf("server never listened on %s", addr)
+}
+
+// TestMountAll_ShutdownHooksLIFOAfterDrain proves the OnShutdown teardown wiring:
+// MountAll registers each ENABLED subsystem's ShutdownFunc as a zip shutdown hook,
+// so on app.Shutdown they run (1) AFTER in-flight requests drain and (2) LIFO =
+// reverse-mount order (a dependency mounted before its dependents is torn down
+// after them). That is exactly the contract the deleted hand-rolled reverse-loop
+// provided by hand — now owned by zip, minus the teardown-before-drain race.
+func TestMountAll_ShutdownHooksLIFOAfterDrain(t *testing.T) {
+	app := zip.New(zip.Config{Logger: luxlog.NewNoOpLogger(), DisableStartupMessage: true})
+
+	// One monotonic tick stamps the ONLY two kinds of event we order against each
+	// other: the in-flight request finishing its drain, and each teardown hook.
+	var tick atomic.Int64
+	var mu sync.Mutex
+	teardown := map[string]int64{}
+	record := func(name string) cloud.ShutdownFunc {
+		return func(context.Context) error {
+			mu.Lock()
+			teardown[name] = tick.Add(1)
+			mu.Unlock()
+			return nil
+		}
+	}
+
+	// Mount order a, b, c ⇒ LIFO teardown must be c, b, a.
+	specs := []cloud.MountSpec{
+		{Name: "a", Mount: noopMount, Shutdown: record("a")},
+		{Name: "b", Mount: noopMount, Shutdown: record("b")},
+		{Name: "c", Mount: noopMount, Shutdown: record("c")},
+	}
+	cfg := &cloud.Config{Enable: []string{"a", "b", "c"}}
+	deps := cloud.Deps{Logger: luxlog.NewNoOpLogger()}
+
+	// A request that parks inside its handler until released, so the shutdown drain
+	// has something real to wait on. Its drain tick is stamped the instant the
+	// handler returns — i.e. the moment this request finishes draining.
+	entered := make(chan struct{})
+	release := make(chan struct{})
+	var drainTick int64
+	app.Get("/hold", func(c *zip.Ctx) error {
+		close(entered)
+		<-release
+		atomic.StoreInt64(&drainTick, tick.Add(1))
+		return c.JSON(http.StatusOK, map[string]bool{"ok": true})
+	})
+
+	if err := cloud.MountAll(app, specs, cfg, deps); err != nil {
+		t.Fatalf("MountAll: %v", err)
+	}
+
+	// Serve on a real loopback listener: an in-flight request over the HTTP
+	// transport is what zip's shutdown actually drains (closeServers → drain) in
+	// production — the path a listener-less test cannot exercise.
+	addr := freeAddr(t)
+	serveDone := make(chan error, 1)
+	go func() { serveDone <- app.Listen("http://" + addr) }()
+	waitListening(t, addr)
+
+	// Fire the request; it parks mid-handler with the connection held open.
+	reqDone := make(chan struct{})
+	go func() {
+		defer close(reqDone)
+		req, _ := http.NewRequest(http.MethodGet, "http://"+addr+"/hold", nil)
+		req.Close = true // no keep-alive: server drops the conn once the handler returns
+		client := &http.Client{Timeout: 30 * time.Second}
+		if resp, err := client.Do(req); err == nil {
+			_ = resp.Body.Close()
+		}
+	}()
+	<-entered // the request is now in-flight, parked mid-handler
+
+	// Shut down WHILE the request is in-flight. zip stops the listeners accepting,
+	// drains (blocking on our parked handler), THEN runs the hooks LIFO.
+	shutDone := make(chan error, 1)
+	go func() {
+		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+		defer cancel()
+		shutDone <- app.ShutdownWithContext(ctx)
+	}()
+
+	// Barrier: with a request still in-flight, Shutdown MUST NOT complete — it is
+	// blocked in the drain. If it returns here, teardown ran without waiting for the
+	// drain (the exact race the OnShutdown move fixes).
+	select {
+	case <-shutDone:
+		t.Fatal("Shutdown completed while a request was still in-flight — teardown did not wait for the drain")
+	case <-time.After(150 * time.Millisecond):
+	}
+
+	// Let the handler finish so the drain can complete; hooks fire only after.
+	close(release)
+
+	if err := <-shutDone; err != nil {
+		t.Fatalf("ShutdownWithContext: %v", err)
+	}
+	<-reqDone
+	<-serveDone // Listen returns once the transport listener is closed
+
+	// (1) AFTER THE DRAIN: the in-flight request finished (drainTick) strictly
+	// before ANY teardown hook ran — no hook raced a request still using it.
+	dt := atomic.LoadInt64(&drainTick)
+	if dt == 0 {
+		t.Fatal("in-flight request never drained")
+	}
+	for name, tk := range teardown {
+		if tk < dt {
+			t.Fatalf("hook %q ran at tick %d, before the drain finished at tick %d — teardown raced the still-draining request", name, tk, dt)
+		}
+	}
+
+	// (2) LIFO = reverse mount order: c (mounted last) tears down first, a last.
+	if len(teardown) != 3 {
+		t.Fatalf("want 3 hooks run, got %d (%v)", len(teardown), teardown)
+	}
+	if !(teardown["c"] < teardown["b"] && teardown["b"] < teardown["a"]) {
+		t.Fatalf("teardown not LIFO: a=%d b=%d c=%d (want c<b<a)", teardown["a"], teardown["b"], teardown["c"])
+	}
+}
+
+// TestMountAll_ShutdownRegistration_EnablementAndNil proves MountAll registers a
+// teardown hook ONLY for an ENABLED spec that HAS a ShutdownFunc: a disabled spec
+// never mounts (so never registers a hook), and an enabled spec whose Shutdown is
+// nil is skipped without panicking. This keeps the enablement axis and the nil
+// guard from silently regressing now that teardown moved onto app.OnShutdown.
+func TestMountAll_ShutdownRegistration_EnablementAndNil(t *testing.T) {
+	app := zip.New(zip.Config{Logger: luxlog.NewNoOpLogger(), DisableStartupMessage: true})
+
+	var mu sync.Mutex
+	var ran []string
+	record := func(name string) cloud.ShutdownFunc {
+		return func(context.Context) error {
+			mu.Lock()
+			ran = append(ran, name)
+			mu.Unlock()
+			return nil
+		}
+	}
+
+	specs := []cloud.MountSpec{
+		{Name: "enabled", Mount: noopMount, Shutdown: record("enabled")},
+		{Name: "disabled", Mount: noopMount, Shutdown: record("disabled")},
+		{Name: "nilsd", Mount: noopMount}, // enabled, but no Shutdown
+	}
+	cfg := &cloud.Config{Enable: []string{"enabled", "nilsd"}} // "disabled" omitted
+
+	if err := cloud.MountAll(app, specs, cfg, cloud.Deps{Logger: luxlog.NewNoOpLogger()}); err != nil {
+		t.Fatalf("MountAll: %v", err)
+	}
+	if err := app.Shutdown(); err != nil {
+		t.Fatalf("Shutdown: %v", err)
+	}
+
+	if len(ran) != 1 || ran[0] != "enabled" {
+		t.Fatalf("teardown hooks ran = %v, want [enabled] (disabled never mounts; nil Shutdown skipped)", ran)
+	}
+}

build_registration_test.go

@@ -0,0 +1,28 @@
+package cloud_test
+
+import (
+	"testing"
+
+	"github.com/hanzoai/cloud"
+	"github.com/zap-proto/zip"
+)
+
+// TestMountFunc_IsTheSubsystemSignature pins the registry's mount contract: the
+// signature every subsystem exports IS a cloud.MountFunc, checked by the compiler.
+//
+// This file used to test cloud.Typed, the adapter that took a MountFunc's `any`
+// app and asserted it back to *zip.App. Both of its tests went with it, and
+// neither is a loss:
+//
+//   - "Typed recovers the *zip.App" only ever proved the adapter handed through
+//     the value it was given. MountFunc now names *zip.App, so there is no
+//     recovery step left to get wrong.
+//   - "Typed fails closed on a wrong type" can no longer be written: passing
+//     "not-a-zip-app" to a MountFunc is a compile error, so the runtime branch it
+//     exercised does not exist. A test asserting a wrong type is rejected is
+//     precisely what a type already is.
+//
+// What remains is the only claim worth making, and the build enforces it.
+func TestMountFunc_IsTheSubsystemSignature(t *testing.T) {
+	var _ cloud.MountFunc = func(*zip.App, cloud.Deps) error { return nil }
+}

build_servicerelease_test.go

@@ -0,0 +1,43 @@
+package cloud
+
+import (
+	"context"
+	"errors"
+	"testing"
+)
+
+// TestOnServiceReleaseNoop proves the dispatch seam is a safe no-op when no
+// releaser is registered (a binary without the paas control plane co-resident) —
+// mirroring OnGitPush's contract.
+func TestOnServiceReleaseNoop(t *testing.T) {
+	RegisterServiceReleaser(nil)
+	if ServiceReleaserRegistered() {
+		t.Fatal("ServiceReleaserRegistered() = true with no releaser registered")
+	}
+	if err := OnServiceRelease(context.Background(), ServiceReleaseEvent{Service: "cloud", Image: "ghcr.io/hanzoai/cloud:v1.0.0"}); err != nil {
+		t.Fatalf("OnServiceRelease with no releaser = %v, want nil no-op", err)
+	}
+}
+
+// TestOnServiceReleaseDispatch proves a registered releaser receives the exact
+// event and its error propagates — the one inversion point paas installs.
+func TestOnServiceReleaseDispatch(t *testing.T) {
+	var got ServiceReleaseEvent
+	sentinel := errors.New("boom")
+	RegisterServiceReleaser(func(_ context.Context, ev ServiceReleaseEvent) error {
+		got = ev
+		return sentinel
+	})
+	t.Cleanup(func() { RegisterServiceReleaser(nil) })
+
+	if !ServiceReleaserRegistered() {
+		t.Fatal("ServiceReleaserRegistered() = false after registration")
+	}
+	want := ServiceReleaseEvent{Service: "hanzo-app", Image: "ghcr.io/hanzoai/hanzo-app:v1.42.15", SHA: "abc1234"}
+	if err := OnServiceRelease(context.Background(), want); !errors.Is(err, sentinel) {
+		t.Fatalf("OnServiceRelease error = %v, want sentinel", err)
+	}
+	if got != want {
+		t.Fatalf("releaser received %+v, want %+v", got, want)
+	}
+}

build_test.go

@@ -6,6 +6,11 @@ import (
 
 	"github.com/hanzoai/cloud"
 	"github.com/hanzoai/cloud/clients"
+
+	// Blank import registers the kms subsystem's client factory (init) into cloud,
+	// so BuildDeps can build the in-process deps.KMS below. cloud itself never
+	// imports clients/kms (no cloud⇄kms cycle); this external test can.
+	_ "github.com/hanzoai/cloud/clients/kms"
 )
 
 // TestBuildDeps_EnabledLeavesNil verifies that BuildDeps leaves an enabled
@@ -28,7 +33,7 @@ func TestBuildDeps_EnabledLeavesNil(t *testing.T) {
 }
 
 // TestBuildDeps_KMSEnabledIsInProcess verifies the HIP-0106 "embed KMS in cloud"
-// contract: when the kms subsystem (kmssvc) is enabled, deps.KMS is a live
+// contract: when the kms subsystem is enabled, deps.KMS is a live
 // in-process client (never nil, never a disabled stub) so other subsystems get a
 // working KMS via direct Go dispatch with no RPC. Absent a master key it still
 // resolves (health-only, fail-closed) — the point is that deps.KMS is populated.
@@ -37,12 +42,12 @@ func TestBuildDeps_KMSEnabledIsInProcess(t *testing.T) {
 		Brand:   "hanzo",
 		Domain:  "api.hanzo.ai",
 		DataDir: t.TempDir(),
-		Enable:  []string{"kmssvc"},
+		Enable:  []string{"kms"},
 	}
 	deps := cloud.BuildDeps(cfg)
 
 	if deps.KMS == nil {
-		t.Fatal("deps.KMS: enabled kmssvc must give an in-process client, got nil")
+		t.Fatal("deps.KMS: enabled kms must give an in-process client, got nil")
 	}
 	// It must NOT be the fail-closed disabled stub — that stub returns IsDisabled
 	// errors; an in-process client (no master key) returns a master-key error.

cek/cek.go

@@ -0,0 +1,830 @@
+// Package cek is cloud's ONE encryption-at-rest gate for its per-subsystem
+// SQLite stores. Every store opens its database through cek.Open — the single
+// seam where a plaintext file is transparently migrated to SQLCipher and a keyed
+// *sql.DB is returned — so "encrypted at rest" is a property of the open path,
+// not something each of the ~30 stores must remember to do.
+//
+// THREAT MODEL. The DO block volume under /var/lib/cloud is provider-encrypted,
+// so the residual exposure is a COPIED PV snapshot/backup or an in-cluster
+// exec/PV read seeing plaintext customer PII (crm), the ledger (treasury), org
+// wallet maps (wallets), the audit log, team/entitlements. cek removes that
+// exposure: each file's pages are SQLCipher-encrypted under a per-database key
+// that never leaves the process in the clear and is itself wrapped by the
+// KMS-injected master key; the pre-migration plaintext copy is shredded once the
+// encrypted store is proven readable. A lifted file is useless without the key.
+//
+// SCOPE / NON-GOALS. cek provides CONFIDENTIALITY at rest against the read-only
+// exposure above (no master key ⇒ no plaintext). It is NOT integrity,
+// authenticity, or anti-rollback against a PV-WRITE (node-compromise) adversary
+// who can modify the volume: the per-file id lives in the (unauthenticated) .dek
+// sidecar, so such an adversary could swap two of OUR OWN {db,.dek} pairs or
+// replay an old snapshot. That is outside the stated model and is deliberately
+// NOT defended here (a logical-id+epoch binding would add complexity for an
+// out-of-model threat); revisit only if tenant-isolation-under-node-compromise
+// is scoped in.
+//
+// ENVELOPE (the primitives live in github.com/hanzoai/sqlite/cek.go and are
+// reused verbatim — one crypto implementation, KAT-gated there):
+//
+//   - Each database has its OWN random 256-bit DEK (the SQLCipher page key),
+//     minted once at first touch and NEVER changed, so ciphertext pages are
+//     never rewritten.
+//   - Each database also gets a random 128-bit FILE ID, stored in the clear at
+//     the head of its <db>.dek sidecar. The KEK is derived from that id, NOT the
+//     file path: KEK = HKDF-SHA256(masterKey, lp("global") || lp(hex(fileID))).
+//     The id is intrinsic to the file and travels with the sidecar, so moving
+//     the data dir or changing CLOUD_DATA_DIR can never change the KEK and brick
+//     a store. RFC-5869 HKDF via x/crypto/hkdf — NOT luxfi/crypto/kdf (a QZMQ
+//     KeySchedule, not generic HKDF; using it would brick every store).
+//   - The DEK is wrapped AES-256-GCM under the KEK, bound to the same id as AAD.
+//     Sidecar = fileID(16) || wrapped-DEK. The raw DEK is never written.
+//   - Master-key ROTATION rewraps only the sidecar: the DEK and fileID are
+//     unchanged, so no page is rewritten and no file can be bricked.
+//
+// FAIL-SECURE. On an encryption-CAPABLE build (production is CGO + libsqlcipher)
+// a missing master key is FATAL — the data plane refuses to open unencrypted,
+// the same posture the KMS store takes. A key set on a NON-encrypting build is
+// likewise fatal. An encrypted file whose sidecar is missing is refused. A
+// migration whose encrypted copy does not reproduce the source's schema AND
+// per-table content (a rowid-independent multiset hash, not just a row count)
+// leaves the plaintext untouched and errors — the caller (MountAll) fails
+// closed, so cloud never serves a half-migrated data plane.
+package cek
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"database/sql"
+	"encoding/base64"
+	"encoding/binary"
+	"encoding/hex"
+	"fmt"
+	"hash"
+	"math"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"sync"
+	"syscall"
+	"time"
+
+	sqlitedrv "github.com/hanzoai/sqlite"
+)
+
+// masterKeyEnv is the ONE variable that supplies the 32-byte KMS master key
+// (base64), matching the operator Deployment and clients/kms. No second gate.
+const masterKeyEnv = "CLOUD_KMS_MASTER_KEY_REF"
+
+const (
+	dekSuffix      = ".dek"       // sidecar: fileID(16) || wrapped-DEK
+	lockSuffix     = ".cek.lock"  // per-db flock guarding first-touch + migration
+	tmpSuffix      = ".cek.tmp"   // in-progress encrypted target (same volume → atomic rename)
+	plainBakSuffix = ".plain.bak" // transient pre-migration plaintext; SHREDDED after verified open
+
+	sqliteMagic = "SQLite format 3\x00" // 16-byte header of an UNENCRYPTED db
+	headerLen   = 16
+	fileIDLen   = 16 // random per-file KEK-derivation id, stored in the sidecar head
+)
+
+// principalType domain-separates cloud's platform databases from IAM's org/user
+// stores in the shared HKDF namespace.
+const principalType = sqlitedrv.PrincipalGlobal
+
+var (
+	masterOnce     sync.Once
+	masterKey      []byte
+	masterErr      error
+	masterOverride []byte
+)
+
+// SetMasterKey injects the 32-byte master key explicitly (cloud's boot resolves
+// it once from cfg and hands it here), taking precedence over the environment.
+// Call before the first Open. A wrong-length key is ignored so the env path can
+// still apply.
+func SetMasterKey(k []byte) {
+	if len(k) == 32 {
+		masterOverride = append([]byte(nil), k...)
+	}
+}
+
+// resolveMaster resolves the process master key exactly once:
+//
+//	(key, nil)   — 32-byte key AND an encryption-capable build → encrypt.
+//	(nil, nil)   — no key AND a non-encrypting (pure-Go) build → dev/CI plaintext.
+//	(nil, error) — key malformed; OR key set on a non-encrypting build; OR NO key
+//	               on an encryption-capable build. The last is the production
+//	               fail-closed: a capable binary never silently ships plaintext.
+func resolveMaster() ([]byte, error) {
+	masterOnce.Do(func() {
+		raw := masterOverride
+		if len(raw) == 0 {
+			b64 := strings.TrimSpace(os.Getenv(masterKeyEnv))
+			if b64 == "" {
+				if sqlitedrv.EncryptionAvailable() {
+					masterErr = fmt.Errorf("cek: %s is required on an encryption-capable build; "+
+						"refusing to open the data plane unencrypted (set the KMS master key, "+
+						"or run a pure-Go dev build)", masterKeyEnv)
+				}
+				return // pure-Go dev/CI: plaintext is expected (no codec linked)
+			}
+			decoded, err := base64.StdEncoding.DecodeString(b64)
+			if err != nil {
+				masterErr = fmt.Errorf("cek: %s is not valid base64: %w", masterKeyEnv, err)
+				return
+			}
+			raw = decoded
+		}
+		if len(raw) != 32 {
+			masterErr = fmt.Errorf("cek: master key must decode to 32 bytes, got %d", len(raw))
+			return
+		}
+		if !sqlitedrv.EncryptionAvailable() {
+			masterErr = fmt.Errorf("cek: %s is set but this build cannot encrypt (pure-Go sqlite); "+
+				"rebuild CGO_ENABLED=1 linked against libsqlcipher, or unset it for a dev build", masterKeyEnv)
+			return
+		}
+		masterKey = raw
+	})
+	return masterKey, masterErr
+}
+
+// Encrypting reports whether cek will encrypt at rest (a valid master key is
+// configured on an encryption-capable build). cloud calls this once at boot for
+// the posture log; a false result on a capable build means resolveMaster errored
+// and the first store Open will fail closed.
+func Encrypting() bool {
+	k, err := resolveMaster()
+	return err == nil && len(k) == 32
+}
+
+// Open returns a *sql.DB for the SQLite database at path, encrypted at rest when
+// a master key is configured. It is the single drop-in replacement for
+// sql.Open("sqlite", path) across every cloud store.
+func Open(path string) (*sql.DB, error) {
+	master, err := resolveMaster()
+	if err != nil {
+		return nil, err
+	}
+	if master == nil {
+		// Only reachable on a non-encrypting dev/CI build (a capable build with no
+		// key already errored above). Preserve the prior bare-path behavior.
+		return sql.Open("sqlite", path)
+	}
+	return openEncrypted(path, master)
+}
+
+func openEncrypted(path string, master []byte) (*sql.DB, error) {
+	unlock, err := flock(path)
+	if err != nil {
+		return nil, err
+	}
+	defer unlock()
+
+	if err := recoverInterrupted(path); err != nil {
+		return nil, err
+	}
+
+	var db *sql.DB
+	switch classify(path) {
+	case stateFresh:
+		db, err = createFresh(path, master)
+	case stateEncrypted:
+		db, err = openExisting(path, master)
+	default: // statePlaintext
+		db, err = migrateThenOpen(path, master)
+	}
+	if err != nil {
+		return nil, err
+	}
+	// No plaintext replica may survive a successful keyed open: shred any backup
+	// left by this (or a crashed prior) migration. THIS is the security objective.
+	shredPlainBak(path)
+	return db, nil
+}
+
+type fileState int
+
+const (
+	stateFresh     fileState = iota // absent or too small to be a real db → mint
+	statePlaintext                  // "SQLite format 3\0" header → migrate
+	stateEncrypted                  // db-sized, non-magic header → SQLCipher, open via sidecar
+)
+
+func classify(path string) fileState {
+	fi, err := os.Stat(path)
+	if err != nil || fi.Size() < headerLen {
+		return stateFresh
+	}
+	if isPlaintextHeader(path) {
+		return statePlaintext
+	}
+	return stateEncrypted
+}
+
+func isPlaintextHeader(path string) bool {
+	f, err := os.Open(path)
+	if err != nil {
+		return false
+	}
+	defer func() { _ = f.Close() }()
+	var hdr [headerLen]byte
+	if _, err := f.ReadAt(hdr[:], 0); err != nil {
+		return false
+	}
+	return string(hdr[:]) == sqliteMagic
+}
+
+// ── sidecar: fileID(16) || wrapped-DEK ───────────────────────────────────────
+
+// mintSidecar generates a fresh fileID + DEK, wraps the DEK under the id-derived
+// KEK, and returns the DEK and the sidecar bytes to persist.
+func mintSidecar(master []byte) (dek, sidecar []byte, err error) {
+	fileID := make([]byte, fileIDLen)
+	if _, err = rand.Read(fileID); err != nil {
+		return nil, nil, fmt.Errorf("cek: generate file id: %w", err)
+	}
+	kek, aad, err := deriveFor(master, fileID)
+	if err != nil {
+		return nil, nil, err
+	}
+	defer zero(kek)
+	if dek, err = sqlitedrv.NewDEK(); err != nil {
+		return nil, nil, fmt.Errorf("cek: new DEK: %w", err)
+	}
+	wrapped, err := sqlitedrv.WrapDEK(kek, dek, aad)
+	if err != nil {
+		zero(dek)
+		return nil, nil, fmt.Errorf("cek: wrap DEK: %w", err)
+	}
+	sidecar = append(append(make([]byte, 0, fileIDLen+len(wrapped)), fileID...), wrapped...)
+	return dek, sidecar, nil
+}
+
+// unwrapSidecar reads the fileID from the sidecar head and unwraps the DEK under
+// the id-derived KEK. A wrong master key, tampered blob, or truncated sidecar
+// fails the GCM tag and errors — never a partial/garbage key.
+func unwrapSidecar(master, sidecar []byte) ([]byte, error) {
+	if len(sidecar) <= fileIDLen {
+		return nil, fmt.Errorf("cek: sidecar too short (%d bytes)", len(sidecar))
+	}
+	fileID, wrapped := sidecar[:fileIDLen], sidecar[fileIDLen:]
+	kek, aad, err := deriveFor(master, fileID)
+	if err != nil {
+		return nil, err
+	}
+	defer zero(kek)
+	dek, err := sqlitedrv.UnwrapDEK(kek, wrapped, aad)
+	if err != nil {
+		return nil, fmt.Errorf("cek: unwrap DEK (wrong master key or corrupt sidecar): %w", err)
+	}
+	return dek, nil
+}
+
+// deriveFor derives the KEK and the wrap-AAD for a file id. Both bind to
+// hex(fileID) so the id — not any path or config value — is the sole identity.
+func deriveFor(master, fileID []byte) (kek, aad []byte, err error) {
+	id := hex.EncodeToString(fileID)
+	kek, err = sqlitedrv.DeriveKey(master, principalType, id)
+	if err != nil {
+		return nil, nil, fmt.Errorf("cek: derive KEK: %w", err)
+	}
+	return kek, sqlitedrv.PrincipalAAD(principalType, id), nil
+}
+
+// ── open paths ───────────────────────────────────────────────────────────────
+
+func createFresh(path string, master []byte) (*sql.DB, error) {
+	dekPath := path + dekSuffix
+	if fileExists(dekPath) {
+		return openExisting(path, master) // a concurrent first-touch won the lock
+	}
+	dek, sidecar, err := mintSidecar(master)
+	if err != nil {
+		return nil, err
+	}
+	defer zero(dek)
+	if err := writeFileAtomic(dekPath, sidecar, 0o600); err != nil {
+		return nil, err
+	}
+	db, err := openKeyed(path, dek)
+	if err != nil {
+		return nil, fmt.Errorf("cek: create encrypted %q: %w", path, err)
+	}
+	return db, nil
+}
+
+func openExisting(path string, master []byte) (*sql.DB, error) {
+	dekPath := path + dekSuffix
+	sidecar, err := os.ReadFile(dekPath)
+	if err != nil {
+		return nil, fmt.Errorf("cek: read sidecar %q (encrypted db, refusing to open blind): %w", dekPath, err)
+	}
+	dek, err := unwrapSidecar(master, sidecar)
+	if err != nil {
+		return nil, err
+	}
+	defer zero(dek)
+	db, err := openKeyed(path, dek)
+	if err != nil {
+		return nil, fmt.Errorf("cek: open encrypted %q: %w", path, err)
+	}
+	return db, nil
+}
+
+// migrateThenOpen converts an existing PLAINTEXT database to SQLCipher without
+// losing a row, then opens it. Crash-safe (plaintext is the source of truth
+// until an atomic rename commits) and fail-secure (the swap happens only after
+// the encrypted copy reproduces the source schema + per-table content hash +
+// integrity_check, re-opened via the exact keyed path the app uses).
+func migrateThenOpen(path string, master []byte) (*sql.DB, error) {
+	dekPath := path + dekSuffix
+	// Plaintext header ⇒ an earlier attempt did not commit: discard any stale
+	// sidecar/tmp and redo from the plaintext source of truth.
+	_ = os.Remove(dekPath)
+	tmp := path + tmpSuffix
+	removeDBFiles(tmp)
+
+	dek, sidecar, err := mintSidecar(master)
+	if err != nil {
+		return nil, err
+	}
+	defer zero(dek)
+
+	srcInv, err := exportPlaintext(path, tmp, dek)
+	if err != nil {
+		removeDBFiles(tmp)
+		return nil, err
+	}
+
+	if isPlaintextHeader(tmp) {
+		removeDBFiles(tmp)
+		return nil, fmt.Errorf("cek: migration of %q produced a plaintext file (SQLCipher not linked?)", path)
+	}
+	if err := verifyParity(tmp, dek, srcInv); err != nil {
+		removeDBFiles(tmp)
+		return nil, fmt.Errorf("cek: migration parity check failed for %q (plaintext left intact): %w", path, err)
+	}
+
+	// Commit. Order for crash-safety:
+	//  1. sidecar (the encrypted db's key),
+	//  2. plaintext → <db>.plain.bak,
+	//  3. delete the now-orphaned plaintext -wal/-shm (WAL was checkpoint-folded
+	//     into the main file, so .plain.bak is complete; removing them now closes
+	//     the window where a stale plaintext WAL sits beside the encrypted db),
+	//  4. atomic rename tmp → path.
+	// A crash between any two steps is resolved by recoverInterrupted on reboot.
+	if err := writeFileAtomic(dekPath, sidecar, 0o600); err != nil {
+		removeDBFiles(tmp)
+		return nil, err
+	}
+	if err := os.Rename(path, path+plainBakSuffix); err != nil {
+		removeDBFiles(tmp)
+		_ = os.Remove(dekPath)
+		return nil, fmt.Errorf("cek: preserve plaintext backup for %q: %w", path, err)
+	}
+	_ = os.Remove(path + "-wal")
+	_ = os.Remove(path + "-shm")
+	if err := os.Rename(tmp, path); err != nil {
+		_ = os.Rename(path+plainBakSuffix, path) // roll back
+		_ = os.Remove(dekPath)
+		return nil, fmt.Errorf("cek: swap encrypted %q into place: %w", path, err)
+	}
+	syncDir(filepath.Dir(path))
+
+	db, err := openKeyed(path, dek)
+	if err != nil {
+		return nil, fmt.Errorf("cek: open migrated %q: %w", path, err)
+	}
+	return db, nil // openEncrypted's tail shreds .plain.bak after this succeeds
+}
+
+// exportPlaintext opens the plaintext source, folds its WAL into the main file
+// (crm.db/audit.db carry MB of live WAL), records the source inventory for the
+// parity check, and copies every page into a fresh SQLCipher database at tmp via
+// SQLCipher's own sqlcipher_export with the format compat pinned. The source is
+// only read.
+func exportPlaintext(path, tmp string, dek []byte) (inventory, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Minute)
+	defer cancel()
+
+	src, err := sql.Open("sqlite", sqlitedrv.DSN(path, nil))
+	if err != nil {
+		return inventory{}, fmt.Errorf("cek: open plaintext %q: %w", path, err)
+	}
+	defer func() { _ = src.Close() }()
+	src.SetMaxOpenConns(1) // ATTACH + sqlcipher_export must run on ONE connection
+
+	conn, err := src.Conn(ctx)
+	if err != nil {
+		return inventory{}, fmt.Errorf("cek: acquire conn for %q: %w", path, err)
+	}
+	defer func() { _ = conn.Close() }()
+
+	if _, err := conn.ExecContext(ctx, "PRAGMA wal_checkpoint(TRUNCATE)"); err != nil {
+		return inventory{}, fmt.Errorf("cek: checkpoint %q: %w", path, err)
+	}
+	srcInv, err := readInventory(ctx, conn)
+	if err != nil {
+		return inventory{}, fmt.Errorf("cek: inventory source %q: %w", path, err)
+	}
+
+	// The DEK is crypto/rand hex — no injection surface; the path is a bound
+	// parameter. The reopen-via-openKeyed parity check downstream is the
+	// authoritative guard that the copy opens under the app's exact keyed path.
+	// The target is created at the runtime's SQLCipher format (the frozen
+	// libsqlcipher default), which is exactly what openKeyed reopens it under.
+	attach := fmt.Sprintf(`ATTACH DATABASE ? AS enc KEY "x'%x'"`, dek)
+	if _, err := conn.ExecContext(ctx, attach, tmp); err != nil {
+		return inventory{}, fmt.Errorf("cek: attach encrypted target: %w", err)
+	}
+	if _, err := conn.ExecContext(ctx, "SELECT sqlcipher_export('enc')"); err != nil {
+		_, _ = conn.ExecContext(ctx, "DETACH DATABASE enc")
+		return inventory{}, fmt.Errorf("cek: sqlcipher_export: %w", err)
+	}
+	if _, err := conn.ExecContext(ctx, "DETACH DATABASE enc"); err != nil {
+		return inventory{}, fmt.Errorf("cek: detach encrypted target: %w", err)
+	}
+	return srcInv, nil
+}
+
+// verifyParity re-opens the encrypted copy exactly as the running app will
+// (openKeyed) and asserts: integrity_check ok, identical schema fingerprint, and
+// — per table — identical row count AND identical rowid-independent content hash.
+// The content hash (a commutative multiset sum of per-row hashes over the USER
+// columns) is what backs the zero-loss claim: it catches any value change, NULL
+// coercion, or row add/drop that count + schema + integrity_check miss, while
+// correctly ignoring the benign implicit-rowid renumbering sqlcipher_export does.
+// It runs BEFORE the atomic swap, so any discrepancy leaves the plaintext intact.
+func verifyParity(tmp string, dek []byte, src inventory) error {
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Minute)
+	defer cancel()
+
+	db, err := openKeyed(tmp, dek)
+	if err != nil {
+		return fmt.Errorf("reopen encrypted copy: %w", err)
+	}
+	defer func() { _ = db.Close() }()
+	db.SetMaxOpenConns(1)
+	if err := db.PingContext(ctx); err != nil {
+		return fmt.Errorf("ping encrypted copy (key/compat mismatch?): %w", err)
+	}
+
+	var ic string
+	if err := db.QueryRowContext(ctx, "PRAGMA integrity_check").Scan(&ic); err != nil {
+		return fmt.Errorf("integrity_check: %w", err)
+	}
+	if ic != "ok" {
+		return fmt.Errorf("integrity_check returned %q", ic)
+	}
+
+	conn, err := db.Conn(ctx)
+	if err != nil {
+		return fmt.Errorf("acquire verify conn: %w", err)
+	}
+	defer func() { _ = conn.Close() }()
+	dst, err := readInventory(ctx, conn)
+	if err != nil {
+		return fmt.Errorf("inventory encrypted copy: %w", err)
+	}
+	if dst.schema != src.schema {
+		return fmt.Errorf("schema fingerprint mismatch")
+	}
+	if len(dst.tables) != len(src.tables) {
+		return fmt.Errorf("table set mismatch: src %d tables, dst %d", len(src.tables), len(dst.tables))
+	}
+	for tbl, s := range src.tables {
+		d, ok := dst.tables[tbl]
+		if !ok {
+			return fmt.Errorf("table %q missing in encrypted copy", tbl)
+		}
+		if d.count != s.count {
+			return fmt.Errorf("row-count mismatch in %q: src %d, dst %d", tbl, s.count, d.count)
+		}
+		if d.content != s.content {
+			return fmt.Errorf("content-hash mismatch in %q (row values differ despite equal count)", tbl)
+		}
+	}
+	return nil
+}
+
+// inventory is the parity fingerprint: a schema hash plus, per table, a row count
+// and a content hash.
+type inventory struct {
+	schema [32]byte
+	tables map[string]tableStat
+}
+
+type tableStat struct {
+	count   int64
+	content [32]byte // commutative multiset sum of per-row hashes over user columns
+}
+
+func readInventory(ctx context.Context, conn *sql.Conn) (inventory, error) {
+	rows, err := conn.QueryContext(ctx,
+		`SELECT type,name,COALESCE(tbl_name,''),COALESCE(sql,'') FROM sqlite_master `+
+			`WHERE name NOT LIKE 'sqlite_%' ORDER BY type,name`)
+	if err != nil {
+		return inventory{}, err
+	}
+	var schemaLines, tables []string
+	for rows.Next() {
+		var typ, name, tbl, ddl string
+		if err := rows.Scan(&typ, &name, &tbl, &ddl); err != nil {
+			_ = rows.Close()
+			return inventory{}, err
+		}
+		schemaLines = append(schemaLines, typ+"\x1f"+name+"\x1f"+tbl+"\x1f"+ddl)
+		if typ == "table" {
+			tables = append(tables, name)
+		}
+	}
+	if err := rows.Err(); err != nil {
+		_ = rows.Close()
+		return inventory{}, err
+	}
+	_ = rows.Close()
+
+	sort.Strings(schemaLines)
+	h := sha256.New()
+	for _, l := range schemaLines {
+		writeLP(h, []byte(l))
+	}
+	inv := inventory{tables: make(map[string]tableStat, len(tables))}
+	copy(inv.schema[:], h.Sum(nil))
+
+	for _, tbl := range tables {
+		st, err := tableContent(ctx, conn, tbl)
+		if err != nil {
+			return inventory{}, fmt.Errorf("content %q: %w", tbl, err)
+		}
+		inv.tables[tbl] = st
+	}
+	return inv, nil
+}
+
+// tableContent streams every row of a table and folds a per-row hash (over the
+// user columns, faithfully distinguishing NULL / "" / 0 / storage class) into a
+// commutative 256-bit sum. Order-independent (survives rowid-driven scan-order
+// differences) and duplicate-safe (addition, not XOR). O(1) memory per table.
+func tableContent(ctx context.Context, conn *sql.Conn, tbl string) (tableStat, error) {
+	q := `SELECT * FROM "` + strings.ReplaceAll(tbl, `"`, `""`) + `"`
+	rows, err := conn.QueryContext(ctx, q)
+	if err != nil {
+		return tableStat{}, err
+	}
+	defer func() { _ = rows.Close() }()
+	cols, err := rows.Columns()
+	if err != nil {
+		return tableStat{}, err
+	}
+	var st tableStat
+	scan := make([]any, len(cols))
+	ptrs := make([]any, len(cols))
+	for i := range scan {
+		ptrs[i] = &scan[i]
+	}
+	for rows.Next() {
+		if err := rows.Scan(ptrs...); err != nil {
+			return tableStat{}, err
+		}
+		rh := sha256.New()
+		for _, v := range scan {
+			encodeValue(rh, v)
+		}
+		var row [32]byte
+		copy(row[:], rh.Sum(nil))
+		addInto(&st.content, row)
+		st.count++
+	}
+	return st, rows.Err()
+}
+
+// encodeValue writes a type-tagged, length-prefixed, NULL-sentinel encoding of a
+// scanned SQLite value so two logically-equal rows hash identically and a NULL
+// never collides with "" or 0.
+func encodeValue(h hash.Hash, v any) {
+	switch x := v.(type) {
+	case nil:
+		h.Write([]byte{0})
+	case int64:
+		var b [8]byte
+		binary.BigEndian.PutUint64(b[:], uint64(x))
+		h.Write([]byte{1})
+		h.Write(b[:])
+	case float64:
+		var b [8]byte
+		binary.BigEndian.PutUint64(b[:], math.Float64bits(x))
+		h.Write([]byte{2})
+		h.Write(b[:])
+	case bool:
+		h.Write([]byte{3})
+		if x {
+			h.Write([]byte{1})
+		} else {
+			h.Write([]byte{0})
+		}
+	case []byte:
+		h.Write([]byte{4})
+		writeLP(h, x)
+	case string:
+		h.Write([]byte{5})
+		writeLP(h, []byte(x))
+	case time.Time:
+		h.Write([]byte{6})
+		var b [8]byte
+		binary.BigEndian.PutUint64(b[:], uint64(x.UnixNano()))
+		h.Write(b[:])
+	default:
+		h.Write([]byte{9})
+		writeLP(h, []byte(fmt.Sprintf("%v", x)))
+	}
+}
+
+// writeLP writes an 8-byte big-endian length prefix then the bytes, so
+// concatenations are unambiguous.
+func writeLP(h hash.Hash, b []byte) {
+	var n [8]byte
+	binary.BigEndian.PutUint64(n[:], uint64(len(b)))
+	h.Write(n[:])
+	h.Write(b)
+}
+
+// addInto computes acc = (acc + row) mod 2^256, big-endian — the commutative,
+// duplicate-safe multiset combiner.
+func addInto(acc *[32]byte, row [32]byte) {
+	var carry uint16
+	for i := 31; i >= 0; i-- {
+		s := uint16(acc[i]) + uint16(row[i]) + carry
+		acc[i] = byte(s)
+		carry = s >> 8
+	}
+}
+
+// recoverInterrupted resumes a migration that crashed between the commit steps,
+// keying only on files (no config). It also scrubs any stale plaintext -wal/-shm
+// so a half-committed state can never leave one beside an encrypted db.
+func recoverInterrupted(path string) error {
+	dekPath := path + dekSuffix
+	tmp := path + tmpSuffix
+	if fileExists(path) {
+		// If the live file is already encrypted, a leftover tmp is a dead
+		// migration attempt — discard it. (A plaintext live file is handled by
+		// migrateThenOpen, which clears tmp itself.)
+		if !isPlaintextHeader(path) {
+			removeDBFiles(tmp)
+		}
+		return nil
+	}
+	switch {
+	case fileExists(tmp) && fileExists(dekPath):
+		// Crashed after the sidecar+backup were written but before/during the swap
+		// rename: finish it. The sidecar matches tmp.
+		if err := os.Rename(tmp, path); err != nil {
+			return fmt.Errorf("cek: resume migration swap for %q: %w", path, err)
+		}
+		_ = os.Remove(path + "-wal")
+		_ = os.Remove(path + "-shm")
+		syncDir(filepath.Dir(path))
+	case fileExists(path + plainBakSuffix):
+		// Swap never happened; restore the plaintext original for a clean redo.
+		if err := os.Rename(path+plainBakSuffix, path); err != nil {
+			return fmt.Errorf("cek: restore plaintext backup for %q: %w", path, err)
+		}
+		removeDBFiles(tmp)
+		_ = os.Remove(dekPath)
+	}
+	return nil
+}
+
+// openKeyed opens a keyed SQLCipher database via the driver's ONE blessed keyed
+// open (the key rides the URI so it is applied at sqlite3_open_v2, before mattn's
+// pragma battery touches the header — a post-open PRAGMA key would be too late).
+//
+// CROSS-VERSION SAFETY. SQLCipher's on-disk format is fixed by the libsqlcipher
+// major the arcd image links; that version is FROZEN in the Dockerfile (see the
+// runbook) so an image rebuild cannot silently change the default cipher format
+// and orphan a store. An at-open `cipher_compatibility` pin is NOT usable here
+// (the URI param is silently ignored, and a post-open pragma runs after mattn has
+// already read the header) — the version freeze is the control. If a mismatch
+// ever occurs it FAILS CLOSED: openExisting returns "file is not a database" and
+// MountAll aborts — never a silent downgrade or corruption.
+func openKeyed(path string, dek []byte) (*sql.DB, error) {
+	db, err := sqlitedrv.OpenDB(path, dek)
+	if err != nil {
+		return nil, fmt.Errorf("cek: open keyed %q: %w", path, err) // no dsn (holds key)
+	}
+	return db, nil
+}
+
+// ── shred + boring helpers ───────────────────────────────────────────────────
+
+// shredPlainBak overwrites and removes the transient pre-migration plaintext
+// backup once the encrypted store is proven readable. Overwrite-then-remove is
+// defense-in-depth (best-effort on a copy-on-write/journalled fs; the block
+// volume is provider-encrypted regardless). Idempotent no-op when absent.
+func shredPlainBak(path string) {
+	bak := path + plainBakSuffix
+	fi, err := os.Stat(bak)
+	if err != nil {
+		return
+	}
+	if f, err := os.OpenFile(bak, os.O_WRONLY, 0); err == nil {
+		overwrite(f, fi.Size())
+		_ = f.Sync()
+		_ = f.Close()
+	}
+	_ = os.Remove(bak)
+}
+
+func overwrite(f *os.File, size int64) {
+	const chunk = 1 << 20
+	buf := make([]byte, chunk)
+	for remaining := size; remaining > 0; {
+		n := int64(chunk)
+		if remaining < n {
+			n = remaining
+		}
+		if _, err := rand.Read(buf[:n]); err != nil {
+			return
+		}
+		if _, err := f.Write(buf[:n]); err != nil {
+			return
+		}
+		remaining -= n
+	}
+}
+
+func fileExists(p string) bool {
+	_, err := os.Stat(p)
+	return err == nil
+}
+
+func removeDBFiles(base string) {
+	for _, s := range []string{"", "-wal", "-shm"} {
+		_ = os.Remove(base + s)
+	}
+}
+
+func writeFileAtomic(dst string, data []byte, perm os.FileMode) error {
+	tmp := dst + ".tmp"
+	f, err := os.OpenFile(tmp, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, perm)
+	if err != nil {
+		return fmt.Errorf("cek: create %q: %w", tmp, err)
+	}
+	if _, err := f.Write(data); err != nil {
+		_ = f.Close()
+		_ = os.Remove(tmp)
+		return fmt.Errorf("cek: write %q: %w", tmp, err)
+	}
+	if err := f.Sync(); err != nil {
+		_ = f.Close()
+		_ = os.Remove(tmp)
+		return fmt.Errorf("cek: sync %q: %w", tmp, err)
+	}
+	if err := f.Close(); err != nil {
+		_ = os.Remove(tmp)
+		return fmt.Errorf("cek: close %q: %w", tmp, err)
+	}
+	if err := os.Rename(tmp, dst); err != nil {
+		_ = os.Remove(tmp)
+		return fmt.Errorf("cek: rename %q→%q: %w", tmp, dst, err)
+	}
+	return nil
+}
+
+func syncDir(dir string) {
+	if d, err := os.Open(dir); err == nil {
+		_ = d.Sync()
+		_ = d.Close()
+	}
+}
+
+// flock takes an exclusive advisory lock on <path>.cek.lock, serializing
+// first-touch and migration for the SAME database across processes/goroutines
+// (different databases never contend). Returns an unlock func.
+func flock(path string) (func(), error) {
+	lockPath := path + lockSuffix
+	if err := os.MkdirAll(filepath.Dir(lockPath), 0o700); err != nil {
+		return nil, fmt.Errorf("cek: create lock dir: %w", err)
+	}
+	f, err := os.OpenFile(lockPath, os.O_CREATE|os.O_RDWR, 0o600)
+	if err != nil {
+		return nil, fmt.Errorf("cek: open lock %q: %w", lockPath, err)
+	}
+	if err := syscall.Flock(int(f.Fd()), syscall.LOCK_EX); err != nil {
+		_ = f.Close()
+		return nil, fmt.Errorf("cek: acquire lock %q: %w", lockPath, err)
+	}
+	return func() {
+		_ = syscall.Flock(int(f.Fd()), syscall.LOCK_UN)
+		_ = f.Close()
+	}, nil
+}
+
+func zero(b []byte) {
+	for i := range b {
+		b[i] = 0
+	}
+}

cek/cek_test.go

@@ -0,0 +1,439 @@
+package cek
+
+import (
+	"context"
+	"database/sql"
+	"encoding/hex"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+
+	sqlitedrv "github.com/hanzoai/sqlite"
+)
+
+// resetMaster clears the once-resolved master so a test can choose a posture.
+// White-box tests only; production never resets.
+func resetMaster(key []byte) {
+	masterOnce = sync.Once{}
+	masterKey = nil
+	masterErr = nil
+	masterOverride = nil
+	if key != nil {
+		SetMasterKey(key)
+	}
+}
+
+func testMaster(t *testing.T) []byte {
+	t.Helper()
+	k := make([]byte, 32)
+	for i := range k {
+		k[i] = byte(i*7 + 1)
+	}
+	return k
+}
+
+// requireCipher skips when the build cannot produce REAL ciphertext (a mis-linked
+// cgo build silently writes plaintext), probing rather than trusting the flag.
+// With SQLITE_REQUIRE_CODEC=1 (the Docker image build sets it) a would-be skip
+// becomes a FAILURE, so the in-image gate is airtight standalone.
+func requireCipher(t *testing.T) {
+	t.Helper()
+	skipOrFail := func(msg string) {
+		if os.Getenv("SQLITE_REQUIRE_CODEC") == "1" {
+			t.Fatal(msg)
+		}
+		t.Skip(msg)
+	}
+	if !sqlitedrv.EncryptionAvailable() {
+		skipOrFail("sqlite build cannot encrypt (pure-Go); run with CGO + libsqlcipher")
+		return
+	}
+	probe := filepath.Join(t.TempDir(), "probe.db")
+	dek, _ := sqlitedrv.NewDEK()
+	db, err := openKeyed(probe, dek)
+	if err != nil {
+		t.Fatalf("probe open: %v", err)
+	}
+	if _, err := db.Exec(`CREATE TABLE t(x)`); err != nil {
+		t.Fatalf("probe ddl: %v", err)
+	}
+	_ = db.Close()
+	if isPlaintextHeader(probe) {
+		skipOrFail("cgo build is NOT linked against libsqlcipher (keyed db is plaintext)")
+		return
+	}
+}
+
+// makePlaintextDB writes a genuine UNENCRYPTED SQLite db with known rows in WAL
+// mode (exercising exportPlaintext's WAL fold), returning per-table row counts.
+func makePlaintextDB(t *testing.T, path string, companies, contacts int) map[string]int64 {
+	t.Helper()
+	db, err := sql.Open("sqlite", path)
+	if err != nil {
+		t.Fatalf("open plaintext: %v", err)
+	}
+	for _, p := range []string{"PRAGMA journal_mode=WAL", "PRAGMA wal_autocheckpoint=0"} {
+		if _, err := db.Exec(p); err != nil {
+			t.Fatalf("pragma %q: %v", p, err)
+		}
+	}
+	if _, err := db.Exec(`
+CREATE TABLE crm_companies(id TEXT PRIMARY KEY, org TEXT, name TEXT, arr INTEGER);
+CREATE INDEX ix_co_org ON crm_companies(org);
+CREATE TABLE crm_contacts(id TEXT PRIMARY KEY, org TEXT, email TEXT, note TEXT);`); err != nil {
+		t.Fatalf("ddl: %v", err)
+	}
+	for i := 0; i < companies; i++ {
+		if _, err := db.Exec(`INSERT INTO crm_companies VALUES(?,?,?,?)`,
+			fmt.Sprintf("co-%d", i), "maxpower", fmt.Sprintf("Co %d", i), int64(i*1000)); err != nil {
+			t.Fatalf("insert company: %v", err)
+		}
+	}
+	for i := 0; i < contacts; i++ {
+		// note is NULL on evens to exercise NULL fidelity in the content hash.
+		if i%2 == 0 {
+			_, err = db.Exec(`INSERT INTO crm_contacts(id,org,email) VALUES(?,?,?)`,
+				fmt.Sprintf("ct-%d", i), "maxpower", fmt.Sprintf("u%d@x.io", i))
+		} else {
+			_, err = db.Exec(`INSERT INTO crm_contacts VALUES(?,?,?,?)`,
+				fmt.Sprintf("ct-%d", i), "maxpower", fmt.Sprintf("u%d@x.io", i), "vip")
+		}
+		if err != nil {
+			t.Fatalf("insert contact: %v", err)
+		}
+	}
+	if !isPlaintextHeader(path) {
+		t.Fatalf("precondition: freshly created db is not plaintext")
+	}
+	_ = db.Close()
+	return map[string]int64{"crm_companies": int64(companies), "crm_contacts": int64(contacts)}
+}
+
+func rowCount(t *testing.T, db *sql.DB, table string) int64 {
+	t.Helper()
+	var n int64
+	if err := db.QueryRow(`SELECT COUNT(*) FROM ` + table).Scan(&n); err != nil {
+		t.Fatalf("count %s: %v", table, err)
+	}
+	return n
+}
+
+func firstBytes(t *testing.T, path string, n int) []byte {
+	t.Helper()
+	f, err := os.Open(path)
+	if err != nil {
+		t.Fatalf("open %s: %v", path, err)
+	}
+	defer func() { _ = f.Close() }()
+	b := make([]byte, n)
+	if _, err := f.ReadAt(b, 0); err != nil {
+		t.Fatalf("read %s: %v", path, err)
+	}
+	return b
+}
+
+// TestMigratePlaintextToCipher is the keystone: plaintext → SQLCipher with a
+// ciphertext header, exact row parity, an unwrappable sidecar, readable data,
+// and — per RED HIGH — NO surviving plaintext backup (shredded after verify).
+func TestMigratePlaintextToCipher(t *testing.T) {
+	requireCipher(t)
+	dir := t.TempDir()
+	path := filepath.Join(dir, "crm.db")
+	want := makePlaintextDB(t, path, 37, 91)
+
+	resetMaster(testMaster(t))
+	db, err := Open(path)
+	if err != nil {
+		t.Fatalf("cek.Open (migrate): %v", err)
+	}
+	defer func() { _ = db.Close() }()
+
+	if isPlaintextHeader(path) {
+		t.Fatalf("FAIL: %s still plaintext after migration", path)
+	}
+	t.Logf("migrated header (hex): %s", hex.EncodeToString(firstBytes(t, path, 16)))
+
+	for tbl, n := range want {
+		if got := rowCount(t, db, tbl); got != n {
+			t.Errorf("row-count mismatch %s: want %d got %d", tbl, n, got)
+		}
+	}
+
+	// sidecar unwraps under the id-derived KEK (path plays no role).
+	sidecar, err := os.ReadFile(path + dekSuffix)
+	if err != nil {
+		t.Fatalf("read sidecar: %v", err)
+	}
+	if dek, err := unwrapSidecar(testMaster(t), sidecar); err != nil || len(dek) != 32 {
+		t.Fatalf("unwrap sidecar: dek=%d err=%v", len(dek), err)
+	}
+
+	// RED HIGH: the plaintext backup must be GONE (shredded), not lingering.
+	if fileExists(path + plainBakSuffix) {
+		t.Errorf("SECURITY: plaintext backup %s survived migration (must be shredded)", path+plainBakSuffix)
+	}
+
+	var name string
+	if err := db.QueryRow(`SELECT name FROM crm_companies WHERE id='co-5'`).Scan(&name); err != nil || name != "Co 5" {
+		t.Errorf("content check: got %q err %v", name, err)
+	}
+}
+
+// TestOpenIdempotent: a second Open of an already-migrated db is a no-op.
+func TestOpenIdempotent(t *testing.T) {
+	requireCipher(t)
+	path := filepath.Join(t.TempDir(), "treasury.db")
+	want := makePlaintextDB(t, path, 5, 5)
+
+	resetMaster(testMaster(t))
+	db1, err := Open(path)
+	if err != nil {
+		t.Fatalf("first open: %v", err)
+	}
+	_ = db1.Close()
+	hdr1 := firstBytes(t, path, 16)
+
+	db2, err := Open(path)
+	if err != nil {
+		t.Fatalf("second open: %v", err)
+	}
+	defer func() { _ = db2.Close() }()
+	if isPlaintextHeader(path) {
+		t.Fatalf("db became plaintext on reopen")
+	}
+	for tbl, n := range want {
+		if got := rowCount(t, db2, tbl); got != n {
+			t.Errorf("reopen row-count %s: want %d got %d", tbl, n, got)
+		}
+	}
+	if string(hdr1) != string(firstBytes(t, path, 16)) {
+		t.Errorf("header changed on reopen (pages rewritten?)")
+	}
+}
+
+// TestFreshCreateEncrypted: a brand-new db is born encrypted.
+func TestFreshCreateEncrypted(t *testing.T) {
+	requireCipher(t)
+	path := filepath.Join(t.TempDir(), "wallets.db")
+	resetMaster(testMaster(t))
+	db, err := Open(path)
+	if err != nil {
+		t.Fatalf("open fresh: %v", err)
+	}
+	if _, err := db.Exec(`CREATE TABLE w(addr TEXT, org TEXT)`); err != nil {
+		t.Fatalf("ddl: %v", err)
+	}
+	_ = db.Close()
+	if isPlaintextHeader(path) {
+		t.Fatalf("fresh db is plaintext")
+	}
+	if !fileExists(path + dekSuffix) {
+		t.Fatalf("fresh db has no sidecar")
+	}
+}
+
+// TestWrongMasterFailsClosed: a sidecar minted under one master cannot open under
+// another — a lifted file + wrong key yields an error, never plaintext.
+func TestWrongMasterFailsClosed(t *testing.T) {
+	requireCipher(t)
+	path := filepath.Join(t.TempDir(), "audit.db")
+	makePlaintextDB(t, path, 3, 3)
+
+	resetMaster(testMaster(t))
+	db, err := Open(path)
+	if err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	_ = db.Close()
+
+	other := make([]byte, 32)
+	for i := range other {
+		other[i] = 0xAB
+	}
+	resetMaster(other)
+	if _, err := Open(path); err == nil {
+		t.Fatalf("SECURITY: opened encrypted db under the WRONG master key")
+	}
+}
+
+// TestDataDirMoveNoBrick (RED MED #2, PoC): the KEK binds to the sidecar fileID,
+// NOT CLOUD_DATA_DIR, so changing/unsetting the data dir — or moving the file to
+// a different path — must NOT brick the store.
+func TestDataDirMoveNoBrick(t *testing.T) {
+	requireCipher(t)
+	dir1 := t.TempDir()
+	pathA := filepath.Join(dir1, "crm.db")
+	want := makePlaintextDB(t, pathA, 8, 8)
+
+	t.Setenv("CLOUD_DATA_DIR", dir1)
+	resetMaster(testMaster(t))
+	db, err := Open(pathA)
+	if err != nil {
+		t.Fatalf("migrate under dir1: %v", err)
+	}
+	_ = db.Close()
+
+	// Simulate a data-dir change AND a physical move to a different filename.
+	dir2 := t.TempDir()
+	pathB := filepath.Join(dir2, "moved.db")
+	copyFile(t, pathA, pathB)
+	copyFile(t, pathA+dekSuffix, pathB+dekSuffix)
+	t.Setenv("CLOUD_DATA_DIR", "/some/other/root") // the old brick trigger
+
+	db2, err := Open(pathB) // KEK from fileID → must still open
+	if err != nil {
+		t.Fatalf("AVAILABILITY: data-dir change bricked the store: %v", err)
+	}
+	defer func() { _ = db2.Close() }()
+	for tbl, n := range want {
+		if got := rowCount(t, db2, tbl); got != n {
+			t.Errorf("moved db row-count %s: want %d got %d", tbl, n, got)
+		}
+	}
+}
+
+// TestMissingKeyFatalOnCapableBuild (RED MED #3): an encryption-capable build
+// with NO master key must FAIL CLOSED, never silently open plaintext. On a
+// pure-Go build the same absence is dev-mode plaintext.
+func TestMissingKeyFatalOnCapableBuild(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "settings.db")
+	resetMaster(nil)
+	os.Unsetenv(masterKeyEnv)
+
+	_, err := Open(path)
+	if sqlitedrv.EncryptionAvailable() {
+		if err == nil {
+			t.Fatalf("SECURITY: capable build opened the data plane with NO master key (silent plaintext)")
+		}
+		if fileExists(path) {
+			t.Fatalf("SECURITY: a db file was created despite the fatal missing-key error")
+		}
+	} else {
+		if err != nil {
+			t.Fatalf("pure-Go dev build should allow plaintext when no key: %v", err)
+		}
+	}
+}
+
+// TestContentHashCatchesMutation (RED MED #4): the content hash catches a value
+// change that row-count + schema + integrity_check all miss, AND does NOT
+// false-positive on the benign implicit-rowid renumbering sqlcipher_export does.
+func TestContentHashCatchesMutation(t *testing.T) {
+	requireCipher(t)
+	a := filepath.Join(t.TempDir(), "a.db")
+	b := filepath.Join(t.TempDir(), "b.db")
+	makePlaintextDB(t, a, 10, 10)
+	makePlaintextDB(t, b, 10, 10)
+	if inventoryOf(t, a).tables["crm_contacts"].content != inventoryOf(t, b).tables["crm_contacts"].content {
+		t.Fatalf("identical data produced different content hashes")
+	}
+
+	// Mutate ONE value in b (same row count, same schema, integrity stays ok).
+	base := inventoryOf(t, a).tables["crm_contacts"]
+	mutate(t, b, `UPDATE crm_contacts SET email='HIJACKED' WHERE id='ct-3'`)
+	after := inventoryOf(t, b).tables["crm_contacts"]
+	if after.count != base.count {
+		t.Fatalf("mutation changed the row count; test would not isolate content")
+	}
+	if base.content == after.content {
+		t.Fatalf("SECURITY: content hash did NOT catch a value mutation (count-blind gate)")
+	}
+
+	// Benign rowid renumber (delete+reinsert identical row, VACUUM) must NOT change it.
+	c := filepath.Join(t.TempDir(), "c.db")
+	makePlaintextDB(t, c, 10, 10)
+	before := inventoryOf(t, c).tables["crm_contacts"].content
+	mutate(t, c, `DELETE FROM crm_contacts WHERE id='ct-0'; INSERT INTO crm_contacts(id,org,email) VALUES('ct-0','maxpower','u0@x.io'); VACUUM`)
+	if before != inventoryOf(t, c).tables["crm_contacts"].content {
+		t.Errorf("content hash false-positived on a rowid renumber (re-inserted identical row)")
+	}
+}
+
+// TestCorruptSidecarFailsClosed (RED re-test #5, safety net): any undecryptable
+// state — a corrupted or missing .dek sidecar, the family a libsqlcipher format
+// mismatch would land in — FAILS CLOSED (errors), never silently opening
+// plaintext or a garbage db. (Cross-version format stability itself is enforced
+// by freezing the libsqlcipher version in the build; an at-open cipher_compat
+// pin is infeasible with mattn's URI-key requirement — see openKeyed.)
+func TestCorruptSidecarFailsClosed(t *testing.T) {
+	requireCipher(t)
+	path := filepath.Join(t.TempDir(), "audit.db")
+	makePlaintextDB(t, path, 4, 4)
+
+	resetMaster(testMaster(t))
+	db, err := Open(path)
+	if err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	_ = db.Close()
+
+	// Flip a byte in the wrapped-DEK region of the sidecar → GCM tag fails.
+	sc, err := os.ReadFile(path + dekSuffix)
+	if err != nil {
+		t.Fatalf("read sidecar: %v", err)
+	}
+	sc[len(sc)-1] ^= 0xFF
+	if err := os.WriteFile(path+dekSuffix, sc, 0o600); err != nil {
+		t.Fatalf("write sidecar: %v", err)
+	}
+	resetMaster(testMaster(t))
+	if _, err := Open(path); err == nil {
+		t.Fatalf("SECURITY: opened an encrypted db with a corrupted DEK sidecar")
+	}
+
+	// A missing sidecar over an encrypted db must also refuse (never open blind).
+	if err := os.Remove(path + dekSuffix); err != nil {
+		t.Fatalf("rm sidecar: %v", err)
+	}
+	resetMaster(testMaster(t))
+	if _, err := Open(path); err == nil {
+		t.Fatalf("SECURITY: opened an encrypted db with NO DEK sidecar")
+	}
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+func inventoryOf(t *testing.T, path string) inventory {
+	t.Helper()
+	db, err := sql.Open("sqlite", sqlitedrv.DSN(path, nil))
+	if err != nil {
+		t.Fatalf("open for inventory: %v", err)
+	}
+	defer func() { _ = db.Close() }()
+	db.SetMaxOpenConns(1)
+	conn, err := db.Conn(context.Background())
+	if err != nil {
+		t.Fatalf("conn: %v", err)
+	}
+	defer func() { _ = conn.Close() }()
+	inv, err := readInventory(context.Background(), conn)
+	if err != nil {
+		t.Fatalf("readInventory: %v", err)
+	}
+	return inv
+}
+
+func mutate(t *testing.T, path, sqlText string) {
+	t.Helper()
+	db, err := sql.Open("sqlite", sqlitedrv.DSN(path, nil))
+	if err != nil {
+		t.Fatalf("open mutate: %v", err)
+	}
+	defer func() { _ = db.Close() }()
+	if _, err := db.Exec(sqlText); err != nil {
+		t.Fatalf("mutate %q: %v", sqlText, err)
+	}
+}
+
+func copyFile(t *testing.T, src, dst string) {
+	t.Helper()
+	b, err := os.ReadFile(src)
+	if err != nil {
+		t.Fatalf("read %s: %v", src, err)
+	}
+	if err := os.WriteFile(dst, b, 0o600); err != nil {
+		t.Fatalf("write %s: %v", dst, err)
+	}
+}

cek/frozen_test.go

@@ -0,0 +1,100 @@
+package cek
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// The frozen fixture pins the SQLCipher on-disk FORMAT the data plane is written
+// with. A committed encrypted store (created under the build's frozen
+// libsqlcipher) is opened by TestFrozenFixtureOpens; if a future libsqlcipher
+// upgrade changes the default cipher format, opening a store written under the
+// old format FAILS — turning a silent prod brick into a red CI. (Build-time
+// SQLITE_REQUIRE_CODEC only proves a FRESH db encrypts; it cannot detect a format
+// change against pre-existing stores — the fixture is what does.)
+
+const frozenCanary = "cek-format-canary-v1"
+
+// frozenMaster is a FIXED, obviously-fake test key (0x00..0x1f) used only to wrap
+// the committed fixture's DEK. Not a secret; never used in production.
+func frozenMaster() []byte {
+	k := make([]byte, 32)
+	for i := range k {
+		k[i] = byte(i)
+	}
+	return k
+}
+
+const frozenDir = "testdata/frozen"
+
+// TestGenerateFrozenFixture (re)writes the committed fixture. Gated on
+// CEK_GEN_FIXTURE=1 and run by hand ONLY when the format is intentionally rev'd;
+// the committed bytes are otherwise frozen.
+func TestGenerateFrozenFixture(t *testing.T) {
+	if os.Getenv("CEK_GEN_FIXTURE") != "1" {
+		t.Skip("set CEK_GEN_FIXTURE=1 to regenerate the frozen fixture")
+	}
+	requireCipher(t)
+	if err := os.MkdirAll(frozenDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	dbPath := filepath.Join(frozenDir, "store.db")
+	for _, s := range []string{"", dekSuffix, "-wal", "-shm"} {
+		_ = os.Remove(dbPath + s)
+	}
+	dek, sidecar, err := mintSidecar(frozenMaster())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(dbPath+dekSuffix, sidecar, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	h, err := openKeyed(dbPath, dek)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := h.Exec(`CREATE TABLE frozen(id INTEGER PRIMARY KEY, note TEXT)`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := h.Exec(`INSERT INTO frozen VALUES(1,?)`, frozenCanary); err != nil {
+		t.Fatal(err)
+	}
+	_, _ = h.Exec(`PRAGMA wal_checkpoint(TRUNCATE)`) // fold into the main .db
+	_ = h.Close()
+	_ = os.Remove(dbPath + "-wal")
+	_ = os.Remove(dbPath + "-shm")
+	if isPlaintextHeader(dbPath) {
+		t.Fatal("generated fixture is plaintext")
+	}
+	t.Logf("wrote frozen fixture %s (+%s)", dbPath, dekSuffix)
+}
+
+// TestFrozenFixtureOpens opens the COMMITTED encrypted fixture (copied to temp so
+// the committed bytes are never mutated) and reads its canary row. A libsqlcipher
+// format change makes this fail — a red CI instead of a silent prod brick.
+func TestFrozenFixtureOpens(t *testing.T) {
+	requireCipher(t)
+	src := filepath.Join(frozenDir, "store.db")
+	if !fileExists(src) {
+		t.Fatal("frozen fixture missing — regenerate with CEK_GEN_FIXTURE=1 and commit testdata/frozen/")
+	}
+	dir := t.TempDir()
+	dst := filepath.Join(dir, "store.db")
+	copyFile(t, src, dst)
+	copyFile(t, src+dekSuffix, dst+dekSuffix)
+
+	resetMaster(frozenMaster())
+	db, err := Open(dst)
+	if err != nil {
+		t.Fatalf("FORMAT DRIFT: frozen fixture failed to open (libsqlcipher format changed?): %v", err)
+	}
+	defer func() { _ = db.Close() }()
+	var note string
+	if err := db.QueryRow(`SELECT note FROM frozen WHERE id=1`).Scan(&note); err != nil {
+		t.Fatalf("read canary: %v", err)
+	}
+	if note != frozenCanary {
+		t.Fatalf("canary mismatch: got %q want %q", note, frozenCanary)
+	}
+}

cli/agent.go

@@ -0,0 +1,74 @@
+package cli
+
+// agent.go — `hanzo agent`: invoke a managed Hanzo agent with a task.
+//
+// An agent is a managed capability (its own /v1/agents subsystem, self-metered),
+// NOT your artifact — so it is a peer verb of `hanzo run`, not a run kind. This is
+// the HEADLESS flavor: a task/tool/code agent, no computer. The computer-using
+// flavor (a booted desktop/terminal) is `hanzo bot` (see bot.go).
+//
+//	hanzo agent run <ref> "<task>"  → POST /v1/agents/:ref/run
+//
+// Thin client: one authenticated call over the IAM token + env.CloudURL, reusing
+// cloudCall (run.go). See docs/architecture/compute-ladder.md.
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+// AgentRunReq is the POST /v1/agents/:ref/run body — a task for a managed agent.
+type AgentRunReq struct {
+	Task    string `json:"task"`
+	GPU     bool   `json:"gpu,omitempty"`
+	Timeout string `json:"timeout,omitempty"`
+	Repo    string `json:"repo,omitempty"`
+}
+
+// AgentRunResult is the agent-run acceptance.
+type AgentRunResult struct {
+	RunID  string `json:"runId"`
+	Status string `json:"status"`
+	URL    string `json:"url"`
+}
+
+func newAgentCmd(envOf func() *Env, _ *globalFlags) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "agent",
+		Short: "Invoke a managed Hanzo agent to run a task (headless)",
+		Long: "Invoke a managed agent by ref (e.g. a coding or tool agent) to run a task on\n" +
+			"Hanzo compute — metered per run. For a computer-using agent (booted desktop\n" +
+			"or terminal), use `hanzo bot`.",
+	}
+	cmd.AddCommand(newAgentRunCmd(envOf))
+	return cmd
+}
+
+func newAgentRunCmd(envOf func() *Env) *cobra.Command {
+	var req AgentRunReq
+	c := &cobra.Command{
+		Use:   "run <ref> <task>",
+		Short: "Run a task with the named agent (POST /v1/agents/:ref/run)",
+		Args:  cobra.MinimumNArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			env := envOf()
+			ref := args[0]
+			req.Task = strings.Join(args[1:], " ")
+			out := &AgentRunResult{}
+			if err := cloudCall(cmd.Context(), env, http.MethodPost, "/v1/agents/"+ref+"/run", &req, out); err != nil {
+				return err
+			}
+			return env.emit(out, func(w io.Writer) {
+				fmt.Fprintf(w, "%s\t%s\t%s\n", out.RunID, out.Status, out.URL)
+			})
+		},
+	}
+	c.Flags().BoolVar(&req.GPU, "gpu", false, "run the agent on a GPU node")
+	c.Flags().StringVar(&req.Timeout, "timeout", "", "max wall-clock (e.g. 30m)")
+	c.Flags().StringVar(&req.Repo, "repo", "", "a repo/checkout the agent operates on")
+	return c
+}

cli/auth.go

@@ -160,23 +160,21 @@ type loginFlags struct {
 }
 
 func runLogin(env *Env, lf *loginFlags, cmd *cobra.Command) error {
-	creds, err := LoadCredentials()
-	if err != nil {
-		return err
-	}
+	var creds *Credentials
 
 	switch {
 	case lf.token != "":
 		// Paste an externally-minted token. Decode claims for identity.
-		tr := &tokenResp{AccessToken: lf.token, TokenType: "Bearer"}
-		creds = credsFromToken(tr)
-	default:
+		creds = credsFromToken(&tokenResp{AccessToken: lf.token, TokenType: "Bearer"})
+	case lf.username != "" || lf.passwordStdin:
+		// Password grant — kept for automation (--username/--password-stdin).
 		username := lf.username
 		if username == "" {
-			username, err = prompt(cmd, "Email: ")
+			u, err := prompt(cmd, "Email: ")
 			if err != nil {
 				return err
 			}
+			username = u
 		}
 		password, err := readPassword(cmd, lf.passwordStdin)
 		if err != nil {
@@ -188,10 +186,18 @@ func runLogin(env *Env, lf *loginFlags, cmd *cobra.Command) error {
 			return err
 		}
 		creds = credsFromToken(tr)
+	default:
+		// The ONE interactive way: RFC 8628 device flow — link + QR + code,
+		// approve from any signed-in browser or phone. Headless-safe.
+		c, err := runDeviceLogin(cmd, env, lf.scope)
+		if err != nil {
+			return err
+		}
+		creds = c
 	}
 
 	// Optional machine-to-machine tokens for the platform control plane,
-	// stored alongside the identity so apps/deploy work post-login.
+	// stored with this identity so apps/deploy work post-login.
 	if lf.platformToken != "" {
 		creds.PlatformToken = lf.platformToken
 	}
@@ -199,14 +205,23 @@ func runLogin(env *Env, lf *loginFlags, cmd *cobra.Command) error {
 		creds.BuildToken = lf.buildToken
 	}
 
-	if err := creds.Save(); err != nil {
+	// Persist under this identity's stable key and make it active. A second
+	// login as a different owner (e.g. admin vs hanzo for the same email, via a
+	// different --client-id) is stored beside the first, never over it;
+	// credentials.json mirrors whichever is active for legacy readers.
+	store, err := LoadIdentities()
+	if err != nil {
+		return err
+	}
+	key := store.Put(creds)
+	if err := store.Save(); err != nil {
 		return err
 	}
 	who := firstNonEmpty(creds.Subject, "(unknown)")
 	if creds.Owner != "" {
 		who += " @ " + creds.Owner
 	}
-	fmt.Fprintf(cmd.OutOrStdout(), "Logged in as %s (token expires %s)\n", who, shortTime(creds.Expiry))
+	fmt.Fprintf(cmd.OutOrStdout(), "Logged in as %s [%s] (token expires %s)\n", who, key, shortTime(creds.Expiry))
 	return nil
 }
 
@@ -215,10 +230,13 @@ func newLoginCmd(envOf func() *Env, _ *globalFlags) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "login",
 		Short: "Authenticate against Hanzo IAM and store a token",
-		Long: "Authenticate against Hanzo IAM (hanzo.id) via the password grant and store\n" +
-			"the token in ~/.hanzo/credentials.json (mode 0600). Use --token to store an\n" +
-			"externally-minted token instead, and --platform-token to store the platform\n" +
-			"control-plane service token needed by apps/deploy/clusters.",
+		Long: "Authenticate against Hanzo IAM (hanzo.id) and store the token in\n" +
+			"~/.hanzo/credentials.json (mode 0600). Default is the device flow: scan the\n" +
+			"QR (or open the link) from any signed-in device and approve — no password\n" +
+			"touches this terminal, works over ssh/headless. --username/--password-stdin\n" +
+			"keep the password grant for automation; --token stores an externally-minted\n" +
+			"token; --platform-token stores the platform control-plane service token\n" +
+			"needed by apps/deploy/clusters.",
 		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error { return runLogin(envOf(), lf, cmd) },
 	}
@@ -238,28 +256,92 @@ func bindLoginFlags(cmd *cobra.Command, lf *loginFlags) {
 
 func newLogoutCmd() *cobra.Command {
 	return &cobra.Command{
-		Use:               "logout",
-		Short:             "Remove stored credentials",
-		Args:              cobra.NoArgs,
+		Use:               "logout [<owner>]",
+		Short:             "Remove a stored identity (the active one, or the named owner)",
+		Args:              cobra.MaximumNArgs(1),
 		PersistentPreRunE: func(*cobra.Command, []string) error { return nil },
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			if err := DeleteCredentials(); err != nil {
+		RunE: func(cmd *cobra.Command, args []string) error {
+			store, err := LoadIdentities()
+			if err != nil {
 				return err
 			}
-			fmt.Fprintln(cmd.OutOrStdout(), "Logged out.")
+			if len(store.Identities) == 0 {
+				fmt.Fprintln(cmd.OutOrStdout(), "Not logged in.")
+				return nil
+			}
+			target := store.Active
+			if len(args) == 1 {
+				if target, err = store.resolve(args[0]); err != nil {
+					return err
+				}
+			}
+			store.Remove(target)
+			if err := store.Save(); err != nil {
+				return err
+			}
+			msg := "Logged out of " + target + "."
+			if store.Active != "" {
+				msg += " Active is now " + store.Active + "."
+			}
+			fmt.Fprintln(cmd.OutOrStdout(), msg)
 			return nil
 		},
 	}
 }
 
+// identityRow is the JSON/table projection of one stored identity.
+type identityRow struct {
+	Key     string `json:"key"`
+	Owner   string `json:"owner"`
+	Subject string `json:"subject"`
+	Expiry  int64  `json:"expiry,omitempty"`
+	Active  bool   `json:"active"`
+}
+
+// listIdentities renders every stored identity (active marked with *) — the
+// shared body of `hanzo auth list` and `hanzo whoami --all`.
+func listIdentities(env *Env, _ *cobra.Command) error {
+	store, err := LoadIdentities()
+	if err != nil {
+		return err
+	}
+	rows := make([]identityRow, 0, len(store.Identities))
+	for _, k := range store.keys() {
+		c := store.Identities[k]
+		rows = append(rows, identityRow{
+			Key: k, Owner: c.Owner, Subject: c.Subject, Expiry: c.Expiry,
+			Active: k == store.Active,
+		})
+	}
+	return env.emit(rows, func(w io.Writer) {
+		if len(rows) == 0 {
+			fmt.Fprintln(w, "No stored identities. Run `hanzo login`.")
+			return
+		}
+		tw := newTab(w)
+		fmt.Fprintln(tw, "ACTIVE\tKEY\tOWNER\tSUBJECT\tEXPIRES")
+		for _, r := range rows {
+			active := ""
+			if r.Active {
+				active = "*"
+			}
+			fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\n", active, r.Key, r.Owner, r.Subject, shortTime(r.Expiry))
+		}
+		tw.Flush()
+	})
+}
+
 func newWhoamiCmd(envOf func() *Env) *cobra.Command {
-	var verify bool
+	var verify, all bool
 	cmd := &cobra.Command{
 		Use:   "whoami",
-		Short: "Show the current identity from the stored token",
+		Short: "Show the active identity from the stored token (--all lists every stored identity)",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			env := envOf()
+			if all {
+				return listIdentities(env, cmd)
+			}
 			tok := env.accessToken()
 			if tok == "" {
 				return fmt.Errorf("not logged in: run `hanzo login`")
@@ -289,6 +371,7 @@ func newWhoamiCmd(envOf func() *Env) *cobra.Command {
 		},
 	}
 	cmd.Flags().BoolVar(&verify, "verify", false, "verify the token against the IAM userinfo endpoint")
+	cmd.Flags().BoolVar(&all, "all", false, "list every stored identity (active marked with *)")
 	return cmd
 }
 
@@ -318,11 +401,11 @@ func verifyUserInfo(ctx context.Context, env *Env, token string) error {
 func newAuthCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "auth",
-		Short: "Manage authentication",
+		Short: "Manage authentication and stored identities",
 	}
 	tokenCmd := &cobra.Command{
 		Use:   "token",
-		Short: "Print the stored access token",
+		Short: "Print the active access token",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			tok := envOf().accessToken()
@@ -333,7 +416,41 @@ func newAuthCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
 			return nil
 		},
 	}
-	cmd.AddCommand(newLoginCmd(envOf, gf), newLogoutCmd(), newWhoamiCmd(envOf), tokenCmd)
+	listCmd := &cobra.Command{
+		Use:     "list",
+		Aliases: []string{"ls", "identities"},
+		Short:   "List stored identities (active marked with *)",
+		Args:    cobra.NoArgs,
+		RunE:    func(cmd *cobra.Command, _ []string) error { return listIdentities(envOf(), cmd) },
+	}
+	switchCmd := &cobra.Command{
+		Use:     "switch <owner>",
+		Aliases: []string{"use"},
+		Short:   "Make a stored identity active (accepts an owner, or a full owner/name key)",
+		Args:    cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			store, err := LoadIdentities()
+			if err != nil {
+				return err
+			}
+			key, err := store.resolve(args[0])
+			if err != nil {
+				return err
+			}
+			store.Active = key
+			if err := store.Save(); err != nil {
+				return err
+			}
+			c := store.Identities[key]
+			who := firstNonEmpty(c.Subject, "(unknown)")
+			if c.Owner != "" {
+				who += " @ " + c.Owner
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "Switched to %s [%s] (token expires %s)\n", who, key, shortTime(c.Expiry))
+			return nil
+		},
+	}
+	cmd.AddCommand(newLoginCmd(envOf, gf), newLogoutCmd(), newWhoamiCmd(envOf), tokenCmd, listCmd, switchCmd)
 	return cmd
 }
 

cli/auth_test.go

@@ -61,9 +61,9 @@ func TestPasswordGrant(t *testing.T) {
 			t.Errorf("bad form: %v", r.Form)
 		}
 		_ = json.NewEncoder(w).Encode(map[string]any{
-			"access_token": makeJWT(map[string]any{"email": "z@hanzo.ai"}),
-			"token_type":   "Bearer",
-			"expires_in":   3600,
+			"access_token":  makeJWT(map[string]any{"email": "z@hanzo.ai"}),
+			"token_type":    "Bearer",
+			"expires_in":    3600,
 			"refresh_token": "r",
 		})
 	}))
@@ -208,3 +208,178 @@ func TestAuthTokenCommand(t *testing.T) {
 		t.Fatalf("auth token output: %q", out)
 	}
 }
+
+// TestMultiIdentityLoginSwitch is the full multi-identity story: two logins for
+// the same email under different owners (admin vs hanzo — the privilege-
+// separation case) coexist, `auth list` shows both, `switch` flips the active
+// pointer and rewrites credentials.json, and legacy single-file readers always
+// see the active identity.
+func TestMultiIdentityLoginSwitch(t *testing.T) {
+	sandbox(t)
+	adminTok := makeJWT(map[string]any{"email": "z@hanzo.ai", "owner": "admin", "sub": "u-admin", "exp": float64(2000000000)})
+	hanzoTok := makeJWT(map[string]any{"email": "z@hanzo.ai", "owner": "hanzo", "sub": "u-hanzo", "exp": float64(2000000001)})
+
+	// First login → admin/z is stored and active.
+	out, err := runRoot(t, "", "login", "--token", adminTok)
+	if err != nil {
+		t.Fatalf("login admin: %v", err)
+	}
+	if !strings.Contains(out, "admin/z") {
+		t.Fatalf("login should report the key: %q", out)
+	}
+	if c, _ := LoadCredentials(); c.Owner != "admin" || c.Subject != "z@hanzo.ai" {
+		t.Fatalf("active not admin after first login: %+v", c)
+	}
+
+	// Second login (different owner) → added beside admin/z, becomes active,
+	// does NOT clobber the first.
+	if _, err := runRoot(t, "", "login", "--token", hanzoTok); err != nil {
+		t.Fatalf("login hanzo: %v", err)
+	}
+	store, err := LoadIdentities()
+	if err != nil {
+		t.Fatalf("load identities: %v", err)
+	}
+	if len(store.Identities) != 2 {
+		t.Fatalf("want 2 identities, got %d: %v", len(store.Identities), store.keys())
+	}
+	if store.Identities["admin/z"] == nil || store.Identities["hanzo/z"] == nil {
+		t.Fatalf("both identities must persist, got %v", store.keys())
+	}
+	if store.Active != "hanzo/z" {
+		t.Fatalf("active = %q, want hanzo/z (last login)", store.Active)
+	}
+	// Legacy reader sees the active (hanzo) identity.
+	if c, _ := LoadCredentials(); c.Owner != "hanzo" {
+		t.Fatalf("credentials.json not mirroring active: %+v", c)
+	}
+
+	// auth list shows both, with the active row marked.
+	out, err = runRoot(t, "", "auth", "list")
+	if err != nil {
+		t.Fatalf("auth list: %v", err)
+	}
+	for _, want := range []string{"admin/z", "hanzo/z", "z@hanzo.ai", "*"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("auth list missing %q in:\n%s", want, out)
+		}
+	}
+
+	// switch admin → active flips + credentials.json is rewritten to admin.
+	if _, err := runRoot(t, "", "auth", "switch", "admin"); err != nil {
+		t.Fatalf("auth switch admin: %v", err)
+	}
+	if st, _ := LoadIdentities(); st.Active != "admin/z" {
+		t.Fatalf("active after switch = %q, want admin/z", st.Active)
+	}
+	if c, _ := LoadCredentials(); c.Owner != "admin" || c.Subject != "z@hanzo.ai" {
+		t.Fatalf("switch did not rewrite credentials.json: %+v", c)
+	}
+
+	// whoami (top-level, reads the active token) reflects admin.
+	out, err = runRoot(t, "", "whoami")
+	if err != nil {
+		t.Fatalf("whoami: %v", err)
+	}
+	if !strings.Contains(out, "admin") || !strings.Contains(out, "z@hanzo.ai") {
+		t.Fatalf("whoami not reflecting the switched-to identity: %q", out)
+	}
+
+	// switch by the full owner/name key works too.
+	if _, err := runRoot(t, "", "auth", "switch", "hanzo/z"); err != nil {
+		t.Fatalf("auth switch hanzo/z: %v", err)
+	}
+	if c, _ := LoadCredentials(); c.Owner != "hanzo" {
+		t.Fatalf("switch by full key failed: %+v", c)
+	}
+}
+
+// TestAuthListJSON checks the machine-readable projection.
+func TestAuthListJSON(t *testing.T) {
+	sandbox(t)
+	tok := makeJWT(map[string]any{"email": "z@hanzo.ai", "owner": "admin", "sub": "a"})
+	if _, err := runRoot(t, "", "login", "--token", tok); err != nil {
+		t.Fatalf("login: %v", err)
+	}
+	out, err := runRoot(t, "", "auth", "list", "-o", "json")
+	if err != nil {
+		t.Fatalf("auth list json: %v", err)
+	}
+	var rows []identityRow
+	if err := json.Unmarshal([]byte(out), &rows); err != nil {
+		t.Fatalf("json unmarshal: %v\n%s", err, out)
+	}
+	if len(rows) != 1 || rows[0].Key != "admin/z" || rows[0].Owner != "admin" || !rows[0].Active {
+		t.Fatalf("json rows wrong: %+v", rows)
+	}
+}
+
+// TestLogoutOneOfMany removes a single identity and, only when the last one is
+// gone, clears the store entirely.
+func TestLogoutOneOfMany(t *testing.T) {
+	sandbox(t)
+	admin := makeJWT(map[string]any{"email": "z@hanzo.ai", "owner": "admin", "sub": "a"})
+	hanzo := makeJWT(map[string]any{"email": "z@hanzo.ai", "owner": "hanzo", "sub": "h"})
+	if _, err := runRoot(t, "", "login", "--token", admin); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := runRoot(t, "", "login", "--token", hanzo); err != nil { // active = hanzo/z
+		t.Fatal(err)
+	}
+
+	// logout of the named owner (admin) leaves hanzo/z active.
+	if _, err := runRoot(t, "", "logout", "admin"); err != nil {
+		t.Fatalf("logout admin: %v", err)
+	}
+	store, _ := LoadIdentities()
+	if store.Identities["admin/z"] != nil {
+		t.Fatalf("admin/z not removed: %v", store.keys())
+	}
+	if store.Active != "hanzo/z" {
+		t.Fatalf("active = %q, want hanzo/z", store.Active)
+	}
+	if c, _ := LoadCredentials(); c.Owner != "hanzo" {
+		t.Fatalf("credentials.json not mirroring survivor: %+v", c)
+	}
+
+	// logout of the active (no arg) removes the last identity → both files gone.
+	if _, err := runRoot(t, "", "logout"); err != nil {
+		t.Fatalf("logout active: %v", err)
+	}
+	if c, _ := LoadCredentials(); c.AccessToken != "" {
+		t.Fatalf("credentials.json not cleared: %+v", c)
+	}
+	if st, _ := LoadIdentities(); len(st.Identities) != 0 {
+		t.Fatalf("identity store not cleared: %v", st.keys())
+	}
+}
+
+// TestMigrateLegacyCredentials proves a pre-multi-identity credentials.json is
+// adopted into the store and preserved when a new identity is added.
+func TestMigrateLegacyCredentials(t *testing.T) {
+	sandbox(t)
+	// Simulate an old single-file login: only credentials.json exists.
+	legacy := credsFromToken(&tokenResp{AccessToken: makeJWT(map[string]any{
+		"email": "z@hanzo.ai", "owner": "hanzo", "sub": "h",
+	})})
+	if err := legacy.Save(); err != nil {
+		t.Fatal(err)
+	}
+	store, err := LoadIdentities()
+	if err != nil {
+		t.Fatalf("load identities: %v", err)
+	}
+	if store.Identities["hanzo/z"] == nil || store.Active != "hanzo/z" {
+		t.Fatalf("legacy credentials not migrated: active=%q keys=%v", store.Active, store.keys())
+	}
+	// A fresh login as a different owner preserves the migrated identity.
+	if _, err := runRoot(t, "", "login", "--token", makeJWT(map[string]any{
+		"email": "z@hanzo.ai", "owner": "admin", "sub": "a",
+	})); err != nil {
+		t.Fatal(err)
+	}
+	st2, _ := LoadIdentities()
+	if len(st2.Identities) != 2 || st2.Identities["hanzo/z"] == nil {
+		t.Fatalf("migrated identity lost after new login: %v", st2.keys())
+	}
+}

cli/bot.go

@@ -0,0 +1,82 @@
+package cli
+
+// bot.go — `hanzo bot`: launch a computer-using agent (a "bot").
+//
+// A bot is the COMPUTER-USING flavor of an agent: it quick-boots a terminal or
+// desktop sandbox on the operative stack (Hanzo's computer-use runtime — noVNC
+// desktop, shell, browser, tools), provisioned by visor, and drives that machine
+// to do the task. The headless flavor (no computer) is `hanzo agent` (agent.go).
+//
+//	hanzo bot run "<task>"            → boot a desktop bot, run the task
+//	hanzo bot run --terminal "<task>" → boot a terminal-only bot
+//
+// Thin client over the IAM token + env.CloudURL (reuses cloudCall, run.go). The
+// operative runtime + visor-provisioned machine do the work; the CLI only starts
+// the run and reports the live session URL. See docs/architecture/compute-ladder.md.
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+// BotRunReq is the boot-a-computer-using-agent body. Surface selects the sandbox
+// the operative runtime drives: "desktop" (noVNC GUI) or "terminal" (shell only).
+type BotRunReq struct {
+	Task    string `json:"task"`
+	Surface string `json:"surface"` // desktop | terminal
+	GPU     bool   `json:"gpu,omitempty"`
+	Timeout string `json:"timeout,omitempty"`
+}
+
+// BotRunResult carries the live session: a URL to watch/attach (noVNC / terminal)
+// plus the run id.
+type BotRunResult struct {
+	RunID      string `json:"runId"`
+	Status     string `json:"status"`
+	SessionURL string `json:"sessionUrl"`
+}
+
+func newBotCmd(envOf func() *Env, _ *globalFlags) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "bot",
+		Short: "Launch a computer-using agent (booted desktop or terminal)",
+		Long: "Quick-boot a terminal or desktop sandbox on the operative computer-use\n" +
+			"runtime (visor-provisioned) and have an agent drive it to do a task —\n" +
+			"metered like any run. For a headless task agent, use `hanzo agent`.",
+	}
+	cmd.AddCommand(newBotRunCmd(envOf))
+	return cmd
+}
+
+func newBotRunCmd(envOf func() *Env) *cobra.Command {
+	var req BotRunReq
+	var terminal bool
+	c := &cobra.Command{
+		Use:   "run <task>",
+		Short: "Boot a computer-using bot and run the task",
+		Args:  cobra.MinimumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			env := envOf()
+			req.Task = strings.Join(args, " ")
+			req.Surface = "desktop"
+			if terminal {
+				req.Surface = "terminal"
+			}
+			out := &BotRunResult{}
+			if err := cloudCall(cmd.Context(), env, http.MethodPost, "/v1/bots/run", &req, out); err != nil {
+				return err
+			}
+			return env.emit(out, func(w io.Writer) {
+				fmt.Fprintf(w, "%s\t%s\t%s\n", out.RunID, out.Status, out.SessionURL)
+			})
+		},
+	}
+	c.Flags().BoolVar(&terminal, "terminal", false, "boot a terminal-only sandbox (default: desktop)")
+	c.Flags().BoolVar(&req.GPU, "gpu", false, "boot on a GPU machine")
+	c.Flags().StringVar(&req.Timeout, "timeout", "", "max wall-clock (e.g. 30m)")
+	return c
+}

cli/cli.go

@@ -8,7 +8,7 @@
 //	hanzo apps  list|get      the platform apps board (declared/running/drift)
 //	hanzo deploy              drive a platform redeploy (rolling, zero-downtime)
 //	hanzo clusters …          provision/list/select dedicated DOKS clusters
-//	hanzo build               enqueue a platform-native (arcd) build
+//	hanzo build               enqueue a platform-native build (runner fabric)
 //	hanzo k8s …               current deploy target helpers
 //	hanzo config …            ~/.hanzo/config preferences
 //
@@ -55,14 +55,21 @@ var controlCommands = map[string]string{
 	"login":    "authenticate against Hanzo IAM (hanzo.id) and store a token",
 	"logout":   "remove stored credentials",
 	"whoami":   "show the current identity from the stored token",
-	"auth":     "manage authentication (login, logout, whoami, token)",
+	"auth":     "manage authentication + stored identities (login, logout, whoami, list, switch, token)",
 	"apps":     "list/get the platform apps board (declared/running/drift)",
 	"deploy":   "drive a platform redeploy (rolling restart, zero-downtime)",
 	"clusters": "provision/list/select dedicated DOKS clusters",
-	"build":    "enqueue a platform-native (arcd) build",
+	"build":    "enqueue a platform-native build (runner fabric)",
 	"k8s":      "deploy-target helpers (current target)",
 	"config":   "view/edit ~/.hanzo/config preferences",
 	"security": "scan files for hardcoded secrets (local guardrail; no server/auth)",
+	"gpu":      "connect this machine's GPU to the Hanzo cloud fleet (connect/status/disconnect)",
+	"engine":   "run a local hanzo-engine (OpenAI + Anthropic model server)",
+	"code":     "launch a coding agent (claude, codex, dev) on a Hanzo cloud model",
+	"runner":   "run this machine as a JIT CI runner for your org (GitHub Actions)",
+	"run":      "launch a workload on Hanzo compute (container or function)",
+	"agent":    "invoke a managed Hanzo agent to run a task (headless)",
+	"bot":      "launch a computer-using agent (booted desktop or terminal)",
 }
 
 // IsControlVerb reports whether sub is a client-mode command (and therefore
@@ -96,6 +103,9 @@ type Config struct {
 	PlatformURL string `json:"platform_url,omitempty"`
 	CloudURL    string `json:"cloud_url,omitempty"`
 	ClientID    string `json:"client_id,omitempty"`
+	APIKey      string `json:"apiKey,omitempty"`   // hk-… key; what `hanzo code` hands the agents
+	CodeTool    string `json:"code_tool,omitempty"` // default agent for bare `hanzo` / `hanzo code`: dev|claude|codex
+	CodeModel   string `json:"code_model,omitempty"` // default model for `hanzo code` (else defaultCodeModel)
 }
 
 // Credentials holds secret material, ~/.hanzo/credentials.json, mode 0600.
@@ -226,6 +236,170 @@ func DeleteCredentials() error {
 	return nil
 }
 
+// ---------------------------------------------------------------------------
+// Identity store — ~/.hanzo/identities.json. Holds EVERY logged-in identity
+// keyed by its stable "<owner>/<name>" key, with an Active pointer. On every
+// write the active identity is mirrored into credentials.json (above), so every
+// legacy single-file reader keeps seeing the current identity unchanged. This
+// is the ONE credential store; credentials.json is its active-view mirror.
+// ---------------------------------------------------------------------------
+
+// IdentityStore is the on-disk shape of ~/.hanzo/identities.json.
+type IdentityStore struct {
+	Active     string                  `json:"active,omitempty"`
+	Identities map[string]*Credentials `json:"identities,omitempty"`
+}
+
+// key is the stable per-identity store key "<owner>/<name>", where name is the
+// email local-part (else the raw subject). The same identity yields the same
+// key every login, so re-login updates in place; the same email under a
+// different org (privilege separation) yields a distinct key (admin/z vs
+// hanzo/z) and is stored side by side rather than clobbering.
+func (c *Credentials) key() string {
+	name := c.Subject
+	if i := strings.IndexByte(name, '@'); i > 0 {
+		name = name[:i]
+	}
+	return firstNonEmpty(c.Owner, "-") + "/" + firstNonEmpty(name, "-")
+}
+
+func identitiesPath() (string, error) {
+	dir, err := hanzoDir()
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(dir, "identities.json"), nil
+}
+
+// LoadIdentities reads the store. A pre-existing single-file credentials.json
+// with no store yet is migrated in (read-only) as the sole, active identity, so
+// upgrades are seamless — the first write persists it into the store.
+func LoadIdentities() (*IdentityStore, error) {
+	p, err := identitiesPath()
+	if err != nil {
+		return nil, err
+	}
+	s := &IdentityStore{Identities: map[string]*Credentials{}}
+	if err := loadJSON(p, s); err != nil {
+		return nil, err
+	}
+	if s.Identities == nil {
+		s.Identities = map[string]*Credentials{}
+	}
+	if len(s.Identities) == 0 {
+		if c, err := LoadCredentials(); err == nil && c.AccessToken != "" {
+			k := c.key()
+			s.Identities[k] = c
+			s.Active = k
+		}
+	}
+	return s, nil
+}
+
+// keys returns the identity keys, sorted, for deterministic output.
+func (s *IdentityStore) keys() []string {
+	ks := make([]string, 0, len(s.Identities))
+	for k := range s.Identities {
+		ks = append(ks, k)
+	}
+	sort.Strings(ks)
+	return ks
+}
+
+// Put stores c under its key and makes it active, returning the key.
+func (s *IdentityStore) Put(c *Credentials) string {
+	if s.Identities == nil {
+		s.Identities = map[string]*Credentials{}
+	}
+	k := c.key()
+	s.Identities[k] = c
+	s.Active = k
+	return k
+}
+
+// Remove deletes an identity; Save re-points Active if it was the one removed.
+func (s *IdentityStore) Remove(key string) { delete(s.Identities, key) }
+
+// resolve turns a user selector into a stored key: an exact key wins; otherwise
+// a bare owner matches iff exactly one identity carries it.
+func (s *IdentityStore) resolve(sel string) (string, error) {
+	if _, ok := s.Identities[sel]; ok {
+		return sel, nil
+	}
+	var match []string
+	for _, k := range s.keys() {
+		if s.Identities[k].Owner == sel {
+			match = append(match, k)
+		}
+	}
+	switch len(match) {
+	case 1:
+		return match[0], nil
+	case 0:
+		return "", fmt.Errorf("no stored identity for %q (see `hanzo auth list`)", sel)
+	default:
+		return "", fmt.Errorf("%q is ambiguous across %s — pass the full owner/name key", sel, strings.Join(match, ", "))
+	}
+}
+
+// Save persists the store (0600) and mirrors the active identity into
+// credentials.json for legacy single-file readers. When the store is empty it
+// removes both files. Active is normalized to a real key first.
+func (s *IdentityStore) Save() error {
+	if _, ok := s.Identities[s.Active]; !ok {
+		s.Active = ""
+		if ks := s.keys(); len(ks) > 0 {
+			s.Active = ks[0]
+		}
+	}
+	if len(s.Identities) == 0 {
+		return clearCredentialStore()
+	}
+	p, err := identitiesPath()
+	if err != nil {
+		return err
+	}
+	if err := writeJSON(p, s, 0o600); err != nil {
+		return err
+	}
+	return s.Identities[s.Active].Save() // mirror active → credentials.json (0600)
+}
+
+// SaveActive writes c back as the active identity (store + mirror), keeping the
+// two consistent after an in-place token refresh. With no store yet it falls
+// back to the single-file write.
+func SaveActive(c *Credentials) error {
+	s, err := LoadIdentities()
+	if err != nil {
+		return err
+	}
+	if len(s.Identities) == 0 {
+		return c.Save()
+	}
+	k := s.Active
+	if k == "" || s.Identities[k] == nil {
+		k = c.key()
+	}
+	s.Identities[k] = c
+	s.Active = k
+	return s.Save()
+}
+
+// clearCredentialStore removes the identity store and its credentials.json
+// mirror (used by logout when the last identity is removed).
+func clearCredentialStore() error {
+	for _, pathOf := range []func() (string, error){credentialsPath, identitiesPath} {
+		p, err := pathOf()
+		if err != nil {
+			return err
+		}
+		if err := os.Remove(p); err != nil && !os.IsNotExist(err) {
+			return err
+		}
+	}
+	return nil
+}
+
 // ---------------------------------------------------------------------------
 // Env — the effective, resolved settings a command operates with.
 // ---------------------------------------------------------------------------
@@ -284,6 +458,22 @@ func (e *Env) accessToken() string {
 	return firstNonEmpty(os.Getenv("HANZO_TOKEN"), e.creds.AccessToken)
 }
 
+// freshAccessToken returns the IAM user token only while it is not yet expired.
+// accessToken() stays expiry-agnostic so `hanzo whoami` can report a dead token
+// rather than masking it as logged-out; freshAccessToken is the code-agent path,
+// where an expired token would 401 a session a still-valid hk- key could serve.
+// No expiry recorded (a raw HANZO_TOKEN with no claims) ⟹ trust it as-is.
+func (e *Env) freshAccessToken() string {
+	tok := e.accessToken()
+	if tok == "" {
+		return ""
+	}
+	if exp := e.creds.Expiry; exp > 0 && time.Now().Unix() >= exp {
+		return ""
+	}
+	return tok
+}
+
 // platformToken resolves the platform control-plane service token. The
 // platform REST surface is machine-to-machine (it cannot validate IAM user
 // tokens), so apps/clusters/redeploy authenticate with this, sourced from
@@ -300,7 +490,7 @@ func (e *Env) platformToken(flagVal string) string {
 }
 
 // buildToken resolves the platform build-enqueue token (a distinct credential
-// from the service token — see /v1/arcd/enqueue).
+// from the service token — see /v1/runner).
 func (e *Env) buildToken(flagVal string) string {
 	return firstNonEmpty(
 		flagVal,
@@ -362,6 +552,17 @@ func newRootCmd() *cobra.Command {
 			env.out = cmd.OutOrStdout()
 			return nil
 		},
+		// Bare `hanzo` gets you coding: log in if needed, then drop into the
+		// configured agent (code_tool, else dev) on a Hanzo cloud model — one word,
+		// billed to your account. `hanzo <cmd>` still runs that command.
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if codeToken(env) == "" {
+				if err := runLogin(env, &loginFlags{}, cmd); err != nil {
+					return err
+				}
+			}
+			return runCode(env, defaultAgent(env), nil)
+		},
 	}
 
 	pf := root.PersistentFlags()
@@ -390,6 +591,13 @@ func newRootCmd() *cobra.Command {
 		newK8sCmd(envOf, &f),
 		newConfigCmd(),
 		newSecurityCmd(envOf),
+		newGPUCmd(envOf, &f),
+		newEngineCmd(envOf, &f),
+		newCodeCmd(envOf, &f),
+		newRunnerCmd(envOf, &f),
+		newRunCmd(envOf, &f),
+		newAgentCmd(envOf, &f),
+		newBotCmd(envOf, &f),
 	)
 	return root
 }
@@ -418,7 +626,7 @@ func newConfigCmd() *cobra.Command {
 		PersistentPreRunE: func(*cobra.Command, []string) error { return nil },
 	}
 
-	configKeys := []string{"org", "output", "iam_issuer", "platform_url", "cloud_url", "client_id"}
+	configKeys := []string{"org", "output", "iam_issuer", "platform_url", "cloud_url", "client_id", "code_tool", "code_model"}
 
 	get := &cobra.Command{
 		Use:   "get <key>",
@@ -506,6 +714,10 @@ func (c *Config) field(key string) (string, error) {
 		return c.CloudURL, nil
 	case "client_id":
 		return c.ClientID, nil
+	case "code_tool":
+		return c.CodeTool, nil
+	case "code_model":
+		return c.CodeModel, nil
 	default:
 		return "", fmt.Errorf("unknown config key %q", key)
 	}
@@ -529,6 +741,13 @@ func (c *Config) setField(key, val string) error {
 		c.CloudURL = val
 	case "client_id":
 		c.ClientID = val
+	case "code_tool":
+		if _, ok := codeAgents[val]; !ok {
+			return fmt.Errorf("code_tool must be one of: claude, codex, dev")
+		}
+		c.CodeTool = val
+	case "code_model":
+		c.CodeModel = val
 	default:
 		return fmt.Errorf("unknown config key %q", key)
 	}

cli/code.go

@@ -0,0 +1,638 @@
+package cli
+
+// code.go — `hanzo code <agent> [model]`: launch a coding agent on the Hanzo AI
+// cloud. ONE way to start ANY agent on ANY Hanzo model: the endpoint, the
+// credential and the model are injected for you; nothing to export, nothing to
+// remember.
+//
+//	hanzo code claude              # Claude Code on the default model
+//	hanzo code codex deepseek-v4-pro
+//	hanzo code dev glm5.2          # ids are resolved fuzzily: glm5.2 -> glm-5.2
+//	hanzo code ls                  # what can I run?
+//
+// Two wire protocols cover all three agents: Claude Code speaks Anthropic,
+// Codex and @hanzo/dev (a Codex fork) speak OpenAI — so an agent is just a
+// binary + a wire + the flag that turns approvals off. Agents run full-auto by
+// default (--safe restores prompting).
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+	"unicode"
+
+	"github.com/spf13/cobra"
+)
+
+// defaultCodeModel is the model `hanzo code <agent>` runs when no model is
+// named. It must be a catalog-served id with working tool calls: coding agents
+// cannot operate on a text-only model even when its SSE transport is healthy.
+// zen5 is the flagship GLM-5.2-class capability alias (1M ctx, tool-capable) —
+// the frontier coding tier. Do not use the virtual `best`: Claude Code treats
+// it (like `opus`/`sonnet`/`haiku`) as a reserved alias and rewrites it to a
+// claude-* id that api.hanzo.ai does not serve. Override per invocation with an
+// explicit id: `hanzo code claude zen5-pro`.
+const defaultCodeModel = "zen5"
+
+// A zenTier bridges a model id Claude Code recognizes (the carrier) to the zen
+// alias api.hanzo.ai serves. CC sizes a model's context window and features only
+// from ids it knows; an unknown id like "zen5-pro" gets a 128K budget and is
+// rejected client-side above it — the "max context 131072" the server never
+// actually imposes. Nothing lets us declare a custom model's window, so the
+// carrier (a known 1M id, [1m] where needed) unlocks the budget and modelOverrides
+// rewrites it back to zen before the request leaves the client — the carrier never
+// reaches the server. Requires Claude Code v2.1.200+.
+type zenTier struct {
+	zen     string // served zen alias — the wire model api.hanzo.ai receives
+	carrier string // recognized id CC budgets from; "" pins zen directly (fast tiers, never >128K)
+	env     string // ANTHROPIC_DEFAULT_*_MODEL slot ("" = selectable, no slot)
+	name    string // /model picker label (via _NAME, gateway-effective)
+	desc    string // /model picker description (via _DESCRIPTION)
+}
+
+// slotID is the tier's wire value: its carrier, or the zen id when direct.
+func (t zenTier) slotID() string {
+	if t.carrier != "" {
+		return t.carrier
+	}
+	return t.zen
+}
+
+// zenTiers is the ONE source of truth for the CC-tier ⇆ zen mapping — the wire
+// env, picker branding, and modelOverrides all derive from it. Every zen id must
+// be one api.hanzo.ai serves (TestZenTiersServeReal); zen5-mini/max/ultra are
+// listed but not served, so fable maps to zen5-pro until zen5-max returns.
+var zenTiers = []zenTier{
+	{zen: "zen5-flash", env: "ANTHROPIC_DEFAULT_HAIKU_MODEL", name: "Zen5 Flash", desc: "Hanzo Zen5 Flash — fast, cheap tier"},
+	{zen: "zen5", carrier: "claude-sonnet-4-6[1m]", env: "ANTHROPIC_DEFAULT_SONNET_MODEL", name: "Zen5", desc: "Hanzo Zen5 — frontier tier (1M context)"},
+	{zen: "zen5-pro", carrier: "claude-opus-4-8[1m]", env: "ANTHROPIC_DEFAULT_OPUS_MODEL", name: "Zen5 Pro", desc: "Hanzo Zen5 Pro — DeepSeek-V4 class (1M context)"},
+	{zen: "zen5-pro", carrier: "claude-fable-5[1m]", env: "ANTHROPIC_DEFAULT_FABLE_MODEL", name: "Zen5 Pro (max effort)", desc: "Hanzo Zen5 Pro, top tier (1M context)"},
+	{zen: "zen5-coder", carrier: "claude-sonnet-5", name: "Zen5 Coder", desc: "Hanzo Zen5 Coder — code-specialized (1M context)"},
+}
+
+// zenCarrier maps a resolved zen alias to the carrier CC budgets from; an unknown
+// id passes through with CC's default budget.
+func zenCarrier(model string) string {
+	for _, t := range zenTiers {
+		if t.zen == model {
+			return t.slotID()
+		}
+	}
+	return model
+}
+
+// stripModelSuffix drops the "[1m]" suffix so a carrier matches its override key.
+func stripModelSuffix(id string) string {
+	if i := strings.IndexByte(id, '['); i >= 0 {
+		return id[:i]
+	}
+	return id
+}
+
+// claudeModelOverrides is the carrier→zen map for settings.json: CC budgets from
+// the carrier key and sends the zen value on the wire. Direct tiers need no entry.
+func claudeModelOverrides() map[string]string {
+	m := make(map[string]string, len(zenTiers))
+	for _, t := range zenTiers {
+		if t.carrier != "" {
+			m[stripModelSuffix(t.carrier)] = t.zen
+		}
+	}
+	return m
+}
+
+// wire builds the env that points an agent's SDK at the Hanzo cloud.
+type wire func(base, token, model string) map[string]string
+
+// anthropicWire points Claude Code at the Hanzo cloud and pins each CC tier slot
+// to its carrier (see zenTier), so subagents, the classifier, and /compact get
+// the right context budget while modelOverrides rewrites carriers back to zen ids
+// on the wire. `model` arrives already mapped to its carrier (runCode).
+func anthropicWire(base, token, model string) map[string]string {
+	env := map[string]string{
+		"ANTHROPIC_BASE_URL":   base,
+		"ANTHROPIC_AUTH_TOKEN": token,
+		"ANTHROPIC_MODEL":      model,
+	}
+	for _, t := range zenTiers {
+		if t.env == "" {
+			continue
+		}
+		env[t.env] = t.slotID()
+		env[t.env+"_NAME"] = t.name
+		env[t.env+"_DESCRIPTION"] = t.desc
+		// SMALL_FAST_MODEL is deprecated AND not rewritten by modelOverrides, so
+		// it must hold a served zen id directly — mirror the (direct) haiku slot.
+		if t.env == "ANTHROPIC_DEFAULT_HAIKU_MODEL" {
+			env["ANTHROPIC_SMALL_FAST_MODEL"] = t.slotID()
+		}
+	}
+	return env
+}
+
+func openaiWire(base, token, _ string) map[string]string {
+	return map[string]string{
+		"OPENAI_BASE_URL": strings.TrimSuffix(base, "/") + "/v1",
+		"OPENAI_API_KEY":  token,
+	}
+}
+
+type codeAgent struct {
+	bin          string                     // executable to exec
+	wire         wire                       // how it finds the cloud
+	fullAuto     []string                   // flags that bypass approval prompts
+	modelArg     []string                   // how the model is passed on argv (empty: via env)
+	carrier      func(model string) string  // maps the resolved model to a client-recognized id (claude: zen→carrier); nil = pass through
+	provider     func(base string) []string // agents that need the endpoint declared, not just env'd
+	clear        []string                   // env that would shadow the wire (a stale key in the shell)
+	configHome   string                     // env var that relocates the agent's config dir to ~/.hanzo ("" = share the user's own install)
+	seed         func(dir string) error     // one-time defaults for the isolated config dir
+	appendSystem []string                   // --append-system-prompt + text; ALWAYS applied (identity, not a permission bypass — present in --safe too)
+	mcp          bool                       // auto-wire the Hanzo MCP server (code/vector/web/vision tools) as an stdio server scoped to the cwd
+	install      string                     // hint when the binary is missing
+}
+
+// codex and @hanzo/dev share a lineage (dev is a Codex fork), hence a wire.
+// They also ignore OPENAI_BASE_URL and talk to chatgpt.com unless a provider is
+// declared, so declare Hanzo as the provider and select it.
+func codexLike(bin, install string) codeAgent {
+	return codeAgent{
+		bin:      bin,
+		wire:     openaiWire,
+		fullAuto: []string{"--dangerously-bypass-approvals-and-sandbox"},
+		modelArg: []string{"-m"},
+		provider: func(base string) []string {
+			return []string{
+				"-c", "model_provider=hanzo",
+				"-c", `model_providers.hanzo.name="Hanzo"`,
+				"-c", fmt.Sprintf(`model_providers.hanzo.base_url="%s/v1"`, strings.TrimSuffix(base, "/")),
+				"-c", `model_providers.hanzo.env_key="OPENAI_API_KEY"`,
+				"-c", `model_providers.hanzo.wire_api="responses"`,
+			}
+		},
+		install: install,
+	}
+}
+
+// zenIdentityPrompt is appended to Claude Code's base system prompt so a model
+// served through the Hanzo cloud self-identifies as a Hanzo Zen model. It is an
+// APPEND, not a replace: Claude Code keeps its base prompt (tool-use, safety,
+// coding conventions); only the model's identity is Hanzo Zen. The model is
+// served as a zen5 alias via api.hanzo.ai. Passed as --append-system-prompt,
+// present in --safe too (identity is not a permission bypass).
+const zenIdentityPrompt = "You are running through the Hanzo AI cloud as a Hanzo Zen model (the `zen5` capability tier, served via api.hanzo.ai). When asked what model or assistant you are, identify as a Hanzo Zen model. You are operating inside the Claude Code harness; keep its tool-use, safety, and coding conventions — only your identity is Hanzo Zen."
+
+var codeAgents = map[string]codeAgent{
+	"claude": {
+		bin:      "claude",
+		wire:     anthropicWire,
+		fullAuto: []string{"--dangerously-skip-permissions"},
+		// --model forces the session model on argv. Claude Code persists the
+		// user's last /model selection (e.g. the reserved word "best"), and that
+		// persisted choice OVERRIDES ANTHROPIC_MODEL — so the env var alone cannot
+		// pin the model. --model is the per-session override that beats it. CC
+		// budgets the context window from this (carrier) id, then rewrites it to
+		// the zen alias via modelOverrides before the request leaves the client —
+		// so api.hanzo.ai serves the zen id regardless of what /model last held.
+		modelArg: []string{"--model"},
+		// zen→carrier: hand CC a model it recognizes so it grants the full (1M)
+		// context budget; claudeSettings' modelOverrides maps it back to zen.
+		carrier: zenCarrier,
+		// Stamp the identity: append the Hanzo Zen identity to CC's base prompt so
+		// the served model says it is a Hanzo Zen model when asked. An append (not
+		// --system-prompt) keeps CC's harness prompt intact; applied in --safe too.
+		appendSystem: []string{"--append-system-prompt", zenIdentityPrompt},
+		clear:        []string{"ANTHROPIC_API_KEY"}, // outranks AUTH_TOKEN: a stale one silently wins
+		// Its own config home under ~/.hanzo, not the user's ~/.claude. Claude
+		// Code and `hanzo code claude` are independent products: sharing one
+		// mutable config braids them — the user's saved /model (e.g. "fable")
+		// leaks in as the session identity, and hanzo's zen5 picks leak back out.
+		// A separate home decomplects them; the injected zen5 slots then show
+		// cleanly in /model instead of a stale saved value.
+		configHome: "CLAUDE_CONFIG_DIR",
+		seed:       seedClaudeConfig,
+		// Auto-wire the Hanzo MCP server so `hanzo code claude` starts with the
+		// Hanzo tool lattice (code search over the cloud index, web search, vision,
+		// fs/exec/git) instead of a bare model. Resolved + injected in runCode.
+		mcp:     true,
+		install: "npm i -g @anthropic-ai/claude-code",
+	},
+	"codex": codexLike("codex", "npm i -g @openai/codex"),
+	"dev":   codexLike("dev", "npm i -g @hanzo/dev"),
+}
+
+// defaultAgent is the agent `hanzo code` (no agent named) and bare `hanzo` launch:
+// HANZO_CODE_TOOL, else the config `code_tool`, else dev — the Hanzo agent. An
+// unknown value falls back to dev rather than failing, so a stale preference never
+// blocks the default flow.
+func defaultAgent(env *Env) codeAgent {
+	name := firstNonEmpty(os.Getenv("HANZO_CODE_TOOL"), env.cfg.CodeTool)
+	if a, ok := codeAgents[name]; ok {
+		return a
+	}
+	return codeAgents["dev"]
+}
+
+func newCodeCmd(envOf func() *Env, _ *globalFlags) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "code [agent] [model] [-- args]",
+		Short: "Launch a coding agent (dev, claude, codex) on a Hanzo cloud model",
+		Long: "Run @hanzo/dev, Claude Code, or Codex against api.hanzo.ai with the endpoint,\n" +
+			"credential and model injected — no env vars to remember. `hanzo code` alone runs\n" +
+			"dev (the Hanzo agent); name an agent to pick another. Model ids resolve fuzzily\n" +
+			"(glm5.2 -> glm-5.2) and agents run full-auto unless you pass --safe.",
+		Example: "  hanzo code                 # dev, the default agent\n" +
+			"  hanzo code claude\n" +
+			"  hanzo code codex deepseek-v4-pro\n" +
+			"  hanzo code dev glm5.2 -- --resume\n" +
+			"  hanzo code ls",
+		// Bare `hanzo code` (or `hanzo code <model>/-- args` with no agent name) runs
+		// the configured default agent (code_tool, else dev). A recognized agent name
+		// (or `ls`) dispatches to its subcommand; anything else is the agent's args, so
+		// `hanzo code glm5.2` works too.
+		DisableFlagParsing: true,
+		RunE: func(c *cobra.Command, args []string) error {
+			if len(args) > 0 {
+				if _, isAgent := codeAgents[args[0]]; isAgent || args[0] == "ls" {
+					sub, _, err := c.Find(args)
+					if err == nil && sub != c {
+						sub.SetArgs(args[1:])
+						return sub.Execute()
+					}
+				}
+			}
+			return runCode(envOf(), defaultAgent(envOf()), args)
+		},
+	}
+
+	names := make([]string, 0, len(codeAgents))
+	for name := range codeAgents {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+
+	for _, name := range names {
+		agent := codeAgents[name]
+		cmd.AddCommand(&cobra.Command{
+			Use:                name + " [model] [-- args]",
+			Short:              "Launch " + name + " on a Hanzo model (default: " + defaultCodeModel + ")",
+			DisableFlagParsing: true, // agent flags (--resume, -c …) pass straight through
+			RunE: func(c *cobra.Command, args []string) error {
+				return runCode(envOf(), agent, args)
+			},
+		})
+	}
+
+	cmd.AddCommand(&cobra.Command{
+		Use:     "ls",
+		Aliases: []string{"models", "list"},
+		Short:   "List the models this account can run",
+		Args:    cobra.NoArgs,
+		RunE: func(c *cobra.Command, _ []string) error {
+			env := envOf()
+			models, err := catalog(env)
+			if err != nil {
+				return err
+			}
+			for _, m := range models {
+				fmt.Fprintln(env.out, m)
+			}
+			return nil
+		},
+	})
+	return cmd
+}
+
+func runCode(env *Env, agent codeAgent, args []string) error {
+	bin, err := exec.LookPath(agent.bin)
+	if err != nil {
+		return fmt.Errorf("%s is not installed — try: %s", agent.bin, agent.install)
+	}
+	token := codeToken(env)
+	if token == "" {
+		return fmt.Errorf("no Hanzo credential — run `hanzo login`, or set HANZO_API_KEY")
+	}
+	base := strings.TrimSuffix(firstNonEmpty(env.CloudURL, "https://api.hanzo.ai"), "/")
+
+	// First non-flag arg is the model; --safe is ours; the rest is the agent's.
+	model, safe, rest := "", false, make([]string, 0, len(args))
+	for _, a := range args {
+		switch {
+		case a == "--": // the separator is ours; the agent must not see it
+		case a == "--safe" || a == "--ask":
+			safe = true
+		case model == "" && !strings.HasPrefix(a, "-") && len(rest) == 0:
+			model = a
+		default:
+			rest = append(rest, a)
+		}
+	}
+	if model == "" {
+		model = defaultCodeModel
+	}
+	if model, err = resolveModel(env, model); err != nil {
+		return err
+	}
+	// Resolve the served zen id first (above), THEN hand the agent its carrier:
+	// the id its client recognizes for context/feature budgeting. The zen id is
+	// what api.hanzo.ai serves; the carrier is a client-side concern only.
+	served := model
+	if agent.carrier != nil {
+		model = agent.carrier(model)
+	}
+
+	for _, k := range agent.clear {
+		if err := os.Unsetenv(k); err != nil {
+			return err
+		}
+	}
+	// The isolated config dir is resolved BEFORE argv so the MCP config file can be
+	// written into it (and cleaned with the rest of the session state).
+	var configDir string
+	if agent.configHome != "" {
+		dir, err := hanzoDir()
+		if err != nil {
+			return err
+		}
+		if agent.seed != nil {
+			if err := agent.seed(dir); err != nil {
+				return err
+			}
+		}
+		if err := os.Setenv(agent.configHome, dir); err != nil {
+			return err
+		}
+		configDir = dir
+	}
+	// Auto-wire the Hanzo MCP server (code search over the cloud index, web search,
+	// vision, fs/exec/git) so the agent starts with the tool lattice, not a bare
+	// model. Appended to the agent's own args; a missing server warns, never blocks.
+	if agent.mcp && configDir != "" {
+		cwd, _ := os.Getwd()
+		if flags, warn := mcpArgs(configDir, cwd); warn != "" {
+			fmt.Fprintf(env.out, "hanzo mcp: %s\n", warn)
+		} else {
+			rest = append(rest, flags...)
+		}
+	}
+
+	argv := codeArgv(agent, base, model, safe, rest)
+
+	for k, v := range agent.wire(base, token, model) {
+		if err := os.Setenv(k, v); err != nil {
+			return err
+		}
+	}
+	if served != model {
+		fmt.Fprintf(env.out, "%s → %s (as %s) on %s\n", agent.bin, served, model, base)
+	} else {
+		fmt.Fprintf(env.out, "%s → %s on %s\n", agent.bin, model, base)
+	}
+	return execEngine(bin, argv) // exec: signals + exit code flow straight through
+}
+
+// codeArgv builds the final agent command line. Permission bypass is the
+// launcher default for every agent; --safe is the single explicit opt-out.
+func codeArgv(agent codeAgent, base, model string, safe bool, rest []string) []string {
+	argv := []string{agent.bin}
+	if !safe {
+		argv = append(argv, agent.fullAuto...)
+	}
+	if agent.provider != nil {
+		argv = append(argv, agent.provider(base)...)
+	}
+	if len(agent.modelArg) > 0 { // claude takes the model via env, codex/dev on argv
+		argv = append(argv, agent.modelArg...)
+		argv = append(argv, model)
+	}
+	argv = append(argv, agent.appendSystem...) // identity — applies in safe AND full-auto
+	argv = append(argv, rest...)
+	return argv
+}
+
+// mcpArgs resolves the Hanzo MCP server and returns the flags that attach it to a
+// claude session, scoped to cwd. It ports the Rust CLI's resolve_mcp: prefer an
+// installed `hanzo-mcp` on PATH, else `uvx hanzo-mcp` (ephemeral), else nothing —
+// MCP is an enhancement, so a missing server never blocks the session. The Hanzo
+// server is layered via --mcp-config, and --strict-mcp-config makes it the SOLE
+// MCP source: a repo's own .mcp.json is NOT loaded (it can carry a hostile stdio
+// server that would inherit the session's bearer). The config file is written into
+// the isolated config dir so it is cleaned with the rest of the hanzo session state.
+//
+// Returns the argv flags to append (possibly empty) and a warning to surface when
+// no server could be resolved, so the caller can tell the user tools are absent.
+func mcpArgs(configDir, cwd string) (flags []string, warn string) {
+	prog, args := resolveHanzoMCP(cwd)
+	if prog == "" {
+		return nil, "hanzo-mcp not found (install: `uv tool install hanzo-mcp`); launching without Hanzo tools"
+	}
+	cfg := mcpConfigJSON(prog, args)
+	path := filepath.Join(configDir, "mcp.json")
+	if err := os.WriteFile(path, []byte(cfg), 0o600); err != nil {
+		return nil, "could not write MCP config; launching without Hanzo tools"
+	}
+	// --strict-mcp-config: the Hanzo server is the ONLY MCP source (a repo
+	// .mcp.json is ignored — it could ship a bearer-exfiltrating stdio server).
+	return []string{"--mcp-config", path, "--strict-mcp-config"}, ""
+}
+
+// resolveHanzoMCP finds how to launch hanzo-mcp as an stdio server scoped to cwd:
+// an installed console script first, else uv's ephemeral runner. Empty program =
+// neither is on PATH.
+func resolveHanzoMCP(cwd string) (prog string, args []string) {
+	if p, err := exec.LookPath("hanzo-mcp"); err == nil {
+		return p, []string{"--project-dir", cwd}
+	}
+	if p, err := exec.LookPath("uvx"); err == nil {
+		return p, []string{"hanzo-mcp", "--project-dir", cwd}
+	}
+	return "", nil
+}
+
+// mcpConfigJSON is the --mcp-config document adding Hanzo's stdio server. Claude
+// requires an explicit "type". Marshaled (not fmt'd) so the cwd/program are
+// correctly escaped.
+func mcpConfigJSON(prog string, args []string) string {
+	doc := map[string]any{
+		"mcpServers": map[string]any{
+			"hanzo": map[string]any{
+				"type":    "stdio",
+				"command": prog,
+				"args":    args,
+				"env":     map[string]string{},
+			},
+		},
+	}
+	b, _ := json.Marshal(doc)
+	return string(b)
+}
+
+// seedClaudeConfig writes first-run defaults into the isolated config dir so
+// `hanzo code claude` starts clean: auto-approve, high effort, onboarding done,
+// and NO pinned model (the zen5 slots come from the injected env, not saved
+// state). It never overwrites — the user's own later edits in this dir persist.
+func seedClaudeConfig(dir string) error {
+	if err := upsertClaudeSettings(filepath.Join(dir, "settings.json")); err != nil {
+		return err
+	}
+	return writeIfAbsent(filepath.Join(dir, ".claude.json"), "{\"hasCompletedOnboarding\":true}\n")
+}
+
+// claudeSettingsBase is the first-run settings.json for `hanzo code claude`:
+// sensible agent defaults and no pinned model, so the env-injected carrier slots
+// win. effortLevel is max — the deepest reasoning tier — matching the operator's
+// /effort max session setting; zen folds it into the upstream's reasoning budget
+// (anthropicThinkingBudget → normalizeReasoning) so it reaches the model. Applied
+// only when settings.json does not yet exist — later user edits to these persist.
+var claudeSettingsBase = map[string]any{
+	"includeCoAuthoredBy":               false,
+	"permissions":                       map[string]any{"defaultMode": "auto"},
+	"skipAutoPermissionPrompt":          true,
+	"skipDangerousModePermissionPrompt": true,
+	"effortLevel":                       "max",
+	"theme":                             "dark",
+	"enableWorkflows":                   true,
+}
+
+// upsertClaudeSettings writes settings.json, (re)applying the operator-owned
+// modelOverrides (carrier→zen) on EVERY launch while preserving the user's own
+// edits to every other key. modelOverrides is policy, not preference: it must
+// track the current zenTiers so Claude Code's context-budgeting carriers keep
+// mapping to the served zen ids — so, unlike the base defaults, it is not
+// write-once. A first run (or an unreadable/corrupt file) starts from the base.
+func upsertClaudeSettings(path string) error {
+	settings := map[string]any{}
+	if b, err := os.ReadFile(path); err != nil || json.Unmarshal(b, &settings) != nil || len(settings) == 0 {
+		settings = map[string]any{}
+		for k, v := range claudeSettingsBase {
+			settings[k] = v
+		}
+	}
+	overrides := make(map[string]any, len(zenTiers))
+	for carrier, zen := range claudeModelOverrides() {
+		overrides[carrier] = zen
+	}
+	settings["modelOverrides"] = overrides
+	b, err := json.MarshalIndent(settings, "", "  ")
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(path, append(b, '\n'), 0o600)
+}
+
+// writeIfAbsent creates path with content only when it does not already exist,
+// so seeding a config dir never clobbers a user's later edits.
+func writeIfAbsent(path, content string) error {
+	if _, err := os.Stat(path); err == nil {
+		return nil
+	}
+	return os.WriteFile(path, []byte(content), 0o600)
+}
+
+// codeToken resolves the credential the agents authenticate with. Precedence:
+// an explicit HANZO_API_KEY always wins (the operator's deliberate override),
+// then the live `hanzo login` JWT, then the hk- API key chain.
+//
+// Why the JWT beats the hk- key: the JWT carries the caller's owner/project/sub
+// claims verbatim, so the identity boundary mints a billing principal on EVERY
+// deployment. The hk- key only mints a principal when the server can resolve it
+// (iamKeys.resolve, which is a no-op without IAM_MINT_CLIENT_ID/SECRET) — on a
+// deployment lacking that credential an hk- request arrives anonymous and zen's
+// billing gate 402s ("a billable tenant is required"). Preferring a FRESH JWT
+// keeps `hanzo code` working everywhere; the hk- key stays the fallback for
+// mint-credentialed servers and the explicit-override case. freshAccessToken
+// skips an expired token so it can't 401 a session a valid hk- key would serve.
+func codeToken(env *Env) string {
+	return firstNonEmpty(os.Getenv("HANZO_API_KEY"), env.freshAccessToken(), env.cfg.APIKey, storedAPIKey())
+}
+
+// storedAPIKey reads (never writes) the hk- key that hanzo-mcp and the rest of
+// the toolchain share, so one `hanzo login`/key serves every tool.
+func storedAPIKey() string {
+	dir, err := hanzoDir()
+	if err != nil {
+		return ""
+	}
+	var cfg struct {
+		APIKey string `json:"apiKey"`
+	}
+	if err := loadJSON(filepath.Join(dir, "config.json"), &cfg); err != nil {
+		return ""
+	}
+	return cfg.APIKey
+}
+
+// resolveModel turns what you typed into an id the cloud serves. Exact ids pass
+// through; otherwise ids are compared with punctuation and case removed, so
+// "glm5.2" finds "glm-5.2". An unknown id lists the near misses rather than
+// failing deep inside the agent.
+func resolveModel(env *Env, want string) (string, error) {
+	models, err := catalog(env)
+	if err != nil {
+		// Never hand an agent a model we could not confirm: it would fail deep
+		// inside the session with an opaque error. Say so here instead.
+		return "", fmt.Errorf("cannot read the model catalog: %w", err)
+	}
+	fold := func(s string) string {
+		return strings.Map(func(r rune) rune {
+			if unicode.IsLetter(r) || unicode.IsDigit(r) {
+				return unicode.ToLower(r)
+			}
+			return -1
+		}, s)
+	}
+	target := fold(want)
+	var near []string
+	for _, m := range models {
+		switch f := fold(m); {
+		case m == want, f == target:
+			return m, nil
+		case strings.Contains(f, target), strings.Contains(target, f):
+			near = append(near, m)
+		}
+	}
+	if len(near) == 1 {
+		return near[0], nil
+	}
+	if len(near) > 1 {
+		return "", fmt.Errorf("%q is ambiguous — did you mean: %s", want, strings.Join(near, ", "))
+	}
+	return "", fmt.Errorf("no model %q — run `hanzo code ls` to see what you can run", want)
+}
+
+func catalog(env *Env) ([]string, error) {
+	base := strings.TrimSuffix(firstNonEmpty(env.CloudURL, "https://api.hanzo.ai"), "/")
+	req, err := http.NewRequest(http.MethodGet, base+"/v1/models", nil)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Authorization", "Bearer "+codeToken(env))
+	resp, err := (&http.Client{Timeout: 15 * time.Second}).Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("%s/v1/models: %s", base, resp.Status)
+	}
+	var body struct {
+		Data []struct {
+			ID string `json:"id"`
+		} `json:"data"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
+		return nil, err
+	}
+	ids := make([]string, 0, len(body.Data))
+	for _, m := range body.Data {
+		ids = append(ids, m.ID)
+	}
+	sort.Strings(ids)
+	return ids, nil
+}

cli/code_test.go

@@ -0,0 +1,409 @@
+// Copyright 2023-2025 Hanzo AI Inc. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cli
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"slices"
+	"testing"
+	"time"
+)
+
+func TestCodeAgentsBypassPermissionsByDefault(t *testing.T) {
+	tests := []struct {
+		name string
+		flag string
+	}{
+		{name: "claude", flag: "--dangerously-skip-permissions"},
+		{name: "codex", flag: "--dangerously-bypass-approvals-and-sandbox"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			agent := codeAgents[tt.name]
+			argv := codeArgv(agent, "https://api.hanzo.ai", defaultCodeModel, false, nil)
+			if !slices.Contains(argv, tt.flag) {
+				t.Fatalf("default argv %q does not contain permission bypass %q", argv, tt.flag)
+			}
+
+			safeArgv := codeArgv(agent, "https://api.hanzo.ai", defaultCodeModel, true, nil)
+			if slices.Contains(safeArgv, tt.flag) {
+				t.Fatalf("--safe argv %q still contains permission bypass %q", safeArgv, tt.flag)
+			}
+		})
+	}
+}
+
+// TestCodeTokenPrecedence locks in the 402 unblock: a fresh `hanzo login` JWT
+// (which carries owner/project/sub on EVERY deployment) beats the hk- API key
+// (which only mints a billing principal where the server has IAM_MINT_CLIENT_*).
+// On a mint-less deployment an hk- request arrives anonymous and zen 402s; the
+// JWT must win when it is live. An EXPIRED JWT must NOT win — it would 401 a
+// session a valid hk- key would still serve — so it falls through to the key.
+// HANZO_API_KEY stays the deliberate operator override at the top.
+func TestCodeTokenPrecedence(t *testing.T) {
+	// freshExpiry is comfortably in the future without a literal unix timestamp.
+	freshExpiry := time.Now().Add(1 * time.Hour).Unix()
+
+	cases := []struct {
+		name    string
+		envKey  string // HANZO_API_KEY override
+		creds   Credentials
+		want    string
+	}{
+		{
+			name:  "fresh JWT beats hk- key",
+			creds: Credentials{AccessToken: "jwt-live", Expiry: freshExpiry},
+			want:  "jwt-live",
+		},
+		{
+			name:  "expired JWT falls through to stored hk- key",
+			creds: Credentials{AccessToken: "jwt-dead", Expiry: time.Now().Add(-1 * time.Hour).Unix()},
+			want:  "hk-stored",
+		},
+		{
+			name:  "no JWT, no expiry record ⟹ hk- key (mint-credentialed servers)",
+			creds: Credentials{},
+			want:  "hk-stored",
+		},
+		{
+			name:  "HANZO_API_KEY overrides everything (deliberate operator override)",
+			envKey: "hk-explicit",
+			creds: Credentials{AccessToken: "jwt-live", Expiry: freshExpiry},
+			want:  "hk-explicit",
+		},
+		{
+			name:  "HANZO_API_KEY overrides even an expired JWT",
+			envKey: "hk-explicit",
+			creds: Credentials{AccessToken: "jwt-dead", Expiry: time.Now().Add(-1 * time.Hour).Unix()},
+			want:  "hk-explicit",
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			sandbox(t) // isolates HANZO_HOME + clears HANZO_TOKEN/HANZO_API_KEY
+			if tc.envKey != "" {
+				t.Setenv("HANZO_API_KEY", tc.envKey)
+			}
+			// Put the hk- key where storedAPIKey() reads it (~/.hanzo/config.json),
+			// the same path the rest of the toolchain shares it from.
+			cfgDir, _ := hanzoDir()
+			if err := os.WriteFile(filepath.Join(cfgDir, "config.json"),
+				[]byte(`{"apiKey":"hk-stored"}`), 0o600); err != nil {
+				t.Fatalf("write config.json: %v", err)
+			}
+			env := resolve(&Config{}, &tc.creds, globalFlags{})
+			if got := codeToken(env); got != tc.want {
+				t.Fatalf("codeToken = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestDefaultCodeModelIsToolCapableAlias(t *testing.T) {
+	// zen5 is the flagship GLM-5.2-class alias — tool-capable (verified live: the
+	// glm-5.2 upstream returns tool_use / stop_reason:tool_use) and the model the
+	// user's "pop open with GLM-5.2" intent maps to. It must NOT be the virtual
+	// `best` (a reserved word Claude Code rewrites to an unserved claude-* id).
+	if defaultCodeModel != "zen5" {
+		t.Fatalf("coding-agent default %q is not the flagship zen5 alias", defaultCodeModel)
+	}
+	if defaultCodeModel == "best" {
+		t.Fatal("default must be a concrete served id, never the reserved word best")
+	}
+}
+
+// TestAnthropicWirePinsCarrierTiers locks in the 1M-context fix: every CC tier
+// slot is pinned to a Claude-Code-recognized CARRIER id (so CC grants the model
+// its true, up-to-1M context budget instead of the 128K fallback it applies to
+// ids it does not know), and settings.json modelOverrides rewrites each carrier
+// back to a served zen alias before the request leaves the client — so the wire
+// model that reaches api.hanzo.ai is always zen, never the carrier. The old
+// deadlock (a raw claude-* id 403ing on the Hanzo account) cannot recur because
+// the carrier never reaches the server; the override guarantees it (asserted in
+// TestCarrierTiersAreOverridden).
+func TestAnthropicWirePinsCarrierTiers(t *testing.T) {
+	env := anthropicWire("https://api.hanzo.ai", "hk-test", "claude-opus-4-8[1m]")
+
+	want := map[string]string{
+		"ANTHROPIC_BASE_URL":             "https://api.hanzo.ai",
+		"ANTHROPIC_AUTH_TOKEN":           "hk-test",
+		"ANTHROPIC_MODEL":                "claude-opus-4-8[1m]",
+		"ANTHROPIC_SMALL_FAST_MODEL":     "zen5-flash", // deprecated var: no override applies, so a direct served zen id
+		"ANTHROPIC_DEFAULT_HAIKU_MODEL":  "zen5-flash", // fast tier is carrier-less (never needs >128K)
+		"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6[1m]",
+		"ANTHROPIC_DEFAULT_OPUS_MODEL":   "claude-opus-4-8[1m]",
+		"ANTHROPIC_DEFAULT_FABLE_MODEL":  "claude-fable-5[1m]",
+	}
+	for k, v := range want {
+		if got := env[k]; got != v {
+			t.Errorf("%s: want %q, got %q", k, v, got)
+		}
+	}
+	// Each tier slot carries a Hanzo-branded display name so the picker never
+	// shows the underlying carrier (Opus/Sonnet/Haiku) — only the Zen brand.
+	if env["ANTHROPIC_DEFAULT_OPUS_MODEL_NAME"] != "Zen5 Pro" {
+		t.Errorf("OPUS tier must display the Zen brand, got %q", env["ANTHROPIC_DEFAULT_OPUS_MODEL_NAME"])
+	}
+}
+
+// TestCarrierTiersAreOverridden is the safety net that replaces the old
+// "no claude-* in the wire" rule: a claude-* carrier in the env is SAFE only
+// because modelOverrides maps it to a served zen id. Every claude-* value the
+// wire emits must have a modelOverrides entry (keyed by its suffix-stripped id)
+// pointing at a zen alias — otherwise CC would send the raw claude-* id to
+// api.hanzo.ai and reintroduce the 403.
+func TestCarrierTiersAreOverridden(t *testing.T) {
+	env := anthropicWire("https://api.hanzo.ai", "hk-test", "claude-opus-4-8[1m]")
+	overrides := claudeModelOverrides()
+	for k, v := range env {
+		if len(v) < 6 || v[:6] != "claude" {
+			continue // only carrier ids need an override
+		}
+		zen, ok := overrides[stripModelSuffix(v)]
+		if !ok {
+			t.Errorf("%s=%q is a claude-* carrier with NO modelOverrides entry — it would reach api.hanzo.ai and 403", k, v)
+			continue
+		}
+		if len(zen) < 3 || zen[:3] != "zen" {
+			t.Errorf("%s=%q overrides to %q, which is not a zen alias", k, v, zen)
+		}
+	}
+}
+
+// TestZenCarrierRoundTrips checks the two-way mapping the fix depends on: every
+// tier's zen id maps to a carrier, and that carrier (suffix-stripped) maps back
+// to a served zen id via modelOverrides. An unknown id passes through unchanged.
+func TestZenCarrierRoundTrips(t *testing.T) {
+	overrides := claudeModelOverrides()
+	for _, tier := range zenTiers {
+		carrier := zenCarrier(tier.zen)
+		if tier.carrier == "" {
+			// Direct tier: zenCarrier returns the served zen id itself, no override.
+			if carrier != tier.zen {
+				t.Errorf("direct tier %q must map to itself, got %q", tier.zen, carrier)
+			}
+			continue
+		}
+		if carrier == tier.zen {
+			t.Errorf("zenCarrier(%q) did not map to a carrier", tier.zen)
+		}
+		if got := overrides[stripModelSuffix(carrier)]; got != tier.zen {
+			t.Errorf("carrier %q for %q overrides to %q, want %q", carrier, tier.zen, got, tier.zen)
+		}
+	}
+	if got := zenCarrier("some-raw-upstream"); got != "some-raw-upstream" {
+		t.Errorf("unknown id must pass through unchanged, got %q", got)
+	}
+}
+
+// TestClaudeArgvForcesModel locks in the fix for "everything shows up as best":
+// the claude agent must pass --model <resolved> on argv so a persisted /model
+// selection (the reserved word "best") cannot override the zen5 model the
+// launcher chose. ANTHROPIC_MODEL alone is not enough — /model beats it.
+func TestClaudeArgvForcesModel(t *testing.T) {
+	agent := codeAgents["claude"]
+	argv := codeArgv(agent, "https://api.hanzo.ai", "zen5-pro", false, nil)
+	i := slices.Index(argv, "--model")
+	if i < 0 {
+		t.Fatalf("claude argv %q does not force --model (a persisted /model selection would win)", argv)
+	}
+	if i+1 >= len(argv) || argv[i+1] != "zen5-pro" {
+		t.Fatalf("claude argv %q: --model must be followed by the resolved id zen5-pro", argv)
+	}
+	// --model is forced in --safe mode too (model pinning is independent of
+	// the permission mode).
+	safeArgv := codeArgv(agent, "https://api.hanzo.ai", "zen5-pro", true, nil)
+	if i := slices.Index(safeArgv, "--model"); i < 0 || safeArgv[i+1] != "zen5-pro" {
+		t.Fatalf("--safe argv %q must still force --model zen5-pro", safeArgv)
+	}
+}
+
+// TestClaudeAppendsZenIdentityInAllModes locks in the identity fix: the claude
+// agent appends --append-system-prompt <zenIdentityPrompt> so a Hanzo-served
+// model self-identifies as a Hanzo Zen model. Identity is not a permission
+// bypass, so it is present in --safe too (unlike --dangerously-skip-permissions).
+// codex/dev (OpenAI wire) do not carry the Anthropic-only append.
+func TestClaudeAppendsZenIdentityInAllModes(t *testing.T) {
+	agent := codeAgents["claude"]
+
+	check := func(argv []string) {
+		t.Helper()
+		i := slices.Index(argv, "--append-system-prompt")
+		if i < 0 || i+1 >= len(argv) || argv[i+1] != zenIdentityPrompt {
+			t.Fatalf("argv %q missing --append-system-prompt <zenIdentityPrompt>", argv)
+		}
+	}
+
+	// full-auto (default)
+	check(codeArgv(agent, "https://api.hanzo.ai", defaultCodeModel, false, nil))
+
+	// --safe keeps the identity (identity != permission bypass) but drops the bypass
+	safeArgv := codeArgv(agent, "https://api.hanzo.ai", defaultCodeModel, true, nil)
+	check(safeArgv)
+	if slices.Contains(safeArgv, "--dangerously-skip-permissions") {
+		t.Fatalf("--safe must not carry the permission bypass: %v", safeArgv)
+	}
+
+	// codex/dev (OpenAI wire) do not carry the Anthropic-only identity append
+	for _, name := range []string{"codex", "dev"} {
+		argv := codeArgv(codeAgents[name], "https://api.hanzo.ai", defaultCodeModel, false, nil)
+		if slices.Contains(argv, "--append-system-prompt") {
+			t.Fatalf("%s must not carry the claude-only identity append: %v", name, argv)
+		}
+	}
+}
+
+// TestClaudeAutoWiresMCP locks in the fix for "hanzo code wires no tools": the
+// claude agent must opt into MCP auto-wiring, and the resolver must produce an
+// stdio server config that is layered STRICTLY (repo .mcp.json ignored — it could
+// exfiltrate the session bearer).
+func TestClaudeAutoWiresMCP(t *testing.T) {
+	if !codeAgents["claude"].mcp {
+		t.Fatal("claude agent must set mcp:true so `hanzo code claude` starts with the Hanzo tool lattice")
+	}
+	// codex/dev are wired additively by their own provider config, not this seam.
+	for _, name := range []string{"codex", "dev"} {
+		if codeAgents[name].mcp {
+			t.Fatalf("%s must not use the claude MCP seam (it attaches Hanzo additively via -c)", name)
+		}
+	}
+
+	// The --mcp-config document is a valid single-server stdio config.
+	cfg := mcpConfigJSON("/usr/bin/hanzo-mcp", []string{"--project-dir", "/repo"})
+	var doc struct {
+		MCPServers map[string]struct {
+			Type    string   `json:"type"`
+			Command string   `json:"command"`
+			Args    []string `json:"args"`
+		} `json:"mcpServers"`
+	}
+	if err := json.Unmarshal([]byte(cfg), &doc); err != nil {
+		t.Fatalf("mcpConfigJSON is not valid JSON: %v", err)
+	}
+	h, ok := doc.MCPServers["hanzo"]
+	if !ok || h.Type != "stdio" || h.Command != "/usr/bin/hanzo-mcp" {
+		t.Fatalf("mcpConfigJSON: want one stdio server 'hanzo' → /usr/bin/hanzo-mcp, got %+v", doc.MCPServers)
+	}
+	if !slices.Contains(h.Args, "--project-dir") || !slices.Contains(h.Args, "/repo") {
+		t.Fatalf("mcpConfigJSON: server must be scoped to the project dir, got args %v", h.Args)
+	}
+
+	// mcpArgs writes the config into the isolated dir and returns the strict flags.
+	dir := t.TempDir()
+	t.Setenv("PATH", "/usr/bin/hanzo-mcp-not-here") // force the not-found path deterministically
+	flags, warn := mcpArgs(dir, "/repo")
+	if warn == "" || len(flags) != 0 {
+		t.Fatalf("with no hanzo-mcp on PATH, mcpArgs must warn and inject nothing, got flags=%v warn=%q", flags, warn)
+	}
+}
+
+// TestClaudeAgentAppliesCarrier locks in the runCode wiring: the claude agent
+// carries the zen→carrier map (so the resolved zen model is handed to CC as a
+// recognized 1M id), while codex/dev have no carrier (they speak OpenAI directly
+// and must NOT rewrite the model).
+func TestClaudeAgentAppliesCarrier(t *testing.T) {
+	if codeAgents["claude"].carrier == nil {
+		t.Fatal("claude agent must set a carrier so CC budgets the full context window")
+	}
+	if got := codeAgents["claude"].carrier("zen5-pro"); got != "claude-opus-4-8[1m]" {
+		t.Fatalf("claude carrier: zen5-pro must map to the opus carrier, got %q", got)
+	}
+	for _, name := range []string{"codex", "dev"} {
+		if codeAgents[name].carrier != nil {
+			t.Fatalf("%s speaks OpenAI directly and must not remap the model", name)
+		}
+	}
+}
+
+// servedZenIDs is the set of zen aliases api.hanzo.ai actually serves, confirmed
+// live (2026-07). zen5-mini/zen5-max/zen5-ultra are catalog-listed but 404 or
+// time out, so no tier may target them. Adding a tier forces confirming its id
+// serves and listing it here — the guard below fails otherwise.
+var servedZenIDs = map[string]bool{
+	"zen5-flash": true,
+	"zen5":       true,
+	"zen5-pro":   true,
+	"zen5-coder": true,
+}
+
+// TestZenTiersServeReal is the invariant a 1M-carrier is useless without: every
+// tier's zen wire id must be one api.hanzo.ai serves. A carrier that budgets 1M
+// but rewrites to a 404 id just fails later, opaquely.
+func TestZenTiersServeReal(t *testing.T) {
+	for _, tier := range zenTiers {
+		if !servedZenIDs[tier.zen] {
+			t.Errorf("tier %q → zen id %q is not in the confirmed-served set; a carrier to an unserved id 404s", tier.carrier, tier.zen)
+		}
+	}
+}
+
+// TestUpsertClaudeSettings checks the seed: a fresh dir gets base defaults plus
+// the carrier→zen modelOverrides, and a re-seed REFRESHES modelOverrides (policy)
+// while PRESERVING a user's own edits to other keys (preference).
+func TestUpsertClaudeSettings(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "settings.json")
+
+	if err := upsertClaudeSettings(path); err != nil {
+		t.Fatalf("first seed failed: %v", err)
+	}
+	read := func() map[string]any {
+		b, err := os.ReadFile(path)
+		if err != nil {
+			t.Fatalf("read settings: %v", err)
+		}
+		var m map[string]any
+		if err := json.Unmarshal(b, &m); err != nil {
+			t.Fatalf("settings.json is not valid JSON: %v", err)
+		}
+		return m
+	}
+	s := read()
+	if s["effortLevel"] != "max" {
+		t.Errorf("base defaults missing: effortLevel = %v", s["effortLevel"])
+	}
+	ov, ok := s["modelOverrides"].(map[string]any)
+	if !ok {
+		t.Fatalf("modelOverrides missing or wrong type: %T", s["modelOverrides"])
+	}
+	if ov["claude-opus-4-8"] != "zen5-pro" {
+		t.Errorf("modelOverrides[claude-opus-4-8] = %v, want zen5-pro", ov["claude-opus-4-8"])
+	}
+
+	// User edits a preference and adds a key; re-seed must keep both.
+	s["effortLevel"] = "low"
+	s["userKey"] = "keepme"
+	b, _ := json.Marshal(s)
+	if err := os.WriteFile(path, b, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := upsertClaudeSettings(path); err != nil {
+		t.Fatalf("re-seed failed: %v", err)
+	}
+	s2 := read()
+	if s2["effortLevel"] != "low" {
+		t.Errorf("re-seed clobbered user edit: effortLevel = %v, want low", s2["effortLevel"])
+	}
+	if s2["userKey"] != "keepme" {
+		t.Errorf("re-seed dropped user key: userKey = %v", s2["userKey"])
+	}
+	ov2, _ := s2["modelOverrides"].(map[string]any)
+	if ov2["claude-opus-4-8"] != "zen5-pro" {
+		t.Errorf("re-seed lost modelOverrides: %v", ov2)
+	}
+}

cli/commands.go

@@ -365,7 +365,7 @@ func printTarget(w io.Writer, t *Target) {
 }
 
 // ---------------------------------------------------------------------------
-// build — platform-native (arcd) build enqueue.
+// build — platform-native build (runner fabric) enqueue.
 // ---------------------------------------------------------------------------
 
 func newBuildCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
@@ -373,8 +373,8 @@ func newBuildCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
 	var buildToken string
 	cmd := &cobra.Command{
 		Use:   "build <repo>",
-		Short: "Enqueue a platform-native (arcd) build (no GitHub builders)",
-		Long: "Enqueue a build on the platform's native CI fabric (arcd). Builds and pushes\n" +
+		Short: "Enqueue a platform-native build on the runner fabric (no GitHub builders)",
+		Long: "Enqueue a build on the platform's native runner fabric. Builds and pushes\n" +
 			"the named image at a SHA; on completion the platform patches the operator\n" +
 			"Service CR (build-job → deploy). Requires a live registered runner for the\n" +
 			"target pool (409 otherwise).",

cli/commands_test.go

@@ -136,7 +136,7 @@ func TestBuildCommandValidation(t *testing.T) {
 
 func TestBuildCommand(t *testing.T) {
 	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/v1/arcd/enqueue" {
+		if r.URL.Path != "/v1/runner" {
 			t.Errorf("path = %s", r.URL.Path)
 		}
 		if got := r.Header.Get("Authorization"); got != "Bearer bt" {

cli/device.go

@@ -0,0 +1,182 @@
+// device.go — RFC 8628 Device Authorization Grant for `hanzo login`: the ONE
+// way any machine signs in. The CLI asks IAM for a device+user code, shows the
+// verification link as text AND a terminal QR (scan with a phone), and polls
+// the token endpoint until the user approves in any browser session. No
+// password ever touches this terminal; works headless (GPU boxes, ssh, CI).
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/mdp/qrterminal/v3"
+	"github.com/spf13/cobra"
+)
+
+// deviceAuthResp is the RFC 8628 device authorization response.
+type deviceAuthResp struct {
+	DeviceCode              string `json:"device_code"`
+	UserCode                string `json:"user_code"`
+	VerificationURI         string `json:"verification_uri"`
+	VerificationURIComplete string `json:"verification_uri_complete"`
+	ExpiresIn               int64  `json:"expires_in"`
+	Interval                int64  `json:"interval"`
+	Error                   string `json:"error"`
+	ErrorDesc               string `json:"error_description"`
+}
+
+const deviceGrantType = "urn:ietf:params:oauth:grant-type:device_code"
+
+// defaultDeviceClientID is the first-party client the device grant runs as.
+// hanzo-app is the one Hanzo client IAM seeds with device_code enabled
+// (iam cmd/iam/cli/init_apps.go brandGrantTypes); hanzo-console stays the
+// password-grant client. hanzo-dev's live device flow uses the same pair of
+// endpoints and this client, so the two CLIs share one server-side config.
+const defaultDeviceClientID = "hanzo-app"
+
+// rawForm posts a form to an oauth endpoint and returns the decoded token
+// response WITHOUT mapping OAuth errors to Go errors — the device poll must
+// inspect authorization_pending / slow_down itself.
+func (c *iamClient) rawForm(ctx context.Context, endpoint string, form url.Values) (*tokenResp, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.issuer+endpoint, strings.NewReader(form.Encode()))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.Header.Set("Accept", "application/json")
+	req.Header.Set("User-Agent", "hanzo-cli/"+Version)
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	var tr tokenResp
+	if err := json.Unmarshal(body, &tr); err != nil {
+		return nil, fmt.Errorf("iam %s: HTTP %d: %s", endpoint, resp.StatusCode, strings.TrimSpace(string(body)))
+	}
+	return &tr, nil
+}
+
+// deviceAuth starts the device flow: mints a device_code + user_code pair.
+// Query-param shape matches hanzo-dev's verified client (oidc_device_auth.rs).
+func (c *iamClient) deviceAuth(ctx context.Context, scope string) (*deviceAuthResp, error) {
+	q := url.Values{"client_id": {c.clientID}, "scope": {scope}, "response_type": {"device_code"}}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.issuer+"/v1/iam/oauth/device?"+q.Encode(), nil)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Accept", "application/json")
+	req.Header.Set("User-Agent", "hanzo-cli/"+Version)
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	var da deviceAuthResp
+	if err := json.Unmarshal(body, &da); err != nil {
+		return nil, fmt.Errorf("iam device auth: HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
+	}
+	if da.Error != "" {
+		return nil, fmt.Errorf("iam device auth: %s: %s", da.Error, da.ErrorDesc)
+	}
+	if da.DeviceCode == "" || da.UserCode == "" {
+		return nil, fmt.Errorf("iam device auth: HTTP %d: no device_code in response", resp.StatusCode)
+	}
+	return &da, nil
+}
+
+// pollDeviceToken polls the token endpoint until the user approves, the code
+// expires, or ctx ends. authorization_pending keeps polling; slow_down backs
+// off per RFC 8628 §3.5.
+func (c *iamClient) pollDeviceToken(ctx context.Context, da *deviceAuthResp) (*tokenResp, error) {
+	interval := time.Duration(max64(da.Interval, 1)) * time.Second
+	deadline := time.Now().Add(time.Duration(da.ExpiresIn) * time.Second)
+	for {
+		select {
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		case <-time.After(interval):
+		}
+		if time.Now().After(deadline) {
+			return nil, fmt.Errorf("device code expired before approval — run `hanzo login` again")
+		}
+		tr, err := c.rawForm(ctx, "/v1/iam/oauth/token", url.Values{
+			"grant_type":  {deviceGrantType},
+			"client_id":   {c.clientID},
+			"device_code": {da.DeviceCode},
+		})
+		if err != nil {
+			return nil, err
+		}
+		switch tr.Error {
+		case "":
+			if tr.AccessToken == "" {
+				return nil, fmt.Errorf("iam device token: empty access_token")
+			}
+			return tr, nil
+		case "authorization_pending":
+			// approved not yet — keep waiting
+		case "slow_down":
+			interval += 5 * time.Second
+		case "expired_token":
+			return nil, fmt.Errorf("device code expired before approval — run `hanzo login` again")
+		default:
+			return nil, fmt.Errorf("iam device token: %s: %s", tr.Error, tr.ErrorDesc)
+		}
+	}
+}
+
+// runDeviceLogin drives the interactive device sign-in and returns credentials.
+func runDeviceLogin(cmd *cobra.Command, env *Env, scope string) (*Credentials, error) {
+	out := cmd.OutOrStdout()
+	// An explicit --client-id/HANZO_CLIENT_ID override wins; otherwise the
+	// device grant runs as hanzo-app (see defaultDeviceClientID).
+	clientID := env.ClientID
+	if clientID == "" || clientID == defaultClientID {
+		clientID = defaultDeviceClientID
+	}
+	iam := newIAMClient(env.IAMIssuer, clientID)
+	da, err := iam.deviceAuth(cmd.Context(), scope)
+	if err != nil {
+		return nil, err
+	}
+	link := firstNonEmpty(da.VerificationURIComplete, da.VerificationURI)
+	fmt.Fprintf(out, "\nSign in on any device:\n\n")
+	printQR(out, link)
+	fmt.Fprintf(out, "\n  %s\n", link)
+	if da.VerificationURI != "" && da.UserCode != "" {
+		fmt.Fprintf(out, "  or open %s and enter code %s\n", da.VerificationURI, da.UserCode)
+	}
+	fmt.Fprintf(out, "\nWaiting for approval…\n")
+	tr, err := iam.pollDeviceToken(cmd.Context(), da)
+	if err != nil {
+		return nil, err
+	}
+	return credsFromToken(tr), nil
+}
+
+// printQR renders a scannable QR of the verification link using half blocks
+// (compact enough for a default 80×24 terminal).
+func printQR(w io.Writer, link string) {
+	qrterminal.GenerateWithConfig(link, qrterminal.Config{
+		Level:      qrterminal.L,
+		Writer:     w,
+		HalfBlocks: true,
+		QuietZone:  1,
+	})
+}
+
+func max64(a, b int64) int64 {
+	if a > b {
+		return a
+	}
+	return b
+}

cli/device_test.go

@@ -0,0 +1,107 @@
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestDeviceAuth(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/iam/oauth/device" {
+			t.Fatalf("path = %s", r.URL.Path)
+		}
+		if got := r.URL.Query().Get("client_id"); got != "hanzo-app" {
+			t.Fatalf("client_id = %q", got)
+		}
+		if got := r.URL.Query().Get("response_type"); got != "device_code" {
+			t.Fatalf("response_type = %q", got)
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"device_code":               "dc-1",
+			"user_code":                 "WDJB-MJHT",
+			"verification_uri":          srv0 + "/login/oauth/device",
+			"verification_uri_complete": srv0 + "/login/oauth/device/WDJB-MJHT",
+			"expires_in":                900,
+			"interval":                  1,
+		})
+	}))
+	defer srv.Close()
+	srv0 = srv.URL
+
+	iam := newIAMClient(srv.URL, "hanzo-app")
+	da, err := iam.deviceAuth(context.Background(), "openid profile email")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if da.DeviceCode != "dc-1" || da.UserCode != "WDJB-MJHT" {
+		t.Fatalf("unexpected device auth: %+v", da)
+	}
+	if !strings.HasSuffix(da.VerificationURIComplete, "/WDJB-MJHT") {
+		t.Fatalf("verification_uri_complete = %q", da.VerificationURIComplete)
+	}
+}
+
+// srv0 lets the handler reference its own server URL in the response body.
+var srv0 string
+
+func TestPollDeviceTokenPendingThenIssued(t *testing.T) {
+	polls := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/iam/oauth/token" {
+			t.Fatalf("path = %s", r.URL.Path)
+		}
+		_ = r.ParseForm()
+		if got := r.Form.Get("grant_type"); got != deviceGrantType {
+			t.Fatalf("grant_type = %q", got)
+		}
+		if got := r.Form.Get("device_code"); got != "dc-1" {
+			t.Fatalf("device_code = %q", got)
+		}
+		polls++
+		if polls < 3 {
+			_ = json.NewEncoder(w).Encode(map[string]string{"error": "authorization_pending"})
+			return
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"access_token": "tok-1", "token_type": "Bearer", "expires_in": 3600})
+	}))
+	defer srv.Close()
+
+	iam := newIAMClient(srv.URL, "hanzo-console")
+	tr, err := iam.pollDeviceToken(context.Background(), &deviceAuthResp{DeviceCode: "dc-1", ExpiresIn: 30, Interval: 0})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if tr.AccessToken != "tok-1" || polls != 3 {
+		t.Fatalf("token = %q polls = %d", tr.AccessToken, polls)
+	}
+}
+
+func TestPollDeviceTokenExpired(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_ = json.NewEncoder(w).Encode(map[string]string{"error": "expired_token"})
+	}))
+	defer srv.Close()
+
+	iam := newIAMClient(srv.URL, "hanzo-console")
+	_, err := iam.pollDeviceToken(context.Background(), &deviceAuthResp{DeviceCode: "dc-1", ExpiresIn: 30, Interval: 0})
+	if err == nil || !strings.Contains(err.Error(), "expired") {
+		t.Fatalf("err = %v", err)
+	}
+}
+
+func TestPollDeviceTokenDenied(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_ = json.NewEncoder(w).Encode(map[string]string{"error": "access_denied", "error_description": "user refused"})
+	}))
+	defer srv.Close()
+
+	iam := newIAMClient(srv.URL, "hanzo-console")
+	_, err := iam.pollDeviceToken(context.Background(), &deviceAuthResp{DeviceCode: "dc-1", ExpiresIn: 30, Interval: 0})
+	if err == nil || !strings.Contains(err.Error(), "access_denied") {
+		t.Fatalf("err = %v", err)
+	}
+}

cli/engine.go

@@ -0,0 +1,199 @@
+package cli
+
+// engine.go — `hanzo engine install|serve|status`: manage a local hanzo-engine
+// (the `hanzoai` OpenAI + Anthropic model server) on THIS machine.
+//
+// One source of truth for install logic: `install` runs the SAME install.sh /
+// install.ps1 the `curl … | sh` one-liner uses (it downloads the prebuilt,
+// cosign-signed binary from the latest github.com/hanzoai/engine release), so the
+// CLI never re-implements platform detection or verification. `serve` launches the
+// installed binary (`hanzoai --port P run -m MODEL`); `status` probes it, reusing
+// the same /v1/models probe `hanzo gpu connect --serve-engine` advertises with.
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+const (
+	installScriptSh = "https://raw.githubusercontent.com/hanzoai/engine/main/install.sh"
+	installScriptPS = "https://raw.githubusercontent.com/hanzoai/engine/main/install.ps1"
+	engineBinName   = "hanzoai"
+)
+
+func newEngineCmd(envOf func() *Env, _ *globalFlags) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "engine",
+		Short: "Run a local hanzo-engine (OpenAI + Anthropic model server)",
+		Long: "Install, serve, and inspect a local hanzo-engine on this machine.\n" +
+			"`install` downloads the prebuilt, signed `hanzoai` binary; `serve` runs it on\n" +
+			":1234; `status` shows whether it is up and which models it serves.",
+	}
+
+	// install ----------------------------------------------------------------
+	var version, dir string
+	install := &cobra.Command{
+		Use:   "install",
+		Short: "Download + install the prebuilt hanzoai binary (runs the canonical install script)",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return runEngineInstall(cmd, version, dir)
+		},
+	}
+	install.Flags().StringVar(&version, "engine-version", "", "install a specific release tag (default: latest)")
+	install.Flags().StringVar(&dir, "dir", "", "install directory (default: /usr/local/bin or ~/.local/bin)")
+
+	// serve ------------------------------------------------------------------
+	var model string
+	var port int
+	serve := &cobra.Command{
+		Use:   "serve",
+		Short: "Serve a model with the local hanzoai binary (hanzoai --port P run -m MODEL)",
+		Long: "Launch the installed hanzoai server. Any args after `--` are passed through to\n" +
+			"the underlying `hanzoai … run` invocation (e.g. `-- --max-seqs 32`).",
+		Args: cobra.ArbitraryArgs,
+		RunE: func(cmd *cobra.Command, extra []string) error {
+			return runEngineServe(cmd, model, port, extra)
+		},
+	}
+	serve.Flags().StringVarP(&model, "model", "m", "Qwen/Qwen3-4B", "model to serve (HF repo id or local path)")
+	serve.Flags().IntVarP(&port, "port", "p", 1234, "port to serve the OpenAI + Anthropic API on")
+
+	// status -----------------------------------------------------------------
+	var url string
+	status := &cobra.Command{
+		Use:   "status",
+		Short: "Show whether a local hanzo-engine is up and what it serves",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return runEngineStatus(cmd, envOf(), firstNonEmpty(url, defaultEngineURL))
+		},
+	}
+	status.Flags().StringVar(&url, "url", defaultEngineURL, "local engine URL to probe (GET /v1/models)")
+
+	cmd.AddCommand(install, serve, status)
+	return cmd
+}
+
+// runEngineInstall shells out to the canonical install script so there is exactly
+// one implementation of platform detection + signature verification.
+func runEngineInstall(cmd *cobra.Command, version, dir string) error {
+	env := os.Environ()
+	if version != "" {
+		env = append(env, "HANZOAI_VERSION="+version)
+	}
+	if dir != "" {
+		env = append(env, "HANZOAI_INSTALL_DIR="+dir)
+	}
+
+	var sh *exec.Cmd
+	if runtime.GOOS == "windows" {
+		sh = exec.CommandContext(cmd.Context(), "powershell", "-NoProfile", "-Command",
+			"irm "+installScriptPS+" | iex")
+	} else {
+		// curl … | sh — the exact one-liner documented in the README.
+		sh = exec.CommandContext(cmd.Context(), "sh", "-c",
+			"curl -fsSL "+installScriptSh+" | sh")
+	}
+	sh.Env = env
+	sh.Stdin, sh.Stdout, sh.Stderr = os.Stdin, cmd.OutOrStdout(), cmd.ErrOrStderr()
+	if err := sh.Run(); err != nil {
+		return fmt.Errorf("install script failed: %w", err)
+	}
+	return nil
+}
+
+// runEngineServe execs the installed hanzoai binary. On Unix it replaces this
+// process (syscall.Exec) so signals + exit code flow straight through; on Windows
+// it runs as a child with inherited stdio.
+func runEngineServe(cmd *cobra.Command, model string, port int, extra []string) error {
+	bin, err := findEngineBinary()
+	if err != nil {
+		return err
+	}
+	args := []string{bin, "--port", fmt.Sprintf("%d", port), "run", "-m", model}
+	args = append(args, extra...)
+	fmt.Fprintf(cmd.ErrOrStderr(), "→ %s\n", exec.Command(bin, args[1:]...).String())
+	return execEngine(bin, args)
+}
+
+// runEngineStatus probes the local engine and prints (or JSON-emits) its state,
+// reusing the same /v1/models probe the fleet advertisement uses.
+func runEngineStatus(cmd *cobra.Command, env *Env, url string) error {
+	ctx, cancel := context.WithTimeout(cmd.Context(), 6*time.Second)
+	defer cancel()
+
+	adv := &engineAdvertisement{URL: url, APIs: []string{"openai", "anthropic"}}
+	if models, perr := probeEngine(ctx, url); perr != nil {
+		adv.Status = "unreachable"
+	} else {
+		adv.Status = "ready"
+		adv.Models = models
+	}
+	bin, _ := findEngineBinary()
+
+	return env.emit(map[string]any{"url": url, "status": adv.Status, "models": adv.Models, "binary": bin},
+		func(out io.Writer) {
+			fmt.Fprintf(out, "engine   %s — %s\n", adv.URL, describeEngine(adv))
+			if len(adv.Models) > 0 {
+				for _, m := range adv.Models {
+					fmt.Fprintf(out, "  model  %s\n", m)
+				}
+			}
+			if bin != "" {
+				fmt.Fprintf(out, "binary   %s\n", bin)
+			} else {
+				fmt.Fprintln(out, "binary   not installed — run `hanzo engine install`")
+			}
+			if adv.Status != "ready" {
+				fmt.Fprintf(out, "hint     start it with `hanzo engine serve -m Qwen/Qwen3-4B --port %s`\n",
+					portOf(url))
+			}
+		})
+}
+
+// findEngineBinary locates the installed hanzoai binary: PATH first, then the
+// directories install.sh / install.ps1 write to.
+func findEngineBinary() (string, error) {
+	name := engineBinName
+	if runtime.GOOS == "windows" {
+		name += ".exe"
+	}
+	if p, err := exec.LookPath(name); err == nil {
+		return p, nil
+	}
+	home, _ := os.UserHomeDir()
+	var dirs []string
+	if runtime.GOOS == "windows" {
+		if la := os.Getenv("LOCALAPPDATA"); la != "" {
+			dirs = append(dirs, filepath.Join(la, "Hanzo", "bin"))
+		}
+	} else {
+		dirs = append(dirs, "/usr/local/bin", filepath.Join(home, ".local", "bin"), filepath.Join(home, ".hanzo", "bin"))
+	}
+	for _, d := range dirs {
+		p := filepath.Join(d, name)
+		if fi, err := os.Stat(p); err == nil && !fi.IsDir() {
+			return p, nil
+		}
+	}
+	return "", fmt.Errorf("hanzoai not found on PATH or in the default install dirs — run `hanzo engine install`")
+}
+
+func portOf(url string) string {
+	// best-effort: pull the ":<port>" tail for the hint
+	for i := len(url) - 1; i >= 0; i-- {
+		if url[i] == ':' {
+			return url[i+1:]
+		}
+	}
+	return "1234"
+}

cli/engine_exec_unix.go

@@ -0,0 +1,14 @@
+//go:build !windows
+
+package cli
+
+import (
+	"os"
+	"syscall"
+)
+
+// execEngine replaces the current process with hanzoai so signals (Ctrl-C) and
+// the exit code flow straight through — `hanzo engine serve` becomes hanzoai.
+func execEngine(bin string, args []string) error {
+	return syscall.Exec(bin, args, os.Environ())
+}

cli/engine_exec_windows.go

@@ -0,0 +1,16 @@
+//go:build windows
+
+package cli
+
+import (
+	"os"
+	"os/exec"
+)
+
+// execEngine runs hanzoai as a child with inherited stdio (Windows has no exec()).
+// The child shares the console, so Ctrl-C reaches it; we return its exit error.
+func execEngine(bin string, args []string) error {
+	c := exec.Command(bin, args[1:]...)
+	c.Stdin, c.Stdout, c.Stderr = os.Stdin, os.Stdout, os.Stderr
+	return c.Run()
+}

cli/engine_test.go

@@ -0,0 +1,96 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+// TestEngineCmdWiring asserts `hanzo engine` exposes install/serve/status with the
+// documented flags — the contract install.sh and the docs promise.
+func TestEngineCmdWiring(t *testing.T) {
+	env := &Env{Output: "table"}
+	cmd := newEngineCmd(func() *Env { return env }, &globalFlags{})
+
+	want := map[string]bool{"install": false, "serve": false, "status": false}
+	for _, sub := range cmd.Commands() {
+		if _, ok := want[sub.Name()]; ok {
+			want[sub.Name()] = true
+		}
+	}
+	for name, found := range want {
+		if !found {
+			t.Fatalf("engine subcommand %q missing", name)
+		}
+	}
+
+	serve, _, _ := cmd.Find([]string{"serve"})
+	if serve.Flags().Lookup("model") == nil || serve.Flags().Lookup("port") == nil {
+		t.Fatalf("serve must have --model and --port")
+	}
+	status, _, _ := cmd.Find([]string{"status"})
+	if status.Flags().Lookup("url") == nil {
+		t.Fatalf("status must have --url")
+	}
+}
+
+// TestEngineStatusReady probes a stub engine and reports it ready with its models.
+func TestEngineStatusReady(t *testing.T) {
+	engine := stubEngine(t, "default", "zen-omni-30b")
+	defer engine.Close()
+
+	var buf bytes.Buffer
+	env := &Env{Output: "table", out: &buf}
+	cmd := &cobra.Command{}
+	cmd.SetContext(context.Background())
+
+	if err := runEngineStatus(cmd, env, engine.URL); err != nil {
+		t.Fatalf("status: %v", err)
+	}
+	out := buf.String()
+	if !strings.Contains(out, "ready") || !strings.Contains(out, "zen-omni-30b") {
+		t.Fatalf("status output missing ready/model:\n%s", out)
+	}
+}
+
+// TestEngineStatusUnreachable reports a down engine as unreachable (not an error).
+func TestEngineStatusUnreachable(t *testing.T) {
+	var buf bytes.Buffer
+	env := &Env{Output: "table", out: &buf}
+	cmd := &cobra.Command{}
+	cmd.SetContext(context.Background())
+
+	// A port with nothing listening.
+	if err := runEngineStatus(cmd, env, "http://127.0.0.1:1"); err != nil {
+		t.Fatalf("status should not error on a down engine: %v", err)
+	}
+	if !strings.Contains(buf.String(), "unreachable") {
+		t.Fatalf("expected 'unreachable', got:\n%s", buf.String())
+	}
+}
+
+// TestFindEngineBinary finds hanzoai on PATH.
+func TestFindEngineBinary(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("PATH exe probe differs on Windows")
+	}
+	dir := t.TempDir()
+	bin := filepath.Join(dir, engineBinName)
+	if err := os.WriteFile(bin, []byte("#!/bin/sh\n"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", dir)
+	got, err := findEngineBinary()
+	if err != nil {
+		t.Fatalf("findEngineBinary: %v", err)
+	}
+	if got != bin {
+		t.Fatalf("found %q, want %q", got, bin)
+	}
+}

cli/gpu_engine_test.go

@@ -0,0 +1,247 @@
+package cli
+
+// gpu_engine_test.go — the `--serve-engine` capability: probing a local hanzo-engine
+// and assembling the fleet advertisement + provider registration. Uses an httptest
+// stub for the engine so no model (or GPU) is needed.
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+// stubEngine stands in for hanzo-engine's OpenAI-shaped GET /v1/models.
+func stubEngine(t *testing.T, models ...string) *httptest.Server {
+	t.Helper()
+	mux := http.NewServeMux()
+	mux.HandleFunc("/v1/models", func(w http.ResponseWriter, _ *http.Request) {
+		data := make([]map[string]any, 0, len(models))
+		for _, m := range models {
+			data = append(data, map[string]any{"id": m, "object": "model", "owned_by": "local"})
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"object": "list", "data": data})
+	})
+	return httptest.NewServer(mux)
+}
+
+func TestProbeEngine(t *testing.T) {
+	srv := stubEngine(t, "default", "zen-omni-30b")
+	defer srv.Close()
+
+	got, err := probeEngine(context.Background(), srv.URL)
+	if err != nil {
+		t.Fatalf("probeEngine: %v", err)
+	}
+	if len(got) != 2 || got[0] != "default" || got[1] != "zen-omni-30b" {
+		t.Fatalf("models = %v, want [default zen-omni-30b]", got)
+	}
+}
+
+func TestProbeEngineDown(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		http.Error(w, "loading", http.StatusServiceUnavailable)
+	}))
+	defer srv.Close()
+
+	if _, err := probeEngine(context.Background(), srv.URL); err == nil {
+		t.Fatal("probeEngine: want error for a 503 engine, got nil")
+	}
+}
+
+func TestRefreshEngineAdvertises(t *testing.T) {
+	srv := stubEngine(t, "default")
+	defer srv.Close()
+
+	w := &worker{
+		identity:     "gb10",
+		hostname:     "gb10",
+		jobsNS:       "gpu-jobs",
+		serveEngine:  true,
+		engineURL:    srv.URL,
+		engineAdvURL: "http://node.example:1234",
+	}
+
+	if changed := w.refreshEngine(context.Background()); !changed {
+		t.Fatal("first refreshEngine should report a change (nil -> ready)")
+	}
+	if w.engine == nil || w.engine.Status != "ready" {
+		t.Fatalf("engine = %+v, want status ready", w.engine)
+	}
+	if w.engine.URL != "http://node.example:1234" {
+		t.Fatalf("advertised URL = %q, want the endpoint, not the local probe URL", w.engine.URL)
+	}
+	if !contains(w.engine.APIs, "openai") || !contains(w.engine.APIs, "anthropic") {
+		t.Fatalf("APIs = %v, want both openai and anthropic (hanzo-engine serves both)", w.engine.APIs)
+	}
+	if len(w.engine.Models) != 1 || w.engine.Models[0] != "default" {
+		t.Fatalf("models = %v, want [default]", w.engine.Models)
+	}
+	// A second probe with an unchanged engine is a no-op (no needless re-register).
+	if changed := w.refreshEngine(context.Background()); changed {
+		t.Fatal("second refreshEngine with an unchanged engine should report no change")
+	}
+}
+
+func TestRefreshEngineUnreachable(t *testing.T) {
+	w := &worker{
+		identity:     "gb10",
+		serveEngine:  true,
+		engineURL:    "http://127.0.0.1:0", // nothing listening
+		engineAdvURL: "http://127.0.0.1:0",
+	}
+	w.refreshEngine(context.Background())
+	if w.engine == nil || w.engine.Status != "unreachable" {
+		t.Fatalf("engine = %+v, want status unreachable", w.engine)
+	}
+}
+
+func TestBuildRegistrationCarriesEngine(t *testing.T) {
+	srv := stubEngine(t, "default")
+	defer srv.Close()
+
+	w := &worker{
+		identity:     "gb10",
+		hostname:     "gb10",
+		jobsNS:       "gpu-jobs",
+		gpus:         []gpuInfo{{Name: "NVIDIA GB10", MemoryTotal: "122880 MiB"}},
+		serveEngine:  true,
+		engineURL:    srv.URL,
+		engineAdvURL: "http://node.example:1234",
+	}
+	w.refreshEngine(context.Background())
+
+	reg := w.buildRegistration()
+	if !contains(reg.Capabilities, studioCap) || !contains(reg.Capabilities, engineCap) {
+		t.Fatalf("capabilities = %v, want both %q and %q", reg.Capabilities, studioCap, engineCap)
+	}
+	if reg.Engine == nil || reg.Engine.URL != "http://node.example:1234" {
+		t.Fatalf("registration engine = %+v, want the advertised endpoint", reg.Engine)
+	}
+
+	// The presence record's Input must carry the endpoint so GET /v1/fleet/workers
+	// (which decodes this exact JSON) can advertise it.
+	raw, err := json.Marshal(reg)
+	if err != nil {
+		t.Fatalf("marshal registration: %v", err)
+	}
+	for _, want := range []string{`"engine.serve"`, `"http://node.example:1234"`, `"openai"`, `"anthropic"`} {
+		if !strings.Contains(string(raw), want) {
+			t.Fatalf("registration JSON missing %s:\n%s", want, raw)
+		}
+	}
+}
+
+func TestCapabilitiesWithoutEngine(t *testing.T) {
+	w := &worker{serveEngine: false}
+	caps := w.capabilities()
+	if len(caps) != 1 || caps[0] != studioCap {
+		t.Fatalf("capabilities = %v, want just [%q] when not serving an engine", caps, studioCap)
+	}
+}
+
+func TestProviderBodyIsOpenAICompatible(t *testing.T) {
+	w := &worker{
+		identity: "gb10",
+		engine:   &engineAdvertisement{URL: "http://node.example:1234", Status: "ready", Models: []string{"zen-omni-30b"}},
+	}
+	body := w.providerBody()
+	if body["type"] != "Local" {
+		t.Fatalf("type = %v, want Local (OpenAI-compatible; gateway auto-appends /v1)", body["type"])
+	}
+	if body["providerUrl"] != "http://node.example:1234" {
+		t.Fatalf("providerUrl = %v", body["providerUrl"])
+	}
+	if body["name"] != "gpu-gb10" {
+		t.Fatalf("name = %v, want gpu-gb10", body["name"])
+	}
+	if body["subType"] != "zen-omni-30b" {
+		t.Fatalf("subType = %v, want the served model", body["subType"])
+	}
+}
+
+// TestConnectServeEngineRoundTrip closes the loop end-to-end on this box, no model
+// and no production: a stub hanzo-engine (GET /v1/models) + a stub cloud that stores
+// the presence Input and serves it back on GET /v1/fleet/workers. It exercises the
+// real chain — probe → build registration → POST the fleet activity → GET
+// /v1/fleet/workers → the engine endpoint is advertised.
+func TestConnectServeEngineRoundTrip(t *testing.T) {
+	engine := stubEngine(t, "default", "zen-omni-30b")
+	defer engine.Close()
+
+	var storedInput registration // what the CLI POSTed as the presence record's Input
+	cloud := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.Method == http.MethodPost && strings.HasSuffix(r.URL.Path, "/fleet/activities"):
+			var body struct {
+				Input registration `json:"input"`
+			}
+			_ = json.NewDecoder(r.Body).Decode(&body)
+			storedInput = body.Input
+			w.WriteHeader(http.StatusOK)
+		case r.Method == http.MethodGet && r.URL.Path == "/v1/fleet/workers":
+			// Fold the stored registration into the fleet worker shape, exactly as
+			// clients/visor/fleet.go byoWorkers does.
+			_ = json.NewEncoder(w).Encode(map[string]any{"workers": []fleetWorker{{
+				ID: "gb10", Hostname: storedInput.Hostname, Provider: "byo", Status: "online",
+				GPUs: storedInput.GPUs, Capabilities: storedInput.Capabilities, Engine: storedInput.Engine,
+			}}})
+		default: // namespace ensure + anything else
+			w.WriteHeader(http.StatusOK)
+		}
+	}))
+	defer cloud.Close()
+
+	t.Setenv("HANZO_TOKEN", "test-token") // ensureToken honors this; no `hanzo login` needed
+
+	w := &worker{
+		env:          &Env{CloudURL: cloud.URL},
+		http:         &http.Client{Timeout: 5 * time.Second},
+		baseURL:      cloud.URL,
+		identity:     "gb10",
+		hostname:     "gb10",
+		jobsNS:       "gpu-jobs",
+		gpus:         []gpuInfo{{Name: "NVIDIA GB10", MemoryTotal: "122880 MiB"}},
+		handlers:     map[string]jobHandler{},
+		serveEngine:  true,
+		engineURL:    engine.URL,
+		engineAdvURL: "http://node.example:1234",
+	}
+	ctx := context.Background()
+	w.refreshEngine(ctx)
+	if err := w.register(ctx); err != nil {
+		t.Fatalf("register: %v", err)
+	}
+
+	var resp struct {
+		Workers []fleetWorker `json:"workers"`
+	}
+	if _, err := w.call(ctx, http.MethodGet, "/v1/fleet/workers", nil, &resp); err != nil {
+		t.Fatalf("GET /v1/fleet/workers: %v", err)
+	}
+	if len(resp.Workers) != 1 {
+		t.Fatalf("workers = %d, want 1", len(resp.Workers))
+	}
+	fw := resp.Workers[0]
+	if !contains(fw.Capabilities, engineCap) {
+		t.Fatalf("fleet worker capabilities = %v, want engine.serve", fw.Capabilities)
+	}
+	if fw.Engine == nil || fw.Engine.URL != "http://node.example:1234" || fw.Engine.Status != "ready" {
+		t.Fatalf("fleet worker engine = %+v, want the advertised ready endpoint", fw.Engine)
+	}
+	if len(fw.Engine.Models) != 2 {
+		t.Fatalf("fleet worker engine models = %v, want 2", fw.Engine.Models)
+	}
+}
+
+func contains(xs []string, v string) bool {
+	for _, x := range xs {
+		if x == v {
+			return true
+		}
+	}
+	return false
+}

cli/gpu_mirror_test.go

@@ -0,0 +1,92 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+// TestMirrorRenders verifies the render mirror: it scans the local studio output
+// tree and POSTs every image (new or changed) to /v1/library/upload with the node's
+// identity + subfolder + bearer, skips unchanged files across scans, and re-uploads
+// a changed file. This is the path that lands EVERY render in studio.hanzo.ai even
+// when it was produced outside the job/claim path.
+func TestMirrorRenders(t *testing.T) {
+	t.Setenv("HANZO_TOKEN", "test-bearer")
+
+	dir := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(dir, "renders"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	write := func(rel, body string) {
+		if err := os.WriteFile(filepath.Join(dir, filepath.FromSlash(rel)), []byte(body), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	write("renders/a.png", "\x89PNG-a")
+	write("top.jpg", "jpg-top")
+	write("notes.txt", "not an image")
+
+	type up struct{ name, node, subpath, auth string }
+	var got []up
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/library/upload" {
+			http.Error(w, "not found", http.StatusNotFound)
+			return
+		}
+		_ = r.ParseMultipartForm(1 << 20)
+		name := ""
+		if r.MultipartForm != nil {
+			for _, fh := range r.MultipartForm.File["image"] {
+				name = fh.Filename
+			}
+		}
+		got = append(got, up{
+			name:    name,
+			node:    r.URL.Query().Get("node"),
+			subpath: r.URL.Query().Get("subpath"),
+			auth:    r.Header.Get("Authorization"),
+		})
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"ok":true,"path":"x"}`))
+	}))
+	defer srv.Close()
+
+	w := &worker{env: &Env{}, http: &http.Client{Timeout: 10 * time.Second}, identity: "spark"}
+	seen := map[string]int64{}
+	var buf bytes.Buffer
+
+	w.mirrorRenders(context.Background(), &buf, dir, srv.URL, seen)
+	if len(got) != 2 {
+		t.Fatalf("uploaded %d files, want 2 images (the .txt is skipped): %+v", len(got), got)
+	}
+	var a *up
+	for i := range got {
+		if got[i].name == "a.png" {
+			a = &got[i]
+		}
+	}
+	if a == nil || a.subpath != "renders" || a.node != "spark" || a.auth != "Bearer test-bearer" {
+		t.Fatalf("renders/a.png upload = %+v, want subpath=renders node=spark bearer set", a)
+	}
+
+	// A second scan re-uploads nothing (seen matches every size).
+	got = nil
+	w.mirrorRenders(context.Background(), &buf, dir, srv.URL, seen)
+	if len(got) != 0 {
+		t.Fatalf("second scan uploaded %d files, want 0 (all unchanged): %+v", len(got), got)
+	}
+
+	// A changed file is re-uploaded on the next scan.
+	write("renders/a.png", "\x89PNG-a-grew")
+	got = nil
+	w.mirrorRenders(context.Background(), &buf, dir, srv.URL, seen)
+	if len(got) != 1 || got[0].name != "a.png" {
+		t.Fatalf("after change, uploaded %+v, want just renders/a.png", got)
+	}
+}

cli/gpu_policy_test.go

@@ -0,0 +1,109 @@
+package cli
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestSharePolicyReject(t *testing.T) {
+	studioInput := json.RawMessage(`{"prompt":{},"org":"karma","project":"swimwear"}`)
+	engineInput := json.RawMessage(`{"model":"Qwen/Qwen3-4B","org":"hanzo"}`)
+
+	cases := []struct {
+		name    string
+		policy  *SharePolicy
+		jobType string
+		input   json.RawMessage
+		allow   bool // true == reject() returns ""
+	}{
+		{"nil policy is permissive", nil, "studio.render", studioInput, true},
+		{"empty policy is permissive", &SharePolicy{}, "studio.render", studioInput, true},
+		{
+			"job type allowed",
+			&SharePolicy{AllowedJobTypes: []string{"studio.render"}},
+			"studio.render", studioInput, true,
+		},
+		{
+			"job type not allowed",
+			&SharePolicy{AllowedJobTypes: []string{"engine.serve"}},
+			"studio.render", studioInput, false,
+		},
+		{
+			"org allowed",
+			&SharePolicy{AllowedOrgs: []string{"karma", "hanzo"}},
+			"studio.render", studioInput, true,
+		},
+		{
+			"org not allowed",
+			&SharePolicy{AllowedOrgs: []string{"hanzo"}},
+			"studio.render", studioInput, false,
+		},
+		{
+			"project not allowed",
+			&SharePolicy{AllowedProjects: []string{"lifestyle"}},
+			"studio.render", studioInput, false,
+		},
+		{
+			"model allowed",
+			&SharePolicy{AllowedModels: []string{"Qwen/Qwen3-4B"}},
+			"engine.serve", engineInput, true,
+		},
+		{
+			"model not allowed",
+			&SharePolicy{AllowedModels: []string{"meta/llama-3"}},
+			"engine.serve", engineInput, false,
+		},
+		{
+			"absent field skips its gate (input has no project)",
+			&SharePolicy{AllowedProjects: []string{"lifestyle"}},
+			"engine.serve", engineInput, true,
+		},
+		{
+			"combined: all gates pass",
+			&SharePolicy{
+				AllowedJobTypes: []string{"studio.render"},
+				AllowedOrgs:     []string{"karma"},
+				AllowedProjects: []string{"swimwear"},
+			},
+			"studio.render", studioInput, true,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			reason := tc.policy.reject(tc.jobType, tc.input)
+			if got := reason == ""; got != tc.allow {
+				t.Fatalf("reject()=%q; want allow=%v", reason, tc.allow)
+			}
+		})
+	}
+}
+
+func TestLoadSharePolicyInline(t *testing.T) {
+	t.Setenv("HANZO_GPU_POLICY", `{"allowedJobTypes":["studio.render"],"allowedOrgs":["karma"],"maxConcurrent":2}`)
+	p, err := loadSharePolicy()
+	if err != nil {
+		t.Fatalf("loadSharePolicy: %v", err)
+	}
+	if p == nil {
+		t.Fatal("expected a policy, got nil")
+	}
+	if len(p.AllowedJobTypes) != 1 || p.AllowedJobTypes[0] != "studio.render" {
+		t.Fatalf("AllowedJobTypes=%v", p.AllowedJobTypes)
+	}
+	if p.MaxConcurrent != 2 {
+		t.Fatalf("MaxConcurrent=%d", p.MaxConcurrent)
+	}
+	if p.reject("engine.serve", json.RawMessage(`{}`)) == "" {
+		t.Fatal("expected engine.serve to be rejected by studio.render-only policy")
+	}
+}
+
+func TestLoadSharePolicyUnset(t *testing.T) {
+	t.Setenv("HANZO_GPU_POLICY", "")
+	t.Setenv("HANZO_GPU_POLICY_FILE", "")
+	p, err := loadSharePolicy()
+	if err != nil || p != nil {
+		t.Fatalf("unset policy: got (%v, %v), want (nil, nil)", p, err)
+	}
+}

cli/gpu_upload_test.go

@@ -0,0 +1,55 @@
+package cli
+
+import (
+	"context"
+	"net/http"
+	"os"
+	"testing"
+	"time"
+)
+
+// TestUploadOutputsIntegration exercises the real BYO-GPU result-upload path:
+// fetchLocalOutput pulls a finished render from the LOCAL studio's /view and
+// postGalleryOutput POSTs it to the org studio's /upload/output with the user's
+// IAM token, landing it in orgs/{org}/output (the gallery, S3-mirrored).
+//
+// It is a live integration test, skipped unless the box is wired for it:
+//
+//	HANZO_TOKEN=<iam bearer> \
+//	HANZO_UPLOAD_IT_FILE=<name of a file the local studio serves at /view?type=output> \
+//	HANZO_STUDIO_UPLOAD_URL=<org studio base, e.g. https://studio.hanzo.ai> \
+//	go test ./cli -run TestUploadOutputsIntegration -v
+//
+// The local studio is assumed at localComfyUI (127.0.0.1:8188).
+func TestUploadOutputsIntegration(t *testing.T) {
+	tok := os.Getenv("HANZO_TOKEN")
+	file := os.Getenv("HANZO_UPLOAD_IT_FILE")
+	if tok == "" || file == "" {
+		t.Skip("set HANZO_TOKEN and HANZO_UPLOAD_IT_FILE to run the live upload integration test")
+	}
+	uploadURL := firstNonEmpty(os.Getenv("HANZO_STUDIO_UPLOAD_URL"), defaultStudioUploadURL)
+
+	w := &worker{
+		env:             &Env{}, // ensureToken reads HANZO_TOKEN first, so no creds needed
+		http:            &http.Client{Timeout: 60 * time.Second},
+		studioUploadURL: uploadURL,
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
+	defer cancel()
+
+	subfolder := os.Getenv("HANZO_UPLOAD_IT_SUBFOLDER") // "" == top of output
+	out := file
+	if subfolder != "" {
+		out = subfolder + "/" + file
+	}
+
+	gallery, err := w.uploadOutputs(ctx, []string{out}, uploadURL, "karma")
+	if err != nil {
+		t.Fatalf("uploadOutputs(%q -> %s): %v", out, uploadURL, err)
+	}
+	if len(gallery) != 1 {
+		t.Fatalf("expected 1 gallery path, got %d: %v", len(gallery), gallery)
+	}
+	t.Logf("uploaded %q -> %s gallery path %q", out, uploadURL, gallery[0])
+}

cli/platform.go

@@ -310,7 +310,7 @@ func (p *Platform) Redeploy(ctx context.Context, org, project, env, container st
 }
 
 // ---------------------------------------------------------------------------
-// Build — POST /v1/arcd/enqueue (platform-native CI, no GitHub builders).
+// Build — POST /v1/runner (platform-native CI, no GitHub builders).
 // ---------------------------------------------------------------------------
 
 // BuildReq is the direct-enqueue body. Repo/SHA/Image are required.
@@ -344,5 +344,5 @@ func (p *Platform) EnqueueBuild(ctx context.Context, req BuildReq, buildToken st
 		return nil, fmt.Errorf("no build token: set HANZO_BUILD_TOKEN / PLATFORM_BUILD_CALLBACK_TOKEN or `hanzo login --build-token <tok>`")
 	}
 	out := &BuildJob{}
-	return out, p.do(ctx, http.MethodPost, "/v1/arcd/enqueue", buildToken, req, out)
+	return out, p.do(ctx, http.MethodPost, "/v1/runner", buildToken, req, out)
 }

cli/platform_test.go

@@ -177,7 +177,7 @@ func TestPlatformEnqueueBuild(t *testing.T) {
 		if got := r.Header.Get("Authorization"); got != "Bearer build-tok" {
 			t.Errorf("build auth header = %q (must use build token)", got)
 		}
-		if r.URL.Path != "/v1/arcd/enqueue" {
+		if r.URL.Path != "/v1/runner" {
 			t.Errorf("path = %s", r.URL.Path)
 		}
 		body, _ := io.ReadAll(r.Body)

cli/run.go

@@ -0,0 +1,185 @@
+package cli
+
+// run.go — `hanzo run`: launch a workload on Hanzo compute through one verb.
+//
+// A "run" is a workload value = {artifact, shape}, dispatched by kind onto the
+// one API host (api.hanzo.ai/v1) and the one binary (cloud):
+//
+//	hanzo run <image>              → POST /v1/run   container service (autoscaled)
+//	hanzo run fn <src>             → POST /v1/fn    source function   (scale-to-zero)
+//
+// `run` launches YOUR artifact (container/source/site) on Hanzo compute. Invoking
+// a managed agent with a task is a peer verb, `hanzo agent` (see agent.go), not a
+// run kind. It is a THIN client: kind-dispatch + one authenticated HTTP call each,
+// over the IAM access token and env.CloudURL, exactly like the fleet worker
+// (gpu.go) — it invents no parallel API. See docs/architecture/compute-ladder.md.
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+// cloudCall performs one authenticated JSON request against env.CloudURL
+// (api.hanzo.ai), decoding a 2xx body into out. It is the api.hanzo.ai analog of
+// Platform.do (which targets platform.hanzo.ai); the two converge as the platform
+// control plane folds into cloud. Mirrors the fleet worker's call idiom.
+func cloudCall(ctx context.Context, env *Env, method, path string, body, out any) error {
+	tok, err := env.ensureToken(ctx)
+	if err != nil {
+		return err
+	}
+	var rdr io.Reader
+	if body != nil {
+		b, err := json.Marshal(body)
+		if err != nil {
+			return err
+		}
+		rdr = bytes.NewReader(b)
+	}
+	req, err := http.NewRequestWithContext(ctx, method, env.CloudURL+path, rdr)
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Authorization", "Bearer "+tok)
+	req.Header.Set("Accept", "application/json")
+	req.Header.Set("User-Agent", "hanzo-cli/"+Version)
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	resp, err := (&http.Client{}).Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	raw, _ := io.ReadAll(io.LimitReader(resp.Body, 8<<20))
+	if resp.StatusCode/100 != 2 {
+		return fmt.Errorf("cloud %s %s: HTTP %d: %s", method, path, resp.StatusCode, serverMessage(raw))
+	}
+	if out != nil && len(raw) > 0 {
+		if err := json.Unmarshal(raw, out); err != nil {
+			return fmt.Errorf("cloud %s: decode response: %w", path, err)
+		}
+	}
+	return nil
+}
+
+// RunSpec is the POST /v1/run (container) / /v1/fn (source) body. Shape selects
+// the execution model: "service" (autoscaled, long-lived), "function"
+// (per-request, scale-to-zero), or "task" (run-to-completion).
+type RunSpec struct {
+	Name    string            `json:"name,omitempty"`
+	Image   string            `json:"image,omitempty"`  // container artifact (run)
+	Source  string            `json:"source,omitempty"` // source ref/path (fn)
+	Runtime string            `json:"runtime,omitempty"`
+	Port    int               `json:"port,omitempty"`
+	Shape   string            `json:"shape"` // service | function | task
+	Min     int               `json:"minScale"`
+	Max     int               `json:"maxScale"`
+	GPU     bool              `json:"gpu,omitempty"`
+	Env     map[string]string `json:"env,omitempty"`
+}
+
+// RunResult is the enqueue/creation acceptance.
+type RunResult struct {
+	ID     string `json:"id"`
+	Name   string `json:"name"`
+	URL    string `json:"url"`
+	Status string `json:"status"`
+	Shape  string `json:"shape"`
+}
+
+func newRunCmd(envOf func() *Env, _ *globalFlags) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "run",
+		Short: "Launch a workload on Hanzo compute (container, function, or agent task)",
+		Long: "One verb, dispatched by kind, all on api.hanzo.ai/v1 — k8s is abstracted away:\n" +
+			"  hanzo run <image>    a container service (autoscaled)\n" +
+			"  hanzo run fn <src>   a source function (scale-to-zero)\n" +
+			"To invoke a managed agent use `hanzo agent`; a computer-using one, `hanzo bot`.\n" +
+			"For a declared, long-running or stateful service use `hanzo deploy`; for raw\n" +
+			"cluster access use `hanzo k8s`.",
+	}
+	cmd.AddCommand(newRunContainerCmd(envOf), newRunFnCmd(envOf))
+	return cmd
+}
+
+// newRunContainerCmd is `hanzo run <image>` (default) AND `hanzo run container <image>`.
+func newRunContainerCmd(envOf func() *Env) *cobra.Command {
+	var spec RunSpec
+	var envKV []string
+	c := &cobra.Command{
+		Use:   "container <image>",
+		Short: "Run a container as an autoscaled service (POST /v1/run)",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			env := envOf()
+			spec.Image = args[0]
+			spec.Shape = firstNonEmpty(spec.Shape, "service")
+			spec.Env = parseEnvKV(envKV)
+			out := &RunResult{}
+			if err := cloudCall(cmd.Context(), env, http.MethodPost, "/v1/run", &spec, out); err != nil {
+				return err
+			}
+			return env.emit(out, func(w io.Writer) {
+				fmt.Fprintf(w, "%s\t%s\t%s\n", out.Name, out.Status, out.URL)
+			})
+		},
+	}
+	c.Flags().StringVar(&spec.Name, "name", "", "workload name (default: derived from image)")
+	c.Flags().IntVar(&spec.Port, "port", 8080, "container port to route traffic to")
+	c.Flags().StringVar(&spec.Shape, "shape", "service", "service | task (run-to-completion)")
+	c.Flags().IntVar(&spec.Min, "min", 0, "min replicas (0 = scale-to-zero when supported)")
+	c.Flags().IntVar(&spec.Max, "max", 20, "max replicas (autoscale ceiling)")
+	c.Flags().BoolVar(&spec.GPU, "gpu", false, "schedule on a GPU node")
+	c.Flags().StringArrayVarP(&envKV, "env", "e", nil, "environment variable KEY=VALUE (repeatable)")
+	return c
+}
+
+func newRunFnCmd(envOf func() *Env) *cobra.Command {
+	var spec RunSpec
+	var envKV []string
+	c := &cobra.Command{
+		Use:   "fn <source>",
+		Short: "Run a source function, scale-to-zero (POST /v1/functions)",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			env := envOf()
+			spec.Source = args[0]
+			spec.Shape = "function"
+			spec.Env = parseEnvKV(envKV)
+			out := &RunResult{}
+			if err := cloudCall(cmd.Context(), env, http.MethodPost, "/v1/functions", &spec, out); err != nil {
+				return err
+			}
+			return env.emit(out, func(w io.Writer) {
+				fmt.Fprintf(w, "%s\t%s\t%s\n", out.Name, out.Status, out.URL)
+			})
+		},
+	}
+	c.Flags().StringVar(&spec.Name, "name", "", "function name")
+	c.Flags().StringVar(&spec.Runtime, "runtime", "", "runtime env (e.g. python312, node20, rust)")
+	c.Flags().BoolVar(&spec.GPU, "gpu", false, "use a GPU function environment")
+	c.Flags().StringArrayVarP(&envKV, "env", "e", nil, "environment variable KEY=VALUE (repeatable)")
+	return c
+}
+
+// parseEnvKV turns []{"K=V"} into a map, ignoring malformed entries.
+func parseEnvKV(kv []string) map[string]string {
+	if len(kv) == 0 {
+		return nil
+	}
+	m := make(map[string]string, len(kv))
+	for _, e := range kv {
+		if i := strings.IndexByte(e, '='); i > 0 {
+			m[e[:i]] = e[i+1:]
+		}
+	}
+	return m
+}

cli/runner.go

@@ -0,0 +1,43 @@
+package cli
+
+// runner.go — `hanzo runner`: turn THIS machine into a JIT CI runner for your
+// org's GitHub Actions. The host role of the arc daemon, migrated from
+// arc-runner/arc (cmd/arcd) into cloud/runner: a GitHub App polls each configured
+// org for queued workflow jobs and spawns ephemeral, auto-exiting actions-runner
+// subprocesses tagged with this box's labels (GPU / vulkan aware). Outbound only —
+// nothing listens for inbound. Completes the trifecta: `engine` serves models,
+// `gpu connect` shares compute, `runner` claims CI — one binary, one org login.
+
+import (
+	"os/signal"
+	"syscall"
+
+	"github.com/hanzoai/cloud/runner"
+	"github.com/spf13/cobra"
+)
+
+func newRunnerCmd(_ func() *Env, _ *globalFlags) *cobra.Command {
+	runner.Version = Version // propagate the cloud build version into the daemon
+	var configPath string
+	cmd := &cobra.Command{
+		Use:   "runner",
+		Short: "Run this machine as a JIT CI runner for your org (GitHub Actions)",
+		Long: "Turn this box into an ephemeral, GPU-aware GitHub Actions runner for your\n" +
+			"org(s). A GitHub App polls for queued jobs and spawns auto-exiting runner\n" +
+			"subprocesses labelled with this machine's tags. Outbound-only; nothing\n" +
+			"listens for inbound. Config defaults to ~/.arcd/config.yaml (app_id, orgs,\n" +
+			"labels, runner_dir).",
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			cfg, err := runner.LoadConfig(configPath)
+			if err != nil {
+				return err
+			}
+			ctx, stop := signal.NotifyContext(cmd.Context(), syscall.SIGINT, syscall.SIGTERM)
+			defer stop()
+			return runner.RunHost(ctx, cfg)
+		},
+	}
+	cmd.Flags().StringVar(&configPath, "config", "", "runner config.yaml (default: ~/.arcd/config.yaml)")
+	return cmd
+}

cli/studio.go

@@ -0,0 +1,176 @@
+// studio.go — local Hanzo Studio render-backend supervision for `hanzo gpu
+// connect --studio-dir <checkout>`. The gpu-jobs claim loop renders on the
+// LOCAL studio server (127.0.0.1:8188); this keeps that server alive so the
+// box needs no separate watchdog script or hand-rolled systemd unit — the
+// hanzo CLI is the one way a BYO box joins the fleet, render backend included.
+//
+// Semantics (ported from the GB10 watchdog it replaces): health-probe
+// /system_stats; on failure, one grace re-check, then free the port (a stale
+// main.py holding :8188 makes the new one crash on EADDRINUSE) and relaunch
+// from the checkout's venv. Emits a line only on restart events.
+package cli
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"syscall"
+	"time"
+)
+
+const (
+	studioAddr        = "127.0.0.1:8188"
+	studioHealthURL   = "http://" + studioAddr + "/system_stats"
+	studioProbeEvery  = 45 * time.Second
+	studioGraceWait   = 8 * time.Second
+	studioStartWindow = 180 * time.Second
+)
+
+func studioHealthy(ctx context.Context) bool {
+	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, studioHealthURL, nil)
+	if err != nil {
+		return false
+	}
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return false
+	}
+	resp.Body.Close()
+	return resp.StatusCode == http.StatusOK
+}
+
+// studioPython picks the checkout's venv interpreter, falling back to python3.
+func studioPython(dir string) string {
+	venv := filepath.Join(dir, ".venv", "bin", "python")
+	if _, err := os.Stat(venv); err == nil {
+		return venv
+	}
+	return "python3"
+}
+
+// launchStudio starts the render backend from dir, logging to
+// <dir>/studio-local.log. The process gets its own group so a restart can
+// kill stragglers (torch dataloader workers and the like) in one signal.
+func launchStudio(dir string) (*exec.Cmd, error) {
+	logf, err := os.OpenFile(filepath.Join(dir, "studio-local.log"),
+		os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644)
+	if err != nil {
+		return nil, err
+	}
+	cmd := exec.Command(studioPython(dir), "main.py",
+		"--listen", "0.0.0.0", "--port", "8188",
+		"--normalvram", "--disable-auto-launch",
+		"--output-directory", filepath.Join(dir, "output"))
+	cmd.Dir = dir
+	cmd.Env = append(os.Environ(),
+		"STUDIO_PERSIST_QUEUE=1",
+		"PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True",
+	)
+	cmd.Stdout = logf
+	cmd.Stderr = logf
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	if err := cmd.Start(); err != nil {
+		logf.Close()
+		return nil, err
+	}
+	logf.Close() // the child holds its own descriptor
+	// Shield the render backend from the OOM killer ahead of pack/model RAM
+	// spikes. Negative adj needs privilege; best-effort.
+	_ = os.WriteFile("/proc/"+strconv.Itoa(cmd.Process.Pid)+"/oom_score_adj",
+		[]byte("-700"), 0o644)
+	go func() { _ = cmd.Wait() }() // reap; the probe loop decides on restarts
+	return cmd, nil
+}
+
+// stopStudio kills the supervised process group (if any) and any foreign
+// main.py still holding the port, then waits for the listener to clear.
+func stopStudio(cmd *exec.Cmd) {
+	if cmd != nil && cmd.Process != nil {
+		_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGTERM)
+	}
+	_ = exec.Command("pkill", "-f", "main.py --listen").Run()
+	for i := 0; i < 15; i++ {
+		conn, err := net.DialTimeout("tcp", studioAddr, time.Second)
+		if err != nil {
+			return
+		}
+		conn.Close()
+		time.Sleep(time.Second)
+	}
+}
+
+// studioRecycle carries at most one pending recycle request; the render
+// handler signals it after each completed render (see gpu.go).
+var studioRecycle = make(chan struct{}, 1)
+
+func requestStudioRecycle() {
+	select {
+	case studioRecycle <- struct{}{}:
+	default:
+	}
+}
+
+// superviseStudio keeps the local render backend on :8188 alive until ctx
+// ends. Quiet by design: one line per restart event, not a probe firehose.
+func superviseStudio(ctx context.Context, dir string, out io.Writer) {
+	var cmd *exec.Cmd
+	restart := func(reason string) {
+		stopStudio(cmd)
+		c, err := launchStudio(dir)
+		if err != nil {
+			fmt.Fprintf(out, "studio: launch failed (%s): %v\n", reason, err)
+			return
+		}
+		cmd = c
+		deadline := time.Now().Add(studioStartWindow)
+		for time.Now().Before(deadline) && ctx.Err() == nil {
+			if studioHealthy(ctx) {
+				fmt.Fprintf(out, "studio: serving on %s (pid %d, %s)\n", studioAddr, c.Process.Pid, reason)
+				return
+			}
+			time.Sleep(4 * time.Second)
+		}
+		fmt.Fprintf(out, "studio: started pid %d (%s) but %s not healthy yet\n", c.Process.Pid, reason, studioAddr)
+	}
+
+	if !studioHealthy(ctx) {
+		restart("boot")
+	} else {
+		fmt.Fprintf(out, "studio: already serving on %s\n", studioAddr)
+	}
+
+	tick := time.NewTicker(studioProbeEvery)
+	defer tick.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			if cmd != nil && cmd.Process != nil {
+				_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGTERM)
+			}
+			return
+		case <-studioRecycle:
+			restart("recycle")
+		case <-tick.C:
+			if studioHealthy(ctx) {
+				continue
+			}
+			// Grace re-check: it may be momentarily busy mid-render.
+			select {
+			case <-ctx.Done():
+				continue
+			case <-time.After(studioGraceWait):
+			}
+			if !studioHealthy(ctx) {
+				restart("unresponsive")
+			}
+		}
+	}
+}

clients/account/account.go

@@ -0,0 +1,524 @@
+// Package account mounts the signed-in caller's OWN account self-service surface
+// natively in the unified cloud binary — the Go port of the console's two NON-proxy
+// Next server routes (app/keys + app/onboard) plus the money/store data bridges the
+// statically-exported console needs (task #41, "True 1-binary FE"). It replaces the
+// retired /v1/console/* namespace: "console" is just the cloud FE name, so there is NO
+// /v1/console API domain — every route lives on its REAL domain.
+//
+// WHY THESE ROUTES (and not the pure passthrough proxies). The console's PURE BFF
+// reverse-proxies — app/cloud, app/ai — vanish in the one-binary model: the SPA calls
+// the canonical /v1/* on its own origin and the already-mounted subsystems answer. The
+// routes ported HERE do REAL server work a static SPA cannot: keys/onboard run
+// privileged IAM logic as the confidential `hanzo-console` client; embed-status/topup
+// do server-side verification; and the billing/commerce bridges inject the commerce
+// SERVICE token and pin the caller's own subject SERVER-SIDE (a passthrough would leak
+// cross-tenant ledgers). Each has no pure-proxy equivalent, so it must be ported.
+//
+// SURFACE — each route on its REAL domain (every one requires a VALIDATED principal — a
+// gateway-minted, IAM-verified X-User-Id; a client-forged X-Org-Id on the bearer-less
+// path is refused):
+//
+//	GET    /v1/iam/keys              — whether the caller has an `hk-` key (+ prefix/mtime); no secret.
+//	POST   /v1/iam/keys              — mint/rotate the key; returns { accessKey } ONCE.
+//	DELETE /v1/iam/keys              — revoke the key.
+//	POST   /v1/iam/onboard           — create the caller's org (+ move them in on first run).
+//	GET    /v1/csrf                  — mint the anti-CSRF token the SPA echoes on money writes (csrf.go).
+//	GET    /v1/embed-status          — brand-app embed entitlement + reachability probe (embed.go).
+//	POST   /v1/commerce/topup/wallet — HUSD on-chain verify → commerce credit (topup.go).
+//	GET    /v1/billing/*             — per-tenant billing read, SCOPED to the validated caller (billing.go).
+//	…      /v1/commerce/*            — per-tenant STORE CRUD, SCOPED to the validated caller's org (commerce.go).
+//
+// TWO SUBSYSTEM REGISTRATIONS FROM ONE PACKAGE. A route-ordering constraint forces the
+// split (Fiber matches by registration order — the earliest-mounted route wins):
+//   - `account` (order 48) mounts the SPECIFIC self-service routes. keys/onboard MUST
+//     win over clients/iam's /v1/iam/* WILDCARD (order 50), and topup MUST win over the
+//     commerce embed (order 100) + the /v1/commerce/* bridge — so they mount EARLY.
+//   - `account-bridge` (order 122) mounts the CATCH-ALL data bridges. /v1/billing/* must
+//     sit AFTER clients/billing's specific routes (order 121) and /v1/commerce/* after
+//     the commerce embed (order 100) — so they mount LATE.
+//
+// Both share one state shape + the process-wide CSRF key (csrf.go), so a token minted at
+// /v1/csrf verifies on the /v1/billing|commerce writes.
+//
+// TENANCY. The caller is resolved from the VALIDATED identity headers ONLY
+// (principal.Validated / c.Org() / c.User()), the same trust boundary every mutating
+// subsystem uses. The IAM id targeted is DERIVED as `<owner>/<name>` from those
+// validated claims — never taken from the request body/query — so a caller can only ever
+// mint/revoke their OWN key and onboard THEMSELVES; there is no path to name a
+// third-party subject. When the confidential client is unwired the surface is honestly
+// "not configured" (501), never a fabricated key or org.
+package account
+
+import (
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"net/http"
+	"os"
+	"strings"
+
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/principal"
+	"github.com/zap-proto/zip"
+)
+
+// adminOrg is THE SuperAdmin / IAM-system org that owns every customer org row —
+// standardized as "admin" across the whole stack (IAM, commerce, ai, gateway all
+// gate cross-tenant on owner=="admin"). A created customer org is owned by it.
+const adminOrg = "admin"
+
+// errNotConfigured is returned by the IAM client when the confidential
+// `hanzo-console` credential is unset; handlers map it to a 501 (honest "not
+// configured on this deployment", mirroring identity.ts's mintConfigured() gate).
+var errNotConfigured = errors.New("iam confidential client not configured")
+
+// errNotFound is a not-present sentinel (e.g. the user row IAM cannot return).
+var errNotFound = errors.New("not found")
+
+// state is account's own data; shared deps live in the embedded cloud.Base. Both
+// subsystem registrations (account @48, account-bridge @122) build their own value;
+// the CSRF key is the process-wide singleton (csrf.go) so a token minted by one
+// verifies on the other.
+type state struct {
+	iam      *iamClient
+	csrfKey  []byte       // keyed-BLAKE3 MAC key for the money-write CSRF token (csrf.go)
+	writesRL *rateLimiter // per-IP abuse cap on the money-write routes (ratelimit.go)
+}
+
+// keysWriteRatePerMin caps money-write frequency per client IP (mint/rotate/revoke
+// key, wallet top-up). Generous enough for real UI bursts, tight enough to blunt
+// brute-force / enumeration when a caller reaches cloud directly (gateway bypassed).
+const keysWriteRatePerMin = 30
+
+// newService builds the shared subsystem value. Both subsystem Mounts construct one;
+// the CSRF key is the process-wide singleton (csrf.go) so account (order 48) and
+// account-bridge (order 122) verify each other's tokens.
+func newService(deps cloud.Deps) *cloud.Service[state] {
+	b := cloud.NewBase(deps, "account")
+	st := state{iam: newIAMClient()}
+	st.csrfKey = sharedCSRFKey(b.Log)
+	st.writesRL = newRateLimiter(keysWriteRatePerMin)
+	return &cloud.Service[state]{Base: b, State: st}
+}
+
+// MountAccount wires the SPECIFIC self-service routes (order 48) — the ones that must
+// win over the IAM /v1/iam/* wildcard (50) and the commerce embed (100).
+func MountAccount(app *zip.App, deps cloud.Deps) error {
+	if app == nil {
+		return fmt.Errorf("account.MountAccount: nil zip.App")
+	}
+	if deps.Logger == nil {
+		return fmt.Errorf("account.MountAccount: nil deps.Logger")
+	}
+	s := newService(deps)
+	routesAccount(s, app)
+	s.Log.Info("account self-service surface mounted",
+		"iam", s.State.iam.base, "configured", s.State.iam.configured(), "brand", s.Brand)
+	return nil
+}
+
+// MountBridge wires the CATCH-ALL data bridges (order 122) — the /v1/billing/* and
+// /v1/commerce/* proxies that must sit AFTER clients/billing (121) + the commerce embed.
+func MountBridge(app *zip.App, deps cloud.Deps) error {
+	if app == nil {
+		return fmt.Errorf("account.MountBridge: nil zip.App")
+	}
+	if deps.Logger == nil {
+		return fmt.Errorf("account.MountBridge: nil deps.Logger")
+	}
+	s := newService(deps)
+	routesBridge(s, app)
+	s.Log.Info("account data bridges mounted", "prefixes", "/v1/billing/*,/v1/commerce/*", "brand", s.Brand)
+	return nil
+}
+
+// routesAccount wires the specific self-service routes (order 48).
+func routesAccount(s *cloud.Service[state], app *zip.App) {
+	// GET /v1/csrf issues the anti-CSRF token the embedded SPA echoes as X-CSRF-Token on
+	// every money write (csrf.go). Safe (read-only), same-origin.
+	app.Get("/v1/csrf", cloud.Handle(s, issueCSRFToken))
+	// The caller's own `hk-` Cloud API key — IAM self-service. These SPECIFIC routes MUST
+	// register before clients/iam's /v1/iam/* wildcard (order 50 > 48) so Fiber's
+	// first-match scan hits the native handler, not the wildcard (TestIAMKeysBeatsWildcard).
+	// Reads are open; every state-changing WRITE is wrapped: requireCSRF blocks a
+	// cross-site ambient-cookie forgery, and rateLimit caps per-IP frequency (cloud is
+	// reachable off-gateway).
+	app.Get("/v1/iam/keys", cloud.Handle(s, getKey))
+	app.Post("/v1/iam/keys", rateLimit(s, s.State.writesRL, requireCSRF(s, cloud.Handle(s, mintKey))))
+	app.Delete("/v1/iam/keys", rateLimit(s, s.State.writesRL, requireCSRF(s, cloud.Handle(s, revokeKey))))
+	app.Post("/v1/iam/onboard", requireCSRF(s, cloud.Handle(s, onboard)))
+	// Console module embed-entitlement + reachability probe (embed.go).
+	app.Get("/v1/embed-status", cloud.Handle(s, embedStatus))
+	// HUSD wallet top-up (on-chain verify → commerce credit). A SPECIFIC commerce route
+	// that must beat the /v1/commerce/* bridge (122) AND the commerce embed (100) — so it
+	// mounts here at 48, ahead of both.
+	app.Post("/v1/commerce/topup/wallet", rateLimit(s, s.State.writesRL, requireCSRF(s, cloud.Handle(s, walletTopup))))
+}
+
+// routesBridge wires the per-tenant catch-all data bridges (order 122).
+func routesBridge(s *cloud.Service[state], app *zip.App) {
+	// Per-tenant billing DATA bridge — the canonical /v1/billing/* the statically-exported
+	// console calls, forwarded to commerce with the admin service token and SCOPED to the
+	// validated caller's own subject (billing.go). Registered AFTER clients/billing's
+	// specific routes (121 < 122) so those win and this catches the rest. GET+POST only.
+	// The wildcard is what the ROUTER matches; it is NOT the forwardable set — billing.go's
+	// billingForwardable allowlist decides that, per method, and 404s everything else
+	// BEFORE the admin service token is attached. Widening this pattern grants nothing on
+	// its own; adding a line to that table is the only way to expose an endpoint.
+	app.Get("/v1/billing/*", cloud.Handle(s, billingData))
+	app.Post("/v1/billing/*", requireCSRF(s, cloud.Handle(s, billingData)))
+	// Per-tenant STORE DATA bridge — the canonical /v1/commerce/* the console calls,
+	// forwarded to commerce's bare store surface /v1/<kind> with the admin service token
+	// and SCOPED to the validated caller's own org (commerce.go). Registered AFTER the
+	// commerce embed (100 < 122) so the embed wins when enabled. Full CRUD.
+	app.Get("/v1/commerce/*", cloud.Handle(s, commerceData))
+	app.Post("/v1/commerce/*", requireCSRF(s, cloud.Handle(s, commerceData)))
+	app.Put("/v1/commerce/*", requireCSRF(s, cloud.Handle(s, commerceData)))
+	app.Patch("/v1/commerce/*", requireCSRF(s, cloud.Handle(s, commerceData)))
+	app.Delete("/v1/commerce/*", requireCSRF(s, cloud.Handle(s, commerceData)))
+}
+
+// ── caller resolution (the tenancy boundary) ─────────────────────────────────
+
+// caller is the signed-in user resolved from the VALIDATED identity headers. id is
+// the `<owner>/<name>` composite IAM's privileged ops parse (GetOwnerAndNameFromId
+// requires it — a bare token count of 1 throws "wrong token count"); owner is the
+// org (X-Org-Id).
+type caller struct {
+	id       string // <owner>/<name> (or the bare user id when owner-less)
+	owner    string // validated org (may be "" for a zero-org, first-run user)
+	name     string // == X-User-Id: the stable user id (a UUID on the direct path)
+	username string // IAM username (X-User-Name); the `name` half IAM's user-key ops parse
+}
+
+// keyID is the `<owner>/<username>` composite IAM's user-key ops (mint/get/revoke
+// user AccessKey) parse via GetOwnerAndNameFromId. It uses the IAM USERNAME, not
+// name (== X-User-Id): on the in-binary direct-Bearer path X-User-Id is the UUID
+// subject and `<owner>/<uuid>` fails IAM's user lookup ("password or code is
+// incorrect"). On the gateway path username==name so keyID()==id — no change.
+// Owner-less (first-run) callers can't own a key, so this is only reached with a
+// validated owner; it falls back to id defensively.
+func (cr caller) keyID() string {
+	if cr.owner != "" && cr.username != "" {
+		return cr.owner + "/" + cr.username
+	}
+	return cr.id
+}
+
+// resolveCaller derives the caller from the validated identity, or (zero,false)
+// when there is no validated principal. requireOwner=true refuses a user with no
+// org yet (used by the key ops, which must act scoped); onboarding passes
+// requireOwner=false so a first-run zero-org user can create their first org. The id
+// is ALWAYS derived from the validated claims, never a request value.
+func resolveCaller(c *zip.Ctx, requireOwner bool) (caller, bool) {
+	if !principal.Validated(c) {
+		return caller{}, false // no gateway-minted, IAM-verified principal — refuse
+	}
+	name := strings.TrimSpace(c.User())
+	if name == "" {
+		return caller{}, false
+	}
+	owner := strings.TrimSpace(c.Org())
+	if requireOwner && owner == "" {
+		return caller{}, false
+	}
+	// IAM parses `<owner>/<name>`; prefer it, fall back to the bare id for an
+	// owner-less (first-run) user. Same id semantics as identity.ts.
+	id := name
+	if owner != "" {
+		id = owner + "/" + name
+	}
+	// username is the IAM USERNAME, kept DISTINCT from name (== X-User-Id) so the
+	// billing/topup subjects (which key on name) are byte-identical to today — this
+	// value narrows the blast radius to the IAM user-key ops alone (keyID()). It
+	// prefers X-User-Name (stamped from the validated `name` claim by
+	// SanitizeIdentity), because on the in-binary direct-Bearer path X-User-Id is the
+	// UUID subject and <owner>/<uuid> fails IAM's mint-user-keys/get-user lookup.
+	// Falls back to name for the gateway path (which mints X-User-Id==username). Both
+	// inputs are gateway/SanitizeIdentity-minted from a verified principal.
+	username := strings.TrimSpace(c.Header("X-User-Name"))
+	if username == "" {
+		username = name
+	}
+	return caller{id: id, owner: owner, name: name, username: username}, true
+}
+
+// ── keys (the per-user `hk-` Cloud API key) ──────────────────────────────────
+
+type keyStatus struct {
+	HasKey    bool   `json:"hasKey"`
+	KeyPrefix string `json:"keyPrefix,omitempty"`
+	CreatedAt string `json:"createdAt,omitempty"`
+}
+
+// getKey reports whether the caller has an `hk-` key, its public prefix, and when
+// the key row last changed — NO secret material. Reads IAM authoritatively (not the
+// session claim, which lags a fresh key). Mirrors GET app/keys/route.ts.
+func getKey(s *cloud.Service[state], c *zip.Ctx) error {
+	cr, ok := resolveCaller(c, true)
+	if !ok {
+		return zip.ErrForbidden("sign in to manage API keys")
+	}
+	if !s.State.iam.configured() {
+		return notConfigured("API key management")
+	}
+	uk, err := s.State.iam.getUserKey(c.Context(), cr.keyID())
+	if err != nil {
+		// Fail-soft on a transient IAM read: report "no key" rather than 5xx, so the
+		// page shows the honest empty state (never a fabricated key). The mint path
+		// still 502s loudly on a real failure — reads degrade, writes do not.
+		s.Log.Warn("get key: iam read failed (reporting no key)", "err", err)
+		return c.JSON(http.StatusOK, keyStatus{HasKey: false})
+	}
+	if uk.AccessKey == "" {
+		return c.JSON(http.StatusOK, keyStatus{HasKey: false})
+	}
+	prefix := uk.AccessKey
+	if len(prefix) > 11 {
+		prefix = prefix[:11]
+	}
+	return c.JSON(http.StatusOK, keyStatus{HasKey: true, KeyPrefix: prefix, CreatedAt: uk.UpdatedTime})
+}
+
+// mintKey (re)generates the caller's `hk-` key and returns it ONCE (show-once). A
+// real IAM failure surfaces as 502 (never a fabricated key). Mirrors POST app/keys.
+func mintKey(s *cloud.Service[state], c *zip.Ctx) error {
+	cr, ok := resolveCaller(c, true)
+	if !ok {
+		return zip.ErrForbidden("sign in to manage API keys")
+	}
+	if !s.State.iam.configured() {
+		return notConfigured("API key management")
+	}
+	key, err := s.State.iam.mintUserKey(c.Context(), cr.keyID())
+	if err != nil {
+		return zip.Errorf(http.StatusBadGateway, "could not mint an API key: %v", err)
+	}
+	return c.JSON(http.StatusOK, map[string]string{"accessKey": key})
+}
+
+// revokeKey clears the caller's `hk-` key. Mirrors DELETE app/keys.
+func revokeKey(s *cloud.Service[state], c *zip.Ctx) error {
+	cr, ok := resolveCaller(c, true)
+	if !ok {
+		return zip.ErrForbidden("sign in to manage API keys")
+	}
+	if !s.State.iam.configured() {
+		return notConfigured("API key management")
+	}
+	if err := s.State.iam.revokeUserKey(c.Context(), cr.keyID()); err != nil {
+		return zip.Errorf(http.StatusBadGateway, "could not revoke the API key: %v", err)
+	}
+	return c.JSON(http.StatusOK, map[string]bool{"ok": true})
+}
+
+// ── onboard (create the caller's org) ────────────────────────────────────────
+
+type onboardReq struct {
+	Name     string `json:"name"`
+	Personal bool   `json:"personal"`
+}
+
+type onboardResp struct {
+	Org         string `json:"org"`
+	DisplayName string `json:"displayName"`
+	Additional  bool   `json:"additional"`
+}
+
+// onboard creates the caller's organization. Two flows, keyed on whether the caller
+// already has a home org (mirrors app/onboard/route.ts):
+//
+//   - FIRST-RUN (no owner): create + MOVE the user in as admin, so their next JWT
+//     carries the new owner and the cloud scopes everything to it.
+//   - ADDITIONAL (owner set): create the org but do NOT move the user — a move
+//     changes their IAM owner (stripping a SuperAdmin's status + orphaning their
+//     current org). They reach the new org via the OrgSwitcher, which re-scopes
+//     X-Org-Id without touching IAM membership. A personal-org request from someone
+//     who already has an org is meaningless → 409.
+func onboard(s *cloud.Service[state], c *zip.Ctx) error {
+	cr, ok := resolveCaller(c, false) // first-run onboarding allows a zero-org user
+	if !ok {
+		return zip.ErrForbidden("sign in to create an organization")
+	}
+	if !s.State.iam.configured() {
+		return notConfigured("organization creation")
+	}
+	var body onboardReq
+	if len(c.Body()) > 0 {
+		if err := c.Bind(&body); err != nil {
+			return err
+		}
+	}
+
+	additional := cr.owner != ""
+	if additional && body.Personal {
+		return zip.ErrConflict("you already have an organization; name the new one explicitly")
+	}
+
+	baseSlug, displayName, herr := resolveOnboardName(s, body, cr)
+	if herr != nil {
+		return herr
+	}
+
+	// Resolve a unique slug. Personal orgs auto-suffix to stay unique; an explicit
+	// name that's taken is an honest conflict the user resolves by renaming.
+	slug, herr := uniqueSlug(s, c, baseSlug, body.Personal)
+	if herr != nil {
+		return herr
+	}
+
+	// Create the org (cloning the caller's current org for password/locale
+	// compatibility), then — first-run only — move the zero-org user in as admin.
+	org := buildOrg(s, c, slug, displayName, body.Personal, cr.owner)
+	if err := s.State.iam.createOrganization(c.Context(), org); err != nil {
+		return zip.Errorf(http.StatusBadGateway, "could not create the organization: %v", err)
+	}
+	if !additional {
+		if err := s.State.iam.moveUserToOrg(c.Context(), cr.id, slug); err != nil {
+			return zip.Errorf(http.StatusBadGateway, "org created but could not assign you to it: %v", err)
+		}
+	}
+	return c.JSON(http.StatusOK, onboardResp{Org: slug, DisplayName: displayName, Additional: additional})
+}
+
+// resolveOnboardName derives the base slug + display name from the request, or a
+// mapped HTTP error. Personal orgs derive from the username; a named org validates
+// through the shared policy (onboarding.go).
+func resolveOnboardName(s *cloud.Service[state], body onboardReq, cr caller) (baseSlug, displayName string, err error) {
+	if body.Personal {
+		baseSlug = personalOrgSlug(cr.name)
+		if len(baseSlug) < minOrgSlug || isReservedOrg(baseSlug) {
+			baseSlug = "org-" + firstNonEmpty(slugifyOrg(cr.name), "workspace")
+		}
+		return baseSlug, humanize(cr.name), nil
+	}
+	v := validateOrgName(body.Name)
+	if !v.ok {
+		return "", "", zip.ErrBadRequest(v.error)
+	}
+	return v.slug, strings.TrimSpace(body.Name), nil
+}
+
+// uniqueSlug returns a free slug at/after base. A named org that's taken is a 409;
+// a personal org auto-suffixes (base, base-2, …) up to a small bound.
+func uniqueSlug(s *cloud.Service[state], c *zip.Ctx, base string, personal bool) (string, error) {
+	existing, err := s.State.iam.getOrganization(c.Context(), base)
+	if err != nil {
+		return "", zip.Errorf(http.StatusBadGateway, "could not check organization availability: %v", err)
+	}
+	if existing == nil {
+		return base, nil
+	}
+	if !personal {
+		return "", zip.Errorf(http.StatusConflict, "“%s” is taken; choose a different name", base)
+	}
+	free, err := freeSlug(s, c, base)
+	if err != nil {
+		return "", err
+	}
+	if free == "" {
+		return "", zip.Errorf(http.StatusConflict, "could not find an available name")
+	}
+	return free, nil
+}
+
+// freeSlug finds the first free slug at/after base (base, base-2, … base-20), or ""
+// if all are taken. Mirrors identity.ts's freeSlug bound of 20.
+func freeSlug(s *cloud.Service[state], c *zip.Ctx, base string) (string, error) {
+	for i := 2; i <= 20; i++ {
+		trimmed := base
+		if len(trimmed) > maxOrgSlug-3 {
+			trimmed = trimmed[:maxOrgSlug-3]
+		}
+		candidate := strings.Trim(fmt.Sprintf("%s-%d", strings.TrimRight(trimmed, "-"), i), "-")
+		if len(candidate) < minOrgSlug || isReservedOrg(candidate) {
+			continue
+		}
+		existing, err := s.State.iam.getOrganization(c.Context(), candidate)
+		if err != nil {
+			return "", zip.Errorf(http.StatusBadGateway, "could not check organization availability: %v", err)
+		}
+		if existing == nil {
+			return candidate, nil
+		}
+	}
+	return "", nil
+}
+
+// buildOrg assembles the new customer org owned by the `admin` org, cloning
+// password/locale settings from the caller's current org (best-effort; a nil source
+// just yields a minimal org IAM completes with its defaults) and clearing all
+// instance-specific material. Mirrors identity.ts's createOrganization body.
+func buildOrg(s *cloud.Service[state], c *zip.Ctx, slug, displayName string, personal bool, sourceOwner string) iamOrg {
+	org := iamOrg{Owner: adminOrg, Name: slug, DisplayName: displayName, IsPersonal: personal}
+	if sourceOwner == "" {
+		return org
+	}
+	src, err := s.State.iam.getOrganization(c.Context(), sourceOwner)
+	if err != nil || src == nil {
+		return org // clone is best-effort; IAM applies its org defaults otherwise
+	}
+	org.PasswordType = src.PasswordType
+	org.PasswordSalt = src.PasswordSalt
+	org.PasswordObfuscatorType = src.PasswordObfuscatorType
+	org.PasswordObfuscatorKey = src.PasswordObfuscatorKey
+	org.PasswordOptions = src.PasswordOptions
+	org.CountryCodes = src.CountryCodes
+	org.Languages = src.Languages
+	org.DefaultAvatar = src.DefaultAvatar
+	return org
+}
+
+// ── shared helpers ────────────────────────────────────────────────────────────
+
+// notConfigured is the honest 501 for a surface whose confidential client is
+// unwired — the deployment simply lacks the `hanzo-console` credential.
+func notConfigured(surface string) error {
+	return zip.Errorf(http.StatusNotImplemented, "%s is not configured on this deployment (IAM client unset)", surface)
+}
+
+// humanize title-cases the base of a username for a personal org's display name
+// (dave.smith@x.com → "Dave Smith"). Mirrors identity/onboard humanize().
+func humanize(username string) string {
+	base := username
+	// Split on '@' anywhere (mirrors identity.ts humanize's `includes('@')`), so a
+	// bare "@" collapses to "" → "Personal". (personalOrgSlug intentionally uses
+	// `> 0` instead, matching its own TS source.)
+	if at := strings.IndexByte(base, '@'); at >= 0 {
+		base = base[:at]
+	}
+	base = strings.TrimSpace(strings.Map(func(r rune) rune {
+		if r == '.' || r == '_' || r == '-' {
+			return ' '
+		}
+		return r
+	}, base))
+	if base == "" {
+		return "Personal"
+	}
+	parts := strings.Fields(base)
+	for i, p := range parts {
+		parts[i] = strings.ToUpper(p[:1]) + p[1:]
+	}
+	return strings.Join(parts, " ")
+}
+
+func firstNonEmpty(vals ...string) string {
+	for _, v := range vals {
+		if v != "" {
+			return v
+		}
+	}
+	return ""
+}
+
+func getenv(key, dflt string) string {
+	if v := strings.TrimSpace(os.Getenv(key)); v != "" {
+		return v
+	}
+	return dflt
+}
+
+func basicToken(id, secret string) string {
+	return base64.StdEncoding.EncodeToString([]byte(id + ":" + secret))
+}

clients/account/account_test.go

@@ -1,4 +1,4 @@
-package console
+package account
 
 import (
 	"encoding/base64"
@@ -24,18 +24,18 @@ type fakeIAM struct {
 	mu sync.Mutex
 
 	// state
-	keys map[string]string            // id → current hk- key ("" = none)
-	orgs map[string]map[string]any    // slug → org row (nil map = absent)
-	user map[string]map[string]any    // id → full user row (for the move)
+	keys map[string]string         // id → current hk- key ("" = none)
+	orgs map[string]map[string]any // slug → org row (nil map = absent)
+	user map[string]map[string]any // id → full user row (for the move)
 
 	// captured
-	gotAuth       string   // Authorization header on the last request
-	mintedFor     []string // ids mint-user-keys was called with
-	revokedFor    []string
-	movedTo       map[string]string // id → new owner (from update-user)
-	createdOrgs   []map[string]any
-	failAddOrg    bool // when true, add-organization answers status!=ok
-	failMintKey   bool
+	gotAuth     string   // Authorization header on the last request
+	mintedFor   []string // ids mint-user-keys was called with
+	revokedFor  []string
+	movedTo     map[string]string // id → new owner (from update-user)
+	createdOrgs []map[string]any
+	failAddOrg  bool // when true, add-organization answers status!=ok
+	failMintKey bool
 }
 
 func newFakeIAM() *fakeIAM {
@@ -165,20 +165,60 @@ func (f *fakeIAM) capture(r *http.Request) {
 	f.mu.Unlock()
 }
 
-// mountApp mounts the console surface against the fake IAM at base, with the
+// mountApp mounts the account surface against the fake IAM at base, with the
 // confidential client wired (unless creds are ""). Returns the app.
 func mountApp(t *testing.T, base, clientID, clientSecret string) *zip.App {
 	t.Helper()
 	t.Setenv("IAM_URL", base)
 	t.Setenv("IAM_MINT_CLIENT_ID", clientID)
 	t.Setenv("IAM_MINT_CLIENT_SECRET", clientSecret)
+	return mountBoth(t, "hanzo")
+}
+
+// mountBoth mounts BOTH account subsystems (self-service + data bridges) on one app —
+// exactly what production registers (account@48 then account-bridge@122), so a test
+// exercises the full surface with the shared CSRF key. The caller sets the IAM env
+// (IAM_URL / IAM_MINT_CLIENT_*) before calling.
+func mountBoth(t *testing.T, brand string) *zip.App {
+	t.Helper()
 	app := zip.New(zip.Config{Logger: luxlog.New("test")})
-	if err := Mount(app, cloud.Deps{Logger: luxlog.New("test"), Brand: "hanzo"}); err != nil {
-		t.Fatalf("Mount: %v", err)
+	deps := cloud.Deps{Logger: luxlog.New("test"), Brand: brand}
+	if err := MountAccount(app, deps); err != nil {
+		t.Fatalf("MountAccount: %v", err)
+	}
+	if err := MountBridge(app, deps); err != nil {
+		t.Fatalf("MountBridge: %v", err)
 	}
 	return app
 }
 
+// callH drives a request with arbitrary VALIDATED-identity headers (the gateway sets
+// these only from a verified credential). Mirrors `call` but lets a test inject
+// X-User-Email / X-User-IsAdmin, which the ported routes read.
+func callH(t *testing.T, app *zip.App, method, path string, headers map[string]string, body string) (int, []byte) {
+	t.Helper()
+	var rdr io.Reader
+	if body != "" {
+		rdr = strings.NewReader(body)
+	}
+	req := httptest.NewRequest(method, path, rdr)
+	if body != "" {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	for k, v := range headers {
+		if v != "" {
+			req.Header.Set(k, v)
+		}
+	}
+	resp, err := app.Fiber().Test(req)
+	if err != nil {
+		t.Fatalf("Test %s %s: %v", method, path, err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	b, _ := io.ReadAll(resp.Body)
+	return resp.StatusCode, b
+}
+
 // call drives a request through the mounted app. When user is non-empty it injects
 // a VALIDATED principal (X-User-Id set — the gateway sets this ONLY from a verified
 // credential) with org as X-Org-Id. body is an optional JSON string.
@@ -216,7 +256,7 @@ func TestKeys_RequireValidatedPrincipal(t *testing.T) {
 	// No X-User-Id → no validated principal → 403, and IAM is never touched, even if
 	// a forged X-Org-Id is present (the bearer-less data path must not mint a key).
 	for _, m := range []string{http.MethodGet, http.MethodPost, http.MethodDelete} {
-		code, _ := call(t, app, m, "/v1/console/keys", "", "victim", "")
+		code, _ := call(t, app, m, "/v1/iam/keys", "", "victim", "")
 		if code != http.StatusForbidden {
 			t.Fatalf("%s /keys with forged org but no principal: want 403, got %d", m, code)
 		}
@@ -231,7 +271,7 @@ func TestKeys_MintGetRevoke_ScopedToCaller(t *testing.T) {
 	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
 
 	// GET before mint → hasKey:false (authoritative IAM read, not the claim).
-	code, body := call(t, app, http.MethodGet, "/v1/console/keys", "alice", "acme", "")
+	code, body := call(t, app, http.MethodGet, "/v1/iam/keys", "alice", "acme", "")
 	if code != http.StatusOK {
 		t.Fatalf("get pre-mint: want 200, got %d (%s)", code, body)
 	}
@@ -243,7 +283,7 @@ func TestKeys_MintGetRevoke_ScopedToCaller(t *testing.T) {
 
 	// POST → mint; the key is returned ONCE, and IAM was targeted with the DERIVED
 	// `<owner>/<name>` id — never a request value.
-	code, body = call(t, app, http.MethodPost, "/v1/console/keys", "alice", "acme", "")
+	code, body = call(t, app, http.MethodPost, "/v1/iam/keys", "alice", "acme", "")
 	if code != http.StatusOK {
 		t.Fatalf("mint: want 200, got %d (%s)", code, body)
 	}
@@ -266,7 +306,7 @@ func TestKeys_MintGetRevoke_ScopedToCaller(t *testing.T) {
 	}
 
 	// GET after mint → hasKey:true with the public prefix only (no secret material).
-	code, body = call(t, app, http.MethodGet, "/v1/console/keys", "alice", "acme", "")
+	code, body = call(t, app, http.MethodGet, "/v1/iam/keys", "alice", "acme", "")
 	mustJSON(t, body, &st)
 	if code != http.StatusOK || !st.HasKey || st.KeyPrefix != "hk-acme-ali" {
 		t.Fatalf("get post-mint: want hasKey + 11-char prefix, got %d %s", code, body)
@@ -276,16 +316,53 @@ func TestKeys_MintGetRevoke_ScopedToCaller(t *testing.T) {
 	}
 
 	// DELETE → revoke, targeting the same derived id.
-	code, _ = call(t, app, http.MethodDelete, "/v1/console/keys", "alice", "acme", "")
+	code, _ = call(t, app, http.MethodDelete, "/v1/iam/keys", "alice", "acme", "")
 	if code != http.StatusOK || len(f.revokedFor) != 1 || f.revokedFor[0] != "acme/alice" {
 		t.Fatalf("revoke: want 200 targeting acme/alice, got %d %v", code, f.revokedFor)
 	}
 }
 
+// TestKeys_DirectBearerPath_MintsByUsernameNotUUID is the regression guard for the
+// cloud-direct hk- mint 502. On the in-binary direct-Bearer path SanitizeIdentity
+// stamps X-User-Id = the JWT subject (a UUID) and, distinctly, X-User-Name = the IAM
+// username. The user-key ops must target <owner>/<username> ("hanzo/z"), NOT
+// <owner>/<uuid> — which failed IAM's GetOwnerAndNameFromId user lookup ("password
+// or code is incorrect", surfaced as 502). The gateway path (no X-User-Name;
+// X-User-Id == username) must be UNCHANGED (keyID falls back to owner/name).
+func TestKeys_DirectBearerPath_MintsByUsernameNotUUID(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	const uuid = "2d4d67ab-30f1-474e-b81f-f60461852259"
+	req := httptest.NewRequest(http.MethodPost, "/v1/iam/keys", nil)
+	req.Header.Set("X-User-Id", uuid)  // direct-path stamp: the subject UUID
+	req.Header.Set("X-User-Name", "z") // direct-path stamp: the IAM username
+	req.Header.Set("X-Org-Id", "hanzo")
+	resp, err := app.Fiber().Test(req)
+	if err != nil {
+		t.Fatalf("Test: %v", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	b, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("direct-path mint: want 200, got %d (%s)", resp.StatusCode, b)
+	}
+	if len(f.mintedFor) != 1 || f.mintedFor[0] != "hanzo/z" {
+		t.Fatalf("direct-path mint must target hanzo/z (username), never hanzo/<uuid>: got %v", f.mintedFor)
+	}
+	var minted struct {
+		AccessKey string `json:"accessKey"`
+	}
+	mustJSON(t, b, &minted)
+	if minted.AccessKey != "hk-hanzo-z-SECRET" {
+		t.Fatalf("direct-path mint returned wrong key: %q", minted.AccessKey)
+	}
+}
+
 func TestKeys_NotConfigured_501(t *testing.T) {
 	f := newFakeIAM()
 	app := mountApp(t, f.server(t).URL, "", "") // confidential client unwired
-	code, body := call(t, app, http.MethodPost, "/v1/console/keys", "alice", "acme", "")
+	code, body := call(t, app, http.MethodPost, "/v1/iam/keys", "alice", "acme", "")
 	if code != http.StatusNotImplemented {
 		t.Fatalf("unconfigured mint: want 501, got %d (%s)", code, body)
 	}
@@ -295,7 +372,7 @@ func TestKeys_MintUpstreamFailure_502(t *testing.T) {
 	f := newFakeIAM()
 	f.failMintKey = true
 	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
-	code, body := call(t, app, http.MethodPost, "/v1/console/keys", "alice", "acme", "")
+	code, body := call(t, app, http.MethodPost, "/v1/iam/keys", "alice", "acme", "")
 	if code != http.StatusBadGateway {
 		t.Fatalf("mint upstream failure: want 502, got %d (%s)", code, body)
 	}
@@ -312,7 +389,7 @@ func TestOnboard_FirstRun_CreatesAndMoves(t *testing.T) {
 
 	// First-run: the caller has NO org (empty X-Org-Id) but IS validated. onboard
 	// must allow it (requireOwner=false), create the org, and MOVE the user in.
-	code, body := call(t, app, http.MethodPost, "/v1/console/onboard", "dave", "", `{"name":"Acme Rockets"}`)
+	code, body := call(t, app, http.MethodPost, "/v1/iam/onboard", "dave", "", `{"name":"Acme Rockets"}`)
 	if code != http.StatusOK {
 		t.Fatalf("first-run onboard: want 200, got %d (%s)", code, body)
 	}
@@ -338,7 +415,7 @@ func TestOnboard_Additional_CreatesWithoutMoving(t *testing.T) {
 
 	// The caller ALREADY has an org. onboard must create the new org but NOT move
 	// them (a move would strip their owner + orphan their current org).
-	code, body := call(t, app, http.MethodPost, "/v1/console/onboard", "alice", "acme", `{"name":"Side Project"}`)
+	code, body := call(t, app, http.MethodPost, "/v1/iam/onboard", "alice", "acme", `{"name":"Side Project"}`)
 	if code != http.StatusOK {
 		t.Fatalf("additional onboard: want 200, got %d (%s)", code, body)
 	}
@@ -358,12 +435,12 @@ func TestOnboard_ReservedAndTaken(t *testing.T) {
 	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
 
 	// A reserved brand/system name is a 400 (policy), before any IAM create.
-	code, _ := call(t, app, http.MethodPost, "/v1/console/onboard", "alice", "acme", `{"name":"Hanzo"}`)
+	code, _ := call(t, app, http.MethodPost, "/v1/iam/onboard", "alice", "acme", `{"name":"Hanzo"}`)
 	if code != http.StatusBadRequest {
 		t.Fatalf("reserved name: want 400, got %d", code)
 	}
 	// An explicit name that's taken is an honest 409.
-	code, _ = call(t, app, http.MethodPost, "/v1/console/onboard", "alice", "acme", `{"name":"Taken"}`)
+	code, _ = call(t, app, http.MethodPost, "/v1/iam/onboard", "alice", "acme", `{"name":"Taken"}`)
 	if code != http.StatusConflict {
 		t.Fatalf("taken name: want 409, got %d", code)
 	}
@@ -380,7 +457,7 @@ func TestOnboard_Personal_AutoSuffixesOnCollision(t *testing.T) {
 
 	// personal:true (zero-org user) with the base slug taken → auto-suffix to dave-2,
 	// first-run move.
-	code, body := call(t, app, http.MethodPost, "/v1/console/onboard", "dave", "", `{"personal":true}`)
+	code, body := call(t, app, http.MethodPost, "/v1/iam/onboard", "dave", "", `{"personal":true}`)
 	if code != http.StatusOK {
 		t.Fatalf("personal onboard: want 200, got %d (%s)", code, body)
 	}
@@ -395,7 +472,7 @@ func TestOnboard_PersonalWhenAlreadyOrged_409(t *testing.T) {
 	f := newFakeIAM()
 	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
 	// A user WITH an org asking for a personal org is meaningless → 409.
-	code, _ := call(t, app, http.MethodPost, "/v1/console/onboard", "alice", "acme", `{"personal":true}`)
+	code, _ := call(t, app, http.MethodPost, "/v1/iam/onboard", "alice", "acme", `{"personal":true}`)
 	if code != http.StatusConflict {
 		t.Fatalf("personal-while-orged: want 409, got %d", code)
 	}
@@ -404,25 +481,69 @@ func TestOnboard_PersonalWhenAlreadyOrged_409(t *testing.T) {
 func TestOnboard_Unauthenticated_403(t *testing.T) {
 	f := newFakeIAM()
 	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
-	code, _ := call(t, app, http.MethodPost, "/v1/console/onboard", "", "", `{"name":"x"}`)
+	code, _ := call(t, app, http.MethodPost, "/v1/iam/onboard", "", "", `{"name":"x"}`)
 	if code != http.StatusForbidden {
 		t.Fatalf("unauth onboard: want 403, got %d", code)
 	}
 }
 
-// ── health ─────────────────────────────────────────────────────────────────
+// ── route ordering: the native /v1/iam surface beats clients/iam's wildcard ───
 
-func TestHealth_ReflectsConfiguration(t *testing.T) {
+// TestIAMKeysBeatsWildcard proves the ACTUAL route-match precedence: with the account
+// self-service routes mounted FIRST (order 48) and clients/iam's /v1/iam/* WILDCARD
+// mounted AFTER (order 50) — the exact production mount order — a request to /v1/iam/keys
+// reaches the NATIVE handler, not the wildcard. A path the native surface does NOT own
+// still falls through to the wildcard, proving it is really mounted and only the specific
+// route shadows it.
+func TestIAMKeysBeatsWildcard(t *testing.T) {
 	f := newFakeIAM()
+	t.Setenv("IAM_URL", f.server(t).URL)
+	t.Setenv("IAM_MINT_CLIENT_ID", "hanzo-console")
+	t.Setenv("IAM_MINT_CLIENT_SECRET", "s3cr3t")
 
-	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
-	if code, _ := call(t, app, http.MethodGet, "/v1/console/health", "", "", ""); code != http.StatusOK {
-		t.Fatalf("configured health: want 200, got %d", code)
+	app := zip.New(zip.Config{Logger: luxlog.New("test")})
+	deps := cloud.Deps{Logger: luxlog.New("test"), Brand: "hanzo"}
+	// account (order 48) mounts its SPECIFIC /v1/iam/keys + /v1/iam/onboard FIRST.
+	if err := MountAccount(app, deps); err != nil {
+		t.Fatalf("MountAccount: %v", err)
+	}
+	// clients/iam (order 50) mounts its /v1/iam/* WILDCARD AFTER — the exact prod order.
+	const sentinel = 599
+	app.All("/v1/iam/*", func(c *zip.Ctx) error {
+		return c.JSON(sentinel, map[string]string{"handler": "iam-wildcard"})
+	})
+
+	// GET /v1/iam/keys must hit the NATIVE handler (keyStatus 200), never the wildcard.
+	code, body := call(t, app, http.MethodGet, "/v1/iam/keys", "alice", "acme", "")
+	if code != http.StatusOK {
+		t.Fatalf("/v1/iam/keys must hit the native handler (200), got %d (%s) — wildcard shadowed it", code, body)
+	}
+	if strings.Contains(string(body), "iam-wildcard") {
+		t.Fatalf("/v1/iam/keys reached the wildcard, not the native handler: %s", body)
+	}
+	var st keyStatus
+	mustJSON(t, body, &st) // native response shape
+
+	// POST /v1/iam/keys (mint) must ALSO hit the native handler and target the derived id.
+	code, body = call(t, app, http.MethodPost, "/v1/iam/keys", "alice", "acme", "")
+	if code != http.StatusOK || strings.Contains(string(body), "iam-wildcard") {
+		t.Fatalf("POST /v1/iam/keys must mint via the native handler, got %d (%s)", code, body)
+	}
+	if len(f.mintedFor) != 1 || f.mintedFor[0] != "acme/alice" {
+		t.Fatalf("native mint must target acme/alice, got %v", f.mintedFor)
 	}
 
-	app2 := mountApp(t, f.server(t).URL, "", "")
-	if code, _ := call(t, app2, http.MethodGet, "/v1/console/health", "", "", ""); code != http.StatusServiceUnavailable {
-		t.Fatalf("unconfigured health: want 503, got %d", code)
+	// /v1/iam/onboard is likewise native (not the wildcard).
+	code, _ = call(t, app, http.MethodPost, "/v1/iam/onboard", "dave", "", `{"name":"Acme Rockets"}`)
+	if code == sentinel {
+		t.Fatalf("/v1/iam/onboard reached the wildcard (%d) — the native handler must win", sentinel)
+	}
+
+	// A path the native surface does NOT own falls through to the wildcard (proof it IS
+	// mounted and only the specific /v1/iam/keys + /v1/iam/onboard routes shadow it).
+	code, _ = call(t, app, http.MethodGet, "/v1/iam/oauth/token", "alice", "acme", "")
+	if code != sentinel {
+		t.Fatalf("/v1/iam/oauth/token must reach the /v1/iam/* wildcard (%d), got %d", sentinel, code)
 	}
 }
 

clients/account/billing.go

@@ -0,0 +1,302 @@
+// billing.go — the per-tenant billing DATA bridge, the Go port of console's
+// app/billing/v1/[...path]/route.ts (task #41, the BFF catch-all sweep). It lets the
+// statically-exported console reach its own money surface at the CANONICAL same-origin
+// /v1/billing/* (nothing before /v1/): GET|POST /v1/billing/<path> forwards to
+// commerce's /v1/billing/<path> with the admin COMMERCE_SERVICE_TOKEN, SCOPING every
+// request to the VALIDATED caller's own billing subject — so a tenant can only ever
+// read/act on its OWN ledger (balance / usage / invoices / subscriptions /
+// payment-methods / spend-alerts / …), never another's.
+//
+// TWO INDEPENDENT BOUNDS, because the token makes this a privileged forwarder:
+//  1. WHICH ENDPOINT — billingForwardable, the per-method allowlist below. It is the
+//     authorization gate: an unlisted path is 404'd before the token is ever attached, so
+//     no money-MINT route (deposit/credit/refund/…) can be reached through this bridge.
+//  2. WHOSE DATA — the subject-pinning below. It aims a permitted call at the caller's own
+//     ledger. It is an IDOR control and NOT an authority control: on a mint route it would
+//     have pinned the CREDIT to the attacker's own account. (1) is what stops that.
+//
+// WHY A SERVER HANDLER (not a same-origin passthrough). Commerce's billing surface is
+// service-token-gated and filters DIFFERENT endpoints on DIFFERENT subject params —
+// subscriptions on ?userId, payment-methods on ?customerId, usage on ?user. Pinning
+// only ONE leaves the others UNFILTERED, so a request with no (or a forged) param
+// returns every subject's rows in the namespace. This handler pins ALL of them to the
+// server-resolved subject (and drops ?org), on the query AND the write body — exactly
+// mirroring console's billing-scope.ts and commerce's own edge-auth billingSubjectKeys.
+//
+// IDOR-safe: the subject is derived from the VALIDATED identity (resolveCaller →
+// principal.Validated / c.Org() / c.User()), NEVER a client-supplied userId/org. A
+// bearer-less request with a forged X-Org-Id has no validated principal and is refused.
+package account
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/url"
+	"strings"
+	"unicode"
+
+	"github.com/hanzoai/account"
+
+	"github.com/hanzoai/cloud"
+	"github.com/zap-proto/zip"
+)
+
+// billingForwardable — THE allowlist of billing endpoints this bridge may forward, keyed
+// by method. It is the whole authorization story of the bridge, because forwarding IS
+// authorization here: every forwarded request carries the admin COMMERCE_SERVICE_TOKEN,
+// and commerce's money gate is MayMintMoney(c) = IsServiceToken(c) || IsSuperAdmin(c)
+// (middleware/platformonly.go). The token satisfies IsServiceToken, so ANY subpath that
+// reaches commerce is executed with PLATFORM authority — not the caller's. Commerce 403s
+// an org admin who calls POST /v1/billing/deposit directly; without this table the bridge
+// handed that same person the platform's own credential and minted it for them, scoped —
+// by the subject-pinning below — to their OWN account. That is the escalation, and
+// subject-pinning is what AIMS it, not what stops it. Only a path gate stops it.
+//
+// It is an ALLOWLIST, never a denylist: a denylist must enumerate every mint route
+// (deposit/credit/refund/credit-grants/payouts/husd/allotment…) and stays correct only
+// until commerce adds the next one — a route this file has never heard of is then
+// forwarded by default. Here the default is REFUSE, so a new commerce mint route is
+// unreachable the day it lands, with no change on this side. One table, one place; a path
+// not in it cannot reach commerce, by construction.
+//
+// GET and POST are SEPARATE sets because a read bridge and a write bridge are different
+// concerns: `payouts` is a legitimate read and a money-MINT write (api/billing/handlers.go
+// `api.Get("/payouts", ListPayouts)` vs `api.Post("/payouts", mintRequired, CreatePayout)`),
+// so one method-blind set would hand the mint to every reader. The POST set is therefore
+// deliberately tiny and holds NOTHING that creates spendable balance from a client-named
+// amount: cancel/reactivate a subscription, vault a card, create a budget, and a top-up
+// that CHARGES a real card (money in, not minted). Every entry is a call the console
+// actually makes; `{}` matches exactly one opaque id segment.
+//
+// EVIDENCE — each entry is a live console call (repo hanzoai/console):
+//
+//	GET  balance             src/lib/api/billing.ts:397   sidebar wallet + billing overview
+//	GET  usage               src/lib/api/billing.ts:415   cost reports / AI metrics
+//	GET  invoices            src/lib/api/billing.ts:419   invoice history table
+//	GET  invoices/{}/pdf     src/components/products/billing/BillingInvoices.tsx:31
+//	GET  subscriptions       src/lib/api/billing.ts:423   subscriptions list
+//	GET  payment-methods     src/lib/api/billing.ts:450   saved cards (masked)
+//	GET  spend-alerts        src/lib/api/billing.ts:482   budgets / spend caps
+//	GET  payment-config      src/lib/api/billing.ts:552   public Square app/location id
+//	GET  plans               src/lib/api/plans.ts:126     published tiers
+//	GET  payouts             src/components/products/SettlementModule.tsx:61  settlement view
+//	POST subscriptions/{}/cancel      src/lib/api/billing.ts:434
+//	POST subscriptions/{}/reactivate  src/lib/api/billing.ts:444
+//	POST payment-methods              src/lib/api/billing.ts:461  vault a Square nonce (no PAN)
+//	POST spend-alerts                 src/lib/api/billing.ts:500  create a budget
+//	POST topup/token                  src/lib/api/billing.ts:565  charge a card → credit
+//
+// balance/usage/payment-methods are ALSO served natively by clients/billing (order 121),
+// which wins over this catch-all (122), so those entries are reached only on a deploy
+// where that subsystem is disabled. They are listed because they are legitimate reads of
+// the caller's own ledger, not because this bridge is their primary route.
+//
+// NOT LISTED, deliberately: `me/welcome` and `grant-starter` (console calls the first at
+// billing.ts:407 and the second server-side at src/lib/server/billing-grant.ts:35) exist
+// in NEITHER the pinned commerce (v1.48.5) route table — both 404 today whether or not
+// this bridge forwards them, and grant-starter is mint-gated and browser-unreachable by
+// design. The console's PATCH/DELETE calls (spend-alerts/{}, payment-methods/{}) are absent
+// because routesBridge mounts GET+POST only, so they never reached this handler.
+var billingForwardable = map[string][]string{
+	http.MethodGet: {
+		"balance",
+		"usage",
+		"invoices",
+		"invoices/{}/pdf",
+		"subscriptions",
+		"payment-methods",
+		"spend-alerts",
+		"payment-config",
+		"plans",
+		"payouts",
+	},
+	http.MethodPost: {
+		"subscriptions/{}/cancel",
+		"subscriptions/{}/reactivate",
+		"payment-methods",
+		"spend-alerts",
+		"topup/token",
+	},
+}
+
+// isForwardableBilling reports whether method+sub is in billingForwardable. sub has
+// already passed isSafeSegment, so no segment can contain a slash, a percent-escape, or a
+// traversal — a pattern segment therefore matches exactly one real segment and `{}` cannot
+// swallow a path. Fail-closed: an unknown method or an unlisted path is false.
+func isForwardableBilling(method, sub string) bool {
+	got := strings.Split(sub, "/")
+	for _, pattern := range billingForwardable[method] {
+		want := strings.Split(pattern, "/")
+		if len(want) != len(got) {
+			continue
+		}
+		match := true
+		for i, seg := range want {
+			if seg != "{}" && seg != got[i] {
+				match = false
+				break
+			}
+		}
+		if match {
+			return true
+		}
+	}
+	return false
+}
+
+// billingSubjectKeys — every query/body param through which a commerce billing endpoint
+// identifies its subject. Kept identical to commerce's edge-auth billingSubjectKeys
+// {user,userId,customerId} AND console's billing-scope.ts BILLING_SUBJECT_KEYS. Change
+// all three together — pinning ALL of them is what scopes EVERY endpoint no matter which
+// param it filters on.
+var billingSubjectKeys = []string{"user", "userId", "customerId"}
+
+func isSubjectKey(k string) bool {
+	for _, s := range billingSubjectKeys {
+		if s == k {
+			return true
+		}
+	}
+	return false
+}
+
+// scopedBillingSearch — pin every billingSubjectKey to subject (OVERWRITING any client
+// value — the browser cannot widen scope) and DROP org. Every OTHER param (currency,
+// status, date range) passes through untouched. Mirrors billing-scope.ts.
+func scopedBillingSearch(in url.Values, subject string) url.Values {
+	out := url.Values{}
+	for k, v := range in {
+		if k == "org" || isSubjectKey(k) {
+			continue // org dropped; subject keys set authoritatively below
+		}
+		out[k] = v
+	}
+	for _, k := range billingSubjectKeys {
+		out.Set(k, subject)
+	}
+	return out
+}
+
+// scopedBillingBody — pin every billingSubjectKey on a top-level JSON object to subject
+// (commerce reads the subject from the JSON body on writes like create-spend-alert). A
+// non-JSON / non-object / empty body is returned UNCHANGED — this only ever narrows a
+// JSON object to the caller; it never invents a body. Mirrors billing-scope.ts.
+func scopedBillingBody(raw []byte, subject string) []byte {
+	if len(bytes.TrimSpace(raw)) == 0 {
+		return raw
+	}
+	var obj map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &obj); err != nil {
+		return raw // JSON array / scalar / form / binary — leave untouched
+	}
+	subj, err := json.Marshal(subject)
+	if err != nil {
+		return raw
+	}
+	for _, k := range billingSubjectKeys {
+		obj[k] = subj
+	}
+	out, err := json.Marshal(obj)
+	if err != nil {
+		return raw
+	}
+	return out
+}
+
+// isSafeSegment reports whether a path segment is safe to forward. It is the ONE segment
+// guard for this package (the billing AND commerce bridges): a segment is safe only if
+// it is non-empty, not "." / "..", and free of any character a downstream router could
+// re-split or re-decode into traversal — slash, backslash, percent-escape (`%2f`/`%2e`,
+// single- or N-encoded), matrix param (`;`), or a control char (incl. null). The router
+// leaves `%2f`/`%2e` UNdecoded in the wildcard param, but the Go http client — and
+// commerce's own router — WILL decode+normalize them downstream, turning
+// `x/..%2fbilling` into `/v1/billing`: a tunnel PAST the allow-list into the money
+// surface. Rejecting `%`/`;` at the segment makes single-, double-, and N-encoded
+// traversal impossible. Billing endpoints / commerce ids are opaque + escape-free, so
+// this never over-blocks. Mirrors console's bearer-proxy pathIsClean.
+func isSafeSegment(s string) bool {
+	if s == "" || s == "." || s == ".." {
+		return false
+	}
+	for _, r := range s {
+		if r == '/' || r == '\\' || r == '%' || r == ';' || unicode.IsControl(r) {
+			return false
+		}
+	}
+	return true
+}
+
+// commerceCreds resolves the commerce base + admin S2S token from server-only env
+// (COMMERCE_URL default the public gateway; COMMERCE_SERVICE_TOKEN sourced from KMS —
+// never a browser value). Same wiring as clients/admin + topup.go's HUSD credit.
+func commerceCreds() (base, token string) {
+	base = strings.TrimRight(getenv("COMMERCE_URL", "https://api.hanzo.ai"), "/")
+	token = getenv("COMMERCE_SERVICE_TOKEN", "")
+	return
+}
+
+// billingData forwards GET|POST /v1/billing/<path> to commerce's /v1/billing/<path>,
+// scoped to the caller's OWN subject. Mirrors GET/POST app/billing/v1/[...path]/route.ts.
+func billingData(s *cloud.Service[state], c *zip.Ctx) error {
+	// IDOR boundary: the subject is the VALIDATED caller's own org/user, never a client
+	// value. requireOwner=true — billing is always org-scoped (a zero-org user has none).
+	cr, ok := resolveCaller(c, true)
+	if !ok {
+		return zip.ErrForbidden("sign in to view billing")
+	}
+
+	method := c.Method()
+	if method != http.MethodGet && method != http.MethodPost {
+		return zip.Errorf(http.StatusMethodNotAllowed, "method not allowed")
+	}
+
+	base, token := commerceCreds()
+	if token == "" {
+		// Honest "not configured" (mirrors the Node route's 501 when COMMERCE_TOKEN
+		// is unset) — the console shows a truthful state, never a fabricated balance.
+		return zip.Errorf(http.StatusNotImplemented, "billing is not configured on this deployment (COMMERCE_SERVICE_TOKEN unset)")
+	}
+
+	sub := strings.Trim(strings.TrimPrefix(c.Fiber().Params("*"), "/"), "/")
+	if sub == "" {
+		return zip.Errorf(http.StatusNotFound, "billing endpoint required")
+	}
+	for _, seg := range strings.Split(sub, "/") {
+		if !isSafeSegment(seg) {
+			return zip.ErrBadRequest("invalid billing path")
+		}
+	}
+	// THE authorization gate. Forwarding is authorization: the request below carries the
+	// admin service token, which satisfies commerce's MayMintMoney. So refuse anything the
+	// console does not actually call — BEFORE the token is attached. Fail closed (404, the
+	// same answer an unrouted path gives, so this leaks no map of the money surface).
+	if !isForwardableBilling(method, sub) {
+		return zip.Errorf(http.StatusNotFound, "not a forwardable billing endpoint")
+	}
+
+	// Scope EVERY request to the caller's OWN subject — query AND write body — so
+	// commerce's per-tenant isolation can never be crossed from the browser. The
+	// subject comes from the ONE rule (ai/object.Payer), keyed on the IAM username
+	// (cr.username = X-User-Name) the gate also keys on — so a top-up credits the
+	// SAME account the gate debits. Keying on cr.name (X-User-Id, a UUID on the
+	// direct-bearer path) would fund an account the gate never reads: the split.
+	subject := account.Payer(account.Credential{Owner: cr.owner, Name: cr.username}).Subject()
+	inQuery, _ := url.ParseQuery(string(c.Fiber().Request().URI().QueryString()))
+	q := scopedBillingSearch(inQuery, subject)
+
+	var body []byte
+	if method == http.MethodPost {
+		body = scopedBillingBody(c.Body(), subject)
+	}
+
+	raw, status, err := commerceDo(c.Context(), base, token, method, "/v1/billing/"+sub, q, cr.owner, body)
+	if err != nil {
+		return zip.Errorf(http.StatusBadGateway, "billing upstream unreachable: %v", err)
+	}
+	// A per-tenant money response must NEVER be cached (a stale balance after a
+	// completion/top-up); commerce answers JSON, so pin JSON + no-store.
+	c.SetHeader("Content-Type", "application/json")
+	c.SetHeader("Cache-Control", "no-store, must-revalidate")
+	return c.Bytes(status, raw)
+}

clients/account/billing_test.go

@@ -1,7 +1,8 @@
-package console
+package account
 
 import (
 	"encoding/json"
+	"github.com/hanzoai/account"
 	"io"
 	"net/http"
 	"net/http/httptest"
@@ -11,22 +12,49 @@ import (
 )
 
 // billing_test.go — the per-tenant billing bridge (billing.go). Proves the tenant
-// scoping that prevents cross-tenant billing reads (the Go port of console2's
+// scoping that prevents cross-tenant billing reads (the Go port of console's
 // billing-scope.test.ts) AND the IDOR-safe handler forwarding.
 
 // ── pure scoping ─────────────────────────────────────────────────────────────
 
+// TestBillingSubject proves the top-up subject is resolved through the ONE rule
+// (ai/object.Payer) — so a top-up credits the SAME account the ai gate debits and
+// the console reads. The signup org bills per-person (matching the gate), which is
+// the whole fix: money and gate land on one account.
 func TestBillingSubject(t *testing.T) {
-	t.Setenv("PERSONAL_BILLING_ORGS", "hanzo")
 	cases := []struct{ org, name, want string }{
-		{"acme", "alice", "acme"},       // dedicated org bills per-ORG
-		{"hanzo", "Dave", "hanzo/dave"}, // personal-billing org bills per-USER (lowercased)
-		{"hanzo", "", "hanzo"},          // personal org, no name → org
-		{"", "x", ""},                   // no org → empty subject
+		{"acme", "alice", "acme"},       // real org: any member bills the ONE org account
+		{"hanzo", "Dave", "hanzo/dave"}, // signup org: each person bills their OWN account
+		{"hanzo", "z", "hanzo/z"},       // another signup person — their own account
+		{"hanzo", "", "hanzo"},          // no name (org-owned principal) → org pool
+		{"Hanzo", "Z", "hanzo/z"},       // folded
+		{"", "x", ""},                   // no org → empty subject (cannot bill)
 	}
 	for _, c := range cases {
-		if got := billingSubject(c.org, c.name); got != c.want {
-			t.Fatalf("billingSubject(%q,%q): want %q, got %q", c.org, c.name, c.want, got)
+		got := account.Payer(account.Credential{Owner: c.org, Name: c.name}).Subject()
+		if got != c.want {
+			t.Fatalf("Payer(%q,%q).Subject(): want %q, got %q", c.org, c.name, c.want, got)
+		}
+	}
+}
+
+// TestBillingSubject_IgnoresLegacyEnv locks that the killed allowlist envs have NO
+// effect: nothing reads them. Set to values that WOULD have flipped every
+// resolution — the subject is unchanged. This is the console/top-up half of the
+// same proof ai carries (one rule, no config), so the view and the gate can never
+// disagree, and the deleted CR env is a genuine no-op.
+func TestBillingSubject_IgnoresLegacyEnv(t *testing.T) {
+	t.Setenv("PERSONAL_BILLING_ORGS", "hanzo,acme") // would have split acme per-user
+	t.Setenv("ORG_BILLING_ORGS", "hanzo")           // would have pooled the signup org
+	cases := []struct{ org, name, want string }{
+		{"hanzo", "z", "hanzo/z"},        // env cannot pool the signup org
+		{"acme", "alice", "acme"},        // env cannot split a real org per-user
+		{"maxpower", "dave", "maxpower"}, // untouched
+	}
+	for _, c := range cases {
+		got := account.Payer(account.Credential{Owner: c.org, Name: c.name}).Subject()
+		if got != c.want {
+			t.Fatalf("legacy env must be ignored: Payer(%q,%q).Subject() want %q, got %q", c.org, c.name, c.want, got)
 		}
 	}
 }
@@ -132,7 +160,6 @@ func TestBilling_ScopesQueryToCallerAndForwards(t *testing.T) {
 	f := &fakeBilling{}
 	t.Setenv("COMMERCE_URL", f.server(t).URL)
 	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
-	t.Setenv("PERSONAL_BILLING_ORGS", "hanzo") // acme is a DEDICATED org → subject "acme"
 	app := mountApp(t, "http://iam.invalid", "", "")
 
 	// alice/acme with a FORGED ?userId=victim & ?org=othercorp: the handler must pin
@@ -165,7 +192,6 @@ func TestBilling_ScopesWriteBodyToCaller(t *testing.T) {
 	f := &fakeBilling{}
 	t.Setenv("COMMERCE_URL", f.server(t).URL)
 	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
-	t.Setenv("PERSONAL_BILLING_ORGS", "hanzo")
 	app := mountApp(t, "http://iam.invalid", "", "")
 
 	// a POST with a forged userId in the body must be overwritten to acme.

clients/account/bridge_mint_test.go

@@ -0,0 +1,257 @@
+package account
+
+import (
+	"net/http"
+	"strings"
+	"testing"
+
+	commercebilling "github.com/hanzoai/commerce/api/billing"
+	commercemid "github.com/hanzoai/commerce/middleware"
+	"github.com/zap-proto/zip"
+)
+
+// bridge_mint_test.go — the privilege-escalation boundary of the /v1/billing/*
+// bridge: an ordinary signed-in ORG user must never reach commerce's money-MINT
+// surface.
+//
+// THE ESCALATION THIS LOCKS OUT. The bridge forwards to commerce with the admin
+// COMMERCE_SERVICE_TOKEN. Commerce gates every mint on
+// MayMintMoney(c) = IsServiceToken(c) || IsSuperAdmin(c) (middleware/platformonly.go)
+// — and the bridge's service token satisfies IsServiceToken. So ANY subpath the
+// bridge forwards is executed by commerce as the PLATFORM, not as the caller.
+// billingData scopes the SUBJECT to the caller's own account, which is exactly the
+// attack rather than a defense: an org user mints to THEMSELVES. Commerce's own
+// gate comment names this: "let ANY org owner self-credit unlimited balance (POST
+// /v1/billing/deposit &c.) → unlimited free inference."
+//
+// Commerce 403s that same org admin when they call it DIRECTLY
+// (TestC1_OrgAdminDeniedOnEveryMintRoute) and mints 201 for the service token
+// (TestC1_ServiceTokenMintsDeposit). The bridge is what converts the former into
+// the latter. The gate therefore has to live HERE, at the point that hands out the
+// token: forwardable subpaths are an ALLOWLIST, and a mint path is not on it.
+//
+// alice is an ordinary org user — X-Org-Id "acme", owner != "admin", NOT a
+// SuperAdmin — i.e. precisely the principal commerce refuses at the front door.
+
+// TestBridge_OrgUserCannotReachMint is the reproduction. Each of these commerce
+// subpaths is PlatformOnly-gated (api/billing/handlers.go: `mintRequired`), meaning
+// possession of the service token IS authority to create spendable balance. None
+// may leave cloud. A request that never reaches commerce cannot mint, so the
+// assertion is twofold: the caller is refused AND upstream saw nothing.
+// mintSurface asks COMMERCE which routes it gates, rather than keeping a copy.
+//
+// The list used to live here by hand under "kept in lockstep with
+// api/billing/handlers.go" — and it had already drifted: 10 paths here against
+// 16 commerce actually gates. A comment cannot hold two lists together. Now
+// commerce DECLARES its gated surface (middleware.Mint records what it gates)
+// and we read that declaration, so a mint route added there is covered here with
+// nobody remembering to do anything.
+//
+// Registration is what populates the registry, so register first, then read.
+func mintSurface(t *testing.T) []commercemid.MintRoute {
+	t.Helper()
+	commercebilling.Route(zip.New(zip.Config{DisableStartupMessage: true}).Group("/v1"))
+
+	var out []commercemid.MintRoute
+	for _, r := range commercemid.MintRoutes() {
+		// Only what THIS bridge can address: it forwards /v1/billing/* alone.
+		if !strings.HasPrefix(r.Path, "/v1/billing/") {
+			continue
+		}
+		// A wildcard segment needs some concrete value to be requestable; which
+		// one is irrelevant, since a refused call never reaches an id.
+		parts := strings.Split(r.Path, "/")
+		for i, seg := range parts {
+			if strings.HasPrefix(seg, ":") || seg == "{}" {
+				parts[i] = "probe"
+			}
+		}
+		r.Path = strings.Join(parts, "/")
+		out = append(out, r)
+	}
+	if len(out) == 0 {
+		t.Fatal("commerce declared no /v1/billing mint routes — the registry is not being populated")
+	}
+	return out
+}
+
+func TestBridge_OrgUserCannotReachMint(t *testing.T) {
+	mintPaths := mintSurface(t)
+	t.Logf("commerce declares %d gated /v1/billing mint routes", len(mintPaths))
+
+	for _, m := range mintPaths {
+		t.Run(m.Method+" "+m.Path, func(t *testing.T) {
+			f := &fakeBilling{}
+			t.Setenv("COMMERCE_URL", f.server(t).URL)
+			t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+			app := mountApp(t, "http://iam.invalid", "", "")
+
+			code, body := callH(t, app, m.Method, m.Path, alice, `{}`)
+
+			// The mint request must NEVER reach commerce: arriving there at all means
+			// it arrived bearing the admin service token, which IS the authority to
+			// mint (MayMintMoney → AuthorizeMint → the ledger write).
+			if f.path != "" {
+				t.Fatalf("ESCALATION: an ordinary org user's %s %s reached commerce at %q "+
+					"carrying %q — the service token that satisfies MayMintMoney. "+
+					"Minted subject=%v amount=%v in org=%q.",
+					m.Method, m.Path, f.path, f.auth, f.body["user"], f.body["amount"], f.org)
+			}
+			if code != http.StatusNotFound {
+				t.Fatalf("%s %s: want 404 (not a forwardable billing endpoint), got %d (%s)",
+					m.Method, m.Path, code, body)
+			}
+		})
+	}
+}
+
+// TestBridge_ConsoleCallsStillForward is the other half of the allowlist: the calls the
+// console ACTUALLY makes must still reach commerce. An allowlist that blocks the product
+// is not a fix, so each entry here is a live console call (cited in billing.go), and this
+// test fails if a future edit narrows the table below the console's real needs.
+func TestBridge_ConsoleCallsStillForward(t *testing.T) {
+	calls := []struct{ method, path, want string }{
+		{http.MethodGet, "/v1/billing/invoices", "/v1/billing/invoices"},
+		{http.MethodGet, "/v1/billing/invoices/inv_123/pdf", "/v1/billing/invoices/inv_123/pdf"},
+		{http.MethodGet, "/v1/billing/subscriptions", "/v1/billing/subscriptions"},
+		{http.MethodGet, "/v1/billing/spend-alerts", "/v1/billing/spend-alerts"},
+		{http.MethodGet, "/v1/billing/payment-config", "/v1/billing/payment-config"},
+		{http.MethodGet, "/v1/billing/plans", "/v1/billing/plans"},
+		{http.MethodGet, "/v1/billing/payouts", "/v1/billing/payouts"},
+		{http.MethodPost, "/v1/billing/subscriptions/sub_1/cancel", "/v1/billing/subscriptions/sub_1/cancel"},
+		{http.MethodPost, "/v1/billing/subscriptions/sub_1/reactivate", "/v1/billing/subscriptions/sub_1/reactivate"},
+		{http.MethodPost, "/v1/billing/payment-methods", "/v1/billing/payment-methods"},
+		{http.MethodPost, "/v1/billing/spend-alerts", "/v1/billing/spend-alerts"},
+		{http.MethodPost, "/v1/billing/topup/token", "/v1/billing/topup/token"},
+	}
+	for _, call := range calls {
+		t.Run(call.method+" "+call.path, func(t *testing.T) {
+			f := &fakeBilling{}
+			t.Setenv("COMMERCE_URL", f.server(t).URL)
+			t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+			app := mountApp(t, "http://iam.invalid", "", "")
+
+			code, body := callH(t, app, call.method, call.path, alice, "{}")
+			if code != http.StatusOK {
+				t.Fatalf("%s %s: want 200 (the console needs this), got %d (%s)",
+					call.method, call.path, code, body)
+			}
+			if f.path != call.want {
+				t.Fatalf("%s %s must forward to %q, got %q", call.method, call.path, call.want, f.path)
+			}
+		})
+	}
+}
+
+// TestBridge_UnlistedPathsAreRefused covers the rest of the money surface — routes that
+// are NOT mint-gated but that the console never calls. The bridge is not a general
+// commerce proxy; least privilege means "only what the product needs", so these 404
+// even though commerce would have served them to a service token.
+func TestBridge_UnlistedPathsAreRefused(t *testing.T) {
+	unlisted := []struct{ method, path string }{
+		{http.MethodPost, "/v1/billing/invoices"},          // CreateInvoice (admin group)
+		{http.MethodPost, "/v1/billing/invoices/i1/pay"},   // PayInvoice
+		{http.MethodPost, "/v1/billing/invoices/i1/void"},  // VoidInvoice
+		{http.MethodPost, "/v1/billing/meters"},            // CreateMeter
+		{http.MethodPost, "/v1/billing/pricing-rules"},     // CreatePricingRule
+		{http.MethodPost, "/v1/billing/withdraw"},          // money OUT
+		{http.MethodPost, "/v1/billing/usage"},             // RecordUsage — the meter itself
+		{http.MethodGet, "/v1/billing/balance/all"},        // every subject's balance
+		{http.MethodGet, "/v1/billing/sbom"},               // OSS payout surface
+		{http.MethodGet, "/v1/billing/oss-payout/summary"}, // OSS payout rollup
+		{http.MethodPost, "/v1/billing/subscriptions"},     // CreateBillingSubscription
+	}
+	for _, u := range unlisted {
+		t.Run(u.method+" "+u.path, func(t *testing.T) {
+			f := &fakeBilling{}
+			t.Setenv("COMMERCE_URL", f.server(t).URL)
+			t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+			app := mountApp(t, "http://iam.invalid", "", "")
+
+			code, _ := callH(t, app, u.method, u.path, alice, "{}")
+			if f.path != "" {
+				t.Fatalf("%s %s is not a console call and must not reach commerce, but upstream saw %q",
+					u.method, u.path, f.path)
+			}
+			if code != http.StatusNotFound {
+				t.Fatalf("%s %s: want 404, got %d", u.method, u.path, code)
+			}
+		})
+	}
+}
+
+// TestBridge_ReadAllowlistIsNotAWriteAllowlist pins the method split. `payouts` is the
+// proof that one method-blind set would be a hole: GET /payouts is a plain read, POST
+// /payouts is `mintRequired` (api/billing/handlers.go). The same string must resolve
+// differently by method, or reading the settlement view would grant minting a payout.
+func TestBridge_ReadAllowlistIsNotAWriteAllowlist(t *testing.T) {
+	if !isForwardableBilling(http.MethodGet, "payouts") {
+		t.Fatal("GET payouts is a live console read and must be forwardable")
+	}
+	if isForwardableBilling(http.MethodPost, "payouts") {
+		t.Fatal("POST payouts is mint-gated in commerce and must NEVER be forwardable")
+	}
+	// A GET-only entry must not leak into POST, and vice-versa.
+	if isForwardableBilling(http.MethodPost, "invoices") {
+		t.Fatal("POST invoices must not inherit the GET entry")
+	}
+	if isForwardableBilling(http.MethodGet, "topup/token") {
+		t.Fatal("GET topup/token must not inherit the POST entry")
+	}
+	// An unknown method fails closed (the router mounts GET+POST only; defense in depth).
+	for _, m := range []string{http.MethodPut, http.MethodPatch, http.MethodDelete, ""} {
+		if isForwardableBilling(m, "balance") {
+			t.Fatalf("method %q must fail closed", m)
+		}
+	}
+	// `{}` matches exactly ONE segment — it can never swallow a path into a mint route.
+	if isForwardableBilling(http.MethodPost, "subscriptions/a/b/cancel") {
+		t.Fatal("{} must match exactly one segment")
+	}
+}
+
+// TestBridge_StoreBridgeCannotReachBilling is the sibling lock. /v1/commerce/* carries the
+// SAME admin token with FULL CRUD, and its own allowlist (commerceStoreHeads) is what keeps
+// it a store proxy. Prove it cannot tunnel into the money surface — a store head that
+// resolved to `billing` would reopen this hole from the other bridge.
+func TestBridge_StoreBridgeCannotReachBilling(t *testing.T) {
+	for _, p := range []string{
+		"/v1/commerce/billing/deposit",
+		"/v1/commerce/billing",
+		"/v1/commerce/checkout",
+		"/v1/commerce/_/commerce/tenants",
+	} {
+		f := &fakeBilling{}
+		t.Setenv("COMMERCE_URL", f.server(t).URL)
+		t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+		app := mountApp(t, "http://iam.invalid", "", "")
+
+		code, _ := callH(t, app, http.MethodPost, p, alice, `{"amount":100000000}`)
+		if f.path != "" {
+			t.Fatalf("store bridge %q must never reach commerce, but upstream saw %q", p, f.path)
+		}
+		if code != http.StatusNotFound {
+			t.Fatalf("store bridge %q: want 404, got %d", p, code)
+		}
+	}
+}
+
+// TestBridge_MintIsRefusedEvenWithForgedSubject proves the refusal does not depend
+// on the subject-pinning. Pinning is an IDOR control, not an authority control: it
+// makes the mint land on the CALLER's own account, which is the attack, not a
+// defense. The path gate must refuse before any of that logic runs.
+func TestBridge_MintIsRefusedEvenWithForgedSubject(t *testing.T) {
+	f := &fakeBilling{}
+	t.Setenv("COMMERCE_URL", f.server(t).URL)
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := mountApp(t, "http://iam.invalid", "", "")
+
+	code, _ := callH(t, app, http.MethodPost, "/v1/billing/deposit", alice,
+		`{"user":"victim","userId":"victim","amount":100000000}`)
+	if f.path != "" {
+		t.Fatalf("ESCALATION: deposit reached commerce at %q with the service token", f.path)
+	}
+	if code != http.StatusNotFound {
+		t.Fatalf("forged-subject deposit: want 404, got %d", code)
+	}
+}

clients/account/commerce.go

@@ -1,4 +1,4 @@
-// commerce.go — the per-tenant STORE data bridge, the Go port of console2's
+// commerce.go — the per-tenant STORE data bridge, the Go port of console's
 // app/commerce/[...path]/route.ts (task #41, the BFF catch-all sweep; the store twin
 // of billing.go). It lets the statically-exported console reach its merchant store at
 // the CANONICAL same-origin /v1/commerce/* (nothing before /v1/): GET|POST|PUT|PATCH|
@@ -15,7 +15,7 @@
 // console namespaces the store under /v1/commerce/* only to keep the generic store
 // heads (product/order/user/store) from colliding with the rest of the /v1 surface;
 // this bridge strips that console-side namespace and forwards to commerce's real bare
-// head — EXACTLY the mapping console2's next.config rewrite already proved live
+// head — EXACTLY the mapping console's next.config rewrite already proved live
 // (`/v1/commerce/:path*` → `/commerce/v1/:path*` → commerce.svc/v1/:path*).
 //
 // WHY A SERVER HANDLER (not a same-origin passthrough). Commerce's store is
@@ -32,20 +32,21 @@
 // (403) BEFORE any commerce call — the exact off-gateway forge principal.Validated
 // closes. Least privilege on the path: only the merchant store heads are reachable, so
 // this bridge can NOT tunnel to /v1/billing (its own subject-scoped bridge), /v1/checkout
-// (the money path), or /v1/_/commerce/tenants (tenant admin) — mirroring console2's
+// (the money path), or /v1/_/commerce/tenants (tenant admin) — mirroring console's
 // proxy-allow.ts allowCommerceSurface.
-package console
+package account
 
 import (
 	"net/http"
 	"net/url"
 	"strings"
 
+	"github.com/hanzoai/cloud"
 	"github.com/zap-proto/zip"
 )
 
 // commerceStoreHeads — the merchant store REST heads reachable through /v1/commerce/*.
-// Kept IDENTICAL to console2's proxy-allow.ts COMMERCE_HEADS (the same defense-in-depth
+// Kept IDENTICAL to console's proxy-allow.ts COMMERCE_HEADS (the same defense-in-depth
 // allow-list the Node /commerce proxy enforced), matching commerce's `rest.New(<kind>{})`
 // route names. Change both together. This is what keeps the bridge a STORE proxy: a head
 // not in this set (billing, checkout, namespace, _) is 404'd before any upstream call, so
@@ -79,7 +80,7 @@ func isCommerceStoreHead(sub string) bool {
 // store surface /v1/<path>, scoped to the caller's OWN org. Mirrors the five method
 // exports of app/commerce/[...path]/route.ts (the store dashboard reads AND writes:
 // create/delete a product, etc. — full CRUD, unlike billing's read-mostly GET|POST).
-func (s *svc) commerceData(c *zip.Ctx) error {
+func commerceData(s *cloud.Service[state], c *zip.Ctx) error {
 	// IDOR boundary: the org is the VALIDATED caller's own, never a client value.
 	// requireOwner=true — the store is always org-scoped (a zero-org user has none).
 	cr, ok := resolveCaller(c, true)

clients/account/commerce_test.go

@@ -1,4 +1,4 @@
-package console
+package account
 
 import (
 	"encoding/json"

clients/account/csrf.go

@@ -0,0 +1,188 @@
+package account
+
+// CSRF protection for the console money-WRITE surface (mint/revoke key, topup,
+// onboard, and the billing/commerce write verbs).
+//
+// THREAT. The forward-perfect money path is the embed same-origin session bridge
+// (middleware_identity.sessionAccessToken): a browser write is authenticated from its
+// httpOnly session COOKIE, which is AMBIENT — a cross-site page's request to our
+// origin carries it too. The bridge's Sec-Fetch-Site check is a NEGATIVE heuristic
+// that passes VACUOUSLY when Origin/Referer/Sec-Fetch-Site are all absent (RED). So a
+// state-changing write gets a POSITIVE control: a token the caller can obtain ONLY by
+// reading a same-origin response (the Same-Origin Policy blocks a cross-site page from
+// reading GET /v1/csrf) and MUST echo in a CUSTOM header (a cross-site simple/
+// form request cannot set X-CSRF-Token without a CORS preflight the server never
+// grants).
+//
+// SCOPE — only the AMBIENT path. A Bearer/Basic-authenticated request is immune to
+// CSRF (a cross-site attacker cannot set the Authorization header), and the gateway
+// path forwards minted identity HEADERS with no browser cookie. requireCSRF therefore
+// enforces ONLY when the request carries NO explicit Authorization/X-Authorization AND
+// a Cookie is present — i.e. exactly the ambient-cookie/embed browser write. Every
+// other caller (API/machine Bearer, gateway-fronted, the header-injected tests) is
+// unaffected. Fail-secure: an ambient write with a missing/invalid token is refused.
+//
+// TOKEN — base64url( ts_be64(8) || mac(16) ), where
+//   mac = KeyedBLAKE3(csrfKey, domain \x00 uid \x00 org \x00 ts)[:16]  (luxfi/crypto).
+// It is BOUND to the validated principal (X-User-Id + X-Org-Id) so a token minted for
+// one identity cannot authorize a write as another, and it EXPIRES after csrfTTL. The
+// key is server-only (KMS-sourced env CONSOLE_CSRF_KEY); no key ⇒ a per-process random
+// key (tokens then reset on restart — the SPA re-fetches on a 403).
+
+import (
+	"crypto/rand"
+	"crypto/subtle"
+	"encoding/base64"
+	"encoding/binary"
+	"encoding/hex"
+	"net/http"
+	"os"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/hanzoai/cloud"
+	"github.com/luxfi/crypto/blake3"
+	luxlog "github.com/luxfi/log"
+	"github.com/zap-proto/zip"
+)
+
+const (
+	csrfDomain    = "hanzo-console-csrf-v1"
+	csrfMACLen    = 16             // 128-bit truncated BLAKE3 MAC — ample for a bound, expiring token
+	csrfTTL       = 12 * time.Hour // token lifetime; SPA re-fetches on expiry/403
+	csrfClockSkew = 120            // seconds of future tolerance
+	csrfTokenLen  = 8 + csrfMACLen // ts || mac
+)
+
+// csrfKeyOnce guards the process-wide CSRF MAC key. It is shared across BOTH account
+// subsystems (account@48 issues GET /v1/csrf; account-bridge@122 verifies the token on
+// the /v1/billing|commerce writes), so a token minted by one verifies on the other —
+// even in the ephemeral (no CONSOLE_CSRF_KEY) case where each Mount would otherwise
+// generate its own random key. Deterministic from CONSOLE_CSRF_KEY (KMS) in prod.
+var (
+	csrfKeyOnce sync.Once
+	csrfKeyVal  []byte
+)
+
+// sharedCSRFKey returns the process-wide keyed-BLAKE3 MAC key, loaded ONCE.
+func sharedCSRFKey(log luxlog.Logger) []byte {
+	csrfKeyOnce.Do(func() { csrfKeyVal = loadCSRFKey(log) })
+	return csrfKeyVal
+}
+
+// loadCSRFKey returns the 32-byte keyed-BLAKE3 MAC key. Prefers the server-only env
+// CONSOLE_CSRF_KEY (KMS-sourced; hex or base64-std, must decode to exactly 32 bytes);
+// otherwise a per-process random key with a WARN (single-replica tolerable — tokens
+// reset on restart, the SPA transparently re-fetches on a 403).
+func loadCSRFKey(log luxlog.Logger) []byte {
+	if raw := strings.TrimSpace(os.Getenv("CONSOLE_CSRF_KEY")); raw != "" {
+		if b, err := hex.DecodeString(raw); err == nil && len(b) == 32 {
+			return b
+		}
+		if b, err := base64.StdEncoding.DecodeString(raw); err == nil && len(b) == 32 {
+			return b
+		}
+		if log != nil {
+			log.Warn("CONSOLE_CSRF_KEY set but not a 32-byte hex/base64 value; using an ephemeral per-process key")
+		}
+	} else if log != nil {
+		log.Warn("CONSOLE_CSRF_KEY unset; using an ephemeral per-process CSRF key (set it from KMS for multi-replica/restart-stable tokens)")
+	}
+	k := make([]byte, 32)
+	if _, err := rand.Read(k); err != nil {
+		// crypto/rand failure is catastrophic; a zero key would be forgeable, so panic.
+		panic("console: cannot generate CSRF key: " + err.Error())
+	}
+	return k
+}
+
+// csrfMAC computes the bound, truncated keyed-BLAKE3 MAC for (uid, org, ts).
+func csrfMAC(s *cloud.Service[state], uid, org string, ts int64) []byte {
+	var msg []byte
+	msg = append(msg, csrfDomain...)
+	msg = append(msg, 0)
+	msg = append(msg, uid...)
+	msg = append(msg, 0)
+	msg = append(msg, org...)
+	msg = append(msg, 0)
+	var t [8]byte
+	binary.BigEndian.PutUint64(t[:], uint64(ts))
+	msg = append(msg, t[:]...)
+	sum, err := blake3.KeyedHash(s.State.csrfKey, msg)
+	if err != nil {
+		// Only errors on a bad key length; loadCSRFKey guarantees 32 bytes.
+		panic("console: CSRF MAC: " + err.Error())
+	}
+	return sum[:csrfMACLen]
+}
+
+// issueCSRF mints a token bound to (uid, org) valid for csrfTTL. Returns the token and
+// its lifetime in seconds.
+func issueCSRF(s *cloud.Service[state], uid, org string) (string, int64) {
+	ts := time.Now().Unix()
+	var out [csrfTokenLen]byte
+	binary.BigEndian.PutUint64(out[:8], uint64(ts))
+	copy(out[8:], csrfMAC(s, uid, org, ts))
+	return base64.RawURLEncoding.EncodeToString(out[:]), int64(csrfTTL / time.Second)
+}
+
+// verifyCSRF checks a token against the CURRENT request's validated (uid, org) and its
+// expiry, in constant time.
+func verifyCSRF(s *cloud.Service[state], token, uid, org string) bool {
+	raw, err := base64.RawURLEncoding.DecodeString(strings.TrimSpace(token))
+	if err != nil || len(raw) != csrfTokenLen {
+		return false
+	}
+	ts := int64(binary.BigEndian.Uint64(raw[:8]))
+	now := time.Now().Unix()
+	if ts > now+csrfClockSkew || now-ts > int64(csrfTTL/time.Second) {
+		return false
+	}
+	return subtle.ConstantTimeCompare(raw[8:], csrfMAC(s, uid, org, ts)) == 1
+}
+
+// ambientCookieAuth reports whether the request is authenticated by an AMBIENT
+// credential (a browser cookie) rather than an explicit one. Only such requests are
+// CSRF-able. Explicit Authorization/X-Authorization (Bearer/Basic) ⇒ not ambient; no
+// Cookie at all (gateway header-injection, the tests) ⇒ not ambient.
+func ambientCookieAuth(c *zip.Ctx) bool {
+	if strings.TrimSpace(c.Header("Authorization")) != "" || strings.TrimSpace(c.Header("X-Authorization")) != "" {
+		return false
+	}
+	return len(c.Fiber().Request().Header.Peek("Cookie")) > 0
+}
+
+// requireCSRF wraps a state-changing handler, enforcing a valid X-CSRF-Token on the
+// ambient-cookie path only (see package note). A validated principal is required for
+// the ambient path to mean anything; the wrapped handler still does its own
+// resolveCaller, so this only ADDS the anti-CSRF gate.
+func requireCSRF(s *cloud.Service[state], next zip.Handler) zip.Handler {
+	return func(c *zip.Ctx) error {
+		if !ambientCookieAuth(c) {
+			return next(c) // Bearer/Basic/gateway/API — not CSRF-able
+		}
+		tok := strings.TrimSpace(c.Header("X-CSRF-Token"))
+		if tok == "" {
+			return zip.ErrForbidden("missing CSRF token (GET /v1/csrf and echo it in X-CSRF-Token)")
+		}
+		if !verifyCSRF(s, tok, strings.TrimSpace(c.User()), strings.TrimSpace(c.Org())) {
+			return zip.ErrForbidden("invalid or expired CSRF token")
+		}
+		return next(c)
+	}
+}
+
+// issueCSRFToken serves GET /v1/csrf: for a VALIDATED caller, a fresh token
+// bound to their identity. no-store so it is never cached by a shared proxy. This is
+// the same-origin endpoint the embedded SPA reads (its response body is unreadable to
+// a cross-site page), then echoes on every money write.
+func issueCSRFToken(s *cloud.Service[state], c *zip.Ctx) error {
+	cr, ok := resolveCaller(c, false) // a zero-org (first-run) user may still need a token
+	if !ok {
+		return zip.ErrForbidden("sign in to obtain a CSRF token")
+	}
+	token, ttl := issueCSRF(s, cr.name, cr.owner)
+	c.Fiber().Set("Cache-Control", "no-store")
+	return c.JSON(http.StatusOK, map[string]any{"csrfToken": token, "expiresIn": ttl})
+}

clients/account/csrf_test.go

@@ -0,0 +1,167 @@
+package account
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/zap-proto/zip"
+)
+
+// req drives one request with arbitrary headers through the mounted app.
+func req(t *testing.T, app *zip.App, method, path string, hdr map[string]string, body string) (int, []byte) {
+	t.Helper()
+	var rdr io.Reader
+	if body != "" {
+		rdr = strings.NewReader(body)
+	}
+	r := httptest.NewRequest(method, path, rdr)
+	if body != "" {
+		r.Header.Set("Content-Type", "application/json")
+	}
+	for k, v := range hdr {
+		r.Header.Set(k, v)
+	}
+	resp, err := app.Fiber().Test(r)
+	if err != nil {
+		t.Fatalf("Test %s %s: %v", method, path, err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	b, _ := io.ReadAll(resp.Body)
+	return resp.StatusCode, b
+}
+
+// csrfToken fetches a CSRF token for (user, org) from the issue endpoint.
+func csrfToken(t *testing.T, app *zip.App, user, org string) string {
+	t.Helper()
+	code, body := req(t, app, http.MethodGet, "/v1/csrf",
+		map[string]string{"X-User-Id": user, "X-Org-Id": org}, "")
+	if code != http.StatusOK {
+		t.Fatalf("GET /v1/csrf: want 200, got %d (%s)", code, body)
+	}
+	var r struct {
+		CsrfToken string `json:"csrfToken"`
+	}
+	mustJSON(t, body, &r)
+	if r.CsrfToken == "" {
+		t.Fatalf("empty csrfToken: %s", body)
+	}
+	return r.CsrfToken
+}
+
+// TestCSRF_AmbientWriteWithoutTokenIsRefused: a cookie-authenticated (ambient) write
+// with no X-CSRF-Token is 403, and IAM is never touched.
+func TestCSRF_AmbientWriteWithoutTokenIsRefused(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	code, _ := req(t, app, http.MethodPost, "/v1/iam/keys", map[string]string{
+		"X-User-Id": "alice", "X-Org-Id": "acme",
+		"Cookie": "iam_access_token=opaque-sid", // ambient credential
+	}, "")
+	if code != http.StatusForbidden {
+		t.Fatalf("ambient write w/o CSRF token: want 403, got %d", code)
+	}
+	if len(f.mintedFor) != 0 {
+		t.Fatalf("IAM mint reached without a CSRF token: %v", f.mintedFor)
+	}
+}
+
+// TestCSRF_AmbientWriteWithValidTokenAllows: same request WITH a valid token mints.
+func TestCSRF_AmbientWriteWithValidTokenAllows(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	tok := csrfToken(t, app, "alice", "acme")
+	code, body := req(t, app, http.MethodPost, "/v1/iam/keys", map[string]string{
+		"X-User-Id": "alice", "X-Org-Id": "acme",
+		"Cookie":       "iam_access_token=opaque-sid",
+		"X-CSRF-Token": tok,
+	}, "")
+	if code != http.StatusOK {
+		t.Fatalf("ambient write with valid CSRF token: want 200, got %d (%s)", code, body)
+	}
+	if len(f.mintedFor) != 1 || f.mintedFor[0] != "acme/alice" {
+		t.Fatalf("mint should target acme/alice: %v", f.mintedFor)
+	}
+}
+
+// TestCSRF_TokenBoundToIdentity: a token minted for alice cannot authorize a write as
+// mallory — the MAC binds (X-User-Id, X-Org-Id).
+func TestCSRF_TokenBoundToIdentity(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	aliceTok := csrfToken(t, app, "alice", "acme")
+	code, _ := req(t, app, http.MethodPost, "/v1/iam/keys", map[string]string{
+		"X-User-Id": "mallory", "X-Org-Id": "acme", // different principal
+		"Cookie":       "iam_access_token=opaque-sid",
+		"X-CSRF-Token": aliceTok, // stolen/replayed token bound to alice
+	}, "")
+	if code != http.StatusForbidden {
+		t.Fatalf("cross-identity CSRF token replay: want 403, got %d", code)
+	}
+	if len(f.mintedFor) != 0 {
+		t.Fatalf("mint reached on a cross-identity token: %v", f.mintedFor)
+	}
+}
+
+// TestCSRF_BearerAuthSkipsCSRF: an explicit Bearer credential is not CSRF-able, so no
+// token is required (API/machine callers unaffected).
+func TestCSRF_BearerAuthSkipsCSRF(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	code, body := req(t, app, http.MethodPost, "/v1/iam/keys", map[string]string{
+		"X-User-Id": "alice", "X-Org-Id": "acme",
+		"Authorization": "Bearer some.jwt.token", // explicit (non-ambient) credential
+		"Cookie":        "iam_access_token=opaque-sid",
+	}, "")
+	if code != http.StatusOK {
+		t.Fatalf("Bearer write should skip CSRF and mint: want 200, got %d (%s)", code, body)
+	}
+	if len(f.mintedFor) != 1 {
+		t.Fatalf("Bearer write should have minted: %v", f.mintedFor)
+	}
+}
+
+// TestRateLimit_PerPrincipalBurstThen429: the money-write cap keys on the VALIDATED
+// principal (un-spoofable), returns 429 past the burst, and a DIFFERENT principal is
+// NOT throttled by the first's flood — and a forged X-Forwarded-For does not reset it.
+func TestRateLimit_PerPrincipalBurstThen429(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	// alice floods, sending a FRESH X-Forwarded-For each request (the old XFF keying
+	// would have reset the bucket every time — it must NOT now).
+	var got429 bool
+	for i := 0; i < keysWriteRatePerMin+5; i++ {
+		code, _ := req(t, app, http.MethodPost, "/v1/iam/keys", map[string]string{
+			"X-User-Id": "alice", "X-Org-Id": "acme",
+			"Authorization":   "Bearer j.w.t",                     // skip CSRF, isolate the limiter
+			"X-Forwarded-For": fmt.Sprintf("203.0.113.%d", i%250), // attacker rotates XFF
+		}, "")
+		if code == 429 {
+			got429 = true
+			break
+		}
+		if code != http.StatusOK {
+			t.Fatalf("req %d: unexpected %d", i, code)
+		}
+	}
+	if !got429 {
+		t.Fatalf("expected 429 after alice's per-principal burst of %d (XFF rotation must not reset it)", keysWriteRatePerMin)
+	}
+
+	// bob (a different validated principal) is unaffected by alice's exhausted bucket.
+	code, body := req(t, app, http.MethodPost, "/v1/iam/keys", map[string]string{
+		"X-User-Id": "bob", "X-Org-Id": "acme",
+		"Authorization": "Bearer j.w.t",
+	}, "")
+	if code != http.StatusOK {
+		t.Fatalf("bob must have his own bucket, not alice's: want 200, got %d (%s)", code, body)
+	}
+}

clients/account/embed.go

@@ -1,5 +1,5 @@
-// embed.go ports console2's app/embed-status/route.ts into the unified binary at
-// GET /v1/console/embed-status (task #41). It answers ONE question for the console's
+// embed.go ports console's app/embed-status/route.ts into the unified binary at
+// GET /v1/embed-status (task #41). It answers ONE question for the console's
 // data-product modules (Content Studio / ERP / Help Center): is this brand's shared
 // embedded app provisioned and reachable, so the module can decide embed-vs-provision
 // panel? A cross-origin browser can't read another origin's status (SOP + CORS), so
@@ -8,8 +8,8 @@
 // TWO real jobs (why it is a handler, not a vanishing proxy):
 //
 //   - ENTITLEMENT (server-authoritative). cms/erp/help are each a SINGLE shared
-//     per-BRAND instance, so only a member of the owning brand org — or a global
-//     admin — may frame them; a customer org gets the honest provision panel, never
+//     per-BRAND instance, so only a member of the owning brand org — or a
+//     SuperAdmin — may frame them; a customer org gets the honest provision panel, never
 //     a cross-tenant frame. The caller's org is the VALIDATED X-Org-Id (never a
 //     browser claim); the owning org is the deployment brand.
 //
@@ -18,7 +18,7 @@
 //     {cms,erp,help}. There is NO client-controlled host in the target at all — a
 //     forged Host header can never steer this into probing an arbitrary origin
 //     (strictly tighter than route.ts, which clamped a client Host).
-package console
+package account
 
 import (
 	"context"
@@ -26,6 +26,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/hanzoai/cloud"
 	"github.com/zap-proto/zip"
 )
 
@@ -85,9 +86,9 @@ type embedStatusResp struct {
 // Mount uses the real, time-boxed probe.
 var reachProbe = liveReachProbe
 
-// embedStatus is GET /v1/console/embed-status?app=cms|erp|help. Mirrors
+// embedStatus is GET /v1/embed-status?app=cms|erp|help. Mirrors
 // GET app/embed-status/route.ts.
-func (s *svc) embedStatus(c *zip.Ctx) error {
+func embedStatus(s *cloud.Service[state], c *zip.Ctx) error {
 	cr, ok := resolveCaller(c, false) // validated; a customer org (owner set) is fine
 	if !ok {
 		return zip.ErrForbidden("sign in to continue")
@@ -98,15 +99,15 @@ func (s *svc) embedStatus(c *zip.Ctx) error {
 		return zip.ErrBadRequest("unknown embed app")
 	}
 
-	origin := "https://" + app + "." + embedBrandDomain(s.brand)
+	origin := "https://" + app + "." + embedBrandDomain(s.Brand)
 	embedURL := origin + landing
 
 	// SERVER-SIDE entitlement gate: a brand-owned app frames only for a member of the
-	// owning brand org (cr.owner == deps.Brand) or a global admin. A non-entitled
+	// owning brand org (cr.owner == deps.Brand) or a SuperAdmin. A non-entitled
 	// caller NEVER receives the embed URL and we don't even probe — the module shows
 	// the provision panel. This is the authoritative gate (the client check only
 	// avoids a flash).
-	entitled := (cr.owner != "" && cr.owner == strings.ToLower(strings.TrimSpace(s.brand))) || c.IsAdmin()
+	entitled := (cr.owner != "" && cr.owner == strings.ToLower(strings.TrimSpace(s.Brand))) || c.IsAdmin()
 	if !entitled {
 		return c.JSON(http.StatusOK, embedStatusResp{App: app, Origin: origin, EmbedURL: "", Reachable: false, Entitled: false, Phase: "not-entitled"})
 	}

clients/account/embed_test.go

@@ -1,27 +1,21 @@
-package console
+package account
 
 import (
 	"context"
 	"net/http"
 	"testing"
 
-	"github.com/hanzoai/cloud"
-	luxlog "github.com/luxfi/log"
 	"github.com/zap-proto/zip"
 )
 
-// mountBrand mounts the console surface for a given deployment brand (the embed
+// mountBrand mounts the account surface for a given deployment brand (the embed
 // entitlement + app-domain derivation are brand-scoped). IAM is unwired — embed-status
 // does not use the confidential client.
 func mountBrand(t *testing.T, brand string) *zip.App {
 	t.Helper()
 	t.Setenv("IAM_MINT_CLIENT_ID", "")
 	t.Setenv("IAM_MINT_CLIENT_SECRET", "")
-	app := zip.New(zip.Config{Logger: luxlog.New("test")})
-	if err := Mount(app, cloud.Deps{Logger: luxlog.New("test"), Brand: brand}); err != nil {
-		t.Fatalf("Mount(%s): %v", brand, err)
-	}
-	return app
+	return mountBoth(t, brand)
 }
 
 // stubProbe swaps the reachability probe for the duration of a test, recording how
@@ -38,7 +32,7 @@ func stubProbe(t *testing.T, up bool) *int {
 func TestEmbedStatus_RequiresValidatedPrincipal(t *testing.T) {
 	stubProbe(t, true)
 	app := mountBrand(t, "hanzo")
-	code, _ := callH(t, app, http.MethodGet, "/v1/console/embed-status?app=cms", nil, "")
+	code, _ := callH(t, app, http.MethodGet, "/v1/embed-status?app=cms", nil, "")
 	if code != http.StatusForbidden {
 		t.Fatalf("no principal: want 403, got %d", code)
 	}
@@ -47,7 +41,7 @@ func TestEmbedStatus_RequiresValidatedPrincipal(t *testing.T) {
 func TestEmbedStatus_UnknownApp_400(t *testing.T) {
 	stubProbe(t, true)
 	app := mountBrand(t, "hanzo")
-	code, _ := callH(t, app, http.MethodGet, "/v1/console/embed-status?app=nope",
+	code, _ := callH(t, app, http.MethodGet, "/v1/embed-status?app=nope",
 		map[string]string{"X-User-Id": "alice", "X-Org-Id": "hanzo"}, "")
 	if code != http.StatusBadRequest {
 		t.Fatalf("unknown app: want 400, got %d", code)
@@ -58,7 +52,7 @@ func TestEmbedStatus_BrandMemberEntitled_Reachable(t *testing.T) {
 	calls := stubProbe(t, true)
 	app := mountBrand(t, "hanzo")
 	// A member of the owning brand org (hanzo) is entitled; the probe says up.
-	code, body := callH(t, app, http.MethodGet, "/v1/console/embed-status?app=cms",
+	code, body := callH(t, app, http.MethodGet, "/v1/embed-status?app=cms",
 		map[string]string{"X-User-Id": "z", "X-Org-Id": "hanzo"}, "")
 	if code != http.StatusOK {
 		t.Fatalf("brand member: want 200, got %d (%s)", code, body)
@@ -76,12 +70,12 @@ func TestEmbedStatus_BrandMemberEntitled_Reachable(t *testing.T) {
 	}
 }
 
-func TestEmbedStatus_GlobalAdminEntitled(t *testing.T) {
+func TestEmbedStatus_SuperAdminEntitled(t *testing.T) {
 	stubProbe(t, false)
 	app := mountBrand(t, "hanzo")
-	// A global admin from a DIFFERENT org is still entitled (isGlobalAdmin bypass);
+	// A SuperAdmin from a DIFFERENT org is still entitled (isSuperAdmin bypass);
 	// the probe says down → not-provisioned but entitled with the embed URL.
-	code, body := callH(t, app, http.MethodGet, "/v1/console/embed-status?app=erp",
+	code, body := callH(t, app, http.MethodGet, "/v1/embed-status?app=erp",
 		map[string]string{"X-User-Id": "root", "X-Org-Id": "acme", "X-User-IsAdmin": "true"}, "")
 	if code != http.StatusOK {
 		t.Fatalf("admin: want 200, got %d", code)
@@ -98,7 +92,7 @@ func TestEmbedStatus_CustomerOrgNotEntitled_NotProbed(t *testing.T) {
 	app := mountBrand(t, "hanzo")
 	// A customer org (not the brand, not admin) is NOT entitled: no embed URL, no
 	// probe, honest not-entitled phase — never a cross-tenant frame.
-	code, body := callH(t, app, http.MethodGet, "/v1/console/embed-status?app=help",
+	code, body := callH(t, app, http.MethodGet, "/v1/embed-status?app=help",
 		map[string]string{"X-User-Id": "alice", "X-Org-Id": "acme"}, "")
 	if code != http.StatusOK {
 		t.Fatalf("customer: want 200, got %d", code)
@@ -117,7 +111,7 @@ func TestEmbedStatus_BrandDomainPerBrand(t *testing.T) {
 	stubProbe(t, true)
 	// lux apps live on lux.cloud (the app-hosting domain), NOT lux.network.
 	app := mountBrand(t, "lux")
-	code, body := callH(t, app, http.MethodGet, "/v1/console/embed-status?app=cms",
+	code, body := callH(t, app, http.MethodGet, "/v1/embed-status?app=cms",
 		map[string]string{"X-User-Id": "z", "X-Org-Id": "lux"}, "")
 	if code != http.StatusOK {
 		t.Fatalf("lux brand member: want 200, got %d", code)

clients/account/iam.go

@@ -1,9 +1,9 @@
 // iam.go is the ONE HTTP path from the console subsystem to Hanzo IAM, acting as
 // the confidential first-party `hanzo-console` client (client_secret_basic). It
-// ports the privileged IAM primitives that console2's server-only
+// ports the privileged IAM primitives that console's server-only
 // src/lib/server/identity.ts drove — mint/revoke/get the per-user `hk-` key and
 // create/read/update an organization — so those standalone Next server routes can
-// be retired and console2 statically exported (task #41, "True 1-binary FE").
+// be retired and console statically exported (task #41, "True 1-binary FE").
 //
 // WHY A CONFIDENTIAL CLIENT (and not the caller's own token). These ops are
 // privileged: `mint-user-keys` writes a user's AccessKey, `add-organization`
@@ -19,7 +19,7 @@
 // sourced from KMS by the deployment), never a NEXT_PUBLIC value and never the
 // browser. When they are unset the subsystem is honestly "not configured" (501),
 // exactly as identity.ts's mintConfigured() gate behaved — no fabricated key/org.
-package console
+package account
 
 import (
 	"context"
@@ -140,7 +140,7 @@ type userKey struct {
 }
 
 // getUserKey reads a user's CURRENT `hk-` key AUTHORITATIVELY from IAM (get-user).
-// The session claim can lag a freshly-minted key (it returns '') — so GET /keys
+// The session claim can lag a freshly-minted key (it returns ”) — so GET /keys
 // must read IAM, not the claim (the "key never listed" bug identity.ts documents).
 // `id` is the `<owner>/<name>` composite IAM parses.
 func (c *iamClient) getUserKey(ctx context.Context, id string) (userKey, error) {

clients/account/onboarding.go

@@ -1,5 +1,5 @@
 // onboarding.go — PURE org-naming + reserved-name policy, no transport/IAM. A
-// faithful Go port of console2's src/lib/server/onboarding.ts, decomplected from
+// faithful Go port of console's src/lib/server/onboarding.ts, decomplected from
 // the handler so the naming rules are one testable thing (the route does the IAM
 // calls; this decides the slug). Two concerns:
 //
@@ -9,7 +9,7 @@
 //     owners (admin/built-in/app) and the brand/staff orgs (hanzo/lux/zoo/pars),
 //     which the OrgGate routes to the admin host. Creating one would collide with
 //     a staff tenant or a system principal.
-package console
+package account
 
 import "strings"
 

clients/account/onboarding_test.go

@@ -1,16 +1,16 @@
-package console
+package account
 
 import "testing"
 
 func TestSlugifyOrg(t *testing.T) {
 	cases := map[string]string{
-		"Acme Rockets":     "acme-rockets",
+		"Acme Rockets":      "acme-rockets",
 		"  Hello, World!  ": "hello-world",
-		"UPPER_case-123":   "upper-case-123",
-		"多 bytes 混":        "bytes", // non-ASCII runes act as separators (slug is ASCII)
-		"---":              "",
-		"":                 "",
-		"a.b.c":            "a-b-c",
+		"UPPER_case-123":    "upper-case-123",
+		"多 bytes 混":         "bytes", // non-ASCII runes act as separators (slug is ASCII)
+		"---":               "",
+		"":                  "",
+		"a.b.c":             "a-b-c",
 	}
 	for in, want := range cases {
 		if got := slugifyOrg(in); got != want {

clients/account/ratelimit.go

@@ -0,0 +1,115 @@
+package account
+
+// Per-IP rate limiting for the abuse-sensitive console write routes (hk- key
+// mint/rotate/revoke, HUSD wallet top-up). This is DISTINCT from commerce's spend-cap
+// (ScopeRateLimit): it caps request FREQUENCY per client IP to blunt brute-force /
+// enumeration / resource-exhaustion, restoring the edge protection cloud loses when a
+// caller reaches it DIRECTLY (bypassing the gateway/ingress limiter) on the money path.
+//
+// A token bucket per IP: `perMin` tokens refilled continuously, burst == perMin. In
+// memory (cloud is single-replica for this surface); multi-replica would be a per-
+// replica soft limit — acceptable defense-in-depth, not a hard global quota. Idle
+// buckets are evicted lazily so the map cannot grow without bound.
+
+import (
+	"net"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/hanzoai/cloud"
+	"github.com/zap-proto/zip"
+)
+
+type tokenBucket struct {
+	tokens float64
+	last   time.Time
+}
+
+type rateLimiter struct {
+	mu      sync.Mutex
+	buckets map[string]*tokenBucket
+	perSec  float64
+	burst   float64
+	ttl     time.Duration // evict buckets idle longer than this
+	lastGC  time.Time
+}
+
+// newRateLimiter builds a limiter allowing `perMin` requests/minute per IP (burst ==
+// perMin). perMin<=0 disables limiting (allow always).
+func newRateLimiter(perMin int) *rateLimiter {
+	return &rateLimiter{
+		buckets: map[string]*tokenBucket{},
+		perSec:  float64(perMin) / 60.0,
+		burst:   float64(perMin),
+		ttl:     10 * time.Minute,
+		lastGC:  time.Now(),
+	}
+}
+
+// allow reports whether a request from key (IP) may proceed, consuming one token.
+func (r *rateLimiter) allow(key string) bool {
+	if r.perSec <= 0 {
+		return true
+	}
+	now := time.Now()
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	if now.Sub(r.lastGC) > r.ttl {
+		for k, b := range r.buckets {
+			if now.Sub(b.last) > r.ttl {
+				delete(r.buckets, k)
+			}
+		}
+		r.lastGC = now
+	}
+
+	b := r.buckets[key]
+	if b == nil {
+		b = &tokenBucket{tokens: r.burst, last: now}
+		r.buckets[key] = b
+	}
+	// Refill.
+	b.tokens += now.Sub(b.last).Seconds() * r.perSec
+	if b.tokens > r.burst {
+		b.tokens = r.burst
+	}
+	b.last = now
+	if b.tokens < 1 {
+		return false
+	}
+	b.tokens--
+	return true
+}
+
+// rateKey resolves the un-spoofable key to limit on. These are all POST-AUTH money-
+// write routes, so the primary key is the VALIDATED principal (X-Org-Id/X-User-Id,
+// minted by SanitizeIdentity from a verified JWT — a caller cannot forge it). This is
+// deliberately NOT X-Forwarded-For: the limiter exists for the OFF-GATEWAY path where
+// nothing trusted stamps XFF, so keying on a client-settable XFF would let an attacker
+// send a fresh value per request and reset the bucket at will (RED). An unauthenticated
+// request (which the handler 403s anyway) has no principal, so it falls back to the
+// SOCKET peer address (c.Fiber().IP() — the L4 RemoteAddr, the real attacker on the
+// direct-to-pod path), never a header.
+func rateKey(c *zip.Ctx) string {
+	if uid := strings.TrimSpace(c.User()); uid != "" {
+		return "p:" + strings.TrimSpace(c.Org()) + "/" + uid
+	}
+	ip := c.Fiber().IP()
+	if host, _, err := net.SplitHostPort(ip); err == nil {
+		ip = host
+	}
+	return "a:" + ip
+}
+
+// rateLimit wraps a handler, refusing 429 when the caller (validated principal, else
+// socket peer) exceeds rl.
+func rateLimit(s *cloud.Service[state], rl *rateLimiter, next zip.Handler) zip.Handler {
+	return func(c *zip.Ctx) error {
+		if !rl.allow(rateKey(c)) {
+			return zip.Errorf(429, "rate limit exceeded; retry shortly")
+		}
+		return next(c)
+	}
+}

clients/account/topup.go

@@ -1,5 +1,5 @@
-// topup.go ports console2's app/billing/v1/topup/wallet/route.ts into the unified
-// binary at POST /v1/console/topup/wallet (task #41). It is the verify-and-record
+// topup.go ports console's app/billing/v1/topup/wallet/route.ts into the unified
+// binary at POST /v1/commerce/topup/wallet (task #41). It is the verify-and-record
 // seam for an HUSD wallet top-up: the browser sends an HUSD ERC-20 transfer to the
 // treasury and posts the tx hash here; this handler reads the receipt from the Hanzo
 // EVM, confirms it is a mined, successful HUSD Transfer(from → treasury, value),
@@ -23,7 +23,7 @@
 // Honest failure (no fabricated credit, ever): HUSD/treasury unconfigured
 // (greenfield — HUSD not yet deployed) → 501; a missing/failed/non-HUSD-to-treasury
 // tx → 400; the chain or commerce unreachable → 502.
-package console
+package account
 
 import (
 	"bytes"
@@ -37,10 +37,27 @@ import (
 	"os"
 	"regexp"
 	"strings"
+	"time"
 
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/commerceinproc"
 	"github.com/zap-proto/zip"
 )
 
+// httpClient is the shared outbound client for the account subsystem's plain-HTTP seams
+// (EVM JSON-RPC, commerce billing/store S2S). Small JSON envelopes, bounded reads; 15s
+// is generous for an in-cluster / same-region hop. (Owned here — the S2S transport home
+// — since the former waitlist.go was retired with the /v1/console namespace.)
+var httpClient = &http.Client{Timeout: 15 * time.Second}
+
+// commerceHTTP is the client for the commerce S2S seam ONLY (commerceDo). Separate
+// from httpClient (which also dials EVM JSON-RPC) so that — when commerce is folded
+// in-process (task #111) — commerce calls dispatch to the in-process handler via
+// commerceinproc's self-routing transport (no socket to the standalone), while the
+// HUSD chain RPC keeps going over the real network. Off the co-resident path it is a
+// plain HTTP client, exactly like before.
+var commerceHTTP = commerceinproc.Client(15 * time.Second)
+
 // transferTopic is keccak256("Transfer(address,address,uint256)") — the ERC-20
 // Transfer event signature, topics[0] of every transfer log. A universally-fixed
 // constant (no need to hash at runtime).
@@ -69,7 +86,7 @@ type topupConfig struct {
 }
 
 func loadTopupConfig() topupConfig {
-	chainID := int64(36900)
+	chainID := int64(36963)
 	if v := strings.TrimSpace(os.Getenv("HANZO_CHAIN_ID")); v != "" {
 		if n, ok := new(big.Int).SetString(v, 10); ok {
 			chainID = n.Int64()
@@ -105,7 +122,7 @@ type walletTopupResp struct {
 
 // walletTopup verifies a sent HUSD transfer on-chain and credits the caller's org.
 // Mirrors POST app/billing/v1/topup/wallet/route.ts.
-func (s *svc) walletTopup(c *zip.Ctx) error {
+func walletTopup(s *cloud.Service[state], c *zip.Ctx) error {
 	cfg := loadTopupConfig()
 	// Greenfield gate: no HUSD contract / treasury ⇒ honest "not configured yet".
 	if !cfg.configured() {
@@ -343,7 +360,7 @@ func commerceDo(ctx context.Context, base, token, method, path string, q url.Val
 	if org != "" {
 		req.Header.Set("X-Org-Id", org)
 	}
-	resp, err := httpClient.Do(req)
+	resp, err := commerceHTTP.Do(req)
 	if err != nil {
 		return nil, 0, fmt.Errorf("commerce unreachable: %w", err)
 	}

clients/account/topup_test.go

@@ -1,4 +1,4 @@
-package console
+package account
 
 import (
 	"encoding/json"
@@ -109,7 +109,7 @@ var alice = map[string]string{"X-User-Id": "alice", "X-Org-Id": "acme"}
 func TestTopup_NotConfigured_501(t *testing.T) {
 	setTopupEnv(t, "", "", "http://rpc.invalid", "http://commerce.invalid")
 	app := mountBrand(t, "hanzo")
-	code, _ := callH(t, app, http.MethodPost, "/v1/console/topup/wallet", alice, `{"txHash":"`+tTxHash+`"}`)
+	code, _ := callH(t, app, http.MethodPost, "/v1/commerce/topup/wallet", alice, `{"txHash":"`+tTxHash+`"}`)
 	if code != http.StatusNotImplemented {
 		t.Fatalf("HUSD unconfigured: want 501, got %d", code)
 	}
@@ -120,7 +120,7 @@ func TestTopup_RequiresValidatedPrincipal(t *testing.T) {
 	com := &fakeCommerce{}
 	setTopupEnv(t, tHusd, tTreasury, rpc.server(t).URL, com.server(t).URL)
 	app := mountBrand(t, "hanzo")
-	code, _ := callH(t, app, http.MethodPost, "/v1/console/topup/wallet", nil, `{"txHash":"`+tTxHash+`"}`)
+	code, _ := callH(t, app, http.MethodPost, "/v1/commerce/topup/wallet", nil, `{"txHash":"`+tTxHash+`"}`)
 	if code != http.StatusForbidden {
 		t.Fatalf("no principal: want 403, got %d", code)
 	}
@@ -131,7 +131,7 @@ func TestTopup_BadTxHash_400(t *testing.T) {
 	com := &fakeCommerce{}
 	setTopupEnv(t, tHusd, tTreasury, rpc.server(t).URL, com.server(t).URL)
 	app := mountBrand(t, "hanzo")
-	code, _ := callH(t, app, http.MethodPost, "/v1/console/topup/wallet", alice, `{"txHash":"0xnothex"}`)
+	code, _ := callH(t, app, http.MethodPost, "/v1/commerce/topup/wallet", alice, `{"txHash":"0xnothex"}`)
 	if code != http.StatusBadRequest {
 		t.Fatalf("bad txHash: want 400, got %d", code)
 	}
@@ -143,7 +143,7 @@ func TestTopup_HappyPath_VerifiesAndCredits(t *testing.T) {
 	setTopupEnv(t, tHusd, tTreasury, rpc.server(t).URL, com.server(t).URL)
 	app := mountBrand(t, "hanzo")
 
-	code, body := callH(t, app, http.MethodPost, "/v1/console/topup/wallet", alice,
+	code, body := callH(t, app, http.MethodPost, "/v1/commerce/topup/wallet", alice,
 		`{"txHash":"`+tTxHash+`","fromAddress":"`+tSender+`"}`)
 	if code != http.StatusOK {
 		t.Fatalf("topup: want 200, got %d (%s)", code, body)
@@ -180,7 +180,7 @@ func TestTopup_IDOR_CreditsCallerNotBodyUserId(t *testing.T) {
 
 	// The body tries to credit "victim/root"; the handler MUST ignore it and credit
 	// the validated caller (acme/alice).
-	code, _ := callH(t, app, http.MethodPost, "/v1/console/topup/wallet", alice,
+	code, _ := callH(t, app, http.MethodPost, "/v1/commerce/topup/wallet", alice,
 		`{"txHash":"`+tTxHash+`","userId":"victim/root"}`)
 	if code != http.StatusOK {
 		t.Fatalf("topup: want 200, got %d", code)
@@ -195,7 +195,7 @@ func TestTopup_NotMined_400(t *testing.T) {
 	com := &fakeCommerce{}
 	setTopupEnv(t, tHusd, tTreasury, rpc.server(t).URL, com.server(t).URL)
 	app := mountBrand(t, "hanzo")
-	code, _ := callH(t, app, http.MethodPost, "/v1/console/topup/wallet", alice, `{"txHash":"`+tTxHash+`"}`)
+	code, _ := callH(t, app, http.MethodPost, "/v1/commerce/topup/wallet", alice, `{"txHash":"`+tTxHash+`"}`)
 	if code != http.StatusBadRequest {
 		t.Fatalf("not mined: want 400, got %d", code)
 	}
@@ -209,7 +209,7 @@ func TestTopup_FailedTx_400(t *testing.T) {
 	com := &fakeCommerce{}
 	setTopupEnv(t, tHusd, tTreasury, rpc.server(t).URL, com.server(t).URL)
 	app := mountBrand(t, "hanzo")
-	code, _ := callH(t, app, http.MethodPost, "/v1/console/topup/wallet", alice, `{"txHash":"`+tTxHash+`"}`)
+	code, _ := callH(t, app, http.MethodPost, "/v1/commerce/topup/wallet", alice, `{"txHash":"`+tTxHash+`"}`)
 	if code != http.StatusBadRequest {
 		t.Fatalf("failed tx: want 400, got %d", code)
 	}
@@ -221,7 +221,7 @@ func TestTopup_NoTransferToTreasury_400(t *testing.T) {
 	com := &fakeCommerce{}
 	setTopupEnv(t, tHusd, tTreasury, rpc.server(t).URL, com.server(t).URL)
 	app := mountBrand(t, "hanzo")
-	code, _ := callH(t, app, http.MethodPost, "/v1/console/topup/wallet", alice, `{"txHash":"`+tTxHash+`"}`)
+	code, _ := callH(t, app, http.MethodPost, "/v1/commerce/topup/wallet", alice, `{"txHash":"`+tTxHash+`"}`)
 	if code != http.StatusBadRequest {
 		t.Fatalf("non-treasury transfer: want 400, got %d", code)
 	}
@@ -233,7 +233,7 @@ func TestTopup_SenderMismatch_400(t *testing.T) {
 	setTopupEnv(t, tHusd, tTreasury, rpc.server(t).URL, com.server(t).URL)
 	app := mountBrand(t, "hanzo")
 	// Claims a different fromAddress than the on-chain sender → rejected.
-	code, _ := callH(t, app, http.MethodPost, "/v1/console/topup/wallet", alice,
+	code, _ := callH(t, app, http.MethodPost, "/v1/commerce/topup/wallet", alice,
 		`{"txHash":"`+tTxHash+`","fromAddress":"`+tOther+`"}`)
 	if code != http.StatusBadRequest {
 		t.Fatalf("sender mismatch: want 400, got %d", code)

clients/admin/admin.go

@@ -1,28 +1,22 @@
-// Package admin mounts the god-mode admin surface (/v1/admin/*) the Hanzo
-// Admin Console (admin.hanzo.ai, apps/operator) calls, per the api.ts contract.
+// Package admin mounts the god-mode admin surface (/v1/admin/*) the Hanzo Admin Console
+// (admin.hanzo.ai, apps/operator) calls, per the api.ts contract.
 //
-// It is an AGGREGATOR, not a new store: identity (orgs/users/roles/applications/
-// audit/me) is read from IAM, the money panels (spend/tokens/credits) from
-// commerce, and System Health from o11y — every one a real upstream, none fused
-// into this binary (see subsystems.go). The facade fans out over HTTP exactly
-// like o11ysvc / productsvc: it holds no business logic, it shapes the reads into
-// the /v1 envelope { status, msg, data, data2 } the operator's transport
-// decodes (get<T> reads data; getList<T> reads data + data2 total).
+// It is an AGGREGATOR, not a new store: identity (orgs/users/roles/applications/audit/me)
+// is read from IAM, the money panels (spend/tokens/credits) from commerce, and System
+// Health from o11y — every one a real upstream. The facade fans out over HTTP, shaping
+// the reads into the /v1 envelope { status, msg, data, data2 } the operator's transport
+// decodes.
 //
-// SECURITY — every route is GLOBAL-ADMIN ONLY, fail-closed. The gate is the
-// SAME predicate the rest of cloud uses: c.IsAdmin(), which after SanitizeIdentity
-// (serve.go) is true ONLY for a JWT-validated principal whose org is the admin org
-// (owner == AdminOrg — IAM's IsGlobalAdmin), matching the gateway's admin-guard.
-// No principal → 403; a tenant-admin (owner != AdminOrg) → 403; a forged
-// X-User-IsAdmin never survives ingress. admin adds no service credential to
-// the IAM fan-out — it replays the caller's own cookie/bearer, so it can never
-// read more than the caller already could, and IAM re-checks IsGlobalAdmin too.
+// The subsystem is decomposed into a shared kernel (clients/admin/core) plus one package
+// per handler domain (audit/customer/revenue/finance). This file is the Mount: it builds
+// the ONE core.State from Deps, then registers each domain's routes alongside the
+// top-level reads (me/overview/orgs/users/usage/roles/applications/products/compute/o11y/
+// analytics/bases + the flags/waitlist control plane).
 //
-// Panels with no in-binary feed yet (the Usage & Costs timeseries + per-product
-// breakdown live in insights/datastore; the product/workload registry + infra
-// tiles live in platform.hanzo.ai / the operator inventory) return the real,
-// honest empty state — never a fabricated number. The operator UI renders those
-// as an em-dash / empty table by design.
+// SECURITY — TWO tiers off ONE identity predicate, both fail-closed. PLATFORM routes are
+// SuperAdmin ONLY (core.Guard). ORG-SCOPED routes (me/overview/orgs/users/usage/analytics/
+// bases) are core.GuardScoped: a SuperAdmin sees EVERY tenant; any other validated admin
+// caller is HARD-limited to their OWN org subtree by core.ResolveScope/ScopedOrgs.
 package admin
 
 import (
@@ -36,166 +30,141 @@ import (
 	"time"
 
 	"github.com/hanzoai/cloud"
-	"github.com/hanzoai/cloud/audit"
+	"github.com/hanzoai/cloud/clients/admin/audit"
+	"github.com/hanzoai/cloud/clients/admin/commerce"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/hanzoai/cloud/clients/admin/customer"
+	"github.com/hanzoai/cloud/clients/admin/digitalocean"
+	"github.com/hanzoai/cloud/clients/admin/finance"
+	"github.com/hanzoai/cloud/clients/admin/health"
+	"github.com/hanzoai/cloud/clients/admin/iam"
+	"github.com/hanzoai/cloud/clients/admin/revenue"
+	"github.com/hanzoai/cloud/clients/commerceinproc"
+	"github.com/hanzoai/cloud/clients/principal"
 	"github.com/zap-proto/zip"
 )
 
-// svc holds the resolved upstream clients + the admin org for this deployment.
-type svc struct {
-	iam      *iamClient
-	commerce *commerceClient
-	health   *healthClient
-	do       *doClient
-	adminOrg string
-	// auditStore is cloud's OWN tamper-evident audit store (nil when unconfigured,
-	// in which case /v1/admin/audit falls back to the IAM get-records proxy). Serve
-	// builds it and hands it over via deps.Audit. See audit.go.
-	auditStore *audit.Recorder
-}
-
-// Mount registers the /v1/admin/* surface on app. Every handler gates on
-// c.IsAdmin() first (global-admin only), then aggregates real upstream data.
+// Mount registers the /v1/admin/* surface on app. Every handler gates on c.IsAdmin()
+// first (via core.Guard/GuardScoped), then aggregates real upstream data.
+//
+// The state is built from Deps fields NOT on cloud.Base (deps.Audit, deps.IAMIssuer), so
+// it constructs the cloud.Service value directly (cloud.NewBase + &cloud.Service[core.State]{…})
+// rather than via cloud.Mount.
 func Mount(app *zip.App, deps cloud.Deps) error {
 	if app == nil {
 		return fmt.Errorf("admin.Mount: nil zip.App")
 	}
-	logger := deps.Logger
-	if logger == nil {
+	if deps.Logger == nil {
 		return fmt.Errorf("admin.Mount: nil deps.Logger")
 	}
-	logger = logger.New("subsystem", "admin")
-
-	s := &svc{
-		iam:        newIAMClient(iamBase(deps)),
-		commerce:   newCommerceClient(os.Getenv("CLOUD_COMMERCE_HTTP_URL"), os.Getenv("COMMERCE_SERVICE_TOKEN")),
-		health:     newHealthClient(o11yHealthURL()),
-		do:         newDOClient(doTokenFromEnv()),
-		adminOrg:   adminOrgOf(deps),
-		auditStore: deps.Audit,
+	b := cloud.NewBase(deps, "admin")
+	s := &cloud.Service[core.State]{
+		Base: b,
+		State: core.State{
+			IAM:        iam.New(iamBase(deps)),
+			Commerce:   commerce.New(commerceinproc.BaseURL(os.Getenv("CLOUD_COMMERCE_HTTP_URL")), os.Getenv("COMMERCE_SERVICE_TOKEN")),
+			Health:     health.New(o11yHealthURL()),
+			DO:         digitalocean.New(doTokenFromEnv()),
+			AdminOrg:   adminOrgOf(deps),
+			AuditStore: deps.Audit,
+		},
 	}
 
-	app.Get("/v1/admin/me", s.guard(s.me))
-	app.Get("/v1/admin/overview", s.guard(s.overview))
-	app.Get("/v1/admin/orgs", s.guard(s.orgs))
-	app.Get("/v1/admin/users", s.guard(s.users))
-	app.Get("/v1/admin/roles", s.guard(s.roles))
-	app.Get("/v1/admin/applications", s.guard(s.applications))
-	app.Get("/v1/admin/audit", s.guard(s.audit))
-	app.Get("/v1/admin/audit/verify", s.guard(s.auditVerify))
-	app.Get("/v1/admin/usage", s.guard(s.usage))
-	app.Get("/v1/admin/products", s.guard(s.products))
-	app.Get("/v1/admin/finance", s.guard(s.finance))
-	app.Get("/v1/admin/compute", s.guard(s.compute))
-	app.Post("/v1/admin/sync", s.guard(s.sync))
+	routes(app, s)
 
-	// Customer management — the operator cockpit. List (static) precedes the :org
-	// param route; the write actions are POST (distinct method), so none collide.
-	app.Get("/v1/admin/customers", s.guard(s.customers))
-	app.Get("/v1/admin/customers/:org", s.guard(s.customerDetail))
-	app.Post("/v1/admin/customers/:org/credit", s.guard(s.grantCredit))
-	app.Post("/v1/admin/customers/:org/suspend", s.guard(s.suspendCustomer))
-	app.Post("/v1/admin/customers/:org/reactivate", s.guard(s.reactivateCustomer))
-
-	// Fleet revenue aggregate + native SaaS analytics (retention/growth/churn).
-	app.Get("/v1/admin/revenue", s.guard(s.revenue))
-	app.Get("/v1/admin/analytics", s.guard(s.analytics))
-
-	logger.Info("admin surface mounted",
+	b.Log.Info("admin surface mounted",
 		"prefix", "/v1/admin",
-		"iam", s.iam.configured(),
-		"commerce", s.commerce.configured(),
-		"digitalocean", s.do.configured(),
-		"adminOrg", s.adminOrg,
+		"iam", s.State.IAM.Ready(),
+		"commerce", s.State.Commerce.Ready(),
+		"digitalocean", s.State.DO.Ready(),
+		"adminOrg", s.State.AdminOrg,
 	)
 	return nil
 }
 
-// guard wraps a handler with the global-admin gate. Fail-closed: any request
-// whose validated identity is not a global admin (X-User-IsAdmin != "true",
-// which SanitizeIdentity sets only for owner == AdminOrg) is refused 403 before
-// the handler — no upstream is touched, no data leaks.
-func (s *svc) guard(h func(*zip.Ctx) error) zip.Handler {
-	return func(c *zip.Ctx) error {
-		if !c.IsAdmin() {
-			return zip.ErrForbidden("global admin required")
-		}
-		return h(c)
-	}
-}
+// routes registers the /v1/admin/* surface on app, threading the ONE service value
+// through the two-tier gate: org-scoped panels behind core.GuardScoped, the platform
+// control plane behind core.Guard. Each carved-out domain (audit/customer/revenue/finance)
+// owns its own route registration.
+func routes(app *zip.App, s *cloud.Service[core.State]) {
+	// Org-scoped panels — GuardScoped. Cross-tenant reads are impossible for a non-super
+	// caller.
+	app.Get("/v1/admin/me", core.GuardScoped(s, me))
+	app.Get("/v1/admin/overview", core.GuardScoped(s, overview))
+	app.Get("/v1/admin/orgs", core.GuardScoped(s, orgs))
+	app.Get("/v1/admin/users", core.GuardScoped(s, users))
+	app.Get("/v1/admin/usage", core.GuardScoped(s, usage))
+	// Platform reads — SuperAdmin only (cross-tenant by nature).
+	app.Get("/v1/admin/roles", core.Guard(s, roles))
+	app.Get("/v1/admin/applications", core.Guard(s, applications))
+	app.Get("/v1/admin/products", core.Guard(s, products))
+	app.Get("/v1/admin/compute", core.Guard(s, compute))
+	app.Get("/v1/admin/o11y", core.Guard(s, o11y))
+	app.Post("/v1/admin/sync", core.Guard(s, syncNow))
 
-// callerCreds captures the caller's replayed authorization context for the IAM
-// fan-out: the raw Cookie header (session model) and the Authorization bearer.
-func callerCreds(c *zip.Ctx) creds {
-	return creds{
-		cookie: string(c.Fiber().Request().Header.Peek("Cookie")),
-		auth:   c.Header("Authorization"),
-	}
-}
+	// Product analytics — org-scoped (SuperAdmin: all-orgs; org admin: their own org).
+	app.Get("/v1/admin/analytics", core.GuardScoped(s, analytics))
+	// Bases — the tenant Base-instance panel, org-scoped (bases.go).
+	app.Get("/v1/admin/bases", core.GuardScoped(s, bases))
 
-// ── /v1 envelope writers ────────────────────────────────────────────────
+	// ── Platform control plane — SuperAdmin ONLY (launch/release/flags + access). ──
+	app.Get("/v1/admin/flags", core.Guard(s, flagsBoard))
+	app.Put("/v1/admin/flags/:key", core.Guard(s, setFlag))
+	// Launch-control services board — the waitlist-mode lens on the flag engine (twin
+	// of /v1/admin/flags), folded in from the former featuregate control plane.
+	app.Get("/v1/admin/services", core.Guard(s, services))
+	app.Post("/v1/admin/services", core.Guard(s, upsertService))
+	app.Post("/v1/admin/services/:service/mode", core.Guard(s, setServiceMode))
+	app.Get("/v1/admin/waitlist", core.Guard(s, waitlist))
+	app.Post("/v1/admin/waitlist/boost", core.Guard(s, waitlistBoost))
 
-// ok writes a { status:"ok", data } envelope (the get<T> shape).
-func ok(c *zip.Ctx, data any) error {
-	return c.JSON(200, map[string]any{"status": "ok", "msg": "", "data": data})
-}
-
-// okList writes a { status:"ok", data:[...], data2:total } envelope (getList<T>).
-func okList(c *zip.Ctx, rows any, total int) error {
-	return c.JSON(200, map[string]any{"status": "ok", "msg": "", "data": rows, "data2": total})
-}
-
-// okRaw writes a { status:"ok", data:<raw>, data2:total } envelope, forwarding an
-// IAM payload verbatim so its exact wire shape (Role, Application, Record, User)
-// reaches the operator field-for-field.
-func okRaw(c *zip.Ctx, rows json.RawMessage, total int) error {
-	if len(rows) == 0 {
-		rows = json.RawMessage("[]")
-	}
-	return c.JSON(200, map[string]any{"status": "ok", "msg": "", "data": rows, "data2": total})
-}
-
-// fail writes a { status:"error", msg } envelope. The operator's transport maps
-// a non-ok envelope to a surfaced error (never a fabricated value).
-func fail(c *zip.Ctx, msg string) error {
-	return c.JSON(200, map[string]any{"status": "error", "msg": msg, "data": nil})
+	// ── Carved-out domains own their routes (audit/customer/revenue/finance). ──
+	audit.Routes(app, s)
+	customer.Routes(app, s)
+	revenue.Routes(app, s)
+	finance.Routes(app, s)
 }
 
 // ── /v1/admin/me — operator identity (AdminMe) ───────────────────────────────
 
-// me answers with the validated operator identity. The gate already proved this
-// is a global admin, so the fields come from the sanitized identity headers —
-// authoritative and never client-forgeable.
-func (s *svc) me(c *zip.Ctx) error {
-	owner := s.adminOrg
-	if o := strings.TrimSpace(c.Org()); o != "" {
-		owner = o
+// me answers with the validated operator identity. The gate already proved this is an
+// admin, so the fields come from the sanitized identity headers — authoritative and never
+// client-forgeable.
+func me(s *cloud.Service[core.State], c *zip.Ctx) error {
+	sc := core.ResolveScope(s, c)
+	owner, _ := principal.Org(c)
+	if owner == "" && sc.Super {
+		owner = s.State.AdminOrg
 	}
 	name := strings.TrimSpace(c.User())
-	return ok(c, adminMe{
-		Owner:         owner,
-		Name:          name,
-		Email:         strings.TrimSpace(c.UserEmail()),
-		DisplayName:   name,
-		IsGlobalAdmin: true,
+	return core.OK(c, adminMe{
+		Owner:        owner,
+		Name:         name,
+		Email:        strings.TrimSpace(c.UserEmail()),
+		DisplayName:  name,
+		IsSuperAdmin: sc.Super,
 	})
 }
 
 // ── /v1/admin/orgs — tenant directory (OrgRow[]) ─────────────────────────────
 
-func (s *svc) orgs(c *zip.Ctx) error {
+func orgs(s *cloud.Service[core.State], c *zip.Ctx) error {
 	ctx := c.Context()
-	cr := callerCreds(c)
-	orgs, err := s.listOrgs(ctx, cr)
+	cr := core.CallerCreds(c)
+	orgs, err := core.ScopedOrgs(s, ctx, c, cr)
 	if err != nil {
-		return fail(c, err.Error())
+		return core.Fail(c, err.Error())
 	}
 	rows := make([]orgRow, 0, len(orgs))
 	for _, o := range orgs {
-		users := s.orgUserCount(ctx, cr, o.Name)
-		spend, credits := s.orgMoney(ctx, o.Name)
+		users := orgUserCount(s, ctx, cr, o.Name)
+		// orgs is a per-ROW panel (OrgRow[] via OKList; it carries NO sources[] channel):
+		// a failed read degrades THAT org's row to an honest zero, never a fleet total that
+		// falsely reads healthy. The aggregate-freshness signal lives on /overview.
+		spend, credits, _ := core.OrgMoney(s, ctx, o.Name)
 		rows = append(rows, orgRow{
 			Org:          o.Name,
-			Display:      display(o.DisplayName, o.Name),
+			Display:      core.Display(o.DisplayName, o.Name),
 			Users:        users,
 			Products:     0, // workload registry feed pending (platform apps table)
 			SpendCents:   spend,
@@ -205,16 +174,23 @@ func (s *svc) orgs(c *zip.Ctx) error {
 		})
 	}
 	sort.Slice(rows, func(i, j int) bool { return rows[i].Org < rows[j].Org })
-	return okList(c, rows, len(rows))
+	return core.OKList(c, rows, len(rows))
 }
 
 // ── /v1/admin/users — cross-org directory (OperatorUser[]) ───────────────────
 
-func (s *svc) users(c *zip.Ctx) error {
+func users(s *cloud.Service[core.State], c *zip.Ctx) error {
 	ctx := c.Context()
-	cr := callerCreds(c)
+	cr := core.CallerCreds(c)
+	sc := core.ResolveScope(s, c)
 	q := url.Values{}
-	if owner := strings.TrimSpace(c.Query("org")); owner != "" {
+	if !sc.Super {
+		// A scoped caller lists ONLY their own org's users — the client ?org= is ignored,
+		// the owner hard-pinned to the sanitized org subtree.
+		if len(sc.Orgs) > 0 {
+			q.Set("owner", sc.Orgs[0])
+		}
+	} else if owner := strings.TrimSpace(c.Query("org")); owner != "" {
 		q.Set("owner", owner)
 	}
 	if p := strings.TrimSpace(c.Query("p")); p != "" {
@@ -228,56 +204,56 @@ func (s *svc) users(c *zip.Ctx) error {
 		q.Set("field", "name")
 		q.Set("value", term)
 	}
-	res, err := s.iam.getList(ctx, cr, "/v1/iam/get-users", q)
+	res, err := s.State.IAM.Users(ctx, cr, q)
 	if err != nil {
-		return fail(c, err.Error())
+		return core.Fail(c, err.Error())
 	}
-	var raw []iamUser
-	if len(res.rows) > 0 {
-		if err := json.Unmarshal(res.rows, &raw); err != nil {
-			return fail(c, "users decode: "+err.Error())
+	var raw []iam.User
+	if len(res.Rows) > 0 {
+		if err := json.Unmarshal(res.Rows, &raw); err != nil {
+			return core.Fail(c, "users decode: "+err.Error())
 		}
 	}
 	rows := make([]operatorUser, 0, len(raw))
 	for _, u := range raw {
 		rows = append(rows, operatorUser{
-			Owner:         u.Owner,
-			Name:          u.Name,
-			Email:         u.Email,
-			DisplayName:   u.DisplayName,
-			IsAdmin:       u.IsAdmin,
-			IsGlobalAdmin: u.Owner == s.adminOrg,
-			Tag:           u.Tag,
-			Created:       u.CreatedTime,
-			LastSignin:    u.LastSigninTime,
-			Forbidden:     u.IsForbidden,
+			Owner:        u.Owner,
+			Name:         u.Name,
+			Email:        u.Email,
+			DisplayName:  u.DisplayName,
+			IsAdmin:      u.IsAdmin,
+			IsSuperAdmin: u.Owner == s.State.AdminOrg,
+			Tag:          u.Tag,
+			Created:      u.CreatedTime,
+			LastSignin:   u.LastSigninTime,
+			Forbidden:    u.IsForbidden,
 		})
 	}
-	total := res.total
+	total := res.Total
 	if total < len(rows) {
 		total = len(rows)
 	}
-	return okList(c, rows, total)
+	return core.OKList(c, rows, total)
 }
 
 // ── /v1/admin/roles and /applications — verbatim IAM passthrough ─────────────
 
-func (s *svc) roles(c *zip.Ctx) error {
-	return s.iamPassthrough(c, "/v1/iam/get-roles")
+func roles(s *cloud.Service[core.State], c *zip.Ctx) error {
+	return iamPassthrough(s, c, "/v1/iam/get-roles")
 }
 
-func (s *svc) applications(c *zip.Ctx) error {
-	return s.iamPassthrough(c, "/v1/iam/get-applications")
+func applications(s *cloud.Service[core.State], c *zip.Ctx) error {
+	return iamPassthrough(s, c, "/v1/iam/get-applications")
 }
 
-// iamPassthrough forwards a paginated IAM read verbatim (the operator decodes
-// Role / Application as the raw IAM wire shape). `owner` defaults to the admin
-// org, which owns the platform applications.
-func (s *svc) iamPassthrough(c *zip.Ctx, path string) error {
+// iamPassthrough forwards a paginated IAM read verbatim (the operator decodes Role /
+// Application as the raw IAM wire shape). `owner` defaults to the admin org, which owns
+// the platform applications.
+func iamPassthrough(s *cloud.Service[core.State], c *zip.Ctx, path string) error {
 	q := url.Values{}
 	owner := strings.TrimSpace(c.Query("owner"))
 	if owner == "" {
-		owner = s.adminOrg
+		owner = s.State.AdminOrg
 	}
 	q.Set("owner", owner)
 	if p := strings.TrimSpace(c.Query("p")); p != "" {
@@ -286,66 +262,52 @@ func (s *svc) iamPassthrough(c *zip.Ctx, path string) error {
 	if ps := strings.TrimSpace(c.Query("pageSize")); ps != "" {
 		q.Set("pageSize", ps)
 	}
-	res, err := s.iam.getList(c.Context(), callerCreds(c), path, q)
+	res, err := s.State.IAM.List(c.Context(), core.CallerCreds(c), path, q)
 	if err != nil {
-		return fail(c, err.Error())
+		return core.Fail(c, err.Error())
 	}
-	return okRaw(c, res.rows, res.total)
-}
-
-// ── /v1/admin/audit — records directory (AuditRow[]) ─────────────────────────
-//
-// The handler lives in audit.go (it reads cloud's OWN tamper-evident store).
-// iamAuditQuery builds the IAM get-records query for the federated fallback
-// auditFromIAM uses when no local store is configured.
-
-func iamAuditQuery(c *zip.Ctx) url.Values {
-	q := url.Values{}
-	if org := strings.TrimSpace(c.Query("org")); org != "" {
-		q.Set("organizationName", org)
-	}
-	q.Set("p", "1")
-	ps := strings.TrimSpace(c.Query("pageSize"))
-	if ps == "" {
-		ps = "100"
-	}
-	q.Set("pageSize", ps)
-	q.Set("sortField", "createdTime")
-	q.Set("sortOrder", "descend")
-	return q
+	return core.OKRaw(c, res.Rows, res.Total)
 }
 
 // ── /v1/admin/usage — fleet usage roll-up (UsageData) ────────────────────────
 
-// usage returns the real fleet money totals from commerce. The daily series and
-// the per-product breakdown are NOT derivable from the commerce billing API
-// (they live in insights/datastore, owned separately); admin returns the
-// honest empty series/byProduct rather than fabricating a trend — the operator
-// renders that as an empty chart, never a fake line.
-func (s *svc) usage(c *zip.Ctx) error {
+// usage returns the real fleet money totals from commerce. The daily series and the
+// per-product breakdown are NOT derivable from the commerce billing API (they live in
+// insights/datastore); admin returns the honest empty series/byProduct rather than
+// fabricating a trend.
+func usage(s *cloud.Service[core.State], c *zip.Ctx) error {
 	ctx := c.Context()
-	cr := callerCreds(c)
+	cr := core.CallerCreds(c)
+	sc := core.ResolveScope(s, c)
 	org := strings.TrimSpace(c.Query("org"))
+	if !sc.Super {
+		// A scoped caller reads ONLY their own org's usage — the client ?org= is ignored,
+		// the org hard-pinned to the sanitized subtree.
+		org = ""
+		if len(sc.Orgs) > 0 {
+			org = sc.Orgs[0]
+		}
+	}
 
 	var spend int64
-	if org != "" {
-		r, err := s.commerce.usageRollup(ctx, org, orgSubject(org))
-		if err == nil {
-			spend = r.ConsumedCents
+	switch {
+	case org != "":
+		if sp, err := s.State.Commerce.Spend(ctx, org); err == nil {
+			spend = int64(sp.Consumed)
 		}
-	} else {
+	case sc.Super:
 		// Fleet: sum month-to-date consumption across every org.
-		orgs, err := s.listOrgs(ctx, cr)
+		orgs, err := core.ListOrgs(s, ctx, cr)
 		if err == nil {
 			for _, o := range orgs {
-				if r, e := s.commerce.usageRollup(ctx, o.Name, orgSubject(o.Name)); e == nil {
-					spend += r.ConsumedCents
+				if sp, e := s.State.Commerce.Spend(ctx, o.Name); e == nil {
+					spend += int64(sp.Consumed)
 				}
 			}
 		}
 	}
 
-	return ok(c, usageData{
+	return core.OK(c, usageData{
 		Totals:    usageTotals{SpendCents: spend, Tokens: 0, Requests: 0},
 		Series:    []usagePoint{},
 		ByProduct: []usageByProduct{},
@@ -354,64 +316,67 @@ func (s *svc) usage(c *zip.Ctx) error {
 
 // ── /v1/admin/products — workload registry (ProductRow[]) ────────────────────
 
-// products is the workload/drift registry (declared vs running tag, health).
-// That inventory is the platform.hanzo.ai apps table / operator reconcile state,
-// NOT an in-binary source. admin exposes the gated endpoint and returns the
-// real empty registry until that feed is wired — it never fabricates workload
-// rows. The operator renders an empty table, not fake products.
-func (s *svc) products(c *zip.Ctx) error {
-	return okList(c, []productRow{}, 0)
+// products is the workload/drift registry. That inventory is the platform.hanzo.ai apps
+// table / operator reconcile state, NOT an in-binary source. admin exposes the gated
+// endpoint and returns the real empty registry until that feed is wired.
+func products(s *cloud.Service[core.State], c *zip.Ctx) error {
+	return core.OKList(c, []productRow{}, 0)
 }
 
 // ── /v1/admin/overview — Platform Overview tiles (OverviewData) ───────────────
 
-func (s *svc) overview(c *zip.Ctx) error {
+func overview(s *cloud.Service[core.State], c *zip.Ctx) error {
 	ctx := c.Context()
-	cr := callerCreds(c)
+	cr := core.CallerCreds(c)
 	now := time.Now().UTC().Format(time.RFC3339)
 
-	var sources []sourceStatus
+	var sources []core.SourceStatus
 	orgCount, userCount, spend, credits := 0, 0, int64(0), int64(0)
 
-	orgs, orgErr := s.listOrgs(ctx, cr)
-	sources = append(sources, srcOf("iam", orgErr, len(orgs), now))
+	orgs, orgErr := core.ScopedOrgs(s, ctx, c, cr)
+	sources = append(sources, core.SrcOf("iam", orgErr, len(orgs), now))
+	commercePartial := false
 	if orgErr == nil {
 		orgCount = len(orgs)
 		for _, o := range orgs {
-			userCount += s.orgUserCount(ctx, cr, o.Name)
-			sp, cr2 := s.orgMoney(ctx, o.Name)
+			userCount += orgUserCount(s, ctx, cr, o.Name)
+			sp, cr2, ok := core.OrgMoney(s, ctx, o.Name)
 			spend += sp
 			credits += cr2
+			if !ok {
+				// This org's money did not read — the fleet spend/credits totals are now
+				// an UNDERCOUNT, so the commerce source must report degraded, not healthy.
+				commercePartial = true
+			}
 		}
 	}
 
-	// Commerce freshness: probe one org's rollup so the tile reflects a real read.
-	commerceRows := 0
+	// Commerce freshness derives from the SAME per-org reads the totals fold — NOT a
+	// single probe org (which could read healthy while commerce was down for every other
+	// org, masking an undercount). Not-configured when unwired; degraded/partial (the ONE
+	// core.ErrPartialRevenue sentinel revenue/finance use) when ANY per-org read failed.
 	var commerceErr error
-	if s.commerce.configured() {
-		probe := s.adminOrg
-		if len(orgs) > 0 {
-			probe = orgs[0].Name
-		}
-		if _, err := s.commerce.usageRollup(ctx, probe, orgSubject(probe)); err != nil {
-			commerceErr = err
-		} else {
-			commerceRows = 1
-		}
-	} else {
+	commerceRows := 0
+	switch {
+	case !s.State.Commerce.Ready():
 		commerceErr = fmt.Errorf("commerce endpoint not configured")
+	case commercePartial:
+		commerceErr = core.ErrPartialRevenue
+		commerceRows = orgCount
+	default:
+		commerceRows = orgCount
 	}
-	sources = append(sources, srcOf("commerce", commerceErr, commerceRows, now))
+	sources = append(sources, core.SrcOf("commerce", commerceErr, commerceRows, now))
 
 	// o11y System Health.
 	o11yRows := 0
-	oOK, oErr := s.health.ok(ctx)
+	oOK, oErr := s.State.Health.Up(ctx)
 	if oOK {
 		o11yRows = 1
 	}
-	sources = append(sources, srcOf("o11y", oErr, o11yRows, now))
+	sources = append(sources, core.SrcOf("o11y", oErr, o11yRows, now))
 
-	return ok(c, overviewData{
+	return core.OK(c, overviewData{
 		Orgs:           orgCount,
 		Users:          userCount,
 		Products:       0, // workload registry feed pending (platform apps table)
@@ -427,95 +392,33 @@ func (s *svc) overview(c *zip.Ctx) error {
 
 // ── /v1/admin/sync — refresh trigger ─────────────────────────────────────────
 
-// sync answers the operator's "Sync now" button. admin aggregates LIVE on
-// every read (there is no cached fleet snapshot in-binary), so there is no batch
-// job to kick — the button simply re-reads. We acknowledge honestly with
-// { started: true } so the UI re-fetches the (freshly-computed) overview.
-func (s *svc) sync(c *zip.Ctx) error {
-	return ok(c, map[string]bool{"started": true})
+// syncNow answers the operator's "Sync now" button. admin aggregates LIVE on every read,
+// so there is no batch job to kick — the button simply re-reads. We acknowledge honestly
+// with { started: true }.
+func syncNow(s *cloud.Service[core.State], c *zip.Ctx) error {
+	return core.OK(c, map[string]bool{"started": true})
 }
 
 // ── aggregation helpers ──────────────────────────────────────────────────────
 
-// listOrgs reads the org directory (owner = admin org) as the typed shape the
-// overview/orgs/usage aggregators fold over.
-func (s *svc) listOrgs(ctx context.Context, cr creds) ([]iamOrg, error) {
-	q := url.Values{}
-	q.Set("owner", s.adminOrg)
-	res, err := s.iam.getList(ctx, cr, "/v1/iam/get-organizations", q)
-	if err != nil {
-		return nil, err
-	}
-	var orgs []iamOrg
-	if len(res.rows) > 0 {
-		if err := json.Unmarshal(res.rows, &orgs); err != nil {
-			return nil, fmt.Errorf("orgs decode: %w", err)
-		}
-	}
-	return orgs, nil
-}
-
-// orgUserCount returns the member count for one org from the IAM list total
-// (data2). Best-effort: an error yields 0 rather than failing the whole row.
-func (s *svc) orgUserCount(ctx context.Context, cr creds, org string) int {
+// orgUserCount returns the member count for one org from the IAM list total (data2).
+// Best-effort: an error yields 0 rather than failing the whole row.
+func orgUserCount(s *cloud.Service[core.State], ctx context.Context, cr iam.Creds, org string) int {
 	q := url.Values{}
 	q.Set("owner", org)
 	q.Set("p", "1")
 	q.Set("pageSize", "1")
-	res, err := s.iam.getList(ctx, cr, "/v1/iam/get-users", q)
+	res, err := s.State.IAM.Users(ctx, cr, q)
 	if err != nil {
 		return 0
 	}
-	return res.total
-}
-
-// orgMoney returns (spendCents, creditsCents) for one org from commerce.
-// Best-effort: unreachable/unconfigured commerce yields zeros.
-func (s *svc) orgMoney(ctx context.Context, org string) (int64, int64) {
-	subj := orgSubject(org)
-	var spend, credits int64
-	if r, err := s.commerce.usageRollup(ctx, org, subj); err == nil {
-		spend = r.ConsumedCents
-	}
-	if c, err := s.commerce.creditsCents(ctx, org, subj); err == nil {
-		credits = c
-	}
-	return spend, credits
-}
-
-// orgSubject is the billing subject commerce keys an org's wallet on. Commerce's
-// per-org billing store (the 2026-07 durability rework, commerce >=1.46.8)
-// namespaces by the TRUSTED X-Org-Id header (set by commerceClient.get from this
-// same org) and keys the org wallet under the BARE org slug as the `user` subject —
-// NOT "org/user". The prior "org/org" subject (with the wrong X-IAM-Org-Id header)
-// resolved to an EMPTY wallet, so every per-org money panel read $0 while real
-// balances existed (lux $10,000, maxpower $20,498). Verified live against commerce
-// /v1/billing/{balance,usage-rollup}: user=<org> + X-Org-Id=<org> returns the real
-// wallet; user="org/org" or a missing/other org header returns $0.
-func orgSubject(org string) string { return org }
-
-// srcOf builds a SourceStatus freshness row for the overview.
-func srcOf(name string, err error, rows int, at string) sourceStatus {
-	s := sourceStatus{Name: name, OK: err == nil, Rows: rows, At: at}
-	if err != nil {
-		s.Error = err.Error()
-	}
-	return s
-}
-
-func display(displayName, fallback string) string {
-	if strings.TrimSpace(displayName) != "" {
-		return displayName
-	}
-	return fallback
+	return res.Total
 }
 
 // ── config resolution ────────────────────────────────────────────────────────
 
-// iamBase resolves the IAM management HTTP base. CLOUD_IAM_HTTP_URL wins (the
-// in-cluster Service, e.g. http://iam.hanzo.svc.cluster.local:8000); otherwise
-// the public issuer (deps.IAMIssuer, e.g. https://hanzo.id) which also serves
-// /v1/iam/*. Empty only when neither is set (endpoint reports not-configured).
+// iamBase resolves the IAM management HTTP base. CLOUD_IAM_HTTP_URL wins (the in-cluster
+// Service); otherwise the public issuer (deps.IAMIssuer) which also serves /v1/iam/*.
 func iamBase(deps cloud.Deps) string {
 	if v := strings.TrimSpace(os.Getenv("CLOUD_IAM_HTTP_URL")); v != "" {
 		return v
@@ -532,8 +435,8 @@ func o11yHealthURL() string {
 	return "http://o11y.hanzo.svc.cluster.local:80/v1/o11y/health"
 }
 
-// adminOrgOf resolves the admin org slug (IAM's IsGlobalAdmin owner). IAM_ADMIN_ORG
-// mirrors config.go's default; "admin" is the fleet-wide default.
+// adminOrgOf resolves the admin org slug (IAM's IsSuperAdmin owner). IAM_ADMIN_ORG mirrors
+// config.go's default; "admin" is the fleet-wide default.
 func adminOrgOf(_ cloud.Deps) string {
 	if v := strings.TrimSpace(os.Getenv("IAM_ADMIN_ORG")); v != "" {
 		return v
@@ -541,15 +444,8 @@ func adminOrgOf(_ cloud.Deps) string {
 	return "admin"
 }
 
-func init() {
-	// Order 146: after productsvc (145); the admin surface has no ordering
-	// dependency (it fans out over HTTP), placed adjacent to the other console
-	// read facades.
-	cloud.Register("admin", 146, func(app any, deps cloud.Deps) error {
-		a, ok := app.(*zip.App)
-		if !ok {
-			return fmt.Errorf("admin.Mount: app is %T, want *zip.App", app)
-		}
-		return Mount(a, deps)
-	})
+// doTokenFromEnv reads the DigitalOcean token from the environment. Sourced from a
+// KMSSecret on the cloud deployment (DO_API_TOKEN) — never hard-coded.
+func doTokenFromEnv() string {
+	return strings.TrimSpace(os.Getenv("DO_API_TOKEN"))
 }

clients/admin/admin_test.go

@@ -10,10 +10,15 @@ import (
 	"testing"
 	"time"
 
-	fiber "github.com/gofiber/fiber/v3"
 	"github.com/hanzoai/cloud"
-	"github.com/zap-proto/zip"
+	"github.com/hanzoai/cloud/clients/admin/commerce"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/hanzoai/cloud/clients/admin/digitalocean"
+	"github.com/hanzoai/cloud/clients/admin/health"
+	"github.com/hanzoai/cloud/clients/admin/iam"
 	luxlog "github.com/luxfi/log"
+	fiber "github.com/zap-proto/fiber/v3"
+	"github.com/zap-proto/zip"
 )
 
 // mount builds a zip app with admin mounted against the given upstream bases,
@@ -23,40 +28,26 @@ func mount(t *testing.T, iamURL, commerceURL, healthURL string) func(method, pat
 	return do
 }
 
-// mountSvc is mount but also returns the underlying svc (so finance tests can swap
+// mountSvc is mount but also returns the underlying cloud.Service[state] (so finance tests can swap
 // in a fake DigitalOcean client, and the cockpit tests can attach an audit store)
 // AND the raw fiber app (so tests that need a request BODY can drive it directly —
 // the returned `do` sends a nil body). The handlers read s.* live at request time,
 // so an override before issuing a request takes effect.
-func mountSvc(t *testing.T, iamURL, commerceURL, healthURL string) (func(method, path string, hdr map[string]string) (*http.Response, []byte), *svc, *fiber.App) {
+func mountSvc(t *testing.T, iamURL, commerceURL, healthURL string) (func(method, path string, hdr map[string]string) (*http.Response, []byte), *cloud.Service[core.State], *fiber.App) {
 	t.Helper()
 	app := zip.New(zip.Config{Logger: luxlog.New("test")})
-	s := &svc{
-		iam:      newIAMClient(iamURL),
-		commerce: newCommerceClient(commerceURL, "test-token"),
-		health:   newHealthClient(healthURL),
-		do:       newDOClient(""), // no token → honest not-configured unless a test overrides s.do
-		adminOrg: "admin",
-	}
-	app.Get("/v1/admin/me", s.guard(s.me))
-	app.Get("/v1/admin/overview", s.guard(s.overview))
-	app.Get("/v1/admin/orgs", s.guard(s.orgs))
-	app.Get("/v1/admin/users", s.guard(s.users))
-	app.Get("/v1/admin/roles", s.guard(s.roles))
-	app.Get("/v1/admin/applications", s.guard(s.applications))
-	app.Get("/v1/admin/audit", s.guard(s.audit))
-	app.Get("/v1/admin/audit/verify", s.guard(s.auditVerify))
-	app.Get("/v1/admin/usage", s.guard(s.usage))
-	app.Get("/v1/admin/products", s.guard(s.products))
-	app.Get("/v1/admin/finance", s.guard(s.finance))
-	app.Post("/v1/admin/sync", s.guard(s.sync))
-	app.Get("/v1/admin/customers", s.guard(s.customers))
-	app.Get("/v1/admin/customers/:org", s.guard(s.customerDetail))
-	app.Post("/v1/admin/customers/:org/credit", s.guard(s.grantCredit))
-	app.Post("/v1/admin/customers/:org/suspend", s.guard(s.suspendCustomer))
-	app.Post("/v1/admin/customers/:org/reactivate", s.guard(s.reactivateCustomer))
-	app.Get("/v1/admin/revenue", s.guard(s.revenue))
-	app.Get("/v1/admin/analytics", s.guard(s.analytics))
+	s := &cloud.Service[core.State]{State: core.State{
+		IAM:      iam.New(iamURL),
+		Commerce: commerce.New(commerceURL, "test-token"),
+		Health:   health.New(healthURL),
+		DO:       digitalocean.New(""), // no token → honest not-configured unless a test overrides s.State.DO
+		AdminOrg: "admin",
+	}}
+	// Mirror the REAL Mount EXACTLY by registering the same routes() the subsystem uses
+	// (org-scoped panels behind GuardScoped, the platform control plane behind Guard,
+	// each domain owning its own routes), so the harness stays authoritative for the
+	// two-tier gate + every surface.
+	routes(app, s)
 	fa := app.Fiber()
 
 	return func(method, path string, hdr map[string]string) (*http.Response, []byte) {
@@ -74,18 +65,28 @@ func mountSvc(t *testing.T, iamURL, commerceURL, healthURL string) (func(method,
 	}, s, fa
 }
 
-// adminRoutes is every mounted /v1/admin route + its method — the full god-mode
-// surface the gate must fail-close on for a non-global-admin.
-var adminRoutes = []struct{ method, path string }{
+type adminRoute struct{ method, path string }
+
+// scopedAdminRoutes are the ORG-SCOPED panels (guardScoped): a SuperAdmin OR a validated
+// org admin is admitted, and the handler scopes the data. A caller with NO validated
+// principal (anonymous, or an org header but no X-User-Id) is still refused.
+var scopedAdminRoutes = []adminRoute{
 	{"GET", "/v1/admin/me"},
 	{"GET", "/v1/admin/overview"},
 	{"GET", "/v1/admin/orgs"},
 	{"GET", "/v1/admin/users"},
+	{"GET", "/v1/admin/usage"},
+	{"GET", "/v1/admin/analytics"},
+	{"GET", "/v1/admin/bases"},
+}
+
+// platformAdminRoutes are SuperAdmin ONLY (s.guard) — the cross-tenant platform reads +
+// the launch/release/flags/access control plane. A non-super caller is ALWAYS 403.
+var platformAdminRoutes = []adminRoute{
 	{"GET", "/v1/admin/roles"},
 	{"GET", "/v1/admin/applications"},
 	{"GET", "/v1/admin/audit"},
 	{"GET", "/v1/admin/audit/verify"},
-	{"GET", "/v1/admin/usage"},
 	{"GET", "/v1/admin/products"},
 	{"GET", "/v1/admin/finance"},
 	{"POST", "/v1/admin/sync"},
@@ -95,11 +96,17 @@ var adminRoutes = []struct{ method, path string }{
 	{"POST", "/v1/admin/customers/acme/suspend"},
 	{"POST", "/v1/admin/customers/acme/reactivate"},
 	{"GET", "/v1/admin/revenue"},
-	{"GET", "/v1/admin/analytics"},
+	{"GET", "/v1/admin/flags"},
+	{"GET", "/v1/admin/waitlist"},
+	{"POST", "/v1/admin/waitlist/boost"},
 }
 
+// adminRoutes is the full surface (both tiers) — the fail-closed gate test denies an
+// unauthenticated caller on EVERY one.
+var adminRoutes = append(append([]adminRoute{}, scopedAdminRoutes...), platformAdminRoutes...)
+
 // TestGate_DeniesEveryRoute proves the non-negotiable: EVERY /v1/admin/* route is
-// global-admin only, fail-closed. An anonymous caller and a tenant-admin (whose
+// SuperAdmin only, fail-closed. An anonymous caller and a tenant-admin (whose
 // identity carries an org but NOT the sanitizer-minted X-User-IsAdmin) are BOTH
 // denied 403 on every route — no upstream is even reached. admin mirrors the
 // gateway's admin-guard: SanitizeIdentity sets X-User-IsAdmin only for a
@@ -109,15 +116,18 @@ func TestGate_DeniesEveryRoute(t *testing.T) {
 	// Upstreams point nowhere reachable; the gate must reject BEFORE any call.
 	do := mount(t, "http://127.0.0.1:0", "http://127.0.0.1:0", "http://127.0.0.1:0")
 
-	cases := []struct {
+	// NO validated principal ⇒ denied on EVERY route (platform + scoped). guardScoped
+	// requires a sanitized X-User-Id, which an anonymous caller lacks — and a client
+	// that merely forges X-Org-Id (the documented Phase-1 residual) still has no
+	// X-User-Id, so it is refused here and can never reach a scoped read.
+	noPrincipal := []struct {
 		name string
 		hdr  map[string]string
 	}{
 		{"anonymous", nil},
-		{"tenant-admin (owner set, not global-admin)", map[string]string{"X-Org-Id": "acme"}},
-		{"tenant-user with email but no admin", map[string]string{"X-Org-Id": "acme", "X-User-Id": "acme/bob", "X-User-Email": "bob@acme.test"}},
+		{"forged X-Org-Id, no validated user", map[string]string{"X-Org-Id": "victim"}},
 	}
-	for _, tc := range cases {
+	for _, tc := range noPrincipal {
 		for _, r := range adminRoutes {
 			resp, body := do(r.method, r.path, tc.hdr)
 			if resp.StatusCode != http.StatusForbidden {
@@ -125,17 +135,30 @@ func TestGate_DeniesEveryRoute(t *testing.T) {
 			}
 		}
 	}
+
+	// A VALIDATED org admin (X-User-Id + pinned X-Org-Id + the sanitizer-minted
+	// X-User-IsOrgAdmin, but NO GLOBAL X-User-IsAdmin) is denied on every PLATFORM route
+	// (super-only). The org-scoped routes admit them but hard-scope the data — proven in
+	// scope_test.go. (A validated NON-admin member, lacking the org-admin bit, is refused
+	// on the scoped panels too — TestScope_MemberWithoutOrgAdminDenied.)
+	orgAdmin := map[string]string{"X-Org-Id": "acme", "X-User-Id": "acme/bob", "X-User-Email": "bob@acme.test", "X-User-IsOrgAdmin": "true"}
+	for _, r := range platformAdminRoutes {
+		resp, body := do(r.method, r.path, orgAdmin)
+		if resp.StatusCode != http.StatusForbidden {
+			t.Errorf("%s %s [org-admin on platform route]: got %d, want 403 (body=%s)", r.method, r.path, resp.StatusCode, body)
+		}
+	}
 }
 
-// TestGate_AllowsGlobalAdmin proves the flip side: a validated global admin
+// TestGate_AllowsSuperAdmin proves the flip side: a validated SuperAdmin
 // (X-User-IsAdmin=true, minted only for owner==AdminOrg) is admitted — the gate
 // is not vacuously closed. Reaches /v1/admin/me, which needs no upstream.
-func TestGate_AllowsGlobalAdmin(t *testing.T) {
+func TestGate_AllowsSuperAdmin(t *testing.T) {
 	do := mount(t, "http://127.0.0.1:0", "http://127.0.0.1:0", "http://127.0.0.1:0")
 	admin := map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin", "X-User-Id": "admin/z", "X-User-Email": "z@hanzo.ai"}
 	resp, body := do("GET", "/v1/admin/me", admin)
 	if resp.StatusCode != http.StatusOK {
-		t.Fatalf("global-admin GET /v1/admin/me: got %d, want 200 (body=%s)", resp.StatusCode, body)
+		t.Fatalf("SuperAdmin GET /v1/admin/me: got %d, want 200 (body=%s)", resp.StatusCode, body)
 	}
 	var env struct {
 		Status string  `json:"status"`
@@ -147,9 +170,14 @@ func TestGate_AllowsGlobalAdmin(t *testing.T) {
 	if env.Status != "ok" {
 		t.Fatalf("me status = %q, want ok", env.Status)
 	}
-	if env.Data.Owner != "admin" || env.Data.Email != "z@hanzo.ai" || !env.Data.IsGlobalAdmin {
+	if env.Data.Owner != "admin" || env.Data.Email != "z@hanzo.ai" || !env.Data.IsSuperAdmin {
 		t.Errorf("me identity wrong: %+v", env.Data)
 	}
+	// SuperAdmin canonicalization: the isSuperAdmin key MUST be present and true
+	// for a platform SuperAdmin.
+	if !env.Data.IsSuperAdmin {
+		t.Errorf("me: isSuperAdmin must be true for a SuperAdmin: %+v", env.Data)
+	}
 }
 
 // fakeIAM stands in for the IAM management surface. It records whether the
@@ -246,11 +274,9 @@ func newFakeCommerce() *fakeCommerce {
 // revenue bug (commerce.go had X-IAM-Org-Id; admin.go orgSubject had "org/org", so
 // every real balance read $0). /v1/admin/orgs must surface acme's real $50.00.
 func TestCommerce_ReconcilesWithXOrgIdBareSlug(t *testing.T) {
-	// orgSubject MUST be the bare slug (not "org/org").
-	if got := orgSubject("acme"); got != "acme" {
-		t.Fatalf("orgSubject(\"acme\") = %q, want \"acme\" (bare slug; \"acme/acme\" reads an empty commerce wallet)", got)
-	}
-
+	// The billing subject is the bare org slug for BOTH the X-Org-Id header and the
+	// `user` param — commerce.Client bakes that in (one subject, no "org/org"). This
+	// test proves it end to end: /v1/admin/orgs must surface acme's real $50.00.
 	iam := newFakeIAM()
 	defer iam.server.Close()
 	commerce := newFakeCommerce()
@@ -338,7 +364,7 @@ func TestOrgs_RealAggregation(t *testing.T) {
 }
 
 // TestUsers_MapsIAMToOperatorUser verifies the cross-org directory mapping,
-// including the derived isGlobalAdmin (owner == adminOrg) and the data2 total.
+// including the derived isSuperAdmin (owner == adminOrg) and the data2 total.
 func TestUsers_MapsIAMToOperatorUser(t *testing.T) {
 	iam := newFakeIAM()
 	defer iam.server.Close()
@@ -363,9 +389,9 @@ func TestUsers_MapsIAMToOperatorUser(t *testing.T) {
 	if u.Name != "alice" || u.Email != "alice@hanzo.ai" || !u.IsAdmin || u.LastSignin == "" {
 		t.Errorf("user mapping wrong: %+v", u)
 	}
-	// owner "hanzo" != adminOrg "admin" → not a global admin.
-	if u.IsGlobalAdmin {
-		t.Errorf("user owner=hanzo must not be flagged global admin")
+	// owner "hanzo" != adminOrg "admin" → not a SuperAdmin.
+	if u.IsSuperAdmin {
+		t.Errorf("user owner=hanzo must not be flagged SuperAdmin")
 	}
 }
 
@@ -466,7 +492,7 @@ func TestOverview_RealTilesAndSources(t *testing.T) {
 		t.Error("overview lastSync must be set")
 	}
 	// Source freshness: iam ok, commerce ok, o11y not-ok (unconfigured).
-	src := map[string]sourceStatus{}
+	src := map[string]core.SourceStatus{}
 	for _, s := range d.Sources {
 		src[s.Name] = s
 	}
@@ -481,6 +507,64 @@ func TestOverview_RealTilesAndSources(t *testing.T) {
 	}
 }
 
+// TestOverview_CommercePartialOnPerOrgError proves the decomplected freshness rule: the
+// commerce source is DEGRADED when ANY per-org money read fails — the fleet total is then
+// an undercount and must NOT read healthy. Commerce succeeds for hanzo but 500s for acme;
+// the overview folds acme's failure into a not-ok commerce source (the SAME partial
+// pattern revenue/finance use) instead of the old single-probe that masked it.
+func TestOverview_CommercePartialOnPerOrgError(t *testing.T) {
+	iam := newFakeIAM()
+	defer iam.server.Close()
+	commerce := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		if r.Header.Get("X-Org-Id") == "acme" {
+			w.WriteHeader(500) // commerce down for THIS org only
+			io.WriteString(w, `{"status":"error","msg":"commerce down for acme"}`)
+			return
+		}
+		switch {
+		case strings.HasSuffix(r.URL.Path, "/usage-rollup"):
+			io.WriteString(w, `{"consumedCents":1500,"overageCents":0}`)
+		case strings.HasSuffix(r.URL.Path, "/balance"):
+			io.WriteString(w, `{"available":5000,"balance":5000}`)
+		default:
+			w.WriteHeader(404)
+		}
+	}))
+	defer commerce.Close()
+
+	do := mount(t, iam.server.URL, commerce.URL, "")
+	admin := map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin"}
+	resp, body := do("GET", "/v1/admin/overview", admin)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("overview: %d (%s)", resp.StatusCode, body)
+	}
+	var env struct {
+		Data overviewData `json:"data"`
+	}
+	if err := json.Unmarshal(body, &env); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	src := map[string]core.SourceStatus{}
+	for _, s := range env.Data.Sources {
+		src[s.Name] = s
+	}
+	c, ok := src["commerce"]
+	if !ok {
+		t.Fatal("overview must report a commerce source")
+	}
+	if c.OK {
+		t.Errorf("commerce source must be DEGRADED when a per-org read failed (undercount masked as healthy), got %+v", c)
+	}
+	if c.Error == "" {
+		t.Errorf("degraded commerce source must carry an error: %+v", c)
+	}
+	// The healthy org still contributes — an honest PARTIAL total, never a hard panel fail.
+	if env.Data.SpendCents30d != 1500 {
+		t.Errorf("spend = %d, want 1500 (only hanzo read; acme failed)", env.Data.SpendCents30d)
+	}
+}
+
 // TestUsage_RealTotalsHonestEmptySeries proves the usage roll-up returns the REAL
 // fleet spend from commerce but an HONEST empty series/byProduct — the timeseries
 // feed lives in insights/datastore, and admin must never fabricate a trend.

clients/admin/analytics.go

@@ -1,23 +1,15 @@
 package admin
 
 // Native SaaS business ANALYTICS (/v1/admin/analytics) — cohort retention, growth,
-// churn, active-customers (DAU/WAU/MAU), revenue (MRR/ARPU) and usage over time,
-// derived from REAL fleet data: IAM org `createdTime` (the signup cohort — always
-// available) + the commerce transaction ledger (usage = `withdraw` rows, the true
-// customer-activity signal). Global-admin only (s.guard), like every admin route.
+// churn, active-customers (DAU/WAU/MAU), revenue (MRR/ARPU) and usage over time, derived
+// from REAL fleet data: IAM org `createdTime` (the signup cohort) + the commerce
+// transaction ledger (usage = `withdraw` rows). SuperAdmin/org-scoped via GuardScoped.
 //
-// HONEST BY CONSTRUCTION. There is NO fabricated curve anywhere. Growth/cohorts
-// come from real signup timestamps; retention/active/churn/usage come from real
-// consumption events. A metric that cannot yet be computed (LTV needs observed
-// churn; NRR needs MRR history commerce does not expose point-in-time) returns a
-// null / honest-empty series — never an invented trend — and the `computed` map
-// flags exactly which metrics are backed by data, so the console renders honest
-// states and a reviewer can verify no number was made up.
-//
-// The heavy read (every org's ledger) is bounded + fanned out concurrently. Admin
-// is low-QPS; at fleet scale this belongs in the insights/datastore OLAP mirror
-// (same note as the usage series), but the billing ledger is the correct SOURCE
-// OF TRUTH for real per-customer activity today.
+// The fleet activity model + the continuous spend series live in clients/admin/core
+// (core.FleetActivity / core.SpendSeries / core.CustActivity / core.SeriesPoint) because
+// the revenue board reuses them — one implementation, DRY. This file holds only the
+// analytics-specific derivation (growth/retention/churn/active/LTV) that folds over that
+// shared model.
 
 import (
 	"context"
@@ -26,21 +18,17 @@ import (
 	"sync"
 	"time"
 
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/hanzoai/cloud/clients/admin/iam"
 	"github.com/zap-proto/zip"
 )
 
 // ── wire shapes (operator contract) ──────────────────────────────────────────
 
-// seriesPoint is one bucketed point (count OR cents, per the series). T is the
-// bucket key (RFC3339 date / "2006-01" month).
-type seriesPoint struct {
-	T     string `json:"t"`
-	Value int64  `json:"value"`
-}
-
-// retentionCohort is one row of the retention triangle: a signup cohort, its size,
-// and the % of it still ACTIVE at each subsequent period (values[0] = the signup
-// period itself). Percentages are 0..100.
+// retentionCohort is one row of the retention triangle: a signup cohort, its size, and
+// the % of it still ACTIVE at each subsequent period (values[0] = the signup period
+// itself). Percentages are 0..100.
 type retentionCohort struct {
 	Cohort string    `json:"cohort"`
 	Size   int       `json:"size"`
@@ -61,40 +49,39 @@ type analyticsData struct {
 	GeneratedAt string `json:"generatedAt"`
 
 	// Growth — from IAM createdTime (always real).
-	Signups             []seriesPoint `json:"signups"`
-	CumulativeCustomers []seriesPoint `json:"cumulativeCustomers"`
-	TotalCustomers      int           `json:"totalCustomers"`
-	NewCustomers        int           `json:"newCustomers"`
-	GrowthRatePct       float64       `json:"growthRatePct"`
+	Signups             []core.SeriesPoint `json:"signups"`
+	CumulativeCustomers []core.SeriesPoint `json:"cumulativeCustomers"`
+	TotalCustomers      int                `json:"totalCustomers"`
+	NewCustomers        int                `json:"newCustomers"`
+	GrowthRatePct       float64            `json:"growthRatePct"`
 
 	// Active customers — from the usage ledger.
-	ActiveCustomers []seriesPoint `json:"activeCustomers"`
-	DAU             int           `json:"dau"`
-	WAU             int           `json:"wau"`
-	MAU             int           `json:"mau"`
+	ActiveCustomers []core.SeriesPoint `json:"activeCustomers"`
+	DAU             int                `json:"dau"`
+	WAU             int                `json:"wau"`
+	MAU             int                `json:"mau"`
 
 	// Retention triangle — signup cohort × active period.
 	Retention retentionGrid `json:"retention"`
 
 	// Churn — logo churn (count) + rate.
-	Churn        []seriesPoint `json:"churn"`
-	ChurnRatePct float64       `json:"churnRatePct"`
+	Churn        []core.SeriesPoint `json:"churn"`
+	ChurnRatePct float64            `json:"churnRatePct"`
 
 	// Revenue analytics.
-	MRRCents      int64    `json:"mrrCents"`
-	Revenue       []seriesPoint `json:"revenue"`
-	ARPUCents     int64    `json:"arpuCents"`
-	LTVCents      *int64   `json:"ltvCents"` // null until churn is observed
-	NRRPct        *float64 `json:"nrrPct"`   // null — needs MRR history
+	MRRCents  int64              `json:"mrrCents"`
+	Revenue   []core.SeriesPoint `json:"revenue"`
+	ARPUCents int64              `json:"arpuCents"`
+	LTVCents  *int64             `json:"ltvCents"` // null until churn is observed
+	NRRPct    *float64           `json:"nrrPct"`   // null — needs MRR history
 
 	// Usage analytics.
-	Usage        []seriesPoint  `json:"usage"`
-	TopCustomers []analyticsSlice `json:"topCustomers"`
+	Usage        []core.SeriesPoint `json:"usage"`
+	TopCustomers []analyticsSlice   `json:"topCustomers"`
 
-	// Transparency: which metrics are backed by real data vs honest-empty. A
-	// reviewer/console reads this to know nothing was fabricated.
-	Computed map[string]bool `json:"computed"`
-	Sources  []sourceStatus  `json:"sources"`
+	// Transparency: which metrics are backed by real data vs honest-empty.
+	Computed map[string]bool     `json:"computed"`
+	Sources  []core.SourceStatus `json:"sources"`
 }
 
 // analyticsSlice is a labelled magnitude (top customers by usage cents).
@@ -104,75 +91,38 @@ type analyticsSlice struct {
 	Hint  string `json:"hint,omitempty"`
 }
 
-// ── the activity model the pure math folds over ──────────────────────────────
-
-// txnPoint is one dated usage event (a commerce `withdraw`, in cents).
-type txnPoint struct {
-	T     time.Time
-	Cents int64
-}
-
-// custActivity is one customer's real analytics input: when they signed up (IAM
-// createdTime) and their consumption events (commerce withdraws). Deposits are
-// NOT activity (a credit grant is not the customer using the product), so only
-// withdraws feed active/retention/churn/usage — the honest "used it" signal.
-type custActivity struct {
-	Org        string
-	Display    string
-	Created    time.Time
-	HasCreated bool
-	Usage      []txnPoint
-	SpendCents int64
-}
-
-func (ca custActivity) activeIn(bucket string, interval string) bool {
-	for _, p := range ca.Usage {
-		if bucketKeyOf(p.T, interval) == bucket {
-			return true
-		}
-	}
-	return false
-}
-
-func (ca custActivity) activeSince(cut time.Time) bool {
-	for _, p := range ca.Usage {
-		if !p.T.Before(cut) {
-			return true
-		}
-	}
-	return false
-}
-
 // ── handler ──────────────────────────────────────────────────────────────────
 
-func (s *svc) analytics(c *zip.Ctx) error {
+func analytics(s *cloud.Service[core.State], c *zip.Ctx) error {
 	ctx := c.Context()
-	cr := callerCreds(c)
+	cr := core.CallerCreds(c)
 	now := time.Now().UTC()
 	rangeStr := normalizeRange(c.Query("range"))
 	since, interval, _ := rangeWindow(rangeStr, now)
 
-	var sources []sourceStatus
+	var sources []core.SourceStatus
 
-	orgs, err := s.listOrgs(ctx, cr)
+	// Scoped fan-in: a SuperAdmin gets every org (all-orgs SaaS analytics); an org admin
+	// gets ONLY their own subtree — the ONE tenant-scope predicate (core.ScopedOrgs).
+	orgs, err := core.ScopedOrgs(s, ctx, c, cr)
 	if err != nil {
-		return fail(c, err.Error())
+		return core.Fail(c, err.Error())
 	}
-	sources = append(sources, srcOf("iam", nil, len(orgs), now.Format(time.RFC3339)))
+	sources = append(sources, core.SrcOf("iam", nil, len(orgs), now.Format(time.RFC3339)))
 
-	acts, ledgerOK := s.fleetActivity(ctx, orgs)
+	acts, ledgerOK := core.FleetActivity(s, ctx, orgs)
 	ledgerRows := 0
 	for _, a := range acts {
 		ledgerRows += len(a.Usage)
 	}
 	var ledgerErr error
 	if !ledgerOK {
-		ledgerErr = errPartialRevenue // partial ledger read — mark degraded
+		ledgerErr = core.ErrPartialRevenue // partial ledger read — mark degraded
 	}
-	sources = append(sources, srcOf("commerce-ledger", ledgerErr, ledgerRows, now.Format(time.RFC3339)))
+	sources = append(sources, core.SrcOf("commerce-ledger", ledgerErr, ledgerRows, now.Format(time.RFC3339)))
 
 	// MRR from subscriptions (point-in-time), fanned out like the money reads.
-	mrr := s.fleetMRR(ctx, orgs)
+	mrr := fleetMRR(s, ctx, orgs)
 
 	data := computeAnalytics(analyticsInput{
 		acts:     acts,
@@ -185,13 +135,13 @@ func (s *svc) analytics(c *zip.Ctx) error {
 	})
 	data.GeneratedAt = now.Format(time.RFC3339)
 	data.Sources = sources
-	return ok(c, data)
+	return core.OK(c, data)
 }
 
 // analyticsInput is everything computeAnalytics needs — no I/O, so the whole SaaS
 // analytics derivation is unit-testable without a network.
 type analyticsInput struct {
-	acts     []custActivity
+	acts     []core.CustActivity
 	mrrCents int64
 	now      time.Time
 	since    time.Time
@@ -202,19 +152,19 @@ type analyticsInput struct {
 
 // computeAnalytics is the PURE derivation of every analytics metric from the real
 // activity model. Growth is always computed (signup timestamps); the ledger-backed
-// metrics compute from real usage when present and degrade to honest empty/zero
-// when the fleet has no usage yet — never a fabricated curve. `computed` flags each.
+// metrics compute from real usage when present and degrade to honest empty/zero when the
+// fleet has no usage yet — never a fabricated curve. `computed` flags each.
 func computeAnalytics(in analyticsInput) analyticsData {
-	buckets := enumerateBuckets(in.since, in.now, in.interval)
+	buckets := core.EnumerateBuckets(in.since, in.now, in.interval)
 
 	// ── Growth (IAM createdTime — always real) ──
-	signups := make([]seriesPoint, len(buckets))
+	signups := make([]core.SeriesPoint, len(buckets))
 	newCount := 0
 	total := 0
 	for i, b := range buckets {
-		signups[i] = seriesPoint{T: b}
+		signups[i] = core.SeriesPoint{T: b}
 	}
-	idx := indexOf(buckets)
+	idx := core.IndexOf(buckets)
 	for _, a := range in.acts {
 		if !a.HasCreated {
 			continue
@@ -223,12 +173,12 @@ func computeAnalytics(in analyticsInput) analyticsData {
 		if !a.Created.Before(in.since) {
 			newCount++
 		}
-		if i, ok := idx[bucketKeyOf(a.Created, in.interval)]; ok {
+		if i, ok := idx[core.BucketKeyOf(a.Created, in.interval)]; ok {
 			signups[i].Value++
 		}
 	}
 	// Cumulative customers across the SAME buckets (all-time count at each bucket end).
-	cumulative := make([]seriesPoint, len(buckets))
+	cumulative := make([]core.SeriesPoint, len(buckets))
 	for i, b := range buckets {
 		end := bucketEnd(b, in.interval)
 		n := 0
@@ -237,15 +187,15 @@ func computeAnalytics(in analyticsInput) analyticsData {
 				n++
 			}
 		}
-		cumulative[i] = seriesPoint{T: b, Value: int64(n)}
+		cumulative[i] = core.SeriesPoint{T: b, Value: int64(n)}
 	}
 	growthRate := priorWindowGrowth(in.acts, in.since, in.now)
 
 	// ── Active customers + usage (ledger-backed) ──
-	usage := spendSeries(in.acts, in.since, in.now, in.interval)
-	active := make([]seriesPoint, len(buckets))
+	usage := core.SpendSeries(in.acts, in.since, in.now, in.interval)
+	active := make([]core.SeriesPoint, len(buckets))
 	for i, b := range buckets {
-		active[i] = seriesPoint{T: b}
+		active[i] = core.SeriesPoint{T: b}
 	}
 	for _, a := range in.acts {
 		// active in a bucket = at least one usage event in it
@@ -254,7 +204,7 @@ func computeAnalytics(in analyticsInput) analyticsData {
 			if p.T.Before(in.since) || p.T.After(in.now) {
 				continue
 			}
-			seen[bucketKeyOf(p.T, in.interval)] = true
+			seen[core.BucketKeyOf(p.T, in.interval)] = true
 		}
 		for b := range seen {
 			if i, ok := idx[b]; ok {
@@ -285,8 +235,7 @@ func computeAnalytics(in analyticsInput) analyticsData {
 	}
 	var ltv *int64
 	if churnRate > 0 && arpu > 0 {
-		// LTV ≈ ARPU / monthly churn rate — computed ONLY when real churn is
-		// observed, else honest null (LTV needs churn to mean anything).
+		// LTV ≈ ARPU / monthly churn rate — computed ONLY when real churn is observed.
 		v := int64(float64(arpu) / (churnRate / 100.0))
 		ltv = &v
 	}
@@ -296,7 +245,7 @@ func computeAnalytics(in analyticsInput) analyticsData {
 
 	// Revenue series = realized usage revenue per bucket (same as usage cents for a
 	// pay-as-you-go fleet; distinct field so the console can theme it as revenue).
-	revenue := make([]seriesPoint, len(usage))
+	revenue := make([]core.SeriesPoint, len(usage))
 	copy(revenue, usage)
 
 	return analyticsData{
@@ -336,18 +285,18 @@ func computeAnalytics(in analyticsInput) analyticsData {
 	}
 }
 
-// computeRetention builds the cohort × period retention triangle from real signup
-// months and usage months. retention[c][k] = fraction of cohort c ACTIVE in month
-// c+k. Cohorts are capped to the last `maxCohorts` months (the classic triangle);
-// a cohort with no signups is omitted. Values are 0..100.
-func computeRetention(acts []custActivity, now time.Time, maxCohorts int) retentionGrid {
+// computeRetention builds the cohort × period retention triangle from real signup months
+// and usage months. retention[c][k] = fraction of cohort c ACTIVE in month c+k. Cohorts
+// are capped to the last `maxCohorts` months; a cohort with no signups is omitted. Values
+// are 0..100.
+func computeRetention(acts []core.CustActivity, now time.Time, maxCohorts int) retentionGrid {
 	// Group customers by signup month.
-	byCohort := map[string][]custActivity{}
+	byCohort := map[string][]core.CustActivity{}
 	for _, a := range acts {
 		if !a.HasCreated {
 			continue
 		}
-		k := monthKey(a.Created)
+		k := core.MonthKey(a.Created)
 		byCohort[k] = append(byCohort[k], a)
 	}
 
@@ -361,7 +310,7 @@ func computeRetention(acts []custActivity, now time.Time, maxCohorts int) retent
 		cohorts = cohorts[len(cohorts)-maxCohorts:]
 	}
 
-	nowMonth := monthKey(now)
+	nowMonth := core.MonthKey(now)
 	grid := retentionGrid{Interval: "month"}
 	maxPeriods := 0
 	for _, cohort := range cohorts {
@@ -375,7 +324,7 @@ func computeRetention(acts []custActivity, now time.Time, maxCohorts int) retent
 			month := addMonths(cohort, k)
 			activeN := 0
 			for _, m := range members {
-				if m.activeIn(month, "month") {
+				if m.ActiveIn(month, "month") {
 					activeN++
 				}
 			}
@@ -392,17 +341,16 @@ func computeRetention(acts []custActivity, now time.Time, maxCohorts int) retent
 	return grid
 }
 
-// computeChurn derives monthly LOGO churn: a customer counts as churned in month M
-// if they were active in M-1 but NOT in M. The rate is the average monthly churn
-// over the observed window (churned / active-at-start). Returns honest zeros when
-// there is no usage history.
-func computeChurn(acts []custActivity, now time.Time, months int) ([]seriesPoint, float64) {
+// computeChurn derives monthly LOGO churn: a customer counts as churned in month M if
+// they were active in M-1 but NOT in M. The rate is the average monthly churn over the
+// observed window. Returns honest zeros when there is no usage history.
+func computeChurn(acts []core.CustActivity, now time.Time, months int) ([]core.SeriesPoint, float64) {
 	// Build the last `months` month keys ending at now.
 	keys := lastMonths(now, months)
-	series := make([]seriesPoint, len(keys))
+	series := make([]core.SeriesPoint, len(keys))
 	var churnedTotal, baseTotal int
 	for i, m := range keys {
-		series[i] = seriesPoint{T: m}
+		series[i] = core.SeriesPoint{T: m}
 		if i == 0 {
 			continue // no prior month to compare
 		}
@@ -410,10 +358,10 @@ func computeChurn(acts []custActivity, now time.Time, months int) ([]seriesPoint
 		churned := 0
 		base := 0
 		for _, a := range acts {
-			wasActive := a.activeIn(prev, "month")
+			wasActive := a.ActiveIn(prev, "month")
 			if wasActive {
 				base++
-				if !a.activeIn(m, "month") {
+				if !a.ActiveIn(m, "month") {
 					churned++
 				}
 			}
@@ -429,31 +377,8 @@ func computeChurn(acts []custActivity, now time.Time, months int) ([]seriesPoint
 	return series, rate
 }
 
-// spendSeries buckets fleet usage cents into a continuous series over since..now.
-// Shared by the analytics usage/revenue trend and the revenue board's spend trend
-// (one implementation, DRY). A bucket with no usage is an honest 0, not a gap.
-func spendSeries(acts []custActivity, since, now time.Time, interval string) []seriesPoint {
-	buckets := enumerateBuckets(since, now, interval)
-	idx := indexOf(buckets)
-	out := make([]seriesPoint, len(buckets))
-	for i, b := range buckets {
-		out[i] = seriesPoint{T: b}
-	}
-	for _, a := range acts {
-		for _, p := range a.Usage {
-			if p.T.Before(since) || p.T.After(now) {
-				continue
-			}
-			if i, ok := idx[bucketKeyOf(p.T, interval)]; ok {
-				out[i].Value += p.Cents
-			}
-		}
-	}
-	return out
-}
-
 // topCustomersByUsage returns the top-N customers by total usage cents (desc).
-func topCustomersByUsage(acts []custActivity, n int) []analyticsSlice {
+func topCustomersByUsage(acts []core.CustActivity, n int) []analyticsSlice {
 	rows := make([]analyticsSlice, 0, len(acts))
 	for _, a := range acts {
 		if a.SpendCents <= 0 {
@@ -468,9 +393,9 @@ func topCustomersByUsage(acts []custActivity, n int) []analyticsSlice {
 	return rows
 }
 
-// priorWindowGrowth is the signup growth vs the immediately-preceding window: the
-// % change in new signups this window vs last. 0 when the prior window had none.
-func priorWindowGrowth(acts []custActivity, since, now time.Time) float64 {
+// priorWindowGrowth is the signup growth vs the immediately-preceding window: the %
+// change in new signups this window vs last. 0 when the prior window had none.
+func priorWindowGrowth(acts []core.CustActivity, since, now time.Time) float64 {
 	window := now.Sub(since)
 	priorStart := since.Add(-window)
 	cur, prev := 0, 0
@@ -491,83 +416,29 @@ func priorWindowGrowth(acts []custActivity, since, now time.Time) float64 {
 }
 
 // activeWithin counts customers with at least one usage event since `cut`.
-func activeWithin(acts []custActivity, cut time.Time) int {
+func activeWithin(acts []core.CustActivity, cut time.Time) int {
 	n := 0
 	for _, a := range acts {
-		if a.activeSince(cut) {
+		if a.ActiveSince(cut) {
 			n++
 		}
 	}
 	return n
 }
 
-// ── fleet readers (I/O; concurrent, bounded) ─────────────────────────────────
-
-// fleetActivity reads every org's signup time (already on the org row) + usage
-// ledger, folded into the pure activity model. Returns (acts, ok) where ok is
-// false if ANY org's ledger read failed (the caller marks the source degraded and
-// flags the ledger-backed metrics as not-fully-computed). Fanned out concurrently
-// with a bound, like the customer list.
-func (s *svc) fleetActivity(ctx context.Context, orgs []iamOrg) ([]custActivity, bool) {
-	acts := make([]custActivity, len(orgs))
-	oks := make([]bool, len(orgs))
-	sem := make(chan struct{}, maxCustomerConcurrency)
-	var wg sync.WaitGroup
-	for i, o := range orgs {
-		wg.Add(1)
-		sem <- struct{}{}
-		go func(i int, o iamOrg) {
-			defer wg.Done()
-			defer func() { <-sem }()
-			ca := custActivity{Org: o.Name, Display: display(o.DisplayName, o.Name)}
-			if t, err := time.Parse(time.RFC3339, o.CreatedTime); err == nil {
-				ca.Created = t.UTC()
-				ca.HasCreated = true
-			}
-			rows, err := s.commerce.transactions(ctx, o.Name, orgSubject(o.Name), 2000)
-			oks[i] = err == nil
-			for _, r := range rows {
-				if strings.ToLower(r.Type) != "withdraw" {
-					continue // only consumption is "activity"; deposits are credits
-				}
-				t, perr := parseTxnTime(r.CreatedAt)
-				if perr != nil {
-					continue
-				}
-				amt := r.Amount
-				if amt < 0 {
-					amt = -amt
-				}
-				ca.Usage = append(ca.Usage, txnPoint{T: t, Cents: amt})
-				ca.SpendCents += amt
-			}
-			acts[i] = ca
-		}(i, o)
-	}
-	wg.Wait()
-	allOK := true
-	for _, ok := range oks {
-		if !ok {
-			allOK = false
-			break
-		}
-	}
-	return acts, allOK
-}
-
 // fleetMRR sums each org's active-subscription MRR concurrently.
-func (s *svc) fleetMRR(ctx context.Context, orgs []iamOrg) int64 {
+func fleetMRR(s *cloud.Service[core.State], ctx context.Context, orgs []iam.Org) int64 {
 	vals := make([]int64, len(orgs))
-	sem := make(chan struct{}, maxCustomerConcurrency)
+	sem := make(chan struct{}, core.MaxCustomerConcurrency)
 	var wg sync.WaitGroup
 	for i, o := range orgs {
 		wg.Add(1)
 		sem <- struct{}{}
-		go func(i int, o iamOrg) {
+		go func(i int, o iam.Org) {
 			defer wg.Done()
 			defer func() { <-sem }()
-			if sum, err := s.commerce.subscriptionSummary(ctx, o.Name, orgSubject(o.Name)); err == nil {
-				vals[i] = sum.MRR
+			if pl, err := s.State.Commerce.Plan(ctx, o.Name); err == nil {
+				vals[i] = int64(pl.MRR)
 			}
 		}(i, o)
 	}
@@ -579,36 +450,10 @@ func (s *svc) fleetMRR(ctx context.Context, orgs []iamOrg) int64 {
 	return total
 }
 
-// ── pure time-bucket helpers ─────────────────────────────────────────────────
+// ── analytics-specific month arithmetic (the shared bucket keys live in core) ──
 
-func monthKey(t time.Time) string { return t.UTC().Format("2006-01") }
-func dayKey(t time.Time) string   { return t.UTC().Format("2006-01-02") }
-
-// weekKey buckets to the ISO week's Monday (a stable weekly key).
-func weekKey(t time.Time) string {
-	u := t.UTC()
-	// back up to Monday
-	wd := int(u.Weekday())
-	if wd == 0 {
-		wd = 7
-	}
-	monday := u.AddDate(0, 0, -(wd - 1))
-	return monday.Format("2006-01-02")
-}
-
-func bucketKeyOf(t time.Time, interval string) string {
-	switch interval {
-	case "month":
-		return monthKey(t)
-	case "week":
-		return weekKey(t)
-	default:
-		return dayKey(t)
-	}
-}
-
-// bucketEnd returns the inclusive end instant of a bucket key (for the cumulative
-// count). A day/week/month key advances one unit; the end is one nanosecond before.
+// bucketEnd returns the inclusive end instant of a bucket key (for the cumulative count).
+// A day/week/month key advances one unit; the end is one nanosecond before.
 func bucketEnd(key, interval string) time.Time {
 	switch interval {
 	case "month":
@@ -627,48 +472,6 @@ func bucketEnd(key, interval string) time.Time {
 	return time.Now().UTC()
 }
 
-// enumerateBuckets lists every bucket key from since..now inclusive so a series has
-// a continuous axis (a zero-usage bucket is an honest 0, not a gap).
-func enumerateBuckets(since, now time.Time, interval string) []string {
-	if since.After(now) {
-		return nil
-	}
-	var out []string
-	seen := map[string]bool{}
-	step := func(t time.Time) time.Time {
-		switch interval {
-		case "month":
-			return t.AddDate(0, 1, 0)
-		case "week":
-			return t.AddDate(0, 0, 7)
-		default:
-			return t.AddDate(0, 0, 1)
-		}
-	}
-	// cap iterations so a bad range can never spin unbounded
-	for t, n := since, 0; !t.After(now) && n < 800; t, n = step(t), n+1 {
-		k := bucketKeyOf(t, interval)
-		if !seen[k] {
-			seen[k] = true
-			out = append(out, k)
-		}
-	}
-	// ensure the final bucket (now) is present
-	last := bucketKeyOf(now, interval)
-	if !seen[last] {
-		out = append(out, last)
-	}
-	return out
-}
-
-func indexOf(buckets []string) map[string]int {
-	m := make(map[string]int, len(buckets))
-	for i, b := range buckets {
-		m[b] = i
-	}
-	return m
-}
-
 // addMonths adds k months to a "2006-01" key.
 func addMonths(month string, k int) string {
 	t, err := time.Parse("2006-01", month)
@@ -692,7 +495,7 @@ func monthsBetween(a, b string) int {
 func lastMonths(now time.Time, n int) []string {
 	out := make([]string, 0, n)
 	for i := n - 1; i >= 0; i-- {
-		out = append(out, monthKey(now.AddDate(0, -i, 0)))
+		out = append(out, core.MonthKey(now.AddDate(0, -i, 0)))
 	}
 	return out
 }
@@ -704,15 +507,6 @@ func pct(part, whole int) float64 {
 	return (float64(part) / float64(whole)) * 100
 }
 
-// parseTxnTime accepts the commerce ledger's RFC3339 forms.
-func parseTxnTime(s string) (time.Time, error) {
-	s = strings.TrimSpace(s)
-	if t, err := time.Parse(time.RFC3339, s); err == nil {
-		return t.UTC(), nil
-	}
-	return time.Parse("2006-01-02T15:04:05Z", s)
-}
-
 // normalizeRange clamps the range param to the supported set (default 30d).
 func normalizeRange(r string) string {
 	switch strings.TrimSpace(r) {

clients/admin/analytics_math_test.go

@@ -4,6 +4,8 @@ import (
 	"math"
 	"testing"
 	"time"
+
+	"github.com/hanzoai/cloud/clients/admin/core"
 )
 
 // mkTime is a test helper for an RFC3339-ish instant.
@@ -21,14 +23,14 @@ func mkTime(s string) time.Time {
 //	alpha: signup 2024-05-10; usage 2024-05-20 (100c), 2024-06-05 (200c)  [cohort 05, active 05+06]
 //	beta : signup 2024-05-25; usage 2024-05-28 (50c)                       [cohort 05, active 05 only]
 //	gamma: signup 2024-06-15; usage 2024-07-01 (400c)                      [cohort 06, active 07 only]
-func fleetFixture() []custActivity {
-	return []custActivity{
+func fleetFixture() []core.CustActivity {
+	return []core.CustActivity{
 		{Org: "alpha", Display: "Alpha", Created: mkTime("2024-05-10"), HasCreated: true,
-			Usage: []txnPoint{{T: mkTime("2024-05-20"), Cents: 100}, {T: mkTime("2024-06-05"), Cents: 200}}, SpendCents: 300},
+			Usage: []core.TxnPoint{{T: mkTime("2024-05-20"), Cents: 100}, {T: mkTime("2024-06-05"), Cents: 200}}, SpendCents: 300},
 		{Org: "beta", Display: "Beta", Created: mkTime("2024-05-25"), HasCreated: true,
-			Usage: []txnPoint{{T: mkTime("2024-05-28"), Cents: 50}}, SpendCents: 50},
+			Usage: []core.TxnPoint{{T: mkTime("2024-05-28"), Cents: 50}}, SpendCents: 50},
 		{Org: "gamma", Display: "Gamma", Created: mkTime("2024-06-15"), HasCreated: true,
-			Usage: []txnPoint{{T: mkTime("2024-07-01"), Cents: 400}}, SpendCents: 400},
+			Usage: []core.TxnPoint{{T: mkTime("2024-07-01"), Cents: 400}}, SpendCents: 400},
 	}
 }
 
@@ -215,10 +217,10 @@ func TestComputeAnalytics_HonestEmptyNoLedger(t *testing.T) {
 func TestSpendSeries_ContinuousHonestBuckets(t *testing.T) {
 	now := mkTime("2024-07-05")
 	since := mkTime("2024-07-01")
-	acts := []custActivity{
-		{Usage: []txnPoint{{T: mkTime("2024-07-01"), Cents: 100}, {T: mkTime("2024-07-03"), Cents: 300}}},
+	acts := []core.CustActivity{
+		{Usage: []core.TxnPoint{{T: mkTime("2024-07-01"), Cents: 100}, {T: mkTime("2024-07-03"), Cents: 300}}},
 	}
-	series := spendSeries(acts, since, now, "day")
+	series := core.SpendSeries(acts, since, now, "day")
 	// 5 daily buckets 07-01..07-05.
 	if len(series) != 5 {
 		t.Fatalf("series buckets = %d, want 5 (%+v)", len(series), series)

clients/admin/audit.go

@@ -1,182 +0,0 @@
-package admin
-
-// The /v1/admin/audit query surface, wired to cloud's REAL tamper-evident audit
-// store (the audit.Recorder Serve builds and hands over via deps.Audit).
-//
-// This REPLACES the previous behavior — proxying IAM get-records — as the primary
-// source: cloud now keeps its OWN append-only, hash-chained trail of every
-// security-relevant request against this binary, and that is what a compliance
-// auditor queries here. IAM's own login/session records remain available in IAM;
-// they are a DIFFERENT trail (IAM's request surface), and admin still federates
-// them as a fallback when cloud's local store is not configured, so no capability
-// is lost.
-//
-// SECURITY. Both handlers are registered behind the SAME s.guard as every other
-// /v1/admin/* route (global-admin only, fail-closed). They are READ-ONLY (Query
-// and Verify issue SELECT only), so exposing them cannot weaken the append-only
-// property. The verify endpoint returns integrity STATUS, never a way to mutate.
-
-import (
-	"strconv"
-	"strings"
-	"time"
-
-	"github.com/hanzoai/cloud/audit"
-	"github.com/zap-proto/zip"
-)
-
-// auditRow is one record in the operator's audit table (AuditRow). The JSON tags
-// are the operator contract. It is cloud's OWN record shape — richer than the IAM
-// Record it supersedes: it carries the outcome, the validated auth context, and
-// the hash-chain linkage so the console can show integrity per row.
-type auditRow struct {
-	Seq        uint64 `json:"seq"`
-	Time       string `json:"time"`
-	Org        string `json:"org"`
-	Sub        string `json:"sub"`
-	Email      string `json:"email,omitempty"`
-	Action     string `json:"action"`
-	Resource   string `json:"resource"`
-	ResourceID string `json:"resourceId,omitempty"`
-	Method     string `json:"method,omitempty"`
-	Path       string `json:"path,omitempty"`
-	Result     string `json:"result"`
-	Status     int    `json:"status"`
-	Reason     string `json:"reason,omitempty"`
-	SourceIP   string `json:"sourceIp,omitempty"`
-	UserAgent  string `json:"userAgent,omitempty"`
-	RequestID  string `json:"requestId,omitempty"`
-	IsAdmin    bool   `json:"isAdmin"`
-	Auth       string `json:"authMethod,omitempty"`
-	Hash       string `json:"hash"`
-	PrevHash   string `json:"prevHash"`
-}
-
-// audit answers GET /v1/admin/audit from cloud's local tamper-evident store when
-// configured, else falls back to the IAM get-records proxy (federated view).
-// Filters: org, sub, action, resource, result, since, until, pageSize, p (page).
-// The response is the /v1 list envelope { data:[rows], data2:total } the
-// operator decodes, with the current chain integrity summary attached.
-func (s *svc) audit(c *zip.Ctx) error {
-	// No local store configured → preserve the legacy federated IAM view so the
-	// endpoint never regresses to empty.
-	if s.auditStore == nil {
-		return s.auditFromIAM(c)
-	}
-
-	f := auditFilterFromQuery(c)
-	rows, total, err := s.auditStore.Query(c.Context(), f)
-	if err != nil {
-		return fail(c, err.Error())
-	}
-
-	out := make([]auditRow, 0, len(rows))
-	for _, r := range rows {
-		out = append(out, toAuditRow(r))
-	}
-
-	// Attach the live integrity summary so the console can badge the trail as
-	// verified. Best-effort: a verify error must not fail the listing.
-	integrity, ivErr := s.auditStore.Verify(c.Context())
-	var integrityPayload any
-	if ivErr == nil {
-		integrityPayload = integrity
-	}
-
-	return c.JSON(200, map[string]any{
-		"status":    "ok",
-		"msg":       "",
-		"data":      out,
-		"data2":     total,
-		"integrity": integrityPayload,
-	})
-}
-
-// auditVerify answers GET /v1/admin/audit/verify — the tamper-evidence check. It
-// walks the whole hash chain and returns the integrity result (ok, count, head,
-// and the seq where the chain first breaks if tampered). Global-admin gated like
-// every admin route.
-func (s *svc) auditVerify(c *zip.Ctx) error {
-	if s.auditStore == nil {
-		return fail(c, "audit store not configured")
-	}
-	integrity, err := s.auditStore.Verify(c.Context())
-	if err != nil {
-		return fail(c, err.Error())
-	}
-	return ok(c, integrity)
-}
-
-// auditFilterFromQuery builds an audit.Filter from the request query params. Time
-// bounds accept RFC3339. pageSize (default 100, cap 1000) and p (1-based page)
-// drive Limit/Offset. Unknown/blank params are simply not applied.
-func auditFilterFromQuery(c *zip.Ctx) audit.Filter {
-	f := audit.Filter{
-		Org:      strings.TrimSpace(c.Query("org")),
-		Sub:      strings.TrimSpace(c.Query("sub")),
-		Action:   strings.TrimSpace(c.Query("action")),
-		Resource: strings.TrimSpace(c.Query("resource")),
-		Result:   strings.TrimSpace(c.Query("result")),
-	}
-	if v := strings.TrimSpace(c.Query("since")); v != "" {
-		if t, err := time.Parse(time.RFC3339, v); err == nil {
-			f.Since = t
-		}
-	}
-	if v := strings.TrimSpace(c.Query("until")); v != "" {
-		if t, err := time.Parse(time.RFC3339, v); err == nil {
-			f.Until = t
-		}
-	}
-	pageSize := 100
-	if v := strings.TrimSpace(c.Query("pageSize")); v != "" {
-		if n, err := strconv.Atoi(v); err == nil && n > 0 {
-			pageSize = n
-		}
-	}
-	f.Limit = pageSize
-	if v := strings.TrimSpace(c.Query("p")); v != "" {
-		if page, err := strconv.Atoi(v); err == nil && page > 1 {
-			f.Offset = (page - 1) * pageSize
-		}
-	}
-	return f
-}
-
-// toAuditRow maps a stored audit.Record to the operator wire row.
-func toAuditRow(r audit.Record) auditRow {
-	return auditRow{
-		Seq:        r.Seq,
-		Time:       r.Time.UTC().Format(time.RFC3339Nano),
-		Org:        r.Actor.Org,
-		Sub:        r.Actor.Sub,
-		Email:      r.Actor.Email,
-		Action:     r.Action,
-		Resource:   r.Resource.Type,
-		ResourceID: r.Resource.ID,
-		Method:     r.Method,
-		Path:       r.Path,
-		Result:     r.Outcome.Result,
-		Status:     r.Outcome.Status,
-		Reason:     r.Outcome.Reason,
-		SourceIP:   r.SourceIP,
-		UserAgent:  r.UserAgent,
-		RequestID:  r.RequestID,
-		IsAdmin:    r.Auth.IsAdmin,
-		Auth:       r.Auth.Method,
-		Hash:       r.Hash,
-		PrevHash:   r.PrevHash,
-	}
-}
-
-// auditFromIAM is the legacy federated view: when cloud has no local audit store,
-// forward the IAM get-records read verbatim (the prior behavior), so the endpoint
-// still surfaces IAM's own audit trail rather than an empty list.
-func (s *svc) auditFromIAM(c *zip.Ctx) error {
-	q := iamAuditQuery(c)
-	res, err := s.iam.getList(c.Context(), callerCreds(c), "/v1/iam/get-records", q)
-	if err != nil {
-		return fail(c, err.Error())
-	}
-	return okRaw(c, res.rows, res.total)
-}

clients/admin/audit/audit.go

@@ -0,0 +1,151 @@
+// Package audit is the /v1/admin/audit query surface, wired to cloud's REAL
+// tamper-evident audit store (the audit.Recorder Serve builds and hands over via
+// deps.Audit).
+//
+// cloud keeps its OWN append-only, hash-chained trail of every security-relevant
+// request against this binary, and that is what a compliance auditor queries here. IAM's
+// own login/session records remain a DIFFERENT trail; admin still federates them as a
+// fallback when cloud's local store is not configured, so no capability is lost.
+//
+// SECURITY. Both handlers are registered behind core.Guard (SuperAdmin only,
+// fail-closed). They are READ-ONLY (Query and Verify issue SELECT only), so exposing
+// them cannot weaken the append-only property.
+package audit
+
+import (
+	"net/url"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/hanzoai/cloud"
+	auditstore "github.com/hanzoai/cloud/audit"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/zap-proto/zip"
+)
+
+// Routes registers the /v1/admin/audit* surface (SuperAdmin only).
+func Routes(app *zip.App, s *cloud.Service[core.State]) {
+	app.Get("/v1/admin/audit", core.Guard(s, Records))
+	app.Get("/v1/admin/audit/verify", core.Guard(s, Verify))
+}
+
+// Records answers GET /v1/admin/audit from cloud's local tamper-evident store when
+// configured, else falls back to the IAM get-records proxy (federated view). Filters:
+// org, sub, action, resource, result, since, until, pageSize, p (page). The response is
+// the /v1 list envelope { data:[rows], data2:total } with the current chain integrity
+// summary attached.
+func Records(s *cloud.Service[core.State], c *zip.Ctx) error {
+	// No local store configured → preserve the legacy federated IAM view so the endpoint
+	// never regresses to empty.
+	if s.State.AuditStore == nil {
+		return fromIAM(s, c)
+	}
+
+	f := auditFilterFromQuery(c)
+	rows, total, err := s.State.AuditStore.Query(c.Context(), f)
+	if err != nil {
+		return core.Fail(c, err.Error())
+	}
+
+	out := make([]auditstore.Wire, 0, len(rows))
+	for _, r := range rows {
+		out = append(out, r.ToWire())
+	}
+
+	// Attach the live integrity summary so the console can badge the trail as verified.
+	// Best-effort: a verify error must not fail the listing.
+	integrity, ivErr := s.State.AuditStore.Verify(c.Context())
+	var integrityPayload any
+	if ivErr == nil {
+		integrityPayload = integrity
+	}
+
+	return c.JSON(200, map[string]any{
+		"status":    "ok",
+		"msg":       "",
+		"data":      out,
+		"data2":     total,
+		"integrity": integrityPayload,
+	})
+}
+
+// Verify answers GET /v1/admin/audit/verify — the tamper-evidence check. It walks the
+// whole hash chain and returns the integrity result (ok, count, head, and the seq where
+// the chain first breaks if tampered).
+func Verify(s *cloud.Service[core.State], c *zip.Ctx) error {
+	if s.State.AuditStore == nil {
+		return core.Fail(c, "audit store not configured")
+	}
+	integrity, err := s.State.AuditStore.Verify(c.Context())
+	if err != nil {
+		return core.Fail(c, err.Error())
+	}
+	return core.OK(c, integrity)
+}
+
+// auditFilterFromQuery builds an audit.Filter from the request query params. Time bounds
+// accept RFC3339. pageSize (default 100) and p (1-based page) drive Limit/Offset.
+// Unknown/blank params are simply not applied.
+func auditFilterFromQuery(c *zip.Ctx) auditstore.Filter {
+	f := auditstore.Filter{
+		Org:        strings.TrimSpace(c.Query("org")),
+		Sub:        strings.TrimSpace(c.Query("sub")),
+		Action:     strings.TrimSpace(c.Query("action")),
+		Resource:   strings.TrimSpace(c.Query("resource")),
+		ResourceID: strings.TrimSpace(c.Query("resourceId")),
+		Result:     strings.TrimSpace(c.Query("result")),
+	}
+	if v := strings.TrimSpace(c.Query("since")); v != "" {
+		if t, err := time.Parse(time.RFC3339, v); err == nil {
+			f.Since = t
+		}
+	}
+	if v := strings.TrimSpace(c.Query("until")); v != "" {
+		if t, err := time.Parse(time.RFC3339, v); err == nil {
+			f.Until = t
+		}
+	}
+	pageSize := 100
+	if v := strings.TrimSpace(c.Query("pageSize")); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n > 0 {
+			pageSize = n
+		}
+	}
+	f.Limit = pageSize
+	if v := strings.TrimSpace(c.Query("p")); v != "" {
+		if page, err := strconv.Atoi(v); err == nil && page > 1 {
+			f.Offset = (page - 1) * pageSize
+		}
+	}
+	return f
+}
+
+// fromIAM is the legacy federated view: when cloud has no local audit store, forward the
+// IAM get-records read verbatim (the prior behavior), so the endpoint still surfaces
+// IAM's own audit trail rather than an empty list.
+func fromIAM(s *cloud.Service[core.State], c *zip.Ctx) error {
+	q := iamAuditQuery(c)
+	res, err := s.State.IAM.List(c.Context(), core.CallerCreds(c), "/v1/iam/get-records", q)
+	if err != nil {
+		return core.Fail(c, err.Error())
+	}
+	return core.OKRaw(c, res.Rows, res.Total)
+}
+
+// iamAuditQuery builds the IAM get-records query for the federated fallback.
+func iamAuditQuery(c *zip.Ctx) url.Values {
+	q := url.Values{}
+	if org := strings.TrimSpace(c.Query("org")); org != "" {
+		q.Set("organizationName", org)
+	}
+	q.Set("p", "1")
+	ps := strings.TrimSpace(c.Query("pageSize"))
+	if ps == "" {
+		ps = "100"
+	}
+	q.Set("pageSize", ps)
+	q.Set("sortField", "createdTime")
+	q.Set("sortOrder", "descend")
+	return q
+}

clients/admin/audit/audit_test.go

@@ -1,9 +1,9 @@
-package admin
+package audit
 
-// Tests for the store-backed /v1/admin/audit + /v1/admin/audit/verify surface.
-// They wire admin against a REAL audit.Recorder (on-disk SQLite) seeded with
-// records, drive requests through the whole zip app, and assert the query
-// results, the integrity summary, and the global-admin gate.
+// Tests for the store-backed /v1/admin/audit + /v1/admin/audit/verify surface. They wire
+// the audit domain against a REAL audit.Recorder (on-disk SQLite) seeded with records,
+// drive requests through the whole zip app, and assert the query results, the integrity
+// summary, and the SuperAdmin gate.
 
 import (
 	"context"
@@ -15,29 +15,29 @@ import (
 	"testing"
 	"time"
 
-	fiber "github.com/gofiber/fiber/v3"
-	"github.com/hanzoai/cloud/audit"
-	"github.com/zap-proto/zip"
+	"github.com/hanzoai/cloud"
+	auditstore "github.com/hanzoai/cloud/audit"
+	"github.com/hanzoai/cloud/clients/admin/core"
 	luxlog "github.com/luxfi/log"
+	fiber "github.com/zap-proto/fiber/v3"
+	"github.com/zap-proto/zip"
 )
 
-// mountWithStore builds a zip app with admin's audit routes wired to a real audit
-// store, and returns the store + a request helper. Only the audit routes are
-// mounted here (the rest are covered by mount()); this keeps the store-backed
-// tests focused.
-func mountWithStore(t *testing.T) (*audit.Recorder, func(method, path string, hdr map[string]string) (*http.Response, []byte)) {
+// mountWithStore builds a zip app with the audit routes wired to a real audit store, and
+// returns the store + a request helper. Only the audit routes are mounted here.
+func mountWithStore(t *testing.T) (*auditstore.Recorder, func(method, path string, hdr map[string]string) (*http.Response, []byte)) {
 	t.Helper()
 	path := filepath.Join(t.TempDir(), "audit.db")
-	rec, err := audit.Open(path, nil)
+	rec, err := auditstore.Open(path, nil)
 	if err != nil {
 		t.Fatalf("audit.Open: %v", err)
 	}
 	t.Cleanup(func() { _ = rec.Close() })
 
 	app := zip.New(zip.Config{Logger: luxlog.New("test")})
-	s := &svc{adminOrg: "admin", auditStore: rec}
-	app.Get("/v1/admin/audit", s.guard(s.audit))
-	app.Get("/v1/admin/audit/verify", s.guard(s.auditVerify))
+	s := &cloud.Service[core.State]{State: core.State{AdminOrg: "admin", AuditStore: rec}}
+	app.Get("/v1/admin/audit", core.Guard(s, Records))
+	app.Get("/v1/admin/audit/verify", core.Guard(s, Verify))
 	fa := app.Fiber()
 
 	do := func(method, p string, hdr map[string]string) (*http.Response, []byte) {
@@ -56,17 +56,17 @@ func mountWithStore(t *testing.T) (*audit.Recorder, func(method, path string, hd
 	return rec, do
 }
 
-func seedAudit(t *testing.T, rec *audit.Recorder, n int) {
+func seedAudit(t *testing.T, rec *auditstore.Recorder, n int) {
 	t.Helper()
 	ctx := context.Background()
 	for i := 0; i < n; i++ {
-		_, err := rec.Append(ctx, audit.Record{
+		_, err := rec.Append(ctx, auditstore.Record{
 			Time:     time.Now().UTC(),
-			Actor:    audit.Actor{Org: "admin", Sub: "z@hanzo.ai"},
+			Actor:    auditstore.Actor{Org: "admin", Sub: "z@hanzo.ai"},
 			Action:   "DELETE /v1/admin/orgs",
-			Resource: audit.Resource{Type: "org", ID: "acme"},
-			Auth:     audit.AuthContext{Method: "jwt", IsAdmin: true},
-			Outcome:  audit.Outcome{Result: "success", Status: 200},
+			Resource: auditstore.Resource{Type: "org", ID: "acme"},
+			Auth:     auditstore.AuthContext{Method: "jwt", IsAdmin: true},
+			Outcome:  auditstore.Outcome{Result: "success", Status: 200},
 			Method:   "DELETE",
 			Path:     "/v1/admin/orgs/acme",
 		})
@@ -76,15 +76,15 @@ func seedAudit(t *testing.T, rec *audit.Recorder, n int) {
 	}
 }
 
-var globalAdmin = map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin", "X-User-Id": "z@hanzo.ai"}
+var superAdmin = map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin", "X-User-Id": "z@hanzo.ai"}
 
-// TestAdminAudit_ReturnsRealRecords proves GET /v1/admin/audit returns the
-// store's records (newest-first) with an accurate total and an integrity summary.
+// TestAdminAudit_ReturnsRealRecords proves GET /v1/admin/audit returns the store's
+// records (newest-first) with an accurate total and an integrity summary.
 func TestAdminAudit_ReturnsRealRecords(t *testing.T) {
 	rec, do := mountWithStore(t)
 	seedAudit(t, rec, 5)
 
-	resp, body := do("GET", "/v1/admin/audit", globalAdmin)
+	resp, body := do("GET", "/v1/admin/audit", superAdmin)
 	if resp.StatusCode != http.StatusOK {
 		t.Fatalf("audit: got %d (body=%s)", resp.StatusCode, body)
 	}
@@ -123,10 +123,10 @@ func TestAdminAudit_Filters(t *testing.T) {
 	rec, do := mountWithStore(t)
 	ctx := context.Background()
 	// One deny among successes.
-	_, _ = rec.Append(ctx, audit.Record{Action: "POST /v1/admin/roles", Actor: audit.Actor{Org: "admin"}, Outcome: audit.Outcome{Result: "deny", Status: 403}})
+	_, _ = rec.Append(ctx, auditstore.Record{Action: "POST /v1/admin/roles", Actor: auditstore.Actor{Org: "admin"}, Outcome: auditstore.Outcome{Result: "deny", Status: 403}})
 	seedAudit(t, rec, 3)
 
-	resp, body := do("GET", "/v1/admin/audit?result=deny", globalAdmin)
+	resp, body := do("GET", "/v1/admin/audit?result=deny", superAdmin)
 	if resp.StatusCode != http.StatusOK {
 		t.Fatalf("got %d (body=%s)", resp.StatusCode, body)
 	}
@@ -143,13 +143,13 @@ func TestAdminAudit_Filters(t *testing.T) {
 	}
 }
 
-// TestAdminAudit_VerifyEndpoint proves GET /v1/admin/audit/verify returns the
-// integrity result for the chain.
+// TestAdminAudit_VerifyEndpoint proves GET /v1/admin/audit/verify returns the integrity
+// result for the chain.
 func TestAdminAudit_VerifyEndpoint(t *testing.T) {
 	rec, do := mountWithStore(t)
 	seedAudit(t, rec, 8)
 
-	resp, body := do("GET", "/v1/admin/audit/verify", globalAdmin)
+	resp, body := do("GET", "/v1/admin/audit/verify", superAdmin)
 	if resp.StatusCode != http.StatusOK {
 		t.Fatalf("verify: got %d (body=%s)", resp.StatusCode, body)
 	}
@@ -172,12 +172,9 @@ func TestAdminAudit_VerifyEndpoint(t *testing.T) {
 	}
 }
 
-// TestAdminAudit_DeniedWithoutGlobalAdmin proves BOTH audit endpoints fail-closed
-// 403 for a non-global-admin, and — critically — the store is NEVER read on a
-// denied request (the gate runs before the handler, so no records leak to an
-// unauthorized caller). We assert non-leakage by seeding records and confirming
-// the denied response body contains none of them.
-func TestAdminAudit_DeniedWithoutGlobalAdmin(t *testing.T) {
+// TestAdminAudit_DeniedWithoutSuperAdmin proves BOTH audit endpoints fail-closed 403 for
+// a non-SuperAdmin, and — critically — the store is NEVER read on a denied request.
+func TestAdminAudit_DeniedWithoutSuperAdmin(t *testing.T) {
 	rec, do := mountWithStore(t)
 	seedAudit(t, rec, 3)
 
@@ -203,17 +200,14 @@ func TestAdminAudit_DeniedWithoutGlobalAdmin(t *testing.T) {
 	}
 }
 
-// TestAdminAudit_FallsBackToIAMWhenNoStore proves that when no local store is
-// configured (auditStore == nil), /v1/admin/audit still serves the federated IAM
-// view rather than erroring — preserving the prior capability. Covered by the
-// existing TestAudit_MapsRecords (IAM proxy path); here we assert the nil-store
-// verify endpoint reports "not configured" rather than panicking.
+// TestAdminAudit_VerifyWithoutStore proves the nil-store verify endpoint reports "not
+// configured" rather than panicking.
 func TestAdminAudit_VerifyWithoutStore(t *testing.T) {
 	app := zip.New(zip.Config{Logger: luxlog.New("test")})
-	s := &svc{adminOrg: "admin"} // no auditStore
-	app.Get("/v1/admin/audit/verify", s.guard(s.auditVerify))
+	s := &cloud.Service[core.State]{State: core.State{AdminOrg: "admin"}} // no auditStore
+	app.Get("/v1/admin/audit/verify", core.Guard(s, Verify))
 	req := httptest.NewRequest("GET", "/v1/admin/audit/verify", nil)
-	for k, v := range globalAdmin {
+	for k, v := range superAdmin {
 		req.Header.Set(k, v)
 	}
 	resp, err := app.Fiber().Test(req, fiber.TestConfig{Timeout: 30 * time.Second})