@crouton-kit/crouter 0.3.33 → 0.3.35

package/dist/daemon/predicate-eval.js

@@ -0,0 +1,248 @@
+// src/daemon/predicate-eval.ts — the daemon-owned `--when` predicate
+// evaluator: subprocess spawn/capture/timeout/capacity/lease mechanics ONLY.
+// No enactment logic lives here (no appendInbox/reviveNode/spawnChild) — every
+// settled outcome is handed to the caller's `onDone`/`onTimeout` callback, and
+// crtrd.ts is the SINGLE place that turns a settled trigger into an inbox
+// message / revive / spawn (reusing the exact same enactment code the clock-
+// trigger pass uses). This keeps enactment in ONE place regardless of whether
+// the trigger fired off a clock or a predicate.
+//
+// Fire-and-forget contract: evaluateDuePredicates NEVER awaits a subprocess —
+// it kicks off child processes and returns immediately; each settles later via
+// its own `close`/timeout handler calling `onDone`. The daemon tick must never
+// block on a slow/hung predicate (spec §Predicate triggers: "cannot block the
+// daemon tick").
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { duePredicateTriggers, duePredicateTimeouts, runningPredicateTriggers, acquirePredicateLease, recordPredicateEvalResult, resetPredicateLease, consumeTrigger, getNode, } from '../core/canvas/index.js';
+import { isPidAlive, killProcessGroup } from '../core/canvas/pid.js';
+import { nextSlotAfter } from '../core/wake.js';
+export const STDOUT_CAP_BYTES = 16 * 1024;
+export const STDERR_TAIL_BYTES = 4 * 1024;
+/** Read fresh each pass (not cached at module load) so a test/operator can
+ *  tune it via env without a daemon restart mid-run. */
+export function predicateCapacity() {
+    const num = (name, fallback) => {
+        const raw = process.env[name];
+        const n = raw !== undefined ? Number(raw) : NaN;
+        return Number.isFinite(n) && n > 0 ? n : fallback;
+    };
+    return {
+        maxCanvas: num('CRTR_PREDICATE_MAX_CANVAS', 8),
+        maxPerOwner: num('CRTR_PREDICATE_MAX_OWNER', 2),
+        evalTimeoutMs: num('CRTR_PREDICATE_EVAL_TIMEOUT_MS', 10_000),
+    };
+}
+/** One id per daemon PROCESS instance — distinguishes THIS process's own
+ *  in-flight leases from a stale 'running' row a prior (crashed/restarted)
+ *  daemon left behind (spec §Lease / in-flight contract, daemon-restart
+ *  recovery). Generated once per process; tests that want deterministic
+ *  recovery behavior can ignore it (recovery only special-cases OWN leases). */
+export const daemonInstanceId = randomUUID();
+function nextEvalAfter(t, nowMs) {
+    return t.eval_every != null ? nextSlotAfter(t.eval_every, new Date(nowMs)) : new Date(nowMs).toISOString();
+}
+/** Recover stale in-flight rows left by a PRIOR daemon instance (crash/
+ *  restart): a still-alive process group past its own eval timeout is killed +
+ *  recorded as a timeout; a dead pid resets straight to idle with no
+ *  diagnostics (spec: "if not alive, the row is reset to idle and eligible for
+ *  the next evaluation slot"). Rows this SAME instance owns are left alone —
+ *  they are genuinely in flight, not stale. */
+export function recoverStalePredicateLeases(now, config) {
+    for (const t of runningPredicateTriggers()) {
+        if (t.eval_lease_owner === daemonInstanceId)
+            continue;
+        const pid = t.eval_pid;
+        if (pid == null || !isPidAlive(pid)) {
+            resetPredicateLease(t.trigger_id);
+            continue;
+        }
+        const startedAtMs = t.eval_started_at != null ? new Date(t.eval_started_at).getTime() : now;
+        if (now - startedAtMs < config.evalTimeoutMs)
+            continue; // still within its own window — leave it
+        killProcessGroup(pid);
+        recordPredicateEvalResult(t.trigger_id, {
+            completedAtIso: new Date(now).toISOString(),
+            nextEvalAtIso: nextEvalAfter(t, now),
+            exitCode: null,
+            stderrTail: `evaluation timed out after ${config.evalTimeoutMs}ms (recovered stale lease from a prior daemon instance)`,
+        });
+    }
+}
+/** Wall-clock `timeout_at` reap — independent of eval_state/next_eval_at.
+ *  Kills any in-flight process group for a timed-out row, consumes it, and
+ *  invokes `onTimeout` once per row so the caller can send the owner urgent
+ *  notice (spec: "consume and notify owner"). Call BEFORE
+ *  evaluateDuePredicates each tick so a timed-out row can never also be
+ *  freshly evaluated in the same tick (consumeTrigger removes it from the due
+ *  query). */
+export function reapTimedOutPredicates(now, onTimeout) {
+    for (const t of duePredicateTimeouts(new Date(now).toISOString())) {
+        if (t.eval_state === 'running' && t.eval_pid != null)
+            killProcessGroup(t.eval_pid);
+        consumeTrigger(t.trigger_id);
+        onTimeout(t);
+    }
+}
+function runOneEvaluation(t, config, onDone) {
+    let cwd;
+    if (t.action === 'msg') {
+        const target = t.node_id != null ? getNode(t.node_id) : null;
+        if (target === null) {
+            // Shouldn't reach here — the caller checks target existence before
+            // calling this — but never spawn against an unresolved cwd.
+            return;
+        }
+        cwd = target.cwd;
+    }
+    else {
+        cwd = t.payload.cwd;
+    }
+    const env = {
+        ...process.env,
+        CRTR_TRIGGER_ID: t.trigger_id,
+        CRTR_TRIGGER_OWNER_ID: t.owner_id,
+    };
+    if (t.node_id != null)
+        env['CRTR_TRIGGER_TARGET_ID'] = t.node_id;
+    const startedAtIso = new Date().toISOString();
+    let child;
+    try {
+        child = spawn('bash', ['-c', t.when_script ?? 'exit 1'], {
+            cwd,
+            env,
+            detached: true, // own process group — killProcessGroup(-pid) reaps the whole tree
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        recordPredicateEvalResult(t.trigger_id, {
+            completedAtIso: new Date().toISOString(),
+            nextEvalAtIso: nextEvalAfter(t, Date.now()),
+            exitCode: null,
+            stderrTail: `evaluation failed to spawn: ${err.message}`.slice(-STDERR_TAIL_BYTES),
+        });
+        return;
+    }
+    if (child.pid == null || !acquirePredicateLease(t.trigger_id, daemonInstanceId, child.pid, startedAtIso)) {
+        // Lost a race (canceled / grabbed between selection and spawn, or the
+        // process never got a pid) — abandon; never leave an unaccounted child.
+        if (child.pid != null)
+            killProcessGroup(child.pid);
+        return;
+    }
+    let stdout = '';
+    let stdoutBytes = 0;
+    let overflowed = false;
+    let stderrTail = '';
+    let settled = false;
+    const timer = setTimeout(() => {
+        if (settled)
+            return;
+        settled = true;
+        if (child.pid != null)
+            killProcessGroup(child.pid);
+        recordPredicateEvalResult(t.trigger_id, {
+            completedAtIso: new Date().toISOString(),
+            nextEvalAtIso: nextEvalAfter(t, Date.now()),
+            exitCode: null,
+            stderrTail: `evaluation timed out after ${config.evalTimeoutMs}ms`,
+        });
+    }, config.evalTimeoutMs);
+    timer.unref?.();
+    child.stdout?.on('data', (chunk) => {
+        stdoutBytes += chunk.length;
+        if (stdout.length < STDOUT_CAP_BYTES)
+            stdout += chunk.toString('utf8');
+        if (stdoutBytes > STDOUT_CAP_BYTES)
+            overflowed = true;
+    });
+    child.stderr?.on('data', (chunk) => {
+        stderrTail = (stderrTail + chunk.toString('utf8')).slice(-STDERR_TAIL_BYTES);
+    });
+    const finish = (code) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        if (code === 0) {
+            // stdout only matters (and only needs a size cap) when it is ABOUT to
+            // become the message body: msg/inbox_message with no inline body
+            // supplied at arm time. A non-zero exit always reschedules below
+            // regardless of overflow — a verbose "not yet" predicate must stay armed
+            // (spec criterion 7) — and an exit-0 node_birth or a msg with a supplied
+            // body never reads stdout at all, so an overflow there is harmless noise,
+            // not a delivery failure.
+            const stdoutIsBody = t.action === 'msg' &&
+                t.action_mode === 'inbox_message' &&
+                t.payload.body === undefined;
+            if (overflowed && stdoutIsBody) {
+                // Guard against the narrow cross-path race: a wall-clock reaper
+                // (reapTimedOutPredicates) may have already killed + consumed this
+                // exact trigger between the kill signal and this close event firing
+                // (the `settled` guard above is local to this evaluation and doesn't
+                // see a racing reaper). consumeTrigger reports whether IT actually
+                // removed a live row; if the row is already gone, no-op instead of
+                // delivering a second, now-orphaned outcome.
+                if (!consumeTrigger(t.trigger_id))
+                    return;
+                onDone({ kind: 'stdout_overflow', trigger: t });
+                return;
+            }
+            if (!consumeTrigger(t.trigger_id))
+                return; // settle-before-enact; no-op if a racing reaper already consumed it
+            onDone({ kind: 'fired', trigger: t, stdout: stdout.slice(0, STDOUT_CAP_BYTES).trim() });
+            return;
+        }
+        recordPredicateEvalResult(t.trigger_id, {
+            completedAtIso: new Date().toISOString(),
+            nextEvalAtIso: nextEvalAfter(t, Date.now()),
+            exitCode: code,
+            stderrTail: stderrTail === '' ? null : stderrTail,
+        });
+    };
+    child.on('close', (code) => finish(code));
+    child.on('error', (err) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        recordPredicateEvalResult(t.trigger_id, {
+            completedAtIso: new Date().toISOString(),
+            nextEvalAtIso: nextEvalAfter(t, Date.now()),
+            exitCode: null,
+            stderrTail: `evaluation process error: ${err.message}`.slice(-STDERR_TAIL_BYTES),
+        });
+    });
+}
+/** Pass 3c: select due idle predicates (deterministic order from the DAO),
+ *  enforce capacity in-memory (seeded from the current running-row snapshot),
+ *  and kick off evaluations — NEVER awaited. `onDone` fires per trigger,
+ *  whenever it settles (possibly after this call returns). Rows over capacity,
+ *  or whose owner is at its per-owner cap, are left untouched (idle,
+ *  next_eval_at unchanged) and are retried next tick. A `msg` trigger whose
+ *  target no longer exists is reaped here (consumed + `target_gone`) instead
+ *  of being spawned against a dangling id. */
+export function evaluateDuePredicates(now, onDone) {
+    const config = predicateCapacity();
+    const running = runningPredicateTriggers();
+    let globalCount = running.length;
+    const perOwner = new Map();
+    for (const r of running)
+        perOwner.set(r.owner_id, (perOwner.get(r.owner_id) ?? 0) + 1);
+    for (const t of duePredicateTriggers(new Date(now).toISOString())) {
+        if (t.action === 'msg' && t.node_id != null && getNode(t.node_id) === null) {
+            consumeTrigger(t.trigger_id);
+            onDone({ kind: 'target_gone', trigger: t });
+            continue;
+        }
+        if (globalCount >= config.maxCanvas)
+            break; // no capacity left for anyone
+        const ownerCount = perOwner.get(t.owner_id) ?? 0;
+        if (ownerCount >= config.maxPerOwner)
+            continue; // this owner is at cap; try the next row
+        globalCount++;
+        perOwner.set(t.owner_id, ownerCount + 1);
+        runOneEvaluation(t, config, onDone);
+    }
+}

