deepdebug-local-agent 1.2.0 → 1.4.0

package/.github/workflows/deploy-gcp.yml

@@ -1,4 +1,8 @@
-# Deploy local-agent (Node) to GCP Cloud Run (visionhammer) via WIF.
+# Deploy local-agent (Node) to GCP Cloud Run via WIF.
+# QA: project visionhammer (europe-west1 since Plano QA Alvo EU 2026-10-29, same
+# conventions as PROD: deploy-local-agent@ SA of the nonprod project, EU registry,
+# immutable sha-<commit> tag, digest-pinned image-only deploy). PROD: project
+# visionhammer-prod (europe-west1), own WIF pool/deploy SA, digest-pinned deploy.
 # Manual-only: this repo has no develop branch and several active feature
 # branches, so deploys are triggered on demand from the Actions tab. Choose the
 # environment input. Replaces the insptechai Cloud Build path.
@@ -23,14 +27,18 @@ permissions:
   id-token: write
 
 env:
-  GCP_PROJECT: visionhammer
-  # EU migration (PLANO-MIGRACAO-EU-PROD.md): PROD moves to europe-west1. The
-  # region comes from repo variables (PROD_REGION / QA_REGION); today's value
-  # stays the default, so nothing changes until the variable is set.
-  GCP_REGION: ${{ inputs.environment == 'prod' && (vars.PROD_REGION || 'us-central1') || (vars.QA_REGION || 'us-central1') }}
-  WIF_PROVIDER: projects/1009366917257/locations/global/workloadIdentityPools/github-pool/providers/github-provider
-  DEPLOYER_SA: github-deployer@visionhammer.iam.gserviceaccount.com
-  AR_IMAGE: us-central1-docker.pkg.dev/visionhammer/visionhammer-docker/local-agent
+  # PROD lives in visionhammer-prod / europe-west1 (hardcoded: no repo variable
+  # can silently repoint PROD). QA lives in visionhammer / europe-west1 (QA_REGION
+  # only as an escape hatch) with its own deploy SA and the EU registry. The QA
+  # WIF provider is a repo variable so the pool/provider adopted by vh-infra
+  # (live/nonprod/_project) can be flipped without a commit:
+  #   gh variable set QA_WIF_PROVIDER --body projects/1009366917257/locations/global/workloadIdentityPools/<pool>/providers/<provider>
+  GCP_PROJECT: ${{ inputs.environment == 'prod' && 'visionhammer-prod' || 'visionhammer' }}
+  GCP_REGION: ${{ inputs.environment == 'prod' && 'europe-west1' || (vars.QA_REGION || 'europe-west1') }}
+  WIF_PROVIDER: ${{ inputs.environment == 'prod' && 'projects/616585643354/locations/global/workloadIdentityPools/github/providers/github-actions' || (vars.QA_WIF_PROVIDER || 'projects/1009366917257/locations/global/workloadIdentityPools/vh-infra/providers/github-actions') }}
+  DEPLOYER_SA: ${{ inputs.environment == 'prod' && 'deploy-local-agent@visionhammer-prod.iam.gserviceaccount.com' || 'deploy-local-agent@visionhammer.iam.gserviceaccount.com' }}
+  AR_HOST: europe-west1-docker.pkg.dev
+  AR_IMAGE: ${{ inputs.environment == 'prod' && 'europe-west1-docker.pkg.dev/visionhammer-prod/vh-docker/local-agent' || 'europe-west1-docker.pkg.dev/visionhammer/visionhammer-docker-eu/local-agent' }}
 
 jobs:
   deploy:
@@ -51,10 +59,12 @@ jobs:
             fi
             echo "service=deepdebug-local-agent"    >> "$GITHUB_OUTPUT"
             echo "tag=prod-${GITHUB_SHA::8}"         >> "$GITHUB_OUTPUT"
+            echo "image_tag=sha-${GITHUB_SHA}"       >> "$GITHUB_OUTPUT"
             echo "traffic=canary"                    >> "$GITHUB_OUTPUT"
           else
             echo "service=deepdebug-local-agent-qa" >> "$GITHUB_OUTPUT"
             echo "tag=qa-${GITHUB_SHA::8}"           >> "$GITHUB_OUTPUT"
+            echo "image_tag=sha-${GITHUB_SHA}"       >> "$GITHUB_OUTPUT"
             echo "traffic=live"                      >> "$GITHUB_OUTPUT"
           fi
 
@@ -68,35 +78,57 @@ jobs:
         uses: google-github-actions/setup-gcloud@v2
 
       - name: Configure Docker for Artifact Registry
-        run: gcloud auth configure-docker us-central1-docker.pkg.dev --quiet
+        run: gcloud auth configure-docker "$AR_HOST" --quiet
 
-      - name: Build & push image (multi-stage Node Dockerfile)
+      # QA and PROD: immutable tag sha-<full SHA> (a re-run of the same SHA fails
+      # the push by design); the deploy references the pushed DIGEST, not the tag.
+      - name: Build & push image (immutable sha tag, resolve digest)
         run: |
-          IMG="${AR_IMAGE}:${{ steps.vars.outputs.tag }}"
-          docker build --platform=linux/amd64 -t "$IMG" .
-          docker push "$IMG"
-          echo "IMG=$IMG" >> "$GITHUB_ENV"
+          TAGGED="${AR_IMAGE}:${{ steps.vars.outputs.image_tag }}"
+          docker build --platform=linux/amd64 -t "$TAGGED" .
+          docker push "$TAGGED"
+          DIGEST="$(docker inspect --format='{{index .RepoDigests 0}}' "$TAGGED")"
+          case "$DIGEST" in
+            "${AR_IMAGE}@sha256:"*) ;;
+            *) echo "::error::Unexpected digest reference: $DIGEST"; exit 1 ;;
+          esac
+          echo "IMG=$DIGEST" >> "$GITHUB_ENV"
 
