@decibelsystems/tools 2.2.0-beta.0 → 3.1.0

package/dist/httpServer.js

@@ -25,7 +25,13 @@
  *   { "status": "error", "error": "...", "code": "..." }
  */
 import { createServer } from 'http';
-import { timingSafeEqual, randomBytes } from 'crypto';
+import { randomBytes } from 'crypto';
+import { isLoopbackPeer, isAllowedOrigin, presentedBearer, respondToPnaPreflight, timingSafeTokenCompare, } from './pty/boundary.js';
+import { pairingOf } from './pty/pairing.js';
+import { isSessionWritePath, isSessionAttachPath, handleSessionWrite, handleSessionUpgrade, closeAllAttachSockets, sessionAuthConfig, handleChatWrite, handlePair, isPairPath, applyPairingAuth, } from './pty/routes.js';
+import { readChat } from './chat.js';
+import { listHostedSessions, SessionError } from './pty/sessions.js';
+import { fleet } from './pty/fleet.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { readFileSync, existsSync } from 'fs';
 import { fileURLToPath } from 'url';
@@ -33,12 +39,18 @@ import { dirname, join, resolve } from 'path';
 import { log } from './config.js';
 import { writeLocalAgentSession } from './agentPresence.js';
 import { drainCommands, setSessionToken, getSessionToken, dropSessionToken, ackOwnerOf, clearAckOwner, } from './agentInbox.js';
-import { settleCommandFromAck, ORG_ID } from './agentCommands.js';
+import { settleCommandFromAck } from './agentCommands.js';
+import { getOrgId } from './orgId.js';
 import { isSupabaseConfigured, getSupabaseServiceClient } from './lib/supabase.js';
 import { shouldQueueForAgent, parseToolCall } from './httpQueueDetection.js';
+import { getExtensionDiagnostics } from './kernel.js';
 import { getLicenseValidator } from './license.js';
 import { listProjects } from './projectRegistry.js';
-import { setDaemonPort } from './daemon.js';
+import { setDaemonPort, clearDaemonPort } from './daemon.js';
+import { RUNTIME_PROTOCOL_VERSION } from './runtime/protocol.js';
+import { daemonStateDir } from './runtime/daemonMeta.js';
+import { PACKAGE } from './version.js';
+import { wrapSuccess, wrapError, envelopeHttpStatus, } from './lib/envelope.js';
 import { listEpics, listRepoIssues, isProjectResolutionError, } from './tools/sentinel.js';
 import { voiceInboxAdd, } from './tools/voice.js';
 import { generateImage, getImageStatus, meshyGenerate, getMeshyStatus, meshyDownload, tripoGenerate, getTripoStatus, tripoDownload, klingGenerateVideo, klingGenerateTextVideo, klingGenerateAvatar, getKlingStatus, listTasks, } from './tools/studio/index.js';
@@ -82,6 +94,21 @@ class RateLimiter {
         entry.count++;
         return entry.count <= limit;
     }
+    /**
+     * A named bucket with its own limit, outside the ip:/agent: namespaces so no
+     * header can land a request in it.
+     */
+    checkBucket(bucket, limit) {
+        const key = `bucket:${bucket}`;
+        const now = Date.now();
+        const entry = this.windows.get(key);
+        if (!entry || now - entry.start > 60_000) {
+            this.windows.set(key, { count: 1, start: now });
+            return true;
+        }
+        entry.count++;
+        return entry.count <= limit;
+    }
     /** Set a per-agent RPM override */
     setAgentLimit(agentId, rpm) {
         this.agentLimits.set(agentId, rpm);
@@ -101,29 +128,31 @@ class RateLimiter {
     }
 }
 // ============================================================================
-// Security: Timing-Safe Token Comparison
+// Security: shared trust boundary (src/pty/boundary.ts)
 // ============================================================================