package/dist/hearth/control-plane/__tests__/node-message.test.js

@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+// Bug-regression test (CLAUDE.md "Testing policy" #2) — locks in the P5-review
+// (mr1ganv3-e3401250) CRITICAL fix: `wakeAndExecNodeMessage` invoked a
+// nonexistent `crtr node spine msg <target> --tier <tier>` command (no `node
+// spine` branch exists, and the `msg` leaf takes its target via `--to`, not
+// positionally). Every exec exited non-zero, so `deliverTrigger` recorded
+// `failed` for every cron fire and webhook — the entire SEAM-5 delivery path
+// was dead. This test fails if the argv regresses to `node spine msg` or a
+// positional target.
+test('wakeAndExecNodeMessage runs `crtr node msg --to <target> --tier <tier>` with the body on stdin', async () => {
+    const { wakeAndExecNodeMessage, nodeMessageInternals } = await import('../node-message.js');
+    const orig = { ...nodeMessageInternals };
+    const execCalls = [];
+    nodeMessageInternals.getHomeById = ((home_id) => ({
+        home_id,
+        tenant_id: 't1',
+        user_id: 'u1',
+        provider: 'blaxel',
+        provider_sandbox_id: 'sbx-1',
+        provider_volume_id: null,
+        preview_endpoint: null,
+        home_agent_target: 'home-agent-1',
+        relay_auth_ref: null,
+        status: 'running',
+        template_version: null,
+        last_ready_at: null,
+        last_wake_at: null,
+        last_suspend_at: null,
+        last_wake_latency_ms: null,
+        health_verdict: 'healthy',
+        created_at: '2026-06-30T00:00:00.000Z',
+        updated_at: '2026-06-30T00:00:00.000Z',
+    }));
+    nodeMessageInternals.ensureAwake = async () => ({ preview_endpoint: 'https://x.example', relayToken: 'tok' });
+    nodeMessageInternals.loadM0Config = (() => ({}));
+    nodeMessageInternals.getHomeBackend = (() => ({
+        wake: async () => ({ provider_sandbox_id: 'sbx-1', provider_volume_id: null, preview_endpoint: null }),
+        suspend: async () => ({ provider_sandbox_id: 'sbx-1', provider_volume_id: null, preview_endpoint: null }),
+        getMachine: async () => null,
+        exec: async (machineId, input) => {
+            execCalls.push({ machineId, argv: input.argv, stdin: input.stdin });
+            return { exitCode: 0, timedOut: false, stdout: '', stderr: '' };
+        },
+    }));
+    try {
+        await wakeAndExecNodeMessage('h1', '{"source":"cron","trigger_id":"f1"}', 'urgent');
+        assert.equal(execCalls.length, 1);
+        const call = execCalls[0];
+        assert.equal(call.machineId, 'sbx-1');
+        // The real CLI form: `crtr node msg --to <target> --tier <tier>` — never
+        // `node spine msg` and never a positional target.
+        assert.deepEqual(call.argv, ['crtr', 'node', 'msg', '--to', 'home-agent-1', '--tier', 'urgent']);
+        assert.equal(call.argv.includes('spine'), false);
+        assert.equal(call.stdin, '{"source":"cron","trigger_id":"f1"}');
+    }
+    finally {
+        Object.assign(nodeMessageInternals, orig);
+    }
+});

