admin(aimetrics): /v1/admin/aimetrics AI-metrics read view (Langfuse totals/latency/models + usage + eval scores) + table-canonical SQL tests

Replaces the pseudo-version pin (v1.49.2-0.20260719024505-24ff20a68f52, the
Bug-A iterator-leak fix only) with the released v1.49.2, which also carries the
Bug-B guard: org.Resolve skips the doomed GetById for a legacy all-digit cached
id (IAM Valkey's stale 1772587477 for 'hanzo') and resolves by name, so the
(*Query).ById legacy-numeric path that hot-looped in v1.801.95 is never taken.
Keeps ai v1.826.4 (in-proc TierReader). go.mod+go.sum only.

.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,155 @@
+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: zen streaming-fix floor — go.mod must pin github.com/hanzoai/zen >= v1.4.1
+        # The SSE body-close fix (zen commit 50328b8, first released in zen v1.4.1)
+        # is what makes streaming completions return a body instead of an empty
+        # stream. A stale-branch merge that reverts go.mod's zen pin below the floor
+        # silently re-breaks streaming, and `next build`'s ignoreBuildErrors hides
+        # the runtime break — so no image may be cut on a regressed pin. This is the
+        # durable root-cause guard: it reads the EFFECTIVE module version (post-MVS,
+        # exactly what the build links) and fails the PR/push below the floor.
+        run: |
+          set -euo pipefail
+          FLOOR="v1.4.1"
+          V="$(go list -m -f '{{.Version}}' github.com/hanzoai/zen)"
+          echo "effective github.com/hanzoai/zen = ${V} (floor ${FLOOR})"
+          # semver-correct compare: the lowest of {V, FLOOR} under `sort -V` must be
+          # the FLOOR, i.e. V >= FLOOR. (sort -V orders v1.4.2 above v1.4.10 too.)
+          low="$(printf '%s\n%s\n' "$V" "$FLOOR" | sort -V | head -1)"
+          if [ "$low" != "$FLOOR" ]; then
+            echo "::error::github.com/hanzoai/zen is pinned at ${V}, below the streaming-fix floor ${FLOOR} — this re-breaks SSE streaming (empty completions). Re-pin zen to >= ${FLOOR} in go.mod before merging."
+            exit 1
+          fi
+          echo "OK: zen ${V} is at or above the streaming-fix floor ${FLOOR}"
+
+      - 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

@@ -1,39 +1,128 @@
 name: release
 
-# Builds and pushes ghcr.io/hanzoai/cloud:<tag> on tag (v*) / main / dispatch.
+# Cuts a release of ghcr.io/hanzoai/cloud. The invariant this workflow exists to
+# enforce:
 #
-# Self-contained on the self-hosted arcd amd64 scale set — NEVER GitHub-hosted
-# runners (this org's GitHub-hosted Actions are billing-frozen: jobs fail in ~5s
-# with "recent account payments have failed").
+#     a git tag v<X.Y.Z> exists  ⇔  an image ghcr.io/hanzoai/cloud:v<X.Y.Z>
+#     was pushed AND booted to "listening" in the smoke test.
 #
-# Why not the shared hanzoai/.github docker-build.yml: that workflow logs into
-# GHCR with the repo's GITHUB_TOKEN, but the ghcr.io/hanzoai/cloud package is
-# linked to a DIFFERENT repo (hanzoai/ai, from the cloud->ai module rename), so
-# this repo's GITHUB_TOKEN is denied write to it (permission_denied:
-# write_package). We log in with GH_PAT instead (admin:org + write:packages →
-# writes any hanzoai package regardless of package-repo linkage), and pass it as
-# the BuildKit gh_token the Dockerfile uses to fetch private cross-org Go
-# modules. amd64-only: the cluster is amd64; pinning one platform completes on
-# the live scale set without waiting on the arm64 pool.
+# The tag is a RECEIPT for a proven image, minted only AFTER a successful push —
+# never a trigger for a build that might fail. The prior design triggered builds
+# FROM pushed tags, so a tag could exist with no image behind it (a failed or
+# never-run build) — universe would then try to roll that tag and the pods went
+# ImagePullBackOff (phantom v1.786.42/43). Here the order is inverted:
+#
+#     main push → compute next version → build → SMOKE → push image → tag → notify
+#
+# so a push/smoke/build failure fails the run BEFORE the tag step and leaves no
+# tag; universe is only ever notified of a version whose image is proven present.
+#
+# DO NOT push v* tags by hand anymore. This workflow OWNS them. A hand-cut tag has
+# no image behind it (exactly the phantom this prevents) and won't build (there is
+# no `tags:` trigger). Every merge to main IS the release; skip one with the usual
+# `[skip ci]` in the commit/merge message (a docs-only change need not ship).
+#
+# concurrency: a single serialized lane (cancel-in-progress:false — a
+# mid-flight push must finish, never be killed between "image pushed" and "tag
+# created"). Two main pushes can therefore never compute the same next number:
+# the queued run starts only after the running one tags, re-reads the tags, and
+# lands on the next patch. Monotonic by construction.
+#
+# The next version is max(highest git tag, highest pushed container tag) + 1 (patch
+# bump only — never a major/minor jump). Folding in the container tags means we
+# never reuse a number that already has a pushed image, even if some earlier run
+# pushed an image but died before tagging.
+#
+# ── Infra notes (unchanged, still true) ─────────────────────────────────────────
+# Self-hosted arcd amd64 scale set — NEVER GitHub-hosted runners (this org's
+# GitHub-hosted Actions are billing-frozen). GHCR login uses GH_PAT, not the repo
+# GITHUB_TOKEN: the ghcr.io/hanzoai/cloud package is linked to a DIFFERENT repo
+# (hanzoai/ai, from the cloud→ai module rename), so this repo's GITHUB_TOKEN is
+# denied write to it (permission_denied: write_package). GH_PAT (admin:org +
+# write:packages) writes any hanzoai package regardless of package-repo linkage,
+# and is the BuildKit gh_token the Dockerfile uses to fetch private cross-org Go
+# modules. amd64-only: the cluster is amd64; one platform completes on the live
+# scale set without waiting on the arm64 pool.
 
 on:
   push:
     branches: [main]
-    tags: ["v*"]
   workflow_dispatch:
 
+# Cut tags on the cloud repo (git tag push) → contents: write. packages: write
+# to push the image; id-token for provenance.
 permissions:
-  contents: read
+  contents: write
   packages: write
   id-token: write
 
+# One serialized release lane. Never cancel in-flight: a run killed between
+# "image pushed" and "tag created" is exactly the drift we are preventing.
+concurrency:
+  group: release-cloud
+  cancel-in-progress: false
+
 jobs:
   build-amd64:
     # ARC ephemeral runners match jobs targeting the scale-set NAME as a label.
     runs-on: [hanzo-build-linux-amd64]
+    outputs:
+      # 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
+      - name: Checkout (full history + all tags — the version floor is read from tags)
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Compute next version (monotonic patch bump over git + container tags)
+        id: ver
+        env:
+          GH_PAT: ${{ secrets.GH_PAT }}
+        run: |
+          set -euo pipefail
+          git fetch --tags --force --quiet
+
+          # Highest semver git tag (vX.Y.Z), normalised without the leading v.
+          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)"
+
+          # Best-effort: highest ALREADY-PUSHED container tag, so a number that has
+          # 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 \
+              '/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
+
+          # Floor = highest of the two; fall back to 1.786.0 only if the repo has
+          # no tags at all (first release ever).
+          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##*.}"
+          version="${major}.${minor}.$((patch + 1))"
+
+          # 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 "note: hint v${version} already tagged — the Tag step will assign the next free version"
+          fi
+
+          echo "version=${version}"     >> "$GITHUB_OUTPUT"
+          echo "version_v=v${version}"  >> "$GITHUB_OUTPUT"
+          echo "major_minor=${major}.${minor}" >> "$GITHUB_OUTPUT"
+          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}')"
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
@@ -41,6 +130,52 @@ jobs:
           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
+            if echo "$REGISTRY_PASSWORD" | docker login registry.hanzo.ai -u "$REGISTRY_USER" --password-stdin; then
+              echo "MIRROR_OK=1" >> "$GITHUB_ENV"
+            else
+              echo "mirror login failed (registry.hanzo.ai unreachable) — mirror skipped, release continues"
+            fi
+            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#*:}"
+          if echo "${UP#*:}" | docker login registry.hanzo.ai -u "${UP%%:*}" --password-stdin; then
+            echo "MIRROR_OK=1" >> "$GITHUB_ENV"
+          else
+            echo "mirror login failed (registry.hanzo.ai unreachable) — mirror skipped, release continues"
+          fi
+
       - name: Log in to ghcr.io (GH_PAT — writes the cloud package despite its ai-repo linkage)
         uses: docker/login-action@v3
         with:
@@ -48,48 +183,502 @@ jobs:
           username: hanzo-dev
           password: ${{ secrets.GH_PAT }}
 
-      - name: Extract metadata
+      - name: Resolve decomplection artifact digests (the Go-only build's prebuilt inputs)
+        id: artifacts
+        run: |
+          set -euo pipefail
+          # cloud compiles ONLY Go; it pulls three prebuilt artifacts (console SPA,
+          # agent-skills catalog, native flags staticlib). Resolve each published
+          # :latest to an IMMUTABLE digest so THIS release is reproducible (pinned,
+          # not floating :latest) AND a console/skills/flags change is picked up —
+          # its CI republished :latest, so this resolves to the NEW digest. A MISSING
+          # artifact FAILS the release HERE, before build/smoke/push/tag: the receipt
+          # invariant means we never tag an image that couldn't embed the real console.
+          command -v crane >/dev/null 2>&1 || {
+            mkdir -p "$HOME/.local/bin"
+            curl -fsSL "https://github.com/google/go-containerregistry/releases/latest/download/go-containerregistry_Linux_x86_64.tar.gz" \
+              | tar -xz -C "$HOME/.local/bin" crane
+          }
+          export PATH="$HOME/.local/bin:$PATH"
+          resolve() {
+            local repo="$1" d
+            d="$(crane digest "ghcr.io/hanzoai/${repo}:latest" 2>/dev/null || true)"
+            [ -n "$d" ] || { echo "::error::decomplection artifact ghcr.io/hanzoai/${repo}:latest is not published — refusing to cut a release that would embed a stale/placeholder ${repo}"; return 1; }
+            printf 'ghcr.io/hanzoai/%s@%s' "$repo" "$d"
+          }
+          CONSOLE_IMAGE="$(resolve console-embed)" || exit 1
+          SKILLS_IMAGE="$(resolve agent-skills)" || exit 1
+          FLAGS_IMAGE="$(resolve cloud-flags)" || exit 1
+          {
+            echo "console_image=${CONSOLE_IMAGE}"
+            echo "skills_image=${SKILLS_IMAGE}"
+            echo "flags_image=${FLAGS_IMAGE}"
+          } >> "$GITHUB_OUTPUT"
+          echo "resolved: console=${CONSOLE_IMAGE} skills=${SKILLS_IMAGE} flags=${FLAGS_IMAGE}"
+
+      - name: OCI labels
         id: meta
         uses: docker/metadata-action@v5
         with:
           images: ghcr.io/hanzoai/cloud
-          tags: |
-            type=ref,event=tag
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-            type=sha,prefix=sha-,format=short
-            type=raw,value=latest,enable={{is_default_branch}}
+          tags: type=raw,value=${{ steps.ver.outputs.version_v }}
 
-      - name: Build and push
+      # ── Build → SMOKE → push → tag ───────────────────────────────────────────
+      # 1. Build once to a LOCAL tag (load into the daemon, do NOT push). Warms
+      #    the BuildKit cache — the expensive console/npm + Go layers land here.
+      # 2. Boot that exact image and assert it reaches "listening" with no
+      #    startup-crash signature (the gate).
+      # 3. Re-run build with push:true and the real tags: identical context /
+      #    platform / secrets, so every layer is a cache hit from step 1 and the
+      #    step only exports + pushes the already-tested image. Nothing that failed
+      #    the smoke test can reach the registry.
+      # 4. Only after the push succeeds, mint + push the git tag (the receipt).
+      - name: Build (load locally for the smoke test)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64
+          push: false
+          load: true
+          tags: cloud:smoke
+          labels: ${{ steps.meta.outputs.labels }}
+          # cloud compiles ONLY Go: pull the three prebuilt artifacts pinned to the
+          # digests resolved above (reproducible, and fresh — a console/skills/flags
+          # change is a new digest). No node/python/rust toolchain in this build.
+          build-args: |
+            CONSOLE_IMAGE=${{ steps.artifacts.outputs.console_image }}
+            SKILLS_IMAGE=${{ steps.artifacts.outputs.skills_image }}
+            FLAGS_IMAGE=${{ steps.artifacts.outputs.flags_image }}
+          # GIT_AUTH_TOKEN: BuildKit secret the Dockerfile consumes to fetch private
+          # cross-org Go modules (hanzoai/*, luxfi/*) over authenticated git.
+          secrets: |
+            GIT_AUTH_TOKEN=${{ secrets.GH_PAT }}
+
+      - name: Smoke test — the binary MUST boot to "listening" with no crash signature
+        run: |
+          set -euo pipefail
+          IMAGE=cloud:smoke
+          CID=""
+          cleanup() { [ -n "$CID" ] && docker rm -f "$CID" >/dev/null 2>&1 || true; }
+          trap cleanup EXIT
+
+          # Minimal, production-representative boot env:
+          #  • a writable ephemeral /data root — the audit store, the embedded
+          #    KMS secrets plane and every per-tenant SQLite open files under
+          #    CLOUD_DATA_DIR; an unwritable dir would fail EVERY image before
+          #    MountAll and the gate would stop discriminating good from bad; and
+          #  • a throwaway 32-byte KMS master key so the KMS plane mounts on its
+          #    normal ready path exactly as prod does (no real secret is used).
+          # The subsystem that crashed the incident (metrics, mount order 40)
+          # mounts AFTER kms (order 10), so the boot must get past kms for the
+          # gate to observe the panic — this env does exactly that.
+          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")"
+
+          # Poll up to 60s for boot to either finish ("listening" is logged once
+          # every subsystem has mounted and both transports are about to bind) or
+          # die (a Mount panic exits the process). A healthy boot is ~1-2s; the
+          # ceiling only guards a cold daemon.
+          listening=0
+          for _ in $(seq 1 60); do
+            logs="$(docker logs "$CID" 2>&1 || true)"
+            if printf '%s' "$logs" | grep -q '"message":"listening"'; then listening=1; break; fi
+            if [ "$(docker inspect -f '{{.State.Running}}' "$CID" 2>/dev/null || echo false)" != "true" ]; then break; fi
+            sleep 1
+          done
+
+          logs="$(docker logs "$CID" 2>&1 || true)"
+          echo "::group::cloud:smoke boot logs"
+          printf '%s\n' "$logs"
+          echo "::endgroup::"
+
+          # (1) No startup-crash signature. Catches the incident's Mount
+          #     type-assert panic AND any generic Go panic — case-insensitive so a
+          #     re-worded variant can't slip through — BEFORE a byte is pushed.
+          if printf '%s' "$logs" | grep -Eiq 'metrics\.Mount|mount metrics|panic|want \*zip\.App'; then
+            echo "SMOKE FAIL: startup-crash signature in boot logs (see above)"
+            exit 1
+          fi
+
+          # (2) Reached "listening" — proof that MountAll returned for every
+          #     enabled subsystem (a failed Mount returns before this line).
+          if [ "$listening" -ne 1 ]; then
+            echo "SMOKE FAIL: binary never reached \"listening\" (a subsystem did not mount)"
+            exit 1
+          fi
+
+          # (3) Still alive — a server that logged "listening" then exited (e.g. a
+          #     listener bind failure) is not a healthy image.
+          if [ "$(docker inspect -f '{{.State.Running}}' "$CID" 2>/dev/null || echo false)" != "true" ]; then
+            echo "SMOKE FAIL: process exited after \"listening\""
+            exit 1
+          fi
+
+          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
         with:
           context: .
           platforms: linux/amd64
           push: true
-          tags: ${{ steps.meta.outputs.tags }}
+          # 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:sha-${{ steps.ver.outputs.sha_short }}
+            ghcr.io/hanzoai/cloud:latest
           labels: ${{ steps.meta.outputs.labels }}
-          # gh_token: BuildKit secret the Dockerfile consumes to fetch private
-          # cross-org Go modules (hanzoai/*, luxfi/*) over authenticated git.
+          # SAME artifact digests as the smoke build → every layer is a cache hit from
+          # step 1 and the pushed image is byte-identical to the one smoke proved.
+          build-args: |
+            CONSOLE_IMAGE=${{ steps.artifacts.outputs.console_image }}
+            SKILLS_IMAGE=${{ steps.artifacts.outputs.skills_image }}
+            FLAGS_IMAGE=${{ steps.artifacts.outputs.flags_image }}
           secrets: |
-            gh_token=${{ secrets.GH_PAT }}
+            GIT_AUTH_TOKEN=${{ secrets.GH_PAT }}
 
-  # Notify universe so the GitOps pipeline rolls the new image to prod —
-  # same image-update contract every service uses (gateway, iam, …).
-  notify-universe:
+      # 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
+          git config user.name  "hanzo-dev"
+          git config user.email "dev@hanzo.ai"
+          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.
+            # Fail-CLOSED. An ORPHANED container tag — image pushed by a run that
+            # died or was cancelled after imagetools-create but before its git tag —
+            # MUST raise the floor, or a later run reassigns that same number to a
+            # different image (an ambiguous mutable prod tag; the v1.801.50 flip). A
+            # git-only floor can't see the orphan, so if the container-tag lookup
+            # ERRORS (vs legitimately returning no tags) we retry the whole attempt
+            # rather than silently proceeding — a version with a pushed image is never
+            # reused. (Reordering git-tag before imagetools-create is the WRONG fix: it
+            # reintroduces the phantom "tag ⇔ no image" this workflow exists to prevent.)
+            cont_max=""
+            if command -v gh >/dev/null 2>&1; then
+              if cont_raw="$(GH_TOKEN="$GH_PAT" gh api \
+                  '/orgs/hanzoai/packages/container/cloud/versions?per_page=100' \
+                  --jq '.[].metadata.container.tags[]?' 2>/dev/null)"; then
+                cont_max="$(printf '%s\n' "$cont_raw" \
+                  | sed 's/^v//' | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1 || true)"
+              else
+                echo "  container-tag lookup failed — retry so an orphaned tag can't be reused (attempt $attempt)"; sleep 3; continue
+              fi
+            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
+                # Bounded: registry.hanzo.ai can *hang* (not just fail), and this
+                # is best-effort — an unbounded crane copy once livelocked the whole
+                # tag step and held the serialized release lane. timeout makes the
+                # mirror truly best-effort so the git-tag receipt below always runs.
+                timeout 120 crane copy "$SHA_IMG" "registry.hanzo.ai/hanzoai/cloud:${MT}" \
+                  || echo "::warning::mirror registry.hanzo.ai/hanzoai/cloud:${MT} failed or timed out"
+              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
+
+  # ── Promote: the declared-tag bump that makes the release DEPLOY ─────────────
+  # The tag minted above is the receipt for a pushed, smoke-passed image; THIS job
+  # records it as the desired state Hanzo CD reconciles. The universe-crs ArgoCD
+  # Application (ns hanzo-cd, `automated` sync + selfHeal) syncs
+  # infra/k8s/operator/crs/*.yaml → cluster and the operator rolls the Deployment,
+  # so a tag bump committed here reaches api.hanzo.ai with NO hand-dispatch and NO
+  # hand-edit of the CR.
+  #
+  # This is the SAME yq-bump → `deploy(<svc>): <tag>` universe commit the hanzoai/ci
+  # reusable (build.yml deploy step) does for every other service. cloud owns it
+  # HERE because its image is built by this workflow, not the ci reusable — its
+  # hanzo.yml carries no main `images:` entry and `# NO deploy`, so the shared
+  # deploy step never bumps cloud's CR. A direct in-cluster CR patch is NOT enough:
+  # ArgoCD selfHeal reverts any live edit not also recorded in git within ~45s.
+  # The retired notify-universe repository_dispatch had no receiver after the
+  # image-update.yml deploy hub was deleted in the Hanzo CD cutover; the git commit
+  # IS the sanctioned path now.
+  promote:
     needs: build-amd64
+    # Only a real release promotes: build+smoke+push+tag all succeeded, so a
+    # proven v* image exists. A failure earlier leaves version_v empty → skipped.
+    if: ${{ needs.build-amd64.outputs.version_v != '' }}
     runs-on: [hanzo-build-linux-amd64]
-    if: startsWith(github.ref, 'refs/tags/v')
     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:${{ github.ref_name }}",
-              "sha":     "${{ github.sha }}",
-              "env":     "all"
-            }
+      - name: Record the proven tag in universe crs/cloud.yaml (Hanzo CD rolls it)
+        env:
+          # GH_PAT already pushes this repo's git tags above (contents:write on the
+          # hanzoai org), so it writes hanzoai/universe too — the SAME token the ci
+          # reusable falls back to for the universe deploy commit.
+          GH_PAT: ${{ secrets.GH_PAT }}
+          VERSION_V: ${{ needs.build-amd64.outputs.version_v }}
+        run: |
+          set -euo pipefail
+          [ -n "${GH_PAT:-}" ] || { echo "::error::no GH_PAT — cannot record the declared-tag bump in universe"; exit 1; }
+
+          # Bare arc runners ship no yq — provision the static binary (sudo-free,
+          # same pattern the ci reusable and this workflow's kubectl/crane fetches use).
+          if ! command -v yq >/dev/null 2>&1; then
+            mkdir -p "$HOME/.local/bin"; export PATH="$HOME/.local/bin:$PATH"
+            curl -fsSL https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 \
+              -o "$HOME/.local/bin/yq" && chmod +x "$HOME/.local/bin/yq"
+          fi
+
+          git clone -q --depth 1 \
+            "https://x-access-token:${GH_PAT}@github.com/hanzoai/universe.git" \
+            "$RUNNER_TEMP/universe"
+          CR="$RUNNER_TEMP/universe/infra/k8s/operator/crs/cloud.yaml"
+          [ -f "$CR" ] || { echo "::error::crs/cloud.yaml not found in universe"; exit 1; }
+
+          CUR="$(yq -r '.spec.image.tag // ""' "$CR")"
+          echo "cloud CR: ${CUR:-<empty>} → ${VERSION_V}"
+
+          # Monotonic guard: never roll the CR BACKWARD. Release runs finish under a
+          # serialized lane but a slow older run must never overwrite a newer promote.
+          # Skip iff the CR already holds a semver >= the version we just cut.
+          CURN="${CUR#v}"; NEWN="${VERSION_V#v}"
+          if printf '%s' "$CURN" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+            top="$(printf '%s\n%s\n' "$CURN" "$NEWN" | sort -V | tail -1)"
+            if [ "$top" = "$CURN" ] && [ "$CURN" != "$NEWN" ]; then
+              echo "::notice::cloud CR already at v${CURN} (≥ ${VERSION_V}) — not rolling back"; exit 0
+            fi
+          fi
+
+          yq -i ".spec.image.tag = \"${VERSION_V}\"" "$CR"
+          if git -C "$RUNNER_TEMP/universe" diff --quiet; then
+            echo "::notice::crs/cloud.yaml already at ${VERSION_V} — nothing to record"; exit 0
+          fi
+          git -C "$RUNNER_TEMP/universe" -c user.name=hanzo-ci -c user.email=dev@hanzo.ai \
+            commit -qam "deploy(cloud): ${VERSION_V} (${GITHUB_REPOSITORY}@$(echo "${GITHUB_SHA}" | cut -c1-7))"
+
+          # Rebase-safe push: universe main advances on every service's deploy, so a
+          # concurrent commit must not make cloud's promote lose the whole roll. Retry
+          # a few times, rebasing between attempts.
+          for attempt in $(seq 1 5); do
+            if git -C "$RUNNER_TEMP/universe" push -q origin HEAD:main; then
+              echo "recorded deploy(cloud): ${VERSION_V} — Hanzo CD (universe-crs) will roll it to api.hanzo.ai"
+              exit 0
+            fi
+            echo "  universe push lost the race — rebasing (attempt ${attempt})"
+            git -C "$RUNNER_TEMP/universe" pull -q --rebase origin main || true
+            sleep 3
+          done
+          echo "::error::could not record the cloud tag bump in universe after 5 attempts"; exit 1

.gitignore

@@ -32,3 +32,6 @@ Thumbs.db
 # Logs
 *.log
 .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,101 +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.
-#
-# NOTE ON THE HONEST CURRENT STATE: console2 today ships 15 Next server route
-# handlers (app/**/route.ts) that hold KMS-sourced service tokens and mint
-# short-lived user tokens — so `next build` emits a Node server bundle, not a
-# static export, and `output: export` would fail. Until console2 exposes a
-# static-export target (npm run build:embed → out/) — or those server routes
-# land in cloud as native /v1 endpoints — this stage produces no /out and the Go
-# build embeds the committed fallback shell (webui/dist/index.html), which is a
-# real, same-origin /v1 bootstrap. The moment console2 emits out/, this stage
-# copies it and the SAME image serves the full @hanzo/gui console with zero Go
-# changes. The stage never fails the image: a missing static target degrades to
-# the shell, it does not error.
-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
-ENV NEXT_TELEMETRY_DISABLED=1 NODE_OPTIONS=--max-old-space-size=6144
-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 it holds the real
-# bundle; otherwise /out stays EMPTY so the Go build keeps the committed fallback
-# shell. Never fail the image (a missing static target is a degrade, not an error).
-RUN mkdir -p /out && \
-    if npm run 2>/dev/null | grep -q ' build:embed'; then \
-      echo ">> console2 build:embed → static bundle"; \
-      npm run build:embed && cp -r out/. /out/; \
-    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,260 @@
+# 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.
+
+## Open Cloud planes
+
+Spec home: HIP-0129 `hip-0129-open-cloud-planes` (hips repo). This section is a
+map, not the spec. One noun, one owner, one route family. No plane reads another
+plane's store; imports flow custody-ward only (channels -> integrations, never
+reverse).
+
+| Route | Noun | Owner | Tier |
+| --- | --- | --- | --- |
+| `/v1/connectors` | Custody: per-user BYO external accounts | `clients/integrations` (extends; user scope new) | In flight (branch `feat/connectors`) |
+| `/v1/channels` | Transport: portable message envelope, DM pairing, send + inbox | `clients/channels` (new) | Planned (branch `feat/channels` reserved; no transport code yet) |
+| `/v1/sync` | Data: bidirectional sync engine | `clients/sync` | Shipped |
+| `/v1/automations` | Workflows: flows/runs, goja piece runtime | `clients/automations` | Shipped |
+| `/v1/compute/bots` | Hosting: `@hanzo/bot` Node containers | `clients/bots` | Shipped |
+| `/v1/tasks` | Durable engine | `clients/tasks` | Shipped |
+| `/v1/gpus` + fleet | BYO GPU presence | `clients/fleet` + `clients/visor` | Shipped |
+| IAM | Identity: users, orgs, roles | IAM | Shipped |
+| KMS | Secret custody: sealed secrets | `clients/kms` | Shipped |
+
+Custody invariants: secrets sealed in KMS at
+`/orgs/{org}/users/{user}/connectors/{provider}/{label}`, never in SQLite rows;
+verify before store. Refresh is single-flight with rotation resealing; the CLI
+does local browser PKCE and posts the bundle to
+`POST /v1/connectors/:provider/credential`; cloud owns device-code flows.
+
+Transport invariants: typed actions (`command|url|select|approval`), no raw
+string sniffing; pairing codes 8 chars, 1h TTL, max 3 pending per account,
+owner bootstrap on first approval.
+
+Container boundary is permanent for native-module, host-filesystem, loop-state,
+and vendor-Node work (agent loop, exec/PTY, harnesses, browser, voice, codecs,
+Node-bound channels, plugin SDK/loader). The Node plugin SDK is never ported to
+Go; cloud extensibility is connectors/automations/tools.
+
+Port roadmap (P1-P15) lives in HIP-0129; do not restate it here. Every claim
+carries its tier: Shipped (on main, named package/route), In flight (named
+pre-main branch), Planned (backlog id or named reservation).
+
+## 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`.
+
+## Deploy plane (`clients/deploy`, `/v1/deploy`)
+
+Native ArgoCD-grade GitOps console over the operator-managed fleet, parallel to
+`/v1/git`: each `hanzo.ai/v1` App CR IS the Application, and the plane OBSERVES the
+operator's reconcile — `GET /v1/deploy/applications` (fleet list), `/{name}/tree`
+(ownerRef resource tree + per-node health/sync), `/{name}/resource/{ref}` (live
+manifest + desired-vs-live diff), `/{name}/logs`; `POST /{name}/rollback` pins the CR
+image to a prior semver and `/{name}/sync` requests a reconcile. SUPERADMIN-only on
+`c.IsAdmin()`, fail-closed; Secret nodes are never surfaced. `engine.go` embeds the argo
+`gitops-engine` (`hanzoai/deploy/gitops-engine` v0.7.2, no replace) in-process for the
+reconcile half behind `DEPLOY_ENGINE_ENABLED` (default off), with a prune-safety fuse.
+
+## The `hanzo` CLI targets THIS binary — one contract, one IAM login
+
+The `hanzo` CLI (`cli/`) is the same unified binary; its control-plane verbs speak the
+routes THIS process serves, authorized off a plain `hanzo login` (the IAM access token is
+the final bearer fallback — no `--platform-token`). The ONE contract, no TS-Dokploy drift:
+
+- `hanzo apps list|get`  → `GET /v1/paas/apps[/{app}]`  (`clients/paas` fleet drift board)
+- `hanzo deploy <app>`   → `POST /v1/paas/apps/{app}/deploy` — a zero-downtime ROLLING
+  RESTART (stamps the Deployment pod-template `hanzo.ai/restartedAt` annotation; never
+  changes the declared TAG — that stays a git commit CD reconciles). `--env` picks the ns.
+- `hanzo clusters list|get` → `GET /v1/clusters`  (`clients/visor`, tenant-scoped)
+- `hanzo build`          → `POST /v1/runner`  (native buildkit fabric)
+
+`/v1/paas/*` auth mirrors `/v1/runner` (`clients/platform/runner.go`): the `guard` admits a
+validated principal who is SuperAdmin OR OrgAdmin, then each handler CONFINES a non-super
+caller to the platform namespaces its own validated org owns (`scopedNamespaces`, keyed on
+`principal.Org` — a tenant admin can never observe/restart another org's, or a platform,
+app; `?org=` cannot widen it). The rolling restart needs `patch` on `apps/deployments`
+(ClusterRole/cloud, universe `infra/k8s/cloud/rbac.yaml`). There is NO `/v1/apps`,
+`/v1/org/{org}/cluster`, or `/v1/platform/projects` CLI path — the first two never existed
+here (TS-Dokploy contract, 404), and `/v1/platform/*` needs a co-resident IAM store this
+deployment does not fold in (IAM runs as a separate svc) so it 500s; the live apps backend
+is `/v1/paas`, whose board reads k8s directly with no IAM-store dependency.

Makefile

@@ -7,15 +7,66 @@ PKG             ?= ./cmd/cloud
 DOCKER_IMAGE    ?= ghcr.io/hanzoai/cloud
 DOCKER_TAG      ?= dev
 LDFLAGS         ?= -s -w
+# 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
 
-.PHONY: help build run smoke test vet tidy docker docker-push clean
+# 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
+# what prod runs — and, critically, register the ONE "sqlite" driver exactly once:
+# cloud's stores use github.com/hanzoai/sqlite (its !cgo backend IS modernc), and
+# the embedded deps (ai/base/commerce/o11y/orm/tasks) that import modernc directly
+# then resolve to the SAME package → a single registration. A plain CGO_ENABLED=1
+# build instead links the fork's mattn backend ALONGSIDE those modernc importers
+# and panics at init ("sql: Register called twice for driver sqlite"); `make
+# test-cgo` proves the cgo path via the fork's `sqlite_purego` opt-out tag, which
+# forces the fork to modernc too so the whole binary registers "sqlite" once.
+CGO_ENABLED     ?= 0
+
+.PHONY: help native webui deploy-ui 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%-12s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+	@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)
 