-function timingSafeTokenCompare(provided, expected) {
-    const a = Buffer.from(provided, 'utf-8');
-    const b = Buffer.from(expected, 'utf-8');
-    if (a.length !== b.length) {
-        // Still do a comparison to keep timing constant
-        timingSafeEqual(a, a);
+// The timing-safe compare and the loopback check live in one module so the REST
+// surface and the session/attach surface cannot drift apart.
+//
+// isLocalAgentPeer is the trust boundary for the /agents/* endpoints: ONLY a
+// process on this machine may register/poll/ack a local runtime (the 127.0.0.1
+// bind is the principal — confused-deputy rule).
+const isLocalAgentPeer = isLoopbackPeer;
+/** Request headers any allowed browser origin may send. */
+const GENERIC_ALLOWED_HEADERS = [
+    'Content-Type', 'Authorization', 'Mcp-Session-Id', 'Accept', 'X-Agent-Id', 'X-Run-Id',
+    'X-License-Key', 'X-Allowed-Facades', 'X-Scope', 'X-Request-Id', 'X-Parent-Call-Id',
+    'X-Engagement-Mode', 'X-User-Key', 'X-Org-Key',
+    'X-Pairing-Id', 'X-Pairing-Nonce', 'X-Pairing-Iat', 'X-Pairing-Sig',
+];
+/** The request carries the daemon auth_token or the sessions token as its bearer. */
+function holdsLocalBearer(req, daemonToken) {
+    const presented = presentedBearer(req);
+    if (!presented)
         return false;
-    }
-    return timingSafeEqual(a, b);
-}
-/**
- * The connection's trust boundary for the /agents/* endpoints: ONLY a process on
- * this machine may register/poll/ack a local runtime (the 127.0.0.1 bind is the
- * principal — confused-deputy rule). We check the real socket peer address (not a
- * spoofable header). An EMPTY remoteAddress is rejected (was previously allowed) —
- * a genuine TCP loopback connection always presents 127.0.0.1/::1, so empty only
- * arises from a destroyed/odd socket and must not be treated as local.
- */
-function isLocalAgentPeer(req) {
-    const peer = (req.socket.remoteAddress || '').replace('::ffff:', '');
-    return peer === '127.0.0.1' || peer === '::1';
+    if (daemonToken && timingSafeTokenCompare(presented, daemonToken))
+        return true;
+    const sessionsToken = sessionAuthConfig().token;
+    return !!sessionsToken && timingSafeTokenCompare(presented, sessionsToken);
 }
 /**
  * Mint-or-return the per-session capability token (proof-of-possession the SDK must
@@ -158,18 +187,7 @@ function isLocalhostOrigin(origin) {
 // ============================================================================
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-function getVersion() {
-    try {
-        // Try to read from package.json (works in both dev and prod)
-        const pkgPath = join(__dirname, '..', 'package.json');
-        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-        return { version: pkg.version || '0.0.0', name: pkg.name || '@decibelsystems/tools' };
-    }
-    catch {
-        return { version: '2.0.0', name: '@decibelsystems/tools' };
-    }
-}
-const PKG = getVersion();
+const PKG = PACKAGE;
 // ============================================================================
 // Landing Page HTML
 // ============================================================================
@@ -208,43 +226,6 @@ function formatUptime(ms) {
         return `${minutes}m ${seconds % 60}s`;
     return `${seconds}s`;
 }
-/**
- * Wrap a successful result in status envelope
- */
-function wrapSuccess(data) {
-    return { status: 'executed', ...data };
-}
-/**
- * Wrap an error in status envelope
- */
-/**
- * Sanitize error messages to prevent information disclosure.
- * Removes absolute file paths and replaces with generic placeholders.
- * Preserves URLs and relative paths.
- */
-function sanitizeErrorMessage(message) {
-    let sanitized = message;
-    // Step 1: Preserve paths containing .decibel (keep the .decibel part, strip prefix)
-    // /home/user/project/.decibel/foo -> .decibel/foo
-    sanitized = sanitized.replace(/(?:\/[^\s:'"]+)?\/\.decibel\//g, '.decibel/');
-    sanitized = sanitized.replace(/(?:[A-Z]:\\[^\s:'"]+)?\\\.decibel\\/gi, '.decibel\\');
-    // Step 2: Remove absolute Unix paths (must start with / and have at least one more /)
-    // But exclude URLs (http://, https://, file://)
-    // Match: /home/user/file.txt, /var/log/app.log
-    // Don't match: http://example.com, ./relative/path
-    sanitized = sanitized.replace(/(?<!:)\/(?:home|Users|var|tmp|opt|usr|etc|media|mnt)\/[^\s:'"]+/g, '[path]');
-    // Step 3: Remove Windows absolute paths (C:\, D:\, etc.)
-    sanitized = sanitized.replace(/[A-Z]:\\[^\s:'"]+/gi, '[path]');
-    // Step 4: Sanitize any remaining usernames in paths that weren't caught
-    sanitized = sanitized.replace(/\/home\/[^\/\s]+\//g, '/home/[user]/');
-    sanitized = sanitized.replace(/\/Users\/[^\/\s]+\//g, '/Users/[user]/');
-    sanitized = sanitized.replace(/C:\\Users\\[^\\]+\\/gi, 'C:\\Users\\[user]\\');
-    return sanitized;
-}
-function wrapError(error, code) {
-    const sanitized = sanitizeErrorMessage(error);
-    return { status: 'error', error: sanitized, ...(code && { code }) };
-}
 /**
  * Send JSON response with status envelope
  */
@@ -346,20 +327,30 @@ async function executeTool(tool, args, req, tierOverride) {
             requestId: req.headers['x-request-id'],
             tier: tierOverride,
             allowedFacades,
-        } : tierOverride ? { tier: tierOverride } : undefined;
+            transport: 'http',
+        } : tierOverride ? { tier: tierOverride, transport: 'http' } : { transport: 'http' };
         const toolResult = await kernel.dispatch(tool, args, context);
         const text = toolResult.content[0]?.text;
         if (toolResult.isError) {
             return wrapError(text || 'Tool execution failed', 'TOOL_ERROR');
         }
-        // Parse JSON result or wrap as message
+        // Parse the tool's payload, or carry it as prose when it isn't JSON.
+        //
+        // The prose branch is legitimate — some tools return markdown — but it used
+        // to be indistinguishable from a data response that failed to parse. A
+        // caller expecting `events` got an object with no `events` key, `ok: true`,
+        // and no indication that anything unusual happened. That is how a
+        // concatenated feedback prompt (fixed in tools/shared/response.ts) turned
+        // one call in fifteen into a silent empty result for every HTTP consumer.
+        // `payload_format` makes the two cases tellable apart.
         let result;
         if (text) {
             try {
                 result = JSON.parse(text);
             }
             catch {
-                result = { message: text };
+                log(`HTTP: tool ${tool} returned non-JSON text (${text.length} bytes) — carrying it as prose`);
+                result = { message: text, payload_format: 'text' };
             }
         }
         else {
@@ -406,6 +397,7 @@ async function queueForAgent(facade, action, args, agentId, projectId) {
     }
     return {
         status: 'queued',
+        ok: true,
         queue_id: data.id,
         message: 'Queued for local sync. Use agentic queue_status to check result.',
     };
@@ -424,7 +416,7 @@ function getAvailableTools() {
  * Get tools in OpenAI function calling format (facade-based)
  */
 function getOpenAITools() {
-    return kernel.getMcpToolDefinitions('full').map(def => ({
+    return kernel.getMcpToolDefinitions('full', { transport: 'http' }).map(def => ({
         type: 'function',
         function: {
             name: def.name,
@@ -563,14 +555,31 @@ export async function startHttpServer(server, kernelInstance, options) {
             // else: untrusted origin → no ACAO header (browser blocks the read).
         }
         res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
-        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, Mcp-Session-Id, Accept, X-Agent-Id, X-Run-Id, X-License-Key, X-Allowed-Facades, X-Scope, X-Request-Id, X-Parent-Call-Id, X-Engagement-Mode, X-User-Key, X-Org-Key');
+        res.setHeader('Access-Control-Allow-Headers', GENERIC_ALLOWED_HEADERS.join(', '));
         res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id');
+        // Hosted-session write routes answer their own preflight: they carry the
+        // Private Network Access header and a stricter origin allowlist than the
+        // generic localhost CORS above (src/pty/routes.ts).
+        // A preflight from an allowlisted HQ origin (the dev server, or deployed HQ
+        // for paired requests) gets the Private Network Access header and the
+        // pairing headers; without PNA an https page cannot reach 127.0.0.1 at all.
+        if (isDaemon && req.method === 'OPTIONS' && isAllowedOrigin(req.headers.origin, sessionAuthConfig().allowedOrigins)) {
+            respondToPnaPreflight(req, res, sessionAuthConfig().allowedOrigins, GENERIC_ALLOWED_HEADERS);
+            return;
+        }
         // (a) Handle preflight OPTIONS requests
         if (req.method === 'OPTIONS') {
             res.writeHead(204);
             res.end();
             return;
         }
+        // Signed requests from a paired browser (ADR-0012 in this repo). Verified
+        // here, once, before rate limiting and auth: a verified request is marked
+        // (pairingOf) and stands in for a bearer everywhere below. A request that
+        // CLAIMS a pairing and fails is refused outright rather than falling
+        // through as anonymous.
+        if (isDaemon && !applyPairingAuth(req, res, url))
+            return;
         // HOSTED FAIL-CLOSED, checked EARLY (before the rate limiter) so an
         // unauthenticated hosted caller can't consume/poison the rate-limit map or any
         // downstream state before being refused. Public infra routes stay open so
@@ -587,9 +596,20 @@ export async function startHttpServer(server, kernelInstance, options) {
             return;
         }
         // Rate limiting (check before auth to prevent brute force)
+        //
+        // Every local caller is 127.0.0.1, so by IP they all share one 100-rpm
+        // bucket: an HQ tab refreshing its roster used to spend it for the whole
+        // machine, and then attach-token and every hook call got RATE_LIMITED.
+        // A loopback caller that proves it holds the daemon bearer or the sessions
+        // bearer (HQ's dev proxy injects one server-side) gets its own, larger
+        // bucket. Anonymous loopback keeps the shared one.
         const clientIp = (req.socket.remoteAddress || '127.0.0.1').replace('::ffff:', '');
         const reqAgentId = req.headers['x-agent-id'];
-        if (!rateLimiter.check(clientIp, reqAgentId)) {
+        const trustedLocal = isDaemon && isLoopbackPeer(req) && (!!pairingOf(req) || holdsLocalBearer(req, authToken));
+        const withinLimit = trustedLocal
+            ? rateLimiter.checkBucket('trusted-local', Math.max(rateLimitRpm * 20, 2000))
+            : rateLimiter.check(clientIp, reqAgentId);
+        if (!withinLimit) {
             log(`HTTP: Rate limited ${reqAgentId || clientIp}`);
             sendJson(res, 429, wrapError('Too many requests (rate limit exceeded)', 'RATE_LIMITED'));
             return;
@@ -602,6 +622,25 @@ export async function startHttpServer(server, kernelInstance, options) {
         activeRequests.add(req);
         res.on('finish', () => activeRequests.delete(req));
         res.on('close', () => activeRequests.delete(req));
+        // Hosted-session writes (attach-token, control, spawn) are gated on the
+        // sessions bearer, not the daemon auth_token, so they are routed BEFORE the
+        // daemon's own auth gate. See src/pty/routes.ts for why. Daemon mode only:
+        // a hosted --http server has no business starting local terminals.
+        if (isDaemon && isSessionWritePath(path)) {
+            await handleSessionWrite(req, res, path);
+            return;
+        }
+        // Pairing: request, status, challenge, revoke. Pre-auth by nature; none of
+        // them approves anything (approval is the CLI, on this machine).
+        if (isDaemon && isPairPath(path)) {
+            await handlePair(req, res, path);
+            return;
+        }
+        // POST /chat puts text into other sessions: same gate as the session writes.
+        if (isDaemon && path === '/chat' && req.method === 'POST') {
+            await handleChatWrite(req, res);
+            return;
+        }
         // (c) Root health check - GET / returns 200
         if (path === '/' && req.method === 'GET') {
             res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -630,6 +669,10 @@ export async function startHttpServer(server, kernelInstance, options) {
                 status: 'ok',
                 version: PKG.version,
                 api_version: 'v1',
+                // Wire-contract version, negotiated by ensureRuntime(). Distinct from
+                // `version` — a long-lived daemon can outlive the clients connecting to
+                // it, and most releases do not change the contract. See runtime/protocol.ts.
+                protocol_version: RUNTIME_PROTOCOL_VERSION,
                 uptime_ms: uptimeMs,
                 uptime_human: formatUptime(uptimeMs),
                 pid: process.pid,
@@ -642,6 +685,17 @@ export async function startHttpServer(server, kernelInstance, options) {
                 pro: licenseTier !== 'core',
                 license_tier: licenseTier,
                 supabase_configured: isSupabaseConfigured(),
+                // Facades whose dependency is failing. `{}` is the healthy case — a
+                // non-empty object means calls to those facades are being refused fast
+                // rather than left to time out. See runtime/circuitBreaker.ts.
+                circuits: kernel.circuitSnapshot(),
+                // Private facades loaded from the allowlist, and every entry refused.
+                // Reported because the alternative is silence: an extension that failed
+                // to load looks exactly like one that was never configured, and this
+                // daemon has already shipped one bug of that shape — a broken voice
+                // inbox that read as "0 messages" for five hours. See
+                // runtime/extensions.ts.
+                extensions: getExtensionDiagnostics(),
             }));
             return;
         }
@@ -667,14 +721,14 @@ export async function startHttpServer(server, kernelInstance, options) {
                 sendJson(res, 401, wrapError('This endpoint requires authentication. Hosted (--http) mode must be started with DECIBEL_AUTH_TOKEN set.', 'AUTH_NOT_CONFIGURED'));
                 return;
             }
-            if (authToken) {
+            if (authToken && !pairingOf(req)) {
                 const authHeader = req.headers.authorization;
                 if (!authHeader || !timingSafeTokenCompare(authHeader, `Bearer ${authToken}`)) {
                     sendJson(res, 401, wrapError('Unauthorized', 'UNAUTHORIZED'));
                     return;
                 }
             }
-            const dispatchLogPath = join(process.env.HOME || '~', '.decibel', 'logs', 'dispatch.jsonl');
+            const dispatchLogPath = join(daemonStateDir(), 'logs', 'dispatch.jsonl');
             try {
                 const content = readFileSync(dispatchLogPath, 'utf-8');
                 const lines = content.trim().split('\n').filter(Boolean);
@@ -772,8 +826,9 @@ export async function startHttpServer(server, kernelInstance, options) {
             sendJson(res, 401, wrapError('This endpoint requires authentication. Hosted (--http) mode must be started with DECIBEL_AUTH_TOKEN set.', 'AUTH_NOT_CONFIGURED'));
             return;
         }
-        // Auth check (timing-safe comparison to prevent timing attacks)
-        if (authToken) {
+        // Auth check (timing-safe comparison to prevent timing attacks). A request
+        // verified under an approved pairing already proved more than a bearer.
+        if (authToken && !pairingOf(req)) {
             const authHeader = req.headers.authorization;
             if (!authHeader || !timingSafeTokenCompare(authHeader, `Bearer ${authToken}`)) {
                 log('HTTP: Unauthorized request');
@@ -784,7 +839,62 @@ export async function startHttpServer(server, kernelInstance, options) {
         // ========================================================================
         // Simple REST Endpoints (for external AI agents)
         // ========================================================================
+        // GET /sessions[?project_id=<id>] — hosted-session roster for HQ (ADR-0012 /
+        // decibel-hq EPIC-0015). Without project_id, every session on the machine.
+        // Read-only, so it sits behind the normal daemon gate; the write routes are
+        // handled above with their own bearer.
+        if (isDaemon && path === '/sessions' && req.method === 'GET') {
+            const projectId = url.searchParams.get('project_id') || undefined;
+            try {
+                const sessions = await listHostedSessions(projectId);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ sessions }));
+            }
+            catch (err) {
+                if (err instanceof SessionError) {
+                    sendJson(res, err.status, wrapError(err.message, err.code));
+                }
+                else {
+                    sendJson(res, 500, wrapError(err instanceof Error ? err.message : String(err), 'INTERNAL'));
+                }
+            }
+            return;
+        }
+        // GET /sessions/last-fleet — the sessions to offer for restore (decibel-hq
+        // ADR-0018). Read-only, behind the normal daemon gate like GET /sessions.
+        if (isDaemon && path === '/sessions/last-fleet' && req.method === 'GET') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(fleet().lastFleet()));
+            return;
+        }
+        // GET /chat?since=<id>&limit= — the HQ chat log (decibel-hq EPIC-0016).
+        // Read-only, behind the normal daemon gate. human_peer_id changes whenever
+        // the peer re-registers, so clients read it from here every time.
+        if (isDaemon && path === '/chat' && req.method === 'GET') {
+            const since = Number(url.searchParams.get('since') ?? 0) || 0;
+            const limit = Number(url.searchParams.get('limit') ?? 200) || 200;
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(readChat(since, limit)));
+            return;
+        }
         // GET /tools - List available tools
+        // MCP tool definitions, verbatim — the shape a `tools/list` response needs.
+        //
+        // This is what lets a stdio client stop building its own kernel. /tools
+        // above is a human/OpenAI-shaped summary; this one is the exact array the
+        // MCP handler returns, so a thin adapter can serve tools/list by forwarding
+        // it rather than loading 195 tool modules to produce the same bytes.
+        if (path === '/mcp/tools' && req.method === 'GET') {
+            const tierParam = url.searchParams.get('tier');
+            const tier = (tierParam === 'compact' || tierParam === 'micro' ? tierParam : 'full');
+            sendJson(res, 200, wrapSuccess({
+                version: PKG.version,
+                protocol_version: RUNTIME_PROTOCOL_VERSION,
+                tier,
+                tools: kernel.getMcpToolDefinitions(tier, { transport: 'http' }),
+            }));
+            return;
+        }
         if (path === '/tools' && req.method === 'GET') {
             sendJson(res, 200, wrapSuccess({
                 version: PKG.version,
@@ -944,7 +1054,13 @@ export async function startHttpServer(server, kernelInstance, options) {
                 sendJson(res, 403, wrapError('Invalid or missing session token', 'BAD_SESSION_TOKEN'));
                 return;
             }
-            const commands = drainCommands(sessionKey, ORG_ID);
+            // No org means no dispatcher ran, so nothing can be queued for this session.
+            let org = null;
+            try {
+                org = getOrgId();
+            }
+            catch { /* malformed: the startup gate reports it */ }
+            const commands = org ? drainCommands(sessionKey, org) : [];
             sendJson(res, 200, wrapSuccess({ session_key: sessionKey, commands, count: commands.length }));
             return;
         }
@@ -1151,7 +1267,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 const tier = await resolveTier(req, configLicenseKey);
                 log(`HTTP: /call tool=${tool} tier=${tier}`);
                 const result = await executeTool(tool, args, req, tier);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1191,10 +1307,30 @@ export async function startHttpServer(server, kernelInstance, options) {
                     requestId: req.headers['x-request-id'] || bodyContext.requestId,
                     allowedFacades: bodyContext.allowedFacades,
                     tier,
+                    // Set here, never read from the request: a caller that could name its
+                    // own transport could name 'stdio' and walk straight through the
+                    // local-only gate.
+                    transport: 'http',
                 };
                 log(`HTTP: /batch — ${calls.length} calls (agent=${context.agentId || 'anonymous'}, tier=${tier})`);
                 const results = await kernel.batch(calls, context);
-                sendJson(res, 200, { status: 'executed', results });
+                // `ok` reflects STRUCTURAL validity: did every call name something this
+                // runtime actually has. A call that ran and returned isError leaves ok
+                // true — partial failure is a normal batch outcome and callers depend on
+                // that. A call naming a facade that is not registered does not.
+                //
+                // The status stays 200 because the body still carries real results for
+                // the other calls in the batch, and throwing those away behind a 4xx
+                // would trade one silent failure for another.
+                const unknown = results.filter(r => r.code === 'UNKNOWN_FACADE');
+                if (unknown.length > 0) {
+                    log(`HTTP: /batch — ${unknown.length} unknown facade(s): ${unknown.map(r => r.facade).join(', ')}`);
+                }
+                sendJson(res, 200, {
+                    status: unknown.length > 0 ? 'error' : 'executed',
+                    ok: unknown.length === 0,
+                    results,
+                });
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1223,7 +1359,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 const body = await parseBody(req);
                 log(`HTTP: /api/tools/${toolName}`);
                 const result = await executeTool(toolName, body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1240,7 +1376,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 const body = await parseBody(req);
                 log('HTTP: /dojo/wish');
                 const result = await executeTool('dojo_add_wish', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1254,7 +1390,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 const body = await parseBody(req);
                 log('HTTP: /dojo/propose');
                 const result = await executeTool('dojo_create_proposal', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1268,7 +1404,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 const body = await parseBody(req);
                 log('HTTP: /dojo/scaffold');
                 const result = await executeTool('dojo_scaffold_experiment', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1282,7 +1418,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 const body = await parseBody(req);
                 log('HTTP: /dojo/run');
                 const result = await executeTool('dojo_run_experiment', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1296,7 +1432,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 const body = await parseBody(req);
                 log('HTTP: /dojo/results');
                 const result = await executeTool('dojo_read_results', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1317,7 +1453,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 }
                 log('HTTP: /dojo/list');
                 const result = await executeTool('dojo_list', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1337,7 +1473,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 }
                 log('HTTP: /dojo/wishes');
                 const result = await executeTool('dojo_list_wishes', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1351,7 +1487,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 const body = await parseBody(req);
                 log('HTTP: /dojo/can-graduate');
                 const result = await executeTool('dojo_can_graduate', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1365,7 +1501,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 const body = await parseBody(req);
                 log('HTTP: /dojo/artifact');
                 const result = await executeTool('dojo_read_artifact', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1379,7 +1515,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 const body = await parseBody(req);
                 log('HTTP: /dojo/bench');
                 const result = await executeTool('dojo_bench', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1396,7 +1532,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 const body = await parseBody(req);
                 log('HTTP: /bench/run');
                 const result = await executeTool('decibel_bench', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1410,7 +1546,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 const body = await parseBody(req);
                 log('HTTP: /bench/compare');
                 const result = await executeTool('decibel_bench_compare', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1427,7 +1563,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 const body = await parseBody(req);
                 log('HTTP: /context/refresh');
                 const result = await executeTool('decibel_context_refresh', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1441,7 +1577,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 const body = await parseBody(req);
                 log('HTTP: /context/pin');
                 const result = await executeTool('decibel_context_pin', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1455,7 +1591,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 const body = await parseBody(req);
                 log('HTTP: /context/unpin');
                 const result = await executeTool('decibel_context_unpin', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1475,7 +1611,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 }
                 log('HTTP: /context/list');
                 const result = await executeTool('decibel_context_list', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1489,7 +1625,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 const body = await parseBody(req);
                 log('HTTP: /event/append');
                 const result = await executeTool('decibel_event_append', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1517,7 +1653,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 }
                 log('HTTP: /event/search');
                 const result = await executeTool('decibel_event_search', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1531,7 +1667,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 const body = await parseBody(req);
                 log('HTTP: /artifact/list');
                 const result = await executeTool('decibel_artifact_list', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1545,7 +1681,7 @@ export async function startHttpServer(server, kernelInstance, options) {
                 const body = await parseBody(req);
                 log('HTTP: /artifact/read');
                 const result = await executeTool('decibel_artifact_read', body);
-                sendJson(res, result.status === 'error' ? 400 : 200, result);
+                sendJson(res, envelopeHttpStatus(result), result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1769,6 +1905,16 @@ export async function startHttpServer(server, kernelInstance, options) {
         // ========================================================================
         // Studio API Endpoints (frontend_v0.2 compatible)
         // ========================================================================
+        // Tier guard: these REST shortcuts call studio (pro-tier) tools directly,
+        // bypassing kernel dispatch where tier gating normally lives. Enforce it
+        // here once for all /api/generate-* routes. (crucible re-run 2026-06-07)
+        if (path.startsWith('/api/generate-') && req.method === 'POST') {
+            const tier = await resolveTier(req, configLicenseKey);
+            if (tier === 'core') {
+                sendJson(res, 403, wrapError('Studio generation requires a pro license', 'TIER_REQUIRED'));
+                return;
+            }
+        }
         // POST /api/generate-flux-kontext-image - Start image generation
         if (path === '/api/generate-flux-kontext-image' && req.method === 'POST') {
             try {
@@ -2122,17 +2268,46 @@ export async function startHttpServer(server, kernelInstance, options) {
         res.writeHead(404, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: 'Not found' }));
     });
+    // WebSocket upgrades. The only upgrade this server accepts is a hosted-session
+    // attach (daemon mode); everything else is refused rather than left hanging,
+    // since Node leaves an unhandled upgrade socket open until it times out.
+    httpServer.on('upgrade', (req, socket, head) => {
+        const upgradeUrl = new URL(req.url || '/', 'http://127.0.0.1');
+        if (isDaemon && isSessionAttachPath(upgradeUrl.pathname)) {
+            handleSessionUpgrade(req, socket, head, upgradeUrl).catch((err) => {
+                log(`HTTP: attach upgrade failed: ${err instanceof Error ? err.message : String(err)}`);
+                try {
+                    socket.destroy();
+                }
+                catch { /* ignore */ }
+            });
+            return;
+        }
+        socket.write('HTTP/1.1 404 Not Found\r\nContent-Length: 0\r\nConnection: close\r\n\r\n');
+        socket.destroy();
+    });
     // Configure HTTP server timeouts to prevent premature connection drops
     httpServer.keepAliveTimeout = timeoutMs;
     httpServer.headersTimeout = timeoutMs + 1000; // Slightly longer than keepAliveTimeout
     httpServer.listen(port, host, () => {
         log(`HTTP Server listening on http://${host}:${port}`);
-        // Advertise port + pid in daemon.meta so clients can discover the daemon.
-        try {
-            setDaemonPort(port);
+        // Advertise port + pid in daemon.meta so clients can discover the daemon —
+        // but ONLY as the daemon. daemon.meta is machine-global: the session-init
+        // hook, the close hook, the HQ client and ensureRuntime all follow it. A
+        // plain `--http` run is a process someone started for a reason of their own
+        // (a test, a second checkout, CI, the hosted deployment), and when it
+        // advertised, every hook on the machine followed it to a port that died
+        // with it (ISS-0179).
+        if (isDaemon) {
+            try {
+                setDaemonPort(port);
+            }
+            catch (err) {
+                log(`Daemon: failed to write port to meta: ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
-        catch (err) {
-            log(`Daemon: failed to write port to meta: ${err instanceof Error ? err.message : String(err)}`);
+        else {
+            log(`HTTP Server: not advertising in daemon.meta (not --daemon); clients keep their existing discovery`);
         }
         console.log(`
 ╔══════════════════════════════════════════════════════════════╗
@@ -2183,6 +2358,8 @@ ${authToken ? '║  Auth:     Bearer token required
                     log(`HTTP: ${activeRequests.size} request(s) still active after 10s drain timeout`);
                 }
             }
+            // Close attach sockets (their tmux sessions live on)
+            closeAllAttachSockets();
             // Close SSE connections
             for (const conn of activeSseConnections) {
                 try {
@@ -2199,40 +2376,17 @@ ${authToken ? '║  Auth:     Bearer token required
                 // If already closed, resolve immediately
                 setTimeout(resolve, 100);
             });
+            // Withdraw discovery if we owned it, so a clean shutdown does not leave
+            // every client on the machine dialling a port nothing is serving
+            // (ISS-0179). clearDaemonPort only clears an entry that is ours.
+            if (isDaemon)
+                clearDaemonPort();
             log('HTTP server stopped');
         },
     };
 }
-/**
- * Parse command line arguments for HTTP mode
- */
-export function parseHttpArgs(args) {
-    const httpMode = args.includes('--http');
-    const portIndex = args.indexOf('--port');
-    // --port flag wins; else honor PORT env (Render sets it); else leave undefined
-    // so daemonConfig's default (4888) applies downstream instead of being
-    // short-circuited by a baked-in default here. See server.ts port/host resolution.
-    const port = portIndex !== -1
-        ? parseInt(args[portIndex + 1], 10)
-        : process.env.PORT
-            ? parseInt(process.env.PORT, 10)
-            : undefined;
-    // SECURITY: Prefer env var for auth token (CLI args visible in ps/history)
-    // Fall back to --auth-token for backwards compatibility
-    const authIndex = args.indexOf('--auth-token');
-    const authToken = process.env.DECIBEL_AUTH_TOKEN ||
-        (authIndex !== -1 ? args[authIndex + 1] : undefined);
-    const hostIndex = args.indexOf('--host');
-    // --host flag wins; else leave undefined so daemonConfig host (127.0.0.1, daemon
-    // mode) or the transport default applies instead of being short-circuited here.
-    const host = hostIndex !== -1 ? args[hostIndex + 1] : undefined;
-    // SSE/Connection tuning arguments
-    const keepaliveIndex = args.indexOf('--sse-keepalive');
-    const sseKeepaliveMs = keepaliveIndex !== -1 ? parseInt(args[keepaliveIndex + 1], 10) : undefined;
-    const timeoutIndex = args.indexOf('--timeout');
-    const timeoutMs = timeoutIndex !== -1 ? parseInt(args[timeoutIndex + 1], 10) : undefined;
-    const retryIndex = args.indexOf('--sse-retry');
-    const retryIntervalMs = retryIndex !== -1 ? parseInt(args[retryIndex + 1], 10) : undefined;
-    return { httpMode, port, authToken, host, sseKeepaliveMs, timeoutMs, retryIntervalMs };
-}
+// parseHttpArgs moved to ./httpArgs.js so that argv parsing carries no
+// dependencies. Re-exported here because it has always been part of this
+// module's surface.
+export { parseHttpArgs } from './httpArgs.js';
 //# sourceMappingURL=httpServer.js.map