deepdebug-local-agent 1.0.23 → 1.1.0

package/docs/releasing.md

@@ -0,0 +1,43 @@
+# Releasing the local agent
+
+Two artefacts are released: the npm package `deepdebug-local-agent` and the
+public BYOC image `local-agent-full`. Nothing here runs on a normal push.
+
+## npm package
+
+`.github/workflows/npm-publish.yml` runs on every push to `main` that touches
+`src/**`, `package.json` or `bin/**`, and bumps the **patch** version
+automatically (from the highest of the latest `v*` tag and `package.json`).
+That is right for routine fixes and wrong for a minor release: with
+`package.json` at `1.1.0` the automatic bump would publish `1.1.1`.
+
+To publish an exact version (for example `1.1.0`):
+
+1. Leave `package.json` as it is. Do **not** bump it in a PR (a push to `main`
+   would trigger the automatic patch bump).
+2. Actions → **Publish NPM Package** → *Run workflow* on `main`, input
+   `version` = `1.1.0`. The workflow validates `X.Y.Z`, requires it to be
+   greater than the highest existing tag and `package.json`, runs
+   `npm version 1.1.0`, publishes with provenance, then pushes the bump commit
+   and the `v1.1.0` tag.
+3. Left empty, the input keeps the old behaviour (automatic patch bump).
+
+Prerequisite (owner of the npm package): Trusted Publisher configured for
+`VISIONHAMMER/deepdebug-local-agent`, workflow `npm-publish.yml` (see the
+header of the workflow). Without it the publish step fails and no version is
+burned.
+
+Heads-up: merging any PR that changes `src/**` to `main` starts an automatic
+patch publish (for example `1.0.39`) once the Trusted Publisher exists. To
+release `1.1.0` as the next version, dispatch it before merging further
+`src/**` changes, or merge with `[skip ci]` in the commit message.
+
+## BYOC image (`local-agent-full`)
+
+Tags pushed by `npm-publish.yml` use `GITHUB_TOKEN` and do not trigger other
+workflows, so after the npm release run Actions → **Build BYOC Agent Image**
+on `main` with `version` = `1.1.0`
+(see `docs/byoc-agent-image.md`). Tick `supply_chain` to also sign the image
+(cosign keyless), attach the SBOM and the provenance, and verify them.
+For `v*` tag and release runs the same job runs when the repository variable
+`BYOC_SUPPLY_CHAIN` is `true`. Default: off.

package/docs/signed-commands.md