-build: ## Build the unified cloud binary into ./bin/cloud.
+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 "$(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 "$(CONSOLE_DIR)/out/." webui/dist/
+	@echo ">> embedded real console bundle into webui/dist (index.html $$(wc -c < webui/dist/index.html) bytes)"
+
+deploy-ui: ## Build the monochrome ArgoCD dashboard bundle into clients/deploy/webui/dist (go:embed source). DEPLOY_DIR=<path to hanzoai/deploy>.
+	@command -v yarn >/dev/null 2>&1 || { echo "yarn is required to build the deploy dashboard bundle"; exit 1; }
+	@test -f "$(DEPLOY_DIR)/ui/package.json" || { echo "deploy checkout not found at $(DEPLOY_DIR) — set DEPLOY_DIR=<path to hanzoai/deploy on rebrand/hanzo-monochrome>"; exit 1; }
+	@test -d "$(DEPLOY_DIR)/ui/node_modules" || (cd "$(DEPLOY_DIR)/ui" && yarn install --frozen-lockfile)
+	cd "$(DEPLOY_DIR)/ui" && NODE_OPTIONS=--max-old-space-size=8192 yarn build
+	# Overlay the fresh bundle, keeping only the tracked fallback (.gitignore +
+	# index.html shell); the real 43MB bundle is build-time-only (gitignored).
+	find clients/deploy/webui/dist -mindepth 1 -maxdepth 1 ! -name .gitignore -exec rm -rf {} +
+	cp -r "$(DEPLOY_DIR)/ui/dist/app/." clients/deploy/webui/dist/
+	@echo ">> embedded monochrome ArgoCD bundle into clients/deploy/webui/dist (index.html $$(wc -c < clients/deploy/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
-	$(GO) build -ldflags="$(LDFLAGS)" -o bin/$(BIN) $(PKG)
+	CGO_ENABLED=$(CGO_ENABLED) $(GO) build -ldflags="$(LDFLAGS)" -o bin/$(BIN) $(PKG)
+
+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
@@ -23,11 +74,14 @@ run: build ## Run with iam,base,kms,gateway,o11y enabled (matches README quickst
 smoke: ## Build and run cmd/cloud-smoke (mount-time integration check).
 	$(GO) run ./cmd/cloud-smoke
 
-test: ## Run unit + integration tests.
-	$(GO) test ./...
+test: ## Run unit + integration tests (pure-Go, exactly as prod ships).
+	CGO_ENABLED=$(CGO_ENABLED) $(GO) test ./...
+
+test-cgo: ## Prove the cgo build works too — forces the fork's pure-Go backend via -tags sqlite_purego so the embedded modernc importers don't double-register "sqlite".
+	CGO_ENABLED=1 $(GO) test -tags sqlite_purego ./...
 
 vet: ## go vet across the module.
-	$(GO) vet ./...
+	CGO_ENABLED=$(CGO_ENABLED) $(GO) vet ./...
 
 tidy: ## go mod tidy + verify go.sum.
 	$(GO) mod tidy
@@ -41,3 +95,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,444 @@
+// 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/admission"
+	"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/cloudflare"
+	"github.com/hanzoai/cloud/clients/code"
+	"github.com/hanzoai/cloud/clients/company"
+	"github.com/hanzoai/cloud/clients/content"
+	"github.com/hanzoai/cloud/clients/crm"
+	"github.com/hanzoai/cloud/clients/dataroom"
+	"github.com/hanzoai/cloud/clients/deploy"
+	"github.com/hanzoai/cloud/clients/dns"
+	"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},
+		// clients/plan.Mount. Enable id normalized "plans" -> "plan" to match the
+		// package + generated cmd/plan (one subsystem, one name). Its product routes
+		// stay /v1/plans/* (incl. the OwnsHealth /v1/plans/health probe) — unchanged.
+		{Name: "plan", 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},
+		// The /v1/dns forward head: relays the console DNS dashboard to the DNS
+		// control plane under the caller's own validated bearer (clients/dns).
+		{Name: "dns", Mount: dns.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},
+		// Per-org Cloudflare asset plane /v1/integrations/cloudflare/{pages,workers,r2,kv,d1}/*.
+		// Mounts AFTER integrations because it reads the org's Cloudflare token through
+		// the integrations custody seam (integrations.TokenFor) — one token, one
+		// custody boundary. Stateless: no store, no shutdown.
+		{Name: "cloudflare", Mount: cloudflare.Mount},
+		{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 gate (per-service waitlist): the COMPLETE feature — host→service
+		// registry + brand seed + the waitlist.<svc> switch registration + the
+		// /v1/flags/waitlist (and /v1/admission/mode compat) mode read + the Enforce
+		// middleware — COMPOSING the flags engine one-way (flags.Bool/Register/
+		// SetPlatformSwitch; flags never imports admission). Mounts AFTER flags so the
+		// engine's platform-switch plane is installed first; the admin board is the
+		// /v1/admin/services lens over it. Owns the registry store handle → Shutdown.
+		{Name: "admission", Mount: admission.Mount, Shutdown: ctxShutdown(admission.Shutdown)},
+		// Tasks: the durable workflow/UI surface AND platform cron (durable schedules
+		// on the same shared engine, replacing every k8s CronJob). cron was a separate
+		// Wire entry; it mounts no routes and only registers schedules, so it is folded
+		// in as a sub-mount of tasks.Mount — ONE tasks subsystem.
+		{Name: "tasks", Mount: tasks.Mount},
+		// Automations: the connector catalogue + flow engine AND native single-connector
+		// execution (POST /v1/automations/connectors/:id/run, HIP-0126). The connector
+		// runner mounts no other routes, so it is folded in as a sub-mount of
+		// automations.Mount (was a separate "connectorruntime" entry) — ONE subsystem.
+		{Name: "automations", Mount: automations.Mount, Shutdown: automations.Shutdown},
+		// 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,272 @@
+// 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"
+	"time"
+
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/commerceclient"
+	"github.com/hanzoai/cloud/clients/commerceinproc"
+	financeclient "github.com/hanzoai/cloud/clients/finance"
+	"github.com/hanzoai/commerce"
+	commercebilling "github.com/hanzoai/commerce/api/billing"
+	commercestore "github.com/hanzoai/commerce/api/store"
+	commercedatastore "github.com/hanzoai/commerce/datastore"
+	commercemid "github.com/hanzoai/commerce/middleware"
+	"github.com/hanzoai/commerce/middleware/iammiddleware"
+	commercensctx "github.com/hanzoai/commerce/util/nscontext"
+	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)
+
+	// Usage-cap enforcement on the FINANCE path. The unified binary records usage in
+	// the finance ledger (fin.RecordUsage), NOT commerce's transaction store — which
+	// it leaves empty — so the cap must read spend from, and fire alerts on, the
+	// finance ledger. Two seams, both org-wide (the finance Entry carries no scope;
+	// per-scope caps are a follow-up):
+	//   - SetPeriodSpendReader: AuthorizeSpendCap's scopeSpentCents reads the org's
+	//     finance period spend instead of the empty commerce transaction ledger, so
+	//     a real LLM request increments the cap's `spent` and trips the 402.
+	//   - SetUsageHook: after each finance debit, fire the org's spend-alerts on the
+	//     SAME crossing (the alert half), reading the same finance spend + debouncing.
+	commercebilling.SetPeriodSpendReader(financePeriodSpend)
+	financeclient.SetUsageHook(fireCapAlert)
+
+	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)
+	}
+}
+
+// financePeriodSpend is the usage-cap's period-spend source (injected into commerce
+// via SetPeriodSpendReader). It returns the org's finance-ledger usage in cents since
+// the start of the CURRENT UTC month — the window the cap resets on (mirrors
+// commerce periodStartUTC). Org-wide: the finance Entry carries no project/service,
+// so scope args are ignored and the org total is returned (what the covering
+// org-wide spend-alert row binds on). A finance impl without the sum capability, or a
+// split deploy (no co-resident finance), reports 0 — the cap can never over-count.
+func financePeriodSpend(ctx context.Context, org string, test bool, _, _ string) (int64, error) {
+	fin := financeclient.Current()
+	if fin == nil {
+		return 0, nil
+	}
+	summer, ok := fin.(interface {
+		SumUsageSince(context.Context, string, bool, int64) (int64, error)
+	})
+	if !ok {
+		return 0, nil
+	}
+	n := time.Now().UTC()
+	since := time.Date(n.Year(), n.Month(), 1, 0, 0, 0, 0, time.UTC).Unix()
+	return summer.SumUsageSince(ctx, org, test, since)
+}
+
+// fireCapAlert fires the org's spend-alerts after a finance usage debit — the alert
+// half of the cap on the finance path (wired via finance.SetUsageHook). It resolves
+// the org's commerce datastore (where the spend-alert rows live) and calls the
+// exported commerce trigger, which reads the org's period spend via financePeriodSpend
+// and stamps/debounces. Detached + best-effort; never blocks the money path. Runs in
+// its own goroutine (the hook is invoked with `go`), so a background context is right.
+func fireCapAlert(org string, test bool, project, service string) {
+	if strings.TrimSpace(org) == "" {
+		return
+	}
+	ctx := commercensctx.WithNamespace(context.Background(), org)
+	db := commercedatastore.New(ctx)
+	commercebilling.FireSpendAlerts(ctx, db, org, test, project, service, nil)
+}

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,153 @@
+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
+	{"plan", true, false},            // was order 111; enable id normalized plans->plan (routes stay /v1/plans/*)
+	{"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
+	{"dns", false, false},            // new: /v1/dns zone plane (after projects)
+	{"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
+	{"cloudflare", false, false},     // new: /v1/cloudflare edge plane (after integrations)
+	{"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
+	{"admission", false, true},       // launch-control gate: composes flags (registry+seed+mode route+Enforce); Shutdown closes the registry store
+	{"tasks", false, false},          // was order 147; platform cron folded in as a sub-mount of tasks.Mount (was a separate entry)
+	{"automations", false, true},     // was order 148; connectorruntime (POST /v1/automations/connectors/:id/run) folded in as a sub-mount of automations.Mount
+	{"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.
@@ -34,15 +34,18 @@ import (
 	"sync"
 	"time"
 
-	// modernc.org/sqlite is the pure-Go SQLite driver already in the cloud dep
-	// graph (see clients/pricing, clients/provisioning). Blank import registers
-	// the "sqlite" driver name.
-	_ "modernc.org/sqlite"
+	// github.com/hanzoai/sqlite is the ONE Hanzo SQLite driver: it registers
+	// the "sqlite" database/sql name under both build tags (cgo →
+	// 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
@@ -105,11 +108,11 @@ type CheckpointFunc func(cp Checkpoint)
 // the chain head from it, so a restart continues the SAME chain rather than
 // forking a new one. path may be ":memory:" for tests. mirror may be nil.
 //
-// modernc's "sqlite" driver; MaxOpenConns(1) serializes every statement against
+// the hanzoai/sqlite "sqlite" driver; MaxOpenConns(1) serializes every statement against
 // 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,219 @@
+// 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),
+	}
+}
+
+// sharedKeys memoizes ONE API-key resolver (and its 60s cache) for the whole
+// binary. The identity boundary (SanitizeIdentity, via newIdentityValidator) and
+// any subsystem that must resolve a key OUT-OF-BAND of the Authorization header
+// (analytics capture: a project key posted in the SDK body/query) both go through
+// this ONE seam, so a key resolves to the SAME org either way and IAM sees one
+// warm cache — never a second, drifting resolver.
+var (
+	sharedKeysOnce sync.Once
+	sharedKeysInst *iamKeys
+)
+
+func sharedKeys() *iamKeys {
+	sharedKeysOnce.Do(func() { sharedKeysInst = newIAMKeys() })
+	return sharedKeysInst
+}
+
+// maxKeyOrgLen bounds a resolved org key the same way principal.MaxOrgLen does: the
+// org becomes a warehouse partition key, so an over-long value (malformed / hostile)
+// is refused rather than stored.
+const maxKeyOrgLen = 128
+
+// OrgForKey resolves an opaque Hanzo API key (hk-/sk-/pk-/fw_/hz_) to the org it
+// belongs to — the SAME owner org SanitizeIdentity mints when that key arrives as a
+// bearer — through the ONE IAM key seam (get-user?accessKey). It is the exported
+// door a keyed, bearer-less SDK path uses to attribute a project key to a tenant.
+//
+// FAILS CLOSED: ("", false) for a non-key-shaped string, an unknown/unresolvable
+// key, an unconfigured resolver, or an out-of-bounds org — never a fabricated or
+// default tenant, so a bad key can never be written into another org's partition.
+// The isAPIKey prefix gate keeps garbage strings off the IAM network path.
+func OrgForKey(ctx context.Context, key string) (string, bool) {
+	key = strings.TrimSpace(key)
+	if !isAPIKey(key) {
+		return "", false
+	}
+	claims := sharedKeys().resolve(ctx, key)
+	if claims == nil {
+		return "", false
+	}
+	owner := strings.TrimSpace(claims.Owner)
+	if owner == "" || len(owner) > maxKeyOrgLen {
+		return "", false
+	}
+	return owner, true
+}
+
+// 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

@@ -24,12 +24,15 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"os"
 	"strings"
 	"sync"
 	"time"
 
 	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.
@@ -37,15 +40,46 @@ 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)
+	BillingAccount    string `json:"billing_account"`    // WHO PAYS, stated by IAM (empty ⟹ pre-claim token)
 	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)
+}
+
+// mintedBillingAccount returns the funding account to stamp into
+// X-Billing-Account-Id, or "" when the header must be OMITTED (a token minted
+// before IAM shipped the claim, or one IAM could not attribute).
+//
+// WHO PAYS IS NOT A CLIENT'S TO NAME. This rides the validated `billing_account`
+// claim — IAM's signed statement, resolved at the identity boundary from the real
+// grant context — exactly like `owner` and `project`. It mirrors the edge
+// (iamauth.Claims.MintedBillingAccount) byte-for-byte, so the in-binary path binds
+// the same header the gateway would, and ai/object.Payer reads the same payer on
+// both. The raw client copy is deleted on ingress and NEVER restored.
+func (c *idClaims) mintedBillingAccount() string {
+	return strings.TrimSpace(c.BillingAccount)
+}
+
 // 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
@@ -56,6 +90,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".
@@ -65,23 +114,87 @@ var jwtSigAlgs = []gojose.SignatureAlgorithm{
 	gojose.PS256, gojose.PS384, gojose.PS512,
 }
 
-// identityValidator validates an IAM JWT against a cached JWKS. Issuer +
-// audience + expiry are always enforced.
+// identityValidator validates an IAM JWT against a cached JWKS. Issuer (any of a
+// trusted SET) + audience + expiry are always enforced.
+//
+// The issuer is a SET so ONE cloud binary validates every white-label brand's
+// tokens (hanzo iss=hanzo.id AND lux iss=lux.id, ...). Signature verification is
+// unaffected: the in-cluster IAM serves EVERY brand's signing cert in one JWKS
+// (cert-hanzo/cert-lux/cert-zoo/...), keyed by the token kid, so a single
+// jwksURL verifies all brands. Only the issuer-string comparison had to widen.
 type identityValidator struct {
-	issuer    string
+	issuers   []string
 	audiences []string
 	cache     *jwksCache
+	keys      keyResolver // resolves an opaque API key to a principal; nil ⟹ keys stay anonymous
 }
 
-// newIdentityValidator builds a validator. ttl<=0 uses the 15m JWKS default.
+// newIdentityValidator builds a validator whose trusted-issuer set is the primary
+// issuer UNIONED with every white-label brand issuer (BrandIssuers) plus any
+// WHITELABEL_ISSUERS override. ttl<=0 uses the 15m JWKS default. The union is
+// fail-secure: it only ADDS the known-good brand issuers, never an arbitrary one.
 func newIdentityValidator(issuer, jwksURL string, audiences []string, ttl time.Duration) *identityValidator {
 	return &identityValidator{
-		issuer:    strings.TrimSpace(issuer),
+		issuers:   trustedIssuers(issuer),
 		audiences: audiences,
 		cache:     newJWKSCache(jwksURL, ttl),
+		keys:      sharedKeys(), // ONE resolver+cache, shared with OrgForKey (analytics capture)
 	}
 }
 
+// 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,
+// object/token_jwt.go tokenAudience) and owner == <org>
+// (object/token_oauth.go GetClientCredentialsToken sets owner = app.Organization).
+//
+// That audience is, by construction, absent from CLOUD_JWT_AUDIENCES — it is
+// 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. 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-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 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 {
+	if owner == "" {
+		return ""
+	}
+	return owner + kmsMachineAudSuffix
+}
+
+// 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 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-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).
+func isKMSMachinePrincipal(claims *idClaims) bool {
+	mach := kmsMachineAudience(claims.Owner)
+	if mach == "" {
+		return false
+	}
+	for _, a := range claims.Audience {
+		if a == mach {
+			return true
+		}
+	}
+	return false
+}
+
 // validate parses raw, verifies its signature against the JWKS, and enforces
 // issuer/audience/expiry. Returns the claims on success, an error otherwise.
 func (v *identityValidator) validate(raw string) (*idClaims, error) {
@@ -99,8 +212,17 @@ func (v *identityValidator) validate(raw string) (*idClaims, error) {
 		return nil, err
 	}
 
-	// Reject a missing issuer: an empty expected issuer would skip the
-	// comparison and let tokens from any issuer pass.
+	// Fail SECURE on a misconfigured (empty) trust set: an empty issuer OR audience
+	// allowlist must REJECT every token, never silently disable that axis. In
+	// production both are always resolved non-empty (BrandIssuers + the baked
+	// audience defaults, unioned in config.go so they are "never empty"), so this
+	// fires ONLY on an operator misconfiguration (CLOUD_JWT_AUDIENCES="" emptying the
+	// resolved set, or an empty issuer set) — and then it denies, it never admits (I2).
+	if len(v.issuers) == 0 || len(v.audiences) == 0 {
+		return nil, fmt.Errorf("identity validator misconfigured: empty issuer or audience allowlist")
+	}
+
+	// Reject a missing issuer: an empty issuer must never pass the set check.
 	if claims.Issuer == "" {
 		return nil, fmt.Errorf("missing issuer")
 	}
@@ -110,10 +232,27 @@ func (v *identityValidator) validate(raw string) (*idClaims, error) {
 	if claims.Expiry == nil {
 		return nil, fmt.Errorf("missing expiry")
 	}
-	expected := jwt.Expected{Issuer: v.issuer}
-	if len(v.audiences) > 0 {
-		expected.AnyAudience = jwt.Audience(v.audiences)
+	// Issuer must be one of the trusted brand issuers. go-jose's jwt.Expected
+	// checks a SINGLE issuer, so the issuer is validated here against the set and
+	// left out of Expected (audience + expiry stay with Expected).
+	if !issuerAllowed(claims.Issuer, v.issuers) {
+		return nil, fmt.Errorf("untrusted issuer %q", claims.Issuer)
 	}
+	// Audience: the static allowlist (CLOUD_JWT_AUDIENCES / brand app client_ids)
+	// 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 org-scoping: the /v1/kms guard still
+	// gates on owner == :org. Without this, a real client_credentials machine token
+	// (aud == its per-org clientId, never in the allowlist) fails here and the
+	// sync silently stays pending — the activation blocker.
+	// The audience allowlist is guaranteed non-empty (checked above), so the
+	// audience axis is ALWAYS enforced — never silently skipped.
+	auds := v.audiences
+	if mach := kmsMachineAudience(claims.Owner); mach != "" {
+		auds = append(append(make([]string, 0, len(v.audiences)+1), v.audiences...), mach)
+	}
+	expected := jwt.Expected{AnyAudience: jwt.Audience(auds)}
 	if err := claims.Claims.ValidateWithLeeway(expected, 2*time.Minute); err != nil {
 		return nil, fmt.Errorf("claims: %w", err)
 	}
@@ -279,3 +418,46 @@ func basicFromAuth(auth string) string {
 	}
 	return user
 }
+
+// trustedIssuers returns the full trusted-issuer set for the in-binary validator:
+// the PRIMARY issuer (the deployment's own brand, cfg.IAMIssuer) UNIONED with every
+// white-label brand issuer (BrandIssuers) and any WHITELABEL_ISSUERS override
+// (comma-separated). Fail-secure: it only ADDS known-good issuers; a nil/empty
+// result is impossible when a primary is set, so the issuer check is always
+// enforced. Duplicates are removed; order is primary-first.
+func trustedIssuers(primary string) []string {
+	out := make([]string, 0, 6)
+	add := func(v string) {
+		v = strings.TrimSpace(v)
+		if v == "" {
+			return
+		}
+		for _, e := range out {
+			if e == v {
+				return
+			}
+		}
+		out = append(out, v)
+	}
+	add(primary)
+	for _, iss := range BrandIssuers() {
+		add(iss)
+	}
+	for _, iss := range splitTrim(os.Getenv("WHITELABEL_ISSUERS")) {
+		add(iss)
+	}
+	return out
+}
+
+// issuerAllowed reports whether iss is one of the trusted issuers. It is
+// fail-secure in BOTH directions: an empty trusted set matches NOTHING (deny), so
+// a misconfiguration that empties the issuer allowlist rejects every token instead
+// of silently disabling the check (I2); a non-empty set rejects any iss not in it.
+func issuerAllowed(iss string, trusted []string) bool {
+	for _, t := range trusted {
+		if iss == t {
+			return true
+		}
+	}
+	return false
+}

auth_identity_kms_test.go

@@ -0,0 +1,87 @@
+package cloud
+
+// 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/kms (v6_aud_e2e_test.go). Reuses the jwksServer/signWith/tokenClaims
+// helpers from middleware_identity_test.go (same package).
+
+import (
+	"crypto/rand"
+	"crypto/rsa"
+	"testing"
+	"time"
+)
+
+func TestIdentityValidator_KMSMachineAudience(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("genkey: %v", err)
+	}
+	jwks := jwksServer(t, &key.PublicKey)
+	// The static allowlist deliberately contains NO *-platform-kms audience, so any
+	// acceptance below can come ONLY from the owner-bound machine-aud rule, not the
+	// allowlist — this is what makes it a fix and not a config workaround.
+	v := newIdentityValidator(testIssuer, jwks.URL, []string{"hanzo-console"}, 0)
+	future := time.Now().Add(time.Hour)
+
+	t.Run("machine token for its own org is accepted", func(t *testing.T) {
+		c, err := v.validate(signWith(t, key, tokenClaims("maxpower-platform-kms", "maxpower", "", false, future)))
+		if err != nil {
+			t.Fatalf("machine token rejected: %v", err)
+		}
+		if c.Owner != "maxpower" {
+			t.Fatalf("owner=%q, want maxpower", c.Owner)
+		}
+	})
+
+	t.Run("machine aud for a DIFFERENT org is rejected (owner-bound)", func(t *testing.T) {
+		// owner=maxpower but aud=acme-platform-kms: the accepted machine aud is bound
+		// to the token's OWN owner (maxpower-platform-kms), so this must fail — it is
+		// not a blanket "*-platform-kms" wildcard.
+		if _, err := v.validate(signWith(t, key, tokenClaims("acme-platform-kms", "maxpower", "", false, future))); err == nil {
+			t.Fatal("cross-org machine audience must be rejected (owner-bound)")
+		}
+	})
+
+	t.Run("arbitrary audience still rejected (fix is scoped, not a disable)", func(t *testing.T) {
+		if _, err := v.validate(signWith(t, key, tokenClaims("some-random-app", "maxpower", "", false, future))); err == nil {
+			t.Fatal("an arbitrary audience must still be rejected")
+		}
+	})
+
+	t.Run("machine aud with empty owner is rejected (fail closed)", func(t *testing.T) {
+		// aud="-platform-kms" with owner="": kmsMachineAudience("")=="" so no machine
+		// audience is granted and the bare suffix is not in the allowlist.
+		if _, err := v.validate(signWith(t, key, tokenClaims("-platform-kms", "", "", false, future))); err == nil {
+			t.Fatal("machine aud with empty owner must be rejected")
+		}
+	})
+
+	t.Run("normal static-allowlist token still accepted (regression)", func(t *testing.T) {
+		if _, err := v.validate(signWith(t, key, tokenClaims("hanzo-console", "maxpower", "", false, future))); err != nil {
+			t.Fatalf("static-allowlist token rejected: %v", err)
+		}
+	})
+
+	t.Run("machine token expiry still enforced", func(t *testing.T) {
+		if _, err := v.validate(signWith(t, key, tokenClaims("maxpower-platform-kms", "maxpower", "", false, time.Now().Add(-time.Hour)))); err == nil {
+			t.Fatal("expired machine token must be rejected")
+		}
+	})
+}
+
+// kmsMachineAudience is a pure helper; lock its contract directly.
+func TestKMSMachineAudience(t *testing.T) {
+	if got := kmsMachineAudience("maxpower"); got != "maxpower-platform-kms" {
+		t.Fatalf("kmsMachineAudience(maxpower)=%q, want maxpower-platform-kms", got)
+	}
+	if got := kmsMachineAudience(""); got != "" {
+		t.Fatalf("kmsMachineAudience(\"\")=%q, want \"\" (no machine aud for an org-less token)", got)
+	}
+}

auth_identity_whitelabel_test.go

@@ -0,0 +1,186 @@
+package cloud
+
+import (
+	"crypto/rand"
+	"crypto/rsa"
+	"os"
+	"testing"
+	"time"
+)
+
+// TestValidate_FailSecureOnEmptyTrustSet proves I2: a validator whose resolved
+// issuer OR audience allowlist is empty REJECTS an otherwise-valid, correctly
+// signed token — the axis is never silently disabled. Production always resolves
+// non-empty sets; this guards the misconfiguration path (CLOUD_JWT_AUDIENCES=""
+// or an empty issuer set), which must fail closed, not open.
+func TestValidate_FailSecureOnEmptyTrustSet(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("genkey: %v", err)
+	}
+	jwks := jwksServer(t, &key.PublicKey)
+	future := time.Now().Add(time.Hour)
+	tok := signWith(t, key, tokenClaims("hanzo-console", "acme", "", false, future))
+
+	// Sanity: a properly configured validator accepts the token.
+	if _, err := newIdentityValidator(testIssuer, jwks.URL, []string{"hanzo-console"}, 0).validate(tok); err != nil {
+		t.Fatalf("baseline valid token must be accepted, got %v", err)
+	}
+
+	// Empty audience set → deny.
+	if _, err := newIdentityValidator(testIssuer, jwks.URL, nil, 0).validate(tok); err == nil {
+		t.Error("empty audience allowlist must REJECT (fail-secure), not accept")
+	}
+
+	// Empty issuer set → deny (construct directly; trustedIssuers never yields empty
+	// with a primary, so bypass it to exercise the guard).
+	vEmptyIss := &identityValidator{issuers: nil, audiences: []string{"hanzo-console"}, cache: newJWKSCache(jwks.URL, 0), keys: newIAMKeys()}
+	if _, err := vEmptyIss.validate(tok); err == nil {
+		t.Error("empty issuer allowlist must REJECT (fail-secure), not accept")
+	}
+}
+
+// TestTrustedIssuers_WhiteLabel proves the in-binary validator's trusted-issuer
+// set is the primary issuer UNIONED with every white-label brand issuer plus the
+// WHITELABEL_ISSUERS override, deduped, primary-first.
+func TestTrustedIssuers_WhiteLabel(t *testing.T) {
+	os.Unsetenv("WHITELABEL_ISSUERS")
+	got := trustedIssuers("https://hanzo.id")
+	want := map[string]bool{
+		"https://hanzo.id":     true,
+		"https://lux.id":       true,
+		"https://zoo.id":       true, // per cloud brand.go registry
+		"https://pars.id":      true,
+		"https://id.bootno.de": true, // bootnode brand also in the registry
+	}
+	set := map[string]bool{}
+	for _, g := range got {
+		set[g] = true
+	}
+	for w := range want {
+		if !set[w] {
+			t.Errorf("trusted set %v missing %q", got, w)
+		}
+	}
+	if got[0] != "https://hanzo.id" {
+		t.Errorf("primary issuer must be first, got %q", got[0])
+	}
+
+	// Override adds a brand without a rebuild.
+	t.Setenv("WHITELABEL_ISSUERS", "https://custom.id, https://another.id")
+	got2 := trustedIssuers("https://hanzo.id")
+	if !issuerAllowed("https://custom.id", got2) || !issuerAllowed("https://another.id", got2) {
+		t.Errorf("WHITELABEL_ISSUERS override must add issuers, got %v", got2)
+	}
+}
+
+// TestIssuerAllowed proves the set membership check: brand issuers pass, an
+// outsider is rejected, and an empty set is fail-secure — it matches NOTHING (I2),
+// so a misconfiguration that empties the allowlist denies every token.
+func TestIssuerAllowed(t *testing.T) {
+	set := []string{"https://hanzo.id", "https://lux.id"}
+	if !issuerAllowed("https://lux.id", set) {
+		t.Error("lux.id must be allowed")
+	}
+	if issuerAllowed("https://attacker.id", set) {
+		t.Error("attacker.id must be rejected")
+	}
+	if issuerAllowed("anything", nil) {
+		t.Error("empty set must DENY (fail-secure), never skip the check")
+	}
+}
+
+// TestBrandIssuers proves the issuer list is derived from the brands registry and
+// covers every configured brand (one source of truth).
+func TestBrandIssuers(t *testing.T) {
+	got := BrandIssuers()
+	for _, want := range []string{"https://hanzo.id", "https://lux.id", "https://zoo.id", "https://pars.id", "https://id.bootno.de"} {
+		found := false
+		for _, g := range got {
+			if g == want {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("BrandIssuers()=%v missing %q", got, want)
+		}
+	}
+}
+
+// TestNewIdentityValidator_MultiIssuer proves the constructed validator carries the
+// full brand set, so a lux token would pass the issuer gate on the hanzo binary.
+func TestNewIdentityValidator_MultiIssuer(t *testing.T) {
+	os.Unsetenv("WHITELABEL_ISSUERS")
+	v := newIdentityValidator("https://hanzo.id", "http://iam.hanzo.svc/v1/iam/.well-known/jwks", []string{"hanzo-cloud", "lux-cloud"}, 0)
+	if !issuerAllowed("https://lux.id", v.issuers) {
+		t.Fatalf("validator must trust the lux issuer, set=%v", v.issuers)
+	}
+	if !issuerAllowed("https://hanzo.id", v.issuers) {
+		t.Fatalf("validator must still trust hanzo (no regression), set=%v", v.issuers)
+	}
+	if issuerAllowed("https://evil.id", v.issuers) {
+		t.Fatalf("validator must reject an untrusted issuer, set=%v", v.issuers)
+	}
+}
+
+// TestBrandAudiences proves every brand's cloud audience (<brand>-cloud) is derived
+// from the brands registry — one source of truth, mirroring BrandIssuers.
+func TestBrandAudiences(t *testing.T) {
+	got := BrandAudiences()
+	for _, want := range []string{"hanzo-cloud", "lux-cloud", "zoo-cloud", "pars-cloud", "bootnode-cloud"} {
+		found := false
+		for _, g := range got {
+			if g == want {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("BrandAudiences()=%v missing %q", got, want)
+		}
+	}
+}
+
+// TestJWTAudiencesFromEnv_BrandUnion proves the resolved audience allowlist ALWAYS
+// includes every brand's <brand>-cloud aud (so a lux token validates), whether the
+// list comes from the baked default or a hanzo-only env override — and that an
+// env-supplied entry is not duplicated.
+func TestJWTAudiencesFromEnv_BrandUnion(t *testing.T) {
+	has := func(list []string, v string) bool {
+		for _, s := range list {
+			if s == v {
+				return true
+			}
+		}
+		return false
+	}
+
+	// Baked default path (no env).
+	os.Unsetenv("CLOUD_JWT_AUDIENCES")
+	os.Unsetenv("GATEWAY_ALLOWED_AUDIENCES")
+	def := jwtAudiencesFromEnv()
+	for _, want := range []string{"hanzo-cloud", "lux-cloud", "zoo-cloud", "pars-cloud"} {
+		if !has(def, want) {
+			t.Errorf("baked audiences %v missing brand aud %q", def, want)
+		}
+	}
+
+	// A legacy hanzo-only env override must STILL accept lux-cloud (brand union),
+	// with no duplicate of the env-supplied hanzo-cloud.
+	os.Setenv("GATEWAY_ALLOWED_AUDIENCES", "hanzo-app,hanzo-console,hanzo-cloud")
+	defer os.Unsetenv("GATEWAY_ALLOWED_AUDIENCES")
+	got := jwtAudiencesFromEnv()
+	if !has(got, "lux-cloud") {
+		t.Fatalf("hanzo-only env override must still accept lux-cloud, got %v", got)
+	}
+	n := 0
+	for _, s := range got {
+		if s == "hanzo-cloud" {
+			n++
+		}
+	}
+	if n != 1 {
+		t.Fatalf("hanzo-cloud must appear exactly once (no duplicate), got %d in %v", n, got)
+	}
+}

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"},
 }
 
@@ -64,3 +72,84 @@ func BrandFor(id string) BrandInfo {
 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
+// source of truth: derived from the same `brands` registry above.
+func BrandIssuers() []string {
+	out := make([]string, 0, len(brands))
+	for _, b := range brands {
+		if b.IAMIssuer != "" {
+			out = append(out, b.IAMIssuer)
+		}
+	}
+	return out
+}
+
+// BrandAudiences returns the OAuth `aud` (== IAM client_id == app name) of every
+// white-label brand's cloud login app: `<brand>-cloud` (hanzo-cloud, lux-cloud,
+// zoo-cloud, pars-cloud, bootnode-cloud). A brand's session token carries
+// aud=<brand>-cloud (HIP-0111: client_id == app == aud), so the audience allowlist
+// must include each to accept a lux/zoo/pars token on the ONE binary. Derived from
+// the same `brands` registry as BrandIssuers — one source of truth, no hand-listing.
+func BrandAudiences() []string {
+	out := make([]string, 0, len(brands))
+	for id := range brands {
+		if id != "" {
+			out = append(out, id+"-cloud")
+		}
+	}
+	return out
+}

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

@@ -1,13 +1,23 @@
 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/kmsembed"
+	"github.com/hanzoai/cloud/clients/finance"
+	"github.com/hanzoai/cloud/clients/gateway/edge"
+	"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).
@@ -43,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,
@@ -52,50 +63,112 @@ 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)
+	wireTierReader(deps.Metering, 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 := edge.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 edge.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) edge.Policy {
+	p := edge.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.
+		// Honor the documented METERING_TEST env: when "true", route every debit to
+		// commerce's TEST/sandbox books (fin.RecordUsage in.Test=true) so a staging /
+		// canary deployment records NO real money — and the usage-cap read (org.TestMode
+		// via SQUARE_ENVIRONMENT=sandbox) sees the SAME test books. Unset in prod → live,
+		// unchanged. Without this the flag was silently ignored (always live).
+		Test:       strings.EqualFold(strings.TrimSpace(os.Getenv(metering.EnvTest)), "true"),
+		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
@@ -103,52 +176,150 @@ func buildMeteringClient(cfg *Config, log luxlog.Logger) *metering.Client {
 		log.Error("billing: invalid commerce URL, gate disabled", "err", err)
 		m, _ = metering.New(metering.Config{})
 	}
+	// Observe every cap-check fail-open (timeout / slow / broken commerce) — a cap that
+	// silently allows must never be silent. The completion still proceeds (fail-open).
+	metering.OnCapError = func(err error) {
+		log.Warn("spend-cap check failed open (allowing completion) — commerce authorize slow/unavailable", "err", err)
+	}
 	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
+}
+
+// wireTierReader installs the embedded ai module's per-tier SKU gate reader so it
+// resolves the caller's commerce subscription tier through the SAME co-resident
+// commerce client the metering gate bills over — in-process (commerceinproc) when
+// commerce is folded in, S2S HTTP with the service token otherwise — NEVER an authed
+// self-call to the cloud edge. That self-call is the toothless-gate bug: the edge
+// 401/403s a service call to /v1/billing/*, so the ai module's own HTTP lookup always
+// returned "" in-cluster and every tier-gated SKU failed OPEN. This mirrors
+// wireFinance's SetBalanceReader: cloud owns the co-resident read, ai stays
+// transport-agnostic. Fail-safe is preserved — Client.Tier folds a commerce error or
+// an unknown plan to "", which the gate treats as ALLOW, so a commerce blip never
+// locks out a paying caller. No-op when commerce is unreachable (metering !Enabled),
+// leaving ai's standalone HTTP fallback in place.
+func wireTierReader(m *metering.Client, log luxlog.Logger) {
+	if m == nil || !m.Enabled() {
+		return
 	}
-	return clients.DisabledIAM()
+	aiobject.SetTierReader(func(ctx context.Context, subject, namespace string) (string, error) {
+		return m.Tier(ctx, subject, namespace)
+	})
+	log.Info("ai per-tier SKU gate wired to co-resident commerce (in-process tier read, fail-safe)")
+}
+
+// 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.
+	}
+	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/kms.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 := kmsembed.New(kmsembed.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 != "" {
@@ -158,20 +329,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)
@@ -180,52 +566,114 @@ 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
+// must return a concrete client, never nil. (A nil deps.AI was the live bug —
+// the default all-enabled config returned nil here and nothing ever filled it,
+// so every /v1/agents/:name/run 503'd "inference is not configured".)
+//
+// Preference order:
+//  1. Static-key HTTP gateway when a base URL AND a static key are configured —
+//     an operator override / pre-provisioned key. The key is a KMS-injected
+//     secret; only the base URL and default model are ever logged.
+//  2. M2M HTTP gateway when a base URL AND the binary's IAM identity are present
+//     (the durable Hanzo default): the client mints+refreshes a client-
+//     credentials token from IAM_CLIENT_ID/SECRET — no static key to rotate. The
+//     secret is never logged.
+//  3. ZAP RPC when an addr is configured (split-deploy of a future ai subsystem).
+//  4. Fail-closed stub otherwise — a run records an honest error, never fakes one.
 func pickAIClient(cfg *Config, log luxlog.Logger) AIClient {
-	if cfg.Enabled("ai") {
-		return nil
+	if cfg.AIBaseURL != "" && cfg.AIAPIKey != "" {
+		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 != "" {
+		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)
 		return clients.AIRPCAt(cfg.AIZAPAddr)
 	}
+	log.Info("deps.AI → disabled (no CLOUD_AI_API_KEY, no IAM M2M identity, no gateway configured)")
 	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)
@@ -242,45 +690,53 @@ 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
 
-// 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).
+// ShutdownFunc releases a subsystem's process-lifetime resources (background
+// goroutines, open DB handles) on graceful shutdown. It must be idempotent and
+// bounded — Serve calls it within the shutdown deadline. ctx carries that
+// deadline so a slow teardown is cut off rather than hanging SIGTERM.
+type ShutdownFunc func(ctx context.Context) error
+
+// 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
+	Name     string
+	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})
-}
-
-// 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
@@ -288,6 +744,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.

