@maka/maka-cli 5.8.0 → 5.10.0

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

@@ -3,6 +3,10 @@ import { capitalCase } from 'change-case';
 import { Category } from './types/shared/item-enum.js';
 import { Item } from './models/item.js';
 import { Room } from './models/_index.js';
+import { Door } from './models/door.js';
+import { SAVE_VERSION } from './types/save-file.js';
+import { serializePlayer, restorePlayer, captureHubOverlay, applyHubOverlay, writeSaveAtomic, deleteSave, } from './utilities/persistence.js';
+import { pushSave, burnCloudSaveFor } from './utilities/cloud-saves.js';
 import { isFence, LIFESTYLE_TIERS } from './utilities/commerce.js';
 import { rollPool, formatRoll } from './utilities/dice.js';
 import { Direction } from './types/shared/direction-enum.js';
@@ -33,6 +37,7 @@ import { SilentCommand } from './commands/silent.js';
 import { RestCommand } from './commands/rest.js';
 import { ReloadCommand } from './commands/reload.js';
 import { SubdueCommand } from './commands/subdue.js';
+import { GrappleCommand, ReleaseCommand, StruggleCommand } from './commands/grapple.js';
 import { EdgeCommand } from './commands/edge.js';
 import { SheetCommand } from './commands/sheet.js';
 import { CallCommand } from './commands/call.js';
@@ -59,6 +64,9 @@ import { InitiateCommand } from './commands/initiate.js';
 import { SummonCommand } from './commands/summon.js';
 import { OrderCommand } from './commands/order.js';
 import { DeployCommand, AgentCommand, RecallCommand } from './commands/companions.js';
+import { MoveCommand, RunCommand, SprintCommand } from './commands/move.js';
+import { HintsCommand } from './commands/hints.js';
+import { hint } from './utilities/hints.js';
 import { InstallCommand } from './commands/install.js';
 import { BuyCommand } from './commands/buy.js';
 import { SellCommand } from './commands/sell.js';
@@ -82,6 +90,7 @@ import { SceneSeedGenerator, FIXER_NAME } from './factories/scene-seed-generator
 import { CALL_ICON, CALL_COLOR } from './utilities/comm-style.js';
 import { AI } from '../../../tools/ai/ai.class.js';
 import { BULLET } from './utilities/log-style.js';
