@maka/maka-cli 5.84.0 → 5.85.0

package/bundle/typescript/src/commands/game/sideQuest/utilities/ephemeral.d.ts

@@ -0,0 +1,116 @@
+import { NPC } from '../models/npc.js';
+import { Room } from '../models/room.js';
+import type { Scene } from '../models/scene.js';
+/**
+ * THE EPHEMERAL NPC GOVERNOR (7ALf6u7PvTg6TZSm7, Maka: "an ephemeral NPC
+ * AI governer. This would handle non-scene generated NPCs, like
+ * authority checking SINs, hostile mobs, neutral npcs that don't impact
+ * the storyline/job").
+ *
+ * THE SPINE OF THE DESIGN: an ephemeral VOICES a result the engine has
+ * already computed. It never decides anything. The SIN sweep's officer
+ * is a mouth for mechanics that already work -- wandRead returns the
+ * band, addHeat bills it, the fake burns -- so the worst a bad brief can
+ * do is produce bad dialogue, never a wrong ruling. Every later kind
+ * (mobs, bystanders) rides these same rails, and the rails are the
+ * reason this is safe to grow.
+ *
+ * THE EPHEMERAL / CHARACTER BOUNDARY, stated as law:
+ *   - an ephemeral is NOT IN THE PLOT -- no run, client, objective or
+ *     payout reaches its brief;
+ *   - an ephemeral CANNOT CREATE OBLIGATIONS -- no prices, no jobs, no
+ *     items, no promises the world would have to honor later.
+ * A patrolman who starts discussing your Johnson has become a
+ * character, and characters have to persist. These two denials are what
+ * keep an ephemeral disposable; without them the first interesting
+ * conversation mints a debt the save file cannot pay.
+ *
+ * ONE GOVERNOR. Spawning, despawning and the brief trim all live here,
+ * and nothing else in the engine mints an ephemeral. A second spawn
+ * site is how a "temporary" NPC ends up outliving the scene.
+ *
+ * NO SAVE PERSISTENCE -- ephemeral means ephemeral (ruling). The
+ * mid-fight-save worry is already answered by the engine rather than by
+ * anything here: requestSave's guards only write at safe beats, and a
+ * mob fight is not one, so a load can neither resurrect a dead officer
+ * nor vanish one mid-swing. See despawn() below, which is where that
+ * reasoning has to be true.
+ */
+/**
+ * How long this body is allowed to exist. ALWAYS EXPLICIT -- an implicit
+ * lifetime is how the "temporary" patrolman is still standing there
+ * three rooms later.
+ *
+ *  'exchange' -- for as long as the player is talking to them. A
+ *                mid-exchange walkout ends the exchange; the officer
+ *                does not follow through the save file.
+ *  'room'     -- while the player is in this room.
+ *  'fight'    -- while the fight lasts. Mob despawn is FIGHT-scoped, not
+ *                room-scoped, on purpose: walking out of the room is a
+ *                thing you do DURING a fight, and a mob that evaporated
+ *                because you backed through a doorway would be a
+ *                retreat that wins by itself.
+ */
+export type EphemeralScope = 'exchange' | 'room' | 'fight';
+export type EphemeralKind = 'authority' | 'mob' | 'bystander';
+export interface IEphemeralMark {
+    kind: EphemeralKind;
+    until: EphemeralScope;
+    /** The room they were spawned into -- what 'room' scope is measured against. */
+    roomName: string;
+}
+/** Every ephemeral currently standing, by NPC name. */
+export type EphemeralRegistry = Map<string, IEphemeralMark>;
+/** What the governor needs of the Game, kept narrow so this is testable. */
+export interface IEphemeralHost {
+    scene: Scene;
+    ephemerals: EphemeralRegistry;
+}
+/**
+ * Bring one into the world. Returns the NPC, or null when the name is
+ * already taken -- the same refusal spawnCompanionShell makes, and for
+ * the same reason: two actors answering to one name is a bug nobody can
+ * see until a command picks the wrong one.
+ */
+export declare function spawnEphemeral(host: IEphemeralHost, opts: {
+    name: string;
+    description: string;
+    kind: EphemeralKind;
+    until: EphemeralScope;
+    room: Room;
+    combat: Partial<import('../models/player.js').ICombatAttributes>;
+}): NPC | null;
+/**
+ * Remove every ephemeral whose scope has ended.
+ *
+ * WHY NO SAVE HOOK IS NEEDED HERE, which is the ruling's reasoning and
+ * has to be true at exactly this line: ephemerals are never written to
+ * the save file, so there is nothing to reconcile on load. The obvious
+ * worry -- a save landing mid-fight, resurrecting a dead mob or erasing
+ * a live one -- is already answered upstream: requestSave's guards only
+ * write at safe beats and a fight is not one. So a load never sees a
+ * half-finished ephemeral, and this function is the only thing that
+ * ever ends one.
+ *
+ * Returns the names removed, so a caller can say so once.
+ */
+export declare function despawnEphemerals(host: IEphemeralHost, opts: {
+    /** Where the player is NOW -- 'room'/'exchange' scopes end elsewhere. */
+    playerRoomName?: string;
+    /** True while a fight is running; 'fight'-scoped bodies stay up. */
+    fightActive?: boolean;
+    /** Ends everything regardless of scope (scene teardown). */
+    all?: boolean;
+}): string[];
+/**
+ * The two denials that make an ephemeral disposable, as prompt text.
+ *
+ * FULL LENGTH, DELIBERATELY. Everything else in an ephemeral's brief is
+ * trimmed hard -- no command help, no objective, no payout, no client,
+ * no wares, no history -- but the honesty pins are not where the budget
+ * gets saved. They are the majority of what remains precisely because
+ * the rest went, and trimming a denial is the exact economy that
+ * reintroduces the bug the denial exists to prevent. A shorter pin does
+ * not produce a shorter answer; it produces a confident wrong one.
+ */
+export declare function ephemeralDenials(role: string): string;