caller_bearer_test.go

@@ -0,0 +1,51 @@
+package cloud
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	luxlog "github.com/luxfi/log"
+	"github.com/zap-proto/zip"
+)
+
+// CallerBearer relays the caller's OWN validated JWT bearer and nothing else: a JWT
+// passes through unchanged, an opaque API key is not relayable, and no credential
+// yields "". This is the token a downstream org-scoped service (the DNS forward
+// head) re-validates to enforce tenant isolation across the hop.
+func TestCallerBearer(t *testing.T) {
+	app := zip.New(zip.Config{Logger: luxlog.New("test")})
+	app.Get("/probe", func(c *zip.Ctx) error { return c.Bytes(200, []byte(CallerBearer(c))) })
+
+	probe := func(setup func(*http.Request)) string {
+		req := httptest.NewRequest(http.MethodGet, "/probe", nil)
+		if setup != nil {
+			setup(req)
+		}
+		res, err := app.Fiber().Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		b, _ := io.ReadAll(res.Body)
+		_ = res.Body.Close()
+		return string(b)
+	}
+
+	cases := []struct {
+		name  string
+		setup func(*http.Request)
+		want  string
+	}{
+		{"jwt bearer relayed unchanged", func(r *http.Request) { r.Header.Set("Authorization", "Bearer jwt.header.sig") }, "jwt.header.sig"},
+		{"X-Authorization fallback", func(r *http.Request) { r.Header.Set("X-Authorization", "Bearer x.y.z") }, "x.y.z"},
+		{"opaque hk- api key is NOT relayable", func(r *http.Request) { r.Header.Set("Authorization", "Bearer hk-secret") }, ""},
+		{"opaque sk- api key is NOT relayable", func(r *http.Request) { r.Header.Set("Authorization", "Bearer sk-secret") }, ""},
+		{"no credential yields empty", nil, ""},
+	}
+	for _, c := range cases {
+		if got := probe(c.setup); got != c.want {
+			t.Errorf("%s: CallerBearer = %q, want %q", c.name, got, c.want)
+		}
+	}
+}

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,13 +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
@@ -95,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.
@@ -225,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.
 // ---------------------------------------------------------------------------
@@ -283,11 +458,30 @@ func (e *Env) accessToken() string {
 	return firstNonEmpty(os.Getenv("HANZO_TOKEN"), e.creds.AccessToken)
 }
 
-// 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
-// (in precedence) the bound --platform-token flag, the environment, then the
-// credential store. Never hardcoded.
+// 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 bearer the platform control plane authenticates
+// apps/clusters/redeploy with. ONE identity authorizes everything: after a plain
+// `hanzo login` the IAM access token is the FINAL fallback, so no separate
+// --platform-token is needed — the platform verifies the IAM JWT (signature,
+// issuer, expiry) and org-scopes the caller. A dedicated service token still
+// wins when present (flag > env > credential store > IAM login), so purpose-minted
+// machine tokens keep their precedence and internal automation is unchanged.
+// Never hardcoded.
 func (e *Env) platformToken(flagVal string) string {
 	return firstNonEmpty(
 		flagVal,
@@ -295,17 +489,22 @@ func (e *Env) platformToken(flagVal string) string {
 		os.Getenv("PLATFORM_SERVICE_TOKEN"),
 		os.Getenv("PAAS_SERVICE_TOKEN"),
 		e.creds.PlatformToken,
+		e.accessToken(), // IAM login is the one identity that authorizes control-plane ops
 	)
 }
 
-// buildToken resolves the platform build-enqueue token (a distinct credential
-// from the service token — see /v1/arcd/enqueue).
+// buildToken resolves the bearer `hanzo build` sends to the platform build
+// enqueue (/v1/runner). Same unify-infra contract as platformToken: a dedicated
+// build token wins when present, but a plain IAM login is the FINAL fallback, so
+// `hanzo build` works off the one identity with no separate --build-token — the
+// platform verifies the IAM JWT and authorizes the build by org + role.
 func (e *Env) buildToken(flagVal string) string {
 	return firstNonEmpty(
 		flagVal,
 		os.Getenv("HANZO_BUILD_TOKEN"),
 		os.Getenv("PLATFORM_BUILD_CALLBACK_TOKEN"),
 		e.creds.BuildToken,
+		e.accessToken(), // IAM login is the one identity that authorizes builds
 	)
 }
 
@@ -361,6 +560,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()
@@ -386,8 +596,15 @@ func newRootCmd() *cobra.Command {
 		newDeployCmd(envOf, &f),
 		newClustersCmd(envOf, &f),
 		newBuildCmd(envOf, &f),
-		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
 }
@@ -416,7 +633,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>",
@@ -504,6 +721,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)
 	}
@@ -527,6 +748,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/cli_test.go

@@ -141,6 +141,29 @@ func TestPlatformTokenPrecedence(t *testing.T) {
 	}
 }
 
+// TestPlatformTokenFallsBackToIAM is the UNIFY-INFRA contract for the control
+// plane: after a plain `hanzo login`, the IAM access token is the FINAL fallback
+// so `hanzo apps`/`hanzo deploy` authorize off the one identity. An explicit
+// platform service token (creds/env/flag) still wins.
+func TestPlatformTokenFallsBackToIAM(t *testing.T) {
+	sandbox(t)
+	// Only an IAM login: no platform token anywhere ⇒ the IAM access token is sent.
+	e := resolve(&Config{}, &Credentials{AccessToken: "iam-jwt"}, globalFlags{})
+	if got := e.platformToken(""); got != "iam-jwt" {
+		t.Fatalf("IAM access token should be the final platform-token fallback: %q", got)
+	}
+	// A dedicated platform service token still beats the IAM token.
+	e = resolve(&Config{}, &Credentials{AccessToken: "iam-jwt", PlatformToken: "svc"}, globalFlags{})
+	if got := e.platformToken(""); got != "svc" {
+		t.Fatalf("dedicated platform token must beat the IAM fallback: %q", got)
+	}
+	// No login at all ⇒ empty (caller surfaces "run `hanzo login`").
+	e = resolve(&Config{}, &Credentials{}, globalFlags{})
+	if got := e.platformToken(""); got != "" {
+		t.Fatalf("no token and no login should resolve empty: %q", got)
+	}
+}
+
 func TestBuildTokenPrecedence(t *testing.T) {
 	sandbox(t)
 	e := resolve(&Config{}, &Credentials{BuildToken: "creds"}, globalFlags{})
@@ -156,6 +179,37 @@ func TestBuildTokenPrecedence(t *testing.T) {
 	}
 }
 
+// TestBuildTokenFallsBackToIAM is the UNIFY-INFRA contract: after a plain
+// `hanzo login` (no --build-token), the IAM access token is the FINAL fallback,
+// so `hanzo build` authorizes off the one identity. An explicit build token
+// (creds/env/flag) still wins — the IAM token is the LAST resort, never an
+// override of a purpose-minted machine token.
+func TestBuildTokenFallsBackToIAM(t *testing.T) {
+	sandbox(t)
+	// Only an IAM login: no build token anywhere ⇒ the IAM access token is sent.
+	e := resolve(&Config{}, &Credentials{AccessToken: "iam-jwt"}, globalFlags{})
+	if got := e.buildToken(""); got != "iam-jwt" {
+		t.Fatalf("IAM access token should be the final build-token fallback: %q", got)
+	}
+	// A dedicated build token still beats the IAM token (precedence preserved).
+	e = resolve(&Config{}, &Credentials{AccessToken: "iam-jwt", BuildToken: "creds"}, globalFlags{})
+	if got := e.buildToken(""); got != "creds" {
+		t.Fatalf("dedicated build token must beat the IAM fallback: %q", got)
+	}
+	// HANZO_TOKEN (the env form of the IAM token) is also honored via accessToken().
+	e = resolve(&Config{}, &Credentials{}, globalFlags{})
+	t.Setenv("HANZO_TOKEN", "iam-env")
+	if got := e.buildToken(""); got != "iam-env" {
+		t.Fatalf("HANZO_TOKEN should back the build-token fallback: %q", got)
+	}
+	// No login at all ⇒ empty, so the caller can surface "run `hanzo login`".
+	t.Setenv("HANZO_TOKEN", "")
+	e = resolve(&Config{}, &Credentials{}, globalFlags{})
+	if got := e.buildToken(""); got != "" {
+		t.Fatalf("no token and no login should resolve empty: %q", got)
+	}
+}
+
 func TestAccessTokenFromEnvOverCreds(t *testing.T) {
 	sandbox(t)
 	e := resolve(&Config{}, &Credentials{AccessToken: "creds"}, globalFlags{})

cli/code.go

@@ -0,0 +1,680 @@
+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
+	continueArgs []string                   // harness-native form of Hanzo -c/--continue
+	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"},
+		continueArgs: []string{"resume", "--last"},
+		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"`,
+				// api.hanzo.ai exposes the standard OpenAI /v1/models shape,
+				// not Codex's private remote model-catalog schema. Skip that
+				// optional refresh and supply the coding model's metadata here.
+				"-c", `features.remote_models=false`,
+				"-c", `model_context_window=262144`,
+				"-c", `model_auto_compact_token_limit=235929`,
+			}
+		},
+		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"},
+		continueArgs: []string{"--continue"},
+		// --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), -c resumes either harness, and agents run full-auto unless\n" +
+			"you pass --safe. Unknown options pass through; -- forces verbatim passthrough.",
+		Example: "  hanzo code                 # dev, the default agent\n" +
+			"  hanzo code claude\n" +
+			"  hanzo code claude -c\n" +
+			"  hanzo code codex -c\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 before -- is the model; --safe and --continue are ours.
+	// Unknown options pass through unchanged. Everything after -- belongs to the
+	// agent, including positional subcommands and raw Codex -c config overrides.
+	model, safe, continueLast, rest := splitCodeArgs(args)
+	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, codeAgentRest(agent, continueLast, 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
+}
+
+// splitCodeArgs pulls the launcher-owned tokens (the model, --safe, -c/--continue)
+// out of the raw args; everything else is the agent's. The `--` separator is ours
+// and switches on verbatim passthrough — every token after it goes to the agent
+// untouched, including positional subcommands (`codex exec`) and raw Codex -c
+// config overrides that would otherwise look like our --continue.
+func splitCodeArgs(args []string) (model string, safe, continueLast bool, rest []string) {
+	rest = make([]string, 0, len(args))
+	passthrough := false
+	for _, a := range args {
+		switch {
+		case passthrough:
+			rest = append(rest, a)
+		case a == "--": // the separator is ours; the agent must not see it
+			passthrough = true
+		case a == "--safe" || a == "--ask":
+			safe = true
+		case a == "-c" || a == "--continue":
+			continueLast = true
+		case model == "" && !strings.HasPrefix(a, "-") && len(rest) == 0:
+			model = a
+		default:
+			rest = append(rest, a)
+		}
+	}
+	return model, safe, continueLast, rest
+}
+
+// codeAgentRest prepends the agent's harness-native resume tokens when -c/--continue
+// was given, so one Hanzo flag resumes the last session on either harness (`--continue`
+// for Claude Code, `resume --last` for Codex/dev).
+func codeAgentRest(agent codeAgent, continueLast bool, rest []string) []string {
+	if !continueLast {
+		return rest
+	}
+	args := make([]string, 0, len(agent.continueArgs)+len(rest))
+	args = append(args, agent.continueArgs...)
+	return append(args, rest...)
+}
+
+// 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,476 @@
+// 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"
+	"reflect"
+	"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)
+			}
+		})
+	}
+}
+
+func TestCodeArgsSeparatorPreservesAgentSubcommand(t *testing.T) {
+	model, safe, continueLast, rest := splitCodeArgs([]string{"--safe", "--", "exec", "--ephemeral", "do it"})
+	if model != "" || !safe || continueLast {
+		t.Fatalf("model=%q safe=%v continue=%v, want default model and safe mode", model, safe, continueLast)
+	}
+	if want := []string{"exec", "--ephemeral", "do it"}; !reflect.DeepEqual(rest, want) {
+		t.Fatalf("agent args = %q, want %q", rest, want)
+	}
+}
+
+func TestCodeArgsExplicitModelBeforeSeparator(t *testing.T) {
+	model, safe, continueLast, rest := splitCodeArgs([]string{"zen5-max", "--", "exec"})
+	if model != "zen5-max" || safe || continueLast || !reflect.DeepEqual(rest, []string{"exec"}) {
+		t.Fatalf("model=%q safe=%v continue=%v rest=%q", model, safe, continueLast, rest)
+	}
+}
+
+func TestCodeContinueIsNormalizedForBothHarnesses(t *testing.T) {
+	for _, tt := range []struct {
+		name string
+		want []string
+	}{
+		{name: "claude", want: []string{"--continue"}},
+		{name: "codex", want: []string{"resume", "--last"}},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			model, safe, continueLast, rest := splitCodeArgs([]string{"-c"})
+			if model != "" || safe || !continueLast || len(rest) != 0 {
+				t.Fatalf("model=%q safe=%v continue=%v rest=%q", model, safe, continueLast, rest)
+			}
+			if got := codeAgentRest(codeAgents[tt.name], continueLast, rest); !reflect.DeepEqual(got, tt.want) {
+				t.Fatalf("normalized continue args = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestCodeUnknownOptionsAndPostSeparatorArgsPassThrough(t *testing.T) {
+	unknown := []string{"--mystery", "value", "--other=1"}
+	model, safe, continueLast, rest := splitCodeArgs(unknown)
+	if model != "" || safe || continueLast || !reflect.DeepEqual(rest, unknown) {
+		t.Fatalf("unknown options changed: model=%q safe=%v continue=%v rest=%q", model, safe, continueLast, rest)
+	}
+
+	_, _, continueLast, rest = splitCodeArgs([]string{"--", "-c", "model=x"})
+	if continueLast || !reflect.DeepEqual(rest, []string{"-c", "model=x"}) {
+		t.Fatalf("post-separator Codex config must pass verbatim: continue=%v rest=%q", continueLast, rest)
+	}
+}
+
+func TestCodexProviderUsesNativeResponsesMetadata(t *testing.T) {
+	argv := codeArgv(codeAgents["codex"], "https://api.hanzo.ai", defaultCodeModel, false, nil)
+	for _, want := range []string{
+		`model_provider=hanzo`,
+		`model_providers.hanzo.base_url="https://api.hanzo.ai/v1"`,
+		`model_providers.hanzo.wire_api="responses"`,
+		`features.remote_models=false`,
+		`model_context_window=262144`,
+		`model_auto_compact_token_limit=235929`,
+	} {
+		if !slices.Contains(argv, want) {
+			t.Errorf("Codex argv %q does not contain %q", argv, want)
+		}
+	}
+}
+
+// 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

@@ -3,6 +3,7 @@ package cli
 import (
 	"fmt"
 	"io"
+	"strings"
 	"text/tabwriter"
 
 	"github.com/spf13/cobra"
@@ -15,12 +16,12 @@ func (e *Env) platform(gf *globalFlags) *Platform {
 	return newPlatform(e.PlatformURL, e.platformToken(gf.platformToken))
 }
 
-// deref renders a *string for a table cell, "-" when nil/empty.
-func deref(p *string) string {
-	if p == nil || *p == "" {
+// dashIfEmpty renders a string cell, "-" when empty.
+func dashIfEmpty(s string) string {
+	if s == "" {
 		return "-"
 	}
-	return *p
+	return s
 }
 
 // yesno renders a bool for a table cell.
@@ -37,7 +38,8 @@ func newTab(w io.Writer) *tabwriter.Writer {
 }
 
 // ---------------------------------------------------------------------------
-// apps — the observe surface.
+// apps — the fleet drift board (GET /v1/paas/apps). Org-confined server-side by
+// the IAM identity: a superadmin sees the whole fleet, an org-admin only its own.
 // ---------------------------------------------------------------------------
 
 func newAppsCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
@@ -56,7 +58,6 @@ func newAppsCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			e := envOf()
 			res, err := e.platform(gf).Apps(cmd.Context(), AppsQuery{
-				Org:    e.Org, // empty == all (single-tenant default)
 				Env:    envFilter,
 				Health: healthFilter,
 				Drift:  driftOnly,
@@ -69,8 +70,8 @@ func newAppsCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
 				fmt.Fprintln(tw, "ORG\tAPP\tENV\tDECLARED\tRUNNING\tHEALTH\tDRIFT")
 				for _, a := range res.Apps {
 					fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\t%s\t%s\n",
-						a.Org, a.App, a.Env, deref(a.DeclaredTag), deref(a.RunningTag),
-						deref(a.Health), driftSeverity(a.Drift))
+						a.Org, a.App, a.Env, dashIfEmpty(a.DeclaredTag), dashIfEmpty(a.RunningTag),
+						dashIfEmpty(a.Health), driftSeverity(a.Drift))
 				}
 				tw.Flush()
 				fmt.Fprintf(w, "\n%d apps  (ok=%d yellow=%d red=%d)\n",
@@ -79,17 +80,17 @@ func newAppsCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
 			})
 		},
 	}
-	list.Flags().StringVar(&envFilter, "env", "", "filter by env: dev|test|main")
+	list.Flags().StringVar(&envFilter, "env", "", "filter by env: main|test|dev")
 	list.Flags().StringVar(&healthFilter, "health", "", "filter by health: green|yellow|red")
 	list.Flags().BoolVar(&driftOnly, "drift", false, "only rows that are drifting")
 
 	get := &cobra.Command{
-		Use:   "get <org/app/env>",
-		Short: "Get one app row by its <org>/<app>/<env> id",
+		Use:   "get <app>",
+		Short: "Get one app row by its CR name (production by default)",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			e := envOf()
-			a, err := e.platform(gf).App(cmd.Context(), args[0], e.Org)
+			a, err := e.platform(gf).App(cmd.Context(), args[0])
 			if err != nil {
 				return err
 			}
@@ -101,109 +102,93 @@ func newAppsCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
 				fmt.Fprintf(tw, "env:\t%s\n", a.Env)
 				fmt.Fprintf(tw, "repo:\t%s\n", a.Repo)
 				fmt.Fprintf(tw, "registry:\t%s\n", a.Registry)
-				fmt.Fprintf(tw, "declared:\t%s\n", deref(a.DeclaredTag))
-				fmt.Fprintf(tw, "running:\t%s\n", deref(a.RunningTag))
-				fmt.Fprintf(tw, "latest:\t%s\n", deref(a.LatestTag))
-				fmt.Fprintf(tw, "health:\t%s\n", deref(a.Health))
+				fmt.Fprintf(tw, "declared:\t%s\n", dashIfEmpty(a.DeclaredTag))
+				fmt.Fprintf(tw, "running:\t%s\n", dashIfEmpty(a.RunningTag))
+				fmt.Fprintf(tw, "health:\t%s\n", dashIfEmpty(a.Health))
+				fmt.Fprintf(tw, "phase:\t%s\n", dashIfEmpty(a.Phase))
 				fmt.Fprintf(tw, "drift:\t%s\n", driftSeverity(a.Drift))
-				fmt.Fprintf(tw, "cluster:\t%s\n", deref(a.Cluster))
-				fmt.Fprintf(tw, "namespace:\t%s\n", deref(a.Namespace))
-				fmt.Fprintf(tw, "updated:\t%s\n", a.UpdatedAt)
+				fmt.Fprintf(tw, "cluster:\t%s\n", dashIfEmpty(a.Cluster))
+				fmt.Fprintf(tw, "namespace:\t%s\n", dashIfEmpty(a.Namespace))
+				if len(a.Endpoints) > 0 {
+					fmt.Fprintf(tw, "endpoints:\t%s\n", strings.Join(a.Endpoints, ", "))
+				}
 				tw.Flush()
 			})
 		},
 	}
 
-	sync := &cobra.Command{
-		Use:   "sync",
-		Short: "Trigger an inventory refresh of the apps board",
-		Args:  cobra.NoArgs,
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			e := envOf()
-			if err := e.platform(gf).SyncApps(cmd.Context()); err != nil {
-				return err
-			}
-			fmt.Fprintln(cmd.OutOrStdout(), "apps sync triggered")
-			return nil
-		},
-	}
-
-	cmd.AddCommand(list, get, sync)
+	cmd.AddCommand(list, get)
 	return cmd
 }
 
 // ---------------------------------------------------------------------------
-// deploy — the drive surface (rolling restart, zero-downtime).
+// deploy — POST /v1/paas/apps/{app}/deploy: a zero-downtime rolling restart.
 // ---------------------------------------------------------------------------
 
 func newDeployCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
-	var project, environment string
+	var environment string
 	cmd := &cobra.Command{
-		Use:   "deploy <container>",
-		Short: "Redeploy a container (rolling restart, zero-downtime)",
-		Long: "Drive a platform redeploy: a rolling restart of the container's k8s\n" +
-			"Deployment (re-pulls the image, recreates pods, zero downtime). Coordinates\n" +
-			"are exact — org (--org/config), project (--project), env (--env) and the\n" +
-			"container id (positional). This is the canonical PaaS-driven deploy.",
+		Use:   "deploy <app>",
+		Short: "Redeploy an app (rolling restart, zero-downtime) — requires --env",
+		Long: "Drive a platform redeploy: a rolling restart of the app's k8s Deployment\n" +
+			"(re-pulls the declared image, recreates pods, zero downtime). The app is the\n" +
+			"operator App CR name; the org comes from your IAM identity. --env is REQUIRED\n" +
+			"(main|test|dev) — deploy never silently targets production. Restarting a shared\n" +
+			"platform service is a platform-operator action, so this needs a superadmin\n" +
+			"identity. A TAG change is still a git commit — this restarts what is declared.",
 		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
+			if strings.TrimSpace(environment) == "" {
+				return fmt.Errorf("--env is required (main|test|dev) — deploy will not default to production")
+			}
 			e := envOf()
-			org, err := e.requireOrg()
+			res, err := e.platform(gf).Redeploy(cmd.Context(), args[0], environment)
 			if err != nil {
 				return err
 			}
-			if project == "" || environment == "" {
-				return fmt.Errorf("--project and --env are required (the container's project/environment ids)")
-			}
-			container := args[0]
-			if err := e.platform(gf).Redeploy(cmd.Context(), org, project, environment, container); err != nil {
-				return err
-			}
-			fmt.Fprintf(cmd.OutOrStdout(), "redeployed %s (org=%s project=%s env=%s)\n", container, org, project, environment)
-			return nil
+			return e.emit(res, func(w io.Writer) {
+				fmt.Fprintf(w, "restarted %s (namespace=%s env=%s at %s)\n",
+					res.App, res.Namespace, dashIfEmpty(res.Env), res.RestartedAt)
+			})
 		},
 	}
-	cmd.Flags().StringVar(&project, "project", "", "project id")
-	cmd.Flags().StringVar(&environment, "env", "", "environment id")
+	cmd.Flags().StringVar(&environment, "env", "", "lifecycle env: main|test|dev (REQUIRED)")
 	return cmd
 }
 
 // ---------------------------------------------------------------------------
-// clusters — dedicated DOKS cluster lifecycle.
+// clusters — GET /v1/clusters: the org's compute fleet (Visor-managed + BYO),
+// tenant-scoped server-side by the IAM identity.
 // ---------------------------------------------------------------------------
 
 func newClustersCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "clusters",
 		Aliases: []string{"cluster"},
-		Short:   "Provision/list/select dedicated DOKS clusters",
+		Short:   "List the org's clusters (managed + BYO)",
 	}
 
 	list := &cobra.Command{
 		Use:   "list",
-		Short: "List the org's dedicated clusters",
+		Short: "List the org's clusters",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			e := envOf()
-			org, err := e.requireOrg()
-			if err != nil {
-				return err
-			}
-			cs, err := e.platform(gf).Clusters(cmd.Context(), org)
+			cs, err := e.platform(gf).Clusters(cmd.Context())
 			if err != nil {
 				return err
 			}
 			return e.emit(cs, func(w io.Writer) {
 				tw := newTab(w)
-				fmt.Fprintln(tw, "NAME\tID\tREGION\tSTATUS\tPHASE\tACTIVE\tOPERATOR\tBASELINE")
+				fmt.Fprintln(tw, "NAME\tID\tREGION\tSTATUS\tKIND\tNODES\tSIZE\tGPUS")
 				for _, c := range cs {
-					fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n",
-						c.Name, c.DoksClusterID, c.Region, c.Status, c.Phase,
-						yesno(c.Active), yesno(c.OperatorInstalled), yesno(c.BaselineInstalled))
+					fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\t%d\t%s\t%s\n",
+						c.Name, dashIfEmpty(c.ID()), dashIfEmpty(c.Region), dashIfEmpty(c.Status),
+						dashIfEmpty(c.Kind), c.NodeCount, dashIfEmpty(c.NodeSize), gpuCell(c))
 				}
 				tw.Flush()
 				if len(cs) == 0 {
-					fmt.Fprintln(w, "(no dedicated clusters)")
+					fmt.Fprintln(w, "(no clusters)")
 				}
 			})
 		},
@@ -215,157 +200,57 @@ func newClustersCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			e := envOf()
-			org, err := e.requireOrg()
-			if err != nil {
-				return err
-			}
-			cs, err := e.platform(gf).Clusters(cmd.Context(), org)
+			cs, err := e.platform(gf).Clusters(cmd.Context())
 			if err != nil {
 				return err
 			}
 			for _, c := range cs {
-				if c.DoksClusterID == args[0] || c.Name == args[0] {
+				if c.ID() == args[0] || c.Name == args[0] {
 					return e.emit(c, func(w io.Writer) { printCluster(w, c) })
 				}
 			}
-			return fmt.Errorf("cluster %q not found in org %s", args[0], org)
+			return fmt.Errorf("cluster %q not found", args[0])
 		},
 	}
 
