@danypops/vehicle-core 0.18.5 → 0.19.0

package/dist/approvals/approval.d.ts

@@ -13,6 +13,20 @@ export declare const DEFAULT_APPROVAL_EFFECTS: readonly VehicleEffect[];
  * loop point of the gate entirely.
  */
 export declare const VEHICLE_APPROVAL_RESOLVE_OPERATION_NAME = "vehicle.approval.resolve";
+/**
+ * The name VehicleRegistry.configureApprovals() registers its own read-only status-lookup
+ * operation under. Unlike vehicle.approval.resolve, this one is deliberately left projectable
+ * as an ordinary Pi/model-callable tool: reading a requestId's own already-made decision (who
+ * decided, when, and any comment) can never let a caller grant its own pending request -- it
+ * only ever surfaces a decision a human (or other authority) already recorded. Exists because a
+ * gated invoke()'s own local HITL prompt and the eventual human decision can genuinely happen on
+ * two different calls (a caller-side timeout, a UI presented asynchronously outside the
+ * originating call's own lifetime, a session restart in between) -- without this, a decision
+ * (and any comment explaining it) made after the originating call already gave up is
+ * unrecoverable, since vehicle.approval.resolve's own vehicleApprovalResolvedEvent is transient
+ * pub/sub with no replay for a caller that wasn't subscribed at that exact moment.
+ */
+export declare const VEHICLE_APPROVAL_STATUS_OPERATION_NAME = "vehicle.approval.status";
 /** How long a request stays resolvable before it lapses and must be re-requested. */
 export declare const DEFAULT_APPROVAL_TIMEOUT_MS: number;
 /** Emitted (as a Vehicle Event) the moment a gated-effect invoke() has no valid capability -- durable-first, before any interactive prompt is attempted. */

package/dist/approvals/approval.js

@@ -37,6 +37,20 @@ export const DEFAULT_APPROVAL_EFFECTS = ["destructive", "open-world"];
  * loop point of the gate entirely.
  */
 export const VEHICLE_APPROVAL_RESOLVE_OPERATION_NAME = "vehicle.approval.resolve";