package/bundle/typescript/src/commands/game/sideQuest/utilities/ephemeral.js

@@ -0,0 +1,96 @@
+import { NPC } from '../models/npc.js';
+import { Logger } from './logger.js';
+import { CommandRegistry } from '../commands/command-registry.js';
+/**
+ * Bring one into the world. Returns the NPC, or null when the name is
+ * already taken -- the same refusal spawnCompanionShell makes, and for
+ * the same reason: two actors answering to one name is a bug nobody can
+ * see until a command picks the wrong one.
+ */
+export function spawnEphemeral(host, opts) {
+    if (host.scene.getActor(opts.name)) {
+        Logger.getInstance().write(`spawnEphemeral: name "${opts.name}" already in scene -- refusing.`);
+        return null;
+    }
+    const npc = new NPC({
+        dialog: [],
+        description: opts.description,
+        playerConstructorConfig: { playerName: opts.name, startLocation: opts.room, combat: opts.combat },
+    }, new CommandRegistry(host.scene));
+    npc.plane = 'meat';
+    // NOT allyOf, and NOT companionKind: an ephemeral belongs to nobody
+    // and is on no roster. Those two fields are what make a companion
+    // persist, follow, and take orders.
+    npc.ephemeral = { kind: opts.kind, until: opts.until, roomName: opts.room.name };
+    host.scene.addActor(npc);
+    host.scene.setCharacterLocation(npc, opts.room.name);
+    npc.scene = host.scene;
+    host.ephemerals.set(opts.name, npc.ephemeral);
+    Logger.getInstance().write(`Ephemeral spawned: ${opts.name} (${opts.kind}, until ${opts.until}) in ${opts.room.name}.`);
+    return npc;
+}
+/**
+ * Remove every ephemeral whose scope has ended.
+ *
+ * WHY NO SAVE HOOK IS NEEDED HERE, which is the ruling's reasoning and
+ * has to be true at exactly this line: ephemerals are never written to
+ * the save file, so there is nothing to reconcile on load. The obvious
+ * worry -- a save landing mid-fight, resurrecting a dead mob or erasing
+ * a live one -- is already answered upstream: requestSave's guards only
+ * write at safe beats and a fight is not one. So a load never sees a
+ * half-finished ephemeral, and this function is the only thing that
+ * ever ends one.
+ *
+ * Returns the names removed, so a caller can say so once.
+ */
+export function despawnEphemerals(host, opts) {
+    const removed = [];
+    for (const [name, mark] of [...host.ephemerals]) {
+        const ended = opts.all
+            ? true
+            : mark.until === 'fight'
+                ? opts.fightActive === false
+                // exchange- and room-scoped bodies both end when the player
+                // leaves: a walkout IS the end of the conversation.
+                : opts.playerRoomName !== undefined && opts.playerRoomName !== mark.roomName;
+        if (!ended)
+            continue;
+        if (host.scene.getActor(name) instanceof NPC)
+            host.scene.removeActor(name);
+        host.ephemerals.delete(name);
+        removed.push(name);
+    }
+    if (removed.length > 0) {
+        Logger.getInstance().write(`Ephemerals despawned: ${removed.join(', ')}.`);
+    }
+    return removed;
+}
+/**
+ * The two denials that make an ephemeral disposable, as prompt text.
+ *
+ * FULL LENGTH, DELIBERATELY. Everything else in an ephemeral's brief is
+ * trimmed hard -- no command help, no objective, no payout, no client,
+ * no wares, no history -- but the honesty pins are not where the budget
+ * gets saved. They are the majority of what remains precisely because
+ * the rest went, and trimming a denial is the exact economy that
+ * reintroduces the bug the denial exists to prevent. A shorter pin does
+ * not produce a shorter answer; it produces a confident wrong one.
+ */
+export function ephemeralDenials(role) {
+    return `
+YOU ARE A PASSING FACE, NOT A CHARACTER IN ANYONE'S STORY. You are ${role} -- here for
+this moment and no longer. You know nothing about any job, run, client, employer,
+objective, payout, or what these people are doing in this district beyond what is
+happening in front of you right now. You have no opinion about their business because you
+do not know they have any. If someone raises a job, a Johnson, a target, or a score, you
+have no idea what they are talking about and no curiosity about it -- that is somebody
+else's world and you are not in it.
+
+YOU CANNOT PROMISE, SELL, HIRE, OR HAND OVER ANYTHING. You quote no prices, offer no work,
+carry no goods to trade, and make no arrangements for later -- no favors owed, no "come
+find me", no meeting tomorrow. You will not be here tomorrow. Anything you agreed to would
+be an obligation nobody in the world can honor, and the person who trusted it would be
+worse off for having met you. If pressed for any of it, say plainly that it is not yours
+to give and point them at whoever actually handles such things.`;
+}
+//# sourceMappingURL=ephemeral.js.map

