deepdebug-local-agent 1.2.0 → 1.3.0

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 (opt-in, off by default)
+
+- **`LOCAL_AGENT_WS_METADATA_ONLY=off|enforce`** (T4-10, D17, D19). `enforce`
+  restricts the outbound WS channel to allowlisted metadata (ids, hashes,
+  counts, state, cost), refuses legacy content commands and denies
+  PolicyGate-backed actions while the control plane is unreachable. See
+  `docs/ws-metadata-only.md`. No behaviour change when off.
 ### Added
 
 - **DLP module (`src/dlp/`, flag `LOCAL_AGENT_DLP_MODE=off|warn|enforce`, default `off`).**

package/docs/ws-metadata-only.md

@@ -0,0 +1,44 @@
+# WS metadata-only mode (T4-10, D17, D19)
+
+Flag: `LOCAL_AGENT_WS_METADATA_ONLY=off|enforce` (default `off`; an unrecognised value fails closed to `enforce`).
+
+## What `enforce` does
+
+1. **Outbound allowlist** (`src/ws-channel/allowlist.js`). Only these message types leave the agent:
+   `register`, `hello`, `status`, `cost` and command replies (`requestId`/`command`/`ok`/`status`/`openWorkspaces`/`errorCode`).
+   Fields are typed as ids, sha256 hashes, bounded integers, booleans or fixed enums. There is no free-text
+   field, so code, diffs, logs and chat text cannot be carried. `register` sends `workspaceHash` (sha256) instead of `workspacePath`.
+2. **Legacy content commands are refused before execution** (`workspace.file-content`, `workspace.diff`,
+   `workspace.safe-patch`, `mcp.*`, ...). Only `health` and `workspace.open` run; the reply is
+   `{ok:false, errorCode:"blocked_metadata_only"}`. Free-text error messages become `errorCode`.
+3. **Rejections are logged without content**: `[ws-metadata] BLOCKED {"reason":..,"type":..,"field":..}` (field names and codes only).
+4. **D17 transit controls**: nothing is persisted or queued by the module (blocked/over-limit messages are dropped);
+   a reply is sent only once, for a known request, within 60 s (TTL); 4 KiB per message; 200 messages per 10 s; 256 in-flight requests.
+5. **D19 offline = DENY**: while the tunnel is not open (or silent for more than 90 s), exec decisions that depend on
+   PolicyGate (signed platform tool commands, human-approval tokens) are denied with `via=policy-gate-offline`.
+   Allowlisted local commands do not need PolicyGate and are unaffected. Note: with `DISABLE_WS_TUNNEL=true` the agent is
+   permanently "offline", so these actions are always denied under `enforce` (a startup warning is logged; product decision for standalone agents pending, see Open points).
+   The same guard is shared with the MCP bridge (`/mcp/execute-command`), so the DENY applies to both exec entry points.
+
+## Reserved contract and known limits
+
+- `hello`, `status` and `cost` are **reserved contract types: nothing emits them yet**. They are in the allowlist so that the
+  protocol v2 emitters (F3-05b, not merged) can be added without widening the closed world. Only `register` and command replies are sent today.
+- `workspace.open` stays allowed in `enforce` (D16: VH is authoritative). It can still change local state (it sets the workspace root
+  from `params.root` sent by the control plane, protected by request signing); only its reply is projected to metadata.
+- D19 liveness relies on the gateway answering the protocol `ping` (or the text `ping` with `pong`) within 90 s. This has **not** been
+  verified against the real QA gateway; validate it before enabling `enforce` in QA (open point on the PR).
+
+## What does not change
+
+With the flag off (default) the tunnel, the register frame, command handling and exec policy are byte-for-byte the legacy ones.
+The module opens no socket of its own. DLP (`src/dlp/*`), signing, bind and Helm are untouched.
+
+## Rollback
+
+Unset `LOCAL_AGENT_WS_METADATA_ONLY` (or set `off`) and restart the agent.
+
+## Extending the contract
+
+Add the type/field to `OUTBOUND_SCHEMAS` and a golden example to `test/ws-channel/allowlist.test.js` (the closed-set test fails on purpose).
+The CP-side contract (F3-05b protocol v2) is not merged yet; align the schema with it when it lands.

package/env.example

@@ -70,6 +70,13 @@ LOG_LEVEL=info
 # LOCAL_AGENT_WORKSPACE_ID=
 # LOCAL_AGENT_REQUIRE_WORKSPACE=false
 