@@ -0,0 +1,163 @@
+# Signed and allow-listed commands — operator notes
+
+The platform (vh-api-gateway, visionhammer-agents) signs every command it sends
+to a local agent with an Ed25519 key, and the agent runs shell commands only
+from an allowlist. Both checks have three modes, `off | warn | enforce`. The
+default is `enforce` (signature: since 1.1.0; exec policy: since 1.0.35), and an
+unrecognised value also means `enforce`. `warn` verifies and logs without
+rejecting; use it only as an explicit, temporary opt-out
+(`LOCAL_AGENT_SIGNATURE_MODE=warn`) for an agent whose platform side does not
+sign yet. Without a listen address the agent also binds `127.0.0.1` unless a
+token (`LOCAL_AGENT_TOKEN` / `AGENT_SHARED_SECRET`) or Cloud Run is present.
+
+## Protocol v1
+
+HTTP headers on every platform → agent request:
+
+| Header | Value |
+|---|---|
+| `X-VH-Key-Id` | id of the signing key, for example `vh-2026-09` |
+| `X-VH-Timestamp` | unix epoch **seconds** |
+| `X-VH-Nonce` | 16–128 chars `[A-Za-z0-9_-]`, unique per request |
+| `X-VH-Tenant-Id` / `X-VH-Workspace-Id` | the tenant and workspace the platform acts for (`""` when unknown) |
+| `X-VH-Signature` | base64 Ed25519 signature over the canonical string |
+
+Canonical string (UTF-8, `\n`-joined, no trailing newline):
+
+```
+VH-AGENT-SIG-V1
+<METHOD upper-case>
+<raw path + "?" + raw query, as sent>
+<hex sha256 of the exact body bytes (sha256("") when empty)>
+<tenantId>
+<workspaceId>
+<timestamp>
+<nonce>
+```
+
+Golden vector (all three implementations test against it): method `post`, path
+`/workspace/exec?x=1`, body `{}`, tenant `t`, workspace `w`, timestamp
+`1790000000`, nonce `abcdefghijklmnop` →
+`VH-AGENT-SIG-V1\nPOST\n/workspace/exec?x=1\n44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\nt\nw\n1790000000\nabcdefghijklmnop`.
+
+WebSocket tunnel: the envelope gains `paramsRaw` (the exact JSON the platform
+signed) and `sig: {keyId, timestamp, nonce, tenantId, workspaceId, signature}`.
+Method is `WS`, path is the command name, body is `paramsRaw`. A verified
+envelope runs `JSON.parse(paramsRaw)`; the unsigned `params` copy is used only
+by older agents, or in `warn`/`off` mode when the envelope is not signed.
+
+The agent rejects (in `enforce`) with 401 when:
+
+* the request has no signature, or the key id is unknown;
+* the signature does not verify;
+* `|now − timestamp| > 60 s`;
+* the nonce was already used (in-memory LRU, TTL 120 s, 100k entries);
+* the tenant does not match the agent's identity (`LOCAL_AGENT_TENANT_ID` →
+  `TENANT_ID` → `~/.deepdebug/config.json`). If the signed workspace is
+  non-empty, it must match `LOCAL_AGENT_WORKSPACE_ID` / `WORKSPACE_ID` (set
+  `LOCAL_AGENT_REQUIRE_WORKSPACE=true` to require it on every call). A shared
+  operator agent with no identity accepts any signed tenant.
+
+`X-Agent-Token` (`LOCAL_AGENT_TOKEN`) is still checked first, as the second
+factor. `GET /health` and `/metrics` stay public.
+
+## Exec allowlist
+
+`/workspace/exec`, `/workspace/run`, `/mcp/execute-command` and
+`/setup/run-command` accept a command only when every segment (`&&`, `||`,
+`;`, `|`) belongs to one of these families: read-only git; package-manager
+install, test, build or lint for an ecosystem detected in the workspace (npm,
+yarn, pnpm, mvn/mvnw, gradle/gradlew, pip, poetry, uv, go, cargo, dotnet); test
+runners; linters; file read/write inside the workspace root; or `cd` inside
+the root. `$VAR`, `$(...)`, backticks, subshells, `&`, here-docs, process
+substitution and paths outside the root are refused.
+
+Hardening rules:
+
+* **Wrappers are validated recursively.** `env`, `time`, `nice`, `timeout`,
+  `c8`, `nyc`, `npx`, `npm/pnpm exec`, `poetry run` and `uv run` wrap another
+  command, and that command must pass the same policy. `xargs` is refused.
+  Interpreter eval (`node -e/-p`, `python -c`, `sh/bash -c`) is never
+  allowed. Test runners refuse inline JSON config.
+* **Paths are realpath-resolved.** Every non-flag token that is path-like or
+  exists on disk, every `--opt=value`, every redirect target and every
+  `cd`/`git -C` directory is resolved with symlinks followed and must stay
+  inside the root. An unquoted glob may use wildcards only in its last segment,
+  and none of the symlinks it can match may point outside.
+* **Protected files.** A redirect, `tee`, `cp`, `mv`, `rm`, `touch`, `chmod`
+  or `sort -o` is refused on these paths: `.git/**`, hook dirs (`.husky`,
+  `.githooks`), and build/test config that executes code. That includes
+  `package.json`, `.npmrc`, lockfiles, `Makefile`, `pom.xml`, `*.gradle*`,
+  `gradle/wrapper`, `setup.py`, `pyproject.toml`, `conftest.py`, and
+  `*.config.js` for jest, vitest, eslint and similar tools. Those files change
+  only through the signed apply-patch tool.
+* **No write-then-execute.** A command string that writes files may not run a
+  package-manager, test or lint tool in a later segment. The source of truth is
+`src/utils/exec-policy.js`; the reason is returned in the 403 body.
+
+Two exceptions:
+
+1. **Human approval (REQUIRE_HUMAN).** An `X-VH-Approval` header (or
+   `approvalToken` in the body) holding a PolicyGate token
+   `vhapr1.<keyId>.<b64url payload>.<b64url sig>`. It is signed with the same
+   platform key over `VH-HUMAN-APPROVAL-V1\n<keyId>\n<payload segment>`. The
+   token is bound to the SHA-256 of the exact command, the tenant and the
+   workspace. It lives at most 15 minutes and can be used once.
+2. **Platform-authored tools.** A body with `commandOrigin: "platform"` and a
+   known `tool` (`create_branch`, `git_commit`, `git_push`, `close_pr`,
+   `delete_branch`, `publish_scope`, `current_branch`). It is honoured only
+   when the request signature verified. The model's free-form `run_command`
+   never carries it.
+
+## Rollout
+
+1. **Generate the keypair** on a trusted workstation. Keep the private key
+   off disk after upload.
+   ```sh
+   openssl genpkey -algorithm ed25519 -out local-agent-signing-key.pem
+   openssl pkey -in local-agent-signing-key.pem -pubout -outform DER | base64   # SPKI, 60 chars
+   ```
+2. **Store the private key** in Secret Manager as `local-agent-signing-key`
+   (PKCS#8 PEM) in `visionhammer`, and grant `secretAccessor` to the gateway
+   and agent2 runtime service accounts.
+   ```sh
+   gcloud secrets create local-agent-signing-key --replication-policy=automatic --data-file=local-agent-signing-key.pem
+   ```
+3. **Mount it on the signers.** On gateway and software-engineer (agent2)
+   Cloud Run, set
+   `--set-secrets=LOCAL_AGENT_SIGNING_KEY=local-agent-signing-key:latest` and
+   `--update-env-vars=LOCAL_AGENT_SIGNING_KEY_ID=vh-2026-09`. Without the key
+   they log once and send unsigned requests, as before. Remember
+   `--vpc-egress=private-ranges-only` on `run services update`.
+4. **Give the agents the public key:**
+   * Image default: add `{"keyId":"vh-2026-09","publicKey":"<SPKI b64>"}` to
+     `src/config/trusted-signing-keys.json` and cut a new image.
+   * BYOC provisioning: set `LOCAL_AGENT_SIGNING_PUBLIC_KEYS=vh-2026-09=<SPKI b64>`
+     on the gateway. `CloudEngineerService` copies it, along with
+     `LOCAL_AGENT_SIGNATURE_MODE` and `LOCAL_AGENT_EXEC_POLICY_MODE`, into
+     every ACI/Cloud Run agent it provisions.
+   * Operator QA agent: set the same env on `deepdebug-local-agent-qa`.
+5. **Soak in `warn`.** Watch the logs for `[agent-sig] WARN` and
+   `[exec-policy] WARN`. The logs are rate-limited, one line per reason and
+   path per minute. Expect zero signature warnings from updated platform
+   callers. Every exec warning is a command that `enforce` would block.
+6. **Flip to enforce** per agent: `LOCAL_AGENT_SIGNATURE_MODE=enforce` once
+   the signature warnings are zero. Set the gateway env to `enforce` so new
+   BYOC agents start enforced. Roll back by setting `warn` again, with no
+   redeploy of the platform.
+
+   Since 1.0.35 (security review 2026-10-11) the **exec policy defaults to
+   `enforce`**: a command outside the allowlist is refused unless it carries a
+   PolicyGate approval token or is a signed platform tool command. Set
+   `LOCAL_AGENT_EXEC_POLICY_MODE=warn` explicitly on an agent that still needs
+   the soak. In the same release the HTTP perimeter stopped defaulting to
+   `compat`: `AGENT_SHARED_SECRET` is enforced as `X-Agent-Token`, and an agent
+   with no token outside Cloud Run only answers loopback callers (the reverse
+   WS tunnel). `LOCAL_AGENT_AUTH=compat` is the explicit, logged opt-out.
+
+### Key rotation
+
+Add the new public key next to the old one (`kid1=...,kid2=...` / two file
+entries) on every agent. Then switch `LOCAL_AGENT_SIGNING_KEY` and
+`LOCAL_AGENT_SIGNING_KEY_ID` on the signers to the new version. After a day,
+remove the old public key. Approval tokens use the same keys.

package/env.example

@@ -39,3 +39,33 @@ LOG_LEVEL=info
 
 # For on-premise DeepDebug server
 # DEEPDEBUG_API_URL=https://deepdebug.internal.company.com
+
+# ─── Security (audit 2026-09) ───
+# LOCAL_AGENT_TOKEN: when set, every route except GET /health and /metrics
+# requires the X-Agent-Token header. Set it only once every caller (gateway,
+# agents) sends the header. AGENT_SHARED_SECRET (injected by the gateway on
+# BYOC ACI agents) is enforced the same way when LOCAL_AGENT_TOKEN is not set.
+# With neither (and outside Cloud Run) the agent is loopback-only: it binds
+# 127.0.0.1 and refuses non-loopback callers. LOCAL_AGENT_BIND_HOST overrides.
+# LOCAL_AGENT_TOKEN=
+# Extra browser origins allowed by CORS (comma-separated, exact match).
+# LOCAL_AGENT_CORS_ORIGINS=
+# Re-enable /setup/run-command, /setup/install-tool, /setup/run-auth-command.
+# LOCAL_AGENT_ENABLE_SETUP_COMMANDS=false
+# LOCAL_AGENT_AUTH=loopback  -> accept loopback callers only (laptop + WS tunnel)
+# LOCAL_AGENT_AUTH=off       -> emergency opt-out (NOT recommended)
+
+# ─── Signed + allow-listed commands (docs/signed-commands.md) ───
+# Trusted platform public keys (Ed25519), keyId=base64 (raw 32-byte or SPKI DER).
+# Several entries = rotation window. The image default lives in
+# src/config/trusted-signing-keys.json.
+# LOCAL_AGENT_SIGNING_PUBLIC_KEYS=vh-2026-09=MCowBQYDK2VwAyEA...
+# off | warn | enforce (default) — verify X-VH-Signature on every command.
+# Set warn only as a loud, temporary opt-out for a platform that does not sign yet.
+# LOCAL_AGENT_SIGNATURE_MODE=enforce
+# off | warn | enforce (default) — shell allowlist on exec endpoints.
+# LOCAL_AGENT_EXEC_POLICY_MODE=enforce
+# Identity the signature must match (defaults: TENANT_ID / WORKSPACE_ID).
+# LOCAL_AGENT_TENANT_ID=
+# LOCAL_AGENT_WORKSPACE_ID=
+# LOCAL_AGENT_REQUIRE_WORKSPACE=false

package/helm/Chart.yaml

@@ -2,8 +2,8 @@ apiVersion: v2
 name: deepdebug-agent
 description: DeepDebug Local Agent for enterprise code debugging and analysis
 type: application
-version: 1.0.0
-appVersion: "1.0.0"
+version: 1.1.0
+appVersion: "1.1.0"
 keywords:
   - debugging
   - ai

package/helm/templates/deployment.yaml

@@ -38,14 +38,24 @@ spec:
               value: "production"
             - name: PORT
               value: "5055"
-            - name: DEEPDEBUG_API_URL
+            # Names aligned to what src/server.js actually reads (server.js frozen):
+            # GATEWAY_URL (server.js:73), TENANT_ID (:7505), WORKSPACE_ROOT (:637).
+            - name: GATEWAY_URL
               value: {{ .Values.config.apiUrl | quote }}
-            - name: DEEPDEBUG_TENANT_ID
+            - name: TENANT_ID
               valueFrom:
                 secretKeyRef:
                   name: {{ include "deepdebug-agent.fullname" . }}-secret
                   key: tenant-id
-            - name: DEEPDEBUG_WORKSPACE_PATH
+            # Without a token the agent is loopback-only (bind 127.0.0.1) and the
+            # kubelet probes would fail; with it, every route but /health and
+            # /metrics needs X-Agent-Token.
+            - name: LOCAL_AGENT_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "deepdebug-agent.fullname" . }}-secret
+                  key: agent-token
+            - name: WORKSPACE_ROOT
               value: {{ .Values.config.workspacePath | quote }}
             - name: LOG_LEVEL
               value: {{ .Values.config.logLevel | quote }}