package/bundle/typescript/src/commands/game/sideQuest/utilities/ephemeral.js.map

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

package/bundle/typescript/src/commands/game/sideQuest/utilities/meet-location.d.ts

@@ -0,0 +1,37 @@
+import type { ISceneSeedJson } from '../types/seed/scene-seed.js';
+/**
+ * WHERE THE MEET ACTUALLY IS, read off the drafted seed.
+ *
+ * Item g5CgJgmw9ix6AcD78: "Krow said to meet at Mama Wu's, that
+ * shouldn't happen." There is no Mama Wu's. The fixer's pitch is
+ * AI-generated free text, and the brief told him the client "will hold
+ * the meet on-site" without telling him WHERE -- so a model writing a
+ * fixer's voice did the natural thing and invented a venue. The player
+ * then travelled to a scene that contains no such place.
+ *
+ * This is the codebase's signature defect: a NAME REFERRING TO NOTHING.
+ * The house cure is to resolve names against the real roster or room
+ * list and repair or reject, never to ship an unresolved one (see
+ * scene-chunks.ts resolveNamedRef). The same cure applies here, and it
+ * is better than a prohibition: the seed already KNOWS the answer, so
+ * the fixer can be told the truth rather than merely forbidden a lie.
+ * A brief that only says "don't invent one" leaves him with nothing to
+ * say and invites a vaguer dodge.
+ *
+ * THE MEET IS WHERE THE CLIENT STANDS, not the start room -- generation
+ * places the client "in a REACHABLE room that makes a characterful meet
+ * spot" (scene-chunks.ts), which is frequently not where the runner
+ * arrives. Falling back to the start room is still TRUE (it is where
+ * they land, and the client is always reachable from it), so the
+ * fallback degrades to vaguer rather than to wrong.
+ *
+ * IT LIVES HERE, not in call.ts, because ONE ANSWER IS THE WHOLE POINT.
+ * The reported bug is two sources disagreeing about where the meet is
+ * (the vetting on the item: "Krow directing the player to Mama Wu's,
+ * then a conflicting message from Mr. Vane at a different location"), so
+ * a resolver that only one of the speakers consults cannot fix it. Every
+ * surface that tells the player or an NPC where the meet is reads this
+ * function; if you are about to write the words "the meet" and a place
+ * name, call this instead.
+ */
+export declare function meetLocationFor(seed: ISceneSeedJson | undefined): string | undefined;