-      - name: Deploy to Cloud Run (image only; preserves env/secrets)
+      - name: Deploy to Cloud Run (QA, image only by digest, live)
+        if: inputs.environment != 'prod'
         run: |
-          # PROD lands at 0% traffic behind a tag (canary); verify the tagged
-          # URL, then promote with `gcloud run services update-traffic`.
-          # QA keeps deploying live. Mirrors vh-api-gateway deploy-gcp.yml.
+          # QA (europe-west1) keeps deploying live. The service is Terraform-owned
+          # (vh-infra live/nonprod/qa/20-services: env, secrets, Filestore mount,
+          # min=max=1), so this is an image-only `services update` on the `app`
+          # container: never --set-env-vars / --update-env-vars / scaling flags.
+          # Service-level flags BEFORE --container.
           #
           # --vpc-egress is pinned: gcloud 572 flipped the template to
           # all-traffic on an image-only update; with no Cloud NAT that cuts
           # the service's internet egress.
-          EXTRA=""
-          if [ "${{ steps.vars.outputs.traffic }}" = "canary" ]; then
-            EXTRA="--no-traffic --tag ${{ steps.vars.outputs.tag }}"
-          fi
-          gcloud run deploy "${{ steps.vars.outputs.service }}" \
+          gcloud run services update "${{ steps.vars.outputs.service }}" \
+            --project "$GCP_PROJECT" \
+            --region "$GCP_REGION" \
+            --vpc-egress=private-ranges-only \
+            --quiet \
+            --container=app \
+            --image="$IMG"
+
+      # PROD: `services update` with image only (Terraform owns env/secrets, so
+      # no --set-env-vars). Singleton service (min=max=1): the revision lands at
+      # 0% behind a tag; promote with `gcloud run services update-traffic`
+      # (--to-revisions) once the tagged revision is verified.
+      - name: Deploy to Cloud Run (PROD, digest, canary)
+        if: inputs.environment == 'prod'
+        run: |
+          gcloud run services update "${{ steps.vars.outputs.service }}" \
             --image "$IMG" \
             --project "$GCP_PROJECT" \
             --region "$GCP_REGION" \
             --vpc-egress=private-ranges-only \
-            $EXTRA \
+            --no-traffic --tag "${{ steps.vars.outputs.tag }}" \
             --quiet
 
       - name: Summary
-        run: echo "Deployed **${{ steps.vars.outputs.service }}** with \`$IMG\`" >> "$GITHUB_STEP_SUMMARY"
+        run: |
+          echo "Deployed **${{ steps.vars.outputs.service }}** (${GCP_PROJECT}/${GCP_REGION}) with \`$IMG\`" >> "$GITHUB_STEP_SUMMARY"

package/CHANGELOG.md

@@ -6,6 +6,19 @@ Security release (security review 2026-10-11, C1 and H4). The agent now fails
 closed by default. Read "Upgrade" before rolling it out to agents whose
 platform side does not sign commands yet.
 
+### Added (opt-in, off by default)
+
+- **`LOCAL_AGENT_PROTOCOL_V2=true`** (F3-05b, default off). The Local Agent side of the CP <-> LA protocol v2:
+  register/hello/ready with resume, seq/ack/retransmission, chunking of `content.response`, allowlist, every
+  frame validated against the gateway's JSON Schemas, Ed25519 check of signed CP frames, `signatureMode` in
+  `hello`. Falls back to the v1 register on the same connection when the gateway does not speak v2; v1 commands
+  keep working. Transport only: no content handlers yet. See `docs/la-protocol-v2.md`. No behaviour change when off.
+
+- **`LOCAL_AGENT_WS_METADATA_ONLY=off|enforce`** (T4-10, D17, D19). `enforce`
+  restricts the outbound WS channel to allowlisted metadata (ids, hashes,
+  counts, state, cost), refuses legacy content commands and denies
+  PolicyGate-backed actions while the control plane is unreachable. See
+  `docs/ws-metadata-only.md`. No behaviour change when off.
 ### Added
 
 - **DLP module (`src/dlp/`, flag `LOCAL_AGENT_DLP_MODE=off|warn|enforce`, default `off`).**

package/docs/la-protocol-v2.md

