deepdebug-local-agent 1.3.0 → 1.5.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

@@ -8,6 +8,12 @@ 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

package/docs/la-protocol-v2.md

@@ -0,0 +1,102 @@
+# 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.
+
+## Content handlers (F3-07, `LOCAL_AGENT_CONTENT_HANDLERS`, default false)
+
+Needs `LOCAL_AGENT_PROTOCOL_V2=true` too. Off (unset, empty, `false` or any unknown value): `content.request` is acked
+`rejected protocol_unsupported` exactly as before and the register announces no `content.*` capability. On: kinds
+`file` and `diff` are served (capabilities `content.file`, `content.diff`); any other kind of the allowlist answers
+`content.response` `status:"error"` + `errorCode:"protocol_unsupported"`.
+
+- **Opaque ids.** The `ref` is an id (`cr1_` + 128 random bits, base64url) minted by the agent, never derived from a path.
+  It maps in memory to (tenant, workspace, root, kind, relative path), lives `LOCAL_AGENT_CONTENT_REF_TTL_MS` (15 min) and
+  is forgotten when the agent restarts. Anything that is not a live id for this tenant+workspace+root+kind (unknown,
+  expired, another workspace, a path, `../x`) is `not_found` and is never echoed. The only other ref is the symbolic
+  `worktree` for kind `diff` (the work tree of the envelope's workspace). Whoever reports metadata to the control plane
+  gets an id with `link.content.mintRef({workspaceId, kind, rel})` (no caller yet: see the F3-07 note).
+- **The agent is the authority on paths.** Workspace must be registered here and belong to this tenant; the real path
+  must stay inside the real root (a link that leaves it is `forbidden`), must not be sensitive under its real name,
+  must be a regular file opened without following links. Sensitive by default: `.env*`, `*.pem`, `*.key`, `*.p12`,
+  `id_rsa*`..., `.npmrc`, `.netrc`, `*.tfstate`, `.git/`, `.ssh/`, `.aws/`, `.docker/`... (`LOCAL_AGENT_CONTENT_DENY_GLOBS`
+  adds to the list). No id is ever minted for them.
+- **DLP before anything leaves** (`LOCAL_AGENT_DLP_MODE`, the module `src/dlp`): `enforce` masks the whole text before it is
+  chunked (a secret cannot straddle chunks), withholds a file with a hit in `LOCAL_AGENT_DLP_BLOCK_CLASSES`, and fails
+  closed for binary files, inputs above `LOCAL_AGENT_DLP_MAX_BYTES` and DLP errors. `warn` and `off` send the content as
+  read (warn only counts). The agent warns at start-up when handlers are on and the mode is not `enforce`.
+- **Limits.** `LOCAL_AGENT_CONTENT_MAX_BYTES` per response (default 1 MiB, ceiling 2 MiB = 64 chunks; a file above it is
+  `payload_too_large` without being read), `LOCAL_AGENT_CONTENT_MAX_CONCURRENT` (4) and `..._MAX_INFLIGHT_BYTES`
+  (`rate_limited` above), `LOCAL_AGENT_CONTENT_TOTAL_MS` (25 s), the session window (8 chunks in flight, backpressure).
+  Cancellation: `handler.cancel(requestId)`, the deadline, closing the link, or loss of the session.
+- **Diff.** `git diff HEAD` of the work tree, no shell, without external diff/textconv/fsmonitor, without any `GIT_*` of
+  the agent's env, only for files that pass the same deny list, at most `LOCAL_AGENT_CONTENT_MAX_DIFF_FILES` (500).
+- **Audit.** One local record per request (kind, status, code, sizes, DLP mode and per-rule counts, a short hash of the
+  ref): in memory and optionally `LOCAL_AGENT_CONTENT_AUDIT_FILE` (JSONL, 0600, rotates at 5 MiB). Never content,
+  paths or the ref.
+
+## What it does NOT do
+
+No handler for the other kinds (`incident.*`, `log.*`, `chat.session`, `wiki.page`, `job.*`, `approval.detail`, `report`),
+no inventory frame that tells the control plane which ids exist (the contract has none), 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), and for F3-07 `content-path-guard.test.js`,
+`content-handlers.test.js`, `content-wiring.test.js` (flag, runtime wiring, real `src/server.js`). 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepdebug-local-agent",
-  "version": "1.3.0",
+  "version": "1.5.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-handlers/audit.js