package/bundle/typescript/src/commands/game/sideQuest/utilities/meet-location.js

@@ -0,0 +1,51 @@
+/**
+ * WHERE THE MEET ACTUALLY IS, read off the drafted seed.
+ *
+ * Item g5CgJgmw9ix6AcD78: "Krow said to meet at Mama Wu's, that
+ * shouldn't happen." There is no Mama Wu's. The fixer's pitch is
+ * AI-generated free text, and the brief told him the client "will hold
+ * the meet on-site" without telling him WHERE -- so a model writing a
+ * fixer's voice did the natural thing and invented a venue. The player
+ * then travelled to a scene that contains no such place.
+ *
+ * This is the codebase's signature defect: a NAME REFERRING TO NOTHING.
+ * The house cure is to resolve names against the real roster or room
+ * list and repair or reject, never to ship an unresolved one (see
+ * scene-chunks.ts resolveNamedRef). The same cure applies here, and it
+ * is better than a prohibition: the seed already KNOWS the answer, so
+ * the fixer can be told the truth rather than merely forbidden a lie.
+ * A brief that only says "don't invent one" leaves him with nothing to
+ * say and invites a vaguer dodge.
+ *
+ * THE MEET IS WHERE THE CLIENT STANDS, not the start room -- generation
+ * places the client "in a REACHABLE room that makes a characterful meet
+ * spot" (scene-chunks.ts), which is frequently not where the runner
+ * arrives. Falling back to the start room is still TRUE (it is where
+ * they land, and the client is always reachable from it), so the
+ * fallback degrades to vaguer rather than to wrong.
+ *
+ * IT LIVES HERE, not in call.ts, because ONE ANSWER IS THE WHOLE POINT.
+ * The reported bug is two sources disagreeing about where the meet is
+ * (the vetting on the item: "Krow directing the player to Mama Wu's,
+ * then a conflicting message from Mr. Vane at a different location"), so
+ * a resolver that only one of the speakers consults cannot fix it. Every
+ * surface that tells the player or an NPC where the meet is reads this
+ * function; if you are about to write the words "the meet" and a place
+ * name, call this instead.
+ */
+export function meetLocationFor(seed) {
+    if (!seed)
+        return undefined;
+    const client = seed.client
+        ? seed.npcs?.find(n => n.player?.name === seed.client)
+        : undefined;
+    const clientRoom = client?.player?.startLocation;
+    // Only trust a room the scene really declares -- a startLocation that
+    // names no room is the same unresolved-name bug one level down, and
+    // repeating it into the fixer's mouth would be worse than silence.
+    const rooms = seed.rooms ?? [];
+    if (clientRoom && rooms.some(r => r.name === clientRoom))
+        return clientRoom;
+    return rooms.find(r => r.isStartRoom)?.name;
+}
+//# sourceMappingURL=meet-location.js.map

package/bundle/typescript/src/commands/game/sideQuest/utilities/meet-location.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meet-location.js","sourceRoot":"","sources":["../../../../../../../src/commands/game/sideQuest/utilities/meet-location.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,eAAe,CAAC,IAAgC;IAC9D,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM;QACxB,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,KAAK,IAAI,CAAC,MAAM,CAAC;QACtD,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,UAAU,GAAG,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC;IACjD,sEAAsE;IACtE,oEAAoE;IACpE,mEAAmE;IACnE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;IAC/B,IAAI,UAAU,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC;QAAE,OAAO,UAAU,CAAC;IAC5E,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC;AAC9C,CAAC"}

package/bundle/typescript/src/commands/game/sideQuest/utilities/perception.d.ts

