@oxygen-agent/cli 1.233.8 → 1.242.6

package/dist/local-custom-http-column.d.ts

@@ -1,8 +1,10 @@
+import { type CustomHttpResolveHostname } from "@oxygen/shared/custom-http-safety";
 type LocalColumnRunOptions = {
     rowId: string | null;
     limit?: number;
     concurrency?: number;
     force: boolean;
+    resolveHostname?: CustomHttpResolveHostname;
 };
 export declare function runLocalCustomHttpColumn(table: string, columnKeyOrId: string, options: LocalColumnRunOptions): Promise<Record<string, unknown>>;
 export {};

package/dist/local-custom-http-column.js

@@ -1,6 +1,6 @@
 import { Buffer } from "node:buffer";
-import { isIP } from "node:net";
 import { OxygenError } from "@oxygen/shared";
+import { CustomHttpUrlSafetyError, assertCustomHttpPublicUrlSyntax, assertCustomHttpResolvedHostAllowed, } from "@oxygen/shared/custom-http-safety";
 import { requestOxygen } from "./http-client.js";
 const LOCAL_CUSTOM_HTTP_TIMEOUT_MS = 10_000;
 const LOCAL_CUSTOM_HTTP_MAX_RESPONSE_BYTES = 1_000_000;
@@ -28,11 +28,13 @@ export async function runLocalCustomHttpColumn(table, columnKeyOrId, options) {
         row,
         secrets,
         force: options.force,
+        ...(options.resolveHostname ? { resolveHostname: options.resolveHostname } : {}),
     }));
     const { completedCount, failedCount, skippedCount } = countLocalCustomHttpResults(results);
     return {
         status: localCustomHttpRunStatus({ completedCount, failedCount, skippedCount }),
         table: described.table ?? queried.table ?? null,
+        web_url: localCustomHttpTableWebUrl(table, described.table, queried.table),
         column,
         toolId: "custom_http",
         requestedRowCount: rows.length,
@@ -56,7 +58,7 @@ async function runLocalCustomHttpRow(input) {
         };
     }
     try {
-        const execution = await executeLocalCustomHttpColumn(input.definition, input.row, input.secrets);
+        const execution = await executeLocalCustomHttpColumn(input.definition, input.row, input.secrets, input.resolveHostname);
         return await persistLocalCustomHttpSuccess({ ...input, rowId, execution });
     }
     catch (error) {
@@ -145,6 +147,20 @@ function localFirstRowFields(first) {
         fields.run = first.run;
     return fields;
 }
+function localCustomHttpTableWebUrl(table, described, queried) {
+    const identifier = readLocalTableIdentifier(described) ?? readLocalTableIdentifier(queried) ?? table;
+    return `https://oxygen-agent.com/tables/${encodeURIComponent(identifier)}`;
+}
+function readLocalTableIdentifier(table) {
+    if (!isRecord(table))
+        return null;
+    for (const key of ["id", "slug", "key"]) {
+        const value = table[key];
+        if (typeof value === "string" && value.trim())
+            return value.trim();
+    }
+    return null;
+}
 function findLocalColumn(columns, columnKeyOrId) {
     const column = columns.find((entry) => entry.id === columnKeyOrId || entry.key === columnKeyOrId);
     if (!column) {
@@ -318,13 +334,13 @@ async function mapLocalConcurrent(values, concurrency, action) {
     }));
     return results;
 }