-	var region, nodeSize string
-	var ha bool
-	var nodeCount int
-	create := &cobra.Command{
-		Use:   "create",
-		Short: "Provision a new dedicated DOKS cluster for the org",
-		Args:  cobra.NoArgs,
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			e := envOf()
-			org, err := e.requireOrg()
-			if err != nil {
-				return err
-			}
-			c, err := e.platform(gf).ProvisionCluster(cmd.Context(), org, ProvisionReq{
-				Region: region, HA: ha, NodeSize: nodeSize, NodeCount: nodeCount,
-			})
-			if err != nil {
-				return err
-			}
-			return e.emit(c, func(w io.Writer) {
-				fmt.Fprintf(w, "provisioning cluster %s (%s)\n", c.Name, c.DoksClusterID)
-				printCluster(w, *c)
-			})
-		},
-	}
-	create.Flags().StringVar(&region, "region", "", "DO region (default sfo3)")
-	create.Flags().BoolVar(&ha, "ha", false, "highly-available control plane")
-	create.Flags().StringVar(&nodeSize, "node-size", "", "node size slug (e.g. s-2vcpu-4gb)")
-	create.Flags().IntVar(&nodeCount, "node-count", 0, "node count")
-
-	var shared bool
-	selectCmd := &cobra.Command{
-		Use:   "select <cluster-id>",
-		Short: "Set the org's active deploy target (or --shared to revert)",
-		Args:  cobra.MaximumNArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			e := envOf()
-			org, err := e.requireOrg()
-			if err != nil {
-				return err
-			}
-			var clusterID *string
-			switch {
-			case shared:
-				clusterID = nil
-			case len(args) == 1:
-				clusterID = &args[0]
-			default:
-				return fmt.Errorf("give a cluster id, or --shared to revert to the shared cluster")
-			}
-			t, err := e.platform(gf).SelectTarget(cmd.Context(), org, clusterID)
-			if err != nil {
-				return err
-			}
-			return e.emit(t, func(w io.Writer) { printTarget(w, t) })
-		},
-	}
-	selectCmd.Flags().BoolVar(&shared, "shared", false, "revert to the shared cluster")
-
-	installBaseline := &cobra.Command{
-		Use:   "install-baseline <cluster-id>",
-		Short: "Install the hanzo-operator + per-tenant baseline on a cluster",
-		Args:  cobra.ExactArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			e := envOf()
-			org, err := e.requireOrg()
-			if err != nil {
-				return err
-			}
-			if err := e.platform(gf).InstallBaseline(cmd.Context(), org, args[0]); err != nil {
-				return err
-			}
-			fmt.Fprintf(cmd.OutOrStdout(), "baseline install requested for %s\n", args[0])
-			return nil
-		},
-	}
-
-	target := &cobra.Command{
-		Use:   "target",
-		Short: "Show the org's current resolved deploy target",
-		Args:  cobra.NoArgs,
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			e := envOf()
-			org, err := e.requireOrg()
-			if err != nil {
-				return err
-			}
-			t, err := e.platform(gf).Target(cmd.Context(), org)
-			if err != nil {
-				return err
-			}
-			return e.emit(t, func(w io.Writer) { printTarget(w, t) })
-		},
-	}
-
-	cmd.AddCommand(list, get, create, selectCmd, installBaseline, target)
+	cmd.AddCommand(list, get)
 	return cmd
 }
 
+// gpuCell renders the live GPU inventory of a cluster ("-" when none).
+func gpuCell(c Cluster) string {
+	var parts []string
+	if c.NvidiaGPU > 0 {
+		parts = append(parts, fmt.Sprintf("%d nvidia", c.NvidiaGPU))
+	}
+	if c.AmdGPU > 0 {
+		parts = append(parts, fmt.Sprintf("%d amd", c.AmdGPU))
+	}
+	if len(parts) == 0 {
+		return "-"
+	}
+	return strings.Join(parts, "+")
+}
+
 func printCluster(w io.Writer, c Cluster) {
 	tw := newTab(w)
-	fmt.Fprintf(tw, "id:\t%s\n", c.DoksClusterID)
+	fmt.Fprintf(tw, "id:\t%s\n", dashIfEmpty(c.ID()))
 	fmt.Fprintf(tw, "name:\t%s\n", c.Name)
-	fmt.Fprintf(tw, "region:\t%s\n", c.Region)
-	fmt.Fprintf(tw, "status:\t%s\n", c.Status)
-	fmt.Fprintf(tw, "phase:\t%s\n", c.Phase)
-	fmt.Fprintf(tw, "active:\t%s\n", yesno(c.Active))
-	fmt.Fprintf(tw, "operatorInstalled:\t%s\n", yesno(c.OperatorInstalled))
-	fmt.Fprintf(tw, "baselineInstalled:\t%s\n", yesno(c.BaselineInstalled))
-	fmt.Fprintf(tw, "endpoint:\t%s\n", deref(c.Endpoint))
-	fmt.Fprintf(tw, "k8sVersion:\t%s\n", deref(c.K8sVersion))
-	fmt.Fprintf(tw, "created:\t%s\n", c.CreatedAt)
-	if c.BaselineError != nil && *c.BaselineError != "" {
-		fmt.Fprintf(tw, "baselineError:\t%s\n", *c.BaselineError)
-	}
-	tw.Flush()
-}
-
-func printTarget(w io.Writer, t *Target) {
-	tw := newTab(w)
-	kind := "shared"
-	if t.Dedicated {
-		kind = "dedicated"
-	}
-	fmt.Fprintf(tw, "cluster:\t%s\n", t.Cluster)
-	fmt.Fprintf(tw, "kind:\t%s\n", kind)
-	for ns, env := range t.Namespaces {
-		fmt.Fprintf(tw, "namespace:\t%s -> %s\n", ns, env)
+	fmt.Fprintf(tw, "region:\t%s\n", dashIfEmpty(c.Region))
+	fmt.Fprintf(tw, "status:\t%s\n", dashIfEmpty(c.Status))
+	fmt.Fprintf(tw, "kind:\t%s\n", dashIfEmpty(c.Kind))
+	fmt.Fprintf(tw, "nodeCount:\t%d\n", c.NodeCount)
+	fmt.Fprintf(tw, "nodeSize:\t%s\n", dashIfEmpty(c.NodeSize))
+	fmt.Fprintf(tw, "gpus:\t%s\n", gpuCell(c))
+	fmt.Fprintf(tw, "created:\t%s\n", dashIfEmpty(c.CreatedAt))
+	for _, np := range c.NodePools {
+		fmt.Fprintf(tw, "pool:\t%s (%s x%d, autoscale=%s)\n", np.Name, np.Size, np.Count, yesno(np.AutoScale))
 	}
 	tw.Flush()
 }
 
 // ---------------------------------------------------------------------------
-// build — platform-native (arcd) build enqueue.
+// build — platform-native build (runner fabric) enqueue.
 // ---------------------------------------------------------------------------
 
 func newBuildCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
@@ -373,8 +258,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).",
@@ -387,6 +272,10 @@ func newBuildCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
 			if br.Repo == "" || br.SHA == "" || br.Image == "" {
 				return fmt.Errorf("--repo (or positional), --sha and --image are required")
 			}
+			// The platform build muscle clones an https git URL; accept the
+			// idiomatic `owner/name` shorthand and expand it to GitHub (the host
+			// for every hanzoai/luxfi/zooai repo). A full URL passes through.
+			br.Repo = normalizeRepoURL(br.Repo)
 			if br.OrganizationID == "" {
 				br.OrganizationID = e.Org // optional; server defaults to DEFAULT_BUILD_ORG_ID
 			}
@@ -419,32 +308,24 @@ func newBuildCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
 	return cmd
 }
 
-// ---------------------------------------------------------------------------
-// k8s — deploy-target helpers.
-// ---------------------------------------------------------------------------
-
-func newK8sCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "k8s",
-		Short: "Kubernetes deploy-target helpers",
+// normalizeRepoURL expands the idiomatic `owner/name` shorthand to a full GitHub
+// https URL (the platform build muscle clones https), and leaves an explicit URL
+// (http/https/git/ssh scheme, or a scp-style git@host:owner/name) untouched. Only
+// a bare single-segment `owner/name` — two path parts, no scheme, no host — is
+// expanded; anything else is the caller's explicit choice and passes through.
+func normalizeRepoURL(repo string) string {
+	r := strings.TrimSpace(repo)
+	if r == "" {
+		return r
 	}
-	target := &cobra.Command{
-		Use:   "target",
-		Short: "Show the org's current resolved deploy target (cluster + namespaces)",
-		Args:  cobra.NoArgs,
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			e := envOf()
-			org, err := e.requireOrg()
-			if err != nil {
-				return err
-			}
-			t, err := e.platform(gf).Target(cmd.Context(), org)
-			if err != nil {
-				return err
-			}
-			return e.emit(t, func(w io.Writer) { printTarget(w, t) })
-		},
+	// Already a URL or scp-style remote → leave as-is.
+	if strings.Contains(r, "://") || strings.Contains(r, "@") {
+		return r
 	}
-	cmd.AddCommand(target)
-	return cmd
+	// Bare owner/name (exactly two non-empty segments, no host dot in the first).
+	parts := strings.Split(strings.Trim(r, "/"), "/")
+	if len(parts) == 2 && parts[0] != "" && parts[1] != "" && !strings.Contains(parts[0], ".") {
+		return "https://github.com/" + parts[0] + "/" + parts[1]
+	}
+	return r
 }

cli/commands_test.go

@@ -8,6 +8,24 @@ import (
 	"testing"
 )
 
+func TestNormalizeRepoURL(t *testing.T) {
+	cases := map[string]string{
+		"luxfi/wallet":                    "https://github.com/luxfi/wallet",
+		"hanzoai/cloud":                   "https://github.com/hanzoai/cloud",
+		"https://github.com/luxfi/wallet": "https://github.com/luxfi/wallet", // full URL untouched
+		"git@github.com:luxfi/wallet.git": "git@github.com:luxfi/wallet.git", // scp-style untouched
+		"https://gitlab.com/org/repo":     "https://gitlab.com/org/repo",     // non-github URL untouched
+		"owner/name/extra":                "owner/name/extra",                // not a bare owner/name
+		"single":                          "single",                          // not two segments
+		"":                                "",                                // empty
+	}
+	for in, want := range cases {
+		if got := normalizeRepoURL(in); got != want {
+			t.Errorf("normalizeRepoURL(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
 // withPlatform points the CLI at an httptest platform via env (HANZO_PLATFORM_URL
 // + HANZO_PLATFORM_TOKEN), the same resolution path the real binary uses.
 func withPlatform(t *testing.T, h http.HandlerFunc) string {
@@ -20,11 +38,15 @@ func withPlatform(t *testing.T, h http.HandlerFunc) string {
 	return srv.URL
 }
 
+// apps list hits the LIVE board path /v1/paas/apps and renders the fleet table.
 func TestAppsListCommandTable(t *testing.T) {
-	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) {
+	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/paas/apps" {
+			t.Errorf("apps path = %s, want /v1/paas/apps", r.URL.Path)
+		}
 		_ = json.NewEncoder(w).Encode(AppsList{
 			Apps: []AppView{
-				{Org: "hanzoai", App: "iam", Env: "main", DeclaredTag: strptr("v1.2.3"), RunningTag: strptr("v1.2.3"), Health: strptr("green"), Drift: json.RawMessage(`{"severity":"ok"}`)},
+				{Org: "hanzoai", App: "iam", Env: "main", DeclaredTag: "v1.2.3", RunningTag: "v1.2.3", Health: "green", Drift: json.RawMessage(`{"severity":"ok"}`)},
 			},
 			Summary: struct {
 				Total   int            `json:"total"`
@@ -43,6 +65,20 @@ func TestAppsListCommandTable(t *testing.T) {
 	}
 }
 
+// apps list honors --env/--health/--drift as server query params (the board filters).
+func TestAppsListCommandFilters(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
+		q := r.URL.Query()
+		if q.Get("env") != "main" || q.Get("health") != "red" || q.Get("drift") != "1" {
+			t.Errorf("filters not forwarded: %s", r.URL.RawQuery)
+		}
+		_ = json.NewEncoder(w).Encode(AppsList{})
+	})
+	if _, err := runRoot(t, "", "apps", "list", "--env", "main", "--health", "red", "--drift"); err != nil {
+		t.Fatalf("apps list filters: %v", err)
+	}
+}
+
 func TestAppsListCommandJSON(t *testing.T) {
 	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) {
 		_ = json.NewEncoder(w).Encode(AppsList{Apps: []AppView{{Org: "hanzoai", App: "iam", Env: "main"}}})
@@ -60,69 +96,112 @@ func TestAppsListCommandJSON(t *testing.T) {
 	}
 }
 
+// apps get hits /v1/paas/apps/{app}.
+func TestAppsGetCommand(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/paas/apps/iam" {
+			t.Errorf("path = %s, want /v1/paas/apps/iam", r.URL.Path)
+		}
+		_ = json.NewEncoder(w).Encode(AppView{ID: "hanzoai/iam/main", Org: "hanzoai", App: "iam", Env: "main", DeclaredTag: "v1.2.3", Health: "green", Phase: "Running"})
+	})
+	out, err := runRoot(t, "", "apps", "get", "iam")
+	if err != nil {
+		t.Fatalf("apps get: %v", err)
+	}
+	for _, want := range []string{"hanzoai/iam/main", "Running", "v1.2.3"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("apps get missing %q in:\n%s", want, out)
+		}
+	}
+}
+
+// deploy hits /v1/paas/apps/{app}/deploy — a rolling restart, org from identity.
 func TestDeployCommand(t *testing.T) {
 	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/v1/org/acme/project/p1/env/e1/container/app-x/redeploy" {
-			t.Errorf("redeploy path = %s", r.URL.Path)
+		if r.URL.Path != "/v1/paas/apps/app-x/deploy" || r.URL.Query().Get("env") != "main" {
+			t.Errorf("redeploy request = %s?%s", r.URL.Path, r.URL.RawQuery)
 		}
-		_ = json.NewEncoder(w).Encode(map[string]bool{"ok": true})
+		w.WriteHeader(202)
+		_ = json.NewEncoder(w).Encode(DeployResult{OK: true, App: "app-x", Namespace: "hanzo", Env: "main", RestartedAt: "2026-07-18T12:00:00Z"})
 	})
-	out, err := runRoot(t, "", "deploy", "app-x", "--org", "acme", "--project", "p1", "--env", "e1")
+	out, err := runRoot(t, "", "deploy", "app-x", "--env", "main")
 	if err != nil {
 		t.Fatalf("deploy: %v", err)
 	}
-	if !strings.Contains(out, "redeployed app-x") {
+	if !strings.Contains(out, "restarted app-x") || !strings.Contains(out, "namespace=hanzo") {
 		t.Fatalf("deploy output: %q", out)
 	}
 }
 
-func TestDeployRequiresProjectEnv(t *testing.T) {
-	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(200) })
-	if _, err := runRoot(t, "", "deploy", "app-x", "--org", "acme"); err == nil {
-		t.Fatalf("deploy must require --project/--env")
+// deploy REQUIRES --env — a bare deploy errors CLI-side, never silently prod.
+func TestDeployRequiresEnv(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) {
+		t.Error("deploy without --env must not reach the server")
+		w.WriteHeader(202)
+	})
+	if _, err := runRoot(t, "", "deploy", "app-x"); err == nil {
+		t.Fatalf("deploy must require --env")
 	}
 }
 
-func TestDeployRequiresOrg(t *testing.T) {
-	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(200) })
-	if _, err := runRoot(t, "", "deploy", "app-x", "--project", "p1", "--env", "e1"); err == nil {
-		t.Fatalf("deploy must require an org")
+// deploy --env selects the lifecycle namespace via the ?env query param.
+func TestDeployCommandEnv(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/paas/apps/chat/deploy" || r.URL.Query().Get("env") != "test" {
+			t.Errorf("deploy env request = %s?%s", r.URL.Path, r.URL.RawQuery)
+		}
+		w.WriteHeader(202)
+		_ = json.NewEncoder(w).Encode(DeployResult{OK: true, App: "chat", Namespace: "hanzo-testnet", Env: "test", RestartedAt: "2026-07-18T12:00:00Z"})
+	})
+	if _, err := runRoot(t, "", "deploy", "chat", "--env", "test"); err != nil {
+		t.Fatalf("deploy --env: %v", err)
 	}
 }
 
+// A non-ok deploy response is surfaced as an error.
+func TestDeployNotOK(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) {
+		_ = json.NewEncoder(w).Encode(DeployResult{OK: false})
+	})
+	if _, err := runRoot(t, "", "deploy", "app-x", "--env", "main"); err == nil {
+		t.Fatalf("deploy must error when the server does not report ok")
+	}
+}
+
+// clusters list hits the LIVE /v1/clusters (org from identity, not the path).
 func TestClustersListCommand(t *testing.T) {
 	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/v1/org/acme/cluster" {
-			t.Errorf("path = %s", r.URL.Path)
+		if r.URL.Path != "/v1/clusters" {
+			t.Errorf("path = %s, want /v1/clusters", r.URL.Path)
 		}
 		_ = json.NewEncoder(w).Encode(map[string]any{"clusters": []Cluster{
-			{DoksClusterID: "c1", Name: "hanzo-acme", Region: "sfo3", Status: "running", Phase: "ready", Active: true, OperatorInstalled: true, BaselineInstalled: true},
+			{DoksClusterID: "c1", Name: "hanzo-acme", Region: "sfo3", Status: "running", Kind: "managed", NodeCount: 3, NodeSize: "s-2vcpu-4gb", NvidiaGPU: 2},
 		}})
 	})
-	out, err := runRoot(t, "", "clusters", "list", "--org", "acme")
+	out, err := runRoot(t, "", "clusters", "list")
 	if err != nil {
 		t.Fatalf("clusters list: %v", err)
 	}
-	for _, want := range []string{"NAME", "hanzo-acme", "c1", "ready", "yes"} {
+	for _, want := range []string{"NAME", "hanzo-acme", "c1", "managed", "2 nvidia"} {
 		if !strings.Contains(out, want) {
 			t.Fatalf("clusters list missing %q in:\n%s", want, out)
 		}
 	}
 }
 
-func TestK8sTargetCommand(t *testing.T) {
-	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/v1/org/acme/cluster/select" {
-			t.Errorf("path = %s", r.URL.Path)
-		}
-		_ = json.NewEncoder(w).Encode(map[string]any{"target": Target{Cluster: "hanzo-k8s", Dedicated: false, Namespaces: map[string]string{"hanzo": "main"}}})
+// clusters get filters the live list client-side by id or name.
+func TestClustersGetCommand(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) {
+		_ = json.NewEncoder(w).Encode(map[string]any{"clusters": []Cluster{
+			{DoksClusterID: "c1", Name: "hanzo-acme", Region: "sfo3", Status: "running", Kind: "byo", NodeCount: 1},
+		}})
 	})
-	out, err := runRoot(t, "", "k8s", "target", "--org", "acme")
+	out, err := runRoot(t, "", "clusters", "get", "c1")
 	if err != nil {
-		t.Fatalf("k8s target: %v", err)
+		t.Fatalf("clusters get: %v", err)
 	}
-	if !strings.Contains(out, "hanzo-k8s") || !strings.Contains(out, "shared") {
-		t.Fatalf("k8s target output: %q", out)
+	if !strings.Contains(out, "hanzo-acme") || !strings.Contains(out, "byo") {
+		t.Fatalf("clusters get output: %q", out)
 	}
 }
 
@@ -136,7 +215,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" {
@@ -167,5 +246,3 @@ func TestConfigSetGetCommand(t *testing.T) {
 		t.Fatalf("config get = %q", out)
 	}
 }
-
-func strptr(s string) *string { return &s }

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

@@ -12,11 +12,13 @@ import (
 	"time"
 )
 