@@ -0,0 +1,76 @@
+import type { Player } from '../models/player.js';
+/**
+ * THE PERCEPTION TEST (SR5 core p.135-136), shared by every verb that
+ * makes one.
+ *
+ * Item FNgptvRhbA5yMunbB, the player writing the spec in two sentences:
+ * '"look" should reveal items that are under a perception threshold.
+ * "search" is an active perception check'.
+ *
+ * The SPLIT they asked for already shipped (52ba4dda): `look` lists
+ * plain-sight goods with no test at all, which is p.135's own
+ * instruction -- characters "should always be able to observe what is
+ * immediately obvious without spending an action or making a test" --
+ * while `search` rolls. What had NOT shipped is the mechanical
+ * difference between the two rolls, and canon is specific about what it
+ * is:
+ *
+ *   "Perceiver is specifically looking/listening for it  +3"
+ *                              (p.135-136, Perception Test Modifiers)
+ *
+ * That +3 IS the active/passive distinction. Without it, `search` was an
+ * active perception check in name while rolling the same pool as the
+ * passive glance -- the player's second sentence unimplemented, one
+ * layer below the one that was fixed.
+ *
+ * AND THE BRACKET IS A LIMIT. `Perception + Intuition [Mental]`: neither
+ * verb applied one, so a huge pool could count unlimited hits. Limits
+ * cap HITS, never dice (utilities/dice.ts, and the house rule at the top
+ * of CLAUDE.md).
+ *
+ * ONE FUNCTION, BOTH CALLERS, deliberately. look.ts and search.ts each
+ * built this pool inline and had already drifted apart; that is the same
+ * one-caller drift that let the meet address disagree with itself
+ * (g5CgJgmw9ix6AcD78) and the same duplicated-mechanic shape that let
+ * `use <medkit>` diverge from `heal`. If you are about to roll
+ * Perception, roll it here.
+ */
+/** p.135-136: the modifier for deliberately looking, which is what makes
+ *  an active search mechanically different from a passive glance. */
+export declare const ACTIVELY_LOOKING = 3;
+export interface IPerceptionTest {
+    pool: number;
+    /** The bracket. Undefined only when the actor has no limit to apply --
+     *  see the Matrix note below; rollPool refuses a zero limit loudly. */
+    limit: number | undefined;
+}
+export interface IPerceptionOpts {
+    /** True for a deliberate hunt (`search`), false for a glance (`look`). */
+    active?: boolean;
+    /** Matrix Search only: a loaded Browse program is purpose-built for it. */
+    browse?: number;
+}
+/**
+ * ON THE GRID IT IS A DIFFERENT TEST WITH A DIFFERENT BRACKET. Matrix
+ * Search is Computer + Logic [Data Processing], so the Mental limit does
+ * NOT apply out there -- capping a decker's sweep by their Willpower
+ * would be a fresh deviation dressed as a fix. The engine takes the
+ * best of Perception and Computer so pre-Computer deckers lose nothing
+ * (a standing allowance, older than this function).
+ *
+ * Data Processing reads 0 for an actor with no deck at all; that is a
+ * caller's missing gate rather than a real limit, so it degrades to
+ * unlimited here instead of handing rollPool a zero it would reject.
+ */
+export declare function perceptionTest(actor: Player, opts?: IPerceptionOpts): IPerceptionTest;
+/**
+ * PERCEPTION THRESHOLDS (p.136). Named because the numbers appear in
+ * player-facing text and in cover reads, and a bare 2 or 4 in three
+ * files is how they drift.
+ */
+export declare const PERCEPTION_THRESHOLD: {
+    /** Street sign, pedestrian, conversation, silenced gunfire. */
+    readonly normal: 2;
+    /** Secret door, needle in a haystack, subvocal speech. */
+    readonly hidden: 4;
+};

package/bundle/typescript/src/commands/game/sideQuest/utilities/perception.js