-async function executeLocalCustomHttpColumn(definition, row, secrets) {
+async function executeLocalCustomHttpColumn(definition, row, secrets, resolveHostname) {
     const prepared = prepareLocalCustomHttpRequest(definition, row, secrets);
-    const response = await fetchLocalCustomHttpResponse(prepared);
+    const response = await fetchLocalCustomHttpResponse(prepared, resolveHostname);
     return await readLocalCustomHttpExecution(response, prepared, definition.outputPath ?? null);
 }
 function prepareLocalCustomHttpRequest(definition, row, secrets) {
-    const secretValues = Object.values(secrets);
+    const secretValues = expandLocalSecretValues(secrets);
     const method = definition.request.method;
     const url = resolveLocalHttpUrl(definition.request.url, row, secrets, secretValues);
     const headers = resolveLocalHeaders(definition.request.headers ?? {}, row, secrets);
@@ -333,6 +349,27 @@ function prepareLocalCustomHttpRequest(definition, row, secrets) {
     const body = bodyValue === undefined ? undefined : serializeLocalHttpBody(bodyValue, headers);
     return { method, url, headers, bodyValue, body, secretValues };
 }
+function expandLocalSecretValues(secrets) {
+    const values = new Set();
+    for (const secret of Object.values(secrets)) {
+        if (!secret)
+            continue;
+        values.add(secret);
+        try {
+            values.add(encodeURIComponent(secret));
+        }
+        catch {
+            // Ignore values that cannot be URL-encoded.
+        }
+        try {
+            values.add(encodeURI(secret));
+        }
+        catch {
+            // Ignore values that cannot be URL-encoded.
+        }
+    }
+    return [...values];
+}
 function resolveLocalHttpUrl(template, row, secrets, secretValues) {
     const resolvedUrl = resolveLocalTemplateString(template, row, secrets, "request.url");
     if (typeof resolvedUrl === "string" && resolvedUrl.trim())
@@ -355,7 +392,8 @@ function assertLocalHttpBodyAllowed(method, bodyValue) {
         });
     }
 }
-async function fetchLocalCustomHttpResponse(prepared) {
+async function fetchLocalCustomHttpResponse(prepared, resolveHostname) {
+    await assertLocalResolvedHttpUrlAllowed(prepared, resolveHostname);
     return await fetch(prepared.url, {
         method: prepared.method,
         headers: prepared.headers,
@@ -371,6 +409,32 @@ async function fetchLocalCustomHttpResponse(prepared) {
         });
     });
 }