+# LOCAL_AGENT_WS_METADATA_ONLY=off|enforce (default off). enforce: the outbound WS channel to the
+# control plane carries ONLY allowlisted metadata (ids, hashes, counts, state, cost) and never
+# content (code, diffs, logs, chat). Legacy content commands are refused in this mode, and
+# PolicyGate-backed actions (platform tool commands, human approvals) are DENIED while the agent
+# has no live connection to the control plane (D19). Unrecognised values fail closed to enforce.
+# LOCAL_AGENT_WS_METADATA_ONLY=off
+
 # 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.2.0",
+  "version": "1.3.0",
   "description": "DeepDebug Local Agent - AI-powered code debugging assistant",
   "private": false,
   "type": "module",

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/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,
+    };
+}

package/test/ws-channel/allowlist.test.js

@@ -0,0 +1,67 @@
+// Contract tests for the metadata-only outbound allowlist (T4-10).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { validateOutbound, projectResponse, OUTBOUND_SCHEMAS } from '../../src/ws-channel/allowlist.js';
+
+const H = 'a'.repeat(64);
+
+test('contract: every allowed message type validates with a golden example', () => {
+  const golden = [
+    { type: 'register', tenantId: 'tenant-1', port: 5055, workspaceHash: H },
+    { type: 'hello', agentVersion: '1.1.0', protocol: 2, signatureMode: 'enforce', metadataOnly: 'enforce' },
+    { type: 'status', state: 'idle', openWorkspaces: 2, queueDepth: 0, uptimeSeconds: 120 },
+    { type: 'cost', requestId: 'req-1', model: 'claude-sonnet-5-5', tokensIn: 10, tokensOut: 5, costMicros: 1200 },
+    { requestId: 'r1', command: 'health', ok: true, status: 'ok', openWorkspaces: 1 },
+    { requestId: 'r2', command: 'workspace.open', ok: false, errorCode: 'command_error' },
+  ];
+  for (const m of golden) assert.deepEqual(validateOutbound(m).ok, true, JSON.stringify(m));
+});
+
+test('contract: schema set is closed (changing it is a deliberate, reviewed edit)', () => {
+  assert.deepEqual(Object.keys(OUTBOUND_SCHEMAS).sort(), ['cost', 'hello', 'register', 'response', 'status']);
+});
+
+test('rejects unknown types, unknown fields and non-objects', () => {
+  assert.equal(validateOutbound({ type: 'file-content', content: 'x' }).reason, 'unknown-type');
+  assert.equal(validateOutbound({ type: 'status', state: 'idle', content: 'x' }).reason, 'unknown-field');
+  assert.equal(validateOutbound('ping').reason, 'not-an-object');
+  assert.equal(validateOutbound([]).reason, 'not-an-object');
+  assert.equal(validateOutbound({ type: '__proto__' }).reason, 'unknown-type');
+});
+
+test('rejects free text: code, diffs, paths, log lines and chat do not fit any string field', () => {
+  const leaks = ['const x = require("fs");', '--- a/x\n+++ b/x', '/Users/me/project/src/A.java', 'ERROR something failed', 'hello how are you', ''];
+  for (const v of leaks) {
+    assert.equal(validateOutbound({ type: 'register', tenantId: v, port: 1 }).ok, false, JSON.stringify(v));
+    assert.equal(validateOutbound({ type: 'cost', requestId: 'r', model: v }).ok, false);
+    assert.equal(validateOutbound({ requestId: 'r', command: v }).ok, false);
+  }
+  assert.equal(validateOutbound({ type: 'register', tenantId: 't', port: 1, workspaceHash: '/etc/passwd' }).field, 'workspaceHash');
+});
+
+test('rejects nested values, wrong numeric ranges and missing required fields', () => {
+  assert.equal(validateOutbound({ type: 'status', state: { a: 1 } }).ok, false);
+  assert.equal(validateOutbound({ type: 'status', openWorkspaces: -1 }).ok, false);
+  assert.equal(validateOutbound({ type: 'status', openWorkspaces: 1.5 }).ok, false);
+  assert.equal(validateOutbound({ type: 'register', port: 70000, tenantId: 't' }).ok, false);
+  assert.equal(validateOutbound({ type: 'register', port: 5055 }).reason, 'missing-field');
+  assert.equal(validateOutbound({ type: 'status', state: 'unknown-state' }).ok, false);
+});
+
+test('validation reports field names and codes, never the offending value', () => {
+  const secret = 'AKIA_SECRET_VALUE_123 /home/x';
+  const r = validateOutbound({ type: 'register', tenantId: secret, port: 1 });
+  assert.equal(JSON.stringify(r).includes('SECRET'), false);
+});
+
+test('projectResponse strips paths, turns free text into errorCode, rejects content fields', () => {
+  assert.deepEqual(projectResponse('r', 'health', { status: 'ok', workspace: '/home/u/p', openWorkspaces: 1 }).message,
+    { requestId: 'r', command: 'health', status: 'ok', openWorkspaces: 1 });
+  assert.deepEqual(projectResponse('r', 'workspace.open', { ok: true, root: '/home/u/p' }).message,
+    { requestId: 'r', command: 'workspace.open', ok: true });
+  assert.deepEqual(projectResponse('r', 'x', { error: 'ENOENT /home/u/secret.txt' }).message,
+    { requestId: 'r', command: 'x', ok: false, errorCode: 'command_error' });
+  const c = projectResponse('r', 'workspace.file-content', { content: 'code', found: true });
+  assert.equal(c.ok, false);
+  assert.equal(c.field, 'content');
+});

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