@@ -0,0 +1,68 @@
+# Protocol v2 on the Local Agent (F3-05b)
+
+The Local Agent side of the CP <-> LA WebSocket protocol v2. The contract is owned by the gateway
+(`docs/contracts/la-protocol-v2` of vh-api-gateway, F3-22); this repo keeps a verified copy in
+`src/la-protocol-v2/contract/` (`CONTRACT_SOURCE.json` records the gateway commit and the sha256 of every
+file; `npm test` fails if a copy was edited). Update it with `node scripts/sync-la-protocol-v2-contract.mjs
+<gateway contract dir> --commit <sha>`; never edit the copy.
+
+## Flag
+
+`LOCAL_AGENT_PROTOCOL_V2=true` (default **off**; unset, empty or unrecognised = off). With it off the tunnel in
+`src/server.js` is the v1 client, byte for byte: no v2 module (nor Ajv, nor the schemas) is loaded.
+
+It also needs `TENANT_ID` to be a UUID and the agent id (`authorizationId` of `~/.deepdebug/config.json`, or
+`LOCAL_AGENT_ID`); without them v2 stays off with a warning. Tuning (clamped): `LOCAL_AGENT_V2_MAX_IN_FLIGHT`
+(frames unacked, default 8), `LOCAL_AGENT_V2_HANDSHAKE_MS` (wait for `ready`, default 10000).
+
+## What it does
+
+- **Handshake.** On each socket: `register` (`protocol:2`, version, capabilities, `signatureMode`, workspaces as
+  `{workspaceId, pathSha256}`, `resume{sessionId,lastRecvSeq}` when it has a session) then `hello`. The gateway
+  answers a signed `ready` (`sessionId`, `resumed`, `peerLastSeq`, limits). Paths never leave the machine, only hashes.
+- **Fallback to v1** on the same connection: no `ready` in 10 s, or `error protocol_unsupported`. The v1
+  register is then sent, and v2 is not offered again for 10 min. A refusal that v1 would not fix
+  (`signature_mode_insufficient`, `clock_skew`, ...) does not fall back.
+- **Signatures.** Every signed CP->LA frame (`ready` included) is checked like a v1 command: `paramsRaw` must equal
+  `payload` (duplicate keys refused), `sig` must be bound to the frame's tenant and workspace, and the Ed25519
+  signature must verify with the trusted keys (`VH-AGENT-SIG-V1`, method `WS`, path = type). `enforce` refuses,
+  `warn` logs and goes on, `off` does not verify. `hello.signatureMode` reports the real mode; the gateway
+  refuses `hybrid`/`client` tenants that are not in `enforce`.
+- **Validation of everything.** Each received and each sent frame is validated with Ajv (2020-12, strict) against
+  the closed schemas, after the allowlist (21 types; direction checked) and the size limit (48 KiB). A refusal is an
+  `error` frame with the wire code only (never an echo of the content) and, for fatal codes, a WS close
+  `4400 + position of the code` (`timeout` = 4420).
+- **Numbering and acks.** `seq` per direction from 1, `ack` piggybacked, an `ack` frame per accepted data frame
+  (`duplicate` for a retransmission, never executed twice: the last 512 `seq`->`msgId` pairs are kept).
+  A frame with no handler is acked `rejected protocol_unsupported`.
+- **Sending.** At most N frames unacked (the rest wait in a bounded queue, 256), retransmitted after
+  `ackTimeoutMs` (same bytes: same seq and msgId), at most 3 times, then `timeout` to the caller and the socket
+  is closed 4420 (the frame is kept for the resume). A `heartbeat` frame every `heartbeatSeconds`; the text `ping`
+  of v1 stays as liveness.
+- **Resume.** The session survives a dropped socket for 120 s (the gateway keeps it 90 s, same instance only).
+  `resumed:false` restarts both numberings at 1 and fails the frames that were in flight (`agent_offline`).
+- **Chunking** (`src/la-protocol-v2/content.js`): `sendContent(session, {requestId, source})` splits a `Buffer` (or
+  `{size, read}`, read lazily) into `content.response` chunks of at most 32 KiB raw (43692 base64 chars, frame
+  under 48 KiB), at most 64 per response (2 MiB), `chunk{index,total,last}`, `byteLength` = decoded size. The
+  chunk rules of the contract are enforced on what is sent; a stream cannot continue across a reset.
+- **v1 commands on a v2 connection** (decision of 2026-10-29: transition, v1 is decommissioned later). A frame
+  without `schemaVersion` is not a v2 frame: it goes to the existing v1 handler (`handleWsCommand`), which
+  answers in the v1 shape. **The gateway (F3-05a) still refuses to send v1 commands to a v2 agent
+  (`protocol_mismatch`)**: this is ready on the LA side, but it will only be exercised once the gateway sends them.
+
+## What it does NOT do
+
+No handler of `content.request` (F3-07), no DLP on what is sent (F3-09, must run before `sendContent` is
+called), no log/incident detector (F3-11b), no `job.assign` runtime (F3-08). Those frames are acked
+`rejected protocol_unsupported`. `sha256` of `content.response` is not sent (the contract does not say what it covers).
+
+## Tests
+
+`npm test` (node:test), all in `test/la-protocol-v2/`:
+`contract.test.js` (all 134 vectors of F3-22, valid and invalid, plus the drift check), `traces.test.js` (the 24
+traces), `session-inbound.test.js`, `session-outbound.test.js`, `link.test.js`, `tunnel-e2e.test.js` (the real
+`src/server.js` against a reference CP; flag off = v1 frames). The reference CP (`test/la-protocol-v2/helpers/reference-cp.js`)
+is a Node model of the gateway rules, not the gateway.
+
+**Interoperability with the real gateway session** (`LaV2Session`, Java, real Reactor Netty socket on loopback, real
+Ed25519 signer): `tools/interop/` (`README.md`). Not part of `npm test` (needs a gateway checkout, JDK 21, Maven).

package/docs/ws-metadata-only.md

