deepdebug-local-agent 1.7.0 → 1.9.0

package/.claude/context.md

@@ -15,7 +15,8 @@ Cloud Run service (`deepdebug-local-agent-qa` / `deepdebug-local-agent`) for the
 variant.
 
 **Does not:** call LLMs or hold provider keys (the thinking happens in vh-agents via
-vh-litellm), decide tenant policy, or merge anything.
+vh-litellm). The one exception, behind `LOCAL_AGENT_LLM_KEY` (default off): the VIRTUAL key of the AI
+gateway delivered by `config.update` (F3-09), kept in memory or a 0600 file, never logged; there is no LLM client yet, decide tenant policy, or merge anything.
 
 ## Neighbours
 

package/CLAUDE.md

@@ -7,7 +7,7 @@
    layers, simplicity, testing, review checklist, `node.md`).
 3. `README.md`: features, legacy connectors, configuration.
 
-Non-negotiables: no LLM calls and no provider keys here; exec with argument arrays only;
+Non-negotiables: no LLM calls and no provider keys here (the one exception, approved by Edu 2026-11-03, is the VIRTUAL key of the AI gateway delivered by `config.update`, F3-09, `client` tenants only: flag `LOCAL_AGENT_LLM_KEY`, memory by default and a 0600 file in a 0700 dir only with `LOCAL_AGENT_LLM_KEY_FILE`, never in logs or acks; there is still no LLM client); exec with argument arrays only;
 paths confined to the workspace; never log secrets or raw customer log payloads beyond
 what an incident needs; PRs target `main` (merging publishes the npm package).
 Personal, uncommitted notes go in `CLAUDE.local.md` (gitignored).

package/docs/la-protocol-v2.md

@@ -136,14 +136,37 @@ start-up. The mode is also read at each request: leaving `enforce` at run time s
 ## What it does NOT do
 
 No handler for the other kinds (`incident.*`, `log.*`, `chat.session`, `wiki.page`, `job.*`, `approval.detail`, `report`),
-no log/incident detector
-(F3-11b), no `job.assign` runtime (F3-08). Those frames are acked `rejected protocol_unsupported`. `sha256` of
+no `job.assign` runtime (F3-08) (the log/incident detector is F3-11b, see below). Those frames are acked `rejected protocol_unsupported`. `sha256` of
 `content.response` is not sent (the contract does not say what it covers).
 
+## Incident detector (F3-11b, `LOCAL_AGENT_INCIDENT_DETECTOR`, default false)
+
+Reads the customer's logs (files, stdin, Loki; `LOCAL_AGENT_INCIDENT_LOG_FILES`, `..._STDIN`, `..._LOKI_URL` + `..._LOKI_QUERY`), detects errors with
+the same rules as the Java monitor (errorHash, fingerprint, significance, noise; parity vectors generated from the Java code) and sends `incident.candidate`
+(9 metadata fields, no text) per errorHash window. Announces the capability `incident.candidate`. The detail stays in a local JSONL store (0600, DLP-masked).
+Needs `LOCAL_AGENT_PROTOCOL_V2=true`. Details, limits and hooks: `src/incident-detector/README.md`. The `incident.detail` content kind is NOT served yet.
+
+## Contract 2.1 consumers (F3-09 / F3-12 / F3-11b, flags default false)
+
+The contract copy is revision 2.1 (`src/la-protocol-v2/contract/CONTRACT_SOURCE.json` names the gateway commit and branch). With every flag off the agent announces exactly what it
+announced before (`protocol.v2 v1.commands chunk.base64`); `contract.v2.1` is announced only when one of the three features below is on.
+- **LLM key** (`LOCAL_AGENT_LLM_KEY`, capability `llm.key`; `src/la-protocol-v2/llm-key/`): `config.update.llmKey` `set` / `revoke`. The virtual key of the AI gateway is held in a
+  private field (memory) or, with `LOCAL_AGENT_LLM_KEY_FILE`, in a 0600 file outside every workspace; it is never in an ack, a log, the audit or a frame. A key whose id is not the
+  sha256 of the key, or that has expired, is `rejected schema_violation`. There is NO LLM client in the agent: `link.llm.request(path, init)` is the hook (https endpoint of the control
+  plane, Authorization set by the holder, redirects refused) and nothing calls it yet. Memory by default; the file only with `LOCAL_AGENT_LLM_KEY_FILE` (file 0600, directory 0700;
+  exception to "no keys here" approved by Edu 2026-11-03, recorded in `CLAUDE.md`). `llm.key.held` (contract 2.1 (e)): at EVERY connect the agent adds this capability to `register` AND `hello`
+  only while the holder has a valid, unexpired key (never without `llm.key`); a revoked or expired key stops being announced on the next connection, so the control plane delivers a new one.
+- **Webhooks** (`LOCAL_AGENT_WEBHOOK_FORWARD`, capabilities `webhook.forward` + `webhook.chunked`; `src/la-protocol-v2/webhooks/`): one frame (<= 9216 bytes) or chunks (16 KiB, <= 64, <= 1 MiB)
+  rebuilt IN MEMORY with the contract limits (30 s, 4 assemblies, 4 MiB), sha256 verified, handed to the incident detector (`src/incident-detector/sources/webhook-source.js`, then the
+  same pipeline and the DLP-masked local store). The ack of the last chunk (or of the single frame) is sent only after the local delivery finished, waiting up to `LOCAL_AGENT_WEBHOOK_DELIVERY_MS`
+  (default 10 s, max 14 s; the session does not ack `accepted` after 2 s for this type); past it the ack is `rejected timeout`. Delivered ids (+ sha256 of the body) are remembered in memory for 10 min (max 1024):
+  a resend (same id and body) is acked `accepted`, chunk by chunk, without being processed again, so the detector's count is not inflated. Needs `LOCAL_AGENT_INCIDENT_DETECTOR=true`.
+- **Candidate size and model** (no new flag, part of `LOCAL_AGENT_INCIDENT_DETECTOR`): `incident.candidate` carries `stackBytes` and `model` only if `ready.capabilities` listed `incident.candidate.size-model`.
+
 ## Tests
 