@@ -0,0 +1,104 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createWsMetadataGuard } from '../../src/ws-channel/metadata-guard.js';
+import { resolveWsMetadataConfig } from '../../src/ws-channel/config.js';
+import { createTransitGuard } from '../../src/ws-channel/transit-guard.js';
+
+const capture = () => { const lines = []; return { lines, warn: (m) => lines.push(String(m)), log: (m) => lines.push(String(m)) }; };
+const enforce = { mode: 'enforce' };
+
+test('flag config: default off, enforce, and unrecognised values fail closed', () => {
+  const warn = () => {};
+  assert.equal(resolveWsMetadataConfig({}, warn).mode, 'off');
+  assert.equal(resolveWsMetadataConfig({ LOCAL_AGENT_WS_METADATA_ONLY: '' }, warn).mode, 'off');
+  assert.equal(resolveWsMetadataConfig({ LOCAL_AGENT_WS_METADATA_ONLY: 'off' }, warn).mode, 'off');
+  assert.equal(resolveWsMetadataConfig({ LOCAL_AGENT_WS_METADATA_ONLY: ' ENFORCE ' }, warn).mode, 'enforce');
+  assert.equal(resolveWsMetadataConfig({ LOCAL_AGENT_WS_METADATA_ONLY: 'enfroce' }, warn).mode, 'enforce');
+});
+
+test('flag off: no guard is created and no socket is opened', () => {
+  let socketsOpened = 0;
+  const openSocket = () => { socketsOpened++; };
+  const guard = createWsMetadataGuard({ config: resolveWsMetadataConfig({}) });
+  assert.equal(guard, null);
+  if (guard) openSocket(); // the conditional start point: only reached when the guard exists
+  assert.equal(socketsOpened, 0);
+});
+
+test('legacy content commands are refused before execution, with a metadata-only error', () => {
+  const log = capture();
+  const g = createWsMetadataGuard({ config: enforce, logger: log });
+  for (const cmd of ['workspace.file-content', 'workspace.diff', 'workspace.safe-patch', 'mcp.read-file', 'mcp.execute-command', 'mcp.apply-patch']) {
+    const a = g.admitCommand('req-1', cmd);
+    assert.equal(a.ok, false, cmd);
+    assert.deepEqual(JSON.parse(a.errorFrame), { requestId: 'req-1', command: cmd, ok: false, errorCode: 'blocked_metadata_only' });
+  }
+});
+
+test('health reply carries only metadata (workspace path dropped)', () => {
+  const g = createWsMetadataGuard({ config: enforce, logger: capture() });
+  assert.equal(g.admitCommand('r1', 'health').ok, true);
+  const out = JSON.parse(g.frameResponse('r1', 'health', { status: 'ok', workspace: '/Users/x/client-repo', openWorkspaces: 2 }));
+  assert.deepEqual(out, { requestId: 'r1', command: 'health', status: 'ok', openWorkspaces: 2 });
+});
+
+test('content in a reply is blocked, replaced by an error, and never logged', () => {
+  const log = capture();
+  const g = createWsMetadataGuard({ config: enforce, logger: log });
+  g.admitCommand('r2', 'health');
+  const secret = 'SUPER_SECRET_SOURCE_CODE_LINE';
+  const out = JSON.parse(g.frameResponse('r2', 'health', { status: 'ok', diff: secret }));
+  assert.deepEqual(out, { requestId: 'r2', command: 'health', ok: false, errorCode: 'blocked_metadata_only' });
+  assert.ok(log.lines.some((l) => l.includes('BLOCKED') && l.includes('unknown-field') && l.includes('diff')));
+  assert.equal(log.lines.join('\n').includes(secret), false, 'payload must never be logged');
+  assert.equal(JSON.stringify(out).includes(secret), false);
+});
+
+test('free-text error messages become an errorCode and are not sent', () => {
+  const g = createWsMetadataGuard({ config: enforce, logger: capture() });
+  g.admitCommand('r3', 'workspace.open');
+  const out = JSON.parse(g.frameResponse('r3', 'workspace.open', { error: 'ENOENT: /home/u/secret/file.js' }));
+  assert.deepEqual(out, { requestId: 'r3', command: 'workspace.open', ok: false, errorCode: 'command_error' });
+});
+
+test('spontaneous messages are validated; violations return null (dropped, not queued)', () => {
+  const log = capture();
+  const g = createWsMetadataGuard({ config: enforce, logger: log });
+  assert.ok(g.frameMessage({ type: 'status', state: 'idle', openWorkspaces: 1 }));
+  assert.equal(g.frameMessage({ type: 'chat', text: 'hi' }), null);
+  assert.equal(g.frameMessage({ type: 'register', tenantId: 't', port: 1, workspacePath: '/x' }), null);
+  assert.equal(g.stats.blocked, 2);
+});
+
+test('D17 TTL: reply to an unknown, expired or already-answered request is dropped', () => {
+  let t = 1_000;
+  const transit = createTransitGuard({ now: () => t, limits: { requestTtlMs: 1000 } });
+  const g = createWsMetadataGuard({ config: enforce, transit, logger: capture() });
+  assert.equal(g.frameResponse('never', 'health', { status: 'ok' }), null);
+  g.admitCommand('a', 'health');
+  assert.ok(g.frameResponse('a', 'health', { status: 'ok' }));
+  assert.equal(g.frameResponse('a', 'health', { status: 'ok' }), null, 'single use');
+  g.admitCommand('b', 'health');
+  t += 1500;
+  assert.equal(g.frameResponse('b', 'health', { status: 'ok' }), null, 'expired');
+});
+
+test('D17 limits: message size, rate and in-flight bound', () => {
+  const transit = createTransitGuard({ limits: { rateMax: 2, maxInFlight: 2, maxMessageBytes: 60 } });
+  const g = createWsMetadataGuard({ config: enforce, transit, logger: capture() });
+  assert.equal(g.frameMessage({ type: 'cost', requestId: 'r', model: 'm'.repeat(100) }), null, 'oversize');
+  assert.ok(g.frameMessage({ type: 'status', state: 'idle' }));
+  assert.ok(g.frameMessage({ type: 'status', state: 'busy' }));
+  assert.equal(g.frameMessage({ type: 'status', state: 'idle' }), null, 'rate limited');
+  assert.equal(g.admitCommand('x1', 'health').ok, true);
+  assert.equal(g.admitCommand('x2', 'health').ok, true);
+  assert.equal(g.admitCommand('x3', 'health').ok, false, 'in-flight cap');
+});
+
+test('D17: the guard persists nothing (no fs/network usage in the module)', async () => {
+  const { readFile } = await import('node:fs/promises');
+  for (const f of ['metadata-guard', 'transit-guard', 'allowlist']) {
+    const src = await readFile(new URL(`../../src/ws-channel/${f}.js`, import.meta.url), 'utf8');
+    assert.equal(/node:fs|from "fs"|appendFile|writeFile|node:net|node:http/.test(src), false, f);
+  }
+});

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