package/helm/templates/networkpolicy.yaml

@@ -0,0 +1,22 @@
+{{- if .Values.networkPolicy.enabled }}
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: {{ include "deepdebug-agent.fullname" . }}
+  labels:
+    {{- include "deepdebug-agent.labels" . | nindent 4 }}
+spec:
+  podSelector:
+    matchLabels:
+      {{- include "deepdebug-agent.selectorLabels" . | nindent 6 }}
+  policyTypes:
+    - Ingress
+  {{- with .Values.networkPolicy.allowFrom }}
+  ingress:
+    - from:
+        {{- toYaml . | nindent 8 }}
+      ports:
+        - protocol: TCP
+          port: 5055
+  {{- end }}
+{{- end }}

package/helm/templates/secret.yaml

@@ -7,3 +7,4 @@ metadata:
 type: Opaque
 data:
   tenant-id: {{ .Values.config.tenantId | b64enc | quote }}
+  agent-token: {{ required "config.agentToken is required (LOCAL_AGENT_TOKEN: the agent refuses remote callers without it)" .Values.config.agentToken | b64enc | quote }}

package/helm/values.yaml

@@ -27,6 +27,9 @@ replicaCount: 1
 # ─────────────────────────────────────────
 config:
   tenantId: ""  # Required: Your tenant ID
