fix(vscode): residual sweep — stale docs, misleading comments, test gap

- Correct handleProtocols comment: ws library does NOT reject connections
  when false is returned; real auth is in the connection handler
- Update serverHelpers.ts comment: token now via subprotocol, not query
- Update HELP.md: reflect subprotocol auth and TTL eviction
- Add null byte rejection test for isValidPythonPath
- Add CSP security comments to all 4 legacy webview panels

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: MythologIQ

packages/agent-os-vscode/HELP.md

@@ -124,8 +124,8 @@ violations today. Sortable and filterable.
 |---|---|---|
 | `'unsafe-inline'` for `style-src` in CSP | Required for VS Code theme CSS variable injection (`var(--vscode-*)`). Scripts remain nonce-gated. | Low -- style-only; no script injection vector. |
 | `retainContextWhenHidden: true` on Topology Detail | Preserves force-simulation state across tab switches (~120 animation frames). | Low -- adds ~2 MB memory when backgrounded. |
-| Session token in WebSocket URL query string | WebSocket upgrade requests cannot carry custom headers (RFC 6455). Token is 128-bit `crypto.randomBytes`. | Low -- server binds to 127.0.0.1; token never leaves loopback. |
-| Rate limiter Map without TTL eviction | Server is loopback-only, so the map holds at most one entry (127.0.0.1). | Negligible -- no memory growth risk. |
+| Session token via `Sec-WebSocket-Protocol` subprotocol | Token sent as subprotocol (not URL query string) to avoid proxy/debug logging. 128-bit `crypto.randomBytes`. | Low -- server binds to 127.0.0.1; token never leaves loopback. |
+| Rate limiter Map with TTL eviction | Stale entries evicted on each request. Server is loopback-only, so the map holds at most one entry (127.0.0.1). | Negligible -- no memory growth risk. |
 | `Math.random()` for burn-rate sparkline jitter | Synthetic demo data only, not used for any security or cryptographic purpose. | None -- replaced by real SRE data when backend connects. |
 | `axios` not used; `http` module for server | The governance server uses Node built-in `http`. No external HTTP client dependency. | N/A |
 

packages/agent-os-vscode/src/server/GovernanceServer.ts

@@ -197,13 +197,15 @@ export class GovernanceServer {
             this._wsServer = new WebSocketModule.WebSocketServer({
                 server: this._httpServer,
                 path: '/',
-                // Validate session token via subprotocol negotiation.
-                // Client sends ['governance-v1', token]; we validate and accept 'governance-v1'.
+                // Select 'governance-v1' subprotocol when token is present.
+                // NOTE: handleProtocols does NOT reject connections — ws completes
+                // the upgrade even when false is returned. Real auth is enforced
+                // in the connection handler via validateWebSocketToken().
                 handleProtocols: (protocols: Set<string>) => {
                     if (protocols.has(this._sessionToken)) {
                         return 'governance-v1';
                     }
-                    return false; // reject connection
+                    return false;
                 },
             }) as WebSocketServerLike;
 

packages/agent-os-vscode/src/server/serverHelpers.ts

@@ -70,8 +70,8 @@ export function generateClientId(): string {
  *
  * @returns 32-character hex token
  */
-// SECURITY: 128 bits of crypto.randomBytes for session auth. Transmitted in WS URL
-// query param (WebSocket upgrade has no custom header support per RFC 6455).
+// SECURITY: 128 bits of crypto.randomBytes for session auth. Transmitted via
+// Sec-WebSocket-Protocol subprotocol header (not URL query string, to avoid logging).
 export function generateSessionToken(): string {
     return randomBytes(16).toString('hex');
 }

packages/agent-os-vscode/src/test/services/sreServer.test.ts

@@ -17,6 +17,7 @@ suite('isValidPythonPath', () => {
     test('rejects backticks', () => { assert.strictEqual(isValidPythonPath('`whoami`'), false); });
     test('rejects pipe', () => { assert.strictEqual(isValidPythonPath('python | cat'), false); });
     test('rejects dollar sign', () => { assert.strictEqual(isValidPythonPath('$HOME/python'), false); });
+    test('rejects null bytes', () => { assert.strictEqual(isValidPythonPath('python\0'), false); });
     test('accepts python3', () => { assert.strictEqual(isValidPythonPath('python3'), true); });
     test('accepts unix path', () => { assert.strictEqual(isValidPythonPath('/usr/bin/python'), true); });
     test('accepts windows path', () => { assert.strictEqual(isValidPythonPath('C:\\Python311\\python.exe'), true); });

packages/agent-os-vscode/src/webviews/metricsDashboard/MetricsDashboardPanel.ts

@@ -242,6 +242,7 @@ export class MetricsDashboardPanel {
 <html lang="en">
 <head>
     <meta charset="UTF-8">
+    <!-- SECURITY: 'unsafe-inline' for styles required by VS Code theme CSS variable injection. Scripts nonce-gated. -->
     <meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src ${cspSource} 'unsafe-inline'; script-src 'nonce-${nonce}'; img-src ${cspSource} https:; font-src ${cspSource};">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>Metrics Dashboard</title>

packages/agent-os-vscode/src/webviews/onboarding/OnboardingPanel.ts

@@ -230,6 +230,7 @@ export class OnboardingPanel {
 <html lang="en">
 <head>
     <meta charset="UTF-8">
+    <!-- SECURITY: 'unsafe-inline' for styles required by VS Code theme CSS variable injection. Scripts nonce-gated. -->
     <meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src ${cspSource} 'unsafe-inline'; script-src 'nonce-${nonce}'; img-src ${cspSource} https:; font-src ${cspSource};">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>Welcome to Agent OS</title>

packages/agent-os-vscode/src/webviews/policyEditor/PolicyEditorPanel.ts

@@ -624,6 +624,7 @@ policies:
 <html lang="en">
 <head>
     <meta charset="UTF-8">
+    <!-- SECURITY: 'unsafe-inline' for styles required by VS Code theme CSS variable injection. Scripts nonce-gated. -->
     <meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src ${cspSource} 'unsafe-inline'; script-src 'nonce-${nonce}'; img-src ${cspSource} https:; font-src ${cspSource};">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>Policy Editor</title>

packages/agent-os-vscode/src/webviews/workflowDesigner/WorkflowDesignerPanel.ts

@@ -626,6 +626,7 @@ ${functionDefs}
 <html lang="en">
 <head>
     <meta charset="UTF-8">
+    <!-- SECURITY: 'unsafe-inline' for styles required by VS Code theme CSS variable injection. Scripts nonce-gated. -->
     <meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src ${cspSource} 'unsafe-inline'; script-src 'nonce-${nonce}'; img-src ${cspSource} https:; font-src ${cspSource};">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>Workflow Designer</title>