@proteinjs/server 3.5.2 → 3.6.0

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [3.6.0](https://github.com/proteinjs/server/compare/@proteinjs/server@3.5.3...@proteinjs/server@3.6.0) (2026-09-10)
+
+
+### Features
+
+* **server:** GracefulShutdown holds — the SIGTERM drain waits for work no connection represents (a detached chat turn), bounded by shutdown.turnDrainMs ([b534d68](https://github.com/proteinjs/server/commit/b534d68ab14f925a686cb338466ebabd4b40ef75))
+
+
+
+
+
+## [3.5.3](https://github.com/proteinjs/server/compare/@proteinjs/server@3.5.2...@proteinjs/server@3.5.3) (2026-09-01)
+
+
+### Bug Fixes
+
+* **server:** the react-app HTML response says Cache-Control: no-cache — the page always revalidates (found live 2026-09-01, the mobile-app stale-page investigation). The '*' route sent HTML with an ETag but NO Cache-Control: with no explicit policy, HTTP heuristic caching applies (RFC 9111 §4.2.2) and WKWebView in particular can serve the cached page without revalidating — across app force-quits — pinning stale bundle POINTERS long after a deploy. The hashed bundles under /static keep their long cache (a fresh page always points at fresh hashes); the PAGE must always revalidate. no-cache + the ETag express already stamps = a cheap 304 on every load, never a stale page. Red-before-green: htmlCacheControl.test.ts (front door — a real spawned server, the LB's X-Forwarded-Proto topology) read cache-control undefined at the pre-fix dist (2 red), green after; / and /chat both pinned (the catch-all is the one HTML owner). Fixture gains a bundlePaths pointer so the react-app route serves its page; full estate 5 suites / 11 green (9 pre-existing). ([076536f](https://github.com/proteinjs/server/commit/076536f158ce1c91b073061345fe7aae802b4f38))
+
+
+
+
+
 ## [3.5.2](https://github.com/proteinjs/server/compare/@proteinjs/server@3.5.1...@proteinjs/server@3.5.2) (2026-08-27)
 
 

package/dist/generated/index.js

@@ -33,7 +33,7 @@ require("react-helmet");
 require("socket.io");
 require("typescript");
 /** Generate Source Graph */
-var sourceGraph = "{\"options\":{\"directed\":true,\"multigraph\":false,\"compound\":false},\"nodes\":[{\"v\":\"@proteinjs/server/NodeGlobalDataStorage\",\"value\":{\"packageName\":\"@proteinjs/server\",\"name\":\"NodeGlobalDataStorage\",\"filePath\":\"/home/runner/work/server/server/packages/server/src/NodeGlobalDataStorage.ts\",\"qualifiedName\":\"@proteinjs/server/NodeGlobalDataStorage\",\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\",\"properties\":[{\"name\":\"HOOK_INITIALIZED\",\"type\":null,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":true,\"visibility\":\"private\"},{\"name\":\"GLOBAL_DATA\",\"type\":{\"packageName\":\"@proteinjs/server\",\"name\":\"{ [id: string]: GlobalData }\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server/{ [id: string]: GlobalData }\",\"typeParameters\":null,\"directParents\":null},\"isOptional\":false,\"isAbstract\":false,\"isStatic\":true,\"visibility\":\"private\"},{\"name\":\"environment\",\"type\":null,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\"}],\"methods\":[{\"name\":\"setData\",\"returnType\":null,\"isAsync\":false,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\",\"parameters\":[{\"name\":\"data\",\"type\":{\"packageName\":\"@proteinjs/server-api\",\"name\":\"GlobalData\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server-api/GlobalData\",\"typeParameters\":null,\"directParents\":null}}]},{\"name\":\"getData\",\"returnType\":{\"packageName\":\"@proteinjs/server-api\",\"name\":\"GlobalData\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server-api/GlobalData\",\"typeParameters\":null,\"directParents\":null},\"isAsync\":false,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\",\"parameters\":[]},{\"name\":\"initHook\",\"returnType\":null,\"isAsync\":false,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"private\",\"parameters\":[]}],\"typeParameters\":[],\"directParentInterfaces\":[{\"packageName\":\"@proteinjs/server-api\",\"name\":\"GlobalDataStorage\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server-api/GlobalDataStorage\",\"properties\":[],\"methods\":[],\"typeParameters\":[],\"directParents\":[]}],\"directParentClasses\":[],\"sourceType\":2}},{\"v\":\"@proteinjs/server-api/GlobalDataStorage\"},{\"v\":\"@proteinjs/server/NodeSessionDataStorage\",\"value\":{\"packageName\":\"@proteinjs/server\",\"name\":\"NodeSessionDataStorage\",\"filePath\":\"/home/runner/work/server/server/packages/server/src/NodeSessionDataStorage.ts\",\"qualifiedName\":\"@proteinjs/server/NodeSessionDataStorage\",\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\",\"properties\":[{\"name\":\"HOOK_INITIALIZED\",\"type\":null,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":true,\"visibility\":\"private\"},{\"name\":\"SESSION_DATA\",\"type\":{\"packageName\":\"@proteinjs/server\",\"name\":\"{ [id: string]: SessionData }\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server/{ [id: string]: SessionData }\",\"typeParameters\":null,\"directParents\":null},\"isOptional\":false,\"isAbstract\":false,\"isStatic\":true,\"visibility\":\"private\"},{\"name\":\"environment\",\"type\":null,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\"}],\"methods\":[{\"name\":\"setData\",\"returnType\":null,\"isAsync\":false,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\",\"parameters\":[{\"name\":\"data\",\"type\":{\"packageName\":\"@proteinjs/server-api\",\"name\":\"SessionData\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server-api/SessionData\",\"typeParameters\":null,\"directParents\":null}}]},{\"name\":\"getData\",\"returnType\":{\"packageName\":\"@proteinjs/server-api\",\"name\":\"SessionData\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server-api/SessionData\",\"typeParameters\":null,\"directParents\":null},\"isAsync\":false,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\",\"parameters\":[]},{\"name\":\"clearData\",\"returnType\":{\"packageName\":\"\",\"name\":\"void\",\"filePath\":null,\"qualifiedName\":\"/void\",\"typeParameters\":null,\"directParents\":null},\"isAsync\":false,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\",\"parameters\":[]},{\"name\":\"initHook\",\"returnType\":null,\"isAsync\":false,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"private\",\"parameters\":[]}],\"typeParameters\":[],\"directParentInterfaces\":[{\"packageName\":\"@proteinjs/server-api\",\"name\":\"SessionDataStorage\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server-api/SessionDataStorage\",\"properties\":[],\"methods\":[],\"typeParameters\":[],\"directParents\":[]}],\"directParentClasses\":[],\"sourceType\":2}},{\"v\":\"@proteinjs/server-api/SessionDataStorage\"},{\"v\":\"@proteinjs/server/ExtendedIncomingMessage\",\"value\":{\"packageName\":\"@proteinjs/server\",\"name\":\"ExtendedIncomingMessage\",\"filePath\":\"/home/runner/work/server/server/packages/server/src/SocketIOServerRepo.ts\",\"qualifiedName\":\"@proteinjs/server/ExtendedIncomingMessage\",\"properties\":[{\"name\":\"sessionID\",\"type\":{\"packageName\":\"\",\"name\":\"string\",\"filePath\":null,\"qualifiedName\":\"/string\",\"typeParameters\":null,\"directParents\":null},\"isOptional\":true,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\"},{\"name\":\"user\",\"type\":{\"packageName\":\"\",\"name\":\"string\",\"filePath\":null,\"qualifiedName\":\"/string\",\"typeParameters\":null,\"directParents\":null},\"isOptional\":true,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\"}],\"methods\":[],\"typeParameters\":[],\"directParents\":[{\"packageName\":\"http\",\"name\":\"IncomingMessage\",\"filePath\":null,\"qualifiedName\":\"http/IncomingMessage\",\"properties\":[],\"methods\":[],\"typeParameters\":[],\"directParents\":[]}],\"sourceType\":3}},{\"v\":\"http/IncomingMessage\"},{\"v\":\"@proteinjs/server/ExtendedSocket\",\"value\":{\"packageName\":\"@proteinjs/server\",\"name\":\"ExtendedSocket\",\"filePath\":\"/home/runner/work/server/server/packages/server/src/SocketIOServerRepo.ts\",\"qualifiedName\":\"@proteinjs/server/ExtendedSocket\",\"properties\":[{\"name\":\"request\",\"type\":{\"packageName\":\"@proteinjs/server\",\"name\":\"ExtendedIncomingMessage\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server/ExtendedIncomingMessage\",\"typeParameters\":null,\"directParents\":null},\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\"}],\"methods\":[],\"typeParameters\":[],\"directParents\":[{\"packageName\":\"socket.io\",\"name\":\"Socket\",\"filePath\":null,\"qualifiedName\":\"socket.io/Socket\",\"properties\":[],\"methods\":[],\"typeParameters\":[],\"directParents\":[]}],\"sourceType\":3}},{\"v\":\"socket.io/Socket\"},{\"v\":\"@proteinjs/server/environmentCache\",\"value\":{\"packageName\":\"@proteinjs/server\",\"name\":\"environmentCache\",\"filePath\":\"/home/runner/work/server/server/packages/server/src/envCache.ts\",\"qualifiedName\":\"@proteinjs/server/environmentCache\",\"type\":{\"packageName\":\"\",\"name\":\"GlobalDataCache<Env>\",\"filePath\":null,\"qualifiedName\":\"/GlobalDataCache<Env>\",\"typeParameters\":[],\"directParents\":[{\"packageName\":\"@proteinjs/server-api\",\"name\":\"GlobalDataCache\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server-api/GlobalDataCache\",\"typeParameters\":[\"@proteinjs/server-api/Env\"],\"directParents\":null}]},\"isExported\":true,\"isConst\":true,\"sourceType\":0}},{\"v\":\"@proteinjs/server-api/GlobalDataCache\"},{\"v\":\"@proteinjs/server/healthCheck\",\"value\":{\"packageName\":\"@proteinjs/server\",\"name\":\"healthCheck\",\"filePath\":\"/home/runner/work/server/server/packages/server/src/routes/healthCheck.ts\",\"qualifiedName\":\"@proteinjs/server/healthCheck\",\"type\":{\"packageName\":\"@proteinjs/server-api\",\"name\":\"Route\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server-api/Route\",\"typeParameters\":[],\"directParents\":[{\"packageName\":\"@proteinjs/server-api\",\"name\":\"Route\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server-api/Route\",\"typeParameters\":[],\"directParents\":null}]},\"isExported\":true,\"isConst\":true,\"sourceType\":0}},{\"v\":\"@proteinjs/server-api/Route\"}],\"edges\":[{\"v\":\"@proteinjs/server/NodeGlobalDataStorage\",\"w\":\"@proteinjs/server-api/GlobalDataStorage\",\"value\":\"implements interface\"},{\"v\":\"@proteinjs/server/NodeSessionDataStorage\",\"w\":\"@proteinjs/server-api/SessionDataStorage\",\"value\":\"implements interface\"},{\"v\":\"@proteinjs/server/ExtendedIncomingMessage\",\"w\":\"http/IncomingMessage\",\"value\":\"extends interface\"},{\"v\":\"@proteinjs/server/ExtendedSocket\",\"w\":\"socket.io/Socket\",\"value\":\"extends interface\"},{\"v\":\"@proteinjs/server/environmentCache\",\"w\":\"@proteinjs/server-api/GlobalDataCache\",\"value\":\"has type\"},{\"v\":\"@proteinjs/server/healthCheck\",\"w\":\"@proteinjs/server-api/Route\",\"value\":\"has type\"}]}";
+var sourceGraph = "{\"options\":{\"directed\":true,\"multigraph\":false,\"compound\":false},\"nodes\":[{\"v\":\"/() => void\"},{\"v\":\"@proteinjs/server/NodeGlobalDataStorage\",\"value\":{\"packageName\":\"@proteinjs/server\",\"name\":\"NodeGlobalDataStorage\",\"filePath\":\"/home/runner/work/server/server/packages/server/src/NodeGlobalDataStorage.ts\",\"qualifiedName\":\"@proteinjs/server/NodeGlobalDataStorage\",\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\",\"properties\":[{\"name\":\"HOOK_INITIALIZED\",\"type\":null,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":true,\"visibility\":\"private\"},{\"name\":\"GLOBAL_DATA\",\"type\":{\"packageName\":\"@proteinjs/server\",\"name\":\"{ [id: string]: GlobalData }\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server/{ [id: string]: GlobalData }\",\"typeParameters\":null,\"directParents\":null},\"isOptional\":false,\"isAbstract\":false,\"isStatic\":true,\"visibility\":\"private\"},{\"name\":\"environment\",\"type\":null,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\"}],\"methods\":[{\"name\":\"setData\",\"returnType\":null,\"isAsync\":false,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\",\"parameters\":[{\"name\":\"data\",\"type\":{\"packageName\":\"@proteinjs/server-api\",\"name\":\"GlobalData\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server-api/GlobalData\",\"typeParameters\":null,\"directParents\":null}}]},{\"name\":\"getData\",\"returnType\":{\"packageName\":\"@proteinjs/server-api\",\"name\":\"GlobalData\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server-api/GlobalData\",\"typeParameters\":null,\"directParents\":null},\"isAsync\":false,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\",\"parameters\":[]},{\"name\":\"initHook\",\"returnType\":null,\"isAsync\":false,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"private\",\"parameters\":[]}],\"typeParameters\":[],\"directParentInterfaces\":[{\"packageName\":\"@proteinjs/server-api\",\"name\":\"GlobalDataStorage\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server-api/GlobalDataStorage\",\"properties\":[],\"methods\":[],\"typeParameters\":[],\"directParents\":[]}],\"directParentClasses\":[],\"sourceType\":2}},{\"v\":\"@proteinjs/server-api/GlobalDataStorage\"},{\"v\":\"@proteinjs/server/NodeSessionDataStorage\",\"value\":{\"packageName\":\"@proteinjs/server\",\"name\":\"NodeSessionDataStorage\",\"filePath\":\"/home/runner/work/server/server/packages/server/src/NodeSessionDataStorage.ts\",\"qualifiedName\":\"@proteinjs/server/NodeSessionDataStorage\",\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\",\"properties\":[{\"name\":\"HOOK_INITIALIZED\",\"type\":null,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":true,\"visibility\":\"private\"},{\"name\":\"SESSION_DATA\",\"type\":{\"packageName\":\"@proteinjs/server\",\"name\":\"{ [id: string]: SessionData }\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server/{ [id: string]: SessionData }\",\"typeParameters\":null,\"directParents\":null},\"isOptional\":false,\"isAbstract\":false,\"isStatic\":true,\"visibility\":\"private\"},{\"name\":\"environment\",\"type\":null,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\"}],\"methods\":[{\"name\":\"setData\",\"returnType\":null,\"isAsync\":false,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\",\"parameters\":[{\"name\":\"data\",\"type\":{\"packageName\":\"@proteinjs/server-api\",\"name\":\"SessionData\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server-api/SessionData\",\"typeParameters\":null,\"directParents\":null}}]},{\"name\":\"getData\",\"returnType\":{\"packageName\":\"@proteinjs/server-api\",\"name\":\"SessionData\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server-api/SessionData\",\"typeParameters\":null,\"directParents\":null},\"isAsync\":false,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\",\"parameters\":[]},{\"name\":\"clearData\",\"returnType\":{\"packageName\":\"\",\"name\":\"void\",\"filePath\":null,\"qualifiedName\":\"/void\",\"typeParameters\":null,\"directParents\":null},\"isAsync\":false,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\",\"parameters\":[]},{\"name\":\"initHook\",\"returnType\":null,\"isAsync\":false,\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"private\",\"parameters\":[]}],\"typeParameters\":[],\"directParentInterfaces\":[{\"packageName\":\"@proteinjs/server-api\",\"name\":\"SessionDataStorage\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server-api/SessionDataStorage\",\"properties\":[],\"methods\":[],\"typeParameters\":[],\"directParents\":[]}],\"directParentClasses\":[],\"sourceType\":2}},{\"v\":\"@proteinjs/server-api/SessionDataStorage\"},{\"v\":\"@proteinjs/server/ExtendedIncomingMessage\",\"value\":{\"packageName\":\"@proteinjs/server\",\"name\":\"ExtendedIncomingMessage\",\"filePath\":\"/home/runner/work/server/server/packages/server/src/SocketIOServerRepo.ts\",\"qualifiedName\":\"@proteinjs/server/ExtendedIncomingMessage\",\"properties\":[{\"name\":\"sessionID\",\"type\":{\"packageName\":\"\",\"name\":\"string\",\"filePath\":null,\"qualifiedName\":\"/string\",\"typeParameters\":null,\"directParents\":null},\"isOptional\":true,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\"},{\"name\":\"user\",\"type\":{\"packageName\":\"\",\"name\":\"string\",\"filePath\":null,\"qualifiedName\":\"/string\",\"typeParameters\":null,\"directParents\":null},\"isOptional\":true,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\"}],\"methods\":[],\"typeParameters\":[],\"directParents\":[{\"packageName\":\"http\",\"name\":\"IncomingMessage\",\"filePath\":null,\"qualifiedName\":\"http/IncomingMessage\",\"properties\":[],\"methods\":[],\"typeParameters\":[],\"directParents\":[]}],\"sourceType\":3}},{\"v\":\"http/IncomingMessage\"},{\"v\":\"@proteinjs/server/ExtendedSocket\",\"value\":{\"packageName\":\"@proteinjs/server\",\"name\":\"ExtendedSocket\",\"filePath\":\"/home/runner/work/server/server/packages/server/src/SocketIOServerRepo.ts\",\"qualifiedName\":\"@proteinjs/server/ExtendedSocket\",\"properties\":[{\"name\":\"request\",\"type\":{\"packageName\":\"@proteinjs/server\",\"name\":\"ExtendedIncomingMessage\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server/ExtendedIncomingMessage\",\"typeParameters\":null,\"directParents\":null},\"isOptional\":false,\"isAbstract\":false,\"isStatic\":false,\"visibility\":\"public\"}],\"methods\":[],\"typeParameters\":[],\"directParents\":[{\"packageName\":\"socket.io\",\"name\":\"Socket\",\"filePath\":null,\"qualifiedName\":\"socket.io/Socket\",\"properties\":[],\"methods\":[],\"typeParameters\":[],\"directParents\":[]}],\"sourceType\":3}},{\"v\":\"socket.io/Socket\"},{\"v\":\"@proteinjs/server/environmentCache\",\"value\":{\"packageName\":\"@proteinjs/server\",\"name\":\"environmentCache\",\"filePath\":\"/home/runner/work/server/server/packages/server/src/envCache.ts\",\"qualifiedName\":\"@proteinjs/server/environmentCache\",\"type\":{\"packageName\":\"\",\"name\":\"GlobalDataCache<Env>\",\"filePath\":null,\"qualifiedName\":\"/GlobalDataCache<Env>\",\"typeParameters\":[],\"directParents\":[{\"packageName\":\"@proteinjs/server-api\",\"name\":\"GlobalDataCache\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server-api/GlobalDataCache\",\"typeParameters\":[\"@proteinjs/server-api/Env\"],\"directParents\":null}]},\"isExported\":true,\"isConst\":true,\"sourceType\":0}},{\"v\":\"@proteinjs/server-api/GlobalDataCache\"},{\"v\":\"@proteinjs/server/healthCheck\",\"value\":{\"packageName\":\"@proteinjs/server\",\"name\":\"healthCheck\",\"filePath\":\"/home/runner/work/server/server/packages/server/src/routes/healthCheck.ts\",\"qualifiedName\":\"@proteinjs/server/healthCheck\",\"type\":{\"packageName\":\"@proteinjs/server-api\",\"name\":\"Route\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server-api/Route\",\"typeParameters\":[],\"directParents\":[{\"packageName\":\"@proteinjs/server-api\",\"name\":\"Route\",\"filePath\":null,\"qualifiedName\":\"@proteinjs/server-api/Route\",\"typeParameters\":[],\"directParents\":null}]},\"isExported\":true,\"isConst\":true,\"sourceType\":0}},{\"v\":\"@proteinjs/server-api/Route\"}],\"edges\":[{\"v\":\"@proteinjs/server/NodeGlobalDataStorage\",\"w\":\"@proteinjs/server-api/GlobalDataStorage\",\"value\":\"implements interface\"},{\"v\":\"@proteinjs/server/NodeSessionDataStorage\",\"w\":\"@proteinjs/server-api/SessionDataStorage\",\"value\":\"implements interface\"},{\"v\":\"@proteinjs/server/ExtendedIncomingMessage\",\"w\":\"http/IncomingMessage\",\"value\":\"extends interface\"},{\"v\":\"@proteinjs/server/ExtendedSocket\",\"w\":\"socket.io/Socket\",\"value\":\"extends interface\"},{\"v\":\"@proteinjs/server/environmentCache\",\"w\":\"@proteinjs/server-api/GlobalDataCache\",\"value\":\"has type\"},{\"v\":\"@proteinjs/server/healthCheck\",\"w\":\"@proteinjs/server-api/Route\",\"value\":\"has type\"}]}";
 /** Generate Source Links */
 var NodeGlobalDataStorage_1 = require("../src/NodeGlobalDataStorage");
 var NodeSessionDataStorage_1 = require("../src/NodeSessionDataStorage");

package/dist/generated/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../generated/index.ts"],"names":[],"mappings":";AAAA,oCAAoC;;;;;;;;;;;;;;;;AAEpC,4BAA0B;AAC1B,6BAA2B;AAC3B,iCAA+B;AAC/B,iCAA+B;AAC/B,gCAA8B;AAC9B,uBAAqB;AACrB,yBAAuB;AACvB,kBAAgB;AAChB,mBAAiB;AACjB,2BAAyB;AACzB,oBAAkB;AAClB,0BAAwB;AACxB,mBAAiB;AACjB,iBAAe;AACf,wBAAsB;AACtB,qBAAmB;AACnB,sBAAoB;AAGpB,4BAA4B;AAE5B,IAAM,WAAW,GAAG,y8RAAy8R,CAAC;AAG99R,4BAA4B;AAE5B,sEAAqE;AACrE,wEAAuE;AACvE,4CAAmD;AACnD,yDAAwD;AAExD,IAAM,WAAW,GAAG;IACnB,yCAAyC,EAAE,6CAAqB;IAChE,0CAA0C,EAAE,+CAAsB;IAClE,oCAAoC,EAAE,2BAAgB;IACtD,+BAA+B,EAAE,yBAAW;CAC5C,CAAC;AAGF,kCAAkC;AAElC,oDAAyD;AACzD,6BAAgB,CAAC,KAAK,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;AAGjD,2CAAyB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../generated/index.ts"],"names":[],"mappings":";AAAA,oCAAoC;;;;;;;;;;;;;;;;AAEpC,4BAA0B;AAC1B,6BAA2B;AAC3B,iCAA+B;AAC/B,iCAA+B;AAC/B,gCAA8B;AAC9B,uBAAqB;AACrB,yBAAuB;AACvB,kBAAgB;AAChB,mBAAiB;AACjB,2BAAyB;AACzB,oBAAkB;AAClB,0BAAwB;AACxB,mBAAiB;AACjB,iBAAe;AACf,wBAAsB;AACtB,qBAAmB;AACnB,sBAAoB;AAGpB,4BAA4B;AAE5B,IAAM,WAAW,GAAG,i+RAAi+R,CAAC;AAGt/R,4BAA4B;AAE5B,sEAAqE;AACrE,wEAAuE;AACvE,4CAAmD;AACnD,yDAAwD;AAExD,IAAM,WAAW,GAAG;IACnB,yCAAyC,EAAE,6CAAqB;IAChE,0CAA0C,EAAE,+CAAsB;IAClE,oCAAoC,EAAE,2BAAgB;IACtD,+BAA+B,EAAE,yBAAW;CAC5C,CAAC;AAGF,kCAAkC;AAElC,oDAAyD;AACzD,6BAAgB,CAAC,KAAK,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;AAGjD,2CAAyB"}

package/dist/src/GracefulShutdown.d.ts

@@ -1,6 +1,21 @@
 /// <reference types="node" />
 import { Server as HttpServer } from 'http';
 import { ServerConfig } from '@proteinjs/server-api';
+/** Releases a hold taken with {@link GracefulShutdown.hold}. Idempotent. */
+export type HoldRelease = () => void;
+/** A hold outstanding on the process: its label plus whatever the holder attached for the logs. */
+export type Hold = {
+    label: string;
+    context?: Record<string, unknown>;
+};
+/**
+ * Follows the process's holds as they come and go — the dev supervisor's lease projection
+ * (@n3xah/util-server's ServePackageHold) is the one consumer; it never decides anything here.
+ */
+export type HoldObserver = {
+    acquired?: (label: string) => void;
+    released?: (label: string) => void;
+};
 /**
  * The one owner of the server's shutdown state. Installed by `startServer` before the listener
  * opens; the `/health-check` route reads `isShuttingDown()` — no other flag system exists.
@@ -15,25 +30,48 @@ import { ServerConfig } from '@proteinjs/server-api';
  *     2. The listener closes (socket.io clients are disconnected, and `io.close()` closes the
  *        http server it is attached to), idle keep-alive connections are closed, and in-flight
  *        requests run to completion.
- *     3. The drain is BOUNDED by `shutdown.drainTimeoutMs`: past it, remaining connections are
- *        force-closed. Either way the exit code is 0 — a drained shutdown is not a crash.
+ *     3. The process WAITS for its HOLDS (`hold(label)` below) to release, bounded by
+ *        `shutdown.turnDrainMs`: work that must not die with the process and that no HTTP
+ *        connection represents — the canonical holder is a chat turn whose client has gone
+ *        (the response detached, the model still writing, nothing persisted yet). Past the
+ *        bound every hold still outstanding is logged by label and abandoned.
+ *     4. The connection drain is BOUNDED by `shutdown.drainTimeoutMs`: past it, remaining
+ *        connections are force-closed. Either way the exit code is 0 — a drained shutdown is
+ *        not a crash.
  *   SIGINT → exit 0 immediately (dev ctrl-C: fast and quiet; nothing needs flushing).
  *   exit 86 → NOT this class's concern: `process.exit(86)` is the ServePackageSupervisor
  *     restart-request contract (a liveness monitor giving up on a dependency); it is not
  *     signal-driven and is untouched by these handlers.
  *
+ * Holds are a process-wide static seam so a holder never needs the server instance (a turn
+ * registry, a suite with no listener): `hold(label, context)` returns the release; the same
+ * label held twice is one hold (the release is shared — the turn registry's idempotence);
+ * `holds()` lists what is outstanding, in acquisition order; `observeHolds` lets the dev
+ * supervisor's lease follow the same set, so a holder declares itself ONCE and both the
+ * pre-signal restart deferral (dev) and the post-SIGTERM drain (prod) honor it.
+ *
+ * Why holds and not connections: the 2026-09-05 prod kill — a phone locked mid-turn, the route
+ * detached the dead response and the turn ran on to persist, GKE's autoscaler evicted the pod,
+ * and this drain saw NO connection in flight, so `process.exit(0)` ran 5 s after SIGTERM with the
+ * model call 32 s in. Nothing persisted, nothing logged (plans/FREE_AGENT.md §M.14).
+ *
  * A SIGTERM before the listener is open (mid-boot kill) exits 0 immediately — nothing is
  * registered anywhere and nothing is in flight.
  *
  * Supervisor compatibility (dev): ServePackageSupervisor SIGTERMs the child's process group and
  * escalates to SIGKILL after its grace period (default 10s); its exit handler ignores exit codes
  * for kills it initiated, so the drain-then-exit-0 shape cannot be misread. DEVELOPMENT defaults
- * `drainDelayMs` to 0 so supervised restarts stay fast.
+ * `drainDelayMs` to 0 so supervised restarts stay fast; a turn in flight under the supervisor is
+ * covered BEFORE the signal by its lease (the hold projection), not by this drain.
  */
 export declare class GracefulShutdown {
     private server;
     private config;
     private static instance?;
+    private static holds;
+    private static holdObservers;
+    private static holdWaiters;
+    private static staticLogger;
     private shuttingDown;
     private logger;
     private constructor();
@@ -41,10 +79,25 @@ export declare class GracefulShutdown {
     static install(server: HttpServer, config: ServerConfig): void;
     /** The readiness seam: `/health-check` reports 503 whenever this is true. */
     static isShuttingDown(): boolean;
+    /**
+     * Keep the process alive through a SIGTERM drain until the returned release is called (bounded
+     * by `shutdown.turnDrainMs`). `label` names the work in the drain's logs (`chat-turn:<id>`);
+     * `context` rides beside it (chat id, user id). Holding a label already held returns the
+     * existing release — one hold per label.
+     */
+    static hold(label: string, context?: Record<string, unknown>): HoldRelease;
+    /** Every hold outstanding right now, in acquisition order. */
+    static outstandingHolds(): Hold[];
+    /** Follow holds as they are acquired and released. Returns the unsubscribe. */
+    static observeHolds(observer: HoldObserver): () => void;
     private drainAndExit;
+    private drainHolds;
     private exitNow;
     private drainDelayMs;
     private drainTimeoutMs;
+    private turnDrainMs;
+    private static whenNoHolds;
+    private static notify;
     /** Await a promise with a deadline; true if it settled in time. */
     private settled;
     private sleep;

package/dist/src/GracefulShutdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GracefulShutdown.d.ts","sourceRoot":"","sources":["../../src/GracefulShutdown.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,MAAM,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAIrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,gBAAgB;IAMzB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,MAAM;IANhB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAmB;IAC3C,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,MAAM,CAA4C;IAE1D,OAAO;IAKP,iFAAiF;IACjF,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI;IAU9D,6EAA6E;IAC7E,MAAM,CAAC,cAAc,IAAI,OAAO;YAIlB,YAAY;IAwC1B,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,cAAc;IAItB,mEAAmE;YACrD,OAAO;IAUrB,OAAO,CAAC,KAAK;CAGd"}
+{"version":3,"file":"GracefulShutdown.d.ts","sourceRoot":"","sources":["../../src/GracefulShutdown.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,MAAM,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAIrD,4EAA4E;AAC5E,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC,mGAAmG;AACnG,MAAM,MAAM,IAAI,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC;AAExE;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IAAE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,CAAC;AAEtG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,qBAAa,gBAAgB;IAUzB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,MAAM;IAVhB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAmB;IAC3C,OAAO,CAAC,MAAM,CAAC,KAAK,CAA2D;IAC/E,OAAO,CAAC,MAAM,CAAC,aAAa,CAA2B;IACvD,OAAO,CAAC,MAAM,CAAC,WAAW,CAAyB;IACnD,OAAO,CAAC,MAAM,CAAC,YAAY,CAA4C;IACvE,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,MAAM,CAA4C;IAE1D,OAAO;IAKP,iFAAiF;IACjF,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI;IAU9D,6EAA6E;IAC7E,MAAM,CAAC,cAAc,IAAI,OAAO;IAIhC;;;;;OAKG;IACH,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW;IAuB1E,8DAA8D;IAC9D,MAAM,CAAC,gBAAgB,IAAI,IAAI,EAAE;IAIjC,+EAA+E;IAC/E,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,IAAI;YAOzC,YAAY;YA6CZ,UAAU;IAqBxB,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,MAAM,CAAC,WAAW;IAO1B,OAAO,CAAC,MAAM,CAAC,MAAM;IAcrB,mEAAmE;YACrD,OAAO;IAUrB,OAAO,CAAC,KAAK;CAGd"}

package/dist/src/GracefulShutdown.js

@@ -1,4 +1,15 @@
 "use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -53,20 +64,39 @@ var SocketIOServerRepo_1 = require("./SocketIOServerRepo");
  *     2. The listener closes (socket.io clients are disconnected, and `io.close()` closes the
  *        http server it is attached to), idle keep-alive connections are closed, and in-flight
  *        requests run to completion.
- *     3. The drain is BOUNDED by `shutdown.drainTimeoutMs`: past it, remaining connections are
- *        force-closed. Either way the exit code is 0 — a drained shutdown is not a crash.
+ *     3. The process WAITS for its HOLDS (`hold(label)` below) to release, bounded by
+ *        `shutdown.turnDrainMs`: work that must not die with the process and that no HTTP
+ *        connection represents — the canonical holder is a chat turn whose client has gone
+ *        (the response detached, the model still writing, nothing persisted yet). Past the
+ *        bound every hold still outstanding is logged by label and abandoned.
+ *     4. The connection drain is BOUNDED by `shutdown.drainTimeoutMs`: past it, remaining
+ *        connections are force-closed. Either way the exit code is 0 — a drained shutdown is
+ *        not a crash.
  *   SIGINT → exit 0 immediately (dev ctrl-C: fast and quiet; nothing needs flushing).
  *   exit 86 → NOT this class's concern: `process.exit(86)` is the ServePackageSupervisor
  *     restart-request contract (a liveness monitor giving up on a dependency); it is not
  *     signal-driven and is untouched by these handlers.
  *
+ * Holds are a process-wide static seam so a holder never needs the server instance (a turn
+ * registry, a suite with no listener): `hold(label, context)` returns the release; the same
+ * label held twice is one hold (the release is shared — the turn registry's idempotence);
+ * `holds()` lists what is outstanding, in acquisition order; `observeHolds` lets the dev
+ * supervisor's lease follow the same set, so a holder declares itself ONCE and both the
+ * pre-signal restart deferral (dev) and the post-SIGTERM drain (prod) honor it.
+ *
+ * Why holds and not connections: the 2026-09-05 prod kill — a phone locked mid-turn, the route
+ * detached the dead response and the turn ran on to persist, GKE's autoscaler evicted the pod,
+ * and this drain saw NO connection in flight, so `process.exit(0)` ran 5 s after SIGTERM with the
+ * model call 32 s in. Nothing persisted, nothing logged (plans/FREE_AGENT.md §M.14).
+ *
  * A SIGTERM before the listener is open (mid-boot kill) exits 0 immediately — nothing is
  * registered anywhere and nothing is in flight.
  *
  * Supervisor compatibility (dev): ServePackageSupervisor SIGTERMs the child's process group and
  * escalates to SIGKILL after its grace period (default 10s); its exit handler ignores exit codes
  * for kills it initiated, so the drain-then-exit-0 shape cannot be misread. DEVELOPMENT defaults
- * `drainDelayMs` to 0 so supervised restarts stay fast.
+ * `drainDelayMs` to 0 so supervised restarts stay fast; a turn in flight under the supervisor is
+ * covered BEFORE the signal by its lease (the hold projection), not by this drain.
  */
 var GracefulShutdown = /** @class */ (function () {
     function GracefulShutdown(server, config) {
@@ -90,9 +120,50 @@ var GracefulShutdown = /** @class */ (function () {
         var _a, _b;
         return (_b = (_a = GracefulShutdown.instance) === null || _a === void 0 ? void 0 : _a.shuttingDown) !== null && _b !== void 0 ? _b : false;
     };
+    /**
+     * Keep the process alive through a SIGTERM drain until the returned release is called (bounded
+     * by `shutdown.turnDrainMs`). `label` names the work in the drain's logs (`chat-turn:<id>`);
+     * `context` rides beside it (chat id, user id). Holding a label already held returns the
+     * existing release — one hold per label.
+     */
+    GracefulShutdown.hold = function (label, context) {
+        var existing = GracefulShutdown.holds.get(label);
+        if (existing) {
+            return existing.release;
+        }
+        var release = function () {
+            var _a;
+            if (((_a = GracefulShutdown.holds.get(label)) === null || _a === void 0 ? void 0 : _a.release) !== release) {
+                return; // already released (or the label re-held since — that hold has its own release)
+            }
+            GracefulShutdown.holds.delete(label);
+            GracefulShutdown.notify('released', label);
+            if (GracefulShutdown.holds.size === 0) {
+                var waiters = GracefulShutdown.holdWaiters.splice(0, GracefulShutdown.holdWaiters.length);
+                for (var _i = 0, waiters_1 = waiters; _i < waiters_1.length; _i++) {
+                    var resolve = waiters_1[_i];
+                    resolve();
+                }
+            }
+        };
+        GracefulShutdown.holds.set(label, { hold: context ? { label: label, context: context } : { label: label }, release: release });
+        GracefulShutdown.notify('acquired', label);
+        return release;
+    };
+    /** Every hold outstanding right now, in acquisition order. */
+    GracefulShutdown.outstandingHolds = function () {
+        return Array.from(GracefulShutdown.holds.values()).map(function (entry) { return (__assign({}, entry.hold)); });
+    };
+    /** Follow holds as they are acquired and released. Returns the unsubscribe. */
+    GracefulShutdown.observeHolds = function (observer) {
+        GracefulShutdown.holdObservers.add(observer);
+        return function () {
+            GracefulShutdown.holdObservers.delete(observer);
+        };
+    };
     GracefulShutdown.prototype.drainAndExit = function () {
         return __awaiter(this, void 0, void 0, function () {
-            var drainDelayMs, drainTimeoutMs, drained, io;
+            var drainDelayMs, drainTimeoutMs, turnDrainMs, drained, io;
             var _this = this;
             return __generator(this, function (_a) {
                 switch (_a.label) {
@@ -107,8 +178,10 @@ var GracefulShutdown = /** @class */ (function () {
                         }
                         drainDelayMs = this.drainDelayMs();
                         drainTimeoutMs = this.drainTimeoutMs();
+                        turnDrainMs = this.turnDrainMs();
                         this.logger.info({
-                            message: "Received SIGTERM \u2014 /health-check now reports 503; accepting connections for another ".concat(drainDelayMs, "ms, then draining in-flight requests (bound: ").concat(drainTimeoutMs, "ms)"),
+                            message: "Received SIGTERM \u2014 /health-check now reports 503; accepting connections for another ".concat(drainDelayMs, "ms, then draining in-flight requests (bound: ").concat(drainTimeoutMs, "ms) and ").concat(GracefulShutdown.holds.size, " hold(s) (bound: ").concat(turnDrainMs, "ms)"),
+                            obj: { holds: GracefulShutdown.outstandingHolds() },
                         });
                         // 1. Readiness-propagation window: the LB observes the 503 while we still serve normally.
                         return [4 /*yield*/, this.sleep(drainDelayMs)];
@@ -124,9 +197,16 @@ var GracefulShutdown = /** @class */ (function () {
                             this.server.close();
                         }
                         this.server.closeIdleConnections();
-                        return [4 /*yield*/, this.settled(drained, drainTimeoutMs)];
+                        // 3. Holds: work no connection represents (a detached chat turn). In-flight requests keep
+                        // running meanwhile — the listener is closed, existing connections are not. Bounded.
+                        return [4 /*yield*/, this.drainHolds(turnDrainMs)];
                     case 2:
-                        // 3. Bounded: past the drain timeout, force-close what remains. Exit 0 either way.
+                        // 3. Holds: work no connection represents (a detached chat turn). In-flight requests keep
+                        // running meanwhile — the listener is closed, existing connections are not. Bounded.
+                        _a.sent();
+                        return [4 /*yield*/, this.settled(drained, drainTimeoutMs)];
+                    case 3:
+                        // 4. Bounded: past the drain timeout, force-close what remains. Exit 0 either way.
                         if (!(_a.sent())) {
                             this.logger.warn({
                                 message: "Drain exceeded its ".concat(drainTimeoutMs, "ms bound \u2014 force-closing the remaining connections"),
@@ -140,6 +220,37 @@ var GracefulShutdown = /** @class */ (function () {
             });
         });
     };
+    GracefulShutdown.prototype.drainHolds = function (turnDrainMs) {
+        return __awaiter(this, void 0, void 0, function () {
+            var abandoned;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (GracefulShutdown.holds.size === 0) {
+                            return [2 /*return*/];
+                        }
+                        this.logger.info({
+                            message: "Listener closed \u2014 waiting for ".concat(GracefulShutdown.holds.size, " hold(s) to release (bound: ").concat(turnDrainMs, "ms)"),
+                            obj: { holds: GracefulShutdown.outstandingHolds() },
+                        });
+                        return [4 /*yield*/, this.settled(GracefulShutdown.whenNoHolds(), turnDrainMs)];
+                    case 1:
+                        if (_a.sent()) {
+                            this.logger.info({ message: "Every hold released \u2014 continuing the drain" });
+                            return [2 /*return*/];
+                        }
+                        abandoned = GracefulShutdown.outstandingHolds();
+                        this.logger.warn({
+                            message: "Hold drain exceeded its ".concat(turnDrainMs, "ms bound \u2014 abandoning ").concat(abandoned.length, " hold(s): ").concat(abandoned
+                                .map(function (hold) { return hold.label; })
+                                .join(', ')),
+                            obj: { holds: abandoned },
+                        });
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
     GracefulShutdown.prototype.exitNow = function () {
         this.shuttingDown = true;
         this.logger.info({ message: "Received SIGINT \u2014 exiting immediately" });
@@ -156,6 +267,32 @@ var GracefulShutdown = /** @class */ (function () {
         var _a, _b;
         return (_b = (_a = this.config.shutdown) === null || _a === void 0 ? void 0 : _a.drainTimeoutMs) !== null && _b !== void 0 ? _b : 30000;
     };
+    GracefulShutdown.prototype.turnDrainMs = function () {
+        var _a, _b;
+        return (_b = (_a = this.config.shutdown) === null || _a === void 0 ? void 0 : _a.turnDrainMs) !== null && _b !== void 0 ? _b : 240000;
+    };
+    GracefulShutdown.whenNoHolds = function () {
+        if (GracefulShutdown.holds.size === 0) {
+            return Promise.resolve();
+        }
+        return new Promise(function (resolve) { return GracefulShutdown.holdWaiters.push(resolve); });
+    };
+    GracefulShutdown.notify = function (event, label) {
+        var _a;
+        for (var _i = 0, _b = Array.from(GracefulShutdown.holdObservers); _i < _b.length; _i++) {
+            var observer = _b[_i];
+            try {
+                (_a = observer[event]) === null || _a === void 0 ? void 0 : _a.call(observer, label);
+            }
+            catch (error) {
+                // An observer follows the holds; its failure never touches the hold itself.
+                GracefulShutdown.staticLogger.warn({
+                    message: "A hold observer threw on ".concat(event),
+                    obj: { label: label, error: error === null || error === void 0 ? void 0 : error.message },
+                });
+            }
+        }
+    };
     /** Await a promise with a deadline; true if it settled in time. */
     GracefulShutdown.prototype.settled = function (promise, ms) {
         return __awaiter(this, void 0, void 0, function () {
@@ -178,6 +315,10 @@ var GracefulShutdown = /** @class */ (function () {
     GracefulShutdown.prototype.sleep = function (ms) {
         return new Promise(function (resolve) { return setTimeout(resolve, ms); });
     };
+    GracefulShutdown.holds = new Map();
+    GracefulShutdown.holdObservers = new Set();
+    GracefulShutdown.holdWaiters = [];
+    GracefulShutdown.staticLogger = new logger_1.Logger({ name: 'GracefulShutdown' });
     return GracefulShutdown;
 }());
 exports.GracefulShutdown = GracefulShutdown;

package/dist/src/GracefulShutdown.js.map

@@ -1 +1 @@
-{"version":3,"file":"GracefulShutdown.js","sourceRoot":"","sources":["../../src/GracefulShutdown.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"GracefulShutdown.js","sourceRoot":"","sources":["../../src/GracefulShutdown.ts"],"names":[],"mappings":"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"}

package/dist/src/routes/reactApp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reactApp.d.ts","sourceRoot":"","sources":["../../../src/routes/reactApp.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAA4B,MAAM,uBAAuB,CAAC;AAU/E,eAAO,MAAM,cAAc,iBAAkB,YAAY;;;yBAI1B,GAAG,YAAY,GAAG,KAAG,QAAQ,IAAI,CAAC;CA+BhE,CAAC"}
+{"version":3,"file":"reactApp.d.ts","sourceRoot":"","sources":["../../../src/routes/reactApp.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAA4B,MAAM,uBAAuB,CAAC;AAU/E,eAAO,MAAM,cAAc,iBAAkB,YAAY;;;yBAI1B,GAAG,YAAY,GAAG,KAAG,QAAQ,IAAI,CAAC;CAsChE,CAAC"}

package/dist/src/routes/reactApp.js

@@ -67,6 +67,13 @@ var createReactApp = function (serverConfig) {
                             throw new Error("ServerConfig.bundlePath or ServerConfig.bundlesDir must be provided to serve a react app");
                         }
                         helmet = react_helmet_1.default.renderStatic();
+                        // The page must ALWAYS revalidate (found live 2026-09-01, the mobile-app stale-page
+                        // investigation): without an explicit policy, HTTP heuristic caching applies (RFC 9111
+                        // §4.2.2) — WKWebView in particular can serve the cached page without revalidating,
+                        // across app force-quits, pinning stale bundle POINTERS long after a deploy. The hashed
+                        // bundles under /static keep their long cache (a fresh page always points at fresh
+                        // hashes); `no-cache` + the ETag express already stamps = a cheap 304 on every load.
+                        response.set('Cache-Control', 'no-cache');
                         _b = (_a = response).send;
                         _e = (_d = "<!DOCTYPE html>\n                <html ".concat(helmet.htmlAttributes, ">\n                    <head>\n                        <meta charset='utf-8' />\n                        <meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1, viewport-fit=cover'>\n                        <meta name='theme-color' content='").concat(THEME_COLOR_LIGHT, "' media='(prefers-color-scheme: light)'>\n                        <meta name='theme-color' content='").concat(THEME_COLOR_DARK, "' media='(prefers-color-scheme: dark)'>\n                        <link href='").concat(((_j = serverConfig.staticContent) === null || _j === void 0 ? void 0 : _j.faviconPath) ? path_1.default.join('/static/', serverConfig.staticContent.faviconPath) : '', "' rel='icon' type='image/png' />\n                        ").concat(helmet.title.toString(), "\n                        ").concat(helmet.meta.toString(), "\n                        ").concat(helmet.link.toString(), "\n                    </head>\n                    <body ").concat(helmet.bodyAttributes.toString(), ">\n                        <div id='app'></div>\n                        <script>proteinjs = {};</script>\n                        ")).concat;
                         return [4 /*yield*/, serverRenderedScriptTags()];

package/dist/src/routes/reactApp.js.map

@@ -1 +1 @@
-{"version":3,"file":"reactApp.js","sourceRoot":"","sources":["../../../src/routes/reactApp.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"reactApp.js","sourceRoot":"","sources":["../../../src/routes/reactApp.ts"],"names":[],"mappings":"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"}

package/generated/index.ts

@@ -21,7 +21,7 @@ import 'typescript';
 /** Generate Source Graph */
 
 const sourceGraph =
-  '{"options":{"directed":true,"multigraph":false,"compound":false},"nodes":[{"v":"@proteinjs/server/NodeGlobalDataStorage","value":{"packageName":"@proteinjs/server","name":"NodeGlobalDataStorage","filePath":"/home/runner/work/server/server/packages/server/src/NodeGlobalDataStorage.ts","qualifiedName":"@proteinjs/server/NodeGlobalDataStorage","isAbstract":false,"isStatic":false,"visibility":"public","properties":[{"name":"HOOK_INITIALIZED","type":null,"isOptional":false,"isAbstract":false,"isStatic":true,"visibility":"private"},{"name":"GLOBAL_DATA","type":{"packageName":"@proteinjs/server","name":"{ [id: string]: GlobalData }","filePath":null,"qualifiedName":"@proteinjs/server/{ [id: string]: GlobalData }","typeParameters":null,"directParents":null},"isOptional":false,"isAbstract":false,"isStatic":true,"visibility":"private"},{"name":"environment","type":null,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public"}],"methods":[{"name":"setData","returnType":null,"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"data","type":{"packageName":"@proteinjs/server-api","name":"GlobalData","filePath":null,"qualifiedName":"@proteinjs/server-api/GlobalData","typeParameters":null,"directParents":null}}]},{"name":"getData","returnType":{"packageName":"@proteinjs/server-api","name":"GlobalData","filePath":null,"qualifiedName":"@proteinjs/server-api/GlobalData","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]},{"name":"initHook","returnType":null,"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private","parameters":[]}],"typeParameters":[],"directParentInterfaces":[{"packageName":"@proteinjs/server-api","name":"GlobalDataStorage","filePath":null,"qualifiedName":"@proteinjs/server-api/GlobalDataStorage","properties":[],"methods":[],"typeParameters":[],"directParents":[]}],"directParentClasses":[],"sourceType":2}},{"v":"@proteinjs/server-api/GlobalDataStorage"},{"v":"@proteinjs/server/NodeSessionDataStorage","value":{"packageName":"@proteinjs/server","name":"NodeSessionDataStorage","filePath":"/home/runner/work/server/server/packages/server/src/NodeSessionDataStorage.ts","qualifiedName":"@proteinjs/server/NodeSessionDataStorage","isAbstract":false,"isStatic":false,"visibility":"public","properties":[{"name":"HOOK_INITIALIZED","type":null,"isOptional":false,"isAbstract":false,"isStatic":true,"visibility":"private"},{"name":"SESSION_DATA","type":{"packageName":"@proteinjs/server","name":"{ [id: string]: SessionData }","filePath":null,"qualifiedName":"@proteinjs/server/{ [id: string]: SessionData }","typeParameters":null,"directParents":null},"isOptional":false,"isAbstract":false,"isStatic":true,"visibility":"private"},{"name":"environment","type":null,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public"}],"methods":[{"name":"setData","returnType":null,"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"data","type":{"packageName":"@proteinjs/server-api","name":"SessionData","filePath":null,"qualifiedName":"@proteinjs/server-api/SessionData","typeParameters":null,"directParents":null}}]},{"name":"getData","returnType":{"packageName":"@proteinjs/server-api","name":"SessionData","filePath":null,"qualifiedName":"@proteinjs/server-api/SessionData","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]},{"name":"clearData","returnType":{"packageName":"","name":"void","filePath":null,"qualifiedName":"/void","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]},{"name":"initHook","returnType":null,"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private","parameters":[]}],"typeParameters":[],"directParentInterfaces":[{"packageName":"@proteinjs/server-api","name":"SessionDataStorage","filePath":null,"qualifiedName":"@proteinjs/server-api/SessionDataStorage","properties":[],"methods":[],"typeParameters":[],"directParents":[]}],"directParentClasses":[],"sourceType":2}},{"v":"@proteinjs/server-api/SessionDataStorage"},{"v":"@proteinjs/server/ExtendedIncomingMessage","value":{"packageName":"@proteinjs/server","name":"ExtendedIncomingMessage","filePath":"/home/runner/work/server/server/packages/server/src/SocketIOServerRepo.ts","qualifiedName":"@proteinjs/server/ExtendedIncomingMessage","properties":[{"name":"sessionID","type":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null},"isOptional":true,"isAbstract":false,"isStatic":false,"visibility":"public"},{"name":"user","type":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null},"isOptional":true,"isAbstract":false,"isStatic":false,"visibility":"public"}],"methods":[],"typeParameters":[],"directParents":[{"packageName":"http","name":"IncomingMessage","filePath":null,"qualifiedName":"http/IncomingMessage","properties":[],"methods":[],"typeParameters":[],"directParents":[]}],"sourceType":3}},{"v":"http/IncomingMessage"},{"v":"@proteinjs/server/ExtendedSocket","value":{"packageName":"@proteinjs/server","name":"ExtendedSocket","filePath":"/home/runner/work/server/server/packages/server/src/SocketIOServerRepo.ts","qualifiedName":"@proteinjs/server/ExtendedSocket","properties":[{"name":"request","type":{"packageName":"@proteinjs/server","name":"ExtendedIncomingMessage","filePath":null,"qualifiedName":"@proteinjs/server/ExtendedIncomingMessage","typeParameters":null,"directParents":null},"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public"}],"methods":[],"typeParameters":[],"directParents":[{"packageName":"socket.io","name":"Socket","filePath":null,"qualifiedName":"socket.io/Socket","properties":[],"methods":[],"typeParameters":[],"directParents":[]}],"sourceType":3}},{"v":"socket.io/Socket"},{"v":"@proteinjs/server/environmentCache","value":{"packageName":"@proteinjs/server","name":"environmentCache","filePath":"/home/runner/work/server/server/packages/server/src/envCache.ts","qualifiedName":"@proteinjs/server/environmentCache","type":{"packageName":"","name":"GlobalDataCache<Env>","filePath":null,"qualifiedName":"/GlobalDataCache<Env>","typeParameters":[],"directParents":[{"packageName":"@proteinjs/server-api","name":"GlobalDataCache","filePath":null,"qualifiedName":"@proteinjs/server-api/GlobalDataCache","typeParameters":["@proteinjs/server-api/Env"],"directParents":null}]},"isExported":true,"isConst":true,"sourceType":0}},{"v":"@proteinjs/server-api/GlobalDataCache"},{"v":"@proteinjs/server/healthCheck","value":{"packageName":"@proteinjs/server","name":"healthCheck","filePath":"/home/runner/work/server/server/packages/server/src/routes/healthCheck.ts","qualifiedName":"@proteinjs/server/healthCheck","type":{"packageName":"@proteinjs/server-api","name":"Route","filePath":null,"qualifiedName":"@proteinjs/server-api/Route","typeParameters":[],"directParents":[{"packageName":"@proteinjs/server-api","name":"Route","filePath":null,"qualifiedName":"@proteinjs/server-api/Route","typeParameters":[],"directParents":null}]},"isExported":true,"isConst":true,"sourceType":0}},{"v":"@proteinjs/server-api/Route"}],"edges":[{"v":"@proteinjs/server/NodeGlobalDataStorage","w":"@proteinjs/server-api/GlobalDataStorage","value":"implements interface"},{"v":"@proteinjs/server/NodeSessionDataStorage","w":"@proteinjs/server-api/SessionDataStorage","value":"implements interface"},{"v":"@proteinjs/server/ExtendedIncomingMessage","w":"http/IncomingMessage","value":"extends interface"},{"v":"@proteinjs/server/ExtendedSocket","w":"socket.io/Socket","value":"extends interface"},{"v":"@proteinjs/server/environmentCache","w":"@proteinjs/server-api/GlobalDataCache","value":"has type"},{"v":"@proteinjs/server/healthCheck","w":"@proteinjs/server-api/Route","value":"has type"}]}';
+  '{"options":{"directed":true,"multigraph":false,"compound":false},"nodes":[{"v":"/() => void"},{"v":"@proteinjs/server/NodeGlobalDataStorage","value":{"packageName":"@proteinjs/server","name":"NodeGlobalDataStorage","filePath":"/home/runner/work/server/server/packages/server/src/NodeGlobalDataStorage.ts","qualifiedName":"@proteinjs/server/NodeGlobalDataStorage","isAbstract":false,"isStatic":false,"visibility":"public","properties":[{"name":"HOOK_INITIALIZED","type":null,"isOptional":false,"isAbstract":false,"isStatic":true,"visibility":"private"},{"name":"GLOBAL_DATA","type":{"packageName":"@proteinjs/server","name":"{ [id: string]: GlobalData }","filePath":null,"qualifiedName":"@proteinjs/server/{ [id: string]: GlobalData }","typeParameters":null,"directParents":null},"isOptional":false,"isAbstract":false,"isStatic":true,"visibility":"private"},{"name":"environment","type":null,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public"}],"methods":[{"name":"setData","returnType":null,"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"data","type":{"packageName":"@proteinjs/server-api","name":"GlobalData","filePath":null,"qualifiedName":"@proteinjs/server-api/GlobalData","typeParameters":null,"directParents":null}}]},{"name":"getData","returnType":{"packageName":"@proteinjs/server-api","name":"GlobalData","filePath":null,"qualifiedName":"@proteinjs/server-api/GlobalData","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]},{"name":"initHook","returnType":null,"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private","parameters":[]}],"typeParameters":[],"directParentInterfaces":[{"packageName":"@proteinjs/server-api","name":"GlobalDataStorage","filePath":null,"qualifiedName":"@proteinjs/server-api/GlobalDataStorage","properties":[],"methods":[],"typeParameters":[],"directParents":[]}],"directParentClasses":[],"sourceType":2}},{"v":"@proteinjs/server-api/GlobalDataStorage"},{"v":"@proteinjs/server/NodeSessionDataStorage","value":{"packageName":"@proteinjs/server","name":"NodeSessionDataStorage","filePath":"/home/runner/work/server/server/packages/server/src/NodeSessionDataStorage.ts","qualifiedName":"@proteinjs/server/NodeSessionDataStorage","isAbstract":false,"isStatic":false,"visibility":"public","properties":[{"name":"HOOK_INITIALIZED","type":null,"isOptional":false,"isAbstract":false,"isStatic":true,"visibility":"private"},{"name":"SESSION_DATA","type":{"packageName":"@proteinjs/server","name":"{ [id: string]: SessionData }","filePath":null,"qualifiedName":"@proteinjs/server/{ [id: string]: SessionData }","typeParameters":null,"directParents":null},"isOptional":false,"isAbstract":false,"isStatic":true,"visibility":"private"},{"name":"environment","type":null,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public"}],"methods":[{"name":"setData","returnType":null,"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[{"name":"data","type":{"packageName":"@proteinjs/server-api","name":"SessionData","filePath":null,"qualifiedName":"@proteinjs/server-api/SessionData","typeParameters":null,"directParents":null}}]},{"name":"getData","returnType":{"packageName":"@proteinjs/server-api","name":"SessionData","filePath":null,"qualifiedName":"@proteinjs/server-api/SessionData","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]},{"name":"clearData","returnType":{"packageName":"","name":"void","filePath":null,"qualifiedName":"/void","typeParameters":null,"directParents":null},"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public","parameters":[]},{"name":"initHook","returnType":null,"isAsync":false,"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"private","parameters":[]}],"typeParameters":[],"directParentInterfaces":[{"packageName":"@proteinjs/server-api","name":"SessionDataStorage","filePath":null,"qualifiedName":"@proteinjs/server-api/SessionDataStorage","properties":[],"methods":[],"typeParameters":[],"directParents":[]}],"directParentClasses":[],"sourceType":2}},{"v":"@proteinjs/server-api/SessionDataStorage"},{"v":"@proteinjs/server/ExtendedIncomingMessage","value":{"packageName":"@proteinjs/server","name":"ExtendedIncomingMessage","filePath":"/home/runner/work/server/server/packages/server/src/SocketIOServerRepo.ts","qualifiedName":"@proteinjs/server/ExtendedIncomingMessage","properties":[{"name":"sessionID","type":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null},"isOptional":true,"isAbstract":false,"isStatic":false,"visibility":"public"},{"name":"user","type":{"packageName":"","name":"string","filePath":null,"qualifiedName":"/string","typeParameters":null,"directParents":null},"isOptional":true,"isAbstract":false,"isStatic":false,"visibility":"public"}],"methods":[],"typeParameters":[],"directParents":[{"packageName":"http","name":"IncomingMessage","filePath":null,"qualifiedName":"http/IncomingMessage","properties":[],"methods":[],"typeParameters":[],"directParents":[]}],"sourceType":3}},{"v":"http/IncomingMessage"},{"v":"@proteinjs/server/ExtendedSocket","value":{"packageName":"@proteinjs/server","name":"ExtendedSocket","filePath":"/home/runner/work/server/server/packages/server/src/SocketIOServerRepo.ts","qualifiedName":"@proteinjs/server/ExtendedSocket","properties":[{"name":"request","type":{"packageName":"@proteinjs/server","name":"ExtendedIncomingMessage","filePath":null,"qualifiedName":"@proteinjs/server/ExtendedIncomingMessage","typeParameters":null,"directParents":null},"isOptional":false,"isAbstract":false,"isStatic":false,"visibility":"public"}],"methods":[],"typeParameters":[],"directParents":[{"packageName":"socket.io","name":"Socket","filePath":null,"qualifiedName":"socket.io/Socket","properties":[],"methods":[],"typeParameters":[],"directParents":[]}],"sourceType":3}},{"v":"socket.io/Socket"},{"v":"@proteinjs/server/environmentCache","value":{"packageName":"@proteinjs/server","name":"environmentCache","filePath":"/home/runner/work/server/server/packages/server/src/envCache.ts","qualifiedName":"@proteinjs/server/environmentCache","type":{"packageName":"","name":"GlobalDataCache<Env>","filePath":null,"qualifiedName":"/GlobalDataCache<Env>","typeParameters":[],"directParents":[{"packageName":"@proteinjs/server-api","name":"GlobalDataCache","filePath":null,"qualifiedName":"@proteinjs/server-api/GlobalDataCache","typeParameters":["@proteinjs/server-api/Env"],"directParents":null}]},"isExported":true,"isConst":true,"sourceType":0}},{"v":"@proteinjs/server-api/GlobalDataCache"},{"v":"@proteinjs/server/healthCheck","value":{"packageName":"@proteinjs/server","name":"healthCheck","filePath":"/home/runner/work/server/server/packages/server/src/routes/healthCheck.ts","qualifiedName":"@proteinjs/server/healthCheck","type":{"packageName":"@proteinjs/server-api","name":"Route","filePath":null,"qualifiedName":"@proteinjs/server-api/Route","typeParameters":[],"directParents":[{"packageName":"@proteinjs/server-api","name":"Route","filePath":null,"qualifiedName":"@proteinjs/server-api/Route","typeParameters":[],"directParents":null}]},"isExported":true,"isConst":true,"sourceType":0}},{"v":"@proteinjs/server-api/Route"}],"edges":[{"v":"@proteinjs/server/NodeGlobalDataStorage","w":"@proteinjs/server-api/GlobalDataStorage","value":"implements interface"},{"v":"@proteinjs/server/NodeSessionDataStorage","w":"@proteinjs/server-api/SessionDataStorage","value":"implements interface"},{"v":"@proteinjs/server/ExtendedIncomingMessage","w":"http/IncomingMessage","value":"extends interface"},{"v":"@proteinjs/server/ExtendedSocket","w":"socket.io/Socket","value":"extends interface"},{"v":"@proteinjs/server/environmentCache","w":"@proteinjs/server-api/GlobalDataCache","value":"has type"},{"v":"@proteinjs/server/healthCheck","w":"@proteinjs/server-api/Route","value":"has type"}]}';
 
 /** Generate Source Links */
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/server",
-  "version": "3.5.2",
+  "version": "3.6.0",
   "description": "A server impl",
   "publishConfig": {
     "access": "public"
@@ -25,7 +25,7 @@
     "@proteinjs/event": "^1.0.18",
     "@proteinjs/logger": "^1.0.21",
     "@proteinjs/reflection": "^1.1.12",
-    "@proteinjs/server-api": "^3.1.2",
+    "@proteinjs/server-api": "^3.2.0",
     "@proteinjs/util-node": "^1.10.1",
     "body-parser": "1.19.0",
     "cookie-parser": "1.4.5",
@@ -64,5 +64,5 @@
   },
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
-  "gitHead": "ea237ffcd7725e009d841d339ed098e324d3afef"
+  "gitHead": "c1a14f62c4e023db66161869955baf616aab31bb"
 }

package/src/GracefulShutdown.ts

@@ -3,6 +3,18 @@ import { ServerConfig } from '@proteinjs/server-api';
 import { Logger } from '@proteinjs/logger';
 import { SocketIOServerRepo } from './SocketIOServerRepo';
 
+/** Releases a hold taken with {@link GracefulShutdown.hold}. Idempotent. */
+export type HoldRelease = () => void;
+
+/** A hold outstanding on the process: its label plus whatever the holder attached for the logs. */
+export type Hold = { label: string; context?: Record<string, unknown> };
+
+/**
+ * Follows the process's holds as they come and go — the dev supervisor's lease projection
+ * (@n3xah/util-server's ServePackageHold) is the one consumer; it never decides anything here.
+ */
+export type HoldObserver = { acquired?: (label: string) => void; released?: (label: string) => void };
+
 /**
  * The one owner of the server's shutdown state. Installed by `startServer` before the listener
  * opens; the `/health-check` route reads `isShuttingDown()` — no other flag system exists.
@@ -17,23 +29,46 @@ import { SocketIOServerRepo } from './SocketIOServerRepo';
  *     2. The listener closes (socket.io clients are disconnected, and `io.close()` closes the
  *        http server it is attached to), idle keep-alive connections are closed, and in-flight
  *        requests run to completion.
- *     3. The drain is BOUNDED by `shutdown.drainTimeoutMs`: past it, remaining connections are
- *        force-closed. Either way the exit code is 0 — a drained shutdown is not a crash.
+ *     3. The process WAITS for its HOLDS (`hold(label)` below) to release, bounded by
+ *        `shutdown.turnDrainMs`: work that must not die with the process and that no HTTP
+ *        connection represents — the canonical holder is a chat turn whose client has gone
+ *        (the response detached, the model still writing, nothing persisted yet). Past the
+ *        bound every hold still outstanding is logged by label and abandoned.
+ *     4. The connection drain is BOUNDED by `shutdown.drainTimeoutMs`: past it, remaining
+ *        connections are force-closed. Either way the exit code is 0 — a drained shutdown is
+ *        not a crash.
  *   SIGINT → exit 0 immediately (dev ctrl-C: fast and quiet; nothing needs flushing).
  *   exit 86 → NOT this class's concern: `process.exit(86)` is the ServePackageSupervisor
  *     restart-request contract (a liveness monitor giving up on a dependency); it is not
  *     signal-driven and is untouched by these handlers.
  *
+ * Holds are a process-wide static seam so a holder never needs the server instance (a turn
+ * registry, a suite with no listener): `hold(label, context)` returns the release; the same
+ * label held twice is one hold (the release is shared — the turn registry's idempotence);
+ * `holds()` lists what is outstanding, in acquisition order; `observeHolds` lets the dev
+ * supervisor's lease follow the same set, so a holder declares itself ONCE and both the
+ * pre-signal restart deferral (dev) and the post-SIGTERM drain (prod) honor it.
+ *
+ * Why holds and not connections: the 2026-09-05 prod kill — a phone locked mid-turn, the route
+ * detached the dead response and the turn ran on to persist, GKE's autoscaler evicted the pod,
+ * and this drain saw NO connection in flight, so `process.exit(0)` ran 5 s after SIGTERM with the
+ * model call 32 s in. Nothing persisted, nothing logged (plans/FREE_AGENT.md §M.14).
+ *
  * A SIGTERM before the listener is open (mid-boot kill) exits 0 immediately — nothing is
  * registered anywhere and nothing is in flight.
  *
  * Supervisor compatibility (dev): ServePackageSupervisor SIGTERMs the child's process group and
  * escalates to SIGKILL after its grace period (default 10s); its exit handler ignores exit codes
  * for kills it initiated, so the drain-then-exit-0 shape cannot be misread. DEVELOPMENT defaults
- * `drainDelayMs` to 0 so supervised restarts stay fast.
+ * `drainDelayMs` to 0 so supervised restarts stay fast; a turn in flight under the supervisor is
+ * covered BEFORE the signal by its lease (the hold projection), not by this drain.
  */
 export class GracefulShutdown {
   private static instance?: GracefulShutdown;
+  private static holds = new Map<string, { hold: Hold; release: HoldRelease }>();
+  private static holdObservers = new Set<HoldObserver>();
+  private static holdWaiters: Array<() => void> = [];
+  private static staticLogger = new Logger({ name: 'GracefulShutdown' });
   private shuttingDown = false;
   private logger = new Logger({ name: 'GracefulShutdown' });
 
@@ -58,6 +93,48 @@ export class GracefulShutdown {
     return GracefulShutdown.instance?.shuttingDown ?? false;
   }
 
+  /**
+   * Keep the process alive through a SIGTERM drain until the returned release is called (bounded
+   * by `shutdown.turnDrainMs`). `label` names the work in the drain's logs (`chat-turn:<id>`);
+   * `context` rides beside it (chat id, user id). Holding a label already held returns the
+   * existing release — one hold per label.
+   */
+  static hold(label: string, context?: Record<string, unknown>): HoldRelease {
+    const existing = GracefulShutdown.holds.get(label);
+    if (existing) {
+      return existing.release;
+    }
+    const release: HoldRelease = () => {
+      if (GracefulShutdown.holds.get(label)?.release !== release) {
+        return; // already released (or the label re-held since — that hold has its own release)
+      }
+      GracefulShutdown.holds.delete(label);
+      GracefulShutdown.notify('released', label);
+      if (GracefulShutdown.holds.size === 0) {
+        const waiters = GracefulShutdown.holdWaiters.splice(0, GracefulShutdown.holdWaiters.length);
+        for (const resolve of waiters) {
+          resolve();
+        }
+      }
+    };
+    GracefulShutdown.holds.set(label, { hold: context ? { label, context } : { label }, release });
+    GracefulShutdown.notify('acquired', label);
+    return release;
+  }
+
+  /** Every hold outstanding right now, in acquisition order. */
+  static outstandingHolds(): Hold[] {
+    return Array.from(GracefulShutdown.holds.values()).map((entry) => ({ ...entry.hold }));
+  }
+
+  /** Follow holds as they are acquired and released. Returns the unsubscribe. */
+  static observeHolds(observer: HoldObserver): () => void {
+    GracefulShutdown.holdObservers.add(observer);
+    return () => {
+      GracefulShutdown.holdObservers.delete(observer);
+    };
+  }
+
   private async drainAndExit(): Promise<void> {
     if (this.shuttingDown) {
       return; // already draining; the sender's escalation is SIGKILL, not a second drain
@@ -69,8 +146,10 @@ export class GracefulShutdown {
     }
     const drainDelayMs = this.drainDelayMs();
     const drainTimeoutMs = this.drainTimeoutMs();
+    const turnDrainMs = this.turnDrainMs();
     this.logger.info({
-      message: `Received SIGTERM — /health-check now reports 503; accepting connections for another ${drainDelayMs}ms, then draining in-flight requests (bound: ${drainTimeoutMs}ms)`,
+      message: `Received SIGTERM — /health-check now reports 503; accepting connections for another ${drainDelayMs}ms, then draining in-flight requests (bound: ${drainTimeoutMs}ms) and ${GracefulShutdown.holds.size} hold(s) (bound: ${turnDrainMs}ms)`,
+      obj: { holds: GracefulShutdown.outstandingHolds() },
     });
     // 1. Readiness-propagation window: the LB observes the 503 while we still serve normally.
     await this.sleep(drainDelayMs);
@@ -87,7 +166,10 @@ export class GracefulShutdown {
       this.server.close();
     }
     this.server.closeIdleConnections();
-    // 3. Bounded: past the drain timeout, force-close what remains. Exit 0 either way.
+    // 3. Holds: work no connection represents (a detached chat turn). In-flight requests keep
+    // running meanwhile — the listener is closed, existing connections are not. Bounded.
+    await this.drainHolds(turnDrainMs);
+    // 4. Bounded: past the drain timeout, force-close what remains. Exit 0 either way.
     if (!(await this.settled(drained, drainTimeoutMs))) {
       this.logger.warn({
         message: `Drain exceeded its ${drainTimeoutMs}ms bound — force-closing the remaining connections`,
@@ -98,6 +180,27 @@ export class GracefulShutdown {
     process.exit(0);
   }
 
+  private async drainHolds(turnDrainMs: number): Promise<void> {
+    if (GracefulShutdown.holds.size === 0) {
+      return;
+    }
+    this.logger.info({
+      message: `Listener closed — waiting for ${GracefulShutdown.holds.size} hold(s) to release (bound: ${turnDrainMs}ms)`,
+      obj: { holds: GracefulShutdown.outstandingHolds() },
+    });
+    if (await this.settled(GracefulShutdown.whenNoHolds(), turnDrainMs)) {
+      this.logger.info({ message: `Every hold released — continuing the drain` });
+      return;
+    }
+    const abandoned = GracefulShutdown.outstandingHolds();
+    this.logger.warn({
+      message: `Hold drain exceeded its ${turnDrainMs}ms bound — abandoning ${abandoned.length} hold(s): ${abandoned
+        .map((hold) => hold.label)
+        .join(', ')}`,
+      obj: { holds: abandoned },
+    });
+  }
+
   private exitNow(): void {
     this.shuttingDown = true;
     this.logger.info({ message: `Received SIGINT — exiting immediately` });
@@ -115,6 +218,31 @@ export class GracefulShutdown {
     return this.config.shutdown?.drainTimeoutMs ?? 30_000;
   }
 
+  private turnDrainMs(): number {
+    return this.config.shutdown?.turnDrainMs ?? 240_000;
+  }
+
+  private static whenNoHolds(): Promise<void> {
+    if (GracefulShutdown.holds.size === 0) {
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve) => GracefulShutdown.holdWaiters.push(resolve));
+  }
+
+  private static notify(event: 'acquired' | 'released', label: string): void {
+    for (const observer of Array.from(GracefulShutdown.holdObservers)) {
+      try {
+        observer[event]?.(label);
+      } catch (error: any) {
+        // An observer follows the holds; its failure never touches the hold itself.
+        GracefulShutdown.staticLogger.warn({
+          message: `A hold observer threw on ${event}`,
+          obj: { label, error: error?.message },
+        });
+      }
+    }
+  }
+
   /** Await a promise with a deadline; true if it settled in time. */
   private async settled(promise: Promise<void>, ms: number): Promise<boolean> {
     let timer: NodeJS.Timeout | undefined;

package/src/routes/reactApp.ts

@@ -24,6 +24,13 @@ export const createReactApp = (serverConfig: ServerConfig) => {
       }
 
       const helmet = ReactHelmet.renderStatic();
+      // The page must ALWAYS revalidate (found live 2026-09-01, the mobile-app stale-page
+      // investigation): without an explicit policy, HTTP heuristic caching applies (RFC 9111
+      // §4.2.2) — WKWebView in particular can serve the cached page without revalidating,
+      // across app force-quits, pinning stale bundle POINTERS long after a deploy. The hashed
+      // bundles under /static keep their long cache (a fresh page always points at fresh
+      // hashes); `no-cache` + the ETag express already stamps = a cheap 304 on every load.
+      response.set('Cache-Control', 'no-cache');
       response.send(`<!DOCTYPE html>
                 <html ${helmet.htmlAttributes}>
                     <head>

package/test/fixture/gracefulShutdownServer.js

@@ -2,18 +2,22 @@
  * Test fixture: a REAL @proteinjs/server (the built dist — the same code prod runs) with a
  * deliberately slow endpoint, so the graceful-shutdown suite can hold a request in flight
  * while it signals the process. Run with:
- *   FIXTURE_PORT=<port> [FIXTURE_DRAIN_DELAY_MS=..] [FIXTURE_DRAIN_TIMEOUT_MS=..] node gracefulShutdownServer.js
+ *   FIXTURE_PORT=<port> [FIXTURE_DRAIN_DELAY_MS=..] [FIXTURE_DRAIN_TIMEOUT_MS=..] [FIXTURE_TURN_DRAIN_MS=..] node gracefulShutdownServer.js
  *
  * Markers on stdout (the suite's synchronization points):
  *   FIXTURE_READY          — startServer resolved (the listener is up)
  *   SLOW_REQUEST_STARTED   — the /slow handler is executing (a request is now in flight)
+ *   HOLD_ACQUIRED <label>  — /hold took a process hold (GracefulShutdown.hold) that outlives
+ *                            its request: the response ends at once, the hold releases itself
+ *                            ?ms= later — a detached chat turn's shape (no connection, work live)
+ *   HOLD_RELEASED <label>  — that hold released
  *
  * Also serves /server-timeouts: the LIVE http.Server's keepAliveTimeout/headersTimeout (read off
  * the request's own socket), so the keep-alive suite asserts the running instance through the
  * front door instead of re-deriving values from source.
  */
 const expressSession = require('express-session');
-const { startServer } = require('../../dist/generated/index.js');
+const { startServer, GracefulShutdown } = require('../../dist/generated/index.js');
 
 const port = Number(process.env.FIXTURE_PORT);
 if (!port) {
@@ -44,6 +48,20 @@ startServer({
         response.status(200).send('session-cookie-set');
         return;
       }
+      if (request.path === '/hold') {
+        // A hold that OUTLIVES its request — the detached-turn shape the drain must wait for:
+        // the response ends now (no connection remains), the work stays live for ?ms=.
+        const label = String(request.query.label ?? 'fixture-hold');
+        const ms = Number(request.query.ms ?? 5000);
+        const release = GracefulShutdown.hold(label, { source: 'fixture', ms });
+        console.log(`HOLD_ACQUIRED ${label}`);
+        setTimeout(() => {
+          release();
+          console.log(`HOLD_RELEASED ${label}`);
+        }, ms);
+        response.status(200).send('held');
+        return;
+      }
       if (request.path !== '/slow') {
         next();
         return;
@@ -54,8 +72,13 @@ startServer({
       response.status(200).send('slow-done');
     },
   },
+  // A bundle pointer so the '*' react-app route serves its HTML — the html-cache-control
+  // suite asserts response headers on the page the app actually ships. No staticContentDir:
+  // nothing needs the bundle to resolve, only the page response to render.
+  staticContent: { bundlePaths: ['bundles/app.test.js'] },
   shutdown: {
     drainDelayMs: process.env.FIXTURE_DRAIN_DELAY_MS ? Number(process.env.FIXTURE_DRAIN_DELAY_MS) : undefined,
     drainTimeoutMs: process.env.FIXTURE_DRAIN_TIMEOUT_MS ? Number(process.env.FIXTURE_DRAIN_TIMEOUT_MS) : undefined,
+    turnDrainMs: process.env.FIXTURE_TURN_DRAIN_MS ? Number(process.env.FIXTURE_TURN_DRAIN_MS) : undefined,
   },
 }).then(() => console.log('FIXTURE_READY'));

package/test/gracefulShutdown.test.ts

@@ -13,6 +13,11 @@ import { ChildProcess, spawn } from 'child_process';
  *             idle keep-alives are closed, and the process exits 0 — bounded by
  *             shutdown.drainTimeoutMs (past it, remaining connections are force-closed and
  *             the exit is still 0).
+ *             HOLDS (GracefulShutdown.hold): work no connection represents — a chat turn whose
+ *             client disconnected (the 2026-09-05 prod kill, plans/FREE_AGENT.md §M.14) — keeps
+ *             the process alive past the connection drain until it releases, bounded by
+ *             shutdown.turnDrainMs; past THAT bound the holds still outstanding are logged by
+ *             label and abandoned, and the exit is still 0.
  *   SIGINT  → immediate exit 0 (dev ctrl-C: fast, quiet).
  *   exit 86 → RESTART_REQUEST_EXIT_CODE, untouched by this feature: process.exit(86) is not
  *             signal-driven (ServePackageSupervisor's respawn contract rides it).
@@ -101,9 +106,70 @@ describe('graceful shutdown', () => {
     expect(exit).toEqual({ code: 0, signal: null });
     expect(Date.now() - sigintAt).toBeLessThan(2000); // no drain delay on the fast path
   }, 30000);
+
+  describe('holds — work no connection represents (a detached chat turn)', () => {
+    it('SIGTERM: a hold whose request already ended keeps the process alive past the connection drain; its release lets the exit proceed', async () => {
+      // No delay, a short connection bound, a long hold bound: the ONLY thing that can keep this
+      // process alive after SIGTERM is the hold.
+      fixture = await startFixture({ drainDelayMs: 0, drainTimeoutMs: 1000, turnDrainMs: 20000 });
+
+      // The detached-turn shape: the request ends immediately (no connection remains), the work
+      // it started stays live for 5s and releases its hold when done.
+      const held = await request(fixture.port, '/hold?label=chat-turn:detached-turn&ms=5000');
+      expect(held).toEqual({ status: 200, body: 'held' });
+      await fixture.waitForMarker('HOLD_ACQUIRED chat-turn:detached-turn');
+
+      const sigtermAt = Date.now();
+      fixture.child.kill('SIGTERM');
+
+      // 1. Past the connection drain (nothing was in flight — it completes at once; the listener
+      //    is closed) the process is STILL RUNNING: the hold is what keeps it.
+      await sleep(2500);
+      expect(fixture.child.exitCode).toBeNull();
+      expect(fixture.child.signalCode).toBeNull();
+      await expect(request(fixture.port, '/health-check')).rejects.toMatchObject({
+        code: expect.stringMatching(/ECONNREFUSED|ECONNRESET/),
+      });
+      expect(fixture.stdout()).toContain('waiting for 1 hold(s) to release (bound: 20000ms)');
+
+      // 2. The work finishes and releases; the exit follows the RELEASE (~5s), not the 20s bound.
+      const exit = await fixture.exited;
+      expect(exit).toEqual({ code: 0, signal: null });
+      const elapsed = Date.now() - sigtermAt;
+      expect(elapsed).toBeGreaterThanOrEqual(4500);
+      expect(elapsed).toBeLessThan(12000);
+      expect(fixture.stdout()).toContain('HOLD_RELEASED chat-turn:detached-turn');
+      expect(fixture.stdout()).toContain('Every hold released');
+    }, 40000);
+
+    it('SIGTERM: the hold drain is BOUNDED — past turnDrainMs the outstanding holds are logged by label, abandoned, and the exit is still 0', async () => {
+      fixture = await startFixture({ drainDelayMs: 0, drainTimeoutMs: 1000, turnDrainMs: 3000 });
+
+      // A hold that would outlive the bound by far.
+      const held = await request(fixture.port, '/hold?label=chat-turn:abandoned-turn&ms=60000');
+      expect(held.status).toBe(200);
+      await fixture.waitForMarker('HOLD_ACQUIRED chat-turn:abandoned-turn');
+
+      const sigtermAt = Date.now();
+      fixture.child.kill('SIGTERM');
+
+      const exit = await fixture.exited;
+      expect(exit).toEqual({ code: 0, signal: null });
+      const elapsed = Date.now() - sigtermAt;
+      expect(elapsed).toBeGreaterThanOrEqual(3000); // the bound was actually served
+      expect(elapsed).toBeLessThan(9000); // ...and it ended the wait, not the 60s hold
+      // The abandoned work is NAMED — the line the 2026-09-05 kill never left behind.
+      expect(fixture.stdout()).toContain('abandoning 1 hold(s): chat-turn:abandoned-turn');
+      expect(fixture.stdout()).not.toContain('HOLD_RELEASED');
+    }, 30000);
+  });
 });
 
-async function startFixture(shutdown: { drainDelayMs: number; drainTimeoutMs: number }): Promise<Fixture> {
+async function startFixture(shutdown: {
+  drainDelayMs: number;
+  drainTimeoutMs: number;
+  turnDrainMs?: number;
+}): Promise<Fixture> {
   const port = await ephemeralPort();
   // Scrub the env vars startServer reads (dev machines export some of these): the fixture's
   // behavior must come from its own config only.
@@ -119,6 +185,7 @@ async function startFixture(shutdown: { drainDelayMs: number; drainTimeoutMs: nu
       FIXTURE_PORT: String(port),
       FIXTURE_DRAIN_DELAY_MS: String(shutdown.drainDelayMs),
       FIXTURE_DRAIN_TIMEOUT_MS: String(shutdown.drainTimeoutMs),
+      ...(shutdown.turnDrainMs !== undefined ? { FIXTURE_TURN_DRAIN_MS: String(shutdown.turnDrainMs) } : {}),
     },
     stdio: ['ignore', 'pipe', 'pipe'],
   });

package/test/holdSeam.test.ts

@@ -0,0 +1,82 @@
+import { GracefulShutdown } from '../src/GracefulShutdown';
+
+/**
+ * The holds seam as a process-wide static contract — what a holder (a chat turn registry) and a
+ * follower (the dev supervisor's lease projection) can rely on without a server instance:
+ * one hold per label, idempotent release, acquisition-ordered listing with the holder's context,
+ * and observers told of every transition exactly once.
+ */
+describe('GracefulShutdown holds', () => {
+  afterEach(() => {
+    for (const hold of GracefulShutdown.outstandingHolds()) {
+      GracefulShutdown.hold(hold.label)(); // hold() on a held label returns its release
+    }
+  });
+
+  it('a hold is listed with its context until its release; releasing twice is a no-op', () => {
+    const release = GracefulShutdown.hold('chat-turn:t1', { chatId: 'c1', userId: 'u1' });
+    expect(GracefulShutdown.outstandingHolds()).toEqual([
+      { label: 'chat-turn:t1', context: { chatId: 'c1', userId: 'u1' } },
+    ]);
+    release();
+    expect(GracefulShutdown.outstandingHolds()).toEqual([]);
+    release();
+    expect(GracefulShutdown.outstandingHolds()).toEqual([]);
+  });
+
+  it('holding a label already held is the SAME hold — one entry, one release', () => {
+    const first = GracefulShutdown.hold('chat-turn:t2', { chatId: 'c2' });
+    const second = GracefulShutdown.hold('chat-turn:t2', { chatId: 'other' });
+    expect(second).toBe(first);
+    expect(GracefulShutdown.outstandingHolds()).toEqual([{ label: 'chat-turn:t2', context: { chatId: 'c2' } }]);
+    second();
+    expect(GracefulShutdown.outstandingHolds()).toEqual([]);
+  });
+
+  it('a stale release never drops a label re-held since', () => {
+    const stale = GracefulShutdown.hold('chat-turn:t3');
+    stale();
+    const fresh = GracefulShutdown.hold('chat-turn:t3');
+    stale(); // the first hold's release, called again after the label was re-held
+    expect(GracefulShutdown.outstandingHolds()).toEqual([{ label: 'chat-turn:t3' }]);
+    fresh();
+    expect(GracefulShutdown.outstandingHolds()).toEqual([]);
+  });
+
+  it('lists holds in acquisition order', () => {
+    GracefulShutdown.hold('b');
+    GracefulShutdown.hold('a');
+    expect(GracefulShutdown.outstandingHolds().map((hold) => hold.label)).toEqual(['b', 'a']);
+  });
+
+  it('observers see each acquisition and release once; a re-hold of a held label is silent; unsubscribing stops the stream', () => {
+    const events: string[] = [];
+    const unsubscribe = GracefulShutdown.observeHolds({
+      acquired: (label) => events.push(`+${label}`),
+      released: (label) => events.push(`-${label}`),
+    });
+    const release = GracefulShutdown.hold('chat-turn:t4');
+    GracefulShutdown.hold('chat-turn:t4');
+    release();
+    release();
+    unsubscribe();
+    GracefulShutdown.hold('chat-turn:t5')();
+    expect(events).toEqual(['+chat-turn:t4', '-chat-turn:t4']);
+  });
+
+  it('a throwing observer never touches the hold', () => {
+    const unsubscribe = GracefulShutdown.observeHolds({
+      acquired: () => {
+        throw new Error('follower down');
+      },
+      released: () => {
+        throw new Error('follower down');
+      },
+    });
+    const release = GracefulShutdown.hold('chat-turn:t6');
+    expect(GracefulShutdown.outstandingHolds()).toEqual([{ label: 'chat-turn:t6' }]);
+    release();
+    expect(GracefulShutdown.outstandingHolds()).toEqual([]);
+    unsubscribe();
+  });
+});

package/test/htmlCacheControl.test.ts

@@ -0,0 +1,129 @@
+import * as http from 'http';
+import * as net from 'net';
+import * as path from 'path';
+import { ChildProcess, spawn } from 'child_process';
+
+/**
+ * HTML cache policy of a real server process (spawns the built dist — run `npm run build`
+ * first), asserted through the front door on the page the react-app route actually sends.
+ *
+ * THE CLASS THIS PINS (found live 2026-09-01, the mobile-app stale-page investigation): the
+ * HTML response carried NO Cache-Control header — an ETag only. With no explicit policy,
+ * HTTP heuristic caching applies (RFC 9111 §4.2.2), and WKWebView in particular can serve
+ * the cached page without revalidating — across app force-quits — pinning stale bundle
+ * POINTERS long after a deploy. The hashed bundles under /static keep their long cache (a
+ * new page always points at new hashes); the PAGE must always revalidate. `no-cache` states
+ * exactly that, and the ETag the response already carries keeps revalidation a cheap 304.
+ */
+const packageRoot = path.join(__dirname, '..');
+const fixturePath = path.join(__dirname, 'fixture', 'gracefulShutdownServer.js');
+
+describe('html cache policy', () => {
+  let fixture: Fixture | undefined;
+
+  afterEach(async () => {
+    if (fixture && fixture.child.exitCode === null && fixture.child.signalCode === null) {
+      fixture.child.kill('SIGKILL');
+      await fixture.exited.catch(() => undefined);
+    }
+    fixture = undefined;
+  });
+
+  it('the react-app HTML response says Cache-Control: no-cache — the page always revalidates', async () => {
+    fixture = await startFixture();
+
+    const result = await request(fixture.port, '/');
+    expect(result.status).toBe(200);
+    // Sanity: this IS the react-app page (the configured bundle pointer is in the body).
+    expect(result.body).toContain('bundles/app.test.js');
+    expect(result.headers['content-type']).toContain('text/html');
+    expect(result.headers['cache-control']).toBe('no-cache');
+  }, 30000);
+
+  it('every page path rides the same policy (the catch-all route is the one HTML owner)', async () => {
+    fixture = await startFixture();
+
+    const result = await request(fixture.port, '/chat');
+    expect(result.status).toBe(200);
+    expect(result.headers['content-type']).toContain('text/html');
+    expect(result.headers['cache-control']).toBe('no-cache');
+  }, 30000);
+});
+
+type Fixture = {
+  child: ChildProcess;
+  port: number;
+  exited: Promise<{ code: number | null; signal: NodeJS.Signals | null }>;
+};
+
+async function startFixture(): Promise<Fixture> {
+  const port = await ephemeralPort();
+  // Scrub the env vars startServer reads (dev machines export some of these): the fixture's
+  // behavior must come from its own config only.
+  const env = { ...process.env };
+  delete env.SERVER_PORT;
+  delete env.DEVELOPMENT;
+  delete env.DISABLE_HOT_CLIENT_BUILDS;
+  delete env.HMR_PORT;
+  const child = spawn(process.execPath, [fixturePath], {
+    cwd: packageRoot,
+    env: { ...env, FIXTURE_PORT: String(port) },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  let output = '';
+  child.stdout!.on('data', (chunk) => (output += String(chunk)));
+  child.stderr!.on('data', (chunk) => (output += String(chunk)));
+  const exited = new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve) =>
+    child.once('exit', (code, signal) => resolve({ code, signal }))
+  );
+  // Ready = the health check answers 200 (readiness through the front door, not log lines).
+  const deadline = Date.now() + 20000;
+  for (;;) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+      throw new Error(`Fixture exited during boot; output:\n${output}`);
+    }
+    const result = await request(port, '/health-check').catch(() => undefined);
+    if (result?.status === 200) {
+      return { child, port, exited };
+    }
+    if (Date.now() > deadline) {
+      throw new Error(`Fixture never became ready; output:\n${output}`);
+    }
+    await sleep(100);
+  }
+}
+
+/** One request on its OWN connection (agent: false — no keep-alive pooling). The forwarded
+ *  proto is the LB topology in miniature: the prod shape 302s plain http to https. */
+function request(
+  port: number,
+  requestPath: string
+): Promise<{ status: number; body: string; headers: http.IncomingHttpHeaders }> {
+  return new Promise((resolve, reject) => {
+    const req = http.get(
+      { host: '127.0.0.1', port, path: requestPath, agent: false, headers: { 'X-Forwarded-Proto': 'https' } },
+      (res) => {
+        let body = '';
+        res.on('data', (chunk) => (body += String(chunk)));
+        res.on('end', () => resolve({ status: res.statusCode ?? 0, body, headers: res.headers }));
+        res.on('error', reject);
+      }
+    );
+    req.on('error', reject);
+  });
+}
+
+async function ephemeralPort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const probe = net.createServer();
+    probe.once('error', reject);
+    probe.listen(0, '127.0.0.1', () => {
+      const address = probe.address() as net.AddressInfo;
+      probe.close(() => resolve(address.port));
+    });
+  });
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+}