knitting 0.1.70 → 0.1.73

package/src/memory/payloadCodec.js

@@ -40,7 +40,7 @@ const objectGetPrototypeOf = Object.getPrototypeOf;
 const objectHasOwn = Object.prototype.hasOwnProperty;
 const arrayIsArray = Array.isArray;
 const objectPrototype = Object.prototype;
-const UNSUPPORTED_OBJECT_DETAIL = "Unsupported object type. Allowed: plain object, array, Error, Date, Envelope, Buffer, ArrayBuffer, DataView, typed arrays, and registered external payloads. Serialize it yourself.";
+const UNSUPPORTED_OBJECT_DETAIL = "Unsupported object type. Allowed: plain object, array, Error, Date, Envelope, Buffer, ArrayBuffer, DataView, Uint8Array, Int32Array, Float64Array, BigInt64Array, BigUint64Array, and registered external payloads. Serialize it yourself.";
 const ENVELOPE_PAYLOAD_DETAIL = "Envelope payload must be an ArrayBuffer, SharedArrayBuffer, " +
     "ProcessSharedBuffer, or BufferReference.";
 const ENVELOPE_HEADER_DETAIL = "Envelope header must be a JSON-like value or string.";
@@ -252,18 +252,23 @@ const toErrorPayload = (error) => {
     }
     return payload;
 };
