deepdebug-local-agent 1.0.23 → 1.2.0

package/.claude/standards/security-owasp.md

@@ -0,0 +1,114 @@
+# Security (OWASP Top 10 and ASVS basics, applied)
+
+Default posture: **deny by default, fail closed, trust nothing the client sends, and prove it
+on the deployed artefact.**
+
+## 1. Tenant isolation and access control (A01)
+
+This is the risk that matters most for us. One missing check leaks one customer's data to
+another.
+
+- **The tenant is always the signed JWT claim.** In the gateway, resolve it with
+  `TenantAccessGuard.requireTenant(user)`. A `tenantId` in the body, query, path or header
+  can at most be *compared* against the claim; it is never used on its own. Enforced by
+  `ControllerTenantSourceArchTest`. Frontend: never send `tenantId`.
+- **Ownership on every lookup by id.** Use `TenantAccessGuard.requireOwnedWorkspace`,
+  `IncidentAccessGuard` for incidents, and `TenantRepoOwnership` before acting on a repo
+  named in a payload. Every SQL query on tenant data has `tenant_id = :tenantId`.
+- **Unknown and foreign both answer 404.** Answering 403 confirms the id exists and makes
+  ids enumerable.
+- **Check the tenant first**, then authentication details, then role or plan (RBAC). Never
+  run a permission check that reveals whether a resource exists before the tenant check.
+- **Root and admin routes** use the dedicated guards (for example `RootAdminGuard`). Root
+  users do not call tenant-scoped `/api/v2/admin/*` from the FE.
+- **Internal endpoints** (`/api/v1/internal/**`, `/internal/**`) use the internal bearer
+  checked by `InternalTokenAuthenticator`: constant-time compare
+  (`MessageDigest.isEqual`), and reject everything when the token isn't configured. A
+  tenant id in an internal payload still has to be bound to the resource
+  (`TenantRepoOwnership`).
+- **Per-purpose credentials.** The codescan callback uses a per-scan HMAC token (with
+  expiry and rotation via `_PREVIOUS`), never the shared internal token. Each service has
+  its own LiteLLM virtual key.
+- **Redis keys and channels** that carry tenant data include the tenant id.
+- **Automation and merge.** Anything that applies a patch goes through
+  `AutomationGateService` (`AutomationGateArchTest`). Nothing merges on its own
+  (`NoAutonomousMergeArchitectureTest`). A model verdict is evidence for a human reviewer,
+  never permission to merge.
+- **A new check on an existing resource:** find **every** read path to that resource, not
+  just the new one. A check that a parallel path bypasses is worse than none.
+
+## 2. Secrets (A02, A05, ASVS V6/V14)
+
+- No secret in code, YAML defaults, Dockerfiles, `manifest.yml`, docs, tests, PR text or
+  commit messages. Secrets come from Secret Manager, env vars or Forge variables at
+  runtime.
+- **Never print a secret.** Not in logs, errors, `toString()`, SSE frames, CLI output, or
+  your own terminal while debugging. To check a secret, compare hashes or lengths, or run
+  `grep -c` against the real log.
+- **Provider keys (Anthropic, Gemini, OpenAI, Voyage) exist only in vh-litellm.** Any
+  other service holding one is a bug (`NoDirectProviderCallsGuardTest`,
+  `LlmAgnosticRatchetTest`, `test_no_direct_provider.py`).
+- Cloud Run: `--update-env-vars` / `--update-secrets`, never `--set-env-vars`.
+- If a secret leaks into git or logs, rotate it. Deleting the line is not enough.
+- Encryption: AES-GCM with a random IV, no ECB, no "decrypt failed, so return the
+  plaintext" (`NoEcbEncryptionArchTest`). Hash passwords with BCrypt or Argon2.
+
+## 3. Input validation and injection (A03)
+
+- Validate at the boundary with allowlists: `@Valid` plus jakarta constraints on DTOs,
+  zod or explicit checks in TS, pydantic or explicit checks in Python. Reject
+  input; don't "clean" it.
+- SQL: bound parameters only (`:param` in `@Query` or `DatabaseClient.bind`). Dynamic sort
+  or column names go through an allowlist map.
+- Shell and git: pass argument arrays (`ProcessBuilder(List)`, `spawn(cmd, args)`,
+  `subprocess.run([...])`), never a concatenated string and never `shell=True`. Refs,
+  branch names and paths from users are validated against a strict pattern.
+- Paths: normalize, then check the result is inside the workspace root. Reject `..`,
+  absolute paths and symlink escapes.
+- **Prompt injection.** Ticket descriptions, repo files, logs and PR comments are untrusted
+  data. Pass them as delimited data, never as instructions, and never let them pick tools,
+  URLs or credentials.
+- Frontend: no `dangerouslySetInnerHTML` with server or user text; encode for the sink.
+
+## 4. SSRF and egress (A10)
+
+- Any URL a tenant supplies (webhooks, `localAgentUrl`, repo URLs, callback URLs) goes
+  through an egress guard (`EgressUrlGuard`). Block loopback, link-local and the metadata
+  server (`169.254.169.254`, `metadata.google.internal`), and block private ranges for
+  third-party targets. Re-check after DNS resolution and on every redirect.
+- Callbacks go only to allowlisted hosts (for example codescan's `CALLBACK_ALLOWED_HOSTS`).
+- Forge app egress allowlist = the gateway domain only.
+- Open redirects: redirect only to relative paths (`/x`, not `//x`) or an exact allowlist.
+
+## 5. Logging without PII or secrets (A09)
+
+- Log events with actor and context ids (`tenantId`, `workspaceId`, `scanId`, correlation
+  id). Don't log payloads.
+- Never log tokens, passwords, API keys, OAuth codes, cookies, `Authorization` headers,
+  URLs with credentials in them (`https://oauth2:<token>@...`), raw prompts, source code,
+  ticket descriptions or personal data (email, names) beyond an id.
+- Redact credentials in URLs before logging (the shared sanitizer, pinned by
+  `SecretsNeverReachLogsTest`). Framework loggers can leak query strings too. Keep keys
+  out of query strings.
+- Security events (auth failure, cross-tenant attempt, guard rejection) are logged at WARN
+  with the reason and no secrets.
+- Error responses carry no stack traces and no internal hosts.
+
+## 6. Other Top 10 items, briefly
+
+- **A04 insecure design:** new flows that act on customer systems need a threat note in the
+  PR: who can trigger it, what it can touch, and how it fails.
+- **A05 misconfiguration:** QA-only beans are `@Profile("qa")` (`QaProfileArchTest`).
+  Security headers in `vercel.json` / nginx are fixed. No runtime DDL.
+- **A06 components:** pin versions. codescan's trivy/gitleaks and Dependabot findings with
+  CVSS >= 7 block release. The LiteLLM image is pinned to an exact tag, never `latest`.
+- **A07 auth:** short-lived JWTs with refresh; OAuth `state` bound to the session and
+  single-use; tokens never in URLs (FE `authenticatedDownload`).
+- **A08 integrity:** verify webhook signatures (GitHub HMAC, Forge FIT via JWKS, Slack
+  signing) before parsing.
+
+## 7. Verify on the real artefact
+
+Code review proves what we control. Leaks happen in what we don't. Before you say "no
+secret, PII or egress", grep the real revision's logs, the real HTTP response and the
+built JS bundle.

package/.claude/standards/simplicity.md

@@ -0,0 +1,42 @@
+# Simplicity (KISS, YAGNI)
+
+The cheapest code to own is code that doesn't exist. Before adding anything, ask:
+
+1. Does the current requirement need it? If the answer starts with "we might", don't add it.
+2. Does the standard library, the framework or code already in the repo solve it? Search first.
+3. Could a new teammate understand it in 30 seconds?
+
+## Rules
+
+- **No speculative generality.** No extension points, config options, feature flags,
+  generic type parameters or plugin systems without a second real use case today.
+- **No interface with a single implementation** unless it is a port that crosses a layer
+  or process boundary (see `solid.md`).
+- **Flags are for rollout, not for design.** A feature flag guards a risky change until
+  the soak is over; then either the old path or the flag gets removed. Every flag has an
+  owner and an exit condition in the PR.
+- **No new dependency** (Maven artifact, npm package, pip package) without saying in the
+  PR why the existing stack can't do it. Check its licence and maintenance. Never add a
+  provider LLM SDK (ADR-001).
+- **Prefer boring technology** that is already in the stack: WebFlux, R2DBC, Postgres,
+  Redis, React Query, shadcn/ui, pytest. Don't add a second library for the same job.
+- **Small PRs.** One intent per PR. Keep mechanical moves and renames separate from
+  behaviour changes. Keep removals in their own PR (gateway CLAUDE.md rule 1).
+- **Delete as you go.** When a flag has soaked, remove the dead branch in a follow-up PR
+  and make the ratchet baseline shrink.
+
+## Smells
+
+| Smell | Simpler alternative |
+|---|---|
+| `AbstractBaseGenericHandler<T, R, C>` with one subclass | the one concrete class |
+| a config property nobody sets to anything but the default | a constant |
+| a 5-step builder for a 3-field object | a record constructor |
+| a Reactor chain with `zip` over one publisher, or `flatMap(Mono::just)` | the plain operator (`map`) |
+| a React context for state used by one component | local `useState` |
+| a retry, cache or queue "for performance" with no measurement | measure first |
+
+## Simple is not naive
+
+Simplicity never justifies skipping tenant checks, input validation, error handling or
+tests. Those are part of the requirement.

package/.claude/standards/solid.md

@@ -0,0 +1,64 @@
+# SOLID, applied to our code
+
+Use SOLID to decide structure: where a responsibility lives and what depends on what. Name
+the principle, point at the concrete smell, and apply the smallest fix. Don't bring in a
+pattern that is heavier than the problem (see `simplicity.md`).
+
+## S: single responsibility
+
+A class has one reason to change, meaning one actor or one policy.
+
+- Smell: a 2,000-line `*Service` that does HTTP mapping, SQL, prompt building and
+  notifications. `AgenticChatService` is the cautionary example.
+- Fix: one use case per application class, such as `IncidentFixRunner` and
+  `OrchestratedImplementRunner`. Adapters live in `infrastructure/`.
+- Rule of thumb: if describing the class needs "and", it probably has two jobs.
+
+## O: open/closed
+
+Add behaviour by adding code, not by editing a switch that keeps growing.
+
+- Smell: `if (provider.equals("github")) ... else if ("gitlab") ... else if ("bitbucket")`
+  copied into several services.
+- Fix: one strategy or adapter per variant behind a port, chosen once in a map or registry.
+  For a closed set, a Java 21 `sealed` interface with a `switch` is fine and simpler.
+- A single `switch` in one place is not a violation. Wait for it to be duplicated.
+
+## L: Liskov substitution
+
+A subtype must work wherever its parent does, with no surprises.
+
+- Smell: an override that throws `UnsupportedOperationException`, or a caller doing
+  `instanceof` checks to avoid a subtype.
+- Fix: composition over inheritance; split the interface (see ISP).
+- Exception: we do deliberately make a dead autonomous path throw (for example the retired
+  `autoApproveAndMerge`) so it cannot run. That is a kill switch, not a design to copy.
+
+## I: interface segregation
+
+Callers depend only on what they use.
+
+- The gateway's `agenttask` feature has three ports, `AgentTaskPort`, `AgentRunPort` and
+  `AgentReviewPort`, instead of one "OrchestratorClient" with every method. Follow that
+  shape.
+- Smell: a port whose implementers leave half the methods empty.
+
+## D: dependency inversion
+
+High-level policy doesn't depend on low-level detail. Both depend on an abstraction owned
+by the high level.
+
+- Ports (interfaces) live in `domain/` (or `application/`) of the feature that needs them.
+  Adapters in `infrastructure/` implement them. Examples: `AgentTaskPort` is implemented by
+  `OrchestratorAgentTaskClient`, and `LlmPort` by `LiteLlmChatAdapter`.
+- Use constructor injection only. No field injection, no `new` of collaborators inside
+  business code, no static service locators.
+- Don't create an interface for a class that has one implementation and no boundary to
+  cross. A port is justified because it crosses a layer or process boundary, not "for
+  testability" alone.
+
+## Order of work
+
+1. SOLID for structure (split responsibilities, invert dependencies).
+2. Clean code for local readability.
+3. A named design pattern only if variation is real and recurring.

package/.claude/standards/testing.md

@@ -0,0 +1,59 @@
+# Testing
+
+A test proves a **behaviour** a user or caller depends on. A green suite is evidence about
+the code; the deployed artefact is evidence about the product. We need both.
+
+## Rules
+
+- **Test behaviour, not choreography.** Assert on outputs, persisted state, emitted events
+  and HTTP status. Use `verify(...)` only when the interaction *is* the contract (for
+  example "the merge endpoint is never called").
+- **One concept per test**, named for the behaviour:
+  `crossTenantWorkspaceAnswers404`, `callbackRejectsExpiredHmac`.
+- **Cover the scenarios, not the lines:** happy path; boundaries (0, 1, max); invalid, null
+  or empty input; error path (downstream fails, times out, returns garbage);
+  **authorization (no token, wrong tenant, wrong role)**; idempotency and retries;
+  ordering and concurrency where it applies.
+- **Every tenant-scoped endpoint or use case has a cross-tenant test** that expects 404 (or
+  an empty result) and proves nothing of the other tenant leaks.
+- **Mock only real boundaries**: HTTP clients, ports to other services, the clock, and
+  external CLIs. Use real objects for the unit under test, value objects, DTOs, records and
+  pure functions.
+- **Mocks hide types.** A mocked repository accepts a `String` that Postgres will reject
+  as `jsonb`, `uuid[]`, an enum or `timestamptz`. Any new write to a column must be
+  exercised against real PostgreSQL (Testcontainers) or a real call in QA before it
+  counts as tested. The same goes for JSON contracts between services: test against the
+  real DTO or schema, not a hand-written map.
+- **Tests are deterministic**: no real network, no sleeps (use virtual time or fake
+  clocks), no order dependence, no shared mutable fixtures.
+- **Don't edit an existing test to make it pass.** If a correct test fails, the code is
+  wrong. If the test is wrong, fix it in a separate, explained commit.
+
+## Bug fixes: RED, then GREEN
+
+1. Reproduce: write a failing test that shows the bug (or point to an existing failing
+   one). Commit it or keep it in the PR.
+2. Fix the production code until it passes.
+3. Run the module suite, then the full suite.
+4. In the PR: scenario, the proof test, the fix and the results.
+
+## Guard tests are tests too
+
+Architecture and guard tests (ArchUnit or source scans) protect invariants that no
+behavioural test will catch next year. See the table in `README.md`. When you fix a class
+of bug (not one instance), add or extend a guard so the *next* instance fails the build.
+
+## Per stack
+
+| Stack | Unit | Slice / integration | Notes |
+|---|---|---|---|
+| Java WebFlux | JUnit 5 + AssertJ + Mockito; `StepVerifier` for every `Mono`/`Flux` (never `.block()` in tests) | `@WebFluxTest` + `WebTestClient`; Testcontainers Postgres for R2DBC and migrations | `mvn -q -Dtest=ClassName test` for targeted runs; JDK 21 locally (Lombok breaks on 25) |
+| TypeScript/React | Vitest + Testing Library; test the hook/component behaviour the user sees | MSW or mocked `lib/api` at the HTTP edge | `npm run typecheck && npm run lint && npm test` |
+| Python | pytest; pure functions (`scoring`, `normalization`, `smart_router_policy`) without I/O | subprocess engines faked at the boundary; schema tests on JSON contracts | `pytest -q` |
+| Node (local-agent) | `node --test` | fixtures under `test/fixtures` | `npm test` |
+
+## Verify by use
+
+After a merge deploys QA, verify the behaviour on the deployed revision: `curl` the
+endpoint, read that revision's logs (the severity is in the text, not in the metadata),
+and grep the built bundle. Compare startup with startup. "Tests pass" is not "it works".

package/.cursor/rules/standards.mdc

@@ -0,0 +1,17 @@
+---
+description: VisionHammer v2 context and engineering standards (shared across repos)
+alwaysApply: true
+---
+
+Before writing or reviewing code in this repo, read and follow:
+
+- @.claude/context.md (what this repo is, boundaries, run/test/deploy, gotchas)
+- @.claude/standards/README.md (index and the guard tests that enforce the standards)
+- @.claude/standards/security-owasp.md
+- @.claude/standards/layered-architecture.md
+- @.claude/standards/node.md
+- @AGENTS.md
+
+The other standards (`clean-code.md`, `solid.md`, `simplicity.md`, `testing.md`,
+`code-review-checklist.md`) live in `.claude/standards/`. Repo rules in `CLAUDE.md` and
+`AGENTS.md` win over the generic standards.

package/.github/workflows/build-byoc-image.yml

@@ -0,0 +1,315 @@
+# Build + push the BYOC "full" local-agent image (Dockerfile.full: Node + JDK 17
+# + Maven + Python + Swift) to the PUBLIC Artifact Registry repo that customer
+# clouds pull from without credentials:
+#
+#   europe-west1-docker.pkg.dev/visionhammer/visionhammer-docker-public-eu/local-agent-full:<semver>
+#   europe-west1-docker.pkg.dev/visionhammer/visionhammer-docker-public-eu/local-agent-full:<git-sha>
+#
+# Consumers: vh-api-gateway CloudEngineerService (BYOC GCP Cloud Run + BYOC Azure
+# ACI) via the `deepdebug.byoc.agent-image` property. The gateway pins a version
+# (ideally `:<semver>@sha256:<digest>`); this workflow never moves a floating
+# tag (no :latest, no :v3) and refuses to overwrite an existing :<semver>.
+#
+# Triggers:
+#   - push of a v* tag / published GitHub release (tag must be on main).
+#     NOTE: tags pushed by npm-publish.yml's auto-bump use GITHUB_TOKEN and so do
+#     NOT trigger other workflows; run this manually (workflow_dispatch) for those.
+#   - workflow_dispatch from main (version defaults to package.json).
+#
+# Supply chain (ADR-0017 D12), OFF by default: the `supply-chain` job signs the
+# pushed image with cosign (keyless, GitHub OIDC), attaches an SPDX SBOM (syft)
+# and a SLSA v1 provenance attestation, then verifies all three. It runs only
+# when the dispatch input `supply_chain` is true or the repository variable
+# BYOC_SUPPLY_CHAIN is 'true' (for v* tag / release runs). Never on branch pushes
+# (this workflow has no branch trigger). See docs/byoc-agent-image.md.
+name: Build BYOC Agent Image
+
+on:
+  push:
+    tags: ['v*']
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Semver tag to publish (default: package.json version, e.g. 1.0.31)'
+        required: false
+        type: string
+      supply_chain:
+        description: 'Also sign (cosign keyless), attach SBOM + provenance and verify'
+        required: false
+        default: false
+        type: boolean
+
+concurrency:
+  group: build-byoc-image-${{ github.sha }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  id-token: write
+
+env:
+  GCP_PROJECT: visionhammer
+  WIF_PROVIDER: projects/1009366917257/locations/global/workloadIdentityPools/github-pool/providers/github-provider
+  DEPLOYER_SA: github-deployer@visionhammer.iam.gserviceaccount.com
+  AR_HOST: europe-west1-docker.pkg.dev
+  AR_IMAGE: europe-west1-docker.pkg.dev/visionhammer/visionhammer-docker-public-eu/local-agent-full
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 75
+    outputs:
+      version: ${{ steps.vars.outputs.version }}
+      sha: ${{ steps.vars.outputs.sha }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Resolve version and verify source is on main
+        id: vars
+        env:
+          INPUT_VERSION: ${{ inputs.version }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          EVENT: ${{ github.event_name }}
+        run: |
+          set -euo pipefail
+          case "$EVENT" in
+            workflow_dispatch)
+              if [ "$GITHUB_REF" != "refs/heads/main" ]; then
+                echo "::error::workflow_dispatch must run from main (got $GITHUB_REF)"; exit 1
+              fi
+              VERSION="${INPUT_VERSION:-$(node -p "require('./package.json').version")}" ;;
+            # Untrusted-ish input: read from env, never interpolated into the script.
+            release) VERSION="${RELEASE_TAG}" ;;
+            *)       VERSION="${GITHUB_REF_NAME}" ;;
+          esac
+          VERSION="${VERSION#v}"
+          if ! printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$'; then
+            echo "::error::'$VERSION' is not a semver version"; exit 1
+          fi
+          git fetch --quiet origin main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "::error::$GITHUB_SHA is not on main; BYOC images are built from main only"; exit 1
+          fi
+          echo "version=$VERSION"  >> "$GITHUB_OUTPUT"
+          echo "sha=$GITHUB_SHA"   >> "$GITHUB_OUTPUT"
+
+      - name: Authenticate to GCP (WIF)
+        uses: google-github-actions/auth@v2
+        with:
+          workload_identity_provider: ${{ env.WIF_PROVIDER }}
+          service_account: ${{ env.DEPLOYER_SA }}
+
+      - name: Set up gcloud
+        uses: google-github-actions/setup-gcloud@v2
+
+      - name: Configure Docker for Artifact Registry
+        run: gcloud auth configure-docker "$AR_HOST" --quiet
+
+      - name: Refuse to overwrite an existing version tag
+        id: exists
+        run: |
+          V="${AR_IMAGE}:${{ steps.vars.outputs.version }}"
+          S="${AR_IMAGE}:${{ steps.vars.outputs.sha }}"
+          if gcloud artifacts docker images describe "$V" --project "$GCP_PROJECT" >/dev/null 2>&1; then
+            VD=$(gcloud artifacts docker images describe "$V" --project "$GCP_PROJECT" --format='value(image_summary.digest)')
+            SD=$(gcloud artifacts docker images describe "$S" --project "$GCP_PROJECT" --format='value(image_summary.digest)' 2>/dev/null || true)
+            if [ -n "$SD" ] && [ "$VD" = "$SD" ]; then
+              # Same commit already published (e.g. tag push + release both fired).
+              echo "::notice::$V already published from this commit ($VD); nothing to do"
+              echo "skip=true" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+            echo "::error::$V already exists from a different build; bump the version instead of overwriting"
+            exit 1
+          fi
+          echo "skip=false" >> "$GITHUB_OUTPUT"
+
+      - name: Free runner disk (image is ~3 GB with the Swift toolchain)
+        if: steps.exists.outputs.skip != 'true'
+        run: |
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc /opt/hostedtoolcache/CodeQL || true
+          df -h /
+
+      - name: Build image (Dockerfile.full)
+        if: steps.exists.outputs.skip != 'true'
+        run: |
+          docker build --platform=linux/amd64 -f Dockerfile.full \
+            --label org.opencontainers.image.source="https://github.com/${GITHUB_REPOSITORY}" \
+            --label org.opencontainers.image.revision="${{ steps.vars.outputs.sha }}" \
+            --label org.opencontainers.image.version="${{ steps.vars.outputs.version }}" \
+            -t "${AR_IMAGE}:${{ steps.vars.outputs.version }}" \
+            -t "${AR_IMAGE}:${{ steps.vars.outputs.sha }}" \
+            .
+
+      - name: Smoke test (boots, /health public, API requires X-Agent-Token)
+        if: steps.exists.outputs.skip != 'true'
+        run: |
+          set -euo pipefail
+          docker run -d --name smoke -p 5055:5055 \
+            -e LOCAL_AGENT_TOKEN=smoke-token -e DISABLE_WS_TUNNEL=true \
+            "${AR_IMAGE}:${{ steps.vars.outputs.version }}"
+          for i in $(seq 1 60); do
+            curl -fsS http://127.0.0.1:5055/health >/dev/null 2>&1 && break
+            sleep 2
+          done
+          curl -fsS http://127.0.0.1:5055/health
+          code=$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:5055/workspace/info)
+          [ "$code" = "401" ] || { echo "::error::expected 401 without X-Agent-Token, got $code"; docker logs smoke; exit 1; }
+          code=$(curl -s -o /dev/null -w '%{http_code}' -H 'X-Agent-Token: smoke-token' http://127.0.0.1:5055/workspace/info)
+          [ "$code" != "401" ] || { echo "::error::valid X-Agent-Token was rejected"; docker logs smoke; exit 1; }
+          docker exec smoke sh -c 'java -version && mvn -version >/dev/null && swift --version >/dev/null && git --version'
+          docker rm -f smoke
+
+      - name: Push :<semver> and :<git-sha>
+        if: steps.exists.outputs.skip != 'true'
+        id: push
+        run: |
+          set -euo pipefail
+          docker push "${AR_IMAGE}:${{ steps.vars.outputs.version }}"
+          # :<git-sha> is immutable too: the same commit may be rebuilt under a new
+          # semver (e.g. dispatch 1.0.31, later tag v1.0.32) and a rebuild is not
+          # byte-reproducible, so never move an existing :<git-sha> to a new digest -
+          # it keeps pointing at the first image built from that commit.
+          if gcloud artifacts docker images describe "${AR_IMAGE}:${{ steps.vars.outputs.sha }}" \
+               --project "$GCP_PROJECT" >/dev/null 2>&1; then
+            echo "::notice::${AR_IMAGE}:${{ steps.vars.outputs.sha }} already exists; not moving it (pin by semver@digest)"
+          else
+            docker push "${AR_IMAGE}:${{ steps.vars.outputs.sha }}"
+          fi
+          DIGEST=$(docker inspect --format='{{index .RepoDigests 0}}' "${AR_IMAGE}:${{ steps.vars.outputs.version }}" | sed 's/.*@//')
+          echo "digest=$DIGEST" >> "$GITHUB_OUTPUT"
+
+      - name: Summary
+        if: steps.exists.outputs.skip != 'true'
+        run: |
+          {
+            echo "### BYOC agent image published"
+            echo ""
+            echo "- \`${AR_IMAGE}:${{ steps.vars.outputs.version }}\`"
+            echo "- \`${AR_IMAGE}:${{ steps.vars.outputs.sha }}\`"
+            echo "- digest: \`${{ steps.push.outputs.digest }}\`"
+            echo ""
+            echo "Pin it in the gateway (vh-api-gateway, \`deepdebug.byoc.agent-image\` / env \`BYOC_AGENT_IMAGE\`):"
+            echo ""
+            echo "\`${AR_IMAGE}:${{ steps.vars.outputs.version }}@${{ steps.push.outputs.digest }}\`"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+  # Cosign keyless signature + SBOM + provenance for the image pushed above.
+  # Flag: input `supply_chain` (dispatch) or repo variable BYOC_SUPPLY_CHAIN=='true'.
+  # Needs github-deployer to write signatures next to the image (same repository,
+  # roles/artifactregistry.writer, already required to push).
+  supply-chain:
+    needs: build
+    if: ${{ inputs.supply_chain == true || vars.BYOC_SUPPLY_CHAIN == 'true' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      id-token: write   # keyless signing identity (Fulcio) + WIF
+    env:
+      VERSION: ${{ needs.build.outputs.version }}
+      SOURCE_SHA: ${{ needs.build.outputs.sha }}
+    steps:
+      - name: Authenticate to GCP (WIF)
+        uses: google-github-actions/auth@v2
+        with:
+          workload_identity_provider: ${{ env.WIF_PROVIDER }}
+          service_account: ${{ env.DEPLOYER_SA }}
+
+      - name: Set up gcloud
+        uses: google-github-actions/setup-gcloud@v2
+
+      - name: Configure Docker for Artifact Registry
+        run: gcloud auth configure-docker "$AR_HOST" --quiet
+
+      - name: Resolve the image digest
+        id: digest
+        run: |
+          set -euo pipefail
+          D=$(gcloud artifacts docker images describe "${AR_IMAGE}:${VERSION}" \
+                --project "$GCP_PROJECT" --format='value(image_summary.digest)')
+          case "$D" in sha256:*) ;; *) echo "::error::could not resolve digest of ${AR_IMAGE}:${VERSION}"; exit 1;; esac
+          echo "digest=$D" >> "$GITHUB_OUTPUT"
+          echo "ref=${AR_IMAGE}@${D}" >> "$GITHUB_OUTPUT"
+
+      - name: Install cosign
+        uses: sigstore/cosign-installer@v3
+        with:
+          cosign-release: 'v2.4.1'
+
+      - name: Sign the image (keyless, OIDC)
+        env:
+          REF: ${{ steps.digest.outputs.ref }}
+        run: cosign sign --yes "$REF"
+
+      - name: SBOM (syft, SPDX JSON)
+        uses: anchore/sbom-action@v0
+        with:
+          image: ${{ steps.digest.outputs.ref }}
+          format: spdx-json
+          output-file: sbom.spdx.json
+          upload-artifact: true
+          artifact-name: local-agent-full-${{ needs.build.outputs.version }}.sbom.spdx.json
+
+      - name: Attach the SBOM as a signed attestation
+        env:
+          REF: ${{ steps.digest.outputs.ref }}
+        run: cosign attest --yes --type spdxjson --predicate sbom.spdx.json "$REF"
+
+      - name: Build and attach the provenance attestation (SLSA v1)
+        env:
+          REF: ${{ steps.digest.outputs.ref }}
+        run: |
+          set -euo pipefail
+          node -e '
+            const e = process.env;
+            const repoUrl = `https://github.com/${e.GITHUB_REPOSITORY}`;
+            const p = {
+              buildDefinition: {
+                buildType: `${repoUrl}/.github/workflows/build-byoc-image.yml`,
+                externalParameters: {
+                  workflow: { ref: e.GITHUB_REF, repository: repoUrl, path: ".github/workflows/build-byoc-image.yml" },
+                  dockerfile: "Dockerfile.full",
+                  version: e.VERSION
+                },
+                resolvedDependencies: [{ uri: `git+${repoUrl}@${e.GITHUB_REF}`, digest: { gitCommit: e.SOURCE_SHA } }]
+              },
+              runDetails: {
+                builder: { id: `${repoUrl}/actions/runner/github-hosted` },
+                metadata: { invocationId: `${repoUrl}/actions/runs/${e.GITHUB_RUN_ID}/attempts/${e.GITHUB_RUN_ATTEMPT}` }
+              }
+            };
+            require("fs").writeFileSync("provenance.json", JSON.stringify(p, null, 2));
+          '
+          cosign attest --yes --type slsaprovenance1 --predicate provenance.json "$REF"
+
+      - name: Verify signature and attestations
+        env:
+          REF: ${{ steps.digest.outputs.ref }}
+        run: |
+          set -euo pipefail
+          ID="https://github.com/${GITHUB_REPOSITORY}/.github/workflows/build-byoc-image.yml@${GITHUB_REF}"
+          ISS="https://token.actions.githubusercontent.com"
+          cosign verify --certificate-identity "$ID" --certificate-oidc-issuer "$ISS" "$REF" >/dev/null
+          for T in spdxjson slsaprovenance1; do
+            cosign verify-attestation --type "$T" --certificate-identity "$ID" --certificate-oidc-issuer "$ISS" "$REF" >/dev/null
+          done
+
+      - name: Summary
+        env:
+          REF: ${{ steps.digest.outputs.ref }}
+        run: |
+          {
+            echo "### BYOC agent image signed"
+            echo ""
+            echo "- \`$REF\`"
+            echo "- cosign keyless signature, SPDX SBOM and SLSA v1 provenance attached and verified"
+            echo ""
+            echo "Verify:"
+            echo ""
+            echo "\`cosign verify --certificate-identity-regexp '^https://github.com/${GITHUB_REPOSITORY}/' --certificate-oidc-issuer https://token.actions.githubusercontent.com $REF\`"
+          } >> "$GITHUB_STEP_SUMMARY"