@wjarka/cezarion 0.15.1 → 0.16.0

package/dist/server/upgrade-router.d.ts

@@ -0,0 +1,23 @@
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+/**
+ * The HTTP server's one `upgrade` listener (#781, spec 2026-10-02-live-preview-v1 "WebSocket").
+ * Each WebSocket endpoint is a route; the first whose `match` returns params handles the upgrade,
+ * and an unmatched path is destroyed. Upgrade-only endpoints never reach Hono, so each one is
+ * inventoried by hand in BACKWARD_COMPATIBILITY.md §2.
+ */
+export interface UpgradeRoute {
+    /** Path params when `pathname` is this route's, else undefined. */
+    match(pathname: string): Record<string, string> | undefined;
+    handle(req: IncomingMessage, socket: Duplex, head: Buffer, params: Record<string, string>): void;
+}
+/** The server surface the router needs: the `http.Server` that `serve()` returns has it. */
+export interface UpgradeCapableServer {
+    on(event: 'upgrade', listener: (req: IncomingMessage, socket: Duplex, head: Buffer) => void): unknown;
+}
+export declare function attachUpgradeRouter(server: UpgradeCapableServer, routes: readonly UpgradeRoute[]): void;
+/**
+ * A `match` for one or more `/a/:param/b` patterns. A param is one non-empty segment, decoded;
+ * one that does not decode is no match.
+ */
+export declare function matchPath(patterns: readonly string[]): UpgradeRoute['match'];

package/dist/server/upgrade-router.js

