@maka/maka-cli 5.133.0 → 5.135.0

package/bundle/typescript/src/commands/game/sideQuest/commands/end-turn.js

@@ -0,0 +1,58 @@
+import { Command } from './command.js';
+import { notYourPhase } from '../utilities/action-cost.js';
+/**
+ * END TURN -- committing your Action Phase (SR5 p.158-159).
+ *
+ * The Combat Turn (utilities/combat-turn.ts) hands each combatant an
+ * Action Phase in initiative order: two Simple Actions or one Complex,
+ * plus a Free. A human's phase waits for this verb. Whatever is unspent
+ * when you type it is forfeit -- the book gives no refund -- and the
+ * pass moves to the next Initiative Score. When everyone has acted,
+ * every score drops by 10 (p.159) and anyone still above zero goes
+ * again; when nobody is, a new Combat Turn rolls fresh initiative.
+ *
+ * WHAT NOW COSTS AN ACTION, swept as one family (CLAUDE.md: "partial
+ * canon is worse than either extreme"):
+ *   Free     drop prone (p.164) · drop an object (p.163) · surrender ·
+ *            release a hold · running past your Walk Rate (p.162)
+ *   Simple   draw / holster (Ready Weapon, p.165) · take cover (p.166) ·
+ *            stand up (p.166) · take aim (p.166) · fire a weapon (p.165)
+ *            · pick up an object (p.165) · equip / unequip · use a
+ *            simple device · observe in detail (search, p.165)
+ *   Complex  melee attack (p.167) · subdue / grapple · struggle free
+ *            (p.195) · cast a spell (p.167) · summon (p.167) · sprint
+ *            (p.167) · reload (p.163/167) · first aid (p.206)
+ *   Score    Full Defense -10 for the turn (p.191) · dodge / block /
+ *            parry -5 each, by "defend" policy (p.168)
+ * Movement is metres from a whole-turn budget (p.161), not an action.
+ *
+ * WHY THE WORD IS "end turn" AND NOT "end": "end" already hangs up a
+ * commlink call (commands/end-call.ts). EndCallCommand hands "end turn"
+ * / "end phase" here; "done" and "pass" are the short forms.
+ */
+export class EndTurnCommand extends Command {
+    static verb = 'end-turn';
+    static description = 'Commit your Action Phase (SR5 p.158): anything unspent is forfeit and the pass moves to the next combatant. Also "end turn", "done", "pass". "initiative" shows the order; "help end-turn" lists what each verb costs.';
+    async execute(_args = []) {
+        const actor = this.actor;
+        const enc = this.scene.encounterFor?.(actor);
+        if (!enc) {
+            return `You're not in a fight -- there's no Action Phase to end.`;
+        }
+        if (!enc.isPhaseOf(actor)) {
+            return notYourPhase(enc, actor);
+        }
+        const budget = enc.budgetOf(actor);
+        const ledger = budget?.ledger() ?? 'nothing';
+        this.logger.write(`${actor.name} ends their Action Phase (${ledger}).`);
+        if (this.scene.isHumanControlled(actor)) {
+            // Logged now rather than returned: the phases that follow announce
+            // themselves while this command is still running, and a return
+            // value would land under them, out of order.
+            this.logger.log(`{cyan-fg}You end your Action Phase${budget && budget.spent.length > 0 ? ` -- ${ledger}` : ' -- nothing spent'}.{/cyan-fg}`, { actor: actor.name });
+        }
+        await enc.endPhase(actor);
+        return this.scene.isHumanControlled(actor) ? '' : `${actor.name} ends their Action Phase.`;
+    }
+}
+//# sourceMappingURL=end-turn.js.map

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

@@ -2,12 +2,18 @@ import { Command } from './command.js';
 import { hint } from '../utilities/hints.js';
 import { Category } from '../types/shared/item-enum.js';
 import { Player } from '../models/player.js';