package/dist/hearth/control-plane/__tests__/rate-limit-recurrence.test.js

@@ -0,0 +1,49 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRateLimiter } from '../ingress/rate-limit.js';
+import { computeNextFire } from '../scheduler/recurrence.js';
+// Category-2 (rate limiter) + category-3 (recurrence) test. The rate-limiter
+// case locks the fix for an observed bug found during P5.5 implementation: an
+// over-eager idle-prune deleted a per-key bucket right after its first draw,
+// so per-key limiting never actually bit. The recurrence case locks the custom
+// interval-parsing + timezone plumbing (my code, not cron-parser's) that cron
+// firing depends on.
+test('the per-key token bucket actually limits a burst and refills over time', () => {
+    let nowMs = 1_000_000;
+    const limiter = createRateLimiter({ capacity: 3, refillPerSec: 1, globalCapacity: 1_000, globalRefillPerSec: 1_000, now: () => nowMs });
+    // Three tokens available for one key, then it trips (the prune bug would let
+    // every request through by resetting the bucket to full each call).
+    assert.equal(limiter.checkRate('k').ok, true);
+    assert.equal(limiter.checkRate('k').ok, true);
+    assert.equal(limiter.checkRate('k').ok, true);
+    const tripped = limiter.checkRate('k');
+    assert.equal(tripped.ok, false);
+    assert.equal(typeof tripped.retryAfterMs, 'number');
+    // A different key has its own independent bucket.
+    assert.equal(limiter.checkRate('other').ok, true);
+    // After ~2s one key refills 2 tokens.
+    nowMs += 2_000;
+    assert.equal(limiter.checkRate('k').ok, true);
+    assert.equal(limiter.checkRate('k').ok, true);
+    assert.equal(limiter.checkRate('k').ok, false);
+});
+test('the global ceiling sheds a flood spread across many distinct keys', () => {
+    let nowMs = 0;
+    const limiter = createRateLimiter({ capacity: 100, refillPerSec: 100, globalCapacity: 5, globalRefillPerSec: 0.0001, now: () => nowMs });
+    let ok = 0;
+    for (let i = 0; i < 20; i++) {
+        if (limiter.checkRate(`key-${i}`).ok)
+            ok += 1;
+    }
+    assert.equal(ok, 5); // global ceiling caps total admits regardless of key spread
+});
+test('computeNextFire handles cron expressions, timezones, and @every intervals', () => {
+    assert.equal(computeNextFire('*/5 * * * *', 'UTC', '2026-06-30T12:01:00.000Z'), '2026-06-30T12:05:00.000Z');
+    // Interval form is timezone-independent, strictly after `after`.
+    assert.equal(computeNextFire('@every 30m', 'America/New_York', '2026-06-30T12:00:00.000Z'), '2026-06-30T12:30:00.000Z');
+    assert.equal(computeNextFire('@every 90s', 'UTC', '2026-06-30T12:00:00.000Z'), '2026-06-30T12:01:30.000Z');
+    // A tz-bearing daily schedule resolves to the correct UTC instant: 09:00
+    // EDT the same day is 13:00 UTC (after 08:00 EDT / 12:00 UTC).
+    assert.equal(computeNextFire('0 9 * * *', 'America/New_York', '2026-06-30T12:00:00.000Z'), '2026-06-30T13:00:00.000Z');
+    assert.throws(() => computeNextFire('not a cron', 'UTC', '2026-06-30T12:00:00.000Z'));
+});

