@alexkroman1/aai-cli 6.10.1 → 7.0.0

package/dist/templates/solo-rpg/shared.ts

@@ -1,4 +1,4 @@
-import { type DeepReadonly, sessionSlot, type ToolContext } from "@alexkroman1/aai";
+import { type DeepReadonly, dialog, sessionSlot, type ToolContext } from "@alexkroman1/aai";
 import { z } from "zod";
 
 // ── Tuning Constants ─────────────────────────────────────────────────────────
@@ -247,8 +247,16 @@ export interface LastRoll {
 
 // ── Game State ───────────────────────────────────────────────────────────────
 export interface GameState {
+  /**
+   * Whether a character exists. The CLIENT's render flag — `client.tsx` shows
+   * the character sheet on it — and nothing else.
+   *
+   * It used to sit beside `phase: "genre" | "playing"`, which was the same bit
+   * spelled twice: `phase === "playing"` was true exactly when this was, and
+   * neither field gated anything. `phase` is gone and {@link storyFlow} holds
+   * the position now — see its own doc for the split.
+   */
   initialized: boolean;
-  phase: "genre" | "playing";
   settingGenre: string;
   settingTone: string;
   settingArchetype: string;
@@ -285,7 +293,6 @@ export interface GameState {
 
 export const DEFAULT_STATE: GameState = {
   initialized: false,
-  phase: "genre",
   settingGenre: "",
   settingTone: "",
   settingArchetype: "",
@@ -326,7 +333,15 @@ export const DEFAULT_STATE: GameState = {
 // `DEFAULT_STATE` is one module-level object shared by every session in the
 // process, so a factory without it would let one player's game show up in
 // another's.
-export const gameSlot = sessionSlot("game", () => structuredClone(DEFAULT_STATE));
+export const gameSlot = sessionSlot("game", () => structuredClone(DEFAULT_STATE), {
+  // The derived-field recalculation every mutating tool used to have to
+  // remember. It was written out by hand in `applyConsequences`,
+  // `revertConsequences` and `update_state`, which is the shape `after` exists
+  // to replace: a new tool that empties a track now cannot store a stale
+  // `gameOver`, and `gameOver` is what the story flow's `DOWNED` transition
+  // reads. `dispatch-center`'s board is the same pattern one template over.
+  after: updateCrisisFlags,
+});
 
 /**
  * The IDENTITY projection, used by `syncState` and by `useAgentState`: this
@@ -335,6 +350,95 @@ export const gameSlot = sessionSlot("game", () => structuredClone(DEFAULT_STATE)
  */
 export const gameProjection = gameSlot.projection((game) => game);
 
+// ── The story, as a machine ──────────────────────────────────────────────────
+
+/**
+ * Where the story is, and what may be done from there, as a plain state map.
+ *
+ * A {@link DialogSpec} rather than an XState machine. This dialog used four
+ * events and one instruction per state, which is all a spec can say — and the
+ * `setup({ types: {} as { events: … } })` block it used to carry restated the
+ * four names already written in the `on` maps. `type: "final"` is `final: true`,
+ * and the instruction is a DECLARED field rather than an untyped `meta` bag, so
+ * misspelling it is a compile error instead of a refusal that arrives with no
+ * recovery text. `as const` keeps the `on` keys literal, so every `send` and
+ * `sendFrom` below is checked against the events this spec declares.
+ *
+ * Three hand-rolled versions of this question lived in the template, and all
+ * three were positional questions answered from data:
+ *
+ * - **`phase: "genre" | "playing"`** (with `initialized` beside it saying the
+ *   same thing) gated NOTHING. `action_roll`, `update_state` and
+ *   `burn_momentum` all ran happily before a character existed — rolling 2d6
+ *   against the stats of nobody, against clocks that were not there.
+ * - **`burn_momentum`'s `if (!last) return { error: "No recent action roll to
+ *   upgrade. Roll first." }`** is `when` written out by hand. Burning is legal
+ *   for exactly as long as a roll is standing, which is a position.
+ * - **`gameOver`** was set by `updateCrisisFlags` and read by nobody who could
+ *   act on it, so a player whose health and spirit were both gone could keep
+ *   rolling for as long as they liked.
+ *
+ * **What stays in {@link GameState} is what the CLIENT renders** —
+ * `initialized`, `crisisMode`, `gameOver` — because `syncState` carries one
+ * projection and it is the campaign's. The flow holds the POSITION and the slot
+ * holds the campaign, which is the same split `travel-concierge` makes between
+ * its gate and its trip: one tool call moves both, in one synchronous window
+ * each.
+ *
+ * **Starting over is a RESET, not a transition.** `setup_character` replaces the
+ * campaign with a pristine `DEFAULT_STATE`, so the honest mirror on this side is
+ * `storyFlow.reset` — and it is what lets `gameOver` be a genuinely `final`
+ * state, which is the whole point of having one: `position().done` means the
+ * story ended, and XState delivers no events to a done actor, so an `on: {
+ * SETUP }` there would have been dead config that looked live. `load_game`
+ * resets for the same reason. `SETUP` therefore appears once, on the only state
+ * that can be transitioned out of.
+ */
+const storySpec = {
+  initial: "awaitingSetup",
+  states: {
+    awaitingSetup: {
+      instruction:
+        "There is no character yet. Take whatever the player gave you — a name, a " +
+        "genre, an idea, or nothing — infer the rest yourself, and call " +
+        "setup_character with every field filled in. Ask no follow-up questions.",
+      on: { SETUP: "playing" },
+    },
+    playing: {
+      initial: "awaitingRoll",
+      on: { DOWNED: "gameOver" },
+      states: {
+        awaitingRoll: {
+          instruction:
+            "Narrate the scene and offer two or three choices. Any risky action goes " +
+            "through action_roll — never narrate a success or a failure yourself.",
+          on: { ROLLED: "rollResolved" },
+        },
+        rollResolved: {
+          instruction:
+            "A roll is standing. burn_momentum can still upgrade it if the player " +
+            "spends momentum; anything that moves the scene on settles it.",
+          // A second roll replaces the standing one, so `ROLLED` re-enters.
+          on: { ROLLED: "rollResolved", SETTLED: "awaitingRoll" },
+        },
+      },
+    },
+    gameOver: {
+      final: true,
+      instruction:
+        "Health and spirit are both gone. Narrate the ending and stop — nothing " +
+        "else may be rolled. setup_character begins a new story.",
+    },
+  },
+} as const;
+
+/**
+ * The flow. Its own slot key beside {@link gameSlot}, and the reason it is not
+ * folded into the campaign is that the campaign is what the browser renders: a
+ * flow stores an XState snapshot, which is not a character sheet.
+ */
+export const storyFlow = dialog("story", storySpec);
+
 /**
  * The game as a READ hands it out: deep-frozen, and typed to say so.
  *
@@ -468,7 +572,6 @@ export function clockSummary(c: DeepReadonly<Clock>) {
 export function stateSummary(state: FrozenGameState) {
   return {
     initialized: state.initialized,
-    phase: state.phase,
     settingGenre: state.settingGenre,
     settingTone: state.settingTone,
     settingArchetype: state.settingArchetype,
@@ -494,8 +597,11 @@ export function stateSummary(state: FrozenGameState) {
     currentSceneContext: state.currentSceneContext,
     timeOfDay: state.timeOfDay,
     chaosFactor: state.chaosFactor,
-    crisisMode: state.crisisMode,
-    gameOver: state.gameOver,
+    // DERIVED here rather than copied off the state: `after` restores the
+    // stored flags only once the calling body has returned, so a summary built
+    // inside that body would report the tracks it just emptied as survivable.
+    crisisMode: inCrisis(state),
+    gameOver: isGameOver(state),
     // NPCs go to the LLM whole (nothing withheld) — copied so a mutation of
     // the summary can't reach live state.
     npcs: state.npcs.filter((n) => n.status !== "deceased").map((n) => ({ ...n })),
@@ -584,15 +690,38 @@ function changeMomentum(game: GameState, amount: number, deltas: ConsequenceDelt
   deltas.momentum += game.momentum - old;
 }
 
-export function updateCrisisFlags(game: GameState): void {
-  if (game.health <= 0 && game.spirit <= 0) {
-    game.gameOver = true;
-    game.crisisMode = true;
-  } else if (game.health <= 0 || game.spirit <= 0) {
-    game.crisisMode = true;
-  } else {
-    game.crisisMode = false;
-  }
+/**
+ * The one rule that ends a story: both tracks empty.
+ *
+ * A PREDICATE beside the writer, because the same fact is wanted at two
+ * different moments. {@link gameSlot}'s `after` writes
+ * {@link GameState.gameOver} from it, which is what keeps the stored flag right
+ * for every mutating tool — including one that never thinks about it. A tool
+ * that REPORTS the flag in its own result reads the predicate directly, because
+ * `after` runs only once the body has already built that result: a copy taken
+ * from `state.gameOver` would be one mutation behind, and that copy is exactly
+ * what `sendFrom` turns into the `DOWNED` transition.
+ */
+export function isGameOver(game: FrozenGameState): boolean {
+  return game.health <= 0 && game.spirit <= 0;
+}
+
+/** Either track empty — what the client paints red. */
+export function inCrisis(game: FrozenGameState): boolean {
+  return game.health <= 0 || game.spirit <= 0;
+}
+
+/**
+ * Restore the two derived flags from the tracks they are derived FROM.
+ *
+ * Called by nothing but {@link gameSlot}'s `after` — it used to be called by
+ * hand from three places, which is a rule every future mutating tool has to
+ * remember and one of them eventually will not. A stale `gameOver` is not a
+ * cosmetic miss: it is what the `DOWNED` transition reads.
+ */
+function updateCrisisFlags(game: GameState): void {
+  game.gameOver = isGameOver(game);
+  game.crisisMode = inCrisis(game);
 }
 
 export function applyConsequences(
@@ -685,8 +814,6 @@ export function applyConsequences(
     }
   }
 
-  updateCrisisFlags(game);
-
   return { consequences, clockEvents, deltas };
 }
 
@@ -713,7 +840,6 @@ export function revertConsequences(game: GameState, deltas: ConsequenceDeltas):
     const clock = game.clocks.find((c) => c.id === deltas.clockId);
     if (clock) clock.filled = Math.max(0, clock.filled - deltas.clockTicks);
   }
-  updateCrisisFlags(game);
 }
 
 // ── Momentum Burn ────────────────────────────────────────────────────────────

package/dist/templates/solo-rpg/system-prompt.md

@@ -63,7 +63,7 @@ MOMENTUM (Ironsworn):
 - Starts at 2, range -6 to +10
 - Weak Hit: +1. Strong Hit: +2 (or +3 with great effect)
 - Miss: -2 (or -3 if desperate)
-- Burn: the player can spend momentum to upgrade the most recent roll — call burn_momentum (no arguments; it validates against the stored roll). Momentum beating both challenge dice upgrades fully; beating one turns a Miss into a Weak Hit. Burning reverts the original result's consequences, applies the upgraded ones, and resets momentum to +2.
+- Burn: the player can spend momentum to upgrade the most recent roll — call burn_momentum (no arguments; it validates against the stored roll). Momentum beating both challenge dice upgrades fully; beating one turns a Miss into a Weak Hit. Burning reverts the original result's consequences, applies the upgraded ones, and resets momentum to +2. The window is only open while a roll is standing: once you move the scene on with update_state, the roll is spent and burn_momentum refuses.
 
 CHAOS FACTOR (Mythic GME):
 - Range 3-9, starts at 5
@@ -86,6 +86,7 @@ Track up to 12 active NPCs.
 CRISIS:
 - Health or spirit at 0 = crisis mode. Both at 0 = game over.
 - In crisis, every miss is more dangerous.
+- Game over is final. Nothing more can be rolled or updated — narrate the ending. setup_character is the only way on, and it begins a new story.
 
 KID MODE:
 If kidMode is true: no explicit violence, no death, hopeful tone, age-appropriate content. Enemies are "defeated" not "killed". Think Studio Ghibli, Zelda.
@@ -97,7 +98,7 @@ CORRECTION SYSTEM:
 If the player starts a message with ##, treat it as a correction to the previous turn. Acknowledge the correction and rewrite the scene.
 
 FLOW:
-1. Call check_state as your FIRST tool call every turn, before narrating or rolling. Read the returned values as ground truth. NEVER remember or guess stats from prior turns.
+1. Call check_state as your FIRST tool call every turn, before narrating or rolling. Read the returned values as ground truth. NEVER remember or guess stats from prior turns. Its `state` and `instruction` say where the story is and what that expects — every other tool answers with the same pair, and a tool that is not available yet refuses and tells you what has to happen first. You do not have to remember any of this between turns.
 2. Present situations with tension and choice. Two to three options, but accept anything.
 3. For ANY risky action, you MUST call action_roll. NEVER narrate success or failure without rolling. NEVER reduce health, spirit, supply, or momentum yourself — action_roll does this through code. If you narrate damage without calling action_roll, the sidebar will be wrong and the game will break.
 4. After location changes, new NPCs, or other world changes, call update_state. But NEVER manually set health, spirit, supply, or momentum in update_state unless the player is resting or trading — action_roll handles combat and risk.

package/dist/templates/solo-rpg/tools/action_roll.ts

@@ -4,16 +4,27 @@ import {
   canBurnMomentum,
   checkChaosInterrupt,
   gameSlot,
+  inCrisis,
+  isGameOver,
   MOVE_LABELS,
   MOVES,
   RESULT_LABELS,
   rollAction,
+  storyFlow,
   updateChaosFactor,
 } from "../shared.ts";
 
-export default gameSlot.updateTool({
+/**
+ * Gated on `playing`, which is what makes "never narrate a success without
+ * rolling" hold from the other side too: before `setup_character` there are no
+ * stats to roll against, and this used to roll 2d6 against nobody and apply
+ * consequences to a game that did not exist. After a game over it refuses
+ * outright — `gameOver` was a flag nothing acted on.
+ */
+export default storyFlow.tool({
   description:
     "Core mechanic. Roll 2d6 + stat (capped at 10) vs 2d10 challenge dice. Also applies consequences (health/spirit/supply/momentum changes, clock advancement) based on move type, position, and result. Call for ANY risky action. Pure conversation needs no roll.",
+  when: "playing",
   inputSchema: z.object({
     move: z.enum(MOVES).describe("Which move the player is making"),
     stat: z.enum(["edge", "heart", "iron", "shadow", "wits"]).describe("Which stat to roll"),
@@ -24,73 +35,81 @@ export default gameSlot.updateTool({
     purpose: z.string().max(300).describe("What the character is attempting"),
     targetNpcId: z.string().max(32).describe("Target NPC id for social moves").optional(),
   }),
-  execute(args, state) {
-    const statValue = state[args.stat];
-    const roll = rollAction(args.stat, statValue, args.move);
+  execute: (args, ctx) =>
+    gameSlot.update(ctx, (state) => {
+      const statValue = state[args.stat];
+      const roll = rollAction(args.stat, statValue, args.move);
 
-    // Apply consequences
-    const { consequences, clockEvents, deltas } = applyConsequences(
-      state,
-      roll,
-      args.position,
-      args.effect,
-      args.targetNpcId ?? null,
-    );
+      // Apply consequences
+      const { consequences, clockEvents, deltas } = applyConsequences(
+        state,
+        roll,
+        args.position,
+        args.effect,
+        args.targetNpcId ?? null,
+      );
 
-    // Persist the roll (with the exact deltas applied) so burn_momentum can
-    // validate against it and revert it — the model never supplies dice.
-    state.lastRoll = {
-      ...roll,
-      position: args.position,
-      effect: args.effect,
-      targetNpcId: args.targetNpcId ?? null,
-      deltas,
-    };
+      // Persist the roll (with the exact deltas applied) so burn_momentum can
+      // validate against it and revert it — the model never supplies dice.
+      state.lastRoll = {
+        ...roll,
+        position: args.position,
+        effect: args.effect,
+        targetNpcId: args.targetNpcId ?? null,
+        deltas,
+      };
 
-    // Update chaos factor
-    updateChaosFactor(state, roll.result);
+      // Update chaos factor
+      updateChaosFactor(state, roll.result);
 
-    // Check for chaos interrupt
-    const interrupt = checkChaosInterrupt(state);
+      // Check for chaos interrupt
+      const interrupt = checkChaosInterrupt(state);
 
-    // Increment scene count
-    state.sceneCount++;
+      // Increment scene count
+      state.sceneCount++;
 
-    // Can burn momentum?
-    const burnTarget = canBurnMomentum(state, roll);
+      // Can burn momentum?
+      const burnTarget = canBurnMomentum(state, roll);
 
-    return {
-      purpose: args.purpose,
-      move: MOVE_LABELS[args.move] || args.move,
-      moveCode: args.move,
-      stat: args.stat,
-      statValue,
-      actionDice: [roll.d1, roll.d2],
-      challengeDice: [roll.c1, roll.c2],
-      actionScore: roll.actionScore,
-      result: RESULT_LABELS[roll.result],
-      resultCode: roll.result,
-      match: roll.match,
-      matchNote: roll.match
-        ? roll.result === "STRONG_HIT" || roll.result === "WEAK_HIT"
-          ? "Fateful roll. Both challenge dice match. An unexpected advantage or twist."
-          : "Fateful roll. Both challenge dice match. A dire and dramatic escalation."
-        : undefined,
-      position: args.position,
-      effect: args.effect,
-      consequences,
-      clockEvents,
-      chaosInterrupt: interrupt,
-      currentHealth: state.health,
-      currentSpirit: state.spirit,
-      currentSupply: state.supply,
-      currentMomentum: state.momentum,
-      chaosFactor: state.chaosFactor,
-      crisisMode: state.crisisMode,
-      gameOver: state.gameOver,
-      sceneCount: state.sceneCount,
-      canBurnMomentum: Boolean(burnTarget),
-      burnWouldYield: burnTarget ? RESULT_LABELS[burnTarget] : undefined,
-    };
-  },
+      return {
+        purpose: args.purpose,
+        move: MOVE_LABELS[args.move] || args.move,
+        moveCode: args.move,
+        stat: args.stat,
+        statValue,
+        actionDice: [roll.d1, roll.d2],
+        challengeDice: [roll.c1, roll.c2],
+        actionScore: roll.actionScore,
+        result: RESULT_LABELS[roll.result],
+        resultCode: roll.result,
+        match: roll.match,
+        matchNote: roll.match
+          ? roll.result === "STRONG_HIT" || roll.result === "WEAK_HIT"
+            ? "Fateful roll. Both challenge dice match. An unexpected advantage or twist."
+            : "Fateful roll. Both challenge dice match. A dire and dramatic escalation."
+          : undefined,
+        position: args.position,
+        effect: args.effect,
+        consequences,
+        clockEvents,
+        chaosInterrupt: interrupt,
+        currentHealth: state.health,
+        currentSpirit: state.spirit,
+        currentSupply: state.supply,
+        currentMomentum: state.momentum,
+        chaosFactor: state.chaosFactor,
+        // Derived, not copied: `gameSlot`'s `after` restores the stored flags
+        // only once this body has returned, so `state.gameOver` here would be
+        // the value from before the roll that emptied the track.
+        crisisMode: inCrisis(state),
+        gameOver: isGameOver(state),
+        sceneCount: state.sceneCount,
+        canBurnMomentum: Boolean(burnTarget),
+        burnWouldYield: burnTarget ? RESULT_LABELS[burnTarget] : undefined,
+      };
+    }),
+  // A roll that emptied both tracks ends the story; anything else leaves a
+  // standing roll that `burn_momentum` may still upgrade.
+  sendFrom: (result) =>
+    result.gameOver ? { type: "DOWNED" as const } : { type: "ROLLED" as const },
 });

package/dist/templates/solo-rpg/tools/burn_momentum.ts

@@ -2,66 +2,101 @@ import {
   applyConsequences,
   canBurnMomentum,
   gameSlot,
+  inCrisis,
+  isGameOver,
   MOMENTUM_RESET,
   RESULT_LABELS,
   revertConsequences,
+  storyFlow,
 } from "../shared.ts";
 
-export default gameSlot.updateTool({
+/**
+ * Gated on `playing.rollResolved` — the state that means "a roll is standing".
+ *
+ * That gate REPLACES this body's opening `if (!state.lastRoll) return { error:
+ * "No recent action roll to upgrade. Roll first." }`, which was `when` written
+ * out by hand: "is there a roll to upgrade" is a question about where the game
+ * is, not about the data, and the flow's refusal names the position and quotes
+ * the state's instruction where that sentence could only assert.
+ *
+ * The two checks BELOW stay, because they really are about the data: whether
+ * the roll was already a Strong Hit, and whether the momentum beats the
+ * challenge dice. Those are the rules of the game; the gate is the shape of the
+ * turn.
+ */
+export default storyFlow.tool({
   description:
     "Burn momentum to upgrade the most recent action roll. Only valid when current momentum beats the roll's challenge dice (both dice for a full upgrade, one for Miss to Weak Hit). Reverts the original result's consequences, applies the upgraded result, and resets momentum to +2.",
-  execute(_args, state) {
-    const last = state.lastRoll;
-    if (!last) return { error: "No recent action roll to upgrade. Roll first." };
-    if (last.result === "STRONG_HIT") {
-      return { error: "The last roll was already a Strong Hit. Nothing to upgrade." };
-    }
+  when: "playing.rollResolved",
+  execute: (_args, ctx) =>
+    gameSlot.update(ctx, (state) => {
+      const last = state.lastRoll;
+      // Reachable only if the position and the campaign disagree — the flow says
+      // a roll is standing and nothing recorded one — which no code path
+      // produces: `action_roll` writes `lastRoll` and sends `ROLLED` in the same
+      // call. Reported rather than thrown, mid-game.
+      if (!last) return { error: "No recent action roll to upgrade. Roll first." };
+      if (last.result === "STRONG_HIT") {
+        return { error: "The last roll was already a Strong Hit. Nothing to upgrade." };
+      }
 
-    const upgrade = canBurnMomentum(state, last);
-    if (!upgrade) {
-      return {
-        error:
-          state.momentum <= 0
-            ? "Momentum is 0 or negative. Cannot burn."
-            : "Momentum not high enough to improve the result.",
-      };
-    }
+      const upgrade = canBurnMomentum(state, last);
+      if (!upgrade) {
+        return {
+          error:
+            state.momentum <= 0
+              ? "Momentum is 0 or negative. Cannot burn."
+              : "Momentum not high enough to improve the result.",
+        };
+      }
 
-    const previousMomentum = state.momentum;
-    const previousResult = last.result;
+      const previousMomentum = state.momentum;
+      const previousResult = last.result;
 
-    // Undo exactly what the original result applied, then apply the
-    // upgraded result's effects (bond/disposition/momentum gains).
-    revertConsequences(state, last.deltas);
-    const upgraded = { ...last, result: upgrade };
-    const { consequences, clockEvents } = applyConsequences(
-      state,
-      upgraded,
-      last.position,
-      last.effect,
-      last.targetNpcId,
-    );
+      // Undo exactly what the original result applied, then apply the
+      // upgraded result's effects (bond/disposition/momentum gains).
+      revertConsequences(state, last.deltas);
+      const upgraded = { ...last, result: upgrade };
+      const { consequences, clockEvents } = applyConsequences(
+        state,
+        upgraded,
+        last.position,
+        last.effect,
+        last.targetNpcId,
+      );
 
-    // Burning always resets momentum, overriding any gain from the upgrade.
-    state.momentum = MOMENTUM_RESET;
-    state.lastRoll = null;
+      // Burning always resets momentum, overriding any gain from the upgrade.
+      state.momentum = MOMENTUM_RESET;
+      state.lastRoll = null;
 
-    return {
-      burned: true,
-      previousMomentum,
-      newMomentum: MOMENTUM_RESET,
-      previousResult: RESULT_LABELS[previousResult],
-      newResult: RESULT_LABELS[upgrade],
-      newResultCode: upgrade,
-      challengeDice: [last.c1, last.c2],
-      revertedConsequences: true,
-      consequences,
-      clockEvents,
-      currentHealth: state.health,
-      currentSpirit: state.spirit,
-      currentSupply: state.supply,
-      crisisMode: state.crisisMode,
-      gameOver: state.gameOver,
-    };
-  },
+      return {
+        burned: true,
+        previousMomentum,
+        newMomentum: MOMENTUM_RESET,
+        previousResult: RESULT_LABELS[previousResult],
+        newResult: RESULT_LABELS[upgrade],
+        newResultCode: upgrade,
+        challengeDice: [last.c1, last.c2],
+        revertedConsequences: true,
+        consequences,
+        clockEvents,
+        currentHealth: state.health,
+        currentSpirit: state.spirit,
+        currentSupply: state.supply,
+        // As `action_roll`: derived rather than copied, because `after` has not
+        // run yet when this object is built.
+        crisisMode: inCrisis(state),
+        gameOver: isGameOver(state),
+      };
+    }),
+  // A burn CONSUMES the standing roll (`lastRoll` is cleared), so the resting
+  // event is `SETTLED` rather than `ROLLED` — where `action_roll` leaves one
+  // standing, this one spends it. A burn that emptied the last track is as
+  // final as a roll that did.
+  //
+  // `result` is the SUCCESS type — `sendFrom` takes `Exclude<R, ToolFailure>`
+  // now, so the `"gameOver" in result` guard that stood in for the failure arm
+  // leaking into `R` is a plain property read.
+  sendFrom: (result) =>
+    result.gameOver ? { type: "DOWNED" as const } : { type: "SETTLED" as const },
 });

package/dist/templates/solo-rpg/tools/check_state.ts

@@ -1,11 +1,28 @@
-import { gameSlot, stateSummary } from "../shared.ts";
+import { gameSlot, stateSummary, storyFlow } from "../shared.ts";
 
-// `gameSlot.tool`, the READING half: the body is handed the value, so it needs
-// neither a context annotation nor an opening `gameSlot.get(ctx)` — and what it
-// is handed is deep-frozen, which is what makes "this tool only reads" a
-// property of the declaration rather than a claim in a comment.
+/**
+ * `gameSlot.tool`, the READING half: the body is handed the value, so it needs
+ * neither a context annotation nor an opening `gameSlot.get(ctx)` — and what it
+ * is handed is deep-frozen, which is what makes "this tool only reads" a
+ * property of the declaration rather than a claim in a comment.
+ *
+ * **Legal in every state, which is why it is not a `storyFlow.tool`** — the
+ * prompt says to call it FIRST every turn, and that includes the turn before a
+ * character exists. It is also the one tool that reports the POSITION, the way
+ * `plan-and-execute`'s `plan_status` does: the position comes from the machine
+ * rather than from a second reading of the campaign's fields, so "there is no
+ * character yet" is the same fact here as the refusal `action_roll` would give.
+ */
 export default gameSlot.tool({
   description:
-    "Returns the full current game state. Call this at the start of every turn, before narrating or rolling, and treat the returned values as ground truth — never guess or remember stats from previous turns.",
-  execute: (_args, game) => stateSummary(game),
+    "Returns the full current game state, and where the story is. Call this at the start of every turn, before narrating or rolling, and treat the returned values as ground truth — never guess or remember stats from previous turns.",
+  execute: (_args, game, ctx) => ({
+    // The position SPREAD rather than renamed. `at`/`next`/`storyOver` said the
+    // same three things a gated tool's result already carries as `state`,
+    // `instruction` and `done` — so within one agent the model was reading its
+    // own position under two key sets, and the system prompt's claim that
+    // "every other tool answers with the same pair" was simply false.
+    ...storyFlow.position(ctx),
+    ...stateSummary(game),
+  }),
 });

package/dist/templates/solo-rpg/tools/load_game.ts

@@ -1,7 +1,7 @@
 import { tool } from "@alexkroman1/aai";
 import { z } from "zod";
 import type { GameState } from "../shared.ts";
-import { gameSlot, loadState, saveSlotKey, saveSlotParam } from "../shared.ts";
+import { gameSlot, loadState, saveSlotKey, saveSlotParam, storyFlow } from "../shared.ts";
 
 // Requires storage — `aai storage enable` (or DATABASE_URL in .env under
 // `aai dev`); the rest of the game works without it.
@@ -12,8 +12,20 @@ export default tool({
     const saved = await loadState<GameState>(ctx, saveSlotKey(args.slot));
     if (!saved) return { error: "No save found." };
     gameSlot.set(ctx, saved);
+
+    // The flow has to be restored alongside the campaign, or a loaded game
+    // would still be sitting in `awaitingSetup` with every roll tool refusing.
+    // A save is written from a settled scene, so it resumes at `awaitingRoll`
+    // rather than with a standing roll — `lastRoll` may be set, but a burn
+    // window that survived a save and a reload is not one a player is still in.
+    storyFlow.reset(ctx);
+    let at = storyFlow.send(ctx, { type: "SETUP" });
+    if (saved.gameOver) at = storyFlow.send(ctx, { type: "DOWNED" });
+
     return {
       loaded: true,
+      // The position spread verbatim — the same keys every gated tool reports.
+      ...at,
       playerName: saved.playerName,
       characterConcept: saved.characterConcept,
       settingGenre: saved.settingGenre,