@huskly/ibkr-client 1.6.0 → 2.0.0

package/dist/ibkr/ibkrClient.js

@@ -99,6 +99,11 @@ function parseRetryAfter(raw, now) {
 function isUnknownRecord(input) {
     return typeof input === "object" && input !== null && !Array.isArray(input);
 }
+function isBrokerageSessionInput(input) {
+    return (isUnknownRecord(input) &&
+        typeof input["compete"] === "boolean" &&
+        typeof input["publish"] === "boolean");
+}
 /**
  * Every distinct listing of an exact symbol that carries a section of one asset class (#671).
  *
@@ -410,6 +415,9 @@ export class IbkrInsufficientHistoryError extends Error {
 export class IbkrClient {
     raw;
     initPromise;
+    logoutPromise;
+    closed = false;
+    accountCriticalSectionTail = Promise.resolve();
     accountIdPromise;
     optionDiscovery = new Map();
     optionDefinitionCache;
@@ -441,125 +449,194 @@ export class IbkrClient {
                 : { onTelemetry: options.onRequestTelemetry }),
         });
     }
-    /** Obtain the live session token (idempotent — safe to await repeatedly). */
-    init() {
-        this.initPromise ??= (async () => {
-            try {
-                await this.raw.init();
-            }
-            catch (error) {
-                throw this.normalizeHttpError(error);
-            }
-            // IBKR is slow right after init; give the session a moment to settle.
-            await this.wait(1000);
-        })();
+    /**
+     * Obtain the live session token with the legacy competing-session behavior.
+     *
+     * @deprecated Use {@link initializeBrokerageSession} with explicit flags.
+     */
+    async init() {
+        this.assertOpen();
+        this.initPromise ??= this.initializeBrokerageSession({ compete: true, publish: true });
         return this.initPromise;
     }
+    async initializeBrokerageSession(input) {
+        this.assertOpen();
+        const rawInput = input;
+        if (!isBrokerageSessionInput(rawInput)) {
+            throw new TypeError("IBKR brokerage session initialization flags must be exact booleans");
+        }
+        try {
+            await this.raw.init(rawInput.compete, rawInput.publish);
+        }
+        catch (error) {
+            throw this.normalizeHttpError(error);
+        }
+        // IBKR is slow right after initialization; give the session a moment to settle.
+        await this.wait(1000);
+    }
+    async renewBrokerageSession(input) {
+        this.assertOpen();
+        const rawInput = input;
+        if (!isBrokerageSessionInput(rawInput) || rawInput.compete) {
+            throw new TypeError("IBKR brokerage session renewal requires compete false and an exact publish boolean");
+        }
+        try {
+            await this.raw.init(false, rawInput.publish);
+        }
+        catch (error) {
+            throw this.normalizeHttpError(error);
+        }
+        await this.wait(1000);
+    }
+    async getSessionEvidence() {
+        this.assertOpen();
+        const [status, rawAccounts] = await Promise.all([
+            this.getAuthStatus(),
+            this.req({ path: "iserver/accounts" }),
+        ]);
+        const accounts = isUnknownRecord(rawAccounts) ? rawAccounts : {};
+        return {
+            authenticated: status.authenticated,
+            competing: status.competing,
+            connected: status.connected,
+            accountIds: this.accountIdsOrNull(accounts["accounts"]),
+            selectedAccountId: typeof accounts["selectedAccount"] === "string" ? accounts["selectedAccount"] : null,
+            isPaper: this.booleanOrNull(accounts["isPaper"]),
+        };
+    }
+    async tickle() {
+        this.assertOpen();
+        await this.req({ path: "tickle", method: "POST" });
+    }
+    async logout() {
+        this.assertOpen();
+        this.logoutPromise ??= this.singleAttemptRequest({
+            path: "logout",
+            method: "POST",
+        }).then(() => undefined);
+        return this.logoutPromise;
+    }
+    close() {
+        if (this.closed)
+            return Promise.resolve();
+        this.closed = true;
+        delete this.accountIdPromise;
+        this.optionDiscovery.clear();
+        this.optionContractResolution.clear();
+        this.priceHistoryContractResolution.clear();
+        this.derivativeDiscovery.clear();
+        return Promise.resolve();
+    }
     async getAuthStatus() {
-        const status = await this.req({
+        this.assertOpen();
+        const rawStatus = await this.req({
             path: "iserver/auth/status",
             method: "POST",
         });
+        const status = isUnknownRecord(rawStatus) ? rawStatus : {};
         return {
-            authenticated: status.authenticated ?? false,
-            competing: status.competing ?? false,
+            authenticated: this.booleanOrNull(status["authenticated"]),
+            competing: this.booleanOrNull(status["competing"]),
+            connected: this.booleanOrNull(status["connected"]),
         };
     }
     async getTradingDiagnostics(accountId) {
+        this.assertOpen();
         if (!accountId.trim())
             throw new Error("An explicit IBKR account ID is required");
-        const [status, accounts] = await Promise.all([
+        const [status, rawAccounts] = await Promise.all([
             this.getAuthStatus(),
             this.req({ path: "iserver/accounts" }),
         ]);
-        if (!accounts.accounts?.includes(accountId)) {
+        const accounts = isUnknownRecord(rawAccounts) ? rawAccounts : {};
+        const accountIds = this.accountIdsOrNull(accounts["accounts"]);
+        if (!accountIds?.includes(accountId)) {
             throw new Error(`IBKR account ${accountId} is not available to this session`);
         }
+        const rawFeatures = accounts["allowFeatures"];
+        const features = isUnknownRecord(rawFeatures) ? rawFeatures : {};
+        const rawAssetTypes = features["allowedAssetTypes"];
         return {
             accountId,
-            selectedAccountId: accounts.selectedAccount ?? null,
-            environment: accounts.isPaper === true ? "paper" : "live",
+            selectedAccountId: typeof accounts["selectedAccount"] === "string" ? accounts["selectedAccount"] : null,
+            environment: accounts["isPaper"] === true ? "paper" : accounts["isPaper"] === false ? "live" : null,
             authenticated: status.authenticated,
+            connected: status.connected,
             competingSession: status.competing,
-            marketDataAvailable: accounts.allowFeatures?.showGFIS ?? null,
-            advisoryAssetPermissions: accounts.allowFeatures?.allowedAssetTypes
-                ?.split(",")
-                .map((value) => value.trim())
-                .filter(Boolean) ?? [],
+            marketDataAvailable: this.booleanOrNull(features["showGFIS"]),
+            advisoryAssetPermissions: typeof rawAssetTypes === "string"
+                ? rawAssetTypes
+                    .split(",")
+                    .map((value) => value.trim())
+                    .filter(Boolean)
+                : [],
         };
     }
     async previewDerivativeCombo(request) {
+        this.assertOpen();
         this.validateComboPreview(request);
-        const diagnostics = await this.getTradingDiagnostics(request.accountId);
-        if (!diagnostics.authenticated || diagnostics.competingSession) {
-            throw new Error("IBKR brokerage session is not safely authenticated for What-If");
-        }
-        await this.prepareBrokerageAccount(request.accountId);
-        const conids = request.legs.map(({ contract }) => contract.conid).join(",");
-        await this.req({
-            path: "iserver/marketdata/snapshot",
-            params: { conids, fields: "6509" },
-        });
-        const response = await this.singleAttemptRequest({
-            path: `iserver/account/${request.accountId}/orders/whatif`,
-            method: "POST",
-            data: {
-                orders: [this.comboOrderTicket(request)],
-            },
+        return this.withTradingMutation(request.accountId, "IBKR brokerage session is not safely authenticated for What-If", async (diagnostics) => {
+            const conids = request.legs.map(({ contract }) => contract.conid).join(",");
+            await this.req({
+                path: "iserver/marketdata/snapshot",
+                params: { conids, fields: "6509" },
+            });
+            const response = await this.singleAttemptRequest({
+                path: `iserver/account/${request.accountId}/orders/whatif`,
+                method: "POST",
+                data: { orders: [this.comboOrderTicket(request)] },
+            });
+            return this.normalizeComboPreview(request.accountId, diagnostics, response);
         });
-        return this.normalizeComboPreview(request.accountId, diagnostics, response);
     }
     async submitDerivativeCombo(request) {
+        this.assertOpen();
         this.validateComboPreview(request);
         if (!request.clientOrderId.trim() || request.clientOrderId.length > 64) {
             throw new Error("Client order ID must contain 1 to 64 characters");
         }
         const cmeOperatorMetadata = this.cmeOperatorMetadata(request.legs[0].contract.assetClass, request);
-        const diagnostics = await this.getTradingDiagnostics(request.accountId);
-        if (!diagnostics.authenticated || diagnostics.competingSession) {
-            throw new Error("IBKR brokerage session is not safely authenticated for submission");
-        }
-        await this.prepareBrokerageAccount(request.accountId);
-        const response = await this.singleAttemptRequest({
-            path: `iserver/account/${request.accountId}/orders`,
-            method: "POST",
-            data: {
-                orders: [
-                    {
-                        ...this.comboOrderTicket(request),
-                        cOID: request.clientOrderId,
-                        ...cmeOperatorMetadata,
-                    },
-                ],
-            },
+        return this.withTradingMutation(request.accountId, "IBKR brokerage session is not safely authenticated for submission", async () => {
+            const response = await this.singleAttemptRequest({
+                path: `iserver/account/${request.accountId}/orders`,
+                method: "POST",
+                data: {
+                    orders: [
+                        {
+                            ...this.comboOrderTicket(request),
+                            cOID: request.clientOrderId,
+                            ...cmeOperatorMetadata,
+                        },
+                    ],
+                },
+            });
+            return this.normalizeOrderSubmission(response, request.clientOrderId);
         });
-        return this.normalizeOrderSubmission(response, request.clientOrderId);
     }
     async submitDerivativeSingleOrder(request) {
+        this.assertOpen();
         this.validateSingleOrder(request);
         const cmeOperatorMetadata = this.cmeOperatorMetadata(request.contract.assetClass, request);
-        const diagnostics = await this.getTradingDiagnostics(request.accountId);
-        if (!diagnostics.authenticated || diagnostics.competingSession) {
-            throw new Error("IBKR brokerage session is not safely authenticated for submission");
-        }
-        await this.prepareBrokerageAccount(request.accountId);
-        const response = await this.singleAttemptRequest({
-            path: `iserver/account/${request.accountId}/orders`,
-            method: "POST",
-            data: {
-                orders: [
-                    {
-                        ...this.singleOrderTicket(request),
-                        ...(request.clientOrderId !== undefined ? { cOID: request.clientOrderId } : {}),
-                        ...(request.parentId !== undefined ? { parentId: request.parentId } : {}),
-                        ...cmeOperatorMetadata,
-                    },
-                ],
-            },
+        return this.withTradingMutation(request.accountId, "IBKR brokerage session is not safely authenticated for submission", async () => {
+            const response = await this.singleAttemptRequest({
+                path: `iserver/account/${request.accountId}/orders`,
+                method: "POST",
+                data: {
+                    orders: [
+                        {
+                            ...this.singleOrderTicket(request),
+                            ...(request.clientOrderId !== undefined ? { cOID: request.clientOrderId } : {}),
+                            ...(request.parentId !== undefined ? { parentId: request.parentId } : {}),
+                            ...cmeOperatorMetadata,
+                        },
+                    ],
+                },
+            });
+            return this.normalizeOrderSubmission(response, request.clientOrderId ?? null);
         });
-        return this.normalizeOrderSubmission(response, request.clientOrderId ?? null);
     }
     async submitDerivativeContingentOrders(request) {
+        this.assertOpen();
         const { accountId, parent, child } = request;
         if (!accountId.trim())
             throw new Error("An explicit IBKR account ID is required");
@@ -578,64 +655,58 @@ export class IbkrClient {
         }
         const parentMetadata = this.cmeOperatorMetadata(parent.contract.assetClass, parent);
         const childMetadata = this.cmeOperatorMetadata(child.contract.assetClass, child);
-        const diagnostics = await this.getTradingDiagnostics(accountId);
-        if (!diagnostics.authenticated || diagnostics.competingSession) {
-            throw new Error("IBKR brokerage session is not safely authenticated for submission");
-        }
-        await this.prepareBrokerageAccount(accountId);
-        const response = await this.singleAttemptRequest({
-            path: `iserver/account/${accountId}/orders`,
-            method: "POST",
-            data: {
-                orders: [
-                    {
-                        ...this.singleOrderTicket(parent),
-                        cOID: parent.clientOrderId,
-                        ...parentMetadata,
-                    },
-                    {
-                        ...this.singleOrderTicket(child),
-                        parentId: parent.clientOrderId,
-                        ...childMetadata,
-                    },
-                ],
-            },
+        return this.withTradingMutation(accountId, "IBKR brokerage session is not safely authenticated for submission", async () => {
+            const response = await this.singleAttemptRequest({
+                path: `iserver/account/${accountId}/orders`,
+                method: "POST",
+                data: {
+                    orders: [
+                        {
+                            ...this.singleOrderTicket(parent),
+                            cOID: parent.clientOrderId,
+                            ...parentMetadata,
+                        },
+                        {
+                            ...this.singleOrderTicket(child),
+                            parentId: parent.clientOrderId,
+                            ...childMetadata,
+                        },
+                    ],
+                },
+            });
+            return this.normalizeMultiOrderSubmission(response, parent.clientOrderId, accountId);
         });
-        return this.normalizeMultiOrderSubmission(response, parent.clientOrderId);
     }
     async submitDerivativeOrderGraph(request) {
+        this.assertOpen();
         this.validateOrderGraph(request);
-        const diagnostics = await this.getTradingDiagnostics(request.accountId);
-        if (!diagnostics.authenticated || diagnostics.competingSession) {
-            throw new Error("IBKR brokerage session is not safely authenticated for submission");
-        }
-        await this.prepareBrokerageAccount(request.accountId);
-        const response = await this.singleAttemptRequest({
-            path: `iserver/account/${request.accountId}/orders`,
-            method: "POST",
-            data: { orders: request.nodes.map((node) => this.graphOrderTicket(request, node)) },
+        return this.withTradingMutation(request.accountId, "IBKR brokerage session is not safely authenticated for submission", async () => {
+            const response = await this.singleAttemptRequest({
+                path: `iserver/account/${request.accountId}/orders`,
+                method: "POST",
+                data: { orders: request.nodes.map((node) => this.graphOrderTicket(request, node)) },
+            });
+            return this.normalizeOrderGraphSubmission(response, request, []);
         });
-        return this.normalizeOrderGraphSubmission(response, request, []);
     }
     async acknowledgeDerivativeOrderGraphWarning(input) {
+        this.assertOpen();
         if (input.confirmed !== true)
             throw new Error("Order warning confirmation must be true");
         this.validateOrderGraph(input.continuation.request);
         if (!input.continuation.replyId.trim())
             throw new Error("An exact warning reply ID is required");
-        const diagnostics = await this.getTradingDiagnostics(input.continuation.request.accountId);
-        if (!diagnostics.authenticated || diagnostics.competingSession) {
-            throw new Error("IBKR brokerage session is not safely authenticated for submission");
-        }
-        await this.prepareBrokerageAccount(input.continuation.request.accountId);
-        const response = await this.singleAttemptRequest({
-            path: `iserver/reply/${encodeURIComponent(input.continuation.replyId)}`,
-            method: "POST",
-            data: { confirmed: true },
+        return this.withTradingMutation(input.continuation.request.accountId, "IBKR brokerage session is not safely authenticated for submission", async () => {
+            const response = await this.singleAttemptRequest({
+                path: `iserver/reply/${encodeURIComponent(input.continuation.replyId)}`,
+                method: "POST",
+                data: { confirmed: true },
+            });
+            return this.normalizeOrderGraphSubmission(response, input.continuation.request, input.continuation.members);
         });
-        return this.normalizeOrderGraphSubmission(response, input.continuation.request, input.continuation.members);
     }
     async recoverDerivativeOrderGraph(input, request) {
+        this.assertOpen();
         this.validateOrderGraph(request);
         if (input.accountId !== request.accountId)
             throw new Error("Graph recovery account does not match request");
@@ -646,138 +717,140 @@ export class IbkrClient {
         if (input.orderId !== undefined && !input.orderId.trim()) {
             throw new Error("An exact broker order ID is required for graph recovery");
         }
-        await this.prepareBrokerageAccount(input.accountId);
-        const response = await this.req({
-            path: "iserver/account/orders",
-            params: { accountId: input.accountId },
-        });
-        const flattenedActiveSnapshot = this.resolveFlattenedGraphParentAliases(request, this.flattenCompleteOrderSnapshot(response));
-        const activeSnapshotIncomplete = flattenedActiveSnapshot === null;
-        const invalidActiveAccountEvidence = flattenedActiveSnapshot?.some(({ order }) => !this.orderHasExactAccount(order, input.accountId)) ?? false;
-        const invalidNestedActiveEvidence = flattenedActiveSnapshot?.some(({ order, nestedParent }) => nestedParent !== null &&
-            !this.recoveryGraphOrderMayBeAttached(request, order) &&
-            this.recoveryGraphOrderIsAttached(request, nestedParent)) ?? false;
-        const accountOrders = (flattenedActiveSnapshot ?? [])
-            .map(({ order }) => order)
-            .filter((order) => this.orderHasExactAccount(order, input.accountId));
-        const activeMatchesByMember = new Map();
-        const knownActiveOrders = accountOrders.filter((order) => input.orderId !== undefined && this.recoveryOrderId(order) === input.orderId);
-        const conflictingKnownActiveOrders = knownActiveOrders.filter((order) => !this.recoveryGraphOrderMayBeAttached(request, order));
-        const observedCandidates = activeSnapshotIncomplete || invalidActiveAccountEvidence || invalidNestedActiveEvidence
-            ? [response]
-            : [...conflictingKnownActiveOrders];
-        observedCandidates.push(...accountOrders.filter((order) => this.recoveryGraphOrderMayBeAttached(request, order)));
-        for (const node of request.nodes) {
-            const matches = accountOrders.filter((order) => this.terminalOrderTicketIsValid(order) &&
-                this.orderHasValidRecoveryStatus(order) &&
-                this.recoveryOrderMatchesGraphNode(request, node, order));
-            activeMatchesByMember.set(node.memberId, matches);
-        }
-        const selected = new Map();
-        const usedOrderIds = new Set();
-        for (const node of request.nodes) {
-            const matches = activeMatchesByMember.get(node.memberId) ?? [];
-            const [match] = matches;
-            if (matches.length !== 1 || match === undefined)
-                continue;
-            const orderId = this.recoveryOrderId(match);
-            if (orderId === undefined)
-                continue;
-            if (usedOrderIds.has(orderId))
-                continue;
-            usedOrderIds.add(orderId);
-            selected.set(node.memberId, match);
-        }
-        const unresolved = request.nodes.filter((node) => !selected.has(node.memberId));
-        const terminalEvidence = await this.findRecoveryGraphTerminalCandidates(input.accountId, request, input.orderId);
-        const conflictingKnownActiveTickets = knownActiveOrders.filter((activeOrder) => terminalEvidence.linkedOrders.some((terminalOrder) => this.recoveryOrderId(terminalOrder) === input.orderId &&
-            this.terminalOrderTicketConflicts(activeOrder, terminalOrder)));
-        this.reconcileSelectedGraphMembers(request, selected, terminalEvidence);
-        if (unresolved.length > 0) {
-            const assignments = this.assignRecoveryGraphCandidates(unresolved, terminalEvidence.byNode, usedOrderIds);
-            for (const node of unresolved) {
-                const order = assignments.get(node.memberId);
-                if (order === undefined)
+        return this.withAccountCriticalSection(async () => {
+            await this.prepareBrokerageAccount(input.accountId);
+            const response = await this.req({
+                path: "iserver/account/orders",
+                params: { accountId: input.accountId },
+            });
+            const flattenedActiveSnapshot = this.resolveFlattenedGraphParentAliases(request, this.flattenCompleteOrderSnapshot(response));
+            const activeSnapshotIncomplete = flattenedActiveSnapshot === null;
+            const invalidActiveAccountEvidence = flattenedActiveSnapshot?.some(({ order }) => !this.orderHasExactAccount(order, input.accountId)) ?? false;
+            const invalidNestedActiveEvidence = flattenedActiveSnapshot?.some(({ order, nestedParent }) => nestedParent !== null &&
+                !this.recoveryGraphOrderMayBeAttached(request, order) &&
+                this.recoveryGraphOrderIsAttached(request, nestedParent)) ?? false;
+            const accountOrders = (flattenedActiveSnapshot ?? [])
+                .map(({ order }) => order)
+                .filter((order) => this.orderHasExactAccount(order, input.accountId));
+            const activeMatchesByMember = new Map();
+            const knownActiveOrders = accountOrders.filter((order) => input.orderId !== undefined && this.recoveryOrderId(order) === input.orderId);
+            const conflictingKnownActiveOrders = knownActiveOrders.filter((order) => !this.recoveryGraphOrderMayBeAttached(request, order));
+            const observedCandidates = activeSnapshotIncomplete || invalidActiveAccountEvidence || invalidNestedActiveEvidence
+                ? [response]
+                : [...conflictingKnownActiveOrders];
+            observedCandidates.push(...accountOrders.filter((order) => this.recoveryGraphOrderMayBeAttached(request, order)));
+            for (const node of request.nodes) {
+                const matches = accountOrders.filter((order) => this.terminalOrderTicketIsValid(order) &&
+                    this.orderHasValidRecoveryStatus(order) &&
+                    this.recoveryOrderMatchesGraphNode(request, node, order));
+                activeMatchesByMember.set(node.memberId, matches);
+            }
+            const selected = new Map();
+            const usedOrderIds = new Set();
+            for (const node of request.nodes) {
+                const matches = activeMatchesByMember.get(node.memberId) ?? [];
+                const [match] = matches;
+                if (matches.length !== 1 || match === undefined)
                     continue;
-                selected.set(node.memberId, order);
-                const orderId = this.recoveryOrderId(order);
-                if (orderId !== undefined)
-                    usedOrderIds.add(orderId);
-                observedCandidates.push(order);
+                const orderId = this.recoveryOrderId(match);
+                if (orderId === undefined)
+                    continue;
+                if (usedOrderIds.has(orderId))
+                    continue;
+                usedOrderIds.add(orderId);
+                selected.set(node.memberId, match);
             }
-        }
-        observedCandidates.push(...terminalEvidence.observedResponses);
-        if (terminalEvidence.invalidAttachedEvidence) {
-            observedCandidates.push({ reason: "Invalid or conflicting terminal broker evidence" });
-        }
-        const selectedCandidates = [...selected.values()];
-        const requestedOrderIdMissing = input.orderId !== undefined &&
-            !selectedCandidates.some((order) => this.recoveryOrderId(order) === input.orderId);
-        const members = request.nodes.map((node) => {
-            const order = selected.get(node.memberId);
-            return this.graphMemberEvidence(request, node, order);
-        });
-        const ids = members.flatMap(({ orderId }) => (orderId === null ? [] : [orderId]));
-        const hasDistinctOrderIds = new Set(ids).size === request.nodes.length;
-        const linkedOrderIds = new Set();
-        let linkedOrderMissingBrokerId = false;
-        for (const order of accountOrders) {
-            if (!this.recoveryGraphOrderMayBeAttached(request, order))
-                continue;
-            if (!this.recoveryGraphOrderIsAttached(request, order)) {
-                linkedOrderMissingBrokerId = true;
-                continue;
+            const unresolved = request.nodes.filter((node) => !selected.has(node.memberId));
+            const terminalEvidence = await this.findRecoveryGraphTerminalCandidates(input.accountId, request, input.orderId);
+            const conflictingKnownActiveTickets = knownActiveOrders.filter((activeOrder) => terminalEvidence.linkedOrders.some((terminalOrder) => this.recoveryOrderId(terminalOrder) === input.orderId &&
+                this.terminalOrderTicketConflicts(activeOrder, terminalOrder)));
+            this.reconcileSelectedGraphMembers(request, selected, terminalEvidence);
+            if (unresolved.length > 0) {
+                const assignments = this.assignRecoveryGraphCandidates(unresolved, terminalEvidence.byNode, usedOrderIds);
+                for (const node of unresolved) {
+                    const order = assignments.get(node.memberId);
+                    if (order === undefined)
+                        continue;
+                    selected.set(node.memberId, order);
+                    const orderId = this.recoveryOrderId(order);
+                    if (orderId !== undefined)
+                        usedOrderIds.add(orderId);
+                    observedCandidates.push(order);
+                }
             }
-            const orderId = this.recoveryOrderId(order);
-            if (orderId === undefined) {
-                linkedOrderMissingBrokerId = true;
-                continue;
+            observedCandidates.push(...terminalEvidence.observedResponses);
+            if (terminalEvidence.invalidAttachedEvidence) {
+                observedCandidates.push({ reason: "Invalid or conflicting terminal broker evidence" });
             }
-            linkedOrderIds.add(orderId);
-        }
-        for (const order of terminalEvidence.linkedOrders) {
-            const orderId = this.recoveryOrderId(order);
-            if (orderId === undefined) {
-                linkedOrderMissingBrokerId = true;
-                continue;
+            const selectedCandidates = [...selected.values()];
+            const requestedOrderIdMissing = input.orderId !== undefined &&
+                !selectedCandidates.some((order) => this.recoveryOrderId(order) === input.orderId);
+            const members = request.nodes.map((node) => {
+                const order = selected.get(node.memberId);
+                return this.graphMemberEvidence(request, node, order);
+            });
+            const ids = members.flatMap(({ orderId }) => (orderId === null ? [] : [orderId]));
+            const hasDistinctOrderIds = new Set(ids).size === request.nodes.length;
+            const linkedOrderIds = new Set();
+            let linkedOrderMissingBrokerId = false;
+            for (const order of accountOrders) {
+                if (!this.recoveryGraphOrderMayBeAttached(request, order))
+                    continue;
+                if (!this.recoveryGraphOrderIsAttached(request, order)) {
+                    linkedOrderMissingBrokerId = true;
+                    continue;
+                }
+                const orderId = this.recoveryOrderId(order);
+                if (orderId === undefined) {
+                    linkedOrderMissingBrokerId = true;
+                    continue;
+                }
+                linkedOrderIds.add(orderId);
+            }
+            for (const order of terminalEvidence.linkedOrders) {
+                const orderId = this.recoveryOrderId(order);
+                if (orderId === undefined) {
+                    linkedOrderMissingBrokerId = true;
+                    continue;
+                }
+                linkedOrderIds.add(orderId);
+            }
+            const selectedOrderIds = new Set(selectedCandidates.flatMap((order) => {
+                const orderId = this.recoveryOrderId(order);
+                return orderId === undefined ? [] : [orderId];
+            }));
+            if (selected.size !== request.nodes.length ||
+                !hasDistinctOrderIds ||
+                linkedOrderMissingBrokerId ||
+                [...linkedOrderIds].some((orderId) => !selectedOrderIds.has(orderId)) ||
+                requestedOrderIdMissing ||
+                activeSnapshotIncomplete ||
+                invalidActiveAccountEvidence ||
+                invalidNestedActiveEvidence ||
+                conflictingKnownActiveOrders.length > 0 ||
+                conflictingKnownActiveTickets.length > 0 ||
+                terminalEvidence.invalidAttachedEvidence ||
+                terminalEvidence.terminalSnapshotLookupFailed ||
+                members.some(({ status }) => status === "UNKNOWN" || status === "WARNING_PENDING")) {
+                return {
+                    state: "recovery_required",
+                    rootClientOrderId: request.rootClientOrderId,
+                    members,
+                    reasons: [
+                        "Exact graph recovery found incomplete, duplicated, or ambiguous member evidence",
+                    ],
+                    warnings: [],
+                    errors: [],
+                    unrecognizedResponses: observedCandidates,
+                };
             }
-            linkedOrderIds.add(orderId);
-        }
-        const selectedOrderIds = new Set(selectedCandidates.flatMap((order) => {
-            const orderId = this.recoveryOrderId(order);
-            return orderId === undefined ? [] : [orderId];
-        }));
-        if (selected.size !== request.nodes.length ||
-            !hasDistinctOrderIds ||
-            linkedOrderMissingBrokerId ||
-            [...linkedOrderIds].some((orderId) => !selectedOrderIds.has(orderId)) ||
-            requestedOrderIdMissing ||
-            activeSnapshotIncomplete ||
-            invalidActiveAccountEvidence ||
-            invalidNestedActiveEvidence ||
-            conflictingKnownActiveOrders.length > 0 ||
-            conflictingKnownActiveTickets.length > 0 ||
-            terminalEvidence.invalidAttachedEvidence ||
-            terminalEvidence.terminalSnapshotLookupFailed ||
-            members.some(({ status }) => status === "UNKNOWN" || status === "WARNING_PENDING")) {
             return {
-                state: "recovery_required",
+                state: "accepted",
                 rootClientOrderId: request.rootClientOrderId,
-                members,
-                reasons: [
-                    "Exact graph recovery found incomplete, duplicated, or ambiguous member evidence",
-                ],
+                members: this.attachGraphParentOrderIds(members),
                 warnings: [],
-                errors: [],
-                unrecognizedResponses: observedCandidates,
             };
-        }
-        return {
-            state: "accepted",
-            rootClientOrderId: request.rootClientOrderId,
-            members: this.attachGraphParentOrderIds(members),
-            warnings: [],
-        };
+        });
     }
     reconcileSelectedGraphMembers(request, selected, terminalEvidence) {
         for (const node of request.nodes) {
@@ -1293,38 +1366,58 @@ export class IbkrClient {
         return assignments;
     }
     async acknowledgeOrderWarning(input) {
+        this.assertOpen();
+        const confirmed = input.confirmed;
+        if (confirmed !== true)
+            throw new Error("Order warning confirmation must be true");
+        if (!input.accountId.trim())
+            throw new Error("An exact account ID is required");
         if (!input.replyId.trim())
             throw new Error("An exact warning reply ID is required");
-        const response = await this.singleAttemptRequest({
-            path: `iserver/reply/${encodeURIComponent(input.replyId)}`,
-            method: "POST",
-            data: { confirmed: true },
+        return this.withTradingMutation(input.accountId, "IBKR brokerage session is not safely authenticated for warning acknowledgement", async () => {
+            const response = await this.singleAttemptRequest({
+                path: `iserver/reply/${encodeURIComponent(input.replyId)}`,
+                method: "POST",
+                data: { confirmed: true },
+            });
+            return this.normalizeOrderSubmission(response, null);
         });
-        return this.normalizeOrderSubmission(response, null);
     }
     async acknowledgeContingentOrderWarning(input) {
+        this.assertOpen();
         const confirmed = input.confirmed;
         if (confirmed !== true) {
             throw new Error("Order warning confirmation must be true");
         }
+        if (!input.continuation.accountId.trim()) {
+            throw new Error("An exact account ID is required");
+        }
         if (!input.continuation.replyId.trim()) {
             throw new Error("An exact warning reply ID is required");
         }
         if (!input.continuation.parentClientOrderId.trim()) {
             throw new Error("An exact parent client order ID is required");
         }
-        const response = await this.singleAttemptRequest({
-            path: `iserver/reply/${encodeURIComponent(input.continuation.replyId)}`,
-            method: "POST",
-            data: { confirmed: true },
+        return this.withTradingMutation(input.continuation.accountId, "IBKR brokerage session is not safely authenticated for warning acknowledgement", async () => {
+            const response = await this.singleAttemptRequest({
+                path: `iserver/reply/${encodeURIComponent(input.continuation.replyId)}`,
+                method: "POST",
+                data: { confirmed: true },
+            });
+            return this.normalizeMultiOrderSubmission(response, input.continuation.parentClientOrderId, input.continuation.accountId);
         });
-        return this.normalizeMultiOrderSubmission(response, input.continuation.parentClientOrderId);
     }
     async getDerivativeOrderStatus(accountId, orderId) {
+        this.assertOpen();
         if (!accountId.trim() || !orderId.trim()) {
             throw new Error("Exact account and order IDs are required");
         }
-        await this.prepareBrokerageAccount(accountId);
+        return this.withAccountCriticalSection(async () => {
+            await this.prepareBrokerageAccount(accountId);
+            return this.getDerivativeOrderStatusPrepared(accountId, orderId);
+        });
+    }
+    async getDerivativeOrderStatusPrepared(accountId, orderId) {
         const order = await this.req({
             path: `iserver/account/order/status/${encodeURIComponent(orderId)}`,
         });
@@ -1341,6 +1434,7 @@ export class IbkrClient {
         return lifecycle;
     }
     async findDerivativeOrder(input) {
+        this.assertOpen();
         if (!input.accountId.trim())
             throw new Error("An exact account ID is required");
         const identity = input.orderId ?? input.clientOrderId;
@@ -1349,78 +1443,84 @@ export class IbkrClient {
         if (input.orderId !== undefined) {
             return this.getDerivativeOrderStatus(input.accountId, input.orderId);
         }
-        await this.prepareBrokerageAccount(input.accountId);
-        const response = await this.req({
-            path: "iserver/account/orders",
-            params: { accountId: input.accountId },
-        });
-        const order = response.orders?.find((candidate) => {
-            if (!this.orderBelongsToAccount(candidate, input.accountId))
-                return false;
-            return (candidate.cOID ?? candidate.order_ref) === input.clientOrderId;
+        return this.withAccountCriticalSection(async () => {
+            await this.prepareBrokerageAccount(input.accountId);
+            const response = await this.req({
+                path: "iserver/account/orders",
+                params: { accountId: input.accountId },
+            });
+            const order = response.orders?.find((candidate) => {
+                if (!this.orderBelongsToAccount(candidate, input.accountId))
+                    return false;
+                return (candidate.cOID ?? candidate.order_ref) === input.clientOrderId;
+            });
+            if (order === undefined)
+                throw new Error(`IBKR order ${identity} was not found`);
+            const orderId = order.order_id ?? order.orderId;
+            if (orderId === undefined) {
+                throw new Error(`IBKR order ${identity} did not include a broker order ID`);
+            }
+            return this.getDerivativeOrderStatusPrepared(input.accountId, String(orderId));
         });
-        if (order === undefined)
-            throw new Error(`IBKR order ${identity} was not found`);
-        const orderId = order.order_id ?? order.orderId;
-        if (orderId === undefined) {
-            throw new Error(`IBKR order ${identity} did not include a broker order ID`);
-        }
-        return this.getDerivativeOrderStatus(input.accountId, String(orderId));
     }
     async listActiveDerivativeOrders(accountId) {
+        this.assertOpen();
         if (!accountId.trim())
             throw new Error("An exact account ID is required");
-        await this.prepareBrokerageAccount(accountId);
-        const response = await this.req({
-            path: "iserver/account/orders",
-            params: { accountId },
-        });
-        const flattened = this.flattenCompleteOrderSnapshot(response);
-        if (flattened === null) {
-            throw new Error("IBKR active-order snapshot is incomplete");
-        }
-        const invalidAccountEvidence = flattened.find(({ order }) => {
-            const returnedAccounts = [order.account, order.acct];
-            const providedAccounts = returnedAccounts.filter((value) => value !== undefined);
-            return (providedAccounts.length === 0 ||
-                providedAccounts.some((returnedAccount) => typeof returnedAccount !== "string" || returnedAccount !== accountId));
-        });
-        if (invalidAccountEvidence !== undefined) {
-            throw new Error("IBKR active-order response did not provide unambiguous account identity");
-        }
-        const normalized = flattened.map(({ order, nestedParent }) => this.normalizeActiveDerivativeOrder(accountId, order, nestedParent));
-        const byOrderId = new Map();
-        const byClientId = new Map();
-        for (const order of normalized) {
-            if (order.orderId !== null) {
-                const members = byOrderId.get(order.orderId) ?? [];
-                members.push(order);
-                byOrderId.set(order.orderId, members);
+        return this.withAccountCriticalSection(async () => {
+            await this.prepareBrokerageAccount(accountId);
+            const response = await this.req({
+                path: "iserver/account/orders",
+                params: { accountId },
+            });
+            const flattened = this.flattenCompleteOrderSnapshot(response);
+            if (flattened === null) {
+                throw new Error("IBKR active-order snapshot is incomplete");
             }
-            if (order.clientOrderId !== null) {
-                const members = byClientId.get(order.clientOrderId) ?? [];
-                members.push(order);
-                byClientId.set(order.clientOrderId, members);
+            const invalidAccountEvidence = flattened.find(({ order }) => {
+                const returnedAccounts = [order.account, order.acct];
+                const providedAccounts = returnedAccounts.filter((value) => value !== undefined);
+                return (providedAccounts.length === 0 ||
+                    providedAccounts.some((returnedAccount) => typeof returnedAccount !== "string" || returnedAccount !== accountId));
+            });
+            if (invalidAccountEvidence !== undefined) {
+                throw new Error("IBKR active-order response did not provide unambiguous account identity");
             }
-        }
-        for (const order of normalized) {
-            if (order.orderId !== null && (byOrderId.get(order.orderId)?.length ?? 0) > 1) {
-                this.addOrderUncertainty(order, "DUPLICATE_MEMBER");
+            const normalized = flattened.map(({ order, nestedParent }) => this.normalizeActiveDerivativeOrder(accountId, order, nestedParent));
+            const byOrderId = new Map();
+            const byClientId = new Map();
+            for (const order of normalized) {
+                if (order.orderId !== null) {
+                    const members = byOrderId.get(order.orderId) ?? [];
+                    members.push(order);
+                    byOrderId.set(order.orderId, members);
+                }
+                if (order.clientOrderId !== null) {
+                    const members = byClientId.get(order.clientOrderId) ?? [];
+                    members.push(order);
+                    byClientId.set(order.clientOrderId, members);
+                }
             }
-            const parentIdentity = order.parentOrderId ?? order.parentClientOrderId;
-            if (parentIdentity === null)
-                continue;
-            const brokerMatches = byOrderId.get(parentIdentity) ?? [];
-            const clientMatches = byClientId.get(parentIdentity) ?? [];
-            const matches = new Set([...brokerMatches, ...clientMatches]);
-            if (matches.size === 0)
-                this.addOrderUncertainty(order, "MISSING_PARENT");
-            if (matches.size > 1)
-                this.addOrderUncertainty(order, "AMBIGUOUS_PARENT");
-        }
-        return normalized;
+            for (const order of normalized) {
+                if (order.orderId !== null && (byOrderId.get(order.orderId)?.length ?? 0) > 1) {
+                    this.addOrderUncertainty(order, "DUPLICATE_MEMBER");
+                }
+                const parentIdentity = order.parentOrderId ?? order.parentClientOrderId;
+                if (parentIdentity === null)
+                    continue;
+                const brokerMatches = byOrderId.get(parentIdentity) ?? [];
+                const clientMatches = byClientId.get(parentIdentity) ?? [];
+                const matches = new Set([...brokerMatches, ...clientMatches]);
+                if (matches.size === 0)
+                    this.addOrderUncertainty(order, "MISSING_PARENT");
+                if (matches.size > 1)
+                    this.addOrderUncertainty(order, "AMBIGUOUS_PARENT");
+            }
+            return normalized;
+        });
     }
     async getDerivativeExecutions(input) {
+        this.assertOpen();
         if (!input.accountId.trim())
             throw new Error("An exact account ID is required");
         if (input.days !== undefined &&
@@ -1433,21 +1533,24 @@ export class IbkrClient {
         if (input.clientOrderId !== undefined && !input.clientOrderId.trim()) {
             throw new Error("Client order ID cannot be empty");
         }
-        await this.prepareBrokerageAccount(input.accountId);
-        const response = await this.req({
-            path: "iserver/account/trades",
-            ...(input.days === undefined ? {} : { params: { days: input.days } }),
-        });
-        return response
-            .filter((trade) => (trade.account ?? trade.accountCode) === input.accountId)
-            .filter((trade) => input.orderId === undefined || String(trade.order_id) === input.orderId)
-            .filter((trade) => input.clientOrderId === undefined || trade.order_ref === input.clientOrderId)
-            .flatMap((trade) => {
-            const execution = this.normalizeDerivativeExecution(input.accountId, trade);
-            return execution === undefined ? [] : [execution];
+        return this.withAccountCriticalSection(async () => {
+            await this.prepareBrokerageAccount(input.accountId);
+            const response = await this.req({
+                path: "iserver/account/trades",
+                ...(input.days === undefined ? {} : { params: { days: input.days } }),
+            });
+            return response
+                .filter((trade) => (trade.account ?? trade.accountCode) === input.accountId)
+                .filter((trade) => input.orderId === undefined || String(trade.order_id) === input.orderId)
+                .filter((trade) => input.clientOrderId === undefined || trade.order_ref === input.clientOrderId)
+                .flatMap((trade) => {
+                const execution = this.normalizeDerivativeExecution(input.accountId, trade);
+                return execution === undefined ? [] : [execution];
+            });
         });
     }
     async reconcileDerivativeComboExecution(request) {
+        this.assertOpen();
         this.validateReconciliationRequest(request);
         const lifecycle = await this.getDerivativeOrderStatus(request.accountId, request.orderId);
         const deadline = this.now() + (request.timeoutMs ?? 30_000);
@@ -1474,24 +1577,22 @@ export class IbkrClient {
         }
     }
     async cancelDerivativeOrder(input) {
+        this.assertOpen();
         if (!input.accountId.trim() || !input.orderId.trim()) {
             throw new Error("Exact account and order IDs are required");
         }
         const cmeOperatorMetadata = this.cmeOperatorMetadata(input.assetClass, input);
-        await this.prepareBrokerageAccount(input.accountId);
-        const response = await this.singleAttemptRequest({
-            path: `iserver/account/${input.accountId}/order/${encodeURIComponent(input.orderId)}`,
-            method: "DELETE",
-            ...(Object.keys(cmeOperatorMetadata).length > 0 ? { params: cmeOperatorMetadata } : {}),
+        return this.withTradingMutation(input.accountId, "IBKR brokerage session is not safely authenticated for cancellation", async () => {
+            const response = await this.singleAttemptRequest({
+                path: `iserver/account/${input.accountId}/order/${encodeURIComponent(input.orderId)}`,
+                method: "DELETE",
+                ...(Object.keys(cmeOperatorMetadata).length > 0 ? { params: cmeOperatorMetadata } : {}),
+            });
+            return this.normalizeOrderCancellation(input, response);
         });
-        return {
-            state: "requested",
-            accountId: input.accountId,
-            orderId: input.orderId,
-            message: this.trimmedString(response.msg),
-        };
     }
     async getAccountId() {
+        this.assertOpen();
         this.accountIdPromise ??= (async () => {
             const override = process.env["IBKR_ACCOUNT_ID"];
             if (override)
@@ -1505,6 +1606,7 @@ export class IbkrClient {
         return this.accountIdPromise;
     }
     async getAccountBalances() {
+        this.assertOpen();
         const accountId = await this.getAccountId();
         const summary = await this.req({
             path: `portfolio/${accountId}/summary`,
@@ -1545,6 +1647,7 @@ export class IbkrClient {
         };
     }
     async getPositions(symbol) {
+        this.assertOpen();
         const accountId = await this.getAccountId();
         const rows = await this.fetchAllPositions(accountId);
         for (const position of rows) {
@@ -1622,6 +1725,7 @@ export class IbkrClient {
         };
     }
     async getQuotes(requests, options = {}) {
+        this.assertOpen();
         const unique = new Map();
         for (const request of requests) {
             if (!request.symbol.trim())
@@ -1680,6 +1784,7 @@ export class IbkrClient {
     }
     /** Resolve equity/ETF symbols to IBKR contracts via `trsrv/stocks`. */
     async searchInstruments(symbol, projection = "symbol-search") {
+        this.assertOpen();
         if (projection !== "symbol-search" && projection !== "search") {
             throw new Error(`IBKR search currently supports only symbol-search/search projections (got '${projection}').`);
         }
@@ -1693,6 +1798,7 @@ export class IbkrClient {
         return (response[query] ?? []).flatMap((listing) => this.normalizeStockListing(query, listing));
     }
     async fetchTransactionHistory(startDate, endDate) {
+        this.assertOpen();
         const accountId = await this.getAccountId();
         const rows = await this.fetchAllPositions(accountId);
         const positionsByConid = new Map(rows
@@ -1722,25 +1828,28 @@ export class IbkrClient {
         return [{ accountNumber: accountId, transactions: [...transactionsByKey.values()] }];
     }
     async fetchOrders(options) {
+        this.assertOpen();
         const accountId = await this.getAccountId();
-        await this.prepareBrokerageAccount(accountId);
-        const params = {};
-        if (options.status && options.status.toUpperCase() !== "WORKING") {
-            params["filters"] = this.ibkrStatusFilter(options.status);
-        }
-        const response = await this.req({
-            path: "iserver/account/orders",
-            params,
+        return this.withAccountCriticalSection(async () => {
+            await this.prepareBrokerageAccount(accountId);
+            const params = {};
+            if (options.status && options.status.toUpperCase() !== "WORKING") {
+                params["filters"] = this.ibkrStatusFilter(options.status);
+            }
+            const response = await this.req({
+                path: "iserver/account/orders",
+                params,
+            });
+            let orders = (response.orders ?? [])
+                .filter((order) => this.orderBelongsToAccount(order, accountId))
+                .map((order) => this.normalizeOrder(order))
+                .filter((order) => this.orderMatchesStatus(order, options.status))
+                .filter((order) => this.orderInDateRange(order, options.fromEnteredTime, options.toEnteredTime))
+                .sort((left, right) => this.orderTimeMs(right) - this.orderTimeMs(left));
+            if (options.maxResults !== undefined)
+                orders = orders.slice(0, options.maxResults);
+            return [{ accountNumber: accountId, orders }];
         });
-        let orders = (response.orders ?? [])
-            .filter((order) => this.orderBelongsToAccount(order, accountId))
-            .map((order) => this.normalizeOrder(order))
-            .filter((order) => this.orderMatchesStatus(order, options.status))
-            .filter((order) => this.orderInDateRange(order, options.fromEnteredTime, options.toEnteredTime))
-            .sort((left, right) => this.orderTimeMs(right) - this.orderTimeMs(left));
-        if (options.maxResults !== undefined)
-            orders = orders.slice(0, options.maxResults);
-        return [{ accountNumber: accountId, orders }];
     }
     validateComboPreview(request) {
         if (!request.accountId.trim())
@@ -2287,7 +2396,172 @@ export class IbkrClient {
             ],
         };
     }
-    normalizeMultiOrderSubmission(response, parentClientOrderId) {
+    normalizeOrderCancellation(input, response) {
+        const record = isUnknownRecord(response) ? response : null;
+        const message = this.trimmedString(record?.["msg"]);
+        const accountId = this.trimmedString(record?.["account"]);
+        const orderId = this.cancellationOrderId(record?.["order_id"]);
+        const errorParts = record === null ? [] : this.cancellationErrorParts(record);
+        const evidence = {
+            message,
+            accountId,
+            orderId,
+            error: errorParts.length > 0 ? errorParts.join("; ").slice(0, 4_096) : null,
+            response: this.sanitizeJsonEvidence(response),
+        };
+        const accountProvided = record !== null && "account" in record;
+        const orderProvided = record !== null && "order_id" in record;
+        const conidProvided = record !== null && "conid" in record;
+        const conid = record?.["conid"];
+        const unknownFields = record === null
+            ? []
+            : Object.keys(record).filter((key) => key !== "msg" && key !== "account" && key !== "order_id" && key !== "conid");
+        let reason = null;
+        if (record === null)
+            reason = "IBKR returned a malformed cancellation response";
+        else if (errorParts.length > 0)
+            reason = "IBKR returned cancellation error evidence";
+        else if (unknownFields.length > 0)
+            reason = "IBKR returned undocumented cancellation fields";
+        else if (message !== "Request was submitted")
+            reason = "IBKR did not confirm the cancellation request";
+        else if (accountProvided && accountId === null)
+            reason = "IBKR returned malformed cancellation account evidence";
+        else if (orderProvided && orderId === null)
+            reason = "IBKR returned malformed cancellation order evidence";
+        else if (conidProvided &&
+            (typeof conid !== "number" || !Number.isSafeInteger(conid) || conid <= 0))
+            reason = "IBKR returned malformed cancellation conid evidence";
+        else if (accountId !== null && accountId !== input.accountId)
+            reason = "IBKR cancellation account evidence conflicts with the request";
+        else if (orderId !== null && orderId !== input.orderId)
+            reason = "IBKR cancellation order evidence conflicts with the request";
+        if (reason !== null || message === null) {
+            return {
+                state: "recovery_required",
+                accountId: input.accountId,
+                orderId: input.orderId,
+                reason: reason ?? "IBKR did not confirm the cancellation request",
+                evidence,
+            };
+        }
+        return {
+            state: "requested",
+            accountId: input.accountId,
+            orderId: input.orderId,
+            message,
+        };
+    }
+    sanitizeJsonEvidence(value) {
+        const seen = new WeakMap();
+        let remainingEntries = 500;
+        const dictionary = () => Object.create(null);
+        const markerKey = (source, result, label) => {
+            let key = label;
+            while (Object.prototype.hasOwnProperty.call(source, key) ||
+                Object.prototype.hasOwnProperty.call(result, key)) {
+                key += "#";
+            }
+            return key;
+        };
+        const sanitize = (item, depth, path) => {
+            if (item === null || typeof item === "boolean" || typeof item === "string")
+                return item;
+            if (typeof item === "number") {
+                return Number.isFinite(item) ? item : `[non-json number: ${String(item)}]`;
+            }
+            if (typeof item !== "object")
+                return `[non-json ${typeof item}]`;
+            const priorPath = seen.get(item);
+            if (priorPath !== undefined)
+                return `[reference: ${priorPath}]`;
+            seen.set(item, path);
+            if (depth >= 8) {
+                const result = dictionary();
+                result[markerKey(item, result, "[truncated: depth]")] = true;
+                return result;
+            }
+            if (Array.isArray(item)) {
+                const result = [];
+                for (const [index, member] of item.entries()) {
+                    if (remainingEntries <= 0) {
+                        result.push("[truncated: entry count]");
+                        break;
+                    }
+                    remainingEntries -= 1;
+                    result.push(sanitize(member, depth + 1, `${path}[${String(index)}]`));
+                }
+                return result;
+            }
+            const result = dictionary();
+            for (const ownKey of Reflect.ownKeys(item)) {
+                if (remainingEntries <= 0) {
+                    result[markerKey(item, result, "[truncated: entry count]")] = true;
+                    break;
+                }
+                remainingEntries -= 1;
+                const key = typeof ownKey === "string"
+                    ? ownKey
+                    : markerKey(item, result, `[non-json symbol key: ${ownKey.description ?? ""}]`);
+                let member;
+                try {
+                    member = Reflect.get(item, ownKey);
+                }
+                catch {
+                    member = "[unreadable property]";
+                }
+                result[key] = sanitize(member, depth + 1, `${path}.${JSON.stringify(key)}`);
+            }
+            return result;
+        };
+        const sanitized = sanitize(value, 0, "$");
+        const encoded = JSON.stringify(sanitized);
+        if (encoded.length <= 8_192)
+            return sanitized;
+        const fallback = dictionary();
+        fallback["[truncated: evidence size]"] = true;
+        fallback["originalSerializedLength"] = encoded.length;
+        let low = 0;
+        let high = encoded.length;
+        while (low < high) {
+            const middle = Math.ceil((low + high) / 2);
+            fallback["preview"] = encoded.slice(0, middle);
+            if (JSON.stringify(fallback).length <= 8_192)
+                low = middle;
+            else
+                high = middle - 1;
+        }
+        fallback["preview"] = encoded.slice(0, low);
+        return fallback;
+    }
+    cancellationOrderId(value) {
+        if (typeof value === "string")
+            return this.trimmedString(value);
+        return typeof value === "number" && Number.isSafeInteger(value) && value > 0
+            ? String(value)
+            : null;
+    }
+    cancellationErrorParts(record) {
+        const parts = [];
+        for (const key of ["error", "message", "text"]) {
+            if (!(key in record))
+                continue;
+            const text = this.trimmedString(record[key]);
+            parts.push(text === null ? `${key}: present` : `${key}: ${text}`);
+        }
+        for (const key of ["statusCode", "code"]) {
+            if (!(key in record))
+                continue;
+            const value = record[key];
+            parts.push(typeof value === "string" || typeof value === "number"
+                ? `${key}: ${String(value)}`
+                : `${key}: present`);
+        }
+        if (record["success"] === false)
+            parts.push("success: false");
+        return parts;
+    }
+    normalizeMultiOrderSubmission(response, parentClientOrderId, accountId) {
         const decoded = this.decodeOrderSubmission(response);
         const hasDistinctBrokerOrderIds = decoded.orders.length === 2 &&
             new Set(decoded.orders.map(({ orderId }) => orderId)).size === 2;
@@ -2314,7 +2588,7 @@ export class IbkrClient {
             return {
                 state: "warning",
                 warnings: decoded.warnings,
-                continuation: { replyId: warning.replyId, parentClientOrderId },
+                continuation: { accountId, replyId: warning.replyId, parentClientOrderId },
             };
         }
         if (hasErrors &&
@@ -3147,15 +3421,57 @@ export class IbkrClient {
         const parsed = Number(match[0].replace(/,/g, ""));
         return Number.isFinite(parsed) ? parsed : null;
     }
+    withAccountCriticalSection(operation) {
+        this.assertOpen();
+        const result = this.accountCriticalSectionTail.then(async () => {
+            this.assertOpen();
+            return operation();
+        });
+        this.accountCriticalSectionTail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    withTradingMutation(accountId, unsafeMessage, operation) {
+        return this.withAccountCriticalSection(async () => {
+            const diagnostics = await this.getTradingDiagnostics(accountId);
+            if (!this.isSafeForTradingMutation(diagnostics))
+                throw new Error(unsafeMessage);
+            await this.prepareBrokerageAccount(accountId);
+            return operation(diagnostics);
+        });
+    }
+    isSafeForTradingMutation(diagnostics) {
+        return (diagnostics.authenticated === true &&
+            diagnostics.connected === true &&
+            diagnostics.competingSession === false &&
+            diagnostics.environment !== null);
+    }
+    assertOpen() {
+        if (this.closed)
+            throw this.closedError();
+    }
+    closedError() {
+        return new Error("This IBKR client is closed");
+    }
+    booleanOrNull(value) {
+        return typeof value === "boolean" ? value : null;
+    }
+    accountIdsOrNull(value) {
+        return Array.isArray(value) &&
+            Array.from(value).every((accountId) => typeof accountId === "string")
+            ? value
+            : null;
+    }
     async prepareBrokerageAccount(accountId) {
-        const brokerageAccounts = await this.req({
+        const rawBrokerageAccounts = await this.req({
             path: "iserver/accounts",
         });
-        if (brokerageAccounts.selectedAccount === accountId)
-            return;
-        if (brokerageAccounts.accounts && !brokerageAccounts.accounts.includes(accountId)) {
+        const brokerageAccounts = isUnknownRecord(rawBrokerageAccounts) ? rawBrokerageAccounts : {};
+        const accountIds = this.accountIdsOrNull(brokerageAccounts["accounts"]);
+        if (!accountIds?.includes(accountId)) {
             throw new Error(`IBKR account ${accountId} is not available for trading/order queries.`);
         }
+        if (brokerageAccounts["selectedAccount"] === accountId)
+            return;
         const switchedAccount = await this.singleAttemptRequest({
             path: "iserver/account",
             method: "POST",
@@ -3294,6 +3610,7 @@ export class IbkrClient {
     }
     /** Return complete daily history with the exact validated IBKR request context. */
     async getPriceHistory(input) {
+        this.assertOpen();
         const requestedSymbol = input.symbol.trim().toUpperCase();
         if (!requestedSymbol) {
             throw new IbkrPriceHistoryContractError("Price history requires a symbol", "CONTRACT_INVALID");
@@ -3444,6 +3761,7 @@ export class IbkrClient {
     }
     /** Discover listed derivative series over an inclusive calendar range. */
     async getDerivativeExpiries(query) {
+        this.assertOpen();
         const contracts = [];
         for (const month of monthCodes(query.from, query.to)) {
             contracts.push(...(await this.discoverDerivativeMonth(query.underlying, query.assetClass, month, query.exchange, query.right)));
@@ -3477,6 +3795,7 @@ export class IbkrClient {
     }
     /** Discover contracts for one exact expiration, preserving class and venue identity. */
     async getDerivativeContracts(query) {
+        this.assertOpen();
         const tradingClass = query.tradingClass?.trim().toUpperCase();
         return (await this.discoverDerivativeMonth(query.underlying, query.assetClass, monthCode(query.expiration), query.exchange, query.right, query.strike)).filter((contract) => contract.expiration === query.expiration &&
             (query.right === undefined || contract.right === query.right) &&
@@ -3485,6 +3804,7 @@ export class IbkrClient {
     }
     /** Resolve exactly one contract and reject missing or ambiguous semantic identity. */
     async resolveDerivativeContract(query) {
+        this.assertOpen();
         const contracts = await this.getDerivativeContracts(query);
         if (!contracts.length) {
             throw new Error(`IBKR returned no exact ${query.assetClass} contract for ${query.underlying} ${query.expiration} ${query.right}${String(query.strike)}`);
@@ -3500,6 +3820,7 @@ export class IbkrClient {
     }
     /** Return an exact-expiration derivative chain with explicit data availability. */
     async getDerivativeChain(query) {
+        this.assertOpen();
         const contracts = await this.getDerivativeContracts(query);
         if (!contracts.length) {
             throw new Error(`IBKR returned no ${query.assetClass} contracts for ${query.underlying} ${query.expiration}`);
@@ -3512,6 +3833,7 @@ export class IbkrClient {
     }
     /** Quote the broker-linked underlying (for example, the Sep NQ future behind QN3). */
     async getDerivativeReferenceQuote(contract) {
+        this.assertOpen();
         const detailResponse = await this.req({
             path: "trsrv/secdef",
             params: { conids: String(contract.conid) },
@@ -3558,6 +3880,7 @@ export class IbkrClient {
     }
     /** Discover every listed weekly/monthly expiry in the requested calendar range. */
     async getOptionExpiries(symbol, right, fromDate, toDate, options = {}) {
+        this.assertOpen();
         const normalized = symbol.trim().toUpperCase();
         const months = monthCodes(fromDate, toDate);
         const contracts = [];
@@ -3573,6 +3896,7 @@ export class IbkrClient {
     }
     /** Build one exact-expiry chain with canonical OSI symbols and required pricing/greeks. */
     async getOptionChain(symbol, expiry, right, options = {}) {
+        this.assertOpen();
         const month = monthCode(expiry);
         const normalized = symbol.trim().toUpperCase();
         const discovery = await this.discoverOptions(normalized, month, right, options);
@@ -3592,6 +3916,7 @@ export class IbkrClient {
     }
     /** Return every qualified contract for one exact expiry and side without hiding sparse data. */
     async getOptionChainSnapshot(symbol, expiry, right, options = {}) {
+        this.assertOpen();
         const month = monthCode(expiry);
         const normalized = symbol.trim().toUpperCase();
         const discovery = await this.discoverOptions(normalized, month, right, options);
@@ -3603,6 +3928,7 @@ export class IbkrClient {
     }
     /** Fetch one exact option quote; null means the contract is not listed. */
     async getOptionQuote(input) {
+        this.assertOpen();
         const contract = await this.resolveOptionContract(input);
         if (!contract)
             return null;
@@ -3610,6 +3936,7 @@ export class IbkrClient {
     }
     /** Resolve a conid back into the canonical OSI-bearing option contract. */
     async getOptionContract(conid) {
+        this.assertOpen();
         const response = await this.req({
             path: "trsrv/secdef",
             params: { conids: String(conid) },
@@ -4984,6 +5311,8 @@ export class IbkrClient {
         return this.scheduledRequest(input, "SINGLE_ATTEMPT");
     }
     scheduledRequest(input, retryPolicy, signal, onTerminalFailure) {
+        if (this.closed)
+            return Promise.reject(this.closedError());
         return this.requestScheduler.schedule({
             endpoint: this.requestEndpoint(input.path),
             priority: this.requestPriority(input.path),