-const parseErrorPayload = (raw) => {
-    let parsed;
-    try {
-        parsed = parseJSON(raw);
+// The shape `toErrorCause` writes for an Error cause. A plain-object cause
+// with any other key is left as the object it was.
+const isErrorPayload = (value) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
     }
-    catch {
-        return new Error(raw);
+    const payload = value;
+    if (typeof payload.name !== "string" || typeof payload.message !== "string") {
+        return false;
     }
-    if (parsed == null || typeof parsed !== "object") {
-        return new Error(String(parsed));
+    for (const key in payload) {
+        if (key !== "name" && key !== "message" && key !== "stack" && key !== "cause")
+            return false;
     }
-    const payload = parsed;
+    return true;
+};
+const reviveErrorPayload = (payload) => {
     const err = new Error(typeof payload.message === "string" ? payload.message : "");
     if (typeof payload.name === "string" && payload.name.length > 0) {
         err.name = payload.name;
@@ -276,10 +281,25 @@ const parseErrorPayload = (raw) => {
         }
     }
     if (objectHasOwn.call(payload, "cause")) {
-        err.cause = payload.cause;
+        err.cause = isErrorPayload(payload.cause)
+            ? reviveErrorPayload(payload.cause)
+            : payload.cause;
     }
     return err;
 };
+const parseErrorPayload = (raw) => {
+    let parsed;
+    try {
+        parsed = parseJSON(raw);
+    }
+    catch {
+        return new Error(raw);
+    }
+    if (parsed == null || typeof parsed !== "object") {
+        return new Error(String(parsed));
+    }
+    return reviveErrorPayload(parsed);
+};
 const decodeBigIntBinary = (bytes) => {
     const sign = bytes[0];
     let value = 0n;

package/src/permission/protocol.d.ts

@@ -2,6 +2,7 @@ type PermissionPath = string | URL;
 type NodePermissionSettings = {
     allowWorker?: boolean;
     allowChildProcess?: boolean;
+    /** Allows task code to load Node native addons inside worker threads. */
     allowAddons?: boolean;
     allowFfi?: boolean;
     allowWasi?: boolean;

package/src/permission/protocol.js

@@ -281,9 +281,14 @@ const resolveDenoLock = (input, cwd, home) => {
 };
 const resolveNodePermissionActivationFlag = () => {
     try {
-        const raw = getNodeProcess()?.versions?.node;
-        const major = Number.parseInt(String(raw).split(".", 1)[0] ?? "", 10);
-        if (Number.isFinite(major) && major > 0 && major < 22) {
+        const version = String(getNodeProcess()?.versions?.node ?? "");
+        const [majorPart, minorPart] = version.split(".");
+        const major = Number.parseInt(majorPart ?? "", 10);
+        const minor = Number.parseInt(minorPart ?? "", 10);
+        const permissionIsStable = major > 23 ||
+            (major === 23 && minor >= 5) ||
+            (major === 22 && minor >= 13);
+        if (Number.isFinite(major) && major > 0 && !permissionIsStable) {
             return "--experimental-permission";
         }
     }

package/src/runtime/dispatcher.d.ts

@@ -2,12 +2,17 @@ import { type MultiQueue } from "./tx-queue.js";
 import { type MainSignal } from "../ipc/transport/shared-memory.js";
 import { type RuntimeMessageChannelLike, type RuntimeMessagePortLike } from "../common/worker-runtime.js";
 import type { DispatcherSettings } from "../types.js";
-export declare const hostDispatcherLoop: ({ signalBox: { opView, txStatus, rxStatus, }, queue: { completeFrame, hasPendingFrames, flushToWorker, txIdle, waitForCompletion, armCompletionNotifier, setCompletionWaiterArmed, }, channelHandler, dispatcherOptions, notifySignal, crossProcess, nativeCompletionDoorbell, processCompletionDoorbell, }: {
+export declare const hostDispatcherLoop: ({ signalBox: { opView, txStatus, rxStatus, }, queue: { completeFrame, hasPendingFrames, flushToWorker, txIdle, waitForCompletion, armCompletionNotifier, setCompletionWaiterArmed, }, channelHandler, dispatcherOptions, notifySignal, wakeAfterPass, crossProcess, nativeCompletionDoorbell, processCompletionDoorbell, }: {
     queue: MultiQueue;
     signalBox: MainSignal;
     channelHandler: ChannelHandler;
     dispatcherOptions?: DispatcherSettings;
     notifySignal?: () => void;
+    /**
+     * Runs at the end of every drain pass. Defaults to waking this lane's worker
+     * if it is parked; a shared queue supplies its own policy.
+     */
+    wakeAfterPass?: () => void;
     /** Workers live in other processes; disables only the atomic doorbell. */
     crossProcess?: boolean;
     /** A runtime-native completion ring that wakes the host event loop. */

package/src/runtime/dispatcher.js

@@ -7,9 +7,9 @@ const IMMEDIATE_PUMP = RUNTIME === "deno" || RUNTIME === "node"
 // Polling tolerates a wider free window; a doorbell should arm promptly.
 const POLL_STALL_FREE_LOOPS = 128;
 const DOORBELL_STALL_FREE_LOOPS = 1;
-export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, }, queue: { completeFrame, hasPendingFrames, flushToWorker, txIdle, waitForCompletion, armCompletionNotifier, setCompletionWaiterArmed, }, channelHandler, dispatcherOptions, notifySignal, crossProcess, nativeCompletionDoorbell, processCompletionDoorbell, }) => {
+export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, }, queue: { completeFrame, hasPendingFrames, flushToWorker, txIdle, waitForCompletion, armCompletionNotifier, setCompletionWaiterArmed, }, channelHandler, dispatcherOptions, notifySignal, wakeAfterPass, crossProcess, nativeCompletionDoorbell, processCompletionDoorbell, }) => {
+    const a_add = Atomics.add;
     const a_load = Atomics.load;
-    const a_store = Atomics.store;
     const a_notify = Atomics.notify;
     const canNotifySignal = opView.buffer instanceof SharedArrayBuffer;
     const wakeSignal = notifySignal ??
@@ -17,6 +17,16 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
             if (canNotifySignal)
                 a_notify(opView, 0, 1);
         });
+    // Bump rather than store a constant: the worker parks on the value it last
+    // read, so only a changed word makes a ring that lands before its wait count.
+    const wakeLane = () => {
+        a_add(opView, 0, 1);
+        wakeSignal();
+    };
+    const wakeIfParked = wakeAfterPass ?? (() => {
+        if (a_load(rxStatus, 0) === 0)
+            wakeLane();
+    });
     const notify = () => channelHandler.notify();
     // Atomics waiters are process-local, so cross-process workers cannot use this
     // doorbell.
@@ -149,12 +159,11 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
         do {
             check.rerun = false;
             txStatus[0] = 1;
-            // Wake a parked worker whenever its receive status is clear. Pending
-            // frames are not a reliable gate because the queue may have room.
-            if (a_load(rxStatus, 0) === 0) {
-                a_store(opView, 0, 1);
-                wakeSignal();
-            }
+            // Wake a parked worker whenever its receive status is clear, so it is
+            // up by the time the frames land. Pending frames are not a reliable gate
+            // because the queue may have room.
+            if (a_load(rxStatus, 0) === 0)
+                wakeLane();
             // Only completed frames count as progress for backoff purposes.
             let completed = false;
             let progressed = true;
@@ -170,6 +179,13 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
                     progressed = true;
                 }
             }
+            // The ring above was decided before the frames flushed here existed, and
+            // calls publish straight from enqueue without passing through this loop.
+            // A worker that parked in between saw neither the frames nor a ring and
+            // slept out its whole parkMs. Publishing ends in a seq-cst store and the
+            // worker re-checks after clearing rxStatus, so re-reading rxStatus after
+            // the pass means either the worker sees the frames or this sees it parked.
+            wakeIfParked();
             txStatus[0] = 0;
             if (!txIdle()) {
                 // Queued frames indicate back-pressure, not progress; only a completion

package/src/runtime/inline-executor.js

@@ -1,4 +1,5 @@
 import { withResolvers } from "../common/with-resolvers.js";
+import { KnittingError } from "../error.js";
 import RingQueue from "../ipc/tools/ring-queue.js";
 import { createRuntimeMessageChannel } from "../common/worker-runtime.js";
 // const objects, not `enum`s: Andromeda's Nova engine can't parse `enum`. Same
@@ -270,7 +271,7 @@ export const createInlineExecutor = ({ tasks, genTaskID, batchSize, }) => {
                 if (stateByIndex[index] !== SlotStateMacro.Pending)
                     continue;
                 try {
-                    deferredByIndex[index]?.reject("Thread closed");
+                    deferredByIndex[index]?.reject(new KnittingError("THREAD_CLOSED", "Thread closed"));
                 }
                 catch {
                 }

package/src/runtime/pool.d.ts

@@ -10,7 +10,11 @@ import "../worker/loop.js";
 import { type PayloadBufferOptions } from "../memory/payload-config.js";
 /** Build the shared submit and private return buffers for a stealing pool. */
 export declare const resolveStealRegionLanes: (consumers: number) => number;
-/** Return the widest region allowed by the selected claim discipline. */
+/**
+ * Return the widest region allowed by the selected claim discipline. Only
+ * Dekker needs a region per consumer; `ticket` has no regions at all and uses
+ * the width purely as a claim batch size.
+ */
 export declare const resolveMaxStealRegionLanes: (consumers: number, stealClaim?: StealClaimDiscipline) => number;
 /** Maximum claimants that leave the protocol's required spare region. */
 export declare const MAX_STEAL_CONSUMERS: number;
@@ -91,7 +95,8 @@ export declare const createStealPoolBuffers: ({ threads, payload, sharedArgs, re
         setPromiseHandler: (handler?: import("../memory/lock.js").PromisePayloadHandler) => void;
     }[];
     sharedQueue: {
-        rejectAll: (reason: string) => void;
+        close: (reason: unknown) => void;
+        rejectAll: (reason: unknown) => void;
         hasPendingFrames: () => boolean;
         txIdle: () => boolean;
         completeFrame: () => number;
@@ -104,12 +109,12 @@ export declare const createStealPoolBuffers: ({ threads, payload, sharedArgs, re
         settlePromisePayload: (task: Task, isRejected: boolean, value: unknown) => boolean;
     };
     regionLanes: number;
-    stealClaim: StealClaimDiscipline;
+    stealClaim: "dekker" | "ticket";
     processMemory: ProcessStealMemoryLayout;
     abortSignalSAB: SharedArrayBuffer | import("../types.js").SharedBufferRegion;
     abortSignalMax: number;
 };
-export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug, hostDebug, totalNumberOfThread, workerCount, source, at, workerOptions, workerExecArgv, permission, host, payload, sharedBytesEnabled, abortSignalCapacity, usesAbortSignal, sharedChannelHandler, denoCompletionDoorbell, stealPool, }: {
+export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug, debugEpoch, hostDebug, totalNumberOfThread, workerCount, source, at, workerOptions, workerExecArgv, requestedExecArgv, permission, host, payload, sharedBytesEnabled, abortSignalCapacity, usesAbortSignal, sharedChannelHandler, denoCompletionDoorbell, stealPool, }: {
     list: string[];
     ids: number[];
     names: string[];
@@ -117,6 +122,7 @@ export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug
     sab?: Sab;
     thread: number;
     debug?: DebugOptions;
+    debugEpoch?: number;
     hostDebug?: (message: string) => void;
     totalNumberOfThread: number;
     /**
@@ -128,6 +134,8 @@ export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug
     source?: string;
     workerOptions?: WorkerSettings;
     workerExecArgv?: string[];
+    /** The caller's own `workerExecArgv`, before defaults and filtering. */
+    requestedExecArgv?: string[];
     permission?: WorkerData["permission"];
     host?: DispatcherSettings;
     payload?: PayloadBufferOptions;
@@ -171,6 +179,7 @@ export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug
     processSharedMemoryBackings?: readonly ProcessSharedMemoryBacking[];
     dispatcherCheck?: DispatcherCheck;
     laneWake?: () => void;
+    laneAwake?: () => boolean;
     bindSend?: (fn: () => void) => void;
     bindCompletionWake?: (fn: () => void) => void;
     processCompletionDoorbell?: boolean;

package/src/runtime/pool.js

@@ -1,10 +1,11 @@
 import { createHostTxQueue } from "./tx-queue.js";
 import { cleanupProcessWorkerMemoryQuietly, createProcessSharedMemoryAllocator, createProcessStealMemoryLayout, createProcessWorkerMemoryLayout, createProcessWorkerNativeSignalNotifier, processWorkerUsesIpc, readProcessSharedMemorySettings, readProcessWorkerCommandPrefix, readProcessWorkerRuntime, spawnProcessWorker, toProcessWorkerBootPayload, } from "./process-worker.js";
-import { serializeWorkerBootstrapData, terminateWorkerQuietly, toWorkerCompatExecArgv, toWorkerSafeExecArgv, } from "./worker-common.js";
+import { serializeWorkerBootstrapData, terminateWorkerQuietly, isNodePermissionExecFlag, toWorkerSafeExecArgv, warnDroppedWorkerExecArgv, } from "./worker-common.js";
 import { createSharedMemoryTransport, TRANSPORT_SIGNAL_BYTES, WORKER_STOP, } from "../ipc/transport/shared-memory.js";
 import { ChannelHandler, hostDispatcherLoop, } from "./dispatcher.js";
+import { KnittingError } from "../error.js";
 import { createNodeCompletionDoorbell } from "./node-doorbell.js";
-import { HEADER_SLOT_STRIDE_U32, lock2, LOCK_SECTOR_BYTE_LENGTH, LockBound, } from "../memory/lock.js";
+import { DEFAULT_STEAL_CLAIM, HEADER_SLOT_STRIDE_U32, lock2, LOCK_SECTOR_BYTE_LENGTH, LockBound, } from "../memory/lock.js";
 // Registers the payload codec before any lock is built.
 import "../memory/payloadCodec.js";
 import "../worker/loop.js";
@@ -25,8 +26,12 @@ const WORKER_STOP_ACK_TIMEOUT_MS = 50;
 // registry. Give its worker loop a chance to drain deferred producer pins
 // before the host falls back to terminate().
 const WORKER_STOP_NEEDS_ACK = RUNTIME === "deno" || RUNTIME === "node";
-// Keep idle workers self-healing if an Atomics.notify wake is missed.
-const DEFAULT_WORKER_PARK_MS = 1;
+// The park timeout is only a safety net: the host wakes a parked thread worker
+// after every publish, so a long park costs no latency and idles at ~0 CPU.
+const DEFAULT_WORKER_PARK_MS = 1000;
+// A process worker can only be rung across processes by a Node host waking a
+// Node child; every other pairing rediscovers work on this timeout.
+const DEFAULT_PROCESS_WORKER_PARK_MS = 1;
 const SINGLE_WORKER_SPIN_US = 50;
 const DEFAULT_ABORT_SIGNAL_CAPACITY = 258;
 const sanitizePositiveInteger = (value) => {
@@ -38,7 +43,10 @@ const sanitizePositiveInteger = (value) => {
 const resolveAbortSignalCapacity = (value) => sanitizePositiveInteger(value) ?? DEFAULT_ABORT_SIGNAL_CAPACITY;
 const abortSignalByteLength = (capacity) => Math.max(1, Math.ceil(capacity / 32)) * Uint32Array.BYTES_PER_ELEMENT;
 const withDefaultWorkerTimers = (options, workerCount) => {
-    const parkMs = options?.timers?.parkMs ?? DEFAULT_WORKER_PARK_MS;
+    const parkMs = options?.timers?.parkMs ??
+        (options?.runtime === "process"
+            ? DEFAULT_PROCESS_WORKER_PARK_MS
+            : DEFAULT_WORKER_PARK_MS);
     // `??` and not `||`: an explicit `spinMicroseconds: 0` is the whole point of
     // the multi-worker default and must not fall through to it.
     const spinMicroseconds = options?.timers?.spinMicroseconds ??
@@ -67,10 +75,14 @@ export const resolveStealRegionLanes = (consumers) => {
     }
     throw new RangeError(`${consumers} stealing workers need more than ${LockBound.slots} lanes`);
 };
-/** Return the widest region allowed by the selected claim discipline. */
-export const resolveMaxStealRegionLanes = (consumers, stealClaim) => stealClaim !== undefined && stealClaim !== "dekker"
-    ? LockBound.slots
-    : resolveStealRegionLanes(consumers);
+/**
+ * Return the widest region allowed by the selected claim discipline. Only
+ * Dekker needs a region per consumer; `ticket` has no regions at all and uses
+ * the width purely as a claim batch size.
+ */
+export const resolveMaxStealRegionLanes = (consumers, stealClaim = DEFAULT_STEAL_CLAIM) => stealClaim === "dekker"
+    ? resolveStealRegionLanes(consumers)
+    : LockBound.slots;
 /** Maximum claimants that leave the protocol's required spare region. */
 export const MAX_STEAL_CONSUMERS = LockBound.slots - 1;
 export const createStealPoolBuffers = ({ threads, payload, sharedArgs, regionLanes, stealClaim, abortSignalCapacity, usesAbortSignal, processWorker, }) => {
@@ -97,7 +109,7 @@ export const createStealPoolBuffers = ({ threads, payload, sharedArgs, regionLan
             payload: payloadSab,
         }),
     });
-    // Keep the default width valid for Dekker; wider CAS-mask regions are explicit.
+    // Keep the default width valid for Dekker; wider regions are explicit.
     const maxLanes = resolveMaxStealRegionLanes(threads, stealClaim);
     const lanes = regionLanes === undefined
         ? resolveStealRegionLanes(threads)
@@ -188,7 +200,7 @@ export const createStealPoolBuffers = ({ threads, payload, sharedArgs, regionLan
             (abortSignalSAB === undefined ? undefined : resolvedAbortSignalCapacity),
     };
 };
-export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostDebug, totalNumberOfThread, workerCount, source, at, workerOptions, workerExecArgv, permission, host, payload, sharedBytesEnabled, abortSignalCapacity, usesAbortSignal, sharedChannelHandler, denoCompletionDoorbell, stealPool, }) => {
+export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, debugEpoch, hostDebug, totalNumberOfThread, workerCount, source, at, workerOptions, workerExecArgv, requestedExecArgv, permission, host, payload, sharedBytesEnabled, abortSignalCapacity, usesAbortSignal, sharedChannelHandler, denoCompletionDoorbell, stealPool, }) => {
     if (workerOptions?.runtime === "compiled") {
         return spawnCompiledWorkerContext({
             list,
@@ -380,10 +392,20 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostD
     const ownsChannel = sharedChannelHandler === undefined &&
         stealPool === undefined;
     const ownChannel = sharedChannelHandler ?? new ChannelHandler();
+    const threadCanLoadNodeAddons = permission?.enabled !== true ||
+        permission.unsafe === true || permission.node.allowAddons === true;
+    const useNativeNodeDoorbell = RUNTIME === "node" &&
+        !useProcessWorkerRuntime && host?.doorbell !== false &&
+        host?.nativeDoorbell === true && threadCanLoadNodeAddons;
+    if (RUNTIME === "node" && !useProcessWorkerRuntime &&
+        host?.doorbell !== false && host?.nativeDoorbell === true &&
+        !threadCanLoadNodeAddons) {
+        hostDebug?.("native Node doorbell disabled by worker permissions; using the " +
+            "portable wake path (set permission.node.allowAddons=true to enable)");
+    }
     // Create the Node doorbell before bootstrapping the worker.
     let nodeCompletionWake;
-    const nodeCompletionDoorbell = !useProcessWorkerRuntime &&
-        host?.doorbell !== false && host?.nativeDoorbell === true
+    const nodeCompletionDoorbell = useNativeNodeDoorbell
         ? createNodeCompletionDoorbell(() => nodeCompletionWake?.())
         : undefined;
     const canUseNodeCompletionDoorbell = nodeCompletionDoorbell !== undefined;
@@ -438,6 +460,7 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostD
         at,
         thread,
         debug,
+        debugEpoch,
         workerOptions: resolvedWorkerOptions,
         totalNumberOfThread,
         startAt: signalBox.startAt,
@@ -476,6 +499,11 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostD
     const withExecArgv = workerExecArgv && workerExecArgv.length > 0
         ? { ...baseWorkerOptions, execArgv: workerExecArgv }
         : baseWorkerOptions;
+    const requiredNodePermissionFlags = RUNTIME === "node" &&
+        permission?.enabled === true &&
+        permission.unsafe !== true
+        ? permission.node.flags.filter(isNodePermissionExecFlag)
+        : [];
     if (processWorkerMemory !== undefined) {
         worker = spawnProcessWorker({
             workerUrl,
@@ -488,43 +516,59 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostD
     }
     else if (HAS_NODE_WORKER_THREADS) {
         try {
-            worker = new WorkerCtor(workerUrl, withExecArgv);
-        }
-        catch (error) {
-            if (error?.code === "ERR_WORKER_INVALID_EXEC_ARGV") {
-                const fallbackExecArgv = toWorkerSafeExecArgv(withExecArgv.execArgv);
-                if (fallbackExecArgv && fallbackExecArgv.length > 0) {
-                    try {
-                        worker = new WorkerCtor(workerUrl, { ...baseWorkerOptions, execArgv: fallbackExecArgv });
+            // The flags the worker actually started with.
+            let appliedExecArgv;
+            try {
+                worker = new WorkerCtor(workerUrl, withExecArgv);
+                appliedExecArgv = withExecArgv.execArgv;
+            }
+            catch (error) {
+                if (error?.code === "ERR_WORKER_INVALID_EXEC_ARGV") {
+                    const fallbackExecArgv = toWorkerSafeExecArgv(withExecArgv.execArgv);
+                    const missingPermissionFlags = requiredNodePermissionFlags.filter((flag) => !fallbackExecArgv?.includes(flag));
+                    if (missingPermissionFlags.length > 0) {
+                        throw new Error("Node rejected the permission flags required by Knitting's " +
+                            `thread worker policy (${missingPermissionFlags.join(", ")}). ` +
+                            "Refusing to retry without them.");
                     }
-                    catch (fallbackError) {
-                        if (fallbackError?.code ===
-                            "ERR_WORKER_INVALID_EXEC_ARGV") {
-                            const compatExecArgv = toWorkerCompatExecArgv(fallbackExecArgv);
-                            if (compatExecArgv && compatExecArgv.length > 0) {
-                                try {
-                                    worker = new WorkerCtor(workerUrl, { ...baseWorkerOptions, execArgv: compatExecArgv });
-                                }
-                                catch {
-                                    worker = new WorkerCtor(workerUrl, baseWorkerOptions);
-                                }
+                    if (fallbackExecArgv && fallbackExecArgv.length > 0) {
+                        try {
+                            worker = new WorkerCtor(workerUrl, { ...baseWorkerOptions, execArgv: fallbackExecArgv });
+                            appliedExecArgv = fallbackExecArgv;
+                        }
+                        catch (fallbackError) {
+                            if (requiredNodePermissionFlags.length > 0) {
+                                throw new Error("Node could not start a thread worker with Knitting's " +
+                                    "permission policy. Refusing to start it without those " +
+                                    `permissions. ${String(fallbackError)}`);
                             }
-                            else {
+                            if (fallbackError?.code ===
+                                "ERR_WORKER_INVALID_EXEC_ARGV") {
                                 worker = new WorkerCtor(workerUrl, baseWorkerOptions);
                             }
+                            else {
+                                throw fallbackError;
+                            }
                         }
-                        else {
-                            throw fallbackError;
-                        }
+                    }
+                    else if (requiredNodePermissionFlags.length > 0) {
+                        throw new Error("Node rejected the permission flags required by Knitting's " +
+                            "thread worker policy. Refusing to start the worker without " +
+                            "those permissions.");
+                    }
+                    else {
+                        worker = new WorkerCtor(workerUrl, baseWorkerOptions);
                     }
                 }
                 else {
-                    worker = new WorkerCtor(workerUrl, baseWorkerOptions);
+                    throw error;
                 }
             }
-            else {
-                throw error;
-            }
+            warnDroppedWorkerExecArgv(requestedExecArgv, appliedExecArgv);
+        }
+        catch (error) {
+            nodeCompletionDoorbell?.close();
+            throw error;
         }
     }
     else {
@@ -553,11 +597,24 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostD
             deactivateStealConsumer();
         }
     };
-    const markWorkerClosed = (reason) => {
+    const markWorkerClosed = (code, reason, cause) => {
         if (closedReason)
             return;
         closedReason = reason;
-        rejectAll(reason);
+        const error = new KnittingError(code, reason, cause);
+        if (stealPool !== undefined && stealPool.stealClaim !== "ticket") {
+            // Dekker's shared queue outlives one consumer: the surviving workers
+            // keep claiming from it, so only the calls in flight are rejected.
+            rejectAll(error);
+        }
+        else {
+            // A lane's own queue has no other consumer, so a call accepted after
+            // this point would stay pending forever: close it and reject them all.
+            // Under ticket stealing a claimed ticket may be lost at any point
+            // between CAS and retirement, so the whole shared registry closes and
+            // task-id/slot reuse is prohibited.
+            queue.close(error);
+        }
         channelHandler?.close();
     };
     const onWorkerMessage = (message) => {
@@ -567,12 +624,12 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostD
         }
         if (!isWorkerFatalMessage(message))
             return;
-        markWorkerClosed(`Worker startup failed: ${message[WORKER_FATAL_MESSAGE_KEY]}`);
+        markWorkerClosed("WORKER_STARTUP_FAILED", `Worker startup failed: ${message[WORKER_FATAL_MESSAGE_KEY]}`);
         terminateFailedWorker();
     };
     const onWorkerError = (error) => {
         const message = String(error?.message ?? error);
-        markWorkerClosed(`Worker crashed: ${message}`);
+        markWorkerClosed("WORKER_CRASHED", `Worker crashed: ${message}`, error);
         terminateFailedWorker();
     };
     const nodeWorker = worker;
@@ -585,11 +642,11 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostD
             if (closedReason !== undefined)
                 return;
             if (stopRequested) {
-                markWorkerClosed("Thread closed");
+                markWorkerClosed("THREAD_CLOSED", "Thread closed");
                 return;
             }
             const normalized = typeof code === "number" ? code : -1;
-            markWorkerClosed(`Worker exited with code ${normalized}`);
+            markWorkerClosed("WORKER_EXITED", `Worker exited with code ${normalized}`);
         });
     }
     else {
@@ -651,7 +708,7 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostD
         call,
         requestStop: requestWorkerStop,
         kills: async () => {
-            markWorkerClosed("Thread closed");
+            markWorkerClosed("THREAD_CLOSED", "Thread closed");
             // Process workers must exit before their shared memory is unmapped.
             const awaitExit = processWorkerMemory !== undefined;
             const termination = terminateWorkerQuietly(worker, awaitExit);
@@ -665,6 +722,9 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostD
         laneWake: sharedChannelHandler !== undefined || stealPool !== undefined
             ? laneWake
             : undefined,
+        laneAwake: stealPool !== undefined
+            ? () => a_load(signalBox.rxStatus, 0) !== 0
+            : undefined,
         bindSend: sharedChannelHandler !== undefined || stealPool !== undefined
             ? ((fn) => void (dispatchSend = fn))
             : undefined,

package/src/runtime/process-worker.js

@@ -681,7 +681,16 @@ const spawnNodeHostedProcessWorker = ({ workerUrl, bootPayload, memory, processR
         child.on("message", events.emitMessage);
         queueMicrotask(() => child.send?.(bootPayload));
     }
-    child.on("error", events.emitError);
+    child.on("error", (error) => {
+        if (error?.code !== "ENOENT") {
+            events.emitError(error);
+            return;
+        }
+        // A bare "spawn deno ENOENT" does not say which option chose the binary.
+        events.emitError(new Error(`process worker binary "${command}" was not found (spawn ENOENT). ` +
+            `Install ${processRuntime} or set worker.processRuntime to "node", ` +
+            `"deno" or "bun"; it defaults to "deno".`, { cause: error }));
+    });
     let resolveExit = () => { };
     const exited = new Promise((resolve) => {
         resolveExit = resolve;

package/src/runtime/tx-queue.d.ts

@@ -26,7 +26,8 @@ type CreateHostTxQueueArgs = {
     now?: () => number;
 };
 export declare function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, abortSignals, now, }: CreateHostTxQueueArgs): {
-    rejectAll: (reason: string) => void;
+    close: (reason: unknown) => void;
+    rejectAll: (reason: unknown) => void;
     hasPendingFrames: () => boolean;
     txIdle: () => boolean;
     completeFrame: () => number;

package/src/runtime/tx-queue.js

@@ -34,6 +34,7 @@ export function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, abo
     const queuePush = (task) => queue.push(task);
     const { publish, flushPending, hasPendingFrames, getPendingFrameCount, getPendingPromiseCount, resetPendingState, } = lock;
     let inUsed = 0 | 0;
+    let closedReason;
     const resetSignal = abortSignals?.resetSignal;
     const nowTime = now ?? p_now;
     const onReturnResolved = (task) => {
@@ -182,11 +183,19 @@ export function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, abo
         resetPendingState();
         inUsed = 0 | 0;
     };
+    /** Reject everything in flight, and every later call, with `reason`. */
+    const close = (reason) => {
+        if (closedReason !== undefined)
+            return;
+        closedReason = reason;
+        rejectAll(reason);
+    };
     const flushToWorker = () => flushPending();
     const enqueueKnown = (task) => {
         return publish(task);
     };
     return {
+        close,
         rejectAll,
         hasPendingFrames,
         txIdle,
@@ -200,6 +209,8 @@ export function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, abo
             const USE_SIGNAL = abortSignal !== undefined &&
                 abortSignals !== undefined;
             return (rawArgs) => {
+                if (closedReason !== undefined)
+                    return Promise.reject(closedReason);
                 if (inUsed === queue.length) {
                     const newSize = inUsed + 32;
                     let current = queue.length;

package/src/runtime/worker-common.d.ts

@@ -7,8 +7,15 @@ export type SpawnedWorker = {
 export type NodeWorkerLike = {
     on?: (event: "error" | "exit" | "message", listener: (...args: unknown[]) => void) => void;
 };
+export declare const isNodePermissionExecFlag: (flag: string) => boolean;
 export declare const toWorkerSafeExecArgv: (flags: string[] | undefined) => string[] | undefined;
+/** Preserve process-worker runtime flags while replacing inherited permissions. */
 export declare const toWorkerCompatExecArgv: (flags: string[] | undefined) => string[] | undefined;
+/**
+ * Warn once per flag set when a `workerExecArgv` flag the caller asked for did
+ * not reach the worker thread, instead of dropping it silently.
+ */
+export declare const warnDroppedWorkerExecArgv: (requested: string[] | undefined, applied: string[] | undefined) => void;
 export declare const serializeWorkerBootstrapData: (options: WorkerSettings) => WorkerSettings;
 /** Terminate a worker, optionally waiting for it to exit. */
 export declare const terminateWorkerQuietly: (worker: SpawnedWorker, awaitExit?: boolean) => Promise<void>;