pome-sh 0.6.6

package/dist/src/demo/capacity.js

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: Apache-2.0
+// FDRS-643 / FDRS-662 — honest at-capacity states for the anonymous demo.
+//
+// The demo's cloud surface returns machine-readable 402/429 errors at three
+// choke points (mint, model-call gateway, finalize/judge). Each maps to an
+// honest labeled terminal state — never a stack trace, never a fabricated
+// completion. Kinds of record (pome-cloud routes/demo-sessions.ts,
+// routes/demo-llm.ts, routes/finalize.ts):
+//   - mint 429 (per-IP daily session cap; no `kind` in details)
+//   - mint 402 (house team session quota; no `kind`)
+//   - gateway 429 kind=session_llm_call_cap
+//   - gateway 429 kind=demo_ip_llm_cap
+//   - gateway 402 kind=daily_model_cap
+//   - finalize 402 kind=daily_judge_cap
+//   - gateway 503 kind=ai_gateway_disabled / demo_model_unpriced
+export class DemoCapacityError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = "DemoCapacityError";
+    }
+}
+/** Map a machine-readable error `kind` string (from the cloud envelope's
+ *  details) + HTTP status to a DemoCapacityKind. */
+export function capacityKindFrom(status, detailsKind) {
+    if (typeof detailsKind === "string") {
+        switch (detailsKind) {
+            case "session_llm_call_cap":
+                return "session_llm_call_cap";
+            case "demo_ip_llm_cap":
+                return "demo_ip_llm_cap";
+            case "daily_model_cap":
+                return "daily_model_cap";
+            case "daily_judge_cap":
+                return "daily_judge_cap";
+            case "ai_gateway_disabled":
+            case "demo_model_unpriced":
+                return "gateway_unavailable";
+            default:
+                break;
+        }
+    }
+    if (status === 402 || status === 429)
+        return "unknown_capacity";
+    if (status === 503)
+        return "gateway_unavailable";
+    return null;
+}
+/** One honest human line per at-capacity kind (design: "the demo is at
+ *  capacity today — try again tomorrow" register; no stack traces). */
+export function capacityLabel(kind) {
+    switch (kind) {
+        case "demo_ip_mint_cap":
+        case "demo_ip_llm_cap":
+            return "the demo hit today's limit for this network — try again tomorrow, or sign up for a free account";
+        case "daily_model_cap":
+            return "the demo's daily model budget is exhausted — try again tomorrow, or sign up for a free account";
+        case "daily_judge_cap":
+            return "the demo's daily evaluation budget is exhausted — try again tomorrow, or sign up for a free account";
+        case "session_llm_call_cap":
+            return "this trial hit its model-call ceiling";
+        case "gateway_unavailable":
+            return "the demo model gateway is unavailable right now — try again shortly";
+        case "demo_mint_quota":
+        case "unknown_capacity":
+            return "the demo is at capacity today — try again tomorrow";
+    }
+}
+/** Marker line the bundled agent prints to stderr when the GATEWAY reports
+ *  capacity, so the parent `pome demo` process (which only sees the child's
+ *  exit code + stderr) can render the honest label instead of a generic
+ *  "trial errored". */
+export const CAPACITY_STDERR_PREFIX = "POME_DEMO_CAPACITY:";
+export function capacityMarkerLine(kind) {
+    return `${CAPACITY_STDERR_PREFIX}${kind}`;
+}
+export function parseCapacityMarker(stderr) {
+    const match = stderr.match(new RegExp(`${CAPACITY_STDERR_PREFIX}([a-z_]+)`, "m"));
+    if (!match)
+        return null;
+    const kind = match[1];
+    const known = [
+        "demo_ip_mint_cap",
+        "demo_mint_quota",
+        "session_llm_call_cap",
+        "demo_ip_llm_cap",
+        "daily_model_cap",
+        "daily_judge_cap",
+        "gateway_unavailable",
+        "unknown_capacity",
+    ];
+    return known.includes(kind) ? kind : "unknown_capacity";
+}

package/dist/src/demo/first-run-demo.md