@@ -0,0 +1,53 @@
+export function attachUpgradeRouter(server, routes) {
+    server.on('upgrade', (req, socket, head) => {
+        let pathname;
+        try {
+            // `req.url` on an upgrade is the path (+query); the base only satisfies URL parsing.
+            pathname = new URL(req.url ?? '', 'http://localhost').pathname;
+        }
+        catch {
+            socket.destroy();
+            return;
+        }
+        for (const route of routes) {
+            const params = route.match(pathname);
+            if (params)
+                return route.handle(req, socket, head, params);
+        }
+        // With an `upgrade` listener installed, Node no longer destroys unhandled upgrades.
+        socket.destroy();
+    });
+}
+/**
+ * A `match` for one or more `/a/:param/b` patterns. A param is one non-empty segment, decoded;
+ * one that does not decode is no match.
+ */
+export function matchPath(patterns) {
+    const compiled = patterns.map(pattern => pattern.split('/'));
+    return pathname => {
+        const parts = pathname.split('/');
+        for (const segments of compiled) {
+            if (segments.length !== parts.length)
+                continue;
+            const params = {};
+            const matched = segments.every((segment, i) => {
+                const part = parts[i];
+                if (!segment.startsWith(':'))
+                    return segment === part;
+                if (!part)
+                    return false;
+                try {
+                    params[segment.slice(1)] = decodeURIComponent(part);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+            if (matched)
+                return params;
+        }
+        return undefined;
+    };
+}
+//# sourceMappingURL=upgrade-router.js.map

package/dist/server/upgrade-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-router.js","sourceRoot":"","sources":["../../src/server/upgrade-router.ts"],"names":[],"mappings":"AAqBA,MAAM,UAAU,mBAAmB,CAAC,MAA4B,EAAE,MAA+B;IAC/F,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;QACzC,IAAI,QAAgB,CAAC;QACrB,IAAI,CAAC;YACH,qFAAqF;YACrF,QAAQ,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,EAAE,kBAAkB,CAAC,CAAC,QAAQ,CAAC;QACjE,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,CAAC,OAAO,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YACrC,IAAI,MAAM;gBAAE,OAAO,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7D,CAAC;QACD,oFAAoF;QACpF,MAAM,CAAC,OAAO,EAAE,CAAC;IACnB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,QAA2B;IACnD,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7D,OAAO,QAAQ,CAAC,EAAE;QAChB,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAClC,KAAK,MAAM,QAAQ,IAAI,QAAQ,EAAE,CAAC;YAChC,IAAI,QAAQ,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;gBAAE,SAAS;YAC/C,MAAM,MAAM,GAA2B,EAAE,CAAC;YAC1C,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE;gBAC5C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;gBACvB,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;oBAAE,OAAO,OAAO,KAAK,IAAI,CAAC;gBACtD,IAAI,CAAC,IAAI;oBAAE,OAAO,KAAK,CAAC;gBACxB,IAAI,CAAC;oBACH,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;oBACpD,OAAO,IAAI,CAAC;gBACd,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,KAAK,CAAC;gBACf,CAAC;YACH,CAAC,CAAC,CAAC;YACH,IAAI,OAAO;gBAAE,OAAO,MAAM,CAAC;QAC7B,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;AACJ,CAAC"}

package/dist/server/validators.d.ts

@@ -1,4 +1,4 @@
-import type { Env, MiddlewareHandler } from 'hono';
+import type { Context, Env, MiddlewareHandler } from 'hono';
 import type { z } from 'zod';
 /**
  * Request validation as ROUTE MIDDLEWARE — the `json` / `param` / `query` trio every mutating
@@ -50,6 +50,11 @@ type JsonOptions = ErrorOptions & {
      * behaviour moved with it rather than being lost in the move.
      */
     malformed?: unknown;
+    /**
+     * Builds the rejection itself, from the issues and the parsed input. The private preview tool
+     * route (#781) answers its agent a typed 200 result naming the field, not this API's 400.
+     */
+    invalid?: (c: Context, error: z.ZodError, input: unknown) => Response;
 };
 /**
  * The request/response split, spelled out rather than inferred.

package/dist/server/validators.js

@@ -25,13 +25,13 @@ schema, options = {}) {
     // `= null` default would silently overwrite exactly that case.
     const absent = 'absent' in options ? options.absent : null;
     const malformed = 'malformed' in options ? options.malformed : absent;
-    const { message, code } = options;
+    const { message, code, invalid } = options;
     const check = (input, c) => {
         const resolved = typeof schema === 'function' ? schema() : schema;
         const parsed = resolved.safeParse(input);
-        return parsed.success
-            ? { ok: true, data: parsed.data }
-            : { ok: false, response: reject(c, parsed.error, message, code) };
+        if (parsed.success)
+            return { ok: true, data: parsed.data };
+        return { ok: false, response: invalid ? invalid(c, parsed.error, input) : reject(c, parsed.error, message, code) };
     };
     const validate = validator('json', (value, c) => {
         const result = check(value, c);

package/dist/server/validators.js.map

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

package/dist/server/ws.d.ts

@@ -1,5 +1,6 @@
 import type { IncomingMessage } from 'node:http';
 import type { Duplex } from 'node:stream';
+import type { UpgradeRoute } from './upgrade-router.ts';
 /**
  * The cockpit's WebSocket subscription bus (`GET /api/v1/ws`, upgrade-only).
  * Design + the subscribe/unsubscribe discipline: spec
@@ -16,10 +17,14 @@ import type { Duplex } from 'node:stream';
  * to mean N polls every 5 s forever; now they mean one publisher while at
  * least one tab subscribes, and none afterwards.
  *
- * Security: the hub itself never decides who may connect — `attach` takes the
- * upgrade guard as a function, and server.ts supplies the WebSocket twin of
- * the `/api/*` request-origin guard (#426). See `verifyWsUpgrade` there for
+ * Security: the hub itself never decides who may connect — `handleUpgrade`
+ * takes the upgrade guard's verdict, and server.ts supplies the WebSocket twin
+ * of the `/api/*` request-origin guard (#426). See `verifyWsUpgrade` there for
  * what it admits, and the caveat about which topics may live on this hub.
+ *
+ * The hub does not listen on the HTTP server itself: the one `upgrade` listener
+ * is `attachUpgradeRouter` (upgrade-router.ts, #781), and `socketHubRoute` is
+ * this hub's route in it.
  */
 /** The one upgrade path. Workspace-level like `/api/workspace/events` — never
  *  mirrored under `/api/p/:projectId` (topics carry workspace data). */
@@ -56,25 +61,18 @@ export interface TopicOptions {
 export type WsUpgradeVerdict = false | {
     trusted: boolean;
 };
-/** The minimal server surface `attach` needs — satisfied by the `http.Server`
- *  that `@hono/node-server`'s `serve()` returns. */
-export interface UpgradeCapableServer {
-    on(event: 'upgrade', listener: (req: IncomingMessage, socket: Duplex, head: Buffer) => void): unknown;
-    on(event: 'close', listener: () => void): unknown;
-}
 export interface SocketHub {
     /** Register a topic clients may subscribe to. Registration is boot-time
      *  wiring (createApp), so a duplicate name is a programming error: throw.
      *  `options.loopbackReadable` defaults to `false` (topic legible to trusted
      *  connections only) — see `TopicOptions`. */
     registerTopic(name: string, publisher: TopicPublisher, options?: TopicOptions): void;
-    /** Start accepting `WS_PATH` upgrades on `server`. `verifyUpgrade` is the
-     *  request-origin guard — `false` answers 403 before the handshake, otherwise
-     *  its `trusted` flag decides which topics the connection may read. Boot-time
-     *  wiring like `registerTopic`: attaching twice throws. */
-    attach(server: UpgradeCapableServer, verifyUpgrade: (req: IncomingMessage) => WsUpgradeVerdict): void;
-    /** Stop publishers, terminate clients, clear timers. Idempotent; also runs
-     *  on the attached server's own `close`. */
+    /** Accept one `WS_PATH` upgrade under the request-origin guard's verdict:
+     *  `false` answers 403 before the handshake, otherwise its `trusted` flag
+     *  decides which topics the connection may read. */
+    handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer, verdict: WsUpgradeVerdict): void;
+    /** Stop publishers, terminate clients, clear timers. Idempotent; the server
+     *  that routes upgrades here calls it on its own `close`. */
     close(): void;
 }
 export interface SocketHubOptions {
@@ -83,3 +81,5 @@ export interface SocketHubOptions {
     heartbeatMs?: number;
 }
 export declare function createSocketHub(options?: SocketHubOptions): SocketHub;
+/** The hub's route in the upgrade router: `WS_PATH`, under `verifyUpgrade`. */
+export declare function socketHubRoute(hub: SocketHub, verifyUpgrade: (req: IncomingMessage) => WsUpgradeVerdict): UpgradeRoute;

package/dist/server/ws.js

@@ -16,10 +16,14 @@ import { z } from 'zod';
  * to mean N polls every 5 s forever; now they mean one publisher while at
  * least one tab subscribes, and none afterwards.
  *
- * Security: the hub itself never decides who may connect — `attach` takes the
- * upgrade guard as a function, and server.ts supplies the WebSocket twin of
- * the `/api/*` request-origin guard (#426). See `verifyWsUpgrade` there for
+ * Security: the hub itself never decides who may connect — `handleUpgrade`
+ * takes the upgrade guard's verdict, and server.ts supplies the WebSocket twin
+ * of the `/api/*` request-origin guard (#426). See `verifyWsUpgrade` there for
  * what it admits, and the caveat about which topics may live on this hub.
+ *
+ * The hub does not listen on the HTTP server itself: the one `upgrade` listener
+ * is `attachUpgradeRouter` (upgrade-router.ts, #781), and `socketHubRoute` is
+ * this hub's route in it.
  */
 /** The one upgrade path. Workspace-level like `/api/workspace/events` — never
  *  mirrored under `/api/p/:projectId` (topics carry workspace data). */
@@ -99,6 +103,33 @@ export function createSocketHub(options = {}) {
             state.stop = null;
         }
     };
+    /** Started by the first upgrade, so a hub nobody connects to holds no timer. */
+    const startHeartbeat = () => {
+        if (heartbeat !== undefined)
+            return;
+        heartbeat = setInterval(() => {
+            for (const [ws, client] of clients) {
+                if (!client.alive) {
+                    // Missed the previous beat's pong — the peer is gone. Terminate (not
+                    // a polite close, there is nobody to handshake with); 'close' fires
+                    // synchronously and dropClient releases its topics.
+                    ws.terminate();
+                    continue;
+                }
+                client.alive = false;
+                ws.ping(); // protocol ping — a live browser auto-pongs, flipping `alive` back
+                // App-level beat too. The browser NEVER surfaces the protocol ping to
+                // page JS, so a client cannot tell a silent-dead socket (sleep, network
+                // partition — no FIN ever arrives) from an idle-but-healthy one on the
+                // protocol ping alone. This visible frame is what the client's own
+                // watchdog watches to decide to reconnect. Sent to every client,
+                // subscribed or not; the client ignores it beyond noting liveness.
+                send(ws, { type: 'ping' });
+            }
+        }, heartbeatMs);
+        // Never the reason the process stays up — the HTTP server owns lifetime.
+        heartbeat.unref?.();
+    };
     const dropClient = (ws) => {
         const client = clients.get(ws);
         if (!client)
@@ -108,7 +139,7 @@ export function createSocketHub(options = {}) {
         clients.delete(ws);
     };
     wss.on('connection', (ws, _req, trusted) => {
-        // `trusted` is emitted by `attach` from the upgrade verdict; default false is
+        // `trusted` is emitted by `handleUpgrade` from the upgrade verdict; default false is
         // the safe read for any path that reaches here without one.
         const client = { alive: true, topics: new Set(), trusted: trusted === true };
         clients.set(ws, client);
@@ -150,56 +181,20 @@ export function createSocketHub(options = {}) {
                 loopbackReadable: options?.loopbackReadable ?? false,
             });
         },
-        attach(server, verifyUpgrade) {
-            // Boot-time wiring like `registerTopic`, so a second call is a programming
-            // error rather than something to absorb: it would install a second
-            // `upgrade` listener and orphan the first heartbeat interval (`close`
-            // clears only the last one). Throw the same way registration does.
-            if (heartbeat !== undefined)
-                throw new Error('ws hub already attached');
-            server.on('upgrade', (req, socket, head) => {
-                // `req.url` on an upgrade is the request path (+query); the base is
-                // only there to satisfy URL parsing of a relative reference.
-                const pathname = new URL(req.url ?? '', 'http://localhost').pathname;
-                if (pathname !== WS_PATH) {
-                    // With an `upgrade` listener installed, Node no longer auto-destroys
-                    // unhandled upgrades — do it explicitly or the socket leaks.
-                    socket.destroy();
-                    return;
-                }
-                const verdict = verifyUpgrade(req);
-                if (!verdict) {
-                    socket.write('HTTP/1.1 403 Forbidden\r\nconnection: close\r\n\r\n');
-                    socket.destroy();
-                    return;
-                }
-                // Carry the verdict's trust flag onto the connection — `subscribe` reads
-                // it to gate non-`loopbackReadable` topics.
-                wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws, req, verdict.trusted));
-            });
-            server.on('close', () => hub.close());
-            heartbeat = setInterval(() => {
-                for (const [ws, client] of clients) {
-                    if (!client.alive) {
-                        // Missed the previous beat's pong — the peer is gone. Terminate (not
-                        // a polite close, there is nobody to handshake with); 'close' fires
-                        // synchronously and dropClient releases its topics.
-                        ws.terminate();
-                        continue;
-                    }
-                    client.alive = false;
-                    ws.ping(); // protocol ping — a live browser auto-pongs, flipping `alive` back
-                    // App-level beat too. The browser NEVER surfaces the protocol ping to
-                    // page JS, so a client cannot tell a silent-dead socket (sleep, network
-                    // partition — no FIN ever arrives) from an idle-but-healthy one on the
-                    // protocol ping alone. This visible frame is what the client's own
-                    // watchdog watches to decide to reconnect. Sent to every client,
-                    // subscribed or not; the client ignores it beyond noting liveness.
-                    send(ws, { type: 'ping' });
-                }
-            }, heartbeatMs);
-            // Never the reason the process stays up — the HTTP server owns lifetime.
-            heartbeat.unref?.();
+        handleUpgrade(req, socket, head, verdict) {
+            if (closed) {
+                socket.destroy();
+                return;
+            }
+            if (!verdict) {
+                socket.write('HTTP/1.1 403 Forbidden\r\nconnection: close\r\n\r\n');
+                socket.destroy();
+                return;
+            }
+            startHeartbeat();
+            // Carry the verdict's trust flag onto the connection — `subscribe` reads
+            // it to gate non-`loopbackReadable` topics.
+            wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws, req, verdict.trusted));
         },
         close() {
             if (closed)
@@ -215,4 +210,11 @@ export function createSocketHub(options = {}) {
     };
     return hub;
 }
+/** The hub's route in the upgrade router: `WS_PATH`, under `verifyUpgrade`. */
+export function socketHubRoute(hub, verifyUpgrade) {
+    return {
+        match: (pathname) => (pathname === WS_PATH ? {} : undefined),
+        handle: (req, socket, head) => hub.handleUpgrade(req, socket, head, verifyUpgrade(req)),
+    };
+}
 //# sourceMappingURL=ws.js.map

package/dist/server/ws.js.map

@@ -1 +1 @@
-{"version":3,"file":"ws.js","sourceRoot":"","sources":["../../src/server/ws.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ws.js","sourceRoot":"","sources":["../../src/server/ws.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAkB,MAAM,IAAI,CAAC;AACrD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;wEACwE;AACxE,MAAM,CAAC,MAAM,OAAO,GAAG,YAAY,CAAC;AAEpC;;;8EAG8E;AAC9E,MAAM,YAAY,GAAG,MAAM,CAAC;AAE5B;+EAC+E;AAC/E,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEhC;;sBAEsB;AACtB,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;IAC1C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;CAClC,CAAC,CAAC;AA0EH,MAAM,UAAU,eAAe,CAAC,OAAO,GAAqB,EAAE;IAC5D,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,YAAY,CAAC;IACxD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC7C,MAAM,OAAO,GAAG,IAAI,GAAG,EAA0B,CAAC;IAClD,MAAM,GAAG,GAAG,IAAI,eAAe,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,iBAAiB,EAAE,CAAC,CAAC;IACnF,IAAI,SAAqD,CAAC;IAC1D,IAAI,MAAM,GAAG,KAAK,CAAC;IAEnB,MAAM,IAAI,GAAG,CAAC,EAAa,EAAE,KAAc,EAAQ,EAAE;QACnD,4EAA4E;QAC5E,IAAI,EAAE,CAAC,UAAU,KAAK,CAAC;YAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1D,CAAC,CAAC;IAEF,MAAM,SAAS,GAAG,CAAC,EAAa,EAAE,MAAmB,EAAE,KAAa,EAAQ,EAAE;QAC5E,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC,CAAC;YAC3D,OAAO;QACT,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,gBAAgB,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAC/C,yEAAyE;YACzE,0EAA0E;YAC1E,0EAA0E;YAC1E,0EAA0E;YAC1E,4CAA4C;YAC5C,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,CAAC,CAAC;YAC7D,OAAO;QACT,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,OAAO,CAAC,wDAAwD;QAC9F,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACzB,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1B,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YACxB,KAAK,CAAC,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE;gBAC1C,KAAK,MAAM,UAAU,IAAI,KAAK,CAAC,WAAW;oBAAE,IAAI,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/F,CAAC,CAAC,CAAC;QACL,CAAC;QACD,2EAA2E;QAC3E,2EAA2E;QAC3E,+DAA+D;QAC/D,KAAK,KAAK,CAAC,SAAS;aACjB,QAAQ,EAAE;aACV,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;YACb,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC;gBAAE,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACzE,CAAC,CAAC;aACD,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC5B,CAAC,CAAC;IAEF,MAAM,WAAW,GAAG,CAAC,EAAa,EAAE,MAAmB,EAAE,KAAa,EAAQ,EAAE;QAC9E,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;YAAE,OAAO;QACzC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC7B,IAAI,KAAK,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YACxD,KAAK,CAAC,IAAI,EAAE,CAAC;YACb,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;QACpB,CAAC;IACH,CAAC,CAAC;IAEF,gFAAgF;IAChF,MAAM,cAAc,GAAG,GAAS,EAAE;QAChC,IAAI,SAAS,KAAK,SAAS;YAAE,OAAO;QACpC,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;YAC3B,KAAK,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;gBACnC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;oBAClB,qEAAqE;oBACrE,oEAAoE;oBACpE,oDAAoD;oBACpD,EAAE,CAAC,SAAS,EAAE,CAAC;oBACf,SAAS;gBACX,CAAC;gBACD,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;gBACrB,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,mEAAmE;gBAC9E,sEAAsE;gBACtE,wEAAwE;gBACxE,uEAAuE;gBACvE,mEAAmE;gBACnE,iEAAiE;gBACjE,mEAAmE;gBACnE,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC,EAAE,WAAW,CAAC,CAAC;QAChB,yEAAyE;QACzE,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC;IACtB,CAAC,CAAC;IAEF,MAAM,UAAU,GAAG,CAAC,EAAa,EAAQ,EAAE;QACzC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC/B,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;YAAE,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;QACvE,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACrB,CAAC,CAAC;IAEF,GAAG,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC,EAAa,EAAE,IAAqB,EAAE,OAAiB,EAAE,EAAE;QAC/E,qFAAqF;QACrF,4DAA4D;QAC5D,MAAM,MAAM,GAAgB,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAG,EAAE,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;QAC1F,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACxB,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;YACjB,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC;QACtB,CAAC,CAAC,CAAC;QACH,EAAE,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE;YACvB,IAAI,MAAe,CAAC;YACpB,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YACnC,CAAC;YAAC,MAAM,CAAC;gBACP,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,2BAA2B,EAAE,CAAC,CAAC;gBAChE,OAAO;YACT,CAAC;YACD,MAAM,KAAK,GAAG,iBAAiB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YAClD,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;gBACnB,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,gEAAgE,EAAE,CAAC,CAAC;gBACrG,OAAO;YACT,CAAC;YACD,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,WAAW;gBAAE,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;;gBACxE,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACjD,CAAC,CAAC,CAAC;QACH,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;QACrC,wEAAwE;QACxE,2CAA2C;QAC3C,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,MAAM,GAAG,GAAc;QACrB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO;YACpC,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,IAAI,EAAE,CAAC,CAAC;YAC9E,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE;gBACf,SAAS;gBACT,WAAW,EAAE,IAAI,GAAG,EAAE;gBACtB,IAAI,EAAE,IAAI;gBACV,gBAAgB,EAAE,OAAO,EAAE,gBAAgB,IAAI,KAAK;aACrD,CAAC,CAAC;QACL,CAAC;QAED,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;YACtC,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,CAAC,OAAO,EAAE,CAAC;gBACjB,OAAO;YACT,CAAC;YACD,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,MAAM,CAAC,KAAK,CAAC,qDAAqD,CAAC,CAAC;gBACpE,MAAM,CAAC,OAAO,EAAE,CAAC;gBACjB,OAAO;YACT,CAAC;YACD,cAAc,EAAE,CAAC;YACjB,yEAAyE;YACzE,4CAA4C;YAC5C,GAAG,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;QACjG,CAAC;QAED,KAAK;YACH,IAAI,MAAM;gBAAE,OAAO;YACnB,MAAM,GAAG,IAAI,CAAC;YACd,aAAa,CAAC,SAAS,CAAC,CAAC;YACzB,KAAK,MAAM,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;gBACrC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,4DAA4D;gBAC5E,EAAE,CAAC,SAAS,EAAE,CAAC;YACjB,CAAC;YACD,GAAG,CAAC,KAAK,EAAE,CAAC;QACd,CAAC;KACF,CAAC;IAEF,OAAO,GAAG,CAAC;AACb,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,cAAc,CAAC,GAAc,EAAE,aAAyD;IACtG,OAAO;QACL,KAAK,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QAC5D,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC;KACxF,CAAC;AACJ,CAAC"}

package/dist/skills-remote.d.ts

@@ -96,6 +96,13 @@ export declare function shouldRecordFetchFailure(opts: {
 }): boolean;
 /** Test hook: simulate a process-local failed attempt for this source. */
 export declare function __markCloneAttemptedForTests(repo: string): void;
+/** Test hook: hold this source's clone/fetch open until `until` settles (#859). */
+export declare function __holdFetchForTests(repo: string, until: Promise<void>): void;
+/**
+ * Test hook: park this project's next passive load right after its list-only
+ * pass until `until` settles (#859). Resolves once the load has parked there.
+ */
+export declare function __pauseAfterCachedListForTests(repoRoot: string, until: Promise<void>): Promise<void>;
 /**
  * The current team-skill list for this project, straight from memory. The
  * first call per `repoRoot` kicks off an async background load (clone + list)
@@ -109,5 +116,12 @@ export declare function getTeamSkillsCached(repoRoot: string): Skill[];
  * background convergence read after they have already rendered local skills.
  */
 export declare function waitForTeamSkills(repoRoot: string): Promise<Skill[]>;
+/**
+ * The first load's list of the bare clones already on disk, published before
+ * any passive fetch (#859). Never waits on the network: no clone yet means an
+ * empty list, not a clone. When a refresh started this project's first load
+ * there is no list-only pass, and this answers with the current list.
+ */
+export declare function waitForCachedTeamSkills(repoRoot: string): Promise<Skill[]>;
 /** Refresh: clone missing sources, `git fetch` existing ones, reload the list. */
 export declare function refreshTeamSkills(repoRoot: string): Promise<Skill[]>;

package/dist/skills-remote.js

@@ -452,16 +452,41 @@ export function shouldRecordFetchFailure(opts) {
 export function __markCloneAttemptedForTests(repo) {
     cloneAttempted.add(repo);
 }
+/** Test hook: hold this source's clone/fetch open until `until` settles (#859). */
+export function __holdFetchForTests(repo, until) {
+    const held = until.finally(() => {
+        if (fetchInFlight.get(repo) === held)
+            fetchInFlight.delete(repo);
+    });
+    fetchInFlight.set(repo, held);
+}
+const cachedListPauses = new Map();
+/**
+ * Test hook: park this project's next passive load right after its list-only
+ * pass until `until` settles (#859). Resolves once the load has parked there.
+ */
+export function __pauseAfterCachedListForTests(repoRoot, until) {
+    return new Promise((reached) => { cachedListPauses.set(repoRoot, { reached, until }); });
+}
 // Both maps are keyed by `repoRoot` (multi-project workspace, step 2.6): each
 // project resolves its own `.ai/cezar/config.json` → `skillsRepos`, so one
 // project's team-skill list must never be served under another project's scope.
 const teamSkillsByRoot = new Map();
 const firstLoadByRoot = new Map();
+// The first load's list-only pass over the clones already on disk (#859).
+const cachedListByRoot = new Map();
+// Bumped by every post-fetch publication, so a list-only pass that finishes
+// late never replaces a newer list (a concurrent refresh) in `teamSkillsByRoot`.
+const postFetchListsByRoot = new Map();
 function initialTeamSkillsLoad(repoRoot) {
     const existing = firstLoadByRoot.get(repoRoot);
     if (existing)
         return existing;
-    const load = loadTeamSkills(repoRoot, false).catch(() => teamSkillsByRoot.get(repoRoot) ?? []);
+    let listed;
+    cachedListByRoot.set(repoRoot, new Promise((resolve) => { listed = resolve; }));
+    const load = loadTeamSkills(repoRoot, false, listed).catch(() => teamSkillsByRoot.get(repoRoot) ?? []);
+    // A load that failed before its list-only pass still settles the cached wait.
+    void load.then((skills) => listed(skills));
     firstLoadByRoot.set(repoRoot, load);
     return load;
 }
@@ -483,6 +508,16 @@ export function getTeamSkillsCached(repoRoot) {
 export function waitForTeamSkills(repoRoot) {
     return initialTeamSkillsLoad(repoRoot);
 }
+/**
+ * The first load's list of the bare clones already on disk, published before
+ * any passive fetch (#859). Never waits on the network: no clone yet means an
+ * empty list, not a clone. When a refresh started this project's first load
+ * there is no list-only pass, and this answers with the current list.
+ */
+export function waitForCachedTeamSkills(repoRoot) {
+    void initialTeamSkillsLoad(repoRoot);
+    return cachedListByRoot.get(repoRoot) ?? Promise.resolve(teamSkillsByRoot.get(repoRoot) ?? []);
+}
 /** Refresh: clone missing sources, `git fetch` existing ones, reload the list. */
 export async function refreshTeamSkills(repoRoot) {
     const load = loadTeamSkills(repoRoot, true).catch(() => teamSkillsByRoot.get(repoRoot) ?? []);
@@ -528,16 +563,55 @@ function fetchBareSource(repo) {
     fetchInFlight.set(repo, work);
     return work;
 }
-async function loadTeamSkills(repoRoot, refresh) {
-    const config = await loadConfig(repoRoot);
+/** First source wins a name, in configured source order. */
+function mergeSourceLists(lists) {
     const out = [];
     const seen = new Set();
-    for (const src of config.skillsRepos) {
+    for (const skill of lists.flatMap((list) => list ?? [])) {
+        if (seen.has(skill.name))
+            continue;
+        seen.add(skill.name);
+        out.push(skill);
+    }
+    return out;
+}
+async function loadTeamSkills(repoRoot, refresh, onCachedList) {
+    const config = await loadConfig(repoRoot);
+    // Passive loads list the clones already on disk BEFORE any fetch (#859): the
+    // first restart past the TTL otherwise hides every team skill — and starves a
+    // recovered Continue of its playbook — for as long as the fetch takes.
+    let cached = [];
+    // Each source's stamp as the snapshot saw it. The bare clone and its stamp
+    // are shared by every project and process, so a fetch made for another
+    // project never bumps this one's generation; a moved stamp is how it shows.
+    let snapshotStamps = [];
+    const generation = postFetchListsByRoot.get(repoRoot) ?? 0;
+    // True once another load has published a post-fetch list since this one
+    // started: its snapshot may predate that list, so it must not win (#859).
+    const superseded = () => (postFetchListsByRoot.get(repoRoot) ?? 0) !== generation;
+    if (!refresh) {
+        snapshotStamps = config.skillsRepos.map((src) => readLastFetchAt(bareDirFor(src.repo)));
+        cached = await Promise.all(config.skillsRepos.map((src) => listRemoteSkills(src).catch(() => undefined)));
+        const pause = cachedListPauses.get(repoRoot);
+        if (pause) {
+            cachedListPauses.delete(repoRoot);
+            pause.reached();
+            await pause.until;
+        }
+        const listed = mergeSourceLists(cached);
+        if (!superseded())
+            teamSkillsByRoot.set(repoRoot, listed);
+        onCachedList?.(listed);
+    }
+    const lists = [];
+    for (const [index, src] of config.skillsRepos.entries()) {
         const now = Date.now();
         if (stampIsFresh(src.repo, now))
             cloneAttempted.delete(src.repo);
+        let fetched = false;
         try {
             if (refresh) {
+                fetched = true;
                 await fetchBareSource(src.repo);
             }
             else if (shouldPassiveFetch({
@@ -546,24 +620,26 @@ async function loadTeamSkills(repoRoot, refresh) {
                 ttlMs: PASSIVE_FETCH_TTL_MS,
             }) &&
                 !cloneAttempted.has(src.repo)) {
+                fetched = true;
                 await fetchBareSource(src.repo);
             }
         }
         catch {
             // offline / no access — list whatever an older clone has (or nothing)
         }
-        try {
-            for (const skill of await listRemoteSkills(src)) {
-                if (seen.has(skill.name))
-                    continue;
-                seen.add(skill.name);
-                out.push(skill);
-            }
-        }
-        catch {
-            // degrade: this source contributes nothing
-        }
+        // An unfetched source has not moved since the list-only pass unless
+        // another load fetched it meanwhile; reuse the snapshot only then.
+        const unmoved = !superseded() && readLastFetchAt(bareDirFor(src.repo)) === snapshotStamps[index];
+        const listed = fetched || !unmoved ? undefined : cached[index];
+        // degrade: a source that fails to list contributes nothing
+        lists.push(listed ?? (await listRemoteSkills(src).catch(() => undefined)));
     }
+    const out = mergeSourceLists(lists);
+    // A refresh always publishes. A passive load that a newer post-fetch list
+    // overtook defers to it rather than replacing it with an older view.
+    if (!refresh && superseded())
+        return teamSkillsByRoot.get(repoRoot) ?? out;
+    postFetchListsByRoot.set(repoRoot, (postFetchListsByRoot.get(repoRoot) ?? 0) + 1);
     teamSkillsByRoot.set(repoRoot, out);
     return out;
 }