deepdebug-local-agent 1.1.0 → 1.2.0

package/.github/workflows/npm-publish.yml

@@ -64,7 +64,7 @@ jobs:
           git add package-lock.json || true
           git diff --staged --quiet || git commit -m "chore: update package-lock.json [skip ci]"
 
-      - name: Bump version (patch, or the exact dispatch input)
+      - name: Bump version (semantic, from the commits; or the exact dispatch input)
         env:
           INPUT_VERSION: ${{ github.event_name == 'workflow_dispatch' && inputs.version || '' }}
         run: |
@@ -77,15 +77,22 @@ jobs:
           LATEST_TAG="${LATEST_TAG#v}"
           PKG="$(node -p "require('./package.json').version")"
           BASE="$(printf '%s\n%s\n' "${LATEST_TAG:-0.0.0}" "$PKG" | sort -V | tail -1)"
-          # Compute the next patch version up front and bump in ONE `npm version`
-          # call. A separate `npm version "$BASE" --no-git-tag-version` rewrites
-          # package.json/package-lock.json whenever the tag is ahead of
-          # package.json, leaving the tree dirty so the following
-          # `npm version patch` aborts with "Git working directory not clean".
-          NEXT="$(node -e 'const [a,b,c]=process.argv[1].split(".").map(Number); console.log(`${a}.${b}.${c+1}`)' "$BASE")"
+          # Semantic version from the commits since the last release tag (Conventional
+          # Commits, see scripts/next-version.mjs and docs/releasing.md):
+          #   BREAKING CHANGE / "type!:" -> major (X.0.0), "feat:" -> minor (0.X.0),
+          #   anything else (fix, chore, docs, ci, ...) -> patch (0.0.X).
+          # Computed up front and applied in ONE `npm version` call. A separate
+          # `npm version "$BASE" --no-git-tag-version` rewrites package.json/
+          # package-lock.json whenever the tag is ahead of package.json, leaving the
+          # tree dirty so the following `npm version` aborts with "Git working
+          # directory not clean".
+          RANGE="HEAD"
+          if [ -n "${LATEST_TAG}" ] && git rev-parse -q --verify "refs/tags/v${LATEST_TAG}" >/dev/null; then
+            RANGE="v${LATEST_TAG}..HEAD"
+          fi
+          NEXT="$(git log -z --no-merges --format=%B "$RANGE" | node scripts/next-version.mjs "$BASE")"
           # Release override (workflow_dispatch input `version`, e.g. 1.1.0): used
-          # as-is instead of the patch bump, so a minor/major release is not turned
-          # into 1.1.1 by the automatic bump. Read from env, never interpolated.
+          # as-is instead of the computed bump (for example to force a version). Read from env, never interpolated.
           if [ -n "${INPUT_VERSION}" ]; then
             if ! printf '%s' "$INPUT_VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
               echo "::error::version input '$INPUT_VERSION' is not X.Y.Z"; exit 1

package/CHANGELOG.md

@@ -6,6 +6,13 @@ 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
+
+- **DLP module (`src/dlp/`, flag `LOCAL_AGENT_DLP_MODE=off|warn|enforce`, default `off`).**
+  Masks secrets and PII in content leaving the agent. First wired point: the
+  `message` of incidents forwarded by the adapter forwarder. See `docs/dlp.md`.
+  With the flag off, output is unchanged.
+
 ### Changed defaults
 
 - **Signed commands: `enforce` by default.** `LOCAL_AGENT_SIGNATURE_MODE`

package/docs/dlp.md