-// Platform is a thin client over the platform.hanzo.ai /v1 control plane. That
-// surface is machine-to-machine (service-token, "No OIDC" — it cannot validate
-// IAM user tokens), so the token here is the platform service token, resolved
-// from flag/env/credential store by the caller; the build endpoint takes its
-// own token per call.
+// Platform is a thin client over the LIVE Hanzo Cloud control plane
+// (platform.hanzo.ai / api.hanzo.ai → svc `cloud`, the Go binary). Every route it
+// calls is served by that one binary and authorized off ONE IAM identity: after
+// `hanzo login` the CLI sends the IAM access token as the bearer, and the cloud's
+// identity middleware (SanitizeIdentity) validates the JWT and org-scopes the
+// caller — no separate platform/service token. A purpose-minted machine token
+// still works (flag > env > credential store > IAM login) for automation.
 type Platform struct {
 	baseURL string
 	token   string
@@ -45,8 +47,8 @@ func (e *apiError) Error() string {
 		msg = http.StatusText(e.status)
 	}
 	hint := ""
-	if e.status == http.StatusUnauthorized {
-		hint = " (set the platform service token: --platform-token, HANZO_PLATFORM_TOKEN, or `hanzo login --platform-token`)"
+	if e.status == http.StatusUnauthorized || e.status == http.StatusForbidden {
+		hint = " (run `hanzo login` — your IAM identity authorizes the platform; admin ops need an org-admin or superadmin identity)"
 	}
 	return fmt.Sprintf("platform %s: HTTP %d: %s%s", e.path, e.status, msg, hint)
 }
@@ -55,7 +57,7 @@ func (e *apiError) Error() string {
 // into out (when non-nil) and mapping a non-2xx into an *apiError.
 func (p *Platform) do(ctx context.Context, method, path, token string, body, out any) error {
 	if token == "" {
-		return fmt.Errorf("no platform token: pass --platform-token, set HANZO_PLATFORM_TOKEN, or run `hanzo login --platform-token <tok>`")
+		return fmt.Errorf("not authenticated: run `hanzo login` (an IAM login now authorizes the platform; a --platform-token / HANZO_PLATFORM_TOKEN still works for machine automation)")
 	}
 	var rdr io.Reader
 	if body != nil {
@@ -94,8 +96,8 @@ func (p *Platform) do(ctx context.Context, method, path, token string, body, out
 	return nil
 }
 
-// serverMessage pulls the `{ "message": … }` field platform errors use, falling
-// back to the raw (truncated) body.
+// serverMessage pulls the `{ "message": … }` / `{ "error": … }` field the cloud's
+// errors use, falling back to the raw (truncated) body.
 func serverMessage(raw []byte) string {
 	var e struct {
 		Message string `json:"message"`
@@ -117,33 +119,35 @@ func serverMessage(raw []byte) string {
 }
 
 // ---------------------------------------------------------------------------
-// Apps board — GET /v1/apps, GET /v1/apps/{id}, POST /v1/apps/sync.
+// Apps board — GET /v1/paas/apps, GET /v1/paas/apps/{app}. The live Go cloud's
+// fleet drift board (clients/paas): the operator App CRs across the platform
+// namespaces, declared/running/latest tags + health + the drift verdict. It is
+// org-confined server-side (a SuperAdmin sees the fleet; an OrgAdmin only its own
+// org), so the CLI sends NO org filter — identity scopes the view.
 // ---------------------------------------------------------------------------
 
-// AppView mirrors the platform apps-lifecycle DTO. Nullable columns are *string
-// so JSON null round-trips; Drift is kept raw so --json is byte-faithful and
-// the drift schema can evolve without a client bump.
+// AppView mirrors clients/paas.AppView (the LIVE board DTO). Tags/health are plain
+// strings ("" == unknown, rendered "-"); Drift is kept raw so --json is
+// byte-faithful and the drift schema can evolve without a client bump.
 type AppView struct {
-	ID            string          `json:"id"`
-	Org           string          `json:"org"`
-	App           string          `json:"app"`
-	Env           string          `json:"env"`
-	Repo          string          `json:"repo"`
-	Registry      string          `json:"registry"`
-	DeclaredTag   *string         `json:"declaredTag"`
-	RunningTag    *string         `json:"runningTag"`
-	LatestTag     *string         `json:"latestTag"`
-	ReleaseURL    *string         `json:"releaseUrl"`
-	ReleaseAssets int             `json:"releaseAssets"`
-	Health        *string         `json:"health"`
-	Cluster       *string         `json:"cluster"`
-	Namespace     *string         `json:"namespace"`
-	LastObserved  *string         `json:"lastObserved"`
-	UpdatedAt     string          `json:"updatedAt"`
-	Drift         json.RawMessage `json:"drift"`
+	ID          string          `json:"id"`  // <org>/<app>/<env>, e.g. hanzoai/iam/main
+	Org         string          `json:"org"` // image namespace, e.g. hanzoai
+	App         string          `json:"app"`
+	Env         string          `json:"env"`
+	Repo        string          `json:"repo"`
+	Registry    string          `json:"registry"`
+	DeclaredTag string          `json:"declaredTag"`
+	RunningTag  string          `json:"runningTag"`
+	LatestTag   string          `json:"latestTag"`
+	Health      string          `json:"health"`
+	Phase       string          `json:"phase"`
+	Cluster     string          `json:"cluster"`
+	Namespace   string          `json:"namespace"`
+	Endpoints   []string        `json:"endpoints"`
+	Drift       json.RawMessage `json:"drift"`
 }
 
-// AppsList is the /v1/apps envelope: ordered rows + a drift summary.
+// AppsList is the /v1/paas/apps envelope: ordered rows + a drift summary.
 type AppsList struct {
 	Apps    []AppView `json:"apps"`
 	Summary struct {
@@ -152,9 +156,10 @@ type AppsList struct {
 	} `json:"summary"`
 }
 
-// AppsQuery are the optional /v1/apps filters.
+// AppsQuery are the optional /v1/paas/apps filters (server-honored). Env/Health/
+// Drift narrow the board; there is deliberately no org filter — the board is
+// confined to the caller's org by the validated identity, never a client value.
 type AppsQuery struct {
-	Org    string
 	Env    string
 	Health string
 	Drift  bool
@@ -162,9 +167,6 @@ type AppsQuery struct {
 
 func (p *Platform) Apps(ctx context.Context, q AppsQuery) (*AppsList, error) {
 	v := url.Values{}
-	if q.Org != "" {
-		v.Set("org", q.Org)
-	}
 	if q.Env != "" {
 		v.Set("env", q.Env)
 	}
@@ -174,7 +176,7 @@ func (p *Platform) Apps(ctx context.Context, q AppsQuery) (*AppsList, error) {
 	if q.Drift {
 		v.Set("drift", "1")
 	}
-	path := "/v1/apps"
+	path := "/v1/paas/apps"
 	if len(v) > 0 {
 		path += "?" + v.Encode()
 	}
@@ -182,17 +184,11 @@ func (p *Platform) Apps(ctx context.Context, q AppsQuery) (*AppsList, error) {
 	return out, p.do(ctx, http.MethodGet, path, p.token, nil, out)
 }
 
-func (p *Platform) App(ctx context.Context, id, org string) (*AppView, error) {
-	path := "/v1/apps/" + id
-	if org != "" {
-		path += "?org=" + url.QueryEscape(org)
-	}
+// App gets one app row by its <app> CR name (production by default; the server
+// scans the caller's authorized namespaces main→test→dev).
+func (p *Platform) App(ctx context.Context, app string) (*AppView, error) {
 	out := &AppView{}
-	return out, p.do(ctx, http.MethodGet, path, p.token, nil, out)
-}
-
-func (p *Platform) SyncApps(ctx context.Context) error {
-	return p.do(ctx, http.MethodPost, "/v1/apps/sync", p.token, nil, nil)
+	return out, p.do(ctx, http.MethodGet, "/v1/paas/apps/"+url.PathEscape(app), p.token, nil, out)
 }
 
 // driftSeverity extracts the severity string from the raw drift object.
@@ -207,110 +203,92 @@ func driftSeverity(raw json.RawMessage) string {
 }
 
 // ---------------------------------------------------------------------------
-// Dedicated clusters — /v1/org/{org}/cluster[ /select | /{id}/install-baseline ].
+// Clusters — GET /v1/clusters. The live Go cloud's compute fleet (clients/visor):
+// Visor-managed node pools + the org's BYO clusters, tenant-scoped server-side by
+// the validated org (?owner is the caller's IAM org). No org in the path.
 // ---------------------------------------------------------------------------
 
-// Cluster mirrors a doks_cluster record. `status` is DigitalOcean state; `phase`
-// is the platform provisioning lifecycle — orthogonal (a DO-running cluster is
-// not a usable target until phase=ready).
+// NodePool mirrors clients/visor.nodePoolView.
+type NodePool struct {
+	PoolID    string `json:"poolId"`
+	Name      string `json:"name"`
+	Size      string `json:"size"`
+	Count     int    `json:"count"`
+	MinNodes  int    `json:"minNodes"`
+	MaxNodes  int    `json:"maxNodes"`
+	AutoScale bool   `json:"autoScale"`
+}
+
+// Cluster mirrors clients/visor.clusterView — the LIVE cluster DTO. `kind` is
+// "managed" (Visor-provisioned) or "byo" (attached kubeconfig).
 type Cluster struct {
-	DoksClusterID     string          `json:"doksClusterId"`
-	Name              string          `json:"name"`
-	DoClusterID       *string         `json:"doClusterId"`
-	Region            string          `json:"region"`
-	Status            string          `json:"status"`
-	Endpoint          *string         `json:"endpoint"`
-	K8sVersion        *string         `json:"k8sVersion"`
-	HA                bool            `json:"ha"`
-	Phase             string          `json:"phase"`
-	OperatorInstalled bool            `json:"operatorInstalled"`
-	BaselineInstalled bool            `json:"baselineInstalled"`
-	Active            bool            `json:"active"`
-	BaselineError     *string         `json:"baselineError"`
-	OrganizationID    string          `json:"organizationId"`
-	CreatedAt         string          `json:"createdAt"`
-	Tags              []string        `json:"tags"`
-	MaintenancePolicy json.RawMessage `json:"maintenancePolicy,omitempty"`
+	DoksClusterID string     `json:"doksClusterId"`
+	DoClusterID   string     `json:"doClusterId"`
+	Name          string     `json:"name"`
+	Region        string     `json:"region"`
+	Status        string     `json:"status"`
+	NodePools     []NodePool `json:"nodePools"`
+	NodeSize      string     `json:"nodeSize"`
+	NodeCount     int        `json:"nodeCount"`
+	CreatedAt     string     `json:"createdAt"`
+	Kind          string     `json:"kind"`
+	NvidiaGPU     int        `json:"nvidiaGpu"`
+	AmdGPU        int        `json:"amdGpu"`
 }
 
-// ProvisionReq is the dedicated-cluster provisioning body (org forced by path).
-type ProvisionReq struct {
-	Region    string `json:"region,omitempty"`
-	HA        bool   `json:"ha,omitempty"`
-	NodeSize  string `json:"nodeSize,omitempty"`
-	NodeCount int    `json:"nodeCount,omitempty"`
+// ID is the stable cluster identifier for display/lookup: the DOKS id when managed,
+// else the name (a BYO cluster keys on its attached name).
+func (c Cluster) ID() string {
+	if c.DoksClusterID != "" {
+		return c.DoksClusterID
+	}
+	return c.Name
 }
 
-// Target is the redacted ClusterTargetView — the kubeconfig is never present.
-type Target struct {
-	Cluster    string            `json:"cluster"`
-	Namespaces map[string]string `json:"namespaces"`
-	Dedicated  bool              `json:"dedicated"`
-}
-
-func (p *Platform) Clusters(ctx context.Context, org string) ([]Cluster, error) {
+func (p *Platform) Clusters(ctx context.Context) ([]Cluster, error) {
 	var out struct {
 		Clusters []Cluster `json:"clusters"`
 	}
-	err := p.do(ctx, http.MethodGet, "/v1/org/"+url.PathEscape(org)+"/cluster", p.token, nil, &out)
+	err := p.do(ctx, http.MethodGet, "/v1/clusters", p.token, nil, &out)
 	return out.Clusters, err
 }
 
-func (p *Platform) ProvisionCluster(ctx context.Context, org string, req ProvisionReq) (*Cluster, error) {
-	var out struct {
-		Cluster Cluster `json:"cluster"`
-	}
-	err := p.do(ctx, http.MethodPost, "/v1/org/"+url.PathEscape(org)+"/cluster", p.token, req, &out)
-	return &out.Cluster, err
-}
-
-func (p *Platform) Target(ctx context.Context, org string) (*Target, error) {
-	var out struct {
-		Target Target `json:"target"`
-	}
-	err := p.do(ctx, http.MethodGet, "/v1/org/"+url.PathEscape(org)+"/cluster/select", p.token, nil, &out)
-	return &out.Target, err
-}
-
-// SelectTarget activates a dedicated cluster as the org's deploy target, or
-// reverts to the shared cluster when clusterID is nil.
-func (p *Platform) SelectTarget(ctx context.Context, org string, clusterID *string) (*Target, error) {
-	var out struct {
-		Target Target `json:"target"`
-	}
-	body := map[string]any{"doksClusterId": clusterID}
-	err := p.do(ctx, http.MethodPost, "/v1/org/"+url.PathEscape(org)+"/cluster/select", p.token, body, &out)
-	return &out.Target, err
-}
-
-func (p *Platform) InstallBaseline(ctx context.Context, org, clusterID string) error {
-	path := "/v1/org/" + url.PathEscape(org) + "/cluster/" + url.PathEscape(clusterID) + "/install-baseline"
-	return p.do(ctx, http.MethodPost, path, p.token, nil, nil)
-}
-
 // ---------------------------------------------------------------------------
-// Deploy — POST …/container/{id}/redeploy (rolling restart, zero-downtime).
+// Deploy — POST /v1/paas/apps/{app}/deploy: a zero-downtime ROLLING RESTART of the
+// app's Deployment (re-pulls the declared image, recreates pods). Org-confined
+// server-side; an optional env selects the lifecycle namespace (main|test|dev).
 // ---------------------------------------------------------------------------
 
-// Redeploy triggers a rolling restart of the container's k8s Deployment. The
-// coordinates are exact (the platform validates org+project+env+container scope).
-func (p *Platform) Redeploy(ctx context.Context, org, project, env, container string) error {
-	path := fmt.Sprintf("/v1/org/%s/project/%s/env/%s/container/%s/redeploy",
-		url.PathEscape(org), url.PathEscape(project), url.PathEscape(env), url.PathEscape(container))
-	var out struct {
-		OK bool `json:"ok"`
+// Redeploy triggers a rolling restart of the named app. env is optional
+// (main|test|dev); empty targets production (the first match, main→test→dev).
+func (p *Platform) Redeploy(ctx context.Context, app, env string) (*DeployResult, error) {
+	path := "/v1/paas/apps/" + url.PathEscape(app) + "/deploy"
+	if env != "" {
+		path += "?env=" + url.QueryEscape(env)
 	}
-	if err := p.do(ctx, http.MethodPost, path, p.token, nil, &out); err != nil {
-		return err
+	out := &DeployResult{}
+	if err := p.do(ctx, http.MethodPost, path, p.token, nil, out); err != nil {
+		return nil, err
 	}
 	if !out.OK {
-		return fmt.Errorf("redeploy did not report ok")
+		return nil, fmt.Errorf("redeploy did not report ok")
 	}
-	return nil
+	return out, nil
+}
+
+// DeployResult is the /deploy acceptance (202): the restarted app + its namespace.
+type DeployResult struct {
+	OK          bool   `json:"ok"`
+	App         string `json:"app"`
+	Namespace   string `json:"namespace"`
+	Env         string `json:"env"`
+	RestartedAt string `json:"restartedAt"`
 }
 
 // ---------------------------------------------------------------------------
-// Build — POST /v1/arcd/enqueue (platform-native CI, no GitHub builders).
+// Build — POST /v1/runner (platform-native CI, no GitHub builders). Authorized off
+// the IAM login exactly like the surfaces above (or a dedicated build token for
+// machine automation). Unchanged wire contract.
 // ---------------------------------------------------------------------------
 
 // BuildReq is the direct-enqueue body. Repo/SHA/Image are required.
@@ -337,12 +315,12 @@ type BuildJob struct {
 	Target     string `json:"target"`
 }
 
-// EnqueueBuild enqueues a native build. It authenticates with the dedicated
-// build-callback token, not the service token.
+// EnqueueBuild enqueues a native build. buildToken is resolved by the caller (IAM
+// login is the final fallback; a dedicated build token wins when present).
 func (p *Platform) EnqueueBuild(ctx context.Context, req BuildReq, buildToken string) (*BuildJob, error) {
 	if buildToken == "" {
-		return nil, fmt.Errorf("no build token: set HANZO_BUILD_TOKEN / PLATFORM_BUILD_CALLBACK_TOKEN or `hanzo login --build-token <tok>`")
+		return nil, fmt.Errorf("not authenticated: run `hanzo login` (an IAM login now authorizes builds; HANZO_BUILD_TOKEN / --build-token still works for machine automation)")
 	}
 	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

@@ -18,17 +18,22 @@ func platformStub(t *testing.T, token string, h http.HandlerFunc) (*Platform, fu
 	return newPlatform(srv.URL, token), srv.Close
 }
 
+// Apps hits the LIVE board /v1/paas/apps with the IAM bearer; it sends NO org
+// filter (the board is org-confined server-side by the validated identity).
 func TestPlatformAuthHeaderAndApps(t *testing.T) {
 	p, done := platformStub(t, "svc-tok", func(w http.ResponseWriter, r *http.Request) {
 		if got := r.Header.Get("Authorization"); got != "Bearer svc-tok" {
 			t.Errorf("auth header = %q", got)
 		}
-		if r.URL.Path != "/v1/apps" {
-			t.Errorf("path = %s", r.URL.Path)
+		if r.URL.Path != "/v1/paas/apps" {
+			t.Errorf("path = %s, want /v1/paas/apps", r.URL.Path)
 		}
 		if r.URL.Query().Get("env") != "main" || r.URL.Query().Get("drift") != "1" {
 			t.Errorf("query = %s", r.URL.RawQuery)
 		}
+		if r.URL.Query().Has("org") {
+			t.Errorf("client must NOT send an org filter (identity confines the board): %s", r.URL.RawQuery)
+		}
 		_ = json.NewEncoder(w).Encode(AppsList{
 			Apps: []AppView{{ID: "hanzoai/iam/main", Org: "hanzoai", App: "iam", Env: "main", Drift: json.RawMessage(`{"severity":"red"}`)}},
 		})
@@ -47,126 +52,75 @@ func TestPlatformAuthHeaderAndApps(t *testing.T) {
 	}
 }
 
+// App hits /v1/paas/apps/{app}; no org query (identity scopes it).
 func TestPlatformApp(t *testing.T) {
 	p, done := platformStub(t, "t", func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/v1/apps/hanzoai/iam/main" {
-			t.Errorf("path = %s", r.URL.Path)
+		if r.URL.Path != "/v1/paas/apps/iam" {
+			t.Errorf("path = %s, want /v1/paas/apps/iam", r.URL.Path)
 		}
-		if r.URL.Query().Get("org") != "hanzoai" {
-			t.Errorf("org query = %s", r.URL.RawQuery)
+		if r.URL.RawQuery != "" {
+			t.Errorf("app get must carry no query, got %s", r.URL.RawQuery)
 		}
-		_ = json.NewEncoder(w).Encode(AppView{ID: "hanzoai/iam/main", App: "iam"})
+		_ = json.NewEncoder(w).Encode(AppView{ID: "hanzoai/iam/main", App: "iam", Phase: "Running"})
 	})
 	defer done()
-	a, err := p.App(context.Background(), "hanzoai/iam/main", "hanzoai")
+	a, err := p.App(context.Background(), "iam")
 	if err != nil || a.App != "iam" {
 		t.Fatalf("App: %v %+v", err, a)
 	}
 }
 
-func TestPlatformSyncApps(t *testing.T) {
+// Clusters hits the LIVE /v1/clusters (org from identity, not the path).
+func TestPlatformClusters(t *testing.T) {
 	p, done := platformStub(t, "t", func(w http.ResponseWriter, r *http.Request) {
-		if r.Method != http.MethodPost || r.URL.Path != "/v1/apps/sync" {
-			t.Errorf("sync = %s %s", r.Method, r.URL.Path)
-		}
-		w.WriteHeader(200)
-	})
-	defer done()
-	if err := p.SyncApps(context.Background()); err != nil {
-		t.Fatalf("SyncApps: %v", err)
-	}
-}
-
-func TestPlatformClustersAndProvision(t *testing.T) {
-	p, done := platformStub(t, "t", func(w http.ResponseWriter, r *http.Request) {
-		switch {
-		case r.Method == http.MethodGet && r.URL.Path == "/v1/org/acme/cluster":
-			_ = json.NewEncoder(w).Encode(map[string]any{"clusters": []Cluster{{DoksClusterID: "c1", Name: "hanzo-acme", Region: "sfo3", Status: "running", Phase: "ready", Active: true}}})
-		case r.Method == http.MethodPost && r.URL.Path == "/v1/org/acme/cluster":
-			body, _ := io.ReadAll(r.Body)
-			var req ProvisionReq
-			_ = json.Unmarshal(body, &req)
-			if req.Region != "sfo3" || !req.HA {
-				t.Errorf("provision body = %+v", req)
-			}
-			w.WriteHeader(201)
-			_ = json.NewEncoder(w).Encode(map[string]any{"cluster": Cluster{DoksClusterID: "c2", Name: "new", Phase: "requested"}})
-		default:
-			t.Errorf("unexpected %s %s", r.Method, r.URL.Path)
+		if r.Method != http.MethodGet || r.URL.Path != "/v1/clusters" {
+			t.Errorf("clusters = %s %s, want GET /v1/clusters", r.Method, r.URL.Path)
 		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"clusters": []Cluster{
+			{DoksClusterID: "c1", Name: "hanzo-acme", Region: "sfo3", Status: "running", Kind: "managed", NodeCount: 3},
+		}})
 	})
 	defer done()
 
-	cs, err := p.Clusters(context.Background(), "acme")
-	if err != nil || len(cs) != 1 || cs[0].DoksClusterID != "c1" {
+	cs, err := p.Clusters(context.Background())
+	if err != nil || len(cs) != 1 || cs[0].ID() != "c1" || cs[0].Kind != "managed" {
 		t.Fatalf("Clusters: %v %+v", err, cs)
 	}
-	c, err := p.ProvisionCluster(context.Background(), "acme", ProvisionReq{Region: "sfo3", HA: true})
-	if err != nil || c.DoksClusterID != "c2" {
-		t.Fatalf("ProvisionCluster: %v %+v", err, c)
-	}
 }
 
-func TestPlatformTargetAndSelect(t *testing.T) {
-	p, done := platformStub(t, "t", func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/v1/org/acme/cluster/select" {
-			t.Errorf("path = %s", r.URL.Path)
-		}
-		if r.Method == http.MethodPost {
-			body, _ := io.ReadAll(r.Body)
-			var m map[string]any
-			_ = json.Unmarshal(body, &m)
-			if m["doksClusterId"] != "c1" {
-				t.Errorf("select body = %v", m)
-			}
-		}
-		_ = json.NewEncoder(w).Encode(map[string]any{"target": Target{Cluster: "hanzo-acme", Dedicated: true, Namespaces: map[string]string{"acme": "main"}}})
-	})
-	defer done()
-
-	tg, err := p.Target(context.Background(), "acme")
-	if err != nil || tg.Cluster != "hanzo-acme" || !tg.Dedicated {
-		t.Fatalf("Target: %v %+v", err, tg)
-	}
-	id := "c1"
-	if _, err := p.SelectTarget(context.Background(), "acme", &id); err != nil {
-		t.Fatalf("SelectTarget: %v", err)
-	}
-}
-
-func TestPlatformInstallBaseline(t *testing.T) {
-	p, done := platformStub(t, "t", func(w http.ResponseWriter, r *http.Request) {
-		if r.Method != http.MethodPost || r.URL.Path != "/v1/org/acme/cluster/c1/install-baseline" {
-			t.Errorf("install-baseline = %s %s", r.Method, r.URL.Path)
-		}
-		w.WriteHeader(200)
-	})
-	defer done()
-	if err := p.InstallBaseline(context.Background(), "acme", "c1"); err != nil {
-		t.Fatalf("InstallBaseline: %v", err)
+// A BYO cluster with no DOKS id keys on its name via ID().
+func TestClusterIDFallsBackToName(t *testing.T) {
+	c := Cluster{Name: "byo-1", Kind: "byo"}
+	if c.ID() != "byo-1" {
+		t.Fatalf("ID() = %q, want byo-1", c.ID())
 	}
 }
 
+// Redeploy hits /v1/paas/apps/{app}/deploy (rolling restart), org from identity.
 func TestPlatformRedeploy(t *testing.T) {
 	p, done := platformStub(t, "t", func(w http.ResponseWriter, r *http.Request) {
-		want := "/v1/org/acme/project/p1/env/e1/container/app-x/redeploy"
-		if r.Method != http.MethodPost || r.URL.Path != want {
-			t.Errorf("redeploy path = %s %s", r.Method, r.URL.Path)
+		if r.Method != http.MethodPost || r.URL.Path != "/v1/paas/apps/app-x/deploy" {
+			t.Errorf("redeploy = %s %s, want POST /v1/paas/apps/app-x/deploy", r.Method, r.URL.Path)
 		}
-		_ = json.NewEncoder(w).Encode(map[string]bool{"ok": true})
+		if r.URL.Query().Get("env") != "test" {
+			t.Errorf("env query = %s", r.URL.RawQuery)
+		}
+		w.WriteHeader(202)
+		_ = json.NewEncoder(w).Encode(DeployResult{OK: true, App: "app-x", Namespace: "hanzo-testnet", Env: "test", RestartedAt: "2026-07-18T00:00:00Z"})
 	})
 	defer done()
-	if err := p.Redeploy(context.Background(), "acme", "p1", "e1", "app-x"); err != nil {
-		t.Fatalf("Redeploy: %v", err)
+	res, err := p.Redeploy(context.Background(), "app-x", "test")
+	if err != nil || res.Namespace != "hanzo-testnet" {
+		t.Fatalf("Redeploy: %v %+v", err, res)
 	}
 }
 
 func TestPlatformRedeployNotOK(t *testing.T) {
 	p, done := platformStub(t, "t", func(w http.ResponseWriter, _ *http.Request) {
-		_ = json.NewEncoder(w).Encode(map[string]bool{"ok": false})
+		_ = json.NewEncoder(w).Encode(DeployResult{OK: false})
 	})
 	defer done()
-	if err := p.Redeploy(context.Background(), "o", "p", "e", "c"); err == nil {
+	if _, err := p.Redeploy(context.Background(), "c", ""); err == nil {
 		t.Fatalf("expected error when ok=false")
 	}
 }
@@ -177,7 +131,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)
@@ -207,14 +161,16 @@ func TestPlatformError401Hint(t *testing.T) {
 	})
 	defer done()
 	_, err := p.Apps(context.Background(), AppsQuery{})
-	if err == nil || !strings.Contains(err.Error(), "HTTP 401") || !strings.Contains(err.Error(), "platform service token") {
-		t.Fatalf("401 error should carry a token hint, got %v", err)
+	if err == nil || !strings.Contains(err.Error(), "HTTP 401") || !strings.Contains(err.Error(), "hanzo login") {
+		t.Fatalf("401 error should point at `hanzo login`, got %v", err)
 	}
 }
 
 func TestPlatformNoTokenError(t *testing.T) {
 	p := newPlatform("https://platform.hanzo.ai", "")
-	if _, err := p.Apps(context.Background(), AppsQuery{}); err == nil || !strings.Contains(err.Error(), "no platform token") {
-		t.Fatalf("expected no-token error, got %v", err)
+	// After unify-infra, the "no credential" error points at `hanzo login` — the one
+	// identity that authorizes the platform — not a separate platform token.
+	if _, err := p.Apps(context.Background(), AppsQuery{}); err == nil || !strings.Contains(err.Error(), "hanzo login") {
+		t.Fatalf("expected a `hanzo login` hint, got %v", err)
 	}
 }

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/security.go

@@ -0,0 +1,259 @@
+package cli
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/hanzoai/cloud/clients/security/detect"
+	"github.com/spf13/cobra"
+)
+
+// `hanzo security scan` is the LOCAL guardrail-at-generation: it walks a path,
+// runs the SAME detect engine the /v1/security server surface uses (one engine,
+// two surfaces — see clients/security/detect), and exits non-zero when a finding
+// at or above the fail threshold is present. No server, no auth, no network — so
+// it drops straight into a pre-commit hook, a CI step, or an agent's shell the
+// moment code is written. It never prints a raw secret: findings carry the
+// engine's masked preview only.
+
+// skipDirs are never descended into — vendored / generated / VCS trees that
+// would drown real findings in noise (and, for node_modules, minified blobs
+// that trip entropy heuristics).
+var skipDirs = map[string]bool{
+	".git": true, "node_modules": true, "vendor": true, "dist": true,
+	"build": true, "out": true, ".vscode-test": true, "target": true,
+	".next": true, "__pycache__": true, ".venv": true, "venv": true,
+}
+
+// maxScanFileBytes caps a single file read; a source file over this is almost
+// certainly a data/blob artifact, not code a human wrote a secret into.
+const maxScanFileBytes = 2 << 20 // 2 MiB
+
+func newSecurityCmd(envOf func() *Env) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "security",
+		Short: "Code-security tools (local secret scanning)",
+		// No PersistentPreRunE override: the root's runs, resolving config/creds
+		// into env so envOf() (used for -o json) is non-nil. It is local-only —
+		// scan requires no login or network.
+	}
+
+	var failOn string
+	scan := &cobra.Command{
+		Use:   "scan [path ...]",
+		Short: "Scan files/directories for hardcoded secrets (default: current dir)",
+		Long: "Walk each path and report hardcoded secrets using the native Hanzo\n" +
+			"detection engine (the same one behind /v1/security). Exits non-zero when a\n" +
+			"finding at or above --fail-on is present, so it gates a pre-commit hook or CI\n" +
+			"step. Secrets are never printed — only a masked preview.",
+		// We print our own findings + a clean "N secrets" error; no cobra usage
+		// dump on a policy failure.
+		SilenceUsage:  true,
+		SilenceErrors: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			paths := args
+			if len(paths) == 0 {
+				paths = []string{"."}
+			}
+			floor := strings.ToLower(strings.TrimSpace(failOn))
+			if floor == "" {
+				floor = "low"
+			}
+			if floor != "none" && detect.SeverityRank(floor) == 0 {
+				return fmt.Errorf("invalid --fail-on %q (want critical|high|medium|low|none)", failOn)
+			}
+
+			findings, scanned, err := scanPaths(paths)
+			if err != nil {
+				return err
+			}
+
+			e := envOf()
+			result := scanResult{
+				FilesScanned: scanned,
+				Findings:     findings,
+				Summary:      tally(findings),
+			}
+			if err := e.emit(result, func(w io.Writer) { renderScan(w, result) }); err != nil {
+				return err
+			}
+
+			// Policy gate: fail when any finding is at/above the floor.
+			if floor != "none" {
+				bad := 0
+				for _, f := range findings {
+					if detect.SeverityRank(f.Severity) >= detect.SeverityRank(floor) {
+						bad++
+					}
+				}
+				if bad > 0 {
+					return fmt.Errorf("%d secret(s) at or above %q severity", bad, floor)
+				}
+			}
+			return nil
+		},
+	}
+	scan.Flags().StringVar(&failOn, "fail-on", "low",
+		"minimum severity that fails the command: critical|high|medium|low|none")
+
+	rules := &cobra.Command{
+		Use:   "rules",
+		Short: "List the detection rules the scanner applies",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			e := envOf()
+			rv := detect.Rules()
+			return e.emit(rv, func(w io.Writer) {
+				tw := newTab(w)
+				fmt.Fprintln(tw, "SEVERITY\tID\tNAME")
+				for _, r := range rv {
+					fmt.Fprintf(tw, "%s\t%s\t%s\n", r.Severity, r.ID, r.Name)
+				}
+				tw.Flush()
+				fmt.Fprintf(w, "\n%d rules\n", len(rv))
+			})
+		},
+	}
+
+	cmd.AddCommand(scan, rules)
+	return cmd
+}
+
+// scanFinding is a CLI finding: the engine finding with the file path it was
+// found in (the engine echoes the path it was handed, which is what we want).
+type scanResult struct {
+	FilesScanned int              `json:"filesScanned"`
+	Findings     []detect.Finding `json:"findings"`
+	Summary      scanSummary      `json:"summary"`
+}
+
+type scanSummary struct {
+	Total    int `json:"total"`
+	Critical int `json:"critical"`
+	High     int `json:"high"`
+	Medium   int `json:"medium"`
+	Low      int `json:"low"`
+}
+
+func tally(fs []detect.Finding) scanSummary {
+	var s scanSummary
+	for _, f := range fs {
+		s.Total++
+		switch f.Severity {
+		case detect.SeverityCritical:
+			s.Critical++
+		case detect.SeverityHigh:
+			s.High++
+		case detect.SeverityMedium:
+			s.Medium++
+		case detect.SeverityLow:
+			s.Low++
+		}
+	}
+	return s
+}
+
+// scanPaths walks each path and runs the engine over every readable text file,
+// returning findings sorted worst-first (by severity, then path, then line).
+func scanPaths(paths []string) ([]detect.Finding, int, error) {
+	var findings []detect.Finding
+	scanned := 0
+	for _, root := range paths {
+		info, err := os.Stat(root)
+		if err != nil {
+			return nil, 0, fmt.Errorf("stat %q: %w", root, err)
+		}
+		if !info.IsDir() {
+			fs, ok := scanOneFile(root)
+			if ok {
+				scanned++
+				findings = append(findings, fs...)
+			}
+			continue
+		}
+		walkErr := filepath.WalkDir(root, func(p string, d os.DirEntry, err error) error {
+			if err != nil {
+				return nil // unreadable entry — skip, don't abort the whole walk
+			}
+			if d.IsDir() {
+				if skipDirs[d.Name()] {
+					return filepath.SkipDir
+				}
+				return nil
+			}
+			if fs, ok := scanOneFile(p); ok {
+				scanned++
+				findings = append(findings, fs...)
+			}
+			return nil
+		})
+		if walkErr != nil {
+			return nil, 0, fmt.Errorf("walk %q: %w", root, walkErr)
+		}
+	}
+	sort.SliceStable(findings, func(i, j int) bool {
+		a, b := findings[i], findings[j]
+		if ra, rb := detect.SeverityRank(a.Severity), detect.SeverityRank(b.Severity); ra != rb {
+			return ra > rb
+		}
+		if a.Path != b.Path {
+			return a.Path < b.Path
+		}
+		return a.Line < b.Line
+	})
+	return findings, scanned, nil
+}
+
+// scanOneFile reads a file (bounded, text-only) and runs the engine. Returns
+// ok=false for a file that was skipped (too big, binary, unreadable) so it is
+// not counted as scanned.
+func scanOneFile(path string) ([]detect.Finding, bool) {
+	info, err := os.Stat(path)
+	if err != nil || info.Size() > maxScanFileBytes {
+		return nil, false
+	}
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return nil, false
+	}
+	if isBinary(b) {
+		return nil, false
+	}
+	return detect.ScanContent(path, string(b)), true
+}
+
+// isBinary reports whether b looks like a non-text blob — a NUL byte in the
+// first 8 KiB is the same heuristic git uses. Skipping binaries avoids both
+// false positives and wasted work on assets.
+func isBinary(b []byte) bool {
+	n := len(b)
+	if n > 8192 {
+		n = 8192
+	}
+	for i := 0; i < n; i++ {
+		if b[i] == 0 {
+			return true
+		}
+	}
+	return false
+}
+
+func renderScan(w io.Writer, r scanResult) {
+	if len(r.Findings) == 0 {
+		fmt.Fprintf(w, "✓ no secrets found (%d files scanned)\n", r.FilesScanned)
+		return
+	}
+	tw := newTab(w)
+	fmt.Fprintln(tw, "SEVERITY\tRULE\tLOCATION\tPREVIEW")
+	for _, f := range r.Findings {
+		fmt.Fprintf(tw, "%s\t%s\t%s:%d\t%s\n", f.Severity, f.RuleID, f.Path, f.Line, f.Preview)
+	}
+	tw.Flush()
+	fmt.Fprintf(w, "\n%d finding(s) in %d files  (critical=%d high=%d medium=%d low=%d)\n",
+		r.Summary.Total, r.FilesScanned, r.Summary.Critical, r.Summary.High,
+		r.Summary.Medium, r.Summary.Low)
+}

cli/security_test.go

@@ -0,0 +1,176 @@
+package cli
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// runSecurity executes `security <args>` through the real root command with an
+// isolated $HOME, capturing stdout. Returns output + the Execute error (the
+// non-zero-exit signal).
+func runSecurity(t *testing.T, args ...string) (string, error) {
+	t.Helper()
+	sandbox(t)
+	root := newRootCmd()
+	var out bytes.Buffer
+	root.SetOut(&out)
+	root.SetErr(&out)
+	root.SetArgs(append([]string{"security"}, args...))
+	err := root.Execute()
+	return out.String(), err
+}
+
+// TestSecurityScanFindsAndFails proves scan detects a planted secret, exits
+// non-zero at the default fail threshold, and never prints the raw secret.
+func TestSecurityScanFindsAndFails(t *testing.T) {
+	dir := t.TempDir()
+	secret := "AKIAIOSFODNN7EXAMPLE"
+	must(t, os.WriteFile(filepath.Join(dir, "config.py"),
+		[]byte("aws_key = \""+secret+"\"\nok = 1\n"), 0o644))
+	// a clean file that must NOT trip anything
+	must(t, os.WriteFile(filepath.Join(dir, "clean.go"),
+		[]byte("package main\nfunc main() {}\n"), 0o644))
+
+	out, err := runSecurity(t, "scan", dir)
+	if err == nil {
+		t.Fatalf("expected non-zero exit on a found secret; out:\n%s", out)
+	}
+	if !strings.Contains(err.Error(), "at or above") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if strings.Contains(out, secret) {
+		t.Fatalf("output leaked the raw secret:\n%s", out)
+	}
+	if !strings.Contains(out, "aws-access-key-id") {
+		t.Fatalf("expected the aws rule id in output:\n%s", out)
+	}
+}
+
+// TestSecurityScanCleanPasses proves a clean tree exits zero with the ok line.
+func TestSecurityScanCleanPasses(t *testing.T) {
+	dir := t.TempDir()
+	must(t, os.WriteFile(filepath.Join(dir, "app.go"),
+		[]byte("package main\nfunc main() { println(\"hi\") }\n"), 0o644))
+
+	out, err := runSecurity(t, "scan", dir)
+	if err != nil {
+		t.Fatalf("clean tree should exit zero, got %v\n%s", err, out)
+	}
+	if !strings.Contains(out, "no secrets found") {
+		t.Fatalf("expected the clean message:\n%s", out)
+	}
+}
+
+// TestSecurityScanFailOnNone proves --fail-on=none reports findings but exits
+// zero (report-only mode).
+func TestSecurityScanFailOnNone(t *testing.T) {
+	dir := t.TempDir()
+	must(t, os.WriteFile(filepath.Join(dir, "s.py"),
+		[]byte(`k = "AKIAIOSFODNN7EXAMPLE"`), 0o644))
+
+	out, err := runSecurity(t, "scan", "--fail-on", "none", dir)
+	if err != nil {
+		t.Fatalf("--fail-on=none should exit zero, got %v\n%s", err, out)
+	}
+	if !strings.Contains(out, "aws-access-key-id") {
+		t.Fatalf("report-only should still list the finding:\n%s", out)
+	}
+}
+
+// TestSecurityScanFailOnThreshold proves a medium finding does NOT fail when
+// --fail-on=critical, but a critical one does.
+func TestSecurityScanFailOnThreshold(t *testing.T) {
+	dir := t.TempDir()
+	// a jwt is medium severity
+	must(t, os.WriteFile(filepath.Join(dir, "t.txt"),
+		[]byte("tok = eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhYmMifQ.SGVsbG9TaWduYXR1cmU\n"), 0o644))
+
+	if out, err := runSecurity(t, "scan", "--fail-on", "critical", dir); err != nil {
+		t.Fatalf("medium finding must not fail at --fail-on=critical, got %v\n%s", err, out)
+	}
+	// now add a critical
+	must(t, os.WriteFile(filepath.Join(dir, "k.py"),
+		[]byte(`k = "AKIAIOSFODNN7EXAMPLE"`), 0o644))
+	if _, err := runSecurity(t, "scan", "--fail-on", "critical", dir); err == nil {
+		t.Fatal("a critical finding must fail at --fail-on=critical")
+	}
+}
+
+// TestSecurityScanJSON proves -o json emits a machine-readable result with the
+// summary and no raw secret.
+func TestSecurityScanJSON(t *testing.T) {
+	dir := t.TempDir()
+	secret := "AKIAIOSFODNN7EXAMPLE"
+	must(t, os.WriteFile(filepath.Join(dir, "s.py"), []byte(`k = "`+secret+`"`), 0o644))
+
+	out, _ := runSecurity(t, "scan", "-o", "json", "--fail-on", "none", dir)
+	var res scanResult
+	if err := json.Unmarshal([]byte(out), &res); err != nil {
+		t.Fatalf("json parse: %v\n%s", err, out)
+	}
+	if res.Summary.Critical < 1 || res.Summary.Total < 1 {
+		t.Fatalf("summary missing the critical: %+v", res.Summary)
+	}
+	if strings.Contains(out, secret) {
+		t.Fatalf("json leaked the secret:\n%s", out)
+	}
+}
+
+// TestSecurityScanSkipsVendorAndBinary proves the walker skips skipDirs and
+// binary files (a secret inside node_modules or a NUL-laden blob is ignored).
+func TestSecurityScanSkipsVendorAndBinary(t *testing.T) {
+	dir := t.TempDir()
+	nm := filepath.Join(dir, "node_modules")
+	must(t, os.MkdirAll(nm, 0o755))
+	must(t, os.WriteFile(filepath.Join(nm, "dep.js"),
+		[]byte(`k = "AKIAIOSFODNN7EXAMPLE"`), 0o644))
+	must(t, os.WriteFile(filepath.Join(dir, "blob.bin"),
+		append([]byte{0, 1, 2}, []byte(`AKIAIOSFODNN7EXAMPLE`)...), 0o644))
+
+	out, err := runSecurity(t, "scan", dir)
+	if err != nil {
+		t.Fatalf("vendored + binary secrets should be skipped → clean exit, got %v\n%s", err, out)
+	}
+	if !strings.Contains(out, "no secrets found") {
+		t.Fatalf("expected clean (skipped) result:\n%s", out)
+	}
+}
+
+// TestSecurityScanBadFailOn proves an invalid --fail-on is a clean error.
+func TestSecurityScanBadFailOn(t *testing.T) {
+	dir := t.TempDir()
+	_, err := runSecurity(t, "scan", "--fail-on", "nope", dir)
+	if err == nil || !strings.Contains(err.Error(), "invalid --fail-on") {
+		t.Fatalf("want invalid --fail-on error, got %v", err)
+	}
+}
+
+// TestSecurityRules proves the rules subcommand lists the catalog.
+func TestSecurityRules(t *testing.T) {
+	out, err := runSecurity(t, "rules")
+	if err != nil {
+		t.Fatalf("rules failed: %v", err)
+	}
+	if !strings.Contains(out, "aws-access-key-id") || !strings.Contains(out, "rules") {
+		t.Fatalf("rules output missing content:\n%s", out)
+	}
+}
+
+// TestSecurityIsControlVerb proves `security` routes to the CLI, not the server
+// dispatcher.
+func TestSecurityIsControlVerb(t *testing.T) {
+	if !IsControlVerb("security") {
+		t.Fatal("security must be a control verb")
+	}
+}
+
+func must(t *testing.T, err error) {
+	t.Helper()
+	if err != nil {
+		t.Fatal(err)
+	}
+}

cli/studio.go

@@ -0,0 +1,226 @@
+// 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"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"sync/atomic"
+	"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)
+
+// staging guards the claim-to-submit window: a claimed job is real work the
+// engine queue cannot see yet, so the supervisor must never recycle over it
+// (observed: jobs claimed during a recycle failed staging on a dead engine
+// and were consumed).
+var staging atomic.Int32
+
+func requestStudioRecycle() {
+	select {
+	case studioRecycle <- struct{}{}:
+	default:
+	}
+}
+
+// studioBusy reports whether the engine holds queued or running prompts.
+// A generous timeout: a saturated GB10 answers slowly mid-render — slow is
+// alive, and killing a live render costs 8-70 minutes of GPU work.
+func studioBusy(ctx context.Context) (busy, ok bool) {
+	ctx, cancel := context.WithTimeout(ctx, 20*time.Second)
+	defer cancel()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, "http://"+studioAddr+"/queue", nil)
+	if err != nil {
+		return false, false
+	}
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return false, false
+	}
+	defer resp.Body.Close()
+	var q struct {
+		Running []json.RawMessage `json:"queue_running"`
+		Pending []json.RawMessage `json:"queue_pending"`
+	}
+	if err := json.NewDecoder(io.LimitReader(resp.Body, 32<<20)).Decode(&q); err != nil {
+		return false, false
+	}
+	return len(q.Running)+len(q.Pending) > 0, true
+}
+
+// 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()
+	// recyclePending defers the post-render recycle until the queue is EMPTY:
+	// short jobs complete while a long render is mid-sample, and recycling on
+	// their completion killed the live render (observed: every direct render
+	// died within ~6 minutes while probe jobs cycled).
+	recyclePending := false
+	unhealthy := 0
+	for {
+		select {
+		case <-ctx.Done():
+			if cmd != nil && cmd.Process != nil {
+				_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGTERM)
+			}
+			return
+		case <-studioRecycle:
+			recyclePending = true
+		case <-tick.C:
+			busy, ok := studioBusy(ctx)
+			if recyclePending && ok && !busy && staging.Load() == 0 {
+				recyclePending = false
+				unhealthy = 0
+				restart("recycle")
+				continue
+			}
+			if studioHealthy(ctx) {
+				unhealthy = 0
+				continue
+			}
+			if ok && busy {
+				// Alive-busy: slow health under render load is not death.
+				unhealthy = 0
+				continue
+			}
+			// Sustained silence with an idle or unreadable queue = actually dead.
+			unhealthy++
+			if unhealthy < 3 {
+				continue
+			}
+			unhealthy = 0
+			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

@@ -0,0 +1,555 @@
+package account
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/hanzoai/cloud"
+	luxlog "github.com/luxfi/log"
+	"github.com/zap-proto/zip"
+)
+
+// fakeIAM is a stand-in for Hanzo IAM's /v1/iam/* management surface. It records
+// the confidential-client Basic auth it received (so a test can assert the console
+// authenticates as `hanzo-console`, NOT as the caller) and the exact `id` each
+// privileged op targeted (so a test can prove the console only ever acts on the
+// validated caller's own `<owner>/<name>`). It never needs a real cluster.
+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)
+
+	// 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
+}
+
+func newFakeIAM() *fakeIAM {
+	return &fakeIAM{
+		keys:    map[string]string{},
+		orgs:    map[string]map[string]any{},
+		user:    map[string]map[string]any{},
+		movedTo: map[string]string{},
+	}
+}
+
+func (f *fakeIAM) server(t *testing.T) *httptest.Server {
+	t.Helper()
+	mux := http.NewServeMux()
+
+	ok := func(w http.ResponseWriter, data any) {
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{"status": "ok", "msg": "", "data": data})
+	}
+	bad := func(w http.ResponseWriter, msg string) {
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{"status": "error", "msg": msg, "data": nil})
+	}
+
+	mux.HandleFunc("/v1/iam/get-user", func(w http.ResponseWriter, r *http.Request) {
+		f.capture(r)
+		id := r.URL.Query().Get("id")
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		if row, present := f.user[id]; present {
+			// A configured user row wins (used by the onboarding move).
+			out := map[string]any{}
+			for k, v := range row {
+				out[k] = v
+			}
+			if key, has := f.keys[id]; has {
+				out["accessKey"] = key
+			}
+			ok(w, out)
+			return
+		}
+		// Otherwise synthesize a thin row carrying just the key state.
+		ok(w, map[string]any{"accessKey": f.keys[id], "updatedTime": "2026-01-02T03:04:05Z"})
+	})
+
+	mux.HandleFunc("/v1/iam/mint-user-keys", func(w http.ResponseWriter, r *http.Request) {
+		f.capture(r)
+		id := r.URL.Query().Get("id")
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		f.mintedFor = append(f.mintedFor, id)
+		if f.failMintKey {
+			bad(w, "mint failed")
+			return
+		}
+		key := "hk-" + strings.ReplaceAll(id, "/", "-") + "-SECRET"
+		f.keys[id] = key
+		ok(w, map[string]any{"accessKey": key})
+	})
+
+	mux.HandleFunc("/v1/iam/revoke-user-keys", func(w http.ResponseWriter, r *http.Request) {
+		f.capture(r)
+		id := r.URL.Query().Get("id")
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		f.revokedFor = append(f.revokedFor, id)
+		f.keys[id] = ""
+		ok(w, map[string]any{})
+	})
+
+	mux.HandleFunc("/v1/iam/get-organization", func(w http.ResponseWriter, r *http.Request) {
+		f.capture(r)
+		id := r.URL.Query().Get("id") // admin/<slug>
+		slug := id
+		if i := strings.IndexByte(id, '/'); i >= 0 {
+			slug = id[i+1:]
+		}
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		if row, present := f.orgs[slug]; present && row != nil {
+			ok(w, row)
+			return
+		}
+		bad(w, "organization does not exist") // not-ok ⇒ getOrganization returns (nil,nil)
+	})
+
+	mux.HandleFunc("/v1/iam/add-organization", func(w http.ResponseWriter, r *http.Request) {
+		f.capture(r)
+		body, _ := io.ReadAll(r.Body)
+		var row map[string]any
+		_ = json.Unmarshal(body, &row)
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		if f.failAddOrg {
+			bad(w, "add-organization denied")
+			return
+		}
+		f.createdOrgs = append(f.createdOrgs, row)
+		if name, _ := row["name"].(string); name != "" {
+			f.orgs[name] = row
+		}
+		ok(w, map[string]any{})
+	})
+
+	mux.HandleFunc("/v1/iam/update-user", func(w http.ResponseWriter, r *http.Request) {
+		f.capture(r)
+		id := r.URL.Query().Get("id")
+		body, _ := io.ReadAll(r.Body)
+		var row map[string]any
+		_ = json.Unmarshal(body, &row)
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		if owner, _ := row["owner"].(string); owner != "" {
+			f.movedTo[id] = owner
+		}
+		ok(w, map[string]any{})
+	})
+
+	srv := httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func (f *fakeIAM) capture(r *http.Request) {
+	f.mu.Lock()
+	f.gotAuth = r.Header.Get("Authorization")
+	f.mu.Unlock()
+}
+
+// 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")})
+	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.
+func call(t *testing.T, app *zip.App, method, path, user, org, 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")
+	}
+	if user != "" {
+		req.Header.Set("X-User-Id", user)
+	}
+	if org != "" {
+		req.Header.Set("X-Org-Id", org)
+	}
+	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
+}
+
+// ── keys ──────────────────────────────────────────────────────────────────────
+
+func TestKeys_RequireValidatedPrincipal(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	// 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/iam/keys", "", "victim", "")
+		if code != http.StatusForbidden {
+			t.Fatalf("%s /keys with forged org but no principal: want 403, got %d", m, code)
+		}
+	}
+	if len(f.mintedFor) != 0 || len(f.revokedFor) != 0 {
+		t.Fatalf("IAM privileged op reached on the unauthenticated path: minted=%v revoked=%v", f.mintedFor, f.revokedFor)
+	}
+}
+
+func TestKeys_MintGetRevoke_ScopedToCaller(t *testing.T) {
+	f := newFakeIAM()
+	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/iam/keys", "alice", "acme", "")
+	if code != http.StatusOK {
+		t.Fatalf("get pre-mint: want 200, got %d (%s)", code, body)
+	}
+	var st keyStatus
+	mustJSON(t, body, &st)
+	if st.HasKey {
+		t.Fatalf("pre-mint hasKey should be false: %s", body)
+	}
+
+	// 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/iam/keys", "alice", "acme", "")
+	if code != http.StatusOK {
+		t.Fatalf("mint: want 200, got %d (%s)", code, body)
+	}
+	var minted struct {
+		AccessKey string `json:"accessKey"`
+	}
+	mustJSON(t, body, &minted)
+	if minted.AccessKey != "hk-acme-alice-SECRET" {
+		t.Fatalf("mint returned wrong key: %q", minted.AccessKey)
+	}
+	if len(f.mintedFor) != 1 || f.mintedFor[0] != "acme/alice" {
+		t.Fatalf("mint should target the derived id acme/alice, got %v", f.mintedFor)
+	}
+
+	// The confidential client authenticated as `hanzo-console` (Basic), NOT as the
+	// caller — the whole point of the app-on-behalf boundary.
+	wantAuth := "Basic " + base64.StdEncoding.EncodeToString([]byte("hanzo-console:s3cr3t"))
+	if f.gotAuth != wantAuth {
+		t.Fatalf("IAM auth: want confidential-client Basic, got %q", f.gotAuth)
+	}
+
+	// GET after mint → hasKey:true with the public prefix only (no secret material).
+	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)
+	}
+	if strings.Contains(string(body), "SECRET") {
+		t.Fatalf("GET /keys leaked the secret: %s", body)
+	}
+
+	// DELETE → revoke, targeting the same derived id.
+	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/iam/keys", "alice", "acme", "")
+	if code != http.StatusNotImplemented {
+		t.Fatalf("unconfigured mint: want 501, got %d (%s)", code, body)
+	}
+}
+
+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/iam/keys", "alice", "acme", "")
+	if code != http.StatusBadGateway {
+		t.Fatalf("mint upstream failure: want 502, got %d (%s)", code, body)
+	}
+}
+
+// ── onboard ─────────────────────────────────────────────────────────────────
+
+func TestOnboard_FirstRun_CreatesAndMoves(t *testing.T) {
+	f := newFakeIAM()
+	// The zero-org user (empty X-Org-Id ⇒ bare id "dave") has a real user row so the
+	// move can re-submit it.
+	f.user["dave"] = map[string]any{"owner": "", "name": "dave", "type": "normal-user"}
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	// 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/iam/onboard", "dave", "", `{"name":"Acme Rockets"}`)
+	if code != http.StatusOK {
+		t.Fatalf("first-run onboard: want 200, got %d (%s)", code, body)
+	}
+	var resp onboardResp
+	mustJSON(t, body, &resp)
+	if resp.Org != "acme-rockets" || resp.Additional {
+		t.Fatalf("onboard result wrong: %+v", resp)
+	}
+	if len(f.createdOrgs) != 1 {
+		t.Fatalf("want 1 org created, got %d", len(f.createdOrgs))
+	}
+	if owner, _ := f.createdOrgs[0]["owner"].(string); owner != "admin" {
+		t.Fatalf("created org must be owned by admin, got %q", owner)
+	}
+	if f.movedTo["dave"] != "acme-rockets" {
+		t.Fatalf("first-run must move the user into the new org, movedTo=%v", f.movedTo)
+	}
+}
+
+func TestOnboard_Additional_CreatesWithoutMoving(t *testing.T) {
+	f := newFakeIAM()
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	// 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/iam/onboard", "alice", "acme", `{"name":"Side Project"}`)
+	if code != http.StatusOK {
+		t.Fatalf("additional onboard: want 200, got %d (%s)", code, body)
+	}
+	var resp onboardResp
+	mustJSON(t, body, &resp)
+	if resp.Org != "side-project" || !resp.Additional {
+		t.Fatalf("additional onboard result wrong: %+v", resp)
+	}
+	if len(f.movedTo) != 0 {
+		t.Fatalf("additional onboard must NOT move the user, movedTo=%v", f.movedTo)
+	}
+}
+
+func TestOnboard_ReservedAndTaken(t *testing.T) {
+	f := newFakeIAM()
+	f.orgs["taken"] = map[string]any{"owner": "admin", "name": "taken"}
+	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/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/iam/onboard", "alice", "acme", `{"name":"Taken"}`)
+	if code != http.StatusConflict {
+		t.Fatalf("taken name: want 409, got %d", code)
+	}
+	if len(f.createdOrgs) != 0 {
+		t.Fatalf("no org should be created for reserved/taken names, got %d", len(f.createdOrgs))
+	}
+}
+
+func TestOnboard_Personal_AutoSuffixesOnCollision(t *testing.T) {
+	f := newFakeIAM()
+	f.user["dave"] = map[string]any{"owner": "", "name": "dave"}
+	f.orgs["dave"] = map[string]any{"owner": "admin", "name": "dave"} // base personal slug already taken
+	app := mountApp(t, f.server(t).URL, "hanzo-console", "s3cr3t")
+
+	// 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/iam/onboard", "dave", "", `{"personal":true}`)
+	if code != http.StatusOK {
+		t.Fatalf("personal onboard: want 200, got %d (%s)", code, body)
+	}
+	var resp onboardResp
+	mustJSON(t, body, &resp)
+	if resp.Org != "dave-2" {
+		t.Fatalf("personal collision should auto-suffix to dave-2, got %q", resp.Org)
+	}
+}
+
+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/iam/onboard", "alice", "acme", `{"personal":true}`)
+	if code != http.StatusConflict {
+		t.Fatalf("personal-while-orged: want 409, got %d", code)
+	}
+}
+
+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/iam/onboard", "", "", `{"name":"x"}`)
+	if code != http.StatusForbidden {
+		t.Fatalf("unauth onboard: want 403, got %d", code)
+	}
+}
+
+// ── route ordering: the native /v1/iam surface beats clients/iam's wildcard ───
+
+// 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 := 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)
+	}
+
+	// /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)
+	}
+}
+
+func mustJSON(t *testing.T, body []byte, v any) {
+	t.Helper()
+	if err := json.Unmarshal(body, v); err != nil {
+		t.Fatalf("decode %T: %v (%s)", v, err, body)
+	}
+}

clients/account/billing.go

@@ -0,0 +1,352 @@
+// 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"
+	"crypto/subtle"
+	"encoding/json"
+	"net/http"
+	"net/url"
+	"strings"
+	"unicode"
+
+	"github.com/hanzoai/account"
+
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/principal"
+	"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",
+		"spend-alerts/authorize", // the S2S cap-verdict read (metering gate); 2 segments need their own entry
+		"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).
+	// Auth. A browser caller is the VALIDATED principal (customer path — subject-pinned
+	// below). An IN-PROC S2S caller carries the verified COMMERCE_SERVICE_TOKEN (the
+	// metering cap-gate's authorize + the SuperAdmin cap-oversight Forward). The gateway
+	// 401s a public Bearer that is not an IAM JWT / hk-|pk-|sk- key (the 64-hex service
+	// token fails JWT parse at the edge), so an EXTERNAL client can NEVER present it here —
+	// an unauthenticated caller still hits the 403 below. On the S2S path the caller
+	// legitimately names its own subject, so its query is forwarded as-is (no pin), scoped
+	// only by the EdgeAuth-controlled X-Org-Id.
+	cr, ok := resolveCaller(c, true)
+	s2s := false
+	owner := cr.owner
+	if !ok {
+		if !s2sBillingCall(c) {
+			return zip.ErrForbidden("sign in to view billing")
+		}
+		owner = strings.TrimSpace(c.Org()) // trusted X-Org-Id (never a client value on a public call)
+		if owner == "" {
+			return zip.ErrForbidden("sign in to view billing")
+		}
+		s2s = true
+	}
+
+	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), fed the account the
+	// credential NAMES (the validated `billing_account` claim) — the same claim the
+	// ai gate reads, so a top-up credits the SAME account the gate debits. Feeding
+	// Payer a different credential here than the gate gets is the modern shape of
+	// the old split: money landing in an account the gate never reads.
+	inQuery, _ := url.ParseQuery(string(c.Fiber().Request().URI().QueryString()))
+	var q url.Values
+	var body []byte
+	if s2s {
+		// Trusted S2S caller: forward its query/body VERBATIM — it legitimately names the
+		// subject (e.g. the metering gate's ?user=<org>&amount=). Scoped by X-Org-Id.
+		q = inQuery
+		if method == http.MethodPost {
+			body = c.Body()
+		}
+	} else {
+		// Browser customer: pin EVERY subject key to the caller's OWN account so commerce's
+		// per-tenant isolation can never be crossed from the client.
+		subject := account.Payer(account.Credential{Owner: cr.owner, Name: cr.username, Account: principal.BillingAccount(c)}).Subject()
+		q = scopedBillingSearch(inQuery, subject)
+		if method == http.MethodPost {
+			body = scopedBillingBody(c.Body(), subject)
+		}
+	}
+
+	raw, status, err := commerceDo(c.Context(), base, token, method, "/v1/billing/"+sub, q, 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)
+}
+
+// s2sBillingCall reports whether the request carries the verified COMMERCE_SERVICE_TOKEN
+// as its Bearer — a trusted IN-PROC service-to-service caller (the metering cap-gate's
+// authorize, the SuperAdmin cap-oversight Forward). It is the SAME secret this bridge
+// already forwards WITH, so admitting a caller who already holds it grants no authority it
+// could not otherwise wield. Safety rests on the edge: the gateway 401s a public Bearer
+// that is not an IAM JWT / hk-|pk-|sk- API key (the 64-hex service token is a JWT
+// candidate that fails to parse), so an EXTERNAL client can never reach this handler
+// holding it — only in-proc commerceinproc dispatch does. Constant-time compare; the token
+// is never logged.
+func s2sBillingCall(c *zip.Ctx) bool {
+	_, token := commerceCreds()
+	if token == "" {
+		return false
+	}
+	bearer := strings.TrimSpace(strings.TrimPrefix(c.Header("Authorization"), "Bearer "))
+	return bearer != "" && subtle.ConstantTimeCompare([]byte(bearer), []byte(token)) == 1
+}

clients/account/billing_test.go

@@ -0,0 +1,296 @@
+package account
+
+import (
+	"encoding/json"
+	"github.com/hanzoai/account"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"sync"
+	"testing"
+)
+
+// billing_test.go — the per-tenant billing bridge (billing.go). Proves the tenant
+// 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) {
+	cases := []struct{ org, name, want string }{
+		{"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 {
+		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)
+		}
+	}
+}
+
+func TestScopedBillingSearch_PinsSubjectDropsOrgKeepsRest(t *testing.T) {
+	in := url.Values{}
+	in.Set("userId", "victim")     // forged subject — must be OVERWRITTEN
+	in.Set("customerId", "victim") // forged subject — must be OVERWRITTEN
+	in.Set("user", "victim")       // forged subject — must be OVERWRITTEN
+	in.Set("org", "othercorp")     // must be DROPPED (cannot widen scope)
+	in.Set("currency", "usd")      // non-subject — must PASS THROUGH
+	in.Set("start", "2026-01-01")  // non-subject — must PASS THROUGH
+
+	out := scopedBillingSearch(in, "acme")
+
+	for _, k := range billingSubjectKeys {
+		if out.Get(k) != "acme" {
+			t.Fatalf("subject key %s must be pinned to acme, got %q", k, out.Get(k))
+		}
+	}
+	if out.Has("org") {
+		t.Fatal("org must be dropped")
+	}
+	if out.Get("currency") != "usd" || out.Get("start") != "2026-01-01" {
+		t.Fatalf("non-subject params must pass through, got %v", out)
+	}
+}
+
+func TestScopedBillingBody(t *testing.T) {
+	// a forged subject in a JSON object write is OVERWRITTEN; other fields survive.
+	out := scopedBillingBody([]byte(`{"userId":"victim","amount":500,"note":"x"}`), "acme")
+	var obj map[string]any
+	if err := json.Unmarshal(out, &obj); err != nil {
+		t.Fatalf("scoped body is not JSON: %v", err)
+	}
+	for _, k := range billingSubjectKeys {
+		if obj[k] != "acme" {
+			t.Fatalf("body subject key %s must be pinned to acme, got %v", k, obj[k])
+		}
+	}
+	if obj["amount"].(float64) != 500 || obj["note"] != "x" {
+		t.Fatalf("non-subject body fields must survive, got %v", obj)
+	}
+
+	// non-object / empty bodies pass through untouched (never invent a body).
+	for _, raw := range []string{"not json", `[1,2,3]`, `"scalar"`, ""} {
+		if got := string(scopedBillingBody([]byte(raw), "acme")); got != raw {
+			t.Fatalf("non-object body %q must pass through, got %q", raw, got)
+		}
+	}
+}
+
+// ── handler (IDOR + forwarding) ──────────────────────────────────────────────
+
+// fakeBilling records exactly what the handler forwarded to commerce.
+type fakeBilling struct {
+	mu    sync.Mutex
+	path  string
+	query url.Values
+	body  map[string]any
+	org   string
+	auth  string
+}
+
+func (f *fakeBilling) server(t *testing.T) *httptest.Server {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		f.mu.Lock()
+		f.path, f.query = r.URL.Path, r.URL.Query()
+		f.org, f.auth = r.Header.Get("X-Org-Id"), r.Header.Get("Authorization")
+		if raw, _ := io.ReadAll(r.Body); len(raw) > 0 {
+			_ = json.Unmarshal(raw, &f.body)
+		}
+		f.mu.Unlock()
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"balance":123}`)
+	}))
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func TestBilling_RequiresValidatedPrincipal(t *testing.T) {
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := mountApp(t, "http://iam.invalid", "", "")
+	// A forged X-Org-Id with NO validated X-User-Id is the exact forge — refuse it
+	// BEFORE any commerce call (no cross-tenant ledger read on a victim org).
+	code, _ := callH(t, app, http.MethodGet, "/v1/billing/balance", map[string]string{"X-Org-Id": "victim"}, "")
+	if code != http.StatusForbidden {
+		t.Fatalf("no validated principal: want 403, got %d", code)
+	}
+}
+
+func TestBilling_NotConfiguredWithoutToken(t *testing.T) {
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "")
+	app := mountApp(t, "http://iam.invalid", "", "")
+	code, _ := callH(t, app, http.MethodGet, "/v1/billing/balance", alice, "")
+	if code != http.StatusNotImplemented {
+		t.Fatalf("no commerce token: want 501, got %d", code)
+	}
+}
+
+func TestBilling_ScopesQueryToCallerAndForwards(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", "", "")
+
+	// alice/acme with a FORGED ?userId=victim & ?org=othercorp: the handler must pin
+	// every subject key to the caller's own subject (acme) and drop org.
+	code, body := callH(t, app, http.MethodGet,
+		"/v1/billing/invoices?userId=victim&customerId=victim&org=othercorp&status=open", alice, "")
+	if code != http.StatusOK {
+		t.Fatalf("want 200, got %d (%s)", code, body)
+	}
+	if f.path != "/v1/billing/invoices" {
+		t.Fatalf("forwarded path: want /v1/billing/invoices, got %q", f.path)
+	}
+	for _, k := range billingSubjectKeys {
+		if f.query.Get(k) != "acme" {
+			t.Fatalf("commerce must receive %s=acme (the caller's subject), got %q", k, f.query.Get(k))
+		}
+	}
+	if f.query.Has("org") {
+		t.Fatal("org must be dropped before commerce")
+	}
+	if f.query.Get("status") != "open" {
+		t.Fatalf("non-subject filter must pass through, got %q", f.query.Get("status"))
+	}
+	if f.org != "acme" || f.auth != "Bearer svc-tok" {
+		t.Fatalf("S2S must send X-Org-Id=acme + the service token, got org=%q auth=%q", f.org, f.auth)
+	}
+}
+
+func TestBilling_ScopesWriteBodyToCaller(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", "", "")
+
+	// a POST with a forged userId in the body must be overwritten to acme.
+	code, _ := callH(t, app, http.MethodPost, "/v1/billing/spend-alerts", alice,
+		`{"userId":"victim","threshold":5000}`)
+	if code != http.StatusOK {
+		t.Fatalf("want 200, got %d", code)
+	}
+	if f.body["userId"] != "acme" {
+		t.Fatalf("write-body subject must be pinned to acme, got %v", f.body["userId"])
+	}
+	if f.body["threshold"].(float64) != 5000 {
+		t.Fatalf("non-subject body field must survive, got %v", f.body["threshold"])
+	}
+}
+
+func TestBilling_RejectsTraversalSegment(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", "", "")
+	// Every traversal form — literal `..`, encoded slash (`%2f`), encoded dot
+	// (`%2e%2e`), matrix param (`;`) — must be REFUSED (400) and must NEVER reach
+	// commerce. Without the percent-escape rejection, `invoices/..%2fadmin` decodes
+	// downstream to `/v1/admin`, tunneling PAST /v1/billing into another surface.
+	for _, p := range []string{
+		"/v1/billing/invoices/../admin",   // literal ..
+		"/v1/billing/invoices/..%2fadmin", // encoded slash (%2f)
+		"/v1/billing/%2e%2e/admin",        // encoded dots (%2e%2e)
+		"/v1/billing/invoices;statement",  // matrix param (;)
+	} {
+		code, _ := callH(t, app, http.MethodGet, p, alice, "")
+		if code != http.StatusBadRequest {
+			t.Fatalf("traversal %q: want 400, got %d", p, code)
+		}
+	}
+	if f.path != "" {
+		t.Fatalf("a traversal must never reach commerce, but upstream saw %q", f.path)
+	}
+}
+
+// ── S2S service-token admission (the auth fix; 4 security invariants) ─────────
+
+// Invariant #4 — THE SECURITY GATE: a public/unauthenticated caller (no validated
+// principal AND not the service token) STILL gets 403 on the spend-alert routes, incl.
+// a WRONG bearer. The fix must NEVER open billing to the world.
+func TestBilling_S2S_PublicStill403(t *testing.T) {
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := mountApp(t, "http://iam.invalid", "", "")
+	for _, path := range []string{
+		"/v1/billing/spend-alerts",
+		"/v1/billing/spend-alerts/authorize?user=acme&amount=1",
+	} {
+		// forged X-Org-Id, no validated principal, no service token
+		if code, body := callH(t, app, http.MethodGet, path, map[string]string{"X-Org-Id": "victim"}, ""); code != http.StatusForbidden {
+			t.Fatalf("public caller to %s: want 403, got %d (%s)", path, code, body)
+		}
+	}
+	// a WRONG bearer is still just a public caller → 403
+	if code, _ := callH(t, app, http.MethodGet, "/v1/billing/spend-alerts/authorize?user=acme&amount=1",
+		map[string]string{"X-Org-Id": "acme", "Authorization": "Bearer not-the-token"}, ""); code != http.StatusForbidden {
+		t.Fatalf("wrong bearer: want 403")
+	}
+}
+
+// The trusted in-proc S2S caller (verified COMMERCE_SERVICE_TOKEN + X-Org-Id) is admitted
+// and its authorize query is forwarded to commerce VERBATIM (a trusted caller names its
+// own subject), scoped by X-Org-Id — this is what lets the cap gate reach AuthorizeSpendCap.
+func TestBilling_S2S_ServiceTokenForwardsVerbatim(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, http.MethodGet,
+		"/v1/billing/spend-alerts/authorize?user=acme&amount=100&project=P",
+		map[string]string{"Authorization": "Bearer svc-tok", "X-Org-Id": "acme"}, "")
+	if code != http.StatusOK {
+		t.Fatalf("S2S authorize: want 200, got %d (%s)", code, body)
+	}
+	if f.path != "/v1/billing/spend-alerts/authorize" {
+		t.Fatalf("forwarded path = %q", f.path)
+	}
+	// VERBATIM: the S2S caller's ?user/?amount/?project reach commerce un-pinned.
+	if f.query.Get("user") != "acme" || f.query.Get("amount") != "100" || f.query.Get("project") != "P" {
+		t.Fatalf("S2S query must forward verbatim, got %v", f.query)
+	}
+	if f.org != "acme" || f.auth != "Bearer svc-tok" {
+		t.Fatalf("S2S must send X-Org-Id=acme + service token, got org=%q auth=%q", f.org, f.auth)
+	}
+}
+
+// S2S with the verified token but NO X-Org-Id → 403 (no org to scope the privileged
+// forward to; never fall back to a client value).
+func TestBilling_S2S_NoOrg403(t *testing.T) {
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := mountApp(t, "http://iam.invalid", "", "")
+	if code, _ := callH(t, app, http.MethodGet, "/v1/billing/spend-alerts/authorize?user=acme&amount=1",
+		map[string]string{"Authorization": "Bearer svc-tok"}, ""); code != http.StatusForbidden {
+		t.Fatalf("S2S without X-Org-Id: want 403")
+	}
+}

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

@@ -0,0 +1,147 @@
+// 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|
+// DELETE /v1/commerce/<path> forwards to commerce's bare store surface /v1/<path> with
+// the admin COMMERCE_SERVICE_TOKEN, SCOPING every request to the VALIDATED caller's own
+// org — so a merchant only ever reads/writes its OWN org's catalog (products / orders /
+// customers / variants / collections / discounts / storefront), never another's.
+//
+// WHY /v1/commerce/<x> → commerce /v1/<x> (the `commerce` segment is DROPPED, not
+// preserved like billing's /v1/billing/<x> → /v1/billing/<x>). The DEPLOYED commerce
+// binary (hanzoai/commerce cmd/commerced) mounts its whole REST surface with
+// `api.Route(router.Group("/v1"))`: the store models live at BARE /v1/<kind>
+// (/v1/product, /v1/order, /v1/user, …) while money lives at /v1/billing/*. The
+// 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 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
+// service-token-gated: its EdgeAuth resolves the org from the X-Org-Id header ONLY
+// after it verifies the bearer is the COMMERCE_SERVICE_TOKEN, then scopes every store
+// row to that org. A browser passthrough would have to carry that admin token (a
+// cross-tenant skeleton key) or a per-tenant selector the browser could forge — either
+// leaks another org's store. This handler injects the token SERVER-SIDE and pins the
+// org to the caller's own, so tenancy can never be crossed from the browser.
+//
+// IDOR-safe: the org is derived from the VALIDATED identity (resolveCaller →
+// principal.Validated / c.Org() / c.User()), NEVER a client-supplied value. A
+// bearer-less request with a forged X-Org-Id has no validated principal and is refused
+// (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 console's
+// proxy-allow.ts allowCommerceSurface.
+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 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
+// the store token can never reach the money or tenant-admin surfaces that share commerce's
+// binary — those have their OWN scoped bridges (billing.go) or are unreachable.
+var commerceStoreHeads = map[string]bool{
+	"product":       true, // products
+	"variant":       true, // inventory / SKUs
+	"collection":    true, // catalog collections
+	"order":         true, // orders
+	"user":          true, // customers
+	"discount":      true, // promotions & discounts
+	"coupon":        true, // discount codes
+	"saleschannel":  true, // sales channels
+	"stocklocation": true, // stock locations
+	"store":         true, // storefront settings
+}
+
+// isCommerceStoreHead reports whether sub (the path after /v1/commerce/) targets an
+// allow-listed store head — the FIRST segment, so `product`, `product/<id>`, and
+// `store/current` all resolve to their head (`product`, `store`).
+func isCommerceStoreHead(sub string) bool {
+	head := sub
+	if i := strings.IndexByte(sub, '/'); i >= 0 {
+		head = sub[:i]
+	}
+	return commerceStoreHeads[head]
+}
+
+// commerceData forwards GET|POST|PUT|PATCH|DELETE /v1/commerce/<path> to commerce's
+// 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 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)
+	if !ok {
+		return zip.ErrForbidden("sign in to manage your store")
+	}
+
+	switch c.Method() {
+	case http.MethodGet, http.MethodPost, http.MethodPut, http.MethodPatch, http.MethodDelete:
+	default:
+		return zip.Errorf(http.StatusMethodNotAllowed, "method not allowed")
+	}
+
+	base, token := commerceCreds()
+	if token == "" {
+		// Honest "not configured" (mirrors billing.go's 501 when the token is unset) —
+		// the console shows a truthful state, never a fabricated store.
+		return zip.Errorf(http.StatusNotImplemented, "commerce 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, "commerce endpoint required")
+	}
+	for _, seg := range strings.Split(sub, "/") {
+		// isSafeSegment is the ONE guard (billing.go): it rejects empty/./../slash/
+		// backslash/control AND percent-escape/matrix-param, so encoded traversal
+		// (`product/..%2fbilling` → downstream `/v1/billing`) can never tunnel PAST the
+		// store-head allow-list into the money surface.
+		if !isSafeSegment(seg) {
+			return zip.ErrBadRequest("invalid commerce path")
+		}
+	}
+	// Least privilege: only the merchant store heads (defense in depth). A non-store
+	// head (billing/checkout/namespace/…) is 404'd here, so this bridge can never be a
+	// general tunnel into commerce's money / tenant-admin surfaces.
+	if !isCommerceStoreHead(sub) {
+		return zip.Errorf(http.StatusNotFound, "not a commerce store endpoint")
+	}
+
+	// The store query (limit/page/q/sort) passes through verbatim — commerce scopes the
+	// store by the X-Org-Id header (bound below), not a query param, so there is no
+	// subject to pin as in billing. The org is NEVER read from the query.
+	q, _ := url.ParseQuery(string(c.Fiber().Request().URI().QueryString()))
+
+	// Forward the write body verbatim on mutating methods (commerce validates it).
+	var body []byte
+	if c.Method() != http.MethodGet && len(c.Body()) > 0 {
+		body = c.Body()
+	}
+
+	// commerceDo binds X-Org-Id = the caller's OWN validated org + the admin service
+	// token; commerce's EdgeAuth trusts that org ONLY behind the token and scopes the
+	// store to it. This is the SAME S2S transport billing.go / topup.go share.
+	raw, status, err := commerceDo(c.Context(), base, token, c.Method(), "/v1/"+sub, q, cr.owner, body)
+	if err != nil {
+		return zip.Errorf(http.StatusBadGateway, "commerce upstream unreachable: %v", err)
+	}
+	// A per-tenant store response must never be cached across tenants; commerce answers
+	// JSON, so pin JSON + no-store (identical to billing.go).
+	c.SetHeader("Content-Type", "application/json")
+	c.SetHeader("Cache-Control", "no-store, must-revalidate")
+	return c.Bytes(status, raw)
+}

clients/account/commerce_test.go

@@ -0,0 +1,188 @@
+package account
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"sync"
+	"testing"
+)
+
+// commerce_test.go — the per-tenant STORE bridge (commerce.go). Proves the org
+// scoping that prevents cross-tenant store access, the /v1/commerce/<x> → /v1/<x>
+// remap, the store-head least-privilege gate, and the IDOR-safe forwarding — the
+// store twin of billing_test.go.
+
+// ── pure allow-list ──────────────────────────────────────────────────────────
+
+func TestIsCommerceStoreHead(t *testing.T) {
+	// Every store head (and its sub-paths) is admitted; a non-store head is not, so
+	// the bridge can never tunnel to the money / tenant-admin surfaces.
+	allow := []string{"product", "product/abc", "store/current", "order", "user", "variant"}
+	deny := []string{"billing", "billing/balance", "checkout", "checkout/session", "namespace", "_", "tenants", ""}
+	for _, p := range allow {
+		if !isCommerceStoreHead(p) {
+			t.Fatalf("store head %q must be admitted", p)
+		}
+	}
+	for _, p := range deny {
+		if isCommerceStoreHead(p) {
+			t.Fatalf("non-store path %q must be refused", p)
+		}
+	}
+}
+
+// ── handler (IDOR + forwarding) ──────────────────────────────────────────────
+
+// fakeStore records exactly what the handler forwarded to commerce.
+type fakeStore struct {
+	mu     sync.Mutex
+	method string
+	path   string
+	query  url.Values
+	body   map[string]any
+	org    string
+	auth   string
+}
+
+func (f *fakeStore) server(t *testing.T) *httptest.Server {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		f.mu.Lock()
+		f.method, f.path, f.query = r.Method, r.URL.Path, r.URL.Query()
+		f.org, f.auth = r.Header.Get("X-Org-Id"), r.Header.Get("Authorization")
+		if raw, _ := io.ReadAll(r.Body); len(raw) > 0 {
+			_ = json.Unmarshal(raw, &f.body)
+		}
+		f.mu.Unlock()
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"models":[],"count":0}`)
+	}))
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func TestCommerce_RequiresValidatedPrincipal(t *testing.T) {
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := mountApp(t, "http://iam.invalid", "", "")
+	// A forged X-Org-Id with NO validated X-User-Id is the exact forge — refuse it
+	// BEFORE any commerce call (no cross-tenant store read on a victim org). Cover a
+	// mutating method too: a forged write must 403, never reach the store.
+	for _, m := range []string{http.MethodGet, http.MethodPost, http.MethodDelete} {
+		code, _ := callH(t, app, m, "/v1/commerce/product", map[string]string{"X-Org-Id": "victim"}, "")
+		if code != http.StatusForbidden {
+			t.Fatalf("%s no validated principal: want 403, got %d", m, code)
+		}
+	}
+}
+
+func TestCommerce_NotConfiguredWithoutToken(t *testing.T) {
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "")
+	app := mountApp(t, "http://iam.invalid", "", "")
+	code, _ := callH(t, app, http.MethodGet, "/v1/commerce/product", alice, "")
+	if code != http.StatusNotImplemented {
+		t.Fatalf("no commerce token: want 501, got %d", code)
+	}
+}
+
+func TestCommerce_ForwardsToBareStoreScopedToCaller(t *testing.T) {
+	f := &fakeStore{}
+	t.Setenv("COMMERCE_URL", f.server(t).URL)
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := mountApp(t, "http://iam.invalid", "", "")
+
+	// alice/acme lists products: the console-side /v1/commerce/product must reach
+	// commerce's BARE /v1/product (the `commerce` namespace stripped), scoped to acme.
+	code, body := callH(t, app, http.MethodGet, "/v1/commerce/product?limit=100&q=shirt", alice, "")
+	if code != http.StatusOK {
+		t.Fatalf("want 200, got %d (%s)", code, body)
+	}
+	if f.path != "/v1/product" {
+		t.Fatalf("forwarded path: want /v1/product (bare, namespace stripped), got %q", f.path)
+	}
+	if f.query.Get("limit") != "100" || f.query.Get("q") != "shirt" {
+		t.Fatalf("store query must pass through verbatim, got %v", f.query)
+	}
+	if f.org != "acme" || f.auth != "Bearer svc-tok" {
+		t.Fatalf("S2S must send X-Org-Id=acme (validated org) + the service token, got org=%q auth=%q", f.org, f.auth)
+	}
+}
+
+func TestCommerce_ForwardsSubPathAndWriteBody(t *testing.T) {
+	f := &fakeStore{}
+	t.Setenv("COMMERCE_URL", f.server(t).URL)
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := mountApp(t, "http://iam.invalid", "", "")
+
+	// createProduct: POST /v1/commerce/product with a body → commerce /v1/product,
+	// body forwarded verbatim, org bound to the caller.
+	code, _ := callH(t, app, http.MethodPost, "/v1/commerce/product", alice,
+		`{"name":"Tee","sku":"TEE-1","slug":"tee"}`)
+	if code != http.StatusOK {
+		t.Fatalf("POST want 200, got %d", code)
+	}
+	if f.method != http.MethodPost || f.path != "/v1/product" {
+		t.Fatalf("want POST /v1/product, got %s %s", f.method, f.path)
+	}
+	if f.body["name"] != "Tee" || f.body["sku"] != "TEE-1" {
+		t.Fatalf("write body must pass through verbatim, got %v", f.body)
+	}
+	if f.org != "acme" {
+		t.Fatalf("write must be scoped to the caller's org acme, got %q", f.org)
+	}
+
+	// deleteProduct: DELETE /v1/commerce/product/<id> → commerce /v1/product/<id>.
+	code, _ = callH(t, app, http.MethodDelete, "/v1/commerce/product/p_123", alice, "")
+	if code != http.StatusOK {
+		t.Fatalf("DELETE want 200, got %d", code)
+	}
+	if f.method != http.MethodDelete || f.path != "/v1/product/p_123" {
+		t.Fatalf("want DELETE /v1/product/p_123, got %s %s", f.method, f.path)
+	}
+}
+
+func TestCommerce_RefusesNonStoreHead(t *testing.T) {
+	f := &fakeStore{}
+	t.Setenv("COMMERCE_URL", f.server(t).URL)
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := mountApp(t, "http://iam.invalid", "", "")
+
+	// The bridge must NOT tunnel to commerce's money / tenant-admin surfaces: a
+	// /v1/commerce/billing/* or /v1/commerce/checkout/* is 404'd BEFORE any upstream
+	// call (billing has its OWN subject-scoped bridge; checkout is unreachable here).
+	for _, p := range []string{"/v1/commerce/billing/balance", "/v1/commerce/checkout/session", "/v1/commerce/namespace"} {
+		code, _ := callH(t, app, http.MethodGet, p, alice, "")
+		if code != http.StatusNotFound {
+			t.Fatalf("%s: want 404 (not a store endpoint), got %d", p, code)
+		}
+	}
+	if f.path != "" {
+		t.Fatalf("a refused head must never reach commerce, but upstream saw %q", f.path)
+	}
+}
+
+func TestCommerce_RejectsTraversalSegment(t *testing.T) {
+	f := &fakeStore{}
+	t.Setenv("COMMERCE_URL", f.server(t).URL)
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := mountApp(t, "http://iam.invalid", "", "")
+	// Every traversal form — literal `..`, encoded slash (`%2f`), encoded dot
+	// (`%2e%2e`) — must be REFUSED (400) and must NEVER reach commerce. Without the
+	// percent-escape rejection, `product/..%2fbilling` decodes downstream to
+	// `/v1/billing`, tunneling PAST the store-head allow-list into the money surface.
+	for _, p := range []string{
+		"/v1/commerce/product/../billing",
+		"/v1/commerce/product/..%2fbilling",
+		"/v1/commerce/%2e%2e/billing",
+	} {
+		code, _ := callH(t, app, http.MethodGet, p, alice, "")
+		if code != http.StatusBadRequest {
+			t.Fatalf("traversal %q: want 400, got %d", p, code)
+		}
+	}
+	if f.path != "" {
+		t.Fatalf("a traversal must never reach commerce, but upstream saw %q", f.path)
+	}
+}

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