@@ -0,0 +1,44 @@
+# WS metadata-only mode (T4-10, D17, D19)
+
+Flag: `LOCAL_AGENT_WS_METADATA_ONLY=off|enforce` (default `off`; an unrecognised value fails closed to `enforce`).
+
+## What `enforce` does
+
+1. **Outbound allowlist** (`src/ws-channel/allowlist.js`). Only these message types leave the agent:
+   `register`, `hello`, `status`, `cost` and command replies (`requestId`/`command`/`ok`/`status`/`openWorkspaces`/`errorCode`).
+   Fields are typed as ids, sha256 hashes, bounded integers, booleans or fixed enums. There is no free-text
+   field, so code, diffs, logs and chat text cannot be carried. `register` sends `workspaceHash` (sha256) instead of `workspacePath`.
+2. **Legacy content commands are refused before execution** (`workspace.file-content`, `workspace.diff`,
+   `workspace.safe-patch`, `mcp.*`, ...). Only `health` and `workspace.open` run; the reply is
+   `{ok:false, errorCode:"blocked_metadata_only"}`. Free-text error messages become `errorCode`.
+3. **Rejections are logged without content**: `[ws-metadata] BLOCKED {"reason":..,"type":..,"field":..}` (field names and codes only).
+4. **D17 transit controls**: nothing is persisted or queued by the module (blocked/over-limit messages are dropped);
+   a reply is sent only once, for a known request, within 60 s (TTL); 4 KiB per message; 200 messages per 10 s; 256 in-flight requests.
+5. **D19 offline = DENY**: while the tunnel is not open (or silent for more than 90 s), exec decisions that depend on
+   PolicyGate (signed platform tool commands, human-approval tokens) are denied with `via=policy-gate-offline`.
+   Allowlisted local commands do not need PolicyGate and are unaffected. Note: with `DISABLE_WS_TUNNEL=true` the agent is
+   permanently "offline", so these actions are always denied under `enforce` (a startup warning is logged; product decision for standalone agents pending, see Open points).
+   The same guard is shared with the MCP bridge (`/mcp/execute-command`), so the DENY applies to both exec entry points.
+
+## Reserved contract and known limits
+
+- `hello`, `status` and `cost` are **reserved contract types: nothing emits them yet**. They are in the allowlist so that the
+  protocol v2 emitters (F3-05b, not merged) can be added without widening the closed world. Only `register` and command replies are sent today.
+- `workspace.open` stays allowed in `enforce` (D16: VH is authoritative). It can still change local state (it sets the workspace root
+  from `params.root` sent by the control plane, protected by request signing); only its reply is projected to metadata.
+- D19 liveness relies on the gateway answering the protocol `ping` (or the text `ping` with `pong`) within 90 s. This has **not** been
+  verified against the real QA gateway; validate it before enabling `enforce` in QA (open point on the PR).
+
+## What does not change
+
+With the flag off (default) the tunnel, the register frame, command handling and exec policy are byte-for-byte the legacy ones.
+The module opens no socket of its own. DLP (`src/dlp/*`), signing, bind and Helm are untouched.
+
+## Rollback
+
+Unset `LOCAL_AGENT_WS_METADATA_ONLY` (or set `off`) and restart the agent.
+
+## Extending the contract
+
+Add the type/field to `OUTBOUND_SCHEMAS` and a golden example to `test/ws-channel/allowlist.test.js` (the closed-set test fails on purpose).
+The CP-side contract (F3-05b protocol v2) is not merged yet; align the schema with it when it lands.

package/env.example

@@ -70,6 +70,13 @@ LOG_LEVEL=info
 # LOCAL_AGENT_WORKSPACE_ID=
 # LOCAL_AGENT_REQUIRE_WORKSPACE=false
 
+# LOCAL_AGENT_WS_METADATA_ONLY=off|enforce (default off). enforce: the outbound WS channel to the
+# control plane carries ONLY allowlisted metadata (ids, hashes, counts, state, cost) and never
+# content (code, diffs, logs, chat). Legacy content commands are refused in this mode, and
+# PolicyGate-backed actions (platform tool commands, human approvals) are DENIED while the agent
+# has no live connection to the control plane (D19). Unrecognised values fail closed to enforce.
+# LOCAL_AGENT_WS_METADATA_ONLY=off
+
 # DLP (T4-09): mask secrets/PII before content leaves the agent. Default off.
 # LOCAL_AGENT_DLP_MODE=off|warn|enforce   (warn = count only, enforce = redact)
 # LOCAL_AGENT_DLP_BLOCK_CLASSES=private-key,cloud-credential   (enforce: withhold whole text)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepdebug-local-agent",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "DeepDebug Local Agent - AI-powered code debugging assistant",
   "private": false,
   "type": "module",
@@ -34,6 +34,7 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.39.0",
     "@modelcontextprotocol/sdk": "^1.0.4",
+    "ajv": "^8.20.0",
     "body-parser": "^1.20.3",
     "chokidar": "^3.6.0",
     "cors": "^2.8.5",

