@maka/maka-cli 5.66.0 → 5.68.0

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

@@ -32,6 +32,7 @@ import { BacklogCommand } from './commands/backlog.js';
 // help index offers, never what the verb accepts (item D).
 import { isPlaytester, probePlaytesterStanding } from './utilities/playtester.js';
 import { RolesCommand } from './commands/roles.js';
+import { ReviewCommand } from './commands/review.js';
 import { SinCommand } from './commands/sin.js';
 import { GoCommand } from './commands/go.js';
 import { UseCommand } from './commands/use.js';
@@ -95,9 +96,12 @@ import { ContactsCommand } from './commands/contacts.js';
 import { JumpCommand } from './commands/jump.js';
 import { InitiateCommand } from './commands/initiate.js';
 import { SummonCommand } from './commands/summon.js';
-import { CompileCommand, SPRITE_TYPES } from './commands/compile.js';
+import { CompileCommand, SPRITE_TYPES, uniqueSpriteName } from './commands/compile.js';
+import { DecompileCommand } from './commands/decompile.js';
 import { ThreadCommand } from './commands/thread.js';
 import { RegisterCommand } from './commands/register.js';
+import { SpritesCommand } from './commands/sprites.js';
+import { UnravelCommand } from './commands/unravel.js';
 import { OrderCommand } from './commands/order.js';
 import { DeployCommand, AgentCommand, RecallCommand } from './commands/companions.js';
 import { DeckCommand, LoadProgramCommand, UnloadProgramCommand } from './commands/deck.js';
