deepdebug-local-agent 1.1.0 → 1.3.0

package/src/dlp/rules.js

@@ -0,0 +1,97 @@
+/**
+ * DLP ruleset (versioned). Each rule: { id, class, re, group?, validate? }.
+ *  - id:       stable identifier, used as the metric label and in the placeholder.
+ *  - class:    coarse family, used by LOCAL_AGENT_DLP_BLOCK_CLASSES.
+ *  - re:       global regex (the engine resets lastIndex; never share state).
+ *  - group:    capture group to redact; default is the whole match.
+ *  - validate: optional predicate on the redactable text; false = not a hit.
+ *
+ * Order matters: specific rules run before generic ones, so a Stripe key is
+ * reported as stripe_key and not as a generic secret assignment.
+ * Bump RULESET_VERSION on every change to the list or to a pattern.
+ *
+ * Reimplemented from public token formats; no third-party rule files copied.
+ */
+import {
+    looksLikeLiteralSecret, looksLikeOpaqueKey, realEmail, plausiblePhone,
+    plausibleCard, ibanValid, ptNifValid,
+} from './validators.js';
+
+export const RULESET_VERSION = '2026.10.28-1';
+
+export const RULE_CLASSES = Object.freeze([
+    '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',
+]);
+
+const r = (id, cls, re, extra = {}) => Object.freeze({ id, class: cls, re, ...extra });
+
+export const RULES = Object.freeze([
+    // Private keys first: they span lines and may contain other-looking text.
+    r('pem_private_key', 'private-key',
+        /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----[\s\S]*?(?:-----END (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----|$)/g),
+
+    // Cloud
+    r('aws_access_key_id', 'cloud-credential', /\b(?:AKIA|ASIA|AGPA|AIDA|AROA|ANPA|ANVA|AIPA)[A-Z0-9]{16}\b/g),
+    r('aws_secret_access_key', 'cloud-credential',
+        /\baws[_-]?secret[_-]?(?:access[_-]?)?key["']?\s*[:=]\s*["']?([A-Za-z0-9/+=]{40})\b/gi, { group: 1 }),
+    r('gcp_api_key', 'cloud-credential', /\bAIza[0-9A-Za-z_-]{35}\b/g),
+    r('gcp_oauth_token', 'cloud-credential', /\bya29\.[0-9A-Za-z_-]{20,}/g),
+    r('gcp_oauth_client_secret', 'cloud-credential', /\bGOCSPX-[A-Za-z0-9_-]{20,}/g),
+    r('azure_storage_account_key', 'cloud-credential', /\bAccountKey=([A-Za-z0-9+/]{40,}={0,2})/g, { group: 1 }),
+    r('digitalocean_token', 'cloud-credential', /\bdo[opr]_v1_[a-f0-9]{64}\b/g),
+
+    // VCS / package registries
+    r('github_token', 'vcs-token', /\bgh[pousr]_[A-Za-z0-9]{36,}\b/g),
+    r('github_fine_grained_pat', 'vcs-token', /\bgithub_pat_[A-Za-z0-9_]{22,}\b/g),
+    r('gitlab_pat', 'vcs-token', /\bglpat-[A-Za-z0-9_-]{20,}/g),
+    r('npm_token', 'vcs-token', /\bnpm_[A-Za-z0-9]{36}\b/g),
+    r('pypi_token', 'vcs-token', /\bpypi-AgEIcHlwaS5vcmc[A-Za-z0-9_-]{50,}/g),
+
+    // Payments / SaaS
+    r('stripe_key', 'payment-key', /\b[sr]k_(?:live|test)_[0-9A-Za-z]{16,}\b/g),
+    r('stripe_webhook_secret', 'payment-key', /\bwhsec_[A-Za-z0-9]{16,}\b/g),
+    r('shopify_token', 'saas-token', /\bshp(?:at|ca|pa|ss)_[a-f0-9]{32}\b/g),
+    r('slack_token', 'saas-token', /\bxox[abprs]-[A-Za-z0-9-]{10,}/g),
+    r('slack_webhook', 'saas-token', /https:\/\/hooks\.slack\.com\/services\/T[A-Z0-9]+\/B[A-Z0-9]+\/[A-Za-z0-9]+/g),
+    r('discord_webhook', 'saas-token', /https:\/\/(?:discord|discordapp)\.com\/api\/webhooks\/\d+\/[\w-]+/g),
+    r('sendgrid_key', 'saas-token', /\bSG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}/g),
+    r('twilio_api_key', 'saas-token', /\bSK[0-9a-f]{32}\b/g),
+    r('mailgun_key', 'saas-token', /\bkey-[0-9a-f]{32}\b/g),
+    r('huggingface_token', 'saas-token', /\bhf_[A-Za-z0-9]{34,}\b/g),
+    r('telegram_bot_token', 'saas-token', /\b\d{8,10}:AA[A-Za-z0-9_-]{33}\b/g),
+    r('anthropic_key', 'saas-token', /\bsk-ant-[A-Za-z0-9_-]{20,}/g),
+    r('openai_key', 'saas-token', /\bsk-(?:proj-)?[A-Za-z0-9_-]{32,}/g, { validate: (v) => /\d/.test(v) }),
+
+    // Generic tokens
+    r('jwt', 'token', /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g),
+    r('bearer_token', 'token', /\bBearer\s+([A-Za-z0-9._~+/-]{20,}=*)/g, { group: 1 }),
+    r('basic_auth_header', 'token', /\bAuthorization:\s*Basic\s+([A-Za-z0-9+/]{12,}={0,2})/gi, { group: 1 }),
+
+    // Connection strings and URL credentials (before the generic assignment rule)
+    r('db_connection_string', 'connection-string',
+        /\b(?:postgres(?:ql)?|mysql|mariadb|mongodb(?:\+srv)?|redis|rediss|amqps?|mssql|sqlserver|cockroachdb):\/\/[^\s"'`<>]+/gi,
+        { validate: (v) => /:\/\/[^/\s]*@/.test(v) }),
+    r('jdbc_password', 'connection-string', /\bjdbc:[a-z0-9]+:[^\s"'`]*?[?&;](?:password|pwd)=([^\s&;"'`]+)/gi, { group: 1 }),
+    r('ado_connection_password', 'connection-string', /(?:^|;)\s*(?:Password|Pwd)\s*=\s*([^;\r\n"']{3,})/gim, { group: 1 }),
+    r('url_credentials', 'url-credential', /\b[a-z][a-z0-9+.-]{0,20}:\/\/([^\s:@/"'`<>]+:[^\s@/"'`<>]+)@/gi, { group: 1, validate: (v) => !/[${}<>]/.test(v) }),
+
+    // Generic "name = literal" assignments
+    r('generic_secret_assignment', 'credential',
+        /\b(?:[A-Za-z0-9_-]{0,40}?(?:password|passwd|pwd|secret|api[_-]?key|apikey|access[_-]?token|auth[_-]?token|client[_-]?secret|private[_-]?key|token))["']?\s*(?::|=|=>)\s*["']?([^\s"'`,;]{8,})/gi,
+        { group: 1, validate: looksLikeLiteralSecret }),
+
+    // PII
+    r('email', 'pii-email', /[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9-]{1,63}(?:\.[A-Za-z0-9-]{1,63}){0,6}\.[A-Za-z]{2,24}(?![A-Za-z0-9_~./-]|:[A-Za-z0-9_~./-])/g, { validate: realEmail }),
+    r('iban', 'pii-financial', /\b[A-Z]{2}\d{2}(?: ?[A-Z0-9]{4}){2,7}(?: ?[A-Z0-9]{1,3})?\b/g, { validate: ibanValid }),
+    r('credit_card', 'pii-financial', /(?<![\d.-])\d{4}(?:[ -]?\d{4}){2}[ -]?\d{1,7}(?![\d-])/g, { validate: plausibleCard }),
+    r('pt_nif', 'pii-id',
+        /\b(?:NIF|NIPC|contribuinte|VAT)\b\s*(?:n[.ºo°]*\s*)?[:=#-]?\s*(?:PT)?(\d{9})\b/gi, { group: 1, validate: ptNifValid }),
+    r('phone_international', 'pii-phone', /(?<![\w.+])(?:\+|00)\d{1,3}(?:[ .-]?\(?\d{1,4}\)?){2,5}(?![\w])/g,
+        { validate: plausiblePhone }),
+
+    // Last: opaque high-entropy blobs
+    r('high_entropy_blob', 'high-entropy', /(?<![A-Za-z0-9+/_=-])[A-Za-z0-9+/_=-]{40,}(?![A-Za-z0-9+/_=-])/g,
+        { validate: looksLikeOpaqueKey }),
+]);

package/src/dlp/validators.js

@@ -0,0 +1,123 @@
+/**
+ * DLP validators: pure helpers that cut false positives after a regex matched.
+ * No I/O, no state.
+ */
+
+/** Shannon entropy in bits per character. */
+export function shannonEntropy(s) {
+    if (!s) return 0;
+    const freq = new Map();
+    for (const ch of s) freq.set(ch, (freq.get(ch) || 0) + 1);
+    let h = 0;
+    for (const n of freq.values()) {
+        const p = n / s.length;
+        h -= p * Math.log2(p);
+    }
+    return h;
+}
+
+/** Luhn checksum over a digit string. */
+export function luhnValid(digits) {
+    if (!/^\d{13,19}$/.test(digits)) return false;
+    let sum = 0;
+    let alt = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let d = digits.charCodeAt(i) - 48;
+        if (alt) {
+            d *= 2;
+            if (d > 9) d -= 9;
+        }
+        sum += d;
+        alt = !alt;
+    }
+    return sum % 10 === 0;
+}
+
+/** ISO 13616 mod-97 check for an IBAN (spaces allowed). */
+export function ibanValid(raw) {
+    const s = raw.replace(/\s+/g, '').toUpperCase();
+    if (!/^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/.test(s)) return false;
+    const rearranged = s.slice(4) + s.slice(0, 4);
+    let rem = 0;
+    for (const ch of rearranged) {
+        const v = ch >= 'A' && ch <= 'Z' ? String(ch.charCodeAt(0) - 55) : ch;
+        for (const c of v) rem = (rem * 10 + (c.charCodeAt(0) - 48)) % 97;
+    }
+    return rem === 1;
+}
+
+/** Portuguese NIF/NIPC checksum (9 digits, mod 11). */
+export function ptNifValid(digits) {
+    if (!/^\d{9}$/.test(digits)) return false;
+    const okPrefix = '1235689'.includes(digits[0]) || /^(?:45|70|71|72|74|75|77|79)/.test(digits);
+    if (!okPrefix) return false;
+    let sum = 0;
+    for (let i = 0; i < 8; i++) sum += (digits.charCodeAt(i) - 48) * (9 - i);
+    const check = 11 - (sum % 11);
+    const expected = check >= 10 ? 0 : check;
+    return expected === digits.charCodeAt(8) - 48;
+}
+
+const PLACEHOLDER_PREFIX = /^(?:\$|\{|<|%|\[|\(|process\.env|os\.getenv|env\[|getenv|config\.|settings\.|this\.|self\.|args\.|params\.|req\.|request\.|\.\.\.)/i;
+const PLACEHOLDER_WORDS = /^(?:\*+|x{3,}|null|undefined|none|true|false|string|required|optional|redacted|changeme|change_me|your[-_ ].*|example.*|placeholder.*|dummy.*|secret|password|token|apikey|api_key)$/i;
+
+/**
+ * Decide whether the value assigned to a secret-looking name is a literal
+ * credential or just code (identifier, call, template, placeholder).
+ */
+export function looksLikeLiteralSecret(value) {
+    const v = value.replace(/^["'`]+|["'`]+$/g, '');
+    if (v.length < 8) return false;
+    if (PLACEHOLDER_PREFIX.test(v) || PLACEHOLDER_WORDS.test(v)) return false;
+    if (v.includes('REDACTED') || v.includes('***')) return false;
+    if (/[()]/.test(v)) return false;             // function call / expression
+    if (/^[A-Za-z_][A-Za-z0-9_.]*$/.test(v) && !/\d/.test(v)) {
+        // plain identifier or dotted path (getPassword, config.password): code, not a secret
+        return false;
+    }
+    if (/^[a-z]+(?:[-_][a-z]+)+$/.test(v)) return false; // kebab/snake names (secret ids, flags), not values
+    const hasDigit = /\d/.test(v);
+    const hasSymbol = /[!@#$%^&*+/=~\-]/.test(v);
+    if (hasDigit || hasSymbol) return true;
+    return v.length >= 16 && shannonEntropy(v) >= 3.5;
+}
+
+/** High-entropy blob heuristic (opaque keys); excludes hashes, UUIDs and paths. */
+export function looksLikeOpaqueKey(token) {
+    if (token.length < 40) return false;
+    if (/^sha\d+-/i.test(token)) return false;                 // npm/SRI integrity hashes
+    if (/^[0-9a-f]+$/i.test(token)) return false;              // hex digests / git SHAs
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(token)) return false; // UUID
+    if (token.startsWith('/') || token.includes('//')) return false; // path / URL remnants
+    // Standard base64 never has - or _, URL-safe never has /: a mix means a path or URL fragment.
+    if (token.includes('/') && /[-_]/.test(token)) return false;
+    if (!/[a-z]/.test(token) || !/[A-Z]/.test(token) || !/\d/.test(token)) return false;
+    return shannonEntropy(token) >= 4.5;
+}
+
+const NON_MAIL_TLDS = new Set(['png', 'jpg', 'jpeg', 'gif', 'svg', 'webp', 'ico', 'css', 'js', 'ts', 'json', 'map', 'woff', 'woff2', 'ttf', 'eot', 'html', 'md']);
+const DOC_DOMAINS = /(?:^|\.)(?:example\.(?:com|org|net)|test|invalid|localhost|local)$/i;
+
+/** E-mail: reject asset names (logo@2x.png) and reserved documentation domains. */
+export function realEmail(addr) {
+    const at = addr.lastIndexOf('@');
+    const domain = addr.slice(at + 1);
+    const tld = domain.slice(domain.lastIndexOf('.') + 1).toLowerCase();
+    if (NON_MAIL_TLDS.has(tld)) return false;
+    if (DOC_DOMAINS.test(domain)) return false;
+    return true;
+}
+
+/** International phone: leading +, 9 to 15 digits overall. */
+export function plausiblePhone(raw) {
+    const digits = raw.replace(/\D/g, '');
+    return digits.length >= 9 && digits.length <= 15;
+}
+
+/** Card number candidates: Luhn + plausible leading digit, separators ignored. */
+export function plausibleCard(raw) {
+    const digits = raw.replace(/[ -]/g, '');
+    if (!/^[2-6]/.test(digits)) return false;
+    if (/^(\d)\1+$/.test(digits)) return false;
+    return luhnValid(digits);
+}

package/src/mcp-http-server.js

@@ -23,7 +23,7 @@ import { applyUnifiedDiff } from "./patch.js";
 
 const IGNORE_DIRS = ["node_modules", ".git", "target", "build", "dist", ".idea", "__pycache__", "vendor", ".gradle"];
 
-export function startMCPHttpServer(workspaceManager, port = 5056) {
+export function startMCPHttpServer(workspaceManager, port = 5056, execPolicyOverride = null) {
     const app = express();
     // SECURITY: this bridge runs shell commands (/mcp/execute-command) and
     // writes files. Its only consumer is the in-process WS tunnel, so it binds
@@ -32,7 +32,9 @@ export function startMCPHttpServer(workspaceManager, port = 5056) {
     app.use(express.json({ limit: "50mb", verify: captureRawBody }));
     // Same signed-command verification as the main API (shared nonce cache).
     const signing = getSigningConfig();
-    const execPolicy = resolveExecPolicyConfig();
+    // D19: server.js shares its EXEC_POLICY (with the offlineGuard when WS metadata-only is on),
+    // so /mcp/execute-command denies PolicyGate-backed actions while the control plane is offline.
+    const execPolicy = execPolicyOverride || resolveExecPolicyConfig();
     app.use(createSignatureMiddleware(signing));
 
     // ========================================
@@ -258,7 +260,7 @@ export function startMCPHttpServer(workspaceManager, port = 5056) {
     // START SERVER
     // ========================================
     const host = process.env.MCP_BIND_HOST || "127.0.0.1";
-    app.listen(port, host, () => {
+    app.locals.server = app.listen(port, host, () => {
         console.log(`🔌 MCP HTTP Bridge listening on http://${host}:${port}`);
     });
 

package/src/server.js

@@ -17,6 +17,8 @@ import { compileAndTest, run } from "./exec-utils.js";
 import { confineToRoot, checkArgsWithinRoot, scanRawCommand, SandboxViolation } from "./utils/sandbox.js";
 import { getSigningConfig, createSignatureMiddleware, captureRawBody, describeSigningConfig, verifyWsEnvelope, internalSignatureHeaders } from "./utils/request-signing.js";
 import { decideExec, rejectionBody, resolveExecPolicyConfig } from "./utils/exec-policy.js";
+import { createHash as wsCreateHash } from "node:crypto";
+import { resolveWsMetadataConfig, createWsMetadataGuard, createConnectionState, createOfflinePolicyGuard } from "./ws-channel/index.js";
 import { resolveEffectiveHeaderRoot } from "./utils/root-recovery.js";
 import { classifyGrepFailure, partialSearchBody } from "./utils/search-outcome.js";
 import { classifyOpenDestination, extractOpenTenantId, isSafeToRemove } from "./utils/open-gate.js";
@@ -637,6 +639,22 @@ app.use(createSignatureMiddleware(SIGNING));
 (SIGNING.mode === "enforce" ? console.log : console.warn)(`[agent-sig] ${describeSigningConfig(SIGNING)}`);
 console.log(`[exec-policy] mode=${EXEC_POLICY.mode} (allowlist; LOCAL_AGENT_EXEC_POLICY_MODE=off|warn|enforce)`);
 
+// WS METADATA-ONLY (T4-10, D17/D19): LOCAL_AGENT_WS_METADATA_ONLY=off|enforce (default off).
+// enforce: the outbound WS channel carries only allowlisted metadata and PolicyGate-backed
+// actions are denied while the control plane is unreachable. off = nothing changes.
+const WS_METADATA = resolveWsMetadataConfig();
+const WS_CONNECTION = createConnectionState();
+if (WS_METADATA.mode === "enforce") {
+    EXEC_POLICY.offlineGuard = createOfflinePolicyGuard({
+        connection: WS_CONNECTION,
+        onDeny: ({ via }) => console.warn(`[ws-metadata] D19 DENY (${via}): control plane offline`),
+    });
+    console.log("[ws-metadata] mode=enforce (metadata-only WS channel; offline PolicyGate = DENY)");
+    if (process.env.DISABLE_WS_TUNNEL === "true") {
+        console.warn("[ws-metadata] WARNING: DISABLE_WS_TUNNEL=true with enforce - the agent is permanently offline and every PolicyGate-backed action (platform tools, human approval) will be denied");
+    }
+}
+
 //  DEFAULT WORKSPACE - Sets the default workspace
 // Can be overridden via an environment variable or POST /workspace/open
 const DEFAULT_WORKSPACE = process.env.WORKSPACE_ROOT
@@ -6953,6 +6971,12 @@ async function startWebSocketTunnel(port, gatewayUrl, authToken, tenantId) {
     let reconnectDelay = 2000;
     let isShuttingDown = false;
     let ws = null;
+    // null unless LOCAL_AGENT_WS_METADATA_ONLY=enforce; with it null every send below is the legacy frame.
+    const metaGuard = createWsMetadataGuard({ config: WS_METADATA });
+    const sendFrame = (legacyObj, guardedFrame) => {
+        const out = metaGuard ? guardedFrame : JSON.stringify(legacyObj);
+        if (out) ws.send(out);
+    };
 
     async function connect() {
         if (isShuttingDown) return;
@@ -6963,14 +6987,26 @@ async function startWebSocketTunnel(port, gatewayUrl, authToken, tenantId) {
             ws.on('open', () => {
                 console.log(`WebSocket tunnel connected to Gateway`);
                 reconnectDelay = 2000;
-                ws.send(JSON.stringify({ type: 'register', tenantId, port, workspacePath: WORKSPACE_ROOT || null }));
+                WS_CONNECTION.markOpen();
+                const legacyRegister = { type: 'register', tenantId, port, workspacePath: WORKSPACE_ROOT || null };
+                sendFrame(legacyRegister, metaGuard && metaGuard.frameMessage({
+                    type: 'register', tenantId, port: Number(port),
+                    ...(WORKSPACE_ROOT ? { workspaceHash: wsCreateHash("sha256").update(String(WORKSPACE_ROOT)).digest('hex') } : {}),
+                }));
                 const hb = setInterval(() => {
-                    if (ws.readyState === WebSocket.OPEN) ws.send('ping');
-                    else clearInterval(hb);
+                    if (ws.readyState === WebSocket.OPEN) {
+                        ws.send('ping');
+                        // Metadata-only: a protocol-level ping (auto-answered by any RFC 6455 server) proves
+                        // liveness for D19 even if the gateway never answers the text 'ping'.
+                        if (metaGuard) { try { ws.ping(); } catch { /* socket closing */ } }
+                    } else clearInterval(hb);
                 }, 30000);
             });
 
+            ws.on('pong', () => WS_CONNECTION.markSeen());
+
             ws.on('message', async (data) => {
+                WS_CONNECTION.markSeen();
                 const text = data.toString();
                 if (text === 'pong') return;
                 let request;
@@ -6982,16 +7018,23 @@ async function startWebSocketTunnel(port, gatewayUrl, authToken, tenantId) {
                 // with the signed paramsRaw, never the unsigned params copy.
                 const envelope = verifyWsEnvelope(request, SIGNING);
                 if (!envelope.ok) {
-                    ws.send(JSON.stringify({ requestId, command, ok: false, error: "invalid command signature", reason: envelope.reason }));
+                    sendFrame({ requestId, command, ok: false, error: "invalid command signature", reason: envelope.reason },
+                        metaGuard && metaGuard.frameError(requestId, command, 'invalid_signature'));
                     return;
                 }
+                if (metaGuard) {
+                    // Metadata-only: legacy content commands never run; the reply is a metadata-only error.
+                    const admit = metaGuard.admitCommand(requestId, command);
+                    if (!admit.ok) { if (admit.errorFrame) ws.send(admit.errorFrame); return; }
+                }
                 let result;
                 try { result = await handleWsCommand(command, envelope.params || {}, envelope); }
                 catch (err) { result = { error: err.message }; }
-                ws.send(JSON.stringify({ requestId, command, ...result }));
+                sendFrame({ requestId, command, ...result }, metaGuard && metaGuard.frameResponse(requestId, command, result));
             });
 
             ws.on('close', () => {
+                WS_CONNECTION.markClosed();
                 if (!isShuttingDown) {
                     console.log(`WS disconnected. Reconnecting in ${reconnectDelay/1000}s...`);
                     setTimeout(connect, reconnectDelay);
@@ -8151,7 +8194,7 @@ app.listen(PORT, BIND_HOST, async () => {
 
 // Start MCP HTTP Bridge em paralelo (port 5056)
 try {
-    startMCPHttpServer(wsManager, parseInt(MCP_PORT));
+    startMCPHttpServer(wsManager, parseInt(MCP_PORT), EXEC_POLICY);
 } catch (err) {
     console.warn(`MCP HTTP Server failed to start: ${err.message}`);
     console.warn(`(MCP features disabled, REST API continues normally)`);

package/src/siblings/incident-forwarder.js

@@ -25,6 +25,7 @@
  */
 import { logger as defaultLogger } from './logger.js';
 import { BurstSuppressor } from './burst-suppressor.js';
+import { protectEgress } from '../dlp/index.js';
 
 const SIX_KEYS = ['adapter', 'errorCode', 'file', 'message', 'source', 'timestamp'];
 
@@ -293,7 +294,8 @@ export class IncidentForwarder {
         return {
             tenantId: this.tenantId || undefined,
             service: evt.source,
-            message: evt.message,
+            // DLP (LOCAL_AGENT_DLP_MODE, default off = unchanged): log excerpts leave the customer network here.
+            message: protectEgress(evt.message, { source: 'incident-forwarder', log: (o, m) => this.logger.info(o, m) }).text,
             severity: 'error',
             environment: 'production',
             detectedBy: 'local-agent-adapter',

package/src/utils/exec-policy.js

@@ -907,7 +907,14 @@ export const execStats = { allowed: 0, platform: 0, approved: 0, warned: 0, reje
  * Decides one exec request. `command` (shell string) or `argv` (no shell).
  * Returns { allow: boolean, status?, reason?, via }.
  */
-export function decideExec({ command, argv, root, headers = {}, body = {}, vhSignature, signingCfg }, cfg = resolveExecPolicyConfig()) {
+export function decideExec(input, cfg = resolveExecPolicyConfig()) {
+    const decision = decideExecInner(input, cfg);
+    // D19 (LOCAL_AGENT_WS_METADATA_ONLY=enforce): PolicyGate-backed ALLOWs become DENY while the
+    // control plane is unreachable. `offlineGuard` is unset by default, so this is a no-op.
+    return typeof cfg.offlineGuard === "function" ? cfg.offlineGuard(decision) : decision;
+}
+
+function decideExecInner({ command, argv, root, headers = {}, body = {}, vhSignature, signingCfg }, cfg) {
     if (cfg.mode === "off") return { allow: true, via: "policy-off" };
     const verdict = argv
         ? (() => {

package/src/ws-channel/allowlist.js

@@ -0,0 +1,143 @@
+/**
+ * allowlist.js - the contract of what may leave the Local Agent on the WS
+ * channel in metadata-only mode (T4-10).
+ *
+ * Rules:
+ *  - closed world: a message type, a field or a value outside this file is rejected;
+ *  - there is NO free-text field: strings are ids, sha256 hashes or members of a
+ *    fixed enum, so code/diffs/logs/chat text cannot fit even by accident;
+ *  - flat messages only (no nested objects/arrays).
+ *
+ * Validation returns reason CODES and field NAMES only - never values - so a
+ * caller can log a rejection without leaking the content that triggered it.
+ */
+
+const ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+const HASH_RE = /^[a-f0-9]{64}$/;
+const VERSION_RE = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9.]{1,32})?$/;
+
+/** Commands the CP may still invoke in metadata-only mode (legacy content commands are vh-mode only). */
+export const METADATA_COMMANDS = Object.freeze(["health", "workspace.open"]);
+
+/** Machine-readable error classes that replace free-text error messages. */
+export const ERROR_CODES = Object.freeze([
+    "command_error", "blocked_metadata_only", "invalid_signature", "request_expired", "rate_limited", "unknown_request",
+]);
+
+const KINDS = {
+    id: (v) => typeof v === "string" && ID_RE.test(v),
+    hash: (v) => typeof v === "string" && HASH_RE.test(v),
+    version: (v) => typeof v === "string" && VERSION_RE.test(v),
+    int: (v) => Number.isSafeInteger(v) && v >= 0,
+    port: (v) => Number.isInteger(v) && v >= 1 && v <= 65535,
+    bool: (v) => typeof v === "boolean",
+};
+
+const enumOf = (...values) => ({ kind: "enum", values });
+const f = (kind, extra = {}) => ({ kind, ...extra });
+
+/** Outbound schemas, keyed by message type. `response` is the implicit type of a command reply. */
+export const OUTBOUND_SCHEMAS = Object.freeze({
+    register: {
+        type: f("const", { value: "register" }),
+        tenantId: f("id", { required: true }),
+        port: f("port", { required: true }),
+        workspaceHash: f("hash"),
+    },
+    hello: {
+        type: f("const", { value: "hello" }),
+        agentVersion: f("version", { required: true }),
+        protocol: f("int"),
+        signatureMode: enumOf("off", "warn", "enforce"),
+        metadataOnly: enumOf("off", "enforce"),
+    },
+    status: {
+        type: f("const", { value: "status" }),
+        state: enumOf("idle", "busy", "degraded"),
+        openWorkspaces: f("int"),
+        queueDepth: f("int"),
+        uptimeSeconds: f("int"),
+    },
+    cost: {
+        type: f("const", { value: "cost" }),
+        requestId: f("id", { required: true }),
+        model: f("id"),
+        tokensIn: f("int"),
+        tokensOut: f("int"),
+        costMicros: f("int"),
+    },
+    response: {
+        requestId: f("id", { required: true }),
+        command: f("id", { required: true }),
+        ok: f("bool"),
+        status: enumOf("ok"),
+        openWorkspaces: f("int"),
+        errorCode: enumOf(...ERROR_CODES),
+    },
+});
+
+/** Per-command result keys that are dropped (never sent) because they are paths/content; listed so the drop is explicit. */
+export const RESPONSE_STRIP = Object.freeze({
+    "health": Object.freeze(["workspace"]),
+    "workspace.open": Object.freeze(["root"]),
+});
+
+/** Free-text keys of a legacy result: replaced by an `errorCode`, value discarded. */
+export const FREE_TEXT_KEYS = Object.freeze(["error", "reason", "hint", "message", "detail"]);
+
+function checkField(spec, value) {
+    if (spec.kind === "const") return value === spec.value;
+    if (spec.kind === "enum") return typeof value === "string" && spec.values.includes(value);
+    const fn = KINDS[spec.kind];
+    return Boolean(fn) && fn(value);
+}
+
+/** The wire type a message will be validated as. */
+export function messageType(msg) {
+    if (msg && typeof msg === "object" && !Array.isArray(msg)) {
+        if (typeof msg.type === "string") return msg.type;
+        if ("requestId" in msg && "command" in msg) return "response";
+    }
+    return null;
+}
+
+/**
+ * @returns {{ok:true,type:string}|{ok:false,reason:string,type?:string,field?:string}}
+ *   reason: not-an-object | unknown-type | unknown-field | invalid-value | missing-field
+ */
+export function validateOutbound(msg) {
+    if (!msg || typeof msg !== "object" || Array.isArray(msg)) return { ok: false, reason: "not-an-object" };
+    const type = messageType(msg);
+    const schema = type && Object.prototype.hasOwnProperty.call(OUTBOUND_SCHEMAS, type) ? OUTBOUND_SCHEMAS[type] : null;
+    if (!schema) return { ok: false, reason: "unknown-type" };
+    for (const key of Object.keys(msg)) {
+        if (!Object.prototype.hasOwnProperty.call(schema, key)) return { ok: false, reason: "unknown-field", type, field: key };
+        if (!checkField(schema[key], msg[key])) return { ok: false, reason: "invalid-value", type, field: key };
+    }
+    for (const [key, spec] of Object.entries(schema)) {
+        if (spec.required && !(key in msg)) return { ok: false, reason: "missing-field", type, field: key };
+    }
+    return { ok: true, type };
+}
+
+/**
+ * Projects a legacy command result onto the response schema.
+ * Strip-listed keys are dropped; free-text keys become errorCode `command_error`;
+ * any other key outside the schema makes the projection fail (content-bearing).
+ * @returns {{ok:true,message:object}|{ok:false,reason:string,field?:string}}
+ */
+export function projectResponse(requestId, command, result) {
+    const schema = OUTBOUND_SCHEMAS.response;
+    const strip = RESPONSE_STRIP[command] || [];
+    const out = { requestId, command };
+    let hadFreeText = false;
+    for (const [key, value] of Object.entries(result && typeof result === "object" ? result : {})) {
+        if (key === "requestId" || key === "command") continue;
+        if (strip.includes(key)) continue;
+        if (FREE_TEXT_KEYS.includes(key)) { hadFreeText = true; continue; }
+        if (!Object.prototype.hasOwnProperty.call(schema, key)) return { ok: false, reason: "unknown-field", field: key };
+        out[key] = value;
+    }
+    if (hadFreeText) { out.ok = false; out.errorCode = "command_error"; }
+    return { ok: true, message: out };
+}

package/src/ws-channel/config.js

@@ -0,0 +1,22 @@
+/**
+ * config.js - LOCAL_AGENT_WS_METADATA_ONLY flag (T4-10).
+ *
+ *   off     (default) legacy behaviour, byte-for-byte: the WS tunnel is untouched.
+ *   enforce metadata-only: the outbound WS channel carries ONLY allowlisted
+ *           metadata (state, counts, hashes, ids, cost) and never content
+ *           (code, diffs, logs, chat text). D19 (offline PolicyGate = DENY) is
+ *           activated by the same flag.
+ *
+ * Unset/empty = off. A non-empty but unrecognised value fails CLOSED to
+ * `enforce` (a typo must never silently re-open the content path).
+ */
+export const WS_METADATA_FLAG = "LOCAL_AGENT_WS_METADATA_ONLY";
+export const WS_METADATA_MODES = Object.freeze(["off", "enforce"]);
+
+export function resolveWsMetadataConfig(env = process.env, warn = console.warn) {
+    const raw = String(env[WS_METADATA_FLAG] ?? "").trim().toLowerCase();
+    if (raw === "") return { mode: "off" };
+    if (WS_METADATA_MODES.includes(raw)) return { mode: raw };
+    warn(`[ws-metadata] unrecognised ${WS_METADATA_FLAG} value; failing closed to 'enforce'`);
+    return { mode: "enforce" };
+}

package/src/ws-channel/connection-state.js

@@ -0,0 +1,18 @@
+/**
+ * connection-state.js - is the Local Agent connected to the control plane?
+ * Input for D19 (offline PolicyGate = DENY). Online = the tunnel socket is open
+ * AND something (message or pong) was seen within `staleAfterMs`; the heartbeat
+ * is 30 s, so the default tolerates one missed beat.
+ */
+export const DEFAULT_STALE_AFTER_MS = 90_000;
+
+export function createConnectionState({ now = Date.now, staleAfterMs = DEFAULT_STALE_AFTER_MS } = {}) {
+    let open = false;
+    let lastSeen = 0;
+    return {
+        markOpen() { open = true; lastSeen = now(); },
+        markClosed() { open = false; },
+        markSeen() { if (open) lastSeen = now(); },
+        isOnline() { return open && now() - lastSeen <= staleAfterMs; },
+    };
+}

package/src/ws-channel/index.js

@@ -0,0 +1,6 @@
+export { resolveWsMetadataConfig, WS_METADATA_FLAG, WS_METADATA_MODES } from "./config.js";
+export { createWsMetadataGuard } from "./metadata-guard.js";
+export { createConnectionState } from "./connection-state.js";
+export { createOfflinePolicyGuard, requiresPolicyGate, decideOffline, OFFLINE_DENY_REASON } from "./policy-offline.js";
+export { validateOutbound, projectResponse, METADATA_COMMANDS, OUTBOUND_SCHEMAS } from "./allowlist.js";
+export { createTransitGuard, DEFAULT_LIMITS } from "./transit-guard.js";