@@ -0,0 +1,99 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createConnectionState } from '../../src/ws-channel/connection-state.js';
+import { createOfflinePolicyGuard, requiresPolicyGate, decideOffline } from '../../src/ws-channel/policy-offline.js';
+import { decideExec } from '../../src/utils/exec-policy.js';
+
+test('connection state: online only while open and fresh', () => {
+  let t = 0;
+  const c = createConnectionState({ now: () => t, staleAfterMs: 90_000 });
+  assert.equal(c.isOnline(), false);
+  c.markOpen();
+  assert.equal(c.isOnline(), true);
+  t = 60_000; c.markSeen();
+  t = 120_000;
+  assert.equal(c.isOnline(), true);
+  t = 200_000;
+  assert.equal(c.isOnline(), false, 'stale = offline');
+  c.markSeen(); // ignored while stale? still open, refreshes
+  assert.equal(c.isOnline(), true);
+  c.markClosed();
+  assert.equal(c.isOnline(), false);
+  c.markSeen();
+  assert.equal(c.isOnline(), false, 'a message on a closed socket does not revive it');
+});
+
+test('D19 classification: only PolicyGate-backed decisions need the gate', () => {
+  assert.equal(requiresPolicyGate('platform-tool:git_push'), true);
+  assert.equal(requiresPolicyGate('human-approval:ana'), true);
+  assert.equal(requiresPolicyGate('allowlist:git'), false);
+  assert.equal(requiresPolicyGate('policy-off'), false);
+  assert.deepEqual(decideOffline({ gated: true, online: false }).decision, 'DENY');
+  assert.deepEqual(decideOffline({ gated: true, online: true }).decision, 'ALLOW');
+  assert.deepEqual(decideOffline({ gated: false, online: false }).decision, 'ALLOW');
+});
+
+test('D19 guard: offline DENY for gated allows, allowlisted local commands unaffected', () => {
+  const state = { online: false };
+  const denied = [];
+  const guard = createOfflinePolicyGuard({ connection: { isOnline: () => state.online }, onDeny: (d) => denied.push(d) });
+  const gated = { allow: true, via: 'platform-tool:git_push' };
+  const local = { allow: true, via: 'allowlist:git' };
+
+  const d = guard(gated);
+  assert.equal(d.allow, false);
+  assert.equal(d.status, 403);
+  assert.equal(d.via, 'policy-gate-offline');
+  assert.deepEqual(denied, [{ via: 'platform-tool' }]);
+  assert.equal(guard(local), local);
+  assert.deepEqual(guard({ allow: false, via: 'rejected' }), { allow: false, via: 'rejected' });
+
+  state.online = true;
+  assert.equal(guard(gated), gated, 'online: PolicyGate path unchanged');
+});
+
+test('D19 via decideExec: a signed platform tool is denied offline, allowed online; flag off = unchanged', () => {
+  const input = {
+    command: 'git push origin feat/x', root: process.cwd(), headers: {},
+    body: { commandOrigin: 'platform', tool: 'git_push' }, vhSignature: { verified: true },
+  };
+  const base = { mode: 'enforce' };
+  assert.equal(decideExec(input, base).allow, true, 'flag off (no guard): unchanged');
+  let online = false;
+  const cfg = { mode: 'enforce', offlineGuard: createOfflinePolicyGuard({ connection: { isOnline: () => online } }) };
+  const off = decideExec(input, cfg);
+  assert.equal(off.allow, false);
+  assert.equal(off.via, 'policy-gate-offline');
+  online = true;
+  assert.equal(decideExec(input, cfg).allow, true);
+});
+
+test('D19 on the MCP bridge: /mcp/execute-command denies a platform tool offline, allows it online', async () => {
+  const net = await import('node:net');
+  const { startMCPHttpServer } = await import('../../src/mcp-http-server.js');
+  const { internalSignatureHeaders } = await import('../../src/utils/request-signing.js');
+  const port = await new Promise((resolve) => {
+    const s = net.createServer().listen(0, '127.0.0.1', () => { const p = s.address().port; s.close(() => resolve(p)); });
+  });
+  let online = false;
+  const execPolicy = { mode: 'enforce', offlineGuard: createOfflinePolicyGuard({ connection: { isOnline: () => online } }) };
+  const app = startMCPHttpServer({ resolveRoot: () => process.cwd(), count: 0, list: () => [] }, port, execPolicy);
+  await new Promise((r) => (app.locals.server.listening ? r() : app.locals.server.once('listening', r)));
+  try {
+    const call = () => fetch(`http://127.0.0.1:${port}/mcp/execute-command`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...internalSignatureHeaders() },
+      body: JSON.stringify({ workspaceId: 'w', command: 'git --version', commandOrigin: 'platform', tool: 'current_branch' }),
+    });
+    const off = await call();
+    const offBody = await off.json();
+    assert.equal(off.status, 403);
+    assert.equal(offBody.ok, false);
+    assert.match(String(offBody.reason), /control plane|offline|policy/i);
+    online = true;
+    const on = await call();
+    assert.notEqual(on.status, 403, 'online: PolicyGate path unchanged');
+  } finally {
+    app.locals.server.close();
+  }
+});