@@ -0,0 +1,36 @@
+/**
+ * audit.js - local audit of served content (F3-07). One record per content.request, NEVER the content, a path or
+ * the ref: kind, status, sizes, DLP mode and per-rule counts, timing, a short hash of the ref and of the user id.
+ *
+ *   ring    the last `ringSize` records in memory (tests, support, future heartbeat summary)
+ *   file    optional JSONL (LOCAL_AGENT_CONTENT_AUDIT_FILE), mode 0600; at `maxFileBytes` it rotates to <file>.1
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+
+export const short = (v) => crypto.createHash("sha256").update(String(v ?? "")).digest("hex").slice(0, 16);
+
+export function createAudit({ file = null, ringSize = 500, maxFileBytes = 5 * 1024 * 1024, now = Date.now } = {}) {
+    const ring = [];
+    let written = 0;
+    let broken = false;
+    if (file) { try { written = fs.statSync(file).size; } catch { written = 0; } }
+    return {
+        record(entry) {
+            const rec = { ts: new Date(now()).toISOString(), ...entry };
+            ring.push(rec);
+            if (ring.length > ringSize) ring.shift();
+            if (file && !broken) {
+                try {
+                    const line = JSON.stringify(rec) + "\n";
+                    if (written + line.length > maxFileBytes) { fs.renameSync(file, `${file}.1`); written = 0; }
+                    fs.appendFileSync(file, line, { mode: 0o600 });
+                    written += line.length;
+                } catch { broken = true; /* auditing to disk must never break the data path; the ring still has it */ }
+            }
+            return rec;
+        },
+        tail(n = 50) { return ring.slice(-n); },
+        get brokenFile() { return broken; },
+    };
+}

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