@@ -0,0 +1,67 @@
+# first-run-demo
+
+<!--
+FDRS-643 — the packaged `npx pome-sh demo` task. This markdown is the
+CANONICAL source of the demo task content: the cloud's server-owned judge
+definition (pome-cloud apps/control-plane/src/lib/demo.ts,
+DEMO_TASK_DEFINITIONS["first-run-demo"]) is regenerated FROM this file — the
+judge scores the server copy, never a client-supplied body, so the two must
+stay in lockstep. Changing the prompt / expected behavior / criteria here
+without regenerating the server definition means the cloud judges a
+different task than the one the bundled agent ran.
+
+The three tools the bundled demo agent exposes (src/demo/agent.ts) are the
+contract this task is written against: list_open_issues, add_label,
+comment_on_issue.
+-->
+
+## Prompt
+
+You are triaging the acme/api repository. Find the open issue that reports a
+500 error on POST /orders, apply the existing `bug` label to it, and leave
+exactly one comment on that issue naming the failing endpoint and summarizing
+the reported evidence for the maintainer. Use only the tools you are given.
+
+## Expected Behavior
+
+The agent lists the open issues, identifies the 500-error report among the
+decoys, applies the existing `bug` label to exactly that issue, and leaves one
+comment naming the failing endpoint (POST /orders) with the reported evidence
+— without creating labels, inventing endpoints or ids, or touching any other
+issue.
+
+## Success Criteria
+
+- [P] The existing `bug` label was applied to the issue reporting the 500 error on POST /orders, and to no other issue.
+- [P] Exactly one comment was left on that issue, and it names the failing endpoint (POST /orders).
+- [P] No other issue was modified and no new label was created.
+
+## Seed State
+
+A GitHub-shaped twin seeded for issue triage (compiled sidecar:
+`first-run-demo.seed.json` — hand-written, kept in lockstep with this prose).
+
+### Repository: `acme/api`
+
+A normal public repo, default branch `main`. `alice` and `bob` are
+collaborators. Exactly three labels exist — `bug`, `feature`, `question` —
+so the agent must pick one rather than invent one.
+
+### Issues
+
+Three open issues, none labeled, none assigned:
+
+- **#1** `500 error on POST /orders after deploy` — "Started failing right
+  after the 14:00 deploy. Stack trace points to OrderController#create."
+  (the target)
+- **#2** `Add CSV export for the orders dashboard` — a feature request
+  (decoy)
+- **#3** `How do we rotate the staging API keys?` — a question (decoy)
+
+## Config
+
+```yaml
+twins: [github]
+timeout: 60
+passThreshold: 100
+```

package/dist/src/demo/first-run-demo.seed.json

@@ -0,0 +1,60 @@
+{
+  "_meta": {
+    "version": 1,
+    "source_hash": "handwritten",
+    "model": "handwritten",
+    "compiled_at": "2026-07-05T00:00:00.000Z"
+  },
+  "repositories": [
+    {
+      "owner": "acme",
+      "name": "api",
+      "description": "ACME API service",
+      "default_branch": "main",
+      "labels": [
+        {
+          "name": "bug",
+          "color": "d73a4a",
+          "description": "Something isn't working"
+        },
+        {
+          "name": "feature",
+          "color": "a2eeef",
+          "description": "New feature request"
+        },
+        {
+          "name": "question",
+          "color": "d876e3",
+          "description": "Further information is requested"
+        }
+      ],
+      "collaborators": ["alice", "bob"],
+      "issues": [
+        {
+          "number": 1,
+          "title": "500 error on POST /orders after deploy",
+          "body": "Started failing right after the 14:00 deploy. Stack trace points to OrderController#create.",
+          "state": "open",
+          "labels": [],
+          "assignee": null
+        },
+        {
+          "number": 2,
+          "title": "Add CSV export for the orders dashboard",
+          "body": "Finance wants to pull monthly order data into a spreadsheet without asking engineering.",
+          "state": "open",
+          "labels": [],
+          "assignee": null
+        },
+        {
+          "number": 3,
+          "title": "How do we rotate the staging API keys?",
+          "body": "The runbook mentions a rotation script but I can't find it in the repo.",
+          "state": "open",
+          "labels": [],
+          "assignee": null
+        }
+      ]
+    }
+  ]
+}

