@maka/maka-cli 5.175.0 → 5.176.0

package/bundle/typescript/src/commands/game/sideQuest/headless.js

@@ -188,6 +188,24 @@ export function buildPlayerFromSave(save) {
     player.refreshEdge(player.ateThisCycle && player.sleptThisCycle);
     return player;
 }
+/** Each rider's DocWagon contract comes off their OWN save (the
+ *  ruling: the wristband works at anyone's table). */
+function loadContract(game, save) {
+    const dw = save.game?.docwagon;
+    if (dw)
+        game.docwagonByPlayer.set(save.playerName, { ...dw });
+}
+/** The hosting server's death/extraction hooks, shared by runs and hubs. */
+function wireDeathHooks(game, logger, opts) {
+    game.onPlayerDeath = (p) => {
+        logger.system(`${p.name} is dead. The street keeps the change.`, 'all', 'death', { player: p.name });
+        opts.onPlayerDeath?.(p.name);
+    };
+    game.onPlayerExtracted = (p) => {
+        logger.system(`A DocWagon team carried ${p.name} off the job -- alive, billed, and out of the run.`, 'all', 'extracted', { player: p.name });
+        opts.onPlayerExtracted?.(p.name);
+    };
+}
 export async function createHeadlessSession(opts) {
     const logger = new EmitterLogger(opts.sink, opts.debug);
     const ctx = { sessionId: opts.sessionId, logger, client: opts.client };
@@ -199,22 +217,8 @@ export async function createHeadlessSession(opts) {
         if (typeof opts.tier === 'number')
             game.tier = opts.tier;
         logger.bindGame(() => game);
-        game.onPlayerDeath = (p) => {
-            logger.system(`${p.name} is dead. The street keeps the change.`, 'all', 'death', { player: p.name });
-            opts.onPlayerDeath?.(p.name);
-        };
-        game.onPlayerExtracted = (p) => {
-            logger.system(`A DocWagon team carried ${p.name} off the job -- alive, billed, and out of the run.`, 'all', 'extracted', { player: p.name });
-            opts.onPlayerExtracted?.(p.name);
-        };
-        // Each rider's DocWagon contract comes off their OWN save (the
-        // ruling: the wristband works at anyone's table).
-        const loadContract = (save) => {
-            const dw = save.game?.docwagon;
-            if (dw)
-                game.docwagonByPlayer.set(save.playerName, { ...dw });
-        };
-        loadContract(opts.players[0]);
+        wireDeathHooks(game, logger, opts);
+        loadContract(game, opts.players[0]);
         await game.initEngine({
             logFilePath: '',
             useAi: opts.useAi ?? false,
@@ -281,273 +285,330 @@ export async function createHeadlessSession(opts) {
         catch (err) {
             logger.write(`spawnCrew (hosted boot) failed: ${err instanceof Error ? err.message : String(err)}`);
         }
-        const spawnRoom = () => game.scene.determineStartRoom();
-        // PER-PLAYER MAP EVENTS (map-overlay wave 2026-08-24): each rider
-        // gets their own icon minimap -- the client holds no Room objects
-        // in a shared run. Fog of war and AR eyes are THIS player's. A
-        // jacked-in rider gets an EMPTY event -- their overlay blinks out
-        // until they jack back out (matrix ruling 2026-08-24).
-        const pushMap = () => {
-            const rooms = game.scene.getRooms();
-            const sealing = (r, d) => game.scene.barrierSealing(r, d);
+        return wireHeadless(game, ctx, logger);
+    });
+}
+/**
+ * EVERYTHING A HOSTED SESSION SHARES, run or hub (2026-09-12): the
+ * per-player map/room pushes, the command queue with the typist's own
+ * auth token, late joins, status, snapshots, dispose, the first paint
+ * and the scene-swap hook. createHeadlessSession boots a RUN and hands
+ * its Game here; createHeadlessHub boots a HUB and does the same.
+ */
+function wireHeadless(game, ctx, logger) {
+    const spawnRoom = () => game.scene.determineStartRoom();
+    // PER-PLAYER MAP EVENTS (map-overlay wave 2026-08-24): each rider
+    // gets their own icon minimap -- the client holds no Room objects
+    // in a shared run. Fog of war and AR eyes are THIS player's. A
+    // jacked-in rider gets an EMPTY event -- their overlay blinks out
+    // until they jack back out (matrix ruling 2026-08-24).
+    const pushMap = () => {
+        const rooms = game.scene.getRooms();
+        const sealing = (r, d) => game.scene.barrierSealing(r, d);
+        for (const p of game.scene.getPlayers()) {
+            if (game.scene.deadPlayers.has(p.name))
+                continue;
+            const here = p.currentLocation;
+            if (!here)
+                continue;
+            if (p.plane === 'matrix') {
+                logger.system('', { actor: p.name }, 'map', {});
+                logger.system('', { actor: p.name }, 'room', {});
+                continue;
+            }
+            const eyes = { visited: p.visitedRooms, arEyes: p.hasMatrixEyes() };
+            // THE CAPTION THE SOLO PANEL HAS ALWAYS HAD
+            // (RwPkFsRwd4c2uHvGN: "in a new shared run, there is no name on
+            // the area map"). renderMapViewport returns grid rows only --
+            // the name underneath is the CALLER's to add, and Game.updateExits
+            // adds it on the solo path. This push never did, so a rider on a
+            // shared run read an unlabelled map: the room box beside it was
+            // captioned, which is what made the gap look like a bug rather
+            // than a design.
+            //
+            // Untrimmed on purpose: the server cannot know the client's box
+            // width, the same compromise the room caption below already
+            // ships on.
+            const mapLines = renderMapViewport(rooms, here, sealing, eyes);
+            if (mapLines.length > 0)
+                mapLines.push(mapCaption(here.name));
+            // STRUCTURED DISTRICT MAP, ADDITIVE (2026-09-11): the same layout
+            // as data, on this same event, so the browser client draws it in
+            // its own style instead of reparsing the text (the `data.grid`
+            // pattern below). A decoration must never kill the push.
+            let district;
+            try {
+                district = serializeDistrictMap(rooms, here, sealing, eyes);
+            }
+            catch (err) {
+                logger.write(`District map serialize failed for ${p.name} in ${here.name}: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
+            }
+            logger.system(mapLines.join('\n'), { actor: p.name }, 'map', district ? { district } : undefined);
+            // THE ROOM BOX'S TWIN (playtest 2026-08-27, reported twice:
+            // "the room minimap isn't updating in the shared run, I only
+            // see @open floor"). Game.updateExits early-returns on
+            // `remoteSession`, so in a shared run the room box kept
+            // whatever the HUB painted into it and then FROZE -- the stale
+            // caption the player was reading was from the bar they left.
+            // The district map has had a server push since the map-overlay
+            // wave; this is the same wiring for the panel beside it.
+            //
+            // Rendered at renderRoomLayoutCompact's DEFAULT width, exactly
+            // as renderMapViewport is above: the server cannot know the
+            // client's box width (23% of a terminal it never sees), and
+            // the district map has shipped on that same compromise since
+            // 2026-08-24. Width only moves the elevation bar's right
+            // justification and how much grid is windowed in.
+            //
+            // A DECORATION MUST NEVER KILL THE RUN -- the solo path wraps
+            // this same render for the same reason, and a throw HERE would
+            // take down the whole table's command, not one player's panel.
+            try {
+                const roomLines = renderRoomLayoutCompact(here, p, {
+                    isOtherPlayer: a => game.scene.isHumanControlled(a),
+                    isHostile: a => hostileByStance(a) || enemyInFight(game.scene, p, a),
+                    // The leader's crew are the TABLE's crew -- without this
+                    // every non-leader saw them as neutral bystanders.
+                    isTableAlly: crewOfTable(game.scene.getPlayers()),
+                });
+                if (roomLines.length > 0) {
+                    roomLines.push(mapCaption(roomCaption(here, p)));
+                }
+                // STRUCTURED ROOM GEOMETRY, ADDITIVE (2026-09-07): the ASCII
+                // above stays the log-adjacent text every consumer already
+                // reads; a browser client wanting the site's real SVG DotMap
+                // instead reads `data.grid` off this SAME event -- no new
+                // event kind, no publication change (GameEvent.data already
+                // round-trips end to end). ensureGrid() always synthesizes now
+                // ("EVERY ROOM IS MATRIXED", room.ts:357-370, the 2026-08-25
+                // ruling that retired the spotless-room compat gap) -- the
+                // `undefined` in its return type is a vestige, kept guarded
+                // here anyway rather than asserted, since a decoration must
+                // never take down the room push (same reasoning as the
+                // try/catch this sits inside).
+                const grid = here.ensureGrid();
+                const data = grid ? { grid: serializeRoomGrid(grid, here.name) } : undefined;
+                logger.system(roomLines.join('\n'), { actor: p.name }, 'room', data);
+            }
+            catch (err) {
+                logger.write(`Room overlay render failed for ${p.name} in ${here.name}: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
+                logger.system('', { actor: p.name }, 'room', {});
+            }
+        }
+    };
+    const session = {
+        game,
+        logger,
+        command: (actorName, input, opts) => runInSession(ctx, () => runWithAuthToken(opts?.authToken, async () => {
+            const res = await game.handleInputAs(actorName, input);
+            session.pushStatus();
+            pushMap();
+            // THE WEB MAP FOLLOWS THE ROOM, NOT JUST YOUR OWN BODY
+            // (oHhjxjqKuptDGMHLD: a looted body stayed on the map "until I
+            // move"; 9aEMA4APbB6rYtWnT: a killed NPC's dot never changed).
+            // The condition beat is what the browser draws actors from. A
+            // kill or a loot mutates the room, not the killer, so this
+            // nudge -- one per command, coalesced -- still covers those.
+            // MOVEMENT NO LONGER WAITS FOR IT (q6tBaFn5EDmGMoJFh): the room
+            // publishes every occupant's position change to the humans in
+            // it the moment it happens (Room.noteOccupancyChanged), so an
+            // NPC stepping on its own reflect chain between commands
+            // reaches the browser without anyone typing.
+            game.player.noteConditionChanged();
+            // EVERY OTHER HUMAN WHO SAW THE ROOM CHANGE (genfBamjTvyHTdWhu):
+            // a member's overlay is written from the member's OWN beat now
+            // (Game.wireConditionReporting), so the same once-per-command
+            // nudge covers the typist and whoever shares their room -- a
+            // kill or a loot changes the room for all of them.
+            const typist = game.scene.getPlayerByName(actorName);
             for (const p of game.scene.getPlayers()) {
-                if (game.scene.deadPlayers.has(p.name))
+                if (p === game.player || game.scene.deadPlayers.has(p.name))
                     continue;
-                const here = p.currentLocation;
-                if (!here)
-                    continue;
-                if (p.plane === 'matrix') {
-                    logger.system('', { actor: p.name }, 'map', {});
-                    logger.system('', { actor: p.name }, 'room', {});
-                    continue;
-                }
-                const eyes = { visited: p.visitedRooms, arEyes: p.hasMatrixEyes() };
-                // THE CAPTION THE SOLO PANEL HAS ALWAYS HAD
-                // (RwPkFsRwd4c2uHvGN: "in a new shared run, there is no name on
-                // the area map"). renderMapViewport returns grid rows only --
-                // the name underneath is the CALLER's to add, and Game.updateExits
-                // adds it on the solo path. This push never did, so a rider on a
-                // shared run read an unlabelled map: the room box beside it was
-                // captioned, which is what made the gap look like a bug rather
-                // than a design.
-                //
-                // Untrimmed on purpose: the server cannot know the client's box
-                // width, the same compromise the room caption below already
-                // ships on.
-                const mapLines = renderMapViewport(rooms, here, sealing, eyes);
-                if (mapLines.length > 0)
-                    mapLines.push(mapCaption(here.name));
-                // STRUCTURED DISTRICT MAP, ADDITIVE (2026-09-11): the same layout
-                // as data, on this same event, so the browser client draws it in
-                // its own style instead of reparsing the text (the `data.grid`
-                // pattern below). A decoration must never kill the push.
-                let district;
-                try {
-                    district = serializeDistrictMap(rooms, here, sealing, eyes);
-                }
-                catch (err) {
-                    logger.write(`District map serialize failed for ${p.name} in ${here.name}: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
-                }
-                logger.system(mapLines.join('\n'), { actor: p.name }, 'map', district ? { district } : undefined);
-                // THE ROOM BOX'S TWIN (playtest 2026-08-27, reported twice:
-                // "the room minimap isn't updating in the shared run, I only
-                // see @open floor"). Game.updateExits early-returns on
-                // `remoteSession`, so in a shared run the room box kept
-                // whatever the HUB painted into it and then FROZE -- the stale
-                // caption the player was reading was from the bar they left.
-                // The district map has had a server push since the map-overlay
-                // wave; this is the same wiring for the panel beside it.
-                //
-                // Rendered at renderRoomLayoutCompact's DEFAULT width, exactly
-                // as renderMapViewport is above: the server cannot know the
-                // client's box width (23% of a terminal it never sees), and
-                // the district map has shipped on that same compromise since
-                // 2026-08-24. Width only moves the elevation bar's right
-                // justification and how much grid is windowed in.
-                //
-                // A DECORATION MUST NEVER KILL THE RUN -- the solo path wraps
-                // this same render for the same reason, and a throw HERE would
-                // take down the whole table's command, not one player's panel.
-                try {
-                    const roomLines = renderRoomLayoutCompact(here, p, {
-                        isOtherPlayer: a => game.scene.isHumanControlled(a),
-                        isHostile: a => hostileByStance(a) || enemyInFight(game.scene, p, a),
-                        // The leader's crew are the TABLE's crew -- without this
-                        // every non-leader saw them as neutral bystanders.
-                        isTableAlly: crewOfTable(game.scene.getPlayers()),
-                    });
-                    if (roomLines.length > 0) {
-                        roomLines.push(mapCaption(roomCaption(here, p)));
-                    }
-                    // STRUCTURED ROOM GEOMETRY, ADDITIVE (2026-09-07): the ASCII
-                    // above stays the log-adjacent text every consumer already
-                    // reads; a browser client wanting the site's real SVG DotMap
-                    // instead reads `data.grid` off this SAME event -- no new
-                    // event kind, no publication change (GameEvent.data already
-                    // round-trips end to end). ensureGrid() always synthesizes now
-                    // ("EVERY ROOM IS MATRIXED", room.ts:357-370, the 2026-08-25
-                    // ruling that retired the spotless-room compat gap) -- the
-                    // `undefined` in its return type is a vestige, kept guarded
-                    // here anyway rather than asserted, since a decoration must
-                    // never take down the room push (same reasoning as the
-                    // try/catch this sits inside).
-                    const grid = here.ensureGrid();
-                    const data = grid ? { grid: serializeRoomGrid(grid, here.name) } : undefined;
-                    logger.system(roomLines.join('\n'), { actor: p.name }, 'room', data);
-                }
-                catch (err) {
-                    logger.write(`Room overlay render failed for ${p.name} in ${here.name}: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
-                    logger.system('', { actor: p.name }, 'room', {});
-                }
+                if (p === typist || (typist && p.currentLocation === typist.currentLocation))
+                    p.noteConditionChanged();
             }
-        };
-        const session = {
-            game,
-            logger,
-            command: (actorName, input, opts) => runInSession(ctx, () => runWithAuthToken(opts?.authToken, async () => {
-                const res = await game.handleInputAs(actorName, input);
-                session.pushStatus();
+            return res;
+        })),
+        addPlayer: (save) => runInSession(ctx, async () => {
+            // REJOIN IS NOT A JOIN (playtest 2026-08-27, Sherry: "got an
+            // internal server error"). A dropped DDP connection -- a
+            // laptop lid, a wifi blip, a client restart -- calls
+            // sideQuest.join again with the same runner, and this used to
+            // walk straight into Scene.addActor, which throws "Actor with
+            // name X already exists in the scene." The method died, the
+            // player saw a raw 500, and their seat was unreachable for
+            // the rest of the run even though the engine still held a
+            // perfectly good actor for them.
+            //
+            // The right answer is to hand the existing actor back: their
+            // position, inventory, wounds and watchers are all still live
+            // on the table. Re-push status and the overlays so the
+            // reconnecting client repaints from the server's truth, and
+            // deliberately DON'T re-narrate the taxi -- they never left,
+            // and the table shouldn't be told they arrived twice.
+            const existing = game.scene.getPlayers().find(x => x.name === save.playerName);
+            if (existing) {
+                logger.write(`addPlayer: ${existing.name} is already seated -- treating as a RECONNECT, not a join.`);
+                logger.status(existing.name, game.statusLinesFor(existing));
                 pushMap();
-                // THE WEB MAP FOLLOWS THE ROOM, NOT JUST YOUR OWN BODY
-                // (oHhjxjqKuptDGMHLD: a looted body stayed on the map "until I
-                // move"; 9aEMA4APbB6rYtWnT: a killed NPC's dot never changed).
-                // The condition beat is what the browser draws actors from. A
-                // kill or a loot mutates the room, not the killer, so this
-                // nudge -- one per command, coalesced -- still covers those.
-                // MOVEMENT NO LONGER WAITS FOR IT (q6tBaFn5EDmGMoJFh): the room
-                // publishes every occupant's position change to the humans in
-                // it the moment it happens (Room.noteOccupancyChanged), so an
-                // NPC stepping on its own reflect chain between commands
-                // reaches the browser without anyone typing.
-                game.player.noteConditionChanged();
-                // EVERY OTHER HUMAN WHO SAW THE ROOM CHANGE (genfBamjTvyHTdWhu):
-                // a member's overlay is written from the member's OWN beat now
-                // (Game.wireConditionReporting), so the same once-per-command
-                // nudge covers the typist and whoever shares their room -- a
-                // kill or a loot changes the room for all of them.
-                const typist = game.scene.getPlayerByName(actorName);
-                for (const p of game.scene.getPlayers()) {
-                    if (p === game.player || game.scene.deadPlayers.has(p.name))
-                        continue;
-                    if (p === typist || (typist && p.currentLocation === typist.currentLocation))
-                        p.noteConditionChanged();
-                }
-                return res;
-            })),
-            addPlayer: (save) => runInSession(ctx, async () => {
-                // REJOIN IS NOT A JOIN (playtest 2026-08-27, Sherry: "got an
-                // internal server error"). A dropped DDP connection -- a
-                // laptop lid, a wifi blip, a client restart -- calls
-                // sideQuest.join again with the same runner, and this used to
-                // walk straight into Scene.addActor, which throws "Actor with
-                // name X already exists in the scene." The method died, the
-                // player saw a raw 500, and their seat was unreachable for
-                // the rest of the run even though the engine still held a
-                // perfectly good actor for them.
-                //
-                // The right answer is to hand the existing actor back: their
-                // position, inventory, wounds and watchers are all still live
-                // on the table. Re-push status and the overlays so the
-                // reconnecting client repaints from the server's truth, and
-                // deliberately DON'T re-narrate the taxi -- they never left,
-                // and the table shouldn't be told they arrived twice.
-                const existing = game.scene.getPlayers().find(x => x.name === save.playerName);
-                if (existing) {
-                    logger.write(`addPlayer: ${existing.name} is already seated -- treating as a RECONNECT, not a join.`);
-                    logger.status(existing.name, game.statusLinesFor(existing));
-                    pushMap();
-                    // The browser's Room box reads the overlay, not the room
-                    // event: one fresh beat so a reconnecting member repaints
-                    // their own map too (genfBamjTvyHTdWhu).
-                    existing.noteConditionChanged();
-                    return existing.name;
-                }
-                const p = buildPlayerFromSave(save);
-                // A MEMBER'S OWN LIVE-SHEET LANE (genfBamjTvyHTdWhu: "in a
-                // shared run, I'm not the leader. I have no room map"). The
-                // hook the constructor installs on the primary, installed on
-                // the joiner too: their beats reach the sink under their own
-                // name and the host writes them to THEIR overlay. Wired before
-                // the spawn so the seating below is the first beat.
-                game.wireConditionReporting(p);
-                const room = spawnRoom();
-                game.scene.addPlayer(p, room);
-                // ROOM GRIDS (spatial wave 2026-08-25, included shared-run
-                // fix): a late joiner used to land CIRCULATING in a spotted
-                // start room -- entrySpotFor gives them a real position
-                // (the doorway spot, same as a solo "go" arrival), set AFTER
-                // addPlayer sets currentLocation (the setter clears atSpot).
-                const spot = entrySpotFor(room, undefined);
-                if (spot)
-                    p.atSpot = spot;
-                loadContract(save);
-                p.noteConditionChanged();
-                logger.system(`${p.name} steps out of a taxi and into the job.`, 'all', 'joined', { player: p.name });
+                // The browser's Room box reads the overlay, not the room
+                // event: one fresh beat so a reconnecting member repaints
+                // their own map too (genfBamjTvyHTdWhu).
+                existing.noteConditionChanged();
+                return existing.name;
+            }
+            const p = buildPlayerFromSave(save);
+            // A MEMBER'S OWN LIVE-SHEET LANE (genfBamjTvyHTdWhu: "in a
+            // shared run, I'm not the leader. I have no room map"). The
+            // hook the constructor installs on the primary, installed on
+            // the joiner too: their beats reach the sink under their own
+            // name and the host writes them to THEIR overlay. Wired before
+            // the spawn so the seating below is the first beat.
+            game.wireConditionReporting(p);
+            const room = spawnRoom();
+            game.scene.addPlayer(p, room);
+            // ROOM GRIDS (spatial wave 2026-08-25, included shared-run
+            // fix): a late joiner used to land CIRCULATING in a spotted
+            // start room -- entrySpotFor gives them a real position
+            // (the doorway spot, same as a solo "go" arrival), set AFTER
+            // addPlayer sets currentLocation (the setter clears atSpot).
+            const spot = entrySpotFor(room, undefined);
+            if (spot)
+                p.atSpot = spot;
+            loadContract(game, save);
+            p.noteConditionChanged();
+            logger.system(`${p.name} steps out of a taxi and into the job.`, 'all', 'joined', { player: p.name });
+            logger.status(p.name, game.statusLinesFor(p));
+            pushMap();
+            return p.name;
+        }),
+        pushStatus: () => {
+            for (const p of game.scene.getPlayers()) {
+                if (game.scene.deadPlayers.has(p.name))
+                    continue;
                 logger.status(p.name, game.statusLinesFor(p));
-                pushMap();
-                return p.name;
-            }),
-            pushStatus: () => {
-                for (const p of game.scene.getPlayers()) {
-                    if (game.scene.deadPlayers.has(p.name))
-                        continue;
-                    logger.status(p.name, game.statusLinesFor(p));
-                }
-            },
-            snapshotPlayers: () => {
-                const out = {};
-                for (const p of game.scene.getPlayers()) {
-                    if (game.scene.deadPlayers.has(p.name))
-                        continue;
-                    out[p.name] = serializePlayer(p);
-                }
-                return out;
-            },
-            docwagonFor: (actorName) => game.docwagonByPlayer.get(actorName),
-            dispose: () => runInSession(ctx, () => game.dispose()),
-        };
-        // THE FIRST PAINT (B7NNNesy5gvRSbZpp: "I was only moved to the
-        // shared run AFTER Jinx joined the shared run -- could be a refresh
-        // issue"). The reporter's guess was right.
-        //
-        // Nothing pushed at boot. Status and the overlays went out only from
-        // `command` and from `addPlayer` -- and addPlayer's pushMap loops the
-        // WHOLE TABLE, which is the whole illusion: a leader who started a
-        // run sat looking at their hub panels, with the session already live
-        // underneath, until somebody else's join repainted everyone. The
-        // second player's arrival appeared to move the FIRST player into the
-        // run.
-        //
-        // A leader alone at the table would have waited until they typed
-        // something, since their own next command pushes too. Which is why
-        // this reads as "Jinx joined and then I moved" rather than as a
-        // missing initial render.
-        //
-        // SAFE TO EMIT BEFORE THE CLIENT SUBSCRIBES, and that is the fact
-        // this fix rests on rather than an assumption: the leader subscribes
-        // AFTER `sideQuest.start` returns (SharedRunSession.startAsLeader),
-        // so these events are inserted before anyone is listening. The
-        // subscription is `sideQuest.events` from seq 0 and replays, which
-        // is what route()'s seq-dedupe exists to absorb -- so a late
-        // subscriber still receives them.
+            }
+        },
+        snapshotPlayers: () => {
+            const out = {};
+            for (const p of game.scene.getPlayers()) {
+                if (game.scene.deadPlayers.has(p.name))
+                    continue;
+                out[p.name] = serializePlayer(p);
+            }
+            return out;
+        },
+        docwagonFor: (actorName) => game.docwagonByPlayer.get(actorName),
+        dispose: () => runInSession(ctx, () => game.dispose()),
+    };
+    // THE FIRST PAINT (B7NNNesy5gvRSbZpp: "I was only moved to the
+    // shared run AFTER Jinx joined the shared run -- could be a refresh
+    // issue"). The reporter's guess was right.
+    //
+    // Nothing pushed at boot. Status and the overlays went out only from
+    // `command` and from `addPlayer` -- and addPlayer's pushMap loops the
+    // WHOLE TABLE, which is the whole illusion: a leader who started a
+    // run sat looking at their hub panels, with the session already live
+    // underneath, until somebody else's join repainted everyone. The
+    // second player's arrival appeared to move the FIRST player into the
+    // run.
+    //
+    // A leader alone at the table would have waited until they typed
+    // something, since their own next command pushes too. Which is why
+    // this reads as "Jinx joined and then I moved" rather than as a
+    // missing initial render.
+    //
+    // SAFE TO EMIT BEFORE THE CLIENT SUBSCRIBES, and that is the fact
+    // this fix rests on rather than an assumption: the leader subscribes
+    // AFTER `sideQuest.start` returns (SharedRunSession.startAsLeader),
+    // so these events are inserted before anyone is listening. The
+    // subscription is `sideQuest.events` from seq 0 and replays, which
+    // is what route()'s seq-dedupe exists to absorb -- so a late
+    // subscriber still receives them.
+    session.pushStatus();
+    pushMap();
+    // THE SCENE CAN MOVE WITHOUT ANYONE TYPING.
+    //
+    // Everything above pushes from three places and three only:
+    // `command`, `addPlayer`, and this boot. Game's own way of saying
+    // "the world changed, repaint" is repaintForScene -- and out here
+    // that is INERT, because `_mapBox` is undefined on a server. Not
+    // assumed: a real headless boot emits map/room/status 1,1,1, calling
+    // updateExits + updateStatus by hand leaves it at 1,1,1, and one
+    // `command` takes it to 2,2,2.
+    //
+    // So a scene swap that happens OUTSIDE a command moves the table's
+    // truth and sends nothing after it. draftNextSceneInBackground is
+    // that shape by design -- `void continueToNextScene()`, 20-40
+    // seconds, resolving long after the command that started it already
+    // pushed the OLD scene.
+    //
+    // Installed AFTER `session` exists, deliberately: repaintForScene
+    // runs during the boot synthesis above, and a hook wired earlier
+    // would reach for a `session` that is not there yet.
+    //
+    // Double-pushing on a swap inside a command is accepted and cheap:
+    // the client coalesces its repaints (Game.scheduleRender) and
+    // route()'s seq dedupe is indifferent. Missing the swap entirely is
+    // the failure worth spending frames on.
+    //
+    // HARDENING. The inert joint is measured; a swap arriving outside a
+    // command is read in the source and NOT executed here
+    // (continueToNextScene is gated on job completion, so the harness
+    // cannot drive one end to end). This is not offered as the cause of
+    // any live report.
+    game.onSceneChanged = () => {
         session.pushStatus();
         pushMap();
-        // THE SCENE CAN MOVE WITHOUT ANYONE TYPING.
-        //
-        // Everything above pushes from three places and three only:
-        // `command`, `addPlayer`, and this boot. Game's own way of saying
-        // "the world changed, repaint" is repaintForScene -- and out here
-        // that is INERT, because `_mapBox` is undefined on a server. Not
-        // assumed: a real headless boot emits map/room/status 1,1,1, calling
-        // updateExits + updateStatus by hand leaves it at 1,1,1, and one
-        // `command` takes it to 2,2,2.
-        //
-        // So a scene swap that happens OUTSIDE a command moves the table's
-        // truth and sends nothing after it. draftNextSceneInBackground is
-        // that shape by design -- `void continueToNextScene()`, 20-40
-        // seconds, resolving long after the command that started it already
-        // pushed the OLD scene.
-        //
-        // Installed AFTER `session` exists, deliberately: repaintForScene
-        // runs during the boot synthesis above, and a hook wired earlier
-        // would reach for a `session` that is not there yet.
-        //
-        // Double-pushing on a swap inside a command is accepted and cheap:
-        // the client coalesces its repaints (Game.scheduleRender) and
-        // route()'s seq dedupe is indifferent. Missing the swap entirely is
-        // the failure worth spending frames on.
-        //
-        // HARDENING. The inert joint is measured; a swap arriving outside a
-        // command is read in the source and NOT executed here
-        // (continueToNextScene is gated on job completion, so the harness
-        // cannot drive one end to end). This is not offered as the cause of
-        // any live report.
-        game.onSceneChanged = () => {
-            session.pushStatus();
-            pushMap();
-            game.player.noteConditionChanged();
+        game.player.noteConditionChanged();
+    };
+    return session;
+}
+/**
+ * A HUB HOSTED ON maka-cli.com (2026-09-12, mjmcee: "allow dropping into
+ * the hub from the browser"). The CLI's solo hub loop -- hideout, shops,
+ * contacts, call Krow, ride to the job and home again -- booted from a
+ * GameSaves doc over the served hub seed, in the site's own process.
+ * Solo by ruling: one runner, one hub instance, their overlay over the
+ * shared seed. See IMainGameConfig.hostedHub for what the flag turns off
+ * (presence, the DDP hub link, the entry-time draft) and where saves go.
+ *
+ * The boot is ui.ts's resume path, not buildPlayerFromSave: a bare
+ * Player from the save's attribute block, and Game.applyResumeState
+ * lays gear, augs, qualities, the hub overlay and the home block over
+ * the fresh synthesis -- exactly as a terminal continues a runner.
+ */
+export async function createHeadlessHub(opts) {
+    const logger = new EmitterLogger(opts.sink, opts.debug);
+    const ctx = { sessionId: opts.sessionId, logger, client: opts.client };
+    return runInSession(ctx, async () => {
+        const save = opts.save;
+        const nexus = new Room({ name: 'Nexus', description: 'A featureless room where lost souls drift.', roomType: 'void' });
+        const a = save.player.attributes;
+        const player = new Player({
+            playerName: save.playerName,
+            startLocation: nexus,
+            combat: { ...a, skills: save.player.skills },
+        });
+        player.archetypeName = save.player.archetypeName;
+        const game = Game.forHostedHub(player, opts.hubSeed, save, opts.conditionSink);
+        logger.bindGame(() => game);
+        wireDeathHooks(game, logger, opts);
+        await game.initEngine({
+            logFilePath: '',
+            useAi: opts.useAi ?? false,
+            hostedHub: true,
+            saveSink: opts.onSave,
+            owner: save.owner,
+            resume: true,
+        });
+        const base = wireHeadless(game, ctx, logger);
+        return {
+            ...base,
+            save: (reason) => game.snapshotSave(reason),
+            flush: (reason) => runInSession(ctx, () => game.flushBoundSave(reason)),
+            inRun: () => !game.onHubScene,
         };
-        return session;
     });
 }
 //# sourceMappingURL=headless.js.map