@@ -0,0 +1,48 @@
+/**
+ * config.js - LOCAL_AGENT_CONTENT_HANDLERS flag and limits of the content.request handlers (F3-07).
+ *
+ *   false (default)  `content.request` keeps being acked `rejected protocol_unsupported`: nothing of this folder is loaded.
+ *   true             handlers for `file` and `diff` are registered. Needs LOCAL_AGENT_PROTOCOL_V2=true as well
+ *                    (without it there is no v2 session and the flag does nothing).
+ *
+ * Unset/empty/unrecognised = false (an unknown value must never open the door to client content).
+ * Every number is clamped: a bad value falls back to the default, never to "unlimited".
+ */
+export const CONTENT_HANDLERS_FLAG = "LOCAL_AGENT_CONTENT_HANDLERS";
+
+const TRUE = new Set(["true", "1", "yes", "on"]);
+const FALSE = new Set(["", "false", "0", "no", "off"]);
+
+const MIB = 1024 * 1024;
+
+function int(raw, def, min, max) {
+    const n = Number.parseInt(String(raw ?? ""), 10);
+    return Number.isFinite(n) && n >= min && n <= max ? n : def;
+}
+
+export function resolveContentHandlersConfig(env = process.env, warn = console.warn) {
+    const raw = String(env[CONTENT_HANDLERS_FLAG] ?? "").trim().toLowerCase();
+    if (!TRUE.has(raw)) {
+        if (!FALSE.has(raw)) warn(`[la-content] unrecognised ${CONTENT_HANDLERS_FLAG} value; content handlers stay off`);
+        return { enabled: false };
+    }
+    const maxConcurrent = int(env.LOCAL_AGENT_CONTENT_MAX_CONCURRENT, 4, 1, 16);
+    const maxBytes = int(env.LOCAL_AGENT_CONTENT_MAX_BYTES, 1 * MIB, 1, 2 * MIB);   // per response (the contract caps it at 2 MiB)
+    return {
+        enabled: true,
+        maxBytes,
+        maxConcurrent,
+        // total bytes held in memory by requests in flight (a response is built whole, masked, then streamed)
+        // (each request reserves 2 x maxBytes: the bytes read and the masked copy)
+        maxInFlightBytes: int(env.LOCAL_AGENT_CONTENT_MAX_INFLIGHT_BYTES, 2 * maxBytes * maxConcurrent, 2 * maxBytes, 256 * MIB),
+        refTtlMs: int(env.LOCAL_AGENT_CONTENT_REF_TTL_MS, 15 * 60_000, 10_000, 24 * 3_600_000),
+        maxRefs: int(env.LOCAL_AGENT_CONTENT_MAX_REFS, 20_000, 100, 200_000),
+        // the gateway gives a request 30 s in total (contract: contentTotalMs)
+        totalMs: int(env.LOCAL_AGENT_CONTENT_TOTAL_MS, 25_000, 1_000, 30_000),
+        gitTimeoutMs: int(env.LOCAL_AGENT_CONTENT_GIT_TIMEOUT_MS, 8_000, 500, 20_000),
+        maxDiffFiles: int(env.LOCAL_AGENT_CONTENT_MAX_DIFF_FILES, 500, 1, 5_000),
+        // additive to the built-in list (path-guard.js); comma separated globs
+        extraDenyGlobs: String(env.LOCAL_AGENT_CONTENT_DENY_GLOBS ?? "").split(",").map((s) => s.trim()).filter(Boolean).slice(0, 200),
+        auditFile: String(env.LOCAL_AGENT_CONTENT_AUDIT_FILE ?? "").trim() || null,
+    };
+}

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

@@ -0,0 +1,65 @@
+/**
+ * egress.js - everything between "bytes read on this machine" and "bytes handed to sendContent" (F3-07).
+ *
+ * The DLP is the one of the agent (src/dlp, LOCAL_AGENT_DLP_MODE=off|warn|enforce, same rules, same counters):
+ *   off      content goes as read.
+ *   warn     content goes as read; the DLP only counts what enforce WOULD have masked (the existing "warn" meaning).
+ *   enforce  every hit is replaced by [REDACTED:<rule>]; a hit in LOCAL_AGENT_DLP_BLOCK_CLASSES withholds the whole
+ *            content (`forbidden`); an input above LOCAL_AGENT_DLP_MAX_BYTES, a DLP failure, or a binary file (it cannot
+ *            be inspected) never goes out (payload_too_large | internal | forbidden). Fail closed, as in the DLP module.
+ * The WHOLE text is masked before it is split into chunks, so a secret that would straddle two chunks is still found.
+ * A `range` is applied to the bytes AS SERVED (after masking): the offsets are stable between requests.
+ */
+import { dlpConfigFromEnv, protectEgress, DENIED } from "../../dlp/index.js";
+import { OVERSIZE } from "../../dlp/engine.js";
+
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+
+export function decodeText(buffer) {
+    const probe = buffer.subarray(0, 8000);
+    if (probe.includes(0)) return null;
+    try { return utf8.decode(buffer); } catch { return null; }
+}
+
+const EXT_TYPES = new Map([
+    [".md", "text/markdown"], [".markdown", "text/markdown"], [".json", "application/json"],
+    [".diff", "text/x-diff"], [".patch", "text/x-diff"], [".zip", "application/zip"],
+]);
+
+export function contentTypeOf(rel, isText) {
+    const m = /(\.[A-Za-z0-9]+)$/.exec(rel || "");
+    const t = m ? EXT_TYPES.get(m[1].toLowerCase()) : undefined;
+    if (isText) return t && t !== "application/zip" ? t : "text/plain";
+    return t === "application/zip" ? t : "application/octet-stream";
+}
+
+/**
+ * @param {{buffer:Buffer, contentType?:string, range?:{offset:number,length:number}, maxBytes:number, env?:object, source:string}} o
+ * @returns {{ok:true, buffer:Buffer, contentType:string, dlp:{mode:string,total:number,redactions:object}} |
+ *           {ok:false, status:"forbidden"|"error", errorCode?:string, dlp:{mode:string,total:number,redactions:object}}}
+ */
+export function prepareOutgoing({ buffer, contentType, range, maxBytes, env = process.env, source }) {
+    const cfg = dlpConfigFromEnv(env);
+    const dlp = { mode: cfg.mode, total: 0, redactions: {} };
+    let out = buffer;
+    let type = contentType;
+    const text = decodeText(buffer);
+    if (text === null) {
+        if (cfg.mode === "enforce") return { ok: false, status: "forbidden", dlp };      // cannot be inspected: fail closed
+        type = type && !type.startsWith("text/") ? type : "application/octet-stream";
+    } else if (cfg.mode !== "off") {
+        if (cfg.mode === "enforce" && text.length > cfg.maxBytes) return { ok: false, status: "error", errorCode: "payload_too_large", dlp };
+        const res = protectEgress(text, { env, source });
+        dlp.total = res.total;
+        dlp.redactions = res.redactions;
+        if (res.denied || res.text === DENIED) return { ok: false, status: "error", errorCode: "internal", dlp };
+        if (cfg.mode === "enforce") {
+            if (res.blocked) return { ok: false, status: "forbidden", dlp };
+            if (res.text === OVERSIZE) return { ok: false, status: "error", errorCode: "payload_too_large", dlp };
+            out = Buffer.from(res.text, "utf8");
+        }
+    }
+    if (range) out = out.subarray(Math.min(range.offset, out.length), Math.min(range.offset + range.length, out.length));
+    if (out.length > maxBytes) return { ok: false, status: "error", errorCode: "payload_too_large", dlp };
+    return { ok: true, buffer: out, contentType: type || "text/plain", dlp };
+}