package/dist/hearth/control-plane/__tests__/relay-security.test.js

@@ -0,0 +1,314 @@
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import http from 'node:http';
+import { test } from 'node:test';
+import { WebSocket, WebSocketServer } from 'ws';
+import { buildUpstreamHttpUrl, proxyHttp, proxyUpgrade } from '../relay.js';
+// Category-3 test (CLAUDE.md "Testing policy" #3 — load-bearing Hearth/CP
+// security regression). Approved by Silas 2026-06-30 as a narrow carve-out
+// after the P4.3 relay review (mr16xp6d-2a5061f5 / mr16z2lz-3cd35b0c) found
+// these exact invariants had zero durable coverage — only a throwaway smoke
+// that was deleted after the implementation pass. The invariants below are
+// the ones part-plan T3.2's acceptance checks and design.md's R-CP-2/R-CP-3/
+// R-CP-6 non-negotiables name explicitly:
+//   - R-CP-3: the browser leg never supplies, and never sees reflected, the
+//     CP->home relay token; the home leg sees ONLY `Authorization: Bearer
+//     <relayToken>`.
+//   - criterion 4 (origin-form-only request target): scheme-relative,
+//     absolute, raw/encoded-backslash, and encoded-CRLF request targets are
+//     rejected before any upstream contact (open-proxy/SSRF prevention).
+//   - R-CP-2/R-CP-6: `home` is resolved once, server-side, from the
+//     caller's session; no client-supplied `?target=`/`/node/<id>` can move
+//     the request onto a different home's preview origin or node target.
+// A regression in any of these is silent (still typechecks, still serves
+// chat) and is exactly the kind of defect this carve-out exists for.
+const testConfig = {
+    host: '127.0.0.1',
+    port: 0,
+    publicOrigin: 'http://127.0.0.1:0',
+    cookieSecure: false,
+    wakeTimeoutMs: 2_000,
+    readyTimeoutMs: 2_000,
+};
+function makeHome(overrides = {}) {
+    const now = '2026-06-30T00:00:00.000Z';
+    return {
+        home_id: 'home-a',
+        tenant_id: 'tenant-1',
+        user_id: 'user-1',
+        provider: 'blaxel',
+        provider_sandbox_id: 'sandbox-a',
+        provider_volume_id: 'volume-a',
+        preview_endpoint: 'https://home-a.example.invalid',
+        home_agent_target: 'node-a',
+        relay_auth_ref: 'ref-a',
+        status: 'running',
+        template_version: null,
+        last_ready_at: null,
+        last_wake_at: null,
+        last_suspend_at: null,
+        last_wake_latency_ms: null,
+        health_verdict: 'healthy',
+        created_at: now,
+        updated_at: now,
+        ...overrides,
+    };
+}
+// --- Minimal req/res fakes (same shape as wake-proxy/__tests__'s FakeReq/
+// FakeRes — only the surface proxyHttp actually touches). ------------------
+class FakeReq extends EventEmitter {
+    url;
+    method;
+    headers;
+    constructor(path, headers = {}, method = 'GET') {
+        super();
+        this.url = path;
+        this.method = method;
+        this.headers = headers;
+    }
+}
+class FakeRes extends EventEmitter {
+    statusCode = 200;
+    statusMessage = '';
+    headersSent = false;
+    writableEnded = false;
+    headers = new Map();
+    chunks = [];
+    socket = { setNoDelay() { } };
+    setHeader(name, value) {
+        this.headers.set(name.toLowerCase(), value);
+    }
+    getHeader(name) {
+        return this.headers.get(name.toLowerCase());
+    }
+    hasHeader(name) {
+        return this.headers.has(name.toLowerCase());
+    }
+    writeHead(code, headers) {
+        this.statusCode = code;
+        this.headersSent = true;
+        if (headers)
+            for (const [k, v] of Object.entries(headers))
+                this.setHeader(k, v);
+    }
+    flushHeaders() {
+        this.headersSent = true;
+    }
+    write(chunk) {
+        this.headersSent = true;
+        this.chunks.push(Buffer.from(chunk));
+        return true;
+    }
+    end(chunk) {
+        this.headersSent = true;
+        if (chunk !== undefined)
+            this.chunks.push(Buffer.from(chunk));
+        this.writableEnded = true;
+        this.emit('finish');
+    }
+    destroy() {
+        this.writableEnded = true;
+    }
+    body() {
+        return Buffer.concat(this.chunks).toString('utf8');
+    }
+}
+function asReq(req) {
+    return req;
+}
+function asRes(res) {
+    return res;
+}
+async function listen(server) {
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    if (address === null || typeof address === 'string')
+        throw new Error('expected a network address');
+    return {
+        origin: `http://127.0.0.1:${address.port}`,
+        close: () => new Promise((resolve) => server.close(() => resolve())),
+    };
+}
+// --- 1. HTTP browser->home header/token isolation -------------------------
+test('proxyHttp: browser auth/cookie/forwarding headers never reach upstream; only the relay Bearer token does; the token is never reflected to the browser', async () => {
+    let captured = null;
+    const upstream = http.createServer((req, res) => {
+        captured = req.headers;
+        // Deliberately reflect the relay token back in the response, the way a
+        // misbehaving or compromised home might — this is what makes the
+        // browser-side assertion below non-vacuous.
+        res.writeHead(200, { 'content-type': 'text/plain', authorization: 'Bearer RELAY_TOKEN_A' });
+        res.end('upstream-ok');
+    });
+    const { origin, close } = await listen(upstream);
+    try {
+        const req = new FakeReq('/views/chat', {
+            authorization: 'Bearer BROWSER_OWN_TOKEN',
+            cookie: 'session=browser-cookie',
+            forwarded: 'for=1.2.3.4;proto=https',
+            'x-forwarded-for': '1.2.3.4',
+            'x-forwarded-proto': 'https',
+            'x-forwarded-host': 'evil.example',
+            'x-real-ip': '1.2.3.4',
+            'proxy-authorization': 'Basic evil',
+            'sec-websocket-key': 'not-a-real-ws-request',
+            'x-keep-me': 'safe-custom-header',
+        });
+        const res = new FakeRes();
+        await proxyHttp(asReq(req), asRes(res), makeHome(), {
+            ensureAwake: async () => ({ preview_endpoint: origin, relayToken: 'RELAY_TOKEN_A' }),
+            resolveRunning: () => null,
+            invalidateWarmVerdict: () => undefined,
+            loadConfig: () => testConfig,
+        });
+        assert.equal(res.statusCode, 200);
+        assert.equal(res.body(), 'upstream-ok');
+        assert.ok(captured, 'upstream must have received the forwarded request');
+        const upstreamHeaders = captured;
+        assert.equal(upstreamHeaders.authorization, 'Bearer RELAY_TOKEN_A', 'upstream must see only the relay token');
+        assert.equal(upstreamHeaders.cookie, undefined, 'browser cookie must not reach upstream');
+        assert.equal(upstreamHeaders.forwarded, undefined, 'client-supplied Forwarded must not reach upstream');
+        assert.equal(upstreamHeaders['x-forwarded-for'], undefined);
+        assert.equal(upstreamHeaders['x-forwarded-proto'], undefined);
+        assert.equal(upstreamHeaders['x-forwarded-host'], undefined);
+        assert.equal(upstreamHeaders['x-real-ip'], undefined);
+        assert.equal(upstreamHeaders['proxy-authorization'], undefined);
+        assert.equal(upstreamHeaders['sec-websocket-key'], undefined);
+        assert.equal(upstreamHeaders['x-keep-me'], 'safe-custom-header', 'a safe custom header must still pass through');
+        assert.equal(res.getHeader('authorization'), undefined, 'an upstream-reflected relay token must never reach the browser response');
+    }
+    finally {
+        await close();
+    }
+});
+// --- 2. Origin-form / SSRF rejection --------------------------------------
+test('buildUpstreamHttpUrl: rejects dangerous request targets before any upstream contact', () => {
+    const previewEndpoint = 'https://home-a.example.invalid';
+    const dangerous = [
+        '//evil.example.com/path',
+        'http://evil.example.com/path',
+        '\\evil.example.com/path',
+        '%5Cevil.example.com/path',
+        '%0d%0aHost:%20evil.example.com',
+    ];
+    for (const target of dangerous) {
+        assert.throws(() => buildUpstreamHttpUrl(previewEndpoint, target), `expected rejection for: ${target}`);
+    }
+});
+test('buildUpstreamHttpUrl: accepts an ordinary origin-form target and stays on the home origin', () => {
+    const url = buildUpstreamHttpUrl('https://home-a.example.invalid', '/views/chat?x=1');
+    assert.equal(url.origin, 'https://home-a.example.invalid');
+    assert.equal(url.pathname, '/views/chat');
+});
+// --- 3. Cross-home/target isolation ---------------------------------------
+test('proxyHttp: a session-resolved home A is never widened by a client ?target= to home B', async () => {
+    let hitsA = 0;
+    let hitsB = 0;
+    const upstreamA = http.createServer((_req, res) => {
+        hitsA += 1;
+        res.writeHead(200);
+        res.end('home-a-ok');
+    });
+    const upstreamB = http.createServer((_req, res) => {
+        hitsB += 1;
+        res.writeHead(200);
+        res.end('home-b-ok');
+    });
+    const a = await listen(upstreamA);
+    const b = await listen(upstreamB);
+    try {
+        const req = new FakeReq('/views/chat?target=home-b');
+        const res = new FakeRes();
+        let ensureAwakeAskedFor = null;
+        let resolveRunningAskedFor = null;
+        await proxyHttp(asReq(req), asRes(res), makeHome({ home_id: 'home-a' }), {
+            ensureAwake: async (home_id) => {
+                ensureAwakeAskedFor = home_id;
+                // The relay's only home-selection input is the `home` row it was
+                // called with — never the request's own query string.
+                if (home_id !== 'home-a')
+                    return { preview_endpoint: b.origin, relayToken: 'RELAY_TOKEN_B' };
+                return { preview_endpoint: a.origin, relayToken: 'RELAY_TOKEN_A' };
+            },
+            resolveRunning: (home_id) => {
+                resolveRunningAskedFor = home_id;
+                return null;
+            },
+            invalidateWarmVerdict: () => undefined,
+            loadConfig: () => testConfig,
+        });
+        assert.equal(resolveRunningAskedFor, 'home-a', 'resolveRunning must be asked for the session-resolved home, never a client-supplied target');
+        assert.equal(ensureAwakeAskedFor, 'home-a', 'ensureAwake must be asked for the session-resolved home, never a client-supplied target');
+        assert.equal(res.body(), 'home-a-ok');
+        assert.equal(hitsA, 1);
+        assert.equal(hitsB, 0, 'home B must never be contacted for a home-A-resolved request');
+    }
+    finally {
+        await Promise.all([a.close(), b.close()]);
+    }
+});
+test('proxyUpgrade: WS upstream target is always home.home_agent_target, never the client-claimed /node/<id> path or ?target=', async () => {
+    let upstreamAHits = [];
+    let upstreamBHits = 0;
+    const wssA = new WebSocketServer({ port: 0 });
+    wssA.on('connection', (ws, req) => {
+        upstreamAHits.push({ url: req.url, authorization: req.headers.authorization, cookie: req.headers.cookie });
+        ws.on('message', (data) => ws.send(data));
+    });
+    const wssB = new WebSocketServer({ port: 0 });
+    wssB.on('connection', () => {
+        upstreamBHits += 1;
+    });
+    const aPort = wssA.address().port;
+    const bPort = wssB.address().port;
+    const home = makeHome({ home_id: 'home-a', home_agent_target: 'node-a' });
+    let ensureAwakeAskedFor = null;
+    const relayServer = http.createServer((_req, res) => {
+        res.writeHead(404);
+        res.end();
+    });
+    relayServer.on('upgrade', (req, socket, head) => {
+        proxyUpgrade(req, socket, head, home, {
+            ensureAwake: async (home_id) => {
+                ensureAwakeAskedFor = home_id;
+                // Same DI seam as the HTTP cross-home test: a regression that derived
+                // the wake target from the client's `?target=` would make this
+                // resolve to home B's listener, and the assertions below would catch
+                // the resulting connection landing on wssB instead of wssA.
+                if (home_id !== 'home-a')
+                    return { preview_endpoint: `http://127.0.0.1:${bPort}`, relayToken: 'RELAY_TOKEN_B' };
+                return { preview_endpoint: `http://127.0.0.1:${aPort}`, relayToken: 'RELAY_TOKEN_A' };
+            },
+            loadConfig: () => testConfig,
+        });
+    });
+    const relay = await listen(relayServer);
+    let client = null;
+    try {
+        client = new WebSocket(`${relay.origin.replace('http://', 'ws://')}/node/some-other-client-claimed-id?target=home-b`, {
+            headers: { authorization: 'Bearer BROWSER_OWN_TOKEN', cookie: 'session=browser-cookie' },
+        });
+        const echoed = await new Promise((resolve, reject) => {
+            client.once('open', () => client.send('ping'));
+            client.once('message', (data) => resolve(data.toString()));
+            client.once('error', reject);
+        });
+        assert.equal(echoed, 'ping');
+        assert.equal(ensureAwakeAskedFor, 'home-a', 'ensureAwake must be asked for the session-resolved home, never the client-claimed path/target');
+        assert.equal(upstreamAHits.length, 1);
+        assert.equal(upstreamAHits[0]?.url, '/node/node-a', 'upstream path must be the server-resolved home_agent_target, not the client path/target');
+        assert.equal(upstreamAHits[0]?.authorization, 'Bearer RELAY_TOKEN_A');
+        assert.equal(upstreamAHits[0]?.cookie, undefined, 'the browser cookie must never reach the upstream websocket');
+        assert.equal(upstreamBHits, 0, 'home B must never receive a connection for a home-A-resolved request');
+    }
+    finally {
+        if (client) {
+            if (client.readyState === WebSocket.OPEN || client.readyState === WebSocket.CONNECTING) {
+                client.terminate();
+            }
+        }
+        await new Promise((resolve) => wssA.close(() => resolve()));
+        await new Promise((resolve) => wssB.close(() => resolve()));
+        await relay.close();
+    }
+});