@@ -0,0 +1,147 @@
+// 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
+// this server route probes it once and returns an honest verdict.
+//
+// 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
+//     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.
+//
+//   - SSRF SAFETY. The probe target is ALWAYS `<app>.<brand-domain>` where the brand
+//     is the deployment's OWN brand (deps.Brand, fixed at deploy) and app ∈
+//     {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 account
+
+import (
+	"context"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/hanzoai/cloud"
+	"github.com/zap-proto/zip"
+)
+
+// embedApps are the apps this route resolves and the in-app landing path each
+// embeds. Mirrors embed-probe.ts EMBED_APPS (verified ground truth).
+var embedApps = map[string]string{
+	"cms":  "/admin",    // Payload admin
+	"erp":  "/app",      // ERPNext desk
+	"help": "/helpdesk", // Frappe Helpdesk
+}
+
+// embedBrandDomains maps a deployment brand to the registrable domain its shared
+// apps live on. These are the app-hosting (`.cloud`) domains, DISTINCT from a
+// brand's marketing domain (brand.go's Domain) — lux apps are on lux.cloud, not
+// lux.network. Mirrors embed-probe.ts KNOWN_BRAND_DOMAINS/DEFAULT_BRAND_DOMAIN.
+var embedBrandDomains = map[string]string{
+	"hanzo": "hanzo.ai",
+	"lux":   "lux.cloud",
+	"zoo":   "zoo.cloud",
+	"pars":  "pars.cloud",
+}
+
+const defaultEmbedDomain = "hanzo.ai"
+
+// embedBrandDomain returns the app-hosting domain for a brand, defaulting to the
+// hanzo domain for an unknown brand (the SSRF-safe fallback).
+func embedBrandDomain(brand string) string {
+	if d, ok := embedBrandDomains[strings.ToLower(strings.TrimSpace(brand))]; ok {
+		return d
+	}
+	return defaultEmbedDomain
+}
+
+// embedUp classifies a probe HTTP status as "app is up": a 2xx/3xx (landing or SSO
+// redirect) or an app-level 401/403 (running, wants login) is up; 404 (no such app)
+// or any 5xx (the unprovisioned 502/503/504 state) is down. Mirrors embed-probe.ts
+// isUp. A network/timeout error is handled by the caller as down.
+func embedUp(status int) bool {
+	if status >= 500 || status == 404 {
+		return false
+	}
+	return status > 0
+}
+
+// embedStatusResp is the verdict the module reads. Mirrors the route.ts JSON.
+type embedStatusResp struct {
+	App       string `json:"app"`
+	Origin    string `json:"origin"`
+	EmbedURL  string `json:"embedUrl"`
+	Reachable bool   `json:"reachable"`
+	Entitled  bool   `json:"entitled"`
+	Phase     string `json:"phase"`
+}
+
+// reachProbe reports whether an embed origin answers "up". It is a package var so
+// the handler's entitlement + shaping logic is testable without a live network hop;
+// Mount uses the real, time-boxed probe.
+var reachProbe = liveReachProbe
+
+// embedStatus is GET /v1/embed-status?app=cms|erp|help. Mirrors
+// GET app/embed-status/route.ts.
+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")
+	}
+	app := strings.ToLower(strings.TrimSpace(c.Query("app")))
+	landing, known := embedApps[app]
+	if !known {
+		return zip.ErrBadRequest("unknown embed app")
+	}
+
+	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 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()
+	if !entitled {
+		return c.JSON(http.StatusOK, embedStatusResp{App: app, Origin: origin, EmbedURL: "", Reachable: false, Entitled: false, Phase: "not-entitled"})
+	}
+
+	up := reachProbe(c.Context(), origin)
+	phase := "not-provisioned"
+	if up {
+		phase = "ready"
+	}
+	return c.JSON(http.StatusOK, embedStatusResp{App: app, Origin: origin, EmbedURL: embedURL, Reachable: up, Entitled: true, Phase: phase})
+}
+
+// liveReachProbe does a time-boxed GET of the origin root. `redirect: manual` so an
+// SSO 302 counts as up (we don't follow it — only the liveness signal is needed). A
+// DNS failure / refused connection / timeout is down (app not provisioned yet).
+func liveReachProbe(ctx context.Context, origin string) bool {
+	cctx, cancel := context.WithTimeout(ctx, 4500*time.Millisecond)
+	defer cancel()
+	req, err := http.NewRequestWithContext(cctx, http.MethodGet, origin, nil)
+	if err != nil {
+		return false
+	}
+	req.Header.Set("Accept", "text/html")
+	resp, err := noRedirectClient.Do(req)
+	if err != nil {
+		return false
+	}
+	defer resp.Body.Close()
+	return embedUp(resp.StatusCode)
+}
+
+// noRedirectClient never follows a redirect — an SSO 302 is a liveness signal, not a
+// hop to chase (chasing it could itself become an SSRF vector).
+var noRedirectClient = &http.Client{
+	Timeout:       5 * time.Second,
+	CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse },
+}