@@ -0,0 +1,84 @@
+import { mentalLimit } from './limits.js';
+/**
+ * THE PERCEPTION TEST (SR5 core p.135-136), shared by every verb that
+ * makes one.
+ *
+ * Item FNgptvRhbA5yMunbB, the player writing the spec in two sentences:
+ * '"look" should reveal items that are under a perception threshold.
+ * "search" is an active perception check'.
+ *
+ * The SPLIT they asked for already shipped (52ba4dda): `look` lists
+ * plain-sight goods with no test at all, which is p.135's own
+ * instruction -- characters "should always be able to observe what is
+ * immediately obvious without spending an action or making a test" --
+ * while `search` rolls. What had NOT shipped is the mechanical
+ * difference between the two rolls, and canon is specific about what it
+ * is:
+ *
+ *   "Perceiver is specifically looking/listening for it  +3"
+ *                              (p.135-136, Perception Test Modifiers)
+ *
+ * That +3 IS the active/passive distinction. Without it, `search` was an
+ * active perception check in name while rolling the same pool as the
+ * passive glance -- the player's second sentence unimplemented, one
+ * layer below the one that was fixed.
+ *
+ * AND THE BRACKET IS A LIMIT. `Perception + Intuition [Mental]`: neither
+ * verb applied one, so a huge pool could count unlimited hits. Limits
+ * cap HITS, never dice (utilities/dice.ts, and the house rule at the top
+ * of CLAUDE.md).
+ *
+ * ONE FUNCTION, BOTH CALLERS, deliberately. look.ts and search.ts each
+ * built this pool inline and had already drifted apart; that is the same
+ * one-caller drift that let the meet address disagree with itself
+ * (g5CgJgmw9ix6AcD78) and the same duplicated-mechanic shape that let
+ * `use <medkit>` diverge from `heal`. If you are about to roll
+ * Perception, roll it here.
+ */
+/** p.135-136: the modifier for deliberately looking, which is what makes
+ *  an active search mechanically different from a passive glance. */
+export const ACTIVELY_LOOKING = 3;
+/**
+ * ON THE GRID IT IS A DIFFERENT TEST WITH A DIFFERENT BRACKET. Matrix
+ * Search is Computer + Logic [Data Processing], so the Mental limit does
+ * NOT apply out there -- capping a decker's sweep by their Willpower
+ * would be a fresh deviation dressed as a fix. The engine takes the
+ * best of Perception and Computer so pre-Computer deckers lose nothing
+ * (a standing allowance, older than this function).
+ *
+ * Data Processing reads 0 for an actor with no deck at all; that is a
+ * caller's missing gate rather than a real limit, so it degrades to
+ * unlimited here instead of handing rollPool a zero it would reject.
+ */
+export function perceptionTest(actor, opts = {}) {
+    const onGrid = actor.plane === 'matrix';
+    const skill = onGrid
+        ? Math.max(actor.skillRating('perception'), actor.skillRating('computer'))
+        : actor.skillRating('perception');
+    const attribute = onGrid ? actor.logic : actor.intuition;
+    // Unskilled defaults at -1 (p.130), exactly as both callers already did.
+    const pool = Math.max(1, attribute
+        + (skill > 0 ? skill : -1)
+        + (opts.browse ?? 0)
+        + (opts.active ? ACTIVELY_LOOKING : 0)
+        + actor.augBonus('perception')
+        + actor.woundModifier
+        - actor.sustainingPenalty);
+    const dataProcessing = onGrid ? actor.matrixAttribute('dataProcessing') : 0;
+    const limit = onGrid
+        ? (dataProcessing > 0 ? dataProcessing : undefined)
+        : mentalLimit(actor);
+    return { pool, limit };
+}
+/**
+ * PERCEPTION THRESHOLDS (p.136). Named because the numbers appear in
+ * player-facing text and in cover reads, and a bare 2 or 4 in three
+ * files is how they drift.
+ */
+export const PERCEPTION_THRESHOLD = {
+    /** Street sign, pedestrian, conversation, silenced gunfire. */
+    normal: 2,
+    /** Secret door, needle in a haystack, subvocal speech. */
+    hidden: 4,
+};
+//# sourceMappingURL=perception.js.map

package/bundle/typescript/src/commands/game/sideQuest/utilities/perception.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"perception.js","sourceRoot":"","sources":["../../../../../../../src/commands/game/sideQuest/utilities/perception.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;qEACqE;AACrE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAgBlC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,OAAwB,EAAE;IACtE,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,KAAK,QAAQ,CAAC;IACxC,MAAM,KAAK,GAAG,MAAM;QAClB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,YAAY,CAAC,EAAE,KAAK,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;QAC1E,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC;IAEzD,yEAAyE;IACzE,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS;UAC9B,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;UACxB,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;UAClB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;UACpC,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC;UAC5B,KAAK,CAAC,aAAa;UACnB,KAAK,CAAC,iBAAiB,CAAC,CAAC;IAE7B,MAAM,cAAc,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5E,MAAM,KAAK,GAAG,MAAM;QAClB,CAAC,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC;QACnD,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IAEvB,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,+DAA+D;IAC/D,MAAM,EAAE,CAAC;IACT,0DAA0D;IAC1D,MAAM,EAAE,CAAC;CACD,CAAC"}

package/bundle/typescript/src/commands/game/sideQuest/utilities/shared-run.d.ts