package/dist/src/demo/gateway.d.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+export type DemoTextPart = {
+    type: "text";
+    text: string;
+};
+export type DemoToolCallPart = {
+    type: "tool-call";
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+};
+export type DemoToolResultPart = {
+    type: "tool-result";
+    toolCallId: string;
+    toolName: string;
+    output: unknown;
+};
+export type DemoMessage = {
+    role: "user";
+    content: string;
+} | {
+    role: "assistant";
+    content: string | Array<DemoTextPart | DemoToolCallPart>;
+} | {
+    role: "tool";
+    content: DemoToolResultPart[];
+};
+export interface DemoToolDef {
+    name: string;
+    description?: string;
+    input_schema: Record<string, unknown>;
+}
+declare const gatewayResponseSchema: z.ZodObject<{
+    text: z.ZodString;
+    tool_calls: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        input: z.ZodUnknown;
+    }, z.core.$strip>>;
+    finish_reason: z.ZodString;
+    usage: z.ZodOptional<z.ZodObject<{
+        input_tokens: z.ZodNumber;
+        output_tokens: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type GatewayResponse = z.infer<typeof gatewayResponseSchema>;
+export interface CallDemoGatewayOptions {
+    /** Full gateway URL: {apiBase}/v1/demo/sessions/{sid}/llm. */
+    gatewayUrl: string;
+    demoToken: string;
+    taskName: string;
+    messages: DemoMessage[];
+    tools?: DemoToolDef[];
+    /** Proxy coordinates (HTTPS_PROXY / NO_PROXY from the runner). */
+    proxyUrl?: string;
+    noProxy?: string;
+    timeoutMs?: number;
+    /** Test seam — force the CONNECT path for loopback targets. */
+    forceProxyForTest?: boolean;
+}
+export declare class DemoGatewayError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+export declare function callDemoGateway(options: CallDemoGatewayOptions): Promise<GatewayResponse>;
+export {};

package/dist/src/demo/gateway.js

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: Apache-2.0
+// FDRS-643 — client for the anonymous demo model-call gateway (FDRS-637):
+// POST {POME_API_BASE}/v1/demo/sessions/:id/llm, Authorization: Bearer
+// <demo_token>.
+//
+// The wire shape is a STRICT ModelMessage subset (pome-cloud
+// routes/demo-llm.ts): user text, assistant text/tool-call parts, tool
+// results — NO `system` role (server-owned prompt), NO `model` field
+// (server-pinned). Unknown fields are a 422 BY DESIGN; that strictness IS the
+// scenario lock, so this client never spreads extra keys into messages.
+// Requests travel through the runner-injected capture proxy
+// (proxyRequest.ts) so each gateway call lands in events.jsonl as a genuine
+// LlmCallEvent and stays inside the egress floor.
+import { z } from "zod";
+import { DemoCapacityError, capacityKindFrom, capacityLabel } from "./capacity.js";
+import { postJsonMaybeViaProxy } from "./proxyRequest.js";
+const gatewayResponseSchema = z.object({
+    text: z.string(),
+    tool_calls: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        input: z.unknown(),
+    })),
+    finish_reason: z.string(),
+    usage: z
+        .object({
+        input_tokens: z.number(),
+        output_tokens: z.number(),
+    })
+        .optional(),
+});
+export class DemoGatewayError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "DemoGatewayError";
+    }
+}
+export async function callDemoGateway(options) {
+    const { status, bodyText } = await postJsonMaybeViaProxy({
+        url: options.gatewayUrl,
+        headers: { authorization: `Bearer ${options.demoToken}` },
+        body: {
+            task_name: options.taskName,
+            messages: options.messages,
+            ...(options.tools && options.tools.length > 0
+                ? { tools: options.tools }
+                : {}),
+        },
+        proxyUrl: options.proxyUrl,
+        noProxy: options.noProxy,
+        timeoutMs: options.timeoutMs ?? 120_000,
+        forceProxy: options.forceProxyForTest,
+    });
+    let json = {};
+    try {
+        json = bodyText.length ? JSON.parse(bodyText) : {};
+    }
+    catch {
+        throw new DemoGatewayError(`demo gateway returned non-JSON (status ${status})`, status);
+    }
+    if (status < 200 || status >= 300) {
+        const envelope = json.error;
+        const kind = capacityKindFrom(status, envelope?.details?.kind);
+        if (kind) {
+            throw new DemoCapacityError(kind, envelope?.message ?? capacityLabel(kind));
+        }
+        throw new DemoGatewayError(envelope?.message ?? `demo gateway → HTTP ${status}`, status);
+    }
+    const parsed = gatewayResponseSchema.safeParse(json);
+    if (!parsed.success) {
+        throw new DemoGatewayError(`demo gateway returned an unexpected shape: ${parsed.error.message}`, status);
+    }
+    return parsed.data;
+}

