@maka/maka-cli 5.9.0 → 5.11.0

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

@@ -4,6 +4,10 @@ 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, restoreItem, readSave, } from './utilities/persistence.js';
+import { pushSave, burnCloudSaveFor } from './utilities/cloud-saves.js';
+import { DOCWAGON_TIERS, RESUSC_FEE, DEATH_COMP } from './utilities/docwagon.js';
 import { isFence, LIFESTYLE_TIERS } from './utilities/commerce.js';
 import { rollPool, formatRoll } from './utilities/dice.js';
 import { Direction } from './types/shared/direction-enum.js';
@@ -35,6 +39,12 @@ 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 { AcceptCommand, DeclineCommand } from './commands/job-offer.js';
+import { SourceCommand } from './commands/source.js';
+import { DocwagonCommand } from './commands/docwagon.js';
+import { LeadCommand, RecruitCommand } from './commands/lead.js';
+import { PalmCommand } from './commands/palm.js';
+import { PerformCommand } from './commands/perform.js';
 import { EdgeCommand } from './commands/edge.js';
 import { SheetCommand } from './commands/sheet.js';
 import { CallCommand } from './commands/call.js';
@@ -149,7 +159,191 @@ export default class Game {
     // against the real pending-run seed. One pull per contact per
     // homecoming (asked resets in returnToHub).
     contacts = new Map();
+    // SWAG orders in flight (SR5e p.387/418, commands/source.ts): a
+    // contact shopping the black market for you. Paid up front on a won
+    // Availability test; the goods land at the NEXT HOMECOMING (the
+    // delivery-times table, abstracted to the job-cycle clock the same
+    // way rest is). Rides the save (ISavedGameState.procurements).
+    pendingProcurements = [];
+    // DOCWAGON (SR5e p.450, utilities/docwagon.ts): the wristband between
+    // a runner and the morgue. Rides the save; ticks down at homecomings.
+    docwagon;
+    // LEADERSHIP's Command action (SR5e p.141-142, commands/lead.ts): a
+    // recruited contact rides the NEXT run as an 'ally' companion shell
+    // (spawned at activateRunScene, released at homecoming). RAW's teeth:
+    // a refusal stands until Loyalty deepens past the level it happened
+    // at. Both ride the save.
+    enlistedAlly;
+    commandRefusals = {};
+    // PERFORMANCE's busking gate (commands/perform.ts): one set per job
+    // cycle, reset at homecoming like a contact's legwork. Deliberately
+    // NOT saved -- a relaunch is as good as a homecoming for new material.
+    performedThisCycle = false;
+    /** The recruited contact joins at the jobsite curb ("takes their own
+     *  ride and meets you there" -- the companion convention). */
+    spawnEnlistedAlly() {
+        const ally = this.enlistedAlly;
+        if (!ally)
+            return [];
+        const shell = this.spawnCompanionShell({
+            name: ally.name,
+            description: `${ally.description} Right now they run as ${this.player.name}'s crew: they fight beside them, follow their lead, and expect to be home by morning.`,
+            kind: 'ally',
+            combat: ally.combat,
+            room: this.player.currentLocation,
+            plane: 'meat',
+            force: Number(ally.combat.body ?? 3),
+        });
+        return shell ? [`${ally.name} is already leaning on the wall when you arrive -- "Took my own ride. Let's work."`] : [];
+    }
+    /** Bills a DocWagon fee: cred first, shortfall onto the rent tab (the
+     *  street's one universal collections agency). Returns the line. */
+    billDocwagon(amount, label) {
+        if (amount <= 0)
+            return '';
+        const paid = Math.min(this.player.currency, amount);
+        if (paid > 0)
+            this.player.adjustCurrency(-paid);
+        const owed = amount - paid;
+        if (owed > 0)
+            this.rentDebt += owed;
+        return owed > 0
+            ? `DocWagon bills ${amount} for ${label} -- ${paid} paid, ${owed} on your tab.`
+            : `DocWagon bills ${amount} for ${label}.`;
+    }
+    /**
+     * The band answers (SR5e p.450). 'htr': a High Threat Response team
+     * extracts a flatlining KO'd runner instead of the street deciding.
+     * 'resusc': clinical death reversed -- a free resuscitation or the
+     * 5,000 fee -- the sanctioned carve-out to permadeath (player ruling;
+     * overflow-past-Body instant death isn't modeled yet, so every death
+     * is currently within reach of the crash cart). Returns true when the
+     * rescue engages -- the caller must then NOT end the game.
+     */
+    tryDocwagonRescue(kind, opts = {}) {
+        const contract = this.docwagon;
+        if (!contract || !this.initialized || this._dead)
+            return false;
+        const tier = DOCWAGON_TIERS[contract.tier];
+        const logger = Logger.getInstance();
+        const bills = [];
+        if (kind === 'resusc') {
+            if (contract.resuscsLeft > 0) {
+                contract.resuscsLeft -= 1;
+                bills.push(`A contract resuscitation is burned -- ${contract.resuscsLeft} left this year.`);
+            }
+            else {
+                bills.push(this.billDocwagon(RESUSC_FEE, 'resuscitation'));
+            }
+            // Back from the white light, barely: two boxes shy of the track.
+            const p = this.player;
+            p.healDamage(Math.max(0, p.damageTaken - (p.maxConditionBoxes - 2)));
+            p.healStun(Math.max(0, p.stunTaken - Math.max(0, p.maxStunBoxes - 2)));
+        }
+        else {
+            bills.push(this.billDocwagon(tier.htrFee, 'High Threat Response'));
+            // Extraction under fire: hostiles still standing can cost DocWagon
+            // a medic -- and the client eats the 20,000 death compensation
+            // (p.450), unless the contract says otherwise.
+            const hostiles = opts.standingHostiles ?? [];
+            if (hostiles.length > 0 && tier.deathComp) {
+                const casualtyRoll = rollPool(Math.min(4, hostiles.length));
+                if (casualtyRoll.hits > 0) {
+                    bills.push(this.billDocwagon(DEATH_COMP, 'employee death compensation -- a medic did not make it out'));
+                }
+            }
+            // Conscious enough to be carried: the band's medics stabilize.
+            const p = this.player;
+            p.healStun(Math.max(0, p.stunTaken - Math.max(0, p.maxStunBoxes - 2)));
+        }
+        logger.logWithColor(kind === 'resusc'
+            ? `${CALL_ICON} Your wristband SCREAMS the flatline. Ten minutes later there is foam, light, and a trauma team refusing to let you go.`
+            : `${CALL_ICON} The band reads the flatline and howls -- a DocWagon HTR team storms the scene behind riot shields and suppression foam.`, CALL_COLOR);
+        for (const b of bills.filter(Boolean))
+            logger.logWithColor(b, 'yellow');
+        this.scene.addWorldEvent(`A DocWagon team extracted ${this.player.name} under the ${contract.tier} contract.`);
+        void this.docwagonMedevac();
+        return true;
+    }
+    /** Where the wagon drops you (player ruling: the CLINIC, not your own
+     *  cot): the district Street Doc's room, generically -- so generated
+     *  hubs work too. Falls back to the hideout if the hub has no doc. */
+    docwagonDropOff() {
+        for (const [name, c] of this.contacts) {
+            if (c.role === 'Street Doc') {
+                const doc = this.hubActor(name);
+                if (doc?.currentLocation)
+                    return doc.currentLocation;
+            }
+        }
+        return this._homeRoom;
+    }
+    /** The ride out on a stretcher: mid-run this is a homecoming (rent and
+     *  all), then the recovery bed at the clinic. */
+    async docwagonMedevac() {
+        const logger = Logger.getInstance();
+        try {
+            const clinic = this.docwagonDropOff();
+            if (this.hasHub && this.scene !== this._hubScene) {
+                const home = await this.continueToNextScene();
+                logger.log(home);
+            }
+            this.player.currentLocation = clinic;
+            this.player.cameFrom = undefined;
+            this.updateExits(this.player.currentLocation);
+            this.updateStatus();
+            logger.log(clinic === this._homeRoom
+                ? `You wake on your own cot, taped, stapled, and alive.`
+                : `You wake on a recovery cot under bad fluorescents -- ${clinic.name}. Taped, stapled, and alive.`);
+            this.requestSave('homecoming');
+        }
+        catch (err) {
+            logger.error(`docwagonMedevac failed: ${err}`);
+        }
+    }
     /** How much juice the name carries, read off the role. */
+    /**
+     * A contact's ROLE, the SR5e archetype list (p.98: fixer, arms dealer,
+     * smuggler, talismonger, street doc, mechanic, bartender...) -- same
+     * keyword school as connectionFor below. Stored on the contact entry
+     * at open time so the roster (and the save) carry it.
+     */
+    static roleOf(npc) {
+        const hay = `${npc.description ?? ''} ${npc.name}`.toLowerCase();
+        // Mr. Johnson is NOT the fixer (player ruling: don't overload his
+        // role). Canon splits them: a Johnson is the anonymous CLIENT who
+        // commissions the run; a fixer is the street middleman (scene1's
+        // Mr. Krow, e.g.). He gets his own archetype label.
+        if (npc.name === FIXER_NAME || /job broker|johnson/.test(hay))
+            return 'Job Broker';
+        if (/fixer/.test(hay))
+            return 'Fixer';
+        // "charms" deliberately absent: a market kid hawking LUCKY charms is
+        // a Vendor, not a talismonger (Skitter proved it).
+        if (/talismonger|magical goods|foci|spell formula/.test(hay))
+            return 'Talismonger';
+        if (/street doc|clinic|surgeon|medic|stitch|chop shop/.test(hay))
+            return 'Street Doc';
+        if (/fence|pawn|launder|no questions/.test(hay))
+            return 'Fence';
+        if (/smuggl/.test(hay))
+            return 'Smuggler';
+        if (/mechanic|drone|rigger|garage|airframe/.test(hay))
+            return 'Mechanic';
+        if (/gunsmith|weapons? (and armor|dealer)|armorer|ironmonger/.test(hay))
+            return 'Arms Dealer';
+        if (/bartender|barkeep|tends the .{0,40}bar|pour(s|ed) drinks/.test(hay))
+            return 'Bartender';
+        if (/decker|data broker|host|electronics/.test(hay))
+            return 'Data Broker';
+        if (/priest|sister|chapel|choir|shaman/.test(hay))
+            return 'Spiritual';
+        if (/noodle|food|cook|kitchen|vendor|stall|merchant|shopkeep|market/.test(hay))
+            return 'Vendor';
+        if (/gang|muscle|enforcer|lieutenant|sentry|lookout|bruiser/.test(hay))
+            return 'Muscle';
+        return 'Street Contact';
+    }
     static connectionFor(npc) {
         const hay = `${npc.description ?? ''} ${npc.name}`.toLowerCase();
         if (npc.name === FIXER_NAME || /fixer|johnson/.test(hay))
@@ -177,7 +371,7 @@ export default class Game {
                 continue;
             if (this.contacts.has(actor.name))
                 continue;
-            this.contacts.set(actor.name, { connection: Game.connectionFor(actor), loyalty: 1, spent: 0, gigs: 0, asked: false });
+            this.contacts.set(actor.name, { connection: Game.connectionFor(actor), loyalty: 1, spent: 0, gigs: 0, asked: false, role: Game.roleOf(actor) });
         }
         Logger.getInstance().write(`Home turf: ${this.contacts.size} contacts seeded from the hub cast.`);
     }
@@ -198,6 +392,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
@@ -409,6 +610,11 @@ export default class Game {
      * cumulative spend raises it at each full 1,000 nuyen (cap 3).
      * Returns a player-facing line when something changed, else null.
      */
+    /** A hub-cast member by name, for roster displays that need the live
+     *  actor (contacts.ts reads their commlink to show reachability). */
+    hubActor(name) {
+        return this._hubScene?.allActors?.find(a => a.name === name && a !== this.player);
+    }
     touchContact(name, kind, spent = 0) {
         if (!this.hasHub)
             return null;
@@ -417,7 +623,7 @@ export default class Game {
             return null;
         let c = this.contacts.get(name);
         if (!c) {
-            c = { connection: Game.connectionFor(npc), loyalty: 1, spent: 0, gigs: 0, asked: false };
+            c = { connection: Game.connectionFor(npc), loyalty: 1, spent: 0, gigs: 0, asked: false, role: Game.roleOf(npc) };
             this.contacts.set(name, c);
             if (kind === 'trade')
                 c.spent += spent;
@@ -613,6 +819,18 @@ export default class Game {
     // "call Mr. Johnson" hears the offer, "travel" goes.
     _pendingRunSeed;
     _pendingRunTier;
+    // The explicit handshake (player ruling, commands/job-offer.ts):
+    // "accept" locks the offer -- rate final, haggle closed, decline
+    // refused -- until "call taxi" installs it. Reset wherever the
+    // pending seed changes hands.
+    pendingRunAccepted = false;
+    /** Trash the offer wholesale ("decline", and any future fixer snub). */
+    clearPendingRun() {
+        this._pendingRunSeed = undefined;
+        this._pendingRunTier = undefined;
+        this._pendingRide = undefined;
+        this.pendingRunAccepted = false;
+    }
     get pendingRun() {
         return this._pendingRunSeed;
     }
@@ -721,6 +939,22 @@ export default class Game {
         CommandFactory.registerCommand('reload', ReloadCommand);
         CommandFactory.registerCommand('subdue', SubdueCommand);
         // SUBDUING p.195 (see commands/grapple.ts): restrain without damage.
+        // Canon skill hooks (see SkillName in models/player.ts).
+        CommandFactory.registerCommand('palm', PalmCommand);
+        CommandFactory.registerCommand('perform', PerformCommand);
+        // LEADERSHIP (commands/lead.ts): rally/direct/inspire + Command recruiting.
+        CommandFactory.registerCommand('lead', LeadCommand);
+        CommandFactory.registerCommand('command', RecruitCommand);
+        // DOCWAGON (commands/docwagon.ts): the wristband between you and the morgue.
+        CommandFactory.registerCommand('docwagon', DocwagonCommand);
+        // SWAG (commands/source.ts): contacts shop the black market for you.
+        CommandFactory.registerCommand('source', SourceCommand);
+        CommandFactory.registerCommand('procure', SourceCommand);
+        // Job-offer outcomes (commands/job-offer.ts): explicit accept/decline.
+        CommandFactory.registerCommand('accept', AcceptCommand);
+        CommandFactory.registerCommand('decline', DeclineCommand);
+        CommandFactory.registerCommand('deny', DeclineCommand);
+        CommandFactory.registerCommand('refuse', DeclineCommand);
         CommandFactory.registerCommand('grapple', GrappleCommand);
         CommandFactory.registerCommand('restrain', GrappleCommand);
         CommandFactory.registerCommand('clinch', GrappleCommand);
@@ -849,6 +1083,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);
@@ -891,16 +1126,24 @@ 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
@@ -908,7 +1151,9 @@ export default class Game {
             // 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.
-            if (this.canDraftNextScene().allowed) {
+            // 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();
             }
         }
@@ -922,7 +1167,20 @@ export default class Game {
         // 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
@@ -933,6 +1191,152 @@ export default class Game {
             : '';
         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);
+        // Roles are DERIVED, not earned -- re-derive them all on every
+        // resume so old saves self-heal (pre-role saves read all "Street
+        // Contact"; the next vintage had Johnson stored as "Fixer" before
+        // the Job Broker split). Missing actors keep whatever the save said.
+        for (const [name, c] of this.contacts) {
+            const npc = this._hubScene?.allActors?.find(a => a.name === name);
+            if (npc)
+                c.role = Game.roleOf(npc);
+            else if (!c.role)
+                c.role = 'Street Contact';
+        }
+        // SEED-TRUTH for commlinks: the hub overlay replaces NPC inventories
+        // wholesale, so a link granted to the CAST by a newer seed (player
+        // request: Torque, Ratchet, Doc, Old Cray, Skitter, and Whisper all
+        // answer calls now) would be wiped by an older save. Re-grant any
+        // seed-held commlink its bearer no longer carries.
+        for (const seedItem of this._hubSeed?.items ?? []) {
+            if (seedItem.category !== 'Commlink' || !seedItem.heldBy)
+                continue;
+            const bearer = this._hubScene?.allActors?.find(a => a.name === seedItem.heldBy);
+            if (!bearer)
+                continue;
+            const hasLink = bearer.inventory.getAllItems().some(i => i.category === Category.Commlink)
+                || bearer.equipment.head?.commlink != null;
+            if (!hasLink) {
+                bearer.inventory.addItem(restoreItem(seedItem));
+                Logger.getInstance().write(`Resume heal: re-granted "${seedItem.name}" to ${seedItem.heldBy}.`);
+            }
+        }
+        this.pendingProcurements = [...(save.game.procurements ?? [])];
+        this.docwagon = save.game.docwagon ? { ...save.game.docwagon } : undefined;
+        this.enlistedAlly = save.game.enlistedAlly ? { ...save.game.enlistedAlly } : undefined;
+        this.commandRefusals = { ...(save.game.commandRefusals ?? {}) };
+        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);
+            // Carry the cloud-sync stamp FORWARD through local writes: the
+            // stamp means "the cloud's savedAt as of our last mirror", and a
+            // new local beat doesn't change what the cloud holds. Without
+            // this, every quit (whose async push can't outlive the process)
+            // left a stampless file that the next launch misread as a FORK
+            // and prompted over (a real session hit it on every reload).
+            const prev = readSave(this._saveFilePath);
+            if (prev.ok && prev.save.sync)
+                save.sync = prev.save.sync;
+            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()],
+                procurements: [...this.pendingProcurements],
+                docwagon: this.docwagon ? { ...this.docwagon } : undefined,
+                enlistedAlly: this.enlistedAlly ? { ...this.enlistedAlly } : undefined,
+                commandRefusals: { ...this.commandRefusals },
+                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
@@ -1047,6 +1451,8 @@ export default class Game {
         // pull each per homecoming (see commands/ask.ts).
         for (const contact of this.contacts.values())
             contact.asked = false;
+        // Fresh material for the buskers too (commands/perform.ts).
+        this.performedThisCycle = false;
         // LIFESTYLE upkeep comes due with the homecoming: this tier's share
         // plus any standing debt, paid from carried cred as far as it goes.
         // Coming up short SLIDES YOU DOWN a tier (the district notices) and
@@ -1096,10 +1502,56 @@ export default class Game {
         // Drones spin back up beside the cot.
         const companionArrivalLines = this.unfoldCompanionsOnArrival();
         const companionBlock = [...companionFoldLines, ...companionArrivalLines];
+        // The commanded ally's tour ends with the run (RAW's Command lasts
+        // turns; ours lasts the job): the crew disbands at the curb.
+        let allyLine = '';
+        if (this.enlistedAlly) {
+            allyLine = `\n${this.enlistedAlly.name} peels off at the curb -- "Call it even, chummer." The crew's back to just you.`;
+            this.enlistedAlly = undefined;
+        }
+        // DOCWAGON's year ticks in homecomings (12 = a street year, player
+        // ruling): the contract lapses quietly unless renewed at Doc's.
+        let docwagonLine = '';
+        if (this.docwagon) {
+            this.docwagon.homecomingsLeft -= 1;
+            if (this.docwagon.homecomingsLeft <= 0) {
+                docwagonLine = `\nYour DocWagon ${this.docwagon.tier} contract LAPSES -- the wristband goes dark.${hint(` ("docwagon <tier>" at Doc's renews it.)`)}`;
+                this.docwagon = undefined;
+            }
+            else if (this.docwagon.homecomingsLeft <= 2) {
+                docwagonLine = `\nDocWagon renewal coming due: ${this.docwagon.homecomingsLeft} homecoming${this.docwagon.homecomingsLeft === 1 ? '' : 's'} left on the ${this.docwagon.tier} contract.`;
+            }
+        }
+        // SWAG deliveries (commands/source.ts): the contact's shopping run
+        // lands with the homecoming -- straight into your gear, paid for at
+        // order time.
+        let deliveryLine = '';
+        if (this.pendingProcurements.length > 0) {
+            const delivered = [];
+            for (const order of this.pendingProcurements.splice(0)) {
+                try {
+                    const item = restoreItem(order.itemConfig);
+                    item.owner = this.player.name;
+                    this.player.inventory.addItem(item);
+                    delivered.push(`${item.name} (${order.contact} came through)`);
+                }
+                catch (err) {
+                    Logger.getInstance().error(`Procurement delivery failed: ${err}`);
+                }
+            }
+            if (delivered.length > 0) {
+                this.updateInventory(this.player.inventory, capitalCase(this.scene.getCurrencyType()));
+                deliveryLine = `\nWaiting with your gear: ${delivered.join(', ')}.`;
+            }
+        }
+        // The homecoming save: everything above (payout, rent, restock,
+        // contacts reset, deliveries) 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}.${hint(` 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}${deliveryLine}${docwagonLine}${allyLine}${companionBlock.length > 0 ? `\n${companionBlock.join('\n')}` : ''}`;
     }
     /**
      * The actual drafting work, split out from continueToNextScene() purely
@@ -1144,6 +1596,7 @@ export default class Game {
             this._pendingRunSeed = nextSeed;
             this._pendingRunTier = nextTier;
             this._pendingRide = Game.RIDE_POOL[Math.floor(Math.random() * Game.RIDE_POOL.length)];
+            this.pendingRunAccepted = false;
             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.
@@ -1197,11 +1650,13 @@ export default class Game {
         // Deployed drones spin back up at the curb -- BEFORE appearance
         // warming so re-shelled companions get warmed with the cast.
         const arrivalLines = this.unfoldCompanionsOnArrival();
+        // A commanded ally meets you at the jobsite (commands/lead.ts).
+        const allyLines = this.spawnEnlistedAlly();
         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];
+        const companionBlock = [...companionLines, ...arrivalLines, ...allyLines];
         return `\n${this.scene.story}${needsLines.length > 0 ? `\n${needsLines.join('\n')}` : ''}${companionBlock.length > 0 ? `\n${companionBlock.join('\n')}` : ''}`;
     }
     /**
@@ -1282,24 +1737,38 @@ 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 });
-            this._pendingRunSeed = undefined;
-            this._pendingRunTier = undefined;
-            this._pendingRide = undefined;
+            this.clearPendingRun();
             this.player.haggledThisJob = haggledAtOffer;
             return `You travel to ${this.player.currentLocation.name}.\n${banner}`;
         }
         catch (err) {
-            this._pendingRunSeed = undefined;
-            this._pendingRunTier = undefined;
-            this._pendingRide = undefined;
+            this.clearPendingRun();
             Logger.getInstance().error(`launchPendingRun failed: ${err}`);
             return `The ride never shows and the job address goes dead. ${FIXER_NAME} will not enjoy hearing this -- call him for another.`;
         }
     }
     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
@@ -1691,9 +2160,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;
     }