deepdebug-local-agent 1.2.0 → 1.4.0

package/src/la-protocol-v2/strict-json.js

@@ -0,0 +1,47 @@
+/**
+ * strict-json.js - JSON.parse that refuses duplicate object keys (the gateway refuses them too: with a
+ * duplicate, two parsers could disagree about which value a signed field has).
+ *
+ * parseStrict(text) -> value. Throws on invalid JSON or on a duplicate key at any depth.
+ * Implemented as a small scanner for the keys plus the native parser for the values, so the parsed
+ * result is exactly what JSON.parse returns.
+ */
+export function parseStrict(text) {
+    const value = JSON.parse(text); // throws on invalid JSON
+    assertNoDuplicateKeys(text);
+    return value;
+}
+
+function assertNoDuplicateKeys(text) {
+    const stack = []; // one Set of keys per open object; null for arrays
+    let i = 0;
+    const n = text.length;
+    let expectKey = false;
+    while (i < n) {
+        const c = text.charCodeAt(i);
+        if (c === 0x22 /* " */) {
+            const start = i + 1;
+            i++;
+            while (i < n) {
+                const d = text.charCodeAt(i);
+                if (d === 0x5c /* \ */) { i += 2; continue; }
+                if (d === 0x22) break;
+                i++;
+            }
+            const top = stack[stack.length - 1];
+            if (expectKey && top) {
+                const key = JSON.parse(`"${text.slice(start, i)}"`);
+                if (top.has(key)) throw new Error("duplicate key");
+                top.add(key);
+                expectKey = false;
+            }
+            i++;
+            continue;
+        }
+        if (c === 0x7b /* { */) { stack.push(new Set()); expectKey = true; }
+        else if (c === 0x5b /* [ */) { stack.push(null); expectKey = false; }
+        else if (c === 0x7d || c === 0x5d) { stack.pop(); expectKey = false; }
+        else if (c === 0x2c /* , */) { expectKey = stack.length > 0 && stack[stack.length - 1] !== null; }
+        i++;
+    }
+}

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,9 @@ 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 { resolveProtocolV2Config, resolveAgentId } from "./la-protocol-v2/config.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 +640,24 @@ 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();
+// LOCAL_AGENT_PROTOCOL_V2 (F3-05b, default off): with it off the tunnel below is the v1 client, untouched.
+const PROTOCOL_V2 = resolveProtocolV2Config();
+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
@@ -6923,7 +6944,7 @@ app.post("/workspace/:workspaceId/run", async (req, res) => {
 //  WEBSOCKET REVERSE TUNNEL
 // Connects Local Agent to Gateway  no public URL needed
 // ============================================
-async function startWebSocketTunnel(port, gatewayUrl, authToken, tenantId) {
+async function startWebSocketTunnel(port, gatewayUrl, authToken, tenantId, agentId = null) {
     if (!gatewayUrl || !tenantId) {
         console.log('WebSocket tunnel skipped: missing gatewayUrl or tenantId');
         return;
@@ -6953,6 +6974,22 @@ 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);
+    };
+    // Protocol v2 (F3-05b): only when LOCAL_AGENT_PROTOCOL_V2=true. null = the v1 client exactly as before.
+    let v2Link = null;
+    if (PROTOCOL_V2.enabled) {
+        try {
+            const { buildV2Link } = await import('./la-protocol-v2/runtime.js');
+            v2Link = buildV2Link({ tenantId, agentId, signing: SIGNING, wsManager, getWorkspaceRoot: () => WORKSPACE_ROOT });
+        } catch (err) {
+            console.warn(`[la-v2] off: ${err.code || err.name} while loading the protocol module`);
+        }
+    }
 
     async function connect() {
         if (isShuttingDown) return;
@@ -6963,16 +7000,32 @@ 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 };
+                const sendLegacyRegister = () => sendFrame(legacyRegister, metaGuard && metaGuard.frameMessage({
+                    type: 'register', tenantId, port: Number(port),
+                    ...(WORKSPACE_ROOT ? { workspaceHash: wsCreateHash("sha256").update(String(WORKSPACE_ROOT)).digest('hex') } : {}),
+                }));
+                // v2 owns the registration while it negotiates; the v1 register goes out only if the gateway does not speak v2.
+                if (!(v2Link && v2Link.begin(ws, sendLegacyRegister))) sendLegacyRegister();
                 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('message', async (data) => {
+            ws.on('pong', () => WS_CONNECTION.markSeen());
+
+            ws.on('message', async (data, isBinary) => {
+                WS_CONNECTION.markSeen();
                 const text = data.toString();
                 if (text === 'pong') return;
+                // v2 frames (schemaVersion) are handled by the protocol module; v1 commands fall through to the handler below.
+                if (v2Link && v2Link.handleMessage(ws, text, isBinary)) return;
                 let request;
                 try { request = JSON.parse(text); } catch { return; }
                 const { requestId, command } = request;
@@ -6982,16 +7035,24 @@ 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 (v2Link) v2Link.onClose(ws);
                 if (!isShuttingDown) {
                     console.log(`WS disconnected. Reconnecting in ${reconnectDelay/1000}s...`);
                     setTimeout(connect, reconnectDelay);
@@ -8121,7 +8182,7 @@ app.listen(PORT, BIND_HOST, async () => {
     }
 
     if (process.env.DISABLE_WS_TUNNEL !== 'true') {
-        startWebSocketTunnel(PORT, gwUrl, wsToken, tenantId);
+        startWebSocketTunnel(PORT, gwUrl, wsToken, tenantId, resolveAgentId(process.env, cfg));
     }
 
     // Sibling plane (started here so the frozen monolith is untouched): metrics
@@ -8151,7 +8212,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/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";

package/src/ws-channel/metadata-guard.js

@@ -0,0 +1,78 @@
+/**
+ * metadata-guard.js - the metadata-only outbound filter for the Local Agent WS
+ * channel (T4-10). A NEW filtering module: it opens no socket itself and
+ * returns null when the flag is off, so with the flag off nothing changes.
+ *
+ * Every outbound message passes: size limit -> rate limit -> allowlist
+ * validation. A violation is dropped, logged WITHOUT its content (type, field
+ * name, reason code, byte size) and, for command replies, answered with a
+ * metadata-only error so the control plane does not wait for a timeout.
+ */
+import { METADATA_COMMANDS, validateOutbound, projectResponse } from "./allowlist.js";
+import { createTransitGuard } from "./transit-guard.js";
+
+export function createWsMetadataGuard({ config, transit, logger = console, now = Date.now } = {}) {
+    if (!config || config.mode !== "enforce") return null; // flag off: no guard, no behaviour change
+    const guard = transit || createTransitGuard({ now });
+    const stats = { sent: 0, blocked: 0 };
+
+    // Content-free log line: only codes/names/sizes, never values.
+    const logBlocked = (info) => {
+        stats.blocked++;
+        logger.warn(`[ws-metadata] BLOCKED ${JSON.stringify(info)}`);
+    };
+
+    /** Serialises + checks one message. @returns {string|null} the frame to send, null if blocked. */
+    function frame(msg) {
+        const v = validateOutbound(msg);
+        if (!v.ok) { logBlocked({ reason: v.reason, type: v.type || null, field: v.field || null }); return null; }
+        const serialized = JSON.stringify(msg);
+        const size = guard.checkSize(serialized);
+        if (!size.ok) { logBlocked({ reason: size.reason, type: v.type }); return null; }
+        const rate = guard.checkRate();
+        if (!rate.ok) { logBlocked({ reason: rate.reason, type: v.type }); return null; }
+        stats.sent++;
+        return serialized;
+    }
+
+    const errorFrame = (requestId, command, errorCode) =>
+        frame({ requestId, command, ok: false, errorCode });
+
+    return {
+        mode: "enforce",
+        stats,
+        /** Spontaneous (non-reply) messages: register, hello, status, cost. */
+        frameMessage: frame,
+        /**
+         * Inbound command gate: legacy content commands never execute in
+         * metadata-only mode. @returns {{ok:true}|{ok:false,errorFrame:string|null}}
+         */
+        admitCommand(requestId, command) {
+            if (!METADATA_COMMANDS.includes(command)) {
+                logBlocked({ reason: "command-not-allowed", type: "command", field: "command" });
+                return { ok: false, errorFrame: errorFrame(requestId, command, "blocked_metadata_only") };
+            }
+            const a = guard.admitRequest(requestId);
+            if (!a.ok) return { ok: false, errorFrame: errorFrame(requestId, command, "rate_limited") };
+            return { ok: true };
+        },
+        /** Reply to an admitted command: projected onto the allowlist, TTL-checked, validated. */
+        frameResponse(requestId, command, result) {
+            const t = guard.consumeRequest(requestId);
+            if (!t.ok) {
+                logBlocked({ reason: t.reason, type: "response" });
+                return null; // nothing to reply to / too late: drop silently (no queueing)
+            }
+            const p = projectResponse(requestId, command, result);
+            if (!p.ok) {
+                logBlocked({ reason: p.reason, type: "response", field: p.field || null });
+                return errorFrame(requestId, command, "blocked_metadata_only");
+            }
+            return frame(p.message) || errorFrame(requestId, command, "blocked_metadata_only");
+        },
+        /** Error reply for a request that never reached execution (e.g. bad signature). */
+        frameError(requestId, command, errorCode) {
+            return errorFrame(requestId, command, errorCode);
+        },
+    };
+}

package/src/ws-channel/policy-offline.js

@@ -0,0 +1,40 @@
+/**
+ * policy-offline.js - D19: PolicyGate per action; offline = DENY (fail-closed).
+ *
+ * Actions that need a PolicyGate decision (a platform-authored tool command or
+ * a human-approval token) are denied while the agent has no live connection to
+ * the control plane. Purely local, allowlisted commands do not need PolicyGate
+ * and are unaffected. Active only when LOCAL_AGENT_WS_METADATA_ONLY=enforce.
+ */
+
+/** decideExec().via prefixes that mean "PolicyGate authorised this". */
+const GATED_VIA_PREFIXES = Object.freeze(["platform-tool:", "human-approval:"]);
+
+export const OFFLINE_DENY_REASON = "PolicyGate unreachable: no connection to the control plane (offline = DENY)";
+
+export function requiresPolicyGate(via) {
+    return typeof via === "string" && GATED_VIA_PREFIXES.some((p) => via.startsWith(p));
+}
+
+/**
+ * Generic per-action decision.
+ * @returns {{decision:"ALLOW"|"DENY",reason?:string}}
+ */
+export function decideOffline({ gated, online }) {
+    if (gated && !online) return { decision: "DENY", reason: OFFLINE_DENY_REASON };
+    return { decision: "ALLOW" };
+}
+
+/**
+ * Builds the guard plugged into exec-policy (`cfg.offlineGuard`): receives a
+ * decideExec() result and downgrades PolicyGate-backed ALLOWs to DENY when offline.
+ */
+export function createOfflinePolicyGuard({ connection, onDeny = () => {} }) {
+    return function offlineGuard(decision) {
+        if (!decision || !decision.allow || !requiresPolicyGate(decision.via)) return decision;
+        const verdict = decideOffline({ gated: true, online: connection.isOnline() });
+        if (verdict.decision === "ALLOW") return decision;
+        onDeny({ via: decision.via.split(":")[0] });
+        return { allow: false, status: 403, reason: verdict.reason, via: "policy-gate-offline" };
+    };
+}

package/src/ws-channel/transit-guard.js

@@ -0,0 +1,55 @@
+/**
+ * transit-guard.js - D17 controls for content/metadata in transit through the
+ * control plane: nothing is persisted or queued here, no payload is ever
+ * logged, replies are only sent for known requests inside a TTL, and size and
+ * rate are bounded.
+ */
+export const DEFAULT_LIMITS = Object.freeze({
+    maxMessageBytes: 4096,
+    requestTtlMs: 60_000,
+    maxInFlight: 256,
+    rateWindowMs: 10_000,
+    rateMax: 200,
+});
+
+export function createTransitGuard({ now = Date.now, limits = {} } = {}) {
+    const lim = { ...DEFAULT_LIMITS, ...limits };
+    const inFlight = new Map(); // requestId -> expiresAt (in memory only; never persisted)
+    let windowStart = now();
+    let windowCount = 0;
+
+    const sweep = () => {
+        const t = now();
+        for (const [id, exp] of inFlight) if (exp <= t) inFlight.delete(id);
+    };
+
+    return {
+        limits: lim,
+        /** Registers an inbound request. @returns {{ok:true}|{ok:false,reason:string}} */
+        admitRequest(requestId) {
+            sweep();
+            if (inFlight.size >= lim.maxInFlight) return { ok: false, reason: "too-many-in-flight" };
+            inFlight.set(requestId, now() + lim.requestTtlMs);
+            return { ok: true };
+        },
+        /** A reply may only be sent once, to a known request, before its TTL. */
+        consumeRequest(requestId) {
+            const exp = inFlight.get(requestId);
+            if (exp === undefined) return { ok: false, reason: "unknown-request" };
+            inFlight.delete(requestId);
+            if (exp <= now()) return { ok: false, reason: "request-expired" };
+            return { ok: true };
+        },
+        checkSize(serialized) {
+            return Buffer.byteLength(serialized, "utf8") <= lim.maxMessageBytes ? { ok: true } : { ok: false, reason: "message-too-large" };
+        },
+        checkRate() {
+            const t = now();
+            if (t - windowStart >= lim.rateWindowMs) { windowStart = t; windowCount = 0; }
+            if (windowCount >= lim.rateMax) return { ok: false, reason: "rate-limited" };
+            windowCount++;
+            return { ok: true };
+        },
+        pending: () => inFlight.size,
+    };
+}