package/dist/src/demo/ids.d.ts

@@ -0,0 +1,4 @@
+/** nanoid-shaped random string over the url-safe 64-char alphabet. */
+export declare function nanoid(size?: number): string;
+/** Mint one trial-group id: `grp_` + nanoid21. */
+export declare function newGroupId(): string;

package/dist/src/demo/ids.js

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: Apache-2.0
+// FDRS-643 — trial-group identity for `pome demo`.
+//
+// One `grp_` + nanoid21 id per demo invocation, shared by all k=5 demo
+// sessions (mint body `group_id`), copied by the cloud onto
+// `sessions.group_id` at mint and `runs.group_id` at finalize, and forming
+// the no-login preview URL `app.pome.sh/demo/<group_id>`.
+//
+// Format contract: the cloud validates `^[A-Za-z0-9_-]{6,64}$`
+// (isValidGroupId in pome-cloud lib/demo.ts). "grp_" + 21 url-safe chars =
+// 25 chars, comfortably inside.
+import { randomBytes } from "node:crypto";
+const NANOID_ALPHABET = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
+/** nanoid-shaped random string over the url-safe 64-char alphabet. */
+export function nanoid(size = 21) {
+    const bytes = randomBytes(size);
+    let id = "";
+    for (let i = 0; i < size; i += 1) {
+        // 64-char alphabet ⇒ 6 bits per char; masking keeps the distribution
+        // uniform (no modulo bias).
+        id += NANOID_ALPHABET[bytes[i] & 63];
+    }
+    return id;
+}
+/** Mint one trial-group id: `grp_` + nanoid21. */
+export function newGroupId() {
+    return `grp_${nanoid(21)}`;
+}