@@ -186,6 +190,9 @@ export default class Game {
     // social layer stays dark (presence, cloud mirror, street, drafts).
     _owner;
     _anonymous = false;
+    _bench = false;
+    _reproItemId;
+    _closing = false;
     _logFilePath = '';
     _tier = 1;
     /**
@@ -254,6 +261,66 @@ export default class Game {
     get isAnonymous() {
         return this._anonymous;
     }
+    /**
+     * A REPRO BENCH: a scratch session stood up to reproduce one backlog
+     * item. Not a life -- no save, no street presence, no shared table.
+     *
+     * SEPARATE FROM `isAnonymous`, and the separation is the point. The
+     * bench first reused the anonymous flag, since both want the street
+     * left alone -- and that quietly took the BACKLOG with it, because
+     * anonymity is a promise about a RUNNER ("nothing about them leaves
+     * this machine") and the backlog is one of the things it forbids. So
+     * a play-tester standing in the bench built for their own report was
+     * refused when they tried to answer it, which is the one thing the
+     * bench exists for.
+     *
+     * Two different concerns wearing one flag: "this character is
+     * private" and "this session is scratch". A bench is not private --
+     * it is the opposite, a place to file and confirm from.
+     */
+    get isBench() {
+        return this._bench;
+    }
+    /** The backlog item this bench was stood up for, if any.
+     *
+     *  The review commands read it so an answer needs no index. Player
+     *  ruling 2026-08-28: "I shouldn't have to pick from the list of
+     *  review items -- I AM reviewing an item." Making someone name which
+     *  report they mean, while they are standing in the scene built for
+     *  that report, is asking a question the session already answered. */
+    get reproItemId() {
+        return this._reproItemId;
+    }
+    /**
+     * CLOSE THE SESSION SHORTLY, leaving the last message on screen.
+     *
+     * For a bench that has just been answered (player request 2026-08-28:
+     * "after accepting or rejecting, give a 3s timeout and then close the
+     * session"). The pause is the point -- exiting the instant the post
+     * lands would wipe the confirmation before it could be read, and the
+     * confirmation is the only proof the answer went anywhere.
+     *
+     * Exits code 0, which is the same door `quit` goes through: the save
+     * seal in ui.ts fires (a no-op for a bench, which has no save path)
+     * and the launcher parent, which is the terminal's guaranteed
+     * janitor, restores the terminal exactly as it would after any other
+     * exit. No second teardown path.
+     *
+     * Idempotent: the first request wins, so answering twice in three
+     * seconds cannot stack timers.
+     */
+    closeAfter(ms, reason) {
+        if (this._closing)
+            return;
+        this._closing = true;
+        const timer = setTimeout(() => {
+            Logger.getInstance().write(`<<<<<<<<--------- Closing session: ${reason}`);
+            process.exit(0);
+        }, ms);
+        // Never hold the process open on its own account -- if everything
+        // else has finished, going now is right.
+        timer.unref?.();
+    }
     get sessionDir() {
         return this._logFilePath ? dirname(this._logFilePath) : undefined;
     }
@@ -452,13 +519,13 @@ export default class Game {
      * push one right now and say so.
      */
     async pushPresenceNow() {
-        if (this._anonymous)
+        if (this._anonymous || this._bench)
             return 'offline';
         return heartbeatPresenceNow(this.presencePayload());
     }
     startPresenceHeartbeat() {
-        if (this._anonymous)
-            return; // account-less: never on the street
+        if (this._anonymous || this._bench)
+            return; // account-less, or a bench: never on the street
         if (this._presenceTimer)
             return;
         this.beatPresence();
@@ -883,9 +950,98 @@ export default class Game {
     // death both remove the entry; persistent state (the frame, the deck)
     // lives on Items in the player's possession, never here.
     companions = [];
-    /** A registered sprite folded for travel, waiting to re-shell at the
-     *  destination (the drone _pendingRedeploys school). */
-    _pendingSpriteRedeploy;
+    /** REGISTERED SPRITES WAITING IN THE RESONANCE (SR5 p.254-256):
+     *  folded for travel, or staged from a resumed save, waiting to
+     *  re-shell (the drone _pendingRedeploys school).
+     *
+     *  An ARRAY since 2026-08-28. It was a single slot back when one
+     *  sprite was the hard maximum; the canon cap is one COMPILED sprite
+     *  with registered ones exempt, up to LOGIC of them (register.ts), so
+     *  a single slot would have quietly dropped every registered sprite
+     *  but one at the next save or journey -- the same "your permanent
+     *  companion vanished" the fix is for, moved one step downstream. */
+    _pendingSpriteRedeploy = [];
+    /** How many registrations are spent: the ones standing here plus the
+     *  ones waiting in the Resonance. register.ts bills this against
+     *  Logic. */
+    registeredSpriteCount() {
+        return this.companions.filter(c => c.kind === 'sprite' && c.registered).length
+            + this._pendingSpriteRedeploy.length;
+    }
+    // THE STASH AND THE LIVE ROSTER ARE DISJOINT, and every mover below
+    // must keep them that way: a registered sprite is EITHER standing in
+    // `companions` OR waiting here, never both and never neither.
+    // foldCompanionsForTravel pushes here and dismisses the shell in the
+    // same pass; both drains splice(0); dismissSpriteToResonance and
+    // callSpriteFromResonance are the two halves of Call/Dismiss and move
+    // a sprite across in one step each.
+    //
+    // This is why decompile.ts needs no "forget this registration" call,
+    // and why one written there could not be made to fail under mutation:
+    // decompile only reaches actors in the room, and a sprite waiting
+    // HERE is not in the room. That stays true now that Call/Dismiss can
+    // put one here mid-run -- dismissing does not make it decompilable,
+    // it makes it absent.
+    /** Registered sprites waiting in the Resonance, for the surfaces that
+     *  have to tell a player what they still have. A copy: the stash is
+     *  maintained by the movers above and nowhere else. */
+    registeredSpritesWaiting() {
+        return this._pendingSpriteRedeploy.map(s => ({ ...s }));
+    }
+    /**
+     * DISMISS half of Call/Dismiss Sprite (SR5 p.250, Simple Action):
+     * "send a sprite back to the Resonance, releasing it from any tasks it
+     * still owes you."
+     *
+     * The task release is canon and it is the expensive part -- p.256
+     * offers STANDBY (costs 1 task, keeps the rest) precisely because
+     * dismissing burns them all. So tasks go to 0 here rather than being
+     * carried, and the command that calls this says so out loud before a
+     * player spends a companion's usefulness to tidy the grid.
+     *
+     * Only a REGISTERED sprite has anywhere to go. A compiled one that is
+     * sent away is simply gone, which is decompile's job, not this one --
+     * so this refuses it rather than quietly destroying it.
+     */
+    dismissSpriteToResonance(entry) {
+        if (entry.kind !== 'sprite' || !entry.registered || !entry.spriteType)
+            return false;
+        this._pendingSpriteRedeploy.push({
+            spriteType: entry.spriteType,
+            level: entry.force,
+            tasks: 0,
+            name: entry.npc.name,
+        });
+        this.dismissCompanion(entry, 'dismissed to the Resonance');
+        return true;
+    }
+    /**
+     * CALL half of Call/Dismiss Sprite (p.250): "You call a registered
+     * sprite you have waiting in the Resonance."
+     *
+     * `name` picks one when several wait; without it, the first. Returns
+     * the arrival line, or undefined when nothing answered -- the caller
+     * owns the refusal wording, because "you have none" and "you have
+     * some but not that one" are different things to be told.
+     */
+    callSpriteFromResonance(name) {
+        const idx = name === undefined
+            ? (this._pendingSpriteRedeploy.length > 0 ? 0 : -1)
+            : this._pendingSpriteRedeploy.findIndex(s => s.name === name);
+        if (idx < 0)
+            return undefined;
+        // Removed BEFORE the re-shell, so a failed spawn cannot leave the
+        // same sprite both waiting and standing.
+        const [spec] = this._pendingSpriteRedeploy.splice(idx, 1);
+        const line = this.respawnRegisteredSprite(spec);
+        if (line === undefined) {
+            // It could not land. Put it back rather than losing it: the
+            // registration is the player's property, not this call's.
+            this._pendingSpriteRedeploy.splice(idx, 0, spec);
+            return undefined;
+        }
+        return line;
+    }
     // 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 = [];
@@ -1164,7 +1320,7 @@ export default class Game {
                 // A REGISTERED sprite persists (register.ts): it folds into
                 // your PAN for the ride and re-shells at the curb.
                 if (entry.registered && entry.spriteType) {
-                    this._pendingSpriteRedeploy = { spriteType: entry.spriteType, level: entry.force, tasks: entry.services ?? 0 };
+                    this._pendingSpriteRedeploy.push({ spriteType: entry.spriteType, level: entry.force, tasks: entry.services ?? 0, name: entry.npc.name });
                     lines.push(`${entry.npc.name} folds into your PAN for the ride -- registered code travels with you.`);
                 }
                 else {
@@ -1196,10 +1352,11 @@ export default class Game {
             if (shell)
                 lines.push(`The ${item.name}'s rotors spin back up at the curb.`);
         }
-        // A REGISTERED sprite re-shells from the PAN (register.ts).
-        if (this._pendingSpriteRedeploy) {
-            const spec = this._pendingSpriteRedeploy;
-            this._pendingSpriteRedeploy = undefined;
+        // EVERY registered sprite re-shells from the PAN (register.ts).
+        // splice(0) drains the stash exactly once, the way the drone loop
+        // above does -- a sprite that fails to land is not left staged to
+        // try again at the next curb.
+        for (const spec of this._pendingSpriteRedeploy.splice(0)) {
             const line = this.respawnRegisteredSprite(spec);
             if (line)
                 lines.push(line);
@@ -1214,7 +1371,11 @@ export default class Game {
         if (!type)
             return undefined;
         const shell = this.spawnCompanionShell({
-            name: `${type.name} Sprite (Level ${spec.level})`,
+            // The name it left with, so "order <name>" still works after the
+            // ride -- but never on top of a live actor, which is how two
+            // registered sprites of the same type and Level used to collide
+            // and silently lose the second one.
+            name: this.scene.getActor(spec.name) ? uniqueSpriteName(this.scene, type.name, spec.level) : spec.name,
             description: `A registered ${type.name.toLowerCase()} sprite riding ${this.player.name}'s PAN -- ${type.blurb}. It serves until its ${spec.tasks} task${spec.tasks === 1 ? '' : 's'} are spent.`,
             kind: 'sprite',
             combat: type.combat(spec.level),
@@ -1512,8 +1673,8 @@ export default class Game {
     /** The transport, hooks-first, CLI default second; undefined =
      *  offline/logged out/classic mode (callers degrade quietly). */
     async streetTransport() {
-        if (this._anonymous)
-            return undefined; // account-less: no street
+        if (this._anonymous || this._bench)
+            return undefined; // account-less, or a bench: no street
         if (this.listStreetPlayers && this.sendPage) {
             return { list: this.listStreetPlayers, send: this.sendPage };
         }
@@ -1805,6 +1966,8 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
         CommandFactory.registerCommand('note', NoteCommand);
         CommandFactory.registerCommand('backlog', BacklogCommand);
         CommandFactory.registerCommand('roles', RolesCommand);
+        // The short form of "backlog review" -- see commands/review.ts.
+        CommandFactory.registerCommand('review', ReviewCommand);
         CommandFactory.registerCommand('sin', SinCommand);
         CommandFactory.registerCommand('sins', SinCommand);
         CommandFactory.registerCommand('papers', SinCommand);
@@ -1910,9 +2073,13 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
         CommandFactory.registerCommand('summon', SummonCommand);
         CommandFactory.registerCommand('conjure', SummonCommand);
         CommandFactory.registerCommand('compile', CompileCommand);
-        CommandFactory.registerCommand('decompile', CompileCommand);
+        CommandFactory.registerCommand('decompile', DecompileCommand);
         CommandFactory.registerCommand('thread', ThreadCommand);
         CommandFactory.registerCommand('register', RegisterCommand);
+        // The sprite database (p.256-259) -- reference, the way "spells" is.
+        CommandFactory.registerCommand('sprites', SpritesCommand);
+        // Kill Complex Form (p.250) -- the Resonance counterpart to dispel.
+        CommandFactory.registerCommand('unravel', UnravelCommand);
         // "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).
@@ -2078,6 +2245,8 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
         this._saveFilePath = options.saveFilePath;
         this._owner = options.owner;
         this._anonymous = options.anonymousRunner === true;
+        this._bench = options.reproBench === true;
+        this._reproItemId = options.reproItemId;
         // Ask the server, once, whether this account is a play-tester, so
         // the help index can stop advertising a backlog that will only 403
         // (item D). Fire-and-forget on purpose: it never blocks the boot,
@@ -2130,7 +2299,23 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
         // spawned in a phantom hideout and read it as a kick back to the
         // hub). The room object still exists for any code that touches
         // _homeRoom; it's just not in the scene.
-        if (!options.sharedRun) {
+        // A BENCH GETS NO HIDEOUT EITHER, for the same reason a shared run
+        // does not: nobody lives here. It is two rooms and a door.
+        //
+        // FOUND FROM A LIVE SESSION LOG (2026-08-28). The bench promises
+        // "you start standing at the barrier", and it did not: the hideout
+        // was added and the player was moved INTO it, so the first thing a
+        // reviewer had to do was "go up" out of a home the bench had built
+        // them. They reported the steps as wrong; the steps were right and
+        // the scene had grown a room.
+        //
+        // WORTH RECORDING WHY THE DRY RUN MISSED IT. The headless harness
+        // boots with sharedRun: true, so it took the branch that skips all
+        // of this -- the replay I had been calling proof of the bench was
+        // quietly proving a DIFFERENT scene from the one a player gets.
+        // Adding reproBench here is what makes the two agree, which is the
+        // property the dry run was supposed to have all along.
+        if (!options.sharedRun && !options.reproBench) {
             this.scene.addRoom(this._homeRoom);
             this.connectHomeRoom(this.player.currentLocation);
             // Every session starts AT HOME -- the hideout, one door from the
@@ -2230,12 +2415,12 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
         }
         // A REGISTERED sprite from the save re-shells at the cot (the
         // technomancer's persistent companion -- register.ts).
-        if (this._pendingSpriteRedeploy && this.scene === this._hubScene) {
-            const spec = this._pendingSpriteRedeploy;
-            this._pendingSpriteRedeploy = undefined;
-            const line = this.respawnRegisteredSprite(spec);
-            if (line)
-                Logger.getInstance().logWithColor(line, 'cyan');
+        if (this._pendingSpriteRedeploy.length > 0 && this.scene === this._hubScene) {
+            for (const spec of this._pendingSpriteRedeploy.splice(0)) {
+                const line = this.respawnRegisteredSprite(spec);
+                if (line)
+                    Logger.getInstance().logWithColor(line, 'cyan');
+            }
         }
         if (this._resume) {
             const pendingNote = this._pendingRunSeed
@@ -2319,9 +2504,22 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
         if (this.crew.length > 0 && this.crewForHire.some(c => this.crew.some(m => m.name === c.name))) {
             this.rollHireCandidates();
         }
-        // The registered sprite stages for its re-shell at hub arrival.
-        if (save.game.registeredSprite) {
-            this._pendingSpriteRedeploy = { ...save.game.registeredSprite };
+        // Registered sprites stage for their re-shell at hub arrival. The
+        // array is the live field; the singular `registeredSprite` is only
+        // read when it is absent, which is exactly the pre-2026-08-28 saves
+        // written before a technomancer could hold more than one. Reading
+        // BOTH would double a sprite on the first save that carries each.
+        if (save.game.registeredSprites && save.game.registeredSprites.length > 0) {
+            this._pendingSpriteRedeploy = save.game.registeredSprites.map(s => ({ ...s }));
+        }
+        else if (save.game.registeredSprite) {
+            const legacy = save.game.registeredSprite;
+            const type = SPRITE_TYPES[legacy.spriteType];
+            this._pendingSpriteRedeploy = [{
+                    ...legacy,
+                    // Old saves carry no name; rebuild the one it would have had.
+                    name: `${type?.name ?? 'Courier'} Sprite (Level ${legacy.level})`,
+                }];
         }
         if (this.crew.length === 0 && save.game.enlistedAlly) {
             const legacy = save.game.enlistedAlly;
@@ -2430,13 +2628,19 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
                 contacts: [...this.contacts.entries()],
                 procurements: [...this.pendingProcurements],
                 docwagon: this.docwagon ? { ...this.docwagon } : undefined,
-                registeredSprite: (() => {
-                    // A live registered sprite rides the save; a travel-folded one
-                    // is in the redeploy stash. Either way it survives the session.
-                    const live = this.companions.find(c => c.kind === 'sprite' && c.registered && c.spriteType);
-                    if (live)
-                        return { spriteType: live.spriteType, level: live.force, tasks: live.services ?? 0 };
-                    return this._pendingSpriteRedeploy ? { ...this._pendingSpriteRedeploy } : undefined;
+                registeredSprites: (() => {
+                    // Registered sprites ride the save from wherever they are:
+                    // STANDING here (a live companion, whose services are the
+                    // truth for its task count) or WAITING in the redeploy stash
+                    // after a fold. Both sources, because a technomancer can have
+                    // some of each -- taking only one of the two lists is how a
+                    // sprite that happened to be manifest at save time would
+                    // survive while its folded sibling silently did not.
+                    const live = this.companions
+                        .filter(c => c.kind === 'sprite' && c.registered && c.spriteType)
+                        .map(c => ({ spriteType: c.spriteType, level: c.force, tasks: c.services ?? 0, name: c.npc.name }));
+                    const all = [...live, ...this._pendingSpriteRedeploy.map(s => ({ ...s }))];
+                    return all.length > 0 ? all : undefined;
                 })(),
                 crew: this.crew.map(m => ({ ...m, gear: [...m.gear] })),
                 commandRefusals: { ...this.commandRefusals },
@@ -2796,7 +3000,7 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
         // offer flow (his call, accept/decline, the taxi) works unchanged.
         // Offline owners fall back to the Phase B ghost riders below.
         let sharedDeclineNote = '';
-        if (this.hasHub && !this._anonymous) {
+        if (this.hasHub && !this._anonymous && !this._bench) {
             const srMod = await import('./utilities/shared-run.js').catch(() => undefined);
             const preferred = this.preferredDraftSessionID;
             this.preferredDraftSessionID = undefined;
@@ -4163,7 +4367,7 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
         { title: 'matrix', entries: [['jack'], ['deck'], ['load'], ['unload'], ['hack'], ['mark'], ['snoop'], ['overwatch', 'os'], ['pan'], ['ar'], ['aros'], ['silent'], ['reboot'], ['agent'], ['drone'], ['jump', 'rig']] },
         // The Emerged get their own shelf (player request: "there MUST be
         // resonance" -- matrix is the place, Resonance is the talent).
-        { title: 'resonance', entries: [['compile', 'decompile'], ['thread'], ['register']] },
+        { title: 'resonance', entries: [['compile', 'decompile'], ['thread'], ['unravel'], ['register'], ['sprites']] },
         { title: 'social', entries: [['say'], ['emote', 'me'], ['talk-to'], ['call'], ['end-call', 'end', 'hangup'], ['accept'], ['decline', 'deny', 'refuse'], ['haggle', 'negotiate'], ['persuade', 'convince'], ['ask'], ['contacts']] },
         { title: 'street', entries: [['browse', 'buy'], ['sell'], ['catalog'], ['source', 'procure'], ['work', 'gig'], ['jobs'], ['journal'], ['perform'], ['palm'], ['docwagon'], ['treat'], ['eat'], ['drink'], ['lifestyle'], ['pay']] },
         { title: 'barriers', entries: [['pick'], ['breach'], ['dispel', 'dispell'], ['bluff'], ['unlock'], ['lock']] },