+async function assertLocalResolvedHttpUrlAllowed(prepared, resolveHostname) {
+    try {
+        await assertCustomHttpResolvedHostAllowed({
+            url: prepared.url,
+            ...(resolveHostname ? { resolveHostname } : {}),
+        });
+    }
+    catch (error) {
+        if (!(error instanceof CustomHttpUrlSafetyError))
+            throw error;
+        if (error.reason === "dns_lookup_failed") {
+            throw new OxygenError("custom_http_network_error", "Custom HTTP request failed before receiving a response.", {
+                details: {
+                    reason: redactLocalSecrets(error.message, prepared.secretValues),
+                },
+                exitCode: 1,
+            });
+        }
+        throw new OxygenError("invalid_column_run", "Custom HTTP request url is invalid.", {
+            details: {
+                reason: redactLocalSecrets(error.message, prepared.secretValues),
+            },
+            exitCode: 1,
+        });
+    }
+}
 async function readLocalCustomHttpExecution(response, prepared, outputPath) {
     assertLocalNoRedirect(response, prepared.secretValues);
     const responseBody = await readLocalHttpResponseBody(response, LOCAL_CUSTOM_HTTP_MAX_RESPONSE_BYTES);
@@ -435,111 +499,14 @@ function validateLocalHttpUrl(rawUrl, secretValues) {
     }
 }
 function validateLocalPublicHttpsUrl(parsed) {
-    if (parsed.protocol !== "https:")
-        throw new Error("Custom HTTP URLs must use https.");
-    if (parsed.username || parsed.password)
-        throw new Error("Custom HTTP URLs cannot contain username or password credentials.");
-    const host = normalizeLocalUrlHost(parsed.hostname);
-    if (isBlockedLocalCustomHttpHost(host))
-        throw new Error("Custom HTTP URL host is not allowed.");
-}
-function normalizeLocalUrlHost(hostname) {
-    const host = hostname.toLowerCase().replace(/\.+$/, "");
-    return host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
-}
-function isBlockedLocalCustomHttpHost(host) {
-    return host === "localhost"
-        || host.endsWith(".localhost")
-        || host === "metadata.google.internal"
-        || isBlockedLocalIpv4Address(host)
-        || isBlockedLocalIpv6Address(host);
-}
-function isBlockedLocalIpv4Address(host) {
-    const address = isIP(host) === 4 ? host : readLeadingLocalIpv4Label(host);
-    if (!address)
-        return false;
-    const parts = address.split(".").map((part) => Number(part));
-    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255))
-        return true;
-    const [a = 0, b = 0] = parts;
-    return a === 0
-        || a === 10
-        || a === 127
-        || (a === 169 && b === 254)
-        || (a === 172 && b >= 16 && b <= 31)
-        || (a === 192 && b === 168)
-        || (a === 100 && b >= 64 && b <= 127)
-        || (a === 192 && b === 0)
-        || (a === 198 && (b === 18 || b === 19))
-        || a >= 224;
-}
-function readLeadingLocalIpv4Label(host) {
-    const match = /^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})(?:\.|$)/.exec(host);
-    return match?.[1] ?? null;
-}
-function isBlockedLocalIpv6Address(host) {
-    if (isIP(host) !== 6)
-        return false;
-    const groups = expandLocalIpv6Groups(host);
-    if (!groups)
-        return true;
-    const mappedIpv4 = localIpv4FromIpv6(groups);
-    if (mappedIpv4 && isBlockedLocalIpv4Address(mappedIpv4))
-        return true;
-    const [first = 0, second = 0] = groups;
-    const isUnspecified = groups.every((group) => group === 0);
-    const isLoopback = groups.slice(0, 7).every((group) => group === 0) && groups[7] === 1;
-    return isUnspecified
-        || isLoopback
-        || (first & 0xfe00) === 0xfc00
-        || (first & 0xffc0) === 0xfe80
-        || (first & 0xff00) === 0xff00
-        || (first === 0x2001 && second === 0x0db8);
-}
-function expandLocalIpv6Groups(host) {
-    const address = host.toLowerCase();
-    const doubleColonParts = address.split("::");
-    if (doubleColonParts.length > 2)
-        return null;
-    const head = splitLocalIpv6Part(doubleColonParts[0] ?? "");
-    const tail = splitLocalIpv6Part(doubleColonParts[1] ?? "");
-    if (!head || !tail)
-        return null;
-    const fill = doubleColonParts.length === 2 ? 8 - head.length - tail.length : 0;
-    if (fill < 0)
-        return null;
-    const groups = doubleColonParts.length === 2
-        ? [...head, ...Array.from({ length: fill }, () => 0), ...tail]
-        : head;
-    return groups.length === 8 ? groups : null;
-}
-function splitLocalIpv6Part(part) {
-    if (!part)
-        return [];
-    const groups = part.split(":");
-    const values = [];
-    for (const group of groups) {
-        if (!/^[0-9a-f]{1,4}$/.test(group))
-            return null;
-        values.push(Number.parseInt(group, 16));
+    try {
+        assertCustomHttpPublicUrlSyntax(parsed);
+    }
+    catch (error) {
+        if (error instanceof CustomHttpUrlSafetyError)
+            throw new Error(error.message);
+        throw error;
     }
-    return values;
-}
-function localIpv4FromIpv6(groups) {
-    const mappedPrefix = groups.slice(0, 5).every((group) => group === 0) && groups[5] === 0xffff;
-    const compatiblePrefix = groups.slice(0, 6).every((group) => group === 0);
-    if (!mappedPrefix && !compatiblePrefix)
-        return null;
-    const high = groups[6] ?? 0;
-    const low = groups[7] ?? 0;
-    if (high === 0 && low === 0)
-        return null;
-    return [
-        high >> 8,
-        high & 0xff,
-        low >> 8,
-        low & 0xff,
-    ].join(".");
 }
 function resolveLocalHeaders(headers, row, secrets) {
     const resolved = {};

package/node_modules/@oxygen/shared/dist/custom-http-safety.d.ts

@@ -0,0 +1,18 @@
+export type CustomHttpResolvedAddress = {
+    address: string;
+    family?: number;
+};
+export type CustomHttpResolveHostname = (hostname: string) => Promise<CustomHttpResolvedAddress[]>;
+export type CustomHttpUrlSafetyErrorReason = "blocked_host" | "blocked_resolved_address" | "credentials" | "dns_lookup_failed" | "protocol";
+export declare class CustomHttpUrlSafetyError extends Error {
+    readonly reason: CustomHttpUrlSafetyErrorReason;
+    readonly details: Record<string, unknown>;
+    constructor(reason: CustomHttpUrlSafetyErrorReason, message: string, details?: Record<string, unknown>);
+}
+export declare function assertCustomHttpPublicUrlSyntax(url: string | URL): URL;
+export declare function assertCustomHttpResolvedHostAllowed(input: {
+    url: string | URL;
+    resolveHostname?: CustomHttpResolveHostname;
+}): Promise<void>;
+export declare function normalizeCustomHttpUrlHost(hostname: string): string;
+export declare function isBlockedCustomHttpHost(host: string): boolean;

package/node_modules/@oxygen/shared/dist/custom-http-safety.js

@@ -0,0 +1,162 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+export class CustomHttpUrlSafetyError extends Error {
+    reason;
+    details;
+    constructor(reason, message, details = {}) {
+        super(message);
+        this.name = "CustomHttpUrlSafetyError";
+        this.reason = reason;
+        this.details = details;
+    }
+}
+export function assertCustomHttpPublicUrlSyntax(url) {
+    const parsed = typeof url === "string" ? new URL(url) : url;
+    if (parsed.protocol !== "https:") {
+        throw new CustomHttpUrlSafetyError("protocol", "Custom HTTP URLs must use https.", {
+            url: safeUrlForDetails(parsed),
+        });
+    }
+    if (parsed.username || parsed.password) {
+        throw new CustomHttpUrlSafetyError("credentials", "Custom HTTP URLs cannot contain username or password credentials.", { url: safeUrlForDetails(parsed) });
+    }
+    const host = normalizeCustomHttpUrlHost(parsed.hostname);
+    if (isBlockedCustomHttpHost(host)) {
+        throw new CustomHttpUrlSafetyError("blocked_host", "Custom HTTP URL host is not allowed.", { host });
+    }
+    return parsed;
+}
+export async function assertCustomHttpResolvedHostAllowed(input) {
+    const parsed = assertCustomHttpPublicUrlSyntax(input.url);
+    const host = normalizeCustomHttpUrlHost(parsed.hostname);
+    if (isIP(host))
+        return;
+    const resolveHostname = input.resolveHostname ?? defaultResolveHostname;
+    let addresses;
+    try {
+        addresses = await resolveHostname(host);
+    }
+    catch (error) {
+        throw new CustomHttpUrlSafetyError("dns_lookup_failed", "Custom HTTP URL host could not be resolved.", {
+            host,
+            reason: error instanceof Error ? error.message : String(error),
+        });
+    }
+    if (addresses.length === 0) {
+        throw new CustomHttpUrlSafetyError("dns_lookup_failed", "Custom HTTP URL host did not resolve to any address.", {
+            host,
+        });
+    }
+    for (const address of addresses) {
+        const normalizedAddress = normalizeCustomHttpUrlHost(address.address);
+        if (isBlockedCustomHttpHost(normalizedAddress)) {
+            throw new CustomHttpUrlSafetyError("blocked_resolved_address", "Custom HTTP URL host resolved to a non-public address.", { host, address: normalizedAddress, family: address.family ?? null });
+        }
+    }
+}
+export function normalizeCustomHttpUrlHost(hostname) {
+    const host = hostname.toLowerCase().replace(/\.+$/, "");
+    return host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+}
+export function isBlockedCustomHttpHost(host) {
+    return host === "localhost"
+        || host.endsWith(".localhost")
+        || host === "metadata.google.internal"
+        || isBlockedCustomHttpIpv4Address(host)
+        || isBlockedCustomHttpIpv6Address(host);
+}
+function safeUrlForDetails(parsed) {
+    return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+}
+async function defaultResolveHostname(hostname) {
+    return await lookup(hostname, { all: true, verbatim: true });
+}
+function isBlockedCustomHttpIpv4Address(host) {
+    const address = isIP(host) === 4 ? host : readLeadingCustomHttpIpv4Label(host);
+    if (!address)
+        return false;
+    const parts = address.split(".").map((part) => Number(part));
+    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255))
+        return true;
+    const [a = 0, b = 0, c = 0] = parts;
+    return a === 0
+        || a === 10
+        || a === 127
+        || (a === 169 && b === 254)
+        || (a === 172 && b >= 16 && b <= 31)
+        || (a === 192 && b === 168)
+        || (a === 100 && b >= 64 && b <= 127)
+        || (a === 192 && b === 0)
+        || (a === 198 && (b === 18 || b === 19))
+        || (a === 198 && b === 51 && c === 100)
+        || (a === 203 && b === 0 && c === 113)
+        || a >= 224;
+}
+function readLeadingCustomHttpIpv4Label(host) {
+    const match = /^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})(?:\.|$)/.exec(host);
+    return match?.[1] ?? null;
+}
+function isBlockedCustomHttpIpv6Address(host) {
+    if (isIP(host) !== 6)
+        return false;
+    const groups = expandCustomHttpIpv6Groups(host);
+    if (!groups)
+        return true;
+    const mappedIpv4 = customHttpIpv4FromIpv6(groups);
+    if (mappedIpv4 && isBlockedCustomHttpIpv4Address(mappedIpv4))
+        return true;
+    const [first = 0, second = 0] = groups;
+    const isUnspecified = groups.every((group) => group === 0);
+    const isLoopback = groups.slice(0, 7).every((group) => group === 0) && groups[7] === 1;
+    return isUnspecified
+        || isLoopback
+        || (first & 0xfe00) === 0xfc00
+        || (first & 0xffc0) === 0xfe80
+        || (first & 0xff00) === 0xff00
+        || (first === 0x2001 && second === 0x0db8);
+}
+function expandCustomHttpIpv6Groups(host) {
+    const address = host.toLowerCase();
+    const doubleColonParts = address.split("::");
+    if (doubleColonParts.length > 2)
+        return null;
+    const head = splitCustomHttpIpv6Part(doubleColonParts[0] ?? "");
+    const tail = splitCustomHttpIpv6Part(doubleColonParts[1] ?? "");
+    if (!head || !tail)
+        return null;
+    const fill = doubleColonParts.length === 2 ? 8 - head.length - tail.length : 0;
+    if (fill < 0)
+        return null;
+    const groups = doubleColonParts.length === 2
+        ? [...head, ...Array.from({ length: fill }, () => 0), ...tail]
+        : head;
+    return groups.length === 8 ? groups : null;
+}
+function splitCustomHttpIpv6Part(part) {
+    if (!part)
+        return [];
+    const groups = part.split(":");
+    const values = [];
+    for (const group of groups) {
+        if (!/^[0-9a-f]{1,4}$/.test(group))
+            return null;
+        values.push(Number.parseInt(group, 16));
+    }
+    return values;
+}
+function customHttpIpv4FromIpv6(groups) {
+    const mappedPrefix = groups.slice(0, 5).every((group) => group === 0) && groups[5] === 0xffff;
+    const compatiblePrefix = groups.slice(0, 6).every((group) => group === 0);
+    if (!mappedPrefix && !compatiblePrefix)
+        return null;
+    const high = groups[6] ?? 0;
+    const low = groups[7] ?? 0;
+    if (high === 0 && low === 0)
+        return null;
+    return [
+        high >> 8,
+        high & 0xff,
+        low >> 8,
+        low & 0xff,
+    ].join(".");
+}