clients/account/embed_test.go

@@ -0,0 +1,142 @@
+package account
+
+import (
+	"context"
+	"net/http"
+	"testing"
+
+	"github.com/zap-proto/zip"
+)
+
+// 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", "")
+	return mountBoth(t, brand)
+}
+
+// stubProbe swaps the reachability probe for the duration of a test, recording how
+// many times it ran (to prove a non-entitled caller is never probed).
+func stubProbe(t *testing.T, up bool) *int {
+	t.Helper()
+	calls := 0
+	prev := reachProbe
+	reachProbe = func(context.Context, string) bool { calls++; return up }
+	t.Cleanup(func() { reachProbe = prev })
+	return &calls
+}
+
+func TestEmbedStatus_RequiresValidatedPrincipal(t *testing.T) {
+	stubProbe(t, true)
+	app := mountBrand(t, "hanzo")
+	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)
+	}
+}
+
+func TestEmbedStatus_UnknownApp_400(t *testing.T) {
+	stubProbe(t, true)
+	app := mountBrand(t, "hanzo")
+	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)
+	}
+}
+
+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/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)
+	}
+	var r embedStatusResp
+	mustJSON(t, body, &r)
+	if !r.Entitled || !r.Reachable || r.Phase != "ready" {
+		t.Fatalf("entitled+reachable expected: %+v", r)
+	}
+	if r.Origin != "https://cms.hanzo.ai" || r.EmbedURL != "https://cms.hanzo.ai/admin" {
+		t.Fatalf("origin/embedUrl wrong: %+v", r)
+	}
+	if *calls != 1 {
+		t.Fatalf("entitled caller must be probed exactly once, got %d", *calls)
+	}
+}
+
+func TestEmbedStatus_SuperAdminEntitled(t *testing.T) {
+	stubProbe(t, false)
+	app := mountBrand(t, "hanzo")
+	// 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/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)
+	}
+	var r embedStatusResp
+	mustJSON(t, body, &r)
+	if !r.Entitled || r.Reachable || r.Phase != "not-provisioned" || r.EmbedURL != "https://erp.hanzo.ai/app" {
+		t.Fatalf("admin entitled + not-provisioned expected: %+v", r)
+	}
+}
+
+func TestEmbedStatus_CustomerOrgNotEntitled_NotProbed(t *testing.T) {
+	calls := stubProbe(t, true)
+	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/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)
+	}
+	var r embedStatusResp
+	mustJSON(t, body, &r)
+	if r.Entitled || r.Reachable || r.EmbedURL != "" || r.Phase != "not-entitled" {
+		t.Fatalf("customer must be not-entitled with no url: %+v", r)
+	}
+	if *calls != 0 {
+		t.Fatalf("a non-entitled caller must NEVER be probed, got %d probes", *calls)
+	}
+}
+
+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/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)
+	}
+	var r embedStatusResp
+	mustJSON(t, body, &r)
+	if r.Origin != "https://cms.lux.cloud" {
+		t.Fatalf("lux embed origin: want https://cms.lux.cloud, got %q", r.Origin)
+	}
+}
+
+func TestEmbedUp_Classification(t *testing.T) {
+	up := map[int]bool{200: true, 302: true, 401: true, 403: true, 404: false, 500: false, 502: false, 503: false, 0: false}
+	for status, want := range up {
+		if got := embedUp(status); got != want {
+			t.Fatalf("embedUp(%d): want %v, got %v", status, want, got)
+		}
+	}
+}
+
+func TestEmbedBrandDomain_Fallback(t *testing.T) {
+	if d := embedBrandDomain("zoo"); d != "zoo.cloud" {
+		t.Fatalf("zoo domain: want zoo.cloud, got %q", d)
+	}
+	if d := embedBrandDomain("unknown-brand"); d != defaultEmbedDomain {
+		t.Fatalf("unknown brand must fall back to %q, got %q", defaultEmbedDomain, d)
+	}
+}

clients/account/iam.go

@@ -0,0 +1,278 @@
+// 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 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 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`
+// creates a tenant and moves the user in. IAM authorizes them for an app that is
+// allow-listed (IAM_KEY_MINT_ALLOWED_APPS / IAM_ORG_ADMIN_APPS /
+// IAM_USER_ADMIN_APPS) — the `hanzo-console` client — NOT for an arbitrary user
+// bearer. So this client authenticates as that app (Basic id:secret) and always
+// targets the ALREADY-VALIDATED caller (the handler resolves the principal from
+// the gateway-minted X-User-Id/X-Org-Id before calling here); the caller can only
+// ever act on their OWN id, never a third party's.
+//
+// CREDENTIALS come from server-only env (IAM_MINT_CLIENT_ID / IAM_MINT_CLIENT_SECRET,
+// 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 account
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+	"time"
+)
+
+// defaultIAMBase is the in-cluster IAM service; overridable by IAM_URL for other
+// environments and by tests (an httptest.Server URL). Mirrors identity.ts's IAM_URL.
+const defaultIAMBase = "http://iam.hanzo.svc.cluster.local:8000"
+
+// iamMaxBody bounds an IAM response read — these are small JSON envelopes (a key,
+// a user row, an org row), never blobs.
+const iamMaxBody = 4 << 20
+
+// iamClient is the confidential-client caller. clientID/clientSecret authenticate
+// as the `hanzo-console` app; an empty pair means "not configured" (handlers 501).
+type iamClient struct {
+	base         string
+	clientID     string
+	clientSecret string
+	http         *http.Client
+}
+
+func newIAMClient() *iamClient {
+	base := strings.TrimRight(strings.TrimSpace(getenv("IAM_URL", defaultIAMBase)), "/")
+	return &iamClient{
+		base:         base,
+		clientID:     strings.TrimSpace(os.Getenv("IAM_MINT_CLIENT_ID")),
+		clientSecret: strings.TrimSpace(os.Getenv("IAM_MINT_CLIENT_SECRET")),
+		http:         &http.Client{Timeout: 15 * time.Second},
+	}
+}
+
+// configured reports whether the confidential client is wired. Handlers 501 when
+// false — the deployment simply lacks the `hanzo-console` credential (the honest
+// "not configured on this deployment" state, never a fabricated result).
+func (c *iamClient) configured() bool { return c != nil && c.clientID != "" && c.clientSecret != "" }
+
+// basicAuth is the client_secret_basic header for the confidential client.
+func (c *iamClient) basicAuth() string {
+	return "Basic " + basicToken(c.clientID, c.clientSecret)
+}
+
+// iamEnvelope is the uniform /v1/iam response shape ({status,msg,data}). A non-ok
+// status is an error surfaced honestly to the caller.
+type iamEnvelope struct {
+	Status string          `json:"status"`
+	Msg    string          `json:"msg"`
+	Data   json.RawMessage `json:"data"`
+}
+
+// do performs one authenticated IAM request and decodes the /v1 envelope. body is
+// an optional JSON payload (nil for GET/param-only POST). A 401/403 from IAM maps
+// to a distinct denied error; a non-envelope or non-ok status is an error with the
+// upstream msg. The response body is size-bounded and never logged (it may carry a
+// freshly-minted key).
+func (c *iamClient) do(ctx context.Context, method, path string, q url.Values, body []byte) (iamEnvelope, error) {
+	if !c.configured() {
+		return iamEnvelope{}, errNotConfigured
+	}
+	u := c.base + path
+	if enc := q.Encode(); enc != "" {
+		u += "?" + enc
+	}
+	var rdr io.Reader
+	if body != nil {
+		rdr = strings.NewReader(string(body))
+	}
+	req, err := http.NewRequestWithContext(ctx, method, u, rdr)
+	if err != nil {
+		return iamEnvelope{}, err
+	}
+	req.Header.Set("Authorization", c.basicAuth())
+	req.Header.Set("Accept", "application/json")
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return iamEnvelope{}, fmt.Errorf("iam unreachable: %w", err)
+	}
+	defer resp.Body.Close()
+	raw, err := io.ReadAll(io.LimitReader(resp.Body, iamMaxBody))
+	if err != nil {
+		return iamEnvelope{}, err
+	}
+	if resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden {
+		return iamEnvelope{}, fmt.Errorf("iam denied (%d)", resp.StatusCode)
+	}
+	var env iamEnvelope
+	if err := json.Unmarshal(raw, &env); err != nil {
+		return iamEnvelope{}, fmt.Errorf("iam non-envelope response (%d)", resp.StatusCode)
+	}
+	if env.Status != "ok" {
+		msg := env.Msg
+		if msg == "" {
+			msg = fmt.Sprintf("iam status %d", resp.StatusCode)
+		}
+		return iamEnvelope{}, fmt.Errorf("iam: %s", msg)
+	}
+	return env, nil
+}
+
+// ── the `hk-` Cloud API key (per-user) ───────────────────────────────────────
+
+// userKey is the subset of an IAM user row the key surface reads: the `hk-` access
+// key and the last time the key row changed (updatedTime).
+type userKey struct {
+	AccessKey   string `json:"accessKey"`
+	UpdatedTime string `json:"updatedTime"`
+}
+
+// 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
+// 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) {
+	env, err := c.do(ctx, http.MethodGet, "/v1/iam/get-user", url.Values{"id": {id}}, nil)
+	if err != nil {
+		return userKey{}, err
+	}
+	var u userKey
+	if err := json.Unmarshal(env.Data, &u); err != nil {
+		return userKey{}, fmt.Errorf("iam get-user: decode: %w", err)
+	}
+	return u, nil
+}
+
+// mintUserKey (re)generates the user's `hk-` key and returns the new secret — shown
+// ONCE to the caller (POST /keys), never echoed again. IAM binds the key to `id`,
+// so a caller can only ever mint their OWN.
+func (c *iamClient) mintUserKey(ctx context.Context, id string) (string, error) {
+	env, err := c.do(ctx, http.MethodPost, "/v1/iam/mint-user-keys", url.Values{"id": {id}}, nil)
+	if err != nil {
+		return "", err
+	}
+	var out struct {
+		AccessKey string `json:"accessKey"`
+	}
+	if err := json.Unmarshal(env.Data, &out); err != nil {
+		return "", fmt.Errorf("iam mint-user-keys: decode: %w", err)
+	}
+	if out.AccessKey == "" {
+		return "", fmt.Errorf("iam did not return an access key")
+	}
+	return out.AccessKey, nil
+}
+
+// revokeUserKey clears the user's `hk-` key (immediate revoke; the gateway key
+// cache lapses within ~5m).
+func (c *iamClient) revokeUserKey(ctx context.Context, id string) error {
+	_, err := c.do(ctx, http.MethodPost, "/v1/iam/revoke-user-keys", url.Values{"id": {id}}, nil)
+	return err
+}
+
+// ── organizations (onboarding) ───────────────────────────────────────────────
+
+// iamOrg is the subset of an IAM organization the onboarding surface reads/clones:
+// password + locale settings, so a created org is well-formed and a moved user's
+// login is unaffected.
+type iamOrg struct {
+	Owner                  string   `json:"owner"`
+	Name                   string   `json:"name"`
+	DisplayName            string   `json:"displayName"`
+	PasswordType           string   `json:"passwordType,omitempty"`
+	PasswordSalt           string   `json:"passwordSalt,omitempty"`
+	PasswordObfuscatorType string   `json:"passwordObfuscatorType,omitempty"`
+	PasswordObfuscatorKey  string   `json:"passwordObfuscatorKey,omitempty"`
+	PasswordOptions        []string `json:"passwordOptions,omitempty"`
+	CountryCodes           []string `json:"countryCodes,omitempty"`
+	Languages              []string `json:"languages,omitempty"`
+	DefaultAvatar          string   `json:"defaultAvatar,omitempty"`
+	IsPersonal             bool     `json:"isPersonal,omitempty"`
+	CreatedTime            string   `json:"createdTime,omitempty"`
+}
+
+// getOrganization reads an org (owned by the `admin` org) by slug; (nil,nil) when
+// absent so a caller can test availability. A transport error (unreachable IAM)
+// propagates so onboarding never mistakes "unreachable" for "available" and creates
+// a duplicate.
+func (c *iamClient) getOrganization(ctx context.Context, slug string) (*iamOrg, error) {
+	env, err := c.do(ctx, http.MethodGet, "/v1/iam/get-organization", url.Values{"id": {adminOrg + "/" + slug}}, nil)
+	if err != nil {
+		// IAM returns status!=ok / empty data for a missing org; do() maps a not-ok
+		// envelope to an "iam:" error — that means the org does not exist. A transport
+		// failure ("iam unreachable"/"iam denied") is a real error and propagates.
+		if strings.HasPrefix(err.Error(), "iam:") {
+			return nil, nil
+		}
+		return nil, err
+	}
+	if len(env.Data) == 0 || string(env.Data) == "null" {
+		return nil, nil
+	}
+	var o iamOrg
+	if err := json.Unmarshal(env.Data, &o); err != nil {
+		return nil, fmt.Errorf("iam get-organization: decode: %w", err)
+	}
+	return &o, nil
+}
+
+// createOrganization creates a customer org owned by the `admin` org, cloning
+// password + locale settings from the caller's current org (so the org is
+// well-formed and a moved user's login is unaffected). Mirrors identity.ts's
+// createOrganization.
+func (c *iamClient) createOrganization(ctx context.Context, o iamOrg) error {
+	body, err := json.Marshal(o)
+	if err != nil {
+		return err
+	}
+	_, err = c.do(ctx, http.MethodPost, "/v1/iam/add-organization", nil, body)
+	return err
+}
+
+// getUser reads a full user row (for the move: update-user re-submits it whole).
+func (c *iamClient) getUser(ctx context.Context, id string) (json.RawMessage, error) {
+	env, err := c.do(ctx, http.MethodGet, "/v1/iam/get-user", url.Values{"id": {id}}, nil)
+	if err != nil {
+		return nil, err
+	}
+	if len(env.Data) == 0 || string(env.Data) == "null" {
+		return nil, errNotFound
+	}
+	return env.Data, nil
+}
+
+// moveUserToOrg makes the zero-org user an admin of `slug`: it re-submits the user
+// row with owner=slug + isAdmin=true (update-user takes the whole row). The user's
+// password travels with the row (IAM verifies against user.PasswordType first), so
+// the move never locks them out. `id` is the caller's CURRENT `<owner>/<name>`.
+func (c *iamClient) moveUserToOrg(ctx context.Context, id, slug string) error {
+	rowRaw, err := c.getUser(ctx, id)
+	if err != nil {
+		return err
+	}
+	var row map[string]any
+	if err := json.Unmarshal(rowRaw, &row); err != nil {
+		return fmt.Errorf("iam get-user: decode: %w", err)
+	}
+	row["owner"] = slug
+	row["isAdmin"] = true
+	body, err := json.Marshal(row)
+	if err != nil {
+		return err
+	}
+	// update-user is keyed by the ORIGINAL id (the row's current owner/name).
+	_, err = c.do(ctx, http.MethodPost, "/v1/iam/update-user", url.Values{"id": {id}}, body)
+	return err
+}

clients/account/onboarding.go

@@ -0,0 +1,98 @@
+// onboarding.go — PURE org-naming + reserved-name policy, no transport/IAM. A
+// 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:
+//
+//   - NAMING: turn a human org name (or a username) into a valid IAM org slug —
+//     lowercase, [a-z0-9-], collapsed, trimmed, bounded.
+//   - RESERVED: refuse names that must never become a customer org — IAM system
+//     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 account
+
+import "strings"
+
+// reservedOrgs are brand/staff orgs + IAM system owners — never a customer org.
+// Matches onboarding.ts RESERVED_ORGS exactly (kept as a set for O(1) lookup).
+var reservedOrgs = map[string]bool{
+	// IAM system owners
+	"admin":    true,
+	"built-in": true,
+	"app":      true,
+	// brand/staff orgs (the OrgGate sends these to the admin host)
+	"hanzo": true,
+	"lux":   true,
+	"zoo":   true,
+	"pars":  true,
+}
+
+const (
+	// maxOrgSlug bounds a slug (IAM org name is varchar(100); keep it short/readable).
+	maxOrgSlug = 60
+	// minOrgSlug is the minimum length after normalization.
+	minOrgSlug = 2
+)
+
+// slugifyOrg normalizes a human name to an IAM org slug: lowercase ASCII, runs of
+// non-alphanumerics → '-', collapse repeats, trim leading/trailing '-', cap at
+// maxOrgSlug (re-trimming a trailing '-' the slice may reveal). Returns "" when the
+// input has no usable characters. Mirrors onboarding.ts slugifyOrg (Go has no NFKD
+// normalize in std without golang.org/x/text; ASCII inputs — the real org-name
+// case — are handled identically, and any non-ASCII rune is treated as a separator,
+// which is the same net effect NFKD+[^a-z0-9] produces for the slug).
+func slugifyOrg(input string) string {
+	var b strings.Builder
+	prevDash := false
+	for _, r := range strings.ToLower(input) {
+		if (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') {
+			b.WriteRune(r)
+			prevDash = false
+		} else if !prevDash {
+			b.WriteByte('-')
+			prevDash = true
+		}
+	}
+	out := strings.Trim(b.String(), "-")
+	if len(out) > maxOrgSlug {
+		out = strings.TrimRight(out[:maxOrgSlug], "-")
+	}
+	return out
+}
+
+// personalOrgSlug is the default personal-org slug for a user. An email-like
+// username collapses to its local part (dave@x.com → dave) so a personal org reads
+// as the person, not their address; everything else is slugified as-is.
+func personalOrgSlug(username string) string {
+	base := username
+	if at := strings.IndexByte(username, '@'); at > 0 {
+		base = username[:at]
+	}
+	return slugifyOrg(base)
+}
+
+// isReservedOrg reports whether a slug is a brand/staff or system org — never
+// creatable.
+func isReservedOrg(slug string) bool { return reservedOrgs[slug] }
+
+// orgNameResult is the outcome of validating a requested org name: a creatable slug
+// or an honest client-facing error.
+type orgNameResult struct {
+	ok    bool
+	slug  string
+	error string
+}
+
+// validateOrgName validates + normalizes a requested org name into a creatable
+// slug, or an honest error. The ONE place the create rules live (handler + tests
+// share it). Mirrors onboarding.ts validateOrgName.
+func validateOrgName(input string) orgNameResult {
+	slug := slugifyOrg(input)
+	if len(slug) < minOrgSlug {
+		return orgNameResult{ok: false, error: "Use at least 2 letters or numbers."}
+	}
+	if isReservedOrg(slug) {
+		return orgNameResult{ok: false, error: "“" + slug + "” is reserved. Choose a different name."}
+	}
+	return orgNameResult{ok: true, slug: slug}
+}

clients/account/onboarding_test.go