package/scripts/sync-la-protocol-v2-contract.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// scripts/sync-la-protocol-v2-contract.mjs - copies the CP <-> LA protocol v2 contract (F3-22) from a
+// vh-api-gateway checkout into this repo and records where it came from.
+//
+//   node scripts/sync-la-protocol-v2-contract.mjs <gateway-contract-dir> --commit <sha> [--tip <sha>]
+//
+// <gateway-contract-dir> is docs/contracts/la-protocol-v2 of vh-api-gateway (a worktree of release/qa, or
+// the output of `git archive`). The gateway folder stays the only source of truth: never edit the copies.
+//   src/la-protocol-v2/contract/   *.schema.json + index.json (shipped: the runtime validates against them)
+//   test/contract/la-protocol-v2/  vectors/ (valid + invalid messages, traces) used by the tests
+//   src/la-protocol-v2/contract/CONTRACT_SOURCE.json   commit + sha256 of every copied file (a test fails on drift)
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const args = process.argv.slice(2);
+const src = args.find((a) => !a.startsWith("--"));
+const opt = (name) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : undefined; };
+const commit = opt("commit");
+if (!src || !commit || !/^[0-9a-f]{40}$/.test(commit)) {
+    console.error("usage: sync-la-protocol-v2-contract.mjs <gateway docs/contracts/la-protocol-v2> --commit <40-hex sha> [--tip <sha>]");
+    process.exit(2);
+}
+const sha256 = (buf) => crypto.createHash("sha256").update(buf).digest("hex");
+const runtimeDir = path.join(ROOT, "src/la-protocol-v2/contract");
+const vectorsDir = path.join(ROOT, "test/contract/la-protocol-v2");
+fs.rmSync(vectorsDir, { recursive: true, force: true });
+fs.mkdirSync(runtimeDir, { recursive: true });
+fs.mkdirSync(vectorsDir, { recursive: true });
+
+const files = {};
+for (const name of fs.readdirSync(src).filter((n) => n.endsWith(".schema.json") || n === "index.json" || n === "README.md")) {
+    const buf = fs.readFileSync(path.join(src, name));
+    fs.writeFileSync(path.join(runtimeDir, name), buf);
+    files[name] = sha256(buf);
+}
+function copyTree(from, to, rel) {
+    fs.mkdirSync(to, { recursive: true });
+    for (const e of fs.readdirSync(from, { withFileTypes: true })) {
+        if (e.isDirectory()) { copyTree(path.join(from, e.name), path.join(to, e.name), `${rel}/${e.name}`); continue; }
+        const buf = fs.readFileSync(path.join(from, e.name));
+        fs.writeFileSync(path.join(to, e.name), buf);
+        files[`${rel}/${e.name}`] = sha256(buf);
+    }
+}
+copyTree(path.join(src, "vectors"), path.join(vectorsDir, "vectors"), "vectors");
+fs.writeFileSync(path.join(runtimeDir, "CONTRACT_SOURCE.json"), JSON.stringify({
+    repo: "VISIONHAMMER/vh-api-gateway",
+    path: "docs/contracts/la-protocol-v2",
+    branch: "release/qa",
+    commit,
+    ...(opt("tip") ? { branchTip: opt("tip") } : {}),
+    note: "Copied by scripts/sync-la-protocol-v2-contract.mjs. Do not edit: change the gateway folder and sync again.",
+    files,
+}, null, 2) + "\n");
+console.log(`synced ${Object.keys(files).length} files from ${commit.slice(0, 8)}`);

package/src/la-protocol-v2/chunks.js

@@ -0,0 +1,45 @@
+/**
+ * chunks.js - the chunk rules of protocol v2 (README of the contract: "chunks") for ONE direction.
+ *
+ * A `content.response` is a stream of frames with the same requestId: chunk.index 0.., chunk.total constant,
+ * chunk.last true only on the last index, nothing after last, every payload.data at most chunkRawBytes
+ * decoded. The Local Agent applies them to what it SENDS (so it can never emit a stream the gateway would
+ * refuse with a fatal error); the same class is how the tests check the traces.
+ */
+const MAX_STREAMS = 256;
+
+/** How many chunks a payload of `size` bytes needs. An empty payload is still one (empty) chunk. */
+export function chunkCount(size, chunkRawBytes) {
+    return Math.max(1, Math.ceil(size / chunkRawBytes));
+}
+
+export class ChunkStreamTracker {
+    constructor({ chunkRawBytes = 32768, maxChunks = 64 } = {}) {
+        this.chunkRawBytes = chunkRawBytes;
+        this.maxChunks = maxChunks;
+        this.streams = new Map(); // requestId -> { total, next, done }
+    }
+
+    /**
+     * Checks one chunk against the stream state and, when it is fine, records it.
+     * @returns {null | "chunk_out_of_order" | "chunk_inconsistent"}
+     */
+    accept(requestId, chunk, decodedBytes) {
+        const { index, total, last } = chunk;
+        const st = this.streams.get(requestId);
+        if (st && st.done) return "chunk_out_of_order";
+        if (st && st.total !== total) return "chunk_inconsistent";
+        if (total > this.maxChunks) return "chunk_inconsistent";
+        const expected = st ? st.next : 0;
+        if (index !== expected) return "chunk_out_of_order";
+        if (last !== (index === total - 1)) return "chunk_inconsistent";
+        if (decodedBytes > this.chunkRawBytes) return "chunk_inconsistent";
+        this.streams.delete(requestId);
+        this.streams.set(requestId, { total, next: index + 1, done: last });
+        while (this.streams.size > MAX_STREAMS) this.streams.delete(this.streams.keys().next().value);
+        return null;
+    }
+
+    forget(requestId) { this.streams.delete(requestId); }
+    clear() { this.streams.clear(); }
+}

package/src/la-protocol-v2/config.js