package/node_modules/@oxygen/shared/dist/email-unsubscribe-token.js

@@ -14,31 +14,21 @@ export function signUnsubscribeToken(payload, secret) {
     const signature = createHmac("sha256", secret).update(body).digest("base64url");
     return `${body}.${signature}`;
 }
-/**
- * Verify a token's signature (constant-time) and shape. Returns the payload only
- * when the signature matches AND it is a well-formed v1 payload with a non-empty
- * org + a plausible email; returns null on ANY problem (bad shape, wrong/blank
- * secret, tampered body, replayed garbage). Pure: the route maps null -> 401.
- */
-export function verifyUnsubscribeToken(token, secret) {
-    if (typeof token !== "string" || typeof secret !== "string" || !secret)
-        return null;
-    const dot = token.indexOf(".");
-    if (dot <= 0 || dot === token.length - 1)
-        return null;
-    const body = token.slice(0, dot);
-    const providedSig = token.slice(dot + 1);
+/** Constant-time HMAC-SHA256 check; false on any error (bad base64, length mismatch). */
+function verifySignature(body, providedSig, secret) {
     const expected = createHmac("sha256", secret).update(body).digest();
     let provided;
     try {
         provided = Buffer.from(providedSig, "base64url");
     }
     catch {
-        return null;
+        return false;
     }
     // Equal-length guard before timingSafeEqual (it throws on length mismatch).
-    if (provided.length !== expected.length || !timingSafeEqual(provided, expected))
-        return null;
+    return provided.length === expected.length && timingSafeEqual(provided, expected);
+}
+/** Decode and validate the base64url body; returns typed payload or null on any problem. */
+function parseTokenPayload(body) {
     let parsed;
     try {
         parsed = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
@@ -65,6 +55,24 @@ export function verifyUnsubscribeToken(token, secret) {
         iat: typeof candidate.iat === "number" && Number.isFinite(candidate.iat) ? candidate.iat : 0,
     };
 }
+/**
+ * Verify a token's signature (constant-time) and shape. Returns the payload only
+ * when the signature matches AND it is a well-formed v1 payload with a non-empty
+ * org + a plausible email; returns null on ANY problem (bad shape, wrong/blank
+ * secret, tampered body, replayed garbage). Pure: the route maps null -> 401.
+ */
+export function verifyUnsubscribeToken(token, secret) {
+    if (typeof token !== "string" || typeof secret !== "string" || !secret)
+        return null;
+    const dot = token.indexOf(".");
+    if (dot <= 0 || dot === token.length - 1)
+        return null;
+    const body = token.slice(0, dot);
+    const providedSig = token.slice(dot + 1);
+    if (!verifySignature(body, providedSig, secret))
+        return null;
+    return parseTokenPayload(body);
+}
 /**
  * The HMAC signing secret for unsubscribe tokens, or null when unset. The send
  * path treats null as "omit the header" (a send with no one-click link still

package/node_modules/@oxygen/shared/dist/sequences.d.ts

@@ -37,6 +37,17 @@ export type SequenceChannel = (typeof SEQUENCE_CHANNELS)[number];
  */
 export declare const SEQUENCE_SIGNALS: readonly ["linkedin_connected", "linkedin_replied", "email_sent", "email_opened", "email_clicked", "email_replied", "email_bounced", "company_hiring", "company_raised_funds", "job_change", "new_hire", "web_visit", "intent"];
 export type SequenceSignal = (typeof SEQUENCE_SIGNALS)[number];
+/**
+ * Email engagement signals that ONLY arrive via the Instantly webhook
+ * (email_opened/email_clicked). Native email sends (Gmail API / Microsoft Graph)
+ * produce no open/click tracking, so a sequence that sends email natively can
+ * never accumulate these — gating a wait_for_signal or signal-branch on them
+ * silently always times out / always takes the else arm. validateSequenceDefinition
+ * rejects that misconfiguration. (email_replied/email_bounced DO arrive natively
+ * via the inbound-message + bounce paths, so they are not listed here.)
+ */
+export declare const SEQUENCE_NATIVE_UNTRACKED_SIGNALS: readonly ["email_opened", "email_clicked"];
+export type SequenceNativeUntrackedSignal = (typeof SEQUENCE_NATIVE_UNTRACKED_SIGNALS)[number];
 /** External GTM signals (the non-engagement subset of SEQUENCE_SIGNALS). */
 export declare const SEQUENCE_EXTERNAL_SIGNALS: readonly ["company_hiring", "company_raised_funds", "job_change", "new_hire", "web_visit", "intent"];
 export type SequenceExternalSignal = (typeof SEQUENCE_EXTERNAL_SIGNALS)[number];

package/node_modules/@oxygen/shared/dist/sequences.js

@@ -58,6 +58,19 @@ export const SEQUENCE_SIGNALS = [
     "web_visit",
     "intent",
 ];
+/**
+ * Email engagement signals that ONLY arrive via the Instantly webhook
+ * (email_opened/email_clicked). Native email sends (Gmail API / Microsoft Graph)
+ * produce no open/click tracking, so a sequence that sends email natively can
+ * never accumulate these — gating a wait_for_signal or signal-branch on them
+ * silently always times out / always takes the else arm. validateSequenceDefinition
+ * rejects that misconfiguration. (email_replied/email_bounced DO arrive natively
+ * via the inbound-message + bounce paths, so they are not listed here.)
+ */
+export const SEQUENCE_NATIVE_UNTRACKED_SIGNALS = ["email_opened", "email_clicked"];
+function isNativeUntrackedSignal(value) {
+    return SEQUENCE_NATIVE_UNTRACKED_SIGNALS.includes(value);
+}
 /** External GTM signals (the non-engagement subset of SEQUENCE_SIGNALS). */
 export const SEQUENCE_EXTERNAL_SIGNALS = [
     "company_hiring",
@@ -228,6 +241,14 @@ export function validateSequenceDefinition(input, options = {}) {
             }
         }
     });