@@ -0,0 +1,78 @@
+# DLP: masking secrets and PII before content leaves the agent (T4-09)
+
+Status: module + first integration point. Flag `LOCAL_AGENT_DLP_MODE`, default **off**.
+
+## Flags
+
+| Variable | Values | Default | Effect |
+|---|---|---|---|
+| `LOCAL_AGENT_DLP_MODE` | `off`, `warn`, `enforce` | `off` | `off`: nothing scanned, output identical to before. `warn`: output unchanged, counters and local log report what enforce would redact. `enforce`: hits replaced by `[REDACTED:<rule_id>]`. Any other value means `off`. |
+| `LOCAL_AGENT_DLP_BLOCK_CLASSES` | comma list of classes | empty | Enforce only. If a hit belongs to a listed class the whole text is replaced by `[BLOCKED:<class>]`. |
+| `LOCAL_AGENT_DLP_MAX_BYTES` | integer | `2000000` | Larger inputs are not scanned; enforce fails closed (`[REDACTED:dlp_oversize]`). |
+
+Classes: `private-key`, `cloud-credential`, `vcs-token`, `payment-key`, `saas-token`, `token`,
+`credential`, `connection-string`, `url-credential`, `pii-email`, `pii-phone`, `pii-id`,
+`pii-financial`, `high-entropy`.
+
+## API (reusable by the WebSocket work, task M)
+
+```js
+import { maskSensitive, maskDeep, protectEgress, protectEgressAsync, protectDeep,
+         getDlpStats, rulesetHash, RULESET_VERSION } from './src/dlp/index.js';
+```
+
+- `maskSensitive(text, { mode, blockClasses, maxBytes })`: **pure** function (no env, no state).
+  Returns `{ text, redactions: {rule_id: n}, total, blocked, blockedClasses, oversize, rulesetVersion }`.
+- `maskDeep(value, opts)`: same over every string of a JSON-like value (keys untouched, input not mutated).
+- `protectEgress(text, { source, log, env })`: reads the flag from the environment, updates counters,
+  writes a local record with counts per rule (never the value). Returns `{ text, ... }`.
+- `protectEgressAsync(text, { policyDecision, timeoutMs, ... })`: as above, plus a per-action
+  PolicyGate decision (D19). In `enforce`, anything other than an explicit `'ALLOW'` (DENY, unknown
+  answer, throw, timeout, PolicyGate offline) returns `[DLP_DENIED]`.
+- `protectDeep(value, opts)`: env-driven `maskDeep`.
+- `getDlpStats()`: `{ mode, ruleset_version, ruleset_hash, scanned, blocked, denied, dlp_redactions_total: {rule_id: n} }`.
+  Counts only; intended for the heartbeat (`dlp_redactions_total` by rule). `rulesetHash()` is what
+  `config.update` can carry to prove which ruleset is active.
+
+Fail-closed rules in `enforce`: internal error, oversize input, policy not ALLOW = content withheld.
+In `warn`/`off` the original text is always returned.
+
+## Where it is applied today
+
+- `src/siblings/incident-forwarder.js`: `message` of the incident POSTed to the gateway (log excerpt).
+
+Not applied yet (follow-ups, outside this PR's boundary): `content.request` responses and `job.event`
+(WebSocket channel, task M), prompts of the loop, error messages returned by routes. They can call
+`protectEgress`/`protectDeep`/`maskSensitive` directly.
+
+## Ruleset (version `2026.10.28-1`, 40 rules)
+
+Order matters (specific before generic). Highlights: PEM/OpenSSH/PGP private keys; AWS key id and secret;
+GCP API key, OAuth token and client secret; Azure storage key; DigitalOcean; GitHub (classic, fine-grained);
+GitLab; npm; PyPI; Stripe (keys, webhook secret); Shopify; Slack (token, webhook); Discord webhook;
+SendGrid; Twilio; Mailgun; Hugging Face; Telegram; Anthropic; OpenAI; JWT; Bearer and Basic headers;
+DB connection strings (postgres, mysql, mongodb, redis, amqp, mssql, cockroach); JDBC and ADO passwords;
+credentials in URLs; generic `name = literal` assignments (with a validator that ignores identifiers,
+calls, templates and placeholders); e-mail (ignores asset names and documentation domains);
+IBAN (mod-97); card numbers (Luhn); PT NIF (checksum and keyword context); international phone
+(leading `+`/`00`, 9 to 15 digits); opaque high-entropy blobs (40+ chars, ignores hex digests, UUIDs,
+SRI hashes and paths). Patterns are reimplemented from public token formats; no third-party rule
+files were copied. The PiiEgressMasker of the agents repo was used as a behavioural reference only.
+
+Bump `RULESET_VERSION` in `src/dlp/rules.js` on any change.
+
+## Tests
+
+`test/dlp/`: every rule has at least one synthetic positive (fixtures are built at runtime from split
+prefixes and a deterministic hash stream, no real secrets); 40 negative lines (code, hashes, UUIDs,
+SSH remotes, templates) must be unchanged; mode, block, oversize, idempotence, performance on
+pathological 1 MB inputs, policy fail-closed and the forwarder integration (flag off = byte-identical).
+
+Indicative false-positive check (not a measured product metric): running `enforce` over this repo
+(182 text files, ~41k lines) altered about 40 lines, almost all true positives (e-mail addresses in
+docs and test fixtures, literal tokens in tests). The plan's target (<= 2 % FP on a real code
+corpus) still needs to be measured on a customer-like corpus during the pilot.
+
+## Rollback
+
+Unset `LOCAL_AGENT_DLP_MODE` (or set `off`) and restart the agent. No data, schema or protocol changes.