package/dist/src/demo/mint.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+export declare const demoSessionSchema: z.ZodObject<{
+    session_id: z.ZodString;
+    demo_token: z.ZodString;
+    expires_at: z.ZodString;
+}, z.core.$strip>;
+export type DemoSession = z.infer<typeof demoSessionSchema>;
+export interface MintDemoSessionsOptions {
+    apiBase: string;
+    taskName: string;
+    groupId: string;
+    count: number;
+    /** Injectable for tests. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+export declare function mintDemoSessions(options: MintDemoSessionsOptions): Promise<DemoSession[]>;

package/dist/src/demo/mint.js

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+// FDRS-643 — anonymous demo session minting.
+//
+// POST {POME_API_BASE}/v1/demo/sessions with
+//   { task_name: "first-run-demo", task_hash: "", group_id: "grp_…" }
+// → { session_id, demo_token, expires_at }. No auth: the response's
+// demo_token (a sid-scoped JWT) is the credential for everything that
+// follows (gateway calls, blob uploads, finalize).
+//
+// All k sessions are minted UPFRONT (one shared group_id per invocation);
+// each session's 15-minute TTL comfortably covers the whole k=5 run, so mint
+// order is irrelevant. 402/429/503 map to DemoCapacityError so the CLI
+// renders an honest labeled state.
+import { z } from "zod";
+import { HostedOrchError } from "../hosted/errors.js";
+import { DemoCapacityError, capacityKindFrom, capacityLabel } from "./capacity.js";
+export const demoSessionSchema = z.object({
+    session_id: z.string().min(1),
+    demo_token: z.string().min(1),
+    expires_at: z.string(),
+});
+export async function mintDemoSessions(options) {
+    const sessions = [];
+    for (let i = 0; i < options.count; i += 1) {
+        sessions.push(await mintOne(options));
+    }
+    return sessions;
+}
+async function mintOne(options) {
+    const doFetch = options.fetchImpl ?? fetch;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), options.timeoutMs ?? 30_000);
+    let res;
+    try {
+        res = await doFetch(`${options.apiBase}/v1/demo/sessions`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                task_name: options.taskName,
+                task_hash: "",
+                group_id: options.groupId,
+            }),
+            signal: ctrl.signal,
+        });
+    }
+    catch (err) {
+        throw new HostedOrchError(err instanceof Error ? err.message : "network error");
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const text = await res.text();
+    let json = {};
+    try {
+        json = text.length ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new HostedOrchError(`POST /v1/demo/sessions returned non-JSON (status ${res.status})`);
+    }
+    if (!res.ok) {
+        const envelope = json.error;
+        // Mint 429 = per-IP daily session cap, 402 = house-team session quota
+        // (neither carries a `kind` in details today — map by status).
+        let kind = capacityKindFrom(res.status, envelope?.details?.kind);
+        if (kind === "unknown_capacity") {
+            kind = res.status === 429 ? "demo_ip_mint_cap" : "demo_mint_quota";
+        }
+        if (kind) {
+            throw new DemoCapacityError(kind, envelope?.message ?? capacityLabel(kind));
+        }
+        throw new HostedOrchError(envelope?.message ?? `POST /v1/demo/sessions → HTTP ${res.status}`, undefined, res.status);
+    }
+    const parsed = demoSessionSchema.safeParse(json);
+    if (!parsed.success) {
+        throw new HostedOrchError(`POST /v1/demo/sessions returned an unexpected shape: ${parsed.error.message}`);
+    }
+    return parsed.data;
+}

package/dist/src/demo/proxyRequest.d.ts

@@ -0,0 +1,21 @@
+export interface ProxyJsonResponse {
+    status: number;
+    bodyText: string;
+}
+export interface PostJsonOptions {
+    url: string;
+    headers: Record<string, string>;
+    body: unknown;
+    /** e.g. process.env.HTTPS_PROXY. Absent → direct fetch. */
+    proxyUrl?: string;
+    /** e.g. process.env.NO_PROXY ("127.0.0.1,localhost"). */
+    noProxy?: string;
+    timeoutMs?: number;
+    /** Test seam: force the CONNECT-proxy path even for loopback targets
+     *  (unit tests run every server on 127.0.0.1, which the production
+     *  bypass would otherwise route around). */
+    forceProxy?: boolean;
+}
+export declare function isLoopbackHost(host: string): boolean;
+export declare function matchesNoProxy(host: string, noProxy: string | undefined): boolean;
+export declare function postJsonMaybeViaProxy(options: PostJsonOptions): Promise<ProxyJsonResponse>;

