refactor(api): follow the ai surface to /v1/ai/<resource>

The namespaces I invented (rag, chat, content, compute, work, ops, auth) are
replaced by the ONE service namespace the canonical spec in hanzoai/openapi
mandates: /v1/<service>/<resource>, and the service is `ai`.

/v1/chat was not just stuttering — the gateway routes GET|POST /v1/chat/{path}
to chat.hanzo.svc, so those calls would have reached a DIFFERENT SERVICE.

Co-authored-by: Hanzo Dev <dev@hanzo.ai>

.dockerignore

@@ -0,0 +1,41 @@
+# VCS
+.git/
+.gitignore
+.gitattributes
+
+# CI / repo metadata not needed inside the build
+.github/
+
+# Docs (image runs the binary; readers visit GitHub)
+*.md
+LICENSE
+SECURITY.md
+
+# Already-built binary at repo root (matches .gitignore)
+/cloud
+
+# Environment files (never bake secrets into images)
+.env
+.env.*
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS metadata
+.DS_Store
+Thumbs.db
+
+# Tests stay out of the runtime image
+*_test.go
+
+# Local build outputs
+/dist/
+/build/
+/bin/
+
+# The Dockerfile itself doesn't need to be in the context it builds
+Dockerfile
+.dockerignore

.github/hero.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="640" viewBox="0 0 1280 640" role="img" aria-label="cloud">
+<rect width="1280" height="640" fill="#0A0A0A"/>
+<svg x="96" y="215" width="210" height="210" viewBox="0 0 67 67"><path d="M22.21 67V44.6369H0V67H22.21Z" fill="#fff"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z" fill="#fff"/><path d="M22.21 0H0V22.3184H22.21V0Z" fill="#fff"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z" fill="#fff"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z" fill="#fff"/></svg>
+<text x="378" y="276" font-family="Inter,system-ui,-apple-system,sans-serif" font-size="78" font-weight="800" letter-spacing="-2" fill="#ffffff">cloud</text>
+<text x="378" y="322" font-family="Inter,system-ui,sans-serif" font-size="30" fill="#ffffff" opacity=".66">Hanzo Cloud — unified Go binary that imports every Hanzo-native…</text>
+<rect x="378" y="338" width="806" height="3" rx="1.5" fill="#ffffff" opacity=".9"/>
+<text x="378" y="390" font-family="Inter,system-ui,sans-serif" font-size="24" font-weight="600" fill="#ffffff" opacity=".5">github.com/hanzoai</text>
+<text x="1184" y="390" text-anchor="end" font-family="Inter,system-ui,sans-serif" font-size="24" font-weight="600" fill="#ffffff" opacity=".5">hanzo.ai</text>
+</svg>

.gitignore

@@ -0,0 +1,46 @@
+# Built binaries (Dockerfile output + `go build ./cmd/hanzo`)
+/cloud
+/hanzo
+
+# Local build directories
+/dist/
+/build/
+/bin/
+
+# Go test + coverage artifacts
+*.test
+*.out
+coverage.txt
+coverage.html
+
+# cek encryption sidecars are key material — never commit one from a source tree.
+# Tests seal their stores under t.TempDir(); a sidecar in a package dir (e.g. from a
+# test that opened ":memory:") is a mistake. The cek testdata fixtures are the one
+# intentional exception.
+*.dek
+*.cek.lock
+!cek/testdata/**
+
+# Environment files
+.env
+.env.*
+!.env.example
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS metadata
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+.shots/
+
+.claude/
+.worktrees/
+native/flags/target

.hanzo/workflows/cicd.yml

@@ -0,0 +1,199 @@
+name: CI/CD
+# The ONE pipeline for cloud, on our own runners against git.hanzo.ai.
+#
+# THE LAW: `.github/workflows` holds exactly one file — a sync nudge that runs
+# zero CI. Everything that gates, builds or deploys lives here.
+#
+# It absorbs the three pipelines that used to run beside each other:
+#
+#   .github/workflows/cicd.yml  → `gate` (unchanged: the ~7-line caller; every
+#     real detail still lives in the repo-root hanzo.yml, which
+#     platform.hanzo.ai reads too, so no build logic moved)
+#   .github/workflows/containment.yml → `containment` (verbatim; only its own
+#     self-exclusion path follows the file)
+#   .hanzo/workflows/deploy.yml → deleted, not moved (below)
+#
+# CI gates. It does not deploy, and deliberately builds no cloud image: that
+# image and its v* tags have ONE owner, clients/platform/release.go (POST
+# /v1/runner {release:true}) — a second builder on the same commit is the
+# double-build hanzo.yml's images: block already refuses for this reason.
+# deploy.yml claimed to do both and could do neither: it shelled
+# `buildctl-daemonless.sh`, absent from the image this fleet actually serves for
+# `hanzo-build-linux-amd64` (catthehacker/ubuntu:act-24.04 —
+# universe:infra/k8s/git-runner/statefulset.yaml), read a GIT_CLONE_TOKEN secret
+# that exists on neither the repo nor the org, and ended in a `kubectl patch app`
+# that cd.hanzo.ai's selfHeal undoes on its next poll. Rollout is, and stays, a
+# reviewed tag pin in hanzoai/universe.
+on:
+  push:
+    branches: [main]
+  pull_request:
+  # The sync (sync-from-github.yml) dispatches this workflow by name after a
+  # fast-forward: a push made with the workflow token does not trigger workflows,
+  # so without this trigger every synced commit would gate nothing. deploy.yml
+  # declared no dispatch trigger, which is why that curl could only 404.
+  workflow_dispatch:
+concurrency:
+  group: cicd-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  # Test gate + the decoupled native flags staticlib image, driven by hanzo.yml.
+  gate:
+    uses: hanzoai/ci/.hanzo/workflows/build.yml@v2
+    secrets: inherit
+
+  # 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 merge:
+  #
+  #   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. graph         — no cmd/ main may reach clients/controlplane through its
+  #      untagged import graph (`go list -deps`), 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.
+  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 '.hanzo/workflows/cicd.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 '.hanzo/workflows/cicd.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
+
+          # Containment is an IMPORT-GRAPH property, so prove it with the import
+          # graph. This step used to lead with `go build ./...`, which compiles
+          # AND LINKS every cmd/ main — and linking needs
+          # native/flags/target/release/libhanzo_flags.a, the Rust staticlib
+          # clients/flags pulls in under cgo (clients/flags/engine.go). Nothing
+          # in THIS job builds it: `make native` runs in the gate job, in that
+          # job's own workspace. It passed on GitHub only because the arc
+          # runners reuse a workspace and target/ is gitignored, so an earlier
+          # gate job's leftover .a was still sitting there; on a container
+          # runner with a fresh volume every cmd/ main died at
+          # `ld: cannot find .../libhanzo_flags.a`. The compile was never the
+          # proof anyway — `go list -deps` reads the same untagged file set
+          # without linking, and the gate job is the ONE place that builds.
+          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"
+

.hanzo/workflows/sync-from-github.yml

@@ -0,0 +1,53 @@
+name: Sync from GitHub
+# git.hanzo.ai is canonical and builds (cicd.yml); development also lands on
+# github.com/hanzoai/cloud. ONE deterministic direction: an in-cluster PULL. The
+# runner reaches both ends (GitHub outbound, this Gitea via the instance URL
+# actions/checkout already uses), so the sync has no ingress dependency.
+#
+# Fast-forward ONLY: a divergence fails loudly here instead of force-pushing
+# either side.
+#
+# Inert until hanzoai/cloud stops being a Gitea pull mirror — while it is one,
+# the forge overwrites main from GitHub on its own timer and rejects the push
+# below. That conversion is also what turns Actions on here (measured today:
+# mirror: true, has_actions: false ⇒ zero native runs).
+on:
+  schedule:
+    - cron: '*/10 * * * *'
+  workflow_dispatch: {}
+concurrency:
+  group: sync-from-github
+  cancel-in-progress: false
+jobs:
+  ff-main:
+    runs-on: [hanzo-build-linux-amd64]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: true
+      - name: Fast-forward main from github.com/hanzoai/cloud
+        env:
+          GH_PAT: ${{ secrets.GH_PAT }}
+        run: |
+          set -euo pipefail
+          git fetch --quiet "https://x-access-token:${GH_PAT}@github.com/hanzoai/cloud.git" main
+          LOCAL="$(git rev-parse HEAD)"; REMOTE="$(git rev-parse FETCH_HEAD)"
+          if [ "$LOCAL" = "$REMOTE" ]; then echo "in sync at $LOCAL"; exit 0; fi
+          if git merge-base --is-ancestor "$LOCAL" "$REMOTE"; then
+            echo "fast-forwarding $LOCAL -> $REMOTE"
+            git push origin "$REMOTE:refs/heads/main"
+            # A push made with the workflow token does not trigger workflows, so
+            # synced commits would never build. Dispatch the pipeline explicitly.
+            curl -fsS --max-time 20 -X POST \
+              -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
+              -H "Content-Type: application/json" \
+              "${{ github.server_url }}/v1/repos/${{ github.repository }}/actions/workflows/cicd.yml/dispatches" \
+              -d '{"ref":"main"}' \
+              && echo "CI/CD dispatched" || echo "CI/CD dispatch failed (non-fatal — next direct push builds)"
+          elif git merge-base --is-ancestor "$REMOTE" "$LOCAL"; then
+            echo "canonical is AHEAD of GitHub — nothing to pull (never force from here)."
+          else
+            echo "::error::main DIVERGED between GitHub ($REMOTE) and canonical ($LOCAL) — refusing to force. Reconcile manually."
+            exit 1
+          fi

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

@@ -1,16 +1,207 @@
-FROM golang:1.26-alpine AS build
-RUN apk add --no-cache ca-certificates tzdata
-RUN addgroup -g 65532 -S nonroot && adduser -u 65532 -S nonroot -G nonroot
-WORKDIR /src
-COPY . .
-RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /cloud ./cmd/cloud
+# hanzoai/cloud — the ONE unified Hanzo Cloud binary (HIP-0106).
+#
+# 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 final `/cloud` binary already carries the UI —
+# no separate console Service, no second origin; the embedded console calls /v1
+# on its own host.
+#
+# ── 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=… .
+#
+# IMMUTABLE per-commit tags, never `:latest`. These defaults are LOAD-BEARING:
+# the builder that actually runs our releases is the native one (POST /v1/runner
+# → launchDirectBuild → BuildKit), and it passes no --build-arg, so whatever is
+# written here is what gets baked. `release.yml`, which the previous comment said
+# would resolve a fresh digest, is a stub and resolves nothing.
+#
+# With `:latest` the embedded console was therefore decided by WHEN the build ran,
+# not by what we shipped — and it bit: cloud v1.801.215 was built ~12 minutes
+# before console CI finished publishing the console-embed carrying v8.5.26, so a
+# release whose whole purpose was that console change silently baked the previous
+# one and shipped green. Same image, two contents, no diff to show for it.
+#
+# BUMP: when a console/skills/flags change must reach production, move its pin
+# here in the same commit that claims it. That is what makes a cloud release
+# reproducible and makes "what console is in v1.801.N" answerable from git.
+ARG CONSOLE_IMAGE=ghcr.io/hanzoai/console-embed:sha-9f7042c-amd64
+ARG SKILLS_IMAGE=ghcr.io/hanzoai/agent-skills:sha-b931a11-amd64
+ARG FLAGS_IMAGE=ghcr.io/hanzoai/cloud-flags:sha-e1ca02a-amd64
 
-FROM scratch
+# ── 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
+# 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=readonly
+COPY go.mod go.sum ./
+# 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 (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 (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").
+# tini: /cloud runs as PID 1, and PID 1 inherits every orphaned descendant in the
+# container. git is not a single process — fetch/clone fan out to git-upload-pack,
+# git-index-pack, git-rev-list and git-pack-objects. When cloud Kill()s a wedged
+# direct child (gitPackStream.Close does exactly that, correctly), those
+# grandchildren orphan and reparent to PID 1. A Go program never reaps adopted
+# orphans, so each one becomes a permanent zombie holding a PID slot.
+# Measured 2026-07-26 on worker-xl-37bw71: 18,553 zombie `git` out of 18,741
+# processes, all parented to /cloud, which drove the node to PID pressure and
+# got cloud ITSELF evicted. A zombie costs no CPU and no memory, so nothing but
+# an eviction ever surfaces it. tini reaps them.
+RUN apk add --no-cache ca-certificates tzdata sqlcipher-libs git libgcc tini \
+    && 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 \
+    && test -x /sbin/tini
 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"]
+# tini as PID 1 forwards signals to /cloud unchanged (so SIGTERM still drains
+# normally) and reaps the orphans described above. `--` keeps cloud's own args
+# untouched; the CR passes none today, but that stays true if it ever does.
+ENTRYPOINT ["/sbin/tini", "--", "/cloud"]

IAM_CUTOVER.md

@@ -0,0 +1,192 @@
+# IAM cutover — Casdoor pod → embedded IAM in cloud (supervised)
+
+Flip `hanzo.id`'s identity plane from the standalone Casdoor pod to the clean-room
+IAM rewrite embedded in this binary (`clients/iam`, `github.com/hanzoai/iam`
+**v1.33.6**). This is the last step of HIP-0106 (one binary embeds IAM + KMS + o11y).
+
+**This is a single supervised session. Do not run it piecemeal or in the
+background.** Every step below is: **action → verify → rollback**. Money/auth is on
+the line — a bad flip 401s every login and every metered request.
+
+The blocking code work is **done and shipped**:
+- IAM v1.33.6 serves the legacy path aliases the deployed fleet hard-codes
+  (`/v1/iam/oauth/access_token`, `/v1/iam/oauth/refresh_token`, `/v1/iam/userinfo`)
+  next to the canonical paths — so no hard-coded caller 404s at the flip.
+- `cloud` pins `github.com/hanzoai/iam v1.33.8` (go.mod) and compiles it in.
+
+> **`iam` is NOT staged.** `stagedSubsystems` in `config.go` holds only `ingress`, so
+> the empty-`CLOUD_ENABLE` "mount everything" default — **the live posture on
+> `universe/infra/k8s/operator/crs/cloud.yaml`** — mounts the embedded IAM. Step 1 is
+> therefore a **precondition of the next deploy**, not of a later flip: a cloud that
+> boots before the store is migrated opens an EMPTY `iam2.db` and seeds only from
+> `init_data.json`. `iam_edge.go` forwards `/v1/iam/*` to the standalone pod ONLY
+> under a non-empty `--enable` that omits `iam`, which is the one way to hold cloud
+> on the old plane while Step 1 runs.
+
+## Preconditions (verify before touching anything)
+
+1. Live image is at or above the tag that carries embedded IAM v1.33.6
+   (`universe/infra/k8s/operator/crs/cloud.yaml` `spec.image.tag`). The subsystem is
+   compiled in but inert until enabled — safe to deploy ahead of the flip.
+2. `spec.replicas: 1` and `strategy: Recreate` (already required — the embedded
+   store is single-writer/single-open). **`config.go` refuses to boot iam-enabled
+   above 1 replica.** Never scale up with iam on.
+3. `CLOUD_DATA_DIR=/var/lib/cloud` on the RWO `cloud-api-data` PVC. The embedded IAM
+   store is **`/var/lib/cloud/iam/iam2.db`** (`clients/iam/iam.go` `paths()`) — the v2
+   store. `iam.db` is a different database; opening it serves the wrong identities
+   without failing.
+4. You have the live Casdoor store to migrate FROM and its KMS master key:
+   - encrypted sharded root: `<dir>/iam.db` + `<dir>/orgs/*/iam.db` (+ `.dek` sidecars)
+   - `IAM_KMS_MASTER_KEY` = the 64-hex master key (from KMS — never an arg, never logged)
+5. `migrate-v1` is built from the **iam** repo (`github.com/hanzoai/iam`,
+   `cmd/migrate-v1`, same v1.33.6 tag) with a C `sqlcipher` binary on PATH (for
+   `--wal-inclusive`).
+
+## Step 1 — Migrate the live store into the embedded datadir (BEFORE any seed)
+
+The embedded IAM seeds new-only from `init_data.json`. Migrating real rows must
+happen **before** the subsystem ever seeds, or the seed masks/collides with them.
+The source is opened **read-only** — the live Casdoor pod is untouched.
+
+**1a. Dry-run = the drift/parity gate.** `--dry-run` runs the full extraction and
+prints the per-entity report WITHOUT writing. Require every entity's count to match
+the live source and **drift = 0** before proceeding.
+
+```
+migrate-v1 \
+  --src-datadir /path/to/live/casdoor/store \
+  --src-master-key-env IAM_KMS_MASTER_KEY \
+  --wal-inclusive \
+  --dest /var/lib/cloud/iam/iam2.db \
+  --dry-run
+```
+
+- `--wal-inclusive` checkpoints each shard's uncheckpointed `-wal` via the C
+  sqlcipher binary → COMPLETE extraction. Without it, uncheckpointed WAL rows are a
+  hard error (or, with `--ignore-wal`, silently dropped — do NOT use for a real cutover).
+- `--dest` accepts either form and both land on the same file here (`storePath` in
+  `iam/cmd/migrate-v1/main.go`): a `.db` path is taken verbatim, anything else is
+  treated as a data-dir and gets `/iam2.db` appended. So `…/iam/iam2.db` and `…/iam`
+  are equivalent. What matters is that the written file is exactly
+  `/var/lib/cloud/iam/iam2.db` — the path `clients/iam` opens.
+
+**Verify:** dry-run report shows expected counts for users, orgs, applications,
+providers, certs; zero drift; zero errors.
+**Rollback:** none needed — nothing written.
+
+**1b. Real migration.** Same command **without** `--dry-run`, writing into the
+(empty) embedded datadir on the cloud PVC. Do this while iam is still staged OFF.
+
+**Verify:** re-run `--dry-run` against `--src /var/lib/cloud/iam/iam2.db` (or open it
+read-only) and confirm counts equal the source.
+**Rollback:** `rm -f /var/lib/cloud/iam/iam2.db*` (only the freshly-written store) and
+re-run. Nothing else consumes it until cloud next boots iam-enabled.
+
+## Step 2 — Boot cloud with the embedded IAM subsystem
+
+`iam` is **not** staged, so the live CR's empty `CLOUD_ENABLE` already enables it —
+there is no env var to add. Deploying the image IS this step. Nothing here is
+additive or reversible by a flag: plan Step 1 to complete before the next roll.
+
+Apply the CR; the operator rolls the Recreate Deployment (single pod, brief blip —
+expected). On boot, `clients/iam` opens `/var/lib/cloud/iam/iam2.db` (the migrated
+store), seeds new-only from `init_data.json` (idempotent — real rows already present,
+so seed only adds anything genuinely missing), and mounts the full `/v1/iam/*` surface
+IN-PROCESS. `iam_edge.go` stops mounting (`serve.go`: `if !cfg.Enabled("iam") …`), so
+there is **no double-mount** and no forward to the Casdoor pod.
+
+**Verify (still on the internal Service, before repointing the edge):**
+```
+kubectl -n hanzo exec deploy/cloud -- \
+  curl -s localhost:8000/v1/iam/.well-known/openid-configuration | jq .issuer
+# → "https://hanzo.id"
+kubectl -n hanzo logs deploy/cloud | grep 'iam embedded in-process'
+```
+A boot failure serves fail-closed 503 on `/v1/iam/*` (cloud + every other subsystem
+stay up) — it does NOT crash the binary.
+**Rollback:** set `CLOUD_ENABLE` to an explicit list that OMITS `iam` and re-apply the
+CR. Deleting an env var does not roll this back — an empty `CLOUD_ENABLE` is
+iam-ENABLED. An explicit list is an allowlist, so it must name every other subsystem
+this deployment serves; take it from the CR's own subsystem set, not from memory.
+With `iam` out of that list the edge re-mounts and forwards to Casdoor again.
+hanzo.id is unaffected (still pointed at Casdoor until Step 3).
+
+## Step 3 — Repoint the hanzo.id identity backend at the edge
+
+`universe/infra/k8s/ingress/routes.yaml`: router `hanzo-id-iam-api` (priority 100)
+matches `Host(hanzo.id) && (PathPrefix(/v1/iam) || PathPrefix(/oauth) ||
+PathPrefix(/.well-known))` → `service: iam-hanzo-ai`. Repoint that **service** from
+the Casdoor pod to embedded cloud:
+
+```yaml
+    iam-hanzo-ai:
+      loadBalancer:
+        passHostHeader: true
+        servers:
+        - url: http://cloud.hanzo.svc.cluster.local:8000   # was: http://iam.hanzo.svc.cluster.local:80
+```
+
+Leave the `hanzo-id` service (`id.hanzo.svc:80`, the @hanzo/id login SPA) as-is — only
+the API backend moves. The ingress file-provider applies the ConfigMap edit **HOT**
+(fsnotify) — **do NOT `rollout restart deploy/ingress`** (that triggers the per-node
+ACME storm / TLS outage documented in `universe/CLAUDE.md`).
+
+**Verify:** run the Step-4 parity checks against the public host `https://hanzo.id`.
+**Rollback:** revert the one `url:` back to `http://iam.hanzo.svc.cluster.local:80`;
+hot-reapplies in seconds. Instant, complete rollback to Casdoor.
+
+## Step 4 — Playwright / curl parity (drive it, don't just curl a status)
+
+Against `https://hanzo.id` (through the repointed edge). Use Playwright for the browser
+login (real interaction, not an HTTP status peek):
+
+1. **Discovery + JWKS**: `/.well-known/openid-configuration`,
+   `/v1/iam/.well-known/openid-configuration`, `/v1/iam/.well-known/jwks` — issuer
+   `https://hanzo.id`, keys present.
+2. **Browser login → code → token** (Playwright): `/login/oauth/authorize` → sign in
+   → callback with `code` → token exchange → a verifiable JWT; the app authenticates.
+3. **client_credentials** (KMS bridge / gateway guards shape) at BOTH
+   `/v1/iam/oauth/token` and the alias `/v1/iam/oauth/access_token` → 200 + token.
+4. **refresh** at the alias `/v1/iam/oauth/refresh_token` (the `hanzo` CLI shape) → 200
+   + rotated token.
+5. **userinfo** at BOTH `/v1/iam/oauth/userinfo` and the alias `/v1/iam/userinfo`
+   (commerce shape) → same principal.
+6. **Real callers**: force one live KMS-bridge / gateway-guard token fetch and one
+   `hanzo login` + `hanzo` CLI refresh against hanzo.id → all 200.
+
+**Accepted delta (not a regression):** BARE `/oauth/token|access_token|userinfo`
+(no `/v1/iam` prefix) on hanzo.id 404 post-cutover — the rewrite serves the
+`/v1/iam/…`-prefixed canonical + alias paths only, discovery advertises those, and no
+live caller uses the bare form (grep-verified: every fleet caller uses `/v1/iam/oauth/*`
+or an app-local `/oauth/*` proxy that rewrites to `/v1/iam/*`). Bare `/oauth/authorize`
+still 302s to the login SPA via the priority-150 router (unchanged). Optionally tighten
+the `hanzo-id-iam-api` rule to drop the bare `/oauth` prefix in the same edit.
+
+**If any parity check fails: roll back Step 3 immediately** (one `url:` revert) and
+diagnose with iam still embedded-but-unrouted.
+
+## Step 5 — Retire the standalone Casdoor `iam` (final, only after parity holds)
+
+With hanzo.id served by embedded IAM and parity green, remove the standalone Casdoor
+workload. It is operator-managed via its App/CR
+(`universe/infra/k8s/operator/crs/iam.yaml`, legacy
+`hanzo-operator/crs/iam.yaml` + `iam-v1.yaml`). **First scale to 0** (reversible),
+soak, then delete the CR + drop its basename from the Hanzo CD
+`universe-crs` `include` glob (so ArgoCD stops governing it).
+
+**Verify:** hanzo.id fully green with the Casdoor pod at 0 replicas for a full soak
+(logins, token refresh, metered `/v1/*` traffic). Then delete.
+**Rollback (pre-delete):** scale the Casdoor Deployment back to 1 and revert Step 3's
+edge `url:` — hanzo.id is back on Casdoor in seconds. **After** the CR is deleted this
+is no longer a one-step rollback (re-apply the CR from git), so hold the scale-to-0
+soak until you are certain.
+
+## Guardrails (do NOT, until this supervised session)
+
+- Do not roll a cloud image onto the live CR before Step 1 completes — the empty
+  `CLOUD_ENABLE` mounts embedded IAM on boot, so the deploy itself performs Step 2.
+- Do not repoint `iam-hanzo-ai` before Step-2 in-process verification passes.
+- Do not delete or scale down the Casdoor `iam` workload before Step-4 parity holds.
+- Do not run `migrate-v1` against prod without the read-only source + a green `--dry-run`.
+- Do not `rollout restart deploy/ingress` (ACME storm). The routes edit is hot-reloaded.
+- Keep `replicas: 1` / `strategy: Recreate` — embedded IAM is single-writer.

LICENSE

@@ -0,0 +1,203 @@
+Copyright (c) 2026 Hanzo AI Inc.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright (c) 2026 Hanzo AI Inc.
+
+   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.

LLM.md

@@ -0,0 +1,416 @@
+# LLM.md — hanzoai/cloud
+
+**Canonical repo.** `hanzoai/cloud` (HIP-0106) is the Open AI Cloud as ONE Go
+binary + `hanzo` CLI: every Hanzo subsystem (iam, base, kms, ai, gateway,
+commerce, o11y, tasks, …) mounted into a single multi-org 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. This is the impl home for the cloud
+control plane; the OpenAPI it emits at `GET /v1/openapi.json` is the single
+source for the generated per-language SDKs.
+
+## Role in the SDK model
+- Full Cloud SDK is GENERATED from THIS binary's OpenAPI; SDK impl lives in
+  `hanzo-<lang>/sdk`, docs/wrappers in `hanzoai/<lang>-sdk`, meta in `hanzoai/sdk`.
+- AI/agents flagship lib is separate: Python `hanzo` (`hanzoai/python-sdk`),
+  Node `@hanzo/ai` (`hanzo-js/ai`). Completeness: Python > Rust > C++ > Go.
+- DRY: one impl, one place; discovery repos link OUT, never duplicate impl.
+- Full spec: `~/work/hanzo/SDK-ARCHITECTURE.md`.
+
+## Brand rules (hard)
+- Hanzo is a full AI cloud, NOT a proxy — never "LLM gateway", never position vs
+  LiteLLM. Zen models are our OWN family; never name upstream models.
+- `/v1/` only, never `/api/`. Voice: "Hanzo — the Open AI Cloud."
+
+## Install / run
+- `docker run -p 8080:8080 ghcr.io/hanzoai/cloud:vX.Y.Z` (pin a released tag) ·
+  `go install github.com/hanzoai/cloud/cmd/hanzo@latest` · `brew install hanzoai/tap/hanzo`
+- Build in MODULE mode only: `make build` / `GOWORK=off go build ./...` — never
+  workspace mode (see "Build & module graph" below).
+
+## Key entry points
+- `cmd/cloud` — server binary · `cmd/hanzo` (`cli/`) — control CLI · `webui.go` — embedded console
+- `apps/apps.go:Wire()` — composition root (the one ordered subsystem slice)
+- `deps.go` / `cloud.Deps` — process-wide handles · `clients/<name>/` — every subsystem
+- `openapi/` — live spec derived from the router (no checked-in spec file)
+
+---
+
+## 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 |
+| `/v1/cloud` | Cloud accounts: link DO/AWS/GCP/Azure, discover native k8s clusters, fold into the fleet | `clients/venue` (new) | In flight (branch `feat/cloud-account-connectors`; blue-held for red) |
+| `/v1/blueprint` | Cost: OSS-template SBOM (compose→images) + compute-cost estimate | `clients/blueprint` (new) | 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).
+
+## Build & module graph — standalone module, NOT a go.work member
+
+`cloud` is a self-contained deploy unit: its own `go.mod`, `Dockerfile`, binary.
+It is intentionally NOT listed in the parent `~/work/hanzo/go.work` workspace —
+that workspace deliberately excludes the heavy modules, and merging cloud's
+k8s/otel dependency tree with `o11y`'s reintroduces `koanf`/`ugorji`
+monolith-vs-split import ambiguities (the parent workspace is itself red on the
+koanf split; that is not cloud's bug to fix).
+
+The catch: `go` auto-discovers that parent `go.work` whenever you run a bare
+`go build ./...` / `go test ./...` from inside this tree, which puts the build in
+workspace mode and SILENTLY DROPS cloud's own `go.mod` directives. Those
+directives are load-bearing and each fixes exactly one graph hazard:
+
+- `replace github.com/vulcand/oxy/v2 => github.com/traefik/oxy/v2 <pseudo>` — the
+  bare require is a placeholder (`v2.0.0-00010101000000-000000000000`); without
+  the replace it resolves to an invalid version.
+- `exclude github.com/ugorji/go <old-monolith>` — drops the pre-split monolith so
+  `github.com/ugorji/go/codec` (pulled by gin) is unambiguous.
+- the `k8s.io/*` staging replace block pins every staging module to the `v0.35.3`
+  line. `k8s.io/kubernetes` is a GRAPH-ONLY transitive require of
+  `hanzoai/deploy/gitops-engine` (clients/deploy uses its `pkg/utils/kube`); NO
+  cloud package imports `k8s.io/kubernetes`, so its staging tree never compiles —
+  do not "drop k8s.io/kubernetes", the pins keep the graph consistent and it is
+  never built. koanf resolves to the split modules; the `koanf v1.5.0` monolith
+  require is a harmless graph leaf, never imported.
+
+So: build cloud in module mode, never workspace mode. `make build`/`test`/`vet`/
+`tidy` force `GOWORK=off` (matches CI and the Dockerfile, which check out cloud
+alone with no parent go.work). For a bare `go` command from this tree, prefix
+`GOWORK=off`. `GOWORK=off go build ./...` and `go vet ./...` are green; `go mod
+tidy` is stable. Do NOT commit a `go.work` here — it would flip the Dockerfile
+(`COPY go.mod go.sum` → `go mod download` → `COPY . .`) into workspace mode after
+its `-mod=readonly` download step.
+
+Test modes: `make test` is pure-Go (`CGO_ENABLED=0`). Encrypted-at-rest OrgDB
+tests (`cek`, `CLOUD_KMS_MASTER_KEY_REF` set) REQUIRE `CGO_ENABLED=1` +
+libsqlcipher (`cek/cek.go` refuses to encrypt in pure-Go); those run only in the
+Dockerfile's dedicated `-tags libsqlite3` CGO stage, and fail under `make test`
+by design (clients/git, kms, flags, x402, cmd/kmsreseal, finance). Bundle-embed
+tests (clients/tasks/ui) need `make deploy-ui` first (real bundle is gitignored).
+
+Store-heavy subsystem tests are fsync-bound, not CPU-bound. A mount opens its own
+SQLite stores, so a test that mounts several subsystems commits many times, and
+`t.TempDir()` under `/tmp` puts every commit behind the ext4 journal — on a box with
+a concurrent build the same mount that costs milliseconds idle costs ~90s, at ~0%
+CPU, blocked in `jbd2_log_wait_commit`. Point `TMPDIR` at tmpfs to measure the real
+cost: `TMPDIR=/dev/shm/t GOWORK=off go test -p 1 ./clients/guide` runs the eight-seam
+cross-subsystem harness (`clients/guide/drivehome_e2e_test.go`) in under a second.
+Prefer one package per `go test` invocation regardless: `./...` links every main
+package at once (`cmd/cloud` alone links >6GB).
+
+## 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.
+- **The EXPERIMENT is a composition, not a fourth engine (`clients/experiments`,
+  `/v1/experiments`).** A/B testing is ONE value whatever the variant KIND (feature
+  flag, ad creative, email subject, model id): the primitive owns only the
+  experiment registry (definition + decision); it COMPOSES three planes it never
+  duplicates. ASSIGNMENT = `flags.Assign(org,project,key,subject,props)` —
+  subject→variant is a deterministic `engineEvaluate` (sha1 rollout hash), no second
+  bucketing, no assignment store; create writes a multivariate flag def
+  (`flags.PutDef`) and decide rewrites its weights to 100% for the winner
+  (`flags.GetDef`+`PutDef`). MEASUREMENT = `analytics.Outcomes(...)` — one
+  org-scoped `hanzo.events` query (the `eventsWhere` isolation invariant), no second
+  event store; the analyze fold joins each subject's analytics outcome to its flags
+  variant by `distinct_id`. EVIDENCE = `research.Record`/`research.List` — per-variant
+  samples land as immutable `kind:"ab"` rows; significance (two-proportion z-test,
+  `math.Erfc`, no dep) is a PURE function over them. `clients/campaign` runs a
+  creative A/B by composing `experiments.Assign`/`experiments.Analyze` — it never
+  reinvents assignment or evidence. Add a new variant KIND by putting a payload on
+  the variant; the primitive does not care what it is.
+- **The OSS-template compute cost is DERIVED from the compose, not a fourth ledger
+  (`clients/blueprint`, `/v1/blueprint`).** A blueprint's `docker-compose.yml` is
+  parsed to its SBOM (the bill of container images) and its services' CPU/memory
+  footprint priced through ONE documented rate card (microdollars per vCPU-/GB-hour,
+  DigitalOcean-droplet-derived + platform margin; tunable via
+  `CLOUD_BLUEPRINT_UCPU_HR`/`_UGB_HR`). Sizing is the declared
+  `deploy.resources.reservations`/`limits` (or legacy `cpus`/`mem_*`) else a default
+  footprint per inferred class (db/cache/web/worker/other). `blueprint.EstimateTemplate(id)`
+  returns `{sbom, vcpuHr, gbHr, microUsdPerHour, estCentsPerMonth}`: `estCentsPerMonth`
+  is the "~$X/mo to run" the console shows; `microUsdPerHour` is the exact rate the
+  deploy path meters the deploying org on via the SAME commerce spine `resource_billing`
+  uses. The author royalty (`clients/authors`, `defaultShareBps=2000`) already accrues
+  20% of a deploying org's metered spend — this plane only DEFINES the compute component
+  of that spend from a real rate card; it never touches the ledger or the accrual sweep.
+  Distinct from `clients/sbom` (CycloneDX packages INSIDE one image, keyed by digest);
+  this is the bill of IMAGES a stack runs, keyed by template.
+
+## 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.
+
+## GTM: `/v1/campaign` orchestration → channels → connectors → analytics
+
+The go-to-market stack decomplects a campaign from its execution. A **Campaign is a
+VALUE** (`clients/campaign`: `{name, audience, content[], schedule, budget, channels[],
+status}`) that SPANS channels; a **Channel is an EXECUTOR** (`channel.go`, the
+`Channel` interface) it fans out to. The three channels are orthogonal and each
+CONSUMES the connector plane via `integrations.TokenFor` — the campaign object never
+touches a credential:
+
+- **paid → `/v1/ads`** — `ads.LaunchPaid/PaidSpend/PausePaid` (`clients/ads/provider.go`)
+  resolve the org's ad token (`meta_ads`/`google_ads`/… via `TokenFor(org, <id>,
+  "access_token")`) and run the campaign on the provider. Meta is executed for real;
+  fail-closed when the org has not connected (424). This is the ONLY place `/v1/ads`
+  touches the connector plane.
+- **organic → `/v1/publish`** (rename of `clients/social`) and **email → `/v1/marketing`**
+  are DESIGNED follow-ons: register their executors the same way in `apps/wire_seams.go`
+  (`campaign.RegisterChannel(campaign.NewChannel(kind, launch, spend, pause))`). Until
+  wired, a fan-out records that channel "unavailable" (honest), never fabricated.
+
+Channels are injected at the composition root (`apps/wire_seams.go`), the SAME
+injected-function decoupling the coding dispatcher uses — `campaign` never imports
+`ads`, `ads` never imports `campaign`. Fan-out (`launch.go` `fanOut`) is best-effort
+per channel; the org (the ONLY tenant key) is passed verbatim to every executor, so a
+campaign can only ever resolve its OWN org's token.
+
+**Metrics = the ONE analytics plane, not a second store.** `GET /v1/campaign/:id/metrics`
+reads the funnel from `analytics.CampaignMetrics(org, campaignID, variant, start, end)`
+(`clients/analytics/campaign.go`) — an org+`utm_campaign`(+`utm_content`)-scoped query
+over `hanzo.events`, org and campaign bound POSITIONALLY (same tenancy invariant as
+every analytics query) — joined with each channel connector's reported spend
+(`Channel.Spend`). Derived KPIs: CTR/CVR/CAC/ROAS. Honest-empty when the warehouse is
+absent.
+
+**Creative A/B composes the experiment primitive** (`experiment.go`), it does not
+reinvent it: a creative A/B is an experiment whose variant = a creative (tagged
+`utm_content`) and whose metric = the analytics read. The `AssignFunc`/`EvidenceFunc`
+seams are wired at the root to the flags-assignment + evidence primitive; nil-safe
+until it lands (single-creative honest default).

Makefile

@@ -0,0 +1,116 @@
+# hanzoai/cloud — developer ergonomics for the unified Hanzo Cloud binary (HIP-0106).
+# Targets are intentionally minimal; deploy artifacts (compose, helm) live in deploy/ and helm/.
+
+GO              ?= go
+BIN             ?= cloud
+PKG             ?= ./cmd/cloud
+
+# cloud is a STANDALONE Go module — a self-contained deploy unit (its own go.mod,
+# Dockerfile, binary). It is intentionally NOT a member of the parent
+# ~/work/hanzo/go.work workspace (that workspace deliberately excludes the heavy
+# modules; adding cloud would merge its k8s/otel graph with o11y's and reintroduce
+# koanf/ugorji import ambiguities). But `go` auto-discovers that parent go.work
+# whenever a dev builds from inside this tree, which shadows cloud's own
+# replace/exclude directives (oxy pin, ugorji monolith exclude, k8s staging pins)
+# and breaks `go build ./...`. Force module mode so make targets build EXACTLY
+# what CI/Docker build (fresh checkout, no parent go.work). Overridable via
+# `make GOWORK=... <target>` for the rare cross-module case.
+export GOWORK := off
+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
+
+# 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 run smoke test test-cgo vet tidy docker docker-push clean
+
+help: ## Show this help.
+	@awk 'BEGIN{FS=":.*##";printf "\nUsage: make <target>\n\nTargets:\n"} /^[a-zA-Z_-]+:.*##/{printf "  \033[36m%-16s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+webui: ## Build the real 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
+	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.
+
+# NOTE: cloud builds ONLY the `cloud` binary — the stateless unified API. The Go
+# `hanzo` CLI (cmd/hanzo + cli/) is RETIRED: the shipped `hanzo` is the Rust CLI
+# (~/work/hanzo/cli, `curl hanzo.sh`), which talks to this API over HTTP via its
+# OpenAPI-generated command surface. The `code` wrapper (incl. the zen-tier 1M
+# mechanism) now lives in the Rust CLI. cmd/hanzo + cli/ remain only as the
+# reference for the still-to-port client-side tools (GPU fleet worker `link`,
+# `runner`, `engine`, `security`) and are no longer built here.
+
+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
+
+smoke: ## Build and run cmd/cloud-smoke (mount-time integration check).
+	$(GO) run ./cmd/cloud-smoke
+
+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.
+	CGO_ENABLED=$(CGO_ENABLED) $(GO) vet ./...
+
+tidy: ## go mod tidy + verify go.sum.
+	$(GO) mod tidy
+	$(GO) mod verify
+
+docker: ## Build the Docker image (uses repo Dockerfile, scratch final stage).
+	docker build -t $(DOCKER_IMAGE):$(DOCKER_TAG) .
+
+docker-push: docker ## Push the Docker image to ghcr.io. Requires docker login.
+	docker push $(DOCKER_IMAGE):$(DOCKER_TAG)
+
+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

NOTICE

@@ -0,0 +1,32 @@
+Hanzo Cloud
+Copyright (c) 2026 Hanzo Industries, Inc.
+
+This product includes software from the following upstream projects. Their names
+appear here and NOWHERE ELSE in this codebase's user-visible surfaces — Hanzo
+products are named for Hanzo (Hanzo Analytics, Hanzo Insights, Hanzo IAM, …).
+
+Umami (https://github.com/umami-software/umami), licensed under MIT:
+
+    Copyright (c) 2022 Umami Software, Inc. <hello@umami.is>
+
+  Hanzo Analytics (analytics.hanzo.ai) is a fork. The cloud destination adapter
+  speaks its public collect contract.
+
+PostHog (https://github.com/PostHog/posthog), licensed under MIT:
+
+    Copyright (c) 2020-present PostHog Inc.
+
+  Hanzo Insights (insights.hanzo.ai) is a fork. The cloud destination adapter
+  speaks its capture contract.
+
+Casibase (https://github.com/casibase/casibase), licensed under Apache-2.0:
+
+    Copyright (c) The Casibase Authors
+
+  The Hanzo AI module (the /v1 AI, RAG, and search surfaces) derives from it.
+
+Casdoor (https://github.com/casdoor/casdoor), licensed under Apache-2.0:
+
+    Copyright (c) The Casdoor Authors
+
+  Hanzo IAM (hanzo.id) derives from it.

README.md

@@ -1,70 +1,75 @@
-# cloud
+<p align="center"><img src=".github/hero.svg" alt="Hanzo Cloud" width="880"></p>
 
-Unified Go control plane and binary for the Hanzo platform (HIP-0106).
+# Hanzo Cloud
+
+**The Open AI Cloud as one Go binary.** Identity, secrets, data, AI, gateway, observability, and the console — every Hanzo-native subsystem mounted into a single multi-org process. Per [HIP-0106](https://github.com/hanzoai/HIPs/blob/main/HIPs/hip-0106-unified-hanzo-cloud-binary.md).
 
 [![Status](https://img.shields.io/badge/status-beta-blue)]()
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)]()
 
+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 — one binary, one origin, no sidecars.
+
 ## Quick start
 
 ```bash
-docker run -p 8080:8080 ghcr.io/hanzoai/cloud:latest
+# Run the unified binary (pin a released version)
+docker run -p 8080:8080 ghcr.io/hanzoai/cloud:v1.801.206
+
+# Or install the CLI + server
+go install github.com/hanzoai/cloud/cmd/hanzo@latest
+brew install hanzoai/tap/hanzo
 ```
 
+Open <http://localhost:8080> for the embedded console; the API is served under `/v1` on the same origin.
+
 ## 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, tasks, …) into a single multi-org process. The 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.
 
-## Specs
+## `hanzo` — cloud control CLI
 
-Implements:
-- HIP-0014 Application Deployment
-- HIP-0026 IAM
-- HIP-0027 KMS
-- HIP-0037 AI Cloud Platform
-- HIP-0105 In-Process Extension Runtime
-- HIP-0106 Unified Cloud Binary
-- HIP-0302 Encrypted SQLite + ZapDB Durability
+The same binary is also a gcloud/doctl-class CLI. The first token selects the mode:
 
-## Architecture
+- `hanzo <subsystem>` — **server mode**: serve a subsystem (`hanzo iam`, `hanzo cloud`, …).
+- `hanzo <verb>` — **client mode**: control the live estate. A thin client over
+  Hanzo IAM (`hanzo.id`), the platform control plane (`platform.hanzo.ai/v1`),
+  and the cloud `/v1` API — it invents no parallel API.
 
-```
-                 api.{tenant}.{brand}
-                          |
-                   hanzoai/cloud (one Go binary)
-                          |
-   +----------+----------+----------+----------+----------+
-   |    iam   |   base   |   kms    |    ai    | gateway  | ...
-   |  Mount() |  Mount() |  Mount() |  Mount() |  Mount() |
-   +----------+----------+----------+----------+----------+
-   per-tenant SQLite (HIP-0302)   |   Hanzo IAM JWKS (HIP-0026)
-   replicate -> S3 (HIP-0107)     |   ZAP inter-subsystem RPC
+```bash
+hanzo login                       # IAM password grant against hanzo.id → token in ~/.hanzo (0600)
+hanzo whoami                      # identity from the stored token (--verify hits IAM userinfo)
+hanzo apps list                   # platform apps board: declared/running/latest tag + drift + health
+hanzo apps get <org>/<app>/<env>  # one app row
+hanzo deploy <container> --project <p> --env <e>   # rolling, zero-downtime redeploy
+hanzo clusters list|get|create|select|target       # dedicated DOKS cluster lifecycle
+hanzo build <repo> --sha <sha> --image <img>       # platform-native (arcd/Kaniko) build, no GitHub builders
+hanzo k8s target                  # the org's resolved deploy target (kubeconfig never returned)
+hanzo config set <k> <v>          # ~/.hanzo/config preferences
 ```
 
-Every subsystem exposes `func Mount(app *zip.App, deps cloud.Deps) error`. White-label fork pattern: customers fork this repo to launch their own ecosystem.
+Global flags: `--org`, `-o/--output table|json`, `--platform-url`, `--iam-issuer`,
+`--platform-token`. Tokens resolve from flag → env → `~/.hanzo` (never hardcoded):
+the IAM user token is the identity; the platform control plane is service-token
+authed (it cannot validate user tokens), so `apps`/`deploy`/`clusters` use
+`--platform-token` / `HANZO_PLATFORM_TOKEN` / `PLATFORM_SERVICE_TOKEN`, and
+`build` uses `HANZO_BUILD_TOKEN` / `PLATFORM_BUILD_CALLBACK_TOKEN`.
 
-
----
-
-# Hanzo Cloud
-
-The unified Go binary that imports every Hanzo-native subsystem and dispatches
-requests per deployment configuration. One artifact, many subsystems.
-
-Per [HIP-0106](https://github.com/hanzoai/HIPs/blob/main/HIPs/hip-0106-unified-hanzo-cloud-binary.md).
+Install: `go install github.com/hanzoai/cloud/cmd/hanzo@latest`, or `brew install hanzoai/tap/hanzo`.
 
 ## Subsystems mounted
 
-- `iam` — identity & access
-- `base` — per-tenant SQLite + extension runtimes (per HIP-0105)
-- `kms` — secrets
+Each subsystem exposes `func Mount(app *zip.App, deps cloud.Deps) error` and wires its own `/v1/<name>/*` routes onto the shared app.
+
+- `iam` — identity & access (users, orgs, roles, OIDC/JWKS per HIP-0026)
+- `base` — per-org SQLite + in-process extension runtimes (HIP-0105)
+- `kms` — secret custody (sealed secrets, HIP-0027)
 - `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)
+- `ai` — AI control plane: inference, RAG, model hub, agents, MCP management
 - `gateway` — HTTP routing + policy
 - `o11y` — metrics / traces / logs
 - `vfs` — virtual filesystem / object-store abstraction
 - `mq` — message queue
-- `dns`, `amqp`, `mcp`, `auto`, `tasks`, ... (full list per HIP-0106)
+- `dns`, `amqp`, `mcp`, `auto`, `tasks`, … — full list per HIP-0106
 
 ## Deployment modes
 
@@ -77,10 +82,27 @@ cloud --enable=iam,base,kms,commerce,ai,gateway,o11y --brand=lux    --domain=lux
 cloud --enable=iam,base,kms,commerce,ai,gateway,o11y --brand=zoo    --domain=zoo.cloud
 ```
 
+## Architecture
+
+```
+                 api.{org}.{brand}
+                          |
+                   hanzoai/cloud (one Go binary)
+                          |
+   +----------+----------+----------+----------+----------+
+   |    iam   |   base   |   kms    |    ai    | gateway  | ...
+   |  Mount() |  Mount() |  Mount() |  Mount() |  Mount() |
+   +----------+----------+----------+----------+----------+
+   per-org SQLite (HIP-0302)   |   Hanzo IAM JWKS (HIP-0026)
+   replicate -> S3 (HIP-0107)  |   ZAP inter-subsystem RPC
+```
+
+Every subsystem mounts through the same `Mount(app, deps)` seam. Cross-subsystem calls ride a narrow in-process interface; no subsystem reaches into another's store.
+
 ## White-label fork pattern
 
 Customers fork `hanzoai/cloud` to launch their own ecosystem in one binary. Brand
-detection, enabled subsystems, ZAP endpoints (payments / vault backends) are all
+detection, enabled subsystems, and ZAP endpoints (payments / vault backends) are all
 deployment configuration.
 
 ## Web framework
@@ -88,7 +110,72 @@ deployment configuration.
 [hanzoai/zip](https://github.com/hanzoai/zip) — Sinatra-style Go web framework
 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/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`).
+
+Pipeline (in the `Dockerfile`, before `go build`):
+
+```
+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
+```
+
+Serving (`webui.go`, registered LAST in `Serve` so it never shadows the API):
+
+- `GET /` and any client-side route (`/orgs`, `/models`, …) → the SPA shell
+  (`index.html`) with `Cache-Control: no-cache`; fingerprinted assets under
+  `assets/`/`_next/` are served `immutable` for a year, with brotli/gzip
+  precompressed negotiation when the build emits `.br`/`.gz` siblings.
+- `GET /v1/*` (and `/zap`, `/healthz`, …) → the API. Real subsystem routes are
+  registered before the console catch-all, so they always win; an **unmatched**
+  path under an API prefix returns a real 404 (JSON namespace), never HTML.
+- Same-origin: the embedded console calls `/v1` on its own host, so the session
+  cookie is first-party — no second origin, no CORS.
+
+`webui/dist/index.html` is a committed **fallback shell** (a real same-origin
+`/v1` bootstrap) so `go build` always compiles and the binary always serves a UI
+even without the Node toolchain. The image build overwrites `webui/dist` with the
+real console bundle. See `webui_test.go` for the boot-and-assert tests
+(`/` → shell, deep link → shell 200, `/v1/*` → API, unmatched `/v1` → 404).
+
+The `hanzoai/console` `build:embed` script (`scripts/build-embed.mjs`) 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).
+
+## Specs
+
+Implements:
+- HIP-0014 Application Deployment
+- HIP-0026 IAM
+- HIP-0027 KMS
+- HIP-0037 AI Cloud Platform
+- HIP-0105 In-Process Extension Runtime
+- HIP-0106 Unified Cloud Binary
+- HIP-0129 Open Cloud Planes
+- HIP-0302 Encrypted SQLite + ZapDB Durability
+
 ## Status
 
-Scaffold. The Mount(app, deps) integration for each subsystem lands per
-HIP-0106's migration phases.
+In production. The unified binary serves `api.hanzo.ai` and the white-label cloud
+surfaces today, with per-org SQLite (HIP-0302) and the embedded console. Subsystems
+continue to land per HIP-0106's migration phases; `apps/apps.go:Wire()` is the one
+ordered list of everything mounted. For repo-level engineering doctrine (module
+graph, route-table projections, cross-subsystem seams), see [`LLM.md`](./LLM.md).
+
+## Hanzo — the Open AI Cloud
+
+Open source · every language · on-chain settlement. [hanzo.ai](https://hanzo.ai) · [docs.hanzo.ai](https://docs.hanzo.ai)
+
+**SDKs in every language** — [Python](https://github.com/hanzoai/python-sdk) (flagship) · [TypeScript](https://github.com/hanzo-js/sdk) · [Go](https://github.com/hanzo-go/sdk) · [Rust](https://github.com/hanzo-rs/sdk) · [C++](https://github.com/hanzo-cpp/sdk) · [Swift](https://github.com/hanzo-swift/sdk) · [Kotlin](https://github.com/hanzo-kt/sdk) · [umbrella](https://github.com/hanzoai/sdk)

account_principal.go

@@ -0,0 +1,72 @@
+// Copyright 2026 Hanzo AI Inc. All Rights Reserved.
+
+package cloud
+
+import (
+	"net/http"
+
+	"github.com/hanzoai/cloud/clients/principal"
+	"github.com/zap-proto/zip"
+)
+
+// AccountFromPrincipal decomplects the console's IDENTITY onto the ONE truth every
+// /v1/admin/* call already authorizes on — the validated cloud principal — instead of
+// the embedded casibase account model.
+//
+// THE COMPLECTION IT REMOVES. The operator SPA authenticates via /v1/signin (a cloud
+// PKCE session → the X-User-* principal the middleware mints) but read its IDENTITY
+// from the account read, which the embedded IAM (casibase) answers from ITS OWN session
+// cookie. A PKCE session is not a casibase session, so that read returned
+// owner:"hanzo" (anonymous) or "Unauthorized operation" — and the SPA's SuperAdmin
+// gate (owner == "admin" && isAdmin), reading that, bounced the operator UI to login
+// even though the SAME session got 200 from every /v1/admin/* route. Two session
+// models for one surface; the identity source and the authorization source disagreed.
+//
+// THE DECOMPLECTION. Identity is now the principal: when a VALIDATED principal is
+// present (X-User-Id is set ONLY by IdentityMiddleware from a real credential, never a
+// raw client header — see middleware_identity.go), /v1/ai/account reflects it. owner
+// is the HOME org (principal.Owner) so a SuperAdmin org-switched into a tenant stays a
+// SuperAdmin; isAdmin is the validated bit. With NO principal it falls through
+// (c.Next()) to the casibase account surface unchanged — the anonymous sign-in page
+// and any legacy casibase-session caller are untouched. One truth, additive, fail-open
+// to the old path. MUST be registered AFTER IdentityMiddleware (needs the minted
+// headers) and BEFORE MountAll (so it precedes the casibase account handler).
+// accountPath is the account read this middleware fronts. It is a named constant
+// because the interception is a PATH MATCH: when the /v1 surface was namespaced
+// (/v1/get-account → /v1/ai/account) a literal left un-updated here would not
+// error — the middleware would simply stop firing, fall through to the casibase
+// account surface, and hand the SPA the anonymous owner again. That is precisely
+// the bug this file exists to fix, silently restored.
+const accountPath = "/v1/ai/account"
+
+func AccountFromPrincipal() zip.Handler {
+	return func(c *zip.Ctx) error {
+		if c.Method() != http.MethodGet || c.Path() != accountPath {
+			return c.Next()
+		}
+		user := c.User() // X-User-Id — minted only from a validated credential
+		if user == "" {
+			return c.Next() // no principal → the casibase account surface (unchanged)
+		}
+		owner := principal.Owner(c) // HOME org (a SuperAdmin stays one when org-switched)
+		if owner == "" {
+			owner = c.Org()
+		}
+		name := c.Header("X-User-Name")
+		if name == "" {
+			name = user
+		}
+		return c.JSON(http.StatusOK, map[string]any{
+			"status": "ok",
+			"msg":    "",
+			"data": map[string]any{
+				"owner":       owner,
+				"name":        name,
+				"displayName": name,
+				"email":       c.Header("X-User-Email"),
+				"isAdmin":     c.IsAdmin(),
+				"type":        "normal-user",
+			},
+		})
+	}
+}

apps/apps.go

@@ -0,0 +1,544 @@
+// 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"
+
+	"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/ask"
+	"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/benchmark"
+	"github.com/hanzoai/cloud/clients/billing"
+	"github.com/hanzoai/cloud/clients/blueprint"
+	"github.com/hanzoai/cloud/clients/books"
+	"github.com/hanzoai/cloud/clients/bots"
+	"github.com/hanzoai/cloud/clients/campaign"
+	"github.com/hanzoai/cloud/clients/captable"
+	"github.com/hanzoai/cloud/clients/catalogsync"
+	"github.com/hanzoai/cloud/clients/channels"
+	"github.com/hanzoai/cloud/clients/cloudflare"
+	"github.com/hanzoai/cloud/clients/code"
+	"github.com/hanzoai/cloud/clients/company"
+	"github.com/hanzoai/cloud/clients/compliance"
+	"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/destinations"
+	"github.com/hanzoai/cloud/clients/dns"
+	"github.com/hanzoai/cloud/clients/do"
+	"github.com/hanzoai/cloud/clients/domain"
+	"github.com/hanzoai/cloud/clients/entitlements"
+	"github.com/hanzoai/cloud/clients/eval"
+	"github.com/hanzoai/cloud/clients/exec"
+	"github.com/hanzoai/cloud/clients/experiments"
+	"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/help"
+	"github.com/hanzoai/cloud/clients/iam"
+	"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/leaderboard"
+	"github.com/hanzoai/cloud/clients/legal"
+	"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/prefs"
+	"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/research"
+	"github.com/hanzoai/cloud/clients/rollingcap"
+	"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/share"
+	"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/validators"
+	"github.com/hanzoai/cloud/clients/venue"
+	"github.com/hanzoai/cloud/clients/visor"
+	"github.com/hanzoai/cloud/clients/wallets"
+	"github.com/hanzoai/cloud/clients/webhooks"
+	"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 — pure fixture lanes that 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. (help is a framework lane too but ALSO mounts
+	// a thin /v1/help public plane, so it is a real import + a Wire() spec below,
+	// alongside knowledge — the other lane with a companion subsystem.)
+	_ "github.com/hanzoai/cloud/clients/cms"
+	_ "github.com/hanzoai/cloud/clients/erp"
+)
+
+// 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
+	})
+}
+
+// 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/*, /login/oauth/*) — the identity authority,
+		// mounts before its dependents. The ONE implementation: the clean-room iam-v2
+		// (zip-native + hanzoai/orm, beego-free); the retired Casdoor iam-v1 embed is GONE.
+		// STAGED: the operator adds "iam" to --enable only after IAM config + the fold are
+		// verified (login/authorize/token/jwks + the operator SSO chain).
+		{Name: "iam", Mount: iam.Mount},
+		// 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},
+		// Rolling AI-spend cap: installs the ai gate's per-tier trailing-window cap
+		// reader (registers no routes; its admin-editable knobs are platform switches
+		// surfaced in the /v1/admin/flags cockpit). After commerce/plan so the tier +
+		// finance globals it composes are wired.
+		{Name: "rollingcap", Mount: rollingcap.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, Shutdown: ctxShutdown(platform.Shutdown), OwnsHealth: true},
+		{Name: "projects", Mount: projects.Mount, Shutdown: ctxShutdown(projects.Shutdown)},
+		// 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},
+		// The registrar: search/price/register domains (name.com) per org.
+		{Name: "domain", Mount: domain.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},
+		// OSS-template compute-cost basis /v1/blueprint/* — parses a blueprint's
+		// docker-compose into its SBOM (bill of container images) and prices the
+		// stack's CPU/memory footprint through a documented rate card. The per-hour
+		// rate the deploy path meters an org on, and the "~$X/mo to run" the console
+		// shows; it is the compute cost the 20% author royalty (clients/authors) is
+		// taken from. OwnsHealth: serves its own /v1/blueprint/health. Reference
+		// content (embedded blueprints), no store → no Shutdown. After templates, its
+		// sibling catalog concern; before the AI /v1/* catch-all.
+		{Name: "blueprint", Mount: blueprint.Mount, OwnsHealth: true},
+		{Name: "framework", Mount: framework.Mount, Shutdown: ctxShutdown(framework.Shutdown)},
+		{Name: "knowledge", Mount: knowledge.Mount},
+		// Hanzo Support PUBLIC plane /v1/help/* (help center KB read + customer ticket
+		// intake) — the anonymous face the secure-by-default framework surface can't
+		// serve. A framework lane like knowledge: its DocType fixtures register via
+		// init() (help.Module), and this mounts the thin public subsystem. Owns no store
+		// (delegates to the framework in-process API), so no Shutdown. After framework
+		// (whose in-process API it calls at request time); before the AI /v1/* catch-all.
+		{Name: "help", Mount: help.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},
+		// The platform-global webhook layer: /v1/webhooks registry (per-org SQLite) +
+		// ONE durable JetStream consumer that delivers ANY bus event to org-registered
+		// HTTP subscribers. A bus consumer like catalogsync — placed adjacent to it and
+		// after the commerce embed whose COMMERCE stream it reads. Fail-soft: the
+		// registry serves even with the bus down; the consumer retries in the background.
+		// Owns per-org store handles + a worker pool → Shutdown drains both.
+		{Name: "webhooks", Mount: webhooks.Mount, Shutdown: webhooks.Shutdown},
+		{Name: "ml", Mount: ml.Mount, OwnsHealth: true},
+		{Name: "usage", Mount: usage.Mount},
+		// Gamified usage analytics: /v1/usage/leaderboard + /v1/usage/activity + the
+		// per-day contribution graph, over the datastore rollup (#43). Co-owns /v1/usage/*
+		// with usage (a distinct concern — who leads + your activity graph) at its own
+		// exact paths; owns the opt-in SQLite store. Before the ai /v1/* catch-all.
+		{Name: "leaderboard", Mount: leaderboard.Mount, Shutdown: leaderboard.Shutdown},
+		{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)},
+		// Top-level GTM orchestration /v1/campaign/* — the capability layer that fans a
+		// campaign VALUE out to its channels (paid→ads, organic→publish, email→marketing),
+		// each CONSUMING the connector plane via integrations.TokenFor. Metrics read from
+		// the ONE analytics plane (never a second store); creative A/B composes the
+		// experiment seam. The paid channel executor is wired in wire_seams.go. Owns a DB
+		// handle, so its Shutdown closes it cleanly on SIGTERM.
+		{Name: "campaign", Mount: campaign.Mount, Shutdown: ctxShutdown(campaign.Shutdown)},
+		// GDA/SDM validator onboarding /v1/validators/* — wallet-sig + ETH-mainnet
+		// GenesisNFT ownerOf → seal luxd staking identity into KMS → write a NEW-node
+		// LuxNetwork CR (node.lux.cloud, never the live luxd) → enqueue an owner-gated
+		// registration (never auto-submitted to any P-Chain). Owns a DB handle.
+		{Name: "validators", Mount: validators.Mount, Shutdown: ctxShutdown(validators.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},
+		// Connect-a-cloud-account plane /v1/cloud/*: an org links its DigitalOcean /
+		// AWS / GCP / Azure accounts (labeled, KMS-sealed, keyless where possible),
+		// Hanzo DISCOVERS each account's native Kubernetes clusters and FOLDS them into
+		// the ONE fleet (clients/fleet.Register) — so they surface in visor's
+		// /v1/clusters and run work like any BYO/managed cluster. No second registry.
+		{Name: "venue", Mount: venue.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},
+		// ngrok-native public sharing: /v1/share/* provisions a per-org zrok
+		// account so `hanzo share <port>` publishes a local service to a public
+		// https://<token>.share.hanzo.ai URL. Fail-closed until ZROK_ADMIN_TOKEN.
+		{Name: "share", Mount: share.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},
+		// Marketing destinations /v1/destinations/* — the native fan-out that
+		// TRANSLATES the canonical /v1/event stream to each connected ad/analytics
+		// platform (GA4 Measurement Protocol, Meta Conversions API, X/LinkedIn/TikTok/
+		// Reddit) and forwards it server-side. Mounts AFTER analytics (whose fan-out
+		// sink it installs) and integrations (a destination may reuse an OAuth
+		// connection's token via integrations.TokenFor). Owns a DB handle → Shutdown.
+		{Name: "destinations", Mount: destinations.Mount, Shutdown: ctxShutdown(destinations.Shutdown)},
+		// First-class per-org Cloudflare asset plane /v1/cloudflare/{zones,pages,workers,
+		// ai,r2,kv,d1}/* (sibling of /v1/dns, /v1/domain). Mounts AFTER integrations
+		// because it reads the org's Cloudflare token through the integrations custody
+		// seam (integrations.TokenFor) — one token, one custody boundary. Connecting the
+		// provider stays on the integrations plane; this plane only MANAGES resources.
+		{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: "prefs", Mount: prefs.Mount, Shutdown: prefs.Shutdown},
+		{Name: "notify", Mount: notify.Mount, OwnsHealth: true},
+		{Name: "channels", Mount: channels.Mount, Shutdown: channels.Shutdown},
+		{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: "benchmark", Mount: benchmark.Mount},
+		// The R&D EVIDENCE plane (HIP-0512) + its R&D Ops Board UI at /research —
+		// the arena's sibling: benchmark measures, research is the versioned diary
+		// every product's runs accrue into. Non-staged: mounts under the default.
+		{Name: "research", Mount: research.Mount, Shutdown: ctxShutdown(research.Shutdown)},
+		// The unified EXPERIMENT primitive (/v1/experiments): A/B testing as ONE value
+		// whatever the variant kind (feature | ad creative | email | model). It is a
+		// COMPOSITION — assignment via flags, measurement via analytics, evidence via
+		// research — so it mounts AFTER all three. It owns only the experiment registry
+		// store → Shutdown. clients/campaign composes it (experiments.Assign/Analyze).
+		{Name: "experiments", Mount: experiments.Mount, Shutdown: ctxShutdown(experiments.Shutdown)},
+		// The revenue BOOKS spine (/v1/books): a native double-entry general ledger that
+		// reads commerce transactions (the sole posting source) and books the accounting twin —
+		// plus bank import (PDF/OFX/CSV/Plaid/Teller), reconciliation, and the AI Ask brain.
+		{Name: "books", Mount: books.Mount, Shutdown: ctxShutdown(books.Shutdown)},
+		{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},
+		// The corporate back-office surfaces — orthogonal to company/captable/billing:
+		// Hanzo Compliance (/v1/compliance) orchestrates KYC/KYB verification providers
+		// + tracks accreditation state + surfaces the SOC 2 audit posture; Hanzo Legal
+		// (/v1/legal) is the versioned template + generation engine + e-sign/filing seams.
+		// Both are TOOLING with providers/professionals in the loop, never advice or
+		// certification. They mount before the /v1/* AI catch-all so their routes resolve.
+		{Name: "compliance", Mount: compliance.Mount, Shutdown: ctxShutdown(compliance.Shutdown), OwnsHealth: true},
+		{Name: "legal", Mount: legal.Mount, Shutdown: ctxShutdown(legal.Shutdown), OwnsHealth: true},
+		// 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 UNIFIED GROUNDED ADVISOR — POST /v1/ask. DISTINCT from /v1/chat/completions
+		// (ai's RAW model) and /v1/agent (tool-calling): it routes a plain-language question
+		// to the domain(s) that can GROUND it, reads the REAL figures from each domain's own
+		// endpoint IN-PROCESS under the caller's own creds (agent.go's replay pattern, so
+		// per-tenant isolation is inherited), hands the model the EXACT figures, and returns
+		// the grounded answer + figures + the domain reads that backed them. The model NEVER
+		// invents a figure. Contributors plug in via a registry (books today; o11y/billing
+		// next) WITHOUT a router edit. Mounts BEFORE the ai /v1/* catch-all so /v1/ask wins
+		// Fiber's first-match; after books/agent so the domains it composes are wired.
+		{Name: "ask", Mount: ask.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,535 @@
+// 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"
+	accountclient "github.com/hanzoai/cloud/clients/account"
+	"github.com/hanzoai/cloud/clients/commerceclient"
+	"github.com/hanzoai/cloud/clients/commerceinproc"
+	financeclient "github.com/hanzoai/cloud/clients/finance"
+	"github.com/hanzoai/cloud/clients/principal"
+	"github.com/hanzoai/commerce"
+	commercebilling "github.com/hanzoai/commerce/api/billing"
+	catalogapi "github.com/hanzoai/commerce/api/catalog"
+	planapi "github.com/hanzoai/commerce/api/plan"
+	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",
+	// Platform-admin catalog CMS: GET/POST/PUT/DELETE /v1/catalog/entries +
+	// POST /v1/catalog/seed — the SuperAdmin CRUD admin.hanzo.ai's editor drives.
+	// commerce's setupRoutes wires only the PUBLIC read (/v1/commerce/catalog);
+	// the CRUD lives on the standalone /v1 bundle (api.Route → catalogApi.AdminRoute),
+	// which the co-resident embed skips, so mountCommerce mounts it below on the
+	// same /v1 gate chain. Own the prefix here so it reaches commerce (each handler
+	// is requireSuperAdmin-gated) instead of the AI /v1/* balance catch-all.
+	"/v1/catalog",
+	// Platform-admin subscription/DNS plan authority CMS: GET/POST/PUT/DELETE
+	// /v1/plans/entries + POST /v1/plans/seed (increment 3a) — the SuperAdmin CRUD
+	// the console plan editor drives. The PUBLIC read stays GET /v1/billing/plans;
+	// this CRUD rides the /v1 bundle (api.Route → planApi.AdminRoute), which the
+	// embed skips, so mountCommerce mounts it below. Own the prefix so it reaches
+	// commerce (each handler requireSuperAdmin-gated), not the AI /v1/* 402 gate.
+	"/v1/plans",
+	// 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())
+
+	// Platform-admin catalog CMS on the SAME /v1 bundle: GET/POST/PUT/DELETE
+	// /v1/catalog/entries + POST /v1/catalog/seed. setupRoutes wires only the
+	// public read (/v1/commerce/catalog); the CRUD rides the standalone /v1 bundle
+	// (api.Route → catalogApi.AdminRoute), which the co-resident embed skips — so
+	// register it here, exactly as the standalone does. storeV1's IAMTokenRequired
+	// populates the claims each handler's requireSuperAdmin reads (anon → 403, a
+	// platform admin edits); it is cross-tenant data, never org-scoped.
+	catalogapi.AdminRoute(storeV1)
+
+	// Platform-admin subscription/DNS plan authority CRUD on the SAME /v1 bundle:
+	// GET/POST/PUT/DELETE /v1/plans/entries + POST /v1/plans/seed (increment 3a).
+	// Mirrors the catalog mount: the standalone wires it on the /v1 bundle
+	// (api.Route → planApi.AdminRoute), which the co-resident embed skips. The
+	// embed seed SOURCE is injected here (the composition root) — commercebilling.
+	// SeedRows, the SAME @hanzo/plans embed the boot seed + resolveSubscriptionPlan
+	// read — so api/plan never imports api/billing. Each handler is
+	// requireSuperAdmin-gated (anon → 403); prices are admin-editable but the mint
+	// gates score the IMMUTABLE embed, so an edit never moves a charge gate.
+	planapi.AdminRoute(storeV1, commercebilling.SeedRows)
+
+	// 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,
+	)
+
+	// GET /v1/billing/plans — the public tier catalog the console renders. commerce's
+	// legacy api.Route() billing bundle (ListPlans, invoices, subscriptions, …) is NOT
+	// registered by the co-resident embed: setupRoutes wires only /v1/commerce/*, so
+	// /v1/billing/plans has NO handler in this binary. The account bridge's
+	// /v1/billing/* wildcard (order 122) then forwards the read BACK to commerce at
+	// COMMERCE_URL — which defaults to the public api.hanzo.ai edge — re-entering the
+	// same bridge in an unbounded self-dispatch loop that surfaces as a 502
+	// ("commerce unreachable: Get https://api.hanzo.ai/v1/billing/plans"). Registering
+	// the static ListPlans handler HERE (order 100, ahead of the bridge) shadows that
+	// wildcard and serves plans in-process — the same co-resident move billing.go makes
+	// for usage/balance. RequestContext supplies the namespaced context promo.Active reads.
+	app.Get("/v1/billing/plans", commercemid.RequestContext(), commercebilling.ListPlans)
+
+	// The rest of the console's billing READS, served co-resident for the SAME reason
+	// plans is: commerce's api.Route() billing bundle is never compiled here, so without
+	// these registrations every one of them falls through to the account bridge's
+	// /v1/billing/* wildcard, which forwards to COMMERCE_URL — the public api.hanzo.ai
+	// edge, which is THIS binary — and self-dispatches into a 502 loop. In prod there is
+	// no separate commerce backend to point COMMERCE_URL at (the in-cluster `commerce`
+	// Service selects the cloud pods), so co-residence is the only way to break the loop.
+	//
+	// Chain: RequestContext (gated context) → IAMTokenRequired (resolves the org from the
+	// gateway-validated X-Org-Id into Locals("organization"), the namespace commerce's
+	// GetOrganization reads) → PinBillingSubject (pins the caller's OWN billing subject
+	// into the query — the SAME isolation the bridge applies, so a read can never widen
+	// past the caller; fail-closed for an unvalidated caller) → the commerce handler. The
+	// specific paths shadow the bridge wildcard (order 100 < 122). payment-config is
+	// org-scoped, not subject-scoped, but PinBillingSubject is still the auth gate that
+	// keeps an unvalidated caller from reaching GetOrganization; its pinned (unused)
+	// subject params are ignored by that handler.
+	billingRead := []struct {
+		path string
+		h    zip.Handler
+	}{
+		{"/v1/billing/invoices", commercebilling.ListInvoices},
+		{"/v1/billing/invoices/:id/pdf", commercebilling.DownloadInvoicePDF},
+		{"/v1/billing/subscriptions", commercebilling.ListBillingSubscriptions},
+		{"/v1/billing/spend-alerts", commercebilling.ListSpendAlerts},
+		{"/v1/billing/payouts", commercebilling.ListPayouts},
+		{"/v1/billing/payment-config", commercebilling.GetPaymentConfig},
+	}
+	for _, r := range billingRead {
+		app.Get(r.path,
+			commercemid.RequestContext(),
+			iammiddleware.IAMTokenRequired(),
+			accountclient.PinBillingSubject(),
+			r.h,
+		)
+	}
+
+	// GET /v1/billing/spend-alerts/authorize — the per-request per-scope spend-CAP
+	// VERDICT the request-edge metering gate consumes (clients/metering scopeAuthorize,
+	// pathLimitsAuthorize). It is a SERVICE-token S2S read (COMMERCE_SERVICE_TOKEN +
+	// X-Org-Id), NOT a browser/IAM read — so it needs its OWN registration, distinct from
+	// the console billingRead block above: without a co-resident handler this authorize
+	// fell through to the account bridge's /v1/billing/* wildcard (order 122), which — being
+	// service-token-forwardable (billing.go billingForwardable) — re-forwarded it to
+	// COMMERCE_URL (the public api.hanzo.ai edge = THIS binary) over commerceinproc's
+	// self-routing transport, re-entering the same wildcard until the depth-8 guard refused
+	// → 502 → the gate fails OPEN (the cap is a policy overlay, so no traffic was blocked,
+	// but ~135 502s/30m spammed the money path and each burned 8 full-app dispatches). The
+	// plain GET /v1/billing/spend-alerts (registered above) already broke this loop for the
+	// CRUD read; this closes the /authorize sibling the metering gate hits on every call.
+	//
+	// Chain mirrors commerce's OWN gate on this route (api/billing/handlers.go: the `billing`
+	// group's userRequired = TokenRequired) plus the RequestContext the standalone supplies
+	// globally — NOT the IAM/PinBillingSubject console chain: a raw service token is not an
+	// IAM JWT, so IAMTokenRequired would leave GetOrganization unset and AuthorizeSpendCap
+	// would 500. TokenRequired authenticates the service token AND resolves the tenant from
+	// the gateway-pinned X-Org-Id into Locals("organization"), which AuthorizeSpendCap reads.
+	// The specific route shadows the bridge wildcard (order 100 < 122). No PlatformOnly:
+	// authorize is a per-org cap read, not a cross-org mint (unlike auto-recharge/run-all).
+	app.Get("/v1/billing/spend-alerts/authorize",
+		commercemid.RequestContext(),
+		commercemid.TokenRequired(),
+		commercebilling.AuthorizeSpendCap,
+	)
+
+	// Self-service spend-cap CRUD WRITES — the customer half of the cap: a customer
+	// (or the admin S2S) CREATES / EDITS / REMOVES their own usage caps. These are the
+	// write siblings of the co-resident GET /v1/billing/spend-alerts list; without their
+	// own registration they too fell through the account bridge's /v1/billing/* wildcard
+	// (billingForwardable includes POST spend-alerts) into the SAME 502 self-dispatch loop
+	// authorize hit — so a customer could not set a cap AT ALL in the unified binary
+	// (POST/PATCH/DELETE all 502'd). Same chain commerce's own route table gates them with
+	// (api/billing/handlers.go:322-325, the `user` group's userRequired = TokenRequired) +
+	// the global RequestContext — an IAM JWT OR the COMMERCE_SERVICE_TOKEN, org resolved
+	// from the gateway-pinned X-Org-Id into Locals("organization"). Org-scoped by that
+	// namespace (a caller only ever writes their OWN org's caps; a foreign :id is a
+	// not-found miss in the caller's namespace), so no PinBillingSubject — spend-alerts are
+	// org-level, not billing-subject-level. Shadow the bridge wildcard (order 100 < 122).
+	// A spend cap is a FINANCIAL SAFETY control, so its writes are gated to an ORG ADMIN
+	// (or SuperAdmin, or the trusted S2S service token for the SuperAdmin cap-oversight
+	// Forward) — never any authenticated member. commerce's own `user` group admits any
+	// member, which would let a compromised member key DELETE the org's cap (→ unbounded
+	// spend) or POST a 1¢ enforce cap (→ org-wide 402 DoS). requireSpendCapAdmin closes that.
+	app.Post("/v1/billing/spend-alerts",
+		commercemid.RequestContext(),
+		commercemid.TokenRequired(),
+		requireSpendCapAdmin(),
+		commercebilling.CreateSpendAlert,
+	)
+	app.Patch("/v1/billing/spend-alerts/:id",
+		commercemid.RequestContext(),
+		commercemid.TokenRequired(),
+		requireSpendCapAdmin(),
+		commercebilling.UpdateSpendAlert,
+	)
+	app.Delete("/v1/billing/spend-alerts/:id",
+		commercemid.RequestContext(),
+		commercemid.TokenRequired(),
+		requireSpendCapAdmin(),
+		commercebilling.DeleteSpendAlert,
+	)
+
+	// POST /v1/billing/topup/token — the INLINE Square card top-up (the console's
+	// "Billing → Credits → add credits": the Square Web Payments SDK tokenizes the card
+	// IN THE BROWSER → a single-use nonce → this endpoint charges it and credits the
+	// caller's balance). commerce's api.Route() billing bundle is NOT compiled into the
+	// co-resident embed, so — exactly like plans/invoices/spend-alerts above — without
+	// this registration the POST fell through to the account bridge's /v1/billing/*
+	// wildcard (order 122). That wildcard is service-token-forwardable for topup/token
+	// (billing.go billingForwardable), so billingData re-forwarded it to COMMERCE_URL
+	// (default the public api.hanzo.ai edge = THIS binary) over commerceinproc's
+	// self-routing transport, re-entering the SAME wildcard until the depth-8 guard
+	// refused → the "commerceinproc: in-process dispatch depth 8 exceeded" 502 that broke
+	// top-up outright. Registering commerce's real TopupWithToken co-resident here
+	// (order 100 < 122) shadows the wildcard and serves the charge in-process at depth 1
+	// — no HTTP hop, no self-dispatch. topup/token STAYS in billingForwardable as the
+	// split-deploy fallback (a standalone commerce still serves it); co-residence just
+	// wins first.
+	//
+	// Chain — the browser money-WRITE posture, byte-for-byte what the bridge applied:
+	//   RequireCSRF        — the ambient-cookie anti-CSRF gate the bridge's requireCSRF
+	//                        wrapped POST /v1/billing/* with (a Bearer/gateway caller is
+	//                        not CSRF-able; an ambient-cookie write needs the token).
+	//   RequestContext     — the gated request context commerce's handler + ledger read.
+	//   IAMTokenRequired   — resolves the org from the gateway-validated X-Org-Id into
+	//                        Locals("organization"), which TopupWithToken.GetOrganization
+	//                        + topupDestination read as the org billing key.
+	//   PinBillingSubject  — pins ?user= to the caller's OWN account.Payer subject (the
+	//                        SAME rule the ai spend-gate debits and billingData pins), so
+	//                        the credit lands on the caller's subject (person=org/name) and
+	//                        can never be widened; fail-closed for an unvalidated caller —
+	//                        the IDOR boundary stays exactly where billingData put it.
+	// The card PAN never touches this binary: TopupWithToken charges the Square nonce only,
+	// and the settled charge itself is the mint authority (mintauth.WithAuthorized).
+	app.Post("/v1/billing/topup/token",
+		accountclient.RequireCSRF(),
+		commercemid.RequestContext(),
+		iammiddleware.IAMTokenRequired(),
+		accountclient.PinBillingSubject(),
+		commercebilling.TopupWithToken,
+	)
+
+	// The remaining console billing WRITES that share topup/token's self-dispatch loop
+	// class — each is a POST the console makes (billingForwardable in billing.go), each had
+	// NO co-resident handler, so each fell through to the account bridge's /v1/billing/*
+	// wildcard (order 122) and re-entered it over commerceinproc until the depth-8 guard
+	// refused (the same "in-process dispatch depth 8 exceeded" 502 that broke top-up). Each
+	// commerce handler exists in the vendored module (v1.49.13); registering them co-resident
+	// (order 100 < 122) shadows the wildcard and serves the write in-process at depth 1. They
+	// STAY in billingForwardable as the split-deploy fallback (same precedent as topup/token
+	// + spend-alerts). Chain matches the bridge's write posture byte-for-byte:
+	//
+	//   - RequireCSRF        — the ambient-cookie anti-CSRF gate the bridge wrapped POST
+	//                          /v1/billing/* with (Bearer/gateway callers are not CSRF-able).
+	//   - RequestContext     — the gated request context commerce's handlers read.
+	//   - IAMTokenRequired   — resolves the org from the gateway-validated X-Org-Id into
+	//                          Locals("organization") — the namespace GetOrganization reads.
+	//   - PinBillingSubject  — pins the caller's OWN account.Payer subject into BOTH query and
+	//                          body AND fail-closes an unvalidated caller. It is the auth gate
+	//                          on every one, and the IDOR control on the subject-scoped one.
+	//
+	// payment-methods (save a card-on-file / vault a Square nonce) is SUBJECT-scoped: commerce's
+	// CreatePaymentMethod reads `customerId` from the BODY, so PinBillingSubject's body-pin is
+	// load-bearing here — a member can only vault a card for their OWN subject, exactly the
+	// boundary billingData's scopedBillingBody enforced. The Square nonce goes to Square; the
+	// PAN never touches this binary.
+	app.Post("/v1/billing/payment-methods",
+		accountclient.RequireCSRF(),
+		commercemid.RequestContext(),
+		iammiddleware.IAMTokenRequired(),
+		accountclient.PinBillingSubject(),
+		commercebilling.CreatePaymentMethod,
+	)
+
+	// subscriptions/:id/{cancel,reactivate} are org-NAMESPACE-scoped: commerce's handlers
+	// resolve the subscription by `:id` WITHIN the caller's org namespace (a foreign org's id
+	// is a 404 miss), so tenancy is the namespace IAMTokenRequired resolves and PinBillingSubject
+	// is the fail-closed-anon auth gate — its pinned subject params are ignored by these
+	// handlers (the SAME role it plays for the org-scoped payment-config read). The bridge's
+	// subject-pin was likewise a no-op for these, so nothing is dropped.
+	app.Post("/v1/billing/subscriptions/:id/cancel",
+		accountclient.RequireCSRF(),
+		commercemid.RequestContext(),
+		iammiddleware.IAMTokenRequired(),
+		accountclient.PinBillingSubject(),
+		commercebilling.CancelBillingSubscription,
+	)
+	app.Post("/v1/billing/subscriptions/:id/reactivate",
+		accountclient.RequireCSRF(),
+		commercemid.RequestContext(),
+		iammiddleware.IAMTokenRequired(),
+		accountclient.PinBillingSubject(),
+		commercebilling.ReactivateBillingSubscription,
+	)
+
+	// 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)
+}
+
+// requireSpendCapAdmin gates a spend-alert WRITE to a validated ORG ADMIN or platform
+// SuperAdmin (the unforgeable SanitizeIdentity-minted X-User-IsOrgAdmin / isAdmin bits),
+// OR the trusted in-proc S2S service token (the SuperAdmin cap-oversight Forward + internal
+// automation). A validated non-admin MEMBER is REFUSED (403): a spend cap is a financial
+// safety boundary — a member must not be able to delete the org's cap (→ unbounded spend)
+// or set a punitive 1¢ cap (→ org-wide 402 DoS). The read paths (list/authorize) stay
+// member/S2S-open; only the mutations require admin.
+func requireSpendCapAdmin() zip.Handler {
+	return func(c *zip.Ctx) error {
+		if principal.IsSuperAdmin(c) || principal.IsOrgAdmin(c) || accountclient.IsServiceToken(c) {
+			return c.Next()
+		}
+		return zip.ErrForbidden("org admin required to change spend caps")
+	}
+}

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,120 @@
+// 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,
+		"/v1/catalog":               false,
+		"/v1/plans":                 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")
+	}
+
+	// The platform-admin catalog CMS (admin.hanzo.ai's editor) must reach commerce —
+	// where each handler is requireSuperAdmin-gated (anon → 401/403) — never the AI
+	// /v1/* balance gate, which would 402 the editor's list/edit instead.
+	if code, _ := doReq(t, app, http.MethodGet, "/v1/catalog/entries"); code == http.StatusPaymentRequired {
+		t.Fatalf("GET /v1/catalog/entries fell through to the AI balance gate (402) — /v1/catalog must be a commercePrefix so the SuperAdmin CMS reaches commerce")
+	}
+	if code, _ := doReq(t, app, http.MethodPut, "/v1/catalog/entries/cloud-starter"); code == http.StatusPaymentRequired {
+		t.Fatalf("PUT /v1/catalog/entries/:slug fell through to the AI balance gate (402) — the whole catalog CMS must be commerce-owned")
+	}
+
+	// The platform-admin plan authority CMS (increment 3a) must also reach commerce —
+	// requireSuperAdmin-gated (anon → 401/403) — never the AI /v1/* 402 gate.
+	if code, _ := doReq(t, app, http.MethodGet, "/v1/plans/entries"); code == http.StatusPaymentRequired {
+		t.Fatalf("GET /v1/plans/entries fell through to the AI balance gate (402) — /v1/plans must be a commercePrefix so the plan authority CMS reaches commerce")
+	}
+	if code, _ := doReq(t, app, http.MethodPut, "/v1/plans/entries/pro"); code == http.StatusPaymentRequired {
+		t.Fatalf("PUT /v1/plans/entries/:slug fell through to the AI balance gate (402) — the whole plan authority CMS 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,35 @@
+package apps
+
+import (
+	"testing"
+
+	"github.com/hanzoai/cloud/clients/framework"
+)
+
+// TestFrameworkContentModulesLinked guards the framework CONTENT modules
+// (cms/erp/help) against silent removal. cms/erp are pure fixture lanes reached
+// ONLY via blank imports in apps.go; help is a real import + a Wire() spec (it also
+// mounts the /v1/help public plane) but still contributes its DocTypes the SAME way,
+// from a package init() (framework.RegisterModule). #248 dropped the blank 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 — for help, dropping the import
+// would also drop its Wire() spec and fail TestWireOrderMatchesFrozen, but this keeps
+// the fixture-linkage guard uniform across all three lanes.
+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,122 @@
+package apps
+
+import (
+	"context"
+	"encoding/json"
+	"time"
+
+	"github.com/hanzoai/cloud/clients/ads"
+	"github.com/hanzoai/cloud/clients/automations"
+	"github.com/hanzoai/cloud/clients/campaign"
+	"github.com/hanzoai/cloud/clients/coding"
+	"github.com/hanzoai/cloud/clients/experiments"
+	"github.com/hanzoai/cloud/clients/framework"
+	"github.com/hanzoai/cloud/clients/git"
+	"github.com/hanzoai/cloud/clients/guide"
+	"github.com/hanzoai/cloud/clients/integrations"
+	"github.com/hanzoai/cloud/clients/principal"
+)
+
+// 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))
+
+	// Guide growth-OBSERVE seam: the /v1/guide/profile observe layer reads the org's
+	// real platform truth through injected, org-scoped, honest-degrading probes.
+	// clients/guide imports NONE of these subsystems (decomplected), so the
+	// composition root — the ONE place that imports them all — binds the reads, the
+	// same injected-function pattern the coding dispatcher above uses. Each probe is
+	// PROVABLY org-scoped: framework.ModuleInstalled keys GetDocType on the org;
+	// integrations.Connected keys store.Get on the org and never surfaces the token.
+	// HasDeployment/RevenueCents/RecordCount are LEFT NIL: deploy is cluster/admin-
+	// scoped (not per-org) and commerce-revenue-of-record + the crm record count have
+	// no clean per-org in-process read yet — binding a read whose org-scoping we
+	// cannot guarantee would be the bug. Until a provably-org-scoped read lands their
+	// signals honest-degrade to not-present (the vocabulary is the contract; a nil
+	// seam can never be a spurious true).
+	guide.BindSignals(guide.Signals{
+		ModuleInstalled:  framework.ModuleInstalled,
+		ConnectorPresent: integrations.Connected,
+	})
+
+	// Inbound-event seam: a verified provider webhook (or chat channel) in
+	// clients/integrations fires the automations engine's Deliver here — the ONE place
+	// that imports both, so integrations never has to import automations (which imports
+	// it, for credential custody). A primitive-typed adapter keeps the seam free of the
+	// automations types.
+	integrations.SetAutomationTrigger(func(ctx context.Context, org, source, name, dedupeKey string, depth int, payload map[string]any) (int, error) {
+		return automations.Deliver(ctx, org, automations.TriggerEvent{
+			Source: source, Name: name, DedupeKey: dedupeKey, Depth: depth, Payload: payload,
+		})
+	})
+
+	// GTM PAID channel: the /v1/campaign orchestrator fans out to executors that
+	// satisfy campaign.Channel; the composition root is the ONE place that imports
+	// both campaign and the ad plane, so it adapts ads' connector-consuming
+	// execution funcs (provider.go — each resolves the org's ad token through
+	// integrations.TokenFor and fails closed) onto the primitive-typed channel
+	// seam. campaign never imports ads and ads never imports campaign — the same
+	// injected-function decoupling the coding dispatcher above uses.
+	campaign.RegisterChannel(campaign.NewChannel(campaign.KindPaid,
+		func(ctx context.Context, org string, p campaign.Plan) (campaign.Ref, error) {
+			r, err := ads.LaunchPaid(ctx, org, ads.PaidPlan{
+				Platform: p.Platform, Account: p.Account, Name: p.Name,
+				Objective: p.Objective, BudgetCents: p.BudgetCents, ScheduleAt: p.ScheduleAt,
+			})
+			return campaign.Ref{Platform: r.Platform, Account: r.Account, ExternalID: r.ExternalID, Status: r.Status, Detail: r.Detail}, err
+		},
+		func(ctx context.Context, org string, ref campaign.Ref) (int64, error) {
+			return ads.PaidSpend(ctx, org, ads.PaidRef{Platform: ref.Platform, Account: ref.Account, ExternalID: ref.ExternalID})
+		},
+		func(ctx context.Context, org string, ref campaign.Ref) error {
+			return ads.PausePaid(ctx, org, ads.PaidRef{Platform: ref.Platform, Account: ref.Account, ExternalID: ref.ExternalID})
+		},
+	))
+
+	// GTM creative A/B composes the merged EXPERIMENT primitive (clients/experiments)
+	// — campaign never reinvents bucketing or measurement. Assign resolves the
+	// subject's variant (creative) from the experiment's flag; Analyze is pull-model
+	// (it reads the metric from analytics itself), returned as opaque JSON so
+	// campaign stays decoupled from the analysis type. Campaign-linked experiments
+	// live in the org's default project. Both are nil-safe upstream: an org that
+	// never created a "campaign:<id>" experiment runs a single creative (Assign
+	// errors → "" → Content[0]).
+	campaign.SetExperiment(
+		func(ctx context.Context, org, experimentID, subject string) (string, error) {
+			a, err := experiments.Assign(ctx, org, principal.DefaultProject, experimentID, subject, nil)
+			if err != nil {
+				return "", err
+			}
+			return a.Variant, nil
+		},
+		func(ctx context.Context, org, experimentID string, start, end time.Time) (json.RawMessage, error) {
+			an, err := experiments.Analyze(ctx, org, principal.DefaultProject, experimentID, start, end, 0.05)
+			if err != nil {
+				return nil, err
+			}
+			return json.Marshal(an)
+		},
+	)
+
+	// GTM ORGANIC + EMAIL channels wire HERE the same way once their executors land
+	// (designed follow-ons — the publish rename + marketing email-connector wiring):
+	//
+	//   campaign.RegisterChannel(campaign.NewChannel(campaign.KindOrganic,
+	//       publish.Syndicate, publish.NoSpend, publish.Unpublish))   // social connectors
+	//   campaign.RegisterChannel(campaign.NewChannel(campaign.KindEmail,
+	//       marketing.Broadcast, marketing.NoSpend, marketing.Halt))  // email connectors
+	//
+	// Until wired, those channels record "unavailable" on a fan-out (honest) and a
+	// campaign runs a single creative — never a fabricated launch or variant.
+}

apps/wire_test.go

@@ -0,0 +1,173 @@
+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
+	{"rollingcap", false, false},     // rolling spend-cap gate (after billing); golden drifted — refrozen
+	{"account-bridge", false, false}, // was order 122
+	{"do", false, false},             // was order 123
+	{"platform", true, true},         // was order 124
+	{"projects", false, true},        // was order 125
+	{"dns", false, false},            // new: /v1/dns zone plane (after projects)
+	{"domain", false, false},         // new: Hanzo Domains registrar (/v1/domain), after dns
+	{"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
+	{"blueprint", true, false},       // new: OSS-template compute-cost basis /v1/blueprint (after templates); owns health, embedded content → no Shutdown
+	{"framework", false, true},       // was order 129
+	{"knowledge", false, false},      // was order 130
+	{"help", false, false},           // new: Hanzo Support public plane /v1/help (after knowledge; framework lane with a companion subsystem, no store → no Shutdown)
+	{"content", false, true},         // new: marketing content loop (after knowledge)
+	{"catalogsync", false, true},     // new: reverse loop (product.created → render) after content
+	{"webhooks", false, true},        // new: platform-global /v1/webhooks registry + bus-driven dispatcher (after catalogsync); owns per-org stores + worker pool → Shutdown
+	{"ml", true, false},              // was order 130
+	{"usage", false, false},          // was order 131
+	{"leaderboard", false, true},     // new: gamified usage analytics (after usage), owns opt-in SQLite (Shutdown)
+	{"crm", false, false},            // was order 131
+	{"marketing", false, true},       // new: marketing domain fold (after crm)
+	{"ads", false, true},             // new: ads domain fold (after crm)
+	{"campaign", false, true},        // new: /v1/campaign GTM orchestration (after ads); fans out to channels
+	{"validators", false, true},      // new: NFT-gated node provisioning (after ads); golden refrozen
+	{"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
+	{"venue", false, false},          // new: /v1/cloud connect-a-cloud-account plane (after visor); folds discovered clusters into the fleet
+	{"captable", false, true},        // was order 133
+	{"code", false, true},            // was order 134
+	{"zero-trust", false, false},     // was order 134
+	{"share", false, false},          // ngrok-native public sharing (/v1/share/*)
+	{"dataroom", true, true},         // was order 134
+	{"graph", false, false},          // was order 135
+	{"security", true, true},         // was order 136
+	{"integrations", false, true},    // was order 137
+	{"destinations", false, true},    // new: /v1/destinations CDP fan-out (after integrations, before cloudflare)
+	{"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
+	{"prefs", false, true},           // new: per-user preference plane (after settings); Shutdown closes the store
+	{"notify", true, false},          // was order 139
+	{"channels", false, true},        // new: /v1/channels transport plane (after notify; must mount after integrations so RegisterIngress installs before webhooks emit)
+	{"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
+	{"benchmark", false, false},      // benchmark plane (after evals, before treasury)
+	{"research", false, true},        // R&D evidence plane + /research board (HIP-0512), arena sibling after benchmark; Shutdown closes per-org stores
+	{"experiments", false, true},     // unified A/B EXPERIMENT primitive: composes flags(assign)+analytics(measure)+research(evidence); Shutdown closes the registry stores
+	{"books", false, true},           // AI bookkeeper (/v1/books, per-org SQLite); Shutdown closes org stores
+	{"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)
+	{"compliance", true, true},       // new: Hanzo Compliance — KYC/KYB + accreditation + audit posture (after company)
+	{"legal", true, true},            // new: Hanzo Legal — template + generation engine + e-sign/filing (after compliance)
+	{"agent", false, false},          // new: /v1/agent tool-calling round (before zen/ai catch-all)
+	{"ask", false, false},            // new: unified grounded advisor /v1/ask (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_key_test.go

@@ -0,0 +1,64 @@
+// Copyright 2026 Hanzo AI Inc. All Rights Reserved.
+
+package apps
+
+import (
+	"context"
+	"errors"
+	"testing"
+)
+
+// stubKMS is a KMSClient whose GetSecret returns a sealed value when present or a
+// not-found error otherwise — mirroring the co-resident store that, in production,
+// holds no upstream provider keys (they are provisioned as KMS-injected env).
+type stubKMS struct{ sealed map[string]string }
+
+func (s stubKMS) GetSecret(_ context.Context, ref string) ([]byte, error) {
+	if v, ok := s.sealed[ref]; ok {
+		return []byte(v), nil
+	}
+	return nil, errors.New("secret not found")
+}
+func (stubKMS) PutSecret(context.Context, string, []byte) error      { return nil }
+func (stubKMS) Sign(context.Context, string, []byte) ([]byte, error) { return nil, nil }
+
+// TestZenKeyResolver_EnvFallback pins the production wiring: the upstream provider
+// key is provisioned as env (from the cloud-api-llm-keys secret), NOT sealed in the
+// co-resident KMS store, so a KMS miss must resolve to the env value rather than
+// returning "" (which would send an empty bearer upstream → provider 401).
+func TestZenKeyResolver_EnvFallback(t *testing.T) {
+	const env = "DO_AI_API_KEY"
+	t.Setenv(env, "env-provisioned-key")
+
+	// KMS store has no upstream keys (the real deployment state) — resolve from env.
+	if got := zenKeyResolver(stubKMS{})(context.Background(), env); got != "env-provisioned-key" {
+		t.Fatalf("KMS-miss: got %q, want env value", got)
+	}
+
+	// A nil KMS client (KMS disabled) — still resolve from env.
+	if got := zenKeyResolver(nil)(context.Background(), env); got != "env-provisioned-key" {
+		t.Fatalf("nil-KMS: got %q, want env value", got)
+	}
+}
+
+// TestZenKeyResolver_EnvTakesPrecedence pins the resolution ORDER: env is read
+// FIRST, then KMS — the same order ai uses on the prod hot path. The operator
+// injects provider keys as env from the KMS-synced secret, so the env is the live
+// value; the co-resident store is the fallback. A key present in BOTH surfaces
+// resolves to the env value.
+func TestZenKeyResolver_EnvTakesPrecedence(t *testing.T) {
+	const env = "ANTHROPIC_API_KEY"
+	t.Setenv(env, "env-key")
+	got := zenKeyResolver(stubKMS{sealed: map[string]string{env: "sealed-key"}})(context.Background(), env)
+	if got != "env-key" {
+		t.Fatalf("got %q, want env-key (env precedence)", got)
+	}
+}
+
+// TestZenKeyResolver_AbsentEverywhere keeps the fail-fast contract: absent from both
+// surfaces resolves to "" so zen refuses rather than serving for free.
+func TestZenKeyResolver_AbsentEverywhere(t *testing.T) {
+	if got := zenKeyResolver(stubKMS{})(context.Background(), "MISSING_KEY_XYZ"); got != "" {
+		t.Fatalf("got %q, want empty", got)
+	}
+}

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)
+		}
+	}
+}

audit/audit_test.go

@@ -0,0 +1,623 @@
+package audit
+
+// Tests for the tamper-evident audit chain. They exercise the REAL SQLite store
+// (an on-disk temp db, not a mock) so the append-only write path, the hash-chain
+// math, the verifier, redaction, and the filtered query are all proven
+// end-to-end. The headline test is tamper-detection: a record edited directly in
+// the database is DETECTED as breaking the chain.
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+// openTemp opens a Recorder backed by a fresh on-disk SQLite file (not :memory:,
+// because tamper tests re-open the same file via a second connection to edit it
+// out-of-band — exactly what an attacker with DB access would do).
+func openTemp(t *testing.T) (*Recorder, string) {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "audit.db")
+	rec, err := Open(path, nil)
+	if err != nil {
+		t.Fatalf("Open: %v", err)
+	}
+	t.Cleanup(func() { _ = rec.Close() })
+	return rec, path
+}
+
+// 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),
+		Actor:     Actor{Org: "admin", Sub: "z@hanzo.ai", Email: "z@hanzo.ai"},
+		Action:    action,
+		Resource:  Resource{Type: "org", ID: "acme"},
+		Auth:      AuthContext{Method: "jwt", IsAdmin: true},
+		Outcome:   Outcome{Result: "success", Status: 200},
+		SourceIP:  "203.0.113.7",
+		UserAgent: "console",
+		RequestID: "req-123",
+		Method:    "DELETE",
+		Path:      "/v1/admin/orgs/acme",
+	}
+}
+
+// TestChain_AppendSealsAndLinks proves each appended record gets a monotonic seq,
+// links its PrevHash to the previous record's Hash, and starts from the genesis
+// anchor.
+func TestChain_AppendSealsAndLinks(t *testing.T) {
+	rec, _ := openTemp(t)
+	ctx := context.Background()
+
+	r0, err := rec.Append(ctx, sampleRecord("DELETE /v1/admin/orgs"))
+	if err != nil {
+		t.Fatalf("append 0: %v", err)
+	}
+	if r0.Seq != 0 {
+		t.Fatalf("first seq = %d, want 0", r0.Seq)
+	}
+	if r0.PrevHash != genesisPrevHash {
+		t.Fatalf("genesis prev = %q, want %q", r0.PrevHash, genesisPrevHash)
+	}
+	if r0.Hash == "" || r0.Hash == genesisPrevHash {
+		t.Fatalf("hash not computed: %q", r0.Hash)
+	}
+
+	r1, err := rec.Append(ctx, sampleRecord("POST /v1/admin/roles"))
+	if err != nil {
+		t.Fatalf("append 1: %v", err)
+	}
+	if r1.Seq != 1 {
+		t.Fatalf("second seq = %d, want 1", r1.Seq)
+	}
+	if r1.PrevHash != r0.Hash {
+		t.Fatalf("link broken: r1.prev=%q, r0.hash=%q", r1.PrevHash, r0.Hash)
+	}
+	if r1.Hash == r0.Hash {
+		t.Fatal("distinct records must have distinct hashes")
+	}
+}
+
+// TestVerify_PassesOnUntamperedChain proves a well-formed chain verifies OK.
+func TestVerify_PassesOnUntamperedChain(t *testing.T) {
+	rec, _ := openTemp(t)
+	ctx := context.Background()
+	for i := 0; i < 25; i++ {
+		if _, err := rec.Append(ctx, sampleRecord("POST /v1/admin/sync")); err != nil {
+			t.Fatalf("append %d: %v", i, err)
+		}
+	}
+	integrity, err := rec.Verify(ctx)
+	if err != nil {
+		t.Fatalf("Verify: %v", err)
+	}
+	if !integrity.OK {
+		t.Fatalf("chain not OK: broken at %d (%s)", integrity.BrokenAt, integrity.Reason)
+	}
+	if integrity.Count != 25 {
+		t.Fatalf("count = %d, want 25", integrity.Count)
+	}
+	if integrity.BrokenAt != -1 {
+		t.Fatalf("brokenAt = %d, want -1 on a good chain", integrity.BrokenAt)
+	}
+	// Head must equal the last record's hash.
+	count, head := rec.Head()
+	if count != 25 || head != integrity.HeadHash {
+		t.Fatalf("head mismatch: (%d,%q) vs verify (%d,%q)", count, head, integrity.Count, integrity.HeadHash)
+	}
+}
+
+// TestVerify_DetectsFieldTamper is the headline: an attacker with direct DB
+// access edits a record's content (flips a denied outcome to success, or changes
+// the actor). The stored hash no longer matches the recomputed hash, so Verify
+// reports the exact seq where the chain breaks. THIS is the tamper-evidence
+// property — an audit trail that can be silently forged is worse than none.
+func TestVerify_DetectsFieldTamper(t *testing.T) {
+	rec, path := openTemp(t)
+	ctx := context.Background()
+	for i := 0; i < 10; i++ {
+		if _, err := rec.Append(ctx, sampleRecord("DELETE /v1/admin/orgs")); err != nil {
+			t.Fatalf("append %d: %v", i, err)
+		}
+	}
+	// Sanity: clean chain verifies.
+	if iv, _ := rec.Verify(ctx); !iv.OK {
+		t.Fatalf("precondition: clean chain should verify, broke at %d", iv.BrokenAt)
+	}
+
+	// Tamper OUT OF BAND — a second connection issues an UPDATE the application
+	// never would. This models an attacker who owns the file / a rogue DBA.
+	tamperOutOfBand(t, path, `UPDATE audit_log SET actor_sub='attacker', result='success' WHERE seq=4`)
+
+	iv, err := rec.Verify(ctx)
+	if err != nil {
+		t.Fatalf("Verify after tamper: %v", err)
+	}
+	if iv.OK {
+		t.Fatal("TAMPER NOT DETECTED — a modified record verified as OK; the chain is forgeable")
+	}
+	if iv.BrokenAt != 4 {
+		t.Fatalf("brokenAt = %d, want 4 (the edited record)", iv.BrokenAt)
+	}
+	if !strings.Contains(iv.Reason, "hash mismatch") {
+		t.Fatalf("reason = %q, want a hash-mismatch explanation", iv.Reason)
+	}
+}
+
+// TestVerify_DetectsDeletion proves deleting a record (or a contiguous run) breaks
+// the chain: the record after the hole has a PrevHash that no longer matches the
+// now-preceding record, and the seq sequence gaps. Either way Verify flags it.
+func TestVerify_DetectsDeletion(t *testing.T) {
+	rec, path := openTemp(t)
+	ctx := context.Background()
+	for i := 0; i < 10; i++ {
+		if _, err := rec.Append(ctx, sampleRecord("POST /v1/admin/roles")); err != nil {
+			t.Fatalf("append %d: %v", i, err)
+		}
+	}
+	// Delete a MIDDLE record — the classic "cover your tracks" edit.
+	tamperOutOfBand(t, path, `DELETE FROM audit_log WHERE seq=5`)
+
+	iv, err := rec.Verify(ctx)
+	if err != nil {
+		t.Fatalf("Verify after delete: %v", err)
+	}
+	if iv.OK {
+		t.Fatal("DELETION NOT DETECTED — a removed record left the chain verifying OK")
+	}
+	// The break is observed at seq 6 (the record whose predecessor vanished): its
+	// seq no longer follows the running counter (5 is missing), so the gap check
+	// fires first at 6.
+	if iv.BrokenAt != 6 {
+		t.Fatalf("brokenAt = %d, want 6 (record after the hole)", iv.BrokenAt)
+	}
+}
+
+// TestVerify_DetectsReorder proves swapping two records' positions (an attacker
+// trying to reorder events) breaks the prev-hash linkage.
+func TestVerify_DetectsReorder(t *testing.T) {
+	rec, path := openTemp(t)
+	ctx := context.Background()
+	for i := 0; i < 6; i++ {
+		if _, err := rec.Append(ctx, sampleRecord("POST /v1/kms/secrets")); err != nil {
+			t.Fatalf("append %d: %v", i, err)
+		}
+	}
+	// Swap the hashes of seq 2 and seq 3 (content stays, linkage corrupts). Any
+	// out-of-band shuffle that doesn't recompute the WHOLE suffix is detectable.
+	tamperOutOfBand(t, path, `
+UPDATE audit_log SET hash = (SELECT hash FROM audit_log WHERE seq=3) WHERE seq=2;`)
+
+	iv, _ := rec.Verify(ctx)
+	if iv.OK {
+		t.Fatal("REORDER/HASH-SWAP NOT DETECTED")
+	}
+	if iv.BrokenAt < 0 {
+		t.Fatalf("expected a break, got brokenAt=%d", iv.BrokenAt)
+	}
+}
+
+// TestChain_RestartContinues proves a re-opened store continues the SAME chain
+// (recovers seq + head) rather than forking — so a pod restart cannot silently
+// reset the trail.
+func TestChain_RestartContinues(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	ctx := context.Background()
+
+	rec1, err := Open(path, nil)
+	if err != nil {
+		t.Fatalf("open 1: %v", err)
+	}
+	var lastHash string
+	for i := 0; i < 5; i++ {
+		r, err := rec1.Append(ctx, sampleRecord("POST /v1/admin/sync"))
+		if err != nil {
+			t.Fatalf("append %d: %v", i, err)
+		}
+		lastHash = r.Hash
+	}
+	_ = rec1.Close()
+
+	rec2, err := Open(path, nil)
+	if err != nil {
+		t.Fatalf("open 2: %v", err)
+	}
+	defer func() { _ = rec2.Close() }()
+
+	count, head := rec2.Head()
+	if count != 5 {
+		t.Fatalf("recovered count = %d, want 5", count)
+	}
+	if head != lastHash {
+		t.Fatalf("recovered head = %q, want %q", head, lastHash)
+	}
+	// The next append must chain onto the recovered head at seq 5.
+	r5, err := rec2.Append(ctx, sampleRecord("DELETE /v1/admin/orgs"))
+	if err != nil {
+		t.Fatalf("append after restart: %v", err)
+	}
+	if r5.Seq != 5 || r5.PrevHash != lastHash {
+		t.Fatalf("chain did not continue: seq=%d prev=%q (want seq 5 prev %q)", r5.Seq, r5.PrevHash, lastHash)
+	}
+	// And the whole continued chain still verifies.
+	if iv, _ := rec2.Verify(ctx); !iv.OK {
+		t.Fatalf("continued chain broke at %d (%s)", iv.BrokenAt, iv.Reason)
+	}
+}
+
+// TestRedact_StripsSecrets proves the redactor removes credential-bearing fields
+// (by key name, recursively) while keeping non-secret structure — so an explicit
+// emit point's before/after can never carry a password/token/key.
+func TestRedact_StripsSecrets(t *testing.T) {
+	in := json.RawMessage(`{
+      "name": "acme",
+      "password": "hunter2",
+      "apiKey": "sk-live-abc123",
+      "passphrase": "correct horse",
+      "wgPrivKey": "PRIVKEYBYTES",
+      "recoveryPhrase": "twelve words here",
+      "socialSecurityNumber": "078-05-1120",
+      "config": {
+        "clientSecret": "shh",
+        "endpoint": "https://api.example.com",
+        "nested": {"private_key": "-----BEGIN-----", "region": "sfo3"}
+      },
+      "tokens": ["t1", "t2"],
+      "roles": ["admin", "viewer"]
+    }`)
+	out := Redact(in)
+
+	s := string(out)
+	// Secrets gone (incl. the edge-case key names: passphrase, privkey, phrase, ssn).
+	for _, leak := range []string{"hunter2", "sk-live-abc123", "shh", "BEGIN",
+		"correct horse", "PRIVKEYBYTES", "twelve words here", "078-05-1120"} {
+		if strings.Contains(s, leak) {
+			t.Fatalf("secret leaked through redaction: %q still present in %s", leak, s)
+		}
+	}
+	// Non-secret structure preserved.
+	for _, keep := range []string{"acme", "https://api.example.com", "sfo3", "viewer"} {
+		if !strings.Contains(s, keep) {
+			t.Fatalf("redaction dropped a non-secret value %q: %s", keep, s)
+		}
+	}
+	// The redaction marker appears where secrets were.
+	if !strings.Contains(s, redactedMarker) {
+		t.Fatalf("no redaction marker in output: %s", s)
+	}
+	// "tokens" is a secret key → the whole array is redacted (not its elements).
+	var decoded map[string]any
+	if err := json.Unmarshal(out, &decoded); err != nil {
+		t.Fatalf("redacted output is not valid JSON: %v", err)
+	}
+	if decoded["tokens"] != redactedMarker {
+		t.Fatalf("secret-keyed array not redacted whole: %v", decoded["tokens"])
+	}
+}
+
+// TestRedact_FailsClosedOnBadJSON proves unparseable input is never echoed back.
+func TestRedact_FailsClosedOnBadJSON(t *testing.T) {
+	out := Redact(json.RawMessage(`{not valid json, password=hunter2`))
+	if strings.Contains(string(out), "hunter2") {
+		t.Fatalf("bad JSON echoed a secret: %s", out)
+	}
+	if !strings.Contains(string(out), redactedMarker) {
+		t.Fatalf("bad JSON should redact to a marker, got %s", out)
+	}
+}
+
+// TestQuery_Filters proves the filtered read returns the right subset by actor,
+// action, resource, and result, newest-first, with an accurate total.
+func TestQuery_Filters(t *testing.T) {
+	rec, _ := openTemp(t)
+	ctx := context.Background()
+
+	mk := func(org, action, res, result string) Record {
+		r := sampleRecord(action)
+		r.Actor.Org = org
+		r.Resource.Type = res
+		r.Outcome.Result = result
+		return r
+	}
+	// A mixed set.
+	seed := []Record{
+		mk("admin", "DELETE /v1/admin/orgs", "org", "success"),
+		mk("acme", "POST /v1/base/records", "records", "success"),
+		mk("admin", "POST /v1/admin/roles", "roles", "deny"),
+		mk("admin", "DELETE /v1/admin/orgs", "org", "success"),
+		mk("acme", "POST /v1/kms/secrets", "secrets", "error"),
+	}
+	for i, r := range seed {
+		if _, err := rec.Append(ctx, r); err != nil {
+			t.Fatalf("seed %d: %v", i, err)
+		}
+	}
+
+	// Filter by org=admin → 3 rows.
+	rows, total, err := rec.Query(ctx, Filter{Org: "admin"})
+	if err != nil {
+		t.Fatalf("query org: %v", err)
+	}
+	if total != 3 || len(rows) != 3 {
+		t.Fatalf("org=admin: got %d rows, total %d, want 3/3", len(rows), total)
+	}
+	// Newest first: the last-appended admin row (seq 3) comes before seq 2, 0.
+	if rows[0].Seq < rows[len(rows)-1].Seq {
+		t.Fatalf("not newest-first: %d..%d", rows[0].Seq, rows[len(rows)-1].Seq)
+	}
+
+	// Filter by result=deny → 1 row (the 403-style role change).
+	denies, dtotal, err := rec.Query(ctx, Filter{Result: "deny"})
+	if err != nil {
+		t.Fatalf("query deny: %v", err)
+	}
+	if dtotal != 1 || len(denies) != 1 || denies[0].Action != "POST /v1/admin/roles" {
+		t.Fatalf("result=deny: got %d (%+v), want 1 role-change", dtotal, denies)
+	}
+
+	// Filter by resource=secrets → 1 row.
+	secs, stotal, err := rec.Query(ctx, Filter{Resource: "secrets"})
+	if err != nil {
+		t.Fatalf("query resource: %v", err)
+	}
+	if stotal != 1 || len(secs) != 1 {
+		t.Fatalf("resource=secrets: got %d, want 1", stotal)
+	}
+}
+
+// TestQuery_SQLInjectionInFilterIsInert proves a malicious filter value is a
+// parameter, never SQL: it simply matches nothing and cannot drop the table.
+func TestQuery_SQLInjectionInFilterIsInert(t *testing.T) {
+	rec, _ := openTemp(t)
+	ctx := context.Background()
+	for i := 0; i < 3; i++ {
+		if _, err := rec.Append(ctx, sampleRecord("POST /v1/admin/sync")); err != nil {
+			t.Fatalf("seed %d: %v", i, err)
+		}
+	}
+	inject := Filter{Org: "admin'; DROP TABLE audit_log;--"}
+	rows, total, err := rec.Query(ctx, inject)
+	if err != nil {
+		t.Fatalf("query should not error on injection attempt: %v", err)
+	}
+	if total != 0 || len(rows) != 0 {
+		t.Fatalf("injection value matched %d rows, want 0", total)
+	}
+	// The table survived — a normal query still returns the seeded rows.
+	if _, all, err := rec.Query(ctx, Filter{}); err != nil || all != 3 {
+		t.Fatalf("table damaged by injection attempt: all=%d err=%v", all, err)
+	}
+}
+
+// TestChain_ConcurrentAppendsStayGapless proves the serialized writer keeps the
+// chain a true, gapless total order under CONCURRENT appends: many goroutines
+// append at once, and the resulting chain must have every seq 0..N-1 exactly once
+// AND verify. A race in the head/seq handoff would surface as a duplicate seq (a
+// PRIMARY KEY error), a gap, or a broken link — all of which this catches.
+func TestChain_ConcurrentAppendsStayGapless(t *testing.T) {
+	rec, _ := openTemp(t)
+	ctx := context.Background()
+
+	const goroutines, per = 16, 20
+	total := goroutines * per
+	errCh := make(chan error, total)
+	var wg sync.WaitGroup
+	for g := 0; g < goroutines; g++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for i := 0; i < per; i++ {
+				if _, err := rec.Append(ctx, sampleRecord("POST /v1/admin/sync")); err != nil {
+					errCh <- err
+				}
+			}
+		}()
+	}
+	wg.Wait()
+	close(errCh)
+	for err := range errCh {
+		t.Fatalf("concurrent append failed (race in seq/head handoff?): %v", err)
+	}
+
+	// The chain must verify and contain exactly `total` gapless records.
+	iv, err := rec.Verify(ctx)
+	if err != nil {
+		t.Fatalf("verify: %v", err)
+	}
+	if !iv.OK {
+		t.Fatalf("concurrent chain broke at %d (%s)", iv.BrokenAt, iv.Reason)
+	}
+	if iv.Count != uint64(total) {
+		t.Fatalf("recorded %d records, want %d (a lost/duplicated append)", iv.Count, total)
+	}
+}
+
+// checkpointMirror is a Mirror that also captures checkpoints (implements
+// CheckpointSink) so the test can assert the head digest reaches an independent
+// sink.
+type checkpointMirror struct {
+	mu  sync.Mutex
+	cps []Checkpoint
+}
+
+func (m *checkpointMirror) Append(context.Context, Record) error { return nil }
+func (m *checkpointMirror) Checkpoint(_ context.Context, cp Checkpoint) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.cps = append(m.cps, cp)
+	return nil
+}
+func (m *checkpointMirror) last() (Checkpoint, bool) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if len(m.cps) == 0 {
+		return Checkpoint{}, false
+	}
+	return m.cps[len(m.cps)-1], true
+}
+
+// TestCheckpoint_EmitsHeadDigest proves the AU-9 anchor: the periodic checkpoint
+// emits the current (count, head) to the log function AND, when the mirror is a
+// CheckpointSink, to the independent digest store — and a final checkpoint fires
+// on Close. This is what an external monitor compares to detect tail-truncation.
+func TestCheckpoint_EmitsHeadDigest(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	mirror := &checkpointMirror{}
+	rec, err := Open(path, mirror)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	ctx := context.Background()
+
+	var logged []Checkpoint
+	var lmu sync.Mutex
+	// every=0 → no ticker; we drive checkpoints via Close (final) + a manual tick.
+	rec.StartCheckpoints(0, func(cp Checkpoint) {
+		lmu.Lock()
+		logged = append(logged, cp)
+		lmu.Unlock()
+	})
+
+	for i := 0; i < 7; i++ {
+		if _, err := rec.Append(ctx, sampleRecord("POST /v1/admin/sync")); err != nil {
+			t.Fatalf("append %d: %v", i, err)
+		}
+	}
+	// Close emits the FINAL checkpoint (count=7, head=chain head).
+	if err := rec.Close(); err != nil {
+		t.Fatalf("close: %v", err)
+	}
+
+	lmu.Lock()
+	n := len(logged)
+	var lastLogged Checkpoint
+	if n > 0 {
+		lastLogged = logged[n-1]
+	}
+	lmu.Unlock()
+	if n == 0 {
+		t.Fatal("no checkpoint logged (Close should emit a final head digest)")
+	}
+	if lastLogged.Count != 7 {
+		t.Errorf("final checkpoint count = %d, want 7", lastLogged.Count)
+	}
+	if lastLogged.Head == "" || lastLogged.Head == genesisPrevHash {
+		t.Errorf("final checkpoint head not set: %q", lastLogged.Head)
+	}
+	// The independent sink also received the final digest.
+	if cp, ok := mirror.last(); !ok || cp.Count != 7 {
+		t.Errorf("checkpoint sink final = %+v (ok=%v), want count 7", cp, ok)
+	}
+}
+
+// TestCheckpoint_DoubleStartIsSafe proves a second StartCheckpoints call is
+// ignored (no re-arm, no field/WaitGroup race) — the Red-review robustness fix.
+// Run under -race to catch a regression.
+func TestCheckpoint_DoubleStartIsSafe(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	rec, err := Open(path, nil)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	rec.StartCheckpoints(time.Hour, func(Checkpoint) {})
+	rec.StartCheckpoints(time.Hour, func(Checkpoint) {}) // second call must be a no-op.
+	// Append + close must not race or hang.
+	if _, err := rec.Append(context.Background(), sampleRecord("POST /v1/admin/sync")); err != nil {
+		t.Fatalf("append: %v", err)
+	}
+	if err := rec.Close(); err != nil {
+		t.Fatalf("close: %v", err)
+	}
+}
+
+// TestCheckpoint_CloseSyncsToSink proves the FINAL checkpoint on Close reaches the
+// independent sink SYNCHRONOUSLY (the Red-review durability fix) — the sink has
+// the final count before Close returns, not on a detached goroutine that might
+// not run before process exit.
+func TestCheckpoint_CloseSyncsToSink(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	mirror := &checkpointMirror{}
+	rec, err := Open(path, mirror)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	rec.StartCheckpoints(0, func(Checkpoint) {}) // no ticker; only the on-close checkpoint.
+	for i := 0; i < 4; i++ {
+		if _, err := rec.Append(context.Background(), sampleRecord("POST /v1/admin/sync")); err != nil {
+			t.Fatalf("append %d: %v", i, err)
+		}
+	}
+	if err := rec.Close(); err != nil {
+		t.Fatalf("close: %v", err)
+	}
+	// Immediately after Close returns (no sleep), the sink MUST already have the
+	// final digest — proving the Close-path write was synchronous.
+	cp, ok := mirror.last()
+	if !ok || cp.Count != 4 {
+		t.Fatalf("sink final checkpoint = %+v (ok=%v), want count 4 synchronously on Close", cp, ok)
+	}
+}
+
+// TestCheckpoint_CountMonotonicDetectsTruncation demonstrates the DETECTION an
+// external monitor performs: consecutive checkpoints have non-decreasing Count;
+// after a tail truncation the head reported by Head() drops below a prior
+// checkpoint — the signal the o11y alert fires on.
+func TestCheckpoint_CountMonotonicDetectsTruncation(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	rec, err := Open(path, nil)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	ctx := context.Background()
+	for i := 0; i < 10; i++ {
+		if _, err := rec.Append(ctx, sampleRecord("POST /v1/admin/sync")); err != nil {
+			t.Fatalf("append %d: %v", i, err)
+		}
+	}
+	before, _ := rec.Head() // the monitor's last pinned checkpoint count.
+	if before != 10 {
+		t.Fatalf("pre-truncation count = %d, want 10", before)
+	}
+	_ = rec.Close()
+
+	// Attacker truncates the tail (deletes the last 4 records) out of band.
+	tamperOutOfBand(t, path, `DELETE FROM audit_log WHERE seq >= 6`)
+
+	rec2, err := Open(path, nil)
+	if err != nil {
+		t.Fatalf("reopen: %v", err)
+	}
+	defer func() { _ = rec2.Close() }()
+	after, _ := rec2.Head()
+	// The internal chain still verifies (a truncated prefix is self-consistent)…
+	if iv, _ := rec2.Verify(ctx); !iv.OK {
+		t.Fatalf("truncated prefix should self-verify, broke at %d", iv.BrokenAt)
+	}
+	// …but the count REGRESSED vs the pinned checkpoint — the truncation signal.
+	if after >= before {
+		t.Fatalf("count did not regress after truncation: before=%d after=%d", before, after)
+	}
+	t.Logf("truncation detected by count regression: %d → %d (chain-internal verify is OK; external anchor catches it)", before, after)
+}
+
+// tamperOutOfBand opens the SAME sqlite file on a SEPARATE connection and runs a
+// mutating statement the audit application itself never issues — modeling an
+// attacker with direct database/file access. The Recorder's own connection is
+// unaffected; Verify then re-reads and must catch the damage.
+func tamperOutOfBand(t *testing.T, path, stmt string) {
+	t.Helper()
+	db, err := sql.Open("sqlite", path)
+	if err != nil {
+		t.Fatalf("tamper open: %v", err)
+	}
+	defer func() { _ = db.Close() }()
+	if _, err := db.Exec(stmt); err != nil {
+		t.Fatalf("tamper exec %q: %v", stmt, err)
+	}
+}

audit/query.go

@@ -0,0 +1,235 @@
+package audit
+
+// The read paths: filtered Query (for /v1/admin/audit) and Verify (the
+// tamper-evidence walk for /v1/admin/audit/verify). Both are read-only — they
+// issue SELECT only, never mutate — so exposing them can never weaken the
+// append-only property.
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+)
+
+// Filter narrows a Query. Zero-value fields are ignored (no constraint), so an
+// empty Filter returns the most-recent Limit records. Time bounds are inclusive
+// 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
+	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
+// the same predicate (ignoring Limit/Offset) for pagination. All predicates are
+// parameterized — never string-interpolated — so a filter value can never inject
+// SQL. Column names in the WHERE come from a fixed allowlist below, not caller
+// input.
+func (r *Recorder) Query(ctx context.Context, f Filter) (rows []Record, total int, err error) {
+	where, args := f.build()
+	limit := f.Limit
+	if limit <= 0 {
+		limit = 100
+	}
+	if limit > 1000 {
+		limit = 1000
+	}
+	offset := f.Offset
+	if offset < 0 {
+		offset = 0
+	}
+
+	countQ := `SELECT COUNT(*) FROM audit_log` + where
+	if err = r.db.QueryRowContext(ctx, countQ, args...).Scan(&total); err != nil {
+		return nil, 0, fmt.Errorf("audit: count: %w", err)
+	}
+
+	listQ := `SELECT ` + selectCols + ` FROM audit_log` + where +
+		` ORDER BY seq DESC LIMIT ? OFFSET ?`
+	listArgs := append(append([]any{}, args...), limit, offset)
+	rs, err := r.db.QueryContext(ctx, listQ, listArgs...)
+	if err != nil {
+		return nil, 0, fmt.Errorf("audit: query: %w", err)
+	}
+	defer func() { _ = rs.Close() }()
+	for rs.Next() {
+		rec, scanErr := scanRecord(rs)
+		if scanErr != nil {
+			return nil, 0, fmt.Errorf("audit: scan: %w", scanErr)
+		}
+		rows = append(rows, rec)
+	}
+	return rows, total, rs.Err()
+}
+
+// build assembles the parameterized WHERE clause from the non-zero filter
+// fields. Each fragment uses a fixed column name and a ? placeholder, so no
+// caller value ever reaches the SQL text.
+func (f Filter) build() (string, []any) {
+	var conds []string
+	var args []any
+	add := func(frag string, val any) {
+		conds = append(conds, frag)
+		args = append(args, val)
+	}
+	if f.Org != "" {
+		add("actor_org = ?", f.Org)
+	}
+	if f.Sub != "" {
+		add("actor_sub = ?", f.Sub)
+	}
+	if f.Action != "" {
+		add("action = ?", f.Action)
+	}
+	if f.Resource != "" {
+		add("res_type = ?", f.Resource)
+	}
+	if f.ResourceID != "" {
+		add("res_id = ?", f.ResourceID)
+	}
+	if f.Result != "" {
+		add("result = ?", f.Result)
+	}
+	if !f.Since.IsZero() {
+		add("ts >= ?", f.Since.UTC().Format(time.RFC3339Nano))
+	}
+	if !f.Until.IsZero() {
+		add("ts <= ?", f.Until.UTC().Format(time.RFC3339Nano))
+	}
+	if len(conds) == 0 {
+		return "", nil
+	}
+	return " WHERE " + strings.Join(conds, " AND "), args
+}
+
+const selectCols = `seq, ts, actor_org, actor_sub, actor_email, action, res_type, res_id,
+  auth_method, is_admin, result, status, reason, source_ip, user_agent,
+  request_id, method, path, before, after, prev_hash, hash`
+
+// scanRecord reconstructs a Record from a row of selectCols.
+func scanRecord(sc interface{ Scan(...any) error }) (Record, error) {
+	var (
+		rec           Record
+		ts            string
+		isAdmin       int
+		before, after string
+	)
+	if err := sc.Scan(
+		&rec.Seq, &ts, &rec.Actor.Org, &rec.Actor.Sub, &rec.Actor.Email,
+		&rec.Action, &rec.Resource.Type, &rec.Resource.ID,
+		&rec.Auth.Method, &isAdmin, &rec.Outcome.Result, &rec.Outcome.Status, &rec.Outcome.Reason,
+		&rec.SourceIP, &rec.UserAgent, &rec.RequestID, &rec.Method, &rec.Path,
+		&before, &after, &rec.PrevHash, &rec.Hash,
+	); err != nil {
+		return Record{}, err
+	}
+	if t, err := time.Parse(time.RFC3339Nano, ts); err == nil {
+		rec.Time = t
+	}
+	rec.Auth.IsAdmin = isAdmin != 0
+	if before != "" {
+		rec.Before = json.RawMessage(before)
+	}
+	if after != "" {
+		rec.After = json.RawMessage(after)
+	}
+	return rec, nil
+}
+
+// Integrity is the result of a Verify walk — the AU-9 evidence that the trail has
+// not been tampered with.
+type Integrity struct {
+	// OK is true iff every record's stored hash equals the recomputed hash AND the
+	// chain links are continuous (each PrevHash == the prior record's Hash, seqs
+	// gapless from 0).
+	OK bool `json:"ok"`
+	// Count is the number of records walked.
+	Count uint64 `json:"count"`
+	// HeadHash is the hash of the last record (or the genesis anchor for an empty
+	// chain). Pin this externally over time to detect tail-truncation.
+	HeadHash string `json:"headHash"`
+	// BrokenAt is the seq of the FIRST record that failed verification, or -1 when
+	// OK. Reason describes the break (recomputed-hash mismatch, prev-hash
+	// discontinuity, or a seq gap).
+	BrokenAt int64  `json:"brokenAt"`
+	Reason   string `json:"reason,omitempty"`
+}
+
+// Verify walks the entire chain in seq order, recomputing each record's hash from
+// its content + the running prev-hash and checking continuity. It is the
+// tamper-detector: any modification (a changed field re-hashes differently), any
+// deletion or reordering (a seq gap or a broken prev-hash link), or a forged row
+// (its recomputed hash won't match unless the attacker also recomputed the entire
+// suffix — which they cannot do without re-inserting every subsequent record) is
+// reported with the exact seq where the chain first breaks.
+//
+// Complexity is O(n) over the records; for very large trails this streams row by
+// row (no full materialization). At cloud's audit volume this is fine; if a trail
+// grows past what an on-demand full walk should touch, verify a seq WINDOW
+// (Verify is easily extended with a bound) or rely on the externally-pinned head.
+func (r *Recorder) Verify(ctx context.Context) (Integrity, error) {
+	rs, err := r.db.QueryContext(ctx,
+		`SELECT `+selectCols+` FROM audit_log ORDER BY seq ASC`)
+	if err != nil {
+		return Integrity{}, fmt.Errorf("audit: verify query: %w", err)
+	}
+	defer func() { _ = rs.Close() }()
+
+	prevHash := genesisPrevHash
+	var expectSeq uint64
+	var count uint64
+	headHash := genesisPrevHash
+
+	for rs.Next() {
+		rec, scanErr := scanRecord(rs)
+		if scanErr != nil {
+			return Integrity{}, fmt.Errorf("audit: verify scan: %w", scanErr)
+		}
+		// Gapless, 0-based ordering.
+		if rec.Seq != expectSeq {
+			return Integrity{
+				OK: false, Count: count, HeadHash: headHash,
+				BrokenAt: int64(rec.Seq),
+				Reason:   fmt.Sprintf("seq gap: expected %d, got %d", expectSeq, rec.Seq),
+			}, nil
+		}
+		// Link continuity: this record must chain to the previous record's hash.
+		if rec.PrevHash != prevHash {
+			return Integrity{
+				OK: false, Count: count, HeadHash: headHash,
+				BrokenAt: int64(rec.Seq),
+				Reason:   "prev_hash discontinuity (a record was deleted, reordered, or altered)",
+			}, nil
+		}
+		// Content integrity: recompute the hash from the record's own fields.
+		want, hErr := computeHash(rec, rec.PrevHash)
+		if hErr != nil {
+			return Integrity{}, fmt.Errorf("audit: verify hash: %w", hErr)
+		}
+		if want != rec.Hash {
+			return Integrity{
+				OK: false, Count: count, HeadHash: headHash,
+				BrokenAt: int64(rec.Seq),
+				Reason:   "hash mismatch (record content was modified after it was written)",
+			}, nil
+		}
+		prevHash = rec.Hash
+		headHash = rec.Hash
+		expectSeq = rec.Seq + 1
+		count++
+	}
+	if err := rs.Err(); err != nil {
+		return Integrity{}, fmt.Errorf("audit: verify rows: %w", err)
+	}
+	return Integrity{OK: true, Count: count, HeadHash: headHash, BrokenAt: -1}, nil
+}

audit/record.go

@@ -0,0 +1,176 @@
+// Package audit is the unified cloud binary's compliance-grade audit trail —
+// tamper-evident, append-only, and complete over the security-relevant request
+// surface (FedRAMP AU-* / SOC 2 CC-* controls).
+//
+// THE CONTROL, IN ONE SENTENCE. Every security-relevant action against this
+// binary is captured as a structured Record, hash-chained to its predecessor so
+// any later deletion or modification is detectable, and written INLINE (never
+// dropped) to an append-only store the application can only INSERT into.
+//
+// THREE PIECES, EACH IN ITS LANE (orthogonal, per the Zen of Hanzo):
+//   - record.go  — the event model + the hash-chain math (what a record IS and
+//     how it links to the one before it). Pure, no I/O.
+//   - store.go   — the append-only sink (SQLite primary, INSERT-only; a
+//     best-effort OLAP mirror) and the serialized Recorder that
+//     owns the chain head. All persistence.
+//   - redact.go  — the secret-stripping allowlist/denylist for any structured
+//     before/after an explicit emit point supplies. No secret ever
+//     reaches a record.
+//
+// The HTTP middleware (Middleware, in the cloud package) and the query/verify
+// endpoints (in clients/admin) are thin callers of this package. This package
+// holds the security logic; it has zero knowledge of routes.
+package audit
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"time"
+)
+
+// Actor identifies WHO performed the action. It is populated ONLY from a
+// validated principal (the sanitized X-User-* headers SanitizeIdentity mints
+// from a verified IAM JWT), never from a raw client header — so an actor can
+// never be forged by the request that is being audited. A service principal
+// (M2M / no user sub) records Org with an empty Sub.
+type Actor struct {
+	// Org is the tenant (IAM `owner`). Empty for an unauthenticated request.
+	Org string `json:"org"`
+	// Sub is the user id (IAM `sub`/`preferred_username`). Empty for a service
+	// principal or an anonymous request.
+	Sub string `json:"sub"`
+	// Email is the validated user email, when present.
+	Email string `json:"email,omitempty"`
+}
+
+// Resource identifies WHAT was acted upon: a type (e.g. "org", "role",
+// "secret", "provider-config", "credit") and its id. For a plain HTTP mutation
+// with no finer resource semantics, Type is the route family and ID is empty —
+// the Action verb + path already pin the object.
+type Resource struct {
+	Type string `json:"type"`
+	ID   string `json:"id,omitempty"`
+}
+
+// AuthContext records HOW the actor authenticated and what authority they held
+// at decision time — the AC-* evidence (was this a SuperAdmin? by what
+// credential?). Method is "jwt" | "api-key" | "none". IsAdmin is the VALIDATED
+// SuperAdmin bit (owner == AdminOrg), never a raw X-User-IsAdmin.
+type AuthContext struct {
+	Method  string `json:"method"`
+	IsAdmin bool   `json:"isAdmin"`
+}
+
+// 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.
+// "SuperAdmin required", "insufficient_balance") — never a secret, never a
+// raw upstream error body.
+type Outcome struct {
+	Result string `json:"result"`
+	Status int    `json:"status"`
+	Reason string `json:"reason,omitempty"`
+}
+
+// Record is one audit event. The JSON tags ARE the on-disk and on-wire contract.
+//
+// Field order in the struct is deliberate but IRRELEVANT to the hash: the chain
+// hashes the CANONICAL (sorted-key) JSON of the record with Hash/PrevHash zeroed
+// (see canonicalBytes), so re-ordering fields or adding an omitempty field can
+// never change an existing record's hash.
+type Record struct {
+	// Seq is the strictly-increasing chain position (0-based). It is assigned by
+	// the Recorder under its lock, so it is a true total order with no gaps.
+	Seq uint64 `json:"seq"`
+
+	// Time is the UTC event timestamp (RFC3339Nano).
+	Time time.Time `json:"time"`
+
+	// Actor / Action / Resource / Auth / Outcome — the AU-3 "content of audit
+	// records" core: who, what, on what, how-authenticated, with what result.
+	Actor    Actor       `json:"actor"`
+	Action   string      `json:"action"`
+	Resource Resource    `json:"resource"`
+	Auth     AuthContext `json:"auth"`
+	Outcome  Outcome     `json:"outcome"`
+
+	// SourceIP + UserAgent — the AU-3 "source of the event" fields.
+	SourceIP  string `json:"sourceIp,omitempty"`
+	UserAgent string `json:"userAgent,omitempty"`
+
+	// RequestID correlates the record to the request-line log and any downstream
+	// trace (the X-Request-Id the pipeline mints).
+	RequestID string `json:"requestId,omitempty"`
+
+	// Method + Path are the HTTP verb and route for a request-sourced event.
+	Method string `json:"method,omitempty"`
+	Path   string `json:"path,omitempty"`
+
+	// Before / After capture a mutation's prior and resulting state for the
+	// AU-required "before/after" on config-affecting changes. They are populated
+	// ONLY by explicit emit points and ONLY after Redact has stripped secrets —
+	// the HTTP middleware never sets them (it never reads bodies), so a secret in
+	// a request body can never leak here. Raw JSON so any shape round-trips.
+	Before json.RawMessage `json:"before,omitempty"`
+	After  json.RawMessage `json:"after,omitempty"`
+
+	// PrevHash is the hash of record Seq-1 (hex). For the genesis record (Seq 0)
+	// it is genesisPrevHash. Hash is this record's hash. Neither participates in
+	// its own hash computation (both are zeroed in canonicalBytes).
+	PrevHash string `json:"prevHash"`
+	Hash     string `json:"hash"`
+}
+
+// genesisPrevHash is the PrevHash of the first record in a fresh chain: 32 zero
+// bytes, hex-encoded. A non-empty, fixed anchor so the genesis record's hash is
+// still a function of a known constant (not the empty string, which would be
+// indistinguishable from "field omitted").
+const genesisPrevHash = "0000000000000000000000000000000000000000000000000000000000000000"
+
+// canonicalBytes returns the deterministic byte string a record hashes over: the
+// record with Hash AND PrevHash zeroed, marshaled by encoding/json (which sorts
+// struct fields in declaration order and, critically, is stable for a given
+// struct — the SAME bytes on every machine and every run). Zeroing PrevHash here
+// means the hash covers only the record's OWN content; the link to the previous
+// record is added explicitly in computeHash by appending prevHash. This keeps
+// the two concerns separable and the math obvious.
+//
+// We marshal a copy with the two hash fields cleared rather than a parallel
+// struct so there is exactly ONE definition of a record's fields (DRY): add a
+// field to Record and it is covered by the hash automatically.
+func canonicalBytes(r Record) ([]byte, error) {
+	r.Hash = ""
+	r.PrevHash = ""
+	return json.Marshal(r)
+}
+
+// computeHash returns the hex SHA-256 of (canonical(record) || prevHash-bytes).
+// The prevHash is folded in as its RAW hex string bytes — the exact value stored
+// in the record's PrevHash field — so the verifier reproduces it byte-for-byte
+// from stored data alone. Any change to the record's content OR to which record
+// precedes it changes this output, which is the whole tamper-evidence property.
+func computeHash(r Record, prevHash string) (string, error) {
+	body, err := canonicalBytes(r)
+	if err != nil {
+		return "", err
+	}
+	h := sha256.New()
+	h.Write(body)
+	h.Write([]byte(prevHash))
+	return hex.EncodeToString(h.Sum(nil)), nil
+}
+
+// seal finalizes a record into position seq linked to prevHash: it stamps Seq
+// and PrevHash, computes Hash, and returns the sealed record ready to append.
+// The Recorder calls this under its lock so seq/prevHash reflect the true head.
+func seal(r Record, seq uint64, prevHash string) (Record, error) {
+	r.Seq = seq
+	r.PrevHash = prevHash
+	hash, err := computeHash(r, prevHash)
+	if err != nil {
+		return Record{}, err
+	}
+	r.Hash = hash
+	return r, nil
+}

audit/redact.go

@@ -0,0 +1,140 @@
+package audit
+
+// Secret redaction for the before/after captured on a mutation.
+//
+// THE RULE. An audit record must NEVER contain a credential — no password,
+// token, API key, private key, card number, or session secret. Two layers
+// enforce this:
+//
+//  1. The HTTP middleware captures METADATA ONLY (actor/action/resource/outcome).
+//     It NEVER reads a request or response body, so a secret in a POST body can
+//     never reach a record through the automatic path. This is the primary
+//     guarantee: the code that can't see a secret can't leak one.
+//
+//  2. An EXPLICIT emit point that supplies structured before/after (e.g. a config
+//     change diff) runs it through Redact first. Redact walks the JSON and
+//     replaces the VALUE of any key whose name matches the secret denylist with a
+//     fixed marker, recursively. It is deny-by-key-name — the same allowlist
+//     PATTERN cloud already uses for user-secret redaction — chosen because a
+//     mutation diff has arbitrary shape and key-name matching is the robust,
+//     well-understood control (vs. trying to detect "secret-looking" values).
+//
+// Redact is conservative: on any structural surprise it returns the redaction
+// marker rather than the input, so a parser edge case fails CLOSED (no raw
+// passthrough).
+
+import (
+	"encoding/json"
+	"strings"
+)
+
+// redactedMarker replaces every redacted value. A constant so tests and the
+// query UI recognize it unambiguously.
+const redactedMarker = "[REDACTED]"
+
+// secretKeyParts are substrings that, when contained (case-insensitively) in a
+// JSON object key, mark that key's value as secret. Kept as a small, auditable
+// denylist of the credential-bearing field names that actually occur across the
+// Hanzo surface (IAM, KMS, commerce, provider config). Matching is substring so
+// "clientSecret", "api_key", "PRIVATE_KEY", "accessToken" all match.
+var secretKeyParts = []string{
+	"password",
+	"passwd",
+	"secret",
+	"token",
+	"apikey",
+	"api_key",
+	"api-key",
+	"authorization",
+	"auth_token",
+	"private_key",
+	"privatekey",
+	"privkey", // privkey, wgPrivKey
+	"passphrase",
+	"client_secret",
+	"credential",
+	"session",
+	"cookie",
+	"card", // card_number, cardNumber
+	"cvv",
+	"cvc",
+	"pin",
+	"ssn",
+	"social_security", // socialSecurityNumber (lower-cased match covers camelCase)
+	"socialsecurity",
+	"otp",
+	"mnemonic",
+	"phrase", // seed_phrase, seedPhrase, recoveryPhrase
+	"access_key",
+	"secret_key",
+	"refresh_token",
+	"id_token",
+	"bearer",
+	"signing_key",
+	"encryption_key",
+}
+
+// isSecretKey reports whether a JSON key names a credential-bearing field.
+func isSecretKey(key string) bool {
+	k := strings.ToLower(key)
+	for _, part := range secretKeyParts {
+		if strings.Contains(k, part) {
+			return true
+		}
+	}
+	return false
+}
+
+// Redact returns a copy of the JSON value with every secret-keyed value replaced
+// by the redaction marker, recursively through objects and arrays. Non-JSON or
+// empty input yields nil (nothing to record). On a JSON parse error the input is
+// dropped (returns the marker as a JSON string) rather than passed through —
+// fail closed.
+//
+// Use it at any explicit emit point that supplies before/after:
+//
+//	audit.Emit(ctx, rec.WithChange(audit.Redact(before), audit.Redact(after)))
+func Redact(raw json.RawMessage) json.RawMessage {
+	if len(raw) == 0 {
+		return nil
+	}
+	var v any
+	if err := json.Unmarshal(raw, &v); err != nil {
+		// Unparseable — never echo it back verbatim; record a marker instead.
+		b, _ := json.Marshal(redactedMarker)
+		return b
+	}
+	cleaned := redactValue("", v)
+	out, err := json.Marshal(cleaned)
+	if err != nil {
+		b, _ := json.Marshal(redactedMarker)
+		return b
+	}
+	return out
+}
+
+// redactValue walks a decoded JSON value. key is the object key under which v
+// sits (empty at the root and for array elements); when key is a secret key, the
+// ENTIRE value v is replaced (whether it is a scalar, object, or array — a secret
+// nested object is redacted whole). Otherwise objects/arrays are recursed.
+func redactValue(key string, v any) any {
+	if key != "" && isSecretKey(key) {
+		return redactedMarker
+	}
+	switch t := v.(type) {
+	case map[string]any:
+		out := make(map[string]any, len(t))
+		for k, val := range t {
+			out[k] = redactValue(k, val)
+		}
+		return out
+	case []any:
+		out := make([]any, len(t))
+		for i, val := range t {
+			out[i] = redactValue("", val) // array elements inherit no key
+		}
+		return out
+	default:
+		return v
+	}
+}

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

@@ -0,0 +1,381 @@
+package audit
+
+// The append-only sink + the serialized Recorder that owns the hash-chain head.
+//
+// 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
+// canonical store is embedded SQLite (one store per the storagelock lockdown;
+// pricing/provisioning already persist to {DataDir}/*.db). A local SQLite table
+// the application can only INSERT into gives us: (a) a real total order under one
+// connection, (b) synchronous durability so NO record is ever lost on the request
+// path (unlike a fire-and-forget mirror), and (c) an append-only surface — the
+// 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 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.
+// Losing a mirror row is a query-completeness issue, not an integrity one.
+//
+// FAIL MODE. Append is INLINE and its error is RETURNED to the middleware, which
+// fails the request CLOSED (a security-relevant action that cannot be recorded is
+// not permitted to silently succeed). This is the AU-5 "response to audit logging
+// process failure": deny rather than act-unlogged.
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"sync"
+	"time"
+
+	// 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/datastore). It is
+// deliberately a tiny interface, not a concrete client, so the Recorder has no
+// 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
+	// logged and dropped by the Recorder — the mirror never gates a request.
+	Append(ctx context.Context, r Record) error
+}
+
+// Checkpoint is a periodic, tamper-EVIDENCE digest of the chain head: the record
+// count and the head hash at a moment in time. It is the AU-9 anchor for
+// TAIL-TRUNCATION detection — an internal chain walk cannot notice that the last
+// K records were deleted (the surviving prefix still verifies), but a durable,
+// INDEPENDENT series of head checkpoints can: Count is monotonic, so any decrease
+// between two consecutive checkpoints is deletion, and an attacker cannot forge a
+// higher count without appending records whose hashes the chain walk would reject.
+type Checkpoint struct {
+	Time  time.Time `json:"time"`
+	Count uint64    `json:"count"`
+	Head  string    `json:"head"`
+}
+
+// CheckpointSink is an optional capability a Mirror may implement to persist the
+// head digest series to an INDEPENDENT store (so truncating the local SQLite
+// cannot also rewrite the anchor history). A Mirror that does not implement it
+// still gets its records; checkpoints then flow only to the structured log.
+type CheckpointSink interface {
+	Checkpoint(ctx context.Context, cp Checkpoint) error
+}
+
+// Recorder is the single serialized writer that owns the audit chain head and
+// the append-only store. Every Record flows through Append, which under one lock
+// assigns the next Seq, links PrevHash to the current head, seals (hashes), and
+// synchronously persists to SQLite before returning. Concurrency is serialized
+// by mu AND by the single-connection SQLite pool, so the on-disk order equals
+// the chain order with no gaps.
+type Recorder struct {
+	db     *sql.DB
+	mirror Mirror // nil when no OLAP mirror is configured.
+
+	mu       sync.Mutex // guards nextSeq/headHash and serializes appends.
+	nextSeq  uint64     // Seq to assign to the next record.
+	headHash string     // Hash of the last-appended record (PrevHash for the next).
+
+	// Checkpoint emission (AU-9 tail-truncation anchor). logCheckpoint, when set,
+	// receives each head digest so it lands in the append-only observability log;
+	// stopCh/wg manage the periodic emitter goroutine's lifecycle; started guards
+	// against a second StartCheckpoints call (the field write + WaitGroup use are
+	// not safe to race). All three are set once, before any concurrent Append.
+	logCheckpoint func(cp Checkpoint)
+	stopCh        chan struct{}
+	wg            sync.WaitGroup
+	started       bool
+}
+
+// CheckpointFunc receives a head digest for the structured (o11y) log. It is a
+// plain func so the pure audit package stays free of any concrete logger type;
+// the cloud wiring adapts luxlog to it.
+type CheckpointFunc func(cp Checkpoint)
+
+// Open opens (creating if needed) the append-only audit DB at path and recovers
+// 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.
+//
+// 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 := cek.Open(path)
+	if err != nil {
+		return nil, fmt.Errorf("audit: open sqlite %q: %w", path, err)
+	}
+	db.SetMaxOpenConns(1)
+	for _, pragma := range []string{
+		"PRAGMA busy_timeout=5000",
+		"PRAGMA journal_mode=WAL",
+		"PRAGMA synchronous=NORMAL",
+	} {
+		if _, err := db.Exec(pragma); err != nil {
+			_ = db.Close()
+			return nil, fmt.Errorf("audit: pragma %q: %w", pragma, err)
+		}
+	}
+	r := &Recorder{db: db, mirror: mirror}
+	if err := r.migrate(); err != nil {
+		_ = db.Close()
+		return nil, err
+	}
+	if err := r.recoverHead(); err != nil {
+		_ = db.Close()
+		return nil, err
+	}
+	return r, nil
+}
+
+// migrate creates the append-only audit table. It is INSERT-only by application
+// discipline: this package issues no UPDATE or DELETE against it, and seq is the
+// PRIMARY KEY so a replayed/duplicated seq is rejected by the engine. The hash
+// columns make any out-of-band row edit detectable by Verify regardless of the
+// storage layer's own guarantees.
+func (r *Recorder) migrate() error {
+	const ddl = `
+CREATE TABLE IF NOT EXISTS audit_log (
+  seq        INTEGER PRIMARY KEY,       -- chain position; gapless, assigned under lock
+  ts         TEXT    NOT NULL,          -- RFC3339Nano UTC event time
+  actor_org  TEXT    NOT NULL DEFAULT '',
+  actor_sub  TEXT    NOT NULL DEFAULT '',
+  actor_email TEXT   NOT NULL DEFAULT '',
+  action     TEXT    NOT NULL,
+  res_type   TEXT    NOT NULL DEFAULT '',
+  res_id     TEXT    NOT NULL DEFAULT '',
+  auth_method TEXT   NOT NULL DEFAULT '',
+  is_admin   INTEGER NOT NULL DEFAULT 0,
+  result     TEXT    NOT NULL,          -- success|deny|error
+  status     INTEGER NOT NULL DEFAULT 0,
+  reason     TEXT    NOT NULL DEFAULT '',
+  source_ip  TEXT    NOT NULL DEFAULT '',
+  user_agent TEXT    NOT NULL DEFAULT '',
+  request_id TEXT    NOT NULL DEFAULT '',
+  method     TEXT    NOT NULL DEFAULT '',
+  path       TEXT    NOT NULL DEFAULT '',
+  before     TEXT    NOT NULL DEFAULT '',  -- redacted JSON (explicit emit only)
+  after      TEXT    NOT NULL DEFAULT '',  -- redacted JSON (explicit emit only)
+  prev_hash  TEXT    NOT NULL,
+  hash       TEXT    NOT NULL
+);
+-- Query indexes for the /v1/admin/audit filters (actor/action/resource/time).
+CREATE INDEX IF NOT EXISTS ix_audit_org_seq    ON audit_log(actor_org, seq);
+CREATE INDEX IF NOT EXISTS ix_audit_action_seq ON audit_log(action, seq);
+CREATE INDEX IF NOT EXISTS ix_audit_result_seq ON audit_log(result, seq);
+CREATE INDEX IF NOT EXISTS ix_audit_ts         ON audit_log(ts);
+`
+	if _, err := r.db.Exec(ddl); err != nil {
+		return fmt.Errorf("audit: migrate: %w", err)
+	}
+	return nil
+}
+
+// recoverHead loads the highest-seq record so a restarted process continues the
+// existing chain (nextSeq = maxSeq+1, headHash = its hash). An empty table starts
+// the genesis chain (nextSeq 0, headHash = genesisPrevHash).
+func (r *Recorder) recoverHead() error {
+	var (
+		maxSeq sql.NullInt64
+		hash   sql.NullString
+	)
+	row := r.db.QueryRow(`SELECT seq, hash FROM audit_log WHERE seq = (SELECT MAX(seq) FROM audit_log)`)
+	if err := row.Scan(&maxSeq, &hash); err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			r.nextSeq = 0
+			r.headHash = genesisPrevHash
+			return nil
+		}
+		return fmt.Errorf("audit: recover head: %w", err)
+	}
+	if !maxSeq.Valid { // empty table (MAX over zero rows is NULL)
+		r.nextSeq = 0
+		r.headHash = genesisPrevHash
+		return nil
+	}
+	r.nextSeq = uint64(maxSeq.Int64) + 1
+	r.headHash = hash.String
+	return nil
+}
+
+// Append seals r into the next chain position and persists it. It fills Seq,
+// PrevHash, and Hash (the caller sets everything else), advances the in-memory
+// head only AFTER the durable INSERT succeeds, and mirrors best-effort. A
+// persistence error is returned so the caller can fail the request CLOSED — the
+// head is NOT advanced on failure, so the chain never gaps.
+//
+// The whole critical section (assign seq → seal → INSERT → advance head) holds
+// mu, so two concurrent requests can never claim the same seq or race the head.
+func (r *Recorder) Append(ctx context.Context, rec Record) (Record, error) {
+	if rec.Time.IsZero() {
+		rec.Time = time.Now().UTC()
+	} else {
+		rec.Time = rec.Time.UTC()
+	}
+
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	sealed, err := seal(rec, r.nextSeq, r.headHash)
+	if err != nil {
+		return Record{}, fmt.Errorf("audit: seal: %w", err)
+	}
+	if err := r.insert(ctx, sealed); err != nil {
+		// Head not advanced; the next append reuses this seq. Fail closed upstream.
+		return Record{}, fmt.Errorf("audit: persist: %w", err)
+	}
+	// Durable — advance the chain head.
+	r.nextSeq = sealed.Seq + 1
+	r.headHash = sealed.Hash
+
+	// Best-effort OLAP mirror, detached so a slow/failed mirror never blocks the
+	// request or corrupts the reply. The local chain is already durable and is the
+	// authority; a lost mirror row is a query-completeness gap, not an integrity
+	// one. Copy by value: the record is immutable and safe to hand to a goroutine.
+	if r.mirror != nil {
+		m, out := r.mirror, sealed
+		go func() { _ = m.Append(context.Background(), out) }()
+	}
+	return sealed, nil
+}
+
+// insert writes one sealed record. INSERT-only — the sole write statement in this
+// package. A duplicate seq (PRIMARY KEY) fails here, which is the desired
+// invariant: the chain never overwrites a position.
+func (r *Recorder) insert(ctx context.Context, rec Record) error {
+	_, err := r.db.ExecContext(ctx, `
+INSERT INTO audit_log (
+  seq, ts, actor_org, actor_sub, actor_email, action, res_type, res_id,
+  auth_method, is_admin, result, status, reason, source_ip, user_agent,
+  request_id, method, path, before, after, prev_hash, hash
+) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+		rec.Seq, rec.Time.Format(time.RFC3339Nano),
+		rec.Actor.Org, rec.Actor.Sub, rec.Actor.Email,
+		rec.Action, rec.Resource.Type, rec.Resource.ID,
+		rec.Auth.Method, boolToInt(rec.Auth.IsAdmin),
+		rec.Outcome.Result, rec.Outcome.Status, rec.Outcome.Reason,
+		rec.SourceIP, rec.UserAgent, rec.RequestID, rec.Method, rec.Path,
+		string(rec.Before), string(rec.After), rec.PrevHash, rec.Hash,
+	)
+	return err
+}
+
+// checkpointCloseTimeout bounds the final (synchronous) checkpoint write to the
+// independent sink at shutdown, so Close cannot hang on an unreachable datastore.
+const checkpointCloseTimeout = 5 * time.Second
+
+// Close stops the periodic checkpoint emitter, emits a FINAL checkpoint
+// SYNCHRONOUSLY (so the head at shutdown reaches both the o11y log and the
+// independent digest store before the process exits — the AU-9 anchor must be
+// current exactly when an attacker might trigger shutdown then truncate), and
+// closes the underlying database.
+func (r *Recorder) Close() error {
+	if r == nil || r.db == nil {
+		return nil
+	}
+	if r.stopCh != nil {
+		close(r.stopCh)
+		r.wg.Wait()
+		r.stopCh = nil
+	}
+	// Anchor the final head before the DB closes — independent of whether the
+	// periodic ticker was running (every<=0 still gets a shutdown checkpoint).
+	// Synchronous to the sink (bounded), so the independent store's last count is
+	// as fresh as the local chain at the moment of shutdown.
+	r.emitCheckpoint(true)
+	return r.db.Close()
+}
+
+// StartCheckpoints begins periodic head-digest emission every `every` (no ticker
+// if every<=0; the on-Close checkpoint still fires). logFn, when non-nil,
+// receives each digest for the append-only observability log (o11y), and a mirror
+// implementing CheckpointSink also gets it persisted to an INDEPENDENT store —
+// together the AU-9 anchor an external monitor compares to detect tail-truncation
+// (count regression). MUST be called at most once, before any concurrent Append
+// (a second call is ignored); the emitter stops on Close.
+func (r *Recorder) StartCheckpoints(every time.Duration, logFn CheckpointFunc) {
+	// Guard the check-and-set under mu so a (mis)use that calls this concurrently
+	// is race-free, not just the single-call production path.
+	r.mu.Lock()
+	if r.started {
+		r.mu.Unlock()
+		return // already started — do not re-arm (avoids a field/WaitGroup race).
+	}
+	r.started = true
+	r.logCheckpoint = logFn
+	r.mu.Unlock()
+	if every <= 0 {
+		return
+	}
+	r.stopCh = make(chan struct{})
+	stop := r.stopCh
+	r.wg.Add(1)
+	go func() {
+		defer r.wg.Done()
+		t := time.NewTicker(every)
+		defer t.Stop()
+		for {
+			select {
+			case <-stop:
+				return
+			case <-t.C:
+				r.emitCheckpoint(false)
+			}
+		}
+	}()
+}
+
+// emitCheckpoint snapshots the head and emits it to the log and (if the mirror is
+// a CheckpointSink) the independent digest store. sync controls the sink write:
+// on the periodic path (sync=false) it is detached so a slow sink never delays
+// the ticker; on the Close path (sync=true) it BLOCKS on a bounded context so the
+// final anchor is durable before shutdown. The log emission is always synchronous
+// (it is the primary anchor and o11y ingests it append-only).
+func (r *Recorder) emitCheckpoint(sync bool) {
+	count, head := r.Head()
+	cp := Checkpoint{Time: time.Now().UTC(), Count: count, Head: head}
+	if r.logCheckpoint != nil {
+		r.logCheckpoint(cp)
+	}
+	cs, ok := r.mirror.(CheckpointSink)
+	if !ok || cs == nil {
+		return
+	}
+	if sync {
+		ctx, cancel := context.WithTimeout(context.Background(), checkpointCloseTimeout)
+		defer cancel()
+		_ = cs.Checkpoint(ctx, cp)
+		return
+	}
+	go func() { _ = cs.Checkpoint(context.Background(), cp) }()
+}
+
+// Head returns the current chain head (count of records, and the head hash). A
+// count of 0 means the genesis (empty) chain, headHash == genesisPrevHash. An
+// external monitor can pin (count, headHash) over time to detect tail-truncation
+// — which an internal chain walk alone cannot catch (a truncated prefix still
+// verifies). This is the anchor point for AU-9 protection against deletion of the
+// most-recent records.
+func (r *Recorder) Head() (count uint64, headHash string) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.nextSeq, r.headHash
+}
+
+func boolToInt(b bool) int {
+	if b {
+		return 1
+	}
+	return 0
+}

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

@@ -0,0 +1,677 @@
+package cloud
+
+// The audit middleware — the ONE place every security-relevant request is
+// recorded to the tamper-evident trail (decomplected: one function, every route).
+//
+// PLACEMENT (why it sits exactly where serve.go puts it). The pipeline is
+// Recover → RequestID → Logger → SanitizeIdentity → AuditTrail → BillingGate →
+// subsystems. AuditTrail runs:
+//   - AFTER SanitizeIdentity, so the actor/isAdmin it records come from a
+//     VALIDATED IAM principal (the sanitized X-User-* headers), never a raw
+//     client header. The request being audited cannot forge its own actor.
+//   - BEFORE BillingGate and every subsystem, so it WRAPS the whole handler
+//     chain and observes the FINAL outcome — including a 402/503 billing denial
+//     and a 403 admin-guard denial (both security-relevant) — via the response
+//     status after Continue(), exactly like the Logger middleware reads it.
+//
+// WHAT IT CAPTURES: metadata only — actor, action (method+route family),
+// resource, source ip, user agent, request id, auth context, and the outcome
+// (result/status/reason). It NEVER reads the request or response BODY, so a
+// secret in a POST body can never reach a record through this path. before/after
+// diffs are the job of explicit emit points (audit.Recorder.Append with a
+// redacted diff), not this middleware.
+//
+// WHAT IT RECORDS (the coverage predicate, auditable in one place — see
+// isSecurityRelevant): every mutating request (POST/PUT/PATCH/DELETE), every
+// /v1/admin/* request (read or write — admin reads are AC-relevant), and every
+// auth-failure outcome (401/403) on ANY method (a denied GET is an access-control
+// event). Safe, unauthenticated reads (a 200 GET on a public route) are NOT
+// audited — that is request-log noise, not a security event, and auditing it
+// would bury the signal and balloon the trail.
+//
+// FAIL MODE (AU-5): if the trail write fails on a request we decided to audit,
+// the CLIENT gets a fail-closed 503 rather than a success it can rely on — the
+// AU-5 "response to an audit logging process failure" is to interrupt, not to
+// operate silently unlogged. A write to local SQLite is sub-millisecond, so this
+// is a real integrity stance, not a latency tax. When no Recorder is configured
+// the middleware is a no-op passthrough (an unconfigured deployment is never
+// blocked), exactly like BillingGate.
+//
+// PRECISE SEMANTIC (do not over-read the 503). This is POST-RESPONSE audit: the
+// handler has already run when the record is written, so a 503 here means "this
+// event could not be RECORDED", NOT "the action did not execute". PREVENTION is
+// the access-control layer's job and runs BEFORE the action — SanitizeIdentity
+// (identity can't be forged) + the per-route admin guard both execute inside
+// c.Next() ahead of any side effect. The audit trail's job is DETECTION and
+// ACCOUNTABILITY (tamper-evident record of what happened), which it does. On a
+// persistent audit-store outage every mutation returns 503 (loud, logged), so
+// the system degrades to read-only rather than mutating unaudited — the intended
+// compliance posture.
+//
+// PANIC BOUND. If a handler PANICS, the outermost middleware.Recover catches it
+// and renders 500 with a full stack trace (loud, never silent); the panic unwinds
+// PAST this middleware's post-c.Next() code, so a panicking request is not written
+// to the trail. This is an accepted bound, not an evasion: an attacker cannot turn
+// a panic into a SUCCESSFUL-but-unaudited mutation (a panic yields 500, not a
+// completed action), and every panic is already captured by Recover's logging.
+// Normal outcomes — including billing 402/503 and admin 403 denials, which return
+// through c.Next() rather than panicking — are always audited.
+
+import (
+	"errors"
+	"net/url"
+	"strings"
+
+	"github.com/hanzoai/cloud/audit"
+	"github.com/hanzoai/cloud/clients/principal"
+	"github.com/zap-proto/zip"
+)
+
+// AuditTrail returns the audit middleware bound to rec. A nil rec makes it a
+// no-op passthrough so callers always Use() it unconditionally.
+func AuditTrail(rec *audit.Recorder) zip.Handler {
+	if rec == nil {
+		return func(c *zip.Ctx) error { return c.Next() }
+	}
+	return func(c *zip.Ctx) error {
+		// Capture the pre-decision inputs BEFORE running the chain: the request
+		// context is recycled by Fiber after the handler returns, so identity and
+		// request fields must be read now (mirrors BillingGate capturing usage by
+		// value pre-Record).
+		method := c.Method()
+		path := c.Path()
+
+		err := c.Next()
+
+		// Resolve the EFFECTIVE status. A handler may set it on the response
+		// directly (c.Status(...).JSON(...)) OR return a *zip.HTTPError that the
+		// framework's error handler renders AFTER this middleware unwinds — in the
+		// latter case the response still reads 200 here, so the returned error is
+		// the authoritative source of a 401/403. Prefer the error's status when it
+		// carries one; this is what makes admin-guard denials (which return
+		// ErrForbidden) get audited as 403.
+		status := effectiveStatus(c.Fiber().Response().StatusCode(), err)
+		if !isSecurityRelevant(method, path, status) {
+			return err // not an audited event; pass the handler result through.
+		}
+
+		record := audit.Record{
+			Actor:    actorFromCtx(c),
+			Action:   method + " " + routeFamily(path),
+			Resource: resourceFromPath(path),
+			Auth:     authFromCtx(c),
+			Outcome:  outcomeOf(status, err),
+			SourceIP: ClientIP(c),
+			// User-Agent is client-controlled free text; a misconfigured/malicious
+			// client could embed a bearer token in it. Scrub credential-shaped runs
+			// (and cap length) so the UA can never carry a secret into the record.
+			UserAgent: scrubFreeText(c.Header("User-Agent")),
+			RequestID: c.RequestID(),
+			Method:    method,
+			// Path is scrubbed of any credential-shaped segment: Hanzo routes use
+			// identifiers (:name/:slug/:id), not secrets, but a token that ever
+			// rides in the path (an hk-/sk-/pk-/fw_/hz_ key) must never be recorded
+			// verbatim. resourceFromPath applies the same scrub to the resource id.
+			Path: scrubCredentialSegments(path),
+		}
+
+		if _, aerr := rec.Append(c.Context(), record); aerr != nil {
+			// AU-5: could not record a security-relevant event — fail the request
+			// closed. Do NOT leak the audit error to the client; log it loud.
+			c.Log().Error("audit append failed — failing request closed",
+				"path", path, "method", method, "err", aerr)
+			return c.JSON(503, map[string]any{
+				"error": map[string]string{
+					"code":    "audit_unavailable",
+					"message": "Request could not be securely recorded",
+				},
+			})
+		}
+		return err
+	}
+}
+
+// isSecurityRelevant is the coverage predicate — the ONE place that decides which
+// requests enter the audit trail (AC/AU scope). Kept tiny and total so the
+// coverage matrix is reviewable at a glance. Order matters and is deliberate:
+// the security-relevant conditions are checked FIRST and are unconditional, so
+// the health-probe exemption can NEVER be used to evade audit of a mutation or a
+// denial (a POST/DELETE, or any 401/403, is always audited whatever the path).
+//   - any auth-failure outcome (401/403) on any method (a denied access attempt),
+//   - any /v1/admin/* request (admin reads are access-control-relevant),
+//   - any mutating request (POST/PUT/PATCH/DELETE).
+//
+// Only then, a genuine liveness probe (a GET to an exact health route) is
+// exempted — it is neither a mutation, a denial, nor an admin call, so it is pure
+// request-log noise. The exemption matches EXACT probe paths, never an arbitrary
+// path that merely ends in "/health" (which a wildcard/attacker-named segment
+// like POST /v1/admin/orgs/x/health could otherwise abuse to slip past audit).
+func isSecurityRelevant(method, path string, status int) bool {
+	// Unconditional security signals — never suppressed by any path shape. A
+	// denial, an admin call, or a mutation is ALWAYS audited, whatever the path
+	// (so a wildcard/attacker-named "/health" tail cannot evade it).
+	if status == 401 || status == 403 {
+		return true
+	}
+	if strings.HasPrefix(path, "/v1/admin/") {
+		return true
+	}
+	if isMutation(method) {
+		return true
+	}
+	// Everything left is a safe read (non-mutating, non-admin, non-denied). None
+	// are audited — they are request-log noise, not security events. (Liveness
+	// probes fall here too; there is no separate case because the answer is the
+	// same: not recorded.)
+	return false
+}
+
+// isMutation reports whether a method changes state.
+func isMutation(method string) bool {
+	switch method {
+	case "POST", "PUT", "PATCH", "DELETE":
+		return true
+	default:
+		return false
+	}
+}
+
+// actorFromCtx builds the Actor from the sanitized identity headers, gating
+// ANTI-FORGERY of the recorded actor on a VALIDATED principal.
+//
+// The authoritative "this request carried a validated principal" signal is a
+// non-empty X-User-Id (c.User()): SanitizeIdentity sets X-User-Id ONLY from a
+// JWT it verified, and strips any client-supplied copy on ingress. A request
+// with no principal — anonymous, OR one bearing an INVALID/garbage bearer that
+// failed validation — has an empty c.User().
+//
+// In that unvalidated case the org header is NOT trustworthy: SanitizeIdentity's
+// Phase-1 residual restores a client-supplied X-Org-Id for the data path, so an
+// anonymous attacker could send X-Org-Id: victim-org and, if we recorded it,
+// forge a FALSE ATTRIBUTION (an event stamped with a victim's org). So when there
+// is no validated sub, the actor is left EMPTY — the record stands as an honest
+// anonymous event identified by SourceIP, never mis-attributed to a claimed org.
+//
+// With a validated sub, org/sub/email all reflect the verified principal and are
+// recorded authoritatively.
+func actorFromCtx(c *zip.Ctx) audit.Actor {
+	if !principal.Validated(c) {
+		// No validated principal — do not trust the client-asserted org.
+		return audit.Actor{}
+	}
+	return audit.Actor{
+		Org:   strings.TrimSpace(c.Org()),
+		Sub:   strings.TrimSpace(c.User()),
+		Email: strings.TrimSpace(c.UserEmail()),
+	}
+}
+
+// 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 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".
+func authFromCtx(c *zip.Ctx) audit.AuthContext {
+	return audit.AuthContext{
+		Method:  authMethodOf(c),
+		IsAdmin: c.IsAdmin(),
+	}
+}
+
+// authMethodOf classifies the credential kind WITHOUT capturing it — it inspects
+// only the token PREFIX (never stores the value). Order mirrors the sanitizer's
+// extraction (bearer, then cookie).
+func authMethodOf(c *zip.Ctx) string {
+	auth := c.Header("Authorization")
+	if auth == "" {
+		auth = c.Header("X-Authorization")
+	}
+	if tok := bearerFromAuth(auth); tok != "" {
+		if isAPIKey(tok) {
+			return "api-key"
+		}
+		return "jwt"
+	}
+	if basicFromAuth(auth) != "" {
+		return "basic"
+	}
+	for _, name := range cookieTokenNames {
+		if c.Fiber().Cookies(name) != "" {
+			return "jwt"
+		}
+	}
+	return "none"
+}
+
+// effectiveStatus reconciles the response status with a returned error. If the
+// handler returned a *zip.HTTPError (e.g. ErrForbidden), its Status is
+// authoritative — the framework renders it after this middleware unwinds, so the
+// live response status does not yet reflect it. A non-HTTPError returned error
+// with a still-2xx response means the framework will render a 500. Otherwise the
+// response status stands.
+func effectiveStatus(respStatus int, err error) int {
+	if err != nil {
+		var he *zip.HTTPError
+		if errors.As(err, &he) && he.Status != 0 {
+			return he.Status
+		}
+		// A non-HTTPError propagating up renders as 500, unless the handler already
+		// set an explicit error status on the response.
+		if respStatus < 400 {
+			return 500
+		}
+	}
+	return respStatus
+}
+
+// outcomeOf maps the final HTTP status + handler error to an audit Outcome.
+// 2xx/3xx ⇒ success; 401/403 ⇒ deny; everything else (4xx/5xx) ⇒ error. The
+// reason is a short, non-sensitive label derived from the status class — never a
+// raw upstream error body (which could echo sensitive detail).
+func outcomeOf(status int, err error) audit.Outcome {
+	switch {
+	case status == 401:
+		return audit.Outcome{Result: "deny", Status: status, Reason: "unauthenticated"}
+	case status == 403:
+		return audit.Outcome{Result: "deny", Status: status, Reason: "forbidden"}
+	case status >= 500:
+		return audit.Outcome{Result: "error", Status: status, Reason: "server_error"}
+	case status >= 400:
+		return audit.Outcome{Result: "error", Status: status, Reason: "client_error"}
+	default:
+		return audit.Outcome{Result: "success", Status: status}
+	}
+}
+
+// routeFamily reduces a concrete path to its stable route family for the action
+// verb, dropping trailing high-cardinality id segments so "DELETE /v1/admin/
+// orgs/acme" and "DELETE /v1/admin/orgs/globex" share the action "DELETE
+// /v1/admin/orgs". The full concrete path is preserved separately in Record.Path.
+func routeFamily(path string) string {
+	segs := strings.Split(strings.Trim(path, "/"), "/")
+	// Keep the leading "v1/<subsystem>/<noun>" and stop before an id-looking tail.
+	out := make([]string, 0, len(segs))
+	for _, s := range segs {
+		if looksLikeID(s) {
+			break
+		}
+		out = append(out, s)
+	}
+	if len(out) == 0 {
+		return "/" + strings.Join(segs, "/")
+	}
+	return "/" + strings.Join(out, "/")
+}
+
+// resourceFromPath derives the {type,id} resource from a /v1/<subsystem>/<type>/
+// [<id>] path. Type is the noun after the subsystem; ID is the following segment
+// when it looks like an identifier. Best-effort — the Action verb + Path are the
+// authoritative locator; this is a convenience for filtering by resource type.
+func resourceFromPath(path string) audit.Resource {
+	segs := strings.Split(strings.Trim(path, "/"), "/")
+	// segs: [v1, <subsystem>, <type>, <id?>, ...]
+	if len(segs) < 3 {
+		return audit.Resource{}
+	}
+	res := audit.Resource{Type: segs[2]}
+	if len(segs) >= 4 && looksLikeID(segs[3]) {
+		res.ID = scrubToken(segs[3])
+	}
+	return res
+}
+
+// scrubToken replaces a path segment that is a credential-shaped token with a
+// fixed marker, so a secret that ever appears in a URL is never recorded
+// verbatim. It catches, in increasing generality:
+//   - a known API-key prefix (hk-/sk-/pk-/fw_/hz_ — what isAPIKey recognizes),
+//     ALSO after percent-decoding, so hk%2DKEY can't slip the prefix check,
+//   - a JWT (three base64url parts split by '.', starting eyJ),
+//   - a long, high-entropy base64url/hex run (>=24) — a raw API key / access
+//     token / hex secret that carries no telltale prefix.
+//
+// A normal identifier passes through unchanged: a UUID (5 hyphen-split groups,
+// each short), a slug, a numeric id, a dotted model name — none is a long
+// unbroken high-entropy blob. See TestScrubToken_NoFalsePositives.
+//
+// RED-review hardening (finding: scrub bypass): the entropy test now (a) accepts
+// the FULL base64url alphabet incl. '-' and '_' (RFC 4648 §5), (b) does NOT
+// require a digit (an all-alpha opaque key is still a secret), (c) percent-
+// decodes first so %2D/%5F can't hide structure, and (d) drops the threshold to
+// 24 (short enough for a 128-bit base64 or a 24-hex key, long enough that no
+// human-readable slug reaches it).
+func scrubToken(seg string) string {
+	dec := percentDecode(seg)
+	if isAPIKey(seg) || isAPIKey(dec) ||
+		looksLikeJWT(seg) || looksLikeJWT(dec) ||
+		looksLikeHighEntropyToken(seg) || looksLikeHighEntropyToken(dec) {
+		return "[REDACTED-TOKEN]"
+	}
+	return seg
+}
+
+// percentDecode best-effort URL-decodes s so a percent-encoded credential
+// (hk%2DKEY, sk%5Flive%5F…) is normalized before the credential tests run. On a
+// malformed escape it returns s unchanged (the raw form is then tested as-is).
+func percentDecode(s string) string {
+	// Decode repeatedly (bounded) so a NESTED encoding (%252D -> %2D -> -) is
+	// fully normalized before the credential tests run. Stop when a pass makes no
+	// change, on a malformed escape, or after a small cap (defeats a decode bomb).
+	for i := 0; i < 3 && strings.Contains(s, "%"); i++ {
+		dec, err := url.PathUnescape(s)
+		if err != nil || dec == s {
+			break
+		}
+		s = dec
+	}
+	return s
+}
+
+// looksLikeJWT reports whether s is a JSON Web Token OR a JWT header segment. A
+// full JWT is three base64url parts split by '.', header starting "eyJ". But when
+// free text (a UA) is tokenized on '.', a dotted JWT splits into parts; a real
+// header part is >=24 chars (caught by the high-entropy run), yet to be safe we
+// ALSO flag any lone segment starting with the canonical base64url header prefix
+// "eyJ" (which decodes to '{"') regardless of length — a JWT header can never be
+// a legitimate resource id, so redacting it has no false-positive cost.
+func looksLikeJWT(s string) bool {
+	if !strings.HasPrefix(s, "eyJ") {
+		return false
+	}
+	// A full token (two dots) or a bare header segment — either way, redact.
+	return true
+}
+
+// highEntropyMinLen is the length at/above which an UNBROKEN run of base64/hex
+// chars is treated as an opaque secret. 24 covers a 128-bit base64 token, a
+// 24-nibble hex key, and short API keys, while every human-readable path
+// segment/slug/model-name stays under it once split on its separators — no
+// single run of a name like "text-embedding-3-large" reaches 24.
+const highEntropyMinLen = 24
+
+// looksLikeHighEntropyToken reports whether s CONTAINS an unbroken run of
+// >= highEntropyMinLen base64/hex chars — the shape of a raw API key / access
+// token / hex secret — UNLESS s is a structured human identifier.
+//
+// The run alphabet is [A-Za-z0-9_+/-] — the base64 alphabets (url-safe §5 '-”_'
+// and standard §4 '+”/') and hex. '-' is INCLUDED so a url-safe-base64 token
+// that embeds '-' is still caught by its run (excluding '-' left an ~11% bypass
+// for 32-byte url-safe tokens whose '-' happened to break every 24-run — measured).
+//
+// TWO-STAGE DETECTION:
+//
+//  1. UNCONDITIONAL run scan — a >= highEntropyMinLen UNBROKEN run over
+//     [A-Za-z0-9_+/-] flags the value REGARDLESS of the structured-id exemption.
+//     This catches every raw secret WITHOUT internal separators (hex, base64) —
+//     the realistic "a client bug put a raw key in the URL" case — at 100%. A
+//     structured identifier never has a 24-char unbroken run, so this stage never
+//     over-scrubs one.
+//
+//  2. STRUCTURED-ID EXEMPTION for the rest (values with separators that DON'T have
+//     a 24-run): exempt a clearly hyphen-joined human id, judged by LEXICAL
+//     content — every group WORD-LIKE (single-case word or decimal number), which
+//     a mixed-case base64 chunk or a long hex-with-letters chunk is NOT (those are
+//     redacted). Shape alone is attacker-satisfiable (RED found a 3x12-chunked
+//     secret slipped a shape-only check); the lexical test rejects the common
+//     secret encodings.
+//
+// ACCEPTED RESIDUAL BOUND (documented, per RED review): the ONLY residual is a
+// secret deliberately chunked into >=3 SINGLE-CASE-ALPHABETIC groups of <=12 chars
+// with no hex-letter runs >= hexChunkMinLen (a lowercase- or uppercase-only base32
+// alphabet, e.g. abcdefghijkl-mnopqrstuvwx-…). Such a value is lexically
+// indistinguishable from a hyphenated model id (deepseek-r1-distill-qwen-32b
+// carries the SAME 24-char entropy budget), so it passes stage 2. This is NOT
+// closable by any length/case/count rule without a word dictionary
+// (over-engineering for a defense-in-depth URL/UA backstop). Mixed-case base64
+// chunks AND small-hex chunks (md5/sha display grouping) ARE now caught
+// (isWordLikeGroup). The residual does not widen exposure for any REAL credential:
+// Hanzo keys are hk-/sk-/pk-/fw_/hz_-prefixed (isAPIKey, caught at any
+// length/shape), JWTs are eyJ-prefixed (looksLikeJWT), and request/response BODIES
+// are never read. It is an adversary DELIBERATELY base32-chunking their OWN secret
+// into a URL path to seed an admin-only audit row — contrived, low-value. The
+// realistic accidental leak (an unbroken raw key) is caught by stage 1.
+//
+// A canonical UUID is exempt (its longest run is 12; the check documents intent).
+func looksLikeHighEntropyToken(s string) bool {
+	if len(s) < highEntropyMinLen {
+		return false
+	}
+	// Stage 1 — unconditional: a long unbroken run is always a secret.
+	if hasHighEntropyRun(s) {
+		return true
+	}
+	// Stage 2 — separated values: redact unless it's a lexical structured id.
+	if isUUID(s) || isStructuredID(s) {
+		return false
+	}
+	// A >=24-length value with separators, not a UUID, not a structured id — e.g.
+	// "sk.live.LONGSECRET…" dotted, or a chunk pattern that is not word-like.
+	return true
+}
+
+// hasHighEntropyRun reports whether s contains an unbroken run of
+// >= highEntropyMinLen high-entropy chars where the run alphabet EXCLUDES '-'
+// (and '.'): a real separator breaks the run. This is stage 1 — it fires only on
+// a genuinely UNBROKEN opaque blob (a raw hex/base64 key with no separators), so
+// it never catches a hyphenated identifier (which stage 2 then classifies). A
+// url-safe-base64 secret that embeds '-' still trips because the run on ONE side
+// of the hyphen is >= 24 (verified: "AbCdEf-GhIjKl_MnOpQrStUvWxYz012345" -> 27).
+func hasHighEntropyRun(s string) bool {
+	run := 0
+	for _, r := range s {
+		if isUnbrokenTokenChar(r) {
+			run++
+			if run >= highEntropyMinLen {
+				return true
+			}
+		} else {
+			run = 0
+		}
+	}
+	return false
+}
+
+// isUnbrokenTokenChar is the stage-1 run alphabet: base64/hex MINUS '-' (and the
+// implicit exclusion of '.', space, etc.). '_' '+' '/' are kept — they appear
+// inside opaque tokens and are not identifier separators.
+func isUnbrokenTokenChar(r rune) bool {
+	return (r >= 'A' && r <= 'Z') || (r >= 'a' && r <= 'z') ||
+		(r >= '0' && r <= '9') || r == '_' || r == '+' || r == '/'
+}
+
+// idPartMaxLen bounds a hyphen-group length in the structured-id exemption. 12
+// covers the longest word in real model ids ("embedding", "20241022", "preview")
+// while a raw secret's random hyphen groups routinely exceed it.
+const idPartMaxLen = 12
+
+// isStructuredID reports whether s is a hyphen-joined human identifier (a model
+// name, slug): >= 3 hyphen groups where EVERY group is non-empty, <= idPartMaxLen
+// chars, and WORD-LIKE. The word-like test is the anti-bypass core — a raw secret
+// chunk cannot satisfy it — so the exemption is not attacker-satisfiable by shape.
+func isStructuredID(s string) bool {
+	groups := strings.Split(s, "-")
+	if len(groups) < 3 {
+		return false
+	}
+	for _, g := range groups {
+		if g == "" || len(g) > idPartMaxLen || !isWordLikeGroup(g) {
+			return false
+		}
+	}
+	return true
+}
+
+// isWordLikeGroup reports whether a hyphen group looks like a model-id token (a
+// dictionary word or a decimal number) rather than a random secret chunk. Two
+// lexical signals reject a secret chunk:
+//   - MIXED CASE (both upper and lower letters) — base64 tokens are dense
+//     mixed-case; real model tokens are single-case ("sonnet", "Instruct", "3").
+//   - an all-hex-with-letters run (>= hexChunkMinLen chars, all [0-9a-fA-F], and
+//     not all-digits) — a hex secret chunk ("dead", "beef", "cafebabe"); a version
+//     date ("20241022", all digits) is NOT hex-with-letters, so it stays
+//     word-like. The threshold is 4: RED re-review verified that NO real model-id
+//     group is all-hex-with-letters of length >= 4, so 4 (vs the prior 8) closes
+//     the small-hex-chunk leak (md5/sha shown in "xxxx-xxxx" display grouping)
+//     with zero model-id over-scrub.
+func isWordLikeGroup(g string) bool {
+	var hasUpper, hasLower, allHex, allDigit bool = false, false, true, true
+	for _, r := range g {
+		switch {
+		case r >= 'A' && r <= 'Z':
+			hasUpper = true
+		case r >= 'a' && r <= 'z':
+			hasLower = true
+		}
+		if r < '0' || r > '9' {
+			allDigit = false
+		}
+		isHex := (r >= '0' && r <= '9') || (r >= 'a' && r <= 'f') || (r >= 'A' && r <= 'F')
+		if !isHex {
+			allHex = false
+		}
+	}
+	if hasUpper && hasLower {
+		return false // dense mixed-case → base64 secret chunk, not a word.
+	}
+	if allHex && !allDigit && len(g) >= hexChunkMinLen {
+		return false // hex-with-letters → hex secret chunk (not a version date).
+	}
+	return true
+}
+
+// hexChunkMinLen is the length at/above which an all-hex-with-letters group is
+// treated as a secret chunk rather than a word. 4 is the tightest bound that does
+// not over-scrub any real model-id group (RED-verified across 19 model ids) while
+// catching hex secrets displayed in short groups (md5 "xxxx-xxxx", uuid-ish).
+const hexChunkMinLen = 4
+
+// isUUID reports whether s is a canonical 8-4-4-4-12 hex UUID (case-insensitive).
+// Used to exempt uuids from the high-entropy secret test — a uuid is a legitimate
+// resource id, not a credential.
+func isUUID(s string) bool {
+	if len(s) != 36 {
+		return false
+	}
+	for i, r := range s {
+		switch i {
+		case 8, 13, 18, 23:
+			if r != '-' {
+				return false
+			}
+		default:
+			if !((r >= '0' && r <= '9') || (r >= 'a' && r <= 'f') || (r >= 'A' && r <= 'F')) {
+				return false
+			}
+		}
+	}
+	return true
+}
+
+// maxUserAgentLen caps the recorded User-Agent so an oversized UA can neither
+// bloat the trail nor smuggle a long payload. 512 chars covers every real UA.
+const maxUserAgentLen = 512
+
+// scrubFreeText scrubs credential-shaped words out of client-controlled free
+// text (the User-Agent) and caps its length. It tokenizes on a broad delimiter
+// superset — whitespace and the punctuation that commonly glues a token into a
+// UA/header value (= ; , : / ( ) [ ] { } " ' < > | and backslash) — scrubs each
+// token, and rebuilds the string preserving the exact delimiters between tokens.
+//
+// RED-review hardening (finding: UA tokenizer split on too few delimiters, and
+// strings.ReplaceAll was substring-fragile): this walks the string in one pass
+// (token-run, delimiter-run, …) and replaces each credential token IN PLACE, so a
+// secret delimited by ':' '/' '(' etc. is caught and a token that is a substring
+// of another is never mis-replaced. A normal UA ("Mozilla/5.0 (Macintosh …)") is
+// unchanged because none of its words is credential-shaped.
+func scrubFreeText(s string) string {
+	if s == "" {
+		return ""
+	}
+	if len(s) > maxUserAgentLen {
+		s = s[:maxUserAgentLen]
+	}
+	var b strings.Builder
+	b.Grow(len(s))
+	start := -1 // start index of the current token run, or -1 in a delimiter run.
+	flush := func(end int) {
+		if start >= 0 {
+			b.WriteString(scrubToken(s[start:end]))
+			start = -1
+		}
+	}
+	for i, r := range s {
+		if isFreeTextDelimiter(r) {
+			flush(i)
+			b.WriteRune(r)
+		} else if start < 0 {
+			start = i
+		}
+	}
+	flush(len(s))
+	return b.String()
+}
+
+// isFreeTextDelimiter reports whether r separates tokens in free text (a UA /
+// header value). Deliberately broad so a credential can't hide behind an unusual
+// separator.
+//
+// RED re-review (UA bypass persists): '.' '@' '#' '~' are INCLUDED — a prefixed
+// key glued by one of them (client@sk-live-KEY, app.sk-live-KEY, build#hk-KEY)
+// otherwise stayed one token whose PREFIX was no longer sk-/hk-, so isAPIKey
+// missed it. Splitting on them exposes the bare key to scrubToken. Real UA dots
+// are numeric version separators (<24, safe) and are split harmlessly. A JWT
+// (eyJ.h.p.s) is handled up-front by scrubToken via looksLikeJWT before any
+// tokenizer runs on a URL path segment; in free text a dotted JWT will split,
+// but each ~40-char base64 part is itself a >=24 high-entropy run, so every part
+// is still redacted.
+func isFreeTextDelimiter(r rune) bool {
+	switch r {
+	case ' ', '\t', '\n', '\r', '=', ';', ',', ':', '/', '\\',
+		'(', ')', '[', ']', '{', '}', '"', '\'', '<', '>', '|', '&', '?',
+		'.', '@', '#', '~':
+		return true
+	}
+	return false
+}
+
+// scrubCredentialSegments applies scrubToken to every segment of a path, so the
+// recorded Path can never carry a credential even if a future route embeds one.
+// Route nouns/ids pass through unchanged (they are not isAPIKey-shaped).
+func scrubCredentialSegments(path string) string {
+	if !strings.ContainsAny(path, "/") {
+		return scrubToken(path)
+	}
+	segs := strings.Split(path, "/")
+	changed := false
+	for i, s := range segs {
+		if scrubbed := scrubToken(s); scrubbed != s {
+			segs[i] = scrubbed
+			changed = true
+		}
+	}
+	if !changed {
+		return path
+	}
+	return strings.Join(segs, "/")
+}
+
+// looksLikeID heuristically flags a path segment as a high-cardinality id (a
+// uuid, a long hex/opaque token, or a numeric id) vs a fixed route noun. Used to
+// collapse route families; false positives only make the action slightly more
+// specific, never leak anything.
+func looksLikeID(s string) bool {
+	if s == "" {
+		return false
+	}
+	if len(s) >= 16 { // long opaque/uuid-ish segment
+		return true
+	}
+	allDigits := true
+	for _, r := range s {
+		if r < '0' || r > '9' {
+			allDigits = false
+			break
+		}
+	}
+	return allDigits && len(s) > 0
+}

audit_middleware_test.go

@@ -0,0 +1,579 @@
+package cloud
+
+// Integration tests for the audit middleware. They drive REAL requests through
+// the zip/fiber stack (app.Fiber().Test) with the audit middleware in front of a
+// handler, backed by a REAL on-disk audit store, then read the store back to
+// assert what was (and was not) recorded. No mocks — the whole capture path runs.
+//
+// The middleware trusts SanitizeIdentity to have already validated identity, so
+// these tests set the sanitized X-User-* headers directly (as SanitizeIdentity
+// would after verifying a JWT) — that is the contract boundary under test here.
+// The forgery/bypass properties of SanitizeIdentity itself are proven in
+// middleware_identity_test.go; here we prove the middleware records the VALIDATED
+// identity and the correct outcome for every security-relevant request.
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/hanzoai/cloud/audit"
+	"github.com/zap-proto/zip"
+)
+
+// newAuditApp wires a zip app with the audit middleware in front of a small set
+// of routes covering the coverage matrix: a mutating POST, a safe GET, an
+// admin-gated route that 403s, and a route that echoes a (secret-bearing) body
+// so we can prove the body never reaches a record.
+func newAuditApp(t *testing.T) (*zip.App, *audit.Recorder) {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "audit.db")
+	rec, err := audit.Open(path, nil)
+	if err != nil {
+		t.Fatalf("audit.Open: %v", err)
+	}
+	t.Cleanup(func() { _ = rec.Close() })
+
+	app := zip.New(zip.Config{})
+	app.Use(AuditTrail(rec))
+
+	// Mutating route — must be audited.
+	app.Post("/v1/kms/secrets", func(c *zip.Ctx) error {
+		return c.JSON(http.StatusCreated, map[string]string{"id": "sec_1"})
+	})
+	// Safe read — must NOT be audited (not a mutation, not admin, not a denial).
+	app.Get("/v1/pricing/models", func(c *zip.Ctx) error {
+		return c.JSON(http.StatusOK, map[string]string{"ok": "true"})
+	})
+	// Admin route that denies (as the real admin guard would) — the 403 is a
+	// 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("SuperAdmin required")
+		}
+		return c.JSON(http.StatusOK, map[string]string{"ok": "true"})
+	})
+	// A mutation whose request body carries secrets — used to prove the body is
+	// never captured. The handler ignores the body; the point is what the
+	// middleware records (metadata only).
+	app.Post("/v1/iam/users", func(c *zip.Ctx) error {
+		return c.JSON(http.StatusOK, map[string]string{"ok": "true"})
+	})
+	return app, rec
+}
+
+// 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")
+	req.Header.Set("X-User-Email", "z@hanzo.ai")
+	req.Header.Set("X-Org-Id", "admin")
+	req.Header.Set("X-User-IsAdmin", "true")
+	req.Header.Set("Authorization", "Bearer eyJ.validated.jwt") // shape only; classifies as jwt
+}
+
+// asUser sets sanitized headers for a normal (non-admin) validated principal.
+func asUser(req *http.Request) {
+	req.Header.Set("X-User-Id", "alice")
+	req.Header.Set("X-Org-Id", "acme")
+	req.Header.Set("Authorization", "Bearer eyJ.validated.jwt")
+}
+
+func mustTest(t *testing.T, app *zip.App, req *http.Request) *http.Response {
+	t.Helper()
+	resp, err := app.Fiber().Test(req)
+	if err != nil {
+		t.Fatalf("Test %s %s: %v", req.Method, req.URL.Path, err)
+	}
+	return resp
+}
+
+// TestAudit_RecordsMutation proves a mutating request is captured with the
+// correct validated actor, action, resource, outcome, and auth context — and the
+// record is hash-chained (has a hash) and verifies.
+func TestAudit_RecordsMutation(t *testing.T) {
+	app, rec := newAuditApp(t)
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/kms/secrets", nil)
+	asUser(req)
+	req.Header.Set("X-Forwarded-For", "203.0.113.9, 10.0.0.1")
+	req.Header.Set("User-Agent", "test-agent/1.0")
+	resp := mustTest(t, app, req)
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("status = %d, want 201", resp.StatusCode)
+	}
+
+	rows, total, err := rec.Query(t.Context(), audit.Filter{})
+	if err != nil {
+		t.Fatalf("Query: %v", err)
+	}
+	if total != 1 || len(rows) != 1 {
+		t.Fatalf("recorded %d events, want exactly 1", total)
+	}
+	r := rows[0]
+	if r.Actor.Org != "acme" || r.Actor.Sub != "alice" {
+		t.Errorf("actor = %+v, want org=acme sub=alice (the VALIDATED identity)", r.Actor)
+	}
+	if r.Method != "POST" || r.Path != "/v1/kms/secrets" {
+		t.Errorf("method/path = %s %s, want POST /v1/kms/secrets", r.Method, r.Path)
+	}
+	if r.Resource.Type != "secrets" {
+		t.Errorf("resource type = %q, want secrets", r.Resource.Type)
+	}
+	if r.Outcome.Result != "success" || r.Outcome.Status != 201 {
+		t.Errorf("outcome = %+v, want success/201", r.Outcome)
+	}
+	if r.Auth.Method != "jwt" {
+		t.Errorf("auth method = %q, want jwt", r.Auth.Method)
+	}
+	if r.SourceIP != "203.0.113.9" {
+		t.Errorf("source ip = %q, want the left-most XFF entry", r.SourceIP)
+	}
+	if r.UserAgent != "test-agent/1.0" {
+		t.Errorf("user agent = %q, want test-agent/1.0", r.UserAgent)
+	}
+	if r.Hash == "" {
+		t.Error("record has no hash — not chained")
+	}
+	if iv, _ := rec.Verify(t.Context()); !iv.OK {
+		t.Errorf("chain broke after one record at %d (%s)", iv.BrokenAt, iv.Reason)
+	}
+}
+
+// TestAudit_RecordsDenial proves a 403 (access-control denial) is audited even on
+// a GET, with outcome result="deny", and records the actor who was denied.
+func TestAudit_RecordsDenial(t *testing.T) {
+	app, rec := newAuditApp(t)
+
+	// A NON-admin hits the admin route → 403.
+	req := httptest.NewRequest(http.MethodGet, "/v1/admin/orgs", nil)
+	asUser(req) // not admin
+	resp := mustTest(t, app, req)
+	if resp.StatusCode != http.StatusForbidden {
+		t.Fatalf("status = %d, want 403", resp.StatusCode)
+	}
+
+	rows, total, err := rec.Query(t.Context(), audit.Filter{Result: "deny"})
+	if err != nil {
+		t.Fatalf("Query: %v", err)
+	}
+	if total != 1 {
+		t.Fatalf("recorded %d denials, want 1", total)
+	}
+	r := rows[0]
+	if r.Outcome.Result != "deny" || r.Outcome.Status != 403 {
+		t.Errorf("outcome = %+v, want deny/403", r.Outcome)
+	}
+	if r.Actor.Sub != "alice" {
+		t.Errorf("denied actor sub = %q, want alice", r.Actor.Sub)
+	}
+	if r.Auth.IsAdmin {
+		t.Error("denied non-admin recorded as admin")
+	}
+}
+
+// TestAudit_SkipsSafeReads proves an ordinary successful GET on a non-admin route
+// is NOT audited — the trail captures security events, not read-log noise.
+func TestAudit_SkipsSafeReads(t *testing.T) {
+	app, rec := newAuditApp(t)
+
+	req := httptest.NewRequest(http.MethodGet, "/v1/pricing/models", nil)
+	asUser(req)
+	resp := mustTest(t, app, req)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200", resp.StatusCode)
+	}
+	_, total, err := rec.Query(t.Context(), audit.Filter{})
+	if err != nil {
+		t.Fatalf("Query: %v", err)
+	}
+	if total != 0 {
+		t.Fatalf("a safe GET was audited (%d rows) — trail should skip non-security reads", total)
+	}
+}
+
+// TestAudit_AdminReadIsAudited proves a SUCCESSFUL admin read is audited (admin
+// access itself is an AC-relevant event), distinguishing it from a normal read.
+func TestAudit_AdminReadIsAudited(t *testing.T) {
+	app, rec := newAuditApp(t)
+
+	req := httptest.NewRequest(http.MethodGet, "/v1/admin/orgs", nil)
+	asAdmin(req)
+	resp := mustTest(t, app, req)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200", resp.StatusCode)
+	}
+	rows, total, err := rec.Query(t.Context(), audit.Filter{})
+	if err != nil {
+		t.Fatalf("Query: %v", err)
+	}
+	if total != 1 {
+		t.Fatalf("admin read recorded %d, want 1", total)
+	}
+	if !rows[0].Auth.IsAdmin || rows[0].Outcome.Result != "success" {
+		t.Errorf("admin read record = auth.isAdmin=%v outcome=%+v, want admin+success", rows[0].Auth.IsAdmin, rows[0].Outcome)
+	}
+}
+
+// TestAudit_NeverCapturesRequestBody is the secret-safety proof: a mutation whose
+// body is FULL of credentials is audited, but the stored record contains NONE of
+// the body — the middleware captures metadata only, so a secret in a body can
+// never leak into the trail. This is the "reuse RedactUserSecrets" guarantee at
+// its strongest: the code that could leak a secret never reads it.
+func TestAudit_NeverCapturesRequestBody(t *testing.T) {
+	app, rec := newAuditApp(t)
+
+	secretBody := `{"username":"bob","password":"hunter2","apiKey":"sk-live-DEADBEEF","token":"ghp_SECRET"}`
+	req := httptest.NewRequest(http.MethodPost, "/v1/iam/users", strings.NewReader(secretBody))
+	req.Header.Set("Content-Type", "application/json")
+	asAdmin(req)
+	// Also stuff a secret into a header value that is NOT an identity header — it
+	// must not be captured either (we only record User-Agent + XFF, never arbitrary
+	// headers, and never Authorization's value).
+	req.Header.Set("Authorization", "Bearer eyJsuper.secret.token.value")
+	resp := mustTest(t, app, req)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200", resp.StatusCode)
+	}
+
+	rows, total, err := rec.Query(t.Context(), audit.Filter{})
+	if err != nil {
+		t.Fatalf("Query: %v", err)
+	}
+	if total != 1 {
+		t.Fatalf("recorded %d, want 1", total)
+	}
+	// Serialize the WHOLE record and scan for any secret substring.
+	blob, _ := json.Marshal(rows[0])
+	for _, secret := range []string{"hunter2", "sk-live-DEADBEEF", "ghp_SECRET", "super.secret.token.value"} {
+		if strings.Contains(string(blob), secret) {
+			t.Fatalf("SECRET LEAKED into audit record: %q found in %s", secret, blob)
+		}
+	}
+	// But the metadata IS there: the auth method is classified without the token.
+	if rows[0].Auth.Method != "jwt" {
+		t.Errorf("auth method = %q, want jwt (classified from prefix, token not stored)", rows[0].Auth.Method)
+	}
+	if rows[0].Before != nil || rows[0].After != nil {
+		t.Errorf("middleware set before/after (%s / %s) — it must never read bodies", rows[0].Before, rows[0].After)
+	}
+}
+
+// TestAudit_ScrubsCredentialInPath proves a credential-shaped token that rides in
+// the URL PATH (e.g. a KMS route where a caller wrongly puts an sk-/hk- key in the
+// path) is never recorded verbatim in either Path or resource.ID — defense in
+// depth beyond "bodies are never read". A normal identifier is untouched.
+func TestAudit_ScrubsCredentialInPath(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	rec, err := audit.Open(path, nil)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	t.Cleanup(func() { _ = rec.Close() })
+	app := zip.New(zip.Config{})
+	app.Use(AuditTrail(rec))
+	app.Delete("/v1/kms/secrets/*", func(c *zip.Ctx) error {
+		return c.JSON(http.StatusOK, map[string]string{"ok": "true"})
+	})
+
+	// Three credential shapes smuggled into the path across three requests: a
+	// prefixed key, a raw high-entropy hex secret (NO telltale prefix), and a JWT.
+	paths := []struct{ path, secret string }{
+		{"/v1/kms/secrets/sk-live-SUPERSECRETKEY1234567890", "SUPERSECRETKEY"},
+		{"/v1/kms/secrets/deadbeefcafe0123456789abcdef0123456789abcdef0123", "deadbeefcafe0123"},
+		{"/v1/kms/secrets/eyJhbGciOiJIUzI1NiJ9.cGF5bG9hZA.c2ln", "eyJhbGciOiJIUzI1NiJ9"},
+	}
+	for _, tc := range paths {
+		req := httptest.NewRequest(http.MethodDelete, tc.path, nil)
+		asAdmin(req)
+		if resp := mustTest(t, app, req); resp.StatusCode != http.StatusOK {
+			t.Fatalf("%s: status = %d, want 200", tc.path, resp.StatusCode)
+		}
+	}
+
+	rows, total, err := rec.Query(t.Context(), audit.Filter{})
+	if err != nil {
+		t.Fatalf("Query: %v", err)
+	}
+	if total != len(paths) {
+		t.Fatalf("recorded %d, want %d", total, len(paths))
+	}
+	blob, _ := json.Marshal(rows)
+	for _, tc := range paths {
+		if strings.Contains(string(blob), tc.secret) {
+			t.Fatalf("credential in path leaked into record: %q present in %s", tc.secret, blob)
+		}
+	}
+	for _, r := range rows {
+		if !strings.Contains(r.Path, "[REDACTED-TOKEN]") {
+			t.Errorf("path token not scrubbed: %q", r.Path)
+		}
+	}
+}
+
+// TestAudit_ScrubsSecretInUserAgent proves a bearer/API-key embedded in the
+// client-controlled User-Agent is scrubbed, and a normal UA is untouched.
+func TestAudit_ScrubsSecretInUserAgent(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	rec, err := audit.Open(path, nil)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	t.Cleanup(func() { _ = rec.Close() })
+	app := zip.New(zip.Config{})
+	app.Use(AuditTrail(rec))
+	app.Post("/v1/kms/secrets", func(c *zip.Ctx) error { return c.JSON(http.StatusOK, map[string]string{"ok": "1"}) })
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/kms/secrets", nil)
+	asAdmin(req)
+	req.Header.Set("User-Agent", "myclient/1.0 Bearer eyJhbGciOiJI.pay.sig key=sk-live-LEAKME99999")
+	mustTest(t, app, req)
+
+	rows, _, _ := rec.Query(t.Context(), audit.Filter{})
+	if len(rows) != 1 {
+		t.Fatalf("got %d rows, want 1", len(rows))
+	}
+	for _, secret := range []string{"eyJhbGciOiJI", "sk-live-LEAKME99999"} {
+		if strings.Contains(rows[0].UserAgent, secret) {
+			t.Errorf("UA secret leaked: %q in %q", secret, rows[0].UserAgent)
+		}
+	}
+	// The non-secret UA prefix survives (audit usefulness preserved).
+	if !strings.Contains(rows[0].UserAgent, "myclient/1.0") {
+		t.Errorf("UA over-scrubbed, lost the client name: %q", rows[0].UserAgent)
+	}
+}
+
+// TestScrubToken_NoFalsePositives proves legitimate identifiers are NEVER
+// scrubbed — the guard fires only on genuinely secret-shaped segments, so the
+// audit trail keeps its query precision for normal resource ids.
+func TestScrubToken_NoFalsePositives(t *testing.T) {
+	for _, id := range []string{
+		"acme-corp", "gpt-4o-mini", "my_project_123", "user@example.com",
+		"550e8400-e29b-41d4-a716-446655440000", // uuid (hyphens)
+		"claude-opus-4-20250514", "text-embedding-3-large",
+		"my-cool-project-name", "feature-branch-xyz",
+		"deployment-2024-01-15", "report.pdf", "data.json",
+		// Red re-review round 2 — hyphenated model ids MUST pass (AU-3: an auditor
+		// must still see WHICH model a config change touched).
+		"claude-3-5-sonnet-20241022", "claude-3-5-haiku-20241022",
+		"claude-sonnet-4-20250514", "claude-3-7-sonnet-20250219",
+		"claude-3-5-sonnet-latest", "deepseek-r1-distill-qwen-32b",
+		"claude-3-opus-20240229", "stable-diffusion-xl-base",
+		"mixtral-8x7b-instruct", "llama-3-1-8b-instruct", "whisper-large-v3-turbo",
+		"v1", "models", "sync", "12345", "a", "",
+	} {
+		if got := scrubToken(id); got != id {
+			t.Errorf("false scrub: legit id %q → %q", id, got)
+		}
+	}
+	// And genuine secrets ARE scrubbed.
+	for _, sec := range []string{
+		"sk-live-abcdef", "hk-1234567890abcdef", "eyJhbG.payload.signature",
+		"deadbeefcafe0123456789abcdef0123456789abcdef0123", // 48-char raw hex
+	} {
+		if scrubToken(sec) == sec {
+			t.Errorf("missed secret: %q not scrubbed", sec)
+		}
+	}
+}
+
+// TestScrubToken_RedReviewBypassClasses is the regression for the 4 scrub-bypass
+// classes Red found: base64url with -/_, all-alpha opaque >=len, percent-encoded
+// prefixes, and delimiter-glued UA tokens. Each MUST now be redacted.
+func TestScrubToken_RedReviewBypassClasses(t *testing.T) {
+	for _, sec := range []string{
+		"AbCdEf-GhIjKl_MnOpQrStUvWxYz012345",       // base64url with - and _
+		"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN", // all-alpha opaque, no digit
+		"hk%2DROTATEKEY0001SECRETKEY",              // percent-encoded hk-
+		"sk%5Flive%5FBYPASS0001SECRETKEY",          // percent-encoded sk_
+		// Red re-review round 2 — dotted-exemption + encoding + standard-base64:
+		"deadbeefcafe0123456789abcdef0123456789abcdef.x", // ".x" tail forces dotted exemption
+		"AbCdEfGhIjKlMnOpQrStUvWxYz012345.json",          // secret with a filename-ish suffix
+		"hk%252DROTATEKEY0001SECRETKEY",                  // double percent-encoded hk-
+		"AbCdEfGhIjKlMnOpQrStUvWx0123456789",             // 34-char opaque run (standard/url b64)
+		// Red re-review round 3 — interior-hyphen raw secret (NOT a structured id:
+		// only 1 hyphen, long parts) must still redact despite '-' in the run.
+		"aaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbbbbbbbbbb",
+		// Red final re-review — a secret CHUNKED to satisfy the structured-id shape
+		// (>=3 groups <=12 chars) must STILL redact: the lexical (word-like) test
+		// rejects mixed-case base64 chunks and hex chunks (>= hexChunkMinLen=4).
+		"AbCdEfGhIjKl-MnOpQrStUvWx-YzAbCdEfGhIj", // mixed-case base64 chunks
+		"A1b2C3d4-E5f6G7h8-I9j0K1l2",             // 128-bit mixed-case chunks
+		"deadbeef-cafebabe-01234567-89abcdef",    // all-hex chunks (8-char groups)
+		"abcdef01-23456789-abcdef01",             // hex chunks
+		// Red final polish — SMALL hex chunks (md5/sha "xxxx-xxxx" display) now
+		// caught by the len>=4 hex rule.
+		"abcd-ef01-2345-6789-abcd-ef01", // 4-char hex groups
+		"dead-beef-cafe-babe-0123-4567", // 4-char hex groups
+	} {
+		if got := scrubToken(sec); got != "[REDACTED-TOKEN]" {
+			t.Errorf("Red bypass STILL OPEN: %q → %q (want redacted)", sec, got)
+		}
+	}
+	// UA with a secret glued by :/()[]= — must be scrubbed, client name kept.
+	ua := scrubFreeText("myapp/1.0 (token:sk-live-BYPASS0001) [key=hk-1234567890abcdef]")
+	for _, leak := range []string{"sk-live-BYPASS0001", "hk-1234567890abcdef"} {
+		if strings.Contains(ua, leak) {
+			t.Errorf("UA bypass: %q leaked in %q", leak, ua)
+		}
+	}
+	if !strings.Contains(ua, "myapp/1.0") {
+		t.Errorf("UA over-scrubbed, lost client name: %q", ua)
+	}
+	// Red re-review round 2 — a key glued by . @ # ~ must NOT survive.
+	for _, glued := range []string{
+		"client@sk-live-SECRETKEY00001", "app.sk-live-SECRETKEY00001",
+		"build#hk-SECRETKEY000000001", "v1~sk-live-SECRETKEY00001",
+	} {
+		if got := scrubFreeText(glued); strings.Contains(got, "SECRETKEY") {
+			t.Errorf("UA glue-char bypass: %q → %q (secret survives)", glued, got)
+		}
+	}
+	// Normal UAs must be byte-identical (no false scrub).
+	for _, ua := range []string{
+		"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 {
+			t.Errorf("UA false positive: %q → %q", ua, got)
+		}
+	}
+}
+
+// TestAudit_HealthSuffixCannotEvadeAudit proves a mutating request whose path
+// ENDS in /health (an attacker-named wildcard segment) is STILL audited — the
+// liveness exemption is exact and never suppresses a mutation or a denial. This
+// closes an audit-evasion hole where POST /v1/admin/orgs/x/health would slip past.
+func TestAudit_HealthSuffixCannotEvadeAudit(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	rec, err := audit.Open(path, nil)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	t.Cleanup(func() { _ = rec.Close() })
+	app := zip.New(zip.Config{})
+	app.Use(AuditTrail(rec))
+	app.Post("/v1/admin/orgs/*", func(c *zip.Ctx) error { return c.JSON(http.StatusOK, map[string]string{"ok": "1"}) })
+	app.Get("/v1/kms/health", func(c *zip.Ctx) error { return c.JSON(http.StatusOK, map[string]string{"status": "ok"}) })
+
+	// (a) A mutating POST ending in /health MUST be audited.
+	req := httptest.NewRequest(http.MethodPost, "/v1/admin/orgs/evil/health", nil)
+	asAdmin(req)
+	mustTest(t, app, req)
+	_, total, _ := rec.Query(t.Context(), audit.Filter{})
+	if total != 1 {
+		t.Fatalf("EVASION: mutating POST ending /health audited %d times, want 1", total)
+	}
+
+	// (b) A genuine liveness GET /v1/kms/health MUST still be skipped.
+	req2 := httptest.NewRequest(http.MethodGet, "/v1/kms/health", nil)
+	mustTest(t, app, req2)
+	_, total2, _ := rec.Query(t.Context(), audit.Filter{})
+	if total2 != 1 {
+		t.Fatalf("liveness probe was audited (total went %d→%d) — should be exempt", total, total2)
+	}
+}
+
+// TestAudit_AnonRequestNotAttributedToForgedOrg proves an UNAUTHENTICATED
+// attacker cannot forge a false attribution: sending X-Org-Id/X-User-Id/
+// X-User-IsAdmin with no validated principal records an ANONYMOUS actor (empty
+// org+sub, not admin), never the claimed victim org. Runs the REAL SanitizeIdentity
+// (nil validator ⇒ strips authority, restores client X-Org-Id for the data path)
+// ahead of AuditTrail, exactly as serve.go wires them.
+func TestAudit_AnonRequestNotAttributedToForgedOrg(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	rec, err := audit.Open(path, nil)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	t.Cleanup(func() { _ = rec.Close() })
+	app := zip.New(zip.Config{})
+	app.Use(SanitizeIdentity(nil, "admin")) // trust boundary
+	app.Use(AuditTrail(rec))
+	app.Post("/v1/kms/secrets", func(c *zip.Ctx) error { return c.JSON(http.StatusOK, map[string]string{"ok": "1"}) })
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/kms/secrets", nil)
+	// Anonymous attacker forging every identity header.
+	req.Header.Set("X-Org-Id", "victim-org")
+	req.Header.Set("X-User-Id", "victim-user")
+	req.Header.Set("X-User-IsAdmin", "true")
+	mustTest(t, app, req)
+
+	rows, _, _ := rec.Query(t.Context(), audit.Filter{})
+	if len(rows) != 1 {
+		t.Fatalf("got %d rows, want 1", len(rows))
+	}
+	r := rows[0]
+	if r.Auth.IsAdmin {
+		t.Error("forged X-User-IsAdmin survived into the record")
+	}
+	if r.Actor.Sub != "" {
+		t.Errorf("forged X-User-Id recorded as actor.Sub = %q", r.Actor.Sub)
+	}
+	if r.Actor.Org == "victim-org" {
+		t.Errorf("FALSE ATTRIBUTION: anonymous request stamped with claimed org %q", r.Actor.Org)
+	}
+	if r.Auth.Method != "none" {
+		t.Errorf("auth method = %q, want none (no valid credential)", r.Auth.Method)
+	}
+	// The event is still recorded (a mutation), honestly anonymous.
+	if r.Outcome.Result != "success" {
+		t.Errorf("outcome = %+v, want the anonymous mutation recorded", r.Outcome)
+	}
+}
+
+// TestAudit_NoopWhenUnconfigured proves a nil Recorder makes the middleware a
+// pass-through (an unconfigured deployment is never blocked), exactly like
+// BillingGate's nil-client behavior.
+func TestAudit_NoopWhenUnconfigured(t *testing.T) {
+	app := zip.New(zip.Config{})
+	app.Use(AuditTrail(nil))
+	var ran bool
+	app.Post("/v1/kms/secrets", func(c *zip.Ctx) error {
+		ran = true
+		return c.JSON(http.StatusOK, map[string]string{"ok": "true"})
+	})
+	req := httptest.NewRequest(http.MethodPost, "/v1/kms/secrets", nil)
+	resp := mustTest(t, app, req)
+	if resp.StatusCode != http.StatusOK || !ran {
+		t.Fatalf("nil-recorder gate must pass through: status=%d ran=%v", resp.StatusCode, ran)
+	}
+}
+
+// TestAudit_FailsClosedOnWriteError proves that when the audit store cannot
+// record a security-relevant event, the request is failed CLOSED (503) rather
+// than allowed to succeed unlogged (AU-5). We force the failure by closing the
+// store's DB before the request, so Append errors.
+func TestAudit_FailsClosedOnWriteError(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "audit.db")
+	rec, err := audit.Open(path, nil)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	// Close the underlying store so every subsequent Append fails.
+	_ = rec.Close()
+
+	app := zip.New(zip.Config{})
+	app.Use(AuditTrail(rec))
+	var ran bool
+	app.Post("/v1/kms/secrets", func(c *zip.Ctx) error {
+		ran = true
+		return c.JSON(http.StatusCreated, map[string]string{"id": "x"})
+	})
+
+	req := httptest.NewRequest(http.MethodPost, "/v1/kms/secrets", nil)
+	asAdmin(req)
+	resp := mustTest(t, app, req)
+	// The handler may have run (audit wraps AFTER the chain), but the response the
+	// CLIENT sees must be the fail-closed 503, not the handler's 201 — a
+	// security-relevant action that could not be recorded is not acknowledged as
+	// success.
+	if resp.StatusCode != http.StatusServiceUnavailable {
+		t.Fatalf("status = %d, want 503 (fail-closed when audit write fails)", resp.StatusCode)
+	}
+	_ = ran
+}

audit_mirror.go

@@ -0,0 +1,212 @@
+package cloud
+
+// 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 — 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 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).
+//
+// This mirror is NEVER the integrity authority — the local SQLite hash-chain is.
+// Its rows carry the same seq + hash so an operator CAN cross-check the OLAP copy
+// against the chain, but a mirror gap is a query-completeness issue, not a
+// tamper-evidence one. Every mirror error is logged and dropped by the Recorder;
+// the request path never sees it.
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	datastore "github.com/hanzo-ds/go"
+	"github.com/hanzoai/cloud/audit"
+	luxlog "github.com/luxfi/log"
+)
+
+// datastoreMirror writes audit records to a datastore MergeTree table.
+type datastoreMirror struct {
+	conn  datastore.Conn
+	table string
+	log   luxlog.Logger
+}
+
+// newAuditMirror builds the OLAP mirror from operator config, or returns nil when
+// no datastore is configured (mirroring is optional — the local chain is the
+// authority). It connects lazily-validated (a Ping) and ensures the table exists.
+//
+// Config (all from env / KMS-injected secrets, never hard-coded):
+//
+//	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(auditEnv("ADDR"))
+	if addr == "" {
+		return nil, nil // no datastore configured — local chain only.
+	}
+	db := auditEnvOr("DB", "hanzo")
+	table := auditEnvOr("TABLE", "audit_log")
+
+	conn, err := datastore.Open(&datastore.Options{
+		Addr: []string{addr},
+		Auth: datastore.Auth{
+			Database: db,
+			Username: auditEnv("USER"),
+			Password: auditEnv("PASSWORD"),
+		},
+		DialTimeout: 5 * time.Second,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("audit mirror: open: %w", err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	if err := conn.Ping(ctx); err != nil {
+		_ = conn.Close()
+		return nil, fmt.Errorf("audit mirror: ping %s: %w", addr, err)
+	}
+
+	qualified := db + "." + table
+	m := &datastoreMirror{conn: conn, table: qualified, log: log}
+	if err := m.ensureTable(ctx); err != nil {
+		_ = conn.Close()
+		return nil, err
+	}
+	if log != nil {
+		log.Info("audit OLAP mirror connected", "addr", addr, "table", qualified)
+	}
+	return m, nil
+}
+
+// ensureTable creates the append-only audit table if it does not exist. MergeTree
+// = 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 *datastoreMirror) ensureTable(ctx context.Context) error {
+	ddl := fmt.Sprintf(`
+CREATE TABLE IF NOT EXISTS %s (
+  seq        UInt64,
+  ts         DateTime64(3, 'UTC'),
+  actor_org  LowCardinality(String),
+  actor_sub  String,
+  actor_email String,
+  action     LowCardinality(String),
+  res_type   LowCardinality(String),
+  res_id     String,
+  auth_method LowCardinality(String),
+  is_admin   UInt8,
+  result     LowCardinality(String),
+  status     UInt16,
+  reason     String,
+  source_ip  String,
+  user_agent String,
+  request_id String,
+  method     LowCardinality(String),
+  path       String,
+  prev_hash  String,
+  hash       String
+) ENGINE = MergeTree
+PARTITION BY toYYYYMM(ts)
+ORDER BY (actor_org, ts, seq)`, m.table)
+	if err := m.conn.Exec(ctx, ddl); err != nil {
+		return fmt.Errorf("audit mirror: ensure table: %w", err)
+	}
+	return nil
+}
+
+// Append writes one record to the OLAP mirror via the canonical batch idiom. The
+// before/after diffs are DELIBERATELY not mirrored — the OLAP copy is for
+// query/analytics over the event stream, and keeping the (already-redacted but
+// 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 *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,
+  request_id, method, path, prev_hash, hash)`)
+	if err != nil {
+		return fmt.Errorf("audit mirror: prepare: %w", err)
+	}
+	if err := batch.Append(
+		r.Seq, r.Time.UTC(), r.Actor.Org, r.Actor.Sub, r.Actor.Email,
+		r.Action, r.Resource.Type, r.Resource.ID,
+		r.Auth.Method, boolToUint8(r.Auth.IsAdmin),
+		r.Outcome.Result, uint16(r.Outcome.Status), r.Outcome.Reason,
+		r.SourceIP, r.UserAgent, r.RequestID, r.Method, r.Path,
+		r.PrevHash, r.Hash,
+	); err != nil {
+		_ = batch.Abort()
+		return fmt.Errorf("audit mirror: append: %w", err)
+	}
+	return batch.Send()
+}
+
+// Checkpoint persists a head-digest checkpoint to an INDEPENDENT digest table in
+// the datastore — the AU-9 tail-truncation anchor. Because this lives in a store
+// SEPARATE from the local SQLite chain, truncating the chain cannot also rewrite
+// the checkpoint history: an external monitor querying this table sees the count
+// 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 *datastoreMirror) Checkpoint(ctx context.Context, cp audit.Checkpoint) error {
+	if err := m.ensureCheckpointTable(ctx); err != nil {
+		return err
+	}
+	batch, err := m.conn.PrepareBatch(ctx, "INSERT INTO "+m.table+"_checkpoints (ts, count, head)")
+	if err != nil {
+		return fmt.Errorf("audit mirror: checkpoint prepare: %w", err)
+	}
+	if err := batch.Append(cp.Time.UTC(), cp.Count, cp.Head); err != nil {
+		_ = batch.Abort()
+		return fmt.Errorf("audit mirror: checkpoint append: %w", err)
+	}
+	return batch.Send()
+}
+
+// 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 *datastoreMirror) ensureCheckpointTable(ctx context.Context) error {
+	ddl := fmt.Sprintf(`
+CREATE TABLE IF NOT EXISTS %s_checkpoints (
+  ts    DateTime64(3, 'UTC'),
+  count UInt64,
+  head  String
+) ENGINE = MergeTree
+ORDER BY ts`, m.table)
+	if err := m.conn.Exec(ctx, ddl); err != nil {
+		return fmt.Errorf("audit mirror: ensure checkpoint table: %w", err)
+	}
+	return nil
+}
+
+func boolToUint8(b bool) uint8 {
+	if b {
+		return 1
+	}
+	return 0
+}

audit_serve.go

@@ -0,0 +1,108 @@
+package cloud
+
+// Audit trail construction — the wiring Serve calls to stand up the Recorder.
+//
+// The audit store is a COMPLIANCE CONTROL, so its persistence is treated like the
+// pricing catalog overlay's: a non-persistent (in-memory) audit trail would
+// silently lose the record of every prior action on each restart — a fail-OPEN
+// degradation of an integrity control. So an empty DataDir is a hard boot error
+// in a normal run (prod always sets CLOUD_DATA_DIR; provisioning + pricing already
+// require it, so the unified binary always has one). The trail can be turned OFF
+// deliberately (CLOUD_AUDIT_DISABLED=true) for a minimal single-service dev run —
+// an explicit opt-out, never a silent one.
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/hanzoai/cloud/audit"
+	luxlog "github.com/luxfi/log"
+)
+
+// buildAuditRecorder constructs the audit Recorder from cfg: the append-only
+// 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) {
+	if getenvBool("CLOUD_AUDIT_DISABLED") {
+		if logger != nil {
+			logger.Warn("audit trail DISABLED by CLOUD_AUDIT_DISABLED — no tamper-evident record will be kept")
+		}
+		return nil, nil
+	}
+	if cfg.DataDir == "" {
+		return nil, fmt.Errorf("empty DataDir — the audit trail is a compliance control and requires a persistent data dir (set CLOUD_DATA_DIR); refusing to boot with a non-persistent trail that would lose all prior records on restart (or set CLOUD_AUDIT_DISABLED=true to opt out explicitly)")
+	}
+	if err := os.MkdirAll(cfg.DataDir, 0o755); err != nil {
+		return nil, fmt.Errorf("data dir: %w", err)
+	}
+
+	// OLAP mirror is optional and best-effort. A mirror that cannot be reached at
+	// boot must NOT stop the binary — the local chain is the authority — so a
+	// mirror construction error is logged and the trail runs local-only.
+	var mirror audit.Mirror
+	if m, err := newAuditMirror(logger); err != nil {
+		if logger != nil {
+			logger.Warn("audit OLAP mirror unavailable — running local-only (chain integrity unaffected)", "err", err)
+		}
+	} else {
+		mirror = m
+	}
+
+	dbPath := filepath.Join(cfg.DataDir, "audit.db")
+	rec, err := audit.Open(dbPath, mirror)
+	if err != nil {
+		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
+	// checkpoints and alerts on a count regression — the only way to detect that
+	// the most-recent records were deleted (an internal chain walk cannot). The
+	// interval is CLOUD_AUDIT_CHECKPOINT_INTERVAL (default 5m; 0 disables).
+	interval := auditCheckpointInterval()
+	if logger != nil {
+		rec.StartCheckpoints(interval, func(cp audit.Checkpoint) {
+			logger.Info("audit_head_checkpoint",
+				"shard", shard, "count", cp.Count, "head", cp.Head, "ts", cp.Time.Format(time.RFC3339Nano))
+		})
+	} else {
+		rec.StartCheckpoints(interval, nil)
+	}
+
+	if logger != nil {
+		count, head := rec.Head()
+		logger.Info("audit trail ready (tamper-evident, append-only)",
+			"store", dbPath, "shard", shard, "records", count, "head", head,
+			"mirror", mirror != nil, "checkpoint_interval", interval.String())
+	}
+	return rec, nil
+}
+
+// auditCheckpointInterval resolves the head-digest checkpoint cadence.
+// CLOUD_AUDIT_CHECKPOINT_INTERVAL is a Go duration (e.g. "5m", "1h"); default 5m;
+// "0" disables periodic checkpoints (the on-close checkpoint still fires).
+func auditCheckpointInterval() time.Duration {
+	if v := getenv("CLOUD_AUDIT_CHECKPOINT_INTERVAL", ""); v != "" {
+		if d, err := time.ParseDuration(v); err == nil {
+			return d
+		}
+	}
+	return 5 * time.Minute
+}

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

@@ -0,0 +1,539 @@
+package cloud
+
+// In-binary IAM JWT validation — the trust anchor for SanitizeIdentity.
+//
+// This MIRRORS github.com/hanzoai/gateway/v2/iamauth, the canonical edge
+// validator, but cloud deliberately does NOT import that package: iamauth lives
+// in the heavyweight gateway module (KrakenD/gin/traefik) AND gateway/v2 already
+// imports github.com/hanzoai/cloud, so importing it back would braid a module
+// cycle and pull the gateway's whole dependency tree into cloud for ~150 lines
+// of validation. The gateway remains the PRIMARY edge authority — in production
+// it fronts cloud-api (universe routes.yaml). This validator is the in-binary
+// defense-in-depth layer for the in-cluster / direct path, kept tiny and
+// auditable on go-jose alone (already in cloud's module graph).
+//
+// What it enforces, exactly like iamauth.ValidateToken: signature against the
+// IAM JWKS, issuer (strict), audience (allowlist, OR semantics), and expiry —
+// always. A token missing the issuer is rejected.
+
+import (
+	"context"
+	"crypto/rsa"
+	"encoding/base64"
+	"encoding/json"
+	"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"
+	model "github.com/hanzoai/iam/pkg/model"
+)
+
+// idClaims is the subset of Hanzo IAM JWT claims the identity sanitizer needs.
+// Shape mirrors iamauth.Claims so a token resolves identically at both layers.
+type idClaims struct {
+	jwt.Claims
+
+	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"`
+	// Type is IAM's account kind: "application" for a client_credentials MACHINE
+	// identity (object/token_oauth.go stamps Type:"application"), else a human kind
+	// ("normal-user", …). It is the discriminator that keeps a machine token — of ANY
+	// app, not only the KMS-sync one — from ever being granted SuperAdmin. Empty on a
+	// token that predates the claim ⟹ treated as non-machine (fail toward the KMS-aud
+	// check below, never toward granting admin).
+	Type string         `json:"type"`
+	Orgs []model.OrgRef `json:"orgs"` // membership SET (home first); empty on legacy tokens
+}
+
+// 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. 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
+	}
+	if c.PreferredUsername != "" {
+		return c.PreferredUsername
+	}
+	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".
+var jwtSigAlgs = []gojose.SignatureAlgorithm{
+	gojose.RS256, gojose.RS384, gojose.RS512,
+	gojose.ES256, gojose.ES384, gojose.ES512,
+	gojose.PS256, gojose.PS384, gojose.PS512,
+}
+
+// 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 {
+	issuers []string
+	cache   *jwksCache
+	keys    keyResolver // resolves an opaque API key to a principal; nil ⟹ keys stay anonymous
+}
+
+// newIdentityValidator builds a validator whose trusted-issuer set is the primary
+// 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.
+//
+// Trust is IAM-native: signature (JWKS) + issuer (this set) + expiry. There is NO
+// per-app audience allowlist — the `aud` (a minting app's client_id) is IAM's to
+// assign, not cloud's to mirror, so a new first-party app needs zero cloud change.
+func newIdentityValidator(issuer, jwksURL string, ttl time.Duration) *identityValidator {
+	return &identityValidator{
+		issuers: trustedIssuers(issuer),
+		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"
+// (object/token_jwt.go tokenAudience) and owner == <org> (object/token_oauth.go
+// GetClientCredentialsToken sets owner = app.Organization).
+//
+// Validation no longer consults the audience at all (trust is signature + issuer +
+// expiry), so a machine token clears validate() like any other. This suffix survives
+// for the OPPOSITE reason: to RECOGNISE a machine principal (isKMSMachinePrincipal) so
+// SanitizeIdentity can DENY it SuperAdmin even when it carries owner==adminOrg — a
+// client_credentials machine identity must never wield platform-admin. The match is
+// bound to the token's OWN owner claim (<owner>-platform-kms), so it certifies "the
+// KMS sync identity for its own org" and grants nothing wider.
+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
+}
+
+// isMachinePrincipal reports whether a validated token is a MACHINE (non-human)
+// identity — the predicate SanitizeIdentity uses to DENY SuperAdmin and the org-admin
+// signal. A client_credentials token carries IAM's `type` == "application"
+// (object/token_oauth.go), which catches EVERY machine app regardless of its audience;
+// this is the fix for the audience-decomplection widening SuperAdmin's reach — a
+// generic admin-org machine app must not become platform-admin just because it belongs
+// to the admin org. It UNIONS the owner-bound KMS-sync check so a machine token is
+// still excluded even on the (defensive) path where `type` is absent but the
+// <owner>-platform-kms audience is present. Fail-closed: unknown/empty type is treated
+// as NON-machine so a real human admin (who may carry no `type`) is never locked out —
+// the KMS-aud fallback still catches the one machine family we can identify audience-only.
+func isMachinePrincipal(claims *idClaims) bool {
+	return claims.Type == "application" || isKMSMachinePrincipal(claims)
+}
+
+// isMember reports whether org is in the token's signed membership set — the
+// `orgs` claim IAM mints for a USER token, home org first. It is the ONE test that
+// turns a client's org SELECTION into an effective org (SanitizeIdentity), and
+// therefore into the ledger that pays (principal.BillingOrg).
+//
+// The comparison is VERBATIM, no folding, for the same reason the owner claim is
+// taken verbatim: "acme" and "ACME" are DISTINCT orgs in IAM, and a fold would let
+// a member of one select the other. An empty org is never a member, so an absent
+// selection leaves the caller in their home org. An empty set (a legacy token, an
+// opaque key, a machine principal — IAM never mints `orgs` for a client_credentials
+// token) admits nothing, which is exactly the pre-claim behavior.
+func isMember(orgs []model.OrgRef, org string) bool {
+	if org == "" {
+		return false
+	}
+	for _, o := range orgs {
+		if o.Org == org {
+			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) {
+	tok, err := jwt.ParseSigned(raw, jwtSigAlgs)
+	if err != nil {
+		return nil, fmt.Errorf("parse: %w", err)
+	}
+	keys, err := v.cache.get()
+	if err != nil {
+		return nil, fmt.Errorf("jwks: %w", err)
+	}
+
+	var claims idClaims
+	if err := verifyAgainstKeys(tok, keys, &claims); err != nil {
+		return nil, err
+	}
+
+	// Fail SECURE on a misconfigured (empty) trust set: with no trusted issuer every
+	// token must be REJECTED, never silently admitted. In production the set is always
+	// non-empty (the primary issuer + BrandIssuers, unioned in config.go so it is
+	// "never empty"), so this fires ONLY on an operator misconfiguration — and then it
+	// denies, it never admits (I2).
+	if len(v.issuers) == 0 {
+		return nil, fmt.Errorf("identity validator misconfigured: empty issuer set")
+	}
+
+	// Reject a missing issuer: an empty issuer must never pass the set check.
+	if claims.Issuer == "" {
+		return nil, fmt.Errorf("missing issuer")
+	}
+	// Reject a missing expiry: ValidateWithLeeway only enforces exp when present
+	// (it checks `if c.Expiry != nil`), so a token with NO exp would never expire.
+	// An IAM access token always carries exp; require it.
+	if claims.Expiry == nil {
+		return nil, fmt.Errorf("missing expiry")
+	}
+	// 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 (only expiry/not-before stay with Expected).
+	if !issuerAllowed(claims.Issuer, v.issuers) {
+		return nil, fmt.Errorf("untrusted issuer %q", claims.Issuer)
+	}
+	// Audience is NOT an access gate. A valid signature from a trusted issuer (both
+	// checked above) proves IAM minted this token for one of ITS OWN registered apps;
+	// the `aud` merely names which app. Cloud does not keep a per-app allowlist to
+	// mirror IAM's registry — that mirror drifted and silently 401'd every new
+	// first-party app until hand-edited. Org scope is the `owner` claim, enforced by
+	// every downstream guard; SuperAdmin is owner==adminOrg AND !isKMSMachinePrincipal
+	// (SanitizeIdentity). Expiry + not-before are STILL enforced here: Expected{} with a
+	// zero Time validates against time.Now(); an empty AnyAudience skips ONLY the
+	// audience match (go-jose/v4 jwt/validation.go).
+	if err := claims.Claims.ValidateWithLeeway(jwt.Expected{}, 2*time.Minute); err != nil {
+		return nil, fmt.Errorf("claims: %w", err)
+	}
+	return &claims, nil
+}
+
+// verifyAgainstKeys tries the kid-matched key first, then any RSA signing key —
+// mirrors iamauth's selection so a token verifies the same way at both layers.
+func verifyAgainstKeys(tok *jwt.JSONWebToken, keys *gojose.JSONWebKeySet, claims *idClaims) error {
+	var lastErr error
+	for _, h := range tok.Headers {
+		if h.KeyID == "" {
+			continue
+		}
+		for _, k := range keys.Key(h.KeyID) {
+			if err := tok.Claims(k.Key, claims); err == nil {
+				return nil
+			} else {
+				lastErr = err
+			}
+		}
+	}
+	for _, k := range keys.Keys {
+		if k.Use != "sig" && k.Use != "" {
+			continue
+		}
+		if _, ok := k.Key.(*rsa.PublicKey); !ok {
+			continue
+		}
+		if err := tok.Claims(k.Key, claims); err == nil {
+			return nil
+		} else {
+			lastErr = err
+		}
+	}
+	if lastErr != nil {
+		return fmt.Errorf("no matching key: %w", lastErr)
+	}
+	return fmt.Errorf("no matching key in JWKS")
+}
+
+// ----------------------------------------------------------------------------
+// JWKS cache (TTL refresh, stale-on-error) — mirrors iamauth.JWKSCache.
+// ----------------------------------------------------------------------------
+
+type jwksCache struct {
+	mu        sync.RWMutex
+	keys      *gojose.JSONWebKeySet
+	fetchedAt time.Time
+	ttl       time.Duration
+	url       string
+	client    *http.Client
+}
+
+func newJWKSCache(url string, ttl time.Duration) *jwksCache {
+	if ttl <= 0 {
+		ttl = 15 * time.Minute
+	}
+	return &jwksCache{url: url, ttl: ttl, client: &http.Client{Timeout: 10 * time.Second}}
+}
+
+// get returns the cached key set, refreshing past TTL. On a fetch error with a
+// previously-cached set, the stale set is returned rather than failing — a
+// transient JWKS blip must not flap validation (and so admin auth) closed.
+func (c *jwksCache) get() (*gojose.JSONWebKeySet, error) {
+	c.mu.RLock()
+	if c.keys != nil && time.Since(c.fetchedAt) < c.ttl {
+		k := c.keys
+		c.mu.RUnlock()
+		return k, nil
+	}
+	c.mu.RUnlock()
+
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.keys != nil && time.Since(c.fetchedAt) < c.ttl {
+		return c.keys, nil
+	}
+	keys, err := c.fetch()
+	if err != nil {
+		if c.keys != nil {
+			return c.keys, nil
+		}
+		return nil, err
+	}
+	c.keys = keys
+	c.fetchedAt = time.Now()
+	return keys, nil
+}
+
+func (c *jwksCache) fetch() (*gojose.JSONWebKeySet, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.url, nil)
+	if err != nil {
+		return nil, fmt.Errorf("request: %w", err)
+	}
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("fetch: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("status %d", resp.StatusCode)
+	}
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return nil, fmt.Errorf("read: %w", err)
+	}
+	var set gojose.JSONWebKeySet
+	if err := json.Unmarshal(body, &set); err != nil {
+		return nil, fmt.Errorf("parse: %w", err)
+	}
+	return &set, nil
+}
+
+// ----------------------------------------------------------------------------
+// Token extraction — mirrors iamauth's Bearer / Basic / API-key helpers.
+// ----------------------------------------------------------------------------
+
+// APIKeyPrefixes are the Hanzo API key families. A published key (pk-) is
+// write-only and scoped, so it is safe in a public bundle; a secret key (sk-)
+// authenticates a server. Everything else is OAuth2, which is a JWT and not a key.
+//
+// hk- is sk- under an older name and is on its way out. It stays accepted here
+// because IAM mints it — cloud only validates (see account.go mintKey, which
+// delegates to iam.mintUserKey) — so dropping it here before IAM renames the
+// family would reject every key IAM hands out. Retire it in that order: IAM mints
+// sk-, holders re-key, then delete the entry below.
+//
+// fw_ and hz_ were listed here and never minted by anything: dead entries that
+// widened what counts as a credential for no reason. Gone.
+//
+// This is the ONE authority. Admission mirrors it rather than importing it (it
+// stays free of cloud-internal imports); if this list changes, that copy must too.
+var APIKeyPrefixes = []string{"pk-", "sk-", "hk-"}
+
+// PublishablePrefix is the ONE publishable spelling: pk- is the key you may ship
+// in a browser bundle, sk- is the one you may not. Stripe's split, same reason.
+const PublishablePrefix = "pk-"
+
+// IsPublishableKey reports whether tok is a publishable key.
+//
+// A publishable key is NOT a credential: it identifies a tenant so a public
+// surface can WRITE (ingest events), and it must never mint a principal that can
+// READ. Cloud resolved any isAPIKey token — pk- included — into "the same
+// principal a JWT yields", which made a key documented as "safe to show" into a
+// full bearer for the org that owns it. IdentityFromRequest now refuses it, so
+// publishable means publishable.
+//
+// It stays in APIKeyPrefixes on purpose: OrgForKey must still resolve a pk- to
+// its owning org, because that is exactly how the ingest door learns which tenant
+// a browser beacon belongs to. Resolvable, not authenticating.
+func IsPublishableKey(tok string) bool {
+	return strings.HasPrefix(strings.TrimSpace(tok), PublishablePrefix)
+}
+
+// isAPIKey reports whether tok is an opaque, backend-validated key rather than a
+// JWT, so the sanitizer skips JWT parsing for it.
+func isAPIKey(tok string) bool {
+	for _, p := range APIKeyPrefixes {
+		if strings.HasPrefix(tok, p) {
+			return true
+		}
+	}
+	return false
+}
+
+// bearerFromAuth extracts the token from a "Bearer <token>" header value.
+func bearerFromAuth(auth string) string {
+	if auth == "" {
+		return ""
+	}
+	parts := strings.SplitN(auth, " ", 2)
+	if len(parts) != 2 || !strings.EqualFold(parts[0], "Bearer") {
+		return ""
+	}
+	return strings.TrimSpace(parts[1])
+}
+
+// basicFromAuth extracts the token from an HTTP Basic header value: the password
+// field (the go/.netrc proxy idiom), falling back to the username when empty.
+func basicFromAuth(auth string) string {
+	if auth == "" {
+		return ""
+	}
+	parts := strings.SplitN(auth, " ", 2)
+	if len(parts) != 2 || !strings.EqualFold(parts[0], "Basic") {
+		return ""
+	}
+	raw, err := base64.StdEncoding.DecodeString(strings.TrimSpace(parts[1]))
+	if err != nil {
+		return ""
+	}
+	user, pass, ok := strings.Cut(string(raw), ":")
+	if !ok {
+		return ""
+	}
+	if pass != "" {
+		return pass
+	}
+	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_audience_test.go

@@ -0,0 +1,52 @@
+package cloud
+
+import (
+	"crypto/rand"
+	"crypto/rsa"
+	"testing"
+	"time"
+)
+
+// TestValidate_AudienceIsNotAGate proves the IAM-native trust model: a token signed
+// by a trusted issuer validates REGARDLESS of its `aud` (the minting app's client_id).
+// Cloud keeps no per-app audience allowlist mirroring IAM's registry — so a brand-new
+// first-party app works with zero cloud change, and the specific app tokens the old
+// per-app tests pinned (admin-guard, world, team, commerce) are accepted by the SAME
+// rule as everything else. Trust is signature + issuer + expiry; org scope is the
+// owner claim, enforced downstream. Replaces the three audience_*_test.go files that
+// asserted a static allowlist which no longer exists.
+func TestValidate_AudienceIsNotAGate(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("genkey: %v", err)
+	}
+	jwks := jwksServer(t, &key.PublicKey)
+	v := newIdentityValidator(testIssuer, jwks.URL, 0)
+	future := time.Now().Add(time.Hour)
+
+	// Every audience — the apps the deleted per-app tests pinned AND a never-registered
+	// one — validates identically, because aud is not an access gate.
+	for _, aud := range []string{
+		"hanzo-admin-guard", // admin.hanzo.ai forward-auth cockpit
+		"hanzo-world",       // world.hanzo.ai analyst tokens
+		"hanzo-team",        // hanzo.team wallet page
+		"hanzo-commerce",    // commerce.hanzo.ai admin AI assistant
+		"a-brand-new-first-party-app-never-listed-anywhere",
+	} {
+		tok := signWith(t, key, tokenClaims(aud, "acme", "", false, future))
+		id, err := v.validate(tok)
+		if err != nil {
+			t.Fatalf("aud=%q from a trusted issuer must validate (no allowlist), got %v", aud, err)
+		}
+		if id.Owner != "acme" {
+			t.Errorf("aud=%q: owner must be carried through, got %q", aud, id.Owner)
+		}
+	}
+
+	// Expiry is STILL enforced (dropping the aud gate must not disable time checks):
+	// a token expired beyond the 2m leeway is rejected whatever its aud.
+	expired := signWith(t, key, tokenClaims("hanzo-commerce", "acme", "", false, time.Now().Add(-time.Hour)))
+	if _, err := v.validate(expired); err == nil {
+		t.Error("expired token must be REJECTED even though audience is no longer gated")
+	}
+}

auth_identity_kms_test.go

@@ -0,0 +1,101 @@
+package cloud
+
+// The per-org PaaS-KMS sync identity authenticates as its own IAM application
+// "<owner>-platform-kms" (client_credentials), so its token carries owner=<org> and
+// aud=<owner>-platform-kms. Validation no longer gates on the audience at all (trust
+// is signature + issuer + expiry), so a machine token clears validate() like any
+// other. The owner-bound machine aud survives only to IDENTIFY such a principal
+// (isKMSMachinePrincipal) so SanitizeIdentity can DENY it SuperAdmin even in the admin
+// org — a client_credentials machine identity must never wield platform-admin. These
+// are white-box unit tests of that identification; 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.
+
+import (
+	"crypto/rand"
+	"crypto/rsa"
+	"testing"
+	"time"
+)
+
+func TestIdentityValidator_KMSMachinePrincipal(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("genkey: %v", err)
+	}
+	jwks := jwksServer(t, &key.PublicKey)
+	v := newIdentityValidator(testIssuer, jwks.URL, 0)
+	future := time.Now().Add(time.Hour)
+
+	t.Run("own-org machine token validates and is recognised as a machine principal", 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)
+		}
+		if !isKMSMachinePrincipal(c) {
+			t.Fatal("aud==<owner>-platform-kms must be recognised as a machine principal")
+		}
+	})
+
+	t.Run("admin-org machine token is recognised so SuperAdmin is denied", func(t *testing.T) {
+		c, err := v.validate(signWith(t, key, tokenClaims("admin-platform-kms", "admin", "", true, future)))
+		if err != nil {
+			t.Fatalf("admin machine token rejected: %v", err)
+		}
+		if !isKMSMachinePrincipal(c) {
+			t.Fatal("admin-org machine token must be recognised (SanitizeIdentity denies it SuperAdmin)")
+		}
+	})
+
+	t.Run("machine aud bound to a DIFFERENT org is not this owner's machine principal", func(t *testing.T) {
+		// owner=maxpower, aud=acme-platform-kms: the machine-principal match is bound to
+		// the token's OWN owner (maxpower-platform-kms), not a "*-platform-kms" wildcard.
+		// It validates (aud is not gated) and is owner-scoped to maxpower downstream.
+		c, err := v.validate(signWith(t, key, tokenClaims("acme-platform-kms", "maxpower", "", false, future)))
+		if err != nil {
+			t.Fatalf("token rejected: %v", err)
+		}
+		if isKMSMachinePrincipal(c) {
+			t.Fatal("a cross-org machine aud must not count as this owner's machine principal")
+		}
+	})
+
+	t.Run("ordinary app token is not a machine principal", func(t *testing.T) {
+		c, err := v.validate(signWith(t, key, tokenClaims("hanzo-console", "maxpower", "", false, future)))
+		if err != nil {
+			t.Fatalf("token rejected: %v", err)
+		}
+		if isKMSMachinePrincipal(c) {
+			t.Fatal("an ordinary app token is not a machine principal")
+		}
+	})
+
+	t.Run("empty-owner token is never a machine principal (fail closed)", func(t *testing.T) {
+		c, err := v.validate(signWith(t, key, tokenClaims("-platform-kms", "", "", false, future)))
+		if err != nil {
+			t.Fatalf("token rejected: %v", err)
+		}
+		if isKMSMachinePrincipal(c) {
+			t.Fatal(`empty-owner token must never be a machine principal (kmsMachineAudience("")=="")`)
+		}
+	})
+
+	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,120 @@
+package cloud
+
+import (
+	"crypto/rand"
+	"crypto/rsa"
+	"os"
+	"testing"
+	"time"
+)
+
+// TestValidate_FailSecureOnEmptyTrustSet proves I2: a validator whose resolved
+// issuer set is empty REJECTS an otherwise-valid, correctly signed token — the axis
+// is never silently disabled. Production always resolves a non-empty set; this
+// guards the misconfiguration path (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, 0).validate(tok); err != nil {
+		t.Fatalf("baseline valid token must be accepted, got %v", err)
+	}
+
+	// Empty issuer set → deny (construct directly; trustedIssuers never yields empty
+	// with a primary, so bypass it to exercise the guard).
+	vEmptyIss := &identityValidator{issuers: nil, cache: newJWKSCache(jwks.URL, 0), keys: newIAMKeys()}
+	if _, err := vEmptyIss.validate(tok); err == nil {
+		t.Error("empty issuer set 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", 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)
+	}
+}

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

@@ -0,0 +1,139 @@
+package cloud
+
+import "strings"
+
+// Brand white-label registry (HIP-0111).
+//
+// The cloud binary is one artifact serving every brand's API host
+// (api.hanzo.ai, api.lux.cloud, api.zoo.cloud, api.cloud.pars.network, ...).
+// Brand is a per-deployment value (CLOUD_BRAND / --brand). This registry maps a
+// brand to its PUBLIC IAM facts — the canonical OIDC issuer the deployment must
+// validate JWTs against. These are public (issuer host + brand domain), so they
+// live in code, not in KMS.
+//
+// One source of truth: nothing else in the binary hardcodes a per-brand issuer.
+// Config.IAMIssuer is derived from here when the operator does not pin one, so a
+// lux deployment validates against lux.id, a zoo deployment against zoo.id, etc.,
+// instead of silently defaulting every brand to iam.hanzo.ai.
+
+// BrandInfo is the PUBLIC per-brand identity used for token validation + URL
+// scoping. No secrets.
+type BrandInfo struct {
+	// ID is the canonical brand key.
+	ID string
+	// 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
+	// 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
+// by CLOUD_BRAND. Per HIP-0111 §Brands: hanzo→hanzo.id, lux→lux.id,
+// zoo→zoo.id, pars→pars.id, bootnode→id.bootno.de.
+//
+// IAMIssuer MUST equal the `iss` IAM actually stamps AND host the signing JWKS.
+// For hanzo the live .well-known/openid-configuration on BOTH hanzo.id and
+// iam.hanzo.ai reports issuer=https://hanzo.id + jwks_uri=
+// 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 — 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", 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"},
+}
+
+// DefaultBrand is the fallback brand when CLOUD_BRAND is unknown.
+const DefaultBrand = "hanzo"
+
+// BrandFor returns the BrandInfo for id, falling back to the Hanzo brand for an
+// unknown id. Lookup is case-insensitive.
+func BrandFor(id string) BrandInfo {
+	if b, ok := brands[strings.ToLower(strings.TrimSpace(id))]; ok {
+		return b
+	}
+	return brands[DefaultBrand]
+}
+
+// IssuerForBrand returns the canonical OIDC issuer for a brand id.
+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
+}

brand_test.go

@@ -0,0 +1,85 @@
+package cloud
+
+import (
+	"os"
+	"testing"
+)
+
+func TestBrandFor(t *testing.T) {
+	// hanzo → hanzo.id (NOT iam.hanzo.ai): brand.go was pinned to the real OIDC
+	// issuer in fddaeb14 ("pin hanzo IAM issuer to hanzo.id") — iam.hanzo.ai is a
+	// routing alias, and the live .well-known reports iss=https://hanzo.id, so a
+	// token would fail the issuer check against iam.hanzo.ai. This stale
+	// assertion predated that pin; aligned here (drive-by, brand.go unchanged).
+	cases := map[string]string{
+		"hanzo":    "https://hanzo.id",
+		"lux":      "https://lux.id",
+		"zoo":      "https://zoo.id",
+		"pars":     "https://pars.id",
+		"bootnode": "https://id.bootno.de",
+		"LUX":      "https://lux.id",   // case-insensitive
+		"  zoo  ":  "https://zoo.id",   // trimmed
+		"unknown":  "https://hanzo.id", // falls back to hanzo
+		"":         "https://hanzo.id", // empty → hanzo default
+	}
+	for brand, want := range cases {
+		if got := IssuerForBrand(brand); got != want {
+			t.Errorf("IssuerForBrand(%q) = %q, want %q", brand, got, want)
+		}
+	}
+}
+
+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.
+func TestLoadConfig_IssuerDerivedFromBrand(t *testing.T) {
+	t.Setenv("CLOUD_BRAND", "lux")
+	os.Unsetenv("CLOUD_IAM_ISSUER")
+	cfg := LoadConfig()
+	if cfg.IAMIssuer != "https://lux.id" {
+		t.Fatalf("derived issuer = %q, want https://lux.id", cfg.IAMIssuer)
+	}
+	if cfg.Brand != "lux" {
+		t.Fatalf("brand = %q, want lux", cfg.Brand)
+	}
+}

build.go

@@ -1,11 +1,28 @@
 package cloud
 
 import (
+	"context"
+	"encoding/base64"
 	"fmt"
+	"os"
+	"strings"
+	"time"
 
+	aiobject "github.com/hanzoai/ai/object"
+	"github.com/hanzoai/cloud/cek"
+	"github.com/hanzoai/cloud/clients/commerceinproc"
+	"github.com/hanzoai/cloud/clients/metering"
+	"github.com/hanzoai/cloud/internal/org"
+	s3 "github.com/hanzoai/s3-go"
 	luxlog "github.com/luxfi/log"
+	"github.com/zap-proto/zip"
 
 	"github.com/hanzoai/cloud/clients"
+	"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).
@@ -33,7 +50,7 @@ import (
 // JSON does not appear in any of these paths. Inter-subsystem calls
 // are ZAP-typed Go values either via direct method dispatch (mode 1)
 // or via ZAP RPC over the wire (mode 2). JSON happens only at the
-// gateway/ingress edge, through the hanzoai/zip jsonenc helper.
+// gateway/ingress edge, through the zip jsonenc helper.
 //
 // Payments and Vault are special: they are NEVER in-process per
 // HIP-0106 solo-vault CDE. Their clients always resolve via
@@ -41,57 +58,282 @@ 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,
 		"data_dir", cfg.DataDir,
 		"enabled", cfg.Enable,
 	)
 
 	deps := Deps{
-		Logger:  logger,
-		Brand:   cfg.Brand,
-		Domain:  cfg.Domain,
-		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,
+		AIFallbackModel: cfg.AIFallbackModel,
 	}
 
 	// 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)
+	// AI (completions, WRITE) and Embed (embeddings, READ-ONLY) are DISTINCT
+	// credentials by concern: completions never ride the read-only publishable
+	// (pk-) key — the gateway 403s a pk- key on any write endpoint — so deps.AI
+	// resolves to the M2M identity, while deps.Embed keeps the pk- key (correct
+	// least-privilege for a read-only call). Both meter through the ONE commerce path.
+	deps.AI = meteredAIClient(pickCompletionsClient(cfg, logger), deps)
+	deps.Embed = meteredAIClient(pickEmbedClient(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)
+	deps.Durable = buildDurability(cfg, logger)
 
 	// Payments and Vault never co-resident. Disabled stub when no
 	// endpoint, otherwise RPC.
 	deps.Payments = pickPaymentsClient(cfg, logger)
 	deps.Vault = pickVaultClient(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
 }
 
-// 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
+// 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.IAMZAPAddr != "" {
-		log.Info("deps.IAM → ZAP RPC", "addr", cfg.IAMZAPAddr)
-		return clients.IAMRPCAt(cfg.IAMZAPAddr)
+	if cfg.EdgeRateEnabled {
+		p.PerIPRPM = cfg.EdgeRatePerIP
 	}
-	return clients.DisabledIAM()
+	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: 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
+		// client (no-op gate) rather than failing boot over billing wiring.
+		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", boolStr(inProcess, "in-process", "http:"+base), "fail_open", cfg.BillingFailOpen)
+	} else {
+		log.Info("billing gate disabled (no commerce URL)")
+	}
+	return m
+}
+
+func boolStr(b bool, t, f string) string {
+	if b {
+		return t
+	}
+	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
+	}
+	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("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 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("kms") {
-		return nil
+		// 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()
+		}
+		return c
 	}
 	if cfg.KMSZAPAddr != "" {
 		log.Info("deps.KMS → ZAP RPC", "addr", cfg.KMSZAPAddr)
@@ -100,20 +342,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)
@@ -122,50 +579,286 @@ func pickCommerceClient(cfg *Config, log luxlog.Logger) CommerceClient {
 	return clients.DisabledCommerce()
 }
 
-func pickAIClient(cfg *Config, log luxlog.Logger) AIClient {
-	if cfg.Enabled("ai") {
-		return nil
+// 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
+}
+
+// publishableKey reports whether apiKey is a read-only PUBLISHABLE key (pk-). The
+// Hanzo gateway 403s a publishable key on any WRITE endpoint — "Publishable keys
+// can only access read-only endpoints … use a secret key (sk-)". So the COMPLETIONS
+// resolver must refuse it (it would only 403 chat), while the EMBED resolver accepts
+// it (embeddings ARE read-only). pk- is the IAM key family's read-only member
+// (hk-/sk-/pk-/fw_/hz_; clients/admission). This ONE predicate is the split's crux:
+// it kept the intermittent-403 bug — a pk- embed key riding the shared completions
+// client — from ever recurring, wherever the key comes from.
+func publishableKey(apiKey string) bool {
+	return strings.HasPrefix(strings.TrimSpace(apiKey), "pk-")
+}
+
+// pickCompletionsClient resolves deps.AI — the client the agents run path (and
+// guide/crm/content/sitegen/code /ask) execute CHAT COMPLETIONS through. There is
+// NO in-process "ai" mount that fills a nil deps.AI: inference is an external
+// gateway, so this returns a concrete client, never nil.
+//
+// Completions are a WRITE endpoint: a read-only publishable (pk-) key 403s them. So
+// this resolver NEVER rides a pk- key — that is the embed credential (pickEmbedClient).
+// Preference order:
+//  1. Static SECRET-key HTTP gateway when a base URL AND a completions-capable
+//     (non-pk-) static key are configured — an explicit operator override (sk-/hk-).
+//     A pk- key here is REFUSED (it would only 403 chat) and the resolver falls
+//     through to M2M — THE fix for the intermittent publishable-key 403 on bot replies.
+//  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. Secret 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 pickCompletionsClient(cfg *Config, log luxlog.Logger) AIClient {
+	if cfg.AIBaseURL != "" && cfg.AIAPIKey != "" && !publishableKey(cfg.AIAPIKey) {
+		log.Info("deps.AI (completions) → HTTP gateway (static secret key)", "base_url", cfg.AIBaseURL, "default_model", cfg.AIDefaultModel)
+		return clients.AIHTTPAt(cfg.AIBaseURL, cfg.AIAPIKey, cfg.AIDefaultModel)
+	}
+	if cfg.AIAPIKey != "" && publishableKey(cfg.AIAPIKey) {
+		log.Info("deps.AI (completions) → refusing read-only publishable (pk-) key for chat; using M2M", "base_url", cfg.AIBaseURL)
+	}
+	if cfg.AIBaseURL != "" && cfg.AIAuthClientID != "" && cfg.AIAuthClientSecret != "" {
+		tokenURL := aiM2MTokenURL(cfg)
+		if tokenURL != "" {
+			log.Info("deps.AI (completions) → 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)
+		log.Info("deps.AI (completions) → ZAP RPC", "addr", cfg.AIZAPAddr)
 		return clients.AIRPCAt(cfg.AIZAPAddr)
 	}
+	log.Info("deps.AI (completions) → disabled (no secret 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
+// pickEmbedClient resolves deps.Embed — the client code-index + KB knowledge run
+// EMBEDDINGS through. Embeddings are a READ-ONLY endpoint, so the read-only
+// publishable (pk-) key (CLOUD_AI_API_KEY ← cloud-ai-embed-key) is the CORRECT
+// least-privilege credential here, and is used UNCHANGED — this path is deliberately
+// not rewired. Preference order:
+//  1. Static-key HTTP gateway when a base URL AND a static key are configured. The
+//     key (pk- or sk-) is a KMS-injected secret; only base URL + model are logged.
+//  2. Otherwise share the completions resolution (M2M / ZAP / fail-closed) so a
+//     deploy with no dedicated embed key still indexes — no regression.
+func pickEmbedClient(cfg *Config, log luxlog.Logger) AIClient {
+	if cfg.AIBaseURL != "" && cfg.AIAPIKey != "" {
+		log.Info("deps.Embed → HTTP gateway (static embed key)", "base_url", cfg.AIBaseURL, "default_model", cfg.AIDefaultModel)
+		return clients.AIHTTPAt(cfg.AIBaseURL, cfg.AIAPIKey, cfg.AIDefaultModel)
 	}
-	if cfg.O11yZAPAddr != "" {
-		log.Info("deps.O11y → ZAP RPC", "addr", cfg.O11yZAPAddr)
-		return clients.O11yRPCAt(cfg.O11yZAPAddr)
+	return pickCompletionsClient(cfg, log)
+}
+
+// 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
 	}
-	// O11y disabled-stub is no-op (not fail-closed) — telemetry
-	// going nowhere is a normal mode.
-	return clients.DisabledO11y()
+	if base := strings.TrimRight(strings.TrimSpace(os.Getenv("IAM_URL")), "/"); base != "" {
+		return base + "/v1/iam/oauth/token"
+	}
+	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") {
+// durableBucket holds every org's HA-SQLite snapshot (and its writer lease). One
+// bucket, keys laid out orgs/<slug>[/…]/<subsystem>.db per HIP-0302 — the durable
+// twin of the on-disk DataDir layout.
+//
+// OPERATIONAL REQUIREMENTS the fence depends on (enforce in the SeaweedFS deployment,
+// not in code):
+//
+//   - Object versioning + a no-expiry / no-lifecycle-deletion policy on this prefix.
+//     The writer lease (orgs/<slug>/.owner) is the round's system of record; if the
+//     gateway silently drops or rolls back that object, a monotone round can reset and
+//     un-fence a zombie writer (Red M4). A local high-water-round floor per pod is the
+//     future in-process defense; the object lifecycle is the operational one.
+//   - RWO, per-writer PVCs for DataDir — NEVER an RWX shared volume (Red M5). Two pods
+//     on one DataDir corrupt SQLite regardless of this fence; single-writer here is the
+//     durable-copy fence, and per-pod RWO is the local-file guarantee the shard router
+//     already relies on (see shardrouter.go).
+const durableBucket = "org-db"
+
+// buildDurability constructs the deployment's HA-durability factory, or nil when the
+// deployment has no object store to be durable against (dev/single-node — every
+// OrgStore then stays local-only). It composes the SeaweedFS S3 If-Match
+// ConditionalStore (the SAME s3admin identity deps.VFS uses), the writer membership
+// over CLOUD_PEERS (the SAME set the shard router elects on, so the store-layer owner
+// and the routed owner agree), and the per-org envelope Cipher rooted at the KMS
+// master. Any construction failure fails SAFE to nil (local-only) rather than crash
+// the boot; an encryption-capable build with no usable cipher is REFUSED — a build
+// that promises encryption never ships plaintext snapshots to the object store.
+func buildDurability(cfg *Config, log luxlog.Logger) *Durability {
+	// A multi-replica deployment REQUIRES the durable plane: with >1 writer, a per-org
+	// store that is not hydrate-on-open + fenced is the outage this exists to fix.
+	// disabledDurability logs at the severity the replica count warrants, so a
+	// misconfigured prod deployment is never SILENTLY non-durable (Red L2).
+	multiReplica := len(parsePeers(cfg.ShardPeers)) > 1
+
+	// Explicit opt-in: the object-store fence rests on the deployed SeaweedFS enforcing
+	// conditional-PUT (If-Match) atomically, which must be validated against the deployed
+	// version before it fences real tenant data (the takeover-fence staging gate). Until
+	// CLOUD_RESEARCH_DURABLE is set the store runs local-only — the shard router still
+	// pins each org to one writer, so this is not the rolling-deploy outage; only the
+	// cross-restart object-store snapshot waits for the opt-in.
+	if !cfg.ResearchDurable {
+		disabledDurability(log, multiReplica, "CLOUD_RESEARCH_DURABLE not set — HA object-store durability is opt-in pending the SeaweedFS conditional-PUT atomicity gate")
 		return nil
 	}
-	if cfg.MQZAPAddr != "" {
-		log.Info("deps.MQ → ZAP RPC", "addr", cfg.MQZAPAddr)
-		return clients.MQRPCAt(cfg.MQZAPAddr)
+
+	admin := s3admin.New()
+	if !admin.Configured() {
+		disabledDurability(log, multiReplica, "no S3 admin creds (S3_ADMIN_* unset)")
+		return nil
 	}
-	return clients.DisabledMQ()
+	client, err := admin.Client()
+	if err != nil {
+		disabledDurability(log, multiReplica, fmt.Sprintf("S3 client construction failed: %v", err))
+		return nil
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	if err := ensureDurableBucket(ctx, admin, client); err != nil {
+		// Non-fatal: the bucket likely already exists; a later ship/hydrate retries.
+		log.Warn("durability bucket ensure failed (continuing)", "bucket", durableBucket, "err", err)
+	}
+	cancel()
+
+	// Membership: CLOUD_PEERS (the shard router's set). A single-pod deployment with
+	// no peers is its own sole writer — still hydrate-on-open + fenced ship across a
+	// rolling restart.
+	self := firstNonEmptyStr(strings.TrimSpace(cfg.ShardSelf), hostnameOr("cloud-0"))
+	peers := parsePeers(cfg.ShardPeers)
+	if len(peers) == 0 {
+		peers = []org.Member{{ID: self, Addr: self}}
+	}
+	members := org.NewMembership(self, org.StaticSource(peers...), 5*time.Second)
+	_ = members.Start(context.Background()) // static source: the initial refresh populates Members()
+
+	cipher := durableCipher(cfg, log)
+	if cipher == nil && cek.Encrypting() {
+		// The master that satisfied cek must decode here too, so this is a genuine
+		// misconfig, not a dev path: never ship plaintext snapshots AND never silently
+		// drop durability — fail closed and log LOUDLY for the replica count.
+		disabledDurability(log, multiReplica, "encryption-capable build but no durable cipher (would ship plaintext snapshots)")
+		return nil
+	}
+
+	log.Info("durability enabled", "bucket", durableBucket, "self", self, "peers", len(peers), "encrypted", cipher != nil)
+	return org.NewDurability(org.NewS3ConditionalStore(client, durableBucket), members, cipher)
+}
+
+// disabledDurability records that the durable plane is OFF, at ERROR when the
+// deployment is multi-replica (per-org stores then survive only via shard routing +
+// per-pod RWO PVC; a lost/rescheduled PVC loses committed data — the operator MUST
+// configure S3) and at INFO when single-replica/dev (local-only is the expected
+// posture). One place, so no disabled path is silent on a deployment that needs HA.
+func disabledDurability(log luxlog.Logger, multiReplica bool, why string) {
+	if multiReplica {
+		log.Error("DURABILITY DISABLED on a MULTI-REPLICA deployment — per-org stores survive only via shard routing + per-pod RWO PVC; a lost/rescheduled PVC loses committed data. Configure S3_ADMIN_* to enable the durable plane.", "reason", why)
+		return
+	}
+	log.Info("durability disabled — single-replica/dev, per-org stores stay local-only", "reason", why)
+}
+
+// ensureDurableBucket creates the durable bucket if absent (idempotent).
+func ensureDurableBucket(ctx context.Context, admin s3admin.Admin, client *s3.Client) error {
+	ok, err := client.BucketExists(ctx, durableBucket)
+	if err != nil {
+		return err
+	}
+	if ok {
+		return nil
+	}
+	return client.MakeBucket(ctx, durableBucket, s3.MakeBucketOptions{Region: admin.Region()})
+}
+
+// durableCipher builds the per-org envelope Cipher from the base64 KMS master
+// (CLOUD_KMS_MASTER_KEY_REF — the SAME key cek derives from). nil when no valid
+// 32-byte master is configured (pure-Go dev → plaintext durable object, matching the
+// plaintext local file).
+func durableCipher(cfg *Config, log luxlog.Logger) *org.Cipher {
+	ref := strings.TrimSpace(cfg.KMSMasterKeyRef)
+	if ref == "" {
+		return nil
+	}
+	master, err := base64.StdEncoding.DecodeString(ref)
+	if err != nil {
+		log.Warn("durable cipher: KMS master key ref is not valid base64", "err", err)
+		return nil
+	}
+	c, err := org.NewCipher(master)
+	if err != nil {
+		log.Warn("durable cipher: invalid KMS master key", "err", err)
+		return nil
+	}
+	return c
+}
+
+// hostnameOr returns the OS hostname, or def when unavailable — a stable self id for
+// a single-pod deployment that sets no CLOUD_POD_NAME.
+func hostnameOr(def string) string {
+	if h, err := os.Hostname(); err == nil && h != "" {
+		return h
+	}
+	return def
 }
 
 func pickPaymentsClient(cfg *Config, log luxlog.Logger) PaymentsClient {
@@ -184,45 +877,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
@@ -230,6 +931,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,25 +6,57 @@ 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 subsystem's Client field nil — the subsystem Mount() is
-// responsible for filling it in.
+// TestBuildDeps_EnabledLeavesNil verifies that BuildDeps leaves an enabled
+// Mount-fills-it subsystem's Client field nil — the subsystem Mount() installs
+// it. KMS is the exception (see TestBuildDeps_KMSEnabledIsInProcess): it is
+// constructed eagerly in BuildDeps because its store must exist before any
+// dependent subsystem mounts.
 func TestBuildDeps_EnabledLeavesNil(t *testing.T) {
 	cfg := &cloud.Config{
 		Brand:   "hanzo",
 		Domain:  "api.hanzo.ai",
-		DataDir: "/tmp",
-		Enable:  []string{"iam", "kms", "base", "commerce", "ai", "o11y", "vfs", "mq"},
+		DataDir: t.TempDir(),
+		Enable:  []string{"iam", "base", "commerce", "ai", "o11y", "vfs", "mq"},
 	}
 	deps := cloud.BuildDeps(cfg)
 
 	if deps.IAM != nil {
 		t.Errorf("deps.IAM: enabled subsystem must leave Client nil, got %T", deps.IAM)
 	}
-	if deps.KMS != nil {
-		t.Errorf("deps.KMS: enabled subsystem must leave Client nil, got %T", deps.KMS)
+}
+
+// TestBuildDeps_KMSEnabledIsInProcess verifies the HIP-0106 "embed KMS in cloud"
+// 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.
+func TestBuildDeps_KMSEnabledIsInProcess(t *testing.T) {
+	cfg := &cloud.Config{
+		Brand:   "hanzo",
+		Domain:  "api.hanzo.ai",
+		DataDir: t.TempDir(),
+		Enable:  []string{"kms"},
+	}
+	deps := cloud.BuildDeps(cfg)
+
+	if deps.KMS == 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.
+	_, err := deps.KMS.GetSecret(context.Background(), "any")
+	if err == nil {
+		t.Fatal("GetSecret with no master key must fail closed")
+	}
+	if clients.IsDisabled(err) {
+		t.Errorf("deps.KMS resolved to the DISABLED stub, want the in-process client: %v", err)
 	}
 }
 

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

@@ -0,0 +1,498 @@
+package cli
+
+import (
+	"bufio"
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+	"golang.org/x/term"
+)
+
+// iamClient is a thin client over the Hanzo IAM OAuth2 surface at
+// {issuer}/v1/iam/oauth/*. It speaks only the standard token + userinfo
+// endpoints; it holds no IAM business logic.
+type iamClient struct {
+	issuer   string
+	clientID string
+	http     *http.Client
+}
+
+func newIAMClient(issuer, clientID string) *iamClient {
+	return &iamClient{
+		issuer:   strings.TrimRight(issuer, "/"),
+		clientID: clientID,
+		http:     &http.Client{Timeout: 30 * time.Second},
+	}
+}
+
+// tokenResp is the OAuth2 token endpoint response (success or RFC-6749 error).
+type tokenResp struct {
+	AccessToken  string `json:"access_token"`
+	RefreshToken string `json:"refresh_token"`
+	TokenType    string `json:"token_type"`
+	ExpiresIn    int64  `json:"expires_in"`
+	Scope        string `json:"scope"`
+	Error        string `json:"error"`
+	ErrorDesc    string `json:"error_description"`
+}
+
+// postForm performs an x-www-form-urlencoded POST to an oauth endpoint and
+// decodes the token response, surfacing OAuth errors as Go errors.
+func (c *iamClient) postForm(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)))
+	}
+	if tr.Error != "" {
+		return nil, fmt.Errorf("iam %s: %s: %s", endpoint, tr.Error, tr.ErrorDesc)
+	}
+	if tr.AccessToken == "" {
+		return nil, fmt.Errorf("iam %s: HTTP %d: no access_token in response", endpoint, resp.StatusCode)
+	}
+	return &tr, nil
+}
+
+// passwordGrant exchanges username+password for a token (the live IAM client
+// supports password grant; device_code is hard-rejected server-side).
+func (c *iamClient) passwordGrant(ctx context.Context, username, password, scope string) (*tokenResp, error) {
+	return c.postForm(ctx, "/v1/iam/oauth/access_token", url.Values{
+		"grant_type": {"password"},
+		"client_id":  {c.clientID},
+		"username":   {username},
+		"password":   {password},
+		"scope":      {scope},
+	})
+}
+
+// refreshGrant exchanges a refresh token for a fresh access token.
+func (c *iamClient) refreshGrant(ctx context.Context, refreshToken string) (*tokenResp, error) {
+	return c.postForm(ctx, "/v1/iam/oauth/refresh_token", url.Values{
+		"grant_type":    {"refresh_token"},
+		"client_id":     {c.clientID},
+		"refresh_token": {refreshToken},
+	})
+}
+
+// decodeJWTClaims base64url-decodes a JWT's payload segment WITHOUT verifying
+// the signature — used only to display the user's own token claims locally.
+func decodeJWTClaims(token string) (map[string]any, error) {
+	parts := strings.Split(token, ".")
+	if len(parts) < 2 {
+		return nil, fmt.Errorf("not a JWT (need 3 dot-separated segments)")
+	}
+	payload, err := base64.RawURLEncoding.DecodeString(strings.TrimRight(parts[1], "="))
+	if err != nil {
+		return nil, fmt.Errorf("decode JWT payload: %w", err)
+	}
+	var claims map[string]any
+	if err := json.Unmarshal(payload, &claims); err != nil {
+		return nil, fmt.Errorf("parse JWT claims: %w", err)
+	}
+	return claims, nil
+}
+
+// claimString reads a string claim, tolerating absence.
+func claimString(claims map[string]any, key string) string {
+	if v, ok := claims[key].(string); ok {
+		return v
+	}
+	return ""
+}
+
+// credsFromToken builds a Credentials carrying the token plus the identity
+// fields decoded from its claims. expiresIn (token endpoint) wins for expiry;
+// otherwise the JWT `exp` claim is used.
+func credsFromToken(tr *tokenResp) *Credentials {
+	c := &Credentials{
+		AccessToken:  tr.AccessToken,
+		RefreshToken: tr.RefreshToken,
+		TokenType:    firstNonEmpty(tr.TokenType, "Bearer"),
+	}
+	if claims, err := decodeJWTClaims(tr.AccessToken); err == nil {
+		c.Subject = firstNonEmpty(claimString(claims, "email"), claimString(claims, "sub"))
+		c.Owner = claimString(claims, "owner")
+		if exp, ok := claims["exp"].(float64); ok {
+			c.Expiry = int64(exp)
+		}
+	}
+	if tr.ExpiresIn > 0 {
+		c.Expiry = time.Now().Add(time.Duration(tr.ExpiresIn) * time.Second).Unix()
+	}
+	return c
+}
+
+// ---------------------------------------------------------------------------
+// Commands: login / logout / whoami, grouped under `auth`.
+// ---------------------------------------------------------------------------
+
+// loginFlags are shared by `hanzo login` and `hanzo auth login`.
+type loginFlags struct {
+	username      string
+	passwordStdin bool
+	token         string
+	platformToken string
+	buildToken    string
+	scope         string
+}
+
+func runLogin(env *Env, lf *loginFlags, cmd *cobra.Command) error {
+	var creds *Credentials
+
+	switch {
+	case lf.token != "":
+		// Paste an externally-minted token. Decode claims for identity.
+		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 == "" {
+			u, err := prompt(cmd, "Email: ")
+			if err != nil {
+				return err
+			}
+			username = u
+		}
+		password, err := readPassword(cmd, lf.passwordStdin)
+		if err != nil {
+			return err
+		}
+		iam := newIAMClient(env.IAMIssuer, env.ClientID)
+		tr, err := iam.passwordGrant(cmd.Context(), username, password, lf.scope)
+		if err != nil {
+			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 with this identity so apps/deploy work post-login.
+	if lf.platformToken != "" {
+		creds.PlatformToken = lf.platformToken
+	}
+	if lf.buildToken != "" {
+		creds.BuildToken = lf.buildToken
+	}
+
+	// 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 [%s] (token expires %s)\n", who, key, shortTime(creds.Expiry))
+	return nil
+}
+
+func newLoginCmd(envOf func() *Env, _ *globalFlags) *cobra.Command {
+	lf := &loginFlags{}
+	cmd := &cobra.Command{
+		Use:   "login",
+		Short: "Authenticate against Hanzo IAM and store a token",
+		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) },
+	}
+	bindLoginFlags(cmd, lf)
+	return cmd
+}
+
+func bindLoginFlags(cmd *cobra.Command, lf *loginFlags) {
+	f := cmd.Flags()
+	f.StringVarP(&lf.username, "username", "u", "", "IAM username/email")
+	f.BoolVar(&lf.passwordStdin, "password-stdin", false, "read the password from stdin (for automation)")
+	f.StringVar(&lf.token, "token", "", "store this access token directly (skip the password grant)")
+	f.StringVar(&lf.platformToken, "platform-token", "", "also store the platform control-plane service token")
+	f.StringVar(&lf.buildToken, "build-token", "", "also store the platform build-enqueue token")
+	f.StringVar(&lf.scope, "scope", "openid profile email", "OAuth scope")
+}
+
+func newLogoutCmd() *cobra.Command {
+	return &cobra.Command{
+		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, args []string) error {
+			store, err := LoadIdentities()
+			if err != nil {
+				return err
+			}
+			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, all bool
+	cmd := &cobra.Command{
+		Use:   "whoami",
+		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`")
+			}
+			claims, err := decodeJWTClaims(tok)
+			if err != nil {
+				return err
+			}
+			if verify {
+				if err := verifyUserInfo(cmd.Context(), env, tok); err != nil {
+					return fmt.Errorf("token rejected by IAM: %w", err)
+				}
+			}
+			return env.emit(claims, func(w io.Writer) {
+				fmt.Fprintf(w, "email:   %s\n", claimString(claims, "email"))
+				fmt.Fprintf(w, "name:    %s\n", firstNonEmpty(claimString(claims, "displayName"), claimString(claims, "name")))
+				fmt.Fprintf(w, "org:     %s\n", claimString(claims, "owner"))
+				fmt.Fprintf(w, "subject: %s\n", claimString(claims, "sub"))
+				fmt.Fprintf(w, "issuer:  %s\n", claimString(claims, "iss"))
+				if exp, ok := claims["exp"].(float64); ok {
+					fmt.Fprintf(w, "expires: %s\n", shortTime(int64(exp)))
+				}
+				if verify {
+					fmt.Fprintln(w, "verified: yes (IAM userinfo accepted the token)")
+				}
+			})
+		},
+	}
+	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
+}
+
+// verifyUserInfo calls the IAM userinfo endpoint with the bearer token; a 2xx
+// means IAM accepts the token as live.
+func verifyUserInfo(ctx context.Context, env *Env, token string) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, env.IAMIssuer+"/v1/iam/oauth/userinfo", nil)
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Authorization", "Bearer "+token)
+	req.Header.Set("User-Agent", "hanzo-cli/"+Version)
+	resp, err := (&http.Client{Timeout: 20 * time.Second}).Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode/100 != 2 {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<16))
+		return fmt.Errorf("HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
+	}
+	return nil
+}
+
+// newAuthCmd is the `auth` group: login/logout/whoami plus `token` (print the
+// stored access token, for piping into other tools).
+func newAuthCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "auth",
+		Short: "Manage authentication and stored identities",
+	}
+	tokenCmd := &cobra.Command{
+		Use:   "token",
+		Short: "Print the active access token",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			tok := envOf().accessToken()
+			if tok == "" {
+				return fmt.Errorf("not logged in: run `hanzo login`")
+			}
+			fmt.Fprintln(cmd.OutOrStdout(), tok)
+			return nil
+		},
+	}
+	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
+}
+
+// ---------------------------------------------------------------------------
+// Terminal helpers.
+// ---------------------------------------------------------------------------
+
+// prompt writes a prompt to stderr and reads a trimmed line from stdin.
+func prompt(cmd *cobra.Command, label string) (string, error) {
+	fmt.Fprint(cmd.ErrOrStderr(), label)
+	r := bufio.NewReader(cmd.InOrStdin())
+	line, err := r.ReadString('\n')
+	if err != nil && err != io.EOF {
+		return "", err
+	}
+	return strings.TrimSpace(line), nil
+}
+
+// readPassword reads a password without echo from the terminal, or as a plain
+// line from stdin when --password-stdin is set (automation) or stdin is not a
+// terminal.
+func readPassword(cmd *cobra.Command, fromStdin bool) (string, error) {
+	if fromStdin {
+		r := bufio.NewReader(cmd.InOrStdin())
+		line, err := r.ReadString('\n')
+		if err != nil && err != io.EOF {
+			return "", err
+		}
+		return strings.TrimRight(line, "\r\n"), nil
+	}
+	if f, ok := cmd.InOrStdin().(*os.File); ok && term.IsTerminal(int(f.Fd())) {
+		fmt.Fprint(cmd.ErrOrStderr(), "Password: ")
+		b, err := term.ReadPassword(int(f.Fd()))
+		fmt.Fprintln(cmd.ErrOrStderr())
+		return string(b), err
+	}
+	// Non-terminal stdin without --password-stdin: read a line so piped input
+	// still works, but nudge toward the explicit flag.
+	r := bufio.NewReader(cmd.InOrStdin())
+	line, err := r.ReadString('\n')
+	if err != nil && err != io.EOF {
+		return "", err
+	}
+	return strings.TrimRight(line, "\r\n"), nil
+}

cli/auth_test.go

@@ -0,0 +1,385 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// makeJWT builds an unsigned JWT (alg=none) carrying claims — enough to test
+// the local, signature-free claim decode the CLI uses for display.
+func makeJWT(claims map[string]any) string {
+	hdr := base64.RawURLEncoding.EncodeToString([]byte(`{"alg":"none","typ":"JWT"}`))
+	p, _ := json.Marshal(claims)
+	return hdr + "." + base64.RawURLEncoding.EncodeToString(p) + ".sig"
+}
+
+func TestDecodeJWTClaims(t *testing.T) {
+	tok := makeJWT(map[string]any{"email": "z@hanzo.ai", "owner": "hanzo", "sub": "abc", "exp": float64(1783110016)})
+	claims, err := decodeJWTClaims(tok)
+	if err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if claimString(claims, "email") != "z@hanzo.ai" || claimString(claims, "owner") != "hanzo" {
+		t.Fatalf("claims wrong: %+v", claims)
+	}
+	if _, err := decodeJWTClaims("not-a-jwt"); err == nil {
+		t.Fatalf("expected error for non-JWT")
+	}
+}
+
+func TestCredsFromToken(t *testing.T) {
+	tok := makeJWT(map[string]any{"email": "z@hanzo.ai", "owner": "hanzo", "exp": float64(2000000000)})
+	// expires_in present → wins over exp.
+	c := credsFromToken(&tokenResp{AccessToken: tok, RefreshToken: "r", ExpiresIn: 3600})
+	if c.Subject != "z@hanzo.ai" || c.Owner != "hanzo" || c.RefreshToken != "r" {
+		t.Fatalf("identity not extracted: %+v", c)
+	}
+	if c.Expiry == 2000000000 {
+		t.Fatalf("expires_in should win over exp claim")
+	}
+	// No expires_in → falls back to exp claim.
+	c2 := credsFromToken(&tokenResp{AccessToken: tok})
+	if c2.Expiry != 2000000000 {
+		t.Fatalf("exp claim fallback failed: %d", c2.Expiry)
+	}
+}
+
+func TestPasswordGrant(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/iam/oauth/access_token" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		_ = r.ParseForm()
+		if r.Form.Get("grant_type") != "password" || r.Form.Get("client_id") != "hanzo-console" ||
+			r.Form.Get("username") != "z@hanzo.ai" || r.Form.Get("password") != "pw" {
+			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,
+			"refresh_token": "r",
+		})
+	}))
+	defer srv.Close()
+
+	c := newIAMClient(srv.URL, "hanzo-console")
+	tr, err := c.passwordGrant(context.Background(), "z@hanzo.ai", "pw", "openid")
+	if err != nil {
+		t.Fatalf("passwordGrant: %v", err)
+	}
+	if tr.AccessToken == "" || tr.RefreshToken != "r" {
+		t.Fatalf("token resp bad: %+v", tr)
+	}
+}
+
+func TestPasswordGrantError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(400)
+		_ = json.NewEncoder(w).Encode(map[string]any{"error": "invalid_grant", "error_description": "bad password"})
+	}))
+	defer srv.Close()
+	c := newIAMClient(srv.URL, "hanzo-console")
+	_, err := c.passwordGrant(context.Background(), "u", "p", "openid")
+	if err == nil || !strings.Contains(err.Error(), "invalid_grant") {
+		t.Fatalf("expected invalid_grant error, got %v", err)
+	}
+}
+
+func TestRefreshGrant(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_ = r.ParseForm()
+		if r.URL.Path != "/v1/iam/oauth/refresh_token" || r.Form.Get("grant_type") != "refresh_token" || r.Form.Get("refresh_token") != "rt" {
+			t.Errorf("bad refresh request: %s %v", r.URL.Path, r.Form)
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"access_token": makeJWT(nil), "token_type": "Bearer"})
+	}))
+	defer srv.Close()
+	c := newIAMClient(srv.URL, "hanzo-console")
+	if _, err := c.refreshGrant(context.Background(), "rt"); err != nil {
+		t.Fatalf("refreshGrant: %v", err)
+	}
+}
+
+// runRoot executes the cobra root with args, returning stdout and any error.
+// stderr is discarded; stdin is provided for password prompts.
+func runRoot(t *testing.T, stdin string, args ...string) (string, error) {
+	t.Helper()
+	root := newRootCmd()
+	var out bytes.Buffer
+	root.SetOut(&out)
+	root.SetErr(new(bytes.Buffer))
+	root.SetIn(strings.NewReader(stdin))
+	root.SetArgs(args)
+	err := root.Execute()
+	return out.String(), err
+}
+
+func TestLoginCommandPasswordStdin(t *testing.T) {
+	sandbox(t)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"access_token": makeJWT(map[string]any{"email": "z@hanzo.ai", "owner": "hanzo"}),
+			"token_type":   "Bearer", "expires_in": 3600,
+		})
+	}))
+	defer srv.Close()
+
+	out, err := runRoot(t, "pw\n", "login", "-u", "z@hanzo.ai", "--password-stdin", "--iam-issuer", srv.URL)
+	if err != nil {
+		t.Fatalf("login: %v", err)
+	}
+	if !strings.Contains(out, "Logged in as z@hanzo.ai @ hanzo") {
+		t.Fatalf("login output: %q", out)
+	}
+	creds, _ := LoadCredentials()
+	if creds.AccessToken == "" || creds.Subject != "z@hanzo.ai" {
+		t.Fatalf("credentials not persisted: %+v", creds)
+	}
+}
+
+func TestLoginTokenPasteAndPlatformToken(t *testing.T) {
+	sandbox(t)
+	tok := makeJWT(map[string]any{"email": "ops@hanzo.ai", "owner": "hanzo"})
+	out, err := runRoot(t, "", "login", "--token", tok, "--platform-token", "svc-123")
+	if err != nil {
+		t.Fatalf("login --token: %v", err)
+	}
+	if !strings.Contains(out, "ops@hanzo.ai") {
+		t.Fatalf("login output: %q", out)
+	}
+	creds, _ := LoadCredentials()
+	if creds.AccessToken != tok || creds.PlatformToken != "svc-123" {
+		t.Fatalf("creds not stored: %+v", creds)
+	}
+}
+
+func TestWhoamiCommand(t *testing.T) {
+	sandbox(t)
+	creds := credsFromToken(&tokenResp{AccessToken: makeJWT(map[string]any{
+		"email": "z@hanzo.ai", "name": "z", "owner": "hanzo", "sub": "u-1", "iss": "https://hanzo.id",
+	})})
+	if err := creds.Save(); err != nil {
+		t.Fatal(err)
+	}
+	out, err := runRoot(t, "", "whoami")
+	if err != nil {
+		t.Fatalf("whoami: %v", err)
+	}
+	for _, want := range []string{"z@hanzo.ai", "hanzo", "u-1", "https://hanzo.id"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("whoami missing %q in %q", want, out)
+		}
+	}
+}
+
+func TestWhoamiLoggedOut(t *testing.T) {
+	sandbox(t)
+	if _, err := runRoot(t, "", "whoami"); err == nil {
+		t.Fatalf("expected error when logged out")
+	}
+}
+
+func TestLogoutCommand(t *testing.T) {
+	sandbox(t)
+	(&Credentials{AccessToken: "x"}).Save()
+	if _, err := runRoot(t, "", "logout"); err != nil {
+		t.Fatalf("logout: %v", err)
+	}
+	if c, _ := LoadCredentials(); c.AccessToken != "" {
+		t.Fatalf("logout did not clear credentials")
+	}
+}
+
+func TestAuthTokenCommand(t *testing.T) {
+	sandbox(t)
+	(&Credentials{AccessToken: "the-token"}).Save()
+	out, err := runRoot(t, "", "auth", "token")
+	if err != nil {
+		t.Fatalf("auth token: %v", err)
+	}
+	if strings.TrimSpace(out) != "the-token" {
+		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

@@ -0,0 +1,784 @@
+// Package cli is the Hanzo cloud-control CLI — the gcloud/doctl-class client
+// half of the `hanzo` binary.
+//
+// `hanzo <subsystem>` SERVES a subsystem (server mode, cmd/hanzo dispatch);
+// `hanzo <verb>` CONTROLS the live estate (client mode, this package):
+//
+//	hanzo login | auth        identity against hanzo.id (IAM)
+//	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 build (runner fabric)
+//	hanzo k8s …               current deploy target helpers
+//	hanzo config …            ~/.hanzo/config preferences
+//
+// It is a THIN client over surfaces that already exist — Hanzo IAM
+// (hanzo.id /v1/iam/oauth/*), the platform REST control plane
+// (platform.hanzo.ai /v1/*), and the cloud /v1 API. It invents no parallel
+// API and holds no business logic; every command is one HTTP call shaped by
+// resolved configuration. Secrets live only in ~/.hanzo (0600) or the
+// environment — never in source, never logged.
+package cli
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+// Version is the binary version, set by cmd/hanzo from its -ldflags value so
+// the CLI and the server report one string. Used in the User-Agent.
+var Version = "dev"
+
+// Default endpoints. Overridable per-field via config / env / flag.
+const (
+	defaultIAMIssuer   = "https://hanzo.id"
+	defaultPlatformURL = "https://platform.hanzo.ai"
+	defaultCloudURL    = "https://api.hanzo.ai"
+	// hanzo-console is the only live IAM client that accepts the password
+	// grant today; a dedicated `hanzo-cli` client is a one-line IAM seed
+	// follow-up. Override with `--client-id` / HANZO_CLIENT_ID / config.
+	defaultClientID = "hanzo-console"
+)
+
+// controlCommands maps every client-mode verb to its one-line help. cmd/hanzo
+// reads this both to ROUTE (a first token in here means client mode) and to
+// list the commands in `hanzo help`, so the verb set is defined exactly once.
+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 + 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 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)",
+	"link":     "bring this machine into the Hanzo cloud fleet as a node (fabric + compute worker)",
+	"unlink":   "take this machine out of the fleet (deregister + stop hanzod)",
+	"status":   "show the org's fleet — every node with each of its GPUs",
+	"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
+// must be routed to this package, not the server dispatcher).
+func IsControlVerb(sub string) bool {
+	_, ok := controlCommands[sub]
+	return ok
+}
+
+// ControlCommands returns the verb→description map for `hanzo help`.
+func ControlCommands() map[string]string { return controlCommands }
+
+// Execute runs the control CLI with args (already stripped of "hanzo"). It is
+// the single entrypoint cmd/hanzo calls for client-mode verbs.
+func Execute(args []string) error {
+	root := newRootCmd()
+	root.SetArgs(args)
+	return root.Execute()
+}
+
+// ---------------------------------------------------------------------------
+// Config — non-secret preferences, ~/.hanzo/config (JSON).
+// ---------------------------------------------------------------------------
+
+// Config holds non-secret CLI preferences. Every field is optional; empty
+// fields fall back to the built-in defaults at resolution time.
+type Config struct {
+	Org         string `json:"org,omitempty"`
+	Output      string `json:"output,omitempty"` // "table" (default) | "json"
+	IAMIssuer   string `json:"iam_issuer,omitempty"`
+	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.
+// AccessToken/RefreshToken are the IAM user identity (from `hanzo login`);
+// PlatformToken/BuildToken are the machine-to-machine tokens the platform
+// REST control plane requires (it cannot validate IAM user tokens).
+type Credentials struct {
+	AccessToken   string `json:"access_token,omitempty"`
+	RefreshToken  string `json:"refresh_token,omitempty"`
+	TokenType     string `json:"token_type,omitempty"`
+	Expiry        int64  `json:"expiry,omitempty"` // unix seconds
+	Subject       string `json:"subject,omitempty"`
+	Owner         string `json:"owner,omitempty"` // org slug from the token
+	PlatformToken string `json:"platform_token,omitempty"`
+	BuildToken    string `json:"build_token,omitempty"`
+}
+
+// hanzoDir is ~/.hanzo, created 0700 if missing. Overridable with HANZO_HOME
+// (used by tests to sandbox the credential store).
+func hanzoDir() (string, error) {
+	if h := os.Getenv("HANZO_HOME"); h != "" {
+		return h, os.MkdirAll(h, 0o700)
+	}
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "", err
+	}
+	dir := filepath.Join(home, ".hanzo")
+	return dir, os.MkdirAll(dir, 0o700)
+}
+
+func configPath() (string, error) {
+	dir, err := hanzoDir()
+	if err != nil {
+		return "", err
+	}
+	if p := os.Getenv("HANZO_CONFIG"); p != "" {
+		return p, nil
+	}
+	return filepath.Join(dir, "config"), nil
+}
+
+func credentialsPath() (string, error) {
+	dir, err := hanzoDir()
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(dir, "credentials.json"), nil
+}
+
+// loadJSON reads a JSON file into v; a missing file is not an error (v is left
+// at its zero value) so first-run with no config/credentials just works.
+func loadJSON(path string, v any) error {
+	b, err := os.ReadFile(path)
+	if os.IsNotExist(err) {
+		return nil
+	}
+	if err != nil {
+		return err
+	}
+	if len(b) == 0 {
+		return nil
+	}
+	return json.Unmarshal(b, v)
+}
+
+// writeJSON writes v as indented JSON at path with the given mode, via a
+// temp-file rename so a crash mid-write never truncates the store.
+func writeJSON(path string, v any, mode os.FileMode) error {
+	b, err := json.MarshalIndent(v, "", "  ")
+	if err != nil {
+		return err
+	}
+	tmp := path + ".tmp"
+	if err := os.WriteFile(tmp, append(b, '\n'), mode); err != nil {
+		return err
+	}
+	return os.Rename(tmp, path)
+}
+
+// LoadConfig reads ~/.hanzo/config (or HANZO_CONFIG).
+func LoadConfig() (*Config, error) {
+	p, err := configPath()
+	if err != nil {
+		return nil, err
+	}
+	c := &Config{}
+	return c, loadJSON(p, c)
+}
+
+// Save persists the config (mode 0644 — non-secret).
+func (c *Config) Save() error {
+	p, err := configPath()
+	if err != nil {
+		return err
+	}
+	return writeJSON(p, c, 0o644)
+}
+
+// LoadCredentials reads ~/.hanzo/credentials.json.
+func LoadCredentials() (*Credentials, error) {
+	p, err := credentialsPath()
+	if err != nil {
+		return nil, err
+	}
+	c := &Credentials{}
+	return c, loadJSON(p, c)
+}
+
+// Save persists credentials with mode 0600 (owner read/write only).
+func (c *Credentials) Save() error {
+	p, err := credentialsPath()
+	if err != nil {
+		return err
+	}
+	return writeJSON(p, c, 0o600)
+}
+
+// DeleteCredentials removes the credential store (used by logout).
+func DeleteCredentials() error {
+	p, err := credentialsPath()
+	if err != nil {
+		return err
+	}
+	if err := os.Remove(p); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	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.
+// ---------------------------------------------------------------------------
+
+// Env is the fully-resolved runtime context for a command: config + creds
+// merged with environment and the global flags. Built once in the root's
+// PersistentPreRunE and read by every subcommand.
+type Env struct {
+	cfg   *Config
+	creds *Credentials
+
+	Org         string
+	Output      string
+	IAMIssuer   string
+	PlatformURL string
+	CloudURL    string
+	ClientID    string
+
+	out io.Writer
+}
+
+// flag values bound by the persistent flags (empty == unset, fall through).
+type globalFlags struct {
+	org, output, platformURL, iamIssuer, cloudURL, clientID, platformToken string
+}
+
+// firstNonEmpty returns the first non-empty argument, or "".
+func firstNonEmpty(vs ...string) string {
+	for _, v := range vs {
+		if v != "" {
+			return v
+		}
+	}
+	return ""
+}
+
+// resolve merges flags > env > config > built-in defaults into an Env. It is
+// pure given its inputs (config/creds are loaded by the caller) so it is
+// directly unit-testable.
+func resolve(cfg *Config, creds *Credentials, f globalFlags) *Env {
+	e := &Env{cfg: cfg, creds: creds, out: os.Stdout}
+	e.Output = firstNonEmpty(f.output, os.Getenv("HANZO_OUTPUT"), cfg.Output, "table")
+	e.IAMIssuer = strings.TrimRight(firstNonEmpty(f.iamIssuer, os.Getenv("HANZO_IAM_ISSUER"), cfg.IAMIssuer, defaultIAMIssuer), "/")
+	e.PlatformURL = strings.TrimRight(firstNonEmpty(f.platformURL, os.Getenv("HANZO_PLATFORM_URL"), cfg.PlatformURL, defaultPlatformURL), "/")
+	e.CloudURL = strings.TrimRight(firstNonEmpty(f.cloudURL, os.Getenv("HANZO_CLOUD_URL"), cfg.CloudURL, defaultCloudURL), "/")
+	e.ClientID = firstNonEmpty(f.clientID, os.Getenv("HANZO_CLIENT_ID"), cfg.ClientID, defaultClientID)
+	// Org for platform calls is the platform organization id (a distinct
+	// namespace from the IAM token's `owner` slug), so it comes only from
+	// flag/env/config — never silently from the token.
+	e.Org = firstNonEmpty(f.org, os.Getenv("HANZO_ORG"), cfg.Org)
+	return e
+}
+
+// accessToken is the IAM user token (identity / cloud calls).
+func (e *Env) accessToken() string {
+	return firstNonEmpty(os.Getenv("HANZO_TOKEN"), e.creds.AccessToken)
+}
+
+// freshAccessToken returns the IAM user token only while it is not yet expired.
+// accessToken() stays expiry-agnostic so `hanzo whoami` can report a dead token
+// rather than masking it as logged-out; freshAccessToken is the code-agent path,
+// where an expired token would 401 a session a still-valid hk- key could serve.
+// No expiry recorded (a raw HANZO_TOKEN with no claims) ⟹ trust it as-is.
+func (e *Env) freshAccessToken() string {
+	tok := e.accessToken()
+	if tok == "" {
+		return ""
+	}
+	if exp := e.creds.Expiry; exp > 0 && time.Now().Unix() >= exp {
+		return ""
+	}
+	return tok
+}
+
+// platformToken resolves the 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,
+		os.Getenv("HANZO_PLATFORM_TOKEN"),
+		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 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
+	)
+}
+
+// requireOrg returns the resolved org or a clear error telling the user how to
+// set it.
+func (e *Env) requireOrg() (string, error) {
+	if e.Org == "" {
+		return "", fmt.Errorf("no org set: pass --org, set HANZO_ORG, or run `hanzo config set org <org>`")
+	}
+	return e.Org, nil
+}
+
+// ---------------------------------------------------------------------------
+// Output helpers — one place decides JSON vs human-readable tables.
+// ---------------------------------------------------------------------------
+
+// emit prints v as JSON when --output=json, otherwise calls table to render a
+// human view. This is the single output branch for every command.
+func (e *Env) emit(v any, table func(w io.Writer)) error {
+	if e.Output == "json" {
+		enc := json.NewEncoder(e.out)
+		enc.SetIndent("", "  ")
+		return enc.Encode(v)
+	}
+	table(e.out)
+	return nil
+}
+
+// ---------------------------------------------------------------------------
+// Root command + global flags.
+// ---------------------------------------------------------------------------
+
+func newRootCmd() *cobra.Command {
+	var f globalFlags
+	var env *Env
+
+	root := &cobra.Command{
+		Use:           "hanzo",
+		Short:         "Hanzo cloud control — manage the live Hanzo estate",
+		Long:          "hanzo — gcloud/doctl-class control for the Hanzo platform (IAM, apps, deploys, clusters, builds).",
+		SilenceUsage:  true,
+		SilenceErrors: false,
+		PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
+			cfg, err := LoadConfig()
+			if err != nil {
+				return fmt.Errorf("load config: %w", err)
+			}
+			creds, err := LoadCredentials()
+			if err != nil {
+				return fmt.Errorf("load credentials: %w", err)
+			}
+			env = resolve(cfg, creds, f)
+			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()
+	pf.StringVar(&f.org, "org", "", "organization (overrides config / HANZO_ORG)")
+	pf.StringVarP(&f.output, "output", "o", "", "output format: table|json")
+	pf.StringVar(&f.platformURL, "platform-url", "", "platform base URL (default "+defaultPlatformURL+")")
+	pf.StringVar(&f.iamIssuer, "iam-issuer", "", "IAM issuer (default "+defaultIAMIssuer+")")
+	pf.StringVar(&f.cloudURL, "cloud-url", "", "cloud API base URL (default "+defaultCloudURL+")")
+	pf.StringVar(&f.clientID, "client-id", "", "IAM OAuth client id (default "+defaultClientID+")")
+	pf.StringVar(&f.platformToken, "platform-token", "", "platform control-plane service token (else env/credential store)")
+
+	// envOf returns the resolved Env for a command's RunE (always non-nil after
+	// PersistentPreRunE).
+	envOf := func() *Env { return env }
+
+	root.AddCommand(
+		newVersionCmd(),
+		newAuthCmd(envOf, &f),
+		newLoginCmd(envOf, &f),
+		newLogoutCmd(),
+		newWhoamiCmd(envOf),
+		newAppsCmd(envOf, &f),
+		newDeployCmd(envOf, &f),
+		newClustersCmd(envOf, &f),
+		newBuildCmd(envOf, &f),
+		newConfigCmd(),
+		newSecurityCmd(envOf),
+		newLinkCmd(envOf, &f),
+		newUnlinkCmd(envOf, &f),
+		newStatusCmd(envOf, &f),
+		newEngineCmd(envOf, &f),
+		newCodeCmd(envOf, &f),
+		newRunnerCmd(envOf, &f),
+		newRunCmd(envOf, &f),
+		newAgentCmd(envOf, &f),
+		newBotCmd(envOf, &f),
+	)
+	return root
+}
+
+func newVersionCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:               "version",
+		Short:             "Print the hanzo version",
+		Args:              cobra.NoArgs,
+		PersistentPreRunE: func(*cobra.Command, []string) error { return nil },
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			fmt.Fprintf(cmd.OutOrStdout(), "hanzo %s\n", Version)
+			return nil
+		},
+	}
+}
+
+// ---------------------------------------------------------------------------
+// config command — view/edit the non-secret preference file.
+// ---------------------------------------------------------------------------
+
+func newConfigCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:               "config",
+		Short:             "View/edit ~/.hanzo/config preferences",
+		PersistentPreRunE: func(*cobra.Command, []string) error { return nil },
+	}
+
+	configKeys := []string{"org", "output", "iam_issuer", "platform_url", "cloud_url", "client_id", "code_tool", "code_model"}
+
+	get := &cobra.Command{
+		Use:   "get <key>",
+		Short: "Print one config value",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg, err := LoadConfig()
+			if err != nil {
+				return err
+			}
+			v, err := cfg.field(args[0])
+			if err != nil {
+				return err
+			}
+			fmt.Fprintln(cmd.OutOrStdout(), v)
+			return nil
+		},
+	}
+
+	set := &cobra.Command{
+		Use:   "set <key> <value>",
+		Short: "Set one config value (keys: " + strings.Join(configKeys, ", ") + ")",
+		Args:  cobra.ExactArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg, err := LoadConfig()
+			if err != nil {
+				return err
+			}
+			if err := cfg.setField(args[0], args[1]); err != nil {
+				return err
+			}
+			if err := cfg.Save(); err != nil {
+				return err
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "set %s = %s\n", args[0], args[1])
+			return nil
+		},
+	}
+
+	list := &cobra.Command{
+		Use:   "list",
+		Short: "Print the full config",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			cfg, err := LoadConfig()
+			if err != nil {
+				return err
+			}
+			enc := json.NewEncoder(cmd.OutOrStdout())
+			enc.SetIndent("", "  ")
+			return enc.Encode(cfg)
+		},
+	}
+
+	path := &cobra.Command{
+		Use:   "path",
+		Short: "Print the config file path",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			p, err := configPath()
+			if err != nil {
+				return err
+			}
+			fmt.Fprintln(cmd.OutOrStdout(), p)
+			return nil
+		},
+	}
+
+	cmd.AddCommand(get, set, list, path)
+	return cmd
+}
+
+// field returns the named config value as a string.
+func (c *Config) field(key string) (string, error) {
+	switch key {
+	case "org":
+		return c.Org, nil
+	case "output":
+		return c.Output, nil
+	case "iam_issuer":
+		return c.IAMIssuer, nil
+	case "platform_url":
+		return c.PlatformURL, nil
+	case "cloud_url":
+		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)
+	}
+}
+
+// setField sets the named config value.
+func (c *Config) setField(key, val string) error {
+	switch key {
+	case "org":
+		c.Org = val
+	case "output":
+		if val != "table" && val != "json" {
+			return fmt.Errorf("output must be table|json")
+		}
+		c.Output = val
+	case "iam_issuer":
+		c.IAMIssuer = val
+	case "platform_url":
+		c.PlatformURL = val
+	case "cloud_url":
+		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)
+	}
+	return nil
+}
+
+// shortTime renders a unix timestamp for human tables; "" for zero.
+func shortTime(unix int64) string {
+	if unix == 0 {
+		return ""
+	}
+	return time.Unix(unix, 0).Format(time.RFC3339)
+}
+
+// sortedKeys returns the keys of m, sorted — for deterministic help output.
+func sortedKeys(m map[string]string) []string {
+	ks := make([]string, 0, len(m))
+	for k := range m {
+		ks = append(ks, k)
+	}
+	sort.Strings(ks)
+	return ks
+}

cli/cli_test.go

@@ -0,0 +1,294 @@
+package cli
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// TestMain restores stdout (quiet.go redirected it to stderr at init) so go
+// test's own reporting stays on stdout.
+func TestMain(m *testing.M) {
+	RestoreStdout()
+	os.Exit(m.Run())
+}
+
+// sandbox isolates the credential/config store in a temp dir and clears every
+// env var resolve() consults, so tests are deterministic and never touch the
+// developer's real ~/.hanzo.
+func sandbox(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	t.Setenv("HANZO_HOME", dir)
+	for _, k := range []string{
+		"HANZO_CONFIG", "HANZO_OUTPUT", "HANZO_IAM_ISSUER", "HANZO_PLATFORM_URL",
+		"HANZO_CLOUD_URL", "HANZO_CLIENT_ID", "HANZO_ORG", "HANZO_TOKEN",
+		"HANZO_PLATFORM_TOKEN", "PLATFORM_SERVICE_TOKEN", "PAAS_SERVICE_TOKEN",
+		"HANZO_BUILD_TOKEN", "PLATFORM_BUILD_CALLBACK_TOKEN",
+	} {
+		t.Setenv(k, "")
+	}
+	return dir
+}
+
+func TestConfigRoundTrip(t *testing.T) {
+	sandbox(t)
+	in := &Config{Org: "acme", Output: "json", PlatformURL: "https://p.example", ClientID: "hanzo-console"}
+	if err := in.Save(); err != nil {
+		t.Fatalf("save: %v", err)
+	}
+	out, err := LoadConfig()
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if *out != *in {
+		t.Fatalf("round-trip mismatch: %+v != %+v", out, in)
+	}
+}
+
+func TestCredentialsRoundTripAndPerms(t *testing.T) {
+	dir := sandbox(t)
+	in := &Credentials{AccessToken: "tok", RefreshToken: "ref", TokenType: "Bearer", Subject: "z@hanzo.ai", Owner: "hanzo", PlatformToken: "pt"}
+	if err := in.Save(); err != nil {
+		t.Fatalf("save: %v", err)
+	}
+	fi, err := os.Stat(filepath.Join(dir, "credentials.json"))
+	if err != nil {
+		t.Fatalf("stat: %v", err)
+	}
+	if perm := fi.Mode().Perm(); perm != 0o600 {
+		t.Fatalf("credentials perm = %o, want 0600", perm)
+	}
+	out, err := LoadCredentials()
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if *out != *in {
+		t.Fatalf("round-trip mismatch: %+v != %+v", out, in)
+	}
+	if err := DeleteCredentials(); err != nil {
+		t.Fatalf("delete: %v", err)
+	}
+	if out, _ := LoadCredentials(); out.AccessToken != "" {
+		t.Fatalf("credentials not deleted")
+	}
+}
+
+func TestLoadMissingFilesIsZeroValue(t *testing.T) {
+	sandbox(t)
+	cfg, err := LoadConfig()
+	if err != nil || cfg.Org != "" {
+		t.Fatalf("missing config should be zero value, got %+v err %v", cfg, err)
+	}
+	creds, err := LoadCredentials()
+	if err != nil || creds.AccessToken != "" {
+		t.Fatalf("missing credentials should be zero value, got %+v err %v", creds, err)
+	}
+}
+
+func TestResolveDefaults(t *testing.T) {
+	sandbox(t)
+	e := resolve(&Config{}, &Credentials{}, globalFlags{})
+	if e.IAMIssuer != defaultIAMIssuer || e.PlatformURL != defaultPlatformURL ||
+		e.CloudURL != defaultCloudURL || e.ClientID != defaultClientID || e.Output != "table" {
+		t.Fatalf("defaults not applied: %+v", e)
+	}
+}
+
+func TestResolvePrecedenceFlagOverEnvOverConfig(t *testing.T) {
+	sandbox(t)
+	t.Setenv("HANZO_ORG", "env-org")
+	cfg := &Config{Org: "cfg-org", Output: "json"}
+	// Flag wins.
+	if e := resolve(cfg, &Credentials{}, globalFlags{org: "flag-org"}); e.Org != "flag-org" {
+		t.Fatalf("flag should win: %q", e.Org)
+	}
+	// Env beats config.
+	if e := resolve(cfg, &Credentials{}, globalFlags{}); e.Org != "env-org" {
+		t.Fatalf("env should beat config: %q", e.Org)
+	}
+	// Config used when no flag/env.
+	t.Setenv("HANZO_ORG", "")
+	if e := resolve(cfg, &Credentials{}, globalFlags{}); e.Org != "cfg-org" {
+		t.Fatalf("config should be used: %q", e.Org)
+	}
+}
+
+func TestPlatformTokenPrecedence(t *testing.T) {
+	sandbox(t)
+	e := resolve(&Config{}, &Credentials{PlatformToken: "from-creds"}, globalFlags{})
+	if got := e.platformToken(""); got != "from-creds" {
+		t.Fatalf("creds token: %q", got)
+	}
+	t.Setenv("PAAS_SERVICE_TOKEN", "from-paas")
+	if got := e.platformToken(""); got != "from-paas" {
+		t.Fatalf("PAAS env should beat creds: %q", got)
+	}
+	t.Setenv("PLATFORM_SERVICE_TOKEN", "from-platform")
+	if got := e.platformToken(""); got != "from-platform" {
+		t.Fatalf("PLATFORM env should beat PAAS: %q", got)
+	}
+	t.Setenv("HANZO_PLATFORM_TOKEN", "from-hanzo")
+	if got := e.platformToken(""); got != "from-hanzo" {
+		t.Fatalf("HANZO_PLATFORM_TOKEN should beat all envs: %q", got)
+	}
+	if got := e.platformToken("from-flag"); got != "from-flag" {
+		t.Fatalf("flag should beat everything: %q", got)
+	}
+}
+
+// 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{})
+	if got := e.buildToken(""); got != "creds" {
+		t.Fatalf("creds build token: %q", got)
+	}
+	t.Setenv("PLATFORM_BUILD_CALLBACK_TOKEN", "cb")
+	if got := e.buildToken(""); got != "cb" {
+		t.Fatalf("callback env: %q", got)
+	}
+	if got := e.buildToken("flag"); got != "flag" {
+		t.Fatalf("flag wins: %q", got)
+	}
+}
+
+// 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{})
+	if got := e.accessToken(); got != "creds" {
+		t.Fatalf("creds token: %q", got)
+	}
+	t.Setenv("HANZO_TOKEN", "env")
+	if got := e.accessToken(); got != "env" {
+		t.Fatalf("env token should win: %q", got)
+	}
+}
+
+func TestRequireOrg(t *testing.T) {
+	sandbox(t)
+	e := resolve(&Config{}, &Credentials{}, globalFlags{})
+	if _, err := e.requireOrg(); err == nil {
+		t.Fatalf("expected error when org unset")
+	}
+	e = resolve(&Config{Org: "acme"}, &Credentials{}, globalFlags{})
+	if org, err := e.requireOrg(); err != nil || org != "acme" {
+		t.Fatalf("org=%q err=%v", org, err)
+	}
+}
+
+func TestConfigFieldGetSet(t *testing.T) {
+	c := &Config{}
+	if err := c.setField("org", "acme"); err != nil || c.Org != "acme" {
+		t.Fatalf("set org: %v", err)
+	}
+	if v, _ := c.field("org"); v != "acme" {
+		t.Fatalf("get org: %q", v)
+	}
+	if err := c.setField("output", "xml"); err == nil {
+		t.Fatalf("invalid output should error")
+	}
+	if err := c.setField("nope", "x"); err == nil {
+		t.Fatalf("unknown key should error")
+	}
+	if _, err := c.field("nope"); err == nil {
+		t.Fatalf("unknown key get should error")
+	}
+}
+
+func TestIsControlVerb(t *testing.T) {
+	for _, v := range []string{"login", "apps", "deploy", "clusters", "build", "k8s", "config", "auth", "whoami", "logout"} {
+		if !IsControlVerb(v) {
+			t.Errorf("%q should be a control verb", v)
+		}
+	}
+	for _, v := range []string{"iam", "kms", "cloud", "gateway", "datastore", "nope"} {
+		if IsControlVerb(v) {
+			t.Errorf("%q must NOT be a control verb (server mode)", v)
+		}
+	}
+}
+
+func TestEmitJSONvsTable(t *testing.T) {
+	// JSON branch: encodes the value, ignores the table func.
+	var jbuf bytes.Buffer
+	ej := &Env{Output: "json", out: &jbuf}
+	called := false
+	if err := ej.emit(map[string]string{"k": "v"}, func(_ io.Writer) { called = true }); err != nil {
+		t.Fatalf("emit json: %v", err)
+	}
+	if called {
+		t.Fatalf("table func must not run in json mode")
+	}
+	var got map[string]string
+	if err := json.Unmarshal(jbuf.Bytes(), &got); err != nil || got["k"] != "v" {
+		t.Fatalf("json output bad: %q (%v)", jbuf.String(), err)
+	}
+
+	// Table branch: runs the table func, does not emit JSON.
+	var tbuf bytes.Buffer
+	et := &Env{Output: "table", out: &tbuf}
+	if err := et.emit(map[string]string{"k": "v"}, func(w io.Writer) { _, _ = w.Write([]byte("ROW")) }); err != nil {
+		t.Fatalf("emit table: %v", err)
+	}
+	if !strings.Contains(tbuf.String(), "ROW") {
+		t.Fatalf("table output missing: %q", tbuf.String())
+	}
+}

cli/code.go

@@ -0,0 +1,697 @@
+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 enso-pro
+//	hanzo code dev zen5            # ids are resolved fuzzily: zen5pro -> zen5-pro
+//	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 — deep reasoning (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, model 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
+}
+
+// codeContextWindow is the input context (tokens) the served coding model
+// budgets from. The enso and zen5 flagship tiers serve 1M; the flash tiers
+// serve 131072. Codex is told this so it sizes context to the real window
+// instead of a flat 256K cap — the cause of "maximum context exceeded" at
+// 262144 even on a 1M-capable model. This wrapper only launches Hanzo coding
+// models (default zen5), so non-flash defaults to the 1M flagship window.
+func codeContextWindow(model string) int {
+	if strings.Contains(strings.ToLower(model), "flash") {
+		return 131072
+	}
+	return 1000000
+}
+
+// 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, model string) []string {
+			// api.hanzo.ai exposes the standard OpenAI /v1/models shape, not
+			// Codex's private remote model-catalog schema, so skip that refresh
+			// and supply the model's window here — sized to the SERVED model
+			// (enso / zen5 flagship = 1M, flash tiers = 131072) so Codex budgets
+			// the real context instead of a flat 256K cap (the "maximum context
+			// exceeded at 262144" bug). Auto-compact at 90% leaves headroom.
+			win := codeContextWindow(model)
+			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"`,
+				"-c", `features.remote_models=false`,
+				"-c", fmt.Sprintf("model_context_window=%d", win),
+				"-c", fmt.Sprintf("model_auto_compact_token_limit=%d", win*9/10),
+			}
+		},
+		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" +
+			"(zen5pro -> zen5-pro), -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 enso-pro\n" +
+			"  hanzo code dev zen5 -- --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, model)...)
+	}
+	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,499 @@
+// 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) {
+	// defaultCodeModel is zen5 — a 1M flagship tier — so the window must be 1M,
+	// NOT the old flat 262144 cap that surfaced as "maximum context exceeded"
+	// even on a 1M-capable model. Auto-compact is 90% of the window.
+	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=1000000`,
+		`model_auto_compact_token_limit=900000`,
+	} {
+		if !slices.Contains(argv, want) {
+			t.Errorf("Codex argv %q does not contain %q", argv, want)
+		}
+	}
+	// A flash tier budgets its smaller real window, not 1M.
+	flash := codeArgv(codeAgents["codex"], "https://api.hanzo.ai", "zen5-flash", false, nil)
+	if !slices.Contains(flash, `model_context_window=131072`) {
+		t.Errorf("zen5-flash argv %q must budget 131072, not the flagship 1M", flash)
+	}
+}
+
+// TestCodeContextWindowSizing pins the model→window map: every non-flash tier
+// gets the 1M flagship window; only flash tiers drop to 131072.
+func TestCodeContextWindowSizing(t *testing.T) {
+	for _, m := range []string{"zen5", "zen5-pro", "zen5-coder", "enso", "enso-ultra"} {
+		if w := codeContextWindow(m); w != 1000000 {
+			t.Errorf("codeContextWindow(%q) = %d, want 1000000", m, w)
+		}
+	}
+	for _, m := range []string{"zen5-flash", "enso-flash"} {
+		if w := codeContextWindow(m); w != 131072 {
+			t.Errorf("codeContextWindow(%q) = %d, want 131072", m, w)
+		}
+	}
+}
+
+// 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

@@ -0,0 +1,331 @@
+package cli
+
+import (
+	"fmt"
+	"io"
+	"strings"
+	"text/tabwriter"
+
+	"github.com/spf13/cobra"
+)
+
+// platform builds a platform REST client from the resolved env + the global
+// --platform-token flag. The token may be empty here; the client surfaces a
+// precise error on first use.
+func (e *Env) platform(gf *globalFlags) *Platform {
+	return newPlatform(e.PlatformURL, e.platformToken(gf.platformToken))
+}
+
+// dashIfEmpty renders a string cell, "-" when empty.
+func dashIfEmpty(s string) string {
+	if s == "" {
+		return "-"
+	}
+	return s
+}
+
+// yesno renders a bool for a table cell.
+func yesno(b bool) string {
+	if b {
+		return "yes"
+	}
+	return "no"
+}
+
+// newTab returns a tabwriter writing to w with a 2-space gutter.
+func newTab(w io.Writer) *tabwriter.Writer {
+	return tabwriter.NewWriter(w, 0, 0, 2, ' ', 0)
+}
+
+// ---------------------------------------------------------------------------
+// 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 {
+	cmd := &cobra.Command{
+		Use:   "apps",
+		Short: "List/get the platform apps board (declared/running/latest/drift)",
+	}
+
+	var envFilter, healthFilter string
+	var driftOnly bool
+
+	list := &cobra.Command{
+		Use:   "list",
+		Short: "List apps with declared/running tags, health and drift",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			e := envOf()
+			res, err := e.platform(gf).Apps(cmd.Context(), AppsQuery{
+				Env:    envFilter,
+				Health: healthFilter,
+				Drift:  driftOnly,
+			})
+			if err != nil {
+				return err
+			}
+			return e.emit(res, func(w io.Writer) {
+				tw := newTab(w)
+				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, 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",
+					res.Summary.Total, res.Summary.ByDrift["ok"],
+					res.Summary.ByDrift["yellow"], res.Summary.ByDrift["red"])
+			})
+		},
+	}
+	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 <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])
+			if err != nil {
+				return err
+			}
+			return e.emit(a, func(w io.Writer) {
+				tw := newTab(w)
+				fmt.Fprintf(tw, "id:\t%s\n", a.ID)
+				fmt.Fprintf(tw, "org:\t%s\n", a.Org)
+				fmt.Fprintf(tw, "app:\t%s\n", a.App)
+				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", 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", 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()
+			})
+		},
+	}
+
+	cmd.AddCommand(list, get)
+	return cmd
+}
+
+// ---------------------------------------------------------------------------
+// deploy — POST /v1/paas/apps/{app}/deploy: a zero-downtime rolling restart.
+// ---------------------------------------------------------------------------
+
+func newDeployCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
+	var environment string
+	cmd := &cobra.Command{
+		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()
+			res, err := e.platform(gf).Redeploy(cmd.Context(), args[0], environment)
+			if err != nil {
+				return err
+			}
+			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(&environment, "env", "", "lifecycle env: main|test|dev (REQUIRED)")
+	return cmd
+}
+
+// ---------------------------------------------------------------------------
+// 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:   "List the org's clusters (managed + BYO)",
+	}
+
+	list := &cobra.Command{
+		Use:   "list",
+		Short: "List the org's clusters",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			e := envOf()
+			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\tKIND\tNODES\tSIZE\tGPUS")
+				for _, c := range cs {
+					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 clusters)")
+				}
+			})
+		},
+	}
+
+	get := &cobra.Command{
+		Use:   "get <cluster-id>",
+		Short: "Show one cluster",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			e := envOf()
+			cs, err := e.platform(gf).Clusters(cmd.Context())
+			if err != nil {
+				return err
+			}
+			for _, c := range cs {
+				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", args[0])
+		},
+	}
+
+	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", dashIfEmpty(c.ID()))
+	fmt.Fprintf(tw, "name:\t%s\n", c.Name)
+	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 build (runner fabric) enqueue.
+// ---------------------------------------------------------------------------
+
+func newBuildCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
+	var br BuildReq
+	var buildToken string
+	cmd := &cobra.Command{
+		Use:   "build <repo>",
+		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).",
+		Args: cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			e := envOf()
+			if len(args) == 1 {
+				br.Repo = args[0]
+			}
+			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
+			}
+			job, err := e.platform(gf).EnqueueBuild(cmd.Context(), br, e.buildToken(buildToken))
+			if err != nil {
+				return err
+			}
+			return e.emit(job, func(w io.Writer) {
+				tw := newTab(w)
+				fmt.Fprintf(tw, "buildJobId:\t%s\n", job.BuildJobID)
+				fmt.Fprintf(tw, "status:\t%s\n", job.Status)
+				fmt.Fprintf(tw, "runnerPool:\t%s\n", job.RunnerPool)
+				fmt.Fprintf(tw, "image:\t%s\n", job.Image)
+				fmt.Fprintf(tw, "target:\t%s\n", job.Target)
+				tw.Flush()
+			})
+		},
+	}
+	f := cmd.Flags()
+	f.StringVar(&br.Repo, "repo", "", "owner/name (e.g. hanzoai/pricing)")
+	f.StringVar(&br.SHA, "sha", "", "commit SHA to build")
+	f.StringVar(&br.Image, "image", "", "image to build+push (e.g. ghcr.io/hanzoai/pricing:<tag>)")
+	f.StringVar(&br.Branch, "branch", "", "branch (default main)")
+	f.StringVar(&br.Dockerfile, "dockerfile", "", "Dockerfile path")
+	f.StringVar(&br.Context, "context", "", "build context")
+	f.StringVar(&br.DockerTarget, "target", "", "Docker build stage (--target)")
+	f.StringVar(&br.OS, "os", "", "linux|darwin|windows (default linux)")
+	f.StringVar(&br.Arch, "arch", "", "amd64|arm64 (default amd64)")
+	f.StringVar(&buildToken, "build-token", "", "platform build-enqueue token (else env/credential store)")
+	return cmd
+}
+
+// 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
+	}
+	// Already a URL or scp-style remote → leave as-is.
+	if strings.Contains(r, "://") || strings.Contains(r, "@") {
+		return r
+	}
+	// 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

@@ -0,0 +1,248 @@
+package cli
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"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 {
+	t.Helper()
+	sandbox(t)
+	srv := httptest.NewServer(h)
+	t.Cleanup(srv.Close)
+	t.Setenv("HANZO_PLATFORM_URL", srv.URL)
+	t.Setenv("HANZO_PLATFORM_TOKEN", "svc-tok")
+	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, 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: "v1.2.3", RunningTag: "v1.2.3", Health: "green", Drift: json.RawMessage(`{"severity":"ok"}`)},
+			},
+			Summary: struct {
+				Total   int            `json:"total"`
+				ByDrift map[string]int `json:"byDrift"`
+			}{Total: 1, ByDrift: map[string]int{"ok": 1}},
+		})
+	})
+	out, err := runRoot(t, "", "apps", "list")
+	if err != nil {
+		t.Fatalf("apps list: %v", err)
+	}
+	for _, want := range []string{"APP", "iam", "v1.2.3", "green", "ok", "1 apps"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("apps list table missing %q in:\n%s", want, out)
+		}
+	}
+}
+
+// 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"}}})
+	})
+	out, err := runRoot(t, "", "apps", "list", "-o", "json")
+	if err != nil {
+		t.Fatalf("apps list json: %v", err)
+	}
+	var res AppsList
+	if err := json.Unmarshal([]byte(out), &res); err != nil {
+		t.Fatalf("output is not valid JSON: %v\n%s", err, out)
+	}
+	if len(res.Apps) != 1 || res.Apps[0].App != "iam" {
+		t.Fatalf("json decode wrong: %+v", res.Apps)
+	}
+}
+
+// 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/paas/apps/app-x/deploy" || r.URL.Query().Get("env") != "main" {
+			t.Errorf("redeploy request = %s?%s", r.URL.Path, r.URL.RawQuery)
+		}
+		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", "--env", "main")
+	if err != nil {
+		t.Fatalf("deploy: %v", err)
+	}
+	if !strings.Contains(out, "restarted app-x") || !strings.Contains(out, "namespace=hanzo") {
+		t.Fatalf("deploy output: %q", out)
+	}
+}
+
+// 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")
+	}
+}
+
+// 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/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", Kind: "managed", NodeCount: 3, NodeSize: "s-2vcpu-4gb", NvidiaGPU: 2},
+		}})
+	})
+	out, err := runRoot(t, "", "clusters", "list")
+	if err != nil {
+		t.Fatalf("clusters list: %v", err)
+	}
+	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)
+		}
+	}
+}
+
+// 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, "", "clusters", "get", "c1")
+	if err != nil {
+		t.Fatalf("clusters get: %v", err)
+	}
+	if !strings.Contains(out, "hanzo-acme") || !strings.Contains(out, "byo") {
+		t.Fatalf("clusters get output: %q", out)
+	}
+}
+
+func TestBuildCommandValidation(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(202) })
+	// Missing --sha/--image → validation error before any HTTP call.
+	if _, err := runRoot(t, "", "build", "hanzoai/pricing"); err == nil {
+		t.Fatalf("build must require --sha and --image")
+	}
+}
+
+func TestBuildCommand(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/runner" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		if got := r.Header.Get("Authorization"); got != "Bearer bt" {
+			t.Errorf("build auth = %q", got)
+		}
+		w.WriteHeader(202)
+		_ = json.NewEncoder(w).Encode(BuildJob{BuildJobID: "bj-9", Status: "queued", Image: "ghcr.io/hanzoai/pricing:t"})
+	})
+	out, err := runRoot(t, "", "build", "hanzoai/pricing", "--sha", "abc", "--image", "ghcr.io/hanzoai/pricing:t", "--build-token", "bt")
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+	if !strings.Contains(out, "bj-9") {
+		t.Fatalf("build output: %q", out)
+	}
+}
+
+func TestConfigSetGetCommand(t *testing.T) {
+	sandbox(t)
+	if _, err := runRoot(t, "", "config", "set", "org", "acme"); err != nil {
+		t.Fatalf("config set: %v", err)
+	}
+	out, err := runRoot(t, "", "config", "get", "org")
+	if err != nil {
+		t.Fatalf("config get: %v", err)
+	}
+	if strings.TrimSpace(out) != "acme" {
+		t.Fatalf("config get = %q", out)
+	}
+}

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 link --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_amd_test.go

@@ -0,0 +1,157 @@
+package cli
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// TestParseRocmSmiCSV — the AMD GPU inventory names a card from its marketing
+// series + gfx target, exactly as `rocm-smi --showproductname --csv` reports on
+// evo's gfx1151 Radeon 8060S. This is the primary AMD detection path.
+func TestParseRocmSmiCSV(t *testing.T) {
+	// Real evo output (header + one card row).
+	csv := []byte("device,Card Series,Card Model,Card Vendor,Card SKU,Subsystem ID,Device Rev,Node ID,GUID,GFX Version\n" +
+		"card0,Radeon 8060S Graphics,0x1586,Advanced Micro Devices Inc. [AMD/ATI],STRXLGEN,-0x7fe3,0xc1,1,49819,gfx1151\n")
+	gpus := parseRocmSmiCSV(csv)
+	if len(gpus) != 1 {
+		t.Fatalf("want 1 AMD GPU, got %d (%+v)", len(gpus), gpus)
+	}
+	if got, want := gpus[0].Name, "AMD Strix Halo \u00b7 Radeon 8060S Graphics (gfx1151)"; got != want {
+		t.Errorf("name = %q, want %q", got, want)
+	}
+}
+
+// TestGfxNameDecodesTargetVersion — the kfd fallback decodes gfx_target_version.
+func TestGfxNameDecodesTargetVersion(t *testing.T) {
+	for _, c := range []struct {
+		v    int
+		want string
+	}{
+		{110501, "gfx1151"}, // evo Radeon 8060S / Strix Halo
+		{90012, "gfx9012"},  // sanity: MI-class encoding shape
+		{100300, "gfx1030"}, // RDNA2
+	} {
+		if got := gfxName(c.v); got != c.want {
+			t.Errorf("gfxName(%d) = %q, want %q", c.v, got, c.want)
+		}
+	}
+}
+
+// TestParseKfdTopology — the driver-only fallback (no rocm-smi) still finds the GPU
+// from /sys/class/kfd: node 0 is the CPU (simd_count 0, skipped), node 1 is the
+// gfx1151 GPU. Built against a fixture tree mirroring evo's real properties files.
+func TestParseKfdTopology(t *testing.T) {
+	root := t.TempDir()
+	writeNode(t, root, "0", "simd_count 0\ngfx_target_version 0\n")
+	writeNode(t, root, "1", "cpu_cores_count 0\nsimd_count 80\ngfx_target_version 110501\n")
+	gpus := parseKfdTopology(root)
+	if len(gpus) != 1 {
+		t.Fatalf("want 1 GPU node (CPU node 0 skipped), got %d (%+v)", len(gpus), gpus)
+	}
+	if got, want := gpus[0].Name, "AMD Strix Halo (gfx1151)"; got != want {
+		t.Errorf("name = %q, want %q", got, want)
+	}
+	if got, want := gpus[0].Arch, "gfx1151"; got != want {
+		t.Errorf("arch = %q, want %q", got, want)
+	}
+}
+
+// TestParseVulkaninfoSummary — the last resort keeps only AMD/Radeon devices so it
+// never double-counts a card another vendor path already reported.
+func TestParseVulkaninfoSummary(t *testing.T) {
+	out := []byte("GPU0:\n\tdeviceName = AMD Radeon Graphics (RADV GFX1151)\n" +
+		"GPU1:\n\tdeviceName = llvmpipe (LLVM 18.1.0, 256 bits)\n")
+	gpus := parseVulkaninfoSummary(out)
+	if len(gpus) != 1 {
+		t.Fatalf("want 1 AMD device (llvmpipe filtered), got %d (%+v)", len(gpus), gpus)
+	}
+	if got := gpus[0].Name; got != "AMD Radeon Graphics (RADV GFX1151)" {
+		t.Errorf("name = %q", got)
+	}
+}
+
+func writeNode(t *testing.T, root, id, props string) {
+	t.Helper()
+	dir := filepath.Join(root, id)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "properties"), []byte(props), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// TestPickAmdMemUnified — an APU whose VRAM is a token carve-out reports the
+// machine's unified RAM snapped to hardware capacity (evo: 1 GiB VRAM, 118 GiB
+// GTT, 124.4 GiB kernel-visible of 128 GiB physical → 128 GiB); a discrete card
+// keeps its VRAM.
+func TestPickAmdMemUnified(t *testing.T) {
+	if miB, unified := pickAmdMem(1024, 120832, 127411); !unified || miB != 131072 {
+		t.Errorf("APU: got (%d, %v), want (131072, true)", miB, unified)
+	}
+	if miB, unified := pickAmdMem(24576, 8192, 127411); unified || miB != 24576 {
+		t.Errorf("discrete: got (%d, %v), want (24576, false)", miB, unified)
+	}
+}
+
+// TestSnapUnified — a small firmware gap snaps up to the DIMM capacity; a big
+// carve-out is real lost capacity and stays as-is; exact multiples stand.
+func TestSnapUnified(t *testing.T) {
+	for _, c := range []struct{ in, want int64 }{
+		{127411, 131072}, // evo: 124.4 GiB visible of 128 GiB physical
+		{124610, 131072}, // spark GB10: 121.7 GiB visible of 128 GiB physical (~6.3 GiB firmware)
+		{131072, 131072}, // exact 128 GiB
+		{119194, 119194}, // ~116 GiB visible (16 GiB BIOS carve) — 11.6 GiB gap, keep honest
+		{63488, 65536},   // 62 GiB visible of 64 GiB
+	} {
+		if got := snapUnified(c.in); got != c.want {
+			t.Errorf("snapUnified(%d) = %d, want %d", c.in, got, c.want)
+		}
+	}
+}
+
+// TestAmdAPUName — the board renders the APU as the processor the owner bought,
+// normalized from the BIOS shouting; non-Ryzen hosts opt out.
+func TestAmdAPUName(t *testing.T) {
+	if got, want := amdAPUName("AMD RYZEN AI MAX+ 395 w/ Radeon 8060S"), "AMD Ryzen AI Max+ 395 w/ Radeon 8060S"; got != want {
+		t.Errorf("amdAPUName = %q, want %q", got, want)
+	}
+	if got := amdAPUName("Intel(R) Core(TM) i9-14900K"); got != "" {
+		t.Errorf("non-Ryzen host must opt out, got %q", got)
+	}
+}
+
+// TestApuProcessorNames — only unified-memory cards are renamed; a discrete
+// card on the same host keeps its own identity.
+func TestApuProcessorNames(t *testing.T) {
+	gpus := []gpuInfo{
+		{Name: "AMD Strix Halo \u00b7 Radeon 8060S Graphics (gfx1151)", Arch: "gfx1151", Unified: true},
+		{Name: "Radeon RX 7900 XTX (gfx1100)", Arch: "gfx1100"},
+	}
+	out := apuProcessorNames(gpus, "AMD RYZEN AI MAX+ 395 w/ Radeon 8060S")
+	if got, want := out[0].Name, "AMD Ryzen AI Max+ 395 w/ Radeon 8060S (gfx1151)"; got != want {
+		t.Errorf("APU name = %q, want %q", got, want)
+	}
+	if got, want := out[1].Name, "Radeon RX 7900 XTX (gfx1100)"; got != want {
+		t.Errorf("discrete name = %q, want %q", got, want)
+	}
+}
+
+// TestParseNvidiaSmiCSV — a GB10-class unified SoC ("[N/A]" VRAM) reports the
+// machine RAM snapped to capacity + its sm arch; a discrete card keeps its VRAM.
+func TestParseNvidiaSmiCSV(t *testing.T) {
+	out := []byte("NVIDIA GB10, [N/A], 12.1\n")
+	gpus := parseNvidiaSmiCSV(out, 124610)
+	if len(gpus) != 1 {
+		t.Fatalf("want 1 GPU, got %d", len(gpus))
+	}
+	g := gpus[0]
+	if g.Name != "NVIDIA GB10" || g.MemoryTotal != "131072 MiB" || !g.Unified || g.Arch != "sm_121" {
+		t.Errorf("GB10 = %+v", g)
+	}
+	disc := parseNvidiaSmiCSV([]byte("NVIDIA GeForce RTX 4090, 24564 MiB, 8.9\n"), 124610)
+	if d := disc[0]; d.MemoryTotal != "24564 MiB" || d.Unified || d.Arch != "sm_89" {
+		t.Errorf("discrete = %+v", d)
+	}
+}

cli/gpu_engine_test.go

@@ -0,0 +1,248 @@
+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,
+		studioReady:  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, studioReady: true}
+	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_fnrun_test.go

@@ -0,0 +1,75 @@
+package cli
+
+import (
+	"encoding/json"
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+// TestFnValidate — payload bounds: script required, flag-injection via
+// requirements refused, timeout defaulted and capped.
+func TestFnValidate(t *testing.T) {
+	if _, err := fnValidate(json.RawMessage(`{}`)); err == nil {
+		t.Error("empty script must be refused")
+	}
+	if _, err := fnValidate(json.RawMessage(`{"script":"print(1)","requirements":["--index-url=evil"]}`)); err == nil {
+		t.Error("flag-shaped requirement must be refused")
+	}
+	in, err := fnValidate(json.RawMessage(`{"script":"print(1)"}`))
+	if err != nil || in.TimeoutSeconds != 3600 {
+		t.Errorf("default timeout: got %d, err %v", in.TimeoutSeconds, err)
+	}
+	in, _ = fnValidate(json.RawMessage(`{"script":"print(1)","timeoutSeconds":999999}`))
+	if in.TimeoutSeconds != 21600 {
+		t.Errorf("timeout cap: got %d, want 21600", in.TimeoutSeconds)
+	}
+}
+
+// TestTailBuffer — a chatty training loop keeps only the LAST bytes, flagged.
+func TestTailBuffer(t *testing.T) {
+	tb := &tailBuffer{cap: 8}
+	tb.Write([]byte("0123456789"))
+	if string(tb.buf) != "23456789" || !tb.truncated {
+		t.Errorf("tail = %q truncated=%v", tb.buf, tb.truncated)
+	}
+	tb2 := &tailBuffer{cap: 8}
+	tb2.Write([]byte("abc"))
+	if string(tb2.buf) != "abc" || tb2.truncated {
+		t.Errorf("small write mangled: %q %v", tb2.buf, tb2.truncated)
+	}
+}
+
+// TestHasNonRenderLane — echo and studio.render alone keep the render-only
+// poison guard; a registered fn.run lane lifts it.
+func TestHasNonRenderLane(t *testing.T) {
+	w := &worker{handlers: map[string]jobHandler{"echo": echoHandler, studioCap: nil}}
+	if w.hasNonRenderLane() {
+		t.Error("render-only worker must report no extra lane")
+	}
+	w.handlers[fnCap] = fnRunHandler
+	if !w.hasNonRenderLane() {
+		t.Error("fn.run lane must lift the guard")
+	}
+}
+
+// TestFnRunSmoke — the real handler end-to-end against the local uv: a script
+// that prints and exits 0. Skipped where uv is absent.
+func TestFnRunSmoke(t *testing.T) {
+	if !uvPresent() {
+		t.Skip("uv not installed")
+	}
+	res, err := fnRunHandler(t.Context(), json.RawMessage(`{"script":"print(2+2)","timeoutSeconds":120}`))
+	if err != nil {
+		t.Fatalf("fn.run: %v", err)
+	}
+	m := res.(map[string]any)
+	if !strings.Contains(m["output"].(string), "4") {
+		t.Errorf("output = %q, want it to contain 4", m["output"])
+	}
+}
+
+func uvPresent() bool {
+	_, err := exec.LookPath("uv")
+	return err == nil
+}

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_queue_test.go

@@ -0,0 +1,291 @@
+package cli
+
+// gpu_queue_test.go — the per-GPU claim contract: a job pinned to THIS machine's
+// lane ("gpu:<identity>") is claimed BEFORE the shared any-GPU lane ("gpu-jobs"),
+// both within the gpu-jobs namespace. A stub cloud records the taskQueue of every
+// claim so the ORDER is the assertion.
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+// stubJobsCloud records the taskQueue of every claim and serves the queued job (if
+// any) on the matching lane, once. A lane with no job (or already drained) answers
+// 204; complete/fail/heartbeat answer 200.
+func stubJobsCloud(t *testing.T, claims *[]string, jobsByLane map[string]*claimedActivity) *httptest.Server {
+	t.Helper()
+	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodPost && strings.HasSuffix(r.URL.Path, "/activities/claim") {
+			var body struct {
+				TaskQueue string `json:"taskQueue"`
+			}
+			_ = json.NewDecoder(r.Body).Decode(&body)
+			*claims = append(*claims, body.TaskQueue)
+			if job := jobsByLane[body.TaskQueue]; job != nil {
+				jobsByLane[body.TaskQueue] = nil // deliver once
+				_ = json.NewEncoder(w).Encode(job)
+				return
+			}
+			w.WriteHeader(http.StatusNoContent)
+			return
+		}
+		w.WriteHeader(http.StatusOK) // complete / fail / heartbeat
+	}))
+}
+
+// echoJob is a GPU-free job the worker's echo handler runs to completion instantly,
+// so a claim test never needs a real render backend.
+func echoJob(id string) *claimedActivity {
+	a := &claimedActivity{Input: json.RawMessage(`{}`)}
+	a.Execution.WorkflowId, a.Execution.RunId = id, id
+	a.Type.Name = "echo"
+	return a
+}
+
+func testWorker(t *testing.T, url string) *worker {
+	t.Helper()
+	t.Setenv("HANZO_TOKEN", "test-token") // ensureToken honors this; no `hanzo login`
+	return &worker{
+		env:         &Env{CloudURL: url},
+		http:        &http.Client{Timeout: 5 * time.Second},
+		baseURL:     url,
+		identity:    "spark",
+		hostname:    "spark",
+		jobsNS:      "gpu-jobs",
+		handlers:    map[string]jobHandler{"echo": echoHandler},
+		studioReady: true, // a render-capable node (preflight passed)
+	}
+}
+
+func TestGPUQueueLaneName(t *testing.T) {
+	w := &worker{identity: "spark"}
+	if got := w.gpuQueue(); got != "gpu:spark" {
+		t.Fatalf("gpuQueue() = %q, want gpu:spark", got)
+	}
+}
+
+// A job pinned to THIS GPU's lane is claimed first — the shared lane is not even
+// polled that cycle.
+func TestClaimPrefersTargetedLane(t *testing.T) {
+	var claims []string
+	srv := stubJobsCloud(t, &claims, map[string]*claimedActivity{"gpu:spark": echoJob("j1")})
+	defer srv.Close()
+	if err := testWorker(t, srv.URL).claimAndRun(context.Background(), io.Discard); err != nil {
+		t.Fatalf("claimAndRun: %v", err)
+	}
+	if len(claims) != 1 || claims[0] != "gpu:spark" {
+		t.Fatalf("claims = %v, want exactly [gpu:spark] (targeted first; shared not polled)", claims)
+	}
+}
+
+// With its own lane empty, the worker falls through to the shared any-GPU lane.
+func TestClaimFallsBackToSharedLane(t *testing.T) {
+	var claims []string
+	srv := stubJobsCloud(t, &claims, map[string]*claimedActivity{"gpu-jobs": echoJob("j2")})
+	defer srv.Close()
+	if err := testWorker(t, srv.URL).claimAndRun(context.Background(), io.Discard); err != nil {
+		t.Fatalf("claimAndRun: %v", err)
+	}
+	if len(claims) != 2 || claims[0] != "gpu:spark" || claims[1] != "gpu-jobs" {
+		t.Fatalf("claims = %v, want [gpu:spark gpu-jobs] (targeted, then shared)", claims)
+	}
+}
+
+// Both lanes empty polls targeted THEN shared and runs nothing.
+func TestClaimBothLanesEmpty(t *testing.T) {
+	var claims []string
+	srv := stubJobsCloud(t, &claims, map[string]*claimedActivity{})
+	defer srv.Close()
+	if err := testWorker(t, srv.URL).claimAndRun(context.Background(), io.Discard); err != nil {
+		t.Fatalf("claimAndRun: %v", err)
+	}
+	if len(claims) != 2 || claims[0] != "gpu:spark" || claims[1] != "gpu-jobs" {
+		t.Fatalf("claims = %v, want [gpu:spark gpu-jobs]", claims)
+	}
+}
+
+// The render submit seam is the gated worker-mode execute path, not the open /prompt
+// — the shared contract with the studio's --worker-mode gate.
+func TestWorkerExecuteSeamIsGated(t *testing.T) {
+	if localWorkerExecute != "http://127.0.0.1:8188/v1/worker/execute" {
+		t.Fatalf("localWorkerExecute = %q, want the gated /v1/worker/execute seam", localWorkerExecute)
+	}
+}
+
+// A HUNG nvidia-smi (blocks until its bounded context fires) must NOT block the
+// caller: reportSample detaches the probe+POST onto a goroutine and returns at once,
+// so the worker's select loop keeps heartbeating and claiming. Guards the
+// worker-wedge regression (a synchronous probe that stalls the loop under GPU/driver
+// pressure → the machine flaps offline mid-render).
+func TestReportSampleNeverBlocksLoop(t *testing.T) {
+	orig := nvidiaSmi
+	defer func() { nvidiaSmi = orig }()
+	probing := make(chan struct{})
+	release := make(chan struct{})
+	nvidiaSmi = func(ctx context.Context) ([]byte, error) {
+		close(probing) // entered the probe (the nvidiaSmi var read already happened)
+		select {
+		case <-release: // the test lets us finish
+		case <-ctx.Done(): // or the bounded probe timeout fires
+		}
+		return nil, ctx.Err()
+	}
+	t.Setenv("HANZO_TOKEN", "t")
+	w := &worker{identity: "spark", hostname: "spark", http: &http.Client{Timeout: time.Second}, env: &Env{}, baseURL: "http://127.0.0.1:0"}
+
+	done := make(chan struct{})
+	go func() { w.reportSample(context.Background()); close(done) }()
+	select {
+	case <-done: // returned immediately — the select loop is never wedged
+	case <-time.After(500 * time.Millisecond):
+		t.Fatal("reportSample blocked the caller — a hung sampler would wedge the worker loop")
+	}
+	select {
+	case <-probing: // the probe really ran, on the detached goroutine (off the critical path)
+	case <-time.After(2 * time.Second):
+		t.Fatal("probe never started")
+	}
+	close(release)
+}
+
+// A node that can't serve renders (preflight failed) claims NOTHING — it must never
+// pull a render job onto a box that will only refuse it on the gated seam (poison
+// loop). It still heartbeats presence; it just stays idle.
+func TestNotStudioReadyClaimsNothing(t *testing.T) {
+	var claims []string
+	srv := stubJobsCloud(t, &claims, map[string]*claimedActivity{"gpu:spark": echoJob("j1")})
+	defer srv.Close()
+	w := testWorker(t, srv.URL)
+	w.studioReady = false
+	if err := w.claimAndRun(context.Background(), io.Discard); err != nil {
+		t.Fatalf("claimAndRun: %v", err)
+	}
+	if len(claims) != 0 {
+		t.Fatalf("a not-ready node claimed %v; want zero claims", claims)
+	}
+}
+
+// The terminal report must hit the RIGHT activity — namespace gpu-jobs, the CLAIMED
+// workflow+run ids, the correct verb. A stub that 200s every path lets an ns/id
+// routing regression pass, so assert the exact paths for both complete and fail.
+func TestTerminalReportsHitCorrectActivityPath(t *testing.T) {
+	t.Setenv("HANZO_TOKEN", "t")
+	var mu sync.Mutex
+	terminal := map[string]string{}
+	served := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case strings.HasSuffix(r.URL.Path, "/activities/claim"):
+			var body struct {
+				TaskQueue string `json:"taskQueue"`
+			}
+			_ = json.NewDecoder(r.Body).Decode(&body)
+			if body.TaskQueue != "gpu:spark" {
+				w.WriteHeader(http.StatusNoContent)
+				return
+			}
+			mu.Lock()
+			n := served
+			served++
+			mu.Unlock()
+			switch n {
+			case 0:
+				_ = json.NewEncoder(w).Encode(echoJob("wf1")) // echo handler → complete
+			case 1:
+				j := echoJob("wf2")
+				j.Type.Name = "nope" // no handler → fail
+				_ = json.NewEncoder(w).Encode(j)
+			default:
+				w.WriteHeader(http.StatusNoContent)
+			}
+		case strings.HasSuffix(r.URL.Path, "/complete"):
+			mu.Lock()
+			terminal["complete"] = r.URL.Path
+			mu.Unlock()
+			w.WriteHeader(http.StatusOK)
+		case strings.HasSuffix(r.URL.Path, "/fail"):
+			mu.Lock()
+			terminal["fail"] = r.URL.Path
+			mu.Unlock()
+			w.WriteHeader(http.StatusOK)
+		default:
+			w.WriteHeader(http.StatusOK)
+		}
+	}))
+	defer srv.Close()
+	w := testWorker(t, srv.URL)
+	if err := w.claimAndRun(context.Background(), io.Discard); err != nil {
+		t.Fatalf("run1 (echo→complete): %v", err)
+	}
+	if err := w.claimAndRun(context.Background(), io.Discard); err != nil {
+		t.Fatalf("run2 (unknown→fail): %v", err)
+	}
+	if got := terminal["complete"]; got != "/v1/tasks/namespaces/gpu-jobs/activities/wf1/wf1/complete" {
+		t.Fatalf("complete path = %q, want the claimed activity's exact ns+ids", got)
+	}
+	if got := terminal["fail"]; got != "/v1/tasks/namespaces/gpu-jobs/activities/wf2/wf2/fail" {
+		t.Fatalf("fail path = %q, want the claimed activity's exact ns+ids", got)
+	}
+}
+
+// SharePolicy.reject's fallback: an ABSENT or unparseable input field skips its gate
+// (permissive), never a hard error, so a policy only ever narrows on fields it can read.
+func TestSharePolicyRejectFallback(t *testing.T) {
+	var nilp *SharePolicy
+	if r := nilp.reject("studio.render", nil); r != "" {
+		t.Fatalf("nil policy must allow everything: %q", r)
+	}
+	p := &SharePolicy{AllowedJobTypes: []string{"studio.render"}}
+	if p.reject("echo", nil) == "" {
+		t.Fatal("a disallowed job type must be rejected")
+	}
+	if r := p.reject("studio.render", nil); r != "" {
+		t.Fatalf("an allowed job type must pass: %q", r)
+	}
+	p2 := &SharePolicy{AllowedOrgs: []string{"acme"}}
+	if r := p2.reject("studio.render", json.RawMessage(`{}`)); r != "" {
+		t.Fatalf("absent org must SKIP the org gate (fallback), not reject: %q", r)
+	}
+	if r := p2.reject("studio.render", json.RawMessage(`{"org":"acme"}`)); r != "" {
+		t.Fatalf("a matching org must pass: %q", r)
+	}
+	if p2.reject("studio.render", json.RawMessage(`{"org":"other"}`)) == "" {
+		t.Fatal("a non-allowed org must be rejected")
+	}
+	if r := p2.reject("studio.render", json.RawMessage(`not json`)); r != "" {
+		t.Fatalf("unparseable input must skip input gates, not reject: %q", r)
+	}
+}
+
+// studioCap is advertised ONLY when the node can actually render: a missing worker
+// token is never ready (the gated seam would 403), and the block reason is explicit.
+func TestStudioReadyGatesCapability(t *testing.T) {
+	t.Setenv("STUDIO_WORKER_TOKEN", "")
+	w := &worker{launchesStudio: true, http: &http.Client{}}
+	w.refreshStudioReady(context.Background())
+	if w.studioReady {
+		t.Fatal("no token must never be studio-ready")
+	}
+	if contains(w.capabilities(), studioCap) {
+		t.Fatalf("studioCap advertised without a token: %v", w.capabilities())
+	}
+	if w.studioBlockReason() == "" {
+		t.Fatal("a not-ready node must explain why it won't render")
+	}
+	// Token present + we launch the studio ⇒ ready ⇒ studioCap advertised.
+	t.Setenv("STUDIO_WORKER_TOKEN", "tok")
+	if changed := w.refreshStudioReady(context.Background()); !changed {
+		t.Fatal("adding the token should flip readiness")
+	}
+	if !w.studioReady || !contains(w.capabilities(), studioCap) {
+		t.Fatalf("token + launchesStudio must be ready + advertise studioCap: ready=%v caps=%v", w.studioReady, w.capabilities())
+	}
+}

cli/gpu_spec_test.go

@@ -0,0 +1,88 @@
+package cli
+
+// gpu_spec_test.go — the host static-spec a `hanzo link` node reports so
+// GET /v1/fleet can show its CPU arch, core count and total RAM (the fields a
+// code-linked box already carries). Real telemetry only: arch is `uname -m`, cores
+// are runtime.NumCPU, RAM is parsed from the OS — never a hardcoded machine.
+
+import (
+	"os/exec"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+func TestParseMemTotalKB(t *testing.T) {
+	// A real /proc/meminfo head from a 128 GiB box. MemTotal is in kB; we report bytes.
+	meminfo := []byte("MemTotal:       131923980 kB\nMemFree:         1048576 kB\nMemAvailable:  120000000 kB\n")
+	if got, want := parseMemTotalKB(meminfo), int64(131923980)*1024; got != want {
+		t.Fatalf("parseMemTotalKB = %d, want %d bytes", got, want)
+	}
+	// Absent / malformed input is reported as 0 (unknown), never a guess.
+	for name, in := range map[string]string{
+		"empty":       "",
+		"no-memtotal": "MemFree: 100 kB\n",
+		"malformed":   "MemTotal: notanumber kB\n",
+		"no-value":    "MemTotal:\n",
+	} {
+		if got := parseMemTotalKB([]byte(in)); got != 0 {
+			t.Fatalf("%s: parseMemTotalKB = %d, want 0", name, got)
+		}
+	}
+}
+
+// detectMemTotal reads the real host, so on Linux/macOS CI it must return a positive
+// byte count — proof the reporter reads actual RAM rather than shipping 0.
+func TestDetectMemTotalIsReal(t *testing.T) {
+	if runtime.GOOS != "linux" && runtime.GOOS != "darwin" {
+		t.Skipf("no MemTotal source on %s", runtime.GOOS)
+	}
+	got := detectMemTotal()
+	if got <= 0 {
+		t.Fatalf("detectMemTotal = %d, want the host's real RAM (>0)", got)
+	}
+	// Evidence: what THIS host actually reports (never hardcoded). On the GB10 spark
+	// box this prints aarch64 + ~128 GiB read from /proc/meminfo.
+	t.Logf("real host spec: arch=%s cpus=%d memory=%d bytes (%.1f GiB)",
+		detectArch(), runtime.NumCPU(), got, float64(got)/(1<<30))
+}
+
+// detectArch must match the fleet's `uname -m` convention (aarch64 | x86_64 | arm64),
+// NOT runtime.GOARCH (arm64 | amd64) — so a machine that appears as both a run-target
+// and a linked worker shows ONE arch string on the board. On Linux uname -m is
+// aarch64/x86_64; assert the real host agrees and is never GOARCH's amd64.
+func TestDetectArchMatchesUnameConvention(t *testing.T) {
+	got := detectArch()
+	if got == "" {
+		t.Fatal("detectArch returned empty; must fall back to runtime.GOARCH")
+	}
+	if out, err := exec.Command("uname", "-m").Output(); err == nil {
+		if want := strings.TrimSpace(string(out)); want != "" && got != want {
+			t.Fatalf("detectArch = %q, want `uname -m` %q (fleet convention)", got, want)
+		}
+	}
+	// Guard the regression this test exists for: on Linux amd64 the value must be
+	// x86_64, never GOARCH's "amd64".
+	if runtime.GOOS == "linux" && runtime.GOARCH == "amd64" && got == "amd64" {
+		t.Fatal("arch is GOARCH 'amd64'; the fleet convention is 'x86_64'")
+	}
+	t.Logf("detectArch=%q (GOARCH=%q)", got, runtime.GOARCH)
+}
+
+// buildRegistration must carry this host's detected arch (uname -m), cores (NumCPU)
+// and RAM — so spark reports aarch64 and evo-2 reports x86_64, both ~128 GB, matching
+// how the same machines already report as code-linked run-targets.
+func TestBuildRegistrationCarriesHostSpec(t *testing.T) {
+	const mem = int64(137438953472) // 128 GiB
+	w := &worker{hostname: "spark", jobsNS: "gpu-jobs", arch: "aarch64", memory: mem}
+	reg := w.buildRegistration()
+	if reg.Arch != "aarch64" {
+		t.Fatalf("Arch = %q, want the worker's detected arch %q", reg.Arch, "aarch64")
+	}
+	if reg.CPUs != runtime.NumCPU() {
+		t.Fatalf("CPUs = %d, want runtime.NumCPU %d", reg.CPUs, runtime.NumCPU())
+	}
+	if reg.Memory != mem {
+		t.Fatalf("Memory = %d, want the detected total %d", reg.Memory, mem)
+	}
+}

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

@@ -0,0 +1,200 @@
+package cli
+
+// link.go — `hanzo link | unlink | status`: bring THIS machine into the Hanzo
+// cloud fleet AS A NODE, take it back out, and view the fleet.
+//
+// A node is two orthogonal memberships, composed under one verb:
+//
+//  1. The FABRIC — hanzod on hanzo.network. `link` starts it by invoking the
+//     canonical fabric verb `hanzo node up` (the Rust node CLI: resolve a hanzod
+//     binary, spawn it detached, record its pid). link does NOT reimplement hanzod
+//     supervision — there is exactly one way to start hanzod, and this composes it.
+//     Best-effort: a node with no hanzod still joins the compute fleet (CPU-only
+//     boxes and dev machines link fine); `--no-fabric` skips it outright.
+//
+//  2. The COMPUTE fleet — this machine's inventory (CPU cores + model, memory, and
+//     each GPU as its own resource) registered as a heartbeating presence in the
+//     org's `fleet` namespace, running the outbound worker loop that claims jobs
+//     from `gpu-jobs`. That machinery lives in gpu.go (runConnect); `link` runs it.
+//
+// `unlink` reverses both: it deregisters the worker (drops the fleet row), then
+// stops the fabric (`hanzo node stop`). `status` is the fleet view — every machine
+// with each of its GPUs shown distinctly, this box highlighted.
+//
+// One identity: the IAM token `hanzo login` mints authorizes every cloud call; the
+// server derives the tenant from the token. No secrets on the box.
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+// ---------------------------------------------------------------------------
+// link / unlink / status — the node-level command surface.
+// ---------------------------------------------------------------------------
+
+func newLinkCmd(envOf func() *Env, _ *globalFlags) *cobra.Command {
+	var opts connectOpts
+	var daemon bool
+	var noFabric bool
+
+	cmd := &cobra.Command{
+		Use:   "link",
+		Short: "Bring this machine into the Hanzo cloud fleet as a node",
+		Long: "Link this machine into the Hanzo cloud as a node: join the fabric (start\n" +
+			"hanzod on hanzo.network) and register as a compute worker — advertising this\n" +
+			"host's CPU (cores + model), memory, and each GPU as its own resource, then\n" +
+			"heartbeating and claiming jobs from your org's queue. The node shows up in the\n" +
+			"console (Machines + GPUs) and on `hanzo status`. Works on a CPU-only box.\n" +
+			"Authentication reuses the `hanzo login` token; the org is taken from its claims.",
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			if daemon {
+				return installDaemon(cmd, opts)
+			}
+			// 1. Fabric: start hanzod via the canonical `hanzo node up` (best-effort).
+			startFabric(cmd, noFabric)
+			// 2. Compute fleet: register inventory, heartbeat, claim jobs (foreground).
+			return runConnect(cmd, envOf(), opts)
+		},
+	}
+
+	f := cmd.Flags()
+	f.StringVar(&opts.jobsNS, "jobs-namespace", defaultJobsNS, "tasks namespace to claim jobs from")
+	f.BoolVar(&noFabric, "no-fabric", false, "join the compute fleet only; do not start hanzod")
+	f.BoolVar(&daemon, "daemon", false, "install a systemd --user unit (Restart=always) instead of running in the foreground")
+	f.BoolVar(&opts.serveEngine, "serve-engine", false, "also advertise a hanzo-engine model server (OpenAI + Anthropic) running on this node")
+	f.StringVar(&opts.engineURL, "engine-url", defaultEngineURL, "local URL where hanzo-engine is probed (GET /v1/models)")
+	f.StringVar(&opts.engineEndpoint, "engine-endpoint", "", "public URL to advertise for gateway routing (defaults to --engine-url; a node behind NAT needs a reachable URL/tunnel)")
+	f.BoolVar(&opts.registerProvider, "register-provider", false, "auto-register the engine endpoint as an org model provider (POST /v1/ai/providers)")
+	f.StringVar(&opts.studioDir, "studio-dir", os.Getenv("HANZO_STUDIO_DIR"), "local Hanzo Studio checkout; when set, link launches and supervises the render backend on 127.0.0.1:8188")
+	f.StringVar(&opts.studioURL, "studio-url", firstNonEmpty(os.Getenv("HANZO_STUDIO_UPLOAD_URL"), defaultStudioUploadURL), "studio base URL the render mirror uploads finished images to (POST /v1/library/upload)")
+	f.BoolVar(&opts.mirror, "mirror", true, "sweep local renders into the org studio library; --mirror=false serves jobs only")
+	return cmd
+}
+
+func newUnlinkCmd(envOf func() *Env, _ *globalFlags) *cobra.Command {
+	return &cobra.Command{
+		Use:   "unlink",
+		Short: "Take this machine out of the fleet (deregister + stop hanzod)",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			// Reverse of link, both best-effort: drop the compute-fleet row, then
+			// ALWAYS stop the fabric so a deregister error never leaves hanzod
+			// running. The deregister error is reported, not short-circuited.
+			derr := runDisconnect(cmd, envOf())
+			stopFabric(cmd)
+			return derr
+		},
+	}
+}
+
+func newStatusCmd(envOf func() *Env, _ *globalFlags) *cobra.Command {
+	return &cobra.Command{
+		Use:   "status",
+		Short: "Show the org's fleet — every machine with each of its GPUs (this box highlighted)",
+		Args:  cobra.NoArgs,
+		RunE:  func(cmd *cobra.Command, _ []string) error { return runFleetStatus(cmd, envOf()) },
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Fabric — compose the canonical `hanzo node up` / `node stop`.
+// ---------------------------------------------------------------------------
+
+// fabricCLI resolves the Hanzo node CLI that owns hanzod supervision — the Rust
+// fabric/dev CLI with `node up/stop`. In the canonical layout the Go unified binary
+// takes the `hanzo` name and the Rust CLI is installed alongside it as `hanzo-node`,
+// so `link` composes `node up` without shelling into itself (this binary has no
+// `node`). Resolution order: HANZO_FABRIC_CLI, then `hanzo-node`, then a
+// self-guarded `hanzo` (for boxes where the Rust CLI still holds the `hanzo` name).
+// Returns "" when none is resolvable.
+func fabricCLI() string {
+	if p := os.Getenv("HANZO_FABRIC_CLI"); p != "" {
+		return p
+	}
+	if p, err := exec.LookPath("hanzo-node"); err == nil {
+		return p
+	}
+	p, err := exec.LookPath("hanzo")
+	if err != nil {
+		return ""
+	}
+	if self, err := os.Executable(); err == nil {
+		if sp, _ := os.Readlink(p); sp == self || p == self {
+			return ""
+		}
+	}
+	return p
+}
+
+// Passthrough delegates a verb this binary does not own — node, dev, wallet,
+// network, … — to the Rust fabric/dev CLI (resolved by fabricCLI, installed as
+// `hanzo-node`), so the single `hanzo` name is a SUPERSET: Go verbs served natively,
+// everything else handed through unchanged. `hanzo node up` (the fabric `link`
+// itself composes) works for users too. It runs the delegate to completion with
+// inherited stdio and exits with its code; it returns false only when no fabric CLI
+// is resolvable, so the caller can report unknown-subcommand.
+func Passthrough(args []string) bool {
+	bin := fabricCLI()
+	if bin == "" {
+		return false
+	}
+	c := exec.Command(bin, args...)
+	c.Stdin, c.Stdout, c.Stderr = os.Stdin, os.Stdout, os.Stderr
+	if err := c.Run(); err != nil {
+		var ee *exec.ExitError
+		if errors.As(err, &ee) {
+			os.Exit(ee.ExitCode())
+		}
+		fmt.Fprintf(os.Stderr, "hanzo: delegating %v to %s: %v\n", args, bin, err)
+		os.Exit(1)
+	}
+	os.Exit(0)
+	return true
+}
+
+// startFabric starts hanzod by invoking `hanzo node up` — the one canonical way to
+// join the fabric. Best-effort by design: a missing CLI or a missing hanzod prints
+// a clear note and the node still joins the compute fleet. `--no-fabric` skips it.
+func startFabric(cmd *cobra.Command, skip bool) {
+	out := cmd.OutOrStdout()
+	if skip {
+		fmt.Fprintln(out, "fabric: skipped (--no-fabric); joining the compute fleet only")
+		return
+	}
+	bin := fabricCLI()
+	if bin == "" {
+		fmt.Fprintln(out, "fabric: hanzo node CLI not found — joining the compute fleet only")
+		fmt.Fprintln(out, "        (install the `hanzo` node CLI or set HANZO_FABRIC_CLI to start hanzod)")
+		return
+	}
+	ctx, cancel := context.WithTimeout(cmd.Context(), 60*time.Second)
+	defer cancel()
+	c := exec.CommandContext(ctx, bin, "node", "up")
+	c.Stdout, c.Stderr = out, cmd.ErrOrStderr()
+	if err := c.Run(); err != nil {
+		fmt.Fprintf(out, "fabric: `%s node up` did not start hanzod (%v) — joining the compute fleet only\n", bin, err)
+	}
+}
+
+// stopFabric stops the hanzod this box started, via the canonical `hanzo node stop`.
+// Best-effort — nothing to stop is not an error.
+func stopFabric(cmd *cobra.Command) {
+	out := cmd.OutOrStdout()
+	bin := fabricCLI()
+	if bin == "" {
+		return
+	}
+	ctx, cancel := context.WithTimeout(cmd.Context(), 30*time.Second)
+	defer cancel()
+	c := exec.CommandContext(ctx, bin, "node", "stop")
+	c.Stdout, c.Stderr = out, cmd.ErrOrStderr()
+	_ = c.Run()
+}

cli/link_test.go

@@ -0,0 +1,58 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+// TestUnlinkIdempotent — a repeat `hanzo unlink` is a no-op. The deregister POST
+// hitting an already-terminal (409) or absent (404) fleet row is the desired end
+// state, so runDisconnect returns nil (not an error) and says so, letting `unlink`
+// be run twice safely.
+func TestUnlinkIdempotent(t *testing.T) {
+	for _, code := range []int{http.StatusConflict, http.StatusNotFound} {
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			w.WriteHeader(code)
+			_, _ = w.Write([]byte(`{"error":"activity terminal"}`))
+		}))
+
+		t.Setenv("HANZO_TOKEN", "test-token") // ensureToken honors this; no login needed
+		var out bytes.Buffer
+		cmd := &cobra.Command{}
+		cmd.SetContext(context.Background())
+		cmd.SetOut(&out)
+
+		if err := runDisconnect(cmd, &Env{CloudURL: srv.URL}); err != nil {
+			t.Errorf("HTTP %d: runDisconnect should be idempotent (nil), got %v", code, err)
+		}
+		if !strings.Contains(out.String(), "already unlinked") {
+			t.Errorf("HTTP %d: want 'already unlinked' notice, got %q", code, out.String())
+		}
+		srv.Close()
+	}
+}
+
+// TestUnlinkDeregisterErrorSurfaces — a non-terminal deregister failure (e.g. 500)
+// is a real error and must be returned, not swallowed as idempotent success.
+func TestUnlinkDeregisterErrorSurfaces(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+		_, _ = w.Write([]byte(`{"error":"boom"}`))
+	}))
+	defer srv.Close()
+
+	t.Setenv("HANZO_TOKEN", "test-token")
+	cmd := &cobra.Command{}
+	cmd.SetContext(context.Background())
+	cmd.SetOut(&bytes.Buffer{})
+
+	if err := runDisconnect(cmd, &Env{CloudURL: srv.URL}); err == nil {
+		t.Fatal("a 500 deregister must surface an error, got nil")
+	}
+}

cli/platform.go

@@ -0,0 +1,326 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+// 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
+	http    *http.Client
+}
+
+func newPlatform(baseURL, token string) *Platform {
+	return &Platform{
+		baseURL: strings.TrimRight(baseURL, "/"),
+		token:   token,
+		http:    &http.Client{Timeout: 60 * time.Second},
+	}
+}
+
+// apiError carries the HTTP status + server message for a failed call so
+// commands can give precise diagnostics (e.g. 401 → token problem).
+type apiError struct {
+	status  int
+	message string
+	path    string
+}
+
+func (e *apiError) Error() string {
+	msg := e.message
+	if msg == "" {
+		msg = http.StatusText(e.status)
+	}
+	hint := ""
+	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)
+}
+
+// do performs one JSON request with the given bearer token, decoding a 2xx body
+// 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("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 {
+		b, err := json.Marshal(body)
+		if err != nil {
+			return err
+		}
+		rdr = bytes.NewReader(b)
+	}
+	req, err := http.NewRequestWithContext(ctx, method, p.baseURL+path, rdr)
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Authorization", "Bearer "+token)
+	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 := p.http.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 &apiError{status: resp.StatusCode, message: serverMessage(raw), path: path}
+	}
+	if out != nil && len(raw) > 0 {
+		if err := json.Unmarshal(raw, out); err != nil {
+			return fmt.Errorf("platform %s: decode response: %w", path, err)
+		}
+	}
+	return nil
+}
+
+// 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"`
+		Error   string `json:"error"`
+	}
+	if json.Unmarshal(raw, &e) == nil {
+		if e.Message != "" {
+			return e.Message
+		}
+		if e.Error != "" {
+			return e.Error
+		}
+	}
+	s := strings.TrimSpace(string(raw))
+	if len(s) > 240 {
+		s = s[:240] + "…"
+	}
+	return s
+}
+
+// ---------------------------------------------------------------------------
+// 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 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>/<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/paas/apps envelope: ordered rows + a drift summary.
+type AppsList struct {
+	Apps    []AppView `json:"apps"`
+	Summary struct {
+		Total   int            `json:"total"`
+		ByDrift map[string]int `json:"byDrift"`
+	} `json:"summary"`
+}
+
+// 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 {
+	Env    string
+	Health string
+	Drift  bool
+}
+
+func (p *Platform) Apps(ctx context.Context, q AppsQuery) (*AppsList, error) {
+	v := url.Values{}
+	if q.Env != "" {
+		v.Set("env", q.Env)
+	}
+	if q.Health != "" {
+		v.Set("health", q.Health)
+	}
+	if q.Drift {
+		v.Set("drift", "1")
+	}
+	path := "/v1/paas/apps"
+	if len(v) > 0 {
+		path += "?" + v.Encode()
+	}
+	out := &AppsList{}
+	return out, p.do(ctx, http.MethodGet, path, p.token, nil, out)
+}
+
+// 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, "/v1/paas/apps/"+url.PathEscape(app), p.token, nil, out)
+}
+
+// driftSeverity extracts the severity string from the raw drift object.
+func driftSeverity(raw json.RawMessage) string {
+	var d struct {
+		Severity string `json:"severity"`
+	}
+	if json.Unmarshal(raw, &d) == nil && d.Severity != "" {
+		return d.Severity
+	}
+	return "-"
+}
+
+// ---------------------------------------------------------------------------
+// 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.
+// ---------------------------------------------------------------------------
+
+// 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"`
+	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"`
+}
+
+// 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
+}
+
+func (p *Platform) Clusters(ctx context.Context) ([]Cluster, error) {
+	var out struct {
+		Clusters []Cluster `json:"clusters"`
+	}
+	err := p.do(ctx, http.MethodGet, "/v1/clusters", p.token, nil, &out)
+	return out.Clusters, err
+}
+
+// ---------------------------------------------------------------------------
+// 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 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)
+	}
+	out := &DeployResult{}
+	if err := p.do(ctx, http.MethodPost, path, p.token, nil, out); err != nil {
+		return nil, err
+	}
+	if !out.OK {
+		return nil, fmt.Errorf("redeploy did not report ok")
+	}
+	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/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.
+type BuildReq struct {
+	Repo           string `json:"repo"`
+	SHA            string `json:"sha"`
+	Image          string `json:"image"`
+	Branch         string `json:"branch,omitempty"`
+	Ref            string `json:"ref,omitempty"`
+	Dockerfile     string `json:"dockerfile,omitempty"`
+	Context        string `json:"context,omitempty"`
+	DockerTarget   string `json:"dockerTarget,omitempty"`
+	OS             string `json:"os,omitempty"`
+	Arch           string `json:"arch,omitempty"`
+	OrganizationID string `json:"organizationId,omitempty"`
+}
+
+// BuildJob is the enqueue acceptance (HTTP 202).
+type BuildJob struct {
+	BuildJobID string `json:"buildJobId"`
+	Status     string `json:"status"`
+	RunnerPool string `json:"runnerPool"`
+	Image      string `json:"image"`
+	Target     string `json:"target"`
+}
+
+// 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("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/runner", buildToken, req, out)
+}

cli/platform_test.go

@@ -0,0 +1,176 @@
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// platformStub spins an httptest server whose handler is provided by the test,
+// plus a client pointed at it with the given token.
+func platformStub(t *testing.T, token string, h http.HandlerFunc) (*Platform, func()) {
+	t.Helper()
+	srv := httptest.NewServer(h)
+	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/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"}`)}},
+		})
+	})
+	defer done()
+
+	res, err := p.Apps(context.Background(), AppsQuery{Env: "main", Drift: true})
+	if err != nil {
+		t.Fatalf("Apps: %v", err)
+	}
+	if len(res.Apps) != 1 || res.Apps[0].App != "iam" {
+		t.Fatalf("apps wrong: %+v", res.Apps)
+	}
+	if driftSeverity(res.Apps[0].Drift) != "red" {
+		t.Fatalf("drift severity = %q", driftSeverity(res.Apps[0].Drift))
+	}
+}
+
+// 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/paas/apps/iam" {
+			t.Errorf("path = %s, want /v1/paas/apps/iam", r.URL.Path)
+		}
+		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", Phase: "Running"})
+	})
+	defer done()
+	a, err := p.App(context.Background(), "iam")
+	if err != nil || a.App != "iam" {
+		t.Fatalf("App: %v %+v", err, a)
+	}
+}
+
+// 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.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())
+	if err != nil || len(cs) != 1 || cs[0].ID() != "c1" || cs[0].Kind != "managed" {
+		t.Fatalf("Clusters: %v %+v", err, cs)
+	}
+}
+
+// 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) {
+		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)
+		}
+		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()
+	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(DeployResult{OK: false})
+	})
+	defer done()
+	if _, err := p.Redeploy(context.Background(), "c", ""); err == nil {
+		t.Fatalf("expected error when ok=false")
+	}
+}
+
+func TestPlatformEnqueueBuild(t *testing.T) {
+	p, done := platformStub(t, "svc-tok", func(w http.ResponseWriter, r *http.Request) {
+		// The build endpoint must use the BUILD token, not the service token.
+		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/runner" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		body, _ := io.ReadAll(r.Body)
+		var req BuildReq
+		_ = json.Unmarshal(body, &req)
+		if req.Repo != "hanzoai/pricing" || req.SHA != "abc123" || req.Image == "" {
+			t.Errorf("build body = %+v", req)
+		}
+		w.WriteHeader(202)
+		_ = json.NewEncoder(w).Encode(BuildJob{BuildJobID: "bj-1", Status: "queued", RunnerPool: "runner-pool-32g", Image: req.Image})
+	})
+	defer done()
+
+	job, err := p.EnqueueBuild(context.Background(), BuildReq{Repo: "hanzoai/pricing", SHA: "abc123", Image: "ghcr.io/hanzoai/pricing:t"}, "build-tok")
+	if err != nil || job.BuildJobID != "bj-1" {
+		t.Fatalf("EnqueueBuild: %v %+v", err, job)
+	}
+	if _, err := p.EnqueueBuild(context.Background(), BuildReq{Repo: "r", SHA: "s", Image: "i"}, ""); err == nil {
+		t.Fatalf("expected error with empty build token")
+	}
+}
+
+func TestPlatformError401Hint(t *testing.T) {
+	p, done := platformStub(t, "bad", func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(401)
+		_ = json.NewEncoder(w).Encode(map[string]string{"message": "Unauthorized"})
+	})
+	defer done()
+	_, err := p.Apps(context.Background(), AppsQuery{})
+	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", "")
+	// 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/quiet.go

@@ -0,0 +1,24 @@
+package cli
+
+import "os"
+
+// realStdout is the process's true stdout, captured at this package's init
+// before the server-graph dependencies (iam/beego, kms) run their own init()
+// functions — several of which emit warnings to stdout (e.g. the IAM registry
+// signing-key loader). To keep the CLI's stdout machine-readable (so
+// `hanzo apps list -o json | jq` is never corrupted by a dependency's startup
+// chatter), this init redirects stdout to stderr for the duration of process
+// initialization; RestoreStdout puts the real stdout back before any command
+// writes a byte.
+//
+// This is best-effort: it only helps when this package initializes before the
+// noisy dependency (cmd/hanzo imports cli first) AND that dependency reads the
+// os.Stdout variable at log time rather than capturing it earlier. main always
+// calls RestoreStdout, so correctness never depends on the redirect taking.
+var realStdout = os.Stdout
+
+func init() { os.Stdout = os.Stderr }
+
+// RestoreStdout restores the real process stdout. cmd/hanzo calls this as its
+// first statement so every command writes to the genuine stdout.
+func RestoreStdout() { os.Stdout = realStdout }

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,
+// `link` 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,239 @@
+// studio.go — local Hanzo Studio render-backend supervision for `hanzo link
+// --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
+	}
+	// --listen 127.0.0.1 (loopback only) + --worker-mode: the render backend serves
+	// the fleet worker on this box and nothing else. The worker dials loopback
+	// (localComfyUI) so binding wider bought nothing but an open, unauthenticated
+	// /prompt — the hidden-run hole. --worker-mode makes the studio gate its submit
+	// seam (/v1/worker/execute + X-Worker-Token) so only the worker can start a render.
+	// VRAM mode: default --normalvram (safe for smaller BYO GPUs); override with
+	// HANZO_STUDIO_VRAM (e.g. "--highvram") on big-memory boxes (GB10 128G unified) so
+	// the Qwen text-encoder stays resident on-GPU instead of non-deterministically
+	// offloading to CPU — offload makes renders CPU-bound and ~8x slower.
+	vramMode := os.Getenv("HANZO_STUDIO_VRAM")
+	if vramMode == "" {
+		vramMode = "--normalvram"
+	}
+	cmd := exec.Command(studioPython(dir), "main.py",
+		"--listen", "127.0.0.1", "--port", "8188", "--worker-mode",
+		vramMode, "--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,570 @@
+// 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 (
+	"context"
+	"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))))
+	// The accepted rails are public on-chain data (chain, token, treasury), read by
+	// the browser to render the send UI. A GET with no side effects and no secret,
+	// so it needs neither CSRF nor the write limiter — but it MUST sit beside the
+	// POST at this priority, or the /v1/commerce/* bridge swallows it.
+	app.Get("/v1/commerce/topup/rails", cloud.Handle(s, topupRails))
+}
+
+// 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
+	}
+
+	// ADDITIONAL org (caller already has a home): create it WITHOUT moving them —
+	// they reach it via the OrgSwitcher (a move would strip their SuperAdmin / orphan
+	// their current org).
+	if additional {
+		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)
+		}
+		return c.JSON(http.StatusOK, onboardResp{Org: slug, DisplayName: displayName, Additional: true})
+	}
+
+	// FIRST-RUN: drive the ONE atomic IAM provision (org + admin move + hashed
+	// org-scoped credential), replacing the create-org + move-user pair — a mid-flight
+	// retry now converges on the founder's own org instead of orphaning it. The org
+	// starts at a zero balance (usage is pre-paid). Prefer it whenever the
+	// service-token path is wired; fall back to the legacy pair only when it is not,
+	// so a partial deploy still onboards.
+	if s.State.iam.provisionReady() {
+		resp, err := onboardFirstRun(c.Context(), s.State.iam, cr.id, slug, displayName, body.Personal)
+		if err != nil {
+			return err
+		}
+		return c.JSON(http.StatusOK, resp)
+	}
+
+	// Legacy fallback (service token unset): create then move — the non-atomic pair.
+	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 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: false})
+}
+
+// onboardFirstRun drives the ONE atomic IAM provision for a zero-org caller (create
+// org + move them in as admin + mint the hashed org-scoped credential), replacing
+// the create-org + move-user pair so a mid-flight retry converges on the founder's
+// own org instead of orphaning it. The org starts at a ZERO balance — usage is
+// pre-paid, so there is no signup grant. Split out so the provisioning glue is
+// unit-tested against mock IAM without the CSRF/routing/principal shell.
+func onboardFirstRun(ctx context.Context, iam *iamClient, callerID, slug, displayName string, personal bool) (onboardResp, error) {
+	row, err := iam.getUserRow(ctx, callerID)
+	if err != nil {
+		return onboardResp{}, zip.Errorf(http.StatusBadGateway, "could not resolve the user: %v", err)
+	}
+	res, err := iam.provision(ctx, row.Owner, row.Name, slug, personal)
+	if err != nil {
+		return onboardResp{}, zip.Errorf(http.StatusBadGateway, "could not provision the organization: %v", err)
+	}
+	return onboardResp{Org: res.Org, DisplayName: displayName, Additional: false}, nil
+}
+
+// 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,358 @@
+// 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
+}
+
+// IsServiceToken is the exported view of s2sBillingCall — whether the request is a trusted
+// in-proc S2S caller bearing the verified COMMERCE_SERVICE_TOKEN. Used by co-resident route
+// gates (e.g. the spend-alert admin gate) that must admit the metering cap-gate and the
+// SuperAdmin cap-oversight Forward alongside org admins, while refusing a plain member.
+func IsServiceToken(c *zip.Ctx) bool { return s2sBillingCall(c) }

clients/account/billing_coresident.go

@@ -0,0 +1,89 @@
+// billing_coresident.go — PinBillingSubject, the subject-pinning middleware that lets
+// commerce's OWN billing READ handlers serve co-resident in the unified cloud binary.
+//
+// WHY IT EXISTS. Co-resident, commerce is EMBEDDED (apps/commerce.go mountCommerce →
+// commerce.Embed on the shared zip app), and in prod there is NO standalone commerce
+// backend — the in-cluster `commerce` Service selects the cloud pods themselves. So the
+// /v1/billing/* bridge (billing.go), which forwards to COMMERCE_URL, has nowhere to send
+// a read but back into cloud: the default base (the public api.hanzo.ai edge) re-enters
+// the same bridge in an unbounded self-dispatch loop that surfaces as a 502
+// ("billing upstream unreachable: Get https://api.hanzo.ai/v1/billing/<path>"). The fix
+// is to serve those reads co-resident from the embedded commerce — the same co-resident
+// move mountCommerce already makes for GET /v1/billing/plans — so the specific route
+// shadows the bridge wildcard (order 100 < 122) and never leaves the process.
+//
+// WHAT IT GUARANTEES. commerce's read handlers scope to the org by NAMESPACE (from the
+// gateway-validated X-Org-Id via iammiddleware) but filter finer scope (the billing
+// subject) only from a query param — an UNPINNED ListInvoices returns every user's rows
+// in the org namespace. The /v1/billing/* bridge is what pins that subject today; this
+// middleware carries the SAME pin onto the co-resident route so the isolation is
+// byte-for-byte the shipped behavior. It is the ONE subject rule (account.Payer, the same
+// function the ai spend-gate and the top-up resolve), fed the account the credential NAMES
+// — so a read scopes to exactly the account the gate debits, never wider.
+package account
+
+import (
+	"net/url"
+
+	"github.com/hanzoai/account"
+
+	"github.com/hanzoai/cloud/clients/principal"
+	"github.com/zap-proto/zip"
+)
+
+// PinBillingSubject pins every billing subject key in the request query to the VALIDATED
+// caller's own subject (dropping ?org), so a co-resident commerce read handler downstream
+// can only ever return the caller's OWN rows. It is the co-resident twin of billingData's
+// subject-pinning, reusing the SAME resolveCaller → account.Payer rule and the SAME
+// scopedBillingSearch, so the two paths scope identically.
+//
+// Three cases, mirroring billingData exactly:
+//   - Browser customer (a validated principal with an org): OVERWRITE the subject keys
+//     with the caller's own subject and drop ?org. The client cannot widen scope.
+//   - Trusted in-proc S2S (the verified COMMERCE_SERVICE_TOKEN bearer, carrying its own
+//     X-Org-Id): pass the query through VERBATIM — it legitimately names its own subject,
+//     scoped by the EdgeAuth-controlled org.
+//   - Neither: refuse. A bearer-less request with a forged X-Org-Id has no validated
+//     principal and is fail-closed here, before the read handler runs.
+//
+// The pin rewrites the request URI's query string AND (on a write) the JSON body in place;
+// fasthttp's SetQueryString resets the parsed-args cache and SetBody replaces the body
+// bytes, so the handler's later c.Query() / c.Bind() read the pinned values. Pinning the
+// body is what keeps a co-resident WRITE handler that reads its subject from the body
+// (commerce's CreatePaymentMethod reads customerId from the JSON body) IDOR-safe — query-only
+// pinning would leave a client-named customerId/userId in the body untouched.
+func PinBillingSubject() zip.Handler {
+	return func(c *zip.Ctx) error {
+		inQuery, _ := url.ParseQuery(string(c.Fiber().Request().URI().QueryString()))
+
+		cr, ok := resolveCaller(c, true)
+		if !ok {
+			// Not a validated customer — admit ONLY a trusted in-proc S2S caller that
+			// names its own org (same admission billingData makes), leaving its query
+			// untouched. Everything else is refused before the read runs.
+			if s2sBillingCall(c) && c.Org() != "" {
+				return c.Next()
+			}
+			return zip.ErrForbidden("sign in to view billing")
+		}
+
+		subject := account.Payer(account.Credential{
+			Owner:   cr.owner,
+			Name:    cr.username,
+			Account: principal.BillingAccount(c),
+		}).Subject()
+
+		// Pin the subject on BOTH the query AND the write body — the SAME two-helper
+		// scoping billingData applies (scopedBillingSearch + scopedBillingBody). A
+		// co-resident WRITE handler that reads its subject from the body (commerce's
+		// CreatePaymentMethod → customerId) is only IDOR-safe if the body is pinned too.
+		// scopedBillingBody overwrites the subject keys and preserves every other field
+		// (card, type, sourceId, …); a non-JSON / empty body is returned unchanged, so a
+		// GET read carries no body and is unaffected.
+		c.Fiber().Request().URI().SetQueryString(scopedBillingSearch(inQuery, subject).Encode())
+		if len(c.Body()) > 0 {
+			c.Fiber().Request().SetBody(scopedBillingBody(c.Body(), subject))
+		}
+		return c.Next()
+	}
+}

clients/account/billing_coresident_test.go

@@ -0,0 +1,150 @@
+package account
+
+import (
+	"encoding/json"
+	"net/http"
+	"testing"
+
+	"github.com/hanzoai/cloud"
+	luxlog "github.com/luxfi/log"
+	"github.com/zap-proto/zip"
+)
+
+// billing_coresident_test.go — proves PinBillingSubject carries the SAME tenant scoping
+// onto a co-resident commerce read handler that billingData applies on the bridge: the
+// caller's own subject is pinned into the query (dropping ?org), an unvalidated caller is
+// refused before the handler runs, and a trusted in-proc S2S caller passes through
+// verbatim. This is what lets commerce's ListInvoices/ListBillingSubscriptions/... serve
+// in-process without leaking another subject's rows.
+
+// echoQuery is the downstream stand-in for a commerce read handler: it reports exactly the
+// query it observes AFTER the pin, so a test can assert the subject the handler would filter on.
+func echoQuery(c *zip.Ctx) error {
+	return c.JSON(200, map[string]any{
+		"user":       c.Query("user"),
+		"userId":     c.Query("userId"),
+		"customerId": c.Query("customerId"),
+		"org":        c.Query("org"),
+		"status":     c.Query("status"),
+	})
+}
+
+// echoBody is the downstream stand-in for a commerce WRITE handler (e.g. CreatePaymentMethod)
+// that reads its subject from the JSON BODY: it reports the body it observes AFTER the pin, so
+// a test can assert the subject the handler would persist and that non-subject fields survive.
+func echoBody(c *zip.Ctx) error {
+	var got map[string]any
+	if len(c.Body()) > 0 {
+		_ = json.Unmarshal(c.Body(), &got)
+	}
+	return c.JSON(200, got)
+}
+
+func pinApp(t *testing.T) *zip.App {
+	t.Helper()
+	app := zip.New(zip.Config{Logger: luxlog.New("test")})
+	// MountAccount installs the identity middleware PinBillingSubject relies on; mounting
+	// it keeps the probe on the same trust plane as the real co-resident registration.
+	if err := MountAccount(app, cloud.Deps{Logger: luxlog.New("test"), Brand: "hanzo"}); err != nil {
+		t.Fatalf("MountAccount: %v", err)
+	}
+	app.Get("/probe", PinBillingSubject(), echoQuery)
+	app.Post("/probe", PinBillingSubject(), echoBody)
+	return app
+}
+
+// TestPinBillingSubject_PinsCallerAndDropsOrg — a validated customer's forged subject
+// keys are overwritten with its OWN subject and ?org is dropped, exactly like the bridge.
+func TestPinBillingSubject_PinsCallerAndDropsOrg(t *testing.T) {
+	app := pinApp(t)
+	code, body := callH(t, app, http.MethodGet,
+		"/probe?userId=victim&customerId=victim&user=victim&org=othercorp&status=open", alice, "")
+	if code != http.StatusOK {
+		t.Fatalf("want 200, got %d (%s)", code, body)
+	}
+	var got map[string]string
+	if err := json.Unmarshal(body, &got); err != nil {
+		t.Fatalf("bad body: %s", body)
+	}
+	for _, k := range billingSubjectKeys {
+		if got[k] != "acme" { // alice/acme resolves to the org subject "acme"
+			t.Fatalf("handler must see %s=acme (caller's own subject), got %q", k, got[k])
+		}
+	}
+	if got["org"] != "" {
+		t.Fatalf("org must be dropped, handler saw org=%q", got["org"])
+	}
+	if got["status"] != "open" {
+		t.Fatalf("non-subject filter must survive, got status=%q", got["status"])
+	}
+}
+
+// TestPinBillingSubject_PinsBodyForWrites — a POST whose JSON body names a FOREIGN subject
+// (customerId/userId/user) has every subject key overwritten with the caller's OWN subject
+// before the handler binds it, while non-subject fields survive. This is the boundary
+// commerce's CreatePaymentMethod (which reads customerId from the body) relies on to be
+// IDOR-safe co-resident — byte-identical to billingData's scopedBillingBody on the bridge.
+func TestPinBillingSubject_PinsBodyForWrites(t *testing.T) {
+	app := pinApp(t)
+	code, body := callH(t, app, http.MethodPost, "/probe", alice,
+		`{"customerId":"victim","userId":"victim","user":"victim","card":{"last4":"4242"}}`)
+	if code != http.StatusOK {
+		t.Fatalf("want 200, got %d (%s)", code, body)
+	}
+	var got map[string]any
+	if err := json.Unmarshal(body, &got); err != nil {
+		t.Fatalf("bad body: %s", body)
+	}
+	for _, k := range billingSubjectKeys {
+		if got[k] != "acme" { // alice/acme resolves to the org subject "acme"
+			t.Fatalf("handler must see body %s=acme (caller's own subject), got %v", k, got[k])
+		}
+	}
+	card, ok := got["card"].(map[string]any)
+	if !ok || card["last4"] != "4242" {
+		t.Fatalf("non-subject body field must survive the pin, got card=%v", got["card"])
+	}
+}
+
+// TestPinBillingSubject_RefusesUnvalidated — a forged X-Org-Id with NO validated
+// X-User-Id (and no service token) is refused before the read handler runs: no
+// cross-tenant billing read is possible.
+func TestPinBillingSubject_RefusesUnvalidated(t *testing.T) {
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := pinApp(t)
+	code, _ := callH(t, app, http.MethodGet, "/probe?userId=victim",
+		map[string]string{"X-Org-Id": "victim"}, "")
+	if code != http.StatusForbidden {
+		t.Fatalf("unvalidated caller: want 403, got %d", code)
+	}
+}
+
+// TestPinBillingSubject_S2SForwardsVerbatim — the trusted in-proc S2S caller (verified
+// COMMERCE_SERVICE_TOKEN + its own X-Org-Id, no validated user) is admitted and its query
+// is left UNTOUCHED, so it can name its own subject (the cap-gate's authorize read).
+func TestPinBillingSubject_S2SForwardsVerbatim(t *testing.T) {
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := pinApp(t)
+	code, body := callH(t, app, http.MethodGet, "/probe?user=acme&status=open",
+		map[string]string{"Authorization": "Bearer svc-tok", "X-Org-Id": "acme"}, "")
+	if code != http.StatusOK {
+		t.Fatalf("S2S: want 200, got %d (%s)", code, body)
+	}
+	var got map[string]string
+	_ = json.Unmarshal(body, &got)
+	if got["user"] != "acme" || got["status"] != "open" {
+		t.Fatalf("S2S query must pass through verbatim, got %+v", got)
+	}
+}
+
+// TestPinBillingSubject_S2SNoOrgRefused — the service token with NO X-Org-Id has no org
+// to scope the privileged read and is refused (matches billingData's s2s org requirement).
+func TestPinBillingSubject_S2SNoOrgRefused(t *testing.T) {
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := pinApp(t)
+	code, _ := callH(t, app, http.MethodGet, "/probe",
+		map[string]string{"Authorization": "Bearer svc-tok"}, "")
+	if code != http.StatusForbidden {
+		t.Fatalf("S2S without X-Org-Id: want 403, got %d", code)
+	}
+}

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")
+	}
+}