+import { billAction } from '../utilities/action-cost.js';
 export class EquipCommand extends Command {
     static verb = 'equip';
     static description = 'Equip an item or everything in your inventory.';
     async execute(args) {
         if (!args)
             return '';
+        // Getting gear onto your body mid-fight is a Simple Action's worth
+        // of hands (SR5 p.165 Ready Weapon / Pick Up Object).
+        const bill = billAction(this.scene, this.actor, 'simple', 'Equip');
+        if (bill)
+            return bill;
         const out = this.equip(args);
         // Worn state is sheet-visible and changes rarely, so the DURABLE
         // path carries it (maka-cli.com suggestion, 2026-09-01): an equip

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

@@ -9,6 +9,7 @@ import { heldBy, holding } from '../utilities/grapple.js';
 import { hint } from '../utilities/hints.js';
 import { fuzzyPickName } from '../utilities/fuzzy-match.js';
 import { gridIconBlock } from '../utilities/grid-view.js';
+import { requirePhase } from '../utilities/action-cost.js';
 import { camerasLive } from '../utilities/surveillance.js';
 import { maybeSinSweep } from '../utilities/sin.js';
 import { despawnEphemerals } from '../utilities/ephemeral.js';
@@ -166,6 +167,11 @@ export class GoCommand extends Command {
         if (gripHeld) {
             return `You're holding ${gripHeld.name} -- walk away and the hold is gone. "release" first if that's the plan.`;
         }
+        // THE COMBAT TURN (utilities/combat-turn.ts): leaving the room is
+        // movement, and movement happens on your own Action Phase.
+        const phase = requirePhase(this.scene, this.actor);
+        if (phase)
+            return phase;
         // No walking out from between the narration beats of a combat exchange
         // you're part of (see CombatExchange.beginExchange) -- found via a real
         // session where the player slipped rooms mid-exchange. The pause
@@ -381,6 +387,10 @@ export class GoCommand extends Command {
             const gapBlock = this.checkHostBoundary(targetRoom);
             if (gapBlock)
                 return gapBlock;
+            // Out of the fight before the room hears you go: a participant's
+            // AI chain is suspended (NPC.combatPhaseLocked), and the "exits"
+            // stimulus below is what makes a hostile give chase.
+            this.scene.encounterIn?.(currentRoom)?.leave(this.actor);
             this.actor.performAction('exits', `${this.actor.currentLocation.name} to ${targetRoom.name}`);
             this.actor.cameFrom = { room: this.actor.currentLocation.name, back: GoCommand.opposite(direction) };
             this.actor.currentLocation = targetRoom; // Update player's location
@@ -418,6 +428,7 @@ export class GoCommand extends Command {
             const gapBlock = this.checkHostBoundary(nextRoom);
             if (gapBlock)
                 return gapBlock;
+            this.scene.encounterIn?.(currentRoom)?.leave(this.actor);
             this.actor.cameFrom = { room: this.actor.currentLocation.name, back: GoCommand.opposite(direction) };
             this.actor.currentLocation = nextRoom;
             // Land IN the doorway you came through when there is one to
@@ -436,6 +447,9 @@ export class GoCommand extends Command {
             }
             this.actor.performAction('enters', `${nextRoom.name}${this.actor.atSpot ? ` (at the ${this.actor.atSpot})` : ''}`);
         }
+        // Walking into a room with a fight on joins it, late (p.160): the
+        // party and the hostile roll in; anyone else stays out until they act.
+        this.scene.admitToEncounter?.(this.actor);
         return this.finishMove(crossNote, currentRoom);
     }
     /**

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

@@ -4,6 +4,7 @@ import { rollPool, formatRoll } from '../utilities/dice.js';
 import { fuzzyPickName } from '../utilities/fuzzy-match.js';
 import { physicalLimit, heldBy, holding, releaseGrapple } from '../utilities/grapple.js';
 import { spotOf, ensureAtSpot } from '../utilities/spots.js';
+import { billAction } from '../utilities/action-cost.js';
 /**
  * SUBDUING (SR5e p.195) -- "grapple"/"restrain"/"clinch": seize someone
  * and hold them, dealing NO damage. The RAW shape, faithfully: a normal
@@ -74,6 +75,12 @@ export class GrappleCommand extends Command {
         const isPlayer = this.scene.isHumanControlled(actor);
         const lines = [];
         const meta = [];
+        // A GRAPPLE IS A MELEE ATTACK (p.195 Subduing Combat: "the attacker
+        // makes a normal melee attack"), so it is the Complex Action a melee
+        // attack is (p.167) -- and the phase's one attack (p.164).
+        const bill = billAction(this.scene, actor, 'complex', 'Grapple (Melee Attack)', { attack: true });
+        if (bill)
+            return bill;
         // Someone with their hands up doesn't resist a zip-tie: restraining a
         // surrendered target is automatic and quiet (threshold 4 to wriggle
         // out -- betraying a surrender is on them).
@@ -137,6 +144,10 @@ export class GrappleCommand extends Command {
         }
     }
     release(held) {
+        // Letting go is a Free Action (p.163 Drop Object -- opening the hand).
+        const bill = billAction(this.scene, this.actor, 'free', 'Release Hold');
+        if (bill)
+            return bill;
         releaseGrapple(held, this.actor);
         this.actor.performAction('releases', `${held.name} from the hold`);
         this.scene.updateStatus();
@@ -168,6 +179,10 @@ export class StruggleCommand extends Command {
             return `Nobody's holding you.`;
         }
         const threshold = actor.grappleThreshold ?? 2;
+        // THE ESCAPE IS A COMPLEX ACTION (p.195), spent on the attempt.
+        const bill = billAction(this.scene, actor, 'complex', 'Break Grapple');
+        if (bill)
+            return bill;
         // Two RAW roads out (p.195 Unarmed+Strength; p.135 Escape Artist,
         // Agility-linked -- the contortionist's slip vs the wrestler's
         // wrench). Whichever pool is bigger is the one they instinctively use.

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

@@ -4,6 +4,7 @@ import { formatRoll } from '../utilities/dice.js';
 import { hint } from '../utilities/hints.js';
 import { sameSpot, spotOf, spotRefusal } from '../utilities/spots.js';
 import { FIRST_AID_THRESHOLD, firstAidCap, firstAidRefusal, medkitRating, performFirstAid, } from '../utilities/first-aid.js';
+import { billAction } from '../utilities/action-cost.js';
 /**
  * HEAL -- first aid in the field (SR5 p.205-206). The mechanic is in
  * utilities/first-aid.ts; this file is the verb and its words.
@@ -84,6 +85,11 @@ export class HealCommand extends Command {
             return spotRefusal(patient.name, spotOf(patient));
         }
         const cap = firstAidCap(actor, kit);
+        // FIRST AID IS A COMPLEX ACTION (p.206) -- the action budget the
+        // class doc once said this engine lacked now exists.
+        const bill = billAction(this.scene, actor, 'complex', 'First Aid');
+        if (bill)
+            return bill;
         const result = performFirstAid(actor, patient, kit, track);
         const summary = track === 'physical' ? patient.conditionSummary() : patient.stunSummary();
         const trained = actor.skillRating('first-aid') > 0;

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

@@ -0,0 +1,20 @@
+import { Command } from './command.js';
+import { hint } from '../utilities/hints.js';
+/**
+ * THE INITIATIVE TRACKER (SR5 p.159-160): who acts when, this Combat
+ * Turn and pass, with scores, and what the live phase has spent. A
+ * reference panel, so ui.ts renders it into the Mechanics column
+ * (MENU_VERBS) rather than the world log.
+ */
+export class InitiativeCommand extends Command {
+    static verb = 'initiative';
+    static description = 'The initiative tracker: Combat Turn, Initiative Pass, every combatant\'s score and whose Action Phase is live (SR5 p.159). Also "turn", "tracker".';
+    async execute(_args = []) {
+        const enc = this.scene.encounterIn?.(this.actor.currentLocation);
+        if (!enc) {
+            return `No fight running here.${hint(` (Attacking someone opens a Combat Turn: initiative for everyone, then Action Phases in order -- "end turn" commits yours.)`)}`;
+        }
+        return enc.trackerLines().join('\n');
+    }
+}
+//# sourceMappingURL=initiative.js.map

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

@@ -2,11 +2,10 @@ import { Command } from './command.js';
 import { hint } from '../utilities/hints.js';
 import { GoCommand } from './go.js';
 import { NPC } from '../models/npc.js';
-import { Player } from '../models/player.js';
 import { Direction } from '../types/shared/direction-enum.js';
 import { Door } from '../models/door.js';
 import { fuzzyPickName } from '../utilities/fuzzy-match.js';
-import { heldBy, holding, physicalLimit } from '../utilities/grapple.js';
+import { heldBy, holding } from '../utilities/grapple.js';
 import { spotsActive, resolveSpot, spotOf, describeSpotRoster, OPEN_FLOOR, pathBetweenSpots, spotDistanceMeters, spotClimbSteps, blockingRegion, terrainRefusal, reseatOpenFloor, routeForMove, stepFrom, spotForCell, actorCell, standingRoomNear, yieldSquareToMaster, furnitureCells, approachCellFor, exitSpot, concealedFrom, revealActor, onTheFloor } from '../utilities/spots.js';
 // fallDamageDVMeters, not fallDamageDV: a climb that fell short drops
 // you from where you GOT to, which is a distance in metres, not a whole
@@ -14,6 +13,9 @@ import { spotsActive, resolveSpot, spotOf, describeSpotRoster, OPEN_FLOOR, pathB
 // do fall a level.
 import { fallDamageDVMeters, climbHitsFor, climbMetersFrom, climbSurfaceModifier, METERS_PER_CELL, METERS_PER_LEVEL, key, distanceMeters } from '../utilities/room-grid.js';
 import { rollPool, formatRoll } from '../utilities/dice.js';
+import { trailMaster } from '../utilities/companion-heel.js';
+import { spendMovementMeters, paceNote } from '../utilities/movement-cost.js';
+import { requirePhase } from '../utilities/action-cost.js';
 /**
  * "walk to <spot>" / "run to <spot>" / "sprint to <spot>" -- crossing
  * the CURRENT room to one of its "at" spots (see utilities/spots.ts;
@@ -101,9 +103,22 @@ export class MoveCommand extends Command {
         }
         return `Spots are a meat-world concern -- on the grid there is no distance at all, so "go <room>" puts your persona anywhere by name.`;
     }
+    /** Your shells trail you across the room (companion-heel.ts
+     *  trailMaster): after every in-room move they re-place themselves
+     *  beside you. An NPC mover has no Game in its context and drags
+     *  nobody. */
+    trailCompanions() {
+        if (!this.game)
+            return;
+        trailMaster(this.actor, this.game.companions);
+    }
     async execute(args = []) {
         const actor = this.actor;
         const room = actor.currentLocation;
+        // THE COMBAT TURN: you move on your own Action Phase (p.158-161).
+        const phase = requirePhase(this.scene, actor);
+        if (phase)
+            return phase;
         // (see offPlaneMoveRefusal below for why the off-plane refusals are
         // no longer one sentence shared by every plane)
         // "move to the bar" reads naturally -- strip the connective and
@@ -623,6 +638,14 @@ export class MoveCommand extends Command {
         const crossing = mine !== undefined && room.ensureGrid()
             ? spotDistanceMeters(room, mine, spot.name)
             : undefined;
+        // GROUND COSTS IN A FIGHT (p.161-162, utilities/movement-cost.ts).
+        const wasRunning = actor.isRunningThisTurn;
+        if (crossing !== undefined && crossing > 0) {
+            const spend = this.spendMeters(crossing);
+            if (spend)
+                return spend;
+        }
+        const pace = paceNote(this.scene, actor, wasRunning);
         actor.atSpot = spot.name;
         // Crossing to a named place gives up any stepped-to square: you're
         // AT the bar now, and seating puts you beside it (spots.ts).
@@ -633,6 +656,7 @@ export class MoveCommand extends Command {
         // an NPC's own spot is a social event for them (the bartender greets
         // you when you reach the bar).
         actor.performAction('moves to', `the ${spot.name}`);
+        this.trailCompanions();
         this.logger.write(`MoveCommand: ${actor.name} ${this.mode()}s to ${spot.name} in ${room.name}.`);
         // Companions drift along with their master (go.ts follow precedent).
         if (actor === this.scene.getPlayer() && this.game) {
@@ -664,16 +688,16 @@ export class MoveCommand extends Command {
         // "cross to" a place that isn't one.
         if (spot.name === OPEN_FLOOR) {
             if (toWhom) {
-                return `You step out onto the open floor where ${toWhom} stands${crossNote}.${here.length > 0 ? ` Also out here: ${here.join(', ')}.` : ''}`;
+                return `You step out onto the open floor where ${toWhom} stands${crossNote}.${here.length > 0 ? ` Also out here: ${here.join(', ')}.` : ''}${pace}`;
             }
-            return `You peel off to the open floor${crossNote} -- nobody's company but your own.${here.length > 0 ? ` Out here with you: ${here.join(', ')}.` : ''}`;
+            return `You peel off to the open floor${crossNote} -- nobody's company but your own.${here.length > 0 ? ` Out here with you: ${here.join(', ')}.` : ''}${pace}`;
         }
-        const pace = this.mode() === 'walk' ? 'cross to' : this.mode() === 'run' ? 'hustle over to' : 'sprint to';
+        const paceVerb = this.mode() === 'walk' ? 'cross to' : this.mode() === 'run' ? 'hustle over to' : 'sprint to';
         const spotDesc = spot.description ? ` ${spot.description}` : '';
         const company = toWhom
             ? `, coming up beside ${toWhom}.`
             : '.';
-        return `${descentNote ? `${descentNote} ` : ''}You ${pace} the ${spot.name}${crossNote}${company}${spotDesc}${here.length > 0 ? ` Here: ${here.join(', ')}.` : ''}`;
+        return `${descentNote ? `${descentNote} ` : ''}You ${paceVerb} the ${spot.name}${crossNote}${company}${spotDesc}${here.length > 0 ? ` Here: ${here.join(', ')}.` : ''}${pace}`;
     }
     /**
      * "move south 2" -- a tactical step across the room's own grid, as
@@ -756,12 +780,19 @@ export class MoveCommand extends Command {
                         : `there's a wall`;
             return `You can't step ${direction} -- ${why}.`;
         }
+        // Paces are metres from the turn's budget (p.161-162).
+        const wasRunning = actor.isRunningThisTurn;
+        const stepSpend = this.spendMeters(taken * METERS_PER_CELL);
+        if (stepSpend)
+            return stepSpend;
+        const stepPace = paceNote(this.scene, actor, wasRunning);
         const wasAt = actor.atSpot;
         actor.atCell = cell;
         actor.atSpot = spotForCell(room, cell);
         // A shell of yours on that square steps aside (spots.ts heelsTo).
         yieldSquareToMaster(room, actor);
         actor.performAction('steps', `${taken} ${taken === 1 ? 'pace' : 'paces'} ${direction}`);
+        this.trailCompanions();
         this.scene.updateStatus();
         this.scene.updateExits(room);
         // QUIET STEPS (user, 2026-09-01: "You step 1 pace east" is spammy now
@@ -780,69 +811,27 @@ export class MoveCommand extends Command {
         const arrived = actor.atSpot !== wasAt && actor.atSpot !== OPEN_FLOOR
             ? `You're at the ${actor.atSpot} now.`
             : '';
-        return [shortNote, arrived].filter(Boolean).join(' ');
-    }
-    /**
-     * IS THIS ACTOR IN A COMBAT TURN AT ALL?
-     *
-     * `inExchange` is only true while an exchange is being resolved, so it
-     * cannot answer "am I in a fight" between commands. `lastExchangeAt`
-     * can, and it is the predicate resolvePartingShot already uses for
-     * "engaged" -- reusing it keeps one definition of being in a fight
-     * rather than minting a second that can drift from it.
-     */
-    static FIGHT_WINDOW_MS = 60_000;
-    inCombatTurn(actor) {
-        return !!actor.combatOpponent && Date.now() - actor.lastExchangeAt < MoveCommand.FIGHT_WINDOW_MS;
+        return [shortNote, arrived, stepPace.trim()].filter(Boolean).join(' ');
     }
     /**
      * Bills a crossing against the Combat Turn's movement rate, or returns
-     * the refusal when there is not enough left (SR5 p.161-162).
+     * the refusal when there is not enough left (SR5 p.161-162). The
+     * rules -- walk free, running spends the Free Action, sprint is a
+     * Complex Action with a test -- live in utilities/movement-cost.ts,
+     * shared with the melee reach in attack.ts and the NPC brain.
      *
-     * Returns undefined -- meaning "go ahead" -- whenever this is not a
-     * combat turn, which is every ordinary walk across a bar.
+     * Returns undefined -- meaning "go ahead" -- whenever there is no
+     * Combat Turn running, which is every ordinary walk across a bar.
      */
     spendMovement(actor, to) {
-        if (!this.inCombatTurn(actor))
-            return undefined;
         const room = actor.currentLocation;
         const from = actorCell(room, actor);
         if (!from)
             return undefined;
-        const cost = distanceMeters(from, to);
-        if (cost <= 0)
-            return undefined;
-        // THE SPRINT ACTION (p.162), and this is where the engine's existing
-        // "sprint to <x>" verb finally means something mechanical. Canon
-        // makes it a Complex Action -- Running + Strength [Physical], each
-        // hit buying more ground -- so it is rolled when the player asks for
-        // it, not applied automatically to cover a shortfall.
-        //
-        // ATHLETICS, NOT RUNNING: this engine's skill list has no Running
-        // (nor Gymnastics); it collapses both into `athletics`, which
-        // resolvePartingShot already rolls for exactly this -- breaking away
-        // at a dead run. Mapping canon's skill onto the one this game has is
-        // better than inventing a skill nobody can raise.
-        if (this.mode() === 'sprint' && actor.sprintMetersThisTurn === 0) {
-            // RUNNING: sprinting is Running (p.133), and this pool already
-            // pairs it with Strength, which is the attribute canon links.
-            const skill = actor.skillRating('running');
-            const roll = rollPool(Math.max(1, skill + actor.strength + actor.bonus('athletics') + actor.woundModifier), physicalLimit(actor));
-            const bought = roll.hits * Player.SPRINT_METERS_PER_HIT;
-            actor.sprintMetersThisTurn = bought;
-            this.logger.meta(`Sprint (Running + Strength [Physical]): ${formatRoll(roll)} -- +${bought} m this turn`);
-        }
-        if (cost > actor.movementLeftMeters) {
-            const left = actor.movementLeftMeters;
-            // Name the numbers. A refusal that says only "you can't" in a
-            // system the player cannot see is the kind of wall that gets
-            // reported as a bug.
-            return left <= 0
-                ? `You've already covered your ground this turn (${actor.runRateMeters} m at a dead run). Nothing left in the legs until the next exchange.`
-                : `That's ${cost.toFixed(1)} m and you have ${left.toFixed(1)} m left this turn (Run Rate ${actor.runRateMeters} m).${hint(` ("sprint" buys more ground -- Athletics + Strength, ${Player.SPRINT_METERS_PER_HIT} m a hit.)`)}`;
-        }
-        actor.movedMetersThisTurn += cost;
-        return undefined;
+        return this.spendMeters(distanceMeters(from, to));
+    }
+    spendMeters(meters) {
+        return spendMovementMeters(this.scene, this.actor, meters, this.mode(), this.logger);
     }
     /** Closes the last few paces to someone already at your own spot --
      *  you end up beside them rather than merely in the same zone. */
@@ -867,6 +856,7 @@ export class MoveCommand extends Command {
         actor.atCell = cell;
         actor.atSpot = spotForCell(room, cell);
         actor.performAction('steps up beside', target.name);
+        this.trailCompanions();
         this.scene.updateStatus();
         this.scene.updateExits(room);
         const pace = actor.isRunningThisTurn ? ` You're running now -- everything else this turn is at -2.` : '';
@@ -1013,9 +1003,13 @@ export class MoveCommand extends Command {
         const cell = standingRoomNear(room, target, actor);
         if (!cell)
             return `There's no room to stand at the ${direction} way out.`;
+        const doorSpend = this.spendMovement(actor, cell);
+        if (doorSpend)
+            return doorSpend;
         actor.atCell = cell;
         actor.atSpot = spotForCell(room, cell);
         actor.performAction('moves to', `the ${direction} doorway`);
+        this.trailCompanions();
         this.scene.updateStatus();
         this.scene.updateExits(room);
         return `You cross to the ${direction} way out.${hint(` ("go ${direction}" to step through.)`)}`;
@@ -1041,6 +1035,9 @@ export class MoveCommand extends Command {
         const cell = standingRoomNear(room, body.cell, actor);
         if (!cell)
             return `There's no room to stand over ${body.name}.`;
+        const bodySpend = this.spendMovement(actor, cell);
+        if (bodySpend)
+            return bodySpend;
         actor.atCell = cell;
         actor.atSpot = spotForCell(room, cell);
         actor.performAction('stands over', `${body.name}'s body`);

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

@@ -2,6 +2,7 @@ import { Command } from './command.js';
 import { hint } from '../utilities/hints.js';
 import { rollPool, formatRoll } from '../utilities/dice.js';
 import { spotOf } from '../utilities/spots.js';
+import { billAction, phaseHint } from '../utilities/action-cost.js';
 /**
  * SIT, LIE DOWN, STAND UP (player request 2026-08-27: sit and lie down
  * as "moving" commands).
@@ -23,9 +24,11 @@ import { spotOf } from '../utilities/spots.js';
  * be inventing rules, which is a worse failure than a verb that is
  * merely flavour.
  *
- * The surprise clause on p.164 is not modelled -- this engine has no
- * surprise state, the same gap noted in cover.ts. Left out rather than
- * faked.
+ * The surprise clause on p.164 is modelled since the Combat Turn landed
+ * (utilities/combat-turn.ts): a character who failed the Surprise Test
+ * cannot drop prone until their next Action Phase. Both postures bill
+ * their action through action-cost.ts -- prone the phase's Free, standing
+ * a Simple.
  */
 export class PostureCommand extends Command {
     static verb = 'sit';
@@ -59,14 +62,22 @@ export class PostureCommand extends Command {
         if (want === 'standing')
             return this.standUp(here);
         if (want === 'prone') {
-            // FREE ACTION (p.164) -- costs nothing, which is exactly why it
-            // is worth doing the moment rounds start coming in.
+            // FREE ACTION (p.164) -- the phase's one Free Action, which is
+            // exactly why it is worth doing the moment rounds start coming
+            // in. "As long as he is not surprised": the encounter knows.
+            const enc = this.scene.encounterFor?.(actor);
+            if (enc?.isSurprised(actor)) {
+                return `You're caught flat-footed -- you don't even get to hit the dirt (SR5 p.164, p.192).`;
+            }
+            const bill = billAction(this.scene, actor, 'free', 'Drop Prone');
+            if (bill)
+                return bill;
             actor.posture = 'prone';
             actor.performAction('drops prone', where ?? actor.currentLocation.name);
             this.scene.updateStatus?.();
             return `You go flat${here}.`
                 + `\n  {green-fg}PRONE:{/green-fg} +2 harder to hit at range, but -2 to defend up close and -1 swinging from the floor.`
-                + hint(` ("stand" to get back up -- a Simple Action.)`);
+                + hint(` ("stand" to get back up -- a Simple Action.)`) + phaseHint(this.scene, actor);
         }
         actor.posture = 'sitting';
         actor.performAction('sits down', where ?? actor.currentLocation.name);
@@ -76,6 +87,11 @@ export class PostureCommand extends Command {
     /** STAND UP: a Simple Action, and a real test when you're hurt. */
     standUp(here) {
         const actor = this.actor;
+        // The SIMPLE ACTION (p.166) is spent on the attempt: a wounded
+        // character who fails the test has still used it trying.
+        const bill = billAction(this.scene, actor, 'simple', 'Stand Up');
+        if (bill)
+            return bill;
         const wounded = actor.woundModifier < 0;
         if (wounded) {
             // p.166: "if the character is wounded and attempting to stand, he
@@ -95,7 +111,7 @@ export class PostureCommand extends Command {
         actor.posture = 'standing';
         actor.performAction('stands up', here.trim() || actor.currentLocation.name);
         this.scene.updateStatus?.();
-        return wounded ? `You drag yourself upright${here}.` : `You get to your feet${here}.`;
+        return (wounded ? `You drag yourself upright${here}.` : `You get to your feet${here}.`) + phaseHint(this.scene, actor);
     }
 }
 /** "lie"/"lie down"/"prone" -- same command, different way in. */

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

@@ -1,17 +1,25 @@
 import { Command } from './command.js';
 import { Category } from '../types/shared/item-enum.js';
 import { Item } from '../models/item.js';
+import { billAction, encounterOf, phaseHint } from '../utilities/action-cost.js';
 /**
  * Refills the equipped firearm's magazine by consuming one
- * Ammunition-category item from the pack. Firearms hold
- * Item.MAGAZINE_CAPACITY rounds and every shot (retaliation included)
- * spends one -- see combat-exchange.ts. Reloading mid-fight is allowed
- * (the between-exchanges pause is exactly the window for it), just not
- * mid-exchange.
+ * Ammunition-category item from the pack. Every shot spends a round --
+ * see combat-exchange.ts.
+ *
+ * WHAT A RELOAD COSTS IN A COMBAT TURN (SR5 p.163 Reloading Weapons,
+ * p.165-167, RAG-checked 2026-09-06): a clip is Remove Clip (Simple) +
+ * Insert Clip (Simple) -- both of a phase's Simple Actions; every other
+ * feed (cylinder, break action, belt, drum, internal magazine, muzzle
+ * loader, speed loader) is a Complex Action. Either way it is the whole
+ * phase, so it is billed as one. The one discount canon gives: a
+ * smartgun linked to a smartlink ejects its clip as a Free Action
+ * (p.164 Eject Smartgun Clip), leaving only the Simple to seat the new
+ * one.
  */
 export class ReloadCommand extends Command {
     static verb = 'reload';
-    static description = 'Reload your equipped firearm -- consumes one Ammunition item from your pack.';
+    static description = 'Reload your equipped firearm -- consumes one Ammunition item from your pack. In a fight it takes the whole Action Phase (Remove Clip + Insert Clip, SR5 p.163), or a Free + a Simple with a smartgun you\'re linked to (p.164).';
     async execute(_args = []) {
         const actor = this.actor;
         if (this.scene.isHumanControlled(actor) && this.scene.isPlayerExchangeActive(actor.name)) {
@@ -21,15 +29,28 @@ export class ReloadCommand extends Command {
         if (!weapon || !weapon.isFirearm()) {
             return `You have no firearm equipped to reload.`;
         }
-        if (weapon.ammo >= Item.MAGAZINE_CAPACITY) {
-            return `The ${weapon.name} is already fully loaded (${weapon.ammo}/${Item.MAGAZINE_CAPACITY}).`;
+        if (weapon.ammo >= weapon.magazineCapacity) {
+            return `The ${weapon.name} is already fully loaded (${weapon.ammo}/${weapon.magazineCapacity}).`;
         }
         // NON-LETHAL STANCE: stun rounds first if you carry any (gel,
         // stick-n-shock -- p.434); otherwise whatever is in the pack.
         const boxes = actor.inventory.getAllItems().filter(i => i.category === Category.Ammunition);
         const ammo = (actor.autoStance === 'non-lethal' ? boxes.find(b => Item.isStunAmmo(b)) : undefined) ?? boxes[0];
         if (!ammo) {
-            return `No ammunition in your pack -- the ${weapon.name} stays at ${weapon.ammo}/${Item.MAGAZINE_CAPACITY}. Find a spare clip.`;
+            return `No ammunition in your pack -- the ${weapon.name} stays at ${weapon.ammo}/${weapon.magazineCapacity}. Find a spare clip.`;
+        }
+        // THE ACTION (see the class doc). A reload also needs the gun in
+        // hand: "insert a fresh clip into a READY firearm" (p.165).
+        if (encounterOf(this.scene, actor)) {
+            if (!actor.weaponDrawn) {
+                return `The ${weapon.name} is holstered -- "draw" it first (Ready Weapon, a Simple Action, p.165).`;
+            }
+            const smartEject = weapon.isSmartgun && actor.smartlinkTier() !== undefined;
+            const bill = smartEject
+                ? (billAction(this.scene, actor, 'free', 'Eject Smartgun Clip') ?? billAction(this.scene, actor, 'simple', 'Insert Clip'))
+                : billAction(this.scene, actor, 'complex', weapon.reloadFeed === 'c' ? 'Remove Clip + Insert Clip' : 'Reload Weapon');
+            if (bill)
+                return bill;
         }
         actor.inventory.consumeOne(ammo.name);
         weapon.reload(ammo.name);
@@ -37,7 +58,7 @@ export class ReloadCommand extends Command {
         this.actor.performAction('reloads', weapon.name);
         this.scene.updateInventory(this.scene.getPlayer().inventory);
         this.scene.updateStatus();
-        return `You slap the ${ammo.name} home -- ${weapon.name} loaded, ${weapon.ammo}/${Item.MAGAZINE_CAPACITY}.${weapon.stunAmmo() ? ' Stun rounds: it drops people, it does not kill them.' : actor.autoStance === 'non-lethal' ? ' No stun rounds in the pack -- that gun is LETHAL until you find some.' : ''}`;
+        return `You slap the ${ammo.name} home -- ${weapon.name} loaded, ${weapon.ammo}/${weapon.magazineCapacity}.${weapon.stunAmmo() ? ' Stun rounds: it drops people, it does not kill them.' : actor.autoStance === 'non-lethal' ? ' No stun rounds in the pack -- that gun is LETHAL until you find some.' : ''}${phaseHint(this.scene, actor)}`;
     }
 }
 //# sourceMappingURL=reload.js.map

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

@@ -5,6 +5,7 @@ import { rollPool, formatRoll } from '../utilities/dice.js';
 import { perceptionTest } from '../utilities/perception.js';
 import { canReach, exitSpot, spotsActive, revealWithPerception, theSpot, sealedRouteTo, } from '../utilities/spots.js';
 import { placeName } from '../utilities/log-style.js';
+import { billAction } from '../utilities/action-cost.js';
 /**
  * Barrier rendering (2026-08-24 playtest: "I don't see THE THING I'm
  * supposed to act on -- just a description... and I still see the
@@ -136,6 +137,11 @@ export class SearchCommand extends Command {
     static description = 'Search for items in your area';
     async execute(_args) {
         const room = this.actor.currentLocation;
+        // OBSERVE IN DETAIL (SR5 p.165): the Perception Test below is the
+        // Simple Action the book names, inside a Combat Turn.
+        const bill = billAction(this.scene, this.actor, 'simple', 'Observe in Detail');
+        if (bill)
+            return bill;
         // Searching is a PERCEPTION test now (Intuition + perception skill;
         // unskilled defaults to Intuition - 1): no hits means the room keeps
         // its secrets this pass -- retry freely, but until a roll lands the

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

@@ -1,6 +1,7 @@
 import { Command } from './command.js';
 import { rollPool, formatRoll } from '../utilities/dice.js';
 import { hint } from '../utilities/hints.js';
+import { billAction } from '../utilities/action-cost.js';
 /**
  * Conjuring (SR5e p.300-303): "summon <force>" calls a spirit -- an
  * opposed Magic + conjuring test against the spirit's Force dice. NET
@@ -50,6 +51,10 @@ export class SummonCommand extends Command {
             return `A Force ${force} spirit would wear YOU as the vessel -- twice your Magic (${actor.magic * 2}) is the hard ceiling.`;
         }
         const overcast = force > actor.magic;
+        // SUMMONING IS A COMPLEX ACTION (SR5 p.167) inside a Combat Turn.
+        const bill = billAction(this.scene, actor, 'complex', 'Summoning');
+        if (bill)
+            return bill;
         // The opposed test (p.300): Magic + conjuring vs the spirit's Force.
         const conjuring = actor.skillRating('conjuring');
         const mine = rollPool(Math.max(1, actor.magic + (conjuring > 0 ? conjuring : -1) + actor.woundModifier - actor.sustainingPenalty));

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

@@ -1,4 +1,5 @@
 import { Command } from './command.js';
+import { billAction } from '../utilities/action-cost.js';
 /**
  * Throwing your hands up, as a real mechanical act instead of just talk.
  * The wound-aware AI guidance already nudges a losing NPC toward
@@ -27,6 +28,11 @@ export class SurrenderCommand extends Command {
         if (actor.inExchange) {
             return `Lead is flying -- wait for the exchange to resolve, then surrender in the lull.`;
         }
+        // Hands up is a gesture and a phrase -- a Free Action (SR5 p.164
+        // Gesture / Speak) in a Combat Turn.
+        const bill = billAction(this.scene, actor, 'free', 'Surrender');
+        if (bill)
+            return bill;
         actor.surrendered = true;
         // Break the fight both ways: no parting shot for walking away from a
         // surrender, and the opponent's own combat memory of you clears too.