+  # Required: shared secret for X-Agent-Token (LOCAL_AGENT_TOKEN). Pass it with
+  # --set config.agentToken=$(openssl rand -hex 32); never commit it.
+  agentToken: ""
   apiUrl: "https://api.deepdebug.ai"
   logLevel: "info"
   
@@ -117,20 +120,6 @@ readinessProbe:
   timeoutSeconds: 5
   failureThreshold: 3
 
-# ─────────────────────────────────────────
-# Network Policies (Enterprise)
-# ─────────────────────────────────────────
-networkPolicy:
-  enabled: true
-  # Allow egress only to DeepDebug API
-  egressRules:
-    - to:
-        - ipBlock:
-            cidr: 0.0.0.0/0
-      ports:
-        - protocol: TCP
-          port: 443
-
 # ─────────────────────────────────────────
 # Pod Disruption Budget
 # ─────────────────────────────────────────
@@ -160,3 +149,13 @@ podAnnotations:
   prometheus.io/scrape: "true"
   prometheus.io/port: "5055"
   prometheus.io/path: "/metrics"
+
+# ─────────────────────────────────────────
+# Network Policy (security review 2026-10-11, C1)
+# ─────────────────────────────────────────
+# The agent reaches the platform over an OUTBOUND tunnel, so it needs no
+# inbound traffic except kubelet probes. Default: deny all ingress except the
+# sources listed in allowFrom (NetworkPolicy peers, e.g. a podSelector).
+networkPolicy:
+  enabled: true
+  allowFrom: []