package/docs/releasing.md

@@ -1,43 +1,37 @@
-# Releasing the local agent
-
-Two artefacts are released: the npm package `deepdebug-local-agent` and the
-public BYOC image `local-agent-full`. Nothing here runs on a normal push.
-
-## npm package
-
-`.github/workflows/npm-publish.yml` runs on every push to `main` that touches
-`src/**`, `package.json` or `bin/**`, and bumps the **patch** version
-automatically (from the highest of the latest `v*` tag and `package.json`).
-That is right for routine fixes and wrong for a minor release: with
-`package.json` at `1.1.0` the automatic bump would publish `1.1.1`.
-
-To publish an exact version (for example `1.1.0`):
-
-1. Leave `package.json` as it is. Do **not** bump it in a PR (a push to `main`
-   would trigger the automatic patch bump).
-2. Actions → **Publish NPM Package** → *Run workflow* on `main`, input
-   `version` = `1.1.0`. The workflow validates `X.Y.Z`, requires it to be
-   greater than the highest existing tag and `package.json`, runs
-   `npm version 1.1.0`, publishes with provenance, then pushes the bump commit
-   and the `v1.1.0` tag.
-3. Left empty, the input keeps the old behaviour (automatic patch bump).
-
-Prerequisite (owner of the npm package): Trusted Publisher configured for
-`VISIONHAMMER/deepdebug-local-agent`, workflow `npm-publish.yml` (see the
-header of the workflow). Without it the publish step fails and no version is
-burned.
-
-Heads-up: merging any PR that changes `src/**` to `main` starts an automatic
-patch publish (for example `1.0.39`) once the Trusted Publisher exists. To
-release `1.1.0` as the next version, dispatch it before merging further
-`src/**` changes, or merge with `[skip ci]` in the commit message.
-
-## BYOC image (`local-agent-full`)
-
-Tags pushed by `npm-publish.yml` use `GITHUB_TOKEN` and do not trigger other
-workflows, so after the npm release run Actions → **Build BYOC Agent Image**
-on `main` with `version` = `1.1.0`
-(see `docs/byoc-agent-image.md`). Tick `supply_chain` to also sign the image
-(cosign keyless), attach the SBOM and the provenance, and verify them.
-For `v*` tag and release runs the same job runs when the repository variable
-`BYOC_SUPPLY_CHAIN` is `true`. Default: off.
+# Releasing (npm)
+
+Every push to `main` publishes `deepdebug-local-agent` to npm through
+`.github/workflows/npm-publish.yml` (Trusted Publishing, OIDC; no token). The version
+is chosen automatically from the commit messages since the last release tag, following
+[Semantic Versioning](https://semver.org) and [Conventional Commits](https://www.conventionalcommits.org):
+
+| Level | Version step | Commit that triggers it |
+|---|---|---|
+| Patch | `0.0.X` bug fix | `fix:`, and any other type (`perf:`, `refactor:`, `docs:`, `chore:`, `ci:`, ...) or a message without a type |
+| Minor | `0.X.0` new functionality | `feat:` or `feat(scope):` |
+| Major | `X.0.0` big, breaking change | `type!:` (for example `feat!:`) or a `BREAKING CHANGE:` footer |
+
+The highest level among the commits since the last `vX.Y.Z` tag wins. Merge commits and the
+CI bump commits (`[skip ci]`) are ignored. The rules live in `scripts/next-version.mjs` and are
+unit tested in `test/next-version.test.js`.
+
+Examples:
+
+```
+fix: reject unsigned requests on /workspace/exec          -> 1.1.0 becomes 1.1.1
+feat(ws): metadata-only channel                           -> 1.1.1 becomes 1.2.0
+feat!: require node 22                                    -> 1.2.0 becomes 2.0.0
+```
+
+Tips
+
+- Write the PR title as a Conventional Commit and use "Squash and merge", so the version
+  follows the title. With a normal merge, the commits inside the PR decide.
+- To skip a release (for example a docs-only change), put `[skip ci]` in the merge commit
+  subject.
+- To force a version, run the workflow by hand with the `version` input:
+  `gh workflow run npm-publish.yml -f version=X.Y.Z` (must be greater than the highest tag).
+- The workflow tags and commits the bump only after a successful publish, so a failed
+  publish does not burn a version. npm reviews each new version automatically: it can stay
+  in "Validating" for a few minutes before it becomes installable.
+- Provenance is not published (`--provenance` is rejected by npm for private repositories).

package/env.example

@@ -69,3 +69,7 @@ LOG_LEVEL=info
 # LOCAL_AGENT_TENANT_ID=
 # LOCAL_AGENT_WORKSPACE_ID=
 # LOCAL_AGENT_REQUIRE_WORKSPACE=false
+
+# 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.1.0",
+  "version": "1.2.0",
   "description": "DeepDebug Local Agent - AI-powered code debugging assistant",
   "private": false,
   "type": "module",

package/scripts/next-version.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * next-version.mjs: semantic version for the automatic npm release.
+ *
+ *   major (X.0.0)  a breaking change: "type!:" subject or a "BREAKING CHANGE:" footer
+ *   minor (0.X.0)  new functionality: a "feat:" commit
+ *   patch (0.0.X)  everything else (fix, perf, refactor, docs, chore, ci, ...)
+ *
+ * Conventional Commits. The highest level among the commits since the last release
+ * tag wins. Merge commits and the CI auto-bump commits ("[skip ci]") are ignored.
+ *
+ * CLI: git log -z --no-merges --format=%B <range> | node scripts/next-version.mjs <base-version>
+ * prints the next version; stderr says which commit decided the bump.
+ */
+import { fileURLToPath } from 'node:url'
+
+const SUBJECT_TYPE = /^([a-z]+)(\([^)]*\))?(!)?:\s/i
+const BREAKING_FOOTER = /^BREAKING[ -]CHANGE:\s/m
+
+/** @param {string} message full commit message (subject + body) */
+export function classify(message) {
+  const text = String(message || '').trim()
+  if (!text) return null
+  const subject = text.split('\n', 1)[0]
+  if (/\[skip ci\]/i.test(subject) || /^Merge /.test(subject)) return null
+  const m = SUBJECT_TYPE.exec(subject)
+  if (BREAKING_FOOTER.test(text) || (m && m[3])) return 'major'
+  if (m && m[1].toLowerCase() === 'feat') return 'minor'
+  return 'patch'
+}
+
+const RANK = { patch: 0, minor: 1, major: 2 }
+
+/** @param {string[]} messages commit messages since the last release */
+export function bumpFor(messages) {
+  let level = 'patch'
+  for (const msg of messages) {
+    const c = classify(msg)
+    if (c && RANK[c] > RANK[level]) level = c
+  }
+  return level
+}
+
+/** @param {string} base X.Y.Z  @param {'major'|'minor'|'patch'} bump */
+export function nextVersion(base, bump) {
+  const parts = String(base).split('.').map(Number)
+  if (parts.length !== 3 || parts.some((n) => !Number.isInteger(n) || n < 0)) {
+    throw new Error(`base version '${base}' is not X.Y.Z`)
+  }
+  const [a, b, c] = parts
+  if (bump === 'major') return `${a + 1}.0.0`
+  if (bump === 'minor') return `${a}.${b + 1}.0`
+  return `${a}.${b}.${c + 1}`
+}
+
+async function main() {
+  const base = process.argv[2]
+  if (!base) {
+    console.error('usage: next-version.mjs <base-version> < commit messages separated by NUL')
+    process.exit(2)
+  }
+  const chunks = []
+  for await (const chunk of process.stdin) chunks.push(chunk)
+  const messages = Buffer.concat(chunks).toString('utf8').split('\0')
+  const bump = bumpFor(messages)
+  console.error(`[next-version] ${messages.filter((m) => classify(m)).length} releasable commit(s) since the last release, bump=${bump}`)
+  console.log(nextVersion(base, bump))
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((e) => {
+    console.error(e.message)
+    process.exit(1)
+  })
+}