+import { spotOf } from './utilities/spots.js';
 export default class Game {
     initialized;
     static instance;
@@ -98,6 +107,10 @@ export default class Game {
     _screen;
     _logBox;
     _metaBox;
+    // Quit confirmation state (see handleInput / initInputBox): armed by
+    // the first quit/exit or ESC, cleared by anything that isn't a yes.
+    _quitArmed = false;
+    _escArmedAt = 0;
     _statusBox;
     _inputBox;
     _useAi = false;
@@ -188,6 +201,13 @@ export default class Game {
     // Drones deployed at travel time re-shell on arrival ("the rotors spin
     // back up at the curb") -- tracked as their items across the swap.
     _pendingRedeploys = [];
+    // ---------------- PERSISTENCE (see utilities/persistence.ts) ----------
+    // Character + hub world survive the process (player rulings): autosave
+    // at safe beats only, one slot per character, PERMADEATH on real death.
+    _saveFilePath; // from options.saveFilePath; unset = never save
+    _dead = false; // set in close(); suppresses any later save
+    _resume; // present when this session continues a save
+    _hubSeed; // the seed embedded into every save
     /**
      * The one correct runtime NPC spawn (mirrors scene-factory's seed
      * path): construct with a scene-bound registry, add to the scene
@@ -414,7 +434,7 @@ export default class Game {
             if (kind === 'gig')
                 c.gigs += 1;
             Logger.getInstance().write(`Contact opened: ${name} (connection ${c.connection}).`);
-            return `${name} knows your name now -- a CONTACT (Connection ${c.connection}, Loyalty 1). ("contacts" for the roster, "ask ${name} about ..." for legwork.)`;
+            return `${name} knows your name now -- a CONTACT (Connection ${c.connection}, Loyalty 1).${hint(` ("contacts" for the roster, "ask ${name} about ..." for legwork.)`)}`;
         }
         if (kind === 'gig') {
             c.gigs += 1;
@@ -428,7 +448,7 @@ export default class Game {
         c.spent += spent;
         if (Math.floor(c.spent / 1000) > thousandsBefore && c.loyalty < 3) {
             c.loyalty += 1;
-            return `${name} has started keeping your usual ready. (Loyalty ${c.loyalty} -- patronage tops out at 3; run their errands to go deeper.)`;
+            return `${name} has started keeping your usual ready.${hint(` (Loyalty ${c.loyalty} -- patronage tops out at 3; run their errands to go deeper.)`)}`;
         }
         return null;
     }
@@ -710,6 +730,12 @@ export default class Game {
         CommandFactory.registerCommand('rest', RestCommand);
         CommandFactory.registerCommand('reload', ReloadCommand);
         CommandFactory.registerCommand('subdue', SubdueCommand);
+        // SUBDUING p.195 (see commands/grapple.ts): restrain without damage.
+        CommandFactory.registerCommand('grapple', GrappleCommand);
+        CommandFactory.registerCommand('restrain', GrappleCommand);
+        CommandFactory.registerCommand('clinch', GrappleCommand);
+        CommandFactory.registerCommand('release', ReleaseCommand);
+        CommandFactory.registerCommand('struggle', StruggleCommand);
         CommandFactory.registerCommand('edge', EdgeCommand);
         CommandFactory.registerCommand('sheet', SheetCommand);
         CommandFactory.registerCommand('stats', SheetCommand);
@@ -747,6 +773,15 @@ export default class Game {
         CommandFactory.registerCommand('submerge', InitiateCommand);
         CommandFactory.registerCommand('summon', SummonCommand);
         CommandFactory.registerCommand('conjure', SummonCommand);
+        // "At" spots (utilities/spots.ts): walk/move/approach are one
+        // crossing; run and sprint are the fast modes (combat semantics in
+        // the spot-move phase).
+        CommandFactory.registerCommand('walk', MoveCommand);
+        CommandFactory.registerCommand('move', MoveCommand);
+        CommandFactory.registerCommand('approach', MoveCommand);
+        CommandFactory.registerCommand('run', RunCommand);
+        CommandFactory.registerCommand('sprint', SprintCommand);
+        CommandFactory.registerCommand('hints', HintsCommand);
         CommandFactory.registerCommand('order', OrderCommand);
         CommandFactory.registerCommand('deploy', DeployCommand);
         CommandFactory.registerCommand('recall', RecallCommand);
@@ -784,6 +819,19 @@ export default class Game {
         if (this._homeRoomExitDirection) {
             this._homeRoom.exits.delete(this._homeRoomExitDirection);
         }
+        // The OTHER half of the previous link: sweep any exit on the anchor
+        // room that already leads home before choosing a direction. Without
+        // this, every homecoming re-ran the search against a room still
+        // holding last time's hideout door and stacked a second one on the
+        // next free direction (a real session's Neon Strip ended up with
+        // "up" AND "down" both reading "To Your Hideout").
+        for (const [dir, ex] of [...jobStartRoom.exits.entries()]) {
+            const leadsHome = ex instanceof Door
+                ? ex.getOtherSide(jobStartRoom) === this._homeRoom
+                : ex === this._homeRoom.name;
+            if (leadsHome)
+                jobStartRoom.exits.delete(dir);
+        }
         const direction = Game.HOME_DIRECTION_PRIORITY.find(d => !jobStartRoom.exits.has(d));
         if (!direction) {
             // Every direction is already spoken for on this job's start room --
@@ -811,6 +859,7 @@ export default class Game {
     async init(options, screen) {
         this._useAi = options.useAi;
         this._logFilePath = options.logFilePath;
+        this._saveFilePath = options.saveFilePath;
         this.initInputBox(screen);
         this.initLogBox(screen);
         this.initMetaBox(screen);
@@ -853,17 +902,36 @@ export default class Game {
         if (this.scene.isHub) {
             this._hubScene = this.scene;
             this._hubName = this.sceneSeed?.name ?? 'home';
+            // Every save embeds this seed -- resume never depends on the
+            // original scene file still existing or matching.
+            this._hubSeed = this.sceneSeed;
             // The street starts talking from minute one.
             this._rumorPool = this.sceneSeed?.rumors ?? [];
             this.advanceRumor();
             // The economy wakes up with it: shelf blueprints for restocking,
             // the first odd job on offer, and the lifestyle's edge perk.
+            // snapshotVendorStock deliberately runs BEFORE any resume overlay:
+            // the restock blueprint is the seed's PRISTINE shelves (config
+            // copies), and restockVendorShelves only refills what the overlay
+            // leaves empty.
             this.snapshotVendorStock();
             this._gigPool = this.sceneSeed?.gigs ?? [];
             this.advanceGig();
             this.player.lifestyleEdgeBonus = this.lifestyle.edgeBonus;
-            // Home turf knows its own (see seedHomeTurfContacts).
+            // Home turf knows its own (see seedHomeTurfContacts). On resume the
+            // saved contacts overwrite these loyalty-1 seeds a few lines down.
             this.seedHomeTurfContacts();
+            // The next run starts cooking the moment you're home (player
+            // request): generation takes 20-40s, and waiting for the player
+            // to CALL first meant "give me a bit" every time. Draft now --
+            // Mr. Johnson's "1 new message" ping lands mid-session, and the
+            // call finds work already waiting. The gate keeps this a no-op
+            // with AI off or a draft/pending seed somehow already in flight.
+            // GATED on resume: a restored pendingRun must not be clobbered by
+            // a fresh background draft landing 20-40s into the session.
+            if (!this._resume && this.canDraftNextScene().allowed) {
+                this.draftNextSceneInBackground();
+            }
         }
         // Gear up automatically: wearables (and the commlink) slot into any
         // EMPTY slots at load -- no "equip all" ritual to start a session
@@ -872,17 +940,133 @@ export default class Game {
         equipIntoEmptySlots(this.player);
         this.warmNpcAppearancesInBackground();
         this.startPursuitHeartbeat();
+        // The banner learns where we are only after the hub/scene bookkeeping
+        // above settles.
+        this.refreshLogLabel();
+        // RESUME (see utilities/persistence.ts): lay the save over the
+        // freshly-synthesized hub -- player sheet/gear, hub world diffs,
+        // and the Game-level ledgers -- AFTER all the fresh-start seeding
+        // above, so the save is authoritative everywhere they overlap.
+        if (this._resume && this._hubScene) {
+            this.applyResumeState(this._resume);
+        }
         this.initialized = true;
+        if (this._resume) {
+            const pendingNote = this._pendingRunSeed
+                ? hint(`\n\n${FIXER_NAME}'s job is still on offer: "${this._pendingRunSeed.name}". "call taxi" when you're ready, or "call ${FIXER_NAME}" to hear it again.`)
+                : '';
+            return `Welcome back, ${this.player.name}. The cot remembers your shape.\n ${this.scene.story}${pendingNote}`;
+        }
         // Nudge the player toward "call" up front -- the fixer convention means
         // the story deliberately doesn't narrate a completed briefing, so
         // without this hint there'd be no in-game indication that "call" is how
         // you actually get your orders.
         const wc = this.scene.getWinCondition();
         const callHint = (wc?.type === 'give' && wc.toNpc)
-            ? `\n\nYour commlink is quiet for now, but ${wc.toNpc} is expecting to hear from you -- try "call ${wc.toNpc}" when you're ready to check in.`
+            ? hint(`\n\nYour commlink is quiet for now, but ${wc.toNpc} is expecting to hear from you -- try "call ${wc.toNpc}" when you're ready to check in.`)
             : '';
         return `Welcome, ${this.player.name}\n ${this.scene.story}${callHint}`;
     }
+    /**
+     * Everything a save restores beyond the seed synthesis: the player,
+     * the hub world overlay, and the Game-level ledgers. Ordering inside
+     * matters less than its POSITION in init(): after seedHomeTurfContacts
+     * and snapshotVendorStock (both deliberately pre-overlay).
+     */
+    applyResumeState(save) {
+        restorePlayer(this.player, save.player);
+        applyHubOverlay(this.scene, save.hub, this.player, this._homeRoom);
+        this.lifestyleTier = save.game.lifestyleTier;
+        this.rentDebt = save.game.rentDebt;
+        this.syncHomeToLifestyle();
+        this.player.lifestyleEdgeBonus = this.lifestyle.edgeBonus;
+        this._tier = save.game.tier;
+        this.contacts = new Map(save.game.contacts);
+        this.fencedCategories = new Set(save.game.fencedCategories);
+        this._rumorIndex = save.game.rumorIndex;
+        this.activeRumor = save.game.activeRumor;
+        this._gigPool = [...save.game.gigPool];
+        this._gigIndex = save.game.gigIndex;
+        this.gigAvailable = save.game.gigAvailable;
+        this.activeGig = save.game.activeGig;
+        if (save.game.pendingRun) {
+            this._pendingRunSeed = save.game.pendingRun.seed;
+            this._pendingRunTier = save.game.pendingRun.tier;
+            this._pendingRide = save.game.pendingRun.ride;
+        }
+        this.player.currentLocation = this._homeRoom;
+        this.updateEquipment(this.player.equipment);
+        this.updateInventory(this.player.inventory, capitalCase(this.scene.getCurrencyType()));
+        this.updateExits(this.player.currentLocation);
+        this.updateStatus();
+        this.refreshLogLabel();
+        Logger.getInstance().write(`Resumed save for ${save.playerName} (saved ${save.savedAt}, reason ${save.reason}).`);
+    }
+    /**
+     * THE single save routine -- every safe beat funnels here. Guards make
+     * it a silent no-op anywhere a save would lie: mid-run (the "runs are
+     * disposable" ruling lives in the scene === _hubScene check), downed
+     * or KO'd, mid-exchange, dead, or before init finishes. Synchronous by
+     * design so the process-exit quit hook can use it; failures log and
+     * never crash a turn.
+     */
+    requestSave(reason) {
+        const logger = Logger.getInstance();
+        if (!this.initialized || this._dead || !this._saveFilePath)
+            return;
+        if (!this.hasHub || this.scene !== this._hubScene || !this._hubSeed)
+            return;
+        if (this.player.isDown() || this.player.isUnconscious())
+            return;
+        if (this.scene.isPlayerExchangeActive())
+            return;
+        try {
+            const save = this.buildSaveFile(reason);
+            writeSaveAtomic(this._saveFilePath, save);
+            logger.write(`Saved (${reason}) -> ${this._saveFilePath}`);
+            // Local-first: the beat is DONE the moment the file lands. The
+            // cloud mirror rides behind, fire-and-forget (see cloud-saves.ts
+            // -- logged-out/offline/expired all degrade to a silent no-op).
+            void pushSave(this._saveFilePath, save);
+        }
+        catch (err) {
+            logger.error(`requestSave(${reason}) failed: ${err}`);
+        }
+    }
+    buildSaveFile(reason) {
+        return {
+            version: SAVE_VERSION,
+            savedAt: new Date().toISOString(),
+            reason,
+            playerName: this.player.name,
+            summary: {
+                archetypeName: this.player.archetypeName,
+                karma: this.player.karma,
+                currency: this.player.currency,
+                lifestyleTier: this.lifestyleTier,
+                hubName: this._hubName,
+            },
+            hubSeed: this._hubSeed,
+            player: serializePlayer(this.player),
+            game: {
+                lifestyleTier: this.lifestyleTier,
+                rentDebt: this.rentDebt,
+                tier: this._tier,
+                contacts: [...this.contacts.entries()],
+                fencedCategories: [...this.fencedCategories],
+                rumorIndex: this._rumorIndex,
+                activeRumor: this.activeRumor,
+                gigPool: [...this._gigPool],
+                gigIndex: this._gigIndex,
+                gigAvailable: this.gigAvailable,
+                activeGig: this.activeGig,
+                pendingRun: this._pendingRunSeed && this._pendingRunTier !== undefined
+                    ? { seed: this._pendingRunSeed, tier: this._pendingRunTier, ride: this._pendingRide }
+                    : undefined,
+            },
+            hub: captureHubOverlay(this._hubScene, this._hubSeed, this.player, this._homeRoom),
+        };
+    }
     /**
      * Synchronous readiness check for continueToNextScene() -- lets callers
      * give instant feedback for the "not ready yet" cases (job not done, no
@@ -1015,10 +1199,10 @@ export default class Game {
                 this.lifestyleTier = LIFESTYLE_TIERS[tierIndex - 1].name;
                 // The downgrade is visible the moment you look around.
                 this.syncHomeToLifestyle();
-                rentLine = `The landlord's drone pings before the door even shuts: ${paid > 0 ? `${paid} paid, ` : ''}${this.rentDebt} nuyen still owed. Your ${tier.name} arrangement lapses -- you're living ${this.lifestyleTier} now. ("pay" the tab, "lifestyle" to climb back.)`;
+                rentLine = `The landlord's drone pings before the door even shuts: ${paid > 0 ? `${paid} paid, ` : ''}${this.rentDebt} nuyen still owed. Your ${tier.name} arrangement lapses -- you're living ${this.lifestyleTier} now.${hint(` ("pay" the tab, "lifestyle" to climb back.)`)}`;
             }
             else {
-                rentLine = `Even the doorway costs something: ${this.rentDebt} nuyen on the tab. ("pay" when you're flush.)`;
+                rentLine = `Even the doorway costs something: ${this.rentDebt} nuyen on the tab.${hint(` ("pay" when you're flush.)`)}`;
             }
         }
         else {
@@ -1041,14 +1225,19 @@ export default class Game {
         this.updateInventory(this.player.inventory, capitalCase(this.scene.getCurrencyType()));
         this.updateExits(this.player.currentLocation);
         this.updateStatus();
+        this.refreshLogLabel();
         Logger.getInstance().write(`Returned to hub "${this._hubName}". Lifestyle ${this.lifestyleTier}: ${paid} paid, ${this.rentDebt} owed. Restocked ${restocked}. Rumor: ${this.activeRumor ?? '(none)'}`);
         // Drones spin back up beside the cot.
         const companionArrivalLines = this.unfoldCompanionsOnArrival();
         const companionBlock = [...companionFoldLines, ...companionArrivalLines];
+        // The homecoming save: everything above (payout, rent, restock,
+        // contacts reset) settled first, so the save reflects the hub as
+        // the player will find it.
+        this.requestSave('homecoming');
         const fateLine = wrappedRun
             ? `The run's wrapped and the street swallows you back up.`
             : `The run's behind you -- unfinished, unpaid, already someone else's problem. The street doesn't ask.`;
-        return `\n=== ${this._hubName.toUpperCase()} ===\n${fateLine} You're home -- your hideout, one door off ${hub.determineStartRoom().name}. Call ${FIXER_NAME} when you're hungry for the next job.\n${rentLine}${comfortLine}${restockLine}${companionBlock.length > 0 ? `\n${companionBlock.join('\n')}` : ''}`;
+        return `\n=== ${this._hubName.toUpperCase()} ===\n${fateLine} You're home -- your hideout, one door off ${hub.determineStartRoom().name}.${hint(` Call ${FIXER_NAME} when you're hungry for the next job.`)}\n${rentLine}${comfortLine}${restockLine}${companionBlock.length > 0 ? `\n${companionBlock.join('\n')}` : ''}`;
     }
     /**
      * The actual drafting work, split out from continueToNextScene() purely
@@ -1093,7 +1282,7 @@ export default class Game {
             this._pendingRunSeed = nextSeed;
             this._pendingRunTier = nextTier;
             this._pendingRide = Game.RIDE_POOL[Math.floor(Math.random() * Game.RIDE_POOL.length)];
-            return `Your link pings -- 1 new message: ${FIXER_NAME}. ("call ${FIXER_NAME}" to hear the job.)`;
+            return `Your link pings -- 1 new message: ${FIXER_NAME}.${hint(` ("call ${FIXER_NAME}" to hear the job.)`)}`;
         }
         // Classic sessions transition immediately, hideout-first, as always.
         return await this.activateRunScene(nextSeed, nextTier, { startInHideout: true });
@@ -1147,8 +1336,11 @@ export default class Game {
         // warming so re-shelled companions get warmed with the cast.
         const arrivalLines = this.unfoldCompanionsOnArrival();
         this.warmNpcAppearancesInBackground();
+        this.refreshLogLabel();
+        // No "=== JOB #n ===" banner on entry (player request) -- the Game
+        // Log window's own title carries the job name now.
         const companionBlock = [...companionLines, ...arrivalLines];
-        return `\n=== JOB #${this._tier}: ${seed.name} ===\n${this.scene.story}${needsLines.length > 0 ? `\n${needsLines.join('\n')}` : ''}${companionBlock.length > 0 ? `\n${companionBlock.join('\n')}` : ''}`;
+        return `\n${this.scene.story}${needsLines.length > 0 ? `\n${needsLines.join('\n')}` : ''}${companionBlock.length > 0 ? `\n${companionBlock.join('\n')}` : ''}`;
     }
     /**
      * The needs check at every job departure (SR5e p.56 / p.172, scaled to
@@ -1171,11 +1363,15 @@ export default class Game {
         p.sleepStreak = slept ? 0 : p.sleepStreak + 1;
         p.refreshEdge(fed && slept);
         if (fed && slept) {
-            lines.push(`Fed and slept -- you head out SHARP. (Edge ${p.edgeRemaining}/${p.edge + p.lifestyleEdgeBonus}.)`);
+            // Good-news status with a rules lesson inside -- hint-gated
+            // (player request); the HUD's edge count carries the number anyway.
+            const note = hint(`Fed and slept -- you head out SHARP. (Edge ${p.edgeRemaining}/${p.edge + p.lifestyleEdgeBonus}.)`);
+            if (note)
+                lines.push(note);
         }
         else {
             const missing = !fed && !slept ? 'meal and no sleep' : !fed ? 'meal' : 'sleep';
-            lines.push(`No ${missing} since the last job -- your edge doesn't come back (${p.edgeRemaining} left). A hot meal and a night in your own bed reset it.`);
+            lines.push(`No ${missing} since the last job -- your edge doesn't come back (${p.edgeRemaining} left).${hint(` A hot meal and a night in your own bed reset it.`)}`);
         }
         // Escalating, resisted, LOCKED fatigue per ignored need.
         const events = [];
@@ -1224,6 +1420,9 @@ export default class Game {
         if (!seed || tier === undefined) {
             return `There's no job waiting. "call ${FIXER_NAME}" to drum one up.`;
         }
+        // The departure save: hub state with the job still on offer -- what
+        // a mid-run quit resumes to (the "runs are disposable" ruling).
+        this.requestSave('job-accept');
         const haggledAtOffer = this.player.haggledThisJob;
         try {
             const banner = await this.activateRunScene(seed, tier, { startInHideout: false });
@@ -1242,6 +1441,21 @@ export default class Game {
         }
     }
     async close() {
+        // PERMADEATH (player ruling): close() is reachable ONLY via
+        // Scene.endGame(), and endGame fires ONLY on real death (combat
+        // resolveDeath, street-decides knockout, drain burnout, ward
+        // backlash, stim crash) -- so this IS the one death choke point.
+        // The save burns with the body; _dead also suppresses the quit
+        // hook's save on the way out. Keep that invariant: any future
+        // non-death caller of close() must set a flag before this line.
+        this._dead = true;
+        if (this._saveFilePath) {
+            deleteSave(this._saveFilePath);
+            // The cloud copy burns too -- tombstone-first, so an offline death
+            // can't be resurrected from the mirror (see cloud-saves.ts).
+            burnCloudSaveFor(this._saveFilePath, this.player.name);
+            Logger.getInstance().write(`Permadeath: save deleted (${this._saveFilePath}).`);
+        }
         this.stopPursuitHeartbeat();
         this._inputBox.removeAllListeners(); // removes all event listeners
         this._inputBox.cancel(); // cancels any active input session
@@ -1273,8 +1487,18 @@ export default class Game {
         });
         this._inputBox = inputBox;
         screen.append(inputBox);
-        // Key bindings
-        screen.key(['escape', 'C-c'], () => process.exit(0));
+        // Key bindings. ESC/Ctrl-C take a SECOND press within 3s to quit
+        // (player request: "I just exited by mistake") -- the first press
+        // warns; typing anything disarms nothing (the window just expires).
+        screen.key(['escape', 'C-c'], () => {
+            const now = Date.now();
+            if (now - this._escArmedAt < 3000) {
+                process.exit(0);
+            }
+            this._escArmedAt = now;
+            Logger.getInstance().logWithColor(`Press again within 3s to quit. (Or "quit" + "y".)`, 'yellow');
+            this._screen?.render();
+        });
         // Focus on the input box by default -- but ONLY if it isn't already
         // focused. screen.append() auto-focuses the first keyable element
         // (Node.insert), and since the sidebar boxes were removed this textbox
@@ -1309,7 +1533,7 @@ export default class Game {
             border: {
                 type: 'line'
             },
-            label: ' Game Log (PgUp/PgDn to scroll) ',
+            label: this.buildLogLabel(false),
             scrollable: true, // Enable scrolling
             alwaysScroll: true,
             scrollbar: {
@@ -1337,10 +1561,17 @@ export default class Game {
         // yanking the view back down (Logger.log and ui.ts honor it).
         // Paging back to the bottom -- or End -- re-engages the follow.
         logBox.followBottom = true;
+        // CRITICAL: the input box is ALWAYS reading (focus never leaves it),
+        // and blessed's textarea.readInput sets screen.grabKeys = true --
+        // which mutes every screen-level key handler EXCEPT keys listed in
+        // screen.ignoreLocked (screen.js:591). Without this, the bindings
+        // below simply never fire (a real session: "PgUp/Dn don't work").
+        // The textbox itself ignores these keys, so nothing is stolen.
+        screen.ignoreLocked.push('pageup', 'pagedown', 'end');
         const page = () => Math.max(1, (typeof logBox.height === 'number' ? logBox.height : 20) - 3);
         const setFollow = (on) => {
             logBox.followBottom = on;
-            logBox.setLabel(on ? ' Game Log (PgUp/PgDn to scroll) ' : ' Game Log -- SCROLLED (End to follow) ');
+            logBox.setLabel(this.buildLogLabel(!on));
         };
         const atBottom = () => logBox.getScrollPerc() >= 100 || logBox.getScrollHeight() <= page() + 3;
         screen.key(['pageup'], () => {
@@ -1361,6 +1592,29 @@ export default class Game {
         });
         screen.append(logBox);
     }
+    /**
+     * The Game Log banner names WHERE you are in the campaign (player
+     * request): the hub by name at home, "JOB #n: <name>" on a run --
+     * plus the scroll state the label already carried.
+     */
+    buildLogLabel(scrolled) {
+        const onHub = this._hubScene !== undefined && this.scene === this._hubScene;
+        const name = onHub ? this._hubName : this.sceneSeed?.name;
+        const where = name ? ` -- ${name}` : '';
+        // The key coaching is hint-gated (player request); the SCROLLED
+        // state itself stays -- it's status, not teaching.
+        return scrolled
+            ? ` Game Log${where} -- SCROLLED${hint(' (End to follow)')} `
+            : ` Game Log${where}${hint(' (PgUp/PgDn to scroll)')} `;
+    }
+    /** Re-stamps the banner after a scene change (init, run start, home). */
+    refreshLogLabel() {
+        const box = this._logBox;
+        if (!box)
+            return;
+        box.setLabel(this.buildLogLabel(box.followBottom === false));
+        this._screen?.render();
+    }
     /**
      * Scroll the log to its tail -- unless the player has paged up to read
      * history (followBottom off), in which case their place is left alone.
@@ -1461,7 +1715,10 @@ export default class Game {
         // a real question.
         const crumb = player.cameFrom ? `${player.cameFrom.room} (${player.cameFrom.back}) > ` : '';
         if (player.currentLocation) {
-            lines.push(`${crumb}{bold}📍 ${player.currentLocation.name}{/bold}  |  ${stance}`);
+            // "At" spots: where you stand WITHIN the room, when it has places
+            // to stand (see utilities/spots.ts).
+            const atNote = spotOf(player) ? ` @ ${player.atSpot}` : '';
+            lines.push(`${crumb}{bold}📍 ${player.currentLocation.name}${atNote}{/bold}  |  ${stance}`);
         }
         else {
             lines.push(stance);
@@ -1544,7 +1801,7 @@ export default class Game {
         // works the grid while you're back in the meat (the AR-drop exit).
         const remoteAgent = this.companions.find(c => c.kind === 'agent');
         if (remoteAgent && player.plane !== 'matrix') {
-            lines.push(`{cyan-fg}▣ DECK IN AR -- ${remoteAgent.npc.name} on the grid${remoteAgent.npc.objective ? ', working its directive' : ''} ("jack in" to rejoin it, "recall" to fold it home){/cyan-fg}`);
+            lines.push(`{cyan-fg}▣ DECK IN AR -- ${remoteAgent.npc.name} on the grid${remoteAgent.npc.objective ? ', working its directive' : ''}${hint(' ("jack in" to rejoin it, "recall" to fold it home)')}{/cyan-fg}`);
         }
         // Off-plane context: which reality you're in, your persona's Matrix
         // track (cold-sim damage lands there), and where your empty body lies.
@@ -1590,9 +1847,10 @@ export default class Game {
         this.updateStatus();
     }
     // Public method to get the instance of the Game class
-    static async getInstance(player, sceneSeed) {
+    static async getInstance(player, sceneSeed, resume) {
         if (!Game.instance) {
             Game.instance = new Game(player, sceneSeed);
+            Game.instance._resume = resume;
         }
         return Game.instance;
     }
@@ -1603,8 +1861,25 @@ export default class Game {
         const parts = normalized.trim().split(' ');
         const verb = parts[0].toLowerCase();
         const args = parts.slice(1);
-        if (verb === 'quit' || verb === 'exit') {
-            return null;
+        // Quitting takes a CONFIRM (player request: "I just exited by
+        // mistake"): the first "quit" arms it, "y"/"yes" (or quit again)
+        // seals it, anything else disarms and runs as the command it is.
+        if (this._quitArmed) {
+            this._quitArmed = false;
+            if (/^(y|yes|quit|exit)$/i.test(verb)) {
+                return null;
+            }
+            // fall through -- the answer was a real command; play on.
+        }
+        else if (verb === 'quit' || verb === 'exit') {
+            this._quitArmed = true;
+            return `Really quit? ("y" to confirm -- anything else keeps playing.)`;
+        }
+        // Out cold with the fight settling around you (see
+        // Scene.beginPlayerKnockout): unconsciousness is not a prompt. Only
+        // quit (handled above) still answers.
+        if (this.player.isUnconscious() && this.scene.playerKnockout) {
+            return `You're out cold -- the world moves without you.`;
         }
         if (verb === 'maka') {
             return 'You are still in the game, type "quit" to exit';
@@ -1653,10 +1928,12 @@ export default class Game {
                 return `I don't understand "${verb}" -- did you mean "${guess}"?`;
             }
             const corrected = await this.handleInput([guess, ...args].join(' '));
-            // The correction note is bookkeeping -- Mechanics ticker, not the
-            // narrative (readability pass).
-            Logger.getInstance().meta(`(read "${verb}" as "${guess}")`);
-            return corrected;
+            // The correction note stays INLINE and always-on (player ruling:
+            // it briefly moved to the Mechanics ticker, and a conversational
+            // "well I'm here..." silently became a SELL with nothing in the
+            // world log explaining the refusal that came back). It's not dice
+            // noise -- it's the only receipt for a command you didn't type.
+            return corrected === null ? null : `(read "${verb}" as "${guess}")\n${corrected ?? ''}`;
         }
         return `I don't understand the command "${verb}".`;
     }
@@ -1670,7 +1947,7 @@ export default class Game {
      * future command can't silently fall out of help.
      */
     static HELP_CATEGORIES = [
-        { title: 'moving', entries: [['look'], ['go'], ['map', 'exits'], ['search'], ['sneak']] },
+        { title: 'moving', entries: [['look'], ['go'], ['move', 'walk', 'approach', 'run', 'sprint'], ['map', 'exits'], ['search'], ['sneak']] },
         { title: 'gear', entries: [['inv', 'inventory'], ['equipment', 'eq'], ['take'], ['drop'], ['give'], ['store'], ['equip'], ['unequip'], ['brandish', 'draw'], ['holster', 'stow'], ['reload'], ['use'], ['read']] },
         { title: 'combat', entries: [['attack', 'kill'], ['subdue'], ['order'], ['stance'], ['surrender'], ['edge'], ['rest']] },
         { title: 'magic', entries: [['spells'], ['cast'], ['summon', 'conjure'], ['project'], ['return'], ['assense']] },
@@ -1679,7 +1956,7 @@ export default class Game {
         { title: 'street', entries: [['browse', 'buy'], ['sell'], ['work', 'gig'], ['treat'], ['eat'], ['drink'], ['lifestyle'], ['pay']] },
         { title: 'barriers', entries: [['solve'], ['pick'], ['bluff'], ['unlock'], ['lock']] },
         { title: 'character', entries: [['sheet', 'stats'], ['advance', 'train'], ['qualities', 'quality'], ['initiate', 'submerge'], ['install', 'chrome']] },
-        { title: 'session', entries: [['help'], ['clear'], ['quit', 'exit']] },
+        { title: 'session', entries: [['help'], ['hints'], ['clear'], ['quit', 'exit']] },
     ];
     /** Descriptions for the verbs handled inline in handleInput() rather than registered. */
     static BUILTIN_DESCRIPTIONS = {