+    // Pass 3: native-email engagement-gate guard. Native email sends produce no
+    // open/click signals (email_opened/email_clicked arrive only from the Instantly
+    // webhook). A sequence that sends email natively — has native email steps
+    // (email_send/email_reply) and is NOT delegated to an Instantly campaign (no
+    // email_enroll/email_move/email_stop steps) — that gates a wait_for_signal or
+    // signal-branch on those signals would silently always time out / always take
+    // the else arm. Reject it at write time so create/update report the dead gate.
+    reportNativeEngagementGates(normalized, issues);
     if (issues.length > 0) {
         throw new OxygenError("invalid_sequence", `Sequence definition is invalid: ${issues.map((i) => `${i.path}: ${i.message}`).join("; ")}`, { details: { issues }, exitCode: 1 });
     }
@@ -248,6 +269,52 @@ export function lintSequenceDefinition(input, options = {}) {
         return [{ path: "steps", message: error instanceof Error ? error.message : "Invalid sequence." }];
     }
 }
+/**
+ * Push an issue for every wait_for_signal / signal-branch that gates on a
+ * natively-untracked engagement signal (email_opened/email_clicked) inside a
+ * sequence that sends email natively. "Native email" = at least one
+ * email_send/email_reply step and NO Instantly-delegated email step
+ * (email_enroll/email_move/email_stop); an Instantly-bound sequence DOES receive
+ * those webhook signals, so it is left alone. Mutates `issues` in place.
+ */
+function reportNativeEngagementGates(steps, issues) {
+    const hasNativeEmail = steps.some((s) => s.kind === "email_send" || s.kind === "email_reply");
+    const hasInstantlyEmail = steps.some((s) => s.kind === "email_enroll" || s.kind === "email_move" || s.kind === "email_stop");
+    if (!hasNativeEmail || hasInstantlyEmail)
+        return;
+    steps.forEach((step, index) => {
+        if (step.kind === "wait_for_signal" && isNativeUntrackedSignal(step.signal)) {
+            issues.push({
+                path: `steps[${index}].signal`,
+                message: `step '${step.id}' waits for '${step.signal}', but this sequence sends email natively (no Instantly binding), which produces no open/click signals — the gate would always time out. Use email_replied/email_bounced, or bind an Instantly campaign to track opens/clicks.`,
+            });
+            return;
+        }
+        if (step.kind === "branch" && typeof step.condition !== "string") {
+            const referenced = new Set();
+            collectConditionSignals(step.condition, referenced);
+            for (const signal of SEQUENCE_NATIVE_UNTRACKED_SIGNALS) {
+                if (referenced.has(signal)) {
+                    issues.push({
+                        path: `steps[${index}].condition`,
+                        message: `step '${step.id}' branches on '${signal}', but this sequence sends email natively (no Instantly binding), which produces no open/click signals — the branch would always take the else arm. Use email_replied/email_bounced, or bind an Instantly campaign to track opens/clicks.`,
+                    });
+                }
+            }
+        }
+    });
+}
+/** Collect every signal name referenced anywhere in a signal-branch condition. */
+function collectConditionSignals(condition, out) {
+    if ("signal" in condition)
+        out.add(condition.signal);
+    else if ("all" in condition)
+        condition.all.forEach((c) => collectConditionSignals(c, out));
+    else if ("any" in condition)
+        condition.any.forEach((c) => collectConditionSignals(c, out));
+    else
+        collectConditionSignals(condition.not, out);
+}
 function collectSteps(input, issues) {
     const record = isRecord(input) ? input : null;
     const steps = record?.steps;
@@ -774,18 +841,13 @@ function normalizeVariants(raw, path, fields, issues) {
     });
     return out.length > 0 ? out : undefined;
 }