package/src/dlp/engine.js

@@ -0,0 +1,111 @@
+/**
+ * DLP engine: pure functions, no env, no I/O, no module state.
+ *
+ * maskSensitive(text, opts) -> { text, redactions, total, blocked, blockedClasses, ... }
+ *   mode 'off'     text returned untouched, nothing scanned.
+ *   mode 'warn'    text returned untouched; redactions/blocked report what enforce WOULD do.
+ *   mode 'enforce' text returned with every hit replaced by [REDACTED:<rule_id>];
+ *                  when a hit belongs to a class in blockClasses the whole text is
+ *                  replaced by [BLOCKED:<class>] and `blocked` is true.
+ * The matched value is never returned, logged or counted: only rule ids and counts.
+ */
+import { RULES, RULESET_VERSION } from './rules.js';
+import { createHash } from 'node:crypto';
+
+export const MODES = Object.freeze(['off', 'warn', 'enforce']);
+export const DEFAULT_MAX_BYTES = 2_000_000;
+
+/** @param {unknown} v @returns {'off'|'warn'|'enforce'} unknown values fall back to 'off'. */
+export function normalizeMode(v) {
+    const m = typeof v === 'string' ? v.trim().toLowerCase() : '';
+    return MODES.includes(m) ? m : 'off';
+}
+
+/** Stable hash of the active ruleset (sent with config.update / heartbeat). */
+export function rulesetHash(rules = RULES) {
+    const h = createHash('sha256');
+    h.update(RULESET_VERSION);
+    for (const rule of rules) h.update(`\n${rule.id}|${rule.class}|${rule.re.source}|${rule.re.flags}|${rule.group ?? 0}`);
+    return h.digest('hex');
+}
+
+export const REDACTED = (id) => `[REDACTED:${id}]`;
+export const BLOCKED = (cls) => `[BLOCKED:${cls}]`;
+export const OVERSIZE = '[REDACTED:dlp_oversize]';
+
+/**
+ * @param {string} text
+ * @param {{mode?: string, rules?: ReadonlyArray<object>, blockClasses?: Iterable<string>, maxBytes?: number}} [opts]
+ */
+export function maskSensitive(text, opts = {}) {
+    const mode = normalizeMode(opts.mode);
+    const empty = { text, mode, redactions: {}, total: 0, blocked: false, blockedClasses: [], oversize: false, rulesetVersion: RULESET_VERSION };
+    if (mode === 'off' || typeof text !== 'string' || text.length === 0) return empty;
+
+    const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+    if (text.length > maxBytes) {
+        // Cannot scan safely in bounded time: enforce fails closed, warn only reports.
+        return { ...empty, text: mode === 'enforce' ? OVERSIZE : text, oversize: true };
+    }
+
+    const rules = opts.rules ?? RULES;
+    const blockSet = new Set(opts.blockClasses ?? []);
+    const redactions = {};
+    const hitClasses = new Set();
+    let out = text;
+    let total = 0;
+
+    for (const rule of rules) {
+        const re = new RegExp(rule.re.source, rule.re.flags.includes('g') ? rule.re.flags : rule.re.flags + 'g');
+        out = out.replace(re, (...args) => {
+            const match = args[0];
+            const groupIdx = rule.group ?? 0;
+            const target = groupIdx === 0 ? match : args[groupIdx];
+            if (typeof target !== 'string' || target.length === 0) return match;
+            if (target.includes('[REDACTED:')) return match; // never re-mask a placeholder (idempotence)
+            if (rule.validate && !rule.validate(target)) return match;
+            redactions[rule.id] = (redactions[rule.id] || 0) + 1;
+            hitClasses.add(rule.class);
+            total++;
+            if (groupIdx === 0) return REDACTED(rule.id);
+            const at = match.lastIndexOf(target);
+            return match.slice(0, at) + REDACTED(rule.id) + match.slice(at + target.length);
+        });
+    }
+
+    const blockedClasses = [...hitClasses].filter((c) => blockSet.has(c));
+    const blocked = blockedClasses.length > 0;
+    if (mode === 'warn') return { ...empty, redactions, total, blocked, blockedClasses };
+    return { ...empty, text: blocked ? BLOCKED(blockedClasses[0]) : out, redactions, total, blocked, blockedClasses };
+}
+
+/**
+ * Apply maskSensitive to every string in a JSON-like value (objects, arrays).
+ * Keys are not touched. Returns a new value plus the merged report.
+ */
+export function maskDeep(value, opts = {}) {
+    const report = { redactions: {}, total: 0, blocked: false, blockedClasses: [], oversize: false };
+    const seen = new WeakSet();
+    const walk = (v) => {
+        if (typeof v === 'string') {
+            const res = maskSensitive(v, opts);
+            for (const [k, n] of Object.entries(res.redactions)) report.redactions[k] = (report.redactions[k] || 0) + n;
+            report.total += res.total;
+            report.blocked ||= res.blocked;
+            report.oversize ||= res.oversize;
+            for (const c of res.blockedClasses) if (!report.blockedClasses.includes(c)) report.blockedClasses.push(c);
+            return res.text;
+        }
+        if (v === null || typeof v !== 'object') return v;
+        if (seen.has(v)) return '[circular]';
+        seen.add(v);
+        if (Array.isArray(v)) return v.map(walk);
+        const o = {};
+        for (const [k, x] of Object.entries(v)) o[k] = walk(x);
+        return o;
+    };
+    const mode = normalizeMode(opts.mode);
+    if (mode === 'off') return { value, mode, ...report };
+    const masked = walk(value);
+    return { value: mode === 'warn' ? value : masked, mode, ...report };
+}