@@ -0,0 +1,27 @@
+/**
+ * config.js - LOCAL_AGENT_PROTOCOL_V2 flag (F3-05b).
+ *
+ *   false (default)  the WS tunnel is the v1 client, byte for byte: no v2 module is loaded.
+ *   true             the tunnel offers protocol v2 first (register/hello/ready, see session.js) and
+ *                    falls back to the v1 register on the SAME connection when the gateway does not
+ *                    answer `ready` or answers `protocol_unsupported`.
+ *
+ * Unset/empty/unrecognised = false (an unknown value must never switch the transport).
+ */
+export const PROTOCOL_V2_FLAG = "LOCAL_AGENT_PROTOCOL_V2";
+
+const TRUE = new Set(["true", "1", "yes", "on"]);
+const FALSE = new Set(["", "false", "0", "no", "off"]);
+
+export function resolveProtocolV2Config(env = process.env, warn = console.warn) {
+    const raw = String(env[PROTOCOL_V2_FLAG] ?? "").trim().toLowerCase();
+    if (TRUE.has(raw)) return { enabled: true };
+    if (!FALSE.has(raw)) warn(`[la-v2] unrecognised ${PROTOCOL_V2_FLAG} value; protocol v2 stays off`);
+    return { enabled: false };
+}
+
+/** The per-machine authorization id the gateway checks as `agentId` (config.json `authorizationId`). */
+export function resolveAgentId(env = process.env, fileCfg = {}) {
+    const raw = String(env.LOCAL_AGENT_ID || fileCfg.authorizationId || "").trim().toLowerCase();
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(raw) ? raw : null;
+}

package/src/la-protocol-v2/content.js

@@ -0,0 +1,57 @@
+/**
+ * content.js - sends content to the control plane as a stream of `content.response` chunks (the relay of
+ * the design: never persisted or logged by the CP). TRANSPORT ONLY: no handler of `content.request` lives
+ * here (F3-07) and nothing here decides what may leave the machine (DLP is F3-09, before this is called).
+ *
+ * Rules (contract): <= 32 KiB raw per chunk (43692 base64 chars, frame <= 48 KiB), <= 64 chunks (2 MiB per
+ * response), chunk.index from 0, total constant, last only on the final one, byteLength = decoded size.
+ * Each chunk is its own data frame: numbered, acked, retransmitted. At most `maxInFlight` chunks are in
+ * flight and the next one is not even read until a slot opens (bounded memory for any size).
+ */
+import { ProtocolError } from "./errors.js";
+import { chunkCount } from "./chunks.js";
+
+/**
+ * @param {import("./session.js").V2Session} session
+ * @param {object} o
+ * @param {string} o.requestId           the content.request being answered (lower-case UUID)
+ * @param {Buffer | {size:number, read:(offset:number, length:number)=>Promise<Buffer>}} o.source
+ * @param {string} [o.contentType]       one of the contract's content types
+ * @param {string} [o.workspaceId]
+ * @param {AbortSignal} [o.signal]       abort stops reading and drops the chunks still waiting for a slot
+ * @returns {Promise<{chunks:number, bytes:number}>} resolves when the last chunk was acked
+ */
+export async function sendContent(session, { requestId, source, contentType = "application/octet-stream", workspaceId, signal }) {
+    const size = Buffer.isBuffer(source) ? source.length : source.size;
+    if (!Number.isSafeInteger(size) || size < 0) throw new ProtocolError("internal", "source size");
+    const { chunkRawBytes, maxChunks } = session.limits;
+    const total = chunkCount(size, chunkRawBytes);
+    if (total > maxChunks) throw new ProtocolError("payload_too_large", "response above the chunk limit");
+    const acks = [];
+    try {
+        for (let index = 0; index < total; index++) {
+            if (signal && signal.aborted) throw new ProtocolError("agent_offline", "cancelled");
+            const offset = index * chunkRawBytes;
+            const length = Math.min(chunkRawBytes, size - offset);
+            const bytes = Buffer.isBuffer(source) ? source.subarray(offset, offset + length) : await source.read(offset, length);
+            if (!Buffer.isBuffer(bytes) || bytes.length !== length) throw new ProtocolError("internal", "source returned a wrong length");
+            const h = await session.enqueue("content.response", {
+                status: "ok", contentType, encoding: "base64", data: bytes.toString("base64"), byteLength: length, totalBytes: size,
+            }, { requestId, workspaceId, chunk: { index, total, last: index === total - 1 } });
+            acks.push(h.acked);
+        }
+    } catch (e) {
+        session.cancelWaiting(requestId);
+        for (const a of acks) a.catch(() => {});
+        throw e;
+    }
+    await Promise.all(acks);
+    return { chunks: total, bytes: size };
+}
+
+/** A failed answer: one empty chunk with the status (error | not_found | forbidden) and a wire error code. */
+export async function sendContentFailure(session, { requestId, status = "error", errorCode = "internal", workspaceId }) {
+    await session.send("content.response", {
+        status, errorCode, encoding: "base64", data: "", byteLength: 0,
+    }, { requestId, workspaceId, chunk: { index: 0, total: 1, last: true } });
+}

package/src/la-protocol-v2/contract/CONTRACT_SOURCE.json