-`npm test` (node:test), all in `test/la-protocol-v2/`:
-`contract.test.js` (all 176 frame vectors of F3-22, valid and invalid, the 54 `file.list` body vectors, plus the drift check), `traces.test.js` (the 26
+`npm test` (node:test). Contract 2.1: `contract-v21.test.js`, `webhook-receiver.test.js` (assembler, handler, the 8 traces, end to end), `llm-key.test.js` (including the sweep for the key), `test/incident-detector/size-model.test.js`. The incident detector (F3-11b) is in `test/incident-detector/` (`parity.test.js` against `parity.vectors.json`, `units`, `sources`, `wiring`); the rest of v2 in `test/la-protocol-v2/`:
+`contract.test.js` (all 294 frame vectors of F3-22 + 2.1, valid and invalid, the 54 `file.list` body vectors, plus the drift check), `traces.test.js` (the 34
 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`), and for F3-07b

package/env.example

@@ -85,4 +85,16 @@ LOG_LEVEL=info
 # LOCAL_AGENT_CONTENT_ALLOW_HARDLINKS=true   serve files with more than one hard link (refused by default)
 # LOCAL_AGENT_CONTENT_INDEX_MAX_IDS=2048     live ids announced to the gateway in content.index (max 2048)
 # LOCAL_AGENT_CONTENT_MAX_DIR_ENTRIES=20000  file.list: a folder with more entries is payload_too_large (100..200000)
+# LOCAL_AGENT_INCIDENT_DETECTOR=true   detects errors in the customer's logs and sends incident.candidate (metadata only; the text stays in a local store).
+#                                      Needs LOCAL_AGENT_PROTOCOL_V2=true and at least one source:
+# LOCAL_AGENT_INCIDENT_LOG_FILES=/var/log/app/api.log,/var/log/app/worker.log   (tailed; new lines only)
+# LOCAL_AGENT_INCIDENT_LOKI_URL=http://loki:3100  + LOCAL_AGENT_INCIDENT_LOKI_QUERY='{app="api"}'  (+ _LOKI_TOKEN, _LOKI_ORG)
+# LOCAL_AGENT_INCIDENT_STDIN=true      read log lines from the agent's own stdin
+# LOCAL_AGENT_INCIDENT_STORE_DIR=~/.deepdebug/incidents   LOCAL_AGENT_INCIDENT_WINDOW_MS=300000   LOCAL_AGENT_INCIDENT_FLUSH_MS=30000
+# LOCAL_AGENT_INCIDENT_MAX_EMITS_PER_MINUTE=60   LOCAL_AGENT_INCIDENT_MAX_PENDING=500   LOCAL_AGENT_INCIDENT_MAX_TRACKED=5000
+# LOCAL_AGENT_WEBHOOK_FORWARD=true     receives the webhook bodies the control plane strips and forwards (webhook.forward, one frame <= 9216 bytes or chunks up to 1 MiB),
+#                                      rebuilds them in memory, verifies the sha256 and hands them to the incident detector. Needs LOCAL_AGENT_PROTOCOL_V2=true AND
+#                                      LOCAL_AGENT_INCIDENT_DETECTOR=true (the local consumer). Tighten only: LOCAL_AGENT_WEBHOOK_MAX_BYTES, _MAX_OPEN, _MAX_BUFFERED_BYTES, _ASSEMBLY_MS, _MAX_ENTRIES. LOCAL_AGENT_WEBHOOK_DELIVERY_MS (default 10000, max 14000: how long the final ack waits for the local delivery), _DEDUPE_MS (600000) and _DEDUPE_MAX (1024): resends of a delivered webhookId are acked without reprocessing
+# LOCAL_AGENT_LLM_KEY=true             accepts the virtual key of the AI gateway (config.update llmKey): in memory only, never logged or returned in an ack. Needs LOCAL_AGENT_PROTOCOL_V2=true
+# LOCAL_AGENT_LLM_KEY_FILE=/var/lib/deepdebug/llm-key.json   optional: keep the key across restarts (mode 0600, directory 0700, MUST be outside every workspace)
 # LOCAL_AGENT_CONTENT_DENY_GLOBS=a/,*.x      extra deny globs (they add to the built-in list: .env*, keys, credentials files, secrets/ ...)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepdebug-local-agent",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "DeepDebug Local Agent - AI-powered code debugging assistant",
   "private": false,
   "type": "module",

package/scripts/incident-parity/Gen.java

@@ -0,0 +1,256 @@
+import io.visionhammer.agents.monitor.detector.ErrorDetector;
+import io.visionhammer.agents.monitor.model.LogEntry;
+import io.visionhammer.agents.shared.logs.LogNoiseClassifier;
+import io.visionhammer.agents.shared.service.IncidentFingerprintGenerator;
+import java.lang.reflect.Method;
+import java.time.Instant;
+import java.util.*;
+
+/** Runs the REAL Java (see extract.py) over a corpus and prints the parity vectors as JSON (ASCII only: every non-ASCII char is a \\uXXXX escape). */
+public class Gen {
+    record C(String name, String service, String severity, String message, String stack) {}
+
+    static final List<C> CASES = new ArrayList<>();
+    static void c(String name, String service, String sev, String message, String stack) { CASES.add(new C(name, service, sev, message, stack)); }
+
+    static final String JAVA_STACK = "java.lang.IllegalStateException: order 4711 not found\n"
+            + "\tat org.springframework.web.method.support.InvocableHandlerMethod.invoke(InvocableHandlerMethod.java:205)\n"
+            + "\tat io.visionhammer.billing.OrderService.load(OrderService.java:88)\n"
+            + "\tat io.visionhammer.billing.OrderController.get(OrderController.java:41)\n";
+
+    static {
+        c("java-npe", "billing-api", "ERROR", "java.lang.NullPointerException: Cannot invoke \"String.length()\" because \"s\" is null", "java.lang.NullPointerException: Cannot invoke \"String.length()\" because \"s\" is null\n\tat com.acme.Foo.bar(Foo.java:12)\n\tat com.acme.Main.main(Main.java:5)");
+        c("java-ids-4711", "billing-api", "ERROR", "java.lang.IllegalStateException: order 4711 not found", JAVA_STACK);
+        c("java-ids-9002", "billing-api", "ERROR", "java.lang.IllegalStateException: order 9002 not found", JAVA_STACK.replace("4711", "9002"));
+        c("java-ids-99999-long-int", "billing-api", "ERROR", "java.lang.IllegalStateException: order 123456 not found", JAVA_STACK);
+        c("framework-frames-only", "svc", "ERROR", "boom", "org.springframework.X: boom\n\tat org.springframework.a.B.c(B.java:1)\n\tat reactor.core.Y.z(Y.java:2)\n\tat java.base/java.lang.Thread.run(Thread.java:1583)");
+        c("frame-line-numbers", "svc", "ERROR", "failed", "com.x.Err: failed\n\tat com.x.A.m(A.java:123)\n");
+        c("frame-kotlin-swift-py-js-ts-rb-go", "svc", "ERROR", "failed", "Err: failed\n\tat app/Foo.kt:77\n");
+        c("frame-swift", "ios", "ERROR", "crash", "Fatal error\n\tat Foo.swift:99 in bar\n");
+        c("frame-hex-addr", "svc", "ERROR", "failed", "Err: x\n\tat com.x.A.m(Native Method @0xdeadbeef)\n");
+        c("frame-over-200", "svc", "ERROR", "failed", "Err: x\n\tat " + "a.".repeat(150) + "B.m(B.java:1)\n");
+        c("caused-by-first", "svc", "ERROR", "wrapper failure", "Caused by: java.io.IOException: disk full\n\tat com.x.Disk.write(Disk.java:9)\n");
+        c("no-colon-type", "svc", "ERROR", "oops", "NullPointerException\n\tat com.x.A.m(A.java:1)\n");
+        c("type-colon-then-space", "svc", "ERROR", "oops", "a.b.Exc: text with spaces\n\tat com.x.A.m(A.java:1)\n");
+        c("type-space-then-colon", "svc", "ERROR", "oops", "Exception in thread main: x\n\tat com.x.A.m(A.java:1)\n");
+        c("crlf-stack", "svc", "ERROR", "oops", "a.b.Exc: text\r\n\tat com.x.A.m(A.java:1)\r\n\tat com.x.B.n(B.java:2)\r\n");
+        c("empty-stack", "svc", "ERROR", "com.acme.Thing: bad input 42", "");
+        c("null-stack", "svc", "ERROR", "com.acme.Thing: bad input 42", null);
+        c("blank-stack", "svc", "ERROR", "com.acme.Thing: bad input 42", "   \n  ");
+        c("msg-dotted-type", "svc", "ERROR", "io.netty.channel.ClosedChannelException: closed", null);
+        c("msg-undotted-type", "svc", "ERROR", "ClosedChannelException: closed", null);
+        c("msg-colon-after-space", "svc", "ERROR", "Error: something broke", null);
+        c("pg-error", "db", "ERROR", "2026-10-29 10:00:01.123 UTC [4242]: [3-1] db=app,user=u ERROR: duplicate key value violates unique constraint \"pk_orders\"", null);
+        c("pg-fatal", "db", "FATAL", "2026-10-29 10:00:01 UTC [4242]: [3-1] FATAL: terminating connection due to administrator command", null);
+        c("pg-warning", "db", "ERROR", "2026-10-29 10:00:01 UTC [77]: [1-1] WARNING: there is no transaction in progress", null);
+        c("pg-preamble-lowercase", "db", "ERROR", "2026-10-29 10:00:01 utc [77]: [1-1] error: relation \"x\" does not exist", null);
+        c("pg-preamble-no-keyword", "db", "ERROR", "2026-10-29 10:00:01 UTC [77]: [1-1] LOG: connection received", null);
+        c("iso-ts-variants", "svc", "ERROR", "failed at 2026-10-29T10:00:01.123456Z and 2026-10-29 10:00:01+01:00 and 2026-10-29T10:00:01 CEST done", null);
+        c("iso-ts-offset-nocolon", "svc", "ERROR", "failed at 2026-10-29T10:00:01-0300 end", null);
+        c("uuids-and-addrs", "svc", "ERROR", "obj 3f2b8c1e-5a4d-4e7b-9c21-0a1b2c3d4e5f at 0xDEADBEEF and @7f3a9c21 pid [12345] [7]", null);
+        c("uuid-uppercase", "svc", "ERROR", "obj 3F2B8C1E-5A4D-4E7B-9C21-0A1B2C3D4E5F failed", null);
+        c("bracket-pid", "svc", "ERROR", "worker [12] [123] [12345] crashed", null);
+        c("long-ints", "svc", "ERROR", "user 12345 order 1234 amount 99999999 x12345y id-12345 12345-id", null);
+        c("urls", "gw", "ERROR", "HTTP 500 POST https://svc-abc123-uc.a.run.app/api/v1/x?id=42 failed; retry http://localhost:8080/health", null);
+        c("urls-two-hostnames", "gw", "ERROR", "HTTP 500 POST https://svc-1234567890-uc.a.run.app/api/v1/x", null);
+        c("urls-two-hostnames-b", "gw", "ERROR", "HTTP 500 POST https://svc-1234567890.europe-west1.run.app/api/v1/x", null);
+        c("long-hex", "svc", "ERROR", "commit deadbeefcafe1234 and short beef12 and abcdef0123456789abcdef", null);
+        c("versions", "build", "ERROR", "maven-compiler-plugin:3.13.0 vs :3.1 and 1.2.3.4 and 10.0", null);
+        c("addr-0x", "svc", "ERROR", "segfault at 0x7ffee1234abc code 0X1F", null);
+        c("digits", "svc", "ERROR", "line 12 col 7 offset 0 size 100", null);
+        c("first-line-only", "svc", "ERROR", "first line 1\nsecond line 2\nthird 3", null);
+        c("first-line-crlf", "svc", "ERROR", "first line 1\r\nsecond line 2", null);
+        c("leading-newline", "svc", "ERROR", "\nreal text 5", null);
+        c("empty-message", "svc", "ERROR", "", null);
+        c("null-message", "svc", "ERROR", null, null);
+        c("only-ws-message", "svc", "ERROR", "   \t  ", null);
+        c("nbsp-message", "svc", "ERROR", " ", null);
+        c("nbsp-inside", "svc", "ERROR", "Error: connection refused  to   host", null);
+        c("unicode-space-inside", "svc", "ERROR", "Error: em space　ideographic narrow
linesep done", null);
+        c("form-feed-vt", "svc", "ERROR", "Error:\u000bvt\u000cff\u001cfs done", null);
+        c("trim-control-chars", "svc", "ERROR", "\u0001\u0002 Error: ctl \u0003\u001f", null);
+        c("kelvin-and-dotted-i", "svc", "ERROR", "ERROR K İSTANBUL ÉCOLE Straße ΣΣ café 12", null);
+        c("greek-final-sigma", "svc", "ERROR", "ΟΔΥΣΣΕΥΣ failed 7", null);
+        c("non-ascii-adjacent-hex", "svc", "ERROR", "édeadbeefcafe12é and xé 123", null);
+        c("non-ascii-word-boundary", "svc", "ERROR", "café123456789abcdef and ü0123456789ab", null);
+        c("cjk-emoji", "svc", "ERROR", "错误: 连接失败 💥 code 500", null);
+        c("lone-surrogate", "svc", "ERROR", "bad \ud800 surrogate and \udc00 more 5", null);
+        c("surrogate-split-at-500", "svc", "ERROR", "x".repeat(499) + "💥 tail", null);
+        c("len-499", "svc", "ERROR", "y".repeat(499), null);
+        c("len-500", "svc", "ERROR", "y".repeat(500), null);
+        c("len-501", "svc", "ERROR", "y".repeat(501), null);
+        c("len-2000-with-numbers", "svc", "ERROR", ("error 12 abc ").repeat(160), null);
+        c("legacy-1000-boundary", "svc", "ERROR", "z".repeat(1005), null);
+        c("legacy-colon-numbers", "svc", "ERROR", "failed at Foo.java:123:45 and :99", null);
+        c("legacy-ts", "svc", "ERROR", "boom at 2026-10-29T10:00:01.123Z+01:00 done", null);
+        c("severity-fatal-no-pattern", "svc", "FATAL", "the process has quit", null);
+        c("severity-critical-no-pattern", "svc", "critical", "the process has quit", null);
+        c("severity-warn", "svc", "WARN", "java.lang.RuntimeException: x", "at a.B.c(B.java:1)");
+        c("severity-info", "svc", "INFO", "all good", null);
+        c("severity-error-plain", "svc", "ERROR", "plain failure without markers", null);
+        c("severity-null", "svc", null, "java.lang.RuntimeException: x", null);
+        c("severity-severe", "svc", "SEVERE", "java.lang.RuntimeException: x", null);
+        c("severity-emerg", "svc", "emerg", "something happened", null);
+        c("noise-healthcheck", "svc", "ERROR", "GET /actuator/health Exception", null);
+        c("noise-broken-pipe", "svc", "ERROR", "IOException: Broken pipe", null);
+        c("noise-ping", "svc", "ERROR", "GET /ping  Exception", null);
+        c("noise-ping-nospace", "svc", "ERROR", "GET /ping Exception", null);
+        c("noise-favicon", "svc", "ERROR", "Error: favicon.ico missing", null);
+        c("noise-conn-reset", "svc", "ERROR", "Error: Connection reset by peer", null);
+        c("sig-java-frame-in-message", "svc", "ERROR", "failure\n\tat com.x.A.m(A.java:12)", null);
+        c("sig-java-frame-in-stack", "svc", "ERROR", "failure header", "x\n\tat com.x.A.m(A.java:12)");
+        c("sig-swift", "ios", "ERROR", "failure Foo.swift:12", null);
+        c("sig-node", "node", "ERROR", "failure (/app/dist/x.js:10:5)", null);
+        c("sig-python", "py", "ERROR", "Traceback\n  File \"/app/main.py\", line 3, in x", null);
+        c("sig-deno", "edge", "ERROR", "failure at file:///src/fn/index.ts:12:3", null);
+        c("sig-generic-exception", "svc", "ERROR", "some Exception happened", null);
+        c("sig-generic-error-colon", "svc", "ERROR", "TypeError: x is not a function", null);
+        c("sig-http-500", "svc", "ERROR", "request done HTTP 503 upstream", null);
+        c("sig-http-404-lower", "svc", "ERROR", "http 404 not found", null);
+        c("sig-http-200", "svc", "ERROR", "HTTP 200 ok", null);
+        c("noise-infra-code", "run", "ERROR", "{code=9, message=Ready condition status changed to False}", null);
+        c("noise-infra-oom", "run", "ERROR", "Memory limit of 1024 MiB exceeded with 1100 MiB used", null);
+        c("noise-infra-signal", "run", "ERROR", "Uncaught signal: 13, pid=136, tid=136", null);
+        c("noise-infra-probe", "run", "ERROR", "Default STARTUP TCP probe failed 1 time consecutively for container x", null);
+        c("noise-not-probe", "svc", "ERROR", "Writer probe failed", null);
+        c("noise-infra-audit", "run", "ERROR", "AUDIT EVENT: method=/Services.ReplaceService resource=x", null);
+        c("noise-infra-auditlog-map", "run", "ERROR", "{@type=type.googleapis.com/google.cloud.audit.AuditLog, x=1}", null);
+        c("noise-infra-mongo", "svc", "ERROR", "com.mongodb.MongoSocketWriteException: Exception sending message", null);
+        c("noise-infra-sqlconn", "svc", "ERROR", "The request failed because either the HTTP response was malformed or", null);
+        c("noise-infra-leading-ws", "run", "ERROR", "  \t{code=9, message=x}", null);
+        c("noise-infra-leading-nbsp", "run", "ERROR", " {code=9, message=x}", null);
+        c("noise-infra-leading-emsp", "run", "ERROR", " {code=9, message=x}", null);
+        c("noise-build-maven", "ci", "ERROR", "Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.13.0:compile", null);
+        c("noise-build-lifecycle", "ci", "ERROR", "org.apache.maven.lifecycle.LifecycleExecutionException: x", null);
+        c("noise-build-gradle", "ci", "ERROR", "Execution failed for task ':app:compileJava'.", null);
+        c("noise-build-gradle2", "ci", "ERROR", "FAILURE: Build failed with an exception.", null);
+        c("noise-blank", "svc", "ERROR", "   ", null);
+        c("python-trace", "py", "ERROR", "ValueError: invalid literal for int() with base 10: 'abc'", "Traceback (most recent call last):\n  File \"/app/main.py\", line 12, in <module>\n    int('abc')\nValueError: invalid literal for int() with base 10: 'abc'");
+        c("node-trace", "node", "ERROR", "TypeError: Cannot read properties of undefined (reading 'id')", "TypeError: Cannot read properties of undefined (reading 'id')\n    at handler (/app/src/h.js:10:15)\n    at Layer.handle [as handle_request] (/app/node_modules/express/lib/router/layer.js:95:5)");
+        c("tab-indented-at", "svc", "ERROR", "x", "a.B: x\n   at com.x.Y.z(Y.java:3)\n");
+        c("jdk-internal-skipped", "svc", "ERROR", "x", "a.B: x\n\tat jdk.internal.reflect.X.y(X.java:1)\n\tat com.x.Real.z(Real.java:3)\n");
+        c("proxy-skipped", "svc", "ERROR", "x", "a.B: x\n\tat com.sun.$Proxy12.run(Unknown Source)\n\tat com.x.Real.z(Real.java:3)\n");
+        c("apache-netty-r2dbc-skipped", "svc", "ERROR", "x", "a.B: x\n\tat org.apache.A.b(A.java:1)\n\tat io.netty.C.d(C.java:2)\n\tat io.r2dbc.E.f(E.java:3)\n\tat com.fasterxml.G.h(G.java:4)\n\tat javax.I.j(I.java:5)\n\tat jakarta.K.l(K.java:6)\n\tat com.x.Real.z(Real.java:3)\n");
+        c("fallback-first-at-when-all-skipped", "svc", "ERROR", "x", "a.B: x\n\tat java.base/java.lang.Thread.run(Thread.java:1583)\n\tat org.springframework.Z.y(Z.java:9)\n");
+        c("frame-with-contains-reflect", "svc", "ERROR", "x", "a.B: x\n\tat com.x.java.lang.reflect.Foo.m(Foo.java:1)\n\tat com.x.Real.z(Real.java:3)\n");
+        c("long-frame-300", "svc", "ERROR", "x", "a.B: x\n\tat com.x." + "q".repeat(300) + ".m(Foo.java:1)\n");
+        c("service-differs-same-message", "svc-a", "ERROR", "java.lang.IllegalStateException: order 1 not found", null);
+        c("service-differs-same-message-b", "svc-b", "ERROR", "java.lang.IllegalStateException: order 1 not found", null);
+        c("linesep-only", "svc", "ERROR", "\u2028", null);
+        c("emsp-only", "svc", "ERROR", "\u2003\u3000\u1680\u205f", null);
+        c("narrow-nbsp-only", "svc", "ERROR", "\u202f", null);
+        c("figure-space-only", "svc", "ERROR", "\u2007", null);
+        c("fs-gs-rs-us-only", "svc", "ERROR", "\u001c\u001d\u001e\u001f", null);
+        c("stack-linesep-blank", "svc", "ERROR", "com.x.E: boom 1", "\u2028\u2003");
+        c("stack-nbsp-not-blank", "svc", "ERROR", "com.x.E: boom 1", "\u00a0Foo: bar\n\tat a.B.c(B.java:1)");
+        c("noise-leading-linesep", "run", "ERROR", "\u2028Memory limit of 1 MiB exceeded", null);
+        c("service-null", null, "ERROR", "java.lang.IllegalStateException: boom", null);
+    }
+
+    static LogEntry cp(LogEntry x) { return new LogEntry(x.getService(), x.getSeverity(), x.getMessage(), x.getStacktrace(), x.getTimestamp()); }
+    static Method NORM_MSG, NORM_FRAME;
+    static String esc(String s) {
+        if (s == null) return "null";
+        StringBuilder b = new StringBuilder("\"");
+        for (int i = 0; i < s.length(); i++) {
+            char ch = s.charAt(i);
+            switch (ch) {
+                case '"' -> b.append("\\\"");
+                case '\\' -> b.append("\\\\");
+                case '\n' -> b.append("\\n");
+                case '\r' -> b.append("\\r");
+                case '\t' -> b.append("\\t");
+                default -> { if (ch < 0x20 || ch > 0x7e) b.append(String.format("\\u%04x", (int) ch)); else b.append(ch); }
+            }
+        }
+        return b.append('"').toString();
+    }
+    static String nullable(Object o) { return o == null ? "null" : esc(o.toString()); }
+
+    public static void main(String[] a) throws Exception {
+        NORM_MSG = IncidentFingerprintGenerator.class.getDeclaredMethod("normaliseMessage", String.class); NORM_MSG.setAccessible(true);
+        NORM_FRAME = IncidentFingerprintGenerator.class.getDeclaredMethod("normaliseFrame", String.class); NORM_FRAME.setAccessible(true);
+        IncidentFingerprintGenerator fp = new IncidentFingerprintGenerator();
+        ErrorDetector det = new ErrorDetector();
+        StringBuilder o = new StringBuilder("{\n\"schema\": \"incident-parity-vectors/1\",\n\"cases\": [\n");
+        boolean first = true;
+        for (C k : CASES) {
+            LogEntry e = new LogEntry(k.service, k.severity, k.message, k.stack, null);
+            String msg = k.message;
+            String firstLine = msg == null ? "" : (msg.indexOf('\n') >= 0 ? msg.substring(0, msg.indexOf('\n')) : msg);
+            String errorType = fp.extractErrorType(msg, k.stack);
+            String frame = fp.extractFirstUserFrame(k.stack);
+            String fingerprint = fp.compute(errorType, frame, msg);
+            String legacy;
+            try { legacy = det.hash(e); } catch (Exception ex) { legacy = null; }
+            if (!first) o.append(",\n");
+            first = false;
+            o.append("{\"name\": ").append(esc(k.name))
+                    .append(", \"service\": ").append(nullable(k.service))
+                    .append(", \"severity\": ").append(nullable(k.severity))
+                    .append(", \"message\": ").append(nullable(k.message))
+                    .append(", \"stack\": ").append(nullable(k.stack))
+                    .append(", \"expect\": {")
+                    .append("\"significant\": ").append(det.isSignificant(e))
+                    .append(", \"groupKey\": ").append(nullable(msg == null ? GroupHash.normalizeGroupKey("") : GroupHash.normalizeGroupKey(firstLine)))
+                    .append(", \"groupHash\": ").append(nullable(GroupHash.computeGroupHash(e)))
+                    .append(", \"errorType\": ").append(nullable(errorType))
+                    .append(", \"firstFrame\": ").append(nullable(frame))
+                    .append(", \"normalisedMessage\": ").append(nullable(NORM_MSG.invoke(fp, msg)))
+                    .append(", \"normalisedFrame\": ").append(nullable(NORM_FRAME.invoke(fp, frame)))
+                    .append(", \"fingerprint\": ").append(nullable(fingerprint))
+                    .append(", \"noiseClass\": ").append(nullable(LogNoiseClassifier.classify(msg)))
+                    .append(", \"legacyHash\": ").append(nullable(legacy))
+                    .append("}}");
+        }
+        o.append("\n],\n\"dedup\": [\n");
+        // natural-key dedup (LogEntryDedup): same service|micros|md5(message) = same entry (an overlap re-read)
+        Instant t0 = Instant.parse("2026-10-29T10:00:00.123456789Z");
+        record D(String name, List<LogEntry> entries, List<String> known) {}
+        List<D> ds = new ArrayList<>();
+        LogEntry e1 = new LogEntry("api", "ERROR", "boom 1", null, t0);
+        LogEntry e1b = new LogEntry("api", "ERROR", "boom 1", null, t0);
+        LogEntry e2 = new LogEntry("api", "ERROR", "boom 1", null, t0.plusMillis(1));
+        LogEntry e3 = new LogEntry("api2", "ERROR", "boom 1", null, t0);
+        LogEntry e4 = new LogEntry("api", "ERROR", "boom 2", null, t0);
+        LogEntry e5 = new LogEntry("api", "ERROR", "no timestamp", null, null);
+        LogEntry e6 = new LogEntry(null, "ERROR", "null service", null, t0);
+        LogEntry e7 = new LogEntry("api", "ERROR", null, null, t0);
+        LogEntry e8 = new LogEntry("api", "ERROR", "x".repeat(9000), null, t0);
+        LogEntry e9 = new LogEntry("api", "ERROR", "x".repeat(8000) + "different tail", null, t0);
+        LogEntry e10 = new LogEntry("api", "ERROR", "café 💥 错误", null, Instant.parse("2026-10-29T10:00:00.999999Z"));
+        LogEntry e11 = new LogEntry("api", "ERROR", "boom 1", null, Instant.parse("1969-12-31T23:59:59.999999500Z"));
+        ds.add(new D("duplicates-in-batch", List.of(e1, e1b, e2, e3, e4), List.of()));
+        ds.add(new D("known-keys-skip", List.of(e1, e2, e3), List.of(LogEntryDedupPure.key(e1))));
+        ds.add(new D("no-timestamp-always-kept", List.of(e5, cp(e5), cp(e5)), List.of()));
+        ds.add(new D("null-service-and-message", List.of(e6, e7, cp(e6)), List.of()));
+        ds.add(new D("truncation-8000", List.of(e8, e9), List.of()));
+        ds.add(new D("unicode-and-micros", List.of(e10, cp(e10)), List.of()));
+        ds.add(new D("pre-epoch-micros", List.of(e11, cp(e11)), List.of()));
+        boolean f2 = true;
+        for (D d : ds) {
+            if (!f2) o.append(",\n");
+            f2 = false;
+            o.append("{\"name\": ").append(esc(d.name)).append(", \"entries\": [");
+            for (int i = 0; i < d.entries.size(); i++) {
+                LogEntry x = d.entries.get(i);
+                o.append(i > 0 ? ", " : "").append("{\"service\": ").append(nullable(x.getService())).append(", \"ts\": ").append(nullable(x.getTimestamp())).append(", \"message\": ").append(nullable(x.getMessage())).append("}");
+            }
+            o.append("], \"known\": [");
+            for (int i = 0; i < d.known.size(); i++) o.append(i > 0 ? ", " : "").append(esc(d.known.get(i)));
+            o.append("], \"keys\": [");
+            for (int i = 0; i < d.entries.size(); i++) o.append(i > 0 ? ", " : "").append(nullable(LogEntryDedupPure.key(d.entries.get(i))));
+            o.append("], \"kept\": [");
+            List<LogEntry> kept = LogEntryDedupPure.filterNew(d.entries, new HashSet<>(d.known));
+            boolean fk = true;
+            for (LogEntry x : kept) {
+                int idx = -1;
+                for (int i = 0; i < d.entries.size(); i++) if (d.entries.get(i) == x) { idx = i; break; }
+                o.append(fk ? "" : ", ").append(idx); fk = false;
+            }
+            o.append("]}");
+        }
+        o.append("\n]\n}\n");
+        System.out.print(o);
+    }
+}

package/scripts/incident-parity/LogEntry.java

@@ -0,0 +1,17 @@
+package io.visionhammer.agents.monitor.model;
+
+import java.time.Instant;
+
+/** Test stub: only the getters the code under test reads (the real one is a Lombok builder). */
+public class LogEntry {
+    private final String service, severity, message, stacktrace;
+    private final Instant timestamp;
+    public LogEntry(String service, String severity, String message, String stacktrace, Instant timestamp) {
+        this.service = service; this.severity = severity; this.message = message; this.stacktrace = stacktrace; this.timestamp = timestamp;
+    }
+    public String getService() { return service; }
+    public String getSeverity() { return severity; }
+    public String getMessage() { return message; }
+    public String getStacktrace() { return stacktrace; }
+    public Instant getTimestamp() { return timestamp; }
+}

package/scripts/incident-parity/extract.py

@@ -0,0 +1,51 @@
+"""Cuts the Java under test out of visionhammer-agents into <work>/ (annotations stripped, behaviour verbatim)."""
+import re, sys
+agents, work = sys.argv[1:3]
+def read(p):
+    return open(f"{agents}/{p}", encoding="utf-8").read()
+def method(src, header_regex):
+    """Source of the method whose signature matches, balanced on braces."""
+    m = re.search(header_regex, src)
+    assert m, header_regex
+    i = src.index("{", m.end() - 1 if src[m.end() - 1] == "{" else m.end())
+    depth, j = 0, i
+    while True:
+        c = src[j]
+        if c == "{": depth += 1
+        elif c == "}":
+            depth -= 1
+            if depth == 0: break
+        j += 1
+    return src[m.start():j + 1]
+def strip(src):
+    out = []
+    for line in src.splitlines():
+        s = line.strip()
+        if s in ("@Component", "@Slf4j", "@RequiredArgsConstructor") or s.startswith(("import lombok", "import org.springframework", "import reactor")):
+            continue
+        out.append(line)
+    return "\n".join(out) + "\n"
+# 1. IncidentFingerprintGenerator and LogNoiseClassifier: whole files
+open(f"{work}/IncidentFingerprintGenerator.java", "w").write(strip(read("shared/src/main/java/io/visionhammer/agents/shared/service/IncidentFingerprintGenerator.java")))
+open(f"{work}/LogNoiseClassifier.java", "w").write(read("shared/src/main/java/io/visionhammer/agents/shared/logs/LogNoiseClassifier.java"))
+# 2. ErrorDetector: whole file (needs the LogEntry stub, same package of the stub)
+ed = strip(read("monitor-service/src/main/java/io/visionhammer/agents/monitor/detector/ErrorDetector.java"))
+open(f"{work}/ErrorDetector.java", "w").write(ed)
+# 3. the two pure statics of MonitorPollScheduler
+sch = read("monitor-service/src/main/java/io/visionhammer/agents/monitor/scheduler/MonitorPollScheduler.java")
+g1 = method(sch, r"static String computeGroupHash\(LogEntry entry\) \{")
+g2 = method(sch, r"static String normalizeGroupKey\(String firstLine\) \{")
+open(f"{work}/GroupHash.java", "w").write("import io.visionhammer.agents.monitor.model.LogEntry;\npublic final class GroupHash {\n" + g1 + "\n" + g2 + "\n}\n")
+# 4. the pure statics of LogEntryDedup
+dd = read("monitor-service/src/main/java/io/visionhammer/agents/monitor/service/LogEntryDedup.java")
+parts = [
+    r"public static final int MAX_MESSAGE_CHARS = 8000;",
+]
+body = ["    public static final int MAX_MESSAGE_CHARS = 8000;"]
+for hdr in [r"public static String key\(LogEntry e\) \{", r"public static String storedMessage\(String message\) \{",
+            r"static String keyOf\(String source, Instant ts, String storedMessage\) \{", r"private static long micros\(Instant ts\) \{",
+            r"static String md5Hex\(String s\) \{", r"public static List<LogEntry> filterNew\(List<LogEntry> entries, Set<String> known\) \{"]:
+    body.append(method(dd, hdr))
+open(f"{work}/LogEntryDedupPure.java", "w").write(
+    "import java.nio.charset.StandardCharsets;\nimport java.security.MessageDigest;\nimport java.time.Instant;\nimport java.time.temporal.ChronoUnit;\n"
+    "import java.util.*;\nimport io.visionhammer.agents.monitor.model.LogEntry;\npublic final class LogEntryDedupPure {\n" + "\n".join(body) + "\n}\n")

package/scripts/incident-parity/gen.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# F3-11b: regenerates test/incident-detector/parity.vectors.json FROM THE JAVA CODE (the source of truth), so the Node
+# detector can be proven byte-identical. Usage: scripts/incident-parity/gen.sh <visionhammer-agents checkout> [out.json]
+# Needs JDK 21 (javac/java on PATH, or JAVA_HOME). The Java sources are used VERBATIM: only the Lombok/Spring annotations and
+# the r2dbc imports are stripped (they are not behaviour), and the pure static methods are cut out of their classes.
+set -euo pipefail
+AGENTS="${1:?path to a visionhammer-agents checkout (release/qa)}"
+HERE="$(cd "$(dirname "$0")" && pwd)"
+OUT="${2:-$HERE/../../test/incident-detector/parity.vectors.json}"
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+JAVAC="${JAVA_HOME:+$JAVA_HOME/bin/}javac"; JAVA="${JAVA_HOME:+$JAVA_HOME/bin/}java"
+python3 -I "$HERE/extract.py" "$AGENTS" "$WORK"
+cp "$HERE"/Gen.java "$HERE"/LogEntry.java "$WORK/"
+( cd "$WORK" && "$JAVAC" -d out *.java && "$JAVA" -cp out Gen > "$WORK/vectors.json" )
+python3 -I - "$AGENTS" "$WORK/vectors.json" "$OUT" <<'PY'
+import hashlib, json, subprocess, sys
+agents, src, out = sys.argv[1:4]
+commit = subprocess.run(["git", "-C", agents, "rev-parse", "HEAD"], capture_output=True, text=True).stdout.strip()
+files = ["shared/src/main/java/io/visionhammer/agents/shared/service/IncidentFingerprintGenerator.java",
+         "shared/src/main/java/io/visionhammer/agents/shared/logs/LogNoiseClassifier.java",
+         "monitor-service/src/main/java/io/visionhammer/agents/monitor/detector/ErrorDetector.java",
+         "monitor-service/src/main/java/io/visionhammer/agents/monitor/scheduler/MonitorPollScheduler.java",
+         "monitor-service/src/main/java/io/visionhammer/agents/monitor/service/LogEntryDedup.java"]
+sha = {f: hashlib.sha256(open(f"{agents}/{f}", "rb").read()).hexdigest() for f in files}
+d = json.load(open(src))
+d["source"] = {"repo": "VISIONHAMMER/visionhammer-agents", "commit": commit, "files": sha,
+               "note": "generated by scripts/incident-parity/gen.sh from the Java code; do not edit by hand"}
+json.dump(d, open(out, "w"), indent=1, ensure_ascii=True)
+open(out, "a").write("\n")
+print("wrote", out, len(d["cases"]), "cases", len(d["dedup"]), "dedup cases")
+PY

package/src/incident-detector/README.md

@@ -0,0 +1,52 @@
+# Incident detector (F3-11b)
+
+The Local Agent reads the customer's logs, detects errors with the **same rules as the Java monitor** and sends `incident.candidate`
+(metadata only) on the protocol v2 session. The text of the error (message, stack trace) stays on the customer's machine.
+
+Flag: `LOCAL_AGENT_INCIDENT_DETECTOR=true` (default **false**; needs `LOCAL_AGENT_PROTOCOL_V2=true`, the module is only started from
+`la-protocol-v2/runtime.js`). With the flag off only `config.js` is loaded: no source is opened, nothing is read or sent.
+
+## Flow
+
+`source -> parse -> (natural-key dedup) -> isSignificant -> noise filter -> errorHash + fingerprint -> local store + aggregator -> emitter -> session`
+
+| file | what |
+|---|---|
+| `java-compat.js`, `normalize.js` | the Java rules ported with the `java.lang.String` quirks (`\s`, `trim`, `isBlank`, lone surrogates). Proven by `test/incident-detector/parity.vectors.json` |
+| `parse.js` | JSON lines and plain text (multi-line stack traces) -> entries |
+| `sources/file-source.js` | tail of files (new lines only, rotation/truncation, bounded reads) |
+| `sources/loki-source.js` | polls a Loki (`query_range`), cursor, byte and time limits |
+| `sources/stream-source.js` | any Readable (the agent's stdin); a slow consumer pauses the stream |
+| `aggregator.js` | per-`errorHash` windows: leading edge at once, batched updates, final update at window close, LRU bound |
+| `store.js` | local JSONL detail store (0600, rotates, DLP-masked). `getDetail(errorHash)` is the hook for `incident.detail` |
+| `emitter.js` | the frame: 9 contract fields, DLP on labels, token bucket, one frame in flight, backoff, coalescing |
+| `detector.js`, `index.js` | glue |
+
+## What goes out, what stays
+
+Out: `errorHash` (32 hex = sha256 prefix of the normalised FIRST line, Java `computeGroupHash`), `fingerprint` (64 hex, Java
+`IncidentFingerprintGenerator`), `severity`, `service`, `environment`, `count`, `firstSeen`, `lastSeen` (the window), `logCategory`.
+Contract 2.1 adds two optional numbers/labels, sent ONLY when the CP listed `incident.candidate.size-model` in `ready.capabilities`: `stackBytes` (UTF-8 size of the biggest stack of the window,
+saturating at 16 MiB) and `model` (`stack-detector-<agent version>`). There is still no field for text. The size is also in the local store (`stackBytes`).
+Stays: message, stack, everything else, in `LOCAL_AGENT_INCIDENT_STORE_DIR` (default `~/.deepdebug/incidents`).
+
+## Window semantics (for the control plane, F3-11c)
+
+One window per `errorHash`, `LOCAL_AGENT_INCIDENT_WINDOW_MS` (5 min) from its first occurrence. Every candidate of a window has the same
+`firstSeen`; `count` only grows. `(errorHash, firstSeen)` identifies the window: upsert on it. The first occurrence is sent at once
+(count 1); later ones in batches at most every `LOCAL_AGENT_INCIDENT_FLUSH_MS` (30 s), plus a final update when the window closes.
+
+## Hooks that are NOT built
+
+- **Alloy / OTLP receiver**: the LA has no OTLP receiver today. A source is an object `{name, start(onEntries), stop()}` where
+  `onEntries(entries)` takes `{severity, message, stacktrace, service, tsMs}`; an OTLP/Alloy source plugs in the same way (`buildSources` in `index.js`).
+- **Cloud providers (CloudWatch/GCP/Azure)**: F3-11d.
+- **`content.request` kind `incident.detail`**: the contract/gateway define the kind but not the `ref` scheme; `link.incidents.getDetail(errorHash, {limit})` is ready
+  to be called by a handler (the DLP of the content handlers then applies on the way out).
+
+## Parity vectors
+
+`scripts/incident-parity/gen.sh <visionhammer-agents checkout>` runs the real Java (ErrorDetector, MonitorPollScheduler.computeGroupHash,
+IncidentFingerprintGenerator, LogNoiseClassifier, LogEntryDedup) over a corpus and rewrites `test/incident-detector/parity.vectors.json`
+(with the commit and sha256 of the Java files). Regenerate when the Java rules change; `npm test` then says what diverged.
+`ErrorDetector.hash` (legacy `service|message` hash) is in the vectors but not ported: Java only falls back to it when `computeGroupHash` throws.

package/src/incident-detector/aggregator.js

@@ -0,0 +1,78 @@
+/**
+ * aggregator.js - dedup and windows of detected errors (F3-11b).
+ *
+ * Java dedups on (tenant, errorHash) in incident_dedup_log: one row per hash with occurrences/first_seen/last_seen, and the
+ * cooldown lives in the control plane. Here the same key (errorHash) is aggregated in WINDOWS so what is sent is bounded:
+ *
+ *   window     from the first occurrence of an errorHash, `windowMs` long (processing time). Every candidate of that window has
+ *              the same firstSeen, so (errorHash, firstSeen) identifies the window and `count` only grows: the control plane can
+ *              upsert on it.
+ *   emission   leading edge: the FIRST occurrence of a window is emitted at once (count 1). Later occurrences are batched: one
+ *              update per `flushMs` while the count changes, and a final one when the window closes with something not yet sent.
+ *   bounds     at most `maxTracked` hashes at once. Beyond it the least recently seen one is closed (final update if it has one
+ *              pending) and counted as evicted. A hash that comes back after its window closed opens a new window.
+ *   severity   the highest seen in the window. fingerprint/service/logCategory: those of the first occurrence.
+ *   stackBytes the biggest stack (UTF-8 bytes) seen in the window, saturating at 16 MiB (contract 2.1 (c)); 0 = no stack.
+ * Pure: no timers, no I/O. The detector calls tick() on an interval.
+ */
+import { maxSeverity } from "./categorize.js";
+
+const MAX_STACK_BYTES = 16 * 1024 * 1024;   // contract 2.1: incident.candidate.stackBytes saturates here
+
+export function createAggregator({ windowMs, flushMs, maxTracked, now = Date.now, onCandidate }) {
+    const states = new Map();   // errorHash -> state (insertion order = least recently seen first)
+    const stats = { observed: 0, windows: 0, emitted: 0, evicted: 0 };
+
+    const snapshot = (s) => ({
+        errorHash: s.errorHash, fingerprint: s.fingerprint, severity: s.severity, service: s.service, environment: s.environment,
+        count: s.count, firstSeen: s.firstSeen, lastSeen: s.lastSeen, logCategory: s.logCategory, windowStart: s.windowStart, stackBytes: s.stackBytes,
+    });
+    const send = (s, t) => { s.sentCount = s.count; s.lastEmitAt = t; stats.emitted++; onCandidate(snapshot(s)); };
+    const close = (s, t) => { states.delete(s.errorHash); if (s.count > s.sentCount) send(s, t); };
+
+    return {
+        stats,
+        get tracked() { return states.size; },
+        /** @returns {{opened: boolean, windowStart: number}} opened = this occurrence opened a new window. */
+        observe({ errorHash, fingerprint, severity, service, environment, logCategory, tsMs, stackBytes = 0 }) {
+            const size = Number.isFinite(stackBytes) && stackBytes > 0 ? Math.min(Math.trunc(stackBytes), MAX_STACK_BYTES) : 0;
+            const t = now();
+            stats.observed++;
+            const seenAt = Number.isFinite(tsMs) && tsMs >= 0 ? Math.min(tsMs, t) : t;   // never in the future, never before the epoch (the log line is untrusted)
+            let s = states.get(errorHash);
+            if (s && t - s.windowStart >= windowMs) { close(s, t); s = undefined; }
+            if (!s) {
+                while (states.size >= maxTracked) {
+                    const oldest = states.values().next().value;
+                    stats.evicted++;
+                    close(oldest, t);
+                }
+                s = { errorHash, fingerprint, severity, service, environment, logCategory, count: 0, sentCount: 0, stackBytes: size, firstSeen: seenAt, lastSeen: seenAt, windowStart: t, lastEmitAt: 0 };
+                stats.windows++;
+                s.count = 1;
+                states.set(errorHash, s);
+                send(s, t);
+                return { opened: true, windowStart: s.windowStart };
+            }
+            states.delete(errorHash);   // move to the most recent position
+            states.set(errorHash, s);
+            s.count++;
+            s.severity = maxSeverity(s.severity, severity);
+            if (size > s.stackBytes) s.stackBytes = size;   // the biggest stack seen in the window (contract 2.1 (c))
+            // firstSeen never changes inside a window (it is part of the window identity), even for an out-of-order line
+            if (seenAt > s.lastSeen) s.lastSeen = seenAt;
+            if (t - s.lastEmitAt >= flushMs) send(s, t);
+            return { opened: false, windowStart: s.windowStart };
+        },
+        /** Sends the updates that are due and closes the windows that ended. */
+        tick() {
+            const t = now();
+            for (const s of [...states.values()]) {
+                if (t - s.windowStart >= windowMs) close(s, t);
+                else if (s.count > s.sentCount && t - s.lastEmitAt >= flushMs) send(s, t);
+            }
+        },
+        /** Sends everything not sent yet and forgets the windows (shutdown). */
+        drain() { const t = now(); for (const s of [...states.values()]) close(s, t); },
+    };
+}