package/src/dlp/index.js

@@ -0,0 +1,137 @@
+/**
+ * DLP for the Local Agent (T4-09): public API.
+ *
+ * Pure, reusable core (no env, no state):  maskSensitive, maskDeep  (engine.js)
+ * Configured wrappers (env + counters):     protectEgress, protectEgressAsync, protectDeep
+ *
+ * Flag: LOCAL_AGENT_DLP_MODE=off|warn|enforce   (default off: output byte-identical to before)
+ *       LOCAL_AGENT_DLP_BLOCK_CLASSES=private-key,cloud-credential   (default none; enforce only)
+ *       LOCAL_AGENT_DLP_MAX_BYTES=2000000                            (enforce fails closed above it)
+ *
+ * Fail-closed (D19): in enforce, an internal DLP error, an oversize input or a
+ * PolicyGate decision that is not an explicit ALLOW (including offline/timeout)
+ * withholds the content ([DLP_DENIED]) instead of letting it out.
+ *
+ * Reports carry rule ids and counts only; never the matched value.
+ */
+import { maskSensitive, maskDeep, normalizeMode, rulesetHash, DEFAULT_MAX_BYTES } from './engine.js';
+import { RULES, RULESET_VERSION, RULE_CLASSES } from './rules.js';
+
+export { maskSensitive, maskDeep, normalizeMode, rulesetHash, RULES, RULESET_VERSION, RULE_CLASSES };
+
+export const DENIED = '[DLP_DENIED]';
+const NOOP = () => {};
+
+/** Read the DLP configuration from an env-like object. */
+export function dlpConfigFromEnv(env = process.env) {
+    const maxRaw = Number.parseInt(env.LOCAL_AGENT_DLP_MAX_BYTES ?? '', 10);
+    const blockClasses = String(env.LOCAL_AGENT_DLP_BLOCK_CLASSES ?? '')
+        .split(',').map((s) => s.trim()).filter((c) => RULE_CLASSES.includes(c));
+    return {
+        mode: normalizeMode(env.LOCAL_AGENT_DLP_MODE),
+        blockClasses,
+        maxBytes: Number.isFinite(maxRaw) && maxRaw > 0 ? maxRaw : DEFAULT_MAX_BYTES,
+    };
+}
+
+// ---- counters (for heartbeat / dlp_redactions_total) -------------------------
+const counters = { scanned: 0, redactedTotal: 0, blocked: 0, denied: 0, byRule: new Map() };
+
+function record(res) {
+    counters.scanned++;
+    counters.redactedTotal += res.total;
+    if (res.blocked) counters.blocked++;
+    for (const [id, n] of Object.entries(res.redactions)) counters.byRule.set(id, (counters.byRule.get(id) || 0) + n);
+}
+
+/** Snapshot for the heartbeat: counts only. `dlp_redactions_total` is per rule id. */
+export function getDlpStats(env = process.env) {
+    const cfg = dlpConfigFromEnv(env);
+    return {
+        mode: cfg.mode,
+        ruleset_version: RULESET_VERSION,
+        ruleset_hash: rulesetHash(),
+        scanned: counters.scanned,
+        blocked: counters.blocked,
+        denied: counters.denied,
+        dlp_redactions_total: Object.fromEntries(counters.byRule),
+    };
+}
+
+export function resetDlpStats() {
+    counters.scanned = 0; counters.redactedTotal = 0; counters.blocked = 0; counters.denied = 0;
+    counters.byRule.clear();
+}
+
+function localLog(log, source, res) {
+    if (res.total === 0 && !res.oversize) return;
+    try {
+        // Counts per rule id only. The masked value is never part of the record.
+        log({ dlp: true, source: source || 'unknown', mode: res.mode, total: res.total, rules: res.redactions, blocked: res.blocked, oversize: res.oversize }, '[dlp] sensitive content detected');
+    } catch { /* logging must never break the data path */ }
+}
+
+/**
+ * Mask one string leaving the agent.
+ * @param {string} text
+ * @param {{env?: object, source?: string, log?: Function}} [opts]
+ * @returns {{text: string, mode: string, redactions: Record<string, number>, total: number, blocked: boolean, denied: boolean}}
+ */
+export function protectEgress(text, opts = {}) {
+    const cfg = dlpConfigFromEnv(opts.env ?? process.env);
+    if (cfg.mode === 'off') return { text, mode: 'off', redactions: {}, total: 0, blocked: false, denied: false };
+    try {
+        const res = maskSensitive(text, cfg);
+        record(res);
+        localLog(opts.log ?? NOOP, opts.source, res);
+        return { text: res.text, mode: cfg.mode, redactions: res.redactions, total: res.total, blocked: res.blocked, denied: false };
+    } catch {
+        if (cfg.mode !== 'enforce') return { text, mode: cfg.mode, redactions: {}, total: 0, blocked: false, denied: false };
+        counters.denied++;
+        return { text: DENIED, mode: cfg.mode, redactions: {}, total: 0, blocked: false, denied: true };
+    }
+}
+
+/**
+ * Same as protectEgress, plus a per-action PolicyGate decision (D19).
+ * `policyDecision` is optional; when given, enforce requires an explicit 'ALLOW'.
+ * Offline, throwing, timing out or answering anything else = DENY.
+ * @param {string} text
+ * @param {{policyDecision?: () => Promise<string>|string, timeoutMs?: number, env?: object, source?: string, log?: Function}} [opts]
+ */
+export async function protectEgressAsync(text, opts = {}) {
+    const cfg = dlpConfigFromEnv(opts.env ?? process.env);
+    if (cfg.mode === 'enforce' && typeof opts.policyDecision === 'function') {
+        let verdict;
+        let timer;
+        try {
+            const timeout = new Promise((_, rej) => { timer = setTimeout(() => rej(new Error('policy timeout')), opts.timeoutMs ?? 3000); });
+            verdict = await Promise.race([Promise.resolve().then(opts.policyDecision), timeout]);
+        } catch {
+            verdict = undefined;
+        } finally {
+            clearTimeout(timer);
+        }
+        if (verdict !== 'ALLOW') {
+            counters.denied++;
+            return { text: DENIED, mode: cfg.mode, redactions: {}, total: 0, blocked: false, denied: true };
+        }
+    }
+    return protectEgress(text, opts);
+}
+
+/** Mask every string in a JSON-like payload. Returns { value, ... } with the same report fields. */
+export function protectDeep(value, opts = {}) {
+    const cfg = dlpConfigFromEnv(opts.env ?? process.env);
+    if (cfg.mode === 'off') return { value, mode: 'off', redactions: {}, total: 0, blocked: false, denied: false };
+    try {
+        const res = maskDeep(value, cfg);
+        record(res);
+        localLog(opts.log ?? NOOP, opts.source, { ...res, mode: cfg.mode });
+        return { ...res, denied: false };
+    } catch {
+        if (cfg.mode !== 'enforce') return { value, mode: cfg.mode, redactions: {}, total: 0, blocked: false, denied: false };
+        counters.denied++;
+        return { value: DENIED, mode: cfg.mode, redactions: {}, total: 0, blocked: false, denied: true };
+    }
+}