@@ -0,0 +1,81 @@
+{
+  "repo": "VISIONHAMMER/vh-api-gateway",
+  "path": "docs/contracts/la-protocol-v2",
+  "branch": "release/qa",
+  "commit": "b090144e19b1da0182554553b18f321452f03bd6",
+  "branchTip": "7043f75e3ed1b201e2c958fd52f721b5a1177efe",
+  "note": "Copied by scripts/sync-la-protocol-v2-contract.mjs. Do not edit: change the gateway folder and sync again.",
+  "files": {
+    "README.md": "41dd3cbceccb487ca30da5838841f04d8abffcc81c31424da833114ab646b291",
+    "ack.schema.json": "d6dfdaa8b1ec2dd47db9e858cd047ca860196ab6b0ad350f8ccb5d2596441ccf",
+    "alert.schema.json": "01a8a77840be8ab7901ed7d07c3d68a2295bfaeb638694564e19e60be1747054",
+    "approval.decision.schema.json": "a9c7bc74d146465afde1d5830839165a02f232b830b5f6cfd8c8e91fb6da1563",
+    "audit.event.schema.json": "e9ceb58ea00077151373955957b8319324de488c80da4063f6d0dcb40a8b3ed0",
+    "config.update.schema.json": "f5318f24230f542c76a3cb996d08f33210c0b2cc2fc55ad73c4f95648582033f",
+    "content.request.schema.json": "9966b55ec051832ac93ee43e9cd226e4f0efaeb49741947bfc48193e40e00a32",
+    "content.response.schema.json": "c9a66ac9cbbcaec7fc182b3e3fa23b34877bd342592521c7e393779230332231",
+    "defs.schema.json": "f19fd27fd103d8da02de4506c086263c6236250c5c127aa3aab41833a90b743a",
+    "envelope.schema.json": "670fb26c7d532475da144185e5100b3a2ffe0d267451b1ef9debadf31b33ab79",
+    "error.schema.json": "b1fd663d4a1ea73d88cb575422f15f8c7279001f9385ebb2d5e1889b5d5ef878",
+    "heartbeat.schema.json": "8aff84a1ef3ca56bdff8819abb3b0ab01a2547814c2ea2f9ee893cb08f7a08f1",
+    "hello.schema.json": "bd500320f01ff10da49ded6f99c7e8081252019984afb3c178e27003df20b963",
+    "incident.candidate.schema.json": "b292a85917b5958fc6de10a2895732e30a35420385623930c78e47341862dc62",
+    "index.json": "55543ecf492b1ffe2b9a78075890ee05518d3539fbcaeb04e8b2da8ff37c9130",
+    "job.assign.schema.json": "fdebb4ae98bf38a2c723281c1cf9477f71d877171df9a55b0baeb0b65244f60c",
+    "job.cancel.schema.json": "40ef64373283e17306d857c9a40081689786015294b0b88ab8f68f063bd2cfb8",
+    "job.event.schema.json": "493d08f9db4f7ffd4a97403ee33ca4a73a65dc8f774d8f18ef0a137fdb5fc470",
+    "job.result.schema.json": "9cbc61211482557283b8f4df44e79011ead1abbacdb2d986138199c747edc043",
+    "log.stats.schema.json": "4b33b111946a19793a60756793294e90911b06f7050e48821759f2497ec17641",
+    "ready.schema.json": "6e8bd8e1a5ce1b840d35af911ae09b8f58ad9de59eb33cd2b7777859892813f4",
+    "register.schema.json": "e75a4aa9d5d750e1473f71ab2f37d8e9a82fcfab3e8ff1c35118d0c08916e795",
+    "scan.upload.schema.json": "b1bba86ee362f73afc94c8c216977c12f67f770490e81002d14789397692f23b",
+    "scan.uploaded.schema.json": "f4c6aed7b9363b3ce1a9e14f9c4f4fb003bcf104b60acf74421dd0c75fc5d229",
+    "webhook.forward.schema.json": "33d4ee238855339850ff198d1078087f3b2f48c8f290b71def93cc02dd32c985",
+    "vectors/ack.vectors.json": "242ec2b8ff0c748eaaedce63e0015cf5bd9a7092d1055b0670ce6b95403b54b2",
+    "vectors/alert.vectors.json": "0bf179ff390bbecf07a117b80237cb7ac8778864e5780f36d68c8c9a64db8f04",
+    "vectors/approval.decision.vectors.json": "338115973bf2c4390d2bb33ce8f4079f3132cd739cd5505e1e873fdc252d2271",
+    "vectors/audit.event.vectors.json": "d05c1820103eef041a84eb8b13d9a67a8a5b54b9b54ee3b6e43fd4ef15ed7000",
+    "vectors/config.update.vectors.json": "8a5088d547e3eb4e460b25a5e413caaa02d4402a601340e279166d8c17758e1c",
+    "vectors/content.request.vectors.json": "6922748edfc630ce881a1b79d24827de03f849e05c441ef7eecc684bf2238e58",
+    "vectors/content.response.vectors.json": "35ef18edbcec24c029781e97d60dcb0b9111697fa3a5a2a8dfd159744e7f8258",
+    "vectors/cross-type.vectors.json": "f7ed403d3e3f53150b715a5423fde1bed708e8c6245709ed4ad74389dc8c3307",
+    "vectors/error.vectors.json": "f5fd7954f2c1736ee0943eb330c2f85b7fdd7a8959e4f043f9cc9e9bcda39aa5",
+    "vectors/heartbeat.vectors.json": "cfd2e048139c67aa925f1fa94c05326e75248839645c1a1e4d6d3bb60cafa624",
+    "vectors/hello.vectors.json": "51067dc645a2e9d8116997b36e6f3fe36401d27f3ee3c18de32ec30f8a052c5f",
+    "vectors/incident.candidate.vectors.json": "0dd75ef396bf7b7911d20b3ab220469701f07866bb032ee31af58523c3633ab6",
+    "vectors/job.assign.vectors.json": "e510c2cc6d17238d477429c255d828c0339b504e39a3a50d4b6ca980e262d9ef",
+    "vectors/job.cancel.vectors.json": "0fc9f99c8662435e9425389068adf418273489dc73928a21eae1b283256b9bc5",
+    "vectors/job.event.vectors.json": "03a2a2435918ba561821916bf4e435f2780210900139ecf68091acac6abf200c",
+    "vectors/job.result.vectors.json": "05995fbe65e5357705d75e9b660b517f54c6902069d36b62190b1b79f283e7a5",
+    "vectors/log.stats.vectors.json": "a8a67e09ef0f87b81f4028b77427ed7afd809c3f8534b8423a712b2ceef9a27f",
+    "vectors/ready.vectors.json": "a584da17e714a13c3583256773ef0be007660c33c62a456e27568def391e7cef",
+    "vectors/register.vectors.json": "e2a696efc547aa2f7242128d1a860238954f9e9a1330f10b567122d7b3da0365",
+    "vectors/scan.upload.vectors.json": "e8a6f73fe91ac58a3222b68cf28124c1254aa4f00c3ef8f472deb7de31cab76e",
+    "vectors/scan.uploaded.vectors.json": "7314ea15b1afa7b9625048fb7e245492d8910bc0dae8a52ea62afe2a1e240382",
+    "vectors/traces/invalid-agent-mismatch.json": "5f17b867de71c1bcc6c42723acb53a50338c0e491193499ea25c2220ea4fa558",
+    "vectors/traces/invalid-chunk-after-last.json": "0dcc3f3cce605a490d65e96592668381fa9a191d908a26ede998717494eb2f2e",
+    "vectors/traces/invalid-chunk-byte-length-mismatch.json": "d328ad05b22d3abaf0497ee8482a07a08ac90a4ede94edf754e8962ca8ea201e",
+    "vectors/traces/invalid-chunk-last-flag.json": "6c59a361313e966999ec25c80733758d86befb5f3607528634a148291844d212",
+    "vectors/traces/invalid-chunk-out-of-order.json": "c6560290755d86b524316823d32fcbd1420c170b13e198813c3b7e7b7f32ecb6",
+    "vectors/traces/invalid-chunk-total-changes.json": "9b7ade197252275725bc0754e40eadc12a289c063fed13a2905c55583a27a767",
+    "vectors/traces/invalid-clock-skew.json": "de16e0bd72e08bb03d44d5f2f04a238dcd38447ff1690f8acfe712ca3fe2028b",
+    "vectors/traces/invalid-event-before-ready.json": "17081f197fab5f4490b15a088f2bce620921007b5fdd7ed63bd988899d674883",
+    "vectors/traces/invalid-first-frame-not-register.json": "cf41c2d0e67f6df382790dab13bb9e49db99a34a88c1f9d108214be5df1e4ea3",
+    "vectors/traces/invalid-frame-over-48kib.json": "912e37c9a326ad92284ba22af752269cb5dd52ed06cdc22b17fd3b74a8423734",
+    "vectors/traces/invalid-la-sends-job-assign.json": "4ce5313e125e2afa920e923c2b5b524f627f47d06961a250a8dc642b79225252",
+    "vectors/traces/invalid-params-raw-differs-from-payload.json": "1220630372c78a41d77b2653b8f9025cb87d601c199adb03edbf007e6e727ad1",
+    "vectors/traces/invalid-payload-above-limit.json": "99f3834cfea69bc6ffa169bd6a2ed915377331205f8e991ceacbf21b3525fe96",
+    "vectors/traces/invalid-resume-restarts-seq.json": "795964093051511c00538f88774956b471a35338b92a0a180bedb33d460f2d83",
+    "vectors/traces/invalid-seq-gap.json": "9c85719b07cb7309752ffaa33b6c6cb1b278c45cd72e21dbc788c56af5e4502f",
+    "vectors/traces/invalid-seq-repeated.json": "4a4dd18d5b9de61a6cec735229b7991d6de4f3598acd7b16541eaca44be4556d",
+    "vectors/traces/invalid-sig-tenant-mismatch.json": "5d8895cbc9c1b91be31a851d009d1f2b832f9735c3713b131ac9837c90b4a8e7",
+    "vectors/traces/invalid-signature-warn-with-enforce-required.json": "71b5b3dc5dce52417173934db1e0de6542ecae5798e87124d54a8017493312e1",
+    "vectors/traces/invalid-tenant-mismatch.json": "dcc04ea423bddef20524ead7bfd146a5d9c42fe474c9216dc38c90544d291151",
+    "vectors/traces/invalid-type-outside-allowlist.json": "e492d326cfa044d3fc9f7e48dee63a52b715a62ba4867fc5ce21f1d86e3c435f",
+    "vectors/traces/valid-content-chunks-in-order.json": "c5fc301527b062b30c625da2798c7cfab3e3debac29a36f6ec7c699705267ab3",
+    "vectors/traces/valid-handshake-and-job.json": "9aa3c423c496403ca77d63965f1805f0a57ea9f6f8a01351310515b265aeb9cc",
+    "vectors/traces/valid-resume-continues-seq.json": "8aa90f24598f8f2d87a5355ec58c3531d16fd11ad41c782f53eca063372b704a",
+    "vectors/traces/valid-retransmit-is-idempotent.json": "924e9d296a67f0006c289e7cc978b9529ae1aa03bec2cd331a62f31354a90257",
+    "vectors/webhook.forward.vectors.json": "38d5b53b8fb4ecdb051e2c594afc52eb8b2044e4e6aae6ffb0057fbda33bcd46"
+  }
+}