package/dist/src/demo/proxyRequest.js

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: Apache-2.0
+// FDRS-643 — proxy-aware JSON POST for the bundled demo agent.
+//
+// The demo agent is spawned through the real capture path (FDRS-399): the
+// runner injects HTTP(S)_PROXY pointing at the capture-server, whose CONNECT
+// tunnels become the LlmCallEvent rows in events.jsonl and whose
+// deny-by-default egress floor (FDRS-635) is the prod-safety control. Node's
+// global fetch does NOT honor proxy env vars, so an agent that used bare
+// fetch for its gateway calls would silently bypass both — no trace row, no
+// floor. This helper restores the contract without adding a dependency:
+//   - target in NO_PROXY / loopback, or no proxy configured → plain fetch;
+//   - otherwise: CONNECT through the proxy, TLS-wrap for https targets, then
+//     a plain node:http request over the established socket.
+import { request as httpRequest } from "node:http";
+import { connect as netConnect } from "node:net";
+import { connect as tlsConnect } from "node:tls";
+export function isLoopbackHost(host) {
+    const value = host.trim().toLowerCase();
+    if (value === "localhost" || value.endsWith(".localhost"))
+        return true;
+    if (value === "::1" || value === "[::1]")
+        return true;
+    return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(value);
+}
+export function matchesNoProxy(host, noProxy) {
+    if (!noProxy)
+        return false;
+    const candidate = host.trim().toLowerCase();
+    return noProxy
+        .split(",")
+        .map((entry) => entry.trim().toLowerCase())
+        .filter((entry) => entry.length > 0)
+        .some((entry) => entry === "*" ||
+        candidate === entry ||
+        candidate.endsWith(entry.startsWith(".") ? entry : `.${entry}`));
+}
+export async function postJsonMaybeViaProxy(options) {
+    const target = new URL(options.url);
+    const useProxy = Boolean(options.proxyUrl) &&
+        (options.forceProxy === true ||
+            (!isLoopbackHost(target.hostname) &&
+                !matchesNoProxy(target.hostname, options.noProxy)));
+    if (!useProxy) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), options.timeoutMs ?? 60_000);
+        try {
+            const res = await fetch(options.url, {
+                method: "POST",
+                headers: { ...options.headers, "content-type": "application/json" },
+                body: JSON.stringify(options.body),
+                signal: ctrl.signal,
+            });
+            return { status: res.status, bodyText: await res.text() };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return postJsonThroughConnectProxy(target, options);
+}
+async function postJsonThroughConnectProxy(target, options) {
+    const proxy = new URL(options.proxyUrl);
+    const targetPort = Number(target.port || (target.protocol === "https:" ? 443 : 80));
+    const timeoutMs = options.timeoutMs ?? 60_000;
+    const rawSocket = await connectTunnel(proxy.hostname, Number(proxy.port || 80), target.hostname, targetPort, timeoutMs);
+    const socket = target.protocol === "https:"
+        ? await new Promise((resolve, reject) => {
+            const tlsSocket = tlsConnect({ socket: rawSocket, servername: target.hostname }, () => resolve(tlsSocket));
+            tlsSocket.once("error", reject);
+        })
+        : rawSocket;
+    return new Promise((resolve, reject) => {
+        const payload = JSON.stringify(options.body);
+        const req = httpRequest({
+            createConnection: () => socket,
+            method: "POST",
+            host: target.hostname,
+            port: targetPort,
+            path: `${target.pathname}${target.search}`,
+            headers: {
+                ...options.headers,
+                host: target.host,
+                "content-type": "application/json",
+                "content-length": Buffer.byteLength(payload),
+                connection: "close",
+            },
+            timeout: timeoutMs,
+        }, (res) => {
+            let bodyText = "";
+            res.setEncoding("utf8");
+            res.on("data", (chunk) => {
+                bodyText += chunk;
+            });
+            res.on("end", () => {
+                resolve({ status: res.statusCode ?? 0, bodyText });
+            });
+            res.on("error", reject);
+        });
+        req.on("timeout", () => {
+            req.destroy(new Error(`request to ${target.host} timed out after ${timeoutMs}ms`));
+        });
+        req.on("error", (err) => {
+            socket.destroy();
+            reject(err);
+        });
+        req.end(payload);
+    });
+}
+function connectTunnel(proxyHost, proxyPort, targetHost, targetPort, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const sock = netConnect({ host: proxyHost, port: proxyPort });
+        let buf = "";
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            sock.destroy();
+            reject(new Error(`CONNECT to ${targetHost}:${targetPort} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        const fail = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            sock.destroy();
+            reject(err);
+        };
+        sock.once("error", fail);
+        const onData = (chunk) => {
+            buf += chunk.toString("utf8");
+            const headerEnd = buf.indexOf("\r\n\r\n");
+            if (headerEnd === -1)
+                return;
+            sock.off("data", onData);
+            if (!/^HTTP\/1\.[01] 200/.test(buf)) {
+                // FDRS-635 — a refused CONNECT (egress floor) surfaces as its 403
+                // status line, so the caller can say WHY the call failed.
+                fail(new Error(`CONNECT ${targetHost}:${targetPort} refused: ${buf.split("\r\n")[0]}`));
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            sock.pause();
+            // Bytes past the header (rare for CONNECT) belong to the tunneled
+            // stream; push them back so the TLS/http layer sees them.
+            const rest = Buffer.from(buf.slice(headerEnd + 4), "utf8");
+            if (rest.length > 0)
+                sock.unshift(rest);
+            sock.resume();
+            resolve(sock);
+        };
+        sock.on("data", onData);
+        sock.write(`CONNECT ${targetHost}:${targetPort} HTTP/1.1\r\nHost: ${targetHost}:${targetPort}\r\n\r\n`);
+    });
+}