-function normalizeSendWindow(raw, path, issues) {
-    if (raw === undefined || raw === null)
-        return undefined;
-    if (!isRecord(raw)) {
-        issues.push({ path, message: "send_window must be an object." });
-        return undefined;
-    }
+function normalizeSendWindowConfiguredTimezone(raw, path, issues) {
     const timezone = typeof raw.timezone === "string" && raw.timezone.trim() ? raw.timezone.trim() : undefined;
     if (!timezone)
         issues.push({ path: `${path}.timezone`, message: "timezone (IANA, e.g. America/New_York) is required." });
-    const start = normalizeHhmm(raw.start, `${path}.start`, issues);
-    const end = normalizeHhmm(raw.end, `${path}.end`, issues);
+    return timezone ?? "UTC";
+}
+function validateSendWindowBounds(start, end, path, issues) {
     // A zero-width window (start === end) is never open — isWithinSendWindow
     // returns false for every instant — so a step carrying it defers
     // (outside_send_window) on every dispatch and the enrollment silently stalls
@@ -794,7 +856,8 @@ function normalizeSendWindow(raw, path, issues) {
     if (start !== undefined && end !== undefined && hhmmToMinutes(start) === hhmmToMinutes(end)) {
         issues.push({ path: `${path}.end`, message: "must differ from start — a zero-width send_window never sends." });
     }
-    const days = normalizeWeekdays(raw.days, `${path}.days`, issues);
+}
+function normalizeSendWindowTimezoneMode(raw, path, issues) {
     const mode = raw.timezone_mode === "recipient" ? "recipient" : "fixed";
     const column = mode === "recipient"
         ? optionalString(raw.recipient_timezone_column, `${path}.recipient_timezone_column`, issues)
@@ -802,8 +865,23 @@ function normalizeSendWindow(raw, path, issues) {
     if (mode === "recipient" && !column) {
         issues.push({ path: `${path}.recipient_timezone_column`, message: 'recipient_timezone_column is required when timezone_mode is "recipient".' });
     }
+    return { mode, column };
+}
+function normalizeSendWindow(raw, path, issues) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isRecord(raw)) {
+        issues.push({ path, message: "send_window must be an object." });
+        return undefined;
+    }
+    const timezone = normalizeSendWindowConfiguredTimezone(raw, path, issues);
+    const start = normalizeHhmm(raw.start, `${path}.start`, issues);
+    const end = normalizeHhmm(raw.end, `${path}.end`, issues);
+    validateSendWindowBounds(start, end, path, issues);
+    const days = normalizeWeekdays(raw.days, `${path}.days`, issues);
+    const { mode, column } = normalizeSendWindowTimezoneMode(raw, path, issues);
     return {
-        timezone: timezone ?? "UTC",
+        timezone,
         ...(days ? { days } : {}),
         start: start ?? "09:00",
         end: end ?? "17:00",