package/src/la-protocol-v2/content-handlers/git-diff.js

@@ -0,0 +1,92 @@
+/**
+ * git-diff.js - `diff` kind: the work tree against HEAD, for the files that may be shown (F3-07).
+ *
+ * No shell. git runs with the agent's env minus secret-looking variables and minus every GIT_* variable (a stray
+ * GIT_DIR must not point it at another repository), without external diff drivers, textconv filters or fsmonitor
+ * hooks (a malicious repo config could name a command for each), with literal pathspecs. The file list is taken
+ * first and filtered (sensitive and out-of-root names never reach the second call), then diffed with that explicit list
+ * (at most `maxFiles` names and 128 KiB of arguments). Output is capped while it streams (the process is killed above the cap).
+ */
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import { sanitizedChildEnv } from "../../utils/child-env.js";
+import { isSensitivePath, normalizeRel } from "./path-guard.js";
+
+const GIT_SAFE = ["--literal-pathspecs", "-c", "core.quotepath=off", "-c", "core.fsmonitor=false", "-c", "core.pager=cat", "-c", "diff.external="];
+
+function gitEnv() {
+    const env = sanitizedChildEnv(process.env);
+    for (const k of Object.keys(env)) if (k.startsWith("GIT_")) delete env[k];
+    return { ...env, GIT_TERMINAL_PROMPT: "0", GIT_OPTIONAL_LOCKS: "0", GIT_PAGER: "cat" };
+}
+
+/** @returns {Promise<{code:number|null, out:Buffer, overflow:boolean, timedOut:boolean, aborted:boolean}>} */
+function runGit(args, { cwd, input, maxBytes, timeoutMs, signal }) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn("git", args, { cwd, env: gitEnv(), shell: false, stdio: ["pipe", "pipe", "ignore"], windowsHide: true });
+        } catch {
+            resolve({ code: null, out: Buffer.alloc(0), overflow: false, timedOut: false, aborted: false });
+            return;
+        }
+        const chunks = [];
+        let size = 0;
+        const st = { overflow: false, timedOut: false, aborted: false };
+        const kill = () => { try { child.kill("SIGKILL"); } catch { /* gone */ } };
+        const timer = setTimeout(() => { st.timedOut = true; kill(); }, timeoutMs);
+        const onAbort = () => { st.aborted = true; kill(); };
+        if (signal) { if (signal.aborted) onAbort(); else signal.addEventListener("abort", onAbort, { once: true }); }
+        child.stdout.on("data", (d) => {
+            size += d.length;
+            if (size > maxBytes) { st.overflow = true; kill(); return; }
+            chunks.push(d);
+        });
+        child.stdin.on("error", () => {});
+        child.stdin.end(input || "");
+        child.on("error", () => { clearTimeout(timer); resolve({ code: null, out: Buffer.alloc(0), ...st }); });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (signal) signal.removeEventListener("abort", onAbort);
+            resolve({ code, out: Buffer.concat(chunks), ...st });
+        });
+    });
+}
+
+/**
+ * @param {{root:string, rel?:string|null, maxBytes:number, maxFiles:number, timeoutMs:number, denyGlobs?:string[], signal?:AbortSignal}} o
+ * @returns {Promise<{ok:true, text:string} | {ok:false, status:"not_found"|"forbidden"|"error", errorCode?:string}>}
+ */
+export async function worktreeDiff({ root, rel = null, maxBytes, maxFiles, timeoutMs, denyGlobs = [], signal }) {
+    let cwd;
+    try { cwd = await fs.promises.realpath(root); } catch { return { ok: false, status: "not_found" }; }
+    let only = null;
+    if (rel !== null) {
+        only = normalizeRel(rel);
+        if (!only) return { ok: false, status: "not_found" };
+        if (isSensitivePath(only, denyGlobs)) return { ok: false, status: "forbidden" };
+    }
+    const listArgs = [...GIT_SAFE, "diff", "--name-only", "-z", "--no-renames", "--no-ext-diff", "--relative", "HEAD", "--", ...(only ? [only] : ["."])];
+    const listed = await runGit(listArgs, { cwd, maxBytes: 4 * 1024 * 1024, timeoutMs, signal });
+    if (listed.aborted) return { ok: false, status: "error", errorCode: "agent_offline" };
+    if (listed.timedOut) return { ok: false, status: "error", errorCode: "timeout" };
+    if (listed.overflow) return { ok: false, status: "error", errorCode: "payload_too_large" };
+    if (listed.code !== 0) return { ok: false, status: "not_found" }; // not a repository, no HEAD yet, unsafe directory...
+    const names = [];
+    let argBytes = 0;
+    for (const n of listed.out.toString("utf8").split("\0")) {
+        const norm = n ? normalizeRel(n) : null;
+        if (!norm || isSensitivePath(norm, denyGlobs)) continue;
+        argBytes += Buffer.byteLength(norm) + 1;
+        if (names.length >= maxFiles || argBytes > 128 * 1024) break;
+        names.push(norm);
+    }
+    if (names.length === 0) return { ok: true, text: "" };
+    const diffArgs = [...GIT_SAFE, "diff", "--no-color", "--no-ext-diff", "--no-textconv", "--no-renames", "--relative", "-U3", "HEAD", "--", ...names];
+    const diff = await runGit(diffArgs, { cwd, maxBytes: maxBytes + 1, timeoutMs, signal });
+    if (diff.aborted) return { ok: false, status: "error", errorCode: "agent_offline" };
+    if (diff.timedOut) return { ok: false, status: "error", errorCode: "timeout" };
+    if (diff.overflow) return { ok: false, status: "error", errorCode: "payload_too_large" };
+    if (diff.code !== 0) return { ok: false, status: "error", errorCode: "internal" };
+    return { ok: true, text: diff.out.toString("utf8") };
+}