@@ -0,0 +1,84 @@
+package account
+
+import "testing"
+
+func TestSlugifyOrg(t *testing.T) {
+	cases := map[string]string{
+		"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",
+	}
+	for in, want := range cases {
+		if got := slugifyOrg(in); got != want {
+			t.Errorf("slugifyOrg(%q) = %q, want %q", in, got, want)
+		}
+	}
+	// A name longer than the cap is truncated and re-trimmed (no trailing dash).
+	long := "this-is-a-very-long-organization-name-that-exceeds-the-sixty-character-cap-easily"
+	got := slugifyOrg(long)
+	if len(got) > maxOrgSlug {
+		t.Errorf("slugifyOrg over-cap: len=%d > %d (%q)", len(got), maxOrgSlug, got)
+	}
+	if got != "" && got[len(got)-1] == '-' {
+		t.Errorf("slugifyOrg left a trailing dash after slice: %q", got)
+	}
+}
+
+func TestValidateOrgName(t *testing.T) {
+	if v := validateOrgName("a"); v.ok {
+		t.Errorf("single char should be rejected (min %d): %+v", minOrgSlug, v)
+	}
+	if v := validateOrgName("!!"); v.ok {
+		t.Errorf("no-usable-chars should be rejected: %+v", v)
+	}
+	for _, reserved := range []string{"admin", "Hanzo", "built-in", "lux", "zoo", "pars", "app"} {
+		if v := validateOrgName(reserved); v.ok {
+			t.Errorf("reserved %q should be rejected: %+v", reserved, v)
+		}
+	}
+	v := validateOrgName("Cool Team")
+	if !v.ok || v.slug != "cool-team" {
+		t.Errorf("valid name: want ok cool-team, got %+v", v)
+	}
+}
+
+func TestPersonalOrgSlug(t *testing.T) {
+	cases := map[string]string{
+		"dave@example.com": "dave",
+		"Alice.Smith":      "alice-smith",
+		"bob":              "bob",
+		"@leading":         "-leading"[1:], // slugified: "leading"
+	}
+	for in, want := range cases {
+		if got := personalOrgSlug(in); got != want {
+			t.Errorf("personalOrgSlug(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestHumanize(t *testing.T) {
+	cases := map[string]string{
+		"dave.smith@x.com": "Dave Smith",
+		"alice":            "Alice",
+		"bob_jones":        "Bob Jones",
+		"@":                "Personal",
+	}
+	for in, want := range cases {
+		if got := humanize(in); got != want {
+			t.Errorf("humanize(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestIsReservedOrg(t *testing.T) {
+	if !isReservedOrg("admin") || !isReservedOrg("hanzo") {
+		t.Fatal("admin/hanzo must be reserved")
+	}
+	if isReservedOrg("acme") {
+		t.Fatal("acme must not be reserved")
+	}
+}

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

@@ -0,0 +1,373 @@
+// 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),
+// derives USD cents from the (18-decimal, USD-pegged) on-chain value, records it to
+// commerce as an `husd` crypto payment, and returns the credited amount + balance.
+//
+// THE CREDITED AMOUNT IS THE ON-CHAIN VALUE, never a client number — which is exactly
+// why this MUST be a server handler and cannot collapse to a same-origin call. Two
+// hardenings over the Node route:
+//
+//   - IDOR-safe: the credit lands on the VALIDATED caller's own org/user (the
+//     gateway-verified X-Org-Id/X-User-Id), never a client-supplied `userId`.
+//   - S2S to commerce: recorded with the admin COMMERCE_SERVICE_TOKEN + the caller's
+//     X-Org-Id (the same service-to-service pattern clients/admin reads balances on),
+//     not by forwarding a browser cookie.
+//
+// The EVM receipt is read over plain JSON-RPC (eth_getTransactionReceipt) — one
+// well-known call + one well-known event, so the stdlib is sufficient and no EVM
+// client dependency is pulled in.
+//
+// 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 account
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"math/big"
+	"net/http"
+	"net/url"
+	"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).
+const transferTopic = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
+
+// husdCentDivisor: HUSD is an 18-decimal, USD-pegged stablecoin, so 1e16 base units
+// = 1 cent. Mirrors route.ts's `value / 10n ** 16n`.
+var husdCentDivisor = new(big.Int).Exp(big.NewInt(10), big.NewInt(16), nil)
+
+var (
+	addrRe   = regexp.MustCompile(`^0x[0-9a-fA-F]{40}$`)
+	txHashRe = regexp.MustCompile(`^0x[0-9a-fA-F]{64}$`)
+)
+
+func isAddr(a string) bool { return addrRe.MatchString(a) }
+
+// topupConfig is the deployment's HUSD + commerce wiring, resolved from server-only
+// env (sourced from KMS by the deployment, never a browser value).
+type topupConfig struct {
+	husd     string // HUSD ERC-20 contract address
+	treasury string // the top-up treasury address
+	rpcURL   string // Hanzo EVM JSON-RPC endpoint
+	chainID  int64
+	commerce string // commerce base (e.g. http://commerce.hanzo.svc.cluster.local:8001)
+	token    string // admin S2S bearer for commerce (COMMERCE_SERVICE_TOKEN; never logged)
+}
+
+func loadTopupConfig() topupConfig {
+	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()
+		}
+	}
+	return topupConfig{
+		husd:     strings.TrimSpace(os.Getenv("HANZO_HUSD_ADDRESS")),
+		treasury: strings.TrimSpace(os.Getenv("HANZO_HUSD_TREASURY")),
+		rpcURL:   strings.TrimRight(getenv("HANZO_RPC_URL", "https://rpc.hanzo.network"), "/"),
+		chainID:  chainID,
+		commerce: strings.TrimRight(getenv("COMMERCE_URL", "https://api.hanzo.ai"), "/"),
+		token:    strings.TrimSpace(os.Getenv("COMMERCE_SERVICE_TOKEN")),
+	}
+}
+
+// configured reports whether the greenfield gate is satisfied — a valid HUSD contract
+// AND treasury. Until HUSD is deployed both are unset and the surface is honestly 501.
+func (t topupConfig) configured() bool { return isAddr(t.husd) && isAddr(t.treasury) }
+
+type walletTopupReq struct {
+	TxHash      string `json:"txHash"`
+	FromAddress string `json:"fromAddress"`
+	// A client-supplied `userId` is intentionally NOT read — the credit lands on the
+	// validated caller (no IDOR).
+}
+
+type walletTopupResp struct {
+	CreditedCents int64  `json:"creditedCents"`
+	Balance       int64  `json:"balance"`
+	TxHash        string `json:"txHash"`
+	Status        string `json:"status"`
+}
+
+// walletTopup verifies a sent HUSD transfer on-chain and credits the caller's org.
+// Mirrors POST app/billing/v1/topup/wallet/route.ts.
+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() {
+		return zip.Errorf(http.StatusNotImplemented, "HUSD top-up is not configured yet (HUSD is not deployed on Hanzo Mainnet)")
+	}
+
+	// The credit lands on the VALIDATED caller's own org (X-Org-Id) — require it.
+	cr, ok := resolveCaller(c, true)
+	if !ok {
+		return zip.ErrForbidden("sign in to top up your balance")
+	}
+
+	var body walletTopupReq
+	if err := c.Bind(&body); err != nil {
+		return zip.ErrBadRequest("invalid JSON body")
+	}
+	txHash := strings.TrimSpace(body.TxHash)
+	if !txHashRe.MatchString(txHash) {
+		return zip.ErrBadRequest("a valid transaction hash is required")
+	}
+
+	// ── 1. Verify the HUSD transfer on-chain ─────────────────────────────────────
+	cents, verifiedFrom, herr := verifyHusdTransfer(c.Context(), cfg, txHash, strings.TrimSpace(body.FromAddress))
+	if herr != nil {
+		return herr
+	}
+
+	// ── 2. Record to commerce as an HUSD crypto payment (S2S) ────────────────────
+	status, herr := recordHusdPayment(c.Context(), cfg, cr, txHash, verifiedFrom, cents)
+	if herr != nil {
+		return herr
+	}
+
+	// New USD-ledger balance — best-effort; the credit already landed.
+	balance := commerceBalanceCents(c.Context(), cfg, cr)
+
+	return c.JSON(http.StatusOK, walletTopupResp{CreditedCents: cents, Balance: balance, TxHash: txHash, Status: status})
+}
+
+// ── on-chain verification (plain JSON-RPC) ───────────────────────────────────────
+
+// rpcReceipt is the subset of an eth_getTransactionReceipt result we read.
+type rpcReceipt struct {
+	Status string   `json:"status"` // "0x1" success, "0x0" failed
+	Logs   []rpcLog `json:"logs"`
+}
+
+type rpcLog struct {
+	Address string   `json:"address"`
+	Topics  []string `json:"topics"`
+	Data    string   `json:"data"`
+}
+
+// verifyHusdTransfer reads the receipt and confirms exactly one mined, successful
+// HUSD Transfer to the treasury, returning the credited cents and the sender. Any
+// non-conforming tx is an honest 400; an unreachable chain is a 502.
+func verifyHusdTransfer(ctx context.Context, cfg topupConfig, txHash, wantFrom string) (int64, string, error) {
+	rcpt, err := getReceipt(ctx, cfg.rpcURL, txHash)
+	if err != nil {
+		return 0, "", zip.Errorf(http.StatusBadGateway, "could not verify the transaction on Hanzo Mainnet: %v", err)
+	}
+	if rcpt == nil {
+		return 0, "", zip.ErrBadRequest("transaction not found or not yet mined")
+	}
+	if strings.ToLower(rcpt.Status) != "0x1" {
+		return 0, "", zip.ErrBadRequest("transaction failed on-chain")
+	}
+
+	husd := strings.ToLower(cfg.husd)
+	treasuryTopic := addrToTopic(cfg.treasury)
+	for _, lg := range rcpt.Logs {
+		if strings.ToLower(lg.Address) != husd {
+			continue
+		}
+		if len(lg.Topics) < 3 || strings.ToLower(lg.Topics[0]) != transferTopic {
+			continue
+		}
+		if strings.ToLower(lg.Topics[2]) != treasuryTopic { // indexed `to`
+			continue
+		}
+		value, ok := new(big.Int).SetString(strings.TrimPrefix(lg.Data, "0x"), 16)
+		if !ok {
+			continue
+		}
+		cents := new(big.Int).Div(value, husdCentDivisor)
+		if cents.Sign() <= 0 || !cents.IsInt64() {
+			return 0, "", zip.ErrBadRequest("transferred amount is below the minimum (1 cent)")
+		}
+		from := topicToAddr(lg.Topics[1]) // indexed `from`
+		if wantFrom != "" && isAddr(wantFrom) && !strings.EqualFold(from, wantFrom) {
+			return 0, "", zip.ErrBadRequest("transfer sender does not match the connected wallet")
+		}
+		return cents.Int64(), from, nil
+	}
+	return 0, "", zip.ErrBadRequest("no HUSD transfer to the treasury was found in this transaction")
+}
+
+// getReceipt calls eth_getTransactionReceipt over JSON-RPC. A null result (not mined)
+// returns (nil,nil); a transport / RPC error propagates.
+func getReceipt(ctx context.Context, rpcURL, txHash string) (*rpcReceipt, error) {
+	reqBody, _ := json.Marshal(map[string]any{
+		"jsonrpc": "2.0", "id": 1, "method": "eth_getTransactionReceipt", "params": []string{txHash},
+	})
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, rpcURL, bytes.NewReader(reqBody))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Accept", "application/json")
+	resp, err := httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("rpc unreachable: %w", err)
+	}
+	defer resp.Body.Close()
+	raw, err := io.ReadAll(io.LimitReader(resp.Body, 4<<20))
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return nil, fmt.Errorf("rpc status %d", resp.StatusCode)
+	}
+	var env struct {
+		Result *rpcReceipt `json:"result"`
+		Error  *struct {
+			Message string `json:"message"`
+		} `json:"error"`
+	}
+	if err := json.Unmarshal(raw, &env); err != nil {
+		return nil, fmt.Errorf("rpc decode: %w", err)
+	}
+	if env.Error != nil {
+		return nil, fmt.Errorf("rpc error: %s", env.Error.Message)
+	}
+	return env.Result, nil // Result==nil ⇒ not found / not yet mined
+}
+
+// addrToTopic left-pads a 20-byte address to a 32-byte indexed topic (lowercase).
+func addrToTopic(addr string) string {
+	h := strings.ToLower(strings.TrimPrefix(addr, "0x"))
+	return "0x" + strings.Repeat("0", 64-len(h)) + h
+}
+
+// topicToAddr extracts the 20-byte address from a 32-byte indexed topic (lowercase,
+// 0x-prefixed).
+func topicToAddr(topic string) string {
+	h := strings.TrimPrefix(topic, "0x")
+	if len(h) < 40 {
+		return "0x" + h
+	}
+	return "0x" + h[len(h)-40:]
+}
+
+// ── commerce (S2S) ───────────────────────────────────────────────────────────────
+
+// recordHusdPayment records the verified credit to commerce as an `husd` crypto
+// payment, scoped to the caller's org via the S2S service token + X-Org-Id.
+func recordHusdPayment(ctx context.Context, cfg topupConfig, cr caller, txHash, from string, cents int64) (string, error) {
+	payload, _ := json.Marshal(map[string]any{
+		"method":      "crypto",
+		"network":     "hanzo",
+		"chainId":     cfg.chainID,
+		"currency":    "husd",
+		"amount":      cents,
+		"txHash":      txHash,
+		"fromAddress": from,
+		"toAddress":   cfg.treasury,
+		"userId":      cr.id, // the VALIDATED caller — never a client-supplied id
+	})
+	raw, status, err := commerceDo(ctx, cfg.commerce, cfg.token, http.MethodPost, "/v1/billing/payment", nil, cr.owner, payload)
+	if err != nil {
+		return "", zip.Errorf(http.StatusBadGateway, "could not reach commerce to record the payment: %v", err)
+	}
+	if status < 200 || status >= 300 {
+		return "", zip.Errorf(http.StatusBadGateway, "commerce rejected the payment (HTTP %d): %s", status, strings.TrimSpace(string(raw)))
+	}
+	var out struct {
+		Status string `json:"status"`
+	}
+	_ = json.Unmarshal(raw, &out)
+	if out.Status == "" {
+		out.Status = "recorded"
+	}
+	return out.Status, nil
+}
+
+// commerceBalanceCents reads the caller's USD-ledger balance (cents). Best-effort:
+// the credit is already recorded, so a read error degrades to 0, not a failure.
+func commerceBalanceCents(ctx context.Context, cfg topupConfig, cr caller) int64 {
+	q := url.Values{"user": {cr.id}, "currency": {"usd"}}
+	raw, status, err := commerceDo(ctx, cfg.commerce, cfg.token, http.MethodGet, "/v1/billing/balance", q, cr.owner, nil)
+	if err != nil || status < 200 || status >= 300 {
+		return 0
+	}
+	var b struct {
+		Balance   int64 `json:"balance"`
+		Available int64 `json:"available"`
+	}
+	if err := json.Unmarshal(raw, &b); err != nil {
+		return 0
+	}
+	if b.Balance != 0 {
+		return b.Balance
+	}
+	return b.Available
+}
+
+// commerceDo performs one S2S commerce request: admin bearer + X-Org-Id (commerce's
+// EdgeAuth trusts the org header ONLY behind the service token). Returns the raw
+// body + status. Mirrors clients/admin/commerce.go's auth. Takes (base, token) rather
+// than the HUSD topupConfig so both the wallet top-up AND the /v1/billing/* data bridge
+// (billing.go) share this ONE S2S transport.
+func commerceDo(ctx context.Context, base, token, method, path string, q url.Values, org string, body []byte) ([]byte, int, error) {
+	if base == "" {
+		return nil, 0, fmt.Errorf("commerce not configured")
+	}
+	u := base + path
+	if enc := q.Encode(); enc != "" {
+		u += "?" + enc
+	}
+	var rdr io.Reader
+	if body != nil {
+		rdr = bytes.NewReader(body)
+	}
+	req, err := http.NewRequestWithContext(ctx, method, u, rdr)
+	if err != nil {
+		return nil, 0, err
+	}
+	req.Header.Set("Accept", "application/json")
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	if token != "" {
+		req.Header.Set("Authorization", "Bearer "+token)
+	}
+	if org != "" {
+		req.Header.Set("X-Org-Id", org)
+	}
+	resp, err := commerceHTTP.Do(req)
+	if err != nil {
+		return nil, 0, fmt.Errorf("commerce unreachable: %w", err)
+	}
+	defer resp.Body.Close()
+	raw, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return nil, resp.StatusCode, err
+	}
+	return raw, resp.StatusCode, nil
+}

clients/account/topup_test.go

@@ -0,0 +1,241 @@
+package account
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"math/big"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+)
+
+const (
+	tHusd     = "0x1111111111111111111111111111111111111111"
+	tTreasury = "0x2222222222222222222222222222222222222222"
+	tSender   = "0x3333333333333333333333333333333333333333"
+	tOther    = "0x4444444444444444444444444444444444444444"
+	tTxHash   = "0xabc0000000000000000000000000000000000000000000000000000000000001"
+)
+
+// fakeRPC is a minimal eth JSON-RPC node: it returns a settable `result` for
+// eth_getTransactionReceipt (nil ⇒ null ⇒ not mined) and records the tx it was asked.
+type fakeRPC struct {
+	mu     sync.Mutex
+	result any
+	gotTx  string
+}
+
+func (f *fakeRPC) server(t *testing.T) *httptest.Server {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var req struct {
+			Params []string `json:"params"`
+		}
+		raw, _ := io.ReadAll(r.Body)
+		_ = json.Unmarshal(raw, &req)
+		f.mu.Lock()
+		if len(req.Params) > 0 {
+			f.gotTx = req.Params[0]
+		}
+		res := f.result
+		f.mu.Unlock()
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{"jsonrpc": "2.0", "id": 1, "result": res})
+	}))
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+// fakeCommerce records the S2S payment record + balance reads.
+type fakeCommerce struct {
+	mu      sync.Mutex
+	payment map[string]any
+	gotOrg  string
+	gotAuth string
+	balance int64
+}
+
+func (f *fakeCommerce) server(t *testing.T) *httptest.Server {
+	t.Helper()
+	mux := http.NewServeMux()
+	mux.HandleFunc("/v1/billing/payment", func(w http.ResponseWriter, r *http.Request) {
+		raw, _ := io.ReadAll(r.Body)
+		var p map[string]any
+		_ = json.Unmarshal(raw, &p)
+		f.mu.Lock()
+		f.payment, f.gotOrg, f.gotAuth = p, r.Header.Get("X-Org-Id"), r.Header.Get("Authorization")
+		f.mu.Unlock()
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"status":"paid"}`)
+	})
+	mux.HandleFunc("/v1/billing/balance", func(w http.ResponseWriter, r *http.Request) {
+		f.mu.Lock()
+		bal := f.balance
+		f.mu.Unlock()
+		_ = json.NewEncoder(w).Encode(map[string]any{"balance": bal})
+	})
+	srv := httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+// husdReceipt builds a receipt carrying one HUSD Transfer(from→to, cents*1e16).
+func husdReceipt(status, husd, from, to string, cents int64) map[string]any {
+	value := new(big.Int).Mul(big.NewInt(cents), husdCentDivisor)
+	return map[string]any{
+		"status": status,
+		"logs": []any{map[string]any{
+			"address": husd,
+			"topics":  []any{transferTopic, addrToTopic(from), addrToTopic(to)},
+			"data":    "0x" + fmt.Sprintf("%064x", value),
+		}},
+	}
+}
+
+func setTopupEnv(t *testing.T, husd, treasury, rpcURL, commerceURL string) {
+	t.Helper()
+	t.Setenv("HANZO_HUSD_ADDRESS", husd)
+	t.Setenv("HANZO_HUSD_TREASURY", treasury)
+	t.Setenv("HANZO_RPC_URL", rpcURL)
+	t.Setenv("COMMERCE_URL", commerceURL)
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-token")
+}
+
+// principal for a signed-in caller in org acme.
+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/commerce/topup/wallet", alice, `{"txHash":"`+tTxHash+`"}`)
+	if code != http.StatusNotImplemented {
+		t.Fatalf("HUSD unconfigured: want 501, got %d", code)
+	}
+}
+
+func TestTopup_RequiresValidatedPrincipal(t *testing.T) {
+	rpc := &fakeRPC{}
+	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/commerce/topup/wallet", nil, `{"txHash":"`+tTxHash+`"}`)
+	if code != http.StatusForbidden {
+		t.Fatalf("no principal: want 403, got %d", code)
+	}
+}
+
+func TestTopup_BadTxHash_400(t *testing.T) {
+	rpc := &fakeRPC{}
+	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/commerce/topup/wallet", alice, `{"txHash":"0xnothex"}`)
+	if code != http.StatusBadRequest {
+		t.Fatalf("bad txHash: want 400, got %d", code)
+	}
+}
+
+func TestTopup_HappyPath_VerifiesAndCredits(t *testing.T) {
+	rpc := &fakeRPC{result: husdReceipt("0x1", tHusd, tSender, tTreasury, 500)}
+	com := &fakeCommerce{balance: 1200}
+	setTopupEnv(t, tHusd, tTreasury, rpc.server(t).URL, com.server(t).URL)
+	app := mountBrand(t, "hanzo")
+
+	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)
+	}
+	var r walletTopupResp
+	mustJSON(t, body, &r)
+	if r.CreditedCents != 500 || r.Balance != 1200 || r.Status != "paid" || r.TxHash != tTxHash {
+		t.Fatalf("topup result wrong: %+v", r)
+	}
+	// Commerce recorded the on-chain amount (500), scoped S2S to the caller's org, on
+	// the caller's own subject, with the service bearer.
+	if com.gotOrg != "acme" || com.gotAuth != "Bearer svc-token" {
+		t.Fatalf("commerce S2S auth wrong: org=%q auth=%q", com.gotOrg, com.gotAuth)
+	}
+	if com.payment["userId"] != "acme/alice" {
+		t.Fatalf("credit must target the validated caller acme/alice, got %v", com.payment["userId"])
+	}
+	if amt, _ := com.payment["amount"].(float64); amt != 500 {
+		t.Fatalf("recorded amount must be the on-chain 500 cents, got %v", com.payment["amount"])
+	}
+	if com.payment["currency"] != "husd" {
+		t.Fatalf("currency must be husd, got %v", com.payment["currency"])
+	}
+	if rpc.gotTx != tTxHash {
+		t.Fatalf("rpc should have been asked for %s, got %s", tTxHash, rpc.gotTx)
+	}
+}
+
+func TestTopup_IDOR_CreditsCallerNotBodyUserId(t *testing.T) {
+	rpc := &fakeRPC{result: husdReceipt("0x1", tHusd, tSender, tTreasury, 100)}
+	com := &fakeCommerce{}
+	setTopupEnv(t, tHusd, tTreasury, rpc.server(t).URL, com.server(t).URL)
+	app := mountBrand(t, "hanzo")
+
+	// 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/commerce/topup/wallet", alice,
+		`{"txHash":"`+tTxHash+`","userId":"victim/root"}`)
+	if code != http.StatusOK {
+		t.Fatalf("topup: want 200, got %d", code)
+	}
+	if com.payment["userId"] != "acme/alice" || com.gotOrg != "acme" {
+		t.Fatalf("IDOR: credit must land on acme/alice, got userId=%v org=%q", com.payment["userId"], com.gotOrg)
+	}
+}
+
+func TestTopup_NotMined_400(t *testing.T) {
+	rpc := &fakeRPC{result: nil} // JSON-RPC null ⇒ not found / not mined
+	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/commerce/topup/wallet", alice, `{"txHash":"`+tTxHash+`"}`)
+	if code != http.StatusBadRequest {
+		t.Fatalf("not mined: want 400, got %d", code)
+	}
+	if com.payment != nil {
+		t.Fatalf("commerce must not be called for an unmined tx")
+	}
+}
+
+func TestTopup_FailedTx_400(t *testing.T) {
+	rpc := &fakeRPC{result: husdReceipt("0x0", tHusd, tSender, tTreasury, 500)} // reverted
+	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/commerce/topup/wallet", alice, `{"txHash":"`+tTxHash+`"}`)
+	if code != http.StatusBadRequest {
+		t.Fatalf("failed tx: want 400, got %d", code)
+	}
+}
+
+func TestTopup_NoTransferToTreasury_400(t *testing.T) {
+	// A valid HUSD transfer, but to some OTHER address (not the treasury) → rejected.
+	rpc := &fakeRPC{result: husdReceipt("0x1", tHusd, tSender, tOther, 500)}
+	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/commerce/topup/wallet", alice, `{"txHash":"`+tTxHash+`"}`)
+	if code != http.StatusBadRequest {
+		t.Fatalf("non-treasury transfer: want 400, got %d", code)
+	}
+}
+
+func TestTopup_SenderMismatch_400(t *testing.T) {
+	rpc := &fakeRPC{result: husdReceipt("0x1", tHusd, tSender, tTreasury, 500)}
+	com := &fakeCommerce{}
+	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/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,153 +30,152 @@ 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/invoices"
+	"github.com/hanzoai/cloud/clients/admin/metrics"
+	"github.com/hanzoai/cloud/clients/admin/revenue"
+	"github.com/hanzoai/cloud/clients/admin/subscriptions"
+	"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.Post("/v1/admin/sync", s.guard(s.sync))
+	routes(app, s)
 
-	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.Get("/v1/admin/aimetrics", core.Guard(s, aimetrics))
+	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), reading the registry + decide the admission gate owns.
+	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})
-}
+	// Usage-cap + promo control plane (promos platform-only; spend-caps org-scoped).
+	limitRoutes(app, s)
 
-// 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 +
+	// the billing fleet views metrics/invoices/subscriptions). ──
+	audit.Routes(app, s)
+	customer.Routes(app, s)
+	revenue.Routes(app, s)
+	finance.Routes(app, s)
+	metrics.Routes(app, s)
+	invoices.Routes(app, s)
+	subscriptions.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,
@@ -192,16 +185,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 != "" {
@@ -215,56 +215,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 != "" {
@@ -273,66 +273,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{},
@@ -341,64 +327,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)
@@ -414,89 +403,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 aggregate on. Commerce
-// meters per "org/user"; the org-level roll-up uses the org's own slug as the
-// subject namespace (X-IAM-Org-Id) with the org name as the user key.
-func orgSubject(org string) string { return org + "/" + 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
@@ -513,8 +446,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
@@ -522,15 +455,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

@@ -2,6 +2,7 @@ package admin
 
 import (
 	"encoding/json"
+	"fmt"
 	"io"
 	"net/http"
 	"net/http/httptest"
@@ -9,44 +10,44 @@ 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,
 // and returns a `do` helper that issues test requests through the whole app.
 func mount(t *testing.T, iamURL, commerceURL, healthURL string) func(method, path string, hdr map[string]string) (*http.Response, []byte) {
-	do, _ := mountSvc(t, iamURL, commerceURL, healthURL)
+	do, _, _ := mountSvc(t, iamURL, commerceURL, healthURL)
 	return do
 }
 
-// mountSvc is mount but also returns the underlying svc so finance tests can
-// swap in a fake DigitalOcean client (s.do) before issuing a request. The
-// handlers read s.do live at request time, so an override here takes effect.
-func mountSvc(t *testing.T, iamURL, commerceURL, healthURL string) (func(method, path string, hdr map[string]string) (*http.Response, []byte), *svc) {
+// 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), *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))
+	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) {
@@ -61,28 +62,51 @@ func mountSvc(t *testing.T, iamURL, commerceURL, healthURL string) (func(method,
 		}
 		b, _ := io.ReadAll(resp.Body)
 		return resp, b
-	}, s
+	}, 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"},
+	{"GET", "/v1/admin/customers"},
+	{"GET", "/v1/admin/customers/acme"},
+	{"POST", "/v1/admin/customers/acme/credit"},
+	{"POST", "/v1/admin/customers/acme/suspend"},
+	{"POST", "/v1/admin/customers/acme/reactivate"},
+	{"GET", "/v1/admin/revenue"},
+	{"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
@@ -92,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 {
@@ -108,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"`
@@ -130,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
@@ -174,20 +219,98 @@ func newFakeIAM() *fakeIAM {
 	return f
 }
 
-// newFakeCommerce serves the billing reads with fixed cents so the money
-// aggregation is deterministic.
-func newFakeCommerce() *httptest.Server {
-	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+// fakeCommerce mimics the LIVE commerce billing contract (commerce >=1.46.8, the
+// 2026-07 per-org durability rework): the per-org wallet is resolved from the
+// TRUSTED X-Org-Id header (set only with the service-token bearer) and keyed under
+// the BARE org slug as the `user` subject. A wrong header (X-IAM-Org-Id) or a wrong
+// subject ("org/org") resolves to an EMPTY wallet — so this fake is a regression
+// guard for the reconciliation bug that made every admin money panel read $0 while
+// real balances existed (lux $10,000, maxpower $20,498). Verified against live
+// commerce /v1/billing/{balance,usage-rollup}.
+type fakeCommerce struct {
+	server          *httptest.Server
+	balances        map[string]int64 // org slug -> availableCents (credits)
+	spend           map[string]int64 // org slug -> consumedCents (month-to-date)
+	sawIAMOrgHeader bool             // true if the stale X-IAM-Org-Id header was ever sent
+}
+
+func newFakeCommerce() *fakeCommerce {
+	f := &fakeCommerce{
+		balances: map[string]int64{"acme": 5000, "hanzo": 5000},
+		spend:    map[string]int64{"acme": 1500, "hanzo": 1500},
+	}
+	f.server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
+		if r.Header.Get("X-IAM-Org-Id") != "" {
+			f.sawIAMOrgHeader = true
+		}
+		// Live commerce trusts ONLY X-Org-Id (with the service-token bearer) for the
+		// org namespace and keys the wallet under the bare org slug. Anything else
+		// (missing X-Org-Id, or user != org) resolves to an empty wallet.
+		org := r.Header.Get("X-Org-Id")
+		user := r.URL.Query().Get("user")
+		bal, spend := int64(0), int64(0)
+		if org != "" && user == org {
+			bal, spend = f.balances[org], f.spend[org]
+		}
 		switch {
 		case strings.HasSuffix(r.URL.Path, "/usage-rollup"):
-			io.WriteString(w, `{"consumedCents":1500,"overageCents":0,"balance":{"balanceCents":5000,"availableCents":5000}}`)
+			fmt.Fprintf(w, `{"consumedCents":%d,"overageCents":0,"balance":{"balanceCents":%d,"availableCents":%d}}`, spend, bal, bal)
 		case strings.HasSuffix(r.URL.Path, "/balance"):
-			io.WriteString(w, `{"user":"x","currency":"usd","balance":5000,"holds":0,"available":5000}`)
+			fmt.Fprintf(w, `{"user":%q,"currency":"usd","balance":%d,"holds":0,"available":%d}`, user, bal, bal)
+		case strings.HasSuffix(r.URL.Path, "/subscriptions"):
+			io.WriteString(w, `{"subscriptions":[]}`)
 		default:
 			w.WriteHeader(404)
 		}
 	}))
+	return f
+}
+
+// TestCommerce_ReconcilesWithXOrgIdBareSlug pins the exact live-commerce contract
+// the admin money aggregation depends on: the org selector is the TRUSTED X-Org-Id
+// header and the wallet subject is the BARE org slug (user=<org>) — NOT
+// X-IAM-Org-Id and NOT "org/org". This is the regression guard for the $0-fleet-
+// 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) {
+	// 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()
+	defer commerce.server.Close()
+
+	do := mount(t, iam.server.URL, commerce.server.URL, "")
+	admin := map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin"}
+	resp, body := do("GET", "/v1/admin/orgs", admin)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("orgs: got %d (body=%s)", resp.StatusCode, body)
+	}
+	var env struct {
+		Data []orgRow `json:"data"`
+	}
+	if err := json.Unmarshal(body, &env); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	// acme (sorted first) must show its REAL money, proving the header + subject key.
+	var acme *orgRow
+	for i := range env.Data {
+		if env.Data[i].Org == "acme" {
+			acme = &env.Data[i]
+		}
+	}
+	if acme == nil {
+		t.Fatalf("acme org missing from %+v", env.Data)
+	}
+	if acme.CreditsCents != 5000 || acme.SpendCents != 1500 {
+		t.Errorf("acme money = credits %d / spend %d, want 5000/1500 — the money did NOT reconcile (stale X-IAM-Org-Id or org/org subject reads $0)", acme.CreditsCents, acme.SpendCents)
+	}
+	// The stale header must NEVER be sent.
+	if commerce.sawIAMOrgHeader {
+		t.Error("admin sent the stale X-IAM-Org-Id header — commerce reads X-Org-Id only")
+	}
 }
 
 // TestOrgs_RealAggregation drives /v1/admin/orgs against fake IAM + commerce and
@@ -198,9 +321,9 @@ func TestOrgs_RealAggregation(t *testing.T) {
 	iam := newFakeIAM()
 	defer iam.server.Close()
 	commerce := newFakeCommerce()
-	defer commerce.Close()
+	defer commerce.server.Close()
 
-	do := mount(t, iam.server.URL, commerce.URL, "")
+	do := mount(t, iam.server.URL, commerce.server.URL, "")
 	admin := map[string]string{
 		"X-User-IsAdmin": "true", "X-Org-Id": "admin",
 		"Authorization": "Bearer operator-jwt", "Cookie": "iam_access_token=operator-jwt",
@@ -241,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()
@@ -266,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")
 	}
 }
 
@@ -335,9 +458,9 @@ func TestOverview_RealTilesAndSources(t *testing.T) {
 	iam := newFakeIAM()
 	defer iam.server.Close()
 	commerce := newFakeCommerce()
-	defer commerce.Close()
+	defer commerce.server.Close()
 
-	do := mount(t, iam.server.URL, commerce.URL, "") // no o11y health → source not-ok
+	do := mount(t, iam.server.URL, commerce.server.URL, "") // no o11y health → source not-ok
 	admin := map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin"}
 
 	resp, body := do("GET", "/v1/admin/overview", admin)
@@ -369,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
 	}
@@ -384,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.
@@ -391,9 +572,9 @@ func TestUsage_RealTotalsHonestEmptySeries(t *testing.T) {
 	iam := newFakeIAM()
 	defer iam.server.Close()
 	commerce := newFakeCommerce()
-	defer commerce.Close()
+	defer commerce.server.Close()
 
-	do := mount(t, iam.server.URL, commerce.URL, "")
+	do := mount(t, iam.server.URL, commerce.server.URL, "")
 	admin := map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin"}
 
 	resp, body := do("GET", "/v1/admin/usage", admin)