+/**
+ * The name VehicleRegistry.configureApprovals() registers its own read-only status-lookup
+ * operation under. Unlike vehicle.approval.resolve, this one is deliberately left projectable
+ * as an ordinary Pi/model-callable tool: reading a requestId's own already-made decision (who
+ * decided, when, and any comment) can never let a caller grant its own pending request -- it
+ * only ever surfaces a decision a human (or other authority) already recorded. Exists because a
+ * gated invoke()'s own local HITL prompt and the eventual human decision can genuinely happen on
+ * two different calls (a caller-side timeout, a UI presented asynchronously outside the
+ * originating call's own lifetime, a session restart in between) -- without this, a decision
+ * (and any comment explaining it) made after the originating call already gave up is
+ * unrecoverable, since vehicle.approval.resolve's own vehicleApprovalResolvedEvent is transient
+ * pub/sub with no replay for a caller that wasn't subscribed at that exact moment.
+ */
+export const VEHICLE_APPROVAL_STATUS_OPERATION_NAME = "vehicle.approval.status";
 /** How long a request stays resolvable before it lapses and must be re-requested. */
 export const DEFAULT_APPROVAL_TIMEOUT_MS = 5 * 60_000;
 const requestedPayloadSchema = defineVehicleSchema({

package/dist/resource-pool/bounded-resource-pool.d.ts

@@ -9,9 +9,8 @@ export interface PooledResource {
 }
 /**
  * Distinguishes an interactive human/agent-facing request from a self-scheduled background one.
- * Foreground admission is never queued or reduced below reservedForegroundSlots' effective
- * ceiling -- background is the only work kind that ever waits. Defaults to "foreground": a caller
- * that never opts in gets today's exact unreserved behavior.
+ * Foreground keeps the full ceiling and remains fail-fast unless its explicit queue timeout is
+ * enabled; background can be held below the reserved-slot ceiling. Defaults to "foreground".
  */
 export type ResourceWorkKind = "foreground" | "background";
 export type ResourcePoolEvent = {
@@ -33,7 +32,9 @@ export interface ResourcePoolStatus<Status = unknown> {
     readonly absoluteMaxActive: number;
     readonly byPartition: Readonly<Record<string, number>>;
     readonly resources?: Status;
-    /** How many background admissions are currently waiting for a slot reserved for foreground work -- count-only, zero whenever reservedForegroundSlots is unset or nothing is contending. */
+    /** How many opt-in foreground admissions are waiting for a lease to free. */
+    readonly waitingForegroundAdmissions: number;
+    /** How many background admissions are waiting for room below their effective ceiling. */
     readonly waitingBackgroundAdmissions: number;
 }
 export interface PoolLease<Value> extends AsyncDisposable {
@@ -52,6 +53,10 @@ export interface ResourcePoolOptions<Status = unknown> {
     readonly backgroundAdmissionQueueTimeoutMs?: number;
     /** How many background admissions may be simultaneously waiting before a new one fails fast with ResourceAdmissionQueueFull instead of growing the wait queue further. Default 8. */
     readonly maxQueuedBackgroundAdmissions?: number;
+    /** Opt-in foreground wait bound. Zero (default) preserves fail-fast ResourceCapacityExceeded behavior. */
+    readonly foregroundAdmissionQueueTimeoutMs?: number;
+    /** How many opted-in foreground admissions may wait simultaneously. Default 8. */
+    readonly maxQueuedForegroundAdmissions?: number;
     /** Fed one (partitionKey, costHandle) pair per active entry with a costHandle on calibrateCosts(). */
     readonly costRecorder?: {
         recordSample(partitionKey: string, costHandle: unknown): void;
@@ -80,7 +85,11 @@ export declare class BoundedResourcePool<OwnerKey extends string, Resource exten
     private readonly reservedForegroundSlots;
     private readonly backgroundAdmissionQueueTimeoutMs;
     private readonly maxQueuedBackgroundAdmissions;
+    private readonly foregroundAdmissionQueueTimeoutMs;
+    private readonly maxQueuedForegroundAdmissions;
     private readonly admissionWaiters;
+    private admissionGeneration;
+    private queuedForegroundAdmissions;
     private queuedBackgroundAdmissions;
     private readonly waitingCounts;
     constructor(options?: ResourcePoolOptions<Status>);
@@ -90,16 +99,14 @@ export declare class BoundedResourcePool<OwnerKey extends string, Resource exten
     private activePartitions;
     private leastRecentlyUsedIdle;
     private evict;
-    /** Wakes every queued background admission to re-check the real state -- called whenever an entry is removed OR a lease completes (an idle candidate an admit() retry might now be able to evict). A false wake just re-checks and re-waits; never a correctness issue, only a wasted retry. */
+    /** Wakes one waiter per newly available opportunity, preferring foreground and preserving FIFO within each class. */
     private notifyAdmissionWaiters;
-    /** True while at least one background admission for this owner is currently waiting for a reserved-slot conflict to clear. */
+    /** True while at least one background admission for this owner is waiting. */
     waitingForAdmission(ownerKey: OwnerKey): boolean;
-    /**
-     * Runs entirely outside the serialized admission lock -- admissionTail is the single global
-     * admission mutex, and this wait can legitimately take up to backgroundAdmissionQueueTimeoutMs.
-     * Holding that lock for the whole wait would block every other admission request, foreground
-     * included, which is the exact starvation this exists to prevent.
-     */
+    private waitTimeoutMs;
+    private canWait;
+    private capacityUnavailable;
+    /** Waits outside the serialized admission lock, with one total deadline across false wakes. */
     private waitForAdmissionRoom;
     private admit;
     private serialized;

package/dist/resource-pool/bounded-resource-pool.js

@@ -5,14 +5,22 @@ const DEFAULT_MAX_ACTIVE = 3;
 const DEFAULT_ABSOLUTE_MAX_ACTIVE = 32;
 const DEFAULT_BACKGROUND_ADMISSION_QUEUE_TIMEOUT_MS = 10_000;
 const DEFAULT_MAX_QUEUED_BACKGROUND_ADMISSIONS = 8;
+const DEFAULT_FOREGROUND_ADMISSION_QUEUE_TIMEOUT_MS = 0;
+const DEFAULT_MAX_QUEUED_FOREGROUND_ADMISSIONS = 8;
 /**
  * Internal signal only: admit() throws this to tell acquire() "release the serialized lock and
- * wait outside it" -- never surfaced to a caller. Waiting for a background admission's turn can
- * legitimately take seconds; holding admissionTail (the single global admission mutex) for that
- * whole span would block every OTHER admission request, including foreground's, which is exactly
- * the starvation this exists to prevent.
+ * wait outside it" -- never surfaced to a caller. A bounded admission wait can take seconds;
+ * holding admissionTail (the single global admission mutex) for that span would block every other
+ * request and create the starvation this mechanism exists to prevent.
  */
-class NeedsBackgroundAdmissionWait extends Error {
+class NeedsAdmissionWait extends Error {
+    workKind;
+    observedGeneration;
+    constructor(workKind, observedGeneration) {
+        super();
+        this.workKind = workKind;
+        this.observedGeneration = observedGeneration;
+    }
 }
 /**
  * Owns the bounded lifecycle of pooled, expensive, stateful resources partitioned by an
@@ -36,7 +44,11 @@ export class BoundedResourcePool {
     reservedForegroundSlots;
     backgroundAdmissionQueueTimeoutMs;
     maxQueuedBackgroundAdmissions;
-    admissionWaiters = new Set();
+    foregroundAdmissionQueueTimeoutMs;
+    maxQueuedForegroundAdmissions;
+    admissionWaiters = [];
+    admissionGeneration = 0;
+    queuedForegroundAdmissions = 0;
     queuedBackgroundAdmissions = 0;
     waitingCounts = new Map();
     constructor(options = {}) {
@@ -67,6 +79,14 @@ export class BoundedResourcePool {
         if (!Number.isSafeInteger(this.maxQueuedBackgroundAdmissions) || this.maxQueuedBackgroundAdmissions < 1) {
             throw new TypeError("maxQueuedBackgroundAdmissions must be a positive safe integer");
         }
+        this.foregroundAdmissionQueueTimeoutMs = options.foregroundAdmissionQueueTimeoutMs ?? DEFAULT_FOREGROUND_ADMISSION_QUEUE_TIMEOUT_MS;
+        if (!Number.isSafeInteger(this.foregroundAdmissionQueueTimeoutMs) || this.foregroundAdmissionQueueTimeoutMs < 0) {
+            throw new TypeError("foregroundAdmissionQueueTimeoutMs must be a non-negative safe integer");
+        }
+        this.maxQueuedForegroundAdmissions = options.maxQueuedForegroundAdmissions ?? DEFAULT_MAX_QUEUED_FOREGROUND_ADMISSIONS;
+        if (!Number.isSafeInteger(this.maxQueuedForegroundAdmissions) || this.maxQueuedForegroundAdmissions < 1) {
+            throw new TypeError("maxQueuedForegroundAdmissions must be a positive safe integer");
+        }
     }
     key(ownerKey, partitionKey) {
         return `${ownerKey}:${partitionKey}`;
@@ -116,73 +136,103 @@ export class BoundedResourcePool {
         this.options.observe?.({ kind, partitionKey: entry[1].partitionKey });
         this.notifyAdmissionWaiters();
     }
-    /** Wakes every queued background admission to re-check the real state -- called whenever an entry is removed OR a lease completes (an idle candidate an admit() retry might now be able to evict). A false wake just re-checks and re-waits; never a correctness issue, only a wasted retry. */
+    /** Wakes one waiter per newly available opportunity, preferring foreground and preserving FIFO within each class. */
     notifyAdmissionWaiters() {
-        if (this.admissionWaiters.size === 0)
+        this.admissionGeneration++;
+        if (this.admissionWaiters.length === 0)
             return;
-        const waiters = Array.from(this.admissionWaiters);
-        this.admissionWaiters.clear();
-        for (const waiter of waiters)
-            waiter();
+        const foregroundIndex = this.admissionWaiters.findIndex((waiter) => waiter.workKind === "foreground");
+        const [waiter] = this.admissionWaiters.splice(foregroundIndex === -1 ? 0 : foregroundIndex, 1);
+        waiter?.wake();
     }
-    /** True while at least one background admission for this owner is currently waiting for a reserved-slot conflict to clear. */
+    /** True while at least one background admission for this owner is waiting. */
     waitingForAdmission(ownerKey) {
         return (this.waitingCounts.get(ownerKey) ?? 0) > 0;
     }
-    /**
-     * Runs entirely outside the serialized admission lock -- admissionTail is the single global
-     * admission mutex, and this wait can legitimately take up to backgroundAdmissionQueueTimeoutMs.
-     * Holding that lock for the whole wait would block every other admission request, foreground
-     * included, which is the exact starvation this exists to prevent.
-     */
-    async waitForAdmissionRoom(partitionKey, ownerKey) {
-        if (this.queuedBackgroundAdmissions >= this.maxQueuedBackgroundAdmissions) {
-            throw new ResourceAdmissionQueueFull(partitionKey, this.maxQueuedBackgroundAdmissions);
+    waitTimeoutMs(workKind) {
+        return workKind === "foreground" ? this.foregroundAdmissionQueueTimeoutMs : this.backgroundAdmissionQueueTimeoutMs;
+    }
+    canWait(workKind) {
+        return workKind === "background" || this.foregroundAdmissionQueueTimeoutMs > 0;
+    }
+    capacityUnavailable(workKind, partitionKey, maxActive, partitionLimit) {
+        if (this.canWait(workKind))
+            throw new NeedsAdmissionWait(workKind, this.admissionGeneration);
+        throw new ResourceCapacityExceeded(partitionKey, maxActive, partitionLimit);
+    }
+    /** Waits outside the serialized admission lock, with one total deadline across false wakes. */
+    async waitForAdmissionRoom(partitionKey, ownerKey, workKind, deadline, observedGeneration) {
+        // A lease may complete after admit() releases the mutex but before this waiter is registered.
+        // Retry immediately when that happened rather than sleeping through a lost wake-up.
+        if (this.admissionGeneration !== observedGeneration)
+            return;
+        const maxQueued = workKind === "foreground" ? this.maxQueuedForegroundAdmissions : this.maxQueuedBackgroundAdmissions;
+        const queued = workKind === "foreground" ? this.queuedForegroundAdmissions : this.queuedBackgroundAdmissions;
+        if (queued >= maxQueued)
+            throw new ResourceAdmissionQueueFull(partitionKey, maxQueued, workKind);
+        const timeoutMs = this.waitTimeoutMs(workKind);
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0)
+            throw new ResourceAdmissionQueueTimedOut(partitionKey, timeoutMs, workKind);
+        if (workKind === "foreground")
+            this.queuedForegroundAdmissions++;
+        else {
+            this.queuedBackgroundAdmissions++;
+            this.waitingCounts.set(ownerKey, (this.waitingCounts.get(ownerKey) ?? 0) + 1);
         }
-        this.queuedBackgroundAdmissions++;
-        this.waitingCounts.set(ownerKey, (this.waitingCounts.get(ownerKey) ?? 0) + 1);
         try {
             const gotSignal = await new Promise((resolve) => {
                 let settled = false;
+                let timer;
+                const waiter = {
+                    workKind,
+                    wake: () => finish(true),
+                };
                 const finish = (ready) => {
                     if (settled)
                         return;
                     settled = true;
                     clearTimeout(timer);
-                    this.admissionWaiters.delete(onSignal);
+                    const index = this.admissionWaiters.indexOf(waiter);
+                    if (index !== -1)
+                        this.admissionWaiters.splice(index, 1);
                     resolve(ready);
                 };
-                const onSignal = () => finish(true);
-                const timer = setTimeout(() => finish(false), this.backgroundAdmissionQueueTimeoutMs);
-                this.admissionWaiters.add(onSignal);
+                timer = setTimeout(() => finish(false), remainingMs);
+                this.admissionWaiters.push(waiter);
             });
             if (!gotSignal)
-                throw new ResourceAdmissionQueueTimedOut(partitionKey, this.backgroundAdmissionQueueTimeoutMs);
+                throw new ResourceAdmissionQueueTimedOut(partitionKey, timeoutMs, workKind);
         }
         finally {
-            this.queuedBackgroundAdmissions--;
-            const remaining = (this.waitingCounts.get(ownerKey) ?? 1) - 1;
-            if (remaining <= 0)
-                this.waitingCounts.delete(ownerKey);
-            else
-                this.waitingCounts.set(ownerKey, remaining);
+            if (workKind === "foreground")
+                this.queuedForegroundAdmissions--;
+            else {
+                this.queuedBackgroundAdmissions--;
+                const remaining = (this.waitingCounts.get(ownerKey) ?? 1) - 1;
+                if (remaining <= 0)
+                    this.waitingCounts.delete(ownerKey);
+                else
+                    this.waitingCounts.set(ownerKey, remaining);
+            }
         }
     }
-    async admit(ownerKey, partitionKey, create, workKind) {
+    async admit(ownerKey, partitionKey, create, workKind, admissionGranted) {
         const partitionLimit = this.partitionLimit(partitionKey);
+        if (this.queuedForegroundAdmissions > 0 && !(workKind === "foreground" && admissionGranted)) {
+            throw new NeedsAdmissionWait(workKind, this.admissionGeneration);
+        }
         while (this.countPartition(partitionKey) >= partitionLimit) {
             const victim = this.leastRecentlyUsedIdle(partitionKey);
             if (!victim)
-                throw new ResourceCapacityExceeded(partitionKey, this.maxActive, partitionLimit);
+                this.capacityUnavailable(workKind, partitionKey, this.maxActive, partitionLimit);
             await this.evict(victim);
         }
         const { ceiling: baseCeiling, source: ceilingSource } = this.baseActiveCeiling();
         this.lastEffectiveMaxActive = baseCeiling;
         this.lastActiveCeilingSource = ceilingSource;
-        // "Borrowable": background's own effective ceiling is reduced, but only background is ever
-        // held to it -- it constrains what background alone can grow the pool into, not a hard
-        // set-aside nothing else can reach. Foreground keeps using the full (possibly resource-
-        // budget-raised) baseCeiling unchanged.
+        // "Borrowable": background's own effective ceiling is reduced, while foreground keeps the
+        // full (possibly resource-budget-raised) base ceiling unchanged.
         const effectiveMaxActive = workKind === "background" ? Math.max(baseCeiling - this.reservedForegroundSlots, 0) : baseCeiling;
         while (this.entries.size >= effectiveMaxActive) {
             const victim = this.leastRecentlyUsedIdle();
@@ -190,14 +240,12 @@ export class BoundedResourcePool {
                 await this.evict(victim);
                 continue;
             }
-            if (workKind === "background")
-                throw new NeedsBackgroundAdmissionWait();
-            throw new ResourceCapacityExceeded(partitionKey, baseCeiling, partitionLimit);
+            this.capacityUnavailable(workKind, partitionKey, baseCeiling, partitionLimit);
         }
         while (this.options.resourcePolicy && !this.options.resourcePolicy.canAdmit(this.activePartitions(), partitionKey)) {
             const victim = this.leastRecentlyUsedIdle();
             if (!victim)
-                throw new ResourceCapacityExceeded(partitionKey, baseCeiling, partitionLimit);
+                this.capacityUnavailable(workKind, partitionKey, baseCeiling, partitionLimit);
             await this.evict(victim, "resource-pressure");
         }
         return {
@@ -225,6 +273,8 @@ export class BoundedResourcePool {
     }
     /** Acquires a lease for (ownerKey, partitionKey), reusing an already-admitted resource if one is warm, or admitting a fresh one via `create()` -- called only on an actual cache miss, never speculatively. workKind defaults to "foreground". */
     async acquire(ownerKey, partitionKey, create, workKind = "foreground") {
+        const deadline = Date.now() + this.waitTimeoutMs(workKind);
+        let admissionGranted = false;
         for (;;) {
             try {
                 const entry = await this.serialized(async () => {
@@ -238,7 +288,7 @@ export class BoundedResourcePool {
                         entry = undefined;
                     }
                     if (!entry) {
-                        entry = await this.admit(ownerKey, partitionKey, create, workKind);
+                        entry = await this.admit(ownerKey, partitionKey, create, workKind, admissionGranted);
                         this.entries.set(key, entry);
                     }
                     entry.activeLeases++;
@@ -247,11 +297,10 @@ export class BoundedResourcePool {
                 return this.lease(entry.resource, [entry]);
             }
             catch (error) {
-                if (!(error instanceof NeedsBackgroundAdmissionWait))
+                if (!(error instanceof NeedsAdmissionWait))
                     throw error;
-                // Outside the lock deliberately -- see waitForAdmissionRoom's own comment. Throws
-                // ResourceAdmissionQueueFull/TimedOut instead of looping back if it can't wait.
-                await this.waitForAdmissionRoom(partitionKey, ownerKey);
+                await this.waitForAdmissionRoom(partitionKey, ownerKey, error.workKind, deadline, error.observedGeneration);
+                admissionGranted = true;
             }
         }
     }
@@ -270,8 +319,7 @@ export class BoundedResourcePool {
                     entry.recencySequence = this.nextSequence++;
                 }
                 // A lease completing makes its entry newly idle -- exactly the condition a queued
-                // background admission's retry is waiting to find, whether or not resource pressure
-                // itself ends up evicting anything below.
+                // admission retries against.
                 this.notifyAdmissionWaiters();
                 await this.reconcileResources();
             },
@@ -324,6 +372,7 @@ export class BoundedResourcePool {
             activeCeilingSource: this.lastActiveCeilingSource,
             absoluteMaxActive: this.absoluteMaxActive,
             byPartition,
+            waitingForegroundAdmissions: this.queuedForegroundAdmissions,
             waitingBackgroundAdmissions: this.queuedBackgroundAdmissions,
             ...(resources !== undefined ? { resources } : {}),
         };
@@ -344,6 +393,8 @@ export class BoundedResourcePool {
         const stale = Array.from(this.entries.entries()).filter(([, entry]) => entry.ownerKey === ownerKey);
         for (const [key] of stale)
             this.entries.delete(key);
+        for (let i = 0; i < stale.length; i++)
+            this.notifyAdmissionWaiters();
         await Promise.all(stale.map(([, entry]) => entry.resource.close()));
     }
     /** Unconditional force-close of one (ownerKey, partitionKey) resource, if any -- the single-partition sibling of closeOwner, for a caller that has already identified exactly which partition needs invalidating. */
@@ -353,6 +404,7 @@ export class BoundedResourcePool {
         if (!entry)
             return;
         this.entries.delete(key);
+        this.notifyAdmissionWaiters();
         await entry.resource.close();
     }
     /**
@@ -373,6 +425,8 @@ export class BoundedResourcePool {
     async closeAll() {
         const entries = Array.from(this.entries.values());
         this.entries.clear();
+        for (let i = 0; i < entries.length; i++)
+            this.notifyAdmissionWaiters();
         await Promise.all(entries.map((entry) => entry.resource.close()));
     }
     async reconcileResourcesUnsafe() {

package/dist/resource-pool/errors.d.ts

@@ -10,15 +10,17 @@ export declare class ResourceInUse extends Error {
     readonly ownerKey: string;
     constructor(ownerKey: string);
 }
-/** Raised when background admission is already waiting at maxQueuedBackgroundAdmissions -- fails fast rather than growing the wait queue without bound. */
+/** Raised when one admission class is already at its configured queue bound. */
 export declare class ResourceAdmissionQueueFull extends Error {
     readonly partitionKey: string;
     readonly maxQueued: number;
-    constructor(partitionKey: string, maxQueued: number);
+    readonly workKind: "foreground" | "background";
+    constructor(partitionKey: string, maxQueued: number, workKind?: "foreground" | "background");
 }
-/** Raised when a queued background admission waits past backgroundAdmissionQueueTimeoutMs without a slot freeing. */
+/** Raised when a queued admission waits past its configured timeout without room becoming available. */
 export declare class ResourceAdmissionQueueTimedOut extends Error {
     readonly partitionKey: string;
     readonly timeoutMs: number;
-    constructor(partitionKey: string, timeoutMs: number);
+    readonly workKind: "foreground" | "background";
+    constructor(partitionKey: string, timeoutMs: number, workKind?: "foreground" | "background");
 }

package/dist/resource-pool/errors.js

@@ -20,25 +20,29 @@ export class ResourceInUse extends Error {
         this.name = "ResourceInUse";
     }
 }
-/** Raised when background admission is already waiting at maxQueuedBackgroundAdmissions -- fails fast rather than growing the wait queue without bound. */
+/** Raised when one admission class is already at its configured queue bound. */
 export class ResourceAdmissionQueueFull extends Error {
     partitionKey;
     maxQueued;
-    constructor(partitionKey, maxQueued) {
-        super(`background admission for partition "${partitionKey}" is already waiting at capacity (${maxQueued} queued); retry later`);
+    workKind;
+    constructor(partitionKey, maxQueued, workKind = "background") {
+        super(`${workKind} admission for partition "${partitionKey}" is already waiting at capacity (${maxQueued} queued); retry later`);
         this.partitionKey = partitionKey;
         this.maxQueued = maxQueued;
+        this.workKind = workKind;
         this.name = "ResourceAdmissionQueueFull";
     }
 }
-/** Raised when a queued background admission waits past backgroundAdmissionQueueTimeoutMs without a slot freeing. */
+/** Raised when a queued admission waits past its configured timeout without room becoming available. */
 export class ResourceAdmissionQueueTimedOut extends Error {
     partitionKey;
     timeoutMs;
-    constructor(partitionKey, timeoutMs) {
-        super(`background admission for partition "${partitionKey}" waited ${timeoutMs}ms for a resource-pool slot and gave up -- foreground demand is holding every admittable slot`);
+    workKind;
+    constructor(partitionKey, timeoutMs, workKind = "background") {
+        super(`${workKind} admission for partition "${partitionKey}" waited ${timeoutMs}ms for a resource-pool slot and gave up`);
         this.partitionKey = partitionKey;
         this.timeoutMs = timeoutMs;
+        this.workKind = workKind;
         this.name = "ResourceAdmissionQueueTimedOut";
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/vehicle-core",
-	"version": "0.18.5",
+	"version": "0.19.0",
 	"description": "Vehicle's runtime-neutral wire contract: operation descriptors, schema codecs, failure shapes. Zero runtime dependencies, zero Bun-specific code -- the one thing every Vehicle client and server package depends on.",
 	"license": "MIT",
 	"type": "module",

package/src/approvals/approval.ts

@@ -42,6 +42,21 @@ export const DEFAULT_APPROVAL_EFFECTS: readonly VehicleEffect[] = ["destructive"
  */
 export const VEHICLE_APPROVAL_RESOLVE_OPERATION_NAME = "vehicle.approval.resolve";
 
+/**
+ * The name VehicleRegistry.configureApprovals() registers its own read-only status-lookup
+ * operation under. Unlike vehicle.approval.resolve, this one is deliberately left projectable
+ * as an ordinary Pi/model-callable tool: reading a requestId's own already-made decision (who
+ * decided, when, and any comment) can never let a caller grant its own pending request -- it
+ * only ever surfaces a decision a human (or other authority) already recorded. Exists because a
+ * gated invoke()'s own local HITL prompt and the eventual human decision can genuinely happen on
+ * two different calls (a caller-side timeout, a UI presented asynchronously outside the
+ * originating call's own lifetime, a session restart in between) -- without this, a decision
+ * (and any comment explaining it) made after the originating call already gave up is
+ * unrecoverable, since vehicle.approval.resolve's own vehicleApprovalResolvedEvent is transient
+ * pub/sub with no replay for a caller that wasn't subscribed at that exact moment.
+ */
+export const VEHICLE_APPROVAL_STATUS_OPERATION_NAME = "vehicle.approval.status";
+
 /** How long a request stays resolvable before it lapses and must be re-requested. */
 export const DEFAULT_APPROVAL_TIMEOUT_MS = 5 * 60_000;
 

package/src/resource-pool/bounded-resource-pool.ts

@@ -15,23 +15,35 @@ const DEFAULT_MAX_ACTIVE = 3;
 const DEFAULT_ABSOLUTE_MAX_ACTIVE = 32;
 const DEFAULT_BACKGROUND_ADMISSION_QUEUE_TIMEOUT_MS = 10_000;
 const DEFAULT_MAX_QUEUED_BACKGROUND_ADMISSIONS = 8;
+const DEFAULT_FOREGROUND_ADMISSION_QUEUE_TIMEOUT_MS = 0;
+const DEFAULT_MAX_QUEUED_FOREGROUND_ADMISSIONS = 8;
 
 /**
  * Distinguishes an interactive human/agent-facing request from a self-scheduled background one.
- * Foreground admission is never queued or reduced below reservedForegroundSlots' effective
- * ceiling -- background is the only work kind that ever waits. Defaults to "foreground": a caller
- * that never opts in gets today's exact unreserved behavior.
+ * Foreground keeps the full ceiling and remains fail-fast unless its explicit queue timeout is
+ * enabled; background can be held below the reserved-slot ceiling. Defaults to "foreground".
  */
 export type ResourceWorkKind = "foreground" | "background";
 
 /**
  * Internal signal only: admit() throws this to tell acquire() "release the serialized lock and
- * wait outside it" -- never surfaced to a caller. Waiting for a background admission's turn can
- * legitimately take seconds; holding admissionTail (the single global admission mutex) for that
- * whole span would block every OTHER admission request, including foreground's, which is exactly
- * the starvation this exists to prevent.
+ * wait outside it" -- never surfaced to a caller. A bounded admission wait can take seconds;
+ * holding admissionTail (the single global admission mutex) for that span would block every other
+ * request and create the starvation this mechanism exists to prevent.
  */
-class NeedsBackgroundAdmissionWait extends Error {}
+class NeedsAdmissionWait extends Error {
+	constructor(
+		readonly workKind: ResourceWorkKind,
+		readonly observedGeneration: number,
+	) {
+		super();
+	}
+}
+
+interface AdmissionWaiter {
+	readonly workKind: ResourceWorkKind;
+	readonly wake: () => void;
+}
 
 export type ResourcePoolEvent =
 	| { readonly kind: "admission-evicted" | "dead-replaced" | "resource-pressure-evicted"; readonly partitionKey: string }
@@ -52,7 +64,9 @@ export interface ResourcePoolStatus<Status = unknown> {
 	readonly absoluteMaxActive: number;
 	readonly byPartition: Readonly<Record<string, number>>;
 	readonly resources?: Status;
-	/** How many background admissions are currently waiting for a slot reserved for foreground work -- count-only, zero whenever reservedForegroundSlots is unset or nothing is contending. */
+	/** How many opt-in foreground admissions are waiting for a lease to free. */
+	readonly waitingForegroundAdmissions: number;
+	/** How many background admissions are waiting for room below their effective ceiling. */
 	readonly waitingBackgroundAdmissions: number;
 }
 
@@ -73,6 +87,10 @@ export interface ResourcePoolOptions<Status = unknown> {
 	readonly backgroundAdmissionQueueTimeoutMs?: number;
 	/** How many background admissions may be simultaneously waiting before a new one fails fast with ResourceAdmissionQueueFull instead of growing the wait queue further. Default 8. */
 	readonly maxQueuedBackgroundAdmissions?: number;
+	/** Opt-in foreground wait bound. Zero (default) preserves fail-fast ResourceCapacityExceeded behavior. */
+	readonly foregroundAdmissionQueueTimeoutMs?: number;
+	/** How many opted-in foreground admissions may wait simultaneously. Default 8. */
+	readonly maxQueuedForegroundAdmissions?: number;
 	/** Fed one (partitionKey, costHandle) pair per active entry with a costHandle on calibrateCosts(). */
 	readonly costRecorder?: { recordSample(partitionKey: string, costHandle: unknown): void };
 	readonly now?: () => number;
@@ -108,7 +126,11 @@ export class BoundedResourcePool<OwnerKey extends string, Resource extends Poole
 	private readonly reservedForegroundSlots: number;
 	private readonly backgroundAdmissionQueueTimeoutMs: number;
 	private readonly maxQueuedBackgroundAdmissions: number;
-	private readonly admissionWaiters = new Set<() => void>();
+	private readonly foregroundAdmissionQueueTimeoutMs: number;
+	private readonly maxQueuedForegroundAdmissions: number;
+	private readonly admissionWaiters: AdmissionWaiter[] = [];
+	private admissionGeneration = 0;
+	private queuedForegroundAdmissions = 0;
 	private queuedBackgroundAdmissions = 0;
 	private readonly waitingCounts = new Map<string, number>();
 
@@ -138,6 +160,14 @@ export class BoundedResourcePool<OwnerKey extends string, Resource extends Poole
 		if (!Number.isSafeInteger(this.maxQueuedBackgroundAdmissions) || this.maxQueuedBackgroundAdmissions < 1) {
 			throw new TypeError("maxQueuedBackgroundAdmissions must be a positive safe integer");
 		}
+		this.foregroundAdmissionQueueTimeoutMs = options.foregroundAdmissionQueueTimeoutMs ?? DEFAULT_FOREGROUND_ADMISSION_QUEUE_TIMEOUT_MS;
+		if (!Number.isSafeInteger(this.foregroundAdmissionQueueTimeoutMs) || this.foregroundAdmissionQueueTimeoutMs < 0) {
+			throw new TypeError("foregroundAdmissionQueueTimeoutMs must be a non-negative safe integer");
+		}
+		this.maxQueuedForegroundAdmissions = options.maxQueuedForegroundAdmissions ?? DEFAULT_MAX_QUEUED_FOREGROUND_ADMISSIONS;
+		if (!Number.isSafeInteger(this.maxQueuedForegroundAdmissions) || this.maxQueuedForegroundAdmissions < 1) {
+			throw new TypeError("maxQueuedForegroundAdmissions must be a positive safe integer");
+		}
 	}
 
 	private key(ownerKey: OwnerKey, partitionKey: string): string {
@@ -196,51 +226,84 @@ export class BoundedResourcePool<OwnerKey extends string, Resource extends Poole
 		this.notifyAdmissionWaiters();
 	}
 
-	/** Wakes every queued background admission to re-check the real state -- called whenever an entry is removed OR a lease completes (an idle candidate an admit() retry might now be able to evict). A false wake just re-checks and re-waits; never a correctness issue, only a wasted retry. */
+	/** Wakes one waiter per newly available opportunity, preferring foreground and preserving FIFO within each class. */
 	private notifyAdmissionWaiters(): void {
-		if (this.admissionWaiters.size === 0) return;
-		const waiters = Array.from(this.admissionWaiters);
-		this.admissionWaiters.clear();
-		for (const waiter of waiters) waiter();
+		this.admissionGeneration++;
+		if (this.admissionWaiters.length === 0) return;
+		const foregroundIndex = this.admissionWaiters.findIndex((waiter) => waiter.workKind === "foreground");
+		const [waiter] = this.admissionWaiters.splice(foregroundIndex === -1 ? 0 : foregroundIndex, 1);
+		waiter?.wake();
 	}
 
-	/** True while at least one background admission for this owner is currently waiting for a reserved-slot conflict to clear. */
+	/** True while at least one background admission for this owner is waiting. */
 	waitingForAdmission(ownerKey: OwnerKey): boolean {
 		return (this.waitingCounts.get(ownerKey) ?? 0) > 0;
 	}
 
-	/**
-	 * Runs entirely outside the serialized admission lock -- admissionTail is the single global
-	 * admission mutex, and this wait can legitimately take up to backgroundAdmissionQueueTimeoutMs.
-	 * Holding that lock for the whole wait would block every other admission request, foreground
-	 * included, which is the exact starvation this exists to prevent.
-	 */
-	private async waitForAdmissionRoom(partitionKey: string, ownerKey: OwnerKey): Promise<void> {
-		if (this.queuedBackgroundAdmissions >= this.maxQueuedBackgroundAdmissions) {
-			throw new ResourceAdmissionQueueFull(partitionKey, this.maxQueuedBackgroundAdmissions);
+	private waitTimeoutMs(workKind: ResourceWorkKind): number {
+		return workKind === "foreground" ? this.foregroundAdmissionQueueTimeoutMs : this.backgroundAdmissionQueueTimeoutMs;
+	}
+
+	private canWait(workKind: ResourceWorkKind): boolean {
+		return workKind === "background" || this.foregroundAdmissionQueueTimeoutMs > 0;
+	}
+
+	private capacityUnavailable(workKind: ResourceWorkKind, partitionKey: string, maxActive: number, partitionLimit: number): never {
+		if (this.canWait(workKind)) throw new NeedsAdmissionWait(workKind, this.admissionGeneration);
+		throw new ResourceCapacityExceeded(partitionKey, maxActive, partitionLimit);
+	}
+
+	/** Waits outside the serialized admission lock, with one total deadline across false wakes. */
+	private async waitForAdmissionRoom(
+		partitionKey: string,
+		ownerKey: OwnerKey,
+		workKind: ResourceWorkKind,
+		deadline: number,
+		observedGeneration: number,
+	): Promise<void> {
+		// A lease may complete after admit() releases the mutex but before this waiter is registered.
+		// Retry immediately when that happened rather than sleeping through a lost wake-up.
+		if (this.admissionGeneration !== observedGeneration) return;
+		const maxQueued = workKind === "foreground" ? this.maxQueuedForegroundAdmissions : this.maxQueuedBackgroundAdmissions;
+		const queued = workKind === "foreground" ? this.queuedForegroundAdmissions : this.queuedBackgroundAdmissions;
+		if (queued >= maxQueued) throw new ResourceAdmissionQueueFull(partitionKey, maxQueued, workKind);
+		const timeoutMs = this.waitTimeoutMs(workKind);
+		const remainingMs = deadline - Date.now();
+		if (remainingMs <= 0) throw new ResourceAdmissionQueueTimedOut(partitionKey, timeoutMs, workKind);
+
+		if (workKind === "foreground") this.queuedForegroundAdmissions++;
+		else {
+			this.queuedBackgroundAdmissions++;
+			this.waitingCounts.set(ownerKey, (this.waitingCounts.get(ownerKey) ?? 0) + 1);
 		}
-		this.queuedBackgroundAdmissions++;
-		this.waitingCounts.set(ownerKey, (this.waitingCounts.get(ownerKey) ?? 0) + 1);
 		try {
 			const gotSignal = await new Promise<boolean>((resolve) => {
 				let settled = false;
+				let timer: ReturnType<typeof setTimeout>;
+				const waiter: AdmissionWaiter = {
+					workKind,
+					wake: () => finish(true),
+				};
 				const finish = (ready: boolean): void => {
 					if (settled) return;
 					settled = true;
 					clearTimeout(timer);
-					this.admissionWaiters.delete(onSignal);
+					const index = this.admissionWaiters.indexOf(waiter);
+					if (index !== -1) this.admissionWaiters.splice(index, 1);
 					resolve(ready);
 				};
-				const onSignal = (): void => finish(true);
-				const timer = setTimeout(() => finish(false), this.backgroundAdmissionQueueTimeoutMs);
-				this.admissionWaiters.add(onSignal);
+				timer = setTimeout(() => finish(false), remainingMs);
+				this.admissionWaiters.push(waiter);
 			});
-			if (!gotSignal) throw new ResourceAdmissionQueueTimedOut(partitionKey, this.backgroundAdmissionQueueTimeoutMs);
+			if (!gotSignal) throw new ResourceAdmissionQueueTimedOut(partitionKey, timeoutMs, workKind);
 		} finally {
-			this.queuedBackgroundAdmissions--;
-			const remaining = (this.waitingCounts.get(ownerKey) ?? 1) - 1;
-			if (remaining <= 0) this.waitingCounts.delete(ownerKey);
-			else this.waitingCounts.set(ownerKey, remaining);
+			if (workKind === "foreground") this.queuedForegroundAdmissions--;
+			else {
+				this.queuedBackgroundAdmissions--;
+				const remaining = (this.waitingCounts.get(ownerKey) ?? 1) - 1;
+				if (remaining <= 0) this.waitingCounts.delete(ownerKey);
+				else this.waitingCounts.set(ownerKey, remaining);
+			}
 		}
 	}
 
@@ -249,20 +312,22 @@ export class BoundedResourcePool<OwnerKey extends string, Resource extends Poole
 		partitionKey: string,
 		create: () => Resource,
 		workKind: ResourceWorkKind,
+		admissionGranted: boolean,
 	): Promise<PoolEntry<OwnerKey, Resource>> {
 		const partitionLimit = this.partitionLimit(partitionKey);
+		if (this.queuedForegroundAdmissions > 0 && !(workKind === "foreground" && admissionGranted)) {
+			throw new NeedsAdmissionWait(workKind, this.admissionGeneration);
+		}
 		while (this.countPartition(partitionKey) >= partitionLimit) {
 			const victim = this.leastRecentlyUsedIdle(partitionKey);
-			if (!victim) throw new ResourceCapacityExceeded(partitionKey, this.maxActive, partitionLimit);
+			if (!victim) this.capacityUnavailable(workKind, partitionKey, this.maxActive, partitionLimit);
 			await this.evict(victim);
 		}
 		const { ceiling: baseCeiling, source: ceilingSource } = this.baseActiveCeiling();
 		this.lastEffectiveMaxActive = baseCeiling;
 		this.lastActiveCeilingSource = ceilingSource;
-		// "Borrowable": background's own effective ceiling is reduced, but only background is ever
-		// held to it -- it constrains what background alone can grow the pool into, not a hard
-		// set-aside nothing else can reach. Foreground keeps using the full (possibly resource-
-		// budget-raised) baseCeiling unchanged.
+		// "Borrowable": background's own effective ceiling is reduced, while foreground keeps the
+		// full (possibly resource-budget-raised) base ceiling unchanged.
 		const effectiveMaxActive = workKind === "background" ? Math.max(baseCeiling - this.reservedForegroundSlots, 0) : baseCeiling;
 		while (this.entries.size >= effectiveMaxActive) {
 			const victim = this.leastRecentlyUsedIdle();
@@ -270,12 +335,11 @@ export class BoundedResourcePool<OwnerKey extends string, Resource extends Poole
 				await this.evict(victim);
 				continue;
 			}
-			if (workKind === "background") throw new NeedsBackgroundAdmissionWait();
-			throw new ResourceCapacityExceeded(partitionKey, baseCeiling, partitionLimit);
+			this.capacityUnavailable(workKind, partitionKey, baseCeiling, partitionLimit);
 		}
 		while (this.options.resourcePolicy && !this.options.resourcePolicy.canAdmit(this.activePartitions(), partitionKey)) {
 			const victim = this.leastRecentlyUsedIdle();
-			if (!victim) throw new ResourceCapacityExceeded(partitionKey, baseCeiling, partitionLimit);
+			if (!victim) this.capacityUnavailable(workKind, partitionKey, baseCeiling, partitionLimit);
 			await this.evict(victim, "resource-pressure");
 		}
 		return {
@@ -309,6 +373,8 @@ export class BoundedResourcePool<OwnerKey extends string, Resource extends Poole
 		create: () => Resource,
 		workKind: ResourceWorkKind = "foreground",
 	): Promise<PoolLease<Resource>> {
+		const deadline = Date.now() + this.waitTimeoutMs(workKind);
+		let admissionGranted = false;
 		for (;;) {
 			try {
 				const entry = await this.serialized(async () => {
@@ -322,7 +388,7 @@ export class BoundedResourcePool<OwnerKey extends string, Resource extends Poole
 						entry = undefined;
 					}
 					if (!entry) {
-						entry = await this.admit(ownerKey, partitionKey, create, workKind);
+						entry = await this.admit(ownerKey, partitionKey, create, workKind, admissionGranted);
 						this.entries.set(key, entry);
 					}
 					entry.activeLeases++;
@@ -330,10 +396,9 @@ export class BoundedResourcePool<OwnerKey extends string, Resource extends Poole
 				});
 				return this.lease(entry.resource, [entry]);
 			} catch (error) {
-				if (!(error instanceof NeedsBackgroundAdmissionWait)) throw error;
-				// Outside the lock deliberately -- see waitForAdmissionRoom's own comment. Throws
-				// ResourceAdmissionQueueFull/TimedOut instead of looping back if it can't wait.
-				await this.waitForAdmissionRoom(partitionKey, ownerKey);
+				if (!(error instanceof NeedsAdmissionWait)) throw error;
+				await this.waitForAdmissionRoom(partitionKey, ownerKey, error.workKind, deadline, error.observedGeneration);
+				admissionGranted = true;
 			}
 		}
 	}
@@ -352,8 +417,7 @@ export class BoundedResourcePool<OwnerKey extends string, Resource extends Poole
 					entry.recencySequence = this.nextSequence++;
 				}
 				// A lease completing makes its entry newly idle -- exactly the condition a queued
-				// background admission's retry is waiting to find, whether or not resource pressure
-				// itself ends up evicting anything below.
+				// admission retries against.
 				this.notifyAdmissionWaiters();
 				await this.reconcileResources();
 			},
@@ -405,6 +469,7 @@ export class BoundedResourcePool<OwnerKey extends string, Resource extends Poole
 			activeCeilingSource: this.lastActiveCeilingSource,
 			absoluteMaxActive: this.absoluteMaxActive,
 			byPartition,
+			waitingForegroundAdmissions: this.queuedForegroundAdmissions,
 			waitingBackgroundAdmissions: this.queuedBackgroundAdmissions,
 			...(resources !== undefined ? { resources } : {}),
 		};
@@ -424,6 +489,7 @@ export class BoundedResourcePool<OwnerKey extends string, Resource extends Poole
 	async closeOwner(ownerKey: OwnerKey): Promise<void> {
 		const stale = Array.from(this.entries.entries()).filter(([, entry]) => entry.ownerKey === ownerKey);
 		for (const [key] of stale) this.entries.delete(key);
+		for (let i = 0; i < stale.length; i++) this.notifyAdmissionWaiters();
 		await Promise.all(stale.map(([, entry]) => entry.resource.close()));
 	}
 
@@ -433,6 +499,7 @@ export class BoundedResourcePool<OwnerKey extends string, Resource extends Poole
 		const entry = this.entries.get(key);
 		if (!entry) return;
 		this.entries.delete(key);
+		this.notifyAdmissionWaiters();
 		await entry.resource.close();
 	}
 
@@ -453,6 +520,7 @@ export class BoundedResourcePool<OwnerKey extends string, Resource extends Poole
 	async closeAll(): Promise<void> {
 		const entries = Array.from(this.entries.values());
 		this.entries.clear();
+		for (let i = 0; i < entries.length; i++) this.notifyAdmissionWaiters();
 		await Promise.all(entries.map((entry) => entry.resource.close()));
 	}
 

package/src/resource-pool/errors.ts

@@ -20,26 +20,26 @@ export class ResourceInUse extends Error {
 	}
 }
 
-/** Raised when background admission is already waiting at maxQueuedBackgroundAdmissions -- fails fast rather than growing the wait queue without bound. */
+/** Raised when one admission class is already at its configured queue bound. */
 export class ResourceAdmissionQueueFull extends Error {
 	constructor(
 		readonly partitionKey: string,
 		readonly maxQueued: number,
+		readonly workKind: "foreground" | "background" = "background",
 	) {
-		super(`background admission for partition "${partitionKey}" is already waiting at capacity (${maxQueued} queued); retry later`);
+		super(`${workKind} admission for partition "${partitionKey}" is already waiting at capacity (${maxQueued} queued); retry later`);
 		this.name = "ResourceAdmissionQueueFull";
 	}
 }
 
-/** Raised when a queued background admission waits past backgroundAdmissionQueueTimeoutMs without a slot freeing. */
+/** Raised when a queued admission waits past its configured timeout without room becoming available. */
 export class ResourceAdmissionQueueTimedOut extends Error {
 	constructor(
 		readonly partitionKey: string,
 		readonly timeoutMs: number,
+		readonly workKind: "foreground" | "background" = "background",
 	) {
-		super(
-			`background admission for partition "${partitionKey}" waited ${timeoutMs}ms for a resource-pool slot and gave up -- foreground demand is holding every admittable slot`,
-		);
+		super(`${workKind} admission for partition "${partitionKey}" waited ${timeoutMs}ms for a resource-pool slot and gave up`);
 		this.name = "ResourceAdmissionQueueTimedOut";
 	}
 }