@maka/maka-cli 5.134.0 → 5.135.0

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

@@ -6,6 +6,7 @@ import { ensureAtSpot, ensureAtExit } from '../utilities/spots.js';
 import { applyDeviceOpened } from '../utilities/devices.js';
 import { hint } from '../utilities/hints.js';
 import { FIRST_AID_THRESHOLD, firstAidCap, firstAidRefusal, performFirstAid, } from '../utilities/first-aid.js';
+import { billAction } from '../utilities/action-cost.js';
 export class UseCommand extends Command {
     static verb = 'use';
     static description = 'Use a thing: an item from your pack (a medkit, a stim patch), or a device in the room -- "use keypad 4471" offers a code, "use safe" tries it with what you are carrying. With one device here, a bare code works too.';
@@ -16,6 +17,13 @@ export class UseCommand extends Command {
     preferredCategory;
     verbNoun = 'use';
     async execute(args) {
+        // USE SIMPLE DEVICE (SR5 p.166-167): a Simple Action in a Combat
+        // Turn -- a medkit's first aid is the Complex Action heal.ts charges,
+        // but the thing this verb does with one is "use the kit", which the
+        // book prices as a Simple Action of the device.
+        const bill = billAction(this.scene, this.actor, 'simple', 'Use Simple Device');
+        if (bill)
+            return bill;
         return this.use(args);
     }
     /**

package/bundle/typescript/src/commands/game/sideQuest/engine-version.js

@@ -359,5 +359,15 @@
 //   beside you (companion-heel.ts trailMaster) -- they used to heel only on
 //   a room change and sat in the doorway while you paced. "recall" judges
 //   "already at your side" by cells, not spot names.
-export const ENGINE_VERSION = '1.39.0';
+// 1.40.0 (2026-09-06): THE COMBAT TURN (SR5 p.158-168). Physical-plane
+//   combat is a turn/pass loop per room (utilities/combat-turn.ts):
+//   initiative for everyone, Action Phases in order, -10 per pass, fresh
+//   rolls per Combat Turn. COMMAND SEMANTICS in shared scenes: "attack"
+//   is one strike on your own phase (no retaliation, no auto-draw); new
+//   verbs end-turn/done/pass, initiative, aim, defend, delay; draw,
+//   holster, cover, stand, reload, take, drop, equip, use, search,
+//   grapple, struggle, release, cast, summon, dispel, heal and movement
+//   are refused outside your Action Phase and spend its Free/Simple/
+//   Complex budget. NPC participants act by rule, not by the LLM chain.
+export const ENGINE_VERSION = '1.40.0';
 //# sourceMappingURL=engine-version.js.map

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

@@ -74,6 +74,11 @@ import { GiveCommand } from './commands/give.js';
 import { ReadCommand } from './commands/read.js';
 import { KillCommand } from './commands/kill.js';
 import { AttackCommand } from './commands/attack.js';
+import { EndTurnCommand } from './commands/end-turn.js';
+import { InitiativeCommand } from './commands/initiative.js';
+import { AimCommand } from './commands/aim.js';
+import { DefendCommand } from './commands/defend.js';
+import { DelayCommand } from './commands/delay.js';
 import { SpellsCommand } from './commands/spells.js';
 import { InventoryCommand } from './commands/inv.js';
 import { EquipmentCommand } from './commands/equipment.js';
@@ -2528,6 +2533,18 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
         // wanted to end a call -- the intent is unambiguous mid-call.
         CommandFactory.registerCommand('end', EndCallCommand);
         CommandFactory.registerCommand('hangup', EndCallCommand);
+        // THE COMBAT TURN (utilities/combat-turn.ts). "end turn" arrives
+        // through EndCallCommand ("end" is the hangup) and is handed here.
+        CommandFactory.registerCommand('end-turn', EndTurnCommand);
+        CommandFactory.registerCommand('endturn', EndTurnCommand);
+        CommandFactory.registerCommand('done', EndTurnCommand);
+        CommandFactory.registerCommand('pass', EndTurnCommand);
+        CommandFactory.registerCommand('initiative', InitiativeCommand);
+        CommandFactory.registerCommand('tracker', InitiativeCommand);
+        CommandFactory.registerCommand('turn', InitiativeCommand);
+        CommandFactory.registerCommand('aim', AimCommand);
+        CommandFactory.registerCommand('defend', DefendCommand);
+        CommandFactory.registerCommand('delay', DelayCommand);
         // 'train' used to alias advance; it belongs to crew instruction now
         // (commands/crew.ts) -- self-training is "advance".
         CommandFactory.registerCommand('advance', AdvanceCommand);
@@ -5305,6 +5322,12 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
         // throws, least of all on the panel a dying player is reading.
         const docwagon = this.docwagonSlot(this.docwagonByPlayer?.get(player.name) ?? (player === this.player ? this.docwagon : undefined));
         lines.push(`${armorNote}${arSlot}  |  ${link}  |  ${docwagon}`);
+        // THE COMBAT TURN (utilities/combat-turn.ts): whose phase it is, the
+        // score, and what this player has left to spend -- present only
+        // while a fight is on, like every transient line below.
+        const combatLine = this.scene?.encounterFor?.(player)?.hudLine(player);
+        if (combatLine)
+            lines.push(combatLine);
         // Lines 4+: transient states, present only while active. Future
         // contexts (astral projection, VR hot-sim) join here the same way.
         // THE COST IS THE ENGINE'S. Every one of these lines printed a
@@ -5988,7 +6011,7 @@ ${client.name} won't be remembering anything. Dead Johnsons pay nothing -- and t
     static HELP_CATEGORIES = [
         { title: 'moving', entries: [['look'], ['go'], ['move', 'walk', 'approach'], ['run'], ['sprint'], ['climb', 'mantle', 'scale', 'clamber'], ['descend'], ['sit', 'kneel'], ['lie', 'prone'], ['stand'], ['follow'], ['unfollow'], ['map', 'exits'], ['search'], ['sneak']] },
         { title: 'gear', entries: [['inv', 'inventory'], ['equipment', 'eq'], ['take'], ['loot'], ['drop'], ['give'], ['store'], ['open'], ['close'], ['put'], ['equip'], ['unequip'], ['fit'], ['unfit'], ['brandish', 'draw'], ['holster'], ['reload'], ['use'], ['read']] },
-        { title: 'combat', entries: [['attack'], ['kill'], ['subdue'], ['grapple', 'restrain', 'clinch'], ['struggle'], ['release'], ['cover'], ['stance'], ['surrender'], ['edge'], ['rest'], ['heal', 'firstaid', 'bandage', 'patch']] },
+        { title: 'combat', entries: [['attack'], ['kill'], ['subdue'], ['grapple', 'restrain', 'clinch'], ['struggle'], ['release'], ['cover'], ['aim'], ['defend'], ['delay'], ['end-turn', 'endturn', 'done', 'pass'], ['initiative', 'tracker', 'turn'], ['stance'], ['surrender'], ['edge'], ['rest'], ['heal', 'firstaid', 'bandage', 'patch']] },
         // The party layer: everyone who walks (or flies, or manifests) at
         // your side answers to these.
         // "players" folded back under crew after playtesting ("crew

package/bundle/typescript/src/commands/game/sideQuest/headless-harness.js

@@ -244,6 +244,8 @@ export function paritySeed(overrides = {}) {
 export async function bootSession(opts = {}) {
     process.env.MAKA_NO_DDP = '1';
     process.env.MAKA_NO_LORE = '1';
+    // Combat narration beats are pacing for a person; a harness has none.
+    process.env.MAKA_NO_BEATS = '1';
     process.env.MAKA_NO_TELEMETRY = '1';
     const events = opts.events;
     const session = await createHeadlessSession({

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

@@ -95,12 +95,29 @@ export class Item extends AbstractItem {
                     break;
             }
         }
-        // Firearms track ammunition: a flat magazine, starting full. Melee
-        // weapons never touch it. See fireRound()/reload() and combat-exchange.
+        // Firearms track ammunition: the row's magazine when it has one,
+        // the flat default otherwise, starting full. Melee weapons never
+        // touch it. See fireRound()/reload() and combat-exchange.
         if (this.isFirearm()) {
-            this.ammo = Item.MAGAZINE_CAPACITY;
+            this.ammo = this.magazineCapacity;
         }
     }
+    /**
+     * ROUNDS IN A FULL MAGAZINE: the catalog row's "ammo" (p.421-431 --
+     * 15(c) for a Predator, 6(cy) for a revolver) when the row carries
+     * one, else the engine's flat default for generated gear.
+     */
+    get magazineCapacity() {
+        const rounds = this.row?.weapon?.ammo?.rounds;
+        return rounds && rounds > 0 ? rounds : Item.MAGAZINE_CAPACITY;
+    }
+    /** How it reloads (p.163 Reloading Weapons): 'c' clip, 'cy' cylinder,
+     *  'm' internal magazine, 'b' break action, 'd' drum, 'belt', 'ml'
+     *  muzzle loader. A clip is two Simple Actions; everything else a
+     *  Complex. Unknown gear reloads like a clip. */
+    get reloadFeed() {
+        return this.row?.weapon?.ammo?.feed ?? 'c';
+    }
     // ======================== Stacking ========================
     /**
      * WHAT FUNGIBLE MEANS HERE (user ruling): only CONSUMABLES stack.
@@ -200,7 +217,7 @@ export class Item extends AbstractItem {
     loadedAmmo;
     reload(ammoName) {
         if (this.isFirearm()) {
-            this.ammo = Item.MAGAZINE_CAPACITY;
+            this.ammo = this.magazineCapacity;
             if (ammoName !== undefined)
                 this.loadedAmmo = ammoName;
         }

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

@@ -909,6 +909,38 @@ description text.`;
             this.logger.write(`AI fallback for appearance (${this.name}): ${err}`);
         }
     }
+    /**
+     * IN A FIGHT, THE TURN LOOP OWNS THIS SHELL (utilities/combat-turn.ts).
+     * While this NPC is a participant in a running encounter, its LLM
+     * chain -- act, respondTo, recursiveReflect -- is suspended: the
+     * deterministic brain (utilities/npc-combat-brain.ts) plays its Action
+     * Phases in initiative order, and a model answering on its own clock
+     * would only be refused by the phase gate and grind to a halt on the
+     * refusals. Perception (see/hear) still records history, so the shell
+     * knows what happened when the chain resumes after the fight.
+     */
+    combatPhaseLocked() {
+        return !!this._scene?.encounterFor?.(this);
+    }
+    /**
+     * One verb, executed now, no reflection -- the brain's way of acting
+     * inside an Action Phase. Returns the command's own result so the
+     * brain can read a refusal, and files it into history like any act.
+     */
+    async actInCombat(commandString) {
+        if (this.deathClaimed)
+            return '';
+        const parsed = await this.commandRegistry.parse(commandString, this);
+        if (!parsed) {
+            this.logger.error(`${this.name} (combat) tried to perform unknown command: ${commandString}`);
+            return '';
+        }
+        const result = await parsed.command.execute(parsed.args);
+        if (result)
+            this._addToHistory(result);
+        this.relayToMaster(commandString, result);
+        return result ?? '';
+    }
     async act(commandString) {
         // A removed actor must STOP: dismissal/death happens while an AI
         // burst is still in flight, and without this latch a real session's
@@ -918,6 +950,10 @@ description text.`;
             this.logger.write(`${this.name} is gone from the world -- dropping queued action "${commandString}".`);
             return;
         }
+        if (this.combatPhaseLocked()) {
+            this.logger.write(`${this.name} is in a Combat Turn -- the turn loop acts for them; dropping "${commandString}".`);
+            return;
+        }
         const parsed = await this.commandRegistry.parse(commandString, this);
         if (parsed) {
             // Capture the result of the command
@@ -1361,6 +1397,10 @@ description text.`;
             this.logger.write(`${this.name} is gone from the world -- reflect chain ends.`);
             return;
         }
+        if (this.combatPhaseLocked()) {
+            this.logger.write(`${this.name} is in a Combat Turn -- reflect chain yields to the turn loop.`);
+            return;
+        }
         // THE GRIND BREAKER. Record what just happened, then refuse to keep
         // going round on it. Deterministic on purpose: the prompt already
         // asks for honesty about failure and got it -- what it lacked was
@@ -1538,6 +1578,10 @@ ${worldEventsSummary}
             : [];
     }
     async respondTo(actor, message) {
+        if (this.combatPhaseLocked()) {
+            this.logger.write(`${this.name} is in a Combat Turn -- no AI reaction to "${message.slice(0, 40)}".`);
+            return;
+        }
         this.logger.write('Attempting to respond');
         // A fresh stimulus earns at most one fresh speech (see the field doc)
         // -- and a clean slate of attempts. Something new has happened, so

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

@@ -229,6 +229,39 @@ export class Player extends AbstractPlayer {
     rallyInitBonus = 0;
     directedDice = 0;
     inspiredGuardDice = 0;
+    // ==================== THE ACTION PHASE (utilities/combat-turn.ts) ====
+    //
+    // TAKE AIM (SR5 p.166): +1 die per Simple Action spent aiming, up to
+    // half Willpower rounded up, on the NEXT attack -- and lost the moment
+    // "any other kind of action (including a Free Action)" is taken first.
+    // Cleared by action-cost.ts on every non-aim spend, by the encounter
+    // at every phase boundary, and consumed by the strike that uses it.
+    aimBonus = 0;
+    aimTarget;
+    clearAim() {
+        this.aimBonus = 0;
+        this.aimTarget = undefined;
+    }
+    /** p.166: the cap on sequential Take Aim bonuses. */
+    get aimCap() {
+        return Math.max(1, Math.ceil(this.willpower / 2));
+    }
+    // PROGRESSIVE RECOIL (p.175-176): the rounds fired keep counting across
+    // Action Phases and Combat Turns until a phase goes by without a shot.
+    // firedThisPhase is the encounter's evidence for that reset.
+    recoilRoundsFired = 0;
+    firedThisPhase = false;
+    /**
+     * THE STANDING ANSWER TO "SOMEONE IS SHOOTING AT YOU" (p.168, p.191).
+     * Interrupt actions are declared in response to an attack, outside
+     * the defender's own phase. A terminal cannot prompt mid-pass -- and
+     * a hosted table cannot wait on one player's keystroke -- so the
+     * player sets a policy ("defend dodge") that the engine applies when
+     * an attack comes in and the Initiative Score can pay for it. Full
+     * Defense is different: declared once, -10, and it lasts the turn
+     * (CombatEncounter.declareFullDefense).
+     */
+    defensePolicy = 'none';
     // Set by the "surrender" command: this actor has thrown their hands up.
     // Cleared the moment they initiate violence again (see
     // CombatExchange.beginExchange). Guarded auto-fight honors it;

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

@@ -6,6 +6,7 @@ import { hint } from '../utilities/hints.js';
 import { Category, Size, Rating } from '../types/shared/item-enum.js';
 import { AbstractScene } from '../types/shared/abstracts.js';
 import { rollPool, formatRoll } from '../utilities/dice.js';
+import { CombatEncounter } from '../utilities/combat-turn.js';
 export class Scene extends AbstractScene {
     story;
     // SYMMETRIC PLAYERS: the scene holds a LIST of human players --
@@ -129,6 +130,96 @@ export class Scene extends AbstractScene {
     // meaning -- begin/end act on the primary player, the query asks
     // "is ANY human's exchange live".
     _playerExchangesActive = new Set();
+    // ==================== COMBAT ENCOUNTERS (utilities/combat-turn.ts) ====
+    //
+    // One Combat Turn structure per ROOM: the fight in the loading bay and
+    // the fight in the office are two initiative orders, as they would be
+    // at a table. An encounter holds the participants, their scores and
+    // whose Action Phase is live; the scene only owns the map.
+    encounters = new Map();
+    /** The live fight in a room, if any. */
+    encounterIn(room) {
+        if (!room)
+            return undefined;
+        const enc = this.encounters.get(room);
+        return enc && !enc.ended ? enc : undefined;
+    }
+    /** The fight this actor is a participant in, if any. */
+    encounterFor(actor) {
+        const enc = this.encounterIn(actor.currentLocation);
+        return enc?.has(actor) ? enc : undefined;
+    }
+    /**
+     * Who is in the fight when `aggressor` opens on `target`: the two of
+     * them, every human and bound shell in the room (the party fights as
+     * one), every NPC flagged hostile, and anyone already engaged with
+     * either. A bystander is scenery; a bartender is not opposition until
+     * someone makes them so (noteAttack pulls them in then).
+     */
+    encounterMembers(room, aggressor, target) {
+        const out = new Set([aggressor]);
+        if (target)
+            out.add(target);
+        for (const a of room.getActors()) {
+            if (a === aggressor || a === target)
+                continue;
+            if (!a.sharesCombatPlane(aggressor) || a.isIncapacitated())
+                continue;
+            const npc = a;
+            if (npc.ephemeral?.kind === 'bystander')
+                continue;
+            const party = this.isHumanControlled(a) || !!npc.allyOf;
+            const hostile = !this.isHumanControlled(a) && npc.hostile === true && !npc.allyOf;
+            const engaged = !!a.combatOpponent && (a.combatOpponent === aggressor || a.combatOpponent === target);
+            if (party || hostile || engaged)
+                out.add(a);
+        }
+        return [...out];
+    }
+    /**
+     * Opens a fight in a room -- or renews the one already running there.
+     * Resolves once the first pass has run up to a human's Action Phase
+     * (or the fight has already ended).
+     */
+    async startEncounter(room, opts) {
+        const existing = this.encounterIn(room);
+        if (existing) {
+            if (opts.target)
+                existing.noteAttack(opts.aggressor, opts.target);
+            else if (!existing.has(opts.aggressor))
+                existing.join(opts.aggressor);
+            return existing;
+        }
+        const enc = new CombatEncounter(this, this.logger, room);
+        this.encounters.set(room, enc);
+        enc.onHumanPhase = (p, e) => this.game?.autoFight?.onPhaseBegins?.(p, e);
+        await enc.start(this.encounterMembers(room, opts.aggressor, opts.target), opts);
+        return enc;
+    }
+    /** The encounter is over (called by the encounter itself). */
+    endEncounter(enc) {
+        if (this.encounters.get(enc.room) === enc)
+            this.encounters.delete(enc.room);
+    }
+    /**
+     * Someone walks into a room where a fight is on (p.160 entering
+     * combat late): the party and the hostile join it; anyone else stays
+     * out until they act.
+     */
+    admitToEncounter(actor) {
+        const enc = this.encounterIn(actor.currentLocation);
+        if (!enc || enc.has(actor) || actor.isIncapacitated())
+            return undefined;
+        const npc = actor;
+        const party = this.isHumanControlled(actor) || !!npc.allyOf;
+        const hostile = !this.isHumanControlled(actor) && npc.hostile === true && !npc.allyOf;
+        if (!party && !hostile)
+            return undefined;
+        if (!enc.participants.some(p => p.actor.sharesCombatPlane(actor)))
+            return undefined;
+        enc.join(actor);
+        return enc;
+    }
     beginPlayerExchange(playerName) {
         this._playerExchangesActive.add(playerName ?? this.player.name);
     }
@@ -491,6 +582,13 @@ export class Scene extends AbstractScene {
         // map was never cleaned on removal, leaving a dead Room reference.
         this.characterLocations.delete(name);
         this.logger.write(`Removed actor: ${name}`);
+        // A fallen participant's Action Phase, if it was live, moves on;
+        // the encounter itself re-checks who is still standing on its next
+        // step (utilities/combat-turn.ts run).
+        const enc = room ? this.encounterIn(room) : undefined;
+        if (enc && enc.phaseActor === actor) {
+            void enc.dropPhaseActor(actor);
+        }
         // Tell the Game an actor left the world -- the companion roster
         // (Game.onActorRemoved) prunes shells and settles their bound
         // devices (a wrecked frame, a bricked deck).

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

@@ -26,6 +26,9 @@ const MENU_VERBS = new Set([
     // The sprite database reads like the spellbook, so it rides the same
     // panel -- reference you consult, not a menu you spend from.
     'sprites',
+    // The initiative tracker (commands/initiative.ts) is a reference
+    // panel too: who acts when, this Combat Turn.
+    'initiative', 'tracker', 'turn',
 ]);
 // Windows Terminal draws astral-plane emoji (📞 call icon, 📍 HUD pin,
 // 👥 companions, 💀) TWO columns wide, but blessed's 2015-era unicode

package/bundle/typescript/src/commands/game/sideQuest/utilities/action-budget.js

@@ -0,0 +1,87 @@
+export class ActionBudget {
+    /** Free Actions left this phase (one, p.158). */
+    free = 1;
+    /** Simple Actions left. A Complex Action spends both at once. */
+    simple = 2;
+    /** Whether an attack action has been taken this phase (p.164). */
+    attackTaken = false;
+    /** Everything spent so far, in order, for the tracker. */
+    spent = [];
+    /** A Complex Action needs the whole phase: both Simples unspent. */
+    get complexAvailable() {
+        return this.simple === 2;
+    }
+    /** Nothing left but to end the turn. */
+    get exhausted() {
+        return this.simple === 0 && this.free === 0;
+    }
+    /** The Simple/Complex half is spent -- only a Free Action remains. */
+    get actionsExhausted() {
+        return this.simple === 0;
+    }
+    /**
+     * Why this spend would be refused, or undefined when it is affordable.
+     * Checking never spends; spend() calls this first.
+     */
+    refusalFor(kind, attack = false) {
+        if (kind === 'free') {
+            if (this.free <= 0)
+                return `You've already used your Free Action this Action Phase (SR5 p.158 -- one per phase).`;
+            return undefined;
+        }
+        if (attack && this.attackTaken) {
+            return `You've already attacked this Action Phase -- only one of its actions can be an attack (SR5 p.164). "end turn" and go again next pass.`;
+        }
+        if (kind === 'simple') {
+            if (this.simple <= 0) {
+                return `You've spent both Simple Actions this Action Phase (SR5 p.163)${this.spentComplex() ? ' -- a Complex Action takes the whole phase (p.167)' : ''}. "end turn" to let the next combatant act.`;
+            }
+            return undefined;
+        }
+        // complex
+        if (!this.complexAvailable) {
+            return this.simple === 0
+                ? `Nothing left this Action Phase -- a Complex Action needs the whole phase (SR5 p.167). "end turn".`
+                : `A Complex Action takes the WHOLE Action Phase (SR5 p.167), and you've already spent a Simple Action. Use the other Simple, or "end turn".`;
+        }
+        return undefined;
+    }
+    /** Spends the action; returns the refusal instead when it cannot be paid. */
+    spend(kind, label, attack = false) {
+        const refusal = this.refusalFor(kind, attack);
+        if (refusal)
+            return refusal;
+        if (kind === 'free')
+            this.free -= 1;
+        else if (kind === 'simple')
+            this.simple -= 1;
+        else
+            this.simple = 0;
+        if (attack)
+            this.attackTaken = true;
+        this.spent.push({ kind, label, attack: attack || undefined });
+        return undefined;
+    }
+    spentComplex() {
+        return this.spent.some(s => s.kind === 'complex');
+    }
+    /** One line for the HUD: what is still on the table. */
+    describe() {
+        const parts = [];
+        if (this.simple === 2)
+            parts.push('2 Simple (or 1 Complex)');
+        else if (this.simple === 1)
+            parts.push('1 Simple');
+        else
+            parts.push('no Simple/Complex left');
+        parts.push(this.free > 0 ? '1 Free' : 'no Free');
+        return parts.join(' · ');
+    }
+    /** The phase's ledger, e.g. "Ready Weapon (Simple), Fire (Simple, attack)". */
+    ledger() {
+        if (this.spent.length === 0)
+            return 'nothing yet';
+        return this.spent.map(s => `${s.label} (${s.kind === 'free' ? 'Free' : s.kind === 'simple' ? 'Simple' : 'Complex'}${s.attack ? ', attack' : ''})`).join(', ');
+    }
+}
+//# sourceMappingURL=action-budget.js.map

package/bundle/typescript/src/commands/game/sideQuest/utilities/action-cost.js

@@ -0,0 +1,66 @@
+import { hint } from './hints.js';
+/** The encounter this actor is fighting in, if any. */
+export function encounterOf(scene, actor) {
+    return scene.encounterFor?.(actor);
+}
+/**
+ * The refusal when it is not this actor's Action Phase -- the wording
+ * every verb shares, so a player learns one sentence.
+ */
+export function notYourPhase(enc, actor) {
+    const who = enc.phaseActor;
+    if (who && who !== actor) {
+        return `It's ${who.name}'s Action Phase -- yours comes round at Initiative ${enc.scoreOf(actor)}.${hint(` ("initiative" shows the order.)`)}`;
+    }
+    return `The pass is resolving -- your Action Phase comes round at Initiative ${enc.scoreOf(actor)}.`;
+}
+/**
+ * Pays for an action, or explains why it cannot be paid. Undefined means
+ * "go ahead" -- out of combat, or in combat with the action affordable
+ * and now spent.
+ */
+export function billAction(scene, actor, kind, label, opts = {}) {
+    const enc = encounterOf(scene, actor);
+    if (!enc || enc.ended)
+        return undefined;
+    if (!enc.isPhaseOf(actor))
+        return notYourPhase(enc, actor);
+    const budget = enc.budgetOf(actor);
+    if (!budget)
+        return notYourPhase(enc, actor);
+    const refusal = budget.spend(kind, label, opts.attack === true);
+    if (refusal)
+        return refusal;
+    // p.166: aiming is lost "if the character takes any other kind of
+    // action (including a Free Action) before attacking". An attack
+    // consumes the bonus at the roll (combat-exchange.ts), so it is left
+    // in place here for the strike to read.
+    if (!opts.aiming && !opts.attack)
+        actor.clearAim();
+    scene.updateStatus?.();
+    return undefined;
+}
+/**
+ * A verb that is refused outright mid-fight unless it is your phase --
+ * for things that are not actions at all but still cannot happen while
+ * someone else is acting (walking out of the room, say).
+ */
+export function requirePhase(scene, actor) {
+    const enc = encounterOf(scene, actor);
+    if (!enc || enc.ended)
+        return undefined;
+    if (!enc.isPhaseOf(actor))
+        return notYourPhase(enc, actor);
+    return undefined;
+}
+/** What is left this phase, for a verb's trailing hint. */
+export function phaseHint(scene, actor) {
+    const enc = encounterOf(scene, actor);
+    const budget = enc?.budgetOf(actor);
+    if (!enc || !budget)
+        return '';
+    return budget.actionsExhausted
+        ? hint(` (${budget.free > 0 ? 'A Free Action left, then ' : ''}"end turn".)`)
+        : hint(` (${budget.describe()} left.)`);
+}
+//# sourceMappingURL=action-cost.js.map

package/bundle/typescript/src/commands/game/sideQuest/utilities/auto-fight.js

@@ -70,6 +70,11 @@ export class AutoFight {
                 continue;
             if (player.autoStance === 'manual')
                 continue;
+            // A COMBAT TURN schedules from the phase (onPhaseBegins), never
+            // from a settled strike -- acting between phases is the thing the
+            // turn structure exists to stop.
+            if (this.game.scene.encounterFor?.(player))
+                continue;
             const target = combatants.find(c => c !== player);
             if (!target)
                 continue;
@@ -81,6 +86,59 @@ export class AutoFight {
             this.pending.set(player.name, t);
         }
     }
+    /**
+     * A COMBAT TURN handed this human their Action Phase
+     * (utilities/combat-turn.ts). At any stance but manual the autopilot
+     * plays the phase after the same interruptible beat: draw if
+     * holstered, the stance's strike, then "end turn". Typing anything
+     * cancels it and takes over, exactly as between exchanges.
+     */
+    onPhaseBegins(player, enc) {
+        if (player.autoStance === 'manual')
+            return;
+        this.cancelPending(player.name);
+        const t = setTimeout(() => {
+            this.pending.delete(player.name);
+            void this.playPhase(player, enc);
+        }, AutoFight.REENGAGE_DELAY_MS);
+        this.pending.set(player.name, t);
+    }
+    async playPhase(player, enc) {
+        const logger = Logger.getInstance();
+        if (player.autoStance === 'manual' || !enc.isPhaseOf(player) || player.isIncapacitated())
+            return;
+        const run = async (cmd) => {
+            if (!enc.isPhaseOf(player))
+                return;
+            logger.meta(`⚔ [${player.autoStance}] ${cmd}`, 'cyan');
+            const result = (await this.game.handleInputAs(player.name, cmd)).text;
+            if (result)
+                logger.log(result);
+        };
+        const target = enc.enemiesOf(player)[0];
+        if (!target) {
+            await run('end-turn');
+            return;
+        }
+        if (player.autoStance === 'non-lethal' && target.surrendered) {
+            if (player.plane === 'meat' && target.plane === 'meat'
+                && player.grappling !== target.name && !target.grappledBy) {
+                await run(`restrain ${target.name}`);
+            }
+            else {
+                logger.logWithColor(`⚔ ${target.name} has surrendered -- you hold fire. (non-lethal)`, 'yellow');
+            }
+            await run('end-turn');
+            this.game.updateStatus();
+            return;
+        }
+        const weapon = player.getCarriedWeapon();
+        if (weapon && !player.weaponDrawn && player.plane === 'meat')
+            await run('draw');
+        await run(this.chooseAction(player, target));
+        await run('end-turn');
+        this.game.updateStatus();
+    }
     /**
      * The beat elapsed uninterrupted -- act, if the fight still stands.
      * Every guard here re-checks live state: the target may have died, fled,