@@ -231,6 +231,18 @@ export declare function tryCreateSharedSession(game: Game, preferredSessionID?:
     declined: string;
     code?: string;
 } | undefined>;
+/** One event off the wire. Exported so tests can drive route() with a
+ *  real frame shape instead of a hand-rolled duplicate that drifts. */
+export interface ISessionEvent {
+    sessionID: string;
+    seq: number;
+    channel: string;
+    visibleTo: 'all' | string[];
+    text: string;
+    actor?: string;
+    kind?: string;
+    data?: Record<string, unknown>;
+}
 /**
  * A live shared run, from this terminal's side: the server's event
  * stream renders into the same blessed panes solo play uses, and every
@@ -238,6 +250,36 @@ export declare function tryCreateSharedSession(game: Game, preferredSessionID?:
  * game.remoteSession -- Game.handleInput delegates here wholesale, so
  * ui.ts needs no new wiring.
  */
+/**
+ * THE HUB'S MAPS ARE NOT THIS RUN'S MAPS.
+ *
+ * On a shared run the panels are painted only by the server's per-player
+ * kind:'map' and kind:'room' events, because Game.updateExits early-
+ * returns on `remoteSession` (the client holds no Room objects out
+ * here). Nothing ever cleared what the HUB had painted, so between
+ * entering the run and the server's first frame the player sat looking
+ * at a map of the bar they had just left -- captioned with its name,
+ * indistinguishable from a live one.
+ *
+ * That is why this arrived as "the maps are not refreshing"
+ * (KXgMCRQePfmsnXLRP, vYk4kcNYgR2CQY5P9) rather than "the run is dead".
+ * The failing session on 2026-08-30T22-12-28 received exactly two frames
+ * and then nothing at all -- no map, no room, nothing, for 59 seconds.
+ * The panels did not go blank and raise the alarm; they kept confidently
+ * displaying the hub, so a table that had received NOTHING looked like a
+ * table whose maps were merely stale.
+ *
+ * Blanking here turns a silent lie into a visible absence. An empty
+ * panel is honest -- it says the server has not painted yet, which is
+ * exactly true. Degrade to vaguer, never to wrong: the same rule
+ * meetLocationFor follows when it returns undefined rather than guess a
+ * venue (g5CgJgmw9ix6AcD78).
+ *
+ * BEFORE subscribe(), deliberately. A link that never opens is precisely
+ * when the stale hub map misleads most, so the blanking must not sit
+ * downstream of a socket that may never come up.
+ */
+export declare function blankRunPanels(game: Game): void;
 export declare class SharedRunSession {
     private game;
     private sessionID;
@@ -256,6 +298,34 @@ export declare class SharedRunSession {
      *  timestamps on different machines -- this is the only thing that
      *  ties their reports to one run. */
     get id(): string;
+    /**
+     * THE HUB'S MAPS ARE NOT THIS RUN'S MAPS.
+     *
+     * On a shared run the panels are painted only by the server's per-player
+     * kind:'map' and kind:'room' events, because Game.updateExits early-
+     * returns on `remoteSession` (the client holds no Room objects out
+     * here). Nothing ever cleared what the HUB had painted, so between
+     * entering the run and the server's first frame the player sat looking
+     * at a map of the bar they had just left -- captioned with its name,
+     * pixel-identical to a live one.
+     *
+     * That is why this arrived as "the maps are not refreshing" rather than
+     * "the run is dead". Tonight's failing session (2026-08-30T22-12-28)
+     * received exactly two frames and then nothing at all: no map, no room,
+     * no anything for 59 seconds. The panels did not go blank and raise the
+     * alarm -- they kept confidently displaying the hub, so a table that had
+     * received NOTHING looked like a table whose maps were merely stale.
+     *
+     * Blanking here converts a silent lie into a visible absence. An empty
+     * panel is honest: it says the server has not painted yet, which is
+     * exactly true. Degrade to vaguer, never to wrong -- the same rule
+     * meetLocationFor follows when it returns undefined rather than guess a
+     * venue (g5CgJgmw9ix6AcD78).
+     *
+     * BEFORE subscribe(), deliberately. If the link never comes up at all,
+     * that is precisely when the stale hub map is most misleading, so the
+     * blanking must not be downstream of a socket that may never open.
+     */
     static startAsLeader(game: Game, sessionID: string): Promise<string>;
     static joinAsMember(game: Game, sessionID: string): Promise<string>;
     private static enter;