package/test/ws-channel/tunnel-e2e.test.js

@@ -0,0 +1,88 @@
+// End-to-end: boots the real agent against a fake control-plane WS server and
+// inspects what actually leaves the socket (T4-10).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import net from 'node:net';
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { WebSocketServer } from 'ws';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const SECRET = 'TOP_SECRET_SOURCE_MARKER_8841';
+
+const freePort = () => new Promise((res) => { const s = net.createServer().listen(0, '127.0.0.1', () => { const p = s.address().port; s.close(() => res(p)); }); });
+
+async function run({ flag, disableTunnel = false }) {
+  const ws = fs.mkdtempSync(path.join(os.tmpdir(), 'wsmeta-ws-'));
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'wsmeta-home-'));
+  fs.writeFileSync(path.join(ws, 'secret.txt'), SECRET);
+  const wss = new WebSocketServer({ port: 0, host: '127.0.0.1' });
+  await new Promise((r) => wss.on('listening', r));
+  const frames = [];
+  let connections = 0;
+  wss.on('connection', (sock) => {
+    connections++;
+    sock.on('message', (d) => {
+      const t = d.toString();
+      if (t === 'ping') return;
+      frames.push(JSON.parse(t));
+      if (frames[frames.length - 1].type === 'register') {
+        sock.send(JSON.stringify({ requestId: 'req-health', command: 'health', params: {} }));
+        sock.send(JSON.stringify({ requestId: 'req-file', command: 'workspace.file-content', params: { path: 'secret.txt', workspacePath: ws } }));
+      }
+    });
+  });
+  const env = { ...process.env, PORT: String(await freePort()), GATEWAY_URL: `http://127.0.0.1:${wss.address().port}`,
+    TENANT_ID: 'tenant-test', AUTH_TOKEN: 'test-token', WORKSPACE_ROOT: ws, HOME: home,
+    LOCAL_AGENT_SIGNATURE_MODE: 'off', ...(flag ? { LOCAL_AGENT_WS_METADATA_ONLY: flag } : {}),
+    ...(disableTunnel ? { DISABLE_WS_TUNNEL: 'true' } : {}) };
+  delete env.LOCAL_AGENT_TOKEN;
+  const child = spawn(process.execPath, ['src/server.js'], { cwd: ROOT, env, stdio: 'ignore' });
+  try {
+    const deadline = Date.now() + (disableTunnel ? 4000 : 20000);
+    while (Date.now() < deadline) {
+      if (frames.some((f) => f.requestId === 'req-file') && frames.some((f) => f.requestId === 'req-health')) break;
+      await new Promise((r) => setTimeout(r, 100));
+    }
+  } finally {
+    child.kill('SIGKILL');
+    for (const c of wss.clients) c.terminate();
+    await new Promise((r) => wss.close(r));
+    fs.rmSync(ws, { recursive: true, force: true });
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+  return { frames, connections };
+}
+
+test('flag off (default): legacy channel is unchanged', async () => {
+  const { frames } = await run({});
+  const reg = frames.find((f) => f.type === 'register');
+  assert.ok(reg && 'workspacePath' in reg, 'legacy register still carries workspacePath');
+  const file = frames.find((f) => f.requestId === 'req-file');
+  assert.equal(file.content, SECRET, 'legacy content command still works with the flag off');
+});
+
+test('enforce: nothing but allowlisted metadata leaves the socket, content never does', async () => {
+  const { frames } = await run({ flag: 'enforce' });
+  assert.ok(frames.length >= 3, 'register + 2 replies expected');
+  assert.equal(JSON.stringify(frames).includes(SECRET), false);
+  assert.equal(JSON.stringify(frames).includes('secret.txt'), false);
+  const reg = frames.find((f) => f.type === 'register');
+  assert.equal(reg.workspacePath, undefined);
+  assert.match(reg.workspaceHash, /^[a-f0-9]{64}$/);
+  assert.deepEqual(frames.find((f) => f.requestId === 'req-file'),
+    { requestId: 'req-file', command: 'workspace.file-content', ok: false, errorCode: 'blocked_metadata_only' });
+  const health = frames.find((f) => f.requestId === 'req-health');
+  assert.equal(health.status, 'ok');
+  assert.equal('workspace' in health, false);
+});
+
+test('DISABLE_WS_TUNNEL=true: no socket is opened, whatever the flag', async () => {
+  for (const flag of [undefined, 'enforce']) {
+    const { connections } = await run({ flag, disableTunnel: true });
+    assert.equal(connections, 0, `flag=${flag}`);
+  }
+});