package/mcp-server.js

@@ -6,6 +6,7 @@ import {
     ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import path from "path";
+import { createAuthMiddleware } from "./src/utils/agent-auth.js";
 import { spawn } from "child_process";
 import { exists, listRecursive, readFile, writeFile, stat } from "./fs-utils.js";
 import { detectProject, readText } from "./detectors.js";
@@ -454,6 +455,8 @@ function errorResponse(message) {
 export async function startMCPHttpServer(wsManager, port = 5056) {
     const express = (await import("express")).default;
     const app = express();
+    // SECURITY: execute_command runs `sh -c`; same auth perimeter as the main API.
+    app.use(createAuthMiddleware());
 
     const server = createMCPServer(wsManager);
 
@@ -522,7 +525,7 @@ export async function startMCPHttpServer(wsManager, port = 5056) {
         }
     });
 
-    app.listen(port, () => {
+    app.listen(port, process.env.MCP_BIND_HOST || "127.0.0.1", () => {
         console.log(`🧠 DeepDebug MCP Server listening on http://localhost:${port}`);
         console.log(`   SSE: http://localhost:${port}/sse`);
         console.log(`   REST: http://localhost:${port}/tool/{toolName}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepdebug-local-agent",
-  "version": "1.0.23",
+  "version": "1.1.0",
   "description": "DeepDebug Local Agent - AI-powered code debugging assistant",
   "private": false,
   "type": "module",
@@ -41,9 +41,14 @@
     "js-yaml": "^4.1.0",
     "pg": "^8.20.0",
     "pidusage": "^3.0.2",
+    "pino": "^10.3.1",
+    "prom-client": "^15.1.3",
     "properties-reader": "^2.3.0",
     "ssh2": "^1.16.0",
     "strip-ansi": "^7.1.0",
+    "tree-sitter": "^0.22.4",
+    "tree-sitter-swift": "^0.7.1",
+    "typescript": "^5.9.3",
     "unidiff": "^1.0.2",
     "ws": "^8.18.0"
   },
@@ -75,10 +80,10 @@
   "license": "Proprietary",
   "repository": {
     "type": "git",
-    "url": "https://github.com/williambella/deepdebug-local-agent.git"
+    "url": "git+https://github.com/VISIONHAMMER/deepdebug-local-agent.git"
   },
-  "homepage": "https://deepdebug.ai",
+  "homepage": "https://visionhammer.io",
   "bugs": {
-    "url": "https://github.com/williambella/deepdebug-local-agent/issues"
+    "url": "https://github.com/VISIONHAMMER/deepdebug-local-agent/issues"
   }
 }

package/scripts/upgrade-observability-push.sh

@@ -0,0 +1,227 @@
+#!/usr/bin/env bash
+# Upgrade an installed DeepDebug client observability bundle so that:
+#   1. Alloy also pushes the Docker log stream to VisionHammer
+#      (OTLP/HTTP JSON -> <gateway>/api/v1/webhooks/logs/otlp, Bearer <trigger secret>),
+#      which feeds Live logs and the services list;
+#   2. Alertmanager sends the trigger secret as a Bearer header instead of ?s= in the URL.
+#
+# Safe to re-run (idempotent). Backs up both files, validates the new configs with the
+# same images the stack runs, restarts only alloy + alertmanager, and rolls back on failure.
+#
+# Usage (on the server, as a user that can run docker):
+#   sudo bash upgrade-observability-push.sh            # apply
+#   sudo bash upgrade-observability-push.sh --dry-run  # show what would change
+# Optional env:
+#   INSTALL_DIR=/path/to/deepdebug-observability   (auto-detected otherwise)
+#   GATEWAY_URL=https://api-qa.visionhammer.io     (read from alertmanager.yml otherwise)
+set -euo pipefail
+
+DRY_RUN=0
+[[ "${1:-}" == "--dry-run" ]] && DRY_RUN=1
+
+log()  { printf '\033[1;34m[upgrade]\033[0m %s\n' "$*"; }
+warn() { printf '\033[1;33m[upgrade]\033[0m %s\n' "$*" >&2; }
+die()  { printf '\033[1;31m[upgrade]\033[0m %s\n' "$*" >&2; exit 1; }
+mask() { local s="$1"; printf '%s...%s' "${s:0:8}" "${s: -4}"; }
+
+command -v docker >/dev/null || die "docker not found"
+docker compose version >/dev/null 2>&1 || die "docker compose plugin not found"
+command -v curl >/dev/null || die "curl not found"
+
+# ---------------------------------------------------------------- locate the stack
+find_install_dir() {
+  if [[ -n "${INSTALL_DIR:-}" ]]; then echo "$INSTALL_DIR"; return; fi
+  # 1) the running compose project
+  local cfg
+  cfg=$(docker compose ls --all --format json 2>/dev/null \
+        | tr '{' '\n' | grep '"Name":"deepdebug-observability"' \
+        | sed -n 's/.*"ConfigFiles":"\([^",]*\).*/\1/p' | head -1 || true)
+  if [[ -n "$cfg" && -f "$cfg" ]]; then dirname "$cfg"; return; fi
+  # 2) default provision paths
+  local d
+  for d in "$HOME/.deepdebug/observability/deepdebug-observability" \
+           /root/.deepdebug/observability/deepdebug-observability \
+           /home/*/.deepdebug/observability/deepdebug-observability; do
+    [[ -f "$d/docker-compose.yml" ]] && { echo "$d"; return; }
+  done
+}
+
+DIR=$(find_install_dir || true)
+[[ -n "$DIR" && -f "$DIR/docker-compose.yml" ]] \
+  || die "observability bundle not found; set INSTALL_DIR=/path/to/deepdebug-observability"
+ALLOY="$DIR/alloy/config.alloy"
+AM="$DIR/alertmanager/alertmanager.yml"
+[[ -f "$ALLOY" ]] || die "missing $ALLOY"
+[[ -f "$AM" ]] || die "missing $AM"
+log "bundle: $DIR"
+
+# ---------------------------------------------------------------- secret + gateway
+SECRET=$(grep -oE 'vht_[A-Za-z0-9._-]+' "$AM" | head -1 || true)
+[[ -n "$SECRET" ]] || die "no vht_ trigger secret found in $AM"
+if [[ -z "${GATEWAY_URL:-}" ]]; then
+  GATEWAY_URL=$(grep -oE "https?://[^/'\" ]+" "$AM" | head -1 || true)
+fi
+GATEWAY_URL="${GATEWAY_URL%/}"
+[[ "$GATEWAY_URL" =~ ^https?://[A-Za-z0-9.:-]+$ ]] || die "could not determine GATEWAY_URL (set it explicitly)"
+log "gateway: $GATEWAY_URL   secret: $(mask "$SECRET")"
+case "$GATEWAY_URL" in
+  https://api-qa.visionhammer.io|https://api.visionhammer.io) ;;
+  *) warn "gateway is not api-qa/api.visionhammer.io; the push endpoint only exists on the current gateway." ;;
+esac
+
+# ---------------------------------------------------------------- 1. probe the endpoint
+# An empty OTLP batch authenticates and registers the SELF_HOSTED log source without
+# writing any log line.
+code=$(curl -sS -o /tmp/vh-otlp-probe.$$ -w '%{http_code}' -m 20 \
+  -X POST "$GATEWAY_URL/api/v1/webhooks/logs/otlp" \
+  -H "Authorization: Bearer $SECRET" -H 'Content-Type: application/json' \
+  --data '{"resourceLogs":[]}' || echo 000)
+case "$code" in
+  200) log "push endpoint OK (200)" ;;
+  401) die "push endpoint rejected the secret (401): the trigger source is disabled or the secret changed" ;;
+  404) die "push endpoint not deployed yet on $GATEWAY_URL (404); retry after the gateway deploy" ;;
+  *)   die "push endpoint probe failed (HTTP $code): $(head -c 300 /tmp/vh-otlp-probe.$$ 2>/dev/null)" ;;
+esac
+rm -f /tmp/vh-otlp-probe.$$
+
+# ---------------------------------------------------------------- 2. build new configs
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+cp "$ALLOY" "$TMP/config.alloy"
+cp "$AM" "$TMP/alertmanager.yml"
+
+alloy_changed=0
+if grep -q 'otelcol.exporter.otlphttp "visionhammer"' "$TMP/config.alloy"; then
+  log "alloy: push already configured"
+else
+  # loki.process "default" must also forward to the OTLP receiver.
+  n=$(grep -c 'forward_to = \[loki.write.default.receiver\]' "$TMP/config.alloy" || true)
+  [[ "$n" == "1" ]] || die "alloy config does not look like the stock bundle (expected one 'forward_to = [loki.write.default.receiver]', found $n); edit $ALLOY by hand"
+  sed -i 's|forward_to = \[loki.write.default.receiver\]|forward_to = [loki.write.default.receiver, otelcol.receiver.loki.visionhammer.receiver]|' "$TMP/config.alloy"
+  cat >> "$TMP/config.alloy" <<EOF
+
+// ---- push to VisionHammer: Loki entries -> OTLP logs (labels become attributes) ----
+otelcol.receiver.loki "visionhammer" {
+  output {
+    logs = [otelcol.processor.batch.visionhammer.input]
+  }
+}
+
+otelcol.processor.batch "visionhammer" {
+  send_batch_size     = 500
+  send_batch_max_size = 2000
+  timeout             = "5s"
+  output {
+    logs = [otelcol.exporter.otlphttp.visionhammer.input]
+  }
+}
+
+otelcol.exporter.otlphttp "visionhammer" {
+  client {
+    endpoint    = "$GATEWAY_URL"
+    compression = "gzip"
+    headers     = { "Authorization" = "Bearer $SECRET" }
+  }
+  encoding      = "json"
+  logs_endpoint = "$GATEWAY_URL/api/v1/webhooks/logs/otlp"
+}
+EOF
+  alloy_changed=1
+  log "alloy: push blocks added"
+fi
+
+am_changed=0
+if grep -q 'webhooks/alertmanager?s=' "$TMP/alertmanager.yml"; then
+  # Drop ?s=... from the URL and add http_config.authorization at the same indent
+  # as the url key of that list item.
+  # Each receiver keeps ITS OWN secret (a bundle may post to QA and PROD gateways,
+  # each registered with a different vht_ secret).
+  awk '
+    /webhooks\/alertmanager\?s=/ {
+      match($0, /vht_[A-Za-z0-9._-]+/)
+      secret = substr($0, RSTART, RLENGTH)
+      line = $0
+      sub(/\?s=[^'"'"'" ]*/, "", line)
+      print line
+      match($0, /^[ ]*(- )?/)
+      ind = RLENGTH
+      pad = sprintf("%" ind "s", "")
+      print pad "http_config:"
+      print pad "  authorization:"
+      print pad "    type: Bearer"
+      print pad "    credentials: '"'"'" secret "'"'"'"
+      next
+    }
+    { print }
+  ' "$TMP/alertmanager.yml" > "$TMP/alertmanager.yml.new"
+  mv "$TMP/alertmanager.yml.new" "$TMP/alertmanager.yml"
+  am_changed=1
+  log "alertmanager: secret moved from ?s= to Authorization header"
+else
+  log "alertmanager: already uses header auth (or a custom config); left unchanged"
+fi
+
+if [[ $alloy_changed == 0 && $am_changed == 0 ]]; then
+  log "nothing to do"; exit 0
+fi
+
+# Mask every vht_ secret in printed output, not only the first one.
+mask_all() { sed -E 's/(vht_[A-Za-z0-9]{4})[A-Za-z0-9._-]*([A-Za-z0-9._-]{4})/\1...\2/g'; }
+show_diff() { diff -u "$1" "$2" | mask_all || true; }
+[[ $alloy_changed == 1 ]] && show_diff "$ALLOY" "$TMP/config.alloy"
+[[ $am_changed == 1 ]] && show_diff "$AM" "$TMP/alertmanager.yml"
+
+if [[ $DRY_RUN == 1 ]]; then log "dry run: nothing written"; exit 0; fi
+
+# ---------------------------------------------------------------- 3. validate with the stack's images
+image_of() { grep -E "^\s*image:\s*.*$1" "$DIR/docker-compose.yml" | head -1 | awk '{print $2}'; }
+ALLOY_IMG=$(image_of 'grafana/alloy'); ALLOY_IMG=${ALLOY_IMG:-grafana/alloy:v1.3.1}
+AM_IMG=$(image_of 'prom/alertmanager'); AM_IMG=${AM_IMG:-prom/alertmanager:v0.27.0}
+
+if [[ $alloy_changed == 1 ]]; then
+  docker run --rm -v "$TMP/config.alloy:/c/config.alloy:ro" "$ALLOY_IMG" fmt /c/config.alloy >/dev/null \
+    || die "new alloy config failed validation; nothing changed"
+  log "alloy config valid ($ALLOY_IMG)"
+fi
+if [[ $am_changed == 1 ]]; then
+  docker run --rm --entrypoint amtool -v "$TMP/alertmanager.yml:/c/am.yml:ro" "$AM_IMG" check-config /c/am.yml >/dev/null \
+    || die "new alertmanager config failed validation; nothing changed"
+  log "alertmanager config valid ($AM_IMG)"
+fi
+
+# ---------------------------------------------------------------- 4. apply + restart
+STAMP=$(date +%Y%m%d-%H%M%S)
+cp -p "$ALLOY" "$ALLOY.bak-$STAMP"
+cp -p "$AM" "$AM.bak-$STAMP"
+log "backups: *.bak-$STAMP"
+# Overwrite in place (keeps owner/permissions and the bind-mounted inode semantics on restart).
+cat "$TMP/config.alloy" > "$ALLOY"
+cat "$TMP/alertmanager.yml" > "$AM"
+
+rollback() {
+  warn "rolling back to *.bak-$STAMP"
+  cat "$ALLOY.bak-$STAMP" > "$ALLOY"
+  cat "$AM.bak-$STAMP" > "$AM"
+  (cd "$DIR" && docker compose restart alloy alertmanager >/dev/null 2>&1) || true
+  die "$1"
+}
+
+(cd "$DIR" && docker compose restart alloy alertmanager) || rollback "restart failed"
+
+# ---------------------------------------------------------------- 5. verify
+log "waiting 30s for alloy to ship its first batch..."
+sleep 30
+running=$(cd "$DIR" && docker compose ps --status running --services 2>/dev/null || true)
+grep -qx alloy <<<"$running" || rollback "alloy is not running after the restart"
+grep -qx alertmanager <<<"$running" || rollback "alertmanager is not running after the restart"
+
+errs=$(cd "$DIR" && docker compose logs --since 40s alloy 2>&1 \
+       | grep -iE 'level=error|Exporting failed|permanent error' | grep -i 'visionhammer\|otlphttp' || true)
+if [[ -n "$errs" ]]; then
+  warn "alloy reported export errors:"
+  mask_all <<<"$errs" | tail -5 >&2
+  rollback "alloy cannot push to $GATEWAY_URL"
+fi
+
+log "done. Logs should appear in VisionHammer > Live logs within ~1-2 minutes."
+log "to undo: cp $ALLOY.bak-$STAMP $ALLOY; cp $AM.bak-$STAMP $AM; (cd $DIR && docker compose restart alloy alertmanager)"