From 1df7aac8a7f7d76ad1d3f58dd00f4d9b94e59950 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Sun, 7 Jun 2026 16:42:31 -0700
Subject: [PATCH 01/55] planning docs

---
 docs/kaizen.md        |   4 +-
 docs/phase-3-plan.md  |  72 ++++++++++++--
 docs/phase-4-notes.md | 213 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 280 insertions(+), 9 deletions(-)
 create mode 100644 docs/phase-4-notes.md

diff --git a/docs/kaizen.md b/docs/kaizen.md
index 7a974a0..141efe1 100644
--- a/docs/kaizen.md
+++ b/docs/kaizen.md
@@ -21,8 +21,8 @@ When an item lands, gets reclassified, or develops new context, edit it in place
 
 ## ▶ Phase 3 candidates
 
-- **Cyberspace / Matrix layer.** Jack-in mechanic, second layered grid, ICE AI (Probes, Sparks, Guardians), CCTV PIP window showing physical body status while jacked in. Originally Blueprint Phase 2; moved to Phase 3 so Phase 2 deepens Meatspace first.
-- **Decker archetype.** Cyberspace specialist. Deferred alongside the Matrix layer — design the environment before designing who navigates it.
+- **Cyberspace / Matrix layer.** Jack-in mechanic, second layered grid, ICE AI (Probes, Sparks, Guardians), CCTV PIP window showing physical body status while jacked in. Originally Blueprint Phase 2; moved to Phase 3 so Phase 2 deepens Meatspace first. **Planning updated:** see [phase-3-plan.md](phase-3-plan.md) P3.M3.1–P3.M3.6 for the first playable "enter Cyberspace" path (contract flag → jack-in terminal → serializable cyber layer → data node → Probe ICE → render swap), and P3.M4.1–P3.M4.6 for dual-deploy / flip integration.
+- **Decker archetype.** Cyberspace specialist. Deferred alongside the Matrix layer — design the environment before designing who navigates it. **Planning updated:** see [phase-3-plan.md](phase-3-plan.md) P3.M2 for recruitment through progressive Hub reveal, normal roster ownership, drone override, and the rule that Cyberspace-required deployments fail loudly without a living Decker.
 - **Full Rep NPC ally behaviour.** Phase 2 (M5) lays the groundwork: Rep meter, NPC taxonomy, behavior tiers. Phase 3 adds the payoff: high-rep neutrals become Human Shields or information sources, as described in the blueprint.
 - **Inter-hostile friction — multiple crews fighting each other on one map.** Surfaced during Phase 2.9 planning (June 2026). Phase 2.9 ships `RIVAL` as a faction *value* but deliberately keeps **one hostile faction per run** (faction derived from the contract's principal: corp/civic → `CORP`, rival groups → `RIVAL`). That's the slim, cosmetic-foundational slice — it does *not* put `CORP` and `RIVAL` on the same map. The deferred expansion is **mixed encounters with relationship structure** — a rival crew/gang on a site you're also hitting, where the play value comes from *friction*, not a recolor. The design spectrum we mapped:
   - **Cooperate vs player** — RIVAL behaves identically and shares your enemy; mechanically a reskin (the M1 display layer already delivers the label/colour delta). Weakest payoff; arguably not worth a faction *model*.
diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index d4dda67..6caeb6e 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -89,10 +89,10 @@ Score-target sites always use roster-stored dimensions (P2.7.M1.5: `mapWidth`, `
 
 **Scope:**
 
-- **Arc state:** Campaign save tracks current act (1/2/3), run count, and arc-specific flags (Decker recruited, Score revealed, Clock started, Score attempted).
+- **Arc state:** Campaign save tracks `arcStage` (`act-1` / `act-2` / `act-3` / `score`), run count, and arc-specific flags (`deckerRecruited`, `scoreRevealed`, `clockStarted`, `scoreAttempted`, `scoreCompleted`). Prefer a typed `Campaign.arc` record over stuffing more opaque keys into `Campaign.meta`; legacy saves can normalize from absent `arc` into Act 1.
 - **Act transitions:** Define triggers for act boundaries:
-  - Act 1 → Act 2: reach top rep tier + minimum run count (e.g. 4–5 runs). Triggers Score reveal and Decker recruitment opportunity.
-  - Act 2 → Act 3: Decker recruited + Score target site visited at least once + Clock threshold (e.g. run 10+). Triggers "final prep" phase.
+  - Act 1 → Act 2: reach top rep tier + minimum successful job count (recommended: `completedJobs >= 4`). Triggers Score reveal and Decker recruitment opportunity.
+  - Act 2 → Act 3: Decker recruited + Score target site visited at least once + Clock threshold (recommended: `completedJobs >= 9`). Triggers "final prep" phase.
   - Score available: Act 3 + player-initiated (choose to attempt the Score from the Hub).
 - **Score target designation:** At Act 2 entry, choose exactly one remembered or newly seeded `LocationSite`, set `scoreTarget: true`, and promote `tier: 'score'` so P2.5.M7 eviction preserves it. If no roster site exists yet, synthesize a site identity from the Curator lexicon and add it to the roster; do not silently defer the Score reveal.
 - **Arc-aware Curator:** Current code already passes through `arcStage`; P3.M1 must make it behaviorally meaningful:
@@ -108,14 +108,33 @@ Score-target sites always use roster-stored dimensions (P2.7.M1.5: `mapWidth`, `
 
 **The Clock mechanic:**
 
-The Clock creates mounting pressure that discourages indefinite grinding. Options (pick one or combine at implementation):
+The Clock creates mounting pressure that discourages indefinite grinding. **Recommended first implementation:** combine escalating global difficulty as soft pressure with an operational window as the hard campaign deadline. It is easy to communicate, test, and tune:
+
+- `clockStartsAtJob = 8`
+- `scoreDeadlineJob = 13`
+- `heat = max(0, completedJobs - clockStartsAtJob)`
+- Each point of heat nudges contract threat / alarm sensitivity upward, capped by difficulty tier.
+- If the player returns to Hub with `completedJobs >= scoreDeadlineJob` and `scoreAttempted` is false, campaign ends with clock loss.
+
+Other Clock variants remain useful later, but should not block P3.M1:
 
 - **Escalating global difficulty:** Each run after a threshold (e.g. run 8), corp security tier increases globally — more drones, tougher spawns, higher alarm sensitivity. Soft pressure: you *can* keep running, but it gets harder.
 - **Rival crew:** A competing team is after the same Score. Abstract progress bar: each run you take, they advance. If they reach the Score first, you lose (or the Score becomes dramatically harder — they've tripped every alarm).
 - **Operational window:** The Score target has a time-limited vulnerability (maintenance cycle, personnel rotation, satellite blind spot). After N total runs, the window closes permanently. Hard deadline.
 - **Neural degradation:** The Decker's implants degrade with each jack-in. After N Cyberspace runs, they can no longer jack in — and the Score requires Cyberspace. Biological clock on the crew, not the world.
 
-Implementation notes TBD after Clock type is chosen. Multiple types may coexist (escalating difficulty as soft pressure + operational window as hard deadline).
+Neural degradation is deferred until Cyberspace is fun enough to deserve a jack-in-specific cost. Rival crew pressure is best saved for the inter-hostile friction work in kaizen unless a Score narrative beat specifically needs it.
+
+**Implementation slices:**
+
+| Slice | Change | Tests |
+|---|---|---|
+| **P3.M1.1 Arc record** | Add `Campaign.arc`, derive `arcStage`, persist/restore, normalize old saves to Act 1 | constructor validation, snapshot round-trip, invalid stage throws |
+| **P3.M1.2 Transitions** | Advance acts from `rep`, `completedJobs`, Decker flag, Score-site visit | boundary tests around job counts and rep tier |
+| **P3.M1.3 Score target** | Promote one roster site to `tier: 'score'`; preserve through eviction | exactly-one target, no eviction at roster cap, synthetic target when roster empty |
+| **P3.M1.4 Clock** | Start heat after threshold; hard loss at deadline; show status | heat math, deadline loss, no loss after Score attempt |
+| **P3.M1.5 Curator bias** | Pass campaign-derived arc context; bias board slots by act and score target | seeded boards show expected `arcStage` and target-site frequency |
+| **P3.M1.6 Score entry** | Hub action creates the special Score contract in Act 3 only | availability gates, deployment path, attempted flag |
 
 **Acceptance:**
 
@@ -141,6 +160,8 @@ Implementation notes TBD after Clock type is chosen. Multiple types may coexist
 - **Cyberspace stats:** The Decker has Cyberspace-specific attributes (e.g. RAM, intrusion strength, ICE resistance) used in P3.M3. Other archetypes cannot jack in (or can with severe penalties — TBD).
 - **Recruitment flow:** Triggered at Act 1 → Act 2 transition. Uses the **progressive Hub reveal** system from P2.5.M5: Curator message introduces the Decker on Hub entry when rep threshold is met and `arc.deckerRecruited` is false. Same pattern as Finn's introduction and Terminal explanation — the Hub grows with the campaign.
 - **Deployment:** The Decker is deployable as a solo operator on any contract (Meatspace only on non-Cyberspace contracts). On Cyberspace contracts, the Decker is one of the dual-deploy pair (see P3.M4).
+- **Roster rule:** The Decker is a named crew member, not a temporary ability unlock. Recruitment should add them to `Campaign.crew` through the existing recruit/callsign machinery or a deliberately separate `recruitDecker()` path with the same validation guarantees. Do not let normal random recruitment roll a Decker before Act 2.
+- **Jack-in authority:** Only a living Decker can start P3.M3 jack-in. If a contract has a Cyberspace requirement and no living Decker is available, deployment should fail loudly at the Hub selection layer rather than starting an unwinnable run.
 
 **Acceptance:**
 
@@ -160,7 +181,7 @@ Implementation notes TBD after Clock type is chosen. Multiple types may coexist
 
 **Scope:**
 
-- **Cyberspace grid:** Separate `Grid` / `World` instance for the digital layer. **Graph-based nodes and logic pathways** (per blueprint) — may use the same grid engine with a different tileset/topology, or a simplified node graph. Design decision at implementation; document trade-offs.
+- **Cyberspace grid:** Separate `Grid` / `World` instance for the digital layer. **First implementation should reuse the existing square grid engine** with a distinct tileset and generation rules, then reserve a later graph-topology refactor only if the square grid fails the feel test. This keeps pathfinding, rendering, snapshots, and tests inside known machinery.
 - **Cyberspace tileset / aesthetic:** Distinct from Meatspace. Nodes, data lines, firewalls, open channels. ASCII glyphs TBD but visually differentiated (color palette, glyph set, CRT effects).
 - **ICE hostiles:** Three types per blueprint:
   - **Probe:** Sentry / patrol. Detects the Decker, raises alert (Cyberspace alarm analog).
@@ -171,6 +192,31 @@ Implementation notes TBD after Clock type is chosen. Multiple types may coexist
 - **Generation:** Procedural per jack-in. Seeded from contract + campaign RNG. Not persistent (fresh each time). Complexity scales with contract difficulty / act.
 - **Jack-in trigger:** Decker interacts with a Meatspace terminal (P2.5.M2.2 `Interactable`). This spawns the Cyberspace grid and activates dual-deploy mode (P3.M4).
 
+**Entering Cyberspace — first playable slice:**
+
+The first jack-in should prove the door between layers before shipping every ICE behavior:
+
+1. Add a `requiresCyberspace` / `cyberspaceObjective` contract param for Act 2+ jobs, generated only when the Decker has been recruited.
+2. Place a Meatspace jack-in terminal using the existing `Terminal` / interactable placement path, distinct in label from ordinary terminal-slice props.
+3. When the Decker interacts with the jack-in terminal, create a `cyberspace` run layer with:
+   - generated grid and seed metadata,
+   - Decker digital avatar,
+   - one data node objective,
+   - at least one Probe ICE.
+4. Latch a run state like `cyberspace.active = true`; repeated jack-in attempts against the same terminal throw or log a deterministic "already linked" message depending on whether state is corrupt or just redundant input.
+5. Saving mid-jack-in restores both Meatspace and Cyberspace. Absent or malformed Cyberspace snapshot data for an active jack-in is tier-1 corrupt state and must throw to the boundary.
+
+**Suggested slice order:**
+
+| Slice | Change | Tests |
+|---|---|---|
+| **P3.M3.1 Contract flag** | Add Cyberspace-capable contract metadata and validation | generated only Act 2+, invalid flag/params throw |
+| **P3.M3.2 Jack-in terminal** | Place a terminal that can start the digital layer | deterministic placement, no collision with objective props |
+| **P3.M3.3 Cyber layer model** | Add serializable `Run.cyberspace` layer with grid/world/avatar | snapshot round-trip, active-layer invariants |
+| **P3.M3.4 Data node objective** | Slice one data node and feed objective satisfaction | incomplete blocks clean extraction, complete allows it |
+| **P3.M3.5 Probe ICE** | Minimal ICE patrol/detect/attack loop | seeded movement, detection/alarm, damage/death |
+| **P3.M3.6 Render swap** | Render Cyberspace when active; Meatspace remains reachable for P3.M4 | browser smoke and console-clean verification |
+
 **Acceptance:**
 
 - Cyberspace grid renders distinctly from Meatspace.
@@ -193,13 +239,25 @@ Implementation notes TBD after Clock type is chosen. Multiple types may coexist
   - **Pre–jack-in phase:** Both operators start in Meatspace. The Meatspace operator moves and acts normally. The Decker must reach a terminal and jack in (P2.5.M2.2 interact) to activate Cyberspace. Until jack-in, this is a normal single-grid mission.
   - **Post–jack-in:** Cyberspace grid spawns. Flip mechanic activates. Decker's Meatspace body remains at the terminal — vulnerable, immobile, and targetable by corp hostiles (blueprint: "your physical body is a vegetable").
 - **The flip:** Switch active control between Meatspace operator and Decker. Active operator receives player input (move, attack, interact). Inactive operator holds position.
-  - Cost: **free action** or **1 AP** (TBD — free action recommended for less friction; AP cost adds tactical weight).
+  - Cost: **free action** for the first implementation. AP cost can be revisited after playtesting, but the first version should make the new mental model easy to explore.
   - Can flip at any point during the active operator's turn (before or after spending AP).
 - **Turn structure:** Player turn → flip as desired → end turn → **both layers' hostile phases resolve** (corp drones move in Meatspace, ICE moves in Cyberspace). Both layers tick simultaneously.
 - **PIP / CCTV window:** The inactive layer renders in a small overlay (bottom right corner of the screen). Shows grid state, hostile positions, the other operator's status. Read-only — no input accepted in the PIP. The blueprint's "real-time CCTV showing your physical body's status" becomes this.
 - **Vulnerability:** While the Decker is jacked in, their Meatspace body is a valid target for corp hostiles. If the body is destroyed, the Decker is killed (flatline) and Cyberspace access is lost. The Meatspace operator's implicit job is to **protect the Decker's body** — or at least keep hostiles away from the terminal.
 - **Jack-out:** The Decker can voluntarily jack out (returns control to single-grid Meatspace). Or is forced out if their body takes critical damage. Jack-out despawns the Cyberspace grid (any unsatisfied Cyberspace objectives fail).
 - **Contracts without Cyberspace:** Single-deploy as today. The Decker deploys solo in Meatspace (no flip, no Cyberspace grid). Their drone override hack is their primary value.
+- **Save invariant:** A run may be single-layer, pre-jack dual-deploy, or active dual-layer. Those states must be explicit. A save with `cyberspace.active = true` but no cyber grid/avatar, or with a Decker marked jacked-in but no Meatspace body anchor, is corrupt and must throw.
+
+**Integration slices:**
+
+| Slice | Change | Tests |
+|---|---|---|
+| **P3.M4.1 Dual deploy pre-jack** | Select Meatspace operator + Decker; both begin in Meatspace | deployment gates, placement, no Decker = no Cyberspace contract |
+| **P3.M4.2 Jacked body anchor** | Decker body becomes immobile target at terminal after jack-in | body targetable, movement rejected, death flatlines Decker |
+| **P3.M4.3 Flip command** | Free action swaps active input layer | input routed to active layer only, inactive holds position |
+| **P3.M4.4 Dual hostile phase** | End turn advances corp and ICE phases once each | deterministic order, both layers tick, no double AP refresh |
+| **P3.M4.5 PIP** | Inactive layer mini-render + status summary | desktop/mobile layout, no input capture |
+| **P3.M4.6 Jack-out** | Voluntary and forced jack-out transitions back to Meatspace | cleanup, objective failure rules, snapshot round-trip |
 
 **Acceptance:**
 
diff --git a/docs/phase-4-notes.md b/docs/phase-4-notes.md
new file mode 100644
index 0000000..3941a8c
--- /dev/null
+++ b/docs/phase-4-notes.md
@@ -0,0 +1,213 @@
+# Phase 4 notes — multi-floor maps (June 6, 2026)
+
+Exploratory notes from a feasibility assessment. Not a living plan — see [phase-3-plan.md](phase-3-plan.md) for official Phase 3 scope and deferrals.
+
+## Context
+
+[phase-3-plan.md](phase-3-plan.md) defers **multi-level / sublevel maps** to Phase 4:
+
+> Vertical map depth (multiple floors, stairs, elevators) is deferred. Labels like "Sublevel 3 cache" remain flavor. Multi-level is a natural extension once persistent locations and Cyberspace are stable — potentially Phase 4.
+
+**Status of that deferral condition (June 2026):**
+
+- **Persistent locations** — shipped (Phase 2.5 M7: `LocationSite`, `mutationDeltas`, `seenKeys`, revisit merge).
+- **Cyberspace** — not yet stable (Phase 3 in flight).
+- **Simulation / mapgen / UI** — still single 2D grid throughout.
+
+---
+
+## Short answer
+
+Multi-floor maps are **feasible but cross-cutting** — roughly half a phase, not a weekend.
+
+| Scope | Rough effort | What you get |
+|-------|--------------|--------------|
+| **Thin MVP** | ~2–3 focused weeks | 2 floors, hand-linked prefabs, stair/elevator interactable, per-floor fog, save/load |
+| **Shippable vertical maps** | ~5–8 weeks | Procgen multi-floor, connectivity validation, recon/dual-site across floors, site memory per floor, content |
+| **Full vision + Phase 3 interplay** | Phase 4-sized | Above + Cyberspace/Meatspace sync rules, mixed-floor AI policy, tower contracts, balance pass |
+
+---
+
+## What exists today
+
+Combat is **one flat `Grid` per run**, wired through every layer:
+
+```
+buildMap() → single Grid
+  → World { grid, entities }
+    → Pathfinding / LOS / Vision / Combat
+    → RunSnapshot + LocationSite
+    → frame.ts → AsciiRenderer
+```
+
+Key facts:
+
+- [`Grid`](../src/game/Grid.ts): `width × height` flat `Uint8Array`; no layer index.
+- [`GridPoint`](../src/types.ts): `{ x, y }` only; coord keys are `"x,y"` everywhere ([`mapConnectivity.ts`](../src/game/mapConnectivity.ts), [`Vision.ts`](../src/game/Vision.ts), [`locations.ts`](../src/game/locations.ts)).
+- [`World`](../src/game/World.ts): one `grid`, `entityAt(x,y)`, `blockerKeys()` as `"x,y"` set.
+- [`Run.enterCombat`](../src/game/Run.ts): `buildMap()` once → spawn everything on that grid.
+- **"Sublevel 3"** is flavor only ([`LocationSite.site`](../src/types.ts)); `DUAL_SITE` = two pads on the **same** floor.
+- **Doors** are the only connectivity gate today; no stair/elevator tile or prefab anchor type.
+- **Renderer**: one tactical canvas; camera centers on player `(x,y)` ([`frame.ts`](../src/render/frame.ts)).
+
+There is **no latent z-axis** to flip on — this is a foundational coordinate-system change.
+
+---
+
+## What got easier since the deferral
+
+Real seams that reduce incremental cost (not multi-floor themselves):
+
+| Seam | Why it helps |
+|------|--------------|
+| **Site memory** (`LocationSite`: `mutationDeltas`, `seenKeys`) | Per-floor deltas/seen keys are a schema extension, not greenfield |
+| **Doors + terminals** | Pattern for gated transitions; stairs/elevators fit `Interactable` |
+| **`Entity.passable`** ([`Entity.ts`](../src/game/Entity.ts)) | Comment already reserves floor signs / location markers |
+| **`mapConnectivity`** | Reusable per-floor; extend for "spawn → stairs → exit on floor 2" |
+| **Dual-site / recon objectives** | Multi-anchor logic exists; needs floor-aware keys |
+| **Hub vs combat grids** ([`SafeSpace.ts`](../src/game/hub/SafeSpace.ts)) | Precedent for "swap active grid" at scene boundaries |
+
+---
+
+## Architectural fork (decide first)
+
+### Option A — Multiple grids + active floor index (recommended)
+
+```typescript
+type FloorId = number;
+World {
+  floors: Map<FloorId, Grid>;
+  activeFloor: FloorId;
+  entities: Map<string, Entity & { floor: FloorId }>;
+}
+```
+
+- **Pros:** Each floor keeps current map sizes (24×16); fog/pathfinding/LOS stay floor-local; matches "Sublevel 3" fiction.
+- **Cons:** Floor transitions are explicit; cross-floor queries need `floor` on every entity/coord key.
+
+### Option B — One mega-grid with floor as metadata
+
+- **Pros:** Minimal change to `Grid` API.
+- **Cons:** Breaks current size caps, camera, and "tower" feel; coord collisions; worse for persistence and revisit.
+
+**Recommendation:** Option A — matches how Hub already treats combat as a separate grid.
+
+---
+
+## Systems touched (breadth)
+
+Roughly **~35–45 production modules** and **~45 test files** assume single-floor `(x,y)`:
+
+| Layer | Files / areas | Work |
+|-------|---------------|------|
+| **Core model** | `Grid`, `World`, `types.ts`, `Entity`, `coordKey` helpers | Add `floor`; scope occupancy, blockers, movement |
+| **Simulation** | `Pathfinding`, `LineOfSight`, `Vision`, `Combat`, `slide`, `knockback`, `Smoke`, `mapConnectivity` | All queries scoped to `activeFloor` (or entity's floor) |
+| **AI** | All `src/game/ai/*`, `PatrolHostile`, `corpTurnDriver` | Design decision: simulate off-floor hostiles or freeze them? |
+| **Run lifecycle** | `Run.enterCombat`, `placement.ts`, objective placement, exit detection in `index.ts` | Multi-floor spawn, floor-aware exit, transition hooks |
+| **Mapgen** | [`mapBuild.ts`](../src/game/procgen/mapBuild.ts), prefabs, BSP | Largest greenfield chunk: per-floor layout + vertical links |
+| **Persistence** | `RunSnapshot`, `persistence.ts`, `Campaign`, `locations.ts` | `{ floor, x, y }` keys; migration for old saves |
+| **Input / shell** | `applyIntent.ts`, describe/look cursor, combat HUD | New intent: use stairs/elevator; floor indicator in HUD |
+| **Render** | `frame.ts`, `AsciiRenderer`, `cameraFor` | Show one floor at a time; optional floor label ("Sublevel 2") |
+
+[`coordKey`](../src/game/mapConnectivity.ts) appears in ~8 modules directly; ad-hoc `` `${x},${y}` `` strings appear in ~20+ more (AI blockers, frame entity index, vision seen sets).
+
+---
+
+## Suggested milestone breakdown
+
+### M0 — Design locks (~2–3 days)
+
+Decisions that change implementation size:
+
+1. **Off-floor hostiles:** frozen vs full sim vs "dormant until player enters floor"
+2. **Transition cost:** 1 AP interact? free? elevator requires keycard?
+3. **Cross-floor LOS/noise/alarm:** none (simplest) vs muffled vs full
+4. **Recon scope:** per-floor fog reset vs unified site memory
+5. **Max floors per contract:** 2 for MVP vs N
+
+### M1 — Foundation (~1 week)
+
+- `FloorId` + `LocatedPoint { floor, x, y }`
+- `coordKey(floor, x, y)` — single helper, replace ad-hoc strings
+- `World` multi-grid + `activeFloor` + floor-scoped `entityAt` / `canMoveEntity`
+- Snapshot schema v2 with save migration (default `floor: 0`)
+
+### M2 — Floor transitions (~3–5 days)
+
+- `Stairs` / `Elevator` interactable: `{ targetFloor, targetX, targetY }`
+- Player transition in `applyIntent` / `World.relocateEntity`
+- Reset or fork fog episode on floor change (`VisionField.resetFogState` pattern already exists)
+
+### M3 — Render + HUD (~3–5 days)
+
+- Frame builder reads `world.activeFloor` grid only
+- HUD floor label; combat log copy ("descends to Sublevel 3")
+- Input: interact on stair glyph when adjacent
+
+### M4 — Mapgen (thin vs full)
+
+**Thin (~1 week):** hand-authored 2-floor prefab pairs linked by fixed stair anchors; `buildMap` returns `{ floors: Grid[], links: FloorLink[] }`.
+
+**Full (~2–3 weeks):** BSP per floor, stair/elevator placement, `mapIsFullyConnectedFromSpawn` extended to multi-floor graph, prefab schema for vertical-link glyphs.
+
+### M5 — Objectives + site memory (~1 week)
+
+- Recon: `mapSeen` keys include floor
+- Retrieve/cache on floor 2; exit on floor 1
+- `LocationSite.seenKeys` / `mutationDeltas` floor-aware merge on extract/revisit
+
+### M6 — AI policy + tests (~1–2 weeks)
+
+- Pick off-floor behavior; update patrol paths per floor
+- Regression: pathfinding, LOS, recon, doors, breach restore, persistence round-trip
+- Procgen connectivity sweep per floor count
+
+---
+
+## Lower-cost alternatives (no multi-floor)
+
+Ways to honor "Sublevel 3" **flavor** without vertical simulation:
+
+- **Hidden pocket / false wall room** on one map (already supported by prefabs + doors)
+- **Separate contracts** for "Sublevel 2" vs "Sublevel 3" as `LocationSite` revisits with different seeds
+- **Taller 2D maps** (28×16, 30×18) for sniper verticality — already in [phase-2.7-plan.md](phase-2.7-plan.md)
+
+These do **not** deliver floor-switching tactics but cover some narrative gap at ~0 incremental architecture cost.
+
+---
+
+## Sequencing
+
+**Why wait for Phase 3 (or do MVP in parallel):**
+
+- Phase 3 adds **dual-control attention** — multi-floor Meatspace increases cognitive load while Cyberspace is also demanding.
+- No blueprint spec for cross-layer floor sync.
+- Phase 2.9 deferred **mixed encounters** for similar complexity reasons.
+
+**Why you could start now:**
+
+- Location persistence is ready — the original deferral condition is partially met.
+- "Sublevel 3 cache" and recon objectives would finally match their names.
+- M1–M3 are mostly orthogonal to Cyberspace if kept Meatspace-only.
+
+Suggested order: **Phase 3 Cyberspace → multi-floor MVP → full vertical maps**.
+
+If the goal is *"Sublevel 3 reads true in combat"* soon, start with **M0 design locks + M1 foundation + hand-authored 2-floor prefab** before investing in full procgen vertical connectivity.
+
+---
+
+## Risks
+
+| Risk | Severity |
+|------|----------|
+| Save migration / corrupt snapshots | High — tier-1 boundary territory per [AGENTS.md](../AGENTS.md) |
+| Recon soft-lock across floors | Medium — `mapConnectivity` must validate full graph |
+| Off-floor AI edge cases | Medium — alarm propagation, turret LOS across floors |
+| Test churn | Medium — ~45 test files construct flat grids |
+| Scope creep into Phase 3 | High — if Cyberspace needs "jack into floor-2 terminal" semantics |
+
+---
+
+## Bottom line
+
+Multi-floor is **not blocked by missing persistence anymore**, but it **is still a foundational coordinate-system change** touching mapgen, simulation, persistence, render, and input. A disciplined **2-floor MVP** is ~**2–3 weeks**; making it feel like a first-class Kernel Panic system (procgen, objectives, revisit memory, AI policy) is ~**5–8 weeks** — comparable to a slice the size of Phase 2.5 M6–M7.

From 49efaf2ac225b7371b4fe0909b44e79ecd6b8fdb Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Sun, 7 Jun 2026 18:33:57 -0700
Subject: [PATCH 02/55] campaign arc stage foundation

---
 docs/phase-3-plan.md             |  20 +++---
 src/game/Campaign.ts             |  65 ++++++++++++++++++-
 src/game/hub/Curator.ts          |  14 ++--
 src/game/persistence.ts          |  10 ++-
 src/types.ts                     |   3 +
 tests/unit/game/Campaign.test.ts | 106 +++++++++++++++++++++++++++++++
 6 files changed, 199 insertions(+), 19 deletions(-)

diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 6caeb6e..190c0c7 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -41,7 +41,7 @@ A new **player archetype** recruited mid-campaign (late Act 1 / start of Act 2),
 
 | Milestone | Status |
 |---|---|
-| P3.M1 — Campaign arc structure | 🔲 Planned |
+| P3.M1 — Campaign arc structure | 🚧 In progress — P3.M1.1 done |
 | P3.M2 — The Decker archetype | 🔲 Planned |
 | P3.M3 — Cyberspace grid + ICE | 🔲 Planned |
 | P3.M4 — Simstim flip (dual-deploy) | 🔲 Planned |
@@ -127,14 +127,16 @@ Neural degradation is deferred until Cyberspace is fun enough to deserve a jack-
 
 **Implementation slices:**
 
-| Slice | Change | Tests |
-|---|---|---|
-| **P3.M1.1 Arc record** | Add `Campaign.arc`, derive `arcStage`, persist/restore, normalize old saves to Act 1 | constructor validation, snapshot round-trip, invalid stage throws |
-| **P3.M1.2 Transitions** | Advance acts from `rep`, `completedJobs`, Decker flag, Score-site visit | boundary tests around job counts and rep tier |
-| **P3.M1.3 Score target** | Promote one roster site to `tier: 'score'`; preserve through eviction | exactly-one target, no eviction at roster cap, synthetic target when roster empty |
-| **P3.M1.4 Clock** | Start heat after threshold; hard loss at deadline; show status | heat math, deadline loss, no loss after Score attempt |
-| **P3.M1.5 Curator bias** | Pass campaign-derived arc context; bias board slots by act and score target | seeded boards show expected `arcStage` and target-site frequency |
-| **P3.M1.6 Score entry** | Hub action creates the special Score contract in Act 3 only | availability gates, deployment path, attempted flag |
+| Slice | Status | Change | Tests |
+|---|---|---|---|
+| **P3.M1.1 Arc record** | ✅ Done | Add `Campaign.arc`, derive `arcStage`, persist/restore, normalize old saves to Act 1 | constructor validation, snapshot round-trip, invalid stage throws |
+| **P3.M1.2 Transitions** | 🔲 Planned | Advance acts from `rep`, `completedJobs`, Decker flag, Score-site visit | boundary tests around job counts and rep tier |
+| **P3.M1.3 Score target** | 🔲 Planned | Promote one roster site to `tier: 'score'`; preserve through eviction | exactly-one target, no eviction at roster cap, synthetic target when roster empty |
+| **P3.M1.4 Clock** | 🔲 Planned | Start heat after threshold; hard loss at deadline; show status | heat math, deadline loss, no loss after Score attempt |
+| **P3.M1.5 Curator bias** | 🔲 Planned | Pass campaign-derived arc context; bias board slots by act and score target | seeded boards show expected `arcStage` and target-site frequency |
+| **P3.M1.6 Score entry** | 🔲 Planned | Hub action creates the special Score contract in Act 3 only | availability gates, deployment path, attempted flag |
+
+**P3.M1.1 implementation note:** `Campaign` now owns a typed `arc` record (`arcStage`, `deckerRecruited`, `scoreRevealed`, `clockStarted`, `scoreAttempted`, `scoreCompleted`) plus an `arcStage` getter for Curator context. New snapshots serialize the record; pre-P3 snapshots normalize to Act 1; malformed persisted arc data throws during restore instead of being silently repaired.
 
 **Acceptance:**
 
diff --git a/src/game/Campaign.ts b/src/game/Campaign.ts
index 89bbaac..86882e0 100644
--- a/src/game/Campaign.ts
+++ b/src/game/Campaign.ts
@@ -37,7 +37,7 @@ import {
 } from './locations.js';
 import type { Contract } from './hub/Curator.js';
 import type { Crew } from './Crew.js';
-import type { GridPoint, KeyItem, LocationSite, TileDelta } from '../types.js';
+import type { CampaignArcStage, GridPoint, KeyItem, LocationSite, TileDelta } from '../types.js';
 import type { RunResult, Outcome } from './Run.js';
 
 /** Max remembered combat locations (P2.5.M7.2). One slot is reserved for Phase 3's score target. */
@@ -57,6 +57,28 @@ export type CampaignState = (typeof CAMPAIGN_STATE)[keyof typeof CAMPAIGN_STATE]
 // type is a plain Record so they don't cause a type error on restore.
 export type CampaignMeta = Record<string, unknown>;
 
+export type CampaignArc = {
+  arcStage: CampaignArcStage;
+  deckerRecruited: boolean;
+  scoreRevealed: boolean;
+  clockStarted: boolean;
+  scoreAttempted: boolean;
+  scoreCompleted: boolean;
+};
+
+const CAMPAIGN_ARC_STAGES: readonly CampaignArcStage[] = ['act-1', 'act-2', 'act-3', 'score'];
+
+export function defaultCampaignArc(): CampaignArc {
+  return {
+    arcStage: 'act-1',
+    deckerRecruited: false,
+    scoreRevealed: false,
+    clockStarted: false,
+    scoreAttempted: false,
+    scoreCompleted: false,
+  };
+}
+
 export type CampaignOptions = {
   id?: string;
   seed?: unknown;
@@ -65,6 +87,7 @@ export type CampaignOptions = {
   credits?: unknown;
   rep?: unknown;
   meta?: unknown;
+  arc?: unknown;
   hubReveals?: unknown;
   completedJobs?: unknown;
   keyItems?: unknown;
@@ -116,6 +139,7 @@ export class Campaign {
   credits: number;
   rep: number;
   meta: CampaignMeta;
+  arc: CampaignArc;
   state: CampaignState;
   activeRun: Run | null;
   deployedMemberId: string | null;
@@ -153,6 +177,7 @@ export class Campaign {
     credits = 0,
     rep = REP.START,
     meta = {},
+    arc,
     hubReveals,
     completedJobs = 0,
     keyItems,
@@ -205,6 +230,7 @@ export class Campaign {
     this.credits = credits;
     this.rep = rep;
     this.meta = { ...(meta as CampaignMeta) };
+    this.arc = normalizeCampaignArc(arc);
     this.hubReveals = normalizeHubReveals(hubReveals, 'Campaign hubReveals');
     this.completedJobs = (completedJobs as number) ?? 0;
     this.keyItems = normalizeKeyItems(keyItems);
@@ -240,6 +266,10 @@ export class Campaign {
     }
   }
 
+  get arcStage(): CampaignArcStage {
+    return this.arc.arcStage;
+  }
+
   enterHub(): void {
     if (this.state !== CAMPAIGN_STATE.HUB && this.state !== CAMPAIGN_STATE.COMBAT) {
       throw new Error(`Campaign.enterHub: illegal transition from ${this.state}`);
@@ -1007,6 +1037,39 @@ function normalizeSiteRoster(raw: unknown): LocationSite[] {
   return raw.map(entry => normalizeLocationSite(entry));
 }
 
+export function isCampaignArcStage(value: unknown): value is CampaignArcStage {
+  return typeof value === 'string' && CAMPAIGN_ARC_STAGES.includes(value as CampaignArcStage);
+}
+
+export function normalizeCampaignArc(raw: unknown, context = 'Campaign arc'): CampaignArc {
+  if (raw === undefined) return defaultCampaignArc();
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new TypeError(`${context} must be an object when supplied`);
+  }
+
+  const candidate = raw as Partial<Record<keyof CampaignArc, unknown>>;
+  if (!isCampaignArcStage(candidate.arcStage)) {
+    throw new Error(`${context}.arcStage "${candidate.arcStage}" is not known`);
+  }
+
+  const readBooleanArcFlag = (flag: keyof Omit<CampaignArc, 'arcStage'>): boolean => {
+    const value = candidate[flag];
+    if (typeof value !== 'boolean') {
+      throw new TypeError(`${context}.${flag} must be boolean`);
+    }
+    return value;
+  };
+
+  return {
+    arcStage: candidate.arcStage,
+    deckerRecruited: readBooleanArcFlag('deckerRecruited'),
+    scoreRevealed: readBooleanArcFlag('scoreRevealed'),
+    clockStarted: readBooleanArcFlag('clockStarted'),
+    scoreAttempted: readBooleanArcFlag('scoreAttempted'),
+    scoreCompleted: readBooleanArcFlag('scoreCompleted'),
+  };
+}
+
 function makeCampaignId(seed: number): string {
   return `campaign-${(seed >>> 0).toString(16)}-${Date.now().toString(36)}`;
 }
diff --git a/src/game/hub/Curator.ts b/src/game/hub/Curator.ts
index 15c65d2..b789625 100644
--- a/src/game/hub/Curator.ts
+++ b/src/game/hub/Curator.ts
@@ -22,7 +22,7 @@ import { resolveMapDimensions } from '../procgen/mapDimensions.js';
 import type { Rng } from '../../rng.js';
 import type { EntityInit } from '../Entity.js';
 import type { ContractDifficulty } from '../constants.js';
-import type { LocationSite, LocationToken } from '../../types.js';
+import type { CampaignArcStage, LocationSite, LocationToken } from '../../types.js';
 
 export const OBJECTIVES = Object.freeze({
   REACH_EXIT: 'reach-exit',
@@ -46,8 +46,6 @@ export type ContractObjective = {
   params?: ObjectiveParams;
 };
 
-export type ContractArcStage = 'act-1' | 'act-2' | 'act-3' | 'score';
-
 export type ContractContextToken = {
   id: string;
   label: string;
@@ -62,7 +60,7 @@ export type ContractContext = {
   asset: ContractContextToken;
   action: ContractContextToken;
   tags: string[];
-  arcStage?: ContractArcStage;
+  arcStage?: CampaignArcStage;
   /**
    * References a `LocationSite.id` in the campaign roster when the Curator
    * targets a remembered site for a revisit (P2.5.M7.2). Distinct from the
@@ -73,7 +71,7 @@ export type ContractContext = {
 };
 
 type ContractRecipeContext = {
-  arcStage?: ContractArcStage;
+  arcStage?: CampaignArcStage;
 };
 
 type ContractToken = {
@@ -489,7 +487,7 @@ type ContractCampaign =
   | {
       rep?: number;
       meta?: Record<string, unknown>;
-      arcStage?: ContractArcStage | null;
+      arcStage?: CampaignArcStage | null;
       /** Remembered combat locations the Curator may steer revisits toward (P2.5.M7.2). */
       siteRoster?: LocationSite[];
     }
@@ -754,7 +752,7 @@ export function buildContractRecipeFixture({
   actionId: string;
   difficulty: ContractDifficulty;
   seed: number;
-  arcStage?: ContractArcStage;
+  arcStage?: CampaignArcStage;
 }): Contract {
   if (!isContractDifficulty(difficulty)) {
     throw new Error(`Curator fixture: unknown difficulty "${difficulty}"`);
@@ -895,7 +893,7 @@ function contractRecipeContext(campaign: ContractCampaign): ContractRecipeContex
   return arcStage ? { arcStage } : {};
 }
 
-function isArcStage(value: unknown): value is ContractArcStage {
+function isArcStage(value: unknown): value is CampaignArcStage {
   return value === 'act-1' || value === 'act-2' || value === 'act-3' || value === 'score';
 }
 
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index 34aeccf..98f018e 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -73,7 +73,7 @@ import { KeyCard } from './entities/KeyCard.js';
 import { BreachingCharge } from './entities/BreachingCharge.js';
 import type { BreachingChargeInit } from './entities/BreachingCharge.js';
 import { Run, RUN_STATE, PATROL_ARCHETYPE_IDS } from './Run.js';
-import { Campaign, CAMPAIGN_STATE } from './Campaign.js';
+import { Campaign, CAMPAIGN_STATE, normalizeCampaignArc } from './Campaign.js';
 import { normalizeContractContext, normalizeObjective } from './hub/Curator.js';
 import {
   migrateLegacyHubReveals,
@@ -97,6 +97,7 @@ import type { ConsumablePickupInit } from './entities/ConsumablePickup.js';
 import type { EscortNpcInit } from './entities/EscortNpc.js';
 import type { KeyCardInit } from './entities/KeyCard.js';
 import type { EntityInit } from './Entity.js';
+import type { CampaignArc } from './Campaign.js';
 import type { FactionId } from './constants.js';
 import type {
   CrewArchetypeId,
@@ -710,6 +711,8 @@ export type CampaignSnapshot = {
   credits?: number;
   rep: number;
   meta: CampaignMeta;
+  /** Phase 3 campaign arc state. Defaults to Act 1 for pre-P3 saves. */
+  arc?: CampaignArc;
   deployedMemberId: string | null;
   activeRun: CampaignActiveRunSnapshot | null;
   /** Recruit candidates available this hub visit. Defaults to [] for pre-P2.M6 saves. */
@@ -775,6 +778,7 @@ export function snapshotCampaign(campaign: Campaign): CampaignSnapshot {
     credits: campaign.credits,
     rep: campaign.rep,
     meta: { ...campaign.meta },
+    arc: { ...campaign.arc },
     deployedMemberId: campaign.deployedMemberId,
     activeRun: campaign.activeRun ? snapshotActiveRun(campaign.activeRun) : null,
     availableRecruits: campaign.availableRecruits.map(snapshotCrewMember),
@@ -920,6 +924,7 @@ export function restoreCampaign(record: unknown, options: RestoreCampaignOptions
     credits: record.credits ?? 0,
     rep: record.rep,
     meta: record.meta,
+    arc: record.arc,
     hubReveals: normalizeHubReveals(
       migrateLegacyHubReveals(record.hubReveals, {
         rep: record.rep,
@@ -1574,6 +1579,9 @@ function validateCampaignRecord(record: unknown): asserts record is CampaignSnap
   ) {
     throw new TypeError('restoreCampaign: meta must be an object');
   }
+  if (candidate.arc !== undefined) {
+    normalizeCampaignArc(candidate.arc, 'restoreCampaign arc');
+  }
   if (candidate.state === CAMPAIGN_STATE.COMBAT && !candidate.activeRun) {
     throw new Error('restoreCampaign: COMBAT state requires activeRun');
   }
diff --git a/src/types.ts b/src/types.ts
index 10b0b2b..8695a63 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -13,6 +13,9 @@
 /** Integer tile on the tactical grid. */
 export type GridPoint = { x: number; y: number };
 
+/** Phase 3 campaign arc stage, shared by Campaign saves and Curator contract context. */
+export type CampaignArcStage = 'act-1' | 'act-2' | 'act-3' | 'score';
+
 /**
  * A JSON-safe value. The persistence layer's opaque entity property bag
  * (`EntitySnapshotExtra`) is keyed to this so anything stashed in a snapshot
diff --git a/tests/unit/game/Campaign.test.ts b/tests/unit/game/Campaign.test.ts
index f2522ba..714d003 100644
--- a/tests/unit/game/Campaign.test.ts
+++ b/tests/unit/game/Campaign.test.ts
@@ -5,6 +5,7 @@ import {
   Campaign,
   CAMPAIGN_STATE,
   buildCrew,
+  defaultCampaignArc,
   willEndCampaignOnThisDeath,
 } from '../../../src/game/Campaign.js';
 import { OUTCOME, RUN_STATE } from '../../../src/game/Run.js';
@@ -52,6 +53,8 @@ test('Campaign starts in HUB with crew, salvage, credits, rep, and meta state',
   assert.equal(campaign.credits, 0);
   assert.equal(campaign.rep, 20);
   assert.deepEqual(campaign.meta, {});
+  assert.deepEqual(campaign.arc, defaultCampaignArc());
+  assert.equal(campaign.arcStage, 'act-1');
   assert.equal(campaign.crew.length, 3);
   assert.ok(campaign.world);
   assert.ok(campaign.player);
@@ -59,6 +62,63 @@ test('Campaign starts in HUB with crew, salvage, credits, rep, and meta state',
   assert.ok(campaign.terminal);
 });
 
+test('Campaign accepts and exposes a valid Phase 3 arc record', () => {
+  const campaign = new Campaign({
+    seed: 42,
+    arc: {
+      arcStage: 'act-2',
+      deckerRecruited: true,
+      scoreRevealed: true,
+      clockStarted: false,
+      scoreAttempted: false,
+      scoreCompleted: false,
+    },
+  });
+
+  assert.equal(campaign.arcStage, 'act-2');
+  assert.deepEqual(campaign.arc, {
+    arcStage: 'act-2',
+    deckerRecruited: true,
+    scoreRevealed: true,
+    clockStarted: false,
+    scoreAttempted: false,
+    scoreCompleted: false,
+  });
+});
+
+test('Campaign rejects malformed Phase 3 arc records', () => {
+  assert.throws(() => new Campaign({ seed: 42, arc: null }), /arc must be an object/i);
+  assert.throws(
+    () =>
+      new Campaign({
+        seed: 42,
+        arc: {
+          arcStage: 'act-x',
+          deckerRecruited: false,
+          scoreRevealed: false,
+          clockStarted: false,
+          scoreAttempted: false,
+          scoreCompleted: false,
+        },
+      }),
+    /arcStage/
+  );
+  assert.throws(
+    () =>
+      new Campaign({
+        seed: 42,
+        arc: {
+          arcStage: 'act-1',
+          deckerRecruited: false,
+          scoreRevealed: false,
+          clockStarted: false,
+          scoreAttempted: false,
+        },
+      }),
+    /scoreCompleted/
+  );
+});
+
 test('deployCrewMember starts a job Run for a non-flatlined crew member', () => {
   const campaign = new Campaign({ seed: 42 });
   const member = campaign.crew[0];
@@ -524,6 +584,52 @@ test('rep survives campaign snapshot/restore round-trip', () => {
   assert.equal(restored.rep, 35);
 });
 
+test('campaign arc survives persistence round-trip', () => {
+  const campaign = new Campaign({
+    seed: 42,
+    arc: {
+      arcStage: 'score',
+      deckerRecruited: true,
+      scoreRevealed: true,
+      clockStarted: true,
+      scoreAttempted: true,
+      scoreCompleted: false,
+    },
+  });
+
+  const snap = snapshotCampaign(campaign);
+  const restored = restoreCampaign(snap);
+
+  assert.deepEqual(snap.arc, campaign.arc);
+  assert.deepEqual(restored.arc, campaign.arc);
+  assert.equal(restored.arcStage, 'score');
+});
+
+test('pre-P3 campaign snapshots restore with a default Act 1 arc', () => {
+  const campaign = new Campaign({ seed: 42 });
+  const snap = snapshotCampaign(campaign) as Record<string, unknown>;
+  delete snap.arc;
+
+  const restored = restoreCampaign(snap as never);
+
+  assert.deepEqual(restored.arc, defaultCampaignArc());
+  assert.equal(restored.arcStage, 'act-1');
+});
+
+test('restoreCampaign rejects corrupt Phase 3 arc snapshots', () => {
+  const campaign = new Campaign({ seed: 42 });
+  const snap = snapshotCampaign(campaign);
+
+  assert.throws(
+    () => restoreCampaign({ ...snap, arc: { ...snap.arc, arcStage: 'bad-stage' } }),
+    /arcStage/
+  );
+  assert.throws(
+    () => restoreCampaign({ ...snap, arc: { ...snap.arc, scoreAttempted: 'yes' } }),
+    /scoreAttempted/
+  );
+});
+
 // ─── Recruitment ────────────────────────────────────────────────────────
 
 test('generateRecruits returns 1–2 candidates when Rep ≥ 65', () => {

From 42deb13f13c0f363e348a48311f724632e93eb6a Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Sun, 7 Jun 2026 19:31:40 -0700
Subject: [PATCH 03/55] Decker archetype

---
 docs/phase-3-plan.md                |  14 +-
 src/game/Hostile.ts                 |  20 ++-
 src/game/Run.ts                     |  15 ++-
 src/game/ai/PatrolHostile.ts        |   8 ++
 src/game/archetypes/Decker.ts       |  67 +++++++++
 src/game/archetypes/index.ts        |  20 ++-
 src/game/combatTurnPipeline.ts      |  33 +++++
 src/game/constants.ts               |  18 +++
 src/game/droneOverride.ts           | 178 ++++++++++++++++++++++++
 src/game/persistence.ts             |  45 ++++++-
 src/input/applyIntent.ts            |  74 +++++++++-
 tests/unit/game/Decker.test.ts      | 202 ++++++++++++++++++++++++++++
 tests/unit/game/archetypes.test.ts  |  31 +++++
 tests/unit/game/persistence.test.ts |  40 ++++++
 14 files changed, 748 insertions(+), 17 deletions(-)
 create mode 100644 src/game/archetypes/Decker.ts
 create mode 100644 src/game/droneOverride.ts
 create mode 100644 tests/unit/game/Decker.test.ts

diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 190c0c7..260c006 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -42,7 +42,7 @@ A new **player archetype** recruited mid-campaign (late Act 1 / start of Act 2),
 | Milestone | Status |
 |---|---|
 | P3.M1 — Campaign arc structure | 🚧 In progress — P3.M1.1 done |
-| P3.M2 — The Decker archetype | 🔲 Planned |
+| P3.M2 — The Decker archetype | 🚧 In progress — class + Drone Override Hack done; recruitment flow pending P3.M1.2 |
 | P3.M3 — Cyberspace grid + ICE | 🔲 Planned |
 | P3.M4 — Simstim flip (dual-deploy) | 🔲 Planned |
 | P3.M5 — The Score (climactic mission) | 🔲 Planned |
@@ -167,11 +167,13 @@ Neural degradation is deferred until Cyberspace is fun enough to deserve a jack-
 
 **Acceptance:**
 
-- Decker archetype playable in Meatspace: move, attack, interact, deploy — comparable to other archetypes.
-- Drone Override Hack: golden-path test — target drone, override succeeds, drone attacks corp allies for N turns, reverts or is destroyed.
-- Recruitment: gated by arc state; not available in Act 1; golden-path test for recruitment flow.
-- Snapshot: Decker state (including Cyberspace attributes) persists in campaign save; restore round-trip.
-- Key help: Decker glyph and ability description.
+- ✅ Decker archetype playable in Meatspace: move, attack, interact — comparable to other archetypes (`Decker` extends `Crew`, `baseHitChance` 0.7, `@` glyph).
+- ✅ Drone Override Hack: golden-path test — target drone, override succeeds, drone attacks corp allies for N turns, reverts or is destroyed (`droneOverride.ts`, `Decker.test.ts`). Failed roll burns AP and trips the alarm.
+- 🔲 Recruitment: gated by arc state; not available in Act 1; golden-path test for recruitment flow. **Deferred — needs P3.M1.2 act transitions.** Decker is registered but excluded from `ARCHETYPE_IDS` and `RECRUIT_ARCHETYPE_POOL` so random recruitment can't roll one early.
+- ✅ Snapshot: Decker state persists (campaign + run round-trip); live drone-override state round-trips through the patrol snapshot. Cyberspace attributes deferred to P3.M3.
+- ✅ Key help: Decker glyph (`@`) and OVERRIDE ability description via shared `ARCHETYPES[id].perkLabel`.
+
+**P3.M2 implementation note:** The Decker's signature **Override** reuses the unified `special` perk key — the intent layer's `doSpecial` sniffs `canOverride` and resolves a drone along the aim ray (`OVERRIDE_RANGE`, LOS-gated, like fire). A successful hijack flips the drone to `FACTION.PLAYER` for `OVERRIDE_DURATION` turns; the existing hostile AI then fights corp for free (it targets by faction difference). Override state lives on `Hostile` (`overrideTurnsRemaining`, `factionBeforeOverride`) and is driven each player turn by `stepOverriddenDrones`, a new combat-aftermath phase that steps the hijacked drone and reverts it when the countdown lapses. Mid-override saves round-trip through the patrol snapshot; half-populated override state throws on restore.
 
 ---
 
diff --git a/src/game/Hostile.ts b/src/game/Hostile.ts
index 10becef..44abda8 100644
--- a/src/game/Hostile.ts
+++ b/src/game/Hostile.ts
@@ -1,6 +1,6 @@
 import { Entity, type EntityInit } from './Entity.js';
 import { EscortNpc } from './entities/EscortNpc.js';
-import { FACTION, SIGHT_RANGE } from './constants.js';
+import { FACTION, SIGHT_RANGE, type FactionId } from './constants.js';
 import { hasLineOfSight, withinRange } from './LineOfSight.js';
 import type { Rng } from '../rng.js';
 import type { TurnActionStep } from '../types.js';
@@ -20,12 +20,30 @@ export interface HostileInit extends EntityInit {
 export abstract class Hostile extends Entity {
   sightRange: number;
 
+  /**
+   * Decker drone-override state (P3.M2). While `overrideTurnsRemaining > 0`
+   * this hostile has been hijacked: its `faction` is temporarily the
+   * overrider's (PLAYER) and `factionBeforeOverride` records the allegiance to
+   * restore when the override lapses. Both default to the not-overridden state
+   * so every existing hostile is unaffected. The countdown is ticked once per
+   * player turn by `stepOverriddenDrones` (see `droneOverride.ts`).
+   */
+  overrideTurnsRemaining: number;
+  factionBeforeOverride: FactionId | null;
+
   constructor({ sightRange = SIGHT_RANGE, ...props }: HostileInit) {
     if (!Number.isInteger(sightRange) || sightRange < 0) {
       throw new RangeError(`Hostile sightRange must be a non-negative integer, got ${sightRange}`);
     }
     super(props);
     this.sightRange = sightRange;
+    this.overrideTurnsRemaining = 0;
+    this.factionBeforeOverride = null;
+  }
+
+  /** Whether this hostile is currently flipped to the player's side. */
+  get isOverridden(): boolean {
+    return this.overrideTurnsRemaining > 0;
   }
 
   abstract override takeTurn(world: World, rng: Rng): void | TurnActionStep[];
diff --git a/src/game/Run.ts b/src/game/Run.ts
index 30f1e0c..75575d4 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -53,6 +53,7 @@ import { Crew } from './Crew.js';
 import { Merc } from './archetypes/Merc.js';
 import { Razor } from './archetypes/Razor.js';
 import { Tech } from './archetypes/Tech.js';
+import { Decker } from './archetypes/Decker.js';
 import { Turret } from './Turret.js';
 import { Skirmisher } from './ai/Skirmisher.js';
 import { Guard } from './ai/Guard.js';
@@ -136,7 +137,7 @@ const KNOWN_OUTCOMES = new Set(Object.values(OUTCOME));
 
 export type RunState = (typeof RUN_STATE)[keyof typeof RUN_STATE];
 export type Outcome = (typeof OUTCOME)[keyof typeof OUTCOME];
-export type CrewArchetypeId = 'merc' | 'razor' | 'tech';
+export type CrewArchetypeId = 'merc' | 'razor' | 'tech' | 'decker';
 export type EntityArchetypeId =
   | CrewArchetypeId
   | 'turret'
@@ -1602,12 +1603,19 @@ function exitTileInWorld(world: World): GridPoint | null {
 
 /** Shared patrol state-machine slice (Skirmisher, Guard, Bruiser, …). */
 function patrolSnapshotExtra(e: PatrolHostile): PatrolSnapshot {
-  return {
+  const snap: PatrolSnapshot = {
     state: e.state,
     lastKnownTarget: e.lastKnownTarget ? { x: e.lastKnownTarget.x, y: e.lastKnownTarget.y } : null,
     patrolWaypoints: e.patrolWaypoints.map(wp => ({ x: wp.x, y: wp.y })),
     patrolIndex: e.patrolIndex,
   };
+  // Only serialise override fields while the hijack is live — keeps the common
+  // (never-overridden) snapshot identical to its pre-P3 shape.
+  if (e.isOverridden) {
+    snap.overrideTurnsRemaining = e.overrideTurnsRemaining;
+    snap.factionBeforeOverride = e.factionBeforeOverride;
+  }
+  return snap;
 }
 
 /** Shared crew slice (Merc, Razor, Tech). Inventory/Gear are JSON-safe at runtime. */
@@ -1634,6 +1642,7 @@ const SNAPSHOT_EXTRACTORS: Partial<Record<EntityArchetypeId, (e: Entity) => Enti
   {
     merc: e => crewSnapshotExtra(e as Crew) as unknown as EntitySnapshotExtra,
     razor: e => crewSnapshotExtra(e as Crew) as unknown as EntitySnapshotExtra,
+    decker: e => crewSnapshotExtra(e as Crew) as unknown as EntitySnapshotExtra,
     tech: e =>
       ({
         ...crewSnapshotExtra(e as Crew),
@@ -1757,6 +1766,7 @@ function archetypeOf(entity: Entity): EntityArchetypeId {
   if (entity instanceof Merc) return 'merc';
   if (entity instanceof Razor) return 'razor';
   if (entity instanceof Tech) return 'tech';
+  if (entity instanceof Decker) return 'decker';
   if (entity instanceof Turret) return 'turret';
   if (entity instanceof Bruiser) return 'bruiser';
   if (entity instanceof Juggernaut) return 'juggernaut';
@@ -2259,6 +2269,7 @@ function archetypeOfCrew(entity: Entity): CrewArchetypeId {
   if (entity instanceof Merc) return 'merc';
   if (entity instanceof Razor) return 'razor';
   if (entity instanceof Tech) return 'tech';
+  if (entity instanceof Decker) return 'decker';
   throw new Error(
     `archetypeOfCrew: cannot classify crew member ${(entity as Entity | undefined)?.id}`
   );
diff --git a/src/game/ai/PatrolHostile.ts b/src/game/ai/PatrolHostile.ts
index e3eb064..d42534c 100644
--- a/src/game/ai/PatrolHostile.ts
+++ b/src/game/ai/PatrolHostile.ts
@@ -66,6 +66,14 @@ export type PatrolSnapshot = {
   lastKnownTarget: GridPoint | null;
   patrolWaypoints: GridPoint[];
   patrolIndex: number;
+  /**
+   * Decker drone-override state (P3.M2). Present only while a hostile is
+   * hijacked: `overrideTurnsRemaining > 0` and `factionBeforeOverride` records
+   * the allegiance to restore. Omitted (and defaulted to the not-overridden
+   * state on restore) for the overwhelming majority of hostiles.
+   */
+  overrideTurnsRemaining?: number;
+  factionBeforeOverride?: FactionId | null;
 };
 
 type NoiseEventPayload = {
diff --git a/src/game/archetypes/Decker.ts b/src/game/archetypes/Decker.ts
new file mode 100644
index 0000000..738e314
--- /dev/null
+++ b/src/game/archetypes/Decker.ts
@@ -0,0 +1,67 @@
+import { Crew } from '../Crew.js';
+import { canOverride, overrideDrone } from '../droneOverride.js';
+import type { CrewInit } from '../Crew.js';
+import type { Entity } from '../Entity.js';
+import type { World } from '../World.js';
+import type { Rng } from '../../rng.js';
+
+/**
+ * Curated callsign pool for the Decker archetype. See `Merc.js` CALLSIGNS for
+ * the design rationale. Decker names lean console-cowboy / matrix-jockey to
+ * match the Cyberspace specialist fantasy (Phase 3).
+ */
+export const CALLSIGNS = Object.freeze([
+  'Case',
+  'Jack',
+  'Flatline',
+  'Blitz',
+  'Is0bel',
+  'Bytesize',
+  'Crash',
+  'Ang3l',
+  'Z0ne',
+  'Neo',
+]);
+
+/**
+ * Decker — Cyberspace specialist (P3.M2), recruited mid-campaign rather than
+ * picked at start. In Meatspace they are *viable but not optimised*: baseline
+ * ranged kit with a slightly lower hit chance than the combat archetypes
+ * (Merc 0.8, Tech 0.75, Razor 0.7). Their real edge is digital — and, on the
+ * physical grid, the signature **Drone Override Hack**.
+ *
+ * Phase-3 perk: **Override**. Reaches across a clean LOS lane to hijack a corp
+ * drone's allegiance for a few turns (`droneOverride.ts`). It is a *targeted*
+ * perk — the intent layer resolves a drone along the aim ray, then calls
+ * `overrideDrone`. Cyberspace attributes (RAM, intrusion strength, ICE
+ * resistance) are deferred to P3.M3, when the Cyberspace grid consumes them.
+ */
+export class Decker extends Crew {
+  override archetype = 'Decker';
+
+  override get baseHitChance(): number {
+    return 0.7;
+  }
+
+  constructor(props: CrewInit) {
+    super({ ...props, glyph: '@' });
+  }
+
+  /**
+   * Pre-flight legality check for overriding `target`. Returns `{ ok }` or
+   * `{ ok: false, reason }`, mirroring the other archetype perks. Delegates to
+   * the shared `droneOverride` module so the rules live in one place.
+   */
+  canOverride(world: World, target: Entity | null) {
+    return canOverride(world, this, target);
+  }
+
+  /**
+   * Commit an override against `target`. Throws on illegal pre-conditions
+   * (no AP burned); on a legal attempt, debits AP and either flips the drone
+   * or trips the alarm depending on the roll. Returns the {@link OverrideResult}.
+   */
+  overrideDrone(world: World, target: Entity, rng: Rng) {
+    return overrideDrone(world, this, target, rng);
+  }
+}
diff --git a/src/game/archetypes/index.ts b/src/game/archetypes/index.ts
index 11cb1b9..4a75600 100644
--- a/src/game/archetypes/index.ts
+++ b/src/game/archetypes/index.ts
@@ -22,22 +22,30 @@
 import { Merc, CALLSIGNS as MERC_CALLSIGNS } from './Merc.js';
 import { Razor, CALLSIGNS as RAZOR_CALLSIGNS } from './Razor.js';
 import { Tech, CALLSIGNS as TECH_CALLSIGNS } from './Tech.js';
+import { Decker, CALLSIGNS as DECKER_CALLSIGNS } from './Decker.js';
 import type { Rng } from '../../rng.js';
 import type { FactionId } from '../constants.js';
 import type { CrewInit } from '../Crew.js';
 
-export type Archetype = Merc | Razor | Tech;
+export type Archetype = Merc | Razor | Tech | Decker;
 
 /**
  * Display order is also the starter crew order in `Campaign.buildCrew`.
  * Merc first so new players hit the simpler ranged archetype on first load;
  * Tech last since its gadget loop is the most involved kit to learn.
+ *
+ * The **Decker is deliberately absent** (P3.M2): it is a mid-campaign narrative
+ * recruit, never a starter pick or selector option. Its metadata still lives in
+ * `ARCHETYPES`/`BUILDERS` so `buildCrewMember('decker', …)` and snapshot
+ * round-trips work — it just isn't offered through the normal selection paths.
  */
 export const ARCHETYPE_IDS = Object.freeze(['merc', 'razor', 'tech']);
 
 /**
  * Weighted archetype pool for recruitment. 40% Merc, 40% Razor, 20% Tech.
  * Expressed as a flat array so `rng.pick()` gives the correct distribution.
+ * The Decker is **not** in this pool — normal random recruitment must never
+ * roll one; it joins only through the Act-2 narrative beat (P3.M2 / P3.M1).
  */
 export const RECRUIT_ARCHETYPE_POOL = Object.freeze(['merc', 'merc', 'razor', 'razor', 'tech']);
 
@@ -73,6 +81,14 @@ export const ARCHETYPES = Object.freeze({
     perkName: 'DEPLOY',
     perkLabel: 'Techs can DEPLOY: place a turret that will fire on enemies',
   }),
+  decker: Object.freeze({
+    id: 'decker',
+    name: 'DECKER',
+    blurb: 'Console cowboy. Hijacks corp drones; jacks into Cyberspace.',
+    perks: Object.freeze(['override']),
+    perkName: 'OVERRIDE',
+    perkLabel: 'Deckers can OVERRIDE: hijack a corp drone to fight for you',
+  }),
 });
 
 export type ArchetypeInfo = (typeof ARCHETYPES)[keyof typeof ARCHETYPES];
@@ -81,6 +97,7 @@ const BUILDERS = Object.freeze({
   merc: Merc,
   razor: Razor,
   tech: Tech,
+  decker: Decker,
 });
 
 /**
@@ -93,6 +110,7 @@ export const CALLSIGNS_BY_ARCHETYPE = Object.freeze({
   merc: MERC_CALLSIGNS,
   razor: RAZOR_CALLSIGNS,
   tech: TECH_CALLSIGNS,
+  decker: DECKER_CALLSIGNS,
 });
 
 export function isArchetypeId(value: string) {
diff --git a/src/game/combatTurnPipeline.ts b/src/game/combatTurnPipeline.ts
index 0da4468..581c025 100644
--- a/src/game/combatTurnPipeline.ts
+++ b/src/game/combatTurnPipeline.ts
@@ -7,6 +7,8 @@ import { EVENT } from './events.js';
 import { chebyshev, findPath } from './Pathfinding.js';
 import { detonateBreachingCharge } from './breachBlast.js';
 import { BreachingCharge } from './entities/BreachingCharge.js';
+import { stepOverriddenDrones, type OverriddenDroneAction } from './droneOverride.js';
+import type { Hostile } from './Hostile.js';
 import type { BlastCasualty } from './breachBlast.js';
 import type { Entity } from './Entity.js';
 import type { NeutralCivilianTurnStep } from '../types.js';
@@ -65,9 +67,16 @@ export type BreachDetonateAftermathStep = {
   casualties: BlastCasualty[];
 };
 
+export type OverriddenDroneAftermathStep = {
+  type: 'overridden-drone';
+  entity: Hostile;
+  action: OverriddenDroneAction;
+};
+
 export type PlayerAftermathStep =
   | BreachDetonateAftermathStep
   | TurretAftermathStep
+  | OverriddenDroneAftermathStep
   | NeutralCivilianAftermathStep
   | EscortAftermathStep
   | HazardAftermathStep;
@@ -89,6 +98,9 @@ export function isPlayerAftermathStepLogVisible(
     }
     return isTileVisible(turret.x, turret.y);
   }
+  if (step.type === 'overridden-drone') {
+    return isTileVisible(step.entity.x, step.entity.y);
+  }
   if (step.type === 'neutral-civilian') {
     return isTileVisible(step.entity.x, step.entity.y);
   }
@@ -320,6 +332,13 @@ export function* runPlayerAftermathSteps(
       };
     }
   }
+  // Phase 1b: overridden drones act on the player's side, then their hijack
+  // countdown ticks and they revert when it lapses (P3.M2). They are
+  // player-aligned automated combatants — same aftermath slot as turrets.
+  for (const { entity, action } of stepOverriddenDrones(world, rng)) {
+    yield { type: 'overridden-drone', entity, action };
+  }
+
   // Phase 2: neutral civilian reactions (flee / panic / idle based on rep)
   const rep = opts?.rep ?? REP.START;
   for (const entity of world.entities.values()) {
@@ -397,6 +416,9 @@ export function formatPlayerAftermathStepLogLines(step: PlayerAftermathStep) {
     const line = formatTurretAutofireLine(step.turret, step.action);
     return line ? [line] : [];
   }
+  if (step.type === 'overridden-drone') {
+    return formatOverriddenDroneLine(step);
+  }
   if (step.type === 'neutral-civilian') {
     return formatNeutralCivilianLine(step.entity, step.step);
   }
@@ -530,6 +552,17 @@ function validatePlayerAftermathDriverCtx(
   }
 }
 
+function formatOverriddenDroneLine(step: OverriddenDroneAftermathStep): string[] {
+  const label = entityLabel(step.entity);
+  if (step.action.type === 'override-expired') {
+    return [`${label} shakes off the override — back under corp control.`];
+  }
+  // The drone's individual combat outcome surfaces through ENTITY_DAMAGED
+  // listeners (same as corp-turn steps); here we only note that the hijacked
+  // unit is acting on our side.
+  return [`${label} (overridden) acts.`];
+}
+
 function formatNeutralCivilianLine(
   entity: NeutralCivilian,
   step: NeutralCivilianTurnStep
diff --git a/src/game/constants.ts b/src/game/constants.ts
index 8cf284b..61e277a 100644
--- a/src/game/constants.ts
+++ b/src/game/constants.ts
@@ -75,8 +75,26 @@ export const AP_COST = Object.freeze({
   VAULT: 2, // Merc — hop a cover tile while firing
   SLIDE: 2, // Razor — 2-tile reposition with stealth bonus
   DEPLOY: 2, // Tech — place a turret on an adjacent tile
+  OVERRIDE: 2, // Decker — hijack a corp drone's allegiance
 });
 
+/**
+ * Decker drone-override parameters (P3.M2). The Decker's signature Meatspace
+ * ability flips a corp drone to the player's side for a few turns by reusing
+ * the existing drone AI with a faction swap (the AI targets by faction, so a
+ * flipped drone fights its former allies for free).
+ *
+ *   - `OVERRIDE_RANGE` — reach for the intrusion, matched to baseline SIGHT so
+ *     the Decker must have a clean LOS lane like a ranged shot.
+ *   - `OVERRIDE_DURATION` — turns the drone stays player-aligned before its
+ *     firmware reasserts control and it reverts to its original faction.
+ *   - `OVERRIDE_SUCCESS_CHANCE` — probability the intrusion takes. A failed
+ *     attempt still burns AP and trips the facility alarm.
+ */
+export const OVERRIDE_RANGE = 5;
+export const OVERRIDE_DURATION = 3;
+export const OVERRIDE_SUCCESS_CHANCE = 0.6;
+
 /**
  * Tech turret parameters. The turret is a placed grid entity (peer of
  * `Entity`, not an archetype) deployed by Tech at `AP_COST.DEPLOY`. Tunables:
diff --git a/src/game/droneOverride.ts b/src/game/droneOverride.ts
new file mode 100644
index 0000000..c0a7a79
--- /dev/null
+++ b/src/game/droneOverride.ts
@@ -0,0 +1,178 @@
+/**
+ * Drone Override Hack (P3.M2) — the Decker's signature Meatspace ability.
+ *
+ * The Decker reaches out across a clean line of sight and hijacks a corp
+ * drone's allegiance. On success the drone's `faction` flips to the Decker's
+ * (PLAYER) for {@link OVERRIDE_DURATION} turns; because the existing hostile AI
+ * acquires targets purely by faction difference (`Hostile.isHostileTo`), a
+ * flipped drone immediately fights its former allies with *zero* new AI code.
+ * When the countdown lapses, the drone's firmware reasserts control and it
+ * reverts to whatever faction it held before.
+ *
+ * State lives on the hostile itself (`overrideTurnsRemaining`,
+ * `factionBeforeOverride`) so it round-trips through the patrol snapshot. This
+ * module owns the *verbs*: the legality check, the commit (with the success
+ * roll + alarm-on-failure), and the per-turn stepping/revert that the combat
+ * aftermath drives. Keeping it here mirrors `slide.ts` — the archetype class
+ * stays a thin delegator and the pipeline stays a thin caller.
+ */
+
+import { Hostile } from './Hostile.js';
+import { hasLineOfSight, withinRange } from './LineOfSight.js';
+import {
+  AP_COST,
+  OVERRIDE_DURATION,
+  OVERRIDE_RANGE,
+  OVERRIDE_SUCCESS_CHANCE,
+  type FactionId,
+} from './constants.js';
+import type { Entity } from './Entity.js';
+import type { World } from './World.js';
+import type { Rng } from '../rng.js';
+import type { TurnActionStep } from '../types.js';
+
+/** Pre-flight legality verdict, mirroring the Tech/Razor/Merc perk shape. */
+export type OverrideCheck = { ok: true } | { ok: false; reason: OverrideDenyReason };
+
+export type OverrideDenyReason =
+  | 'dead'
+  | 'insufficient-ap'
+  | 'not-overridable'
+  | 'dead-target'
+  | 'already-overridden'
+  | 'friendly'
+  | 'out-of-range'
+  | 'no-los';
+
+/** Result of a committed override attempt. */
+export type OverrideResult = {
+  ok: true;
+  /** Whether the intrusion took. On false the alarm was raised. */
+  success: boolean;
+  /** The success roll, surfaced for log copy / determinism tests. */
+  roll: number;
+  alarm: boolean;
+};
+
+/**
+ * Pure legality check. Returns `{ ok }` or `{ ok: false, reason }`; never
+ * mutates. `decker` is the overriding crew member (any PLAYER-faction
+ * operator); `target` is the entity it is aiming at.
+ *
+ * Only a live, in-range, line-of-sight `Hostile` of a *different* faction that
+ * is not already overridden can be hijacked. A non-Hostile target (terminal,
+ * civilian, turret) is `not-overridable` rather than a thrown error — the
+ * picker may legitimately land on one and we want a legible deny, not a crash.
+ */
+export function canOverride(world: World, decker: Entity, target: Entity | null): OverrideCheck {
+  if (!decker.alive) return { ok: false, reason: 'dead' };
+  if (!decker.canAfford(AP_COST.OVERRIDE)) return { ok: false, reason: 'insufficient-ap' };
+  if (!(target instanceof Hostile)) return { ok: false, reason: 'not-overridable' };
+  if (!target.alive) return { ok: false, reason: 'dead-target' };
+  if (target.isOverridden) return { ok: false, reason: 'already-overridden' };
+  if (target.faction === decker.faction) return { ok: false, reason: 'friendly' };
+  if (!withinRange(decker.x, decker.y, target.x, target.y, OVERRIDE_RANGE)) {
+    return { ok: false, reason: 'out-of-range' };
+  }
+  if (
+    !hasLineOfSight(world.grid, decker.x, decker.y, target.x, target.y, {
+      blockers: world.blockerKeys(),
+    })
+  ) {
+    return { ok: false, reason: 'no-los' };
+  }
+  return { ok: true };
+}
+
+/**
+ * Commit an override attempt. Throws on illegal pre-conditions *before*
+ * mutating any state (no AP burned). On a legal attempt: debits
+ * `AP_COST.OVERRIDE`, rolls against {@link OVERRIDE_SUCCESS_CHANCE}, and either
+ * flips the drone (success) or trips the facility alarm (failure). A failed
+ * hack still costs AP — the intrusion was noisy whether or not it landed.
+ */
+export function overrideDrone(
+  world: World,
+  decker: Entity,
+  target: Entity,
+  rng: Rng
+): OverrideResult {
+  const check = canOverride(world, decker, target);
+  if (!check.ok) {
+    throw new Error(`Illegal override for ${decker.id}: ${check.reason}`);
+  }
+  decker.spendAp(AP_COST.OVERRIDE);
+  const roll = rng.next();
+  const success = roll < OVERRIDE_SUCCESS_CHANCE;
+  if (success) {
+    applyOverride(target as Hostile, decker.faction);
+    return { ok: true, success: true, roll, alarm: false };
+  }
+  // A botched intrusion pings the building's security net.
+  const raised = world.raiseAlarm({ source: decker, repPenalty: false });
+  return { ok: true, success: false, roll, alarm: raised };
+}
+
+/** Flip a hostile to `overriderFaction` for the full override duration. */
+export function applyOverride(target: Hostile, overriderFaction: FactionId): void {
+  target.factionBeforeOverride = target.faction;
+  target.faction = overriderFaction;
+  target.overrideTurnsRemaining = OVERRIDE_DURATION;
+}
+
+/**
+ * Restore a hostile's original allegiance. Throws if there is no recorded
+ * pre-override faction — reverting an entity we never overrode is corrupt
+ * bookkeeping, not a recoverable situation.
+ */
+export function revertOverride(target: Hostile): void {
+  if (target.factionBeforeOverride === null) {
+    throw new Error(`revertOverride: ${target.id} has no factionBeforeOverride to restore`);
+  }
+  target.faction = target.factionBeforeOverride;
+  target.factionBeforeOverride = null;
+  target.overrideTurnsRemaining = 0;
+}
+
+/** One action emitted by an overridden drone during the player aftermath. */
+export type OverriddenDroneAction = TurnActionStep | { type: 'override-expired' };
+
+/**
+ * Step every currently-overridden drone through one turn on the player's side,
+ * then tick its countdown and revert it when the override lapses. Yields one
+ * entry per committed action so the aftermath pipeline can pace + log it, plus
+ * a synthetic `override-expired` action when a drone snaps back to corp.
+ *
+ * Dead overridden drones are skipped (their corpse needs no turn and no
+ * revert). The live entity list is snapshotted up front so a drone that kills
+ * a corp unit mid-turn can't perturb the iteration.
+ */
+export function* stepOverriddenDrones(
+  world: World,
+  rng: Rng
+): Generator<{ entity: Hostile; action: OverriddenDroneAction }, void, undefined> {
+  const overridden: Hostile[] = [];
+  for (const e of world.entities.values()) {
+    if (e instanceof Hostile && e.isOverridden && e.alive) overridden.push(e);
+  }
+  for (const drone of overridden) {
+    if (!drone.alive) continue; // may have died earlier in this aftermath pass
+    // Corp drones are PatrolHostiles with a step generator; fall back to the
+    // synchronous `takeTurn` for any future hostile that lacks one.
+    if (typeof drone.takeTurnSteps === 'function') {
+      for (const step of drone.takeTurnSteps(world, rng)) {
+        yield { entity: drone, action: step };
+      }
+    } else if (typeof drone.takeTurn === 'function') {
+      const steps = drone.takeTurn(world, rng);
+      if (Array.isArray(steps)) {
+        for (const step of steps) yield { entity: drone, action: step };
+      }
+    }
+    drone.overrideTurnsRemaining -= 1;
+    if (drone.overrideTurnsRemaining <= 0) {
+      revertOverride(drone);
+      yield { entity: drone, action: { type: 'override-expired' } };
+    }
+  }
+}
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index 98f018e..626f92f 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -47,6 +47,7 @@ import { Crew } from './Crew.js';
 import { Merc } from './archetypes/Merc.js';
 import { Razor } from './archetypes/Razor.js';
 import { Tech } from './archetypes/Tech.js';
+import { Decker } from './archetypes/Decker.js';
 import { Turret } from './Turret.js';
 import { Skirmisher, type SkirmisherProps } from './ai/Skirmisher.js';
 import { Guard, type GuardProps } from './ai/Guard.js';
@@ -179,6 +180,7 @@ const ARCHETYPE_FACTORY: Record<EntityArchetypeId, (props: RestoreEntityProps) =
     merc: (props: RestoreEntityProps) => new Merc(props as CrewInit),
     razor: (props: RestoreEntityProps) => new Razor(props as CrewInit),
     tech: (props: RestoreEntityProps) => new Tech(props as CrewInit),
+    decker: (props: RestoreEntityProps) => new Decker(props as CrewInit),
     turret: (props: RestoreEntityProps) => new Turret(props as TurretInit),
     drone: (props: RestoreEntityProps) => new Skirmisher(props as SkirmisherProps),
     guard: (props: RestoreEntityProps) => new Guard(props as GuardProps),
@@ -475,6 +477,46 @@ function restorePatrolState(
     }
     entity.patrolIndex = len > 0 ? idx : 0;
   }
+  restoreOverrideState(entity, patrol, rec);
+}
+
+/**
+ * Re-apply Decker drone-override bookkeeping (P3.M2). The two fields travel as
+ * a pair: a live hijack has a positive countdown *and* a recorded prior
+ * faction. Either one present without the other — or a countdown that isn't a
+ * positive integer, or a prior faction that isn't a known faction — is corrupt
+ * mid-override state and throws, rather than silently restoring a drone that
+ * can never revert.
+ */
+function restoreOverrideState(
+  entity: PatrolHostile,
+  patrol: Partial<PatrolSnapshot>,
+  rec: RunEntitySnapshot
+): void {
+  const hasTurns = patrol.overrideTurnsRemaining !== undefined;
+  const hasPrior =
+    patrol.factionBeforeOverride !== undefined && patrol.factionBeforeOverride !== null;
+  if (!hasTurns && !hasPrior) return;
+  if (hasTurns !== hasPrior) {
+    throw new Error(
+      `restore: ${rec.archetype} ${rec.id} override state is half-populated ` +
+        `(turns=${patrol.overrideTurnsRemaining}, prior=${patrol.factionBeforeOverride})`
+    );
+  }
+  const turns = patrol.overrideTurnsRemaining as number;
+  if (!Number.isInteger(turns) || turns <= 0) {
+    throw new RangeError(
+      `restore: ${rec.archetype} ${rec.id} overrideTurnsRemaining must be a positive integer, got ${turns}`
+    );
+  }
+  const prior = patrol.factionBeforeOverride as FactionId;
+  if (!KNOWN_FACTIONS.has(prior)) {
+    throw new Error(
+      `restore: ${rec.archetype} ${rec.id} factionBeforeOverride "${prior}" is not a known faction`
+    );
+  }
+  entity.overrideTurnsRemaining = turns;
+  entity.factionBeforeOverride = prior;
 }
 
 type RestoreEntry = {
@@ -1168,7 +1210,7 @@ function validateRecord(record: unknown): asserts record is RunSnapshot {
   }
 }
 
-const KNOWN_ARCHETYPES_SET = new Set<CrewArchetypeId>(['merc', 'razor', 'tech']);
+const KNOWN_ARCHETYPES_SET = new Set<CrewArchetypeId>(['merc', 'razor', 'tech', 'decker']);
 
 /** Clamp gear bonuses to archetype caps after restore. */
 function repairGearForCrew(member: Crew) {
@@ -1620,6 +1662,7 @@ function archetypeOfCrew(member: Crew): CrewArchetypeId {
   if (member instanceof Merc) return 'merc';
   if (member instanceof Razor) return 'razor';
   if (member instanceof Tech) return 'tech';
+  if (member instanceof Decker) return 'decker';
   throw new Error(`snapshotCampaign: cannot classify crew member ${member?.id}`);
 }
 
diff --git a/src/input/applyIntent.ts b/src/input/applyIntent.ts
index 1d8ee32..e5a3ccb 100644
--- a/src/input/applyIntent.ts
+++ b/src/input/applyIntent.ts
@@ -18,11 +18,13 @@
  * automation can commit a melee strike without synthesizing a walk intent.
  *
  * The archetype-specific perks (Merc's Vault, Razor's Slide, Tech's Deploy
- * Turret) collapse into a single `special` intent at the keymap layer. The
- * `doSpecial` dispatcher below routes it to the right verb based on which
- * methods the active player class exposes — `canVault` → vault, `canSlide` →
- * slide, `canDeploy` → deploy. This keeps the input surface symmetric across
- * archetypes (one key, one touch button) and stays out of the player's way:
+ * Turret, Decker's Override) collapse into a single `special` intent at the
+ * keymap layer. The `doSpecial` dispatcher below routes it to the right verb
+ * based on which methods the active player class exposes — `canVault` → vault,
+ * `canSlide` → slide, `canDeploy` → deploy, `canOverride` → override (the
+ * Decker resolves a drone along the aim ray, like fire). This keeps the input
+ * surface symmetric across archetypes (one key, one touch button) and stays
+ * out of the player's way:
  * the keymap doesn't need to know which class is in play, and the intent
  * dispatcher doesn't need an explicit archetype switch.
  *
@@ -39,7 +41,13 @@
  * harness assumption.
  */
 
-import { FACTION, SIGHT_RANGE, VAULT_DAMAGE, NOISE_RADIUS } from '../game/constants.js';
+import {
+  FACTION,
+  SIGHT_RANGE,
+  VAULT_DAMAGE,
+  NOISE_RADIUS,
+  OVERRIDE_RANGE,
+} from '../game/constants.js';
 import { totalSalvage, formatSalvageCompact } from '../game/salvage.js';
 import { canFireRanged, resolveRanged, canMelee, resolveMelee } from '../game/Combat.js';
 import { isConcealedFromPlayer } from '../game/playerPerception.js';
@@ -58,6 +66,7 @@ import type { Rng } from '../rng.js';
 import type { Tech } from '../game/archetypes/Tech.js';
 import type { Merc } from '../game/archetypes/Merc.js';
 import type { Razor } from '../game/archetypes/Razor.js';
+import type { Decker } from '../game/archetypes/Decker.js';
 
 export type Intent = {
   type: string;
@@ -347,9 +356,62 @@ function doSpecial(intent: Intent, ctx: ApplyIntentContext) {
   if (typeof (player as Razor).canSlide === 'function') {
     return doSlide(intent, ctx);
   }
+  if (typeof (player as Decker).canOverride === 'function') {
+    return doOverride(intent, ctx);
+  }
   log('> SPECIAL: this archetype has no perk action.');
 }
 
+/**
+ * Walk the aim ray for the Decker's Override perk and resolve the first hostile
+ * drone in reach, then attempt the hijack. Mirrors `pickFireTarget`'s geometry
+ * (bounded by `OVERRIDE_RANGE`, LOS-gated) so the target the picker lands on is
+ * exactly the one the resolver will act on. A failed roll trips the alarm; an
+ * out-of-reach ray or non-drone target yields a legible deny, not a crash.
+ */
+function doOverride(intent: Intent, ctx: ApplyIntentContext) {
+  const { world, player, log } = ctx;
+  const decker = player as Decker;
+  const playerLabel = entityLabel(player);
+  const target = pickOverrideTarget(ctx, intent.dx!, intent.dy!);
+  const check = decker.canOverride(world, target);
+  if (!check.ok) {
+    log(`> ${playerLabel} OVERRIDE DENIED: ${check.reason}`);
+    return;
+  }
+  const result = decker.overrideDrone(world, target!, ctx.rng);
+  const targetLabel = entityLabel(target!);
+  if (result.success) {
+    log(`> ${playerLabel} OVERRIDES ${targetLabel} — it fights for you! (${player.ap} AP left).`);
+  } else {
+    log(
+      `> ${playerLabel} OVERRIDE FAILED on ${targetLabel}` +
+        `${result.alarm ? ' — ALARM TRIPPED' : ''} (${player.ap} AP left).`
+    );
+  }
+  gateOnApExhausted(ctx);
+}
+
+/**
+ * First hostile along (dx, dy) within `OVERRIDE_RANGE` and LOS. Returns `null`
+ * when the ray leaves the map, exceeds range, hits a wall, or finds no entity —
+ * `canOverride` turns that `null` into a `not-overridable` deny.
+ */
+function pickOverrideTarget(ctx: ApplyIntentContext, dx: number, dy: number) {
+  const { world, player } = ctx;
+  const blockers = world.blockerKeys();
+  for (let step = 1; step <= OVERRIDE_RANGE; step++) {
+    const x = player.x + dx * step;
+    const y = player.y + dy * step;
+    if (!world.grid.inBounds(x, y)) return null;
+    if (!withinRange(player.x, player.y, x, y, OVERRIDE_RANGE)) return null;
+    if (!hasLineOfSight(world.grid, player.x, player.y, x, y, { blockers })) return null;
+    const e = world.entityAt(x, y);
+    if (e) return e;
+  }
+  return null;
+}
+
 function doDeploy(intent: Intent, ctx: ApplyIntentContext) {
   const { world, player, log } = ctx;
   const tech = player as Tech;
diff --git a/tests/unit/game/Decker.test.ts b/tests/unit/game/Decker.test.ts
new file mode 100644
index 0000000..1ab565d
--- /dev/null
+++ b/tests/unit/game/Decker.test.ts
@@ -0,0 +1,202 @@
+/**
+ * Decker archetype tests (P3.M2) — Drone Override Hack legality matrix,
+ * commit semantics, and the per-turn stepping/revert loop.
+ *
+ * The perk mirrors the Tech/Razor/Merc contract: `canOverride` is a pure
+ * legality check returning `{ ok, reason }`; `overrideDrone` commits the spend
+ * (AP + faction flip, or AP + alarm on a failed roll) and throws — without
+ * mutating state — on any illegal precondition. The override then plays out
+ * through `stepOverriddenDrones`, which fights the drone on the player's side
+ * and reverts it when the countdown lapses.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { Decker } from '../../../src/game/archetypes/Decker.js';
+import { Crew } from '../../../src/game/Crew.js';
+import { Grid } from '../../../src/game/Grid.js';
+import { World } from '../../../src/game/World.js';
+import { Entity } from '../../../src/game/Entity.js';
+import { Skirmisher } from '../../../src/game/ai/Skirmisher.js';
+import { applyOverride, stepOverriddenDrones } from '../../../src/game/droneOverride.js';
+import { TILE, FACTION, AP_COST, OVERRIDE_DURATION } from '../../../src/game/constants.js';
+import { Rng } from '../../../src/rng.js';
+
+function makeWorld({ deckerAt = [1, 1], grid, extraEntities = [] } = {}) {
+  const g = grid ?? new Grid(12, 12);
+  const w = new World(g);
+  const decker = new Decker({ id: 'decker', x: deckerAt[0], y: deckerAt[1] });
+  w.addEntity(decker);
+  for (const e of extraEntities) w.addEntity(e);
+  return { world: w, decker };
+}
+
+function makeDrone(id, x, y, faction = FACTION.CORP) {
+  return new Skirmisher({ id, x, y, faction });
+}
+
+// Deterministic single-roll stubs for the commit step (overrideDrone only
+// consumes one rng.next()). 0.1 < success chance → hijack; 0.9 → failure.
+const winRng = { next: () => 0.1 };
+const loseRng = { next: () => 0.9 };
+
+// --- class basics ----------------------------------------------------------
+
+test('Decker extends Crew and is a PLAYER-faction operator with the @ glyph', () => {
+  const d = new Decker({ id: 'd', x: 0, y: 0 });
+  assert.ok(d instanceof Crew, 'Decker must extend Crew');
+  assert.equal(d.faction, FACTION.PLAYER);
+  assert.equal(d.glyph, '@');
+  assert.equal(d.archetype, 'Decker');
+  assert.equal(d.baseHitChance, 0.7);
+});
+
+// --- canOverride legality matrix -------------------------------------------
+
+test('canOverride accepts a live in-range LOS corp drone', () => {
+  const drone = makeDrone('k', 3, 1);
+  const { world, decker } = makeWorld({ extraEntities: [drone] });
+  assert.equal(decker.canOverride(world, drone).ok, true);
+});
+
+test('canOverride rejects a null / non-Hostile target as not-overridable', () => {
+  const prop = new Entity({ id: 'prop', x: 2, y: 1, faction: FACTION.CORP, glyph: '#' });
+  const { world, decker } = makeWorld({ extraEntities: [prop] });
+  assert.equal(decker.canOverride(world, null).reason, 'not-overridable');
+  assert.equal(decker.canOverride(world, prop).reason, 'not-overridable');
+});
+
+test('canOverride rejects when the Decker is dead', () => {
+  const drone = makeDrone('k', 3, 1);
+  const { world, decker } = makeWorld({ extraEntities: [drone] });
+  decker.alive = false;
+  assert.equal(decker.canOverride(world, drone).reason, 'dead');
+});
+
+test('canOverride rejects when AP < OVERRIDE cost', () => {
+  const drone = makeDrone('k', 3, 1);
+  const { world, decker } = makeWorld({ extraEntities: [drone] });
+  decker.spendAp(decker.ap - (AP_COST.OVERRIDE - 1));
+  assert.equal(decker.canOverride(world, drone).reason, 'insufficient-ap');
+});
+
+test('canOverride rejects a dead target drone', () => {
+  const drone = makeDrone('k', 3, 1);
+  const { world, decker } = makeWorld({ extraEntities: [drone] });
+  drone.alive = false;
+  assert.equal(decker.canOverride(world, drone).reason, 'dead-target');
+});
+
+test('canOverride rejects a drone that is already overridden', () => {
+  const drone = makeDrone('k', 3, 1);
+  const { world, decker } = makeWorld({ extraEntities: [drone] });
+  applyOverride(drone, FACTION.PLAYER);
+  assert.equal(decker.canOverride(world, drone).reason, 'already-overridden');
+});
+
+test('canOverride rejects a same-faction (already player-aligned) drone', () => {
+  const drone = makeDrone('k', 3, 1, FACTION.PLAYER);
+  const { world, decker } = makeWorld({ extraEntities: [drone] });
+  assert.equal(decker.canOverride(world, drone).reason, 'friendly');
+});
+
+test('canOverride rejects an out-of-range drone', () => {
+  const drone = makeDrone('k', 9, 1); // distance 8 > OVERRIDE_RANGE (5)
+  const { world, decker } = makeWorld({ extraEntities: [drone] });
+  assert.equal(decker.canOverride(world, drone).reason, 'out-of-range');
+});
+
+test('canOverride rejects a drone behind a wall (no LOS)', () => {
+  const g = new Grid(12, 12);
+  g.setTile(2, 1, TILE.WALL);
+  const drone = makeDrone('k', 3, 1);
+  const { world, decker } = makeWorld({ grid: g, extraEntities: [drone] });
+  assert.equal(decker.canOverride(world, drone).reason, 'no-los');
+});
+
+// --- overrideDrone commit semantics ----------------------------------------
+
+test('overrideDrone success flips the drone to PLAYER for the full duration', () => {
+  const drone = makeDrone('k', 3, 1);
+  const { world, decker } = makeWorld({ extraEntities: [drone] });
+  const apBefore = decker.ap;
+  const result = decker.overrideDrone(world, drone, winRng);
+  assert.equal(result.success, true);
+  assert.equal(result.alarm, false);
+  assert.equal(drone.faction, FACTION.PLAYER);
+  assert.equal(drone.factionBeforeOverride, FACTION.CORP);
+  assert.equal(drone.overrideTurnsRemaining, OVERRIDE_DURATION);
+  assert.equal(drone.isOverridden, true);
+  assert.equal(decker.ap, apBefore - AP_COST.OVERRIDE);
+});
+
+test('overrideDrone failure burns AP, trips the alarm, leaves faction intact', () => {
+  const drone = makeDrone('k', 3, 1);
+  const { world, decker } = makeWorld({ extraEntities: [drone] });
+  const apBefore = decker.ap;
+  assert.equal(world.alarmActive, false);
+  const result = decker.overrideDrone(world, drone, loseRng);
+  assert.equal(result.success, false);
+  assert.equal(result.alarm, true);
+  assert.equal(world.alarmActive, true);
+  assert.equal(drone.faction, FACTION.CORP);
+  assert.equal(drone.isOverridden, false);
+  assert.equal(decker.ap, apBefore - AP_COST.OVERRIDE);
+});
+
+test('overrideDrone throws on an illegal attempt without burning AP', () => {
+  const drone = makeDrone('k', 9, 1); // out of range
+  const { world, decker } = makeWorld({ extraEntities: [drone] });
+  const apBefore = decker.ap;
+  assert.throws(() => decker.overrideDrone(world, drone, winRng), /Illegal override/);
+  assert.equal(decker.ap, apBefore, 'AP not debited on illegal override');
+  assert.equal(drone.faction, FACTION.CORP);
+});
+
+// --- golden path: hijacked drone fights corp, then reverts -----------------
+
+test('an overridden drone attacks corp allies for N turns then reverts', () => {
+  // Open arena: decker, hijacked drone, and a corp victim in a clean LOS line.
+  const drone = makeDrone('hijacked', 4, 4);
+  const victim = makeDrone('victim', 6, 4); // corp; the drone's new enemy
+  const { world, decker } = makeWorld({ deckerAt: [2, 4], extraEntities: [drone, victim] });
+
+  const result = decker.overrideDrone(world, drone, winRng);
+  assert.equal(result.success, true);
+
+  const rng = new Rng(7);
+  const victimHpStart = victim.hp;
+  let sawEngageAction = false;
+
+  // Drive the override across its whole lifetime. Each pass is one player turn:
+  // the drone acts, then its countdown ticks.
+  let expired = false;
+  for (let turn = 0; turn < OVERRIDE_DURATION; turn++) {
+    assert.equal(drone.faction, FACTION.PLAYER, `drone should be player-aligned on turn ${turn}`);
+    drone.refreshAp(); // mimic the AP refresh PLAYER entities get each round
+    for (const { entity, action } of stepOverriddenDrones(world, rng)) {
+      assert.equal(entity.id, drone.id);
+      if (action.type === 'fire' || String(action.type).startsWith('move')) {
+        sawEngageAction = true;
+      }
+      if (action.type === 'override-expired') expired = true;
+    }
+  }
+
+  assert.ok(sawEngageAction, 'hijacked drone should engage (fire/move) against corp');
+  assert.ok(expired, 'override should emit an override-expired action when it lapses');
+  assert.equal(drone.isOverridden, false, 'override countdown should be spent');
+  assert.equal(drone.faction, FACTION.CORP, 'drone reverts to its original faction');
+  assert.equal(drone.factionBeforeOverride, null, 'override bookkeeping cleared on revert');
+  assert.ok(victim.hp <= victimHpStart, 'corp victim took fire from the hijacked drone');
+});
+
+test('overrideDrone is a no-op on the corp turn list — driver skips player faction', () => {
+  // Sanity: once flipped, the drone is PLAYER faction, so the corp-turn driver
+  // (which filters on corpFaction) will never step it. We assert the faction
+  // contract that guarantees this rather than re-running the whole driver.
+  const drone = makeDrone('k', 3, 1);
+  const { world, decker } = makeWorld({ extraEntities: [drone] });
+  decker.overrideDrone(world, drone, winRng);
+  assert.notEqual(drone.faction, FACTION.CORP);
+});
diff --git a/tests/unit/game/archetypes.test.ts b/tests/unit/game/archetypes.test.ts
index 9de5385..d5e14d7 100644
--- a/tests/unit/game/archetypes.test.ts
+++ b/tests/unit/game/archetypes.test.ts
@@ -16,10 +16,12 @@ import {
   ARCHETYPES,
   ARCHETYPE_IDS,
   CALLSIGNS_BY_ARCHETYPE,
+  RECRUIT_ARCHETYPE_POOL,
   buildCrewMember,
   isArchetypeId,
   pickCallsign,
 } from '../../../src/game/archetypes/index.js';
+import { Decker } from '../../../src/game/archetypes/Decker.js';
 import { FACTION } from '../../../src/game/constants.js';
 import { Merc, CALLSIGNS as MERC_CALLSIGNS } from '../../../src/game/archetypes/Merc.js';
 import { CALLSIGNS as RAZOR_CALLSIGNS } from '../../../src/game/archetypes/Razor.js';
@@ -145,6 +147,35 @@ test('buildCrewMember rejects a missing or invalid rng', () => {
   assert.throws(() => buildCrewMember('merc', { x: 0, y: 0 }, {}), /Rng/i);
 });
 
+// --- Decker (P3.M2): registered, buildable, but not a starter/recruit pick ---
+
+test('Decker is registered in ARCHETYPES with its OVERRIDE perk metadata', () => {
+  const a = ARCHETYPES.decker;
+  assert.ok(a, 'missing decker archetype');
+  assert.equal(a.id, 'decker');
+  assert.equal(a.name, 'DECKER');
+  assert.deepEqual(a.perks, ['override']);
+  assert.equal(a.perkName, 'OVERRIDE');
+  assert.ok(a.perkLabel.length > 0);
+});
+
+test('Decker is excluded from the starter selector and the random recruit pool', () => {
+  // The Decker joins only via the Act-2 narrative beat — never as a starter
+  // pick or a random recruit roll (P3.M2 design constraint).
+  assert.ok(!ARCHETYPE_IDS.includes('decker'), 'Decker must not be a selectable starter');
+  assert.ok(
+    !RECRUIT_ARCHETYPE_POOL.includes('decker'),
+    'Decker must not be in the random recruit pool'
+  );
+});
+
+test('buildCrewMember can still construct a Decker by id (recruitment path)', () => {
+  const d = buildCrewMember('decker', { x: 1, y: 2 }, new Rng(9));
+  assert.ok(d instanceof Decker);
+  assert.equal(isArchetypeId('decker'), true);
+  assert.ok(CALLSIGNS_BY_ARCHETYPE.decker.includes(d.callsign));
+});
+
 test('isArchetypeId is a string-set membership check', () => {
   assert.equal(isArchetypeId('merc'), true);
   assert.equal(isArchetypeId('razor'), true);
diff --git a/tests/unit/game/persistence.test.ts b/tests/unit/game/persistence.test.ts
index 5b27745..bf496ac 100644
--- a/tests/unit/game/persistence.test.ts
+++ b/tests/unit/game/persistence.test.ts
@@ -25,6 +25,9 @@ import {
 } from '../../../src/game/constants.js';
 import { makeSalvage, totalSalvage } from '../../../src/game/salvage.js';
 import { buildCrewMember } from '../../../src/game/archetypes/index.js';
+import { Decker } from '../../../src/game/archetypes/Decker.js';
+import { PatrolHostile } from '../../../src/game/ai/PatrolHostile.js';
+import { applyOverride } from '../../../src/game/droneOverride.js';
 import { Rng } from '../../../src/rng.js';
 import { testContractContext } from './contractTestUtils.js';
 
@@ -104,6 +107,43 @@ test('run snapshot → restore → snapshot is byte-for-byte stable', () => {
   assert.deepEqual(recB, recA, 'round-trip should reproduce the source record');
 });
 
+test('snapshot/restore round-trips a Decker deploy (P3.M2)', () => {
+  const run = freshCombatRun(0xc0ffee, 'decker');
+  assert.ok(run.player instanceof Decker, 'fixture should deploy a Decker');
+  const rec = snapshot(run);
+  const { run: restoredRun } = restore(rec);
+  assert.ok(restoredRun.player instanceof Decker, 'Decker should restore as a Decker');
+  assert.equal(restoredRun.player.callsign, run.player.callsign);
+  // Stable round-trip through a second snapshot.
+  assert.deepEqual(snapshot(restoredRun), rec);
+});
+
+test('snapshot/restore preserves a live drone-override (P3.M2)', () => {
+  const run = freshCombatRun(0xbadbeef, 'decker');
+  const drone = [...run.world.entities.values()].find(e => e instanceof PatrolHostile);
+  assert.ok(drone, 'fixture run should contain at least one patrol hostile');
+  const originalFaction = drone.faction;
+  applyOverride(drone, FACTION.PLAYER);
+
+  const rec = snapshot(run);
+  const { world: restoredWorld } = restore(rec);
+  const restoredDrone = [...restoredWorld.entities.values()].find(e => e.id === drone.id);
+  assert.ok(restoredDrone, 'overridden drone should survive the round-trip');
+  assert.equal(restoredDrone.faction, FACTION.PLAYER, 'flipped faction preserved');
+  assert.equal(restoredDrone.factionBeforeOverride, originalFaction, 'prior faction preserved');
+  assert.equal(restoredDrone.overrideTurnsRemaining, drone.overrideTurnsRemaining);
+  assert.equal(restoredDrone.isOverridden, true);
+});
+
+test('a never-overridden drone snapshot omits override fields (no shape drift)', () => {
+  const run = freshCombatRun(0x1234, 'razor');
+  const rec = snapshot(run);
+  const droneRec = rec.entities.find(e => e.archetype === 'drone' || e.archetype === 'guard');
+  assert.ok(droneRec, 'expected a patrol hostile in the snapshot');
+  assert.equal(droneRec.extra.overrideTurnsRemaining, undefined);
+  assert.equal(droneRec.extra.factionBeforeOverride, undefined);
+});
+
 test('snapshot/restore round-trips a Tech with a placed turret (M1)', () => {
   const run = freshCombatRun(0xc0ffee, 'tech');
   const tech = run.player;

From a5e7943c689ac524fc6e41d67dfc292d5eb25c4a Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Mon, 8 Jun 2026 08:57:53 -0700
Subject: [PATCH 04/55] transitions and score target identification

---
 docs/phase-3-plan.md             |  24 ++--
 src/game/Campaign.ts             | 137 +++++++++++++++++-
 src/game/persistence.ts          |   2 +-
 tests/unit/game/Campaign.test.ts | 231 ++++++++++++++++++++++++++++++-
 4 files changed, 379 insertions(+), 15 deletions(-)

diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 260c006..068881f 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -41,8 +41,8 @@ A new **player archetype** recruited mid-campaign (late Act 1 / start of Act 2),
 
 | Milestone | Status |
 |---|---|
-| P3.M1 — Campaign arc structure | 🚧 In progress — P3.M1.1 done |
-| P3.M2 — The Decker archetype | 🚧 In progress — class + Drone Override Hack done; recruitment flow pending P3.M1.2 |
+| P3.M1 — Campaign arc structure | 🚧 In progress — P3.M1.1–P3.M1.3 done; Hub arc surface next |
+| P3.M2 — The Decker archetype | 🚧 In progress — class + Drone Override Hack done; recruitment flow pending |
 | P3.M3 — Cyberspace grid + ICE | 🔲 Planned |
 | P3.M4 — Simstim flip (dual-deploy) | 🔲 Planned |
 | P3.M5 — The Score (climactic mission) | 🔲 Planned |
@@ -100,7 +100,7 @@ Score-target sites always use roster-stored dimensions (P2.7.M1.5: `mapWidth`, `
   - Act 2 = at least one board slot biased toward the Score target or its principal/site identity when available.
   - Act 3 = board mostly prep contracts at or near the Score target, plus a separate player-initiated Score action instead of a random roll.
   - Score = special contract build path; not part of the normal three-card job board.
-- **Hub surface:** Hub status / Terminal shows current act, Clock pressure, and Score target label once revealed. Decker recruitment uses progressive Hub reveal plumbing.
+- **Hub surface:** Hub status / Terminal shows current act, Clock pressure, and Score target label once revealed. The Score reveal uses progressive Hub reveal plumbing so the Curator can present the target as a campaign beat instead of leaving the player to infer it from state changes.
 - **Win/loss conditions:**
   - **Win:** Complete the Score (extract with objective satisfied from the final mission).
   - **Loss (flatline):** Entire crew wiped during any run (existing behavior, but now with arc context for the chronicle).
@@ -130,18 +130,24 @@ Neural degradation is deferred until Cyberspace is fun enough to deserve a jack-
 | Slice | Status | Change | Tests |
 |---|---|---|---|
 | **P3.M1.1 Arc record** | ✅ Done | Add `Campaign.arc`, derive `arcStage`, persist/restore, normalize old saves to Act 1 | constructor validation, snapshot round-trip, invalid stage throws |
-| **P3.M1.2 Transitions** | 🔲 Planned | Advance acts from `rep`, `completedJobs`, Decker flag, Score-site visit | boundary tests around job counts and rep tier |
-| **P3.M1.3 Score target** | 🔲 Planned | Promote one roster site to `tier: 'score'`; preserve through eviction | exactly-one target, no eviction at roster cap, synthetic target when roster empty |
-| **P3.M1.4 Clock** | 🔲 Planned | Start heat after threshold; hard loss at deadline; show status | heat math, deadline loss, no loss after Score attempt |
-| **P3.M1.5 Curator bias** | 🔲 Planned | Pass campaign-derived arc context; bias board slots by act and score target | seeded boards show expected `arcStage` and target-site frequency |
-| **P3.M1.6 Score entry** | 🔲 Planned | Hub action creates the special Score contract in Act 3 only | availability gates, deployment path, attempted flag |
+| **P3.M1.2 Transitions** | ✅ Done | Advance acts from `rep`, `completedJobs`, Decker flag, Score-site visit | boundary tests around job counts and rep tier |
+| **P3.M1.3 Score target** | ✅ Done | Promote one roster site to `tier: 'score'`; preserve through eviction | exactly-one target, no eviction at roster cap, synthetic target when roster empty |
+| **P3.M1.4 Hub arc surface** | 🔲 Planned | Curator presents the Score reveal; Hub / Terminal shows act and Score target; contract selection labels Score-site jobs | one-shot reveal, status render, Score-site badge |
+| **P3.M1.5 Clock** | 🔲 Planned | Start heat after threshold; hard loss at deadline; show status | heat math, deadline loss, no loss after Score attempt |
+| **P3.M1.6 Curator bias** | 🔲 Planned | Pass campaign-derived arc context; bias board slots by act and score target | seeded boards show expected `arcStage` and target-site frequency |
+| **P3.M1.7 Score entry** | 🔲 Planned | Hub action creates the special Score contract in Act 3 only | availability gates, deployment path, attempted flag |
 
 **P3.M1.1 implementation note:** `Campaign` now owns a typed `arc` record (`arcStage`, `deckerRecruited`, `scoreRevealed`, `clockStarted`, `scoreAttempted`, `scoreCompleted`) plus an `arcStage` getter for Curator context. New snapshots serialize the record; pre-P3 snapshots normalize to Act 1; malformed persisted arc data throws during restore instead of being silently repaired.
 
+**P3.M1.2 implementation note:** Hub entry now runs a monotonic arc transition evaluator. Act 1 advances to Act 2 at `TRUSTED` Rep plus `completedJobs >= 4` and sets `scoreRevealed`; successful extractions increment `completedJobs`, abort extractions do not. Act 2 advances to Act 3 once a Decker has joined the crew, `completedJobs >= 9`, and a score-target roster site has a prior visit marker (`lastVisitedJob > 0`). M1.2 does not synthesize or promote the Score target — that remains P3.M1.3.
+
+**P3.M1.3 implementation note:** Score reveal now guarantees exactly one Score target. If a roster site exists at Act 2 entry, the most recently visited site is promoted to `tier: 'score'` with `scoreTarget: true`, preserving its seed, dimensions, mutation deltas, and exploration memory. If the roster is empty, Campaign synthesizes a CRITICAL-footprint score site from Curator lexicon principal/site tokens instead of deferring reveal. Multiple persisted score targets, or score-tier sites missing `scoreTarget`, throw during Hub-entry arc evaluation.
+
 **Acceptance:**
 
 - Arc state persists in campaign save; restore round-trip.
 - Act transitions fire at correct thresholds; tests for boundary conditions.
+- Score reveal is player-visible: Curator presents the target once, Hub / Terminal displays the current act and target label, and contract selection marks Score-site jobs.
 - Curator generates arc-appropriate contracts per act (testable via seeded generation with arc context).
 - At least one Clock type implemented with visible feedback (Hub status, contract briefing, or log).
 - Exactly one Score target exists after Score reveal; it survives roster eviction and keeps its P2.5.M7 terrain memory.
@@ -169,7 +175,7 @@ Neural degradation is deferred until Cyberspace is fun enough to deserve a jack-
 
 - ✅ Decker archetype playable in Meatspace: move, attack, interact — comparable to other archetypes (`Decker` extends `Crew`, `baseHitChance` 0.7, `@` glyph).
 - ✅ Drone Override Hack: golden-path test — target drone, override succeeds, drone attacks corp allies for N turns, reverts or is destroyed (`droneOverride.ts`, `Decker.test.ts`). Failed roll burns AP and trips the alarm.
-- 🔲 Recruitment: gated by arc state; not available in Act 1; golden-path test for recruitment flow. **Deferred — needs P3.M1.2 act transitions.** Decker is registered but excluded from `ARCHETYPE_IDS` and `RECRUIT_ARCHETYPE_POOL` so random recruitment can't roll one early.
+- 🔲 Recruitment: gated by arc state; not available in Act 1; golden-path test for recruitment flow. **Ready after P3.M1.4 confirms the shared Hub reveal surface.** Decker is registered but excluded from `ARCHETYPE_IDS` and `RECRUIT_ARCHETYPE_POOL` so random recruitment can't roll one early.
 - ✅ Snapshot: Decker state persists (campaign + run round-trip); live drone-override state round-trips through the patrol snapshot. Cyberspace attributes deferred to P3.M3.
 - ✅ Key help: Decker glyph (`@`) and OVERRIDE ability description via shared `ARCHETYPES[id].perkLabel`.
 
diff --git a/src/game/Campaign.ts b/src/game/Campaign.ts
index 86882e0..f9415b6 100644
--- a/src/game/Campaign.ts
+++ b/src/game/Campaign.ts
@@ -3,7 +3,16 @@ import { World } from './World.js';
 import { TurnQueue } from './TurnQueue.js';
 import { EventBus } from './events.js';
 import { Entity } from './Entity.js';
-import { FACTION, REP, RECRUIT, SALVAGE_SELL_RATE, CLINIC_COST_PER_HP } from './constants.js';
+import {
+  CONTRACT_DIFFICULTY,
+  FACTION,
+  REP,
+  REP_TIER,
+  RECRUIT,
+  SALVAGE_SELL_RATE,
+  CLINIC_COST_PER_HP,
+  repTierForRep,
+} from './constants.js';
 import {
   SALVAGE_TYPES,
   addSalvage,
@@ -14,7 +23,7 @@ import {
   type TypedSalvage,
 } from './salvage.js';
 import { buildCrewMember, RECRUIT_ARCHETYPE_POOL } from './archetypes/index.js';
-import { Curator } from './hub/Curator.js';
+import { CONTRACT_LEXICON, Curator } from './hub/Curator.js';
 import { Terminal } from './hub/Terminal.js';
 import { Finn } from './hub/Finn.js';
 import { Clinic } from './hub/Clinic.js';
@@ -35,13 +44,24 @@ import {
   mergeSiteSeenKeys as mergeSeen,
   normalizeLocationSite,
 } from './locations.js';
+import { resolveMapDimensions } from './procgen/mapDimensions.js';
 import type { Contract } from './hub/Curator.js';
 import type { Crew } from './Crew.js';
-import type { CampaignArcStage, GridPoint, KeyItem, LocationSite, TileDelta } from '../types.js';
+import type {
+  CampaignArcStage,
+  GridPoint,
+  KeyItem,
+  LocationSite,
+  LocationToken,
+  TileDelta,
+} from '../types.js';
 import type { RunResult, Outcome } from './Run.js';
 
 /** Max remembered combat locations (P2.5.M7.2). One slot is reserved for Phase 3's score target. */
 export const SITE_ROSTER_CAP = 6;
+export const ARC_ACT_2_MIN_COMPLETED_JOBS = 4;
+export const ARC_ACT_3_MIN_COMPLETED_JOBS = 9;
+const SYNTHETIC_SCORE_TARGET_DIFFICULTY = CONTRACT_DIFFICULTY.CRITICAL;
 
 export const CAMPAIGN_STATE = Object.freeze({
   HUB: 'HUB',
@@ -274,6 +294,7 @@ export class Campaign {
     if (this.state !== CAMPAIGN_STATE.HUB && this.state !== CAMPAIGN_STATE.COMBAT) {
       throw new Error(`Campaign.enterHub: illegal transition from ${this.state}`);
     }
+    this.#advanceArcTransitions();
     this.recruitedThisVisit = false;
     this.healedThisVisit = new Set();
     this.lastHubReveal = null;
@@ -424,8 +445,8 @@ export class Campaign {
       // returning to the Hub — breach holes survive even on an aborted exit.
       this.#mergeRunDeltasIntoRoster(this.activeRun);
       this.#mergeRunSeenIntoRoster(this.activeRun);
-      this.completedJobs += 1;
       if (completed) {
+        this.completedJobs += 1;
         addSalvage(this.salvage, extracted);
         const reward = this.activeRun.contract?.reward;
         this.credits += reward?.credits ?? 0;
@@ -968,6 +989,102 @@ export class Campaign {
     return this.crew.find(member => member.id === memberId) ?? null;
   }
 
+  #advanceArcTransitions(): void {
+    if (this.crew.some(member => member.archetype === 'Decker')) {
+      this.arc.deckerRecruited = true;
+    }
+
+    if (this.arc.arcStage === 'act-1' && this.#qualifiesForAct2()) {
+      this.arc.arcStage = 'act-2';
+      this.arc.scoreRevealed = true;
+    }
+
+    if (this.arc.scoreRevealed) {
+      this.#ensureScoreTargetDesignated();
+    }
+
+    if (this.arc.arcStage === 'act-2' && this.#qualifiesForAct3()) {
+      this.arc.arcStage = 'act-3';
+    }
+  }
+
+  #qualifiesForAct2(): boolean {
+    return (
+      repTierForRep(this.rep).id === REP_TIER.TRUSTED &&
+      this.completedJobs >= ARC_ACT_2_MIN_COMPLETED_JOBS
+    );
+  }
+
+  #qualifiesForAct3(): boolean {
+    return (
+      this.arc.deckerRecruited &&
+      this.completedJobs >= ARC_ACT_3_MIN_COMPLETED_JOBS &&
+      this.siteRoster.some(site => site.scoreTarget && site.lastVisitedJob > 0)
+    );
+  }
+
+  #ensureScoreTargetDesignated(): void {
+    const scoreTargets = this.siteRoster.filter(site => site.scoreTarget);
+    if (scoreTargets.length > 1) {
+      throw new Error('Campaign arc: multiple Score targets in site roster');
+    }
+    const scoreTierNonTargets = this.siteRoster.filter(
+      site => site.tier === 'score' && !site.scoreTarget
+    );
+    if (scoreTierNonTargets.length > 0) {
+      throw new Error('Campaign arc: score-tier roster site missing scoreTarget');
+    }
+    if (scoreTargets.length === 1) {
+      scoreTargets[0]!.tier = 'score';
+      return;
+    }
+
+    const target = this.#selectRememberedScoreTarget() ?? this.#synthesizeScoreTarget();
+    target.scoreTarget = true;
+    target.tier = 'score';
+  }
+
+  #selectRememberedScoreTarget(): LocationSite | null {
+    if (this.siteRoster.length === 0) return null;
+    return [...this.siteRoster].sort(
+      (a, b) => b.lastVisitedJob - a.lastVisitedJob || a.id.localeCompare(b.id)
+    )[0]!;
+  }
+
+  #synthesizeScoreTarget(): LocationSite {
+    const seed = this.rng.intRange(0, 0x7fffffff);
+    const principal = this.rng.pick(
+      CONTRACT_LEXICON.principals.filter(token => token.groups.includes('corp'))
+    );
+    const site = this.rng.pick(
+      CONTRACT_LEXICON.sites.filter(token =>
+        token.groups.some(group =>
+          ['corp', 'data', 'security', 'infrastructure', 'hidden'].includes(group)
+        )
+      )
+    );
+    const dimensions = resolveMapDimensions({
+      seed,
+      difficulty: SYNTHETIC_SCORE_TARGET_DIFFICULTY,
+    });
+    const target = normalizeLocationSite({
+      id: `score-${generateSiteId(seed)}`,
+      seed: String(seed),
+      mapWidth: dimensions.width,
+      mapHeight: dimensions.height,
+      label: `// ${principal.label} ${site.label} - Score target`,
+      tier: 'score',
+      scoreTarget: true,
+      mutationDeltas: [],
+      seenKeys: [],
+      lastVisitedJob: 0,
+      principal: locationTokenFromLexicon(principal),
+      site: locationTokenFromLexicon(site),
+    });
+    this.siteRoster.push(target);
+    return target;
+  }
+
   #persist(): void {
     this.onPersist?.(this);
   }
@@ -1070,6 +1187,18 @@ export function normalizeCampaignArc(raw: unknown, context = 'Campaign arc'): Ca
   };
 }
 
+function locationTokenFromLexicon(token: {
+  id: string;
+  label: string;
+  groups: readonly string[];
+}): LocationToken {
+  return {
+    id: token.id,
+    label: token.label,
+    groups: [...token.groups],
+  };
+}
+
 function makeCampaignId(seed: number): string {
   return `campaign-${(seed >>> 0).toString(16)}-${Date.now().toString(36)}`;
 }
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index 626f92f..cb0b4dc 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -769,7 +769,7 @@ export type CampaignSnapshot = {
   healedThisVisit?: string[];
   /** Progressive Hub introduction flags. Defaults to {} for pre-P2.5.M5.4 saves. */
   hubReveals?: HubRevealsSnapshot;
-  /** Count of jobs ended with EXIT (extract). Defaults to 0 for pre-P2.5.M5.4 saves. */
+  /** Count of completed jobs. Abort extractions do not increment this arc counter. */
   completedJobs?: number;
   /** Persistent key-item inventory (keycards). Defaults to [] for pre-P2.5.M6.2 saves. */
   keyItems?: KeyItemSnapshot[];
diff --git a/tests/unit/game/Campaign.test.ts b/tests/unit/game/Campaign.test.ts
index 714d003..2547a9e 100644
--- a/tests/unit/game/Campaign.test.ts
+++ b/tests/unit/game/Campaign.test.ts
@@ -4,6 +4,7 @@ import assert from 'node:assert/strict';
 import {
   Campaign,
   CAMPAIGN_STATE,
+  SITE_ROSTER_CAP,
   buildCrew,
   defaultCampaignArc,
   willEndCampaignOnThisDeath,
@@ -12,9 +13,11 @@ import { OUTCOME, RUN_STATE } from '../../../src/game/Run.js';
 import { Rng } from '../../../src/rng.js';
 import { OBJECTIVES } from '../../../src/game/hub/Curator.js';
 import { snapshotCampaign, restoreCampaign } from '../../../src/game/persistence.js';
-import { SALVAGE_SELL_RATE, SHOP_COST } from '../../../src/game/constants.js';
+import { SALVAGE_SELL_RATE, SHOP_COST, TILE } from '../../../src/game/constants.js';
 import { emptySalvage, makeSalvage, totalSalvage } from '../../../src/game/salvage.js';
 import { testContractContext } from './contractTestUtils.js';
+import { buildCrewMember } from '../../../src/game/archetypes/index.js';
+import type { LocationSite } from '../../../src/types.js';
 
 const fakeContract = (overrides = {}) => ({
   seed: 12345,
@@ -31,6 +34,22 @@ const fakeContract = (overrides = {}) => ({
   ...overrides,
 });
 
+function validSite(overrides: Partial<LocationSite> = {}): LocationSite {
+  return {
+    id: '12345',
+    seed: '12345',
+    mapWidth: 24,
+    mapHeight: 16,
+    label: '// Matsuda contractor annex - payroll mirror',
+    tier: 'roster',
+    scoreTarget: false,
+    mutationDeltas: [],
+    seenKeys: [],
+    lastVisitedJob: 0,
+    ...overrides,
+  };
+}
+
 test('buildCrew creates one named member per starter archetype with unique callsigns', () => {
   const crew = buildCrew(new Rng(0xc0ffee));
   assert.equal(crew.length, 3);
@@ -630,6 +649,216 @@ test('restoreCampaign rejects corrupt Phase 3 arc snapshots', () => {
   );
 });
 
+test('P3.M1.2: Act 1 does not advance until Rep and completed job gates both qualify', () => {
+  const lowRep = new Campaign({ seed: 42, rep: 79, completedJobs: 4 });
+  assert.equal(lowRep.arcStage, 'act-1');
+  assert.equal(lowRep.arc.scoreRevealed, false);
+
+  const lowJobs = new Campaign({ seed: 43, rep: 80, completedJobs: 3 });
+  assert.equal(lowJobs.arcStage, 'act-1');
+  assert.equal(lowJobs.arc.scoreRevealed, false);
+});
+
+test('P3.M1.2: Act 1 advances to Act 2 at TRUSTED Rep plus four completed jobs', () => {
+  const campaign = new Campaign({ seed: 42, rep: 80, completedJobs: 4 });
+
+  assert.equal(campaign.arcStage, 'act-2');
+  assert.equal(campaign.arc.scoreRevealed, true);
+});
+
+test('P3.M1.2: successful extraction advances Act 2 when the final gate is crossed', () => {
+  const campaign = new Campaign({ seed: 42, rep: 79, completedJobs: 3 });
+  const member = campaign.crew[0];
+  const run = campaign.deployCrewMember(
+    member.id,
+    fakeContract({ reward: { credits: 0, repDelta: 1 } })
+  );
+  run.enterCombat();
+
+  campaign.onJobEnd({ outcome: OUTCOME.EXIT, completed: true });
+
+  assert.equal(campaign.completedJobs, 4);
+  assert.equal(campaign.rep, 80);
+  assert.equal(campaign.arcStage, 'act-2');
+  assert.equal(campaign.arc.scoreRevealed, true);
+});
+
+test('P3.M1.2: abort extraction does not count as a completed arc job', () => {
+  const campaign = new Campaign({ seed: 42, rep: 90, completedJobs: 3 });
+  const member = campaign.crew[0];
+  const run = campaign.deployCrewMember(member.id, fakeContract());
+  run.enterCombat();
+
+  campaign.onJobEnd({ outcome: OUTCOME.EXIT, completed: false });
+
+  assert.equal(campaign.completedJobs, 3);
+  assert.equal(campaign.arcStage, 'act-1');
+  assert.equal(campaign.arc.scoreRevealed, false);
+});
+
+test('P3.M1.2: Act 2 waits for Decker recruitment, Score-site visit, and nine jobs', () => {
+  const decker = buildCrewMember('decker', { x: 0, y: 0 }, new Rng(101), {
+    id: 'crew-decker',
+  });
+  const missingDecker = new Campaign({
+    seed: 42,
+    rep: 80,
+    completedJobs: 9,
+    siteRoster: [
+      validSite({
+        id: 'score',
+        seed: '12345',
+        tier: 'score',
+        scoreTarget: true,
+        lastVisitedJob: 5,
+      }),
+    ],
+  });
+  assert.equal(missingDecker.arcStage, 'act-2');
+
+  const missingTargetVisit = new Campaign({
+    seed: 43,
+    rep: 80,
+    completedJobs: 9,
+    crew: [decker],
+  });
+  assert.equal(missingTargetVisit.arcStage, 'act-2');
+
+  const tooFewJobs = new Campaign({
+    seed: 44,
+    rep: 80,
+    completedJobs: 8,
+    crew: [decker],
+    siteRoster: [
+      validSite({
+        id: 'score',
+        seed: '12345',
+        tier: 'score',
+        scoreTarget: true,
+        lastVisitedJob: 5,
+      }),
+    ],
+  });
+  assert.equal(tooFewJobs.arcStage, 'act-2');
+});
+
+test('P3.M1.2: Act 2 advances to Act 3 once Decker, Score-site visit, and nine jobs qualify', () => {
+  const decker = buildCrewMember('decker', { x: 0, y: 0 }, new Rng(102), {
+    id: 'crew-decker',
+  });
+  const campaign = new Campaign({
+    seed: 42,
+    rep: 80,
+    completedJobs: 9,
+    crew: [decker],
+    siteRoster: [
+      validSite({
+        id: 'score',
+        seed: '12345',
+        tier: 'score',
+        scoreTarget: true,
+        lastVisitedJob: 5,
+      }),
+    ],
+  });
+
+  assert.equal(campaign.arc.deckerRecruited, true);
+  assert.equal(campaign.arcStage, 'act-3');
+});
+
+test('P3.M1.3: Act 2 entry promotes one remembered site as the Score target', () => {
+  const campaign = new Campaign({
+    seed: 42,
+    rep: 80,
+    completedJobs: 4,
+    siteRoster: [
+      validSite({
+        id: 'remembered',
+        seed: '98765',
+        mapWidth: 30,
+        mapHeight: 18,
+        lastVisitedJob: 3,
+        seenKeys: ['1,1'],
+        mutationDeltas: [{ kind: 'tile', x: 2, y: 2, from: TILE.WALL, to: TILE.RUBBLE }],
+        principal: { id: 'orchid-vector', label: 'Orchid Vector', groups: ['corp', 'medical'] },
+        site: { id: 'sublevel-3', label: 'Sublevel 3', groups: ['infrastructure', 'hidden'] },
+      }),
+    ],
+  });
+
+  const target = campaign.findRosterSite('remembered');
+  assert.ok(target);
+  assert.equal(target!.scoreTarget, true);
+  assert.equal(target!.tier, 'score');
+  assert.equal(target!.mapWidth, 30);
+  assert.equal(target!.mapHeight, 18);
+  assert.deepEqual(target!.seenKeys, ['1,1']);
+  assert.equal(target!.mutationDeltas.length, 1);
+  assert.equal(campaign.siteRoster.filter(site => site.scoreTarget).length, 1);
+});
+
+test('P3.M1.3: remembered Score target selection prefers the most recently visited site', () => {
+  const campaign = new Campaign({
+    seed: 42,
+    rep: 80,
+    completedJobs: 4,
+    siteRoster: [
+      validSite({ id: 'older', seed: '101', lastVisitedJob: 1 }),
+      validSite({ id: 'newest', seed: '202', lastVisitedJob: 7 }),
+      validSite({ id: 'middle', seed: '303', lastVisitedJob: 3 }),
+    ],
+  });
+
+  assert.equal(campaign.siteRoster.find(site => site.scoreTarget)?.id, 'newest');
+  assert.equal(campaign.findRosterSite('newest')?.tier, 'score');
+});
+
+test('P3.M1.3: Act 2 entry synthesizes a Score target when the roster is empty', () => {
+  const campaign = new Campaign({ seed: 42, rep: 80, completedJobs: 4 });
+
+  assert.equal(campaign.arcStage, 'act-2');
+  assert.equal(campaign.arc.scoreRevealed, true);
+  assert.equal(campaign.siteRoster.length, 1);
+  const target = campaign.siteRoster[0]!;
+  assert.equal(target.scoreTarget, true);
+  assert.equal(target.tier, 'score');
+  assert.match(target.id, /^score-/);
+  assert.match(target.seed, /^\d+$/);
+  assert.ok(target.mapWidth >= 28);
+  assert.ok(target.mapHeight >= 18);
+  assert.ok(target.principal?.id);
+  assert.ok(target.site?.id);
+});
+
+test('P3.M1.3: designated Score target survives roster eviction at cap', () => {
+  const campaign = new Campaign({ seed: 42, rep: 80, completedJobs: 4 });
+  const targetId = campaign.siteRoster.find(site => site.scoreTarget)!.id;
+
+  for (let i = 0; i < SITE_ROSTER_CAP; i++) {
+    campaign.addSiteToRoster(validSite({ id: `filler-${i}`, seed: `${1000 + i}` }));
+  }
+
+  assert.equal(campaign.siteRoster.length, SITE_ROSTER_CAP);
+  assert.ok(campaign.findRosterSite(targetId), 'Score target must not be evicted');
+  assert.equal(campaign.siteRoster.filter(site => site.scoreTarget).length, 1);
+});
+
+test('P3.M1.3: multiple persisted Score targets crash instead of being normalized', () => {
+  assert.throws(
+    () =>
+      new Campaign({
+        seed: 42,
+        rep: 80,
+        completedJobs: 4,
+        siteRoster: [
+          validSite({ id: 'score-a', seed: '111', tier: 'score', scoreTarget: true }),
+          validSite({ id: 'score-b', seed: '222', tier: 'score', scoreTarget: true }),
+        ],
+      }),
+    /multiple Score targets/i
+  );
+});
+
 // ─── Recruitment ────────────────────────────────────────────────────────
 
 test('generateRecruits returns 1–2 candidates when Rep ≥ 65', () => {

From 0e99137e71369a5fed442b096d5d0fc63c5fa2f1 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Mon, 8 Jun 2026 12:46:01 -0700
Subject: [PATCH 05/55] savestate editor

---
 debug/save.html         | 225 +++++++++++++++++++
 debug/save.ts           | 467 ++++++++++++++++++++++++++++++++++++++++
 scripts/copy-assets.mjs |   1 +
 3 files changed, 693 insertions(+)
 create mode 100644 debug/save.html
 create mode 100644 debug/save.ts

diff --git a/debug/save.html b/debug/save.html
new file mode 100644
index 0000000..1b15892
--- /dev/null
+++ b/debug/save.html
@@ -0,0 +1,225 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <title>Kernel Panic — savegame editor</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" href="/favicon.ico" sizes="32x32" />
+    <link rel="stylesheet" href="/main.css" type="text/css" />
+    <style>
+      .save-editor {
+        max-width: 960px;
+        margin: 1rem auto;
+        padding: 0 1rem;
+        font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+      }
+
+      /* --- toolbar --- */
+      .toolbar {
+        display: flex;
+        gap: 0.5rem;
+        margin-bottom: 1rem;
+        flex-wrap: wrap;
+      }
+      .toolbar button {
+        background: #1a2422;
+        color: var(--accent-color);
+        border: 1px solid var(--accent-color);
+        padding: 0.4rem 0.75rem;
+        border-radius: 4px;
+        cursor: pointer;
+        font-family: inherit;
+        font-size: 0.85rem;
+      }
+      .toolbar button:hover,
+      .toolbar button:focus-visible {
+        background: var(--accent-color);
+        color: #06090a;
+      }
+      .toolbar button.danger {
+        border-color: #e05050;
+        color: #e05050;
+      }
+      .toolbar button.danger:hover,
+      .toolbar button.danger:focus-visible {
+        background: #e05050;
+        color: #06090a;
+      }
+
+      /* --- toast --- */
+      .toast {
+        position: fixed;
+        bottom: 1rem;
+        left: 50%;
+        transform: translateX(-50%);
+        background: var(--accent-color);
+        color: #06090a;
+        padding: 0.5rem 1.25rem;
+        border-radius: 4px;
+        font-weight: bold;
+        opacity: 0;
+        transition: opacity 0.3s;
+        pointer-events: none;
+        z-index: 100;
+      }
+      .toast.visible {
+        opacity: 1;
+      }
+
+      /* --- quick-edit panel --- */
+      .quick-edit {
+        background: #0d1614;
+        border: 1px solid #1a2422;
+        border-radius: 6px;
+        padding: 0.75rem 1rem;
+        margin-bottom: 1rem;
+      }
+      .quick-edit h2 {
+        margin: 0 0 0.5rem;
+        font-size: 1rem;
+        color: var(--accent-color);
+      }
+      .quick-edit .qe-grid {
+        display: grid;
+        grid-template-columns: repeat(auto-fill, minmax(180px, 1fr));
+        gap: 0.4rem 1rem;
+      }
+      .quick-edit label {
+        display: flex;
+        align-items: center;
+        gap: 0.4rem;
+        font-size: 0.8rem;
+      }
+      .quick-edit input,
+      .quick-edit select {
+        background: #06090a;
+        color: var(--text-color);
+        border: 1px solid #2a3e38;
+        border-radius: 3px;
+        padding: 0.2rem 0.35rem;
+        font-family: inherit;
+        font-size: 0.8rem;
+        width: 5rem;
+      }
+      .quick-edit input:focus,
+      .quick-edit select:focus {
+        outline: 1px solid var(--accent-color);
+        border-color: var(--accent-color);
+      }
+      .qe-crew-row {
+        display: contents;
+      }
+      .qe-crew-row span.callsign {
+        font-weight: bold;
+        color: var(--accent-color);
+        min-width: 6rem;
+      }
+
+      /* --- empty state --- */
+      .empty-state {
+        text-align: center;
+        padding: 3rem 1rem;
+        color: #6a8a80;
+      }
+
+      /* --- tree --- */
+      .tree {
+        background: #06090a;
+        border: 1px solid #1a2422;
+        border-radius: 6px;
+        padding: 0.75rem;
+        overflow-x: auto;
+        font-size: 0.8rem;
+        line-height: 1.6;
+      }
+      .tree details {
+        margin-left: 1rem;
+      }
+      .tree details > summary {
+        cursor: pointer;
+        list-style: none;
+        color: #8a9e98;
+        user-select: none;
+      }
+      .tree details > summary::before {
+        content: '▸ ';
+        color: #4a6e60;
+      }
+      .tree details[open] > summary::before {
+        content: '▾ ';
+      }
+      .tree .key {
+        color: #6ee5c0;
+      }
+      .tree .bracket {
+        color: #4a6e60;
+      }
+      .tree .count {
+        color: #4a6e60;
+        font-size: 0.75rem;
+      }
+      .tree .leaf {
+        margin-left: 1rem;
+        display: flex;
+        align-items: center;
+        gap: 0.35rem;
+      }
+      .tree .leaf .key {
+        min-width: 8ch;
+      }
+      .tree .val-null {
+        color: #666;
+        font-style: italic;
+      }
+      .tree .val-bool {
+        color: #c5a3ff;
+      }
+      .tree .val-num {
+        color: #ffb86c;
+      }
+      .tree .val-str {
+        color: #f1fa8c;
+      }
+      .tree input.inline-edit {
+        background: #0d1614;
+        color: var(--text-color);
+        border: 1px solid #2a3e38;
+        border-radius: 3px;
+        padding: 0 0.25rem;
+        font-family: inherit;
+        font-size: 0.8rem;
+        width: auto;
+        min-width: 4ch;
+      }
+      .tree input.inline-edit:focus {
+        outline: 1px solid var(--accent-color);
+        border-color: var(--accent-color);
+      }
+      .tree select.inline-edit {
+        background: #0d1614;
+        color: var(--text-color);
+        border: 1px solid #2a3e38;
+        border-radius: 3px;
+        padding: 0 0.25rem;
+        font-family: inherit;
+        font-size: 0.8rem;
+      }
+      .tree .dirty {
+        border-color: #ffb86c !important;
+        box-shadow: 0 0 3px #ffb86c44;
+      }
+    </style>
+  </head>
+  <body class="save-editor">
+    <header>
+      <h1>Kernel Panic — savegame editor</h1>
+    </header>
+    <main>
+      <div class="toolbar" id="toolbar"></div>
+      <section id="quick-edit"></section>
+      <section id="tree-root"></section>
+    </main>
+    <div class="toast" id="toast"></div>
+    <script src="/debug/save.js" type="module"></script>
+  </body>
+</html>
diff --git a/debug/save.ts b/debug/save.ts
new file mode 100644
index 0000000..4a70c50
--- /dev/null
+++ b/debug/save.ts
@@ -0,0 +1,467 @@
+/**
+ * Savegame editor — debug tool for inspecting and modifying the `kp:data`
+ * localStorage payload without hand-editing raw JSON.
+ *
+ * Two views:
+ *   1. **Quick-edit panel** — labeled fields for the most common campaign
+ *      values (crew HP, salvage, credits, rep, arc stage).
+ *   2. **Tree editor** — full recursive render of every key/value.
+ *      Scalars are editable inline; objects/arrays collapse.
+ *
+ * All edits are staged in memory. Nothing touches localStorage until you
+ * press "Save". A "Revert" button re-reads from storage. "Export" and
+ * "Import" round-trip the full JSON blob for clipboard / file backup.
+ */
+import { h } from '/src/domUtils.js';
+
+const STORAGE_KEY = 'kp:data';
+const CREW_ARCHETYPES = ['merc', 'razor', 'tech', 'decker'] as const;
+const ARC_STAGES = ['act-1', 'act-2', 'act-3', 'score'] as const;
+const CAMPAIGN_STATES = ['HUB', 'COMBAT', 'ENDED'] as const;
+
+// ---------------------------------------------------------------------------
+// Types (mirrors DataStore's KPData but kept local so we stay import-free
+// from the game runtime — this page must work even if the save is corrupt).
+// ---------------------------------------------------------------------------
+type KPData = {
+  prefs: Record<string, unknown>;
+  runs: unknown[];
+  campaign: Record<string, unknown> | null;
+};
+
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+let data: KPData = { prefs: {}, runs: [], campaign: null };
+let dirty = false;
+
+function loadFromStorage(): KPData {
+  const raw = window.localStorage.getItem(STORAGE_KEY);
+  if (!raw) return { prefs: {}, runs: [], campaign: null };
+  try {
+    const parsed = JSON.parse(raw);
+    return {
+      prefs: parsed.prefs ?? {},
+      runs: parsed.runs ?? [],
+      campaign: parsed.campaign ?? null,
+    };
+  } catch {
+    return { prefs: {}, runs: [], campaign: null };
+  }
+}
+
+function saveToStorage(): void {
+  window.localStorage.setItem(STORAGE_KEY, JSON.stringify(data));
+  dirty = false;
+  toast('Saved to localStorage');
+  render();
+}
+
+function revert(): void {
+  data = loadFromStorage();
+  dirty = false;
+  render();
+  toast('Reverted from localStorage');
+}
+
+// ---------------------------------------------------------------------------
+// Toast
+// ---------------------------------------------------------------------------
+function toast(msg: string): void {
+  const el = document.getElementById('toast')!;
+  el.textContent = msg;
+  el.classList.add('visible');
+  setTimeout(() => el.classList.remove('visible'), 1800);
+}
+
+// ---------------------------------------------------------------------------
+// Deep accessor helpers
+// ---------------------------------------------------------------------------
+
+/** Walk a dotted path like "campaign.crew.0.hp" into the data tree. */
+function getByPath(obj: unknown, path: string): unknown {
+  const parts = path.split('.');
+  let cur: unknown = obj;
+  for (const p of parts) {
+    if (cur == null || typeof cur !== 'object') return undefined;
+    cur = (cur as Record<string, unknown>)[p];
+  }
+  return cur;
+}
+
+function setByPath(obj: unknown, path: string, value: unknown): void {
+  const parts = path.split('.');
+  let cur: unknown = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (cur == null || typeof cur !== 'object') return;
+    cur = (cur as Record<string, unknown>)[parts[i]];
+  }
+  if (cur != null && typeof cur === 'object') {
+    (cur as Record<string, unknown>)[parts[parts.length - 1]] = value;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Quick-edit panel
+// ---------------------------------------------------------------------------
+function renderQuickEdit(): void {
+  const root = document.getElementById('quick-edit')!;
+  root.innerHTML = '';
+  const c = data.campaign;
+  if (!c) {
+    root.appendChild(
+      h('div', { className: 'empty-state' }, [document.createTextNode('No active campaign.')])
+    );
+    return;
+  }
+
+  const panel = h('div', { className: 'quick-edit' }, [
+    h('h2', null, [document.createTextNode('Quick edit — campaign')]),
+  ]);
+
+  const grid = h('div', { className: 'qe-grid' });
+
+  // --- Economy ---
+  grid.appendChild(qeNumberField('Credits', c, 'credits', 0));
+  grid.appendChild(qeNumberField('Rep', c, 'rep', 0, 0, 100));
+
+  // Typed salvage wallet
+  const salvage = c.salvage;
+  if (salvage && typeof salvage === 'object' && !Array.isArray(salvage)) {
+    const sw = salvage as Record<string, unknown>;
+    for (const bucket of ['scrap', 'tech', 'bioware', 'synth']) {
+      if (bucket in sw) {
+        grid.appendChild(qeNumberField(`Salvage: ${bucket}`, sw, bucket, 0));
+      }
+    }
+  } else if (typeof salvage === 'number') {
+    grid.appendChild(qeNumberField('Salvage (legacy)', c, 'salvage', 0));
+  }
+
+  // --- Campaign state ---
+  grid.appendChild(qeSelectField('State', c, 'state', CAMPAIGN_STATES));
+
+  // --- Arc ---
+  const arc = c.arc as Record<string, unknown> | undefined;
+  if (arc) {
+    grid.appendChild(qeSelectField('Arc stage', arc, 'stage', ARC_STAGES));
+    grid.appendChild(qeNumberField('Completed jobs', c, 'completedJobs', 0));
+  }
+
+  // --- Crew quick rows ---
+  const crew = c.crew;
+  if (Array.isArray(crew)) {
+    for (let i = 0; i < crew.length; i++) {
+      const m = crew[i] as Record<string, unknown>;
+      const label = (m.callsign as string) || (m.id as string) || `crew-${i}`;
+      grid.appendChild(
+        h('span', { className: 'callsign', style: 'grid-column: 1 / -1; margin-top: 0.4rem' }, [
+          document.createTextNode(`▸ ${label} (${m.archetype})`),
+        ])
+      );
+      grid.appendChild(qeNumberField('HP', m, 'hp', 0, 0, m.maxHp as number));
+      grid.appendChild(qeNumberField('Max HP', m, 'maxHp', 1));
+      grid.appendChild(qeNumberField('AP', m, 'ap', 0, 0, m.maxAp as number));
+      grid.appendChild(qeNumberField('Max AP', m, 'maxAp', 1));
+      grid.appendChild(qeBoolField('Alive', m, 'alive'));
+      grid.appendChild(qeBoolField('Flatlined', m, 'flatlined'));
+    }
+  }
+
+  panel.appendChild(grid);
+  root.appendChild(panel);
+}
+
+function qeNumberField(
+  label: string,
+  obj: Record<string, unknown>,
+  key: string,
+  fallback: number,
+  min?: number,
+  max?: number
+): HTMLElement {
+  const cur = typeof obj[key] === 'number' ? (obj[key] as number) : fallback;
+  const input = h('input', {
+    type: 'number',
+    value: String(cur),
+    ...(min !== undefined ? { min: String(min) } : {}),
+    ...(max !== undefined ? { max: String(max) } : {}),
+  }) as HTMLInputElement;
+  input.addEventListener('change', () => {
+    const v = Number(input.value);
+    if (!Number.isFinite(v)) return;
+    obj[key] = Number.isInteger(cur) ? Math.round(v) : v;
+    markDirty();
+  });
+  return h('label', null, [document.createTextNode(label), input]);
+}
+
+function qeBoolField(
+  label: string,
+  obj: Record<string, unknown>,
+  key: string
+): HTMLElement {
+  const cur = !!obj[key];
+  const input = h('input', { type: 'checkbox', checked: cur }) as HTMLInputElement;
+  input.addEventListener('change', () => {
+    obj[key] = input.checked;
+    markDirty();
+  });
+  return h('label', null, [document.createTextNode(label), input]);
+}
+
+function qeSelectField(
+  label: string,
+  obj: Record<string, unknown>,
+  key: string,
+  options: readonly string[]
+): HTMLElement {
+  const cur = String(obj[key] ?? '');
+  const select = h(
+    'select',
+    null,
+    options.map(o => {
+      const opt = h('option', { value: o }, [document.createTextNode(o)]) as HTMLOptionElement;
+      if (o === cur) opt.selected = true;
+      return opt;
+    })
+  ) as HTMLSelectElement;
+  select.addEventListener('change', () => {
+    obj[key] = select.value;
+    markDirty();
+  });
+  return h('label', null, [document.createTextNode(label), select]);
+}
+
+function markDirty(): void {
+  dirty = true;
+  renderToolbar();
+}
+
+// ---------------------------------------------------------------------------
+// Tree editor
+// ---------------------------------------------------------------------------
+
+function renderTree(): void {
+  const root = document.getElementById('tree-root')!;
+  root.innerHTML = '';
+  const container = h('div', { className: 'tree' });
+  container.appendChild(buildNode('kp:data', data, 'data', true));
+  root.appendChild(container);
+}
+
+function buildNode(
+  key: string,
+  value: unknown,
+  path: string,
+  startOpen = false
+): HTMLElement {
+  if (value === null || value === undefined) {
+    return leafNode(key, value, path);
+  }
+  if (Array.isArray(value)) {
+    return arrayNode(key, value, path, startOpen);
+  }
+  if (typeof value === 'object') {
+    return objectNode(key, value as Record<string, unknown>, path, startOpen);
+  }
+  return leafNode(key, value, path);
+}
+
+function objectNode(
+  key: string,
+  obj: Record<string, unknown>,
+  path: string,
+  startOpen: boolean
+): HTMLElement {
+  const keys = Object.keys(obj);
+  const details = h('details', startOpen ? { open: true } : {}) as HTMLDetailsElement;
+  const summary = h('summary', null, [
+    h('span', { className: 'key' }, [document.createTextNode(key)]),
+    document.createTextNode(': '),
+    h('span', { className: 'bracket' }, [document.createTextNode('{')]),
+    h('span', { className: 'count' }, [document.createTextNode(` ${keys.length} keys `)]),
+    h('span', { className: 'bracket' }, [document.createTextNode('}')]),
+  ]);
+  details.appendChild(summary);
+  for (const k of keys) {
+    details.appendChild(buildNode(k, obj[k], `${path}.${k}`));
+  }
+  return details;
+}
+
+function arrayNode(
+  key: string,
+  arr: unknown[],
+  path: string,
+  startOpen: boolean
+): HTMLElement {
+  const details = h('details', startOpen ? { open: true } : {}) as HTMLDetailsElement;
+  const summary = h('summary', null, [
+    h('span', { className: 'key' }, [document.createTextNode(key)]),
+    document.createTextNode(': '),
+    h('span', { className: 'bracket' }, [document.createTextNode('[')]),
+    h('span', { className: 'count' }, [document.createTextNode(` ${arr.length} items `)]),
+    h('span', { className: 'bracket' }, [document.createTextNode(']')]),
+  ]);
+  details.appendChild(summary);
+  for (let i = 0; i < arr.length; i++) {
+    details.appendChild(buildNode(String(i), arr[i], `${path}.${i}`));
+  }
+  return details;
+}
+
+function leafNode(key: string, value: unknown, path: string): HTMLElement {
+  const row = h('div', { className: 'leaf' });
+  row.appendChild(
+    h('span', { className: 'key' }, [document.createTextNode(`${key}: `)])
+  );
+
+  if (value === null || value === undefined) {
+    row.appendChild(
+      h('span', { className: 'val-null' }, [document.createTextNode('null')])
+    );
+    return row;
+  }
+
+  if (typeof value === 'boolean') {
+    const select = h(
+      'select',
+      { className: 'inline-edit' },
+      [
+        h('option', { value: 'true', selected: value === true }, [
+          document.createTextNode('true'),
+        ]) as HTMLOptionElement,
+        h('option', { value: 'false', selected: value === false }, [
+          document.createTextNode('false'),
+        ]) as HTMLOptionElement,
+      ]
+    ) as HTMLSelectElement;
+    select.classList.add('val-bool');
+    select.addEventListener('change', () => {
+      setByPath(data, path.replace(/^data\./, ''), select.value === 'true');
+      select.classList.add('dirty');
+      markDirty();
+    });
+    row.appendChild(select);
+    return row;
+  }
+
+  if (typeof value === 'number') {
+    const input = h('input', {
+      className: 'inline-edit val-num',
+      type: 'number',
+      value: String(value),
+      style: `width: ${Math.max(4, String(value).length + 2)}ch`,
+    }) as HTMLInputElement;
+    input.addEventListener('change', () => {
+      const v = Number(input.value);
+      if (!Number.isFinite(v)) return;
+      setByPath(data, path.replace(/^data\./, ''), v);
+      input.classList.add('dirty');
+      markDirty();
+    });
+    row.appendChild(input);
+    return row;
+  }
+
+  // string
+  const str = String(value);
+  const input = h('input', {
+    className: 'inline-edit val-str',
+    type: 'text',
+    value: str,
+    style: `width: ${Math.max(4, str.length + 2)}ch`,
+  }) as HTMLInputElement;
+  input.addEventListener('change', () => {
+    setByPath(data, path.replace(/^data\./, ''), input.value);
+    input.classList.add('dirty');
+    markDirty();
+  });
+  row.appendChild(input);
+  return row;
+}
+
+// ---------------------------------------------------------------------------
+// Toolbar
+// ---------------------------------------------------------------------------
+
+function renderToolbar(): void {
+  const bar = document.getElementById('toolbar')!;
+  bar.innerHTML = '';
+
+  const saveBtn = h('button', null, [
+    document.createTextNode(dirty ? '● Save' : 'Save'),
+  ]);
+  saveBtn.addEventListener('click', saveToStorage);
+
+  const revertBtn = h('button', null, [document.createTextNode('Revert')]);
+  revertBtn.addEventListener('click', revert);
+
+  const exportBtn = h('button', null, [document.createTextNode('Export')]);
+  exportBtn.addEventListener('click', () => {
+    const json = JSON.stringify(data, null, 2);
+    navigator.clipboard.writeText(json).then(
+      () => toast('Copied to clipboard'),
+      () => {
+        // Fallback: download as file
+        const blob = new Blob([json], { type: 'application/json' });
+        const url = URL.createObjectURL(blob);
+        const a = h('a', { href: url, download: 'kp-save.json' }) as HTMLAnchorElement;
+        a.click();
+        URL.revokeObjectURL(url);
+        toast('Downloaded kp-save.json');
+      }
+    );
+  });
+
+  const importBtn = h('button', null, [document.createTextNode('Import')]);
+  importBtn.addEventListener('click', () => {
+    const json = prompt('Paste JSON:');
+    if (!json) return;
+    try {
+      const parsed = JSON.parse(json);
+      data = {
+        prefs: parsed.prefs ?? {},
+        runs: parsed.runs ?? [],
+        campaign: parsed.campaign ?? null,
+      };
+      dirty = true;
+      render();
+      toast('Imported — press Save to persist');
+    } catch (e) {
+      toast(`Import failed: ${(e as Error).message}`);
+    }
+  });
+
+  const nukeBtn = h('button', { className: 'danger' }, [
+    document.createTextNode('Nuke save'),
+  ]);
+  nukeBtn.addEventListener('click', () => {
+    if (!confirm('Delete ALL save data from localStorage? This cannot be undone.')) return;
+    window.localStorage.removeItem(STORAGE_KEY);
+    data = { prefs: {}, runs: [], campaign: null };
+    dirty = false;
+    render();
+    toast('Save data nuked');
+  });
+
+  bar.append(saveBtn, revertBtn, exportBtn, importBtn, nukeBtn);
+}
+
+// ---------------------------------------------------------------------------
+// Render
+// ---------------------------------------------------------------------------
+
+function render(): void {
+  renderToolbar();
+  renderQuickEdit();
+  renderTree();
+}
+
+// ---------------------------------------------------------------------------
+// Boot
+// ---------------------------------------------------------------------------
+
+data = loadFromStorage();
+render();
diff --git a/scripts/copy-assets.mjs b/scripts/copy-assets.mjs
index 239a007..1447be1 100644
--- a/scripts/copy-assets.mjs
+++ b/scripts/copy-assets.mjs
@@ -32,6 +32,7 @@ const files = [
   // Debug harness pages (their scripts are compiled by tsc into dist/debug/).
   'debug/index.html',
   'debug/map.html',
+  'debug/save.html',
 ];
 
 // Directories copied recursively.

From afc548a5369a4d2ec934ff8658e7c8b7f11de4f8 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Tue, 9 Jun 2026 09:38:43 -0700
Subject: [PATCH 06/55] campaign arc reveal in the hub

---
 components/ContractSelect.ts           |  24 ++-
 components/CrewRoster.ts               |  16 ++
 debug/save.ts                          |  58 +++-----
 docs/phase-3-plan.md                   |  49 +++---
 index.ts                               |  23 +++
 src/game/Campaign.ts                   |  56 +++++--
 src/game/archetypes/Decker.ts          |   6 +-
 src/game/hub/arcSurface.ts             |  99 +++++++++++++
 src/game/hub/hubReveals.ts             |  21 ++-
 src/game/persistence.ts                |   1 +
 src/types.ts                           |   5 +-
 sw-core.js                             |   1 +
 tests/unit/game/Campaign.test.ts       | 197 ++++++++++++++++---------
 tests/unit/game/hub/arcSurface.test.ts | 134 +++++++++++++++++
 tests/unit/game/hub/hubReveals.test.ts |  29 ++++
 15 files changed, 563 insertions(+), 156 deletions(-)
 create mode 100644 src/game/hub/arcSurface.ts
 create mode 100644 tests/unit/game/hub/arcSurface.test.ts

diff --git a/components/ContractSelect.ts b/components/ContractSelect.ts
index 2eddd21..9de6f39 100644
--- a/components/ContractSelect.ts
+++ b/components/ContractSelect.ts
@@ -6,6 +6,7 @@
 
 import { h } from '/src/domUtils.js';
 import { encounterHostileCount } from '/src/game/encounters.js';
+import { isScoreSiteContract } from '/src/game/hub/arcSurface.js';
 import { cloneObjective } from '/src/game/hub/Curator.js';
 import type { Contract } from '/src/game/hub/Curator.js';
 
@@ -149,6 +150,12 @@ const CSS = `
   white-space: nowrap;
 }
 
+.known.score-site {
+  color: #020403;
+  background: var(--board-warn);
+  border-color: var(--board-warn);
+}
+
 .meta {
   color: var(--board-dim);
   font-size: 0.84rem;
@@ -185,6 +192,7 @@ const CSS = `
 
 class ContractSelect extends HTMLElement {
   #contracts: Contract[] = [];
+  #scoreTargetSiteId: string | null = null;
   #selectedIndex = 0;
   #ready = false;
   #listEl: HTMLElement | null = null;
@@ -235,6 +243,14 @@ class ContractSelect extends HTMLElement {
     if (this.#ready) this.#render();
   }
 
+  setScoreTargetSiteId(siteId: string | null) {
+    if (siteId !== null && (typeof siteId !== 'string' || siteId.length === 0)) {
+      throw new TypeError('<contract-select>.setScoreTargetSiteId requires a site id or null');
+    }
+    this.#scoreTargetSiteId = siteId;
+    if (this.#ready) this.#render();
+  }
+
   show() {
     this.setAttribute('open', '');
     queueMicrotask(() => this.#focusSelected());
@@ -273,7 +289,7 @@ class ContractSelect extends HTMLElement {
               }),
               h('span', { className: 'target', textContent: jobTitleCopy(contract) }),
             ]),
-            h('div', { className: 'location' }, locationLine(contract)),
+            h('div', { className: 'location' }, locationLine(contract, this.#scoreTargetSiteId)),
             h('div', { className: 'meta', textContent: rewardCopy(contract) }),
           ]),
           h('div', { className: 'take', textContent: 'TAKE THE JOB' }),
@@ -352,12 +368,14 @@ function jobTitleCopy(contract: Contract): string {
   return `// ${contract.objective.title}${window}`;
 }
 
-function locationLine(contract: Contract): HTMLElement[] {
+function locationLine(contract: Contract, scoreTargetSiteId: string | null): HTMLElement[] {
   const { principal, site, siteState, locationSiteId } = contract.context;
   const place = site ? `${principal.label} ${site.label}` : principal.label;
   const state = siteState ? ` [${siteState.label}]` : '';
   const nodes: HTMLElement[] = [h('span', { textContent: `Location: ${place}${state}` })];
-  if (locationSiteId) {
+  if (isScoreSiteContract(contract, scoreTargetSiteId)) {
+    nodes.push(h('span', { className: 'known score-site', textContent: 'SCORE SITE' }));
+  } else if (locationSiteId) {
     nodes.push(h('span', { className: 'known', textContent: '// known site' }));
   }
   return nodes;
diff --git a/components/CrewRoster.ts b/components/CrewRoster.ts
index 1dd7337..a5abeee 100644
--- a/components/CrewRoster.ts
+++ b/components/CrewRoster.ts
@@ -11,6 +11,7 @@
  * Usage:
  *   rosterEl.setCrew(campaign.crew, {
  *     salvage: campaign.salvage,
+ *     campaignStatus: 'ACT 2: CASING | SCORE: Matsuda server farm',
  *     availableRecruits: campaign.availableRecruits,
  *     recruitedThisVisit: campaign.recruitedThisVisit,
  *   });
@@ -116,6 +117,14 @@ const CSS = `
   letter-spacing: 0.08em;
 }
 
+.campaign-status {
+  margin: -0.35rem 0 0.75rem;
+  text-align: center;
+  color: #ffd166;
+  font-size: 0.82rem;
+  letter-spacing: 0.08em;
+}
+
 .body {
   display: grid;
   grid-template-columns: 1fr 1fr;
@@ -308,6 +317,7 @@ class CrewRoster extends HTMLElement {
   #detailEl: HTMLElement | null = null;
   #titleEl: HTMLElement | null = null;
   #balanceEl: HTMLElement | null = null;
+  #campaignStatusEl: HTMLElement | null = null;
   #hintEl: HTMLElement | null = null;
   #panelEl: HTMLElement | null = null;
   #recruitSectionEl: HTMLElement | null = null;
@@ -329,6 +339,7 @@ class CrewRoster extends HTMLElement {
 
     this.#titleEl = h('h2', { className: 'title', textContent: '── CREW ROSTER ──' });
     this.#balanceEl = h('p', { className: 'balance' });
+    this.#campaignStatusEl = h('p', { className: 'campaign-status' });
 
     this.#listEl = document.createElement('crew-list') as CrewList;
     this.#listEl.addEventListener('select', evt =>
@@ -359,6 +370,7 @@ class CrewRoster extends HTMLElement {
     this.#panelEl = h('section', { className: 'panel' }, [
       this.#titleEl,
       this.#balanceEl,
+      this.#campaignStatusEl,
       body,
       this.#recruitSectionEl,
       this.#hintEl,
@@ -389,10 +401,12 @@ class CrewRoster extends HTMLElement {
     crew: CrewMember[],
     {
       salvage = emptySalvage(),
+      campaignStatus = '',
       availableRecruits = [] as CrewMember[],
       recruitedThisVisit = false,
     }: {
       salvage?: TypedSalvage;
+      campaignStatus?: string;
       availableRecruits?: CrewMember[];
       recruitedThisVisit?: boolean;
     } = {}
@@ -407,6 +421,8 @@ class CrewRoster extends HTMLElement {
     // Show typed breakdown + total
     const total = totalSalvage(this.#salvage);
     this.#balanceEl!.textContent = `SALVAGE ${total} · ${formatSalvageCompact(this.#salvage)}`;
+    this.#campaignStatusEl!.textContent = campaignStatus;
+    this.#campaignStatusEl!.style.display = campaignStatus ? '' : 'none';
     this.#recruitFocused = false;
     this.#selectedRecruitIndex = -1;
     // Crew list handles its own rendering; selection triggers detail update.
diff --git a/debug/save.ts b/debug/save.ts
index 4a70c50..d83d662 100644
--- a/debug/save.ts
+++ b/debug/save.ts
@@ -15,6 +15,7 @@
 import { h } from '/src/domUtils.js';
 
 const STORAGE_KEY = 'kp:data';
+/* eslint-disable-next-line no-unused-vars */
 const CREW_ARCHETYPES = ['merc', 'razor', 'tech', 'decker'] as const;
 const ARC_STAGES = ['act-1', 'act-2', 'act-3', 'score'] as const;
 const CAMPAIGN_STATES = ['HUB', 'COMBAT', 'ENDED'] as const;
@@ -79,6 +80,7 @@ function toast(msg: string): void {
 // ---------------------------------------------------------------------------
 
 /** Walk a dotted path like "campaign.crew.0.hp" into the data tree. */
+/* eslint-disable-next-line no-unused-vars */
 function getByPath(obj: unknown, path: string): unknown {
   const parts = path.split('.');
   let cur: unknown = obj;
@@ -196,11 +198,7 @@ function qeNumberField(
   return h('label', null, [document.createTextNode(label), input]);
 }
 
-function qeBoolField(
-  label: string,
-  obj: Record<string, unknown>,
-  key: string
-): HTMLElement {
+function qeBoolField(label: string, obj: Record<string, unknown>, key: string): HTMLElement {
   const cur = !!obj[key];
   const input = h('input', { type: 'checkbox', checked: cur }) as HTMLInputElement;
   input.addEventListener('change', () => {
@@ -250,12 +248,7 @@ function renderTree(): void {
   root.appendChild(container);
 }
 
-function buildNode(
-  key: string,
-  value: unknown,
-  path: string,
-  startOpen = false
-): HTMLElement {
+function buildNode(key: string, value: unknown, path: string, startOpen = false): HTMLElement {
   if (value === null || value === undefined) {
     return leafNode(key, value, path);
   }
@@ -290,12 +283,7 @@ function objectNode(
   return details;
 }
 
-function arrayNode(
-  key: string,
-  arr: unknown[],
-  path: string,
-  startOpen: boolean
-): HTMLElement {
+function arrayNode(key: string, arr: unknown[], path: string, startOpen: boolean): HTMLElement {
   const details = h('details', startOpen ? { open: true } : {}) as HTMLDetailsElement;
   const summary = h('summary', null, [
     h('span', { className: 'key' }, [document.createTextNode(key)]),
@@ -313,30 +301,22 @@ function arrayNode(
 
 function leafNode(key: string, value: unknown, path: string): HTMLElement {
   const row = h('div', { className: 'leaf' });
-  row.appendChild(
-    h('span', { className: 'key' }, [document.createTextNode(`${key}: `)])
-  );
+  row.appendChild(h('span', { className: 'key' }, [document.createTextNode(`${key}: `)]));
 
   if (value === null || value === undefined) {
-    row.appendChild(
-      h('span', { className: 'val-null' }, [document.createTextNode('null')])
-    );
+    row.appendChild(h('span', { className: 'val-null' }, [document.createTextNode('null')]));
     return row;
   }
 
   if (typeof value === 'boolean') {
-    const select = h(
-      'select',
-      { className: 'inline-edit' },
-      [
-        h('option', { value: 'true', selected: value === true }, [
-          document.createTextNode('true'),
-        ]) as HTMLOptionElement,
-        h('option', { value: 'false', selected: value === false }, [
-          document.createTextNode('false'),
-        ]) as HTMLOptionElement,
-      ]
-    ) as HTMLSelectElement;
+    const select = h('select', { className: 'inline-edit' }, [
+      h('option', { value: 'true', selected: value === true }, [
+        document.createTextNode('true'),
+      ]) as HTMLOptionElement,
+      h('option', { value: 'false', selected: value === false }, [
+        document.createTextNode('false'),
+      ]) as HTMLOptionElement,
+    ]) as HTMLSelectElement;
     select.classList.add('val-bool');
     select.addEventListener('change', () => {
       setByPath(data, path.replace(/^data\./, ''), select.value === 'true');
@@ -390,9 +370,7 @@ function renderToolbar(): void {
   const bar = document.getElementById('toolbar')!;
   bar.innerHTML = '';
 
-  const saveBtn = h('button', null, [
-    document.createTextNode(dirty ? '● Save' : 'Save'),
-  ]);
+  const saveBtn = h('button', null, [document.createTextNode(dirty ? '● Save' : 'Save')]);
   saveBtn.addEventListener('click', saveToStorage);
 
   const revertBtn = h('button', null, [document.createTextNode('Revert')]);
@@ -434,9 +412,7 @@ function renderToolbar(): void {
     }
   });
 
-  const nukeBtn = h('button', { className: 'danger' }, [
-    document.createTextNode('Nuke save'),
-  ]);
+  const nukeBtn = h('button', { className: 'danger' }, [document.createTextNode('Nuke save')]);
   nukeBtn.addEventListener('click', () => {
     if (!confirm('Delete ALL save data from localStorage? This cannot be undone.')) return;
     window.localStorage.removeItem(STORAGE_KEY);
diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 068881f..5cfa057 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -13,13 +13,13 @@ The campaign is a **Neuromancer-shaped arc**: a crew of operators assembles over
 
 ### Campaign shape
 
-| Arc | Runs | What happens | Systems |
-|-----|------|-------------|---------|
-| **Act 1: Street level** | 1–5 | Build rep, learn combat, recruit crew. Pure Meatspace gigs. Unconnected contracts from P2.5.M2.10 recipes. | P2.5.M2 objectives, P2.5.M5 economy, P2.5.M7 site roster begins |
-| **Turning point** | ~5 | Reach top rep tier. Offered the Score (or discover it). Recruit the Decker. | Decker joins crew; Score target site designated |
-| **Act 2: Casing** | 6–10 | Prep runs at/near the target site + resource building. Cyberspace available on some contracts. Learning the flip. Curator biases toward Score-adjacent contracts. | P2.5.M7 persistence (casing), Cyberspace, simstim flip |
+| Stage | Runs | What happens | Systems |
+|-------|------|-------------|---------|
+| **Stage 1: Street level** | 1–5 | Build rep, learn combat, recruit crew. Pure Meatspace gigs. Unconnected contracts from P2.5.M2.10 recipes. | P2.5.M2 objectives, P2.5.M5 economy, P2.5.M7 site roster begins |
+| **Turning point** | ~5 | Reach KNOWN rep tier. Curator reveals the Score and assigns the Decker in one beat. | Decker joins crew; Score target synthesized (always new, CRITICAL-tier) |
+| **Stage 2: Casing** | 6–10 | Prep runs targeting the Score principal's org + resource building. Cyberspace available on some contracts. Learning the flip. Curator biases toward same-principal contracts. | P2.5.M7 persistence (casing), Cyberspace, simstim flip |
 | **The Clock starts** | ~8 | Pressure mounts — rival crew, corp heat, neural degradation. Contracts get harder; delay has cost. | Clock mechanic |
-| **Act 3: The Score** | 11–13 | Final prep runs, then the big job. Dual-layer climax: Meatspace breach + Cyberspace penetration. | Everything converges |
+| **Stage 3: The Score** | 11–13 | Final prep runs, then the big job. Dual-layer climax: Meatspace breach + Cyberspace penetration. | Everything converges |
 
 ### The simstim flip
 
@@ -41,7 +41,7 @@ A new **player archetype** recruited mid-campaign (late Act 1 / start of Act 2),
 
 | Milestone | Status |
 |---|---|
-| P3.M1 — Campaign arc structure | 🚧 In progress — P3.M1.1–P3.M1.3 done; Hub arc surface next |
+| P3.M1 — Campaign arc structure | 🚧 In progress — P3.M1.1–P3.M1.4 done |
 | P3.M2 — The Decker archetype | 🚧 In progress — class + Drone Override Hack done; recruitment flow pending |
 | P3.M3 — Cyberspace grid + ICE | 🔲 Planned |
 | P3.M4 — Simstim flip (dual-deploy) | 🔲 Planned |
@@ -63,7 +63,7 @@ Phase 3 should start from the shipped Phase 2.5 surface, not rebuild it:
 - `LocationSite` already reserves `tier: 'score'` and `scoreTarget`; P2.5.M7 never sets them, so P3.M1 owns designation.
 - `Curator.generateContracts(rng, campaign)` already accepts `arcStage` and stores it into `contract.context.arcStage`; P3.M1 owns deriving the stage from campaign state and using it for real recipe weighting / Score targeting.
 - P2.7.M6.2 landed: entity snapshot `extra` property bags and campaign-scoped key items are available for Decker / Cyberspace state instead of expanding the old top-level snapshot union.
-- Hub reveal plumbing already exists (`applyFirstHubReveal`, Finn, Clinic, Terminal), so Decker recruitment should use the same progressive reveal pattern rather than adding a parallel modal.
+- Hub reveal plumbing already exists (`applyFirstHubReveal`, Finn, Clinic, Terminal). The Score reveal and Decker recruitment share a single `score-reveal` Hub reveal beat rather than using a separate modal.
 
 ## Phase 2.5 foundations (prerequisites)
 
@@ -72,12 +72,12 @@ Phase 3 depends on specific hooks built into Phase 2.5 milestones:
 | 2.5 Milestone | Phase 3 hook | Notes |
 |---|---|---|
 | **P2.5.M2.10** (recipes) | Recipe context accepts **arc stage** input | Phase 3 uses this to bias contract generation toward Score-adjacent objectives in Acts 2–3 |
-| **P2.5.M5** (economy/rep) | Top rep tier defined and reachable | Phase 3 gates Decker recruitment and Score access at this tier |
-| **P2.5.M7** (persistence) | Location schema includes `scoreTarget` flag; site roster + mutation deltas | Phase 3 designates one roster site as the Score target; player "cases" it across visits |
+| **P2.5.M5** (economy/rep) | KNOWN rep tier defined and reachable | Phase 3 gates Decker recruitment and Score access at KNOWN (50) |
+| **P2.5.M7** (persistence) | Location schema includes `scoreTarget` flag; site roster + mutation deltas | Phase 3 synthesizes a new CRITICAL-tier Score target; player "cases" it across visits. Roster sites for the same principal provide recon value |
 
 ### Score target identification
 
-Score-target sites always use roster-stored dimensions (P2.7.M1.5: `mapWidth`, `mapHeight`, `seed`, mutation deltas); contract `difficulty` scales encounter composition only, not footprint.
+The Score target is always a newly synthesized CRITICAL-tier site, never promoted from the roster. This ensures the map is large enough to support escalated hostile placement as heat grows. Act 2 Curator bias weights toward the same principal (same corp, different sites) so the player learns the organization before the climax. The synthesized site uses roster-stored dimensions (P2.7.M1.5: `mapWidth`, `mapHeight`, `seed`, mutation deltas from visits); contract `difficulty` scales encounter composition only, not footprint.
 
 ## Milestones — detail
 
@@ -91,16 +91,17 @@ Score-target sites always use roster-stored dimensions (P2.7.M1.5: `mapWidth`, `
 
 - **Arc state:** Campaign save tracks `arcStage` (`act-1` / `act-2` / `act-3` / `score`), run count, and arc-specific flags (`deckerRecruited`, `scoreRevealed`, `clockStarted`, `scoreAttempted`, `scoreCompleted`). Prefer a typed `Campaign.arc` record over stuffing more opaque keys into `Campaign.meta`; legacy saves can normalize from absent `arc` into Act 1.
 - **Act transitions:** Define triggers for act boundaries:
-  - Act 1 → Act 2: reach top rep tier + minimum successful job count (recommended: `completedJobs >= 4`). Triggers Score reveal and Decker recruitment opportunity.
-  - Act 2 → Act 3: Decker recruited + Score target site visited at least once + Clock threshold (recommended: `completedJobs >= 9`). Triggers "final prep" phase.
+  - Act 1 → Act 2: reach `KNOWN` rep tier (50) + minimum successful job count (recommended: `completedJobs >= 4`). Triggers Score reveal and Decker recruitment (same beat).
+  - Act 2 → Act 3: `completedJobs >= 9` + at least 4 **living** (non-flatlined) crew + at least 3 visited sites sharing the Score target's principal (including the Score target itself). The Decker gate is gone — the Decker is always assigned at Act 2 entry. The crew gate rewards keeping people alive; the principal-sites gate is the "casing" payoff — you've hit enough of the org's facilities to know how they operate. Triggers "final prep" phase.
   - Score available: Act 3 + player-initiated (choose to attempt the Score from the Hub).
-- **Score target designation:** At Act 2 entry, choose exactly one remembered or newly seeded `LocationSite`, set `scoreTarget: true`, and promote `tier: 'score'` so P2.5.M7 eviction preserves it. If no roster site exists yet, synthesize a site identity from the Curator lexicon and add it to the roster; do not silently defer the Score reveal.
+- **Score target designation:** At Act 2 entry, always synthesize a new CRITICAL-tier `LocationSite` from Curator lexicon as the Score target. The Score is a location the player hasn't seen — Act 2 contracts bias toward the same principal so the player learns about the organization before hitting the crown jewel. Existing roster sites are never promoted; they serve as intel and casing prep. Multiple persisted score targets, or score-tier sites missing `scoreTarget`, throw during Hub-entry arc evaluation.
+- **Decker recruitment:** Same narrative beat as the Score reveal. The Curator assigns a named Decker — no player choice modal. The crew gains a specialist as part of the Score pitch ("here's the job, and here's the person who can open it"). Future phases may differentiate Decker stats and offer a choice; for now the assignment is the narrative.
 - **Arc-aware Curator:** Current code already passes through `arcStage`; P3.M1 must make it behaviorally meaningful:
   - Act 1 = broad pool, unconnected gigs, no Score-target pinning.
-  - Act 2 = at least one board slot biased toward the Score target or its principal/site identity when available.
+  - Act 2 = at least one board slot biased toward the Score target's principal (same corp, different sites) so the player learns the org before the climax.
   - Act 3 = board mostly prep contracts at or near the Score target, plus a separate player-initiated Score action instead of a random roll.
   - Score = special contract build path; not part of the normal three-card job board.
-- **Hub surface:** Hub status / Terminal shows current act, Clock pressure, and Score target label once revealed. The Score reveal uses progressive Hub reveal plumbing so the Curator can present the target as a campaign beat instead of leaving the player to infer it from state changes.
+- **Hub surface:** Hub status / Terminal shows current stage, Clock pressure, and Score target label once revealed. User-facing labels use "Stage" (STAGE 1, STAGE 2, etc.) — code and persistence keep `arc`/`arcStage` naming. The Score reveal uses progressive Hub reveal plumbing so the Curator can present the target and the Decker together as a single campaign beat.
 - **Win/loss conditions:**
   - **Win:** Complete the Score (extract with objective satisfied from the final mission).
   - **Loss (flatline):** Entire crew wiped during any run (existing behavior, but now with arc context for the chronicle).
@@ -131,17 +132,19 @@ Neural degradation is deferred until Cyberspace is fun enough to deserve a jack-
 |---|---|---|---|
 | **P3.M1.1 Arc record** | ✅ Done | Add `Campaign.arc`, derive `arcStage`, persist/restore, normalize old saves to Act 1 | constructor validation, snapshot round-trip, invalid stage throws |
 | **P3.M1.2 Transitions** | ✅ Done | Advance acts from `rep`, `completedJobs`, Decker flag, Score-site visit | boundary tests around job counts and rep tier |
-| **P3.M1.3 Score target** | ✅ Done | Promote one roster site to `tier: 'score'`; preserve through eviction | exactly-one target, no eviction at roster cap, synthetic target when roster empty |
-| **P3.M1.4 Hub arc surface** | 🔲 Planned | Curator presents the Score reveal; Hub / Terminal shows act and Score target; contract selection labels Score-site jobs | one-shot reveal, status render, Score-site badge |
+| **P3.M1.3 Score target** | ✅ Done | Always synthesize a new CRITICAL-tier Score target; preserve through eviction | exactly-one target, no eviction at roster cap, always synthesized (never promoted) |
+| **P3.M1.4 Hub arc surface** | ✅ Done | Curator presents Score + Decker reveal; Hub / Terminal shows stage and Score target; contract selection labels Score-site jobs | one-shot reveal, status render, Score-site badge |
 | **P3.M1.5 Clock** | 🔲 Planned | Start heat after threshold; hard loss at deadline; show status | heat math, deadline loss, no loss after Score attempt |
-| **P3.M1.6 Curator bias** | 🔲 Planned | Pass campaign-derived arc context; bias board slots by act and score target | seeded boards show expected `arcStage` and target-site frequency |
+| **P3.M1.6 Curator bias** | 🔲 Planned | Pass campaign-derived arc context; bias board slots by act and score target's principal | seeded boards show expected `arcStage` and same-principal frequency in Act 2+ |
 | **P3.M1.7 Score entry** | 🔲 Planned | Hub action creates the special Score contract in Act 3 only | availability gates, deployment path, attempted flag |
 
 **P3.M1.1 implementation note:** `Campaign` now owns a typed `arc` record (`arcStage`, `deckerRecruited`, `scoreRevealed`, `clockStarted`, `scoreAttempted`, `scoreCompleted`) plus an `arcStage` getter for Curator context. New snapshots serialize the record; pre-P3 snapshots normalize to Act 1; malformed persisted arc data throws during restore instead of being silently repaired.
 
-**P3.M1.2 implementation note:** Hub entry now runs a monotonic arc transition evaluator. Act 1 advances to Act 2 at `TRUSTED` Rep plus `completedJobs >= 4` and sets `scoreRevealed`; successful extractions increment `completedJobs`, abort extractions do not. Act 2 advances to Act 3 once a Decker has joined the crew, `completedJobs >= 9`, and a score-target roster site has a prior visit marker (`lastVisitedJob > 0`). M1.2 does not synthesize or promote the Score target — that remains P3.M1.3.
+**P3.M1.2 implementation note:** Hub entry now runs a monotonic arc transition evaluator. Act 1 advances to Act 2 at `KNOWN` Rep (50) plus `completedJobs >= 4`, sets `scoreRevealed`, and auto-assigns a Decker to the crew. Act 2 advances to Act 3 once `completedJobs >= 9`, at least 4 non-flatlined crew, and at least 3 visited roster sites sharing the Score target's principal (including the target itself). The crew gate counts living members only — attrition blocks advancement. Successful extractions increment `completedJobs`, abort extractions do not. M1.2 does not synthesize the Score target — that remains P3.M1.3.
 
-**P3.M1.3 implementation note:** Score reveal now guarantees exactly one Score target. If a roster site exists at Act 2 entry, the most recently visited site is promoted to `tier: 'score'` with `scoreTarget: true`, preserving its seed, dimensions, mutation deltas, and exploration memory. If the roster is empty, Campaign synthesizes a CRITICAL-footprint score site from Curator lexicon principal/site tokens instead of deferring reveal. Multiple persisted score targets, or score-tier sites missing `scoreTarget`, throw during Hub-entry arc evaluation.
+**P3.M1.3 implementation note:** Score reveal always synthesizes a new CRITICAL-tier site from Curator lexicon `corp` principal and `corp/data/security/infrastructure/hidden` site tokens. Existing roster sites are never promoted — the Score is always a location the player hasn't visited yet. The synthesized site gets `scoreTarget: true`, `tier: 'score'`, and CRITICAL-footprint dimensions to support escalated hostile placement. Multiple persisted score targets, or score-tier sites missing `scoreTarget`, throw during Hub-entry arc evaluation.
+
+**P3.M1.4 implementation note:** Score reveal is now player-visible. A one-shot `score-reveal` Hub reveal lets the Curator name the target, introduce the Decker, and teach the `SCORE SITE` board badge — all in a single narrative beat. The Hub status row and Terminal crew roster show the current stage label (user-facing "STAGE N") plus Score target once revealed, and `<contract-select>` highlights contracts whose `locationSiteId` matches the campaign Score target. Shared `arcSurface` helpers own the copy and invariant checks so multiple Score targets, or revealed Score state without a target, fail loud instead of rendering misleading UI.
 
 **Acceptance:**
 
@@ -166,7 +169,7 @@ Neural degradation is deferred until Cyberspace is fun enough to deserve a jack-
 - **Archetype definition:** Stats, AP costs, base loadout. Comparable to Merc/Razor/Tech in Meatspace capability but not optimized for it.
 - **Signature ability — Drone Override Hack:** Target a corp drone within range; spend AP to attempt override. On success, drone switches to PLAYER faction for N turns (or until destroyed). Reuses existing drone AI with faction flip. Failure may trigger alarm (P2.5.M2.1 cadence).
 - **Cyberspace stats:** The Decker has Cyberspace-specific attributes (e.g. RAM, intrusion strength, ICE resistance) used in P3.M3. Other archetypes cannot jack in (or can with severe penalties — TBD).
-- **Recruitment flow:** Triggered at Act 1 → Act 2 transition. Uses the **progressive Hub reveal** system from P2.5.M5: Curator message introduces the Decker on Hub entry when rep threshold is met and `arc.deckerRecruited` is false. Same pattern as Finn's introduction and Terminal explanation — the Hub grows with the campaign.
+- **Recruitment flow:** Same narrative beat as the Score reveal — triggered at Act 1 → Act 2 transition. The Curator assigns a named Decker (no player choice modal); the `score-reveal` Hub reveal introduces both the Score target and the Decker in one moment. Same progressive Hub reveal pattern as Finn's introduction and Terminal explanation — the Hub grows with the campaign. Future phases may differentiate Decker stats and offer a choice; for now the assignment is the narrative.
 - **Deployment:** The Decker is deployable as a solo operator on any contract (Meatspace only on non-Cyberspace contracts). On Cyberspace contracts, the Decker is one of the dual-deploy pair (see P3.M4).
 - **Roster rule:** The Decker is a named crew member, not a temporary ability unlock. Recruitment should add them to `Campaign.crew` through the existing recruit/callsign machinery or a deliberately separate `recruitDecker()` path with the same validation guarantees. Do not let normal random recruitment roll a Decker before Act 2.
 - **Jack-in authority:** Only a living Decker can start P3.M3 jack-in. If a contract has a Cyberspace requirement and no living Decker is available, deployment should fail loudly at the Hub selection layer rather than starting an unwinnable run.
@@ -175,7 +178,7 @@ Neural degradation is deferred until Cyberspace is fun enough to deserve a jack-
 
 - ✅ Decker archetype playable in Meatspace: move, attack, interact — comparable to other archetypes (`Decker` extends `Crew`, `baseHitChance` 0.7, `@` glyph).
 - ✅ Drone Override Hack: golden-path test — target drone, override succeeds, drone attacks corp allies for N turns, reverts or is destroyed (`droneOverride.ts`, `Decker.test.ts`). Failed roll burns AP and trips the alarm.
-- 🔲 Recruitment: gated by arc state; not available in Act 1; golden-path test for recruitment flow. **Ready after P3.M1.4 confirms the shared Hub reveal surface.** Decker is registered but excluded from `ARCHETYPE_IDS` and `RECRUIT_ARCHETYPE_POOL` so random recruitment can't roll one early.
+- 🔲 Recruitment: same beat as Score reveal (Act 1 → Act 2 transition); Curator assigns a named Decker, no choice modal. Not available in Act 1; golden-path test for recruitment flow. Decker is registered but excluded from `ARCHETYPE_IDS` and `RECRUIT_ARCHETYPE_POOL` so random recruitment can't roll one early.
 - ✅ Snapshot: Decker state persists (campaign + run round-trip); live drone-override state round-trips through the patrol snapshot. Cyberspace attributes deferred to P3.M3.
 - ✅ Key help: Decker glyph (`@`) and OVERRIDE ability description via shared `ARCHETYPES[id].perkLabel`.
 
diff --git a/index.ts b/index.ts
index 88687d4..b51aab6 100644
--- a/index.ts
+++ b/index.ts
@@ -74,6 +74,7 @@ import { hasLineOfSight } from '/src/game/LineOfSight.js';
 import { ITEM_ID, getItemById } from '/src/game/items.js';
 import type { CampaignSnapshot } from '/src/game/persistence.js';
 import type { Contract } from '/src/game/hub/Curator.js';
+import { formatHubArcStatus, scoreTargetSiteId } from '/src/game/hub/arcSurface.js';
 import { isTerminalAccessible } from '/src/game/hub/hubReveals.js';
 import type { Crew } from '/src/game/Crew.js';
 import { resolveEntityLabel, type Entity } from '/src/game/Entity.js';
@@ -125,6 +126,7 @@ type RunBriefingElement = ModalElement & {
 };
 type ContractSelectElement = ModalElement & {
   setContracts(contracts: Contract[]): void;
+  setScoreTargetSiteId(siteId: string | null): void;
 };
 type CrashDumpElement = ModalElement & {
   setTelemetry(telemetry: Record<string, unknown>): void;
@@ -146,6 +148,7 @@ type CrewRosterElement = ModalElement & {
     crew: Crew[],
     opts?: {
       salvage?: TypedSalvage;
+      campaignStatus?: string;
       availableRecruits?: Crew[];
       recruitedThisVisit?: boolean;
     }
@@ -712,6 +715,7 @@ function presentCrewRoster() {
   campaign.backfillRecruitsIfEligible();
   crewRosterEl.setCrew(campaign.crew, {
     salvage: campaign.salvage,
+    campaignStatus: formatHubArcStatus(campaign),
     availableRecruits: campaign.availableRecruits,
     recruitedThisVisit: campaign.recruitedThisVisit,
   });
@@ -740,6 +744,7 @@ function presentBriefing(contract: Contract) {
 }
 
 function presentContractSelect(contracts: Contract[]) {
+  contractSelectEl.setScoreTargetSiteId(campaign ? scoreTargetSiteId(campaign) : null);
   contractSelectEl.setContracts(contracts);
   contractSelectEl.show();
 }
@@ -2006,6 +2011,22 @@ function buildCombatHudSnapshot(scene: ShellScene | null): CombatHudSummaryInput
   };
 }
 
+function buildHubHudRows(scene: ShellScene | null) {
+  if (!campaign || scene?.state !== CAMPAIGN_STATE.HUB) return undefined;
+  return [
+    {
+      text: formatHubArcStatus(campaign),
+      anchor: 'top-left' as const,
+      row: 1,
+      color: '#ffd166',
+      glowColor: '#ffd166',
+      accentColor: 'rgba(255, 209, 102, 0.5)',
+      uppercase: true,
+      maxWidth: 520,
+    },
+  ];
+}
+
 function paint(stateHint: InputState = activeInputState()): void {
   const run = currentScene();
   if (canvas.hidden) {
@@ -2031,6 +2052,7 @@ function paint(stateHint: InputState = activeInputState()): void {
     lookCursor,
     principalId,
     locationLabel: currentLocationLabel(),
+    hudRows: buildHubHudRows(run),
     combatHud: buildCombatHudSnapshot(run),
   });
   crt.alertTint = run.state === RUN_STATE.COMBAT && run.world.alarmActive;
@@ -2079,6 +2101,7 @@ function statusLine(state: InputState): string {
   } else {
     if (!campaign) return stateLabel();
     const repLabel = REP_LABEL.find(b => campaign!.rep >= b.min)?.label ?? 'UNKNOWN';
+    context = escapeHtml(formatHubArcStatus(campaign));
     // Hub identity drops the typed-salvage compact tag —
     // the inventory overlay (`i` in Hub) is the canonical wallet view with
     // full bucket names. Total Cred / Rep / crew counts stay on this line.
diff --git a/src/game/Campaign.ts b/src/game/Campaign.ts
index f9415b6..32a413c 100644
--- a/src/game/Campaign.ts
+++ b/src/game/Campaign.ts
@@ -61,6 +61,10 @@ import type { RunResult, Outcome } from './Run.js';
 export const SITE_ROSTER_CAP = 6;
 export const ARC_ACT_2_MIN_COMPLETED_JOBS = 4;
 export const ARC_ACT_3_MIN_COMPLETED_JOBS = 9;
+/** Minimum *living* crew size before the Score's final-prep stage unlocks. Starter 2 + Decker = 3, so 4 requires at least one additional recruit who hasn't flatlined. */
+export const ARC_ACT_3_MIN_CREW_ALIVE = 4;
+/** Visited sites sharing the Score target's principal required for Act 3. Includes the target itself. */
+export const ARC_ACT_3_MIN_PRINCIPAL_SITES_VISITED = 3;
 const SYNTHETIC_SCORE_TARGET_DIFFICULTY = CONTRACT_DIFFICULTY.CRITICAL;
 
 export const CAMPAIGN_STATE = Object.freeze({
@@ -999,7 +1003,11 @@ export class Campaign {
       this.arc.scoreRevealed = true;
     }
 
+    // Invariant: once the Score is revealed, the Curator's Decker is on the
+    // crew. Holds for fresh act-2 transitions and for restores/constructs that
+    // land in a revealed state with a crew that's missing the operative.
     if (this.arc.scoreRevealed) {
+      this.#assignDecker();
       this.#ensureScoreTargetDesignated();
     }
 
@@ -1010,17 +1018,44 @@ export class Campaign {
 
   #qualifiesForAct2(): boolean {
     return (
-      repTierForRep(this.rep).id === REP_TIER.TRUSTED &&
+      repTierForRep(this.rep).id === REP_TIER.KNOWN &&
       this.completedJobs >= ARC_ACT_2_MIN_COMPLETED_JOBS
     );
   }
 
   #qualifiesForAct3(): boolean {
-    return (
-      this.arc.deckerRecruited &&
-      this.completedJobs >= ARC_ACT_3_MIN_COMPLETED_JOBS &&
-      this.siteRoster.some(site => site.scoreTarget && site.lastVisitedJob > 0)
-    );
+    if (this.completedJobs < ARC_ACT_3_MIN_COMPLETED_JOBS) return false;
+    const livingCrew = this.crew.filter(m => !m.flatlined).length;
+    if (livingCrew < ARC_ACT_3_MIN_CREW_ALIVE) return false;
+
+    const scoreTarget = this.siteRoster.find(site => site.scoreTarget);
+    if (!scoreTarget?.principal?.id) return false;
+
+    const principalId = scoreTarget.principal.id;
+    const visitedPrincipalSites = this.siteRoster.filter(
+      site => site.principal?.id === principalId && site.lastVisitedJob > 0
+    ).length;
+    return visitedPrincipalSites >= ARC_ACT_3_MIN_PRINCIPAL_SITES_VISITED;
+  }
+
+  /**
+   * Assign a Decker to the crew as part of the Act 2 narrative beat. The Curator
+   * "finds" a Decker for the player — no choice modal, just a named operative.
+   * Callsign is deduped against existing crew. Idempotent: skips if a Decker is
+   * already on the roster (e.g. from a restored save that already transitioned).
+   */
+  #assignDecker(): void {
+    // Guard on the actual roster, not the `deckerRecruited` flag: a restored
+    // save (or a constructed campaign) can carry the flag while the crew lacks
+    // the operative, and the Score reveal requires a real Decker present.
+    if (this.crew.some(member => member.archetype === 'Decker')) return;
+
+    const decker = buildCrewMember('decker', { x: 0, y: 0 }, this.rng, {
+      id: `crew-decker-${this.rng.intRange(0, 0xffff).toString(16)}`,
+      excludeCallsigns: this.allUsedCallsigns(),
+    });
+    this.crew.push(decker);
+    this.arc.deckerRecruited = true;
   }
 
   #ensureScoreTargetDesignated(): void {
@@ -1039,18 +1074,11 @@ export class Campaign {
       return;
     }
 
-    const target = this.#selectRememberedScoreTarget() ?? this.#synthesizeScoreTarget();
+    const target = this.#synthesizeScoreTarget();
     target.scoreTarget = true;
     target.tier = 'score';
   }
 
-  #selectRememberedScoreTarget(): LocationSite | null {
-    if (this.siteRoster.length === 0) return null;
-    return [...this.siteRoster].sort(
-      (a, b) => b.lastVisitedJob - a.lastVisitedJob || a.id.localeCompare(b.id)
-    )[0]!;
-  }
-
   #synthesizeScoreTarget(): LocationSite {
     const seed = this.rng.intRange(0, 0x7fffffff);
     const principal = this.rng.pick(
diff --git a/src/game/archetypes/Decker.ts b/src/game/archetypes/Decker.ts
index 738e314..188a374 100644
--- a/src/game/archetypes/Decker.ts
+++ b/src/game/archetypes/Decker.ts
@@ -11,16 +11,16 @@ import type { Rng } from '../../rng.js';
  * match the Cyberspace specialist fantasy (Phase 3).
  */
 export const CALLSIGNS = Object.freeze([
-  'Case',
+  'Phreak',
   'Jack',
   'Flatline',
   'Blitz',
   'Is0bel',
   'Bytesize',
-  'Crash',
+  'AcidBurn',
   'Ang3l',
   'Z0ne',
-  'Neo',
+  'Tr1nity',
 ]);
 
 /**
diff --git a/src/game/hub/arcSurface.ts b/src/game/hub/arcSurface.ts
new file mode 100644
index 0000000..bc7f4b8
--- /dev/null
+++ b/src/game/hub/arcSurface.ts
@@ -0,0 +1,99 @@
+import type { Contract } from './Curator.js';
+import type { Campaign } from '../Campaign.js';
+import type { CampaignArcStage, LocationSite } from '../../types.js';
+import type { Decker } from '../archetypes/Decker.js';
+import type { Crew } from '../Crew.js';
+
+type ArcSurfaceCampaign = Pick<Campaign, 'arc' | 'siteRoster' | 'crew'>;
+
+const ARC_STAGE_LABELS: Record<CampaignArcStage, string> = Object.freeze({
+  'act-1': 'STAGE 1: STREET LEVEL',
+  'act-2': 'STAGE 2: CASING',
+  'act-3': 'STAGE 3: FINAL PREP',
+  score: 'THE SCORE',
+});
+
+export function findScoreTargetSite(sites: readonly LocationSite[]): LocationSite | null {
+  const targets = sites.filter(site => site.scoreTarget);
+  if (targets.length > 1) {
+    throw new Error('arcSurface: multiple Score targets in site roster');
+  }
+  return targets[0] ?? null;
+}
+
+export function scoreTargetDisplayName(site: LocationSite): string {
+  const principal = cleanLabel(site.principal?.label);
+  const place = cleanLabel(site.site?.label);
+  if (principal && place) return `${principal} ${place}`;
+  if (principal) return principal;
+  if (place) return place;
+  return cleanSiteLabel(site.label);
+}
+
+export function formatArcStageLabel(stage: CampaignArcStage): string {
+  const label = ARC_STAGE_LABELS[stage];
+  if (!label) {
+    throw new Error(`arcSurface: unknown arc stage "${stage}"`);
+  }
+  return label;
+}
+
+export function formatHubArcStatus(campaign: ArcSurfaceCampaign): string {
+  const parts = [formatArcStageLabel(campaign.arc.arcStage)];
+  if (campaign.arc.scoreRevealed) {
+    const target = findScoreTargetSite(campaign.siteRoster);
+    if (!target) {
+      throw new Error('arcSurface: score revealed without a Score target site');
+    }
+    parts.push(`SCORE: ${scoreTargetDisplayName(target)}`);
+  }
+  return parts.join(' | ');
+}
+
+export function scoreRevealLines(campaign: ArcSurfaceCampaign): readonly string[] {
+  if (!campaign.arc.scoreRevealed) {
+    throw new Error('arcSurface: cannot build Score reveal copy before scoreRevealed');
+  }
+  const target = findScoreTargetSite(campaign.siteRoster);
+  if (!target) {
+    throw new Error('arcSurface: cannot build Score reveal copy without a Score target');
+  }
+  const targetName = scoreTargetDisplayName(target);
+  const deckerName = findDecker(campaign.crew).callsign;
+  return [
+    `CURATOR: We found it. ${targetName}. The Score has a door.`,
+    'CURATOR: Contracts touching that site are casing work now. Watch for SCORE SITE on the board.',
+    `CURATOR: You'll need a Decker to open the digital side. ${deckerName} just joined your crew.`,
+  ];
+}
+
+export function findDecker(crew: readonly Crew[]): Decker {
+  const decker = crew.find(crew => crew.archetype === 'Decker');
+  if (!decker) {
+    throw new Error('arcSurface: cannot build Score reveal copy without a Decker');
+  }
+  return decker as Decker;
+}
+
+export function isScoreSiteContract(
+  contract: Contract,
+  scoreTargetSiteId: string | null | undefined
+): boolean {
+  return !!scoreTargetSiteId && contract.context.locationSiteId === scoreTargetSiteId;
+}
+
+export function scoreTargetSiteId(campaign: ArcSurfaceCampaign): string | null {
+  return findScoreTargetSite(campaign.siteRoster)?.id ?? null;
+}
+
+function cleanLabel(label: string | undefined): string {
+  return label?.trim() ?? '';
+}
+
+function cleanSiteLabel(label: string): string {
+  return label
+    .replace(/^\/\//, '')
+    .replace(/\/\/$/, '')
+    .replace(/\s+-\s+Score target$/i, '')
+    .trim();
+}
diff --git a/src/game/hub/hubReveals.ts b/src/game/hub/hubReveals.ts
index 4013a78..05c25c5 100644
--- a/src/game/hub/hubReveals.ts
+++ b/src/game/hub/hubReveals.ts
@@ -8,6 +8,7 @@
 
 import { REP } from '../constants.js';
 import { totalSalvage } from '../salvage.js';
+import { scoreRevealLines } from './arcSurface.js';
 import type { Campaign } from '../Campaign.js';
 
 export type HubReveals = {
@@ -17,9 +18,11 @@ export type HubReveals = {
   /** Rep-gated recruitment channel on the terminal. */
   terminalRecruitmentExplained?: boolean;
   clinicIntroduced?: boolean;
+  /** Curator has presented the Phase 3 Score target reveal. */
+  scoreBriefingPresented?: boolean;
 };
 
-export type HubRevealId = 'finn' | 'terminal' | 'terminal-recruit' | 'clinic';
+export type HubRevealId = 'finn' | 'terminal' | 'terminal-recruit' | 'clinic' | 'score-reveal';
 
 export type HubRevealMessage = {
   id: HubRevealId;
@@ -34,7 +37,7 @@ type HubRevealDefinition = {
   flag: HubRevealFlag;
   title: string;
   qualifies: (campaign: Campaign) => boolean;
-  lines: readonly string[];
+  lines: readonly string[] | ((campaign: Campaign) => readonly string[]);
 };
 
 const HUB_REVEAL_DEFINITIONS: readonly HubRevealDefinition[] = [
@@ -50,6 +53,15 @@ const HUB_REVEAL_DEFINITIONS: readonly HubRevealDefinition[] = [
       'CURATOR: [Space] at the ‡ glyph to review operatives, gear, and salvage.',
     ],
   },
+  {
+    id: 'score-reveal',
+    flag: 'scoreBriefingPresented',
+    title: '── THE SCORE / THE DECKER ──',
+    qualifies(campaign) {
+      return campaign.arc.scoreRevealed;
+    },
+    lines: scoreRevealLines,
+  },
   {
     id: 'finn',
     flag: 'finnIntroduced',
@@ -106,6 +118,7 @@ export function normalizeHubReveals(raw: unknown, context = 'hubReveals'): HubRe
     'terminalExplained',
     'terminalRecruitmentExplained',
     'clinicIntroduced',
+    'scoreBriefingPresented',
   ] as const) {
     if (record[key] === undefined) continue;
     if (typeof record[key] !== 'boolean') {
@@ -148,6 +161,7 @@ export function snapshotHubReveals(reveals: HubReveals): HubReveals {
   if (reveals.finnIntroduced) out.finnIntroduced = true;
   if (reveals.terminalExplained) out.terminalExplained = true;
   if (reveals.clinicIntroduced) out.clinicIntroduced = true;
+  if (reveals.scoreBriefingPresented) out.scoreBriefingPresented = true;
   return out;
 }
 
@@ -176,7 +190,8 @@ export function applyFirstHubReveal(campaign: Campaign): HubRevealMessage | null
     if (campaign.hubReveals[def.flag]) continue;
     if (!def.qualifies(campaign)) continue;
     campaign.hubReveals[def.flag] = true;
-    return { id: def.id, title: def.title, lines: def.lines };
+    const lines = typeof def.lines === 'function' ? def.lines(campaign) : def.lines;
+    return { id: def.id, title: def.title, lines };
   }
   return null;
 }
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index cb0b4dc..b6350e1 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -791,6 +791,7 @@ export type HubRevealsSnapshot = {
   terminalExplained?: boolean;
   terminalRecruitmentExplained?: boolean;
   clinicIntroduced?: boolean;
+  scoreBriefingPresented?: boolean;
 };
 
 /**
diff --git a/src/types.ts b/src/types.ts
index 8695a63..e70c2c5 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -206,8 +206,7 @@ export type LocationToken = { id: string; label: string; groups: string[] };
  * (objective/asset/action) is rolled fresh. `label` is the name from the most
  * recent generation.
  *
- * `tier` / `scoreTarget` reserve one slot for Phase 3's "Score target" site;
- * `scoreTarget` is always false until Phase 3.
+ * `tier` / `scoreTarget` reserve one slot for Phase 3's "Score target" site.
  */
 export type LocationSite = {
   /** Stable, seed-derived id — the roster key. */
@@ -222,7 +221,7 @@ export type LocationSite = {
   label: string;
   /** Roster tier — `'score'` is reserved for Phase 3 and never evicted. */
   tier: 'score' | 'roster';
-  /** Phase 3 hook — always false until Phase 3. */
+  /** Phase 3 hook — true for the single campaign Score target. */
   scoreTarget: boolean;
   /** Accumulated terrain mutations replayed on revisit. */
   mutationDeltas: TileDelta[];
diff --git a/sw-core.js b/sw-core.js
index 777c08d..a8dbe81 100644
--- a/sw-core.js
+++ b/sw-core.js
@@ -89,6 +89,7 @@ const CacheConfig = {
       '/src/game/Grid.js',
       '/src/game/Hostile.js',
       '/src/game/hub/Curator.js',
+      '/src/game/hub/arcSurface.js',
       '/src/game/hub/Clinic.js',
       '/src/game/hub/Finn.js',
       '/src/game/hub/hubReveals.js',
diff --git a/tests/unit/game/Campaign.test.ts b/tests/unit/game/Campaign.test.ts
index 2547a9e..d92cf79 100644
--- a/tests/unit/game/Campaign.test.ts
+++ b/tests/unit/game/Campaign.test.ts
@@ -650,24 +650,30 @@ test('restoreCampaign rejects corrupt Phase 3 arc snapshots', () => {
 });
 
 test('P3.M1.2: Act 1 does not advance until Rep and completed job gates both qualify', () => {
-  const lowRep = new Campaign({ seed: 42, rep: 79, completedJobs: 4 });
+  const lowRep = new Campaign({ seed: 42, rep: 49, completedJobs: 4 });
   assert.equal(lowRep.arcStage, 'act-1');
   assert.equal(lowRep.arc.scoreRevealed, false);
 
-  const lowJobs = new Campaign({ seed: 43, rep: 80, completedJobs: 3 });
+  const lowJobs = new Campaign({ seed: 43, rep: 60, completedJobs: 3 });
   assert.equal(lowJobs.arcStage, 'act-1');
   assert.equal(lowJobs.arc.scoreRevealed, false);
 });
 
-test('P3.M1.2: Act 1 advances to Act 2 at TRUSTED Rep plus four completed jobs', () => {
-  const campaign = new Campaign({ seed: 42, rep: 80, completedJobs: 4 });
+test('P3.M1.2: Act 1 advances to Act 2 at KNOWN Rep plus four completed jobs and assigns Decker', () => {
+  const campaign = new Campaign({ seed: 42, rep: 60, completedJobs: 4 });
 
   assert.equal(campaign.arcStage, 'act-2');
   assert.equal(campaign.arc.scoreRevealed, true);
+  assert.equal(campaign.arc.deckerRecruited, true);
+
+  const decker = campaign.crew.find(m => m.archetype === 'Decker');
+  assert.ok(decker, 'Decker should join crew at Act 2 entry');
+  assert.ok(decker!.callsign, 'Decker should have a unique callsign');
+  assert.match(decker!.id, /^crew-decker-/);
 });
 
 test('P3.M1.2: successful extraction advances Act 2 when the final gate is crossed', () => {
-  const campaign = new Campaign({ seed: 42, rep: 79, completedJobs: 3 });
+  const campaign = new Campaign({ seed: 42, rep: 49, completedJobs: 3 });
   const member = campaign.crew[0];
   const run = campaign.deployCrewMember(
     member.id,
@@ -678,9 +684,14 @@ test('P3.M1.2: successful extraction advances Act 2 when the final gate is cross
   campaign.onJobEnd({ outcome: OUTCOME.EXIT, completed: true });
 
   assert.equal(campaign.completedJobs, 4);
-  assert.equal(campaign.rep, 80);
+  assert.equal(campaign.rep, 50);
   assert.equal(campaign.arcStage, 'act-2');
   assert.equal(campaign.arc.scoreRevealed, true);
+  assert.equal(campaign.arc.deckerRecruited, true);
+  assert.ok(
+    campaign.crew.some(m => m.archetype === 'Decker'),
+    'Decker should join crew when Act 2 gate is crossed'
+  );
 });
 
 test('P3.M1.2: abort extraction does not count as a completed arc job', () => {
@@ -696,80 +707,147 @@ test('P3.M1.2: abort extraction does not count as a completed arc job', () => {
   assert.equal(campaign.arc.scoreRevealed, false);
 });
 
-test('P3.M1.2: Act 2 waits for Decker recruitment, Score-site visit, and nine jobs', () => {
-  const decker = buildCrewMember('decker', { x: 0, y: 0 }, new Rng(101), {
-    id: 'crew-decker',
+test('P3.M1.2: Act 2 gates — each Act 3 condition checked independently', () => {
+  // Act 3 requires: completedJobs >= 9, 4 living crew, and 3 visited same-principal sites.
+  // Default test crew: buildCrew() trio + auto-Decker = 4 living.
+  const scorePrincipal = { id: 'matsuda', label: 'Matsuda', groups: ['corp'] };
+
+  // Gate: not enough jobs (crew and sites satisfied by default)
+  const tooFewJobs = new Campaign({
+    seed: 44,
+    rep: 60,
+    completedJobs: 8,
+    siteRoster: [
+      validSite({
+        id: 'score',
+        seed: '100',
+        tier: 'score',
+        scoreTarget: true,
+        lastVisitedJob: 5,
+        principal: scorePrincipal,
+      }),
+      validSite({ id: 'case-1', seed: '101', lastVisitedJob: 6, principal: scorePrincipal }),
+      validSite({ id: 'case-2', seed: '102', lastVisitedJob: 7, principal: scorePrincipal }),
+    ],
   });
-  const missingDecker = new Campaign({
-    seed: 42,
-    rep: 80,
+  assert.equal(tooFewJobs.arcStage, 'act-2', 'blocks on job count');
+
+  // Gate: not enough living crew (need 4 non-flatlined).
+  // Start in Act 1 (low rep), flatline a member, then cross the Act 2 threshold
+  // so the Act 3 check sees only 3 living crew.
+  const attrition = new Campaign({
+    seed: 45,
+    rep: 20,
     completedJobs: 9,
     siteRoster: [
       validSite({
         id: 'score',
-        seed: '12345',
+        seed: '100',
         tier: 'score',
         scoreTarget: true,
         lastVisitedJob: 5,
+        principal: scorePrincipal,
       }),
+      validSite({ id: 'case-1', seed: '101', lastVisitedJob: 6, principal: scorePrincipal }),
+      validSite({ id: 'case-2', seed: '102', lastVisitedJob: 7, principal: scorePrincipal }),
     ],
   });
-  assert.equal(missingDecker.arcStage, 'act-2');
-
-  const missingTargetVisit = new Campaign({
-    seed: 43,
-    rep: 80,
+  assert.equal(attrition.arcStage, 'act-1', 'starts in Act 1 with low rep');
+  attrition.crew[0].flatlined = true;
+  attrition.rep = 60;
+  attrition.enterHub();
+  assert.equal(attrition.crew.length, 4, 'buildCrew trio + auto-Decker');
+  assert.equal(attrition.crew.filter(m => !m.flatlined).length, 3, 'only 3 living');
+  assert.equal(attrition.arcStage, 'act-2', 'blocks on living crew count');
+
+  // Gate: not enough same-principal visited sites (2 of 3 required)
+  const tooCasual = new Campaign({
+    seed: 46,
+    rep: 60,
     completedJobs: 9,
-    crew: [decker],
-  });
-  assert.equal(missingTargetVisit.arcStage, 'act-2');
-
-  const tooFewJobs = new Campaign({
-    seed: 44,
-    rep: 80,
-    completedJobs: 8,
-    crew: [decker],
     siteRoster: [
       validSite({
         id: 'score',
-        seed: '12345',
+        seed: '100',
         tier: 'score',
         scoreTarget: true,
         lastVisitedJob: 5,
+        principal: scorePrincipal,
       }),
+      validSite({ id: 'case-1', seed: '101', lastVisitedJob: 6, principal: scorePrincipal }),
+      // Only 2 visited sites for this principal — need 3
     ],
   });
-  assert.equal(tooFewJobs.arcStage, 'act-2');
-});
+  assert.equal(tooCasual.arcStage, 'act-2', 'blocks on principal site visits');
 
-test('P3.M1.2: Act 2 advances to Act 3 once Decker, Score-site visit, and nine jobs qualify', () => {
-  const decker = buildCrewMember('decker', { x: 0, y: 0 }, new Rng(102), {
-    id: 'crew-decker',
+  // Gate: score target never visited (synthesized, lastVisitedJob: 0)
+  const noTargetVisit = new Campaign({
+    seed: 47,
+    rep: 60,
+    completedJobs: 9,
   });
+  const scoreTarget = noTargetVisit.siteRoster.find(s => s.scoreTarget);
+  assert.ok(scoreTarget);
+  assert.equal(scoreTarget!.lastVisitedJob, 0, 'synthesized target starts unvisited');
+  assert.equal(noTargetVisit.arcStage, 'act-2', 'blocks when score target unvisited');
+});
+
+test('P3.M1.2: Act 2 advances to Act 3 with 4 living crew and 3 visited same-principal sites', () => {
+  const scorePrincipal = { id: 'matsuda', label: 'Matsuda', groups: ['corp'] };
   const campaign = new Campaign({
     seed: 42,
-    rep: 80,
+    rep: 60,
     completedJobs: 9,
-    crew: [decker],
     siteRoster: [
       validSite({
         id: 'score',
-        seed: '12345',
+        seed: '100',
         tier: 'score',
         scoreTarget: true,
         lastVisitedJob: 5,
+        principal: scorePrincipal,
       }),
+      validSite({ id: 'case-1', seed: '101', lastVisitedJob: 6, principal: scorePrincipal }),
+      validSite({ id: 'case-2', seed: '102', lastVisitedJob: 7, principal: scorePrincipal }),
     ],
   });
 
-  assert.equal(campaign.arc.deckerRecruited, true);
+  const living = campaign.crew.filter(m => !m.flatlined).length;
+  assert.ok(living >= 4, `need 4 living crew, have ${living}`);
   assert.equal(campaign.arcStage, 'act-3');
 });
 
-test('P3.M1.3: Act 2 entry promotes one remembered site as the Score target', () => {
+test('P3.M2: Decker assignment is idempotent — restored save with existing Decker does not duplicate', () => {
+  const decker = buildCrewMember('decker', { x: 0, y: 0 }, new Rng(102), {
+    id: 'crew-decker',
+  });
+  const campaign = new Campaign({
+    seed: 42,
+    rep: 60,
+    completedJobs: 4,
+    crew: [decker],
+  });
+
+  assert.equal(campaign.arcStage, 'act-2');
+  const deckers = campaign.crew.filter(m => m.archetype === 'Decker');
+  assert.equal(deckers.length, 1, 'should not duplicate Decker when one already exists');
+});
+
+test('P3.M2: Decker callsign does not collide with existing crew', () => {
+  const campaign = new Campaign({ seed: 42, rep: 60, completedJobs: 4 });
+  const decker = campaign.crew.find(m => m.archetype === 'Decker');
+  assert.ok(decker);
+  const otherCallsigns = campaign.crew.filter(m => m.archetype !== 'Decker').map(m => m.callsign);
+  assert.ok(
+    !otherCallsigns.includes(decker!.callsign!),
+    `Decker callsign "${decker!.callsign}" should not collide with existing crew`
+  );
+});
+
+test('P3.M1.3: Act 2 entry always synthesizes a new CRITICAL-tier Score target', () => {
   const campaign = new Campaign({
     seed: 42,
-    rep: 80,
+    rep: 60,
     completedJobs: 4,
     siteRoster: [
       validSite({
@@ -786,35 +864,22 @@ test('P3.M1.3: Act 2 entry promotes one remembered site as the Score target', ()
     ],
   });
 
-  const target = campaign.findRosterSite('remembered');
-  assert.ok(target);
-  assert.equal(target!.scoreTarget, true);
+  const remembered = campaign.findRosterSite('remembered');
+  assert.ok(remembered);
+  assert.equal(remembered!.scoreTarget, false, 'existing roster site is not promoted');
+  assert.notEqual(remembered!.tier, 'score');
+
+  const target = campaign.siteRoster.find(site => site.scoreTarget);
+  assert.ok(target, 'synthesized Score target exists');
+  assert.match(target!.id, /^score-/);
   assert.equal(target!.tier, 'score');
-  assert.equal(target!.mapWidth, 30);
-  assert.equal(target!.mapHeight, 18);
-  assert.deepEqual(target!.seenKeys, ['1,1']);
-  assert.equal(target!.mutationDeltas.length, 1);
+  assert.ok(target!.mapWidth >= 28, 'Score target uses CRITICAL-tier dimensions');
+  assert.ok(target!.mapHeight >= 18);
   assert.equal(campaign.siteRoster.filter(site => site.scoreTarget).length, 1);
 });
 
-test('P3.M1.3: remembered Score target selection prefers the most recently visited site', () => {
-  const campaign = new Campaign({
-    seed: 42,
-    rep: 80,
-    completedJobs: 4,
-    siteRoster: [
-      validSite({ id: 'older', seed: '101', lastVisitedJob: 1 }),
-      validSite({ id: 'newest', seed: '202', lastVisitedJob: 7 }),
-      validSite({ id: 'middle', seed: '303', lastVisitedJob: 3 }),
-    ],
-  });
-
-  assert.equal(campaign.siteRoster.find(site => site.scoreTarget)?.id, 'newest');
-  assert.equal(campaign.findRosterSite('newest')?.tier, 'score');
-});
-
-test('P3.M1.3: Act 2 entry synthesizes a Score target when the roster is empty', () => {
-  const campaign = new Campaign({ seed: 42, rep: 80, completedJobs: 4 });
+test('P3.M1.3: Act 2 entry synthesizes a Score target even when roster is empty', () => {
+  const campaign = new Campaign({ seed: 42, rep: 60, completedJobs: 4 });
 
   assert.equal(campaign.arcStage, 'act-2');
   assert.equal(campaign.arc.scoreRevealed, true);
@@ -831,7 +896,7 @@ test('P3.M1.3: Act 2 entry synthesizes a Score target when the roster is empty',
 });
 
 test('P3.M1.3: designated Score target survives roster eviction at cap', () => {
-  const campaign = new Campaign({ seed: 42, rep: 80, completedJobs: 4 });
+  const campaign = new Campaign({ seed: 42, rep: 60, completedJobs: 4 });
   const targetId = campaign.siteRoster.find(site => site.scoreTarget)!.id;
 
   for (let i = 0; i < SITE_ROSTER_CAP; i++) {
@@ -848,7 +913,7 @@ test('P3.M1.3: multiple persisted Score targets crash instead of being normalize
     () =>
       new Campaign({
         seed: 42,
-        rep: 80,
+        rep: 60,
         completedJobs: 4,
         siteRoster: [
           validSite({ id: 'score-a', seed: '111', tier: 'score', scoreTarget: true }),
diff --git a/tests/unit/game/hub/arcSurface.test.ts b/tests/unit/game/hub/arcSurface.test.ts
new file mode 100644
index 0000000..670ba29
--- /dev/null
+++ b/tests/unit/game/hub/arcSurface.test.ts
@@ -0,0 +1,134 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { CONTRACT_DIFFICULTY } from '../../../../src/game/constants.js';
+import { buildContractRecipeFixture } from '../../../../src/game/hub/Curator.js';
+import {
+  findDecker,
+  findScoreTargetSite,
+  formatArcStageLabel,
+  formatHubArcStatus,
+  isScoreSiteContract,
+  scoreRevealLines,
+  scoreTargetDisplayName,
+  scoreTargetSiteId,
+} from '../../../../src/game/hub/arcSurface.js';
+import { Decker } from '../../../../src/game/archetypes/Decker.js';
+import { Merc } from '../../../../src/game/archetypes/Merc.js';
+import type { CampaignArc } from '../../../../src/game/Campaign.js';
+import type { LocationSite, LocationToken } from '../../../../src/types.js';
+
+const principal = token('matsuda', 'Matsuda', ['corp']);
+const site = token('server-farm', 'server farm', ['corp', 'data']);
+
+function token(id: string, label: string, groups: string[]): LocationToken {
+  return { id, label, groups };
+}
+
+function arc(overrides: Partial<CampaignArc> = {}): CampaignArc {
+  return {
+    arcStage: 'act-1',
+    deckerRecruited: false,
+    scoreRevealed: false,
+    clockStarted: false,
+    scoreAttempted: false,
+    scoreCompleted: false,
+    ...overrides,
+  };
+}
+
+function scoreSite(overrides: Partial<LocationSite> = {}): LocationSite {
+  return {
+    id: 'score-site',
+    seed: '123',
+    mapWidth: 32,
+    mapHeight: 20,
+    label: '// Matsuda server farm - Score target',
+    tier: 'score',
+    scoreTarget: true,
+    mutationDeltas: [],
+    seenKeys: [],
+    lastVisitedJob: 4,
+    principal,
+    site,
+    ...overrides,
+  };
+}
+
+test('formatHubArcStatus shows act label and Score target once revealed', () => {
+  const campaign = {
+    arc: arc({ arcStage: 'act-2', scoreRevealed: true }),
+    siteRoster: [scoreSite()],
+  };
+  assert.equal(formatHubArcStatus(campaign), 'STAGE 2: CASING | SCORE: Matsuda server farm');
+});
+
+test('formatHubArcStatus throws when revealed state has no Score target', () => {
+  assert.throws(
+    () =>
+      formatHubArcStatus({
+        arc: arc({ arcStage: 'act-2', scoreRevealed: true }),
+        siteRoster: [],
+      }),
+    /score revealed without a Score target/i
+  );
+});
+
+test('Score target helpers reject multiple targets instead of guessing', () => {
+  const sites = [scoreSite({ id: 'a' }), scoreSite({ id: 'b' })];
+  assert.throws(() => findScoreTargetSite(sites), /multiple Score targets/i);
+  assert.throws(() => scoreTargetSiteId({ arc: arc(), siteRoster: sites }), /multiple Score/i);
+});
+
+test('score reveal copy names the target and points at job-board badges', () => {
+  const lines = scoreRevealLines({
+    arc: arc({ arcStage: 'act-2', scoreRevealed: true }),
+    siteRoster: [scoreSite()],
+    crew: [new Decker({ id: 'decker', x: 0, y: 0, callsign: 'Case' })],
+  });
+  assert.match(lines.join('\n'), /Matsuda server farm/);
+  assert.match(lines.join('\n'), /SCORE SITE/);
+  assert.match(lines.join('\n'), /Case/);
+});
+
+test('scoreTargetDisplayName falls back to sanitized roster label', () => {
+  assert.equal(
+    scoreTargetDisplayName(scoreSite({ principal: undefined, site: undefined })),
+    'Matsuda server farm'
+  );
+});
+
+test('formatArcStageLabel has stable player-facing labels', () => {
+  assert.equal(formatArcStageLabel('act-1'), 'STAGE 1: STREET LEVEL');
+  assert.equal(formatArcStageLabel('act-3'), 'STAGE 3: FINAL PREP');
+  assert.equal(formatArcStageLabel('score'), 'THE SCORE');
+});
+
+test('isScoreSiteContract matches contract locationSiteId to the Score target id', () => {
+  const contract = buildContractRecipeFixture({
+    recipeId: 'terminal-slice',
+    principalId: 'matsuda',
+    siteId: 'server-farm',
+    assetId: 'identity-spool',
+    actionId: 'slice',
+    difficulty: CONTRACT_DIFFICULTY.STANDARD,
+    seed: 11,
+  });
+  contract.context.locationSiteId = 'score-site';
+
+  assert.equal(isScoreSiteContract(contract, 'score-site'), true);
+  assert.equal(isScoreSiteContract(contract, 'other-site'), false);
+  assert.equal(isScoreSiteContract(contract, null), false);
+});
+
+test('findDecker throws when no Decker is present', () => {
+  const merc = new Merc({ id: 'merc', x: 0, y: 0, callsign: 'Glitch' });
+  assert.throws(() => findDecker([merc]), /without a Decker/i);
+  assert.throws(() => findDecker([]), /without a Decker/i);
+});
+
+test('findDecker returns the Decker when one is present', () => {
+  const decker = new Decker({ id: 'decker', x: 0, y: 0, callsign: 'Case' });
+  const crew = [new Merc({ id: 'merc', x: 1, y: 1, callsign: 'Glitch' }), decker];
+  assert.equal(findDecker(crew), decker);
+});
diff --git a/tests/unit/game/hub/hubReveals.test.ts b/tests/unit/game/hub/hubReveals.test.ts
index 00a64d4..9aca71f 100644
--- a/tests/unit/game/hub/hubReveals.test.ts
+++ b/tests/unit/game/hub/hubReveals.test.ts
@@ -125,6 +125,34 @@ test('terminal recruitment reveal when Rep meets threshold', () => {
   assert.ok(campaign.hubReveals.terminalRecruitmentExplained);
 });
 
+test('Score reveal presents the target and assigns a Decker when Act 2 opens', () => {
+  const campaign = hubCampaign({
+    rep: 60,
+    completedJobs: 4,
+    hubReveals: {
+      terminalExplained: true,
+      finnIntroduced: true,
+      clinicIntroduced: true,
+      terminalRecruitmentExplained: true,
+    },
+  });
+  assert.equal(campaign.arc.arcStage, 'act-2');
+  assert.equal(campaign.lastHubReveal?.id, 'score-reveal');
+  assert.equal(campaign.hubReveals.scoreBriefingPresented, true);
+  const revealText = campaign.lastHubReveal?.lines.join('\n') ?? '';
+  assert.match(revealText, /SCORE SITE/);
+  assert.match(revealText, /Decker/);
+
+  // Decker was assigned as part of the same transition beat
+  assert.equal(campaign.arc.deckerRecruited, true);
+  const decker = campaign.crew.find(m => m.archetype === 'Decker');
+  assert.ok(decker, 'Decker should be on the crew after Act 2 entry');
+  assert.ok(decker!.callsign, 'Decker should have a callsign');
+
+  campaign.enterHub();
+  assert.equal(campaign.lastHubReveal, null);
+});
+
 test('terminal recruitment reveal when pendingRecruitReward even below Rep', () => {
   const campaign = hubCampaign({
     rep: REP.START,
@@ -180,6 +208,7 @@ test('hubReveals and completedJobs round-trip in campaign snapshot', () => {
       terminalExplained: true,
       finnIntroduced: true,
       clinicIntroduced: true,
+      scoreBriefingPresented: true,
     },
   });
   const snap = snapshotCampaign(campaign);

From e31008c62352403708a403c20f7cb973522715f1 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Tue, 9 Jun 2026 12:13:32 -0700
Subject: [PATCH 07/55] plan status fix

---
 docs/phase-3-plan.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 5cfa057..8f651a0 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -178,7 +178,7 @@ Neural degradation is deferred until Cyberspace is fun enough to deserve a jack-
 
 - ✅ Decker archetype playable in Meatspace: move, attack, interact — comparable to other archetypes (`Decker` extends `Crew`, `baseHitChance` 0.7, `@` glyph).
 - ✅ Drone Override Hack: golden-path test — target drone, override succeeds, drone attacks corp allies for N turns, reverts or is destroyed (`droneOverride.ts`, `Decker.test.ts`). Failed roll burns AP and trips the alarm.
-- 🔲 Recruitment: same beat as Score reveal (Act 1 → Act 2 transition); Curator assigns a named Decker, no choice modal. Not available in Act 1; golden-path test for recruitment flow. Decker is registered but excluded from `ARCHETYPE_IDS` and `RECRUIT_ARCHETYPE_POOL` so random recruitment can't roll one early.
+- ✅ Recruitment: same beat as Score reveal (Act 1 → Act 2 transition); Curator assigns a named Decker, no choice modal. Not available in Act 1; golden-path test for recruitment flow. Decker is registered but excluded from `ARCHETYPE_IDS` and `RECRUIT_ARCHETYPE_POOL` so random recruitment can't roll one early.
 - ✅ Snapshot: Decker state persists (campaign + run round-trip); live drone-override state round-trips through the patrol snapshot. Cyberspace attributes deferred to P3.M3.
 - ✅ Key help: Decker glyph (`@`) and OVERRIDE ability description via shared `ARCHETYPES[id].perkLabel`.
 

From 3aa139e91a9a92ad80c47ef5589cdca4b7fc2cc9 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Tue, 9 Jun 2026 14:31:46 -0700
Subject: [PATCH 08/55] fix hub reveal gating on save reload

---
 index.ts                               | 29 ++++++++++++--
 src/game/Campaign.ts                   |  9 ++---
 src/game/hub/arcSurface.ts             |  4 +-
 src/game/hub/hubReveals.ts             | 44 +++++++++++++++++++--
 src/game/items.ts                      | 18 ++++-----
 tests/unit/game/Campaign.test.ts       | 12 ++++++
 tests/unit/game/hub/hubReveals.test.ts | 55 +++++++++++++++++++++++++-
 7 files changed, 147 insertions(+), 24 deletions(-)

diff --git a/index.ts b/index.ts
index b51aab6..5363b27 100644
--- a/index.ts
+++ b/index.ts
@@ -75,7 +75,12 @@ import { ITEM_ID, getItemById } from '/src/game/items.js';
 import type { CampaignSnapshot } from '/src/game/persistence.js';
 import type { Contract } from '/src/game/hub/Curator.js';
 import { formatHubArcStatus, scoreTargetSiteId } from '/src/game/hub/arcSurface.js';
-import { isTerminalAccessible } from '/src/game/hub/hubReveals.js';
+import {
+  commitHubReveal,
+  hubRevealCommitsOnDismiss,
+  isTerminalAccessible,
+  type HubRevealId,
+} from '/src/game/hub/hubReveals.js';
 import type { Crew } from '/src/game/Crew.js';
 import { resolveEntityLabel, type Entity } from '/src/game/Entity.js';
 import type { RunResult, RunTelemetry, Outcome } from '/src/game/Run.js';
@@ -254,6 +259,8 @@ let systemStartEl: SystemStartElement;
 let curatorBriefingEl: CuratorBriefingElement;
 /** Status line to flash after the player dismisses a Hub reveal briefing. */
 let hubRevealFollowUpFlash: string | null = null;
+/** Score reveal (and future deferred reveals) commit their flag on dismiss. */
+let pendingHubRevealId: HubRevealId | null = null;
 let initialRecruitEl: InitialRecruitElement;
 let confirmationModalEl: ConfirmationModalElement;
 let touchPadEl: TouchPadElement;
@@ -608,6 +615,7 @@ function abortShellForFault(): void {
   invalidateCombatPumps();
   pendingJobResult = null;
   hubRevealFollowUpFlash = null;
+  pendingHubRevealId = null;
   corpToneActivityBody = null;
   clearBreachBlastOverlay(false);
   resetInputModes();
@@ -681,6 +689,7 @@ function presentHubRevealIfAny(followUpFlash: string): boolean {
   const reveal = campaign.lastHubReveal;
   campaign.lastHubReveal = null;
   hubRevealFollowUpFlash = followUpFlash;
+  pendingHubRevealId = hubRevealCommitsOnDismiss(reveal.id) ? reveal.id : null;
   curatorBriefingEl.setBriefing({ title: reveal.title, lines: reveal.lines });
   curatorBriefingEl.show();
   return true;
@@ -688,6 +697,11 @@ function presentHubRevealIfAny(followUpFlash: string): boolean {
 
 function onCuratorBriefingDismiss(): void {
   curatorBriefingEl.hide();
+  if (pendingHubRevealId && campaign) {
+    commitHubReveal(campaign, pendingHubRevealId);
+    pendingHubRevealId = null;
+    handlePersist();
+  }
   if (hubRevealFollowUpFlash) {
     flash(hubRevealFollowUpFlash);
     hubRevealFollowUpFlash = null;
@@ -1195,17 +1209,26 @@ function resumeCampaign(record: CampaignSnapshot | unknown) {
       briefingEl.setCrew(campaign.crew);
     }
     resumePendingCombatSliceIfNeeded();
+    const resumeFlashMessage = `RESUMED — crew ${campaign.crew.filter(member => !member.flatlined).length} active.`;
     if (campaign.state === CAMPAIGN_STATE.ENDED) {
       pendingJobResult = null;
       crashEl.setTelemetry(telemetryForEndedCampaign(campaign));
       flash('CAMPAIGN ENDED — no surviving crew in this save.');
+      renderShell();
     } else if (campaign.activeRun?.state === RUN_STATE.RESULT) {
       pushPendingJobResultOverlay({ ...campaign.activeRun.telemetry });
       flash('RESUMED — mission debrief.');
+      renderShell();
+    } else if (campaign.state === CAMPAIGN_STATE.HUB && campaign.curator) {
+      renderShell();
+      if (!presentHubRevealIfAny(resumeFlashMessage)) {
+        flash(resumeFlashMessage);
+      }
+      currentJobOptions = campaign.curator.generateContracts(campaign.rng, campaign);
     } else {
-      flash(`RESUMED — crew ${campaign.crew.filter(member => !member.flatlined).length} active.`);
+      flash(resumeFlashMessage);
+      renderShell();
     }
-    renderShell();
   } catch (err) {
     console.error('[shell] failed to restore saved campaign', err);
     dataStore.deleteCampaign();
diff --git a/src/game/Campaign.ts b/src/game/Campaign.ts
index 32a413c..7cb2f07 100644
--- a/src/game/Campaign.ts
+++ b/src/game/Campaign.ts
@@ -7,11 +7,9 @@ import {
   CONTRACT_DIFFICULTY,
   FACTION,
   REP,
-  REP_TIER,
   RECRUIT,
   SALVAGE_SELL_RATE,
   CLINIC_COST_PER_HP,
-  repTierForRep,
 } from './constants.js';
 import {
   SALVAGE_TYPES,
@@ -59,6 +57,8 @@ import type { RunResult, Outcome } from './Run.js';
 
 /** Max remembered combat locations (P2.5.M7.2). One slot is reserved for Phase 3's score target. */
 export const SITE_ROSTER_CAP = 6;
+/** Minimum Rep to leave Act 1 — matches KNOWN tier floor (50). Higher tiers qualify too. */
+export const ARC_ACT_2_MIN_REP = 50;
 export const ARC_ACT_2_MIN_COMPLETED_JOBS = 4;
 export const ARC_ACT_3_MIN_COMPLETED_JOBS = 9;
 /** Minimum *living* crew size before the Score's final-prep stage unlocks. Starter 2 + Decker = 3, so 4 requires at least one additional recruit who hasn't flatlined. */
@@ -1017,10 +1017,7 @@ export class Campaign {
   }
 
   #qualifiesForAct2(): boolean {
-    return (
-      repTierForRep(this.rep).id === REP_TIER.KNOWN &&
-      this.completedJobs >= ARC_ACT_2_MIN_COMPLETED_JOBS
-    );
+    return this.rep >= ARC_ACT_2_MIN_REP && this.completedJobs >= ARC_ACT_2_MIN_COMPLETED_JOBS;
   }
 
   #qualifiesForAct3(): boolean {
diff --git a/src/game/hub/arcSurface.ts b/src/game/hub/arcSurface.ts
index bc7f4b8..54b9c84 100644
--- a/src/game/hub/arcSurface.ts
+++ b/src/game/hub/arcSurface.ts
@@ -61,9 +61,9 @@ export function scoreRevealLines(campaign: ArcSurfaceCampaign): readonly string[
   const targetName = scoreTargetDisplayName(target);
   const deckerName = findDecker(campaign.crew).callsign;
   return [
-    `CURATOR: We found it. ${targetName}. The Score has a door.`,
+    `CURATOR: We found it: ${targetName}. The Score has a door.`,
     'CURATOR: Contracts touching that site are casing work now. Watch for SCORE SITE on the board.',
-    `CURATOR: You'll need a Decker to open the digital side. ${deckerName} just joined your crew.`,
+    `CURATOR: You'll need a Decker to crack the ICE; I've got ${deckerName} for you.`,
   ];
 }
 
diff --git a/src/game/hub/hubReveals.ts b/src/game/hub/hubReveals.ts
index 05c25c5..9164840 100644
--- a/src/game/hub/hubReveals.ts
+++ b/src/game/hub/hubReveals.ts
@@ -40,6 +40,9 @@ type HubRevealDefinition = {
   lines: readonly string[] | ((campaign: Campaign) => readonly string[]);
 };
 
+/** Reveal flags committed when the shell dismisses the Curator briefing, not when queued. */
+const HUB_REVEAL_DEFER_FLAG_COMMIT = new Set<HubRevealId>(['score-reveal']);
+
 const HUB_REVEAL_DEFINITIONS: readonly HubRevealDefinition[] = [
   {
     id: 'terminal',
@@ -181,17 +184,52 @@ export function isTerminalRecruitmentUnlocked(reveals: HubReveals): boolean {
   return !!reveals.terminalRecruitmentExplained;
 }
 
+function buildHubRevealMessage(
+  def: HubRevealDefinition,
+  campaign: Campaign,
+  commitFlag: boolean
+): HubRevealMessage {
+  if (commitFlag) {
+    campaign.hubReveals[def.flag] = true;
+  }
+  const lines = typeof def.lines === 'function' ? def.lines(campaign) : def.lines;
+  return { id: def.id, title: def.title, lines };
+}
+
+export function hubRevealCommitsOnDismiss(id: HubRevealId): boolean {
+  return HUB_REVEAL_DEFER_FLAG_COMMIT.has(id);
+}
+
+/** Persist a Hub reveal flag after the player dismisses its Curator briefing. */
+export function commitHubReveal(campaign: Campaign, id: HubRevealId): void {
+  const def = HUB_REVEAL_DEFINITIONS.find(entry => entry.id === id);
+  if (!def) {
+    throw new Error(`hubReveals: unknown reveal id "${id}"`);
+  }
+  campaign.hubReveals[def.flag] = true;
+}
+
 /**
  * Evaluate reveal triggers in definition order. Sets the first qualifying
  * unseen flag on `campaign.hubReveals` and returns its message. Does not persist.
+ * Score reveal is checked first so Act 2 openings are not crowded out by lower
+ * priority intros on the same visit. Score briefing flags commit on dismiss.
  */
 export function applyFirstHubReveal(campaign: Campaign): HubRevealMessage | null {
+  const scoreReveal = HUB_REVEAL_DEFINITIONS.find(def => def.id === 'score-reveal');
+  if (scoreReveal && !campaign.hubReveals[scoreReveal.flag] && scoreReveal.qualifies(campaign)) {
+    return buildHubRevealMessage(
+      scoreReveal,
+      campaign,
+      !HUB_REVEAL_DEFER_FLAG_COMMIT.has(scoreReveal.id)
+    );
+  }
+
   for (const def of HUB_REVEAL_DEFINITIONS) {
+    if (def.id === 'score-reveal') continue;
     if (campaign.hubReveals[def.flag]) continue;
     if (!def.qualifies(campaign)) continue;
-    campaign.hubReveals[def.flag] = true;
-    const lines = typeof def.lines === 'function' ? def.lines(campaign) : def.lines;
-    return { id: def.id, title: def.title, lines };
+    return buildHubRevealMessage(def, campaign, true);
   }
   return null;
 }
diff --git a/src/game/items.ts b/src/game/items.ts
index f4bfa8d..7cfe3b1 100644
--- a/src/game/items.ts
+++ b/src/game/items.ts
@@ -132,6 +132,15 @@ const CATALOG: readonly Item[] = Object.freeze([
     needsAim: true,
     minRepTier: REP_TIER.UNKNOWN,
   }),
+  Object.freeze({
+    id: ITEM_ID.ARMOUR_PLATING,
+    label: 'Armour Plating',
+    scope: ITEM_SCOPE.CAMPAIGN,
+    cost: SHOP_COST.ARMOUR_PLATING,
+    description: "+1 max HP (Tech's turrets deploy at that max HP).",
+    needsTarget: true,
+    minRepTier: REP_TIER.KNOWN,
+  }),
   Object.freeze({
     id: ITEM_ID.REFLEX_WEAVE,
     label: 'Reflex Weave',
@@ -150,15 +159,6 @@ const CATALOG: readonly Item[] = Object.freeze([
     needsTarget: true,
     minRepTier: REP_TIER.KNOWN,
   }),
-  Object.freeze({
-    id: ITEM_ID.ARMOUR_PLATING,
-    label: 'Armour Plating',
-    scope: ITEM_SCOPE.CAMPAIGN,
-    cost: SHOP_COST.ARMOUR_PLATING,
-    description: "+1 max HP (Tech's turrets deploy at that max HP).",
-    needsTarget: true,
-    minRepTier: REP_TIER.KNOWN,
-  }),
   Object.freeze({
     id: ITEM_ID.BALLISTICS_COIL,
     label: 'Ballistics Coil',
diff --git a/tests/unit/game/Campaign.test.ts b/tests/unit/game/Campaign.test.ts
index d92cf79..586a08b 100644
--- a/tests/unit/game/Campaign.test.ts
+++ b/tests/unit/game/Campaign.test.ts
@@ -672,6 +672,18 @@ test('P3.M1.2: Act 1 advances to Act 2 at KNOWN Rep plus four completed jobs and
   assert.match(decker!.id, /^crew-decker-/);
 });
 
+test('P3.M1.2: Act 1 advances to Act 2 at TRUSTED Rep when job gate is met', () => {
+  const campaign = new Campaign({ seed: 42, rep: 100, completedJobs: 9 });
+
+  assert.equal(campaign.arcStage, 'act-2');
+  assert.equal(campaign.arc.scoreRevealed, true);
+  assert.equal(campaign.arc.deckerRecruited, true);
+  assert.ok(
+    campaign.crew.some(m => m.archetype === 'Decker'),
+    'TRUSTED Rep should not block Act 2 after overshooting KNOWN'
+  );
+});
+
 test('P3.M1.2: successful extraction advances Act 2 when the final gate is crossed', () => {
   const campaign = new Campaign({ seed: 42, rep: 49, completedJobs: 3 });
   const member = campaign.crew[0];
diff --git a/tests/unit/game/hub/hubReveals.test.ts b/tests/unit/game/hub/hubReveals.test.ts
index 9aca71f..5af2164 100644
--- a/tests/unit/game/hub/hubReveals.test.ts
+++ b/tests/unit/game/hub/hubReveals.test.ts
@@ -5,7 +5,9 @@ import { Campaign } from '../../../../src/game/Campaign.js';
 import { REP } from '../../../../src/game/constants.js';
 import { OUTCOME } from '../../../../src/game/Run.js';
 import {
+  commitHubReveal,
   emptyHubReveals,
+  hubRevealCommitsOnDismiss,
   isTerminalAccessible,
   isTerminalRecruitmentUnlocked,
   migrateLegacyHubReveals,
@@ -138,7 +140,8 @@ test('Score reveal presents the target and assigns a Decker when Act 2 opens', (
   });
   assert.equal(campaign.arc.arcStage, 'act-2');
   assert.equal(campaign.lastHubReveal?.id, 'score-reveal');
-  assert.equal(campaign.hubReveals.scoreBriefingPresented, true);
+  assert.equal(campaign.hubReveals.scoreBriefingPresented, undefined);
+  assert.ok(hubRevealCommitsOnDismiss('score-reveal'));
   const revealText = campaign.lastHubReveal?.lines.join('\n') ?? '';
   assert.match(revealText, /SCORE SITE/);
   assert.match(revealText, /Decker/);
@@ -149,10 +152,60 @@ test('Score reveal presents the target and assigns a Decker when Act 2 opens', (
   assert.ok(decker, 'Decker should be on the crew after Act 2 entry');
   assert.ok(decker!.callsign, 'Decker should have a callsign');
 
+  commitHubReveal(campaign, 'score-reveal');
+  assert.equal(campaign.hubReveals.scoreBriefingPresented, true);
+
   campaign.enterHub();
   assert.equal(campaign.lastHubReveal, null);
 });
 
+test('Score reveal takes priority over clinic when Act 2 opens with injured crew', () => {
+  const campaign = hubCampaign({
+    rep: 60,
+    completedJobs: 4,
+    hubReveals: {
+      terminalExplained: true,
+      finnIntroduced: true,
+      terminalRecruitmentExplained: true,
+    },
+  });
+  campaign.crew[0].hp = 1;
+  campaign.enterHub();
+  assert.equal(campaign.lastHubReveal?.id, 'score-reveal');
+  assert.equal(campaign.hubReveals.clinicIntroduced, undefined);
+});
+
+test('restoreCampaign leaves Score briefing pending until the shell dismisses it', () => {
+  const snap = snapshotCampaign(
+    new Campaign({
+      seed: 42,
+      rep: 100,
+      completedJobs: 9,
+      hubReveals: {
+        terminalExplained: true,
+        finnIntroduced: true,
+        clinicIntroduced: true,
+        terminalRecruitmentExplained: true,
+      },
+      arc: {
+        arcStage: 'act-1',
+        deckerRecruited: false,
+        scoreRevealed: false,
+        clockStarted: false,
+        scoreAttempted: false,
+        scoreCompleted: false,
+      },
+    })
+  );
+  delete snap.arc;
+
+  const restored = restoreCampaign(snap);
+  assert.equal(restored.arcStage, 'act-2');
+  assert.equal(restored.arc.scoreRevealed, true);
+  assert.equal(restored.lastHubReveal?.id, 'score-reveal');
+  assert.equal(restored.hubReveals.scoreBriefingPresented, undefined);
+});
+
 test('terminal recruitment reveal when pendingRecruitReward even below Rep', () => {
   const campaign = hubCampaign({
     rep: REP.START,

From 39499b14f7541343d75f5308941078e3fd6cbcea Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Tue, 9 Jun 2026 16:51:17 -0700
Subject: [PATCH 09/55] Finish campaign arc narrative beats

---
 components/ContractSelect.ts           |  50 ++++++-
 components/CrashDump.ts                |  89 +++++++++++-
 components/CrewRoster.ts               |  29 +++-
 components/RunBriefing.ts              |   3 +
 docs/kaizen.md                         |   1 +
 docs/phase-3-plan.md                   |  69 ++++++----
 index.ts                               |  94 ++++++++++---
 src/game/Campaign.ts                   | 184 +++++++++++++++++++++++++
 src/game/hub/Curator.ts                | 124 ++++++++++++++++-
 src/game/hub/arcSurface.ts             |  78 ++++++++++-
 src/game/hub/hubReveals.ts             |  71 ++++++++--
 src/game/persistence.ts                |  11 ++
 src/types.ts                           |   4 +
 sw-dev.js                              |   2 +-
 tests/unit/game/Campaign.test.ts       | 168 +++++++++++++++++++++-
 tests/unit/game/hub/Curator.test.ts    |  80 +++++++++++
 tests/unit/game/hub/arcSurface.test.ts | 116 ++++++++++++++--
 tests/unit/game/hub/hubReveals.test.ts | 106 +++++++++++++-
 18 files changed, 1181 insertions(+), 98 deletions(-)

diff --git a/components/ContractSelect.ts b/components/ContractSelect.ts
index 9de6f39..676bd5f 100644
--- a/components/ContractSelect.ts
+++ b/components/ContractSelect.ts
@@ -6,7 +6,7 @@
 
 import { h } from '/src/domUtils.js';
 import { encounterHostileCount } from '/src/game/encounters.js';
-import { isScoreSiteContract } from '/src/game/hub/arcSurface.js';
+import { isScorePrincipalContract, isScoreSiteContract } from '/src/game/hub/arcSurface.js';
 import { cloneObjective } from '/src/game/hub/Curator.js';
 import type { Contract } from '/src/game/hub/Curator.js';
 
@@ -140,6 +140,11 @@ const CSS = `
   background: var(--board-danger);
 }
 
+.badge.score {
+  background: #f8f7ff;
+  color: #020403;
+}
+
 .known {
   color: var(--board-dim);
   border: 1px solid rgba(106, 232, 200, 0.45);
@@ -156,6 +161,12 @@ const CSS = `
   border-color: var(--board-warn);
 }
 
+.known.casing {
+  color: #020403;
+  background: #9be7ff;
+  border-color: #9be7ff;
+}
+
 .meta {
   color: var(--board-dim);
   font-size: 0.84rem;
@@ -193,6 +204,7 @@ const CSS = `
 class ContractSelect extends HTMLElement {
   #contracts: Contract[] = [];
   #scoreTargetSiteId: string | null = null;
+  #scorePrincipalId: string | null = null;
   #selectedIndex = 0;
   #ready = false;
   #listEl: HTMLElement | null = null;
@@ -251,6 +263,14 @@ class ContractSelect extends HTMLElement {
     if (this.#ready) this.#render();
   }
 
+  setScorePrincipalId(principalId: string | null) {
+    if (principalId !== null && (typeof principalId !== 'string' || principalId.length === 0)) {
+      throw new TypeError('<contract-select>.setScorePrincipalId requires a principal id or null');
+    }
+    this.#scorePrincipalId = principalId;
+    if (this.#ready) this.#render();
+  }
+
   show() {
     this.setAttribute('open', '');
     queueMicrotask(() => this.#focusSelected());
@@ -284,15 +304,22 @@ class ContractSelect extends HTMLElement {
           h('div', { className: 'primary' }, [
             h('div', { className: 'name' }, [
               h('span', {
-                className: `badge ${contract.difficulty}`,
+                className: `badge ${isScoreContract(contract) ? 'score' : contract.difficulty}`,
                 textContent: difficultyLabel(contract),
               }),
               h('span', { className: 'target', textContent: jobTitleCopy(contract) }),
             ]),
-            h('div', { className: 'location' }, locationLine(contract, this.#scoreTargetSiteId)),
+            h(
+              'div',
+              { className: 'location' },
+              locationLine(contract, this.#scoreTargetSiteId, this.#scorePrincipalId)
+            ),
             h('div', { className: 'meta', textContent: rewardCopy(contract) }),
           ]),
-          h('div', { className: 'take', textContent: 'TAKE THE JOB' }),
+          h('div', {
+            className: 'take',
+            textContent: isScoreContract(contract) ? 'TAKE THE SCORE' : 'TAKE THE JOB',
+          }),
         ]
       ) as HTMLButtonElement;
       if (index === this.#selectedIndex) button.setAttribute('selected', '');
@@ -353,28 +380,37 @@ class ContractSelect extends HTMLElement {
 }
 
 function difficultyLabel(contract: Contract): string {
+  if (isScoreContract(contract)) return 'SCORE';
   return DIFFICULTY_LABEL[contract.difficulty] ?? contract.difficulty.toUpperCase();
 }
 
 function rewardCopy(contract: Contract): string {
+  if (isScoreContract(contract)) return 'final run · no payout · campaign on the line';
   const recruit = contract.reward.recruit ? ' · recruit lead' : '';
   return `${encounterHostileCount(contract)} hostiles · Cr +${contract.reward.credits} · REP +${contract.reward.repDelta}${recruit}`;
 }
 
 function jobTitleCopy(contract: Contract): string {
+  if (isScoreContract(contract)) return '// The Score';
   const turnLimit = contract.objective.params?.turnLimit;
   const window =
     Number.isInteger(turnLimit) && Number(turnLimit) > 0 ? ` · WINDOW ${turnLimit} turns` : '';
   return `// ${contract.objective.title}${window}`;
 }
 
-function locationLine(contract: Contract, scoreTargetSiteId: string | null): HTMLElement[] {
+function locationLine(
+  contract: Contract,
+  scoreTargetSiteId: string | null,
+  scorePrincipalId: string | null
+): HTMLElement[] {
   const { principal, site, siteState, locationSiteId } = contract.context;
   const place = site ? `${principal.label} ${site.label}` : principal.label;
   const state = siteState ? ` [${siteState.label}]` : '';
   const nodes: HTMLElement[] = [h('span', { textContent: `Location: ${place}${state}` })];
   if (isScoreSiteContract(contract, scoreTargetSiteId)) {
     nodes.push(h('span', { className: 'known score-site', textContent: 'SCORE SITE' }));
+  } else if (isScorePrincipalContract(contract, scorePrincipalId, scoreTargetSiteId)) {
+    nodes.push(h('span', { className: 'known casing', textContent: 'CASING' }));
   } else if (locationSiteId) {
     nodes.push(h('span', { className: 'known', textContent: '// known site' }));
   }
@@ -389,6 +425,10 @@ function cloneContract(contract: Contract): Contract {
   };
 }
 
+function isScoreContract(contract: Contract): boolean {
+  return contract.context.tags.includes('score') && contract.context.recipeId === 'score-final';
+}
+
 customElements.define('contract-select', ContractSelect);
 
 export default ContractSelect;
diff --git a/components/CrashDump.ts b/components/CrashDump.ts
index a3f7d75..ebec5e2 100644
--- a/components/CrashDump.ts
+++ b/components/CrashDump.ts
@@ -168,6 +168,14 @@ function campaignOverTitle() {
   return '*** CAMPAIGN TERMINATED ***';
 }
 
+function clockExpiredTitle() {
+  return '*** WINDOW CLOSED ***';
+}
+
+function scoreCompleteTitle() {
+  return '*** SCORE COMPLETE ***';
+}
+
 function deathFault() {
   return ['fault:  unhandled_exception_in_meatspace', 'addr:   0x00000@meatspace', 'trace:'].join(
     '\n'
@@ -186,6 +194,18 @@ function campaignOverFault() {
   ].join('\n');
 }
 
+function clockExpiredFault() {
+  return [
+    'fault:  score_operational_window_expired',
+    'addr:   0x00000@campaign_layer',
+    'trace:',
+  ].join('\n');
+}
+
+function scoreCompleteFault() {
+  return ['status: score_extracted', 'addr:   0x00000@campaign_layer', 'trace:'].join('\n');
+}
+
 function campaignTerminalFault() {
   return [
     'notice: final_operator_channel_lost — no surviving crew',
@@ -206,8 +226,41 @@ function buildCampaignOverTraceLines(crewRoster: CrewMemberStub[]) {
   });
 }
 
+function buildClockExpiredTraceLines() {
+  return [
+    { text: '  0x01  arc::clock_deadline_reached()', tag: '<expired>' },
+    { text: '  0x02  curator::score_contract_cold()', tag: '' },
+    { text: '  0x03  campaign::terminate(window_closed)', tag: '' },
+  ];
+}
+
+function buildScoreCompleteTraceLines(crewRoster: CrewMemberStub[]) {
+  const survivors = crewRoster.filter(op => !op.flatlined);
+  const lead = survivors[0];
+  const lines = [
+    {
+      text: `  0x01  score::extract_success(${lead?.callsign ?? 'crew'})`,
+      tag: '<ok>',
+    },
+    { text: '  0x02  arc::score_completed()', tag: '' },
+  ];
+  if (survivors.length > 1) {
+    lines.push({
+      text: `  0x03  roster::survivors(${survivors.length})`,
+      tag: '',
+    });
+  }
+  return lines;
+}
+
 function buildTraceLines(telemetry: Telemetry) {
   if (telemetry.outcome === 'campaign-over') {
+    if (telemetry.campaignEndReason === 'clock-expired') {
+      return buildClockExpiredTraceLines();
+    }
+    if (telemetry.campaignEndReason === 'score-complete') {
+      return buildScoreCompleteTraceLines(telemetry.crewRoster ?? []);
+    }
     return buildCampaignOverTraceLines(telemetry.crewRoster ?? []);
   }
 
@@ -360,8 +413,19 @@ class CrashDump extends HTMLElement {
     const isCampaignTerminalDeath = isDeath && t.campaignTerminal;
 
     if (isCampaignOver || isCampaignTerminalDeath) {
-      this.#els.title.textContent = campaignOverTitle();
-      this.#els.fault.textContent = isCampaignOver ? campaignOverFault() : campaignTerminalFault();
+      if (isCampaignOver && t.campaignEndReason === 'clock-expired') {
+        this.#els.title.textContent = clockExpiredTitle();
+        this.#els.fault.textContent = clockExpiredFault();
+      } else if (isCampaignOver && t.campaignEndReason === 'score-complete') {
+        this.#els.title.textContent = scoreCompleteTitle();
+        this.#els.fault.textContent = scoreCompleteFault();
+        this.setAttribute('outcome', 'exit');
+      } else {
+        this.#els.title.textContent = campaignOverTitle();
+        this.#els.fault.textContent = isCampaignOver
+          ? campaignOverFault()
+          : campaignTerminalFault();
+      }
     } else if (isDeath) {
       this.#els.title.textContent = deathTitle();
       this.#els.fault.textContent = deathFault();
@@ -382,7 +446,12 @@ class CrashDump extends HTMLElement {
       if (line.tag) {
         this.#els!.trace.appendChild(document.createTextNode('   '));
         const span = h('span', {
-          className: line.tag.includes('killed') ? 'killed' : '',
+          className:
+            line.tag.includes('killed') ||
+            line.tag.includes('flatlined') ||
+            line.tag.includes('expired')
+              ? 'killed'
+              : '',
           textContent: line.tag,
         });
         this.#els!.trace.appendChild(span);
@@ -396,10 +465,16 @@ class CrashDump extends HTMLElement {
     if (isCampaignOver) {
       this.#els.turnDd.textContent = '—';
       this.#els.killsDd.textContent = '—';
-      this.#els.causeDd.textContent =
-        Number.isInteger(t.salvage) && Number(t.salvage) >= 0
-          ? `pool salvage ${t.salvage} (lost with run)`
-          : 'no-surviving-crew';
+      if (t.campaignEndReason === 'clock-expired') {
+        this.#els.causeDd.textContent = 'Score window closed — contract cold';
+      } else if (t.campaignEndReason === 'score-complete') {
+        this.#els.causeDd.textContent = 'Score extracted — campaign complete';
+      } else {
+        this.#els.causeDd.textContent =
+          Number.isInteger(t.salvage) && Number(t.salvage) >= 0
+            ? `pool salvage ${t.salvage} (lost with run)`
+            : 'no-surviving-crew';
+      }
     } else {
       this.#els.turnDd.textContent = Number.isInteger(t.turn) ? String(t.turn) : '?';
       this.#els.killsDd.textContent = Number.isInteger(t.kills) ? String(t.kills) : '0';
diff --git a/components/CrewRoster.ts b/components/CrewRoster.ts
index a5abeee..b3408bb 100644
--- a/components/CrewRoster.ts
+++ b/components/CrewRoster.ts
@@ -11,7 +11,7 @@
  * Usage:
  *   rosterEl.setCrew(campaign.crew, {
  *     salvage: campaign.salvage,
- *     campaignStatus: 'ACT 2: CASING | SCORE: Matsuda server farm',
+ *     campaignStatus: ['ACT 2: CASING | SCORE: Matsuda server farm', 'CLOCK: HEAT 1 / 4 JOBS LEFT'],
  *     availableRecruits: campaign.availableRecruits,
  *     recruitedThisVisit: campaign.recruitedThisVisit,
  *   });
@@ -119,12 +119,21 @@ const CSS = `
 
 .campaign-status {
   margin: -0.35rem 0 0.75rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.15rem;
   text-align: center;
   color: #ffd166;
   font-size: 0.82rem;
   letter-spacing: 0.08em;
 }
 
+.campaign-status__line {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
 .body {
   display: grid;
   grid-template-columns: 1fr 1fr;
@@ -339,7 +348,7 @@ class CrewRoster extends HTMLElement {
 
     this.#titleEl = h('h2', { className: 'title', textContent: '── CREW ROSTER ──' });
     this.#balanceEl = h('p', { className: 'balance' });
-    this.#campaignStatusEl = h('p', { className: 'campaign-status' });
+    this.#campaignStatusEl = h('div', { className: 'campaign-status' });
 
     this.#listEl = document.createElement('crew-list') as CrewList;
     this.#listEl.addEventListener('select', evt =>
@@ -406,7 +415,7 @@ class CrewRoster extends HTMLElement {
       recruitedThisVisit = false,
     }: {
       salvage?: TypedSalvage;
-      campaignStatus?: string;
+      campaignStatus?: string | readonly string[];
       availableRecruits?: CrewMember[];
       recruitedThisVisit?: boolean;
     } = {}
@@ -421,8 +430,7 @@ class CrewRoster extends HTMLElement {
     // Show typed breakdown + total
     const total = totalSalvage(this.#salvage);
     this.#balanceEl!.textContent = `SALVAGE ${total} · ${formatSalvageCompact(this.#salvage)}`;
-    this.#campaignStatusEl!.textContent = campaignStatus;
-    this.#campaignStatusEl!.style.display = campaignStatus ? '' : 'none';
+    this.#renderCampaignStatus(campaignStatus);
     this.#recruitFocused = false;
     this.#selectedRecruitIndex = -1;
     // Crew list handles its own rendering; selection triggers detail update.
@@ -430,6 +438,17 @@ class CrewRoster extends HTMLElement {
     this.#renderRecruits();
   }
 
+  #renderCampaignStatus(status: string | readonly string[]) {
+    const lines = typeof status === 'string' ? status.split('\n') : status;
+    const normalized = lines.map(line => line.trim()).filter(Boolean);
+    this.#campaignStatusEl!.replaceChildren(
+      ...normalized.map(line =>
+        h('span', { className: 'campaign-status__line', textContent: line })
+      )
+    );
+    this.#campaignStatusEl!.style.display = normalized.length > 0 ? '' : 'none';
+  }
+
   show() {
     this.setAttribute('open', '');
     queueMicrotask(() => {
diff --git a/components/RunBriefing.ts b/components/RunBriefing.ts
index 261aa0c..86f5bdd 100644
--- a/components/RunBriefing.ts
+++ b/components/RunBriefing.ts
@@ -195,6 +195,9 @@ function threatCopy(count: number) {
 }
 
 function rewardCopy(contract: Partial<Contract>) {
+  if (contract.context?.tags.includes('score') && contract.context.recipeId === 'score-final') {
+    return 'Campaign finale';
+  }
   const reward = contract.reward;
   if (!reward) return '?';
   const recruit = reward.recruit ? ' + recruit lead' : '';
diff --git a/docs/kaizen.md b/docs/kaizen.md
index 141efe1..7aa124b 100644
--- a/docs/kaizen.md
+++ b/docs/kaizen.md
@@ -55,6 +55,7 @@ When an item lands, gets reclassified, or develops new context, edit it in place
 - **`Run.id` collision risk.** `Run.makeRunId(seed)` concatenates `seed` and `Date.now()` for a non-cryptographic id; two runs started on the same millisecond with the same seed would collide. Vanishingly unlikely in practice, but if a future automated playthrough harness ever spins many runs quickly, switch to `crypto.randomUUID()`. Logged in `Run.js`.
 - **No Hub healing path.** M4 made HP persistent across jobs but deliberately shipped with no Hub-side heal beyond Armour Plating's +1 hp side-effect. **→ M5.3 (Hub clinic NPC)** will ship a dedicated Doc NPC on the Hub map: heal-to-full for Creds, one heal per crew member per visit. See [phase-2.5-plan.md](phase-2.5-plan.md) M5.3.
 - **Dev browser reports multiple service workers.** M8 browser smoke showed `[KernelPanic] Multiple service workers detected` before accepting the waiting worker. The update flow recovered and reloaded cleanly, with no console errors after activation, so this is monitored rather than blocking. Revisit if update prompts repeat in a loop or stale bundles survive an accepted update.
+- **`RunBriefing` still has one direct DOM creation call.** `components/RunBriefing.ts` creates its nested `<crew-list>` with `document.createElement('crew-list')` instead of the project-standard `h()` helper. Not touched during P3.M1 because it is unrelated to campaign arc behavior; clean it up next time that component is edited.
 - **`mapConnectivity` cleanup backlog (post–Pier 7 audit).** Chokepoint avoidance, entity-aware RECON eligible cells, and `explorationReachableKeys` as the shared flood are landed (`mapConnectivity.ts`; see [phase-2.5-plan.md](phase-2.5-plan.md) M2.11 / M6.3). Remaining items are mechanical dedup — no known correctness gap:
   - **Anchor finder loops in `Run.ts`.** `findInteractableAnchor`, `findDecoupledTerminalAnchor`, `findInteractableAnchorByReachability`, and `findBehindDoorFallbackAnchor` each repeat the same grid scan + filter predicates (~80 lines). Extract a shared candidate collector when next touching objective placement.
   - **Door-state exploration wrapper duplicated.** `anchorPreservesExplorationReachabilityForDoorAnchor` (`Run.ts`) and `preservesExplorationWithDoorState` (`mapBuild.ts`) are the same lock/unlock + chokepoint check. Consolidate when either file is next edited.
diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 8f651a0..21ab864 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -18,8 +18,8 @@ The campaign is a **Neuromancer-shaped arc**: a crew of operators assembles over
 | **Stage 1: Street level** | 1–5 | Build rep, learn combat, recruit crew. Pure Meatspace gigs. Unconnected contracts from P2.5.M2.10 recipes. | P2.5.M2 objectives, P2.5.M5 economy, P2.5.M7 site roster begins |
 | **Turning point** | ~5 | Reach KNOWN rep tier. Curator reveals the Score and assigns the Decker in one beat. | Decker joins crew; Score target synthesized (always new, CRITICAL-tier) |
 | **Stage 2: Casing** | 6–10 | Prep runs targeting the Score principal's org + resource building. Cyberspace available on some contracts. Learning the flip. Curator biases toward same-principal contracts. | P2.5.M7 persistence (casing), Cyberspace, simstim flip |
-| **The Clock starts** | ~8 | Pressure mounts — rival crew, corp heat, neural degradation. Contracts get harder; delay has cost. | Clock mechanic |
-| **Stage 3: The Score** | 11–13 | Final prep runs, then the big job. Dual-layer climax: Meatspace breach + Cyberspace penetration. | Everything converges |
+| **The Clock starts** | Act 2+ | After a grace period of Act 2/3 **deploys** (not completed jobs), corp heat mounts — more hostiles, tighter alarms, visible deadline pressure. | Clock mechanic + `clock-reveal` Hub beat |
+| **Stage 3: Final prep** | ~9+ jobs | Casing gates satisfied; Curator `act-3-reveal` beat; prep board + player-initiated **THE SCORE**. | Everything converges toward the climax |
 
 ### The simstim flip
 
@@ -41,8 +41,8 @@ A new **player archetype** recruited mid-campaign (late Act 1 / start of Act 2),
 
 | Milestone | Status |
 |---|---|
-| P3.M1 — Campaign arc structure | 🚧 In progress — P3.M1.1–P3.M1.4 done |
-| P3.M2 — The Decker archetype | 🚧 In progress — class + Drone Override Hack done; recruitment flow pending |
+| P3.M1 — Campaign arc structure | ✅ Done |
+| P3.M2 — The Decker archetype | ✅ Done |
 | P3.M3 — Cyberspace grid + ICE | 🔲 Planned |
 | P3.M4 — Simstim flip (dual-deploy) | 🔲 Planned |
 | P3.M5 — The Score (climactic mission) | 🔲 Planned |
@@ -63,7 +63,7 @@ Phase 3 should start from the shipped Phase 2.5 surface, not rebuild it:
 - `LocationSite` already reserves `tier: 'score'` and `scoreTarget`; P2.5.M7 never sets them, so P3.M1 owns designation.
 - `Curator.generateContracts(rng, campaign)` already accepts `arcStage` and stores it into `contract.context.arcStage`; P3.M1 owns deriving the stage from campaign state and using it for real recipe weighting / Score targeting.
 - P2.7.M6.2 landed: entity snapshot `extra` property bags and campaign-scoped key items are available for Decker / Cyberspace state instead of expanding the old top-level snapshot union.
-- Hub reveal plumbing already exists (`applyFirstHubReveal`, Finn, Clinic, Terminal). The Score reveal and Decker recruitment share a single `score-reveal` Hub reveal beat rather than using a separate modal.
+- Hub reveal plumbing already exists (`applyFirstHubReveal`, Finn, Clinic, Terminal). Phase 3 arc beats use deferred Curator briefings: `score-reveal` (Score + Decker), `clock-reveal` (heat + deadline), and `act-3-reveal` (THE SCORE available). Flags commit on briefing dismiss, not on queue.
 
 ## Phase 2.5 foundations (prerequisites)
 
@@ -72,7 +72,7 @@ Phase 3 depends on specific hooks built into Phase 2.5 milestones:
 | 2.5 Milestone | Phase 3 hook | Notes |
 |---|---|---|
 | **P2.5.M2.10** (recipes) | Recipe context accepts **arc stage** input | Phase 3 uses this to bias contract generation toward Score-adjacent objectives in Acts 2–3 |
-| **P2.5.M5** (economy/rep) | KNOWN rep tier defined and reachable | Phase 3 gates Decker recruitment and Score access at KNOWN (50) |
+| **P2.5.M5** (economy/rep) | KNOWN rep tier defined and reachable | Phase 3 gates Decker recruitment and Score access at `rep >= 50` (KNOWN floor; TRUSTED qualifies) |
 | **P2.5.M7** (persistence) | Location schema includes `scoreTarget` flag; site roster + mutation deltas | Phase 3 synthesizes a new CRITICAL-tier Score target; player "cases" it across visits. Roster sites for the same principal provide recon value |
 
 ### Score target identification
@@ -81,7 +81,7 @@ The Score target is always a newly synthesized CRITICAL-tier site, never promote
 
 ## Milestones — detail
 
-### P3.M1 — Campaign arc structure 🔲
+### P3.M1 — Campaign arc structure ✅
 
 **Depends on:** Phase 2.5 complete (P2.5.M2.10 recipe hooks, P2.5.M5 rep tiers, P2.5.M7 site roster).
 
@@ -89,11 +89,11 @@ The Score target is always a newly synthesized CRITICAL-tier site, never promote
 
 **Scope:**
 
-- **Arc state:** Campaign save tracks `arcStage` (`act-1` / `act-2` / `act-3` / `score`), run count, and arc-specific flags (`deckerRecruited`, `scoreRevealed`, `clockStarted`, `scoreAttempted`, `scoreCompleted`). Prefer a typed `Campaign.arc` record over stuffing more opaque keys into `Campaign.meta`; legacy saves can normalize from absent `arc` into Act 1.
+- **Arc state:** Campaign save tracks `arcStage` (`act-1` / `act-2` / `act-3` / `score`), `completedJobs`, `clockJobsTaken` (Act 2/3 deploys that drive the Clock — incremented on deploy, not on extract), and arc-specific flags (`deckerRecruited`, `scoreRevealed`, `clockStarted`, `scoreAttempted`, `scoreCompleted`). Hub reveal flags (`scoreBriefingPresented`, `clockBriefingPresented`, `act3BriefingPresented`) persist separately. Prefer a typed `Campaign.arc` record over stuffing more opaque keys into `Campaign.meta`; legacy saves can normalize from absent `arc` into Act 1.
 - **Act transitions:** Define triggers for act boundaries:
-  - Act 1 → Act 2: reach `KNOWN` rep tier (50) + minimum successful job count (recommended: `completedJobs >= 4`). Triggers Score reveal and Decker recruitment (same beat).
-  - Act 2 → Act 3: `completedJobs >= 9` + at least 4 **living** (non-flatlined) crew + at least 3 visited sites sharing the Score target's principal (including the Score target itself). The Decker gate is gone — the Decker is always assigned at Act 2 entry. The crew gate rewards keeping people alive; the principal-sites gate is the "casing" payoff — you've hit enough of the org's facilities to know how they operate. Triggers "final prep" phase.
-  - Score available: Act 3 + player-initiated (choose to attempt the Score from the Hub).
+  - Act 1 → Act 2: reach at least `KNOWN` rep tier (`rep >= 50`) + minimum successful job count (recommended: `completedJobs >= 4`). Triggers Score reveal and Decker recruitment (same beat).
+  - Act 2 → Act 3: `completedJobs >= 9` + at least 4 **living** (non-flatlined) crew + at least 3 visited sites sharing the Score target's principal (including the Score target itself). The Decker gate is gone — the Decker is always assigned at Act 2 entry. The crew gate rewards keeping people alive; the principal-sites gate is the "casing" payoff — you've hit enough of the org's facilities to know how they operate. Triggers "final prep" phase and the `act-3-reveal` Hub beat on first qualifying Hub entry.
+  - Score available: Act 3 + player-initiated (choose **THE SCORE** from the Hub job board after the Act 3 briefing).
 - **Score target designation:** At Act 2 entry, always synthesize a new CRITICAL-tier `LocationSite` from Curator lexicon as the Score target. The Score is a location the player hasn't seen — Act 2 contracts bias toward the same principal so the player learns about the organization before hitting the crown jewel. Existing roster sites are never promoted; they serve as intel and casing prep. Multiple persisted score targets, or score-tier sites missing `scoreTarget`, throw during Hub-entry arc evaluation.
 - **Decker recruitment:** Same narrative beat as the Score reveal. The Curator assigns a named Decker — no player choice modal. The crew gains a specialist as part of the Score pitch ("here's the job, and here's the person who can open it"). Future phases may differentiate Decker stats and offer a choice; for now the assignment is the narrative.
 - **Arc-aware Curator:** Current code already passes through `arcStage`; P3.M1 must make it behaviorally meaningful:
@@ -101,21 +101,26 @@ The Score target is always a newly synthesized CRITICAL-tier site, never promote
   - Act 2 = at least one board slot biased toward the Score target's principal (same corp, different sites) so the player learns the org before the climax.
   - Act 3 = board mostly prep contracts at or near the Score target, plus a separate player-initiated Score action instead of a random roll.
   - Score = special contract build path; not part of the normal three-card job board.
-- **Hub surface:** Hub status / Terminal shows current stage, Clock pressure, and Score target label once revealed. User-facing labels use "Stage" (STAGE 1, STAGE 2, etc.) — code and persistence keep `arc`/`arcStage` naming. The Score reveal uses progressive Hub reveal plumbing so the Curator can present the target and the Decker together as a single campaign beat.
+- **Hub surface:** Hub status / Terminal shows current stage and Score target label once revealed. Clock HUD (`CLOCK: HEAT X / Y JOBS LEFT`) appears **only after** the player dismisses the `clock-reveal` briefing and heat has actually started — no "dormant" or countdown-to-heat lines before then. User-facing labels use "Stage" (STAGE 1, STAGE 2, etc.) — code and persistence keep `arc`/`arcStage` naming. Arc beats use progressive Hub reveal plumbing (`score-reveal`, `clock-reveal`, `act-3-reveal`); see P3.M1.4–M1.5 notes.
 - **Win/loss conditions:**
-  - **Win:** Complete the Score (extract with objective satisfied from the final mission).
+  - **Win:** Complete the Score (extract with objective satisfied from the final mission). Terminal debrief: `*** SCORE COMPLETE ***`.
   - **Loss (flatline):** Entire crew wiped during any run (existing behavior, but now with arc context for the chronicle).
-  - **Loss (clock):** Clock expires before Score is attempted (if hard deadline chosen — see Clock mechanic below).
+  - **Loss (clock):** `clockJobsTaken >= CLOCK_ACT2_DEADLINE_JOBS` (8) before `scoreAttempted`. Terminal debrief: `*** WINDOW CLOSED ***` — not a status-line footnote. Attempted Score keeps the deadline from retroactively killing the save.
 
 **The Clock mechanic:**
 
-The Clock creates mounting pressure that discourages indefinite grinding. **Recommended first implementation:** combine escalating global difficulty as soft pressure with an operational window as the hard campaign deadline. It is easy to communicate, test, and tune:
+The Clock creates mounting pressure that discourages indefinite grinding in Act 2/3. **Shipped implementation:** Act 2/3 **deploys taken** (successful or not) drive heat and the hard deadline — not global `completedJobs`, so entering Act 2 with a high job count from Stage 1 does not immediately start the Clock.
 
-- `clockStartsAtJob = 8`
-- `scoreDeadlineJob = 13`
-- `heat = max(0, completedJobs - clockStartsAtJob)`
-- Each point of heat nudges contract threat / alarm sensitivity upward, capped by difficulty tier.
-- If the player returns to Hub with `completedJobs >= scoreDeadlineJob` and `scoreAttempted` is false, campaign ends with clock loss.
+- `CLOCK_ACT2_GRACE_JOBS = 3` — first three Act 2/3 deploys are grace (no heat, no `clockStarted`)
+- `CLOCK_HEAT_WINDOW_JOBS = 5` — deploys after grace before the window closes
+- `CLOCK_ACT2_DEADLINE_JOBS = 8` — total Act 2/3 deploys (`grace + window`)
+- `clockJobsTaken` increments on `deployCrewMember` while `arcStage` is `act-2` or `act-3` (Score deploy excluded — it sets `scoreAttempted`)
+- `clockStarted` when `scoreRevealed && clockJobsTaken >= CLOCK_ACT2_GRACE_JOBS`
+- `clockHeat = max(0, clockJobsTaken - CLOCK_ACT2_GRACE_JOBS)` once started
+- Heat nudges Curator threat counts upward, capped per difficulty tier
+- Returning to Hub at the deadline without `scoreAttempted` sets `Campaign.state` to `ENDED` with `endReason: 'clock-expired'` and presents the terminal game-over screen
+
+**Hub narrative beats (priority order on `enterHub`):** `score-reveal` → `clock-reveal` → `act-3-reveal`. Each defers its `hubReveals` flag until the player dismisses the Curator briefing modal.
 
 Other Clock variants remain useful later, but should not block P3.M1:
 
@@ -131,28 +136,34 @@ Neural degradation is deferred until Cyberspace is fun enough to deserve a jack-
 | Slice | Status | Change | Tests |
 |---|---|---|---|
 | **P3.M1.1 Arc record** | ✅ Done | Add `Campaign.arc`, derive `arcStage`, persist/restore, normalize old saves to Act 1 | constructor validation, snapshot round-trip, invalid stage throws |
-| **P3.M1.2 Transitions** | ✅ Done | Advance acts from `rep`, `completedJobs`, Decker flag, Score-site visit | boundary tests around job counts and rep tier |
+| **P3.M1.2 Transitions** | ✅ Done | Advance acts from `rep`, `completedJobs`, Decker flag, Score-site visit | boundary tests around job counts; rep floor (incl. TRUSTED) |
 | **P3.M1.3 Score target** | ✅ Done | Always synthesize a new CRITICAL-tier Score target; preserve through eviction | exactly-one target, no eviction at roster cap, always synthesized (never promoted) |
-| **P3.M1.4 Hub arc surface** | ✅ Done | Curator presents Score + Decker reveal; Hub / Terminal shows stage and Score target; contract selection labels Score-site jobs | one-shot reveal, status render, Score-site badge |
-| **P3.M1.5 Clock** | 🔲 Planned | Start heat after threshold; hard loss at deadline; show status | heat math, deadline loss, no loss after Score attempt |
-| **P3.M1.6 Curator bias** | 🔲 Planned | Pass campaign-derived arc context; bias board slots by act and score target's principal | seeded boards show expected `arcStage` and same-principal frequency in Act 2+ |
-| **P3.M1.7 Score entry** | 🔲 Planned | Hub action creates the special Score contract in Act 3 only | availability gates, deployment path, attempted flag |
+| **P3.M1.4 Hub arc surface** | ✅ Done | Curator arc briefings; Hub / Terminal stage + Score target; `<contract-select>` CASING + SCORE SITE badges | deferred-commit reveals, resume briefing, casing tag |
+| **P3.M1.5 Clock** | ✅ Done | Act 2/3 deploy-driven heat + deadline; `clock-reveal`; HUD gated on briefing; clock loss game-over screen | heat math, grace deploys, deadline loss, endReason |
+| **P3.M1.6 Curator bias** | ✅ Done | Pass campaign-derived arc context; bias board slots by act and score target's principal | seeded boards show expected `arcStage` and same-principal frequency in Act 2+ |
+| **P3.M1.7 Score entry** | ✅ Done | Hub action creates the special Score contract in Act 3 only | availability gates, deployment path, attempted flag |
 
 **P3.M1.1 implementation note:** `Campaign` now owns a typed `arc` record (`arcStage`, `deckerRecruited`, `scoreRevealed`, `clockStarted`, `scoreAttempted`, `scoreCompleted`) plus an `arcStage` getter for Curator context. New snapshots serialize the record; pre-P3 snapshots normalize to Act 1; malformed persisted arc data throws during restore instead of being silently repaired.
 
-**P3.M1.2 implementation note:** Hub entry now runs a monotonic arc transition evaluator. Act 1 advances to Act 2 at `KNOWN` Rep (50) plus `completedJobs >= 4`, sets `scoreRevealed`, and auto-assigns a Decker to the crew. Act 2 advances to Act 3 once `completedJobs >= 9`, at least 4 non-flatlined crew, and at least 3 visited roster sites sharing the Score target's principal (including the target itself). The crew gate counts living members only — attrition blocks advancement. Successful extractions increment `completedJobs`, abort extractions do not. M1.2 does not synthesize the Score target — that remains P3.M1.3.
+**P3.M1.2 implementation note:** Hub entry now runs a monotonic arc transition evaluator. Act 1 advances to Act 2 at `rep >= ARC_ACT_2_MIN_REP` (50 — the KNOWN tier floor) plus `completedJobs >= 4`, sets `scoreRevealed`, and auto-assigns a Decker to the crew. Higher rep tiers qualify too: a save that overshoots KNOWN into TRUSTED before the job gate is crossed must not stall in Act 1 (an early implementation checked for the KNOWN tier band exactly, which blocked TRUSTED saves). Act 2 advances to Act 3 once `completedJobs >= 9`, at least 4 non-flatlined crew, and at least 3 visited roster sites sharing the Score target's principal (including the target itself). The crew gate counts living members only — attrition blocks advancement. Successful extractions increment `completedJobs`, abort extractions do not. M1.2 does not synthesize the Score target — that remains P3.M1.3.
 
 **P3.M1.3 implementation note:** Score reveal always synthesizes a new CRITICAL-tier site from Curator lexicon `corp` principal and `corp/data/security/infrastructure/hidden` site tokens. Existing roster sites are never promoted — the Score is always a location the player hasn't visited yet. The synthesized site gets `scoreTarget: true`, `tier: 'score'`, and CRITICAL-footprint dimensions to support escalated hostile placement. Multiple persisted score targets, or score-tier sites missing `scoreTarget`, throw during Hub-entry arc evaluation.
 
-**P3.M1.4 implementation note:** Score reveal is now player-visible. A one-shot `score-reveal` Hub reveal lets the Curator name the target, introduce the Decker, and teach the `SCORE SITE` board badge — all in a single narrative beat. The Hub status row and Terminal crew roster show the current stage label (user-facing "STAGE N") plus Score target once revealed, and `<contract-select>` highlights contracts whose `locationSiteId` matches the campaign Score target. Shared `arcSurface` helpers own the copy and invariant checks so multiple Score targets, or revealed Score state without a target, fail loud instead of rendering misleading UI.
+**P3.M1.4 implementation note:** Score reveal is player-visible. A one-shot `score-reveal` Hub reveal lets the Curator name the target, introduce the Decker, and teach the **CASING** job-board badge (same-principal org jobs during Act 2+). **SCORE SITE** still marks contracts whose `locationSiteId` matches the synthesized Score target. Arc briefings (`score-reveal`, `clock-reveal`, `act-3-reveal`) are priority Hub reveals: they are evaluated before lower-priority intros (Finn, clinic, terminal-recruit) so a mid-save act transition is not crowded out on the same visit. Their `hubReveals` flags commit on Curator briefing **dismiss** (`commitHubReveal` in the shell), not when `enterHub` queues the copy — so a missed modal can retry on the next Hub entry, and pre-P3 saves that qualify for Act 2 on first load under 3.0 are not silently bumped without the narrative beat. The shell resume path presents any pending `lastHubReveal` when restoring a HUB save. The Hub status row and Terminal crew roster show the current stage label (user-facing "STAGE N") plus Score target once revealed. Shared `arcSurface` helpers own the copy and invariant checks so multiple Score targets, or revealed Score state without a target, fail loud instead of rendering misleading UI.
+
+**P3.M1.5 implementation note:** The Clock is driven by `clockJobsTaken` (Act 2/3 deploys), not `completedJobs` — entering Act 2 with many Stage 1 extractions does not start heat immediately. Grace: `CLOCK_ACT2_GRACE_JOBS` (3) deploys; then `clockStarted` and heat accrue until `CLOCK_ACT2_DEADLINE_JOBS` (8). A `clock-reveal` Hub briefing explains heat, the operational window, and what happens when it closes (copy in `clockRevealLines`). Clock HUD text appears only after `clockBriefingPresented` **and** `clockStarted`: `CLOCK: HEAT X / Y JOBS LEFT` on the canvas HUD, Terminal roster, and status bar. No "dormant" or "N jobs to heat" lines before the player has seen the briefing. Heat raises Curator threat counts without changing difficulty tier, capped per tier. Deadline loss sets `Campaign.endReason` to `clock-expired` and shows a dedicated terminal game-over screen (`*** WINDOW CLOSED ***` via `<crash-dump>`), not a clock status footnote. Score win uses `*** SCORE COMPLETE ***`; crew wipe keeps the existing campaign-terminal death path. An attempted Score keeps the deadline from retroactively killing the save.
+
+**P3.M1.6 implementation note:** `Curator.generateContracts` now uses campaign-derived arc context behaviorally. Act 2 guarantees at least one fresh same-principal casing job for the Score target's organization. Act 3 guarantees a mostly same-principal prep board. The normal board avoids rolling the Score target itself so the finale stays a deliberate Hub action.
+
+**P3.M1.7 implementation note:** Act 3 exposes a special `THE SCORE` contract through `Campaign.buildScoreContract()`, appended to the Hub job choices only when `Campaign.canAttemptScore()` passes. The first qualifying Hub visit also fires `act-3-reveal` ("You're ready… grab THE SCORE from the board while you can") before the player sees the fourth board slot. Deploying THE SCORE marks `scoreAttempted`, moves `arcStage` to `score`, uses the persisted Score target dimensions/memory, and completing it marks `scoreCompleted` and ends the campaign in a win state.
 
 **Acceptance:**
 
 - Arc state persists in campaign save; restore round-trip.
 - Act transitions fire at correct thresholds; tests for boundary conditions.
-- Score reveal is player-visible: Curator presents the target once, Hub / Terminal displays the current act and target label, and contract selection marks Score-site jobs.
+- Score reveal is player-visible: Curator presents the target once (including on legacy-save restore when Act 2 opens for the first time), Hub / Terminal displays the current act and target label, and contract selection marks **CASING** (same principal) and **SCORE SITE** (target location) jobs.
 - Curator generates arc-appropriate contracts per act (testable via seeded generation with arc context).
-- At least one Clock type implemented with visible feedback (Hub status, contract briefing, or log).
+- Clock: `clock-reveal` briefing, deploy-driven heat, HUD visible only post-briefing, clock loss reaches terminal game-over screen.
 - Exactly one Score target exists after Score reveal; it survives roster eviction and keeps its P2.5.M7 terrain memory.
 - Win/loss conditions reachable in golden-path test.
 
diff --git a/index.ts b/index.ts
index 5363b27..3490956 100644
--- a/index.ts
+++ b/index.ts
@@ -74,7 +74,11 @@ import { hasLineOfSight } from '/src/game/LineOfSight.js';
 import { ITEM_ID, getItemById } from '/src/game/items.js';
 import type { CampaignSnapshot } from '/src/game/persistence.js';
 import type { Contract } from '/src/game/hub/Curator.js';
-import { formatHubArcStatus, scoreTargetSiteId } from '/src/game/hub/arcSurface.js';
+import {
+  formatHubArcStatusLines,
+  scorePrincipalId,
+  scoreTargetSiteId,
+} from '/src/game/hub/arcSurface.js';
 import {
   commitHubReveal,
   hubRevealCommitsOnDismiss,
@@ -132,6 +136,7 @@ type RunBriefingElement = ModalElement & {
 type ContractSelectElement = ModalElement & {
   setContracts(contracts: Contract[]): void;
   setScoreTargetSiteId(siteId: string | null): void;
+  setScorePrincipalId(principalId: string | null): void;
 };
 type CrashDumpElement = ModalElement & {
   setTelemetry(telemetry: Record<string, unknown>): void;
@@ -153,7 +158,7 @@ type CrewRosterElement = ModalElement & {
     crew: Crew[],
     opts?: {
       salvage?: TypedSalvage;
-      campaignStatus?: string;
+      campaignStatus?: string | readonly string[];
       availableRecruits?: Crew[];
       recruitedThisVisit?: boolean;
     }
@@ -721,7 +726,7 @@ function enterHubAndRender() {
     flash('HUB — Curator has contracts when you are adjacent [Space].');
   }
   // generate job options once on hub enter
-  currentJobOptions = campaign.curator.generateContracts(campaign.rng, campaign);
+  currentJobOptions = generateCurrentJobOptions();
 }
 
 function presentCrewRoster() {
@@ -729,7 +734,9 @@ function presentCrewRoster() {
   campaign.backfillRecruitsIfEligible();
   crewRosterEl.setCrew(campaign.crew, {
     salvage: campaign.salvage,
-    campaignStatus: formatHubArcStatus(campaign),
+    campaignStatus: formatHubArcStatusLines(campaign).filter(
+      (line): line is string => line !== null
+    ),
     availableRecruits: campaign.availableRecruits,
     recruitedThisVisit: campaign.recruitedThisVisit,
   });
@@ -759,10 +766,22 @@ function presentBriefing(contract: Contract) {
 
 function presentContractSelect(contracts: Contract[]) {
   contractSelectEl.setScoreTargetSiteId(campaign ? scoreTargetSiteId(campaign) : null);
+  contractSelectEl.setScorePrincipalId(campaign ? scorePrincipalId(campaign) : null);
   contractSelectEl.setContracts(contracts);
   contractSelectEl.show();
 }
 
+function generateCurrentJobOptions(): Contract[] {
+  if (!campaign?.curator) {
+    throw new Error('generateCurrentJobOptions: hub not entered — curator is missing.');
+  }
+  const contracts = campaign.curator.generateContracts(campaign.rng, campaign);
+  if (campaign.canAttemptScore()) {
+    contracts.push(campaign.buildScoreContract());
+  }
+  return contracts;
+}
+
 function onContractSelected(evt: Event) {
   const { contract } = (evt as CustomEvent<{ contract?: Contract }>).detail;
   if (!contract) return;
@@ -1140,8 +1159,10 @@ function crewMemberArchetypeId(member: Crew): string {
 }
 
 function telemetryForEndedCampaign(c: Campaign): Telemetry {
+  const reason = c.endReason ?? 'crew-wipe';
   return {
     outcome: 'campaign-over',
+    campaignEndReason: reason,
     seed: c.seed,
     salvage: c.salvage,
     crewRoster: c.crew.map(member => ({
@@ -1152,6 +1173,16 @@ function telemetryForEndedCampaign(c: Campaign): Telemetry {
   };
 }
 
+function presentCampaignEnd(c: Campaign): void {
+  crashEl.setTelemetry(telemetryForEndedCampaign(c));
+  renderShell();
+}
+
+function finishEndedCampaign(): void {
+  dataStore.deleteCampaign();
+  startFreshCampaign();
+}
+
 /**
  * Drives `<crash-dump>` and `pendingJobResult` whenever the active job is in
  * RESULT — both from a live `Run.onResult` callback and from a cold resume
@@ -1213,7 +1244,13 @@ function resumeCampaign(record: CampaignSnapshot | unknown) {
     if (campaign.state === CAMPAIGN_STATE.ENDED) {
       pendingJobResult = null;
       crashEl.setTelemetry(telemetryForEndedCampaign(campaign));
-      flash('CAMPAIGN ENDED — no surviving crew in this save.');
+      flash(
+        campaign.endReason === 'clock-expired'
+          ? 'WINDOW CLOSED — Score contract went cold.'
+          : campaign.endReason === 'score-complete'
+            ? 'SCORE COMPLETE — campaign archived.'
+            : 'CAMPAIGN ENDED — this save has reached a terminal state.'
+      );
       renderShell();
     } else if (campaign.activeRun?.state === RUN_STATE.RESULT) {
       pushPendingJobResultOverlay({ ...campaign.activeRun.telemetry });
@@ -1224,7 +1261,7 @@ function resumeCampaign(record: CampaignSnapshot | unknown) {
       if (!presentHubRevealIfAny(resumeFlashMessage)) {
         flash(resumeFlashMessage);
       }
-      currentJobOptions = campaign.curator.generateContracts(campaign.rng, campaign);
+      currentJobOptions = generateCurrentJobOptions();
     } else {
       flash(resumeFlashMessage);
       renderShell();
@@ -1662,9 +1699,13 @@ function handleInteract(): void {
     return;
   }
   if (currentJobOptions.length === 0) {
-    currentJobOptions = campaign.curator.generateContracts(campaign.rng, campaign);
+    currentJobOptions = generateCurrentJobOptions();
   }
-  flash('CURATOR: Three jobs on the board. Pick your trouble.');
+  flash(
+    currentJobOptions.some(contract => contract.context.recipeId === 'score-final')
+      ? 'CURATOR: Three jobs on the board. The Score is your call.'
+      : 'CURATOR: Three jobs on the board. Pick your trouble.'
+  );
   presentContractSelect(currentJobOptions);
 }
 
@@ -1776,8 +1817,12 @@ function onNewRunRequested(): void {
     }
     campaign.onJobEnd({ outcome, salvage, completed: objectiveComplete });
     if (campaign.state === CAMPAIGN_STATE.ENDED) {
-      dataStore.deleteCampaign();
-      startFreshCampaign();
+      pendingJobResult = null;
+      if (campaign.endReason === 'crew-wipe') {
+        finishEndedCampaign();
+        return;
+      }
+      presentCampaignEnd(campaign);
       return;
     } else {
       if (!presentHubRevealIfAny('HUB — choose the next job.')) {
@@ -1787,11 +1832,10 @@ function onNewRunRequested(): void {
       if (!campaign.curator) {
         throw new Error('onNewRunRequested: hub not entered — curator is missing.');
       }
-      currentJobOptions = campaign.curator.generateContracts(campaign.rng, campaign);
+      currentJobOptions = generateCurrentJobOptions();
     }
   } else if (campaign.state === CAMPAIGN_STATE.ENDED) {
-    dataStore.deleteCampaign();
-    startFreshCampaign();
+    finishEndedCampaign();
     return;
   }
   crashEl.hide();
@@ -2036,18 +2080,30 @@ function buildCombatHudSnapshot(scene: ShellScene | null): CombatHudSummaryInput
 
 function buildHubHudRows(scene: ShellScene | null) {
   if (!campaign || scene?.state !== CAMPAIGN_STATE.HUB) return undefined;
-  return [
+  const [summary, clock] = formatHubArcStatusLines(campaign);
+  const rows = [
     {
-      text: formatHubArcStatus(campaign),
+      text: summary,
       anchor: 'top-left' as const,
       row: 1,
       color: '#ffd166',
       glowColor: '#ffd166',
       accentColor: 'rgba(255, 209, 102, 0.5)',
       uppercase: true,
-      maxWidth: 520,
     },
   ];
+  if (clock) {
+    rows.push({
+      text: clock,
+      anchor: 'top-left' as const,
+      row: 2,
+      color: '#ffd166',
+      glowColor: '#ffd166',
+      accentColor: 'rgba(255, 209, 102, 0.5)',
+      uppercase: true,
+    });
+  }
+  return rows;
 }
 
 function paint(stateHint: InputState = activeInputState()): void {
@@ -2124,7 +2180,11 @@ function statusLine(state: InputState): string {
   } else {
     if (!campaign) return stateLabel();
     const repLabel = REP_LABEL.find(b => campaign!.rep >= b.min)?.label ?? 'UNKNOWN';
-    context = escapeHtml(formatHubArcStatus(campaign));
+    context = joinStatusParts(
+      formatHubArcStatusLines(campaign)
+        .filter((line): line is string => line !== null)
+        .map(escapeHtml)
+    );
     // Hub identity drops the typed-salvage compact tag —
     // the inventory overlay (`i` in Hub) is the canonical wallet view with
     // full bucket names. Total Cred / Rep / crew counts stay on this line.
diff --git a/src/game/Campaign.ts b/src/game/Campaign.ts
index 7cb2f07..998d601 100644
--- a/src/game/Campaign.ts
+++ b/src/game/Campaign.ts
@@ -22,6 +22,7 @@ import {
 } from './salvage.js';
 import { buildCrewMember, RECRUIT_ARCHETYPE_POOL } from './archetypes/index.js';
 import { CONTRACT_LEXICON, Curator } from './hub/Curator.js';
+import { OBJECTIVES } from './hub/Curator.js';
 import { Terminal } from './hub/Terminal.js';
 import { Finn } from './hub/Finn.js';
 import { Clinic } from './hub/Clinic.js';
@@ -47,6 +48,7 @@ import type { Contract } from './hub/Curator.js';
 import type { Crew } from './Crew.js';
 import type {
   CampaignArcStage,
+  CampaignEndReason,
   GridPoint,
   KeyItem,
   LocationSite,
@@ -65,6 +67,12 @@ export const ARC_ACT_3_MIN_COMPLETED_JOBS = 9;
 export const ARC_ACT_3_MIN_CREW_ALIVE = 4;
 /** Visited sites sharing the Score target's principal required for Act 3. Includes the target itself. */
 export const ARC_ACT_3_MIN_PRINCIPAL_SITES_VISITED = 3;
+/** Act-2/3 deploys taken before corp heat starts (successful or not). */
+export const CLOCK_ACT2_GRACE_JOBS = 3;
+/** Deploys after grace before the Score window closes. */
+export const CLOCK_HEAT_WINDOW_JOBS = 5;
+/** Total act-2/3 deploys allowed before clock loss (`grace + window`). */
+export const CLOCK_ACT2_DEADLINE_JOBS = CLOCK_ACT2_GRACE_JOBS + CLOCK_HEAT_WINDOW_JOBS;
 const SYNTHETIC_SCORE_TARGET_DIFFICULTY = CONTRACT_DIFFICULTY.CRITICAL;
 
 export const CAMPAIGN_STATE = Object.freeze({
@@ -114,6 +122,8 @@ export type CampaignOptions = {
   arc?: unknown;
   hubReveals?: unknown;
   completedJobs?: unknown;
+  /** Act-2/3 job deploys that drive the Clock (not completedJobs). */
+  clockJobsTaken?: unknown;
   keyItems?: unknown;
   siteRoster?: unknown;
   onPersist?: unknown;
@@ -185,6 +195,8 @@ export class Campaign {
   healedThisVisit: Set<string>;
   hubReveals: HubReveals;
   completedJobs: number;
+  /** Deploys taken during Act 2 / Act 3 casing prep — drives Clock heat and deadline. */
+  clockJobsTaken: number;
   /** Persistent key-item inventory (P2.5.M6.2) — keycards survive across runs. */
   keyItems: KeyItem[];
   /** Remembered combat locations / site roster (P2.5.M7.2), max `SITE_ROSTER_CAP`. */
@@ -204,6 +216,7 @@ export class Campaign {
     arc,
     hubReveals,
     completedJobs = 0,
+    clockJobsTaken = 0,
     keyItems,
     siteRoster,
     onPersist,
@@ -239,6 +252,14 @@ export class Campaign {
         `Campaign completedJobs must be a non-negative integer, got ${completedJobs}`
       );
     }
+    if (
+      clockJobsTaken !== undefined &&
+      (!Number.isInteger(clockJobsTaken) || (clockJobsTaken as number) < 0)
+    ) {
+      throw new RangeError(
+        `Campaign clockJobsTaken must be a non-negative integer, got ${clockJobsTaken}`
+      );
+    }
     if (onPersist !== undefined && typeof onPersist !== 'function') {
       throw new TypeError('Campaign: onPersist must be a function');
     }
@@ -257,6 +278,7 @@ export class Campaign {
     this.arc = normalizeCampaignArc(arc);
     this.hubReveals = normalizeHubReveals(hubReveals, 'Campaign hubReveals');
     this.completedJobs = (completedJobs as number) ?? 0;
+    this.clockJobsTaken = (clockJobsTaken as number) ?? 0;
     this.keyItems = normalizeKeyItems(keyItems);
     this.siteRoster = normalizeSiteRoster(siteRoster);
     this.state = CAMPAIGN_STATE.HUB;
@@ -294,11 +316,40 @@ export class Campaign {
     return this.arc.arcStage;
   }
 
+  get clockHeat(): number {
+    if (!this.arc.clockStarted) return 0;
+    return Math.max(0, this.clockJobsTaken - CLOCK_ACT2_GRACE_JOBS);
+  }
+
+  get scoreDeadlineJobsRemaining(): number {
+    return Math.max(0, CLOCK_ACT2_DEADLINE_JOBS - this.clockJobsTaken);
+  }
+
+  /** Set when `state === ENDED`; null while the campaign is still live. */
+  get endReason(): CampaignEndReason | null {
+    if (this.state !== CAMPAIGN_STATE.ENDED) return null;
+    if (this.arc.scoreCompleted) return 'score-complete';
+    if (
+      this.arc.scoreRevealed &&
+      this.clockJobsTaken >= CLOCK_ACT2_DEADLINE_JOBS &&
+      !this.arc.scoreAttempted
+    ) {
+      return 'clock-expired';
+    }
+    return 'crew-wipe';
+  }
+
   enterHub(): void {
     if (this.state !== CAMPAIGN_STATE.HUB && this.state !== CAMPAIGN_STATE.COMBAT) {
       throw new Error(`Campaign.enterHub: illegal transition from ${this.state}`);
     }
     this.#advanceArcTransitions();
+    if (this.arc.scoreCompleted || this.#clockExpired()) {
+      this.state = CAMPAIGN_STATE.ENDED;
+      this.#tearDownHubWorld();
+      this.#persist();
+      return;
+    }
     this.recruitedThisVisit = false;
     this.healedThisVisit = new Set();
     this.lastHubReveal = null;
@@ -381,6 +432,11 @@ export class Campaign {
     if (member.flatlined) {
       throw new Error(`Campaign.deployCrewMember: ${member.callsign ?? member.id} is flatlined`);
     }
+    if (isScoreContract(contract)) {
+      this.#beginScoreAttempt(contract);
+    } else if (this.arc.arcStage === 'act-2' || this.arc.arcStage === 'act-3') {
+      this.clockJobsTaken += 1;
+    }
     const deployedContract = this.#contractWithRememberedDimensions(contract);
     this.#tearDownHubWorld();
     this.deployedMemberId = member.id;
@@ -442,6 +498,12 @@ export class Campaign {
       throw new TypeError(`Campaign.onJobEnd: completed must be boolean`);
     }
 
+    const completedScoreRun =
+      this.activeRun.contract !== null &&
+      isScoreContract(this.activeRun.contract) &&
+      outcome === OUTCOME.EXIT &&
+      completed;
+
     if (outcome === OUTCOME.DEATH) {
       this.flatlineMember(this.deployedMemberId);
     } else {
@@ -479,10 +541,78 @@ export class Campaign {
       return;
     }
 
+    if (completedScoreRun) {
+      this.arc.scoreCompleted = true;
+      this.arc.arcStage = 'score';
+      this.state = CAMPAIGN_STATE.ENDED;
+      this.#tearDownHubWorld();
+      this.#persist();
+      return;
+    }
+
     this.state = CAMPAIGN_STATE.HUB;
     this.enterHub();
   }
 
+  canAttemptScore(): boolean {
+    if (this.state !== CAMPAIGN_STATE.HUB) return false;
+    if (this.arc.arcStage !== 'act-3') return false;
+    if (this.arc.scoreAttempted || this.arc.scoreCompleted) return false;
+    return this.#scoreTargetSiteOrNull() !== null;
+  }
+
+  buildScoreContract(): Contract {
+    if (!this.canAttemptScore()) {
+      throw new Error('Campaign.buildScoreContract: Score is not available');
+    }
+    const target = this.#scoreTargetSiteOrNull();
+    if (!target) {
+      throw new Error('Campaign.buildScoreContract: no Score target designated');
+    }
+    if (!target.principal) {
+      throw new Error('Campaign.buildScoreContract: Score target is missing principal identity');
+    }
+    const seed = Number(target.seed);
+    if (!Number.isInteger(seed) || seed < 0) {
+      throw new Error(`Campaign.buildScoreContract: Score target seed "${target.seed}" is invalid`);
+    }
+    const principal = locationContextToken(target.principal);
+    const site = target.site ? locationContextToken(target.site) : undefined;
+    const heatThreat = Math.min(6, 4 + this.clockHeat);
+    return {
+      seed,
+      mapWidth: target.mapWidth,
+      mapHeight: target.mapHeight,
+      objective: {
+        kind: OBJECTIVES.REACH_EXIT,
+        title: 'The Score',
+        briefing: `Hit ${target.label
+          .replace(/^\/\//, '')
+          .replace(/\s+-\s+Score target$/i, '')
+          .trim()} and extract with the crew alive.`,
+      },
+      difficulty: CONTRACT_DIFFICULTY.CRITICAL,
+      threatCount: heatThreat,
+      label: `${target.label.replace(/\s+-\s+Score target$/i, '')} - THE SCORE`,
+      context: {
+        recipeId: 'score-final',
+        principal,
+        ...(site ? { site } : {}),
+        asset: { id: 'score-target', label: 'Score target', groups: ['score'] },
+        action: { id: 'score-run', label: 'run', groups: ['score'] },
+        tags: [
+          'score',
+          'meatspace',
+          `objective:${OBJECTIVES.REACH_EXIT}`,
+          `principal:${principal.id}`,
+        ],
+        arcStage: 'score',
+        locationSiteId: target.id,
+      },
+      reward: { credits: 0, repDelta: 0 },
+    };
+  }
+
   flatlineMember(memberId: string): void {
     const member = this.getCrewMember(memberId);
     if (!member) {
@@ -1014,6 +1144,10 @@ export class Campaign {
     if (this.arc.arcStage === 'act-2' && this.#qualifiesForAct3()) {
       this.arc.arcStage = 'act-3';
     }
+
+    if (this.arc.scoreRevealed && this.clockJobsTaken >= CLOCK_ACT2_GRACE_JOBS) {
+      this.arc.clockStarted = true;
+    }
   }
 
   #qualifiesForAct2(): boolean {
@@ -1076,6 +1210,44 @@ export class Campaign {
     target.tier = 'score';
   }
 
+  #scoreTargetSiteOrNull(): LocationSite | null {
+    const scoreTargets = this.siteRoster.filter(site => site.scoreTarget);
+    if (scoreTargets.length > 1) {
+      throw new Error('Campaign arc: multiple Score targets in site roster');
+    }
+    if (this.siteRoster.some(site => site.tier === 'score' && !site.scoreTarget)) {
+      throw new Error('Campaign arc: score-tier roster site missing scoreTarget');
+    }
+    return scoreTargets[0] ?? null;
+  }
+
+  #beginScoreAttempt(contract: Contract): void {
+    if (this.arc.arcStage !== 'act-3') {
+      throw new Error('Campaign.deployCrewMember: Score can only be attempted from Act 3');
+    }
+    if (this.arc.scoreAttempted) {
+      throw new Error('Campaign.deployCrewMember: Score has already been attempted');
+    }
+    if (this.arc.scoreCompleted) {
+      throw new Error('Campaign.deployCrewMember: Score is already complete');
+    }
+    const target = this.#scoreTargetSiteOrNull();
+    if (!target || contract.context.locationSiteId !== target.id) {
+      throw new Error('Campaign.deployCrewMember: Score contract does not target the Score site');
+    }
+    this.arc.scoreAttempted = true;
+    this.arc.arcStage = 'score';
+  }
+
+  #clockExpired(): boolean {
+    return (
+      this.arc.scoreRevealed &&
+      this.clockJobsTaken >= CLOCK_ACT2_DEADLINE_JOBS &&
+      !this.arc.scoreAttempted &&
+      !this.arc.scoreCompleted
+    );
+  }
+
   #synthesizeScoreTarget(): LocationSite {
     const seed = this.rng.intRange(0, 0x7fffffff);
     const principal = this.rng.pick(
@@ -1224,6 +1396,18 @@ function locationTokenFromLexicon(token: {
   };
 }
 
+function locationContextToken(token: LocationToken) {
+  return {
+    id: token.id,
+    label: token.label,
+    groups: [...token.groups],
+  };
+}
+
+function isScoreContract(contract: Contract): boolean {
+  return contract.context.tags.includes('score') && contract.context.recipeId === 'score-final';
+}
+
 function makeCampaignId(seed: number): string {
   return `campaign-${(seed >>> 0).toString(16)}-${Date.now().toString(36)}`;
 }
diff --git a/src/game/hub/Curator.ts b/src/game/hub/Curator.ts
index b789625..5f20482 100644
--- a/src/game/hub/Curator.ts
+++ b/src/game/hub/Curator.ts
@@ -488,6 +488,7 @@ type ContractCampaign =
       rep?: number;
       meta?: Record<string, unknown>;
       arcStage?: CampaignArcStage | null;
+      clockHeat?: number;
       /** Remembered combat locations the Curator may steer revisits toward (P2.5.M7.2). */
       siteRoster?: LocationSite[];
     }
@@ -540,6 +541,11 @@ export class Curator extends Entity {
     const revisitedSiteIds = new Set<string>();
     const context = contractRecipeContext(campaign);
     const roster = campaign?.siteRoster ?? [];
+    const scoreTarget = scoreTargetForArcBoard(roster);
+    const revisitRoster = scoreTarget ? roster.filter(site => site.id !== scoreTarget.id) : roster;
+    const biasedSlots =
+      scoreTarget && scoreTarget.principal ? biasedBoardSlots(context.arcStage) : 0;
+    const heat = campaignClockHeat(campaign);
 
     for (let i = 0; i < CONTRACTS_PER_VISIT; i++) {
       const difficulty = rng.pick([...pool]);
@@ -553,9 +559,14 @@ export class Curator extends Entity {
       // unchanged (no extra rng draws) and pre-P2.5.M7.2 determinism holds.
       let revisitSite: LocationSite | undefined;
       let built: RenderedContract | undefined;
+      let builtFreshBias = false;
       let seed: number;
-      if (roster.length > 0 && rng.chance(SITE_REVISIT_CHANCE)) {
-        const candidate = rng.pick(roster);
+      if (i < biasedSlots && scoreTarget) {
+        built = generatePrincipalBiasedContract(rng, labelsUsed, context, scoreTarget) ?? undefined;
+        builtFreshBias = !!built;
+      }
+      if (!built && revisitRoster.length > 0 && rng.chance(SITE_REVISIT_CHANCE)) {
+        const candidate = rng.pick(revisitRoster);
         // Pinnable only if it carries identity tokens and isn't already on this
         // board. Otherwise fall through to a fresh contract.
         if (candidate.principal && !revisitedSiteIds.has(candidate.id)) {
@@ -569,6 +580,8 @@ export class Curator extends Entity {
       if (!built) {
         built = generateRecipeContract(rng, labelsUsed, context);
         seed = rng.intRange(0, 0x7fffffff);
+      } else if (builtFreshBias) {
+        seed = rng.intRange(0, 0x7fffffff);
       } else {
         seed = siteSeedToContractSeed(revisitSite!);
       }
@@ -588,7 +601,7 @@ export class Curator extends Entity {
         mapHeight: dimensions.height,
         objective: applyDoorRoutingToObjective(built.objective, difficulty),
         difficulty,
-        threatCount: spec.threatCount,
+        threatCount: applyHeatToThreat(spec.threatCount, difficulty, heat),
         label: built.label,
         context: revisitSite ? { ...built.context, locationSiteId: revisitSite.id } : built.context,
         reward,
@@ -1023,6 +1036,56 @@ function generateRevisitContract(
   return null;
 }
 
+function generatePrincipalBiasedContract(
+  rng: Rng,
+  labelsUsed: Set<string>,
+  context: ContractRecipeContext,
+  scoreTarget: LocationSite
+): RenderedContract | null {
+  if (!scoreTarget.principal) return null;
+  const principal = lexiconTokenFrom(scoreTarget.principal);
+  const avoidedSiteId = scoreTarget.site?.id;
+  const candidates = CONTRACT_RECIPES.filter(recipe =>
+    groupsIntersect(principal.groups, recipe.principalGroups)
+  );
+  if (candidates.length === 0) return null;
+
+  for (let i = 0; i < MAX_UNIQUE_CONTRACT_ATTEMPTS; i++) {
+    const recipe = rng.pick(candidates);
+    const site = recipe.siteGroups
+      ? pickCompatibleTokenAvoiding(
+          rng,
+          CONTRACT_LEXICON.sites,
+          recipe.siteGroups,
+          avoidedSiteId,
+          recipe.id
+        )
+      : undefined;
+    const siteState = recipe.siteStateGroups
+      ? pickCompatibleToken(rng, CONTRACT_LEXICON.siteStates, recipe.siteStateGroups, recipe.id)
+      : undefined;
+    const asset = pickCompatibleToken(rng, CONTRACT_LEXICON.assets, recipe.assetGroups, recipe.id);
+    const action = pickCompatibleToken(
+      rng,
+      CONTRACT_LEXICON.actions,
+      recipe.actionGroups,
+      recipe.id
+    );
+    const tokens = {
+      principal,
+      ...(site ? { site } : {}),
+      ...(siteState ? { siteState } : {}),
+      asset,
+      action,
+    };
+    const contract = buildContractFromRecipe(recipe, tokens, context);
+    if (labelsUsed.has(contract.label)) continue;
+    labelsUsed.add(contract.label);
+    return contract;
+  }
+  return null;
+}
+
 /**
  * Contract label: `// <principal> <site> - <state?> <asset> <action>`.
  * Site is omitted when the recipe has no site token; transient site state
@@ -1048,6 +1111,61 @@ function groupsIntersect(groups: readonly string[], allowed: readonly string[]):
   return groups.some(group => allowed.includes(group));
 }
 
+function pickCompatibleTokenAvoiding(
+  rng: Rng,
+  tokens: readonly ContractToken[],
+  groups: readonly string[],
+  avoidId: string | undefined,
+  recipeId: string
+): ContractToken {
+  const compatible = tokens.filter(tokenValue => groupsIntersect(tokenValue.groups, groups));
+  if (compatible.length === 0) {
+    throw new Error(`Curator: recipe "${recipeId}" has no compatible token`);
+  }
+  const filtered =
+    avoidId && compatible.length > 1
+      ? compatible.filter(tokenValue => tokenValue.id !== avoidId)
+      : compatible;
+  return rng.pick(filtered.length > 0 ? filtered : compatible);
+}
+
+function scoreTargetForArcBoard(roster: readonly LocationSite[]): LocationSite | null {
+  const targets = roster.filter(site => site.scoreTarget);
+  if (targets.length > 1) {
+    throw new Error('Curator.generateContracts: multiple Score targets in site roster');
+  }
+  return targets[0] ?? null;
+}
+
+function biasedBoardSlots(arcStage: CampaignArcStage | undefined): number {
+  if (arcStage === 'act-2') return 1;
+  if (arcStage === 'act-3') return 2;
+  return 0;
+}
+
+function campaignClockHeat(campaign: ContractCampaign): number {
+  const heat = campaign?.clockHeat ?? 0;
+  if (!Number.isFinite(heat) || heat < 0) {
+    throw new RangeError(`Curator.generateContracts: clockHeat must be a non-negative number`);
+  }
+  return Math.floor(heat);
+}
+
+function applyHeatToThreat(
+  baseThreat: number,
+  difficulty: ContractDifficulty,
+  heat: number
+): number {
+  if (heat === 0) return baseThreat;
+  const cap =
+    difficulty === CONTRACT_DIFFICULTY.STANDARD
+      ? 3
+      : difficulty === CONTRACT_DIFFICULTY.ELEVATED
+        ? 5
+        : 6;
+  return Math.min(cap, baseThreat + heat);
+}
+
 function buildContractFromRecipe(
   recipe: ContractRecipe,
   tokens: ContractRecipeTokens,
diff --git a/src/game/hub/arcSurface.ts b/src/game/hub/arcSurface.ts
index 54b9c84..2fb42d6 100644
--- a/src/game/hub/arcSurface.ts
+++ b/src/game/hub/arcSurface.ts
@@ -1,10 +1,19 @@
 import type { Contract } from './Curator.js';
 import type { Campaign } from '../Campaign.js';
+import type { HubReveals } from './hubReveals.js';
+import { CLOCK_ACT2_DEADLINE_JOBS, CLOCK_ACT2_GRACE_JOBS } from '../Campaign.js';
 import type { CampaignArcStage, LocationSite } from '../../types.js';
 import type { Decker } from '../archetypes/Decker.js';
 import type { Crew } from '../Crew.js';
 
-type ArcSurfaceCampaign = Pick<Campaign, 'arc' | 'siteRoster' | 'crew'>;
+type ArcSurfaceCampaign = Pick<Campaign, 'arc' | 'siteRoster' | 'crew'> &
+  Partial<
+    Pick<Campaign, 'completedJobs' | 'clockJobsTaken' | 'clockHeat' | 'scoreDeadlineJobsRemaining'>
+  > & {
+    hubReveals?: HubReveals;
+  };
+
+export type HubArcStatusLines = readonly [summary: string, clock: string | null];
 
 const ARC_STAGE_LABELS: Record<CampaignArcStage, string> = Object.freeze({
   'act-1': 'STAGE 1: STREET LEVEL',
@@ -39,6 +48,12 @@ export function formatArcStageLabel(stage: CampaignArcStage): string {
 }
 
 export function formatHubArcStatus(campaign: ArcSurfaceCampaign): string {
+  return formatHubArcStatusLines(campaign)
+    .filter((line): line is string => line !== null)
+    .join('\n');
+}
+
+export function formatHubArcStatusLines(campaign: ArcSurfaceCampaign): HubArcStatusLines {
   const parts = [formatArcStageLabel(campaign.arc.arcStage)];
   if (campaign.arc.scoreRevealed) {
     const target = findScoreTargetSite(campaign.siteRoster);
@@ -47,7 +62,22 @@ export function formatHubArcStatus(campaign: ArcSurfaceCampaign): string {
     }
     parts.push(`SCORE: ${scoreTargetDisplayName(target)}`);
   }
-  return parts.join(' | ');
+  return [parts.join(' | '), formatClockStatus(campaign)];
+}
+
+/** Clock HUD line — only after the Curator briefing, and only while heat is active. */
+export function formatClockStatus(campaign: ArcSurfaceCampaign): string | null {
+  if (!campaign.hubReveals?.clockBriefingPresented) return null;
+  if (!campaign.arc.clockStarted) return null;
+  if (campaign.arc.scoreAttempted || campaign.arc.scoreCompleted) return null;
+
+  const clockJobsTaken = campaign.clockJobsTaken ?? 0;
+  if (clockJobsTaken >= CLOCK_ACT2_DEADLINE_JOBS) return null;
+
+  const heat = campaign.clockHeat ?? Math.max(0, clockJobsTaken - CLOCK_ACT2_GRACE_JOBS);
+  const jobsRemaining =
+    campaign.scoreDeadlineJobsRemaining ?? Math.max(0, CLOCK_ACT2_DEADLINE_JOBS - clockJobsTaken);
+  return `CLOCK: HEAT ${heat} / ${jobsRemaining} JOBS LEFT`;
 }
 
 export function scoreRevealLines(campaign: ArcSurfaceCampaign): readonly string[] {
@@ -62,11 +92,30 @@ export function scoreRevealLines(campaign: ArcSurfaceCampaign): readonly string[
   const deckerName = findDecker(campaign.crew).callsign;
   return [
     `CURATOR: We found it: ${targetName}. The Score has a door.`,
-    'CURATOR: Contracts touching that site are casing work now. Watch for SCORE SITE on the board.',
+    'CURATOR: Jobs tagged CASING on the board hit the Score org — take those to learn the target.',
     `CURATOR: You'll need a Decker to crack the ICE; I've got ${deckerName} for you.`,
   ];
 }
 
+export function clockRevealLines(campaign: ArcSurfaceCampaign): readonly string[] {
+  if (!campaign.arc.clockStarted) {
+    throw new Error('arcSurface: cannot build Clock reveal copy before clockStarted');
+  }
+  const principal = scorePrincipalLabel(campaign);
+  return [
+    'CURATOR: The Score window is live — corp security is tracking the org.',
+    `CURATOR: Every job you take from here adds heat: more hostiles, tighter alarms.`,
+    `CURATOR: Run ${principal} before the window closes or the contract goes cold.`,
+  ];
+}
+
+export function act3RevealLines(): readonly string[] {
+  return [
+    "CURATOR: You're ready. Our window is open, but it's tight.",
+    'CURATOR: Do your final prep, watch your heat, and grab THE SCORE from the board while you can.',
+  ];
+}
+
 export function findDecker(crew: readonly Crew[]): Decker {
   const decker = crew.find(crew => crew.archetype === 'Decker');
   if (!decker) {
@@ -82,10 +131,33 @@ export function isScoreSiteContract(
   return !!scoreTargetSiteId && contract.context.locationSiteId === scoreTargetSiteId;
 }
 
+export function isScorePrincipalContract(
+  contract: Contract,
+  scorePrincipalId: string | null | undefined,
+  scoreTargetSiteId: string | null | undefined
+): boolean {
+  if (!scorePrincipalId || contract.context.principal?.id !== scorePrincipalId) return false;
+  if (isScoreSiteContract(contract, scoreTargetSiteId)) return false;
+  if (contract.context.recipeId === 'score-final') return false;
+  return true;
+}
+
 export function scoreTargetSiteId(campaign: ArcSurfaceCampaign): string | null {
   return findScoreTargetSite(campaign.siteRoster)?.id ?? null;
 }
 
+export function scorePrincipalId(campaign: ArcSurfaceCampaign): string | null {
+  return findScoreTargetSite(campaign.siteRoster)?.principal?.id ?? null;
+}
+
+function scorePrincipalLabel(campaign: ArcSurfaceCampaign): string {
+  const target = findScoreTargetSite(campaign.siteRoster);
+  if (!target) {
+    throw new Error('arcSurface: cannot build Clock reveal copy without a Score target');
+  }
+  return cleanLabel(target.principal?.label) || scoreTargetDisplayName(target);
+}
+
 function cleanLabel(label: string | undefined): string {
   return label?.trim() ?? '';
 }
diff --git a/src/game/hub/hubReveals.ts b/src/game/hub/hubReveals.ts
index 9164840..574fff8 100644
--- a/src/game/hub/hubReveals.ts
+++ b/src/game/hub/hubReveals.ts
@@ -8,7 +8,7 @@
 
 import { REP } from '../constants.js';
 import { totalSalvage } from '../salvage.js';
-import { scoreRevealLines } from './arcSurface.js';
+import { clockRevealLines, act3RevealLines, scoreRevealLines } from './arcSurface.js';
 import type { Campaign } from '../Campaign.js';
 
 export type HubReveals = {
@@ -20,9 +20,20 @@ export type HubReveals = {
   clinicIntroduced?: boolean;
   /** Curator has presented the Phase 3 Score target reveal. */
   scoreBriefingPresented?: boolean;
+  /** Curator has explained Clock heat and the Score window deadline. */
+  clockBriefingPresented?: boolean;
+  /** Curator has presented Act 3 final prep and THE SCORE availability. */
+  act3BriefingPresented?: boolean;
 };
 
-export type HubRevealId = 'finn' | 'terminal' | 'terminal-recruit' | 'clinic' | 'score-reveal';
+export type HubRevealId =
+  | 'finn'
+  | 'terminal'
+  | 'terminal-recruit'
+  | 'clinic'
+  | 'score-reveal'
+  | 'clock-reveal'
+  | 'act-3-reveal';
 
 export type HubRevealMessage = {
   id: HubRevealId;
@@ -41,7 +52,18 @@ type HubRevealDefinition = {
 };
 
 /** Reveal flags committed when the shell dismisses the Curator briefing, not when queued. */
-const HUB_REVEAL_DEFER_FLAG_COMMIT = new Set<HubRevealId>(['score-reveal']);
+const HUB_REVEAL_DEFER_FLAG_COMMIT = new Set<HubRevealId>([
+  'score-reveal',
+  'clock-reveal',
+  'act-3-reveal',
+]);
+
+/** Arc beats checked before lower-priority Hub intros; order within this list matters. */
+const PRIORITY_HUB_REVEALS: readonly HubRevealId[] = [
+  'score-reveal',
+  'clock-reveal',
+  'act-3-reveal',
+];
 
 const HUB_REVEAL_DEFINITIONS: readonly HubRevealDefinition[] = [
   {
@@ -65,6 +87,28 @@ const HUB_REVEAL_DEFINITIONS: readonly HubRevealDefinition[] = [
     },
     lines: scoreRevealLines,
   },
+  {
+    id: 'clock-reveal',
+    flag: 'clockBriefingPresented',
+    title: '── THE CLOCK ──',
+    qualifies(campaign) {
+      return (
+        campaign.arc.clockStarted &&
+        !!campaign.hubReveals.scoreBriefingPresented &&
+        !campaign.hubReveals.clockBriefingPresented
+      );
+    },
+    lines: clockRevealLines,
+  },
+  {
+    id: 'act-3-reveal',
+    flag: 'act3BriefingPresented',
+    title: '── FINAL PREP / THE SCORE ──',
+    qualifies(campaign) {
+      return !!campaign.hubReveals.scoreBriefingPresented && campaign.canAttemptScore();
+    },
+    lines: act3RevealLines,
+  },
   {
     id: 'finn',
     flag: 'finnIntroduced',
@@ -122,6 +166,8 @@ export function normalizeHubReveals(raw: unknown, context = 'hubReveals'): HubRe
     'terminalRecruitmentExplained',
     'clinicIntroduced',
     'scoreBriefingPresented',
+    'clockBriefingPresented',
+    'act3BriefingPresented',
   ] as const) {
     if (record[key] === undefined) continue;
     if (typeof record[key] !== 'boolean') {
@@ -165,6 +211,8 @@ export function snapshotHubReveals(reveals: HubReveals): HubReveals {
   if (reveals.terminalExplained) out.terminalExplained = true;
   if (reveals.clinicIntroduced) out.clinicIntroduced = true;
   if (reveals.scoreBriefingPresented) out.scoreBriefingPresented = true;
+  if (reveals.clockBriefingPresented) out.clockBriefingPresented = true;
+  if (reveals.act3BriefingPresented) out.act3BriefingPresented = true;
   return out;
 }
 
@@ -212,21 +260,18 @@ export function commitHubReveal(campaign: Campaign, id: HubRevealId): void {
 /**
  * Evaluate reveal triggers in definition order. Sets the first qualifying
  * unseen flag on `campaign.hubReveals` and returns its message. Does not persist.
- * Score reveal is checked first so Act 2 openings are not crowded out by lower
- * priority intros on the same visit. Score briefing flags commit on dismiss.
+ * Score and Clock reveals are checked first so arc beats are not crowded out by
+ * lower-priority intros on the same visit. Their briefing flags commit on dismiss.
  */
 export function applyFirstHubReveal(campaign: Campaign): HubRevealMessage | null {
-  const scoreReveal = HUB_REVEAL_DEFINITIONS.find(def => def.id === 'score-reveal');
-  if (scoreReveal && !campaign.hubReveals[scoreReveal.flag] && scoreReveal.qualifies(campaign)) {
-    return buildHubRevealMessage(
-      scoreReveal,
-      campaign,
-      !HUB_REVEAL_DEFER_FLAG_COMMIT.has(scoreReveal.id)
-    );
+  for (const id of PRIORITY_HUB_REVEALS) {
+    const def = HUB_REVEAL_DEFINITIONS.find(entry => entry.id === id);
+    if (!def || campaign.hubReveals[def.flag] || !def.qualifies(campaign)) continue;
+    return buildHubRevealMessage(def, campaign, !HUB_REVEAL_DEFER_FLAG_COMMIT.has(def.id));
   }
 
   for (const def of HUB_REVEAL_DEFINITIONS) {
-    if (def.id === 'score-reveal') continue;
+    if (PRIORITY_HUB_REVEALS.includes(def.id)) continue;
     if (campaign.hubReveals[def.flag]) continue;
     if (!def.qualifies(campaign)) continue;
     return buildHubRevealMessage(def, campaign, true);
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index b6350e1..d22e937 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -771,6 +771,8 @@ export type CampaignSnapshot = {
   hubReveals?: HubRevealsSnapshot;
   /** Count of completed jobs. Abort extractions do not increment this arc counter. */
   completedJobs?: number;
+  /** Act-2/3 deploys that drive Clock heat. Defaults to 0 for pre-P3.M1.5 saves. */
+  clockJobsTaken?: number;
   /** Persistent key-item inventory (keycards). Defaults to [] for pre-P2.5.M6.2 saves. */
   keyItems?: KeyItemSnapshot[];
   /** Remembered combat locations (site roster). Defaults to [] for pre-P2.5.M7.2 saves. */
@@ -792,6 +794,8 @@ export type HubRevealsSnapshot = {
   terminalRecruitmentExplained?: boolean;
   clinicIntroduced?: boolean;
   scoreBriefingPresented?: boolean;
+  clockBriefingPresented?: boolean;
+  act3BriefingPresented?: boolean;
 };
 
 /**
@@ -831,6 +835,7 @@ export function snapshotCampaign(campaign: Campaign): CampaignSnapshot {
     healedThisVisit: [...campaign.healedThisVisit],
     hubReveals: snapshotHubReveals(campaign.hubReveals),
     completedJobs: campaign.completedJobs,
+    clockJobsTaken: campaign.clockJobsTaken,
     keyItems: campaign.keyItems.map(k => ({ ...k })),
     siteRoster: campaign.siteRoster.map(snapshotLocationSite),
   };
@@ -976,6 +981,7 @@ export function restoreCampaign(record: unknown, options: RestoreCampaignOptions
       'restoreCampaign hubReveals'
     ),
     completedJobs: record.completedJobs ?? 0,
+    clockJobsTaken: record.clockJobsTaken ?? 0,
     keyItems: record.keyItems,
     siteRoster: record.siteRoster,
     onPersist: options.onPersist,
@@ -1649,6 +1655,11 @@ function validateCampaignRecord(record: unknown): asserts record is CampaignSnap
       throw new RangeError('restoreCampaign: completedJobs must be a non-negative integer');
     }
   }
+  if (candidate.clockJobsTaken !== undefined) {
+    if (!Number.isInteger(candidate.clockJobsTaken) || candidate.clockJobsTaken < 0) {
+      throw new RangeError('restoreCampaign: clockJobsTaken must be a non-negative integer');
+    }
+  }
   if (candidate.siteRoster !== undefined) {
     if (!Array.isArray(candidate.siteRoster)) {
       throw new TypeError('restoreCampaign: siteRoster must be an array when present');
diff --git a/src/types.ts b/src/types.ts
index e70c2c5..bc297a7 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -16,6 +16,9 @@ export type GridPoint = { x: number; y: number };
 /** Phase 3 campaign arc stage, shared by Campaign saves and Curator contract context. */
 export type CampaignArcStage = 'act-1' | 'act-2' | 'act-3' | 'score';
 
+/** Why a campaign reached `ENDED` — drives terminal debrief copy in the shell. */
+export type CampaignEndReason = 'crew-wipe' | 'clock-expired' | 'score-complete';
+
 /**
  * A JSON-safe value. The persistence layer's opaque entity property bag
  * (`EntitySnapshotExtra`) is keyed to this so anything stashed in a snapshot
@@ -240,6 +243,7 @@ export type LocationSite = {
 
 export type Telemetry = {
   outcome: 'death' | 'exit' | 'campaign-over';
+  campaignEndReason?: CampaignEndReason;
   campaignTerminal?: boolean;
   crewRoster?: { callsign: string; archetype: string; flatlined: boolean }[];
   /** Typed-salvage wallet snapshot at the moment the run/campaign ends. */
diff --git a/sw-dev.js b/sw-dev.js
index d3b5b9d..25811e2 100644
--- a/sw-dev.js
+++ b/sw-dev.js
@@ -1,5 +1,5 @@
 // Service Worker for Kernel Panic - Development Version
-const VERSION = '0.2.10-dev';
+const VERSION = '0.2.11-dev';
 importScripts(`/sw-core.js?v=${VERSION}`);
 
 const cacheConfig = CacheConfig.create(VERSION);
diff --git a/tests/unit/game/Campaign.test.ts b/tests/unit/game/Campaign.test.ts
index 586a08b..99e1390 100644
--- a/tests/unit/game/Campaign.test.ts
+++ b/tests/unit/game/Campaign.test.ts
@@ -4,6 +4,8 @@ import assert from 'node:assert/strict';
 import {
   Campaign,
   CAMPAIGN_STATE,
+  CLOCK_ACT2_DEADLINE_JOBS,
+  CLOCK_ACT2_GRACE_JOBS,
   SITE_ROSTER_CAP,
   buildCrew,
   defaultCampaignArc,
@@ -13,7 +15,12 @@ import { OUTCOME, RUN_STATE } from '../../../src/game/Run.js';
 import { Rng } from '../../../src/rng.js';
 import { OBJECTIVES } from '../../../src/game/hub/Curator.js';
 import { snapshotCampaign, restoreCampaign } from '../../../src/game/persistence.js';
-import { SALVAGE_SELL_RATE, SHOP_COST, TILE } from '../../../src/game/constants.js';
+import {
+  CONTRACT_DIFFICULTY,
+  SALVAGE_SELL_RATE,
+  SHOP_COST,
+  TILE,
+} from '../../../src/game/constants.js';
 import { emptySalvage, makeSalvage, totalSalvage } from '../../../src/game/salvage.js';
 import { testContractContext } from './contractTestUtils.js';
 import { buildCrewMember } from '../../../src/game/archetypes/index.js';
@@ -936,6 +943,165 @@ test('P3.M1.3: multiple persisted Score targets crash instead of being normalize
   );
 });
 
+test('P3.M1.5: Clock ignores completedJobs until act-2/3 deploys cross grace', () => {
+  const freshAct2 = new Campaign({ seed: 42, rep: 60, completedJobs: 9 });
+  assert.equal(freshAct2.arc.clockStarted, false);
+  assert.equal(freshAct2.clockHeat, 0);
+  assert.equal(freshAct2.scoreDeadlineJobsRemaining, CLOCK_ACT2_DEADLINE_JOBS);
+
+  const heating = new Campaign({
+    seed: 42,
+    rep: 60,
+    completedJobs: 9,
+    clockJobsTaken: CLOCK_ACT2_GRACE_JOBS + 2,
+  });
+  assert.equal(heating.arc.clockStarted, true);
+  assert.equal(heating.clockHeat, 2);
+  assert.equal(
+    heating.scoreDeadlineJobsRemaining,
+    CLOCK_ACT2_DEADLINE_JOBS - heating.clockJobsTaken
+  );
+  assert.equal(heating.state, CAMPAIGN_STATE.HUB);
+
+  const expired = new Campaign({
+    seed: 43,
+    rep: 60,
+    completedJobs: 4,
+    clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS,
+  });
+  assert.equal(expired.clockHeat, CLOCK_ACT2_DEADLINE_JOBS - CLOCK_ACT2_GRACE_JOBS);
+  assert.equal(expired.arc.clockStarted, true);
+  assert.equal(expired.state, CAMPAIGN_STATE.ENDED);
+  assert.equal(expired.endReason, 'clock-expired');
+});
+
+test('P3.M1.5: endReason distinguishes score win, clock loss, and crew wipe', () => {
+  const clockLoss = new Campaign({
+    seed: 43,
+    rep: 60,
+    completedJobs: 4,
+    clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS,
+  });
+  assert.equal(clockLoss.endReason, 'clock-expired');
+
+  const scoreWin = new Campaign({
+    seed: 44,
+    rep: 60,
+    completedJobs: 4,
+    arc: {
+      arcStage: 'score',
+      deckerRecruited: true,
+      scoreRevealed: true,
+      clockStarted: true,
+      scoreAttempted: true,
+      scoreCompleted: true,
+    },
+    siteRoster: [
+      validSite({ id: 'score', seed: '100', tier: 'score', scoreTarget: true, lastVisitedJob: 5 }),
+    ],
+  });
+  scoreWin.state = CAMPAIGN_STATE.ENDED;
+  assert.equal(scoreWin.endReason, 'score-complete');
+
+  const crewWipe = new Campaign({
+    seed: 45,
+    rep: 60,
+    completedJobs: 2,
+  });
+  crewWipe.crew.forEach(member => {
+    member.flatlined = true;
+  });
+  crewWipe.state = CAMPAIGN_STATE.ENDED;
+  assert.equal(crewWipe.endReason, 'crew-wipe');
+});
+
+test('P3.M1.5: Clock deadline does not end the campaign after the Score is attempted', () => {
+  const campaign = new Campaign({
+    seed: 42,
+    rep: 60,
+    completedJobs: 4,
+    clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS,
+    arc: {
+      arcStage: 'score',
+      deckerRecruited: true,
+      scoreRevealed: true,
+      clockStarted: true,
+      scoreAttempted: true,
+      scoreCompleted: false,
+    },
+    siteRoster: [
+      validSite({ id: 'score', seed: '100', tier: 'score', scoreTarget: true, lastVisitedJob: 5 }),
+    ],
+  });
+
+  assert.equal(campaign.state, CAMPAIGN_STATE.HUB);
+  assert.equal(campaign.clockHeat, CLOCK_ACT2_DEADLINE_JOBS - CLOCK_ACT2_GRACE_JOBS);
+});
+
+test('P3.M1.7: Score contract is gated to Act 3 and marks attempted on deployment', () => {
+  const scorePrincipal = { id: 'matsuda', label: 'Matsuda', groups: ['corp'] };
+  const campaign = new Campaign({
+    seed: 42,
+    rep: 60,
+    completedJobs: 9,
+    siteRoster: [
+      validSite({
+        id: 'score',
+        seed: '100',
+        tier: 'score',
+        scoreTarget: true,
+        lastVisitedJob: 5,
+        principal: scorePrincipal,
+        site: { id: 'server-farm', label: 'server farm', groups: ['corp', 'data'] },
+      }),
+      validSite({ id: 'case-1', seed: '101', lastVisitedJob: 6, principal: scorePrincipal }),
+      validSite({ id: 'case-2', seed: '102', lastVisitedJob: 7, principal: scorePrincipal }),
+    ],
+  });
+  assert.equal(campaign.arcStage, 'act-3');
+  assert.equal(campaign.canAttemptScore(), true);
+
+  const score = campaign.buildScoreContract();
+  assert.equal(score.difficulty, CONTRACT_DIFFICULTY.CRITICAL);
+  assert.equal(score.context.locationSiteId, 'score');
+  assert.ok(score.context.tags.includes('score'));
+  assert.match(score.label, /THE SCORE/);
+
+  const run = campaign.deployCrewMember(campaign.crew[0]!.id, score);
+  assert.equal(campaign.arc.scoreAttempted, true);
+  assert.equal(campaign.arcStage, 'score');
+  assert.equal(run.contract?.context.locationSiteId, 'score');
+});
+
+test('P3.M1.7: completed Score contract records campaign win state', () => {
+  const scorePrincipal = { id: 'matsuda', label: 'Matsuda', groups: ['corp'] };
+  const campaign = new Campaign({
+    seed: 42,
+    rep: 60,
+    completedJobs: 9,
+    siteRoster: [
+      validSite({
+        id: 'score',
+        seed: '100',
+        tier: 'score',
+        scoreTarget: true,
+        lastVisitedJob: 5,
+        principal: scorePrincipal,
+        site: { id: 'server-farm', label: 'server farm', groups: ['corp', 'data'] },
+      }),
+      validSite({ id: 'case-1', seed: '101', lastVisitedJob: 6, principal: scorePrincipal }),
+      validSite({ id: 'case-2', seed: '102', lastVisitedJob: 7, principal: scorePrincipal }),
+    ],
+  });
+  const run = campaign.deployCrewMember(campaign.crew[0]!.id, campaign.buildScoreContract());
+  run.enterCombat();
+
+  campaign.onJobEnd({ outcome: OUTCOME.EXIT, completed: true });
+
+  assert.equal(campaign.arc.scoreCompleted, true);
+  assert.equal(campaign.state, CAMPAIGN_STATE.ENDED);
+});
+
 // ─── Recruitment ────────────────────────────────────────────────────────
 
 test('generateRecruits returns 1–2 candidates when Rep ≥ 65', () => {
diff --git a/tests/unit/game/hub/Curator.test.ts b/tests/unit/game/hub/Curator.test.ts
index 27e3d9a..b3a6c60 100644
--- a/tests/unit/game/hub/Curator.test.ts
+++ b/tests/unit/game/hub/Curator.test.ts
@@ -314,6 +314,86 @@ test('same seed plus same arc stage yields identical recipe contracts', () => {
   }
 });
 
+test('P3.M1.5: campaign Clock heat raises threat counts without changing difficulty', () => {
+  const baseline = new Curator().generateContracts(new Rng(999), { rep: 60, clockHeat: 0 });
+  const heated = new Curator().generateContracts(new Rng(999), { rep: 60, clockHeat: 2 });
+
+  assert.deepEqual(
+    heated.map(contract => contract.difficulty),
+    baseline.map(contract => contract.difficulty)
+  );
+  assert.ok(
+    heated.some((contract, index) => contract.threatCount > baseline[index]!.threatCount),
+    'expected at least one board slot to gain heat pressure'
+  );
+});
+
+test('P3.M1.6: Act 2 guarantees at least one same-principal casing contract', () => {
+  const roster = [
+    {
+      id: 'score',
+      seed: '100',
+      mapWidth: 32,
+      mapHeight: 20,
+      label: '// Matsuda server farm - Score target',
+      tier: 'score',
+      scoreTarget: true,
+      mutationDeltas: [],
+      seenKeys: [],
+      lastVisitedJob: 0,
+      principal: { id: 'matsuda', label: 'Matsuda', groups: ['corp', 'finance'] },
+      site: { id: 'server-farm', label: 'server farm', groups: ['corp', 'data'] },
+    },
+  ];
+
+  const contracts = new Curator().generateContracts(new Rng(777), {
+    rep: 60,
+    arcStage: 'act-2',
+    siteRoster: roster,
+  });
+
+  assert.equal(contracts.length, 3);
+  assert.ok(
+    contracts.some(contract => contract.context.principal.id === 'matsuda'),
+    'Act 2 board should include a same-principal casing job'
+  );
+  assert.ok(
+    contracts.every(contract => contract.context.locationSiteId !== 'score'),
+    'normal board should not roll the Score target as the final job'
+  );
+});
+
+test('P3.M1.6: Act 3 board is mostly same-principal prep contracts', () => {
+  const roster = [
+    {
+      id: 'score',
+      seed: '100',
+      mapWidth: 32,
+      mapHeight: 20,
+      label: '// Matsuda server farm - Score target',
+      tier: 'score',
+      scoreTarget: true,
+      mutationDeltas: [],
+      seenKeys: [],
+      lastVisitedJob: 5,
+      principal: { id: 'matsuda', label: 'Matsuda', groups: ['corp', 'finance'] },
+      site: { id: 'server-farm', label: 'server farm', groups: ['corp', 'data'] },
+    },
+  ];
+
+  const contracts = new Curator().generateContracts(new Rng(888), {
+    rep: 80,
+    arcStage: 'act-3',
+    siteRoster: roster,
+  });
+
+  assert.ok(
+    contracts.filter(contract => contract.context.principal.id === 'matsuda').length >= 2,
+    'Act 3 board should be mostly Score-principal prep'
+  );
+  assert.ok(contracts.every(contract => contract.context.locationSiteId !== 'score'));
+});
+
 test('different seeds vary compatible recipe output', () => {
   const labels = new Set<string>();
   for (let seed = 0; seed < 8; seed++) {
diff --git a/tests/unit/game/hub/arcSurface.test.ts b/tests/unit/game/hub/arcSurface.test.ts
index 670ba29..452608e 100644
--- a/tests/unit/game/hub/arcSurface.test.ts
+++ b/tests/unit/game/hub/arcSurface.test.ts
@@ -4,10 +4,14 @@ import assert from 'node:assert/strict';
 import { CONTRACT_DIFFICULTY } from '../../../../src/game/constants.js';
 import { buildContractRecipeFixture } from '../../../../src/game/hub/Curator.js';
 import {
+  act3RevealLines,
   findDecker,
   findScoreTargetSite,
   formatArcStageLabel,
+  formatClockStatus,
   formatHubArcStatus,
+  formatHubArcStatusLines,
+  isScorePrincipalContract,
   isScoreSiteContract,
   scoreRevealLines,
   scoreTargetDisplayName,
@@ -15,6 +19,7 @@ import {
 } from '../../../../src/game/hub/arcSurface.js';
 import { Decker } from '../../../../src/game/archetypes/Decker.js';
 import { Merc } from '../../../../src/game/archetypes/Merc.js';
+import { CLOCK_ACT2_DEADLINE_JOBS, CLOCK_ACT2_GRACE_JOBS } from '../../../../src/game/Campaign.js';
 import type { CampaignArc } from '../../../../src/game/Campaign.js';
 import type { LocationSite, LocationToken } from '../../../../src/types.js';
 
@@ -55,25 +60,101 @@ function scoreSite(overrides: Partial<LocationSite> = {}): LocationSite {
   };
 }
 
-test('formatHubArcStatus shows act label and Score target once revealed', () => {
+test('formatHubArcStatusLines omits clock until the Curator briefing is dismissed', () => {
   const campaign = {
-    arc: arc({ arcStage: 'act-2', scoreRevealed: true }),
+    arc: arc({ arcStage: 'act-2', scoreRevealed: true, clockStarted: true }),
     siteRoster: [scoreSite()],
+    crew: [],
+    hubReveals: {},
+    clockJobsTaken: CLOCK_ACT2_GRACE_JOBS + 1,
+    clockHeat: 1,
+    scoreDeadlineJobsRemaining: 4,
   };
+  assert.deepEqual(formatHubArcStatusLines(campaign), [
+    'STAGE 2: CASING | SCORE: Matsuda server farm',
+    null,
+  ]);
   assert.equal(formatHubArcStatus(campaign), 'STAGE 2: CASING | SCORE: Matsuda server farm');
 });
 
+test('formatHubArcStatusLines shows active heat only after clock briefing', () => {
+  const campaign = {
+    arc: arc({ arcStage: 'act-2', scoreRevealed: true, clockStarted: true }),
+    siteRoster: [scoreSite()],
+    crew: [],
+    hubReveals: { clockBriefingPresented: true },
+    clockJobsTaken: CLOCK_ACT2_GRACE_JOBS + 2,
+    clockHeat: 2,
+    scoreDeadlineJobsRemaining: 3,
+  };
+  assert.deepEqual(formatHubArcStatusLines(campaign), [
+    'STAGE 2: CASING | SCORE: Matsuda server farm',
+    'CLOCK: HEAT 2 / 3 JOBS LEFT',
+  ]);
+});
+
 test('formatHubArcStatus throws when revealed state has no Score target', () => {
   assert.throws(
     () =>
       formatHubArcStatus({
         arc: arc({ arcStage: 'act-2', scoreRevealed: true }),
         siteRoster: [],
+        crew: [],
       }),
     /score revealed without a Score target/i
   );
 });
 
+test('formatClockStatus stays hidden before briefing, during grace, and after deadline', () => {
+  assert.equal(
+    formatClockStatus({
+      arc: arc({ scoreRevealed: true }),
+      siteRoster: [scoreSite()],
+      crew: [],
+      hubReveals: {},
+      clockJobsTaken: 1,
+    }),
+    null
+  );
+  assert.equal(
+    formatClockStatus({
+      arc: arc({ scoreRevealed: true, clockStarted: false }),
+      siteRoster: [scoreSite()],
+      crew: [],
+      hubReveals: { clockBriefingPresented: true },
+      clockJobsTaken: 1,
+    }),
+    null
+  );
+  assert.equal(
+    formatClockStatus({
+      arc: arc({ scoreRevealed: true, clockStarted: true, scoreAttempted: true }),
+      siteRoster: [scoreSite()],
+      crew: [],
+      hubReveals: { clockBriefingPresented: true },
+      clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS,
+    }),
+    null
+  );
+  assert.equal(
+    formatClockStatus({
+      arc: arc({ scoreRevealed: true, clockStarted: true }),
+      siteRoster: [scoreSite()],
+      crew: [],
+      hubReveals: { clockBriefingPresented: true },
+      clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS,
+    }),
+    null
+  );
+});
+
+test('act3 reveal copy points at THE SCORE on the job board', () => {
+  const lines = act3RevealLines();
+  assert.match(lines.join('\n'), /You're ready/i);
+  assert.match(lines.join('\n'), /THE SCORE/i);
+  assert.match(lines.join('\n'), /heat/i);
+});
+
 test('Score target helpers reject multiple targets instead of guessing', () => {
   const sites = [scoreSite({ id: 'a' }), scoreSite({ id: 'b' })];
   assert.throws(() => findScoreTargetSite(sites), /multiple Score targets/i);
@@ -87,7 +168,7 @@ test('score reveal copy names the target and points at job-board badges', () =>
     crew: [new Decker({ id: 'decker', x: 0, y: 0, callsign: 'Case' })],
   });
   assert.match(lines.join('\n'), /Matsuda server farm/);
-  assert.match(lines.join('\n'), /SCORE SITE/);
+  assert.match(lines.join('\n'), /CASING/);
   assert.match(lines.join('\n'), /Case/);
 });
 
@@ -118,17 +199,28 @@ test('isScoreSiteContract matches contract locationSiteId to the Score target id
 
   assert.equal(isScoreSiteContract(contract, 'score-site'), true);
   assert.equal(isScoreSiteContract(contract, 'other-site'), false);
-  assert.equal(isScoreSiteContract(contract, null), false);
 });
 
-test('findDecker throws when no Decker is present', () => {
-  const merc = new Merc({ id: 'merc', x: 0, y: 0, callsign: 'Glitch' });
-  assert.throws(() => findDecker([merc]), /without a Decker/i);
-  assert.throws(() => findDecker([]), /without a Decker/i);
+test('isScorePrincipalContract matches same-principal jobs but not the Score site', () => {
+  const contract = buildContractRecipeFixture({
+    recipeId: 'terminal-slice',
+    principalId: 'matsuda',
+    siteId: 'server-farm',
+    assetId: 'identity-spool',
+    actionId: 'slice',
+    difficulty: CONTRACT_DIFFICULTY.STANDARD,
+    seed: 11,
+  });
+  contract.context.locationSiteId = 'case-site';
+
+  assert.equal(isScorePrincipalContract(contract, 'matsuda', 'score-site'), true);
+  contract.context.locationSiteId = 'score-site';
+  assert.equal(isScorePrincipalContract(contract, 'matsuda', 'score-site'), false);
 });
 
-test('findDecker returns the Decker when one is present', () => {
-  const decker = new Decker({ id: 'decker', x: 0, y: 0, callsign: 'Case' });
-  const crew = [new Merc({ id: 'merc', x: 1, y: 1, callsign: 'Glitch' }), decker];
-  assert.equal(findDecker(crew), decker);
+test('findDecker throws when crew has no Decker', () => {
+  assert.throws(
+    () => findDecker([new Merc({ id: 'merc', x: 0, y: 0, callsign: 'Wraith' })]),
+    /without a Decker/i
+  );
 });
diff --git a/tests/unit/game/hub/hubReveals.test.ts b/tests/unit/game/hub/hubReveals.test.ts
index 5af2164..584d071 100644
--- a/tests/unit/game/hub/hubReveals.test.ts
+++ b/tests/unit/game/hub/hubReveals.test.ts
@@ -1,7 +1,7 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 
-import { Campaign } from '../../../../src/game/Campaign.js';
+import { Campaign, CLOCK_ACT2_GRACE_JOBS } from '../../../../src/game/Campaign.js';
 import { REP } from '../../../../src/game/constants.js';
 import { OUTCOME } from '../../../../src/game/Run.js';
 import {
@@ -28,6 +28,7 @@ function hubCampaign(
     rep?: number;
     hubReveals?: Record<string, boolean>;
     completedJobs?: number;
+    clockJobsTaken?: number;
   } = {}
 ) {
   const campaign = new Campaign({
@@ -37,6 +38,7 @@ function hubCampaign(
     rep: opts.rep ?? REP.START,
     hubReveals: opts.hubReveals,
     completedJobs: opts.completedJobs,
+    clockJobsTaken: opts.clockJobsTaken,
   });
   return campaign;
 }
@@ -143,7 +145,7 @@ test('Score reveal presents the target and assigns a Decker when Act 2 opens', (
   assert.equal(campaign.hubReveals.scoreBriefingPresented, undefined);
   assert.ok(hubRevealCommitsOnDismiss('score-reveal'));
   const revealText = campaign.lastHubReveal?.lines.join('\n') ?? '';
-  assert.match(revealText, /SCORE SITE/);
+  assert.match(revealText, /CASING/);
   assert.match(revealText, /Decker/);
 
   // Decker was assigned as part of the same transition beat
@@ -159,6 +161,106 @@ test('Score reveal presents the target and assigns a Decker when Act 2 opens', (
   assert.equal(campaign.lastHubReveal, null);
 });
 
+test('Clock reveal fires after grace deploys once Score briefing was dismissed', () => {
+  const campaign = hubCampaign({
+    rep: 60,
+    completedJobs: 4,
+    clockJobsTaken: CLOCK_ACT2_GRACE_JOBS,
+    hubReveals: {
+      terminalExplained: true,
+      finnIntroduced: true,
+      clinicIntroduced: true,
+      terminalRecruitmentExplained: true,
+      scoreBriefingPresented: true,
+    },
+  });
+  assert.equal(campaign.arc.clockStarted, true);
+  assert.equal(campaign.lastHubReveal?.id, 'clock-reveal');
+  assert.equal(campaign.hubReveals.clockBriefingPresented, undefined);
+  assert.ok(hubRevealCommitsOnDismiss('clock-reveal'));
+  const revealText = campaign.lastHubReveal?.lines.join('\n') ?? '';
+  assert.match(revealText, /heat/i);
+  assert.match(revealText, /window closes/i);
+
+  commitHubReveal(campaign, 'clock-reveal');
+  assert.equal(campaign.hubReveals.clockBriefingPresented, true);
+  campaign.enterHub();
+  assert.equal(campaign.lastHubReveal, null);
+});
+
+test('Act 3 reveal presents THE SCORE when final prep unlocks', () => {
+  const scorePrincipal = { id: 'matsuda', label: 'Matsuda', groups: ['corp'] as const };
+  const campaign = new Campaign({
+    seed: 42,
+    rep: 60,
+    completedJobs: 9,
+    hubReveals: {
+      terminalExplained: true,
+      finnIntroduced: true,
+      clinicIntroduced: true,
+      terminalRecruitmentExplained: true,
+      scoreBriefingPresented: true,
+      clockBriefingPresented: true,
+    },
+    siteRoster: [
+      {
+        id: 'score',
+        seed: '100',
+        mapWidth: 32,
+        mapHeight: 20,
+        label: '// Matsuda server farm - Score target',
+        tier: 'score',
+        scoreTarget: true,
+        mutationDeltas: [],
+        seenKeys: [],
+        lastVisitedJob: 5,
+        principal: scorePrincipal,
+        site: { id: 'server-farm', label: 'server farm', groups: ['corp', 'data'] },
+      },
+      {
+        id: 'case-1',
+        seed: '101',
+        mapWidth: 24,
+        mapHeight: 16,
+        label: '// Matsuda case site',
+        tier: 'roster',
+        scoreTarget: false,
+        mutationDeltas: [],
+        seenKeys: [],
+        lastVisitedJob: 6,
+        principal: scorePrincipal,
+      },
+      {
+        id: 'case-2',
+        seed: '102',
+        mapWidth: 24,
+        mapHeight: 16,
+        label: '// Matsuda case site 2',
+        tier: 'roster',
+        scoreTarget: false,
+        mutationDeltas: [],
+        seenKeys: [],
+        lastVisitedJob: 7,
+        principal: scorePrincipal,
+      },
+    ],
+  });
+  assert.equal(campaign.arc.arcStage, 'act-3');
+  assert.equal(campaign.canAttemptScore(), true);
+  assert.equal(campaign.lastHubReveal?.id, 'act-3-reveal');
+  assert.equal(campaign.hubReveals.act3BriefingPresented, undefined);
+  assert.ok(hubRevealCommitsOnDismiss('act-3-reveal'));
+  const revealText = campaign.lastHubReveal?.lines.join('\n') ?? '';
+  assert.match(revealText, /You're ready/i);
+  assert.match(revealText, /THE SCORE/i);
+  assert.match(revealText, /heat/i);
+
+  commitHubReveal(campaign, 'act-3-reveal');
+  assert.equal(campaign.hubReveals.act3BriefingPresented, true);
+  campaign.enterHub();
+  assert.equal(campaign.lastHubReveal, null);
+});
+
 test('Score reveal takes priority over clinic when Act 2 opens with injured crew', () => {
   const campaign = hubCampaign({
     rep: 60,

From 660fd02385d3d97fd4dd68edeaaeff884383956c Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Tue, 9 Jun 2026 20:23:40 -0700
Subject: [PATCH 10/55] dedicated GameOver component

---
 components/CrashDump.ts   | 161 +++---------------
 components/FaultScreen.ts |   4 +-
 components/GameOver.ts    | 338 ++++++++++++++++++++++++++++++++++++++
 index.html                |   1 +
 index.ts                  | 117 ++++++++++---
 main.css                  |   1 +
 src/types.ts              |  17 +-
 sw-core.js                |   1 +
 sw-dev.js                 |   2 +-
 9 files changed, 477 insertions(+), 165 deletions(-)
 create mode 100644 components/GameOver.ts

diff --git a/components/CrashDump.ts b/components/CrashDump.ts
index ebec5e2..5ec2dd8 100644
--- a/components/CrashDump.ts
+++ b/components/CrashDump.ts
@@ -1,10 +1,8 @@
 /**
- * <crash-dump> — DOM overlay shown while `Run.state === RESULT`, when
- * `Campaign.state === ENDED` (restore), or for the terminal job death that
- * wipes the crew. Renders the run's telemetry as a faux kernel-panic stack
- * trace (on DEATH) or a clean "JACK OUT" debrief (on EXIT). Campaign wipe uses
- * `outcome: 'campaign-over'` or `campaignTerminal: true` on a death payload.
- * Same component, different copy — keeps the shell's overlay count down.
+ * <crash-dump> — per-job debrief overlay shown while `Run.state === RESULT`.
+ * Renders run telemetry as a faux kernel-panic stack trace (DEATH setback) or a
+ * clean "JACK OUT" debrief (EXIT). Score-complete campaign wins reuse the green
+ * exit presentation. Terminal campaign loss uses sibling `<game-over>`.
  *
  *   *** KERNEL PANIC ***
  *   fault:  unhandled_exception_in_meatspace
@@ -19,17 +17,15 @@
  *
  * Usage:
  *   const dump = document.querySelector('crash-dump');
- *   dump.addEventListener('new-run', () => { dataStore.deleteCampaign(); startFreshCampaign(); });
- *   dump.setTelemetry({ outcome, archetype, turn, kills, cause, seed, hpAtDeath });
+ *   dump.addEventListener('new-run', () => onJobEndContinue());
+ *   dump.setTelemetry({ outcome, archetype, turn, kills, cause, seed });
  *   dump.show();
  *
  * Visual verification via the shell — same rule as <touch-pad> / <run-briefing>.
  */
 
 import { h } from '/src/domUtils.js';
-import type { Telemetry } from '/src/types.js';
-
-type CrewMemberStub = { callsign: string; archetype: string; flatlined: boolean };
+import type { GameOverCrewStub, Telemetry } from '/src/types.js';
 
 const CSS = `
 :host {
@@ -52,8 +48,7 @@ const CSS = `
   justify-content: center;
 }
 
-:host([outcome="death"]),
-:host([outcome="campaign-over"]) {
+:host([outcome="death"]) {
   --crash-accent: var(--crash-warn);
   --crash-border: var(--crash-warn);
 }
@@ -164,14 +159,6 @@ function exitTitle() {
   return '*** JACK OUT ***';
 }
 
-function campaignOverTitle() {
-  return '*** CAMPAIGN TERMINATED ***';
-}
-
-function clockExpiredTitle() {
-  return '*** WINDOW CLOSED ***';
-}
-
 function scoreCompleteTitle() {
   return '*** SCORE COMPLETE ***';
 }
@@ -186,55 +173,11 @@ function exitFault() {
   return ['status: exfil_successful', 'addr:   0x00000@meatspace', 'trace:'].join('\n');
 }
 
-function campaignOverFault() {
-  return [
-    'fault:  collective_operator_pool_exhausted',
-    'addr:   0x00000@campaign_layer',
-    'trace:',
-  ].join('\n');
-}
-
-function clockExpiredFault() {
-  return [
-    'fault:  score_operational_window_expired',
-    'addr:   0x00000@campaign_layer',
-    'trace:',
-  ].join('\n');
-}
-
 function scoreCompleteFault() {
   return ['status: score_extracted', 'addr:   0x00000@campaign_layer', 'trace:'].join('\n');
 }
 
-function campaignTerminalFault() {
-  return [
-    'notice: final_operator_channel_lost — no surviving crew',
-    'fault:  unhandled_exception_in_meatspace',
-    'addr:   0x00000@meatspace',
-    'trace:',
-  ].join('\n');
-}
-
-function buildCampaignOverTraceLines(crewRoster: CrewMemberStub[]) {
-  return crewRoster.map((op, i) => {
-    const idx = (i + 1).toString(16).padStart(2, '0');
-    const tag = op.flatlined ? '<flatlined>' : '';
-    return {
-      text: `  0x${idx}  roster::${op.callsign} (${op.archetype})`,
-      tag,
-    };
-  });
-}
-
-function buildClockExpiredTraceLines() {
-  return [
-    { text: '  0x01  arc::clock_deadline_reached()', tag: '<expired>' },
-    { text: '  0x02  curator::score_contract_cold()', tag: '' },
-    { text: '  0x03  campaign::terminate(window_closed)', tag: '' },
-  ];
-}
-
-function buildScoreCompleteTraceLines(crewRoster: CrewMemberStub[]) {
+function buildScoreCompleteTraceLines(crewRoster: GameOverCrewStub[]) {
   const survivors = crewRoster.filter(op => !op.flatlined);
   const lead = survivors[0];
   const lines = [
@@ -255,13 +198,7 @@ function buildScoreCompleteTraceLines(crewRoster: CrewMemberStub[]) {
 
 function buildTraceLines(telemetry: Telemetry) {
   if (telemetry.outcome === 'campaign-over') {
-    if (telemetry.campaignEndReason === 'clock-expired') {
-      return buildClockExpiredTraceLines();
-    }
-    if (telemetry.campaignEndReason === 'score-complete') {
-      return buildScoreCompleteTraceLines(telemetry.crewRoster ?? []);
-    }
-    return buildCampaignOverTraceLines(telemetry.crewRoster ?? []);
+    return buildScoreCompleteTraceLines(telemetry.crewRoster ?? []);
   }
 
   const archetype = telemetry.archetype ?? 'entity';
@@ -269,8 +206,6 @@ function buildTraceLines(telemetry: Telemetry) {
   const attacker = telemetry.lastAttacker ?? 'unknown';
   const killed = telemetry.outcome === 'death';
 
-  // Format: "  0xNN  module::function(arg)            <killed>"
-  // We pack synthetic stack frames so the panic reads like a real backtrace.
   const lines = [];
   if (telemetry.outcome === 'death') {
     lines.push({
@@ -286,7 +221,6 @@ function buildTraceLines(telemetry: Telemetry) {
       tag: '',
     });
   } else {
-    // EXIT: walk the player off the exit tile. Friendlier trace.
     lines.push({ text: `  0x01  ${archetype}::reach_exit()`, tag: '<ok>' });
     lines.push({ text: `  0x02  world::move_entity(${archetype})`, tag: '' });
     if (Number.isInteger(telemetry.kills) && Number(telemetry.kills) > 0) {
@@ -354,39 +288,22 @@ class CrashDump extends HTMLElement {
     if (this.#telemetry) this.#render();
   }
 
-  /**
-   * @param {{
-   *   outcome: 'death' | 'exit' | 'campaign-over',
-   *   campaignTerminal?: boolean,
-   *   crewRoster?: { callsign: string, archetype: string, flatlined: boolean }[],
-   *   salvage?: number,
-   *   archetype?: string,
-   *   turn?: number,
-   *   kills?: number,
-   *   cause?: string,
-   *   seed?: number,
-   *   hpAtDeath?: number | null,
-   *   hpAtDamage?: number | null,
-   *   lastDamageSource?: string | null,
-   *   lastAttacker?: string | null,
-   * }} telemetry
-   */
   setTelemetry(telemetry: Telemetry) {
     if (!telemetry || typeof telemetry !== 'object') {
       throw new TypeError('<crash-dump>.setTelemetry requires a telemetry object');
     }
-    const { outcome, campaignTerminal } = telemetry;
+    const { outcome } = telemetry;
     if (outcome !== 'death' && outcome !== 'exit' && outcome !== 'campaign-over') {
       throw new Error(`<crash-dump>: unknown outcome "${outcome}"`);
     }
-    if (campaignTerminal && outcome !== 'death') {
-      throw new Error('<crash-dump>: campaignTerminal is only valid with outcome "death"');
+    if (outcome === 'campaign-over' && telemetry.campaignEndReason !== 'score-complete') {
+      throw new Error('<crash-dump>: campaign-over is only valid for score-complete wins');
     }
     if (outcome === 'campaign-over' && !Array.isArray(telemetry.crewRoster)) {
-      throw new TypeError('<crash-dump>: campaign-over requires crewRoster array');
+      throw new TypeError('<crash-dump>: score-complete requires crewRoster array');
     }
     this.#telemetry = { ...telemetry };
-    this.setAttribute('outcome', outcome);
+    this.setAttribute('outcome', outcome === 'campaign-over' ? 'exit' : outcome);
     if (this.#ready) this.#render();
   }
 
@@ -408,24 +325,12 @@ class CrashDump extends HTMLElement {
   #render() {
     if (!this.#els || !this.#telemetry) return;
     const t = this.#telemetry;
-    const isCampaignOver = t.outcome === 'campaign-over';
+    const isScoreWin = t.outcome === 'campaign-over';
     const isDeath = t.outcome === 'death';
-    const isCampaignTerminalDeath = isDeath && t.campaignTerminal;
-
-    if (isCampaignOver || isCampaignTerminalDeath) {
-      if (isCampaignOver && t.campaignEndReason === 'clock-expired') {
-        this.#els.title.textContent = clockExpiredTitle();
-        this.#els.fault.textContent = clockExpiredFault();
-      } else if (isCampaignOver && t.campaignEndReason === 'score-complete') {
-        this.#els.title.textContent = scoreCompleteTitle();
-        this.#els.fault.textContent = scoreCompleteFault();
-        this.setAttribute('outcome', 'exit');
-      } else {
-        this.#els.title.textContent = campaignOverTitle();
-        this.#els.fault.textContent = isCampaignOver
-          ? campaignOverFault()
-          : campaignTerminalFault();
-      }
+
+    if (isScoreWin) {
+      this.#els.title.textContent = scoreCompleteTitle();
+      this.#els.fault.textContent = scoreCompleteFault();
     } else if (isDeath) {
       this.#els.title.textContent = deathTitle();
       this.#els.fault.textContent = deathFault();
@@ -434,11 +339,6 @@ class CrashDump extends HTMLElement {
       this.#els.fault.textContent = exitFault();
     }
 
-    const newRunLabel =
-      isCampaignOver || isCampaignTerminalDeath ? '[ NEW CAMPAIGN ]' : '[ RETURN TO HUB ]';
-    this.#els.newRunBtn.textContent = newRunLabel;
-
-    // Build trace with `<killed>` highlight.
     const lines = buildTraceLines(t);
     this.#els.trace.replaceChildren();
     lines.forEach((line, i) => {
@@ -446,12 +346,7 @@ class CrashDump extends HTMLElement {
       if (line.tag) {
         this.#els!.trace.appendChild(document.createTextNode('   '));
         const span = h('span', {
-          className:
-            line.tag.includes('killed') ||
-            line.tag.includes('flatlined') ||
-            line.tag.includes('expired')
-              ? 'killed'
-              : '',
+          className: line.tag.includes('killed') ? 'killed' : '',
           textContent: line.tag,
         });
         this.#els!.trace.appendChild(span);
@@ -462,24 +357,16 @@ class CrashDump extends HTMLElement {
     });
 
     this.#els.seedDd.textContent = hexSeed(t.seed ?? 0);
-    if (isCampaignOver) {
+    if (isScoreWin) {
       this.#els.turnDd.textContent = '—';
       this.#els.killsDd.textContent = '—';
-      if (t.campaignEndReason === 'clock-expired') {
-        this.#els.causeDd.textContent = 'Score window closed — contract cold';
-      } else if (t.campaignEndReason === 'score-complete') {
-        this.#els.causeDd.textContent = 'Score extracted — campaign complete';
-      } else {
-        this.#els.causeDd.textContent =
-          Number.isInteger(t.salvage) && Number(t.salvage) >= 0
-            ? `pool salvage ${t.salvage} (lost with run)`
-            : 'no-surviving-crew';
-      }
+      this.#els.causeDd.textContent = 'Score extracted — campaign complete';
     } else {
       this.#els.turnDd.textContent = Number.isInteger(t.turn) ? String(t.turn) : '?';
       this.#els.killsDd.textContent = Number.isInteger(t.kills) ? String(t.kills) : '0';
       this.#els.causeDd.textContent = t.cause ?? (isDeath ? 'unknown' : 'exit-reached');
     }
+    this.#els.newRunBtn.textContent = isScoreWin ? '[ NEW CAMPAIGN ]' : '[ RETURN TO HUB ]';
   }
 
   #emit(eventName: string, detail: Record<string, unknown> = {}) {
diff --git a/components/FaultScreen.ts b/components/FaultScreen.ts
index 0930fec..586ceaf 100644
--- a/components/FaultScreen.ts
+++ b/components/FaultScreen.ts
@@ -2,8 +2,8 @@
  * <fault-screen> — the top-level error boundary's user-facing surface.
  *
  * This is deliberately **non-diegetic**, and that distinction matters. The
- * sibling `<crash-dump>` is in-fiction: a faux "KERNEL PANIC" stack trace shown
- * when your operator *dies* — a normal, authored game outcome. Routing a real
+ * sibling `<crash-dump>` / `<game-over>` are in-fiction: per-job debrief and
+ * terminal campaign loss — normal, authored game outcomes. Routing a real
  * software bug through that screen would disguise the bug as an in-universe
  * death (the player shrugs and hits "new run"), which is exactly the silent
  * failure the project's error doctrine forbids (see `AGENTS.md` → "Error
diff --git a/components/GameOver.ts b/components/GameOver.ts
new file mode 100644
index 0000000..1ab5419
--- /dev/null
+++ b/components/GameOver.ts
@@ -0,0 +1,338 @@
+/**
+ * <game-over> — full-screen terminal loss overlay. Shown when the campaign is
+ * truly over: crew wipe, Score window closed, or the last operator flatlines
+ * on a job. Distinct from `<crash-dump>`, which handles recoverable per-job
+ * setbacks and successful exfil debriefs.
+ *
+ *   GAME OVER
+ *   The Score window closed.
+ *   Corp security caught up. The contract is cold…
+ *   [ NEW CAMPAIGN ]
+ *
+ * Usage:
+ *   const screen = document.querySelector('game-over');
+ *   screen.addEventListener('new-run', () => finishEndedCampaign());
+ *   screen.setTelemetry({ campaignEndReason: 'clock-expired', seed });
+ *   screen.show();
+ */
+
+import { h } from '/src/domUtils.js';
+import type { GameOverTelemetry } from '/src/types.js';
+
+const CSS = `
+:host {
+  --go-accent: #ff3355;
+  --go-bg: rgba(4, 2, 3, 0.98);
+  --go-text: #f0d4da;
+  --go-dim: #c96b7d;
+  --go-shadow: 0 0 48px rgba(255, 51, 85, 0.35), 0 16px 48px rgba(0, 0, 0, 0.75);
+
+  display: none;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  color: var(--go-text);
+  background:
+    radial-gradient(ellipse at center, rgba(255, 51, 85, 0.12) 0%, transparent 65%),
+    rgba(0, 0, 0, 0.88);
+  animation: game-over-backdrop 2.4s ease-in-out infinite alternate;
+}
+
+:host([open]) {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+@keyframes game-over-backdrop {
+  from { background-color: rgba(0, 0, 0, 0.86); }
+  to { background-color: rgba(12, 2, 4, 0.92); }
+}
+
+.panel {
+  background: var(--go-bg);
+  border: 2px solid var(--go-accent);
+  border-radius: 6px;
+  padding: 1.25rem 1.5rem 1.5rem;
+  box-shadow: var(--go-shadow);
+  min-width: min(520px, 94vw);
+  max-width: min(680px, 96vw);
+  text-align: center;
+}
+
+.banner {
+  margin: 0 0 0.35rem;
+  font-size: clamp(1.75rem, 6vw, 2.5rem);
+  letter-spacing: 0.28em;
+  color: var(--go-accent);
+  text-shadow: 0 0 18px rgba(255, 51, 85, 0.45);
+  animation: game-over-pulse 1.8s ease-in-out infinite;
+}
+
+@keyframes game-over-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.82; }
+}
+
+.rule {
+  margin: 0 auto 1.25rem;
+  width: min(280px, 70%);
+  border: none;
+  border-top: 2px solid var(--go-accent);
+  opacity: 0.7;
+}
+
+.reason {
+  margin: 0 0 0.75rem;
+  font-size: 1.05rem;
+  color: var(--go-text);
+}
+
+.detail {
+  margin: 0 0 1.25rem;
+  font-size: 0.9rem;
+  color: var(--go-dim);
+  line-height: 1.45;
+}
+
+.roster {
+  margin: 0 0 1.25rem;
+  padding: 0.65rem 0.85rem;
+  background: rgba(0, 0, 0, 0.45);
+  border: 1px solid rgba(255, 51, 85, 0.28);
+  border-radius: 4px;
+  font-size: 0.85rem;
+  text-align: left;
+}
+
+.roster dt {
+  margin: 0;
+  color: var(--go-dim);
+  letter-spacing: 0.1em;
+  font-size: 0.75rem;
+}
+
+.roster dd {
+  margin: 0.35rem 0 0;
+  display: grid;
+  gap: 0.2rem;
+}
+
+.roster-line {
+  display: flex;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.roster-line .status {
+  color: var(--go-accent);
+  letter-spacing: 0.08em;
+}
+
+.meta {
+  display: grid;
+  grid-template-columns: max-content 1fr;
+  column-gap: 1.25rem;
+  row-gap: 0.2rem;
+  font-size: 0.85rem;
+  margin: 0 0 1.25rem;
+  text-align: left;
+}
+
+.meta dt {
+  color: var(--go-dim);
+  letter-spacing: 0.08em;
+}
+
+.meta dd {
+  margin: 0;
+  word-break: break-word;
+}
+
+.actions {
+  display: flex;
+  justify-content: center;
+}
+
+button.new-campaign {
+  appearance: none;
+  -webkit-appearance: none;
+  background: transparent;
+  color: var(--go-accent);
+  border: 2px solid var(--go-accent);
+  padding: 0.65em 2.25em;
+  border-radius: 4px;
+  font-family: inherit;
+  font-size: 1.05rem;
+  letter-spacing: 0.2em;
+  cursor: pointer;
+  min-height: 44px;
+  transition: background 0.15s ease, color 0.15s ease;
+}
+
+button.new-campaign:hover,
+button.new-campaign:focus-visible {
+  background: var(--go-accent);
+  color: #020403;
+  outline: none;
+}
+
+button.new-campaign:active { transform: scale(0.98); }
+`;
+
+function hexSeed(seed: number) {
+  if (!Number.isFinite(seed)) return '?';
+  return `0x${(seed >>> 0).toString(16).toUpperCase().padStart(8, '0')}`;
+}
+
+function reasonCopy(telemetry: GameOverTelemetry): string {
+  if (telemetry.campaignEndReason === 'clock-expired') {
+    return 'The Score window closed.';
+  }
+  if (telemetry.campaignTerminal) {
+    return 'Final operator lost on the wire.';
+  }
+  return 'No surviving operators.';
+}
+
+function detailCopy(telemetry: GameOverTelemetry): string {
+  if (telemetry.campaignEndReason === 'clock-expired') {
+    return 'Corp security caught up. The contract is cold and this campaign is over.';
+  }
+  if (telemetry.campaignTerminal) {
+    const label = telemetry.cause ?? telemetry.archetype ?? 'operator';
+    return `Last channel down — ${label}. No backup left on the roster.`;
+  }
+  const salvageNote =
+    telemetry.salvage != null && typeof telemetry.salvage === 'number' && telemetry.salvage >= 0
+      ? `Pool salvage ${telemetry.salvage} is lost with the run.`
+      : 'Every crew slot on the roster is flatlined.';
+  return `${salvageNote} Start a new campaign to run the board again.`;
+}
+
+function causeLabel(telemetry: GameOverTelemetry): string {
+  if (telemetry.campaignEndReason === 'clock-expired') return 'window-closed';
+  if (telemetry.campaignTerminal) return 'final-operator-lost';
+  return 'crew-wipe';
+}
+
+class GameOver extends HTMLElement {
+  #telemetry: GameOverTelemetry | null = null;
+  #ready = false;
+  #els: {
+    reason: HTMLElement;
+    detail: HTMLElement;
+    roster: HTMLElement;
+    rosterList: HTMLElement;
+    seedDd: HTMLElement;
+    causeDd: HTMLElement;
+    newCampaignBtn: HTMLButtonElement;
+  } | null = null;
+
+  connectedCallback() {
+    if (this.#ready) return;
+    const shadow = this.attachShadow({ mode: 'open' });
+    const style = h('style');
+    style.textContent = CSS;
+    shadow.appendChild(style);
+
+    const reason = h('p', { className: 'reason' });
+    const detail = h('p', { className: 'detail' });
+    const rosterList = h('dd');
+    const seedDd = h('dd', { id: 'seed' });
+    const causeDd = h('dd', { id: 'cause' });
+    const roster = h('dl', { className: 'roster' }, [
+      h('dt', { textContent: 'ROSTER' }),
+      rosterList,
+    ]);
+
+    const newCampaignBtn = h('button', {
+      type: 'button',
+      className: 'new-campaign',
+      textContent: '[ NEW CAMPAIGN ]',
+    }) as HTMLButtonElement;
+    newCampaignBtn.addEventListener('click', () => this.#emit('new-run'));
+
+    const panel = h('section', { className: 'panel' }, [
+      h('h1', { className: 'banner', textContent: 'GAME OVER' }),
+      h('hr', { className: 'rule' }),
+      reason,
+      detail,
+      roster,
+      h('dl', { className: 'meta' }, [
+        h('dt', { textContent: 'seed' }),
+        seedDd,
+        h('dt', { textContent: 'cause' }),
+        causeDd,
+      ]),
+      h('div', { className: 'actions' }, [newCampaignBtn]),
+    ]);
+    shadow.appendChild(panel);
+    this.#els = { reason, detail, roster, rosterList, seedDd, causeDd, newCampaignBtn };
+    this.#ready = true;
+    if (this.#telemetry) this.#render();
+  }
+
+  setTelemetry(telemetry: GameOverTelemetry) {
+    if (!telemetry || typeof telemetry !== 'object') {
+      throw new TypeError('<game-over>.setTelemetry requires a telemetry object');
+    }
+    const { campaignEndReason, campaignTerminal } = telemetry;
+    if (!campaignEndReason && !campaignTerminal) {
+      throw new Error('<game-over>: requires campaignEndReason or campaignTerminal');
+    }
+    this.#telemetry = { ...telemetry };
+    if (this.#ready) this.#render();
+  }
+
+  show() {
+    this.setAttribute('open', '');
+    queueMicrotask(() => {
+      (this.shadowRoot?.querySelector('button.new-campaign') as HTMLButtonElement)?.focus();
+    });
+  }
+
+  hide() {
+    this.removeAttribute('open');
+  }
+
+  get isOpen() {
+    return this.hasAttribute('open');
+  }
+
+  #render() {
+    if (!this.#els || !this.#telemetry) return;
+    const t = this.#telemetry;
+    this.#els.reason.textContent = reasonCopy(t);
+    this.#els.detail.textContent = detailCopy(t);
+    this.#els.seedDd.textContent = hexSeed(t.seed ?? 0);
+    this.#els.causeDd.textContent = causeLabel(t);
+
+    if (t.campaignEndReason === 'clock-expired') {
+      this.#els.roster.hidden = true;
+      return;
+    }
+
+    const roster = t.crewRoster ?? [];
+    this.#els.roster.hidden = roster.length === 0;
+    this.#els.rosterList.replaceChildren(
+      ...roster.map(op =>
+        h('div', { className: 'roster-line' }, [
+          h('span', { textContent: `${op.callsign} (${op.archetype})` }),
+          h('span', {
+            className: 'status',
+            textContent: op.flatlined ? 'FLATLINED' : 'ACTIVE',
+          }),
+        ])
+      )
+    );
+  }
+
+  #emit(eventName: string, detail: Record<string, unknown> = {}) {
+    this.dispatchEvent(
+      new CustomEvent(eventName, { detail: { ...detail, telemetry: { ...this.#telemetry } } })
+    );
+  }
+}
+
+customElements.define('game-over', GameOver);
+
+export default GameOver;
diff --git a/index.html b/index.html
index cae9c73..1d3ab22 100644
--- a/index.html
+++ b/index.html
@@ -60,6 +60,7 @@ <h3>Log</h3>
         <contract-select id="contract-select"></contract-select>
         <run-briefing id="briefing"></run-briefing>
         <crash-dump id="crash"></crash-dump>
+        <game-over id="game-over"></game-over>
         <fault-screen id="fault-screen"></fault-screen>
         <system-start id="system-start"></system-start>
         <curator-briefing id="curator-briefing"></curator-briefing>
diff --git a/index.ts b/index.ts
index 3490956..21aeced 100644
--- a/index.ts
+++ b/index.ts
@@ -93,7 +93,7 @@ import type { Intent } from '/src/input/applyIntent.js';
 import type { AimKind, Mode } from '/src/input/keymap.js';
 import { formatCombatHudA11ySummary } from '/src/render/combatHud.js';
 import type { CombatHudSummaryInput } from '/src/render/combatHud.js';
-import type { KeyItem, Telemetry, TurnActionStep } from '/src/types.js';
+import type { GameOverTelemetry, KeyItem, Telemetry, TurnActionStep } from '/src/types.js';
 import { installErrorBoundary, type FaultSignal } from '/src/errorBoundary.js';
 import { isDevelopmentMode } from '/src/domUtils.js';
 
@@ -103,6 +103,7 @@ import '/components/TouchPad.js';
 import '/components/ContractSelect.js';
 import '/components/RunBriefing.js';
 import '/components/CrashDump.js';
+import '/components/GameOver.js';
 import '/components/FaultScreen.js';
 import '/components/SystemStart.js';
 import '/components/CuratorBriefing.js';
@@ -139,7 +140,10 @@ type ContractSelectElement = ModalElement & {
   setScorePrincipalId(principalId: string | null): void;
 };
 type CrashDumpElement = ModalElement & {
-  setTelemetry(telemetry: Record<string, unknown>): void;
+  setTelemetry(telemetry: Telemetry): void;
+};
+type GameOverElement = ModalElement & {
+  setTelemetry(telemetry: GameOverTelemetry): void;
 };
 type FaultScreenElement = ModalElement & {
   show(detail: { code?: string }): void;
@@ -259,6 +263,9 @@ let stageEl: HTMLElement;
 let briefingEl: RunBriefingElement;
 let contractSelectEl: ContractSelectElement;
 let crashEl: CrashDumpElement;
+let gameOverEl: GameOverElement;
+/** Which overlay owns `RUN_STATE.RESULT` — set in `pushPendingJobResultOverlay`. */
+let resultOverlayTarget: 'crash' | 'game-over' = 'crash';
 let faultEl: FaultScreenElement;
 let systemStartEl: SystemStartElement;
 let curatorBriefingEl: CuratorBriefingElement;
@@ -427,6 +434,7 @@ async function boot() {
   contractSelectEl = mustGetElement<ContractSelectElement>('contract-select');
   briefingEl = mustGetElement<RunBriefingElement>('briefing');
   crashEl = mustGetElement<CrashDumpElement>('crash');
+  gameOverEl = mustGetElement<GameOverElement>('game-over');
   faultEl = mustGetElement<FaultScreenElement>('fault-screen');
   systemStartEl = mustGetElement<SystemStartElement>('system-start');
   curatorBriefingEl = mustGetElement<CuratorBriefingElement>('curator-briefing');
@@ -470,6 +478,7 @@ async function boot() {
   briefingEl.addEventListener('deploy', onBriefingDeploy);
   briefingEl.addEventListener('dismiss', onBriefingDismiss);
   crashEl.addEventListener('new-run', onNewRunRequested);
+  gameOverEl.addEventListener('new-run', onNewRunRequested);
   faultEl.addEventListener('return-to-hub', () => onFaultReturnToHub());
   systemStartEl.addEventListener('hub-enter', onSystemStartHubEnter);
   curatorBriefingEl.addEventListener('dismiss', onCuratorBriefingDismiss);
@@ -601,10 +610,15 @@ function onInitialRecruited(evt: Event) {
   flash(`CURATOR: ${names} on the board. Find me when you want work.`);
 }
 
+function hideResultOverlays(): void {
+  crashEl?.hide();
+  gameOverEl?.hide();
+}
+
 function hideBlockingShellModals(): void {
   keyHelpEl?.hide();
   briefingEl?.hide();
-  crashEl?.hide();
+  hideResultOverlays();
   contractSelectEl?.hide();
   systemStartEl?.hide();
   curatorBriefingEl?.hide();
@@ -1158,6 +1172,14 @@ function crewMemberArchetypeId(member: Crew): string {
   return 'op';
 }
 
+function crewRosterStubs(c: Campaign) {
+  return c.crew.map(member => ({
+    callsign: member.callsign ?? member.id,
+    archetype: crewMemberArchetypeId(member),
+    flatlined: !!member.flatlined,
+  }));
+}
+
 function telemetryForEndedCampaign(c: Campaign): Telemetry {
   const reason = c.endReason ?? 'crew-wipe';
   return {
@@ -1165,16 +1187,33 @@ function telemetryForEndedCampaign(c: Campaign): Telemetry {
     campaignEndReason: reason,
     seed: c.seed,
     salvage: c.salvage,
-    crewRoster: c.crew.map(member => ({
-      callsign: member.callsign ?? member.id,
-      archetype: crewMemberArchetypeId(member),
-      flatlined: !!member.flatlined,
-    })),
+    crewRoster: crewRosterStubs(c),
+  };
+}
+
+function gameOverTelemetryForCampaign(c: Campaign): GameOverTelemetry {
+  const reason = c.endReason ?? 'crew-wipe';
+  if (reason === 'score-complete') {
+    throw new Error('[shell] score-complete is a win debrief, not game over');
+  }
+  return {
+    campaignEndReason: reason,
+    seed: c.seed,
+    salvage: c.salvage,
+    crewRoster: crewRosterStubs(c),
   };
 }
 
+function presentEndedCampaignOverlay(c: Campaign): void {
+  if (c.endReason === 'score-complete') {
+    crashEl.setTelemetry(telemetryForEndedCampaign(c));
+  } else {
+    gameOverEl.setTelemetry(gameOverTelemetryForCampaign(c));
+  }
+}
+
 function presentCampaignEnd(c: Campaign): void {
-  crashEl.setTelemetry(telemetryForEndedCampaign(c));
+  presentEndedCampaignOverlay(c);
   renderShell();
 }
 
@@ -1184,9 +1223,9 @@ function finishEndedCampaign(): void {
 }
 
 /**
- * Drives `<crash-dump>` and `pendingJobResult` whenever the active job is in
+ * Drives result overlays and `pendingJobResult` whenever the active job is in
  * RESULT — both from a live `Run.onResult` callback and from a cold resume
- * (otherwise `renderShell` opens the overlay with no `setTelemetry` call).
+ * (otherwise `renderShell` opens an overlay with no `setTelemetry` call).
  */
 function pushPendingJobResultOverlay(telemetry: Partial<RunTelemetry> & { outcome?: unknown }) {
   const tel = { ...telemetry };
@@ -1200,11 +1239,29 @@ function pushPendingJobResultOverlay(telemetry: Partial<RunTelemetry> & { outcom
   };
   const campaignTerminal =
     outcome === 'death' && campaign ? willEndCampaignOnThisDeath(campaign) : false;
-  crashEl.setTelemetry({
-    ...tel,
-    outcome,
-    campaignTerminal,
-  });
+  if (campaignTerminal && campaign) {
+    const activeCampaign = campaign;
+    const deployedId = activeCampaign.deployedMemberId;
+    resultOverlayTarget = 'game-over';
+    gameOverEl.setTelemetry({
+      campaignTerminal: true,
+      seed: tel.seed,
+      cause: tel.cause,
+      archetype: tel.archetype,
+      crewRoster: activeCampaign.crew.map(member => ({
+        callsign: member.callsign ?? member.id,
+        archetype: crewMemberArchetypeId(member),
+        flatlined: !!member.flatlined || member.id === deployedId,
+      })),
+    });
+  } else {
+    resultOverlayTarget = 'crash';
+    crashEl.setTelemetry({
+      ...tel,
+      outcome,
+      cause: tel.cause ?? undefined,
+    });
+  }
 }
 
 function handleResult({ outcome, telemetry }: RunResult) {
@@ -1243,7 +1300,7 @@ function resumeCampaign(record: CampaignSnapshot | unknown) {
     const resumeFlashMessage = `RESUMED — crew ${campaign.crew.filter(member => !member.flatlined).length} active.`;
     if (campaign.state === CAMPAIGN_STATE.ENDED) {
       pendingJobResult = null;
-      crashEl.setTelemetry(telemetryForEndedCampaign(campaign));
+      presentEndedCampaignOverlay(campaign);
       flash(
         campaign.endReason === 'clock-expired'
           ? 'WINDOW CLOSED — Score contract went cold.'
@@ -1296,13 +1353,14 @@ function performQuitCampaign(): void {
   if (!campaign) return;
   keyHelpEl.hide();
   briefingEl.hide();
-  crashEl.hide();
+  hideResultOverlays();
   crewRosterEl.hide();
   finnShopEl.hide();
   clinicModalEl.hide();
   itemInventoryEl.hide();
 
   pendingJobResult = null;
+  resultOverlayTarget = 'crash';
   dataStore.deleteCampaign();
   startFreshCampaign();
   flash('Campaign deleted — new campaign.');
@@ -1838,7 +1896,7 @@ function onNewRunRequested(): void {
     finishEndedCampaign();
     return;
   }
-  crashEl.hide();
+  hideResultOverlays();
   attachVisionListener();
   attachAnimationListeners();
   attachRepListeners();
@@ -1988,7 +2046,7 @@ function renderShell(): void {
     case RUN_STATE.COMBAT:
       canvas.hidden = false;
       briefingEl.hide();
-      crashEl.hide();
+      hideResultOverlays();
       break;
     case RUN_STATE.BRIEFING:
       // The combined briefing modal handles its own show/hide. If we land
@@ -2003,17 +2061,29 @@ function renderShell(): void {
         briefingEl.setCrew(campaign.crew);
         briefingEl.show();
       }
-      crashEl.hide();
+      hideResultOverlays();
       break;
     case RUN_STATE.RESULT:
       canvas.hidden = true;
       briefingEl.hide();
-      crashEl.show();
+      if (resultOverlayTarget === 'game-over') {
+        crashEl.hide();
+        gameOverEl.show();
+      } else {
+        gameOverEl.hide();
+        crashEl.show();
+      }
       break;
     case CAMPAIGN_STATE.ENDED:
       canvas.hidden = true;
       briefingEl.hide();
-      crashEl.show();
+      if (campaign.endReason === 'score-complete') {
+        gameOverEl.hide();
+        crashEl.show();
+      } else {
+        crashEl.hide();
+        gameOverEl.show();
+      }
       break;
     default:
       throw new Error(`[shell] unknown state "${state}"`);
@@ -2480,6 +2550,7 @@ function isAnyBlockingModalOpen(): boolean {
   if (contractSelectEl?.isOpen) return true;
   if (briefingEl?.isOpen) return true;
   if (crashEl?.isOpen) return true;
+  if (gameOverEl?.isOpen) return true;
   if (systemStartEl?.isOpen) return true;
   if (curatorBriefingEl?.isOpen) return true;
   if (initialRecruitEl?.isOpen) return true;
diff --git a/main.css b/main.css
index 429b5b7..1786a7e 100644
--- a/main.css
+++ b/main.css
@@ -354,6 +354,7 @@ main {
 
 .game-stage > run-briefing,
 .game-stage > crash-dump,
+.game-stage > game-over,
 .game-stage > fault-screen,
 .game-stage > system-start,
 .game-stage > curator-briefing {
diff --git a/src/types.ts b/src/types.ts
index bc297a7..eb74f15 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -241,17 +241,30 @@ export type LocationSite = {
   site?: LocationToken;
 };
 
+export type GameOverCrewStub = { callsign: string; archetype: string; flatlined: boolean };
+
+/** Terminal campaign loss — crew wipe, clock deadline, or last-operator death. */
+export type GameOverTelemetry = {
+  campaignEndReason?: Exclude<CampaignEndReason, 'score-complete'>;
+  campaignTerminal?: boolean;
+  crewRoster?: GameOverCrewStub[];
+  salvage?: import('./game/salvage.js').TypedSalvage;
+  seed?: number;
+  cause?: string | null;
+  archetype?: string;
+};
+
 export type Telemetry = {
   outcome: 'death' | 'exit' | 'campaign-over';
   campaignEndReason?: CampaignEndReason;
   campaignTerminal?: boolean;
-  crewRoster?: { callsign: string; archetype: string; flatlined: boolean }[];
+  crewRoster?: GameOverCrewStub[];
   /** Typed-salvage wallet snapshot at the moment the run/campaign ends. */
   salvage?: import('./game/salvage.js').TypedSalvage;
   archetype?: string;
   turn?: number;
   kills?: number;
-  cause?: string;
+  cause?: string | null;
   seed?: number;
   hpAtDeath?: number | null;
   hpAtDamage?: number | null;
diff --git a/sw-core.js b/sw-core.js
index a8dbe81..0fb5872 100644
--- a/sw-core.js
+++ b/sw-core.js
@@ -30,6 +30,7 @@ const CacheConfig = {
       '/components/CuratorBriefing.js',
       '/components/ContractSelect.js',
       '/components/CrashDump.js',
+      '/components/GameOver.js',
       '/components/FaultScreen.js',
       '/components/CrewList.js',
       '/components/CrewRoster.js',
diff --git a/sw-dev.js b/sw-dev.js
index 25811e2..33f02aa 100644
--- a/sw-dev.js
+++ b/sw-dev.js
@@ -1,5 +1,5 @@
 // Service Worker for Kernel Panic - Development Version
-const VERSION = '0.2.11-dev';
+const VERSION = '0.2.12-dev';
 importScripts(`/sw-core.js?v=${VERSION}`);
 
 const cacheConfig = CacheConfig.create(VERSION);

From c65764848ad4088c22c118b1ead2127ab45fd06a Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Tue, 9 Jun 2026 20:24:59 -0700
Subject: [PATCH 11/55] plan updates

---
 docs/phase-3-plan.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 21ab864..8a8ea77 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -142,6 +142,7 @@ Neural degradation is deferred until Cyberspace is fun enough to deserve a jack-
 | **P3.M1.5 Clock** | ✅ Done | Act 2/3 deploy-driven heat + deadline; `clock-reveal`; HUD gated on briefing; clock loss game-over screen | heat math, grace deploys, deadline loss, endReason |
 | **P3.M1.6 Curator bias** | ✅ Done | Pass campaign-derived arc context; bias board slots by act and score target's principal | seeded boards show expected `arcStage` and same-principal frequency in Act 2+ |
 | **P3.M1.7 Score entry** | ✅ Done | Hub action creates the special Score contract in Act 3 only | availability gates, deployment path, attempted flag |
+| **P3.M1.8 Game Over component** | ✅ Done | Dedicated component, separate from CrashDump, to be shown when Score window closes or crew are all flatlined |
 
 **P3.M1.1 implementation note:** `Campaign` now owns a typed `arc` record (`arcStage`, `deckerRecruited`, `scoreRevealed`, `clockStarted`, `scoreAttempted`, `scoreCompleted`) plus an `arcStage` getter for Curator context. New snapshots serialize the record; pre-P3 snapshots normalize to Act 1; malformed persisted arc data throws during restore instead of being silently repaired.
 

From e4fb86cfc8ff2b76088d6a9bc6a1756402eb619a Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Tue, 9 Jun 2026 21:01:45 -0700
Subject: [PATCH 12/55] plan tweaks for M4

---
 docs/phase-3-plan.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 8a8ea77..bff337b 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -170,7 +170,7 @@ Neural degradation is deferred until Cyberspace is fun enough to deserve a jack-
 
 ---
 
-### P3.M2 — The Decker archetype 🔲
+### P3.M2 — The Decker archetype ✅
 
 **Depends on:** P3.M1 (arc structure for recruitment gating). Can develop archetype mechanics in parallel, but recruitment integration requires arc state.
 
@@ -261,16 +261,16 @@ The first jack-in should prove the door between layers before shipping every ICE
 **Scope:**
 
 - **Dual-deploy:** On contracts with a Cyberspace component, the player selects two operators: one for Meatspace, one (the Decker) for Cyberspace. Both are placed on their respective grids at mission start (Meatspace operator at spawn, Decker at the jack-in terminal's Cyberspace entry node).
-  - **Pre–jack-in phase:** Both operators start in Meatspace. The Meatspace operator moves and acts normally. The Decker must reach a terminal and jack in (P2.5.M2.2 interact) to activate Cyberspace. Until jack-in, this is a normal single-grid mission.
-  - **Post–jack-in:** Cyberspace grid spawns. Flip mechanic activates. Decker's Meatspace body remains at the terminal — vulnerable, immobile, and targetable by corp hostiles (blueprint: "your physical body is a vegetable").
+  - **Pre–jack-in phase:** The Decker starts in Meatspace, where they move and act normally. The player must reach a terminal and jack in (P2.5.M2.2 interact) to activate Cyberspace. Until jack-in, this is a normal single-grid mission.
+  - **Post–jack-in:** Cyberspace grid spawns. Flip mechanic activates. Decker's Meatspace body remains at the terminal — vulnerable, immobile, and targetable by corp hostiles (blueprint: "your physical body is a vegetable"). Secondary operator now enters the Meatspace grid.
 - **The flip:** Switch active control between Meatspace operator and Decker. Active operator receives player input (move, attack, interact). Inactive operator holds position.
   - Cost: **free action** for the first implementation. AP cost can be revisited after playtesting, but the first version should make the new mental model easy to explore.
   - Can flip at any point during the active operator's turn (before or after spending AP).
 - **Turn structure:** Player turn → flip as desired → end turn → **both layers' hostile phases resolve** (corp drones move in Meatspace, ICE moves in Cyberspace). Both layers tick simultaneously.
 - **PIP / CCTV window:** The inactive layer renders in a small overlay (bottom right corner of the screen). Shows grid state, hostile positions, the other operator's status. Read-only — no input accepted in the PIP. The blueprint's "real-time CCTV showing your physical body's status" becomes this.
-- **Vulnerability:** While the Decker is jacked in, their Meatspace body is a valid target for corp hostiles. If the body is destroyed, the Decker is killed (flatline) and Cyberspace access is lost. The Meatspace operator's implicit job is to **protect the Decker's body** — or at least keep hostiles away from the terminal.
+- **Vulnerability:** While the Decker is jacked in, their Meatspace body is a valid target for corp hostiles. If the body is destroyed, the Decker is killed (flatline) and Cyberspace access is lost. The Meatspace operator's explicit job is to **protect the Decker's body** — or at least keep hostiles away from the terminal.
 - **Jack-out:** The Decker can voluntarily jack out (returns control to single-grid Meatspace). Or is forced out if their body takes critical damage. Jack-out despawns the Cyberspace grid (any unsatisfied Cyberspace objectives fail).
-- **Contracts without Cyberspace:** Single-deploy as today. The Decker deploys solo in Meatspace (no flip, no Cyberspace grid). Their drone override hack is their primary value.
+- **Contracts without Cyberspace:** Single-deploy as today. The Decker deploys solo in Meatspace (no flip, no Cyberspace grid). Their drone override hack is their primary value, but if they're flatlined, the campaign is over - no new Deckers can be recruited.
 - **Save invariant:** A run may be single-layer, pre-jack dual-deploy, or active dual-layer. Those states must be explicit. A save with `cyberspace.active = true` but no cyber grid/avatar, or with a Decker marked jacked-in but no Meatspace body anchor, is corrupt and must throw.
 
 **Integration slices:**

From b4be1e7cad0504a73d0f0b75b90880d22306074f Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Tue, 9 Jun 2026 21:08:17 -0700
Subject: [PATCH 13/55] P3.M3.1: Cyberspace contract flag + deployment gates

DATA_NODE_SLICE objective kind with cross-validated requiresCyberspace/count
params, cyber-data-spike recipe gated on Act 2+ with a living Decker
(availableWhen filter across all three generation paths), Campaign
hasLivingDecker getter + loud deploy gate, and NEEDS DECKER row gating in
the briefing crew list.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 components/CrewList.ts                    |  34 +++-
 components/RunBriefing.ts                 |  36 +++-
 src/game/Campaign.ts                      |  18 +-
 src/game/Run.ts                           |   5 +
 src/game/hub/Curator.ts                   |  98 ++++++++-
 tests/unit/game/hub/cyberContract.test.ts | 230 ++++++++++++++++++++++
 6 files changed, 403 insertions(+), 18 deletions(-)
 create mode 100644 tests/unit/game/hub/cyberContract.test.ts

diff --git a/components/CrewList.ts b/components/CrewList.ts
index 2124c59..61a8c48 100644
--- a/components/CrewList.ts
+++ b/components/CrewList.ts
@@ -19,8 +19,17 @@ type CrewSummary = {
   hp: number;
   maxHp: number;
   flatlined: boolean;
+  /** P3.M3.1: non-null when a contract gate disables this row (e.g. 'NEEDS DECKER'). */
+  gatedReason: string | null;
 };
 
+/**
+ * P3.M3.1: optional per-row deployment gate. Return a short uppercase tag
+ * (e.g. 'NEEDS DECKER') to disable the row with that flag, or null to leave
+ * the row deployable.
+ */
+export type CrewRowGate = (member: CrewMember) => string | null;
+
 const CSS = `
 :host {
   display: block;
@@ -127,11 +136,15 @@ class CrewList extends HTMLElement {
 
   /**
    * @param {Array} crew — array of crew member objects (or snapshots).
+   * @param rowGate — optional P3.M3.1 deployment gate; see {@link CrewRowGate}.
    */
-  setCrew(crew: CrewMember[]) {
+  setCrew(crew: CrewMember[], rowGate: CrewRowGate | null = null) {
     if (!Array.isArray(crew)) {
       throw new TypeError('<crew-list>.setCrew requires an array');
     }
+    if (rowGate !== null && typeof rowGate !== 'function') {
+      throw new TypeError('<crew-list>.setCrew rowGate must be a function when set');
+    }
     this.#crew = crew.map(member => ({
       id: member.id,
       callsign: member.callsign ?? member.id,
@@ -139,10 +152,11 @@ class CrewList extends HTMLElement {
       hp: member.hp,
       maxHp: member.maxHp,
       flatlined: !!member.flatlined,
+      gatedReason: rowGate ? rowGate(member) : null,
     }));
     this.#selectedIndex = Math.max(
       0,
-      this.#crew.findIndex(member => !member.flatlined)
+      this.#crew.findIndex(member => isSelectable(member))
     );
     if (this.#ready) this.#render();
     // Emit initial selection so the parent can populate the detail pane.
@@ -175,9 +189,9 @@ class CrewList extends HTMLElement {
 
     for (let i = 0; i < this.#crew.length; i++) {
       const member = this.#crew[i];
-      // Only flatlined members are disabled; living rows stay focusable for
-      // keyboard navigation and click-to-select.
-      const disabled = member.flatlined;
+      // Flatlined members and contract-gated rows (P3.M3.1) are disabled;
+      // living deployable rows stay focusable for keyboard nav and click.
+      const disabled = !isSelectable(member);
       const row = h('button', {
         type: 'button',
         className: 'row',
@@ -191,7 +205,7 @@ class CrewList extends HTMLElement {
         h('span', { className: 'name', textContent: member.callsign }),
         h('span', {
           className: 'flag',
-          textContent: member.flatlined ? 'FLATLINED' : '',
+          textContent: member.flatlined ? 'FLATLINED' : (member.gatedReason ?? ''),
         }),
         h('span', {
           className: 'meta',
@@ -223,7 +237,7 @@ class CrewList extends HTMLElement {
     let next = this.#selectedIndex;
     for (let i = 0; i < this.#crew.length; i++) {
       next = (next + delta + this.#crew.length) % this.#crew.length;
-      if (!this.#crew[next].flatlined) break;
+      if (isSelectable(this.#crew[next])) break;
     }
     this.#selectedIndex = next;
     this.#syncCurrent();
@@ -233,7 +247,7 @@ class CrewList extends HTMLElement {
 
   #onRowClick(index: number) {
     const member = this.#crew[index];
-    if (!member || member.flatlined) return;
+    if (!member || !isSelectable(member)) return;
     // Update selection to clicked row.
     this.#selectedIndex = index;
     this.#syncCurrent();
@@ -254,6 +268,10 @@ class CrewList extends HTMLElement {
   }
 }
 
+function isSelectable(member: CrewSummary): boolean {
+  return !member.flatlined && member.gatedReason === null;
+}
+
 customElements.define('crew-list', CrewList);
 
 export default CrewList;
diff --git a/components/RunBriefing.ts b/components/RunBriefing.ts
index 86f5bdd..0d289bc 100644
--- a/components/RunBriefing.ts
+++ b/components/RunBriefing.ts
@@ -20,9 +20,10 @@
 import { h } from '/src/domUtils.js';
 import CrewList from '/components/CrewList.js';
 import { encounterHostileCount } from '/src/game/encounters.js';
-import { cloneObjective } from '/src/game/hub/Curator.js';
+import { cloneObjective, contractRequiresCyberspace } from '/src/game/hub/Curator.js';
 import type { Crew as CrewMember } from '/src/game/Crew.js';
 import type { Contract } from '/src/game/hub/Curator.js';
+import type { CrewRowGate } from '/components/CrewList.js';
 
 type BriefingCells = {
   target: HTMLElement;
@@ -206,6 +207,7 @@ function rewardCopy(contract: Partial<Contract>) {
 
 class RunBriefing extends HTMLElement {
   #contract: Contract | null = null;
+  #crew: CrewMember[] = [];
   #selectedMember: CrewMember | null = null;
   #ready = false;
   #cells: BriefingCells | null = null;
@@ -254,7 +256,7 @@ class RunBriefing extends HTMLElement {
     this.#listEl?.addEventListener('select', evt => {
       this.#selectedMember = (evt as CustomEvent<{ member: CrewMember }>).detail.member;
       if (this.#jackInBtn) {
-        this.#jackInBtn.disabled = !this.#selectedMember || this.#selectedMember.flatlined;
+        this.#jackInBtn.disabled = !this.#deployable(this.#selectedMember);
       }
     });
 
@@ -309,6 +311,9 @@ class RunBriefing extends HTMLElement {
     }
     this.#contract = cloneContract(contract);
     if (this.#ready) this.#renderContract();
+    // The deployment gate depends on the contract (P3.M3.1) — re-render any
+    // already-set crew so row gating cannot go stale on contract swap.
+    if (this.#crew.length > 0) this.#syncCrewList();
   }
 
   /**
@@ -319,9 +324,29 @@ class RunBriefing extends HTMLElement {
     if (!Array.isArray(crew)) {
       throw new TypeError('<run-briefing>.setCrew requires an array');
     }
+    this.#crew = crew;
+    this.#syncCrewList();
+  }
+
+  /**
+   * P3.M3.1: Cyberspace contracts can only deploy the Decker — every other
+   * row renders disabled with a NEEDS DECKER tag.
+   */
+  #rowGate(): CrewRowGate | null {
+    if (!this.#contract || !contractRequiresCyberspace(this.#contract)) return null;
+    return member => (member.archetype === 'Decker' ? null : 'NEEDS DECKER');
+  }
+
+  #deployable(member: CrewMember | null): boolean {
+    if (!member || member.flatlined) return false;
+    const gate = this.#rowGate();
+    return gate ? gate(member) === null : true;
+  }
+
+  #syncCrewList() {
     this.#selectedMember = null;
     if (this.#jackInBtn) this.#jackInBtn.disabled = true;
-    this.#listEl?.setCrew(crew);
+    this.#listEl?.setCrew(this.#crew, this.#rowGate());
   }
 
   show() {
@@ -382,10 +407,11 @@ class RunBriefing extends HTMLElement {
   }
 
   #commit() {
-    if (!this.#contract || !this.#selectedMember || this.#selectedMember.flatlined) return;
+    const member = this.#selectedMember;
+    if (!this.#contract || !member || !this.#deployable(member)) return;
     this.dispatchEvent(
       new CustomEvent('deploy', {
-        detail: { memberId: this.#selectedMember.id, contract: cloneContract(this.#contract) },
+        detail: { memberId: member.id, contract: cloneContract(this.#contract) },
       })
     );
   }
diff --git a/src/game/Campaign.ts b/src/game/Campaign.ts
index 998d601..a8b5ba3 100644
--- a/src/game/Campaign.ts
+++ b/src/game/Campaign.ts
@@ -21,7 +21,7 @@ import {
   type TypedSalvage,
 } from './salvage.js';
 import { buildCrewMember, RECRUIT_ARCHETYPE_POOL } from './archetypes/index.js';
-import { CONTRACT_LEXICON, Curator } from './hub/Curator.js';
+import { CONTRACT_LEXICON, Curator, contractRequiresCyberspace } from './hub/Curator.js';
 import { OBJECTIVES } from './hub/Curator.js';
 import { Terminal } from './hub/Terminal.js';
 import { Finn } from './hub/Finn.js';
@@ -321,6 +321,15 @@ export class Campaign {
     return Math.max(0, this.clockJobsTaken - CLOCK_ACT2_GRACE_JOBS);
   }
 
+  /**
+   * P3.M3.1: whether the roster carries a non-flatlined Decker. Gates
+   * Cyberspace-capable contract generation (`Curator` reads this through the
+   * `ContractCampaign` surface) and is the precondition for jack-in.
+   */
+  get hasLivingDecker(): boolean {
+    return this.crew.some(member => member.archetype === 'Decker' && !member.flatlined);
+  }
+
   get scoreDeadlineJobsRemaining(): number {
     return Math.max(0, CLOCK_ACT2_DEADLINE_JOBS - this.clockJobsTaken);
   }
@@ -432,6 +441,13 @@ export class Campaign {
     if (member.flatlined) {
       throw new Error(`Campaign.deployCrewMember: ${member.callsign ?? member.id} is flatlined`);
     }
+    // P3.M3.1: a Cyberspace contract is unwinnable without the one operator who
+    // can jack in — fail loudly at the Hub boundary instead of starting it.
+    if (contractRequiresCyberspace(contract) && member.archetype !== 'Decker') {
+      throw new Error(
+        `Campaign.deployCrewMember: contract "${contract.label}" requires a living Decker to jack in`
+      );
+    }
     if (isScoreContract(contract)) {
       this.#beginScoreAttempt(contract);
     } else if (this.arc.arcStage === 'act-2' || this.arc.arcStage === 'act-3') {
diff --git a/src/game/Run.ts b/src/game/Run.ts
index 75575d4..f992e2d 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -1508,6 +1508,11 @@ function isObjectiveFamilySatisfied(
       return isReconSatisfied(world, objectiveState);
     case OBJECTIVES.ESCORT_EXTRACT:
       return isEscortExtractSatisfied(world);
+    case OBJECTIVES.DATA_NODE_SLICE:
+      // P3.M3.1: satisfaction requires the Cyberspace layer (P3.M3.4 wires
+      // sliced-node counting through ObjectiveState). Until then a cyber
+      // contract is honestly unsatisfiable — extraction stays gated.
+      return false;
     default: {
       const exhaustive: never = kind;
       throw new Error(`Run.isObjectiveSatisfied: unknown objective kind "${exhaustive}"`);
diff --git a/src/game/hub/Curator.ts b/src/game/hub/Curator.ts
index 5f20482..1948e6c 100644
--- a/src/game/hub/Curator.ts
+++ b/src/game/hub/Curator.ts
@@ -34,6 +34,8 @@ export const OBJECTIVES = Object.freeze({
   DUAL_SITE: 'dual-site',
   RECON: 'recon',
   ESCORT_EXTRACT: 'escort-extract',
+  /** P3.M3: slice a data node in Cyberspace — requires a living Decker to jack in. */
+  DATA_NODE_SLICE: 'data-node-slice',
 });
 
 const KNOWN_OBJECTIVE_KINDS = new Set(Object.values(OBJECTIVES));
@@ -72,6 +74,8 @@ export type ContractContext = {
 
 type ContractRecipeContext = {
   arcStage?: CampaignArcStage;
+  /** P3.M3.1: whether the campaign roster carries a non-flatlined Decker. */
+  hasLivingDecker?: boolean;
 };
 
 type ContractToken = {
@@ -108,6 +112,12 @@ type ContractRecipe = {
   title: (tokens: ContractRecipeTokens) => string;
   briefing: (tokens: ContractRecipeTokens) => string;
   params: (tokens: ContractRecipeTokens) => ObjectiveParams | undefined;
+  /**
+   * P3.M3.1: campaign-state gate. When present, the recipe only enters the
+   * generation pool if this returns `true` for the board's recipe context.
+   * Absent means always available (the pre-P3.M3 pool is unchanged).
+   */
+  availableWhen?: (context: ContractRecipeContext) => boolean;
 };
 
 const REACH_EXIT_OBJECTIVE: ContractObjective = Object.freeze({
@@ -387,6 +397,27 @@ export const CONTRACT_RECIPES: readonly ContractRecipe[] = Object.freeze([
       contact: asset.contact ?? asset.label,
     }),
   },
+  {
+    // P3.M3.1: the first Cyberspace-capable contract family. Only enters the
+    // pool in Act 2+ with a living Decker on the roster — the jack-in port and
+    // the digital layer are meaningless without one. Params stay minimal:
+    // `requiresCyberspace` is the layer flag, `count` the data nodes to slice.
+    id: 'cyber-data-spike',
+    objectiveKind: OBJECTIVES.DATA_NODE_SLICE,
+    tags: Object.freeze(['cyberspace', 'digital', 'slice']),
+    principalGroups: Object.freeze(['corp']),
+    siteGroups: Object.freeze(['corp', 'data', 'security', 'infrastructure']),
+    siteStateGroups: Object.freeze(['normal', 'security']),
+    assetGroups: Object.freeze(['terminal']),
+    actionGroups: Object.freeze(['terminal']),
+    title: ({ asset }) => `Spike ${noun(asset)}`,
+    briefing: ({ principal, site, asset }) =>
+      `Find the jack-in port at ${possessive(principal.label)} ${sitePhrase({ site })}, breach the grid, slice the ${asset.label} node, then extract.`,
+    params: () => ({ requiresCyberspace: true, count: 1 }),
+    availableWhen: context =>
+      (context.arcStage === 'act-2' || context.arcStage === 'act-3') &&
+      context.hasLivingDecker === true,
+  },
 ]);
 
 const CURATOR_GLYPH = 'C';
@@ -491,6 +522,8 @@ type ContractCampaign =
       clockHeat?: number;
       /** Remembered combat locations the Curator may steer revisits toward (P2.5.M7.2). */
       siteRoster?: LocationSite[];
+      /** P3.M3.1: gates Cyberspace-capable recipes (`availableWhen`). */
+      hasLivingDecker?: boolean;
     }
   | null
   | undefined;
@@ -667,9 +700,45 @@ export function normalizeObjective(value: unknown): ContractObjective {
   if (candidate.params !== undefined) {
     validateObjectiveParams(candidate.params);
   }
+  validateCyberspaceObjective(candidate.kind, candidate.params);
   return cloneObjective(candidate as ContractObjective);
 }
 
+/**
+ * P3.M3.1: cross-field rules for the Cyberspace layer flag. `data-node-slice`
+ * must carry `requiresCyberspace: true` plus a positive integer `count`; no
+ * other kind may carry the flag. Validated at generation, at
+ * `Run.enterBriefing`, and on snapshot restore (all call `normalizeObjective`).
+ */
+function validateCyberspaceObjective(kind: ObjectiveKind, params: ObjectiveParams | undefined): void {
+  if (kind === OBJECTIVES.DATA_NODE_SLICE) {
+    if (params?.requiresCyberspace !== true) {
+      throw new Error(
+        `contract objective "${kind}" requires params.requiresCyberspace to be exactly true`
+      );
+    }
+    if (!Number.isInteger(params.count) || (params.count as number) < 1) {
+      throw new RangeError(
+        `contract objective "${kind}" requires params.count to be a positive integer`
+      );
+    }
+  } else if (params?.requiresCyberspace !== undefined) {
+    throw new Error(
+      `contract objective param "requiresCyberspace" is only valid on "${OBJECTIVES.DATA_NODE_SLICE}", got kind "${kind}"`
+    );
+  }
+}
+
+/**
+ * P3.M3.1: single source of truth for "this contract has a Cyberspace
+ * component". The params flag is validated against the objective kind by
+ * `normalizeObjective`, so any contract that survived validation answers
+ * consistently.
+ */
+export function contractRequiresCyberspace(contract: Pick<Contract, 'objective'>): boolean {
+  return contract.objective.params?.requiresCyberspace === true;
+}
+
 /**
  * Throws if recipes, lexicon, and objective coverage drift apart. Called from
  * unit tests so content additions fail fast without string-parsing labels back
@@ -903,7 +972,24 @@ function contractRecipeContext(campaign: ContractCampaign): ContractRecipeContex
   if (arcStage !== undefined && !isArcStage(arcStage)) {
     throw new Error(`Curator.generateContracts: unknown arcStage "${arcStage}"`);
   }
-  return arcStage ? { arcStage } : {};
+  const hasLivingDecker = campaign?.hasLivingDecker;
+  if (hasLivingDecker !== undefined && typeof hasLivingDecker !== 'boolean') {
+    throw new TypeError('Curator.generateContracts: hasLivingDecker must be a boolean when set');
+  }
+  return {
+    ...(arcStage ? { arcStage } : {}),
+    ...(hasLivingDecker !== undefined ? { hasLivingDecker } : {}),
+  };
+}
+
+/**
+ * P3.M3.1: recipes with an `availableWhen` gate only enter the pool when the
+ * campaign context satisfies it. Recipes without the gate are always eligible,
+ * so the filtered pool is identical to the historic pool whenever no gated
+ * recipe qualifies — seeded generation for pre-P3.M3 saves is unchanged.
+ */
+function recipeIsAvailable(recipe: ContractRecipe, context: ContractRecipeContext): boolean {
+  return recipe.availableWhen ? recipe.availableWhen(context) === true : true;
 }
 
 function isArcStage(value: unknown): value is CampaignArcStage {
@@ -944,8 +1030,9 @@ function generateRecipeContract(
   labelsUsed: Set<string>,
   context: ContractRecipeContext
 ): RenderedContract {
+  const availableRecipes = CONTRACT_RECIPES.filter(recipe => recipeIsAvailable(recipe, context));
   for (let i = 0; i < MAX_UNIQUE_CONTRACT_ATTEMPTS; i++) {
-    const recipe = rng.pick(CONTRACT_RECIPES);
+    const recipe = rng.pick(availableRecipes);
     const tokens = {
       principal: pickCompatibleToken(
         rng,
@@ -1003,6 +1090,7 @@ function generateRevisitContract(
   // Recipes the pinned identity can satisfy: principal groups must intersect,
   // and any site-using recipe needs a remembered site compatible with it.
   const candidates = CONTRACT_RECIPES.filter(recipe => {
+    if (!recipeIsAvailable(recipe, context)) return false;
     if (!groupsIntersect(principal.groups, recipe.principalGroups)) return false;
     if (recipe.siteGroups) {
       return !!siteToken && groupsIntersect(siteToken.groups, recipe.siteGroups);
@@ -1045,8 +1133,10 @@ function generatePrincipalBiasedContract(
   if (!scoreTarget.principal) return null;
   const principal = lexiconTokenFrom(scoreTarget.principal);
   const avoidedSiteId = scoreTarget.site?.id;
-  const candidates = CONTRACT_RECIPES.filter(recipe =>
-    groupsIntersect(principal.groups, recipe.principalGroups)
+  const candidates = CONTRACT_RECIPES.filter(
+    recipe =>
+      recipeIsAvailable(recipe, context) &&
+      groupsIntersect(principal.groups, recipe.principalGroups)
   );
   if (candidates.length === 0) return null;
 
diff --git a/tests/unit/game/hub/cyberContract.test.ts b/tests/unit/game/hub/cyberContract.test.ts
new file mode 100644
index 0000000..11e57dd
--- /dev/null
+++ b/tests/unit/game/hub/cyberContract.test.ts
@@ -0,0 +1,230 @@
+/**
+ * P3.M3.1 — Cyberspace-capable contract metadata + gates.
+ *
+ * The DATA_NODE_SLICE objective kind carries `requiresCyberspace: true` in its
+ * params, is generated only in Act 2+ when a living Decker is on the roster,
+ * and deploying such a contract with anyone but a living Decker fails loudly
+ * at the Hub boundary.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  Curator,
+  OBJECTIVES,
+  CONTRACT_RECIPES,
+  assertLabelObjectiveRegistryInSync,
+  contractRequiresCyberspace,
+  normalizeObjective,
+} from '../../../../src/game/hub/Curator.js';
+import { Campaign, CAMPAIGN_STATE } from '../../../../src/game/Campaign.js';
+import { RUN_STATE } from '../../../../src/game/Run.js';
+import { Rng } from '../../../../src/rng.js';
+import { testContractContext } from '../contractTestUtils.js';
+import type { Contract } from '../../../../src/game/hub/Curator.js';
+import type { CampaignArcStage } from '../../../../src/types.js';
+
+const cyberObjective = (
+  params: Record<string, string | number | boolean> | null = {
+    requiresCyberspace: true,
+    count: 1,
+  }
+) => ({
+  kind: OBJECTIVES.DATA_NODE_SLICE,
+  title: 'Spike the server farm',
+  briefing: 'Jack in, slice the data node, then extract.',
+  ...(params ? { params } : {}),
+});
+
+const cyberContract = (overrides: Partial<Contract> = {}): Contract =>
+  ({
+    seed: 12345,
+    mapWidth: 24,
+    mapHeight: 16,
+    objective: cyberObjective(),
+    difficulty: 'standard',
+    threatCount: 1,
+    label: '// test cyber job',
+    context: testContractContext(OBJECTIVES.DATA_NODE_SLICE),
+    reward: { credits: 0, repDelta: 0 },
+    ...overrides,
+  }) as Contract;
+
+// --- objective validation -------------------------------------------------
+
+test('normalizeObjective accepts a well-formed data-node-slice objective', () => {
+  const normalized = normalizeObjective(cyberObjective());
+  assert.equal(normalized.kind, OBJECTIVES.DATA_NODE_SLICE);
+  assert.equal(normalized.params?.requiresCyberspace, true);
+  assert.equal(normalized.params?.count, 1);
+});
+
+test('normalizeObjective throws on data-node-slice without requiresCyberspace', () => {
+  assert.throws(() => normalizeObjective(cyberObjective(null)), /requiresCyberspace/);
+  assert.throws(() => normalizeObjective(cyberObjective({ count: 1 })), /requiresCyberspace/);
+  assert.throws(
+    () => normalizeObjective(cyberObjective({ requiresCyberspace: false, count: 1 })),
+    /requiresCyberspace/
+  );
+  assert.throws(
+    () => normalizeObjective(cyberObjective({ requiresCyberspace: 'yes', count: 1 })),
+    /requiresCyberspace/
+  );
+});
+
+test('normalizeObjective throws on data-node-slice with a malformed count', () => {
+  assert.throws(
+    () => normalizeObjective(cyberObjective({ requiresCyberspace: true })),
+    /count/
+  );
+  assert.throws(
+    () => normalizeObjective(cyberObjective({ requiresCyberspace: true, count: 0 })),
+    /count/
+  );
+  assert.throws(
+    () => normalizeObjective(cyberObjective({ requiresCyberspace: true, count: 1.5 })),
+    /count/
+  );
+});
+
+test('normalizeObjective throws when requiresCyberspace appears on a non-cyber kind', () => {
+  assert.throws(
+    () =>
+      normalizeObjective({
+        kind: OBJECTIVES.RETRIEVE,
+        title: 'Secure cache',
+        briefing: 'Find the cache.',
+        params: { requiresCyberspace: true },
+      }),
+    /requiresCyberspace/
+  );
+});
+
+test('contractRequiresCyberspace is true only for validated cyber contracts', () => {
+  assert.equal(contractRequiresCyberspace(cyberContract()), true);
+  assert.equal(
+    contractRequiresCyberspace(
+      cyberContract({
+        objective: {
+          kind: OBJECTIVES.REACH_EXIT,
+          title: 'Extract clean',
+          briefing: 'Reach the exit.',
+        },
+      })
+    ),
+    false
+  );
+});
+
+// --- recipe + generation gating --------------------------------------------
+
+test('a cyber-data-spike recipe covers the data-node-slice kind', () => {
+  const recipe = CONTRACT_RECIPES.find(r => r.objectiveKind === OBJECTIVES.DATA_NODE_SLICE);
+  assert.ok(recipe, 'expected a recipe covering data-node-slice');
+  assertLabelObjectiveRegistryInSync();
+});
+
+function boardKinds(arcStage: CampaignArcStage, hasLivingDecker: boolean, seeds: number) {
+  const curator = new Curator();
+  const kinds: string[] = [];
+  for (let seed = 1; seed <= seeds; seed++) {
+    for (const contract of curator.generateContracts(new Rng(seed), {
+      rep: 60,
+      arcStage,
+      hasLivingDecker,
+    })) {
+      kinds.push(contract.objective.kind);
+    }
+  }
+  return kinds;
+}
+
+test('data-node-slice never generates in Act 1, even with a living Decker', () => {
+  assert.ok(!boardKinds('act-1', true, 40).includes(OBJECTIVES.DATA_NODE_SLICE));
+});
+
+test('data-node-slice never generates without a living Decker', () => {
+  assert.ok(!boardKinds('act-2', false, 40).includes(OBJECTIVES.DATA_NODE_SLICE));
+  // Plain campaign fixtures that never mention the Decker behave the same.
+  const curator = new Curator();
+  for (let seed = 1; seed <= 40; seed++) {
+    for (const contract of curator.generateContracts(new Rng(seed), {
+      rep: 60,
+      arcStage: 'act-2',
+    })) {
+      assert.notEqual(contract.objective.kind, OBJECTIVES.DATA_NODE_SLICE);
+    }
+  }
+});
+
+test('data-node-slice generates in Act 2+ with a living Decker, validated and door-free', () => {
+  const curator = new Curator();
+  let found = 0;
+  for (let seed = 1; seed <= 40; seed++) {
+    for (const contract of curator.generateContracts(new Rng(seed), {
+      rep: 60,
+      arcStage: 'act-2',
+      hasLivingDecker: true,
+    })) {
+      if (contract.objective.kind !== OBJECTIVES.DATA_NODE_SLICE) continue;
+      found += 1;
+      assert.equal(contractRequiresCyberspace(contract), true);
+      assert.equal(contract.objective.params?.requiresCyberspace, true);
+      assert.equal(typeof contract.objective.params?.count, 'number');
+      // Cyber contracts route through the jack-in port, not prefab doors.
+      assert.equal(contract.objective.params?.requiresUnlock, undefined);
+    }
+  }
+  assert.ok(found > 0, 'expected at least one cyber contract across 40 seeded boards');
+});
+
+test('cyber-capable board generation is deterministic per seed', () => {
+  const campaign = { rep: 60, arcStage: 'act-2' as const, hasLivingDecker: true };
+  const a = new Curator().generateContracts(new Rng(777), campaign);
+  const b = new Curator().generateContracts(new Rng(777), campaign);
+  assert.deepEqual(a, b);
+});
+
+// --- Campaign deploy gate ---------------------------------------------------
+
+/** Act-2 campaign whose arc transition has auto-assigned a Decker (P3.M1.2). */
+function act2CampaignWithDecker(): Campaign {
+  const campaign = new Campaign({ seed: 42, rep: 60, completedJobs: 4 });
+  assert.equal(campaign.arcStage, 'act-2');
+  assert.ok(campaign.crew.some(m => m.archetype === 'Decker'));
+  return campaign;
+}
+
+test('Campaign.hasLivingDecker tracks roster state', () => {
+  const fresh = new Campaign({ seed: 42 });
+  assert.equal(fresh.hasLivingDecker, false);
+
+  const campaign = act2CampaignWithDecker();
+  assert.equal(campaign.hasLivingDecker, true);
+
+  const decker = campaign.crew.find(m => m.archetype === 'Decker')!;
+  campaign.flatlineMember(decker.id);
+  assert.equal(campaign.hasLivingDecker, false);
+});
+
+test('deploying a non-Decker on a cyber contract throws at the Hub boundary', () => {
+  const campaign = act2CampaignWithDecker();
+  const merc = campaign.crew.find(m => m.archetype !== 'Decker')!;
+  assert.throws(() => campaign.deployCrewMember(merc.id, cyberContract()), /Decker/);
+  assert.equal(campaign.state, CAMPAIGN_STATE.HUB, 'failed deploy must not leave the Hub');
+});
+
+test('a living Decker deploys onto a cyber contract', () => {
+  const campaign = act2CampaignWithDecker();
+  const decker = campaign.crew.find(m => m.archetype === 'Decker')!;
+  const run = campaign.deployCrewMember(decker.id, cyberContract());
+  assert.equal(run.state, RUN_STATE.BRIEFING);
+  assert.equal(campaign.state, CAMPAIGN_STATE.COMBAT);
+});
+
+test('a flatlined Decker cannot deploy onto a cyber contract', () => {
+  const campaign = act2CampaignWithDecker();
+  const decker = campaign.crew.find(m => m.archetype === 'Decker')!;
+  campaign.flatlineMember(decker.id);
+  assert.throws(() => campaign.deployCrewMember(decker.id, cyberContract()), /flatlined/);
+});

From 3719fdc67bd29614e9119fc8f3ad8bd1e31ca808 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Tue, 9 Jun 2026 21:24:32 -0700
Subject: [PATCH 14/55] =?UTF-8?q?P3.M3.2:=20jack-in=20point=20=E2=80=94=20?=
 =?UTF-8?q?the=20Meatspace=20door=20into=20Cyberspace?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

JackInPoint interactable (Ω) placed for data-node-slice contracts: Decker-only
capability sniff, linked latch with logged (never thrown) redundant input,
one-shot EVENT.JACK_IN emit. Run latches a dormant cyberspace state machine at
briefing; snapshot/restore enforce the block ⇔ cyber-contract invariant and
throw on unknown phases, dormant payload smuggling, or missing linked state.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/game/Run.ts                     |  64 +++++++
 src/game/archetypes/Decker.ts       |   6 +
 src/game/constants.ts               |   2 +
 src/game/entities/JackInPoint.ts    |  67 ++++++++
 src/game/events.ts                  |   4 +
 src/game/persistence.ts             |  74 +++++++-
 tests/unit/game/jackInPoint.test.ts | 255 ++++++++++++++++++++++++++++
 7 files changed, 470 insertions(+), 2 deletions(-)
 create mode 100644 src/game/entities/JackInPoint.ts
 create mode 100644 tests/unit/game/jackInPoint.test.ts

diff --git a/src/game/Run.ts b/src/game/Run.ts
index f992e2d..ed33b2d 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -78,6 +78,7 @@ import { RelayNode } from './entities/RelayNode.js';
 import { ConsumablePickup } from './entities/ConsumablePickup.js';
 import { EscortNpc } from './entities/EscortNpc.js';
 import { KeyCard } from './entities/KeyCard.js';
+import { JackInPoint } from './entities/JackInPoint.js';
 import { applyMutationDeltas } from './locations.js';
 import { BreachingCharge } from './entities/BreachingCharge.js';
 import { ITEM_ID, getItemById } from './items.js';
@@ -93,6 +94,7 @@ import { VisionField } from './Vision.js';
 import {
   OBJECTIVES,
   cloneObjective,
+  contractRequiresCyberspace,
   isContractDifficulty,
   normalizeContractContext,
   normalizeObjective,
@@ -119,6 +121,7 @@ import type { SyncPadSnapshot } from './entities/SyncPad.js';
 import type { RelayNodeSnapshot } from './entities/RelayNode.js';
 import type { ConsumablePickupSnapshot } from './entities/ConsumablePickup.js';
 import type { EscortNpcSnapshot } from './entities/EscortNpc.js';
+import type { JackInPointSnapshot } from './entities/JackInPoint.js';
 import type { KeyCardSnapshot } from './entities/KeyCard.js';
 import type { AlarmState } from './World.js';
 
@@ -163,6 +166,7 @@ export type EntityArchetypeId =
   | 'escort-npc'
   | 'keycard'
   | 'breaching-charge'
+  | 'jack-in-point'
   | 'entity';
 
 export type RunTelemetry = {
@@ -273,6 +277,31 @@ export type RunSnapshot = {
   keyItems?: KeyItemSnapshot[];
   /** Terrain/entity mutations recorded during the run (P2.5.M7.1). Defaults to []. */
   mutationDeltas?: TileDelta[];
+  /**
+   * P3.M3: Cyberspace layer state. Present exactly when the contract requires
+   * Cyberspace (`contractRequiresCyberspace`) — a mismatch in either direction
+   * is corrupt and throws on restore.
+   */
+  cyberspace?: RunCyberspaceSnapshot;
+};
+
+/**
+ * P3.M3: serialized Cyberspace layer state. The `dormant` phase carries no
+ * payload — the layer spawns fresh on jack-in. P3.M3.3 extends this with the
+ * `active` (grid + entities) and `resolved` (objective latch) phases.
+ */
+export type RunCyberspaceSnapshot = {
+  phase: 'dormant';
+};
+
+/**
+ * P3.M3: live Cyberspace state machine on the Run. `null` ⇔ the contract has
+ * no Cyberspace component. P3.M3.3 extends the union with
+ * `{ phase: 'active'; layer: CyberspaceLayer }` and
+ * `{ phase: 'resolved'; objectiveComplete: boolean }`.
+ */
+export type CyberspaceState = {
+  phase: 'dormant';
 };
 
 /** Serializable run-scoped key item (P2.5.M6.2). */
@@ -335,6 +364,8 @@ export class Run {
   player: Crew | null;
   contract: Contract | null;
   exitTile: GridPoint | null;
+  /** P3.M3: Cyberspace state machine; `null` ⇔ no Cyberspace component. */
+  cyberspace: CyberspaceState | null;
   telemetry: RunTelemetry;
   objectiveTimer: ObjectiveTimerSnapshot;
   mapSeen: Set<string>;
@@ -402,6 +433,7 @@ export class Run {
     this.player = null;
     this.contract = null;
     this.exitTile = null;
+    this.cyberspace = null;
     this.telemetry = freshTelemetry(this.archetype, this.seed);
     this.objectiveTimer = freshObjectiveTimer();
     this.mapSeen = new Set();
@@ -428,6 +460,8 @@ export class Run {
       throw new Error(`Run.enterBriefing: illegal transition from ${this.state}`);
     }
     this.contract = normalizeContractForRun(contract);
+    // P3.M3: latch the Cyberspace state machine off the validated contract.
+    this.cyberspace = contractRequiresCyberspace(this.contract) ? { phase: 'dormant' } : null;
     this.objectiveTimer = freshObjectiveTimer();
     this.mapSeen.clear();
     this.state = RUN_STATE.BRIEFING;
@@ -731,6 +765,8 @@ export class Run {
       objectiveProgress: { securedPickups: world.securedPickupIds() },
       keyItems: this.keyItems.map(k => ({ id: k.id, label: k.label, doorId: k.doorId })),
       mutationDeltas: world.mutationDeltas.map(delta => ({ ...delta })),
+      // P3.M3: present exactly when the contract has a Cyberspace component.
+      ...(this.cyberspace ? { cyberspace: snapshotCyberspace(this.cyberspace) } : {}),
     };
   }
 
@@ -1154,6 +1190,18 @@ export class Run {
         })
       );
     }
+    if (this.contract.objective.kind === OBJECTIVES.DATA_NODE_SLICE) {
+      // P3.M3.2: the Meatspace door into Cyberspace. One port per contract;
+      // the data nodes themselves live on the cyber grid (P3.M3.3+).
+      const anchor = findInteractableAnchor(this.world, this.player, this.exitTile, this.rng);
+      this.world.addEntity(
+        new JackInPoint({
+          id: 'jack-in-0',
+          x: anchor.x,
+          y: anchor.y,
+        })
+      );
+    }
     if (this.contract.objective.kind === OBJECTIVES.RETRIEVE) {
       const count = objectiveCount(this.contract);
       for (let i = 0; i < count; i++) {
@@ -1738,8 +1786,23 @@ const SNAPSHOT_EXTRACTORS: Partial<Record<EntityArchetypeId, (e: Entity) => Enti
         siteId: k.siteId ?? null,
       } satisfies KeyCardSnapshot;
     },
+    'jack-in-point': e => {
+      const p = e as JackInPoint;
+      return { label: p.label, linked: p.linked } satisfies JackInPointSnapshot;
+    },
   };
 
+/**
+ * P3.M3: serialize the Cyberspace state machine. Dormant carries no payload;
+ * P3.M3.3 adds the active-layer grid/entities and the resolved latch.
+ */
+function snapshotCyberspace(state: CyberspaceState): RunCyberspaceSnapshot {
+  if (state.phase === 'dormant') return { phase: 'dormant' };
+  throw new Error(
+    `Run.snapshot: unknown cyberspace phase "${(state as { phase: string }).phase}"`
+  );
+}
+
 function snapshotEntity(entity: Entity): RunEntitySnapshot {
   const archetype = archetypeOf(entity);
   const base: RunEntitySnapshot = {
@@ -1794,6 +1857,7 @@ function archetypeOf(entity: Entity): EntityArchetypeId {
   if (entity instanceof ConsumablePickup) return 'consumable-pickup';
   if (entity instanceof EscortNpc) return 'escort-npc';
   if (entity instanceof KeyCard) return 'keycard';
+  if (entity instanceof JackInPoint) return 'jack-in-point';
   if (entity instanceof BreachingCharge) return 'breaching-charge';
   if (entity instanceof Entity) return 'entity';
   throw new Error(`archetypeOf: cannot classify entity ${(entity as Entity | undefined)?.id}`);
diff --git a/src/game/archetypes/Decker.ts b/src/game/archetypes/Decker.ts
index 188a374..f7dcc53 100644
--- a/src/game/archetypes/Decker.ts
+++ b/src/game/archetypes/Decker.ts
@@ -39,6 +39,12 @@ export const CALLSIGNS = Object.freeze([
 export class Decker extends Crew {
   override archetype = 'Decker';
 
+  /**
+   * P3.M3.2: capability sniffed by `JackInPoint.interact` — only an actor
+   * carrying a cyberdeck can open the digital layer.
+   */
+  readonly canJackIn = true;
+
   override get baseHitChance(): number {
     return 0.7;
   }
diff --git a/src/game/constants.ts b/src/game/constants.ts
index 61e277a..84ce1af 100644
--- a/src/game/constants.ts
+++ b/src/game/constants.ts
@@ -44,6 +44,8 @@ export const DENY_TARGET_GLYPH = '◆';
 export const SYNC_PAD_GLYPH = '§';
 export const ESCORT_NPC_GLYPH = 'A';
 export const KEYCARD_GLYPH = 'κ';
+/** P3.M3.2: the Meatspace door into Cyberspace. */
+export const JACK_IN_GLYPH = 'Ω';
 
 /** Numeric tile id — one of the `TILE` values. */
 export type TileId = (typeof TILE)[keyof typeof TILE];
diff --git a/src/game/entities/JackInPoint.ts b/src/game/entities/JackInPoint.ts
new file mode 100644
index 0000000..f2db958
--- /dev/null
+++ b/src/game/entities/JackInPoint.ts
@@ -0,0 +1,67 @@
+/**
+ * P3.M3.2 — Jack-in point: the Meatspace door into Cyberspace.
+ *
+ * Placed for `data-node-slice` contracts. Only a Decker can link (capability
+ * sniff on `canJackIn`); a successful link spends interact AP, latches
+ * `linked`, and emits `EVENT.JACK_IN` exactly once — `Run` listens and spawns
+ * the Cyberspace layer (P3.M3.3). Re-interacting a linked port is *redundant
+ * input*, not corruption: it returns a logged refusal and never throws.
+ *
+ * The id is namespaced `jack-in-*` deliberately — `Run`'s TERMINAL_SLICE
+ * satisfaction counts terminals by the `/^terminal-\d+$/` id pattern, and this
+ * port must never satisfy a slice quota.
+ */
+import { Interactable, type InteractableInit, type InteractResult } from './Interactable.js';
+import { AP_COST, JACK_IN_GLYPH } from '../constants.js';
+import { EVENT } from '../events.js';
+import type { Entity } from '../Entity.js';
+import type { World } from '../World.js';
+
+export interface JackInPointInit extends Omit<InteractableInit, 'glyph' | 'label'> {
+  label?: string;
+  linked?: boolean;
+}
+
+/** P2.7.M6.2: JackInPoint snapshot `extra`. */
+export type JackInPointSnapshot = {
+  label: string;
+  linked: boolean;
+};
+
+export class JackInPoint extends Interactable {
+  linked: boolean;
+
+  constructor({ label = 'Jack-in port', linked = false, ...props }: JackInPointInit) {
+    super({
+      ...props,
+      glyph: JACK_IN_GLYPH,
+      label,
+      secured: linked,
+      armed: !linked,
+    });
+    this.linked = !!linked;
+  }
+
+  override interact(world: World, actor: Entity): InteractResult {
+    if (this.linked) {
+      return { ok: false, reason: 'already-linked', message: `${this.label}: already linked.` };
+    }
+    const check = this.canInteract(actor);
+    if (!check.ok) {
+      return { ok: false, reason: check.reason, message: `${this.label}: ${check.reason}.` };
+    }
+    if ((actor as { canJackIn?: boolean }).canJackIn !== true) {
+      return {
+        ok: false,
+        reason: 'no-cyberdeck',
+        message: `${this.label}: no cyberdeck — only a Decker can jack in.`,
+      };
+    }
+    actor.spendAp(AP_COST.INTERACT);
+    this.linked = true;
+    this.secured = true;
+    this.armed = false;
+    world.events?.emit(EVENT.JACK_IN, { point: this, actor });
+    return { ok: true, message: `${this.label}: link established.` };
+  }
+}
diff --git a/src/game/events.ts b/src/game/events.ts
index 0cc6fb9..c5a5ae2 100644
--- a/src/game/events.ts
+++ b/src/game/events.ts
@@ -33,6 +33,10 @@ export const EVENT = Object.freeze({
   HAZARD_DAMAGE: 'hazard:damage',
   OBJECTIVE_TIMER_EXPIRED: 'objective:timer-expired',
   DOOR_UNLOCKED: 'door:unlocked',
+  /** P3.M3.2: a Decker linked a jack-in point. Payload `{ point, actor }`. */
+  JACK_IN: 'cyber:jack-in',
+  /** P3.M3: the Decker left the grid (voluntary or forced). */
+  JACK_OUT: 'cyber:jack-out',
 });
 
 const KNOWN_TYPES = new Set<string>(Object.values(EVENT));
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index d22e937..0f76ebb 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -71,11 +71,16 @@ import { RelayNode } from './entities/RelayNode.js';
 import { ConsumablePickup } from './entities/ConsumablePickup.js';
 import { EscortNpc } from './entities/EscortNpc.js';
 import { KeyCard } from './entities/KeyCard.js';
+import { JackInPoint } from './entities/JackInPoint.js';
 import { BreachingCharge } from './entities/BreachingCharge.js';
 import type { BreachingChargeInit } from './entities/BreachingCharge.js';
 import { Run, RUN_STATE, PATROL_ARCHETYPE_IDS } from './Run.js';
 import { Campaign, CAMPAIGN_STATE, normalizeCampaignArc } from './Campaign.js';
-import { normalizeContractContext, normalizeObjective } from './hub/Curator.js';
+import {
+  contractRequiresCyberspace,
+  normalizeContractContext,
+  normalizeObjective,
+} from './hub/Curator.js';
 import {
   migrateLegacyHubReveals,
   normalizeHubReveals,
@@ -97,6 +102,7 @@ import type { RelayNodeInit } from './entities/RelayNode.js';
 import type { ConsumablePickupInit } from './entities/ConsumablePickup.js';
 import type { EscortNpcInit } from './entities/EscortNpc.js';
 import type { KeyCardInit } from './entities/KeyCard.js';
+import type { JackInPointInit, JackInPointSnapshot } from './entities/JackInPoint.js';
 import type { EntityInit } from './Entity.js';
 import type { CampaignArc } from './Campaign.js';
 import type { FactionId } from './constants.js';
@@ -112,6 +118,7 @@ import type {
   ObjectiveTimerSnapshot,
   MapMemorySnapshot,
   ObjectiveProgressSnapshot,
+  CyberspaceState,
 } from './Run.js';
 import type { CrewSnapshot } from './Crew.js';
 import type { TechSnapshot } from './archetypes/Tech.js';
@@ -162,7 +169,8 @@ type RestoreEntityProps = Partial<
     ConsumablePickupInit &
     EscortNpcInit &
     KeyCardInit &
-    BreachingChargeInit
+    BreachingChargeInit &
+    JackInPointInit
 > & {
   id: string;
   x: number;
@@ -205,6 +213,7 @@ const ARCHETYPE_FACTORY: Record<EntityArchetypeId, (props: RestoreEntityProps) =
       new ConsumablePickup(props as ConsumablePickupInit),
     'escort-npc': (props: RestoreEntityProps) => new EscortNpc(props as EscortNpcInit),
     keycard: (props: RestoreEntityProps) => new KeyCard(props as KeyCardInit),
+    'jack-in-point': (props: RestoreEntityProps) => new JackInPoint(props as JackInPointInit),
     'breaching-charge': (props: RestoreEntityProps) =>
       new BreachingCharge(props as BreachingChargeInit),
     // Generic fallback so a future `Entity` subclass (NPCs, items) doesn't break
@@ -340,6 +349,17 @@ function readTerminal(extra: EntitySnapshotExtra, id: string): TerminalSnapshot
   };
 }
 
+function readJackInPoint(extra: EntitySnapshotExtra, id: string): JackInPointSnapshot {
+  if (hasNoState(extra)) {
+    throw new TypeError(`restore: jack-in point entity ${id} requires jack-in state`);
+  }
+  const p = extra as Partial<JackInPointSnapshot>;
+  return {
+    label: requireString(p.label, `restore: jack-in point ${id} label must be a non-empty string`),
+    linked: requireBoolean(p.linked, `restore: jack-in point ${id} linked must be boolean`),
+  };
+}
+
 function readDoor(extra: EntitySnapshotExtra, id: string): DoorSnapshot {
   if (hasNoState(extra)) throw new TypeError(`restore: door entity ${id} requires door state`);
   const d = extra as Partial<DoorSnapshot>;
@@ -582,6 +602,17 @@ const ENTITY_RESTORE: Partial<Record<EntityArchetypeId, RestoreEntry>> = Object.
       return { label: typeof r.label === 'string' && r.label.length > 0 ? r.label : 'Relay node' };
     },
   },
+  'jack-in-point': {
+    buildProps(extra, rec) {
+      const p = readJackInPoint(extra, rec.id);
+      return { label: p.label, linked: p.linked };
+    },
+    apply(entity, _extra, rec) {
+      if (!(entity instanceof JackInPoint)) {
+        throw new Error(`restore: jack-in point entity ${rec.id} did not restore as JackInPoint`);
+      }
+    },
+  },
   terminal: {
     buildProps(extra, rec) {
       const t = readTerminal(extra, rec.id);
@@ -906,6 +937,7 @@ export function restore(record: unknown, options: RestoreOptions = {}) {
   run.rng = new Rng(record.rng.seed);
   run.rng.setState(record.rng.state);
   run.contract = normalizeContract(record.contract);
+  run.cyberspace = restoreCyberspace(record, run.contract !== null && contractRequiresCyberspace(run.contract));
   run.exitTile = record.exitTile ? { ...record.exitTile } : null;
   run.telemetry = { ...record.telemetry };
   run.objectiveTimer = normalizeObjectiveTimer(record.objectiveTimer);
@@ -961,6 +993,44 @@ export function restore(record: unknown, options: RestoreOptions = {}) {
   return { run, world: run.world, queue: run.queue, rng: run.rng, player: run.player };
 }
 
+/**
+ * P3.M3: rebuild the Cyberspace state machine from its snapshot block.
+ *
+ * Invariant (both directions): a contract with a Cyberspace component
+ * (`contractRequiresCyberspace`) carries a `cyberspace` block, and only such
+ * contracts do. Any mismatch, unknown phase, or payload smuggled onto the
+ * `dormant` phase is tier-1 corrupt state and throws. P3.M3.3 extends this
+ * with the `active` (grid + entities) and `resolved` (latch) phases.
+ */
+function restoreCyberspace(record: RunSnapshot, requiresCyberspace: boolean): CyberspaceState | null {
+  const block = record.cyberspace;
+  if (!requiresCyberspace) {
+    if (block !== undefined && block !== null) {
+      throw new Error(
+        'restore: cyberspace block present on a contract without a Cyberspace component'
+      );
+    }
+    return null;
+  }
+  if (block === undefined || block === null) {
+    throw new Error('restore: Cyberspace contract snapshot is missing its cyberspace block');
+  }
+  if (typeof block !== 'object' || Array.isArray(block)) {
+    throw new TypeError('restore: cyberspace block must be an object');
+  }
+  const phase = (block as { phase?: unknown }).phase;
+  if (phase === 'dormant') {
+    const payloadKeys = Object.keys(block).filter(key => key !== 'phase');
+    if (payloadKeys.length > 0) {
+      throw new Error(
+        `restore: dormant cyberspace block must carry no payload, got [${payloadKeys.join(', ')}]`
+      );
+    }
+    return { phase: 'dormant' };
+  }
+  throw new Error(`restore: unknown cyberspace phase "${String(phase)}"`);
+}
+
 export function restoreCampaign(record: unknown, options: RestoreCampaignOptions = {}): Campaign {
   validateCampaignRecord(record);
   const crew = record.crew.map(restoreCrewMember);
diff --git a/tests/unit/game/jackInPoint.test.ts b/tests/unit/game/jackInPoint.test.ts
new file mode 100644
index 0000000..4614777
--- /dev/null
+++ b/tests/unit/game/jackInPoint.test.ts
@@ -0,0 +1,255 @@
+/**
+ * P3.M3.2 — Jack-in point: the Meatspace door into Cyberspace.
+ *
+ * A `JackInPoint` is placed for data-node-slice contracts. Only a Decker can
+ * link (capability sniff on `canJackIn`); linking emits `EVENT.JACK_IN` once;
+ * redundant input logs (never throws); state round-trips through persistence.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { Grid } from '../../../src/game/Grid.js';
+import { World } from '../../../src/game/World.js';
+import { Run, RUN_STATE } from '../../../src/game/Run.js';
+import { JackInPoint } from '../../../src/game/entities/JackInPoint.js';
+import { EventBus, EVENT } from '../../../src/game/events.js';
+import { snapshot, restore } from '../../../src/game/persistence.js';
+import { buildCrewMember } from '../../../src/game/archetypes/index.js';
+import { AP_COST, TILE } from '../../../src/game/constants.js';
+import { OBJECTIVES } from '../../../src/game/hub/Curator.js';
+import { Rng } from '../../../src/rng.js';
+import { testContractContext } from './contractTestUtils.js';
+
+const fakeContract = (overrides = {}) => ({
+  seed: 12345,
+  objective: {
+    kind: OBJECTIVES.REACH_EXIT,
+    title: 'Extract clean',
+    briefing: 'Reach the exit.',
+  },
+  difficulty: 'standard',
+  threatCount: 1,
+  label: 'test job',
+  context: testContractContext(OBJECTIVES.REACH_EXIT),
+  reward: { credits: 0, repDelta: 0 },
+  ...overrides,
+});
+
+const cyberContract = (overrides = {}) =>
+  fakeContract({
+    objective: {
+      kind: OBJECTIVES.DATA_NODE_SLICE,
+      title: 'Spike the server farm',
+      briefing: 'Jack in, slice the data node, then extract.',
+      params: { requiresCyberspace: true, count: 1 },
+    },
+    label: 'cyber test job',
+    context: testContractContext(OBJECTIVES.DATA_NODE_SLICE),
+    ...overrides,
+  });
+
+function openWorld(width = 7, height = 5) {
+  const grid = new Grid(width, height);
+  return new World(grid, { events: new EventBus() });
+}
+
+function makeDecker(x = 1, y = 1) {
+  return buildCrewMember('decker', { x, y }, new Rng(100), { id: 'crew-decker' });
+}
+
+function makeMerc(x = 1, y = 1) {
+  return buildCrewMember('merc', { x, y }, new Rng(101), { id: 'crew-merc' });
+}
+
+function readyForCombat(member: ReturnType<typeof makeDecker>) {
+  member.ap = member.maxAp = 4;
+  return member;
+}
+
+// --- interact behavior ------------------------------------------------------
+
+test('a non-Decker cannot link: refused, no AP spent, no event', () => {
+  const world = openWorld();
+  const merc = readyForCombat(makeMerc(1, 1));
+  const point = new JackInPoint({ id: 'jack-in-0', x: 2, y: 1 });
+  world.addEntity(merc);
+  world.addEntity(point);
+  let events = 0;
+  world.events!.on(EVENT.JACK_IN, () => events++);
+
+  const apBefore = merc.ap;
+  const result = point.interact(world, merc);
+  assert.equal(result.ok, false);
+  assert.match((result as { reason: string }).reason, /cyberdeck|decker/i);
+  assert.equal(merc.ap, apBefore);
+  assert.equal(point.linked, false);
+  assert.equal(events, 0);
+});
+
+test('a Decker links: AP debited, linked latched, one JACK_IN event', () => {
+  const world = openWorld();
+  const decker = readyForCombat(makeDecker(1, 1));
+  const point = new JackInPoint({ id: 'jack-in-0', x: 2, y: 1 });
+  world.addEntity(decker);
+  world.addEntity(point);
+  const payloads: unknown[] = [];
+  world.events!.on(EVENT.JACK_IN, payload => payloads.push(payload));
+
+  const apBefore = decker.ap;
+  const result = point.interact(world, decker);
+  assert.equal(result.ok, true);
+  assert.equal(decker.ap, apBefore - AP_COST.INTERACT);
+  assert.equal(point.linked, true);
+  assert.equal(payloads.length, 1);
+  const payload = payloads[0] as { point: JackInPoint; actor: unknown };
+  assert.equal(payload.point, point);
+  assert.equal(payload.actor, decker);
+});
+
+test('re-linking is redundant input: logged refusal, no second event, no AP', () => {
+  const world = openWorld();
+  const decker = readyForCombat(makeDecker(1, 1));
+  const point = new JackInPoint({ id: 'jack-in-0', x: 2, y: 1 });
+  world.addEntity(decker);
+  world.addEntity(point);
+  let events = 0;
+  world.events!.on(EVENT.JACK_IN, () => events++);
+
+  assert.equal(point.interact(world, decker).ok, true);
+  const apAfterLink = decker.ap;
+  const repeat = point.interact(world, decker);
+  assert.equal(repeat.ok, false);
+  assert.equal((repeat as { reason: string }).reason, 'already-linked');
+  assert.equal(decker.ap, apAfterLink);
+  assert.equal(events, 1);
+});
+
+test('linking requires adjacency', () => {
+  const world = openWorld();
+  const decker = readyForCombat(makeDecker(1, 1));
+  const point = new JackInPoint({ id: 'jack-in-0', x: 4, y: 1 });
+  world.addEntity(decker);
+  world.addEntity(point);
+  const result = point.interact(world, decker);
+  assert.equal(result.ok, false);
+  assert.equal((result as { reason: string }).reason, 'not-adjacent');
+});
+
+// --- Run placement ------------------------------------------------------------
+
+function combatRun(seed = 12345) {
+  const run = new Run({ crewMember: makeDecker(0, 0), seed });
+  run.enterBriefing(cyberContract({ seed }));
+  run.enterCombat();
+  return run;
+}
+
+function jackInPoints(run: Run): JackInPoint[] {
+  return Array.from(run.world!.entities.values()).filter(
+    (e): e is JackInPoint => e instanceof JackInPoint
+  );
+}
+
+test('a cyber contract places exactly one jack-in point, deterministically', () => {
+  const a = combatRun();
+  const b = combatRun();
+  const pointsA = jackInPoints(a);
+  const pointsB = jackInPoints(b);
+  assert.equal(pointsA.length, 1);
+  assert.equal(pointsB.length, 1);
+  const point = pointsA[0];
+  assert.equal(point.id, 'jack-in-0');
+  assert.equal(point.linked, false);
+  assert.deepEqual({ x: point.x, y: point.y }, { x: pointsB[0].x, y: pointsB[0].y });
+  // The jack-in id must never count toward TERMINAL_SLICE objectives.
+  assert.ok(!/^terminal-\d+$/.test(point.id));
+  // Never stacked on the operator spawn or the exit tile.
+  assert.ok(point.x !== a.player!.x || point.y !== a.player!.y);
+  assert.ok(point.x !== a.exitTile!.x || point.y !== a.exitTile!.y);
+});
+
+test('non-cyber contracts place no jack-in point and carry no cyberspace state', () => {
+  const run = new Run({ crewMember: makeDecker(0, 0), seed: 999 });
+  run.enterBriefing(fakeContract({ seed: 999 }));
+  run.enterCombat();
+  assert.equal(jackInPoints(run).length, 0);
+  assert.equal(run.cyberspace, null);
+});
+
+test('a cyber contract latches dormant cyberspace state at briefing', () => {
+  const run = new Run({ crewMember: makeDecker(0, 0), seed: 12345 });
+  run.enterBriefing(cyberContract());
+  assert.deepEqual(run.cyberspace, { phase: 'dormant' });
+  assert.equal(run.state, RUN_STATE.BRIEFING);
+});
+
+// --- persistence ---------------------------------------------------------------
+
+test('jack-in point and dormant cyberspace state round-trip a snapshot', () => {
+  const run = combatRun();
+  const point = jackInPoints(run)[0];
+  point.linked = true;
+  point.secured = true;
+  point.armed = false;
+
+  const record = snapshot(run);
+  assert.deepEqual(record.cyberspace, { phase: 'dormant' });
+
+  const { run: restored } = restore(structuredClone(record));
+  const restoredPoint = jackInPoints(restored)[0];
+  assert.ok(restoredPoint, 'jack-in point survives the round-trip');
+  assert.equal(restoredPoint.linked, true);
+  assert.equal(restoredPoint.x, point.x);
+  assert.equal(restoredPoint.y, point.y);
+  assert.deepEqual(restored.cyberspace, { phase: 'dormant' });
+});
+
+test('non-cyber snapshots omit the cyberspace block', () => {
+  const run = new Run({ crewMember: makeDecker(0, 0), seed: 999 });
+  run.enterBriefing(fakeContract({ seed: 999 }));
+  run.enterCombat();
+  const record = snapshot(run);
+  assert.equal('cyberspace' in record && record.cyberspace !== undefined, false);
+  assert.equal(restore(structuredClone(record)).run.cyberspace, null);
+});
+
+test('restore throws on cyberspace/contract mismatches and malformed phases', () => {
+  const cyberRecord = snapshot(combatRun());
+
+  // Cyber contract without its cyberspace block is corrupt.
+  const missingBlock = structuredClone(cyberRecord) as Record<string, unknown>;
+  delete missingBlock.cyberspace;
+  assert.throws(() => restore(missingBlock), /cyberspace/);
+
+  // Unknown phase is corrupt.
+  const badPhase = structuredClone(cyberRecord);
+  (badPhase.cyberspace as { phase: string }).phase = 'jacked-sideways';
+  assert.throws(() => restore(badPhase), /phase/);
+
+  // Dormant must not smuggle payload fields.
+  const dormantPayload = structuredClone(cyberRecord);
+  (dormantPayload.cyberspace as Record<string, unknown>).grid = { w: 1, h: 1, tiles: [0] };
+  assert.throws(() => restore(dormantPayload), /dormant/);
+
+  // A cyberspace block on a non-cyber contract is corrupt.
+  const plainRun = new Run({ crewMember: makeDecker(0, 0), seed: 999 });
+  plainRun.enterBriefing(fakeContract({ seed: 999 }));
+  plainRun.enterCombat();
+  const plainRecord = structuredClone(snapshot(plainRun)) as Record<string, unknown>;
+  plainRecord.cyberspace = { phase: 'dormant' };
+  assert.throws(() => restore(plainRecord), /cyberspace/);
+});
+
+test('restore throws on a jack-in point record missing linked state', () => {
+  const record = structuredClone(snapshot(combatRun()));
+  const pointRec = record.entities.find(e => e.archetype === 'jack-in-point');
+  assert.ok(pointRec, 'snapshot carries the jack-in point');
+  delete (pointRec!.extra as Record<string, unknown>).linked;
+  assert.throws(() => restore(record), /linked/);
+});
+
+test('TILE smoke guard: jack-in anchor sits on a passable tile', () => {
+  const run = combatRun();
+  const point = jackInPoints(run)[0];
+  assert.notEqual(run.world!.grid.tileAt(point.x, point.y), TILE.WALL);
+});

From 96afb478e8ed35616c13d8978d12104a3a5da48e Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Tue, 9 Jun 2026 21:28:27 -0700
Subject: [PATCH 15/55] P3.M3 working plan: scope decisions, slice progress, S3
 worklist

Records the four scope decisions, S1/S2 implementation notes (shipped),
approved architecture for S3-S7, and verified research notes so the
Cyberspace effort can resume cold at S3.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/phase-3-cyberspace-plan.md | 389 ++++++++++++++++++++++++++++++++
 1 file changed, 389 insertions(+)
 create mode 100644 docs/phase-3-cyberspace-plan.md

diff --git a/docs/phase-3-cyberspace-plan.md b/docs/phase-3-cyberspace-plan.md
new file mode 100644
index 0000000..1347aa4
--- /dev/null
+++ b/docs/phase-3-cyberspace-plan.md
@@ -0,0 +1,389 @@
+# P3.M3 — Cyberspace Grid + ICE: Working Plan & Progress
+
+Working document for the P3.M3 implementation effort on branch `3.0-cyberspace`.
+Companion to [phase-3-plan.md](phase-3-plan.md) (the milestone spec); this file
+tracks the approved slice plan, recorded scope decisions, and live progress so
+the effort can be resumed cold.
+
+## Scope decisions (recorded 2026-06-09, Rylee)
+
+1. **First playable slice only** — slices M3.1–M3.6 (contract flag → jack-in
+   terminal → cyber layer model → data node objective → Probe ICE → render
+   swap). **Spark/Guardian ICE deferred** to follow-up slices; the milestone
+   stays open in phase-3-plan.md until they land.
+2. **Minimal voluntary jack-out pulled forward** from P3.M4.6 so the layer is
+   playable end-to-end solo before the simstim flip exists. M4.6 then only adds
+   forced jack-out + dual-deploy cleanup.
+3. **Avatar death = flatline** — ICE destroying the avatar kills the Decker
+   through the existing DEATH/flatline paths. Genre-honest (black ICE kills),
+   zero new death machinery.
+4. **Named cyber stats ship now with real effects**: RAM = avatar HP pool,
+   intrusion strength = slice progress per interact, ICE resistance =
+   `damageReduction` (existing min-1 mitigation in `Combat.ts`). Persisted and
+   validated in both crew persistence paths.
+
+TDD throughout; malformed persisted state throws (no silent fallbacks).
+Commits land **per green slice** (user-approved).
+
+## Progress
+
+| Slice | Status | Commit |
+|---|---|---|
+| **S1 — P3.M3.1 Contract flag + gates** | ✅ Done | `f436330` |
+| **S2 — P3.M3.2 Jack-in terminal** | ✅ Done | `05013f6` |
+| **S3 — P3.M3.3 Cyber layer model + avatar + persistence** | 🔨 In progress (research done, no code yet) | — |
+| **S4 — P3.M3.4 Data node objective** | 🔲 Planned | — |
+| **S5 — Voluntary jack-out (M4.6 pull-forward)** | 🔲 Planned | — |
+| **S6 — P3.M3.5 Probe ICE** | 🔲 Planned | — |
+| **S7 — P3.M3.6 Render/input swap + shell ICE phase** | 🔲 Planned | — |
+| **S8 — Docs + wrap-up** | 🔲 Planned | — |
+
+### S1 implementation notes (shipped)
+
+- `OBJECTIVES.DATA_NODE_SLICE = 'data-node-slice'` with cross-field validation
+  in `normalizeObjective` (`Curator.ts`): the kind requires
+  `params.requiresCyberspace === true` plus positive-integer `params.count`;
+  the flag is forbidden on every other kind. Validates at generation,
+  `Run.enterBriefing`, and snapshot restore (all call `normalizeObjective`).
+- `contractRequiresCyberspace(contract)` exported from `Curator.ts` — single
+  source of truth for "this contract has a Cyberspace component".
+- New recipe `cyber-data-spike` (params `{requiresCyberspace: true, count: 1}`,
+  no `targetParams` spread — placement is owned by the DATA_NODE_SLICE arm, and
+  no turn-limit/door-routing machinery engages). Gated by the new
+  `ContractRecipe.availableWhen?: (ctx) => boolean` hook: requires
+  `arcStage ∈ {act-2, act-3} && hasLivingDecker === true`.
+- `recipeIsAvailable` filter applies to **all three** generation paths (fresh
+  `generateRecipeContract`, revisit, principal-biased). When no gated recipe
+  qualifies the filtered pool is identical to the historic pool, so seeded
+  generation for pre-P3.M3 contexts is unchanged (full suite stayed green).
+- `ContractRecipeContext`/`ContractCampaign` gained `hasLivingDecker?`;
+  `Campaign.get hasLivingDecker()` = some non-flatlined `archetype === 'Decker'`.
+- Deploy gate in `Campaign.deployCrewMember`: throws
+  `requires a living Decker to jack in` for cyber contracts unless the deployed
+  member is a (non-flatlined) Decker.
+- UX: `CrewList.setCrew(crew, rowGate?)` — `CrewRowGate` returns a disable tag
+  or null; selection/keyboard nav skip gated rows. `RunBriefing` derives the
+  gate from the contract (`NEEDS DECKER` on non-Decker rows), re-applies on
+  contract swap, and `#commit`/jack-in button respect it.
+- `Run.isObjectiveFamilySatisfied` has a `DATA_NODE_SLICE` case returning
+  `false` (honestly unsatisfiable until S4 wires sliced-node counting). The
+  exhaustive `never` default caught the new kind at typecheck.
+- Tests: `tests/unit/game/hub/cyberContract.test.ts` (14 tests — validation
+  throws, generation gating over 40 seeded boards, determinism, deploy gates).
+
+### S2 implementation notes (shipped)
+
+- `src/game/entities/JackInPoint.ts` — `JackInPoint extends Interactable`,
+  glyph `Ω` (`JACK_IN_GLYPH` in constants), default label `Jack-in port`,
+  id `jack-in-0` (deliberately **not** matching `/^terminal-\d+$/`, which
+  TERMINAL_SLICE counts — regression-tested). `interact`: linked → logged
+  `already-linked` refusal (never throws); capability sniff
+  `actor.canJackIn !== true` → `no-cyberdeck` refusal; success spends interact
+  AP, latches `linked`, emits `EVENT.JACK_IN` `{point, actor}` exactly once.
+- `Decker.canJackIn = true` (readonly capability, P3.M2 sniffing pattern).
+- `events.ts`: `JACK_IN: 'cyber:jack-in'`, `JACK_OUT: 'cyber:jack-out'`
+  registered (known-types-only bus).
+- Placement: `Run.#placeObjectiveInteractables` gained the DATA_NODE_SLICE arm —
+  one port via `findInteractableAnchor`, deterministic per contract seed.
+- `Run.cyberspace: CyberspaceState | null` latched in `enterBriefing` from
+  `contractRequiresCyberspace` (`{phase:'dormant'}` or `null`). S2's
+  `CyberspaceState` is dormant-only; S3 extends the union.
+- Persistence: `RunSnapshot.cyberspace?: RunCyberspaceSnapshot`;
+  `snapshotCyberspace` in Run.ts; `restoreCyberspace` in persistence.ts
+  enforcing **block ⇔ cyber-contract both directions**, unknown phase throws,
+  dormant payload smuggling throws. Entity plumbing: `'jack-in-point'` in
+  `EntityArchetypeId`, `archetypeOf`, `SNAPSHOT_EXTRACTORS`,
+  `ARCHETYPE_FACTORY`, `ENTITY_RESTORE` (+ `readJackInPoint` throwing on
+  missing label/linked).
+- Tests: `tests/unit/game/jackInPoint.test.ts` (12 tests — interact behavior,
+  placement determinism, round-trip, adversarial restore throws).
+
+## Architecture decisions (approved plan)
+
+### Cyber layer model — `CyberspaceLayer` owned by `Run`, single `TurnQueue`, both worlds tick
+
+New `src/game/cyber/CyberspaceLayer.ts`: owns its own `EventBus`, `World`
+(own `Grid`), `CyberAvatar`, `entryTile`, `mapSeen`. NOT a nested Run.
+
+```ts
+type CyberspaceState =
+  | { phase: 'dormant' }                                // shipped (S2)
+  | { phase: 'active'; layer: CyberspaceLayer }         // S3
+  | { phase: 'resolved'; objectiveComplete: boolean };  // S3/S5
+Run.cyberspace: CyberspaceState | null;                 // null ⇔ no cyber component
+```
+
+Turn integration: keep the one existing `TurnQueue`. `TurnQueue.endTurn(world)`
+(verified: emits `TURN_ENDED {previous, next, turn}`, refreshes incoming-faction
+AP in the world it is handed, ticks that world's alarm on round advance) runs on
+the meat world as today. `Run`'s existing `TURN_ENDED` listener
+(`_reattachCombatListeners`, Run.ts ~887) consumes the payload and, when cyber
+is active, calls `layer.onTurnEnded(next)`: refresh incoming-faction AP in the
+cyber world + tick the cyber alarm on round advance. The shell's corp phase
+(S7) chains two `corpTurnDriver.runCorpTurn` passes: meat hostiles, then ICE
+(`ctx.run = {state, world: layer.world, rng: run.rng}`). **Meatspace keeps
+ticking during jack-in** — the Decker body stands at the port as `run.player`,
+targetable; body death hits the existing player-death path
+(`#onEntityDamaged`, Run.ts ~938). M4.2 vulnerability falls out for free.
+
+### Avatar + cyber stats
+
+`src/game/cyber/CyberAvatar.ts` — `CyberAvatar extends Entity`: faction PLAYER,
+glyph `@`, maxAp 4, `maxHp = decker.ram`,
+`damageReduction = decker.iceResistance`, carries `intrusionStrength` +
+`callsign`, `baseHitChance` 0.8 (the grid is home turf; `Combat.resolveRanged`
+capability-sniffs `'baseHitChance' in attacker`, so a non-Crew avatar fights
+with zero combat changes).
+
+Stats live on `Decker` as validated fields with constants
+`DECKER_BASE_RAM = 8`, `DECKER_BASE_INTRUSION = 2`,
+`DECKER_BASE_ICE_RESISTANCE = 1` (`src/game/constants.ts`); ctor throws on
+non-positive-integer overrides. Persist in **both** crew paths:
+
+1. `CampaignCrewSnapshot` (persistence.ts ~743) gains optional
+   `cyber?: { ram; intrusion; iceResistance }` written by `snapshotCrewMember`
+   for deckers only; `restoreCrewMember` (~1326) applies for
+   `archetype === 'decker'`. Absent → defaults (legacy normalization);
+   present-but-malformed or half-populated → throw.
+2. Run-entity `decker` extra becomes
+   `DeckerSnapshot = CrewSnapshot & {ram; intrusion; iceResistance}` —
+   extractor in Run.ts `SNAPSHOT_EXTRACTORS.decker` (~1698), matching
+   `ENTITY_RESTORE.decker` apply hook.
+
+Avatar **current** RAM rides the base entity record (`hp`/`maxHp`/
+`damageReduction`) inside the cyber snapshot block; `intrusionStrength` +
+`callsign` ride its `extra`.
+
+Avatar death: cyber-bus `ENTITY_DAMAGED` listener wired at jack-in (and on
+restore via `_reattachCombatListeners` — the single seam both `enterCombat` and
+`persistence.restore` already call) → set `telemetry.cause` →
+`enterResult({outcome: OUTCOME.DEATH})` → `Campaign.onJobEnd` flatlines the
+Decker through existing machinery.
+
+### Generation — dedicated generator, reuse TILE values, contract-seed determinism
+
+`src/game/cyber/cyberMapBuild.ts`: `buildCyberMap({rng, difficulty})` →
+rooms-as-nodes lattice (5–8 square nodes), 1-tile corridors (data lines),
+`TILE.WALL` fill (firewall). **Only FLOOR/WALL tile ids** — Grid
+passability/LOS, A*, VisionField, World all work unchanged. Node count scales
+with difficulty. Returns `{grid, entryTile, nodeTiles, patrolRings}`.
+Connectivity validated from `entryTile` via `mapConnectivity.ts`
+`explorationReachableKeys` (verified signature: `(world, start, options)` —
+needs a throwaway `World` wrap or a grid-level flood; throws on unreachable
+node tiles). ~150 lines; do NOT reuse the BSP/prefab `buildMap`.
+
+Seed: `new Rng(contract.seed).fork('cyberspace')` — layout independent of
+jack-in turn, trivially restorable.
+
+Distinct visuals via a **tileset axis** (S7), not new TILE ids: `palette.ts`
+gains `TilesetId = 'meat' | 'cyber'` + `CYBER_TILE_GLYPH` (FLOOR `·` deep cyan,
+WALL `▒` magenta — tune in browser); `glyphForTile(tile, principalId?,
+tileset?)` throws on unknown tileset. Thread through
+`BuildFrameOptions`/`buildFrame`/`AsciiRenderer.draw`.
+
+### Data node objective semantics (S4)
+
+`src/game/cyber/DataNode.ts` — `DataNode extends Interactable` (Terminal
+pattern): `sliceProgress`, `sliceDifficulty` (2/3/4 by contract difficulty).
+`interact` capability-sniffs `intrusionStrength` (non-avatars refused), spends
+interact AP, adds intrusion to progress; sliced at threshold. Glyph `◈`
+(`◆` is DenyTarget's).
+
+Satisfaction: `ObjectiveState` gains `cyber?: {sliced, required}`;
+`isObjectiveFamilySatisfied` DATA_NODE_SLICE case reads it;
+`#refreshObjectiveTimerState` computes — `active` → count sliced nodes in the
+layer world; `resolved` → `objectiveComplete ? required : 0`; `dormant` → 0.
+**Jack-out before slicing = objective permanently unsatisfiable** → reaching
+the meat exit hits the existing `onAbortRequested` confirm flow (incomplete
+blocks *clean* extraction; zero new extraction code). `objectiveProgress.ts`
+gains a `NODES` progress chip. Grep `describe.ts`/`combatHud.ts` for
+kind-keyed copy in this slice.
+
+### Jack-in / jack-out (S3 core, S5 finalization)
+
+- `Run.jackIn(point)` via meat-bus `EVENT.JACK_IN` subscription (registered in
+  `_reattachCombatListeners`): `state === COMBAT` else throw;
+  `cyberspace.phase === 'dormant'` else **throw** (corrupt latch); build layer,
+  wire cyber listeners, autosave (`onPersist` explicitly — the latch transition
+  must never be lost).
+- Jack-out: `EntryPort extends Interactable` at `entryTile` in the cyber world
+  (glyph `▼`, avatar-only capability sniff); interact emits `EVENT.JACK_OUT` on
+  the cyber bus → `Run.jackOut()`: throw unless active; latch
+  `objectiveComplete`, `layer.teardown()` (unbind ICE bus subs), phase
+  `resolved`, autosave. Re-jack-in after resolve refused (`LINK BURNED`
+  flavor — `JackInPoint.linked` is already latched).
+
+### Probe ICE (S6)
+
+`src/game/cyber/ProbeIce.ts` — `ProbeIce extends PatrolHostile`, faction CORP,
+glyph `¶`, displayName `Probe`, explicit small stats (maxHp 3, dmg 1,
+sightRange 6 — ICE scaling is its own axis, skip `resolveEnemyStats`).
+`engageSteps`: on acquisition raise the cyber alarm
+(`world.raiseAlarm({repPenalty: false, ...})`) then weak attack; Probe
+**listens** for alarms (unlike Lookout) so packs converge. Add `'probe-ice'`
+to `PATROL_ARCHETYPE_IDS` so `PatrolSnapshot` machinery applies. Patrol
+waypoint rings around node tiles from `buildCyberMap`. Run's cyber
+`ENTITY_DAMAGED` listener also unbinds killed patrol hostiles (mirror of the
+meat path). Verify no rep listener attaches to the cyber bus.
+
+### Render/input swap (S7)
+
+`Run` accessors keep the shell mechanical: `get cyberActive`,
+`get activeWorld`, `get activeActor`. Shell (`index.ts`): module-level
+`cyberVision = new VisionField()`; swap `recomputeVision`, `paint`
+(+`tileset`), `applyIntent` ctx (`world: run.activeWorld,
+player: run.activeActor`), look/describe, `buildCombatHudSnapshot` (identity
+`AVATAR`, HP pane labeled RAM), statusLine, location label (`// THE GRID //`),
+chained ICE corp pass. `ApplyIntentContext.player: Archetype` widens to accept
+`CyberAvatar` (it exposes none of the perk capabilities, so `doSpecial`
+sniffing is safe). No keymap/keyHelp changes — jack-in/out are interactions.
+PIP deferred to M4.5. **Grep `run.world` / `run.player` / `scene.world` /
+`scene.player` exhaustively** — look/describe, touch path, corpse-memory
+vision are the known stragglers.
+
+## Persistence (consolidated; S2 shipped the dormant scaffolding)
+
+`RunSnapshot.cyberspace` (S3 extends the S2 shape):
+
+```ts
+cyberspace?: {
+  phase: 'dormant' | 'active' | 'resolved';
+  // 'active' only — all required together:
+  seed?, grid?: {w,h,tiles}, entities?: RunEntitySnapshot[],  // avatar, entry-port, data-nodes, probe-ice
+  entryTile?, alarm?: AlarmState, mapMemory?: {seen: string[]},
+  // 'resolved' only:
+  objectiveComplete?: boolean;
+};
+```
+
+Restore rules (`restoreCyberspace` in persistence.ts — S2 shipped the dormant
+subset; all throws, `restoreOverrideState` style):
+
+- `contractRequiresCyberspace(contract)` ⇔ block present (both directions). ✅ shipped
+- Unknown phase throws. ✅ shipped
+- `dormant` carrying payload throws. ✅ shipped
+- S3: `active` missing any required field throws; exactly one alive
+  `cyber-avatar` (0 or 2+ throws); entities bounds-checked against the
+  **cyber** grid (reuse `restoreEntity(rec, cyberGrid)`); seen keys
+  bounds-checked.
+- S3: `resolved` without boolean `objectiveComplete`, or carrying active-only
+  fields, throws.
+- S3: Decker `cyber` stat blocks (campaign crew + run entity extra): absent →
+  defaults (legacy normalization); present-but-malformed or half-populated →
+  throw.
+- After rebuild: probes `bindToBus(layer.bus)`; cyber listeners re-wired in
+  `_reattachCombatListeners`.
+- Autosave cadence unchanged (meat-bus `TURN_ENDED` still fires every end-turn
+  while jacked in — single queue); `jackIn`/`jackOut` call `onPersist`
+  explicitly.
+
+## S3 detailed worklist (next up — research complete, no code yet)
+
+**Create:**
+- `src/game/cyber/cyberMapBuild.ts` — `buildCyberMap({rng, difficulty})` per
+  above; throws on connectivity failure.
+- `src/game/cyber/CyberAvatar.ts` — per above.
+- `src/game/cyber/EntryPort.ts` — `EntryPort extends Interactable` (glyph `▼`,
+  label `Exit port`); interact by avatar emits `EVENT.JACK_OUT` (charge
+  `AP_COST.INTERACT`).
+- `src/game/cyber/CyberspaceLayer.ts` — class +
+  `static build({contractSeed, difficulty, decker})` (forks
+  `new Rng(contractSeed).fork('cyberspace')`, builds map, spawns avatar at
+  `entryTile`, `EntryPort`, data nodes (S4 fills in), ICE (S6));
+  `onTurnEnded(next: FactionId)`; `recordSeen(keys)` (bounds-validated,
+  throws); `snapshot(): CyberspaceLayerSnapshot`; `teardown()`.
+
+**Modify:**
+- `src/game/archetypes/Decker.ts` + `constants.ts` — `ram`/`intrusionStrength`/
+  `iceResistance` fields, `DECKER_BASE_*` constants, ctor validation.
+- `src/game/Run.ts` — extend `CyberspaceState` union + `RunCyberspaceSnapshot`;
+  `get cyberActive / activeWorld / activeActor`; `jackIn(point)` (driven by
+  `EVENT.JACK_IN` subscription added to `_reattachCombatListeners`);
+  `jackOut()` core; `#onTurnEnded` consumes the `{next}` payload (currently
+  ignores it — Run.ts ~927) for the cyber AP/alarm tick; `snapshotCyberspace`
+  extended; `SNAPSHOT_EXTRACTORS` entries `'cyber-avatar'`/`'entry-port'`;
+  `archetypeOf` instanceof arms; `DeckerSnapshot` extra extension.
+- `src/game/persistence.ts` — extend `restoreCyberspace` (active/resolved
+  rules above); `ARCHETYPE_FACTORY`/`ENTITY_RESTORE` for
+  `'cyber-avatar'`/`'entry-port'`; `ENTITY_RESTORE.decker` apply for cyber
+  stats; `CampaignCrewSnapshot.cyber?` in `snapshotCrewMember` (~1309) +
+  `restoreCrewMember` (~1326).
+
+**Tests (failing first):**
+- `tests/unit/game/cyber/cyberMapBuild.test.ts`: equal-seed determinism;
+  different-seed divergence; every node tile reachable from entry; only
+  FLOOR/WALL ids; difficulty scales node count.
+- `tests/unit/game/cyber/CyberspaceLayer.test.ts`: `build` spawns avatar at
+  entry with `maxHp === decker.ram`,
+  `damageReduction === decker.iceResistance`; `onTurnEnded(FACTION.PLAYER)`
+  refreshes avatar AP only.
+- `tests/unit/game/cyber/runJackIn.test.ts`: golden path — seeded cyber run,
+  walk Decker to port, interact → `phase === 'active'`; layer grid equals a
+  fresh build from the same contract seed (jack-in-turn independence);
+  `jackIn` while already active throws; `JACK_IN` on a non-cyber contract
+  throws.
+- `tests/unit/game/cyber/cyberPersistence.test.ts` (the heart): mid-jack-in
+  snapshot → restore → grids/entities/avatar hp/ap/seen equal; full
+  adversarial throw matrix (active missing grid/avatar; avatar OOB; multiple
+  avatars; resolved missing latch; decker cyber stats half-populated in both
+  paths).
+
+## S3 research notes (verified against the tree, 2026-06-09)
+
+- `TurnQueue.endTurn(world)` emits `TURN_ENDED {previous, next, turn}` and
+  refreshes AP only for entities in the world it is handed; alarm ticks on
+  round advance (TurnQueue.ts:34-55). `Run.#onTurnEnded()` currently takes no
+  payload (Run.ts ~927) — S3 threads `{next}` through for the cyber tick.
+- `_reattachCombatListeners` (Run.ts ~887) is the single seam used by both
+  `enterCombat` and `persistence.restore` — register the `EVENT.JACK_IN`
+  subscription and (re)wire cyber-layer listeners there.
+- `#onEntityDamaged` (Run.ts ~938) is the player-death template: avatar-death
+  listener mirrors `target === avatar && killed` → telemetry.cause →
+  `enterResult({outcome: OUTCOME.DEATH})`. It also unbinds killed
+  `PatrolHostile`s — the cyber listener needs the same for probes (S6).
+- `persistence.restore` (persistence.ts ~872) rebuilds grid → entities →
+  Run → world → queue, then calls `_reattachCombatListeners` for COMBAT
+  snapshots. `restoreEntity(rec, grid)` bounds-checks against the grid it is
+  given — reuse with the cyber grid for cyber entities.
+- `CampaignCrewSnapshot` (~743) and `snapshotCrewMember`/`restoreCrewMember`
+  (~1309/~1326) are the campaign crew path; run-entity crew state flows through
+  `crewSnapshotExtra` (Run.ts ~1675) + `ENTITY_RESTORE` crew handling. Decker
+  cyber stats must round-trip through **both**.
+- `Entity` ctor validates `damageReduction` as a non-negative integer
+  (Entity.ts ~110) — avatar can pass `iceResistance` straight through.
+- `explorationReachableKeys(world, start, options)` (mapConnectivity.ts) is the
+  flood-fill for cyber connectivity validation; it needs a `World`, so
+  `buildCyberMap` should wrap its fresh grid in a throwaway `World` (no
+  entities yet → entity blockers moot).
+- `World` ctor: `new World(grid, { events: bus })`; alarm API:
+  `raiseAlarm(ctx)`, `tickAlarm()`, `snapshotAlarm()`, `restoreAlarm(state)`.
+- `Crew.archetype` is the class-name string (`'Decker'`, capital D) for live
+  checks; persistence archetype ids are lowercase (`'decker'`).
+
+## Verification (per slice + end-to-end)
+
+1. Per slice: `npm test` (typecheck + test build + `node --test`), `npm run lint`.
+2. Determinism: equal-seed trace assertions in S3/S6 tests.
+3. Browser smoke after S7 (`npm start`, port 8099): Act-2 save with Decker →
+   cyber contract on board → non-Decker rows disabled → deploy Decker → jack
+   in → cyber tileset + RAM HUD + probe attacks → slice node → jack out → meat
+   renders → clean extract. Plus: Merc bump refusal copy, redundant jack-in
+   message, mid-cyber reload resumes in the grid, avatar death → flatline
+   screen, jack-out-early → abort-confirm extraction. Console clean on iOS
+   Safari sim + Chrome.
+4. Persistence adversarial: hand-mutate a save in devtools (delete
+   `cyberspace.grid`, flip phase) → restore throws to the error boundary, not
+   a silent fallback.
+
+## Risks
+
+- **S7 shell breadth** is the highest-risk surface (~2300-line index.ts reads
+  `run.world`/`run.player` widely). Mitigation: accessors + exhaustive grep +
+  the smoke script above.
+- **`ApplyIntentContext.player` widening** may ripple into
+  `doSpecial`/`doUseItem` narrowing; the avatar exposes no perk capabilities,
+  and `collectTileLoot` guards on `player.inventory`.
+- **Shared-rng turn order**: meat pass then ICE pass consumes `run.rng` in a
+  fixed order; lock with the S7 dual-phase test.
+- **Cyber alarm/rep**: Probe passes `repPenalty: false`; confirm no rep
+  listeners attach to the cyber bus (S6 test).

From 76841a05234ce8dad39b49105a231af645250a54 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Tue, 9 Jun 2026 21:33:03 -0700
Subject: [PATCH 16/55] lint

---
 src/game/Run.ts                           |  4 +---
 src/game/hub/Curator.ts                   |  5 ++++-
 src/game/persistence.ts                   | 10 ++++++++--
 tests/unit/game/hub/cyberContract.test.ts |  5 +----
 4 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/src/game/Run.ts b/src/game/Run.ts
index ed33b2d..c3938ab 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -1798,9 +1798,7 @@ const SNAPSHOT_EXTRACTORS: Partial<Record<EntityArchetypeId, (e: Entity) => Enti
  */
 function snapshotCyberspace(state: CyberspaceState): RunCyberspaceSnapshot {
   if (state.phase === 'dormant') return { phase: 'dormant' };
-  throw new Error(
-    `Run.snapshot: unknown cyberspace phase "${(state as { phase: string }).phase}"`
-  );
+  throw new Error(`Run.snapshot: unknown cyberspace phase "${(state as { phase: string }).phase}"`);
 }
 
 function snapshotEntity(entity: Entity): RunEntitySnapshot {
diff --git a/src/game/hub/Curator.ts b/src/game/hub/Curator.ts
index 1948e6c..d7996c5 100644
--- a/src/game/hub/Curator.ts
+++ b/src/game/hub/Curator.ts
@@ -710,7 +710,10 @@ export function normalizeObjective(value: unknown): ContractObjective {
  * other kind may carry the flag. Validated at generation, at
  * `Run.enterBriefing`, and on snapshot restore (all call `normalizeObjective`).
  */
-function validateCyberspaceObjective(kind: ObjectiveKind, params: ObjectiveParams | undefined): void {
+function validateCyberspaceObjective(
+  kind: ObjectiveKind,
+  params: ObjectiveParams | undefined
+): void {
   if (kind === OBJECTIVES.DATA_NODE_SLICE) {
     if (params?.requiresCyberspace !== true) {
       throw new Error(
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index 0f76ebb..3434b7b 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -937,7 +937,10 @@ export function restore(record: unknown, options: RestoreOptions = {}) {
   run.rng = new Rng(record.rng.seed);
   run.rng.setState(record.rng.state);
   run.contract = normalizeContract(record.contract);
-  run.cyberspace = restoreCyberspace(record, run.contract !== null && contractRequiresCyberspace(run.contract));
+  run.cyberspace = restoreCyberspace(
+    record,
+    run.contract !== null && contractRequiresCyberspace(run.contract)
+  );
   run.exitTile = record.exitTile ? { ...record.exitTile } : null;
   run.telemetry = { ...record.telemetry };
   run.objectiveTimer = normalizeObjectiveTimer(record.objectiveTimer);
@@ -1002,7 +1005,10 @@ export function restore(record: unknown, options: RestoreOptions = {}) {
  * `dormant` phase is tier-1 corrupt state and throws. P3.M3.3 extends this
  * with the `active` (grid + entities) and `resolved` (latch) phases.
  */
-function restoreCyberspace(record: RunSnapshot, requiresCyberspace: boolean): CyberspaceState | null {
+function restoreCyberspace(
+  record: RunSnapshot,
+  requiresCyberspace: boolean
+): CyberspaceState | null {
   const block = record.cyberspace;
   if (!requiresCyberspace) {
     if (block !== undefined && block !== null) {
diff --git a/tests/unit/game/hub/cyberContract.test.ts b/tests/unit/game/hub/cyberContract.test.ts
index 11e57dd..e9e7bf7 100644
--- a/tests/unit/game/hub/cyberContract.test.ts
+++ b/tests/unit/game/hub/cyberContract.test.ts
@@ -73,10 +73,7 @@ test('normalizeObjective throws on data-node-slice without requiresCyberspace',
 });
 
 test('normalizeObjective throws on data-node-slice with a malformed count', () => {
-  assert.throws(
-    () => normalizeObjective(cyberObjective({ requiresCyberspace: true })),
-    /count/
-  );
+  assert.throws(() => normalizeObjective(cyberObjective({ requiresCyberspace: true })), /count/);
   assert.throws(
     () => normalizeObjective(cyberObjective({ requiresCyberspace: true, count: 0 })),
     /count/

From 39b357e50eceaec401c1436b8df8ae43b8bda253 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Wed, 10 Jun 2026 13:39:11 -0700
Subject: [PATCH 17/55] =?UTF-8?q?P3.M3.3:=20Cyberspace=20layer=20=E2=80=94?=
 =?UTF-8?q?=20grid,=20avatar,=20jack-in/out=20core,=20persistence?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

S3 of the cyberspace slice plan. The digital layer exists and round-trips:

- cyberMapBuild: deterministic node-lattice generator (spanning random walk
  over a 4×2 cell lattice, rooms + L-corridors, FLOOR/WALL only), seeded
  from the contract via Rng.fork('cyberspace') so layout is independent of
  jack-in turn. Connectivity flood-validated; unreachable port/node throws.
- CyberAvatar (Entity subclass): maxHp = Decker RAM, damageReduction = ICE
  resistance, carries intrusionStrength + callsign, baseHitChance 0.8,
  isCyberAvatar capability flag.
- EntryPort interactable: avatar-only interact emits JACK_OUT (resolve
  latch lives on Run.cyberspace, not the port).
- CyberspaceLayer: own bus + World, build/restore ctors, onTurnEnded AP
  refresh + alarm tick driven by the single meat TurnQueue, mapSeen.
- Run: CyberspaceState active/resolved phases, cyberActive/activeWorld/
  activeActor accessors, jackIn/jackOut with throw-on-illegal-phase,
  cyber ENTITY_DAMAGED listener (avatar death → RESULT/DEATH flatline),
  snapshot block for all three phases.
- persistence: restoreCyberspace with full adversarial throw matrix
  (allowed-keys per phase, grid/tile validation, exactly-one avatar/port,
  bounds checks against the cyber grid); Decker cyber stats persist via
  both crew paths (campaign snapshot + run-entity extra), absent → base
  defaults, partial → throw.
- Decker: ram/intrusionStrength/iceResistance fields with ctor validation
  and DECKER_BASE_* constants (scope decision #4 — named stats, real
  effects).

49 new tests under tests/unit/game/cyber/ (failing-first verified).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/game/Entity.ts                            |   3 +
 src/game/Run.ts                               | 247 ++++++++++-
 src/game/archetypes/Decker.ts                 |  59 ++-
 src/game/constants.ts                         |  26 ++
 src/game/cyber/CyberAvatar.ts                 | 103 +++++
 src/game/cyber/CyberspaceLayer.ts             | 194 +++++++++
 src/game/cyber/EntryPort.ts                   |  53 +++
 src/game/cyber/cyberMapBuild.ts               | 172 ++++++++
 src/game/persistence.ts                       | 294 ++++++++++++-
 tests/unit/game/cyber/CyberspaceLayer.test.ts | 172 ++++++++
 tests/unit/game/cyber/cyberMapBuild.test.ts   | 101 +++++
 .../unit/game/cyber/cyberPersistence.test.ts  | 404 ++++++++++++++++++
 tests/unit/game/cyber/runJackIn.test.ts       | 242 +++++++++++
 13 files changed, 2038 insertions(+), 32 deletions(-)
 create mode 100644 src/game/cyber/CyberAvatar.ts
 create mode 100644 src/game/cyber/CyberspaceLayer.ts
 create mode 100644 src/game/cyber/EntryPort.ts
 create mode 100644 src/game/cyber/cyberMapBuild.ts
 create mode 100644 tests/unit/game/cyber/CyberspaceLayer.test.ts
 create mode 100644 tests/unit/game/cyber/cyberMapBuild.test.ts
 create mode 100644 tests/unit/game/cyber/cyberPersistence.test.ts
 create mode 100644 tests/unit/game/cyber/runJackIn.test.ts

diff --git a/src/game/Entity.ts b/src/game/Entity.ts
index b51c3ce..f70e130 100644
--- a/src/game/Entity.ts
+++ b/src/game/Entity.ts
@@ -274,6 +274,9 @@ function kindFromId(id: string): string {
   if (id.startsWith('relay-node')) return 'Relay';
   if (id.startsWith('escort-npc')) return 'Escort';
   if (id.startsWith('keycard')) return 'Keycard';
+  if (id.startsWith('jack-in')) return 'Jack-in Port';
+  if (id.startsWith('cyber-avatar')) return 'Avatar';
+  if (id.startsWith('entry-port')) return 'Exit Port';
   if (id.includes('turret')) return 'Turret';
   if (id.startsWith('crew')) return 'Operative';
   return id;
diff --git a/src/game/Run.ts b/src/game/Run.ts
index c3938ab..61f4641 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -79,6 +79,9 @@ import { ConsumablePickup } from './entities/ConsumablePickup.js';
 import { EscortNpc } from './entities/EscortNpc.js';
 import { KeyCard } from './entities/KeyCard.js';
 import { JackInPoint } from './entities/JackInPoint.js';
+import { CyberspaceLayer } from './cyber/CyberspaceLayer.js';
+import { CyberAvatar } from './cyber/CyberAvatar.js';
+import { EntryPort } from './cyber/EntryPort.js';
 import { applyMutationDeltas } from './locations.js';
 import { BreachingCharge } from './entities/BreachingCharge.js';
 import { ITEM_ID, getItemById } from './items.js';
@@ -123,6 +126,9 @@ import type { ConsumablePickupSnapshot } from './entities/ConsumablePickup.js';
 import type { EscortNpcSnapshot } from './entities/EscortNpc.js';
 import type { JackInPointSnapshot } from './entities/JackInPoint.js';
 import type { KeyCardSnapshot } from './entities/KeyCard.js';
+import type { CyberAvatarSnapshot } from './cyber/CyberAvatar.js';
+import type { EntryPortSnapshot } from './cyber/EntryPort.js';
+import type { DeckerSnapshot } from './archetypes/Decker.js';
 import type { AlarmState } from './World.js';
 
 export const RUN_STATE = Object.freeze({
@@ -167,6 +173,8 @@ export type EntityArchetypeId =
   | 'keycard'
   | 'breaching-charge'
   | 'jack-in-point'
+  | 'cyber-avatar'
+  | 'entry-port'
   | 'entity';
 
 export type RunTelemetry = {
@@ -286,23 +294,37 @@ export type RunSnapshot = {
 };
 
 /**
- * P3.M3: serialized Cyberspace layer state. The `dormant` phase carries no
- * payload — the layer spawns fresh on jack-in. P3.M3.3 extends this with the
- * `active` (grid + entities) and `resolved` (objective latch) phases.
+ * P3.M3: serialized Cyberspace layer state.
+ *
+ *   - `dormant` — cyber contract, not yet jacked in. No payload; the layer
+ *     spawns fresh (and deterministically) on jack-in.
+ *   - `active` — the live layer: its grid, entities (avatar, exit port, and
+ *     later data nodes + ICE), alarm cadence, and fog memory. All fields are
+ *     required together; a partial block is corrupt and throws on restore.
+ *   - `resolved` — jacked out; only the objective latch survives.
  */
-export type RunCyberspaceSnapshot = {
-  phase: 'dormant';
-};
+export type RunCyberspaceSnapshot =
+  | { phase: 'dormant' }
+  | {
+      phase: 'active';
+      grid: { w: number; h: number; tiles: number[] };
+      entities: RunEntitySnapshot[];
+      entryTile: GridPoint;
+      alarm: AlarmState;
+      mapMemory: MapMemorySnapshot;
+    }
+  | { phase: 'resolved'; objectiveComplete: boolean };
 
 /**
  * P3.M3: live Cyberspace state machine on the Run. `null` ⇔ the contract has
- * no Cyberspace component. P3.M3.3 extends the union with
- * `{ phase: 'active'; layer: CyberspaceLayer }` and
- * `{ phase: 'resolved'; objectiveComplete: boolean }`.
+ * no Cyberspace component. Transitions: dormant → active (`jackIn`) →
+ * resolved (`jackOut` / P3.M4 forced jack-out). Resolved is a latch — the
+ * link is burned; re-entry is refused.
  */
-export type CyberspaceState = {
-  phase: 'dormant';
-};
+export type CyberspaceState =
+  | { phase: 'dormant' }
+  | { phase: 'active'; layer: CyberspaceLayer }
+  | { phase: 'resolved'; objectiveComplete: boolean };
 
 /** Serializable run-scoped key item (P2.5.M6.2). */
 type KeyItemSnapshot = {
@@ -351,6 +373,12 @@ type EntityMovedPayload = {
   to: GridPoint;
 };
 
+type TurnEndedPayload = {
+  previous: FactionId;
+  next: FactionId;
+  turn: number;
+};
+
 export class Run {
   id: string;
   crewMember: Crew;
@@ -779,6 +807,89 @@ export class Run {
     return this.world?.mutationDeltas ?? [];
   }
 
+  // ------------------------------------------------------------------
+  // P3.M3.3 — Cyberspace layer bridge
+  // ------------------------------------------------------------------
+
+  /** True while the Decker is jacked in and the cyber layer is live. */
+  get cyberActive(): boolean {
+    return this.cyberspace?.phase === 'active';
+  }
+
+  /** The world the shell should render/drive: cyber while jacked in, else meat. */
+  get activeWorld(): World | null {
+    return this.cyberspace?.phase === 'active' ? this.cyberspace.layer.world : this.world;
+  }
+
+  /** The actor the shell should control: the avatar while jacked in, else the player. */
+  get activeActor(): Crew | CyberAvatar | null {
+    return this.cyberspace?.phase === 'active' ? this.cyberspace.layer.avatar : this.player;
+  }
+
+  /**
+   * Dormant → active: spawn the Cyberspace layer. Driven by the meat-bus
+   * `EVENT.JACK_IN` emission from a `JackInPoint` link. The layer derives
+   * from the *contract* seed, so the layout is independent of the jack-in
+   * turn. Every precondition violation throws — a JACK_IN emission outside a
+   * dormant cyber run is corrupt state, not a recoverable refusal.
+   */
+  jackIn(point: JackInPoint): void {
+    if (this.state !== RUN_STATE.COMBAT) {
+      throw new Error(`Run.jackIn: illegal from state ${this.state} (COMBAT only)`);
+    }
+    if (!this.contract) {
+      throw new Error('Run.jackIn: COMBAT state without a contract');
+    }
+    if (!this.cyberspace) {
+      throw new Error('Run.jackIn: contract has no Cyberspace component');
+    }
+    if (this.cyberspace.phase !== 'dormant') {
+      throw new Error(`Run.jackIn: illegal from cyberspace phase "${this.cyberspace.phase}"`);
+    }
+    if (!(point instanceof JackInPoint) || !point.linked) {
+      throw new Error('Run.jackIn: requires a linked jack-in point');
+    }
+    if (!(this.player instanceof Decker)) {
+      throw new Error('Run.jackIn: only a Decker can enter the grid');
+    }
+    const layer = CyberspaceLayer.build({
+      contractSeed: this.contract.seed,
+      difficulty: this.contract.difficulty,
+      decker: this.player,
+    });
+    this.cyberspace = { phase: 'active', layer };
+    this.#wireCyberLayerListeners(layer);
+    // The latch transition must never be lost — autosave explicitly.
+    if (this.onPersist) {
+      this.onPersist(this.snapshot());
+    }
+  }
+
+  /**
+   * Active → resolved: the avatar routed out through the exit port (cyber-bus
+   * `EVENT.JACK_OUT`). Latches the objective outcome and tears the layer
+   * down; the link is burned — re-entry is refused. P3.M4.6 adds the forced
+   * variant (body under fire).
+   */
+  jackOut(): void {
+    if (this.state !== RUN_STATE.COMBAT) {
+      throw new Error(`Run.jackOut: illegal from state ${this.state} (COMBAT only)`);
+    }
+    if (this.cyberspace?.phase !== 'active') {
+      throw new Error(
+        `Run.jackOut: illegal from cyberspace phase "${this.cyberspace?.phase ?? 'none'}"`
+      );
+    }
+    const layer = this.cyberspace.layer;
+    // TODO(P3.M3.4): derive from sliced data-node count once nodes exist.
+    const objectiveComplete = false;
+    layer.teardown();
+    this.cyberspace = { phase: 'resolved', objectiveComplete };
+    if (this.onPersist) {
+      this.onPersist(this.snapshot());
+    }
+  }
+
   /**
    * Phase 2.9: the single hostile faction for this run, derived from the
    * contract principal's groups (rival-group → `RIVAL`, corp/civic → `CORP`).
@@ -891,12 +1002,18 @@ export class Run {
     this.#unwireCombatListeners();
     const bus = this.bus;
     this._busUnsubs.push(
-      bus.on(EVENT.TURN_ENDED, () => this.#onTurnEnded()),
+      bus.on(EVENT.TURN_ENDED, payload => this.#onTurnEnded(payload as TurnEndedPayload)),
       bus.on(EVENT.ENTITY_DAMAGED, payload =>
         this.#onEntityDamaged(payload as EntityDamagedPayload)
       ),
-      bus.on(EVENT.ENTITY_MOVED, payload => this.#onEntityMoved(payload as EntityMovedPayload))
+      bus.on(EVENT.ENTITY_MOVED, payload => this.#onEntityMoved(payload as EntityMovedPayload)),
+      // P3.M3.3: a Decker linking a JackInPoint opens the cyber layer.
+      bus.on(EVENT.JACK_IN, payload => this.jackIn((payload as { point: JackInPoint }).point))
     );
+    // Restored mid-jack-in: re-wire the cyber-layer listeners on the same seam.
+    if (this.cyberspace?.phase === 'active') {
+      this.#wireCyberLayerListeners(this.cyberspace.layer);
+    }
   }
 
   // ------------------------------------------------------------------
@@ -924,17 +1041,71 @@ export class Run {
     this._busUnsubs = [];
   }
 
-  #onTurnEnded(): void {
+  #onTurnEnded(payload: TurnEndedPayload): void {
     if (this.state !== RUN_STATE.COMBAT) return;
     if (!this.queue) {
       throw new Error('Run.#onTurnEnded: COMBAT state without a TurnQueue');
     }
+    if (!payload || typeof payload.next !== 'string') {
+      throw new Error('Run.#onTurnEnded: TURN_ENDED payload missing the incoming faction');
+    }
     this.telemetry.turn = this.queue.turnNumber;
+    // P3.M3.3: both worlds tick on the single meat queue — refresh the
+    // incoming faction's AP on the cyber grid (and its alarm on round
+    // advance) before the autosave below captures the post-state.
+    if (this.cyberspace?.phase === 'active') {
+      this.cyberspace.layer.onTurnEnded(payload.next);
+    }
     this.#refreshObjectiveTimerState();
     if (!this.onPersist) return;
     this.onPersist(this.snapshot());
   }
 
+  /**
+   * P3.M3.3: cyber-bus listeners, wired on jack-in and re-wired through
+   * `_reattachCombatListeners` after a mid-jack-in restore. Unsubs join
+   * `_busUnsubs`, so `enterResult`/re-wiring clears them with the meat set.
+   */
+  #wireCyberLayerListeners(layer: CyberspaceLayer): void {
+    this._busUnsubs.push(
+      layer.bus.on(EVENT.ENTITY_DAMAGED, payload =>
+        this.#onCyberEntityDamaged(payload as EntityDamagedPayload)
+      ),
+      layer.bus.on(EVENT.JACK_OUT, () => this.jackOut())
+    );
+  }
+
+  /**
+   * The cyber twin of {@link #onEntityDamaged}. Avatar death is real death
+   * (scope decision #3): black ICE burning the last RAM routes through the
+   * existing DEATH path, and `Campaign.onJobEnd` flatlines the Decker.
+   */
+  #onCyberEntityDamaged({ attacker, target, damage, killed, source }: EntityDamagedPayload): void {
+    if (this.state !== RUN_STATE.COMBAT) return;
+    if (this.cyberspace?.phase !== 'active') return;
+    const layer = this.cyberspace.layer;
+    if (damage <= 0 && !killed) return;
+    if (target === layer.avatar) {
+      this.telemetry.lastDamageSource = source ?? null;
+      this.telemetry.lastAttacker = attacker?.id ?? null;
+      this.telemetry.hpAtDamage = layer.avatar.hp;
+      if (killed) {
+        this.telemetry.hpAtDeath = 0;
+        this.telemetry.cause = `${attacker?.id ?? 'unknown'}::${source ?? 'unknown'}(${damage})`;
+        this.enterResult({ outcome: OUTCOME.DEATH });
+      }
+      return;
+    }
+    if (attacker === layer.avatar && killed) {
+      this.telemetry.kills = (this.telemetry.kills ?? 0) + 1;
+    }
+    // Unbind dead ICE patrols immediately (P3.M3.5 spawns them) — mirror of
+    // the meat-side PatrolHostile unbind.
+    if (killed && target instanceof PatrolHostile) {
+      target.unbind();
+    }
+  }
+
   #onEntityDamaged({ attacker, target, damage, killed, source }: EntityDamagedPayload): void {
     if (this.state !== RUN_STATE.COMBAT) return;
     if (!this.player) {
@@ -1695,7 +1866,17 @@ const SNAPSHOT_EXTRACTORS: Partial<Record<EntityArchetypeId, (e: Entity) => Enti
   {
     merc: e => crewSnapshotExtra(e as Crew) as unknown as EntitySnapshotExtra,
     razor: e => crewSnapshotExtra(e as Crew) as unknown as EntitySnapshotExtra,
-    decker: e => crewSnapshotExtra(e as Crew) as unknown as EntitySnapshotExtra,
+    decker: e => {
+      const d = e as Decker;
+      return {
+        ...crewSnapshotExtra(d),
+        // P3.M3.3: named cyber stats ride the run-entity path too, so a
+        // mid-job save can't lose a stat upgrade.
+        ram: d.ram,
+        intrusionStrength: d.intrusionStrength,
+        iceResistance: d.iceResistance,
+      } satisfies DeckerSnapshot as unknown as EntitySnapshotExtra;
+    },
     tech: e =>
       ({
         ...crewSnapshotExtra(e as Crew),
@@ -1790,14 +1971,44 @@ const SNAPSHOT_EXTRACTORS: Partial<Record<EntityArchetypeId, (e: Entity) => Enti
       const p = e as JackInPoint;
       return { label: p.label, linked: p.linked } satisfies JackInPointSnapshot;
     },
+    'cyber-avatar': e => {
+      const a = e as CyberAvatar;
+      return {
+        intrusionStrength: a.intrusionStrength,
+        callsign: a.callsign,
+      } satisfies CyberAvatarSnapshot;
+    },
+    'entry-port': e => {
+      return { label: (e as EntryPort).label } satisfies EntryPortSnapshot;
+    },
   };
 
 /**
  * P3.M3: serialize the Cyberspace state machine. Dormant carries no payload;
- * P3.M3.3 adds the active-layer grid/entities and the resolved latch.
+ * active serializes the live layer (grid + entities + alarm + fog memory)
+ * with the same entity codec as the meat world; resolved keeps only its
+ * objective latch.
  */
 function snapshotCyberspace(state: CyberspaceState): RunCyberspaceSnapshot {
   if (state.phase === 'dormant') return { phase: 'dormant' };
+  if (state.phase === 'active') {
+    const layer = state.layer;
+    return {
+      phase: 'active',
+      grid: {
+        w: layer.world.grid.width,
+        h: layer.world.grid.height,
+        tiles: Array.from(layer.world.grid.tiles),
+      },
+      entities: Array.from(layer.world.entities.values()).map(snapshotEntity),
+      entryTile: { ...layer.entryTile },
+      alarm: layer.world.snapshotAlarm(),
+      mapMemory: { seen: layer.mapSeenKeys() },
+    };
+  }
+  if (state.phase === 'resolved') {
+    return { phase: 'resolved', objectiveComplete: state.objectiveComplete };
+  }
   throw new Error(`Run.snapshot: unknown cyberspace phase "${(state as { phase: string }).phase}"`);
 }
 
@@ -1856,6 +2067,8 @@ function archetypeOf(entity: Entity): EntityArchetypeId {
   if (entity instanceof EscortNpc) return 'escort-npc';
   if (entity instanceof KeyCard) return 'keycard';
   if (entity instanceof JackInPoint) return 'jack-in-point';
+  if (entity instanceof CyberAvatar) return 'cyber-avatar';
+  if (entity instanceof EntryPort) return 'entry-port';
   if (entity instanceof BreachingCharge) return 'breaching-charge';
   if (entity instanceof Entity) return 'entity';
   throw new Error(`archetypeOf: cannot classify entity ${(entity as Entity | undefined)?.id}`);
diff --git a/src/game/archetypes/Decker.ts b/src/game/archetypes/Decker.ts
index f7dcc53..80dde4c 100644
--- a/src/game/archetypes/Decker.ts
+++ b/src/game/archetypes/Decker.ts
@@ -1,6 +1,11 @@
 import { Crew } from '../Crew.js';
 import { canOverride, overrideDrone } from '../droneOverride.js';
-import type { CrewInit } from '../Crew.js';
+import {
+  DECKER_BASE_ICE_RESISTANCE,
+  DECKER_BASE_INTRUSION,
+  DECKER_BASE_RAM,
+} from '../constants.js';
+import type { CrewInit, CrewSnapshot } from '../Crew.js';
 import type { Entity } from '../Entity.js';
 import type { World } from '../World.js';
 import type { Rng } from '../../rng.js';
@@ -33,9 +38,27 @@ export const CALLSIGNS = Object.freeze([
  * Phase-3 perk: **Override**. Reaches across a clean LOS lane to hijack a corp
  * drone's allegiance for a few turns (`droneOverride.ts`). It is a *targeted*
  * perk — the intent layer resolves a drone along the aim ray, then calls
- * `overrideDrone`. Cyberspace attributes (RAM, intrusion strength, ICE
- * resistance) are deferred to P3.M3, when the Cyberspace grid consumes them.
+ * `overrideDrone`.
+ *
+ * Cyberspace attributes (P3.M3.3) are named stats with real effects: `ram`
+ * is the avatar HP pool, `intrusionStrength` the slice progress per data-node
+ * interact, `iceResistance` the avatar's `damageReduction`. They persist
+ * through both crew paths (campaign crew snapshot + run-entity extra).
  */
+
+export interface DeckerInit extends CrewInit {
+  ram?: number;
+  intrusionStrength?: number;
+  iceResistance?: number;
+}
+
+/** P2.7.M6.2-style snapshot `extra` for the Decker — crew slice + cyber stats. */
+export type DeckerSnapshot = CrewSnapshot & {
+  ram: number;
+  intrusionStrength: number;
+  iceResistance: number;
+};
+
 export class Decker extends Crew {
   override archetype = 'Decker';
 
@@ -45,12 +68,40 @@ export class Decker extends Crew {
    */
   readonly canJackIn = true;
 
+  /** Avatar HP pool on the cyber grid (P3.M3.3). */
+  ram: number;
+  /** Slice progress per data-node interact (P3.M3.4 consumes it). */
+  intrusionStrength: number;
+  /** Avatar `damageReduction` against ICE (P3.M3.3). */
+  iceResistance: number;
+
   override get baseHitChance(): number {
     return 0.7;
   }
 
-  constructor(props: CrewInit) {
+  constructor({
+    ram = DECKER_BASE_RAM,
+    intrusionStrength = DECKER_BASE_INTRUSION,
+    iceResistance = DECKER_BASE_ICE_RESISTANCE,
+    ...props
+  }: DeckerInit) {
     super({ ...props, glyph: '@' });
+    if (!Number.isInteger(ram) || ram <= 0) {
+      throw new RangeError(`Decker ram must be a positive integer, got ${ram}`);
+    }
+    if (!Number.isInteger(intrusionStrength) || intrusionStrength <= 0) {
+      throw new RangeError(
+        `Decker intrusionStrength must be a positive integer, got ${intrusionStrength}`
+      );
+    }
+    if (!Number.isInteger(iceResistance) || iceResistance < 0) {
+      throw new RangeError(
+        `Decker iceResistance must be a non-negative integer, got ${iceResistance}`
+      );
+    }
+    this.ram = ram;
+    this.intrusionStrength = intrusionStrength;
+    this.iceResistance = iceResistance;
   }
 
   /**
diff --git a/src/game/constants.ts b/src/game/constants.ts
index 84ce1af..8d628ce 100644
--- a/src/game/constants.ts
+++ b/src/game/constants.ts
@@ -46,6 +46,8 @@ export const ESCORT_NPC_GLYPH = 'A';
 export const KEYCARD_GLYPH = 'κ';
 /** P3.M3.2: the Meatspace door into Cyberspace. */
 export const JACK_IN_GLYPH = 'Ω';
+/** P3.M3.3: the Cyberspace door back into Meatspace. */
+export const ENTRY_PORT_GLYPH = '▼';
 
 /** Numeric tile id — one of the `TILE` values. */
 export type TileId = (typeof TILE)[keyof typeof TILE];
@@ -97,6 +99,30 @@ export const OVERRIDE_RANGE = 5;
 export const OVERRIDE_DURATION = 3;
 export const OVERRIDE_SUCCESS_CHANCE = 0.6;
 
+/**
+ * Decker cyber stats (P3.M3.3). Named stats with real effects from day one
+ * (scope decision #4):
+ *   - `DECKER_BASE_RAM` — the avatar's HP pool on the cyber grid. ICE damage
+ *     burns RAM; zero RAM = flatline (avatar death is real death).
+ *   - `DECKER_BASE_INTRUSION` — slice progress added per data-node interact
+ *     (P3.M3.4 consumes it).
+ *   - `DECKER_BASE_ICE_RESISTANCE` — the avatar's `damageReduction`; the
+ *     existing min-1 mitigation in `Combat.ts` applies unchanged.
+ * Per-Decker overrides validate in the `Decker` ctor (crash on bad data).
+ */
+export const DECKER_BASE_RAM = 8;
+export const DECKER_BASE_INTRUSION = 2;
+export const DECKER_BASE_ICE_RESISTANCE = 1;
+
+/**
+ * Cyberspace avatar tuning (P3.M3.3). The avatar keeps the player AP budget
+ * (4) and fights at the Merc's hit chance — the grid is the Decker's home
+ * turf. `Combat.resolveRanged` capability-sniffs `baseHitChance`, so the
+ * non-Crew avatar plugs into combat with zero combat-code changes.
+ */
+export const CYBER_AVATAR_MAX_AP = 4;
+export const CYBER_AVATAR_HIT_CHANCE = 0.8;
+
 /**
  * Tech turret parameters. The turret is a placed grid entity (peer of
  * `Entity`, not an archetype) deployed by Tech at `AP_COST.DEPLOY`. Tunables:
diff --git a/src/game/cyber/CyberAvatar.ts b/src/game/cyber/CyberAvatar.ts
new file mode 100644
index 0000000..c4b761d
--- /dev/null
+++ b/src/game/cyber/CyberAvatar.ts
@@ -0,0 +1,103 @@
+/**
+ * P3.M3.3 — the Decker's avatar on the Cyberspace grid.
+ *
+ * A plain `Entity` (NOT a `Crew` — no inventory, gear, or perks): the cyber
+ * grid has its own verbs. Pools derive from the Decker's named cyber stats:
+ *
+ *   - `maxHp = decker.ram` — ICE damage burns RAM; zero RAM = flatline
+ *     (avatar death routes through the existing DEATH path; scope decision #3).
+ *   - `damageReduction = decker.iceResistance` — the existing min-1
+ *     mitigation in `Combat.ts` applies unchanged.
+ *   - `intrusionStrength` — slice progress per data-node interact (P3.M3.4).
+ *
+ * `baseHitChance` rides the capability sniff in `Combat.resolveRanged`
+ * (`'baseHitChance' in attacker`), so the avatar fights with zero combat-code
+ * changes. `isCyberAvatar` is the capability `EntryPort` sniffs — `Decker`
+ * also carries `intrusionStrength`, so a flag (not the stat) marks the avatar.
+ */
+import { Entity } from '../Entity.js';
+import { CYBER_AVATAR_HIT_CHANCE, CYBER_AVATAR_MAX_AP, FACTION } from '../constants.js';
+
+export type CyberAvatarInit = {
+  id: string;
+  x: number;
+  y: number;
+  /** Avatar HP pool — the owning Decker's RAM. */
+  ram: number;
+  intrusionStrength: number;
+  /** Avatar `damageReduction` — the owning Decker's ICE resistance. */
+  iceResistance: number;
+  callsign?: string | null;
+  maxAp?: number;
+};
+
+/**
+ * P2.7.M6.2: avatar snapshot `extra`. Current RAM rides the base entity
+ * record (`hp`/`maxHp`/`damageReduction`); only the non-Entity fields live here.
+ */
+export type CyberAvatarSnapshot = {
+  intrusionStrength: number;
+  callsign: string | null;
+};
+
+export class CyberAvatar extends Entity {
+  /** Capability sniffed by `EntryPort.interact` — only the avatar routes out. */
+  readonly isCyberAvatar = true;
+
+  intrusionStrength: number;
+  callsign: string | null;
+
+  get baseHitChance(): number {
+    return CYBER_AVATAR_HIT_CHANCE;
+  }
+
+  /** Alias for the HP pool in cyber terms. */
+  get ram(): number {
+    return this.maxHp;
+  }
+
+  /** Alias for `damageReduction` in cyber terms. */
+  get iceResistance(): number {
+    return this.damageReduction;
+  }
+
+  constructor({
+    id,
+    x,
+    y,
+    ram,
+    intrusionStrength,
+    iceResistance,
+    callsign = null,
+    maxAp = CYBER_AVATAR_MAX_AP,
+  }: CyberAvatarInit) {
+    if (!Number.isInteger(ram) || ram <= 0) {
+      throw new RangeError(`CyberAvatar ram must be a positive integer, got ${ram}`);
+    }
+    if (!Number.isInteger(intrusionStrength) || intrusionStrength <= 0) {
+      throw new RangeError(
+        `CyberAvatar intrusionStrength must be a positive integer, got ${intrusionStrength}`
+      );
+    }
+    if (!Number.isInteger(iceResistance) || iceResistance < 0) {
+      throw new RangeError(
+        `CyberAvatar iceResistance must be a non-negative integer, got ${iceResistance}`
+      );
+    }
+    if (callsign !== null && (typeof callsign !== 'string' || callsign.length === 0)) {
+      throw new TypeError(`CyberAvatar callsign must be a non-empty string or null`);
+    }
+    super({
+      id,
+      x,
+      y,
+      faction: FACTION.PLAYER,
+      glyph: '@',
+      maxAp,
+      maxHp: ram,
+      damageReduction: iceResistance,
+    });
+    this.intrusionStrength = intrusionStrength;
+    this.callsign = callsign;
+  }
+}
diff --git a/src/game/cyber/CyberspaceLayer.ts b/src/game/cyber/CyberspaceLayer.ts
new file mode 100644
index 0000000..504a229
--- /dev/null
+++ b/src/game/cyber/CyberspaceLayer.ts
@@ -0,0 +1,194 @@
+/**
+ * P3.M3.3 — CyberspaceLayer: the digital tactical layer owned by `Run`.
+ *
+ * Owns its own `EventBus`, `World` (own `Grid`), `CyberAvatar`, `EntryPort`,
+ * and map memory. Deliberately NOT a nested `Run` — no contract, telemetry,
+ * or extraction machinery; the owning `Run` remains the single state machine
+ * and bridges the two layers:
+ *
+ *   - **Turn cadence:** there is one `TurnQueue` (the meat one). `Run`'s
+ *     `TURN_ENDED` listener calls {@link onTurnEnded} with the incoming
+ *     faction, refreshing that faction's AP in the cyber world and ticking
+ *     the cyber alarm on round advance — both worlds tick, Meatspace keeps
+ *     moving while the Decker is jacked in.
+ *   - **Determinism:** `build` forks `new Rng(contractSeed).fork('cyberspace')`,
+ *     so the layout is a function of the *contract*, independent of the turn
+ *     the player jacks in — and trivially reproducible on restore.
+ *   - **Persistence:** serialization lives in `Run.snapshot` (symmetric with
+ *     the meat world); `persistence.restoreCyberspace` rebuilds the layer via
+ *     the plain constructor. `nodeTiles`/`patrolRings` are build-time spawn
+ *     anchors only — restored layers carry their spawned entities instead.
+ */
+import { EventBus } from '../events.js';
+import { World } from '../World.js';
+import { Rng } from '../../rng.js';
+import { buildCyberMap } from './cyberMapBuild.js';
+import { CyberAvatar } from './CyberAvatar.js';
+import { EntryPort } from './EntryPort.js';
+import { PatrolHostile } from '../ai/PatrolHostile.js';
+import { FACTION, type ContractDifficulty, type FactionId } from '../constants.js';
+import { coordKey } from '../mapConnectivity.js';
+import type { Decker } from '../archetypes/Decker.js';
+import type { GridPoint } from '../../types.js';
+
+export type CyberspaceLayerInit = {
+  bus: EventBus;
+  world: World;
+  avatar: CyberAvatar;
+  port: EntryPort;
+  entryTile: GridPoint;
+  /** Build-time data-node anchors (P3.M3.4). Empty on a restored layer. */
+  nodeTiles?: GridPoint[];
+  /** Build-time Probe patrol rings (P3.M3.5). Empty on a restored layer. */
+  patrolRings?: GridPoint[][];
+};
+
+export type CyberspaceLayerBuildOptions = {
+  contractSeed: number;
+  difficulty: ContractDifficulty;
+  decker: Decker;
+};
+
+export class CyberspaceLayer {
+  readonly bus: EventBus;
+  readonly world: World;
+  readonly avatar: CyberAvatar;
+  readonly port: EntryPort;
+  readonly entryTile: GridPoint;
+  readonly nodeTiles: GridPoint[];
+  readonly patrolRings: GridPoint[][];
+  /** Cyber-grid fog memory — the twin of `Run.mapSeen` for the digital layer. */
+  mapSeen: Set<string>;
+
+  constructor({
+    bus,
+    world,
+    avatar,
+    port,
+    entryTile,
+    nodeTiles,
+    patrolRings,
+  }: CyberspaceLayerInit) {
+    if (!(world instanceof World)) {
+      throw new TypeError('CyberspaceLayer requires a World');
+    }
+    if (!(avatar instanceof CyberAvatar)) {
+      throw new TypeError('CyberspaceLayer requires a CyberAvatar');
+    }
+    if (!(port instanceof EntryPort)) {
+      throw new TypeError('CyberspaceLayer requires an EntryPort');
+    }
+    if (
+      !entryTile ||
+      !Number.isInteger(entryTile.x) ||
+      !Number.isInteger(entryTile.y) ||
+      !world.grid.inBounds(entryTile.x, entryTile.y)
+    ) {
+      throw new RangeError('CyberspaceLayer requires an in-bounds integer entryTile');
+    }
+    this.bus = bus;
+    this.world = world;
+    this.avatar = avatar;
+    this.port = port;
+    this.entryTile = { ...entryTile };
+    this.nodeTiles = (nodeTiles ?? []).map(p => ({ ...p }));
+    this.patrolRings = (patrolRings ?? []).map(ring => ring.map(p => ({ ...p })));
+    this.mapSeen = new Set();
+  }
+
+  /**
+   * Build a fresh layer for `decker` jacking into a contract. Layout is a
+   * deterministic function of the contract seed (see module docstring).
+   */
+  static build({ contractSeed, difficulty, decker }: CyberspaceLayerBuildOptions): CyberspaceLayer {
+    if (!Number.isFinite(contractSeed)) {
+      throw new TypeError(`CyberspaceLayer.build requires a finite contractSeed`);
+    }
+    const rng = new Rng(contractSeed).fork('cyberspace');
+    const map = buildCyberMap({ rng, difficulty });
+    const bus = new EventBus();
+    const world = new World(map.grid, { events: bus });
+    const avatar = new CyberAvatar({
+      id: 'cyber-avatar-0',
+      x: map.entryTile.x,
+      y: map.entryTile.y,
+      ram: decker.ram,
+      intrusionStrength: decker.intrusionStrength,
+      iceResistance: decker.iceResistance,
+      callsign: decker.callsign,
+    });
+    const port = new EntryPort({ id: 'entry-port-0', x: map.portTile.x, y: map.portTile.y });
+    world.addEntity(avatar);
+    world.addEntity(port);
+    return new CyberspaceLayer({
+      bus,
+      world,
+      avatar,
+      port,
+      entryTile: map.entryTile,
+      nodeTiles: map.nodeTiles,
+      patrolRings: map.patrolRings,
+    });
+  }
+
+  /**
+   * Mirror of `TurnQueue.endTurn`'s per-world work, driven by the meat
+   * queue's `TURN_ENDED` payload: refresh the incoming faction's AP in the
+   * cyber world, and tick the cyber alarm on round advance (the incoming
+   * faction wrapping back to PLAYER).
+   */
+  onTurnEnded(next: FactionId): void {
+    for (const entity of this.world.entities.values()) {
+      if (entity.alive && entity.faction === next) {
+        entity.refreshAp();
+      }
+    }
+    if (next === FACTION.PLAYER) {
+      this.world.tickAlarm();
+    }
+  }
+
+  /** Record seen cyber-grid coordinate keys. Out-of-bounds keys are corrupt and throw. */
+  recordSeen(keys: Iterable<string>): void {
+    for (const key of keys) {
+      const point = parseCoordKey(key);
+      if (!this.world.grid.inBounds(point.x, point.y)) {
+        throw new RangeError(`CyberspaceLayer.recordSeen: key "${key}" is out of bounds`);
+      }
+      this.mapSeen.add(coordKey(point.x, point.y));
+    }
+  }
+
+  /** Sorted (row-major) seen keys for byte-stable snapshots. */
+  mapSeenKeys(): string[] {
+    return [...this.mapSeen].sort((a, b) => {
+      const pa = parseCoordKey(a);
+      const pb = parseCoordKey(b);
+      return pa.y === pb.y ? pa.x - pb.x : pa.y - pb.y;
+    });
+  }
+
+  /**
+   * Unbind ICE bus subscriptions on jack-out/death so dead-layer listeners
+   * can never fire again. Probe ICE lands in P3.M3.5; the hook is wired now
+   * so `Run.jackOut` has one teardown seam.
+   */
+  teardown(): void {
+    for (const entity of this.world.entities.values()) {
+      if (entity instanceof PatrolHostile) {
+        entity.unbind();
+      }
+    }
+  }
+}
+
+function parseCoordKey(key: string): GridPoint {
+  if (typeof key !== 'string') {
+    throw new TypeError('CyberspaceLayer: coordinate key must be a string');
+  }
+  const match = /^(-?\d+),(-?\d+)$/.exec(key);
+  if (!match) {
+    throw new TypeError(`CyberspaceLayer: malformed coordinate key "${key}"`);
+  }
+  return { x: Number(match[1]), y: Number(match[2]) };
+}
diff --git a/src/game/cyber/EntryPort.ts b/src/game/cyber/EntryPort.ts
new file mode 100644
index 0000000..ee9cb91
--- /dev/null
+++ b/src/game/cyber/EntryPort.ts
@@ -0,0 +1,53 @@
+/**
+ * P3.M3.3 — Exit port: the Cyberspace door back into Meatspace.
+ *
+ * Anchored at the avatar's entry point on the cyber grid. The avatar (and
+ * only the avatar — capability sniff on `isCyberAvatar`) interacts to route
+ * out: spends interact AP and emits `EVENT.JACK_OUT` on the *cyber* bus.
+ * `Run.jackOut()` listens, latches the objective outcome, and resolves the
+ * layer (voluntary jack-out pulled forward from P3.M4.6; scope decision #2).
+ *
+ * Unlike the meat-side `JackInPoint`, the port does not latch on use — the
+ * resolve latch lives on `Run.cyberspace` (the layer is torn down with it).
+ */
+import {
+  Interactable,
+  type InteractableInit,
+  type InteractResult,
+} from '../entities/Interactable.js';
+import { AP_COST, ENTRY_PORT_GLYPH } from '../constants.js';
+import { EVENT } from '../events.js';
+import type { Entity } from '../Entity.js';
+import type { World } from '../World.js';
+
+export interface EntryPortInit extends Omit<InteractableInit, 'glyph' | 'label'> {
+  label?: string;
+}
+
+/** P2.7.M6.2: exit-port snapshot `extra`. */
+export type EntryPortSnapshot = {
+  label: string;
+};
+
+export class EntryPort extends Interactable {
+  constructor({ label = 'Exit port', ...props }: EntryPortInit) {
+    super({ ...props, glyph: ENTRY_PORT_GLYPH, label });
+  }
+
+  override interact(world: World, actor: Entity): InteractResult {
+    const check = this.canInteract(actor);
+    if (!check.ok) {
+      return { ok: false, reason: check.reason, message: `${this.label}: ${check.reason}.` };
+    }
+    if ((actor as { isCyberAvatar?: boolean }).isCyberAvatar !== true) {
+      return {
+        ok: false,
+        reason: 'not-an-avatar',
+        message: `${this.label}: only the avatar can route out.`,
+      };
+    }
+    actor.spendAp(AP_COST.INTERACT);
+    world.events?.emit(EVENT.JACK_OUT, { port: this, actor });
+    return { ok: true, message: `${this.label}: connection dropped — jacking out.` };
+  }
+}
diff --git a/src/game/cyber/cyberMapBuild.ts b/src/game/cyber/cyberMapBuild.ts
new file mode 100644
index 0000000..541e214
--- /dev/null
+++ b/src/game/cyber/cyberMapBuild.ts
@@ -0,0 +1,172 @@
+/**
+ * P3.M3.3 — Cyberspace map generation.
+ *
+ * Dedicated generator (deliberately NOT the BSP/prefab `buildMap`): a lattice
+ * of square *nodes* (rooms) linked by 1-tile *data lines* (corridors) through
+ * solid firewall (`TILE.WALL` fill). Only FLOOR/WALL tile ids are used, so
+ * Grid passability / LOS, A*, VisionField, and World all work unchanged —
+ * the distinct look comes from the renderer's tileset axis (P3.M3.6), not
+ * from new tile ids.
+ *
+ * Topology: a random spanning walk over a 4×2 slot lattice picks `nodeCount`
+ * slots (scaling with contract difficulty); each slot gets a 3–5 tile square
+ * node and each walk edge a carved L-corridor. The entry node hosts the
+ * avatar spawn (`entryTile`) and the exit port anchor (`portTile`, adjacent).
+ * Non-entry node centers are returned as `nodeTiles` (data-node anchors,
+ * P3.M3.4) with `patrolRings` (Probe ICE waypoints, P3.M3.5) around them.
+ *
+ * Deterministic per `rng` — callers seed with the *contract* seed fork so the
+ * layout is independent of the jack-in turn. Connectivity is validated from
+ * `entryTile`; an unreachable node is a generator bug and throws.
+ */
+import { Grid } from '../Grid.js';
+import { World } from '../World.js';
+import { CONTRACT_DIFFICULTY, TILE, type ContractDifficulty } from '../constants.js';
+import { coordKey, explorationReachableKeys } from '../mapConnectivity.js';
+import type { GridPoint } from '../../types.js';
+import type { Rng } from '../../rng.js';
+
+const LATTICE_COLS = 4;
+const LATTICE_ROWS = 2;
+/** Slot pitch in tiles; each slot's interior is `CELL - 1` tiles square. */
+const CELL = 7;
+
+export const CYBER_MAP_WIDTH = LATTICE_COLS * CELL + 1; // 29
+export const CYBER_MAP_HEIGHT = LATTICE_ROWS * CELL + 1; // 15
+
+/** Node count per contract difficulty — the cyber-side threat/objective budget. */
+const NODE_COUNT: Record<string, number> = Object.freeze({
+  [CONTRACT_DIFFICULTY.STANDARD]: 5,
+  [CONTRACT_DIFFICULTY.ELEVATED]: 6,
+  [CONTRACT_DIFFICULTY.CRITICAL]: 8,
+});
+
+type Slot = { c: number; r: number };
+
+const slotKey = (slot: Slot): string => `${slot.c},${slot.r}`;
+
+export type CyberMapBuildResult = {
+  grid: Grid;
+  /** Avatar spawn — center of the entry node. */
+  entryTile: GridPoint;
+  /** Exit-port anchor, Chebyshev-adjacent to `entryTile` inside the entry node. */
+  portTile: GridPoint;
+  /** Non-entry node centers — data-node anchors (P3.M3.4). */
+  nodeTiles: GridPoint[];
+  /** Per-`nodeTiles` waypoint ring just inside each node — Probe patrols (P3.M3.5). */
+  patrolRings: GridPoint[][];
+};
+
+export function buildCyberMap({
+  rng,
+  difficulty,
+}: {
+  rng: Rng;
+  difficulty: ContractDifficulty;
+}): CyberMapBuildResult {
+  const nodeCount = NODE_COUNT[difficulty];
+  if (!nodeCount) {
+    throw new Error(`buildCyberMap: unknown contract difficulty "${difficulty}"`);
+  }
+
+  // 1. Spanning random walk over the slot lattice. Always connected by
+  // construction (every new slot attaches to a visited one).
+  const startSlot: Slot = { c: 0, r: rng.intRange(0, LATTICE_ROWS) };
+  const visited: Slot[] = [startSlot];
+  const visitedKeys = new Set([slotKey(startSlot)]);
+  const edges: Array<[Slot, Slot]> = [];
+  while (visited.length < nodeCount) {
+    const frontier: Array<[Slot, Slot]> = [];
+    for (const slot of visited) {
+      for (const [dc, dr] of [
+        [1, 0],
+        [-1, 0],
+        [0, 1],
+        [0, -1],
+      ] as const) {
+        const next: Slot = { c: slot.c + dc, r: slot.r + dr };
+        if (next.c < 0 || next.r < 0 || next.c >= LATTICE_COLS || next.r >= LATTICE_ROWS) continue;
+        if (visitedKeys.has(slotKey(next))) continue;
+        frontier.push([slot, next]);
+      }
+    }
+    if (frontier.length === 0) {
+      // Unreachable while nodeCount ≤ lattice slots, but fail loud if the
+      // lattice dimensions and NODE_COUNT ever drift apart.
+      throw new Error(`buildCyberMap: lattice walk exhausted at ${visited.length}/${nodeCount}`);
+    }
+    const [from, to] = rng.pick(frontier);
+    visited.push(to);
+    visitedKeys.add(slotKey(to));
+    edges.push([from, to]);
+  }
+
+  // 2. Carve square nodes into the firewall fill.
+  const grid = new Grid(CYBER_MAP_WIDTH, CYBER_MAP_HEIGHT, TILE.WALL);
+  const centers = new Map<string, GridPoint>();
+  const rings = new Map<string, GridPoint[]>();
+  for (const slot of visited) {
+    const size = rng.intRange(3, 6); // 3–5 tiles square
+    const ox = 1 + slot.c * CELL + Math.floor((CELL - 1 - size) / 2);
+    const oy = 1 + slot.r * CELL + Math.floor((CELL - 1 - size) / 2);
+    for (let y = oy; y < oy + size; y++) {
+      for (let x = ox; x < ox + size; x++) {
+        grid.setTile(x, y, TILE.FLOOR);
+      }
+    }
+    centers.set(slotKey(slot), { x: ox + Math.floor(size / 2), y: oy + Math.floor(size / 2) });
+    // Clockwise perimeter ring just inside the node — Probe patrol waypoints.
+    const ring: GridPoint[] = [];
+    for (let x = ox; x < ox + size; x++) ring.push({ x, y: oy });
+    for (let y = oy + 1; y < oy + size; y++) ring.push({ x: ox + size - 1, y });
+    for (let x = ox + size - 2; x >= ox; x--) ring.push({ x, y: oy + size - 1 });
+    for (let y = oy + size - 2; y >= oy + 1; y--) ring.push({ x: ox, y });
+    rings.set(slotKey(slot), ring);
+  }
+
+  // 3. Carve 1-tile L-corridors (data lines) along the walk edges. Adjacent
+  // slots keep the path inside their two cells, so corridors never clip a
+  // third node.
+  for (const [a, b] of edges) {
+    const ca = centers.get(slotKey(a))!;
+    const cb = centers.get(slotKey(b))!;
+    let x = ca.x;
+    let y = ca.y;
+    while (x !== cb.x) {
+      x += Math.sign(cb.x - x);
+      grid.setTile(x, y, TILE.FLOOR);
+    }
+    while (y !== cb.y) {
+      y += Math.sign(cb.y - y);
+      grid.setTile(x, y, TILE.FLOOR);
+    }
+  }
+
+  // 4. Entry node hosts the avatar spawn and the exit-port anchor. Nodes are
+  // ≥ 3 tiles square, so center+1 is always inside the node.
+  const entryTile = centers.get(slotKey(startSlot))!;
+  const portTile: GridPoint = { x: entryTile.x + 1, y: entryTile.y };
+
+  // 5. Connectivity gate — crash on an unreachable node rather than ship a
+  // map the objective can never complete on.
+  const reachable = explorationReachableKeys(new World(grid), entryTile);
+  if (!reachable.has(coordKey(portTile.x, portTile.y))) {
+    throw new Error(`buildCyberMap: port tile (${portTile.x}, ${portTile.y}) unreachable`);
+  }
+  const nodeTiles: GridPoint[] = [];
+  const patrolRings: GridPoint[][] = [];
+  for (const slot of visited) {
+    const center = centers.get(slotKey(slot))!;
+    if (!reachable.has(coordKey(center.x, center.y))) {
+      throw new Error(
+        `buildCyberMap: node at (${center.x}, ${center.y}) unreachable from entry ` +
+          `(${entryTile.x}, ${entryTile.y})`
+      );
+    }
+    if (slot === startSlot) continue;
+    nodeTiles.push(center);
+    patrolRings.push(rings.get(slotKey(slot))!);
+  }
+
+  return { grid, entryTile, portTile, nodeTiles, patrolRings };
+}
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index 3434b7b..58fd76a 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -72,8 +72,14 @@ import { ConsumablePickup } from './entities/ConsumablePickup.js';
 import { EscortNpc } from './entities/EscortNpc.js';
 import { KeyCard } from './entities/KeyCard.js';
 import { JackInPoint } from './entities/JackInPoint.js';
+import { CyberspaceLayer } from './cyber/CyberspaceLayer.js';
+import { CyberAvatar } from './cyber/CyberAvatar.js';
+import { EntryPort } from './cyber/EntryPort.js';
 import { BreachingCharge } from './entities/BreachingCharge.js';
 import type { BreachingChargeInit } from './entities/BreachingCharge.js';
+import type { CyberAvatarInit, CyberAvatarSnapshot } from './cyber/CyberAvatar.js';
+import type { EntryPortInit, EntryPortSnapshot } from './cyber/EntryPort.js';
+import type { DeckerInit, DeckerSnapshot } from './archetypes/Decker.js';
 import { Run, RUN_STATE, PATROL_ARCHETYPE_IDS } from './Run.js';
 import { Campaign, CAMPAIGN_STATE, normalizeCampaignArc } from './Campaign.js';
 import {
@@ -170,7 +176,10 @@ type RestoreEntityProps = Partial<
     EscortNpcInit &
     KeyCardInit &
     BreachingChargeInit &
-    JackInPointInit
+    JackInPointInit &
+    CyberAvatarInit &
+    EntryPortInit &
+    DeckerInit
 > & {
   id: string;
   x: number;
@@ -188,7 +197,7 @@ const ARCHETYPE_FACTORY: Record<EntityArchetypeId, (props: RestoreEntityProps) =
     merc: (props: RestoreEntityProps) => new Merc(props as CrewInit),
     razor: (props: RestoreEntityProps) => new Razor(props as CrewInit),
     tech: (props: RestoreEntityProps) => new Tech(props as CrewInit),
-    decker: (props: RestoreEntityProps) => new Decker(props as CrewInit),
+    decker: (props: RestoreEntityProps) => new Decker(props as DeckerInit),
     turret: (props: RestoreEntityProps) => new Turret(props as TurretInit),
     drone: (props: RestoreEntityProps) => new Skirmisher(props as SkirmisherProps),
     guard: (props: RestoreEntityProps) => new Guard(props as GuardProps),
@@ -214,6 +223,8 @@ const ARCHETYPE_FACTORY: Record<EntityArchetypeId, (props: RestoreEntityProps) =
     'escort-npc': (props: RestoreEntityProps) => new EscortNpc(props as EscortNpcInit),
     keycard: (props: RestoreEntityProps) => new KeyCard(props as KeyCardInit),
     'jack-in-point': (props: RestoreEntityProps) => new JackInPoint(props as JackInPointInit),
+    'cyber-avatar': (props: RestoreEntityProps) => new CyberAvatar(props as CyberAvatarInit),
+    'entry-port': (props: RestoreEntityProps) => new EntryPort(props as EntryPortInit),
     'breaching-charge': (props: RestoreEntityProps) =>
       new BreachingCharge(props as BreachingChargeInit),
     // Generic fallback so a future `Entity` subclass (NPCs, items) doesn't break
@@ -360,6 +371,47 @@ function readJackInPoint(extra: EntitySnapshotExtra, id: string): JackInPointSna
   };
 }
 
+function readCyberAvatar(extra: EntitySnapshotExtra, id: string): CyberAvatarSnapshot {
+  if (hasNoState(extra)) {
+    throw new TypeError(`restore: cyber avatar entity ${id} requires avatar state`);
+  }
+  const a = extra as Partial<CyberAvatarSnapshot>;
+  if (!Number.isInteger(a.intrusionStrength) || (a.intrusionStrength as number) <= 0) {
+    throw new TypeError(`restore: cyber avatar ${id} intrusionStrength must be a positive integer`);
+  }
+  const callsign = a.callsign ?? null;
+  if (callsign !== null && (typeof callsign !== 'string' || callsign.length === 0)) {
+    throw new TypeError(`restore: cyber avatar ${id} callsign must be a non-empty string or null`);
+  }
+  return { intrusionStrength: a.intrusionStrength as number, callsign };
+}
+
+/**
+ * P3.M3.3: Decker named cyber stats from the run-entity `extra`. All three
+ * absent → pre-P3.M3.3 save, base stats apply (legacy normalization). Any
+ * present-but-malformed or half-populated set is corrupt and throws.
+ */
+function readDeckerCyberStats(extra: EntitySnapshotExtra, id: string): Partial<DeckerInit> {
+  const d = extra as Partial<DeckerSnapshot>;
+  if (d.ram === undefined && d.intrusionStrength === undefined && d.iceResistance === undefined) {
+    return {};
+  }
+  if (!Number.isInteger(d.ram) || (d.ram as number) <= 0) {
+    throw new TypeError(`restore: decker ${id} ram must be a positive integer`);
+  }
+  if (!Number.isInteger(d.intrusionStrength) || (d.intrusionStrength as number) <= 0) {
+    throw new TypeError(`restore: decker ${id} intrusionStrength must be a positive integer`);
+  }
+  if (!Number.isInteger(d.iceResistance) || (d.iceResistance as number) < 0) {
+    throw new TypeError(`restore: decker ${id} iceResistance must be a non-negative integer`);
+  }
+  return {
+    ram: d.ram as number,
+    intrusionStrength: d.intrusionStrength as number,
+    iceResistance: d.iceResistance as number,
+  };
+}
+
 function readDoor(extra: EntitySnapshotExtra, id: string): DoorSnapshot {
   if (hasNoState(extra)) throw new TypeError(`restore: door entity ${id} requires door state`);
   const d = extra as Partial<DoorSnapshot>;
@@ -547,6 +599,52 @@ type RestoreEntry = {
 };
 
 const ENTITY_RESTORE: Partial<Record<EntityArchetypeId, RestoreEntry>> = Object.freeze({
+  decker: {
+    // P3.M3.3: named cyber stats ride the crew extra. Absent on legacy saves
+    // (base stats apply); half-populated or malformed throws.
+    buildProps(extra, rec) {
+      return readDeckerCyberStats(extra, rec.id);
+    },
+    apply(entity, _extra, rec) {
+      if (!(entity instanceof Decker)) {
+        throw new Error(`restore: decker entity ${rec.id} did not restore as Decker`);
+      }
+    },
+  },
+  'cyber-avatar': {
+    buildProps(extra, rec) {
+      const a = readCyberAvatar(extra, rec.id);
+      // The HP pool rides the base entity record: maxHp IS the RAM pool,
+      // damageReduction IS the ICE resistance.
+      return {
+        ram: rec.maxHp,
+        iceResistance: rec.damageReduction ?? 0,
+        intrusionStrength: a.intrusionStrength,
+        callsign: a.callsign,
+      };
+    },
+    apply(entity, _extra, rec) {
+      if (!(entity instanceof CyberAvatar)) {
+        throw new Error(`restore: cyber avatar entity ${rec.id} did not restore as CyberAvatar`);
+      }
+    },
+  },
+  'entry-port': {
+    buildProps(extra, rec) {
+      const p = extra as Partial<EntryPortSnapshot>;
+      return {
+        label: requireString(
+          p.label,
+          `restore: entry port ${rec.id} label must be a non-empty string`
+        ),
+      };
+    },
+    apply(entity, _extra, rec) {
+      if (!(entity instanceof EntryPort)) {
+        throw new Error(`restore: entry port entity ${rec.id} did not restore as EntryPort`);
+      }
+    },
+  },
   tech: {
     // Re-apply the pre-built turret flag (default `true` from the Tech ctor when
     // a legacy record omits it — preserve that by only assigning when present).
@@ -752,6 +850,12 @@ type CampaignCrewSnapshot = {
   alive: boolean;
   inventory: Inventory | null;
   gear: Gear | null;
+  /**
+   * P3.M3.3: Decker named cyber stats — written for deckers only. Absent on
+   * legacy saves (base stats apply); half-populated/malformed throws; present
+   * on a non-decker throws.
+   */
+  cyber?: { ram: number; intrusion: number; iceResistance: number };
 };
 
 type CampaignActiveRunSnapshot = {
@@ -1001,9 +1105,9 @@ export function restore(record: unknown, options: RestoreOptions = {}) {
  *
  * Invariant (both directions): a contract with a Cyberspace component
  * (`contractRequiresCyberspace`) carries a `cyberspace` block, and only such
- * contracts do. Any mismatch, unknown phase, or payload smuggled onto the
- * `dormant` phase is tier-1 corrupt state and throws. P3.M3.3 extends this
- * with the `active` (grid + entities) and `resolved` (latch) phases.
+ * contracts do. Any mismatch, unknown phase, payload smuggled onto the
+ * `dormant`/`resolved` phases, or a partial `active` block is tier-1 corrupt
+ * state and throws.
  */
 function restoreCyberspace(
   record: RunSnapshot,
@@ -1026,17 +1130,139 @@ function restoreCyberspace(
   }
   const phase = (block as { phase?: unknown }).phase;
   if (phase === 'dormant') {
-    const payloadKeys = Object.keys(block).filter(key => key !== 'phase');
-    if (payloadKeys.length > 0) {
-      throw new Error(
-        `restore: dormant cyberspace block must carry no payload, got [${payloadKeys.join(', ')}]`
-      );
-    }
+    assertCyberspaceBlockKeys(block, ['phase'], 'dormant');
     return { phase: 'dormant' };
   }
+  if (phase === 'resolved') {
+    assertCyberspaceBlockKeys(block, ['phase', 'objectiveComplete'], 'resolved');
+    const latch = (block as { objectiveComplete?: unknown }).objectiveComplete;
+    if (typeof latch !== 'boolean') {
+      throw new TypeError('restore: resolved cyberspace block requires boolean objectiveComplete');
+    }
+    return { phase: 'resolved', objectiveComplete: latch };
+  }
+  if (phase === 'active') {
+    assertCyberspaceBlockKeys(
+      block,
+      ['phase', 'grid', 'entities', 'entryTile', 'alarm', 'mapMemory'],
+      'active'
+    );
+    return {
+      phase: 'active',
+      layer: restoreCyberspaceLayer(
+        record,
+        block as Extract<NonNullable<RunSnapshot['cyberspace']>, { phase: 'active' }>
+      ),
+    };
+  }
   throw new Error(`restore: unknown cyberspace phase "${String(phase)}"`);
 }
 
+/** Cross-phase payload smuggling (e.g. a grid on `resolved`) is corrupt — throw. */
+function assertCyberspaceBlockKeys(block: object, allowed: readonly string[], phase: string): void {
+  const rogue = Object.keys(block).filter(key => !allowed.includes(key));
+  if (rogue.length > 0) {
+    throw new Error(
+      `restore: ${phase} cyberspace block carries illegal payload [${rogue.join(', ')}]`
+    );
+  }
+}
+
+/**
+ * P3.M3.3: rebuild the live cyber layer. Every field of the `active` block is
+ * required; entities are bounds-checked against the *cyber* grid via the same
+ * `restoreEntity` codec as the meat world. Exactly one avatar and one exit
+ * port must exist (the avatar must be alive while the run is mid-COMBAT —
+ * avatar death transitions to RESULT before the snapshot is cut).
+ */
+function restoreCyberspaceLayer(
+  record: RunSnapshot,
+  block: Extract<NonNullable<RunSnapshot['cyberspace']>, { phase: 'active' }>
+): CyberspaceLayer {
+  const gridRec = block.grid;
+  if (!gridRec || !Number.isInteger(gridRec.w) || !Number.isInteger(gridRec.h)) {
+    throw new TypeError('restore: active cyberspace block requires a grid with integer w/h');
+  }
+  if (!Array.isArray(gridRec.tiles)) {
+    throw new TypeError('restore: active cyberspace block requires a grid tiles array');
+  }
+  const grid = new Grid(gridRec.w, gridRec.h);
+  if (gridRec.tiles.length !== grid.tiles.length) {
+    throw new Error(
+      `restore: cyberspace grid tile count mismatch — record ${gridRec.tiles.length}, ` +
+        `expected ${grid.tiles.length}`
+    );
+  }
+  for (let i = 0; i < gridRec.tiles.length; i++) {
+    const tile = gridRec.tiles[i];
+    // Cyber maps are FLOOR/WALL only by construction (`buildCyberMap`); any
+    // other tile id is corruption, not an old save.
+    if (tile !== TILE.FLOOR && tile !== TILE.WALL) {
+      throw new Error(`restore: cyberspace grid tile ${i} has non-cyber tile id ${tile}`);
+    }
+    grid.tiles[i] = tile;
+  }
+
+  const entryTile = block.entryTile;
+  if (!entryTile || !Number.isInteger(entryTile.x) || !Number.isInteger(entryTile.y)) {
+    throw new TypeError('restore: active cyberspace block requires an integer entryTile');
+  }
+  if (!grid.inBounds(entryTile.x, entryTile.y) || !grid.isPassable(entryTile.x, entryTile.y)) {
+    throw new RangeError(
+      `restore: cyberspace entryTile (${entryTile.x}, ${entryTile.y}) is not a passable cyber tile`
+    );
+  }
+
+  if (!Array.isArray(block.entities)) {
+    throw new TypeError('restore: active cyberspace block requires an entities array');
+  }
+  if (!block.alarm) {
+    throw new Error('restore: active cyberspace block requires alarm state');
+  }
+  if (!block.mapMemory || !Array.isArray(block.mapMemory.seen)) {
+    throw new TypeError('restore: active cyberspace block requires mapMemory with a seen array');
+  }
+
+  const bus = new EventBus();
+  const world = new World(grid, { events: bus });
+  world.restoreAlarm(block.alarm);
+
+  let avatar: CyberAvatar | null = null;
+  let port: EntryPort | null = null;
+  for (const rec of block.entities) {
+    const entity = restoreEntity(rec, grid);
+    if (entity instanceof CyberAvatar) {
+      if (avatar) {
+        throw new Error('restore: active cyberspace block has multiple cyber-avatar entities');
+      }
+      avatar = entity;
+    }
+    if (entity instanceof EntryPort) {
+      if (port) {
+        throw new Error('restore: active cyberspace block has multiple entry-port entities');
+      }
+      port = entity;
+    }
+    world.addEntity(entity);
+    if (entity instanceof PatrolHostile) {
+      entity.bindToBus(bus);
+    }
+  }
+  if (!avatar) {
+    throw new Error('restore: active cyberspace block has no cyber-avatar');
+  }
+  if (record.state === RUN_STATE.COMBAT && !avatar.alive) {
+    throw new Error('restore: COMBAT snapshot carries a dead cyber-avatar in an active layer');
+  }
+  if (!port) {
+    throw new Error('restore: active cyberspace block has no entry-port');
+  }
+
+  const layer = new CyberspaceLayer({ bus, world, avatar, port, entryTile });
+  layer.recordSeen(block.mapMemory.seen);
+  return layer;
+}
+
 export function restoreCampaign(record: unknown, options: RestoreCampaignOptions = {}): Campaign {
   validateCampaignRecord(record);
   const crew = record.crew.map(restoreCrewMember);
@@ -1326,6 +1552,50 @@ function snapshotCrewMember(member: Crew): CampaignCrewSnapshot {
     alive: !!member.alive,
     inventory: member.inventory,
     gear: member.gear,
+    // P3.M3.3: Decker cyber stats persist through the campaign crew path too.
+    ...(member instanceof Decker
+      ? {
+          cyber: {
+            ram: member.ram,
+            intrusion: member.intrusionStrength,
+            iceResistance: member.iceResistance,
+          },
+        }
+      : {}),
+  };
+}
+
+/**
+ * P3.M3.3: validate + translate the campaign crew `cyber` block into Decker
+ * ctor props. Absent → `{}` (legacy save, base stats). Present on a
+ * non-decker, half-populated, or malformed → throw.
+ */
+function readCampaignCrewCyber(rec: CampaignCrewSnapshot): Partial<DeckerInit> {
+  const cyber = rec.cyber;
+  if (cyber === undefined || cyber === null) return {};
+  if (rec.archetype !== 'decker') {
+    throw new Error(`restoreCampaign: crew "${rec.id}" carries cyber stats but is not a decker`);
+  }
+  if (typeof cyber !== 'object' || Array.isArray(cyber)) {
+    throw new TypeError(`restoreCampaign: crew "${rec.id}" cyber block must be an object`);
+  }
+  if (!Number.isInteger(cyber.ram) || cyber.ram <= 0) {
+    throw new TypeError(`restoreCampaign: crew "${rec.id}" cyber.ram must be a positive integer`);
+  }
+  if (!Number.isInteger(cyber.intrusion) || cyber.intrusion <= 0) {
+    throw new TypeError(
+      `restoreCampaign: crew "${rec.id}" cyber.intrusion must be a positive integer`
+    );
+  }
+  if (!Number.isInteger(cyber.iceResistance) || cyber.iceResistance < 0) {
+    throw new TypeError(
+      `restoreCampaign: crew "${rec.id}" cyber.iceResistance must be a non-negative integer`
+    );
+  }
+  return {
+    ram: cyber.ram,
+    intrusionStrength: cyber.intrusion,
+    iceResistance: cyber.iceResistance,
   };
 }
 
@@ -1364,6 +1634,8 @@ function restoreCrewMember(rec: CampaignCrewSnapshot): Crew {
     gear: rec.gear ?? null,
     maxHp: rec.maxHp,
     maxAp: rec.maxAp,
+    // P3.M3.3: Decker cyber stats (validated; throws on a non-decker record).
+    ...readCampaignCrewCyber(rec),
   });
   if (!(member instanceof Crew)) {
     throw new Error(`restoreCampaign: crew archetype "${rec.archetype}" did not restore as Crew`);
diff --git a/tests/unit/game/cyber/CyberspaceLayer.test.ts b/tests/unit/game/cyber/CyberspaceLayer.test.ts
new file mode 100644
index 0000000..988b728
--- /dev/null
+++ b/tests/unit/game/cyber/CyberspaceLayer.test.ts
@@ -0,0 +1,172 @@
+/**
+ * P3.M3.3 — CyberspaceLayer: the digital tactical layer owned by `Run`.
+ *
+ * Owns its own EventBus / World / CyberAvatar / EntryPort. The avatar's pools
+ * come from the Decker's named cyber stats: RAM = HP pool, ICE resistance =
+ * damageReduction, intrusion strength carried for data-node slicing (S4).
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { CyberspaceLayer } from '../../../../src/game/cyber/CyberspaceLayer.js';
+import { CyberAvatar } from '../../../../src/game/cyber/CyberAvatar.js';
+import { EntryPort } from '../../../../src/game/cyber/EntryPort.js';
+import { Decker } from '../../../../src/game/archetypes/Decker.js';
+import { ALARM_PHASE } from '../../../../src/game/World.js';
+import { EVENT } from '../../../../src/game/events.js';
+import {
+  AP_COST,
+  CYBER_AVATAR_HIT_CHANCE,
+  CYBER_AVATAR_MAX_AP,
+  DECKER_BASE_ICE_RESISTANCE,
+  DECKER_BASE_INTRUSION,
+  DECKER_BASE_RAM,
+  FACTION,
+} from '../../../../src/game/constants.js';
+
+const makeDecker = (overrides = {}) =>
+  new Decker({ id: 'crew-decker', x: 0, y: 0, callsign: 'Phreak', ...overrides });
+
+const buildLayer = (contractSeed = 12345, decker = makeDecker(), difficulty = 'standard') =>
+  CyberspaceLayer.build({ contractSeed, difficulty, decker });
+
+// --- Decker cyber stats ------------------------------------------------------
+
+test('Decker ships base cyber stats', () => {
+  const decker = makeDecker();
+  assert.equal(decker.ram, DECKER_BASE_RAM);
+  assert.equal(decker.intrusionStrength, DECKER_BASE_INTRUSION);
+  assert.equal(decker.iceResistance, DECKER_BASE_ICE_RESISTANCE);
+});
+
+test('Decker cyber stat overrides are validated', () => {
+  assert.throws(() => makeDecker({ ram: 0 }), /ram/);
+  assert.throws(() => makeDecker({ ram: 2.5 }), /ram/);
+  assert.throws(() => makeDecker({ intrusionStrength: 0 }), /intrusion/);
+  assert.throws(() => makeDecker({ intrusionStrength: -1 }), /intrusion/);
+  assert.throws(() => makeDecker({ iceResistance: -1 }), /resistance/i);
+  assert.throws(() => makeDecker({ iceResistance: 0.5 }), /resistance/i);
+  // Zero ICE resistance is legal (no mitigation); zero RAM is not (no pool).
+  assert.equal(makeDecker({ iceResistance: 0 }).iceResistance, 0);
+  assert.equal(makeDecker({ ram: 12 }).ram, 12);
+});
+
+// --- avatar ------------------------------------------------------------------
+
+test('build spawns the avatar at the entry tile with stats from the Decker', () => {
+  const decker = makeDecker({ ram: 10, intrusionStrength: 3, iceResistance: 2 });
+  const layer = buildLayer(777, decker);
+  const avatar = layer.avatar;
+  assert.ok(avatar instanceof CyberAvatar);
+  assert.deepEqual({ x: avatar.x, y: avatar.y }, layer.entryTile);
+  assert.equal(avatar.maxHp, 10);
+  assert.equal(avatar.hp, 10);
+  assert.equal(avatar.damageReduction, 2);
+  assert.equal(avatar.intrusionStrength, 3);
+  assert.equal(avatar.callsign, 'Phreak');
+  assert.equal(avatar.faction, FACTION.PLAYER);
+  assert.equal(avatar.maxAp, CYBER_AVATAR_MAX_AP);
+  assert.equal(avatar.baseHitChance, CYBER_AVATAR_HIT_CHANCE);
+});
+
+test('the cyber world contains exactly the avatar and the exit port', () => {
+  const layer = buildLayer();
+  const entities = Array.from(layer.world.entities.values());
+  assert.equal(entities.filter(e => e instanceof CyberAvatar).length, 1);
+  assert.equal(entities.filter(e => e instanceof EntryPort).length, 1);
+  assert.equal(entities.length, 2);
+  const cheb = Math.max(
+    Math.abs(layer.port.x - layer.avatar.x),
+    Math.abs(layer.port.y - layer.avatar.y)
+  );
+  assert.equal(cheb, 1, 'exit port starts adjacent to the avatar');
+});
+
+test('layer layout is deterministic on the contract seed', () => {
+  const a = buildLayer(424242);
+  const b = buildLayer(424242);
+  assert.deepEqual(Array.from(a.world.grid.tiles), Array.from(b.world.grid.tiles));
+  assert.deepEqual({ x: a.avatar.x, y: a.avatar.y }, { x: b.avatar.x, y: b.avatar.y });
+  assert.deepEqual({ x: a.port.x, y: a.port.y }, { x: b.port.x, y: b.port.y });
+});
+
+test('CyberAvatar validates its pools', () => {
+  const props = { id: 'cyber-avatar-0', x: 1, y: 1 };
+  assert.throws(
+    () => new CyberAvatar({ ...props, ram: 0, intrusionStrength: 2, iceResistance: 1 }),
+    /ram/i
+  );
+  assert.throws(
+    () => new CyberAvatar({ ...props, ram: 8, intrusionStrength: 0, iceResistance: 1 }),
+    /intrusion/i
+  );
+  assert.throws(
+    () => new CyberAvatar({ ...props, ram: 8, intrusionStrength: 2, iceResistance: -1 }),
+    /resistance/i
+  );
+});
+
+// --- turn integration ---------------------------------------------------------
+
+test('onTurnEnded refreshes only the incoming faction in the cyber world', () => {
+  const layer = buildLayer();
+  layer.avatar.spendAp(2);
+  layer.onTurnEnded(FACTION.CORP);
+  assert.equal(layer.avatar.ap, layer.avatar.maxAp - 2, 'corp activation leaves the avatar spent');
+  layer.onTurnEnded(FACTION.PLAYER);
+  assert.equal(layer.avatar.ap, layer.avatar.maxAp, 'player activation refreshes the avatar');
+});
+
+test('onTurnEnded ticks the cyber alarm on round advance (player activation)', () => {
+  const layer = buildLayer();
+  layer.world.raiseAlarm({ repPenalty: false });
+  assert.equal(layer.world.alarm.phase, ALARM_PHASE.ALERT);
+  layer.onTurnEnded(FACTION.CORP);
+  assert.equal(layer.world.alarm.phase, ALARM_PHASE.ALERT, 'corp activation is mid-round');
+  layer.onTurnEnded(FACTION.PLAYER);
+  layer.onTurnEnded(FACTION.PLAYER);
+  assert.equal(layer.world.alarm.phase, ALARM_PHASE.COOLDOWN, 'alert hold expires over rounds');
+});
+
+// --- map memory ----------------------------------------------------------------
+
+test('recordSeen validates bounds and round-trips sorted keys', () => {
+  const layer = buildLayer();
+  const { x, y } = layer.entryTile;
+  layer.recordSeen([`${x},${y}`, `${layer.port.x},${layer.port.y}`]);
+  assert.equal(layer.mapSeenKeys().length, 2);
+  assert.throws(() => layer.recordSeen(['999,999']), /bounds/);
+  assert.throws(() => layer.recordSeen(['not-a-key']), /key/);
+});
+
+// --- exit port ------------------------------------------------------------------
+
+test('the avatar interacting with the exit port emits JACK_OUT once and debits AP', () => {
+  const layer = buildLayer();
+  const payloads: unknown[] = [];
+  layer.bus.on(EVENT.JACK_OUT, payload => payloads.push(payload));
+  const apBefore = layer.avatar.ap;
+  const result = layer.port.interact(layer.world, layer.avatar);
+  assert.equal(result.ok, true);
+  assert.equal(layer.avatar.ap, apBefore - AP_COST.INTERACT);
+  assert.equal(payloads.length, 1);
+  const payload = payloads[0] as { port: EntryPort; actor: unknown };
+  assert.equal(payload.port, layer.port);
+  assert.equal(payload.actor, layer.avatar);
+});
+
+test('a non-avatar cannot route out through the exit port', () => {
+  const layer = buildLayer();
+  // A meat-side Decker standing in the grid is corrupt state; the port still
+  // refuses anything without the avatar capability — including a Decker.
+  const decker = makeDecker();
+  decker.x = layer.avatar.x;
+  decker.y = layer.avatar.y;
+  decker.ap = decker.maxAp = 4;
+  let events = 0;
+  layer.bus.on(EVENT.JACK_OUT, () => events++);
+  const result = layer.port.interact(layer.world, decker);
+  assert.equal(result.ok, false);
+  assert.equal((result as { reason: string }).reason, 'not-an-avatar');
+  assert.equal(events, 0);
+});
diff --git a/tests/unit/game/cyber/cyberMapBuild.test.ts b/tests/unit/game/cyber/cyberMapBuild.test.ts
new file mode 100644
index 0000000..0a41026
--- /dev/null
+++ b/tests/unit/game/cyber/cyberMapBuild.test.ts
@@ -0,0 +1,101 @@
+/**
+ * P3.M3.3 — Cyberspace map generation.
+ *
+ * `buildCyberMap` carves a rooms-as-nodes lattice (data nodes linked by
+ * 1-tile data lines through firewall) using only FLOOR/WALL tile ids, so
+ * Grid passability / LOS / A* / VisionField all work unchanged. Deterministic
+ * per rng seed; every node tile must be reachable from the entry tile.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { buildCyberMap } from '../../../../src/game/cyber/cyberMapBuild.js';
+import { World } from '../../../../src/game/World.js';
+import { explorationReachableKeys, coordKey } from '../../../../src/game/mapConnectivity.js';
+import { TILE, CONTRACT_DIFFICULTY } from '../../../../src/game/constants.js';
+import { Rng } from '../../../../src/rng.js';
+
+const build = (seed = 1, difficulty = CONTRACT_DIFFICULTY.STANDARD) =>
+  buildCyberMap({ rng: new Rng(seed), difficulty });
+
+test('equal seeds build identical cyber maps', () => {
+  const a = build(7);
+  const b = build(7);
+  assert.deepEqual(Array.from(a.grid.tiles), Array.from(b.grid.tiles));
+  assert.deepEqual(a.entryTile, b.entryTile);
+  assert.deepEqual(a.portTile, b.portTile);
+  assert.deepEqual(a.nodeTiles, b.nodeTiles);
+  assert.deepEqual(a.patrolRings, b.patrolRings);
+});
+
+test('different seeds diverge', () => {
+  const base = Array.from(build(1).grid.tiles).join(',');
+  const variants = [2, 3, 4, 5].map(seed => Array.from(build(seed).grid.tiles).join(','));
+  assert.ok(
+    variants.some(tiles => tiles !== base),
+    'expected at least one divergent layout across seeds 2-5'
+  );
+});
+
+test('cyber maps carry only FLOOR and WALL tile ids', () => {
+  for (const difficulty of Object.values(CONTRACT_DIFFICULTY)) {
+    const { grid } = build(11, difficulty);
+    for (const tile of grid.tiles) {
+      assert.ok(
+        tile === TILE.FLOOR || tile === TILE.WALL,
+        `unexpected tile id ${tile} on a ${difficulty} cyber map`
+      );
+    }
+  }
+});
+
+test('entry, port, and every node tile are mutually reachable', () => {
+  for (const difficulty of Object.values(CONTRACT_DIFFICULTY)) {
+    for (let seed = 1; seed <= 10; seed++) {
+      const map = build(seed, difficulty);
+      assert.ok(map.grid.isPassable(map.entryTile.x, map.entryTile.y), 'entry tile passable');
+      const reachable = explorationReachableKeys(new World(map.grid), map.entryTile);
+      assert.ok(reachable.has(coordKey(map.portTile.x, map.portTile.y)), 'port reachable');
+      for (const node of map.nodeTiles) {
+        assert.ok(
+          reachable.has(coordKey(node.x, node.y)),
+          `node (${node.x}, ${node.y}) reachable from entry (seed ${seed}, ${difficulty})`
+        );
+      }
+    }
+  }
+});
+
+test('the exit port sits adjacent to the entry tile', () => {
+  for (let seed = 1; seed <= 5; seed++) {
+    const map = build(seed);
+    const cheb = Math.max(
+      Math.abs(map.portTile.x - map.entryTile.x),
+      Math.abs(map.portTile.y - map.entryTile.y)
+    );
+    assert.equal(cheb, 1);
+    assert.ok(map.grid.isPassable(map.portTile.x, map.portTile.y));
+  }
+});
+
+test('node count scales with contract difficulty', () => {
+  const standard = build(3, CONTRACT_DIFFICULTY.STANDARD).nodeTiles.length;
+  const critical = build(3, CONTRACT_DIFFICULTY.CRITICAL).nodeTiles.length;
+  assert.ok(standard >= 2, `standard maps need slice targets, got ${standard}`);
+  assert.ok(critical > standard, `critical (${critical}) must out-node standard (${standard})`);
+});
+
+test('each non-entry node carries a non-empty passable patrol ring', () => {
+  const map = build(9, CONTRACT_DIFFICULTY.CRITICAL);
+  assert.equal(map.patrolRings.length, map.nodeTiles.length);
+  for (const ring of map.patrolRings) {
+    assert.ok(ring.length > 0);
+    for (const wp of ring) {
+      assert.ok(map.grid.isPassable(wp.x, wp.y), `waypoint (${wp.x}, ${wp.y}) passable`);
+    }
+  }
+});
+
+test('unknown difficulty throws', () => {
+  assert.throws(() => buildCyberMap({ rng: new Rng(1), difficulty: 'impossible' }), /difficulty/);
+});
diff --git a/tests/unit/game/cyber/cyberPersistence.test.ts b/tests/unit/game/cyber/cyberPersistence.test.ts
new file mode 100644
index 0000000..456924e
--- /dev/null
+++ b/tests/unit/game/cyber/cyberPersistence.test.ts
@@ -0,0 +1,404 @@
+/**
+ * P3.M3.3 — Cyberspace persistence: the heart of the slice.
+ *
+ * A mid-jack-in snapshot must round-trip the cyber grid, avatar pools, alarm,
+ * and map memory exactly; the restored run re-wires its cyber listeners.
+ * Malformed blocks throw (crash > data corruption): missing fields, OOB or
+ * duplicated avatars, half-populated Decker cyber stats in *both* crew paths.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { Run, RUN_STATE, OUTCOME } from '../../../../src/game/Run.js';
+import { CyberspaceLayer } from '../../../../src/game/cyber/CyberspaceLayer.js';
+import { CyberAvatar } from '../../../../src/game/cyber/CyberAvatar.js';
+import { EntryPort } from '../../../../src/game/cyber/EntryPort.js';
+import { JackInPoint } from '../../../../src/game/entities/JackInPoint.js';
+import { Decker } from '../../../../src/game/archetypes/Decker.js';
+import { Campaign } from '../../../../src/game/Campaign.js';
+import { EVENT } from '../../../../src/game/events.js';
+import {
+  snapshot,
+  restore,
+  snapshotCampaign,
+  restoreCampaign,
+} from '../../../../src/game/persistence.js';
+import { buildCrewMember } from '../../../../src/game/archetypes/index.js';
+import {
+  DECKER_BASE_ICE_RESISTANCE,
+  DECKER_BASE_INTRUSION,
+  DECKER_BASE_RAM,
+  TILE,
+} from '../../../../src/game/constants.js';
+import { OBJECTIVES } from '../../../../src/game/hub/Curator.js';
+import { Rng } from '../../../../src/rng.js';
+import { testContractContext } from '../contractTestUtils.js';
+import type { World } from '../../../../src/game/World.js';
+import type { Entity } from '../../../../src/game/Entity.js';
+import type { RunEntitySnapshot, RunSnapshot, RunResult } from '../../../../src/game/Run.js';
+
+const cyberContract = (seed = 12345) => ({
+  seed,
+  objective: {
+    kind: OBJECTIVES.DATA_NODE_SLICE,
+    title: 'Spike the server farm',
+    briefing: 'Jack in, slice the data node, then extract.',
+    params: { requiresCyberspace: true, count: 1 },
+  },
+  difficulty: 'standard',
+  threatCount: 1,
+  label: 'cyber test job',
+  context: testContractContext(OBJECTIVES.DATA_NODE_SLICE),
+  reward: { credits: 0, repDelta: 0 },
+});
+
+function makeDecker() {
+  return buildCrewMember('decker', { x: 0, y: 0 }, new Rng(100), { id: 'crew-decker' });
+}
+
+function adjacentFreeTile(world: World, target: Entity) {
+  for (let dy = -1; dy <= 1; dy++) {
+    for (let dx = -1; dx <= 1; dx++) {
+      if (dx === 0 && dy === 0) continue;
+      const x = target.x + dx;
+      const y = target.y + dy;
+      if (world.grid.inBounds(x, y) && world.grid.isPassable(x, y) && !world.entityAt(x, y)) {
+        return { x, y };
+      }
+    }
+  }
+  throw new Error(`no free tile adjacent to ${target.id}`);
+}
+
+function activeRun(seed = 12345, hooks: { onResult?: (r: RunResult) => void } = {}) {
+  const run = new Run({ crewMember: makeDecker(), seed, ...hooks });
+  run.enterBriefing(cyberContract(seed));
+  run.enterCombat();
+  const point = Array.from(run.world!.entities.values()).find(
+    e => e instanceof JackInPoint
+  ) as JackInPoint;
+  const spot = adjacentFreeTile(run.world!, point);
+  run.world!.relocateEntity(run.player!, spot.x, spot.y);
+  run.player!.refreshAp();
+  assert.equal(point.interact(run.world!, run.player!).ok, true);
+  assert.equal(run.cyberspace?.phase, 'active');
+  return run;
+}
+
+function layerOf(run: Run): CyberspaceLayer {
+  assert.equal(run.cyberspace?.phase, 'active');
+  return (run.cyberspace as { phase: 'active'; layer: CyberspaceLayer }).layer;
+}
+
+function activeRecord(seed = 12345): RunSnapshot {
+  const run = activeRun(seed);
+  const layer = layerOf(run);
+  // Dirty the layer so the round-trip carries real state.
+  const dest = adjacentFreeTile(layer.world, layer.avatar);
+  layer.world.relocateEntity(layer.avatar, dest.x, dest.y);
+  layer.avatar.spendAp(1);
+  layer.avatar.damage(2);
+  layer.recordSeen([
+    `${layer.entryTile.x},${layer.entryTile.y}`,
+    `${layer.avatar.x},${layer.avatar.y}`,
+  ]);
+  layer.world.raiseAlarm({ repPenalty: false });
+  return structuredClone(snapshot(run));
+}
+
+function cyberBlock(record: RunSnapshot): Record<string, unknown> {
+  assert.ok(record.cyberspace, 'record carries a cyberspace block');
+  return record.cyberspace as unknown as Record<string, unknown>;
+}
+
+function cyberEntities(record: RunSnapshot): RunEntitySnapshot[] {
+  return cyberBlock(record).entities as RunEntitySnapshot[];
+}
+
+// --- round-trip -------------------------------------------------------------------
+
+test('a mid-jack-in snapshot round-trips the layer exactly', () => {
+  const run = activeRun();
+  const layer = layerOf(run);
+  const dest = adjacentFreeTile(layer.world, layer.avatar);
+  layer.world.relocateEntity(layer.avatar, dest.x, dest.y);
+  layer.avatar.spendAp(1);
+  layer.avatar.damage(2);
+  layer.recordSeen([`${layer.entryTile.x},${layer.entryTile.y}`]);
+  layer.world.raiseAlarm({ repPenalty: false });
+
+  const record = structuredClone(snapshot(run));
+  const { run: restored } = restore(record);
+  assert.equal(restored.cyberspace?.phase, 'active');
+  const restoredLayer = layerOf(restored);
+
+  assert.deepEqual(Array.from(restoredLayer.world.grid.tiles), Array.from(layer.world.grid.tiles));
+  assert.deepEqual(restoredLayer.entryTile, layer.entryTile);
+  const avatar = restoredLayer.avatar;
+  assert.deepEqual(
+    {
+      x: avatar.x,
+      y: avatar.y,
+      hp: avatar.hp,
+      maxHp: avatar.maxHp,
+      ap: avatar.ap,
+      damageReduction: avatar.damageReduction,
+      intrusionStrength: avatar.intrusionStrength,
+      callsign: avatar.callsign,
+    },
+    {
+      x: layer.avatar.x,
+      y: layer.avatar.y,
+      hp: layer.avatar.hp,
+      maxHp: layer.avatar.maxHp,
+      ap: layer.avatar.ap,
+      damageReduction: layer.avatar.damageReduction,
+      intrusionStrength: layer.avatar.intrusionStrength,
+      callsign: layer.avatar.callsign,
+    }
+  );
+  assert.ok(restoredLayer.port instanceof EntryPort);
+  assert.deepEqual(restoredLayer.mapSeenKeys(), layer.mapSeenKeys());
+  assert.deepEqual(restoredLayer.world.snapshotAlarm(), layer.world.snapshotAlarm());
+  // Meatspace round-tripped alongside: the Decker body is still the player.
+  assert.ok(restored.player instanceof Decker);
+});
+
+test('a restored active run re-wires its cyber listeners', () => {
+  const results: RunResult[] = [];
+  const { run: restored } = restore(activeRecord(), { onResult: r => results.push(r) });
+  const layer = layerOf(restored);
+  const avatar = layer.avatar;
+  avatar.damage(avatar.hp);
+  layer.bus.emit(EVENT.ENTITY_DAMAGED, {
+    target: avatar,
+    attacker: null,
+    damage: avatar.maxHp,
+    killed: true,
+    source: 'black-ice',
+  });
+  assert.equal(restored.state, RUN_STATE.RESULT);
+  assert.equal(results[0]?.outcome, OUTCOME.DEATH);
+});
+
+test('a restored active run keeps the dual-world turn cadence', () => {
+  const { run: restored } = restore(activeRecord());
+  const layer = layerOf(restored);
+  layer.avatar.refreshAp();
+  layer.avatar.spendAp(2);
+  restored.queue!.endTurn(restored.world!); // player → corp
+  restored.queue!.endTurn(restored.world!); // corp → player
+  assert.equal(layer.avatar.ap, layer.avatar.maxAp);
+});
+
+test('a resolved layer round-trips its latch', () => {
+  const run = activeRun();
+  const layer = layerOf(run);
+  layer.port.interact(layer.world, layer.avatar);
+  assert.deepEqual(run.cyberspace, { phase: 'resolved', objectiveComplete: false });
+  const record = structuredClone(snapshot(run));
+  assert.deepEqual(record.cyberspace, { phase: 'resolved', objectiveComplete: false });
+  const { run: restored } = restore(record);
+  assert.deepEqual(restored.cyberspace, { phase: 'resolved', objectiveComplete: false });
+  assert.throws(() => restored.jackOut(), /phase/);
+});
+
+// --- adversarial: active block -----------------------------------------------------
+
+test('active block missing a required field throws', () => {
+  for (const field of ['grid', 'entities', 'entryTile', 'alarm', 'mapMemory']) {
+    const record = activeRecord();
+    delete cyberBlock(record)[field];
+    assert.throws(
+      () => restore(record),
+      new RegExp(field === 'mapMemory' ? 'mapMemory' : field),
+      `expected restore to throw on missing cyberspace.${field}`
+    );
+  }
+});
+
+test('active block with unknown payload keys throws', () => {
+  const record = activeRecord();
+  cyberBlock(record).objectiveComplete = true; // resolved-only latch on active phase
+  assert.throws(() => restore(record), /objectiveComplete/);
+});
+
+test('an out-of-bounds cyber entity throws', () => {
+  const record = activeRecord();
+  const avatarRec = cyberEntities(record).find(e => e.archetype === 'cyber-avatar')!;
+  avatarRec.x = 999;
+  assert.throws(() => restore(record), /out of bounds/);
+});
+
+test('zero or multiple avatars throw', () => {
+  const missing = activeRecord();
+  const block = cyberBlock(missing);
+  block.entities = cyberEntities(missing).filter(e => e.archetype !== 'cyber-avatar');
+  assert.throws(() => restore(missing), /avatar/);
+
+  const doubled = activeRecord();
+  const entities = cyberEntities(doubled);
+  const avatarRec = entities.find(e => e.archetype === 'cyber-avatar')!;
+  const clone = structuredClone(avatarRec);
+  clone.id = 'cyber-avatar-1';
+  entities.push(clone);
+  assert.throws(() => restore(doubled), /avatar/);
+});
+
+test('a missing exit port throws', () => {
+  const record = activeRecord();
+  const block = cyberBlock(record);
+  block.entities = cyberEntities(record).filter(e => e.archetype !== 'entry-port');
+  assert.throws(() => restore(record), /port/);
+});
+
+test('non-cyber tile ids in the cyber grid throw', () => {
+  const record = activeRecord();
+  const grid = cyberBlock(record).grid as { tiles: number[] };
+  const wallIndex = grid.tiles.findIndex(t => t === TILE.WALL);
+  assert.ok(wallIndex >= 0);
+  grid.tiles[wallIndex] = TILE.COVER;
+  assert.throws(() => restore(record), /tile/);
+});
+
+test('an avatar record without intrusion state throws', () => {
+  const record = activeRecord();
+  const avatarRec = cyberEntities(record).find(e => e.archetype === 'cyber-avatar')!;
+  delete (avatarRec.extra as Record<string, unknown>).intrusionStrength;
+  assert.throws(() => restore(record), /intrusion/);
+});
+
+// --- adversarial: resolved block -----------------------------------------------------
+
+test('resolved block without its latch throws', () => {
+  const run = activeRun();
+  const layer = layerOf(run);
+  layer.port.interact(layer.world, layer.avatar);
+  const record = structuredClone(snapshot(run));
+  delete cyberBlock(record).objectiveComplete;
+  assert.throws(() => restore(record), /objectiveComplete/);
+});
+
+test('resolved block smuggling active payload throws', () => {
+  const run = activeRun();
+  const layer = layerOf(run);
+  layer.port.interact(layer.world, layer.avatar);
+  const record = structuredClone(snapshot(run));
+  cyberBlock(record).grid = { w: 1, h: 1, tiles: [0] };
+  assert.throws(() => restore(record), /grid/);
+});
+
+// --- Decker cyber stats: run-entity path ---------------------------------------------
+
+test('Decker cyber stats round-trip through the run-entity extra', () => {
+  const record = activeRecord();
+  const deckerRec = record.entities.find(e => e.archetype === 'decker')!;
+  assert.deepEqual(
+    {
+      ram: (deckerRec.extra as Record<string, unknown>).ram,
+      intrusionStrength: (deckerRec.extra as Record<string, unknown>).intrusionStrength,
+      iceResistance: (deckerRec.extra as Record<string, unknown>).iceResistance,
+    },
+    {
+      ram: DECKER_BASE_RAM,
+      intrusionStrength: DECKER_BASE_INTRUSION,
+      iceResistance: DECKER_BASE_ICE_RESISTANCE,
+    }
+  );
+  const { run: restored } = restore(record);
+  const decker = restored.player as Decker;
+  assert.equal(decker.ram, DECKER_BASE_RAM);
+  assert.equal(decker.intrusionStrength, DECKER_BASE_INTRUSION);
+  assert.equal(decker.iceResistance, DECKER_BASE_ICE_RESISTANCE);
+});
+
+test('half-populated Decker cyber stats in the run-entity extra throw', () => {
+  const record = activeRecord();
+  const deckerRec = record.entities.find(e => e.archetype === 'decker')!;
+  delete (deckerRec.extra as Record<string, unknown>).ram;
+  assert.throws(() => restore(record), /ram/);
+});
+
+test('a legacy Decker record without cyber stats restores with base stats', () => {
+  const record = activeRecord();
+  const deckerRec = record.entities.find(e => e.archetype === 'decker')!;
+  const extra = deckerRec.extra as Record<string, unknown>;
+  delete extra.ram;
+  delete extra.intrusionStrength;
+  delete extra.iceResistance;
+  const { run: restored } = restore(record);
+  const decker = restored.player as Decker;
+  assert.equal(decker.ram, DECKER_BASE_RAM);
+  assert.equal(decker.iceResistance, DECKER_BASE_ICE_RESISTANCE);
+});
+
+// --- Decker cyber stats: campaign crew path -------------------------------------------
+
+function act2CampaignWithDecker(): Campaign {
+  const campaign = new Campaign({ seed: 42, rep: 60, completedJobs: 4 });
+  assert.ok(campaign.crew.some(m => m.archetype === 'Decker'));
+  return campaign;
+}
+
+test('campaign crew snapshots carry the Decker cyber block', () => {
+  const record = snapshotCampaign(act2CampaignWithDecker());
+  const deckerRec = record.crew.find(c => c.archetype === 'decker') as unknown as {
+    cyber?: { ram: number; intrusion: number; iceResistance: number };
+  };
+  assert.deepEqual(deckerRec.cyber, {
+    ram: DECKER_BASE_RAM,
+    intrusion: DECKER_BASE_INTRUSION,
+    iceResistance: DECKER_BASE_ICE_RESISTANCE,
+  });
+  const restored = restoreCampaign(structuredClone(record));
+  const decker = restored.crew.find(m => m.archetype === 'Decker') as Decker;
+  assert.equal(decker.ram, DECKER_BASE_RAM);
+  assert.equal(decker.intrusionStrength, DECKER_BASE_INTRUSION);
+});
+
+test('half-populated campaign cyber stats throw; absent stats default', () => {
+  const base = snapshotCampaign(act2CampaignWithDecker());
+
+  const half = structuredClone(base);
+  const halfDecker = half.crew.find(c => c.archetype === 'decker') as unknown as {
+    cyber: Record<string, unknown>;
+  };
+  delete halfDecker.cyber.intrusion;
+  assert.throws(() => restoreCampaign(half), /intrusion/);
+
+  const legacy = structuredClone(base);
+  const legacyDecker = legacy.crew.find(c => c.archetype === 'decker') as unknown as {
+    cyber?: unknown;
+  };
+  delete legacyDecker.cyber;
+  const restored = restoreCampaign(legacy);
+  const decker = restored.crew.find(m => m.archetype === 'Decker') as Decker;
+  assert.equal(decker.ram, DECKER_BASE_RAM);
+});
+
+test('cyber stats on a non-Decker crew record throw', () => {
+  const record = structuredClone(snapshotCampaign(act2CampaignWithDecker()));
+  const mercRec = record.crew.find(c => c.archetype !== 'decker') as unknown as {
+    cyber?: unknown;
+  };
+  mercRec.cyber = { ram: 8, intrusion: 2, iceResistance: 1 };
+  assert.throws(() => restoreCampaign(record), /cyber/);
+});
+
+// --- avatar snapshot extra ------------------------------------------------------------
+
+test('the avatar snapshot rides the entity record (hp pool) plus its extra', () => {
+  const record = activeRecord();
+  const avatarRec = cyberEntities(record).find(e => e.archetype === 'cyber-avatar')!;
+  assert.equal(avatarRec.maxHp, DECKER_BASE_RAM);
+  assert.equal(avatarRec.damageReduction, DECKER_BASE_ICE_RESISTANCE);
+  assert.equal(avatarRec.hp, DECKER_BASE_RAM - 2); // damaged in activeRecord()
+  assert.deepEqual(avatarRec.extra, {
+    intrusionStrength: DECKER_BASE_INTRUSION,
+    callsign: (record.entities.find(e => e.archetype === 'decker')!.extra as { callsign: string })
+      .callsign,
+  });
+  // Restored avatars are real CyberAvatars.
+  const { run: restored } = restore(record);
+  assert.ok(layerOf(restored).avatar instanceof CyberAvatar);
+});
diff --git a/tests/unit/game/cyber/runJackIn.test.ts b/tests/unit/game/cyber/runJackIn.test.ts
new file mode 100644
index 0000000..d92b752
--- /dev/null
+++ b/tests/unit/game/cyber/runJackIn.test.ts
@@ -0,0 +1,242 @@
+/**
+ * P3.M3.3 — Run-level jack-in: the dormant → active transition.
+ *
+ * Linking the jack-in point emits `EVENT.JACK_IN` on the meat bus; `Run`
+ * builds the CyberspaceLayer from the *contract* seed (jack-in-turn
+ * independent), wires the cyber listeners, and keeps Meatspace ticking.
+ * Avatar death routes through the existing DEATH/flatline path.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { Run, RUN_STATE, OUTCOME } from '../../../../src/game/Run.js';
+import { CyberspaceLayer } from '../../../../src/game/cyber/CyberspaceLayer.js';
+import { JackInPoint } from '../../../../src/game/entities/JackInPoint.js';
+import { EVENT } from '../../../../src/game/events.js';
+import { buildCrewMember } from '../../../../src/game/archetypes/index.js';
+import { OBJECTIVES } from '../../../../src/game/hub/Curator.js';
+import { Rng } from '../../../../src/rng.js';
+import { testContractContext } from '../contractTestUtils.js';
+import type { World } from '../../../../src/game/World.js';
+import type { Entity } from '../../../../src/game/Entity.js';
+import type { RunResult, RunSnapshot } from '../../../../src/game/Run.js';
+
+const fakeContract = (overrides = {}) => ({
+  seed: 12345,
+  objective: {
+    kind: OBJECTIVES.REACH_EXIT,
+    title: 'Extract clean',
+    briefing: 'Reach the exit.',
+  },
+  difficulty: 'standard',
+  threatCount: 1,
+  label: 'test job',
+  context: testContractContext(OBJECTIVES.REACH_EXIT),
+  reward: { credits: 0, repDelta: 0 },
+  ...overrides,
+});
+
+const cyberContract = (overrides = {}) =>
+  fakeContract({
+    objective: {
+      kind: OBJECTIVES.DATA_NODE_SLICE,
+      title: 'Spike the server farm',
+      briefing: 'Jack in, slice the data node, then extract.',
+      params: { requiresCyberspace: true, count: 1 },
+    },
+    label: 'cyber test job',
+    context: testContractContext(OBJECTIVES.DATA_NODE_SLICE),
+    ...overrides,
+  });
+
+function makeDecker(x = 0, y = 0) {
+  return buildCrewMember('decker', { x, y }, new Rng(100), { id: 'crew-decker' });
+}
+
+type RunHooks = {
+  onPersist?: (record: RunSnapshot) => void;
+  onResult?: (result: RunResult) => void;
+};
+
+function combatRun(seed = 12345, hooks: RunHooks = {}) {
+  const run = new Run({ crewMember: makeDecker(), seed, ...hooks });
+  run.enterBriefing(cyberContract({ seed }));
+  run.enterCombat();
+  return run;
+}
+
+function jackInPoint(run: Run): JackInPoint {
+  const point = Array.from(run.world!.entities.values()).find(e => e instanceof JackInPoint);
+  assert.ok(point, 'cyber contract placed a jack-in point');
+  return point as JackInPoint;
+}
+
+function adjacentFreeTile(world: World, target: Entity) {
+  for (let dy = -1; dy <= 1; dy++) {
+    for (let dx = -1; dx <= 1; dx++) {
+      if (dx === 0 && dy === 0) continue;
+      const x = target.x + dx;
+      const y = target.y + dy;
+      if (world.grid.inBounds(x, y) && world.grid.isPassable(x, y) && !world.entityAt(x, y)) {
+        return { x, y };
+      }
+    }
+  }
+  throw new Error(`no free tile adjacent to ${target.id}`);
+}
+
+/** Walk the Decker to the port and link. Returns the active layer. */
+function jackIn(run: Run): CyberspaceLayer {
+  const point = jackInPoint(run);
+  const spot = adjacentFreeTile(run.world!, point);
+  run.world!.relocateEntity(run.player!, spot.x, spot.y);
+  run.player!.refreshAp();
+  const result = point.interact(run.world!, run.player!);
+  assert.equal(result.ok, true, `link failed: ${result.message}`);
+  assert.equal(run.cyberspace?.phase, 'active');
+  return (run.cyberspace as { phase: 'active'; layer: CyberspaceLayer }).layer;
+}
+
+// --- golden path ---------------------------------------------------------------
+
+test('linking the port flips the run to an active cyber layer', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  assert.ok(layer instanceof CyberspaceLayer);
+  assert.equal(run.cyberActive, true);
+  assert.equal(run.activeWorld, layer.world);
+  assert.equal(run.activeActor, layer.avatar);
+  // Avatar stats derive from the deployed Decker's base cyber stats.
+  const decker = run.player! as unknown as { ram: number; iceResistance: number };
+  assert.equal(layer.avatar.maxHp, decker.ram);
+  assert.equal(layer.avatar.damageReduction, decker.iceResistance);
+  // The Decker body keeps standing at the port in Meatspace.
+  assert.equal(run.player!.alive, true);
+  assert.ok(run.world!.entities.has(run.player!.id));
+});
+
+test('jack-in autosaves the active layer', () => {
+  const records: RunSnapshot[] = [];
+  const run = combatRun(12345, { onPersist: r => records.push(r) });
+  jackIn(run);
+  const last = records.at(-1)!;
+  assert.equal(last.cyberspace?.phase, 'active');
+  const block = last.cyberspace as { grid: { tiles: number[] }; entities: unknown[] };
+  assert.ok(block.grid.tiles.length > 0);
+  assert.ok(block.entities.length >= 2);
+});
+
+test('layer layout is independent of the jack-in turn', () => {
+  const immediate = jackIn(combatRun(777));
+
+  const late = combatRun(777);
+  late.queue!.endTurn(late.world!); // player → corp
+  late.queue!.endTurn(late.world!); // corp → player (round advance)
+  const lateLayer = jackIn(late);
+
+  assert.deepEqual(Array.from(lateLayer.world.grid.tiles), Array.from(immediate.world.grid.tiles));
+  assert.deepEqual(lateLayer.entryTile, immediate.entryTile);
+
+  // And both equal a fresh build from the same contract seed.
+  const fresh = CyberspaceLayer.build({
+    contractSeed: 777,
+    difficulty: 'standard',
+    decker: makeDecker(),
+  });
+  assert.deepEqual(Array.from(fresh.world.grid.tiles), Array.from(immediate.world.grid.tiles));
+});
+
+// --- illegal transitions ---------------------------------------------------------
+
+test('jackIn while already active throws (corrupt latch)', () => {
+  const run = combatRun();
+  jackIn(run);
+  assert.throws(() => run.jackIn(jackInPoint(run)), /phase/);
+});
+
+test('jackIn outside COMBAT throws', () => {
+  const run = new Run({ crewMember: makeDecker(), seed: 12345 });
+  run.enterBriefing(cyberContract());
+  assert.throws(
+    () => run.jackIn(new JackInPoint({ id: 'jack-in-0', x: 1, y: 1, linked: true })),
+    /COMBAT|illegal/
+  );
+});
+
+test('a JACK_IN emission on a non-cyber contract throws', () => {
+  const run = new Run({ crewMember: makeDecker(), seed: 999 });
+  run.enterBriefing(fakeContract({ seed: 999 }));
+  run.enterCombat();
+  assert.equal(run.cyberspace, null);
+  // Smuggle a port into a non-cyber run — the Run listener must refuse loudly.
+  const point = new JackInPoint({ id: 'jack-in-rogue', x: 0, y: 0 });
+  const spot = adjacentFreeTile(run.world!, run.player!);
+  point.x = spot.x;
+  point.y = spot.y;
+  run.world!.addEntity(point);
+  run.player!.refreshAp();
+  assert.throws(() => point.interact(run.world!, run.player!), /[Cc]yberspace/);
+});
+
+// --- both worlds tick -------------------------------------------------------------
+
+test('meat turn cadence drives the cyber AP refresh', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  layer.avatar.spendAp(3);
+  run.queue!.endTurn(run.world!); // player → corp: avatar stays spent
+  assert.equal(layer.avatar.ap, layer.avatar.maxAp - 3);
+  run.queue!.endTurn(run.world!); // corp → player: avatar refreshes
+  assert.equal(layer.avatar.ap, layer.avatar.maxAp);
+  // The meat body refreshed on the same cadence (single TurnQueue).
+  assert.equal(run.player!.ap, run.player!.maxAp);
+});
+
+// --- avatar death = flatline --------------------------------------------------------
+
+test('avatar death routes through the existing DEATH path', () => {
+  const results: RunResult[] = [];
+  const run = combatRun(12345, { onResult: r => results.push(r) });
+  const layer = jackIn(run);
+  const avatar = layer.avatar;
+  avatar.damage(avatar.hp);
+  layer.bus.emit(EVENT.ENTITY_DAMAGED, {
+    target: avatar,
+    attacker: null,
+    damage: avatar.maxHp,
+    killed: true,
+    source: 'black-ice',
+  });
+  assert.equal(run.state, RUN_STATE.RESULT);
+  assert.equal(results.length, 1);
+  assert.equal(results[0].outcome, OUTCOME.DEATH);
+  assert.match(String(results[0].telemetry.cause), /black-ice/);
+});
+
+// --- voluntary jack-out core (S5 finalizes) -----------------------------------------
+
+test('the avatar routing out resolves the layer', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  const result = layer.port.interact(layer.world, layer.avatar);
+  assert.equal(result.ok, true);
+  assert.deepEqual(run.cyberspace, { phase: 'resolved', objectiveComplete: false });
+  assert.equal(run.state, RUN_STATE.COMBAT, 'jack-out returns to Meatspace, not RESULT');
+  assert.equal(run.cyberActive, false);
+  assert.equal(run.activeWorld, run.world);
+  assert.equal(run.activeActor, run.player);
+  // Resolved is a latch: jacking out twice is corrupt state.
+  assert.throws(() => run.jackOut(), /phase/);
+});
+
+test('re-interacting the meat port after resolve stays refused (LINK BURNED)', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  layer.port.interact(layer.world, layer.avatar);
+  const point = jackInPoint(run);
+  run.player!.refreshAp();
+  const repeat = point.interact(run.world!, run.player!);
+  assert.equal(repeat.ok, false);
+  assert.equal((repeat as { reason: string }).reason, 'already-linked');
+  assert.equal(run.cyberspace?.phase, 'resolved');
+});

From 5f90d44d08ce494e9c95ead6868bd63f519ee325 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Wed, 10 Jun 2026 13:57:13 -0700
Subject: [PATCH 18/55] =?UTF-8?q?P3.M3=20plan:=20S3=20shipped=20=E2=80=94?=
 =?UTF-8?q?=20progress=20row,=20implementation=20notes,=20deviations?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/phase-3-cyberspace-plan.md | 70 +++++++++++++++++++++++++++++++--
 1 file changed, 66 insertions(+), 4 deletions(-)

diff --git a/docs/phase-3-cyberspace-plan.md b/docs/phase-3-cyberspace-plan.md
index 1347aa4..b03c2ba 100644
--- a/docs/phase-3-cyberspace-plan.md
+++ b/docs/phase-3-cyberspace-plan.md
@@ -31,7 +31,7 @@ Commits land **per green slice** (user-approved).
 |---|---|---|
 | **S1 — P3.M3.1 Contract flag + gates** | ✅ Done | `f436330` |
 | **S2 — P3.M3.2 Jack-in terminal** | ✅ Done | `05013f6` |
-| **S3 — P3.M3.3 Cyber layer model + avatar + persistence** | 🔨 In progress (research done, no code yet) | — |
+| **S3 — P3.M3.3 Cyber layer model + avatar + persistence** | ✅ Done | `39b357e` |
 | **S4 — P3.M3.4 Data node objective** | 🔲 Planned | — |
 | **S5 — Voluntary jack-out (M4.6 pull-forward)** | 🔲 Planned | — |
 | **S6 — P3.M3.5 Probe ICE** | 🔲 Planned | — |
@@ -98,6 +98,68 @@ Commits land **per green slice** (user-approved).
 - Tests: `tests/unit/game/jackInPoint.test.ts` (12 tests — interact behavior,
   placement determinism, round-trip, adversarial restore throws).
 
+### S3 implementation notes (shipped)
+
+- `src/game/cyber/cyberMapBuild.ts` — `buildCyberMap({rng, difficulty})`:
+  spanning random walk over a 4×2 cell lattice (29×15 grid), square rooms
+  (3–6) centered per cell, L-corridors along walk edges, clockwise perimeter
+  patrol rings. Node count by difficulty: standard 5 / elevated 6 / critical 8
+  (unknown difficulty throws). `entryTile` = entry room center;
+  **deviation: returns `portTile`** (Chebyshev-1 from entry) so layer build
+  doesn't re-derive placement. Connectivity flood
+  (`explorationReachableKeys`) validates every node + port reachable; throws
+  otherwise. Returned `nodeTiles`/`patrolRings` exclude the entry node.
+- `src/game/cyber/CyberAvatar.ts` — `Entity` subclass: `maxHp = ram`,
+  `damageReduction = iceResistance` (0 is legal), `intrusionStrength`,
+  `callsign`, maxAp 4, `baseHitChance` 0.8 (sniffed by `Combat.resolveRanged`
+  — zero combat changes needed). **Deviation: capability flag is
+  `readonly isCyberAvatar = true`**, not the planned `intrusionStrength`
+  sniff — the Decker now carries `intrusionStrength` too, so the stat sniff
+  would have let the meat body use cyber interactables.
+- `src/game/cyber/EntryPort.ts` — avatar-only interact (`'not-an-avatar'`
+  refusal), spends interact AP, emits `EVENT.JACK_OUT` once. Deliberately
+  does **not** latch — the resolve latch lives on `Run.cyberspace`.
+- `src/game/cyber/CyberspaceLayer.ts` — own bus + `World`;
+  `static build({contractSeed, difficulty, decker})` forks
+  `new Rng(contractSeed).fork('cyberspace')` (layout independent of jack-in
+  turn — regression-tested); plain ctor used by restore (restored layers have
+  empty `nodeTiles`/`patrolRings` — those are build-time spawn anchors only);
+  `onTurnEnded(next)` refreshes incoming-faction AP + ticks cyber alarm on
+  PLAYER; `recordSeen` bounds-validates (throws); `teardown()` unbinds patrol
+  hostiles (S6 seam). **Deviation: no `layer.snapshot()`** — serialization
+  lives in Run's `snapshotCyberspace` beside the entity extractor registry.
+- `Run.ts` — `CyberspaceState` active/resolved arms;
+  `cyberActive`/`activeWorld`/`activeActor` accessors (shell seam for S7);
+  `jackIn(point)` throws unless COMBAT + cyber contract + dormant + linked
+  `JackInPoint` + Decker player; `jackOut()` latches
+  `objectiveComplete: false` (**TODO(P3.M3.4)**: real value once nodes
+  exist); both autosave explicitly. `#onTurnEnded` now consumes the `{next}`
+  payload (throws if absent) and forwards to the layer before autosave. Cyber
+  `ENTITY_DAMAGED` listener mirrors the meat player-death handler — avatar
+  killed → telemetry cause → `enterResult(DEATH)` → existing flatline path
+  (scope decision #3).
+- `persistence.ts` — `restoreCyberspace` per-phase **allowed-keys checks**
+  (cross-phase payload smuggling throws); active block validates grid dims +
+  FLOOR/WALL-only tile values, entryTile in-bounds/passable, alarm,
+  mapMemory; entities restored via `restoreEntity(rec, grid)` against the
+  **cyber** grid; exactly one avatar and one port (duplicates throw).
+  **Deviation: a dead avatar is legal when `record.state !== COMBAT`** — a
+  RESULT-state death snapshot legitimately carries one; alive required only
+  for COMBAT records. **Deviation: no `seed` field in the active block** —
+  the serialized grid is authoritative. Decker cyber stats round-trip through
+  both crew paths (`CampaignCrewSnapshot.cyber?` + run-entity `decker`
+  extra): all-absent → `DECKER_BASE_*` defaults (legacy saves),
+  half-populated/malformed → throw, `cyber` on a non-decker throws.
+- `Decker.ts`/`constants.ts` — `ram` 8 / `intrusionStrength` 2 /
+  `iceResistance` 1 base constants, validated mutable fields (scope
+  decision #4).
+- Tests: 49 across `tests/unit/game/cyber/` — `cyberMapBuild.test.ts` (8),
+  `CyberspaceLayer.test.ts` (11), `runJackIn.test.ts` (10),
+  `cyberPersistence.test.ts` (20, the adversarial heart). Failing-first
+  verified; full suite 1604 green.
+- Playtest note (pre-S7): jack-in flips state internally but the shell still
+  renders Meatspace until the S7 render/input swap — expected, not a bug.
+
 ## Architecture decisions (approved plan)
 
 ### Cyber layer model — `CyberspaceLayer` owned by `Run`, single `TurnQueue`, both worlds tick
@@ -108,8 +170,8 @@ New `src/game/cyber/CyberspaceLayer.ts`: owns its own `EventBus`, `World`
 ```ts
 type CyberspaceState =
   | { phase: 'dormant' }                                // shipped (S2)
-  | { phase: 'active'; layer: CyberspaceLayer }         // S3
-  | { phase: 'resolved'; objectiveComplete: boolean };  // S3/S5
+  | { phase: 'active'; layer: CyberspaceLayer }         // shipped (S3)
+  | { phase: 'resolved'; objectiveComplete: boolean };  // shipped (S3); S5 finalizes
 Run.cyberspace: CyberspaceState | null;                 // null ⇔ no cyber component
 ```
 
@@ -277,7 +339,7 @@ subset; all throws, `restoreOverrideState` style):
   while jacked in — single queue); `jackIn`/`jackOut` call `onPersist`
   explicitly.
 
-## S3 detailed worklist (next up — research complete, no code yet)
+## S3 detailed worklist (shipped in `39b357e` — see implementation notes above for deviations)
 
 **Create:**
 - `src/game/cyber/cyberMapBuild.ts` — `buildCyberMap({rng, difficulty})` per

From 392314990a5194337b92e2587c39d38426dc1c73 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Wed, 10 Jun 2026 14:14:26 -0700
Subject: [PATCH 19/55] =?UTF-8?q?P3.M3.4:=20data=20node=20objective=20?=
 =?UTF-8?q?=E2=80=94=20slice=20targets,=20satisfaction,=20NODES=20chip?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

S4 of the cyberspace slice plan. The layer now has a reason to exist:

- DataNode interactable (glyph ◈): interact adds the actor's
  intrusionStrength to sliceProgress; sliced at sliceDifficulty (2/3/4 by
  contract difficulty). Avatar-only via the isCyberAvatar sniff — the
  Decker body also carries intrusionStrength, so the stat is not the
  capability. Slicing is silent; ICE detection (S6) owns the cyber alarm.
  Progress is raw (never clamped) so persisted state loses nothing.
- CyberspaceLayer.build gains required nodeCount (the contract objective's
  count — required, not defaulted, so a divergence can't silently corrupt
  the objective) and spawns nodes on the farthest node anchors from entry,
  Chebyshev-sorted stable over the deterministic generator order.
- Run: ObjectiveState.cyber tally threaded per phase (live count while
  active, the resolved latch after jack-out, zero while dormant);
  DATA_NODE_SLICE satisfaction counts sliced >= required; jackOut latches
  objectiveComplete from the real tally — jacking out early leaves the
  objective permanently unsatisfiable and extraction gated through the
  existing abort-confirm flow (zero new extraction code).
- objectiveProgress: dataNodeProgress helper + NODES HUD chip; the chip
  pipeline is kind-generic so no shell changes needed.
- persistence: data-node entity codec (label/sliceDifficulty/sliceProgress,
  malformed throws); active cyberspace blocks must carry exactly the
  contract's node count (nodes never despawn — any drift is corruption).

25 new tests (dataNode.test.ts, dataNodeObjective.test.ts; failing-first
verified), suite at 1629 green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/game/Entity.ts                            |   1 +
 src/game/Run.ts                               |  67 +++-
 src/game/constants.ts                         |   2 +
 src/game/cyber/CyberspaceLayer.ts             |  45 ++-
 src/game/cyber/DataNode.ts                    | 112 +++++++
 src/game/objectiveProgress.ts                 |  39 ++-
 src/game/persistence.ts                       |  47 +++
 tests/unit/game/cyber/CyberspaceLayer.test.ts |   7 +-
 tests/unit/game/cyber/dataNode.test.ts        | 171 ++++++++++
 .../unit/game/cyber/dataNodeObjective.test.ts | 308 ++++++++++++++++++
 tests/unit/game/cyber/runJackIn.test.ts       |   1 +
 11 files changed, 785 insertions(+), 15 deletions(-)
 create mode 100644 src/game/cyber/DataNode.ts
 create mode 100644 tests/unit/game/cyber/dataNode.test.ts
 create mode 100644 tests/unit/game/cyber/dataNodeObjective.test.ts

diff --git a/src/game/Entity.ts b/src/game/Entity.ts
index f70e130..8307a6d 100644
--- a/src/game/Entity.ts
+++ b/src/game/Entity.ts
@@ -277,6 +277,7 @@ function kindFromId(id: string): string {
   if (id.startsWith('jack-in')) return 'Jack-in Port';
   if (id.startsWith('cyber-avatar')) return 'Avatar';
   if (id.startsWith('entry-port')) return 'Exit Port';
+  if (id.startsWith('data-node')) return 'Data Node';
   if (id.includes('turret')) return 'Turret';
   if (id.startsWith('crew')) return 'Operative';
   return id;
diff --git a/src/game/Run.ts b/src/game/Run.ts
index 61f4641..be2aa82 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -82,16 +82,19 @@ import { JackInPoint } from './entities/JackInPoint.js';
 import { CyberspaceLayer } from './cyber/CyberspaceLayer.js';
 import { CyberAvatar } from './cyber/CyberAvatar.js';
 import { EntryPort } from './cyber/EntryPort.js';
+import { DataNode } from './cyber/DataNode.js';
 import { applyMutationDeltas } from './locations.js';
 import { BreachingCharge } from './entities/BreachingCharge.js';
 import { ITEM_ID, getItemById } from './items.js';
 import { resetCorpTurnStatusCache } from './corpTurnStatusCopy.js';
 import {
   objectiveProgress as resolveObjectiveProgress,
+  dataNodeProgress,
   reconObjectiveProgress,
   sweepQuotaType,
   SWEEP_QUOTA,
 } from './objectiveProgress.js';
+import type { CyberNodeProgress } from './objectiveProgress.js';
 import { NeutralCivilian } from './entities/NeutralCivilian.js';
 import { VisionField } from './Vision.js';
 import {
@@ -128,6 +131,7 @@ import type { JackInPointSnapshot } from './entities/JackInPoint.js';
 import type { KeyCardSnapshot } from './entities/KeyCard.js';
 import type { CyberAvatarSnapshot } from './cyber/CyberAvatar.js';
 import type { EntryPortSnapshot } from './cyber/EntryPort.js';
+import type { DataNodeSnapshot } from './cyber/DataNode.js';
 import type { DeckerSnapshot } from './archetypes/Decker.js';
 import type { AlarmState } from './World.js';
 
@@ -175,6 +179,7 @@ export type EntityArchetypeId =
   | 'jack-in-point'
   | 'cyber-avatar'
   | 'entry-port'
+  | 'data-node'
   | 'entity';
 
 export type RunTelemetry = {
@@ -856,6 +861,7 @@ export class Run {
       contractSeed: this.contract.seed,
       difficulty: this.contract.difficulty,
       decker: this.player,
+      nodeCount: objectiveCount(this.contract),
     });
     this.cyberspace = { phase: 'active', layer };
     this.#wireCyberLayerListeners(layer);
@@ -880,9 +886,15 @@ export class Run {
         `Run.jackOut: illegal from cyberspace phase "${this.cyberspace?.phase ?? 'none'}"`
       );
     }
+    if (!this.contract) {
+      throw new Error('Run.jackOut: COMBAT state without a contract');
+    }
     const layer = this.cyberspace.layer;
-    // TODO(P3.M3.4): derive from sliced data-node count once nodes exist.
-    const objectiveComplete = false;
+    // P3.M3.4: the latch is the sliced-node tally at the moment the link
+    // drops. Jacking out early leaves the objective permanently unsatisfiable
+    // — extraction then routes through the existing abort-confirm flow.
+    const { sliced } = dataNodeProgress(layer.world);
+    const objectiveComplete = sliced >= objectiveCount(this.contract);
     layer.teardown();
     this.cyberspace = { phase: 'resolved', objectiveComplete };
     if (this.onPersist) {
@@ -987,7 +999,31 @@ export class Run {
 
   objectiveProgress() {
     if (!this.contract) return null;
-    return resolveObjectiveProgress(this.contract, this.world, this.mapSeen);
+    return resolveObjectiveProgress(
+      this.contract,
+      this.world,
+      this.mapSeen,
+      this.#cyberNodeProgress() ?? null
+    );
+  }
+
+  /**
+   * P3.M3.4: the data-node tally per cyberspace phase — live count while the
+   * layer is active, the latch once resolved, zero while dormant. `undefined`
+   * for contracts without a Cyberspace component.
+   */
+  #cyberNodeProgress(): CyberNodeProgress | undefined {
+    if (!this.contract || !this.cyberspace) return undefined;
+    if (this.contract.objective.kind !== OBJECTIVES.DATA_NODE_SLICE) return undefined;
+    const required = objectiveCount(this.contract);
+    switch (this.cyberspace.phase) {
+      case 'dormant':
+        return { sliced: 0, required };
+      case 'active':
+        return { sliced: dataNodeProgress(this.cyberspace.layer.world).sliced, required };
+      case 'resolved':
+        return { sliced: this.cyberspace.objectiveComplete ? required : 0, required };
+    }
   }
 
   /**
@@ -1625,6 +1661,7 @@ export class Run {
     const satisfied = isObjectiveSatisfied(this.contract, this.world, timing, {
       mapSeen: this.mapSeen,
       reconSeen: this.mapSeen,
+      cyber: this.#cyberNodeProgress(),
     });
     const limit = turnLimitForContract(this.contract);
     if (limit === null || !this.queue) return satisfied;
@@ -1681,6 +1718,8 @@ export type ObjectiveTiming = {
 export type ObjectiveState = {
   mapSeen?: ReadonlySet<string> | readonly string[];
   reconSeen?: ReadonlySet<string> | readonly string[];
+  /** P3.M3.4: data-node tally for `data-node-slice` contracts. */
+  cyber?: CyberNodeProgress;
 };
 
 export function isObjectiveSatisfied(
@@ -1727,11 +1766,14 @@ function isObjectiveFamilySatisfied(
       return isReconSatisfied(world, objectiveState);
     case OBJECTIVES.ESCORT_EXTRACT:
       return isEscortExtractSatisfied(world);
-    case OBJECTIVES.DATA_NODE_SLICE:
-      // P3.M3.1: satisfaction requires the Cyberspace layer (P3.M3.4 wires
-      // sliced-node counting through ObjectiveState). Until then a cyber
-      // contract is honestly unsatisfiable — extraction stays gated.
-      return false;
+    case OBJECTIVES.DATA_NODE_SLICE: {
+      // P3.M3.4: `Run` threads the per-phase node tally through
+      // `ObjectiveState.cyber` (live count / resolved latch / dormant zero).
+      // Without it — e.g. a bare `isObjectiveSatisfied` call — the objective
+      // is honestly unsatisfiable and extraction stays gated.
+      const cyber = objectiveState?.cyber;
+      return !!cyber && cyber.required > 0 && cyber.sliced >= cyber.required;
+    }
     default: {
       const exhaustive: never = kind;
       throw new Error(`Run.isObjectiveSatisfied: unknown objective kind "${exhaustive}"`);
@@ -1981,6 +2023,14 @@ const SNAPSHOT_EXTRACTORS: Partial<Record<EntityArchetypeId, (e: Entity) => Enti
     'entry-port': e => {
       return { label: (e as EntryPort).label } satisfies EntryPortSnapshot;
     },
+    'data-node': e => {
+      const n = e as DataNode;
+      return {
+        label: n.label,
+        sliceDifficulty: n.sliceDifficulty,
+        sliceProgress: n.sliceProgress,
+      } satisfies DataNodeSnapshot;
+    },
   };
 
 /**
@@ -2069,6 +2119,7 @@ function archetypeOf(entity: Entity): EntityArchetypeId {
   if (entity instanceof JackInPoint) return 'jack-in-point';
   if (entity instanceof CyberAvatar) return 'cyber-avatar';
   if (entity instanceof EntryPort) return 'entry-port';
+  if (entity instanceof DataNode) return 'data-node';
   if (entity instanceof BreachingCharge) return 'breaching-charge';
   if (entity instanceof Entity) return 'entity';
   throw new Error(`archetypeOf: cannot classify entity ${(entity as Entity | undefined)?.id}`);
diff --git a/src/game/constants.ts b/src/game/constants.ts
index 8d628ce..199b5b2 100644
--- a/src/game/constants.ts
+++ b/src/game/constants.ts
@@ -48,6 +48,8 @@ export const KEYCARD_GLYPH = 'κ';
 export const JACK_IN_GLYPH = 'Ω';
 /** P3.M3.3: the Cyberspace door back into Meatspace. */
 export const ENTRY_PORT_GLYPH = '▼';
+/** P3.M3.4: the slice target on the cyber grid (`◆` is DenyTarget's). */
+export const DATA_NODE_GLYPH = '◈';
 
 /** Numeric tile id — one of the `TILE` values. */
 export type TileId = (typeof TILE)[keyof typeof TILE];
diff --git a/src/game/cyber/CyberspaceLayer.ts b/src/game/cyber/CyberspaceLayer.ts
index 504a229..ed110d4 100644
--- a/src/game/cyber/CyberspaceLayer.ts
+++ b/src/game/cyber/CyberspaceLayer.ts
@@ -25,6 +25,7 @@ import { Rng } from '../../rng.js';
 import { buildCyberMap } from './cyberMapBuild.js';
 import { CyberAvatar } from './CyberAvatar.js';
 import { EntryPort } from './EntryPort.js';
+import { DataNode, sliceDifficultyFor } from './DataNode.js';
 import { PatrolHostile } from '../ai/PatrolHostile.js';
 import { FACTION, type ContractDifficulty, type FactionId } from '../constants.js';
 import { coordKey } from '../mapConnectivity.js';
@@ -47,6 +48,12 @@ export type CyberspaceLayerBuildOptions = {
   contractSeed: number;
   difficulty: ContractDifficulty;
   decker: Decker;
+  /**
+   * P3.M3.4: data nodes to spawn — the contract objective's `count`.
+   * Deliberately required (no default): a count silently diverging from the
+   * contract would corrupt the objective.
+   */
+  nodeCount: number;
 };
 
 export class CyberspaceLayer {
@@ -100,12 +107,26 @@ export class CyberspaceLayer {
    * Build a fresh layer for `decker` jacking into a contract. Layout is a
    * deterministic function of the contract seed (see module docstring).
    */
-  static build({ contractSeed, difficulty, decker }: CyberspaceLayerBuildOptions): CyberspaceLayer {
+  static build({
+    contractSeed,
+    difficulty,
+    decker,
+    nodeCount,
+  }: CyberspaceLayerBuildOptions): CyberspaceLayer {
     if (!Number.isFinite(contractSeed)) {
       throw new TypeError(`CyberspaceLayer.build requires a finite contractSeed`);
     }
+    if (!Number.isInteger(nodeCount) || nodeCount <= 0) {
+      throw new RangeError(`CyberspaceLayer.build nodeCount must be a positive integer`);
+    }
     const rng = new Rng(contractSeed).fork('cyberspace');
     const map = buildCyberMap({ rng, difficulty });
+    if (nodeCount > map.nodeTiles.length) {
+      throw new RangeError(
+        `CyberspaceLayer.build: nodeCount ${nodeCount} exceeds the map's ` +
+          `${map.nodeTiles.length} node tiles`
+      );
+    }
     const bus = new EventBus();
     const world = new World(map.grid, { events: bus });
     const avatar = new CyberAvatar({
@@ -120,6 +141,24 @@ export class CyberspaceLayer {
     const port = new EntryPort({ id: 'entry-port-0', x: map.portTile.x, y: map.portTile.y });
     world.addEntity(avatar);
     world.addEntity(port);
+    // P3.M3.4: data nodes claim the *farthest* node anchors from the entry —
+    // the avatar has to cross the lattice (and, from P3.M3.5, the ICE
+    // patrolling it). Chebyshev sort is stable over the deterministic
+    // generator order, so placement is a pure function of the contract seed.
+    const sliceDifficulty = sliceDifficultyFor(difficulty);
+    const anchors = [...map.nodeTiles].sort(
+      (a, b) => chebyshevFrom(map.entryTile, b) - chebyshevFrom(map.entryTile, a)
+    );
+    for (let i = 0; i < nodeCount; i++) {
+      world.addEntity(
+        new DataNode({
+          id: `data-node-${i}`,
+          x: anchors[i].x,
+          y: anchors[i].y,
+          sliceDifficulty,
+        })
+      );
+    }
     return new CyberspaceLayer({
       bus,
       world,
@@ -182,6 +221,10 @@ export class CyberspaceLayer {
   }
 }
 
+function chebyshevFrom(a: GridPoint, b: GridPoint): number {
+  return Math.max(Math.abs(a.x - b.x), Math.abs(a.y - b.y));
+}
+
 function parseCoordKey(key: string): GridPoint {
   if (typeof key !== 'string') {
     throw new TypeError('CyberspaceLayer: coordinate key must be a string');
diff --git a/src/game/cyber/DataNode.ts b/src/game/cyber/DataNode.ts
new file mode 100644
index 0000000..5833a1e
--- /dev/null
+++ b/src/game/cyber/DataNode.ts
@@ -0,0 +1,112 @@
+/**
+ * P3.M3.4 — DataNode: the slice target the Decker's avatar came for.
+ *
+ * Interacting adds the actor's `intrusionStrength` to `sliceProgress`; the
+ * node is sliced once progress reaches `sliceDifficulty` (2/3/4 by contract
+ * difficulty). This is scope decision #4 made concrete — intrusion strength
+ * is *the* stat that moves the objective. Only the avatar can slice
+ * (capability sniff on `isCyberAvatar`, same rule as `EntryPort`: the Decker
+ * body also carries `intrusionStrength`, so the stat must not be the sniff).
+ *
+ * Slicing is silent — ICE detection (P3.M3.5), not the slice itself, raises
+ * the cyber alarm. `sliceProgress` is raw (not clamped to the threshold) so
+ * persisted state never loses information.
+ */
+import {
+  Interactable,
+  type InteractableInit,
+  type InteractResult,
+} from '../entities/Interactable.js';
+import { AP_COST, DATA_NODE_GLYPH, type ContractDifficulty } from '../constants.js';
+import type { Entity } from '../Entity.js';
+import type { World } from '../World.js';
+
+/** Intrusion needed to slice a node, by contract difficulty. */
+const SLICE_DIFFICULTY: Record<ContractDifficulty, number> = Object.freeze({
+  standard: 2,
+  elevated: 3,
+  critical: 4,
+});
+
+export function sliceDifficultyFor(difficulty: ContractDifficulty): number {
+  const threshold = SLICE_DIFFICULTY[difficulty];
+  if (threshold === undefined) {
+    throw new RangeError(`sliceDifficultyFor: unknown contract difficulty "${difficulty}"`);
+  }
+  return threshold;
+}
+
+export interface DataNodeInit extends Omit<InteractableInit, 'glyph' | 'label'> {
+  label?: string;
+  /** Intrusion threshold to slice. Required — derived from contract difficulty. */
+  sliceDifficulty: number;
+  sliceProgress?: number;
+}
+
+/** P2.7.M6.2: data-node snapshot `extra`. */
+export type DataNodeSnapshot = {
+  label: string;
+  sliceDifficulty: number;
+  sliceProgress: number;
+};
+
+export class DataNode extends Interactable {
+  sliceDifficulty: number;
+  sliceProgress: number;
+
+  constructor({ label = 'Data node', sliceDifficulty, sliceProgress = 0, ...props }: DataNodeInit) {
+    if (!Number.isInteger(sliceDifficulty) || sliceDifficulty <= 0) {
+      throw new RangeError(
+        `DataNode sliceDifficulty must be a positive integer, got ${sliceDifficulty}`
+      );
+    }
+    if (!Number.isInteger(sliceProgress) || sliceProgress < 0) {
+      throw new RangeError(
+        `DataNode sliceProgress must be a non-negative integer, got ${sliceProgress}`
+      );
+    }
+    const sliced = sliceProgress >= sliceDifficulty;
+    super({
+      ...props,
+      glyph: DATA_NODE_GLYPH,
+      label,
+      secured: sliced,
+      armed: !sliced,
+    });
+    this.sliceDifficulty = sliceDifficulty;
+    this.sliceProgress = sliceProgress;
+  }
+
+  get sliced(): boolean {
+    return this.sliceProgress >= this.sliceDifficulty;
+  }
+
+  override interact(_world: World, actor: Entity): InteractResult {
+    if (this.sliced) {
+      return { ok: false, reason: 'already-sliced', message: `${this.label}: already sliced.` };
+    }
+    const check = this.canInteract(actor);
+    if (!check.ok) {
+      return { ok: false, reason: check.reason, message: `${this.label}: ${check.reason}.` };
+    }
+    if ((actor as { isCyberAvatar?: boolean }).isCyberAvatar !== true) {
+      return {
+        ok: false,
+        reason: 'not-an-avatar',
+        message: `${this.label}: only the avatar can slice.`,
+      };
+    }
+    actor.spendAp(AP_COST.INTERACT);
+    // The sniff above guarantees a CyberAvatar, which validates the stat.
+    this.sliceProgress += (actor as unknown as { intrusionStrength: number }).intrusionStrength;
+    if (this.sliced) {
+      this.secured = true;
+      this.armed = false;
+      return { ok: true, message: `${this.label} sliced.` };
+    }
+    return {
+      ok: true,
+      message: `${this.label}: intrusion ${this.sliceProgress}/${this.sliceDifficulty}.`,
+    };
+  }
+}
diff --git a/src/game/objectiveProgress.ts b/src/game/objectiveProgress.ts
index 2f2d377..6b034d8 100644
--- a/src/game/objectiveProgress.ts
+++ b/src/game/objectiveProgress.ts
@@ -7,6 +7,7 @@ import { Hostile } from './Hostile.js';
 import { CorpTurret } from './entities/CorpTurret.js';
 import { RelayNode } from './entities/RelayNode.js';
 import { EscortNpc } from './entities/EscortNpc.js';
+import { DataNode } from './cyber/DataNode.js';
 import { OBJECTIVES } from './hub/Curator.js';
 import { coordKey, explorationReachableKeys } from './mapConnectivity.js';
 import type { Contract } from './hub/Curator.js';
@@ -30,6 +31,16 @@ export type SweepProgress = {
   total: number;
 };
 
+/**
+ * P3.M3.4: data-node tally for the `data-node-slice` objective. `Run` derives
+ * it per cyberspace phase (live count while active, the latch once resolved)
+ * and threads it into both satisfaction and the HUD chip.
+ */
+export type CyberNodeProgress = {
+  sliced: number;
+  required: number;
+};
+
 export const SWEEP_QUOTA = Object.freeze({
   HOSTILE_ALL: 'hostile-all',
   /** @deprecated Legacy save alias for HOSTILE_ALL. New contracts emit hostile-all. */
@@ -120,14 +131,32 @@ export function reconObjectiveProgress(
   return { mapped, required: eligible.size };
 }
 
+/** Count sliced vs. total data nodes in a (cyber) world. */
+export function dataNodeProgress(world: World | null | undefined): {
+  sliced: number;
+  total: number;
+} {
+  if (!world) return { sliced: 0, total: 0 };
+  let sliced = 0;
+  let total = 0;
+  for (const entity of world.entities.values()) {
+    if (!(entity instanceof DataNode)) continue;
+    total++;
+    if (entity.sliced) sliced++;
+  }
+  return { sliced, total };
+}
+
 /**
- * Progress tally for objectives that expose a fractional meter (recon, sweep).
- * Returns `null` when the contract kind has no meter or `total` is zero.
+ * Progress tally for objectives that expose a fractional meter (recon, sweep,
+ * data-node slice). Returns `null` when the contract kind has no meter or
+ * `total` is zero.
  */
 export function objectiveProgress(
   contract: Contract,
   world: World | null | undefined,
-  mapSeen: ReadonlySet<string> | readonly string[] = []
+  mapSeen: ReadonlySet<string> | readonly string[] = [],
+  cyber: CyberNodeProgress | null = null
 ): ObjectiveProgress | null {
   switch (contract.objective.kind) {
     case OBJECTIVES.RECON: {
@@ -140,6 +169,10 @@ export function objectiveProgress(
       if (total <= 0) return null;
       return { label: 'SWEEP', current: cleared, total };
     }
+    case OBJECTIVES.DATA_NODE_SLICE: {
+      if (!cyber || cyber.required <= 0) return null;
+      return { label: 'NODES', current: cyber.sliced, total: cyber.required };
+    }
     default:
       return null;
   }
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index 58fd76a..2e1ece1 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -79,6 +79,8 @@ import { BreachingCharge } from './entities/BreachingCharge.js';
 import type { BreachingChargeInit } from './entities/BreachingCharge.js';
 import type { CyberAvatarInit, CyberAvatarSnapshot } from './cyber/CyberAvatar.js';
 import type { EntryPortInit, EntryPortSnapshot } from './cyber/EntryPort.js';
+import { DataNode } from './cyber/DataNode.js';
+import type { DataNodeInit, DataNodeSnapshot } from './cyber/DataNode.js';
 import type { DeckerInit, DeckerSnapshot } from './archetypes/Decker.js';
 import { Run, RUN_STATE, PATROL_ARCHETYPE_IDS } from './Run.js';
 import { Campaign, CAMPAIGN_STATE, normalizeCampaignArc } from './Campaign.js';
@@ -179,6 +181,7 @@ type RestoreEntityProps = Partial<
     JackInPointInit &
     CyberAvatarInit &
     EntryPortInit &
+    DataNodeInit &
     DeckerInit
 > & {
   id: string;
@@ -225,6 +228,7 @@ const ARCHETYPE_FACTORY: Record<EntityArchetypeId, (props: RestoreEntityProps) =
     'jack-in-point': (props: RestoreEntityProps) => new JackInPoint(props as JackInPointInit),
     'cyber-avatar': (props: RestoreEntityProps) => new CyberAvatar(props as CyberAvatarInit),
     'entry-port': (props: RestoreEntityProps) => new EntryPort(props as EntryPortInit),
+    'data-node': (props: RestoreEntityProps) => new DataNode(props as DataNodeInit),
     'breaching-charge': (props: RestoreEntityProps) =>
       new BreachingCharge(props as BreachingChargeInit),
     // Generic fallback so a future `Entity` subclass (NPCs, items) doesn't break
@@ -371,6 +375,24 @@ function readJackInPoint(extra: EntitySnapshotExtra, id: string): JackInPointSna
   };
 }
 
+function readDataNode(extra: EntitySnapshotExtra, id: string): DataNodeSnapshot {
+  if (hasNoState(extra)) {
+    throw new TypeError(`restore: data node entity ${id} requires slice state`);
+  }
+  const n = extra as Partial<DataNodeSnapshot>;
+  if (!Number.isInteger(n.sliceDifficulty) || (n.sliceDifficulty as number) <= 0) {
+    throw new TypeError(`restore: data node ${id} sliceDifficulty must be a positive integer`);
+  }
+  if (!Number.isInteger(n.sliceProgress) || (n.sliceProgress as number) < 0) {
+    throw new TypeError(`restore: data node ${id} sliceProgress must be a non-negative integer`);
+  }
+  return {
+    label: requireString(n.label, `restore: data node ${id} label must be a non-empty string`),
+    sliceDifficulty: n.sliceDifficulty as number,
+    sliceProgress: n.sliceProgress as number,
+  };
+}
+
 function readCyberAvatar(extra: EntitySnapshotExtra, id: string): CyberAvatarSnapshot {
   if (hasNoState(extra)) {
     throw new TypeError(`restore: cyber avatar entity ${id} requires avatar state`);
@@ -645,6 +667,16 @@ const ENTITY_RESTORE: Partial<Record<EntityArchetypeId, RestoreEntry>> = Object.
       }
     },
   },
+  'data-node': {
+    buildProps(extra, rec) {
+      return readDataNode(extra, rec.id);
+    },
+    apply(entity, _extra, rec) {
+      if (!(entity instanceof DataNode)) {
+        throw new Error(`restore: data node entity ${rec.id} did not restore as DataNode`);
+      }
+    },
+  },
   tech: {
     // Re-apply the pre-built turret flag (default `true` from the Tech ctor when
     // a legacy record omits it — preserve that by only assigning when present).
@@ -1229,8 +1261,10 @@ function restoreCyberspaceLayer(
 
   let avatar: CyberAvatar | null = null;
   let port: EntryPort | null = null;
+  let dataNodes = 0;
   for (const rec of block.entities) {
     const entity = restoreEntity(rec, grid);
+    if (entity instanceof DataNode) dataNodes++;
     if (entity instanceof CyberAvatar) {
       if (avatar) {
         throw new Error('restore: active cyberspace block has multiple cyber-avatar entities');
@@ -1257,6 +1291,19 @@ function restoreCyberspaceLayer(
   if (!port) {
     throw new Error('restore: active cyberspace block has no entry-port');
   }
+  // P3.M3.4: nodes never despawn (sliced nodes stay in the world), so the
+  // entity count must equal the contract objective's count exactly.
+  const requiredNodes = (record.contract?.objective?.params as { count?: unknown } | undefined)
+    ?.count;
+  if (!Number.isInteger(requiredNodes) || (requiredNodes as number) <= 0) {
+    throw new TypeError('restore: cyber contract objective count must be a positive integer');
+  }
+  if (dataNodes !== requiredNodes) {
+    throw new Error(
+      `restore: active cyberspace block has ${dataNodes} data-node entities, ` +
+        `contract requires ${requiredNodes}`
+    );
+  }
 
   const layer = new CyberspaceLayer({ bus, world, avatar, port, entryTile });
   layer.recordSeen(block.mapMemory.seen);
diff --git a/tests/unit/game/cyber/CyberspaceLayer.test.ts b/tests/unit/game/cyber/CyberspaceLayer.test.ts
index 988b728..f97a87c 100644
--- a/tests/unit/game/cyber/CyberspaceLayer.test.ts
+++ b/tests/unit/game/cyber/CyberspaceLayer.test.ts
@@ -28,7 +28,8 @@ const makeDecker = (overrides = {}) =>
   new Decker({ id: 'crew-decker', x: 0, y: 0, callsign: 'Phreak', ...overrides });
 
 const buildLayer = (contractSeed = 12345, decker = makeDecker(), difficulty = 'standard') =>
-  CyberspaceLayer.build({ contractSeed, difficulty, decker });
+  // nodeCount 1 matches the `cyber-data-spike` recipe (P3.M3.4).
+  CyberspaceLayer.build({ contractSeed, difficulty, decker, nodeCount: 1 });
 
 // --- Decker cyber stats ------------------------------------------------------
 
@@ -69,12 +70,12 @@ test('build spawns the avatar at the entry tile with stats from the Decker', ()
   assert.equal(avatar.baseHitChance, CYBER_AVATAR_HIT_CHANCE);
 });
 
-test('the cyber world contains exactly the avatar and the exit port', () => {
+test('the cyber world contains exactly the avatar, the exit port, and the nodes', () => {
   const layer = buildLayer();
   const entities = Array.from(layer.world.entities.values());
   assert.equal(entities.filter(e => e instanceof CyberAvatar).length, 1);
   assert.equal(entities.filter(e => e instanceof EntryPort).length, 1);
-  assert.equal(entities.length, 2);
+  assert.equal(entities.length, 3, 'avatar + port + the contract data node (P3.M3.4)');
   const cheb = Math.max(
     Math.abs(layer.port.x - layer.avatar.x),
     Math.abs(layer.port.y - layer.avatar.y)
diff --git a/tests/unit/game/cyber/dataNode.test.ts b/tests/unit/game/cyber/dataNode.test.ts
new file mode 100644
index 0000000..ea18e04
--- /dev/null
+++ b/tests/unit/game/cyber/dataNode.test.ts
@@ -0,0 +1,171 @@
+/**
+ * P3.M3.4 — DataNode: the slice target on the cyber grid.
+ *
+ * Interact accumulates the actor's `intrusionStrength` toward
+ * `sliceDifficulty` (scope decision #4: named stats with real effects).
+ * Only the avatar can slice (capability sniff on `isCyberAvatar`); the
+ * threshold scales with contract difficulty.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { DataNode, sliceDifficultyFor } from '../../../../src/game/cyber/DataNode.js';
+import { CyberAvatar } from '../../../../src/game/cyber/CyberAvatar.js';
+import { Grid } from '../../../../src/game/Grid.js';
+import { World } from '../../../../src/game/World.js';
+import { buildCrewMember } from '../../../../src/game/archetypes/index.js';
+import { AP_COST } from '../../../../src/game/constants.js';
+import { Rng } from '../../../../src/rng.js';
+
+function makeWorld() {
+  return new World(new Grid(7, 7));
+}
+
+function makeAvatar(x = 1, y = 1, intrusionStrength = 2) {
+  return new CyberAvatar({
+    id: 'cyber-avatar-0',
+    x,
+    y,
+    ram: 8,
+    intrusionStrength,
+    iceResistance: 1,
+  });
+}
+
+function makeNode(sliceDifficulty = 3, overrides = {}) {
+  return new DataNode({ id: 'data-node-0', x: 2, y: 1, sliceDifficulty, ...overrides });
+}
+
+// --- difficulty table ---------------------------------------------------------------
+
+test('sliceDifficultyFor maps contract difficulty to the slice threshold', () => {
+  assert.equal(sliceDifficultyFor('standard'), 2);
+  assert.equal(sliceDifficultyFor('elevated'), 3);
+  assert.equal(sliceDifficultyFor('critical'), 4);
+});
+
+test('sliceDifficultyFor throws on an unknown difficulty', () => {
+  assert.throws(() => sliceDifficultyFor('apocalyptic' as never), /difficulty/);
+});
+
+// --- construction ---------------------------------------------------------------------
+
+test('ctor validates sliceDifficulty and sliceProgress', () => {
+  assert.throws(() => makeNode(0), /sliceDifficulty/);
+  assert.throws(() => makeNode(-2), /sliceDifficulty/);
+  assert.throws(() => makeNode(1.5), /sliceDifficulty/);
+  // An absent threshold must throw, not default (no silent fallback).
+  assert.throws(
+    () =>
+      new DataNode({
+        id: 'data-node-0',
+        x: 2,
+        y: 1,
+        sliceDifficulty: undefined as unknown as number,
+      }),
+    /sliceDifficulty/
+  );
+  assert.throws(() => makeNode(3, { sliceProgress: -1 }), /sliceProgress/);
+  assert.throws(() => makeNode(3, { sliceProgress: 0.5 }), /sliceProgress/);
+});
+
+test('a fresh node starts unsliced and armed', () => {
+  const node = makeNode(3);
+  assert.equal(node.sliceProgress, 0);
+  assert.equal(node.sliced, false);
+  assert.equal(node.secured, false);
+  assert.equal(node.armed, true);
+});
+
+test('a node restored at threshold is sliced and secured', () => {
+  const node = makeNode(3, { sliceProgress: 4 });
+  assert.equal(node.sliced, true);
+  assert.equal(node.secured, true);
+  assert.equal(node.armed, false);
+});
+
+// --- interact -------------------------------------------------------------------------
+
+test('avatar interact debits AP and adds intrusionStrength to progress', () => {
+  const world = makeWorld();
+  const avatar = makeAvatar();
+  const node = makeNode(3);
+  world.addEntity(avatar);
+  world.addEntity(node);
+
+  const result = node.interact(world, avatar);
+  assert.equal(result.ok, true);
+  assert.equal(avatar.ap, avatar.maxAp - AP_COST.INTERACT);
+  assert.equal(node.sliceProgress, 2);
+  assert.equal(node.sliced, false, 'below threshold stays unsliced');
+  assert.match(result.message, /2\s*\/\s*3/, 'message reports intrusion progress');
+});
+
+test('reaching the threshold slices the node', () => {
+  const world = makeWorld();
+  const avatar = makeAvatar();
+  const node = makeNode(3);
+  world.addEntity(avatar);
+  world.addEntity(node);
+
+  node.interact(world, avatar);
+  const result = node.interact(world, avatar);
+  assert.equal(result.ok, true);
+  assert.equal(node.sliceProgress, 4, 'progress is raw, not clamped');
+  assert.equal(node.sliced, true);
+  assert.equal(node.secured, true);
+  assert.equal(node.armed, false);
+  assert.match(result.message, /sliced/i);
+});
+
+test('an already-sliced node refuses without burning AP', () => {
+  const world = makeWorld();
+  const avatar = makeAvatar(1, 1, 4);
+  const node = makeNode(3);
+  world.addEntity(avatar);
+  world.addEntity(node);
+
+  assert.equal(node.interact(world, avatar).ok, true);
+  assert.equal(node.sliced, true);
+  const apBefore = avatar.ap;
+  const repeat = node.interact(world, avatar);
+  assert.equal(repeat.ok, false);
+  assert.equal((repeat as { reason: string }).reason, 'already-sliced');
+  assert.equal(avatar.ap, apBefore);
+});
+
+test('a non-avatar is refused without burning AP — even a Decker', () => {
+  const world = makeWorld();
+  // The Decker carries intrusionStrength too — the sniff must be the
+  // isCyberAvatar capability flag, not the stat.
+  const decker = buildCrewMember('decker', { x: 1, y: 1 }, new Rng(7), { id: 'crew-decker' });
+  const node = makeNode(3);
+  world.addEntity(decker);
+  world.addEntity(node);
+  decker.refreshAp();
+
+  const apBefore = decker.ap;
+  const result = node.interact(world, decker);
+  assert.equal(result.ok, false);
+  assert.equal((result as { reason: string }).reason, 'not-an-avatar');
+  assert.equal(decker.ap, apBefore);
+  assert.equal(node.sliceProgress, 0);
+});
+
+test('standard adjacency and AP gates apply', () => {
+  const world = makeWorld();
+  const far = makeAvatar(5, 5);
+  const node = makeNode(3);
+  world.addEntity(far);
+  world.addEntity(node);
+
+  const notAdjacent = node.interact(world, far);
+  assert.equal(notAdjacent.ok, false);
+  assert.equal((notAdjacent as { reason: string }).reason, 'not-adjacent');
+
+  const broke = makeAvatar(2, 2);
+  broke.spendAp(broke.ap);
+  const noAp = node.interact(world, broke);
+  assert.equal(noAp.ok, false);
+  assert.equal((noAp as { reason: string }).reason, 'insufficient-ap');
+});
diff --git a/tests/unit/game/cyber/dataNodeObjective.test.ts b/tests/unit/game/cyber/dataNodeObjective.test.ts
new file mode 100644
index 0000000..da8464b
--- /dev/null
+++ b/tests/unit/game/cyber/dataNodeObjective.test.ts
@@ -0,0 +1,308 @@
+/**
+ * P3.M3.4 — the data-node-slice objective wired through the Run.
+ *
+ * `CyberspaceLayer.build` spawns the contract's `count` nodes on the far
+ * node tiles; satisfaction counts sliced nodes (active), the resolved latch
+ * (jacked out), or zero (dormant). Jack-out before slicing leaves the
+ * objective permanently unsatisfiable — extraction stays gated through the
+ * existing abort-confirm flow. Node slice progress round-trips persistence.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { Run } from '../../../../src/game/Run.js';
+import { CyberspaceLayer } from '../../../../src/game/cyber/CyberspaceLayer.js';
+import { DataNode, sliceDifficultyFor } from '../../../../src/game/cyber/DataNode.js';
+import { JackInPoint } from '../../../../src/game/entities/JackInPoint.js';
+import { snapshot, restore } from '../../../../src/game/persistence.js';
+import { buildCrewMember } from '../../../../src/game/archetypes/index.js';
+import { OBJECTIVES } from '../../../../src/game/hub/Curator.js';
+import { Rng } from '../../../../src/rng.js';
+import { testContractContext } from '../contractTestUtils.js';
+import type { World } from '../../../../src/game/World.js';
+import type { Entity } from '../../../../src/game/Entity.js';
+import type { RunEntitySnapshot, RunSnapshot } from '../../../../src/game/Run.js';
+import type { ContractDifficulty } from '../../../../src/game/constants.js';
+
+const cyberContract = (seed = 12345, difficulty: ContractDifficulty = 'standard', count = 1) => ({
+  seed,
+  objective: {
+    kind: OBJECTIVES.DATA_NODE_SLICE,
+    title: 'Spike the server farm',
+    briefing: 'Jack in, slice the data node, then extract.',
+    params: { requiresCyberspace: true, count },
+  },
+  difficulty,
+  threatCount: 1,
+  label: 'cyber test job',
+  context: testContractContext(OBJECTIVES.DATA_NODE_SLICE),
+  reward: { credits: 0, repDelta: 0 },
+});
+
+function makeDecker() {
+  return buildCrewMember('decker', { x: 0, y: 0 }, new Rng(100), { id: 'crew-decker' });
+}
+
+function adjacentFreeTile(world: World, target: Entity) {
+  for (let dy = -1; dy <= 1; dy++) {
+    for (let dx = -1; dx <= 1; dx++) {
+      if (dx === 0 && dy === 0) continue;
+      const x = target.x + dx;
+      const y = target.y + dy;
+      if (world.grid.inBounds(x, y) && world.grid.isPassable(x, y) && !world.entityAt(x, y)) {
+        return { x, y };
+      }
+    }
+  }
+  throw new Error(`no free tile adjacent to ${target.id}`);
+}
+
+function combatRun(seed = 12345, difficulty: ContractDifficulty = 'standard', count = 1) {
+  const run = new Run({ crewMember: makeDecker(), seed });
+  run.enterBriefing(cyberContract(seed, difficulty, count));
+  run.enterCombat();
+  return run;
+}
+
+function jackIn(run: Run): CyberspaceLayer {
+  const point = Array.from(run.world!.entities.values()).find(
+    e => e instanceof JackInPoint
+  ) as JackInPoint;
+  assert.ok(point, 'cyber contract placed a jack-in point');
+  const spot = adjacentFreeTile(run.world!, point);
+  run.world!.relocateEntity(run.player!, spot.x, spot.y);
+  run.player!.refreshAp();
+  assert.equal(point.interact(run.world!, run.player!).ok, true);
+  assert.equal(run.cyberspace?.phase, 'active');
+  return (run.cyberspace as { phase: 'active'; layer: CyberspaceLayer }).layer;
+}
+
+function layerNodes(layer: CyberspaceLayer): DataNode[] {
+  return Array.from(layer.world.entities.values()).filter(
+    (e): e is DataNode => e instanceof DataNode
+  );
+}
+
+/** Walk the avatar adjacent to `node` and interact until it slices. */
+function sliceNode(layer: CyberspaceLayer, node: DataNode): void {
+  while (!node.sliced) {
+    const spot = adjacentFreeTile(layer.world, node);
+    layer.world.relocateEntity(layer.avatar, spot.x, spot.y);
+    layer.avatar.refreshAp();
+    const result = node.interact(layer.world, layer.avatar);
+    assert.equal(result.ok, true, `slice attempt failed: ${result.message}`);
+  }
+}
+
+/** Walk the avatar back to the exit port and route out. */
+function routeOut(layer: CyberspaceLayer): void {
+  const spot = adjacentFreeTile(layer.world, layer.port);
+  layer.world.relocateEntity(layer.avatar, spot.x, spot.y);
+  layer.avatar.refreshAp();
+  const result = layer.port.interact(layer.world, layer.avatar);
+  assert.equal(result.ok, true, `jack-out failed: ${result.message}`);
+}
+
+function cyberEntities(record: RunSnapshot): RunEntitySnapshot[] {
+  const block = record.cyberspace as unknown as Record<string, unknown>;
+  return block.entities as RunEntitySnapshot[];
+}
+
+// --- node spawning ------------------------------------------------------------------
+
+test('build spawns the contract count of data nodes with the difficulty threshold', () => {
+  const layer = jackIn(combatRun(4242, 'standard', 1));
+  const nodes = layerNodes(layer);
+  assert.equal(nodes.length, 1);
+  assert.equal(nodes[0].sliceDifficulty, sliceDifficultyFor('standard'));
+  assert.equal(nodes[0].sliced, false);
+  // The node spawned on a passable tile away from the entry point.
+  assert.ok(layer.world.grid.isPassable(nodes[0].x, nodes[0].y));
+  const cheb = Math.max(
+    Math.abs(nodes[0].x - layer.entryTile.x),
+    Math.abs(nodes[0].y - layer.entryTile.y)
+  );
+  assert.ok(cheb > 1, 'node does not crowd the entry tile');
+});
+
+test('multi-node contracts spawn distinct nodes on distinct tiles', () => {
+  const layer = jackIn(combatRun(4242, 'critical', 3));
+  const nodes = layerNodes(layer);
+  assert.equal(nodes.length, 3);
+  const tiles = new Set(nodes.map(n => `${n.x},${n.y}`));
+  assert.equal(tiles.size, 3);
+  const ids = new Set(nodes.map(n => n.id));
+  assert.equal(ids.size, 3);
+  for (const node of nodes) {
+    assert.equal(node.sliceDifficulty, sliceDifficultyFor('critical'));
+  }
+});
+
+test('node placement is deterministic per contract seed', () => {
+  const a = layerNodes(jackIn(combatRun(909, 'elevated', 2)));
+  const b = layerNodes(jackIn(combatRun(909, 'elevated', 2)));
+  assert.deepEqual(
+    a.map(n => ({ id: n.id, x: n.x, y: n.y })),
+    b.map(n => ({ id: n.id, x: n.x, y: n.y }))
+  );
+});
+
+test('a node count beyond the map anchors throws at build', () => {
+  assert.throws(
+    () =>
+      CyberspaceLayer.build({
+        contractSeed: 1,
+        difficulty: 'standard',
+        decker: makeDecker(),
+        nodeCount: 99,
+      }),
+    /nodeCount|node tiles/
+  );
+});
+
+// --- satisfaction --------------------------------------------------------------------
+
+test('dormant: objective unsatisfied, extraction gated, chip shows 0 of count', () => {
+  const run = combatRun();
+  assert.equal(run.cyberspace?.phase, 'dormant');
+  assert.equal(run.isObjectiveSatisfied(), false);
+  assert.equal(run.canExtract(), false);
+  assert.deepEqual(run.objectiveProgress(), { label: 'NODES', current: 0, total: 1 });
+});
+
+test('active: slicing the node satisfies the objective and fills the chip', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  assert.equal(run.isObjectiveSatisfied(), false);
+  assert.deepEqual(run.objectiveProgress(), { label: 'NODES', current: 0, total: 1 });
+
+  sliceNode(layer, layerNodes(layer)[0]);
+  assert.equal(run.isObjectiveSatisfied(), true);
+  assert.equal(run.canExtract(), true);
+  assert.deepEqual(run.objectiveProgress(), { label: 'NODES', current: 1, total: 1 });
+});
+
+test('multi-node: every node must slice', () => {
+  const run = combatRun(4242, 'critical', 3);
+  const layer = jackIn(run);
+  const nodes = layerNodes(layer);
+  sliceNode(layer, nodes[0]);
+  assert.equal(run.isObjectiveSatisfied(), false);
+  assert.deepEqual(run.objectiveProgress(), { label: 'NODES', current: 1, total: 3 });
+  sliceNode(layer, nodes[1]);
+  sliceNode(layer, nodes[2]);
+  assert.equal(run.isObjectiveSatisfied(), true);
+});
+
+test('jack-out after slicing latches objectiveComplete: true', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  sliceNode(layer, layerNodes(layer)[0]);
+  routeOut(layer);
+  assert.deepEqual(run.cyberspace, { phase: 'resolved', objectiveComplete: true });
+  assert.equal(run.isObjectiveSatisfied(), true);
+  assert.equal(run.canExtract(), true);
+});
+
+test('jack-out before slicing latches false — permanently unsatisfiable', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  assert.equal(layer.port.interact(layer.world, layer.avatar).ok, true);
+  assert.deepEqual(run.cyberspace, { phase: 'resolved', objectiveComplete: false });
+  assert.equal(run.isObjectiveSatisfied(), false);
+  assert.equal(run.canExtract(), false, 'clean extraction stays gated (abort flow)');
+  assert.deepEqual(run.objectiveProgress(), { label: 'NODES', current: 0, total: 1 });
+});
+
+// --- persistence ---------------------------------------------------------------------
+
+test('mid-slice progress round-trips and finishes after restore', () => {
+  const run = combatRun(777, 'elevated', 1); // threshold 3, base intrusion 2
+  const layer = jackIn(run);
+  const node = layerNodes(layer)[0];
+  const spot = adjacentFreeTile(layer.world, node);
+  layer.world.relocateEntity(layer.avatar, spot.x, spot.y);
+  layer.avatar.refreshAp();
+  assert.equal(node.interact(layer.world, layer.avatar).ok, true);
+  assert.equal(node.sliceProgress, 2);
+  assert.equal(node.sliced, false);
+
+  const record = structuredClone(snapshot(run));
+  const { run: restored } = restore(record);
+  assert.equal(restored.cyberspace?.phase, 'active');
+  const restoredLayer = (restored.cyberspace as { phase: 'active'; layer: CyberspaceLayer }).layer;
+  const restoredNode = layerNodes(restoredLayer)[0];
+  assert.equal(restoredNode.sliceProgress, 2);
+  assert.equal(restoredNode.sliceDifficulty, 3);
+  assert.equal(restoredNode.sliced, false);
+  assert.equal(restored.isObjectiveSatisfied(), false);
+
+  sliceNode(restoredLayer, restoredNode);
+  assert.equal(restored.isObjectiveSatisfied(), true);
+});
+
+test('a sliced node round-trips as sliced', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  sliceNode(layer, layerNodes(layer)[0]);
+
+  const { run: restored } = restore(structuredClone(snapshot(run)));
+  const restoredLayer = (restored.cyberspace as { phase: 'active'; layer: CyberspaceLayer }).layer;
+  assert.equal(layerNodes(restoredLayer)[0].sliced, true);
+  assert.equal(restored.isObjectiveSatisfied(), true);
+});
+
+test('the resolved latch round-trips satisfaction both ways', () => {
+  for (const complete of [true, false]) {
+    const run = combatRun();
+    const layer = jackIn(run);
+    if (complete) sliceNode(layer, layerNodes(layer)[0]);
+    routeOut(layer);
+
+    const { run: restored } = restore(structuredClone(snapshot(run)));
+    assert.deepEqual(restored.cyberspace, { phase: 'resolved', objectiveComplete: complete });
+    assert.equal(restored.isObjectiveSatisfied(), complete);
+  }
+});
+
+// --- adversarial restore --------------------------------------------------------------
+
+test('an active block missing its data nodes throws', () => {
+  const run = combatRun();
+  jackIn(run);
+  const record = structuredClone(snapshot(run));
+  const block = record.cyberspace as unknown as Record<string, unknown>;
+  block.entities = cyberEntities(record).filter(e => e.archetype !== 'data-node');
+  assert.throws(() => restore(record), /data.node/i);
+});
+
+test('a node-count mismatch against the contract throws', () => {
+  const run = combatRun();
+  jackIn(run);
+  const record = structuredClone(snapshot(run));
+  const block = record.cyberspace as unknown as Record<string, unknown>;
+  const node = cyberEntities(record).find(e => e.archetype === 'data-node')!;
+  const clone = structuredClone(node);
+  clone.id = 'data-node-rogue';
+  clone.x = node.x + 1;
+  (block.entities as RunEntitySnapshot[]).push(clone);
+  assert.throws(() => restore(record), /data.node/i);
+});
+
+test('malformed node extras throw', () => {
+  const base = () => {
+    const run = combatRun();
+    jackIn(run);
+    return structuredClone(snapshot(run));
+  };
+
+  const missingDifficulty = base();
+  const node1 = cyberEntities(missingDifficulty).find(e => e.archetype === 'data-node')!;
+  delete (node1.extra as Record<string, unknown>).sliceDifficulty;
+  assert.throws(() => restore(missingDifficulty), /sliceDifficulty/);
+
+  const negativeProgress = base();
+  const node2 = cyberEntities(negativeProgress).find(e => e.archetype === 'data-node')!;
+  (node2.extra as Record<string, unknown>).sliceProgress = -1;
+  assert.throws(() => restore(negativeProgress), /sliceProgress/);
+});
diff --git a/tests/unit/game/cyber/runJackIn.test.ts b/tests/unit/game/cyber/runJackIn.test.ts
index d92b752..daf11f2 100644
--- a/tests/unit/game/cyber/runJackIn.test.ts
+++ b/tests/unit/game/cyber/runJackIn.test.ts
@@ -142,6 +142,7 @@ test('layer layout is independent of the jack-in turn', () => {
     contractSeed: 777,
     difficulty: 'standard',
     decker: makeDecker(),
+    nodeCount: 1,
   });
   assert.deepEqual(Array.from(fresh.world.grid.tiles), Array.from(immediate.world.grid.tiles));
 });

From 0489345a816a26ea8c2d44e6fa544c8906d9aab6 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Wed, 10 Jun 2026 14:15:03 -0700
Subject: [PATCH 20/55] =?UTF-8?q?P3.M3=20plan:=20S4=20shipped=20=E2=80=94?=
 =?UTF-8?q?=20progress=20row=20+=20implementation=20notes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/phase-3-cyberspace-plan.md | 42 ++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/docs/phase-3-cyberspace-plan.md b/docs/phase-3-cyberspace-plan.md
index b03c2ba..0f9f3b7 100644
--- a/docs/phase-3-cyberspace-plan.md
+++ b/docs/phase-3-cyberspace-plan.md
@@ -32,7 +32,7 @@ Commits land **per green slice** (user-approved).
 | **S1 — P3.M3.1 Contract flag + gates** | ✅ Done | `f436330` |
 | **S2 — P3.M3.2 Jack-in terminal** | ✅ Done | `05013f6` |
 | **S3 — P3.M3.3 Cyber layer model + avatar + persistence** | ✅ Done | `39b357e` |
-| **S4 — P3.M3.4 Data node objective** | 🔲 Planned | — |
+| **S4 — P3.M3.4 Data node objective** | ✅ Done | `3923149` |
 | **S5 — Voluntary jack-out (M4.6 pull-forward)** | 🔲 Planned | — |
 | **S6 — P3.M3.5 Probe ICE** | 🔲 Planned | — |
 | **S7 — P3.M3.6 Render/input swap + shell ICE phase** | 🔲 Planned | — |
@@ -160,6 +160,46 @@ Commits land **per green slice** (user-approved).
 - Playtest note (pre-S7): jack-in flips state internally but the shell still
   renders Meatspace until the S7 render/input swap — expected, not a bug.
 
+### S4 implementation notes (shipped)
+
+- `src/game/cyber/DataNode.ts` — `DataNode extends Interactable`, glyph `◈`
+  (`DATA_NODE_GLYPH`). Interact: sliced → `already-sliced` refusal; standard
+  adjacency/AP gates; **avatar-only via the `isCyberAvatar` sniff** (same S3
+  deviation rationale — the Decker body carries `intrusionStrength` too);
+  success spends interact AP and adds the avatar's `intrusionStrength` to
+  `sliceProgress`. Sliced at `sliceDifficulty` — `sliceDifficultyFor`:
+  standard 2 / elevated 3 / critical 4 (unknown throws). Progress is **raw,
+  never clamped**, so persistence loses nothing. Slicing is silent — the
+  cyber alarm belongs to ICE detection (S6), not the slice.
+- `CyberspaceLayer.build` gains **required `nodeCount`** (no default — a
+  count silently diverging from the contract would corrupt the objective;
+  `Run.jackIn` passes the objective's `count`). Nodes spawn on the
+  *farthest* node anchors from entry (Chebyshev sort, stable over generator
+  order → placement is a pure function of the contract seed);
+  `nodeCount > nodeTiles.length` throws.
+- `Run` — `ObjectiveState.cyber?: {sliced, required}` computed per phase by
+  `#cyberNodeProgress()`: live `dataNodeProgress(layer.world)` while active,
+  the resolved latch (`required`/0), zero while dormant, `undefined` on
+  non-cyber contracts. `DATA_NODE_SLICE` satisfaction: `sliced >= required`
+  (absent tally → honestly unsatisfiable). `jackOut()` latches
+  `objectiveComplete` from the real tally — the S3 TODO is gone; early
+  jack-out latches `false`, leaving extraction gated through the existing
+  abort-confirm flow (zero new extraction code).
+- `objectiveProgress.ts` — `CyberNodeProgress` type, `dataNodeProgress(world)`
+  tally, optional 4th `cyber` param, `NODES` chip case. The HUD chip pipeline
+  is kind-generic — **no shell copy changes were needed** (the planned
+  describe/combatHud grep came up empty).
+- Persistence — `data-node` codec in both registries (`label` /
+  `sliceDifficulty` / `sliceProgress`, malformed or half-populated throws);
+  `restoreCyberspaceLayer` now requires the active block to carry **exactly
+  the contract's node count** (nodes never despawn, so any drift is
+  corruption).
+- Tests: 25 across `dataNode.test.ts` (10 — entity behavior, difficulty
+  table, refusal matrix) and `dataNodeObjective.test.ts` (15 — spawn
+  determinism, satisfaction per phase, both latch directions, mid-slice
+  round-trip, adversarial node-count/extra throws). Failing-first verified;
+  suite 1629 green.
+
 ## Architecture decisions (approved plan)
 
 ### Cyber layer model — `CyberspaceLayer` owned by `Run`, single `TurnQueue`, both worlds tick

From fab3bcb647a326887f45a9f8950b58ab98ad8977 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Wed, 10 Jun 2026 14:20:18 -0700
Subject: [PATCH 21/55] =?UTF-8?q?P3.M3=20S5:=20voluntary=20jack-out=20fina?=
 =?UTF-8?q?lized=20=E2=80=94=20LINK=20BURNED=20latch=20on=20the=20port?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The P3.M4.6 pull-forward (scope decision #2), completing what S3/S4
started (resolve latch, teardown, autosave, objective tally):

- JackInPoint gains the `burned` latch: `Run.jackOut()` burns the meat-side
  port when the avatar routes out, so re-jack-in is refused with dedicated
  flavor (`link-burned` / "LINK BURNED — the connection is dead") instead
  of the redundant-input 'already-linked'. `burn()` on an unlinked port
  throws (corrupt state), as does constructing one.
- Snapshot extra carries `burned`; pre-S5 records restore unburned (legacy
  normalization), non-boolean or burned-without-linked throws.
- Coverage audit of the planned S5 matrix: jackOut from dormant / on a
  non-cyber contract throws (new); resolved latching both ways, post-jack-
  out round-trip, and resolved-block smuggling were already locked by
  S3/S4 tests.

8 new tests (jackOut.test.ts; failing-first verified), suite at 1637 green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/game/Run.ts                         |  15 +-
 src/game/entities/JackInPoint.ts        |  34 ++++-
 src/game/persistence.ts                 |  15 +-
 tests/unit/game/cyber/jackOut.test.ts   | 186 ++++++++++++++++++++++++
 tests/unit/game/cyber/runJackIn.test.ts |   4 +-
 5 files changed, 249 insertions(+), 5 deletions(-)
 create mode 100644 tests/unit/game/cyber/jackOut.test.ts

diff --git a/src/game/Run.ts b/src/game/Run.ts
index be2aa82..7770ff0 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -897,11 +897,24 @@ export class Run {
     const objectiveComplete = sliced >= objectiveCount(this.contract);
     layer.teardown();
     this.cyberspace = { phase: 'resolved', objectiveComplete };
+    // S5: the link is burned — re-jack-in refused for the rest of the run.
+    this.#meatJackInPoint().burn();
     if (this.onPersist) {
       this.onPersist(this.snapshot());
     }
   }
 
+  /** The contract's single meat-side jack-in point. Missing on a cyber run is corrupt. */
+  #meatJackInPoint(): JackInPoint {
+    if (!this.world) {
+      throw new Error('Run.#meatJackInPoint: no live world');
+    }
+    for (const entity of this.world.entities.values()) {
+      if (entity instanceof JackInPoint) return entity;
+    }
+    throw new Error('Run.#meatJackInPoint: cyber contract has no jack-in point in the world');
+  }
+
   /**
    * Phase 2.9: the single hostile faction for this run, derived from the
    * contract principal's groups (rival-group → `RIVAL`, corp/civic → `CORP`).
@@ -2011,7 +2024,7 @@ const SNAPSHOT_EXTRACTORS: Partial<Record<EntityArchetypeId, (e: Entity) => Enti
     },
     'jack-in-point': e => {
       const p = e as JackInPoint;
-      return { label: p.label, linked: p.linked } satisfies JackInPointSnapshot;
+      return { label: p.label, linked: p.linked, burned: p.burned } satisfies JackInPointSnapshot;
     },
     'cyber-avatar': e => {
       const a = e as CyberAvatar;
diff --git a/src/game/entities/JackInPoint.ts b/src/game/entities/JackInPoint.ts
index f2db958..b78d4e7 100644
--- a/src/game/entities/JackInPoint.ts
+++ b/src/game/entities/JackInPoint.ts
@@ -20,18 +20,31 @@ import type { World } from '../World.js';
 export interface JackInPointInit extends Omit<InteractableInit, 'glyph' | 'label'> {
   label?: string;
   linked?: boolean;
+  burned?: boolean;
 }
 
 /** P2.7.M6.2: JackInPoint snapshot `extra`. */
 export type JackInPointSnapshot = {
   label: string;
   linked: boolean;
+  burned: boolean;
 };
 
 export class JackInPoint extends Interactable {
   linked: boolean;
+  /**
+   * P3.M3 S5: latched by `Run.jackOut()` once the avatar routes back out —
+   * the link is dead and re-jack-in is refused with burn flavor. A burned
+   * port is always a linked port (`burn()` enforces it).
+   */
+  burned: boolean;
 
-  constructor({ label = 'Jack-in port', linked = false, ...props }: JackInPointInit) {
+  constructor({
+    label = 'Jack-in port',
+    linked = false,
+    burned = false,
+    ...props
+  }: JackInPointInit) {
     super({
       ...props,
       glyph: JACK_IN_GLYPH,
@@ -39,10 +52,29 @@ export class JackInPoint extends Interactable {
       secured: linked,
       armed: !linked,
     });
+    if (burned && !linked) {
+      throw new Error(`JackInPoint ${props.id}: burned without linked is corrupt state`);
+    }
     this.linked = !!linked;
+    this.burned = !!burned;
+  }
+
+  /** Kill the link after jack-out. Burning an unlinked port is corrupt state. */
+  burn(): void {
+    if (!this.linked) {
+      throw new Error(`JackInPoint ${this.id}: cannot burn an unlinked port`);
+    }
+    this.burned = true;
   }
 
   override interact(world: World, actor: Entity): InteractResult {
+    if (this.burned) {
+      return {
+        ok: false,
+        reason: 'link-burned',
+        message: `${this.label}: LINK BURNED — the connection is dead.`,
+      };
+    }
     if (this.linked) {
       return { ok: false, reason: 'already-linked', message: `${this.label}: already linked.` };
     }
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index 2e1ece1..48385ba 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -369,9 +369,20 @@ function readJackInPoint(extra: EntitySnapshotExtra, id: string): JackInPointSna
     throw new TypeError(`restore: jack-in point entity ${id} requires jack-in state`);
   }
   const p = extra as Partial<JackInPointSnapshot>;
+  const linked = requireBoolean(p.linked, `restore: jack-in point ${id} linked must be boolean`);
+  // S5 added the burn latch; absent on pre-S5 records → unburned (legacy
+  // normalization). Present-but-malformed, or burned without linked, throws.
+  const burned =
+    p.burned === undefined
+      ? false
+      : requireBoolean(p.burned, `restore: jack-in point ${id} burned must be boolean`);
+  if (burned && !linked) {
+    throw new Error(`restore: jack-in point ${id} is burned but not linked — corrupt state`);
+  }
   return {
     label: requireString(p.label, `restore: jack-in point ${id} label must be a non-empty string`),
-    linked: requireBoolean(p.linked, `restore: jack-in point ${id} linked must be boolean`),
+    linked,
+    burned,
   };
 }
 
@@ -735,7 +746,7 @@ const ENTITY_RESTORE: Partial<Record<EntityArchetypeId, RestoreEntry>> = Object.
   'jack-in-point': {
     buildProps(extra, rec) {
       const p = readJackInPoint(extra, rec.id);
-      return { label: p.label, linked: p.linked };
+      return { label: p.label, linked: p.linked, burned: p.burned };
     },
     apply(entity, _extra, rec) {
       if (!(entity instanceof JackInPoint)) {
diff --git a/tests/unit/game/cyber/jackOut.test.ts b/tests/unit/game/cyber/jackOut.test.ts
new file mode 100644
index 0000000..8a5066f
--- /dev/null
+++ b/tests/unit/game/cyber/jackOut.test.ts
@@ -0,0 +1,186 @@
+/**
+ * P3.M3 S5 — voluntary jack-out finalization (P3.M4.6 pull-forward).
+ *
+ * The resolve core (latch, teardown, autosave) landed in S3/S4; this file
+ * covers the remaining matrix: illegal-phase throws and the LINK BURNED
+ * latch on the meat-side port — once the avatar routes out, the link is
+ * dead and re-jack-in is refused with burn flavor, across persistence.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { Run } from '../../../../src/game/Run.js';
+import { CyberspaceLayer } from '../../../../src/game/cyber/CyberspaceLayer.js';
+import { JackInPoint } from '../../../../src/game/entities/JackInPoint.js';
+import { snapshot, restore } from '../../../../src/game/persistence.js';
+import { buildCrewMember } from '../../../../src/game/archetypes/index.js';
+import { OBJECTIVES } from '../../../../src/game/hub/Curator.js';
+import { Rng } from '../../../../src/rng.js';
+import { testContractContext } from '../contractTestUtils.js';
+import type { World } from '../../../../src/game/World.js';
+import type { Entity } from '../../../../src/game/Entity.js';
+import type { RunEntitySnapshot, RunSnapshot } from '../../../../src/game/Run.js';
+
+const cyberContract = (seed = 12345) => ({
+  seed,
+  objective: {
+    kind: OBJECTIVES.DATA_NODE_SLICE,
+    title: 'Spike the server farm',
+    briefing: 'Jack in, slice the data node, then extract.',
+    params: { requiresCyberspace: true, count: 1 },
+  },
+  difficulty: 'standard',
+  threatCount: 1,
+  label: 'cyber test job',
+  context: testContractContext(OBJECTIVES.DATA_NODE_SLICE),
+  reward: { credits: 0, repDelta: 0 },
+});
+
+function makeDecker() {
+  return buildCrewMember('decker', { x: 0, y: 0 }, new Rng(100), { id: 'crew-decker' });
+}
+
+function adjacentFreeTile(world: World, target: Entity) {
+  for (let dy = -1; dy <= 1; dy++) {
+    for (let dx = -1; dx <= 1; dx++) {
+      if (dx === 0 && dy === 0) continue;
+      const x = target.x + dx;
+      const y = target.y + dy;
+      if (world.grid.inBounds(x, y) && world.grid.isPassable(x, y) && !world.entityAt(x, y)) {
+        return { x, y };
+      }
+    }
+  }
+  throw new Error(`no free tile adjacent to ${target.id}`);
+}
+
+function combatRun(seed = 12345) {
+  const run = new Run({ crewMember: makeDecker(), seed });
+  run.enterBriefing(cyberContract(seed));
+  run.enterCombat();
+  return run;
+}
+
+function meatPort(run: Run): JackInPoint {
+  const point = Array.from(run.world!.entities.values()).find(e => e instanceof JackInPoint);
+  assert.ok(point, 'cyber contract placed a jack-in point');
+  return point as JackInPoint;
+}
+
+function jackIn(run: Run): CyberspaceLayer {
+  const point = meatPort(run);
+  const spot = adjacentFreeTile(run.world!, point);
+  run.world!.relocateEntity(run.player!, spot.x, spot.y);
+  run.player!.refreshAp();
+  assert.equal(point.interact(run.world!, run.player!).ok, true);
+  return (run.cyberspace as { phase: 'active'; layer: CyberspaceLayer }).layer;
+}
+
+function routeOut(layer: CyberspaceLayer): void {
+  const spot = adjacentFreeTile(layer.world, layer.port);
+  layer.world.relocateEntity(layer.avatar, spot.x, spot.y);
+  layer.avatar.refreshAp();
+  assert.equal(layer.port.interact(layer.world, layer.avatar).ok, true);
+}
+
+function portRecord(record: RunSnapshot): RunEntitySnapshot {
+  const rec = record.entities.find(e => e.archetype === 'jack-in-point');
+  assert.ok(rec, 'snapshot carries the jack-in point');
+  return rec!;
+}
+
+// --- illegal phases -----------------------------------------------------------------
+
+test('jackOut while dormant throws (no layer to resolve)', () => {
+  const run = combatRun();
+  assert.equal(run.cyberspace?.phase, 'dormant');
+  assert.throws(() => run.jackOut(), /phase/);
+});
+
+test('jackOut on a non-cyber contract throws', () => {
+  const run = new Run({ crewMember: makeDecker(), seed: 999 });
+  run.enterBriefing({
+    seed: 999,
+    objective: { kind: OBJECTIVES.REACH_EXIT, title: 'Extract clean', briefing: 'Reach exit.' },
+    difficulty: 'standard',
+    threatCount: 1,
+    label: 'meat job',
+    context: testContractContext(OBJECTIVES.REACH_EXIT),
+    reward: { credits: 0, repDelta: 0 },
+  });
+  run.enterCombat();
+  assert.equal(run.cyberspace, null);
+  assert.throws(() => run.jackOut(), /phase/);
+});
+
+// --- LINK BURNED ---------------------------------------------------------------------
+
+test('jack-out burns the meat-side port', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  const point = meatPort(run);
+  assert.equal(point.burned, false, 'link is live while the avatar is in the grid');
+
+  routeOut(layer);
+  assert.equal(run.cyberspace?.phase, 'resolved');
+  assert.equal(point.burned, true);
+
+  run.player!.refreshAp();
+  const apBefore = run.player!.ap;
+  const repeat = point.interact(run.world!, run.player!);
+  assert.equal(repeat.ok, false);
+  assert.equal((repeat as { reason: string }).reason, 'link-burned');
+  assert.match(repeat.message, /LINK BURNED/);
+  assert.equal(run.player!.ap, apBefore, 'refusal burns no AP');
+  assert.equal(run.cyberspace?.phase, 'resolved', 'the layer does not reactivate');
+});
+
+test('burn() on an unlinked port is corrupt state and throws', () => {
+  const point = new JackInPoint({ id: 'jack-in-0', x: 1, y: 1 });
+  assert.throws(() => point.burn(), /link/i);
+});
+
+// --- persistence ----------------------------------------------------------------------
+
+test('the burned latch round-trips and the restored port stays dead', () => {
+  const run = combatRun();
+  routeOut(jackIn(run));
+
+  const record = structuredClone(snapshot(run));
+  assert.equal((portRecord(record).extra as { burned?: boolean }).burned, true);
+
+  const { run: restored } = restore(record);
+  const point = meatPort(restored);
+  assert.equal(point.burned, true);
+  restored.player!.refreshAp();
+  const repeat = point.interact(restored.world!, restored.player!);
+  assert.equal(repeat.ok, false);
+  assert.equal((repeat as { reason: string }).reason, 'link-burned');
+});
+
+test('a pre-S5 record without the burned flag restores unburned', () => {
+  const run = combatRun();
+  jackIn(run);
+  const record = structuredClone(snapshot(run));
+  delete (portRecord(record).extra as Record<string, unknown>).burned;
+  const { run: restored } = restore(record);
+  assert.equal(meatPort(restored).burned, false);
+});
+
+test('burned without linked is corrupt and throws on restore', () => {
+  const run = combatRun();
+  jackIn(run);
+  const record = structuredClone(snapshot(run));
+  const extra = portRecord(record).extra as Record<string, unknown>;
+  extra.linked = false;
+  extra.burned = true;
+  assert.throws(() => restore(record), /burned/);
+});
+
+test('a non-boolean burned flag throws on restore', () => {
+  const run = combatRun();
+  jackIn(run);
+  const record = structuredClone(snapshot(run));
+  (portRecord(record).extra as Record<string, unknown>).burned = 'yes';
+  assert.throws(() => restore(record), /burned/);
+});
diff --git a/tests/unit/game/cyber/runJackIn.test.ts b/tests/unit/game/cyber/runJackIn.test.ts
index daf11f2..9ed791a 100644
--- a/tests/unit/game/cyber/runJackIn.test.ts
+++ b/tests/unit/game/cyber/runJackIn.test.ts
@@ -238,6 +238,8 @@ test('re-interacting the meat port after resolve stays refused (LINK BURNED)', (
   run.player!.refreshAp();
   const repeat = point.interact(run.world!, run.player!);
   assert.equal(repeat.ok, false);
-  assert.equal((repeat as { reason: string }).reason, 'already-linked');
+  // S5: jack-out burns the link — the refusal carries burn flavor, not the
+  // redundant-input 'already-linked'.
+  assert.equal((repeat as { reason: string }).reason, 'link-burned');
   assert.equal(run.cyberspace?.phase, 'resolved');
 });

From 2e3db6acb29f09323a487f242a0707fca872b6c6 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Wed, 10 Jun 2026 14:20:44 -0700
Subject: [PATCH 22/55] =?UTF-8?q?P3.M3=20plan:=20S5=20shipped=20=E2=80=94?=
 =?UTF-8?q?=20progress=20row=20+=20implementation=20notes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/phase-3-cyberspace-plan.md | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/docs/phase-3-cyberspace-plan.md b/docs/phase-3-cyberspace-plan.md
index 0f9f3b7..2cc7c91 100644
--- a/docs/phase-3-cyberspace-plan.md
+++ b/docs/phase-3-cyberspace-plan.md
@@ -33,7 +33,7 @@ Commits land **per green slice** (user-approved).
 | **S2 — P3.M3.2 Jack-in terminal** | ✅ Done | `05013f6` |
 | **S3 — P3.M3.3 Cyber layer model + avatar + persistence** | ✅ Done | `39b357e` |
 | **S4 — P3.M3.4 Data node objective** | ✅ Done | `3923149` |
-| **S5 — Voluntary jack-out (M4.6 pull-forward)** | 🔲 Planned | — |
+| **S5 — Voluntary jack-out (M4.6 pull-forward)** | ✅ Done | `fab3bcb` |
 | **S6 — P3.M3.5 Probe ICE** | 🔲 Planned | — |
 | **S7 — P3.M3.6 Render/input swap + shell ICE phase** | 🔲 Planned | — |
 | **S8 — Docs + wrap-up** | 🔲 Planned | — |
@@ -200,6 +200,29 @@ Commits land **per green slice** (user-approved).
   round-trip, adversarial node-count/extra throws). Failing-first verified;
   suite 1629 green.
 
+### S5 implementation notes (shipped)
+
+- Most of the planned S5 core had already landed: the resolve latch,
+  teardown, autosave (S3) and the real `objectiveComplete` tally (S4). The
+  coverage audit confirmed resolved-latching-both-ways, post-jack-out
+  round-trip, and resolved-block payload smuggling were locked by S3/S4
+  tests; the genuinely missing rows were the dormant/non-cyber jackOut
+  throws (now in `jackOut.test.ts`).
+- **LINK BURNED is a real latch, not copy**: `JackInPoint.burned`, set by
+  `Run.jackOut()` via `burn()` on the meat-side port. A burned port refuses
+  *before* the linked check with its own reason (`link-burned`, "LINK BURNED
+  — the connection is dead"), distinct from the redundant-input
+  `already-linked`. `burn()` on an unlinked port throws — and so does
+  constructing one (burned ⇒ linked is an invariant).
+- Persistence: snapshot `extra` carries `burned`; absent on pre-S5 records →
+  unburned (legacy normalization, decker-stats pattern); non-boolean or
+  burned-without-linked throws.
+- Tests: 8 in `jackOut.test.ts` (illegal phases, burn-on-jack-out + refusal
+  flavor + no-AP, burn invariants, round-trip, legacy absence, adversarial
+  malformed/inconsistent flags). The S3 runJackIn LINK BURNED test was
+  updated from the placeholder `already-linked` expectation to the real
+  `link-burned`. Suite 1637 green.
+
 ## Architecture decisions (approved plan)
 
 ### Cyber layer model — `CyberspaceLayer` owned by `Run`, single `TurnQueue`, both worlds tick

From 0a4687837988228329bc3e1d858b142f2f622eaf Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Wed, 10 Jun 2026 14:38:21 -0700
Subject: [PATCH 23/55] =?UTF-8?q?P3.M3.5:=20Probe=20ICE=20=E2=80=94=20trac?=
 =?UTF-8?q?e=20flare,=20pack=20convergence,=20the=20grid=20bites=20back?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

S6 of the cyberspace slice plan:

- ProbeIce (glyph ¶, displayName Probe) extends PatrolHostile: explicit
  small stats (hp 3, melee dmg 1, sight 6 — ICE scaling is its own axis,
  resolveEnemyStats tiers deliberately unused). EngageSteps = trace flare
  then Guard-style close-and-strike: raiseAlarm({repPenalty: false}) on
  the *cyber* world self-gates while ALERT, so the 'trace-alarm' step
  fires once per alarm window; probes listen for alarms (PatrolHostile
  default, unlike the Lookout) so one flare converges the pack.
- CyberspaceLayer.build spawns one probe per patrol ring at a seed-picked
  ring tile (pure function of the contract seed) and binds it to the
  layer bus; the restore path was already re-binding PatrolHostiles.
- Registry plumbing: 'probe-ice' joins PATROL_ARCHETYPE_IDS (shares the
  generic patrol snapshot/restore machinery wholesale), archetypeOf,
  SNAPSHOT_EXTRACTORS, ARCHETYPE_FACTORY, kindFromId; 'trace-alarm' step
  type + corp-turn status copy line.
- Death paths proven through the real combat pipeline (no synthetic
  emits): probe melee on a 1-hp avatar → RESULT/DEATH with cause; avatar
  killing a probe counts in run telemetry. ICE resistance mitigation
  locked to the min-1 rule (dmg 1 vs resist 1 → 1).
- Cyber alarm verified decoupled from Meatspace (no ALARM on the meat
  bus, meat latch untouched) and ticking on meat round advances.

9 new tests (ProbeIce.test.ts; failing-first verified), suite 1646 green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/game/Entity.ts                            |   1 +
 src/game/Run.ts                               |   6 +
 src/game/constants.ts                         |   2 +
 src/game/corpTurnStatusCopy.ts                |   5 +
 src/game/cyber/CyberspaceLayer.ts             |  16 ++
 src/game/cyber/ProbeIce.ts                    |  81 ++++++
 src/game/persistence.ts                       |   3 +
 src/types.ts                                  |   8 +
 tests/unit/game/cyber/CyberspaceLayer.test.ts |  10 +-
 tests/unit/game/cyber/ProbeIce.test.ts        | 272 ++++++++++++++++++
 10 files changed, 402 insertions(+), 2 deletions(-)
 create mode 100644 src/game/cyber/ProbeIce.ts
 create mode 100644 tests/unit/game/cyber/ProbeIce.test.ts

diff --git a/src/game/Entity.ts b/src/game/Entity.ts
index 8307a6d..c914783 100644
--- a/src/game/Entity.ts
+++ b/src/game/Entity.ts
@@ -278,6 +278,7 @@ function kindFromId(id: string): string {
   if (id.startsWith('cyber-avatar')) return 'Avatar';
   if (id.startsWith('entry-port')) return 'Exit Port';
   if (id.startsWith('data-node')) return 'Data Node';
+  if (id.startsWith('probe-ice')) return 'Probe';
   if (id.includes('turret')) return 'Turret';
   if (id.startsWith('crew')) return 'Operative';
   return id;
diff --git a/src/game/Run.ts b/src/game/Run.ts
index 7770ff0..36fd613 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -83,6 +83,7 @@ import { CyberspaceLayer } from './cyber/CyberspaceLayer.js';
 import { CyberAvatar } from './cyber/CyberAvatar.js';
 import { EntryPort } from './cyber/EntryPort.js';
 import { DataNode } from './cyber/DataNode.js';
+import { ProbeIce } from './cyber/ProbeIce.js';
 import { applyMutationDeltas } from './locations.js';
 import { BreachingCharge } from './entities/BreachingCharge.js';
 import { ITEM_ID, getItemById } from './items.js';
@@ -180,6 +181,7 @@ export type EntityArchetypeId =
   | 'cyber-avatar'
   | 'entry-port'
   | 'data-node'
+  | 'probe-ice'
   | 'entity';
 
 export type RunTelemetry = {
@@ -224,6 +226,8 @@ export const PATROL_ARCHETYPE_IDS = Object.freeze([
   'lookout',
   'sniper',
   'medic',
+  // P3.M3.5: Probe ICE shares the identical patrol state-machine block.
+  'probe-ice',
 ] as const);
 
 export type PatrolArchetypeId = (typeof PATROL_ARCHETYPE_IDS)[number];
@@ -2044,6 +2048,7 @@ const SNAPSHOT_EXTRACTORS: Partial<Record<EntityArchetypeId, (e: Entity) => Enti
         sliceProgress: n.sliceProgress,
       } satisfies DataNodeSnapshot;
     },
+    'probe-ice': e => patrolSnapshotExtra(e as PatrolHostile),
   };
 
 /**
@@ -2133,6 +2138,7 @@ function archetypeOf(entity: Entity): EntityArchetypeId {
   if (entity instanceof CyberAvatar) return 'cyber-avatar';
   if (entity instanceof EntryPort) return 'entry-port';
   if (entity instanceof DataNode) return 'data-node';
+  if (entity instanceof ProbeIce) return 'probe-ice';
   if (entity instanceof BreachingCharge) return 'breaching-charge';
   if (entity instanceof Entity) return 'entity';
   throw new Error(`archetypeOf: cannot classify entity ${(entity as Entity | undefined)?.id}`);
diff --git a/src/game/constants.ts b/src/game/constants.ts
index 199b5b2..52dba84 100644
--- a/src/game/constants.ts
+++ b/src/game/constants.ts
@@ -50,6 +50,8 @@ export const JACK_IN_GLYPH = 'Ω';
 export const ENTRY_PORT_GLYPH = '▼';
 /** P3.M3.4: the slice target on the cyber grid (`◆` is DenyTarget's). */
 export const DATA_NODE_GLYPH = '◈';
+/** P3.M3.5: Probe ICE — the patrol fodder of the cyber grid. */
+export const PROBE_ICE_GLYPH = '¶';
 
 /** Numeric tile id — one of the `TILE` values. */
 export type TileId = (typeof TILE)[keyof typeof TILE];
diff --git a/src/game/corpTurnStatusCopy.ts b/src/game/corpTurnStatusCopy.ts
index 47db5cc..b127918 100644
--- a/src/game/corpTurnStatusCopy.ts
+++ b/src/game/corpTurnStatusCopy.ts
@@ -223,6 +223,11 @@ export function formatCorpTurnStep(
       return `${actorLabel} abandons pursuit — resuming patrol.`;
     case 'alarm':
       return `${actorLabel} trips the facility alarm — corp net hot.`;
+    case 'trace-alarm': {
+      // P3.M3.5: Probe ICE trace flare on the cyber grid.
+      const targetLabel = resolve(step.target);
+      return `${actorLabel} flares a trace on ${targetLabel} — ICE converging.`;
+    }
     case 'spot': {
       const targetLabel = resolve(step.target);
       return `${actorLabel} marks ${targetLabel} — fire converging on your position.`;
diff --git a/src/game/cyber/CyberspaceLayer.ts b/src/game/cyber/CyberspaceLayer.ts
index ed110d4..760cd60 100644
--- a/src/game/cyber/CyberspaceLayer.ts
+++ b/src/game/cyber/CyberspaceLayer.ts
@@ -26,6 +26,7 @@ import { buildCyberMap } from './cyberMapBuild.js';
 import { CyberAvatar } from './CyberAvatar.js';
 import { EntryPort } from './EntryPort.js';
 import { DataNode, sliceDifficultyFor } from './DataNode.js';
+import { ProbeIce } from './ProbeIce.js';
 import { PatrolHostile } from '../ai/PatrolHostile.js';
 import { FACTION, type ContractDifficulty, type FactionId } from '../constants.js';
 import { coordKey } from '../mapConnectivity.js';
@@ -159,6 +160,21 @@ export class CyberspaceLayer {
         })
       );
     }
+    // P3.M3.5: one Probe per patrol ring, spawned at a seed-picked ring tile
+    // (the rng has fully determined the map by here, so this stays a pure
+    // function of the contract seed). Probes bind to the layer bus at build —
+    // the restore path re-binds via `restoreCyberspaceLayer`.
+    map.patrolRings.forEach((ring, i) => {
+      const spawn = ring[rng.intRange(0, ring.length)];
+      const probe = new ProbeIce({
+        id: `probe-ice-${i}`,
+        x: spawn.x,
+        y: spawn.y,
+        patrolWaypoints: ring,
+      });
+      world.addEntity(probe);
+      probe.bindToBus(bus);
+    });
     return new CyberspaceLayer({
       bus,
       world,
diff --git a/src/game/cyber/ProbeIce.ts b/src/game/cyber/ProbeIce.ts
new file mode 100644
index 0000000..27e9489
--- /dev/null
+++ b/src/game/cyber/ProbeIce.ts
@@ -0,0 +1,81 @@
+/**
+ * P3.M3.5 — Probe ICE: the patrol fodder of the cyber grid.
+ *
+ * Walks a perimeter ring around a data-node room via the shared
+ * patrol → investigate → engage machine. Its identity is the **trace
+ * flare**: on acquiring the avatar it raises the *cyber* world's alarm
+ * (`repPenalty: false` — job noise on a private bus, never a social cost)
+ * so the whole pack converges, then closes and strikes like a Guard.
+ * Unlike the Lookout it *listens* for alarms (the `PatrolHostile` default):
+ * one probe's flare is every probe's heading.
+ *
+ * Stats are explicit and small — ICE scaling is its own axis (Spark and
+ * Guardian ICE are the follow-up slices), so `resolveEnemyStats` tiers are
+ * deliberately not reused. The avatar's `iceResistance` mitigates the weak
+ * strike down to the engine-wide minimum of 1.
+ */
+import { PatrolHostile, type PatrolHostileInit, type EngageSteps } from '../ai/PatrolHostile.js';
+import { AP_COST, PROBE_ICE_GLYPH } from '../constants.js';
+import { canMelee, resolveMelee } from '../Combat.js';
+import type { Entity } from '../Entity.js';
+import type { World } from '../World.js';
+import type { Rng } from '../../rng.js';
+
+export const PROBE_ICE_HP = 3;
+export const PROBE_ICE_DAMAGE = 1;
+export const PROBE_ICE_SIGHT_RANGE = 6;
+
+export interface ProbeIceProps extends Omit<PatrolHostileInit, 'glyph'> {}
+
+export class ProbeIce extends PatrolHostile {
+  /** Sniffed by `Combat.attackerMeleeDamage` — the weak ICE strike. */
+  readonly meleeDamage = PROBE_ICE_DAMAGE;
+
+  constructor({
+    maxHp = PROBE_ICE_HP,
+    sightRange = PROBE_ICE_SIGHT_RANGE,
+    patrolWaypoints,
+    ...props
+  }: ProbeIceProps) {
+    super({
+      ...props,
+      maxHp,
+      sightRange,
+      glyph: PROBE_ICE_GLYPH,
+      displayName: 'Probe',
+      patrolWaypoints,
+    });
+  }
+
+  /**
+   * Trace flare, then Guard-style close-and-strike. `raiseAlarm` self-gates
+   * (returns false while the alarm is already ALERT), so the flare step is
+   * yielded exactly once per alarm window.
+   */
+  protected override *engageSteps(world: World, rng: Rng, target: Entity): EngageSteps {
+    const raised = world.raiseAlarm({
+      source: this,
+      target,
+      origin: { x: this.x, y: this.y },
+      repPenalty: false,
+    });
+    if (raised) {
+      yield { type: 'trace-alarm', target: target.id };
+    }
+
+    const meleeCheck = canMelee(world, this, target);
+    if (meleeCheck.ok) {
+      const result = resolveMelee(world, this, target, rng);
+      yield { type: 'melee', target: target.id, result };
+      return 'continue';
+    }
+    if (meleeCheck.reason !== 'not-adjacent' && meleeCheck.reason !== 'insufficient-ap') {
+      return 'break';
+    }
+    if (this.ap < AP_COST.MOVE) return 'break';
+    const step = this.stepToward(world, target.x, target.y, 'engage');
+    if (!step) return 'break';
+    yield step;
+    return 'continue';
+  }
+}
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index 48385ba..9d59a07 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -81,6 +81,8 @@ import type { CyberAvatarInit, CyberAvatarSnapshot } from './cyber/CyberAvatar.j
 import type { EntryPortInit, EntryPortSnapshot } from './cyber/EntryPort.js';
 import { DataNode } from './cyber/DataNode.js';
 import type { DataNodeInit, DataNodeSnapshot } from './cyber/DataNode.js';
+import { ProbeIce } from './cyber/ProbeIce.js';
+import type { ProbeIceProps } from './cyber/ProbeIce.js';
 import type { DeckerInit, DeckerSnapshot } from './archetypes/Decker.js';
 import { Run, RUN_STATE, PATROL_ARCHETYPE_IDS } from './Run.js';
 import { Campaign, CAMPAIGN_STATE, normalizeCampaignArc } from './Campaign.js';
@@ -229,6 +231,7 @@ const ARCHETYPE_FACTORY: Record<EntityArchetypeId, (props: RestoreEntityProps) =
     'cyber-avatar': (props: RestoreEntityProps) => new CyberAvatar(props as CyberAvatarInit),
     'entry-port': (props: RestoreEntityProps) => new EntryPort(props as EntryPortInit),
     'data-node': (props: RestoreEntityProps) => new DataNode(props as DataNodeInit),
+    'probe-ice': (props: RestoreEntityProps) => new ProbeIce(props as ProbeIceProps),
     'breaching-charge': (props: RestoreEntityProps) =>
       new BreachingCharge(props as BreachingChargeInit),
     // Generic fallback so a future `Entity` subclass (NPCs, items) doesn't break
diff --git a/src/types.ts b/src/types.ts
index eb74f15..f64f750 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -144,6 +144,13 @@ export type JuggernautTurnStep =
 /** Flanker SLIDE — a silent two-tile reposition that vanishes from player view. */
 export type FlankerTurnStep = { type: 'slide'; to: GridPoint };
 
+/**
+ * Probe ICE trace flare (P3.M3.5) — yielded the moment a probe's acquisition
+ * actually raises the cyber alarm (the raise self-gates while already ALERT),
+ * dragging every listening probe onto the avatar.
+ */
+export type ProbeIceTurnStep = { type: 'trace-alarm'; target: string };
+
 /** NeutralCivilian aftermath steps — yielded during the player aftermath phase. */
 export type NeutralCivilianTurnStep =
   | { type: 'neutral-idle' }
@@ -164,6 +171,7 @@ export type TurnActionStep =
   | SniperTurnStep
   | JuggernautTurnStep
   | FlankerTurnStep
+  | ProbeIceTurnStep
   | NeutralCivilianTurnStep;
 
 /**
diff --git a/tests/unit/game/cyber/CyberspaceLayer.test.ts b/tests/unit/game/cyber/CyberspaceLayer.test.ts
index f97a87c..7d54a80 100644
--- a/tests/unit/game/cyber/CyberspaceLayer.test.ts
+++ b/tests/unit/game/cyber/CyberspaceLayer.test.ts
@@ -70,12 +70,18 @@ test('build spawns the avatar at the entry tile with stats from the Decker', ()
   assert.equal(avatar.baseHitChance, CYBER_AVATAR_HIT_CHANCE);
 });
 
-test('the cyber world contains exactly the avatar, the exit port, and the nodes', () => {
+test('the cyber world census: avatar, exit port, nodes, ring probes', () => {
   const layer = buildLayer();
   const entities = Array.from(layer.world.entities.values());
   assert.equal(entities.filter(e => e instanceof CyberAvatar).length, 1);
   assert.equal(entities.filter(e => e instanceof EntryPort).length, 1);
-  assert.equal(entities.length, 3, 'avatar + port + the contract data node (P3.M3.4)');
+  assert.equal(
+    entities.length,
+    // avatar + port + the contract data node (P3.M3.4) + one Probe per
+    // patrol ring (P3.M3.5).
+    3 + layer.patrolRings.length,
+    'no surprise entities on the cyber grid'
+  );
   const cheb = Math.max(
     Math.abs(layer.port.x - layer.avatar.x),
     Math.abs(layer.port.y - layer.avatar.y)
diff --git a/tests/unit/game/cyber/ProbeIce.test.ts b/tests/unit/game/cyber/ProbeIce.test.ts
new file mode 100644
index 0000000..02ad293
--- /dev/null
+++ b/tests/unit/game/cyber/ProbeIce.test.ts
@@ -0,0 +1,272 @@
+/**
+ * P3.M3.5 — Probe ICE: the first hostile on the cyber grid.
+ *
+ * A weak melee patroller on the node rings. Its identity: on acquiring the
+ * avatar it raises the *cyber* alarm (trace flare — no rep penalty, no meat
+ * coupling) so the pack converges, then strikes. Avatar death routes through
+ * the existing DEATH/flatline path via the real combat pipeline; ICE
+ * resistance mitigates with the min-1 rule.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { Run, RUN_STATE, OUTCOME } from '../../../../src/game/Run.js';
+import { CyberspaceLayer } from '../../../../src/game/cyber/CyberspaceLayer.js';
+import { ProbeIce } from '../../../../src/game/cyber/ProbeIce.js';
+import { PATROL_STATE } from '../../../../src/game/ai/PatrolHostile.js';
+import { JackInPoint } from '../../../../src/game/entities/JackInPoint.js';
+import { resolveMelee } from '../../../../src/game/Combat.js';
+import { EVENT } from '../../../../src/game/events.js';
+import { snapshot, restore } from '../../../../src/game/persistence.js';
+import { buildCrewMember } from '../../../../src/game/archetypes/index.js';
+import { Decker } from '../../../../src/game/archetypes/Decker.js';
+import { FACTION } from '../../../../src/game/constants.js';
+import { OBJECTIVES } from '../../../../src/game/hub/Curator.js';
+import { Rng } from '../../../../src/rng.js';
+import { testContractContext } from '../contractTestUtils.js';
+import type { World } from '../../../../src/game/World.js';
+import type { Entity } from '../../../../src/game/Entity.js';
+import type { RunResult } from '../../../../src/game/Run.js';
+
+const cyberContract = (seed = 12345) => ({
+  seed,
+  objective: {
+    kind: OBJECTIVES.DATA_NODE_SLICE,
+    title: 'Spike the server farm',
+    briefing: 'Jack in, slice the data node, then extract.',
+    params: { requiresCyberspace: true, count: 1 },
+  },
+  difficulty: 'standard',
+  threatCount: 1,
+  label: 'cyber test job',
+  context: testContractContext(OBJECTIVES.DATA_NODE_SLICE),
+  reward: { credits: 0, repDelta: 0 },
+});
+
+function makeDecker() {
+  return buildCrewMember('decker', { x: 0, y: 0 }, new Rng(100), { id: 'crew-decker' });
+}
+
+function buildLayer(contractSeed = 12345) {
+  return CyberspaceLayer.build({
+    contractSeed,
+    difficulty: 'standard',
+    decker: new Decker({ id: 'crew-decker', x: 0, y: 0 }),
+    nodeCount: 1,
+  });
+}
+
+function adjacentFreeTile(world: World, target: Entity) {
+  for (let dy = -1; dy <= 1; dy++) {
+    for (let dx = -1; dx <= 1; dx++) {
+      if (dx === 0 && dy === 0) continue;
+      const x = target.x + dx;
+      const y = target.y + dy;
+      if (world.grid.inBounds(x, y) && world.grid.isPassable(x, y) && !world.entityAt(x, y)) {
+        return { x, y };
+      }
+    }
+  }
+  throw new Error(`no free tile adjacent to ${target.id}`);
+}
+
+function combatRun(seed = 12345, hooks: { onResult?: (r: RunResult) => void } = {}) {
+  const run = new Run({ crewMember: makeDecker(), seed, ...hooks });
+  run.enterBriefing(cyberContract(seed));
+  run.enterCombat();
+  return run;
+}
+
+function jackIn(run: Run): CyberspaceLayer {
+  const point = Array.from(run.world!.entities.values()).find(
+    e => e instanceof JackInPoint
+  ) as JackInPoint;
+  const spot = adjacentFreeTile(run.world!, point);
+  run.world!.relocateEntity(run.player!, spot.x, spot.y);
+  run.player!.refreshAp();
+  assert.equal(point.interact(run.world!, run.player!).ok, true);
+  return (run.cyberspace as { phase: 'active'; layer: CyberspaceLayer }).layer;
+}
+
+function probesOf(layer: CyberspaceLayer): ProbeIce[] {
+  return Array.from(layer.world.entities.values()).filter(
+    (e): e is ProbeIce => e instanceof ProbeIce
+  );
+}
+
+function probeKey(p: ProbeIce) {
+  return { id: p.id, x: p.x, y: p.y, waypoints: p.patrolWaypoints };
+}
+
+// --- spawning -------------------------------------------------------------------------
+
+test('build spawns one probe per patrol ring with explicit ICE stats', () => {
+  const layer = buildLayer();
+  const probes = probesOf(layer);
+  assert.equal(probes.length, layer.patrolRings.length);
+  assert.ok(probes.length > 0, 'standard difficulty patrols at least one ring');
+  const ids = new Set(probes.map(p => p.id));
+  assert.equal(ids.size, probes.length, 'probe ids are unique');
+  for (const probe of probes) {
+    assert.equal(probe.glyph, '¶');
+    assert.equal(probe.displayName, 'Probe');
+    assert.equal(probe.maxHp, 3);
+    assert.equal(probe.sightRange, 6);
+    assert.equal(probe.meleeDamage, 1);
+    assert.equal(probe.faction, FACTION.CORP);
+    assert.ok(probe.patrolWaypoints.length > 0, 'probe walks a ring');
+    assert.ok(
+      probe.patrolWaypoints.some(wp => wp.x === probe.x && wp.y === probe.y),
+      'probe spawns on its own ring'
+    );
+    assert.ok(layer.world.grid.isPassable(probe.x, probe.y));
+  }
+});
+
+test('probe spawns are deterministic on the contract seed', () => {
+  const a = probesOf(buildLayer(909)).map(probeKey);
+  const b = probesOf(buildLayer(909)).map(probeKey);
+  assert.deepEqual(a, b);
+  const c = probesOf(buildLayer(910)).map(probeKey);
+  assert.notDeepEqual(a, c, 'a different seed diverges');
+});
+
+// --- combat ---------------------------------------------------------------------------
+
+test('probe damage is mitigated by ICE resistance with the min-1 rule', () => {
+  const layer = buildLayer();
+  const avatar = layer.avatar; // RAM 8, iceResistance 1
+  const probe = probesOf(layer)[0];
+  const spot = adjacentFreeTile(layer.world, avatar);
+  layer.world.relocateEntity(probe, spot.x, spot.y);
+  probe.refreshAp();
+
+  const result = resolveMelee(layer.world, probe, avatar, new Rng(1), { dodgeChance: 0 });
+  assert.equal(result.hit, true);
+  assert.equal(result.damage, 1, 'dmg 1 vs resist 1 still chips the minimum 1');
+  assert.equal(avatar.hp, avatar.maxHp - 1);
+});
+
+test('acquisition raises the cyber alarm and converges the pack', () => {
+  const layer = buildLayer();
+  const avatar = layer.avatar;
+  const probes = probesOf(layer);
+  const hunter = probes[0];
+  const distant = probes[probes.length - 1];
+  assert.notEqual(hunter, distant);
+
+  const spot = adjacentFreeTile(layer.world, avatar);
+  layer.world.relocateEntity(hunter, spot.x, spot.y);
+  hunter.refreshAp();
+  assert.equal(distant.state, PATROL_STATE.PATROL);
+
+  const steps = hunter.takeTurn(layer.world, new Rng(7));
+  assert.equal(layer.world.alarmActive, true, 'trace flare trips the cyber alarm');
+  assert.ok(
+    steps.some(s => s.type === 'trace-alarm'),
+    'turn log carries the trace step'
+  );
+  assert.ok(
+    steps.some(s => s.type === 'melee'),
+    'the probe strikes after flaring'
+  );
+  // The far probe heard the flare (alarm bus) and converges on the avatar.
+  assert.equal(distant.state, PATROL_STATE.ENGAGE);
+  assert.deepEqual(distant.lastKnownTarget, { x: avatar.x, y: avatar.y });
+});
+
+test('the cyber alarm never couples to Meatspace', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  let meatAlarmEvents = 0;
+  run.bus!.on(EVENT.ALARM, () => meatAlarmEvents++);
+
+  layer.world.raiseAlarm({ target: layer.avatar, repPenalty: false });
+  assert.equal(layer.world.alarmActive, true);
+  assert.equal(run.world!.alarmActive, false, 'meat alarm latch untouched');
+  assert.equal(meatAlarmEvents, 0, 'no ALARM event leaks onto the meat bus');
+});
+
+test('the cyber alarm cadence ticks on meat round advances', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  layer.world.raiseAlarm({ target: layer.avatar, repPenalty: false });
+  const before = layer.world.snapshotAlarm();
+
+  run.queue!.endTurn(run.world!); // player → corp
+  run.queue!.endTurn(run.world!); // corp → player: round advance ticks the cyber alarm
+  const after = layer.world.snapshotAlarm();
+  assert.equal(after.holdTurnsRemaining, before.holdTurnsRemaining - 1);
+});
+
+// --- death paths ------------------------------------------------------------------------
+
+test('a probe killing the avatar flatlines through the real combat pipeline', () => {
+  const results: RunResult[] = [];
+  const run = combatRun(12345, { onResult: r => results.push(r) });
+  const layer = jackIn(run);
+  const avatar = layer.avatar;
+  avatar.damage(avatar.hp - 1); // one strike from death
+
+  const probe = probesOf(layer)[0];
+  const spot = adjacentFreeTile(layer.world, avatar);
+  layer.world.relocateEntity(probe, spot.x, spot.y);
+  probe.refreshAp();
+  const result = resolveMelee(layer.world, probe, avatar, new Rng(1), { dodgeChance: 0 });
+  assert.equal(result.killed, true);
+
+  assert.equal(run.state, RUN_STATE.RESULT);
+  assert.equal(results.length, 1);
+  assert.equal(results[0].outcome, OUTCOME.DEATH);
+  assert.match(String(results[0].telemetry.cause), new RegExp(probe.id));
+});
+
+test('the avatar killing a probe counts toward run telemetry', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  const probe = probesOf(layer)[0];
+  const spot = adjacentFreeTile(layer.world, probe);
+  layer.world.relocateEntity(layer.avatar, spot.x, spot.y);
+  layer.avatar.refreshAp();
+  const before = run.telemetry.kills ?? 0;
+
+  const result = resolveMelee(layer.world, layer.avatar, probe, new Rng(1), {
+    dodgeChance: 0,
+    damage: probe.hp,
+  });
+  assert.equal(result.killed, true);
+  assert.equal(probe.alive, false);
+  assert.equal(run.telemetry.kills, before + 1);
+});
+
+// --- persistence --------------------------------------------------------------------------
+
+test('probe patrol state round-trips and restored probes are re-bound', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  const probe = probesOf(layer)[0];
+  // Dirty the state machine: mid-pursuit, off-ring, chipped.
+  const spot = adjacentFreeTile(layer.world, layer.avatar);
+  layer.world.relocateEntity(probe, spot.x, spot.y);
+  probe.state = PATROL_STATE.ENGAGE;
+  probe.lastKnownTarget = { x: layer.avatar.x, y: layer.avatar.y };
+  probe.patrolIndex = 1 % probe.patrolWaypoints.length;
+  probe.damage(1);
+
+  const { run: restored } = restore(structuredClone(snapshot(run)));
+  const restoredLayer = (restored.cyberspace as { phase: 'active'; layer: CyberspaceLayer }).layer;
+  const twin = probesOf(restoredLayer).find(p => p.id === probe.id);
+  assert.ok(twin instanceof ProbeIce);
+  assert.deepEqual(
+    { x: twin!.x, y: twin!.y, state: twin!.state, idx: twin!.patrolIndex, hp: twin!.hp },
+    { x: probe.x, y: probe.y, state: probe.state, idx: probe.patrolIndex, hp: probe.hp }
+  );
+  assert.deepEqual(twin!.lastKnownTarget, probe.lastKnownTarget);
+  assert.deepEqual(twin!.patrolWaypoints, probe.patrolWaypoints);
+
+  // Re-binding: a fresh cyber alarm drags a still-patrolling probe to ENGAGE.
+  const patroller = probesOf(restoredLayer).find(p => p.state === PATROL_STATE.PATROL);
+  assert.ok(patroller, 'another probe is still on its ring');
+  restoredLayer.world.raiseAlarm({ target: restoredLayer.avatar, repPenalty: false });
+  assert.equal(patroller!.state, PATROL_STATE.ENGAGE);
+});

From 27ab16feb34f57ddbddda9f5f1f65b9ae15c6c44 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Wed, 10 Jun 2026 14:39:09 -0700
Subject: [PATCH 24/55] =?UTF-8?q?P3.M3=20plan:=20S6=20shipped=20=E2=80=94?=
 =?UTF-8?q?=20progress=20row,=20notes,=20ICE-faction=20follow-up=20flag?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/phase-3-cyberspace-plan.md | 39 ++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/docs/phase-3-cyberspace-plan.md b/docs/phase-3-cyberspace-plan.md
index 2cc7c91..b61de11 100644
--- a/docs/phase-3-cyberspace-plan.md
+++ b/docs/phase-3-cyberspace-plan.md
@@ -34,7 +34,7 @@ Commits land **per green slice** (user-approved).
 | **S3 — P3.M3.3 Cyber layer model + avatar + persistence** | ✅ Done | `39b357e` |
 | **S4 — P3.M3.4 Data node objective** | ✅ Done | `3923149` |
 | **S5 — Voluntary jack-out (M4.6 pull-forward)** | ✅ Done | `fab3bcb` |
-| **S6 — P3.M3.5 Probe ICE** | 🔲 Planned | — |
+| **S6 — P3.M3.5 Probe ICE** | ✅ Done | `0a46878` |
 | **S7 — P3.M3.6 Render/input swap + shell ICE phase** | 🔲 Planned | — |
 | **S8 — Docs + wrap-up** | 🔲 Planned | — |
 
@@ -223,6 +223,43 @@ Commits land **per green slice** (user-approved).
   updated from the placeholder `already-linked` expectation to the real
   `link-burned`. Suite 1637 green.
 
+### S6 implementation notes (shipped)
+
+- `src/game/cyber/ProbeIce.ts` — `ProbeIce extends PatrolHostile`, glyph `¶`
+  (`PROBE_ICE_GLYPH`), displayName `Probe`. Explicit stats
+  (`PROBE_ICE_HP 3` / `PROBE_ICE_DAMAGE 1` via the `meleeDamage` sniff /
+  `PROBE_ICE_SIGHT_RANGE 6`); `resolveEnemyStats` tiers deliberately unused —
+  ICE scaling is its own axis for the Spark/Guardian follow-ups.
+- **Trace flare**: `engageSteps` raises the *cyber* world's alarm
+  (`repPenalty: false`) before striking; `raiseAlarm` self-gates while
+  ALERT so the `trace-alarm` step (new `ProbeIceTurnStep` in `types.ts`,
+  with corp-turn status copy) fires once per alarm window. Probes keep the
+  `PatrolHostile` default `listensForAlarm() === true` — one probe's flare
+  is every probe's heading (verified: a distant patroller flips to ENGAGE
+  with the avatar's coordinates).
+- Spawning: one probe per `buildCyberMap` patrol ring, at a seed-picked ring
+  tile (rng consumed *after* map generation, so layouts are untouched and
+  placement stays a pure function of the contract seed). Build binds probes
+  to the layer bus; restore re-binds via the existing
+  `restoreCyberspaceLayer` PatrolHostile path.
+- Persistence rode the generic machinery: adding `'probe-ice'` to
+  `PATROL_ARCHETYPE_IDS` bought waypoints/state/index round-trip wholesale;
+  only `ARCHETYPE_FACTORY` + extractor entries were new.
+- Death paths proven through the **real combat pipeline** (resolveMelee on
+  the cyber world's bus, no synthetic emits): probe kills avatar →
+  RESULT/DEATH with attacker in the cause; avatar kills probe → telemetry
+  kill count. Min-1 mitigation locked (dmg 1 vs iceResistance 1 → 1).
+- Decoupling verified: cyber alarm raises emit nothing on the meat bus and
+  leave the meat latch untouched; the cyber alarm cadence ticks once per
+  meat round advance (proves the single-TurnQueue wiring).
+- **Noted for later**: probes default `FACTION.CORP`. The `cyber-data-spike`
+  recipe locks principals to corp, so this matches `run.hostileFaction`
+  today — but a future rival-principal cyber recipe would leave ICE AP
+  unrefreshed (the queue ticks PLAYER/RIVAL only). Revisit when a second
+  cyber recipe lands (stamp `hostileFaction` onto ICE at `jackIn`, or
+  validate at build).
+- Tests: 9 in `ProbeIce.test.ts`. Failing-first verified; suite 1646 green.
+
 ## Architecture decisions (approved plan)
 
 ### Cyber layer model — `CyberspaceLayer` owned by `Run`, single `TurnQueue`, both worlds tick

From dd17cb83285d3198b32b8046b376a1f4419674a4 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Thu, 11 Jun 2026 12:04:07 -0700
Subject: [PATCH 25/55] =?UTF-8?q?P3.M3.6=20S7:=20render/input=20swap=20?=
 =?UTF-8?q?=E2=80=94=20the=20shell=20enters=20the=20grid?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cyber tileset axis in palette (glyphForTile tileset param, throws on
unknown), buildFrame/AsciiRenderer threading, RAM-labeled avatar HUD,
// THE GRID // location line, active-view seam (run.activeWorld /
activeActor) through applyIntent + look/describe + vision, and the
chained dual-phase corp turn (meat hostiles, then ICE) locked by
dualPhaseTurn.test.ts shared-rng order assertions.

kaizen.md: index.ts complexity findings recorded for post-M3 cleanup
(ShellScene casts, statusLine extraction, listener rewire dedupe,
bus listener-order coupling, active-view seam enforcement).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/kaizen.md                              |  13 +
 index.ts                                    | 419 ++++++++++++++++----
 src/input/applyIntent.ts                    |  24 +-
 src/render/combatHud.ts                     |   6 +-
 src/render/frame.ts                         |  25 +-
 src/render/palette.ts                       |  29 +-
 tests/unit/game/cyber/dualPhaseTurn.test.ts | 186 +++++++++
 tests/unit/render/cyberTileset.test.ts      |  77 ++++
 8 files changed, 683 insertions(+), 96 deletions(-)
 create mode 100644 tests/unit/game/cyber/dualPhaseTurn.test.ts
 create mode 100644 tests/unit/render/cyberTileset.test.ts

diff --git a/docs/kaizen.md b/docs/kaizen.md
index 7aa124b..bead4cd 100644
--- a/docs/kaizen.md
+++ b/docs/kaizen.md
@@ -38,6 +38,19 @@ When an item lands, gets reclassified, or develops new context, edit it in place
   - **Clean constraints as modifiers:** no alarm, no civilian harm, no kills, under turn budget. Treat as bonus constraints / payout modifiers unless a future design proves one should be a base objective kind.
   - **Breach / demolition target:** place or detonate a breach charge at an authored wall or target. Mechanically adjacent to deny/destroy; Phase 2.5 M7 covers breaching foundations.
   - **Cyberspace / data-layer objectives:** jack in, slice data nodes, open locks, defeat or avoid ICE. Likely Phase 3 dual-layer objective work rather than plain Meatspace recipes.
+- **index.ts complexity:** Introduction of the Cyberspace layer pushed complexity of the core UI shell over a reasonable limit; candidates for cleanup / simplification identified:
+  - **ShellScene = Campaign | Run union** forces isRun() casts everywhere — ~15 sites narrow-and-cast; a SceneView
+  interface both classes implement would delete most of them.
+  - **statusLine()** is a ~110-line HTML string builder mixing a11y, alarm tags, hub identity, corp mood, and
+  activity-row layout — prime extraction target (pure function over a snapshot, like combatHud.ts already does).
+  - **Four duplicated attachVisionListener/Animation/Rep/Cyber blocks at every scene transition** — one
+  rewireSceneListeners() would collapse them and prevent the "forgot to add the new attach call" failure mode (I
+  had to touch all four for S7).
+  - **Listener-order coupling on the bus**: the shell's JACK_IN/JACK_OUT handlers depend on Run subscribing first
+  (true today, enforced nowhere). A bus.on(..., {priority}) or explicit shell callbacks on Run would make it
+  structural.
+  - **run.world/run.player direct reads remain legal** — the new active-view seam is convention, not
+  compiler-enforced; a lint rule or accessor deprecation would lock it in.
 
 ## ◇ Monitored
 
diff --git a/index.ts b/index.ts
index 21aeced..e965395 100644
--- a/index.ts
+++ b/index.ts
@@ -51,6 +51,9 @@ import {
 import { EVENT, alarmPayloadTriggersRepPenalty } from '/src/game/events.js';
 import { VisionField } from '/src/game/Vision.js';
 import { describeTileAt } from '/src/game/describe.js';
+import type { CyberspaceLayer } from '/src/game/cyber/CyberspaceLayer.js';
+import type { World } from '/src/game/World.js';
+import type { TilesetId } from '/src/render/palette.js';
 import { AsciiRenderer } from '/src/render/AsciiRenderer.js';
 import { CrtFilter } from '/src/render/CrtFilter.js';
 import {
@@ -251,6 +254,14 @@ function maybeDevFault(site: string): void {
 
 let campaign: Campaign | null = null;
 let vision = new VisionField();
+/**
+ * P3.M3.6: the cyber grid's own fog field — `vision` stays Meatspace-truth
+ * for the body (aftermath visibility, meat corpse memory) while the avatar
+ * sees through this one. Rebuilt (and re-seeded from `layer.mapSeen`) every
+ * time the cyber listeners attach.
+ */
+let cyberVision = new VisionField();
+let cyberUnsubs: (() => void)[] = [];
 let visionMoveUnsub: (() => void) | null = null;
 let repUnsubs: (() => void)[] = [];
 let civilianHarmsThisJob = 0;
@@ -420,6 +431,40 @@ function isRun(scene: ShellScene): scene is Run {
   return 'archetype' in scene;
 }
 
+// ---------------------------------------------------------------------------
+// P3.M3.6 — the active-view seam. While the Decker is jacked in, every
+// presentation/input surface looks *through* these helpers at the cyber
+// layer; in Meatspace (and the Hub) they are identity functions. This is the
+// single place the world/actor/vision/tileset swap happens — shell code
+// below should never reach for `run.world`/`run.player` directly on a
+// surface the player is looking at.
+// ---------------------------------------------------------------------------
+
+function cyberLayerOf(scene: ShellScene | null): CyberspaceLayer | null {
+  if (!scene || !isRun(scene)) return null;
+  return scene.cyberspace?.phase === 'active' ? scene.cyberspace.layer : null;
+}
+
+function isJackedIn(scene: ShellScene | null): boolean {
+  return cyberLayerOf(scene) !== null;
+}
+
+function activeWorldOf(scene: ShellScene): World | null {
+  return cyberLayerOf(scene)?.world ?? scene.world;
+}
+
+function activeActorOf(scene: ShellScene): Entity | null {
+  return cyberLayerOf(scene)?.avatar ?? scene.player;
+}
+
+function activeVisionField(scene: ShellScene | null): VisionField {
+  return isJackedIn(scene) ? cyberVision : vision;
+}
+
+function activeTileset(scene: ShellScene | null): TilesetId {
+  return isJackedIn(scene) ? 'cyber' : 'meat';
+}
+
 // ---------------------------------------------------------------------------
 // Boot
 // ---------------------------------------------------------------------------
@@ -734,6 +779,7 @@ function enterHubAndRender() {
   attachVisionListener();
   attachAnimationListeners();
   attachRepListeners();
+  attachCyberListeners();
   recomputeVision();
   renderShell();
   if (!presentHubRevealIfAny('HUB — Curator has contracts when you are adjacent [Space].')) {
@@ -861,6 +907,7 @@ function onBriefingDeploy(evt: Event) {
   attachVisionListener();
   attachAnimationListeners();
   attachRepListeners();
+  attachCyberListeners();
   recomputeVision();
   flash('JACKED IN. Reach the exit tile (¤) before the corpos drop you.');
   renderShell();
@@ -1102,6 +1149,14 @@ function applyUseConsumableResult(
  */
 function resolveAimedUseItem(aim: { dx: number; dy: number }, run: Run): void {
   if (!run.world || !run.player) throw new Error('[shell] resolveAimedUseItem: no scene');
+  // P3.M3.6: items are meat gear; the inventory gate blocks new aims while
+  // jacked in, but an aim pending across the jack-in interact must also die.
+  if (isJackedIn(run)) {
+    pendingAimItemId = null;
+    flash('USE FAILED: jacked in — your gear is back in Meatspace.');
+    resetInputModes();
+    return;
+  }
   const itemId = pendingAimItemId;
   if (!itemId) {
     // Direction press arrived without a stashed item — shouldn't be reachable
@@ -1291,6 +1346,7 @@ function resumeCampaign(record: CampaignSnapshot | unknown) {
     attachVisionListener();
     attachAnimationListeners();
     attachRepListeners();
+    attachCyberListeners();
     recomputeVision();
     if (campaign.activeRun?.state === RUN_STATE.BRIEFING && campaign.activeRun.contract) {
       briefingEl.setContract(campaign.activeRun.contract);
@@ -1382,7 +1438,9 @@ function enterLookMode(): void {
   const run = currentScene();
   if (!run?.world || !run.player) return;
   if (lookCursor) return;
-  lookCursor = { x: run.player.x, y: run.player.y };
+  const actor = activeActorOf(run);
+  if (!actor) return;
+  lookCursor = { x: actor.x, y: actor.y };
   keyboard.mode = MODE.LOOK;
   keyboard.aimKind = null;
   if (touchPadEl.mode !== MODE.LOOK) touchPadEl.setMode(MODE.LOOK);
@@ -1406,18 +1464,23 @@ function handleLookMove(dx = 0, dy = 0): void {
   }
   const run = currentScene();
   if (!run?.world || !run.player) return;
+  // P3.M3.6: the look cursor roams whichever grid is on screen.
+  const world = activeWorldOf(run);
+  const actor = activeActorOf(run);
+  if (!world || !actor) return;
+  const fog = activeVisionField(run);
   if (!lookCursor) {
-    lookCursor = { x: run.player.x, y: run.player.y };
+    lookCursor = { x: actor.x, y: actor.y };
   }
-  const tx = Math.max(0, Math.min(run.world.grid.width - 1, lookCursor.x + dx));
-  const ty = Math.max(0, Math.min(run.world.grid.height - 1, lookCursor.y + dy));
-  if (run.state === RUN_STATE.COMBAT && !vision.hasSeen(tx, ty)) {
+  const tx = Math.max(0, Math.min(world.grid.width - 1, lookCursor.x + dx));
+  const ty = Math.max(0, Math.min(world.grid.height - 1, lookCursor.y + dy));
+  if (run.state === RUN_STATE.COMBAT && !fog.hasSeen(tx, ty)) {
     flash("You haven't seen that tile.");
     return;
   }
   lookCursor = { x: tx, y: ty };
-  const line = describeTileAt(run.world, tx, ty, {
-    vision: run.state === RUN_STATE.COMBAT ? vision : undefined,
+  const line = describeTileAt(world, tx, ty, {
+    vision: run.state === RUN_STATE.COMBAT ? fog : undefined,
     showStats: true,
   });
   if (line) flash(line);
@@ -1461,9 +1524,17 @@ function handleIntent(intent: Intent): void {
     throw new Error(`[shell] state "${run.state}" is missing playable scene wiring`);
   }
 
+  // P3.M3.6: intents drive whoever the player is being — the crew body in
+  // Meatspace, the avatar on the grid (same queue either way).
+  const intentWorld = activeWorldOf(run);
+  const intentActor = activeActorOf(run);
+  if (!intentWorld || !intentActor) {
+    throw new Error(`[shell] state "${run.state}" has no active world/actor for intents`);
+  }
+
   applyIntent(intent, {
-    world: run.world,
-    player: run.player as Parameters<typeof applyIntent>[1]['player'],
+    world: intentWorld,
+    player: intentActor as Parameters<typeof applyIntent>[1]['player'],
     queue: run.queue,
     rng: run.rng,
     // Capture the action line for the next paint(); see lastActionLine docs.
@@ -1474,7 +1545,7 @@ function handleIntent(intent: Intent): void {
       resolveAimedUseItem(aim, run as Run);
     },
     onCorpseSalvaged: entity => {
-      vision.forgetCorpse(entity);
+      activeVisionField(run).forgetCorpse(entity);
     },
     keyItems: [...(campaign?.keyItems ?? []), ...(run as Run).keyItems],
     onKeycardCollected: kc => {
@@ -1501,6 +1572,12 @@ function handleIntent(intent: Intent): void {
               flash('Inventory is only available on your turn.');
               return;
             }
+            // P3.M3.6: the avatar has no pockets — gear stays with the body
+            // until the P3.M4 simstim flip makes split control real.
+            if (isJackedIn(run)) {
+              flash('Jacked in — your meatspace gear is out of reach.');
+              return;
+            }
           }
           presentItemInventory();
           break;
@@ -1568,7 +1645,11 @@ function driveCombatTurnPipeline(run: Run, options: { resumeFromCorpSlice?: bool
     onPlayerAftermathStep: step => {
       if (degrading) return;
       const scene = currentScene();
-      if (step.type === 'breach-detonate') {
+      // P3.M3.6: aftermath is a Meatspace phase — while jacked in it still
+      // *applies*, but the canvas is showing the grid, so skip its
+      // presentation (overlays/shake/log lines).
+      const jacked = isJackedIn(scene);
+      if (step.type === 'breach-detonate' && !jacked) {
         showBreachBlastOverlay(step.charge.x, step.charge.y);
         if (scene?.player && vision.isVisible(step.charge.x, step.charge.y)) {
           triggerShake(stageEl);
@@ -1576,6 +1657,7 @@ function driveCombatTurnPipeline(run: Run, options: { resumeFromCorpSlice?: bool
         }
       }
       if (
+        !jacked &&
         scene?.player &&
         isPlayerAftermathStepLogVisible(step, (x, y) => vision.isVisible(x, y), scene.player.id)
       ) {
@@ -1660,6 +1742,51 @@ function runCorpTurn(onFinish: () => void): void {
   if (!run.world) {
     throw new Error(`[shell] cannot drive corp turn without world in state "${run.state}"`);
   }
+  // P3.M3.6: while the Decker is jacked in, the corp slice chains two
+  // driver passes — meat hostiles on the meat world (silent: the canvas is
+  // showing the grid), then ICE on the cyber world. Both consume the shared
+  // run rng in this fixed order, keeping the turn deterministic. If the meat
+  // pass flatlines the body the driver bails terminally and the ICE pass
+  // (correctly) never runs.
+  const icePass = () => {
+    if (degrading) return;
+    const layer = cyberLayerOf(currentScene());
+    if (!layer) {
+      onFinish();
+      return;
+    }
+    driveCorpTurn({
+      run: { state: run.state ?? '', world: layer.world, rng: run.rng },
+      corpFaction: FACTION.CORP,
+      paint,
+      animLock,
+      actionDelayMs: CORP_ACTION_DELAY_MS,
+      lockMarginMs: ANIMATION_DURATIONS.MUZZLE_FLASH,
+      onFinish,
+      schedule: scheduleCombatPump,
+      shouldAnimateStep: (entityId: string, step: TurnActionStep) => {
+        if (degrading) return true;
+        return isCorpTurnStepVisibleToPlayer(layer.world, layer.avatar.id, entityId, step, (x, y) =>
+          cyberVision.isVisible(x, y)
+        );
+      },
+      onStep: (entityId: string, step: TurnActionStep) => {
+        if (degrading) return;
+        const resolve = (id: string) => resolveEntityLabel(id, layer.world.entities);
+        const line = formatCorpTurnStep(resolve(entityId), step, resolve);
+        if (
+          !line ||
+          !isCorpTurnStepLogVisibleToPlayer(layer.world, layer.avatar.id, entityId, step, (x, y) =>
+            cyberVision.isVisible(x, y)
+          )
+        ) {
+          return;
+        }
+        flash(line);
+      },
+    });
+  };
+
   driveCorpTurn({
     run: {
       state: run.state ?? '',
@@ -1671,12 +1798,15 @@ function runCorpTurn(onFinish: () => void): void {
     animLock,
     actionDelayMs: CORP_ACTION_DELAY_MS,
     lockMarginMs: ANIMATION_DURATIONS.MUZZLE_FLASH,
-    onFinish,
+    onFinish: icePass,
     schedule: scheduleCombatPump,
     shouldAnimateStep: (entityId: string, step: TurnActionStep) => {
       if (degrading) return true;
       const scene = currentScene();
       if (!scene?.world || !scene.player) return true;
+      // Jacked in: meat steps still *apply*, but the canvas is showing the
+      // grid — drain them silently rather than pacing invisible frames.
+      if (isJackedIn(scene)) return false;
       return isCorpTurnStepVisibleToPlayer(scene.world, scene.player.id, entityId, step, (x, y) =>
         vision.isVisible(x, y)
       );
@@ -1685,6 +1815,7 @@ function runCorpTurn(onFinish: () => void): void {
       if (degrading) return;
       const scene = currentScene();
       if (!scene?.world || !scene.player) return;
+      if (isJackedIn(scene)) return;
       const resolve = (id: string) => resolveEntityLabel(id, scene.world!.entities);
       const line = formatCorpTurnStep(resolve(entityId), step, resolve);
       if (
@@ -1797,38 +1928,49 @@ function handleCombatInteract(): void {
   const run = campaign.activeRun;
   if (!run || !run.player) return;
   if (!run.world) throw new Error('[shell] active combat run has no world');
-  const player = run.player;
-  if (!player.inventory) throw new Error('[shell] combat player inventory is not initialised');
-  // Scan the 8 neighbours plus the player's own tile for lootable corpses.
-  for (let dy = -1; dy <= 1; dy++) {
-    for (let dx = -1; dx <= 1; dx++) {
-      const tx = player.x + dx;
-      const ty = player.y + dy;
-      const entity = run.world.lootableCorpseAt(tx, ty);
-      if (entity && !entity.alive && entity.loot && totalSalvage(entity.loot.salvage) > 0) {
-        if (!player.canAfford(AP_COST.INTERACT)) {
-          flash('Insufficient AP to loot.');
+  // P3.M3.6: interact targets the world the player is being in — meat props
+  // for the body, data nodes / the exit port for the avatar.
+  const world = activeWorldOf(run);
+  const player = activeActorOf(run);
+  if (!world || !player) throw new Error('[shell] combat interact requires an active world/actor');
+  // Corpse looting needs pockets — the avatar (no inventory) skips straight
+  // to interactables. ICE leaves no salvage in this slice.
+  const inventory = 'inventory' in player ? (player as Crew).inventory : null;
+  if (!isJackedIn(run) && !inventory) {
+    throw new Error('[shell] combat player inventory is not initialised');
+  }
+  if (inventory) {
+    // Scan the 8 neighbours plus the player's own tile for lootable corpses.
+    for (let dy = -1; dy <= 1; dy++) {
+      for (let dx = -1; dx <= 1; dx++) {
+        const tx = player.x + dx;
+        const ty = player.y + dy;
+        const entity = world.lootableCorpseAt(tx, ty);
+        if (entity && !entity.alive && entity.loot && totalSalvage(entity.loot.salvage) > 0) {
+          if (!player.canAfford(AP_COST.INTERACT)) {
+            flash('Insufficient AP to loot.');
+            return;
+          }
+          // Typed salvage — show pickup total + post-pickup compact wallet.
+          const amount = totalSalvage(entity.loot.salvage);
+          (player as Crew).collectSalvage(world, entity);
+          activeVisionField(run).forgetCorpse(entity);
+          flash(
+            `Salvaged +${amount} — carrying ${formatSalvageCompact(inventory.salvage)}. ${player.ap} AP left.`
+          );
+          paint();
+          if (player.ap === 0) {
+            advanceTurn();
+          }
           return;
         }
-        // Typed salvage — show pickup total + post-pickup compact wallet.
-        const amount = totalSalvage(entity.loot.salvage);
-        player.collectSalvage(run.world, entity);
-        vision.forgetCorpse(entity);
-        flash(
-          `Salvaged +${amount} — carrying ${formatSalvageCompact(player.inventory.salvage)}. ${player.ap} AP left.`
-        );
-        paint();
-        if (player.ap === 0) {
-          advanceTurn();
-        }
-        return;
       }
     }
   }
 
-  const interactable = run.world.adjacentInteractables(player)[0];
+  const interactable = world.adjacentInteractables(player)[0];
   if (interactable) {
-    const result = interactable.interact(run.world, player);
+    const result = interactable.interact(world, player);
     flash(result.message);
     if (
       result.ok &&
@@ -1900,6 +2042,7 @@ function onNewRunRequested(): void {
   attachVisionListener();
   attachAnimationListeners();
   attachRepListeners();
+  attachCyberListeners();
   recomputeVision();
   renderShell();
 }
@@ -1970,6 +2113,68 @@ function attachAnimationListeners(): void {
     run.bus.on(EVENT.DOOR_UNLOCKED, payload => {
       const { label = 'Door' } = (payload ?? {}) as DoorUnlockPayload;
       flash(`${label} unlocked — passage open.`);
+    }),
+    // P3.M3.6: Run's own JACK_IN listener (wired at enterCombat, so it runs
+    // first) has already spawned the layer by the time this fires — the
+    // shell just swaps its presentation onto the grid.
+    run.bus.on(EVENT.JACK_IN, () => {
+      attachCyberListeners();
+      if (!isJackedIn(currentScene())) return;
+      recomputeVision();
+      flash('LINK ESTABLISHED — entering // THE GRID //.');
+      paint();
+    })
+  );
+}
+
+/**
+ * P3.M3.6: subscribe avatar-side feedback to the *cyber* bus while a layer
+ * is active — combat shake/flash for the avatar, muzzle flashes for ICE
+ * strikes, corpse memory in `cyberVision`, vision refresh on movement, and
+ * the jack-out swap back to Meatspace. No-op (and cleanup) when dormant or
+ * resolved. Called from every scene (re)wiring site plus the JACK_IN hook,
+ * so a mid-jack-in resume re-attaches automatically.
+ */
+function attachCyberListeners(): void {
+  for (const off of cyberUnsubs) off();
+  cyberUnsubs = [];
+  const run = currentScene();
+  const layer = cyberLayerOf(run);
+  if (!run || !layer) return;
+  cyberVision = new VisionField();
+  cyberVision.restoreSeen(layer.mapSeenKeys());
+  cyberUnsubs.push(
+    layer.bus.on(EVENT.ENTITY_MOVED, () => recomputeVision()),
+    layer.bus.on(EVENT.ENTITY_DAMAGED, payload => {
+      const { target, damage = 0, killed, source } = (payload ?? {}) as EntityDamagedPayload;
+      if (target === layer.avatar && damage > 0) {
+        triggerShake(stageEl);
+        triggerDamageFlash(stageEl);
+        animLock.push(ANIMATION_DURATIONS.DAMAGE_FLASH);
+      }
+      if (source === 'melee' && target && damage > 0) {
+        const fired = runMuzzleFlash(renderer, paint, target.x, target.y);
+        if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
+      }
+      if (killed && target && cyberVision.isVisible(target.x, target.y)) {
+        cyberVision.memoriseCorpse(target);
+      }
+    }),
+    layer.bus.on(EVENT.NOISE, payload => {
+      const noise = (payload ?? {}) as NoisePayload;
+      if (noise.kind !== 'ranged') return;
+      const origin = noise.origin;
+      if (!origin) return;
+      const fired = runMuzzleFlash(renderer, paint, origin.x, origin.y);
+      if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
+    }),
+    layer.bus.on(EVENT.JACK_OUT, () => {
+      // Run.jackOut (subscribed first) has already resolved the layer.
+      for (const off of cyberUnsubs) off();
+      cyberUnsubs = [];
+      flash('LINK DROPPED — back in your body.');
+      recomputeVision();
+      paint();
     })
   );
 }
@@ -2024,12 +2229,23 @@ function attachRepListeners(): void {
 
 function recomputeVision(): void {
   const run = currentScene();
-  if (!run || !run.world || !run.player) return;
-  vision.recompute(run.world.grid, run.player, undefined, {
-    blockers: run.world.blockerKeys(),
-  });
-  if (isRun(run) && run.state === RUN_STATE.COMBAT) {
-    run.recordMapSeen(vision.visible);
+  if (!run) return;
+  // Meatspace vision stays live even while jacked in — the body still
+  // stands at the port and aftermath/corpse-memory checks read this field.
+  if (run.world && run.player) {
+    vision.recompute(run.world.grid, run.player, undefined, {
+      blockers: run.world.blockerKeys(),
+    });
+    if (isRun(run) && run.state === RUN_STATE.COMBAT) {
+      run.recordMapSeen(vision.visible);
+    }
+  }
+  const layer = cyberLayerOf(run);
+  if (layer) {
+    cyberVision.recompute(layer.world.grid, layer.avatar, undefined, {
+      blockers: layer.world.blockerKeys(),
+    });
+    layer.recordSeen(cyberVision.visible);
   }
 }
 
@@ -2098,6 +2314,9 @@ function renderShell(): void {
  */
 function currentLocationLabel(): string | undefined {
   if (!campaign) return undefined;
+  if (isJackedIn(currentScene())) {
+    return '// THE GRID //';
+  }
   if (campaign.state === CAMPAIGN_STATE.COMBAT && campaign.activeRun?.contract) {
     const { principal, site } = campaign.activeRun.contract.context;
     const siteName = site?.label ?? 'Location Unknown';
@@ -2128,19 +2347,7 @@ function buildCombatHudSnapshot(scene: ShellScene | null): CombatHudSummaryInput
             progress: scene.objectiveProgress(),
           }
         : null,
-    identity: {
-      callsign: scene.player.callsign,
-      archetype: scene.archetype,
-      stealthed: scene.player.stealthed,
-    },
-    hp: {
-      hp: scene.player.hp,
-      maxHp: scene.player.maxHp,
-    },
-    ap: {
-      ap: scene.player.ap,
-      maxAp: scene.player.maxAp,
-    },
+    ...combatHudBodyPanes(scene),
     turn: {
       currentFaction: scene.queue.currentFaction,
       turnNumber: scene.queue.turnNumber,
@@ -2148,6 +2355,36 @@ function buildCombatHudSnapshot(scene: ShellScene | null): CombatHudSummaryInput
   };
 }
 
+/**
+ * P3.M3.6: identity/HP/AP panes track whoever the player is being right now —
+ * the crew body in Meatspace, the avatar (RAM pool) on the grid.
+ */
+function combatHudBodyPanes(scene: Run): Pick<CombatHudSummaryInput, 'identity' | 'hp' | 'ap'> {
+  const layer = cyberLayerOf(scene);
+  if (layer) {
+    const avatar = layer.avatar;
+    return {
+      identity: {
+        callsign: avatar.callsign,
+        archetype: 'Avatar',
+        stealthed: avatar.stealthed,
+      },
+      hp: { hp: avatar.hp, maxHp: avatar.maxHp, label: 'RAM' },
+      ap: { ap: avatar.ap, maxAp: avatar.maxAp },
+    };
+  }
+  const player = scene.player!;
+  return {
+    identity: {
+      callsign: player.callsign,
+      archetype: scene.archetype,
+      stealthed: player.stealthed,
+    },
+    hp: { hp: player.hp, maxHp: player.maxHp },
+    ap: { ap: player.ap, maxAp: player.maxAp },
+  };
+}
+
 function buildHubHudRows(scene: ShellScene | null) {
   if (!campaign || scene?.state !== CAMPAIGN_STATE.HUB) return undefined;
   const [summary, clock] = formatHubArcStatusLines(campaign);
@@ -2183,28 +2420,35 @@ function paint(stateHint: InputState = activeInputState()): void {
     return;
   }
   if (!run || !run.world || !run.player) return;
+  // P3.M3.6: the rendered pair — meat body in Meatspace, avatar on the grid.
+  const world = activeWorldOf(run);
+  const actor = activeActorOf(run);
+  if (!world || !actor) return;
+  const jacked = isJackedIn(run);
   // Hub is a safe space — no fog of war. Vision is only meaningful during
   // combat where LOS and drone stealth detection matter.
-  const activeVision = run.state === RUN_STATE.COMBAT ? vision : undefined;
+  const activeVision = run.state === RUN_STATE.COMBAT ? activeVisionField(run) : undefined;
+  // Breach blasts are a Meatspace effect — never painted onto the grid.
   const blastOverlayKeys =
-    run.state === RUN_STATE.COMBAT && activeBreachBlastOverlayKeys.size > 0
+    run.state === RUN_STATE.COMBAT && !jacked && activeBreachBlastOverlayKeys.size > 0
       ? activeBreachBlastOverlayKeys
       : undefined;
   const principalId =
-    run.state === RUN_STATE.COMBAT
+    run.state === RUN_STATE.COMBAT && !jacked
       ? campaign?.activeRun?.contract?.context?.principal?.id
       : undefined;
-  renderer.draw(run.world, run.player, {
+  renderer.draw(world, actor, {
     vision: activeVision,
-    player: run.player,
+    player: actor,
     blastOverlayKeys,
     lookCursor,
     principalId,
+    tileset: activeTileset(run),
     locationLabel: currentLocationLabel(),
     hudRows: buildHubHudRows(run),
     combatHud: buildCombatHudSnapshot(run),
   });
-  crt.alertTint = run.state === RUN_STATE.COMBAT && run.world.alarmActive;
+  crt.alertTint = run.state === RUN_STATE.COMBAT && world.alarmActive;
   crt.apply();
   setStatus(statusLine(stateHint));
 }
@@ -2234,7 +2478,10 @@ function statusLine(state: InputState): string {
     combatA11y = `<span class="u-sr-only">Combat status: ${escapeHtml(
       formatCombatHudA11ySummary(hudSnapshot)
     )}</span>`;
-    const alarm = run.world?.alarm;
+    // P3.M3.6: alarm + hazard read from the world the player is *being in*.
+    const statusWorld = activeWorldOf(run);
+    const statusActor = activeActorOf(run);
+    const alarm = statusWorld?.alarm;
     const alertTag =
       alarm?.phase === 'alert'
         ? `<span class="alert-tag">ALERT ${alarm.holdTurnsRemaining}</span>`
@@ -2242,7 +2489,9 @@ function statusLine(state: InputState): string {
           ? `<span class="alert-tag">COOL ${alarm.cooldownTurnsRemaining}</span>`
           : '';
     const onHazard =
-      run.world && run.player && run.world.grid.tileAt(run.player.x, run.player.y) === TILE.HAZARD;
+      statusWorld &&
+      statusActor &&
+      statusWorld.grid.tileAt(statusActor.x, statusActor.y) === TILE.HAZARD;
     const hazardTag = onHazard
       ? '<span class="hazard-tag">▓ HAZARD — move or take damage</span>'
       : '';
@@ -2280,15 +2529,19 @@ function statusLine(state: InputState): string {
     run.state === RUN_STATE.COMBAT &&
     run.queue.currentFaction === run.hostileFaction
   ) {
-    if (!run.world) throw new Error('[shell] combat status requires a world');
+    const corpWorld = activeWorldOf(run);
+    if (!corpWorld) throw new Error('[shell] combat status requires a world');
+    // P3.M3.6: while jacked in, the hostile mood row reads the ICE on the
+    // grid (probes are CORP-faction regardless of the meat principal).
+    const jacked = isJackedIn(run);
     const visibleHostiles = countVisibleCorpEntities(
-      run.world.entities.values(),
-      (x: number, y: number) => vision.isVisible(x, y),
-      run.hostileFaction
+      corpWorld.entities.values(),
+      (x: number, y: number) => activeVisionField(run).isVisible(x, y),
+      jacked ? FACTION.CORP : run.hostileFaction
     );
     const body = corpTurnStatusBody(visibleHostiles, run.queue.turnNumber);
     corpToneActivityBody = body;
-    const hostileTag = run.hostileFaction.toUpperCase();
+    const hostileTag = jacked ? 'ICE' : run.hostileFaction.toUpperCase();
     ephemeral = `<span class="game-shell__activity corp"><span class="faction-tag">${hostileTag}</span> — ${body}</span>`;
   } else if (
     isRun(run) &&
@@ -2297,7 +2550,7 @@ function statusLine(state: InputState): string {
     corpToneActivityBody !== null
   ) {
     // show the last hostile-turn mood until the player acts and flushes it
-    const hostileTag = run.hostileFaction.toUpperCase();
+    const hostileTag = isJackedIn(run) ? 'ICE' : run.hostileFaction.toUpperCase();
     ephemeral = `<span class="game-shell__activity corp"><span class="faction-tag">${hostileTag}</span> — ${corpToneActivityBody}</span>`;
     corpToneActivityBody = null;
   }
@@ -2370,23 +2623,29 @@ function proximityHint(): string {
     return '';
   }
   if (run.state === RUN_STATE.COMBAT) {
-    // Loot hint: check for adjacent lootable corpses.
-    if (run.world && run.player) {
-      const p = run.player;
-      for (let dy = -1; dy <= 1; dy++) {
-        for (let dx = -1; dx <= 1; dx++) {
-          const e = run.world.lootableCorpseAt(p.x + dx, p.y + dy);
-          if (e && !e.alive && e.loot && totalSalvage(e.loot.salvage) > 0) {
-            return 'SALVAGE nearby — press [Space] to loot.';
+    // P3.M3.6: hints follow the active body — meat props for the crew,
+    // nodes/exit port for the avatar.
+    const world = activeWorldOf(run);
+    const p = activeActorOf(run);
+    const jacked = isJackedIn(run);
+    if (world && p) {
+      // Loot hint: adjacent lootable corpses (needs pockets — avatar skips).
+      if (!jacked) {
+        for (let dy = -1; dy <= 1; dy++) {
+          for (let dx = -1; dx <= 1; dx++) {
+            const e = world.lootableCorpseAt(p.x + dx, p.y + dy);
+            if (e && !e.alive && e.loot && totalSalvage(e.loot.salvage) > 0) {
+              return 'SALVAGE nearby — press [Space] to loot.';
+            }
           }
         }
       }
-      const interactable = run.world.adjacentInteractables(p)[0];
+      const interactable = world.adjacentInteractables(p)[0];
       if (interactable) {
         return `${interactable.label.toUpperCase()} nearby — press [Space] to interact.`;
       }
     }
-    if (run.exitTile && isChebyshevAdjacent(run.player, run.exitTile)) {
+    if (!jacked && run.exitTile && isChebyshevAdjacent(run.player, run.exitTile)) {
       return 'EXIT (¤) one step away.';
     }
   }
diff --git a/src/input/applyIntent.ts b/src/input/applyIntent.ts
index e5a3ccb..090decc 100644
--- a/src/input/applyIntent.ts
+++ b/src/input/applyIntent.ts
@@ -60,6 +60,7 @@ import { EVENT } from '../game/events.js';
 import { TILE } from '../game/constants.js';
 import type { KeyItem } from '../types.js';
 import type { Archetype } from '../game/archetypes/index.js';
+import type { CyberAvatar } from '../game/cyber/CyberAvatar.js';
 import type { World } from '../game/World.js';
 import type { TurnQueue } from '../game/TurnQueue.js';
 import type { Rng } from '../rng.js';
@@ -76,7 +77,13 @@ export type Intent = {
 
 export type ApplyIntentContext = {
   world: World;
-  player: Archetype;
+  /**
+   * P3.M3.6: the acting body — a crew archetype in Meatspace, the
+   * `CyberAvatar` on the grid. The avatar exposes none of the perk or
+   * inventory capabilities, so every capability-sniffed branch (`doSpecial`,
+   * loot, consumables) degrades to its existing refusal path.
+   */
+  player: Archetype | CyberAvatar;
   queue: TurnQueue;
   rng: Rng;
   log: (line: string) => void;
@@ -292,8 +299,11 @@ function collectTileLoot(ctx: ApplyIntentContext) {
     objectivePickup.secureWalkOnto(world);
     log(`> ${entityLabel(player)} secures ${objectivePickup.label}.`);
   }
-  const consumablePickup = player.alive ? world.consumablePickupAt(player.x, player.y) : null;
-  if (consumablePickup) {
+  // Capability sniff (P3.M3.6): the CyberAvatar carries no gear — pickups
+  // stay on the tile for whoever has pockets.
+  const consumablePickup =
+    'addConsumable' in player && player.alive ? world.consumablePickupAt(player.x, player.y) : null;
+  if (consumablePickup && 'addConsumable' in player) {
     player.addConsumable(consumablePickup.consumableId);
     world.removeEntity(consumablePickup.id);
     log(`> ${entityLabel(player)} picks up ${consumablePickup.label}.`);
@@ -313,8 +323,10 @@ function collectTileLoot(ctx: ApplyIntentContext) {
     log(`> ${entityLabel(player)} picks up ${keycard.label}.`);
   }
   const corpse =
-    player.inventory && player.alive ? world.lootableCorpseAt(player.x, player.y) : null;
-  if (corpse) {
+    'inventory' in player && player.inventory && player.alive
+      ? world.lootableCorpseAt(player.x, player.y)
+      : null;
+  if (corpse && 'inventory' in player) {
     const amount = totalSalvage(corpse.loot!.salvage);
     player.collectSalvage(world, corpse, { spendAp: false });
     ctx.onCorpseSalvaged?.(corpse);
@@ -432,7 +444,7 @@ function doDeploy(intent: Intent, ctx: ApplyIntentContext) {
       const turret = tech.improviseTurret(world, intent.dx!, intent.dy!);
       log(
         `> ${playerLabel} improvises ${entityLabel(turret)} at (${turret.x}, ${turret.y}) — ` +
-          `${player.inventory!.salvage.scrap} scrap left, ${player.ap} AP left.`
+          `${tech.inventory!.salvage.scrap} scrap left, ${player.ap} AP left.`
       );
       gateOnApExhausted(ctx);
       return;
diff --git a/src/render/combatHud.ts b/src/render/combatHud.ts
index 6cc2547..2429893 100644
--- a/src/render/combatHud.ts
+++ b/src/render/combatHud.ts
@@ -25,6 +25,8 @@ export type CombatHudIdentityInput = Readonly<{
 export type CombatHudVitalInput = Readonly<{
   hp: number;
   maxHp: number;
+  /** P3.M3.6: pane label — `HP` (default) in Meatspace, `RAM` on the grid. */
+  label?: string;
 }>;
 
 export type CombatHudApInput = Readonly<{
@@ -116,7 +118,7 @@ export function formatIdentityHud(identity: CombatHudIdentityInput): string {
 
 export function formatHpSegments(vitals: CombatHudVitalInput): string {
   validateCounter(vitals.hp, vitals.maxHp, 'hp', 'maxHp');
-  return `HP ${rightFilledSegments(
+  return `${vitals.label ?? 'HP'} ${rightFilledSegments(
     vitals.hp,
     vitals.maxHp,
     COMBAT_HUD_GLYPHS.HP_FILLED,
@@ -155,7 +157,7 @@ export function formatCombatHudA11ySummary(summary: CombatHudSummaryInput): stri
   const parts = [
     name,
     archetype.toUpperCase(),
-    `${summary.hp.hp} of ${summary.hp.maxHp} HP`,
+    `${summary.hp.hp} of ${summary.hp.maxHp} ${summary.hp.label ?? 'HP'}`,
     `${summary.ap.ap} of ${summary.ap.maxAp} AP`,
     turnA11yText(summary.turn),
   ];
diff --git a/src/render/frame.ts b/src/render/frame.ts
index 14181e6..dc8224e 100644
--- a/src/render/frame.ts
+++ b/src/render/frame.ts
@@ -15,7 +15,7 @@ import { Interactable } from '../game/entities/Interactable.js';
 import type { World } from '../game/World.js';
 import type { Entity } from '../game/Entity.js';
 import type { VisionField } from '../game/Vision.js';
-import type { Glyph } from './palette.js';
+import type { Glyph, TilesetId } from './palette.js';
 import { isConcealedFromPlayer, sniperAimOverlayTiles } from '../game/playerPerception.js';
 import type { FactionId, TileId } from '../game/constants.js';
 
@@ -93,6 +93,8 @@ export type BuildFrameOptions = {
   lookCursor?: { x: number; y: number } | null;
   /** Combat terrain mood — `contract.context.principal.id` when in a job. */
   principalId?: string;
+  /** P3.M3.6: which look the terrain paints with. Default `'meat'`. */
+  tileset?: TilesetId;
 };
 
 /** Sniper telegraph overlay — red crosshair composited over the target glyph. */
@@ -107,7 +109,7 @@ const BLAST_OVERLAY_GLYPH = glyphForTile(TILE.HAZARD);
  */
 export function buildFrame(world: World, camera: Camera, options: BuildFrameOptions = {}): Frame {
   const { x: cx, y: cy, width, height } = camera;
-  const { vision, blastOverlayKeys, lookCursor, player, principalId } = options;
+  const { vision, blastOverlayKeys, lookCursor, player, principalId, tileset = 'meat' } = options;
   const cells: Glyph[] = Array.from({ length: width * height });
 
   const omitEntity = (e: Entity) => player && isConcealedFromPlayer(e, player, world);
@@ -139,7 +141,15 @@ export function buildFrame(world: World, camera: Camera, options: BuildFrameOpti
 
       if (vision) {
         if (vision.isVisible(wx, wy)) {
-          cells[idx] = glyphForCell(world, entityIndex, wx, wy, blastOverlayKeys, principalId);
+          cells[idx] = glyphForCell(
+            world,
+            entityIndex,
+            wx,
+            wy,
+            blastOverlayKeys,
+            principalId,
+            tileset
+          );
         } else if (vision.hasSeen(wx, wy)) {
           // Memory pass: tile only for live entities (we don't track where
           // they are). Memorised corpses render at MEMORY_DIM so the player
@@ -154,7 +164,7 @@ export function buildFrame(world: World, camera: Camera, options: BuildFrameOpti
             cells[idx] = { char: CORPSE_GLYPH_CHAR, fg: dimColor(fg, MEMORY_DIM) };
           } else {
             const tileGlyph = dimGlyph(
-              glyphForTile(world.grid.tileAt(wx, wy) as TileId, principalId)
+              glyphForTile(world.grid.tileAt(wx, wy) as TileId, principalId, tileset)
             );
             cells[idx] = blastTerrainOverlay(wx, wy, blastOverlayKeys, tileGlyph, { dim: true });
           }
@@ -164,7 +174,7 @@ export function buildFrame(world: World, camera: Camera, options: BuildFrameOpti
         continue;
       }
 
-      cells[idx] = glyphForCell(world, entityIndex, wx, wy, blastOverlayKeys, principalId);
+      cells[idx] = glyphForCell(world, entityIndex, wx, wy, blastOverlayKeys, principalId, tileset);
     }
   }
 
@@ -207,13 +217,14 @@ function glyphForCell(
   wx: number,
   wy: number,
   blastOverlayKeys: ReadonlySet<string> | undefined,
-  principalId?: string
+  principalId?: string,
+  tileset?: TilesetId
 ): Glyph {
   const entity = entityIndex.get(`${wx},${wy}`);
   if (entity) {
     return glyphForEntityCell(entity);
   }
-  const tileGlyph = glyphForTile(world.grid.tileAt(wx, wy) as TileId, principalId);
+  const tileGlyph = glyphForTile(world.grid.tileAt(wx, wy) as TileId, principalId, tileset);
   return blastTerrainOverlay(wx, wy, blastOverlayKeys, tileGlyph);
 }
 
diff --git a/src/render/palette.ts b/src/render/palette.ts
index ebf85bf..a8e2b92 100644
--- a/src/render/palette.ts
+++ b/src/render/palette.ts
@@ -59,7 +59,34 @@ export const OOB_GLYPH = Object.freeze({ char: ' ', fg: '#000000' });
  */
 export const UNSEEN_GLYPH = Object.freeze({ char: '·', fg: '#1a1a1a' });
 
-export function glyphForTile(tile: TileId, principalId?: string): Glyph {
+/**
+ * P3.M3.6: tileset axis. The cyber grid reuses the FLOOR/WALL tile ids
+ * (passability, LOS, pathfinding, persistence untouched) and swaps the look —
+ * data-line mid-dots on deep cyan, firewall static in magenta. Principal
+ * terrain palettes are a Meatspace mood axis and never recolor the grid.
+ */
+export type TilesetId = 'meat' | 'cyber';
+
+const CYBER_TILE_GLYPH: Partial<Record<TileId, Glyph>> = {
+  [TILE.FLOOR]: { char: '·', fg: '#0e6b66' },
+  [TILE.WALL]: { char: '▒', fg: '#c23bd4' },
+};
+
+export function glyphForTile(
+  tile: TileId,
+  principalId?: string,
+  tileset: TilesetId = 'meat'
+): Glyph {
+  if (tileset === 'cyber') {
+    const cyber = CYBER_TILE_GLYPH[tile];
+    // Cyber maps are FLOOR/WALL only by construction (`buildCyberMap`); any
+    // other id reaching the cyber painter is corruption, not a style gap.
+    if (!cyber) throw new Error(`palette: tile id ${tile} has no cyber tileset glyph`);
+    return cyber;
+  }
+  if (tileset !== 'meat') {
+    throw new Error(`palette: unknown tileset "${String(tileset)}"`);
+  }
   const g = TILE_GLYPH[tile];
   if (!g) throw new Error(`palette: unknown tile id ${tile}`);
   if (!principalId) return g;
diff --git a/tests/unit/game/cyber/dualPhaseTurn.test.ts b/tests/unit/game/cyber/dualPhaseTurn.test.ts
new file mode 100644
index 0000000..9d04db1
--- /dev/null
+++ b/tests/unit/game/cyber/dualPhaseTurn.test.ts
@@ -0,0 +1,186 @@
+/**
+ * P3.M3.6 — the dual-phase corp turn: while the Decker is jacked in, the
+ * shell chains two `corpTurnDriver` passes per corp slice — meat hostiles
+ * on the meat world, then ICE on the cyber world. One shared TurnQueue
+ * gives each side exactly one AP refresh per round; the shared run rng in
+ * fixed pass order keeps the whole thing deterministic.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { Run } from '../../../../src/game/Run.js';
+import { CyberspaceLayer } from '../../../../src/game/cyber/CyberspaceLayer.js';
+import { ProbeIce } from '../../../../src/game/cyber/ProbeIce.js';
+import { JackInPoint } from '../../../../src/game/entities/JackInPoint.js';
+import { runCorpTurn } from '../../../../src/game/corpTurnDriver.js';
+import { buildCrewMember } from '../../../../src/game/archetypes/index.js';
+import { FACTION } from '../../../../src/game/constants.js';
+import { OBJECTIVES } from '../../../../src/game/hub/Curator.js';
+import { Rng } from '../../../../src/rng.js';
+import { testContractContext } from '../contractTestUtils.js';
+import type { World } from '../../../../src/game/World.js';
+import type { Entity } from '../../../../src/game/Entity.js';
+import type { TurnActionStep } from '../../../../src/types.js';
+
+const cyberContract = (seed = 12345) => ({
+  seed,
+  objective: {
+    kind: OBJECTIVES.DATA_NODE_SLICE,
+    title: 'Spike the server farm',
+    briefing: 'Jack in, slice the data node, then extract.',
+    params: { requiresCyberspace: true, count: 1 },
+  },
+  difficulty: 'standard',
+  threatCount: 1,
+  label: 'cyber test job',
+  context: testContractContext(OBJECTIVES.DATA_NODE_SLICE),
+  reward: { credits: 0, repDelta: 0 },
+});
+
+function adjacentFreeTile(world: World, target: Entity) {
+  for (let dy = -1; dy <= 1; dy++) {
+    for (let dx = -1; dx <= 1; dx++) {
+      if (dx === 0 && dy === 0) continue;
+      const x = target.x + dx;
+      const y = target.y + dy;
+      if (world.grid.inBounds(x, y) && world.grid.isPassable(x, y) && !world.entityAt(x, y)) {
+        return { x, y };
+      }
+    }
+  }
+  throw new Error(`no free tile adjacent to ${target.id}`);
+}
+
+function jackedInRun(seed = 12345): { run: Run; layer: CyberspaceLayer } {
+  const decker = buildCrewMember('decker', { x: 0, y: 0 }, new Rng(100), { id: 'crew-decker' });
+  const run = new Run({ crewMember: decker, seed });
+  run.enterBriefing(cyberContract(seed));
+  run.enterCombat();
+  const point = Array.from(run.world!.entities.values()).find(
+    e => e instanceof JackInPoint
+  ) as JackInPoint;
+  const spot = adjacentFreeTile(run.world!, point);
+  run.world!.relocateEntity(run.player!, spot.x, spot.y);
+  run.player!.refreshAp();
+  assert.equal(point.interact(run.world!, run.player!).ok, true);
+  const layer = (run.cyberspace as { phase: 'active'; layer: CyberspaceLayer }).layer;
+  return { run, layer };
+}
+
+type StepLog = { id: string; type: string }[];
+
+/** Drive one corp pass synchronously and collect the committed steps. */
+function drivePass(run: Run, world: World, faction: string): StepLog {
+  const log: StepLog = [];
+  let finished = false;
+  runCorpTurn({
+    run: { state: run.state ?? '', world, rng: run.rng },
+    corpFaction: faction,
+    paint: () => {},
+    animLock: { push: () => {} },
+    actionDelayMs: 0,
+    lockMarginMs: 0,
+    schedule: (fn: () => void) => fn(),
+    shouldAnimateStep: () => false,
+    onStep: (id: string, step: TurnActionStep) => log.push({ id, type: step.type }),
+    onFinish: () => {
+      finished = true;
+    },
+  });
+  assert.equal(finished, true, 'synchronous pass drains to onFinish');
+  return log;
+}
+
+/** One full dual-phase corp slice, the way the shell chains it. */
+function dualPhaseRound(run: Run, layer: CyberspaceLayer): { meat: StepLog; ice: StepLog } {
+  run.queue!.endTurn(run.world!); // player → corp (refreshes both corp sides)
+  const meat = drivePass(run, run.world!, run.hostileFaction);
+  const ice = drivePass(run, layer.world, FACTION.CORP);
+  run.queue!.endTurn(run.world!); // corp → player (refreshes both player sides)
+  return { meat, ice };
+}
+
+function probeIds(layer: CyberspaceLayer): Set<string> {
+  return new Set(
+    Array.from(layer.world.entities.values())
+      .filter(e => e instanceof ProbeIce)
+      .map(e => e.id)
+  );
+}
+
+// --- isolation -----------------------------------------------------------------------
+
+test('the meat pass steps only meat hostiles; the ICE pass only probes', () => {
+  const { run, layer } = jackedInRun();
+  const probes = probeIds(layer);
+  const { meat, ice } = dualPhaseRound(run, layer);
+
+  for (const { id } of meat) {
+    assert.ok(!probes.has(id), `meat pass must not step ICE (stepped ${id})`);
+  }
+  assert.ok(ice.length > 0, 'probes patrol their rings');
+  for (const { id } of ice) {
+    assert.ok(probes.has(id), `ICE pass stepped a non-probe (${id})`);
+  }
+});
+
+// --- AP cadence ------------------------------------------------------------------------
+
+test('one AP refresh per side per round, on the single shared queue', () => {
+  const { run, layer } = jackedInRun();
+  layer.avatar.spendAp(2);
+  run.player!.spendAp(run.player!.ap);
+
+  run.queue!.endTurn(run.world!); // player → corp
+  // Corp-side refresh hit both worlds; player sides stay spent.
+  assert.equal(layer.avatar.ap, layer.avatar.maxAp - 2);
+  assert.equal(run.player!.ap, 0);
+
+  drivePass(run, run.world!, run.hostileFaction);
+  drivePass(run, layer.world, FACTION.CORP);
+  const probesSpent = Array.from(layer.world.entities.values()).filter(
+    e => e instanceof ProbeIce && e.ap < e.maxAp
+  );
+  assert.ok(probesSpent.length > 0, 'patrolling probes spent AP during the ICE pass');
+
+  run.queue!.endTurn(run.world!); // corp → player
+  assert.equal(layer.avatar.ap, layer.avatar.maxAp, 'avatar refreshed');
+  assert.equal(run.player!.ap, run.player!.maxAp, 'meat body refreshed on the same flip');
+  for (const probe of probesSpent) {
+    assert.ok(probe.ap < probe.maxAp, 'probes stay spent until the next corp flip');
+  }
+});
+
+// --- determinism -------------------------------------------------------------------------
+
+test('the dual-phase sequence is deterministic per contract seed', () => {
+  const a = jackedInRun(777);
+  const b = jackedInRun(777);
+  const roundA = dualPhaseRound(a.run, a.layer);
+  const roundB = dualPhaseRound(b.run, b.layer);
+  assert.deepEqual(roundA, roundB);
+
+  const c = jackedInRun(778);
+  const roundC = dualPhaseRound(c.run, c.layer);
+  assert.notDeepEqual(roundA, roundC);
+});
+
+// --- engagement through the pass --------------------------------------------------------
+
+test('an ICE pass with the avatar in sight yields the trace flare', () => {
+  const { run, layer } = jackedInRun();
+  const probe = Array.from(layer.world.entities.values()).find(
+    e => e instanceof ProbeIce
+  ) as ProbeIce;
+  const spot = adjacentFreeTile(layer.world, layer.avatar);
+  layer.world.relocateEntity(probe, spot.x, spot.y);
+
+  run.queue!.endTurn(run.world!);
+  drivePass(run, run.world!, run.hostileFaction);
+  const ice = drivePass(run, layer.world, FACTION.CORP);
+  assert.ok(
+    ice.some(s => s.id === probe.id && s.type === 'trace-alarm'),
+    'the adjacent probe flared a trace during its pass'
+  );
+  assert.equal(layer.world.alarmActive, true);
+});
diff --git a/tests/unit/render/cyberTileset.test.ts b/tests/unit/render/cyberTileset.test.ts
new file mode 100644
index 0000000..0cb59a3
--- /dev/null
+++ b/tests/unit/render/cyberTileset.test.ts
@@ -0,0 +1,77 @@
+/**
+ * P3.M3.6 — cyber tileset: distinct visuals on a separate *tileset axis*,
+ * not new TILE ids. The cyber grid reuses FLOOR/WALL (so passability, LOS,
+ * A*, and persistence stay untouched) and the palette swaps the look.
+ * Meat rendering must stay byte-stable when no tileset is passed.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { glyphForTile } from '../../../src/render/palette.js';
+import { buildFrame } from '../../../src/render/frame.js';
+import { Grid } from '../../../src/game/Grid.js';
+import { World } from '../../../src/game/World.js';
+import { TILE } from '../../../src/game/constants.js';
+import type { TileId } from '../../../src/game/constants.js';
+
+// --- palette ---------------------------------------------------------------------
+
+test('cyber tiles render distinct glyphs from meat', () => {
+  const meatFloor = glyphForTile(TILE.FLOOR as TileId);
+  const cyberFloor = glyphForTile(TILE.FLOOR as TileId, undefined, 'cyber');
+  const meatWall = glyphForTile(TILE.WALL as TileId);
+  const cyberWall = glyphForTile(TILE.WALL as TileId, undefined, 'cyber');
+
+  assert.equal(cyberFloor.char, '·');
+  assert.equal(cyberWall.char, '▒');
+  assert.notDeepEqual(cyberFloor, meatFloor);
+  assert.notDeepEqual(cyberWall, meatWall);
+  assert.notEqual(cyberFloor.fg, cyberWall.fg, 'floor and wall hues are distinct');
+});
+
+test('the meat tileset is the default and stays byte-stable', () => {
+  for (const tile of [TILE.FLOOR, TILE.WALL, TILE.COVER, TILE.EXIT] as TileId[]) {
+    assert.deepEqual(glyphForTile(tile, undefined, 'meat'), glyphForTile(tile));
+  }
+});
+
+test('principal terrain palettes do not recolor the cyber tileset', () => {
+  // The grid is the grid — corp moodboards belong to Meatspace.
+  const plain = glyphForTile(TILE.FLOOR as TileId, undefined, 'cyber');
+  const themed = glyphForTile(TILE.FLOOR as TileId, 'corp-helix', 'cyber');
+  assert.deepEqual(themed, plain);
+});
+
+test('an unknown tileset throws', () => {
+  assert.throws(() => glyphForTile(TILE.FLOOR as TileId, undefined, 'astral' as never), /tileset/);
+});
+
+test('non-cyber tile ids on the cyber tileset throw (FLOOR/WALL only by construction)', () => {
+  assert.throws(() => glyphForTile(TILE.COVER as TileId, undefined, 'cyber'), /cyber/);
+  assert.throws(() => glyphForTile(TILE.HAZARD as TileId, undefined, 'cyber'), /cyber/);
+});
+
+// --- frame threading ---------------------------------------------------------------
+
+function tinyWorld(): World {
+  const grid = new Grid(4, 3); // all FLOOR
+  grid.setTile(1, 1, TILE.WALL);
+  return new World(grid);
+}
+
+test('buildFrame threads the cyber tileset into terrain cells', () => {
+  const world = tinyWorld();
+  const camera = { x: 0, y: 0, width: 4, height: 3 };
+  const frame = buildFrame(world, camera, { tileset: 'cyber' });
+  assert.deepEqual(frame.cells[0], glyphForTile(TILE.FLOOR as TileId, undefined, 'cyber'));
+  assert.deepEqual(frame.cells[1 * 4 + 1], glyphForTile(TILE.WALL as TileId, undefined, 'cyber'));
+});
+
+test('buildFrame without a tileset stays byte-identical to before', () => {
+  const world = tinyWorld();
+  const camera = { x: 0, y: 0, width: 4, height: 3 };
+  const implicit = buildFrame(world, camera, {});
+  const explicit = buildFrame(world, camera, { tileset: 'meat' });
+  assert.deepEqual(explicit, implicit);
+  assert.deepEqual(implicit.cells[0], glyphForTile(TILE.FLOOR as TileId));
+});

From 3c693dcd2988ff1f6cddf4224f8e9e7aad71d794 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Thu, 11 Jun 2026 12:04:58 -0700
Subject: [PATCH 26/55] =?UTF-8?q?P3:=20The=20Score=20is=20a=20cyber=20run?=
 =?UTF-8?q?=20=E2=80=94=20DATA=5FNODE=5FSLICE=20objective?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

buildScoreContract now emits kind DATA_NODE_SLICE with
{requiresCyberspace: true, count: 1} (Rylee's call: the Score always
has a Cyberspace component, for now). P3.M1.7 tests deploy the
Decker through the living-Decker gate and lock the objective shape.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/game/Campaign.ts             | 14 +++++++-------
 tests/unit/game/Campaign.test.ts | 12 ++++++++++--
 2 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/src/game/Campaign.ts b/src/game/Campaign.ts
index a8b5ba3..17f441f 100644
--- a/src/game/Campaign.ts
+++ b/src/game/Campaign.ts
@@ -595,17 +595,22 @@ export class Campaign {
     const principal = locationContextToken(target.principal);
     const site = target.site ? locationContextToken(target.site) : undefined;
     const heatThreat = Math.min(6, 4 + this.clockHeat);
+    const objectiveKind = OBJECTIVES.DATA_NODE_SLICE;
     return {
       seed,
       mapWidth: target.mapWidth,
       mapHeight: target.mapHeight,
       objective: {
-        kind: OBJECTIVES.REACH_EXIT,
+        kind: objectiveKind,
         title: 'The Score',
         briefing: `Hit ${target.label
           .replace(/^\/\//, '')
           .replace(/\s+-\s+Score target$/i, '')
           .trim()} and extract with the crew alive.`,
+        params: {
+          requiresCyberspace: true,
+          count: 1,
+        },
       },
       difficulty: CONTRACT_DIFFICULTY.CRITICAL,
       threatCount: heatThreat,
@@ -616,12 +621,7 @@ export class Campaign {
         ...(site ? { site } : {}),
         asset: { id: 'score-target', label: 'Score target', groups: ['score'] },
         action: { id: 'score-run', label: 'run', groups: ['score'] },
-        tags: [
-          'score',
-          'meatspace',
-          `objective:${OBJECTIVES.REACH_EXIT}`,
-          `principal:${principal.id}`,
-        ],
+        tags: ['score', 'meatspace', `objective:${objectiveKind}`, `principal:${principal.id}`],
         arcStage: 'score',
         locationSiteId: target.id,
       },
diff --git a/tests/unit/game/Campaign.test.ts b/tests/unit/game/Campaign.test.ts
index 99e1390..63d4e7b 100644
--- a/tests/unit/game/Campaign.test.ts
+++ b/tests/unit/game/Campaign.test.ts
@@ -1066,8 +1066,14 @@ test('P3.M1.7: Score contract is gated to Act 3 and marks attempted on deploymen
   assert.equal(score.context.locationSiteId, 'score');
   assert.ok(score.context.tags.includes('score'));
   assert.match(score.label, /THE SCORE/);
+  // The Score is (for now) always a cyber run: DATA_NODE_SLICE end to end.
+  assert.equal(score.objective.kind, OBJECTIVES.DATA_NODE_SLICE);
+  assert.equal(score.objective.params?.requiresCyberspace, true);
+  assert.equal(score.objective.params?.count, 1);
 
-  const run = campaign.deployCrewMember(campaign.crew[0]!.id, score);
+  const decker = campaign.crew.find(m => m.archetype === 'Decker');
+  assert.ok(decker, 'Act 3 campaign should include auto-assigned Decker');
+  const run = campaign.deployCrewMember(decker!.id, score);
   assert.equal(campaign.arc.scoreAttempted, true);
   assert.equal(campaign.arcStage, 'score');
   assert.equal(run.contract?.context.locationSiteId, 'score');
@@ -1093,7 +1099,9 @@ test('P3.M1.7: completed Score contract records campaign win state', () => {
       validSite({ id: 'case-2', seed: '102', lastVisitedJob: 7, principal: scorePrincipal }),
     ],
   });
-  const run = campaign.deployCrewMember(campaign.crew[0]!.id, campaign.buildScoreContract());
+  const decker = campaign.crew.find(m => m.archetype === 'Decker');
+  assert.ok(decker, 'Act 3 campaign should include auto-assigned Decker');
+  const run = campaign.deployCrewMember(decker!.id, campaign.buildScoreContract());
   run.enterCombat();
 
   campaign.onJobEnd({ outcome: OUTCOME.EXIT, completed: true });

From 2d668bd8c565e3d328c943c4bd0f9f7d12f041a5 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Thu, 11 Jun 2026 12:13:31 -0700
Subject: [PATCH 27/55] =?UTF-8?q?P3.M3=20S7.5:=20early=20jack-out=20confir?=
 =?UTF-8?q?mation=20=E2=80=94=20the=20link=20burn=20warns=20first?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An incomplete jack-out is irreversible (LINK BURNED + objective latched
unsatisfiable) but resolved with zero warning. Run.jackOut now defers to
onJackOutRequested when the objective is incomplete (mirror of the
onAbortRequested seam; no callback → resolve immediately, same harness
posture); run.confirmJackOut() finalizes, throwing on illegal states —
unlike confirmAbort there is no legal request-voiding race, so a stale
confirm is a wiring bug. A complete jack-out never asks.

Shell: confirmation modal context 'jack-out-early' with link-burn copy;
JACK_OUT bus handler skips the Meatspace swap while the layer is still
live (deferred); completeJackOutShellSwap shared by both resolve paths.
wireRunConfirmations extracted and now also called on campaign resume —
restored runs previously lost onAbortRequested entirely, silently
skipping the abort-extraction confirm after any mid-run reload.

EntryPort success copy neutralized ("routing out…") since the port no
longer knows whether the link actually dropped.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 index.ts                              | 70 ++++++++++++++++-----
 src/game/Run.ts                       | 51 +++++++++++++++
 src/game/cyber/EntryPort.ts           |  4 +-
 tests/unit/game/cyber/jackOut.test.ts | 91 +++++++++++++++++++++++++++
 4 files changed, 201 insertions(+), 15 deletions(-)

diff --git a/index.ts b/index.ts
index e965395..e482359 100644
--- a/index.ts
+++ b/index.ts
@@ -571,6 +571,14 @@ async function boot() {
           paint();
         }
         break;
+      case 'jack-out-early': {
+        const activeRun = campaign?.activeRun;
+        if (activeRun) {
+          activeRun.confirmJackOut();
+          completeJackOutShellSwap();
+        }
+        break;
+      }
     }
   });
 
@@ -884,14 +892,8 @@ function onBriefingDeploy(evt: Event) {
     flash(`CURATOR: ${member.callsign} takes ${contract.label}. JACKING IN.`);
   }
 
-  // Wire abort confirmation so stepping on exit with an incomplete objective
-  // pops a modal instead of silently ending the run.
-  run.onAbortRequested = () => {
-    confirmationModalEl.showModal(
-      `Objective incomplete. Abort extraction?\n\nYou will lose all rewards and take a REP ${REP.ABORT_PENALTY} penalty.`,
-      'abort-run'
-    );
-  };
+  // Wire the run's confirmation callbacks (abort extraction, early jack-out).
+  wireRunConfirmations(run);
 
   // Go straight into combat — the player already reviewed the contract and
   // chose their operative in the combined briefing modal.
@@ -1333,12 +1335,40 @@ function currentScene(): ShellScene | null {
   return campaign.activeRun ?? campaign;
 }
 
+/**
+ * Wire the confirmation callbacks a Run raises mid-combat. Callbacks do not
+ * persist, so this runs at deploy AND on campaign resume — a restored run
+ * without them would silently skip both confirmations (the no-callback
+ * harness fallback).
+ */
+function wireRunConfirmations(run: Run): void {
+  // Stepping on exit with an incomplete objective pops a modal instead of
+  // silently ending the run.
+  run.onAbortRequested = () => {
+    confirmationModalEl.showModal(
+      `Objective incomplete. Abort extraction?\n\nYou will lose all rewards and take a REP ${REP.ABORT_PENALTY} penalty.`,
+      'abort-run'
+    );
+  };
+  // P3.M3 S7.5: routing out of the grid with the objective incomplete is
+  // irreversible (LINK BURNED, objective unsatisfiable) — confirm first.
+  run.onJackOutRequested = () => {
+    confirmationModalEl.showModal(
+      'Objective incomplete. Jack out anyway?\n\nThe link will burn — you cannot re-enter the grid this run.',
+      'jack-out-early'
+    );
+  };
+}
+
 function resumeCampaign(record: CampaignSnapshot | unknown) {
   try {
     campaign = restoreCampaign(record, {
       onPersist: () => handlePersist(),
       onResult: handleResult,
     });
+    if (campaign.activeRun) {
+      wireRunConfirmations(campaign.activeRun);
+    }
     if (campaign.activeRun?.state === RUN_STATE.COMBAT) {
       vision.resetFogState();
       vision.restoreSeen(campaign.activeRun.mapSeenKeys());
@@ -2169,16 +2199,28 @@ function attachCyberListeners(): void {
       if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
     }),
     layer.bus.on(EVENT.JACK_OUT, () => {
-      // Run.jackOut (subscribed first) has already resolved the layer.
-      for (const off of cyberUnsubs) off();
-      cyberUnsubs = [];
-      flash('LINK DROPPED — back in your body.');
-      recomputeVision();
-      paint();
+      // Run.jackOut (subscribed first) has either resolved the layer or, with
+      // the objective incomplete, deferred to the early-jack-out confirmation
+      // (S7.5) — the modal's confirm path completes the swap instead.
+      if (cyberLayerOf(currentScene())) return;
+      completeJackOutShellSwap();
     })
   );
 }
 
+/**
+ * S7.5: shell-side half of a finalized jack-out — drop the cyber listeners
+ * and re-present Meatspace. Reached from the JACK_OUT bus event (immediate
+ * resolve) or the `jack-out-early` modal confirmation (deferred resolve).
+ */
+function completeJackOutShellSwap(): void {
+  for (const off of cyberUnsubs) off();
+  cyberUnsubs = [];
+  flash('LINK DROPPED — back in your body.');
+  recomputeVision();
+  paint();
+}
+
 /**
  * Subscribe Rep-affecting events to the active run's bus.
  *
diff --git a/src/game/Run.ts b/src/game/Run.ts
index 36fd613..1f2ca35 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -358,6 +358,13 @@ export type RunOptions = {
    *  to finalise the abort extraction, or do nothing to let the player
    *  stay on the exit tile and keep playing. */
   onAbortRequested?: unknown;
+  /** P3.M3: called when the avatar routes out with the objective incomplete —
+   *  an irreversible step (the link burns, the objective latches
+   *  unsatisfiable). The shell should show a confirmation prompt; call
+   *  `run.confirmJackOut()` to finalize, or do nothing to keep the layer
+   *  live. No callback registered → jack out immediately (tests/harness),
+   *  matching the `onAbortRequested` posture. */
+  onJackOutRequested?: unknown;
   /** Terrain mutations from a prior visit to this location (P2.5.M7.2), replayed
    *  onto the freshly-built map in `enterCombat`. Empty/omitted for a first visit. */
   priorMutationDeltas?: unknown;
@@ -417,6 +424,7 @@ export class Run {
   onPersist: ((record: RunSnapshot) => void) | null;
   onResult: ((result: RunResult) => void) | null;
   onAbortRequested: (() => void) | null;
+  onJackOutRequested: (() => void) | null;
   _busUnsubs: (() => void)[];
 
   constructor({
@@ -426,6 +434,7 @@ export class Run {
     onPersist,
     onResult,
     onAbortRequested,
+    onJackOutRequested,
     priorMutationDeltas,
     priorKeyItems,
     priorSeenKeys,
@@ -448,6 +457,9 @@ export class Run {
     if (onAbortRequested !== undefined && typeof onAbortRequested !== 'function') {
       throw new TypeError('Run: onAbortRequested must be a function');
     }
+    if (onJackOutRequested !== undefined && typeof onJackOutRequested !== 'function') {
+      throw new TypeError('Run: onJackOutRequested must be a function');
+    }
     if (priorMutationDeltas !== undefined && !Array.isArray(priorMutationDeltas)) {
       throw new TypeError('Run: priorMutationDeltas must be an array when supplied');
     }
@@ -486,6 +498,7 @@ export class Run {
     this.onPersist = (onPersist as ((record: RunSnapshot) => void) | undefined) ?? null;
     this.onResult = (onResult as ((result: RunResult) => void) | undefined) ?? null;
     this.onAbortRequested = (onAbortRequested as (() => void) | undefined) ?? null;
+    this.onJackOutRequested = (onJackOutRequested as (() => void) | undefined) ?? null;
 
     /** @type {Array<() => void>} active bus subscriptions */
     this._busUnsubs = [];
@@ -899,6 +912,44 @@ export class Run {
     // — extraction then routes through the existing abort-confirm flow.
     const { sliced } = dataNodeProgress(layer.world);
     const objectiveComplete = sliced >= objectiveCount(this.contract);
+    // S7.5: an incomplete jack-out is irreversible — defer to the shell for
+    // confirmation when a callback is registered (the port's interact AP is
+    // already spent; a re-request after cancel costs it again). No callback
+    // → resolve immediately, the `onAbortRequested` posture.
+    if (!objectiveComplete && this.onJackOutRequested) {
+      this.onJackOutRequested();
+      return;
+    }
+    this.#finalizeJackOut(layer, objectiveComplete);
+  }
+
+  /**
+   * S7.5: finalize a deferred early jack-out after the shell confirms.
+   * Unlike `confirmAbort` (where walking off the exit tile legitimately
+   * voids the request), nothing can legally change between request and
+   * confirm — the modal blocks turn flow — so an illegal state here is a
+   * wiring bug and throws rather than silently no-oping.
+   */
+  confirmJackOut(): void {
+    if (this.state !== RUN_STATE.COMBAT || this.cyberspace?.phase !== 'active') {
+      throw new Error(
+        `Run.confirmJackOut: no jack-out pending (state ${this.state}, phase ${
+          this.cyberspace?.phase ?? 'none'
+        })`
+      );
+    }
+    if (!this.contract) {
+      throw new Error('Run.confirmJackOut: COMBAT state without a contract');
+    }
+    const layer = this.cyberspace.layer;
+    // Recompute rather than latch `false` blindly — honest if a future flow
+    // ever confirms after progress changed.
+    const { sliced } = dataNodeProgress(layer.world);
+    this.#finalizeJackOut(layer, sliced >= objectiveCount(this.contract));
+  }
+
+  /** Active → resolved: teardown, latch, LINK BURNED, autosave. */
+  #finalizeJackOut(layer: CyberspaceLayer, objectiveComplete: boolean): void {
     layer.teardown();
     this.cyberspace = { phase: 'resolved', objectiveComplete };
     // S5: the link is burned — re-jack-in refused for the rest of the run.
diff --git a/src/game/cyber/EntryPort.ts b/src/game/cyber/EntryPort.ts
index ee9cb91..2453348 100644
--- a/src/game/cyber/EntryPort.ts
+++ b/src/game/cyber/EntryPort.ts
@@ -48,6 +48,8 @@ export class EntryPort extends Interactable {
     }
     actor.spendAp(AP_COST.INTERACT);
     world.events?.emit(EVENT.JACK_OUT, { port: this, actor });
-    return { ok: true, message: `${this.label}: connection dropped — jacking out.` };
+    // Neutral copy: Run may have resolved the layer or deferred to an
+    // early-jack-out confirmation (S7.5) — the shell narrates the outcome.
+    return { ok: true, message: `${this.label}: routing out…` };
   }
 }
diff --git a/tests/unit/game/cyber/jackOut.test.ts b/tests/unit/game/cyber/jackOut.test.ts
index 8a5066f..1f1f29a 100644
--- a/tests/unit/game/cyber/jackOut.test.ts
+++ b/tests/unit/game/cyber/jackOut.test.ts
@@ -11,6 +11,7 @@ import assert from 'node:assert/strict';
 
 import { Run } from '../../../../src/game/Run.js';
 import { CyberspaceLayer } from '../../../../src/game/cyber/CyberspaceLayer.js';
+import { DataNode } from '../../../../src/game/cyber/DataNode.js';
 import { JackInPoint } from '../../../../src/game/entities/JackInPoint.js';
 import { snapshot, restore } from '../../../../src/game/persistence.js';
 import { buildCrewMember } from '../../../../src/game/archetypes/index.js';
@@ -83,6 +84,18 @@ function routeOut(layer: CyberspaceLayer): void {
   assert.equal(layer.port.interact(layer.world, layer.avatar).ok, true);
 }
 
+/** Slice every node in the layer (standard difficulty 2 vs decker intrusion 2 → one pass each). */
+function sliceAllNodes(layer: CyberspaceLayer): void {
+  for (const entity of Array.from(layer.world.entities.values())) {
+    if (!(entity instanceof DataNode)) continue;
+    const spot = adjacentFreeTile(layer.world, entity);
+    layer.world.relocateEntity(layer.avatar, spot.x, spot.y);
+    layer.avatar.refreshAp();
+    assert.equal(entity.interact(layer.world, layer.avatar).ok, true);
+    assert.equal(entity.sliced, true, 'standard node slices in one pass at base intrusion');
+  }
+}
+
 function portRecord(record: RunSnapshot): RunEntitySnapshot {
   const rec = record.entities.find(e => e.archetype === 'jack-in-point');
   assert.ok(rec, 'snapshot carries the jack-in point');
@@ -140,6 +153,84 @@ test('burn() on an unlinked port is corrupt state and throws', () => {
   assert.throws(() => point.burn(), /link/i);
 });
 
+// --- early jack-out confirmation (P3.M3 S7.5) -----------------------------------------
+//
+// An incomplete jack-out is irreversible — the link burns and the objective
+// latches unsatisfiable. With `onJackOutRequested` registered, Run defers to
+// the shell instead of resolving; `confirmJackOut()` finalizes. No callback
+// (tests/harness) → resolve immediately, the `onAbortRequested` posture —
+// locked by the LINK BURNED tests above, which route out with no callback.
+
+test('Run rejects a non-function onJackOutRequested', () => {
+  assert.throws(
+    () => new Run({ crewMember: makeDecker(), seed: 1, onJackOutRequested: 'nope' }),
+    TypeError
+  );
+});
+
+test('incomplete jack-out defers to onJackOutRequested — layer stays live, link unburned', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  let requests = 0;
+  run.onJackOutRequested = () => requests++;
+
+  routeOut(layer);
+  assert.equal(requests, 1, 'shell asked exactly once');
+  assert.equal(run.cyberspace?.phase, 'active', 'layer stays live pending confirmation');
+  assert.equal(meatPort(run).burned, false, 'deferred request does not burn the link');
+});
+
+test('confirmJackOut finalizes the deferred jack-out: resolved, incomplete, burned', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  run.onJackOutRequested = () => {};
+  routeOut(layer);
+
+  run.confirmJackOut();
+  assert.equal(run.cyberspace?.phase, 'resolved');
+  assert.equal(
+    (run.cyberspace as { objectiveComplete?: boolean }).objectiveComplete,
+    false,
+    'early jack-out latches the objective unsatisfiable'
+  );
+  assert.equal(meatPort(run).burned, true);
+});
+
+test('complete objective jacks out immediately — no confirmation requested', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  let requests = 0;
+  run.onJackOutRequested = () => requests++;
+
+  sliceAllNodes(layer);
+  routeOut(layer);
+  assert.equal(requests, 0, 'a clean jack-out never asks');
+  assert.equal(run.cyberspace?.phase, 'resolved');
+  assert.equal((run.cyberspace as { objectiveComplete?: boolean }).objectiveComplete, true);
+});
+
+test('confirmJackOut with no jack-out pending throws (dormant and resolved)', () => {
+  const run = combatRun();
+  assert.equal(run.cyberspace?.phase, 'dormant');
+  assert.throws(() => run.confirmJackOut(), /pending/);
+
+  const layer = jackIn(run);
+  routeOut(layer); // no callback → resolves immediately
+  assert.equal(run.cyberspace?.phase, 'resolved');
+  assert.throws(() => run.confirmJackOut(), /pending/);
+});
+
+test('a pending jack-out confirmation persists as a live layer', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  run.onJackOutRequested = () => {};
+  routeOut(layer);
+
+  const { run: restored } = restore(structuredClone(snapshot(run)));
+  assert.equal(restored.cyberspace?.phase, 'active', 'nothing resolved until the shell confirms');
+  assert.equal(meatPort(restored).burned, false);
+});
+
 // --- persistence ----------------------------------------------------------------------
 
 test('the burned latch round-trips and the restored port stays dead', () => {

From f35cf258353dea6c86664de3aa591d3947ed6263 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Thu, 11 Jun 2026 12:16:40 -0700
Subject: [PATCH 28/55] =?UTF-8?q?P3.M3=20plan:=20S7/S7.5=20shipped,=20S8?=
 =?UTF-8?q?=20wrap-up=20=E2=80=94=20first=20playable=20slice=20complete?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Progress rows + implementation notes for the render/input swap and the
early jack-out confirmation; scope decision #5 recorded (the Score is
always a cyber run). phase-3-plan.md M3 status: first playable slice
shipped, milestone open for Spark/Guardian ICE.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/phase-3-cyberspace-plan.md | 79 ++++++++++++++++++++++++++++++++-
 docs/phase-3-plan.md            | 11 ++++-
 2 files changed, 86 insertions(+), 4 deletions(-)

diff --git a/docs/phase-3-cyberspace-plan.md b/docs/phase-3-cyberspace-plan.md
index b61de11..54d5b58 100644
--- a/docs/phase-3-cyberspace-plan.md
+++ b/docs/phase-3-cyberspace-plan.md
@@ -21,6 +21,11 @@ the effort can be resumed cold.
    intrusion strength = slice progress per interact, ICE resistance =
    `damageReduction` (existing min-1 mitigation in `Combat.ts`). Persisted and
    validated in both crew persistence paths.
+5. **The Score is always a cyber run** (recorded 2026-06-11, Rylee):
+   `buildScoreContract` emits `DATA_NODE_SLICE` with
+   `{requiresCyberspace: true, count: 1}` — for now; revisit if a
+   meat-only Score variant is ever wanted. Deploy goes through the
+   living-Decker gate; objective shape locked in the P3.M1.7 tests.
 
 TDD throughout; malformed persisted state throws (no silent fallbacks).
 Commits land **per green slice** (user-approved).
@@ -35,8 +40,10 @@ Commits land **per green slice** (user-approved).
 | **S4 — P3.M3.4 Data node objective** | ✅ Done | `3923149` |
 | **S5 — Voluntary jack-out (M4.6 pull-forward)** | ✅ Done | `fab3bcb` |
 | **S6 — P3.M3.5 Probe ICE** | ✅ Done | `0a46878` |
-| **S7 — P3.M3.6 Render/input swap + shell ICE phase** | 🔲 Planned | — |
-| **S8 — Docs + wrap-up** | 🔲 Planned | — |
+| **S7 — P3.M3.6 Render/input swap + shell ICE phase** | ✅ Done | `dd17cb8` |
+| **— Score → cyber (scope decision #5)** | ✅ Done | `3c693dc` |
+| **S7.5 — Early jack-out confirmation** | ✅ Done | `2d668bd` |
+| **S8 — Docs + wrap-up** | ✅ Done | — |
 
 ### S1 implementation notes (shipped)
 
@@ -260,6 +267,74 @@ Commits land **per green slice** (user-approved).
   validate at build).
 - Tests: 9 in `ProbeIce.test.ts`. Failing-first verified; suite 1646 green.
 
+### S7 implementation notes (shipped)
+
+- `palette.ts` — `TilesetId = 'meat' | 'cyber'` axis; `CYBER_TILE_GLYPH`
+  (FLOOR `·` deep cyan `#0e6b66`, WALL `▒` magenta `#c23bd4`).
+  `glyphForTile(tile, principalId?, tileset?)` throws on an unknown tileset
+  *and* on a non-FLOOR/WALL tile reaching the cyber painter (cyber maps are
+  FLOOR/WALL-only by construction — corruption, not a style gap). Principal
+  terrain palettes are a Meatspace mood axis and never recolor the grid.
+- `frame.ts` — `BuildFrameOptions.tileset` (default `'meat'`) threaded
+  through `buildFrame`/`glyphForCell`; `combatHud.ts` — vitals pane label
+  axis (`HP` default, `RAM` on the grid).
+- `applyIntent.ts` — `ApplyIntentContext.player` widened to
+  `Archetype | CyberAvatar`; the avatar exposes no perk/inventory
+  capabilities, so every capability-sniffed branch (`doSpecial`, corpse
+  loot, consumable pickup) degrades to its existing refusal path.
+- `index.ts` — active-view seam (`run.activeWorld`/`run.activeActor`)
+  through vision, paint, look/describe, touch, and statusLine (location
+  reads `// THE GRID //`); module-level `cyberVision = new VisionField()`;
+  shell `JACK_IN`/`JACK_OUT` handlers depend on Run subscribing first
+  (recorded in kaizen — listener-order coupling); `attachCyberListeners`
+  called at every scene (re)wiring site plus the `JACK_IN` hook so a
+  mid-cyber resume re-attaches automatically.
+- **Dual-phase corp turn**: while jacked in, the corp slice chains two
+  `corpTurnDriver` passes — meat hostiles on the meat world (silent: the
+  canvas shows the grid), then ICE on `layer.world` — consuming the shared
+  `run.rng` in that fixed order. Body flatlined during the meat pass →
+  driver bails terminally and the ICE pass never runs.
+- Tests: `dualPhaseTurn.test.ts` (shared-rng order/determinism lock),
+  `cyberTileset.test.ts` (glyph table + throw matrix). kaizen.md gained the
+  index.ts complexity findings (ShellScene casts, statusLine extraction,
+  listener rewire dedupe, listener-order coupling, seam enforcement).
+
+### S7.5 implementation notes (shipped)
+
+- Gap found in Rylee's S7 smoke: jacking out early resolved instantly —
+  an **irreversible** step (LINK BURNED + objective latched unsatisfiable)
+  with zero warning, unlike the exit-abort flow.
+- `Run.onJackOutRequested` (ctor-validated, mirror of `onAbortRequested`):
+  `jackOut()` with the objective **incomplete** defers to the callback —
+  layer stays live, link unburned, nothing persisted; no callback
+  registered → resolve immediately (tests/harness posture). A complete
+  jack-out never asks. The port's interact AP is spent either way; a
+  re-request after cancel costs it again.
+- `run.confirmJackOut()` finalizes (teardown → resolved latch → burn →
+  autosave, shared `#finalizeJackOut`). **Throws** on illegal states —
+  unlike `confirmAbort`'s no-op there is no legal request-voiding race
+  (the modal blocks turn flow), so a stale confirm is a wiring bug.
+- Shell: modal context `jack-out-early` with link-burn copy;
+  `completeJackOutShellSwap()` shared by the immediate path (bus handler,
+  which now skips while the layer is still live) and the confirmed path.
+  `wireRunConfirmations(run)` extracted and called at deploy **and**
+  campaign resume — fixes a latent bug where a restored run lost
+  `onAbortRequested` entirely, silently skipping the abort confirm after
+  any mid-run reload.
+- `EntryPort` success copy neutralized (`routing out…`) — the port no
+  longer knows whether the link actually dropped.
+- Tests: +6 in `jackOut.test.ts` (defer/confirm matrix, complete-objective
+  immediacy, illegal-state throws, pending-confirmation persistence as a
+  live layer). Suite 1663 green.
+
+### S8 wrap-up
+
+- P3.M3 milestone status in `phase-3-plan.md` updated: first playable
+  slice shipped end-to-end; milestone stays open for Spark/Guardian ICE
+  (scope decision #1) and the deferred follow-ups noted in S6
+  (ICE faction stamping) and kaizen (index.ts cleanup).
+- Browser re-smoke of the S7.5 confirm flow: pending (Rylee).
+
 ## Architecture decisions (approved plan)
 
 ### Cyber layer model — `CyberspaceLayer` owned by `Run`, single `TurnQueue`, both worlds tick
diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index bff337b..0af95cb 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -43,7 +43,7 @@ A new **player archetype** recruited mid-campaign (late Act 1 / start of Act 2),
 |---|---|
 | P3.M1 — Campaign arc structure | ✅ Done |
 | P3.M2 — The Decker archetype | ✅ Done |
-| P3.M3 — Cyberspace grid + ICE | 🔲 Planned |
+| P3.M3 — Cyberspace grid + ICE | 🟡 First playable slice shipped (Spark/Guardian ICE open) |
 | P3.M4 — Simstim flip (dual-deploy) | 🔲 Planned |
 | P3.M5 — The Score (climactic mission) | 🔲 Planned |
 | P3.M6 — Chronicle (campaign narrative memory) | 🔲 Planned |
@@ -198,7 +198,14 @@ Neural degradation is deferred until Cyberspace is fun enough to deserve a jack-
 
 ---
 
-### P3.M3 — Cyberspace grid + ICE 🔲
+### P3.M3 — Cyberspace grid + ICE 🟡
+
+> **Status (2026-06-11):** the first playable slice (M3.1–M3.6, plus voluntary
+> jack-out pulled forward from M4.6 and an early-jack-out confirmation) is
+> shipped end-to-end on `3.0-cyberspace` — see
+> [phase-3-cyberspace-plan.md](phase-3-cyberspace-plan.md) for slice notes and
+> recorded scope decisions. The milestone stays open for **Spark and Guardian
+> ICE**. The Score contract is now always a cyber run (scope decision #5).
 
 **Depends on:** P3.M2 (Decker as the Cyberspace avatar). Can prototype grid mechanics independently.
 

From 8c56fc0ba6ba8d8d123657ab4ae8654b9c8b0e63 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Sun, 14 Jun 2026 12:09:38 -0700
Subject: [PATCH 29/55] cyberspace tuning

---
 components/ContractSelect.ts                  |   7 +-
 components/CrashDump.ts                       |  67 +----
 components/GameOver.ts                        | 179 +++++++-----
 components/RunBriefing.ts                     |   2 +-
 docs/kaizen.md                                |   7 +-
 docs/phase-2-plan.md                          |   2 +-
 docs/phase-2.6-plan.md                        |   2 +-
 docs/phase-3-cyberspace-plan.md               |  10 +-
 docs/phase-3-plan.md                          |  41 ++-
 index.ts                                      | 275 +++++++++---------
 src/DataStore.ts                              |  51 +++-
 src/game/Campaign.ts                          |  82 +++++-
 src/game/campaignSummary.ts                   | 236 +++++++++++++++
 src/game/cyber/CyberAvatar.ts                 |  18 +-
 src/game/cyber/ProbeIce.ts                    |   5 +-
 src/input/applyIntent.ts                      |  86 ++++--
 src/types.ts                                  |  26 +-
 sw-core.js                                    |   1 +
 sw-dev.js                                     |   2 +-
 sw.js                                         |   2 +-
 tests/unit/DataStore.test.ts                  |  66 +++++
 tests/unit/game/Campaign.test.ts              | 188 ++++++++++++
 tests/unit/game/campaignSummary.test.ts       | 151 ++++++++++
 tests/unit/game/cyber/ProbeIce.test.ts        |  32 +-
 .../unit/game/cyber/cyberPersistence.test.ts  |  22 ++
 tests/unit/input/applyIntent.test.ts          |  72 +++++
 26 files changed, 1268 insertions(+), 364 deletions(-)
 create mode 100644 src/game/campaignSummary.ts
 create mode 100644 tests/unit/DataStore.test.ts
 create mode 100644 tests/unit/game/campaignSummary.test.ts

diff --git a/components/ContractSelect.ts b/components/ContractSelect.ts
index 676bd5f..6220fcb 100644
--- a/components/ContractSelect.ts
+++ b/components/ContractSelect.ts
@@ -385,9 +385,12 @@ function difficultyLabel(contract: Contract): string {
 }
 
 function rewardCopy(contract: Contract): string {
-  if (isScoreContract(contract)) return 'final run · no payout · campaign on the line';
+  const creditsFormatted = contract.reward.credits.toLocaleString();
+  if (isScoreContract(contract)) {
+    return `${encounterHostileCount(contract)} hostiles · Cr +${creditsFormatted} · campaign on the line`;
+  }
   const recruit = contract.reward.recruit ? ' · recruit lead' : '';
-  return `${encounterHostileCount(contract)} hostiles · Cr +${contract.reward.credits} · REP +${contract.reward.repDelta}${recruit}`;
+  return `${encounterHostileCount(contract)} hostiles · Cr +${creditsFormatted} · REP +${contract.reward.repDelta}${recruit}`;
 }
 
 function jobTitleCopy(contract: Contract): string {
diff --git a/components/CrashDump.ts b/components/CrashDump.ts
index 5ec2dd8..8c8cf41 100644
--- a/components/CrashDump.ts
+++ b/components/CrashDump.ts
@@ -1,8 +1,8 @@
 /**
  * <crash-dump> — per-job debrief overlay shown while `Run.state === RESULT`.
  * Renders run telemetry as a faux kernel-panic stack trace (DEATH setback) or a
- * clean "JACK OUT" debrief (EXIT). Score-complete campaign wins reuse the green
- * exit presentation. Terminal campaign loss uses sibling `<game-over>`.
+ * clean "JACK OUT" debrief (EXIT). All terminal campaign outcomes use sibling
+ * `<game-over>` and never pass through this per-job screen.
  *
  *   *** KERNEL PANIC ***
  *   fault:  unhandled_exception_in_meatspace
@@ -25,7 +25,7 @@
  */
 
 import { h } from '/src/domUtils.js';
-import type { GameOverCrewStub, Telemetry } from '/src/types.js';
+import type { Telemetry } from '/src/types.js';
 
 const CSS = `
 :host {
@@ -159,10 +159,6 @@ function exitTitle() {
   return '*** JACK OUT ***';
 }
 
-function scoreCompleteTitle() {
-  return '*** SCORE COMPLETE ***';
-}
-
 function deathFault() {
   return ['fault:  unhandled_exception_in_meatspace', 'addr:   0x00000@meatspace', 'trace:'].join(
     '\n'
@@ -173,34 +169,7 @@ function exitFault() {
   return ['status: exfil_successful', 'addr:   0x00000@meatspace', 'trace:'].join('\n');
 }
 
-function scoreCompleteFault() {
-  return ['status: score_extracted', 'addr:   0x00000@campaign_layer', 'trace:'].join('\n');
-}
-
-function buildScoreCompleteTraceLines(crewRoster: GameOverCrewStub[]) {
-  const survivors = crewRoster.filter(op => !op.flatlined);
-  const lead = survivors[0];
-  const lines = [
-    {
-      text: `  0x01  score::extract_success(${lead?.callsign ?? 'crew'})`,
-      tag: '<ok>',
-    },
-    { text: '  0x02  arc::score_completed()', tag: '' },
-  ];
-  if (survivors.length > 1) {
-    lines.push({
-      text: `  0x03  roster::survivors(${survivors.length})`,
-      tag: '',
-    });
-  }
-  return lines;
-}
-
 function buildTraceLines(telemetry: Telemetry) {
-  if (telemetry.outcome === 'campaign-over') {
-    return buildScoreCompleteTraceLines(telemetry.crewRoster ?? []);
-  }
-
   const archetype = telemetry.archetype ?? 'entity';
   const lastSource = telemetry.lastDamageSource ?? 'unknown';
   const attacker = telemetry.lastAttacker ?? 'unknown';
@@ -293,17 +262,11 @@ class CrashDump extends HTMLElement {
       throw new TypeError('<crash-dump>.setTelemetry requires a telemetry object');
     }
     const { outcome } = telemetry;
-    if (outcome !== 'death' && outcome !== 'exit' && outcome !== 'campaign-over') {
+    if (outcome !== 'death' && outcome !== 'exit') {
       throw new Error(`<crash-dump>: unknown outcome "${outcome}"`);
     }
-    if (outcome === 'campaign-over' && telemetry.campaignEndReason !== 'score-complete') {
-      throw new Error('<crash-dump>: campaign-over is only valid for score-complete wins');
-    }
-    if (outcome === 'campaign-over' && !Array.isArray(telemetry.crewRoster)) {
-      throw new TypeError('<crash-dump>: score-complete requires crewRoster array');
-    }
     this.#telemetry = { ...telemetry };
-    this.setAttribute('outcome', outcome === 'campaign-over' ? 'exit' : outcome);
+    this.setAttribute('outcome', outcome);
     if (this.#ready) this.#render();
   }
 
@@ -325,13 +288,9 @@ class CrashDump extends HTMLElement {
   #render() {
     if (!this.#els || !this.#telemetry) return;
     const t = this.#telemetry;
-    const isScoreWin = t.outcome === 'campaign-over';
     const isDeath = t.outcome === 'death';
 
-    if (isScoreWin) {
-      this.#els.title.textContent = scoreCompleteTitle();
-      this.#els.fault.textContent = scoreCompleteFault();
-    } else if (isDeath) {
+    if (isDeath) {
       this.#els.title.textContent = deathTitle();
       this.#els.fault.textContent = deathFault();
     } else {
@@ -357,16 +316,10 @@ class CrashDump extends HTMLElement {
     });
 
     this.#els.seedDd.textContent = hexSeed(t.seed ?? 0);
-    if (isScoreWin) {
-      this.#els.turnDd.textContent = '—';
-      this.#els.killsDd.textContent = '—';
-      this.#els.causeDd.textContent = 'Score extracted — campaign complete';
-    } else {
-      this.#els.turnDd.textContent = Number.isInteger(t.turn) ? String(t.turn) : '?';
-      this.#els.killsDd.textContent = Number.isInteger(t.kills) ? String(t.kills) : '0';
-      this.#els.causeDd.textContent = t.cause ?? (isDeath ? 'unknown' : 'exit-reached');
-    }
-    this.#els.newRunBtn.textContent = isScoreWin ? '[ NEW CAMPAIGN ]' : '[ RETURN TO HUB ]';
+    this.#els.turnDd.textContent = Number.isInteger(t.turn) ? String(t.turn) : '?';
+    this.#els.killsDd.textContent = Number.isInteger(t.kills) ? String(t.kills) : '0';
+    this.#els.causeDd.textContent = t.cause ?? (isDeath ? 'unknown' : 'exit-reached');
+    this.#els.newRunBtn.textContent = '[ RETURN TO HUB ]';
   }
 
   #emit(eventName: string, detail: Record<string, unknown> = {}) {
diff --git a/components/GameOver.ts b/components/GameOver.ts
index 1ab5419..fe06edb 100644
--- a/components/GameOver.ts
+++ b/components/GameOver.ts
@@ -1,23 +1,19 @@
 /**
- * <game-over> — full-screen terminal loss overlay. Shown when the campaign is
- * truly over: crew wipe, Score window closed, or the last operator flatlines
- * on a job. Distinct from `<crash-dump>`, which handles recoverable per-job
- * setbacks and successful exfil debriefs.
+ * <game-over> — the single terminal campaign overlay.
  *
- *   GAME OVER
- *   The Score window closed.
- *   Corp security caught up. The contract is cold…
- *   [ NEW CAMPAIGN ]
+ * Both outcomes consume the Chronicle's validated `CampaignSummary`: wins use
+ * a cyan/green SCORE COMPLETE treatment, while losses retain the red GAME OVER
+ * presentation. Per-job death and exfil debriefs remain in `<crash-dump>`.
  *
  * Usage:
  *   const screen = document.querySelector('game-over');
  *   screen.addEventListener('new-run', () => finishEndedCampaign());
- *   screen.setTelemetry({ campaignEndReason: 'clock-expired', seed });
+ *   screen.setSummary(summary);
  *   screen.show();
  */
 
 import { h } from '/src/domUtils.js';
-import type { GameOverTelemetry } from '/src/types.js';
+import { validateCampaignSummary, type CampaignSummary } from '/src/game/campaignSummary.js';
 
 const CSS = `
 :host {
@@ -25,6 +21,7 @@ const CSS = `
   --go-bg: rgba(4, 2, 3, 0.98);
   --go-text: #f0d4da;
   --go-dim: #c96b7d;
+  --go-roster-border: rgba(255, 51, 85, 0.28);
   --go-shadow: 0 0 48px rgba(255, 51, 85, 0.35), 0 16px 48px rgba(0, 0, 0, 0.75);
 
   display: none;
@@ -36,6 +33,19 @@ const CSS = `
   animation: game-over-backdrop 2.4s ease-in-out infinite alternate;
 }
 
+:host([result='win']) {
+  --go-accent: #00e5b0;
+  --go-bg: rgba(2, 10, 9, 0.98);
+  --go-text: #d8fff5;
+  --go-dim: #72d9c0;
+  --go-roster-border: rgba(0, 229, 176, 0.3);
+  --go-shadow: 0 0 54px rgba(0, 229, 176, 0.28), 0 16px 48px rgba(0, 0, 0, 0.72);
+  background:
+    radial-gradient(ellipse at center, rgba(0, 229, 176, 0.14) 0%, transparent 68%),
+    rgba(0, 5, 4, 0.88);
+  animation: score-complete-backdrop 5s ease-in-out infinite alternate;
+}
+
 :host([open]) {
   display: flex;
   align-items: center;
@@ -47,6 +57,11 @@ const CSS = `
   to { background-color: rgba(12, 2, 4, 0.92); }
 }
 
+@keyframes score-complete-backdrop {
+  from { background-color: rgba(0, 4, 3, 0.86); }
+  to { background-color: rgba(1, 14, 11, 0.92); }
+}
+
 .panel {
   background: var(--go-bg);
   border: 2px solid var(--go-accent);
@@ -60,13 +75,17 @@ const CSS = `
 
 .banner {
   margin: 0 0 0.35rem;
-  font-size: clamp(1.75rem, 6vw, 2.5rem);
-  letter-spacing: 0.28em;
+  font-size: clamp(1.55rem, 6vw, 2.5rem);
+  letter-spacing: 0.22em;
   color: var(--go-accent);
-  text-shadow: 0 0 18px rgba(255, 51, 85, 0.45);
+  text-shadow: 0 0 18px color-mix(in srgb, var(--go-accent) 45%, transparent);
   animation: game-over-pulse 1.8s ease-in-out infinite;
 }
 
+:host([result='win']) .banner {
+  animation-duration: 3.6s;
+}
+
 @keyframes game-over-pulse {
   0%, 100% { opacity: 1; }
   50% { opacity: 0.82; }
@@ -74,7 +93,7 @@ const CSS = `
 
 .rule {
   margin: 0 auto 1.25rem;
-  width: min(280px, 70%);
+  width: min(320px, 76%);
   border: none;
   border-top: 2px solid var(--go-accent);
   opacity: 0.7;
@@ -97,7 +116,7 @@ const CSS = `
   margin: 0 0 1.25rem;
   padding: 0.65rem 0.85rem;
   background: rgba(0, 0, 0, 0.45);
-  border: 1px solid rgba(255, 51, 85, 0.28);
+  border: 1px solid var(--go-roster-border);
   border-radius: 4px;
   font-size: 0.85rem;
   text-align: left;
@@ -127,11 +146,15 @@ const CSS = `
   letter-spacing: 0.08em;
 }
 
+.roster-line .status.flatlined {
+  color: #ff6680;
+}
+
 .meta {
   display: grid;
   grid-template-columns: max-content 1fr;
   column-gap: 1.25rem;
-  row-gap: 0.2rem;
+  row-gap: 0.25rem;
   font-size: 0.85rem;
   margin: 0 0 1.25rem;
   text-align: left;
@@ -178,53 +201,45 @@ button.new-campaign:focus-visible {
 button.new-campaign:active { transform: scale(0.98); }
 `;
 
-function hexSeed(seed: number) {
-  if (!Number.isFinite(seed)) return '?';
+function hexSeed(seed: number): string {
   return `0x${(seed >>> 0).toString(16).toUpperCase().padStart(8, '0')}`;
 }
 
-function reasonCopy(telemetry: GameOverTelemetry): string {
-  if (telemetry.campaignEndReason === 'clock-expired') {
-    return 'The Score window closed.';
-  }
-  if (telemetry.campaignTerminal) {
-    return 'Final operator lost on the wire.';
+function reasonCopy(summary: CampaignSummary): string {
+  if (summary.result === 'win') return 'The Score is complete.';
+  if (summary.endReason === 'clock-expired') return 'The Score window closed.';
+  if (summary.endReason === 'decker-flatlined-score') {
+    return 'The Decker flatlined during the Score.';
   }
   return 'No surviving operators.';
 }
 
-function detailCopy(telemetry: GameOverTelemetry): string {
-  if (telemetry.campaignEndReason === 'clock-expired') {
+function detailCopy(summary: CampaignSummary): string {
+  if (summary.result === 'win') {
+    return 'Target data secured. The crew beat the window and closed the campaign on their terms.';
+  }
+  if (summary.endReason === 'clock-expired') {
     return 'Corp security caught up. The contract is cold and this campaign is over.';
   }
-  if (telemetry.campaignTerminal) {
-    const label = telemetry.cause ?? telemetry.archetype ?? 'operator';
-    return `Last channel down — ${label}. No backup left on the roster.`;
+  if (summary.endReason === 'decker-flatlined-score') {
+    return 'The intrusion channel is gone. Until dual-deploy exists, nobody can finish the Score.';
   }
-  const salvageNote =
-    telemetry.salvage != null && typeof telemetry.salvage === 'number' && telemetry.salvage >= 0
-      ? `Pool salvage ${telemetry.salvage} is lost with the run.`
-      : 'Every crew slot on the roster is flatlined.';
-  return `${salvageNote} Start a new campaign to run the board again.`;
-}
-
-function causeLabel(telemetry: GameOverTelemetry): string {
-  if (telemetry.campaignEndReason === 'clock-expired') return 'window-closed';
-  if (telemetry.campaignTerminal) return 'final-operator-lost';
-  return 'crew-wipe';
+  return 'Every crew slot on the roster is flatlined. Their campaign ends here.';
 }
 
 class GameOver extends HTMLElement {
-  #telemetry: GameOverTelemetry | null = null;
+  #summary: CampaignSummary | null = null;
   #ready = false;
   #els: {
+    banner: HTMLElement;
     reason: HTMLElement;
     detail: HTMLElement;
-    roster: HTMLElement;
     rosterList: HTMLElement;
+    jobsDd: HTMLElement;
+    repDd: HTMLElement;
+    creditsDd: HTMLElement;
     seedDd: HTMLElement;
     causeDd: HTMLElement;
-    newCampaignBtn: HTMLButtonElement;
   } | null = null;
 
   connectedCallback() {
@@ -234,13 +249,17 @@ class GameOver extends HTMLElement {
     style.textContent = CSS;
     shadow.appendChild(style);
 
+    const banner = h('h1', { className: 'banner' });
     const reason = h('p', { className: 'reason' });
     const detail = h('p', { className: 'detail' });
     const rosterList = h('dd');
+    const jobsDd = h('dd', { id: 'jobs' });
+    const repDd = h('dd', { id: 'rep' });
+    const creditsDd = h('dd', { id: 'credits' });
     const seedDd = h('dd', { id: 'seed' });
     const causeDd = h('dd', { id: 'cause' });
     const roster = h('dl', { className: 'roster' }, [
-      h('dt', { textContent: 'ROSTER' }),
+      h('dt', { textContent: 'FINAL ROSTER' }),
       rosterList,
     ]);
 
@@ -252,12 +271,18 @@ class GameOver extends HTMLElement {
     newCampaignBtn.addEventListener('click', () => this.#emit('new-run'));
 
     const panel = h('section', { className: 'panel' }, [
-      h('h1', { className: 'banner', textContent: 'GAME OVER' }),
+      banner,
       h('hr', { className: 'rule' }),
       reason,
       detail,
       roster,
       h('dl', { className: 'meta' }, [
+        h('dt', { textContent: 'jobs' }),
+        jobsDd,
+        h('dt', { textContent: 'rep' }),
+        repDd,
+        h('dt', { textContent: 'credits' }),
+        creditsDd,
         h('dt', { textContent: 'seed' }),
         seedDd,
         h('dt', { textContent: 'cause' }),
@@ -266,20 +291,24 @@ class GameOver extends HTMLElement {
       h('div', { className: 'actions' }, [newCampaignBtn]),
     ]);
     shadow.appendChild(panel);
-    this.#els = { reason, detail, roster, rosterList, seedDd, causeDd, newCampaignBtn };
+    this.#els = {
+      banner,
+      reason,
+      detail,
+      rosterList,
+      jobsDd,
+      repDd,
+      creditsDd,
+      seedDd,
+      causeDd,
+    };
     this.#ready = true;
-    if (this.#telemetry) this.#render();
+    if (this.#summary) this.#render();
   }
 
-  setTelemetry(telemetry: GameOverTelemetry) {
-    if (!telemetry || typeof telemetry !== 'object') {
-      throw new TypeError('<game-over>.setTelemetry requires a telemetry object');
-    }
-    const { campaignEndReason, campaignTerminal } = telemetry;
-    if (!campaignEndReason && !campaignTerminal) {
-      throw new Error('<game-over>: requires campaignEndReason or campaignTerminal');
-    }
-    this.#telemetry = { ...telemetry };
+  setSummary(summary: CampaignSummary) {
+    this.#summary = validateCampaignSummary(summary);
+    this.setAttribute('result', this.#summary.result);
     if (this.#ready) this.#render();
   }
 
@@ -299,36 +328,34 @@ class GameOver extends HTMLElement {
   }
 
   #render() {
-    if (!this.#els || !this.#telemetry) return;
-    const t = this.#telemetry;
-    this.#els.reason.textContent = reasonCopy(t);
-    this.#els.detail.textContent = detailCopy(t);
-    this.#els.seedDd.textContent = hexSeed(t.seed ?? 0);
-    this.#els.causeDd.textContent = causeLabel(t);
-
-    if (t.campaignEndReason === 'clock-expired') {
-      this.#els.roster.hidden = true;
-      return;
-    }
-
-    const roster = t.crewRoster ?? [];
-    this.#els.roster.hidden = roster.length === 0;
+    if (!this.#els || !this.#summary) return;
+    const summary = this.#summary;
+    this.#els.banner.textContent = summary.result === 'win' ? 'SCORE COMPLETE' : 'GAME OVER';
+    this.#els.reason.textContent = reasonCopy(summary);
+    this.#els.detail.textContent = detailCopy(summary);
+    this.#els.jobsDd.textContent = String(summary.completedJobs);
+    this.#els.repDd.textContent = String(summary.rep);
+    this.#els.creditsDd.textContent = String(summary.credits);
+    this.#els.seedDd.textContent = hexSeed(summary.seed);
+    this.#els.causeDd.textContent = summary.endReason;
     this.#els.rosterList.replaceChildren(
-      ...roster.map(op =>
+      ...summary.crewRoster.map(operator =>
         h('div', { className: 'roster-line' }, [
-          h('span', { textContent: `${op.callsign} (${op.archetype})` }),
+          h('span', { textContent: `${operator.callsign} (${operator.archetype})` }),
           h('span', {
-            className: 'status',
-            textContent: op.flatlined ? 'FLATLINED' : 'ACTIVE',
+            className: `status${operator.flatlined ? ' flatlined' : ''}`,
+            textContent: operator.flatlined ? 'FLATLINED' : 'SURVIVED',
           }),
         ])
       )
     );
   }
 
-  #emit(eventName: string, detail: Record<string, unknown> = {}) {
+  #emit(eventName: string) {
     this.dispatchEvent(
-      new CustomEvent(eventName, { detail: { ...detail, telemetry: { ...this.#telemetry } } })
+      new CustomEvent(eventName, {
+        detail: { summary: this.#summary ? validateCampaignSummary(this.#summary) : null },
+      })
     );
   }
 }
diff --git a/components/RunBriefing.ts b/components/RunBriefing.ts
index 0d289bc..420b577 100644
--- a/components/RunBriefing.ts
+++ b/components/RunBriefing.ts
@@ -197,7 +197,7 @@ function threatCopy(count: number) {
 
 function rewardCopy(contract: Partial<Contract>) {
   if (contract.context?.tags.includes('score') && contract.context.recipeId === 'score-final') {
-    return 'Campaign finale';
+    return contract.reward ? `Cr +${contract.reward.credits} / Campaign finale` : 'Campaign finale';
   }
   const reward = contract.reward;
   if (!reward) return '?';
diff --git a/docs/kaizen.md b/docs/kaizen.md
index bead4cd..091ca0f 100644
--- a/docs/kaizen.md
+++ b/docs/kaizen.md
@@ -21,8 +21,8 @@ When an item lands, gets reclassified, or develops new context, edit it in place
 
 ## ▶ Phase 3 candidates
 
-- **Cyberspace / Matrix layer.** Jack-in mechanic, second layered grid, ICE AI (Probes, Sparks, Guardians), CCTV PIP window showing physical body status while jacked in. Originally Blueprint Phase 2; moved to Phase 3 so Phase 2 deepens Meatspace first. **Planning updated:** see [phase-3-plan.md](phase-3-plan.md) P3.M3.1–P3.M3.6 for the first playable "enter Cyberspace" path (contract flag → jack-in terminal → serializable cyber layer → data node → Probe ICE → render swap), and P3.M4.1–P3.M4.6 for dual-deploy / flip integration.
-- **Decker archetype.** Cyberspace specialist. Deferred alongside the Matrix layer — design the environment before designing who navigates it. **Planning updated:** see [phase-3-plan.md](phase-3-plan.md) P3.M2 for recruitment through progressive Hub reveal, normal roster ownership, drone override, and the rule that Cyberspace-required deployments fail loudly without a living Decker.
+- **Cyberspace / Matrix layer.** **P3.M3 first playable slice shipped (2026-06-11):** `JackInPoint` (Ω) in Meatspace opens the layer; `CyberspaceLayer` owns its own `World`, `CyberAvatar`, data nodes, and Probe ICE; data-node-slice objective with `NODES` HUD chip; Probe ICE with trace-flare and pack convergence; render/input swap to the grid view (distinct cyan/magenta tileset, `// THE GRID //` location, RAM HUD); voluntary jack-out with LINK BURNED latch and early-exit confirmation modal. Score is always a cyber run (scope decision #5). **Still open:** Spark ICE (fast attacker), Guardian ICE (heavy node guard), CCTV PIP window showing inactive layer, dual-deploy simstim flip (P3.M4). See [phase-3-plan.md](phase-3-plan.md) P3.M3–P3.M4 and [phase-3-cyberspace-plan.md](phase-3-cyberspace-plan.md) for full slice notes and recorded scope decisions.
+- ~~**Decker archetype.**~~ **✓ Closed — P3.M2.** Shipped 2026-06-11: recruited as a narrative beat at Act 1 → Act 2 (same `score-reveal` Hub beat as the Score target), drone override hack, `Decker.ts` archetype with Cyberspace stats (`ram`, `intrusionStrength`, `iceResistance`), normal roster ownership. Cannot be randomly recruited before Act 2; Cyberspace-required deploys fail loudly without a living Decker. Cyberspace avatar (`CyberAvatar`) and its stats are P3.M3.
 - **Full Rep NPC ally behaviour.** Phase 2 (M5) lays the groundwork: Rep meter, NPC taxonomy, behavior tiers. Phase 3 adds the payoff: high-rep neutrals become Human Shields or information sources, as described in the blueprint.
 - **Inter-hostile friction — multiple crews fighting each other on one map.** Surfaced during Phase 2.9 planning (June 2026). Phase 2.9 ships `RIVAL` as a faction *value* but deliberately keeps **one hostile faction per run** (faction derived from the contract's principal: corp/civic → `CORP`, rival groups → `RIVAL`). That's the slim, cosmetic-foundational slice — it does *not* put `CORP` and `RIVAL` on the same map. The deferred expansion is **mixed encounters with relationship structure** — a rival crew/gang on a site you're also hitting, where the play value comes from *friction*, not a recolor. The design spectrum we mapped:
   - **Cooperate vs player** — RIVAL behaves identically and shares your enemy; mechanically a reskin (the M1 display layer already delivers the label/colour delta). Weakest payoff; arguably not worth a faction *model*.
@@ -31,7 +31,7 @@ When an item lands, gets reclassified, or develops new context, edit it in place
   - **Cost insight:** target acquisition is *already faction-general* — `Hostile.acquireTarget` scans for the closest entity `isHostileTo` returns true for, and that's just `faction !== this.faction` (minus NEUTRAL). So the three-way needs **no new targeting AI**; the cost is a stance/relationship helper replacing raw `!==`, plus **balance tuning** to avoid the degenerate case (enemies ignore the player and murder each other while you spectate — lever: weight aggro toward the player or by proximity).
   - **Why deferred:** Cyberspace (Phase 3) is the higher-impact direction for the game Rylee wants to build first. Revisit after the Matrix layer lands, or sooner if a contract design specifically calls for a contested-site fantasy. The Phase 2.9 `RIVAL` faction + Principal→faction mapping is the foundation this would build on.
 - **Typed salvage components.** Phase 2 uses a generic `salvage: number` counter. **Intro scope (typed categories + Finn integration) moves to [phase-2.5-plan.md](phase-2.5-plan.md) M4.** Deep multi-recipe crafting and Matrix-adjacent sinks may remain Phase 3+.
-- **"What's this glyph?" / "Look" feature:** Roaming-cursor inspect mode to disambiguate `%` (rubble vs corpse) and identify map glyphs via the log feed. **Planned — Tier 2 spec in [`look-feature-plan.md`](look-feature-plan.md)** (cursor, player-turn only, minimal+ labels, floor no-op). Implement when scheduling post–2.5 QoL.
+~~- **"What's this glyph?" / "Look" feature:**~~ **(→ Closed in P2.9)** ~~Roaming-cursor inspect mode to disambiguate `%` (rubble vs corpse) and identify map glyphs via the log feed. **Planned — Tier 2 spec in [`look-feature-plan.md`](look-feature-plan.md)** (cursor, player-turn only, minimal+ labels, floor no-op). Implement when scheduling post–2.5 QoL.~~
 - **Objective extension backlog beyond Phase 2.5 M2.11–M2.12.** Recon and escort/extract are now planned in [phase-2.5-plan.md](phase-2.5-plan.md), but the M2.10 recipe-builder discussion surfaced additional objective shapes worth preserving:
   - **Plant / seed / bug:** carry something in, place it at a target, then extract. Fiction: bug a relay, plant evidence, seed malware, place a charge.
   - **Compound chains:** retrieve then handoff, slice then retrieve, sync then deny, etc. Likely needs a multi-step objective schema rather than more one-kind recipes.
@@ -51,6 +51,7 @@ When an item lands, gets reclassified, or develops new context, edit it in place
   structural.
   - **run.world/run.player direct reads remain legal** — the new active-view seam is convention, not
   compiler-enforced; a lint rule or accessor deprecation would lock it in.
+- ~~**Cyberspace playtesting feedback.**~~ **Closed 2026-06-14:** Probe ICE reduced from 3 HP / 4 AP to 2 HP / 2 AP; the CyberAvatar can use Override against ICE, including allied aftermath actions, reversion, and save round-trip; a pre-Score Decker flatline creates a free replacement Decker lead in the Terminal and gates THE SCORE until recruited; a Decker flatline during THE SCORE ends the campaign with explicit Game Over copy (`decker-flatlined-score`). See the P3.M3 playtest stabilization note in [phase-3-plan.md](phase-3-plan.md).
 
 ## ◇ Monitored
 
diff --git a/docs/phase-2-plan.md b/docs/phase-2-plan.md
index 7aa480d..516e778 100644
--- a/docs/phase-2-plan.md
+++ b/docs/phase-2-plan.md
@@ -143,7 +143,7 @@ The biggest architectural seam in Phase 2. `Run.js` is refactored; Hub logic mov
 - `Run.js` refactored: `HUB` state removed. Run now covers `BRIEFING → COMBAT → RESULT` only. Hub panel rendering moves to Campaign's `HUB` handler in `index.js`.
 - `index.js` (shell): mounts `Campaign` instead of `Run` directly. Campaign's `onPersist` callback writes to DataStore at campaign scope. Meta scope written separately on every Hub upgrade purchase.
 - **Campaign start UX:** On the start of a new campaign, a new `<system-start>` overlay shows a basic terminal-styled welcome message in the Curator's voice.
-- **Campaign wipe UX (shell):** When the last non-flatlined operator dies on a job, `<crash-dump>` shows campaign-terminal copy (`willEndCampaignOnThisDeath` → `campaignTerminal` on death telemetry — **CAMPAIGN TERMINATED**, last-fight trace, `[ NEW CAMPAIGN ]`). Resuming a save in `ENDED` uses `outcome: 'campaign-over'` (roster + salvage line). Same overlay component as per-job debrief (M8).
+- **Campaign wipe UX (shell, superseded by P3.M6):** Phase 2 originally routed the last-operator death through `<crash-dump>`. The Chronicle end-summary slice now settles terminal results immediately and presents the summary-backed `<game-over>` overlay; `<crash-dump>` is restricted to recoverable job debriefs.
 - DataStore: new `campaign` record `{ id, crew: CrewSnapshot[], salvage, credits, vouch, meta }`. `persistence.js` gains `snapshotCampaign(campaign)` / `restoreCampaign(record)`. Corrupt campaign records throw with useful messages (same rule as job snapshots).
 - Hub UI: `<crew-roster>` web component — shows all three crew members (callsign, archetype badge, HP indicator, `FLATLINED` flag). Crew member selection for next deployment. Mounts in place of the removed Hub-inside-Run panel.
 - `buildPlayer` removed from `src/game/archetypes/index.js`; all callers updated.
diff --git a/docs/phase-2.6-plan.md b/docs/phase-2.6-plan.md
index 3326d7e..02495a7 100644
--- a/docs/phase-2.6-plan.md
+++ b/docs/phase-2.6-plan.md
@@ -128,6 +128,6 @@ This doctrine is codified in `AGENTS.md` → "Error handling — fail loud, but
 
 - **Doctrine already codified.** The three-tier policy is already written in `AGENTS.md` → "Error handling — fail loud, but recover." M2 is therefore *just the boundary*, not "doctrine + boundary."
 - **M2.1 audit result:** confirmed **no** global handlers exist anywhere (`window.onerror`, `unhandledrejection`, `addEventListener('error')`) and no app-level boundary component. The real entry/bootstrap is root `index.ts` (no `entries/` dir); `DataStore` is `src/DataStore.ts`.
-- **Fault screen is non-diegetic, separate from `CrashDump`.** `components/CrashDump.ts` is the *in-fiction* death/exit/campaign-over modal (faux "KERNEL PANIC" stack trace). Routing a real bug through it would disguise the bug as an in-universe death — itself a silent failure. The boundary gets its own deliberately out-of-fiction `<fault-screen>`: "Something glitched — returning to the Hub, your progress is safe," single `[ RETURN TO HUB ]`.
+- **Fault screen is non-diegetic, separate from run-result UI.** `components/CrashDump.ts` is the *in-fiction* recoverable death/exit modal (faux "KERNEL PANIC" stack trace); Phase 3 terminal campaign outcomes moved to `<game-over>`. Routing a real bug through either would disguise the bug as an in-universe outcome — itself a silent failure. The boundary gets its own deliberately out-of-fiction `<fault-screen>`: "Something glitched — returning to the Hub, your progress is safe," single `[ RETURN TO HUB ]`.
 - **Architecture (honors no-logic-in-components):** browser-free `src/errorBoundary.ts` (installs handlers on an injected `EventTarget`, normalizes the thrown value, fires `onSignal` = console.error + no-op telemetry seam, invokes a coarse `degrade()` callback, re-entrancy guarded, returns an uninstall fn) + thin `components/FaultScreen.ts` + `index.ts` wiring. Node 22 lacks `ErrorEvent`/`PromiseRejectionEvent`, so the module duck-types the payload (`.error ?? .reason ?? event`) and stays testable under `node --test` with a plain `EventTarget`.
 - **Corp-slice cold resume:** autosave fires at the player→corp `turn:ended` before the animated aftermath/corp driver runs. On reload with `currentFaction: corp`, the shell calls `resumePendingCombatSliceIfNeeded()` (`advanceFromPlayerTurn` with `resumeFromCorpSlice: true`) so the save doesn't load into a stuck "CORP TURN — controls locked" state with no driver running.
diff --git a/docs/phase-3-cyberspace-plan.md b/docs/phase-3-cyberspace-plan.md
index 54d5b58..750b134 100644
--- a/docs/phase-3-cyberspace-plan.md
+++ b/docs/phase-3-cyberspace-plan.md
@@ -43,8 +43,16 @@ Commits land **per green slice** (user-approved).
 | **S7 — P3.M3.6 Render/input swap + shell ICE phase** | ✅ Done | `dd17cb8` |
 | **— Score → cyber (scope decision #5)** | ✅ Done | `3c693dc` |
 | **S7.5 — Early jack-out confirmation** | ✅ Done | `2d668bd` |
+| **Playtest stabilization** | ✅ Done | — |
 | **S8 — Docs + wrap-up** | ✅ Done | — |
 
+### Playtest stabilization (2026-06-14)
+
+- Probe ICE tuned from 3 HP / 4 AP to 2 HP / 2 AP. The one-damage strike stays; reducing repeated actions addresses the real burst-pressure source while making Probes appropriately disposable before Spark and Guardian land.
+- CyberAvatar now exposes Override against ICE. It uses the existing 2 AP / 60% / 3-turn override contract, runs allied ICE in the cyber aftermath pass, and preserves override state through active-layer snapshots.
+- A flatlined Decker before THE SCORE creates a single free replacement Decker lead in the Terminal. Recruiting them consumes the visit's recruit slot, and THE SCORE remains unavailable without a living Decker.
+- A Decker flatline during THE SCORE ends the campaign with the persisted `decker-flatlined-score` reason and dedicated Game Over copy. This remains the rule until dual-deploy gives the Score another meaningful failure/recovery shape.
+
 ### S1 implementation notes (shipped)
 
 - `OBJECTIVES.DATA_NODE_SLICE = 'data-node-slice'` with cross-field validation
@@ -333,7 +341,7 @@ Commits land **per green slice** (user-approved).
   slice shipped end-to-end; milestone stays open for Spark/Guardian ICE
   (scope decision #1) and the deferred follow-ups noted in S6
   (ICE faction stamping) and kaizen (index.ts cleanup).
-- Browser re-smoke of the S7.5 confirm flow: pending (Rylee).
+- Browser smoke of the S7.5 confirm flow: verified.
 
 ## Architecture decisions (approved plan)
 
diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 0af95cb..b31dd0d 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -46,7 +46,7 @@ A new **player archetype** recruited mid-campaign (late Act 1 / start of Act 2),
 | P3.M3 — Cyberspace grid + ICE | 🟡 First playable slice shipped (Spark/Guardian ICE open) |
 | P3.M4 — Simstim flip (dual-deploy) | 🔲 Planned |
 | P3.M5 — The Score (climactic mission) | 🔲 Planned |
-| P3.M6 — Chronicle (campaign narrative memory) | 🔲 Planned |
+| P3.M6 — Chronicle (campaign narrative memory) | 🟡 End-summary foundation shipped |
 
 **Phase 3** is complete when:
 
@@ -103,9 +103,10 @@ The Score target is always a newly synthesized CRITICAL-tier site, never promote
   - Score = special contract build path; not part of the normal three-card job board.
 - **Hub surface:** Hub status / Terminal shows current stage and Score target label once revealed. Clock HUD (`CLOCK: HEAT X / Y JOBS LEFT`) appears **only after** the player dismisses the `clock-reveal` briefing and heat has actually started — no "dormant" or countdown-to-heat lines before then. User-facing labels use "Stage" (STAGE 1, STAGE 2, etc.) — code and persistence keep `arc`/`arcStage` naming. Arc beats use progressive Hub reveal plumbing (`score-reveal`, `clock-reveal`, `act-3-reveal`); see P3.M1.4–M1.5 notes.
 - **Win/loss conditions:**
-  - **Win:** Complete the Score (extract with objective satisfied from the final mission). Terminal debrief: `*** SCORE COMPLETE ***`.
+  - **Win:** Complete the Score (extract with objective satisfied from the final mission). Terminal campaign overlay: `SCORE COMPLETE`.
   - **Loss (flatline):** Entire crew wiped during any run (existing behavior, but now with arc context for the chronicle).
-  - **Loss (clock):** `clockJobsTaken >= CLOCK_ACT2_DEADLINE_JOBS` (8) before `scoreAttempted`. Terminal debrief: `*** WINDOW CLOSED ***` — not a status-line footnote. Attempted Score keeps the deadline from retroactively killing the save.
+  - **Loss (Score Decker):** If the Decker flatlines during THE SCORE, the campaign ends immediately with explicit Game Over copy. Before the Score, a flatlined Decker instead opens one free replacement lead through the Terminal; THE SCORE remains gated until a living Decker is recruited.
+  - **Loss (clock):** `clockJobsTaken >= CLOCK_ACT2_DEADLINE_JOBS` (8) before `scoreAttempted`. Terminal campaign overlay: `GAME OVER` with explicit window-closed copy — not a status-line footnote. Attempted Score keeps the deadline from retroactively killing the save.
 
 **The Clock mechanic:**
 
@@ -152,11 +153,11 @@ Neural degradation is deferred until Cyberspace is fun enough to deserve a jack-
 
 **P3.M1.4 implementation note:** Score reveal is player-visible. A one-shot `score-reveal` Hub reveal lets the Curator name the target, introduce the Decker, and teach the **CASING** job-board badge (same-principal org jobs during Act 2+). **SCORE SITE** still marks contracts whose `locationSiteId` matches the synthesized Score target. Arc briefings (`score-reveal`, `clock-reveal`, `act-3-reveal`) are priority Hub reveals: they are evaluated before lower-priority intros (Finn, clinic, terminal-recruit) so a mid-save act transition is not crowded out on the same visit. Their `hubReveals` flags commit on Curator briefing **dismiss** (`commitHubReveal` in the shell), not when `enterHub` queues the copy — so a missed modal can retry on the next Hub entry, and pre-P3 saves that qualify for Act 2 on first load under 3.0 are not silently bumped without the narrative beat. The shell resume path presents any pending `lastHubReveal` when restoring a HUB save. The Hub status row and Terminal crew roster show the current stage label (user-facing "STAGE N") plus Score target once revealed. Shared `arcSurface` helpers own the copy and invariant checks so multiple Score targets, or revealed Score state without a target, fail loud instead of rendering misleading UI.
 
-**P3.M1.5 implementation note:** The Clock is driven by `clockJobsTaken` (Act 2/3 deploys), not `completedJobs` — entering Act 2 with many Stage 1 extractions does not start heat immediately. Grace: `CLOCK_ACT2_GRACE_JOBS` (3) deploys; then `clockStarted` and heat accrue until `CLOCK_ACT2_DEADLINE_JOBS` (8). A `clock-reveal` Hub briefing explains heat, the operational window, and what happens when it closes (copy in `clockRevealLines`). Clock HUD text appears only after `clockBriefingPresented` **and** `clockStarted`: `CLOCK: HEAT X / Y JOBS LEFT` on the canvas HUD, Terminal roster, and status bar. No "dormant" or "N jobs to heat" lines before the player has seen the briefing. Heat raises Curator threat counts without changing difficulty tier, capped per tier. Deadline loss sets `Campaign.endReason` to `clock-expired` and shows a dedicated terminal game-over screen (`*** WINDOW CLOSED ***` via `<crash-dump>`), not a clock status footnote. Score win uses `*** SCORE COMPLETE ***`; crew wipe keeps the existing campaign-terminal death path. An attempted Score keeps the deadline from retroactively killing the save.
+**P3.M1.5 implementation note:** The Clock is driven by `clockJobsTaken` (Act 2/3 deploys), not `completedJobs` — entering Act 2 with many Stage 1 extractions does not start heat immediately. Grace: `CLOCK_ACT2_GRACE_JOBS` (3) deploys; then `clockStarted` and heat accrue until `CLOCK_ACT2_DEADLINE_JOBS` (8). A `clock-reveal` Hub briefing explains heat, the operational window, and what happens when it closes (copy in `clockRevealLines`). Clock HUD text appears only after `clockBriefingPresented` **and** `clockStarted`: `CLOCK: HEAT X / Y JOBS LEFT` on the canvas HUD, Terminal roster, and status bar. No "dormant" or "N jobs to heat" lines before the player has seen the briefing. Heat raises Curator threat counts without changing difficulty tier, capped per tier. Deadline loss sets `Campaign.endReason` to `clock-expired`; terminal outcomes now bypass `<crash-dump>` and use the summary-backed `<game-over>` overlay. An attempted Score keeps the deadline from retroactively killing the save.
 
 **P3.M1.6 implementation note:** `Curator.generateContracts` now uses campaign-derived arc context behaviorally. Act 2 guarantees at least one fresh same-principal casing job for the Score target's organization. Act 3 guarantees a mostly same-principal prep board. The normal board avoids rolling the Score target itself so the finale stays a deliberate Hub action.
 
-**P3.M1.7 implementation note:** Act 3 exposes a special `THE SCORE` contract through `Campaign.buildScoreContract()`, appended to the Hub job choices only when `Campaign.canAttemptScore()` passes. The first qualifying Hub visit also fires `act-3-reveal` ("You're ready… grab THE SCORE from the board while you can") before the player sees the fourth board slot. Deploying THE SCORE marks `scoreAttempted`, moves `arcStage` to `score`, uses the persisted Score target dimensions/memory, and completing it marks `scoreCompleted` and ends the campaign in a win state.
+**P3.M1.7 implementation note:** Act 3 exposes a special `THE SCORE` contract through `Campaign.buildScoreContract()`, appended to the Hub job choices only when `Campaign.canAttemptScore()` passes. The first qualifying Hub visit also fires `act-3-reveal` ("You're ready… grab THE SCORE from the board while you can") before the player sees the fourth board slot. Deploying THE SCORE marks `scoreAttempted`, moves `arcStage` to `score`, uses the persisted Score target dimensions/memory, and completing it awards the campaign-ending `1,000 Cr` payoff, marks `scoreCompleted`, and ends the campaign in a win state.
 
 **Acceptance:**
 
@@ -238,16 +239,20 @@ The first jack-in should prove the door between layers before shipping every ICE
 4. Latch a run state like `cyberspace.active = true`; repeated jack-in attempts against the same terminal throw or log a deterministic "already linked" message depending on whether state is corrupt or just redundant input.
 5. Saving mid-jack-in restores both Meatspace and Cyberspace. Absent or malformed Cyberspace snapshot data for an active jack-in is tier-1 corrupt state and must throw to the boundary.
 
-**Suggested slice order:**
+**Implementation slices:**
 
-| Slice | Change | Tests |
-|---|---|---|
-| **P3.M3.1 Contract flag** | Add Cyberspace-capable contract metadata and validation | generated only Act 2+, invalid flag/params throw |
-| **P3.M3.2 Jack-in terminal** | Place a terminal that can start the digital layer | deterministic placement, no collision with objective props |
-| **P3.M3.3 Cyber layer model** | Add serializable `Run.cyberspace` layer with grid/world/avatar | snapshot round-trip, active-layer invariants |
-| **P3.M3.4 Data node objective** | Slice one data node and feed objective satisfaction | incomplete blocks clean extraction, complete allows it |
-| **P3.M3.5 Probe ICE** | Minimal ICE patrol/detect/attack loop | seeded movement, detection/alarm, damage/death |
-| **P3.M3.6 Render swap** | Render Cyberspace when active; Meatspace remains reachable for P3.M4 | browser smoke and console-clean verification |
+| Slice | Status | Change | Tests |
+|---|---|---|---|
+| **P3.M3.1 Contract flag** | ✅ Done | Add Cyberspace-capable contract metadata and validation | generated only Act 2+, invalid flag/params throw |
+| **P3.M3.2 Jack-in terminal** | ✅ Done | Place a terminal that can start the digital layer | deterministic placement, no collision with objective props |
+| **P3.M3.3 Cyber layer model** | ✅ Done | Add serializable `Run.cyberspace` layer with grid/world/avatar | snapshot round-trip, active-layer invariants |
+| **P3.M3.4 Data node objective** | ✅ Done | Slice one data node and feed objective satisfaction | incomplete blocks clean extraction, complete allows it |
+| **P3.M3.5 Probe ICE** | ✅ Done | Minimal ICE patrol/detect/attack loop | seeded movement, detection/alarm, damage/death |
+| **P3.M3.6 Render swap** | ✅ Done | Render Cyberspace when active; Meatspace remains reachable for P3.M4 | browser smoke and console-clean verification |
+| **M4.6 pull-forward — voluntary jack-out** | ✅ Done | `JackInPoint.burned` latch; `Run.jackOut()`; shell swap; early jack-out confirmation modal (`onJackOutRequested` / `confirmJackOut`) | LINK BURNED latch, defer/confirm matrix, round-trip |
+| **Playtest stabilization** | ✅ Done | Probe 2 HP / 2 AP; Cyber Override against ICE; pre-Score replacement Decker; Score Decker death Game Over | action budget, override/revert + persistence, replacement/Score gates, terminal end reason |
+| **Spark ICE** | 🔲 Planned | Fast, fragile attacker; swarm behavior | — |
+| **Guardian ICE** | 🔲 Planned | Heavy guard of critical nodes; high HP/damage | — |
 
 **Acceptance:**
 
@@ -257,6 +262,8 @@ The first jack-in should prove the door between layers before shipping every ICE
 - Cyberspace grid generated deterministically from seed; snapshot round-trip for mid-run save/restore.
 - Jack-in from Meatspace terminal spawns Cyberspace grid.
 
+**P3.M3 playtest stabilization note (2026-06-14):** Probe pressure came from action economy, not its nominal one-damage strike: the original 3 HP / 4 AP unit could close and attack repeatedly after one Probe woke the pack. Probe now has 2 HP / 2 AP while retaining the trace-flare identity. `CyberAvatar` exposes the Decker's Override capability against ICE; successful overrides reuse the existing temporary faction flip, act during the cyber player-aftermath pass, revert on the normal countdown, and round-trip through the existing patrol snapshot. Campaign dead ends are explicit: before THE SCORE, loss of the assigned Decker creates one free Terminal replacement lead and hides THE SCORE until a living Decker joins; once THE SCORE begins, Decker death ends the campaign with `decker-flatlined-score` Game Over copy.
+
 ---
 
 ### P3.M4 — Simstim flip (dual-deploy) 🔲
@@ -277,7 +284,7 @@ The first jack-in should prove the door between layers before shipping every ICE
 - **PIP / CCTV window:** The inactive layer renders in a small overlay (bottom right corner of the screen). Shows grid state, hostile positions, the other operator's status. Read-only — no input accepted in the PIP. The blueprint's "real-time CCTV showing your physical body's status" becomes this.
 - **Vulnerability:** While the Decker is jacked in, their Meatspace body is a valid target for corp hostiles. If the body is destroyed, the Decker is killed (flatline) and Cyberspace access is lost. The Meatspace operator's explicit job is to **protect the Decker's body** — or at least keep hostiles away from the terminal.
 - **Jack-out:** The Decker can voluntarily jack out (returns control to single-grid Meatspace). Or is forced out if their body takes critical damage. Jack-out despawns the Cyberspace grid (any unsatisfied Cyberspace objectives fail).
-- **Contracts without Cyberspace:** Single-deploy as today. The Decker deploys solo in Meatspace (no flip, no Cyberspace grid). Their drone override hack is their primary value, but if they're flatlined, the campaign is over - no new Deckers can be recruited.
+- **Contracts without Cyberspace:** Single-deploy as today. The Decker deploys solo in Meatspace (no flip, no Cyberspace grid). Their drone override hack is their primary value. A pre-Score flatline opens one replacement Decker lead through the Terminal; a flatline during THE SCORE is campaign-terminal.
 - **Save invariant:** A run may be single-layer, pre-jack dual-deploy, or active dual-layer. Those states must be explicit. A save with `cyberspace.active = true` but no cyber grid/avatar, or with a Decker marked jacked-in but no Meatspace body anchor, is corrupt and must throw.
 
 **Integration slices:**
@@ -330,7 +337,7 @@ The first jack-in should prove the door between layers before shipping every ICE
 
 ---
 
-### P3.M6 — Chronicle (campaign narrative memory) 🔲
+### P3.M6 — Chronicle (campaign narrative memory) 🟡
 
 **Depends on:** P3.M1 (arc structure provides the narrative beats to chronicle). Can begin data collection earlier if arc state is available.
 
@@ -352,6 +359,8 @@ The first jack-in should prove the door between layers before shipping every ICE
 - Hub can open chronicle (active campaign) and history (past campaigns) without errors.
 - Tests for append + round-trip + cap/trim policy if the list is bounded.
 
+**P3.M6 implementation note:** The end-summary foundation is shipped. A validated `CampaignSummary` is built only after campaign settlement reaches `ENDED`, so the final completed-job increment, Credits (including the Score payoff), Rep, seed, and roster state are captured from the canonical final campaign. Salvage remains a campaign resource rather than a summary measure of value. `DataStore` keeps summaries newest-first, preserves the original record on duplicate archival, and trims history to 50 campaigns. Live completion and restored ended saves share the same idempotent archival path. `<game-over>` is now the single terminal campaign overlay with success and failure modes; terminal outcomes bypass the recoverable job-level `<crash-dump>` debrief. Active per-job chronicle entries, Terminal presentation, and history browsing remain follow-up work within P3.M6.
+
 ---
 
 ## Recorded design decisions
diff --git a/index.ts b/index.ts
index e482359..13fd602 100644
--- a/index.ts
+++ b/index.ts
@@ -21,7 +21,8 @@
 import { serviceWorkerManager } from '/src/ServiceWorkerManager.js';
 import dataStore from '/src/DataStore.js';
 
-import { Campaign, CAMPAIGN_STATE, willEndCampaignOnThisDeath } from '/src/game/Campaign.js';
+import { Campaign, CAMPAIGN_STATE, willEndCampaignAfterResult } from '/src/game/Campaign.js';
+import { buildCampaignSummary, type CampaignSummary } from '/src/game/campaignSummary.js';
 import { totalSalvage, formatSalvageCompact, type TypedSalvage } from '/src/game/salvage.js';
 import { RUN_STATE, Run } from '/src/game/Run.js';
 import { restoreCampaign, snapshotCampaign } from '/src/game/persistence.js';
@@ -96,7 +97,7 @@ import type { Intent } from '/src/input/applyIntent.js';
 import type { AimKind, Mode } from '/src/input/keymap.js';
 import { formatCombatHudA11ySummary } from '/src/render/combatHud.js';
 import type { CombatHudSummaryInput } from '/src/render/combatHud.js';
-import type { GameOverTelemetry, KeyItem, Telemetry, TurnActionStep } from '/src/types.js';
+import type { KeyItem, Telemetry, TurnActionStep } from '/src/types.js';
 import { installErrorBoundary, type FaultSignal } from '/src/errorBoundary.js';
 import { isDevelopmentMode } from '/src/domUtils.js';
 
@@ -146,7 +147,7 @@ type CrashDumpElement = ModalElement & {
   setTelemetry(telemetry: Telemetry): void;
 };
 type GameOverElement = ModalElement & {
-  setTelemetry(telemetry: GameOverTelemetry): void;
+  setSummary(summary: CampaignSummary): void;
 };
 type FaultScreenElement = ModalElement & {
   show(detail: { code?: string }): void;
@@ -275,8 +276,6 @@ let briefingEl: RunBriefingElement;
 let contractSelectEl: ContractSelectElement;
 let crashEl: CrashDumpElement;
 let gameOverEl: GameOverElement;
-/** Which overlay owns `RUN_STATE.RESULT` — set in `pushPendingJobResultOverlay`. */
-let resultOverlayTarget: 'crash' | 'game-over' = 'crash';
 let faultEl: FaultScreenElement;
 let systemStartEl: SystemStartElement;
 let curatorBriefingEl: CuratorBriefingElement;
@@ -625,6 +624,7 @@ async function boot() {
 // ---------------------------------------------------------------------------
 
 function startFreshCampaign() {
+  hideBlockingShellModals();
   campaign = new Campaign({
     seed: seedFromClock(),
     crew: [],
@@ -633,6 +633,7 @@ function startFreshCampaign() {
   });
 
   pendingJobResult = null;
+  setStatus('Booting Meatspace…');
   systemStartEl.setSession({ seed: campaign.seed });
   systemStartEl.show();
 }
@@ -818,6 +819,14 @@ function onCrewRecruit(evt: Event) {
     campaign.recruit(recruitId);
     const member = campaign.getCrewMember(recruitId);
     flash(`NEW OPERATIVE: ${member?.callsign ?? recruitId} joins the collective.`);
+    // A replacement Decker can unlock THE SCORE immediately. Preserve the
+    // existing three-card board and append only the newly legal finale.
+    if (
+      campaign.canAttemptScore() &&
+      !currentJobOptions.some(contract => contract.context.recipeId === 'score-final')
+    ) {
+      currentJobOptions.push(campaign.buildScoreContract());
+    }
     // Refresh the roster to reflect the new crew + hide recruit section.
     presentCrewRoster();
   } catch (err) {
@@ -1221,52 +1230,9 @@ function handlePersist() {
   dataStore.setCampaign(snapshotCampaign(campaign));
 }
 
-function crewMemberArchetypeId(member: Crew): string {
-  const n = member?.constructor?.name;
-  if (n === 'Merc') return 'merc';
-  if (n === 'Razor') return 'razor';
-  if (n === 'Tech') return 'tech';
-  return 'op';
-}
-
-function crewRosterStubs(c: Campaign) {
-  return c.crew.map(member => ({
-    callsign: member.callsign ?? member.id,
-    archetype: crewMemberArchetypeId(member),
-    flatlined: !!member.flatlined,
-  }));
-}
-
-function telemetryForEndedCampaign(c: Campaign): Telemetry {
-  const reason = c.endReason ?? 'crew-wipe';
-  return {
-    outcome: 'campaign-over',
-    campaignEndReason: reason,
-    seed: c.seed,
-    salvage: c.salvage,
-    crewRoster: crewRosterStubs(c),
-  };
-}
-
-function gameOverTelemetryForCampaign(c: Campaign): GameOverTelemetry {
-  const reason = c.endReason ?? 'crew-wipe';
-  if (reason === 'score-complete') {
-    throw new Error('[shell] score-complete is a win debrief, not game over');
-  }
-  return {
-    campaignEndReason: reason,
-    seed: c.seed,
-    salvage: c.salvage,
-    crewRoster: crewRosterStubs(c),
-  };
-}
-
 function presentEndedCampaignOverlay(c: Campaign): void {
-  if (c.endReason === 'score-complete') {
-    crashEl.setTelemetry(telemetryForEndedCampaign(c));
-  } else {
-    gameOverEl.setTelemetry(gameOverTelemetryForCampaign(c));
-  }
+  const summary = dataStore.archiveCampaign(buildCampaignSummary(c, new Date().toISOString()));
+  gameOverEl.setSummary(summary);
 }
 
 function presentCampaignEnd(c: Campaign): void {
@@ -1280,9 +1246,9 @@ function finishEndedCampaign(): void {
 }
 
 /**
- * Drives result overlays and `pendingJobResult` whenever the active job is in
- * RESULT — both from a live `Run.onResult` callback and from a cold resume
- * (otherwise `renderShell` opens an overlay with no `setTelemetry` call).
+ * Stage one result for settlement. Non-terminal jobs show `<crash-dump>`;
+ * terminal outcomes are settled immediately by `handleResult` and route to
+ * the Chronicle-backed `<game-over>` screen.
  */
 function pushPendingJobResultOverlay(telemetry: Partial<RunTelemetry> & { outcome?: unknown }) {
   const tel = { ...telemetry };
@@ -1294,31 +1260,20 @@ function pushPendingJobResultOverlay(telemetry: Partial<RunTelemetry> & { outcom
     outcome,
     telemetry: { ...tel, outcome } as RunTelemetry & { outcome: Outcome },
   };
-  const campaignTerminal =
-    outcome === 'death' && campaign ? willEndCampaignOnThisDeath(campaign) : false;
-  if (campaignTerminal && campaign) {
-    const activeCampaign = campaign;
-    const deployedId = activeCampaign.deployedMemberId;
-    resultOverlayTarget = 'game-over';
-    gameOverEl.setTelemetry({
-      campaignTerminal: true,
-      seed: tel.seed,
-      cause: tel.cause,
-      archetype: tel.archetype,
-      crewRoster: activeCampaign.crew.map(member => ({
-        callsign: member.callsign ?? member.id,
-        archetype: crewMemberArchetypeId(member),
-        flatlined: !!member.flatlined || member.id === deployedId,
-      })),
-    });
-  } else {
-    resultOverlayTarget = 'crash';
-    crashEl.setTelemetry({
-      ...tel,
-      outcome,
-      cause: tel.cause ?? undefined,
-    });
-  }
+  crashEl.setTelemetry({
+    ...tel,
+    outcome,
+    cause: tel.cause ?? undefined,
+  });
+}
+
+function pendingResultEndsCampaign(result: PendingJobResult): boolean {
+  if (!campaign) return false;
+  return willEndCampaignAfterResult(
+    campaign,
+    result.outcome,
+    result.outcome === 'exit' && result.telemetry.objectiveComplete !== false
+  );
 }
 
 function handleResult({ outcome, telemetry }: RunResult) {
@@ -1327,6 +1282,10 @@ function handleResult({ outcome, telemetry }: RunResult) {
     ...telemetry,
     outcome: telemetry?.outcome ?? outcome,
   });
+  if (pendingJobResult && pendingResultEndsCampaign(pendingJobResult)) {
+    settlePendingJobResult();
+    return;
+  }
   renderShell();
 }
 
@@ -1397,8 +1356,12 @@ function resumeCampaign(record: CampaignSnapshot | unknown) {
       renderShell();
     } else if (campaign.activeRun?.state === RUN_STATE.RESULT) {
       pushPendingJobResultOverlay({ ...campaign.activeRun.telemetry });
-      flash('RESUMED — mission debrief.');
-      renderShell();
+      if (pendingJobResult && pendingResultEndsCampaign(pendingJobResult)) {
+        settlePendingJobResult();
+      } else {
+        flash('RESUMED — mission debrief.');
+        renderShell();
+      }
     } else if (campaign.state === CAMPAIGN_STATE.HUB && campaign.curator) {
       renderShell();
       if (!presentHubRevealIfAny(resumeFlashMessage)) {
@@ -1446,7 +1409,6 @@ function performQuitCampaign(): void {
   itemInventoryEl.hide();
 
   pendingJobResult = null;
-  resultOverlayTarget = 'crash';
   dataStore.deleteCampaign();
   startFreshCampaign();
   flash('Campaign deleted — new campaign.');
@@ -1618,7 +1580,14 @@ function handleIntent(intent: Intent): void {
           if (campaign?.state === CAMPAIGN_STATE.HUB) {
             flash('Curator: Hang tight! Come talk to me to claim a contract.');
           }
-          advanceTurn();
+          // Moving onto an extraction tile synchronously emits the run result.
+          // Score settlement may therefore clear the active run and tear down
+          // the campaign world before this callback resumes. Only advance when
+          // the captured scene is still playable (incomplete abort/escort wait,
+          // or the Hub's decorative exit tile).
+          if (run.state === RUN_STATE.COMBAT || run.state === CAMPAIGN_STATE.HUB) {
+            advanceTurn();
+          }
           break;
       }
     },
@@ -1649,15 +1618,31 @@ function driveCombatTurnPipeline(run: Run, options: { resumeFromCorpSlice?: bool
     rng: run.rng,
     isTerminal: () => run.state === RUN_STATE.RESULT,
     drivePlayerAftermath: ({ onStep, onFinish }) => {
+      const finishMeatAftermath = () => {
+        if (degrading) return;
+        clearBreachBlastOverlay(false);
+        const layer = cyberLayerOf(run);
+        if (!layer) {
+          onFinish();
+          return;
+        }
+        drivePlayerAftermath({
+          world: layer.world,
+          rng: run.rng,
+          onStep,
+          onFinish,
+          animLock,
+          stepDelayMs: PLAYER_AFTERMATH_ACTION_DELAY_MS,
+          lockMarginMs: ANIMATION_DURATIONS.MUZZLE_FLASH,
+          player: layer.avatar,
+          schedule: scheduleCombatPump,
+        });
+      };
       drivePlayerAftermath({
         world,
         rng: run.rng,
         onStep,
-        onFinish: () => {
-          if (degrading) return;
-          clearBreachBlastOverlay(false);
-          onFinish();
-        },
+        onFinish: finishMeatAftermath,
         animLock,
         stepDelayMs: PLAYER_AFTERMATH_ACTION_DELAY_MS,
         lockMarginMs: ANIMATION_DURATIONS.MUZZLE_FLASH,
@@ -1679,6 +1664,11 @@ function driveCombatTurnPipeline(run: Run, options: { resumeFromCorpSlice?: bool
       // *applies*, but the canvas is showing the grid, so skip its
       // presentation (overlays/shake/log lines).
       const jacked = isJackedIn(scene);
+      const cyberLayer = cyberLayerOf(scene);
+      const isCyberStep =
+        cyberLayer !== null &&
+        step.type === 'overridden-drone' &&
+        cyberLayer.world.entities.has(step.entity.id);
       if (step.type === 'breach-detonate' && !jacked) {
         showBreachBlastOverlay(step.charge.x, step.charge.y);
         if (scene?.player && vision.isVisible(step.charge.x, step.charge.y)) {
@@ -1687,6 +1677,18 @@ function driveCombatTurnPipeline(run: Run, options: { resumeFromCorpSlice?: bool
         }
       }
       if (
+        isCyberStep &&
+        cyberLayer &&
+        isPlayerAftermathStepLogVisible(
+          step,
+          (x, y) => cyberVision.isVisible(x, y),
+          cyberLayer.avatar.id
+        )
+      ) {
+        for (const line of formatPlayerAftermathStepLogLines(step)) {
+          flash(line);
+        }
+      } else if (
         !jacked &&
         scene?.player &&
         isPlayerAftermathStepLogVisible(step, (x, y) => vision.isVisible(x, y), scene.player.id)
@@ -2021,49 +2023,50 @@ function handleCombatInteract(): void {
 
 // onJackIn removed — combat entry is handled in onBriefingDeploy.
 
+function settlePendingJobResult(): 'ended' | 'hub' {
+  if (!campaign || !pendingJobResult) {
+    throw new Error('settlePendingJobResult requires an active campaign result');
+  }
+  const jobResult = pendingJobResult;
+  const { outcome } = jobResult;
+  pendingJobResult = null;
+  // Extract typed salvage from the deployed crew member's inventory on exit.
+  // Death outcomes pass `undefined`, preserving the existing forfeiture rule.
+  const member = campaign.deployedMemberId
+    ? campaign.getCrewMember(campaign.deployedMemberId)
+    : null;
+  const salvage = member?.inventory?.salvage;
+  const objectiveComplete =
+    outcome === 'exit' ? jobResult.telemetry.objectiveComplete !== false : false;
+  // Apply the clean completion bonus before `onJobEnd`, so the terminal
+  // Chronicle record sees the final Rep value and Hub recruitment gates retain
+  // their existing ordering on non-terminal jobs.
+  if (outcome === 'exit' && objectiveComplete && civilianHarmsThisJob === 0) {
+    const actual = campaign.adjustRep(REP.CLEAN_COMPLETION_BONUS);
+    flash(`REP +${actual}: clean extraction — no civilian casualties.`);
+  }
+  if (outcome === 'exit' && !objectiveComplete) {
+    flash(`ABORT: Objective abandoned. REP ${REP.ABORT_PENALTY}.`);
+  }
+  campaign.onJobEnd({ outcome, salvage, completed: objectiveComplete });
+  if (campaign.state === CAMPAIGN_STATE.ENDED) {
+    presentCampaignEnd(campaign);
+    return 'ended';
+  }
+  if (!presentHubRevealIfAny('HUB — choose the next job.')) {
+    flash('HUB — choose the next job.');
+  }
+  if (!campaign.curator) {
+    throw new Error('settlePendingJobResult: hub not entered — curator is missing.');
+  }
+  currentJobOptions = generateCurrentJobOptions();
+  return 'hub';
+}
+
 function onNewRunRequested(): void {
   if (!campaign) return;
   if (pendingJobResult) {
-    const jobResult = pendingJobResult;
-    const { outcome } = jobResult;
-    pendingJobResult = null;
-    // Extract typed salvage from the deployed crew member's
-    // inventory on exit. Death outcomes pass `undefined` so onJobEnd defaults
-    // to an empty wallet (loot forfeited on flatline).
-    const member = campaign.deployedMemberId
-      ? campaign.getCrewMember(campaign.deployedMemberId)
-      : null;
-    const salvage = member?.inventory?.salvage;
-    const objectiveComplete =
-      outcome === 'exit' ? jobResult.telemetry.objectiveComplete !== false : false;
-    // Clean completion bonus — must run *before* `onJobEnd` so `enterHub` →
-    // `generateRecruits()` sees the updated Rep (recruitment gates at 65).
-    if (outcome === 'exit' && objectiveComplete && civilianHarmsThisJob === 0) {
-      const actual = campaign.adjustRep(REP.CLEAN_COMPLETION_BONUS);
-      flash(`REP +${actual}: clean extraction — no civilian casualties.`);
-    }
-    if (outcome === 'exit' && !objectiveComplete) {
-      flash(`ABORT: Objective abandoned. REP ${REP.ABORT_PENALTY}.`);
-    }
-    campaign.onJobEnd({ outcome, salvage, completed: objectiveComplete });
-    if (campaign.state === CAMPAIGN_STATE.ENDED) {
-      pendingJobResult = null;
-      if (campaign.endReason === 'crew-wipe') {
-        finishEndedCampaign();
-        return;
-      }
-      presentCampaignEnd(campaign);
-      return;
-    } else {
-      if (!presentHubRevealIfAny('HUB — choose the next job.')) {
-        flash('HUB — choose the next job.');
-      }
-      // reset the current job options
-      if (!campaign.curator) {
-        throw new Error('onNewRunRequested: hub not entered — curator is missing.');
-      }
-      currentJobOptions = generateCurrentJobOptions();
-    }
+    if (settlePendingJobResult() === 'ended') return;
   } else if (campaign.state === CAMPAIGN_STATE.ENDED) {
     finishEndedCampaign();
     return;
@@ -2324,24 +2327,14 @@ function renderShell(): void {
     case RUN_STATE.RESULT:
       canvas.hidden = true;
       briefingEl.hide();
-      if (resultOverlayTarget === 'game-over') {
-        crashEl.hide();
-        gameOverEl.show();
-      } else {
-        gameOverEl.hide();
-        crashEl.show();
-      }
+      gameOverEl.hide();
+      crashEl.show();
       break;
     case CAMPAIGN_STATE.ENDED:
       canvas.hidden = true;
       briefingEl.hide();
-      if (campaign.endReason === 'score-complete') {
-        gameOverEl.hide();
-        crashEl.show();
-      } else {
-        crashEl.hide();
-        gameOverEl.show();
-      }
+      crashEl.hide();
+      gameOverEl.show();
       break;
     default:
       throw new Error(`[shell] unknown state "${state}"`);
diff --git a/src/DataStore.ts b/src/DataStore.ts
index f8eae0c..3d70c29 100644
--- a/src/DataStore.ts
+++ b/src/DataStore.ts
@@ -1,5 +1,12 @@
 // singleton class to manage the user's data
 
+import {
+  archiveCampaignSummary,
+  cloneCampaignSummary,
+  normalizeCampaignHistory,
+  type CampaignSummary,
+} from './game/campaignSummary.js';
+
 const STORAGE_KEY = 'kp:data';
 let instance: DataStore | null = null;
 
@@ -15,13 +22,15 @@ type KPData = {
   prefs: Record<string, string | number | boolean | object>;
   runs: Run[];
   campaign: Campaign | null;
+  campaignHistory: CampaignSummary[];
 };
-type KPDataObject = string | object | Run | Campaign | Run[] | Campaign[];
+type KPDataObject = string | object | Run | Campaign | Run[] | Campaign[] | CampaignSummary[];
 
 class DataStore extends EventTarget {
   #prefs: KPData['prefs'] = {};
   #runs: KPData['runs'] = [];
   #campaign: KPData['campaign'] = null;
+  #campaignHistory: KPData['campaignHistory'] = [];
 
   constructor() {
     if (instance) {
@@ -36,46 +45,58 @@ class DataStore extends EventTarget {
   #loadDataFromJson(json: string): KPData {
     try {
       const data = JSON.parse(json);
-      return { prefs: data.prefs ?? {}, runs: data.runs ?? [], campaign: data.campaign ?? null };
+      return {
+        prefs: data.prefs ?? {},
+        runs: data.runs ?? [],
+        campaign: data.campaign ?? null,
+        campaignHistory: normalizeCampaignHistory(data.campaignHistory),
+      };
     } catch (error) {
       console.warn('[DataStore] Failed to parse stored JSON, resetting stored data.', error);
       try {
         window.localStorage.setItem(
           STORAGE_KEY,
-          JSON.stringify({ prefs: {}, runs: [], campaign: null })
+          JSON.stringify({ prefs: {}, runs: [], campaign: null, campaignHistory: [] })
         );
       } catch (storageError) {
         console.warn('[DataStore] Failed to reset stored data.', storageError);
       }
-      return { prefs: {}, runs: [], campaign: null };
+      return { prefs: {}, runs: [], campaign: null, campaignHistory: [] };
     }
   }
 
   async init() {
     let savedDataJson = window.localStorage.getItem(STORAGE_KEY);
     if (!savedDataJson) {
-      savedDataJson = JSON.stringify({ prefs: {}, runs: [], campaign: null });
+      savedDataJson = JSON.stringify({ prefs: {}, runs: [], campaign: null, campaignHistory: [] });
       window.localStorage.setItem(STORAGE_KEY, savedDataJson);
     }
-    const { prefs, runs, campaign } = this.#loadDataFromJson(savedDataJson);
+    const { prefs, runs, campaign, campaignHistory } = this.#loadDataFromJson(savedDataJson);
     this.#prefs = prefs;
     this.#runs = runs;
     this.#campaign = campaign;
+    this.#campaignHistory = campaignHistory;
     this.#emitChangeEvent('init', '*');
   }
 
   import(jsonData: string): void {
-    const { prefs, runs, campaign } = this.#loadDataFromJson(jsonData);
+    const { prefs, runs, campaign, campaignHistory } = this.#loadDataFromJson(jsonData);
     this.#prefs = prefs;
     this.#runs = runs;
     this.#campaign = campaign;
+    this.#campaignHistory = campaignHistory;
     this.#emitChangeEvent('import', '*');
   }
 
   #saveData() {
     window.localStorage.setItem(
       STORAGE_KEY,
-      JSON.stringify({ prefs: this.#prefs, runs: this.#runs, campaign: this.#campaign })
+      JSON.stringify({
+        prefs: this.#prefs,
+        runs: this.#runs,
+        campaign: this.#campaign,
+        campaignHistory: this.#campaignHistory,
+      })
     );
   }
 
@@ -108,6 +129,20 @@ class DataStore extends EventTarget {
     return this.#campaign;
   }
 
+  get campaignHistory(): CampaignSummary[] {
+    return this.#campaignHistory.map(cloneCampaignSummary);
+  }
+
+  archiveCampaign(summary: CampaignSummary): CampaignSummary {
+    const archived = archiveCampaignSummary(this.#campaignHistory, summary);
+    this.#campaignHistory = archived.history;
+    if (archived.added) {
+      this.#emitChangeEvent('add', 'campaignHistory', cloneCampaignSummary(archived.summary));
+      this.#saveData();
+    }
+    return cloneCampaignSummary(archived.summary);
+  }
+
   getRunById(id: string): Run | undefined {
     return this.#runs.find(run => run.id === id);
   }
diff --git a/src/game/Campaign.ts b/src/game/Campaign.ts
index 17f441f..fe07896 100644
--- a/src/game/Campaign.ts
+++ b/src/game/Campaign.ts
@@ -73,6 +73,8 @@ export const CLOCK_ACT2_GRACE_JOBS = 3;
 export const CLOCK_HEAT_WINDOW_JOBS = 5;
 /** Total act-2/3 deploys allowed before clock loss (`grace + window`). */
 export const CLOCK_ACT2_DEADLINE_JOBS = CLOCK_ACT2_GRACE_JOBS + CLOCK_HEAT_WINDOW_JOBS;
+/** Campaign-ending payday for completing THE SCORE. */
+export const SCORE_CREDITS_REWARD = 5_000;
 const SYNTHETIC_SCORE_TARGET_DIFFICULTY = CONTRACT_DIFFICULTY.CRITICAL;
 
 export const CAMPAIGN_STATE = Object.freeze({
@@ -132,13 +134,14 @@ export type CampaignOptions = {
 
 type CampaignLike = {
   crew: { flatlined: boolean }[];
+  activeRun?: { contract: Contract | null } | null;
+  arc?: Pick<CampaignArc, 'scoreRevealed' | 'scoreAttempted'>;
+  clockJobsTaken?: number;
 };
 
 /**
- * True when exactly one crew member is not yet `flatlined` — the operator
- * currently on a job. A `DEATH` outcome on `Campaign.onJobEnd` would flatline
- * them and set `Campaign.state` to `ENDED`. The shell uses this to swap the
- * debrief overlay before `onJobEnd` runs.
+ * True when a `DEATH` outcome is campaign-terminal: either the last living
+ * operator is gone, or the Decker flatlines during the Score.
  *
  * @param {{ crew: { flatlined: boolean }[] }} campaign
  */
@@ -146,7 +149,38 @@ export function willEndCampaignOnThisDeath(campaign: CampaignLike): boolean {
   if (!campaign || typeof campaign !== 'object' || !Array.isArray(campaign.crew)) {
     throw new TypeError('willEndCampaignOnThisDeath requires a Campaign-like object with crew[]');
   }
-  return campaign.crew.filter(member => !member.flatlined).length === 1;
+  return (
+    campaign.crew.filter(member => !member.flatlined).length === 1 ||
+    (campaign.activeRun?.contract !== null &&
+      campaign.activeRun?.contract !== undefined &&
+      isScoreContract(campaign.activeRun.contract))
+  );
+}
+
+/**
+ * True when settling this job result will transition the campaign to ENDED.
+ * The shell uses this before showing a debrief so terminal outcomes can bypass
+ * `<crash-dump>` and proceed directly to the Chronicle summary.
+ */
+export function willEndCampaignAfterResult(
+  campaign: CampaignLike,
+  outcome: Outcome,
+  completed: boolean
+): boolean {
+  if (outcome !== OUTCOME.DEATH && outcome !== OUTCOME.EXIT) {
+    throw new Error(`willEndCampaignAfterResult: unknown outcome "${outcome}"`);
+  }
+  if (typeof completed !== 'boolean') {
+    throw new TypeError('willEndCampaignAfterResult: completed must be boolean');
+  }
+  if (outcome === OUTCOME.DEATH && willEndCampaignOnThisDeath(campaign)) return true;
+  const contract = campaign.activeRun?.contract;
+  if (outcome === OUTCOME.EXIT && completed && contract && isScoreContract(contract)) return true;
+  return Boolean(
+    campaign.arc?.scoreRevealed &&
+    (campaign.clockJobsTaken ?? 0) >= CLOCK_ACT2_DEADLINE_JOBS &&
+    !campaign.arc.scoreAttempted
+  );
 }
 
 export function buildCrew(rng: Rng): Crew[] {
@@ -338,6 +372,9 @@ export class Campaign {
   get endReason(): CampaignEndReason | null {
     if (this.state !== CAMPAIGN_STATE.ENDED) return null;
     if (this.arc.scoreCompleted) return 'score-complete';
+    if (this.arc.scoreAttempted && this.arc.arcStage === 'score') {
+      return 'decker-flatlined-score';
+    }
     if (
       this.arc.scoreRevealed &&
       this.clockJobsTaken >= CLOCK_ACT2_DEADLINE_JOBS &&
@@ -424,7 +461,13 @@ export class Campaign {
   backfillRecruitsIfEligible(): void {
     if (this.state !== CAMPAIGN_STATE.HUB) return;
     if (this.recruitedThisVisit) return;
-    if (this.rep < REP.RECRUIT_THRESHOLD && !this.pendingRecruitReward) return;
+    if (
+      this.rep < REP.RECRUIT_THRESHOLD &&
+      !this.pendingRecruitReward &&
+      !this.#needsReplacementDecker()
+    ) {
+      return;
+    }
     if (this.availableRecruits.length > 0) return;
     this.availableRecruits = this.generateRecruits();
     this.#persist();
@@ -519,6 +562,10 @@ export class Campaign {
       isScoreContract(this.activeRun.contract) &&
       outcome === OUTCOME.EXIT &&
       completed;
+    const failedScoreRun =
+      this.activeRun.contract !== null &&
+      isScoreContract(this.activeRun.contract) &&
+      outcome === OUTCOME.DEATH;
 
     if (outcome === OUTCOME.DEATH) {
       this.flatlineMember(this.deployedMemberId);
@@ -550,6 +597,13 @@ export class Campaign {
     this.activeRun = null;
     this.deployedMemberId = null;
 
+    if (failedScoreRun) {
+      this.state = CAMPAIGN_STATE.ENDED;
+      this.#tearDownHubWorld();
+      this.#persist();
+      return;
+    }
+
     if (this.crew.every(member => member.flatlined)) {
       this.state = CAMPAIGN_STATE.ENDED;
       this.#tearDownHubWorld();
@@ -574,6 +628,7 @@ export class Campaign {
     if (this.state !== CAMPAIGN_STATE.HUB) return false;
     if (this.arc.arcStage !== 'act-3') return false;
     if (this.arc.scoreAttempted || this.arc.scoreCompleted) return false;
+    if (!this.hasLivingDecker) return false;
     return this.#scoreTargetSiteOrNull() !== null;
   }
 
@@ -625,7 +680,7 @@ export class Campaign {
         arcStage: 'score',
         locationSiteId: target.id,
       },
-      reward: { credits: 0, repDelta: 0 },
+      reward: { credits: SCORE_CREDITS_REWARD, repDelta: 0 },
     };
   }
 
@@ -724,6 +779,14 @@ export class Campaign {
    * Returns an empty array when Rep is below the recruitment threshold.
    */
   generateRecruits(): Crew[] {
+    if (this.#needsReplacementDecker()) {
+      const replacement = buildCrewMember('decker', { x: 0, y: 0 }, this.rng, {
+        id: `recruit-decker-${this.rng.intRange(0, 0xffff).toString(16)}`,
+        excludeCallsigns: this.allUsedCallsigns(),
+      });
+      this.rewardRecruitIds.add(replacement.id);
+      return [replacement];
+    }
     const rewardRecruit = this.pendingRecruitReward;
     if (this.rep < REP.RECRUIT_THRESHOLD && !rewardRecruit) return [];
     const count =
@@ -1205,6 +1268,11 @@ export class Campaign {
     this.arc.deckerRecruited = true;
   }
 
+  /** A pre-Score flatline opens one free Terminal lead instead of dead-ending the campaign. */
+  #needsReplacementDecker(): boolean {
+    return this.arc.scoreRevealed && !this.arc.scoreAttempted && !this.hasLivingDecker;
+  }
+
   #ensureScoreTargetDesignated(): void {
     const scoreTargets = this.siteRoster.filter(site => site.scoreTarget);
     if (scoreTargets.length > 1) {
diff --git a/src/game/campaignSummary.ts b/src/game/campaignSummary.ts
new file mode 100644
index 0000000..0387ab9
--- /dev/null
+++ b/src/game/campaignSummary.ts
@@ -0,0 +1,236 @@
+import type { CampaignEndReason } from '../types.js';
+
+export const CAMPAIGN_HISTORY_CAP = 50;
+
+export type CampaignSummaryResult = 'win' | 'loss';
+
+export type CampaignSummaryCrew = {
+  callsign: string;
+  archetype: string;
+  flatlined: boolean;
+};
+
+export type CampaignSummary = {
+  campaignId: string;
+  completedAt: string;
+  result: CampaignSummaryResult;
+  endReason: CampaignEndReason;
+  seed: number;
+  completedJobs: number;
+  rep: number;
+  credits: number;
+  crewRoster: CampaignSummaryCrew[];
+};
+
+type EndedCampaignLike = {
+  id: string;
+  state: string;
+  endReason: CampaignEndReason | null;
+  seed: number;
+  completedJobs: number;
+  rep: number;
+  credits: number;
+  crew: Array<{
+    id: string;
+    callsign: string | null;
+    archetype: string;
+    flatlined: boolean;
+  }>;
+};
+
+const END_REASONS: readonly CampaignEndReason[] = [
+  'crew-wipe',
+  'clock-expired',
+  'decker-flatlined-score',
+  'score-complete',
+];
+
+export function buildCampaignSummary(
+  campaign: EndedCampaignLike,
+  completedAt: string
+): CampaignSummary {
+  if (!campaign || typeof campaign !== 'object') {
+    throw new TypeError('buildCampaignSummary requires a Campaign-like object');
+  }
+  if (campaign.state !== 'ENDED') {
+    throw new Error(`buildCampaignSummary requires an ENDED campaign, got ${campaign.state}`);
+  }
+  if (!campaign.endReason) {
+    throw new Error('buildCampaignSummary requires a campaign end reason');
+  }
+
+  return validateCampaignSummary({
+    campaignId: campaign.id,
+    completedAt,
+    result: campaign.endReason === 'score-complete' ? 'win' : 'loss',
+    endReason: campaign.endReason,
+    seed: campaign.seed,
+    completedJobs: campaign.completedJobs,
+    rep: campaign.rep,
+    credits: campaign.credits,
+    crewRoster: campaign.crew.map(member => ({
+      callsign: member.callsign ?? member.id,
+      archetype: member.archetype,
+      flatlined: member.flatlined,
+    })),
+  });
+}
+
+export function validateCampaignSummary(value: unknown): CampaignSummary {
+  if (!isPlainObject(value)) {
+    throw new TypeError('CampaignSummary must be a plain object');
+  }
+  const summary = value as Record<string, unknown>;
+  requireExactKeys(summary, [
+    'campaignId',
+    'completedAt',
+    'result',
+    'endReason',
+    'seed',
+    'completedJobs',
+    'rep',
+    'credits',
+    'crewRoster',
+  ]);
+  const campaignId = requireNonEmptyString(summary.campaignId, 'CampaignSummary.campaignId');
+  const completedAt = requireIsoTimestamp(summary.completedAt);
+  if (summary.result !== 'win' && summary.result !== 'loss') {
+    throw new Error(`CampaignSummary.result must be win or loss, got ${summary.result}`);
+  }
+  if (!END_REASONS.includes(summary.endReason as CampaignEndReason)) {
+    throw new Error(`CampaignSummary.endReason is invalid: ${summary.endReason}`);
+  }
+  const endReason = summary.endReason as CampaignEndReason;
+  const expectedResult: CampaignSummaryResult = endReason === 'score-complete' ? 'win' : 'loss';
+  if (summary.result !== expectedResult) {
+    throw new Error(`CampaignSummary ${endReason} must have result ${expectedResult}`);
+  }
+  const seed = requireFiniteNumber(summary.seed, 'CampaignSummary.seed');
+  const completedJobs = requireNonNegativeInteger(
+    summary.completedJobs,
+    'CampaignSummary.completedJobs'
+  );
+  const rep = requireNonNegativeInteger(summary.rep, 'CampaignSummary.rep');
+  const credits = requireNonNegativeInteger(summary.credits, 'CampaignSummary.credits');
+  if (!Array.isArray(summary.crewRoster)) {
+    throw new TypeError('CampaignSummary.crewRoster must be an array');
+  }
+  const crewRoster = summary.crewRoster.map((member, index) => validateCrew(member, index));
+
+  return {
+    campaignId,
+    completedAt,
+    result: summary.result,
+    endReason,
+    seed,
+    completedJobs,
+    rep,
+    credits,
+    crewRoster,
+  };
+}
+
+export function normalizeCampaignHistory(value: unknown): CampaignSummary[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) {
+    throw new TypeError('campaignHistory must be an array');
+  }
+  const seen = new Set<string>();
+  const history: CampaignSummary[] = [];
+  for (const candidate of value) {
+    const summary = validateCampaignSummary(candidate);
+    if (seen.has(summary.campaignId)) continue;
+    seen.add(summary.campaignId);
+    history.push(summary);
+    if (history.length === CAMPAIGN_HISTORY_CAP) break;
+  }
+  return history;
+}
+
+export function archiveCampaignSummary(
+  history: readonly CampaignSummary[],
+  candidate: CampaignSummary
+): { history: CampaignSummary[]; summary: CampaignSummary; added: boolean } {
+  const normalized = normalizeCampaignHistory(history);
+  const summary = validateCampaignSummary(candidate);
+  const existing = normalized.find(entry => entry.campaignId === summary.campaignId);
+  if (existing) {
+    return { history: normalized, summary: existing, added: false };
+  }
+  return {
+    history: [summary, ...normalized].slice(0, CAMPAIGN_HISTORY_CAP),
+    summary,
+    added: true,
+  };
+}
+
+export function cloneCampaignSummary(summary: CampaignSummary): CampaignSummary {
+  return {
+    ...summary,
+    crewRoster: summary.crewRoster.map(member => ({ ...member })),
+  };
+}
+
+function validateCrew(value: unknown, index: number): CampaignSummaryCrew {
+  if (!isPlainObject(value)) {
+    throw new TypeError(`CampaignSummary.crewRoster[${index}] must be a plain object`);
+  }
+  const member = value as Record<string, unknown>;
+  requireExactKeys(member, ['callsign', 'archetype', 'flatlined']);
+  if (typeof member.flatlined !== 'boolean') {
+    throw new TypeError(`CampaignSummary.crewRoster[${index}].flatlined must be boolean`);
+  }
+  return {
+    callsign: requireNonEmptyString(
+      member.callsign,
+      `CampaignSummary.crewRoster[${index}].callsign`
+    ),
+    archetype: requireNonEmptyString(
+      member.archetype,
+      `CampaignSummary.crewRoster[${index}].archetype`
+    ),
+    flatlined: member.flatlined,
+  };
+}
+
+function requireIsoTimestamp(value: unknown): string {
+  const timestamp = requireNonEmptyString(value, 'CampaignSummary.completedAt');
+  const parsed = new Date(timestamp);
+  if (!Number.isFinite(parsed.getTime()) || parsed.toISOString() !== timestamp) {
+    throw new Error(`CampaignSummary.completedAt must be an ISO timestamp, got ${timestamp}`);
+  }
+  return timestamp;
+}
+
+function requireNonEmptyString(value: unknown, label: string): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string`);
+  }
+  return value;
+}
+
+function requireFiniteNumber(value: unknown, label: string): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new TypeError(`${label} must be a finite number`);
+  }
+  return value;
+}
+
+function requireNonNegativeInteger(value: unknown, label: string): number {
+  if (!Number.isInteger(value) || (value as number) < 0) {
+    throw new RangeError(`${label} must be a non-negative integer`);
+  }
+  return value as number;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function requireExactKeys(value: Record<string, unknown>, expected: readonly string[]): void {
+  const actual = Object.keys(value).sort();
+  const wanted = [...expected].sort();
+  if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) {
+    throw new TypeError(`CampaignSummary keys must be exactly ${wanted.join(', ')}`);
+  }
+}
diff --git a/src/game/cyber/CyberAvatar.ts b/src/game/cyber/CyberAvatar.ts
index c4b761d..07e7514 100644
--- a/src/game/cyber/CyberAvatar.ts
+++ b/src/game/cyber/CyberAvatar.ts
@@ -1,8 +1,9 @@
 /**
  * P3.M3.3 — the Decker's avatar on the Cyberspace grid.
  *
- * A plain `Entity` (NOT a `Crew` — no inventory, gear, or perks): the cyber
- * grid has its own verbs. Pools derive from the Decker's named cyber stats:
+ * A plain `Entity` (NOT a `Crew` — no inventory or gear): the cyber grid has
+ * its own verbs, including the Decker's Override signature against ICE. Pools
+ * derive from the Decker's named cyber stats:
  *
  *   - `maxHp = decker.ram` — ICE damage burns RAM; zero RAM = flatline
  *     (avatar death routes through the existing DEATH path; scope decision #3).
@@ -16,7 +17,10 @@
  * also carries `intrusionStrength`, so a flag (not the stat) marks the avatar.
  */
 import { Entity } from '../Entity.js';
+import { canOverride, overrideDrone } from '../droneOverride.js';
 import { CYBER_AVATAR_HIT_CHANCE, CYBER_AVATAR_MAX_AP, FACTION } from '../constants.js';
+import type { World } from '../World.js';
+import type { Rng } from '../../rng.js';
 
 export type CyberAvatarInit = {
   id: string;
@@ -61,6 +65,16 @@ export class CyberAvatar extends Entity {
     return this.damageReduction;
   }
 
+  /** Decker Override translated into the digital layer: ICE is hostile code. */
+  canOverride(world: World, target: Entity | null) {
+    return canOverride(world, this, target);
+  }
+
+  /** Attempt to flip ICE to the avatar's faction for the normal override duration. */
+  overrideDrone(world: World, target: Entity, rng: Rng) {
+    return overrideDrone(world, this, target, rng);
+  }
+
   constructor({
     id,
     x,
diff --git a/src/game/cyber/ProbeIce.ts b/src/game/cyber/ProbeIce.ts
index 27e9489..7ce0534 100644
--- a/src/game/cyber/ProbeIce.ts
+++ b/src/game/cyber/ProbeIce.ts
@@ -21,7 +21,8 @@ import type { Entity } from '../Entity.js';
 import type { World } from '../World.js';
 import type { Rng } from '../../rng.js';
 
-export const PROBE_ICE_HP = 3;
+export const PROBE_ICE_HP = 2;
+export const PROBE_ICE_AP = 2;
 export const PROBE_ICE_DAMAGE = 1;
 export const PROBE_ICE_SIGHT_RANGE = 6;
 
@@ -33,12 +34,14 @@ export class ProbeIce extends PatrolHostile {
 
   constructor({
     maxHp = PROBE_ICE_HP,
+    maxAp = PROBE_ICE_AP,
     sightRange = PROBE_ICE_SIGHT_RANGE,
     patrolWaypoints,
     ...props
   }: ProbeIceProps) {
     super({
       ...props,
+      maxAp,
       maxHp,
       sightRange,
       glyph: PROBE_ICE_GLYPH,
diff --git a/src/input/applyIntent.ts b/src/input/applyIntent.ts
index 090decc..0325470 100644
--- a/src/input/applyIntent.ts
+++ b/src/input/applyIntent.ts
@@ -22,9 +22,9 @@
  * keymap layer. The `doSpecial` dispatcher below routes it to the right verb
  * based on which methods the active player class exposes — `canVault` → vault,
  * `canSlide` → slide, `canDeploy` → deploy, `canOverride` → override (the
- * Decker resolves a drone along the aim ray, like fire). This keeps the input
- * surface symmetric across archetypes (one key, one touch button) and stays
- * out of the player's way:
+ * Decker resolves the nearest visible drone in the aimed eight-way sector).
+ * This keeps the input surface symmetric across archetypes (one key, one touch
+ * button) and stays out of the player's way:
  * the keymap doesn't need to know which class is in play, and the intent
  * dispatcher doesn't need an explicit archetype switch.
  *
@@ -58,9 +58,11 @@ import { Door } from '../game/entities/Door.js';
 import { DenyTarget } from '../game/entities/DenyTarget.js';
 import { EVENT } from '../game/events.js';
 import { TILE } from '../game/constants.js';
+import { Hostile } from '../game/Hostile.js';
 import type { KeyItem } from '../types.js';
 import type { Archetype } from '../game/archetypes/index.js';
 import type { CyberAvatar } from '../game/cyber/CyberAvatar.js';
+import type { Entity } from '../game/Entity.js';
 import type { World } from '../game/World.js';
 import type { TurnQueue } from '../game/TurnQueue.js';
 import type { Rng } from '../rng.js';
@@ -79,9 +81,8 @@ export type ApplyIntentContext = {
   world: World;
   /**
    * P3.M3.6: the acting body — a crew archetype in Meatspace, the
-   * `CyberAvatar` on the grid. The avatar exposes none of the perk or
-   * inventory capabilities, so every capability-sniffed branch (`doSpecial`,
-   * loot, consumables) degrades to its existing refusal path.
+   * `CyberAvatar` on the grid. The avatar exposes Override but no inventory
+   * capabilities, so loot and consumables retain their refusal paths.
    */
   player: Archetype | CyberAvatar;
   queue: TurnQueue;
@@ -375,15 +376,18 @@ function doSpecial(intent: Intent, ctx: ApplyIntentContext) {
 }
 
 /**
- * Walk the aim ray for the Decker's Override perk and resolve the first hostile
- * drone in reach, then attempt the hijack. Mirrors `pickFireTarget`'s geometry
- * (bounded by `OVERRIDE_RANGE`, LOS-gated) so the target the picker lands on is
- * exactly the one the resolver will act on. A failed roll trips the alarm; an
- * out-of-reach ray or non-drone target yields a legible deny, not a crash.
+ * Acquire a drone in the Decker's aimed eight-way sector and attempt the
+ * hijack. Range, LOS, and perception match the resolver and combat targeting;
+ * a failed roll trips the alarm, while an empty sector yields a legible deny.
  */
+type OverrideActor = ApplyIntentContext['player'] & {
+  canOverride(world: World, target: Entity | null): ReturnType<Decker['canOverride']>;
+  overrideDrone(world: World, target: Entity, rng: Rng): ReturnType<Decker['overrideDrone']>;
+};
+
 function doOverride(intent: Intent, ctx: ApplyIntentContext) {
   const { world, player, log } = ctx;
-  const decker = player as Decker;
+  const decker = player as OverrideActor;
   const playerLabel = entityLabel(player);
   const target = pickOverrideTarget(ctx, intent.dx!, intent.dy!);
   const check = decker.canOverride(world, target);
@@ -405,23 +409,57 @@ function doOverride(intent: Intent, ctx: ApplyIntentContext) {
 }
 
 /**
- * First hostile along (dx, dy) within `OVERRIDE_RANGE` and LOS. Returns `null`
- * when the ray leaves the map, exceeds range, hits a wall, or finds no entity —
- * `canOverride` turns that `null` into a `not-overridable` deny.
+ * Nearest live hostile in the aimed eight-way sector within `OVERRIDE_RANGE`
+ * and LOS. The 22.5-degree half-angle partitions arbitrary target offsets
+ * across the eight directions supplied by keyboard and touch controls, so a
+ * moving Probe does not need to be perfectly collinear with the avatar.
  */
 function pickOverrideTarget(ctx: ApplyIntentContext, dx: number, dy: number) {
   const { world, player } = ctx;
   const blockers = world.blockerKeys();
-  for (let step = 1; step <= OVERRIDE_RANGE; step++) {
-    const x = player.x + dx * step;
-    const y = player.y + dy * step;
-    if (!world.grid.inBounds(x, y)) return null;
-    if (!withinRange(player.x, player.y, x, y, OVERRIDE_RANGE)) return null;
-    if (!hasLineOfSight(world.grid, player.x, player.y, x, y, { blockers })) return null;
-    const e = world.entityAt(x, y);
-    if (e) return e;
+  let best: Hostile | null = null;
+  let bestDistanceSquared = Infinity;
+  let bestAlignment = -Infinity;
+
+  for (const entity of world.entities.values()) {
+    if (!(entity instanceof Hostile) || !entity.alive) continue;
+    const offsetX = entity.x - player.x;
+    const offsetY = entity.y - player.y;
+    if (!isInAimSector(dx, dy, offsetX, offsetY)) continue;
+    if (!withinRange(player.x, player.y, entity.x, entity.y, OVERRIDE_RANGE)) continue;
+    if (
+      !hasLineOfSight(world.grid, player.x, player.y, entity.x, entity.y, {
+        blockers,
+      })
+    ) {
+      continue;
+    }
+    if (isConcealedFromPlayer(entity, player, world)) continue;
+
+    const distanceSquared = offsetX * offsetX + offsetY * offsetY;
+    const alignment = offsetX * dx + offsetY * dy;
+    if (
+      distanceSquared < bestDistanceSquared ||
+      (distanceSquared === bestDistanceSquared && alignment > bestAlignment) ||
+      (distanceSquared === bestDistanceSquared &&
+        alignment === bestAlignment &&
+        best !== null &&
+        entity.id < best.id)
+    ) {
+      best = entity;
+      bestDistanceSquared = distanceSquared;
+      bestAlignment = alignment;
+    }
   }
-  return null;
+  return best;
+}
+
+function isInAimSector(dx: number, dy: number, offsetX: number, offsetY: number): boolean {
+  const aimMagnitude = Math.hypot(dx, dy);
+  const targetMagnitude = Math.hypot(offsetX, offsetY);
+  if (aimMagnitude === 0 || targetMagnitude === 0) return false;
+  const cosine = (dx * offsetX + dy * offsetY) / (aimMagnitude * targetMagnitude);
+  return cosine >= Math.cos(Math.PI / 8) - Number.EPSILON;
 }
 
 function doDeploy(intent: Intent, ctx: ApplyIntentContext) {
diff --git a/src/types.ts b/src/types.ts
index f64f750..98b19e3 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -17,7 +17,11 @@ export type GridPoint = { x: number; y: number };
 export type CampaignArcStage = 'act-1' | 'act-2' | 'act-3' | 'score';
 
 /** Why a campaign reached `ENDED` — drives terminal debrief copy in the shell. */
-export type CampaignEndReason = 'crew-wipe' | 'clock-expired' | 'score-complete';
+export type CampaignEndReason =
+  | 'crew-wipe'
+  | 'clock-expired'
+  | 'decker-flatlined-score'
+  | 'score-complete';
 
 /**
  * A JSON-safe value. The persistence layer's opaque entity property bag
@@ -249,26 +253,8 @@ export type LocationSite = {
   site?: LocationToken;
 };
 
-export type GameOverCrewStub = { callsign: string; archetype: string; flatlined: boolean };
-
-/** Terminal campaign loss — crew wipe, clock deadline, or last-operator death. */
-export type GameOverTelemetry = {
-  campaignEndReason?: Exclude<CampaignEndReason, 'score-complete'>;
-  campaignTerminal?: boolean;
-  crewRoster?: GameOverCrewStub[];
-  salvage?: import('./game/salvage.js').TypedSalvage;
-  seed?: number;
-  cause?: string | null;
-  archetype?: string;
-};
-
 export type Telemetry = {
-  outcome: 'death' | 'exit' | 'campaign-over';
-  campaignEndReason?: CampaignEndReason;
-  campaignTerminal?: boolean;
-  crewRoster?: GameOverCrewStub[];
-  /** Typed-salvage wallet snapshot at the moment the run/campaign ends. */
-  salvage?: import('./game/salvage.js').TypedSalvage;
+  outcome: 'death' | 'exit';
   archetype?: string;
   turn?: number;
   kills?: number;
diff --git a/sw-core.js b/sw-core.js
index 0fb5872..b3f1979 100644
--- a/sw-core.js
+++ b/sw-core.js
@@ -61,6 +61,7 @@ const CacheConfig = {
       '/src/game/archetypes/Razor.js',
       '/src/game/archetypes/Tech.js',
       '/src/game/Campaign.js',
+      '/src/game/campaignSummary.js',
       '/src/game/Combat.js',
       '/src/game/combatTurnPipeline.js',
       '/src/game/constants.js',
diff --git a/sw-dev.js b/sw-dev.js
index 33f02aa..7a0e5dd 100644
--- a/sw-dev.js
+++ b/sw-dev.js
@@ -1,5 +1,5 @@
 // Service Worker for Kernel Panic - Development Version
-const VERSION = '0.2.12-dev';
+const VERSION = '0.2.15-dev';
 importScripts(`/sw-core.js?v=${VERSION}`);
 
 const cacheConfig = CacheConfig.create(VERSION);
diff --git a/sw.js b/sw.js
index 2039fae..0b5e68d 100644
--- a/sw.js
+++ b/sw.js
@@ -1,6 +1,6 @@
 // Service Worker for Kernel Panic - Production Version
 // Import shared caching core with cache-busting query parameter
-const VERSION = '0.2.10';
+const VERSION = '0.2.15';
 importScripts(`/sw-core.js?v=${VERSION}`);
 
 const cacheConfig = CacheConfig.create(VERSION);
diff --git a/tests/unit/DataStore.test.ts b/tests/unit/DataStore.test.ts
new file mode 100644
index 0000000..5de6c29
--- /dev/null
+++ b/tests/unit/DataStore.test.ts
@@ -0,0 +1,66 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { CAMPAIGN_HISTORY_CAP, type CampaignSummary } from '../../src/game/campaignSummary.js';
+
+const STORAGE_KEY = 'kp:data';
+
+class MemoryStorage {
+  #values = new Map<string, string>();
+
+  getItem(key: string): string | null {
+    return this.#values.get(key) ?? null;
+  }
+
+  setItem(key: string, value: string): void {
+    this.#values.set(key, value);
+  }
+}
+
+function summary(index: number): CampaignSummary {
+  return {
+    campaignId: `campaign-${index}`,
+    completedAt: '2026-06-14T19:30:00.000Z',
+    result: 'win',
+    endReason: 'score-complete',
+    seed: index,
+    completedJobs: index,
+    rep: 50,
+    credits: index * 100,
+    crewRoster: [{ callsign: 'Phreak', archetype: 'Decker', flatlined: false }],
+  };
+}
+
+test('DataStore migrates legacy data and archives idempotent capped campaign history', async () => {
+  const localStorage = new MemoryStorage();
+  (globalThis as unknown as { window: { localStorage: MemoryStorage } }).window = { localStorage };
+  localStorage.setItem(STORAGE_KEY, JSON.stringify({ prefs: {}, runs: [], campaign: null }));
+  const { default: dataStore } = await import('../../src/DataStore.js');
+
+  await dataStore.init();
+  assert.deepEqual(dataStore.campaignHistory, []);
+
+  const original = summary(0);
+  const first = dataStore.archiveCampaign(original);
+  const duplicate = dataStore.archiveCampaign({
+    ...original,
+    completedAt: '2026-06-15T19:30:00.000Z',
+    completedJobs: 999,
+  });
+  assert.deepEqual(duplicate, first, 'the first archived record remains canonical');
+
+  for (let index = 1; index <= CAMPAIGN_HISTORY_CAP + 5; index++) {
+    dataStore.archiveCampaign(summary(index));
+  }
+  assert.equal(dataStore.campaignHistory.length, CAMPAIGN_HISTORY_CAP);
+  assert.equal(dataStore.campaignHistory[0].campaignId, `campaign-${CAMPAIGN_HISTORY_CAP + 5}`);
+  assert.equal(
+    dataStore.campaignHistory.some(entry => entry.campaignId === original.campaignId),
+    false
+  );
+
+  const stored = JSON.parse(localStorage.getItem(STORAGE_KEY) ?? '{}') as {
+    campaignHistory?: CampaignSummary[];
+  };
+  assert.equal(stored.campaignHistory?.length, CAMPAIGN_HISTORY_CAP);
+});
diff --git a/tests/unit/game/Campaign.test.ts b/tests/unit/game/Campaign.test.ts
index 63d4e7b..7b3d938 100644
--- a/tests/unit/game/Campaign.test.ts
+++ b/tests/unit/game/Campaign.test.ts
@@ -6,9 +6,11 @@ import {
   CAMPAIGN_STATE,
   CLOCK_ACT2_DEADLINE_JOBS,
   CLOCK_ACT2_GRACE_JOBS,
+  SCORE_CREDITS_REWARD,
   SITE_ROSTER_CAP,
   buildCrew,
   defaultCampaignArc,
+  willEndCampaignAfterResult,
   willEndCampaignOnThisDeath,
 } from '../../../src/game/Campaign.js';
 import { OUTCOME, RUN_STATE } from '../../../src/game/Run.js';
@@ -1015,6 +1017,98 @@ test('P3.M1.5: endReason distinguishes score win, clock loss, and crew wipe', ()
   assert.equal(crewWipe.endReason, 'crew-wipe');
 });
 
+test('terminal result detection bypasses debrief for Score, terminal death, and Clock loss', () => {
+  const scoreCampaign = new Campaign({
+    seed: 44,
+    rep: 60,
+    completedJobs: 9,
+    siteRoster: [
+      validSite({
+        id: 'score',
+        seed: '100',
+        tier: 'score',
+        scoreTarget: true,
+        principal: { id: 'matsuda', label: 'Matsuda', groups: ['corp'] },
+      }),
+      validSite({
+        id: 'case-1',
+        seed: '101',
+        principal: { id: 'matsuda', label: 'Matsuda', groups: ['corp'] },
+      }),
+      validSite({
+        id: 'case-2',
+        seed: '102',
+        principal: { id: 'matsuda', label: 'Matsuda', groups: ['corp'] },
+      }),
+    ],
+  });
+  scoreCampaign.arc.arcStage = 'act-3';
+  const decker = scoreCampaign.crew.find(member => member.archetype === 'Decker');
+  assert.ok(decker);
+  scoreCampaign.deployCrewMember(decker.id, scoreCampaign.buildScoreContract());
+  assert.equal(willEndCampaignAfterResult(scoreCampaign, OUTCOME.EXIT, true), true);
+  assert.equal(willEndCampaignAfterResult(scoreCampaign, OUTCOME.EXIT, false), false);
+  assert.equal(willEndCampaignAfterResult(scoreCampaign, OUTCOME.DEATH, false), true);
+
+  const finalOperator = new Campaign({ seed: 45 });
+  finalOperator.crew.slice(1).forEach(member => {
+    member.flatlined = true;
+  });
+  finalOperator.deployCrewMember(finalOperator.crew[0].id, fakeContract());
+  assert.equal(willEndCampaignAfterResult(finalOperator, OUTCOME.DEATH, false), true);
+
+  const clockLoss = new Campaign({
+    seed: 46,
+    rep: 60,
+    completedJobs: 4,
+    clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS,
+  });
+  clockLoss.state = CAMPAIGN_STATE.COMBAT;
+  assert.equal(willEndCampaignAfterResult(clockLoss, OUTCOME.EXIT, true), true);
+});
+
+test('completed Score extraction settles synchronously before the exit move callback returns', () => {
+  let campaign!: Campaign;
+  campaign = new Campaign({
+    seed: 47,
+    rep: 60,
+    completedJobs: 9,
+    onResult: result => {
+      campaign.onJobEnd({
+        outcome: result.outcome,
+        completed: result.telemetry.objectiveComplete === true,
+      });
+    },
+    siteRoster: [
+      validSite({
+        id: 'score',
+        seed: '100',
+        tier: 'score',
+        scoreTarget: true,
+        principal: { id: 'matsuda', label: 'Matsuda', groups: ['corp'] },
+      }),
+    ],
+  });
+  campaign.arc.arcStage = 'act-3';
+  const decker = campaign.crew.find(member => member.archetype === 'Decker');
+  assert.ok(decker);
+  const run = campaign.deployCrewMember(decker.id, campaign.buildScoreContract());
+  run.enterCombat();
+  run.cyberspace = { phase: 'resolved', objectiveComplete: true };
+  assert.ok(run.world && run.player && run.exitTile);
+
+  run.world.relocateEntity(run.player, run.exitTile.x, run.exitTile.y);
+
+  assert.equal(run.state, RUN_STATE.RESULT, 'the captured Run is no longer turn-playable');
+  assert.equal(campaign.state, CAMPAIGN_STATE.ENDED);
+  assert.equal(campaign.endReason, 'score-complete');
+  assert.equal(
+    campaign.activeRun,
+    null,
+    'Score settlement tears down the active run synchronously'
+  );
+});
+
 test('P3.M1.5: Clock deadline does not end the campaign after the Score is attempted', () => {
   const campaign = new Campaign({
     seed: 42,
@@ -1070,6 +1164,8 @@ test('P3.M1.7: Score contract is gated to Act 3 and marks attempted on deploymen
   assert.equal(score.objective.kind, OBJECTIVES.DATA_NODE_SLICE);
   assert.equal(score.objective.params?.requiresCyberspace, true);
   assert.equal(score.objective.params?.count, 1);
+  assert.equal(score.reward.credits, SCORE_CREDITS_REWARD);
+  assert.equal(score.reward.repDelta, 0);
 
   const decker = campaign.crew.find(m => m.archetype === 'Decker');
   assert.ok(decker, 'Act 3 campaign should include auto-assigned Decker');
@@ -1079,10 +1175,58 @@ test('P3.M1.7: Score contract is gated to Act 3 and marks attempted on deploymen
   assert.equal(run.contract?.context.locationSiteId, 'score');
 });
 
+test('a flatlined pre-Score Decker creates a free Terminal replacement lead', () => {
+  const campaign = new Campaign({ seed: 42, rep: 60, completedJobs: 4 });
+  const original = campaign.crew.find(member => member.archetype === 'Decker');
+  assert.ok(original);
+  campaign.flatlineMember(original.id);
+  campaign.enterHub();
+
+  assert.equal(campaign.hasLivingDecker, false);
+  assert.equal(campaign.availableRecruits.length, 1);
+  const replacement = campaign.availableRecruits[0];
+  assert.equal(replacement.archetype, 'Decker');
+  campaign.recruit(replacement.id);
+  assert.equal(campaign.hasLivingDecker, true);
+  assert.equal(campaign.recruitedThisVisit, true);
+});
+
+test('the Score remains unavailable until a living replacement Decker is recruited', () => {
+  const scorePrincipal = { id: 'matsuda', label: 'Matsuda', groups: ['corp'] };
+  const campaign = new Campaign({
+    seed: 42,
+    rep: 60,
+    completedJobs: 9,
+    siteRoster: [
+      validSite({
+        id: 'score',
+        seed: '100',
+        tier: 'score',
+        scoreTarget: true,
+        lastVisitedJob: 5,
+        principal: scorePrincipal,
+      }),
+      validSite({ id: 'case-1', seed: '101', lastVisitedJob: 6, principal: scorePrincipal }),
+      validSite({ id: 'case-2', seed: '102', lastVisitedJob: 7, principal: scorePrincipal }),
+    ],
+  });
+  const decker = campaign.crew.find(member => member.archetype === 'Decker');
+  assert.ok(decker);
+  campaign.flatlineMember(decker.id);
+  campaign.enterHub();
+
+  assert.equal(campaign.arcStage, 'act-3');
+  assert.equal(campaign.canAttemptScore(), false);
+  const replacement = campaign.availableRecruits[0];
+  campaign.recruit(replacement.id);
+  assert.equal(campaign.canAttemptScore(), true);
+});
+
 test('P3.M1.7: completed Score contract records campaign win state', () => {
   const scorePrincipal = { id: 'matsuda', label: 'Matsuda', groups: ['corp'] };
   const campaign = new Campaign({
     seed: 42,
+    credits: 25,
     rep: 60,
     completedJobs: 9,
     siteRoster: [
@@ -1108,6 +1252,50 @@ test('P3.M1.7: completed Score contract records campaign win state', () => {
 
   assert.equal(campaign.arc.scoreCompleted, true);
   assert.equal(campaign.state, CAMPAIGN_STATE.ENDED);
+  assert.equal(campaign.credits, 25 + SCORE_CREDITS_REWARD);
+});
+
+test('a Decker flatline during the Score ends the campaign explicitly', () => {
+  const scorePrincipal = { id: 'matsuda', label: 'Matsuda', groups: ['corp'] };
+  const campaign = new Campaign({
+    seed: 42,
+    rep: 60,
+    completedJobs: 9,
+    siteRoster: [
+      validSite({
+        id: 'score',
+        seed: '100',
+        tier: 'score',
+        scoreTarget: true,
+        lastVisitedJob: 5,
+        principal: scorePrincipal,
+      }),
+      validSite({ id: 'case-1', seed: '101', lastVisitedJob: 6, principal: scorePrincipal }),
+      validSite({ id: 'case-2', seed: '102', lastVisitedJob: 7, principal: scorePrincipal }),
+    ],
+  });
+  const decker = campaign.crew.find(member => member.archetype === 'Decker');
+  assert.ok(decker);
+  const run = campaign.deployCrewMember(decker.id, campaign.buildScoreContract());
+  run.enterCombat();
+  assert.equal(
+    willEndCampaignOnThisDeath(campaign),
+    true,
+    'Score death is terminal even with surviving crew'
+  );
+
+  campaign.onJobEnd({ outcome: OUTCOME.DEATH });
+
+  assert.equal(campaign.state, CAMPAIGN_STATE.ENDED);
+  assert.equal(campaign.endReason, 'decker-flatlined-score');
+  assert.ok(
+    campaign.crew.some(member => !member.flatlined),
+    'other survivors do not avert the loss'
+  );
+
+  const restored = restoreCampaign(snapshotCampaign(campaign));
+  assert.equal(restored.state, CAMPAIGN_STATE.ENDED);
+  assert.equal(restored.endReason, 'decker-flatlined-score');
 });
 
 // ─── Recruitment ────────────────────────────────────────────────────────
diff --git a/tests/unit/game/campaignSummary.test.ts b/tests/unit/game/campaignSummary.test.ts
new file mode 100644
index 0000000..a06fcd2
--- /dev/null
+++ b/tests/unit/game/campaignSummary.test.ts
@@ -0,0 +1,151 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { Campaign, CAMPAIGN_STATE, SCORE_CREDITS_REWARD } from '../../../src/game/Campaign.js';
+import {
+  CAMPAIGN_HISTORY_CAP,
+  archiveCampaignSummary,
+  buildCampaignSummary,
+  normalizeCampaignHistory,
+  validateCampaignSummary,
+  type CampaignSummary,
+} from '../../../src/game/campaignSummary.js';
+import { OUTCOME } from '../../../src/game/Run.js';
+import { makeSalvage } from '../../../src/game/salvage.js';
+import type { LocationSite } from '../../../src/types.js';
+
+const COMPLETED_AT = '2026-06-14T19:30:00.000Z';
+
+function validSite(overrides: Partial<LocationSite> = {}): LocationSite {
+  return {
+    id: 'score',
+    seed: '100',
+    mapWidth: 24,
+    mapHeight: 16,
+    label: '// Matsuda server farm',
+    tier: 'score',
+    scoreTarget: true,
+    mutationDeltas: [],
+    seenKeys: [],
+    lastVisitedJob: 5,
+    principal: { id: 'matsuda', label: 'Matsuda', groups: ['corp'] },
+    ...overrides,
+  };
+}
+
+function summary(overrides: Partial<CampaignSummary> = {}): CampaignSummary {
+  return {
+    campaignId: 'campaign-1',
+    completedAt: COMPLETED_AT,
+    result: 'win',
+    endReason: 'score-complete',
+    seed: 42,
+    completedJobs: 10,
+    rep: 67,
+    credits: 1_125,
+    crewRoster: [{ callsign: 'Phreak', archetype: 'Decker', flatlined: false }],
+    ...overrides,
+  };
+}
+
+test('Score completion summary uses post-settlement jobs, Rep, and Credits', () => {
+  const campaign = new Campaign({
+    id: 'campaign-score',
+    seed: 42,
+    credits: 125,
+    rep: 60,
+    completedJobs: 9,
+    siteRoster: [
+      validSite(),
+      validSite({ id: 'case-1', tier: 'roster', scoreTarget: false, seed: '101' }),
+      validSite({ id: 'case-2', tier: 'roster', scoreTarget: false, seed: '102' }),
+    ],
+  });
+  const decker = campaign.crew.find(member => member.archetype === 'Decker');
+  assert.ok(decker);
+  const score = campaign.buildScoreContract();
+  score.reward.repDelta = 7;
+  const run = campaign.deployCrewMember(decker.id, score);
+  run.enterCombat();
+
+  campaign.onJobEnd({
+    outcome: OUTCOME.EXIT,
+    completed: true,
+    salvage: makeSalvage({ scrap: 2, data: 3 }),
+  });
+  const record = buildCampaignSummary(campaign, COMPLETED_AT);
+
+  assert.equal(campaign.state, CAMPAIGN_STATE.ENDED);
+  assert.equal(record.result, 'win');
+  assert.equal(record.endReason, 'score-complete');
+  assert.equal(record.completedJobs, 10);
+  assert.equal(record.rep, 67);
+  assert.equal(record.credits, 125 + SCORE_CREDITS_REWARD);
+  assert.equal('salvage' in record, false);
+  assert.ok(record.crewRoster.some(member => member.archetype === 'Decker'));
+});
+
+test('loss summaries preserve each terminal reason and final roster state', () => {
+  for (const endReason of ['crew-wipe', 'clock-expired', 'decker-flatlined-score'] as const) {
+    const campaign = new Campaign({ id: `campaign-${endReason}`, seed: 9 });
+    campaign.state = CAMPAIGN_STATE.ENDED;
+    campaign.crew[0].flatlined = true;
+    Object.defineProperty(campaign, 'endReason', { value: endReason });
+
+    const record = buildCampaignSummary(campaign, COMPLETED_AT);
+
+    assert.equal(record.result, 'loss');
+    assert.equal(record.endReason, endReason);
+    assert.equal(record.crewRoster[0].flatlined, true);
+  }
+});
+
+test('CampaignSummary validation rejects mismatched outcomes and malformed credit totals', () => {
+  assert.throws(
+    () => validateCampaignSummary(summary({ result: 'loss' })),
+    /score-complete must have result win/
+  );
+  assert.throws(
+    () => validateCampaignSummary({ ...summary(), credits: -1 }),
+    /credits must be a non-negative integer/
+  );
+});
+
+test('legacy history defaults empty and imported history deduplicates then trims', () => {
+  assert.deepEqual(normalizeCampaignHistory(undefined), []);
+  const imported = Array.from({ length: CAMPAIGN_HISTORY_CAP + 5 }, (_, index) =>
+    summary({ campaignId: `campaign-${index}` })
+  );
+  imported.splice(1, 0, summary({ campaignId: 'campaign-0', completedJobs: 999 }));
+
+  const normalized = normalizeCampaignHistory(imported);
+
+  assert.equal(normalized.length, CAMPAIGN_HISTORY_CAP);
+  assert.equal(normalized[0].campaignId, 'campaign-0');
+  assert.equal(normalized[0].completedJobs, 10, 'newest original row wins duplicate conflict');
+});
+
+test('archival is newest-first, preserves an existing record, and caps at 50', () => {
+  const existing = summary({ campaignId: 'campaign-existing', completedAt: COMPLETED_AT });
+  const duplicate = summary({
+    campaignId: 'campaign-existing',
+    completedAt: '2026-06-15T19:30:00.000Z',
+    completedJobs: 99,
+  });
+  const duplicateResult = archiveCampaignSummary([existing], duplicate);
+  assert.equal(duplicateResult.added, false);
+  assert.deepEqual(duplicateResult.summary, existing);
+
+  const full = Array.from({ length: CAMPAIGN_HISTORY_CAP }, (_, index) =>
+    summary({ campaignId: `campaign-${index}` })
+  );
+  const newest = summary({ campaignId: 'campaign-newest' });
+  const added = archiveCampaignSummary(full, newest);
+  assert.equal(added.added, true);
+  assert.equal(added.history.length, CAMPAIGN_HISTORY_CAP);
+  assert.equal(added.history[0].campaignId, 'campaign-newest');
+  assert.equal(
+    added.history.some(entry => entry.campaignId === 'campaign-49'),
+    false
+  );
+});
diff --git a/tests/unit/game/cyber/ProbeIce.test.ts b/tests/unit/game/cyber/ProbeIce.test.ts
index 02ad293..dcc0977 100644
--- a/tests/unit/game/cyber/ProbeIce.test.ts
+++ b/tests/unit/game/cyber/ProbeIce.test.ts
@@ -16,6 +16,8 @@ import { ProbeIce } from '../../../../src/game/cyber/ProbeIce.js';
 import { PATROL_STATE } from '../../../../src/game/ai/PatrolHostile.js';
 import { JackInPoint } from '../../../../src/game/entities/JackInPoint.js';
 import { resolveMelee } from '../../../../src/game/Combat.js';
+import { runPlayerAftermathSteps } from '../../../../src/game/combatTurnPipeline.js';
+import { applyOverride } from '../../../../src/game/droneOverride.js';
 import { EVENT } from '../../../../src/game/events.js';
 import { snapshot, restore } from '../../../../src/game/persistence.js';
 import { buildCrewMember } from '../../../../src/game/archetypes/index.js';
@@ -110,7 +112,8 @@ test('build spawns one probe per patrol ring with explicit ICE stats', () => {
   for (const probe of probes) {
     assert.equal(probe.glyph, '¶');
     assert.equal(probe.displayName, 'Probe');
-    assert.equal(probe.maxHp, 3);
+    assert.equal(probe.maxHp, 2);
+    assert.equal(probe.maxAp, 2);
     assert.equal(probe.sightRange, 6);
     assert.equal(probe.meleeDamage, 1);
     assert.equal(probe.faction, FACTION.CORP);
@@ -147,6 +150,33 @@ test('probe damage is mitigated by ICE resistance with the min-1 rule', () => {
   assert.equal(avatar.hp, avatar.maxHp - 1);
 });
 
+test('overridden Probe ICE fights other ICE and reverts through cyber aftermath', () => {
+  const layer = buildLayer();
+  const probes = probesOf(layer);
+  assert.ok(probes.length >= 2);
+  const ally = probes[0];
+  const target = probes[1];
+  const spot = adjacentFreeTile(layer.world, target);
+  layer.world.relocateEntity(ally, spot.x, spot.y);
+  applyOverride(ally, FACTION.PLAYER);
+
+  let sawAttack = false;
+  for (let turn = 0; turn < 3; turn++) {
+    ally.refreshAp();
+    for (const step of runPlayerAftermathSteps(layer.world, new Rng(turn + 1), {
+      player: layer.avatar,
+    })) {
+      if (step.type === 'overridden-drone' && step.action.type === 'melee') {
+        sawAttack = true;
+      }
+    }
+  }
+
+  assert.equal(sawAttack, true);
+  assert.equal(ally.faction, FACTION.CORP);
+  assert.equal(ally.isOverridden, false);
+});
+
 test('acquisition raises the cyber alarm and converges the pack', () => {
   const layer = buildLayer();
   const avatar = layer.avatar;
diff --git a/tests/unit/game/cyber/cyberPersistence.test.ts b/tests/unit/game/cyber/cyberPersistence.test.ts
index 456924e..cbc4c20 100644
--- a/tests/unit/game/cyber/cyberPersistence.test.ts
+++ b/tests/unit/game/cyber/cyberPersistence.test.ts
@@ -15,6 +15,8 @@ import { CyberAvatar } from '../../../../src/game/cyber/CyberAvatar.js';
 import { EntryPort } from '../../../../src/game/cyber/EntryPort.js';
 import { JackInPoint } from '../../../../src/game/entities/JackInPoint.js';
 import { Decker } from '../../../../src/game/archetypes/Decker.js';
+import { ProbeIce } from '../../../../src/game/cyber/ProbeIce.js';
+import { applyOverride } from '../../../../src/game/droneOverride.js';
 import { Campaign } from '../../../../src/game/Campaign.js';
 import { EVENT } from '../../../../src/game/events.js';
 import {
@@ -29,6 +31,7 @@ import {
   DECKER_BASE_INTRUSION,
   DECKER_BASE_RAM,
   TILE,
+  FACTION,
 } from '../../../../src/game/constants.js';
 import { OBJECTIVES } from '../../../../src/game/hub/Curator.js';
 import { Rng } from '../../../../src/rng.js';
@@ -164,6 +167,25 @@ test('a mid-jack-in snapshot round-trips the layer exactly', () => {
   assert.ok(restored.player instanceof Decker);
 });
 
+test('overridden ICE state round-trips through an active cyber layer', () => {
+  const run = activeRun();
+  const layer = layerOf(run);
+  const probe = Array.from(layer.world.entities.values()).find(
+    (entity): entity is ProbeIce => entity instanceof ProbeIce
+  );
+  assert.ok(probe);
+  applyOverride(probe, FACTION.PLAYER);
+
+  const { run: restored } = restore(structuredClone(snapshot(run)));
+  const restoredProbe = Array.from(layerOf(restored).world.entities.values()).find(
+    (entity): entity is ProbeIce => entity instanceof ProbeIce
+  );
+  assert.ok(restoredProbe);
+  assert.equal(restoredProbe.faction, FACTION.PLAYER);
+  assert.equal(restoredProbe.isOverridden, true);
+  assert.equal(restoredProbe.overrideTurnsRemaining, probe.overrideTurnsRemaining);
+});
+
 test('a restored active run re-wires its cyber listeners', () => {
   const results: RunResult[] = [];
   const { run: restored } = restore(activeRecord(), { onResult: r => results.push(r) });
diff --git a/tests/unit/input/applyIntent.test.ts b/tests/unit/input/applyIntent.test.ts
index 69f936d..7b60892 100644
--- a/tests/unit/input/applyIntent.test.ts
+++ b/tests/unit/input/applyIntent.test.ts
@@ -16,6 +16,8 @@ import { makeSalvage, totalSalvage } from '../../../src/game/salvage.js';
 import { Merc } from '../../../src/game/archetypes/Merc.js';
 import { Razor } from '../../../src/game/archetypes/Razor.js';
 import { Tech } from '../../../src/game/archetypes/Tech.js';
+import { CyberAvatar } from '../../../src/game/cyber/CyberAvatar.js';
+import { ProbeIce } from '../../../src/game/cyber/ProbeIce.js';
 import { Turret } from '../../../src/game/Turret.js';
 import { Skirmisher } from '../../../src/game/ai/Skirmisher.js';
 import { ConsumablePickup } from '../../../src/game/entities/ConsumablePickup.js';
@@ -412,6 +414,76 @@ test('special intent routes to Slide on a Razor (moves 2 tiles, engages stealth)
   assert.equal(player.stealthed, true);
 });
 
+test('special intent routes CyberAvatar Override against Probe ICE', () => {
+  const grid = new Grid(8, 5);
+  const bus = new EventBus();
+  const world = new World(grid, { events: bus });
+  const avatar = new CyberAvatar({
+    id: 'cyber-avatar-0',
+    x: 1,
+    y: 2,
+    ram: 8,
+    intrusionStrength: 2,
+    iceResistance: 1,
+  });
+  const probe = new ProbeIce({ id: 'probe-ice-0', x: 3, y: 2 });
+  world.addEntity(avatar);
+  world.addEntity(probe);
+  probe.bindToBus(bus);
+  const log: string[] = [];
+  const ctx = {
+    world,
+    player: avatar,
+    queue: new TurnQueue([FACTION.PLAYER, FACTION.CORP]),
+    rng: { next: () => 0 },
+    log: (line: string) => log.push(line),
+    advanceTurn: () => {},
+    resetInputModes: () => {},
+    onPlayerAction: () => {},
+  };
+
+  applyIntent({ type: 'special', dx: 1, dy: 0 }, ctx);
+
+  assert.equal(probe.faction, FACTION.PLAYER);
+  assert.equal(avatar.ap, avatar.maxAp - AP_COST.OVERRIDE);
+  assert.ok(log.some(line => line.includes('OVERRIDES Probe')));
+});
+
+test('CyberAvatar Override acquires an off-axis Probe in the aimed direction', () => {
+  const grid = new Grid(8, 6);
+  const bus = new EventBus();
+  const world = new World(grid, { events: bus });
+  const avatar = new CyberAvatar({
+    id: 'cyber-avatar-0',
+    x: 1,
+    y: 2,
+    ram: 8,
+    intrusionStrength: 2,
+    iceResistance: 1,
+  });
+  const probe = new ProbeIce({ id: 'probe-ice-0', x: 4, y: 3 });
+  world.addEntity(avatar);
+  world.addEntity(probe);
+  probe.bindToBus(bus);
+  const log: string[] = [];
+  const ctx = {
+    world,
+    player: avatar,
+    queue: new TurnQueue([FACTION.PLAYER, FACTION.CORP]),
+    rng: { next: () => 0 },
+    log: (line: string) => log.push(line),
+    advanceTurn: () => {},
+    resetInputModes: () => {},
+    onPlayerAction: () => {},
+  };
+
+  applyIntent({ type: 'special', dx: 1, dy: 0 }, ctx);
+
+  assert.equal(probe.faction, FACTION.PLAYER);
+  assert.equal(avatar.ap, avatar.maxAp - AP_COST.OVERRIDE);
+  assert.ok(log.some(line => line.includes('OVERRIDES Probe')));
+});
+
 test('end-turn drains AP to 0, logs wait, and invokes advanceTurn once', () => {
   const { ctx, player, calls, log } = buildCtx();
   applyIntent({ type: 'end-turn' }, ctx);

From 75042366c34923ddafe109173a16bbf05edb2907 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Sun, 14 Jun 2026 12:13:23 -0700
Subject: [PATCH 30/55] docs cleanup

---
 docs/kaizen.md                  |   2 +-
 docs/phase-3-cyberspace-plan.md | 634 --------------------------------
 docs/phase-3-plan.md            | 102 +++--
 3 files changed, 67 insertions(+), 671 deletions(-)
 delete mode 100644 docs/phase-3-cyberspace-plan.md

diff --git a/docs/kaizen.md b/docs/kaizen.md
index 091ca0f..9ac466a 100644
--- a/docs/kaizen.md
+++ b/docs/kaizen.md
@@ -21,7 +21,7 @@ When an item lands, gets reclassified, or develops new context, edit it in place
 
 ## ▶ Phase 3 candidates
 
-- **Cyberspace / Matrix layer.** **P3.M3 first playable slice shipped (2026-06-11):** `JackInPoint` (Ω) in Meatspace opens the layer; `CyberspaceLayer` owns its own `World`, `CyberAvatar`, data nodes, and Probe ICE; data-node-slice objective with `NODES` HUD chip; Probe ICE with trace-flare and pack convergence; render/input swap to the grid view (distinct cyan/magenta tileset, `// THE GRID //` location, RAM HUD); voluntary jack-out with LINK BURNED latch and early-exit confirmation modal. Score is always a cyber run (scope decision #5). **Still open:** Spark ICE (fast attacker), Guardian ICE (heavy node guard), CCTV PIP window showing inactive layer, dual-deploy simstim flip (P3.M4). See [phase-3-plan.md](phase-3-plan.md) P3.M3–P3.M4 and [phase-3-cyberspace-plan.md](phase-3-cyberspace-plan.md) for full slice notes and recorded scope decisions.
+- **Cyberspace / Matrix layer.** **P3.M3 first playable slice shipped (2026-06-11):** `JackInPoint` (Ω) in Meatspace opens the layer; `CyberspaceLayer` owns its own `World`, `CyberAvatar`, data nodes, and Probe ICE; data-node-slice objective with `NODES` HUD chip; Probe ICE with trace-flare and pack convergence; render/input swap to the grid view (distinct cyan/magenta tileset, `// THE GRID //` location, RAM HUD); voluntary jack-out with LINK BURNED latch and early-exit confirmation modal. Score is always a cyber run (scope decision #5). **Still open:** Spark ICE (fast attacker), Guardian ICE (heavy node guard), CCTV PIP window showing inactive layer, dual-deploy simstim flip (P3.M4). See [phase-3-plan.md](phase-3-plan.md) P3.M3–P3.M4 for full slice notes and recorded scope decisions.
 - ~~**Decker archetype.**~~ **✓ Closed — P3.M2.** Shipped 2026-06-11: recruited as a narrative beat at Act 1 → Act 2 (same `score-reveal` Hub beat as the Score target), drone override hack, `Decker.ts` archetype with Cyberspace stats (`ram`, `intrusionStrength`, `iceResistance`), normal roster ownership. Cannot be randomly recruited before Act 2; Cyberspace-required deploys fail loudly without a living Decker. Cyberspace avatar (`CyberAvatar`) and its stats are P3.M3.
 - **Full Rep NPC ally behaviour.** Phase 2 (M5) lays the groundwork: Rep meter, NPC taxonomy, behavior tiers. Phase 3 adds the payoff: high-rep neutrals become Human Shields or information sources, as described in the blueprint.
 - **Inter-hostile friction — multiple crews fighting each other on one map.** Surfaced during Phase 2.9 planning (June 2026). Phase 2.9 ships `RIVAL` as a faction *value* but deliberately keeps **one hostile faction per run** (faction derived from the contract's principal: corp/civic → `CORP`, rival groups → `RIVAL`). That's the slim, cosmetic-foundational slice — it does *not* put `CORP` and `RIVAL` on the same map. The deferred expansion is **mixed encounters with relationship structure** — a rival crew/gang on a site you're also hitting, where the play value comes from *friction*, not a recolor. The design spectrum we mapped:
diff --git a/docs/phase-3-cyberspace-plan.md b/docs/phase-3-cyberspace-plan.md
deleted file mode 100644
index 750b134..0000000
--- a/docs/phase-3-cyberspace-plan.md
+++ /dev/null
@@ -1,634 +0,0 @@
-# P3.M3 — Cyberspace Grid + ICE: Working Plan & Progress
-
-Working document for the P3.M3 implementation effort on branch `3.0-cyberspace`.
-Companion to [phase-3-plan.md](phase-3-plan.md) (the milestone spec); this file
-tracks the approved slice plan, recorded scope decisions, and live progress so
-the effort can be resumed cold.
-
-## Scope decisions (recorded 2026-06-09, Rylee)
-
-1. **First playable slice only** — slices M3.1–M3.6 (contract flag → jack-in
-   terminal → cyber layer model → data node objective → Probe ICE → render
-   swap). **Spark/Guardian ICE deferred** to follow-up slices; the milestone
-   stays open in phase-3-plan.md until they land.
-2. **Minimal voluntary jack-out pulled forward** from P3.M4.6 so the layer is
-   playable end-to-end solo before the simstim flip exists. M4.6 then only adds
-   forced jack-out + dual-deploy cleanup.
-3. **Avatar death = flatline** — ICE destroying the avatar kills the Decker
-   through the existing DEATH/flatline paths. Genre-honest (black ICE kills),
-   zero new death machinery.
-4. **Named cyber stats ship now with real effects**: RAM = avatar HP pool,
-   intrusion strength = slice progress per interact, ICE resistance =
-   `damageReduction` (existing min-1 mitigation in `Combat.ts`). Persisted and
-   validated in both crew persistence paths.
-5. **The Score is always a cyber run** (recorded 2026-06-11, Rylee):
-   `buildScoreContract` emits `DATA_NODE_SLICE` with
-   `{requiresCyberspace: true, count: 1}` — for now; revisit if a
-   meat-only Score variant is ever wanted. Deploy goes through the
-   living-Decker gate; objective shape locked in the P3.M1.7 tests.
-
-TDD throughout; malformed persisted state throws (no silent fallbacks).
-Commits land **per green slice** (user-approved).
-
-## Progress
-
-| Slice | Status | Commit |
-|---|---|---|
-| **S1 — P3.M3.1 Contract flag + gates** | ✅ Done | `f436330` |
-| **S2 — P3.M3.2 Jack-in terminal** | ✅ Done | `05013f6` |
-| **S3 — P3.M3.3 Cyber layer model + avatar + persistence** | ✅ Done | `39b357e` |
-| **S4 — P3.M3.4 Data node objective** | ✅ Done | `3923149` |
-| **S5 — Voluntary jack-out (M4.6 pull-forward)** | ✅ Done | `fab3bcb` |
-| **S6 — P3.M3.5 Probe ICE** | ✅ Done | `0a46878` |
-| **S7 — P3.M3.6 Render/input swap + shell ICE phase** | ✅ Done | `dd17cb8` |
-| **— Score → cyber (scope decision #5)** | ✅ Done | `3c693dc` |
-| **S7.5 — Early jack-out confirmation** | ✅ Done | `2d668bd` |
-| **Playtest stabilization** | ✅ Done | — |
-| **S8 — Docs + wrap-up** | ✅ Done | — |
-
-### Playtest stabilization (2026-06-14)
-
-- Probe ICE tuned from 3 HP / 4 AP to 2 HP / 2 AP. The one-damage strike stays; reducing repeated actions addresses the real burst-pressure source while making Probes appropriately disposable before Spark and Guardian land.
-- CyberAvatar now exposes Override against ICE. It uses the existing 2 AP / 60% / 3-turn override contract, runs allied ICE in the cyber aftermath pass, and preserves override state through active-layer snapshots.
-- A flatlined Decker before THE SCORE creates a single free replacement Decker lead in the Terminal. Recruiting them consumes the visit's recruit slot, and THE SCORE remains unavailable without a living Decker.
-- A Decker flatline during THE SCORE ends the campaign with the persisted `decker-flatlined-score` reason and dedicated Game Over copy. This remains the rule until dual-deploy gives the Score another meaningful failure/recovery shape.
-
-### S1 implementation notes (shipped)
-
-- `OBJECTIVES.DATA_NODE_SLICE = 'data-node-slice'` with cross-field validation
-  in `normalizeObjective` (`Curator.ts`): the kind requires
-  `params.requiresCyberspace === true` plus positive-integer `params.count`;
-  the flag is forbidden on every other kind. Validates at generation,
-  `Run.enterBriefing`, and snapshot restore (all call `normalizeObjective`).
-- `contractRequiresCyberspace(contract)` exported from `Curator.ts` — single
-  source of truth for "this contract has a Cyberspace component".
-- New recipe `cyber-data-spike` (params `{requiresCyberspace: true, count: 1}`,
-  no `targetParams` spread — placement is owned by the DATA_NODE_SLICE arm, and
-  no turn-limit/door-routing machinery engages). Gated by the new
-  `ContractRecipe.availableWhen?: (ctx) => boolean` hook: requires
-  `arcStage ∈ {act-2, act-3} && hasLivingDecker === true`.
-- `recipeIsAvailable` filter applies to **all three** generation paths (fresh
-  `generateRecipeContract`, revisit, principal-biased). When no gated recipe
-  qualifies the filtered pool is identical to the historic pool, so seeded
-  generation for pre-P3.M3 contexts is unchanged (full suite stayed green).
-- `ContractRecipeContext`/`ContractCampaign` gained `hasLivingDecker?`;
-  `Campaign.get hasLivingDecker()` = some non-flatlined `archetype === 'Decker'`.
-- Deploy gate in `Campaign.deployCrewMember`: throws
-  `requires a living Decker to jack in` for cyber contracts unless the deployed
-  member is a (non-flatlined) Decker.
-- UX: `CrewList.setCrew(crew, rowGate?)` — `CrewRowGate` returns a disable tag
-  or null; selection/keyboard nav skip gated rows. `RunBriefing` derives the
-  gate from the contract (`NEEDS DECKER` on non-Decker rows), re-applies on
-  contract swap, and `#commit`/jack-in button respect it.
-- `Run.isObjectiveFamilySatisfied` has a `DATA_NODE_SLICE` case returning
-  `false` (honestly unsatisfiable until S4 wires sliced-node counting). The
-  exhaustive `never` default caught the new kind at typecheck.
-- Tests: `tests/unit/game/hub/cyberContract.test.ts` (14 tests — validation
-  throws, generation gating over 40 seeded boards, determinism, deploy gates).
-
-### S2 implementation notes (shipped)
-
-- `src/game/entities/JackInPoint.ts` — `JackInPoint extends Interactable`,
-  glyph `Ω` (`JACK_IN_GLYPH` in constants), default label `Jack-in port`,
-  id `jack-in-0` (deliberately **not** matching `/^terminal-\d+$/`, which
-  TERMINAL_SLICE counts — regression-tested). `interact`: linked → logged
-  `already-linked` refusal (never throws); capability sniff
-  `actor.canJackIn !== true` → `no-cyberdeck` refusal; success spends interact
-  AP, latches `linked`, emits `EVENT.JACK_IN` `{point, actor}` exactly once.
-- `Decker.canJackIn = true` (readonly capability, P3.M2 sniffing pattern).
-- `events.ts`: `JACK_IN: 'cyber:jack-in'`, `JACK_OUT: 'cyber:jack-out'`
-  registered (known-types-only bus).
-- Placement: `Run.#placeObjectiveInteractables` gained the DATA_NODE_SLICE arm —
-  one port via `findInteractableAnchor`, deterministic per contract seed.
-- `Run.cyberspace: CyberspaceState | null` latched in `enterBriefing` from
-  `contractRequiresCyberspace` (`{phase:'dormant'}` or `null`). S2's
-  `CyberspaceState` is dormant-only; S3 extends the union.
-- Persistence: `RunSnapshot.cyberspace?: RunCyberspaceSnapshot`;
-  `snapshotCyberspace` in Run.ts; `restoreCyberspace` in persistence.ts
-  enforcing **block ⇔ cyber-contract both directions**, unknown phase throws,
-  dormant payload smuggling throws. Entity plumbing: `'jack-in-point'` in
-  `EntityArchetypeId`, `archetypeOf`, `SNAPSHOT_EXTRACTORS`,
-  `ARCHETYPE_FACTORY`, `ENTITY_RESTORE` (+ `readJackInPoint` throwing on
-  missing label/linked).
-- Tests: `tests/unit/game/jackInPoint.test.ts` (12 tests — interact behavior,
-  placement determinism, round-trip, adversarial restore throws).
-
-### S3 implementation notes (shipped)
-
-- `src/game/cyber/cyberMapBuild.ts` — `buildCyberMap({rng, difficulty})`:
-  spanning random walk over a 4×2 cell lattice (29×15 grid), square rooms
-  (3–6) centered per cell, L-corridors along walk edges, clockwise perimeter
-  patrol rings. Node count by difficulty: standard 5 / elevated 6 / critical 8
-  (unknown difficulty throws). `entryTile` = entry room center;
-  **deviation: returns `portTile`** (Chebyshev-1 from entry) so layer build
-  doesn't re-derive placement. Connectivity flood
-  (`explorationReachableKeys`) validates every node + port reachable; throws
-  otherwise. Returned `nodeTiles`/`patrolRings` exclude the entry node.
-- `src/game/cyber/CyberAvatar.ts` — `Entity` subclass: `maxHp = ram`,
-  `damageReduction = iceResistance` (0 is legal), `intrusionStrength`,
-  `callsign`, maxAp 4, `baseHitChance` 0.8 (sniffed by `Combat.resolveRanged`
-  — zero combat changes needed). **Deviation: capability flag is
-  `readonly isCyberAvatar = true`**, not the planned `intrusionStrength`
-  sniff — the Decker now carries `intrusionStrength` too, so the stat sniff
-  would have let the meat body use cyber interactables.
-- `src/game/cyber/EntryPort.ts` — avatar-only interact (`'not-an-avatar'`
-  refusal), spends interact AP, emits `EVENT.JACK_OUT` once. Deliberately
-  does **not** latch — the resolve latch lives on `Run.cyberspace`.
-- `src/game/cyber/CyberspaceLayer.ts` — own bus + `World`;
-  `static build({contractSeed, difficulty, decker})` forks
-  `new Rng(contractSeed).fork('cyberspace')` (layout independent of jack-in
-  turn — regression-tested); plain ctor used by restore (restored layers have
-  empty `nodeTiles`/`patrolRings` — those are build-time spawn anchors only);
-  `onTurnEnded(next)` refreshes incoming-faction AP + ticks cyber alarm on
-  PLAYER; `recordSeen` bounds-validates (throws); `teardown()` unbinds patrol
-  hostiles (S6 seam). **Deviation: no `layer.snapshot()`** — serialization
-  lives in Run's `snapshotCyberspace` beside the entity extractor registry.
-- `Run.ts` — `CyberspaceState` active/resolved arms;
-  `cyberActive`/`activeWorld`/`activeActor` accessors (shell seam for S7);
-  `jackIn(point)` throws unless COMBAT + cyber contract + dormant + linked
-  `JackInPoint` + Decker player; `jackOut()` latches
-  `objectiveComplete: false` (**TODO(P3.M3.4)**: real value once nodes
-  exist); both autosave explicitly. `#onTurnEnded` now consumes the `{next}`
-  payload (throws if absent) and forwards to the layer before autosave. Cyber
-  `ENTITY_DAMAGED` listener mirrors the meat player-death handler — avatar
-  killed → telemetry cause → `enterResult(DEATH)` → existing flatline path
-  (scope decision #3).
-- `persistence.ts` — `restoreCyberspace` per-phase **allowed-keys checks**
-  (cross-phase payload smuggling throws); active block validates grid dims +
-  FLOOR/WALL-only tile values, entryTile in-bounds/passable, alarm,
-  mapMemory; entities restored via `restoreEntity(rec, grid)` against the
-  **cyber** grid; exactly one avatar and one port (duplicates throw).
-  **Deviation: a dead avatar is legal when `record.state !== COMBAT`** — a
-  RESULT-state death snapshot legitimately carries one; alive required only
-  for COMBAT records. **Deviation: no `seed` field in the active block** —
-  the serialized grid is authoritative. Decker cyber stats round-trip through
-  both crew paths (`CampaignCrewSnapshot.cyber?` + run-entity `decker`
-  extra): all-absent → `DECKER_BASE_*` defaults (legacy saves),
-  half-populated/malformed → throw, `cyber` on a non-decker throws.
-- `Decker.ts`/`constants.ts` — `ram` 8 / `intrusionStrength` 2 /
-  `iceResistance` 1 base constants, validated mutable fields (scope
-  decision #4).
-- Tests: 49 across `tests/unit/game/cyber/` — `cyberMapBuild.test.ts` (8),
-  `CyberspaceLayer.test.ts` (11), `runJackIn.test.ts` (10),
-  `cyberPersistence.test.ts` (20, the adversarial heart). Failing-first
-  verified; full suite 1604 green.
-- Playtest note (pre-S7): jack-in flips state internally but the shell still
-  renders Meatspace until the S7 render/input swap — expected, not a bug.
-
-### S4 implementation notes (shipped)
-
-- `src/game/cyber/DataNode.ts` — `DataNode extends Interactable`, glyph `◈`
-  (`DATA_NODE_GLYPH`). Interact: sliced → `already-sliced` refusal; standard
-  adjacency/AP gates; **avatar-only via the `isCyberAvatar` sniff** (same S3
-  deviation rationale — the Decker body carries `intrusionStrength` too);
-  success spends interact AP and adds the avatar's `intrusionStrength` to
-  `sliceProgress`. Sliced at `sliceDifficulty` — `sliceDifficultyFor`:
-  standard 2 / elevated 3 / critical 4 (unknown throws). Progress is **raw,
-  never clamped**, so persistence loses nothing. Slicing is silent — the
-  cyber alarm belongs to ICE detection (S6), not the slice.
-- `CyberspaceLayer.build` gains **required `nodeCount`** (no default — a
-  count silently diverging from the contract would corrupt the objective;
-  `Run.jackIn` passes the objective's `count`). Nodes spawn on the
-  *farthest* node anchors from entry (Chebyshev sort, stable over generator
-  order → placement is a pure function of the contract seed);
-  `nodeCount > nodeTiles.length` throws.
-- `Run` — `ObjectiveState.cyber?: {sliced, required}` computed per phase by
-  `#cyberNodeProgress()`: live `dataNodeProgress(layer.world)` while active,
-  the resolved latch (`required`/0), zero while dormant, `undefined` on
-  non-cyber contracts. `DATA_NODE_SLICE` satisfaction: `sliced >= required`
-  (absent tally → honestly unsatisfiable). `jackOut()` latches
-  `objectiveComplete` from the real tally — the S3 TODO is gone; early
-  jack-out latches `false`, leaving extraction gated through the existing
-  abort-confirm flow (zero new extraction code).
-- `objectiveProgress.ts` — `CyberNodeProgress` type, `dataNodeProgress(world)`
-  tally, optional 4th `cyber` param, `NODES` chip case. The HUD chip pipeline
-  is kind-generic — **no shell copy changes were needed** (the planned
-  describe/combatHud grep came up empty).
-- Persistence — `data-node` codec in both registries (`label` /
-  `sliceDifficulty` / `sliceProgress`, malformed or half-populated throws);
-  `restoreCyberspaceLayer` now requires the active block to carry **exactly
-  the contract's node count** (nodes never despawn, so any drift is
-  corruption).
-- Tests: 25 across `dataNode.test.ts` (10 — entity behavior, difficulty
-  table, refusal matrix) and `dataNodeObjective.test.ts` (15 — spawn
-  determinism, satisfaction per phase, both latch directions, mid-slice
-  round-trip, adversarial node-count/extra throws). Failing-first verified;
-  suite 1629 green.
-
-### S5 implementation notes (shipped)
-
-- Most of the planned S5 core had already landed: the resolve latch,
-  teardown, autosave (S3) and the real `objectiveComplete` tally (S4). The
-  coverage audit confirmed resolved-latching-both-ways, post-jack-out
-  round-trip, and resolved-block payload smuggling were locked by S3/S4
-  tests; the genuinely missing rows were the dormant/non-cyber jackOut
-  throws (now in `jackOut.test.ts`).
-- **LINK BURNED is a real latch, not copy**: `JackInPoint.burned`, set by
-  `Run.jackOut()` via `burn()` on the meat-side port. A burned port refuses
-  *before* the linked check with its own reason (`link-burned`, "LINK BURNED
-  — the connection is dead"), distinct from the redundant-input
-  `already-linked`. `burn()` on an unlinked port throws — and so does
-  constructing one (burned ⇒ linked is an invariant).
-- Persistence: snapshot `extra` carries `burned`; absent on pre-S5 records →
-  unburned (legacy normalization, decker-stats pattern); non-boolean or
-  burned-without-linked throws.
-- Tests: 8 in `jackOut.test.ts` (illegal phases, burn-on-jack-out + refusal
-  flavor + no-AP, burn invariants, round-trip, legacy absence, adversarial
-  malformed/inconsistent flags). The S3 runJackIn LINK BURNED test was
-  updated from the placeholder `already-linked` expectation to the real
-  `link-burned`. Suite 1637 green.
-
-### S6 implementation notes (shipped)
-
-- `src/game/cyber/ProbeIce.ts` — `ProbeIce extends PatrolHostile`, glyph `¶`
-  (`PROBE_ICE_GLYPH`), displayName `Probe`. Explicit stats
-  (`PROBE_ICE_HP 3` / `PROBE_ICE_DAMAGE 1` via the `meleeDamage` sniff /
-  `PROBE_ICE_SIGHT_RANGE 6`); `resolveEnemyStats` tiers deliberately unused —
-  ICE scaling is its own axis for the Spark/Guardian follow-ups.
-- **Trace flare**: `engageSteps` raises the *cyber* world's alarm
-  (`repPenalty: false`) before striking; `raiseAlarm` self-gates while
-  ALERT so the `trace-alarm` step (new `ProbeIceTurnStep` in `types.ts`,
-  with corp-turn status copy) fires once per alarm window. Probes keep the
-  `PatrolHostile` default `listensForAlarm() === true` — one probe's flare
-  is every probe's heading (verified: a distant patroller flips to ENGAGE
-  with the avatar's coordinates).
-- Spawning: one probe per `buildCyberMap` patrol ring, at a seed-picked ring
-  tile (rng consumed *after* map generation, so layouts are untouched and
-  placement stays a pure function of the contract seed). Build binds probes
-  to the layer bus; restore re-binds via the existing
-  `restoreCyberspaceLayer` PatrolHostile path.
-- Persistence rode the generic machinery: adding `'probe-ice'` to
-  `PATROL_ARCHETYPE_IDS` bought waypoints/state/index round-trip wholesale;
-  only `ARCHETYPE_FACTORY` + extractor entries were new.
-- Death paths proven through the **real combat pipeline** (resolveMelee on
-  the cyber world's bus, no synthetic emits): probe kills avatar →
-  RESULT/DEATH with attacker in the cause; avatar kills probe → telemetry
-  kill count. Min-1 mitigation locked (dmg 1 vs iceResistance 1 → 1).
-- Decoupling verified: cyber alarm raises emit nothing on the meat bus and
-  leave the meat latch untouched; the cyber alarm cadence ticks once per
-  meat round advance (proves the single-TurnQueue wiring).
-- **Noted for later**: probes default `FACTION.CORP`. The `cyber-data-spike`
-  recipe locks principals to corp, so this matches `run.hostileFaction`
-  today — but a future rival-principal cyber recipe would leave ICE AP
-  unrefreshed (the queue ticks PLAYER/RIVAL only). Revisit when a second
-  cyber recipe lands (stamp `hostileFaction` onto ICE at `jackIn`, or
-  validate at build).
-- Tests: 9 in `ProbeIce.test.ts`. Failing-first verified; suite 1646 green.
-
-### S7 implementation notes (shipped)
-
-- `palette.ts` — `TilesetId = 'meat' | 'cyber'` axis; `CYBER_TILE_GLYPH`
-  (FLOOR `·` deep cyan `#0e6b66`, WALL `▒` magenta `#c23bd4`).
-  `glyphForTile(tile, principalId?, tileset?)` throws on an unknown tileset
-  *and* on a non-FLOOR/WALL tile reaching the cyber painter (cyber maps are
-  FLOOR/WALL-only by construction — corruption, not a style gap). Principal
-  terrain palettes are a Meatspace mood axis and never recolor the grid.
-- `frame.ts` — `BuildFrameOptions.tileset` (default `'meat'`) threaded
-  through `buildFrame`/`glyphForCell`; `combatHud.ts` — vitals pane label
-  axis (`HP` default, `RAM` on the grid).
-- `applyIntent.ts` — `ApplyIntentContext.player` widened to
-  `Archetype | CyberAvatar`; the avatar exposes no perk/inventory
-  capabilities, so every capability-sniffed branch (`doSpecial`, corpse
-  loot, consumable pickup) degrades to its existing refusal path.
-- `index.ts` — active-view seam (`run.activeWorld`/`run.activeActor`)
-  through vision, paint, look/describe, touch, and statusLine (location
-  reads `// THE GRID //`); module-level `cyberVision = new VisionField()`;
-  shell `JACK_IN`/`JACK_OUT` handlers depend on Run subscribing first
-  (recorded in kaizen — listener-order coupling); `attachCyberListeners`
-  called at every scene (re)wiring site plus the `JACK_IN` hook so a
-  mid-cyber resume re-attaches automatically.
-- **Dual-phase corp turn**: while jacked in, the corp slice chains two
-  `corpTurnDriver` passes — meat hostiles on the meat world (silent: the
-  canvas shows the grid), then ICE on `layer.world` — consuming the shared
-  `run.rng` in that fixed order. Body flatlined during the meat pass →
-  driver bails terminally and the ICE pass never runs.
-- Tests: `dualPhaseTurn.test.ts` (shared-rng order/determinism lock),
-  `cyberTileset.test.ts` (glyph table + throw matrix). kaizen.md gained the
-  index.ts complexity findings (ShellScene casts, statusLine extraction,
-  listener rewire dedupe, listener-order coupling, seam enforcement).
-
-### S7.5 implementation notes (shipped)
-
-- Gap found in Rylee's S7 smoke: jacking out early resolved instantly —
-  an **irreversible** step (LINK BURNED + objective latched unsatisfiable)
-  with zero warning, unlike the exit-abort flow.
-- `Run.onJackOutRequested` (ctor-validated, mirror of `onAbortRequested`):
-  `jackOut()` with the objective **incomplete** defers to the callback —
-  layer stays live, link unburned, nothing persisted; no callback
-  registered → resolve immediately (tests/harness posture). A complete
-  jack-out never asks. The port's interact AP is spent either way; a
-  re-request after cancel costs it again.
-- `run.confirmJackOut()` finalizes (teardown → resolved latch → burn →
-  autosave, shared `#finalizeJackOut`). **Throws** on illegal states —
-  unlike `confirmAbort`'s no-op there is no legal request-voiding race
-  (the modal blocks turn flow), so a stale confirm is a wiring bug.
-- Shell: modal context `jack-out-early` with link-burn copy;
-  `completeJackOutShellSwap()` shared by the immediate path (bus handler,
-  which now skips while the layer is still live) and the confirmed path.
-  `wireRunConfirmations(run)` extracted and called at deploy **and**
-  campaign resume — fixes a latent bug where a restored run lost
-  `onAbortRequested` entirely, silently skipping the abort confirm after
-  any mid-run reload.
-- `EntryPort` success copy neutralized (`routing out…`) — the port no
-  longer knows whether the link actually dropped.
-- Tests: +6 in `jackOut.test.ts` (defer/confirm matrix, complete-objective
-  immediacy, illegal-state throws, pending-confirmation persistence as a
-  live layer). Suite 1663 green.
-
-### S8 wrap-up
-
-- P3.M3 milestone status in `phase-3-plan.md` updated: first playable
-  slice shipped end-to-end; milestone stays open for Spark/Guardian ICE
-  (scope decision #1) and the deferred follow-ups noted in S6
-  (ICE faction stamping) and kaizen (index.ts cleanup).
-- Browser smoke of the S7.5 confirm flow: verified.
-
-## Architecture decisions (approved plan)
-
-### Cyber layer model — `CyberspaceLayer` owned by `Run`, single `TurnQueue`, both worlds tick
-
-New `src/game/cyber/CyberspaceLayer.ts`: owns its own `EventBus`, `World`
-(own `Grid`), `CyberAvatar`, `entryTile`, `mapSeen`. NOT a nested Run.
-
-```ts
-type CyberspaceState =
-  | { phase: 'dormant' }                                // shipped (S2)
-  | { phase: 'active'; layer: CyberspaceLayer }         // shipped (S3)
-  | { phase: 'resolved'; objectiveComplete: boolean };  // shipped (S3); S5 finalizes
-Run.cyberspace: CyberspaceState | null;                 // null ⇔ no cyber component
-```
-
-Turn integration: keep the one existing `TurnQueue`. `TurnQueue.endTurn(world)`
-(verified: emits `TURN_ENDED {previous, next, turn}`, refreshes incoming-faction
-AP in the world it is handed, ticks that world's alarm on round advance) runs on
-the meat world as today. `Run`'s existing `TURN_ENDED` listener
-(`_reattachCombatListeners`, Run.ts ~887) consumes the payload and, when cyber
-is active, calls `layer.onTurnEnded(next)`: refresh incoming-faction AP in the
-cyber world + tick the cyber alarm on round advance. The shell's corp phase
-(S7) chains two `corpTurnDriver.runCorpTurn` passes: meat hostiles, then ICE
-(`ctx.run = {state, world: layer.world, rng: run.rng}`). **Meatspace keeps
-ticking during jack-in** — the Decker body stands at the port as `run.player`,
-targetable; body death hits the existing player-death path
-(`#onEntityDamaged`, Run.ts ~938). M4.2 vulnerability falls out for free.
-
-### Avatar + cyber stats
-
-`src/game/cyber/CyberAvatar.ts` — `CyberAvatar extends Entity`: faction PLAYER,
-glyph `@`, maxAp 4, `maxHp = decker.ram`,
-`damageReduction = decker.iceResistance`, carries `intrusionStrength` +
-`callsign`, `baseHitChance` 0.8 (the grid is home turf; `Combat.resolveRanged`
-capability-sniffs `'baseHitChance' in attacker`, so a non-Crew avatar fights
-with zero combat changes).
-
-Stats live on `Decker` as validated fields with constants
-`DECKER_BASE_RAM = 8`, `DECKER_BASE_INTRUSION = 2`,
-`DECKER_BASE_ICE_RESISTANCE = 1` (`src/game/constants.ts`); ctor throws on
-non-positive-integer overrides. Persist in **both** crew paths:
-
-1. `CampaignCrewSnapshot` (persistence.ts ~743) gains optional
-   `cyber?: { ram; intrusion; iceResistance }` written by `snapshotCrewMember`
-   for deckers only; `restoreCrewMember` (~1326) applies for
-   `archetype === 'decker'`. Absent → defaults (legacy normalization);
-   present-but-malformed or half-populated → throw.
-2. Run-entity `decker` extra becomes
-   `DeckerSnapshot = CrewSnapshot & {ram; intrusion; iceResistance}` —
-   extractor in Run.ts `SNAPSHOT_EXTRACTORS.decker` (~1698), matching
-   `ENTITY_RESTORE.decker` apply hook.
-
-Avatar **current** RAM rides the base entity record (`hp`/`maxHp`/
-`damageReduction`) inside the cyber snapshot block; `intrusionStrength` +
-`callsign` ride its `extra`.
-
-Avatar death: cyber-bus `ENTITY_DAMAGED` listener wired at jack-in (and on
-restore via `_reattachCombatListeners` — the single seam both `enterCombat` and
-`persistence.restore` already call) → set `telemetry.cause` →
-`enterResult({outcome: OUTCOME.DEATH})` → `Campaign.onJobEnd` flatlines the
-Decker through existing machinery.
-
-### Generation — dedicated generator, reuse TILE values, contract-seed determinism
-
-`src/game/cyber/cyberMapBuild.ts`: `buildCyberMap({rng, difficulty})` →
-rooms-as-nodes lattice (5–8 square nodes), 1-tile corridors (data lines),
-`TILE.WALL` fill (firewall). **Only FLOOR/WALL tile ids** — Grid
-passability/LOS, A*, VisionField, World all work unchanged. Node count scales
-with difficulty. Returns `{grid, entryTile, nodeTiles, patrolRings}`.
-Connectivity validated from `entryTile` via `mapConnectivity.ts`
-`explorationReachableKeys` (verified signature: `(world, start, options)` —
-needs a throwaway `World` wrap or a grid-level flood; throws on unreachable
-node tiles). ~150 lines; do NOT reuse the BSP/prefab `buildMap`.
-
-Seed: `new Rng(contract.seed).fork('cyberspace')` — layout independent of
-jack-in turn, trivially restorable.
-
-Distinct visuals via a **tileset axis** (S7), not new TILE ids: `palette.ts`
-gains `TilesetId = 'meat' | 'cyber'` + `CYBER_TILE_GLYPH` (FLOOR `·` deep cyan,
-WALL `▒` magenta — tune in browser); `glyphForTile(tile, principalId?,
-tileset?)` throws on unknown tileset. Thread through
-`BuildFrameOptions`/`buildFrame`/`AsciiRenderer.draw`.
-
-### Data node objective semantics (S4)
-
-`src/game/cyber/DataNode.ts` — `DataNode extends Interactable` (Terminal
-pattern): `sliceProgress`, `sliceDifficulty` (2/3/4 by contract difficulty).
-`interact` capability-sniffs `intrusionStrength` (non-avatars refused), spends
-interact AP, adds intrusion to progress; sliced at threshold. Glyph `◈`
-(`◆` is DenyTarget's).
-
-Satisfaction: `ObjectiveState` gains `cyber?: {sliced, required}`;
-`isObjectiveFamilySatisfied` DATA_NODE_SLICE case reads it;
-`#refreshObjectiveTimerState` computes — `active` → count sliced nodes in the
-layer world; `resolved` → `objectiveComplete ? required : 0`; `dormant` → 0.
-**Jack-out before slicing = objective permanently unsatisfiable** → reaching
-the meat exit hits the existing `onAbortRequested` confirm flow (incomplete
-blocks *clean* extraction; zero new extraction code). `objectiveProgress.ts`
-gains a `NODES` progress chip. Grep `describe.ts`/`combatHud.ts` for
-kind-keyed copy in this slice.
-
-### Jack-in / jack-out (S3 core, S5 finalization)
-
-- `Run.jackIn(point)` via meat-bus `EVENT.JACK_IN` subscription (registered in
-  `_reattachCombatListeners`): `state === COMBAT` else throw;
-  `cyberspace.phase === 'dormant'` else **throw** (corrupt latch); build layer,
-  wire cyber listeners, autosave (`onPersist` explicitly — the latch transition
-  must never be lost).
-- Jack-out: `EntryPort extends Interactable` at `entryTile` in the cyber world
-  (glyph `▼`, avatar-only capability sniff); interact emits `EVENT.JACK_OUT` on
-  the cyber bus → `Run.jackOut()`: throw unless active; latch
-  `objectiveComplete`, `layer.teardown()` (unbind ICE bus subs), phase
-  `resolved`, autosave. Re-jack-in after resolve refused (`LINK BURNED`
-  flavor — `JackInPoint.linked` is already latched).
-
-### Probe ICE (S6)
-
-`src/game/cyber/ProbeIce.ts` — `ProbeIce extends PatrolHostile`, faction CORP,
-glyph `¶`, displayName `Probe`, explicit small stats (maxHp 3, dmg 1,
-sightRange 6 — ICE scaling is its own axis, skip `resolveEnemyStats`).
-`engageSteps`: on acquisition raise the cyber alarm
-(`world.raiseAlarm({repPenalty: false, ...})`) then weak attack; Probe
-**listens** for alarms (unlike Lookout) so packs converge. Add `'probe-ice'`
-to `PATROL_ARCHETYPE_IDS` so `PatrolSnapshot` machinery applies. Patrol
-waypoint rings around node tiles from `buildCyberMap`. Run's cyber
-`ENTITY_DAMAGED` listener also unbinds killed patrol hostiles (mirror of the
-meat path). Verify no rep listener attaches to the cyber bus.
-
-### Render/input swap (S7)
-
-`Run` accessors keep the shell mechanical: `get cyberActive`,
-`get activeWorld`, `get activeActor`. Shell (`index.ts`): module-level
-`cyberVision = new VisionField()`; swap `recomputeVision`, `paint`
-(+`tileset`), `applyIntent` ctx (`world: run.activeWorld,
-player: run.activeActor`), look/describe, `buildCombatHudSnapshot` (identity
-`AVATAR`, HP pane labeled RAM), statusLine, location label (`// THE GRID //`),
-chained ICE corp pass. `ApplyIntentContext.player: Archetype` widens to accept
-`CyberAvatar` (it exposes none of the perk capabilities, so `doSpecial`
-sniffing is safe). No keymap/keyHelp changes — jack-in/out are interactions.
-PIP deferred to M4.5. **Grep `run.world` / `run.player` / `scene.world` /
-`scene.player` exhaustively** — look/describe, touch path, corpse-memory
-vision are the known stragglers.
-
-## Persistence (consolidated; S2 shipped the dormant scaffolding)
-
-`RunSnapshot.cyberspace` (S3 extends the S2 shape):
-
-```ts
-cyberspace?: {
-  phase: 'dormant' | 'active' | 'resolved';
-  // 'active' only — all required together:
-  seed?, grid?: {w,h,tiles}, entities?: RunEntitySnapshot[],  // avatar, entry-port, data-nodes, probe-ice
-  entryTile?, alarm?: AlarmState, mapMemory?: {seen: string[]},
-  // 'resolved' only:
-  objectiveComplete?: boolean;
-};
-```
-
-Restore rules (`restoreCyberspace` in persistence.ts — S2 shipped the dormant
-subset; all throws, `restoreOverrideState` style):
-
-- `contractRequiresCyberspace(contract)` ⇔ block present (both directions). ✅ shipped
-- Unknown phase throws. ✅ shipped
-- `dormant` carrying payload throws. ✅ shipped
-- S3: `active` missing any required field throws; exactly one alive
-  `cyber-avatar` (0 or 2+ throws); entities bounds-checked against the
-  **cyber** grid (reuse `restoreEntity(rec, cyberGrid)`); seen keys
-  bounds-checked.
-- S3: `resolved` without boolean `objectiveComplete`, or carrying active-only
-  fields, throws.
-- S3: Decker `cyber` stat blocks (campaign crew + run entity extra): absent →
-  defaults (legacy normalization); present-but-malformed or half-populated →
-  throw.
-- After rebuild: probes `bindToBus(layer.bus)`; cyber listeners re-wired in
-  `_reattachCombatListeners`.
-- Autosave cadence unchanged (meat-bus `TURN_ENDED` still fires every end-turn
-  while jacked in — single queue); `jackIn`/`jackOut` call `onPersist`
-  explicitly.
-
-## S3 detailed worklist (shipped in `39b357e` — see implementation notes above for deviations)
-
-**Create:**
-- `src/game/cyber/cyberMapBuild.ts` — `buildCyberMap({rng, difficulty})` per
-  above; throws on connectivity failure.
-- `src/game/cyber/CyberAvatar.ts` — per above.
-- `src/game/cyber/EntryPort.ts` — `EntryPort extends Interactable` (glyph `▼`,
-  label `Exit port`); interact by avatar emits `EVENT.JACK_OUT` (charge
-  `AP_COST.INTERACT`).
-- `src/game/cyber/CyberspaceLayer.ts` — class +
-  `static build({contractSeed, difficulty, decker})` (forks
-  `new Rng(contractSeed).fork('cyberspace')`, builds map, spawns avatar at
-  `entryTile`, `EntryPort`, data nodes (S4 fills in), ICE (S6));
-  `onTurnEnded(next: FactionId)`; `recordSeen(keys)` (bounds-validated,
-  throws); `snapshot(): CyberspaceLayerSnapshot`; `teardown()`.
-
-**Modify:**
-- `src/game/archetypes/Decker.ts` + `constants.ts` — `ram`/`intrusionStrength`/
-  `iceResistance` fields, `DECKER_BASE_*` constants, ctor validation.
-- `src/game/Run.ts` — extend `CyberspaceState` union + `RunCyberspaceSnapshot`;
-  `get cyberActive / activeWorld / activeActor`; `jackIn(point)` (driven by
-  `EVENT.JACK_IN` subscription added to `_reattachCombatListeners`);
-  `jackOut()` core; `#onTurnEnded` consumes the `{next}` payload (currently
-  ignores it — Run.ts ~927) for the cyber AP/alarm tick; `snapshotCyberspace`
-  extended; `SNAPSHOT_EXTRACTORS` entries `'cyber-avatar'`/`'entry-port'`;
-  `archetypeOf` instanceof arms; `DeckerSnapshot` extra extension.
-- `src/game/persistence.ts` — extend `restoreCyberspace` (active/resolved
-  rules above); `ARCHETYPE_FACTORY`/`ENTITY_RESTORE` for
-  `'cyber-avatar'`/`'entry-port'`; `ENTITY_RESTORE.decker` apply for cyber
-  stats; `CampaignCrewSnapshot.cyber?` in `snapshotCrewMember` (~1309) +
-  `restoreCrewMember` (~1326).
-
-**Tests (failing first):**
-- `tests/unit/game/cyber/cyberMapBuild.test.ts`: equal-seed determinism;
-  different-seed divergence; every node tile reachable from entry; only
-  FLOOR/WALL ids; difficulty scales node count.
-- `tests/unit/game/cyber/CyberspaceLayer.test.ts`: `build` spawns avatar at
-  entry with `maxHp === decker.ram`,
-  `damageReduction === decker.iceResistance`; `onTurnEnded(FACTION.PLAYER)`
-  refreshes avatar AP only.
-- `tests/unit/game/cyber/runJackIn.test.ts`: golden path — seeded cyber run,
-  walk Decker to port, interact → `phase === 'active'`; layer grid equals a
-  fresh build from the same contract seed (jack-in-turn independence);
-  `jackIn` while already active throws; `JACK_IN` on a non-cyber contract
-  throws.
-- `tests/unit/game/cyber/cyberPersistence.test.ts` (the heart): mid-jack-in
-  snapshot → restore → grids/entities/avatar hp/ap/seen equal; full
-  adversarial throw matrix (active missing grid/avatar; avatar OOB; multiple
-  avatars; resolved missing latch; decker cyber stats half-populated in both
-  paths).
-
-## S3 research notes (verified against the tree, 2026-06-09)
-
-- `TurnQueue.endTurn(world)` emits `TURN_ENDED {previous, next, turn}` and
-  refreshes AP only for entities in the world it is handed; alarm ticks on
-  round advance (TurnQueue.ts:34-55). `Run.#onTurnEnded()` currently takes no
-  payload (Run.ts ~927) — S3 threads `{next}` through for the cyber tick.
-- `_reattachCombatListeners` (Run.ts ~887) is the single seam used by both
-  `enterCombat` and `persistence.restore` — register the `EVENT.JACK_IN`
-  subscription and (re)wire cyber-layer listeners there.
-- `#onEntityDamaged` (Run.ts ~938) is the player-death template: avatar-death
-  listener mirrors `target === avatar && killed` → telemetry.cause →
-  `enterResult({outcome: OUTCOME.DEATH})`. It also unbinds killed
-  `PatrolHostile`s — the cyber listener needs the same for probes (S6).
-- `persistence.restore` (persistence.ts ~872) rebuilds grid → entities →
-  Run → world → queue, then calls `_reattachCombatListeners` for COMBAT
-  snapshots. `restoreEntity(rec, grid)` bounds-checks against the grid it is
-  given — reuse with the cyber grid for cyber entities.
-- `CampaignCrewSnapshot` (~743) and `snapshotCrewMember`/`restoreCrewMember`
-  (~1309/~1326) are the campaign crew path; run-entity crew state flows through
-  `crewSnapshotExtra` (Run.ts ~1675) + `ENTITY_RESTORE` crew handling. Decker
-  cyber stats must round-trip through **both**.
-- `Entity` ctor validates `damageReduction` as a non-negative integer
-  (Entity.ts ~110) — avatar can pass `iceResistance` straight through.
-- `explorationReachableKeys(world, start, options)` (mapConnectivity.ts) is the
-  flood-fill for cyber connectivity validation; it needs a `World`, so
-  `buildCyberMap` should wrap its fresh grid in a throwaway `World` (no
-  entities yet → entity blockers moot).
-- `World` ctor: `new World(grid, { events: bus })`; alarm API:
-  `raiseAlarm(ctx)`, `tickAlarm()`, `snapshotAlarm()`, `restoreAlarm(state)`.
-- `Crew.archetype` is the class-name string (`'Decker'`, capital D) for live
-  checks; persistence archetype ids are lowercase (`'decker'`).
-
-## Verification (per slice + end-to-end)
-
-1. Per slice: `npm test` (typecheck + test build + `node --test`), `npm run lint`.
-2. Determinism: equal-seed trace assertions in S3/S6 tests.
-3. Browser smoke after S7 (`npm start`, port 8099): Act-2 save with Decker →
-   cyber contract on board → non-Decker rows disabled → deploy Decker → jack
-   in → cyber tileset + RAM HUD + probe attacks → slice node → jack out → meat
-   renders → clean extract. Plus: Merc bump refusal copy, redundant jack-in
-   message, mid-cyber reload resumes in the grid, avatar death → flatline
-   screen, jack-out-early → abort-confirm extraction. Console clean on iOS
-   Safari sim + Chrome.
-4. Persistence adversarial: hand-mutate a save in devtools (delete
-   `cyberspace.grid`, flip phase) → restore throws to the error boundary, not
-   a silent fallback.
-
-## Risks
-
-- **S7 shell breadth** is the highest-risk surface (~2300-line index.ts reads
-  `run.world`/`run.player` widely). Mitigation: accessors + exhaustive grep +
-  the smoke script above.
-- **`ApplyIntentContext.player` widening** may ripple into
-  `doSpecial`/`doUseItem` narrowing; the avatar exposes no perk capabilities,
-  and `collectTileLoot` guards on `player.inventory`.
-- **Shared-rng turn order**: meat pass then ICE pass consumes `run.rng` in a
-  fixed order; lock with the S7 dual-phase test.
-- **Cyber alarm/rep**: Probe passes `repPenalty: false`; confirm no rep
-  listeners attach to the cyber bus (S6 test).
diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index b31dd0d..1f1fbb9 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -201,68 +201,98 @@ Neural degradation is deferred until Cyberspace is fun enough to deserve a jack-
 
 ### P3.M3 — Cyberspace grid + ICE 🟡
 
-> **Status (2026-06-11):** the first playable slice (M3.1–M3.6, plus voluntary
-> jack-out pulled forward from M4.6 and an early-jack-out confirmation) is
-> shipped end-to-end on `3.0-cyberspace` — see
-> [phase-3-cyberspace-plan.md](phase-3-cyberspace-plan.md) for slice notes and
-> recorded scope decisions. The milestone stays open for **Spark and Guardian
-> ICE**. The Score contract is now always a cyber run (scope decision #5).
+**Status (2026-06-14):** The first playable slice (M3.1–M3.6, plus voluntary jack-out pulled forward from M4.6 and an early-jack-out confirmation) is shipped end-to-end. The milestone stays open for **Spark and Guardian ICE**.
 
 **Depends on:** P3.M2 (Decker as the Cyberspace avatar). Can prototype grid mechanics independently.
 
 **Goal:** The second tactical layer — a **Cyberspace grid** with its own geometry, traversal rules, and hostile AI (**ICE** — Intrusion Countermeasure Electronics). Generated fresh per jack-in (not persistent across runs).
 
+**Scope decisions (recorded):**
+
+1. **First playable slice only** — slices M3.1–M3.6 (contract flag → jack-in terminal → cyber layer model → data node objective → Probe ICE → render swap). **Spark/Guardian ICE deferred** to follow-up slices; the milestone stays open until they land.
+2. **Minimal voluntary jack-out pulled forward** from P3.M4.6 so the layer is playable end-to-end solo before the simstim flip exists. M4.6 then only adds forced jack-out + dual-deploy cleanup.
+3. **Avatar death = flatline** — ICE destroying the avatar kills the Decker through the existing DEATH/flatline paths. Genre-honest (black ICE kills), zero new death machinery.
+4. **Named cyber stats ship now with real effects:** RAM = avatar HP pool, intrusion strength = slice progress per interact, ICE resistance = `damageReduction` (existing min-1 mitigation in `Combat.ts`). Persisted and validated in both crew persistence paths.
+5. **The Score is always a cyber run** (2026-06-11): `buildScoreContract` emits `DATA_NODE_SLICE` with `{requiresCyberspace: true, count: 1}` — for now; revisit if a meat-only Score variant is ever wanted. Deploy goes through the living-Decker gate; objective shape locked in the P3.M1.7 tests.
+
+TDD throughout; malformed persisted state throws (no silent fallbacks).
+
 **Scope:**
 
-- **Cyberspace grid:** Separate `Grid` / `World` instance for the digital layer. **First implementation should reuse the existing square grid engine** with a distinct tileset and generation rules, then reserve a later graph-topology refactor only if the square grid fails the feel test. This keeps pathfinding, rendering, snapshots, and tests inside known machinery.
-- **Cyberspace tileset / aesthetic:** Distinct from Meatspace. Nodes, data lines, firewalls, open channels. ASCII glyphs TBD but visually differentiated (color palette, glyph set, CRT effects).
+- **Cyberspace grid:** Separate `Grid` / `World` instance for the digital layer. **First implementation reuses the existing square grid engine** with a distinct tileset and generation rules; reserve a graph-topology refactor only if the square grid fails the feel test.
+- **Cyberspace tileset / aesthetic:** Distinct from Meatspace — FLOOR `·` deep cyan, WALL `▒` magenta; location label `// THE GRID //`; vitals pane labeled RAM.
 - **ICE hostiles:** Three types per blueprint:
-  - **Probe:** Sentry / patrol. Detects the Decker, raises alert (Cyberspace alarm analog).
-  - **Spark:** Fast, fragile attacker. Swarm behavior.
-  - **Guardian:** Heavy. Guards critical nodes. High HP, high damage, limited mobility.
-- **ICE AI:** A* pathfinding (reuse Meatspace drone infrastructure with Cyberspace-specific cost maps). Alarm/alert model adapted from P2.5.M2.1 for the digital layer.
-- **Cyberspace objectives:** What the Decker *does* once jacked in — slice data nodes, disable firewalls, open digital locks. Reuses `Interactable` patterns from P2.5.M2.2 adapted for Cyberspace.
-- **Generation:** Procedural per jack-in. Seeded from contract + campaign RNG. Not persistent (fresh each time). Complexity scales with contract difficulty / act.
-- **Jack-in trigger:** Decker interacts with a Meatspace terminal (P2.5.M2.2 `Interactable`). This spawns the Cyberspace grid and activates dual-deploy mode (P3.M4).
+  - **Probe:** Sentry / patrol. Detects the Decker, raises alert (Cyberspace alarm analog). ✅ Shipped.
+  - **Spark:** Fast, fragile attacker. Swarm behavior. 🔲 Planned.
+  - **Guardian:** Heavy. Guards critical nodes. High HP, high damage, limited mobility. 🔲 Planned.
+- **ICE AI:** A* pathfinding (reuse Meatspace drone infrastructure). Alarm/alert model adapted from P2.5.M2.1 for the digital layer.
+- **Cyberspace objectives:** Slice data nodes (shipped); disable firewalls, open digital locks — future.
+- **Generation:** Procedural per jack-in. Seeded from contract (`new Rng(contract.seed).fork('cyberspace')`). Not persistent. Complexity scales with contract difficulty.
+- **Jack-in trigger:** Decker interacts with a Meatspace `JackInPoint` (Ω glyph). Spawns the Cyberspace grid; dual-deploy flip deferred to P3.M4.
+
+**Architecture:**
+
+- **`CyberspaceLayer` owned by `Run`, single `TurnQueue`, both worlds tick.** New `src/game/cyber/CyberspaceLayer.ts` owns its own `EventBus`, `World`, `CyberAvatar`, `entryTile`, `mapSeen` — not a nested Run.
+- **`CyberspaceState` union:** `{phase: 'dormant'}` | `{phase: 'active'; layer: CyberspaceLayer}` | `{phase: 'resolved'; objectiveComplete: boolean}`. `Run.cyberspace: CyberspaceState | null` — null ⇔ no cyber component.
+- **Turn integration:** One existing `TurnQueue`. Meat `TURN_ENDED` listener forwards `{next}` to `layer.onTurnEnded(next)` when cyber is active. Shell corp phase chains two `corpTurnDriver` passes — meat hostiles, then ICE — consuming shared `run.rng` in fixed order. **Meatspace keeps ticking during jack-in** — Decker body stands at the port as `run.player`, targetable; body death hits existing player-death path (M4.2 vulnerability falls out for free).
+- **`CyberAvatar`:** `Entity` subclass; `maxHp = decker.ram`, `damageReduction = decker.iceResistance`, `intrusionStrength`, `readonly isCyberAvatar = true` (capability sniff — Decker body also carries `intrusionStrength`). Stats on `Decker` with `DECKER_BASE_RAM/INTRUSION/ICE_RESISTANCE` constants; round-trip through both crew persistence paths.
+- **Generation:** `buildCyberMap({rng, difficulty})` — rooms-as-nodes lattice, FLOOR/WALL only, connectivity validated via `explorationReachableKeys`. Distinct visuals via tileset axis in `palette.ts`, not new TILE ids.
 
 **Entering Cyberspace — first playable slice:**
 
-The first jack-in should prove the door between layers before shipping every ICE behavior:
-
-1. Add a `requiresCyberspace` / `cyberspaceObjective` contract param for Act 2+ jobs, generated only when the Decker has been recruited.
-2. Place a Meatspace jack-in terminal using the existing `Terminal` / interactable placement path, distinct in label from ordinary terminal-slice props.
-3. When the Decker interacts with the jack-in terminal, create a `cyberspace` run layer with:
-   - generated grid and seed metadata,
-   - Decker digital avatar,
-   - one data node objective,
-   - at least one Probe ICE.
-4. Latch a run state like `cyberspace.active = true`; repeated jack-in attempts against the same terminal throw or log a deterministic "already linked" message depending on whether state is corrupt or just redundant input.
-5. Saving mid-jack-in restores both Meatspace and Cyberspace. Absent or malformed Cyberspace snapshot data for an active jack-in is tier-1 corrupt state and must throw to the boundary.
+1. `requiresCyberspace` contract param for Act 2+ jobs, generated only when a living Decker exists.
+2. Meatspace `JackInPoint` placed via `findInteractableAnchor`, deterministic per contract seed.
+3. Jack-in creates active cyber layer: generated grid, `CyberAvatar`, data nodes, Probe ICE per patrol ring.
+4. Repeated jack-in against linked port → deterministic `already-linked` refusal; corrupt state throws.
+5. Mid-jack-in save restores both layers; absent/malformed cyber snapshot for active jack-in is tier-1 corrupt state.
 
 **Implementation slices:**
 
 | Slice | Status | Change | Tests |
 |---|---|---|---|
-| **P3.M3.1 Contract flag** | ✅ Done | Add Cyberspace-capable contract metadata and validation | generated only Act 2+, invalid flag/params throw |
-| **P3.M3.2 Jack-in terminal** | ✅ Done | Place a terminal that can start the digital layer | deterministic placement, no collision with objective props |
-| **P3.M3.3 Cyber layer model** | ✅ Done | Add serializable `Run.cyberspace` layer with grid/world/avatar | snapshot round-trip, active-layer invariants |
-| **P3.M3.4 Data node objective** | ✅ Done | Slice one data node and feed objective satisfaction | incomplete blocks clean extraction, complete allows it |
-| **P3.M3.5 Probe ICE** | ✅ Done | Minimal ICE patrol/detect/attack loop | seeded movement, detection/alarm, damage/death |
-| **P3.M3.6 Render swap** | ✅ Done | Render Cyberspace when active; Meatspace remains reachable for P3.M4 | browser smoke and console-clean verification |
-| **M4.6 pull-forward — voluntary jack-out** | ✅ Done | `JackInPoint.burned` latch; `Run.jackOut()`; shell swap; early jack-out confirmation modal (`onJackOutRequested` / `confirmJackOut`) | LINK BURNED latch, defer/confirm matrix, round-trip |
-| **Playtest stabilization** | ✅ Done | Probe 2 HP / 2 AP; Cyber Override against ICE; pre-Score replacement Decker; Score Decker death Game Over | action budget, override/revert + persistence, replacement/Score gates, terminal end reason |
+| **P3.M3.1 Contract flag** | ✅ Done | Cyberspace-capable contract metadata and validation | generated only Act 2+, invalid flag/params throw |
+| **P3.M3.2 Jack-in terminal** | ✅ Done | `JackInPoint` placement and interact flow | deterministic placement, no collision with objective props |
+| **P3.M3.3 Cyber layer model** | ✅ Done | Serializable `Run.cyberspace` layer with grid/world/avatar | snapshot round-trip, active-layer invariants |
+| **P3.M3.4 Data node objective** | ✅ Done | Slice data nodes and feed objective satisfaction | incomplete blocks clean extraction, complete allows it |
+| **P3.M3.5 Probe ICE** | ✅ Done | ICE patrol/detect/attack loop | seeded movement, detection/alarm, damage/death |
+| **P3.M3.6 Render swap** | ✅ Done | Render Cyberspace when active; dual-phase corp turn | browser smoke, dualPhaseTurn determinism |
+| **M4.6 pull-forward — voluntary jack-out** | ✅ Done | `JackInPoint.burned` latch; `Run.jackOut()`; early jack-out confirmation | LINK BURNED latch, defer/confirm matrix, round-trip |
+| **Playtest stabilization** | ✅ Done | Probe 2 HP / 2 AP; Cyber Override against ICE; pre-Score replacement Decker; Score Decker death Game Over | action budget, override/revert + persistence, replacement/Score gates |
 | **Spark ICE** | 🔲 Planned | Fast, fragile attacker; swarm behavior | — |
 | **Guardian ICE** | 🔲 Planned | Heavy guard of critical nodes; high HP/damage | — |
 
+**P3.M3.1 implementation note:** `OBJECTIVES.DATA_NODE_SLICE = 'data-node-slice'` with cross-field validation in `normalizeObjective`: kind requires `params.requiresCyberspace === true` plus positive-integer `params.count`; flag forbidden on every other kind. `contractRequiresCyberspace(contract)` exported from `Curator.ts`. Recipe `cyber-data-spike` gated by `ContractRecipe.availableWhen`: `arcStage ∈ {act-2, act-3} && hasLivingDecker`. Deploy gate in `Campaign.deployCrewMember` throws for cyber contracts unless deployed member is a living Decker. UX: `CrewList.setCrew(crew, rowGate?)` — `NEEDS DECKER` on non-Decker rows.
+
+**P3.M3.2 implementation note:** `JackInPoint extends Interactable`, glyph `Ω`, id `jack-in-0` (not matching `/^terminal-\d+$/`). Interact: linked → `already-linked` refusal; `actor.canJackIn !== true` → `no-cyberdeck`; success latches `linked`, emits `EVENT.JACK_IN`. `Run.cyberspace` latched in `enterBriefing` from `contractRequiresCyberspace`. Persistence: `RunSnapshot.cyberspace?`; dormant-only in S2, extended in S3.
+
+**P3.M3.3 implementation note:** `buildCyberMap` — 4×2 cell lattice, L-corridors, patrol rings; node count by difficulty (standard 5 / elevated 6 / critical 8); returns `portTile` (Chebyshev-1 from entry). `CyberspaceLayer.build` forks `new Rng(contractSeed).fork('cyberspace')`. Serialization lives in Run's `snapshotCyberspace`, not `layer.snapshot()`. `Run.jackIn(point)` / `jackOut()` with explicit autosave. Cyber `ENTITY_DAMAGED` listener mirrors meat player-death → flatline. Decker cyber stats: absent → defaults (legacy), half-populated → throw.
+
+**P3.M3.4 implementation note:** `DataNode extends Interactable`, glyph `◈`, avatar-only via `isCyberAvatar` sniff. `sliceDifficultyFor`: standard 2 / elevated 3 / critical 4. `ObjectiveState.cyber?: {sliced, required}`; `DATA_NODE_SLICE` satisfaction reads live tally while active, resolved latch after jack-out. Early jack-out latches `objectiveComplete: false` → existing abort-confirm extraction flow. Active snapshot requires exactly the contract's node count.
+
+**P3.M3.5 (Probe ICE) implementation note:** `ProbeIce extends PatrolHostile`, glyph `¶`. Trace flare: `engageSteps` raises cyber alarm (`repPenalty: false`) before striking; pack convergence via default `listensForAlarm()`. One probe per patrol ring. `'probe-ice'` in `PATROL_ARCHETYPE_IDS` for snapshot machinery. **Follow-up:** probes default `FACTION.CORP`; future rival-principal cyber recipe needs ICE faction stamping at `jackIn`.
+
+**P3.M3.6 implementation note:** `TilesetId = 'meat' | 'cyber'` in `palette.ts`. Shell active-view seam via `run.activeWorld`/`run.activeActor` through vision, paint, look/describe, touch, statusLine. `ApplyIntentContext.player` widened to `Archetype | CyberAvatar`. Dual-phase corp turn while jacked in. PIP deferred to M4.5.
+
+**M4.6 pull-forward (jack-out) implementation note:** `JackInPoint.burned` set by `Run.jackOut()` — real latch, distinct `link-burned` refusal flavor. `burn()` on unlinked port throws (burned ⇒ linked invariant). Persistence: `extra.burned`; absent on pre-S5 records → unburned.
+
+**Early jack-out confirmation implementation note:** `Run.onJackOutRequested` defers incomplete jack-out to confirmation modal (LINK BURNED is irreversible). `run.confirmJackOut()` finalizes; throws on illegal states. `wireRunConfirmations(run)` extracted — called at deploy **and** campaign resume (fixes latent abort-confirm loss on mid-run reload).
+
+**Persistence (consolidated):** `RunSnapshot.cyberspace` with phase `dormant | active | resolved`. Restore rules in `restoreCyberspace`: `contractRequiresCyberspace` ⇔ block present (both directions); unknown phase throws; dormant carrying payload throws; active validates grid dims, exactly one avatar + one port, entities bounds-checked against cyber grid; resolved requires boolean `objectiveComplete`; decker cyber stat blocks half-populated → throw. Autosave on meat `TURN_ENDED` while jacked in; `jackIn`/`jackOut` call `onPersist` explicitly.
+
+**Risks / follow-ups:**
+
+- S7 shell breadth — `index.ts` reads `run.world`/`run.player` widely; kaizen tracks cleanup (ShellScene casts, statusLine extraction, listener rewire dedupe, listener-order coupling).
+- Spark/Guardian ICE and ICE faction stamping for non-corp principals remain open.
+
 **Acceptance:**
 
 - Cyberspace grid renders distinctly from Meatspace.
-- All three ICE types functional: patrol, attack, guard behaviors.
+- All three ICE types functional: patrol, attack, guard behaviors (Probe ✅; Spark/Guardian 🔲).
 - At least one Cyberspace objective type (data node slice) with `isObjectiveSatisfied` integration.
 - Cyberspace grid generated deterministically from seed; snapshot round-trip for mid-run save/restore.
 - Jack-in from Meatspace terminal spawns Cyberspace grid.
 
-**P3.M3 playtest stabilization note (2026-06-14):** Probe pressure came from action economy, not its nominal one-damage strike: the original 3 HP / 4 AP unit could close and attack repeatedly after one Probe woke the pack. Probe now has 2 HP / 2 AP while retaining the trace-flare identity. `CyberAvatar` exposes the Decker's Override capability against ICE; successful overrides reuse the existing temporary faction flip, act during the cyber player-aftermath pass, revert on the normal countdown, and round-trip through the existing patrol snapshot. Campaign dead ends are explicit: before THE SCORE, loss of the assigned Decker creates one free Terminal replacement lead and hides THE SCORE until a living Decker joins; once THE SCORE begins, Decker death ends the campaign with `decker-flatlined-score` Game Over copy.
+**P3.M3 playtest stabilization note (2026-06-14):** Probe tuned from 3 HP / 4 AP to 2 HP / 2 AP — burst pressure came from action economy, not nominal one-damage strike. `CyberAvatar` exposes Override against ICE (2 AP / 60% / 3-turn contract, cyber aftermath pass, patrol snapshot round-trip). Pre-Score Decker flatline → one free Terminal replacement lead; THE SCORE gated until living Decker. Decker flatline during THE SCORE → `decker-flatlined-score` campaign Game Over.
 
 ---
 

From 9d22e501ff566fb286f8980cea14ea6a28846030 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Sun, 14 Jun 2026 13:06:12 -0700
Subject: [PATCH 31/55] PIP meatspace window

---
 docs/phase-3-plan.md                          |  38 ++-
 index.html                                    |  24 +-
 index.ts                                      |  95 ++++++-
 main.css                                      |  51 +++-
 src/game/Entity.ts                            |   2 +
 src/game/Run.ts                               |  11 +
 src/game/constants.ts                         |   6 +-
 src/game/cyber/CyberspaceLayer.ts             | 114 ++++++--
 src/game/cyber/GuardianIce.ts                 |  85 ++++++
 src/game/cyber/ProbeIce.ts                    |  17 +-
 src/game/cyber/SparkIce.ts                    |  75 ++++++
 src/game/persistence.ts                       |   6 +
 src/render/AsciiRenderer.ts                   |   4 +-
 src/render/pip.ts                             |  91 +++++++
 sw-core.js                                    |   1 +
 sw-dev.js                                     |   2 +-
 sw.js                                         |   2 +-
 tests/unit/game/cyber/CyberspaceLayer.test.ts |  22 +-
 tests/unit/game/cyber/ProbeIce.test.ts        |   7 +-
 tests/unit/game/cyber/dualPhaseTurn.test.ts   |  15 +-
 tests/unit/game/cyber/iceRoster.test.ts       | 253 ++++++++++++++++++
 tests/unit/render/AsciiRenderer.test.ts       |  15 ++
 tests/unit/render/pip.test.ts                 |  82 ++++++
 23 files changed, 943 insertions(+), 75 deletions(-)
 create mode 100644 src/game/cyber/GuardianIce.ts
 create mode 100644 src/game/cyber/SparkIce.ts
 create mode 100644 src/render/pip.ts
 create mode 100644 tests/unit/game/cyber/iceRoster.test.ts
 create mode 100644 tests/unit/render/pip.test.ts

diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 1f1fbb9..4940580 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -43,7 +43,7 @@ A new **player archetype** recruited mid-campaign (late Act 1 / start of Act 2),
 |---|---|
 | P3.M1 — Campaign arc structure | ✅ Done |
 | P3.M2 — The Decker archetype | ✅ Done |
-| P3.M3 — Cyberspace grid + ICE | 🟡 First playable slice shipped (Spark/Guardian ICE open) |
+| P3.M3 — Cyberspace grid + ICE | ✅ Done (full ICE roster: Probe, Spark, Guardian) |
 | P3.M4 — Simstim flip (dual-deploy) | 🔲 Planned |
 | P3.M5 — The Score (climactic mission) | 🔲 Planned |
 | P3.M6 — Chronicle (campaign narrative memory) | 🟡 End-summary foundation shipped |
@@ -199,9 +199,9 @@ Neural degradation is deferred until Cyberspace is fun enough to deserve a jack-
 
 ---
 
-### P3.M3 — Cyberspace grid + ICE 🟡
+### P3.M3 — Cyberspace grid + ICE ✅
 
-**Status (2026-06-14):** The first playable slice (M3.1–M3.6, plus voluntary jack-out pulled forward from M4.6 and an early-jack-out confirmation) is shipped end-to-end. The milestone stays open for **Spark and Guardian ICE**.
+**Status (2026-06-14):** Complete. The first playable slice (M3.1–M3.6, plus voluntary jack-out pulled forward from M4.6 and an early-jack-out confirmation) shipped end-to-end, and the **full ICE roster** — Probe (detector), Spark (fast/fragile swarm), and Guardian (heavy node guard) — now lands at every jack-in.
 
 **Depends on:** P3.M2 (Decker as the Cyberspace avatar). Can prototype grid mechanics independently.
 
@@ -222,9 +222,9 @@ TDD throughout; malformed persisted state throws (no silent fallbacks).
 - **Cyberspace grid:** Separate `Grid` / `World` instance for the digital layer. **First implementation reuses the existing square grid engine** with a distinct tileset and generation rules; reserve a graph-topology refactor only if the square grid fails the feel test.
 - **Cyberspace tileset / aesthetic:** Distinct from Meatspace — FLOOR `·` deep cyan, WALL `▒` magenta; location label `// THE GRID //`; vitals pane labeled RAM.
 - **ICE hostiles:** Three types per blueprint:
-  - **Probe:** Sentry / patrol. Detects the Decker, raises alert (Cyberspace alarm analog). ✅ Shipped.
-  - **Spark:** Fast, fragile attacker. Swarm behavior. 🔲 Planned.
-  - **Guardian:** Heavy. Guards critical nodes. High HP, high damage, limited mobility. 🔲 Planned.
+  - **Probe:** Sentry / patrol. Detects the Decker, raises alert (Cyberspace alarm analog). ✅ Shipped. 2 HP / 2 AP / 1 dmg / **sight 7** (longest — it's the detector).
+  - **Spark:** Fast, fragile attacker. Swarm behavior. ✅ Shipped. 1 HP / **4 AP** / 1 dmg / sight 6 — rides the trace flare, never raises one.
+  - **Guardian:** Heavy. Guards critical nodes. High HP, high damage, limited mobility. ✅ Shipped. 6 HP / 2 AP / **3 dmg** / sight 5 — parks on a data node (no patrol), flares on contact.
 - **ICE AI:** A* pathfinding (reuse Meatspace drone infrastructure). Alarm/alert model adapted from P2.5.M2.1 for the digital layer.
 - **Cyberspace objectives:** Slice data nodes (shipped); disable firewalls, open digital locks — future.
 - **Generation:** Procedural per jack-in. Seeded from contract (`new Rng(contract.seed).fork('cyberspace')`). Not persistent. Complexity scales with contract difficulty.
@@ -256,10 +256,12 @@ TDD throughout; malformed persisted state throws (no silent fallbacks).
 | **P3.M3.4 Data node objective** | ✅ Done | Slice data nodes and feed objective satisfaction | incomplete blocks clean extraction, complete allows it |
 | **P3.M3.5 Probe ICE** | ✅ Done | ICE patrol/detect/attack loop | seeded movement, detection/alarm, damage/death |
 | **P3.M3.6 Render swap** | ✅ Done | Render Cyberspace when active; dual-phase corp turn | browser smoke, dualPhaseTurn determinism |
+| **P3.M3.7 Body CCTV PIP** | ✅ Done | Meatspace overlay while jacked in; body-damage feedback | pip viewport/chrome unit tests, browser smoke |
 | **M4.6 pull-forward — voluntary jack-out** | ✅ Done | `JackInPoint.burned` latch; `Run.jackOut()`; early jack-out confirmation | LINK BURNED latch, defer/confirm matrix, round-trip |
 | **Playtest stabilization** | ✅ Done | Probe 2 HP / 2 AP; Cyber Override against ICE; pre-Score replacement Decker; Score Decker death Game Over | action budget, override/revert + persistence, replacement/Score gates |
-| **Spark ICE** | 🔲 Planned | Fast, fragile attacker; swarm behavior | — |
-| **Guardian ICE** | 🔲 Planned | Heavy guard of critical nodes; high HP/damage | — |
+| **Spark ICE** | ✅ Done | Fast, fragile attacker; swarm behavior (rides the flare) | stats, listens-for-flare swarm, difficulty-scaled count, round-trip |
+| **Guardian ICE** | ✅ Done | Heavy guard of critical nodes; high HP/damage, parks on the node | stats, one-per-data-node placement, heavy strike vs resistance, round-trip |
+| **ProbeIce rebalance** | ✅ Done | Sight 6→7 (the detector); roster split off the data-node rings | sight, non-data-ring patrol count |
 
 **P3.M3.1 implementation note:** `OBJECTIVES.DATA_NODE_SLICE = 'data-node-slice'` with cross-field validation in `normalizeObjective`: kind requires `params.requiresCyberspace === true` plus positive-integer `params.count`; flag forbidden on every other kind. `contractRequiresCyberspace(contract)` exported from `Curator.ts`. Recipe `cyber-data-spike` gated by `ContractRecipe.availableWhen`: `arcStage ∈ {act-2, act-3} && hasLivingDecker`. Deploy gate in `Campaign.deployCrewMember` throws for cyber contracts unless deployed member is a living Decker. UX: `CrewList.setCrew(crew, rowGate?)` — `NEEDS DECKER` on non-Decker rows.
 
@@ -269,9 +271,19 @@ TDD throughout; malformed persisted state throws (no silent fallbacks).
 
 **P3.M3.4 implementation note:** `DataNode extends Interactable`, glyph `◈`, avatar-only via `isCyberAvatar` sniff. `sliceDifficultyFor`: standard 2 / elevated 3 / critical 4. `ObjectiveState.cyber?: {sliced, required}`; `DATA_NODE_SLICE` satisfaction reads live tally while active, resolved latch after jack-out. Early jack-out latches `objectiveComplete: false` → existing abort-confirm extraction flow. Active snapshot requires exactly the contract's node count.
 
-**P3.M3.5 (Probe ICE) implementation note:** `ProbeIce extends PatrolHostile`, glyph `¶`. Trace flare: `engageSteps` raises cyber alarm (`repPenalty: false`) before striking; pack convergence via default `listensForAlarm()`. One probe per patrol ring. `'probe-ice'` in `PATROL_ARCHETYPE_IDS` for snapshot machinery. **Follow-up:** probes default `FACTION.CORP`; future rival-principal cyber recipe needs ICE faction stamping at `jackIn`.
+**P3.M3.5 (Probe ICE) implementation note:** `ProbeIce extends PatrolHostile`, glyph `¶`. Trace flare: `engageSteps` raises cyber alarm (`repPenalty: false`) before striking; pack convergence via default `listensForAlarm()`. `'probe-ice'` in `PATROL_ARCHETYPE_IDS` for snapshot machinery. **Follow-up:** probes default `FACTION.CORP`; future rival-principal cyber recipe needs ICE faction stamping at `jackIn`.
 
-**P3.M3.6 implementation note:** `TilesetId = 'meat' | 'cyber'` in `palette.ts`. Shell active-view seam via `run.activeWorld`/`run.activeActor` through vision, paint, look/describe, touch, statusLine. `ApplyIntentContext.player` widened to `Archetype | CyberAvatar`. Dual-phase corp turn while jacked in. PIP deferred to M4.5.
+**Spark + Guardian ICE implementation note (2026-06-14):** The roster is now three distinct silhouettes that share the patrol state machine but split by role and map geometry, assembled in one pass in `CyberspaceLayer.build`:
+
+- **Guardian** (`GuardianIce`, glyph `Ψ`) spawns on **every data-node ring** (`dataNodeIndices`) — one heavy per critical node. 6 HP / 2 AP / 3 dmg (`HEAVY_MELEE_DAMAGE`) / sight 5, **no patrol waypoints** so it holds station on the prize until the avatar enters its short sight, then flares (like the Probe) and closes. ICE resistance only files its strike to 2.
+- **Probe** (`ProbeIce`, glyph `¶`) patrols **every non-data ring**. Rebalanced to **sight 7** — the longest of the three — because its job is to *see* you first and trip the flare that wakes the pack; it stays the weakest in a fight (2 HP / 2 AP / 1 dmg).
+- **Spark** (`SparkIce`, glyph `×`) is the **difficulty-scaled swarm** (`SPARK_COUNT`: standard 1 / elevated 2 / critical 3), seeded onto random rings. 1 HP / 4 AP / 1 dmg / sight 6 — it **rides** the Probe/Guardian flare via `listensForAlarm()` but never raises one itself, closing three tiles and biting in a single activation.
+
+Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans the ring, throwing rather than stacking ICE) and remains a pure function of the contract seed. All three share the `PatrolSnapshot` `extra` block via `PATROL_ARCHETYPE_IDS` (`spark-ice`, `guardian-ice` added alongside `probe-ice`); both round-trip through the active-cyber restore path with bus re-binding. **Follow-ups:** ICE faction stamping for rival-principal recipes (unchanged from M3.5); a leashing option if Guardians chasing a lost lead across the lattice ever reads wrong; live playtest tuning of `SPARK_COUNT` / Guardian HP.
+
+**P3.M3.6 implementation note:** `TilesetId = 'meat' | 'cyber'` in `palette.ts`. Shell active-view seam via `run.activeWorld`/`run.activeActor` through vision, paint, look/describe, touch, statusLine. `ApplyIntentContext.player` widened to `Archetype | CyberAvatar`. Dual-phase corp turn while jacked in.
+
+**P3.M3.7 implementation note (2026-06-14):** Partial pull-forward of M4.5 PIP. While `cyberspace.active`, a read-only `#pip-canvas` overlay (bottom-right on `.game-stage`) paints meatspace via a second `AsciiRenderer` (`pip.ts` helpers: `pipCameraFor`, `pipChrome`, `shouldShowPip`). Meat `vision` stays live; the silent meat corp pass now refreshes the PIP each step and flashes visible corp lines. Body hits while jacked in emit `BODY HIT` status text, pulse the PIP border, and route muzzle flashes to the PIP renderer (not the cyber canvas). Playtest finding: Score flatline from silent meat damage motivated this slice. M4.5 will generalize to the *inactive* layer after simstim flip.
 
 **M4.6 pull-forward (jack-out) implementation note:** `JackInPoint.burned` set by `Run.jackOut()` — real latch, distinct `link-burned` refusal flavor. `burn()` on unlinked port throws (burned ⇒ linked invariant). Persistence: `extra.burned`; absent on pre-S5 records → unburned.
 
@@ -282,17 +294,17 @@ TDD throughout; malformed persisted state throws (no silent fallbacks).
 **Risks / follow-ups:**
 
 - S7 shell breadth — `index.ts` reads `run.world`/`run.player` widely; kaizen tracks cleanup (ShellScene casts, statusLine extraction, listener rewire dedupe, listener-order coupling).
-- Spark/Guardian ICE and ICE faction stamping for non-corp principals remain open.
+- Spark/Guardian ICE shipped; ICE faction stamping for non-corp principals remains open.
 
 **Acceptance:**
 
 - Cyberspace grid renders distinctly from Meatspace.
-- All three ICE types functional: patrol, attack, guard behaviors (Probe ✅; Spark/Guardian 🔲).
+- All three ICE types functional: patrol, attack, guard behaviors (Probe ✅; Spark ✅; Guardian ✅).
 - At least one Cyberspace objective type (data node slice) with `isObjectiveSatisfied` integration.
 - Cyberspace grid generated deterministically from seed; snapshot round-trip for mid-run save/restore.
 - Jack-in from Meatspace terminal spawns Cyberspace grid.
 
-**P3.M3 playtest stabilization note (2026-06-14):** Probe tuned from 3 HP / 4 AP to 2 HP / 2 AP — burst pressure came from action economy, not nominal one-damage strike. `CyberAvatar` exposes Override against ICE (2 AP / 60% / 3-turn contract, cyber aftermath pass, patrol snapshot round-trip). Pre-Score Decker flatline → one free Terminal replacement lead; THE SCORE gated until living Decker. Decker flatline during THE SCORE → `decker-flatlined-score` campaign Game Over.
+**P3.M3 playtest stabilization note (2026-06-14):** Probe tuned from 3 HP / 4 AP to 2 HP / 2 AP — burst pressure came from action economy, not nominal one-damage strike. `CyberAvatar` exposes Override against ICE (2 AP / 60% / 3-turn contract, cyber aftermath pass, patrol snapshot round-trip). Pre-Score Decker flatline → one free Terminal replacement lead; THE SCORE gated until living Decker. Decker flatline during THE SCORE → `decker-flatlined-score` campaign Game Over. **P3.M3.7** adds meatspace CCTV PIP so jacked-in body vulnerability is visible (silent meat corp damage was the Score death vector in first playtest).
 
 ---
 
diff --git a/index.html b/index.html
index 1d3ab22..83a9de7 100644
--- a/index.html
+++ b/index.html
@@ -46,13 +46,23 @@ <h1>Kernel Panic</h1>
     </header>
     <main class="game-shell u-fill-width u-flex u-flex-column">
       <div class="game-stage">
-        <canvas
-          id="game-canvas"
-          width="640"
-          height="400"
-          tabindex="0"
-          aria-label="Kernel Panic game view"
-        ></canvas>
+        <div class="game-canvas-wrap">
+          <canvas
+            id="game-canvas"
+            width="640"
+            height="400"
+            tabindex="0"
+            aria-label="Kernel Panic game view"
+          ></canvas>
+          <canvas
+            id="pip-canvas"
+            width="160"
+            height="100"
+            hidden
+            aria-hidden="true"
+            aria-label="Meatspace CCTV"
+          ></canvas>
+        </div>
         <aside class="game-log collapsed">
           <h3>Log</h3>
           <pre id="log" aria-live="polite"></pre>
diff --git a/index.ts b/index.ts
index 13fd602..1906928 100644
--- a/index.ts
+++ b/index.ts
@@ -97,6 +97,7 @@ import type { Intent } from '/src/input/applyIntent.js';
 import type { AimKind, Mode } from '/src/input/keymap.js';
 import { formatCombatHudA11ySummary } from '/src/render/combatHud.js';
 import type { CombatHudSummaryInput } from '/src/render/combatHud.js';
+import { pipCameraFor, pipChrome, shouldShowPip } from '/src/render/pip.js';
 import type { KeyItem, Telemetry, TurnActionStep } from '/src/types.js';
 import { installErrorBoundary, type FaultSignal } from '/src/errorBoundary.js';
 import { isDevelopmentMode } from '/src/domUtils.js';
@@ -217,6 +218,7 @@ type PendingJobResult = {
 };
 
 type EntityDamagedPayload = {
+  attacker?: Entity;
   target?: Entity;
   damage?: number;
   killed?: boolean;
@@ -268,8 +270,11 @@ let repUnsubs: (() => void)[] = [];
 let civilianHarmsThisJob = 0;
 
 let canvas: HTMLCanvasElement;
+/** P3.M3.7: meatspace CCTV overlay while jacked in. */
+let pipCanvas: HTMLCanvasElement;
 let statusEl: HTMLElement | null = null;
 let renderer: AsciiRenderer;
+let pipRenderer: AsciiRenderer;
 let crt: CrtFilter;
 let stageEl: HTMLElement;
 let briefingEl: RunBriefingElement;
@@ -470,10 +475,11 @@ function activeTileset(scene: ShellScene | null): TilesetId {
 
 async function boot() {
   canvas = mustGetElement<HTMLCanvasElement>('game-canvas');
-  if (!canvas.parentElement) {
-    throw new Error('[shell] #game-canvas requires a parent stage element');
+  const gameStage = canvas.closest('.game-stage');
+  if (!(gameStage instanceof HTMLElement)) {
+    throw new Error('[shell] #game-canvas must live inside .game-stage');
   }
-  stageEl = canvas.parentElement;
+  stageEl = gameStage;
   statusEl = mustGetElement<HTMLElement>('game-status');
   contractSelectEl = mustGetElement<ContractSelectElement>('contract-select');
   briefingEl = mustGetElement<RunBriefingElement>('briefing');
@@ -495,6 +501,8 @@ async function boot() {
   logContentEl = mustQuery<HTMLPreElement>('pre', logEl);
 
   renderer = new AsciiRenderer(canvas);
+  pipCanvas = mustGetElement<HTMLCanvasElement>('pip-canvas');
+  pipRenderer = new AsciiRenderer(pipCanvas, { cellSize: 10, fontSize: 9 });
   crt = new CrtFilter(canvas);
 
   keyboard = new KeyboardController({
@@ -1847,7 +1855,20 @@ function runCorpTurn(onFinish: () => void): void {
       if (degrading) return;
       const scene = currentScene();
       if (!scene?.world || !scene.player) return;
-      if (isJackedIn(scene)) return;
+      if (isJackedIn(scene)) {
+        paintPip();
+        const resolve = (id: string) => resolveEntityLabel(id, scene.world!.entities);
+        const line = formatCorpTurnStep(resolve(entityId), step, resolve);
+        if (
+          line &&
+          isCorpTurnStepLogVisibleToPlayer(scene.world, scene.player.id, entityId, step, (x, y) =>
+            vision.isVisible(x, y)
+          )
+        ) {
+          flash(line);
+        }
+        return;
+      }
       const resolve = (id: string) => resolveEntityLabel(id, scene.world!.entities);
       const line = formatCorpTurnStep(resolve(entityId), step, resolve);
       if (
@@ -2113,19 +2134,43 @@ function attachAnimationListeners(): void {
   if (!run?.bus) return;
   animationUnsubs.push(
     run.bus.on(EVENT.ENTITY_DAMAGED, payload => {
-      const { target, damage = 0, killed, source } = (payload ?? {}) as EntityDamagedPayload;
+      const {
+        attacker,
+        target,
+        damage = 0,
+        killed,
+        source,
+      } = (payload ?? {}) as EntityDamagedPayload;
+      const jacked = isJackedIn(run);
       // Player-side feedback: screen shake + red vignette when *we* get hit.
       if (run?.player && target === run.player && damage > 0) {
         triggerShake(stageEl);
         triggerDamageFlash(stageEl);
         animLock.push(ANIMATION_DURATIONS.DAMAGE_FLASH);
+        if (jacked) {
+          const attackerLabel = attacker
+            ? resolveEntityLabel(attacker.id, run.world!.entities)
+            : 'unknown';
+          flash(
+            killed
+              ? `BODY FLATLINED — ${attackerLabel} killed your meatspace link.`
+              : `BODY HIT — ${attackerLabel} struck for ${damage} (meatspace).`
+          );
+          triggerPipHitPulse();
+          paintPip();
+        }
       }
       // Melee impact: the strike reads as landing on the *target*, not
       // hovering above the attacker. Ranged stays on the NOISE path so
       // misses still get a muzzle flash on the shooter's tile.
       if (source === 'melee' && target && damage > 0) {
-        const fired = runMuzzleFlash(renderer, paint, target.x, target.y);
-        if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
+        if (jacked && target === run.player) {
+          const fired = runMuzzleFlash(pipRenderer, paintPip, target.x, target.y);
+          if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
+        } else if (!jacked) {
+          const fired = runMuzzleFlash(renderer, paint, target.x, target.y);
+          if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
+        }
       }
       // Memorise corpse position when a kill occurs within current LOS.
       if (killed && target && vision.isVisible(target.x, target.y)) {
@@ -2140,7 +2185,10 @@ function attachAnimationListeners(): void {
       if (noise.kind !== 'ranged') return;
       const origin = noise.origin;
       if (!origin) return;
-      const fired = runMuzzleFlash(renderer, paint, origin.x, origin.y);
+      const jacked = isJackedIn(run);
+      const flashRenderer = jacked ? pipRenderer : renderer;
+      const repaint = jacked ? paintPip : paint;
+      const fired = runMuzzleFlash(flashRenderer, repaint, origin.x, origin.y);
       if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
     }),
     run.bus.on(EVENT.DOOR_UNLOCKED, payload => {
@@ -2219,6 +2267,7 @@ function attachCyberListeners(): void {
 function completeJackOutShellSwap(): void {
   for (const off of cyberUnsubs) off();
   cyberUnsubs = [];
+  pipCanvas.hidden = true;
   flash('LINK DROPPED — back in your body.');
   recomputeVision();
   paint();
@@ -2448,6 +2497,35 @@ function buildHubHudRows(scene: ShellScene | null) {
   return rows;
 }
 
+function paintPip(): void {
+  const run = currentScene();
+  if (!run || !isRun(run) || run.state !== RUN_STATE.COMBAT || !shouldShowPip(run)) {
+    pipCanvas.hidden = true;
+    return;
+  }
+  if (!run.world || !run.player) {
+    pipCanvas.hidden = true;
+    return;
+  }
+  pipCanvas.hidden = false;
+  const principalId = campaign?.activeRun?.contract?.context?.principal?.id;
+  pipRenderer.draw(run.world, run.player, {
+    camera: pipCameraFor(run.player, run.world),
+    vision,
+    player: run.player,
+    tileset: 'meat',
+    principalId,
+    hudRows: pipChrome(run.player),
+  });
+}
+
+function triggerPipHitPulse(): void {
+  pipCanvas.classList.remove('pip-hit');
+  // Force reflow so repeated hits retrigger the animation.
+  void pipCanvas.offsetWidth;
+  pipCanvas.classList.add('pip-hit');
+}
+
 function paint(stateHint: InputState = activeInputState()): void {
   const run = currentScene();
   if (canvas.hidden) {
@@ -2485,6 +2563,7 @@ function paint(stateHint: InputState = activeInputState()): void {
   });
   crt.alertTint = run.state === RUN_STATE.COMBAT && world.alarmActive;
   crt.apply();
+  paintPip();
   setStatus(statusLine(stateHint));
 }
 
diff --git a/main.css b/main.css
index 1786a7e..5306cb2 100644
--- a/main.css
+++ b/main.css
@@ -287,12 +287,61 @@ main {
   max-width: min(960px, max(320px, calc((100dvh - 13.25rem) * 1.6)), 100%);
 }
 
-.game-stage > #game-canvas {
+.game-canvas-wrap {
+  position: relative;
   flex: 1 1 80%;
+  min-width: 0;
   border-radius: 1rem 0.5rem 0.5rem 2rem;
   corner-shape: bevel;
 }
 
+/* P3.M3.7: meatspace CCTV while jacked in — anchored to the main canvas, not the stage. */
+.game-canvas-wrap > #pip-canvas {
+  position: absolute;
+  right: 0.35rem;
+  bottom: 0.35rem;
+  z-index: 2;
+  pointer-events: none;
+  border: 1px solid rgba(0, 217, 165, 0.45);
+  border-radius: 0.35rem 0.75rem 0.35rem 0.35rem;
+  corner-shape: bevel;
+  box-shadow: 0 0 12px rgba(0, 217, 165, 0.15);
+  opacity: 0.92;
+  image-rendering: pixelated;
+}
+
+.game-canvas-wrap > #pip-canvas[hidden] {
+  display: none;
+}
+
+.game-canvas-wrap > #pip-canvas.pip-hit {
+  animation: pip-hit-pulse 0.45s ease-out;
+}
+
+@keyframes pip-hit-pulse {
+  0% {
+    border-color: #ff7a66;
+    box-shadow: 0 0 16px rgba(255, 122, 102, 0.55);
+  }
+  100% {
+    border-color: rgba(0, 217, 165, 0.45);
+    box-shadow: 0 0 12px rgba(0, 217, 165, 0.15);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .game-canvas-wrap > #pip-canvas.pip-hit {
+    animation: none;
+    border-color: #ff7a66;
+  }
+}
+
+@media (max-width: 360px) {
+  .game-canvas-wrap > #pip-canvas {
+    display: none !important;
+  }
+}
+
 .game-stage > .game-log {
   display: flex;
   flex-direction: column;
diff --git a/src/game/Entity.ts b/src/game/Entity.ts
index c914783..edac889 100644
--- a/src/game/Entity.ts
+++ b/src/game/Entity.ts
@@ -279,6 +279,8 @@ function kindFromId(id: string): string {
   if (id.startsWith('entry-port')) return 'Exit Port';
   if (id.startsWith('data-node')) return 'Data Node';
   if (id.startsWith('probe-ice')) return 'Probe';
+  if (id.startsWith('spark-ice')) return 'Spark';
+  if (id.startsWith('guardian-ice')) return 'Guardian';
   if (id.includes('turret')) return 'Turret';
   if (id.startsWith('crew')) return 'Operative';
   return id;
diff --git a/src/game/Run.ts b/src/game/Run.ts
index 1f2ca35..6519a18 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -84,6 +84,8 @@ import { CyberAvatar } from './cyber/CyberAvatar.js';
 import { EntryPort } from './cyber/EntryPort.js';
 import { DataNode } from './cyber/DataNode.js';
 import { ProbeIce } from './cyber/ProbeIce.js';
+import { SparkIce } from './cyber/SparkIce.js';
+import { GuardianIce } from './cyber/GuardianIce.js';
 import { applyMutationDeltas } from './locations.js';
 import { BreachingCharge } from './entities/BreachingCharge.js';
 import { ITEM_ID, getItemById } from './items.js';
@@ -182,6 +184,8 @@ export type EntityArchetypeId =
   | 'entry-port'
   | 'data-node'
   | 'probe-ice'
+  | 'spark-ice'
+  | 'guardian-ice'
   | 'entity';
 
 export type RunTelemetry = {
@@ -228,6 +232,9 @@ export const PATROL_ARCHETYPE_IDS = Object.freeze([
   'medic',
   // P3.M3.5: Probe ICE shares the identical patrol state-machine block.
   'probe-ice',
+  // P3.M3: Spark + Guardian ICE share the same patrol state-machine block.
+  'spark-ice',
+  'guardian-ice',
 ] as const);
 
 export type PatrolArchetypeId = (typeof PATROL_ARCHETYPE_IDS)[number];
@@ -2100,6 +2107,8 @@ const SNAPSHOT_EXTRACTORS: Partial<Record<EntityArchetypeId, (e: Entity) => Enti
       } satisfies DataNodeSnapshot;
     },
     'probe-ice': e => patrolSnapshotExtra(e as PatrolHostile),
+    'spark-ice': e => patrolSnapshotExtra(e as PatrolHostile),
+    'guardian-ice': e => patrolSnapshotExtra(e as PatrolHostile),
   };
 
 /**
@@ -2190,6 +2199,8 @@ function archetypeOf(entity: Entity): EntityArchetypeId {
   if (entity instanceof EntryPort) return 'entry-port';
   if (entity instanceof DataNode) return 'data-node';
   if (entity instanceof ProbeIce) return 'probe-ice';
+  if (entity instanceof SparkIce) return 'spark-ice';
+  if (entity instanceof GuardianIce) return 'guardian-ice';
   if (entity instanceof BreachingCharge) return 'breaching-charge';
   if (entity instanceof Entity) return 'entity';
   throw new Error(`archetypeOf: cannot classify entity ${(entity as Entity | undefined)?.id}`);
diff --git a/src/game/constants.ts b/src/game/constants.ts
index 52dba84..a6730be 100644
--- a/src/game/constants.ts
+++ b/src/game/constants.ts
@@ -50,8 +50,12 @@ export const JACK_IN_GLYPH = 'Ω';
 export const ENTRY_PORT_GLYPH = '▼';
 /** P3.M3.4: the slice target on the cyber grid (`◆` is DenyTarget's). */
 export const DATA_NODE_GLYPH = '◈';
-/** P3.M3.5: Probe ICE — the patrol fodder of the cyber grid. */
+/** P3.M3.5: Probe ICE — the patrol/detector of the cyber grid. */
 export const PROBE_ICE_GLYPH = '¶';
+/** P3.M3: Spark ICE — the fast, fragile swarm attacker. */
+export const SPARK_ICE_GLYPH = '×';
+/** P3.M3: Guardian ICE — the heavy guard parked on critical data nodes. */
+export const GUARDIAN_ICE_GLYPH = 'Ψ';
 
 /** Numeric tile id — one of the `TILE` values. */
 export type TileId = (typeof TILE)[keyof typeof TILE];
diff --git a/src/game/cyber/CyberspaceLayer.ts b/src/game/cyber/CyberspaceLayer.ts
index 760cd60..4734de9 100644
--- a/src/game/cyber/CyberspaceLayer.ts
+++ b/src/game/cyber/CyberspaceLayer.ts
@@ -27,12 +27,30 @@ import { CyberAvatar } from './CyberAvatar.js';
 import { EntryPort } from './EntryPort.js';
 import { DataNode, sliceDifficultyFor } from './DataNode.js';
 import { ProbeIce } from './ProbeIce.js';
+import { SparkIce } from './SparkIce.js';
+import { GuardianIce } from './GuardianIce.js';
 import { PatrolHostile } from '../ai/PatrolHostile.js';
-import { FACTION, type ContractDifficulty, type FactionId } from '../constants.js';
+import {
+  CONTRACT_DIFFICULTY,
+  FACTION,
+  type ContractDifficulty,
+  type FactionId,
+} from '../constants.js';
 import { coordKey } from '../mapConnectivity.js';
 import type { Decker } from '../archetypes/Decker.js';
 import type { GridPoint } from '../../types.js';
 
+/**
+ * P3.M3 Spark swarm size per contract difficulty — the fast/fragile wave that
+ * converges on the trace flare. Scales the cyber-side tempo pressure without
+ * touching the Guardian/Probe placement (those are tied to node geometry).
+ */
+const SPARK_COUNT: Record<string, number> = Object.freeze({
+  [CONTRACT_DIFFICULTY.STANDARD]: 1,
+  [CONTRACT_DIFFICULTY.ELEVATED]: 2,
+  [CONTRACT_DIFFICULTY.CRITICAL]: 3,
+});
+
 export type CyberspaceLayerInit = {
   bus: EventBus;
   world: World;
@@ -143,38 +161,68 @@ export class CyberspaceLayer {
     world.addEntity(avatar);
     world.addEntity(port);
     // P3.M3.4: data nodes claim the *farthest* node anchors from the entry —
-    // the avatar has to cross the lattice (and, from P3.M3.5, the ICE
-    // patrolling it). Chebyshev sort is stable over the deterministic
-    // generator order, so placement is a pure function of the contract seed.
+    // the avatar has to cross the lattice (and the ICE guarding it). Rank node
+    // *indices* by distance so each center stays paired with its patrol ring;
+    // the order is a pure function of the contract seed.
     const sliceDifficulty = sliceDifficultyFor(difficulty);
-    const anchors = [...map.nodeTiles].sort(
-      (a, b) => chebyshevFrom(map.entryTile, b) - chebyshevFrom(map.entryTile, a)
-    );
-    for (let i = 0; i < nodeCount; i++) {
+    const rankedNodes = map.nodeTiles
+      .map((_, i) => i)
+      .sort(
+        (a, b) =>
+          chebyshevFrom(map.entryTile, map.nodeTiles[b]) -
+          chebyshevFrom(map.entryTile, map.nodeTiles[a])
+      );
+    const dataNodeIndices = new Set(rankedNodes.slice(0, nodeCount));
+    rankedNodes.slice(0, nodeCount).forEach((nodeIndex, ordinal) => {
+      const center = map.nodeTiles[nodeIndex];
       world.addEntity(
         new DataNode({
-          id: `data-node-${i}`,
-          x: anchors[i].x,
-          y: anchors[i].y,
+          id: `data-node-${ordinal}`,
+          x: center.x,
+          y: center.y,
           sliceDifficulty,
         })
       );
-    }
-    // P3.M3.5: one Probe per patrol ring, spawned at a seed-picked ring tile
-    // (the rng has fully determined the map by here, so this stays a pure
-    // function of the contract seed). Probes bind to the layer bus at build —
-    // the restore path re-binds via `restoreCyberspaceLayer`.
+    });
+
+    // P3.M3 ICE roster — three roles, one pass over the non-entry rings:
+    //   - **Guardian** on every data-node ring: the heavy parks (no waypoints)
+    //     on the prize it guards.
+    //   - **Probe** on every other ring: the long-sighted detector patrols.
+    //   - **Spark** swarm: a difficulty-scaled wave seeded onto random rings.
+    // Each spawn consumes a fixed rng cadence (one `pickFreeRingTile` call), so
+    // the whole roster stays a pure function of the contract seed. ICE binds to
+    // the layer bus at build; the restore path re-binds via
+    // `restoreCyberspaceLayer`.
+    let probeOrdinal = 0;
+    let guardianOrdinal = 0;
     map.patrolRings.forEach((ring, i) => {
-      const spawn = ring[rng.intRange(0, ring.length)];
-      const probe = new ProbeIce({
-        id: `probe-ice-${i}`,
+      const spawn = pickFreeRingTile(world, ring, rng);
+      const ice = dataNodeIndices.has(i)
+        ? new GuardianIce({ id: `guardian-ice-${guardianOrdinal++}`, x: spawn.x, y: spawn.y })
+        : new ProbeIce({
+            id: `probe-ice-${probeOrdinal++}`,
+            x: spawn.x,
+            y: spawn.y,
+            patrolWaypoints: ring,
+          });
+      world.addEntity(ice);
+      ice.bindToBus(bus);
+    });
+
+    const sparkCount = SPARK_COUNT[difficulty] ?? 0;
+    for (let i = 0; i < sparkCount; i++) {
+      const ring = map.patrolRings[rng.intRange(0, map.patrolRings.length)];
+      const spawn = pickFreeRingTile(world, ring, rng);
+      const spark = new SparkIce({
+        id: `spark-ice-${i}`,
         x: spawn.x,
         y: spawn.y,
         patrolWaypoints: ring,
       });
-      world.addEntity(probe);
-      probe.bindToBus(bus);
-    });
+      world.addEntity(spark);
+      spark.bindToBus(bus);
+    }
     return new CyberspaceLayer({
       bus,
       world,
@@ -241,6 +289,28 @@ function chebyshevFrom(a: GridPoint, b: GridPoint): number {
   return Math.max(Math.abs(a.x - b.x), Math.abs(a.y - b.y));
 }
 
+/**
+ * Pick an unoccupied, passable tile on a patrol ring for an ICE spawn. Consumes
+ * exactly one rng draw (the start offset) then scans the ring deterministically
+ * so multiple ICE on/near the same ring never stack. Throws if a ring somehow
+ * has no free tile — a generator invariant violation, not a silent skip.
+ */
+function pickFreeRingTile(world: World, ring: GridPoint[], rng: Rng): GridPoint {
+  if (ring.length === 0) {
+    throw new RangeError('pickFreeRingTile: empty patrol ring');
+  }
+  const start = rng.intRange(0, ring.length);
+  for (let step = 0; step < ring.length; step++) {
+    const tile = ring[(start + step) % ring.length];
+    if (world.grid.isPassable(tile.x, tile.y) && !world.entityAt(tile.x, tile.y)) {
+      return tile;
+    }
+  }
+  throw new RangeError(
+    `pickFreeRingTile: no free tile on a ring of ${ring.length} (all occupied/blocked)`
+  );
+}
+
 function parseCoordKey(key: string): GridPoint {
   if (typeof key !== 'string') {
     throw new TypeError('CyberspaceLayer: coordinate key must be a string');
diff --git a/src/game/cyber/GuardianIce.ts b/src/game/cyber/GuardianIce.ts
new file mode 100644
index 0000000..6a5f2e8
--- /dev/null
+++ b/src/game/cyber/GuardianIce.ts
@@ -0,0 +1,85 @@
+/**
+ * P3.M3 — Guardian ICE: the heavy that guards a critical data node.
+ *
+ * The counterweight to the Spark. Where the swarm trades durability for tempo,
+ * the Guardian is slow, sighted short, and very hard to move through:
+ *
+ *   - `GUARDIAN_ICE_HP = 6` — three avatar swings at the cyber melee baseline.
+ *   - `GUARDIAN_ICE_DAMAGE = 3` (`HEAVY_MELEE_DAMAGE`) — the avatar's
+ *     `iceResistance` only files this down to 2; the prize bites back.
+ *   - `GUARDIAN_ICE_AP = 2` — limited mobility. It spawns *on* its node and is
+ *     deliberately given no patrol ring, so it holds station until the avatar
+ *     enters its short sight, then closes and strikes.
+ *
+ * Like the Probe, it flares on engagement — a hand on the crown jewel trips the
+ * trace and calls the swarm. ICE stats are an explicit axis (no
+ * `resolveEnemyStats` tiers) — see ProbeIce.
+ */
+import { PatrolHostile, type PatrolHostileInit, type EngageSteps } from '../ai/PatrolHostile.js';
+import { AP_COST, GUARDIAN_ICE_GLYPH, HEAVY_MELEE_DAMAGE } from '../constants.js';
+import { canMelee, resolveMelee } from '../Combat.js';
+import type { Entity } from '../Entity.js';
+import type { World } from '../World.js';
+import type { Rng } from '../../rng.js';
+
+export const GUARDIAN_ICE_HP = 6;
+export const GUARDIAN_ICE_AP = 2;
+export const GUARDIAN_ICE_DAMAGE = HEAVY_MELEE_DAMAGE;
+export const GUARDIAN_ICE_SIGHT_RANGE = 5;
+
+export interface GuardianIceProps extends Omit<PatrolHostileInit, 'glyph'> {}
+
+export class GuardianIce extends PatrolHostile {
+  /** Sniffed by `Combat.attackerMeleeDamage` — the heavy ICE strike. */
+  readonly meleeDamage = GUARDIAN_ICE_DAMAGE;
+
+  constructor({
+    maxHp = GUARDIAN_ICE_HP,
+    maxAp = GUARDIAN_ICE_AP,
+    sightRange = GUARDIAN_ICE_SIGHT_RANGE,
+    patrolWaypoints,
+    ...props
+  }: GuardianIceProps) {
+    super({
+      ...props,
+      maxAp,
+      maxHp,
+      sightRange,
+      glyph: GUARDIAN_ICE_GLYPH,
+      displayName: 'Guardian',
+      patrolWaypoints,
+    });
+  }
+
+  /**
+   * Trace flare on first contact, then heavy close-and-strike. `raiseAlarm`
+   * self-gates (false while already ALERT), so the flare yields exactly once
+   * per alarm window — identical cadence to the Probe.
+   */
+  protected override *engageSteps(world: World, rng: Rng, target: Entity): EngageSteps {
+    const raised = world.raiseAlarm({
+      source: this,
+      target,
+      origin: { x: this.x, y: this.y },
+      repPenalty: false,
+    });
+    if (raised) {
+      yield { type: 'trace-alarm', target: target.id };
+    }
+
+    const meleeCheck = canMelee(world, this, target);
+    if (meleeCheck.ok) {
+      const result = resolveMelee(world, this, target, rng);
+      yield { type: 'melee', target: target.id, result };
+      return 'continue';
+    }
+    if (meleeCheck.reason !== 'not-adjacent' && meleeCheck.reason !== 'insufficient-ap') {
+      return 'break';
+    }
+    if (this.ap < AP_COST.MOVE) return 'break';
+    const step = this.stepToward(world, target.x, target.y, 'engage');
+    if (!step) return 'break';
+    yield step;
+    return 'continue';
+  }
+}
diff --git a/src/game/cyber/ProbeIce.ts b/src/game/cyber/ProbeIce.ts
index 7ce0534..c528545 100644
--- a/src/game/cyber/ProbeIce.ts
+++ b/src/game/cyber/ProbeIce.ts
@@ -9,10 +9,10 @@
  * Unlike the Lookout it *listens* for alarms (the `PatrolHostile` default):
  * one probe's flare is every probe's heading.
  *
- * Stats are explicit and small — ICE scaling is its own axis (Spark and
- * Guardian ICE are the follow-up slices), so `resolveEnemyStats` tiers are
- * deliberately not reused. The avatar's `iceResistance` mitigates the weak
- * strike down to the engine-wide minimum of 1.
+ * Stats are explicit and small — ICE scaling is its own axis (the Spark and
+ * Guardian siblings carry their own explicit blocks too), so `resolveEnemyStats`
+ * tiers are deliberately not reused. The avatar's `iceResistance` mitigates the
+ * weak strike down to the engine-wide minimum of 1.
  */
 import { PatrolHostile, type PatrolHostileInit, type EngageSteps } from '../ai/PatrolHostile.js';
 import { AP_COST, PROBE_ICE_GLYPH } from '../constants.js';
@@ -24,7 +24,14 @@ import type { Rng } from '../../rng.js';
 export const PROBE_ICE_HP = 2;
 export const PROBE_ICE_AP = 2;
 export const PROBE_ICE_DAMAGE = 1;
-export const PROBE_ICE_SIGHT_RANGE = 6;
+/**
+ * Longest sight of the three ICE types (Spark 6, Guardian 5). The Probe's job
+ * is to *see* the intruder first and trip the trace flare that wakes the pack
+ * — so it earns the widest detection radius while staying the weakest in a
+ * fight. Roster composition (P3.M3) reflects the same role split: Guardians
+ * hold the data nodes, Probes patrol the approaches, Sparks swarm the flare.
+ */
+export const PROBE_ICE_SIGHT_RANGE = 7;
 
 export interface ProbeIceProps extends Omit<PatrolHostileInit, 'glyph'> {}
 
diff --git a/src/game/cyber/SparkIce.ts b/src/game/cyber/SparkIce.ts
new file mode 100644
index 0000000..d76c308
--- /dev/null
+++ b/src/game/cyber/SparkIce.ts
@@ -0,0 +1,75 @@
+/**
+ * P3.M3 — Spark ICE: the fast, fragile swarm attacker of the cyber grid.
+ *
+ * Where the Probe is the *detector* (long sight, trace flare) and the Guardian
+ * the *parked heavy*, the Spark is the **silent fast responder**. It does NOT
+ * raise the trace flare itself — it *listens* for one (the `PatrolHostile`
+ * alarm default) and converges at speed. Its identity is action economy:
+ *
+ *   - `SPARK_ICE_AP = 4` — double the Probe's budget. It closes three tiles and
+ *     strikes in a single activation, so a flare anywhere on the grid pulls a
+ *     wave of Sparks onto the avatar the very next turn — the swarm.
+ *   - `SPARK_ICE_HP = 1` — one avatar swing deletes it. The threat is numbers
+ *     and tempo, never durability.
+ *
+ * Engage is plain close-and-strike (the Guard loop); the chip strike is
+ * mitigated to the engine-wide minimum of 1 by the avatar's `iceResistance`.
+ * ICE stats are an explicit axis (no `resolveEnemyStats` tiers) — see ProbeIce.
+ */
+import { PatrolHostile, type PatrolHostileInit, type EngageSteps } from '../ai/PatrolHostile.js';
+import { AP_COST, SPARK_ICE_GLYPH } from '../constants.js';
+import { canMelee, resolveMelee } from '../Combat.js';
+import type { Entity } from '../Entity.js';
+import type { World } from '../World.js';
+import type { Rng } from '../../rng.js';
+
+export const SPARK_ICE_HP = 1;
+export const SPARK_ICE_AP = 4;
+export const SPARK_ICE_DAMAGE = 1;
+export const SPARK_ICE_SIGHT_RANGE = 6;
+
+export interface SparkIceProps extends Omit<PatrolHostileInit, 'glyph'> {}
+
+export class SparkIce extends PatrolHostile {
+  /** Sniffed by `Combat.attackerMeleeDamage` — the chip strike. */
+  readonly meleeDamage = SPARK_ICE_DAMAGE;
+
+  constructor({
+    maxHp = SPARK_ICE_HP,
+    maxAp = SPARK_ICE_AP,
+    sightRange = SPARK_ICE_SIGHT_RANGE,
+    patrolWaypoints,
+    ...props
+  }: SparkIceProps) {
+    super({
+      ...props,
+      maxAp,
+      maxHp,
+      sightRange,
+      glyph: SPARK_ICE_GLYPH,
+      displayName: 'Spark',
+      patrolWaypoints,
+    });
+  }
+
+  /**
+   * Silent close-and-strike. No trace flare — the Spark rides the Probe/Guardian
+   * alarm to find the avatar, then spends its deep AP pool closing and biting.
+   */
+  protected override *engageSteps(world: World, rng: Rng, target: Entity): EngageSteps {
+    const meleeCheck = canMelee(world, this, target);
+    if (meleeCheck.ok) {
+      const result = resolveMelee(world, this, target, rng);
+      yield { type: 'melee', target: target.id, result };
+      return 'continue';
+    }
+    if (meleeCheck.reason !== 'not-adjacent' && meleeCheck.reason !== 'insufficient-ap') {
+      return 'break';
+    }
+    if (this.ap < AP_COST.MOVE) return 'break';
+    const step = this.stepToward(world, target.x, target.y, 'engage');
+    if (!step) return 'break';
+    yield step;
+    return 'continue';
+  }
+}
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index 9d59a07..db81e7c 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -83,6 +83,10 @@ import { DataNode } from './cyber/DataNode.js';
 import type { DataNodeInit, DataNodeSnapshot } from './cyber/DataNode.js';
 import { ProbeIce } from './cyber/ProbeIce.js';
 import type { ProbeIceProps } from './cyber/ProbeIce.js';
+import { SparkIce } from './cyber/SparkIce.js';
+import type { SparkIceProps } from './cyber/SparkIce.js';
+import { GuardianIce } from './cyber/GuardianIce.js';
+import type { GuardianIceProps } from './cyber/GuardianIce.js';
 import type { DeckerInit, DeckerSnapshot } from './archetypes/Decker.js';
 import { Run, RUN_STATE, PATROL_ARCHETYPE_IDS } from './Run.js';
 import { Campaign, CAMPAIGN_STATE, normalizeCampaignArc } from './Campaign.js';
@@ -232,6 +236,8 @@ const ARCHETYPE_FACTORY: Record<EntityArchetypeId, (props: RestoreEntityProps) =
     'entry-port': (props: RestoreEntityProps) => new EntryPort(props as EntryPortInit),
     'data-node': (props: RestoreEntityProps) => new DataNode(props as DataNodeInit),
     'probe-ice': (props: RestoreEntityProps) => new ProbeIce(props as ProbeIceProps),
+    'spark-ice': (props: RestoreEntityProps) => new SparkIce(props as SparkIceProps),
+    'guardian-ice': (props: RestoreEntityProps) => new GuardianIce(props as GuardianIceProps),
     'breaching-charge': (props: RestoreEntityProps) =>
       new BreachingCharge(props as BreachingChargeInit),
     // Generic fallback so a future `Entity` subclass (NPCs, items) doesn't break
diff --git a/src/render/AsciiRenderer.ts b/src/render/AsciiRenderer.ts
index a3662a2..a9cb626 100644
--- a/src/render/AsciiRenderer.ts
+++ b/src/render/AsciiRenderer.ts
@@ -168,8 +168,8 @@ export class AsciiRenderer {
   /**
    * Render a world centred on `followTarget` (any object with x, y), unless
    * `options.camera` is set — then that rectangle (world tile coords) is drawn
-   * in full, which sizes the visible tile count (use for whole-map debug views).
-   * Pass `options.vision` (a `VisionField`) for fog-of-war fading.
+   * in full (used by the P3.M3.7 meatspace CCTV overlay with a second renderer
+   * instance). Pass `options.vision` (a `VisionField`) for fog-of-war fading.
    */
   draw(world: World, followTarget: Entity, options: DrawOptions = {}) {
     this.#syncViewport();
diff --git a/src/render/pip.ts b/src/render/pip.ts
new file mode 100644
index 0000000..6eb08df
--- /dev/null
+++ b/src/render/pip.ts
@@ -0,0 +1,91 @@
+/**
+ * P3.M3.7 — Jacked-in body CCTV (PIP) helpers.
+ *
+ * Pure presentation seam: the shell paints meatspace in a small overlay while
+ * the Decker is on the grid. M4 will swap `pipFollowTargetOf` / `pipWorldOf`
+ * to track whichever layer is *inactive* after the simstim flip.
+ */
+import { formatHpSegments } from './combatHud.js';
+import { cameraFor, type Camera, type Viewport } from './frame.js';
+import type { Entity } from '../game/Entity.js';
+import type { World } from '../game/World.js';
+
+/** Matches `#pip-canvas` pixel size at `PIP_CELL_SIZE` (160×100). */
+export const PIP_VIEWPORT_TILES = Object.freeze({ width: 16, height: 10 });
+export const PIP_CELL_SIZE = 10;
+
+export type PipHudRow = {
+  text: string;
+  anchor: 'top-left' | 'top-right';
+  row?: number;
+  color?: string;
+  glowColor?: string;
+  accentColor?: string;
+  uppercase?: boolean;
+  segments?: readonly { text: string; color: string; glowColor?: string }[];
+};
+
+export type PipCyberspacePhase = 'dormant' | 'active' | 'resolved';
+
+export type PipRunView = {
+  cyberspace?: { phase: PipCyberspacePhase } | null;
+  world?: World | null;
+  player?: Entity | null;
+};
+
+export function shouldShowPip(run: PipRunView | null | undefined): boolean {
+  return run?.cyberspace?.phase === 'active' && run.world != null && run.player != null;
+}
+
+/** Inactive layer world while jacked in — meat body feed until M4 flip. */
+export function pipWorldOf(run: PipRunView | null | undefined): World | null {
+  return shouldShowPip(run) ? (run!.world ?? null) : null;
+}
+
+export function pipFollowTargetOf(run: PipRunView | null | undefined): Entity | null {
+  return shouldShowPip(run) ? (run!.player ?? null) : null;
+}
+
+export function pipViewport(): Viewport {
+  return { width: PIP_VIEWPORT_TILES.width, height: PIP_VIEWPORT_TILES.height };
+}
+
+/**
+ * Center on the body, then clamp so the viewport stays inside the grid when
+ * the jack-in terminal is near a map edge.
+ */
+export function pipCameraFor(
+  body: Entity,
+  world: World,
+  viewport: Viewport = pipViewport()
+): Camera {
+  const camera = cameraFor(body, viewport);
+  const maxX = Math.max(0, world.grid.width - viewport.width);
+  const maxY = Math.max(0, world.grid.height - viewport.height);
+  return {
+    ...camera,
+    x: Math.max(0, Math.min(camera.x, maxX)),
+    y: Math.max(0, Math.min(camera.y, maxY)),
+  };
+}
+
+export function pipChrome(body: Entity): PipHudRow[] {
+  const hpText = formatHpSegments({ hp: body.hp, maxHp: body.maxHp, label: 'BODY' });
+  return [
+    {
+      text: '// CCTV //',
+      anchor: 'top-left',
+      uppercase: true,
+      color: '#9ff3da',
+      glowColor: '#6ae8c8',
+      accentColor: 'rgba(0, 217, 165, 0.5)',
+    },
+    {
+      text: hpText,
+      anchor: 'top-right',
+      color: '#6ae8c8',
+      glowColor: '#6ae8c8',
+      accentColor: 'rgba(0, 217, 165, 0.5)',
+    },
+  ];
+}
diff --git a/sw-core.js b/sw-core.js
index b3f1979..f614c5b 100644
--- a/sw-core.js
+++ b/sw-core.js
@@ -136,6 +136,7 @@ const CacheConfig = {
       '/src/render/combatHud.js',
       '/src/render/CrtFilter.js',
       '/src/render/frame.js',
+      '/src/render/pip.js',
       '/src/render/palette.js',
       '/src/render/principalTerrainPalettes.js',
       '/src/rng.js',
diff --git a/sw-dev.js b/sw-dev.js
index 7a0e5dd..6098667 100644
--- a/sw-dev.js
+++ b/sw-dev.js
@@ -1,5 +1,5 @@
 // Service Worker for Kernel Panic - Development Version
-const VERSION = '0.2.15-dev';
+const VERSION = '0.2.16-dev';
 importScripts(`/sw-core.js?v=${VERSION}`);
 
 const cacheConfig = CacheConfig.create(VERSION);
diff --git a/sw.js b/sw.js
index 0b5e68d..ed0b0fc 100644
--- a/sw.js
+++ b/sw.js
@@ -1,6 +1,6 @@
 // Service Worker for Kernel Panic - Production Version
 // Import shared caching core with cache-busting query parameter
-const VERSION = '0.2.15';
+const VERSION = '0.2.16';
 importScripts(`/sw-core.js?v=${VERSION}`);
 
 const cacheConfig = CacheConfig.create(VERSION);
diff --git a/tests/unit/game/cyber/CyberspaceLayer.test.ts b/tests/unit/game/cyber/CyberspaceLayer.test.ts
index 7d54a80..c942872 100644
--- a/tests/unit/game/cyber/CyberspaceLayer.test.ts
+++ b/tests/unit/game/cyber/CyberspaceLayer.test.ts
@@ -11,6 +11,10 @@ import assert from 'node:assert/strict';
 import { CyberspaceLayer } from '../../../../src/game/cyber/CyberspaceLayer.js';
 import { CyberAvatar } from '../../../../src/game/cyber/CyberAvatar.js';
 import { EntryPort } from '../../../../src/game/cyber/EntryPort.js';
+import { DataNode } from '../../../../src/game/cyber/DataNode.js';
+import { ProbeIce } from '../../../../src/game/cyber/ProbeIce.js';
+import { SparkIce } from '../../../../src/game/cyber/SparkIce.js';
+import { GuardianIce } from '../../../../src/game/cyber/GuardianIce.js';
 import { Decker } from '../../../../src/game/archetypes/Decker.js';
 import { ALARM_PHASE } from '../../../../src/game/World.js';
 import { EVENT } from '../../../../src/game/events.js';
@@ -70,16 +74,26 @@ test('build spawns the avatar at the entry tile with stats from the Decker', ()
   assert.equal(avatar.baseHitChance, CYBER_AVATAR_HIT_CHANCE);
 });
 
-test('the cyber world census: avatar, exit port, nodes, ring probes', () => {
+test('the cyber world census: avatar, exit port, data nodes, ICE roster', () => {
+  // nodeCount 1 (the cyber-data-spike / Score shape): 1 data node ⇒ 1 Guardian.
   const layer = buildLayer();
   const entities = Array.from(layer.world.entities.values());
+  const dataNodes = entities.filter(e => e instanceof DataNode).length;
+  const guardians = entities.filter(e => e instanceof GuardianIce).length;
+  const probes = entities.filter(e => e instanceof ProbeIce).length;
+  const sparks = entities.filter(e => e instanceof SparkIce).length;
+
   assert.equal(entities.filter(e => e instanceof CyberAvatar).length, 1);
   assert.equal(entities.filter(e => e instanceof EntryPort).length, 1);
+  assert.equal(dataNodes, 1, 'one contract data node');
+  // One Guardian per data node (it guards the prize); the rest of the rings
+  // patrol with Probes; the Sparks are the difficulty-scaled swarm (standard 1).
+  assert.equal(guardians, dataNodes, 'a Guardian holds every data node');
+  assert.equal(probes, layer.patrolRings.length - dataNodes, 'Probes patrol the other rings');
+  assert.equal(sparks, 1, 'standard difficulty seeds one Spark');
   assert.equal(
     entities.length,
-    // avatar + port + the contract data node (P3.M3.4) + one Probe per
-    // patrol ring (P3.M3.5).
-    3 + layer.patrolRings.length,
+    2 + dataNodes + guardians + probes + sparks,
     'no surprise entities on the cyber grid'
   );
   const cheb = Math.max(
diff --git a/tests/unit/game/cyber/ProbeIce.test.ts b/tests/unit/game/cyber/ProbeIce.test.ts
index dcc0977..d3b7c21 100644
--- a/tests/unit/game/cyber/ProbeIce.test.ts
+++ b/tests/unit/game/cyber/ProbeIce.test.ts
@@ -102,10 +102,11 @@ function probeKey(p: ProbeIce) {
 
 // --- spawning -------------------------------------------------------------------------
 
-test('build spawns one probe per patrol ring with explicit ICE stats', () => {
+test('build patrols the non-data rings with Probes carrying explicit ICE stats', () => {
+  // nodeCount 1 ⇒ one ring becomes a Guardian's data node; the rest patrol.
   const layer = buildLayer();
   const probes = probesOf(layer);
-  assert.equal(probes.length, layer.patrolRings.length);
+  assert.equal(probes.length, layer.patrolRings.length - 1, 'one ring guards a data node');
   assert.ok(probes.length > 0, 'standard difficulty patrols at least one ring');
   const ids = new Set(probes.map(p => p.id));
   assert.equal(ids.size, probes.length, 'probe ids are unique');
@@ -114,7 +115,7 @@ test('build spawns one probe per patrol ring with explicit ICE stats', () => {
     assert.equal(probe.displayName, 'Probe');
     assert.equal(probe.maxHp, 2);
     assert.equal(probe.maxAp, 2);
-    assert.equal(probe.sightRange, 6);
+    assert.equal(probe.sightRange, 7, 'the detector has the longest sight of the ICE');
     assert.equal(probe.meleeDamage, 1);
     assert.equal(probe.faction, FACTION.CORP);
     assert.ok(probe.patrolWaypoints.length > 0, 'probe walks a ring');
diff --git a/tests/unit/game/cyber/dualPhaseTurn.test.ts b/tests/unit/game/cyber/dualPhaseTurn.test.ts
index 9d04db1..eaefc80 100644
--- a/tests/unit/game/cyber/dualPhaseTurn.test.ts
+++ b/tests/unit/game/cyber/dualPhaseTurn.test.ts
@@ -11,6 +11,7 @@ import assert from 'node:assert/strict';
 import { Run } from '../../../../src/game/Run.js';
 import { CyberspaceLayer } from '../../../../src/game/cyber/CyberspaceLayer.js';
 import { ProbeIce } from '../../../../src/game/cyber/ProbeIce.js';
+import { PatrolHostile } from '../../../../src/game/ai/PatrolHostile.js';
 import { JackInPoint } from '../../../../src/game/entities/JackInPoint.js';
 import { runCorpTurn } from '../../../../src/game/corpTurnDriver.js';
 import { buildCrewMember } from '../../../../src/game/archetypes/index.js';
@@ -100,27 +101,27 @@ function dualPhaseRound(run: Run, layer: CyberspaceLayer): { meat: StepLog; ice:
   return { meat, ice };
 }
 
-function probeIds(layer: CyberspaceLayer): Set<string> {
+function iceIds(layer: CyberspaceLayer): Set<string> {
   return new Set(
     Array.from(layer.world.entities.values())
-      .filter(e => e instanceof ProbeIce)
+      .filter(e => e instanceof PatrolHostile)
       .map(e => e.id)
   );
 }
 
 // --- isolation -----------------------------------------------------------------------
 
-test('the meat pass steps only meat hostiles; the ICE pass only probes', () => {
+test('the meat pass steps only meat hostiles; the ICE pass only ICE', () => {
   const { run, layer } = jackedInRun();
-  const probes = probeIds(layer);
+  const ids = iceIds(layer);
   const { meat, ice } = dualPhaseRound(run, layer);
 
   for (const { id } of meat) {
-    assert.ok(!probes.has(id), `meat pass must not step ICE (stepped ${id})`);
+    assert.ok(!ids.has(id), `meat pass must not step ICE (stepped ${id})`);
   }
-  assert.ok(ice.length > 0, 'probes patrol their rings');
+  assert.ok(ice.length > 0, 'ICE patrol their rings');
   for (const { id } of ice) {
-    assert.ok(probes.has(id), `ICE pass stepped a non-probe (${id})`);
+    assert.ok(ids.has(id), `ICE pass stepped a non-ICE entity (${id})`);
   }
 });
 
diff --git a/tests/unit/game/cyber/iceRoster.test.ts b/tests/unit/game/cyber/iceRoster.test.ts
new file mode 100644
index 0000000..17175f7
--- /dev/null
+++ b/tests/unit/game/cyber/iceRoster.test.ts
@@ -0,0 +1,253 @@
+/**
+ * P3.M3 — Spark + Guardian ICE and the cyber-grid roster composition.
+ *
+ * Three distinct silhouettes share the patrol state machine:
+ *   - **Probe**  — long-sighted detector, patrols the approach rings.
+ *   - **Spark**  — fast/fragile swarm; rides the trace flare, never raises it.
+ *   - **Guardian** — heavy node guard; parks on a data node, strikes hard.
+ *
+ * The roster ties each role to map geometry: one Guardian per data node, a
+ * Probe on every other ring, and a difficulty-scaled Spark swarm.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { CyberspaceLayer } from '../../../../src/game/cyber/CyberspaceLayer.js';
+import { ProbeIce } from '../../../../src/game/cyber/ProbeIce.js';
+import { SparkIce } from '../../../../src/game/cyber/SparkIce.js';
+import { GuardianIce } from '../../../../src/game/cyber/GuardianIce.js';
+import { DataNode } from '../../../../src/game/cyber/DataNode.js';
+import { PATROL_STATE } from '../../../../src/game/ai/PatrolHostile.js';
+import { Decker } from '../../../../src/game/archetypes/Decker.js';
+import { resolveMelee } from '../../../../src/game/Combat.js';
+import { Run, RUN_STATE } from '../../../../src/game/Run.js';
+import { JackInPoint } from '../../../../src/game/entities/JackInPoint.js';
+import { snapshot, restore } from '../../../../src/game/persistence.js';
+import { buildCrewMember } from '../../../../src/game/archetypes/index.js';
+import { FACTION, type ContractDifficulty } from '../../../../src/game/constants.js';
+import { OBJECTIVES } from '../../../../src/game/hub/Curator.js';
+import { Rng } from '../../../../src/rng.js';
+import { testContractContext } from '../contractTestUtils.js';
+import type { World } from '../../../../src/game/World.js';
+import type { Entity } from '../../../../src/game/Entity.js';
+
+function buildLayer(
+  opts: {
+    contractSeed?: number;
+    difficulty?: ContractDifficulty;
+    nodeCount?: number;
+  } = {}
+) {
+  const { contractSeed = 12345, difficulty = 'standard', nodeCount = 1 } = opts;
+  return CyberspaceLayer.build({
+    contractSeed,
+    difficulty,
+    decker: new Decker({ id: 'crew-decker', x: 0, y: 0 }),
+    nodeCount,
+  });
+}
+
+const ofType = <T extends Entity>(layer: CyberspaceLayer, ctor: new (...a: never[]) => T): T[] =>
+  Array.from(layer.world.entities.values()).filter((e): e is T => e instanceof ctor);
+
+function adjacentFreeTile(world: World, target: Entity) {
+  for (let dy = -1; dy <= 1; dy++) {
+    for (let dx = -1; dx <= 1; dx++) {
+      if (dx === 0 && dy === 0) continue;
+      const x = target.x + dx;
+      const y = target.y + dy;
+      if (world.grid.inBounds(x, y) && world.grid.isPassable(x, y) && !world.entityAt(x, y)) {
+        return { x, y };
+      }
+    }
+  }
+  throw new Error(`no free tile adjacent to ${target.id}`);
+}
+
+// --- Spark stats ----------------------------------------------------------------------
+
+test('Spark is the fast, fragile swarm attacker', () => {
+  const spark = ofType(buildLayer(), SparkIce)[0];
+  assert.ok(spark instanceof SparkIce);
+  assert.equal(spark.glyph, '×');
+  assert.equal(spark.displayName, 'Spark');
+  assert.equal(spark.maxHp, 1, 'one swing deletes it');
+  assert.equal(spark.maxAp, 4, 'deep AP pool — it closes and bites in one activation');
+  assert.equal(spark.sightRange, 6);
+  assert.equal(spark.meleeDamage, 1);
+  assert.equal(spark.faction, FACTION.CORP);
+});
+
+test('Spark rides the trace flare but never raises one', () => {
+  const layer = buildLayer();
+  const spark = ofType(layer, SparkIce)[0];
+  // Move it well clear of the avatar so its own turn cannot acquire a target.
+  assert.equal(spark.state, PATROL_STATE.PATROL);
+  const before = layer.world.alarmActive;
+  // A flare from elsewhere drags the Spark to ENGAGE (it listens for alarms).
+  layer.world.raiseAlarm({ target: layer.avatar, repPenalty: false });
+  assert.equal(before, false);
+  assert.equal(spark.state, PATROL_STATE.ENGAGE, 'the swarm converges on the flare');
+  assert.deepEqual(spark.lastKnownTarget, { x: layer.avatar.x, y: layer.avatar.y });
+});
+
+// --- Guardian stats -------------------------------------------------------------------
+
+test('Guardian is the heavy node guard that holds station', () => {
+  const layer = buildLayer();
+  const guardian = ofType(layer, GuardianIce)[0];
+  assert.ok(guardian instanceof GuardianIce);
+  assert.equal(guardian.glyph, 'Ψ');
+  assert.equal(guardian.displayName, 'Guardian');
+  assert.equal(guardian.maxHp, 6, 'three avatar swings to break');
+  assert.equal(guardian.maxAp, 2, 'limited mobility');
+  assert.equal(guardian.sightRange, 5, 'shortest sight — it reacts at its node');
+  assert.equal(guardian.meleeDamage, 3);
+  assert.equal(guardian.faction, FACTION.CORP);
+  assert.equal(guardian.patrolWaypoints.length, 0, 'no patrol — it parks on the prize');
+
+  // It guards a data node: spawned within its node, close to the slice target.
+  const node = ofType(layer, DataNode)[0];
+  const cheb = Math.max(Math.abs(guardian.x - node.x), Math.abs(guardian.y - node.y));
+  assert.ok(cheb <= 3, 'the Guardian stands on the data node it guards');
+});
+
+test("Guardian's heavy strike beats ICE resistance", () => {
+  const layer = buildLayer();
+  const avatar = layer.avatar; // RAM 8, iceResistance 1
+  const guardian = ofType(layer, GuardianIce)[0];
+  const spot = adjacentFreeTile(layer.world, avatar);
+  layer.world.relocateEntity(guardian, spot.x, spot.y);
+  guardian.refreshAp();
+
+  const result = resolveMelee(layer.world, guardian, avatar, new Rng(1), { dodgeChance: 0 });
+  assert.equal(result.hit, true);
+  assert.equal(result.damage, 2, 'dmg 3 vs resist 1 lands 2 — the prize bites back');
+  assert.equal(avatar.hp, avatar.maxHp - 2);
+});
+
+// --- roster composition ----------------------------------------------------------------
+
+const rosterCounts = (layer: CyberspaceLayer) => ({
+  data: ofType(layer, DataNode).length,
+  guardians: ofType(layer, GuardianIce).length,
+  probes: ofType(layer, ProbeIce).length,
+  sparks: ofType(layer, SparkIce).length,
+});
+
+test('one Guardian per data node; Probes on the remaining rings', () => {
+  for (const [difficulty, nodeCount] of [
+    ['standard', 1],
+    ['elevated', 2],
+    ['critical', 3],
+  ] as const) {
+    const layer = buildLayer({ difficulty, nodeCount });
+    const c = rosterCounts(layer);
+    assert.equal(c.data, nodeCount, `${difficulty}: ${nodeCount} data nodes`);
+    assert.equal(c.guardians, nodeCount, `${difficulty}: a Guardian per data node`);
+    assert.equal(
+      c.probes,
+      layer.patrolRings.length - nodeCount,
+      `${difficulty}: Probes patrol every non-data ring`
+    );
+  }
+});
+
+test('the Spark swarm scales with contract difficulty', () => {
+  assert.equal(rosterCounts(buildLayer({ difficulty: 'standard', nodeCount: 1 })).sparks, 1);
+  assert.equal(rosterCounts(buildLayer({ difficulty: 'elevated', nodeCount: 1 })).sparks, 2);
+  assert.equal(rosterCounts(buildLayer({ difficulty: 'critical', nodeCount: 1 })).sparks, 3);
+});
+
+test('no two ICE stack on the same tile', () => {
+  const layer = buildLayer({ difficulty: 'critical', nodeCount: 3 });
+  const seen = new Set<string>();
+  for (const e of layer.world.entities.values()) {
+    if (e instanceof ProbeIce || e instanceof SparkIce || e instanceof GuardianIce) {
+      const key = `${e.x},${e.y}`;
+      assert.ok(!seen.has(key), `two ICE share tile ${key}`);
+      seen.add(key);
+    }
+  }
+});
+
+test('the full ICE roster is deterministic on the contract seed', () => {
+  const key = (layer: CyberspaceLayer) =>
+    Array.from(layer.world.entities.values())
+      .filter(e => e instanceof ProbeIce || e instanceof SparkIce || e instanceof GuardianIce)
+      .map(e => ({ id: e.id, x: e.x, y: e.y }))
+      .sort((a, b) => a.id.localeCompare(b.id));
+  const a = key(buildLayer({ contractSeed: 555, difficulty: 'critical', nodeCount: 3 }));
+  const b = key(buildLayer({ contractSeed: 555, difficulty: 'critical', nodeCount: 3 }));
+  assert.deepEqual(a, b);
+  const c = key(buildLayer({ contractSeed: 556, difficulty: 'critical', nodeCount: 3 }));
+  assert.notDeepEqual(a, c, 'a different seed diverges');
+});
+
+// --- persistence ----------------------------------------------------------------------
+
+const cyberContract = (seed = 12345) => ({
+  seed,
+  objective: {
+    kind: OBJECTIVES.DATA_NODE_SLICE,
+    title: 'Spike the server farm',
+    briefing: 'Jack in, slice the data node, then extract.',
+    params: { requiresCyberspace: true, count: 1 },
+  },
+  difficulty: 'standard',
+  threatCount: 1,
+  label: 'cyber test job',
+  context: testContractContext(OBJECTIVES.DATA_NODE_SLICE),
+  reward: { credits: 0, repDelta: 0 },
+});
+
+function jackedInLayer(seed = 12345): { run: Run; layer: CyberspaceLayer } {
+  const run = new Run({
+    crewMember: buildCrewMember('decker', { x: 0, y: 0 }, new Rng(100), { id: 'crew-decker' }),
+    seed,
+  });
+  run.enterBriefing(cyberContract(seed));
+  run.enterCombat();
+  const point = Array.from(run.world!.entities.values()).find(
+    e => e instanceof JackInPoint
+  ) as JackInPoint;
+  const spot = adjacentFreeTile(run.world!, point);
+  run.world!.relocateEntity(run.player!, spot.x, spot.y);
+  run.player!.refreshAp();
+  assert.equal(point.interact(run.world!, run.player!).ok, true);
+  assert.equal(run.state, RUN_STATE.COMBAT);
+  const layer = (run.cyberspace as { phase: 'active'; layer: CyberspaceLayer }).layer;
+  return { run, layer };
+}
+
+test('Spark and Guardian patrol state round-trips and re-binds', () => {
+  const { run, layer } = jackedInLayer();
+  const spark = ofType(layer, SparkIce)[0];
+  const guardian = ofType(layer, GuardianIce)[0];
+
+  // Dirty both state machines.
+  spark.state = PATROL_STATE.ENGAGE;
+  spark.lastKnownTarget = { x: layer.avatar.x, y: layer.avatar.y };
+  guardian.state = PATROL_STATE.INVESTIGATE;
+  guardian.lastKnownTarget = { x: layer.entryTile.x, y: layer.entryTile.y };
+  guardian.damage(2);
+
+  const { run: restored } = restore(structuredClone(snapshot(run)));
+  const restoredLayer = (restored.cyberspace as { phase: 'active'; layer: CyberspaceLayer }).layer;
+
+  const sparkTwin = ofType(restoredLayer, SparkIce).find(e => e.id === spark.id);
+  const guardianTwin = ofType(restoredLayer, GuardianIce).find(e => e.id === guardian.id);
+  assert.ok(sparkTwin instanceof SparkIce);
+  assert.ok(guardianTwin instanceof GuardianIce);
+  assert.equal(sparkTwin!.state, PATROL_STATE.ENGAGE);
+  assert.deepEqual(sparkTwin!.lastKnownTarget, spark.lastKnownTarget);
+  assert.equal(guardianTwin!.state, PATROL_STATE.INVESTIGATE);
+  assert.equal(guardianTwin!.hp, guardian.hp);
+  assert.equal(guardianTwin!.maxHp, 6);
+
+  // Re-binding: a fresh cyber flare drags the restored Spark to ENGAGE.
+  sparkTwin!.state = PATROL_STATE.PATROL;
+  sparkTwin!.lastKnownTarget = null;
+  restoredLayer.world.raiseAlarm({ target: restoredLayer.avatar, repPenalty: false });
+  assert.equal(sparkTwin!.state, PATROL_STATE.ENGAGE, 'restored Spark still listens for flares');
+});
diff --git a/tests/unit/render/AsciiRenderer.test.ts b/tests/unit/render/AsciiRenderer.test.ts
index 60e8f59..31e93f5 100644
--- a/tests/unit/render/AsciiRenderer.test.ts
+++ b/tests/unit/render/AsciiRenderer.test.ts
@@ -318,6 +318,21 @@ test('draw() omits combat HUD rows when combatHud is null', () => {
   assert.equal(hudText.length, 0);
 });
 
+test('draw() with an explicit camera offsets the map relative to followTarget', () => {
+  const canvas = makeCanvas();
+  const r = new AsciiRenderer(canvas, { now: () => 0, cellSize: 10 });
+  const { world, player } = makeWorld();
+
+  r.draw(world, player, {
+    camera: { x: player.x - 2, y: player.y - 2, width: 6, height: 4 },
+  });
+  const playerGlyph = canvas._drawCalls.find(c => c.op === 'text' && c.char === '@');
+  assert.ok(playerGlyph);
+  // Player is at world (16,10); camera top-left (14,8) → screen cell (2,2) → px center 25,25.
+  assert.equal(playerGlyph.px, 25);
+  assert.equal(playerGlyph.py, 25);
+});
+
 test('flashes outside the camera are silently skipped (but stay registered)', () => {
   const canvas = makeCanvas();
   const r = new AsciiRenderer(canvas, { now: () => 0 });
diff --git a/tests/unit/render/pip.test.ts b/tests/unit/render/pip.test.ts
new file mode 100644
index 0000000..802f55c
--- /dev/null
+++ b/tests/unit/render/pip.test.ts
@@ -0,0 +1,82 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { Grid } from '../../../src/game/Grid.js';
+import { World } from '../../../src/game/World.js';
+import { Entity } from '../../../src/game/Entity.js';
+import { FACTION } from '../../../src/game/constants.js';
+import {
+  pipCameraFor,
+  pipChrome,
+  pipViewport,
+  pipWorldOf,
+  pipFollowTargetOf,
+  shouldShowPip,
+  PIP_VIEWPORT_TILES,
+} from '../../../src/render/pip.js';
+
+function makeBody(x: number, y: number, hp = 5, maxHp = 8) {
+  const grid = new Grid(28, 18);
+  const world = new World(grid);
+  const body = new Entity({
+    id: 'body',
+    x,
+    y,
+    faction: FACTION.PLAYER,
+    glyph: '@',
+    maxHp,
+    hp,
+  });
+  world.addEntity(body);
+  return { world, body };
+}
+
+test('shouldShowPip is true only while cyberspace is active with world and player', () => {
+  const run = {
+    cyberspace: { phase: 'active' as const },
+    world: {},
+    player: {},
+  };
+  assert.equal(shouldShowPip(run), true);
+  assert.equal(shouldShowPip({ ...run, cyberspace: { phase: 'dormant' } }), false);
+  assert.equal(shouldShowPip({ ...run, cyberspace: { phase: 'resolved' } }), false);
+  assert.equal(shouldShowPip({ ...run, world: null }), false);
+  assert.equal(shouldShowPip(null), false);
+});
+
+test('pipWorldOf and pipFollowTargetOf gate on shouldShowPip', () => {
+  const { world, body } = makeBody(5, 6);
+  const active = { cyberspace: { phase: 'active' as const }, world, player: body };
+  assert.equal(pipWorldOf(active), world);
+  assert.equal(pipFollowTargetOf(active), body);
+  assert.equal(pipWorldOf({ cyberspace: { phase: 'dormant' }, world, player: body }), null);
+});
+
+test('pipViewport matches pip canvas tile footprint', () => {
+  assert.deepEqual(pipViewport(), PIP_VIEWPORT_TILES);
+});
+
+test('pipCameraFor centers on the body', () => {
+  const { world, body } = makeBody(14, 9);
+  const camera = pipCameraFor(body, world);
+  assert.equal(camera.width, 16);
+  assert.equal(camera.height, 10);
+  assert.equal(camera.x, body.x - Math.floor(16 / 2));
+  assert.equal(camera.y, body.y - Math.floor(10 / 2));
+});
+
+test('pipCameraFor clamps near map edges', () => {
+  const { world, body } = makeBody(1, 1);
+  const camera = pipCameraFor(body, world);
+  assert.equal(camera.x, 0);
+  assert.equal(camera.y, 0);
+});
+
+test('pipChrome labels the feed and body HP', () => {
+  const { body } = makeBody(0, 0, 3, 8);
+  const rows = pipChrome(body);
+  assert.equal(rows[0]?.text, '// CCTV //');
+  assert.equal(rows[0]?.anchor, 'top-left');
+  assert.match(rows[1]?.text ?? '', /^BODY /);
+  assert.equal(rows[1]?.anchor, 'top-right');
+});

From 62934139e5debf265b3bb05af706040ced21c17c Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Sun, 14 Jun 2026 14:29:34 -0700
Subject: [PATCH 32/55] refactor shell code

---
 docs/kaizen.md                          |   19 +-
 index.ts                                | 2941 +----------------------
 src/game/Run.ts                         |   22 +-
 src/shell/activeView.ts                 |   54 +
 src/shell/combatHudSnapshot.ts          |   64 +
 src/shell/domTypes.ts                   |  171 ++
 src/shell/locationHud.ts                |   58 +
 src/shell/sceneListeners.ts             |  204 ++
 src/shell/sceneView.ts                  |   29 +
 src/shell/shellRuntime.ts               | 2430 +++++++++++++++++++
 src/shell/statusLine.ts                 |  181 ++
 src/shell/visionSync.ts                 |   77 +
 sw-core.js                              |    9 +
 sw-dev.js                               |    2 +-
 sw.js                                   |    2 +-
 tests/unit/game/cyber/jackOut.test.ts   |   19 +
 tests/unit/shell/activeView.test.ts     |  108 +
 tests/unit/shell/sceneListeners.test.ts |   58 +
 tests/unit/shell/statusLine.test.ts     |  126 +
 19 files changed, 3642 insertions(+), 2932 deletions(-)
 create mode 100644 src/shell/activeView.ts
 create mode 100644 src/shell/combatHudSnapshot.ts
 create mode 100644 src/shell/domTypes.ts
 create mode 100644 src/shell/locationHud.ts
 create mode 100644 src/shell/sceneListeners.ts
 create mode 100644 src/shell/sceneView.ts
 create mode 100644 src/shell/shellRuntime.ts
 create mode 100644 src/shell/statusLine.ts
 create mode 100644 src/shell/visionSync.ts
 create mode 100644 tests/unit/shell/activeView.test.ts
 create mode 100644 tests/unit/shell/sceneListeners.test.ts
 create mode 100644 tests/unit/shell/statusLine.test.ts

diff --git a/docs/kaizen.md b/docs/kaizen.md
index 9ac466a..717ca03 100644
--- a/docs/kaizen.md
+++ b/docs/kaizen.md
@@ -38,19 +38,12 @@ When an item lands, gets reclassified, or develops new context, edit it in place
   - **Clean constraints as modifiers:** no alarm, no civilian harm, no kills, under turn budget. Treat as bonus constraints / payout modifiers unless a future design proves one should be a base objective kind.
   - **Breach / demolition target:** place or detonate a breach charge at an authored wall or target. Mechanically adjacent to deny/destroy; Phase 2.5 M7 covers breaching foundations.
   - **Cyberspace / data-layer objectives:** jack in, slice data nodes, open locks, defeat or avoid ICE. Likely Phase 3 dual-layer objective work rather than plain Meatspace recipes.
-- **index.ts complexity:** Introduction of the Cyberspace layer pushed complexity of the core UI shell over a reasonable limit; candidates for cleanup / simplification identified:
-  - **ShellScene = Campaign | Run union** forces isRun() casts everywhere — ~15 sites narrow-and-cast; a SceneView
-  interface both classes implement would delete most of them.
-  - **statusLine()** is a ~110-line HTML string builder mixing a11y, alarm tags, hub identity, corp mood, and
-  activity-row layout — prime extraction target (pure function over a snapshot, like combatHud.ts already does).
-  - **Four duplicated attachVisionListener/Animation/Rep/Cyber blocks at every scene transition** — one
-  rewireSceneListeners() would collapse them and prevent the "forgot to add the new attach call" failure mode (I
-  had to touch all four for S7).
-  - **Listener-order coupling on the bus**: the shell's JACK_IN/JACK_OUT handlers depend on Run subscribing first
-  (true today, enforced nowhere). A bus.on(..., {priority}) or explicit shell callbacks on Run would make it
-  structural.
-  - **run.world/run.player direct reads remain legal** — the new active-view seam is convention, not
-  compiler-enforced; a lint rule or accessor deprecation would lock it in.
+- **index.ts complexity:** ~~Introduction of the Cyberspace layer pushed complexity of the core UI shell over a reasonable limit; candidates for cleanup / simplification identified:~~ **Partially closed (2026-06-14):** extracted `src/shell/` modules (`activeView`, `statusLine`, `sceneView`, `combatHudSnapshot`, `locationHud`, `visionSync`, `sceneListeners`, `shellRuntime`, `GameShell`); `index.ts` is now boot-only (~65 LOC). Remaining ◇ items:
+  - ~~**ShellScene = Campaign | Run union** forces isRun() casts everywhere~~ — `sceneView.ts` + `resolveSceneView` landed; casts reduced.
+  - ~~**statusLine()** is a ~110-line HTML string builder~~ — pure `formatStatusLine` in `statusLine.ts` with unit tests.
+  - ~~**Four duplicated attachVisionListener/Animation/Rep/Cyber blocks**~~ — `SceneListenerController.rewire()` + `rewireSceneListeners()`.
+  - ~~**Listener-order coupling on the bus** (JACK_IN/JACK_OUT)~~ — `Run.onJackInPresent` / `onJackOutPresent` shell hooks.
+  - **run.world/run.player direct reads remain legal** — active-view seam in `activeView.ts`; lint rule still ◇ Monitored.
 - ~~**Cyberspace playtesting feedback.**~~ **Closed 2026-06-14:** Probe ICE reduced from 3 HP / 4 AP to 2 HP / 2 AP; the CyberAvatar can use Override against ICE, including allied aftermath actions, reversion, and save round-trip; a pre-Score Decker flatline creates a free replacement Decker lead in the Terminal and gates THE SCORE until recruited; a Decker flatline during THE SCORE ends the campaign with explicit Game Over copy (`decker-flatlined-score`). See the P3.M3 playtest stabilization note in [phase-3-plan.md](phase-3-plan.md).
 
 ## ◇ Monitored
diff --git a/index.ts b/index.ts
index 1906928..4091c1b 100644
--- a/index.ts
+++ b/index.ts
@@ -1,106 +1,9 @@
 /**
- * Game shell. Promotes `/index.html` from the original scaffold to a real game:
- *
- *   - boots DataStore + service worker,
- *   - restores a saved campaign when present,
- *   - drives `Campaign` (HUB) plus one active `Run` job episode,
- *   - paints the canvas during HUB / COMBAT, swaps DOM overlays during
- *     BRIEFING / RESULT (per the original plan: "DOM panels above the canvas;
- *     canvas paints during HUB/COMBAT only"), plus <system-start> on a new
- *     campaign,
- *   - wires KeyboardController and <touch-pad> through the shared
- *     `applyIntent` helper that the debug harness also uses,
- *   - persists snapshots on every `turn:ended` and clears the save on
- *     DEATH / EXIT (autosave-on-turn-end per the locked-in decision).
- *
- * The debug harness at `/debug/index.html` continues to be the engineer-facing
- * surface (single hand-built scenario, log feed, archetype hot-swap). Both
- * shells share `applyIntent` so movement / combat plumbing has one consumer.
+ * Game shell entry — component registration and boot only.
+ * Orchestration lives in `/src/shell/shellRuntime.ts` via {@link GameShell}.
  */
 
-import { serviceWorkerManager } from '/src/ServiceWorkerManager.js';
-import dataStore from '/src/DataStore.js';
-
-import { Campaign, CAMPAIGN_STATE, willEndCampaignAfterResult } from '/src/game/Campaign.js';
-import { buildCampaignSummary, type CampaignSummary } from '/src/game/campaignSummary.js';
-import { totalSalvage, formatSalvageCompact, type TypedSalvage } from '/src/game/salvage.js';
-import { RUN_STATE, Run } from '/src/game/Run.js';
-import { restoreCampaign, snapshotCampaign } from '/src/game/persistence.js';
-import { runCorpTurn as driveCorpTurn } from '/src/game/corpTurnDriver.js';
-import {
-  FACTION,
-  AP_COST,
-  TILE,
-  REP,
-  REP_LABEL,
-  INCENDIARY_THROW_DIST,
-  BREACHING_CHARGE_RANGE,
-} from '/src/game/constants.js';
-import {
-  advanceFromPlayerTurn,
-  drivePlayerAftermath,
-  formatPlayerAftermathStepLogLines,
-  isPlayerAftermathStepLogVisible,
-} from '/src/game/combatTurnPipeline.js';
-import {
-  corpTurnStatusBody,
-  countVisibleCorpEntities,
-  formatCorpTurnStep,
-  isCorpTurnStepLogVisibleToPlayer,
-  isCorpTurnStepVisibleToPlayer,
-} from '/src/game/corpTurnStatusCopy.js';
-import { EVENT, alarmPayloadTriggersRepPenalty } from '/src/game/events.js';
-import { VisionField } from '/src/game/Vision.js';
-import { describeTileAt } from '/src/game/describe.js';
-import type { CyberspaceLayer } from '/src/game/cyber/CyberspaceLayer.js';
-import type { World } from '/src/game/World.js';
-import type { TilesetId } from '/src/render/palette.js';
-import { AsciiRenderer } from '/src/render/AsciiRenderer.js';
-import { CrtFilter } from '/src/render/CrtFilter.js';
-import {
-  ANIMATION_DURATIONS,
-  createAnimationLock,
-  runInteractSecuredFlash,
-  runMuzzleFlash,
-  triggerDamageFlash,
-  triggerShake,
-} from '/src/render/animations.js';
-import { Interactable } from '/src/game/entities/Interactable.js';
-import { KeyboardController } from '/src/input/KeyboardController.js';
-import { AIM_KIND, MODE, aimKindLabel } from '/src/input/keymap.js';
-import { applyIntent, PLAYER_ACTIONS } from '/src/input/applyIntent.js';
-import { recordStatusActionLine, statusActionRows } from '/src/statusActivityRows.js';
-
-import { placeSmoke, clearSmoke } from '/src/game/Smoke.js';
-import { placeHazardCluster } from '/src/game/Run.js';
-import { blastCells } from '/src/game/breachBlast.js';
-import { hasLineOfSight } from '/src/game/LineOfSight.js';
-import { ITEM_ID, getItemById } from '/src/game/items.js';
-import type { CampaignSnapshot } from '/src/game/persistence.js';
-import type { Contract } from '/src/game/hub/Curator.js';
-import {
-  formatHubArcStatusLines,
-  scorePrincipalId,
-  scoreTargetSiteId,
-} from '/src/game/hub/arcSurface.js';
-import {
-  commitHubReveal,
-  hubRevealCommitsOnDismiss,
-  isTerminalAccessible,
-  type HubRevealId,
-} from '/src/game/hub/hubReveals.js';
-import type { Crew } from '/src/game/Crew.js';
-import { resolveEntityLabel, type Entity } from '/src/game/Entity.js';
-import type { RunResult, RunTelemetry, Outcome } from '/src/game/Run.js';
-import type { Item } from '/src/game/items.js';
-import type { Intent } from '/src/input/applyIntent.js';
-import type { AimKind, Mode } from '/src/input/keymap.js';
-import { formatCombatHudA11ySummary } from '/src/render/combatHud.js';
-import type { CombatHudSummaryInput } from '/src/render/combatHud.js';
-import { pipCameraFor, pipChrome, shouldShowPip } from '/src/render/pip.js';
-import type { KeyItem, Telemetry, TurnActionStep } from '/src/types.js';
-import { installErrorBoundary, type FaultSignal } from '/src/errorBoundary.js';
-import { isDevelopmentMode } from '/src/domUtils.js';
+import { gameShell } from '/src/shell/GameShell.js';
 
 import '/components/ConfirmationModal.js';
 import '/components/UpdateNotification.js';
@@ -112,7 +15,6 @@ import '/components/GameOver.js';
 import '/components/FaultScreen.js';
 import '/components/SystemStart.js';
 import '/components/CuratorBriefing.js';
-import type { CuratorBriefingContent } from '/components/CuratorBriefing.js';
 import '/components/InitialRecruit.js';
 import '/components/CrewList.js';
 import '/components/CrewRoster.js';
@@ -121,2834 +23,43 @@ import '/components/ClinicModal.js';
 import '/components/ItemInventory.js';
 import KeyHelp from '/components/KeyHelp.js';
 
-// ---------------------------------------------------------------------------
-// State
-// ---------------------------------------------------------------------------
-
-type ShellScene = Campaign | Run;
-type SmokeOverlay = ReturnType<typeof placeSmoke>[number];
-type HelpScope = 'hub' | 'combat';
-type PointLike = Pick<Entity, 'x' | 'y'> | { x: number; y: number } | null | undefined;
-
-type ModalElement = HTMLElement & {
-  show(): void;
-  hide(): void;
-  readonly isOpen: boolean;
-};
-type RunBriefingElement = ModalElement & {
-  setContract(contract: Contract): void;
-  setCrew(crew: Crew[]): void;
-};
-type ContractSelectElement = ModalElement & {
-  setContracts(contracts: Contract[]): void;
-  setScoreTargetSiteId(siteId: string | null): void;
-  setScorePrincipalId(principalId: string | null): void;
-};
-type CrashDumpElement = ModalElement & {
-  setTelemetry(telemetry: Telemetry): void;
-};
-type GameOverElement = ModalElement & {
-  setSummary(summary: CampaignSummary): void;
-};
-type FaultScreenElement = ModalElement & {
-  show(detail: { code?: string }): void;
-};
-type SystemStartElement = ModalElement & {
-  setSession(session: { seed: number }): void;
-};
-type CuratorBriefingElement = ModalElement & {
-  setBriefing(content: CuratorBriefingContent): void;
-};
-type InitialRecruitElement = ModalElement & {
-  setCandidates(candidates: Crew[]): void;
-};
-type CrewRosterElement = ModalElement & {
-  setCrew(
-    crew: Crew[],
-    opts?: {
-      salvage?: TypedSalvage;
-      campaignStatus?: string | readonly string[];
-      availableRecruits?: Crew[];
-      recruitedThisVisit?: boolean;
-    }
-  ): void;
-};
-type FinnShopElement = ModalElement & {
-  setCatalog(
-    catalog: Item[],
-    crew: Crew[],
-    balances: { credits: number; salvage: TypedSalvage }
-  ): void;
-};
-type ClinicModalElement = ModalElement & {
-  setPatients(crew: Crew[], balances: { credits: number; healedMemberIds?: string[] }): void;
-};
-type ItemInventoryElement = ModalElement & {
-  setContents(contents: {
-    salvage?: TypedSalvage;
-    consumables?: NonNullable<Crew['inventory']>['consumables'];
-    keyItems?: KeyItem[];
-  }): void;
-  /** Legacy single-arg API — prefer `setContents`. */
-  setItems(consumables: NonNullable<Crew['inventory']>['consumables']): void;
-};
-type KeyHelpElement = ModalElement & {
-  setScope(scope: HelpScope, archetypeId?: string): void;
-};
-type TouchPadElement = HTMLElement & {
-  mode: Mode;
-  aimKind: AimKind | null;
-  setMode(mode: Mode, aimKind?: AimKind | null): void;
-  setBlocked(predicate: (() => boolean) | null): void;
-};
-type InputState = {
-  mode: Mode;
-  aimKind: AimKind | null;
-};
-type ConfirmationModalElement = HTMLElement & {
-  showModal(message: string, context?: unknown): void;
-};
-type UpdateNotificationElement = HTMLElement & {
-  show(pendingWorker: ServiceWorker | null): void;
-};
-
-type PendingJobResult = {
-  outcome: Outcome;
-  telemetry: RunTelemetry & { outcome: Outcome };
-};
-
-type EntityDamagedPayload = {
-  attacker?: Entity;
-  target?: Entity;
-  damage?: number;
-  killed?: boolean;
-  source?: string;
-};
-
-type NoisePayload = {
-  kind?: string;
-  origin?: { x: number; y: number };
-};
-
-type DoorUnlockPayload = {
-  label?: string;
-};
-
-/** Dev-only: `?triggerFault=corp` throws once on the next corp turn (see phase-2.6-plan). */
-let devFaultTrigger: string | null = null;
-let devFaultConsumed = false;
-
-function initDevFaultTrigger(): void {
-  if (!isDevelopmentMode()) return;
-  const param = new URLSearchParams(location.search).get('triggerFault');
-  if (!param) return;
-  devFaultTrigger = param;
-  if (param === 'rejection') {
-    devFaultConsumed = true;
-    Promise.reject(new Error('[dev] triggerFault=rejection'));
-  }
-}
-
-function maybeDevFault(site: string): void {
-  if (!devFaultTrigger || devFaultConsumed || devFaultTrigger !== site) return;
-  devFaultConsumed = true;
-  throw new Error(`[dev] triggerFault=${site}`);
-}
-
-let campaign: Campaign | null = null;
-let vision = new VisionField();
-/**
- * P3.M3.6: the cyber grid's own fog field — `vision` stays Meatspace-truth
- * for the body (aftermath visibility, meat corpse memory) while the avatar
- * sees through this one. Rebuilt (and re-seeded from `layer.mapSeen`) every
- * time the cyber listeners attach.
- */
-let cyberVision = new VisionField();
-let cyberUnsubs: (() => void)[] = [];
-let visionMoveUnsub: (() => void) | null = null;
-let repUnsubs: (() => void)[] = [];
-let civilianHarmsThisJob = 0;
-
-let canvas: HTMLCanvasElement;
-/** P3.M3.7: meatspace CCTV overlay while jacked in. */
-let pipCanvas: HTMLCanvasElement;
-let statusEl: HTMLElement | null = null;
-let renderer: AsciiRenderer;
-let pipRenderer: AsciiRenderer;
-let crt: CrtFilter;
-let stageEl: HTMLElement;
-let briefingEl: RunBriefingElement;
-let contractSelectEl: ContractSelectElement;
-let crashEl: CrashDumpElement;
-let gameOverEl: GameOverElement;
-let faultEl: FaultScreenElement;
-let systemStartEl: SystemStartElement;
-let curatorBriefingEl: CuratorBriefingElement;
-/** Status line to flash after the player dismisses a Hub reveal briefing. */
-let hubRevealFollowUpFlash: string | null = null;
-/** Score reveal (and future deferred reveals) commit their flag on dismiss. */
-let pendingHubRevealId: HubRevealId | null = null;
-let initialRecruitEl: InitialRecruitElement;
-let confirmationModalEl: ConfirmationModalElement;
-let touchPadEl: TouchPadElement;
-let crewRosterEl: CrewRosterElement;
-let finnShopEl: FinnShopElement;
-let clinicModalEl: ClinicModalElement;
-let itemInventoryEl: ItemInventoryElement;
-let keyHelpEl: KeyHelpElement;
-let logEl: HTMLElement;
-let logHeaderEl: HTMLElement;
-let logContentEl: HTMLPreElement;
-let keyboard: KeyboardController;
-
-let currentJobOptions: Contract[] = [];
-
-/**
- * Animation-lock for combat feedback. Listeners on the run bus
- * (`attachAnimationListeners`) push durations as effects fire; both
- * input controllers consult `isLocked()` so a key held mid-shake doesn't
- * sneak through. See `src/render/animations.js`.
- */
-const animLock = createAnimationLock();
-/** Unsubscribers for the run-bus animation listeners. Re-bound on every state transition. */
-let animationUnsubs: (() => void)[] = [];
-
-let pendingJobResult: PendingJobResult | null = null;
-/** Latched during tier-1 fault recovery — blocks autosave and stale turn pumps. */
-let degrading = false;
-/** Set when degradeToHub successfully re-read hub state from disk. */
-let faultHubRestored = false;
-/** Bumped to invalidate in-flight corp/aftermath setTimeout pumps after a fault. */
-let combatPumpGeneration = 0;
-
-function invalidateCombatPumps(): void {
-  combatPumpGeneration += 1;
-  animLock.reset();
-}
-
-function scheduleCombatPump(fn: () => void, ms: number): void {
-  const generation = combatPumpGeneration;
-  setTimeout(() => {
-    if (generation !== combatPumpGeneration || degrading) return;
-    fn();
-  }, ms);
-}
-/**
- * Active smoke overlays from Smoke Charge consumables. Each entry records
- * the tile position and original tile type so `clearSmoke` can restore the
- * grid. Cleared at the start of the player's next turn (`onPlayerTurnReady`).
- */
-let activeSmokeOverlays: SmokeOverlay[] = [];
-/** Hazard-glyph blast flash — cleared on a short timer after each detonation. */
-let activeBreachBlastOverlayKeys = new Set<string>();
-let breachBlastOverlayTimer: ReturnType<typeof setTimeout> | null = null;
-
-function clearBreachBlastOverlay(repaint = false): void {
-  if (breachBlastOverlayTimer) {
-    clearTimeout(breachBlastOverlayTimer);
-    breachBlastOverlayTimer = null;
-  }
-  if (activeBreachBlastOverlayKeys.size === 0) return;
-  activeBreachBlastOverlayKeys.clear();
-  if (repaint) paint();
-}
-
-function showBreachBlastOverlay(cx: number, cy: number): void {
-  clearBreachBlastOverlay(false);
-  for (const { x, y } of blastCells(cx, cy)) {
-    activeBreachBlastOverlayKeys.add(`${x},${y}`);
-  }
-  breachBlastOverlayTimer = setTimeout(() => {
-    breachBlastOverlayTimer = null;
-    activeBreachBlastOverlayKeys.clear();
-    paint();
-  }, ANIMATION_DURATIONS.BREACH_BLAST_OVERLAY);
-}
-
-/**
- * Recent intent-result log lines (melee, fire, perk use, denials, etc.).
- * Stored newest-first, then rendered oldest-to-newest so a single interaction
- * burst stays readable: terminal side effects (door unlock, alarm/Rep) remain
- * visible beside the terminal result instead of disappearing into the log.
- */
-let actionLineHistory: string[] = [];
-let pendingActionLineCount = 0;
-let lookCursor: { x: number; y: number } | null = null;
-
-/**
- * Plain-text body after `CORP —` from the last status paint while the queue
- * belonged to CORP. Surfaced again on the player slice until `flash()` runs
- * on the player's turn (new feedback replaces it; avoids snapping the third
- * row back to a stale `lastActionLine` from before the yield).
- */
-let corpToneActivityBody: string | null = null;
-
-/**
- * Rolling game-log buffer (newest first in `logLines`).
- * Tracked at module level because `applyIntent`'s `log` callback fires
- * during intent handling, but the status line is finalised later in
- * `paint()` — without this, the action line gets clobbered by the
- * subsequent statusLine() rewrite.
- */
-let logLines: string[] = [];
-
-const seedFromClock = () => Date.now() & 0xffffffff;
-
 const allComponentsReady = Promise.all([
-  customElements.whenDefined('update-notification'),
   customElements.whenDefined('confirmation-modal'),
-  customElements.whenDefined('finn-shop'),
-  customElements.whenDefined('clinic-modal'),
-  customElements.whenDefined('item-inventory'),
+  customElements.whenDefined('update-notification'),
+  customElements.whenDefined('touch-pad'),
   customElements.whenDefined('contract-select'),
+  customElements.whenDefined('run-briefing'),
+  customElements.whenDefined('crash-dump'),
+  customElements.whenDefined('game-over'),
   customElements.whenDefined('fault-screen'),
-  customElements.whenDefined('touch-pad'),
-  customElements.whenDefined('crew-list'),
-  customElements.whenDefined('crew-roster'),
-  customElements.whenDefined('key-help'),
   customElements.whenDefined('system-start'),
   customElements.whenDefined('curator-briefing'),
   customElements.whenDefined('initial-recruit'),
+  customElements.whenDefined('crew-list'),
+  customElements.whenDefined('crew-roster'),
+  customElements.whenDefined('finn-shop'),
+  customElements.whenDefined('clinic-modal'),
+  customElements.whenDefined('item-inventory'),
+  customElements.whenDefined('key-help'),
 ]);
 
-function mustGetElement<T extends HTMLElement>(id: string): T {
-  const el = document.getElementById(id);
-  if (!el) {
-    throw new Error(`[shell] required element #${id} is missing`);
-  }
-  return el as T;
-}
-
-function mustQuery<T extends Element>(selector: string, root: ParentNode = document): T {
-  const el = root.querySelector(selector);
-  if (!el) {
-    throw new Error(`[shell] required selector "${selector}" is missing`);
-  }
-  return el as T;
-}
-
-function errorMessage(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
-}
-
-function isRun(scene: ShellScene): scene is Run {
-  return 'archetype' in scene;
-}
-
-// ---------------------------------------------------------------------------
-// P3.M3.6 — the active-view seam. While the Decker is jacked in, every
-// presentation/input surface looks *through* these helpers at the cyber
-// layer; in Meatspace (and the Hub) they are identity functions. This is the
-// single place the world/actor/vision/tileset swap happens — shell code
-// below should never reach for `run.world`/`run.player` directly on a
-// surface the player is looking at.
-// ---------------------------------------------------------------------------
-
-function cyberLayerOf(scene: ShellScene | null): CyberspaceLayer | null {
-  if (!scene || !isRun(scene)) return null;
-  return scene.cyberspace?.phase === 'active' ? scene.cyberspace.layer : null;
-}
-
-function isJackedIn(scene: ShellScene | null): boolean {
-  return cyberLayerOf(scene) !== null;
-}
-
-function activeWorldOf(scene: ShellScene): World | null {
-  return cyberLayerOf(scene)?.world ?? scene.world;
-}
-
-function activeActorOf(scene: ShellScene): Entity | null {
-  return cyberLayerOf(scene)?.avatar ?? scene.player;
-}
-
-function activeVisionField(scene: ShellScene | null): VisionField {
-  return isJackedIn(scene) ? cyberVision : vision;
-}
-
-function activeTileset(scene: ShellScene | null): TilesetId {
-  return isJackedIn(scene) ? 'cyber' : 'meat';
-}
-
-// ---------------------------------------------------------------------------
-// Boot
-// ---------------------------------------------------------------------------
-
-async function boot() {
-  canvas = mustGetElement<HTMLCanvasElement>('game-canvas');
-  const gameStage = canvas.closest('.game-stage');
-  if (!(gameStage instanceof HTMLElement)) {
-    throw new Error('[shell] #game-canvas must live inside .game-stage');
-  }
-  stageEl = gameStage;
-  statusEl = mustGetElement<HTMLElement>('game-status');
-  contractSelectEl = mustGetElement<ContractSelectElement>('contract-select');
-  briefingEl = mustGetElement<RunBriefingElement>('briefing');
-  crashEl = mustGetElement<CrashDumpElement>('crash');
-  gameOverEl = mustGetElement<GameOverElement>('game-over');
-  faultEl = mustGetElement<FaultScreenElement>('fault-screen');
-  systemStartEl = mustGetElement<SystemStartElement>('system-start');
-  curatorBriefingEl = mustGetElement<CuratorBriefingElement>('curator-briefing');
-  initialRecruitEl = mustGetElement<InitialRecruitElement>('initial-recruit');
-  confirmationModalEl = mustGetElement<ConfirmationModalElement>('confirm-modal');
-  touchPadEl = mustGetElement<TouchPadElement>('touch-pad');
-  crewRosterEl = mustGetElement<CrewRosterElement>('crew-roster');
-  finnShopEl = mustGetElement<FinnShopElement>('finn-shop');
-  clinicModalEl = mustGetElement<ClinicModalElement>('clinic-modal');
-  itemInventoryEl = mustGetElement<ItemInventoryElement>('item-inventory');
-  keyHelpEl = mustGetElement<KeyHelpElement>('key-help');
-  logEl = mustQuery<HTMLElement>('.game-log');
-  logHeaderEl = mustQuery<HTMLElement>('.game-log h3');
-  logContentEl = mustQuery<HTMLPreElement>('pre', logEl);
-
-  renderer = new AsciiRenderer(canvas);
-  pipCanvas = mustGetElement<HTMLCanvasElement>('pip-canvas');
-  pipRenderer = new AsciiRenderer(pipCanvas, { cellSize: 10, fontSize: 9 });
-  crt = new CrtFilter(canvas);
-
-  keyboard = new KeyboardController({
-    onIntent: (intent: Intent) => {
-      handleIntent(intent);
-      paint();
-    },
-    onModeChange: () => {
-      // Keep the keyboard / touchpad in lock-step so cross-input cancel still holds.
-      handleInputModeChange();
-      paint();
-    },
-    isBlocked: () => animLock.isLocked() || isAnyBlockingModalOpen(),
-  });
-  keyboard.attach();
-
-  // `?` and Esc-for-help live above the keymap: `?` is a UI toggle (not a
-  // game intent), and Esc must reach <key-help> before the keymap turns it
-  // into a `cancel` intent. Capture phase + a return-early when the help
-  // panel is open keeps both behaviours clean.
-  window.addEventListener('keydown', handleGlobalKey, true);
-
-  contractSelectEl.addEventListener('contract-selected', onContractSelected);
-  contractSelectEl.addEventListener('dismiss', () => contractSelectEl.hide());
-  briefingEl.addEventListener('deploy', onBriefingDeploy);
-  briefingEl.addEventListener('dismiss', onBriefingDismiss);
-  crashEl.addEventListener('new-run', onNewRunRequested);
-  gameOverEl.addEventListener('new-run', onNewRunRequested);
-  faultEl.addEventListener('return-to-hub', () => onFaultReturnToHub());
-  systemStartEl.addEventListener('hub-enter', onSystemStartHubEnter);
-  curatorBriefingEl.addEventListener('dismiss', onCuratorBriefingDismiss);
-  initialRecruitEl.addEventListener('recruited', onInitialRecruited);
-
-  crewRosterEl.addEventListener('dismiss', () => crewRosterEl.hide());
-  crewRosterEl.addEventListener('recruit', onCrewRecruit);
-
-  finnShopEl.addEventListener('purchase', onFinnPurchase);
-  finnShopEl.addEventListener('sell-salvage', onFinnSellSalvage);
-  finnShopEl.addEventListener('dismiss', () => finnShopEl.hide());
-
-  clinicModalEl.addEventListener('heal', onClinicHeal);
-  clinicModalEl.addEventListener('dismiss', onClinicDismiss);
-
-  itemInventoryEl.addEventListener('use-item', onUseItem);
-  itemInventoryEl.addEventListener('dismiss', () => itemInventoryEl.hide());
-
-  keyHelpEl.addEventListener('dismiss', () => keyHelpEl.hide());
-
-  const keyHelpToggleEl = document.getElementById('key-help-toggle');
-  if (keyHelpToggleEl) {
-    keyHelpToggleEl.addEventListener('click', () => {
-      if (keyHelpEl.isOpen) {
-        keyHelpEl.hide();
-        return;
-      }
-      tryShowKeyHelpOverlay();
-    });
-  }
-
-  confirmationModalEl.addEventListener('confirm', evt => {
-    const detail = (evt as CustomEvent<{ context?: string }>).detail;
-    switch (detail?.context) {
-      case 'resume-campaign':
-        // not currently implemented
-        break;
-      case 'quit-campaign':
-        performQuitCampaign();
-        break;
-      case 'abort-run':
-        const run = campaign?.activeRun;
-        if (run) {
-          run.confirmAbort();
-          paint();
-        }
-        break;
-      case 'jack-out-early': {
-        const activeRun = campaign?.activeRun;
-        if (activeRun) {
-          activeRun.confirmJackOut();
-          completeJackOutShellSwap();
-        }
-        break;
-      }
-    }
-  });
-
-  touchPadEl.addEventListener('intent', evt => {
-    handleIntent((evt as CustomEvent<Intent>).detail);
-    paint();
-  });
-  touchPadEl.addEventListener('mode-change', () => {
-    handleInputModeChange();
-    paint();
-  });
-  touchPadEl.setBlocked(() => animLock.isLocked() || isAnyBlockingModalOpen());
-
-  logHeaderEl.addEventListener('click', () => {
-    logEl.classList.toggle('collapsed');
-  });
-
-  // Update-notification wiring kept from the original scaffold.
-  const updateNotification = mustQuery<UpdateNotificationElement>('update-notification');
-  window.addEventListener('sw-update-available', event => {
-    const detail = (event as CustomEvent<{ pendingWorker: ServiceWorker | null }>).detail;
-    updateNotification.show(detail.pendingWorker);
-  });
-
-  await dataStore.init();
-  initDevFaultTrigger();
-  installErrorBoundary({ target: window, degrade: degradeToHub });
-  if (dataStore.currentRun) {
-    dataStore.deleteRun(dataStore.currentRun.id);
-  }
-  if (dataStore.currentCampaign) {
-    resumeCampaign(dataStore.currentCampaign);
-  } else {
-    startFreshCampaign();
-  }
-
-  // SW registration is the same posture as the debug scaffold — kicked off last
-  // so it doesn't gate the shell's first paint.
-  serviceWorkerManager.register().catch(err => console.warn('[shell] sw register failed', err));
-}
-
-// ---------------------------------------------------------------------------
-// Run lifecycle
-// ---------------------------------------------------------------------------
-
-function startFreshCampaign() {
-  hideBlockingShellModals();
-  campaign = new Campaign({
-    seed: seedFromClock(),
-    crew: [],
-    onPersist: handlePersist,
-    onResult: handleResult,
-  });
-
-  pendingJobResult = null;
-  setStatus('Booting Meatspace…');
-  systemStartEl.setSession({ seed: campaign.seed });
-  systemStartEl.show();
-}
-
-function onSystemStartHubEnter() {
-  systemStartEl.hide();
-  if (!campaign) return;
-  // Fresh campaign: crew is empty — show initial recruitment overlay.
-  if (campaign.crew.length === 0) {
-    const candidates = campaign.generateInitialCandidates();
-    initialRecruitEl.setCandidates(candidates);
-    initialRecruitEl.show();
-    return;
-  }
-  // Resumed or post-recruitment — go straight to hub.
-  enterHubAndRender();
-}
-
-function onInitialRecruited(evt: Event) {
-  if (!campaign) return;
-  const { memberIds } = (evt as CustomEvent<{ memberIds: string[] }>).detail;
-  campaign.recruitInitial(memberIds);
-  initialRecruitEl.hide();
-  // Now the crew is set — enter the hub for the first time (builds world, persists).
-  campaign.enterHub();
-  enterHubAndRender();
-  const names = campaign.crew.map(m => m.callsign).join(' and ');
-  flash(`CURATOR: ${names} on the board. Find me when you want work.`);
-}
-
-function hideResultOverlays(): void {
-  crashEl?.hide();
-  gameOverEl?.hide();
-}
-
-function hideBlockingShellModals(): void {
-  keyHelpEl?.hide();
-  briefingEl?.hide();
-  hideResultOverlays();
-  contractSelectEl?.hide();
-  systemStartEl?.hide();
-  curatorBriefingEl?.hide();
-  initialRecruitEl?.hide();
-  crewRosterEl?.hide();
-  finnShopEl?.hide();
-  clinicModalEl?.hide();
-  itemInventoryEl?.hide();
-}
-
-function abortShellForFault(): void {
-  hideBlockingShellModals();
-  invalidateCombatPumps();
-  pendingJobResult = null;
-  hubRevealFollowUpFlash = null;
-  pendingHubRevealId = null;
-  corpToneActivityBody = null;
-  clearBreachBlastOverlay(false);
-  resetInputModes();
-  activeSmokeOverlays = [];
-  civilianHarmsThisJob = 0;
-}
-
-function hubSnapshotFromLastGoodSave(saved: CampaignSnapshot): CampaignSnapshot {
-  return {
-    ...saved,
-    state: CAMPAIGN_STATE.HUB,
-    activeRun: null,
-    deployedMemberId: null,
-  };
-}
-
-function degradeToHub(signal: FaultSignal): void {
-  degrading = true;
-  faultHubRestored = false;
-  try {
-    abortShellForFault();
-
-    const saved = dataStore.currentCampaign as CampaignSnapshot | null;
-    if (!saved) {
-      faultEl.show({ code: signal.source });
-      return;
-    }
-
-    resumeCampaign(hubSnapshotFromLastGoodSave(saved));
-    faultHubRestored = true;
-    faultEl.show({ code: signal.source });
-  } catch (err) {
-    try {
-      console.error('[shell] degradeToHub failed:', err);
-    } catch {
-      // ignore
-    }
-    faultEl.show({ code: signal.source });
-  }
-}
-
-function onFaultReturnToHub(): void {
-  faultEl.hide();
-  degrading = false;
-  if (faultHubRestored) {
-    handlePersist();
-    if (campaign?.state === CAMPAIGN_STATE.ENDED) {
-      renderShell();
-      canvas.focus();
-      return;
-    }
-    enterHubAndRender();
-  } else {
-    dataStore.deleteCampaign();
-    startFreshCampaign();
-  }
-  canvas.focus();
-}
-
-/**
- * Attach listeners and render the hub after enterHub() has been called.
- * Shared by both the post-initial-recruitment path and the normal
- * system-start path (when crew already exists).
- */
-/**
- * Show a full-screen Curator briefing for a pending Hub reveal, if any.
- * Defers `followUpFlash` to the status line until the player dismisses the modal.
- */
-function presentHubRevealIfAny(followUpFlash: string): boolean {
-  if (!campaign?.lastHubReveal) return false;
-  const reveal = campaign.lastHubReveal;
-  campaign.lastHubReveal = null;
-  hubRevealFollowUpFlash = followUpFlash;
-  pendingHubRevealId = hubRevealCommitsOnDismiss(reveal.id) ? reveal.id : null;
-  curatorBriefingEl.setBriefing({ title: reveal.title, lines: reveal.lines });
-  curatorBriefingEl.show();
-  return true;
-}
-
-function onCuratorBriefingDismiss(): void {
-  curatorBriefingEl.hide();
-  if (pendingHubRevealId && campaign) {
-    commitHubReveal(campaign, pendingHubRevealId);
-    pendingHubRevealId = null;
-    handlePersist();
-  }
-  if (hubRevealFollowUpFlash) {
-    flash(hubRevealFollowUpFlash);
-    hubRevealFollowUpFlash = null;
-  }
-}
-
-function enterHubAndRender() {
-  if (!campaign?.curator) {
-    throw new Error('enterHubAndRender: hub not entered — curator is missing.');
-  }
-  attachVisionListener();
-  attachAnimationListeners();
-  attachRepListeners();
-  attachCyberListeners();
-  recomputeVision();
-  renderShell();
-  if (!presentHubRevealIfAny('HUB — Curator has contracts when you are adjacent [Space].')) {
-    flash('HUB — Curator has contracts when you are adjacent [Space].');
-  }
-  // generate job options once on hub enter
-  currentJobOptions = generateCurrentJobOptions();
-}
-
-function presentCrewRoster() {
-  if (!campaign) return;
-  campaign.backfillRecruitsIfEligible();
-  crewRosterEl.setCrew(campaign.crew, {
-    salvage: campaign.salvage,
-    campaignStatus: formatHubArcStatusLines(campaign).filter(
-      (line): line is string => line !== null
-    ),
-    availableRecruits: campaign.availableRecruits,
-    recruitedThisVisit: campaign.recruitedThisVisit,
-  });
-  crewRosterEl.show();
-}
-
-function onCrewRecruit(evt: Event) {
-  if (!campaign) return;
-  const { recruitId } = (evt as CustomEvent<{ recruitId: string }>).detail;
-  try {
-    campaign.recruit(recruitId);
-    const member = campaign.getCrewMember(recruitId);
-    flash(`NEW OPERATIVE: ${member?.callsign ?? recruitId} joins the collective.`);
-    // A replacement Decker can unlock THE SCORE immediately. Preserve the
-    // existing three-card board and append only the newly legal finale.
-    if (
-      campaign.canAttemptScore() &&
-      !currentJobOptions.some(contract => contract.context.recipeId === 'score-final')
-    ) {
-      currentJobOptions.push(campaign.buildScoreContract());
-    }
-    // Refresh the roster to reflect the new crew + hide recruit section.
-    presentCrewRoster();
-  } catch (err) {
-    flash(`RECRUITMENT FAILED: ${(err as Error).message}`);
-  }
-}
-
-function presentBriefing(contract: Contract) {
-  if (!campaign) return;
-  briefingEl.setContract(contract);
-  briefingEl.setCrew(campaign.crew);
-  briefingEl.show();
-}
-
-function presentContractSelect(contracts: Contract[]) {
-  contractSelectEl.setScoreTargetSiteId(campaign ? scoreTargetSiteId(campaign) : null);
-  contractSelectEl.setScorePrincipalId(campaign ? scorePrincipalId(campaign) : null);
-  contractSelectEl.setContracts(contracts);
-  contractSelectEl.show();
-}
-
-function generateCurrentJobOptions(): Contract[] {
-  if (!campaign?.curator) {
-    throw new Error('generateCurrentJobOptions: hub not entered — curator is missing.');
-  }
-  const contracts = campaign.curator.generateContracts(campaign.rng, campaign);
-  if (campaign.canAttemptScore()) {
-    contracts.push(campaign.buildScoreContract());
-  }
-  return contracts;
-}
-
-function onContractSelected(evt: Event) {
-  const { contract } = (evt as CustomEvent<{ contract?: Contract }>).detail;
-  if (!contract) return;
-  contractSelectEl.hide();
-  flash(`CURATOR: ${contract.label} — choose an operative.`);
-  presentBriefing(contract);
-}
-
-function onBriefingDismiss() {
-  briefingEl.hide();
-  // Hub briefing (no activeRun yet): dismiss returns to the canvas.
-  // Resumed mid-briefing (activeRun in BRIEFING): deployment already
-  // committed — re-present the modal instead of leaving a blank screen.
-  if (campaign?.activeRun?.state === RUN_STATE.BRIEFING) {
-    renderShell();
-  }
-}
-
-function onBriefingDeploy(evt: Event) {
-  if (!campaign) return;
-  const { memberId, contract } = (evt as CustomEvent<{ memberId?: string; contract?: Contract }>)
-    .detail;
-  if (!memberId || !contract) return;
-  const member = campaign.getCrewMember(memberId);
-  if (!member || member.flatlined) return;
-  briefingEl.hide();
-
-  let run = campaign.activeRun;
-  if (run?.state === RUN_STATE.BRIEFING) {
-    // Resumed save: deployCrewMember already ran before the reload.
-    if (run.crewMember.id !== member.id) {
-      flash(
-        `DEPLOY LOCKED: ${run.crewMember.callsign ?? run.crewMember.id} is slotted for this contract.`
-      );
-      briefingEl.show();
-      return;
-    }
-  } else {
-    run = campaign.deployCrewMember(member.id, contract);
-    flash(`CURATOR: ${member.callsign} takes ${contract.label}. JACKING IN.`);
-  }
-
-  // Wire the run's confirmation callbacks (abort extraction, early jack-out).
-  wireRunConfirmations(run);
-
-  // Go straight into combat — the player already reviewed the contract and
-  // chose their operative in the combined briefing modal.
-  if (!run || run.state !== RUN_STATE.BRIEFING) {
-    throw new Error(`[shell] expected deployed run to enter BRIEFING, got ${run?.state}`);
-  }
-  run.enterCombat();
-  handlePersist();
-  vision.resetFogState();
-  if (run.priorSeenKeys.length > 0) {
-    vision.restoreSeen(run.priorSeenKeys);
-  }
-  attachVisionListener();
-  attachAnimationListeners();
-  attachRepListeners();
-  attachCyberListeners();
-  recomputeVision();
-  flash('JACKED IN. Reach the exit tile (¤) before the corpos drop you.');
-  renderShell();
-}
-
-function presentFinnShop() {
-  if (!campaign || !campaign.finn) return;
-  const catalog = campaign.finn.catalog(campaign.rep);
-  finnShopEl.setCatalog(catalog, campaign.crew, {
-    credits: campaign.credits,
-    salvage: campaign.salvage,
-  });
-  finnShopEl.show();
-}
-
-function presentClinic() {
-  if (!campaign || !campaign.clinic) return;
-  clinicModalEl.setPatients(campaign.crew, {
-    credits: campaign.credits,
-    healedMemberIds: [...campaign.healedThisVisit],
-  });
-  clinicModalEl.show();
-}
-
-function onClinicHeal(evt: Event) {
-  if (!campaign) return;
-  const { memberId } = (evt as CustomEvent<{ memberId?: string }>).detail;
-  if (!memberId) return;
-  const member = campaign.getCrewMember(memberId);
-  try {
-    campaign.healMember(memberId);
-  } catch (err) {
-    flash(`HEAL FAILED: ${errorMessage(err)}`);
-    return;
-  }
-  const label = member?.callsign ?? memberId;
-  flash(`PATCH: ${label} patched up. CREDS ${campaign.credits}.`);
-  presentClinic();
-}
-
-function onClinicDismiss() {
-  clinicModalEl.hide();
-}
-
-function onFinnPurchase(evt: Event) {
-  if (!campaign) return;
-  const { itemId, targetMemberId } = (
-    evt as CustomEvent<{
-      itemId?: string;
-      targetMemberId?: string;
-    }>
-  ).detail;
-  try {
-    campaign.purchase({ itemId, targetMemberId });
-  } catch (err) {
-    flash(`PURCHASE FAILED: ${errorMessage(err)}`);
-    return;
-  }
-  flash(`FINN: Purchased ${itemId}. CREDS ${campaign.credits}.`);
-  // Refresh the shop to reflect new balance and purchased meta upgrades.
-  presentFinnShop();
-}
-
-function onFinnSellSalvage(evt: Event) {
-  if (!campaign) return;
-  const { quantity, type } = (evt as CustomEvent<{ quantity?: number; type?: string }>).detail;
-  try {
-    if (quantity === undefined) {
-      throw new TypeError('sell-salvage quantity is required');
-    }
-    const creditsBefore = campaign.credits;
-    campaign.sellSalvage(quantity, type as import('/src/game/salvage.js').SalvageType | undefined);
-    const earned = campaign.credits - creditsBefore;
-    flash(`FINN: Bought ${quantity} salvage for ${earned} Cr.`);
-  } catch (err) {
-    flash(`SALE FAILED: ${errorMessage(err)}`);
-    return;
-  }
-  presentFinnShop();
-}
-
-function presentItemInventory() {
-  if (!campaign) return;
-  // Inventory is now available in both Hub and combat. The two states
-  // surface different wallets:
-  //   - Combat: the deployed crew member's job-scoped inventory (what they've
-  //     picked up this run + their consumables).
-  //   - Hub:    the campaign-wide accumulated salvage. No active crew member,
-  //     so no consumables list — the player visits the shop or roster for
-  //     per-crew loadout management.
-  // This keeps the overlay's mental model simple: it always shows the
-  // currently meaningful wallet for the state the player is standing in.
-  if (campaign.state === CAMPAIGN_STATE.HUB) {
-    itemInventoryEl.setContents({
-      salvage: campaign.salvage,
-      consumables: [],
-      keyItems: campaign.keyItems,
-    });
-    itemInventoryEl.show();
-    return;
-  }
-  const run = campaign.activeRun;
-  if (!run || !run.player || !run.player.inventory) return;
-  itemInventoryEl.setContents({
-    salvage: run.player.inventory.salvage,
-    consumables: run.player.inventory.consumables,
-    keyItems: [...campaign.keyItems, ...run.keyItems],
-  });
-  itemInventoryEl.show();
-}
-
-/**
- * Stashed item id for thrown-consumable aim flow. Set when the
- * inventory overlay confirmed an aimed consumable (incendiary) and we
- * flipped the input controllers into `MODE.AIM` with `aimKind: 'use-item'`;
- * consumed when the subsequent `use-item { dx, dy }` intent arrives or cleared
- * on cancel.
- *
- * Kept at module scope (not inside `onUseItem`) because the aim resolution
- * happens in a separate event tick from the inventory click — the keypress
- * routes through KeyboardController → applyIntent → ctx.onUseItem.
- */
-let pendingAimItemId: string | null = null;
-
-function onUseItem(evt: Event) {
-  if (!campaign) return;
-  const run = campaign.activeRun;
-  if (!run || !run.player) return;
-  if (!run.world) throw new Error('[shell] active combat run has no world');
-  const { itemId } = (evt as CustomEvent<{ itemId?: string }>).detail;
-  if (!itemId) return;
-  // Aimed consumables (incendiary): close the inventory overlay, switch the
-  // input controllers into unified aim mode, and wait for the next direction.
-  // Crew.useConsumable will be called from `resolveAimedUseItem` once the
-  // aim direction is in.
-  let descriptor: Item;
-  try {
-    descriptor = getItemById(itemId) as Item;
-  } catch (err) {
-    flash(`USE FAILED: ${errorMessage(err)}`);
-    return;
-  }
-  if (descriptor.needsAim) {
-    if (!run.player.canAfford(AP_COST.INTERACT)) {
-      // Cheap pre-check: don't strand the player in aim mode if `useConsumable`
-      // will reject the commit anyway. Crew's `canAfford(AP_COST.INTERACT)`
-      // remains the source of truth at commit time.
-      flash('USE FAILED: insufficient AP.');
-      return;
-    }
-    pendingAimItemId = itemId;
-    itemInventoryEl.hide();
-    setInputAim(AIM_KIND.USE_ITEM);
-    flash(`AIM ${descriptor.label.toUpperCase()} — pick a direction (Esc to cancel).`);
-    return;
-  }
-  try {
-    const result = run.player.useConsumable(itemId);
-    applyUseConsumableResult(result, run);
-  } catch (err) {
-    flash(`USE FAILED: ${errorMessage(err)}`);
-    return;
-  }
-  itemInventoryEl.hide();
-  paint();
-  if (run.player.ap === 0) {
-    advanceTurn();
-  }
-}
-
-/**
- * Common world-side effects for a `useConsumable` result. Split out so the
- * direct (non-aim) inventory flow and the aimed-throw flow share one place
- * to translate Crew's pure descriptors into grid mutations.
- */
-function applyUseConsumableResult(
-  result: ReturnType<NonNullable<Run['player']>['useConsumable']>,
-  run: Run
-): void {
-  if (!run.world || !run.player) throw new Error('[shell] applyUseConsumableResult: no scene');
-  if (result.type === 'stim') {
-    const healed = (result as { healed: number }).healed;
-    flash(
-      `Used STIM — healed ${healed} HP (now ${run.player.hp}/${run.player.maxHp}). ${run.player.ap} AP left.`
-    );
-    return;
-  }
-  if (result.type === 'smoke') {
-    const { cx, cy, radius } = result as { cx: number; cy: number; radius: number };
-    if (!Number.isInteger(cx) || !Number.isInteger(cy) || !Number.isInteger(radius)) {
-      throw new Error('[shell] smoke consumable returned invalid placement data');
-    }
-    const overlays = placeSmoke(run.world.grid, cx, cy, radius);
-    activeSmokeOverlays.push(...overlays);
-    recomputeVision();
-    flash(`Used SMOKE CHARGE — LOS blocked in radius ${radius}. ${run.player.ap} AP left.`);
-    return;
-  }
-  if (result.type === 'incendiary') {
-    const { cx, cy } = result as { cx: number; cy: number };
-    if (!Number.isInteger(cx) || !Number.isInteger(cy)) {
-      throw new Error('[shell] incendiary consumable returned invalid placement data');
-    }
-    // `placeHazardCluster` only stamps onto FLOOR tiles inside bounds — if
-    // the target is on/past the map edge or buried in a wall, the cluster
-    // simply finds zero candidates and stamps nothing. We've already paid
-    // AP and consumed the charge in Crew.useConsumable; the LOS pre-check
-    // in `resolveAimedUseItem` is what protects the player from "throw
-    // through a wall and lose your bomb."
-    const stamped = placeHazardCluster(run.world, { x: cx, y: cy }, run.rng);
-    if (stamped === 0) {
-      flash(`Used INCENDIARY — bomb landed on hard cover; no fire took. ${run.player.ap} AP left.`);
-    } else {
-      flash(
-        `Used INCENDIARY — ${stamped} tile${stamped === 1 ? '' : 's'} ignited. ${run.player.ap} AP left.`
-      );
-    }
-    recomputeVision();
-    return;
-  }
-  if (result.type === 'breach') {
-    const { tx, ty } = result as { tx: number; ty: number };
-    if (!Number.isInteger(tx) || !Number.isInteger(ty)) {
-      throw new Error('[shell] breaching charge returned invalid target data');
-    }
-    run.world.placeBreachingCharge(tx, ty);
-    flash(`BREACHING CHARGE planted. Detonates end of turn. ${run.player.ap} AP left.`);
-    recomputeVision();
-    return;
-  }
-  throw new Error(`[shell] applyUseConsumableResult: unknown result.type "${result.type}"`);
-}
-
-/**
- * Resolve an aimed `use-item { dx, dy }` intent. Pairs the keymap's direction
- * pick with the shell's stashed `pendingAimItemId` and runs the LOS-clear
- * pre-check before mutating state. Called from `applyIntent`'s onUseItem
- * callback.
- */
-function resolveAimedUseItem(aim: { dx: number; dy: number }, run: Run): void {
-  if (!run.world || !run.player) throw new Error('[shell] resolveAimedUseItem: no scene');
-  // P3.M3.6: items are meat gear; the inventory gate blocks new aims while
-  // jacked in, but an aim pending across the jack-in interact must also die.
-  if (isJackedIn(run)) {
-    pendingAimItemId = null;
-    flash('USE FAILED: jacked in — your gear is back in Meatspace.');
-    resetInputModes();
-    return;
-  }
-  const itemId = pendingAimItemId;
-  if (!itemId) {
-    // Direction press arrived without a stashed item — shouldn't be reachable
-    // (the keymap only emits use-item from MODE.AIM / use-item aimKind, which
-    // only the shell can enter), but crash loud if it does so the wiring bug
-    throw new Error('[shell] use-item intent received without pendingAimItemId');
-  }
-  pendingAimItemId = null;
-  if (itemId === ITEM_ID.INCENDIARY) {
-    // LOS-clear-target pre-check: the throw lands at
-    // `player + dir * INCENDIARY_THROW_DIST`. If LOS from the thrower to
-    // that tile is blocked (or the tile is out of bounds), refuse the
-    // throw *before* spending AP / consuming the bomb.
-    const cx = run.player.x + aim.dx * INCENDIARY_THROW_DIST;
-    const cy = run.player.y + aim.dy * INCENDIARY_THROW_DIST;
-    if (!run.world.grid.inBounds(cx, cy)) {
-      flash('USE FAILED: target is off the map.');
-      paint();
-      return;
-    }
-    const blockers = run.world.blockerKeys();
-    if (!hasLineOfSight(run.world.grid, run.player.x, run.player.y, cx, cy, { blockers })) {
-      flash('USE FAILED: target is behind cover.');
-      paint();
-      return;
-    }
-  }
-  if (itemId === ITEM_ID.BREACHING_CHARGE) {
-    const tx = run.player.x + aim.dx * BREACHING_CHARGE_RANGE;
-    const ty = run.player.y + aim.dy * BREACHING_CHARGE_RANGE;
-    const plantCheck = run.world.canPlaceBreachingCharge(tx, ty);
-    if (!plantCheck.ok) {
-      const msg =
-        plantCheck.reason === 'blocked'
-          ? 'USE FAILED: need clear ground to plant.'
-          : plantCheck.reason === 'occupied' || plantCheck.reason === 'charge-present'
-            ? 'USE FAILED: that tile is blocked.'
-            : 'USE FAILED: target is off the map.';
-      flash(msg);
-      paint();
-      return;
-    }
-  }
-  try {
-    const result = run.player.useConsumable(itemId, aim);
-    applyUseConsumableResult(result, run);
-  } catch (err) {
-    flash(`USE FAILED: ${errorMessage(err)}`);
-    paint();
-    return;
-  }
-  paint();
-  if (run.player.ap === 0) {
-    advanceTurn();
-  }
-}
-
-function handlePersist() {
-  if (!campaign || degrading) return;
-  dataStore.setCampaign(snapshotCampaign(campaign));
-}
-
-function presentEndedCampaignOverlay(c: Campaign): void {
-  const summary = dataStore.archiveCampaign(buildCampaignSummary(c, new Date().toISOString()));
-  gameOverEl.setSummary(summary);
-}
-
-function presentCampaignEnd(c: Campaign): void {
-  presentEndedCampaignOverlay(c);
-  renderShell();
-}
-
-function finishEndedCampaign(): void {
-  dataStore.deleteCampaign();
-  startFreshCampaign();
-}
-
-/**
- * Stage one result for settlement. Non-terminal jobs show `<crash-dump>`;
- * terminal outcomes are settled immediately by `handleResult` and route to
- * the Chronicle-backed `<game-over>` screen.
- */
-function pushPendingJobResultOverlay(telemetry: Partial<RunTelemetry> & { outcome?: unknown }) {
-  const tel = { ...telemetry };
-  const outcome = tel.outcome;
-  if (outcome !== 'death' && outcome !== 'exit') {
-    throw new Error(`[shell] invalid job outcome for debrief overlay: "${outcome}"`);
-  }
-  pendingJobResult = {
-    outcome,
-    telemetry: { ...tel, outcome } as RunTelemetry & { outcome: Outcome },
-  };
-  crashEl.setTelemetry({
-    ...tel,
-    outcome,
-    cause: tel.cause ?? undefined,
-  });
-}
-
-function pendingResultEndsCampaign(result: PendingJobResult): boolean {
-  if (!campaign) return false;
-  return willEndCampaignAfterResult(
-    campaign,
-    result.outcome,
-    result.outcome === 'exit' && result.telemetry.objectiveComplete !== false
-  );
-}
-
-function handleResult({ outcome, telemetry }: RunResult) {
-  if (degrading) return;
-  pushPendingJobResultOverlay({
-    ...telemetry,
-    outcome: telemetry?.outcome ?? outcome,
-  });
-  if (pendingJobResult && pendingResultEndsCampaign(pendingJobResult)) {
-    settlePendingJobResult();
-    return;
-  }
-  renderShell();
-}
-
-function currentScene(): ShellScene | null {
-  if (!campaign) return null;
-  return campaign.activeRun ?? campaign;
-}
-
-/**
- * Wire the confirmation callbacks a Run raises mid-combat. Callbacks do not
- * persist, so this runs at deploy AND on campaign resume — a restored run
- * without them would silently skip both confirmations (the no-callback
- * harness fallback).
- */
-function wireRunConfirmations(run: Run): void {
-  // Stepping on exit with an incomplete objective pops a modal instead of
-  // silently ending the run.
-  run.onAbortRequested = () => {
-    confirmationModalEl.showModal(
-      `Objective incomplete. Abort extraction?\n\nYou will lose all rewards and take a REP ${REP.ABORT_PENALTY} penalty.`,
-      'abort-run'
-    );
-  };
-  // P3.M3 S7.5: routing out of the grid with the objective incomplete is
-  // irreversible (LINK BURNED, objective unsatisfiable) — confirm first.
-  run.onJackOutRequested = () => {
-    confirmationModalEl.showModal(
-      'Objective incomplete. Jack out anyway?\n\nThe link will burn — you cannot re-enter the grid this run.',
-      'jack-out-early'
-    );
-  };
-}
-
-function resumeCampaign(record: CampaignSnapshot | unknown) {
-  try {
-    campaign = restoreCampaign(record, {
-      onPersist: () => handlePersist(),
-      onResult: handleResult,
-    });
-    if (campaign.activeRun) {
-      wireRunConfirmations(campaign.activeRun);
-    }
-    if (campaign.activeRun?.state === RUN_STATE.COMBAT) {
-      vision.resetFogState();
-      vision.restoreSeen(campaign.activeRun.mapSeenKeys());
-    }
-    attachVisionListener();
-    attachAnimationListeners();
-    attachRepListeners();
-    attachCyberListeners();
-    recomputeVision();
-    if (campaign.activeRun?.state === RUN_STATE.BRIEFING && campaign.activeRun.contract) {
-      briefingEl.setContract(campaign.activeRun.contract);
-      briefingEl.setCrew(campaign.crew);
-    }
-    resumePendingCombatSliceIfNeeded();
-    const resumeFlashMessage = `RESUMED — crew ${campaign.crew.filter(member => !member.flatlined).length} active.`;
-    if (campaign.state === CAMPAIGN_STATE.ENDED) {
-      pendingJobResult = null;
-      presentEndedCampaignOverlay(campaign);
-      flash(
-        campaign.endReason === 'clock-expired'
-          ? 'WINDOW CLOSED — Score contract went cold.'
-          : campaign.endReason === 'score-complete'
-            ? 'SCORE COMPLETE — campaign archived.'
-            : 'CAMPAIGN ENDED — this save has reached a terminal state.'
-      );
-      renderShell();
-    } else if (campaign.activeRun?.state === RUN_STATE.RESULT) {
-      pushPendingJobResultOverlay({ ...campaign.activeRun.telemetry });
-      if (pendingJobResult && pendingResultEndsCampaign(pendingJobResult)) {
-        settlePendingJobResult();
-      } else {
-        flash('RESUMED — mission debrief.');
-        renderShell();
-      }
-    } else if (campaign.state === CAMPAIGN_STATE.HUB && campaign.curator) {
-      renderShell();
-      if (!presentHubRevealIfAny(resumeFlashMessage)) {
-        flash(resumeFlashMessage);
-      }
-      currentJobOptions = generateCurrentJobOptions();
-    } else {
-      flash(resumeFlashMessage);
-      renderShell();
-    }
-  } catch (err) {
-    console.error('[shell] failed to restore saved campaign', err);
-    dataStore.deleteCampaign();
-    flash('CAMPAIGN SAVE CORRUPT — starting fresh.');
-    startFreshCampaign();
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Intent handling
-// ---------------------------------------------------------------------------
-
-function isConfirmationDialogOpen(el: HTMLElement | null | undefined): boolean {
-  const dialog = el?.shadowRoot?.querySelector('dialog');
-  return Boolean(dialog?.open);
-}
-
-function presentQuitCampaignConfirm() {
-  if (!campaign) return;
-  if (isConfirmationDialogOpen(confirmationModalEl)) return;
-  confirmationModalEl.showModal(
-    'Delete this campaign and all progress? This cannot be undone.',
-    'quit-campaign'
-  );
-}
-
-function performQuitCampaign(): void {
-  if (!campaign) return;
-  keyHelpEl.hide();
-  briefingEl.hide();
-  hideResultOverlays();
-  crewRosterEl.hide();
-  finnShopEl.hide();
-  clinicModalEl.hide();
-  itemInventoryEl.hide();
-
-  pendingJobResult = null;
-  dataStore.deleteCampaign();
-  startFreshCampaign();
-  flash('Campaign deleted — new campaign.');
-  canvas.focus();
-}
-
-function handleInputModeChange(): void {
-  const state = activeInputState();
-  if (state.mode !== MODE.LOOK) return;
-  if (isCorpControlsLocked()) {
-    resetInputModes();
-    flash('HOSTILES ACTIVE — controls locked until security finishes.');
-    return;
-  }
-  enterLookMode();
-}
-
-function enterLookMode(): void {
-  const run = currentScene();
-  if (!run?.world || !run.player) return;
-  if (lookCursor) return;
-  const actor = activeActorOf(run);
-  if (!actor) return;
-  lookCursor = { x: actor.x, y: actor.y };
-  keyboard.mode = MODE.LOOK;
-  keyboard.aimKind = null;
-  if (touchPadEl.mode !== MODE.LOOK) touchPadEl.setMode(MODE.LOOK);
-  flash('LOOK — move cursor (Esc to cancel).');
-}
-
-function exitLookMode(): void {
-  lookCursor = null;
-  resetInputModes();
-}
-
-function isCorpControlsLocked(): boolean {
-  const run = currentScene();
-  return run?.state === RUN_STATE.COMBAT && run.queue?.currentFaction !== FACTION.PLAYER;
-}
-
-function handleLookMove(dx = 0, dy = 0): void {
-  if (isCorpControlsLocked()) {
-    flash('HOSTILES ACTIVE — controls locked until security finishes.');
-    return;
-  }
-  const run = currentScene();
-  if (!run?.world || !run.player) return;
-  // P3.M3.6: the look cursor roams whichever grid is on screen.
-  const world = activeWorldOf(run);
-  const actor = activeActorOf(run);
-  if (!world || !actor) return;
-  const fog = activeVisionField(run);
-  if (!lookCursor) {
-    lookCursor = { x: actor.x, y: actor.y };
-  }
-  const tx = Math.max(0, Math.min(world.grid.width - 1, lookCursor.x + dx));
-  const ty = Math.max(0, Math.min(world.grid.height - 1, lookCursor.y + dy));
-  if (run.state === RUN_STATE.COMBAT && !fog.hasSeen(tx, ty)) {
-    flash("You haven't seen that tile.");
-    return;
-  }
-  lookCursor = { x: tx, y: ty };
-  const line = describeTileAt(world, tx, ty, {
-    vision: run.state === RUN_STATE.COMBAT ? fog : undefined,
-    showStats: true,
-  });
-  if (line) flash(line);
-}
-
-function handleIntent(intent: Intent): void {
-  if (intent?.type === 'quit-campaign') {
-    resetInputModes();
-    if (!campaign) return;
-    presentQuitCampaignConfirm();
-    return;
-  }
-
-  if (intent?.type === 'look-move') {
-    handleLookMove(intent.dx, intent.dy);
-    return;
-  }
-
-  if (intent?.type === 'cancel' && lookCursor) {
-    exitLookMode();
-    return;
-  }
-
-  const run = currentScene();
-  if (!run) return;
-  // BRIEFING / RESULT swallow gameplay intents — JACK IN / NEW RUN drive
-  // those transitions through the DOM buttons. Cancel is still valid (it
-  // clears any stuck aim mode, per the cross-input cancel rule).
-  if (
-    run.state === RUN_STATE.BRIEFING ||
-    run.state === RUN_STATE.RESULT ||
-    run.state === CAMPAIGN_STATE.ENDED
-  ) {
-    if (intent?.type === 'cancel') {
-      resetInputModes();
-    }
-    return;
-  }
-
-  if (!run.world || !run.player || !run.queue) {
-    throw new Error(`[shell] state "${run.state}" is missing playable scene wiring`);
-  }
-
-  // P3.M3.6: intents drive whoever the player is being — the crew body in
-  // Meatspace, the avatar on the grid (same queue either way).
-  const intentWorld = activeWorldOf(run);
-  const intentActor = activeActorOf(run);
-  if (!intentWorld || !intentActor) {
-    throw new Error(`[shell] state "${run.state}" has no active world/actor for intents`);
-  }
-
-  applyIntent(intent, {
-    world: intentWorld,
-    player: intentActor as Parameters<typeof applyIntent>[1]['player'],
-    queue: run.queue,
-    rng: run.rng,
-    // Capture the action line for the next paint(); see lastActionLine docs.
-    log: (line: string) => flash(line),
-    advanceTurn,
-    resetInputModes,
-    onUseItem: (aim: { dx: number; dy: number }) => {
-      resolveAimedUseItem(aim, run as Run);
-    },
-    onCorpseSalvaged: entity => {
-      activeVisionField(run).forgetCorpse(entity);
-    },
-    keyItems: [...(campaign?.keyItems ?? []), ...(run as Run).keyItems],
-    onKeycardCollected: kc => {
-      if (kc.siteId) {
-        // Campaign-scoped: persists across runs.
-        if (campaign?.keyItems.some(k => k.id === kc.id)) {
-          return;
-        }
-        campaign?.addKeyItem({ id: kc.id, label: kc.label, doorId: kc.doorId, siteId: kc.siteId });
-      } else {
-        // Run-scoped: lives only in this run, discarded on run end.
-        (run as Run).addKeyItem({ id: kc.id, label: kc.label, doorId: kc.doorId });
-      }
-    },
-    onSecuredInteract: handleSecuredInteract,
-    onPlayerAction: (actionName: string) => {
-      switch (actionName) {
-        case PLAYER_ACTIONS.INVENTORY:
-          // Inventory opens in Hub *and* combat. In combat we still
-          // restrict to the player's turn so peeking doesn't dodge corp
-          // tempo; in Hub there's no turn queue gating to worry about.
-          if (campaign?.state === CAMPAIGN_STATE.COMBAT) {
-            if (run.state !== RUN_STATE.COMBAT || run.queue?.currentFaction !== FACTION.PLAYER) {
-              flash('Inventory is only available on your turn.');
-              return;
-            }
-            // P3.M3.6: the avatar has no pockets — gear stays with the body
-            // until the P3.M4 simstim flip makes split control real.
-            if (isJackedIn(run)) {
-              flash('Jacked in — your meatspace gear is out of reach.');
-              return;
-            }
-          }
-          presentItemInventory();
-          break;
-        case PLAYER_ACTIONS.INTERACT:
-          handleInteract();
-          break;
-        case PLAYER_ACTIONS.REACHED_EXIT:
-          if (campaign?.state === CAMPAIGN_STATE.HUB) {
-            flash('Curator: Hang tight! Come talk to me to claim a contract.');
-          }
-          // Moving onto an extraction tile synchronously emits the run result.
-          // Score settlement may therefore clear the active run and tear down
-          // the campaign world before this callback resumes. Only advance when
-          // the captured scene is still playable (incomplete abort/escort wait,
-          // or the Hub's decorative exit tile).
-          if (run.state === RUN_STATE.COMBAT || run.state === CAMPAIGN_STATE.HUB) {
-            advanceTurn();
-          }
-          break;
-      }
-    },
-  });
-}
-
-/**
- * Pacing between drone actions when the corp turn is animated step-by-step.
- * Tuned just above MUZZLE_FLASH duration so the firing flash decays cleanly
- * before the same drone takes its next action (move, second shot, etc.) —
- * the original user-reported bug where a "fire then move" turn left the flash
- * stranded on the tile the drone had just vacated.
- */
-const CORP_ACTION_DELAY_MS = 130;
-const PLAYER_AFTERMATH_ACTION_DELAY_MS = 130;
-
-function driveCombatTurnPipeline(run: Run, options: { resumeFromCorpSlice?: boolean } = {}): void {
-  if (degrading) return;
-  if (!run.world || !run.queue) {
-    throw new Error(`[shell] cannot advance turn without world/queue in state "${run.state}"`);
-  }
-  const world = run.world;
-  const queue = run.queue;
-  advanceFromPlayerTurn({
-    resumeFromCorpSlice: options.resumeFromCorpSlice,
-    queue,
-    world,
-    rng: run.rng,
-    isTerminal: () => run.state === RUN_STATE.RESULT,
-    drivePlayerAftermath: ({ onStep, onFinish }) => {
-      const finishMeatAftermath = () => {
-        if (degrading) return;
-        clearBreachBlastOverlay(false);
-        const layer = cyberLayerOf(run);
-        if (!layer) {
-          onFinish();
-          return;
-        }
-        drivePlayerAftermath({
-          world: layer.world,
-          rng: run.rng,
-          onStep,
-          onFinish,
-          animLock,
-          stepDelayMs: PLAYER_AFTERMATH_ACTION_DELAY_MS,
-          lockMarginMs: ANIMATION_DURATIONS.MUZZLE_FLASH,
-          player: layer.avatar,
-          schedule: scheduleCombatPump,
-        });
-      };
-      drivePlayerAftermath({
-        world,
-        rng: run.rng,
-        onStep,
-        onFinish: finishMeatAftermath,
-        animLock,
-        stepDelayMs: PLAYER_AFTERMATH_ACTION_DELAY_MS,
-        lockMarginMs: ANIMATION_DURATIONS.MUZZLE_FLASH,
-        rep: campaign?.rep,
-        player: run.player,
-        schedule: scheduleCombatPump,
-      });
-    },
-    onCorpTurnReady: () => {
-      if (degrading) return;
-      clearBreachBlastOverlay(false);
-      recomputeVision();
-      paint();
-    },
-    onPlayerAftermathStep: step => {
-      if (degrading) return;
-      const scene = currentScene();
-      // P3.M3.6: aftermath is a Meatspace phase — while jacked in it still
-      // *applies*, but the canvas is showing the grid, so skip its
-      // presentation (overlays/shake/log lines).
-      const jacked = isJackedIn(scene);
-      const cyberLayer = cyberLayerOf(scene);
-      const isCyberStep =
-        cyberLayer !== null &&
-        step.type === 'overridden-drone' &&
-        cyberLayer.world.entities.has(step.entity.id);
-      if (step.type === 'breach-detonate' && !jacked) {
-        showBreachBlastOverlay(step.charge.x, step.charge.y);
-        if (scene?.player && vision.isVisible(step.charge.x, step.charge.y)) {
-          triggerShake(stageEl);
-          animLock.push(ANIMATION_DURATIONS.SHAKE);
-        }
-      }
-      if (
-        isCyberStep &&
-        cyberLayer &&
-        isPlayerAftermathStepLogVisible(
-          step,
-          (x, y) => cyberVision.isVisible(x, y),
-          cyberLayer.avatar.id
-        )
-      ) {
-        for (const line of formatPlayerAftermathStepLogLines(step)) {
-          flash(line);
-        }
-      } else if (
-        !jacked &&
-        scene?.player &&
-        isPlayerAftermathStepLogVisible(step, (x, y) => vision.isVisible(x, y), scene.player.id)
-      ) {
-        for (const line of formatPlayerAftermathStepLogLines(step)) {
-          flash(line);
-        }
-      }
-      paint();
-    },
-    driveCorpTurn: ({ onFinish }) => {
-      runCorpTurn(() => {
-        if (degrading) return;
-        onFinish();
-      });
-    },
-    onPlayerTurnReady: () => {
-      if (degrading) return;
-      // Clear any smoke from last turn before the player acts.
-      if (activeSmokeOverlays.length > 0) {
-        clearSmoke(world.grid, activeSmokeOverlays);
-        activeSmokeOverlays = [];
-      }
-      // Stealth & vision may both have changed during the corp turn.
-      recomputeVision();
-      paint();
-    },
-  });
-}
-
-function advanceTurn(): void {
-  if (degrading) return;
-  const scene = currentScene();
-  if (!scene) return;
-  if (!scene.world || !scene.queue) {
-    throw new Error(`[shell] cannot advance turn without world/queue in state "${scene.state}"`);
-  }
-
-  if (isRun(scene)) {
-    driveCombatTurnPipeline(scene);
-    return;
-  }
-
-  // Hub — no corp actors; sync PLAYER→CORP→PLAYER flip refreshes operator AP.
-  advanceFromPlayerTurn({
-    queue: scene.queue,
-    world: scene.world,
-    rng: scene.rng,
-    isTerminal: () => false,
-    drivePlayerAftermath: ({ onFinish }) => onFinish(),
-    driveCorpTurn: ({ onFinish }) => onFinish(),
-    onPlayerTurnReady: () => paint(),
-  });
-}
-
-/**
- * Autosave fires at the player→corp `turn:ended` before the animated aftermath
- * and corp slice run. On cold resume (or fault recovery that reloads that
- * checkpoint), kick the pipeline from the corp slice without flipping the
- * queue again.
- */
-function resumePendingCombatSliceIfNeeded(): void {
-  const run = campaign?.activeRun;
-  if (!run || run.state !== RUN_STATE.COMBAT || !run.world || !run.queue) return;
-  if (run.queue.currentFaction === FACTION.PLAYER) return;
-  driveCombatTurnPipeline(run, { resumeFromCorpSlice: true });
-}
-
-/**
- * Kick off the animated corp turn. Delegates to `corpTurnDriver.runCorpTurn`,
- * which iterates each corp entity's `takeTurnSteps` generator one yield at
- * a time, paints between each, and fires `onFinish` once every generator
- * drains (or immediately when the world has zero corp entities — hub, or a
- * combat map the player has cleared). The driver lives in `/src/game/` so
- * its state machine is testable under `node --test`.
- */
-function runCorpTurn(onFinish: () => void): void {
-  if (degrading) return;
-  maybeDevFault('corp');
-  const run = currentScene();
-  if (!run) return;
-  if (!(run instanceof Run)) return;
-  if (!run.world) {
-    throw new Error(`[shell] cannot drive corp turn without world in state "${run.state}"`);
-  }
-  // P3.M3.6: while the Decker is jacked in, the corp slice chains two
-  // driver passes — meat hostiles on the meat world (silent: the canvas is
-  // showing the grid), then ICE on the cyber world. Both consume the shared
-  // run rng in this fixed order, keeping the turn deterministic. If the meat
-  // pass flatlines the body the driver bails terminally and the ICE pass
-  // (correctly) never runs.
-  const icePass = () => {
-    if (degrading) return;
-    const layer = cyberLayerOf(currentScene());
-    if (!layer) {
-      onFinish();
-      return;
-    }
-    driveCorpTurn({
-      run: { state: run.state ?? '', world: layer.world, rng: run.rng },
-      corpFaction: FACTION.CORP,
-      paint,
-      animLock,
-      actionDelayMs: CORP_ACTION_DELAY_MS,
-      lockMarginMs: ANIMATION_DURATIONS.MUZZLE_FLASH,
-      onFinish,
-      schedule: scheduleCombatPump,
-      shouldAnimateStep: (entityId: string, step: TurnActionStep) => {
-        if (degrading) return true;
-        return isCorpTurnStepVisibleToPlayer(layer.world, layer.avatar.id, entityId, step, (x, y) =>
-          cyberVision.isVisible(x, y)
-        );
-      },
-      onStep: (entityId: string, step: TurnActionStep) => {
-        if (degrading) return;
-        const resolve = (id: string) => resolveEntityLabel(id, layer.world.entities);
-        const line = formatCorpTurnStep(resolve(entityId), step, resolve);
-        if (
-          !line ||
-          !isCorpTurnStepLogVisibleToPlayer(layer.world, layer.avatar.id, entityId, step, (x, y) =>
-            cyberVision.isVisible(x, y)
-          )
-        ) {
-          return;
-        }
-        flash(line);
-      },
-    });
-  };
-
-  driveCorpTurn({
-    run: {
-      state: run.state ?? '',
-      world: run.world,
-      rng: run.rng,
-    },
-    corpFaction: run.hostileFaction,
-    paint,
-    animLock,
-    actionDelayMs: CORP_ACTION_DELAY_MS,
-    lockMarginMs: ANIMATION_DURATIONS.MUZZLE_FLASH,
-    onFinish: icePass,
-    schedule: scheduleCombatPump,
-    shouldAnimateStep: (entityId: string, step: TurnActionStep) => {
-      if (degrading) return true;
-      const scene = currentScene();
-      if (!scene?.world || !scene.player) return true;
-      // Jacked in: meat steps still *apply*, but the canvas is showing the
-      // grid — drain them silently rather than pacing invisible frames.
-      if (isJackedIn(scene)) return false;
-      return isCorpTurnStepVisibleToPlayer(scene.world, scene.player.id, entityId, step, (x, y) =>
-        vision.isVisible(x, y)
-      );
-    },
-    onStep: (entityId: string, step: TurnActionStep) => {
-      if (degrading) return;
-      const scene = currentScene();
-      if (!scene?.world || !scene.player) return;
-      if (isJackedIn(scene)) {
-        paintPip();
-        const resolve = (id: string) => resolveEntityLabel(id, scene.world!.entities);
-        const line = formatCorpTurnStep(resolve(entityId), step, resolve);
-        if (
-          line &&
-          isCorpTurnStepLogVisibleToPlayer(scene.world, scene.player.id, entityId, step, (x, y) =>
-            vision.isVisible(x, y)
-          )
-        ) {
-          flash(line);
-        }
-        return;
-      }
-      const resolve = (id: string) => resolveEntityLabel(id, scene.world!.entities);
-      const line = formatCorpTurnStep(resolve(entityId), step, resolve);
-      if (
-        !line ||
-        !isCorpTurnStepLogVisibleToPlayer(scene.world, scene.player.id, entityId, step, (x, y) =>
-          vision.isVisible(x, y)
-        )
-      ) {
-        return;
-      }
-      flash(line);
-    },
-  });
-}
-
-/*
- * `advanceFromPlayerTurn` owns the final CORP→PLAYER queue transition; the
- * shell callback above only refreshes presentation state after that happens.
- */
-
-function handleInteract(): void {
-  if (!campaign) return;
-  // Combat interact: check for adjacent lootable corpses first.
-  if (campaign.state === CAMPAIGN_STATE.COMBAT && campaign.activeRun?.state === RUN_STATE.COMBAT) {
-    handleCombatInteract();
-    return;
-  }
-  if (campaign.state !== CAMPAIGN_STATE.HUB) {
-    flash('Nothing to interact with here.');
-    return;
-  }
-  if (campaign.player && campaign.finn && isChebyshevAdjacent(campaign.player, campaign.finn)) {
-    flash('FINN — browse the shop.');
-    presentFinnShop();
-    return;
-  }
-  if (campaign.player && campaign.clinic && isChebyshevAdjacent(campaign.player, campaign.clinic)) {
-    flash('PATCH — clinic services.');
-    presentClinic();
-    return;
-  }
-  if (
-    campaign.player &&
-    campaign.terminal &&
-    isChebyshevAdjacent(campaign.player, campaign.terminal)
-  ) {
-    if (!isTerminalAccessible(campaign.hubReveals)) {
-      flash('TERMINAL — access denied. Systems locked.');
-      return;
-    }
-    flash('TERMINAL — crew roster.');
-    presentCrewRoster();
-    return;
-  }
-  if (
-    !campaign.player ||
-    !campaign.curator ||
-    !isChebyshevAdjacent(campaign.player, campaign.curator)
-  ) {
-    const hints = ['Curator (contract)'];
-    if (campaign.finn) hints.unshift('Finn (shop)');
-    if (campaign.clinic) hints.push('Patch (clinic)');
-    hints.push('Terminal (roster)');
-    flash(`Step adjacent to ${hints.join(', ')}.`);
-    return;
-  }
-  // Gate: can't take contracts with no deployable crew.
-  if (campaign.crew.filter(m => !m.flatlined).length === 0) {
-    flash('CURATOR: You need a crew first. Try the Terminal.');
-    return;
-  }
-  if (currentJobOptions.length === 0) {
-    currentJobOptions = generateCurrentJobOptions();
-  }
-  flash(
-    currentJobOptions.some(contract => contract.context.recipeId === 'score-final')
-      ? 'CURATOR: Three jobs on the board. The Score is your call.'
-      : 'CURATOR: Three jobs on the board. Pick your trouble.'
-  );
-  presentContractSelect(currentJobOptions);
-}
-
-/**
- * Combat interact — scan Chebyshev-adjacent tiles for a lootable corpse.
- * If found: call `player.collectSalvage`, flash result, auto-end turn on AP
- * exhaustion. If not found: show a no-loot hint.
- */
-function pulseSecuredInteractable(entity: Entity): boolean {
-  if (!(entity instanceof Interactable) || !entity.secured || !entity.alive) return false;
-  const fired = runInteractSecuredFlash(renderer, paint, entity.x, entity.y, entity.glyph);
-  if (fired) animLock.push(ANIMATION_DURATIONS.INTERACT_SECURED_FLASH);
-  return fired;
-}
-
-function handleSecuredInteract(
-  entity: Interactable,
-  { apExhausted }: { apExhausted: boolean }
-): void {
-  const fired = pulseSecuredInteractable(entity);
-  if (!apExhausted) return;
-  if (fired) {
-    scheduleCombatPump(() => advanceTurn(), ANIMATION_DURATIONS.INTERACT_SECURED_FLASH);
-  } else {
-    advanceTurn();
-  }
-}
-
-function handleCombatInteract(): void {
-  if (!campaign) return;
-  const run = campaign.activeRun;
-  if (!run || !run.player) return;
-  if (!run.world) throw new Error('[shell] active combat run has no world');
-  // P3.M3.6: interact targets the world the player is being in — meat props
-  // for the body, data nodes / the exit port for the avatar.
-  const world = activeWorldOf(run);
-  const player = activeActorOf(run);
-  if (!world || !player) throw new Error('[shell] combat interact requires an active world/actor');
-  // Corpse looting needs pockets — the avatar (no inventory) skips straight
-  // to interactables. ICE leaves no salvage in this slice.
-  const inventory = 'inventory' in player ? (player as Crew).inventory : null;
-  if (!isJackedIn(run) && !inventory) {
-    throw new Error('[shell] combat player inventory is not initialised');
-  }
-  if (inventory) {
-    // Scan the 8 neighbours plus the player's own tile for lootable corpses.
-    for (let dy = -1; dy <= 1; dy++) {
-      for (let dx = -1; dx <= 1; dx++) {
-        const tx = player.x + dx;
-        const ty = player.y + dy;
-        const entity = world.lootableCorpseAt(tx, ty);
-        if (entity && !entity.alive && entity.loot && totalSalvage(entity.loot.salvage) > 0) {
-          if (!player.canAfford(AP_COST.INTERACT)) {
-            flash('Insufficient AP to loot.');
-            return;
-          }
-          // Typed salvage — show pickup total + post-pickup compact wallet.
-          const amount = totalSalvage(entity.loot.salvage);
-          (player as Crew).collectSalvage(world, entity);
-          activeVisionField(run).forgetCorpse(entity);
-          flash(
-            `Salvaged +${amount} — carrying ${formatSalvageCompact(inventory.salvage)}. ${player.ap} AP left.`
-          );
-          paint();
-          if (player.ap === 0) {
-            advanceTurn();
-          }
-          return;
-        }
-      }
-    }
-  }
-
-  const interactable = world.adjacentInteractables(player)[0];
-  if (interactable) {
-    const result = interactable.interact(world, player);
-    flash(result.message);
-    if (
-      result.ok &&
-      interactable instanceof Interactable &&
-      interactable.secured &&
-      interactable.alive
-    ) {
-      handleSecuredInteract(interactable, { apExhausted: player.ap === 0 });
-    } else if (result.ok && player.ap === 0) {
-      advanceTurn();
-    }
-    paint();
-    return;
-  }
-
-  flash('Nothing to interact with nearby.');
-}
-
-// onJackIn removed — combat entry is handled in onBriefingDeploy.
-
-function settlePendingJobResult(): 'ended' | 'hub' {
-  if (!campaign || !pendingJobResult) {
-    throw new Error('settlePendingJobResult requires an active campaign result');
-  }
-  const jobResult = pendingJobResult;
-  const { outcome } = jobResult;
-  pendingJobResult = null;
-  // Extract typed salvage from the deployed crew member's inventory on exit.
-  // Death outcomes pass `undefined`, preserving the existing forfeiture rule.
-  const member = campaign.deployedMemberId
-    ? campaign.getCrewMember(campaign.deployedMemberId)
-    : null;
-  const salvage = member?.inventory?.salvage;
-  const objectiveComplete =
-    outcome === 'exit' ? jobResult.telemetry.objectiveComplete !== false : false;
-  // Apply the clean completion bonus before `onJobEnd`, so the terminal
-  // Chronicle record sees the final Rep value and Hub recruitment gates retain
-  // their existing ordering on non-terminal jobs.
-  if (outcome === 'exit' && objectiveComplete && civilianHarmsThisJob === 0) {
-    const actual = campaign.adjustRep(REP.CLEAN_COMPLETION_BONUS);
-    flash(`REP +${actual}: clean extraction — no civilian casualties.`);
-  }
-  if (outcome === 'exit' && !objectiveComplete) {
-    flash(`ABORT: Objective abandoned. REP ${REP.ABORT_PENALTY}.`);
-  }
-  campaign.onJobEnd({ outcome, salvage, completed: objectiveComplete });
-  if (campaign.state === CAMPAIGN_STATE.ENDED) {
-    presentCampaignEnd(campaign);
-    return 'ended';
-  }
-  if (!presentHubRevealIfAny('HUB — choose the next job.')) {
-    flash('HUB — choose the next job.');
-  }
-  if (!campaign.curator) {
-    throw new Error('settlePendingJobResult: hub not entered — curator is missing.');
-  }
-  currentJobOptions = generateCurrentJobOptions();
-  return 'hub';
-}
-
-function onNewRunRequested(): void {
-  if (!campaign) return;
-  if (pendingJobResult) {
-    if (settlePendingJobResult() === 'ended') return;
-  } else if (campaign.state === CAMPAIGN_STATE.ENDED) {
-    finishEndedCampaign();
-    return;
-  }
-  hideResultOverlays();
-  attachVisionListener();
-  attachAnimationListeners();
-  attachRepListeners();
-  attachCyberListeners();
-  recomputeVision();
-  renderShell();
-}
-
-// ---------------------------------------------------------------------------
-// Vision (mirrors the debug harness rule: refresh on every entity move)
-// ---------------------------------------------------------------------------
-
-function attachVisionListener(): void {
-  if (visionMoveUnsub) {
-    visionMoveUnsub();
-    visionMoveUnsub = null;
-  }
-  const run = currentScene();
-  if (!run?.bus) return;
-  visionMoveUnsub = run.bus.on(EVENT.ENTITY_MOVED, () => recomputeVision());
-}
-
-/**
- * Subscribe the combat-feedback animations to the active run's bus.
- *
- *   - `entity:damaged` where the player is the target → shake + reddening
- *     (~300ms lock).
- *   - `noise` of `kind: 'ranged'` or `'melee'` → muzzle flash on the
- *     shooter's tile (~80ms lock). Fires for *any* attacker so the player
- *     also sees drones return fire.
- *
- * Re-attached on every Run state transition because Run.#tearDownWorld
- * recreates `bus` from scratch — same posture as `attachVisionListener`.
- */
-function attachAnimationListeners(): void {
-  for (const off of animationUnsubs) off();
-  animationUnsubs = [];
-  const run = currentScene();
-  if (!run?.bus) return;
-  animationUnsubs.push(
-    run.bus.on(EVENT.ENTITY_DAMAGED, payload => {
-      const {
-        attacker,
-        target,
-        damage = 0,
-        killed,
-        source,
-      } = (payload ?? {}) as EntityDamagedPayload;
-      const jacked = isJackedIn(run);
-      // Player-side feedback: screen shake + red vignette when *we* get hit.
-      if (run?.player && target === run.player && damage > 0) {
-        triggerShake(stageEl);
-        triggerDamageFlash(stageEl);
-        animLock.push(ANIMATION_DURATIONS.DAMAGE_FLASH);
-        if (jacked) {
-          const attackerLabel = attacker
-            ? resolveEntityLabel(attacker.id, run.world!.entities)
-            : 'unknown';
-          flash(
-            killed
-              ? `BODY FLATLINED — ${attackerLabel} killed your meatspace link.`
-              : `BODY HIT — ${attackerLabel} struck for ${damage} (meatspace).`
-          );
-          triggerPipHitPulse();
-          paintPip();
-        }
-      }
-      // Melee impact: the strike reads as landing on the *target*, not
-      // hovering above the attacker. Ranged stays on the NOISE path so
-      // misses still get a muzzle flash on the shooter's tile.
-      if (source === 'melee' && target && damage > 0) {
-        if (jacked && target === run.player) {
-          const fired = runMuzzleFlash(pipRenderer, paintPip, target.x, target.y);
-          if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
-        } else if (!jacked) {
-          const fired = runMuzzleFlash(renderer, paint, target.x, target.y);
-          if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
-        }
-      }
-      // Memorise corpse position when a kill occurs within current LOS.
-      if (killed && target && vision.isVisible(target.x, target.y)) {
-        vision.memoriseCorpse(target);
-      }
-    }),
-    run.bus.on(EVENT.NOISE, payload => {
-      const noise = (payload ?? {}) as NoisePayload;
-      // Muzzle flash on the shooter's tile. Melee is handled via
-      // ENTITY_DAMAGED above (so we know the *target* position); NOISE
-      // for melee would only know the attacker.
-      if (noise.kind !== 'ranged') return;
-      const origin = noise.origin;
-      if (!origin) return;
-      const jacked = isJackedIn(run);
-      const flashRenderer = jacked ? pipRenderer : renderer;
-      const repaint = jacked ? paintPip : paint;
-      const fired = runMuzzleFlash(flashRenderer, repaint, origin.x, origin.y);
-      if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
-    }),
-    run.bus.on(EVENT.DOOR_UNLOCKED, payload => {
-      const { label = 'Door' } = (payload ?? {}) as DoorUnlockPayload;
-      flash(`${label} unlocked — passage open.`);
-    }),
-    // P3.M3.6: Run's own JACK_IN listener (wired at enterCombat, so it runs
-    // first) has already spawned the layer by the time this fires — the
-    // shell just swaps its presentation onto the grid.
-    run.bus.on(EVENT.JACK_IN, () => {
-      attachCyberListeners();
-      if (!isJackedIn(currentScene())) return;
-      recomputeVision();
-      flash('LINK ESTABLISHED — entering // THE GRID //.');
-      paint();
-    })
-  );
-}
-
-/**
- * P3.M3.6: subscribe avatar-side feedback to the *cyber* bus while a layer
- * is active — combat shake/flash for the avatar, muzzle flashes for ICE
- * strikes, corpse memory in `cyberVision`, vision refresh on movement, and
- * the jack-out swap back to Meatspace. No-op (and cleanup) when dormant or
- * resolved. Called from every scene (re)wiring site plus the JACK_IN hook,
- * so a mid-jack-in resume re-attaches automatically.
- */
-function attachCyberListeners(): void {
-  for (const off of cyberUnsubs) off();
-  cyberUnsubs = [];
-  const run = currentScene();
-  const layer = cyberLayerOf(run);
-  if (!run || !layer) return;
-  cyberVision = new VisionField();
-  cyberVision.restoreSeen(layer.mapSeenKeys());
-  cyberUnsubs.push(
-    layer.bus.on(EVENT.ENTITY_MOVED, () => recomputeVision()),
-    layer.bus.on(EVENT.ENTITY_DAMAGED, payload => {
-      const { target, damage = 0, killed, source } = (payload ?? {}) as EntityDamagedPayload;
-      if (target === layer.avatar && damage > 0) {
-        triggerShake(stageEl);
-        triggerDamageFlash(stageEl);
-        animLock.push(ANIMATION_DURATIONS.DAMAGE_FLASH);
-      }
-      if (source === 'melee' && target && damage > 0) {
-        const fired = runMuzzleFlash(renderer, paint, target.x, target.y);
-        if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
-      }
-      if (killed && target && cyberVision.isVisible(target.x, target.y)) {
-        cyberVision.memoriseCorpse(target);
-      }
-    }),
-    layer.bus.on(EVENT.NOISE, payload => {
-      const noise = (payload ?? {}) as NoisePayload;
-      if (noise.kind !== 'ranged') return;
-      const origin = noise.origin;
-      if (!origin) return;
-      const fired = runMuzzleFlash(renderer, paint, origin.x, origin.y);
-      if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
-    }),
-    layer.bus.on(EVENT.JACK_OUT, () => {
-      // Run.jackOut (subscribed first) has either resolved the layer or, with
-      // the objective incomplete, deferred to the early-jack-out confirmation
-      // (S7.5) — the modal's confirm path completes the swap instead.
-      if (cyberLayerOf(currentScene())) return;
-      completeJackOutShellSwap();
-    })
-  );
-}
-
-/**
- * S7.5: shell-side half of a finalized jack-out — drop the cyber listeners
- * and re-present Meatspace. Reached from the JACK_OUT bus event (immediate
- * resolve) or the `jack-out-early` modal confirmation (deferred resolve).
- */
-function completeJackOutShellSwap(): void {
-  for (const off of cyberUnsubs) off();
-  cyberUnsubs = [];
-  pipCanvas.hidden = true;
-  flash('LINK DROPPED — back in your body.');
-  recomputeVision();
-  paint();
-}
-
-/**
- * Subscribe Rep-affecting events to the active run's bus.
- *
- *   - `civilian:harmed` (NeutralCivilian only) → -20 Rep per kill; track harm
- *     for clean completion. Corp staff kills are excluded.
- *   - `alarm` with `kind: 'facility'` → -5 Rep per CorpCivilian raise. Terminal
- *     slice/unlock alarms and lookout pings do not adjust Rep.
- *
- * Re-attached on every Run state transition (same posture as animations).
- */
-function attachRepListeners(): void {
-  for (const off of repUnsubs) off();
-  repUnsubs = [];
-  civilianHarmsThisJob = 0;
-  const run = currentScene();
-  if (!run?.bus || !campaign) return;
-  repUnsubs.push(
-    run.bus.on(EVENT.CIVILIAN_HARMED, payload => {
-      if (!campaign) return;
-      civilianHarmsThisJob++;
-      const { killed } = (payload ?? {}) as { killed?: boolean };
-      if (killed) {
-        const actual = campaign.adjustRep(REP.CIVILIAN_KILL_PENALTY);
-        flash(`REP ${actual >= 0 ? '+' : ''}${actual}: civilian killed.`);
-      }
-    }),
-    run.bus.on(EVENT.ALARM, payload => {
-      if (!campaign || !alarmPayloadTriggersRepPenalty(payload)) return;
-      const actual = campaign.adjustRep(REP.ALARM_PENALTY);
-      flash(`REP ${actual >= 0 ? '+' : ''}${actual}: facility alarm triggered.`);
-    }),
-    run.bus.on(EVENT.ALARM_CHANGED, payload => {
-      const transition = (payload as { transition?: string } | undefined)?.transition;
-      if (transition === 'cooldown') {
-        flash('ALERT: heat tapering — corp net entering cooldown.');
-      } else if (transition === 'quiet') {
-        flash('ALERT: facility net quiet.');
-      }
-    }),
-    run.bus.on(EVENT.OBJECTIVE_TIMER_EXPIRED, payload => {
-      const contract = (payload as { contract?: { objective?: { title?: string } } } | undefined)
-        ?.contract;
-      const title = contract?.objective?.title ?? 'objective';
-      flash(`WINDOW CLOSED: ${title} can no longer be completed cleanly.`);
-    })
-  );
-}
-
-function recomputeVision(): void {
-  const run = currentScene();
-  if (!run) return;
-  // Meatspace vision stays live even while jacked in — the body still
-  // stands at the port and aftermath/corpse-memory checks read this field.
-  if (run.world && run.player) {
-    vision.recompute(run.world.grid, run.player, undefined, {
-      blockers: run.world.blockerKeys(),
-    });
-    if (isRun(run) && run.state === RUN_STATE.COMBAT) {
-      run.recordMapSeen(vision.visible);
-    }
-  }
-  const layer = cyberLayerOf(run);
-  if (layer) {
-    cyberVision.recompute(layer.world.grid, layer.avatar, undefined, {
-      blockers: layer.world.blockerKeys(),
-    });
-    layer.recordSeen(cyberVision.visible);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Presentation
-// ---------------------------------------------------------------------------
-
-function renderShell(): void {
-  if (!campaign) return;
-  const run = currentScene();
-  const state = run?.state;
-  switch (state) {
-    case CAMPAIGN_STATE.HUB:
-    case RUN_STATE.COMBAT:
-      canvas.hidden = false;
-      briefingEl.hide();
-      hideResultOverlays();
-      break;
-    case RUN_STATE.BRIEFING:
-      // The combined briefing modal handles its own show/hide. If we land
-      // here on resume, re-present the briefing so the player can pick an
-      // operative.
-      canvas.hidden = true;
-      if (!briefingEl.isOpen) {
-        if (!campaign.activeRun?.contract) {
-          throw new Error('[shell] briefing state without an active contract');
-        }
-        briefingEl.setContract(campaign.activeRun.contract);
-        briefingEl.setCrew(campaign.crew);
-        briefingEl.show();
-      }
-      hideResultOverlays();
-      break;
-    case RUN_STATE.RESULT:
-      canvas.hidden = true;
-      briefingEl.hide();
-      gameOverEl.hide();
-      crashEl.show();
-      break;
-    case CAMPAIGN_STATE.ENDED:
-      canvas.hidden = true;
-      briefingEl.hide();
-      crashEl.hide();
-      gameOverEl.show();
-      break;
-    default:
-      throw new Error(`[shell] unknown state "${state}"`);
-  }
-  paint();
-}
-
-/**
- * The persistent location chip text for the canvas top-left. Combat shows
- * the contract's site flavor label (bracketed by `//`); the Hub shows
- * "// Safe House //" so the corner always answers "where am I".
- */
-function currentLocationLabel(): string | undefined {
-  if (!campaign) return undefined;
-  if (isJackedIn(currentScene())) {
-    return '// THE GRID //';
-  }
-  if (campaign.state === CAMPAIGN_STATE.COMBAT && campaign.activeRun?.contract) {
-    const { principal, site } = campaign.activeRun.contract.context;
-    const siteName = site?.label ?? 'Location Unknown';
-    const labelName = `${principal.label} - ${siteName}`;
-    return `// ${labelName} //`;
-  }
-  if (campaign.state === CAMPAIGN_STATE.HUB) {
-    return '// Safe House //';
-  }
-  return undefined;
-}
-
-function buildCombatHudSnapshot(scene: ShellScene | null): CombatHudSummaryInput | null {
-  if (!scene || scene.state !== RUN_STATE.COMBAT) return null;
-  if (!isRun(scene)) {
-    throw new Error('[shell] combat HUD requires an active run');
-  }
-  if (!scene.player || !scene.queue) {
-    throw new Error('[shell] combat HUD requires player and turn queue');
-  }
-  return {
-    objective:
-      scene.contract && scene.world
-        ? {
-            title: scene.contract.objective.title,
-            done: scene.isObjectiveSatisfied(),
-            turnsRemaining: scene.objectiveTurnsRemaining(),
-            progress: scene.objectiveProgress(),
-          }
-        : null,
-    ...combatHudBodyPanes(scene),
-    turn: {
-      currentFaction: scene.queue.currentFaction,
-      turnNumber: scene.queue.turnNumber,
-    },
-  };
-}
-
-/**
- * P3.M3.6: identity/HP/AP panes track whoever the player is being right now —
- * the crew body in Meatspace, the avatar (RAM pool) on the grid.
- */
-function combatHudBodyPanes(scene: Run): Pick<CombatHudSummaryInput, 'identity' | 'hp' | 'ap'> {
-  const layer = cyberLayerOf(scene);
-  if (layer) {
-    const avatar = layer.avatar;
-    return {
-      identity: {
-        callsign: avatar.callsign,
-        archetype: 'Avatar',
-        stealthed: avatar.stealthed,
-      },
-      hp: { hp: avatar.hp, maxHp: avatar.maxHp, label: 'RAM' },
-      ap: { ap: avatar.ap, maxAp: avatar.maxAp },
-    };
-  }
-  const player = scene.player!;
-  return {
-    identity: {
-      callsign: player.callsign,
-      archetype: scene.archetype,
-      stealthed: player.stealthed,
-    },
-    hp: { hp: player.hp, maxHp: player.maxHp },
-    ap: { ap: player.ap, maxAp: player.maxAp },
-  };
-}
-
-function buildHubHudRows(scene: ShellScene | null) {
-  if (!campaign || scene?.state !== CAMPAIGN_STATE.HUB) return undefined;
-  const [summary, clock] = formatHubArcStatusLines(campaign);
-  const rows = [
-    {
-      text: summary,
-      anchor: 'top-left' as const,
-      row: 1,
-      color: '#ffd166',
-      glowColor: '#ffd166',
-      accentColor: 'rgba(255, 209, 102, 0.5)',
-      uppercase: true,
-    },
-  ];
-  if (clock) {
-    rows.push({
-      text: clock,
-      anchor: 'top-left' as const,
-      row: 2,
-      color: '#ffd166',
-      glowColor: '#ffd166',
-      accentColor: 'rgba(255, 209, 102, 0.5)',
-      uppercase: true,
-    });
-  }
-  return rows;
-}
-
-function paintPip(): void {
-  const run = currentScene();
-  if (!run || !isRun(run) || run.state !== RUN_STATE.COMBAT || !shouldShowPip(run)) {
-    pipCanvas.hidden = true;
-    return;
-  }
-  if (!run.world || !run.player) {
-    pipCanvas.hidden = true;
-    return;
-  }
-  pipCanvas.hidden = false;
-  const principalId = campaign?.activeRun?.contract?.context?.principal?.id;
-  pipRenderer.draw(run.world, run.player, {
-    camera: pipCameraFor(run.player, run.world),
-    vision,
-    player: run.player,
-    tileset: 'meat',
-    principalId,
-    hudRows: pipChrome(run.player),
-  });
-}
-
-function triggerPipHitPulse(): void {
-  pipCanvas.classList.remove('pip-hit');
-  // Force reflow so repeated hits retrigger the animation.
-  void pipCanvas.offsetWidth;
-  pipCanvas.classList.add('pip-hit');
-}
-
-function paint(stateHint: InputState = activeInputState()): void {
-  const run = currentScene();
-  if (canvas.hidden) {
-    setStatus(statusLine(stateHint));
-    return;
-  }
-  if (!run || !run.world || !run.player) return;
-  // P3.M3.6: the rendered pair — meat body in Meatspace, avatar on the grid.
-  const world = activeWorldOf(run);
-  const actor = activeActorOf(run);
-  if (!world || !actor) return;
-  const jacked = isJackedIn(run);
-  // Hub is a safe space — no fog of war. Vision is only meaningful during
-  // combat where LOS and drone stealth detection matter.
-  const activeVision = run.state === RUN_STATE.COMBAT ? activeVisionField(run) : undefined;
-  // Breach blasts are a Meatspace effect — never painted onto the grid.
-  const blastOverlayKeys =
-    run.state === RUN_STATE.COMBAT && !jacked && activeBreachBlastOverlayKeys.size > 0
-      ? activeBreachBlastOverlayKeys
-      : undefined;
-  const principalId =
-    run.state === RUN_STATE.COMBAT && !jacked
-      ? campaign?.activeRun?.contract?.context?.principal?.id
-      : undefined;
-  renderer.draw(world, actor, {
-    vision: activeVision,
-    player: actor,
-    blastOverlayKeys,
-    lookCursor,
-    principalId,
-    tileset: activeTileset(run),
-    locationLabel: currentLocationLabel(),
-    hudRows: buildHubHudRows(run),
-    combatHud: buildCombatHudSnapshot(run),
-  });
-  crt.alertTint = run.state === RUN_STATE.COMBAT && world.alarmActive;
-  crt.apply();
-  paintPip();
-  setStatus(statusLine(stateHint));
-}
-
-function statusLine(state: InputState): string {
-  const run = currentScene();
-  if (!run) return '';
-  if (run.state !== RUN_STATE.COMBAT) {
-    corpToneActivityBody = null;
-  }
-  const aim = state.mode === MODE.AIM && state.aimKind ? `AIM ${aimKindLabel(state.aimKind)}` : '';
-  const look = state.mode === MODE.LOOK ? 'LOOK' : '';
-  const player = run.player;
-  if (!player) return stateLabel();
-  if (!run.queue) return stateLabel();
-  let identity;
-  let context = '';
-  let combatA11y = '';
-  if (run.state === RUN_STATE.COMBAT) {
-    if (!isRun(run)) {
-      throw new Error('[shell] combat status requires an active run');
-    }
-    const hudSnapshot = buildCombatHudSnapshot(run);
-    if (!hudSnapshot) {
-      throw new Error('[shell] combat status requires HUD summary data');
-    }
-    combatA11y = `<span class="u-sr-only">Combat status: ${escapeHtml(
-      formatCombatHudA11ySummary(hudSnapshot)
-    )}</span>`;
-    // P3.M3.6: alarm + hazard read from the world the player is *being in*.
-    const statusWorld = activeWorldOf(run);
-    const statusActor = activeActorOf(run);
-    const alarm = statusWorld?.alarm;
-    const alertTag =
-      alarm?.phase === 'alert'
-        ? `<span class="alert-tag">ALERT ${alarm.holdTurnsRemaining}</span>`
-        : alarm?.phase === 'cooldown'
-          ? `<span class="alert-tag">COOL ${alarm.cooldownTurnsRemaining}</span>`
-          : '';
-    const onHazard =
-      statusWorld &&
-      statusActor &&
-      statusWorld.grid.tileAt(statusActor.x, statusActor.y) === TILE.HAZARD;
-    const hazardTag = onHazard
-      ? '<span class="hazard-tag">▓ HAZARD — move or take damage</span>'
-      : '';
-    context = joinStatusParts([hazardTag, alertTag]);
-  } else {
-    if (!campaign) return stateLabel();
-    const repLabel = REP_LABEL.find(b => campaign!.rep >= b.min)?.label ?? 'UNKNOWN';
-    context = joinStatusParts(
-      formatHubArcStatusLines(campaign)
-        .filter((line): line is string => line !== null)
-        .map(escapeHtml)
-    );
-    // Hub identity drops the typed-salvage compact tag —
-    // the inventory overlay (`i` in Hub) is the canonical wallet view with
-    // full bucket names. Total Cred / Rep / crew counts stay on this line.
-    identity = `CREW ${campaign.crew.filter(member => !member.flatlined).length}/${campaign.crew.length} CREDS ${campaign.credits ?? 0} REP ${campaign.rep} (${escapeHtml(repLabel)})`;
-  }
-  const modeTag = look && run.state !== RUN_STATE.COMBAT ? look : '';
-  const statsInner =
-    run.state === RUN_STATE.COMBAT
-      ? joinStatusParts([stateLabel(), aim, look])
-      : joinStatusParts([stateLabel(), identity, modeTag]);
-  const stats = `<span class="game-shell__stats">${statsInner}</span>`;
-  const contextRow = `<span class="game-shell__context">${context}</span>`;
-  // Two activity rows below the stable status rows. A single fresh action can
-  // share the HUD with ephemeral, non-logged status (proximity hints, corp
-  // mood). Short same-interaction bursts take both rows so side effects like
-  // door unlocks stay visible instead of disappearing into the log.
-  let ephemeral = '';
-  const hintText = proximityHint();
-  if (hintText) {
-    ephemeral = `<span class="game-shell__activity hint">${hintText}</span>`;
-  } else if (
-    isRun(run) &&
-    run.state === RUN_STATE.COMBAT &&
-    run.queue.currentFaction === run.hostileFaction
-  ) {
-    const corpWorld = activeWorldOf(run);
-    if (!corpWorld) throw new Error('[shell] combat status requires a world');
-    // P3.M3.6: while jacked in, the hostile mood row reads the ICE on the
-    // grid (probes are CORP-faction regardless of the meat principal).
-    const jacked = isJackedIn(run);
-    const visibleHostiles = countVisibleCorpEntities(
-      corpWorld.entities.values(),
-      (x: number, y: number) => activeVisionField(run).isVisible(x, y),
-      jacked ? FACTION.CORP : run.hostileFaction
-    );
-    const body = corpTurnStatusBody(visibleHostiles, run.queue.turnNumber);
-    corpToneActivityBody = body;
-    const hostileTag = jacked ? 'ICE' : run.hostileFaction.toUpperCase();
-    ephemeral = `<span class="game-shell__activity corp"><span class="faction-tag">${hostileTag}</span> — ${body}</span>`;
-  } else if (
-    isRun(run) &&
-    run.state === RUN_STATE.COMBAT &&
-    run.queue.currentFaction === FACTION.PLAYER &&
-    corpToneActivityBody !== null
-  ) {
-    // show the last hostile-turn mood until the player acts and flushes it
-    const hostileTag = isJackedIn(run) ? 'ICE' : run.hostileFaction.toUpperCase();
-    ephemeral = `<span class="game-shell__activity corp"><span class="faction-tag">${hostileTag}</span> — ${corpToneActivityBody}</span>`;
-    corpToneActivityBody = null;
-  }
-  const activityRows = statusActionRows(actionLineHistory, pendingActionLineCount, !!ephemeral);
-  pendingActionLineCount = 0;
-  const [upper, lower] = activityRows.map(row => {
-    if (row.source === 'ephemeral') return ephemeral;
-    return `<span class="game-shell__activity">${escapeHtml(row.text)}</span>`;
-  });
-  return combatA11y + stats + contextRow + upper + lower;
-}
-
-function joinStatusParts(parts: Array<string | null | undefined>): string {
-  return parts
-    .filter(part => part && part.trim().length > 0)
-    .join(' <span class="status-sep">|</span> ');
-}
-
-function escapeHtml(value: string): string {
-  return value.replace(/[&<>"']/g, char => {
-    switch (char) {
-      case '&':
-        return '&amp;';
-      case '<':
-        return '&lt;';
-      case '>':
-        return '&gt;';
-      case '"':
-        return '&quot;';
-      case "'":
-        return '&#39;';
-      default:
-        return char;
-    }
-  });
-}
-
-/**
- * Player-facing nudge for whatever interactable is within reach. Computed
- * fresh every paint so it always reflects the *current* player position
- * (vs. caching at action-time, which would let a stale hint linger after a
- * corp turn shuffled the world).
- *
- * When non-empty, the hint takes the upper activity row in the status bar,
- * bumping the previous action log line. It is *not* pushed into the
- * rolling logLines buffer — it's a transient, positional display.
- *
- * Add a case here when new interactables land (terminals, dropped weapons,
- * etc.).
- */
-function proximityHint(): string {
-  const run = currentScene();
-  if (!run || !run.player) return '';
-  if (run.state === CAMPAIGN_STATE.HUB) {
-    if (run.finn && isChebyshevAdjacent(run.player, run.finn)) {
-      return 'FINN — press [Space] to shop.';
-    }
-    if (run.curator && isChebyshevAdjacent(run.player, run.curator)) {
-      return 'CURATOR — press [Space] for a contract.';
-    }
-    if (run.terminal && isChebyshevAdjacent(run.player, run.terminal)) {
-      return 'TERMINAL — press [Space] for roster.';
-    }
-    if (run.clinic && isChebyshevAdjacent(run.player, run.clinic)) {
-      return 'PATCH — press [Space] for clinic.';
-    }
-    if (run.exitTile && isChebyshevAdjacent(run.player, run.exitTile)) {
-      return 'EXIT (¤) one step away.';
-    }
-    return '';
-  }
-  if (run.state === RUN_STATE.COMBAT) {
-    // P3.M3.6: hints follow the active body — meat props for the crew,
-    // nodes/exit port for the avatar.
-    const world = activeWorldOf(run);
-    const p = activeActorOf(run);
-    const jacked = isJackedIn(run);
-    if (world && p) {
-      // Loot hint: adjacent lootable corpses (needs pockets — avatar skips).
-      if (!jacked) {
-        for (let dy = -1; dy <= 1; dy++) {
-          for (let dx = -1; dx <= 1; dx++) {
-            const e = world.lootableCorpseAt(p.x + dx, p.y + dy);
-            if (e && !e.alive && e.loot && totalSalvage(e.loot.salvage) > 0) {
-              return 'SALVAGE nearby — press [Space] to loot.';
-            }
-          }
-        }
-      }
-      const interactable = world.adjacentInteractables(p)[0];
-      if (interactable) {
-        return `${interactable.label.toUpperCase()} nearby — press [Space] to interact.`;
-      }
-    }
-    if (!jacked && run.exitTile && isChebyshevAdjacent(run.player, run.exitTile)) {
-      return 'EXIT (¤) one step away.';
-    }
-  }
-  return '';
-}
-
-/** Stash a one-shot message that the next paint surfaces in the status bar. */
-function flash(line: string): void {
-  const scene = currentScene();
-  if (scene?.state === RUN_STATE.COMBAT && scene.queue?.currentFaction === FACTION.PLAYER) {
-    corpToneActivityBody = null;
-  }
-  actionLineHistory = recordStatusActionLine(actionLineHistory, line);
-  pendingActionLineCount = Math.min(pendingActionLineCount + 1, actionLineHistory.length);
-  const currentActionLine = actionLineHistory[0] ?? '';
-  if (currentActionLine) {
-    logLines.unshift(`> ${currentActionLine}`);
-    if (logLines.length > 20) logLines.splice(20);
-    logContentEl.textContent = logLines.join('\n');
-  }
-}
-
-function stateLabel(): string {
-  const run = currentScene();
-  if (!run) return 'BOOTING';
-  switch (run.state) {
-    case CAMPAIGN_STATE.HUB:
-      return '[HUB]';
-    case RUN_STATE.BRIEFING:
-      return '[BRIEFING]';
-    case RUN_STATE.COMBAT:
-      return '[COMBAT]';
-    case RUN_STATE.RESULT:
-      return '[DEBRIEF]';
-    case CAMPAIGN_STATE.ENDED:
-      return '[ENDED]';
-    default:
-      return run.state ?? '';
-  }
-}
-
-function setStatus(richText: string): void {
-  if (statusEl) statusEl.innerHTML = richText;
-}
-
-function activeInputState(): InputState {
-  if (touchPadEl && touchPadEl.mode !== MODE.IDLE) {
-    return { mode: touchPadEl.mode, aimKind: touchPadEl.aimKind ?? null };
-  }
-  return { mode: keyboard?.mode ?? MODE.IDLE, aimKind: keyboard?.aimKind ?? null };
-}
-
-function setInputAim(aimKind: AimKind): void {
-  keyboard.mode = MODE.AIM;
-  keyboard.aimKind = aimKind;
-  touchPadEl.setMode(MODE.AIM, aimKind);
-  paint({ mode: MODE.AIM, aimKind });
-}
-
-function resetInputModes(): void {
-  lookCursor = null;
-  keyboard.mode = MODE.IDLE;
-  keyboard.aimKind = null;
-  touchPadEl.setMode(MODE.IDLE);
-  // Clear any half-armed thrown-consumable aim. Esc-cancel from
-  // aim mode, or a cross-controller cancel, must not leave a stashed item
-  // hanging — a later inventory click would otherwise mismatch.
-  pendingAimItemId = null;
-}
-
-// ---------------------------------------------------------------------------
-// Geometry helpers
-// ---------------------------------------------------------------------------
-
-function isChebyshevAdjacent(a: PointLike, b: PointLike): boolean {
-  return chebyshevDistance(a, b) === 1;
-}
-
-function chebyshevDistance(a: PointLike, b: PointLike): number {
-  if (!a || !b) return Infinity;
-  return Math.max(Math.abs(a.x - b.x), Math.abs(a.y - b.y));
-}
-
-// ---------------------------------------------------------------------------
-// Global keys (UI-layer, not routed through keymap.js)
-// ---------------------------------------------------------------------------
-
-/**
- * Opens <key-help> when Hub/Combat and no blocking modal — same rules as the
- * `?` shortcut and the header toolbar button.
- *
- * @returns {'ok'|'blocking'|'no-scope'|'none'}
- */
-function tryShowKeyHelpOverlay(): 'ok' | 'blocking' | 'no-scope' | 'none' {
-  if (isAnyBlockingModalOpen()) return 'blocking';
-  const scope = helpScopeForRunState();
-  if (!scope) return 'no-scope';
-  const scene = currentScene();
-  const archetypeId = scene && isRun(scene) ? scene.archetype : undefined;
-  keyHelpEl.setScope(scope, archetypeId);
-  keyHelpEl.show();
-  return 'ok';
-}
-
-/**
- * `?` toggles the help overlay. Esc, when the help overlay is open, dismisses
- * it (and we swallow the event so the keymap doesn't also turn it into a
- * `cancel` intent for whatever aim mode was active).
- *
- * `?` is suppressed while any blocking modal owns the foreground — opening
- * help over a briefing or crew-roster would just stack panels.
- */
-function handleGlobalKey(evt: KeyboardEvent): void {
-  if (evt.ctrlKey || evt.metaKey || evt.altKey) return;
-
-  // While <key-help> is open it owns the foreground entirely: `?` and Esc
-  // close it; every other key is swallowed so a held WASD doesn't pump
-  // moves into the game underneath. (Tested manually — gameplay events
-  // routing through this layer was the bug we hit during touchpad
-  // testing too.)
-  if (keyHelpEl.isOpen) {
-    if (evt.key === '?' || evt.key === 'Escape') {
-      evt.preventDefault();
-      evt.stopPropagation();
-      keyHelpEl.hide();
-      return;
-    }
-    // Tab navigation: prevent scroll/focus churn but let <key-help> handle it.
-    if (KeyHelp.isTabNavKey(evt.key)) {
-      evt.preventDefault();
-      return;
-    }
-    // Everything else: block, don't process.
-    evt.preventDefault();
-    evt.stopPropagation();
-    return;
-  }
-
-  if (evt.key !== '?') return;
-  const opened = tryShowKeyHelpOverlay();
-  if (opened === 'ok') {
-    evt.preventDefault();
-    return;
-  }
-  if (opened === 'blocking') {
-    // Briefing / Crash / System start / Resume / Character-select own focus — silently drop
-    // `?` rather than stacking yet another overlay over them.
-    evt.preventDefault();
-  }
-}
-
-function helpScopeForRunState(): HelpScope | null {
-  const run = currentScene();
-  if (!run) return null;
-  if (run.state === CAMPAIGN_STATE.HUB) return 'hub';
-  if (run.state === RUN_STATE.COMBAT) return 'combat';
-  return null;
-}
-
-function isAnyBlockingModalOpen(): boolean {
-  if (contractSelectEl?.isOpen) return true;
-  if (briefingEl?.isOpen) return true;
-  if (crashEl?.isOpen) return true;
-  if (gameOverEl?.isOpen) return true;
-  if (systemStartEl?.isOpen) return true;
-  if (curatorBriefingEl?.isOpen) return true;
-  if (initialRecruitEl?.isOpen) return true;
-  if (crewRosterEl?.isOpen) return true;
-  if (finnShopEl?.isOpen) return true;
-  if (clinicModalEl?.isOpen) return true;
-  if (itemInventoryEl?.isOpen) return true;
-  if (keyHelpEl?.isOpen) return true;
-  if (faultEl?.isOpen) return true;
-  // <confirmation-modal> uses a native <dialog> internally; treat any open
-  // attribute as "blocking".
-  if (isConfirmationDialogOpen(confirmationModalEl)) return true;
-  return false;
-}
-
-// ---------------------------------------------------------------------------
-
 allComponentsReady
   .then(() => {
-    boot().catch(err => {
+    gameShell.boot().catch(err => {
       console.error('[shell] boot failed', err);
-      setStatus(`BOOT ERROR — ${err.message}`);
+      const statusEl = document.getElementById('game-status');
+      if (statusEl) {
+        statusEl.textContent = `BOOT ERROR — ${err instanceof Error ? err.message : String(err)}`;
+      }
     });
   })
   .catch(err => {
     console.error('[shell] display components failed to load', err);
-    setStatus(`BOOT ERROR — ${err.message}`);
+    const statusEl = document.getElementById('game-status');
+    if (statusEl) {
+      statusEl.textContent = `BOOT ERROR — ${err instanceof Error ? err.message : String(err)}`;
+    }
   });
+
+// Re-export for modules that expect KeyHelp on the entry graph.
+void KeyHelp;
diff --git a/src/game/Run.ts b/src/game/Run.ts
index 6519a18..43adb61 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -372,6 +372,10 @@ export type RunOptions = {
    *  live. No callback registered → jack out immediately (tests/harness),
    *  matching the `onAbortRequested` posture. */
   onJackOutRequested?: unknown;
+  /** Shell presentation — fired after jack-in completes. */
+  onJackInPresent?: unknown;
+  /** Shell presentation — fired after jack-out finalizes. */
+  onJackOutPresent?: unknown;
   /** Terrain mutations from a prior visit to this location (P2.5.M7.2), replayed
    *  onto the freshly-built map in `enterCombat`. Empty/omitted for a first visit. */
   priorMutationDeltas?: unknown;
@@ -432,6 +436,10 @@ export class Run {
   onResult: ((result: RunResult) => void) | null;
   onAbortRequested: (() => void) | null;
   onJackOutRequested: (() => void) | null;
+  /** Shell presentation hook — fired synchronously after jack-in completes. */
+  onJackInPresent: (() => void) | null;
+  /** Shell presentation hook — fired after jack-out finalizes. */
+  onJackOutPresent: (() => void) | null;
   _busUnsubs: (() => void)[];
 
   constructor({
@@ -442,6 +450,8 @@ export class Run {
     onResult,
     onAbortRequested,
     onJackOutRequested,
+    onJackInPresent,
+    onJackOutPresent,
     priorMutationDeltas,
     priorKeyItems,
     priorSeenKeys,
@@ -467,6 +477,12 @@ export class Run {
     if (onJackOutRequested !== undefined && typeof onJackOutRequested !== 'function') {
       throw new TypeError('Run: onJackOutRequested must be a function');
     }
+    if (onJackInPresent !== undefined && typeof onJackInPresent !== 'function') {
+      throw new TypeError('Run: onJackInPresent must be a function');
+    }
+    if (onJackOutPresent !== undefined && typeof onJackOutPresent !== 'function') {
+      throw new TypeError('Run: onJackOutPresent must be a function');
+    }
     if (priorMutationDeltas !== undefined && !Array.isArray(priorMutationDeltas)) {
       throw new TypeError('Run: priorMutationDeltas must be an array when supplied');
     }
@@ -506,6 +522,8 @@ export class Run {
     this.onResult = (onResult as ((result: RunResult) => void) | undefined) ?? null;
     this.onAbortRequested = (onAbortRequested as (() => void) | undefined) ?? null;
     this.onJackOutRequested = (onJackOutRequested as (() => void) | undefined) ?? null;
+    this.onJackInPresent = (onJackInPresent as (() => void) | undefined) ?? null;
+    this.onJackOutPresent = (onJackOutPresent as (() => void) | undefined) ?? null;
 
     /** @type {Array<() => void>} active bus subscriptions */
     this._busUnsubs = [];
@@ -893,6 +911,7 @@ export class Run {
     if (this.onPersist) {
       this.onPersist(this.snapshot());
     }
+    this.onJackInPresent?.();
   }
 
   /**
@@ -964,9 +983,8 @@ export class Run {
     if (this.onPersist) {
       this.onPersist(this.snapshot());
     }
+    this.onJackOutPresent?.();
   }
-
-  /** The contract's single meat-side jack-in point. Missing on a cyber run is corrupt. */
   #meatJackInPoint(): JackInPoint {
     if (!this.world) {
       throw new Error('Run.#meatJackInPoint: no live world');
diff --git a/src/shell/activeView.ts b/src/shell/activeView.ts
new file mode 100644
index 0000000..13c8db6
--- /dev/null
+++ b/src/shell/activeView.ts
@@ -0,0 +1,54 @@
+/**
+ * P3.M3.6 active-view seam. While the Decker is jacked in, presentation and
+ * input look through these helpers at the cyber layer; in Meatspace (and the
+ * Hub) they are identity functions.
+ */
+import type { CyberspaceLayer } from '../game/cyber/CyberspaceLayer.js';
+import type { Run } from '../game/Run.js';
+import type { Entity } from '../game/Entity.js';
+import type { World } from '../game/World.js';
+import type { VisionField } from '../game/Vision.js';
+import type { TilesetId } from '../render/palette.js';
+
+/** Minimal scene shape for active-view resolution (Run or Campaign hub scene). */
+export type ActiveViewScene = {
+  world: World | null;
+  player: Entity | null;
+  cyberspace?: Run['cyberspace'];
+  state?: Run['state'] | string | null;
+} & Partial<Pick<Run, 'archetype'>>;
+
+export function isRunScene(
+  scene: ActiveViewScene
+): scene is ActiveViewScene & Pick<Run, 'archetype'> {
+  return 'archetype' in scene && scene.archetype !== undefined;
+}
+
+export function cyberLayerOf(scene: ActiveViewScene | null): CyberspaceLayer | null {
+  if (!scene || !isRunScene(scene)) return null;
+  return scene.cyberspace?.phase === 'active' ? scene.cyberspace.layer : null;
+}
+
+export function isJackedIn(scene: ActiveViewScene | null): boolean {
+  return cyberLayerOf(scene) !== null;
+}
+
+export function activeWorldOf(scene: ActiveViewScene): World | null {
+  return cyberLayerOf(scene)?.world ?? scene.world;
+}
+
+export function activeActorOf(scene: ActiveViewScene): Entity | null {
+  return cyberLayerOf(scene)?.avatar ?? scene.player;
+}
+
+export function pickActiveVisionField(
+  scene: ActiveViewScene | null,
+  meatVision: VisionField,
+  cyberVisionField: VisionField
+): VisionField {
+  return isJackedIn(scene) ? cyberVisionField : meatVision;
+}
+
+export function activeTileset(scene: ActiveViewScene | null): TilesetId {
+  return isJackedIn(scene) ? 'cyber' : 'meat';
+}
diff --git a/src/shell/combatHudSnapshot.ts b/src/shell/combatHudSnapshot.ts
new file mode 100644
index 0000000..836a4d2
--- /dev/null
+++ b/src/shell/combatHudSnapshot.ts
@@ -0,0 +1,64 @@
+import { RUN_STATE } from '../game/Run.js';
+import type { Run } from '../game/Run.js';
+import type { CombatHudSummaryInput } from '../render/combatHud.js';
+import { cyberLayerOf } from './activeView.js';
+import { isRun } from './sceneView.js';
+import type { ShellScene } from './sceneView.js';
+
+export function buildCombatHudSnapshot(scene: ShellScene | null): CombatHudSummaryInput | null {
+  if (!scene || scene.state !== RUN_STATE.COMBAT) return null;
+  if (!isRun(scene)) {
+    throw new Error('[shell] combat HUD requires an active run');
+  }
+  if (!scene.player || !scene.queue) {
+    throw new Error('[shell] combat HUD requires player and turn queue');
+  }
+  return {
+    objective:
+      scene.contract && scene.world
+        ? {
+            title: scene.contract.objective.title,
+            done: scene.isObjectiveSatisfied(),
+            turnsRemaining: scene.objectiveTurnsRemaining(),
+            progress: scene.objectiveProgress(),
+          }
+        : null,
+    ...combatHudBodyPanes(scene),
+    turn: {
+      currentFaction: scene.queue.currentFaction,
+      turnNumber: scene.queue.turnNumber,
+    },
+  };
+}
+
+/**
+ * P3.M3.6: identity/HP/AP panes track whoever the player is being right now —
+ * the crew body in Meatspace, the avatar (RAM pool) on the grid.
+ */
+export function combatHudBodyPanes(
+  scene: Run
+): Pick<CombatHudSummaryInput, 'identity' | 'hp' | 'ap'> {
+  const layer = cyberLayerOf(scene);
+  if (layer) {
+    const avatar = layer.avatar;
+    return {
+      identity: {
+        callsign: avatar.callsign,
+        archetype: 'Avatar',
+        stealthed: avatar.stealthed,
+      },
+      hp: { hp: avatar.hp, maxHp: avatar.maxHp, label: 'RAM' },
+      ap: { ap: avatar.ap, maxAp: avatar.maxAp },
+    };
+  }
+  const player = scene.player!;
+  return {
+    identity: {
+      callsign: player.callsign,
+      archetype: scene.archetype,
+      stealthed: player.stealthed,
+    },
+    hp: { hp: player.hp, maxHp: player.maxHp },
+    ap: { ap: player.ap, maxAp: player.maxAp },
+  };
+}
diff --git a/src/shell/domTypes.ts b/src/shell/domTypes.ts
new file mode 100644
index 0000000..064a0ff
--- /dev/null
+++ b/src/shell/domTypes.ts
@@ -0,0 +1,171 @@
+import type { Campaign } from '../game/Campaign.js';
+import type { Crew } from '../game/Crew.js';
+import type { Contract } from '../game/hub/Curator.js';
+import type { Item } from '../game/items.js';
+import type { CampaignSummary } from '../game/campaignSummary.js';
+import type { TypedSalvage } from '../game/salvage.js';
+import type { KeyItem, Telemetry } from '../types.js';
+import type { AimKind, Mode } from '../input/keymap.js';
+
+export type HelpScope = 'hub' | 'combat';
+
+export type ModalElement = HTMLElement & {
+  show(): void;
+  hide(): void;
+  readonly isOpen: boolean;
+};
+
+export type CuratorBriefingContent = { title: string; lines: readonly string[] };
+
+export type RunBriefingElement = ModalElement & {
+  setContract(contract: Contract): void;
+  setCrew(crew: Crew[]): void;
+};
+
+export type ContractSelectElement = ModalElement & {
+  setContracts(contracts: Contract[]): void;
+  setScoreTargetSiteId(siteId: string | null): void;
+  setScorePrincipalId(principalId: string | null): void;
+};
+
+export type CrashDumpElement = ModalElement & {
+  setTelemetry(telemetry: Telemetry): void;
+};
+
+export type GameOverElement = ModalElement & {
+  setSummary(summary: CampaignSummary): void;
+};
+
+export type FaultScreenElement = ModalElement & {
+  show(detail: { code?: string }): void;
+};
+
+export type SystemStartElement = ModalElement & {
+  setSession(session: { seed: number }): void;
+};
+
+export type CuratorBriefingElement = ModalElement & {
+  setBriefing(content: CuratorBriefingContent): void;
+};
+
+export type InitialRecruitElement = ModalElement & {
+  setCandidates(candidates: Crew[]): void;
+};
+
+export type CrewRosterElement = ModalElement & {
+  setCrew(
+    crew: Crew[],
+    opts?: {
+      salvage?: TypedSalvage;
+      campaignStatus?: string | readonly string[];
+      availableRecruits?: Crew[];
+      recruitedThisVisit?: boolean;
+    }
+  ): void;
+};
+
+export type FinnShopElement = ModalElement & {
+  setCatalog(
+    catalog: Item[],
+    crew: Crew[],
+    balances: { credits: number; salvage: TypedSalvage }
+  ): void;
+};
+
+export type ClinicModalElement = ModalElement & {
+  setPatients(crew: Crew[], balances: { credits: number; healedMemberIds?: string[] }): void;
+};
+
+export type ItemInventoryElement = ModalElement & {
+  setContents(contents: {
+    salvage?: TypedSalvage;
+    consumables?: NonNullable<Crew['inventory']>['consumables'];
+    keyItems?: KeyItem[];
+  }): void;
+  setItems(consumables: NonNullable<Crew['inventory']>['consumables']): void;
+};
+
+export type KeyHelpElement = ModalElement & {
+  setScope(scope: HelpScope, archetypeId?: string): void;
+};
+
+export type TouchPadElement = HTMLElement & {
+  mode: Mode;
+  aimKind: AimKind | null;
+  setMode(mode: Mode, aimKind?: AimKind | null): void;
+  setBlocked(predicate: (() => boolean) | null): void;
+};
+
+export type ConfirmationModalElement = HTMLElement & {
+  showModal(message: string, context?: unknown): void;
+};
+
+export type UpdateNotificationElement = HTMLElement & {
+  show(pendingWorker: ServiceWorker | null): void;
+};
+
+export type InputState = {
+  mode: Mode;
+  aimKind: AimKind | null;
+};
+
+export type EntityDamagedPayload = {
+  attacker?: import('../game/Entity.js').Entity;
+  target?: import('../game/Entity.js').Entity;
+  damage?: number;
+  killed?: boolean;
+  source?: string;
+};
+
+export type NoisePayload = {
+  kind?: string;
+  origin?: { x: number; y: number };
+};
+
+export type DoorUnlockPayload = {
+  label?: string;
+};
+
+export type ShellDomRefs = {
+  stageEl: HTMLElement;
+  pipCanvas: HTMLCanvasElement;
+};
+
+export type ShellRenderers = {
+  main: import('../render/AsciiRenderer.js').AsciiRenderer;
+  pip: import('../render/AsciiRenderer.js').AsciiRenderer;
+};
+
+export type AnimationLock = {
+  push(ms: number): void;
+};
+
+export type SceneListenerDeps = {
+  getScene: () => import('./sceneView.js').ShellScene | null;
+  getCampaign: () => Campaign | null;
+  getMeatVision: () => import('../game/Vision.js').VisionField;
+  getCyberVision: () => import('../game/Vision.js').VisionField;
+  resetCyberVision: () => import('../game/Vision.js').VisionField;
+  dom: ShellDomRefs;
+  renderers: ShellRenderers;
+  animLock: AnimationLock;
+  effects: {
+    flash(line: string): void;
+    paint(): void;
+    paintPip(): void;
+    recomputeVision(): void;
+  };
+  onCivilianHarmReset(): void;
+  onCivilianHarmed(killed: boolean): void;
+  onRepAdjust(actual: number, reason: string): void;
+  onAlarmTransition(transition: string): void;
+  onObjectiveTimerExpired(title: string): void;
+  memoriseMeatCorpse(
+    target: import('../game/Entity.js').Entity,
+    isVisible: (x: number, y: number) => boolean
+  ): void;
+  memoriseCyberCorpse(
+    target: import('../game/Entity.js').Entity,
+    isVisible: (x: number, y: number) => boolean
+  ): void;
+};
diff --git a/src/shell/locationHud.ts b/src/shell/locationHud.ts
new file mode 100644
index 0000000..2f96329
--- /dev/null
+++ b/src/shell/locationHud.ts
@@ -0,0 +1,58 @@
+import { CAMPAIGN_STATE } from '../game/Campaign.js';
+import type { Campaign } from '../game/Campaign.js';
+import { formatHubArcStatusLines } from '../game/hub/arcSurface.js';
+import { isJackedIn } from './activeView.js';
+import type { ShellScene } from './sceneView.js';
+
+/**
+ * The persistent location chip text for the canvas top-left. Combat shows
+ * the contract's site flavor label (bracketed by `//`); the Hub shows
+ * "// Safe House //" so the corner always answers "where am I".
+ */
+export function currentLocationLabel(
+  campaign: Campaign | null,
+  scene: ShellScene | null
+): string | undefined {
+  if (!campaign) return undefined;
+  if (isJackedIn(scene)) {
+    return '// THE GRID //';
+  }
+  if (campaign.state === CAMPAIGN_STATE.COMBAT && campaign.activeRun?.contract) {
+    const { principal, site } = campaign.activeRun.contract.context;
+    const siteName = site?.label ?? 'Location Unknown';
+    const labelName = `${principal.label} - ${siteName}`;
+    return `// ${labelName} //`;
+  }
+  if (campaign.state === CAMPAIGN_STATE.HUB) {
+    return '// Safe House //';
+  }
+  return undefined;
+}
+
+export function buildHubHudRows(campaign: Campaign | null, scene: ShellScene | null) {
+  if (!campaign || scene?.state !== CAMPAIGN_STATE.HUB) return undefined;
+  const [summary, clock] = formatHubArcStatusLines(campaign);
+  const rows = [
+    {
+      text: summary,
+      anchor: 'top-left' as const,
+      row: 1,
+      color: '#ffd166',
+      glowColor: '#ffd166',
+      accentColor: 'rgba(255, 209, 102, 0.5)',
+      uppercase: true,
+    },
+  ];
+  if (clock) {
+    rows.push({
+      text: clock,
+      anchor: 'top-left' as const,
+      row: 2,
+      color: '#ffd166',
+      glowColor: '#ffd166',
+      accentColor: 'rgba(255, 209, 102, 0.5)',
+      uppercase: true,
+    });
+  }
+  return rows;
+}
diff --git a/src/shell/sceneListeners.ts b/src/shell/sceneListeners.ts
new file mode 100644
index 0000000..e860d18
--- /dev/null
+++ b/src/shell/sceneListeners.ts
@@ -0,0 +1,204 @@
+import { REP } from '../game/constants.js';
+import { EVENT, alarmPayloadTriggersRepPenalty } from '../game/events.js';
+import { resolveEntityLabel } from '../game/Entity.js';
+import {
+  ANIMATION_DURATIONS,
+  runMuzzleFlash,
+  triggerDamageFlash,
+  triggerShake,
+} from '../render/animations.js';
+import { cyberLayerOf, isJackedIn } from './activeView.js';
+import type {
+  DoorUnlockPayload,
+  EntityDamagedPayload,
+  NoisePayload,
+  SceneListenerDeps,
+} from './domTypes.js';
+
+/**
+ * Owns run-bus and cyber-bus listener subscriptions for the game shell.
+ * Call `rewire()` on every scene transition and after resume.
+ */
+export class SceneListenerController {
+  #deps: SceneListenerDeps;
+  #visionMoveUnsub: (() => void) | null = null;
+  #animationUnsubs: (() => void)[] = [];
+  #cyberUnsubs: (() => void)[] = [];
+  #repUnsubs: (() => void)[] = [];
+
+  constructor(deps: SceneListenerDeps) {
+    this.#deps = deps;
+  }
+
+  rewire(): void {
+    this.#attachVisionListener();
+    this.#attachAnimationListeners();
+    this.#attachRepListeners();
+    this.#attachCyberListeners();
+  }
+
+  detachCyber(): void {
+    for (const off of this.#cyberUnsubs) off();
+    this.#cyberUnsubs = [];
+  }
+
+  #attachVisionListener(): void {
+    if (this.#visionMoveUnsub) {
+      this.#visionMoveUnsub();
+      this.#visionMoveUnsub = null;
+    }
+    const run = this.#deps.getScene();
+    if (!run?.bus) return;
+    this.#visionMoveUnsub = run.bus.on(EVENT.ENTITY_MOVED, () =>
+      this.#deps.effects.recomputeVision()
+    );
+  }
+
+  #attachAnimationListeners(): void {
+    for (const off of this.#animationUnsubs) off();
+    this.#animationUnsubs = [];
+    const run = this.#deps.getScene();
+    if (!run?.bus) return;
+    const { dom, renderers, animLock, effects } = this.#deps;
+    const meatVision = this.#deps.getMeatVision();
+
+    this.#animationUnsubs.push(
+      run.bus.on(EVENT.ENTITY_DAMAGED, payload => {
+        const {
+          attacker,
+          target,
+          damage = 0,
+          killed,
+          source,
+        } = (payload ?? {}) as EntityDamagedPayload;
+        const jacked = isJackedIn(run);
+        if (run?.player && target === run.player && damage > 0) {
+          triggerShake(dom.stageEl);
+          triggerDamageFlash(dom.stageEl);
+          animLock.push(ANIMATION_DURATIONS.DAMAGE_FLASH);
+          if (jacked) {
+            const attackerLabel = attacker
+              ? resolveEntityLabel(attacker.id, run.world!.entities)
+              : 'unknown';
+            effects.flash(
+              killed
+                ? `BODY FLATLINED — ${attackerLabel} killed your meatspace link.`
+                : `BODY HIT — ${attackerLabel} struck for ${damage} (meatspace).`
+            );
+            dom.pipCanvas.classList.remove('pip-hit');
+            void dom.pipCanvas.offsetWidth;
+            dom.pipCanvas.classList.add('pip-hit');
+            effects.paintPip();
+          }
+        }
+        if (source === 'melee' && target && damage > 0) {
+          if (jacked && target === run.player) {
+            const fired = runMuzzleFlash(renderers.pip, effects.paintPip, target.x, target.y);
+            if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
+          } else if (!jacked) {
+            const fired = runMuzzleFlash(renderers.main, effects.paint, target.x, target.y);
+            if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
+          }
+        }
+        if (killed && target) {
+          this.#deps.memoriseMeatCorpse(target, (x, y) => meatVision.isVisible(x, y));
+        }
+      }),
+      run.bus.on(EVENT.NOISE, payload => {
+        const noise = (payload ?? {}) as NoisePayload;
+        if (noise.kind !== 'ranged') return;
+        const origin = noise.origin;
+        if (!origin) return;
+        const jacked = isJackedIn(run);
+        const flashRenderer = jacked ? renderers.pip : renderers.main;
+        const repaint = jacked ? effects.paintPip : effects.paint;
+        const fired = runMuzzleFlash(flashRenderer, repaint, origin.x, origin.y);
+        if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
+      }),
+      run.bus.on(EVENT.DOOR_UNLOCKED, payload => {
+        const { label = 'Door' } = (payload ?? {}) as DoorUnlockPayload;
+        effects.flash(`${label} unlocked — passage open.`);
+      })
+    );
+  }
+
+  #attachCyberListeners(): void {
+    for (const off of this.#cyberUnsubs) off();
+    this.#cyberUnsubs = [];
+    const run = this.#deps.getScene();
+    const layer = cyberLayerOf(run);
+    if (!run || !layer) return;
+
+    const cyberVision = this.#deps.resetCyberVision();
+    cyberVision.restoreSeen(layer.mapSeenKeys());
+    const { dom, renderers, animLock, effects } = this.#deps;
+
+    this.#cyberUnsubs.push(
+      layer.bus.on(EVENT.ENTITY_MOVED, () => effects.recomputeVision()),
+      layer.bus.on(EVENT.ENTITY_DAMAGED, payload => {
+        const { target, damage = 0, killed, source } = (payload ?? {}) as EntityDamagedPayload;
+        if (target === layer.avatar && damage > 0) {
+          triggerShake(dom.stageEl);
+          triggerDamageFlash(dom.stageEl);
+          animLock.push(ANIMATION_DURATIONS.DAMAGE_FLASH);
+        }
+        if (source === 'melee' && target && damage > 0) {
+          const fired = runMuzzleFlash(renderers.main, effects.paint, target.x, target.y);
+          if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
+        }
+        if (killed && target) {
+          this.#deps.memoriseCyberCorpse(target, (x, y) => cyberVision.isVisible(x, y));
+        }
+      }),
+      layer.bus.on(EVENT.NOISE, payload => {
+        const noise = (payload ?? {}) as NoisePayload;
+        if (noise.kind !== 'ranged') return;
+        const origin = noise.origin;
+        if (!origin) return;
+        const fired = runMuzzleFlash(renderers.main, effects.paint, origin.x, origin.y);
+        if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
+      })
+    );
+  }
+
+  #attachRepListeners(): void {
+    for (const off of this.#repUnsubs) off();
+    this.#repUnsubs = [];
+    this.#deps.onCivilianHarmReset();
+    const run = this.#deps.getScene();
+    const campaign = this.#deps.getCampaign();
+    if (!run?.bus || !campaign) return;
+
+    this.#repUnsubs.push(
+      run.bus.on(EVENT.CIVILIAN_HARMED, payload => {
+        const { killed } = (payload ?? {}) as { killed?: boolean };
+        this.#deps.onCivilianHarmed(!!killed);
+        if (killed) {
+          const actual = campaign.adjustRep(REP.CIVILIAN_KILL_PENALTY);
+          this.#deps.onRepAdjust(actual, 'civilian killed.');
+        }
+      }),
+      run.bus.on(EVENT.ALARM, payload => {
+        if (!alarmPayloadTriggersRepPenalty(payload)) return;
+        const actual = campaign.adjustRep(REP.ALARM_PENALTY);
+        this.#deps.onRepAdjust(actual, 'facility alarm triggered.');
+      }),
+      run.bus.on(EVENT.ALARM_CHANGED, payload => {
+        const transition = (payload as { transition?: string } | undefined)?.transition;
+        if (transition === 'cooldown') {
+          this.#deps.effects.flash('ALERT: heat tapering — corp net entering cooldown.');
+        } else if (transition === 'quiet') {
+          this.#deps.effects.flash('ALERT: facility net quiet.');
+        }
+        if (transition) this.#deps.onAlarmTransition(transition);
+      }),
+      run.bus.on(EVENT.OBJECTIVE_TIMER_EXPIRED, payload => {
+        const contract = (payload as { contract?: { objective?: { title?: string } } } | undefined)
+          ?.contract;
+        const title = contract?.objective?.title ?? 'objective';
+        this.#deps.onObjectiveTimerExpired(title);
+        this.#deps.effects.flash(`WINDOW CLOSED: ${title} can no longer be completed cleanly.`);
+      })
+    );
+  }
+}
diff --git a/src/shell/sceneView.ts b/src/shell/sceneView.ts
new file mode 100644
index 0000000..e493835
--- /dev/null
+++ b/src/shell/sceneView.ts
@@ -0,0 +1,29 @@
+import type { Campaign } from '../game/Campaign.js';
+import type { Run } from '../game/Run.js';
+
+export type ShellSceneView =
+  | { kind: 'hub'; campaign: Campaign; scene: Campaign }
+  | { kind: 'run'; campaign: Campaign; scene: Run };
+
+export function resolveSceneView(campaign: Campaign | null): ShellSceneView | null {
+  if (!campaign) return null;
+  const activeRun = campaign.activeRun;
+  if (!activeRun) {
+    return { kind: 'hub', campaign, scene: campaign };
+  }
+  return { kind: 'run', campaign, scene: activeRun };
+}
+
+export function assertRun(view: ShellSceneView): Run {
+  if (view.kind !== 'run') {
+    throw new Error('[shell] expected an active run scene');
+  }
+  return view.scene;
+}
+
+/** Scene returned by `currentScene()` — hub Campaign or active Run episode. */
+export type ShellScene = Campaign | Run;
+
+export function isRun(scene: ShellScene): scene is Run {
+  return 'archetype' in scene;
+}
diff --git a/src/shell/shellRuntime.ts b/src/shell/shellRuntime.ts
new file mode 100644
index 0000000..c19eb43
--- /dev/null
+++ b/src/shell/shellRuntime.ts
@@ -0,0 +1,2430 @@
+/**
+ * Game shell runtime — state and orchestration extracted from index.ts.
+ */
+import dataStore from '/src/DataStore.js';
+import { serviceWorkerManager } from '/src/ServiceWorkerManager.js';
+
+import { Campaign, CAMPAIGN_STATE, willEndCampaignAfterResult } from '/src/game/Campaign.js';
+import { buildCampaignSummary } from '/src/game/campaignSummary.js';
+import { totalSalvage, formatSalvageCompact } from '/src/game/salvage.js';
+import { RUN_STATE, Run } from '/src/game/Run.js';
+import { restoreCampaign, snapshotCampaign } from '/src/game/persistence.js';
+import { runCorpTurn as driveCorpTurn } from '/src/game/corpTurnDriver.js';
+import {
+  FACTION,
+  AP_COST,
+  TILE,
+  REP,
+  REP_LABEL,
+  INCENDIARY_THROW_DIST,
+  BREACHING_CHARGE_RANGE,
+} from '/src/game/constants.js';
+import {
+  advanceFromPlayerTurn,
+  drivePlayerAftermath,
+  formatPlayerAftermathStepLogLines,
+  isPlayerAftermathStepLogVisible,
+} from '/src/game/combatTurnPipeline.js';
+import {
+  corpTurnStatusBody,
+  countVisibleCorpEntities,
+  formatCorpTurnStep,
+  isCorpTurnStepLogVisibleToPlayer,
+  isCorpTurnStepVisibleToPlayer,
+} from '/src/game/corpTurnStatusCopy.js';
+import { VisionField } from '/src/game/Vision.js';
+import { describeTileAt } from '/src/game/describe.js';
+import { AsciiRenderer } from '/src/render/AsciiRenderer.js';
+import { CrtFilter } from '/src/render/CrtFilter.js';
+import {
+  ANIMATION_DURATIONS,
+  createAnimationLock,
+  runInteractSecuredFlash,
+  triggerShake,
+} from '/src/render/animations.js';
+import { Interactable } from '/src/game/entities/Interactable.js';
+import { KeyboardController } from '/src/input/KeyboardController.js';
+import { AIM_KIND, MODE } from '/src/input/keymap.js';
+import { applyIntent, PLAYER_ACTIONS } from '/src/input/applyIntent.js';
+import { recordStatusActionLine } from '/src/statusActivityRows.js';
+
+import { placeSmoke, clearSmoke } from '/src/game/Smoke.js';
+import { placeHazardCluster } from '/src/game/Run.js';
+import { blastCells } from '/src/game/breachBlast.js';
+import { hasLineOfSight } from '/src/game/LineOfSight.js';
+import { ITEM_ID, getItemById } from '/src/game/items.js';
+import type { CampaignSnapshot } from '/src/game/persistence.js';
+import type { Contract } from '/src/game/hub/Curator.js';
+import {
+  formatHubArcStatusLines,
+  scorePrincipalId,
+  scoreTargetSiteId,
+} from '/src/game/hub/arcSurface.js';
+import {
+  commitHubReveal,
+  hubRevealCommitsOnDismiss,
+  isTerminalAccessible,
+  type HubRevealId,
+} from '/src/game/hub/hubReveals.js';
+import type { Crew } from '/src/game/Crew.js';
+import { resolveEntityLabel, type Entity } from '/src/game/Entity.js';
+import type { RunResult, RunTelemetry, Outcome } from '/src/game/Run.js';
+import type { Item } from '/src/game/items.js';
+import type { Intent } from '/src/input/applyIntent.js';
+import type { AimKind } from '/src/input/keymap.js';
+import { pipCameraFor, pipChrome, shouldShowPip } from '/src/render/pip.js';
+import type { TurnActionStep } from '/src/types.js';
+import { installErrorBoundary, type FaultSignal } from '/src/errorBoundary.js';
+import { isDevelopmentMode } from '/src/domUtils.js';
+import {
+  activeActorOf,
+  activeTileset,
+  activeWorldOf,
+  cyberLayerOf,
+  isJackedIn,
+  pickActiveVisionField,
+} from '/src/shell/activeView.js';
+import { buildCombatHudSnapshot } from '/src/shell/combatHudSnapshot.js';
+import { buildHubHudRows, currentLocationLabel } from '/src/shell/locationHud.js';
+import { SceneListenerController } from '/src/shell/sceneListeners.js';
+import { isRun, resolveSceneView, type ShellScene } from '/src/shell/sceneView.js';
+import {
+  escapeHtml,
+  formatAlertTag,
+  formatHazardTag,
+  formatStatusLine,
+  hostileMoodTag,
+  isHostileTurnSlice,
+  isPlayerTurnSlice,
+  joinStatusParts,
+  stateLabelForSceneState,
+} from '/src/shell/statusLine.js';
+import { applyMeatSeenRecord, syncVisionFields } from '/src/shell/visionSync.js';
+import type {
+  ClinicModalElement,
+  ConfirmationModalElement,
+  ContractSelectElement,
+  CrashDumpElement,
+  CrewRosterElement,
+  CuratorBriefingElement,
+  FaultScreenElement,
+  FinnShopElement,
+  GameOverElement,
+  InitialRecruitElement,
+  InputState,
+  ItemInventoryElement,
+  KeyHelpElement,
+  RunBriefingElement,
+  SystemStartElement,
+  TouchPadElement,
+  UpdateNotificationElement,
+} from '/src/shell/domTypes.js';
+
+import KeyHelp from '/components/KeyHelp.js';
+
+type SmokeOverlay = ReturnType<typeof placeSmoke>[number];
+type PointLike = Pick<Entity, 'x' | 'y'> | { x: number; y: number } | null | undefined;
+type HelpScope = import('/src/shell/domTypes.js').HelpScope;
+
+type PendingJobResult = {
+  outcome: Outcome;
+  telemetry: RunTelemetry & { outcome: Outcome };
+};
+
+/** Dev-only: `?triggerFault=corp` throws once on the next corp turn (see phase-2.6-plan). */
+let devFaultTrigger: string | null = null;
+let devFaultConsumed = false;
+
+function initDevFaultTrigger(): void {
+  if (!isDevelopmentMode()) return;
+  const param = new URLSearchParams(location.search).get('triggerFault');
+  if (!param) return;
+  devFaultTrigger = param;
+  if (param === 'rejection') {
+    devFaultConsumed = true;
+    Promise.reject(new Error('[dev] triggerFault=rejection'));
+  }
+}
+
+function maybeDevFault(site: string): void {
+  if (!devFaultTrigger || devFaultConsumed || devFaultTrigger !== site) return;
+  devFaultConsumed = true;
+  throw new Error(`[dev] triggerFault=${site}`);
+}
+
+let campaign: Campaign | null = null;
+let vision = new VisionField();
+/**
+ * P3.M3.6: the cyber grid's own fog field — `vision` stays Meatspace-truth
+ * for the body (aftermath visibility, meat corpse memory) while the avatar
+ * sees through this one. Rebuilt (and re-seeded from `layer.mapSeen`) every
+ * time the cyber listeners attach.
+ */
+let cyberVision = new VisionField();
+let sceneListenerController: SceneListenerController;
+let civilianHarmsThisJob = 0;
+
+let canvas: HTMLCanvasElement;
+/** P3.M3.7: meatspace CCTV overlay while jacked in. */
+let pipCanvas: HTMLCanvasElement;
+let statusEl: HTMLElement | null = null;
+let renderer: AsciiRenderer;
+let pipRenderer: AsciiRenderer;
+let crt: CrtFilter;
+let stageEl: HTMLElement;
+let briefingEl: RunBriefingElement;
+let contractSelectEl: ContractSelectElement;
+let crashEl: CrashDumpElement;
+let gameOverEl: GameOverElement;
+let faultEl: FaultScreenElement;
+let systemStartEl: SystemStartElement;
+let curatorBriefingEl: CuratorBriefingElement;
+/** Status line to flash after the player dismisses a Hub reveal briefing. */
+let hubRevealFollowUpFlash: string | null = null;
+/** Score reveal (and future deferred reveals) commit their flag on dismiss. */
+let pendingHubRevealId: HubRevealId | null = null;
+let initialRecruitEl: InitialRecruitElement;
+let confirmationModalEl: ConfirmationModalElement;
+let touchPadEl: TouchPadElement;
+let crewRosterEl: CrewRosterElement;
+let finnShopEl: FinnShopElement;
+let clinicModalEl: ClinicModalElement;
+let itemInventoryEl: ItemInventoryElement;
+let keyHelpEl: KeyHelpElement;
+let logEl: HTMLElement;
+let logHeaderEl: HTMLElement;
+let logContentEl: HTMLPreElement;
+let keyboard: KeyboardController;
+
+let currentJobOptions: Contract[] = [];
+
+/**
+ * Animation-lock for combat feedback. Listeners on the run bus
+ * (`attachAnimationListeners`) push durations as effects fire; both
+ * input controllers consult `isLocked()` so a key held mid-shake doesn't
+ * sneak through. See `src/render/animations.js`.
+ */
+const animLock = createAnimationLock();
+
+let pendingJobResult: PendingJobResult | null = null;
+/** Latched during tier-1 fault recovery — blocks autosave and stale turn pumps. */
+let degrading = false;
+/** Set when degradeToHub successfully re-read hub state from disk. */
+let faultHubRestored = false;
+/** Bumped to invalidate in-flight corp/aftermath setTimeout pumps after a fault. */
+let combatPumpGeneration = 0;
+
+function invalidateCombatPumps(): void {
+  combatPumpGeneration += 1;
+  animLock.reset();
+}
+
+function scheduleCombatPump(fn: () => void, ms: number): void {
+  const generation = combatPumpGeneration;
+  setTimeout(() => {
+    if (generation !== combatPumpGeneration || degrading) return;
+    fn();
+  }, ms);
+}
+/**
+ * Active smoke overlays from Smoke Charge consumables. Each entry records
+ * the tile position and original tile type so `clearSmoke` can restore the
+ * grid. Cleared at the start of the player's next turn (`onPlayerTurnReady`).
+ */
+let activeSmokeOverlays: SmokeOverlay[] = [];
+/** Hazard-glyph blast flash — cleared on a short timer after each detonation. */
+let activeBreachBlastOverlayKeys = new Set<string>();
+let breachBlastOverlayTimer: ReturnType<typeof setTimeout> | null = null;
+
+function clearBreachBlastOverlay(repaint = false): void {
+  if (breachBlastOverlayTimer) {
+    clearTimeout(breachBlastOverlayTimer);
+    breachBlastOverlayTimer = null;
+  }
+  if (activeBreachBlastOverlayKeys.size === 0) return;
+  activeBreachBlastOverlayKeys.clear();
+  if (repaint) paint();
+}
+
+function showBreachBlastOverlay(cx: number, cy: number): void {
+  clearBreachBlastOverlay(false);
+  for (const { x, y } of blastCells(cx, cy)) {
+    activeBreachBlastOverlayKeys.add(`${x},${y}`);
+  }
+  breachBlastOverlayTimer = setTimeout(() => {
+    breachBlastOverlayTimer = null;
+    activeBreachBlastOverlayKeys.clear();
+    paint();
+  }, ANIMATION_DURATIONS.BREACH_BLAST_OVERLAY);
+}
+
+/**
+ * Recent intent-result log lines (melee, fire, perk use, denials, etc.).
+ * Stored newest-first, then rendered oldest-to-newest so a single interaction
+ * burst stays readable: terminal side effects (door unlock, alarm/Rep) remain
+ * visible beside the terminal result instead of disappearing into the log.
+ */
+let actionLineHistory: string[] = [];
+let pendingActionLineCount = 0;
+let lookCursor: { x: number; y: number } | null = null;
+
+/**
+ * Plain-text body after `CORP —` from the last status paint while the queue
+ * belonged to CORP. Surfaced again on the player slice until `flash()` runs
+ * on the player's turn (new feedback replaces it; avoids snapping the third
+ * row back to a stale `lastActionLine` from before the yield).
+ */
+let corpToneActivityBody: string | null = null;
+
+/**
+ * Rolling game-log buffer (newest first in `logLines`).
+ * Tracked at module level because `applyIntent`'s `log` callback fires
+ * during intent handling, but the status line is finalised later in
+ * `paint()` — without this, the action line gets clobbered by the
+ * subsequent statusLine() rewrite.
+ */
+let logLines: string[] = [];
+
+const seedFromClock = () => Date.now() & 0xffffffff;
+
+function mustGetElement<T extends HTMLElement>(id: string): T {
+  const el = document.getElementById(id);
+  if (!el) {
+    throw new Error(`[shell] required element #${id} is missing`);
+  }
+  return el as T;
+}
+
+function mustQuery<T extends Element>(selector: string, root: ParentNode = document): T {
+  const el = root.querySelector(selector);
+  if (!el) {
+    throw new Error(`[shell] required selector "${selector}" is missing`);
+  }
+  return el as T;
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+function activeVisionField(scene: ShellScene | null): VisionField {
+  return pickActiveVisionField(scene, vision, cyberVision);
+}
+
+function initSceneListenerController(): void {
+  sceneListenerController = new SceneListenerController({
+    getScene: currentScene,
+    getCampaign: () => campaign,
+    getMeatVision: () => vision,
+    getCyberVision: () => cyberVision,
+    resetCyberVision: () => {
+      cyberVision = new VisionField();
+      return cyberVision;
+    },
+    dom: { stageEl, pipCanvas },
+    renderers: { main: renderer, pip: pipRenderer },
+    animLock,
+    effects: {
+      flash,
+      paint,
+      paintPip,
+      recomputeVision,
+    },
+    onCivilianHarmReset: () => {
+      civilianHarmsThisJob = 0;
+    },
+    onCivilianHarmed: killed => {
+      if (killed) civilianHarmsThisJob++;
+    },
+    onRepAdjust: (actual, reason) => {
+      flash(`REP ${actual >= 0 ? '+' : ''}${actual}: ${reason}`);
+    },
+    onAlarmTransition: () => {},
+    onObjectiveTimerExpired: () => {},
+    memoriseMeatCorpse: (target, isVisible) => {
+      if (isVisible(target.x, target.y)) {
+        vision.memoriseCorpse(target);
+      }
+    },
+    memoriseCyberCorpse: (target, isVisible) => {
+      if (isVisible(target.x, target.y)) {
+        cyberVision.memoriseCorpse(target);
+      }
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Boot
+// ---------------------------------------------------------------------------
+
+export async function boot() {
+  canvas = mustGetElement<HTMLCanvasElement>('game-canvas');
+  const gameStage = canvas.closest('.game-stage');
+  if (!(gameStage instanceof HTMLElement)) {
+    throw new Error('[shell] #game-canvas must live inside .game-stage');
+  }
+  stageEl = gameStage;
+  statusEl = mustGetElement<HTMLElement>('game-status');
+  contractSelectEl = mustGetElement<ContractSelectElement>('contract-select');
+  briefingEl = mustGetElement<RunBriefingElement>('briefing');
+  crashEl = mustGetElement<CrashDumpElement>('crash');
+  gameOverEl = mustGetElement<GameOverElement>('game-over');
+  faultEl = mustGetElement<FaultScreenElement>('fault-screen');
+  systemStartEl = mustGetElement<SystemStartElement>('system-start');
+  curatorBriefingEl = mustGetElement<CuratorBriefingElement>('curator-briefing');
+  initialRecruitEl = mustGetElement<InitialRecruitElement>('initial-recruit');
+  confirmationModalEl = mustGetElement<ConfirmationModalElement>('confirm-modal');
+  touchPadEl = mustGetElement<TouchPadElement>('touch-pad');
+  crewRosterEl = mustGetElement<CrewRosterElement>('crew-roster');
+  finnShopEl = mustGetElement<FinnShopElement>('finn-shop');
+  clinicModalEl = mustGetElement<ClinicModalElement>('clinic-modal');
+  itemInventoryEl = mustGetElement<ItemInventoryElement>('item-inventory');
+  keyHelpEl = mustGetElement<KeyHelpElement>('key-help');
+  logEl = mustQuery<HTMLElement>('.game-log');
+  logHeaderEl = mustQuery<HTMLElement>('.game-log h3');
+  logContentEl = mustQuery<HTMLPreElement>('pre', logEl);
+
+  renderer = new AsciiRenderer(canvas);
+  pipCanvas = mustGetElement<HTMLCanvasElement>('pip-canvas');
+  pipRenderer = new AsciiRenderer(pipCanvas, { cellSize: 10, fontSize: 9 });
+  crt = new CrtFilter(canvas);
+  initSceneListenerController();
+
+  keyboard = new KeyboardController({
+    onIntent: (intent: Intent) => {
+      handleIntent(intent);
+      paint();
+    },
+    onModeChange: () => {
+      // Keep the keyboard / touchpad in lock-step so cross-input cancel still holds.
+      handleInputModeChange();
+      paint();
+    },
+    isBlocked: () => animLock.isLocked() || isAnyBlockingModalOpen(),
+  });
+  keyboard.attach();
+
+  // `?` and Esc-for-help live above the keymap: `?` is a UI toggle (not a
+  // game intent), and Esc must reach <key-help> before the keymap turns it
+  // into a `cancel` intent. Capture phase + a return-early when the help
+  // panel is open keeps both behaviours clean.
+  window.addEventListener('keydown', handleGlobalKey, true);
+
+  contractSelectEl.addEventListener('contract-selected', onContractSelected);
+  contractSelectEl.addEventListener('dismiss', () => contractSelectEl.hide());
+  briefingEl.addEventListener('deploy', onBriefingDeploy);
+  briefingEl.addEventListener('dismiss', onBriefingDismiss);
+  crashEl.addEventListener('new-run', onNewRunRequested);
+  gameOverEl.addEventListener('new-run', onNewRunRequested);
+  faultEl.addEventListener('return-to-hub', () => onFaultReturnToHub());
+  systemStartEl.addEventListener('hub-enter', onSystemStartHubEnter);
+  curatorBriefingEl.addEventListener('dismiss', onCuratorBriefingDismiss);
+  initialRecruitEl.addEventListener('recruited', onInitialRecruited);
+
+  crewRosterEl.addEventListener('dismiss', () => crewRosterEl.hide());
+  crewRosterEl.addEventListener('recruit', onCrewRecruit);
+
+  finnShopEl.addEventListener('purchase', onFinnPurchase);
+  finnShopEl.addEventListener('sell-salvage', onFinnSellSalvage);
+  finnShopEl.addEventListener('dismiss', () => finnShopEl.hide());
+
+  clinicModalEl.addEventListener('heal', onClinicHeal);
+  clinicModalEl.addEventListener('dismiss', onClinicDismiss);
+
+  itemInventoryEl.addEventListener('use-item', onUseItem);
+  itemInventoryEl.addEventListener('dismiss', () => itemInventoryEl.hide());
+
+  keyHelpEl.addEventListener('dismiss', () => keyHelpEl.hide());
+
+  const keyHelpToggleEl = document.getElementById('key-help-toggle');
+  if (keyHelpToggleEl) {
+    keyHelpToggleEl.addEventListener('click', () => {
+      if (keyHelpEl.isOpen) {
+        keyHelpEl.hide();
+        return;
+      }
+      tryShowKeyHelpOverlay();
+    });
+  }
+
+  confirmationModalEl.addEventListener('confirm', evt => {
+    const detail = (evt as CustomEvent<{ context?: string }>).detail;
+    switch (detail?.context) {
+      case 'resume-campaign':
+        // not currently implemented
+        break;
+      case 'quit-campaign':
+        performQuitCampaign();
+        break;
+      case 'abort-run':
+        const run = campaign?.activeRun;
+        if (run) {
+          run.confirmAbort();
+          paint();
+        }
+        break;
+      case 'jack-out-early': {
+        const activeRun = campaign?.activeRun;
+        if (activeRun) {
+          activeRun.confirmJackOut();
+        }
+        break;
+      }
+    }
+  });
+
+  touchPadEl.addEventListener('intent', evt => {
+    handleIntent((evt as CustomEvent<Intent>).detail);
+    paint();
+  });
+  touchPadEl.addEventListener('mode-change', () => {
+    handleInputModeChange();
+    paint();
+  });
+  touchPadEl.setBlocked(() => animLock.isLocked() || isAnyBlockingModalOpen());
+
+  logHeaderEl.addEventListener('click', () => {
+    logEl.classList.toggle('collapsed');
+  });
+
+  // Update-notification wiring kept from the original scaffold.
+  const updateNotification = mustQuery<UpdateNotificationElement>('update-notification');
+  window.addEventListener('sw-update-available', event => {
+    const detail = (event as CustomEvent<{ pendingWorker: ServiceWorker | null }>).detail;
+    updateNotification.show(detail.pendingWorker);
+  });
+
+  await dataStore.init();
+  initDevFaultTrigger();
+  installErrorBoundary({ target: window, degrade: degradeToHub });
+  if (dataStore.currentRun) {
+    dataStore.deleteRun(dataStore.currentRun.id);
+  }
+  if (dataStore.currentCampaign) {
+    resumeCampaign(dataStore.currentCampaign);
+  } else {
+    startFreshCampaign();
+  }
+
+  // SW registration is the same posture as the debug scaffold — kicked off last
+  // so it doesn't gate the shell's first paint.
+  serviceWorkerManager.register().catch(err => console.warn('[shell] sw register failed', err));
+}
+
+// ---------------------------------------------------------------------------
+// Run lifecycle
+// ---------------------------------------------------------------------------
+
+function startFreshCampaign() {
+  hideBlockingShellModals();
+  campaign = new Campaign({
+    seed: seedFromClock(),
+    crew: [],
+    onPersist: handlePersist,
+    onResult: handleResult,
+  });
+
+  pendingJobResult = null;
+  setStatus('Booting Meatspace…');
+  systemStartEl.setSession({ seed: campaign.seed });
+  systemStartEl.show();
+}
+
+function onSystemStartHubEnter() {
+  systemStartEl.hide();
+  if (!campaign) return;
+  // Fresh campaign: crew is empty — show initial recruitment overlay.
+  if (campaign.crew.length === 0) {
+    const candidates = campaign.generateInitialCandidates();
+    initialRecruitEl.setCandidates(candidates);
+    initialRecruitEl.show();
+    return;
+  }
+  // Resumed or post-recruitment — go straight to hub.
+  enterHubAndRender();
+}
+
+function onInitialRecruited(evt: Event) {
+  if (!campaign) return;
+  const { memberIds } = (evt as CustomEvent<{ memberIds: string[] }>).detail;
+  campaign.recruitInitial(memberIds);
+  initialRecruitEl.hide();
+  // Now the crew is set — enter the hub for the first time (builds world, persists).
+  campaign.enterHub();
+  enterHubAndRender();
+  const names = campaign.crew.map(m => m.callsign).join(' and ');
+  flash(`CURATOR: ${names} on the board. Find me when you want work.`);
+}
+
+function hideResultOverlays(): void {
+  crashEl?.hide();
+  gameOverEl?.hide();
+}
+
+function hideBlockingShellModals(): void {
+  keyHelpEl?.hide();
+  briefingEl?.hide();
+  hideResultOverlays();
+  contractSelectEl?.hide();
+  systemStartEl?.hide();
+  curatorBriefingEl?.hide();
+  initialRecruitEl?.hide();
+  crewRosterEl?.hide();
+  finnShopEl?.hide();
+  clinicModalEl?.hide();
+  itemInventoryEl?.hide();
+}
+
+function abortShellForFault(): void {
+  hideBlockingShellModals();
+  invalidateCombatPumps();
+  pendingJobResult = null;
+  hubRevealFollowUpFlash = null;
+  pendingHubRevealId = null;
+  corpToneActivityBody = null;
+  clearBreachBlastOverlay(false);
+  resetInputModes();
+  activeSmokeOverlays = [];
+  civilianHarmsThisJob = 0;
+}
+
+function hubSnapshotFromLastGoodSave(saved: CampaignSnapshot): CampaignSnapshot {
+  return {
+    ...saved,
+    state: CAMPAIGN_STATE.HUB,
+    activeRun: null,
+    deployedMemberId: null,
+  };
+}
+
+function degradeToHub(signal: FaultSignal): void {
+  degrading = true;
+  faultHubRestored = false;
+  try {
+    abortShellForFault();
+
+    const saved = dataStore.currentCampaign as CampaignSnapshot | null;
+    if (!saved) {
+      faultEl.show({ code: signal.source });
+      return;
+    }
+
+    resumeCampaign(hubSnapshotFromLastGoodSave(saved));
+    faultHubRestored = true;
+    faultEl.show({ code: signal.source });
+  } catch (err) {
+    try {
+      console.error('[shell] degradeToHub failed:', err);
+    } catch {
+      // ignore
+    }
+    faultEl.show({ code: signal.source });
+  }
+}
+
+function onFaultReturnToHub(): void {
+  faultEl.hide();
+  degrading = false;
+  if (faultHubRestored) {
+    handlePersist();
+    if (campaign?.state === CAMPAIGN_STATE.ENDED) {
+      renderShell();
+      canvas.focus();
+      return;
+    }
+    enterHubAndRender();
+  } else {
+    dataStore.deleteCampaign();
+    startFreshCampaign();
+  }
+  canvas.focus();
+}
+
+/**
+ * Attach listeners and render the hub after enterHub() has been called.
+ * Shared by both the post-initial-recruitment path and the normal
+ * system-start path (when crew already exists).
+ */
+/**
+ * Show a full-screen Curator briefing for a pending Hub reveal, if any.
+ * Defers `followUpFlash` to the status line until the player dismisses the modal.
+ */
+function presentHubRevealIfAny(followUpFlash: string): boolean {
+  if (!campaign?.lastHubReveal) return false;
+  const reveal = campaign.lastHubReveal;
+  campaign.lastHubReveal = null;
+  hubRevealFollowUpFlash = followUpFlash;
+  pendingHubRevealId = hubRevealCommitsOnDismiss(reveal.id) ? reveal.id : null;
+  curatorBriefingEl.setBriefing({ title: reveal.title, lines: reveal.lines });
+  curatorBriefingEl.show();
+  return true;
+}
+
+function onCuratorBriefingDismiss(): void {
+  curatorBriefingEl.hide();
+  if (pendingHubRevealId && campaign) {
+    commitHubReveal(campaign, pendingHubRevealId);
+    pendingHubRevealId = null;
+    handlePersist();
+  }
+  if (hubRevealFollowUpFlash) {
+    flash(hubRevealFollowUpFlash);
+    hubRevealFollowUpFlash = null;
+  }
+}
+
+function enterHubAndRender() {
+  if (!campaign?.curator) {
+    throw new Error('enterHubAndRender: hub not entered — curator is missing.');
+  }
+  rewireSceneListeners();
+  recomputeVision();
+  renderShell();
+  if (!presentHubRevealIfAny('HUB — Curator has contracts when you are adjacent [Space].')) {
+    flash('HUB — Curator has contracts when you are adjacent [Space].');
+  }
+  // generate job options once on hub enter
+  currentJobOptions = generateCurrentJobOptions();
+}
+
+function presentCrewRoster() {
+  if (!campaign) return;
+  campaign.backfillRecruitsIfEligible();
+  crewRosterEl.setCrew(campaign.crew, {
+    salvage: campaign.salvage,
+    campaignStatus: formatHubArcStatusLines(campaign).filter(
+      (line): line is string => line !== null
+    ),
+    availableRecruits: campaign.availableRecruits,
+    recruitedThisVisit: campaign.recruitedThisVisit,
+  });
+  crewRosterEl.show();
+}
+
+function onCrewRecruit(evt: Event) {
+  if (!campaign) return;
+  const { recruitId } = (evt as CustomEvent<{ recruitId: string }>).detail;
+  try {
+    campaign.recruit(recruitId);
+    const member = campaign.getCrewMember(recruitId);
+    flash(`NEW OPERATIVE: ${member?.callsign ?? recruitId} joins the collective.`);
+    // A replacement Decker can unlock THE SCORE immediately. Preserve the
+    // existing three-card board and append only the newly legal finale.
+    if (
+      campaign.canAttemptScore() &&
+      !currentJobOptions.some(contract => contract.context.recipeId === 'score-final')
+    ) {
+      currentJobOptions.push(campaign.buildScoreContract());
+    }
+    // Refresh the roster to reflect the new crew + hide recruit section.
+    presentCrewRoster();
+  } catch (err) {
+    flash(`RECRUITMENT FAILED: ${(err as Error).message}`);
+  }
+}
+
+function presentBriefing(contract: Contract) {
+  if (!campaign) return;
+  briefingEl.setContract(contract);
+  briefingEl.setCrew(campaign.crew);
+  briefingEl.show();
+}
+
+function presentContractSelect(contracts: Contract[]) {
+  contractSelectEl.setScoreTargetSiteId(campaign ? scoreTargetSiteId(campaign) : null);
+  contractSelectEl.setScorePrincipalId(campaign ? scorePrincipalId(campaign) : null);
+  contractSelectEl.setContracts(contracts);
+  contractSelectEl.show();
+}
+
+function generateCurrentJobOptions(): Contract[] {
+  if (!campaign?.curator) {
+    throw new Error('generateCurrentJobOptions: hub not entered — curator is missing.');
+  }
+  const contracts = campaign.curator.generateContracts(campaign.rng, campaign);
+  if (campaign.canAttemptScore()) {
+    contracts.push(campaign.buildScoreContract());
+  }
+  return contracts;
+}
+
+function onContractSelected(evt: Event) {
+  const { contract } = (evt as CustomEvent<{ contract?: Contract }>).detail;
+  if (!contract) return;
+  contractSelectEl.hide();
+  flash(`CURATOR: ${contract.label} — choose an operative.`);
+  presentBriefing(contract);
+}
+
+function onBriefingDismiss() {
+  briefingEl.hide();
+  // Hub briefing (no activeRun yet): dismiss returns to the canvas.
+  // Resumed mid-briefing (activeRun in BRIEFING): deployment already
+  // committed — re-present the modal instead of leaving a blank screen.
+  if (campaign?.activeRun?.state === RUN_STATE.BRIEFING) {
+    renderShell();
+  }
+}
+
+function onBriefingDeploy(evt: Event) {
+  if (!campaign) return;
+  const { memberId, contract } = (evt as CustomEvent<{ memberId?: string; contract?: Contract }>)
+    .detail;
+  if (!memberId || !contract) return;
+  const member = campaign.getCrewMember(memberId);
+  if (!member || member.flatlined) return;
+  briefingEl.hide();
+
+  let run = campaign.activeRun;
+  if (run?.state === RUN_STATE.BRIEFING) {
+    // Resumed save: deployCrewMember already ran before the reload.
+    if (run.crewMember.id !== member.id) {
+      flash(
+        `DEPLOY LOCKED: ${run.crewMember.callsign ?? run.crewMember.id} is slotted for this contract.`
+      );
+      briefingEl.show();
+      return;
+    }
+  } else {
+    run = campaign.deployCrewMember(member.id, contract);
+    flash(`CURATOR: ${member.callsign} takes ${contract.label}. JACKING IN.`);
+  }
+
+  // Wire the run's confirmation callbacks (abort extraction, early jack-out).
+  wireRunConfirmations(run);
+
+  // Go straight into combat — the player already reviewed the contract and
+  // chose their operative in the combined briefing modal.
+  if (!run || run.state !== RUN_STATE.BRIEFING) {
+    throw new Error(`[shell] expected deployed run to enter BRIEFING, got ${run?.state}`);
+  }
+  run.enterCombat();
+  handlePersist();
+  vision.resetFogState();
+  if (run.priorSeenKeys.length > 0) {
+    vision.restoreSeen(run.priorSeenKeys);
+  }
+  rewireSceneListeners();
+  recomputeVision();
+  flash('JACKED IN. Reach the exit tile (¤) before the corpos drop you.');
+  renderShell();
+}
+
+function presentFinnShop() {
+  if (!campaign || !campaign.finn) return;
+  const catalog = campaign.finn.catalog(campaign.rep);
+  finnShopEl.setCatalog(catalog, campaign.crew, {
+    credits: campaign.credits,
+    salvage: campaign.salvage,
+  });
+  finnShopEl.show();
+}
+
+function presentClinic() {
+  if (!campaign || !campaign.clinic) return;
+  clinicModalEl.setPatients(campaign.crew, {
+    credits: campaign.credits,
+    healedMemberIds: [...campaign.healedThisVisit],
+  });
+  clinicModalEl.show();
+}
+
+function onClinicHeal(evt: Event) {
+  if (!campaign) return;
+  const { memberId } = (evt as CustomEvent<{ memberId?: string }>).detail;
+  if (!memberId) return;
+  const member = campaign.getCrewMember(memberId);
+  try {
+    campaign.healMember(memberId);
+  } catch (err) {
+    flash(`HEAL FAILED: ${errorMessage(err)}`);
+    return;
+  }
+  const label = member?.callsign ?? memberId;
+  flash(`PATCH: ${label} patched up. CREDS ${campaign.credits}.`);
+  presentClinic();
+}
+
+function onClinicDismiss() {
+  clinicModalEl.hide();
+}
+
+function onFinnPurchase(evt: Event) {
+  if (!campaign) return;
+  const { itemId, targetMemberId } = (
+    evt as CustomEvent<{
+      itemId?: string;
+      targetMemberId?: string;
+    }>
+  ).detail;
+  try {
+    campaign.purchase({ itemId, targetMemberId });
+  } catch (err) {
+    flash(`PURCHASE FAILED: ${errorMessage(err)}`);
+    return;
+  }
+  flash(`FINN: Purchased ${itemId}. CREDS ${campaign.credits}.`);
+  // Refresh the shop to reflect new balance and purchased meta upgrades.
+  presentFinnShop();
+}
+
+function onFinnSellSalvage(evt: Event) {
+  if (!campaign) return;
+  const { quantity, type } = (evt as CustomEvent<{ quantity?: number; type?: string }>).detail;
+  try {
+    if (quantity === undefined) {
+      throw new TypeError('sell-salvage quantity is required');
+    }
+    const creditsBefore = campaign.credits;
+    campaign.sellSalvage(quantity, type as import('/src/game/salvage.js').SalvageType | undefined);
+    const earned = campaign.credits - creditsBefore;
+    flash(`FINN: Bought ${quantity} salvage for ${earned} Cr.`);
+  } catch (err) {
+    flash(`SALE FAILED: ${errorMessage(err)}`);
+    return;
+  }
+  presentFinnShop();
+}
+
+function presentItemInventory() {
+  if (!campaign) return;
+  // Inventory is now available in both Hub and combat. The two states
+  // surface different wallets:
+  //   - Combat: the deployed crew member's job-scoped inventory (what they've
+  //     picked up this run + their consumables).
+  //   - Hub:    the campaign-wide accumulated salvage. No active crew member,
+  //     so no consumables list — the player visits the shop or roster for
+  //     per-crew loadout management.
+  // This keeps the overlay's mental model simple: it always shows the
+  // currently meaningful wallet for the state the player is standing in.
+  if (campaign.state === CAMPAIGN_STATE.HUB) {
+    itemInventoryEl.setContents({
+      salvage: campaign.salvage,
+      consumables: [],
+      keyItems: campaign.keyItems,
+    });
+    itemInventoryEl.show();
+    return;
+  }
+  const run = campaign.activeRun;
+  if (!run || !run.player || !run.player.inventory) return;
+  itemInventoryEl.setContents({
+    salvage: run.player.inventory.salvage,
+    consumables: run.player.inventory.consumables,
+    keyItems: [...campaign.keyItems, ...run.keyItems],
+  });
+  itemInventoryEl.show();
+}
+
+/**
+ * Stashed item id for thrown-consumable aim flow. Set when the
+ * inventory overlay confirmed an aimed consumable (incendiary) and we
+ * flipped the input controllers into `MODE.AIM` with `aimKind: 'use-item'`;
+ * consumed when the subsequent `use-item { dx, dy }` intent arrives or cleared
+ * on cancel.
+ *
+ * Kept at module scope (not inside `onUseItem`) because the aim resolution
+ * happens in a separate event tick from the inventory click — the keypress
+ * routes through KeyboardController → applyIntent → ctx.onUseItem.
+ */
+let pendingAimItemId: string | null = null;
+
+function onUseItem(evt: Event) {
+  if (!campaign) return;
+  const run = campaign.activeRun;
+  if (!run || !run.player) return;
+  if (!run.world) throw new Error('[shell] active combat run has no world');
+  const { itemId } = (evt as CustomEvent<{ itemId?: string }>).detail;
+  if (!itemId) return;
+  // Aimed consumables (incendiary): close the inventory overlay, switch the
+  // input controllers into unified aim mode, and wait for the next direction.
+  // Crew.useConsumable will be called from `resolveAimedUseItem` once the
+  // aim direction is in.
+  let descriptor: Item;
+  try {
+    descriptor = getItemById(itemId) as Item;
+  } catch (err) {
+    flash(`USE FAILED: ${errorMessage(err)}`);
+    return;
+  }
+  if (descriptor.needsAim) {
+    if (!run.player.canAfford(AP_COST.INTERACT)) {
+      // Cheap pre-check: don't strand the player in aim mode if `useConsumable`
+      // will reject the commit anyway. Crew's `canAfford(AP_COST.INTERACT)`
+      // remains the source of truth at commit time.
+      flash('USE FAILED: insufficient AP.');
+      return;
+    }
+    pendingAimItemId = itemId;
+    itemInventoryEl.hide();
+    setInputAim(AIM_KIND.USE_ITEM);
+    flash(`AIM ${descriptor.label.toUpperCase()} — pick a direction (Esc to cancel).`);
+    return;
+  }
+  try {
+    const result = run.player.useConsumable(itemId);
+    applyUseConsumableResult(result, run);
+  } catch (err) {
+    flash(`USE FAILED: ${errorMessage(err)}`);
+    return;
+  }
+  itemInventoryEl.hide();
+  paint();
+  if (run.player.ap === 0) {
+    advanceTurn();
+  }
+}
+
+/**
+ * Common world-side effects for a `useConsumable` result. Split out so the
+ * direct (non-aim) inventory flow and the aimed-throw flow share one place
+ * to translate Crew's pure descriptors into grid mutations.
+ */
+function applyUseConsumableResult(
+  result: ReturnType<NonNullable<Run['player']>['useConsumable']>,
+  run: Run
+): void {
+  if (!run.world || !run.player) throw new Error('[shell] applyUseConsumableResult: no scene');
+  if (result.type === 'stim') {
+    const healed = (result as { healed: number }).healed;
+    flash(
+      `Used STIM — healed ${healed} HP (now ${run.player.hp}/${run.player.maxHp}). ${run.player.ap} AP left.`
+    );
+    return;
+  }
+  if (result.type === 'smoke') {
+    const { cx, cy, radius } = result as { cx: number; cy: number; radius: number };
+    if (!Number.isInteger(cx) || !Number.isInteger(cy) || !Number.isInteger(radius)) {
+      throw new Error('[shell] smoke consumable returned invalid placement data');
+    }
+    const overlays = placeSmoke(run.world.grid, cx, cy, radius);
+    activeSmokeOverlays.push(...overlays);
+    recomputeVision();
+    flash(`Used SMOKE CHARGE — LOS blocked in radius ${radius}. ${run.player.ap} AP left.`);
+    return;
+  }
+  if (result.type === 'incendiary') {
+    const { cx, cy } = result as { cx: number; cy: number };
+    if (!Number.isInteger(cx) || !Number.isInteger(cy)) {
+      throw new Error('[shell] incendiary consumable returned invalid placement data');
+    }
+    // `placeHazardCluster` only stamps onto FLOOR tiles inside bounds — if
+    // the target is on/past the map edge or buried in a wall, the cluster
+    // simply finds zero candidates and stamps nothing. We've already paid
+    // AP and consumed the charge in Crew.useConsumable; the LOS pre-check
+    // in `resolveAimedUseItem` is what protects the player from "throw
+    // through a wall and lose your bomb."
+    const stamped = placeHazardCluster(run.world, { x: cx, y: cy }, run.rng);
+    if (stamped === 0) {
+      flash(`Used INCENDIARY — bomb landed on hard cover; no fire took. ${run.player.ap} AP left.`);
+    } else {
+      flash(
+        `Used INCENDIARY — ${stamped} tile${stamped === 1 ? '' : 's'} ignited. ${run.player.ap} AP left.`
+      );
+    }
+    recomputeVision();
+    return;
+  }
+  if (result.type === 'breach') {
+    const { tx, ty } = result as { tx: number; ty: number };
+    if (!Number.isInteger(tx) || !Number.isInteger(ty)) {
+      throw new Error('[shell] breaching charge returned invalid target data');
+    }
+    run.world.placeBreachingCharge(tx, ty);
+    flash(`BREACHING CHARGE planted. Detonates end of turn. ${run.player.ap} AP left.`);
+    recomputeVision();
+    return;
+  }
+  throw new Error(`[shell] applyUseConsumableResult: unknown result.type "${result.type}"`);
+}
+
+/**
+ * Resolve an aimed `use-item { dx, dy }` intent. Pairs the keymap's direction
+ * pick with the shell's stashed `pendingAimItemId` and runs the LOS-clear
+ * pre-check before mutating state. Called from `applyIntent`'s onUseItem
+ * callback.
+ */
+function resolveAimedUseItem(aim: { dx: number; dy: number }, run: Run): void {
+  if (!run.world || !run.player) throw new Error('[shell] resolveAimedUseItem: no scene');
+  // P3.M3.6: items are meat gear; the inventory gate blocks new aims while
+  // jacked in, but an aim pending across the jack-in interact must also die.
+  if (isJackedIn(run)) {
+    pendingAimItemId = null;
+    flash('USE FAILED: jacked in — your gear is back in Meatspace.');
+    resetInputModes();
+    return;
+  }
+  const itemId = pendingAimItemId;
+  if (!itemId) {
+    // Direction press arrived without a stashed item — shouldn't be reachable
+    // (the keymap only emits use-item from MODE.AIM / use-item aimKind, which
+    // only the shell can enter), but crash loud if it does so the wiring bug
+    throw new Error('[shell] use-item intent received without pendingAimItemId');
+  }
+  pendingAimItemId = null;
+  if (itemId === ITEM_ID.INCENDIARY) {
+    // LOS-clear-target pre-check: the throw lands at
+    // `player + dir * INCENDIARY_THROW_DIST`. If LOS from the thrower to
+    // that tile is blocked (or the tile is out of bounds), refuse the
+    // throw *before* spending AP / consuming the bomb.
+    const cx = run.player.x + aim.dx * INCENDIARY_THROW_DIST;
+    const cy = run.player.y + aim.dy * INCENDIARY_THROW_DIST;
+    if (!run.world.grid.inBounds(cx, cy)) {
+      flash('USE FAILED: target is off the map.');
+      paint();
+      return;
+    }
+    const blockers = run.world.blockerKeys();
+    if (!hasLineOfSight(run.world.grid, run.player.x, run.player.y, cx, cy, { blockers })) {
+      flash('USE FAILED: target is behind cover.');
+      paint();
+      return;
+    }
+  }
+  if (itemId === ITEM_ID.BREACHING_CHARGE) {
+    const tx = run.player.x + aim.dx * BREACHING_CHARGE_RANGE;
+    const ty = run.player.y + aim.dy * BREACHING_CHARGE_RANGE;
+    const plantCheck = run.world.canPlaceBreachingCharge(tx, ty);
+    if (!plantCheck.ok) {
+      const msg =
+        plantCheck.reason === 'blocked'
+          ? 'USE FAILED: need clear ground to plant.'
+          : plantCheck.reason === 'occupied' || plantCheck.reason === 'charge-present'
+            ? 'USE FAILED: that tile is blocked.'
+            : 'USE FAILED: target is off the map.';
+      flash(msg);
+      paint();
+      return;
+    }
+  }
+  try {
+    const result = run.player.useConsumable(itemId, aim);
+    applyUseConsumableResult(result, run);
+  } catch (err) {
+    flash(`USE FAILED: ${errorMessage(err)}`);
+    paint();
+    return;
+  }
+  paint();
+  if (run.player.ap === 0) {
+    advanceTurn();
+  }
+}
+
+function handlePersist() {
+  if (!campaign || degrading) return;
+  dataStore.setCampaign(snapshotCampaign(campaign));
+}
+
+function presentEndedCampaignOverlay(c: Campaign): void {
+  const summary = dataStore.archiveCampaign(buildCampaignSummary(c, new Date().toISOString()));
+  gameOverEl.setSummary(summary);
+}
+
+function presentCampaignEnd(c: Campaign): void {
+  presentEndedCampaignOverlay(c);
+  renderShell();
+}
+
+function finishEndedCampaign(): void {
+  dataStore.deleteCampaign();
+  startFreshCampaign();
+}
+
+/**
+ * Stage one result for settlement. Non-terminal jobs show `<crash-dump>`;
+ * terminal outcomes are settled immediately by `handleResult` and route to
+ * the Chronicle-backed `<game-over>` screen.
+ */
+function pushPendingJobResultOverlay(telemetry: Partial<RunTelemetry> & { outcome?: unknown }) {
+  const tel = { ...telemetry };
+  const outcome = tel.outcome;
+  if (outcome !== 'death' && outcome !== 'exit') {
+    throw new Error(`[shell] invalid job outcome for debrief overlay: "${outcome}"`);
+  }
+  pendingJobResult = {
+    outcome,
+    telemetry: { ...tel, outcome } as RunTelemetry & { outcome: Outcome },
+  };
+  crashEl.setTelemetry({
+    ...tel,
+    outcome,
+    cause: tel.cause ?? undefined,
+  });
+}
+
+function pendingResultEndsCampaign(result: PendingJobResult): boolean {
+  if (!campaign) return false;
+  return willEndCampaignAfterResult(
+    campaign,
+    result.outcome,
+    result.outcome === 'exit' && result.telemetry.objectiveComplete !== false
+  );
+}
+
+function handleResult({ outcome, telemetry }: RunResult) {
+  if (degrading) return;
+  pushPendingJobResultOverlay({
+    ...telemetry,
+    outcome: telemetry?.outcome ?? outcome,
+  });
+  if (pendingJobResult && pendingResultEndsCampaign(pendingJobResult)) {
+    settlePendingJobResult();
+    return;
+  }
+  renderShell();
+}
+
+function currentScene(): ShellScene | null {
+  if (!campaign) return null;
+  return campaign.activeRun ?? campaign;
+}
+
+/**
+ * Wire the confirmation callbacks a Run raises mid-combat. Callbacks do not
+ * persist, so this runs at deploy AND on campaign resume — a restored run
+ * without them would silently skip both confirmations (the no-callback
+ * harness fallback).
+ */
+function wireRunConfirmations(run: Run): void {
+  run.onAbortRequested = () => {
+    confirmationModalEl.showModal(
+      `Objective incomplete. Abort extraction?\n\nYou will lose all rewards and take a REP ${REP.ABORT_PENALTY} penalty.`,
+      'abort-run'
+    );
+  };
+  run.onJackOutRequested = () => {
+    confirmationModalEl.showModal(
+      'Objective incomplete. Jack out anyway?\n\nThe link will burn — you cannot re-enter the grid this run.',
+      'jack-out-early'
+    );
+  };
+  run.onJackInPresent = () => {
+    sceneListenerController.rewire();
+    recomputeVision();
+    flash('LINK ESTABLISHED — entering // THE GRID //.');
+    paint();
+  };
+  run.onJackOutPresent = () => completeJackOutShellSwap();
+}
+
+function resumeCampaign(record: CampaignSnapshot | unknown) {
+  try {
+    campaign = restoreCampaign(record, {
+      onPersist: () => handlePersist(),
+      onResult: handleResult,
+    });
+    if (campaign.activeRun) {
+      wireRunConfirmations(campaign.activeRun);
+    }
+    if (campaign.activeRun?.state === RUN_STATE.COMBAT) {
+      vision.resetFogState();
+      vision.restoreSeen(campaign.activeRun.mapSeenKeys());
+    }
+    rewireSceneListeners();
+    recomputeVision();
+    if (campaign.activeRun?.state === RUN_STATE.BRIEFING && campaign.activeRun.contract) {
+      briefingEl.setContract(campaign.activeRun.contract);
+      briefingEl.setCrew(campaign.crew);
+    }
+    resumePendingCombatSliceIfNeeded();
+    const resumeFlashMessage = `RESUMED — crew ${campaign.crew.filter(member => !member.flatlined).length} active.`;
+    if (campaign.state === CAMPAIGN_STATE.ENDED) {
+      pendingJobResult = null;
+      presentEndedCampaignOverlay(campaign);
+      flash(
+        campaign.endReason === 'clock-expired'
+          ? 'WINDOW CLOSED — Score contract went cold.'
+          : campaign.endReason === 'score-complete'
+            ? 'SCORE COMPLETE — campaign archived.'
+            : 'CAMPAIGN ENDED — this save has reached a terminal state.'
+      );
+      renderShell();
+    } else if (campaign.activeRun?.state === RUN_STATE.RESULT) {
+      pushPendingJobResultOverlay({ ...campaign.activeRun.telemetry });
+      if (pendingJobResult && pendingResultEndsCampaign(pendingJobResult)) {
+        settlePendingJobResult();
+      } else {
+        flash('RESUMED — mission debrief.');
+        renderShell();
+      }
+    } else if (campaign.state === CAMPAIGN_STATE.HUB && campaign.curator) {
+      renderShell();
+      if (!presentHubRevealIfAny(resumeFlashMessage)) {
+        flash(resumeFlashMessage);
+      }
+      currentJobOptions = generateCurrentJobOptions();
+    } else {
+      flash(resumeFlashMessage);
+      renderShell();
+    }
+  } catch (err) {
+    console.error('[shell] failed to restore saved campaign', err);
+    dataStore.deleteCampaign();
+    flash('CAMPAIGN SAVE CORRUPT — starting fresh.');
+    startFreshCampaign();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Intent handling
+// ---------------------------------------------------------------------------
+
+function isConfirmationDialogOpen(el: HTMLElement | null | undefined): boolean {
+  const dialog = el?.shadowRoot?.querySelector('dialog');
+  return Boolean(dialog?.open);
+}
+
+function presentQuitCampaignConfirm() {
+  if (!campaign) return;
+  if (isConfirmationDialogOpen(confirmationModalEl)) return;
+  confirmationModalEl.showModal(
+    'Delete this campaign and all progress? This cannot be undone.',
+    'quit-campaign'
+  );
+}
+
+function performQuitCampaign(): void {
+  if (!campaign) return;
+  keyHelpEl.hide();
+  briefingEl.hide();
+  hideResultOverlays();
+  crewRosterEl.hide();
+  finnShopEl.hide();
+  clinicModalEl.hide();
+  itemInventoryEl.hide();
+
+  pendingJobResult = null;
+  dataStore.deleteCampaign();
+  startFreshCampaign();
+  flash('Campaign deleted — new campaign.');
+  canvas.focus();
+}
+
+function handleInputModeChange(): void {
+  const state = activeInputState();
+  if (state.mode !== MODE.LOOK) return;
+  if (isCorpControlsLocked()) {
+    resetInputModes();
+    flash('HOSTILES ACTIVE — controls locked until security finishes.');
+    return;
+  }
+  enterLookMode();
+}
+
+function enterLookMode(): void {
+  const run = currentScene();
+  if (!run?.world || !run.player) return;
+  if (lookCursor) return;
+  const actor = activeActorOf(run);
+  if (!actor) return;
+  lookCursor = { x: actor.x, y: actor.y };
+  keyboard.mode = MODE.LOOK;
+  keyboard.aimKind = null;
+  if (touchPadEl.mode !== MODE.LOOK) touchPadEl.setMode(MODE.LOOK);
+  flash('LOOK — move cursor (Esc to cancel).');
+}
+
+function exitLookMode(): void {
+  lookCursor = null;
+  resetInputModes();
+}
+
+function isCorpControlsLocked(): boolean {
+  const run = currentScene();
+  return run?.state === RUN_STATE.COMBAT && run.queue?.currentFaction !== FACTION.PLAYER;
+}
+
+function handleLookMove(dx = 0, dy = 0): void {
+  if (isCorpControlsLocked()) {
+    flash('HOSTILES ACTIVE — controls locked until security finishes.');
+    return;
+  }
+  const run = currentScene();
+  if (!run?.world || !run.player) return;
+  // P3.M3.6: the look cursor roams whichever grid is on screen.
+  const world = activeWorldOf(run);
+  const actor = activeActorOf(run);
+  if (!world || !actor) return;
+  const fog = activeVisionField(run);
+  if (!lookCursor) {
+    lookCursor = { x: actor.x, y: actor.y };
+  }
+  const tx = Math.max(0, Math.min(world.grid.width - 1, lookCursor.x + dx));
+  const ty = Math.max(0, Math.min(world.grid.height - 1, lookCursor.y + dy));
+  if (run.state === RUN_STATE.COMBAT && !fog.hasSeen(tx, ty)) {
+    flash("You haven't seen that tile.");
+    return;
+  }
+  lookCursor = { x: tx, y: ty };
+  const line = describeTileAt(world, tx, ty, {
+    vision: run.state === RUN_STATE.COMBAT ? fog : undefined,
+    showStats: true,
+  });
+  if (line) flash(line);
+}
+
+export function handleIntent(intent: Intent): void {
+  if (intent?.type === 'quit-campaign') {
+    resetInputModes();
+    if (!campaign) return;
+    presentQuitCampaignConfirm();
+    return;
+  }
+
+  if (intent?.type === 'look-move') {
+    handleLookMove(intent.dx, intent.dy);
+    return;
+  }
+
+  if (intent?.type === 'cancel' && lookCursor) {
+    exitLookMode();
+    return;
+  }
+
+  const run = currentScene();
+  if (!run) return;
+  // BRIEFING / RESULT swallow gameplay intents — JACK IN / NEW RUN drive
+  // those transitions through the DOM buttons. Cancel is still valid (it
+  // clears any stuck aim mode, per the cross-input cancel rule).
+  if (
+    run.state === RUN_STATE.BRIEFING ||
+    run.state === RUN_STATE.RESULT ||
+    run.state === CAMPAIGN_STATE.ENDED
+  ) {
+    if (intent?.type === 'cancel') {
+      resetInputModes();
+    }
+    return;
+  }
+
+  if (!run.world || !run.player || !run.queue) {
+    throw new Error(`[shell] state "${run.state}" is missing playable scene wiring`);
+  }
+
+  // P3.M3.6: intents drive whoever the player is being — the crew body in
+  // Meatspace, the avatar on the grid (same queue either way).
+  const intentWorld = activeWorldOf(run);
+  const intentActor = activeActorOf(run);
+  if (!intentWorld || !intentActor) {
+    throw new Error(`[shell] state "${run.state}" has no active world/actor for intents`);
+  }
+
+  applyIntent(intent, {
+    world: intentWorld,
+    player: intentActor as Parameters<typeof applyIntent>[1]['player'],
+    queue: run.queue,
+    rng: run.rng,
+    // Capture the action line for the next paint(); see lastActionLine docs.
+    log: (line: string) => flash(line),
+    advanceTurn,
+    resetInputModes,
+    onUseItem: (aim: { dx: number; dy: number }) => {
+      resolveAimedUseItem(aim, run as Run);
+    },
+    onCorpseSalvaged: entity => {
+      activeVisionField(run).forgetCorpse(entity);
+    },
+    keyItems: [...(campaign?.keyItems ?? []), ...(run as Run).keyItems],
+    onKeycardCollected: kc => {
+      if (kc.siteId) {
+        // Campaign-scoped: persists across runs.
+        if (campaign?.keyItems.some(k => k.id === kc.id)) {
+          return;
+        }
+        campaign?.addKeyItem({ id: kc.id, label: kc.label, doorId: kc.doorId, siteId: kc.siteId });
+      } else {
+        // Run-scoped: lives only in this run, discarded on run end.
+        (run as Run).addKeyItem({ id: kc.id, label: kc.label, doorId: kc.doorId });
+      }
+    },
+    onSecuredInteract: handleSecuredInteract,
+    onPlayerAction: (actionName: string) => {
+      switch (actionName) {
+        case PLAYER_ACTIONS.INVENTORY:
+          // Inventory opens in Hub *and* combat. In combat we still
+          // restrict to the player's turn so peeking doesn't dodge corp
+          // tempo; in Hub there's no turn queue gating to worry about.
+          if (campaign?.state === CAMPAIGN_STATE.COMBAT) {
+            if (run.state !== RUN_STATE.COMBAT || run.queue?.currentFaction !== FACTION.PLAYER) {
+              flash('Inventory is only available on your turn.');
+              return;
+            }
+            // P3.M3.6: the avatar has no pockets — gear stays with the body
+            // until the P3.M4 simstim flip makes split control real.
+            if (isJackedIn(run)) {
+              flash('Jacked in — your meatspace gear is out of reach.');
+              return;
+            }
+          }
+          presentItemInventory();
+          break;
+        case PLAYER_ACTIONS.INTERACT:
+          handleInteract();
+          break;
+        case PLAYER_ACTIONS.REACHED_EXIT:
+          if (campaign?.state === CAMPAIGN_STATE.HUB) {
+            flash('Curator: Hang tight! Come talk to me to claim a contract.');
+          }
+          // Moving onto an extraction tile synchronously emits the run result.
+          // Score settlement may therefore clear the active run and tear down
+          // the campaign world before this callback resumes. Only advance when
+          // the captured scene is still playable (incomplete abort/escort wait,
+          // or the Hub's decorative exit tile).
+          if (run.state === RUN_STATE.COMBAT || run.state === CAMPAIGN_STATE.HUB) {
+            advanceTurn();
+          }
+          break;
+      }
+    },
+  });
+}
+
+/**
+ * Pacing between drone actions when the corp turn is animated step-by-step.
+ * Tuned just above MUZZLE_FLASH duration so the firing flash decays cleanly
+ * before the same drone takes its next action (move, second shot, etc.) —
+ * the original user-reported bug where a "fire then move" turn left the flash
+ * stranded on the tile the drone had just vacated.
+ */
+const CORP_ACTION_DELAY_MS = 130;
+const PLAYER_AFTERMATH_ACTION_DELAY_MS = 130;
+
+function driveCombatTurnPipeline(run: Run, options: { resumeFromCorpSlice?: boolean } = {}): void {
+  if (degrading) return;
+  if (!run.world || !run.queue) {
+    throw new Error(`[shell] cannot advance turn without world/queue in state "${run.state}"`);
+  }
+  const world = run.world;
+  const queue = run.queue;
+  advanceFromPlayerTurn({
+    resumeFromCorpSlice: options.resumeFromCorpSlice,
+    queue,
+    world,
+    rng: run.rng,
+    isTerminal: () => run.state === RUN_STATE.RESULT,
+    drivePlayerAftermath: ({ onStep, onFinish }) => {
+      const finishMeatAftermath = () => {
+        if (degrading) return;
+        clearBreachBlastOverlay(false);
+        const layer = cyberLayerOf(run);
+        if (!layer) {
+          onFinish();
+          return;
+        }
+        drivePlayerAftermath({
+          world: layer.world,
+          rng: run.rng,
+          onStep,
+          onFinish,
+          animLock,
+          stepDelayMs: PLAYER_AFTERMATH_ACTION_DELAY_MS,
+          lockMarginMs: ANIMATION_DURATIONS.MUZZLE_FLASH,
+          player: layer.avatar,
+          schedule: scheduleCombatPump,
+        });
+      };
+      drivePlayerAftermath({
+        world,
+        rng: run.rng,
+        onStep,
+        onFinish: finishMeatAftermath,
+        animLock,
+        stepDelayMs: PLAYER_AFTERMATH_ACTION_DELAY_MS,
+        lockMarginMs: ANIMATION_DURATIONS.MUZZLE_FLASH,
+        rep: campaign?.rep,
+        player: run.player,
+        schedule: scheduleCombatPump,
+      });
+    },
+    onCorpTurnReady: () => {
+      if (degrading) return;
+      clearBreachBlastOverlay(false);
+      recomputeVision();
+      paint();
+    },
+    onPlayerAftermathStep: step => {
+      if (degrading) return;
+      const scene = currentScene();
+      // P3.M3.6: aftermath is a Meatspace phase — while jacked in it still
+      // *applies*, but the canvas is showing the grid, so skip its
+      // presentation (overlays/shake/log lines).
+      const jacked = isJackedIn(scene);
+      const cyberLayer = cyberLayerOf(scene);
+      const isCyberStep =
+        cyberLayer !== null &&
+        step.type === 'overridden-drone' &&
+        cyberLayer.world.entities.has(step.entity.id);
+      if (step.type === 'breach-detonate' && !jacked) {
+        showBreachBlastOverlay(step.charge.x, step.charge.y);
+        if (scene?.player && vision.isVisible(step.charge.x, step.charge.y)) {
+          triggerShake(stageEl);
+          animLock.push(ANIMATION_DURATIONS.SHAKE);
+        }
+      }
+      if (
+        isCyberStep &&
+        cyberLayer &&
+        isPlayerAftermathStepLogVisible(
+          step,
+          (x, y) => cyberVision.isVisible(x, y),
+          cyberLayer.avatar.id
+        )
+      ) {
+        for (const line of formatPlayerAftermathStepLogLines(step)) {
+          flash(line);
+        }
+      } else if (
+        !jacked &&
+        scene?.player &&
+        isPlayerAftermathStepLogVisible(step, (x, y) => vision.isVisible(x, y), scene.player.id)
+      ) {
+        for (const line of formatPlayerAftermathStepLogLines(step)) {
+          flash(line);
+        }
+      }
+      paint();
+    },
+    driveCorpTurn: ({ onFinish }) => {
+      runCorpTurn(() => {
+        if (degrading) return;
+        onFinish();
+      });
+    },
+    onPlayerTurnReady: () => {
+      if (degrading) return;
+      // Clear any smoke from last turn before the player acts.
+      if (activeSmokeOverlays.length > 0) {
+        clearSmoke(world.grid, activeSmokeOverlays);
+        activeSmokeOverlays = [];
+      }
+      // Stealth & vision may both have changed during the corp turn.
+      recomputeVision();
+      paint();
+    },
+  });
+}
+
+function advanceTurn(): void {
+  if (degrading) return;
+  const scene = currentScene();
+  if (!scene) return;
+  if (!scene.world || !scene.queue) {
+    throw new Error(`[shell] cannot advance turn without world/queue in state "${scene.state}"`);
+  }
+
+  if (isRun(scene)) {
+    driveCombatTurnPipeline(scene);
+    return;
+  }
+
+  // Hub — no corp actors; sync PLAYER→CORP→PLAYER flip refreshes operator AP.
+  advanceFromPlayerTurn({
+    queue: scene.queue,
+    world: scene.world,
+    rng: scene.rng,
+    isTerminal: () => false,
+    drivePlayerAftermath: ({ onFinish }) => onFinish(),
+    driveCorpTurn: ({ onFinish }) => onFinish(),
+    onPlayerTurnReady: () => paint(),
+  });
+}
+
+/**
+ * Autosave fires at the player→corp `turn:ended` before the animated aftermath
+ * and corp slice run. On cold resume (or fault recovery that reloads that
+ * checkpoint), kick the pipeline from the corp slice without flipping the
+ * queue again.
+ */
+function resumePendingCombatSliceIfNeeded(): void {
+  const run = campaign?.activeRun;
+  if (!run || run.state !== RUN_STATE.COMBAT || !run.world || !run.queue) return;
+  if (run.queue.currentFaction === FACTION.PLAYER) return;
+  driveCombatTurnPipeline(run, { resumeFromCorpSlice: true });
+}
+
+/**
+ * Kick off the animated corp turn. Delegates to `corpTurnDriver.runCorpTurn`,
+ * which iterates each corp entity's `takeTurnSteps` generator one yield at
+ * a time, paints between each, and fires `onFinish` once every generator
+ * drains (or immediately when the world has zero corp entities — hub, or a
+ * combat map the player has cleared). The driver lives in `/src/game/` so
+ * its state machine is testable under `node --test`.
+ */
+function runCorpTurn(onFinish: () => void): void {
+  if (degrading) return;
+  maybeDevFault('corp');
+  const run = currentScene();
+  if (!run) return;
+  if (!(run instanceof Run)) return;
+  if (!run.world) {
+    throw new Error(`[shell] cannot drive corp turn without world in state "${run.state}"`);
+  }
+  // P3.M3.6: while the Decker is jacked in, the corp slice chains two
+  // driver passes — meat hostiles on the meat world (silent: the canvas is
+  // showing the grid), then ICE on the cyber world. Both consume the shared
+  // run rng in this fixed order, keeping the turn deterministic. If the meat
+  // pass flatlines the body the driver bails terminally and the ICE pass
+  // (correctly) never runs.
+  const icePass = () => {
+    if (degrading) return;
+    const layer = cyberLayerOf(currentScene());
+    if (!layer) {
+      onFinish();
+      return;
+    }
+    driveCorpTurn({
+      run: { state: run.state ?? '', world: layer.world, rng: run.rng },
+      corpFaction: FACTION.CORP,
+      paint,
+      animLock,
+      actionDelayMs: CORP_ACTION_DELAY_MS,
+      lockMarginMs: ANIMATION_DURATIONS.MUZZLE_FLASH,
+      onFinish,
+      schedule: scheduleCombatPump,
+      shouldAnimateStep: (entityId: string, step: TurnActionStep) => {
+        if (degrading) return true;
+        return isCorpTurnStepVisibleToPlayer(layer.world, layer.avatar.id, entityId, step, (x, y) =>
+          cyberVision.isVisible(x, y)
+        );
+      },
+      onStep: (entityId: string, step: TurnActionStep) => {
+        if (degrading) return;
+        const resolve = (id: string) => resolveEntityLabel(id, layer.world.entities);
+        const line = formatCorpTurnStep(resolve(entityId), step, resolve);
+        if (
+          !line ||
+          !isCorpTurnStepLogVisibleToPlayer(layer.world, layer.avatar.id, entityId, step, (x, y) =>
+            cyberVision.isVisible(x, y)
+          )
+        ) {
+          return;
+        }
+        flash(line);
+      },
+    });
+  };
+
+  driveCorpTurn({
+    run: {
+      state: run.state ?? '',
+      world: run.world,
+      rng: run.rng,
+    },
+    corpFaction: run.hostileFaction,
+    paint,
+    animLock,
+    actionDelayMs: CORP_ACTION_DELAY_MS,
+    lockMarginMs: ANIMATION_DURATIONS.MUZZLE_FLASH,
+    onFinish: icePass,
+    schedule: scheduleCombatPump,
+    shouldAnimateStep: (entityId: string, step: TurnActionStep) => {
+      if (degrading) return true;
+      const scene = currentScene();
+      if (!scene?.world || !scene.player) return true;
+      // Jacked in: meat steps still *apply*, but the canvas is showing the
+      // grid — drain them silently rather than pacing invisible frames.
+      if (isJackedIn(scene)) return false;
+      return isCorpTurnStepVisibleToPlayer(scene.world, scene.player.id, entityId, step, (x, y) =>
+        vision.isVisible(x, y)
+      );
+    },
+    onStep: (entityId: string, step: TurnActionStep) => {
+      if (degrading) return;
+      const scene = currentScene();
+      if (!scene?.world || !scene.player) return;
+      if (isJackedIn(scene)) {
+        paintPip();
+        const resolve = (id: string) => resolveEntityLabel(id, scene.world!.entities);
+        const line = formatCorpTurnStep(resolve(entityId), step, resolve);
+        if (
+          line &&
+          isCorpTurnStepLogVisibleToPlayer(scene.world, scene.player.id, entityId, step, (x, y) =>
+            vision.isVisible(x, y)
+          )
+        ) {
+          flash(line);
+        }
+        return;
+      }
+      const resolve = (id: string) => resolveEntityLabel(id, scene.world!.entities);
+      const line = formatCorpTurnStep(resolve(entityId), step, resolve);
+      if (
+        !line ||
+        !isCorpTurnStepLogVisibleToPlayer(scene.world, scene.player.id, entityId, step, (x, y) =>
+          vision.isVisible(x, y)
+        )
+      ) {
+        return;
+      }
+      flash(line);
+    },
+  });
+}
+
+/*
+ * `advanceFromPlayerTurn` owns the final CORP→PLAYER queue transition; the
+ * shell callback above only refreshes presentation state after that happens.
+ */
+
+function handleInteract(): void {
+  if (!campaign) return;
+  // Combat interact: check for adjacent lootable corpses first.
+  if (campaign.state === CAMPAIGN_STATE.COMBAT && campaign.activeRun?.state === RUN_STATE.COMBAT) {
+    handleCombatInteract();
+    return;
+  }
+  if (campaign.state !== CAMPAIGN_STATE.HUB) {
+    flash('Nothing to interact with here.');
+    return;
+  }
+  if (campaign.player && campaign.finn && isChebyshevAdjacent(campaign.player, campaign.finn)) {
+    flash('FINN — browse the shop.');
+    presentFinnShop();
+    return;
+  }
+  if (campaign.player && campaign.clinic && isChebyshevAdjacent(campaign.player, campaign.clinic)) {
+    flash('PATCH — clinic services.');
+    presentClinic();
+    return;
+  }
+  if (
+    campaign.player &&
+    campaign.terminal &&
+    isChebyshevAdjacent(campaign.player, campaign.terminal)
+  ) {
+    if (!isTerminalAccessible(campaign.hubReveals)) {
+      flash('TERMINAL — access denied. Systems locked.');
+      return;
+    }
+    flash('TERMINAL — crew roster.');
+    presentCrewRoster();
+    return;
+  }
+  if (
+    !campaign.player ||
+    !campaign.curator ||
+    !isChebyshevAdjacent(campaign.player, campaign.curator)
+  ) {
+    const hints = ['Curator (contract)'];
+    if (campaign.finn) hints.unshift('Finn (shop)');
+    if (campaign.clinic) hints.push('Patch (clinic)');
+    hints.push('Terminal (roster)');
+    flash(`Step adjacent to ${hints.join(', ')}.`);
+    return;
+  }
+  // Gate: can't take contracts with no deployable crew.
+  if (campaign.crew.filter(m => !m.flatlined).length === 0) {
+    flash('CURATOR: You need a crew first. Try the Terminal.');
+    return;
+  }
+  if (currentJobOptions.length === 0) {
+    currentJobOptions = generateCurrentJobOptions();
+  }
+  flash(
+    currentJobOptions.some(contract => contract.context.recipeId === 'score-final')
+      ? 'CURATOR: Three jobs on the board. The Score is your call.'
+      : 'CURATOR: Three jobs on the board. Pick your trouble.'
+  );
+  presentContractSelect(currentJobOptions);
+}
+
+/**
+ * Combat interact — scan Chebyshev-adjacent tiles for a lootable corpse.
+ * If found: call `player.collectSalvage`, flash result, auto-end turn on AP
+ * exhaustion. If not found: show a no-loot hint.
+ */
+function pulseSecuredInteractable(entity: Entity): boolean {
+  if (!(entity instanceof Interactable) || !entity.secured || !entity.alive) return false;
+  const fired = runInteractSecuredFlash(renderer, paint, entity.x, entity.y, entity.glyph);
+  if (fired) animLock.push(ANIMATION_DURATIONS.INTERACT_SECURED_FLASH);
+  return fired;
+}
+
+function handleSecuredInteract(
+  entity: Interactable,
+  { apExhausted }: { apExhausted: boolean }
+): void {
+  const fired = pulseSecuredInteractable(entity);
+  if (!apExhausted) return;
+  if (fired) {
+    scheduleCombatPump(() => advanceTurn(), ANIMATION_DURATIONS.INTERACT_SECURED_FLASH);
+  } else {
+    advanceTurn();
+  }
+}
+
+function handleCombatInteract(): void {
+  if (!campaign) return;
+  const run = campaign.activeRun;
+  if (!run || !run.player) return;
+  if (!run.world) throw new Error('[shell] active combat run has no world');
+  // P3.M3.6: interact targets the world the player is being in — meat props
+  // for the body, data nodes / the exit port for the avatar.
+  const world = activeWorldOf(run);
+  const player = activeActorOf(run);
+  if (!world || !player) throw new Error('[shell] combat interact requires an active world/actor');
+  // Corpse looting needs pockets — the avatar (no inventory) skips straight
+  // to interactables. ICE leaves no salvage in this slice.
+  const inventory = 'inventory' in player ? (player as Crew).inventory : null;
+  if (!isJackedIn(run) && !inventory) {
+    throw new Error('[shell] combat player inventory is not initialised');
+  }
+  if (inventory) {
+    // Scan the 8 neighbours plus the player's own tile for lootable corpses.
+    for (let dy = -1; dy <= 1; dy++) {
+      for (let dx = -1; dx <= 1; dx++) {
+        const tx = player.x + dx;
+        const ty = player.y + dy;
+        const entity = world.lootableCorpseAt(tx, ty);
+        if (entity && !entity.alive && entity.loot && totalSalvage(entity.loot.salvage) > 0) {
+          if (!player.canAfford(AP_COST.INTERACT)) {
+            flash('Insufficient AP to loot.');
+            return;
+          }
+          // Typed salvage — show pickup total + post-pickup compact wallet.
+          const amount = totalSalvage(entity.loot.salvage);
+          (player as Crew).collectSalvage(world, entity);
+          activeVisionField(run).forgetCorpse(entity);
+          flash(
+            `Salvaged +${amount} — carrying ${formatSalvageCompact(inventory.salvage)}. ${player.ap} AP left.`
+          );
+          paint();
+          if (player.ap === 0) {
+            advanceTurn();
+          }
+          return;
+        }
+      }
+    }
+  }
+
+  const interactable = world.adjacentInteractables(player)[0];
+  if (interactable) {
+    const result = interactable.interact(world, player);
+    flash(result.message);
+    if (
+      result.ok &&
+      interactable instanceof Interactable &&
+      interactable.secured &&
+      interactable.alive
+    ) {
+      handleSecuredInteract(interactable, { apExhausted: player.ap === 0 });
+    } else if (result.ok && player.ap === 0) {
+      advanceTurn();
+    }
+    paint();
+    return;
+  }
+
+  flash('Nothing to interact with nearby.');
+}
+
+// onJackIn removed — combat entry is handled in onBriefingDeploy.
+
+function settlePendingJobResult(): 'ended' | 'hub' {
+  if (!campaign || !pendingJobResult) {
+    throw new Error('settlePendingJobResult requires an active campaign result');
+  }
+  const jobResult = pendingJobResult;
+  const { outcome } = jobResult;
+  pendingJobResult = null;
+  // Extract typed salvage from the deployed crew member's inventory on exit.
+  // Death outcomes pass `undefined`, preserving the existing forfeiture rule.
+  const member = campaign.deployedMemberId
+    ? campaign.getCrewMember(campaign.deployedMemberId)
+    : null;
+  const salvage = member?.inventory?.salvage;
+  const objectiveComplete =
+    outcome === 'exit' ? jobResult.telemetry.objectiveComplete !== false : false;
+  // Apply the clean completion bonus before `onJobEnd`, so the terminal
+  // Chronicle record sees the final Rep value and Hub recruitment gates retain
+  // their existing ordering on non-terminal jobs.
+  if (outcome === 'exit' && objectiveComplete && civilianHarmsThisJob === 0) {
+    const actual = campaign.adjustRep(REP.CLEAN_COMPLETION_BONUS);
+    flash(`REP +${actual}: clean extraction — no civilian casualties.`);
+  }
+  if (outcome === 'exit' && !objectiveComplete) {
+    flash(`ABORT: Objective abandoned. REP ${REP.ABORT_PENALTY}.`);
+  }
+  campaign.onJobEnd({ outcome, salvage, completed: objectiveComplete });
+  if (campaign.state === CAMPAIGN_STATE.ENDED) {
+    presentCampaignEnd(campaign);
+    return 'ended';
+  }
+  if (!presentHubRevealIfAny('HUB — choose the next job.')) {
+    flash('HUB — choose the next job.');
+  }
+  if (!campaign.curator) {
+    throw new Error('settlePendingJobResult: hub not entered — curator is missing.');
+  }
+  currentJobOptions = generateCurrentJobOptions();
+  return 'hub';
+}
+
+function onNewRunRequested(): void {
+  if (!campaign) return;
+  if (pendingJobResult) {
+    if (settlePendingJobResult() === 'ended') return;
+  } else if (campaign.state === CAMPAIGN_STATE.ENDED) {
+    finishEndedCampaign();
+    return;
+  }
+  hideResultOverlays();
+  rewireSceneListeners();
+  recomputeVision();
+  renderShell();
+}
+
+// ---------------------------------------------------------------------------
+// Vision (mirrors the debug harness rule: refresh on every entity move)
+// ---------------------------------------------------------------------------
+
+function rewireSceneListeners(): void {
+  sceneListenerController.rewire();
+}
+
+function completeJackOutShellSwap(): void {
+  sceneListenerController.detachCyber();
+  pipCanvas.hidden = true;
+  flash('LINK DROPPED — back in your body.');
+  recomputeVision();
+  paint();
+}
+
+function recomputeVision(): void {
+  const scene = currentScene();
+  const result = syncVisionFields({ scene, meatVision: vision, cyberVision });
+  if (result.recordMeatSeen && result.meatVisible && scene && isRun(scene)) {
+    applyMeatSeenRecord(scene, result.meatVisible);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Presentation
+// ---------------------------------------------------------------------------
+
+function renderShell(): void {
+  if (!campaign) return;
+  const run = currentScene();
+  const state = run?.state;
+  switch (state) {
+    case CAMPAIGN_STATE.HUB:
+    case RUN_STATE.COMBAT:
+      canvas.hidden = false;
+      briefingEl.hide();
+      hideResultOverlays();
+      break;
+    case RUN_STATE.BRIEFING:
+      // The combined briefing modal handles its own show/hide. If we land
+      // here on resume, re-present the briefing so the player can pick an
+      // operative.
+      canvas.hidden = true;
+      if (!briefingEl.isOpen) {
+        if (!campaign.activeRun?.contract) {
+          throw new Error('[shell] briefing state without an active contract');
+        }
+        briefingEl.setContract(campaign.activeRun.contract);
+        briefingEl.setCrew(campaign.crew);
+        briefingEl.show();
+      }
+      hideResultOverlays();
+      break;
+    case RUN_STATE.RESULT:
+      canvas.hidden = true;
+      briefingEl.hide();
+      gameOverEl.hide();
+      crashEl.show();
+      break;
+    case CAMPAIGN_STATE.ENDED:
+      canvas.hidden = true;
+      briefingEl.hide();
+      crashEl.hide();
+      gameOverEl.show();
+      break;
+    default:
+      throw new Error(`[shell] unknown state "${state}"`);
+  }
+  paint();
+}
+
+function paintPip(): void {
+  const view = resolveSceneView(campaign);
+  if (
+    !view ||
+    view.kind !== 'run' ||
+    view.scene.state !== RUN_STATE.COMBAT ||
+    !shouldShowPip(view.scene)
+  ) {
+    pipCanvas.hidden = true;
+    return;
+  }
+  const run = view.scene;
+  if (!run.world || !run.player) {
+    pipCanvas.hidden = true;
+    return;
+  }
+  pipCanvas.hidden = false;
+  const principalId = campaign?.activeRun?.contract?.context?.principal?.id;
+  pipRenderer.draw(run.world, run.player, {
+    camera: pipCameraFor(run.player, run.world),
+    vision,
+    player: run.player,
+    tileset: 'meat',
+    principalId,
+    hudRows: pipChrome(run.player),
+  });
+}
+
+export function paint(stateHint: InputState = activeInputState()): void {
+  const run = currentScene();
+  if (canvas.hidden) {
+    setStatus(statusLine(stateHint));
+    return;
+  }
+  if (!run || !run.world || !run.player) return;
+  // P3.M3.6: the rendered pair — meat body in Meatspace, avatar on the grid.
+  const world = activeWorldOf(run);
+  const actor = activeActorOf(run);
+  if (!world || !actor) return;
+  const jacked = isJackedIn(run);
+  // Hub is a safe space — no fog of war. Vision is only meaningful during
+  // combat where LOS and drone stealth detection matter.
+  const activeVision = run.state === RUN_STATE.COMBAT ? activeVisionField(run) : undefined;
+  // Breach blasts are a Meatspace effect — never painted onto the grid.
+  const blastOverlayKeys =
+    run.state === RUN_STATE.COMBAT && !jacked && activeBreachBlastOverlayKeys.size > 0
+      ? activeBreachBlastOverlayKeys
+      : undefined;
+  const principalId =
+    run.state === RUN_STATE.COMBAT && !jacked
+      ? campaign?.activeRun?.contract?.context?.principal?.id
+      : undefined;
+  renderer.draw(world, actor, {
+    vision: activeVision,
+    player: actor,
+    blastOverlayKeys,
+    lookCursor,
+    principalId,
+    tileset: activeTileset(run),
+    locationLabel: currentLocationLabel(campaign, run),
+    hudRows: buildHubHudRows(campaign, run),
+    combatHud: buildCombatHudSnapshot(run),
+  });
+  crt.alertTint = run.state === RUN_STATE.COMBAT && world.alarmActive;
+  crt.apply();
+  paintPip();
+  setStatus(statusLine(stateHint));
+}
+
+function statusLine(state: InputState): string {
+  const run = currentScene();
+  if (!run) return '';
+  if (run.state !== RUN_STATE.COMBAT) {
+    corpToneActivityBody = null;
+  }
+  const label = stateLabelForSceneState(run.state);
+  if (!run.player) return label;
+  if (!run.queue) return label;
+
+  let contextHtml = '';
+  let hubIdentity: string | undefined;
+  let combatHud = null;
+  let corpMood = null;
+  let latchedCorpMood = null;
+
+  if (run.state === RUN_STATE.COMBAT) {
+    if (!isRun(run)) {
+      throw new Error('[shell] combat status requires an active run');
+    }
+    combatHud = buildCombatHudSnapshot(run);
+    if (!combatHud) {
+      throw new Error('[shell] combat status requires HUD summary data');
+    }
+    const statusWorld = activeWorldOf(run);
+    const statusActor = activeActorOf(run);
+    const alarm = statusWorld?.alarm;
+    const alertTag = alarm ? formatAlertTag(alarm) : '';
+    const onHazard =
+      statusWorld &&
+      statusActor &&
+      statusWorld.grid.tileAt(statusActor.x, statusActor.y) === TILE.HAZARD;
+    contextHtml = joinStatusParts([formatHazardTag(!!onHazard), alertTag]);
+
+    const jacked = isJackedIn(run);
+    const hintText = proximityHint();
+    if (
+      !hintText &&
+      isHostileTurnSlice(run.state, run.queue.currentFaction, run.hostileFaction, jacked)
+    ) {
+      const corpWorld = activeWorldOf(run);
+      if (!corpWorld) throw new Error('[shell] combat status requires a world');
+      const visibleHostiles = countVisibleCorpEntities(
+        corpWorld.entities.values(),
+        (x: number, y: number) => activeVisionField(run).isVisible(x, y),
+        jacked ? FACTION.CORP : run.hostileFaction
+      );
+      const body = corpTurnStatusBody(visibleHostiles, run.queue.turnNumber);
+      corpMood = { hostileTag: hostileMoodTag(jacked, run.hostileFaction), body };
+    } else if (
+      !hintText &&
+      isPlayerTurnSlice(run.state, run.queue.currentFaction) &&
+      corpToneActivityBody !== null
+    ) {
+      latchedCorpMood = {
+        hostileTag: hostileMoodTag(isJackedIn(run), run.hostileFaction),
+        body: corpToneActivityBody,
+      };
+      corpToneActivityBody = null;
+    }
+  } else {
+    if (!campaign) return label;
+    const repLabel = REP_LABEL.find(b => campaign!.rep >= b.min)?.label ?? 'UNKNOWN';
+    contextHtml = joinStatusParts(
+      formatHubArcStatusLines(campaign)
+        .filter((line): line is string => line !== null)
+        .map(escapeHtml)
+    );
+    hubIdentity = `CREW ${campaign.crew.filter(member => !member.flatlined).length}/${campaign.crew.length} CREDS ${campaign.credits ?? 0} REP ${campaign.rep} (${escapeHtml(repLabel)})`;
+  }
+
+  const { html, nextCorpMoodBody } = formatStatusLine({
+    stateLabel: label,
+    sceneState: run.state,
+    input: state,
+    hasPlayer: !!run.player,
+    hasQueue: !!run.queue,
+    combatHud,
+    contextHtml,
+    hubIdentity,
+    proximityHint: proximityHint() || undefined,
+    corpMood,
+    latchedCorpMood,
+    actionHistory: actionLineHistory,
+    pendingActionCount: pendingActionLineCount,
+  });
+  if (nextCorpMoodBody !== null) {
+    corpToneActivityBody = nextCorpMoodBody;
+  }
+  pendingActionLineCount = 0;
+  return html;
+}
+
+/**
+ * Player-facing nudge for whatever interactable is within reach. Computed
+ * fresh every paint so it always reflects the *current* player position
+ * (vs. caching at action-time, which would let a stale hint linger after a
+ * corp turn shuffled the world).
+ *
+ * When non-empty, the hint takes the upper activity row in the status bar,
+ * bumping the previous action log line. It is *not* pushed into the
+ * rolling logLines buffer — it's a transient, positional display.
+ *
+ * Add a case here when new interactables land (terminals, dropped weapons,
+ * etc.).
+ */
+function proximityHint(): string {
+  const run = currentScene();
+  if (!run || !run.player) return '';
+  if (run.state === CAMPAIGN_STATE.HUB) {
+    if (run.finn && isChebyshevAdjacent(run.player, run.finn)) {
+      return 'FINN — press [Space] to shop.';
+    }
+    if (run.curator && isChebyshevAdjacent(run.player, run.curator)) {
+      return 'CURATOR — press [Space] for a contract.';
+    }
+    if (run.terminal && isChebyshevAdjacent(run.player, run.terminal)) {
+      return 'TERMINAL — press [Space] for roster.';
+    }
+    if (run.clinic && isChebyshevAdjacent(run.player, run.clinic)) {
+      return 'PATCH — press [Space] for clinic.';
+    }
+    if (run.exitTile && isChebyshevAdjacent(run.player, run.exitTile)) {
+      return 'EXIT (¤) one step away.';
+    }
+    return '';
+  }
+  if (run.state === RUN_STATE.COMBAT) {
+    // P3.M3.6: hints follow the active body — meat props for the crew,
+    // nodes/exit port for the avatar.
+    const world = activeWorldOf(run);
+    const p = activeActorOf(run);
+    const jacked = isJackedIn(run);
+    if (world && p) {
+      // Loot hint: adjacent lootable corpses (needs pockets — avatar skips).
+      if (!jacked) {
+        for (let dy = -1; dy <= 1; dy++) {
+          for (let dx = -1; dx <= 1; dx++) {
+            const e = world.lootableCorpseAt(p.x + dx, p.y + dy);
+            if (e && !e.alive && e.loot && totalSalvage(e.loot.salvage) > 0) {
+              return 'SALVAGE nearby — press [Space] to loot.';
+            }
+          }
+        }
+      }
+      const interactable = world.adjacentInteractables(p)[0];
+      if (interactable) {
+        return `${interactable.label.toUpperCase()} nearby — press [Space] to interact.`;
+      }
+    }
+    if (!jacked && run.exitTile && isChebyshevAdjacent(run.player, run.exitTile)) {
+      return 'EXIT (¤) one step away.';
+    }
+  }
+  return '';
+}
+
+/** Stash a one-shot message that the next paint surfaces in the status bar. */
+function flash(line: string): void {
+  const scene = currentScene();
+  if (scene?.state === RUN_STATE.COMBAT && scene.queue?.currentFaction === FACTION.PLAYER) {
+    corpToneActivityBody = null;
+  }
+  actionLineHistory = recordStatusActionLine(actionLineHistory, line);
+  pendingActionLineCount = Math.min(pendingActionLineCount + 1, actionLineHistory.length);
+  const currentActionLine = actionLineHistory[0] ?? '';
+  if (currentActionLine) {
+    logLines.unshift(`> ${currentActionLine}`);
+    if (logLines.length > 20) logLines.splice(20);
+    logContentEl.textContent = logLines.join('\n');
+  }
+}
+
+function setStatus(richText: string): void {
+  if (statusEl) statusEl.innerHTML = richText;
+}
+
+function activeInputState(): InputState {
+  if (touchPadEl && touchPadEl.mode !== MODE.IDLE) {
+    return { mode: touchPadEl.mode, aimKind: touchPadEl.aimKind ?? null };
+  }
+  return { mode: keyboard?.mode ?? MODE.IDLE, aimKind: keyboard?.aimKind ?? null };
+}
+
+function setInputAim(aimKind: AimKind): void {
+  keyboard.mode = MODE.AIM;
+  keyboard.aimKind = aimKind;
+  touchPadEl.setMode(MODE.AIM, aimKind);
+  paint({ mode: MODE.AIM, aimKind });
+}
+
+function resetInputModes(): void {
+  lookCursor = null;
+  keyboard.mode = MODE.IDLE;
+  keyboard.aimKind = null;
+  touchPadEl.setMode(MODE.IDLE);
+  // Clear any half-armed thrown-consumable aim. Esc-cancel from
+  // aim mode, or a cross-controller cancel, must not leave a stashed item
+  // hanging — a later inventory click would otherwise mismatch.
+  pendingAimItemId = null;
+}
+
+// ---------------------------------------------------------------------------
+// Geometry helpers
+// ---------------------------------------------------------------------------
+
+function isChebyshevAdjacent(a: PointLike, b: PointLike): boolean {
+  return chebyshevDistance(a, b) === 1;
+}
+
+function chebyshevDistance(a: PointLike, b: PointLike): number {
+  if (!a || !b) return Infinity;
+  return Math.max(Math.abs(a.x - b.x), Math.abs(a.y - b.y));
+}
+
+// ---------------------------------------------------------------------------
+// Global keys (UI-layer, not routed through keymap.js)
+// ---------------------------------------------------------------------------
+
+/**
+ * Opens <key-help> when Hub/Combat and no blocking modal — same rules as the
+ * `?` shortcut and the header toolbar button.
+ *
+ * @returns {'ok'|'blocking'|'no-scope'|'none'}
+ */
+function tryShowKeyHelpOverlay(): 'ok' | 'blocking' | 'no-scope' | 'none' {
+  if (isAnyBlockingModalOpen()) return 'blocking';
+  const scope = helpScopeForRunState();
+  if (!scope) return 'no-scope';
+  const scene = currentScene();
+  const archetypeId = scene && isRun(scene) ? scene.archetype : undefined;
+  keyHelpEl.setScope(scope, archetypeId);
+  keyHelpEl.show();
+  return 'ok';
+}
+
+/**
+ * `?` toggles the help overlay. Esc, when the help overlay is open, dismisses
+ * it (and we swallow the event so the keymap doesn't also turn it into a
+ * `cancel` intent for whatever aim mode was active).
+ *
+ * `?` is suppressed while any blocking modal owns the foreground — opening
+ * help over a briefing or crew-roster would just stack panels.
+ */
+export function handleGlobalKey(evt: KeyboardEvent): void {
+  if (evt.ctrlKey || evt.metaKey || evt.altKey) return;
+
+  // While <key-help> is open it owns the foreground entirely: `?` and Esc
+  // close it; every other key is swallowed so a held WASD doesn't pump
+  // moves into the game underneath. (Tested manually — gameplay events
+  // routing through this layer was the bug we hit during touchpad
+  // testing too.)
+  if (keyHelpEl.isOpen) {
+    if (evt.key === '?' || evt.key === 'Escape') {
+      evt.preventDefault();
+      evt.stopPropagation();
+      keyHelpEl.hide();
+      return;
+    }
+    // Tab navigation: prevent scroll/focus churn but let <key-help> handle it.
+    if (KeyHelp.isTabNavKey(evt.key)) {
+      evt.preventDefault();
+      return;
+    }
+    // Everything else: block, don't process.
+    evt.preventDefault();
+    evt.stopPropagation();
+    return;
+  }
+
+  if (evt.key !== '?') return;
+  const opened = tryShowKeyHelpOverlay();
+  if (opened === 'ok') {
+    evt.preventDefault();
+    return;
+  }
+  if (opened === 'blocking') {
+    // Briefing / Crash / System start / Resume / Character-select own focus — silently drop
+    // `?` rather than stacking yet another overlay over them.
+    evt.preventDefault();
+  }
+}
+
+function helpScopeForRunState(): HelpScope | null {
+  const run = currentScene();
+  if (!run) return null;
+  if (run.state === CAMPAIGN_STATE.HUB) return 'hub';
+  if (run.state === RUN_STATE.COMBAT) return 'combat';
+  return null;
+}
+
+function isAnyBlockingModalOpen(): boolean {
+  if (contractSelectEl?.isOpen) return true;
+  if (briefingEl?.isOpen) return true;
+  if (crashEl?.isOpen) return true;
+  if (gameOverEl?.isOpen) return true;
+  if (systemStartEl?.isOpen) return true;
+  if (curatorBriefingEl?.isOpen) return true;
+  if (initialRecruitEl?.isOpen) return true;
+  if (crewRosterEl?.isOpen) return true;
+  if (finnShopEl?.isOpen) return true;
+  if (clinicModalEl?.isOpen) return true;
+  if (itemInventoryEl?.isOpen) return true;
+  if (keyHelpEl?.isOpen) return true;
+  if (faultEl?.isOpen) return true;
+  // <confirmation-modal> uses a native <dialog> internally; treat any open
+  // attribute as "blocking".
+  if (isConfirmationDialogOpen(confirmationModalEl)) return true;
+  return false;
+}
diff --git a/src/shell/statusLine.ts b/src/shell/statusLine.ts
new file mode 100644
index 0000000..ac554b1
--- /dev/null
+++ b/src/shell/statusLine.ts
@@ -0,0 +1,181 @@
+import { FACTION } from '../game/constants.js';
+import { CAMPAIGN_STATE } from '../game/Campaign.js';
+import { RUN_STATE } from '../game/Run.js';
+import { aimKindLabel, MODE } from '../input/keymap.js';
+import type { AimKind, Mode } from '../input/keymap.js';
+import { formatCombatHudA11ySummary } from '../render/combatHud.js';
+import type { CombatHudSummaryInput } from '../render/combatHud.js';
+import { statusActionRows } from '../statusActivityRows.js';
+
+export type StatusLineInputState = {
+  mode: Mode;
+  aimKind: AimKind | null;
+};
+
+export type CorpMoodSnapshot = {
+  hostileTag: string;
+  body: string;
+};
+
+export type StatusLineSnapshot = {
+  stateLabel: string;
+  sceneState: string | null | undefined;
+  input: StatusLineInputState;
+  hasPlayer: boolean;
+  hasQueue: boolean;
+  combatHud?: CombatHudSummaryInput | null;
+  contextHtml: string;
+  hubIdentity?: string;
+  proximityHint?: string;
+  /** Hostile-turn mood row — builder sets when queue is on hostile faction. */
+  corpMood?: CorpMoodSnapshot | null;
+  /** Latched mood shown on player slice until flushed. */
+  latchedCorpMood?: CorpMoodSnapshot | null;
+  actionHistory: readonly string[];
+  pendingActionCount: number;
+};
+
+export type StatusLineResult = {
+  html: string;
+  /** Updated latch after rendering hostile-turn mood. */
+  nextCorpMoodBody: string | null;
+};
+
+export function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, char => {
+    switch (char) {
+      case '&':
+        return '&amp;';
+      case '<':
+        return '&lt;';
+      case '>':
+        return '&gt;';
+      case '"':
+        return '&quot;';
+      case "'":
+        return '&#39;';
+      default:
+        return char;
+    }
+  });
+}
+
+export function joinStatusParts(parts: Array<string | null | undefined>): string {
+  return parts
+    .filter(part => part && part.trim().length > 0)
+    .join(' <span class="status-sep">|</span> ');
+}
+
+export function stateLabelForSceneState(state: string | null | undefined): string {
+  if (!state) return 'BOOTING';
+  switch (state) {
+    case CAMPAIGN_STATE.HUB:
+      return '[HUB]';
+    case RUN_STATE.BRIEFING:
+      return '[BRIEFING]';
+    case RUN_STATE.COMBAT:
+      return '[COMBAT]';
+    case RUN_STATE.RESULT:
+      return '[DEBRIEF]';
+    case CAMPAIGN_STATE.ENDED:
+      return '[ENDED]';
+    default:
+      return state;
+  }
+}
+
+export function formatStatusLine(snapshot: StatusLineSnapshot): StatusLineResult {
+  if (!snapshot.hasPlayer || !snapshot.hasQueue) {
+    return { html: snapshot.stateLabel, nextCorpMoodBody: null };
+  }
+
+  const aim =
+    snapshot.input.mode === MODE.AIM && snapshot.input.aimKind
+      ? `AIM ${aimKindLabel(snapshot.input.aimKind)}`
+      : '';
+  const look = snapshot.input.mode === MODE.LOOK ? 'LOOK' : '';
+  const isCombat = snapshot.sceneState === RUN_STATE.COMBAT;
+
+  let combatA11y = '';
+  if (isCombat && snapshot.combatHud) {
+    combatA11y = `<span class="u-sr-only">Combat status: ${escapeHtml(
+      formatCombatHudA11ySummary(snapshot.combatHud)
+    )}</span>`;
+  }
+
+  const modeTag = look && !isCombat ? look : '';
+  const statsInner = isCombat
+    ? joinStatusParts([snapshot.stateLabel, aim, look])
+    : joinStatusParts([snapshot.stateLabel, snapshot.hubIdentity, modeTag]);
+  const stats = `<span class="game-shell__stats">${statsInner}</span>`;
+  const contextRow = `<span class="game-shell__context">${snapshot.contextHtml}</span>`;
+
+  let ephemeral = '';
+  let nextCorpMoodBody: string | null = null;
+
+  if (snapshot.proximityHint) {
+    ephemeral = `<span class="game-shell__activity hint">${escapeHtml(snapshot.proximityHint)}</span>`;
+  } else if (snapshot.corpMood) {
+    const { hostileTag, body } = snapshot.corpMood;
+    nextCorpMoodBody = body;
+    ephemeral = `<span class="game-shell__activity corp"><span class="faction-tag">${hostileTag}</span> — ${body}</span>`;
+  } else if (snapshot.latchedCorpMood) {
+    const { hostileTag, body } = snapshot.latchedCorpMood;
+    ephemeral = `<span class="game-shell__activity corp"><span class="faction-tag">${hostileTag}</span> — ${body}</span>`;
+  }
+
+  const activityRows = statusActionRows(
+    snapshot.actionHistory,
+    snapshot.pendingActionCount,
+    !!ephemeral
+  );
+  const [upper, lower] = activityRows.map(row => {
+    if (row.source === 'ephemeral') return ephemeral;
+    return `<span class="game-shell__activity">${escapeHtml(row.text)}</span>`;
+  });
+
+  return {
+    html: combatA11y + stats + contextRow + upper + lower,
+    nextCorpMoodBody,
+  };
+}
+
+export function formatAlertTag(alarm: {
+  phase: string;
+  holdTurnsRemaining?: number;
+  cooldownTurnsRemaining?: number;
+}): string {
+  if (alarm.phase === 'alert') {
+    return `<span class="alert-tag">ALERT ${alarm.holdTurnsRemaining ?? 0}</span>`;
+  }
+  if (alarm.phase === 'cooldown') {
+    return `<span class="alert-tag">COOL ${alarm.cooldownTurnsRemaining ?? 0}</span>`;
+  }
+  return '';
+}
+
+export function formatHazardTag(onHazard: boolean): string {
+  return onHazard ? '<span class="hazard-tag">▓ HAZARD — move or take damage</span>' : '';
+}
+
+export function hostileMoodTag(jackedIn: boolean, hostileFaction: string): string {
+  return jackedIn ? 'ICE' : hostileFaction.toUpperCase();
+}
+
+/** Whether the queue is on the hostile slice (corp or ICE while jacked in). */
+export function isHostileTurnSlice(
+  sceneState: string | null | undefined,
+  currentFaction: string,
+  hostileFaction: string,
+  jackedIn: boolean
+): boolean {
+  if (sceneState !== RUN_STATE.COMBAT) return false;
+  return jackedIn ? currentFaction === FACTION.CORP : currentFaction === hostileFaction;
+}
+
+export function isPlayerTurnSlice(
+  sceneState: string | null | undefined,
+  currentFaction: string
+): boolean {
+  return sceneState === RUN_STATE.COMBAT && currentFaction === FACTION.PLAYER;
+}
diff --git a/src/shell/visionSync.ts b/src/shell/visionSync.ts
new file mode 100644
index 0000000..204f729
--- /dev/null
+++ b/src/shell/visionSync.ts
@@ -0,0 +1,77 @@
+import { RUN_STATE } from '../game/Run.js';
+import type { Run } from '../game/Run.js';
+import type { CyberspaceLayer } from '../game/cyber/CyberspaceLayer.js';
+import type { Entity } from '../game/Entity.js';
+import type { World } from '../game/World.js';
+import type { VisionField } from '../game/Vision.js';
+import { cyberLayerOf, isRunScene } from './activeView.js';
+import type { ActiveViewScene } from './activeView.js';
+
+export type VisionSyncInput = {
+  scene: ActiveViewScene | null;
+  meatVision: VisionField;
+  cyberVision: VisionField;
+};
+
+export type VisionSyncResult = {
+  /** When set, caller should record map-seen keys on the active run. */
+  recordMeatSeen: boolean;
+  /** Visible keys from the meat recompute — pass to `Run.recordMapSeen`. */
+  meatVisible?: ReadonlySet<string>;
+};
+
+/**
+ * Recompute meat (and cyber, when jacked in) vision fields. Returns hints
+ * for persistence side-effects the shell owns.
+ */
+export function syncVisionFields(input: VisionSyncInput): VisionSyncResult {
+  const { scene, meatVision, cyberVision } = input;
+  if (!scene) return { recordMeatSeen: false };
+
+  let recordMeatSeen = false;
+  let meatVisible: ReadonlySet<string> | undefined;
+
+  if (scene.world && scene.player) {
+    meatVision.recompute(scene.world.grid, scene.player, undefined, {
+      blockers: scene.world.blockerKeys(),
+    });
+    meatVisible = meatVision.visible;
+    if (isRunScene(scene) && scene.state === RUN_STATE.COMBAT) {
+      recordMeatSeen = true;
+    }
+  }
+
+  const layer = cyberLayerOf(scene);
+  if (layer) {
+    cyberVision.recompute(layer.world.grid, layer.avatar, undefined, {
+      blockers: layer.world.blockerKeys(),
+    });
+    layer.recordSeen(cyberVision.visible);
+  }
+
+  return { recordMeatSeen, meatVisible };
+}
+
+export type ActiveWorldPair = {
+  meatWorld: World | null;
+  meatPlayer: Entity | null;
+  layer: CyberspaceLayer | null;
+};
+
+export function meatWorldPair(scene: ActiveViewScene | null): ActiveWorldPair {
+  if (!scene) {
+    return { meatWorld: null, meatPlayer: null, layer: null };
+  }
+  return {
+    meatWorld: scene.world,
+    meatPlayer: scene.player,
+    layer: cyberLayerOf(scene),
+  };
+}
+
+/** Record map-seen on a combat run after meat vision sync. */
+export function applyMeatSeenRecord(run: Run, visible: ReadonlySet<string>): void {
+  if (run.state === RUN_STATE.COMBAT) {
+    run.recordMapSeen(visible);
+  }
+}
diff --git a/sw-core.js b/sw-core.js
index f614c5b..d8bd56c 100644
--- a/sw-core.js
+++ b/sw-core.js
@@ -141,6 +141,15 @@ const CacheConfig = {
       '/src/render/principalTerrainPalettes.js',
       '/src/rng.js',
       '/src/ServiceWorkerManager.js',
+      '/src/shell/activeView.js',
+      '/src/shell/combatHudSnapshot.js',
+      '/src/shell/domTypes.js',
+      '/src/shell/locationHud.js',
+      '/src/shell/sceneListeners.js',
+      '/src/shell/sceneView.js',
+      '/src/shell/statusLine.js',
+      '/src/shell/GameShell.js',
+      '/src/shell/shellRuntime.js',
       '/src/statusActivityRows.js',
     ];
   },
diff --git a/sw-dev.js b/sw-dev.js
index 6098667..8245b48 100644
--- a/sw-dev.js
+++ b/sw-dev.js
@@ -1,5 +1,5 @@
 // Service Worker for Kernel Panic - Development Version
-const VERSION = '0.2.16-dev';
+const VERSION = '0.2.17-dev';
 importScripts(`/sw-core.js?v=${VERSION}`);
 
 const cacheConfig = CacheConfig.create(VERSION);
diff --git a/sw.js b/sw.js
index ed0b0fc..c3d3ae8 100644
--- a/sw.js
+++ b/sw.js
@@ -1,6 +1,6 @@
 // Service Worker for Kernel Panic - Production Version
 // Import shared caching core with cache-busting query parameter
-const VERSION = '0.2.16';
+const VERSION = '0.2.17';
 importScripts(`/sw-core.js?v=${VERSION}`);
 
 const cacheConfig = CacheConfig.create(VERSION);
diff --git a/tests/unit/game/cyber/jackOut.test.ts b/tests/unit/game/cyber/jackOut.test.ts
index 1f1f29a..00c948c 100644
--- a/tests/unit/game/cyber/jackOut.test.ts
+++ b/tests/unit/game/cyber/jackOut.test.ts
@@ -161,6 +161,25 @@ test('burn() on an unlinked port is corrupt state and throws', () => {
 // (tests/harness) → resolve immediately, the `onAbortRequested` posture —
 // locked by the LINK BURNED tests above, which route out with no callback.
 
+test('jackIn invokes onJackInPresent after layer spawns', () => {
+  const run = combatRun();
+  let presented = 0;
+  run.onJackInPresent = () => presented++;
+  jackIn(run);
+  assert.equal(presented, 1);
+});
+
+test('finalize jack-out invokes onJackOutPresent', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  sliceAllNodes(layer);
+  let presented = 0;
+  run.onJackOutPresent = () => presented++;
+  routeOut(layer);
+  assert.equal(presented, 1);
+  assert.equal(run.cyberspace?.phase, 'resolved');
+});
+
 test('Run rejects a non-function onJackOutRequested', () => {
   assert.throws(
     () => new Run({ crewMember: makeDecker(), seed: 1, onJackOutRequested: 'nope' }),
diff --git a/tests/unit/shell/activeView.test.ts b/tests/unit/shell/activeView.test.ts
new file mode 100644
index 0000000..81cab84
--- /dev/null
+++ b/tests/unit/shell/activeView.test.ts
@@ -0,0 +1,108 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { Run } from '../../../src/game/Run.js';
+import { CyberspaceLayer } from '../../../src/game/cyber/CyberspaceLayer.js';
+import { JackInPoint } from '../../../src/game/entities/JackInPoint.js';
+import { VisionField } from '../../../src/game/Vision.js';
+import { buildCrewMember } from '../../../src/game/archetypes/index.js';
+import { OBJECTIVES } from '../../../src/game/hub/Curator.js';
+import { Rng } from '../../../src/rng.js';
+import { testContractContext } from '../game/contractTestUtils.js';
+import {
+  activeActorOf,
+  activeTileset,
+  activeWorldOf,
+  cyberLayerOf,
+  isJackedIn,
+  isRunScene,
+  pickActiveVisionField,
+} from '../../../src/shell/activeView.js';
+import type { World } from '../../../src/game/World.js';
+import type { Entity } from '../../../src/game/Entity.js';
+
+const cyberContract = (seed = 12345) => ({
+  seed,
+  objective: {
+    kind: OBJECTIVES.DATA_NODE_SLICE,
+    title: 'Spike the server farm',
+    briefing: 'Jack in, slice the data node, then extract.',
+    params: { requiresCyberspace: true, count: 1 },
+  },
+  difficulty: 'standard',
+  threatCount: 1,
+  label: 'cyber test job',
+  context: testContractContext(OBJECTIVES.DATA_NODE_SLICE),
+  reward: { credits: 0, repDelta: 0 },
+});
+
+function makeDecker() {
+  return buildCrewMember('decker', { x: 0, y: 0 }, new Rng(100), { id: 'crew-decker' });
+}
+
+function adjacentFreeTile(world: World, target: Entity) {
+  for (let dy = -1; dy <= 1; dy++) {
+    for (let dx = -1; dx <= 1; dx++) {
+      if (dx === 0 && dy === 0) continue;
+      const x = target.x + dx;
+      const y = target.y + dy;
+      if (world.grid.inBounds(x, y) && world.grid.isPassable(x, y) && !world.entityAt(x, y)) {
+        return { x, y };
+      }
+    }
+  }
+  throw new Error(`no free tile adjacent to ${target.id}`);
+}
+
+function combatRun(seed = 12345) {
+  const run = new Run({ crewMember: makeDecker(), seed });
+  run.enterBriefing(cyberContract(seed));
+  run.enterCombat();
+  return run;
+}
+
+function jackIn(run: Run): CyberspaceLayer {
+  const point = Array.from(run.world!.entities.values()).find(e => e instanceof JackInPoint);
+  assert.ok(point, 'cyber contract placed a jack-in point');
+  const spot = adjacentFreeTile(run.world!, point!);
+  run.world!.relocateEntity(run.player!, spot.x, spot.y);
+  run.player!.refreshAp();
+  assert.equal((point as JackInPoint).interact(run.world!, run.player!).ok, true);
+  return (run.cyberspace as { phase: 'active'; layer: CyberspaceLayer }).layer;
+}
+
+test('isRunScene distinguishes Run from hub-shaped stubs', () => {
+  const run = combatRun();
+  assert.equal(isRunScene(run), true);
+  assert.equal(isRunScene({ world: null, player: null }), false);
+});
+
+test('active view reads meat body before jack-in', () => {
+  const run = combatRun();
+  assert.equal(isJackedIn(run), false);
+  assert.equal(activeWorldOf(run), run.world);
+  assert.equal(activeActorOf(run), run.player);
+  assert.equal(activeTileset(run), 'meat');
+  assert.equal(cyberLayerOf(run), null);
+});
+
+test('active view swaps to cyber layer after jack-in', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  assert.equal(isJackedIn(run), true);
+  assert.equal(activeWorldOf(run), layer.world);
+  assert.equal(activeActorOf(run), layer.avatar);
+  assert.equal(activeTileset(run), 'cyber');
+  assert.equal(cyberLayerOf(run), layer);
+  assert.notEqual(activeWorldOf(run), run.world);
+  assert.notEqual(activeActorOf(run), run.player);
+});
+
+test('pickActiveVisionField selects meat or cyber fog', () => {
+  const run = combatRun();
+  const meatVision = new VisionField();
+  const cyberVision = new VisionField();
+  assert.equal(pickActiveVisionField(run, meatVision, cyberVision), meatVision);
+  jackIn(run);
+  assert.equal(pickActiveVisionField(run, meatVision, cyberVision), cyberVision);
+});
diff --git a/tests/unit/shell/sceneListeners.test.ts b/tests/unit/shell/sceneListeners.test.ts
new file mode 100644
index 0000000..5398d5f
--- /dev/null
+++ b/tests/unit/shell/sceneListeners.test.ts
@@ -0,0 +1,58 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { EventBus, EVENT } from '../../../src/game/events.js';
+import { VisionField } from '../../../src/game/Vision.js';
+import { SceneListenerController } from '../../../src/shell/sceneListeners.js';
+import type { ShellScene } from '../../../src/shell/sceneView.js';
+
+test('SceneListenerController rewire replaces bus handlers', () => {
+  let flashCount = 0;
+  let recomputeCount = 0;
+  const bus = new EventBus();
+  const scene: ShellScene = {
+    bus,
+    world: null,
+    player: null,
+    state: 'hub',
+  } as unknown as ShellScene;
+
+  const controller = new SceneListenerController({
+    getScene: () => scene,
+    getCampaign: () => null,
+    getMeatVision: () => new VisionField(),
+    getCyberVision: () => new VisionField(),
+    resetCyberVision: () => new VisionField(),
+    dom: { stageEl: {} as HTMLElement, pipCanvas: {} as HTMLCanvasElement },
+    renderers: {
+      main: { draw: () => {} } as never,
+      pip: { draw: () => {} } as never,
+    },
+    animLock: { push: () => {} },
+    effects: {
+      flash: () => {
+        flashCount++;
+      },
+      paint: () => {},
+      paintPip: () => {},
+      recomputeVision: () => {
+        recomputeCount++;
+      },
+    },
+    onCivilianHarmReset: () => {},
+    onCivilianHarmed: () => {},
+    onRepAdjust: () => {},
+    onAlarmTransition: () => {},
+    onObjectiveTimerExpired: () => {},
+    memoriseMeatCorpse: () => {},
+    memoriseCyberCorpse: () => {},
+  });
+
+  controller.rewire();
+  bus.emit(EVENT.ENTITY_MOVED);
+  assert.equal(recomputeCount, 1);
+
+  controller.rewire();
+  bus.emit(EVENT.DOOR_UNLOCKED, { label: 'Vault door' });
+  assert.equal(flashCount, 1);
+});
diff --git a/tests/unit/shell/statusLine.test.ts b/tests/unit/shell/statusLine.test.ts
new file mode 100644
index 0000000..d9cbeac
--- /dev/null
+++ b/tests/unit/shell/statusLine.test.ts
@@ -0,0 +1,126 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { FACTION } from '../../../src/game/constants.js';
+import { RUN_STATE } from '../../../src/game/Run.js';
+import { CAMPAIGN_STATE } from '../../../src/game/Campaign.js';
+import { MODE } from '../../../src/input/keymap.js';
+import {
+  escapeHtml,
+  formatAlertTag,
+  formatHazardTag,
+  formatStatusLine,
+  hostileMoodTag,
+  joinStatusParts,
+  stateLabelForSceneState,
+} from '../../../src/shell/statusLine.js';
+
+test('stateLabelForSceneState maps hub and combat', () => {
+  assert.equal(stateLabelForSceneState(CAMPAIGN_STATE.HUB), '[HUB]');
+  assert.equal(stateLabelForSceneState(RUN_STATE.COMBAT), '[COMBAT]');
+});
+
+test('formatAlertTag renders ALERT and COOL phases', () => {
+  assert.match(formatAlertTag({ phase: 'alert', holdTurnsRemaining: 3 }), /ALERT 3/);
+  assert.match(formatAlertTag({ phase: 'cooldown', cooldownTurnsRemaining: 2 }), /COOL 2/);
+  assert.equal(formatAlertTag({ phase: 'quiet' }), '');
+});
+
+test('formatHazardTag renders hazard warning when standing on hazard tile', () => {
+  assert.match(formatHazardTag(true), /HAZARD/);
+  assert.equal(formatHazardTag(false), '');
+});
+
+test('formatStatusLine renders hub identity and arc context', () => {
+  const { html } = formatStatusLine({
+    stateLabel: '[HUB]',
+    sceneState: CAMPAIGN_STATE.HUB,
+    input: { mode: MODE.IDLE, aimKind: null },
+    hasPlayer: true,
+    hasQueue: true,
+    contextHtml: joinStatusParts(['Act 1 — casing']),
+    hubIdentity: 'CREW 2/3 CREDS 100 REP 55 (NEUTRAL)',
+    actionHistory: ['Curator acknowledged.'],
+    pendingActionCount: 0,
+  });
+  assert.match(html, /game-shell__stats.*CREW 2\/3/);
+  assert.match(html, /Act 1 — casing/);
+  assert.match(html, /Curator acknowledged/);
+});
+
+test('formatStatusLine renders combat a11y summary and alert tag', () => {
+  const { html } = formatStatusLine({
+    stateLabel: '[COMBAT]',
+    sceneState: RUN_STATE.COMBAT,
+    input: { mode: MODE.IDLE, aimKind: null },
+    hasPlayer: true,
+    hasQueue: true,
+    combatHud: {
+      identity: { callsign: 'Patch', archetype: 'decker', stealthed: false },
+      hp: { hp: 3, maxHp: 3 },
+      ap: { ap: 4, maxAp: 4 },
+      turn: { currentFaction: FACTION.PLAYER, turnNumber: 1 },
+    },
+    contextHtml: joinStatusParts([formatAlertTag({ phase: 'alert', holdTurnsRemaining: 2 })]),
+    actionHistory: [],
+    pendingActionCount: 0,
+  });
+  assert.match(html, /u-sr-only.*Combat status/);
+  assert.match(html, /alert-tag.*ALERT 2/);
+});
+
+test('formatStatusLine prefers proximity hint over corp mood', () => {
+  const { html } = formatStatusLine({
+    stateLabel: '[COMBAT]',
+    sceneState: RUN_STATE.COMBAT,
+    input: { mode: MODE.IDLE, aimKind: null },
+    hasPlayer: true,
+    hasQueue: true,
+    contextHtml: '',
+    proximityHint: 'FINN — press [Space] to shop.',
+    corpMood: { hostileTag: 'CORP', body: 'hostiles closing' },
+    actionHistory: [],
+    pendingActionCount: 0,
+  });
+  assert.match(html, /hint.*FINN/);
+  assert.doesNotMatch(html, /hostiles closing/);
+});
+
+test('formatStatusLine latches corp mood on player slice', () => {
+  const hostile = formatStatusLine({
+    stateLabel: '[COMBAT]',
+    sceneState: RUN_STATE.COMBAT,
+    input: { mode: MODE.IDLE, aimKind: null },
+    hasPlayer: true,
+    hasQueue: true,
+    contextHtml: '',
+    corpMood: { hostileTag: 'ICE', body: 'probes converging' },
+    actionHistory: [],
+    pendingActionCount: 0,
+  });
+  assert.equal(hostile.nextCorpMoodBody, 'probes converging');
+  assert.match(hostile.html, /ICE.*probes converging/);
+
+  const playerSlice = formatStatusLine({
+    stateLabel: '[COMBAT]',
+    sceneState: RUN_STATE.COMBAT,
+    input: { mode: MODE.IDLE, aimKind: null },
+    hasPlayer: true,
+    hasQueue: true,
+    contextHtml: '',
+    latchedCorpMood: { hostileTag: 'ICE', body: 'probes converging' },
+    actionHistory: ['> moved north'],
+    pendingActionCount: 1,
+  });
+  assert.match(playerSlice.html, /ICE.*probes converging/);
+  assert.equal(playerSlice.nextCorpMoodBody, null);
+});
+
+test('hostileMoodTag reads ICE while jacked in', () => {
+  assert.equal(hostileMoodTag(true, FACTION.RIVAL), 'ICE');
+  assert.equal(hostileMoodTag(false, FACTION.RIVAL), 'RIVAL');
+});
+
+test('escapeHtml encodes markup characters', () => {
+  assert.equal(escapeHtml('<script>&"'), '&lt;script&gt;&amp;&quot;');
+});

From 0f0b52c1236cfe81b8213fcb979b02925914f7fb Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Sun, 14 Jun 2026 14:45:02 -0700
Subject: [PATCH 33/55] tune heat vs score reveal

---
 docs/phase-3-plan.md                   |   9 +-
 src/game/Campaign.ts                   |  28 ++++--
 src/game/hub/arcSurface.ts             |  13 ++-
 tests/unit/game/Campaign.test.ts       | 116 +++++++++++++++++++++++--
 tests/unit/game/hub/arcSurface.test.ts |  32 ++++++-
 5 files changed, 177 insertions(+), 21 deletions(-)

diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 4940580..fb04b54 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -113,13 +113,14 @@ The Score target is always a newly synthesized CRITICAL-tier site, never promote
 The Clock creates mounting pressure that discourages indefinite grinding in Act 2/3. **Shipped implementation:** Act 2/3 **deploys taken** (successful or not) drive heat and the hard deadline — not global `completedJobs`, so entering Act 2 with a high job count from Stage 1 does not immediately start the Clock.
 
 - `CLOCK_ACT2_GRACE_JOBS = 3` — first three Act 2/3 deploys are grace (no heat, no `clockStarted`)
-- `CLOCK_HEAT_WINDOW_JOBS = 5` — deploys after grace before the window closes
-- `CLOCK_ACT2_DEADLINE_JOBS = 8` — total Act 2/3 deploys (`grace + window`)
+- `CLOCK_HEAT_WINDOW_JOBS = 5` — deploys after grace before the window closes **in Act 3**
+- `CLOCK_ACT2_DEADLINE_JOBS = 8` — total Act 2/3 deploys (`grace + window`) counted against the Act 3 deadline
+- `CLOCK_ACT3_MIN_JOBS_REMAINING = 3` — on Act 2 → Act 3 transition, over-budget `clockJobsTaken` is clamped so final prep always has at least this many deploys left
 - `clockJobsTaken` increments on `deployCrewMember` while `arcStage` is `act-2` or `act-3` (Score deploy excluded — it sets `scoreAttempted`)
 - `clockStarted` when `scoreRevealed && clockJobsTaken >= CLOCK_ACT2_GRACE_JOBS`
 - `clockHeat = max(0, clockJobsTaken - CLOCK_ACT2_GRACE_JOBS)` once started
-- Heat nudges Curator threat counts upward, capped per difficulty tier
-- Returning to Hub at the deadline without `scoreAttempted` sets `Campaign.state` to `ENDED` with `endReason: 'clock-expired'` and presents the terminal game-over screen
+- **Act 2 casing:** heat mounts and HUD shows `CLOCK: HEAT N`, but the deadline cannot end the campaign — failed deploys must not stillborn the path to Act 3
+- **Act 3 final prep:** HUD adds `/ Y JOBS LEFT`; returning to Hub at the deadline without `scoreAttempted` sets `Campaign.state` to `ENDED` with `endReason: 'clock-expired'`
 
 **Hub narrative beats (priority order on `enterHub`):** `score-reveal` → `clock-reveal` → `act-3-reveal`. Each defers its `hubReveals` flag until the player dismisses the Curator briefing modal.
 
diff --git a/src/game/Campaign.ts b/src/game/Campaign.ts
index fe07896..355cbad 100644
--- a/src/game/Campaign.ts
+++ b/src/game/Campaign.ts
@@ -69,10 +69,17 @@ export const ARC_ACT_3_MIN_CREW_ALIVE = 4;
 export const ARC_ACT_3_MIN_PRINCIPAL_SITES_VISITED = 3;
 /** Act-2/3 deploys taken before corp heat starts (successful or not). */
 export const CLOCK_ACT2_GRACE_JOBS = 3;
-/** Deploys after grace before the Score window closes. */
+/** Deploys after grace before the Score window closes (Act 3 only). */
 export const CLOCK_HEAT_WINDOW_JOBS = 5;
 /** Total act-2/3 deploys allowed before clock loss (`grace + window`). */
 export const CLOCK_ACT2_DEADLINE_JOBS = CLOCK_ACT2_GRACE_JOBS + CLOCK_HEAT_WINDOW_JOBS;
+/** Act 3 deploy budget guaranteed when final prep unlocks — room for prep + THE SCORE. */
+export const CLOCK_ACT3_MIN_JOBS_REMAINING = 3;
+
+/** Clock expiry applies only during Act 3 final prep; Act 2 casing can run past the old deadline. */
+export function clockDeadlineApplies(arcStage: CampaignArcStage): boolean {
+  return arcStage === 'act-3';
+}
 /** Campaign-ending payday for completing THE SCORE. */
 export const SCORE_CREDITS_REWARD = 5_000;
 const SYNTHETIC_SCORE_TARGET_DIFFICULTY = CONTRACT_DIFFICULTY.CRITICAL;
@@ -135,7 +142,7 @@ export type CampaignOptions = {
 type CampaignLike = {
   crew: { flatlined: boolean }[];
   activeRun?: { contract: Contract | null } | null;
-  arc?: Pick<CampaignArc, 'scoreRevealed' | 'scoreAttempted'>;
+  arc?: Pick<CampaignArc, 'scoreRevealed' | 'scoreAttempted' | 'arcStage'>;
   clockJobsTaken?: number;
 };
 
@@ -178,6 +185,7 @@ export function willEndCampaignAfterResult(
   if (outcome === OUTCOME.EXIT && completed && contract && isScoreContract(contract)) return true;
   return Boolean(
     campaign.arc?.scoreRevealed &&
+    clockDeadlineApplies(campaign.arc.arcStage) &&
     (campaign.clockJobsTaken ?? 0) >= CLOCK_ACT2_DEADLINE_JOBS &&
     !campaign.arc.scoreAttempted
   );
@@ -375,11 +383,7 @@ export class Campaign {
     if (this.arc.scoreAttempted && this.arc.arcStage === 'score') {
       return 'decker-flatlined-score';
     }
-    if (
-      this.arc.scoreRevealed &&
-      this.clockJobsTaken >= CLOCK_ACT2_DEADLINE_JOBS &&
-      !this.arc.scoreAttempted
-    ) {
+    if (this.#clockExpired()) {
       return 'clock-expired';
     }
     return 'crew-wipe';
@@ -1222,6 +1226,7 @@ export class Campaign {
 
     if (this.arc.arcStage === 'act-2' && this.#qualifiesForAct3()) {
       this.arc.arcStage = 'act-3';
+      this.#ensureAct3ScoreWindow();
     }
 
     if (this.arc.scoreRevealed && this.clockJobsTaken >= CLOCK_ACT2_GRACE_JOBS) {
@@ -1326,12 +1331,21 @@ export class Campaign {
   #clockExpired(): boolean {
     return (
       this.arc.scoreRevealed &&
+      clockDeadlineApplies(this.arc.arcStage) &&
       this.clockJobsTaken >= CLOCK_ACT2_DEADLINE_JOBS &&
       !this.arc.scoreAttempted &&
       !this.arc.scoreCompleted
     );
   }
 
+  /** Guarantee deploy headroom once THE SCORE can appear — casing failures must not stillborn Act 3. */
+  #ensureAct3ScoreWindow(): void {
+    const maxTaken = CLOCK_ACT2_DEADLINE_JOBS - CLOCK_ACT3_MIN_JOBS_REMAINING;
+    if (this.clockJobsTaken > maxTaken) {
+      this.clockJobsTaken = maxTaken;
+    }
+  }
+
   #synthesizeScoreTarget(): LocationSite {
     const seed = this.rng.intRange(0, 0x7fffffff);
     const principal = this.rng.pick(
diff --git a/src/game/hub/arcSurface.ts b/src/game/hub/arcSurface.ts
index 2fb42d6..47c4409 100644
--- a/src/game/hub/arcSurface.ts
+++ b/src/game/hub/arcSurface.ts
@@ -1,7 +1,11 @@
 import type { Contract } from './Curator.js';
 import type { Campaign } from '../Campaign.js';
 import type { HubReveals } from './hubReveals.js';
-import { CLOCK_ACT2_DEADLINE_JOBS, CLOCK_ACT2_GRACE_JOBS } from '../Campaign.js';
+import {
+  CLOCK_ACT2_DEADLINE_JOBS,
+  CLOCK_ACT2_GRACE_JOBS,
+  clockDeadlineApplies,
+} from '../Campaign.js';
 import type { CampaignArcStage, LocationSite } from '../../types.js';
 import type { Decker } from '../archetypes/Decker.js';
 import type { Crew } from '../Crew.js';
@@ -72,9 +76,14 @@ export function formatClockStatus(campaign: ArcSurfaceCampaign): string | null {
   if (campaign.arc.scoreAttempted || campaign.arc.scoreCompleted) return null;
 
   const clockJobsTaken = campaign.clockJobsTaken ?? 0;
+  const heat = campaign.clockHeat ?? Math.max(0, clockJobsTaken - CLOCK_ACT2_GRACE_JOBS);
+
+  if (!clockDeadlineApplies(campaign.arc.arcStage)) {
+    return `CLOCK: HEAT ${heat}`;
+  }
+
   if (clockJobsTaken >= CLOCK_ACT2_DEADLINE_JOBS) return null;
 
-  const heat = campaign.clockHeat ?? Math.max(0, clockJobsTaken - CLOCK_ACT2_GRACE_JOBS);
   const jobsRemaining =
     campaign.scoreDeadlineJobsRemaining ?? Math.max(0, CLOCK_ACT2_DEADLINE_JOBS - clockJobsTaken);
   return `CLOCK: HEAT ${heat} / ${jobsRemaining} JOBS LEFT`;
diff --git a/tests/unit/game/Campaign.test.ts b/tests/unit/game/Campaign.test.ts
index 7b3d938..d4471c8 100644
--- a/tests/unit/game/Campaign.test.ts
+++ b/tests/unit/game/Campaign.test.ts
@@ -973,8 +973,90 @@ test('P3.M1.5: Clock ignores completedJobs until act-2/3 deploys cross grace', (
   });
   assert.equal(expired.clockHeat, CLOCK_ACT2_DEADLINE_JOBS - CLOCK_ACT2_GRACE_JOBS);
   assert.equal(expired.arc.clockStarted, true);
-  assert.equal(expired.state, CAMPAIGN_STATE.ENDED);
-  assert.equal(expired.endReason, 'clock-expired');
+  assert.equal(expired.arcStage, 'act-2');
+  assert.equal(expired.state, CAMPAIGN_STATE.HUB);
+  assert.equal(expired.endReason, null);
+});
+
+test('P3.M1.5: clock loss requires Act 3 — Act 2 casing survives past the deploy deadline', () => {
+  const act2PastDeadline = new Campaign({
+    seed: 43,
+    rep: 60,
+    completedJobs: 6,
+    clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS - 1,
+  });
+  assert.equal(act2PastDeadline.arcStage, 'act-2');
+  assert.equal(act2PastDeadline.state, CAMPAIGN_STATE.HUB);
+  assert.equal(act2PastDeadline.endReason, null);
+  assert.equal(willEndCampaignAfterResult(act2PastDeadline, OUTCOME.EXIT, true), false);
+
+  const act3AtDeadline = new Campaign({
+    seed: 43,
+    rep: 60,
+    completedJobs: 9,
+    clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS,
+    siteRoster: [
+      validSite({
+        id: 'score',
+        seed: '100',
+        tier: 'score',
+        scoreTarget: true,
+        lastVisitedJob: 5,
+        principal: { id: 'matsuda', label: 'Matsuda', groups: ['corp'] },
+      }),
+      validSite({
+        id: 'case-1',
+        seed: '101',
+        lastVisitedJob: 6,
+        principal: { id: 'matsuda', label: 'Matsuda', groups: ['corp'] },
+      }),
+      validSite({
+        id: 'case-2',
+        seed: '102',
+        lastVisitedJob: 7,
+        principal: { id: 'matsuda', label: 'Matsuda', groups: ['corp'] },
+      }),
+    ],
+  });
+  assert.equal(act3AtDeadline.arcStage, 'act-3');
+  assert.equal(act3AtDeadline.state, CAMPAIGN_STATE.HUB, 'Act 3 entry refunds over-budget clock');
+  act3AtDeadline.clockJobsTaken = CLOCK_ACT2_DEADLINE_JOBS;
+  act3AtDeadline.state = CAMPAIGN_STATE.COMBAT;
+  act3AtDeadline.enterHub();
+  assert.equal(act3AtDeadline.state, CAMPAIGN_STATE.ENDED);
+  assert.equal(act3AtDeadline.endReason, 'clock-expired');
+});
+
+test('P3.M1.5: Act 3 entry clamps an over-budget clock to guarantee Score deploy headroom', () => {
+  const scorePrincipal = { id: 'matsuda', label: 'Matsuda', groups: ['corp'] };
+  const campaign = new Campaign({
+    seed: 42,
+    rep: 60,
+    completedJobs: 9,
+    clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS,
+    siteRoster: [
+      validSite({
+        id: 'score',
+        seed: '100',
+        tier: 'score',
+        scoreTarget: true,
+        lastVisitedJob: 5,
+        principal: scorePrincipal,
+      }),
+      validSite({ id: 'case-1', seed: '101', lastVisitedJob: 6, principal: scorePrincipal }),
+      validSite({ id: 'case-2', seed: '102', lastVisitedJob: 7, principal: scorePrincipal }),
+    ],
+  });
+
+  assert.equal(campaign.arcStage, 'act-3');
+  assert.equal(campaign.state, CAMPAIGN_STATE.HUB);
+  assert.equal(
+    campaign.clockJobsTaken,
+    CLOCK_ACT2_DEADLINE_JOBS - 3,
+    'must leave at least three Act 3 deploys'
+  );
+  assert.equal(campaign.scoreDeadlineJobsRemaining, 3);
+  assert.ok(campaign.canAttemptScore());
 });
 
 test('P3.M1.5: endReason distinguishes score win, clock loss, and crew wipe', () => {
@@ -984,7 +1066,7 @@ test('P3.M1.5: endReason distinguishes score win, clock loss, and crew wipe', ()
     completedJobs: 4,
     clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS,
   });
-  assert.equal(clockLoss.endReason, 'clock-expired');
+  assert.equal(clockLoss.endReason, null, 'Act 2 past deadline is not clock loss');
 
   const scoreWin = new Campaign({
     seed: 44,
@@ -1060,9 +1142,33 @@ test('terminal result detection bypasses debrief for Score, terminal death, and
   const clockLoss = new Campaign({
     seed: 46,
     rep: 60,
-    completedJobs: 4,
-    clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS,
+    completedJobs: 9,
+    clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS - 1,
+    siteRoster: [
+      validSite({
+        id: 'score',
+        seed: '100',
+        tier: 'score',
+        scoreTarget: true,
+        lastVisitedJob: 5,
+        principal: { id: 'matsuda', label: 'Matsuda', groups: ['corp'] },
+      }),
+      validSite({
+        id: 'case-1',
+        seed: '101',
+        lastVisitedJob: 6,
+        principal: { id: 'matsuda', label: 'Matsuda', groups: ['corp'] },
+      }),
+      validSite({
+        id: 'case-2',
+        seed: '102',
+        lastVisitedJob: 7,
+        principal: { id: 'matsuda', label: 'Matsuda', groups: ['corp'] },
+      }),
+    ],
   });
+  assert.equal(clockLoss.arcStage, 'act-3');
+  clockLoss.clockJobsTaken = CLOCK_ACT2_DEADLINE_JOBS;
   clockLoss.state = CAMPAIGN_STATE.COMBAT;
   assert.equal(willEndCampaignAfterResult(clockLoss, OUTCOME.EXIT, true), true);
 });
diff --git a/tests/unit/game/hub/arcSurface.test.ts b/tests/unit/game/hub/arcSurface.test.ts
index 452608e..4508ac8 100644
--- a/tests/unit/game/hub/arcSurface.test.ts
+++ b/tests/unit/game/hub/arcSurface.test.ts
@@ -89,7 +89,7 @@ test('formatHubArcStatusLines shows active heat only after clock briefing', () =
   };
   assert.deepEqual(formatHubArcStatusLines(campaign), [
     'STAGE 2: CASING | SCORE: Matsuda server farm',
-    'CLOCK: HEAT 2 / 3 JOBS LEFT',
+    'CLOCK: HEAT 2',
   ]);
 });
 
@@ -105,7 +105,7 @@ test('formatHubArcStatus throws when revealed state has no Score target', () =>
   );
 });
 
-test('formatClockStatus stays hidden before briefing, during grace, and after deadline', () => {
+test('formatClockStatus stays hidden before briefing, during grace, and after Act 3 deadline', () => {
   assert.equal(
     formatClockStatus({
       arc: arc({ scoreRevealed: true }),
@@ -138,7 +138,18 @@ test('formatClockStatus stays hidden before briefing, during grace, and after de
   );
   assert.equal(
     formatClockStatus({
-      arc: arc({ scoreRevealed: true, clockStarted: true }),
+      arc: arc({ arcStage: 'act-2', scoreRevealed: true, clockStarted: true }),
+      siteRoster: [scoreSite()],
+      crew: [],
+      hubReveals: { clockBriefingPresented: true },
+      clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS,
+      clockHeat: CLOCK_ACT2_DEADLINE_JOBS - CLOCK_ACT2_GRACE_JOBS,
+    }),
+    `CLOCK: HEAT ${CLOCK_ACT2_DEADLINE_JOBS - CLOCK_ACT2_GRACE_JOBS}`
+  );
+  assert.equal(
+    formatClockStatus({
+      arc: arc({ arcStage: 'act-3', scoreRevealed: true, clockStarted: true }),
       siteRoster: [scoreSite()],
       crew: [],
       hubReveals: { clockBriefingPresented: true },
@@ -148,6 +159,21 @@ test('formatClockStatus stays hidden before briefing, during grace, and after de
   );
 });
 
+test('formatClockStatus shows Act 3 deadline countdown', () => {
+  assert.equal(
+    formatClockStatus({
+      arc: arc({ arcStage: 'act-3', scoreRevealed: true, clockStarted: true }),
+      siteRoster: [scoreSite()],
+      crew: [],
+      hubReveals: { clockBriefingPresented: true },
+      clockJobsTaken: CLOCK_ACT2_GRACE_JOBS + 2,
+      clockHeat: 2,
+      scoreDeadlineJobsRemaining: 3,
+    }),
+    'CLOCK: HEAT 2 / 3 JOBS LEFT'
+  );
+});
+
 test('act3 reveal copy points at THE SCORE on the job board', () => {
   const lines = act3RevealLines();
   assert.match(lines.join('\n'), /You're ready/i);

From 348ad8a0bba83f670e20fb27eaac37f6392ccb8c Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Sun, 14 Jun 2026 14:57:58 -0700
Subject: [PATCH 34/55] tweak reveal pacing

---
 docs/phase-2-plan.md                          |  8 +-
 docs/phase-2.5-plan.md                        | 12 +--
 docs/phase-3-plan.md                          |  6 +-
 src/game/Campaign.ts                          |  4 +-
 src/game/constants.ts                         |  4 +-
 src/game/hub/hubReveals.ts                    |  2 +-
 tests/unit/game/Campaign.test.ts              | 86 +++++++++----------
 tests/unit/game/campaignSummary.test.ts       |  4 +-
 .../unit/game/cyber/cyberPersistence.test.ts  |  2 +-
 tests/unit/game/hub/cyberContract.test.ts     |  2 +-
 tests/unit/game/hub/hubReveals.test.ts        |  8 +-
 tests/unit/game/persistence.test.ts           |  4 +-
 12 files changed, 71 insertions(+), 71 deletions(-)

diff --git a/docs/phase-2-plan.md b/docs/phase-2-plan.md
index 516e778..32d322f 100644
--- a/docs/phase-2-plan.md
+++ b/docs/phase-2-plan.md
@@ -49,7 +49,7 @@ Test count at Phase 2 start: **409 passing** (end of Phase 1 / M8).
   - *Truly neutral* — civilians; Rep-sensitive (behavior scales with meter level).
   - *Corp-aligned non-combatant* — office workers, desk security; do not fight but trigger an alarm (all drones in the map enter ENGAGE) if they spot the player.
 - **Rep:** Campaign-level meter (0–100, starting at 50). Raised by clean contract completion; lowered by civilian/neutral kills. Gates neutral NPC behavior and crew recruitment unlocks.
-- **Recruitment:** New crew members unlock when Rep reaches a threshold (suggest 65) or as a specific contract reward. Archetype and callsign generated on recruit; callsign deduplication applies.
+- **Recruitment:** New crew members unlock when Rep reaches the KNOWN tier floor (`REP.RECRUIT_THRESHOLD`, 50) or as a specific contract reward. Archetype and callsign generated on recruit; callsign deduplication applies.
 - **Animations (M0):** Turn-blocking — input disabled for ~300ms during the longest active animation. Three effects: screen shake (CSS `@keyframes` translate on game container, ~150ms), damage reddening (CRT filter temporary red vignette, ~300ms), muzzle flash (1-frame canvas color override at shooter's tile, ~80ms). All wired to the existing event bus. No game-logic changes.
 - **Unified special-action key (M1):** Vault, Slide, and Deploy collapse into a single `x` → `MODE.SPECIAL_AIM` → `{ type: 'special', dx, dy }` intent at the keymap layer; `applyIntent.doSpecial` dispatches to the archetype's perk by capability sniffing (`canDeploy` → Tech, `canVault` → Merc, `canSlide` → Razor). One key, one touch-pad button, one help row — no WASD collision (the original plan's `d` key clashed with WASD-right), and adding a future archetype only requires implementing its perk method.
 - **Interact key rebound to Space (M3):** `i` → Space (`' '`). Roguelike players associate `i` with inventory (which M4's Finn shop will want). Space is the universal "activate" key in modern games — accessible, no directional collision (qezc diagonals, WASD, arrows all occupied). Keymap, touchpad, key-help rows, and proximity hints all updated. `i` is now unbound, reserved for inventory in M4.
@@ -72,8 +72,8 @@ Test count at Phase 2 start: **409 passing** (end of Phase 1 / M8).
 
 - **Campaign-start recruitment (M6):** New campaigns start with an empty crew (`crew: []`). The shell shows `<system-start>`, then presents `<initial-recruit>` — a full-screen overlay with 3 randomly-generated candidates (weighted 40/40/20 Merc/Razor/Tech). Player picks 2 of 3; the unchosen candidate is discarded. `Campaign.recruitInitial(memberIds)` commits the picks, then the shell calls `enterHub()` to build the hub world and persist. No Rep gate for initial recruitment — this is the campaign-start exception.
 - **`<initial-recruit>` component (M6):** New Web Component (`components/InitialRecruit.ts`). Card-based layout (3-column grid, responsive to 1-column on mobile). Cards show callsign, archetype, HP, AIM%, DODGE%, and a short blurb. Toggle selection with Enter/Space or click; ←/→ or A/D navigate. Confirm when exactly 2 are selected. Emits `recruited` CustomEvent with `{ memberIds: string[] }`.
-- **Mid-campaign recruitment (M6):** `Campaign.generateRecruits()` called on every `enterHub()`. Returns 1–2 candidates (weighted archetype pool) when `rep ≥ REP.RECRUIT_THRESHOLD` (65), empty array otherwise. `<crew-roster>` extended with an "Available Recruits" section below the crew list — recruit rows with keyboard nav (ArrowDown from last crew row transitions into recruit section). One recruit per hub visit (`recruitedThisVisit` flag, reset on `enterHub()`). `Campaign.recruit(recruitId)` validates Rep gate still holds, moves the recruit from `availableRecruits` into `crew`, persists.
-- **Recruit constants (M6):** `RECRUIT.POOL_MIN = 1`, `POOL_MAX = 2`, `INITIAL_CANDIDATES = 3`, `INITIAL_PICKS = 2`. `REP.RECRUIT_THRESHOLD = 65`. `RECRUIT_ARCHETYPE_POOL = ['merc','merc','razor','razor','tech']` (flat array for `rng.pick()` weighted distribution).
+- **Mid-campaign recruitment (M6):** `Campaign.generateRecruits()` called on every `enterHub()`. Returns 1–2 candidates (weighted archetype pool) when `rep ≥ REP.RECRUIT_THRESHOLD` (50 — KNOWN tier floor), empty array otherwise. `<crew-roster>` extended with an "Available Recruits" section below the crew list — recruit rows with keyboard nav (ArrowDown from last crew row transitions into recruit section). One recruit per hub visit (`recruitedThisVisit` flag, reset on `enterHub()`). `Campaign.recruit(recruitId)` validates Rep gate still holds, moves the recruit from `availableRecruits` into `crew`, persists.
+- **Recruit constants (M6):** `RECRUIT.POOL_MIN = 1`, `POOL_MAX = 2`, `INITIAL_CANDIDATES = 3`, `INITIAL_PICKS = 2`. `REP.RECRUIT_THRESHOLD = 50` (lowered from the original 65 in Phase 3 so recruitment opens at KNOWN while Act 2 waits on a higher bar). `RECRUIT_ARCHETYPE_POOL = ['merc','merc','razor','razor','tech']` (flat array for `rng.pick()` weighted distribution).
 - **Entity display labels (M6):** `entityLabel(entity)` and `resolveEntityLabel(id, entities)` in `Entity.ts`. Crew members display by callsign; other entities display as `[Faction]Kind` (e.g. `[Corp]Drone`, `[Neutral]Civilian`, `Turret`). All log messages in `applyIntent`, `combatTurnPipeline`, `corpTurnStatusCopy`, and `debug/index` switched from raw entity IDs to display labels.
 - **`CharacterSelect` removed (M6):** The `<character-select>` component is deleted — campaign-start archetype selection is replaced by the recruitment flow. The debug harness retains its own archetype selection via URL params.
 - **Status bar two-row activity (M6):** The status bar's lower section now has two activity rows instead of a dedicated hint row + action row. When a proximity hint is active, it takes the upper slot (pushing previous action line out); otherwise both rows show rolling action logs (`prevActionLine` / `lastActionLine`). Corp turn status messages also take the upper slot ephemerally. Geometry remains constant (CSS reserved heights).
@@ -229,7 +229,7 @@ Closes the **NEUTRAL faction shootable** kaizen item.
 ### M6 — Recruitment ✅
 
 - `Campaign` gains `availableRecruits: Crew[]` and `recruitedThisVisit: boolean` — refreshed on each `enterHub()`. `generateRecruits()` rolls 1–2 candidates; archetype weighted via `RECRUIT_ARCHETYPE_POOL` (Merc 40%, Razor 40%, Tech 20%); callsign picked from archetype list excluding all names ever used in this campaign (living + flatlined + current recruit candidates).
-- **Unlock conditions** checked in `generateRecruits`: Rep ≥ `REP.RECRUIT_THRESHOLD` (65). Returns empty array below threshold. Contract `reward.recruit` flag type-stubbed on `Contract` for M8's high-tier contract rewards.
+- **Unlock conditions** checked in `generateRecruits`: Rep ≥ `REP.RECRUIT_THRESHOLD` (50). Returns empty array below threshold. Contract `reward.recruit` flag type-stubbed on `Contract` for M8's high-tier contract rewards.
 - `Campaign.recruit(recruitId)` — validates Rep gate still holds, `recruitedThisVisit` not set, recruit exists in pool; splices recruit from `availableRecruits` into `crew`; sets `recruitedThisVisit = true`; persists. Crew can exceed 3 members after recruitment. Throws on all illegal preconditions.
 - `Campaign.backfillRecruitsIfEligible()` — safety net called by the shell before opening `<crew-roster>`. Fills an empty pool when Rep meets threshold but recruits weren't generated (edge case from restore order or Rep changes between enterHub and roster open).
 - Hub UI: `<crew-roster>` extended with an "Available Recruits" section below the crew list (visible when `availableRecruits.length > 0` and `!recruitedThisVisit`). Recruit rows are keyboard-navigable — ArrowDown from the last crew row transitions into the recruit section; ArrowUp from the first recruit row returns to crew. Selected recruit shows stats in the detail pane. RECRUIT button commits via `recruit` CustomEvent.
diff --git a/docs/phase-2.5-plan.md b/docs/phase-2.5-plan.md
index 5479213..3e24cb7 100644
--- a/docs/phase-2.5-plan.md
+++ b/docs/phase-2.5-plan.md
@@ -759,8 +759,8 @@ Phase 2.5 milestones that follow (M4–M7) retain their original numbering for c
 - **Rep tier constants:** Formalise the existing `REP_LABEL` brackets into a tier enum with gameplay consequences. At least four tiers with defined thresholds:
   - **BURNED** (0–19): Only STANDARD contracts. Recruitment locked.
   - **UNKNOWN** (20–49): BASE_DIFFICULTY_POOL (5 STD / 3 ELV / 1 CRT). Current default.
-  - **KNOWN** (50–79): Shifted pool (3 STD / 4 ELV / 2 CRT). Recruitment unlocked at 65 (existing gate).
-  - **TRUSTED** (80–100): Top pool (2 STD / 3 ELV / 4 CRT). Phase 3 Decker recruitment + Score access gate.
+  - **KNOWN** (50–79): Shifted pool (3 STD / 4 ELV / 2 CRT). Terminal recruitment unlocked (KNOWN floor).
+  - **TRUSTED** (80–100): Top pool (2 STD / 3 ELV / 4 CRT). Phase 3 Act 2 transition (`rep >= 65`) and Score access.
 - **BURNED penalty pool:** When Rep < 20, the Curator rolls only STANDARD difficulty — the player is too hot to get offered real work. This is the stick; the existing clean-completion Rep bonuses are the carrot.
 - **Curator integration:** `generateContracts` reads `campaign.rep` (via the existing `ContractCampaign` type) to select the difficulty pool, replacing the `betterContracts` boolean check. The `BETTER_CONTRACTS_POOL` constant and `betterContracts` meta key are removed.
 - **Reward scaling per tier:** The per-contract credit reward floor bump that `betterContracts` provided (`+2× SALVAGE_TO_CRED_RATE`) is now tied to the TRUSTED tier instead of a purchased flag.
@@ -888,7 +888,7 @@ Phase 2.5 milestones that follow (M4–M7) retain their original numbering for c
 - **Reveal check on Hub entry:** `Campaign.enterHub` (or a new `Campaign.checkHubReveals`) evaluates trigger conditions against campaign state and fires the **first unseen** introduction that qualifies. **One message per Hub visit** (don’t stack — the player absorbs one new thing at a time).
 - **Reveal definitions:**
   - **Finn introduction:** Trigger = player has returned from at least one run (campaign has > 0 completed jobs, or `credits > 0`, or `totalSalvage > 0`). Before this trigger, **Finn’s entity is absent from the Hub map** — `enterHub` skips spawning him. Curator message introduces Finn and explains salvage selling. After the flag is set, Finn spawns every visit.
-  - **Terminal / recruitment introduction:** Trigger = `campaign.rep >= REP.RECRUIT_THRESHOLD` (65) or `campaign.pendingRecruitReward`. Terminal entity is **always present** on the Hub map (it’s plausible scenery), but the Curator message is the prompt to use it. Before the flag, interacting with the Terminal could show a “systems locked” or “access denied” flavor response (or simply not open the recruit UI).
+  - **Terminal / recruitment introduction:** Trigger = `campaign.rep >= REP.RECRUIT_THRESHOLD` (50 — KNOWN floor) or `campaign.pendingRecruitReward`. Terminal entity is **always present** on the Hub map (it’s plausible scenery), but the Curator message is the prompt to use it. Before the flag, interacting with the Terminal could show a “systems locked” or “access denied” flavor response (or simply not open the recruit UI).
   - **Clinic introduction:** Trigger = any crew member has `hp < maxHp` on Hub entry (the player has experienced attrition). Curator message introduces the Doc and explains the clinic. Before the flag, the clinic NPC is absent from the Hub map (same pattern as Finn).
 - **Curator message delivery:** The Curator entity (or the shell’s Hub interaction handler) emits a `curator:message` event (or equivalent) with the reveal’s text. The shell displays it in the log or a brief overlay/modal — same feedback channel as existing Curator contract-board interactions. Messages are 1–3 lines of flavor text that double as system hints.
 - **Pattern reuse (Phase 3):** The reveal system accepts new entries without modifying the check loop. Phase 3 adds Decker recruitment (trigger: top Rep tier, new flag `deckerRecruited`). M5 documents this extension point but does **not** implement the Decker reveal.
@@ -897,17 +897,17 @@ Phase 2.5 milestones that follow (M4–M7) retain their original numbering for c
 **Acceptance:**
 
 - Unit tests: each reveal’s trigger condition fires correctly; flags persist and prevent re-fire; only one reveal per Hub visit; Finn/Clinic absent from world when their flag is unset.
-- Integration test: fresh campaign → first Hub (no Finn, no Clinic) → complete a run → return to Hub → Finn introduced → next Hub visit with damaged crew → Clinic introduced → next Hub visit with Rep ≥ 65 → Terminal explained.
+- Integration test: fresh campaign → first Hub (no Finn, no Clinic) → complete a run → return to Hub → Finn introduced → next Hub visit with damaged crew → Clinic introduced → next Hub visit with Rep ≥ 50 → Terminal recruitment explained.
 - Campaign snapshot round-trip preserves `hubReveals`.
 - Pre-M5.4 saves load with `hubReveals: {}` default and don’t crash.
 
 **Implementation notes:**
 
-- `src/game/hub/hubReveals.ts` owns reveal definitions in fixed order (Finn → Clinic → Terminal), trigger predicates, `applyFirstHubReveal`, and spawn/unlock helpers (`shouldSpawnFinn`, `shouldSpawnClinic`, `isTerminalRecruitmentUnlocked`). Clinic precedes Terminal so attrition healing is introduced before recruitment at Rep 65.
+- `src/game/hub/hubReveals.ts` owns reveal definitions in fixed order (Finn → Clinic → Terminal), trigger predicates, `applyFirstHubReveal`, and spawn/unlock helpers (`shouldSpawnFinn`, `shouldSpawnClinic`, `isTerminalRecruitmentUnlocked`). Clinic precedes Terminal so attrition healing is introduced before recruitment at Rep 50 (KNOWN).
 - `Campaign.hubReveals` + `completedJobs` persist in `CampaignSnapshot`; `normalizeHubReveals` on load; pre-M5.4 saves default to `{}` / `0`.
 - `Campaign.enterHub()` applies at most one reveal (sets flag + `lastHubReveal`), then spawns Finn/Clinic only when their flags are set; Terminal always spawns.
 - Finn trigger: `completedJobs > 0` OR `credits > 0` OR `totalSalvage > 0`. `onJobEnd` EXIT increments `completedJobs`.
-- Terminal trigger: `rep >= REP.RECRUIT_THRESHOLD` (65) OR `pendingRecruitReward`. Shell blocks roster UI until `terminalExplained` (“access denied” flash).
+- Terminal trigger: `rep >= REP.RECRUIT_THRESHOLD` (50) OR `pendingRecruitReward`. Shell blocks roster UI until `terminalExplained` (“access denied” flash).
 - Clinic trigger: any living crew member with `hp < maxHp`. Clinic absent until `clinicIntroduced`.
 - `<curator-briefing>` (`components/CuratorBriefing.ts`) — SystemStart-style full-screen modal; `setBriefing({ title, lines })` for diegetic copy. Hub reveals show here (titles per reveal in `hubReveals.ts`); status-line hint deferred until `[ CONTINUE ]` / Esc / Enter. Shell `presentHubRevealIfAny()` after `enterHubAndRender` and post-job `onNewRunRequested`; interact hints list only spawned NPCs.
 - 13 tests in `hubReveals.test.ts`; Campaign/persistence tests updated. Full suite: 976/976 green.
diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index fb04b54..d384c0a 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -72,7 +72,7 @@ Phase 3 depends on specific hooks built into Phase 2.5 milestones:
 | 2.5 Milestone | Phase 3 hook | Notes |
 |---|---|---|
 | **P2.5.M2.10** (recipes) | Recipe context accepts **arc stage** input | Phase 3 uses this to bias contract generation toward Score-adjacent objectives in Acts 2–3 |
-| **P2.5.M5** (economy/rep) | KNOWN rep tier defined and reachable | Phase 3 gates Decker recruitment and Score access at `rep >= 50` (KNOWN floor; TRUSTED qualifies) |
+| **P2.5.M5** (economy/rep) | KNOWN rep tier defined and reachable | Terminal recruitment opens at `rep >= 50` (KNOWN floor). Act 2 (Score reveal + Decker) gates at `rep >= 65` plus job count |
 | **P2.5.M7** (persistence) | Location schema includes `scoreTarget` flag; site roster + mutation deltas | Phase 3 synthesizes a new CRITICAL-tier Score target; player "cases" it across visits. Roster sites for the same principal provide recon value |
 
 ### Score target identification
@@ -91,7 +91,7 @@ The Score target is always a newly synthesized CRITICAL-tier site, never promote
 
 - **Arc state:** Campaign save tracks `arcStage` (`act-1` / `act-2` / `act-3` / `score`), `completedJobs`, `clockJobsTaken` (Act 2/3 deploys that drive the Clock — incremented on deploy, not on extract), and arc-specific flags (`deckerRecruited`, `scoreRevealed`, `clockStarted`, `scoreAttempted`, `scoreCompleted`). Hub reveal flags (`scoreBriefingPresented`, `clockBriefingPresented`, `act3BriefingPresented`) persist separately. Prefer a typed `Campaign.arc` record over stuffing more opaque keys into `Campaign.meta`; legacy saves can normalize from absent `arc` into Act 1.
 - **Act transitions:** Define triggers for act boundaries:
-  - Act 1 → Act 2: reach at least `KNOWN` rep tier (`rep >= 50`) + minimum successful job count (recommended: `completedJobs >= 4`). Triggers Score reveal and Decker recruitment (same beat).
+  - Act 1 → Act 2: `rep >= 65` (proven-operator bar) + minimum successful job count (recommended: `completedJobs >= 4`). Triggers Score reveal and Decker recruitment (same beat). Terminal recruitment for Merc/Razor/Tech opens earlier at KNOWN (`rep >= 50`).
   - Act 2 → Act 3: `completedJobs >= 9` + at least 4 **living** (non-flatlined) crew + at least 3 visited sites sharing the Score target's principal (including the Score target itself). The Decker gate is gone — the Decker is always assigned at Act 2 entry. The crew gate rewards keeping people alive; the principal-sites gate is the "casing" payoff — you've hit enough of the org's facilities to know how they operate. Triggers "final prep" phase and the `act-3-reveal` Hub beat on first qualifying Hub entry.
   - Score available: Act 3 + player-initiated (choose **THE SCORE** from the Hub job board after the Act 3 briefing).
 - **Score target designation:** At Act 2 entry, always synthesize a new CRITICAL-tier `LocationSite` from Curator lexicon as the Score target. The Score is a location the player hasn't seen — Act 2 contracts bias toward the same principal so the player learns about the organization before hitting the crown jewel. Existing roster sites are never promoted; they serve as intel and casing prep. Multiple persisted score targets, or score-tier sites missing `scoreTarget`, throw during Hub-entry arc evaluation.
@@ -148,7 +148,7 @@ Neural degradation is deferred until Cyberspace is fun enough to deserve a jack-
 
 **P3.M1.1 implementation note:** `Campaign` now owns a typed `arc` record (`arcStage`, `deckerRecruited`, `scoreRevealed`, `clockStarted`, `scoreAttempted`, `scoreCompleted`) plus an `arcStage` getter for Curator context. New snapshots serialize the record; pre-P3 snapshots normalize to Act 1; malformed persisted arc data throws during restore instead of being silently repaired.
 
-**P3.M1.2 implementation note:** Hub entry now runs a monotonic arc transition evaluator. Act 1 advances to Act 2 at `rep >= ARC_ACT_2_MIN_REP` (50 — the KNOWN tier floor) plus `completedJobs >= 4`, sets `scoreRevealed`, and auto-assigns a Decker to the crew. Higher rep tiers qualify too: a save that overshoots KNOWN into TRUSTED before the job gate is crossed must not stall in Act 1 (an early implementation checked for the KNOWN tier band exactly, which blocked TRUSTED saves). Act 2 advances to Act 3 once `completedJobs >= 9`, at least 4 non-flatlined crew, and at least 3 visited roster sites sharing the Score target's principal (including the target itself). The crew gate counts living members only — attrition blocks advancement. Successful extractions increment `completedJobs`, abort extractions do not. M1.2 does not synthesize the Score target — that remains P3.M1.3.
+**P3.M1.2 implementation note:** Hub entry now runs a monotonic arc transition evaluator. Act 1 advances to Act 2 at `rep >= ARC_ACT_2_MIN_REP` (65 — proven-operator bar, above the KNOWN recruitment floor) plus `completedJobs >= 4`, sets `scoreRevealed`, and auto-assigns a Decker to the crew. Higher rep tiers qualify too: a save that overshoots the rep floor before the job gate is crossed must not stall in Act 1. Terminal recruitment (`REP.RECRUIT_THRESHOLD = 50`) was inverted relative to the original M6 design so Stage 1 crew growth precedes the Score pitch. Act 2 advances to Act 3 once `completedJobs >= 9`, at least 4 non-flatlined crew, and at least 3 visited roster sites sharing the Score target's principal (including the target itself). The crew gate counts living members only — attrition blocks advancement. Successful extractions increment `completedJobs`, abort extractions do not. M1.2 does not synthesize the Score target — that remains P3.M1.3.
 
 **P3.M1.3 implementation note:** Score reveal always synthesizes a new CRITICAL-tier site from Curator lexicon `corp` principal and `corp/data/security/infrastructure/hidden` site tokens. Existing roster sites are never promoted — the Score is always a location the player hasn't visited yet. The synthesized site gets `scoreTarget: true`, `tier: 'score'`, and CRITICAL-footprint dimensions to support escalated hostile placement. Multiple persisted score targets, or score-tier sites missing `scoreTarget`, throw during Hub-entry arc evaluation.
 
diff --git a/src/game/Campaign.ts b/src/game/Campaign.ts
index 355cbad..c451bb7 100644
--- a/src/game/Campaign.ts
+++ b/src/game/Campaign.ts
@@ -59,8 +59,8 @@ import type { RunResult, Outcome } from './Run.js';
 
 /** Max remembered combat locations (P2.5.M7.2). One slot is reserved for Phase 3's score target. */
 export const SITE_ROSTER_CAP = 6;
-/** Minimum Rep to leave Act 1 — matches KNOWN tier floor (50). Higher tiers qualify too. */
-export const ARC_ACT_2_MIN_REP = 50;
+/** Minimum Rep to leave Act 1 — proven-operator bar (65). Recruitment opens earlier at KNOWN (50). */
+export const ARC_ACT_2_MIN_REP = 65;
 export const ARC_ACT_2_MIN_COMPLETED_JOBS = 4;
 export const ARC_ACT_3_MIN_COMPLETED_JOBS = 9;
 /** Minimum *living* crew size before the Score's final-prep stage unlocks. Starter 2 + Decker = 3, so 4 requires at least one additional recruit who hasn't flatlined. */
diff --git a/src/game/constants.ts b/src/game/constants.ts
index a6730be..1a4b7a7 100644
--- a/src/game/constants.ts
+++ b/src/game/constants.ts
@@ -540,8 +540,8 @@ export const REP = Object.freeze({
   /** Rep thresholds for NeutralCivilian behaviour. */
   NEUTRAL_IDLE_THRESHOLD: 70,
   NEUTRAL_FLEE_THRESHOLD: 30,
-  /** Rep threshold for recruitment. */
-  RECRUIT_THRESHOLD: 65,
+  /** Rep threshold for recruitment — matches KNOWN tier floor (50). */
+  RECRUIT_THRESHOLD: 50,
   /** Rep adjustments. */
   CLEAN_COMPLETION_BONUS: 10,
   CIVILIAN_KILL_PENALTY: -20,
diff --git a/src/game/hub/hubReveals.ts b/src/game/hub/hubReveals.ts
index 574fff8..7d52c44 100644
--- a/src/game/hub/hubReveals.ts
+++ b/src/game/hub/hubReveals.ts
@@ -194,7 +194,7 @@ export function migrateLegacyHubReveals(
   if (record.terminalExplained === true && !('terminalRecruitmentExplained' in record)) {
     const rep = context.rep ?? REP.START;
     const pending = context.pendingRecruitReward ?? false;
-    // Pre-split saves only set terminalExplained when recruitment unlocked (Rep ≥ 65).
+    // Pre-split saves only set terminalExplained when recruitment unlocked (Rep ≥ 50).
     if (rep >= REP.RECRUIT_THRESHOLD || pending) {
       return { ...record, terminalRecruitmentExplained: true };
     }
diff --git a/tests/unit/game/Campaign.test.ts b/tests/unit/game/Campaign.test.ts
index d4471c8..61f6809 100644
--- a/tests/unit/game/Campaign.test.ts
+++ b/tests/unit/game/Campaign.test.ts
@@ -659,17 +659,17 @@ test('restoreCampaign rejects corrupt Phase 3 arc snapshots', () => {
 });
 
 test('P3.M1.2: Act 1 does not advance until Rep and completed job gates both qualify', () => {
-  const lowRep = new Campaign({ seed: 42, rep: 49, completedJobs: 4 });
+  const lowRep = new Campaign({ seed: 42, rep: 64, completedJobs: 4 });
   assert.equal(lowRep.arcStage, 'act-1');
   assert.equal(lowRep.arc.scoreRevealed, false);
 
-  const lowJobs = new Campaign({ seed: 43, rep: 60, completedJobs: 3 });
+  const lowJobs = new Campaign({ seed: 43, rep: 80, completedJobs: 3 });
   assert.equal(lowJobs.arcStage, 'act-1');
   assert.equal(lowJobs.arc.scoreRevealed, false);
 });
 
-test('P3.M1.2: Act 1 advances to Act 2 at KNOWN Rep plus four completed jobs and assigns Decker', () => {
-  const campaign = new Campaign({ seed: 42, rep: 60, completedJobs: 4 });
+test('P3.M1.2: Act 1 advances to Act 2 at proven-operator Rep plus four completed jobs and assigns Decker', () => {
+  const campaign = new Campaign({ seed: 42, rep: 65, completedJobs: 4 });
 
   assert.equal(campaign.arcStage, 'act-2');
   assert.equal(campaign.arc.scoreRevealed, true);
@@ -689,12 +689,12 @@ test('P3.M1.2: Act 1 advances to Act 2 at TRUSTED Rep when job gate is met', ()
   assert.equal(campaign.arc.deckerRecruited, true);
   assert.ok(
     campaign.crew.some(m => m.archetype === 'Decker'),
-    'TRUSTED Rep should not block Act 2 after overshooting KNOWN'
+    'TRUSTED Rep should not block Act 2 after overshooting the rep floor'
   );
 });
 
 test('P3.M1.2: successful extraction advances Act 2 when the final gate is crossed', () => {
-  const campaign = new Campaign({ seed: 42, rep: 49, completedJobs: 3 });
+  const campaign = new Campaign({ seed: 42, rep: 64, completedJobs: 3 });
   const member = campaign.crew[0];
   const run = campaign.deployCrewMember(
     member.id,
@@ -705,7 +705,7 @@ test('P3.M1.2: successful extraction advances Act 2 when the final gate is cross
   campaign.onJobEnd({ outcome: OUTCOME.EXIT, completed: true });
 
   assert.equal(campaign.completedJobs, 4);
-  assert.equal(campaign.rep, 50);
+  assert.equal(campaign.rep, 65);
   assert.equal(campaign.arcStage, 'act-2');
   assert.equal(campaign.arc.scoreRevealed, true);
   assert.equal(campaign.arc.deckerRecruited, true);
@@ -736,7 +736,7 @@ test('P3.M1.2: Act 2 gates — each Act 3 condition checked independently', () =
   // Gate: not enough jobs (crew and sites satisfied by default)
   const tooFewJobs = new Campaign({
     seed: 44,
-    rep: 60,
+    rep: 65,
     completedJobs: 8,
     siteRoster: [
       validSite({
@@ -775,7 +775,7 @@ test('P3.M1.2: Act 2 gates — each Act 3 condition checked independently', () =
   });
   assert.equal(attrition.arcStage, 'act-1', 'starts in Act 1 with low rep');
   attrition.crew[0].flatlined = true;
-  attrition.rep = 60;
+  attrition.rep = 65;
   attrition.enterHub();
   assert.equal(attrition.crew.length, 4, 'buildCrew trio + auto-Decker');
   assert.equal(attrition.crew.filter(m => !m.flatlined).length, 3, 'only 3 living');
@@ -784,7 +784,7 @@ test('P3.M1.2: Act 2 gates — each Act 3 condition checked independently', () =
   // Gate: not enough same-principal visited sites (2 of 3 required)
   const tooCasual = new Campaign({
     seed: 46,
-    rep: 60,
+    rep: 65,
     completedJobs: 9,
     siteRoster: [
       validSite({
@@ -804,7 +804,7 @@ test('P3.M1.2: Act 2 gates — each Act 3 condition checked independently', () =
   // Gate: score target never visited (synthesized, lastVisitedJob: 0)
   const noTargetVisit = new Campaign({
     seed: 47,
-    rep: 60,
+    rep: 65,
     completedJobs: 9,
   });
   const scoreTarget = noTargetVisit.siteRoster.find(s => s.scoreTarget);
@@ -817,7 +817,7 @@ test('P3.M1.2: Act 2 advances to Act 3 with 4 living crew and 3 visited same-pri
   const scorePrincipal = { id: 'matsuda', label: 'Matsuda', groups: ['corp'] };
   const campaign = new Campaign({
     seed: 42,
-    rep: 60,
+    rep: 65,
     completedJobs: 9,
     siteRoster: [
       validSite({
@@ -844,7 +844,7 @@ test('P3.M2: Decker assignment is idempotent — restored save with existing Dec
   });
   const campaign = new Campaign({
     seed: 42,
-    rep: 60,
+    rep: 65,
     completedJobs: 4,
     crew: [decker],
   });
@@ -855,7 +855,7 @@ test('P3.M2: Decker assignment is idempotent — restored save with existing Dec
 });
 
 test('P3.M2: Decker callsign does not collide with existing crew', () => {
-  const campaign = new Campaign({ seed: 42, rep: 60, completedJobs: 4 });
+  const campaign = new Campaign({ seed: 42, rep: 65, completedJobs: 4 });
   const decker = campaign.crew.find(m => m.archetype === 'Decker');
   assert.ok(decker);
   const otherCallsigns = campaign.crew.filter(m => m.archetype !== 'Decker').map(m => m.callsign);
@@ -868,7 +868,7 @@ test('P3.M2: Decker callsign does not collide with existing crew', () => {
 test('P3.M1.3: Act 2 entry always synthesizes a new CRITICAL-tier Score target', () => {
   const campaign = new Campaign({
     seed: 42,
-    rep: 60,
+    rep: 65,
     completedJobs: 4,
     siteRoster: [
       validSite({
@@ -900,7 +900,7 @@ test('P3.M1.3: Act 2 entry always synthesizes a new CRITICAL-tier Score target',
 });
 
 test('P3.M1.3: Act 2 entry synthesizes a Score target even when roster is empty', () => {
-  const campaign = new Campaign({ seed: 42, rep: 60, completedJobs: 4 });
+  const campaign = new Campaign({ seed: 42, rep: 65, completedJobs: 4 });
 
   assert.equal(campaign.arcStage, 'act-2');
   assert.equal(campaign.arc.scoreRevealed, true);
@@ -917,7 +917,7 @@ test('P3.M1.3: Act 2 entry synthesizes a Score target even when roster is empty'
 });
 
 test('P3.M1.3: designated Score target survives roster eviction at cap', () => {
-  const campaign = new Campaign({ seed: 42, rep: 60, completedJobs: 4 });
+  const campaign = new Campaign({ seed: 42, rep: 65, completedJobs: 4 });
   const targetId = campaign.siteRoster.find(site => site.scoreTarget)!.id;
 
   for (let i = 0; i < SITE_ROSTER_CAP; i++) {
@@ -934,7 +934,7 @@ test('P3.M1.3: multiple persisted Score targets crash instead of being normalize
     () =>
       new Campaign({
         seed: 42,
-        rep: 60,
+        rep: 65,
         completedJobs: 4,
         siteRoster: [
           validSite({ id: 'score-a', seed: '111', tier: 'score', scoreTarget: true }),
@@ -946,14 +946,14 @@ test('P3.M1.3: multiple persisted Score targets crash instead of being normalize
 });
 
 test('P3.M1.5: Clock ignores completedJobs until act-2/3 deploys cross grace', () => {
-  const freshAct2 = new Campaign({ seed: 42, rep: 60, completedJobs: 9 });
+  const freshAct2 = new Campaign({ seed: 42, rep: 65, completedJobs: 9 });
   assert.equal(freshAct2.arc.clockStarted, false);
   assert.equal(freshAct2.clockHeat, 0);
   assert.equal(freshAct2.scoreDeadlineJobsRemaining, CLOCK_ACT2_DEADLINE_JOBS);
 
   const heating = new Campaign({
     seed: 42,
-    rep: 60,
+    rep: 65,
     completedJobs: 9,
     clockJobsTaken: CLOCK_ACT2_GRACE_JOBS + 2,
   });
@@ -967,7 +967,7 @@ test('P3.M1.5: Clock ignores completedJobs until act-2/3 deploys cross grace', (
 
   const expired = new Campaign({
     seed: 43,
-    rep: 60,
+    rep: 65,
     completedJobs: 4,
     clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS,
   });
@@ -981,7 +981,7 @@ test('P3.M1.5: Clock ignores completedJobs until act-2/3 deploys cross grace', (
 test('P3.M1.5: clock loss requires Act 3 — Act 2 casing survives past the deploy deadline', () => {
   const act2PastDeadline = new Campaign({
     seed: 43,
-    rep: 60,
+    rep: 65,
     completedJobs: 6,
     clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS - 1,
   });
@@ -992,7 +992,7 @@ test('P3.M1.5: clock loss requires Act 3 — Act 2 casing survives past the depl
 
   const act3AtDeadline = new Campaign({
     seed: 43,
-    rep: 60,
+    rep: 65,
     completedJobs: 9,
     clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS,
     siteRoster: [
@@ -1031,7 +1031,7 @@ test('P3.M1.5: Act 3 entry clamps an over-budget clock to guarantee Score deploy
   const scorePrincipal = { id: 'matsuda', label: 'Matsuda', groups: ['corp'] };
   const campaign = new Campaign({
     seed: 42,
-    rep: 60,
+    rep: 65,
     completedJobs: 9,
     clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS,
     siteRoster: [
@@ -1062,7 +1062,7 @@ test('P3.M1.5: Act 3 entry clamps an over-budget clock to guarantee Score deploy
 test('P3.M1.5: endReason distinguishes score win, clock loss, and crew wipe', () => {
   const clockLoss = new Campaign({
     seed: 43,
-    rep: 60,
+    rep: 65,
     completedJobs: 4,
     clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS,
   });
@@ -1070,7 +1070,7 @@ test('P3.M1.5: endReason distinguishes score win, clock loss, and crew wipe', ()
 
   const scoreWin = new Campaign({
     seed: 44,
-    rep: 60,
+    rep: 65,
     completedJobs: 4,
     arc: {
       arcStage: 'score',
@@ -1089,7 +1089,7 @@ test('P3.M1.5: endReason distinguishes score win, clock loss, and crew wipe', ()
 
   const crewWipe = new Campaign({
     seed: 45,
-    rep: 60,
+    rep: 65,
     completedJobs: 2,
   });
   crewWipe.crew.forEach(member => {
@@ -1102,7 +1102,7 @@ test('P3.M1.5: endReason distinguishes score win, clock loss, and crew wipe', ()
 test('terminal result detection bypasses debrief for Score, terminal death, and Clock loss', () => {
   const scoreCampaign = new Campaign({
     seed: 44,
-    rep: 60,
+    rep: 65,
     completedJobs: 9,
     siteRoster: [
       validSite({
@@ -1141,7 +1141,7 @@ test('terminal result detection bypasses debrief for Score, terminal death, and
 
   const clockLoss = new Campaign({
     seed: 46,
-    rep: 60,
+    rep: 65,
     completedJobs: 9,
     clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS - 1,
     siteRoster: [
@@ -1177,7 +1177,7 @@ test('completed Score extraction settles synchronously before the exit move call
   let campaign!: Campaign;
   campaign = new Campaign({
     seed: 47,
-    rep: 60,
+    rep: 65,
     completedJobs: 9,
     onResult: result => {
       campaign.onJobEnd({
@@ -1218,7 +1218,7 @@ test('completed Score extraction settles synchronously before the exit move call
 test('P3.M1.5: Clock deadline does not end the campaign after the Score is attempted', () => {
   const campaign = new Campaign({
     seed: 42,
-    rep: 60,
+    rep: 65,
     completedJobs: 4,
     clockJobsTaken: CLOCK_ACT2_DEADLINE_JOBS,
     arc: {
@@ -1242,7 +1242,7 @@ test('P3.M1.7: Score contract is gated to Act 3 and marks attempted on deploymen
   const scorePrincipal = { id: 'matsuda', label: 'Matsuda', groups: ['corp'] };
   const campaign = new Campaign({
     seed: 42,
-    rep: 60,
+    rep: 65,
     completedJobs: 9,
     siteRoster: [
       validSite({
@@ -1282,7 +1282,7 @@ test('P3.M1.7: Score contract is gated to Act 3 and marks attempted on deploymen
 });
 
 test('a flatlined pre-Score Decker creates a free Terminal replacement lead', () => {
-  const campaign = new Campaign({ seed: 42, rep: 60, completedJobs: 4 });
+  const campaign = new Campaign({ seed: 42, rep: 65, completedJobs: 4 });
   const original = campaign.crew.find(member => member.archetype === 'Decker');
   assert.ok(original);
   campaign.flatlineMember(original.id);
@@ -1301,7 +1301,7 @@ test('the Score remains unavailable until a living replacement Decker is recruit
   const scorePrincipal = { id: 'matsuda', label: 'Matsuda', groups: ['corp'] };
   const campaign = new Campaign({
     seed: 42,
-    rep: 60,
+    rep: 65,
     completedJobs: 9,
     siteRoster: [
       validSite({
@@ -1333,7 +1333,7 @@ test('P3.M1.7: completed Score contract records campaign win state', () => {
   const campaign = new Campaign({
     seed: 42,
     credits: 25,
-    rep: 60,
+    rep: 65,
     completedJobs: 9,
     siteRoster: [
       validSite({
@@ -1365,7 +1365,7 @@ test('a Decker flatline during the Score ends the campaign explicitly', () => {
   const scorePrincipal = { id: 'matsuda', label: 'Matsuda', groups: ['corp'] };
   const campaign = new Campaign({
     seed: 42,
-    rep: 60,
+    rep: 65,
     completedJobs: 9,
     siteRoster: [
       validSite({
@@ -1406,14 +1406,14 @@ test('a Decker flatline during the Score ends the campaign explicitly', () => {
 
 // ─── Recruitment ────────────────────────────────────────────────────────
 
-test('generateRecruits returns 1–2 candidates when Rep ≥ 65', () => {
-  const campaign = new Campaign({ seed: 99, rep: 65 });
+test('generateRecruits returns 1–2 candidates when Rep ≥ threshold', () => {
+  const campaign = new Campaign({ seed: 99, rep: 50 });
   assert.ok(campaign.availableRecruits.length >= 1);
   assert.ok(campaign.availableRecruits.length <= 2);
 });
 
-test('generateRecruits returns empty when Rep < 65', () => {
-  const campaign = new Campaign({ seed: 99, rep: 64 });
+test('generateRecruits returns empty when Rep < threshold', () => {
+  const campaign = new Campaign({ seed: 99, rep: 49 });
   assert.equal(campaign.availableRecruits.length, 0);
 });
 
@@ -1500,7 +1500,7 @@ test('recruit() throws for unknown recruitId', () => {
 });
 
 test('recruit() throws when Rep drops below threshold before recruiting', () => {
-  const campaign = new Campaign({ seed: 7, rep: 65 });
+  const campaign = new Campaign({ seed: 7, rep: 50 });
   assert.ok(campaign.availableRecruits.length > 0, 'Precondition: has recruits');
   const recruit = campaign.availableRecruits[0];
   // Drop rep below threshold after recruits were generated
@@ -1553,7 +1553,7 @@ test('backfillRecruitsIfEligible fills empty pool when Rep meets threshold', ()
 });
 
 test('backfillRecruitsIfEligible is a no-op when Rep is below threshold', () => {
-  const campaign = new Campaign({ seed: 3, rep: 50 });
+  const campaign = new Campaign({ seed: 3, rep: 49 });
   assert.equal(campaign.availableRecruits.length, 0);
   campaign.backfillRecruitsIfEligible();
   assert.equal(campaign.availableRecruits.length, 0);
@@ -1684,7 +1684,7 @@ test('deployCrewMember does NOT double-grant breaching charge if already carried
 });
 
 test('recruitInitial does not require Rep gate', () => {
-  // Fresh campaign has rep=20, below the 65 threshold — but initial
+  // Fresh campaign has rep=20, below the recruitment threshold — but initial
   // recruitment bypasses the gate.
   const campaign = new Campaign({ seed: 42, crew: [], rep: 20 });
   campaign.generateInitialCandidates();
diff --git a/tests/unit/game/campaignSummary.test.ts b/tests/unit/game/campaignSummary.test.ts
index a06fcd2..4e4abf9 100644
--- a/tests/unit/game/campaignSummary.test.ts
+++ b/tests/unit/game/campaignSummary.test.ts
@@ -53,7 +53,7 @@ test('Score completion summary uses post-settlement jobs, Rep, and Credits', ()
     id: 'campaign-score',
     seed: 42,
     credits: 125,
-    rep: 60,
+    rep: 65,
     completedJobs: 9,
     siteRoster: [
       validSite(),
@@ -79,7 +79,7 @@ test('Score completion summary uses post-settlement jobs, Rep, and Credits', ()
   assert.equal(record.result, 'win');
   assert.equal(record.endReason, 'score-complete');
   assert.equal(record.completedJobs, 10);
-  assert.equal(record.rep, 67);
+  assert.equal(record.rep, 72);
   assert.equal(record.credits, 125 + SCORE_CREDITS_REWARD);
   assert.equal('salvage' in record, false);
   assert.ok(record.crewRoster.some(member => member.archetype === 'Decker'));
diff --git a/tests/unit/game/cyber/cyberPersistence.test.ts b/tests/unit/game/cyber/cyberPersistence.test.ts
index cbc4c20..11ff58c 100644
--- a/tests/unit/game/cyber/cyberPersistence.test.ts
+++ b/tests/unit/game/cyber/cyberPersistence.test.ts
@@ -357,7 +357,7 @@ test('a legacy Decker record without cyber stats restores with base stats', () =
 // --- Decker cyber stats: campaign crew path -------------------------------------------
 
 function act2CampaignWithDecker(): Campaign {
-  const campaign = new Campaign({ seed: 42, rep: 60, completedJobs: 4 });
+  const campaign = new Campaign({ seed: 42, rep: 65, completedJobs: 4 });
   assert.ok(campaign.crew.some(m => m.archetype === 'Decker'));
   return campaign;
 }
diff --git a/tests/unit/game/hub/cyberContract.test.ts b/tests/unit/game/hub/cyberContract.test.ts
index e9e7bf7..3d10711 100644
--- a/tests/unit/game/hub/cyberContract.test.ts
+++ b/tests/unit/game/hub/cyberContract.test.ts
@@ -186,7 +186,7 @@ test('cyber-capable board generation is deterministic per seed', () => {
 
 /** Act-2 campaign whose arc transition has auto-assigned a Decker (P3.M1.2). */
 function act2CampaignWithDecker(): Campaign {
-  const campaign = new Campaign({ seed: 42, rep: 60, completedJobs: 4 });
+  const campaign = new Campaign({ seed: 42, rep: 65, completedJobs: 4 });
   assert.equal(campaign.arcStage, 'act-2');
   assert.ok(campaign.crew.some(m => m.archetype === 'Decker'));
   return campaign;
diff --git a/tests/unit/game/hub/hubReveals.test.ts b/tests/unit/game/hub/hubReveals.test.ts
index 584d071..13c56aa 100644
--- a/tests/unit/game/hub/hubReveals.test.ts
+++ b/tests/unit/game/hub/hubReveals.test.ts
@@ -131,7 +131,7 @@ test('terminal recruitment reveal when Rep meets threshold', () => {
 
 test('Score reveal presents the target and assigns a Decker when Act 2 opens', () => {
   const campaign = hubCampaign({
-    rep: 60,
+    rep: 65,
     completedJobs: 4,
     hubReveals: {
       terminalExplained: true,
@@ -163,7 +163,7 @@ test('Score reveal presents the target and assigns a Decker when Act 2 opens', (
 
 test('Clock reveal fires after grace deploys once Score briefing was dismissed', () => {
   const campaign = hubCampaign({
-    rep: 60,
+    rep: 65,
     completedJobs: 4,
     clockJobsTaken: CLOCK_ACT2_GRACE_JOBS,
     hubReveals: {
@@ -192,7 +192,7 @@ test('Act 3 reveal presents THE SCORE when final prep unlocks', () => {
   const scorePrincipal = { id: 'matsuda', label: 'Matsuda', groups: ['corp'] as const };
   const campaign = new Campaign({
     seed: 42,
-    rep: 60,
+    rep: 65,
     completedJobs: 9,
     hubReveals: {
       terminalExplained: true,
@@ -263,7 +263,7 @@ test('Act 3 reveal presents THE SCORE when final prep unlocks', () => {
 
 test('Score reveal takes priority over clinic when Act 2 opens with injured crew', () => {
   const campaign = hubCampaign({
-    rep: 60,
+    rep: 65,
     completedJobs: 4,
     hubReveals: {
       terminalExplained: true,
diff --git a/tests/unit/game/persistence.test.ts b/tests/unit/game/persistence.test.ts
index bf496ac..416b0b0 100644
--- a/tests/unit/game/persistence.test.ts
+++ b/tests/unit/game/persistence.test.ts
@@ -472,7 +472,7 @@ test('campaign snapshot/restore round-trips campaign scope', () => {
   // shape survives without scrap-only flattening).
   campaign.salvage = makeSalvage({ scrap: 3, chips: 2, bio: 1, data: 1 });
   campaign.credits = 90;
-  campaign.rep = 62;
+  campaign.rep = 49;
   campaign.meta = { someFlag: true };
   campaign.crew[1].flatlined = true;
   campaign.enterHub();
@@ -485,7 +485,7 @@ test('campaign snapshot/restore round-trips campaign scope', () => {
   assert.deepEqual(restored.salvage, makeSalvage({ scrap: 3, chips: 2, bio: 1, data: 1 }));
   assert.equal(totalSalvage(restored.salvage), 7);
   assert.equal(restored.credits, 90);
-  assert.equal(restored.rep, 62);
+  assert.equal(restored.rep, 49);
   assert.deepEqual(restored.meta, { someFlag: true });
   assert.equal(restored.crew[1].flatlined, true);
 });

From 7915e60f7391256051574a682c61b29b2203d709 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Mon, 15 Jun 2026 08:19:33 -0700
Subject: [PATCH 35/55] fix build

---
 index.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.ts b/index.ts
index 4091c1b..19143e9 100644
--- a/index.ts
+++ b/index.ts
@@ -3,7 +3,7 @@
  * Orchestration lives in `/src/shell/shellRuntime.ts` via {@link GameShell}.
  */
 
-import { gameShell } from '/src/shell/GameShell.js';
+import * as gameShell from '/src/shell/shellRuntime.js';
 
 import '/components/ConfirmationModal.js';
 import '/components/UpdateNotification.js';

From 905e3df3451c2c14916c8be272023dc122829b50 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Mon, 15 Jun 2026 09:27:28 -0700
Subject: [PATCH 36/55] tweak cyberspace palette

---
 src/render/palette.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/render/palette.ts b/src/render/palette.ts
index a8e2b92..df30b34 100644
--- a/src/render/palette.ts
+++ b/src/render/palette.ts
@@ -68,8 +68,8 @@ export const UNSEEN_GLYPH = Object.freeze({ char: '·', fg: '#1a1a1a' });
 export type TilesetId = 'meat' | 'cyber';
 
 const CYBER_TILE_GLYPH: Partial<Record<TileId, Glyph>> = {
-  [TILE.FLOOR]: { char: '·', fg: '#0e6b66' },
-  [TILE.WALL]: { char: '▒', fg: '#c23bd4' },
+  [TILE.FLOOR]: { char: '÷', fg: '#5e6b66' },
+  [TILE.WALL]: { char: '▒', fg: '#c2e0d4' },
 };
 
 export function glyphForTile(

From 4019bfe2cd036b3a62bb52313e8f3ff51a4e3554 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Mon, 15 Jun 2026 10:25:45 -0700
Subject: [PATCH 37/55] whoops fix cyber tileset test

---
 tests/unit/render/cyberTileset.test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/unit/render/cyberTileset.test.ts b/tests/unit/render/cyberTileset.test.ts
index 0cb59a3..4dcbdcc 100644
--- a/tests/unit/render/cyberTileset.test.ts
+++ b/tests/unit/render/cyberTileset.test.ts
@@ -22,7 +22,7 @@ test('cyber tiles render distinct glyphs from meat', () => {
   const meatWall = glyphForTile(TILE.WALL as TileId);
   const cyberWall = glyphForTile(TILE.WALL as TileId, undefined, 'cyber');
 
-  assert.equal(cyberFloor.char, '·');
+  assert.equal(cyberFloor.char, '÷');
   assert.equal(cyberWall.char, '▒');
   assert.notDeepEqual(cyberFloor, meatFloor);
   assert.notDeepEqual(cyberWall, meatWall);

From 26355a0dd306b59ddb27836790f778a4bdc7f77d Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Mon, 15 Jun 2026 11:01:10 -0700
Subject: [PATCH 38/55] dual-deploy foundation

---
 components/RunBriefing.ts                |  40 +++-
 docs/phase-3-plan.md                     |  42 ++--
 src/game/Campaign.ts                     |  46 ++++-
 src/game/Run.ts                          |  57 +++++-
 src/game/persistence.ts                  |  38 +++-
 src/shell/shellRuntime.ts                |  13 +-
 tests/unit/game/cyber/dualDeploy.test.ts | 232 +++++++++++++++++++++++
 7 files changed, 432 insertions(+), 36 deletions(-)
 create mode 100644 tests/unit/game/cyber/dualDeploy.test.ts

diff --git a/components/RunBriefing.ts b/components/RunBriefing.ts
index 420b577..b465c5c 100644
--- a/components/RunBriefing.ts
+++ b/components/RunBriefing.ts
@@ -329,11 +329,28 @@ class RunBriefing extends HTMLElement {
   }
 
   /**
-   * P3.M3.1: Cyberspace contracts can only deploy the Decker — every other
-   * row renders disabled with a NEEDS DECKER tag.
+   * P3.M4.1: a Cyberspace dual-deploy auto-includes the Decker (the jack-in
+   * operator) and asks the player to pick the *meat partner* who rides along.
+   * The Decker row renders locked (CYBER OP); living non-Deckers are the
+   * selectable partners.
+   *
+   * Solo fallback (P3.M3 behaviour): if no living non-Decker is available, the
+   * dual-deploy is impossible — only the Decker can deploy, so other rows show
+   * NEEDS DECKER and the run goes in solo.
    */
+  #cyberPartnerMode(): boolean {
+    return (
+      !!this.#contract &&
+      contractRequiresCyberspace(this.#contract) &&
+      this.#crew.some(member => member.archetype !== 'Decker' && !member.flatlined)
+    );
+  }
+
   #rowGate(): CrewRowGate | null {
     if (!this.#contract || !contractRequiresCyberspace(this.#contract)) return null;
+    if (this.#cyberPartnerMode()) {
+      return member => (member.archetype === 'Decker' ? 'CYBER OP' : null);
+    }
     return member => (member.archetype === 'Decker' ? null : 'NEEDS DECKER');
   }
 
@@ -407,11 +424,24 @@ class RunBriefing extends HTMLElement {
   }
 
   #commit() {
-    const member = this.#selectedMember;
-    if (!this.#contract || !member || !this.#deployable(member)) return;
+    const selected = this.#selectedMember;
+    if (!this.#contract || !selected || !this.#deployable(selected)) return;
+    // P3.M4.1: in dual-deploy mode the selected row is the meat partner and the
+    // Decker auto-attaches as the jack-in operator; otherwise the selected row
+    // deploys solo (non-cyber, or cyber with no partner available).
+    let memberId = selected.id;
+    let partnerId: string | null = null;
+    if (this.#cyberPartnerMode()) {
+      const decker = this.#crew.find(
+        member => member.archetype === 'Decker' && !member.flatlined
+      );
+      if (!decker) return; // cyber board invariant: a living Decker exists
+      memberId = decker.id;
+      partnerId = selected.id;
+    }
     this.dispatchEvent(
       new CustomEvent('deploy', {
-        detail: { memberId: member.id, contract: cloneContract(this.#contract) },
+        detail: { memberId, partnerId, contract: cloneContract(this.#contract) },
       })
     );
   }
diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index d384c0a..6901df0 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -27,7 +27,7 @@ On contracts with a Cyberspace component, the player **dual-deploys**: a Meatspa
 
 - Reuses the existing single-operator control model twice (no squad tactics required).
 - Tension is purely **attention allocation**: every turn spent in Cyberspace is a turn the Meatspace operator isn't moving, while corp drones keep closing in — and vice versa.
-- The flip is a **free action** (or 1 AP — TBD). The PIP / CCTV window from the blueprint shows the inactive layer in miniature.
+- The flip is a **free action** (resolved 2026-06-15; AP cost may be revisited after playtest). The PIP / CCTV window from the blueprint shows the inactive layer in miniature.
 
 ### The Decker
 
@@ -44,7 +44,7 @@ A new **player archetype** recruited mid-campaign (late Act 1 / start of Act 2),
 | P3.M1 — Campaign arc structure | ✅ Done |
 | P3.M2 — The Decker archetype | ✅ Done |
 | P3.M3 — Cyberspace grid + ICE | ✅ Done (full ICE roster: Probe, Spark, Guardian) |
-| P3.M4 — Simstim flip (dual-deploy) | 🔲 Planned |
+| P3.M4 — Simstim flip (dual-deploy) | 🟡 In progress (M4.1 dual-deploy reservation done) |
 | P3.M5 — The Score (climactic mission) | 🔲 Planned |
 | P3.M6 — Chronicle (campaign narrative memory) | 🟡 End-summary foundation shipped |
 
@@ -309,37 +309,47 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 
 ---
 
-### P3.M4 — Simstim flip (dual-deploy) 🔲
+### P3.M4 — Simstim flip (dual-deploy) 🟡
 
 **Depends on:** P3.M2 (Decker), P3.M3 (Cyberspace grid). This is the integration milestone.
 
 **Goal:** The **simstim flip** — dual-deploy two operators (Meatspace + Decker in Cyberspace) with a flip mechanic that switches active control between layers. The PIP/CCTV window shows the inactive layer.
 
+**Resolved design decisions (2026-06-15):**
+
+- **Partner spawns at jack-in, not at mission start.** A Cyberspace contract is selected as a dual-deploy (Decker + meat partner), but pre-jack-in the run is the existing solo-Decker mission — the partner is *reserved* at deploy and only spawns onto the meat grid (a random safe cell, behind cover, out of immediate danger) the moment the Decker jacks in.
+- **Control stays in Meatspace after jack-in until the first flip.** On jack-in the freshly-spawned partner is the active operator; the player enters Cyberspace only on the first explicit flip.
+- **Deploy UX:** the Decker is auto-included as the jack-in operator; the player picks the living meat partner. If no living non-Decker is available, the run falls back to a solo Decker deploy (the P3.M3 path).
+- **Flip is a free action** that swaps the active operator among the live operators: pre-jack `{Decker}` (no-op), jacked `{partner(meat), avatar(cyber)}` (layer swap; Decker body frozen), post-jack-out `{Decker(meat), partner(meat)}` (meat↔meat).
+- **Forced jack-out at 1 HP:** the Decker's body cannot die while jacked in — a killing/critical hit clamps the body to 1 HP and ejects the Decker (alive) back to Meatspace. Cyber-side death (ICE depleting RAM) still flatlines. This retires the silent-meat-damage Score death vector from M3.7.
+
 **Scope:**
 
-- **Dual-deploy:** On contracts with a Cyberspace component, the player selects two operators: one for Meatspace, one (the Decker) for Cyberspace. Both are placed on their respective grids at mission start (Meatspace operator at spawn, Decker at the jack-in terminal's Cyberspace entry node).
-  - **Pre–jack-in phase:** The Decker starts in Meatspace, where they move and act normally. The player must reach a terminal and jack in (P2.5.M2.2 interact) to activate Cyberspace. Until jack-in, this is a normal single-grid mission.
-  - **Post–jack-in:** Cyberspace grid spawns. Flip mechanic activates. Decker's Meatspace body remains at the terminal — vulnerable, immobile, and targetable by corp hostiles (blueprint: "your physical body is a vegetable"). Secondary operator now enters the Meatspace grid.
+- **Dual-deploy:** On contracts with a Cyberspace component, the player selects two operators: the Decker (auto-included, the eventual Cyberspace avatar) and a meat partner. Only the Decker is placed at mission start — the partner is *reserved* (see the resolved decisions above) and spawns at jack-in.
+  - **Pre–jack-in phase:** The Decker starts solo in Meatspace, where they move and act normally. The player must reach a terminal and jack in (P2.5.M2.2 interact) to activate Cyberspace. Until jack-in, this is a normal single-grid mission.
+  - **Post–jack-in:** Cyberspace grid spawns; the reserved partner spawns into Meatspace at a safe cell and **becomes the active operator** (control stays in Meatspace until the first flip). The Decker's Meatspace body remains at the terminal — frozen, immobile, and targetable by corp hostiles (blueprint: "your physical body is a vegetable").
 - **The flip:** Switch active control between Meatspace operator and Decker. Active operator receives player input (move, attack, interact). Inactive operator holds position.
   - Cost: **free action** for the first implementation. AP cost can be revisited after playtesting, but the first version should make the new mental model easy to explore.
   - Can flip at any point during the active operator's turn (before or after spending AP).
 - **Turn structure:** Player turn → flip as desired → end turn → **both layers' hostile phases resolve** (corp drones move in Meatspace, ICE moves in Cyberspace). Both layers tick simultaneously.
 - **PIP / CCTV window:** The inactive layer renders in a small overlay (bottom right corner of the screen). Shows grid state, hostile positions, the other operator's status. Read-only — no input accepted in the PIP. The blueprint's "real-time CCTV showing your physical body's status" becomes this.
-- **Vulnerability:** While the Decker is jacked in, their Meatspace body is a valid target for corp hostiles. If the body is destroyed, the Decker is killed (flatline) and Cyberspace access is lost. The Meatspace operator's explicit job is to **protect the Decker's body** — or at least keep hostiles away from the terminal.
-- **Jack-out:** The Decker can voluntarily jack out (returns control to single-grid Meatspace). Or is forced out if their body takes critical damage. Jack-out despawns the Cyberspace grid (any unsatisfied Cyberspace objectives fail).
+- **Vulnerability:** While the Decker is jacked in, their Meatspace body is a valid target for corp hostiles. The body **cannot die while jacked in** — a killing/critical hit clamps it to 1 HP and forces a jack-out (resolved decision); only ICE depleting RAM flatlines the Decker outright. The Meatspace partner's explicit job is to **protect the Decker's body** — or at least keep hostiles away from the terminal.
+- **Jack-out:** The Decker can voluntarily jack out (returns control to single-grid Meatspace). Or is forced out when their body is driven to 1 HP. Jack-out despawns the Cyberspace grid (any unsatisfied Cyberspace objectives fail).
 - **Contracts without Cyberspace:** Single-deploy as today. The Decker deploys solo in Meatspace (no flip, no Cyberspace grid). Their drone override hack is their primary value. A pre-Score flatline opens one replacement Decker lead through the Terminal; a flatline during THE SCORE is campaign-terminal.
 - **Save invariant:** A run may be single-layer, pre-jack dual-deploy, or active dual-layer. Those states must be explicit. A save with `cyberspace.active = true` but no cyber grid/avatar, or with a Decker marked jacked-in but no Meatspace body anchor, is corrupt and must throw.
 
 **Integration slices:**
 
-| Slice | Change | Tests |
-|---|---|---|
-| **P3.M4.1 Dual deploy pre-jack** | Select Meatspace operator + Decker; both begin in Meatspace | deployment gates, placement, no Decker = no Cyberspace contract |
-| **P3.M4.2 Jacked body anchor** | Decker body becomes immobile target at terminal after jack-in | body targetable, movement rejected, death flatlines Decker |
-| **P3.M4.3 Flip command** | Free action swaps active input layer | input routed to active layer only, inactive holds position |
-| **P3.M4.4 Dual hostile phase** | End turn advances corp and ICE phases once each | deterministic order, both layers tick, no double AP refresh |
-| **P3.M4.5 PIP** | Inactive layer mini-render + status summary | desktop/mobile layout, no input capture |
-| **P3.M4.6 Jack-out** | Voluntary and forced jack-out transitions back to Meatspace | cleanup, objective failure rules, snapshot round-trip |
+| Slice | Status | Change | Tests |
+|---|---|---|---|
+| **P3.M4.1 Dual deploy** | ✅ Done | Reserve the meat partner alongside the Decker on a Cyberspace deploy; `Run.partnerMember`, deploy gates, persistence | deploy gates, partner shape, campaign + standalone round-trip |
+| **P3.M4.2 Jacked body anchor + partner spawn** | 🔲 | Decker body becomes immobile target at terminal after jack-in; partner spawns at a safe meat cell | body targetable, movement rejected, partner placement, round-trip |
+| **P3.M4.3 Flip command** | 🔲 | Free action swaps active input layer | input routed to active layer only, inactive holds position |
+| **P3.M4.4 Dual hostile phase** | 🔲 | End turn advances corp and ICE phases once each | deterministic order, both layers tick, no double AP refresh |
+| **P3.M4.5 PIP** | 🔲 | Inactive layer mini-render + status summary | desktop/mobile layout, no input capture |
+| **P3.M4.6 Jack-out** | 🔲 | Voluntary + forced (1-HP) jack-out transitions back to Meatspace | cleanup, objective failure rules, snapshot round-trip |
+
+**P3.M4.1 implementation note (2026-06-15):** A Cyberspace dual-deploy reserves a meat partner without spawning it. `Run.partnerMember: Crew | null` (validated non-Decker, living, distinct from the deployed operator) is set at construction; `Run.enterBriefing` forbids a partner on a non-cyber contract but does **not** require one (a solo Decker cyber run stays legal — the dual-deploy product rule is enforced by the briefing UI, not the model). `Campaign.deployCrewMember(memberId, contract, partnerId?)` gains the optional partner, records `Campaign.deployedPartnerId`, commits both operators (both clear job-scoped salvage at `onJobEnd`), and gates the partner (cyber-only, living, non-Decker, distinct, known id). `<run-briefing>` inverts its P3.M3.1 gate: on a cyber contract the Decker row is locked as `CYBER OP` and the player selects the living meat partner (Decker auto-attaches via the emitted `partnerId`); with no eligible partner it falls back to the solo `NEEDS DECKER` gate. Persistence: the reserved partner round-trips as an off-grid entity record (`RunSnapshot.partner`, throwaway `(0,0)` cell) for standalone restore, and re-binds to the canonical crew object via `partnerMemberId` on the campaign path (BRIEFING and COMBAT/RESULT). A partner record without a Cyberspace contract throws on restore. **Follow-up:** partner-death flatline accounting lands with M4.2 (the partner isn't on the field until jack-in); a fully crew-depleted player still cannot field a partner for THE SCORE — revisit if that edge proves too punishing.
 
 **Acceptance:**
 
diff --git a/src/game/Campaign.ts b/src/game/Campaign.ts
index c451bb7..8f51da0 100644
--- a/src/game/Campaign.ts
+++ b/src/game/Campaign.ts
@@ -219,6 +219,8 @@ export class Campaign {
   state: CampaignState;
   activeRun: Run | null;
   deployedMemberId: string | null;
+  /** P3.M4.1: the reserved meat partner on a dual-deploy. `null` on solo runs. */
+  deployedPartnerId: string | null;
   availableRecruits: Crew[];
   recruitedThisVisit: boolean;
   pendingRecruitReward: boolean;
@@ -326,6 +328,7 @@ export class Campaign {
     this.state = CAMPAIGN_STATE.HUB;
     this.activeRun = null;
     this.deployedMemberId = null;
+    this.deployedPartnerId = null;
     this.availableRecruits = [];
     this.recruitedThisVisit = false;
     this.pendingRecruitReward = false;
@@ -477,7 +480,7 @@ export class Campaign {
     this.#persist();
   }
 
-  deployCrewMember(memberId: string, contract: Contract): Run {
+  deployCrewMember(memberId: string, contract: Contract, partnerId?: string | null): Run {
     if (this.state !== CAMPAIGN_STATE.HUB) {
       throw new Error(`Campaign.deployCrewMember: illegal from ${this.state}`);
     }
@@ -488,13 +491,39 @@ export class Campaign {
     if (member.flatlined) {
       throw new Error(`Campaign.deployCrewMember: ${member.callsign ?? member.id} is flatlined`);
     }
+    const cyber = contractRequiresCyberspace(contract);
     // P3.M3.1: a Cyberspace contract is unwinnable without the one operator who
     // can jack in — fail loudly at the Hub boundary instead of starting it.
-    if (contractRequiresCyberspace(contract) && member.archetype !== 'Decker') {
+    if (cyber && member.archetype !== 'Decker') {
       throw new Error(
         `Campaign.deployCrewMember: contract "${contract.label}" requires a living Decker to jack in`
       );
     }
+    // P3.M4.1: a dual-deploy rides a meat partner alongside the Decker. The
+    // partner is optional at this layer (the briefing requires one for normal
+    // play, but a solo Decker cyber run stays legal); when supplied it must be
+    // a distinct, living, non-Decker operator. A partner on a non-cyber
+    // contract is a wiring bug.
+    const partner = partnerId ? this.getCrewMember(partnerId) : null;
+    if (partnerId) {
+      if (!cyber) {
+        throw new Error('Campaign.deployCrewMember: a meat partner requires a Cyberspace contract');
+      }
+      if (!partner) {
+        throw new Error(`Campaign.deployCrewMember: unknown partner "${partnerId}"`);
+      }
+      if (partner.flatlined) {
+        throw new Error(
+          `Campaign.deployCrewMember: partner ${partner.callsign ?? partner.id} is flatlined`
+        );
+      }
+      if (partner.archetype === 'Decker') {
+        throw new Error('Campaign.deployCrewMember: the meat partner cannot be a Decker');
+      }
+      if (partner.id === member.id) {
+        throw new Error('Campaign.deployCrewMember: partner must differ from the deployed operator');
+      }
+    }
     if (isScoreContract(contract)) {
       this.#beginScoreAttempt(contract);
     } else if (this.arc.arcStage === 'act-2' || this.arc.arcStage === 'act-3') {
@@ -503,8 +532,10 @@ export class Campaign {
     const deployedContract = this.#contractWithRememberedDimensions(contract);
     this.#tearDownHubWorld();
     this.deployedMemberId = member.id;
+    this.deployedPartnerId = partner?.id ?? null;
     this.activeRun = new Run({
       crewMember: member,
+      partnerMember: partner ?? undefined,
       seed: deployedContract.seed,
       // Replay prior-visit terrain mutations on revisits ([] for first visits).
       priorMutationDeltas: this.priorDeltasForContract(deployedContract),
@@ -593,13 +624,18 @@ export class Campaign {
     // Clear job-scoped salvage (extracted or forfeited on death).
     // Consumables persist in the crew member's inventory until used —
     // they're a permanent part of the loadout, not job-scoped.
-    const member = this.getCrewMember(this.deployedMemberId);
-    if (member?.inventory) {
-      member.inventory.salvage = emptySalvage();
+    // P3.M4.1: a dual-deploy commits the meat partner too — clear its
+    // job-scoped salvage on the same boundary as the primary operator.
+    for (const id of [this.deployedMemberId, this.deployedPartnerId]) {
+      const crew = id ? this.getCrewMember(id) : null;
+      if (crew?.inventory) {
+        crew.inventory.salvage = emptySalvage();
+      }
     }
 
     this.activeRun = null;
     this.deployedMemberId = null;
+    this.deployedPartnerId = null;
 
     if (failedScoreRun) {
       this.state = CAMPAIGN_STATE.ENDED;
diff --git a/src/game/Run.ts b/src/game/Run.ts
index 43adb61..a901017 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -301,6 +301,14 @@ export type RunSnapshot = {
   keyItems?: KeyItemSnapshot[];
   /** Terrain/entity mutations recorded during the run (P2.5.M7.1). Defaults to []. */
   mutationDeltas?: TileDelta[];
+  /**
+   * P3.M4.1: the reserved meat partner for a dual-deploy. Present only when a
+   * Cyberspace contract was deployed with a partner (the player-chosen meat
+   * operator who spawns on jack-in). Serialized as an off-grid entity record
+   * with a throwaway (0,0) position — the partner's real cell is computed at
+   * jack-in (P3.M4.2). Absent on solo deploys.
+   */
+  partner?: RunEntitySnapshot;
   /**
    * P3.M3: Cyberspace layer state. Present exactly when the contract requires
    * Cyberspace (`contractRequiresCyberspace`) — a mismatch in either direction
@@ -357,6 +365,8 @@ export type RunResult = {
 export type RunOptions = {
   id?: string;
   crewMember?: unknown;
+  /** P3.M4.1: the meat partner for a dual-deploy Cyberspace contract. */
+  partnerMember?: unknown;
   seed?: unknown;
   onPersist?: unknown;
   onResult?: unknown;
@@ -409,6 +419,12 @@ type TurnEndedPayload = {
 export class Run {
   id: string;
   crewMember: Crew;
+  /**
+   * P3.M4.1: the meat operator reserved alongside the Decker on a dual-deploy
+   * Cyberspace contract. `null` on solo deploys (no partner, or non-cyber).
+   * Reserved at deploy; spawned onto the meat grid at jack-in (P3.M4.2).
+   */
+  partnerMember: Crew | null;
   archetype: CrewArchetypeId;
   seed: number;
   rng: Rng;
@@ -445,6 +461,7 @@ export class Run {
   constructor({
     id,
     crewMember,
+    partnerMember,
     seed,
     onPersist,
     onResult,
@@ -465,6 +482,7 @@ export class Run {
     if (crewMember.flatlined) {
       throw new Error(`Run: cannot deploy flatlined crew member "${crewMember.id}"`);
     }
+    const partner = normalizePartnerMember(partnerMember, crewMember);
     if (onPersist !== undefined && typeof onPersist !== 'function') {
       throw new TypeError('Run: onPersist must be a function');
     }
@@ -495,6 +513,7 @@ export class Run {
 
     this.id = id ?? makeRunId(seed);
     this.crewMember = crewMember;
+    this.partnerMember = partner;
     this.archetype = archetypeOfCrew(crewMember);
     this.seed = seed >>> 0;
     this.rng = new Rng(this.seed);
@@ -536,7 +555,14 @@ export class Run {
     }
     this.contract = normalizeContractForRun(contract);
     // P3.M3: latch the Cyberspace state machine off the validated contract.
-    this.cyberspace = contractRequiresCyberspace(this.contract) ? { phase: 'dormant' } : null;
+    const cyber = contractRequiresCyberspace(this.contract);
+    this.cyberspace = cyber ? { phase: 'dormant' } : null;
+    // P3.M4.1: a meat partner only rides along on a Cyberspace dual-deploy.
+    // (The Decker spawns it at jack-in.) A partner on a non-cyber run is a
+    // wiring bug — crash rather than carry a reservation that never spawns.
+    if (!cyber && this.partnerMember) {
+      throw new Error('Run.enterBriefing: a meat partner requires a Cyberspace contract');
+    }
     this.objectiveTimer = freshObjectiveTimer();
     this.mapSeen.clear();
     this.state = RUN_STATE.BRIEFING;
@@ -840,6 +866,12 @@ export class Run {
       objectiveProgress: { securedPickups: world.securedPickupIds() },
       keyItems: this.keyItems.map(k => ({ id: k.id, label: k.label, doorId: k.doorId })),
       mutationDeltas: world.mutationDeltas.map(delta => ({ ...delta })),
+      // P3.M4.1: the reserved meat partner. Captured as an off-grid entity
+      // record with a (0,0) placeholder cell — the partner is not on any grid
+      // until jack-in (P3.M4.2) computes its real spawn. Absent on solo runs.
+      ...(this.partnerMember
+        ? { partner: { ...snapshotEntity(this.partnerMember), x: 0, y: 0 } }
+        : {}),
       // P3.M3: present exactly when the contract has a Cyberspace component.
       ...(this.cyberspace ? { cyberspace: snapshotCyberspace(this.cyberspace) } : {}),
     };
@@ -2705,6 +2737,29 @@ function archetypeOfCrew(entity: Entity): CrewArchetypeId {
   );
 }
 
+/**
+ * P3.M4.1: validate a dual-deploy meat partner. Returns the partner (or `null`
+ * when none supplied). Contract-dependent require/forbid lives in
+ * `enterBriefing` — this only enforces the partner's intrinsic shape so a
+ * malformed reservation crashes at construction rather than at jack-in.
+ */
+function normalizePartnerMember(partnerMember: unknown, primary: Crew): Crew | null {
+  if (partnerMember === undefined || partnerMember === null) return null;
+  if (!(partnerMember instanceof Crew)) {
+    throw new TypeError('Run: partnerMember must be a Crew member when supplied');
+  }
+  if (partnerMember instanceof Decker) {
+    throw new Error('Run: the meat partner cannot be a Decker (the Decker jacks in)');
+  }
+  if (partnerMember.flatlined) {
+    throw new Error(`Run: cannot deploy flatlined partner "${partnerMember.id}"`);
+  }
+  if (partnerMember.id === primary.id) {
+    throw new Error('Run: partner must differ from the deployed operator');
+  }
+  return partnerMember;
+}
+
 function freshTelemetry(archetype: CrewArchetypeId, seed: number): RunTelemetry {
   return {
     archetype,
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index db81e7c..26216ca 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -915,6 +915,8 @@ type CampaignActiveRunSnapshot = {
   type: 'run';
   state: RunState;
   crewMemberId: string;
+  /** P3.M4.1: reserved meat partner id for a dual-deploy. Absent on solo runs. */
+  partnerMemberId?: string | null;
   archetype: CrewArchetypeId;
   seed: number;
   rng: { seed: number; state: number };
@@ -943,6 +945,8 @@ export type CampaignSnapshot = {
   /** Phase 3 campaign arc state. Defaults to Act 1 for pre-P3 saves. */
   arc?: CampaignArc;
   deployedMemberId: string | null;
+  /** P3.M4.1: reserved meat partner id for a dual-deploy. Defaults to null. */
+  deployedPartnerId?: string | null;
   activeRun: CampaignActiveRunSnapshot | null;
   /** Recruit candidates available this hub visit. Defaults to [] for pre-P2.M6 saves. */
   availableRecruits?: CampaignCrewSnapshot[];
@@ -1014,6 +1018,7 @@ export function snapshotCampaign(campaign: Campaign): CampaignSnapshot {
     meta: { ...campaign.meta },
     arc: { ...campaign.arc },
     deployedMemberId: campaign.deployedMemberId,
+    deployedPartnerId: campaign.deployedPartnerId,
     activeRun: campaign.activeRun ? snapshotActiveRun(campaign.activeRun) : null,
     availableRecruits: campaign.availableRecruits.map(snapshotCrewMember),
     recruitedThisVisit: campaign.recruitedThisVisit,
@@ -1093,10 +1098,20 @@ export function restore(record: unknown, options: RestoreOptions = {}) {
   run.rng = new Rng(record.rng.seed);
   run.rng.setState(record.rng.state);
   run.contract = normalizeContract(record.contract);
-  run.cyberspace = restoreCyberspace(
-    record,
-    run.contract !== null && contractRequiresCyberspace(run.contract)
-  );
+  const runIsCyber = run.contract !== null && contractRequiresCyberspace(run.contract);
+  run.cyberspace = restoreCyberspace(record, runIsCyber);
+  // P3.M4.1: the reserved meat partner round-trips as an off-grid entity.
+  // Present ⇒ Cyberspace dual-deploy; a partner on a non-cyber run is corrupt.
+  if (record.partner) {
+    if (!runIsCyber) {
+      throw new Error('restore: run snapshot has a meat partner but no Cyberspace contract');
+    }
+    const partner = restoreEntity(record.partner, grid);
+    if (!(partner instanceof Crew) || partner instanceof Decker) {
+      throw new Error('restore: run partner must be a non-Decker Crew member');
+    }
+    run.partnerMember = partner;
+  }
   run.exitTile = record.exitTile ? { ...record.exitTile } : null;
   run.telemetry = { ...record.telemetry };
   run.objectiveTimer = normalizeObjectiveTimer(record.objectiveTimer);
@@ -1374,7 +1389,13 @@ export function restoreCampaign(record: unknown, options: RestoreCampaignOptions
         `restoreCampaign: activeRun references unknown crew "${record.activeRun.crewMemberId}"`
       );
     }
-    campaign.activeRun = restoreActiveRun(record.activeRun, member, {
+    // P3.M4.1: resolve the reserved meat partner against the canonical crew.
+    const partnerId = record.activeRun.partnerMemberId ?? null;
+    const partner = partnerId ? campaign.getCrewMember(partnerId) : null;
+    if (partnerId && !partner) {
+      throw new Error(`restoreCampaign: activeRun references unknown partner "${partnerId}"`);
+    }
+    campaign.activeRun = restoreActiveRun(record.activeRun, member, partner, {
       onPersist: () => options.onPersist?.(campaign),
       onResult: options.onResult,
     });
@@ -1394,6 +1415,7 @@ export function restoreCampaign(record: unknown, options: RestoreCampaignOptions
       );
     }
     campaign.deployedMemberId = member.id;
+    campaign.deployedPartnerId = partner?.id ?? null;
     campaign.state = CAMPAIGN_STATE.COMBAT;
     campaign.world = null;
     campaign.queue = null;
@@ -1726,6 +1748,7 @@ function snapshotActiveRun(run: Run): CampaignActiveRunSnapshot {
     type: 'run',
     state: run.state,
     crewMemberId: run.crewMember.id,
+    partnerMemberId: run.partnerMember?.id ?? null,
     archetype: run.archetype,
     seed: run.seed,
     rng: { seed: run.rng.seed, state: run.rng.state },
@@ -1741,16 +1764,21 @@ function snapshotActiveRun(run: Run): CampaignActiveRunSnapshot {
 function restoreActiveRun(
   record: CampaignActiveRunSnapshot,
   member: Crew,
+  partner: Crew | null,
   options: RestoreOptions
 ): Run {
   if (record.snapshot) {
     const restored = restore(record.snapshot, options).run;
     restored.crewMember = member;
+    // P3.M4.1: re-bind the partner to the canonical crew object (the snapshot
+    // carried a detached copy), matching how `crewMember` is re-linked.
+    restored.partnerMember = partner;
     return restored;
   }
   const run = new Run({
     id: record.id,
     crewMember: member,
+    partnerMember: partner ?? undefined,
     seed: record.seed,
     onPersist: options.onPersist,
     onResult: options.onResult,
diff --git a/src/shell/shellRuntime.ts b/src/shell/shellRuntime.ts
index c19eb43..ee1b621 100644
--- a/src/shell/shellRuntime.ts
+++ b/src/shell/shellRuntime.ts
@@ -769,11 +769,15 @@ function onBriefingDismiss() {
 
 function onBriefingDeploy(evt: Event) {
   if (!campaign) return;
-  const { memberId, contract } = (evt as CustomEvent<{ memberId?: string; contract?: Contract }>)
-    .detail;
+  const { memberId, partnerId, contract } = (
+    evt as CustomEvent<{ memberId?: string; partnerId?: string | null; contract?: Contract }>
+  ).detail;
   if (!memberId || !contract) return;
   const member = campaign.getCrewMember(memberId);
   if (!member || member.flatlined) return;
+  // P3.M4.1: dual-deploy rides a meat partner alongside the Decker.
+  const partner = partnerId ? campaign.getCrewMember(partnerId) : null;
+  if (partnerId && (!partner || partner.flatlined)) return;
   briefingEl.hide();
 
   let run = campaign.activeRun;
@@ -787,8 +791,9 @@ function onBriefingDeploy(evt: Event) {
       return;
     }
   } else {
-    run = campaign.deployCrewMember(member.id, contract);
-    flash(`CURATOR: ${member.callsign} takes ${contract.label}. JACKING IN.`);
+    run = campaign.deployCrewMember(member.id, contract, partnerId ?? null);
+    const partnerNote = partner ? ` + ${partner.callsign ?? partner.id}` : '';
+    flash(`CURATOR: ${member.callsign}${partnerNote} takes ${contract.label}. JACKING IN.`);
   }
 
   // Wire the run's confirmation callbacks (abort extraction, early jack-out).
diff --git a/tests/unit/game/cyber/dualDeploy.test.ts b/tests/unit/game/cyber/dualDeploy.test.ts
new file mode 100644
index 0000000..a9db952
--- /dev/null
+++ b/tests/unit/game/cyber/dualDeploy.test.ts
@@ -0,0 +1,232 @@
+/**
+ * P3.M4.1 — Dual-deploy: a Cyberspace contract reserves a meat partner who
+ * rides along with the Decker (the jack-in operator). This slice carries the
+ * partner reference through deploy, validation, and persistence; the partner
+ * does not spawn onto the meat grid until jack-in (P3.M4.2).
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { Run } from '../../../../src/game/Run.js';
+import { Campaign } from '../../../../src/game/Campaign.js';
+import { OUTCOME } from '../../../../src/game/Run.js';
+import { OBJECTIVES } from '../../../../src/game/hub/Curator.js';
+import { buildCrewMember } from '../../../../src/game/archetypes/index.js';
+import { Rng } from '../../../../src/rng.js';
+import { snapshot, restore, snapshotCampaign, restoreCampaign } from '../../../../src/game/persistence.js';
+import { testContractContext } from '../contractTestUtils.js';
+
+const fakeContract = (overrides = {}) => ({
+  seed: 12345,
+  objective: {
+    kind: OBJECTIVES.REACH_EXIT,
+    title: 'Extract clean',
+    briefing: 'Reach the exit.',
+  },
+  difficulty: 'standard',
+  threatCount: 1,
+  label: 'meat job',
+  context: testContractContext(OBJECTIVES.REACH_EXIT),
+  reward: { credits: 0, repDelta: 0 },
+  ...overrides,
+});
+
+const cyberContract = (overrides = {}) =>
+  fakeContract({
+    objective: {
+      kind: OBJECTIVES.DATA_NODE_SLICE,
+      title: 'Spike the server farm',
+      briefing: 'Jack in, slice the data node, then extract.',
+      params: { requiresCyberspace: true, count: 1 },
+    },
+    label: 'cyber casing job',
+    context: testContractContext(OBJECTIVES.DATA_NODE_SLICE),
+    ...overrides,
+  });
+
+const makeDecker = (id = 'crew-decker') =>
+  buildCrewMember('decker', { x: 0, y: 0 }, new Rng(100), { id });
+const makeMerc = (id = 'crew-merc') =>
+  buildCrewMember('merc', { x: 0, y: 0 }, new Rng(101), { id });
+
+// An Act-2 campaign: buildCrew trio (merc/razor/tech) + auto-assigned Decker.
+const act2Campaign = () => new Campaign({ seed: 42, rep: 65, completedJobs: 4 });
+const deckerOf = (c: Campaign) => c.crew.find(m => m.archetype === 'Decker')!;
+const meatOf = (c: Campaign) => c.crew.find(m => m.archetype !== 'Decker')!;
+
+// ---------------------------------------------------------------------------
+// Run model: partner shape validation
+// ---------------------------------------------------------------------------
+
+test('P3.M4.1: Run accepts a non-Decker meat partner on a cyber contract', () => {
+  const run = new Run({ crewMember: makeDecker(), partnerMember: makeMerc(), seed: 42 });
+  run.enterBriefing(cyberContract());
+  assert.equal(run.partnerMember?.id, 'crew-merc');
+});
+
+test('P3.M4.1: Run rejects a Decker as the meat partner', () => {
+  assert.throws(
+    () => new Run({ crewMember: makeDecker('a'), partnerMember: makeDecker('b'), seed: 42 }),
+    /partner cannot be a Decker/
+  );
+});
+
+test('P3.M4.1: Run rejects a flatlined partner', () => {
+  const partner = makeMerc();
+  partner.flatlined = true;
+  assert.throws(
+    () => new Run({ crewMember: makeDecker(), partnerMember: partner, seed: 42 }),
+    /flatlined partner/
+  );
+});
+
+test('P3.M4.1: Run rejects a partner identical to the deployed operator', () => {
+  const solo = makeMerc('crew-merc');
+  assert.throws(
+    () => new Run({ crewMember: makeMerc('crew-merc'), partnerMember: solo, seed: 42 }),
+    /partner must differ/
+  );
+});
+
+test('P3.M4.1: a partner on a non-cyber contract throws at enterBriefing', () => {
+  const run = new Run({ crewMember: makeDecker(), partnerMember: makeMerc(), seed: 42 });
+  assert.throws(() => run.enterBriefing(fakeContract()), /requires a Cyberspace contract/);
+});
+
+test('P3.M4.1: a solo Decker cyber run (no partner) stays legal', () => {
+  const run = new Run({ crewMember: makeDecker(), seed: 42 });
+  run.enterBriefing(cyberContract());
+  assert.equal(run.partnerMember, null);
+});
+
+// ---------------------------------------------------------------------------
+// Campaign deploy gates
+// ---------------------------------------------------------------------------
+
+test('P3.M4.1: deployCrewMember reserves the partner and records deployedPartnerId', () => {
+  const campaign = act2Campaign();
+  const decker = deckerOf(campaign);
+  const partner = meatOf(campaign);
+  const run = campaign.deployCrewMember(decker.id, cyberContract(), partner.id);
+  assert.equal(run.partnerMember?.id, partner.id);
+  assert.equal(campaign.deployedPartnerId, partner.id);
+  assert.equal(campaign.deployedMemberId, decker.id);
+});
+
+test('P3.M4.1: deployCrewMember rejects a Decker partner', () => {
+  const campaign = act2Campaign();
+  const decker = deckerOf(campaign);
+  // A second Decker can only arrive via direct construction — simulate by
+  // pointing the partner id at the Decker itself (same archetype guard fires).
+  assert.throws(
+    () => campaign.deployCrewMember(decker.id, cyberContract(), decker.id),
+    /partner must differ|cannot be a Decker/
+  );
+});
+
+test('P3.M4.1: deployCrewMember rejects a flatlined partner', () => {
+  const campaign = act2Campaign();
+  const decker = deckerOf(campaign);
+  const partner = meatOf(campaign);
+  partner.flatlined = true;
+  assert.throws(
+    () => campaign.deployCrewMember(decker.id, cyberContract(), partner.id),
+    /flatlined/
+  );
+});
+
+test('P3.M4.1: deployCrewMember rejects an unknown partner id', () => {
+  const campaign = act2Campaign();
+  const decker = deckerOf(campaign);
+  assert.throws(
+    () => campaign.deployCrewMember(decker.id, cyberContract(), 'ghost'),
+    /unknown partner/
+  );
+});
+
+test('P3.M4.1: deployCrewMember rejects a partner on a non-cyber contract', () => {
+  const campaign = act2Campaign();
+  const member = meatOf(campaign);
+  const other = campaign.crew.find(m => m !== member && m.archetype !== 'Decker')!;
+  assert.throws(
+    () => campaign.deployCrewMember(member.id, fakeContract(), other.id),
+    /requires a Cyberspace contract/
+  );
+});
+
+test('P3.M4.1: solo Decker cyber deploy leaves deployedPartnerId null', () => {
+  const campaign = act2Campaign();
+  const decker = deckerOf(campaign);
+  const run = campaign.deployCrewMember(decker.id, cyberContract());
+  assert.equal(run.partnerMember, null);
+  assert.equal(campaign.deployedPartnerId, null);
+});
+
+// ---------------------------------------------------------------------------
+// Persistence round-trips
+// ---------------------------------------------------------------------------
+
+test('P3.M4.1: partner survives a campaign round-trip in BRIEFING state', () => {
+  const campaign = act2Campaign();
+  const decker = deckerOf(campaign);
+  const partner = meatOf(campaign);
+  campaign.deployCrewMember(decker.id, cyberContract(), partner.id);
+
+  const restored = restoreCampaign(snapshotCampaign(campaign));
+  assert.equal(restored.deployedPartnerId, partner.id);
+  assert.equal(restored.activeRun?.partnerMember?.id, partner.id);
+  // Re-linked to the canonical crew object, not a detached copy.
+  assert.equal(restored.activeRun?.partnerMember, restored.getCrewMember(partner.id));
+});
+
+test('P3.M4.1: partner survives a campaign round-trip in COMBAT state', () => {
+  const campaign = act2Campaign();
+  const decker = deckerOf(campaign);
+  const partner = meatOf(campaign);
+  const run = campaign.deployCrewMember(decker.id, cyberContract(), partner.id);
+  run.enterCombat();
+
+  const restored = restoreCampaign(snapshotCampaign(campaign));
+  assert.equal(restored.deployedPartnerId, partner.id);
+  assert.equal(restored.activeRun?.partnerMember?.id, partner.id);
+  assert.equal(restored.activeRun?.partnerMember, restored.getCrewMember(partner.id));
+  assert.equal(restored.activeRun?.partnerMember?.flatlined, false);
+});
+
+test('P3.M4.1: partner survives a standalone run snapshot/restore', () => {
+  const run = new Run({ crewMember: makeDecker(), partnerMember: makeMerc(), seed: 42 });
+  run.enterBriefing(cyberContract());
+  run.enterCombat();
+
+  const restored = restore(snapshot(run)).run;
+  assert.equal(restored.partnerMember?.id, 'crew-merc');
+  assert.equal(restored.partnerMember?.archetype, 'Merc');
+  assert.equal(restored.partnerMember?.flatlined, false);
+});
+
+test('P3.M4.1: a partner record on a non-cyber run snapshot is rejected on restore', () => {
+  const run = new Run({ crewMember: makeDecker(), partnerMember: makeMerc(), seed: 42 });
+  run.enterBriefing(cyberContract());
+  run.enterCombat();
+  const snap = snapshot(run);
+  // Strip the Cyberspace component but keep the partner block — corrupt pairing.
+  delete snap.cyberspace;
+  snap.contract!.objective = { kind: OBJECTIVES.REACH_EXIT, title: 'x', briefing: 'y' };
+  assert.throws(() => restore(snap), /partner but no Cyberspace contract/);
+});
+
+// ---------------------------------------------------------------------------
+// Job end returns the partner
+// ---------------------------------------------------------------------------
+
+test('P3.M4.1: a clean extraction returns the partner and clears deployedPartnerId', () => {
+  const campaign = act2Campaign();
+  const decker = deckerOf(campaign);
+  const partner = meatOf(campaign);
+  const run = campaign.deployCrewMember(decker.id, cyberContract(), partner.id);
+  run.enterCombat();
+
+  campaign.onJobEnd({ outcome: OUTCOME.EXIT, completed: false });
+  assert.equal(campaign.deployedPartnerId, null);
+  assert.equal(campaign.getCrewMember(partner.id)?.flatlined, false);
+});

From 2ec17b9edfef974d52e6cbdf2be9487ca1e03f2e Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Mon, 15 Jun 2026 11:41:57 -0700
Subject: [PATCH 39/55] dual-deploy spawn

---
 docs/phase-3-plan.md                          |   4 +-
 src/game/Entity.ts                            |   8 +
 src/game/Run.ts                               | 191 +++++++++++++--
 src/game/World.ts                             |   5 +
 src/game/persistence.ts                       |  59 ++++-
 .../unit/game/cyber/jackInDualDeploy.test.ts  | 219 ++++++++++++++++++
 6 files changed, 452 insertions(+), 34 deletions(-)
 create mode 100644 tests/unit/game/cyber/jackInDualDeploy.test.ts

diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 6901df0..302c95e 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -343,12 +343,14 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 | Slice | Status | Change | Tests |
 |---|---|---|---|
 | **P3.M4.1 Dual deploy** | ✅ Done | Reserve the meat partner alongside the Decker on a Cyberspace deploy; `Run.partnerMember`, deploy gates, persistence | deploy gates, partner shape, campaign + standalone round-trip |
-| **P3.M4.2 Jacked body anchor + partner spawn** | 🔲 | Decker body becomes immobile target at terminal after jack-in; partner spawns at a safe meat cell | body targetable, movement rejected, partner placement, round-trip |
+| **P3.M4.2 Jacked body anchor + partner spawn** | ✅ Done (model) | Decker body freezes at port; partner spawns at a safe meat cell; `activeLayer`/`meatActor`/`deckerBody` on `Run` | body frozen+targetable, movement rejected, partner placement, determinism, round-trip |
 | **P3.M4.3 Flip command** | 🔲 | Free action swaps active input layer | input routed to active layer only, inactive holds position |
 | **P3.M4.4 Dual hostile phase** | 🔲 | End turn advances corp and ICE phases once each | deterministic order, both layers tick, no double AP refresh |
 | **P3.M4.5 PIP** | 🔲 | Inactive layer mini-render + status summary | desktop/mobile layout, no input capture |
 | **P3.M4.6 Jack-out** | 🔲 | Voluntary + forced (1-HP) jack-out transitions back to Meatspace | cleanup, objective failure rules, snapshot round-trip |
 
+**P3.M4.2 implementation note (2026-06-15):** Run-model layer only — the shell/`activeView` wiring and the flip *command* land with P3.M4.3. `jackIn` now captures the Decker as the **body**, freezes it (`Entity.frozen`, enforced in `World.canMoveEntity` → `'jacked-in'`; still a live, targetable grid entity), and — when a partner was reserved — spawns the partner via `#partnerSpawnTile` (deterministic, prefers cells no live hostile can see and that sit against cover; falls back safe → any-free; throws on a full grid), hands it control (`meatActor`), and keeps `activeLayer = 'meat'`. A solo jack-in has no partner, so `meatActor` stays the Decker and `activeLayer = 'cyber'` (M3 behaviour preserved). New `Run` surface: `meatActor` (controllable meat crew), `activeLayer` (`'meat'`|`'cyber'`), `deckerBody` getter, and `activeWorld`/`activeActor` now honor `activeLayer` (via `cyberInputActive`). `player` deliberately stays the Decker/body so body-targeting feedback and the PIP keep reading it. `#finalizeJackOut` unfreezes the body, returns meat control to the Decker, and resets `activeLayer`. Persistence: the off-grid `partner` record is written only while the cyber layer is `dormant` (post-jack the partner is a live grid entity); `activeLayer` is captured while `active`; restore disambiguates the two meat PLAYER crew (Decker = body, non-Decker = partner), re-freezes the body when `active`, and re-establishes `meatActor`/`activeLayer`. **Follow-up:** partner-death flatline accounting (the partner can now die on the field but the campaign doesn't yet flatline it) — must land before M4 closes.
+
 **P3.M4.1 implementation note (2026-06-15):** A Cyberspace dual-deploy reserves a meat partner without spawning it. `Run.partnerMember: Crew | null` (validated non-Decker, living, distinct from the deployed operator) is set at construction; `Run.enterBriefing` forbids a partner on a non-cyber contract but does **not** require one (a solo Decker cyber run stays legal — the dual-deploy product rule is enforced by the briefing UI, not the model). `Campaign.deployCrewMember(memberId, contract, partnerId?)` gains the optional partner, records `Campaign.deployedPartnerId`, commits both operators (both clear job-scoped salvage at `onJobEnd`), and gates the partner (cyber-only, living, non-Decker, distinct, known id). `<run-briefing>` inverts its P3.M3.1 gate: on a cyber contract the Decker row is locked as `CYBER OP` and the player selects the living meat partner (Decker auto-attaches via the emitted `partnerId`); with no eligible partner it falls back to the solo `NEEDS DECKER` gate. Persistence: the reserved partner round-trips as an off-grid entity record (`RunSnapshot.partner`, throwaway `(0,0)` cell) for standalone restore, and re-binds to the canonical crew object via `partnerMemberId` on the campaign path (BRIEFING and COMBAT/RESULT). A partner record without a Cyberspace contract throws on restore. **Follow-up:** partner-death flatline accounting lands with M4.2 (the partner isn't on the field until jack-in); a fully crew-depleted player still cannot field a partner for THE SCORE — revisit if that edge proves too punishing.
 
 **Acceptance:**
diff --git a/src/game/Entity.ts b/src/game/Entity.ts
index edac889..dc900b4 100644
--- a/src/game/Entity.ts
+++ b/src/game/Entity.ts
@@ -75,6 +75,13 @@ export class Entity {
   stealthed: boolean;
   passable: boolean;
   anchored: boolean;
+  /**
+   * P3.M4.2: a frozen entity cannot move under its own power (`canMoveEntity`
+   * refuses it). Set on the Decker's Meatspace body while it is jacked in — the
+   * body is "a vegetable" at the port: still targetable, still occupies its
+   * tile, but immobile until jack-out clears the flag.
+   */
+  frozen: boolean;
   displayName?: string;
   principalTag?: string;
 
@@ -134,6 +141,7 @@ export class Entity {
     this.stealthed = false;
     this.passable = passable;
     this.anchored = anchored;
+    this.frozen = false;
     this.displayName = displayName;
     this.principalTag = principalTag;
   }
diff --git a/src/game/Run.ts b/src/game/Run.ts
index a901017..7c1f337 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -49,6 +49,7 @@ import { isValidBlockingPlacement, checkPlacementIntegrity } from './placement.j
 import { makeSalvage, type TypedSalvage } from './salvage.js';
 import { Entity, type LootableEntity } from './Entity.js';
 import { Hostile } from './Hostile.js';
+import { hasLineOfSight } from './LineOfSight.js';
 import { Crew } from './Crew.js';
 import { Merc } from './archetypes/Merc.js';
 import { Razor } from './archetypes/Razor.js';
@@ -309,6 +310,11 @@ export type RunSnapshot = {
    * jack-in (P3.M4.2). Absent on solo deploys.
    */
   partner?: RunEntitySnapshot;
+  /**
+   * P3.M4.2: which layer held input at save time (`'meat'` | `'cyber'`).
+   * Present only while jacked in (cyber phase `active`); absent ⇒ `'meat'`.
+   */
+  activeLayer?: 'meat' | 'cyber';
   /**
    * P3.M3: Cyberspace layer state. Present exactly when the contract requires
    * Cyberspace (`contractRequiresCyberspace`) — a mismatch in either direction
@@ -432,7 +438,28 @@ export class Run {
   world: World | null;
   queue: TurnQueue | null;
   bus: EventBus | null;
+  /**
+   * The Decker (the deployed primary) on a cyber contract — and, once jacked
+   * in, the immobile Meatspace **body** at the port. On non-cyber runs this is
+   * simply the deployed operator. Body-targeting feedback and the forced
+   * jack-out (P3.M4.6) read `player` as the body; the *controllable* meat crew
+   * is `meatActor` (they diverge only after a dual-deploy jack-in).
+   */
   player: Crew | null;
+  /**
+   * P3.M4.2: the controllable Meatspace crew. Equals `player` until a
+   * dual-deploy jack-in spawns the partner, after which it points at the
+   * partner (the body freezes). The simstim flip (P3.M4.3) swaps `activeLayer`,
+   * not this — `meatActor` is always "who moves in Meatspace".
+   */
+  meatActor: Crew | null;
+  /**
+   * P3.M4.2/M4.3: which layer currently receives player input. Only meaningful
+   * while the cyber layer is active; `'meat'` everywhere else. On a dual-deploy
+   * jack-in control stays in Meatspace (`'meat'`) until the first flip; a solo
+   * Decker jack-in goes straight to `'cyber'` (no meat operator to hold).
+   */
+  activeLayer: 'meat' | 'cyber';
   contract: Contract | null;
   exitTile: GridPoint | null;
   /** P3.M3: Cyberspace state machine; `null` ⇔ no Cyberspace component. */
@@ -522,6 +549,8 @@ export class Run {
     this.queue = null;
     this.bus = null;
     this.player = null;
+    this.meatActor = null;
+    this.activeLayer = 'meat';
     this.contract = null;
     this.exitTile = null;
     this.cyberspace = null;
@@ -603,6 +632,10 @@ export class Run {
       applyMutationDeltas(this.world.grid, this.priorMutationDeltas);
     }
     this.player = this.#makePlayer(map.spawns.player);
+    // P3.M4.2: pre-jack-in the deployed operator is the sole controllable meat
+    // crew; the partner (if any) is reserved off-grid until jack-in.
+    this.meatActor = this.player;
+    this.activeLayer = 'meat';
     this.world.addEntity(this.player);
     for (let i = 0; i < map.doors.length; i++) {
       const a = map.doors[i]!;
@@ -866,12 +899,17 @@ export class Run {
       objectiveProgress: { securedPickups: world.securedPickupIds() },
       keyItems: this.keyItems.map(k => ({ id: k.id, label: k.label, doorId: k.doorId })),
       mutationDeltas: world.mutationDeltas.map(delta => ({ ...delta })),
-      // P3.M4.1: the reserved meat partner. Captured as an off-grid entity
-      // record with a (0,0) placeholder cell — the partner is not on any grid
-      // until jack-in (P3.M4.2) computes its real spawn. Absent on solo runs.
-      ...(this.partnerMember
+      // P3.M4.1/M4.2: the reserved meat partner. While the cyber layer is still
+      // dormant the partner is off-grid, so it serializes as an entity record
+      // with a (0,0) placeholder cell. Once jacked in (active/resolved) the
+      // partner is a live grid entity captured in `entities`, so the off-grid
+      // record is omitted to avoid a duplicate.
+      ...(this.partnerMember && this.cyberspace?.phase === 'dormant'
         ? { partner: { ...snapshotEntity(this.partnerMember), x: 0, y: 0 } }
         : {}),
+      // P3.M4.2: which layer holds input. Only meaningful while jacked in;
+      // captured so a mid-flip save restores to the same side.
+      ...(this.cyberspace?.phase === 'active' ? { activeLayer: this.activeLayer } : {}),
       // P3.M3: present exactly when the contract has a Cyberspace component.
       ...(this.cyberspace ? { cyberspace: snapshotCyberspace(this.cyberspace) } : {}),
     };
@@ -895,14 +933,40 @@ export class Run {
     return this.cyberspace?.phase === 'active';
   }
 
-  /** The world the shell should render/drive: cyber while jacked in, else meat. */
+  /** True while a cyber layer is live *and* the active layer is Cyberspace. */
+  get cyberInputActive(): boolean {
+    return this.cyberspace?.phase === 'active' && this.activeLayer === 'cyber';
+  }
+
+  /**
+   * The world the shell should render/drive. Honors the simstim flip
+   * (`activeLayer`): Cyberspace only while jacked in *and* flipped to cyber;
+   * Meatspace otherwise (including the post-jack-in pre-first-flip window).
+   */
   get activeWorld(): World | null {
-    return this.cyberspace?.phase === 'active' ? this.cyberspace.layer.world : this.world;
+    return this.cyberInputActive && this.cyberspace?.phase === 'active'
+      ? this.cyberspace.layer.world
+      : this.world;
   }
 
-  /** The actor the shell should control: the avatar while jacked in, else the player. */
+  /**
+   * The actor the shell should control: the cyber avatar while flipped to the
+   * grid, else the controllable Meatspace crew (`meatActor`, which is the
+   * partner after a dual-deploy jack-in, the Decker otherwise).
+   */
   get activeActor(): Crew | CyberAvatar | null {
-    return this.cyberspace?.phase === 'active' ? this.cyberspace.layer.avatar : this.player;
+    if (this.cyberInputActive && this.cyberspace?.phase === 'active') {
+      return this.cyberspace.layer.avatar;
+    }
+    return this.meatActor ?? this.player;
+  }
+
+  /**
+   * P3.M4.2: the Decker's immobile Meatspace body while jacked in (`null`
+   * otherwise). It is the deployed Decker (`player`) frozen at the port.
+   */
+  get deckerBody(): Crew | null {
+    return this.cyberspace?.phase === 'active' && this.player instanceof Decker ? this.player : null;
   }
 
   /**
@@ -931,14 +995,34 @@ export class Run {
     if (!(this.player instanceof Decker)) {
       throw new Error('Run.jackIn: only a Decker can enter the grid');
     }
+    const decker = this.player;
     const layer = CyberspaceLayer.build({
       contractSeed: this.contract.seed,
       difficulty: this.contract.difficulty,
-      decker: this.player,
+      decker,
       nodeCount: objectiveCount(this.contract),
     });
     this.cyberspace = { phase: 'active', layer };
     this.#wireCyberLayerListeners(layer);
+    // P3.M4.2: the Decker's body is now "a vegetable" at the port — freeze it
+    // (immobile, still targetable). If a meat partner was reserved, spawn it
+    // onto the grid and hand it control; the player stays in Meatspace until
+    // the first flip (P3.M4.3). A solo jack-in has no meat operator to hold, so
+    // control drops straight to the grid.
+    if (!this.world) {
+      throw new Error('Run.jackIn: COMBAT state without a meat world');
+    }
+    decker.frozen = true;
+    if (this.partnerMember) {
+      const spawn = this.#partnerSpawnTile(this.world, decker);
+      this.#initCombatant(this.partnerMember, spawn);
+      this.world.addEntity(this.partnerMember);
+      this.meatActor = this.partnerMember;
+      this.activeLayer = 'meat';
+    } else {
+      this.meatActor = decker;
+      this.activeLayer = 'cyber';
+    }
     // The latch transition must never be lost — autosave explicitly.
     if (this.onPersist) {
       this.onPersist(this.snapshot());
@@ -1010,6 +1094,15 @@ export class Run {
   #finalizeJackOut(layer: CyberspaceLayer, objectiveComplete: boolean): void {
     layer.teardown();
     this.cyberspace = { phase: 'resolved', objectiveComplete };
+    // P3.M4.2: the Decker is back in its body — unfreeze it, return control to
+    // Meatspace, and make the body the active operator. The partner (if any)
+    // remains on the grid as a second meat crew; the meat↔meat flip that lets
+    // the player switch between them lands with P3.M4.3.
+    if (this.player) {
+      this.player.frozen = false;
+      this.meatActor = this.player;
+    }
+    this.activeLayer = 'meat';
     // S5: the link is burned — re-jack-in refused for the rest of the run.
     this.#meatJackInPoint().burn();
     if (this.onPersist) {
@@ -1182,19 +1275,73 @@ export class Run {
   // ------------------------------------------------------------------
 
   #makePlayer(spawn: GridPoint): Crew {
-    this.crewMember.x = spawn.x;
-    this.crewMember.y = spawn.y;
-    this.crewMember.maxAp = 4;
-    this.crewMember.ap = this.crewMember.maxAp;
-    // HP persists across jobs — no reset. Armour Plating (via Finn) is
-    // the only Hub-side HP recovery. Stims are combat-only.
-    this.crewMember.alive = true;
-    this.crewMember.stealthed = false;
-    this.crewMember.initInventory();
-    if (this.crewMember instanceof Tech) {
-      this.crewMember.turretReady = true;
-    }
-    return this.crewMember;
+    return this.#initCombatant(this.crewMember, spawn);
+  }
+
+  /**
+   * Prep a crew member for the Meatspace grid — spawn position, full AP, combat
+   * inventory. HP persists across jobs (no reset; Armour Plating via Finn is the
+   * only Hub-side HP recovery, stims are combat-only). Shared by the deployed
+   * operator (`#makePlayer`) and the dual-deploy partner spawned at jack-in.
+   */
+  #initCombatant(crew: Crew, spawn: GridPoint): Crew {
+    crew.x = spawn.x;
+    crew.y = spawn.y;
+    crew.maxAp = 4;
+    crew.ap = crew.maxAp;
+    crew.alive = true;
+    crew.stealthed = false;
+    crew.frozen = false;
+    crew.initInventory();
+    if (crew instanceof Tech) {
+      crew.turretReady = true;
+    }
+    return crew;
+  }
+
+  /**
+   * P3.M4.2: choose a deterministic, *safe* Meatspace cell to drop the
+   * dual-deploy partner into at jack-in — "a random cell, not directly in
+   * danger, behind cover" (resolved decision). Candidates are free, unoccupied
+   * floor tiles off the body's tile; we prefer tiles no live hostile can see
+   * (geometry LOS) and that sit against cover (a wall neighbour). Falls back
+   * through safe → any-free so a hostile-saturated map still spawns the
+   * partner; an utterly full grid is corrupt and throws.
+   */
+  #partnerSpawnTile(world: World, body: Entity): GridPoint {
+    const grid = world.grid;
+    const hostiles = [...world.entities.values()].filter(
+      e => e.alive && e.faction !== FACTION.PLAYER && e.faction !== FACTION.NEUTRAL
+    );
+    const seen = (tx: number, ty: number): boolean =>
+      hostiles.some(h => hasLineOfSight(grid, h.x, h.y, tx, ty));
+    const hasCover = (tx: number, ty: number): boolean =>
+      !grid.isPassable(tx, ty - 1) ||
+      !grid.isPassable(tx, ty + 1) ||
+      !grid.isPassable(tx - 1, ty) ||
+      !grid.isPassable(tx + 1, ty);
+
+    const free: GridPoint[] = [];
+    const safe: GridPoint[] = [];
+    const safeCover: GridPoint[] = [];
+    // Stable iteration (row-major) keeps the candidate order deterministic.
+    for (let y = 0; y < grid.height; y++) {
+      for (let x = 0; x < grid.width; x++) {
+        if (x === body.x && y === body.y) continue;
+        if (!grid.isPassable(x, y)) continue;
+        if (world.entityAt(x, y)) continue;
+        const tile = { x, y };
+        free.push(tile);
+        if (seen(x, y)) continue;
+        safe.push(tile);
+        if (hasCover(x, y)) safeCover.push(tile);
+      }
+    }
+    const pool = safeCover.length ? safeCover : safe.length ? safe : free;
+    if (pool.length === 0) {
+      throw new Error('Run.#partnerSpawnTile: no free Meatspace cell to spawn the partner');
+    }
+    return pool[this.rng.intRange(0, pool.length)]!;
   }
 
   #unwireCombatListeners(): void {
diff --git a/src/game/World.ts b/src/game/World.ts
index b87c2e9..332586e 100644
--- a/src/game/World.ts
+++ b/src/game/World.ts
@@ -491,6 +491,11 @@ export class World {
     if (!entity.alive) {
       return { ok: false, reason: 'dead' };
     }
+    // P3.M4.2: a jacked-in Decker body is immobile — it holds its tile at the
+    // port while the Decker's attention is in Cyberspace.
+    if (entity.frozen) {
+      return { ok: false, reason: 'jacked-in' };
+    }
     if (dx === 0 && dy === 0) {
       return { ok: false, reason: 'no-op' };
     }
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index 26216ca..746ac1c 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -1074,18 +1074,31 @@ export function restore(record: unknown, options: RestoreOptions = {}) {
     grid.tiles[i] = record.grid.tiles[i] & 0xff;
   }
 
-  let player = null;
   const restoredEntities = record.entities.map(entityRec => restoreEntity(entityRec, grid));
-  for (const entity of restoredEntities) {
-    if (entity instanceof Crew && entity.faction === FACTION.PLAYER) {
-      if (player) {
-        throw new Error('restore: run snapshot has multiple player crew entities');
-      }
-      player = entity;
+  const playerCrew = restoredEntities.filter(
+    (e): e is Crew => e instanceof Crew && e.faction === FACTION.PLAYER
+  );
+  // P3.M4.2: a dual-deploy jack-in puts two PLAYER crew on the meat grid — the
+  // frozen Decker body (the deployed primary) and the partner. Disambiguate by
+  // archetype: the Decker is the body, the non-Decker is the partner.
+  let player: Crew;
+  let gridPartner: Crew | null = null;
+  if (playerCrew.length === 1) {
+    player = playerCrew[0]!;
+  } else if (playerCrew.length === 2) {
+    const deckers = playerCrew.filter(e => e instanceof Decker);
+    const others = playerCrew.filter(e => !(e instanceof Decker));
+    if (deckers.length !== 1 || others.length !== 1) {
+      throw new Error(
+        'restore: a dual-deploy meat layer needs exactly one Decker body and one partner'
+      );
     }
-  }
-  if (!player) {
+    player = deckers[0]!;
+    gridPartner = others[0]!;
+  } else if (playerCrew.length === 0) {
     throw new Error('restore: run snapshot has no player crew entity');
+  } else {
+    throw new Error(`restore: run snapshot has ${playerCrew.length} player crew entities`);
   }
 
   const run = new Run({
@@ -1100,17 +1113,41 @@ export function restore(record: unknown, options: RestoreOptions = {}) {
   run.contract = normalizeContract(record.contract);
   const runIsCyber = run.contract !== null && contractRequiresCyberspace(run.contract);
   run.cyberspace = restoreCyberspace(record, runIsCyber);
-  // P3.M4.1: the reserved meat partner round-trips as an off-grid entity.
-  // Present ⇒ Cyberspace dual-deploy; a partner on a non-cyber run is corrupt.
+  const cyberPhase = run.cyberspace?.phase ?? null;
+  // P3.M4.1/M4.2: resolve the meat partner. Pre-jack (dormant) it round-trips
+  // as an off-grid entity record; once jacked in it is a live grid entity
+  // (`gridPartner`). The two encodings are mutually exclusive.
   if (record.partner) {
     if (!runIsCyber) {
       throw new Error('restore: run snapshot has a meat partner but no Cyberspace contract');
     }
+    if (cyberPhase !== 'dormant') {
+      throw new Error(
+        'restore: off-grid partner record is only valid while the cyber layer is dormant'
+      );
+    }
+    if (gridPartner) {
+      throw new Error('restore: partner present both off-grid and on the meat grid');
+    }
     const partner = restoreEntity(record.partner, grid);
     if (!(partner instanceof Crew) || partner instanceof Decker) {
       throw new Error('restore: run partner must be a non-Decker Crew member');
     }
     run.partnerMember = partner;
+  } else if (gridPartner) {
+    run.partnerMember = gridPartner;
+  }
+
+  // P3.M4.2: re-establish the simstim flip state. While jacked in the Decker
+  // body is frozen and control sits with `meatActor` (the partner when one was
+  // spawned) unless the save had flipped into Cyberspace.
+  if (cyberPhase === 'active') {
+    player.frozen = true;
+    run.meatActor = gridPartner ?? player;
+    run.activeLayer = record.activeLayer === 'cyber' ? 'cyber' : 'meat';
+  } else {
+    run.meatActor = player;
+    run.activeLayer = 'meat';
   }
   run.exitTile = record.exitTile ? { ...record.exitTile } : null;
   run.telemetry = { ...record.telemetry };
diff --git a/tests/unit/game/cyber/jackInDualDeploy.test.ts b/tests/unit/game/cyber/jackInDualDeploy.test.ts
new file mode 100644
index 0000000..ee14244
--- /dev/null
+++ b/tests/unit/game/cyber/jackInDualDeploy.test.ts
@@ -0,0 +1,219 @@
+/**
+ * P3.M4.2 — Jacked body anchor + partner spawn (Run-model layer).
+ *
+ * On a dual-deploy jack-in the Decker's Meatspace body freezes at the port
+ * (immobile, still targetable) and the reserved partner spawns onto the meat
+ * grid as the controllable operator — control stays in Meatspace until the
+ * first flip (the flip command + shell wiring land in P3.M4.3). A solo Decker
+ * jack-in (no partner) drops straight into Cyberspace as before.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { Run } from '../../../../src/game/Run.js';
+import { JackInPoint } from '../../../../src/game/entities/JackInPoint.js';
+import { Decker } from '../../../../src/game/archetypes/Decker.js';
+import { CyberAvatar } from '../../../../src/game/cyber/CyberAvatar.js';
+import { FACTION } from '../../../../src/game/constants.js';
+import { buildCrewMember } from '../../../../src/game/archetypes/index.js';
+import { OBJECTIVES } from '../../../../src/game/hub/Curator.js';
+import { Rng } from '../../../../src/rng.js';
+import { snapshot, restore } from '../../../../src/game/persistence.js';
+import { testContractContext } from '../contractTestUtils.js';
+import type { World } from '../../../../src/game/World.js';
+import type { Entity } from '../../../../src/game/Entity.js';
+
+const cyberContract = (overrides = {}) => ({
+  seed: 12345,
+  objective: {
+    kind: OBJECTIVES.DATA_NODE_SLICE,
+    title: 'Spike the server farm',
+    briefing: 'Jack in, slice the data node, then extract.',
+    params: { requiresCyberspace: true, count: 1 },
+  },
+  difficulty: 'standard',
+  threatCount: 1,
+  label: 'cyber casing job',
+  context: testContractContext(OBJECTIVES.DATA_NODE_SLICE),
+  reward: { credits: 0, repDelta: 0 },
+  ...overrides,
+});
+
+const makeDecker = () => buildCrewMember('decker', { x: 0, y: 0 }, new Rng(100), { id: 'crew-decker' });
+const makeMerc = () => buildCrewMember('merc', { x: 0, y: 0 }, new Rng(101), { id: 'crew-merc' });
+
+function dualRun(seed = 12345) {
+  const run = new Run({ crewMember: makeDecker(), partnerMember: makeMerc(), seed });
+  run.enterBriefing(cyberContract({ seed }));
+  run.enterCombat();
+  return run;
+}
+
+function soloRun(seed = 12345) {
+  const run = new Run({ crewMember: makeDecker(), seed });
+  run.enterBriefing(cyberContract({ seed }));
+  run.enterCombat();
+  return run;
+}
+
+function jackInPoint(run: Run): JackInPoint {
+  const point = [...run.world!.entities.values()].find(e => e instanceof JackInPoint);
+  assert.ok(point, 'cyber contract placed a jack-in point');
+  return point as JackInPoint;
+}
+
+function adjacentFreeTile(world: World, target: Entity) {
+  for (let dy = -1; dy <= 1; dy++) {
+    for (let dx = -1; dx <= 1; dx++) {
+      if (dx === 0 && dy === 0) continue;
+      const x = target.x + dx;
+      const y = target.y + dy;
+      if (world.grid.inBounds(x, y) && world.grid.isPassable(x, y) && !world.entityAt(x, y)) {
+        return { x, y };
+      }
+    }
+  }
+  throw new Error(`no free tile adjacent to ${target.id}`);
+}
+
+/** Walk the Decker to the port and link — fires EVENT.JACK_IN → run.jackIn. */
+function jackIn(run: Run) {
+  const point = jackInPoint(run);
+  const spot = adjacentFreeTile(run.world!, point);
+  run.world!.relocateEntity(run.player!, spot.x, spot.y);
+  run.player!.refreshAp();
+  const result = point.interact(run.world!, run.player!);
+  assert.equal(result.ok, true, `link failed: ${result.message}`);
+  assert.equal(run.cyberspace?.phase, 'active');
+}
+
+// ---------------------------------------------------------------------------
+// Dual-deploy jack-in
+// ---------------------------------------------------------------------------
+
+test('P3.M4.2: dual jack-in freezes the body and spawns the partner in Meatspace', () => {
+  const run = dualRun();
+  const body = run.player!;
+  jackIn(run);
+
+  // The Decker body is the frozen anchor.
+  assert.equal(run.deckerBody, body);
+  assert.equal(body.frozen, true);
+  assert.ok(body instanceof Decker);
+
+  // The partner is now a live meat-grid entity and the controllable operator.
+  const partner = run.partnerMember!;
+  assert.equal(run.meatActor, partner);
+  assert.equal(run.world!.entities.get(partner.id), partner);
+  assert.equal(partner.alive, true);
+  assert.equal(partner.faction, FACTION.PLAYER);
+
+  // Control stays in Meatspace until the first flip.
+  assert.equal(run.activeLayer, 'meat');
+  assert.equal(run.activeActor, partner);
+  assert.equal(run.activeWorld, run.world);
+});
+
+test('P3.M4.2: the partner spawns on a valid, distinct, passable tile', () => {
+  const run = dualRun();
+  const body = run.player!;
+  jackIn(run);
+  const partner = run.partnerMember!;
+
+  assert.ok(run.world!.grid.inBounds(partner.x, partner.y));
+  assert.equal(run.world!.grid.isPassable(partner.x, partner.y), true);
+  assert.ok(partner.x !== body.x || partner.y !== body.y, 'partner is not on the body tile');
+  // Exactly one entity occupies the partner's tile — itself.
+  assert.equal(run.world!.entityAt(partner.x, partner.y), partner);
+});
+
+test('P3.M4.2: partner spawn is deterministic for a given seed', () => {
+  const a = dualRun(777);
+  const b = dualRun(777);
+  jackIn(a);
+  jackIn(b);
+  assert.deepEqual(
+    { x: a.partnerMember!.x, y: a.partnerMember!.y },
+    { x: b.partnerMember!.x, y: b.partnerMember!.y }
+  );
+});
+
+test('P3.M4.2: the frozen body refuses movement but stays on its tile', () => {
+  const run = dualRun();
+  jackIn(run);
+  const body = run.deckerBody!;
+  const { x, y } = body;
+  const check = run.world!.canMoveEntity(body, 1, 0);
+  assert.equal(check.ok, false);
+  assert.equal(check.reason, 'jacked-in');
+  // It is still present and targetable on the grid.
+  assert.equal(run.world!.entityAt(x, y), body);
+});
+
+// ---------------------------------------------------------------------------
+// Solo jack-in (no partner) — unchanged from M3
+// ---------------------------------------------------------------------------
+
+test('P3.M4.2: solo jack-in drops control into Cyberspace with no partner', () => {
+  const run = soloRun();
+  const body = run.player!;
+  jackIn(run);
+
+  assert.equal(run.partnerMember, null);
+  assert.equal(run.activeLayer, 'cyber');
+  assert.equal(run.meatActor, body);
+  assert.equal(body.frozen, true);
+  assert.ok(run.activeActor instanceof CyberAvatar);
+  assert.equal(run.deckerBody, body);
+});
+
+// ---------------------------------------------------------------------------
+// Jack-out releases the body
+// ---------------------------------------------------------------------------
+
+test('P3.M4.2: jack-out unfreezes the body and returns meat control to the Decker', () => {
+  const run = dualRun();
+  const body = run.player!;
+  jackIn(run);
+  assert.equal(body.frozen, true);
+
+  // No onJackOutRequested hook → an incomplete jack-out resolves immediately.
+  run.jackOut();
+  assert.equal(run.cyberspace?.phase, 'resolved');
+  assert.equal(body.frozen, false);
+  assert.equal(run.meatActor, body);
+  assert.equal(run.activeLayer, 'meat');
+});
+
+// ---------------------------------------------------------------------------
+// Persistence round-trips
+// ---------------------------------------------------------------------------
+
+test('P3.M4.2: a jacked dual run round-trips body + partner + flip state', () => {
+  const run = dualRun();
+  jackIn(run);
+  const restored = restore(snapshot(run)).run;
+
+  const body = restored.deckerBody!;
+  assert.ok(body instanceof Decker);
+  assert.equal(body.frozen, true);
+  assert.equal(restored.activeLayer, 'meat');
+
+  const partner = restored.partnerMember!;
+  assert.ok(!(partner instanceof Decker));
+  assert.equal(restored.meatActor, partner);
+  assert.equal(restored.world!.entities.get(partner.id), partner);
+  assert.equal(restored.activeActor, partner);
+});
+
+test('P3.M4.2: a run flipped into Cyberspace restores on the cyber side', () => {
+  const run = dualRun();
+  jackIn(run);
+  // Simulate the M4.3 flip at the model level.
+  run.activeLayer = 'cyber';
+  const restored = restore(snapshot(run)).run;
+
+  assert.equal(restored.activeLayer, 'cyber');
+  assert.ok(restored.activeActor instanceof CyberAvatar);
+  assert.equal(restored.deckerBody!.frozen, true);
+});

From 07139f3e5c1fca8c979ad25ddc1cb193f328799d Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Mon, 15 Jun 2026 12:11:05 -0700
Subject: [PATCH 40/55] The Flip!

---
 docs/phase-3-plan.md                      |   4 +-
 src/game/Run.ts                           |  49 ++++++
 src/input/keyHelp.ts                      |   8 +
 src/input/keymap.ts                       |   6 +
 src/shell/activeView.ts                   |  33 +++-
 src/shell/combatHudSnapshot.ts            |  35 +++--
 src/shell/locationHud.ts                  |   4 +-
 src/shell/shellRuntime.ts                 |  51 ++++--
 src/shell/visionSync.ts                   |  10 +-
 tests/unit/game/cyber/simstimFlip.test.ts | 180 ++++++++++++++++++++++
 tests/unit/input/keyHelp.test.ts          |   1 +
 11 files changed, 344 insertions(+), 37 deletions(-)
 create mode 100644 tests/unit/game/cyber/simstimFlip.test.ts

diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 302c95e..4ea42dd 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -344,11 +344,13 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 |---|---|---|---|
 | **P3.M4.1 Dual deploy** | ✅ Done | Reserve the meat partner alongside the Decker on a Cyberspace deploy; `Run.partnerMember`, deploy gates, persistence | deploy gates, partner shape, campaign + standalone round-trip |
 | **P3.M4.2 Jacked body anchor + partner spawn** | ✅ Done (model) | Decker body freezes at port; partner spawns at a safe meat cell; `activeLayer`/`meatActor`/`deckerBody` on `Run` | body frozen+targetable, movement rejected, partner placement, determinism, round-trip |
-| **P3.M4.3 Flip command** | 🔲 | Free action swaps active input layer | input routed to active layer only, inactive holds position |
+| **P3.M4.3 Flip command** | ✅ Done | Tab → free-action flip; `activeView` keys on `activeLayer`; `Run.flip()`/`canFlip()` | flip toggles layer/actor, solo+pre-jack can't flip, meat↔meat post-jack-out, keymap intent |
 | **P3.M4.4 Dual hostile phase** | 🔲 | End turn advances corp and ICE phases once each | deterministic order, both layers tick, no double AP refresh |
 | **P3.M4.5 PIP** | 🔲 | Inactive layer mini-render + status summary | desktop/mobile layout, no input capture |
 | **P3.M4.6 Jack-out** | 🔲 | Voluntary + forced (1-HP) jack-out transitions back to Meatspace | cleanup, objective failure rules, snapshot round-trip |
 
+**P3.M4.3 implementation note (2026-06-15):** The flip is a free action bound to **Tab** (`keymap` → `{type:'flip'}`; the shell's `handleFlip` validates and flashes a deny when there's nothing to flip to, so the keymap stays dumb). `Run.flip()`/`canFlip()` swap active control: while jacked in, between the controllable meat operator and the cyber avatar (only when the meat side is a real partner, not the frozen solo body); post-jack-out, between the two live meat operators (`#aliveMeatAlternate`). The big seam change is in **`activeView`**: `isJackedIn` ("a cyber layer exists" — body vulnerability, dual-layer turn plumbing) now splits from new **`isCyberView`** ("the player is viewing/controlling the grid" = jacked **and** `activeLayer==='cyber'`). Render, tileset, vision, HUD, gear gates, corp-step render target, breach overlay, and mood/hint all switched to `isCyberView`; `meatActorOf` centers meat fog + the meat HUD pane on the controllable operator (partner after a dual jack-in). Solo cyber runs are unchanged (jack-in sets `activeLayer='cyber'` ⇒ `isCyberView` true everywhere it was `isJackedIn`). **Verification gap:** the shell `handleFlip`/render path has no DOM test harness and the debug harness lacks Cyber/PIP support, so the end-to-end flip needs an in-campaign playtest once a dual-deploy cyber contract is reachable through the live loop. **Follow-up:** no touch-pad flip button yet (keyboard-only); M4.5 still owes the PIP showing the *inactive* layer (today it always shows meat per M3.7, so it's redundant while viewing meat).
+
 **P3.M4.2 implementation note (2026-06-15):** Run-model layer only — the shell/`activeView` wiring and the flip *command* land with P3.M4.3. `jackIn` now captures the Decker as the **body**, freezes it (`Entity.frozen`, enforced in `World.canMoveEntity` → `'jacked-in'`; still a live, targetable grid entity), and — when a partner was reserved — spawns the partner via `#partnerSpawnTile` (deterministic, prefers cells no live hostile can see and that sit against cover; falls back safe → any-free; throws on a full grid), hands it control (`meatActor`), and keeps `activeLayer = 'meat'`. A solo jack-in has no partner, so `meatActor` stays the Decker and `activeLayer = 'cyber'` (M3 behaviour preserved). New `Run` surface: `meatActor` (controllable meat crew), `activeLayer` (`'meat'`|`'cyber'`), `deckerBody` getter, and `activeWorld`/`activeActor` now honor `activeLayer` (via `cyberInputActive`). `player` deliberately stays the Decker/body so body-targeting feedback and the PIP keep reading it. `#finalizeJackOut` unfreezes the body, returns meat control to the Decker, and resets `activeLayer`. Persistence: the off-grid `partner` record is written only while the cyber layer is `dormant` (post-jack the partner is a live grid entity); `activeLayer` is captured while `active`; restore disambiguates the two meat PLAYER crew (Decker = body, non-Decker = partner), re-freezes the body when `active`, and re-establishes `meatActor`/`activeLayer`. **Follow-up:** partner-death flatline accounting (the partner can now die on the field but the campaign doesn't yet flatline it) — must land before M4 closes.
 
 **P3.M4.1 implementation note (2026-06-15):** A Cyberspace dual-deploy reserves a meat partner without spawning it. `Run.partnerMember: Crew | null` (validated non-Decker, living, distinct from the deployed operator) is set at construction; `Run.enterBriefing` forbids a partner on a non-cyber contract but does **not** require one (a solo Decker cyber run stays legal — the dual-deploy product rule is enforced by the briefing UI, not the model). `Campaign.deployCrewMember(memberId, contract, partnerId?)` gains the optional partner, records `Campaign.deployedPartnerId`, commits both operators (both clear job-scoped salvage at `onJobEnd`), and gates the partner (cyber-only, living, non-Decker, distinct, known id). `<run-briefing>` inverts its P3.M3.1 gate: on a cyber contract the Decker row is locked as `CYBER OP` and the player selects the living meat partner (Decker auto-attaches via the emitted `partnerId`); with no eligible partner it falls back to the solo `NEEDS DECKER` gate. Persistence: the reserved partner round-trips as an off-grid entity record (`RunSnapshot.partner`, throwaway `(0,0)` cell) for standalone restore, and re-binds to the canonical crew object via `partnerMemberId` on the campaign path (BRIEFING and COMBAT/RESULT). A partner record without a Cyberspace contract throws on restore. **Follow-up:** partner-death flatline accounting lands with M4.2 (the partner isn't on the field until jack-in); a fully crew-depleted player still cannot field a partner for THE SCORE — revisit if that edge proves too punishing.
diff --git a/src/game/Run.ts b/src/game/Run.ts
index 7c1f337..4eb98f5 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -969,6 +969,55 @@ export class Run {
     return this.cyberspace?.phase === 'active' && this.player instanceof Decker ? this.player : null;
   }
 
+  /**
+   * P3.M4.3: is there a second operator to flip control to right now?
+   *   - Jacked in: flip between the controllable meat operator and the cyber
+   *     avatar — but only when the meat side is actually controllable (a
+   *     dual-deploy partner, not just the frozen solo body).
+   *   - Post jack-out: flip between the two live meat operators (Decker ↔
+   *     partner) sharing the meat grid.
+   */
+  canFlip(): boolean {
+    if (this.state !== RUN_STATE.COMBAT) return false;
+    if (this.cyberspace?.phase === 'active') {
+      return !!this.meatActor && this.meatActor.alive && !this.meatActor.frozen;
+    }
+    return this.#aliveMeatAlternate() !== null;
+  }
+
+  /**
+   * P3.M4.3: the simstim flip — swap which operator receives player input.
+   * Free action. Throws if there is nothing to flip to (the shell gates on
+   * {@link canFlip} first, so reaching here illegally is a wiring bug).
+   */
+  flip(): void {
+    if (!this.canFlip()) {
+      throw new Error('Run.flip: no second operator to flip to');
+    }
+    if (this.cyberspace?.phase === 'active') {
+      this.activeLayer = this.activeLayer === 'cyber' ? 'meat' : 'cyber';
+      return;
+    }
+    const alternate = this.#aliveMeatAlternate();
+    if (alternate) this.meatActor = alternate;
+  }
+
+  /**
+   * The *other* live meat operator on the grid (Decker ↔ partner), distinct
+   * from the current `meatActor`. `null` when there is no second one — pre-jack
+   * solo runs, or after a partner flatline. Used only outside an active
+   * jack-in (where the flip is meat↔cyber instead).
+   */
+  #aliveMeatAlternate(): Crew | null {
+    const current = this.meatActor;
+    for (const crew of [this.player, this.partnerMember]) {
+      if (crew && crew !== current && crew.alive && this.world?.entities.has(crew.id)) {
+        return crew;
+      }
+    }
+    return null;
+  }
+
   /**
    * Dormant → active: spawn the Cyberspace layer. Driven by the meat-bus
    * `EVENT.JACK_IN` emission from a `JackInPoint` link. The layer derives
diff --git a/src/input/keyHelp.ts b/src/input/keyHelp.ts
index 11c92c9..15c579c 100644
--- a/src/input/keyHelp.ts
+++ b/src/input/keyHelp.ts
@@ -75,6 +75,14 @@ export const HELP_ROWS = Object.freeze([
     scope: 'both',
     group: 'action',
   },
+  {
+    // P3.M4.3 simstim flip — swap control between the Meatspace operator and
+    // the Decker's Cyberspace avatar (only on a dual-deploy jack-in).
+    keys: Object.freeze(['Tab']),
+    label: 'Flip — switch Meatspace / Cyberspace control',
+    scope: 'combat',
+    group: 'action',
+  },
   // --- system -----------------------------------------------------------
   {
     keys: Object.freeze(['.']),
diff --git a/src/input/keymap.ts b/src/input/keymap.ts
index bd036ea..d24d07e 100644
--- a/src/input/keymap.ts
+++ b/src/input/keymap.ts
@@ -116,6 +116,12 @@ function dispatchIdle(key: string): DispatchResult {
       return { intent: { type: 'inventory' }, nextMode: MODE.IDLE, aimKind: null };
     case 'l':
       return stayLook();
+    case 'Tab':
+      // P3.M4.3: simstim flip — swap active control between the Meatspace
+      // operator and the Decker's Cyberspace avatar (or, post-jack-out, the
+      // two meat operators). The keymap stays dumb; the shell decides whether
+      // a flip is currently possible and flashes a deny otherwise.
+      return { intent: { type: 'flip' }, nextMode: MODE.IDLE, aimKind: null };
     case 'Escape':
       return { intent: { type: 'cancel' }, nextMode: MODE.IDLE, aimKind: null };
     case 'f':
diff --git a/src/shell/activeView.ts b/src/shell/activeView.ts
index 13c8db6..fb02470 100644
--- a/src/shell/activeView.ts
+++ b/src/shell/activeView.ts
@@ -2,6 +2,12 @@
  * P3.M3.6 active-view seam. While the Decker is jacked in, presentation and
  * input look through these helpers at the cyber layer; in Meatspace (and the
  * Hub) they are identity functions.
+ *
+ * P3.M4.3: the simstim flip splits "the cyber layer exists" (`isJackedIn`)
+ * from "the player is currently *viewing/controlling* the cyber layer"
+ * (`isCyberView`). Render, input, vision, and HUD follow the active view;
+ * body vulnerability and the dual-layer turn orchestration follow layer
+ * existence.
  */
 import type { CyberspaceLayer } from '../game/cyber/CyberspaceLayer.js';
 import type { Run } from '../game/Run.js';
@@ -15,6 +21,10 @@ export type ActiveViewScene = {
   world: World | null;
   player: Entity | null;
   cyberspace?: Run['cyberspace'];
+  /** P3.M4.2/M4.3: the controllable Meatspace crew (partner after a dual jack-in). */
+  meatActor?: Entity | null;
+  /** P3.M4.3: which layer holds input — `'cyber'` only while flipped to the grid. */
+  activeLayer?: 'meat' | 'cyber';
   state?: Run['state'] | string | null;
 } & Partial<Pick<Run, 'archetype'>>;
 
@@ -29,16 +39,31 @@ export function cyberLayerOf(scene: ActiveViewScene | null): CyberspaceLayer | n
   return scene.cyberspace?.phase === 'active' ? scene.cyberspace.layer : null;
 }
 
+/** True while a cyber layer exists (jacked in) — regardless of which side is on screen. */
 export function isJackedIn(scene: ActiveViewScene | null): boolean {
   return cyberLayerOf(scene) !== null;
 }
 
+/**
+ * P3.M4.3: True when the player is currently viewing/controlling Cyberspace —
+ * jacked in *and* flipped to the grid. Render/input/vision/HUD key off this;
+ * `isJackedIn` (layer existence) drives body vulnerability + turn plumbing.
+ */
+export function isCyberView(scene: ActiveViewScene | null): boolean {
+  return cyberLayerOf(scene) !== null && scene?.activeLayer === 'cyber';
+}
+
+/** The controllable Meatspace crew — the partner after a dual jack-in, else the body/operator. */
+export function meatActorOf(scene: ActiveViewScene): Entity | null {
+  return scene.meatActor ?? scene.player;
+}
+
 export function activeWorldOf(scene: ActiveViewScene): World | null {
-  return cyberLayerOf(scene)?.world ?? scene.world;
+  return isCyberView(scene) ? cyberLayerOf(scene)!.world : scene.world;
 }
 
 export function activeActorOf(scene: ActiveViewScene): Entity | null {
-  return cyberLayerOf(scene)?.avatar ?? scene.player;
+  return isCyberView(scene) ? cyberLayerOf(scene)!.avatar : meatActorOf(scene);
 }
 
 export function pickActiveVisionField(
@@ -46,9 +71,9 @@ export function pickActiveVisionField(
   meatVision: VisionField,
   cyberVisionField: VisionField
 ): VisionField {
-  return isJackedIn(scene) ? cyberVisionField : meatVision;
+  return isCyberView(scene) ? cyberVisionField : meatVision;
 }
 
 export function activeTileset(scene: ActiveViewScene | null): TilesetId {
-  return isJackedIn(scene) ? 'cyber' : 'meat';
+  return isCyberView(scene) ? 'cyber' : 'meat';
 }
diff --git a/src/shell/combatHudSnapshot.ts b/src/shell/combatHudSnapshot.ts
index 836a4d2..50e14b6 100644
--- a/src/shell/combatHudSnapshot.ts
+++ b/src/shell/combatHudSnapshot.ts
@@ -1,7 +1,9 @@
 import { RUN_STATE } from '../game/Run.js';
 import type { Run } from '../game/Run.js';
 import type { CombatHudSummaryInput } from '../render/combatHud.js';
-import { cyberLayerOf } from './activeView.js';
+import { CyberAvatar } from '../game/cyber/CyberAvatar.js';
+import { Crew } from '../game/Crew.js';
+import { activeActorOf, isCyberView } from './activeView.js';
 import { isRun } from './sceneView.js';
 import type { ShellScene } from './sceneView.js';
 
@@ -32,33 +34,34 @@ export function buildCombatHudSnapshot(scene: ShellScene | null): CombatHudSumma
 }
 
 /**
- * P3.M3.6: identity/HP/AP panes track whoever the player is being right now —
- * the crew body in Meatspace, the avatar (RAM pool) on the grid.
+ * P3.M3.6/M4.3: identity/HP/AP panes track whoever the player is controlling
+ * right now — the avatar (RAM pool) while flipped to the grid, otherwise the
+ * active Meatspace crew (the partner after a dual jack-in, else the operator).
  */
 export function combatHudBodyPanes(
   scene: Run
 ): Pick<CombatHudSummaryInput, 'identity' | 'hp' | 'ap'> {
-  const layer = cyberLayerOf(scene);
-  if (layer) {
-    const avatar = layer.avatar;
+  const actor = activeActorOf(scene);
+  if (isCyberView(scene) && actor instanceof CyberAvatar) {
     return {
       identity: {
-        callsign: avatar.callsign,
+        callsign: actor.callsign,
         archetype: 'Avatar',
-        stealthed: avatar.stealthed,
+        stealthed: actor.stealthed,
       },
-      hp: { hp: avatar.hp, maxHp: avatar.maxHp, label: 'RAM' },
-      ap: { ap: avatar.ap, maxAp: avatar.maxAp },
+      hp: { hp: actor.hp, maxHp: actor.maxHp, label: 'RAM' },
+      ap: { ap: actor.ap, maxAp: actor.maxAp },
     };
   }
-  const player = scene.player!;
+  const crew = actor instanceof Crew ? actor : scene.player!;
   return {
     identity: {
-      callsign: player.callsign,
-      archetype: scene.archetype,
-      stealthed: player.stealthed,
+      callsign: crew.callsign,
+      // The active meat crew may be the partner — show its own archetype.
+      archetype: crew === scene.player ? scene.archetype : crew.archetype,
+      stealthed: crew.stealthed,
     },
-    hp: { hp: player.hp, maxHp: player.maxHp },
-    ap: { ap: player.ap, maxAp: player.maxAp },
+    hp: { hp: crew.hp, maxHp: crew.maxHp },
+    ap: { ap: crew.ap, maxAp: crew.maxAp },
   };
 }
diff --git a/src/shell/locationHud.ts b/src/shell/locationHud.ts
index 2f96329..489d620 100644
--- a/src/shell/locationHud.ts
+++ b/src/shell/locationHud.ts
@@ -1,7 +1,7 @@
 import { CAMPAIGN_STATE } from '../game/Campaign.js';
 import type { Campaign } from '../game/Campaign.js';
 import { formatHubArcStatusLines } from '../game/hub/arcSurface.js';
-import { isJackedIn } from './activeView.js';
+import { isCyberView } from './activeView.js';
 import type { ShellScene } from './sceneView.js';
 
 /**
@@ -14,7 +14,7 @@ export function currentLocationLabel(
   scene: ShellScene | null
 ): string | undefined {
   if (!campaign) return undefined;
-  if (isJackedIn(scene)) {
+  if (isCyberView(scene)) {
     return '// THE GRID //';
   }
   if (campaign.state === CAMPAIGN_STATE.COMBAT && campaign.activeRun?.contract) {
diff --git a/src/shell/shellRuntime.ts b/src/shell/shellRuntime.ts
index ee1b621..3e061a4 100644
--- a/src/shell/shellRuntime.ts
+++ b/src/shell/shellRuntime.ts
@@ -81,7 +81,7 @@ import {
   activeTileset,
   activeWorldOf,
   cyberLayerOf,
-  isJackedIn,
+  isCyberView,
   pickActiveVisionField,
 } from '/src/shell/activeView.js';
 import { buildCombatHudSnapshot } from '/src/shell/combatHudSnapshot.js';
@@ -1054,7 +1054,7 @@ function resolveAimedUseItem(aim: { dx: number; dy: number }, run: Run): void {
   if (!run.world || !run.player) throw new Error('[shell] resolveAimedUseItem: no scene');
   // P3.M3.6: items are meat gear; the inventory gate blocks new aims while
   // jacked in, but an aim pending across the jack-in interact must also die.
-  if (isJackedIn(run)) {
+  if (isCyberView(run)) {
     pendingAimItemId = null;
     flash('USE FAILED: jacked in — your gear is back in Meatspace.');
     resetInputModes();
@@ -1370,6 +1370,30 @@ function handleLookMove(dx = 0, dy = 0): void {
   if (line) flash(line);
 }
 
+function handleFlip(): void {
+  const run = currentScene();
+  if (!run || !isRun(run) || run.state !== RUN_STATE.COMBAT) return;
+  if (isCorpControlsLocked()) {
+    flash('HOSTILES ACTIVE — controls locked until security finishes.');
+    return;
+  }
+  if (!run.canFlip()) {
+    flash('SIMSTIM: no second operator to flip to.');
+    return;
+  }
+  // The look cursor + any aim mode are layer-specific — clear them before the
+  // view swaps out from under them.
+  lookCursor = null;
+  resetInputModes();
+  run.flip();
+  recomputeVision();
+  paint();
+  const actor = activeActorOf(run);
+  const where = isCyberView(run) ? 'CYBERSPACE' : 'MEATSPACE';
+  const who = actor && 'callsign' in actor && actor.callsign ? ` · ${actor.callsign}` : '';
+  flash(`SIMSTIM → ${where}${who}`);
+}
+
 export function handleIntent(intent: Intent): void {
   if (intent?.type === 'quit-campaign') {
     resetInputModes();
@@ -1383,6 +1407,11 @@ export function handleIntent(intent: Intent): void {
     return;
   }
 
+  if (intent?.type === 'flip') {
+    handleFlip();
+    return;
+  }
+
   if (intent?.type === 'cancel' && lookCursor) {
     exitLookMode();
     return;
@@ -1458,7 +1487,7 @@ export function handleIntent(intent: Intent): void {
             }
             // P3.M3.6: the avatar has no pockets — gear stays with the body
             // until the P3.M4 simstim flip makes split control real.
-            if (isJackedIn(run)) {
+            if (isCyberView(run)) {
               flash('Jacked in — your meatspace gear is out of reach.');
               return;
             }
@@ -1555,7 +1584,7 @@ function driveCombatTurnPipeline(run: Run, options: { resumeFromCorpSlice?: bool
       // P3.M3.6: aftermath is a Meatspace phase — while jacked in it still
       // *applies*, but the canvas is showing the grid, so skip its
       // presentation (overlays/shake/log lines).
-      const jacked = isJackedIn(scene);
+      const jacked = isCyberView(scene);
       const cyberLayer = cyberLayerOf(scene);
       const isCyberStep =
         cyberLayer !== null &&
@@ -1730,7 +1759,7 @@ function runCorpTurn(onFinish: () => void): void {
       if (!scene?.world || !scene.player) return true;
       // Jacked in: meat steps still *apply*, but the canvas is showing the
       // grid — drain them silently rather than pacing invisible frames.
-      if (isJackedIn(scene)) return false;
+      if (isCyberView(scene)) return false;
       return isCorpTurnStepVisibleToPlayer(scene.world, scene.player.id, entityId, step, (x, y) =>
         vision.isVisible(x, y)
       );
@@ -1739,7 +1768,7 @@ function runCorpTurn(onFinish: () => void): void {
       if (degrading) return;
       const scene = currentScene();
       if (!scene?.world || !scene.player) return;
-      if (isJackedIn(scene)) {
+      if (isCyberView(scene)) {
         paintPip();
         const resolve = (id: string) => resolveEntityLabel(id, scene.world!.entities);
         const line = formatCorpTurnStep(resolve(entityId), step, resolve);
@@ -1873,7 +1902,7 @@ function handleCombatInteract(): void {
   // Corpse looting needs pockets — the avatar (no inventory) skips straight
   // to interactables. ICE leaves no salvage in this slice.
   const inventory = 'inventory' in player ? (player as Crew).inventory : null;
-  if (!isJackedIn(run) && !inventory) {
+  if (!isCyberView(run) && !inventory) {
     throw new Error('[shell] combat player inventory is not initialised');
   }
   if (inventory) {
@@ -2093,7 +2122,7 @@ export function paint(stateHint: InputState = activeInputState()): void {
   const world = activeWorldOf(run);
   const actor = activeActorOf(run);
   if (!world || !actor) return;
-  const jacked = isJackedIn(run);
+  const jacked = isCyberView(run);
   // Hub is a safe space — no fog of war. Vision is only meaningful during
   // combat where LOS and drone stealth detection matter.
   const activeVision = run.state === RUN_STATE.COMBAT ? activeVisionField(run) : undefined;
@@ -2157,7 +2186,7 @@ function statusLine(state: InputState): string {
       statusWorld.grid.tileAt(statusActor.x, statusActor.y) === TILE.HAZARD;
     contextHtml = joinStatusParts([formatHazardTag(!!onHazard), alertTag]);
 
-    const jacked = isJackedIn(run);
+    const jacked = isCyberView(run);
     const hintText = proximityHint();
     if (
       !hintText &&
@@ -2178,7 +2207,7 @@ function statusLine(state: InputState): string {
       corpToneActivityBody !== null
     ) {
       latchedCorpMood = {
-        hostileTag: hostileMoodTag(isJackedIn(run), run.hostileFaction),
+        hostileTag: hostileMoodTag(isCyberView(run), run.hostileFaction),
         body: corpToneActivityBody,
       };
       corpToneActivityBody = null;
@@ -2255,7 +2284,7 @@ function proximityHint(): string {
     // nodes/exit port for the avatar.
     const world = activeWorldOf(run);
     const p = activeActorOf(run);
-    const jacked = isJackedIn(run);
+    const jacked = isCyberView(run);
     if (world && p) {
       // Loot hint: adjacent lootable corpses (needs pockets — avatar skips).
       if (!jacked) {
diff --git a/src/shell/visionSync.ts b/src/shell/visionSync.ts
index 204f729..5d548ff 100644
--- a/src/shell/visionSync.ts
+++ b/src/shell/visionSync.ts
@@ -4,7 +4,7 @@ import type { CyberspaceLayer } from '../game/cyber/CyberspaceLayer.js';
 import type { Entity } from '../game/Entity.js';
 import type { World } from '../game/World.js';
 import type { VisionField } from '../game/Vision.js';
-import { cyberLayerOf, isRunScene } from './activeView.js';
+import { cyberLayerOf, isRunScene, meatActorOf } from './activeView.js';
 import type { ActiveViewScene } from './activeView.js';
 
 export type VisionSyncInput = {
@@ -31,8 +31,12 @@ export function syncVisionFields(input: VisionSyncInput): VisionSyncResult {
   let recordMeatSeen = false;
   let meatVisible: ReadonlySet<string> | undefined;
 
-  if (scene.world && scene.player) {
-    meatVision.recompute(scene.world.grid, scene.player, undefined, {
+  // P3.M4.3: meat fog follows the *controllable* meat operator — the partner
+  // after a dual jack-in, the body/operator otherwise. (The frozen Decker body
+  // still reveals nothing extra; vision is single-viewer.)
+  const meatViewer = meatActorOf(scene);
+  if (scene.world && meatViewer) {
+    meatVision.recompute(scene.world.grid, meatViewer, undefined, {
       blockers: scene.world.blockerKeys(),
     });
     meatVisible = meatVision.visible;
diff --git a/tests/unit/game/cyber/simstimFlip.test.ts b/tests/unit/game/cyber/simstimFlip.test.ts
new file mode 100644
index 0000000..37937cf
--- /dev/null
+++ b/tests/unit/game/cyber/simstimFlip.test.ts
@@ -0,0 +1,180 @@
+/**
+ * P3.M4.3 — the simstim flip. Tab swaps active control between the Meatspace
+ * operator and the Decker's Cyberspace avatar (and, post-jack-out, between the
+ * two meat operators). The flip is a free action; the active view/actor follow
+ * `activeLayer`, which the flip toggles.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { Run } from '../../../../src/game/Run.js';
+import { JackInPoint } from '../../../../src/game/entities/JackInPoint.js';
+import { CyberAvatar } from '../../../../src/game/cyber/CyberAvatar.js';
+import { buildCrewMember } from '../../../../src/game/archetypes/index.js';
+import { OBJECTIVES } from '../../../../src/game/hub/Curator.js';
+import { Rng } from '../../../../src/rng.js';
+import { dispatch, MODE } from '../../../../src/input/keymap.js';
+import {
+  activeActorOf,
+  activeTileset,
+  activeWorldOf,
+  isCyberView,
+  isJackedIn,
+} from '../../../../src/shell/activeView.js';
+import { testContractContext } from '../contractTestUtils.js';
+import type { World } from '../../../../src/game/World.js';
+import type { Entity } from '../../../../src/game/Entity.js';
+
+const cyberContract = (overrides = {}) => ({
+  seed: 12345,
+  objective: {
+    kind: OBJECTIVES.DATA_NODE_SLICE,
+    title: 'Spike the server farm',
+    briefing: 'Jack in, slice the data node, then extract.',
+    params: { requiresCyberspace: true, count: 1 },
+  },
+  difficulty: 'standard',
+  threatCount: 1,
+  label: 'cyber casing job',
+  context: testContractContext(OBJECTIVES.DATA_NODE_SLICE),
+  reward: { credits: 0, repDelta: 0 },
+  ...overrides,
+});
+
+const makeDecker = () => buildCrewMember('decker', { x: 0, y: 0 }, new Rng(100), { id: 'crew-decker' });
+const makeMerc = () => buildCrewMember('merc', { x: 0, y: 0 }, new Rng(101), { id: 'crew-merc' });
+
+function dualRun(seed = 12345) {
+  const run = new Run({ crewMember: makeDecker(), partnerMember: makeMerc(), seed });
+  run.enterBriefing(cyberContract({ seed }));
+  run.enterCombat();
+  return run;
+}
+function soloRun(seed = 12345) {
+  const run = new Run({ crewMember: makeDecker(), seed });
+  run.enterBriefing(cyberContract({ seed }));
+  run.enterCombat();
+  return run;
+}
+
+function adjacentFreeTile(world: World, target: Entity) {
+  for (let dy = -1; dy <= 1; dy++) {
+    for (let dx = -1; dx <= 1; dx++) {
+      if (dx === 0 && dy === 0) continue;
+      const x = target.x + dx;
+      const y = target.y + dy;
+      if (world.grid.inBounds(x, y) && world.grid.isPassable(x, y) && !world.entityAt(x, y)) {
+        return { x, y };
+      }
+    }
+  }
+  throw new Error(`no free tile adjacent to ${target.id}`);
+}
+
+function jackIn(run: Run) {
+  const point = [...run.world!.entities.values()].find(e => e instanceof JackInPoint) as JackInPoint;
+  const spot = adjacentFreeTile(run.world!, point);
+  run.world!.relocateEntity(run.player!, spot.x, spot.y);
+  run.player!.refreshAp();
+  assert.equal(point.interact(run.world!, run.player!).ok, true);
+}
+
+// ---------------------------------------------------------------------------
+// Keymap binding
+// ---------------------------------------------------------------------------
+
+test('P3.M4.3: Tab dispatches a flip intent in IDLE', () => {
+  const r = dispatch('Tab', MODE.IDLE);
+  assert.deepEqual(r.intent, { type: 'flip' });
+  assert.equal(r.nextMode, MODE.IDLE);
+});
+
+// ---------------------------------------------------------------------------
+// Flip while jacked in (dual deploy)
+// ---------------------------------------------------------------------------
+
+test('P3.M4.3: flip swaps meat partner ↔ cyber avatar while jacked in', () => {
+  const run = dualRun();
+  jackIn(run);
+  const partner = run.partnerMember!;
+
+  // Control starts in Meatspace on the partner.
+  assert.equal(run.canFlip(), true);
+  assert.equal(run.activeLayer, 'meat');
+  assert.equal(run.activeActor, partner);
+  assert.equal(activeActorOf(run), partner);
+  assert.equal(isCyberView(run), false);
+  assert.equal(activeTileset(run), 'meat');
+
+  // Flip into Cyberspace.
+  run.flip();
+  assert.equal(run.activeLayer, 'cyber');
+  assert.ok(run.activeActor instanceof CyberAvatar);
+  assert.ok(activeActorOf(run) instanceof CyberAvatar);
+  assert.equal(isCyberView(run), true);
+  assert.equal(isJackedIn(run), true);
+  assert.equal(activeTileset(run), 'cyber');
+  assert.equal(activeWorldOf(run), run.cyberspace!.phase === 'active' && run.cyberspace.layer.world);
+
+  // Flip back to Meatspace.
+  run.flip();
+  assert.equal(run.activeLayer, 'meat');
+  assert.equal(run.activeActor, partner);
+  assert.equal(isCyberView(run), false);
+});
+
+test('P3.M4.3: the frozen body is never the flip target while jacked', () => {
+  const run = dualRun();
+  jackIn(run);
+  // Flip to cyber and back; the meat side is always the partner, never the body.
+  run.flip();
+  run.flip();
+  assert.equal(run.activeActor, run.partnerMember);
+  assert.notEqual(run.activeActor, run.deckerBody);
+});
+
+// ---------------------------------------------------------------------------
+// Solo jack-in cannot flip (no controllable meat operator)
+// ---------------------------------------------------------------------------
+
+test('P3.M4.3: a solo jack-in cannot flip — only the frozen body is in Meatspace', () => {
+  const run = soloRun();
+  jackIn(run);
+  assert.equal(run.activeLayer, 'cyber');
+  assert.equal(run.canFlip(), false);
+  assert.throws(() => run.flip(), /no second operator/);
+});
+
+// ---------------------------------------------------------------------------
+// Pre-jack and non-cyber runs cannot flip
+// ---------------------------------------------------------------------------
+
+test('P3.M4.3: pre-jack-in there is nothing to flip to', () => {
+  const run = dualRun();
+  assert.equal(run.canFlip(), false);
+  assert.throws(() => run.flip(), /no second operator/);
+});
+
+// ---------------------------------------------------------------------------
+// Post-jack-out: meat ↔ meat flip between the two operators
+// ---------------------------------------------------------------------------
+
+test('P3.M4.3: after jack-out the flip cycles the two meat operators', () => {
+  const run = dualRun();
+  const decker = run.player!;
+  const partner = run.partnerMember!;
+  jackIn(run);
+  run.jackOut(); // no hook → resolves immediately even though incomplete
+
+  // Back in Meatspace controlling the Decker; the partner is the alternate.
+  assert.equal(run.activeLayer, 'meat');
+  assert.equal(run.meatActor, decker);
+  assert.equal(run.canFlip(), true);
+
+  run.flip();
+  assert.equal(run.meatActor, partner);
+  assert.equal(run.activeActor, partner);
+
+  run.flip();
+  assert.equal(run.meatActor, decker);
+});
diff --git a/tests/unit/input/keyHelp.test.ts b/tests/unit/input/keyHelp.test.ts
index a9babe2..5552369 100644
--- a/tests/unit/input/keyHelp.test.ts
+++ b/tests/unit/input/keyHelp.test.ts
@@ -96,6 +96,7 @@ test('drift guard: every key handled by keymap.js dispatch appears in HELP_ROWS'
     ' ',
     'i',
     'l',
+    'Tab',
     // system
     '.',
     'Escape',

From 6d71c965c34f8a787a9c55d6c24f2c943821d6bb Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Mon, 15 Jun 2026 16:13:31 -0700
Subject: [PATCH 41/55] tune flip mechanics

---
 docs/phase-3-plan.md                          |   7 +-
 src/game/Run.ts                               |  66 ++++
 src/game/persistence.ts                       |  14 +-
 src/input/applyIntent.ts                      |  33 +-
 src/shell/shellRuntime.ts                     |  91 +++++-
 tests/unit/game/cyber/dualDeploy.test.ts      |  54 ++++
 .../game/cyber/operatorTurnConclude.test.ts   | 284 ++++++++++++++++++
 tests/unit/input/applyIntent.test.ts          |  15 +
 8 files changed, 541 insertions(+), 23 deletions(-)
 create mode 100644 tests/unit/game/cyber/operatorTurnConclude.test.ts

diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 4ea42dd..9b21b3a 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -322,6 +322,7 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 - **Deploy UX:** the Decker is auto-included as the jack-in operator; the player picks the living meat partner. If no living non-Decker is available, the run falls back to a solo Decker deploy (the P3.M3 path).
 - **Flip is a free action** that swaps the active operator among the live operators: pre-jack `{Decker}` (no-op), jacked `{partner(meat), avatar(cyber)}` (layer swap; Decker body frozen), post-jack-out `{Decker(meat), partner(meat)}` (meat↔meat).
 - **Forced jack-out at 1 HP:** the Decker's body cannot die while jacked in — a killing/critical hit clamps the body to 1 HP and ejects the Decker (alive) back to Meatspace. Cyber-side death (ICE depleting RAM) still flatlines. This retires the silent-meat-damage Score death vector from M3.7.
+- **Independent AP pools, decoupled turn-end (2026-06-15, from playtest).** Each dual-deploy operator keeps its own 4-AP pool — moving the avatar spends only avatar AP, the partner only partner AP. The mutual turn (which drives *both* hostile phases) ends only when **every controllable** operator is spent, or on an explicit Wait — **not** when whichever one you're driving hits 0. Exhausting the active operator while the other still has AP **auto-flips** control to it (free, like the manual flip) rather than ending the turn. Rationale: the partner is a separate living crew member, so two operators ⇒ two full turns of action, matched by the two hostile phases already ticking each round (meat drones *and* ICE) — the economy stays symmetric. The earlier behaviour (turn ended on the *active* operator's exhaustion, refreshing both) wasted the other's unspent AP and rewarded tedious flip-drain micro. *Sub-decision:* auto-flip over a passive "operator spent" nudge — keeps the player's hands moving; the view-snap is covered by a loud flash. *Refinement (2026-06-15, playtest):* **Wait (`.`) passes *this* operator and always hands control to the other operator when one exists** — forfeit this operator's remaining AP, then flip to the other *regardless of whether it still has AP*; the mutual turn (and the hostile phases) fires only once both operators are spent/passed (on a flip-and-end, next turn opens on the operator we flipped to). Distinct from AP-exhaustion, which auto-flips only *while* the other can still act and ends *in place* when the last operator runs dry — flipping back to an already-spent operator at exhaustion would be an unwanted view-snap, whereas Wait is an explicit pass/switch gesture so it always switches. (An earlier pass mid-implementation flipped on Wait only when the other had AP and otherwise stayed put — that two-faced Wait read as confusing in playtest.) This gives a clean split — **Tab** switches attention keeping both pools, **`.`** commits one operator to inaction and rotates to the other — matching the reach-for-`.`-when-this-operator-has-nothing-to-do intuition. Trade-off: no single-press "end the whole round"; ending while both hold AP is two passes (`.` then `.`). No dedicated hard-end binding for now; revisit if the two-tap end proves annoying. *Possible follow-up:* exhaustion could be made to round-robin too if the Wait/exhaustion end-position difference reads as inconsistent in play.
 
 **Scope:**
 
@@ -345,10 +346,14 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 | **P3.M4.1 Dual deploy** | ✅ Done | Reserve the meat partner alongside the Decker on a Cyberspace deploy; `Run.partnerMember`, deploy gates, persistence | deploy gates, partner shape, campaign + standalone round-trip |
 | **P3.M4.2 Jacked body anchor + partner spawn** | ✅ Done (model) | Decker body freezes at port; partner spawns at a safe meat cell; `activeLayer`/`meatActor`/`deckerBody` on `Run` | body frozen+targetable, movement rejected, partner placement, determinism, round-trip |
 | **P3.M4.3 Flip command** | ✅ Done | Tab → free-action flip; `activeView` keys on `activeLayer`; `Run.flip()`/`canFlip()` | flip toggles layer/actor, solo+pre-jack can't flip, meat↔meat post-jack-out, keymap intent |
-| **P3.M4.4 Dual hostile phase** | 🔲 | End turn advances corp and ICE phases once each | deterministic order, both layers tick, no double AP refresh |
+| **P3.M4.4 Dual hostile phase** | 🟡 | Independent AP pools + decoupled turn-end (auto-flip on exhaustion); end turn advances corp and ICE phases once each | ✅ AP-pool/turn-end model (`endOfTurnReady`/`concludeActiveOperatorTurn`); ⬜ verify M3.6 dual-phase with partner+body present |
 | **P3.M4.5 PIP** | 🔲 | Inactive layer mini-render + status summary | desktop/mobile layout, no input capture |
 | **P3.M4.6 Jack-out** | 🔲 | Voluntary + forced (1-HP) jack-out transitions back to Meatspace | cleanup, objective failure rules, snapshot round-trip |
 
+**P3.M4.4 bugfix — stranded partner after restore (2026-06-15, playtest):** On a campaign mid-run restore, flipping to the meat partner after the Decker jacked out controlled a phantom: the partner appeared "stuck in a wall off the map" and couldn't move. Contributing factors: (1) restore rebuilds grid entities as *detached copies*, separate from the canonical roster crew objects; the primary tolerates this because `run.player` stays the grid copy (operator) while `crewMember` is re-linked to the roster object (identity) — two fields. (2) The partner has only `partnerMember`, doing double duty as both operator and roster ref. (3) `restoreActiveRun` unconditionally rebound `partnerMember` to the off-grid canonical roster object, so once the partner was a live grid entity (jacked in / jacked out) the flip's `#aliveMeatAlternate` handed control to the off-grid copy (id-match in `world.entities.has` masked it), centering the camera on the roster object's `(0,0)` and denying movement. Fix: `restoreActiveRun` re-binds `partnerMember` to the canonical object **only while it is still off-grid** (a dormant reserve a later jack-in spawns); once it is a live grid entity, keep that entity — mirroring `run.player`. Regression test: `dualDeploy.test.ts` "after jack-out the campaign round-trip keeps the partner on the grid" (identity + flip). **Follow-up (broader, pre-existing):** the detached-grid-copy-vs-canonical-roster split means combat stats applied *after* a mid-run restore land on the grid copy, not the roster object — a latent crew-HP desync across save→restore→play→save for the primary too. Investigate whether job-end reconciliation already covers it; if not, restore should rehydrate the canonical crew objects *as* the grid entities so there is one object, as in live play.
+
+**P3.M4.4 implementation note — AP pools (2026-06-15):** Independent AP pools with a decoupled turn-end, settled from playtest (see the resolved decision above). Two new pure `Run` methods carry the model: **`endOfTurnReady()`** — the active actor is at 0 AP and there is no flip alternate with AP left (`#flipAlternate()` returns the operator `flip()` would hand control to: the other layer's operator while jacked, else the other live meat operator); and **`concludeActiveOperatorTurn(): 'continue' | 'auto-flip' | 'end'`** — `'continue'` while the active actor still has AP, `'end'` once the crew is spent (the shell drives the corp+ICE phases, which refresh every pool once), `'auto-flip'` when the active operator is spent but another still has AP (the method performs the flip; a spent-but-not-end-ready actor guarantees a live alternate with AP, so the flip is always safe). The frozen Decker body is never the active actor nor a flip alternate, so its full pool can't keep the turn alive; solo/single-deploy has no alternate and ends at 0 as before (no M3 regression). Shell: every auto-end-on-exhaustion site (the `applyIntent` `gateOnApExhausted` via new optional `ctx.concludeTurn`, plus consumable / loot / secured-interact) routes through one `concludeOperatorTurn()` helper that switches on the discriminant — `'end'` → `advanceTurn()`, `'auto-flip'` → shared `repaintAfterFlip(run, 'OPERATOR SPENT')` (factored out of `handleFlip`). **Wait** (`end-turn`) zeroes the active operator's AP then routes through a *separate* `passTurn` hook → `Run.passActiveOperatorTurn(): 'flip' | 'flip-and-end' | 'end'` (playtest refinement). Unlike exhaustion, Wait **always** flips to the other operator when one exists (`#flipAlternate` non-null), regardless of that operator's AP — `'flip'` keeps the turn open, `'flip-and-end'` also drives the hostile phases (next turn opens on the flipped-to operator), `'end'` is the solo/single-deploy case; the `?? advanceTurn` fallback keeps a hard end for harness contexts. The shell's `passOperatorTurn` repaints (`repaintAfterFlip(run, 'WAIT')`) on both flip outcomes and additionally `advanceTurn()`s on `'flip-and-end'`. Tests: `operatorTurnConclude.test.ts` (14) and an `applyIntent` `end-turn`-routes-through-`passTurn` case covers the predicate, the three-way conclude, auto-flip-not-end-not-refresh, never flipping to a dead/frozen operator, solo/single-deploy end-at-0, and post-jack-out meat↔meat. **Still open for M4.4:** verify the M3.6 dual-phase corp turn (`dualPhaseTurn.test.ts` was solo-Decker only) holds with the partner+body present — both layers tick once, no double refresh, deterministic with the partner on the field.
+
 **P3.M4.3 implementation note (2026-06-15):** The flip is a free action bound to **Tab** (`keymap` → `{type:'flip'}`; the shell's `handleFlip` validates and flashes a deny when there's nothing to flip to, so the keymap stays dumb). `Run.flip()`/`canFlip()` swap active control: while jacked in, between the controllable meat operator and the cyber avatar (only when the meat side is a real partner, not the frozen solo body); post-jack-out, between the two live meat operators (`#aliveMeatAlternate`). The big seam change is in **`activeView`**: `isJackedIn` ("a cyber layer exists" — body vulnerability, dual-layer turn plumbing) now splits from new **`isCyberView`** ("the player is viewing/controlling the grid" = jacked **and** `activeLayer==='cyber'`). Render, tileset, vision, HUD, gear gates, corp-step render target, breach overlay, and mood/hint all switched to `isCyberView`; `meatActorOf` centers meat fog + the meat HUD pane on the controllable operator (partner after a dual jack-in). Solo cyber runs are unchanged (jack-in sets `activeLayer='cyber'` ⇒ `isCyberView` true everywhere it was `isJackedIn`). **Verification gap:** the shell `handleFlip`/render path has no DOM test harness and the debug harness lacks Cyber/PIP support, so the end-to-end flip needs an in-campaign playtest once a dual-deploy cyber contract is reachable through the live loop. **Follow-up:** no touch-pad flip button yet (keyboard-only); M4.5 still owes the PIP showing the *inactive* layer (today it always shows meat per M3.7, so it's redundant while viewing meat).
 
 **P3.M4.2 implementation note (2026-06-15):** Run-model layer only — the shell/`activeView` wiring and the flip *command* land with P3.M4.3. `jackIn` now captures the Decker as the **body**, freezes it (`Entity.frozen`, enforced in `World.canMoveEntity` → `'jacked-in'`; still a live, targetable grid entity), and — when a partner was reserved — spawns the partner via `#partnerSpawnTile` (deterministic, prefers cells no live hostile can see and that sit against cover; falls back safe → any-free; throws on a full grid), hands it control (`meatActor`), and keeps `activeLayer = 'meat'`. A solo jack-in has no partner, so `meatActor` stays the Decker and `activeLayer = 'cyber'` (M3 behaviour preserved). New `Run` surface: `meatActor` (controllable meat crew), `activeLayer` (`'meat'`|`'cyber'`), `deckerBody` getter, and `activeWorld`/`activeActor` now honor `activeLayer` (via `cyberInputActive`). `player` deliberately stays the Decker/body so body-targeting feedback and the PIP keep reading it. `#finalizeJackOut` unfreezes the body, returns meat control to the Decker, and resets `activeLayer`. Persistence: the off-grid `partner` record is written only while the cyber layer is `dormant` (post-jack the partner is a live grid entity); `activeLayer` is captured while `active`; restore disambiguates the two meat PLAYER crew (Decker = body, non-Decker = partner), re-freezes the body when `active`, and re-establishes `meatActor`/`activeLayer`. **Follow-up:** partner-death flatline accounting (the partner can now die on the field but the campaign doesn't yet flatline it) — must land before M4 closes.
diff --git a/src/game/Run.ts b/src/game/Run.ts
index 4eb98f5..4107a18 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -1002,6 +1002,72 @@ export class Run {
     if (alternate) this.meatActor = alternate;
   }
 
+  /**
+   * P3.M4.4: the operator {@link flip} would hand control to right now — the
+   * other layer's operator while jacked (avatar ↔ partner), else the other
+   * live meat operator. `null` when there is nothing to flip to. Used to reason
+   * about the *crew's* remaining AP, not just the active actor's.
+   */
+  #flipAlternate(): Crew | CyberAvatar | null {
+    if (!this.canFlip()) return null;
+    if (this.cyberspace?.phase === 'active') {
+      return this.activeLayer === 'cyber' ? this.meatActor : this.cyberspace.layer.avatar;
+    }
+    return this.#aliveMeatAlternate();
+  }
+
+  /**
+   * P3.M4.4: independent AP pools, decoupled turn-end. The mutual turn is over
+   * only when *every controllable* operator is spent — the active actor at 0 AP
+   * and no flip alternate with AP left. A single-deploy/solo operator (no
+   * alternate) ends at 0 as before; the frozen Decker body is never the active
+   * actor nor a flip alternate, so its full pool can't keep the turn alive.
+   */
+  endOfTurnReady(): boolean {
+    const active = this.activeActor;
+    if (!active || active.ap > 0) return false;
+    const alternate = this.#flipAlternate();
+    return !alternate || alternate.ap === 0;
+  }
+
+  /**
+   * P3.M4.4: resolve the active operator running out of AP. The shell calls
+   * this wherever it used to auto-end on exhaustion:
+   *   - `'continue'` — the active operator still has AP; nothing to do.
+   *   - `'end'`      — the whole crew is spent; the shell drives the corp/ICE
+   *                    hostile phases (which refresh every pool exactly once).
+   *   - `'auto-flip'`— the active operator is spent but another still has AP;
+   *                    control has been handed to it (no turn end, no refresh).
+   * The flip is safe here: a spent active actor that is not {@link endOfTurnReady}
+   * guarantees a live alternate with AP to flip to.
+   */
+  concludeActiveOperatorTurn(): 'continue' | 'auto-flip' | 'end' {
+    const active = this.activeActor;
+    if (!active || active.ap > 0) return 'continue';
+    if (this.endOfTurnReady()) return 'end';
+    this.flip();
+    return 'auto-flip';
+  }
+
+  /**
+   * P3.M4.4: resolve a Wait (`.`). The caller has already forfeited the active
+   * operator's remaining AP; Wait is an explicit "pass *this* operator, switch
+   * to the other," so — unlike running dry through actions — it **always** hands
+   * control to the other operator when one exists, regardless of whether that
+   * operator still has AP. Ending is orthogonal: the mutual turn ends when the
+   * whole crew is spent.
+   *   - `'flip'`         — control handed off; the other operator can still act.
+   *   - `'flip-and-end'` — control handed off *and* the crew is spent, so the
+   *                        shell also drives the hostile phases (next turn opens
+   *                        on the operator we flipped to).
+   *   - `'end'`          — solo / single-deploy (nobody to flip to); just end.
+   */
+  passActiveOperatorTurn(): 'flip' | 'flip-and-end' | 'end' {
+    if (!this.#flipAlternate()) return 'end';
+    this.flip();
+    return this.endOfTurnReady() ? 'flip-and-end' : 'flip';
+  }
+
   /**
    * The *other* live meat operator on the grid (Decker ↔ partner), distinct
    * from the current `meatActor`. `null` when there is no second one — pre-jack
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index 746ac1c..d3a9b65 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -1807,9 +1807,17 @@ function restoreActiveRun(
   if (record.snapshot) {
     const restored = restore(record.snapshot, options).run;
     restored.crewMember = member;
-    // P3.M4.1: re-bind the partner to the canonical crew object (the snapshot
-    // carried a detached copy), matching how `crewMember` is re-linked.
-    restored.partnerMember = partner;
+    // P3.M4.1/M4.4: re-bind the partner to the canonical roster object ONLY
+    // while it is still off-grid — a dormant reserve, the object a later jack-in
+    // spawns onto the meat grid. Once the partner is a *live grid entity*
+    // (jacked in, or jacked out), keep the entity `restore()` already wired:
+    // it's the meat operator the simstim flip controls, exactly as `run.player`
+    // stays the grid body for the primary. Rebinding it to the off-grid roster
+    // copy stranded the partner off the map — the flip drove a phantom while the
+    // on-grid copy sat frozen in place.
+    if (partner && !restored.world?.entities.has(partner.id)) {
+      restored.partnerMember = partner;
+    }
     return restored;
   }
   const run = new Run({
diff --git a/src/input/applyIntent.ts b/src/input/applyIntent.ts
index 0325470..75a5641 100644
--- a/src/input/applyIntent.ts
+++ b/src/input/applyIntent.ts
@@ -89,6 +89,23 @@ export type ApplyIntentContext = {
   rng: Rng;
   log: (line: string) => void;
   advanceTurn: () => void;
+  /**
+   * P3.M4.4: resolve the active operator hitting 0 AP. With independent
+   * dual-deploy AP pools, exhausting one operator must not end the mutual turn
+   * while another still has AP — the shell auto-flips control instead, and only
+   * ends (driving the hostile phases) once the whole crew is spent. Optional:
+   * contexts that don't supply it fall back to the single-operator `advanceTurn`
+   * (correct for solo/single-deploy, where there is nothing to flip to).
+   */
+  concludeTurn?: () => void;
+  /**
+   * P3.M4.4: resolve a Wait (`.`). Distinct from `concludeTurn`: Wait always
+   * hands control to the other operator when one exists (a consistent
+   * pass/switch gesture), ending the mutual turn additionally when the crew is
+   * spent. Optional: without it (solo/single-deploy harness) Wait hard-ends via
+   * `advanceTurn`.
+   */
+  passTurn?: () => void;
   resetInputModes: () => void;
   onPlayerAction: (actionName: string) => void;
   /**
@@ -153,10 +170,11 @@ export const PLAYER_ACTIONS = Object.freeze({
 });
 
 function gateOnApExhausted(ctx: ApplyIntentContext) {
-  const { player, advanceTurn } = ctx;
-  if (player.ap === 0) {
-    advanceTurn();
-  }
+  const { player, advanceTurn, concludeTurn } = ctx;
+  if (player.ap !== 0) return;
+  // P3.M4.4: defer the end-vs-auto-flip decision to the shell when wired;
+  // otherwise fall back to a hard end (single-operator semantics).
+  (concludeTurn ?? advanceTurn)();
 }
 
 function finishBumpInteract(
@@ -203,10 +221,15 @@ export function applyIntent(intent: Intent, ctx: ApplyIntentContext) {
     case 'use-item':
       return doUseItem(intent, ctx);
     case 'end-turn': {
+      // P3.M4.4: Wait passes *this* operator — forfeit its remaining AP, then
+      // hand control to the other operator if it can still act (auto-flip via
+      // `concludeTurn`), ending the mutual turn only once the whole crew is
+      // spent. Without a `concludeTurn` (solo/single-deploy harness) this is a
+      // hard end, same as before.
       const apBefore = player.ap;
       log(`> ${entityLabel(player)} waits (drops ${apBefore} AP).`);
       player.ap = 0;
-      advanceTurn();
+      (ctx.passTurn ?? advanceTurn)();
       return;
     }
     case 'cancel':
diff --git a/src/shell/shellRuntime.ts b/src/shell/shellRuntime.ts
index 3e061a4..eca315e 100644
--- a/src/shell/shellRuntime.ts
+++ b/src/shell/shellRuntime.ts
@@ -976,9 +976,7 @@ function onUseItem(evt: Event) {
   }
   itemInventoryEl.hide();
   paint();
-  if (run.player.ap === 0) {
-    advanceTurn();
-  }
+  concludeOperatorTurn();
 }
 
 /**
@@ -1112,9 +1110,7 @@ function resolveAimedUseItem(aim: { dx: number; dy: number }, run: Run): void {
     return;
   }
   paint();
-  if (run.player.ap === 0) {
-    advanceTurn();
-  }
+  concludeOperatorTurn();
 }
 
 function handlePersist() {
@@ -1383,15 +1379,82 @@ function handleFlip(): void {
   }
   // The look cursor + any aim mode are layer-specific — clear them before the
   // view swaps out from under them.
+  run.flip();
+  repaintAfterFlip(run, 'SIMSTIM');
+}
+
+/**
+ * Shared post-flip presentation: the look cursor + any aim mode are
+ * layer-specific, so clear them before the view swaps, then recompute vision,
+ * repaint, and flash where control landed. `prefix` distinguishes a manual
+ * flip (`SIMSTIM`) from an auto-flip on AP exhaustion (`OPERATOR SPENT …`).
+ * The flip mutation itself has already happened on the `Run` by the time we
+ * get here.
+ */
+function repaintAfterFlip(run: Run, prefix: string): void {
   lookCursor = null;
   resetInputModes();
-  run.flip();
   recomputeVision();
   paint();
   const actor = activeActorOf(run);
   const where = isCyberView(run) ? 'CYBERSPACE' : 'MEATSPACE';
   const who = actor && 'callsign' in actor && actor.callsign ? ` · ${actor.callsign}` : '';
-  flash(`SIMSTIM → ${where}${who}`);
+  flash(`${prefix} → ${where}${who}`);
+}
+
+/**
+ * P3.M4.4: resolve the active operator running out of AP. Replaces the bare
+ * `advanceTurn()` at every auto-end-on-exhaustion site. Independent AP pools
+ * mean exhausting one operator does *not* end the mutual turn while another
+ * still has AP — `Run.concludeActiveOperatorTurn()` auto-flips control to it
+ * instead; only when the whole crew is spent do we drive the hostile phases.
+ * Explicit Wait (`end-turn`) keeps its own hard `advanceTurn()` escape hatch.
+ */
+function concludeOperatorTurn(): void {
+  const run = currentScene();
+  if (!run || !isRun(run)) {
+    advanceTurn();
+    return;
+  }
+  switch (run.concludeActiveOperatorTurn()) {
+    case 'continue':
+      return;
+    case 'end':
+      advanceTurn();
+      return;
+    case 'auto-flip':
+      repaintAfterFlip(run, 'OPERATOR SPENT');
+      return;
+  }
+}
+
+/**
+ * P3.M4.4: resolve a Wait (`.`). The active operator has forfeited its AP;
+ * Wait always hands control to the other operator when one exists (consistent
+ * "pass/switch" gesture), and additionally ends the mutual turn — driving the
+ * hostile phases — once the whole crew is spent.
+ */
+function passOperatorTurn(): void {
+  const run = currentScene();
+  if (!run || !isRun(run)) {
+    advanceTurn();
+    return;
+  }
+  switch (run.passActiveOperatorTurn()) {
+    case 'end':
+      advanceTurn();
+      return;
+    case 'flip':
+      repaintAfterFlip(run, 'WAIT');
+      return;
+    case 'flip-and-end':
+      // Control handed to the other operator (so next turn opens there), then
+      // the crew-spent turn ends; repaint first so the corp/ICE phases animate
+      // on the operator we flipped to.
+      repaintAfterFlip(run, 'WAIT');
+      advanceTurn();
+      return;
+  }
 }
 
 export function handleIntent(intent: Intent): void {
@@ -1453,6 +1516,8 @@ export function handleIntent(intent: Intent): void {
     // Capture the action line for the next paint(); see lastActionLine docs.
     log: (line: string) => flash(line),
     advanceTurn,
+    concludeTurn: concludeOperatorTurn,
+    passTurn: passOperatorTurn,
     resetInputModes,
     onUseItem: (aim: { dx: number; dy: number }) => {
       resolveAimedUseItem(aim, run as Run);
@@ -1883,9 +1948,9 @@ function handleSecuredInteract(
   const fired = pulseSecuredInteractable(entity);
   if (!apExhausted) return;
   if (fired) {
-    scheduleCombatPump(() => advanceTurn(), ANIMATION_DURATIONS.INTERACT_SECURED_FLASH);
+    scheduleCombatPump(() => concludeOperatorTurn(), ANIMATION_DURATIONS.INTERACT_SECURED_FLASH);
   } else {
-    advanceTurn();
+    concludeOperatorTurn();
   }
 }
 
@@ -1925,9 +1990,7 @@ function handleCombatInteract(): void {
             `Salvaged +${amount} — carrying ${formatSalvageCompact(inventory.salvage)}. ${player.ap} AP left.`
           );
           paint();
-          if (player.ap === 0) {
-            advanceTurn();
-          }
+          concludeOperatorTurn();
           return;
         }
       }
@@ -1946,7 +2009,7 @@ function handleCombatInteract(): void {
     ) {
       handleSecuredInteract(interactable, { apExhausted: player.ap === 0 });
     } else if (result.ok && player.ap === 0) {
-      advanceTurn();
+      concludeOperatorTurn();
     }
     paint();
     return;
diff --git a/tests/unit/game/cyber/dualDeploy.test.ts b/tests/unit/game/cyber/dualDeploy.test.ts
index a9db952..089987d 100644
--- a/tests/unit/game/cyber/dualDeploy.test.ts
+++ b/tests/unit/game/cyber/dualDeploy.test.ts
@@ -9,6 +9,7 @@ import assert from 'node:assert/strict';
 
 import { Run } from '../../../../src/game/Run.js';
 import { Campaign } from '../../../../src/game/Campaign.js';
+import { JackInPoint } from '../../../../src/game/entities/JackInPoint.js';
 import { OUTCOME } from '../../../../src/game/Run.js';
 import { OBJECTIVES } from '../../../../src/game/hub/Curator.js';
 import { buildCrewMember } from '../../../../src/game/archetypes/index.js';
@@ -193,6 +194,59 @@ test('P3.M4.1: partner survives a campaign round-trip in COMBAT state', () => {
   assert.equal(restored.activeRun?.partnerMember?.flatlined, false);
 });
 
+// P3.M4.4 regression: once the partner is a live grid entity (jacked in, or
+// jacked out), the campaign restore must keep `partnerMember` pointing at that
+// grid entity — not the off-grid canonical roster copy. Rebinding it to the
+// roster object stranded the partner off the map: flipping to it controlled a
+// phantom that couldn't move (the on-grid copy sat frozen in place).
+function jackInCampaignRun(run: Run) {
+  const point = [...run.world!.entities.values()].find(e => e instanceof JackInPoint) as JackInPoint;
+  let spot: { x: number; y: number } | null = null;
+  for (let dy = -1; dy <= 1 && !spot; dy++) {
+    for (let dx = -1; dx <= 1 && !spot; dx++) {
+      if (dx === 0 && dy === 0) continue;
+      const x = point.x + dx;
+      const y = point.y + dy;
+      if (
+        run.world!.grid.inBounds(x, y) &&
+        run.world!.grid.isPassable(x, y) &&
+        !run.world!.entityAt(x, y)
+      ) {
+        spot = { x, y };
+      }
+    }
+  }
+  run.world!.relocateEntity(run.player!, spot!.x, spot!.y);
+  run.player!.refreshAp();
+  assert.equal(point.interact(run.world!, run.player!).ok, true);
+}
+
+test('P3.M4.4: after jack-out the campaign round-trip keeps the partner on the grid', () => {
+  const campaign = act2Campaign();
+  const decker = deckerOf(campaign);
+  const partner = meatOf(campaign);
+  const run = campaign.deployCrewMember(decker.id, cyberContract(), partner.id);
+  run.enterCombat();
+  jackInCampaignRun(run); // spawns the partner on the meat grid
+  run.jackOut(); // phase → resolved; both meat crew on the grid, control on the body
+  assert.equal(run.cyberspace?.phase, 'resolved');
+
+  const restored = restoreCampaign(structuredClone(snapshotCampaign(campaign)));
+  const rerun = restored.activeRun!;
+
+  // The partner reference IS the live grid entity (identity), not an off-grid
+  // roster copy — so flipping to it controls the thing the player can see.
+  const gridPartner = rerun.world!.entities.get(partner.id);
+  assert.ok(gridPartner, 'partner is a live entity on the restored meat grid');
+  assert.equal(rerun.partnerMember, gridPartner, 'partnerMember is the grid entity');
+  assert.equal(rerun.partnerMember!.frozen, false, 'partner is not frozen post jack-out');
+
+  // Flip to the partner: the active meat operator is the on-grid entity.
+  rerun.flip();
+  assert.equal(rerun.meatActor, gridPartner);
+  assert.equal(rerun.world!.entities.get(rerun.meatActor!.id), rerun.meatActor);
+});
+
 test('P3.M4.1: partner survives a standalone run snapshot/restore', () => {
   const run = new Run({ crewMember: makeDecker(), partnerMember: makeMerc(), seed: 42 });
   run.enterBriefing(cyberContract());
diff --git a/tests/unit/game/cyber/operatorTurnConclude.test.ts b/tests/unit/game/cyber/operatorTurnConclude.test.ts
new file mode 100644
index 0000000..7558d77
--- /dev/null
+++ b/tests/unit/game/cyber/operatorTurnConclude.test.ts
@@ -0,0 +1,284 @@
+/**
+ * P3.M4.4 — independent AP pools + decoupled turn-end. Each dual-deploy
+ * operator keeps its own AP pool; the mutual turn ends (driving the corp +
+ * ICE hostile phases) only when *every controllable* operator is spent — not
+ * when whichever one you happen to be driving hits 0. Exhausting the active
+ * operator while the other still has AP **auto-flips** control to it instead
+ * of ending the turn.
+ *
+ * `Run.endOfTurnReady()` is the model-level "the crew is spent" predicate;
+ * `Run.concludeActiveOperatorTurn()` is the decision+handoff the shell wires
+ * its auto-end sites to (`'continue' | 'auto-flip' | 'end'`).
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { Run } from '../../../../src/game/Run.js';
+import { JackInPoint } from '../../../../src/game/entities/JackInPoint.js';
+import { CyberAvatar } from '../../../../src/game/cyber/CyberAvatar.js';
+import { buildCrewMember } from '../../../../src/game/archetypes/index.js';
+import { OBJECTIVES } from '../../../../src/game/hub/Curator.js';
+import { Rng } from '../../../../src/rng.js';
+import { testContractContext } from '../contractTestUtils.js';
+import type { World } from '../../../../src/game/World.js';
+import type { Entity } from '../../../../src/game/Entity.js';
+
+const cyberContract = (overrides = {}) => ({
+  seed: 12345,
+  objective: {
+    kind: OBJECTIVES.DATA_NODE_SLICE,
+    title: 'Spike the server farm',
+    briefing: 'Jack in, slice the data node, then extract.',
+    params: { requiresCyberspace: true, count: 1 },
+  },
+  difficulty: 'standard',
+  threatCount: 1,
+  label: 'cyber casing job',
+  context: testContractContext(OBJECTIVES.DATA_NODE_SLICE),
+  reward: { credits: 0, repDelta: 0 },
+  ...overrides,
+});
+
+const meatContract = (overrides = {}) => ({
+  seed: 999,
+  objective: {
+    kind: OBJECTIVES.REACH_EXIT,
+    title: 'Extract clean',
+    briefing: 'Reach the exit.',
+  },
+  difficulty: 'standard',
+  threatCount: 1,
+  label: 'meat job',
+  context: testContractContext(OBJECTIVES.REACH_EXIT),
+  reward: { credits: 0, repDelta: 0 },
+  ...overrides,
+});
+
+const makeDecker = () =>
+  buildCrewMember('decker', { x: 0, y: 0 }, new Rng(100), { id: 'crew-decker' });
+const makeMerc = () => buildCrewMember('merc', { x: 0, y: 0 }, new Rng(101), { id: 'crew-merc' });
+
+function dualRun(seed = 12345) {
+  const run = new Run({ crewMember: makeDecker(), partnerMember: makeMerc(), seed });
+  run.enterBriefing(cyberContract({ seed }));
+  run.enterCombat();
+  return run;
+}
+function soloRun(seed = 12345) {
+  const run = new Run({ crewMember: makeDecker(), seed });
+  run.enterBriefing(cyberContract({ seed }));
+  run.enterCombat();
+  return run;
+}
+function meatRun(seed = 999) {
+  const run = new Run({ crewMember: makeMerc(), seed });
+  run.enterBriefing(meatContract({ seed }));
+  run.enterCombat();
+  return run;
+}
+
+function adjacentFreeTile(world: World, target: Entity) {
+  for (let dy = -1; dy <= 1; dy++) {
+    for (let dx = -1; dx <= 1; dx++) {
+      if (dx === 0 && dy === 0) continue;
+      const x = target.x + dx;
+      const y = target.y + dy;
+      if (world.grid.inBounds(x, y) && world.grid.isPassable(x, y) && !world.entityAt(x, y)) {
+        return { x, y };
+      }
+    }
+  }
+  throw new Error(`no free tile adjacent to ${target.id}`);
+}
+
+function jackIn(run: Run) {
+  const point = [...run.world!.entities.values()].find(e => e instanceof JackInPoint) as JackInPoint;
+  const spot = adjacentFreeTile(run.world!, point);
+  run.world!.relocateEntity(run.player!, spot.x, spot.y);
+  run.player!.refreshAp();
+  assert.equal(point.interact(run.world!, run.player!).ok, true);
+}
+
+const drain = (a: { ap: number; spendAp(n: number): void }) => a.spendAp(a.ap);
+
+// ---------------------------------------------------------------------------
+// endOfTurnReady — the "crew is spent" predicate
+// ---------------------------------------------------------------------------
+
+test('P3.M4.4: not end-ready while the active operator still has AP', () => {
+  const run = dualRun();
+  jackIn(run);
+  assert.ok(run.activeActor!.ap > 0);
+  assert.equal(run.endOfTurnReady(), false);
+});
+
+test('P3.M4.4: not end-ready when the active operator is spent but the other still has AP', () => {
+  const run = dualRun();
+  jackIn(run);
+  // Control starts on the meat partner; spend it dry, avatar still full.
+  drain(run.activeActor!);
+  assert.equal(run.activeActor!.ap, 0);
+  assert.ok(run.cyberspace!.phase === 'active' && run.cyberspace.layer.avatar.ap > 0);
+  assert.equal(run.endOfTurnReady(), false);
+});
+
+test('P3.M4.4: end-ready only once both controllable operators are spent', () => {
+  const run = dualRun();
+  jackIn(run);
+  const avatar = run.cyberspace!.phase === 'active' ? run.cyberspace.layer.avatar : null;
+  drain(run.meatActor!);
+  drain(avatar!);
+  assert.equal(run.endOfTurnReady(), true);
+});
+
+// ---------------------------------------------------------------------------
+// concludeActiveOperatorTurn — continue / auto-flip / end
+// ---------------------------------------------------------------------------
+
+test('P3.M4.4: concluding with AP left is a no-op continue', () => {
+  const run = dualRun();
+  jackIn(run);
+  const before = run.activeActor;
+  assert.equal(run.concludeActiveOperatorTurn(), 'continue');
+  assert.equal(run.activeActor, before, 'control did not move');
+});
+
+test('P3.M4.4: exhausting one operator auto-flips control to the other (no turn end, no refresh)', () => {
+  const run = dualRun();
+  jackIn(run);
+  const partner = run.meatActor!;
+  const avatar = run.cyberspace!.phase === 'active' ? run.cyberspace.layer.avatar : null;
+  assert.ok(avatar instanceof CyberAvatar);
+  const turnBefore = run.queue!.turnNumber;
+
+  drain(partner);
+  assert.equal(run.concludeActiveOperatorTurn(), 'auto-flip');
+
+  // Control handed to the avatar; the partner's spent pool was NOT refreshed,
+  // and no corp/ICE turn advanced (the queue did not flip factions).
+  assert.equal(run.activeLayer, 'cyber');
+  assert.equal(run.activeActor, avatar);
+  assert.equal(partner.ap, 0, 'spent partner pool untouched — no early refresh');
+  assert.equal(avatar!.ap, avatar!.maxAp, 'avatar keeps its full, independent pool');
+  assert.equal(run.queue!.turnNumber, turnBefore, 'mutual turn did not advance');
+});
+
+test('P3.M4.4: exhausting the second operator ends the mutual turn', () => {
+  const run = dualRun();
+  jackIn(run);
+  const avatar = run.cyberspace!.phase === 'active' ? run.cyberspace.layer.avatar : null;
+
+  drain(run.meatActor!);
+  assert.equal(run.concludeActiveOperatorTurn(), 'auto-flip'); // → cyber
+  drain(avatar!);
+  assert.equal(run.concludeActiveOperatorTurn(), 'end');
+});
+
+// ---------------------------------------------------------------------------
+// Wait (passActiveOperatorTurn) — always flips to the other operator
+// ---------------------------------------------------------------------------
+
+test('P3.M4.4: waiting with the other operator holding AP flips and keeps the turn open', () => {
+  const run = dualRun();
+  jackIn(run);
+  const avatar = run.cyberspace!.phase === 'active' ? run.cyberspace.layer.avatar : null;
+  drain(run.activeActor!); // Wait forfeits the partner's AP
+  assert.equal(run.passActiveOperatorTurn(), 'flip');
+  assert.equal(run.activeLayer, 'cyber');
+  assert.equal(run.activeActor, avatar);
+});
+
+test('P3.M4.4: waiting the LAST operator still flips, then ends the mutual turn', () => {
+  // The behaviour the playtest flagged: Wait must hand off consistently, even
+  // when the other operator is already spent (it just also ends the turn).
+  const run = dualRun();
+  jackIn(run);
+  const partner = run.meatActor!;
+  const avatar = run.cyberspace!.phase === 'active' ? run.cyberspace.layer.avatar : null;
+  // Both operators spent; control sits on the avatar (cyber).
+  drain(partner);
+  run.flip();
+  assert.equal(run.activeActor, avatar);
+  drain(avatar!);
+
+  assert.equal(run.passActiveOperatorTurn(), 'flip-and-end');
+  assert.equal(run.activeLayer, 'meat', 'Wait still flips control to the partner');
+  assert.equal(run.activeActor, partner);
+});
+
+test('P3.M4.4: a solo jack-in Wait just ends — nobody to flip to', () => {
+  const run = soloRun();
+  jackIn(run);
+  drain(run.activeActor!);
+  assert.equal(run.passActiveOperatorTurn(), 'end');
+  assert.equal(run.activeLayer, 'cyber', 'no flip — control stays on the lone avatar');
+});
+
+test('P3.M4.4: single-deploy Wait ends without flipping', () => {
+  const run = meatRun();
+  drain(run.activeActor!);
+  assert.equal(run.passActiveOperatorTurn(), 'end');
+});
+
+// ---------------------------------------------------------------------------
+// Auto-flip never targets the frozen body or a dead operator
+// ---------------------------------------------------------------------------
+
+test('P3.M4.4: a solo jack-in ends the turn at 0 AP — never flips to the frozen body', () => {
+  const run = soloRun();
+  jackIn(run);
+  // Solo: only the avatar is controllable; the body is frozen at the port.
+  assert.equal(run.activeLayer, 'cyber');
+  drain(run.activeActor!);
+  assert.equal(run.endOfTurnReady(), true);
+  assert.equal(run.concludeActiveOperatorTurn(), 'end');
+});
+
+test('P3.M4.4: a dead partner is not a flip target — exhausting the avatar ends the turn', () => {
+  const run = dualRun();
+  jackIn(run);
+  const partner = run.meatActor!;
+  const avatar = run.cyberspace!.phase === 'active' ? run.cyberspace.layer.avatar : null;
+  // Avatar takes control, partner falls on the meat field.
+  run.flip();
+  assert.equal(run.activeActor, avatar);
+  partner.damage(partner.hp); // flatline the partner
+  assert.equal(partner.alive, false);
+
+  drain(avatar!);
+  assert.equal(run.endOfTurnReady(), true, 'no living second operator to flip to');
+  assert.equal(run.concludeActiveOperatorTurn(), 'end');
+});
+
+// ---------------------------------------------------------------------------
+// Single-deploy (no cyber layer) — unchanged: end at 0
+// ---------------------------------------------------------------------------
+
+test('P3.M4.4: single-deploy meat run ends the turn when its one operator is spent', () => {
+  const run = meatRun();
+  assert.equal(run.canFlip(), false);
+  drain(run.activeActor!);
+  assert.equal(run.endOfTurnReady(), true);
+  assert.equal(run.concludeActiveOperatorTurn(), 'end');
+});
+
+// ---------------------------------------------------------------------------
+// Post jack-out: meat ↔ meat auto-flip between the two operators
+// ---------------------------------------------------------------------------
+
+test('P3.M4.4: after jack-out, exhausting one meat operator auto-flips to the other', () => {
+  const run = dualRun();
+  const decker = run.player!;
+  const partner = run.partnerMember!;
+  jackIn(run);
+  run.jackOut(); // no hook → resolves immediately
+
+  assert.equal(run.meatActor, decker);
+  drain(run.activeActor!); // drain the Decker
+  assert.equal(run.concludeActiveOperatorTurn(), 'auto-flip');
+  assert.equal(run.meatActor, partner, 'control flipped to the partner');
+  assert.equal(decker.ap, 0, 'no early refresh of the spent operator');
+
+  drain(run.activeActor!); // drain the partner
+  assert.equal(run.concludeActiveOperatorTurn(), 'end');
+});
diff --git a/tests/unit/input/applyIntent.test.ts b/tests/unit/input/applyIntent.test.ts
index 7b60892..1de3004 100644
--- a/tests/unit/input/applyIntent.test.ts
+++ b/tests/unit/input/applyIntent.test.ts
@@ -495,6 +495,21 @@ test('end-turn drains AP to 0, logs wait, and invokes advanceTurn once', () => {
   );
 });
 
+test('P3.M4.4: end-turn routes through passTurn when wired (Wait passes this operator)', () => {
+  // Dual-deploy: Wait forfeits the active operator's AP but defers the
+  // flip/end decision to the shell's pass handler, so the *other* operator
+  // takes over instead of having its turn dumped.
+  const { ctx, player, calls } = buildCtx();
+  let passed = 0;
+  ctx.passTurn = () => {
+    passed++;
+  };
+  applyIntent({ type: 'end-turn' }, ctx);
+  assert.equal(player.ap, 0, 'this operator forfeits its remaining AP');
+  assert.equal(passed, 1, 'Wait drives the pass/flip path');
+  assert.equal(calls.advanceTurn, 0, 'no hard end while passTurn is wired');
+});
+
 test('cancel calls resetInputModes and does not mutate state', () => {
   const { ctx, calls, player } = buildCtx();
   const beforeAp = player.ap;

From 150b6422790cd27a241643a5cf475e273b2e0532 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Mon, 15 Jun 2026 16:59:03 -0700
Subject: [PATCH 42/55] fix partner death issues

---
 docs/phase-3-plan.md                        |   4 +-
 src/game/Campaign.ts                        |   7 +
 src/game/Run.ts                             |  46 ++++
 src/game/persistence.ts                     |  11 +-
 src/shell/shellRuntime.ts                   |  10 +
 tests/unit/game/cyber/dualPhaseTurn.test.ts |  96 +++++++++
 tests/unit/game/cyber/partnerDeath.test.ts  | 228 ++++++++++++++++++++
 7 files changed, 399 insertions(+), 3 deletions(-)
 create mode 100644 tests/unit/game/cyber/partnerDeath.test.ts

diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 9b21b3a..0d30cac 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -346,10 +346,12 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 | **P3.M4.1 Dual deploy** | ✅ Done | Reserve the meat partner alongside the Decker on a Cyberspace deploy; `Run.partnerMember`, deploy gates, persistence | deploy gates, partner shape, campaign + standalone round-trip |
 | **P3.M4.2 Jacked body anchor + partner spawn** | ✅ Done (model) | Decker body freezes at port; partner spawns at a safe meat cell; `activeLayer`/`meatActor`/`deckerBody` on `Run` | body frozen+targetable, movement rejected, partner placement, determinism, round-trip |
 | **P3.M4.3 Flip command** | ✅ Done | Tab → free-action flip; `activeView` keys on `activeLayer`; `Run.flip()`/`canFlip()` | flip toggles layer/actor, solo+pre-jack can't flip, meat↔meat post-jack-out, keymap intent |
-| **P3.M4.4 Dual hostile phase** | 🟡 | Independent AP pools + decoupled turn-end (auto-flip on exhaustion); end turn advances corp and ICE phases once each | ✅ AP-pool/turn-end model (`endOfTurnReady`/`concludeActiveOperatorTurn`); ⬜ verify M3.6 dual-phase with partner+body present |
+| **P3.M4.4 Dual hostile phase** | ✅ Done | Independent AP pools + decoupled turn-end (auto-flip on exhaustion); both hostile phases tick once each with partner+body present; partner death handled | AP-pool/turn-end model; dual-phase verify with partner+body; partner flatline + control repair + alert |
 | **P3.M4.5 PIP** | 🔲 | Inactive layer mini-render + status summary | desktop/mobile layout, no input capture |
 | **P3.M4.6 Jack-out** | 🔲 | Voluntary + forced (1-HP) jack-out transitions back to Meatspace | cleanup, objective failure rules, snapshot round-trip |
 
+**P3.M4.4 — dual-phase verify + partner death (2026-06-15):** The M3.6 dual-phase corp turn (chained meat pass → ICE pass on the shared run rng) was only ever tested solo-Decker; re-verified with a partner + frozen body on the meat grid: the meat pass steps neither PLAYER operator, both layers tick regardless of which layer the player is viewing, one AP refresh per round across body + partner + avatar (+ ICE), determinism holds with the partner present (PLAYER faction draws no corp rng), and post-jack-out the meat corp turn runs solo (no ICE pass) with both operators present (`dualPhaseTurn.test.ts`, +5). **Partner death** (the playtest report — partner killed off-screen during the corp turn while the player was in Cyberspace, discovered only via a "no operator to flip to" deny): the meat partner flatlining is *not* run-ending (the Decker fights on), handled in `Run.#onEntityDamaged` → `#onPartnerFlatlined` — it repairs the active-operator state so the player never drives a corpse (if the dead partner was the meat actor, control returns to the Decker `player`; while still jacked in the body is frozen, so the view also force-flips to Cyberspace onto the avatar), and fires a new `onPartnerDown` shell hook that flashes an **unconditional** "⚠ OPERATOR DOWN" alert (the kill is invisible from the grid view). `Run.partnerDown` (partner fielded + not alive) drives `Campaign.onJobEnd`, which flatlines `deployedPartnerId` for good — independent of the Decker's outcome (extracted clean or died), and across a campaign round-trip. Tests: `partnerDeath.test.ts` (8). Closes the partner-death follow-up that M4.2 deferred. **Restore companion fix (playtest, dead-partner-stuck save):** `#onPartnerFlatlined` repairs control at the *moment* of death, but `restore()` still set `meatActor = gridPartner` unconditionally — so a save with a jacked-in run + dead partner (or any pre-fix save) reconstructed the stuck state (driving a corpse in Meatspace, `canFlip` false). Restore now mirrors the live repair: a dead grid partner is never the meat operator — `meatActor` falls back to the (frozen) body and the view defaults to Cyberspace onto the avatar; a living partner restores normally honoring the saved view.
+
 **P3.M4.4 bugfix — stranded partner after restore (2026-06-15, playtest):** On a campaign mid-run restore, flipping to the meat partner after the Decker jacked out controlled a phantom: the partner appeared "stuck in a wall off the map" and couldn't move. Contributing factors: (1) restore rebuilds grid entities as *detached copies*, separate from the canonical roster crew objects; the primary tolerates this because `run.player` stays the grid copy (operator) while `crewMember` is re-linked to the roster object (identity) — two fields. (2) The partner has only `partnerMember`, doing double duty as both operator and roster ref. (3) `restoreActiveRun` unconditionally rebound `partnerMember` to the off-grid canonical roster object, so once the partner was a live grid entity (jacked in / jacked out) the flip's `#aliveMeatAlternate` handed control to the off-grid copy (id-match in `world.entities.has` masked it), centering the camera on the roster object's `(0,0)` and denying movement. Fix: `restoreActiveRun` re-binds `partnerMember` to the canonical object **only while it is still off-grid** (a dormant reserve a later jack-in spawns); once it is a live grid entity, keep that entity — mirroring `run.player`. Regression test: `dualDeploy.test.ts` "after jack-out the campaign round-trip keeps the partner on the grid" (identity + flip). **Follow-up (broader, pre-existing):** the detached-grid-copy-vs-canonical-roster split means combat stats applied *after* a mid-run restore land on the grid copy, not the roster object — a latent crew-HP desync across save→restore→play→save for the primary too. Investigate whether job-end reconciliation already covers it; if not, restore should rehydrate the canonical crew objects *as* the grid entities so there is one object, as in live play.
 
 **P3.M4.4 implementation note — AP pools (2026-06-15):** Independent AP pools with a decoupled turn-end, settled from playtest (see the resolved decision above). Two new pure `Run` methods carry the model: **`endOfTurnReady()`** — the active actor is at 0 AP and there is no flip alternate with AP left (`#flipAlternate()` returns the operator `flip()` would hand control to: the other layer's operator while jacked, else the other live meat operator); and **`concludeActiveOperatorTurn(): 'continue' | 'auto-flip' | 'end'`** — `'continue'` while the active actor still has AP, `'end'` once the crew is spent (the shell drives the corp+ICE phases, which refresh every pool once), `'auto-flip'` when the active operator is spent but another still has AP (the method performs the flip; a spent-but-not-end-ready actor guarantees a live alternate with AP, so the flip is always safe). The frozen Decker body is never the active actor nor a flip alternate, so its full pool can't keep the turn alive; solo/single-deploy has no alternate and ends at 0 as before (no M3 regression). Shell: every auto-end-on-exhaustion site (the `applyIntent` `gateOnApExhausted` via new optional `ctx.concludeTurn`, plus consumable / loot / secured-interact) routes through one `concludeOperatorTurn()` helper that switches on the discriminant — `'end'` → `advanceTurn()`, `'auto-flip'` → shared `repaintAfterFlip(run, 'OPERATOR SPENT')` (factored out of `handleFlip`). **Wait** (`end-turn`) zeroes the active operator's AP then routes through a *separate* `passTurn` hook → `Run.passActiveOperatorTurn(): 'flip' | 'flip-and-end' | 'end'` (playtest refinement). Unlike exhaustion, Wait **always** flips to the other operator when one exists (`#flipAlternate` non-null), regardless of that operator's AP — `'flip'` keeps the turn open, `'flip-and-end'` also drives the hostile phases (next turn opens on the flipped-to operator), `'end'` is the solo/single-deploy case; the `?? advanceTurn` fallback keeps a hard end for harness contexts. The shell's `passOperatorTurn` repaints (`repaintAfterFlip(run, 'WAIT')`) on both flip outcomes and additionally `advanceTurn()`s on `'flip-and-end'`. Tests: `operatorTurnConclude.test.ts` (14) and an `applyIntent` `end-turn`-routes-through-`passTurn` case covers the predicate, the three-way conclude, auto-flip-not-end-not-refresh, never flipping to a dead/frozen operator, solo/single-deploy end-at-0, and post-jack-out meat↔meat. **Still open for M4.4:** verify the M3.6 dual-phase corp turn (`dualPhaseTurn.test.ts` was solo-Decker only) holds with the partner+body present — both layers tick once, no double refresh, deterministic with the partner on the field.
diff --git a/src/game/Campaign.ts b/src/game/Campaign.ts
index 8f51da0..d243a0b 100644
--- a/src/game/Campaign.ts
+++ b/src/game/Campaign.ts
@@ -602,6 +602,13 @@ export class Campaign {
       isScoreContract(this.activeRun.contract) &&
       outcome === OUTCOME.DEATH;
 
+    // P3.M4.4: a meat partner that flatlined on the field is gone for good —
+    // independent of the Decker's outcome. The Decker may have extracted clean
+    // while the partner died covering the body; flatline the partner either way.
+    if (this.deployedPartnerId && this.activeRun.partnerDown) {
+      this.flatlineMember(this.deployedPartnerId);
+    }
+
     if (outcome === OUTCOME.DEATH) {
       this.flatlineMember(this.deployedMemberId);
     } else {
diff --git a/src/game/Run.ts b/src/game/Run.ts
index 4107a18..1420a7f 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -392,6 +392,10 @@ export type RunOptions = {
   onJackInPresent?: unknown;
   /** Shell presentation — fired after jack-out finalizes. */
   onJackOutPresent?: unknown;
+  /** P3.M4.4 shell presentation — fired when the meat partner flatlines on the
+   *  field (the corp can kill it off-screen while the player is in Cyberspace),
+   *  so the shell can surface an unconditional "operator down" alert. */
+  onPartnerDown?: unknown;
   /** Terrain mutations from a prior visit to this location (P2.5.M7.2), replayed
    *  onto the freshly-built map in `enterCombat`. Empty/omitted for a first visit. */
   priorMutationDeltas?: unknown;
@@ -483,6 +487,8 @@ export class Run {
   onJackInPresent: (() => void) | null;
   /** Shell presentation hook — fired after jack-out finalizes. */
   onJackOutPresent: (() => void) | null;
+  /** P3.M4.4 shell presentation hook — fired with the partner when it flatlines. */
+  onPartnerDown: ((partner: Crew) => void) | null;
   _busUnsubs: (() => void)[];
 
   constructor({
@@ -496,6 +502,7 @@ export class Run {
     onJackOutRequested,
     onJackInPresent,
     onJackOutPresent,
+    onPartnerDown,
     priorMutationDeltas,
     priorKeyItems,
     priorSeenKeys,
@@ -528,6 +535,9 @@ export class Run {
     if (onJackOutPresent !== undefined && typeof onJackOutPresent !== 'function') {
       throw new TypeError('Run: onJackOutPresent must be a function');
     }
+    if (onPartnerDown !== undefined && typeof onPartnerDown !== 'function') {
+      throw new TypeError('Run: onPartnerDown must be a function');
+    }
     if (priorMutationDeltas !== undefined && !Array.isArray(priorMutationDeltas)) {
       throw new TypeError('Run: priorMutationDeltas must be an array when supplied');
     }
@@ -572,6 +582,7 @@ export class Run {
     this.onJackOutRequested = (onJackOutRequested as (() => void) | undefined) ?? null;
     this.onJackInPresent = (onJackInPresent as (() => void) | undefined) ?? null;
     this.onJackOutPresent = (onJackOutPresent as (() => void) | undefined) ?? null;
+    this.onPartnerDown = (onPartnerDown as ((partner: Crew) => void) | undefined) ?? null;
 
     /** @type {Array<() => void>} active bus subscriptions */
     this._busUnsubs = [];
@@ -969,6 +980,15 @@ export class Run {
     return this.cyberspace?.phase === 'active' && this.player instanceof Decker ? this.player : null;
   }
 
+  /**
+   * P3.M4.4: true when a dual-deploy meat partner was fielded and has flatlined
+   * on the grid. The run does not end on partner death (the Decker fights on),
+   * but `Campaign.onJobEnd` flatlines the partner for good once the run wraps.
+   */
+  get partnerDown(): boolean {
+    return !!this.partnerMember && !this.partnerMember.alive;
+  }
+
   /**
    * P3.M4.3: is there a second operator to flip control to right now?
    *   - Jacked in: flip between the controllable meat operator and the cyber
@@ -1068,6 +1088,24 @@ export class Run {
     return this.endOfTurnReady() ? 'flip-and-end' : 'flip';
   }
 
+  /**
+   * P3.M4.4: the meat partner just flatlined. Repair the active-operator state
+   * so the player is never left driving a corpse, then alert the shell. If the
+   * dead partner was the meat operator, hand meat control back to the Decker
+   * (`player`); while still jacked in, the body is frozen and can't act, so also
+   * force the view to Cyberspace (the avatar is the only live operator). The
+   * shell hook surfaces the alert even when the kill happened off-screen.
+   */
+  #onPartnerFlatlined(partner: Crew): void {
+    if (this.meatActor === partner) {
+      this.meatActor = this.player;
+      if (this.cyberspace?.phase === 'active') {
+        this.activeLayer = 'cyber';
+      }
+    }
+    this.onPartnerDown?.(partner);
+  }
+
   /**
    * The *other* live meat operator on the grid (Decker ↔ partner), distinct
    * from the current `meatActor`. `null` when there is no second one — pre-jack
@@ -1546,6 +1584,14 @@ export class Run {
       }
       return;
     }
+    // P3.M4.4: the meat partner flatlining is *not* run-ending — the Decker
+    // fights on (jacked in, or post jack-out). But it loses the player a meat
+    // operator, so repair control state and alert the shell unconditionally
+    // (the kill can land off-screen while the player is in Cyberspace).
+    if (killed && this.partnerMember && target === this.partnerMember) {
+      this.#onPartnerFlatlined(this.partnerMember);
+      return;
+    }
     if (attacker === this.player && killed) {
       this.telemetry.kills = (this.telemetry.kills ?? 0) + 1;
     } else if (killed && attacker instanceof Turret && attacker.ownerId === this.player.id) {
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index d3a9b65..0a1759e 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -1143,8 +1143,15 @@ export function restore(record: unknown, options: RestoreOptions = {}) {
   // spawned) unless the save had flipped into Cyberspace.
   if (cyberPhase === 'active') {
     player.frozen = true;
-    run.meatActor = gridPartner ?? player;
-    run.activeLayer = record.activeLayer === 'cyber' ? 'cyber' : 'meat';
+    // P3.M4.4: a *dead* partner can't be the meat operator — restoring it as
+    // `meatActor` strands the player driving a corpse with no flip target (the
+    // dead-partner-stuck save). While jacked in the body is frozen, so the only
+    // live operator is the avatar; default control to Cyberspace, mirroring the
+    // live repair in `Run.#onPartnerFlatlined`. A living partner restores
+    // normally, honoring the saved view.
+    const liveMeatPartner = gridPartner?.alive ? gridPartner : null;
+    run.meatActor = liveMeatPartner ?? player;
+    run.activeLayer = liveMeatPartner && record.activeLayer !== 'cyber' ? 'meat' : 'cyber';
   } else {
     run.meatActor = player;
     run.activeLayer = 'meat';
diff --git a/src/shell/shellRuntime.ts b/src/shell/shellRuntime.ts
index eca315e..e5c754b 100644
--- a/src/shell/shellRuntime.ts
+++ b/src/shell/shellRuntime.ts
@@ -1208,6 +1208,16 @@ function wireRunConfirmations(run: Run): void {
     paint();
   };
   run.onJackOutPresent = () => completeJackOutShellSwap();
+  run.onPartnerDown = partner => {
+    // P3.M4.4: the corp can flatline the partner on the meat grid while the
+    // player is jacked into Cyberspace and never sees it — so the alert is
+    // unconditional. The model force-flips control off the corpse (the body is
+    // frozen), so recompute vision + repaint to match the new active operator.
+    const who = partner.callsign ?? partner.id;
+    recomputeVision();
+    paint();
+    flash(`⚠ OPERATOR DOWN — ${who} flatlined. Your meat cover is gone.`);
+  };
 }
 
 function resumeCampaign(record: CampaignSnapshot | unknown) {
diff --git a/tests/unit/game/cyber/dualPhaseTurn.test.ts b/tests/unit/game/cyber/dualPhaseTurn.test.ts
index eaefc80..fbd5523 100644
--- a/tests/unit/game/cyber/dualPhaseTurn.test.ts
+++ b/tests/unit/game/cyber/dualPhaseTurn.test.ts
@@ -21,6 +21,7 @@ import { Rng } from '../../../../src/rng.js';
 import { testContractContext } from '../contractTestUtils.js';
 import type { World } from '../../../../src/game/World.js';
 import type { Entity } from '../../../../src/game/Entity.js';
+import type { Crew } from '../../../../src/game/Crew.js';
 import type { TurnActionStep } from '../../../../src/types.js';
 
 const cyberContract = (seed = 12345) => ({
@@ -185,3 +186,98 @@ test('an ICE pass with the avatar in sight yields the trace flare', () => {
   );
   assert.equal(layer.world.alarmActive, true);
 });
+
+// --- P3.M4.4: the dual phase with a meat partner + frozen body present -------------------
+//
+// The M3.6 tests above all run a *solo* Decker — one PLAYER entity (the frozen
+// body) on the meat grid, always viewed from Cyberspace. A dual deploy adds a
+// live mobile partner and lets the player view either layer. Re-verify the four
+// invariants under those new conditions.
+
+function jackedInDualRun(seed = 12345): {
+  run: Run;
+  layer: CyberspaceLayer;
+  partner: Crew;
+  body: Crew;
+} {
+  const decker = buildCrewMember('decker', { x: 0, y: 0 }, new Rng(100), { id: 'crew-decker' });
+  const partner = buildCrewMember('merc', { x: 0, y: 0 }, new Rng(101), { id: 'crew-merc' });
+  const run = new Run({ crewMember: decker, partnerMember: partner, seed });
+  run.enterBriefing(cyberContract(seed));
+  run.enterCombat();
+  const point = Array.from(run.world!.entities.values()).find(
+    e => e instanceof JackInPoint
+  ) as JackInPoint;
+  const spot = adjacentFreeTile(run.world!, point);
+  run.world!.relocateEntity(run.player!, spot.x, spot.y);
+  run.player!.refreshAp();
+  assert.equal(point.interact(run.world!, run.player!).ok, true);
+  const layer = (run.cyberspace as { phase: 'active'; layer: CyberspaceLayer }).layer;
+  return { run, layer, partner: run.partnerMember!, body: run.player! };
+}
+
+test('P3.M4.4: the meat pass steps neither the frozen body nor the live partner', () => {
+  const { run, layer, partner, body } = jackedInDualRun();
+  const operators = new Set([partner.id, body.id]);
+  const { meat } = dualPhaseRound(run, layer);
+  assert.ok(meat.length >= 0);
+  for (const { id } of meat) {
+    assert.ok(!operators.has(id), `meat pass stepped a PLAYER operator (${id})`);
+  }
+});
+
+test('P3.M4.4: both layers tick even while the player is viewing Meatspace', () => {
+  const { run, layer } = jackedInDualRun();
+  run.activeLayer = 'meat'; // controlling the partner, not the avatar
+  const ids = iceIds(layer);
+  const { ice } = dualPhaseRound(run, layer);
+  assert.ok(ice.length > 0, 'ICE still patrol while the player views Meatspace');
+  for (const { id } of ice) {
+    assert.ok(ids.has(id), `ICE pass stepped a non-ICE entity (${id})`);
+  }
+});
+
+test('P3.M4.4: one AP refresh per round for body, partner, and avatar', () => {
+  const { run, layer, partner, body } = jackedInDualRun();
+  layer.avatar.spendAp(2);
+  partner.spendAp(partner.ap);
+  body.spendAp(body.ap);
+
+  run.queue!.endTurn(run.world!); // player → corp: PLAYER pools stay spent
+  assert.equal(partner.ap, 0, 'partner stays spent through the corp flip');
+  assert.equal(body.ap, 0, 'frozen body stays spent through the corp flip');
+  assert.equal(layer.avatar.ap, layer.avatar.maxAp - 2);
+
+  drivePass(run, run.world!, run.hostileFaction);
+  drivePass(run, layer.world, FACTION.CORP);
+
+  run.queue!.endTurn(run.world!); // corp → player: every PLAYER pool refreshes once
+  assert.equal(partner.ap, partner.maxAp, 'partner refreshed exactly once');
+  assert.equal(body.ap, body.maxAp, 'body refreshed on the same flip');
+  assert.equal(layer.avatar.ap, layer.avatar.maxAp, 'avatar refreshed on the same flip');
+});
+
+test('P3.M4.4: the dual-phase round is deterministic with a partner on the field', () => {
+  const a = jackedInDualRun(777);
+  const b = jackedInDualRun(777);
+  const roundA = dualPhaseRound(a.run, a.layer);
+  const roundB = dualPhaseRound(b.run, b.layer);
+  assert.deepEqual(roundA, roundB);
+
+  const c = jackedInDualRun(778);
+  const roundC = dualPhaseRound(c.run, c.layer);
+  assert.notDeepEqual(roundA, roundC);
+});
+
+test('P3.M4.4: after jack-out the meat corp turn runs solo with both operators present', () => {
+  const { run, partner, body } = jackedInDualRun();
+  run.jackOut();
+  assert.equal(run.cyberspace?.phase, 'resolved', 'no live cyber layer => no ICE pass');
+  // Both meat operators are still on the grid; the lone meat pass steps neither.
+  run.queue!.endTurn(run.world!);
+  const meat = drivePass(run, run.world!, run.hostileFaction);
+  const operators = new Set([partner.id, body.id]);
+  for (const { id } of meat) {
+    assert.ok(!operators.has(id), `corp pass stepped a PLAYER operator (${id})`);
+  }
+});
diff --git a/tests/unit/game/cyber/partnerDeath.test.ts b/tests/unit/game/cyber/partnerDeath.test.ts
new file mode 100644
index 0000000..9e022d0
--- /dev/null
+++ b/tests/unit/game/cyber/partnerDeath.test.ts
@@ -0,0 +1,228 @@
+/**
+ * P3.M4.4 — partner death. The meat partner can be killed by the corp on the
+ * meat grid — including off-screen while the player is jacked into Cyberspace
+ * (the exact playtest report). Partner death is *not* run-ending (the Decker
+ * fights on), but it must: flatline the partner for good at job end, never
+ * leave the player driving a corpse, and alert the shell unconditionally.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { Run, RUN_STATE, OUTCOME } from '../../../../src/game/Run.js';
+import { Campaign } from '../../../../src/game/Campaign.js';
+import { JackInPoint } from '../../../../src/game/entities/JackInPoint.js';
+import { CyberAvatar } from '../../../../src/game/cyber/CyberAvatar.js';
+import { buildCrewMember } from '../../../../src/game/archetypes/index.js';
+import { OBJECTIVES } from '../../../../src/game/hub/Curator.js';
+import { EVENT } from '../../../../src/game/events.js';
+import { FACTION } from '../../../../src/game/constants.js';
+import { Rng } from '../../../../src/rng.js';
+import {
+  snapshot,
+  restore,
+  snapshotCampaign,
+  restoreCampaign,
+} from '../../../../src/game/persistence.js';
+import { testContractContext } from '../contractTestUtils.js';
+import type { World } from '../../../../src/game/World.js';
+import type { Entity } from '../../../../src/game/Entity.js';
+import type { Crew } from '../../../../src/game/Crew.js';
+
+const cyberContract = (overrides = {}) => ({
+  seed: 12345,
+  objective: {
+    kind: OBJECTIVES.DATA_NODE_SLICE,
+    title: 'Spike the server farm',
+    briefing: 'Jack in, slice the data node, then extract.',
+    params: { requiresCyberspace: true, count: 1 },
+  },
+  difficulty: 'standard',
+  threatCount: 1,
+  label: 'cyber casing job',
+  context: testContractContext(OBJECTIVES.DATA_NODE_SLICE),
+  reward: { credits: 0, repDelta: 0 },
+  ...overrides,
+});
+
+const makeDecker = () =>
+  buildCrewMember('decker', { x: 0, y: 0 }, new Rng(100), { id: 'crew-decker' });
+const makeMerc = () => buildCrewMember('merc', { x: 0, y: 0 }, new Rng(101), { id: 'crew-merc' });
+
+function dualRun(opts: { onPartnerDown?: (p: Crew) => void } = {}) {
+  const run = new Run({
+    crewMember: makeDecker(),
+    partnerMember: makeMerc(),
+    seed: 12345,
+    ...opts,
+  });
+  run.enterBriefing(cyberContract());
+  run.enterCombat();
+  return run;
+}
+
+function adjacentFreeTile(world: World, target: Entity) {
+  for (let dy = -1; dy <= 1; dy++) {
+    for (let dx = -1; dx <= 1; dx++) {
+      if (dx === 0 && dy === 0) continue;
+      const x = target.x + dx;
+      const y = target.y + dy;
+      if (world.grid.inBounds(x, y) && world.grid.isPassable(x, y) && !world.entityAt(x, y)) {
+        return { x, y };
+      }
+    }
+  }
+  throw new Error(`no free tile adjacent to ${target.id}`);
+}
+
+function jackIn(run: Run) {
+  const point = [...run.world!.entities.values()].find(e => e instanceof JackInPoint) as JackInPoint;
+  const spot = adjacentFreeTile(run.world!, point);
+  run.world!.relocateEntity(run.player!, spot.x, spot.y);
+  run.player!.refreshAp();
+  assert.equal(point.interact(run.world!, run.player!).ok, true);
+}
+
+/** Flatline the partner the way the corp does — kill it, then fire the same
+ *  ENTITY_DAMAGED the Combat resolver emits, so `Run` sees a real death. */
+function flatlinePartner(run: Run) {
+  const partner = run.partnerMember!;
+  const attacker = [...run.world!.entities.values()].find(e => e.faction === FACTION.CORP) ?? null;
+  partner.damage(partner.hp);
+  run.bus!.emit(EVENT.ENTITY_DAMAGED, {
+    attacker,
+    target: partner,
+    damage: 5,
+    killed: true,
+    source: 'ranged',
+  });
+}
+
+// ---------------------------------------------------------------------------
+// The run survives; the partner is down
+// ---------------------------------------------------------------------------
+
+test('P3.M4.4: partner death does not end the run', () => {
+  const run = dualRun();
+  jackIn(run);
+  flatlinePartner(run);
+  assert.equal(run.state, RUN_STATE.COMBAT, 'the Decker fights on');
+  assert.equal(run.partnerMember!.alive, false);
+  assert.equal(run.partnerDown, true);
+});
+
+// ---------------------------------------------------------------------------
+// Never leaves the player driving a corpse
+// ---------------------------------------------------------------------------
+
+test('P3.M4.4: partner death while viewing Cyberspace leaves control on the avatar', () => {
+  const run = dualRun();
+  jackIn(run);
+  run.flip(); // view cyber
+  assert.equal(run.activeLayer, 'cyber');
+  flatlinePartner(run);
+  // Control still rides the avatar; the dead partner is no longer the meat actor.
+  assert.ok(run.activeActor instanceof CyberAvatar);
+  assert.notEqual(run.meatActor, run.partnerMember);
+  assert.equal(run.canFlip(), false, 'no live meat operator to flip to');
+});
+
+test('P3.M4.4: partner death while viewing Meatspace force-flips to the avatar', () => {
+  const run = dualRun();
+  jackIn(run);
+  // Control is in Meatspace on the partner (the post-jack-in default).
+  assert.equal(run.activeLayer, 'meat');
+  assert.equal(run.activeActor, run.partnerMember);
+  flatlinePartner(run);
+  // The player must not be left driving the corpse — view snaps to Cyberspace.
+  assert.equal(run.activeLayer, 'cyber');
+  assert.ok(run.activeActor instanceof CyberAvatar);
+});
+
+test('P3.M4.4: after jack-out, partner death hands meat control back to the Decker', () => {
+  const run = dualRun();
+  const decker = run.player!;
+  jackIn(run);
+  run.jackOut(); // resolved; both meat crew on the grid, control on the Decker
+  run.flip(); // control to the partner
+  assert.equal(run.meatActor, run.partnerMember);
+  flatlinePartner(run);
+  assert.equal(run.meatActor, decker, 'control returns to the Decker');
+  assert.equal(run.activeActor, decker);
+  assert.equal(run.canFlip(), false, 'the partner is gone — nothing to flip to');
+});
+
+// ---------------------------------------------------------------------------
+// Shell alert hook fires (even off-screen)
+// ---------------------------------------------------------------------------
+
+test('P3.M4.4: the onPartnerDown hook fires with the flatlined partner', () => {
+  const downed: Crew[] = [];
+  const run = dualRun({ onPartnerDown: p => downed.push(p) });
+  jackIn(run);
+  const partner = run.partnerMember!;
+  flatlinePartner(run);
+  assert.deepEqual(downed, [partner]);
+});
+
+// ---------------------------------------------------------------------------
+// Restore never strands control on a dead partner
+// ---------------------------------------------------------------------------
+
+test('P3.M4.4: restoring a jacked-in run whose partner died defaults control to the avatar', () => {
+  const run = dualRun();
+  jackIn(run);
+  const partner = run.partnerMember!;
+  // Reproduce a save written *before* control was repaired (the dead-partner
+  // -stuck save): the partner is dead, but meatActor/activeLayer still point at
+  // it. Kill it without firing the bus so #onPartnerFlatlined does NOT run.
+  partner.damage(partner.hp);
+  assert.equal(run.meatActor, partner);
+  assert.equal(run.activeLayer, 'meat');
+
+  const restored = restore(snapshot(run)).run;
+  assert.equal(restored.partnerDown, true);
+  assert.notEqual(restored.meatActor, restored.partnerMember, 'not driving the corpse');
+  assert.equal(restored.meatActor, restored.player, 'meat control falls back to the body');
+  assert.equal(restored.activeLayer, 'cyber', 'view defaults to Cyberspace');
+  assert.ok(restored.activeActor instanceof CyberAvatar);
+  assert.equal(restored.canFlip(), false, 'no live meat operator to flip to');
+});
+
+// ---------------------------------------------------------------------------
+// Campaign flatlines the partner at job end
+// ---------------------------------------------------------------------------
+
+const act2Campaign = () => new Campaign({ seed: 42, rep: 65, completedJobs: 4 });
+const deckerOf = (c: Campaign) => c.crew.find(m => m.archetype === 'Decker')!;
+const meatOf = (c: Campaign) => c.crew.find(m => m.archetype !== 'Decker')!;
+
+test('P3.M4.4: a partner that died on the field is flatlined at job end even on a clean extract', () => {
+  const campaign = act2Campaign();
+  const decker = deckerOf(campaign);
+  const partner = meatOf(campaign);
+  const run = campaign.deployCrewMember(decker.id, cyberContract(), partner.id);
+  run.enterCombat();
+  jackIn(run);
+  flatlinePartner(run);
+  assert.equal(partner.flatlined, false, 'not flatlined until the job wraps');
+
+  // The Decker extracts clean; the partner still died covering the body.
+  campaign.onJobEnd({ outcome: OUTCOME.EXIT, completed: true });
+  assert.equal(campaign.getCrewMember(partner.id)?.flatlined, true);
+  assert.equal(campaign.deployedPartnerId, null);
+});
+
+test('P3.M4.4: partner-down survives a campaign round-trip and flatlines on the far side', () => {
+  const campaign = act2Campaign();
+  const decker = deckerOf(campaign);
+  const partner = meatOf(campaign);
+  const run = campaign.deployCrewMember(decker.id, cyberContract(), partner.id);
+  run.enterCombat();
+  jackIn(run);
+  flatlinePartner(run);
+
+  const restored = restoreCampaign(structuredClone(snapshotCampaign(campaign)));
+  assert.equal(restored.activeRun!.partnerDown, true, 'the downed partner round-trips');
+  restored.onJobEnd({ outcome: OUTCOME.EXIT, completed: true });
+  assert.equal(restored.getCrewMember(partner.id)?.flatlined, true);
+});

From 5624a38d316b0a126468f5d3d5b3935aaa3d89dc Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Tue, 16 Jun 2026 16:06:54 -0700
Subject: [PATCH 43/55] Simstim PIP and cyber styling

---
 docs/phase-3-plan.md                    |   6 +-
 main.css                                |  24 ++++-
 src/render/AsciiRenderer.ts             |  74 +++++++++----
 src/render/combatHud.ts                 |   1 +
 src/render/pip.ts                       | 118 +++++++++++++++------
 src/shell/combatHudSnapshot.ts          |   1 +
 src/shell/sceneListeners.ts             |  47 ++++++---
 src/shell/shellRuntime.ts               |  34 ++++--
 tests/unit/render/AsciiRenderer.test.ts |  18 ++--
 tests/unit/render/pip.test.ts           | 133 +++++++++++++++++-------
 tests/unit/shell/sceneListeners.test.ts |  61 +++++++++++
 11 files changed, 391 insertions(+), 126 deletions(-)

diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 0d30cac..b60115e 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -44,7 +44,7 @@ A new **player archetype** recruited mid-campaign (late Act 1 / start of Act 2),
 | P3.M1 — Campaign arc structure | ✅ Done |
 | P3.M2 — The Decker archetype | ✅ Done |
 | P3.M3 — Cyberspace grid + ICE | ✅ Done (full ICE roster: Probe, Spark, Guardian) |
-| P3.M4 — Simstim flip (dual-deploy) | 🟡 In progress (M4.1 dual-deploy reservation done) |
+| P3.M4 — Simstim flip (dual-deploy) | 🟡 In progress (M4.1–M4.5 done; M4.6 jack-out remains) |
 | P3.M5 — The Score (climactic mission) | 🔲 Planned |
 | P3.M6 — Chronicle (campaign narrative memory) | 🟡 End-summary foundation shipped |
 
@@ -347,7 +347,7 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 | **P3.M4.2 Jacked body anchor + partner spawn** | ✅ Done (model) | Decker body freezes at port; partner spawns at a safe meat cell; `activeLayer`/`meatActor`/`deckerBody` on `Run` | body frozen+targetable, movement rejected, partner placement, determinism, round-trip |
 | **P3.M4.3 Flip command** | ✅ Done | Tab → free-action flip; `activeView` keys on `activeLayer`; `Run.flip()`/`canFlip()` | flip toggles layer/actor, solo+pre-jack can't flip, meat↔meat post-jack-out, keymap intent |
 | **P3.M4.4 Dual hostile phase** | ✅ Done | Independent AP pools + decoupled turn-end (auto-flip on exhaustion); both hostile phases tick once each with partner+body present; partner death handled | AP-pool/turn-end model; dual-phase verify with partner+body; partner flatline + control repair + alert |
-| **P3.M4.5 PIP** | 🔲 | Inactive layer mini-render + status summary | desktop/mobile layout, no input capture |
+| **P3.M4.5 PIP** | ✅ Done | Inactive layer mini-render + status summary; both layers route flashes to whichever side is in the PIP | inactive-feed resolution, partner→body follow fallback, cyber/RAM chrome, body-hit-in-PIP routing, cyber vs meat palatte styling of both main & PIP canvases |
 | **P3.M4.6 Jack-out** | 🔲 | Voluntary + forced (1-HP) jack-out transitions back to Meatspace | cleanup, objective failure rules, snapshot round-trip |
 
 **P3.M4.4 — dual-phase verify + partner death (2026-06-15):** The M3.6 dual-phase corp turn (chained meat pass → ICE pass on the shared run rng) was only ever tested solo-Decker; re-verified with a partner + frozen body on the meat grid: the meat pass steps neither PLAYER operator, both layers tick regardless of which layer the player is viewing, one AP refresh per round across body + partner + avatar (+ ICE), determinism holds with the partner present (PLAYER faction draws no corp rng), and post-jack-out the meat corp turn runs solo (no ICE pass) with both operators present (`dualPhaseTurn.test.ts`, +5). **Partner death** (the playtest report — partner killed off-screen during the corp turn while the player was in Cyberspace, discovered only via a "no operator to flip to" deny): the meat partner flatlining is *not* run-ending (the Decker fights on), handled in `Run.#onEntityDamaged` → `#onPartnerFlatlined` — it repairs the active-operator state so the player never drives a corpse (if the dead partner was the meat actor, control returns to the Decker `player`; while still jacked in the body is frozen, so the view also force-flips to Cyberspace onto the avatar), and fires a new `onPartnerDown` shell hook that flashes an **unconditional** "⚠ OPERATOR DOWN" alert (the kill is invisible from the grid view). `Run.partnerDown` (partner fielded + not alive) drives `Campaign.onJobEnd`, which flatlines `deployedPartnerId` for good — independent of the Decker's outcome (extracted clean or died), and across a campaign round-trip. Tests: `partnerDeath.test.ts` (8). Closes the partner-death follow-up that M4.2 deferred. **Restore companion fix (playtest, dead-partner-stuck save):** `#onPartnerFlatlined` repairs control at the *moment* of death, but `restore()` still set `meatActor = gridPartner` unconditionally — so a save with a jacked-in run + dead partner (or any pre-fix save) reconstructed the stuck state (driving a corpse in Meatspace, `canFlip` false). Restore now mirrors the live repair: a dead grid partner is never the meat operator — `meatActor` falls back to the (frozen) body and the view defaults to Cyberspace onto the avatar; a living partner restores normally honoring the saved view.
@@ -362,6 +362,8 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 
 **P3.M4.1 implementation note (2026-06-15):** A Cyberspace dual-deploy reserves a meat partner without spawning it. `Run.partnerMember: Crew | null` (validated non-Decker, living, distinct from the deployed operator) is set at construction; `Run.enterBriefing` forbids a partner on a non-cyber contract but does **not** require one (a solo Decker cyber run stays legal — the dual-deploy product rule is enforced by the briefing UI, not the model). `Campaign.deployCrewMember(memberId, contract, partnerId?)` gains the optional partner, records `Campaign.deployedPartnerId`, commits both operators (both clear job-scoped salvage at `onJobEnd`), and gates the partner (cyber-only, living, non-Decker, distinct, known id). `<run-briefing>` inverts its P3.M3.1 gate: on a cyber contract the Decker row is locked as `CYBER OP` and the player selects the living meat partner (Decker auto-attaches via the emitted `partnerId`); with no eligible partner it falls back to the solo `NEEDS DECKER` gate. Persistence: the reserved partner round-trips as an off-grid entity record (`RunSnapshot.partner`, throwaway `(0,0)` cell) for standalone restore, and re-binds to the canonical crew object via `partnerMemberId` on the campaign path (BRIEFING and COMBAT/RESULT). A partner record without a Cyberspace contract throws on restore. **Follow-up:** partner-death flatline accounting lands with M4.2 (the partner isn't on the field until jack-in); a fully crew-depleted player still cannot field a partner for THE SCORE — revisit if that edge proves too punishing.
 
+**P3.M4.5 implementation note (2026-06-15):** The M3.7 PIP (always the meatspace body CCTV) now renders the **inactive** layer after the simstim flip — the layer the player is *not* driving. `pip.ts` is the pure seam: `pipFeedFor` resolves `'meat'` when viewing cyber and `'cyber'` when viewing meat (absent `activeLayer` defaults to the meat feed, preserving solo/legacy behaviour); `pipWorldOf`/`pipFollowTargetOf`/`pipChrome`/`shouldShowPip` all key off the feed. The meat feed follows the **living partner**, falling back to the Decker's frozen **body** once the partner flatlines (or on a solo Decker run) — chrome labels `PARTNER`/`BODY` accordingly; the cyber feed follows the avatar and reads `// THE GRID //` + `RAM` over a magenta-tinted (`.pip-cyber`) border, with cyber fog (`cyberVision`) and no principal palette. `pointer-events: none` keeps the overlay read-only. **Flash routing fix:** M3.7 routed body-hit feedback to the PIP whenever `isJackedIn`; that was only correct while viewing cyber. `sceneListeners` now routes by *which layer is in the PIP* — meat events (body/partner damage, muzzle, ranged noise) flash the PIP iff `isCyberView` (meat is the inactive feed) and the main canvas otherwise; cyber events symmetrically flash the PIP when viewing meat, including a new `RAM HIT`/`RAM WIPED` pulse so off-screen ICE damage is visible. Tests: `pip.test.ts` rewritten for the inactive-feed resolution + partner/body fallback + cyber chrome (11), and a `sceneListeners.test.ts` case locks the body-hit-routes-to-PIP-only-while-viewing-cyber predicate. **Follow-up:** still no touch-pad flip button (keyboard-only, from M4.3); the end-to-end PIP swap wants a live in-campaign playtest once a dual-deploy cyber contract is reachable (no DOM harness for the render path).
+
 **Acceptance:**
 
 - Dual-deploy: two operators on two grids, each controllable.
diff --git a/main.css b/main.css
index 5306cb2..326c91d 100644
--- a/main.css
+++ b/main.css
@@ -291,11 +291,21 @@ main {
   position: relative;
   flex: 1 1 80%;
   min-width: 0;
-  border-radius: 1rem 0.5rem 0.5rem 2rem;
-  corner-shape: bevel;
+
+  & > #game-canvas {
+    border-radius: 1rem 0.5rem 0.5rem 2rem;
+    corner-shape: bevel;
+
+    &.cyber {
+      border-color: rgba(255, 92, 198, 0.5);
+      box-shadow: 0 0 12px rgba(255, 92, 198, 0.18);
+    }
+  }
 }
 
-/* P3.M3.7: meatspace CCTV while jacked in — anchored to the main canvas, not the stage. */
+/* P3.M3.7 / P3.M4.5: PIP of the inactive layer while jacked in — meat CCTV by
+   default, cyber-tinted (`.pip-cyber`) when the grid is the inactive feed.
+   Anchored to the main canvas, not the stage. */
 .game-canvas-wrap > #pip-canvas {
   position: absolute;
   right: 0.35rem;
@@ -303,13 +313,19 @@ main {
   z-index: 2;
   pointer-events: none;
   border: 1px solid rgba(0, 217, 165, 0.45);
-  border-radius: 0.35rem 0.75rem 0.35rem 0.35rem;
+  border-radius: 0.35rem 0.35rem 0.35rem 0.75rem;
   corner-shape: bevel;
   box-shadow: 0 0 12px rgba(0, 217, 165, 0.15);
   opacity: 0.92;
   image-rendering: pixelated;
 }
 
+/* Cyber feed (viewing meat) — magenta to match `// GRID //`. */
+.game-canvas-wrap > #pip-canvas.pip-cyber {
+  border-color: rgba(255, 92, 198, 0.5);
+  box-shadow: 0 0 12px rgba(255, 92, 198, 0.18);
+}
+
 .game-canvas-wrap > #pip-canvas[hidden] {
   display: none;
 }
diff --git a/src/render/AsciiRenderer.ts b/src/render/AsciiRenderer.ts
index a9cb626..dc4bbdf 100644
--- a/src/render/AsciiRenderer.ts
+++ b/src/render/AsciiRenderer.ts
@@ -97,16 +97,26 @@ const HUD_GLOW = '#6ae8c8';
 const TRUNCATION_MARK = '...';
 const HUD_OBJECTIVE_DONE = '#7dff9d';
 const HUD_OBJECTIVE_TODO = '#ff7a66';
-const HUD_IDENTITY = '#6ae8c8';
-const HUD_HP_EMPTY = '#2a4a42';
-const HUD_HP_FILLED = '#6ae8c8';
-const HUD_AP_SPENT = '#ff7a66';
-const HUD_AP_AVAILABLE = '#6ae8c8';
+const HUD_HP_EMPTY = HUD_GLOW;
+const HUD_HP_FILLED = HUD_GLOW;
+const HUD_AP_SPENT = HUD_GLOW;
+const HUD_AP_AVAILABLE = HUD_GLOW;
 const HUD_TURN_PLAYER = '#b8f5e2';
 const HUD_TURN_CORP = '#ff7a66';
 /** Reserve top-right chrome so the objective row does not sit under identity/vitals. */
 const OBJECTIVE_RIGHT_GUTTER = 200;
 
+const HUD_MEAT_PALETTE = Object.freeze({
+  color: '#9ff3da',
+  glowColor: '#6ae8c8',
+  accentColor: 'rgba(0, 217, 165, 0.5)',
+});
+const HUD_CYBER_PALETTE = Object.freeze({
+  color: '#ff8ad8',
+  glowColor: '#ff5cc6',
+  accentColor: 'rgba(255, 92, 198, 0.5)',
+});
+
 export class AsciiRenderer {
   canvas: HTMLCanvasElement;
   ctx: CanvasRenderingContext2D | null;
@@ -180,7 +190,7 @@ export class AsciiRenderer {
     this.lastCamera = camera;
     this.#paintActiveFlashes();
     // Painted last so persistent chrome is never occluded by glyphs/flashes.
-    this.#drawLocationLabel(locationLabel);
+    this.#drawLocationLabel(locationLabel, combatHud?.cyber ?? false);
     this.#drawCombatHud(combatHud);
     this.#drawHudRows(hudRows);
   }
@@ -256,9 +266,15 @@ export class AsciiRenderer {
    * keeps it legible over map glyphs; a thin accent underline ties it to the
    * terminal aesthetic. No-op when no label is supplied.
    */
-  #drawLocationLabel(label?: string) {
+  #drawLocationLabel(label?: string, cyber?: boolean) {
     if (!label) return;
-    this.#drawHudRow({ text: label, anchor: 'top-left', uppercase: true });
+    const palette = cyber ? HUD_CYBER_PALETTE : HUD_MEAT_PALETTE;
+    this.#drawHudRow({
+      text: label,
+      anchor: 'top-left',
+      uppercase: true,
+      ...palette,
+    });
   }
 
   #drawHudRows(rows?: readonly HudRow[]) {
@@ -271,6 +287,7 @@ export class AsciiRenderer {
   #drawCombatHud(hud?: CombatHudSummaryInput | null) {
     if (!hud) return;
     const objective = formatObjectiveHud(hud.objective);
+    const palette = hud.cyber ? HUD_CYBER_PALETTE : HUD_MEAT_PALETTE;
     if (objective) {
       this.#drawHudRow({
         text: objective,
@@ -280,28 +297,30 @@ export class AsciiRenderer {
         glowColor: hud.objective?.done ? HUD_OBJECTIVE_DONE : HUD_OBJECTIVE_TODO,
         maxWidth: Math.max(0, this.canvas.width - OBJECTIVE_RIGHT_GUTTER),
         preserveObjectiveTags: true,
+        accentColor: palette.accentColor,
       });
     }
     this.#drawHudRow({
       text: formatIdentityHud(hud.identity),
       anchor: 'top-right',
       row: 0,
-      color: HUD_IDENTITY,
-      glowColor: HUD_IDENTITY,
+      ...palette,
     });
     const hpText = formatHpSegments(hud.hp);
     this.#drawHudRow({
       text: hpText,
       anchor: 'top-right',
       row: 1,
-      segments: hpSegments(hpText),
+      segments: hpSegments(hpText, palette),
+      ...palette,
     });
     const apText = formatApPips(hud.ap);
     this.#drawHudRow({
       text: apText,
       anchor: 'top-right',
       row: 2,
-      segments: apSegments(apText),
+      segments: apSegments(apText, palette),
+      ...palette,
     });
     const turnLabel = formatTurnLabel(hud.turn);
     const isCorpTurn = hud.turn.currentFaction !== FACTION.PLAYER;
@@ -372,7 +391,8 @@ export class AsciiRenderer {
     text: string,
     boxX: number,
     boxW: number,
-    boxY: number
+    boxY: number,
+    accentColor?: string
   ) {
     const ctx = this.ctx;
     if (!ctx) return;
@@ -440,37 +460,45 @@ export class AsciiRenderer {
   }
 }
 
-function hpSegments(text: string): HudTextSegment[] {
+function hpSegments(
+  text: string,
+  palette?: { color: string; glowColor: string }
+): HudTextSegment[] {
+  const { color, glowColor } = palette ?? { color: HUD_TEXT, glowColor: HUD_GLOW };
   const prefix = 'HP ';
   const glyphs = text.startsWith(prefix) ? text.slice(prefix.length) : text;
   const segments: HudTextSegment[] = text.startsWith(prefix)
-    ? [{ text: prefix, color: HUD_TEXT, glowColor: HUD_GLOW }]
+    ? [{ text: prefix, color, glowColor }]
     : [];
   for (const char of glyphs) {
     if (char === COMBAT_HUD_GLYPHS.HP_EMPTY) {
-      segments.push({ text: char, color: HUD_HP_EMPTY });
+      segments.push({ text: char, color: glowColor ?? HUD_HP_EMPTY });
     } else if (char === COMBAT_HUD_GLYPHS.HP_FILLED) {
-      segments.push({ text: char, color: HUD_HP_FILLED });
+      segments.push({ text: char, color: glowColor ?? HUD_HP_FILLED });
     } else {
-      segments.push({ text: char, color: HUD_TEXT, glowColor: HUD_GLOW });
+      segments.push({ text: char, color, glowColor });
     }
   }
   return segments;
 }
 
-function apSegments(text: string): HudTextSegment[] {
+function apSegments(
+  text: string,
+  palette?: { color: string; glowColor: string }
+): HudTextSegment[] {
   const prefix = 'AP ';
   const glyphs = text.startsWith(prefix) ? text.slice(prefix.length) : text;
+  const { color, glowColor } = palette ?? { color: HUD_TEXT, glowColor: HUD_GLOW };
   const segments: HudTextSegment[] = text.startsWith(prefix)
-    ? [{ text: prefix, color: HUD_TEXT, glowColor: HUD_GLOW }]
+    ? [{ text: prefix, color, glowColor }]
     : [];
   for (const char of glyphs) {
     if (char === COMBAT_HUD_GLYPHS.AP_SPENT) {
-      segments.push({ text: char, color: HUD_AP_SPENT });
+      segments.push({ text: char, color: glowColor ?? HUD_AP_SPENT });
     } else if (char === COMBAT_HUD_GLYPHS.AP_AVAILABLE) {
-      segments.push({ text: char, color: HUD_AP_AVAILABLE });
+      segments.push({ text: char, color: glowColor ?? HUD_AP_AVAILABLE });
     } else {
-      segments.push({ text: char, color: HUD_TEXT, glowColor: HUD_GLOW });
+      segments.push({ text: char, color, glowColor });
     }
   }
   return segments;
diff --git a/src/render/combatHud.ts b/src/render/combatHud.ts
index 2429893..7615347 100644
--- a/src/render/combatHud.ts
+++ b/src/render/combatHud.ts
@@ -45,6 +45,7 @@ export type CombatHudSummaryInput = Readonly<{
   hp: CombatHudVitalInput;
   ap: CombatHudApInput;
   turn: CombatHudTurnInput;
+  cyber: boolean;
 }>;
 
 export function formatObjectiveHud(objective: CombatHudObjectiveInput | null | undefined): string {
diff --git a/src/render/pip.ts b/src/render/pip.ts
index 6eb08df..73c43c9 100644
--- a/src/render/pip.ts
+++ b/src/render/pip.ts
@@ -1,19 +1,28 @@
 /**
- * P3.M3.7 — Jacked-in body CCTV (PIP) helpers.
+ * P3.M3.7 / P3.M4.5 — simstim PIP (picture-in-picture of the *inactive* layer).
  *
- * Pure presentation seam: the shell paints meatspace in a small overlay while
- * the Decker is on the grid. M4 will swap `pipFollowTargetOf` / `pipWorldOf`
- * to track whichever layer is *inactive* after the simstim flip.
+ * While the Decker is jacked in, the shell paints the layer the player is **not**
+ * currently driving into a small read-only overlay:
+ *   - viewing Cyberspace  → PIP shows Meatspace (the body/partner CCTV feed)
+ *   - viewing Meatspace    → PIP shows Cyberspace (the avatar on the grid)
+ *
+ * M3.7 shipped the meat-only feed; M4.5 generalizes it to whichever layer is
+ * inactive after the flip. The feed follows the inactive *operator* — the meat
+ * partner while they're alive, falling back to the Decker's frozen body once the
+ * partner flatlines (or on a solo Decker run), and the cyber avatar on the grid.
  */
 import { formatHpSegments } from './combatHud.js';
 import { cameraFor, type Camera, type Viewport } from './frame.js';
 import type { Entity } from '../game/Entity.js';
 import type { World } from '../game/World.js';
+import type { Crew } from '../game/Crew.js';
 
 /** Matches `#pip-canvas` pixel size at `PIP_CELL_SIZE` (160×100). */
 export const PIP_VIEWPORT_TILES = Object.freeze({ width: 16, height: 10 });
 export const PIP_CELL_SIZE = 10;
 
+export type PipFeed = 'meat' | 'cyber';
+
 export type PipHudRow = {
   text: string;
   anchor: 'top-left' | 'top-right';
@@ -28,22 +37,54 @@ export type PipHudRow = {
 export type PipCyberspacePhase = 'dormant' | 'active' | 'resolved';
 
 export type PipRunView = {
-  cyberspace?: { phase: PipCyberspacePhase } | null;
+  cyberspace?: { phase: PipCyberspacePhase; layer?: { world: World; avatar: Entity } } | null;
   world?: World | null;
+  /** Decker body while jacked in (`Run.player`). */
   player?: Entity | null;
+  /** Reserved/fielded meat partner on a dual-deploy (`Run.partnerMember`). */
+  partnerMember?: Entity | null;
+  /** Which layer holds input — `'cyber'` only while flipped to the grid. */
+  activeLayer?: PipFeed;
 };
 
-export function shouldShowPip(run: PipRunView | null | undefined): boolean {
-  return run?.cyberspace?.phase === 'active' && run.world != null && run.player != null;
+/**
+ * The layer the PIP should render — the one the player is *not* driving — or
+ * null when there is no second layer (no active jack-in). The active view is
+ * `activeLayer`; absent (legacy / solo) it defaults to `'cyber'`, so the PIP
+ * shows the meat body feed exactly as in M3.7.
+ */
+export function pipFeedFor(run: PipRunView | null | undefined): PipFeed | null {
+  if (run?.cyberspace?.phase !== 'active') return null;
+  return (run.activeLayer ?? 'cyber') === 'cyber' ? 'meat' : 'cyber';
+}
+
+/**
+ * The Meatspace operator the CCTV feed follows: the living partner if there is
+ * one, otherwise the Decker's frozen body. Resolution order is deliberate — once
+ * the partner flatlines the camera falls back to the body the corp is chewing on.
+ */
+export function pipMeatFollow(run: PipRunView | null | undefined): Entity | null {
+  const partner = run?.partnerMember;
+  if (partner && partner.alive) return partner;
+  return run?.player ?? null;
 }
 
-/** Inactive layer world while jacked in — meat body feed until M4 flip. */
 export function pipWorldOf(run: PipRunView | null | undefined): World | null {
-  return shouldShowPip(run) ? (run!.world ?? null) : null;
+  const feed = pipFeedFor(run);
+  if (feed === 'meat') return run!.world ?? null;
+  if (feed === 'cyber') return run!.cyberspace?.layer?.world ?? null;
+  return null;
+}
+
+export function pipFollowTargetOf(run: PipRunView | null | undefined): Entity | Crew | null {
+  const feed = pipFeedFor(run);
+  if (feed === 'meat') return pipMeatFollow(run);
+  if (feed === 'cyber') return run!.cyberspace?.layer?.avatar ?? null;
+  return null;
 }
 
-export function pipFollowTargetOf(run: PipRunView | null | undefined): Entity | null {
-  return shouldShowPip(run) ? (run!.player ?? null) : null;
+export function shouldShowPip(run: PipRunView | null | undefined): boolean {
+  return pipWorldOf(run) != null && pipFollowTargetOf(run) != null;
 }
 
 export function pipViewport(): Viewport {
@@ -51,15 +92,15 @@ export function pipViewport(): Viewport {
 }
 
 /**
- * Center on the body, then clamp so the viewport stays inside the grid when
- * the jack-in terminal is near a map edge.
+ * Center on the followed operator, then clamp so the viewport stays inside the
+ * grid when they stand near a map edge.
  */
 export function pipCameraFor(
-  body: Entity,
+  follow: Entity,
   world: World,
   viewport: Viewport = pipViewport()
 ): Camera {
-  const camera = cameraFor(body, viewport);
+  const camera = cameraFor(follow, viewport);
   const maxX = Math.max(0, world.grid.width - viewport.width);
   const maxY = Math.max(0, world.grid.height - viewport.height);
   return {
@@ -69,23 +110,42 @@ export function pipCameraFor(
   };
 }
 
-export function pipChrome(body: Entity): PipHudRow[] {
-  const hpText = formatHpSegments({ hp: body.hp, maxHp: body.maxHp, label: 'BODY' });
+const MEAT_ACCENT = Object.freeze({
+  color: '#9ff3da',
+  glowColor: '#6ae8c8',
+  accentColor: 'rgba(0, 217, 165, 0.5)',
+});
+const CYBER_ACCENT = Object.freeze({
+  color: '#ff8ad8',
+  glowColor: '#ff5cc6',
+  accentColor: 'rgba(255, 92, 198, 0.5)',
+});
+
+/** Feed chrome: label + vitals for the inactive operator the PIP is following. */
+export function pipChrome(run: PipRunView | null | undefined): PipHudRow[] {
+  const feed = pipFeedFor(run);
+  const follow = pipFollowTargetOf(run);
+  if (!feed || !follow) return [];
+  if (feed === 'cyber') {
+    return [
+      { text: '// GRID //', anchor: 'top-left', row: 0, uppercase: true, ...CYBER_ACCENT },
+      {
+        text: formatHpSegments({ hp: follow.hp, maxHp: follow.maxHp, label: 'RAM' }),
+        anchor: 'top-right',
+        row: 3,
+        ...CYBER_ACCENT,
+      },
+    ];
+  }
+  // Meat CCTV feed: BODY when following the frozen Decker, PARTNER otherwise.
+  const label = follow === run?.player ? 'BODY' : `${(follow as Crew)?.callsign ?? 'PARTNER'}`;
   return [
+    { text: '// CCTV //', anchor: 'top-left', row: 0, uppercase: true, ...MEAT_ACCENT },
     {
-      text: '// CCTV //',
-      anchor: 'top-left',
-      uppercase: true,
-      color: '#9ff3da',
-      glowColor: '#6ae8c8',
-      accentColor: 'rgba(0, 217, 165, 0.5)',
-    },
-    {
-      text: hpText,
+      text: formatHpSegments({ hp: follow.hp, maxHp: follow.maxHp, label }),
       anchor: 'top-right',
-      color: '#6ae8c8',
-      glowColor: '#6ae8c8',
-      accentColor: 'rgba(0, 217, 165, 0.5)',
+      row: 3,
+      ...MEAT_ACCENT,
     },
   ];
 }
diff --git a/src/shell/combatHudSnapshot.ts b/src/shell/combatHudSnapshot.ts
index 50e14b6..92fc285 100644
--- a/src/shell/combatHudSnapshot.ts
+++ b/src/shell/combatHudSnapshot.ts
@@ -30,6 +30,7 @@ export function buildCombatHudSnapshot(scene: ShellScene | null): CombatHudSumma
       currentFaction: scene.queue.currentFaction,
       turnNumber: scene.queue.turnNumber,
     },
+    cyber: isCyberView(scene),
   };
 }
 
diff --git a/src/shell/sceneListeners.ts b/src/shell/sceneListeners.ts
index e860d18..c54fbad 100644
--- a/src/shell/sceneListeners.ts
+++ b/src/shell/sceneListeners.ts
@@ -7,7 +7,7 @@ import {
   triggerDamageFlash,
   triggerShake,
 } from '../render/animations.js';
-import { cyberLayerOf, isJackedIn } from './activeView.js';
+import { cyberLayerOf, isCyberView } from './activeView.js';
 import type {
   DoorUnlockPayload,
   EntityDamagedPayload,
@@ -71,12 +71,14 @@ export class SceneListenerController {
           killed,
           source,
         } = (payload ?? {}) as EntityDamagedPayload;
-        const jacked = isJackedIn(run);
+        // P3.M4.5: the meat layer is in the PIP only while the player is
+        // *viewing* Cyberspace; once flipped back to meat it is the main canvas.
+        const meatInPip = isCyberView(run);
         if (run?.player && target === run.player && damage > 0) {
           triggerShake(dom.stageEl);
           triggerDamageFlash(dom.stageEl);
           animLock.push(ANIMATION_DURATIONS.DAMAGE_FLASH);
-          if (jacked) {
+          if (meatInPip) {
             const attackerLabel = attacker
               ? resolveEntityLabel(attacker.id, run.world!.entities)
               : 'unknown';
@@ -92,13 +94,10 @@ export class SceneListenerController {
           }
         }
         if (source === 'melee' && target && damage > 0) {
-          if (jacked && target === run.player) {
-            const fired = runMuzzleFlash(renderers.pip, effects.paintPip, target.x, target.y);
-            if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
-          } else if (!jacked) {
-            const fired = runMuzzleFlash(renderers.main, effects.paint, target.x, target.y);
-            if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
-          }
+          const flashRenderer = meatInPip ? renderers.pip : renderers.main;
+          const repaint = meatInPip ? effects.paintPip : effects.paint;
+          const fired = runMuzzleFlash(flashRenderer, repaint, target.x, target.y);
+          if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
         }
         if (killed && target) {
           this.#deps.memoriseMeatCorpse(target, (x, y) => meatVision.isVisible(x, y));
@@ -109,9 +108,9 @@ export class SceneListenerController {
         if (noise.kind !== 'ranged') return;
         const origin = noise.origin;
         if (!origin) return;
-        const jacked = isJackedIn(run);
-        const flashRenderer = jacked ? renderers.pip : renderers.main;
-        const repaint = jacked ? effects.paintPip : effects.paint;
+        const meatInPip = isCyberView(run);
+        const flashRenderer = meatInPip ? renderers.pip : renderers.main;
+        const repaint = meatInPip ? effects.paintPip : effects.paint;
         const fired = runMuzzleFlash(flashRenderer, repaint, origin.x, origin.y);
         if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
       }),
@@ -137,13 +136,28 @@ export class SceneListenerController {
       layer.bus.on(EVENT.ENTITY_MOVED, () => effects.recomputeVision()),
       layer.bus.on(EVENT.ENTITY_DAMAGED, payload => {
         const { target, damage = 0, killed, source } = (payload ?? {}) as EntityDamagedPayload;
+        // P3.M4.5: the cyber grid is in the PIP while the player is viewing meat.
+        const cyberInPip = !isCyberView(run);
+        const flashRenderer = cyberInPip ? renderers.pip : renderers.main;
+        const repaint = cyberInPip ? effects.paintPip : effects.paint;
         if (target === layer.avatar && damage > 0) {
           triggerShake(dom.stageEl);
           triggerDamageFlash(dom.stageEl);
           animLock.push(ANIMATION_DURATIONS.DAMAGE_FLASH);
+          if (cyberInPip) {
+            effects.flash(
+              killed
+                ? 'RAM WIPED — ICE flatlined your avatar on the grid.'
+                : `RAM HIT — ICE burned ${damage} (cyberspace).`
+            );
+            dom.pipCanvas.classList.remove('pip-hit');
+            void dom.pipCanvas.offsetWidth;
+            dom.pipCanvas.classList.add('pip-hit');
+            effects.paintPip();
+          }
         }
         if (source === 'melee' && target && damage > 0) {
-          const fired = runMuzzleFlash(renderers.main, effects.paint, target.x, target.y);
+          const fired = runMuzzleFlash(flashRenderer, repaint, target.x, target.y);
           if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
         }
         if (killed && target) {
@@ -155,7 +169,10 @@ export class SceneListenerController {
         if (noise.kind !== 'ranged') return;
         const origin = noise.origin;
         if (!origin) return;
-        const fired = runMuzzleFlash(renderers.main, effects.paint, origin.x, origin.y);
+        const cyberInPip = !isCyberView(run);
+        const flashRenderer = cyberInPip ? renderers.pip : renderers.main;
+        const repaint = cyberInPip ? effects.paintPip : effects.paint;
+        const fired = runMuzzleFlash(flashRenderer, repaint, origin.x, origin.y);
         if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
       })
     );
diff --git a/src/shell/shellRuntime.ts b/src/shell/shellRuntime.ts
index e5c754b..c430735 100644
--- a/src/shell/shellRuntime.ts
+++ b/src/shell/shellRuntime.ts
@@ -72,7 +72,14 @@ import type { RunResult, RunTelemetry, Outcome } from '/src/game/Run.js';
 import type { Item } from '/src/game/items.js';
 import type { Intent } from '/src/input/applyIntent.js';
 import type { AimKind } from '/src/input/keymap.js';
-import { pipCameraFor, pipChrome, shouldShowPip } from '/src/render/pip.js';
+import {
+  pipCameraFor,
+  pipChrome,
+  pipFeedFor,
+  pipFollowTargetOf,
+  pipWorldOf,
+  shouldShowPip,
+} from '/src/render/pip.js';
 import type { TurnActionStep } from '/src/types.js';
 import { installErrorBoundary, type FaultSignal } from '/src/errorBoundary.js';
 import { isDevelopmentMode } from '/src/domUtils.js';
@@ -2168,19 +2175,25 @@ function paintPip(): void {
     return;
   }
   const run = view.scene;
-  if (!run.world || !run.player) {
+  // P3.M4.5: the PIP shows whichever layer the player is *not* driving — meat
+  // (body/partner CCTV) while viewing the grid, the cyber grid while viewing meat.
+  const feed = pipFeedFor(run);
+  const world = pipWorldOf(run);
+  const follow = pipFollowTargetOf(run);
+  if (!feed || !world || !follow) {
     pipCanvas.hidden = true;
     return;
   }
   pipCanvas.hidden = false;
-  const principalId = campaign?.activeRun?.contract?.context?.principal?.id;
-  pipRenderer.draw(run.world, run.player, {
-    camera: pipCameraFor(run.player, run.world),
-    vision,
-    player: run.player,
-    tileset: 'meat',
-    principalId,
-    hudRows: pipChrome(run.player),
+  const cyberFeed = feed === 'cyber';
+  pipCanvas.classList.toggle('pip-cyber', cyberFeed);
+  pipRenderer.draw(world, follow, {
+    camera: pipCameraFor(follow, world),
+    vision: cyberFeed ? cyberVision : vision,
+    player: follow,
+    tileset: cyberFeed ? 'cyber' : 'meat',
+    principalId: cyberFeed ? undefined : campaign?.activeRun?.contract?.context?.principal?.id,
+    hudRows: pipChrome(run),
   });
 }
 
@@ -2196,6 +2209,7 @@ export function paint(stateHint: InputState = activeInputState()): void {
   const actor = activeActorOf(run);
   if (!world || !actor) return;
   const jacked = isCyberView(run);
+  canvas.classList.toggle('cyber', jacked);
   // Hub is a safe space — no fog of war. Vision is only meaningful during
   // combat where LOS and drone stealth detection matter.
   const activeVision = run.state === RUN_STATE.COMBAT ? activeVisionField(run) : undefined;
diff --git a/tests/unit/render/AsciiRenderer.test.ts b/tests/unit/render/AsciiRenderer.test.ts
index 31e93f5..ce4d553 100644
--- a/tests/unit/render/AsciiRenderer.test.ts
+++ b/tests/unit/render/AsciiRenderer.test.ts
@@ -266,6 +266,8 @@ test('draw() paints combat HUD HP and AP glyphs with per-state colors', () => {
   const canvas = makeCanvas();
   const r = new AsciiRenderer(canvas, { now: () => 0 });
   const { world, player } = makeWorld();
+  const GLOW_COLOR = '#6ae8c8';
+  const CORP_COLOR = '#ff7a66';
 
   r.draw(world, player, {
     combatHud: {
@@ -282,9 +284,9 @@ test('draw() paints combat HUD HP and AP glyphs with per-state colors', () => {
   assert.deepEqual(
     hpGlyphs.map(c => [c.char, c.fillStyle]),
     [
-      ['□', '#2a4a42'],
-      ['□', '#2a4a42'],
-      ['■', '#6ae8c8'],
+      ['□', GLOW_COLOR],
+      ['□', GLOW_COLOR],
+      ['■', GLOW_COLOR],
     ]
   );
 
@@ -292,15 +294,15 @@ test('draw() paints combat HUD HP and AP glyphs with per-state colors', () => {
   assert.deepEqual(
     apGlyphs.map(c => [c.char, c.fillStyle]),
     [
-      ['○', '#ff7a66'],
-      ['○', '#ff7a66'],
-      ['●', '#6ae8c8'],
-      ['●', '#6ae8c8'],
+      ['○', GLOW_COLOR],
+      ['○', GLOW_COLOR],
+      ['●', GLOW_COLOR],
+      ['●', GLOW_COLOR],
     ]
   );
 
   const corpTurn = textOps.find(c => c.char === 'HOSTILES ACTIVE');
-  assert.equal(corpTurn?.fillStyle, '#ff7a66');
+  assert.equal(corpTurn?.fillStyle, CORP_COLOR);
 });
 
 test('draw() omits combat HUD rows when combatHud is null', () => {
diff --git a/tests/unit/render/pip.test.ts b/tests/unit/render/pip.test.ts
index 802f55c..de26494 100644
--- a/tests/unit/render/pip.test.ts
+++ b/tests/unit/render/pip.test.ts
@@ -8,6 +8,8 @@ import { FACTION } from '../../../src/game/constants.js';
 import {
   pipCameraFor,
   pipChrome,
+  pipFeedFor,
+  pipMeatFollow,
   pipViewport,
   pipWorldOf,
   pipFollowTargetOf,
@@ -15,68 +17,129 @@ import {
   PIP_VIEWPORT_TILES,
 } from '../../../src/render/pip.js';
 
-function makeBody(x: number, y: number, hp = 5, maxHp = 8) {
+function makeEntity(id: string, x: number, y: number, hp = 5, maxHp = 8) {
   const grid = new Grid(28, 18);
   const world = new World(grid);
-  const body = new Entity({
-    id: 'body',
-    x,
-    y,
+  const ent = new Entity({ id, x, y, faction: FACTION.PLAYER, glyph: '@', maxHp, hp });
+  world.addEntity(ent);
+  return { world, ent };
+}
+
+/** A dual-deploy run viewing Cyberspace: PIP should show the meat feed. */
+function viewingCyber() {
+  const { world: meatWorld, ent: body } = makeEntity('body', 5, 6);
+  const { world: cyberWorld, ent: avatar } = makeEntity('avatar', 10, 4, 6, 6);
+  const partner = new Entity({
+    id: 'partner',
+    x: 7,
+    y: 8,
     faction: FACTION.PLAYER,
-    glyph: '@',
-    maxHp,
-    hp,
+    glyph: 'R',
+    maxHp: 6,
+    hp: 6,
   });
-  world.addEntity(body);
-  return { world, body };
+  meatWorld.addEntity(partner);
+  return {
+    cyberspace: { phase: 'active' as const, layer: { world: cyberWorld, avatar } },
+    world: meatWorld,
+    player: body,
+    partnerMember: partner,
+    activeLayer: 'cyber' as const,
+    body,
+    avatar,
+    partner,
+  };
 }
 
-test('shouldShowPip is true only while cyberspace is active with world and player', () => {
-  const run = {
-    cyberspace: { phase: 'active' as const },
-    world: {},
-    player: {},
-  };
+test('pipFeedFor renders the inactive layer (opposite of the active view)', () => {
+  const run = viewingCyber();
+  assert.equal(pipFeedFor(run), 'meat');
+  assert.equal(pipFeedFor({ ...run, activeLayer: 'meat' }), 'cyber');
+  // Solo / legacy (no activeLayer) defaults to the meat feed, as in M3.7.
+  assert.equal(pipFeedFor({ ...run, activeLayer: undefined }), 'meat');
+  assert.equal(pipFeedFor({ ...run, cyberspace: { phase: 'dormant' } }), null);
+  assert.equal(pipFeedFor(null), null);
+});
+
+test('shouldShowPip requires the inactive layer to have a world and operator', () => {
+  const run = viewingCyber();
   assert.equal(shouldShowPip(run), true);
+  assert.equal(shouldShowPip({ ...run, activeLayer: 'meat' }), true);
   assert.equal(shouldShowPip({ ...run, cyberspace: { phase: 'dormant' } }), false);
-  assert.equal(shouldShowPip({ ...run, cyberspace: { phase: 'resolved' } }), false);
   assert.equal(shouldShowPip({ ...run, world: null }), false);
   assert.equal(shouldShowPip(null), false);
 });
 
-test('pipWorldOf and pipFollowTargetOf gate on shouldShowPip', () => {
-  const { world, body } = makeBody(5, 6);
-  const active = { cyberspace: { phase: 'active' as const }, world, player: body };
-  assert.equal(pipWorldOf(active), world);
-  assert.equal(pipFollowTargetOf(active), body);
-  assert.equal(pipWorldOf({ cyberspace: { phase: 'dormant' }, world, player: body }), null);
+test('viewing cyber: PIP follows the meat feed (living partner over the body)', () => {
+  const run = viewingCyber();
+  assert.equal(pipWorldOf(run), run.world);
+  assert.equal(pipFollowTargetOf(run), run.partner);
+});
+
+test('viewing cyber: PIP falls back to the Decker body once the partner flatlines', () => {
+  const run = viewingCyber();
+  run.partner.alive = false;
+  assert.equal(pipMeatFollow(run), run.body);
+  assert.equal(pipFollowTargetOf(run), run.body);
+});
+
+test('solo Decker (no partner): meat feed follows the body', () => {
+  const run = viewingCyber();
+  const solo = { ...run, partnerMember: null };
+  assert.equal(pipFollowTargetOf(solo), solo.body);
+});
+
+test('viewing meat: PIP shows the cyber grid and follows the avatar', () => {
+  const run = { ...viewingCyber(), activeLayer: 'meat' as const };
+  assert.equal(pipWorldOf(run), run.cyberspace.layer.world);
+  assert.equal(pipFollowTargetOf(run), run.avatar);
 });
 
 test('pipViewport matches pip canvas tile footprint', () => {
   assert.deepEqual(pipViewport(), PIP_VIEWPORT_TILES);
 });
 
-test('pipCameraFor centers on the body', () => {
-  const { world, body } = makeBody(14, 9);
-  const camera = pipCameraFor(body, world);
+test('pipCameraFor centers on the followed operator', () => {
+  const { world, ent } = makeEntity('body', 14, 9);
+  const camera = pipCameraFor(ent, world);
   assert.equal(camera.width, 16);
   assert.equal(camera.height, 10);
-  assert.equal(camera.x, body.x - Math.floor(16 / 2));
-  assert.equal(camera.y, body.y - Math.floor(10 / 2));
+  assert.equal(camera.x, ent.x - Math.floor(16 / 2));
+  assert.equal(camera.y, ent.y - Math.floor(10 / 2));
 });
 
 test('pipCameraFor clamps near map edges', () => {
-  const { world, body } = makeBody(1, 1);
-  const camera = pipCameraFor(body, world);
+  const { world, ent } = makeEntity('body', 1, 1);
+  const camera = pipCameraFor(ent, world);
   assert.equal(camera.x, 0);
   assert.equal(camera.y, 0);
 });
 
-test('pipChrome labels the feed and body HP', () => {
-  const { body } = makeBody(0, 0, 3, 8);
-  const rows = pipChrome(body);
-  assert.equal(rows[0]?.text, '// CCTV //');
+test('pipChrome labels the meat feed by followed operator', () => {
+  const run = viewingCyber();
+  const partnerRows = pipChrome(run);
+  assert.equal(partnerRows[0]?.text, '// CCTV //');
+  assert.match(partnerRows[1]?.text ?? '', /^PARTNER /);
+
+  run.partner.alive = false;
+  const bodyRows = pipChrome(run);
+  assert.match(bodyRows[1]?.text ?? '', /^BODY /);
+});
+
+test('pipChrome labels the cyber feed on two rows (GRID caption, RAM vitals)', () => {
+  const run = { ...viewingCyber(), activeLayer: 'meat' as const };
+  const rows = pipChrome(run);
+  assert.equal(rows[0]?.text, '// GRID //');
   assert.equal(rows[0]?.anchor, 'top-left');
-  assert.match(rows[1]?.text ?? '', /^BODY /);
+  assert.equal(rows[0]?.row, 0);
+  assert.match(rows[1]?.text ?? '', /^RAM /);
   assert.equal(rows[1]?.anchor, 'top-right');
+  assert.equal(rows[1]?.row, 3);
+});
+
+test('pipChrome stacks meat feed caption and vitals on separate rows', () => {
+  const run = viewingCyber();
+  const rows = pipChrome(run);
+  assert.equal(rows[0]?.row, 0);
+  assert.equal(rows[1]?.row, 3);
 });
diff --git a/tests/unit/shell/sceneListeners.test.ts b/tests/unit/shell/sceneListeners.test.ts
index 5398d5f..cacf8d3 100644
--- a/tests/unit/shell/sceneListeners.test.ts
+++ b/tests/unit/shell/sceneListeners.test.ts
@@ -56,3 +56,64 @@ test('SceneListenerController rewire replaces bus handlers', () => {
   bus.emit(EVENT.DOOR_UNLOCKED, { label: 'Vault door' });
   assert.equal(flashCount, 1);
 });
+
+test('P3.M4.5: meat body damage flashes the PIP only while viewing Cyberspace', () => {
+  const bus = new EventBus();
+  const body = { id: 'body', x: 3, y: 4, hp: 4, maxHp: 8, alive: true };
+  // Minimal jacked-in scene: archetype marks it a Run, cyberspace active = a layer exists.
+  const scene = {
+    bus,
+    world: { entities: new Map() },
+    player: body,
+    archetype: 'decker',
+    cyberspace: { phase: 'active', layer: { avatar: { id: 'avatar' }, bus: new EventBus(), mapSeenKeys: () => [] } },
+    activeLayer: 'cyber',
+    state: 'combat',
+  } as unknown as ShellScene;
+
+  const flashes: string[] = [];
+  let pipPaints = 0;
+  const fakeClassList = { remove: () => {}, add: () => {}, toggle: () => {} };
+  const controller = new SceneListenerController({
+    getScene: () => scene,
+    getCampaign: () => null,
+    getMeatVision: () => new VisionField(),
+    getCyberVision: () => new VisionField(),
+    resetCyberVision: () => new VisionField(),
+    dom: {
+      stageEl: { classList: fakeClassList, offsetWidth: 0 } as unknown as HTMLElement,
+      pipCanvas: { classList: fakeClassList, offsetWidth: 0 } as unknown as HTMLCanvasElement,
+    },
+    // No flashCell ⇒ runMuzzleFlash is a no-op, so we exercise only the damage block.
+    renderers: { main: {} as never, pip: {} as never },
+    animLock: { push: () => {} },
+    effects: {
+      flash: (msg: string) => flashes.push(msg),
+      paint: () => {},
+      paintPip: () => {
+        pipPaints++;
+      },
+      recomputeVision: () => {},
+    },
+    onCivilianHarmReset: () => {},
+    onCivilianHarmed: () => {},
+    onRepAdjust: () => {},
+    onAlarmTransition: () => {},
+    onObjectiveTimerExpired: () => {},
+    memoriseMeatCorpse: () => {},
+    memoriseCyberCorpse: () => {},
+  });
+  controller.rewire();
+
+  // Viewing Cyberspace: the meat body is in the PIP, so a body hit pulses it.
+  bus.emit(EVENT.ENTITY_DAMAGED, { target: body, damage: 3 });
+  assert.equal(pipPaints, 1);
+  assert.equal(flashes.length, 1);
+  assert.match(flashes[0] ?? '', /^BODY HIT/);
+
+  // Flip back to Meatspace: the body is on the main canvas now — no PIP feedback.
+  (scene as unknown as { activeLayer: string }).activeLayer = 'meat';
+  bus.emit(EVENT.ENTITY_DAMAGED, { target: body, damage: 3 });
+  assert.equal(pipPaints, 1);
+  assert.equal(flashes.length, 1);
+});

From 8915b28b88bd8a27376d089dee8bfe04920ed5f4 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Tue, 16 Jun 2026 16:14:58 -0700
Subject: [PATCH 44/55] gah prettier

---
 components/RunBriefing.ts                          |  4 +---
 src/game/Campaign.ts                               |  4 +++-
 src/game/Run.ts                                    |  4 +++-
 tests/unit/game/cyber/dualDeploy.test.ts           | 11 +++++++++--
 tests/unit/game/cyber/jackInDualDeploy.test.ts     |  3 ++-
 tests/unit/game/cyber/operatorTurnConclude.test.ts |  4 +++-
 tests/unit/game/cyber/partnerDeath.test.ts         |  4 +++-
 tests/unit/game/cyber/simstimFlip.test.ts          | 12 +++++++++---
 tests/unit/shell/sceneListeners.test.ts            |  5 ++++-
 9 files changed, 37 insertions(+), 14 deletions(-)

diff --git a/components/RunBriefing.ts b/components/RunBriefing.ts
index b465c5c..249f4e4 100644
--- a/components/RunBriefing.ts
+++ b/components/RunBriefing.ts
@@ -432,9 +432,7 @@ class RunBriefing extends HTMLElement {
     let memberId = selected.id;
     let partnerId: string | null = null;
     if (this.#cyberPartnerMode()) {
-      const decker = this.#crew.find(
-        member => member.archetype === 'Decker' && !member.flatlined
-      );
+      const decker = this.#crew.find(member => member.archetype === 'Decker' && !member.flatlined);
       if (!decker) return; // cyber board invariant: a living Decker exists
       memberId = decker.id;
       partnerId = selected.id;
diff --git a/src/game/Campaign.ts b/src/game/Campaign.ts
index d243a0b..95c66a6 100644
--- a/src/game/Campaign.ts
+++ b/src/game/Campaign.ts
@@ -521,7 +521,9 @@ export class Campaign {
         throw new Error('Campaign.deployCrewMember: the meat partner cannot be a Decker');
       }
       if (partner.id === member.id) {
-        throw new Error('Campaign.deployCrewMember: partner must differ from the deployed operator');
+        throw new Error(
+          'Campaign.deployCrewMember: partner must differ from the deployed operator'
+        );
       }
     }
     if (isScoreContract(contract)) {
diff --git a/src/game/Run.ts b/src/game/Run.ts
index 1420a7f..85b76f2 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -977,7 +977,9 @@ export class Run {
    * otherwise). It is the deployed Decker (`player`) frozen at the port.
    */
   get deckerBody(): Crew | null {
-    return this.cyberspace?.phase === 'active' && this.player instanceof Decker ? this.player : null;
+    return this.cyberspace?.phase === 'active' && this.player instanceof Decker
+      ? this.player
+      : null;
   }
 
   /**
diff --git a/tests/unit/game/cyber/dualDeploy.test.ts b/tests/unit/game/cyber/dualDeploy.test.ts
index 089987d..b87eb23 100644
--- a/tests/unit/game/cyber/dualDeploy.test.ts
+++ b/tests/unit/game/cyber/dualDeploy.test.ts
@@ -14,7 +14,12 @@ import { OUTCOME } from '../../../../src/game/Run.js';
 import { OBJECTIVES } from '../../../../src/game/hub/Curator.js';
 import { buildCrewMember } from '../../../../src/game/archetypes/index.js';
 import { Rng } from '../../../../src/rng.js';
-import { snapshot, restore, snapshotCampaign, restoreCampaign } from '../../../../src/game/persistence.js';
+import {
+  snapshot,
+  restore,
+  snapshotCampaign,
+  restoreCampaign,
+} from '../../../../src/game/persistence.js';
 import { testContractContext } from '../contractTestUtils.js';
 
 const fakeContract = (overrides = {}) => ({
@@ -200,7 +205,9 @@ test('P3.M4.1: partner survives a campaign round-trip in COMBAT state', () => {
 // roster object stranded the partner off the map: flipping to it controlled a
 // phantom that couldn't move (the on-grid copy sat frozen in place).
 function jackInCampaignRun(run: Run) {
-  const point = [...run.world!.entities.values()].find(e => e instanceof JackInPoint) as JackInPoint;
+  const point = [...run.world!.entities.values()].find(
+    e => e instanceof JackInPoint
+  ) as JackInPoint;
   let spot: { x: number; y: number } | null = null;
   for (let dy = -1; dy <= 1 && !spot; dy++) {
     for (let dx = -1; dx <= 1 && !spot; dx++) {
diff --git a/tests/unit/game/cyber/jackInDualDeploy.test.ts b/tests/unit/game/cyber/jackInDualDeploy.test.ts
index ee14244..e56258a 100644
--- a/tests/unit/game/cyber/jackInDualDeploy.test.ts
+++ b/tests/unit/game/cyber/jackInDualDeploy.test.ts
@@ -39,7 +39,8 @@ const cyberContract = (overrides = {}) => ({
   ...overrides,
 });
 
-const makeDecker = () => buildCrewMember('decker', { x: 0, y: 0 }, new Rng(100), { id: 'crew-decker' });
+const makeDecker = () =>
+  buildCrewMember('decker', { x: 0, y: 0 }, new Rng(100), { id: 'crew-decker' });
 const makeMerc = () => buildCrewMember('merc', { x: 0, y: 0 }, new Rng(101), { id: 'crew-merc' });
 
 function dualRun(seed = 12345) {
diff --git a/tests/unit/game/cyber/operatorTurnConclude.test.ts b/tests/unit/game/cyber/operatorTurnConclude.test.ts
index 7558d77..1fda3c5 100644
--- a/tests/unit/game/cyber/operatorTurnConclude.test.ts
+++ b/tests/unit/game/cyber/operatorTurnConclude.test.ts
@@ -92,7 +92,9 @@ function adjacentFreeTile(world: World, target: Entity) {
 }
 
 function jackIn(run: Run) {
-  const point = [...run.world!.entities.values()].find(e => e instanceof JackInPoint) as JackInPoint;
+  const point = [...run.world!.entities.values()].find(
+    e => e instanceof JackInPoint
+  ) as JackInPoint;
   const spot = adjacentFreeTile(run.world!, point);
   run.world!.relocateEntity(run.player!, spot.x, spot.y);
   run.player!.refreshAp();
diff --git a/tests/unit/game/cyber/partnerDeath.test.ts b/tests/unit/game/cyber/partnerDeath.test.ts
index 9e022d0..0162069 100644
--- a/tests/unit/game/cyber/partnerDeath.test.ts
+++ b/tests/unit/game/cyber/partnerDeath.test.ts
@@ -75,7 +75,9 @@ function adjacentFreeTile(world: World, target: Entity) {
 }
 
 function jackIn(run: Run) {
-  const point = [...run.world!.entities.values()].find(e => e instanceof JackInPoint) as JackInPoint;
+  const point = [...run.world!.entities.values()].find(
+    e => e instanceof JackInPoint
+  ) as JackInPoint;
   const spot = adjacentFreeTile(run.world!, point);
   run.world!.relocateEntity(run.player!, spot.x, spot.y);
   run.player!.refreshAp();
diff --git a/tests/unit/game/cyber/simstimFlip.test.ts b/tests/unit/game/cyber/simstimFlip.test.ts
index 37937cf..b017181 100644
--- a/tests/unit/game/cyber/simstimFlip.test.ts
+++ b/tests/unit/game/cyber/simstimFlip.test.ts
@@ -41,7 +41,8 @@ const cyberContract = (overrides = {}) => ({
   ...overrides,
 });
 
-const makeDecker = () => buildCrewMember('decker', { x: 0, y: 0 }, new Rng(100), { id: 'crew-decker' });
+const makeDecker = () =>
+  buildCrewMember('decker', { x: 0, y: 0 }, new Rng(100), { id: 'crew-decker' });
 const makeMerc = () => buildCrewMember('merc', { x: 0, y: 0 }, new Rng(101), { id: 'crew-merc' });
 
 function dualRun(seed = 12345) {
@@ -72,7 +73,9 @@ function adjacentFreeTile(world: World, target: Entity) {
 }
 
 function jackIn(run: Run) {
-  const point = [...run.world!.entities.values()].find(e => e instanceof JackInPoint) as JackInPoint;
+  const point = [...run.world!.entities.values()].find(
+    e => e instanceof JackInPoint
+  ) as JackInPoint;
   const spot = adjacentFreeTile(run.world!, point);
   run.world!.relocateEntity(run.player!, spot.x, spot.y);
   run.player!.refreshAp();
@@ -114,7 +117,10 @@ test('P3.M4.3: flip swaps meat partner ↔ cyber avatar while jacked in', () =>
   assert.equal(isCyberView(run), true);
   assert.equal(isJackedIn(run), true);
   assert.equal(activeTileset(run), 'cyber');
-  assert.equal(activeWorldOf(run), run.cyberspace!.phase === 'active' && run.cyberspace.layer.world);
+  assert.equal(
+    activeWorldOf(run),
+    run.cyberspace!.phase === 'active' && run.cyberspace.layer.world
+  );
 
   // Flip back to Meatspace.
   run.flip();
diff --git a/tests/unit/shell/sceneListeners.test.ts b/tests/unit/shell/sceneListeners.test.ts
index cacf8d3..6505d88 100644
--- a/tests/unit/shell/sceneListeners.test.ts
+++ b/tests/unit/shell/sceneListeners.test.ts
@@ -66,7 +66,10 @@ test('P3.M4.5: meat body damage flashes the PIP only while viewing Cyberspace',
     world: { entities: new Map() },
     player: body,
     archetype: 'decker',
-    cyberspace: { phase: 'active', layer: { avatar: { id: 'avatar' }, bus: new EventBus(), mapSeenKeys: () => [] } },
+    cyberspace: {
+      phase: 'active',
+      layer: { avatar: { id: 'avatar' }, bus: new EventBus(), mapSeenKeys: () => [] },
+    },
     activeLayer: 'cyber',
     state: 'combat',
   } as unknown as ShellScene;

From e35b48e596d60cba7e7d5f7333e25003b398da64 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Tue, 16 Jun 2026 19:59:45 -0700
Subject: [PATCH 45/55] lint

---
 src/render/AsciiRenderer.ts | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/render/AsciiRenderer.ts b/src/render/AsciiRenderer.ts
index dc4bbdf..f59296d 100644
--- a/src/render/AsciiRenderer.ts
+++ b/src/render/AsciiRenderer.ts
@@ -391,8 +391,7 @@ export class AsciiRenderer {
     text: string,
     boxX: number,
     boxW: number,
-    boxY: number,
-    accentColor?: string
+    boxY: number
   ) {
     const ctx = this.ctx;
     if (!ctx) return;

From b60dc63dda756053ae06482badec1d559c2d814a Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Tue, 16 Jun 2026 21:25:33 -0700
Subject: [PATCH 46/55] 3 jack-out routes

---
 components/TouchPad.ts                  |   1 +
 docs/phase-3-plan.md                    |  16 ++-
 src/game/Run.ts                         | 115 +++++++++++++---
 src/game/constants.ts                   |   2 +
 src/input/applyIntent.ts                |  18 ++-
 src/input/keyHelp.ts                    |   6 +
 src/input/keymap.ts                     |   9 +-
 src/input/touchpad.ts                   |   3 +-
 src/shell/sceneListeners.ts             |  10 +-
 src/shell/shellRuntime.ts               |  48 +++++--
 src/shell/statusLine.ts                 |   7 +-
 src/statusActivityRows.ts               |  15 +-
 tests/unit/game/cyber/jackOut.test.ts   | 176 +++++++++++++++++++++++-
 tests/unit/input/applyIntent.test.ts    |  16 +++
 tests/unit/input/keyHelp.test.ts        |   1 +
 tests/unit/input/keymap.test.ts         |   6 +
 tests/unit/input/touchpad.test.ts       |   8 ++
 tests/unit/shell/sceneListeners.test.ts |  50 +++++++
 tests/unit/shell/statusLine.test.ts     |  20 +++
 tests/unit/statusActivityRows.test.ts   |  22 +++
 20 files changed, 508 insertions(+), 41 deletions(-)

diff --git a/components/TouchPad.ts b/components/TouchPad.ts
index 36d6faf..f82d6dd 100644
--- a/components/TouchPad.ts
+++ b/components/TouchPad.ts
@@ -75,6 +75,7 @@ const ACTION_BUTTONS = Object.freeze([
   // verb actually resolves, so the player still sees their kit's flavour.
   { id: 'special', label: 'SPECIAL', shortcut: 'x' },
   { id: 'interact', label: 'INTERACT', shortcut: '␣' },
+  { id: 'jack-out', label: 'JACK OUT', shortcut: 'j' },
   { id: 'look', label: 'LOOK', shortcut: 'l' },
   { id: 'inventory', label: 'ITEMS', shortcut: 'i' },
   { id: 'end-turn', label: 'WAIT', shortcut: '.' },
diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index b60115e..66a7a3b 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -44,7 +44,7 @@ A new **player archetype** recruited mid-campaign (late Act 1 / start of Act 2),
 | P3.M1 — Campaign arc structure | ✅ Done |
 | P3.M2 — The Decker archetype | ✅ Done |
 | P3.M3 — Cyberspace grid + ICE | ✅ Done (full ICE roster: Probe, Spark, Guardian) |
-| P3.M4 — Simstim flip (dual-deploy) | 🟡 In progress (M4.1–M4.5 done; M4.6 jack-out remains) |
+| P3.M4 — Simstim flip (dual-deploy) | ✅ Done |
 | P3.M5 — The Score (climactic mission) | 🔲 Planned |
 | P3.M6 — Chronicle (campaign narrative memory) | 🟡 End-summary foundation shipped |
 
@@ -335,7 +335,11 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 - **Turn structure:** Player turn → flip as desired → end turn → **both layers' hostile phases resolve** (corp drones move in Meatspace, ICE moves in Cyberspace). Both layers tick simultaneously.
 - **PIP / CCTV window:** The inactive layer renders in a small overlay (bottom right corner of the screen). Shows grid state, hostile positions, the other operator's status. Read-only — no input accepted in the PIP. The blueprint's "real-time CCTV showing your physical body's status" becomes this.
 - **Vulnerability:** While the Decker is jacked in, their Meatspace body is a valid target for corp hostiles. The body **cannot die while jacked in** — a killing/critical hit clamps it to 1 HP and forces a jack-out (resolved decision); only ICE depleting RAM flatlines the Decker outright. The Meatspace partner's explicit job is to **protect the Decker's body** — or at least keep hostiles away from the terminal.
-- **Jack-out:** The Decker can voluntarily jack out (returns control to single-grid Meatspace). Or is forced out when their body is driven to 1 HP. Jack-out despawns the Cyberspace grid (any unsatisfied Cyberspace objectives fail).
+- **Jack-out:**
+  - Jack-out despawns the Cyberspace grid, returning control to single-grid Meatspace
+  - The Decker can voluntarily jack out at any time via two means: 1, moving to the cyberspace exit glyph, or 2, hitting an explicit "jack-out" key (doing it this way causes neural shock and loss of 3 HP, so should be confirmed before proceeding)
+  - when jacking out, any unsatisfied Cyberspace objectives fail, but the run can still be completed for the usual penalty (the exception being the Score, which MUST be completed successfully).
+  - The Decker is also forced out when their body is driven to 1 HP by hostile attacks in Meatspace.
 - **Contracts without Cyberspace:** Single-deploy as today. The Decker deploys solo in Meatspace (no flip, no Cyberspace grid). Their drone override hack is their primary value. A pre-Score flatline opens one replacement Decker lead through the Terminal; a flatline during THE SCORE is campaign-terminal.
 - **Save invariant:** A run may be single-layer, pre-jack dual-deploy, or active dual-layer. Those states must be explicit. A save with `cyberspace.active = true` but no cyber grid/avatar, or with a Decker marked jacked-in but no Meatspace body anchor, is corrupt and must throw.
 
@@ -348,7 +352,7 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 | **P3.M4.3 Flip command** | ✅ Done | Tab → free-action flip; `activeView` keys on `activeLayer`; `Run.flip()`/`canFlip()` | flip toggles layer/actor, solo+pre-jack can't flip, meat↔meat post-jack-out, keymap intent |
 | **P3.M4.4 Dual hostile phase** | ✅ Done | Independent AP pools + decoupled turn-end (auto-flip on exhaustion); both hostile phases tick once each with partner+body present; partner death handled | AP-pool/turn-end model; dual-phase verify with partner+body; partner flatline + control repair + alert |
 | **P3.M4.5 PIP** | ✅ Done | Inactive layer mini-render + status summary; both layers route flashes to whichever side is in the PIP | inactive-feed resolution, partner→body follow fallback, cyber/RAM chrome, body-hit-in-PIP routing, cyber vs meat palatte styling of both main & PIP canvases |
-| **P3.M4.6 Jack-out** | 🔲 | Voluntary + forced (1-HP) jack-out transitions back to Meatspace | cleanup, objective failure rules, snapshot round-trip |
+| **P3.M4.6 Jack-out** | ✅ Done | Exit-port, explicit-key, and forced (1-HP) jack-out transition back to Meatspace | cleanup, objective failure rules, neural-shock confirmation, snapshot round-trip |
 
 **P3.M4.4 — dual-phase verify + partner death (2026-06-15):** The M3.6 dual-phase corp turn (chained meat pass → ICE pass on the shared run rng) was only ever tested solo-Decker; re-verified with a partner + frozen body on the meat grid: the meat pass steps neither PLAYER operator, both layers tick regardless of which layer the player is viewing, one AP refresh per round across body + partner + avatar (+ ICE), determinism holds with the partner present (PLAYER faction draws no corp rng), and post-jack-out the meat corp turn runs solo (no ICE pass) with both operators present (`dualPhaseTurn.test.ts`, +5). **Partner death** (the playtest report — partner killed off-screen during the corp turn while the player was in Cyberspace, discovered only via a "no operator to flip to" deny): the meat partner flatlining is *not* run-ending (the Decker fights on), handled in `Run.#onEntityDamaged` → `#onPartnerFlatlined` — it repairs the active-operator state so the player never drives a corpse (if the dead partner was the meat actor, control returns to the Decker `player`; while still jacked in the body is frozen, so the view also force-flips to Cyberspace onto the avatar), and fires a new `onPartnerDown` shell hook that flashes an **unconditional** "⚠ OPERATOR DOWN" alert (the kill is invisible from the grid view). `Run.partnerDown` (partner fielded + not alive) drives `Campaign.onJobEnd`, which flatlines `deployedPartnerId` for good — independent of the Decker's outcome (extracted clean or died), and across a campaign round-trip. Tests: `partnerDeath.test.ts` (8). Closes the partner-death follow-up that M4.2 deferred. **Restore companion fix (playtest, dead-partner-stuck save):** `#onPartnerFlatlined` repairs control at the *moment* of death, but `restore()` still set `meatActor = gridPartner` unconditionally — so a save with a jacked-in run + dead partner (or any pre-fix save) reconstructed the stuck state (driving a corpse in Meatspace, `canFlip` false). Restore now mirrors the live repair: a dead grid partner is never the meat operator — `meatActor` falls back to the (frozen) body and the view defaults to Cyberspace onto the avatar; a living partner restores normally honoring the saved view.
 
@@ -364,12 +368,16 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 
 **P3.M4.5 implementation note (2026-06-15):** The M3.7 PIP (always the meatspace body CCTV) now renders the **inactive** layer after the simstim flip — the layer the player is *not* driving. `pip.ts` is the pure seam: `pipFeedFor` resolves `'meat'` when viewing cyber and `'cyber'` when viewing meat (absent `activeLayer` defaults to the meat feed, preserving solo/legacy behaviour); `pipWorldOf`/`pipFollowTargetOf`/`pipChrome`/`shouldShowPip` all key off the feed. The meat feed follows the **living partner**, falling back to the Decker's frozen **body** once the partner flatlines (or on a solo Decker run) — chrome labels `PARTNER`/`BODY` accordingly; the cyber feed follows the avatar and reads `// THE GRID //` + `RAM` over a magenta-tinted (`.pip-cyber`) border, with cyber fog (`cyberVision`) and no principal palette. `pointer-events: none` keeps the overlay read-only. **Flash routing fix:** M3.7 routed body-hit feedback to the PIP whenever `isJackedIn`; that was only correct while viewing cyber. `sceneListeners` now routes by *which layer is in the PIP* — meat events (body/partner damage, muzzle, ranged noise) flash the PIP iff `isCyberView` (meat is the inactive feed) and the main canvas otherwise; cyber events symmetrically flash the PIP when viewing meat, including a new `RAM HIT`/`RAM WIPED` pulse so off-screen ICE damage is visible. Tests: `pip.test.ts` rewritten for the inactive-feed resolution + partner/body fallback + cyber chrome (11), and a `sceneListeners.test.ts` case locks the body-hit-routes-to-PIP-only-while-viewing-cyber predicate. **Follow-up:** still no touch-pad flip button (keyboard-only, from M4.3); the end-to-end PIP swap wants a live in-campaign playtest once a dual-deploy cyber contract is reachable (no DOM harness for the render path).
 
+**P3.M4.6 implementation note (2026-06-17):** Forced jack-out now lands on the same resolver as voluntary jack-out: if the frozen Decker body takes Meatspace damage while the cyber layer is active and is driven to **1 HP or below**, `Run.#onEntityDamaged` clamps the body alive at 1 HP, bypasses early-jack-out confirmation (it is not a choice), tears down the cyber layer, burns the jack-in port, returns control to the Decker in Meatspace, and latches the data-node objective at its current progress. Unsliced nodes therefore make the cyber objective permanently incomplete; already-sliced objectives remain complete. This covers both nonlethal hits to exactly 1 HP and lethal hits that `Entity.damage()` had already marked dead before the run listener repaired the body. Snapshot round-trip preserves the resolved cyber latch, burned port, living 1-HP Decker, and post-jack-out meat control. Shell corpse memory now ignores the repaired body even when the raw damage payload said `killed: true`, so the PIP/visibility cache does not record the Decker as a corpse after emergency ejection. Tests: `jackOut.test.ts` (+3 forced-jack-out cases) and `sceneListeners.test.ts` (+1 repaired-body corpse-memory guard).
+
+**P3.M4.6 explicit jack-out key closeout (2026-06-17):** The missing second voluntary path is now bound to **`j`** (`keymap` → `{type:'jack-out'}`; touch pad mirrors it as `JACK OUT`). Unlike routing out through the Cyberspace exit glyph, explicit jack-out always confirms when the shell is wired because it applies `JACK_OUT_SHOCK_DAMAGE = 3` HP neural shock to the Decker's body after the link actually drops. The request is valid from either side of a live dual-deploy jack-in, so the player can eject while controlling the meat partner; it burns the link, resolves/despawns Cyberspace, latches objective progress, and then applies shock. At critical HP, confirmed shock can flatline the Decker, but the save state is still resolved/burned before death settlement — no dead-but-still-jacked-in state. Key help and touch controls both advertise the action. Tests: `jackOut.test.ts` (+3 explicit-key cases), `keymap.test.ts`, `applyIntent.test.ts`, `touchpad.test.ts`, and `keyHelp.test.ts`. Closes P3.M4.
+
 **Acceptance:**
 
 - Dual-deploy: two operators on two grids, each controllable.
 - Flip switches active control; inactive operator holds position; both hostile phases tick.
 - PIP renders inactive layer (at minimum: grid + entities + operator status).
-- Decker body vulnerable in Meatspace while jacked in; body death = Decker death.
+- Decker body vulnerable in Meatspace while jacked in; body at 1 HP = forced jack-out, while cyber avatar death still flatlines the Decker.
 - Jack-out despawns Cyberspace grid cleanly.
 - Snapshot: both grids, both operators, flip state; restore round-trip mid-mission.
 - Golden-path test: deploy → jack in → flip between layers → complete objectives in both → extract.
diff --git a/src/game/Run.ts b/src/game/Run.ts
index 85b76f2..39334c3 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -42,6 +42,7 @@ import {
   SALVAGE_DROP_MIN,
   SALVAGE_DROP_MAX,
   ENEMY_ROLE,
+  JACK_OUT_SHOCK_DAMAGE,
   factionForPrincipalGroups,
 } from './constants.js';
 import { coordKey, explorationReachableKeys } from './mapConnectivity.js';
@@ -363,6 +364,12 @@ type KeyItemSnapshot = {
   doorId: string;
 };
 
+export type JackOutRequest = {
+  reason: 'exit-port' | 'explicit-key';
+  objectiveComplete: boolean;
+  shockDamage: number;
+};
+
 export type RunResult = {
   outcome: Outcome;
   telemetry: RunTelemetry;
@@ -381,9 +388,9 @@ export type RunOptions = {
    *  to finalise the abort extraction, or do nothing to let the player
    *  stay on the exit tile and keep playing. */
   onAbortRequested?: unknown;
-  /** P3.M3: called when the avatar routes out with the objective incomplete —
-   *  an irreversible step (the link burns, the objective latches
-   *  unsatisfiable). The shell should show a confirmation prompt; call
+  /** P3.M3/M4: called when jack-out needs confirmation: either incomplete
+   *  objective through the exit port, or the explicit jack-out key's neural
+   *  shock. The shell should show a confirmation prompt; call
    *  `run.confirmJackOut()` to finalize, or do nothing to keep the layer
    *  live. No callback registered → jack out immediately (tests/harness),
    *  matching the `onAbortRequested` posture. */
@@ -482,13 +489,14 @@ export class Run {
   onPersist: ((record: RunSnapshot) => void) | null;
   onResult: ((result: RunResult) => void) | null;
   onAbortRequested: (() => void) | null;
-  onJackOutRequested: (() => void) | null;
+  onJackOutRequested: ((request: JackOutRequest) => void) | null;
   /** Shell presentation hook — fired synchronously after jack-in completes. */
   onJackInPresent: (() => void) | null;
   /** Shell presentation hook — fired after jack-out finalizes. */
   onJackOutPresent: (() => void) | null;
   /** P3.M4.4 shell presentation hook — fired with the partner when it flatlines. */
   onPartnerDown: ((partner: Crew) => void) | null;
+  #pendingJackOut: JackOutRequest | null;
   _busUnsubs: (() => void)[];
 
   constructor({
@@ -579,10 +587,12 @@ export class Run {
     this.onPersist = (onPersist as ((record: RunSnapshot) => void) | undefined) ?? null;
     this.onResult = (onResult as ((result: RunResult) => void) | undefined) ?? null;
     this.onAbortRequested = (onAbortRequested as (() => void) | undefined) ?? null;
-    this.onJackOutRequested = (onJackOutRequested as (() => void) | undefined) ?? null;
+    this.onJackOutRequested =
+      (onJackOutRequested as ((request: JackOutRequest) => void) | undefined) ?? null;
     this.onJackInPresent = (onJackInPresent as (() => void) | undefined) ?? null;
     this.onJackOutPresent = (onJackOutPresent as (() => void) | undefined) ?? null;
     this.onPartnerDown = (onPartnerDown as ((partner: Crew) => void) | undefined) ?? null;
+    this.#pendingJackOut = null;
 
     /** @type {Array<() => void>} active bus subscriptions */
     this._busUnsubs = [];
@@ -1192,6 +1202,25 @@ export class Run {
    * variant (body under fire).
    */
   jackOut(): void {
+    this.#requestJackOut({ reason: 'exit-port', shockDamage: 0 });
+  }
+
+  /**
+   * P3.M4 explicit jack-out key: drop the link from anywhere in an active
+   * jack-in. Unlike the exit port, this always asks for confirmation when the
+   * shell is wired because it applies neural shock to the Decker's body.
+   */
+  requestJackOut(): void {
+    this.#requestJackOut({ reason: 'explicit-key', shockDamage: JACK_OUT_SHOCK_DAMAGE });
+  }
+
+  #requestJackOut({
+    reason,
+    shockDamage,
+  }: {
+    reason: JackOutRequest['reason'];
+    shockDamage: number;
+  }): void {
     if (this.state !== RUN_STATE.COMBAT) {
       throw new Error(`Run.jackOut: illegal from state ${this.state} (COMBAT only)`);
     }
@@ -1207,17 +1236,17 @@ export class Run {
     // P3.M3.4: the latch is the sliced-node tally at the moment the link
     // drops. Jacking out early leaves the objective permanently unsatisfiable
     // — extraction then routes through the existing abort-confirm flow.
-    const { sliced } = dataNodeProgress(layer.world);
-    const objectiveComplete = sliced >= objectiveCount(this.contract);
-    // S7.5: an incomplete jack-out is irreversible — defer to the shell for
-    // confirmation when a callback is registered (the port's interact AP is
-    // already spent; a re-request after cancel costs it again). No callback
-    // → resolve immediately, the `onAbortRequested` posture.
-    if (!objectiveComplete && this.onJackOutRequested) {
-      this.onJackOutRequested();
+    const objectiveComplete = this.#cyberObjectiveComplete(layer);
+    const request: JackOutRequest = { reason, objectiveComplete, shockDamage };
+    // S7.5/P3.M4: incomplete jack-out is irreversible; explicit-key jack-out
+    // additionally hurts the body. Defer to shell confirmation when wired. No
+    // callback → resolve immediately, the `onAbortRequested` posture.
+    if ((!objectiveComplete || shockDamage > 0) && this.onJackOutRequested) {
+      this.#pendingJackOut = request;
+      this.onJackOutRequested(request);
       return;
     }
-    this.#finalizeJackOut(layer, objectiveComplete);
+    this.#finalizeJackOut(layer, objectiveComplete, shockDamage);
   }
 
   /**
@@ -1228,7 +1257,8 @@ export class Run {
    * wiring bug and throws rather than silently no-oping.
    */
   confirmJackOut(): void {
-    if (this.state !== RUN_STATE.COMBAT || this.cyberspace?.phase !== 'active') {
+    const request = this.#pendingJackOut;
+    if (!request || this.state !== RUN_STATE.COMBAT || this.cyberspace?.phase !== 'active') {
       throw new Error(
         `Run.confirmJackOut: no jack-out pending (state ${this.state}, phase ${
           this.cyberspace?.phase ?? 'none'
@@ -1239,14 +1269,40 @@ export class Run {
       throw new Error('Run.confirmJackOut: COMBAT state without a contract');
     }
     const layer = this.cyberspace.layer;
+    this.#pendingJackOut = null;
     // Recompute rather than latch `false` blindly — honest if a future flow
     // ever confirms after progress changed.
+    this.#finalizeJackOut(layer, this.#cyberObjectiveComplete(layer), request.shockDamage);
+  }
+
+  #cyberObjectiveComplete(layer: CyberspaceLayer): boolean {
+    if (!this.contract) {
+      throw new Error('Run.#cyberObjectiveComplete: COMBAT state without a contract');
+    }
     const { sliced } = dataNodeProgress(layer.world);
-    this.#finalizeJackOut(layer, sliced >= objectiveCount(this.contract));
+    return sliced >= objectiveCount(this.contract);
+  }
+
+  /**
+   * P3.M4.6: while jacked in, the Decker's meat body cannot flatline from
+   * Meatspace damage. A hit that drives it to the danger floor ejects the Decker,
+   * clamps the body alive at 1 HP, burns the link, and latches the cyber
+   * objective at its current progress. Unlike voluntary early jack-out, this is
+   * not a choice, so it bypasses the confirmation hook.
+   */
+  #forceJackOutFromBodyDamage(layer: CyberspaceLayer): void {
+    if (!(this.player instanceof Decker)) {
+      throw new Error('Run.#forceJackOutFromBodyDamage: jacked body is not a Decker');
+    }
+    this.#pendingJackOut = null;
+    this.player.hp = 1;
+    this.player.alive = true;
+    this.#finalizeJackOut(layer, this.#cyberObjectiveComplete(layer), 0);
   }
 
   /** Active → resolved: teardown, latch, LINK BURNED, autosave. */
-  #finalizeJackOut(layer: CyberspaceLayer, objectiveComplete: boolean): void {
+  #finalizeJackOut(layer: CyberspaceLayer, objectiveComplete: boolean, shockDamage: number): void {
+    this.#pendingJackOut = null;
     layer.teardown();
     this.cyberspace = { phase: 'resolved', objectiveComplete };
     // P3.M4.2: the Decker is back in its body — unfreeze it, return control to
@@ -1260,11 +1316,32 @@ export class Run {
     this.activeLayer = 'meat';
     // S5: the link is burned — re-jack-in refused for the rest of the run.
     this.#meatJackInPoint().burn();
+    this.#applyJackOutShock(shockDamage);
+    if (this.state !== RUN_STATE.COMBAT) return;
     if (this.onPersist) {
       this.onPersist(this.snapshot());
     }
     this.onJackOutPresent?.();
   }
+
+  #applyJackOutShock(shockDamage: number): void {
+    if (shockDamage === 0) return;
+    if (!Number.isInteger(shockDamage) || shockDamage < 0) {
+      throw new RangeError(`Run.#applyJackOutShock: invalid shockDamage ${shockDamage}`);
+    }
+    if (!this.player) {
+      throw new Error('Run.#applyJackOutShock: COMBAT state without a player');
+    }
+    const applied = this.player.damage(shockDamage);
+    this.telemetry.lastDamageSource = 'neural-shock';
+    this.telemetry.lastAttacker = null;
+    this.telemetry.hpAtDamage = this.player.hp;
+    if (!this.player.alive) {
+      this.telemetry.hpAtDeath = 0;
+      this.telemetry.cause = `neural-shock(${applied})`;
+      this.enterResult({ outcome: OUTCOME.DEATH });
+    }
+  }
   #meatJackInPoint(): JackInPoint {
     if (!this.world) {
       throw new Error('Run.#meatJackInPoint: no live world');
@@ -1579,6 +1656,10 @@ export class Run {
       this.telemetry.lastDamageSource = source ?? null;
       this.telemetry.lastAttacker = attacker?.id ?? null;
       this.telemetry.hpAtDamage = this.player.hp;
+      if (this.cyberspace?.phase === 'active' && this.player.hp <= 1) {
+        this.#forceJackOutFromBodyDamage(this.cyberspace.layer);
+        return;
+      }
       if (killed) {
         this.telemetry.hpAtDeath = 0;
         this.telemetry.cause = `${attacker?.id ?? 'unknown'}::${source ?? 'unknown'}(${damage})`;
diff --git a/src/game/constants.ts b/src/game/constants.ts
index 1a4b7a7..3f3d30c 100644
--- a/src/game/constants.ts
+++ b/src/game/constants.ts
@@ -130,6 +130,8 @@ export const DECKER_BASE_ICE_RESISTANCE = 1;
  */
 export const CYBER_AVATAR_MAX_AP = 4;
 export const CYBER_AVATAR_HIT_CHANCE = 0.8;
+/** P3.M4: explicit jack-out drops the link hard enough to hurt the body. */
+export const JACK_OUT_SHOCK_DAMAGE = 3;
 
 /**
  * Tech turret parameters. The turret is a placed grid entity (peer of
diff --git a/src/input/applyIntent.ts b/src/input/applyIntent.ts
index 75a5641..a488842 100644
--- a/src/input/applyIntent.ts
+++ b/src/input/applyIntent.ts
@@ -6,8 +6,8 @@
  *
  * The intent shape is the closed enum the keymap / touch layer and other
  * callers may produce:
- *   { type: 'move' | 'special' | 'melee' | 'fire' | 'interact' | 'end-turn'
- *         | 'cancel', dx?, dy? }
+ *   { type: 'move' | 'special' | 'melee' | 'fire' | 'interact' | 'jack-out'
+ *         | 'end-turn' | 'cancel', dx?, dy? }
  *
  * `move` into an occupied tile is resolved in `doMove`: a corp (or any
  * non-allied, non-neutral) neighbour is a bump-melee; same-faction or neutral
@@ -154,6 +154,7 @@ const KNOWN_INTENT_TYPES = new Set([
   'fire',
   'interact',
   'inventory',
+  'jack-out',
   'use-item',
   'end-turn',
   'cancel',
@@ -167,6 +168,7 @@ export const PLAYER_ACTIONS = Object.freeze({
   REACHED_EXIT: 'movedToExit',
   INVENTORY: 'inventory',
   INTERACT: 'interact',
+  JACK_OUT: 'jack-out',
 });
 
 function gateOnApExhausted(ctx: ApplyIntentContext) {
@@ -218,6 +220,8 @@ export function applyIntent(intent: Intent, ctx: ApplyIntentContext) {
       return doInteract(ctx);
     case 'inventory':
       return doInventory(ctx);
+    case 'jack-out':
+      return doJackOut(ctx);
     case 'use-item':
       return doUseItem(intent, ctx);
     case 'end-turn': {
@@ -651,6 +655,16 @@ function doInventory(ctx: ApplyIntentContext) {
   ctx.onPlayerAction(PLAYER_ACTIONS.INVENTORY);
 }
 
+function doJackOut(ctx: ApplyIntentContext) {
+  // Explicit jack-out is a Run-level transition, not an active-world action:
+  // it can eject the Decker even while the player is controlling the meat
+  // partner. The shell owns the active-Cyberspace gate and confirmation copy.
+  if (typeof ctx.onPlayerAction !== 'function') {
+    throw new Error('applyIntent: jack-out intent received but ctx.onPlayerAction is missing');
+  }
+  ctx.onPlayerAction(PLAYER_ACTIONS.JACK_OUT);
+}
+
 /**
  * Thrown-consumable resolution. The keymap emits `use-item { dx, dy }`
  * from `MODE.AIM` / `aimKind: 'use-item'`; the shell stashes the pending `itemId` when it
diff --git a/src/input/keyHelp.ts b/src/input/keyHelp.ts
index 15c579c..9a4385f 100644
--- a/src/input/keyHelp.ts
+++ b/src/input/keyHelp.ts
@@ -83,6 +83,12 @@ export const HELP_ROWS = Object.freeze([
     scope: 'combat',
     group: 'action',
   },
+  {
+    keys: Object.freeze(['j']),
+    label: 'Jack out — confirm neural shock',
+    scope: 'combat',
+    group: 'action',
+  },
   // --- system -----------------------------------------------------------
   {
     keys: Object.freeze(['.']),
diff --git a/src/input/keymap.ts b/src/input/keymap.ts
index d24d07e..a07c965 100644
--- a/src/input/keymap.ts
+++ b/src/input/keymap.ts
@@ -10,8 +10,9 @@
  * the next directional press resolves into. Thrown consumables enter the same
  * aim mode programmatically (`aimKind: 'use-item'`). Wait / pass turn is `.`
  * in IDLE (`end-turn` intent). Interact (Curator, Terminal, …) is Space in IDLE;
- * `i` opens inventory. `Q` emits `quit-campaign` in IDLE only — the shell
- * confirms, deletes the save, and starts a new campaign (not routed through
+ * `i` opens inventory; `j` requests explicit jack-out while linked to
+ * Cyberspace. `Q` emits `quit-campaign` in IDLE only — the shell confirms,
+ * deletes the save, and starts a new campaign (not routed through
  * `applyIntent`).
  *
  * The archetype-specific perks — Merc's Vault, Razor's Slide, Tech's Deploy
@@ -114,6 +115,10 @@ function dispatchIdle(key: string): DispatchResult {
       // presents `<item-inventory>` and handles `use-item` events. In the Hub
       // this is a no-op (Finn's shop uses Space-interact).
       return { intent: { type: 'inventory' }, nextMode: MODE.IDLE, aimKind: null };
+    case 'j':
+      // Explicit jack-out — shell gates it to active Cyberspace and confirms
+      // neural shock before calling Run.requestJackOut().
+      return { intent: { type: 'jack-out' }, nextMode: MODE.IDLE, aimKind: null };
     case 'l':
       return stayLook();
     case 'Tab':
diff --git a/src/input/touchpad.ts b/src/input/touchpad.ts
index d40930c..7aacbfe 100644
--- a/src/input/touchpad.ts
+++ b/src/input/touchpad.ts
@@ -7,7 +7,7 @@
  *
  * Button identifiers:
  *   - Directions (8): N, NE, E, SE, S, SW, W, NW
- *   - Actions: fire, special, interact, end-turn, cancel
+ *   - Actions: fire, special, interact, jack-out, end-turn, cancel
  *   - Shell (not `applyIntent`): quit-campaign → synthetic `Q`
  *
  * The `special` action covers each archetype's perk verb (Merc Vault, Razor
@@ -36,6 +36,7 @@ const ACTION_KEYS = Object.freeze({
   fire: 'f',
   special: 'x',
   interact: ' ',
+  'jack-out': 'j',
   inventory: 'i',
   look: 'l',
   'end-turn': '.',
diff --git a/src/shell/sceneListeners.ts b/src/shell/sceneListeners.ts
index c54fbad..24fc761 100644
--- a/src/shell/sceneListeners.ts
+++ b/src/shell/sceneListeners.ts
@@ -8,6 +8,7 @@ import {
   triggerShake,
 } from '../render/animations.js';
 import { cyberLayerOf, isCyberView } from './activeView.js';
+import { isRun } from './sceneView.js';
 import type {
   DoorUnlockPayload,
   EntityDamagedPayload,
@@ -74,7 +75,10 @@ export class SceneListenerController {
         // P3.M4.5: the meat layer is in the PIP only while the player is
         // *viewing* Cyberspace; once flipped back to meat it is the main canvas.
         const meatInPip = isCyberView(run);
-        if (run?.player && target === run.player && damage > 0) {
+        const bodyHit = isRun(run) && !!run.player && target === run.player;
+        const forcedBodyJackOut =
+          bodyHit && killed === true && !!target?.alive && run.cyberspace?.phase === 'resolved';
+        if (bodyHit && damage > 0) {
           triggerShake(dom.stageEl);
           triggerDamageFlash(dom.stageEl);
           animLock.push(ANIMATION_DURATIONS.DAMAGE_FLASH);
@@ -84,7 +88,7 @@ export class SceneListenerController {
               : 'unknown';
             effects.flash(
               killed
-                ? `BODY FLATLINED — ${attackerLabel} killed your meatspace link.`
+                ? `BODY CRITICAL — ${attackerLabel} forced an emergency jack-out.`
                 : `BODY HIT — ${attackerLabel} struck for ${damage} (meatspace).`
             );
             dom.pipCanvas.classList.remove('pip-hit');
@@ -99,7 +103,7 @@ export class SceneListenerController {
           const fired = runMuzzleFlash(flashRenderer, repaint, target.x, target.y);
           if (fired) animLock.push(ANIMATION_DURATIONS.MUZZLE_FLASH);
         }
-        if (killed && target) {
+        if (killed && target && !forcedBodyJackOut) {
           this.#deps.memoriseMeatCorpse(target, (x, y) => meatVision.isVisible(x, y));
         }
       }),
diff --git a/src/shell/shellRuntime.ts b/src/shell/shellRuntime.ts
index c430735..d5162d1 100644
--- a/src/shell/shellRuntime.ts
+++ b/src/shell/shellRuntime.ts
@@ -68,7 +68,7 @@ import {
 } from '/src/game/hub/hubReveals.js';
 import type { Crew } from '/src/game/Crew.js';
 import { resolveEntityLabel, type Entity } from '/src/game/Entity.js';
-import type { RunResult, RunTelemetry, Outcome } from '/src/game/Run.js';
+import type { JackOutRequest, RunResult, RunTelemetry, Outcome } from '/src/game/Run.js';
 import type { Item } from '/src/game/items.js';
 import type { Intent } from '/src/input/applyIntent.js';
 import type { AimKind } from '/src/input/keymap.js';
@@ -273,6 +273,7 @@ function showBreachBlastOverlay(cx: number, cy: number): void {
  */
 let actionLineHistory: string[] = [];
 let pendingActionLineCount = 0;
+let priorityFlashLine: string | null = null;
 let lookCursor: { x: number; y: number } | null = null;
 
 /**
@@ -1202,11 +1203,8 @@ function wireRunConfirmations(run: Run): void {
       'abort-run'
     );
   };
-  run.onJackOutRequested = () => {
-    confirmationModalEl.showModal(
-      'Objective incomplete. Jack out anyway?\n\nThe link will burn — you cannot re-enter the grid this run.',
-      'jack-out-early'
-    );
+  run.onJackOutRequested = request => {
+    confirmationModalEl.showModal(jackOutConfirmationCopy(request), 'jack-out-early');
   };
   run.onJackInPresent = () => {
     sceneListenerController.rewire();
@@ -1227,6 +1225,22 @@ function wireRunConfirmations(run: Run): void {
   };
 }
 
+function jackOutConfirmationCopy(request: JackOutRequest): string {
+  if (request.reason === 'explicit-key') {
+    const objectiveLine = request.objectiveComplete
+      ? 'Cyberspace objective is complete.'
+      : 'Cyberspace objective is incomplete and will fail.';
+    return (
+      `Emergency jack-out?\n\n${objectiveLine}\n` +
+      `The link will burn and neural shock will deal ${request.shockDamage} HP.`
+    );
+  }
+  return (
+    'Objective incomplete. Jack out anyway?\n\n' +
+    'The link will burn — you cannot re-enter the grid this run.'
+  );
+}
+
 function resumeCampaign(record: CampaignSnapshot | unknown) {
   try {
     campaign = restoreCampaign(record, {
@@ -1579,6 +1593,9 @@ export function handleIntent(intent: Intent): void {
         case PLAYER_ACTIONS.INTERACT:
           handleInteract();
           break;
+        case PLAYER_ACTIONS.JACK_OUT:
+          handleExplicitJackOut(run as Run);
+          break;
         case PLAYER_ACTIONS.REACHED_EXIT:
           if (campaign?.state === CAMPAIGN_STATE.HUB) {
             flash('Curator: Hang tight! Come talk to me to claim a contract.');
@@ -1946,6 +1963,14 @@ function handleInteract(): void {
   presentContractSelect(currentJobOptions);
 }
 
+function handleExplicitJackOut(run: Run): void {
+  if (run.state !== RUN_STATE.COMBAT || run.cyberspace?.phase !== 'active') {
+    flash('No active Cyberspace link to jack out from.');
+    return;
+  }
+  run.requestJackOut();
+}
+
 /**
  * Combat interact — scan Chebyshev-adjacent tiles for a lootable corpse.
  * If found: call `player.collectSalvage`, flash result, auto-end turn on AP
@@ -2102,7 +2127,7 @@ function rewireSceneListeners(): void {
 function completeJackOutShellSwap(): void {
   sceneListenerController.detachCyber();
   pipCanvas.hidden = true;
-  flash('LINK DROPPED — back in your body.');
+  flash('LINK DROPPED — back in your body.', { priority: true });
   recomputeVision();
   paint();
 }
@@ -2324,6 +2349,7 @@ function statusLine(state: InputState): string {
     latchedCorpMood,
     actionHistory: actionLineHistory,
     pendingActionCount: pendingActionLineCount,
+    priorityFlash: priorityFlashLine,
   });
   if (nextCorpMoodBody !== null) {
     corpToneActivityBody = nextCorpMoodBody;
@@ -2397,13 +2423,19 @@ function proximityHint(): string {
 }
 
 /** Stash a one-shot message that the next paint surfaces in the status bar. */
-function flash(line: string): void {
+function flash(line: string, opts: { priority?: boolean } = {}): void {
   const scene = currentScene();
   if (scene?.state === RUN_STATE.COMBAT && scene.queue?.currentFaction === FACTION.PLAYER) {
     corpToneActivityBody = null;
+    if (!opts.priority) {
+      priorityFlashLine = null;
+    }
   }
   actionLineHistory = recordStatusActionLine(actionLineHistory, line);
   pendingActionLineCount = Math.min(pendingActionLineCount + 1, actionLineHistory.length);
+  if (opts.priority) {
+    priorityFlashLine = actionLineHistory[0] ?? line;
+  }
   const currentActionLine = actionLineHistory[0] ?? '';
   if (currentActionLine) {
     logLines.unshift(`> ${currentActionLine}`);
diff --git a/src/shell/statusLine.ts b/src/shell/statusLine.ts
index ac554b1..1c34b2e 100644
--- a/src/shell/statusLine.ts
+++ b/src/shell/statusLine.ts
@@ -33,6 +33,7 @@ export type StatusLineSnapshot = {
   latchedCorpMood?: CorpMoodSnapshot | null;
   actionHistory: readonly string[];
   pendingActionCount: number;
+  priorityFlash?: string | null;
 };
 
 export type StatusLineResult = {
@@ -127,10 +128,14 @@ export function formatStatusLine(snapshot: StatusLineSnapshot): StatusLineResult
   const activityRows = statusActionRows(
     snapshot.actionHistory,
     snapshot.pendingActionCount,
-    !!ephemeral
+    !!ephemeral,
+    snapshot.priorityFlash ?? null
   );
   const [upper, lower] = activityRows.map(row => {
     if (row.source === 'ephemeral') return ephemeral;
+    if (row.source === 'priority') {
+      return `<span class="game-shell__activity priority">${escapeHtml(row.text)}</span>`;
+    }
     return `<span class="game-shell__activity">${escapeHtml(row.text)}</span>`;
   });
 
diff --git a/src/statusActivityRows.ts b/src/statusActivityRows.ts
index 63d9533..8e14479 100644
--- a/src/statusActivityRows.ts
+++ b/src/statusActivityRows.ts
@@ -1,7 +1,7 @@
 export const STATUS_ACTION_HISTORY_LIMIT = 3;
 
 export type StatusActivityRow = {
-  source: 'action' | 'ephemeral';
+  source: 'action' | 'ephemeral' | 'priority';
   text: string;
 };
 
@@ -17,8 +17,19 @@ export function recordStatusActionLine(
 export function statusActionRows(
   history: readonly string[],
   pendingCount: number,
-  hasEphemeral: boolean
+  hasEphemeral: boolean,
+  priorityLine: string | null = null
 ): [StatusActivityRow, StatusActivityRow] {
+  if (priorityLine) {
+    const latestNonPriority = history.find(line => line !== priorityLine) ?? '';
+    return [
+      hasEphemeral
+        ? { source: 'ephemeral', text: '' }
+        : { source: 'action', text: latestNonPriority },
+      { source: 'priority', text: priorityLine },
+    ];
+  }
+
   const pending = history.slice(0, Math.max(0, pendingCount)).reverse();
   if (pending.length >= 2) {
     return [
diff --git a/tests/unit/game/cyber/jackOut.test.ts b/tests/unit/game/cyber/jackOut.test.ts
index 00c948c..0d7bd0b 100644
--- a/tests/unit/game/cyber/jackOut.test.ts
+++ b/tests/unit/game/cyber/jackOut.test.ts
@@ -9,6 +9,7 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 
+import { JACK_OUT_SHOCK_DAMAGE } from '../../../../src/game/constants.js';
 import { Run } from '../../../../src/game/Run.js';
 import { CyberspaceLayer } from '../../../../src/game/cyber/CyberspaceLayer.js';
 import { DataNode } from '../../../../src/game/cyber/DataNode.js';
@@ -16,11 +17,12 @@ import { JackInPoint } from '../../../../src/game/entities/JackInPoint.js';
 import { snapshot, restore } from '../../../../src/game/persistence.js';
 import { buildCrewMember } from '../../../../src/game/archetypes/index.js';
 import { OBJECTIVES } from '../../../../src/game/hub/Curator.js';
+import { EVENT } from '../../../../src/game/events.js';
 import { Rng } from '../../../../src/rng.js';
 import { testContractContext } from '../contractTestUtils.js';
 import type { World } from '../../../../src/game/World.js';
 import type { Entity } from '../../../../src/game/Entity.js';
-import type { RunEntitySnapshot, RunSnapshot } from '../../../../src/game/Run.js';
+import type { JackOutRequest, RunEntitySnapshot, RunSnapshot } from '../../../../src/game/Run.js';
 
 const cyberContract = (seed = 12345) => ({
   seed,
@@ -41,6 +43,10 @@ function makeDecker() {
   return buildCrewMember('decker', { x: 0, y: 0 }, new Rng(100), { id: 'crew-decker' });
 }
 
+function makeMerc() {
+  return buildCrewMember('merc', { x: 0, y: 0 }, new Rng(101), { id: 'crew-merc' });
+}
+
 function adjacentFreeTile(world: World, target: Entity) {
   for (let dy = -1; dy <= 1; dy++) {
     for (let dx = -1; dx <= 1; dx++) {
@@ -62,6 +68,13 @@ function combatRun(seed = 12345) {
   return run;
 }
 
+function dualCombatRun(seed = 12345) {
+  const run = new Run({ crewMember: makeDecker(), partnerMember: makeMerc(), seed });
+  run.enterBriefing(cyberContract(seed));
+  run.enterCombat();
+  return run;
+}
+
 function meatPort(run: Run): JackInPoint {
   const point = Array.from(run.world!.entities.values()).find(e => e instanceof JackInPoint);
   assert.ok(point, 'cyber contract placed a jack-in point');
@@ -96,6 +109,18 @@ function sliceAllNodes(layer: CyberspaceLayer): void {
   }
 }
 
+function damageBody(run: Run, amount: number): void {
+  const body = run.player!;
+  const damage = body.damage(amount);
+  run.world!.events!.emit(EVENT.ENTITY_DAMAGED, {
+    attacker: null,
+    target: body,
+    damage,
+    killed: !body.alive,
+    source: 'test-body-hit',
+  });
+}
+
 function portRecord(record: RunSnapshot): RunEntitySnapshot {
   const rec = record.entities.find(e => e.archetype === 'jack-in-point');
   assert.ok(rec, 'snapshot carries the jack-in point');
@@ -234,6 +259,8 @@ test('confirmJackOut with no jack-out pending throws (dormant and resolved)', ()
   assert.throws(() => run.confirmJackOut(), /pending/);
 
   const layer = jackIn(run);
+  assert.throws(() => run.confirmJackOut(), /pending/);
+
   routeOut(layer); // no callback → resolves immediately
   assert.equal(run.cyberspace?.phase, 'resolved');
   assert.throws(() => run.confirmJackOut(), /pending/);
@@ -250,6 +277,153 @@ test('a pending jack-out confirmation persists as a live layer', () => {
   assert.equal(meatPort(restored).burned, false);
 });
 
+// --- explicit jack-out key (P3.M4 gap closeout) ---------------------------------------
+
+test('explicit jack-out defers for neural shock even after the objective is complete', () => {
+  const run = combatRun();
+  const layer = jackIn(run);
+  sliceAllNodes(layer);
+  const body = run.player!;
+  const requests: JackOutRequest[] = [];
+  run.onJackOutRequested = request => requests.push(request);
+
+  run.requestJackOut();
+
+  assert.equal(run.cyberspace?.phase, 'active', 'link stays live pending confirmation');
+  assert.equal(body.hp, body.maxHp, 'shock is not applied before confirmation');
+  assert.deepEqual(requests, [
+    {
+      reason: 'explicit-key',
+      objectiveComplete: true,
+      shockDamage: JACK_OUT_SHOCK_DAMAGE,
+    },
+  ]);
+
+  run.confirmJackOut();
+  assert.equal(run.cyberspace?.phase, 'resolved');
+  assert.equal((run.cyberspace as { objectiveComplete?: boolean }).objectiveComplete, true);
+  assert.equal(body.hp, body.maxHp - JACK_OUT_SHOCK_DAMAGE);
+  assert.equal(meatPort(run).burned, true);
+});
+
+test('explicit jack-out works while controlling the meat partner and fails unfinished objective', () => {
+  const run = dualCombatRun();
+  jackIn(run);
+  assert.equal(run.activeLayer, 'meat', 'dual-deploy jack-in leaves control in Meatspace');
+  const body = run.player!;
+  run.onJackOutRequested = () => {};
+
+  run.requestJackOut();
+  run.confirmJackOut();
+
+  assert.equal(run.cyberspace?.phase, 'resolved');
+  assert.equal((run.cyberspace as { objectiveComplete?: boolean }).objectiveComplete, false);
+  assert.equal(body.hp, body.maxHp - JACK_OUT_SHOCK_DAMAGE);
+  assert.equal(run.activeLayer, 'meat');
+  assert.equal(run.meatActor, body);
+  assert.equal(body.frozen, false);
+  assert.equal(meatPort(run).burned, true);
+});
+
+test('confirmed explicit jack-out can flatline a critically wounded Decker', () => {
+  const run = combatRun();
+  jackIn(run);
+  const body = run.player!;
+  body.hp = JACK_OUT_SHOCK_DAMAGE - 1;
+  let result: unknown = null;
+  run.onResult = value => {
+    result = value;
+  };
+  run.onJackOutRequested = () => {};
+
+  run.requestJackOut();
+  run.confirmJackOut();
+
+  assert.equal(run.state, 'RESULT');
+  assert.equal(body.alive, false);
+  assert.equal(body.hp, 0);
+  assert.equal(run.cyberspace?.phase, 'resolved', 'link still drops before shock death resolves');
+  assert.equal(meatPort(run).burned, true);
+  assert.deepEqual(result, {
+    outcome: 'death',
+    telemetry: {
+      ...run.telemetry,
+      outcome: 'death',
+      hpAtDeath: 0,
+      lastDamageSource: 'neural-shock',
+      lastAttacker: null,
+      hpAtDamage: 0,
+      cause: `neural-shock(${JACK_OUT_SHOCK_DAMAGE - 1})`,
+    },
+  });
+});
+
+// --- forced jack-out (P3.M4.6) ---------------------------------------------------------
+
+test('body damage to 1 HP forces jack-out without early-jack-out confirmation', () => {
+  const run = dualCombatRun();
+  jackIn(run);
+  run.flip(); // view Cyberspace, leaving the body in the meat feed.
+  const body = run.player!;
+  body.hp = 2;
+  let requests = 0;
+  run.onJackOutRequested = () => requests++;
+
+  damageBody(run, 1);
+
+  assert.equal(requests, 0, 'forced jack-out never asks for early-jack-out confirmation');
+  assert.equal(run.cyberspace?.phase, 'resolved');
+  assert.equal((run.cyberspace as { objectiveComplete?: boolean }).objectiveComplete, false);
+  assert.equal(body.alive, true);
+  assert.equal(body.hp, 1);
+  assert.equal(body.frozen, false);
+  assert.equal(run.activeLayer, 'meat');
+  assert.equal(run.meatActor, body);
+  assert.equal(meatPort(run).burned, true);
+  assert.equal(run.canFlip(), true, 'post-jack-out control can still flip to the living partner');
+});
+
+test('lethal body damage while jacked in clamps the Decker alive and round-trips', () => {
+  const run = dualCombatRun();
+  jackIn(run);
+  const body = run.player!;
+  body.hp = 1;
+  let results = 0;
+  run.onResult = () => results++;
+
+  damageBody(run, body.maxHp);
+
+  assert.equal(results, 0, 'forced jack-out is not a run death');
+  assert.equal(run.state, 'COMBAT');
+  assert.equal(body.alive, true);
+  assert.equal(body.hp, 1);
+  assert.equal(run.cyberspace?.phase, 'resolved');
+
+  const { run: restored } = restore(structuredClone(snapshot(run)));
+  assert.equal(restored.cyberspace?.phase, 'resolved');
+  assert.equal((restored.cyberspace as { objectiveComplete?: boolean }).objectiveComplete, false);
+  assert.equal(restored.player!.alive, true);
+  assert.equal(restored.player!.hp, 1);
+  assert.equal(restored.player!.frozen, false);
+  assert.equal(restored.meatActor, restored.player);
+  assert.equal(meatPort(restored).burned, true);
+});
+
+test('forced jack-out after all nodes are sliced preserves the completed objective latch', () => {
+  const run = dualCombatRun();
+  const layer = jackIn(run);
+  sliceAllNodes(layer);
+  const body = run.player!;
+  body.hp = 1;
+
+  damageBody(run, body.maxHp);
+
+  assert.equal(run.cyberspace?.phase, 'resolved');
+  assert.equal((run.cyberspace as { objectiveComplete?: boolean }).objectiveComplete, true);
+  assert.equal(body.alive, true);
+  assert.equal(body.hp, 1);
+});
+
 // --- persistence ----------------------------------------------------------------------
 
 test('the burned latch round-trips and the restored port stays dead', () => {
diff --git a/tests/unit/input/applyIntent.test.ts b/tests/unit/input/applyIntent.test.ts
index 1de3004..f4b7b0c 100644
--- a/tests/unit/input/applyIntent.test.ts
+++ b/tests/unit/input/applyIntent.test.ts
@@ -69,6 +69,7 @@ function buildCtx({ archetype = 'merc', placeDrone = true } = {}) {
     resetInputModes: 0,
     interact: 0,
     inventory: 0,
+    jackOut: 0,
     reachedExit: 0,
     corpseSalvaged: 0,
     securedInteract: 0,
@@ -101,6 +102,9 @@ function buildCtx({ archetype = 'merc', placeDrone = true } = {}) {
         case PLAYER_ACTIONS.INVENTORY:
           calls.inventory++;
           break;
+        case PLAYER_ACTIONS.JACK_OUT:
+          calls.jackOut++;
+          break;
         default:
           throw new Error(`Unknown player action: ${actionName}`);
       }
@@ -560,6 +564,18 @@ test('interact intent crashes when ctx.onPlayerAction is missing (no silent no-o
   assert.throws(() => applyIntent({ type: 'interact' }, ctx), /onPlayerAction is missing/);
 });
 
+test('jack-out intent fires the shell-supplied onPlayerAction callback once', () => {
+  const { ctx, calls } = buildCtx();
+  applyIntent({ type: 'jack-out' }, ctx);
+  assert.equal(calls.jackOut, 1);
+});
+
+test('jack-out intent crashes when ctx.onPlayerAction is missing (no silent no-op)', () => {
+  const { ctx } = buildCtx();
+  delete ctx.onPlayerAction;
+  assert.throws(() => applyIntent({ type: 'jack-out' }, ctx), /onPlayerAction is missing/);
+});
+
 test('use-item intent forwards a validated aim direction to the shell', () => {
   const { ctx } = buildCtx();
   const aims = [];
diff --git a/tests/unit/input/keyHelp.test.ts b/tests/unit/input/keyHelp.test.ts
index 5552369..fb5311b 100644
--- a/tests/unit/input/keyHelp.test.ts
+++ b/tests/unit/input/keyHelp.test.ts
@@ -97,6 +97,7 @@ test('drift guard: every key handled by keymap.js dispatch appears in HELP_ROWS'
     'i',
     'l',
     'Tab',
+    'j',
     // system
     '.',
     'Escape',
diff --git a/tests/unit/input/keymap.test.ts b/tests/unit/input/keymap.test.ts
index da8486a..2a4b947 100644
--- a/tests/unit/input/keymap.test.ts
+++ b/tests/unit/input/keymap.test.ts
@@ -183,6 +183,12 @@ test('IDLE + i emits inventory intent (M4)', () => {
   assert.equal(r.nextMode, MODE.IDLE);
 });
 
+test('IDLE + j emits explicit jack-out intent', () => {
+  const r = dispatch('j', MODE.IDLE);
+  assert.deepStrictEqual(r.intent, { type: 'jack-out' });
+  assert.equal(r.nextMode, MODE.IDLE);
+});
+
 test('IDLE + l enters LOOK with no intent yet', () => {
   const r = dispatch('l', MODE.IDLE);
   assert.equal(r.intent, null);
diff --git a/tests/unit/input/touchpad.test.ts b/tests/unit/input/touchpad.test.ts
index c8b2eed..d9ff3c4 100644
--- a/tests/unit/input/touchpad.test.ts
+++ b/tests/unit/input/touchpad.test.ts
@@ -21,6 +21,7 @@ test('TOUCHPAD_ACTIONS includes gameplay actions (perks unified as `special`)',
     'fire',
     'interact',
     'inventory',
+    'jack-out',
     'look',
     'special',
   ]);
@@ -44,6 +45,7 @@ test('syntheticKeyFor resolves actions to keymap keys', () => {
   assert.equal(syntheticKeyFor('cancel'), 'Escape');
   assert.equal(syntheticKeyFor('interact'), ' ');
   assert.equal(syntheticKeyFor('inventory'), 'i');
+  assert.equal(syntheticKeyFor('jack-out'), 'j');
   assert.equal(syntheticKeyFor('look'), 'l');
 });
 
@@ -134,6 +136,12 @@ test('IDLE + look button enters LOOK mode', () => {
   assert.equal(r.nextMode, MODE.LOOK);
 });
 
+test('IDLE + jack-out button emits jack-out intent', () => {
+  const r = dispatchTouchAction('jack-out', MODE.IDLE);
+  assert.deepEqual(r.intent, { type: 'jack-out' });
+  assert.equal(r.nextMode, MODE.IDLE);
+});
+
 test('LOOK + direction emits a look-move intent', () => {
   const r = dispatchTouchAction('N', MODE.LOOK);
   assert.deepEqual(r.intent, { type: 'look-move', dx: 0, dy: -1 });
diff --git a/tests/unit/shell/sceneListeners.test.ts b/tests/unit/shell/sceneListeners.test.ts
index 6505d88..cd70a30 100644
--- a/tests/unit/shell/sceneListeners.test.ts
+++ b/tests/unit/shell/sceneListeners.test.ts
@@ -120,3 +120,53 @@ test('P3.M4.5: meat body damage flashes the PIP only while viewing Cyberspace',
   assert.equal(pipPaints, 1);
   assert.equal(flashes.length, 1);
 });
+
+test('P3.M4.6: forced jack-out body repair is not memorised as a meat corpse', () => {
+  const bus = new EventBus();
+  const body = { id: 'body', x: 3, y: 4, hp: 1, maxHp: 8, alive: true };
+  const scene = {
+    bus,
+    world: { entities: new Map() },
+    player: body,
+    archetype: 'decker',
+    cyberspace: { phase: 'resolved', objectiveComplete: false },
+    activeLayer: 'meat',
+    state: 'combat',
+  } as unknown as ShellScene;
+
+  let memorised = 0;
+  const fakeClassList = { remove: () => {}, add: () => {}, toggle: () => {} };
+  const controller = new SceneListenerController({
+    getScene: () => scene,
+    getCampaign: () => null,
+    getMeatVision: () => new VisionField(),
+    getCyberVision: () => new VisionField(),
+    resetCyberVision: () => new VisionField(),
+    dom: {
+      stageEl: { classList: fakeClassList, offsetWidth: 0 } as unknown as HTMLElement,
+      pipCanvas: { classList: fakeClassList, offsetWidth: 0 } as unknown as HTMLCanvasElement,
+    },
+    renderers: { main: {} as never, pip: {} as never },
+    animLock: { push: () => {} },
+    effects: {
+      flash: () => {},
+      paint: () => {},
+      paintPip: () => {},
+      recomputeVision: () => {},
+    },
+    onCivilianHarmReset: () => {},
+    onCivilianHarmed: () => {},
+    onRepAdjust: () => {},
+    onAlarmTransition: () => {},
+    onObjectiveTimerExpired: () => {},
+    memoriseMeatCorpse: () => {
+      memorised++;
+    },
+    memoriseCyberCorpse: () => {},
+  });
+  controller.rewire();
+
+  bus.emit(EVENT.ENTITY_DAMAGED, { target: body, damage: 1, killed: true });
+
+  assert.equal(memorised, 0);
+});
diff --git a/tests/unit/shell/statusLine.test.ts b/tests/unit/shell/statusLine.test.ts
index d9cbeac..1906926 100644
--- a/tests/unit/shell/statusLine.test.ts
+++ b/tests/unit/shell/statusLine.test.ts
@@ -116,6 +116,26 @@ test('formatStatusLine latches corp mood on player slice', () => {
   assert.equal(playerSlice.nextCorpMoodBody, null);
 });
 
+test('formatStatusLine renders priority flash below newer ordinary action lines', () => {
+  const { html } = formatStatusLine({
+    stateLabel: '[COMBAT]',
+    sceneState: RUN_STATE.COMBAT,
+    input: { mode: MODE.IDLE, aimKind: null },
+    hasPlayer: true,
+    hasQueue: true,
+    contextHtml: '',
+    actionHistory: [
+      '[Sable]Vault Security strikes Blitz - HIT.',
+      'LINK DROPPED - back in your body.',
+    ],
+    pendingActionCount: 2,
+    priorityFlash: 'LINK DROPPED - back in your body.',
+  });
+
+  assert.match(html, /Security strikes Blitz/);
+  assert.match(html, /priority.*LINK DROPPED/);
+});
+
 test('hostileMoodTag reads ICE while jacked in', () => {
   assert.equal(hostileMoodTag(true, FACTION.RIVAL), 'ICE');
   assert.equal(hostileMoodTag(false, FACTION.RIVAL), 'RIVAL');
diff --git a/tests/unit/statusActivityRows.test.ts b/tests/unit/statusActivityRows.test.ts
index 0fe89b4..cb3590e 100644
--- a/tests/unit/statusActivityRows.test.ts
+++ b/tests/unit/statusActivityRows.test.ts
@@ -39,3 +39,25 @@ test('statusActionRows lets a single fresh action share the HUD with an ephemera
     { source: 'action', text: 'Access terminal sliced.' },
   ]);
 });
+
+test('statusActionRows keeps a priority transition visible under later combat lines', () => {
+  let history: string[] = [];
+  history = recordStatusActionLine(history, 'LINK DROPPED - back in your body.');
+  history = recordStatusActionLine(history, '[Sable]Vault Security strikes Blitz - HIT.');
+
+  assert.deepEqual(statusActionRows(history, 2, false, 'LINK DROPPED - back in your body.'), [
+    { source: 'action', text: '[Sable]Vault Security strikes Blitz - HIT.' },
+    { source: 'priority', text: 'LINK DROPPED - back in your body.' },
+  ]);
+});
+
+test('statusActionRows lets proximity hints sit above a priority transition', () => {
+  let history: string[] = [];
+  history = recordStatusActionLine(history, 'LINK DROPPED - back in your body.');
+  history = recordStatusActionLine(history, '[Sable]Vault Security strikes Blitz - HIT.');
+
+  assert.deepEqual(statusActionRows(history, 2, true, 'LINK DROPPED - back in your body.'), [
+    { source: 'ephemeral', text: '' },
+    { source: 'priority', text: 'LINK DROPPED - back in your body.' },
+  ]);
+});

From b336aff343ee369ebfd4f683459f0e972a0a3c33 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Wed, 24 Jun 2026 22:03:18 -0700
Subject: [PATCH 47/55] the score (mvp)

---
 components/ContractSelect.ts            |  13 +-
 components/GameOver.ts                  |   6 +-
 docs/phase-3-plan.md                    |  34 ++--
 src/game/Campaign.ts                    |  42 ++++-
 src/game/Run.ts                         | 214 +++++++++++++++++++++-
 src/game/campaignSummary.ts             |  17 +-
 src/game/cyber/DataNode.ts              |   4 +-
 src/game/events.ts                      |   2 +
 src/game/hub/Curator.ts                 |  19 +-
 src/game/hub/arcSurface.ts              |  43 +++++
 src/game/objectiveProgress.ts           |   4 +
 src/game/persistence.ts                 |  78 +++++++-
 src/types.ts                            |   1 +
 tests/unit/game/Campaign.test.ts        |  33 ++--
 tests/unit/game/campaignSummary.test.ts |  16 +-
 tests/unit/game/hub/arcSurface.test.ts  |  49 +++++
 tests/unit/game/scoreFinal.test.ts      | 234 ++++++++++++++++++++++++
 17 files changed, 746 insertions(+), 63 deletions(-)
 create mode 100644 tests/unit/game/scoreFinal.test.ts

diff --git a/components/ContractSelect.ts b/components/ContractSelect.ts
index 6220fcb..db097e4 100644
--- a/components/ContractSelect.ts
+++ b/components/ContractSelect.ts
@@ -6,7 +6,7 @@
 
 import { h } from '/src/domUtils.js';
 import { encounterHostileCount } from '/src/game/encounters.js';
-import { isScorePrincipalContract, isScoreSiteContract } from '/src/game/hub/arcSurface.js';
+import { contractLocationBadges } from '/src/game/hub/arcSurface.js';
 import { cloneObjective } from '/src/game/hub/Curator.js';
 import type { Contract } from '/src/game/hub/Curator.js';
 
@@ -406,16 +406,13 @@ function locationLine(
   scoreTargetSiteId: string | null,
   scorePrincipalId: string | null
 ): HTMLElement[] {
-  const { principal, site, siteState, locationSiteId } = contract.context;
+  const { principal, site, siteState } = contract.context;
   const place = site ? `${principal.label} ${site.label}` : principal.label;
   const state = siteState ? ` [${siteState.label}]` : '';
   const nodes: HTMLElement[] = [h('span', { textContent: `Location: ${place}${state}` })];
-  if (isScoreSiteContract(contract, scoreTargetSiteId)) {
-    nodes.push(h('span', { className: 'known score-site', textContent: 'SCORE SITE' }));
-  } else if (isScorePrincipalContract(contract, scorePrincipalId, scoreTargetSiteId)) {
-    nodes.push(h('span', { className: 'known casing', textContent: 'CASING' }));
-  } else if (locationSiteId) {
-    nodes.push(h('span', { className: 'known', textContent: '// known site' }));
+  for (const badge of contractLocationBadges(contract, scoreTargetSiteId, scorePrincipalId)) {
+    const className = badge.variant === 'revisit' ? 'known' : `known ${badge.variant}`;
+    nodes.push(h('span', { className, textContent: badge.text }));
   }
   return nodes;
 }
diff --git a/components/GameOver.ts b/components/GameOver.ts
index fe06edb..2c5acb0 100644
--- a/components/GameOver.ts
+++ b/components/GameOver.ts
@@ -207,6 +207,7 @@ function hexSeed(seed: number): string {
 
 function reasonCopy(summary: CampaignSummary): string {
   if (summary.result === 'win') return 'The Score is complete.';
+  if (summary.result === 'partial') return 'The Score is compromised.';
   if (summary.endReason === 'clock-expired') return 'The Score window closed.';
   if (summary.endReason === 'decker-flatlined-score') {
     return 'The Decker flatlined during the Score.';
@@ -218,11 +219,14 @@ function detailCopy(summary: CampaignSummary): string {
   if (summary.result === 'win') {
     return 'Target data secured. The crew beat the window and closed the campaign on their terms.';
   }
+  if (summary.result === 'partial') {
+    return 'Someone made it out, but the finale broke before the crew could clear the target cleanly.';
+  }
   if (summary.endReason === 'clock-expired') {
     return 'Corp security caught up. The contract is cold and this campaign is over.';
   }
   if (summary.endReason === 'decker-flatlined-score') {
-    return 'The intrusion channel is gone. Until dual-deploy exists, nobody can finish the Score.';
+    return 'The intrusion channel is gone. Nobody can finish the Score.';
   }
   return 'Every crew slot on the roster is flatlined. Their campaign ends here.';
 }
diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 66a7a3b..e3c8e49 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -45,7 +45,7 @@ A new **player archetype** recruited mid-campaign (late Act 1 / start of Act 2),
 | P3.M2 — The Decker archetype | ✅ Done |
 | P3.M3 — Cyberspace grid + ICE | ✅ Done (full ICE roster: Probe, Spark, Guardian) |
 | P3.M4 — Simstim flip (dual-deploy) | ✅ Done |
-| P3.M5 — The Score (climactic mission) | 🔲 Planned |
+| P3.M5 — The Score (climactic mission) | ✅ Done |
 | P3.M6 — Chronicle (campaign narrative memory) | 🟡 End-summary foundation shipped |
 
 **Phase 3** is complete when:
@@ -214,7 +214,7 @@ Neural degradation is deferred until Cyberspace is fun enough to deserve a jack-
 2. **Minimal voluntary jack-out pulled forward** from P3.M4.6 so the layer is playable end-to-end solo before the simstim flip exists. M4.6 then only adds forced jack-out + dual-deploy cleanup.
 3. **Avatar death = flatline** — ICE destroying the avatar kills the Decker through the existing DEATH/flatline paths. Genre-honest (black ICE kills), zero new death machinery.
 4. **Named cyber stats ship now with real effects:** RAM = avatar HP pool, intrusion strength = slice progress per interact, ICE resistance = `damageReduction` (existing min-1 mitigation in `Combat.ts`). Persisted and validated in both crew persistence paths.
-5. **The Score is always a cyber run** (2026-06-11): `buildScoreContract` emits `DATA_NODE_SLICE` with `{requiresCyberspace: true, count: 1}` — for now; revisit if a meat-only Score variant is ever wanted. Deploy goes through the living-Decker gate; objective shape locked in the P3.M1.7 tests.
+5. **The Score is always a cyber run** (2026-06-11, superseded by P3.M5): `buildScoreContract` now emits `SCORE_FINAL` with `{requiresCyberspace: true, count: 1, doorId: 'score-door-0'}`. Deploy goes through the living-Decker gate and, for the finale only, requires a living non-Decker meat partner at the model layer.
 
 TDD throughout; malformed persisted state throws (no silent fallbacks).
 
@@ -309,7 +309,7 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 
 ---
 
-### P3.M4 — Simstim flip (dual-deploy) 🟡
+### P3.M4 — Simstim flip (dual-deploy) ✅
 
 **Depends on:** P3.M2 (Decker), P3.M3 (Cyberspace grid). This is the integration milestone.
 
@@ -384,30 +384,36 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 
 ---
 
-### P3.M5 — The Score (climactic mission) 🔲
+### P3.M5 — The Score (climactic mission) ✅
 
 **Depends on:** P3.M1 (arc structure), P3.M4 (simstim flip), P2.5.M7 (location persistence for the target site).
 
 **Goal:** The **climactic dual-layer mission** that the entire campaign builds toward. The Score is a contract at the designated target site, requiring both Meatspace breach and Cyberspace penetration to complete.
 
+**Status (2026-06-20):** Complete for the M5 scope. The finale ships as one linked Cyberspace core node and one locked Meatspace route/payload pair, with independent operative extraction and terminal win/partial/loss campaign outcomes. The schema remains open for future multiple node/lock pairs, but M5 deliberately ships exactly one pair.
+
 **Scope:**
 
-- **Score contract:** A special contract type (or recipe) that is only available in Act 3 when the player chooses to attempt it. Not randomly rolled — player-initiated from the Hub.
+- **Score contract:** A special `score-final` objective emitted by `Campaign.buildScoreContract()` only when Act 3 Score gates pass. It is not randomly rolled — player-initiated from the Hub — and it uses the persisted Score target site's dimensions, breach deltas, seen tiles, and site memory.
 - **Dual objectives:** The Score has objectives in **both** layers:
-  - **Meatspace:** Breach the target site (using P2.5.M7 pre-made breaches + new ones), reach the objective room, protect the Decker's body, extract.
-  - **Cyberspace:** Penetrate the target's digital defenses (ICE gauntlet), disable core security (opens physical locks/routes for the Meatspace operator), extract the target data/asset.
-  - Both must be satisfied for a clean completion. Partial completion (one layer only) = partial payout or narrative consequence (TBD).
+  - **Meatspace:** Reach the locked Score route, enter the objective room after the core unlock, secure the Score payload, protect the Decker's body, and extract both deployed operatives.
+  - **Cyberspace:** Jack in, slice the single Score core data node, and jack out or continue coordinating the Meatspace finish.
+  - Both layer objectives plus both deployed operatives extracting alive are required for clean completion. Confirmed early/one-layer extraction is terminal partial completion, not a retry path.
 - **Site knowledge payoff:** The target site uses P2.5.M7's persistent geometry. Every prior visit's breaches, mapped rooms, and learned patrol routes carry over. The player who cased the site thoroughly has a significant advantage.
 - **Escalated difficulty:** The Score is harder than any normal contract — more hostiles, tighter turn budget, more ICE, higher stakes. Failure = campaign loss (crew wipe or objective irrecoverably failed).
-- **Narrative climax:** The Score's briefing, objective copy, and completion text reflect the campaign's arc. The chronicle (P3.M6) records the outcome as the campaign's defining moment.
+- **Independent extraction:** Score runs persist `extractedOperativeIds`. A deployed Meatspace operative who reaches the exit after objectives are complete is marked extracted and removed from active control/targeting; the run continues until the remaining required operative also extracts. Either the meat partner or the Decker body can leave first. Early exit before full objectives uses the existing confirmation path; confirmed extraction ends the campaign as partial.
+- **Terminal outcomes:** Full Score extraction sets `score-complete`, marks the campaign as a win, and awards the full `1,000 Cr` Score payoff. Confirmed partial extraction sets `score-partial`, marks the campaign result as `partial`, and awards no full Score payoff. Decker flatline during the Score remains `decker-flatlined-score`; crew wipe remains terminal loss.
+- **Narrative climax:** The Score's briefing, objective copy, and completion/partial/failure text reflect the campaign's arc. The chronicle (P3.M6) records the outcome as the campaign's defining moment.
+
+**P3.M5 implementation note (2026-06-20):** `OBJECTIVES.SCORE_FINAL` is validated separately from normal `data-node-slice` contracts and requires `requiresCyberspace: true`, a positive `count`, and a stable linked `doorId`. `DataNode` emits `EVENT.DATA_NODE_SLICED`; Score runs listen for that event and unlock the linked Meatspace door once the core node is sliced. Score objective satisfaction is a conjunction of cyber core progress and secured payload state; extraction is a separate requirement handled by `Run.#extractScoreOperative`. Snapshot/restore persists the extracted operative ids plus off-grid extracted operative records so mid-finale saves can restore a partner-first or body-first extraction state without resurrecting the extracted crew onto the grid. `Campaign.onJobEnd` maps incomplete Score exits to `score-partial`, skips the normal abort Rep penalty, and ends the campaign without the Score reward; `buildCampaignSummary` now reports `win | partial | loss`, and `<game-over>` renders distinct compromised-Score copy.
 
 **Acceptance:**
 
-- Score contract available only in Act 3, player-initiated.
-- Dual-layer objectives: Meatspace + Cyberspace both required.
-- Target site uses persistent geometry from prior visits (P2.5.M7 mutations present).
-- Completion = campaign win; failure = campaign loss.
-- Golden-path test: full Score run from deployment through dual-layer completion to extraction.
+- ✅ Score contract available only in Act 3, player-initiated, and gated by living Decker + living non-Decker partner.
+- ✅ Dual-layer objectives: Meatspace payload + Cyberspace core both required for clean completion.
+- ✅ Target site uses persistent geometry from prior visits (P2.5.M7 dimensions, breach deltas, and seen tiles present).
+- ✅ Completion = campaign win with Score reward; confirmed partial = terminal partial result with no full reward; Decker flatline / crew wipe remain campaign loss.
+- ✅ Golden-path and persistence tests cover full Score deployment, linked door unlock, partner-first extraction, mid-Score restore, early partial extraction, campaign partial settlement, and summary/game-over validation.
 
 ---
 
diff --git a/src/game/Campaign.ts b/src/game/Campaign.ts
index 95c66a6..950c26d 100644
--- a/src/game/Campaign.ts
+++ b/src/game/Campaign.ts
@@ -182,7 +182,7 @@ export function willEndCampaignAfterResult(
   }
   if (outcome === OUTCOME.DEATH && willEndCampaignOnThisDeath(campaign)) return true;
   const contract = campaign.activeRun?.contract;
-  if (outcome === OUTCOME.EXIT && completed && contract && isScoreContract(contract)) return true;
+  if (outcome === OUTCOME.EXIT && contract && isScoreContract(contract)) return true;
   return Boolean(
     campaign.arc?.scoreRevealed &&
     clockDeadlineApplies(campaign.arc.arcStage) &&
@@ -375,6 +375,10 @@ export class Campaign {
     return this.crew.some(member => member.archetype === 'Decker' && !member.flatlined);
   }
 
+  get hasLivingScorePartner(): boolean {
+    return this.crew.some(member => member.archetype !== 'Decker' && !member.flatlined);
+  }
+
   get scoreDeadlineJobsRemaining(): number {
     return Math.max(0, CLOCK_ACT2_DEADLINE_JOBS - this.clockJobsTaken);
   }
@@ -383,6 +387,7 @@ export class Campaign {
   get endReason(): CampaignEndReason | null {
     if (this.state !== CAMPAIGN_STATE.ENDED) return null;
     if (this.arc.scoreCompleted) return 'score-complete';
+    if (this.meta.scorePartial === true) return 'score-partial';
     if (this.arc.scoreAttempted && this.arc.arcStage === 'score') {
       return 'decker-flatlined-score';
     }
@@ -499,6 +504,9 @@ export class Campaign {
         `Campaign.deployCrewMember: contract "${contract.label}" requires a living Decker to jack in`
       );
     }
+    if (isScoreContract(contract) && !partnerId) {
+      throw new Error('Campaign.deployCrewMember: THE SCORE requires a living meat partner');
+    }
     // P3.M4.1: a dual-deploy rides a meat partner alongside the Decker. The
     // partner is optional at this layer (the briefing requires one for normal
     // play, but a solo Decker cyber run stays legal); when supplied it must be
@@ -599,6 +607,11 @@ export class Campaign {
       isScoreContract(this.activeRun.contract) &&
       outcome === OUTCOME.EXIT &&
       completed;
+    const partialScoreRun =
+      this.activeRun.contract !== null &&
+      isScoreContract(this.activeRun.contract) &&
+      outcome === OUTCOME.EXIT &&
+      !completed;
     const failedScoreRun =
       this.activeRun.contract !== null &&
       isScoreContract(this.activeRun.contract) &&
@@ -625,7 +638,7 @@ export class Campaign {
         this.credits += reward?.credits ?? 0;
         if (reward) this.adjustRep(reward.repDelta);
         if (reward?.recruit) this.pendingRecruitReward = true;
-      } else {
+      } else if (!partialScoreRun) {
         // Abort extraction: objective abandoned — rep penalty, no rewards.
         this.adjustRep(REP.ABORT_PENALTY);
       }
@@ -653,6 +666,15 @@ export class Campaign {
       return;
     }
 
+    if (partialScoreRun) {
+      this.meta.scorePartial = true;
+      this.arc.arcStage = 'score';
+      this.state = CAMPAIGN_STATE.ENDED;
+      this.#tearDownHubWorld();
+      this.#persist();
+      return;
+    }
+
     if (this.crew.every(member => member.flatlined)) {
       this.state = CAMPAIGN_STATE.ENDED;
       this.#tearDownHubWorld();
@@ -678,6 +700,7 @@ export class Campaign {
     if (this.arc.arcStage !== 'act-3') return false;
     if (this.arc.scoreAttempted || this.arc.scoreCompleted) return false;
     if (!this.hasLivingDecker) return false;
+    if (!this.hasLivingScorePartner) return false;
     return this.#scoreTargetSiteOrNull() !== null;
   }
 
@@ -699,7 +722,8 @@ export class Campaign {
     const principal = locationContextToken(target.principal);
     const site = target.site ? locationContextToken(target.site) : undefined;
     const heatThreat = Math.min(6, 4 + this.clockHeat);
-    const objectiveKind = OBJECTIVES.DATA_NODE_SLICE;
+    const objectiveKind = OBJECTIVES.SCORE_FINAL;
+    const doorId = 'score-door-0';
     return {
       seed,
       mapWidth: target.mapWidth,
@@ -714,6 +738,7 @@ export class Campaign {
         params: {
           requiresCyberspace: true,
           count: 1,
+          doorId,
         },
       },
       difficulty: CONTRACT_DIFFICULTY.CRITICAL,
@@ -725,7 +750,13 @@ export class Campaign {
         ...(site ? { site } : {}),
         asset: { id: 'score-target', label: 'Score target', groups: ['score'] },
         action: { id: 'score-run', label: 'run', groups: ['score'] },
-        tags: ['score', 'meatspace', `objective:${objectiveKind}`, `principal:${principal.id}`],
+        tags: [
+          'score',
+          'meatspace',
+          'cyberspace',
+          `objective:${objectiveKind}`,
+          `principal:${principal.id}`,
+        ],
         arcStage: 'score',
         locationSiteId: target.id,
       },
@@ -1365,6 +1396,9 @@ export class Campaign {
     if (this.arc.scoreCompleted) {
       throw new Error('Campaign.deployCrewMember: Score is already complete');
     }
+    if (contract.objective.kind !== OBJECTIVES.SCORE_FINAL) {
+      throw new Error('Campaign.deployCrewMember: Score contract must use score-final objective');
+    }
     const target = this.#scoreTargetSiteOrNull();
     if (!target || contract.context.locationSiteId !== target.id) {
       throw new Error('Campaign.deployCrewMember: Score contract does not target the Score site');
diff --git a/src/game/Run.ts b/src/game/Run.ts
index 39334c3..1ecf76a 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -299,6 +299,10 @@ export type RunSnapshot = {
   mapMemory?: MapMemorySnapshot;
   /** Pickup unification: removed objective pickups still count as secured. */
   objectiveProgress?: ObjectiveProgressSnapshot;
+  /** P3.M5: Score-only independent extraction latch. */
+  extractedOperativeIds?: string[];
+  /** P3.M5: off-grid crew records for extracted Score operatives. */
+  extractedOperatives?: RunEntitySnapshot[];
   /** Run-scoped key items / keycards without a siteId (P2.5.M6.2). Defaults to []. */
   keyItems?: KeyItemSnapshot[];
   /** Terrain/entity mutations recorded during the run (P2.5.M7.1). Defaults to []. */
@@ -480,6 +484,8 @@ export class Run {
   mapSeen: Set<string>;
   /** Run-scoped key items / keycards without a siteId (P2.5.M6.2). Lost on run end. */
   keyItems: KeyItem[];
+  /** P3.M5: Score-only independent extraction latch. Empty on normal runs. */
+  extractedOperativeIds: Set<string>;
   /** Prior-visit terrain mutations replayed in `enterCombat` (P2.5.M7.2). */
   priorMutationDeltas: TileDelta[];
   /** Prior-visit exploration memory restored into shell fog on jack-in (P2.5.M7.2). */
@@ -576,6 +582,7 @@ export class Run {
     this.objectiveTimer = freshObjectiveTimer();
     this.mapSeen = new Set();
     this.keyItems = [];
+    this.extractedOperativeIds = new Set();
     // Deltas are validated structurally on application (`applyMutationDeltas`)
     // and on campaign restore (`normalizeLocationSite`); store a shallow copy
     // so external mutation can't reach into the run.
@@ -658,13 +665,35 @@ export class Run {
     this.meatActor = this.player;
     this.activeLayer = 'meat';
     this.world.addEntity(this.player);
+    let scoreDoorPlaced = false;
     for (let i = 0; i < map.doors.length; i++) {
       const a = map.doors[i]!;
       // A door breached on a prior visit left its cell as RUBBLE (via the
       // companion tile delta). Skip re-placing the door so the breach persists.
       if (this.world.grid.tileAt(a.x, a.y) === TILE.RUBBLE) continue;
+      const doorId =
+        this.contract.objective.kind === OBJECTIVES.SCORE_FINAL && !scoreDoorPlaced
+          ? scoreDoorId(this.contract)
+          : `door-${i}`;
+      this.world.addEntity(new Door({ id: `door-entity-${i}`, doorId, x: a.x, y: a.y }));
+      if (doorId === scoreDoorIdOrNull(this.contract)) scoreDoorPlaced = true;
+    }
+    if (this.contract.objective.kind === OBJECTIVES.SCORE_FINAL && !scoreDoorPlaced) {
+      const fallback = map.dynamicDoors.find(
+        anchor =>
+          this.world!.grid.isPassable(anchor.door.x, anchor.door.y) &&
+          !this.world!.liveEntityAt(anchor.door.x, anchor.door.y)
+      );
+      if (!fallback) {
+        throw new Error('Run.enterCombat: Score contract has no legal locked-route door anchor');
+      }
       this.world.addEntity(
-        new Door({ id: `door-entity-${i}`, doorId: `door-${i}`, x: a.x, y: a.y })
+        new Door({
+          id: 'door-entity-score',
+          doorId: scoreDoorId(this.contract),
+          x: fallback.door.x,
+          y: fallback.door.y,
+        })
       );
     }
     // Phase 2.9: one hostile faction per run, derived from the contract
@@ -918,6 +947,14 @@ export class Run {
       objectiveTimer: { ...this.objectiveTimer },
       mapMemory: { seen: this.mapSeenKeys() },
       objectiveProgress: { securedPickups: world.securedPickupIds() },
+      ...(this.extractedOperativeIds.size > 0
+        ? {
+            extractedOperativeIds: [...this.extractedOperativeIds].sort(),
+            extractedOperatives: [this.crewMember, this.partnerMember]
+              .filter((crew): crew is Crew => !!crew && this.extractedOperativeIds.has(crew.id))
+              .map(crew => ({ ...snapshotEntity(crew), x: 0, y: 0 })),
+          }
+        : {}),
       keyItems: this.keyItems.map(k => ({ id: k.id, label: k.label, doorId: k.doorId })),
       mutationDeltas: world.mutationDeltas.map(delta => ({ ...delta })),
       // P3.M4.1/M4.2: the reserved meat partner. While the cyber layer is still
@@ -1280,7 +1317,20 @@ export class Run {
       throw new Error('Run.#cyberObjectiveComplete: COMBAT state without a contract');
     }
     const { sliced } = dataNodeProgress(layer.world);
-    return sliced >= objectiveCount(this.contract);
+    const complete = sliced >= objectiveCount(this.contract);
+    if (complete) this.#syncScoreDoorUnlock();
+    return complete;
+  }
+
+  #syncScoreDoorUnlock(): void {
+    if (!this.contract || this.contract.objective.kind !== OBJECTIVES.SCORE_FINAL) return;
+    if (!this.world) return;
+    const cyber = this.#cyberNodeProgress();
+    if (!cyber || cyber.sliced < cyber.required) return;
+    const door = assertDoorExists(this.world, scoreDoorId(this.contract));
+    if (!door.locked) return;
+    door.unlock();
+    this.world.events?.emit(EVENT.DOOR_UNLOCKED, { door, source: 'score-core' });
   }
 
   /**
@@ -1464,7 +1514,12 @@ export class Run {
    */
   #cyberNodeProgress(): CyberNodeProgress | undefined {
     if (!this.contract || !this.cyberspace) return undefined;
-    if (this.contract.objective.kind !== OBJECTIVES.DATA_NODE_SLICE) return undefined;
+    if (
+      this.contract.objective.kind !== OBJECTIVES.DATA_NODE_SLICE &&
+      this.contract.objective.kind !== OBJECTIVES.SCORE_FINAL
+    ) {
+      return undefined;
+    }
     const required = objectiveCount(this.contract);
     switch (this.cyberspace.phase) {
       case 'dormant':
@@ -1611,6 +1666,7 @@ export class Run {
       layer.bus.on(EVENT.ENTITY_DAMAGED, payload =>
         this.#onCyberEntityDamaged(payload as EntityDamagedPayload)
       ),
+      layer.bus.on(EVENT.DATA_NODE_SLICED, () => this.#syncScoreDoorUnlock()),
       layer.bus.on(EVENT.JACK_OUT, () => this.jackOut())
     );
   }
@@ -1735,10 +1791,10 @@ export class Run {
   #onEntityMoved({ entity, to }: EntityMovedPayload): void {
     if (this.state !== RUN_STATE.COMBAT) return;
     if (!this.exitTile) return;
-    if (entity === this.player) {
+    if (entity === this.player || entity === this.partnerMember) {
       this.#recordCurrentPlayerVision();
       if (to.x === this.exitTile.x && to.y === this.exitTile.y) {
-        this.#tryExtractFromExit();
+        this.#tryExtractFromExit(entity as Crew);
       }
       return;
     }
@@ -1751,7 +1807,7 @@ export class Run {
     }
   }
 
-  #tryExtractFromExit(): void {
+  #tryExtractFromExit(actor: Crew = this.player as Crew): void {
     if (!this.contract) {
       throw new Error('Run.#tryExtractFromExit: exit reached without an active contract');
     }
@@ -1770,6 +1826,10 @@ export class Run {
         return;
       }
     }
+    if (this.contract.objective.kind === OBJECTIVES.SCORE_FINAL && objectiveComplete) {
+      this.#extractScoreOperative(actor);
+      return;
+    }
     this.telemetry.cause = objectiveComplete
       ? 'exit-reached'
       : objectiveExpired
@@ -1778,12 +1838,84 @@ export class Run {
     this.enterResult({
       outcome: OUTCOME.EXIT,
       telemetry: {
-        objectiveComplete,
+        objectiveComplete:
+          this.contract.objective.kind === OBJECTIVES.SCORE_FINAL ? false : objectiveComplete,
         objectiveExpired,
       },
     });
   }
 
+  #extractScoreOperative(actor: Crew): void {
+    if (!this.contract || this.contract.objective.kind !== OBJECTIVES.SCORE_FINAL) {
+      throw new Error('Run.#extractScoreOperative: active contract is not the Score');
+    }
+    if (!this.world) {
+      throw new Error('Run.#extractScoreOperative: no live world');
+    }
+    if (this.extractedOperativeIds.has(actor.id)) return;
+    this.extractedOperativeIds.add(actor.id);
+    this.world.removeEntity(actor.id);
+    if (this.meatActor === actor) {
+      this.meatActor = this.#nextScoreMeatActor();
+      if (this.cyberspace?.phase === 'active') {
+        this.activeLayer = 'cyber';
+      }
+    }
+    if (this.player === actor && this.cyberspace?.phase === 'active') {
+      throw new Error('Run.#extractScoreOperative: cannot extract a jacked-in Decker body');
+    }
+    const required = this.#scoreOperativeIds();
+    if (
+      [this.crewMember, this.partnerMember].some(
+        crew => crew && required.includes(crew.id) && !crew.alive
+      )
+    ) {
+      this.telemetry.cause = 'score-partial';
+      this.enterResult({
+        outcome: OUTCOME.EXIT,
+        telemetry: {
+          objectiveComplete: false,
+          objectiveExpired: false,
+        },
+      });
+      return;
+    }
+    const allExtracted = required.every(id => this.extractedOperativeIds.has(id));
+    if (!allExtracted) {
+      if (this.onPersist) this.onPersist(this.snapshot());
+      return;
+    }
+    this.telemetry.cause = 'score-extracted';
+    this.enterResult({
+      outcome: OUTCOME.EXIT,
+      telemetry: {
+        objectiveComplete: true,
+        objectiveExpired: false,
+      },
+    });
+  }
+
+  #nextScoreMeatActor(): Crew | null {
+    for (const crew of [this.player, this.partnerMember]) {
+      if (
+        crew &&
+        crew.alive &&
+        this.world?.entities.has(crew.id) &&
+        !this.extractedOperativeIds.has(crew.id)
+      ) {
+        return crew;
+      }
+    }
+    return null;
+  }
+
+  #scoreOperativeIds(): string[] {
+    if (!this.partnerMember) {
+      throw new Error('Run.#scoreOperativeIds: Score run requires a meat partner');
+    }
+    return [this.crewMember.id, this.partnerMember.id];
+  }
+
   /**
    * Finalise an abort extraction after the shell confirms. Safe to call only
    * while the run is still in COMBAT (if the player moved away from the exit
@@ -1835,7 +1967,10 @@ export class Run {
     const linkedDoorId = objectiveDoorId(this.contract);
     if (linkedDoorId) {
       assertDoorExists(this.world, linkedDoorId);
-      if (this.contract.objective.kind !== OBJECTIVES.TERMINAL_SLICE) {
+      if (
+        this.contract.objective.kind !== OBJECTIVES.TERMINAL_SLICE &&
+        this.contract.objective.kind !== OBJECTIVES.SCORE_FINAL
+      ) {
         const revisitSiteId = this.contract.context.locationSiteId;
         const priorKey =
           revisitSiteId &&
@@ -1925,6 +2060,32 @@ export class Run {
         })
       );
     }
+    if (this.contract.objective.kind === OBJECTIVES.SCORE_FINAL) {
+      const doorId = scoreDoorId(this.contract);
+      const jackAnchor = findInteractableAnchor(this.world, this.player, this.exitTile, this.rng);
+      this.world.addEntity(
+        new JackInPoint({
+          id: 'jack-in-0',
+          x: jackAnchor.x,
+          y: jackAnchor.y,
+        })
+      );
+      const payloadAnchor = findBehindDoorAnchor(
+        this.world,
+        this.player,
+        this.exitTile,
+        doorId,
+        this.rng
+      );
+      this.world.addEntity(
+        new Pickup({
+          id: scorePayloadId(this.contract),
+          x: payloadAnchor.x,
+          y: payloadAnchor.y,
+          label: 'Score payload',
+        })
+      );
+    }
     if (this.contract.objective.kind === OBJECTIVES.RETRIEVE) {
       const count = objectiveCount(this.contract);
       for (let i = 0; i < count; i++) {
@@ -2179,6 +2340,7 @@ export class Run {
       reconSeen: this.mapSeen,
       cyber: this.#cyberNodeProgress(),
     });
+    this.#syncScoreDoorUnlock();
     const limit = turnLimitForContract(this.contract);
     if (limit === null || !this.queue) return satisfied;
 
@@ -2290,6 +2452,8 @@ function isObjectiveFamilySatisfied(
       const cyber = objectiveState?.cyber;
       return !!cyber && cyber.required > 0 && cyber.sliced >= cyber.required;
     }
+    case OBJECTIVES.SCORE_FINAL:
+      return isScoreFinalSatisfied(contract, world, objectiveState);
     default: {
       const exhaustive: never = kind;
       throw new Error(`Run.isObjectiveSatisfied: unknown objective kind "${exhaustive}"`);
@@ -2312,6 +2476,26 @@ function objectiveDoorId(contract: Contract): string | null {
   return doorId;
 }
 
+function scoreDoorId(contract: Contract): string {
+  if (contract.objective.kind !== OBJECTIVES.SCORE_FINAL) {
+    throw new Error('Run: scoreDoorId requires a score-final contract');
+  }
+  const doorId = objectiveDoorId(contract);
+  if (!doorId) {
+    throw new Error('Run: score-final objective is missing a linked door id');
+  }
+  return doorId;
+}
+
+function scoreDoorIdOrNull(contract: Contract): string | null {
+  return contract.objective.kind === OBJECTIVES.SCORE_FINAL ? scoreDoorId(contract) : null;
+}
+
+function scorePayloadId(contract: Contract): string {
+  const doorId = scoreDoorId(contract);
+  return `score-payload-${doorId}`;
+}
+
 export type UnlockMethod = 'terminal' | 'keycard';
 
 /**
@@ -2667,6 +2851,20 @@ function isRetrieveSatisfied(contract: Contract, world?: World | null): boolean
   return secured.size >= required;
 }
 
+function isScoreFinalSatisfied(
+  contract: Contract,
+  world?: World | null,
+  objectiveState: ObjectiveState = {}
+): boolean {
+  if (!world) return false;
+  const cyber = objectiveState.cyber;
+  if (!cyber || cyber.required <= 0 || cyber.sliced < cyber.required) return false;
+  const payloadId = scorePayloadId(contract);
+  if (world.securedPickupIds().includes(payloadId)) return true;
+  const payload = world.entities.get(payloadId);
+  return payload instanceof Pickup && payload.secured;
+}
+
 function isHandoffSatisfied(contract: Contract, world?: World | null): boolean {
   if (!world) return false;
   const required = objectiveCount(contract);
diff --git a/src/game/campaignSummary.ts b/src/game/campaignSummary.ts
index 0387ab9..dc3b124 100644
--- a/src/game/campaignSummary.ts
+++ b/src/game/campaignSummary.ts
@@ -2,7 +2,7 @@ import type { CampaignEndReason } from '../types.js';
 
 export const CAMPAIGN_HISTORY_CAP = 50;
 
-export type CampaignSummaryResult = 'win' | 'loss';
+export type CampaignSummaryResult = 'win' | 'partial' | 'loss';
 
 export type CampaignSummaryCrew = {
   callsign: string;
@@ -42,6 +42,7 @@ const END_REASONS: readonly CampaignEndReason[] = [
   'crew-wipe',
   'clock-expired',
   'decker-flatlined-score',
+  'score-partial',
   'score-complete',
 ];
 
@@ -62,7 +63,7 @@ export function buildCampaignSummary(
   return validateCampaignSummary({
     campaignId: campaign.id,
     completedAt,
-    result: campaign.endReason === 'score-complete' ? 'win' : 'loss',
+    result: resultForEndReason(campaign.endReason),
     endReason: campaign.endReason,
     seed: campaign.seed,
     completedJobs: campaign.completedJobs,
@@ -94,14 +95,14 @@ export function validateCampaignSummary(value: unknown): CampaignSummary {
   ]);
   const campaignId = requireNonEmptyString(summary.campaignId, 'CampaignSummary.campaignId');
   const completedAt = requireIsoTimestamp(summary.completedAt);
-  if (summary.result !== 'win' && summary.result !== 'loss') {
-    throw new Error(`CampaignSummary.result must be win or loss, got ${summary.result}`);
+  if (summary.result !== 'win' && summary.result !== 'partial' && summary.result !== 'loss') {
+    throw new Error(`CampaignSummary.result must be win, partial, or loss, got ${summary.result}`);
   }
   if (!END_REASONS.includes(summary.endReason as CampaignEndReason)) {
     throw new Error(`CampaignSummary.endReason is invalid: ${summary.endReason}`);
   }
   const endReason = summary.endReason as CampaignEndReason;
-  const expectedResult: CampaignSummaryResult = endReason === 'score-complete' ? 'win' : 'loss';
+  const expectedResult = resultForEndReason(endReason);
   if (summary.result !== expectedResult) {
     throw new Error(`CampaignSummary ${endReason} must have result ${expectedResult}`);
   }
@@ -130,6 +131,12 @@ export function validateCampaignSummary(value: unknown): CampaignSummary {
   };
 }
 
+function resultForEndReason(endReason: CampaignEndReason): CampaignSummaryResult {
+  if (endReason === 'score-complete') return 'win';
+  if (endReason === 'score-partial') return 'partial';
+  return 'loss';
+}
+
 export function normalizeCampaignHistory(value: unknown): CampaignSummary[] {
   if (value === undefined) return [];
   if (!Array.isArray(value)) {
diff --git a/src/game/cyber/DataNode.ts b/src/game/cyber/DataNode.ts
index 5833a1e..7842175 100644
--- a/src/game/cyber/DataNode.ts
+++ b/src/game/cyber/DataNode.ts
@@ -18,6 +18,7 @@ import {
   type InteractResult,
 } from '../entities/Interactable.js';
 import { AP_COST, DATA_NODE_GLYPH, type ContractDifficulty } from '../constants.js';
+import { EVENT } from '../events.js';
 import type { Entity } from '../Entity.js';
 import type { World } from '../World.js';
 
@@ -81,7 +82,7 @@ export class DataNode extends Interactable {
     return this.sliceProgress >= this.sliceDifficulty;
   }
 
-  override interact(_world: World, actor: Entity): InteractResult {
+  override interact(world: World, actor: Entity): InteractResult {
     if (this.sliced) {
       return { ok: false, reason: 'already-sliced', message: `${this.label}: already sliced.` };
     }
@@ -102,6 +103,7 @@ export class DataNode extends Interactable {
     if (this.sliced) {
       this.secured = true;
       this.armed = false;
+      world.events?.emit(EVENT.DATA_NODE_SLICED, { node: this, actor });
       return { ok: true, message: `${this.label} sliced.` };
     }
     return {
diff --git a/src/game/events.ts b/src/game/events.ts
index c5a5ae2..f503d84 100644
--- a/src/game/events.ts
+++ b/src/game/events.ts
@@ -33,6 +33,8 @@ export const EVENT = Object.freeze({
   HAZARD_DAMAGE: 'hazard:damage',
   OBJECTIVE_TIMER_EXPIRED: 'objective:timer-expired',
   DOOR_UNLOCKED: 'door:unlocked',
+  /** P3.M5: a Cyberspace data node crossed its slice threshold. */
+  DATA_NODE_SLICED: 'cyber:data-node-sliced',
   /** P3.M3.2: a Decker linked a jack-in point. Payload `{ point, actor }`. */
   JACK_IN: 'cyber:jack-in',
   /** P3.M3: the Decker left the grid (voluntary or forced). */
diff --git a/src/game/hub/Curator.ts b/src/game/hub/Curator.ts
index d7996c5..a292a8b 100644
--- a/src/game/hub/Curator.ts
+++ b/src/game/hub/Curator.ts
@@ -36,6 +36,8 @@ export const OBJECTIVES = Object.freeze({
   ESCORT_EXTRACT: 'escort-extract',
   /** P3.M3: slice a data node in Cyberspace — requires a living Decker to jack in. */
   DATA_NODE_SLICE: 'data-node-slice',
+  /** P3.M5: THE SCORE finale — linked Cyberspace core, Meatspace door, payload. */
+  SCORE_FINAL: 'score-final',
 });
 
 const KNOWN_OBJECTIVE_KINDS = new Set(Object.values(OBJECTIVES));
@@ -714,7 +716,7 @@ function validateCyberspaceObjective(
   kind: ObjectiveKind,
   params: ObjectiveParams | undefined
 ): void {
-  if (kind === OBJECTIVES.DATA_NODE_SLICE) {
+  if (kind === OBJECTIVES.DATA_NODE_SLICE || kind === OBJECTIVES.SCORE_FINAL) {
     if (params?.requiresCyberspace !== true) {
       throw new Error(
         `contract objective "${kind}" requires params.requiresCyberspace to be exactly true`
@@ -725,9 +727,16 @@ function validateCyberspaceObjective(
         `contract objective "${kind}" requires params.count to be a positive integer`
       );
     }
+    if (kind === OBJECTIVES.SCORE_FINAL) {
+      if (typeof params.doorId !== 'string' || params.doorId.length === 0) {
+        throw new TypeError(
+          `contract objective "${kind}" requires params.doorId to be a non-empty string`
+        );
+      }
+    }
   } else if (params?.requiresCyberspace !== undefined) {
     throw new Error(
-      `contract objective param "requiresCyberspace" is only valid on "${OBJECTIVES.DATA_NODE_SLICE}", got kind "${kind}"`
+      `contract objective param "requiresCyberspace" is only valid on Cyberspace objectives, got kind "${kind}"`
     );
   }
 }
@@ -778,7 +787,11 @@ export function assertLabelObjectiveRegistryInSync(): void {
     validateRenderedContract(contract);
   }
   for (const kind of Object.values(OBJECTIVES)) {
-    if (kind !== OBJECTIVES.REACH_EXIT && !coveredKinds.has(kind)) {
+    if (
+      kind !== OBJECTIVES.REACH_EXIT &&
+      kind !== OBJECTIVES.SCORE_FINAL &&
+      !coveredKinds.has(kind)
+    ) {
       throw new Error(`Curator: no contract recipe covers objective kind "${kind}"`);
     }
   }
diff --git a/src/game/hub/arcSurface.ts b/src/game/hub/arcSurface.ts
index 47c4409..7d29762 100644
--- a/src/game/hub/arcSurface.ts
+++ b/src/game/hub/arcSurface.ts
@@ -151,6 +151,49 @@ export function isScorePrincipalContract(
   return true;
 }
 
+/**
+ * A location badge for the job board. `variant` maps to the CSS modifier the
+ * renderer appends after the base `known` class (`'revisit'` is the bare
+ * `known` styling).
+ */
+export interface ContractLocationBadge {
+  variant: 'score-site' | 'casing' | 'revisit';
+  text: string;
+}
+
+/**
+ * Ordered location badges for a contract. Score-intel status (SCORE SITE /
+ * CASING) and revisit memory (`// known site`) are *independent* facts: a
+ * casing job at the score principal can also be a place we've already cased, so
+ * both badges surface together.
+ *
+ * The Score *target* is excluded from the revisit badge. This is sound because
+ * the target is always net-new when the board renders: the Score is a one-shot
+ * that ends the campaign on any outcome (so it's never deployed to twice), and
+ * no normal run can accrue memory onto it — its roster id is namespaced
+ * (`score-…`) out of reach of `generateSiteId(seed)`, and the Curator filters
+ * the target out of revisit rolls. The suppression is belt-and-suspenders
+ * against a double-badge, not a correctness dependency. Non-target `score`-tier
+ * sites are *not* special-cased — they can be cased/revisited like any other.
+ */
+export function contractLocationBadges(
+  contract: Contract,
+  scoreTargetSiteId: string | null | undefined,
+  scorePrincipalId: string | null | undefined
+): ContractLocationBadge[] {
+  const badges: ContractLocationBadge[] = [];
+  const scoreSite = isScoreSiteContract(contract, scoreTargetSiteId);
+  if (scoreSite) {
+    badges.push({ variant: 'score-site', text: 'SCORE SITE' });
+  } else if (isScorePrincipalContract(contract, scorePrincipalId, scoreTargetSiteId)) {
+    badges.push({ variant: 'casing', text: 'CASING' });
+  }
+  if (contract.context.locationSiteId && !scoreSite) {
+    badges.push({ variant: 'revisit', text: '// known site' });
+  }
+  return badges;
+}
+
 export function scoreTargetSiteId(campaign: ArcSurfaceCampaign): string | null {
   return findScoreTargetSite(campaign.siteRoster)?.id ?? null;
 }
diff --git a/src/game/objectiveProgress.ts b/src/game/objectiveProgress.ts
index 6b034d8..28e0660 100644
--- a/src/game/objectiveProgress.ts
+++ b/src/game/objectiveProgress.ts
@@ -173,6 +173,10 @@ export function objectiveProgress(
       if (!cyber || cyber.required <= 0) return null;
       return { label: 'NODES', current: cyber.sliced, total: cyber.required };
     }
+    case OBJECTIVES.SCORE_FINAL: {
+      if (!cyber || cyber.required <= 0) return null;
+      return { label: 'CORE', current: cyber.sliced, total: cyber.required };
+    }
     default:
       return null;
   }
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index 0a1759e..3e6941d 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -1075,6 +1075,8 @@ export function restore(record: unknown, options: RestoreOptions = {}) {
   }
 
   const restoredEntities = record.entities.map(entityRec => restoreEntity(entityRec, grid));
+  const extractedOperativeIds = normalizeExtractedOperativeIds(record.extractedOperativeIds);
+  const extractedOperatives = normalizeExtractedOperatives(record.extractedOperatives, grid);
   const playerCrew = restoredEntities.filter(
     (e): e is Crew => e instanceof Crew && e.faction === FACTION.PLAYER
   );
@@ -1084,7 +1086,16 @@ export function restore(record: unknown, options: RestoreOptions = {}) {
   let player: Crew;
   let gridPartner: Crew | null = null;
   if (playerCrew.length === 1) {
-    player = playerCrew[0]!;
+    const lone = playerCrew[0]!;
+    const extractedPrimary = extractedOperatives.find(
+      (e): e is Crew => e instanceof Decker && extractedOperativeIds.includes(e.id)
+    );
+    if (extractedPrimary && !(lone instanceof Decker)) {
+      player = extractedPrimary;
+      gridPartner = lone;
+    } else {
+      player = lone;
+    }
   } else if (playerCrew.length === 2) {
     const deckers = playerCrew.filter(e => e instanceof Decker);
     const others = playerCrew.filter(e => !(e instanceof Decker));
@@ -1136,6 +1147,11 @@ export function restore(record: unknown, options: RestoreOptions = {}) {
     run.partnerMember = partner;
   } else if (gridPartner) {
     run.partnerMember = gridPartner;
+  } else {
+    const extractedPartner = extractedOperatives.find(
+      (e): e is Crew => e instanceof Crew && !(e instanceof Decker)
+    );
+    if (extractedPartner) run.partnerMember = extractedPartner;
   }
 
   // P3.M4.2: re-establish the simstim flip state. While jacked in the Decker
@@ -1153,7 +1169,11 @@ export function restore(record: unknown, options: RestoreOptions = {}) {
     run.meatActor = liveMeatPartner ?? player;
     run.activeLayer = liveMeatPartner && record.activeLayer !== 'cyber' ? 'meat' : 'cyber';
   } else {
-    run.meatActor = player;
+    run.meatActor = !extractedOperativeIds.includes(player.id)
+      ? player
+      : gridPartner && !extractedOperativeIds.includes(gridPartner.id)
+        ? gridPartner
+        : null;
     run.activeLayer = 'meat';
   }
   run.exitTile = record.exitTile ? { ...record.exitTile } : null;
@@ -1165,6 +1185,7 @@ export function restore(record: unknown, options: RestoreOptions = {}) {
   run.world.restoreSecuredPickups(
     normalizeObjectiveProgress(record.objectiveProgress).securedPickups
   );
+  run.extractedOperativeIds = new Set(extractedOperativeIds);
   run.world.mutationDeltas = normalizeMutationDeltas(record.mutationDeltas, grid);
   if (record.alarm) {
     run.world.restoreAlarm(record.alarm);
@@ -1199,9 +1220,13 @@ export function restore(record: unknown, options: RestoreOptions = {}) {
     }
   }
   if (run.state === RUN_STATE.COMBAT && !run.player) {
-    throw new Error(
-      `restore: COMBAT snapshot has no player entity matching archetype "${run.archetype}"`
-    );
+    if (run.extractedOperativeIds.has(player.id)) {
+      run.player = player;
+    } else {
+      throw new Error(
+        `restore: COMBAT snapshot has no player entity matching archetype "${run.archetype}"`
+      );
+    }
   }
 
   if (run.state === RUN_STATE.COMBAT) {
@@ -1814,6 +1839,10 @@ function restoreActiveRun(
   if (record.snapshot) {
     const restored = restore(record.snapshot, options).run;
     restored.crewMember = member;
+    restored.archetype = archetypeOfCrew(member);
+    if (restored.extractedOperativeIds.has(member.id)) {
+      restored.player = member;
+    }
     // P3.M4.1/M4.4: re-bind the partner to the canonical roster object ONLY
     // while it is still off-grid — a dormant reserve, the object a later jack-in
     // spawns onto the meat grid. Once the partner is a *live grid entity*
@@ -1825,6 +1854,13 @@ function restoreActiveRun(
     if (partner && !restored.world?.entities.has(partner.id)) {
       restored.partnerMember = partner;
     }
+    if (
+      partner &&
+      restored.meatActor?.id === partner.id &&
+      !restored.world?.entities.has(partner.id)
+    ) {
+      restored.meatActor = partner;
+    }
     return restored;
   }
   const run = new Run({
@@ -1968,6 +2004,38 @@ function normalizeObjectiveProgress(progress: unknown): ObjectiveProgressSnapsho
   return { securedPickups: [...candidate.securedPickups] };
 }
 
+function normalizeExtractedOperativeIds(raw: unknown): string[] {
+  if (raw === undefined || raw === null) return [];
+  if (!Array.isArray(raw)) {
+    throw new TypeError('restore: extractedOperativeIds must be an array when supplied');
+  }
+  const seen = new Set<string>();
+  for (const id of raw) {
+    if (typeof id !== 'string' || id.length === 0) {
+      throw new TypeError('restore: extractedOperativeIds entries must be non-empty strings');
+    }
+    if (seen.has(id)) {
+      throw new Error(`restore: duplicate extracted operative id "${id}"`);
+    }
+    seen.add(id);
+  }
+  return [...seen];
+}
+
+function normalizeExtractedOperatives(raw: unknown, grid: Grid): Crew[] {
+  if (raw === undefined || raw === null) return [];
+  if (!Array.isArray(raw)) {
+    throw new TypeError('restore: extractedOperatives must be an array when supplied');
+  }
+  return raw.map((rec, index) => {
+    const entity = restoreEntity(rec as RunEntitySnapshot, grid);
+    if (!(entity instanceof Crew)) {
+      throw new TypeError(`restore: extractedOperatives[${index}] must be a crew entity`);
+    }
+    return entity;
+  });
+}
+
 /**
  * Normalize run-scoped key items from a snapshot (or undefined for
  * pre-P2.5.M6.2 saves). Validates structure. Crashes on malformed entries.
diff --git a/src/types.ts b/src/types.ts
index 98b19e3..dacbbaf 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -21,6 +21,7 @@ export type CampaignEndReason =
   | 'crew-wipe'
   | 'clock-expired'
   | 'decker-flatlined-score'
+  | 'score-partial'
   | 'score-complete';
 
 /**
diff --git a/tests/unit/game/Campaign.test.ts b/tests/unit/game/Campaign.test.ts
index 61f6809..c637907 100644
--- a/tests/unit/game/Campaign.test.ts
+++ b/tests/unit/game/Campaign.test.ts
@@ -1126,10 +1126,12 @@ test('terminal result detection bypasses debrief for Score, terminal death, and
   });
   scoreCampaign.arc.arcStage = 'act-3';
   const decker = scoreCampaign.crew.find(member => member.archetype === 'Decker');
+  const partner = scoreCampaign.crew.find(member => member.archetype !== 'Decker');
   assert.ok(decker);
-  scoreCampaign.deployCrewMember(decker.id, scoreCampaign.buildScoreContract());
+  assert.ok(partner);
+  scoreCampaign.deployCrewMember(decker.id, scoreCampaign.buildScoreContract(), partner.id);
   assert.equal(willEndCampaignAfterResult(scoreCampaign, OUTCOME.EXIT, true), true);
-  assert.equal(willEndCampaignAfterResult(scoreCampaign, OUTCOME.EXIT, false), false);
+  assert.equal(willEndCampaignAfterResult(scoreCampaign, OUTCOME.EXIT, false), true);
   assert.equal(willEndCampaignAfterResult(scoreCampaign, OUTCOME.DEATH, false), true);
 
   const finalOperator = new Campaign({ seed: 45 });
@@ -1197,15 +1199,13 @@ test('completed Score extraction settles synchronously before the exit move call
   });
   campaign.arc.arcStage = 'act-3';
   const decker = campaign.crew.find(member => member.archetype === 'Decker');
+  const partner = campaign.crew.find(member => member.archetype !== 'Decker');
   assert.ok(decker);
-  const run = campaign.deployCrewMember(decker.id, campaign.buildScoreContract());
+  assert.ok(partner);
+  const run = campaign.deployCrewMember(decker.id, campaign.buildScoreContract(), partner.id);
   run.enterCombat();
-  run.cyberspace = { phase: 'resolved', objectiveComplete: true };
-  assert.ok(run.world && run.player && run.exitTile);
-
-  run.world.relocateEntity(run.player, run.exitTile.x, run.exitTile.y);
+  campaign.onJobEnd({ outcome: OUTCOME.EXIT, completed: true });
 
-  assert.equal(run.state, RUN_STATE.RESULT, 'the captured Run is no longer turn-playable');
   assert.equal(campaign.state, CAMPAIGN_STATE.ENDED);
   assert.equal(campaign.endReason, 'score-complete');
   assert.equal(
@@ -1266,16 +1266,19 @@ test('P3.M1.7: Score contract is gated to Act 3 and marks attempted on deploymen
   assert.equal(score.context.locationSiteId, 'score');
   assert.ok(score.context.tags.includes('score'));
   assert.match(score.label, /THE SCORE/);
-  // The Score is (for now) always a cyber run: DATA_NODE_SLICE end to end.
-  assert.equal(score.objective.kind, OBJECTIVES.DATA_NODE_SLICE);
+  assert.equal(score.objective.kind, OBJECTIVES.SCORE_FINAL);
   assert.equal(score.objective.params?.requiresCyberspace, true);
   assert.equal(score.objective.params?.count, 1);
+  assert.equal(score.objective.params?.doorId, 'score-door-0');
   assert.equal(score.reward.credits, SCORE_CREDITS_REWARD);
   assert.equal(score.reward.repDelta, 0);
 
   const decker = campaign.crew.find(m => m.archetype === 'Decker');
+  const partner = campaign.crew.find(m => m.archetype !== 'Decker');
   assert.ok(decker, 'Act 3 campaign should include auto-assigned Decker');
-  const run = campaign.deployCrewMember(decker!.id, score);
+  assert.ok(partner, 'Act 3 campaign should include a living meat partner');
+  assert.throws(() => campaign.deployCrewMember(decker!.id, score), /meat partner/);
+  const run = campaign.deployCrewMember(decker!.id, score, partner!.id);
   assert.equal(campaign.arc.scoreAttempted, true);
   assert.equal(campaign.arcStage, 'score');
   assert.equal(run.contract?.context.locationSiteId, 'score');
@@ -1350,8 +1353,10 @@ test('P3.M1.7: completed Score contract records campaign win state', () => {
     ],
   });
   const decker = campaign.crew.find(m => m.archetype === 'Decker');
+  const partner = campaign.crew.find(m => m.archetype !== 'Decker');
   assert.ok(decker, 'Act 3 campaign should include auto-assigned Decker');
-  const run = campaign.deployCrewMember(decker!.id, campaign.buildScoreContract());
+  assert.ok(partner);
+  const run = campaign.deployCrewMember(decker!.id, campaign.buildScoreContract(), partner.id);
   run.enterCombat();
 
   campaign.onJobEnd({ outcome: OUTCOME.EXIT, completed: true });
@@ -1381,8 +1386,10 @@ test('a Decker flatline during the Score ends the campaign explicitly', () => {
     ],
   });
   const decker = campaign.crew.find(member => member.archetype === 'Decker');
+  const partner = campaign.crew.find(member => member.archetype !== 'Decker');
   assert.ok(decker);
-  const run = campaign.deployCrewMember(decker.id, campaign.buildScoreContract());
+  assert.ok(partner);
+  const run = campaign.deployCrewMember(decker.id, campaign.buildScoreContract(), partner.id);
   run.enterCombat();
   assert.equal(
     willEndCampaignOnThisDeath(campaign),
diff --git a/tests/unit/game/campaignSummary.test.ts b/tests/unit/game/campaignSummary.test.ts
index 4e4abf9..452e22a 100644
--- a/tests/unit/game/campaignSummary.test.ts
+++ b/tests/unit/game/campaignSummary.test.ts
@@ -62,10 +62,12 @@ test('Score completion summary uses post-settlement jobs, Rep, and Credits', ()
     ],
   });
   const decker = campaign.crew.find(member => member.archetype === 'Decker');
+  const partner = campaign.crew.find(member => member.archetype !== 'Decker');
   assert.ok(decker);
+  assert.ok(partner);
   const score = campaign.buildScoreContract();
   score.reward.repDelta = 7;
-  const run = campaign.deployCrewMember(decker.id, score);
+  const run = campaign.deployCrewMember(decker.id, score, partner.id);
   run.enterCombat();
 
   campaign.onJobEnd({
@@ -100,11 +102,23 @@ test('loss summaries preserve each terminal reason and final roster state', () =
   }
 });
 
+test('partial Score summary validates as partial', () => {
+  const record = validateCampaignSummary(
+    summary({ result: 'partial', endReason: 'score-partial' })
+  );
+  assert.equal(record.result, 'partial');
+  assert.equal(record.endReason, 'score-partial');
+});
+
 test('CampaignSummary validation rejects mismatched outcomes and malformed credit totals', () => {
   assert.throws(
     () => validateCampaignSummary(summary({ result: 'loss' })),
     /score-complete must have result win/
   );
+  assert.throws(
+    () => validateCampaignSummary(summary({ result: 'win', endReason: 'score-partial' })),
+    /score-partial must have result partial/
+  );
   assert.throws(
     () => validateCampaignSummary({ ...summary(), credits: -1 }),
     /credits must be a non-negative integer/
diff --git a/tests/unit/game/hub/arcSurface.test.ts b/tests/unit/game/hub/arcSurface.test.ts
index 4508ac8..cd4f416 100644
--- a/tests/unit/game/hub/arcSurface.test.ts
+++ b/tests/unit/game/hub/arcSurface.test.ts
@@ -5,6 +5,7 @@ import { CONTRACT_DIFFICULTY } from '../../../../src/game/constants.js';
 import { buildContractRecipeFixture } from '../../../../src/game/hub/Curator.js';
 import {
   act3RevealLines,
+  contractLocationBadges,
   findDecker,
   findScoreTargetSite,
   formatArcStageLabel,
@@ -244,6 +245,54 @@ test('isScorePrincipalContract matches same-principal jobs but not the Score sit
   assert.equal(isScorePrincipalContract(contract, 'matsuda', 'score-site'), false);
 });
 
+function badgeFixture(locationSiteId?: string) {
+  const contract = buildContractRecipeFixture({
+    recipeId: 'terminal-slice',
+    principalId: 'matsuda',
+    siteId: 'server-farm',
+    assetId: 'identity-spool',
+    actionId: 'slice',
+    difficulty: CONTRACT_DIFFICULTY.STANDARD,
+    seed: 11,
+  });
+  if (locationSiteId !== undefined) contract.context.locationSiteId = locationSiteId;
+  return contract;
+}
+
+test('contractLocationBadges returns only SCORE SITE for the Score target', () => {
+  const contract = badgeFixture('score-site');
+  assert.deepEqual(contractLocationBadges(contract, 'score-site', 'matsuda'), [
+    { variant: 'score-site', text: 'SCORE SITE' },
+  ]);
+});
+
+test('contractLocationBadges returns only CASING for a fresh score-principal job', () => {
+  const contract = badgeFixture(); // no locationSiteId → not a revisit
+  assert.deepEqual(contractLocationBadges(contract, 'score-site', 'matsuda'), [
+    { variant: 'casing', text: 'CASING' },
+  ]);
+});
+
+test('contractLocationBadges returns only known-site for a non-principal revisit', () => {
+  const contract = badgeFixture('case-site');
+  assert.deepEqual(contractLocationBadges(contract, 'score-site', 'other-principal'), [
+    { variant: 'revisit', text: '// known site' },
+  ]);
+});
+
+test('contractLocationBadges surfaces both CASING and known-site when both are true', () => {
+  const contract = badgeFixture('case-site'); // score principal AND a remembered site
+  assert.deepEqual(contractLocationBadges(contract, 'score-site', 'matsuda'), [
+    { variant: 'casing', text: 'CASING' },
+    { variant: 'revisit', text: '// known site' },
+  ]);
+});
+
+test('contractLocationBadges returns no badges for a fresh non-principal job', () => {
+  const contract = badgeFixture(); // no locationSiteId, principal not the Score org
+  assert.deepEqual(contractLocationBadges(contract, 'score-site', 'other-principal'), []);
+});
+
 test('findDecker throws when crew has no Decker', () => {
   assert.throws(
     () => findDecker([new Merc({ id: 'merc', x: 0, y: 0, callsign: 'Wraith' })]),
diff --git a/tests/unit/game/scoreFinal.test.ts b/tests/unit/game/scoreFinal.test.ts
new file mode 100644
index 0000000..e429375
--- /dev/null
+++ b/tests/unit/game/scoreFinal.test.ts
@@ -0,0 +1,234 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { Campaign, CAMPAIGN_STATE, SCORE_CREDITS_REWARD } from '../../../src/game/Campaign.js';
+import { OUTCOME, RUN_STATE, Run } from '../../../src/game/Run.js';
+import { DataNode } from '../../../src/game/cyber/DataNode.js';
+import { CyberspaceLayer } from '../../../src/game/cyber/CyberspaceLayer.js';
+import { Door } from '../../../src/game/entities/Door.js';
+import { JackInPoint } from '../../../src/game/entities/JackInPoint.js';
+import { Pickup } from '../../../src/game/entities/Pickup.js';
+import { snapshot, restore } from '../../../src/game/persistence.js';
+import { buildCrewMember } from '../../../src/game/archetypes/index.js';
+import { CONTRACT_DIFFICULTY } from '../../../src/game/constants.js';
+import { OBJECTIVES } from '../../../src/game/hub/Curator.js';
+import { Rng } from '../../../src/rng.js';
+import { testContractContext } from './contractTestUtils.js';
+import type { Entity } from '../../../src/game/Entity.js';
+import type { World } from '../../../src/game/World.js';
+import type { Contract } from '../../../src/game/hub/Curator.js';
+import type { LocationSite } from '../../../src/types.js';
+
+const SCORE_DOOR_ID = 'score-door-0';
+
+function scoreContract(seed = 100): Contract {
+  return {
+    seed,
+    mapWidth: 28,
+    mapHeight: 18,
+    objective: {
+      kind: OBJECTIVES.SCORE_FINAL,
+      title: 'The Score',
+      briefing: 'Slice the core, secure the payload, and extract both operators.',
+      params: { requiresCyberspace: true, count: 1, doorId: SCORE_DOOR_ID },
+    },
+    difficulty: CONTRACT_DIFFICULTY.CRITICAL,
+    threatCount: 1,
+    label: '// Matsuda server farm - THE SCORE',
+    context: {
+      ...testContractContext(OBJECTIVES.SCORE_FINAL),
+      recipeId: 'score-final',
+      tags: ['score', 'meatspace', 'cyberspace', `objective:${OBJECTIVES.SCORE_FINAL}`],
+      arcStage: 'score',
+      locationSiteId: 'score',
+    },
+    reward: { credits: SCORE_CREDITS_REWARD, repDelta: 0 },
+  };
+}
+
+function makeDecker() {
+  return buildCrewMember('decker', { x: 0, y: 0 }, new Rng(100), { id: 'crew-decker' });
+}
+
+function makeMerc() {
+  return buildCrewMember('merc', { x: 0, y: 0 }, new Rng(101), { id: 'crew-merc' });
+}
+
+function adjacentFreeTile(world: World, target: Entity) {
+  for (let dy = -1; dy <= 1; dy++) {
+    for (let dx = -1; dx <= 1; dx++) {
+      if (dx === 0 && dy === 0) continue;
+      const x = target.x + dx;
+      const y = target.y + dy;
+      if (world.grid.inBounds(x, y) && world.grid.isPassable(x, y) && !world.entityAt(x, y)) {
+        return { x, y };
+      }
+    }
+  }
+  throw new Error(`no free tile adjacent to ${target.id}`);
+}
+
+function scoreRun(seed = 100): Run {
+  const run = new Run({ crewMember: makeDecker(), partnerMember: makeMerc(), seed });
+  run.enterBriefing(scoreContract(seed));
+  run.enterCombat();
+  return run;
+}
+
+function jackIn(run: Run): CyberspaceLayer {
+  const point = [...run.world!.entities.values()].find(e => e instanceof JackInPoint);
+  assert.ok(point, 'Score placed a jack-in point');
+  const spot = adjacentFreeTile(run.world!, point);
+  run.world!.relocateEntity(run.player!, spot.x, spot.y);
+  run.player!.refreshAp();
+  assert.equal(point.interact(run.world!, run.player!).ok, true);
+  assert.equal(run.cyberspace?.phase, 'active');
+  return (run.cyberspace as { phase: 'active'; layer: CyberspaceLayer }).layer;
+}
+
+function sliceCore(layer: CyberspaceLayer): void {
+  const node = [...layer.world.entities.values()].find(e => e instanceof DataNode);
+  assert.ok(node, 'Score placed a core data node');
+  while (!node.sliced) {
+    const spot = adjacentFreeTile(layer.world, node);
+    layer.world.relocateEntity(layer.avatar, spot.x, spot.y);
+    layer.avatar.refreshAp();
+    assert.equal(node.interact(layer.world, layer.avatar).ok, true);
+  }
+}
+
+function routeOut(layer: CyberspaceLayer): void {
+  const spot = adjacentFreeTile(layer.world, layer.port);
+  layer.world.relocateEntity(layer.avatar, spot.x, spot.y);
+  layer.avatar.refreshAp();
+  assert.equal(layer.port.interact(layer.world, layer.avatar).ok, true);
+}
+
+function scoreDoor(run: Run): Door {
+  const door = [...run.world!.entities.values()].find(
+    (e): e is Door => e instanceof Door && e.doorId === SCORE_DOOR_ID
+  );
+  assert.ok(door, 'Score placed the linked Meatspace door');
+  return door;
+}
+
+function scorePayload(run: Run): Pickup {
+  const payload = [...run.world!.entities.values()].find(
+    (e): e is Pickup => e instanceof Pickup && e.id === `score-payload-${SCORE_DOOR_ID}`
+  );
+  assert.ok(payload, 'Score placed the payload behind the linked door');
+  return payload;
+}
+
+function scoreSite(overrides: Partial<LocationSite> = {}): LocationSite {
+  const principal = { id: 'matsuda', label: 'Matsuda', groups: ['corp'] };
+  return {
+    id: 'score',
+    seed: '100',
+    mapWidth: 28,
+    mapHeight: 18,
+    label: '// Matsuda server farm - Score target',
+    tier: 'score',
+    scoreTarget: true,
+    mutationDeltas: [],
+    seenKeys: [],
+    lastVisitedJob: 5,
+    principal,
+    site: { id: 'server-farm', label: 'server farm', groups: ['corp', 'data'] },
+    ...overrides,
+  };
+}
+
+test('Score run places linked Meatspace and Cyberspace objectives', () => {
+  const run = scoreRun();
+  const door = scoreDoor(run);
+  assert.equal(door.locked, true);
+  assert.ok(scorePayload(run));
+  const layer = jackIn(run);
+  assert.equal([...layer.world.entities.values()].filter(e => e instanceof DataNode).length, 1);
+});
+
+test('slicing the Score core unlocks the linked Meatspace door', () => {
+  const run = scoreRun();
+  const door = scoreDoor(run);
+  const layer = jackIn(run);
+  sliceCore(layer);
+  assert.equal(door.locked, false);
+});
+
+test('partner can extract first; Decker later jacks out and completes the Score', () => {
+  const run = scoreRun();
+  const layer = jackIn(run);
+  sliceCore(layer);
+  scorePayload(run).secureWalkOnto(run.world!);
+  assert.equal(run.isObjectiveSatisfied(), true);
+
+  const partner = run.partnerMember!;
+  run.world!.relocateEntity(partner, run.exitTile!.x, run.exitTile!.y);
+  assert.deepEqual([...run.extractedOperativeIds], [partner.id]);
+  assert.equal(run.state, RUN_STATE.COMBAT);
+  assert.equal(run.world!.entities.has(partner.id), false);
+  assert.equal(run.activeLayer, 'cyber');
+
+  routeOut(layer);
+  run.world!.relocateEntity(run.player!, run.exitTile!.x, run.exitTile!.y);
+  assert.equal(run.state, RUN_STATE.RESULT);
+  assert.equal(run.telemetry.outcome, OUTCOME.EXIT);
+  assert.equal(run.telemetry.objectiveComplete, true);
+});
+
+test('mid-Score restore preserves extracted partner and can still finish', () => {
+  const run = scoreRun();
+  const layer = jackIn(run);
+  sliceCore(layer);
+  scorePayload(run).secureWalkOnto(run.world!);
+  const partner = run.partnerMember!;
+  run.world!.relocateEntity(partner, run.exitTile!.x, run.exitTile!.y);
+
+  const { run: restored } = restore(structuredClone(snapshot(run)));
+  assert.deepEqual([...restored.extractedOperativeIds], [partner.id]);
+  assert.equal(restored.world!.entities.has(partner.id), false);
+  assert.equal(restored.partnerMember?.id, partner.id);
+  assert.equal(restored.cyberspace?.phase, 'active');
+
+  const restoredLayer = (restored.cyberspace as { phase: 'active'; layer: CyberspaceLayer }).layer;
+  routeOut(restoredLayer);
+  restored.world!.relocateEntity(restored.player!, restored.exitTile!.x, restored.exitTile!.y);
+  assert.equal(restored.state, RUN_STATE.RESULT);
+  assert.equal(restored.telemetry.objectiveComplete, true);
+});
+
+test('early Score exit requests confirmation and confirmed extraction is partial', () => {
+  const run = scoreRun();
+  let requests = 0;
+  run.onAbortRequested = () => requests++;
+  run.world!.relocateEntity(run.player!, run.exitTile!.x, run.exitTile!.y);
+  assert.equal(requests, 1);
+  assert.equal(run.state, RUN_STATE.COMBAT);
+
+  run.confirmAbort();
+  assert.equal(run.state, RUN_STATE.RESULT);
+  assert.equal(run.telemetry.objectiveComplete, false);
+});
+
+test('Campaign records partial Score as terminal without full reward', () => {
+  const campaign = new Campaign({
+    seed: 42,
+    credits: 25,
+    rep: 65,
+    completedJobs: 9,
+    siteRoster: [
+      scoreSite(),
+      scoreSite({ id: 'case-1', tier: 'roster', scoreTarget: false, seed: '101' }),
+      scoreSite({ id: 'case-2', tier: 'roster', scoreTarget: false, seed: '102' }),
+    ],
+  });
+  const decker = campaign.crew.find(member => member.archetype === 'Decker')!;
+  const partner = campaign.crew.find(member => member.archetype !== 'Decker')!;
+  campaign.deployCrewMember(decker.id, campaign.buildScoreContract(), partner.id).enterCombat();
+
+  campaign.onJobEnd({ outcome: OUTCOME.EXIT, completed: false });
+  assert.equal(campaign.state, CAMPAIGN_STATE.ENDED);
+  assert.equal(campaign.endReason, 'score-partial');
+  assert.equal(campaign.credits, 25);
+});

From 2ff0cf7014aaaab05ce676891944ce667402e884 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Thu, 25 Jun 2026 11:56:39 -0700
Subject: [PATCH 48/55] plan revision

---
 docs/phase-3-plan.md | 64 +++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 60 insertions(+), 4 deletions(-)

diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index e3c8e49..1b2d058 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -46,7 +46,8 @@ A new **player archetype** recruited mid-campaign (late Act 1 / start of Act 2),
 | P3.M3 — Cyberspace grid + ICE | ✅ Done (full ICE roster: Probe, Spark, Guardian) |
 | P3.M4 — Simstim flip (dual-deploy) | ✅ Done |
 | P3.M5 — The Score (climactic mission) | ✅ Done |
-| P3.M6 — Chronicle (campaign narrative memory) | 🟡 End-summary foundation shipped |
+| P3.M6 — Stolen Blueprints (shop rework + meta-progression) | 🔲 Not started |
+| P3.M7 — Chronicle (campaign narrative memory) | 🟡 End-summary foundation shipped |
 
 **Phase 3** is complete when:
 
@@ -417,7 +418,61 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 
 ---
 
-### P3.M6 — Chronicle (campaign narrative memory) 🟡
+### P3.M6 — Stolen Blueprints (shop rework + meta-progression) 🔲
+
+**Depends on:** P3.M5 (Score completion path — unlock writes to meta-store on `score-complete`); P2.5.M5 (existing shop/rep system being replaced).
+
+**Goal:** Replace rep-gated shop access with a **meta-progression unlock system** rooted in successful Score heists. The item catalog is restructured into two explicit groups: **default items** (always available) and **scoreable items** (each a distinct Score target, unlocked permanently by stealing its blueprint). An enriched scoreable pool (8–12 items total, at least 5 net-new) means multiple campaigns have distinct heist targets before the pool exhausts; once exhausted, Scores shift to abstract RNG-driven credit payloads that keep the arc alive indefinitely.
+
+**Scope:**
+
+- **Data model change:** The current `minRepTier` property on items is retired as a shop-access mechanism. Items are reorganized into two fixed compile-time catalogs:
+  - **`DEFAULT_ITEMS`:** Items previously flagged `BURNED` or `UNKNOWN` `minRepTier`. Always available in Finn's shop; no condition, no gate.
+  - **`SCOREABLE_ITEMS`:** Items previously flagged `KNOWN` `minRepTier`, plus at least 5 net-new items added as part of this milestone. Each has a unique ID, a name, stats, and a short flavor line describing what was stolen (the prototype, the implant design, the weapons schematic). Not available in the shop until unlocked via a Score heist.
+  - `minRepTier` can be safely removed from item definitions, as it no longer influences shop availability after this milestone, and is not referenced elsewhere.
+
+- **Finn's shop rework:** Rep no longer gates shop inventory.
+  - `DEFAULT_ITEMS` always stocked from campaign start.
+  - Unlocked `SCOREABLE_ITEMS` added to stock permanently once acquired; locked scoreable items are not shown at all. The discovery of a new item appearing in Finn's shop after a Score is the reward.
+  - Shop variance = which scoreable items the meta-crew has acquired across all past campaigns. Rep meter decoupled from shop access (still drives arc transitions as before).
+
+- **Score target rework:** `buildScoreContract()` draws from the set of not-yet-acquired `SCOREABLE_ITEMS`. The Score target site is still a synthesized CRITICAL-tier facility, but briefing copy and objective text frame the site around the specific payload — the R&D lab, the secure vault, the production facility where the prototype lives. On clean `score-complete`, the item ID is written to the meta-progression store and the item becomes permanently available in Finn's shop.
+
+- **Abstract Score targets (pool exhausted):** When all `SCOREABLE_ITEMS` are acquired, `buildScoreContract()` shifts to abstract RNG-driven credit payloads drawn from a small fixed category set (corp payroll, exotic meta-materials, black-market data cache, prototype weapons cache, etc.). Payload category is seeded from the contract RNG so each exhausted-pool campaign gets different flavor. The full arc structure runs identically; the payout is a substantial credit sum rather than a shop unlock. No item is written to the meta-store.
+
+- **Meta-progression store:** New `DataStore` key `unlockedScoreableItems: string[]` (item IDs, ordered by acquisition date). Written only on `score-complete` (not `score-partial` — the prototype wasn't secured). Read at campaign init and Hub load. Idempotent archival: writing a duplicate ID is a no-op (no throw, no double-entry). Half-populated or structurally invalid store throws on restore rather than silently falling back to an empty list.
+
+- **Hub surface:** Finn's shop renders only purchasable items — `DEFAULT_ITEMS + unlockedScoreableItems`. An `ACQUISITIONS: N / M` counter is deferred to P3.M7, where it fits naturally in the Chronicle / history view.
+
+**Implementation slices:**
+
+| Slice | Status | Change | Tests |
+|---|---|---|---|
+| **P3.M6.1 Meta-store** | 🔲 | `DataStore` key `unlockedScoreableItems`; write on Score complete; read at campaign init; idempotent; duplicate is no-op; corrupt throws | round-trip, idempotent archival, duplicate no-op, corrupt throws |
+| **P3.M6.2 Item catalog split** | 🔲 | Define `DEFAULT_ITEMS` and `SCOREABLE_ITEMS` catalogs; retire `minRepTier` as shop gate; add at least 5 net-new scoreable items | catalog validation, no duplicate IDs, all items have required fields, `minRepTier` not read by shop |
+| **P3.M6.3 Shop rework** | 🔲 | Shop stocks `DEFAULT_ITEMS + unlockedScoreableItems`; no rep gate; locked scoreable items not rendered | shop shows only default items when meta-store is empty; adds unlocked scoreable items as they accrue; rep change has no effect on stock |
+| **P3.M6.4 Score target rework** | 🔲 | `buildScoreContract()` draws from unacquired `SCOREABLE_ITEMS`; briefing copy reflects item; completion writes meta-store | available targets exclude acquired; retired items not rolled; store updated on complete |
+| **P3.M6.5 Abstract targets** | 🔲 | Exhausted-pool Score draws RNG credit payload from category set; seeded flavor; arc gates pass with empty scoreable pool | category selection determinism, arc unaffected, no meta-store write |
+| **P3.M6.6 Hub surface** | 🔲 | Shop renders only purchasable items; no locked placeholders | shop never renders a locked scoreable item regardless of meta-store state |
+
+**Recorded design decisions:**
+
+- **Why `minRepTier` is retired as a shop gate:** Rep-gated access was mechanical — the best gear was reachable by grinding rep without doing anything interesting. Two explicit catalogs make availability rules legible in the data rather than computed from a tier comparison at runtime.
+- **Why default items are fixed:** The interesting question is "which upgrades has the meta-crew earned?" not "will Finn have ammo today?" Fixed default stock removes friction and keeps meaningful variance on scoreable unlocks.
+- **Why abstract payloads instead of pool reset:** Resetting would retroactively devalue past heists. Abstract payloads acknowledge mastery — "you've stolen everything worth stealing; now you're just taking their money" — while keeping the arc valid indefinitely for long-running meta-campaigns.
+- **Why partial Score doesn't unlock:** Incomplete extraction means the prototype wasn't secured. Clean win only; the fiction holds.
+
+**Acceptance:**
+
+- Finn's shop never gates by rep; `DEFAULT_ITEMS` always present from campaign start.
+- Unlocked `SCOREABLE_ITEMS` appear in shop; locked ones are not rendered.
+- `buildScoreContract()` excludes acquired scoreable items; draws abstract credit payload when pool is exhausted.
+- Meta-store persists across campaign boundaries; duplicate ID writes are no-ops; corrupt store throws.
+- Golden-path test: complete Score with scoreable item target → next campaign shows item in Finn's shop and excludes it from Score target pool.
+
+---
+
+### P3.M7 — Chronicle (campaign narrative memory) 🟡
 
 **Depends on:** P3.M1 (arc structure provides the narrative beats to chronicle). Can begin data collection earlier if arc state is available.
 
@@ -427,9 +482,10 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 
 - **Active campaign chronicle:** Entries for each run (jobs taken, outcomes, objectives completed/failed, major Rep deltas, crew changes, Decker recruitment, Score prep milestones) stored **in the campaign save**.
 - **Arc-aware entries:** Chronicle entries reflect the campaign's narrative arc — Act 1 entries read as "getting established"; Act 2 entries reference the Score target; Act 3 entries build tension toward the climax.
-- **Presentation:** Surfaced from the Hub **Terminal** alongside / inside the existing **crew** view (exact IA: tab, section, or shared scroll — TBD).
+- **Presentation:** Surfaced from a new Hub entry point (not the existing crew terminal: it remains focused on crew stats, inventory, and recruiting).
 - **Campaign end summary:** On win (Score completed) or loss (flatline / clock expired), roll up a **summary record** into a **persistent history** list (localStorage / DataStore — same durability pattern as runs/prefs). High-scores-style: scannable list with campaign stats, arc outcome, run count, crew roster at end.
 - **History access:** Hub waypoint or menu entry to view past campaign summaries. Viewable without an active campaign.
+- **Acquisitions counter:** The Chronicle / history view surfaces an `ACQUISITIONS: N / M` counter showing how many scoreable item blueprints the meta-crew has stolen across all campaigns (read from `unlockedScoreableItems` in the meta-store). The shop itself shows only purchasable items; this is the right place to communicate meta-progression depth.
 
 **Acceptance:**
 
@@ -439,7 +495,7 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 - Hub can open chronicle (active campaign) and history (past campaigns) without errors.
 - Tests for append + round-trip + cap/trim policy if the list is bounded.
 
-**P3.M6 implementation note:** The end-summary foundation is shipped. A validated `CampaignSummary` is built only after campaign settlement reaches `ENDED`, so the final completed-job increment, Credits (including the Score payoff), Rep, seed, and roster state are captured from the canonical final campaign. Salvage remains a campaign resource rather than a summary measure of value. `DataStore` keeps summaries newest-first, preserves the original record on duplicate archival, and trims history to 50 campaigns. Live completion and restored ended saves share the same idempotent archival path. `<game-over>` is now the single terminal campaign overlay with success and failure modes; terminal outcomes bypass the recoverable job-level `<crash-dump>` debrief. Active per-job chronicle entries, Terminal presentation, and history browsing remain follow-up work within P3.M6.
+**P3.M7 implementation note:** The end-summary foundation is shipped. A validated `CampaignSummary` is built only after campaign settlement reaches `ENDED`, so the final completed-job increment, Credits (including the Score payoff), Rep, seed, and roster state are captured from the canonical final campaign. Salvage remains a campaign resource rather than a summary measure of value. `DataStore` keeps summaries newest-first, preserves the original record on duplicate archival, and trims history to 50 campaigns. Live completion and restored ended saves share the same idempotent archival path. `<game-over>` is now the single terminal campaign overlay with success and failure modes; terminal outcomes bypass the recoverable job-level `<crash-dump>` debrief. Active per-job chronicle entries, Terminal presentation, and history browsing remain follow-up work within P3.M6.
 
 ---
 

From d172e1b2f80c2e1e7eac55b26c7d10271a377b07 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Thu, 25 Jun 2026 13:30:14 -0700
Subject: [PATCH 49/55] score targets m1

---
 docs/phase-3-plan.md                     | 21 +++++-
 src/DataStore.ts                         | 91 ++++++++++++++++++++----
 src/game/scoreableUnlocks.ts             | 63 ++++++++++++++++
 tests/unit/DataStore.test.ts             | 56 +++++++++++++++
 tests/unit/game/scoreableUnlocks.test.ts | 60 ++++++++++++++++
 5 files changed, 277 insertions(+), 14 deletions(-)
 create mode 100644 src/game/scoreableUnlocks.ts
 create mode 100644 tests/unit/game/scoreableUnlocks.test.ts

diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 1b2d058..aa9e74a 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -448,13 +448,32 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 
 | Slice | Status | Change | Tests |
 |---|---|---|---|
-| **P3.M6.1 Meta-store** | 🔲 | `DataStore` key `unlockedScoreableItems`; write on Score complete; read at campaign init; idempotent; duplicate is no-op; corrupt throws | round-trip, idempotent archival, duplicate no-op, corrupt throws |
+| **P3.M6.1 Meta-store** | ✅ | `DataStore` key `unlockedScoreableItems`; read at campaign init; idempotent archival; duplicate no-op; corrupt throws | round-trip, idempotent archival, duplicate no-op, corrupt throws |
 | **P3.M6.2 Item catalog split** | 🔲 | Define `DEFAULT_ITEMS` and `SCOREABLE_ITEMS` catalogs; retire `minRepTier` as shop gate; add at least 5 net-new scoreable items | catalog validation, no duplicate IDs, all items have required fields, `minRepTier` not read by shop |
 | **P3.M6.3 Shop rework** | 🔲 | Shop stocks `DEFAULT_ITEMS + unlockedScoreableItems`; no rep gate; locked scoreable items not rendered | shop shows only default items when meta-store is empty; adds unlocked scoreable items as they accrue; rep change has no effect on stock |
 | **P3.M6.4 Score target rework** | 🔲 | `buildScoreContract()` draws from unacquired `SCOREABLE_ITEMS`; briefing copy reflects item; completion writes meta-store | available targets exclude acquired; retired items not rolled; store updated on complete |
 | **P3.M6.5 Abstract targets** | 🔲 | Exhausted-pool Score draws RNG credit payload from category set; seeded flavor; arc gates pass with empty scoreable pool | category selection determinism, arc unaffected, no meta-store write |
 | **P3.M6.6 Hub surface** | 🔲 | Shop renders only purchasable items; no locked placeholders | shop never renders a locked scoreable item regardless of meta-store state |
 
+**P3.M6.1 implementation note:** The meta-progression store lands as a new
+`DataStore` key, `unlockedScoreableItems: string[]` (item IDs, acquisition order,
+newest-last), backed by a pure validator module `src/game/scoreableUnlocks.ts`
+(mirroring the `campaignSummary.ts` ⇄ `DataStore` relationship):
+`normalizeUnlockedScoreableItems` (absent → `[]`, non-array/non-string-element throws,
+de-dupes preserving order) and `archiveScoreableItem` (idempotent append, duplicate →
+`{ added: false }`). `DataStore.archiveScoreableItem(id)` only emits a `change` event /
+saves when the store actually changes (matching `archiveCampaign`'s `added` gate); the
+getter returns a defensive copy. Per the global "crashing beats data corruption"
+directive, `#loadDataFromJson` was split so an unparseable blob still resets to defaults
+but a **structurally corrupt (yet parseable) scoreable store throws** out of
+`init`/`import` rather than silently erasing earned blueprints. Structural validation
+only — catalog membership (id ∈ `SCOREABLE_ITEMS`) is a follow-up once that catalog
+exists in M6.2. The `score-complete` write call-site lands in M6.4. **Follow-up:**
+`campaignHistory` keeps its older swallow-and-reset-on-corrupt posture (deliberately not
+retrofitted in this slice). Tests: `scoreableUnlocks.test.ts`, plus three
+`DataStore.test.ts` cases (absent → `[]`, idempotent archival + persistence + defensive
+copy, corrupt store throws).
+
 **Recorded design decisions:**
 
 - **Why `minRepTier` is retired as a shop gate:** Rep-gated access was mechanical — the best gear was reachable by grinding rep without doing anything interesting. Two explicit catalogs make availability rules legible in the data rather than computed from a tier comparison at runtime.
diff --git a/src/DataStore.ts b/src/DataStore.ts
index 3d70c29..63db58d 100644
--- a/src/DataStore.ts
+++ b/src/DataStore.ts
@@ -6,6 +6,10 @@ import {
   normalizeCampaignHistory,
   type CampaignSummary,
 } from './game/campaignSummary.js';
+import {
+  archiveScoreableItem,
+  normalizeUnlockedScoreableItems,
+} from './game/scoreableUnlocks.js';
 
 const STORAGE_KEY = 'kp:data';
 let instance: DataStore | null = null;
@@ -23,14 +27,24 @@ type KPData = {
   runs: Run[];
   campaign: Campaign | null;
   campaignHistory: CampaignSummary[];
+  unlockedScoreableItems: string[];
 };
-type KPDataObject = string | object | Run | Campaign | Run[] | Campaign[] | CampaignSummary[];
+type KPDataObject =
+  | string
+  | object
+  | Run
+  | Campaign
+  | Run[]
+  | Campaign[]
+  | CampaignSummary[]
+  | string[];
 
 class DataStore extends EventTarget {
   #prefs: KPData['prefs'] = {};
   #runs: KPData['runs'] = [];
   #campaign: KPData['campaign'] = null;
   #campaignHistory: KPData['campaignHistory'] = [];
+  #unlockedScoreableItems: KPData['unlockedScoreableItems'] = [];
 
   constructor() {
     if (instance) {
@@ -43,48 +57,74 @@ class DataStore extends EventTarget {
   }
 
   #loadDataFromJson(json: string): KPData {
+    let data: Record<string, unknown>;
+    let campaignHistory: CampaignSummary[];
     try {
-      const data = JSON.parse(json);
-      return {
-        prefs: data.prefs ?? {},
-        runs: data.runs ?? [],
-        campaign: data.campaign ?? null,
-        campaignHistory: normalizeCampaignHistory(data.campaignHistory),
-      };
+      data = JSON.parse(json);
+      // `campaignHistory` keeps its existing posture: a structurally corrupt
+      // (but parseable) history resets the whole store rather than throwing.
+      campaignHistory = normalizeCampaignHistory(data.campaignHistory);
     } catch (error) {
       console.warn('[DataStore] Failed to parse stored JSON, resetting stored data.', error);
       try {
         window.localStorage.setItem(
           STORAGE_KEY,
-          JSON.stringify({ prefs: {}, runs: [], campaign: null, campaignHistory: [] })
+          JSON.stringify({
+            prefs: {},
+            runs: [],
+            campaign: null,
+            campaignHistory: [],
+            unlockedScoreableItems: [],
+          })
         );
       } catch (storageError) {
         console.warn('[DataStore] Failed to reset stored data.', storageError);
       }
-      return { prefs: {}, runs: [], campaign: null, campaignHistory: [] };
+      return { prefs: {}, runs: [], campaign: null, campaignHistory: [], unlockedScoreableItems: [] };
     }
+    // The meta-progression store crashes loudly on structural corruption — a
+    // silent reset would erase blueprints the meta-crew earned across campaigns
+    // (global directive: crashing beats data corruption). The throw propagates
+    // out of `init`/`import` rather than being swallowed above.
+    return {
+      prefs: (data.prefs as KPData['prefs']) ?? {},
+      runs: (data.runs as KPData['runs']) ?? [],
+      campaign: (data.campaign as KPData['campaign']) ?? null,
+      campaignHistory,
+      unlockedScoreableItems: normalizeUnlockedScoreableItems(data.unlockedScoreableItems),
+    };
   }
 
   async init() {
     let savedDataJson = window.localStorage.getItem(STORAGE_KEY);
     if (!savedDataJson) {
-      savedDataJson = JSON.stringify({ prefs: {}, runs: [], campaign: null, campaignHistory: [] });
+      savedDataJson = JSON.stringify({
+        prefs: {},
+        runs: [],
+        campaign: null,
+        campaignHistory: [],
+        unlockedScoreableItems: [],
+      });
       window.localStorage.setItem(STORAGE_KEY, savedDataJson);
     }
-    const { prefs, runs, campaign, campaignHistory } = this.#loadDataFromJson(savedDataJson);
+    const { prefs, runs, campaign, campaignHistory, unlockedScoreableItems } =
+      this.#loadDataFromJson(savedDataJson);
     this.#prefs = prefs;
     this.#runs = runs;
     this.#campaign = campaign;
     this.#campaignHistory = campaignHistory;
+    this.#unlockedScoreableItems = unlockedScoreableItems;
     this.#emitChangeEvent('init', '*');
   }
 
   import(jsonData: string): void {
-    const { prefs, runs, campaign, campaignHistory } = this.#loadDataFromJson(jsonData);
+    const { prefs, runs, campaign, campaignHistory, unlockedScoreableItems } =
+      this.#loadDataFromJson(jsonData);
     this.#prefs = prefs;
     this.#runs = runs;
     this.#campaign = campaign;
     this.#campaignHistory = campaignHistory;
+    this.#unlockedScoreableItems = unlockedScoreableItems;
     this.#emitChangeEvent('import', '*');
   }
 
@@ -96,6 +136,7 @@ class DataStore extends EventTarget {
         runs: this.#runs,
         campaign: this.#campaign,
         campaignHistory: this.#campaignHistory,
+        unlockedScoreableItems: this.#unlockedScoreableItems,
       })
     );
   }
@@ -133,6 +174,30 @@ class DataStore extends EventTarget {
     return this.#campaignHistory.map(cloneCampaignSummary);
   }
 
+  /**
+   * Cross-campaign meta-progression store (P3.M6): item IDs of scoreable
+   * blueprints stolen via clean Score heists, in acquisition order. Returns a
+   * defensive copy.
+   */
+  get unlockedScoreableItems(): string[] {
+    return [...this.#unlockedScoreableItems];
+  }
+
+  /**
+   * Record a scoreable item blueprint as stolen. Idempotent: re-archiving an
+   * already-unlocked id is a no-op (no event, no save). Returns whether the
+   * store changed. Written only on `score-complete` (call-site lands in M6.4).
+   */
+  archiveScoreableItem(id: string): { added: boolean } {
+    const { list, added } = archiveScoreableItem(this.#unlockedScoreableItems, id);
+    if (added) {
+      this.#unlockedScoreableItems = list;
+      this.#emitChangeEvent('add', 'unlockedScoreableItems', [...list]);
+      this.#saveData();
+    }
+    return { added };
+  }
+
   archiveCampaign(summary: CampaignSummary): CampaignSummary {
     const archived = archiveCampaignSummary(this.#campaignHistory, summary);
     this.#campaignHistory = archived.history;
diff --git a/src/game/scoreableUnlocks.ts b/src/game/scoreableUnlocks.ts
new file mode 100644
index 0000000..628592b
--- /dev/null
+++ b/src/game/scoreableUnlocks.ts
@@ -0,0 +1,63 @@
+/**
+ * Meta-progression store helpers for "Stolen Blueprints" (P3.M6).
+ *
+ * `unlockedScoreableItems` is a cross-campaign record of which scoreable item
+ * blueprints the meta-crew has stolen via clean Score heists. It is an ordered
+ * list of item IDs (acquisition order, newest-last) persisted by `DataStore`.
+ *
+ * These are pure functions — no DOM, no mutation of inputs — mirroring the
+ * relationship `campaignSummary.ts` has with `DataStore`. They validate
+ * structure only: catalog membership (an id naming a real `SCOREABLE_ITEMS`
+ * entry) is a later-slice concern (M6.2/M6.4) once that catalog exists.
+ *
+ * Per the global directive — silent fallbacks corrupt data — a structurally
+ * invalid store throws rather than resetting to an empty list.
+ */
+
+/**
+ * Validate and normalize a persisted `unlockedScoreableItems` value.
+ *
+ *   - `undefined` (key absent in a legacy save) → `[]`.
+ *   - Not an array → throw.
+ *   - Any element that is not a non-empty string → throw.
+ *   - De-duplicates, preserving first-seen (acquisition) order.
+ *
+ * Returns a fresh array — never the caller-owned reference.
+ */
+export function normalizeUnlockedScoreableItems(value: unknown): string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) {
+    throw new TypeError('unlockedScoreableItems must be an array');
+  }
+  const seen = new Set<string>();
+  const items: string[] = [];
+  for (const candidate of value) {
+    if (typeof candidate !== 'string' || candidate.length === 0) {
+      throw new TypeError('unlockedScoreableItems entries must be non-empty strings');
+    }
+    if (seen.has(candidate)) continue;
+    seen.add(candidate);
+    items.push(candidate);
+  }
+  return items;
+}
+
+/**
+ * Append a newly-stolen scoreable item id to the unlock list. Idempotent:
+ * archiving an id already present is a no-op (`added: false`) — the blueprint
+ * is stolen once. The input list is validated; the id must be a non-empty
+ * string. Returns a fresh list and whether anything changed.
+ */
+export function archiveScoreableItem(
+  list: readonly string[],
+  id: string
+): { list: string[]; added: boolean } {
+  const normalized = normalizeUnlockedScoreableItems(list);
+  if (typeof id !== 'string' || id.length === 0) {
+    throw new TypeError('archiveScoreableItem: id must be a non-empty string');
+  }
+  if (normalized.includes(id)) {
+    return { list: normalized, added: false };
+  }
+  return { list: [...normalized, id], added: true };
+}
diff --git a/tests/unit/DataStore.test.ts b/tests/unit/DataStore.test.ts
index 5de6c29..56b5147 100644
--- a/tests/unit/DataStore.test.ts
+++ b/tests/unit/DataStore.test.ts
@@ -64,3 +64,59 @@ test('DataStore migrates legacy data and archives idempotent capped campaign his
   };
   assert.equal(stored.campaignHistory?.length, CAMPAIGN_HISTORY_CAP);
 });
+
+function installStorage(seed: object): MemoryStorage {
+  const localStorage = new MemoryStorage();
+  (globalThis as unknown as { window: { localStorage: MemoryStorage } }).window = { localStorage };
+  localStorage.setItem(STORAGE_KEY, JSON.stringify(seed));
+  return localStorage;
+}
+
+test('DataStore normalizes an absent scoreable store to an empty list', async () => {
+  installStorage({ prefs: {}, runs: [], campaign: null });
+  const { default: dataStore } = await import('../../src/DataStore.js');
+  await dataStore.init();
+  assert.deepEqual(dataStore.unlockedScoreableItems, []);
+});
+
+test('DataStore archives scoreable items idempotently and persists them', async () => {
+  const localStorage = installStorage({ prefs: {}, runs: [], campaign: null });
+  const { default: dataStore } = await import('../../src/DataStore.js');
+  await dataStore.init();
+
+  let events = 0;
+  const onChange = (evt: Event) => {
+    if ((evt as CustomEvent).detail.key === 'unlockedScoreableItems') events++;
+  };
+  dataStore.addEventListener('change', onChange);
+
+  const first = dataStore.archiveScoreableItem('proto-exoframe');
+  assert.equal(first.added, true);
+  const second = dataStore.archiveScoreableItem('mil-spec-optics');
+  assert.equal(second.added, true);
+  assert.deepEqual(dataStore.unlockedScoreableItems, ['proto-exoframe', 'mil-spec-optics']);
+  assert.equal(events, 2, 'each new unlock emits one change event');
+
+  // Duplicate archival is a silent no-op: no event, no growth, no save churn.
+  const duplicate = dataStore.archiveScoreableItem('proto-exoframe');
+  assert.equal(duplicate.added, false);
+  assert.deepEqual(dataStore.unlockedScoreableItems, ['proto-exoframe', 'mil-spec-optics']);
+  assert.equal(events, 2, 'a duplicate archival emits no change event');
+  dataStore.removeEventListener('change', onChange);
+
+  const stored = JSON.parse(localStorage.getItem(STORAGE_KEY) ?? '{}') as {
+    unlockedScoreableItems?: string[];
+  };
+  assert.deepEqual(stored.unlockedScoreableItems, ['proto-exoframe', 'mil-spec-optics']);
+
+  // The getter hands back a defensive copy — callers can't mutate the store.
+  const snapshot = dataStore.unlockedScoreableItems;
+  snapshot.push('tampered');
+  assert.deepEqual(dataStore.unlockedScoreableItems, ['proto-exoframe', 'mil-spec-optics']);
+});
+
+test('DataStore throws on a structurally corrupt scoreable store rather than resetting', async () => {
+  installStorage({ prefs: {}, runs: [], campaign: null, unlockedScoreableItems: [1] });
+  const { default: dataStore } = await import('../../src/DataStore.js');
+  await assert.rejects(() => dataStore.init(), TypeError);
+});
diff --git a/tests/unit/game/scoreableUnlocks.test.ts b/tests/unit/game/scoreableUnlocks.test.ts
new file mode 100644
index 0000000..f761b24
--- /dev/null
+++ b/tests/unit/game/scoreableUnlocks.test.ts
@@ -0,0 +1,60 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  archiveScoreableItem,
+  normalizeUnlockedScoreableItems,
+} from '../../../src/game/scoreableUnlocks.js';
+
+test('normalizeUnlockedScoreableItems treats an absent store as empty', () => {
+  assert.deepEqual(normalizeUnlockedScoreableItems(undefined), []);
+});
+
+test('normalizeUnlockedScoreableItems passes through a valid id list, fresh copy', () => {
+  const input = ['proto-exoframe', 'mil-spec-optics'];
+  const result = normalizeUnlockedScoreableItems(input);
+  assert.deepEqual(result, ['proto-exoframe', 'mil-spec-optics']);
+  assert.notEqual(result, input, 'returns a fresh array, not the caller-owned reference');
+});
+
+test('normalizeUnlockedScoreableItems de-dupes preserving acquisition order', () => {
+  const result = normalizeUnlockedScoreableItems(['a', 'b', 'a', 'c', 'b']);
+  assert.deepEqual(result, ['a', 'b', 'c']);
+});
+
+test('normalizeUnlockedScoreableItems throws on a non-array store', () => {
+  assert.throws(() => normalizeUnlockedScoreableItems('proto-exoframe'), TypeError);
+  assert.throws(() => normalizeUnlockedScoreableItems({ 0: 'a' }), TypeError);
+});
+
+test('normalizeUnlockedScoreableItems throws on a non-string or empty element', () => {
+  assert.throws(() => normalizeUnlockedScoreableItems(['ok', 1]), TypeError);
+  assert.throws(() => normalizeUnlockedScoreableItems(['ok', '']), TypeError);
+  assert.throws(() => normalizeUnlockedScoreableItems(['ok', null]), TypeError);
+});
+
+test('archiveScoreableItem appends a new id to the end (acquisition order)', () => {
+  const { list, added } = archiveScoreableItem(['proto-exoframe'], 'mil-spec-optics');
+  assert.equal(added, true);
+  assert.deepEqual(list, ['proto-exoframe', 'mil-spec-optics']);
+});
+
+test('archiveScoreableItem is a no-op for a duplicate id', () => {
+  const start = ['proto-exoframe', 'mil-spec-optics'];
+  const { list, added } = archiveScoreableItem(start, 'proto-exoframe');
+  assert.equal(added, false);
+  assert.deepEqual(list, ['proto-exoframe', 'mil-spec-optics']);
+});
+
+test('archiveScoreableItem validates the input list', () => {
+  assert.throws(() => archiveScoreableItem('proto-exoframe' as unknown as string[], 'x'), TypeError);
+  assert.throws(() => archiveScoreableItem(['ok', ''], 'x'), TypeError);
+});
+
+test('archiveScoreableItem rejects an empty or non-string id', () => {
+  assert.throws(() => archiveScoreableItem(['proto-exoframe'], ''), TypeError);
+  assert.throws(
+    () => archiveScoreableItem(['proto-exoframe'], 7 as unknown as string),
+    TypeError
+  );
+});

From 68975036021acaefbb0c79cbb79c459676e574ef Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Thu, 25 Jun 2026 14:30:04 -0700
Subject: [PATCH 50/55] new scoreable gear targets

---
 docs/phase-3-plan.md                 |  53 ++++++++-
 src/game/Combat.ts                   |   4 +
 src/game/Crew.ts                     | 129 +++++++++++++++++++++
 src/game/constants.ts                |  39 +++++++
 src/game/hub/Finn.ts                 |   9 +-
 src/game/items.ts                    | 165 +++++++++++++++++----------
 src/game/persistence.ts              |  31 +++++
 src/shell/shellRuntime.ts            |   2 +-
 tests/unit/game/Campaign.test.ts     |  39 +++++++
 tests/unit/game/breach.test.ts       |   9 +-
 tests/unit/game/catalogSplit.test.ts | 137 ++++++++++++++++++++++
 tests/unit/game/hub/Finn.test.ts     |  53 +++------
 tests/unit/game/items.test.ts        | 140 +++++++++++++++++++++++
 13 files changed, 701 insertions(+), 109 deletions(-)
 create mode 100644 tests/unit/game/catalogSplit.test.ts

diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index aa9e74a..6d51a18 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -46,7 +46,7 @@ A new **player archetype** recruited mid-campaign (late Act 1 / start of Act 2),
 | P3.M3 — Cyberspace grid + ICE | ✅ Done (full ICE roster: Probe, Spark, Guardian) |
 | P3.M4 — Simstim flip (dual-deploy) | ✅ Done |
 | P3.M5 — The Score (climactic mission) | ✅ Done |
-| P3.M6 — Stolen Blueprints (shop rework + meta-progression) | 🔲 Not started |
+| P3.M6 — Stolen Blueprints (shop rework + meta-progression) | 🟡 Meta-store + catalog split shipped (M6.1–M6.2) |
 | P3.M7 — Chronicle (campaign narrative memory) | 🟡 End-summary foundation shipped |
 
 **Phase 3** is complete when:
@@ -449,7 +449,7 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 | Slice | Status | Change | Tests |
 |---|---|---|---|
 | **P3.M6.1 Meta-store** | ✅ | `DataStore` key `unlockedScoreableItems`; read at campaign init; idempotent archival; duplicate no-op; corrupt throws | round-trip, idempotent archival, duplicate no-op, corrupt throws |
-| **P3.M6.2 Item catalog split** | 🔲 | Define `DEFAULT_ITEMS` and `SCOREABLE_ITEMS` catalogs; retire `minRepTier` as shop gate; add at least 5 net-new scoreable items | catalog validation, no duplicate IDs, all items have required fields, `minRepTier` not read by shop |
+| **P3.M6.2 Item catalog split** | ✅ | Define `DEFAULT_ITEMS` and `SCOREABLE_ITEMS` catalogs; retire `minRepTier` as shop gate; add at least 5 net-new scoreable items (fully wired gear) | catalog validation, no duplicate IDs, all items have required fields, `minRepTier` not read by shop |
 | **P3.M6.3 Shop rework** | 🔲 | Shop stocks `DEFAULT_ITEMS + unlockedScoreableItems`; no rep gate; locked scoreable items not rendered | shop shows only default items when meta-store is empty; adds unlocked scoreable items as they accrue; rep change has no effect on stock |
 | **P3.M6.4 Score target rework** | 🔲 | `buildScoreContract()` draws from unacquired `SCOREABLE_ITEMS`; briefing copy reflects item; completion writes meta-store | available targets exclude acquired; retired items not rolled; store updated on complete |
 | **P3.M6.5 Abstract targets** | 🔲 | Exhausted-pool Score draws RNG credit payload from category set; seeded flavor; arc gates pass with empty scoreable pool | category selection determinism, arc unaffected, no meta-store write |
@@ -474,6 +474,55 @@ retrofitted in this slice). Tests: `scoreableUnlocks.test.ts`, plus three
 `DataStore.test.ts` cases (absent → `[]`, idempotent archival + persistence + defensive
 copy, corrupt store throws).
 
+**P3.M6.2 implementation note:** The single rep-gated `CATALOG` was split into two
+frozen arrays — `DEFAULT_ITEMS` (the four always-available consumables: Stim, Smoke,
+Incendiary, Breaching Charge) and `SCOREABLE_ITEMS` (the four former KNOWN-tier gear
+items plus **five net-new prototypes**). `minRepTier` was removed from the `Item` type
+and every descriptor; `getShopCatalog()` now takes no rep argument and returns a fresh
+copy of `DEFAULT_ITEMS` only (the unlocked-scoreable merge is M6.3's seam). `getItemById`
+searches both catalogs; `SCOREABLE_ITEM_IDS` (a frozen `Set`) is exported for M6.4's
+pool membership checks. Each scoreable item carries a `flavor` line (the stolen-prototype
+fiction) for M6.4 briefing copy.
+
+Rather than scale the existing four gear channels, the **five net-new items each fill a
+stat channel no crew gear previously touched** (a deliberate design choice — a heist reward
+should be a new capability, not a bigger number). Premium "bigger X" variants were
+explicitly rejected in design review: with random unlock order and no equip limit, a
+premium can arrive before its base and double-buying the base is identical, so the variant
+adds nothing.
+- **Monoblade** (`+1 melee dmg`) — the Razor's signature attack had zero gear support.
+  New `gear.meleeDamageBonus`, applied via a new `Crew.meleeAttackDamage()` that mirrors
+  `rangedAttackDamage()`; `Combat.attackerMeleeDamage` now prefers that method.
+- **Subdermal Plating** (`+1 damageReduction`) — the flat-armour channel (min-1 floor in
+  `Combat.applyDamageReduction`) existed but no crew gear set it. The live `damageReduction`
+  stat is the source of truth; `gear.armorBonus` tracks it for cap-clamping. This stat was
+  **not** carried by the campaign-crew snapshot, so `snapshotCrewMember`/`restoreCrewMember`
+  were extended to persist it (the in-job entity snapshot already round-tripped it).
+- **Reflex Booster** (`+1 maxAp`, hard-capped at 1) — the master action resource. `maxAp`
+  already round-trips on both save paths; `gear.apBonus` tracks. Immediate benefit (the
+  extra AP is usable the same turn), matching Armour Plating's `+hp`.
+- **Phase Shield Prototype** (`+1 shield/turn`) — re-grants `shieldHp` at the start of each
+  crew turn via a new `Crew.refreshAp()` override (the same hook the Razor uses to clear
+  stealth; `super.refreshAp` zeroes the shield, the override tops it back up). Free and
+  uncontested, unlike the Medic's AP-costed `MEDIC_SHIELD_HP`, so kept to +1.
+- **Regen Mesh** (`+1 HP/turn`) — heals real HP up to max each turn via the same refresh
+  hook; slow in-combat sustain distinct from the shield's resettable buffer.
+
+`refreshAp` regen is guarded (`alive` + amount `> 0`) so a flatlined body regenerates
+nothing (`heal`/`addShield` would otherwise throw on a corpse). The five new `Gear` fields
+are optional (`?? 0` reads) so pre-M6.2 gear snapshots restore cleanly; `repairGearForCrew`
+clamps the capped bonuses. Capped items follow the Ballistics Coil pattern (bonus = cap → a
+duplicate purchase is a harmless no-op). **Known transitional state:** between M6.2 and M6.3
+the shop shows only `DEFAULT_ITEMS`, so the former KNOWN gear is temporarily unbuyable until
+the M6.3 unlocked-item merge lands.
+
+**Follow-up (kaizen, tabled):** a **revive** path — un-flatline a crew member at the Hub for
+a steep Cred cost, zeroing their gear (and resetting the derived maxHp/maxAp/damageReduction
+to archetype base). Pure Hub economy + narrative, no combat-mechanics implications. Needs a
+new `Campaign.reviveMember()` and a delivery surface (Clinic service vs. Finn purchase — the
+shop target-picker currently excludes flatlined crew). Deferred to its own slice; revisit
+after M6.3/M6.4.
+
 **Recorded design decisions:**
 
 - **Why `minRepTier` is retired as a shop gate:** Rep-gated access was mechanical — the best gear was reachable by grinding rep without doing anything interesting. Two explicit catalogs make availability rules legible in the data rather than computed from a tier comparison at runtime.
diff --git a/src/game/Combat.ts b/src/game/Combat.ts
index 2ed61be..1c3941f 100644
--- a/src/game/Combat.ts
+++ b/src/game/Combat.ts
@@ -70,6 +70,10 @@ function attackerRangedDamage(attacker: Entity, override?: number): number {
 
 function attackerMeleeDamage(attacker: Entity, override?: number): number {
   if (override !== undefined) return override;
+  const meleeAttackDamage = (attacker as { meleeAttackDamage?: () => number }).meleeAttackDamage;
+  if (typeof meleeAttackDamage === 'function') {
+    return meleeAttackDamage.call(attacker);
+  }
   if ('meleeDamage' in attacker) {
     return (attacker as { meleeDamage: number }).meleeDamage;
   }
diff --git a/src/game/Crew.ts b/src/game/Crew.ts
index d9f5385..8482178 100644
--- a/src/game/Crew.ts
+++ b/src/game/Crew.ts
@@ -15,6 +15,16 @@ import {
   TURRET_DAMAGE,
   RANGED_DAMAGE_BONUS,
   RANGED_MAX_DAMAGE_BONUS,
+  MELEE_DAMAGE_BONUS,
+  MELEE_MAX_DAMAGE_BONUS,
+  ARMOR_BONUS,
+  MAX_ARMOR_BONUS,
+  AP_BONUS,
+  MAX_AP_BONUS,
+  SHIELD_REGEN,
+  MAX_SHIELD_REGEN,
+  HP_REGEN,
+  MAX_HP_REGEN,
   type FactionId,
 } from './constants.js';
 import { ITEM_ID } from './items.js';
@@ -33,6 +43,25 @@ export type Gear = {
   hitBonus: number;
   dodgeBonus: number;
   rangedDamageBonus: number;
+  /**
+   * Net-new scoreable channels (P3.M6.2). Optional so pre-M6.2 gear snapshots
+   * (which lack them) restore cleanly; consumers read `?? 0`.
+   *   - `meleeDamageBonus` — Monoblade; added in {@link Crew.meleeAttackDamage}.
+   *   - `armorBonus`       — Subdermal Plating; tracks the value applied to
+   *                          `damageReduction` (the live combat stat).
+   *   - `apBonus`          — Reflex Booster; tracks the value added to `maxAp`.
+   *   - `shieldRegen`      — Phase Shield; `shieldHp` re-granted each turn in
+   *                          {@link Crew.refreshAp}.
+   *   - `hpRegen`          — Regen Mesh; HP healed each turn in the same hook.
+   * `armorBonus`/`apBonus` mirror `maxHpBonus`: the live stat is the source of
+   * truth in combat, the bonus field exists for cap-clamping on restore.
+   * `shieldRegen`/`hpRegen` are pure per-turn effect rates (no live-stat twin).
+   */
+  meleeDamageBonus?: number;
+  armorBonus?: number;
+  apBonus?: number;
+  shieldRegen?: number;
+  hpRegen?: number;
 };
 
 /**
@@ -52,6 +81,11 @@ const createDefaultGear = (): Gear => ({
   hitBonus: 0,
   dodgeBonus: 0,
   rangedDamageBonus: 0,
+  meleeDamageBonus: 0,
+  armorBonus: 0,
+  apBonus: 0,
+  shieldRegen: 0,
+  hpRegen: 0,
 });
 
 /**
@@ -165,6 +199,46 @@ export class Crew extends Entity {
     return this.rangedDamage + this.effectiveRangedDamageBonus;
   }
 
+  /** Cap for {@link ITEM_ID.MONOBLADE} melee-damage bonus on this operator. */
+  get maxMeleeDamageBonus(): number {
+    return MELEE_MAX_DAMAGE_BONUS;
+  }
+
+  /** Capped Monoblade bonus for this operator's outgoing melee damage. */
+  get effectiveMeleeDamageBonus(): number {
+    return Math.min(this.gear?.meleeDamageBonus ?? 0, this.maxMeleeDamageBonus);
+  }
+
+  /**
+   * Outgoing melee damage for this crew member (archetype base + gear). Mirrors
+   * {@link rangedAttackDamage}; `Combat.resolveMelee` prefers this method over
+   * the bare `meleeDamage` getter so the Monoblade bonus lands without each
+   * archetype having to re-implement its `meleeDamage` override.
+   */
+  meleeAttackDamage(): number {
+    return this.meleeDamage + this.effectiveMeleeDamageBonus;
+  }
+
+  /** Cap for the {@link ITEM_ID.SUBDERMAL_PLATING} armour bonus. */
+  get maxArmorBonus(): number {
+    return MAX_ARMOR_BONUS;
+  }
+
+  /** Cap for the {@link ITEM_ID.REFLEX_BOOSTER} AP bonus. */
+  get maxApBonus(): number {
+    return MAX_AP_BONUS;
+  }
+
+  /** Cap for the {@link ITEM_ID.PHASE_SHIELD} per-turn shield regen. */
+  get maxShieldRegen(): number {
+    return MAX_SHIELD_REGEN;
+  }
+
+  /** Cap for the {@link ITEM_ID.REGEN_MESH} per-turn HP regen. */
+  get maxHpRegen(): number {
+    return MAX_HP_REGEN;
+  }
+
   /**
    * Stats for a player turret this crew member deploys (Tech). HP mirrors the
    * owner's current max (includes Armour Plating); damage uses the same coil
@@ -260,11 +334,66 @@ export class Crew extends Entity {
           this.maxRangedDamageBonus
         );
         break;
+      case ITEM_ID.MONOBLADE:
+        // Tracking-only bonus, read via `meleeAttackDamage`. Capped like the coil.
+        this.gear!.meleeDamageBonus = Math.min(
+          (this.gear!.meleeDamageBonus ?? 0) + MELEE_DAMAGE_BONUS,
+          this.maxMeleeDamageBonus
+        );
+        break;
+      case ITEM_ID.SUBDERMAL_PLATING: {
+        // Mirror Armour Plating: `damageReduction` is the live stat, `armorBonus`
+        // tracks it. Delta-apply so a capped second purchase is a no-op.
+        const next = Math.min((this.gear!.armorBonus ?? 0) + ARMOR_BONUS, this.maxArmorBonus);
+        this.damageReduction += next - (this.gear!.armorBonus ?? 0);
+        this.gear!.armorBonus = next;
+        break;
+      }
+      case ITEM_ID.REFLEX_BOOSTER: {
+        // `maxAp` is the live stat, `apBonus` tracks it. Immediate benefit: the
+        // extra AP is available this turn too (matches Armour Plating's +hp).
+        const next = Math.min((this.gear!.apBonus ?? 0) + AP_BONUS, this.maxApBonus);
+        const delta = next - (this.gear!.apBonus ?? 0);
+        this.maxAp += delta;
+        this.ap += delta;
+        this.gear!.apBonus = next;
+        break;
+      }
+      case ITEM_ID.PHASE_SHIELD:
+        // Per-turn effect rate — applied in `refreshAp`, not a live stat here.
+        this.gear!.shieldRegen = Math.min(
+          (this.gear!.shieldRegen ?? 0) + SHIELD_REGEN,
+          this.maxShieldRegen
+        );
+        break;
+      case ITEM_ID.REGEN_MESH:
+        this.gear!.hpRegen = Math.min((this.gear!.hpRegen ?? 0) + HP_REGEN, this.maxHpRegen);
+        break;
       default:
         throw new Error(`Crew.applyGear: unknown gear item "${itemId}"`);
     }
   }
 
+  /**
+   * Refresh AP at the start of this crew member's turn, then apply per-turn
+   * gear regen (P3.M6.2). `super.refreshAp` (Entity) zeroes `shieldHp`, so the
+   * Phase Shield re-grant here tops the buffer back to `shieldRegen` each turn
+   * — free and automatic, unlike the Medic's AP-costed top-up. Regen Mesh heals
+   * real HP up to max. Both are guarded: a flatlined/dead body regenerates
+   * nothing (`addShield`/`heal` would otherwise throw on a corpse).
+   *
+   * Razor overrides this to also clear stealth; its `super.refreshAp()` chains
+   * through here, so the Razor benefits from regen gear too.
+   */
+  override refreshAp(): void {
+    super.refreshAp();
+    if (!this.alive || !this.gear) return;
+    const hpRegen = this.gear.hpRegen ?? 0;
+    if (hpRegen > 0) this.heal(hpRegen);
+    const shieldRegen = this.gear.shieldRegen ?? 0;
+    if (shieldRegen > 0) this.addShield(shieldRegen);
+  }
+
   /**
    * Add a consumable to inventory for the next job. Initialises inventory if
    * null (purchase can happen before deploy). The consumable is a plain
diff --git a/src/game/constants.ts b/src/game/constants.ts
index 3f3d30c..945a064 100644
--- a/src/game/constants.ts
+++ b/src/game/constants.ts
@@ -360,6 +360,37 @@ export const BREACHING_CHARGE_RANGE = 1;
 export const TARGETING_BONUS = 0.1;
 export const DODGE_BONUS = 0.1;
 
+/**
+ * Net-new scoreable gear tuning (P3.M6.2). Each fills a stat channel that
+ * existing shop gear never touched — the reward fiction is a stolen prototype,
+ * not a bigger number on an existing chip (premium variants were rejected:
+ * random unlock order and no equip limit make "bigger X" incoherent). Caps
+ * mirror the {@link RANGED_DAMAGE_BONUS} pattern (bonus equals cap → a second
+ * purchase is a harmless no-op).
+ *
+ *   - **Monoblade** (`MELEE_DAMAGE_BONUS`) — the Razor's signature attack had no
+ *     gear path. +1 melee damage, applied via {@link Crew.meleeAttackDamage}.
+ *   - **Subdermal Plating** (`ARMOR_BONUS`) — flat `damageReduction` (min-1 floor
+ *     in `Combat.applyDamageReduction`); the channel existed but no crew gear set it.
+ *   - **Reflex Booster** (`AP_BONUS`) — +1 `maxAp`, the master action resource.
+ *     Capped hard at 1: two extra AP would warp the turn economy.
+ *   - **Phase Shield** (`SHIELD_REGEN`) — re-grants `shieldHp` at the start of each
+ *     crew turn via {@link Crew.refreshAp}. Free and uncontested (unlike the
+ *     Medic's AP-costed {@link MEDIC_SHIELD_HP}), so kept to +1.
+ *   - **Regen Mesh** (`HP_REGEN`) — heals real HP each turn via the same refresh
+ *     hook; slow in-combat sustain distinct from the shield's resettable buffer.
+ */
+export const MELEE_DAMAGE_BONUS = 1;
+export const MELEE_MAX_DAMAGE_BONUS = 1;
+export const ARMOR_BONUS = 1;
+export const MAX_ARMOR_BONUS = 1;
+export const AP_BONUS = 1;
+export const MAX_AP_BONUS = 1;
+export const SHIELD_REGEN = 1;
+export const MAX_SHIELD_REGEN = 1;
+export const HP_REGEN = 1;
+export const MAX_HP_REGEN = 1;
+
 /**
  * Legacy flat salvage-to-Cred rate. Retained for backward-compat references
  * (e.g. TRUSTED tier rewardFloorBump calculation). New sell paths use the
@@ -391,6 +422,14 @@ export const SHOP_COST = Object.freeze({
   TARGETING_CHIP: 80,
   REFLEX_WEAVE: 80,
   BALLISTICS_COIL: 80,
+  // Net-new scoreable gear (P3.M6.2) — priced above baseline KNOWN gear; the
+  // reward is the unlock, the Cred cost is the install. Reflex Booster (+1 AP)
+  // is the priciest, matching its outsized impact on the turn economy.
+  MONOBLADE: 90,
+  SUBDERMAL_PLATING: 100,
+  REFLEX_BOOSTER: 150,
+  PHASE_SHIELD: 110,
+  REGEN_MESH: 120,
 });
 
 /** Patch clinic — Creds per HP restored (partial heal not offered). */
diff --git a/src/game/hub/Finn.ts b/src/game/hub/Finn.ts
index 7ff4af3..3a84b9a 100644
--- a/src/game/hub/Finn.ts
+++ b/src/game/hub/Finn.ts
@@ -37,10 +37,11 @@ export class Finn extends Entity {
   }
 
   /**
-   * Return the shop catalog filtered by the player's current Rep tier.
-   * Higher Rep unlocks more items — see `getShopCatalog` for tier mapping.
+   * Return Finn's purchasable stock. Rep no longer gates the shop (P3.M6.2);
+   * this is the always-available {@link DEFAULT_ITEMS}. Unlocked scoreable
+   * items are folded in by the M6.3 shop rework.
    */
-  catalog(rep: number = 20) {
-    return getShopCatalog(rep);
+  catalog() {
+    return getShopCatalog();
   }
 }
diff --git a/src/game/items.ts b/src/game/items.ts
index 7cfe3b1..e7cb64f 100644
--- a/src/game/items.ts
+++ b/src/game/items.ts
@@ -24,9 +24,11 @@ import {
   TARGETING_BONUS,
   DODGE_BONUS,
   RANGED_DAMAGE_BONUS,
-  REP_TIER,
-  repTierForRep,
-  type RepTierId,
+  MELEE_DAMAGE_BONUS,
+  ARMOR_BONUS,
+  AP_BONUS,
+  SHIELD_REGEN,
+  HP_REGEN,
 } from './constants.js';
 
 export type Item = {
@@ -50,17 +52,11 @@ export type Item = {
    */
   needsAim?: boolean;
   /**
-   * Minimum Rep tier required for this item to appear in Finn's shop (P2.5.M5.2).
-   * Items below the player's current tier are hidden. Progression:
-   *   BURNED  → Stim only
-   *   UNKNOWN → + Smoke Charge, Incendiary Bomb
-   *   KNOWN   → + Armour Plating, Targeting Chip, Reflex Weave
-   *   TRUSTED → all (future expansion)
-   *
-   * Optional on the type because inventory-stored items (consumable records)
-   * don't carry shop metadata.
+   * Heist fiction for a scoreable item — one line describing what was stolen
+   * (P3.M6.2). Surfaced by the Score briefing copy in M6.4. Present on every
+   * {@link SCOREABLE_ITEMS} entry, absent on default stock and consumable records.
    */
-  minRepTier?: RepTierId;
+  flavor?: string;
   unique?: boolean;
   metaGate?: string;
 };
@@ -80,20 +76,33 @@ export const ITEM_ID = Object.freeze({
   TARGETING_CHIP: 'targeting-chip',
   REFLEX_WEAVE: 'reflex-weave',
   BALLISTICS_COIL: 'ballistics-coil',
+  // Net-new scoreable gear (P3.M6.2) — each fills a previously-untouched stat
+  // channel (melee dmg, flat armour, AP, shield regen, HP regen).
+  MONOBLADE: 'monoblade',
+  SUBDERMAL_PLATING: 'subdermal-plating',
+  REFLEX_BOOSTER: 'reflex-booster',
+  PHASE_SHIELD: 'phase-shield',
+  REGEN_MESH: 'regen-mesh',
 });
 
 /**
- * Full item catalog. Each entry is a frozen descriptor:
+ * Two explicit catalogs replace the old single rep-gated list (P3.M6.2). Each
+ * entry is a frozen descriptor:
  *   - `id`          — unique key, matches ITEM_ID
  *   - `label`       — display name for the shop UI
  *   - `scope`       — ITEM_SCOPE value
  *   - `cost`        — Cred price
  *   - `description` — one-line effect summary for the shop
  *   - `needsTarget` — true if purchase requires a target crew member
+ *   - `needsAim`    — true if the consumable resolves along an aim direction
+ *   - `flavor`      — (scoreable only) one line describing the stolen prototype
  *   - `metaGate`    — if set, item only appears when `meta[metaGate]` is truthy
  *   - `unique`      — if true, can only be purchased once (meta-scope items)
+ *
+ * **`DEFAULT_ITEMS`** — Finn's permanent stock. Always available from campaign
+ * start, no condition, no gate (the old BURNED/UNKNOWN consumables).
  */
-const CATALOG: readonly Item[] = Object.freeze([
+export const DEFAULT_ITEMS: readonly Item[] = Object.freeze([
   Object.freeze({
     id: ITEM_ID.STIM,
     label: 'Stim',
@@ -101,7 +110,6 @@ const CATALOG: readonly Item[] = Object.freeze([
     cost: SHOP_COST.STIM,
     description: `Restores ${STIM_HEAL} HP to the deployed crew member. Single use.`,
     needsTarget: true,
-    minRepTier: REP_TIER.BURNED,
   }),
   Object.freeze({
     id: ITEM_ID.SMOKE_CHARGE,
@@ -110,7 +118,6 @@ const CATALOG: readonly Item[] = Object.freeze([
     cost: SHOP_COST.SMOKE_CHARGE,
     description: `Blocks LOS in radius ${SMOKE_RADIUS} for 1 turn. Single use.`,
     needsTarget: true,
-    minRepTier: REP_TIER.UNKNOWN,
   }),
   Object.freeze({
     id: ITEM_ID.INCENDIARY,
@@ -120,7 +127,6 @@ const CATALOG: readonly Item[] = Object.freeze([
     description: `Throw ${INCENDIARY_THROW_DIST} tiles in a chosen direction; ignites a persistent hazard cluster. Single use.`,
     needsTarget: true,
     needsAim: true,
-    minRepTier: REP_TIER.UNKNOWN,
   }),
   Object.freeze({
     id: ITEM_ID.BREACHING_CHARGE,
@@ -130,8 +136,18 @@ const CATALOG: readonly Item[] = Object.freeze([
     description: `Destroy a wall, locked door, or reinforced objective within ${BREACHING_CHARGE_RANGE} tile. Single use.`,
     needsTarget: true,
     needsAim: true,
-    minRepTier: REP_TIER.UNKNOWN,
   }),
+]);
+
+/**
+ * **`SCOREABLE_ITEMS`** — each a distinct Score heist target, unlocked
+ * permanently by stealing its blueprint (the unlock writes to the meta-store in
+ * M6.4). Not shown in Finn's shop until acquired. The first four are the old
+ * KNOWN-tier gear; the rest (P3.M6.2) are net-new prototypes that each fill a
+ * stat channel existing gear never touched — melee damage, flat armour, AP,
+ * shield regen, and HP regen.
+ */
+export const SCOREABLE_ITEMS: readonly Item[] = Object.freeze([
   Object.freeze({
     id: ITEM_ID.ARMOUR_PLATING,
     label: 'Armour Plating',
@@ -139,16 +155,7 @@ const CATALOG: readonly Item[] = Object.freeze([
     cost: SHOP_COST.ARMOUR_PLATING,
     description: "+1 max HP (Tech's turrets deploy at that max HP).",
     needsTarget: true,
-    minRepTier: REP_TIER.KNOWN,
-  }),
-  Object.freeze({
-    id: ITEM_ID.REFLEX_WEAVE,
-    label: 'Reflex Weave',
-    scope: ITEM_SCOPE.CAMPAIGN,
-    cost: SHOP_COST.REFLEX_WEAVE,
-    description: `+${(DODGE_BONUS * 100).toFixed(0)}% melee dodge chance.`,
-    needsTarget: true,
-    minRepTier: REP_TIER.KNOWN,
+    flavor: 'Corp-issue trauma plating, lifted straight off a fabrication line.',
   }),
   Object.freeze({
     id: ITEM_ID.TARGETING_CHIP,
@@ -157,7 +164,16 @@ const CATALOG: readonly Item[] = Object.freeze([
     cost: SHOP_COST.TARGETING_CHIP,
     description: `+${(TARGETING_BONUS * 100).toFixed(0)}% ranged hit chance.`,
     needsTarget: true,
-    minRepTier: REP_TIER.KNOWN,
+    flavor: 'A smartgun targeting co-processor, pulled still-warm from a test rig.',
+  }),
+  Object.freeze({
+    id: ITEM_ID.REFLEX_WEAVE,
+    label: 'Reflex Weave',
+    scope: ITEM_SCOPE.CAMPAIGN,
+    cost: SHOP_COST.REFLEX_WEAVE,
+    description: `+${(DODGE_BONUS * 100).toFixed(0)}% melee dodge chance.`,
+    needsTarget: true,
+    flavor: "Subdermal reflex mesh, cut from an exec's private medbay.",
   }),
   Object.freeze({
     id: ITEM_ID.BALLISTICS_COIL,
@@ -166,43 +182,76 @@ const CATALOG: readonly Item[] = Object.freeze([
     cost: SHOP_COST.BALLISTICS_COIL,
     description: `+${RANGED_DAMAGE_BONUS} ranged damage (Tech's turrets inherit the bonus).`,
     needsTarget: true,
-    minRepTier: REP_TIER.KNOWN,
+    flavor: 'An accelerator coil prised off a prototype railgun bench.',
+  }),
+  Object.freeze({
+    id: ITEM_ID.MONOBLADE,
+    label: 'Monoblade',
+    scope: ITEM_SCOPE.CAMPAIGN,
+    cost: SHOP_COST.MONOBLADE,
+    description: `+${MELEE_DAMAGE_BONUS} melee damage.`,
+    needsTarget: true,
+    flavor: 'A monomolecular blade schematic — an edge that never dulls.',
+  }),
+  Object.freeze({
+    id: ITEM_ID.SUBDERMAL_PLATING,
+    label: 'Subdermal Plating',
+    scope: ITEM_SCOPE.CAMPAIGN,
+    cost: SHOP_COST.SUBDERMAL_PLATING,
+    description: `+${ARMOR_BONUS} armour — reduces every incoming hit (minimum 1 damage).`,
+    needsTarget: true,
+    flavor: 'Military subdermal armour, woven from layered impact ceramics.',
+  }),
+  Object.freeze({
+    id: ITEM_ID.REFLEX_BOOSTER,
+    label: 'Reflex Booster',
+    scope: ITEM_SCOPE.CAMPAIGN,
+    cost: SHOP_COST.REFLEX_BOOSTER,
+    description: `+${AP_BONUS} max AP. One per operator.`,
+    needsTarget: true,
+    flavor: 'A black-clinic adrenal booster — the world slows when it fires.',
+  }),
+  Object.freeze({
+    id: ITEM_ID.PHASE_SHIELD,
+    label: 'Phase Shield Prototype',
+    scope: ITEM_SCOPE.CAMPAIGN,
+    cost: SHOP_COST.PHASE_SHIELD,
+    description: `Regenerates +${SHIELD_REGEN} shield at the start of each turn (absorbs damage before HP).`,
+    needsTarget: true,
+    flavor: 'A phase-shield emitter that bleeds incoming kinetic force into a flicker field.',
+  }),
+  Object.freeze({
+    id: ITEM_ID.REGEN_MESH,
+    label: 'Regen Mesh',
+    scope: ITEM_SCOPE.CAMPAIGN,
+    cost: SHOP_COST.REGEN_MESH,
+    description: `Regenerates +${HP_REGEN} HP at the start of each turn (up to max HP).`,
+    needsTarget: true,
+    flavor: 'A subdermal nanite mesh that knits wounds closed mid-firefight.',
   }),
 ]);
 
-/**
- * Rep tier ordering for comparison — index 0 is lowest tier. Used by
- * `getShopCatalog` to filter items whose `minRepTier` exceeds the player's
- * current tier.
- */
-const TIER_ORDER: readonly RepTierId[] = [
-  REP_TIER.BURNED,
-  REP_TIER.UNKNOWN,
-  REP_TIER.KNOWN,
-  REP_TIER.TRUSTED,
-];
+/** Frozen id set for the scoreable pool — O(1) membership checks (M6.4). */
+export const SCOREABLE_ITEM_IDS: ReadonlySet<string> = Object.freeze(
+  new Set(SCOREABLE_ITEMS.map(item => item.id))
+) as ReadonlySet<string>;
+
+/** Every descriptor, both catalogs — backing store for {@link getItemById}. */
+const CATALOG: readonly Item[] = Object.freeze([...DEFAULT_ITEMS, ...SCOREABLE_ITEMS]);
 
 /**
- * Return the shop catalog filtered by the player's current Rep. Items whose
- * `minRepTier` exceeds the player's tier are hidden — the shop grows as
- * standing improves.
- *
- * @param rep — campaign Rep value (0–100). Defaults to REP.START (20) so
- *   callers that omit it see the UNKNOWN-tier catalog.
+ * Return Finn's always-available stock — the {@link DEFAULT_ITEMS}. Rep no
+ * longer gates the shop (P3.M6.2 retired `minRepTier`); unlocked
+ * {@link SCOREABLE_ITEMS} are folded in by the shop rework in M6.3, which reads
+ * the meta-progression store rather than any tier comparison.
  */
-export function getShopCatalog(rep: number = 20) {
-  const currentTier = repTierForRep(rep);
-  const currentIndex = TIER_ORDER.indexOf(currentTier.id);
-  return CATALOG.filter(item => {
-    const itemTier = item.minRepTier ?? REP_TIER.BURNED;
-    const itemIndex = TIER_ORDER.indexOf(itemTier);
-    return itemIndex <= currentIndex;
-  });
+export function getShopCatalog(): Item[] {
+  return [...DEFAULT_ITEMS];
 }
 
 /**
- * Look up a single item descriptor by id. Throws on unknown id — no silent
- * fallback for a typo in a purchase call.
+ * Look up a single item descriptor by id, across both catalogs. Throws on
+ * unknown id — no silent fallback for a typo in a purchase call.
  */
 export function getItemById(itemId: string) {
   const item = CATALOG.find(i => i.id === itemId);
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index 3e6941d..4f4a35e 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -899,6 +899,12 @@ type CampaignCrewSnapshot = {
   maxHp: number;
   ap: number;
   maxAp: number;
+  /**
+   * P3.M6.2: live `damageReduction` (Subdermal Plating armour). Persisted like
+   * `maxHp`/`maxAp` — the live stat is the source of truth, `gear.armorBonus`
+   * only tracks it for cap-clamping. Absent on pre-M6.2 saves → restores to 0.
+   */
+  damageReduction?: number;
   alive: boolean;
   inventory: Inventory | null;
   gear: Gear | null;
@@ -1694,6 +1700,29 @@ function repairGearForCrew(member: Crew) {
   if (rangedBonus > member.maxRangedDamageBonus) {
     gear.rangedDamageBonus = member.maxRangedDamageBonus;
   }
+  // P3.M6.2 scoreable channels. armorBonus/apBonus only track their live stats
+  // (damageReduction/maxAp, restored directly); clamp the tracking value so a
+  // tampered save can't carry an over-cap bonus forward.
+  const meleeBonus = gear.meleeDamageBonus ?? 0;
+  if (meleeBonus > member.maxMeleeDamageBonus) {
+    gear.meleeDamageBonus = member.maxMeleeDamageBonus;
+  }
+  const armorBonus = gear.armorBonus ?? 0;
+  if (armorBonus > member.maxArmorBonus) {
+    gear.armorBonus = member.maxArmorBonus;
+  }
+  const apBonus = gear.apBonus ?? 0;
+  if (apBonus > member.maxApBonus) {
+    gear.apBonus = member.maxApBonus;
+  }
+  const shieldRegen = gear.shieldRegen ?? 0;
+  if (shieldRegen > member.maxShieldRegen) {
+    gear.shieldRegen = member.maxShieldRegen;
+  }
+  const hpRegen = gear.hpRegen ?? 0;
+  if (hpRegen > member.maxHpRegen) {
+    gear.hpRegen = member.maxHpRegen;
+  }
 }
 
 function snapshotCrewMember(member: Crew): CampaignCrewSnapshot {
@@ -1707,6 +1736,7 @@ function snapshotCrewMember(member: Crew): CampaignCrewSnapshot {
     maxHp: member.maxHp,
     ap: member.ap,
     maxAp: member.maxAp,
+    damageReduction: member.damageReduction,
     alive: !!member.alive,
     inventory: member.inventory,
     gear: member.gear,
@@ -1792,6 +1822,7 @@ function restoreCrewMember(rec: CampaignCrewSnapshot): Crew {
     gear: rec.gear ?? null,
     maxHp: rec.maxHp,
     maxAp: rec.maxAp,
+    damageReduction: rec.damageReduction ?? 0,
     // P3.M3.3: Decker cyber stats (validated; throws on a non-decker record).
     ...readCampaignCrewCyber(rec),
   });
diff --git a/src/shell/shellRuntime.ts b/src/shell/shellRuntime.ts
index d5162d1..3d9eaa7 100644
--- a/src/shell/shellRuntime.ts
+++ b/src/shell/shellRuntime.ts
@@ -826,7 +826,7 @@ function onBriefingDeploy(evt: Event) {
 
 function presentFinnShop() {
   if (!campaign || !campaign.finn) return;
-  const catalog = campaign.finn.catalog(campaign.rep);
+  const catalog = campaign.finn.catalog();
   finnShopEl.setCatalog(catalog, campaign.crew, {
     credits: campaign.credits,
     salvage: campaign.salvage,
diff --git a/tests/unit/game/Campaign.test.ts b/tests/unit/game/Campaign.test.ts
index c637907..7f3a28f 100644
--- a/tests/unit/game/Campaign.test.ts
+++ b/tests/unit/game/Campaign.test.ts
@@ -540,10 +540,49 @@ test('crew gear survives campaign snapshot/restore round-trip', () => {
     hitBonus: 0.1,
     dodgeBonus: 0,
     rangedDamageBonus: 0,
+    meleeDamageBonus: 0,
+    armorBonus: 0,
+    apBonus: 0,
+    shieldRegen: 0,
+    hpRegen: 0,
   });
   assert.equal(restoredMember.maxHp, member.maxHp);
 });
 
+test('net-new scoreable gear survives campaign round-trip', () => {
+  // Subdermal Plating writes the live `damageReduction` stat, which the
+  // campaign-crew snapshot did NOT carry before P3.M6.2 — guard the round-trip.
+  // Phase Shield / Regen Mesh are pure per-turn rates on `gear`.
+  const campaign = new Campaign({
+    seed: 42,
+    credits:
+      SHOP_COST.SUBDERMAL_PLATING +
+      SHOP_COST.REFLEX_BOOSTER +
+      SHOP_COST.MONOBLADE +
+      SHOP_COST.PHASE_SHIELD +
+      SHOP_COST.REGEN_MESH,
+  });
+  const member = campaign.crew[0];
+  const baseMaxAp = member.maxAp;
+  campaign.purchase({ itemId: 'subdermal-plating', targetMemberId: member.id });
+  campaign.purchase({ itemId: 'reflex-booster', targetMemberId: member.id });
+  campaign.purchase({ itemId: 'monoblade', targetMemberId: member.id });
+  campaign.purchase({ itemId: 'phase-shield', targetMemberId: member.id });
+  campaign.purchase({ itemId: 'regen-mesh', targetMemberId: member.id });
+  assert.equal(member.damageReduction, 1);
+  assert.equal(member.maxAp, baseMaxAp + 1);
+
+  const restored = restoreCampaign(snapshotCampaign(campaign)).crew[0];
+  assert.equal(restored.damageReduction, 1, 'armour (damageReduction) round-trips');
+  assert.equal(restored.maxAp, baseMaxAp + 1, 'reflex booster maxAp round-trips');
+  assert.equal(restored.gear.armorBonus, 1);
+  assert.equal(restored.gear.apBonus, 1);
+  assert.equal(restored.gear.meleeDamageBonus, 1);
+  assert.equal(restored.gear.shieldRegen, 1, 'phase shield regen round-trips');
+  assert.equal(restored.gear.hpRegen, 1, 'regen mesh round-trips');
+  assert.equal(restored.meleeAttackDamage(), member.meleeAttackDamage());
+});
+
 test('meta state survives campaign snapshot/restore round-trip', () => {
   // meta upgrades removed, but meta is still a plain Record that can
   // carry arbitrary keys (future features, dead legacy data). Prove the
diff --git a/tests/unit/game/breach.test.ts b/tests/unit/game/breach.test.ts
index 39bd1c1..181bb0b 100644
--- a/tests/unit/game/breach.test.ts
+++ b/tests/unit/game/breach.test.ts
@@ -19,7 +19,7 @@ import { detonateBreachingCharge } from '../../../src/game/breachBlast.js';
 import { runPlayerAftermathSteps } from '../../../src/game/combatTurnPipeline.js';
 import { EVENT } from '../../../src/game/events.js';
 import { EventBus } from '../../../src/game/events.js';
-import { BREACH_BLAST_DAMAGE, REP, TILE } from '../../../src/game/constants.js';
+import { BREACH_BLAST_DAMAGE, TILE } from '../../../src/game/constants.js';
 import { Rng } from '../../../src/rng.js';
 import { testContractContext } from './contractTestUtils.js';
 import type { Contract } from '../../../src/game/hub/Curator.js';
@@ -348,10 +348,9 @@ test('armed breaching charge round-trips through run snapshots', () => {
   assert.equal(charges.length, 1);
 });
 
-test('breaching charge appears in Finn catalog at UNKNOWN tier and is aimed', () => {
-  const item = getShopCatalog(REP.START).find(entry => entry.id === ITEM_ID.BREACHING_CHARGE);
+test('breaching charge is default Finn stock and is aimed', () => {
+  const item = getShopCatalog().find(entry => entry.id === ITEM_ID.BREACHING_CHARGE);
 
   assert.ok(item);
-  assert.equal(item.needsAim, true);
-  assert.equal(item.minRepTier, 'UNKNOWN');
+  assert.equal(item?.needsAim, true);
 });
diff --git a/tests/unit/game/catalogSplit.test.ts b/tests/unit/game/catalogSplit.test.ts
new file mode 100644
index 0000000..e0d7f29
--- /dev/null
+++ b/tests/unit/game/catalogSplit.test.ts
@@ -0,0 +1,137 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  DEFAULT_ITEMS,
+  SCOREABLE_ITEMS,
+  SCOREABLE_ITEM_IDS,
+  ITEM_ID,
+  ITEM_SCOPE,
+  getShopCatalog,
+  getItemById,
+  type Item,
+} from '../../../src/game/items.js';
+
+// ---------------------------------------------------------------------------
+// P3.M6.2 — Item catalog split (DEFAULT_ITEMS vs SCOREABLE_ITEMS)
+// ---------------------------------------------------------------------------
+
+const REQUIRED_FIELDS: (keyof Item)[] = [
+  'id',
+  'label',
+  'scope',
+  'cost',
+  'description',
+  'needsTarget',
+];
+
+function assertWellFormed(item: Item) {
+  for (const field of REQUIRED_FIELDS) {
+    assert.ok(
+      item[field] !== undefined && item[field] !== null,
+      `item "${item.id}" missing required field "${field}"`
+    );
+  }
+  assert.equal(typeof item.id, 'string');
+  assert.ok(item.id.length > 0, `item has empty id`);
+  assert.equal(typeof item.label, 'string');
+  assert.ok(item.label.length > 0, `item "${item.id}" has empty label`);
+  assert.equal(typeof item.cost, 'number');
+  assert.ok(Number.isInteger(item.cost) && item.cost > 0, `item "${item.id}" cost must be > 0`);
+  assert.equal(typeof item.needsTarget, 'boolean');
+  assert.ok(
+    Object.values(ITEM_SCOPE).includes(item.scope),
+    `item "${item.id}" has invalid scope "${item.scope}"`
+  );
+}
+
+test('every DEFAULT_ITEMS entry is well-formed', () => {
+  assert.ok(DEFAULT_ITEMS.length > 0);
+  for (const item of DEFAULT_ITEMS) assertWellFormed(item);
+});
+
+test('every SCOREABLE_ITEMS entry is well-formed', () => {
+  assert.ok(SCOREABLE_ITEMS.length > 0);
+  for (const item of SCOREABLE_ITEMS) assertWellFormed(item);
+});
+
+test('no item id is duplicated within or across the two catalogs', () => {
+  const all = [...DEFAULT_ITEMS, ...SCOREABLE_ITEMS].map(i => i.id);
+  const unique = new Set(all);
+  assert.equal(unique.size, all.length, `duplicate item id(s): ${all.join(', ')}`);
+});
+
+test('the two catalogs are disjoint (no item is both default and scoreable)', () => {
+  const defaultIds = new Set(DEFAULT_ITEMS.map(i => i.id));
+  for (const item of SCOREABLE_ITEMS) {
+    assert.ok(!defaultIds.has(item.id), `"${item.id}" appears in both catalogs`);
+  }
+});
+
+test('scoreable pool has at least 5 net-new items beyond the original KNOWN gear', () => {
+  // The original rep-gated KNOWN gear that became scoreable.
+  const ORIGINAL_KNOWN = new Set([
+    ITEM_ID.ARMOUR_PLATING,
+    ITEM_ID.TARGETING_CHIP,
+    ITEM_ID.REFLEX_WEAVE,
+    ITEM_ID.BALLISTICS_COIL,
+  ]);
+  const netNew = SCOREABLE_ITEMS.filter(i => !ORIGINAL_KNOWN.has(i.id));
+  assert.ok(netNew.length >= 5, `expected >= 5 net-new scoreable items, found ${netNew.length}`);
+  // Pool sized for multi-campaign variety (plan: 8–12 total).
+  assert.ok(SCOREABLE_ITEMS.length >= 8 && SCOREABLE_ITEMS.length <= 12);
+});
+
+test('every scoreable item carries a heist flavor line; default items do not', () => {
+  for (const item of SCOREABLE_ITEMS) {
+    assert.equal(typeof item.flavor, 'string', `scoreable "${item.id}" missing flavor`);
+    assert.ok(item.flavor!.length > 0, `scoreable "${item.id}" has empty flavor`);
+  }
+  for (const item of DEFAULT_ITEMS) {
+    assert.equal(item.flavor, undefined, `default "${item.id}" should not carry heist flavor`);
+  }
+});
+
+test('SCOREABLE_ITEM_IDS matches the SCOREABLE_ITEMS pool exactly', () => {
+  assert.equal(SCOREABLE_ITEM_IDS.size, SCOREABLE_ITEMS.length);
+  for (const item of SCOREABLE_ITEMS) {
+    assert.ok(SCOREABLE_ITEM_IDS.has(item.id), `id set missing "${item.id}"`);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// getShopCatalog — rep no longer gates; only DEFAULT_ITEMS until M6.3
+// ---------------------------------------------------------------------------
+
+test('getShopCatalog returns exactly the default items (no rep gate)', () => {
+  const catalog = getShopCatalog();
+  assert.deepEqual(catalog.map(i => i.id).sort(), DEFAULT_ITEMS.map(i => i.id).sort());
+});
+
+test('getShopCatalog never surfaces a scoreable item (locked until unlocked)', () => {
+  const shopIds = new Set(getShopCatalog().map(i => i.id));
+  for (const item of SCOREABLE_ITEMS) {
+    assert.ok(!shopIds.has(item.id), `scoreable "${item.id}" leaked into default shop stock`);
+  }
+});
+
+test('getShopCatalog takes no rep argument and is independent of standing', () => {
+  // Signature regression guard: the rep-gated overload is gone. Calling with a
+  // stray argument is a no-op rather than a tier filter.
+  assert.equal(getShopCatalog.length, 0);
+  const a = getShopCatalog();
+  const b = (getShopCatalog as (rep?: number) => Item[])(100);
+  assert.deepEqual(
+    a.map(i => i.id),
+    b.map(i => i.id)
+  );
+  // Returns a fresh array each call — callers may mutate without corrupting source.
+  assert.notEqual(a, b);
+});
+
+test('getItemById resolves across both catalogs and throws on unknown', () => {
+  assert.equal(getItemById(ITEM_ID.STIM).id, ITEM_ID.STIM); // default
+  assert.equal(getItemById(ITEM_ID.MONOBLADE).id, ITEM_ID.MONOBLADE); // scoreable net-new
+  assert.equal(getItemById(ITEM_ID.ARMOUR_PLATING).id, ITEM_ID.ARMOUR_PLATING); // scoreable original
+  assert.throws(() => getItemById('unobtanium'), /unknown item/i);
+});
diff --git a/tests/unit/game/hub/Finn.test.ts b/tests/unit/game/hub/Finn.test.ts
index 7600fd7..4def425 100644
--- a/tests/unit/game/hub/Finn.test.ts
+++ b/tests/unit/game/hub/Finn.test.ts
@@ -27,60 +27,35 @@ test('Finn is immobile — refreshAp keeps AP at 0', () => {
   assert.equal(f.canAfford(1), false);
 });
 
-test('Finn.catalog at TRUSTED rep returns the full shop catalog', () => {
+test('Finn.catalog returns the default consumable stock, no rep gate (P3.M6.2)', () => {
   const f = new Finn();
-  const items = f.catalog(85); // TRUSTED tier
+  const items = f.catalog();
   assert.ok(Array.isArray(items));
-  assert.ok(items.length > 0);
-  const ids = items.map(i => i.id);
-  assert.ok(ids.includes(ITEM_ID.STIM));
-  assert.ok(ids.includes(ITEM_ID.SMOKE_CHARGE));
-  assert.ok(ids.includes(ITEM_ID.INCENDIARY));
-  assert.ok(ids.includes(ITEM_ID.BREACHING_CHARGE));
-  assert.ok(ids.includes(ITEM_ID.ARMOUR_PLATING));
-  assert.ok(ids.includes(ITEM_ID.TARGETING_CHIP));
-  assert.ok(ids.includes(ITEM_ID.REFLEX_WEAVE));
-});
-
-test('Finn.catalog at BURNED rep only shows Stim', () => {
-  const f = new Finn();
-  const items = f.catalog(5); // BURNED tier
-  const ids = items.map(i => i.id);
-  assert.equal(items.length, 1);
-  assert.ok(ids.includes(ITEM_ID.STIM));
-});
-
-test('Finn.catalog at UNKNOWN rep shows Stim + Smoke + Incendiary + Breach', () => {
-  const f = new Finn();
-  const items = f.catalog(25); // UNKNOWN tier
   const ids = items.map(i => i.id);
   assert.equal(items.length, 4);
   assert.ok(ids.includes(ITEM_ID.STIM));
   assert.ok(ids.includes(ITEM_ID.SMOKE_CHARGE));
   assert.ok(ids.includes(ITEM_ID.INCENDIARY));
   assert.ok(ids.includes(ITEM_ID.BREACHING_CHARGE));
-  assert.ok(!ids.includes(ITEM_ID.ARMOUR_PLATING));
 });
 
-test('Finn.catalog at KNOWN rep adds gear items', () => {
+test('Finn.catalog never surfaces a locked scoreable item', () => {
   const f = new Finn();
-  const items = f.catalog(55); // KNOWN tier
-  const ids = items.map(i => i.id);
-  assert.equal(items.length, 8);
-  assert.ok(ids.includes(ITEM_ID.ARMOUR_PLATING));
-  assert.ok(ids.includes(ITEM_ID.TARGETING_CHIP));
-  assert.ok(ids.includes(ITEM_ID.REFLEX_WEAVE));
-  assert.ok(ids.includes(ITEM_ID.BALLISTICS_COIL));
+  const ids = f.catalog().map(i => i.id);
+  // The former KNOWN-tier gear is now scoreable — locked until a Score unlock.
+  assert.ok(!ids.includes(ITEM_ID.ARMOUR_PLATING));
+  assert.ok(!ids.includes(ITEM_ID.TARGETING_CHIP));
+  assert.ok(!ids.includes(ITEM_ID.REFLEX_WEAVE));
+  assert.ok(!ids.includes(ITEM_ID.BALLISTICS_COIL));
 });
 
 // ---------------------------------------------------------------------------
 // Item catalog (pure functions)
 // ---------------------------------------------------------------------------
 
-test('getShopCatalog returns all items at TRUSTED rep', () => {
-  const items = getShopCatalog(85);
-  // 8 items (4 consumables + 4 gear) visible at TRUSTED tier.
-  assert.equal(items.length, 8);
+test('getShopCatalog returns the four default items regardless of standing', () => {
+  const items = getShopCatalog();
+  assert.equal(items.length, 4);
 });
 
 test('getItemById returns the item for a valid id', () => {
@@ -95,7 +70,7 @@ test('getItemById throws on unknown id', () => {
 });
 
 test('every catalog item has a valid scope', () => {
-  const items = getShopCatalog({});
+  const items = getShopCatalog();
   const validScopes = new Set(Object.values(ITEM_SCOPE));
   for (const item of items) {
     assert.ok(validScopes.has(item.scope), `item ${item.id} has unknown scope "${item.scope}"`);
@@ -103,7 +78,7 @@ test('every catalog item has a valid scope', () => {
 });
 
 test('every catalog item has a positive integer cost', () => {
-  const items = getShopCatalog({});
+  const items = getShopCatalog();
   for (const item of items) {
     assert.ok(Number.isInteger(item.cost) && item.cost > 0, `item ${item.id} has invalid cost`);
   }
diff --git a/tests/unit/game/items.test.ts b/tests/unit/game/items.test.ts
index eef9933..3879002 100644
--- a/tests/unit/game/items.test.ts
+++ b/tests/unit/game/items.test.ts
@@ -14,6 +14,13 @@ import {
   DODGE_BONUS,
   RANGED_DAMAGE_BONUS,
   DEFAULT_HP,
+  DEFAULT_AP,
+  MELEE_DAMAGE_BONUS,
+  ARMOR_BONUS,
+  AP_BONUS,
+  SHIELD_REGEN,
+  HP_REGEN,
+  HEAVY_MELEE_DAMAGE,
 } from '../../../src/game/constants.js';
 import { Merc } from '../../../src/game/archetypes/Merc.js';
 import { Skirmisher } from '../../../src/game/ai/Skirmisher.js';
@@ -78,6 +85,139 @@ test('applyGear(BALLISTICS_COIL) sets rangedDamageBonus', () => {
   assert.equal(crew.gear.rangedDamageBonus, RANGED_DAMAGE_BONUS);
 });
 
+// ---------------------------------------------------------------------------
+// P3.M6.2 net-new scoreable gear — Crew.applyGear
+// ---------------------------------------------------------------------------
+
+test('applyGear(MONOBLADE) raises meleeAttackDamage by the bonus, capped', () => {
+  const razor = new Razor({ id: 'razor', x: 0, y: 0, callsign: 'Cipher' });
+  const base = razor.meleeAttackDamage();
+  razor.applyGear(ITEM_ID.MONOBLADE);
+  assert.equal(razor.gear.meleeDamageBonus, MELEE_DAMAGE_BONUS);
+  assert.equal(razor.meleeAttackDamage(), base + MELEE_DAMAGE_BONUS);
+  // Capped: a second install is a harmless no-op (mirrors Ballistics Coil).
+  razor.applyGear(ITEM_ID.MONOBLADE);
+  assert.equal(razor.gear.meleeDamageBonus, razor.maxMeleeDamageBonus);
+  assert.equal(razor.meleeAttackDamage(), base + razor.maxMeleeDamageBonus);
+});
+
+test('resolveMelee applies the Monoblade bonus through meleeAttackDamage', () => {
+  const grid = new Grid(12, 6, TILE.FLOOR);
+  const bus = new EventBus();
+  const world = new World(grid, { events: bus });
+  const attacker = new Razor({ id: 'razor', x: 2, y: 2, callsign: 'Cipher', maxAp: 4 });
+  attacker.applyGear(ITEM_ID.MONOBLADE);
+  const target = new Skirmisher({ id: 'drone', x: 3, y: 2 });
+  world.addEntity(attacker);
+  world.addEntity(target);
+  const rng = new Rng(42);
+  // Force a clean hit (no dodge) so we read the unmitigated swing.
+  const result = resolveMelee(world, attacker, target, rng, { dodgeChance: 0 });
+  assert.equal(result.hit, true);
+  assert.equal(result.damage, HEAVY_MELEE_DAMAGE + MELEE_DAMAGE_BONUS);
+  assert.equal(result.damage, attacker.meleeAttackDamage());
+});
+
+test('applyGear(SUBDERMAL_PLATING) raises damageReduction, capped', () => {
+  const merc = new Merc({ id: 'merc', x: 0, y: 0 });
+  assert.equal(merc.damageReduction, 0);
+  merc.applyGear(ITEM_ID.SUBDERMAL_PLATING);
+  assert.equal(merc.gear.armorBonus, ARMOR_BONUS);
+  assert.equal(merc.damageReduction, ARMOR_BONUS);
+  // Capped at one effective unit — a second install changes nothing.
+  merc.applyGear(ITEM_ID.SUBDERMAL_PLATING);
+  assert.equal(merc.damageReduction, merc.maxArmorBonus);
+  assert.equal(merc.gear.armorBonus, merc.maxArmorBonus);
+});
+
+test('subdermal plating mitigates incoming melee damage with a min-1 floor', () => {
+  const grid = new Grid(12, 6, TILE.FLOOR);
+  const bus = new EventBus();
+  const world = new World(grid, { events: bus });
+  const attacker = new Entity({ id: 'corp', x: 2, y: 2, faction: FACTION.CORP, glyph: 'd' });
+  const target = new Merc({ id: 'merc', x: 3, y: 2 });
+  target.applyGear(ITEM_ID.SUBDERMAL_PLATING);
+  world.addEntity(attacker);
+  world.addEntity(target);
+  const hpBefore = target.hp;
+  const rng = new Rng(42);
+  // Generic corp melee is MELEE_DAMAGE (2); armour 1 → 1 applied.
+  const result = resolveMelee(world, attacker, target, rng, { dodgeChance: 0, damage: 2 });
+  assert.equal(result.hit, true);
+  assert.equal(result.damage, 1);
+  assert.equal(target.hp, hpBefore - 1);
+});
+
+test('applyGear(REFLEX_BOOSTER) grants +AP immediately, capped at one', () => {
+  const merc = new Merc({ id: 'merc', x: 0, y: 0, maxAp: DEFAULT_AP });
+  const apBefore = merc.ap;
+  merc.applyGear(ITEM_ID.REFLEX_BOOSTER);
+  assert.equal(merc.maxAp, DEFAULT_AP + AP_BONUS);
+  assert.equal(merc.ap, apBefore + AP_BONUS, 'extra AP is usable the same turn');
+  assert.equal(merc.gear.apBonus, AP_BONUS);
+  // One per operator — a second install is a no-op, no runaway AP.
+  merc.applyGear(ITEM_ID.REFLEX_BOOSTER);
+  assert.equal(merc.maxAp, DEFAULT_AP + merc.maxApBonus);
+  assert.equal(merc.gear.apBonus, merc.maxApBonus);
+});
+
+test('applyGear(PHASE_SHIELD) sets shieldRegen; refreshAp re-grants the shield each turn', () => {
+  const merc = new Merc({ id: 'merc', x: 0, y: 0, maxAp: 4 });
+  merc.applyGear(ITEM_ID.PHASE_SHIELD);
+  assert.equal(merc.gear.shieldRegen, SHIELD_REGEN);
+  // Capped — a second install is a no-op.
+  merc.applyGear(ITEM_ID.PHASE_SHIELD);
+  assert.equal(merc.gear.shieldRegen, merc.maxShieldRegen);
+
+  // refreshAp tops the buffer back to the regen value every turn.
+  assert.equal(merc.shieldHp, 0);
+  merc.refreshAp();
+  assert.equal(merc.shieldHp, SHIELD_REGEN);
+  // Spend the buffer, then a fresh turn restores it (not accumulates).
+  merc.damage(SHIELD_REGEN);
+  assert.equal(merc.shieldHp, 0);
+  merc.refreshAp();
+  assert.equal(merc.shieldHp, SHIELD_REGEN);
+});
+
+test('phase shield buffer absorbs damage before HP', () => {
+  const merc = new Merc({ id: 'merc', x: 0, y: 0, maxAp: 4 });
+  merc.applyGear(ITEM_ID.PHASE_SHIELD);
+  merc.refreshAp();
+  const hpBefore = merc.hp;
+  merc.damage(SHIELD_REGEN); // fully soaked by the shield
+  assert.equal(merc.hp, hpBefore);
+  assert.equal(merc.shieldHp, 0);
+});
+
+test('applyGear(REGEN_MESH) sets hpRegen; refreshAp heals each turn up to maxHp', () => {
+  const merc = new Merc({ id: 'merc', x: 0, y: 0, maxAp: 4 });
+  merc.applyGear(ITEM_ID.REGEN_MESH);
+  assert.equal(merc.gear.hpRegen, HP_REGEN);
+  // Capped — second install is a no-op.
+  merc.applyGear(ITEM_ID.REGEN_MESH);
+  assert.equal(merc.gear.hpRegen, merc.maxHpRegen);
+
+  merc.hp = 1; // wounded
+  merc.refreshAp();
+  assert.equal(merc.hp, 1 + HP_REGEN);
+  // Does not exceed maxHp.
+  merc.hp = merc.maxHp;
+  merc.refreshAp();
+  assert.equal(merc.hp, merc.maxHp);
+});
+
+test('a dead crew member regenerates nothing on refreshAp', () => {
+  const merc = new Merc({ id: 'merc', x: 0, y: 0, maxAp: 4 });
+  merc.applyGear(ITEM_ID.PHASE_SHIELD);
+  merc.applyGear(ITEM_ID.REGEN_MESH);
+  merc.damage(merc.hp); // flatline the body
+  assert.equal(merc.alive, false);
+  merc.refreshAp(); // must not throw on a corpse (heal/addShield would)
+  assert.equal(merc.shieldHp, 0);
+  assert.equal(merc.hp, 0);
+});
+
 // ---------------------------------------------------------------------------
 // Combat.resolveRanged reads hitBonus from gear
 // ---------------------------------------------------------------------------

From d7f539a087e0cee321ff75bea380adc4d78cea1a Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Thu, 25 Jun 2026 14:37:57 -0700
Subject: [PATCH 51/55] Finn shows acquired scores

---
 docs/phase-3-plan.md                 | 19 ++++++++-
 src/game/hub/Finn.ts                 | 11 ++---
 src/game/items.ts                    | 20 ++++++---
 src/shell/shellRuntime.ts            |  5 ++-
 tests/unit/game/catalogSplit.test.ts | 63 +++++++++++++++++++++-------
 tests/unit/game/hub/Finn.test.ts     | 12 ++++++
 6 files changed, 101 insertions(+), 29 deletions(-)

diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 6d51a18..c1454ce 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -46,7 +46,7 @@ A new **player archetype** recruited mid-campaign (late Act 1 / start of Act 2),
 | P3.M3 — Cyberspace grid + ICE | ✅ Done (full ICE roster: Probe, Spark, Guardian) |
 | P3.M4 — Simstim flip (dual-deploy) | ✅ Done |
 | P3.M5 — The Score (climactic mission) | ✅ Done |
-| P3.M6 — Stolen Blueprints (shop rework + meta-progression) | 🟡 Meta-store + catalog split shipped (M6.1–M6.2) |
+| P3.M6 — Stolen Blueprints (shop rework + meta-progression) | 🟡 Meta-store + catalog split + shop rework shipped (M6.1–M6.3) |
 | P3.M7 — Chronicle (campaign narrative memory) | 🟡 End-summary foundation shipped |
 
 **Phase 3** is complete when:
@@ -450,7 +450,7 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 |---|---|---|---|
 | **P3.M6.1 Meta-store** | ✅ | `DataStore` key `unlockedScoreableItems`; read at campaign init; idempotent archival; duplicate no-op; corrupt throws | round-trip, idempotent archival, duplicate no-op, corrupt throws |
 | **P3.M6.2 Item catalog split** | ✅ | Define `DEFAULT_ITEMS` and `SCOREABLE_ITEMS` catalogs; retire `minRepTier` as shop gate; add at least 5 net-new scoreable items (fully wired gear) | catalog validation, no duplicate IDs, all items have required fields, `minRepTier` not read by shop |
-| **P3.M6.3 Shop rework** | 🔲 | Shop stocks `DEFAULT_ITEMS + unlockedScoreableItems`; no rep gate; locked scoreable items not rendered | shop shows only default items when meta-store is empty; adds unlocked scoreable items as they accrue; rep change has no effect on stock |
+| **P3.M6.3 Shop rework** | ✅ | Shop stocks `DEFAULT_ITEMS + unlockedScoreableItems`; no rep gate; locked scoreable items not rendered | shop shows only default items when meta-store is empty; adds unlocked scoreable items as they accrue; rep change has no effect on stock |
 | **P3.M6.4 Score target rework** | 🔲 | `buildScoreContract()` draws from unacquired `SCOREABLE_ITEMS`; briefing copy reflects item; completion writes meta-store | available targets exclude acquired; retired items not rolled; store updated on complete |
 | **P3.M6.5 Abstract targets** | 🔲 | Exhausted-pool Score draws RNG credit payload from category set; seeded flavor; arc gates pass with empty scoreable pool | category selection determinism, arc unaffected, no meta-store write |
 | **P3.M6.6 Hub surface** | 🔲 | Shop renders only purchasable items; no locked placeholders | shop never renders a locked scoreable item regardless of meta-store state |
@@ -523,6 +523,21 @@ new `Campaign.reviveMember()` and a delivery surface (Clinic service vs. Finn pu
 shop target-picker currently excludes flatlined crew). Deferred to its own slice; revisit
 after M6.3/M6.4.
 
+**P3.M6.3 implementation note:** `getShopCatalog(unlockedScoreableIds = [])` now returns
+`DEFAULT_ITEMS` plus the `SCOREABLE_ITEMS` whose ids appear in the supplied unlock list
+(membership via a `Set`); rep is structurally gone (no parameter). `Finn.catalog()` is a
+thin passthrough. The shell reads the meta-store **live** at shop-open time
+(`presentFinnShop` → `dataStore.unlockedScoreableItems`) rather than caching it at campaign
+init — a refinement of the M6.1 "read at init/Hub load" sketch. This is simpler and always
+correct, and the practical difference is nil: the only in-campaign unlock path is completing
+the climactic Score (M6.4), after which the player doesn't return to shop. **Lenient
+membership:** an unlocked id that isn't a known scoreable item (a retired or
+forward-version blueprint) is silently skipped, not thrown — the shop can't render a
+nonexistent item, and hard-failing would brick saves across catalog changes. This resolves
+the M6.1 "catalog membership validation" follow-up in the shop layer (the store stays
+structural-only). The `buildScoreContract` acquired-set exclusion (which also needs the
+unlock list) lands in M6.4; it will read the same `dataStore.unlockedScoreableItems`.
+
 **Recorded design decisions:**
 
 - **Why `minRepTier` is retired as a shop gate:** Rep-gated access was mechanical — the best gear was reachable by grinding rep without doing anything interesting. Two explicit catalogs make availability rules legible in the data rather than computed from a tier comparison at runtime.
diff --git a/src/game/hub/Finn.ts b/src/game/hub/Finn.ts
index 3a84b9a..50c299e 100644
--- a/src/game/hub/Finn.ts
+++ b/src/game/hub/Finn.ts
@@ -37,11 +37,12 @@ export class Finn extends Entity {
   }
 
   /**
-   * Return Finn's purchasable stock. Rep no longer gates the shop (P3.M6.2);
-   * this is the always-available {@link DEFAULT_ITEMS}. Unlocked scoreable
-   * items are folded in by the M6.3 shop rework.
+   * Return Finn's purchasable stock (P3.M6.3): {@link DEFAULT_ITEMS} plus the
+   * meta-crew's unlocked scoreable blueprints. Rep no longer gates the shop;
+   * the caller supplies the unlocked ids from the meta-progression store
+   * (`DataStore.unlockedScoreableItems`).
    */
-  catalog() {
-    return getShopCatalog();
+  catalog(unlockedScoreableIds: readonly string[] = []) {
+    return getShopCatalog(unlockedScoreableIds);
   }
 }
diff --git a/src/game/items.ts b/src/game/items.ts
index e7cb64f..f881fb8 100644
--- a/src/game/items.ts
+++ b/src/game/items.ts
@@ -240,13 +240,21 @@ export const SCOREABLE_ITEM_IDS: ReadonlySet<string> = Object.freeze(
 const CATALOG: readonly Item[] = Object.freeze([...DEFAULT_ITEMS, ...SCOREABLE_ITEMS]);
 
 /**
- * Return Finn's always-available stock — the {@link DEFAULT_ITEMS}. Rep no
- * longer gates the shop (P3.M6.2 retired `minRepTier`); unlocked
- * {@link SCOREABLE_ITEMS} are folded in by the shop rework in M6.3, which reads
- * the meta-progression store rather than any tier comparison.
+ * Return Finn's purchasable stock (P3.M6.3): the always-available
+ * {@link DEFAULT_ITEMS} plus any {@link SCOREABLE_ITEMS} the meta-crew has
+ * unlocked across all campaigns. Rep no longer gates anything — the only
+ * variance is which blueprints have been stolen.
+ *
+ * @param unlockedScoreableIds — item ids from the meta-progression store
+ *   (`DataStore.unlockedScoreableItems`). Defaults to empty: a fresh meta-crew
+ *   sees default stock only. Ids not present in `SCOREABLE_ITEMS` are ignored
+ *   (a retired/forward-version blueprint can't be rendered) rather than thrown —
+ *   the store, not the shop, owns earned-data integrity. Locked scoreable items
+ *   are never included, so the shop never renders a placeholder.
  */
-export function getShopCatalog(): Item[] {
-  return [...DEFAULT_ITEMS];
+export function getShopCatalog(unlockedScoreableIds: readonly string[] = []): Item[] {
+  const unlocked = new Set(unlockedScoreableIds);
+  return [...DEFAULT_ITEMS, ...SCOREABLE_ITEMS.filter(item => unlocked.has(item.id))];
 }
 
 /**
diff --git a/src/shell/shellRuntime.ts b/src/shell/shellRuntime.ts
index 3d9eaa7..f3ec1a5 100644
--- a/src/shell/shellRuntime.ts
+++ b/src/shell/shellRuntime.ts
@@ -826,7 +826,10 @@ function onBriefingDeploy(evt: Event) {
 
 function presentFinnShop() {
   if (!campaign || !campaign.finn) return;
-  const catalog = campaign.finn.catalog();
+  // P3.M6.3: stock = default items + scoreable blueprints stolen across all
+  // campaigns. Read live from the meta-store so a Score unlock surfaces at the
+  // next shop visit; rep no longer influences stock.
+  const catalog = campaign.finn.catalog(dataStore.unlockedScoreableItems);
   finnShopEl.setCatalog(catalog, campaign.crew, {
     credits: campaign.credits,
     salvage: campaign.salvage,
diff --git a/tests/unit/game/catalogSplit.test.ts b/tests/unit/game/catalogSplit.test.ts
index e0d7f29..25b7e4d 100644
--- a/tests/unit/game/catalogSplit.test.ts
+++ b/tests/unit/game/catalogSplit.test.ts
@@ -100,33 +100,66 @@ test('SCOREABLE_ITEM_IDS matches the SCOREABLE_ITEMS pool exactly', () => {
 });
 
 // ---------------------------------------------------------------------------
-// getShopCatalog — rep no longer gates; only DEFAULT_ITEMS until M6.3
+// getShopCatalog — P3.M6.3 shop rework: DEFAULT_ITEMS + unlocked scoreable
 // ---------------------------------------------------------------------------
 
-test('getShopCatalog returns exactly the default items (no rep gate)', () => {
-  const catalog = getShopCatalog();
+test('getShopCatalog with an empty meta-store returns exactly the default items', () => {
+  const catalog = getShopCatalog([]);
   assert.deepEqual(catalog.map(i => i.id).sort(), DEFAULT_ITEMS.map(i => i.id).sort());
 });
 
-test('getShopCatalog never surfaces a scoreable item (locked until unlocked)', () => {
-  const shopIds = new Set(getShopCatalog().map(i => i.id));
+test('getShopCatalog defaults to default-only stock when called with no arg', () => {
+  assert.deepEqual(
+    getShopCatalog()
+      .map(i => i.id)
+      .sort(),
+    DEFAULT_ITEMS.map(i => i.id).sort()
+  );
+});
+
+test('getShopCatalog folds in unlocked scoreable items as they accrue', () => {
+  const oneUnlock = getShopCatalog([ITEM_ID.MONOBLADE]);
+  const ids = oneUnlock.map(i => i.id);
+  // All default items still present...
+  for (const item of DEFAULT_ITEMS) assert.ok(ids.includes(item.id));
+  // ...plus exactly the one unlocked scoreable.
+  assert.ok(ids.includes(ITEM_ID.MONOBLADE));
+  assert.equal(oneUnlock.length, DEFAULT_ITEMS.length + 1);
+
+  const twoUnlocks = getShopCatalog([ITEM_ID.MONOBLADE, ITEM_ID.ARMOUR_PLATING]);
+  assert.equal(twoUnlocks.length, DEFAULT_ITEMS.length + 2);
+  assert.ok(twoUnlocks.some(i => i.id === ITEM_ID.ARMOUR_PLATING));
+});
+
+test('getShopCatalog never renders a locked scoreable item', () => {
+  // Unlock only the Monoblade — every other scoreable stays hidden.
+  const ids = new Set(getShopCatalog([ITEM_ID.MONOBLADE]).map(i => i.id));
   for (const item of SCOREABLE_ITEMS) {
-    assert.ok(!shopIds.has(item.id), `scoreable "${item.id}" leaked into default shop stock`);
+    if (item.id === ITEM_ID.MONOBLADE) continue;
+    assert.ok(!ids.has(item.id), `locked scoreable "${item.id}" should not render`);
   }
 });
 
-test('getShopCatalog takes no rep argument and is independent of standing', () => {
-  // Signature regression guard: the rep-gated overload is gone. Calling with a
-  // stray argument is a no-op rather than a tier filter.
-  assert.equal(getShopCatalog.length, 0);
-  const a = getShopCatalog();
-  const b = (getShopCatalog as (rep?: number) => Item[])(100);
+test('getShopCatalog ignores an unlocked id that is not a known scoreable item', () => {
+  // A retired / forward-version blueprint can't be rendered; it must not crash
+  // or leak a phantom entry — the store owns earned-data integrity, not the shop.
+  const catalog = getShopCatalog([ITEM_ID.MONOBLADE, 'ghost-blueprint', ITEM_ID.STIM]);
+  const ids = catalog.map(i => i.id);
+  assert.ok(!ids.includes('ghost-blueprint'));
+  // STIM is a default item, not scoreable — passing it as "unlocked" doesn't
+  // duplicate it (default items are added once, unconditionally).
+  assert.equal(ids.filter(id => id === ITEM_ID.STIM).length, 1);
+  assert.ok(ids.includes(ITEM_ID.MONOBLADE));
+});
+
+test('getShopCatalog stock depends only on unlocks, never on rep (no rep param)', () => {
+  // Structural decoupling: there is no rep argument. Same unlocks → same stock.
   assert.deepEqual(
-    a.map(i => i.id),
-    b.map(i => i.id)
+    getShopCatalog([ITEM_ID.MONOBLADE]).map(i => i.id),
+    getShopCatalog([ITEM_ID.MONOBLADE]).map(i => i.id)
   );
   // Returns a fresh array each call — callers may mutate without corrupting source.
-  assert.notEqual(a, b);
+  assert.notEqual(getShopCatalog([]), getShopCatalog([]));
 });
 
 test('getItemById resolves across both catalogs and throws on unknown', () => {
diff --git a/tests/unit/game/hub/Finn.test.ts b/tests/unit/game/hub/Finn.test.ts
index 4def425..4b6ef60 100644
--- a/tests/unit/game/hub/Finn.test.ts
+++ b/tests/unit/game/hub/Finn.test.ts
@@ -49,6 +49,18 @@ test('Finn.catalog never surfaces a locked scoreable item', () => {
   assert.ok(!ids.includes(ITEM_ID.BALLISTICS_COIL));
 });
 
+test('Finn.catalog folds in unlocked scoreable blueprints from the meta-store', () => {
+  const f = new Finn();
+  const ids = f.catalog([ITEM_ID.ARMOUR_PLATING, ITEM_ID.MONOBLADE]).map(i => i.id);
+  // Default stock still present.
+  assert.ok(ids.includes(ITEM_ID.STIM));
+  // Unlocked scoreable now stocked.
+  assert.ok(ids.includes(ITEM_ID.ARMOUR_PLATING));
+  assert.ok(ids.includes(ITEM_ID.MONOBLADE));
+  // Still-locked scoreable stays hidden.
+  assert.ok(!ids.includes(ITEM_ID.TARGETING_CHIP));
+});
+
 // ---------------------------------------------------------------------------
 // Item catalog (pure functions)
 // ---------------------------------------------------------------------------

From b924d083e2f95aaba98e0d6c7752e9e0a7bc4814 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Thu, 25 Jun 2026 15:22:54 -0700
Subject: [PATCH 52/55] add score targets to The Score jobs

---
 components/GameOver.ts               |  73 +++++++++++++
 docs/phase-3-plan.md                 |  29 ++++-
 src/game/Campaign.ts                 |  96 ++++++++++++++---
 src/game/Run.ts                      |  29 ++++-
 src/game/entities/Pickup.ts          |  14 ++-
 src/game/persistence.ts              |   5 +-
 src/input/applyIntent.ts             |   3 +
 src/shell/domTypes.ts                |   1 +
 src/shell/shellRuntime.ts            |  17 ++-
 tests/unit/game/scoreFinal.test.ts   | 153 ++++++++++++++++++++++++++-
 tests/unit/input/applyIntent.test.ts |  32 ++++++
 11 files changed, 428 insertions(+), 24 deletions(-)

diff --git a/components/GameOver.ts b/components/GameOver.ts
index 2c5acb0..1f1852c 100644
--- a/components/GameOver.ts
+++ b/components/GameOver.ts
@@ -112,6 +112,41 @@ const CSS = `
   line-height: 1.45;
 }
 
+.reward {
+  display: none;
+  margin: 0 0 1.25rem;
+  padding: 0.6rem 0.85rem;
+  background: rgba(0, 0, 0, 0.4);
+  border: 1px solid var(--go-roster-border);
+  border-radius: 4px;
+  text-align: center;
+}
+
+.reward .reward-kicker {
+  display: block;
+  font-size: 0.7rem;
+  letter-spacing: 0.18em;
+  color: var(--go-dim);
+}
+
+.reward .reward-name {
+  display: block;
+  margin-top: 0.2rem;
+  font-size: 1.1rem;
+  letter-spacing: 0.06em;
+  color: var(--go-accent);
+  text-shadow: 0 0 12px color-mix(in srgb, var(--go-accent) 40%, transparent);
+}
+
+.reward .reward-flavor {
+  display: block;
+  margin-top: 0.35rem;
+  font-size: 0.82rem;
+  font-style: italic;
+  color: var(--go-text);
+  line-height: 1.4;
+}
+
 .roster {
   margin: 0 0 1.25rem;
   padding: 0.65rem 0.85rem;
@@ -231,13 +266,20 @@ function detailCopy(summary: CampaignSummary): string {
   return 'Every crew slot on the roster is flatlined. Their campaign ends here.';
 }
 
+/** Presentation-only Score prize (P3.M6.4) — not part of the persisted summary. */
+export type ScoreReward = { label: string; flavor: string };
+
 class GameOver extends HTMLElement {
   #summary: CampaignSummary | null = null;
+  #scoreReward: ScoreReward | null = null;
   #ready = false;
   #els: {
     banner: HTMLElement;
     reason: HTMLElement;
     detail: HTMLElement;
+    reward: HTMLElement;
+    rewardName: HTMLElement;
+    rewardFlavor: HTMLElement;
     rosterList: HTMLElement;
     jobsDd: HTMLElement;
     repDd: HTMLElement;
@@ -256,6 +298,13 @@ class GameOver extends HTMLElement {
     const banner = h('h1', { className: 'banner' });
     const reason = h('p', { className: 'reason' });
     const detail = h('p', { className: 'detail' });
+    const rewardName = h('span', { className: 'reward-name' });
+    const rewardFlavor = h('span', { className: 'reward-flavor' });
+    const reward = h('p', { className: 'reward' }, [
+      h('span', { className: 'reward-kicker', textContent: 'BLUEPRINT SECURED' }),
+      rewardName,
+      rewardFlavor,
+    ]);
     const rosterList = h('dd');
     const jobsDd = h('dd', { id: 'jobs' });
     const repDd = h('dd', { id: 'rep' });
@@ -279,6 +328,7 @@ class GameOver extends HTMLElement {
       h('hr', { className: 'rule' }),
       reason,
       detail,
+      reward,
       roster,
       h('dl', { className: 'meta' }, [
         h('dt', { textContent: 'jobs' }),
@@ -299,6 +349,9 @@ class GameOver extends HTMLElement {
       banner,
       reason,
       detail,
+      reward,
+      rewardName,
+      rewardFlavor,
       rosterList,
       jobsDd,
       repDd,
@@ -316,6 +369,17 @@ class GameOver extends HTMLElement {
     if (this.#ready) this.#render();
   }
 
+  /**
+   * Set (or clear) the stolen Score blueprint shown on a win (P3.M6.4).
+   * Presentation-only — the persisted {@link CampaignSummary} schema is
+   * untouched; the shell re-derives this from the meta-store on both live
+   * completion and a restored ended save.
+   */
+  setScoreReward(reward: ScoreReward | null) {
+    this.#scoreReward = reward;
+    if (this.#ready) this.#render();
+  }
+
   show() {
     this.setAttribute('open', '');
     queueMicrotask(() => {
@@ -337,6 +401,15 @@ class GameOver extends HTMLElement {
     this.#els.banner.textContent = summary.result === 'win' ? 'SCORE COMPLETE' : 'GAME OVER';
     this.#els.reason.textContent = reasonCopy(summary);
     this.#els.detail.textContent = detailCopy(summary);
+    // Score prize — only meaningful on a win that stole a blueprint.
+    const reward = summary.result === 'win' ? this.#scoreReward : null;
+    if (reward) {
+      this.#els.rewardName.textContent = reward.label;
+      this.#els.rewardFlavor.textContent = reward.flavor;
+      this.#els.reward.style.display = 'block';
+    } else {
+      this.#els.reward.style.display = 'none';
+    }
     this.#els.jobsDd.textContent = String(summary.completedJobs);
     this.#els.repDd.textContent = String(summary.rep);
     this.#els.creditsDd.textContent = String(summary.credits);
diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index c1454ce..51b891f 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -46,7 +46,7 @@ A new **player archetype** recruited mid-campaign (late Act 1 / start of Act 2),
 | P3.M3 — Cyberspace grid + ICE | ✅ Done (full ICE roster: Probe, Spark, Guardian) |
 | P3.M4 — Simstim flip (dual-deploy) | ✅ Done |
 | P3.M5 — The Score (climactic mission) | ✅ Done |
-| P3.M6 — Stolen Blueprints (shop rework + meta-progression) | 🟡 Meta-store + catalog split + shop rework shipped (M6.1–M6.3) |
+| P3.M6 — Stolen Blueprints (shop rework + meta-progression) | 🟡 Meta-store + catalog split + shop rework + Score target rework shipped (M6.1–M6.4) |
 | P3.M7 — Chronicle (campaign narrative memory) | 🟡 End-summary foundation shipped |
 
 **Phase 3** is complete when:
@@ -451,7 +451,7 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 | **P3.M6.1 Meta-store** | ✅ | `DataStore` key `unlockedScoreableItems`; read at campaign init; idempotent archival; duplicate no-op; corrupt throws | round-trip, idempotent archival, duplicate no-op, corrupt throws |
 | **P3.M6.2 Item catalog split** | ✅ | Define `DEFAULT_ITEMS` and `SCOREABLE_ITEMS` catalogs; retire `minRepTier` as shop gate; add at least 5 net-new scoreable items (fully wired gear) | catalog validation, no duplicate IDs, all items have required fields, `minRepTier` not read by shop |
 | **P3.M6.3 Shop rework** | ✅ | Shop stocks `DEFAULT_ITEMS + unlockedScoreableItems`; no rep gate; locked scoreable items not rendered | shop shows only default items when meta-store is empty; adds unlocked scoreable items as they accrue; rep change has no effect on stock |
-| **P3.M6.4 Score target rework** | 🔲 | `buildScoreContract()` draws from unacquired `SCOREABLE_ITEMS`; briefing copy reflects item; completion writes meta-store | available targets exclude acquired; retired items not rolled; store updated on complete |
+| **P3.M6.4 Score target rework** | ✅ | `buildScoreContract()` draws from unacquired `SCOREABLE_ITEMS`; briefing copy reflects item; completion writes meta-store | available targets exclude acquired; retired items not rolled; store updated on complete |
 | **P3.M6.5 Abstract targets** | 🔲 | Exhausted-pool Score draws RNG credit payload from category set; seeded flavor; arc gates pass with empty scoreable pool | category selection determinism, arc unaffected, no meta-store write |
 | **P3.M6.6 Hub surface** | 🔲 | Shop renders only purchasable items; no locked placeholders | shop never renders a locked scoreable item regardless of meta-store state |
 
@@ -538,6 +538,31 @@ the M6.1 "catalog membership validation" follow-up in the shop layer (the store
 structural-only). The `buildScoreContract` acquired-set exclusion (which also needs the
 unlock list) lands in M6.4; it will read the same `dataStore.unlockedScoreableItems`.
 
+**P3.M6.4 implementation note:** `buildScoreContract(unlockedScoreableIds = [])` now draws a
+specific heist payload via `pickScorePayload(seed, acquired)` — `SCOREABLE_ITEMS` minus the
+acquired ids, selected with a `Rng` seeded from the target seed XORed with a salt
+(`SCORE_PAYLOAD_SALT`) so the choice is deterministic per campaign yet independent of the
+map roll. Retired/foreign ids in the acquired list simply aren't in the pool, so they're
+never rolled. The chosen blueprint's `flavor` + `label` frame the briefing, and its id rides
+in `objective.params.scoreItemId` (a plain `ObjectiveParams` string that `cloneObjective`
+preserves across a mid-run save/restore). On clean `score-complete`, `onJobEnd` reads that id
+off the completing contract and records it on `meta.scoreUnlockedItemId` (alongside the
+existing `meta.scorePartial`), exposed via the `Campaign.scoreUnlockedItemId` getter
+(validated against `SCOREABLE_ITEM_IDS`). The shell writes it to the meta-store in
+`presentEndedCampaignOverlay` — the shared terminal-settlement chokepoint for both live
+completion and a restored already-ended save — right beside `archiveCampaign`, and the write
+is idempotent so the double path is safe. Partial Scores record nothing (prototype not
+secured). **Exhausted pool:** `pickScorePayload` returns `null`, the contract drops the
+`scoreItemId` param and falls back to generic briefing with no unlock — the abstract
+credit-payload Score is M6.5.
+
+*Messaging polish (playtest feedback):* the Score payload pickup is now labelled with the
+target blueprint and carries its `flavor` (new optional `Pickup.detail`, persisted), so the
+grab logs e.g. `secures Monoblade` followed by the flavor beat; the `<game-over>` win screen
+names the stolen blueprint + flavor via a presentation-only `setScoreReward` (re-derived from
+`scoreUnlockedItemId`, **not** added to the validated `CampaignSummary` schema). Abstract /
+exhausted-pool Scores keep the generic "Score payload" with no flavor beat.
+
 **Recorded design decisions:**
 
 - **Why `minRepTier` is retired as a shop gate:** Rep-gated access was mechanical — the best gear was reachable by grinding rep without doing anything interesting. Two explicit catalogs make availability rules legible in the data rather than computed from a tier comparison at runtime.
diff --git a/src/game/Campaign.ts b/src/game/Campaign.ts
index 950c26d..5f0e705 100644
--- a/src/game/Campaign.ts
+++ b/src/game/Campaign.ts
@@ -35,7 +35,14 @@ import {
   type HubReveals,
 } from './hub/hubReveals.js';
 import { buildHub } from './hub/SafeSpace.js';
-import { getItemById, ITEM_SCOPE, metaKeyFor } from './items.js';
+import {
+  getItemById,
+  ITEM_SCOPE,
+  metaKeyFor,
+  SCOREABLE_ITEMS,
+  SCOREABLE_ITEM_IDS,
+  type Item,
+} from './items.js';
 import { OUTCOME, Run } from './Run.js';
 import {
   generateSiteId,
@@ -83,6 +90,33 @@ export function clockDeadlineApplies(arcStage: CampaignArcStage): boolean {
 /** Campaign-ending payday for completing THE SCORE. */
 export const SCORE_CREDITS_REWARD = 5_000;
 const SYNTHETIC_SCORE_TARGET_DIFFICULTY = CONTRACT_DIFFICULTY.CRITICAL;
+/**
+ * Salt mixed into the Score target seed when picking the heist payload (P3.M6.4),
+ * so blueprint selection is deterministic per campaign but independent of the
+ * map-generation roll that shares the same seed.
+ */
+const SCORE_PAYLOAD_SALT = 0x5c07e;
+
+/**
+ * Deterministically pick the unacquired scoreable blueprint this Score targets.
+ * Draws from {@link SCOREABLE_ITEMS} minus the meta-crew's already-stolen ids;
+ * a retired/forward-version id in `acquiredIds` simply isn't in the pool, so it
+ * is never rolled. Returns `null` when the pool is exhausted (every blueprint
+ * stolen) — the abstract-payload Score is M6.5's job.
+ */
+function pickScorePayload(seed: number, acquiredIds: readonly string[]): Item | null {
+  const acquired = new Set(acquiredIds);
+  const pool = SCOREABLE_ITEMS.filter(item => !acquired.has(item.id));
+  if (pool.length === 0) return null;
+  const rng = new Rng(((seed >>> 0) ^ SCORE_PAYLOAD_SALT) >>> 0);
+  return pool[Math.floor(rng.next() * pool.length)] ?? null;
+}
+
+/** Read the embedded heist payload id from a completed Score contract (or `null`). */
+function scorePayloadItemId(contract: Contract | null): string | null {
+  const raw = contract?.objective?.params?.scoreItemId;
+  return typeof raw === 'string' && SCOREABLE_ITEM_IDS.has(raw) ? raw : null;
+}
 
 export const CAMPAIGN_STATE = Object.freeze({
   HUB: 'HUB',
@@ -602,20 +636,21 @@ export class Campaign {
       throw new TypeError(`Campaign.onJobEnd: completed must be boolean`);
     }
 
+    // Capture the contract before settlement clears `activeRun` — the completed
+    // Score's payload id (P3.M6.4) is read from it after the run is torn down.
+    const activeContract = this.activeRun.contract;
     const completedScoreRun =
-      this.activeRun.contract !== null &&
-      isScoreContract(this.activeRun.contract) &&
+      activeContract !== null &&
+      isScoreContract(activeContract) &&
       outcome === OUTCOME.EXIT &&
       completed;
     const partialScoreRun =
-      this.activeRun.contract !== null &&
-      isScoreContract(this.activeRun.contract) &&
+      activeContract !== null &&
+      isScoreContract(activeContract) &&
       outcome === OUTCOME.EXIT &&
       !completed;
     const failedScoreRun =
-      this.activeRun.contract !== null &&
-      isScoreContract(this.activeRun.contract) &&
-      outcome === OUTCOME.DEATH;
+      activeContract !== null && isScoreContract(activeContract) && outcome === OUTCOME.DEATH;
 
     // P3.M4.4: a meat partner that flatlined on the field is gone for good —
     // independent of the Decker's outcome. The Decker may have extracted clean
@@ -685,6 +720,12 @@ export class Campaign {
     if (completedScoreRun) {
       this.arc.scoreCompleted = true;
       this.arc.arcStage = 'score';
+      // P3.M6.4: record the stolen blueprint so settlement writes it to the
+      // cross-campaign meta-store. Persisted on `meta` (alongside `scorePartial`)
+      // so a refresh after completion still surfaces the unlock to the shell —
+      // the actual `DataStore.archiveScoreableItem` write is idempotent.
+      const payloadId = scorePayloadItemId(activeContract);
+      if (payloadId) this.meta.scoreUnlockedItemId = payloadId;
       this.state = CAMPAIGN_STATE.ENDED;
       this.#tearDownHubWorld();
       this.#persist();
@@ -695,6 +736,17 @@ export class Campaign {
     this.enterHub();
   }
 
+  /**
+   * The scoreable blueprint id stolen by a completed Score, or `null` if the
+   * Score isn't complete / drew an abstract payload (P3.M6.4). Read by the shell
+   * on terminal settlement to write the cross-campaign meta-store. Returns a
+   * known scoreable id only — a stale/foreign meta value is treated as absent.
+   */
+  get scoreUnlockedItemId(): string | null {
+    const raw = this.meta.scoreUnlockedItemId;
+    return typeof raw === 'string' && SCOREABLE_ITEM_IDS.has(raw) ? raw : null;
+  }
+
   canAttemptScore(): boolean {
     if (this.state !== CAMPAIGN_STATE.HUB) return false;
     if (this.arc.arcStage !== 'act-3') return false;
@@ -704,7 +756,18 @@ export class Campaign {
     return this.#scoreTargetSiteOrNull() !== null;
   }
 
-  buildScoreContract(): Contract {
+  /**
+   * Build the climactic Score contract. P3.M6.4: the heist targets a specific
+   * unacquired scoreable blueprint (drawn deterministically from the seed minus
+   * the meta-crew's already-stolen ids), and the briefing frames the site around
+   * that prototype. The chosen id rides along in `objective.params.scoreItemId`
+   * so the completion path can unlock it. An exhausted pool yields the generic
+   * framing with no payload id (abstract credit payloads are M6.5).
+   *
+   * @param unlockedScoreableIds — acquired blueprint ids from the meta-store
+   *   (`DataStore.unlockedScoreableItems`); these are excluded from the draw.
+   */
+  buildScoreContract(unlockedScoreableIds: readonly string[] = []): Contract {
     if (!this.canAttemptScore()) {
       throw new Error('Campaign.buildScoreContract: Score is not available');
     }
@@ -724,6 +787,15 @@ export class Campaign {
     const heatThreat = Math.min(6, 4 + this.clockHeat);
     const objectiveKind = OBJECTIVES.SCORE_FINAL;
     const doorId = 'score-door-0';
+    const siteLabel = target.label
+      .replace(/^\/\//, '')
+      .replace(/\s+-\s+Score target$/i, '')
+      .trim();
+    const payload = pickScorePayload(seed, unlockedScoreableIds);
+    const briefing = payload
+      ? `${payload.flavor} Their prototype is held at ${siteLabel}. Breach the facility, ` +
+        `secure the ${payload.label}, and extract with the crew alive.`
+      : `Hit ${siteLabel} and extract with the crew alive.`;
     return {
       seed,
       mapWidth: target.mapWidth,
@@ -731,14 +803,12 @@ export class Campaign {
       objective: {
         kind: objectiveKind,
         title: 'The Score',
-        briefing: `Hit ${target.label
-          .replace(/^\/\//, '')
-          .replace(/\s+-\s+Score target$/i, '')
-          .trim()} and extract with the crew alive.`,
+        briefing,
         params: {
           requiresCyberspace: true,
           count: 1,
           doorId,
+          ...(payload ? { scoreItemId: payload.id } : {}),
         },
       },
       difficulty: CONTRACT_DIFFICULTY.CRITICAL,
diff --git a/src/game/Run.ts b/src/game/Run.ts
index 1ecf76a..5effa3b 100644
--- a/src/game/Run.ts
+++ b/src/game/Run.ts
@@ -90,7 +90,7 @@ import { SparkIce } from './cyber/SparkIce.js';
 import { GuardianIce } from './cyber/GuardianIce.js';
 import { applyMutationDeltas } from './locations.js';
 import { BreachingCharge } from './entities/BreachingCharge.js';
-import { ITEM_ID, getItemById } from './items.js';
+import { ITEM_ID, getItemById, SCOREABLE_ITEMS } from './items.js';
 import { resetCorpTurnStatusCache } from './corpTurnStatusCopy.js';
 import {
   objectiveProgress as resolveObjectiveProgress,
@@ -2077,12 +2077,14 @@ export class Run {
         doorId,
         this.rng
       );
+      const payloadDesc = scorePayloadDescriptor(this.contract);
       this.world.addEntity(
         new Pickup({
           id: scorePayloadId(this.contract),
           x: payloadAnchor.x,
           y: payloadAnchor.y,
-          label: 'Score payload',
+          label: payloadDesc.label,
+          detail: payloadDesc.detail,
         })
       );
     }
@@ -2496,6 +2498,21 @@ function scorePayloadId(contract: Contract): string {
   return `score-payload-${doorId}`;
 }
 
+/**
+ * Label + flavor for the Score payload pickup (P3.M6.4). When the contract names
+ * a specific stolen blueprint (`objective.params.scoreItemId`), the grab reads as
+ * that item with its heist flavor; an exhausted-pool / abstract Score falls back
+ * to the generic label with no flavor beat.
+ */
+function scorePayloadDescriptor(contract: Contract): { label: string; detail?: string } {
+  const itemId = contract.objective.params?.scoreItemId;
+  if (typeof itemId === 'string') {
+    const item = SCOREABLE_ITEMS.find(i => i.id === itemId);
+    if (item) return { label: item.label, detail: item.flavor };
+  }
+  return { label: 'Score payload' };
+}
+
 export type UnlockMethod = 'terminal' | 'keycard';
 
 /**
@@ -2668,7 +2685,13 @@ const SNAPSHOT_EXTRACTORS: Partial<Record<EntityArchetypeId, (e: Entity) => Enti
     },
     pickup: e => {
       const p = e as Pickup;
-      return { label: p.label, secured: p.secured, armed: p.armed } satisfies PickupSnapshot;
+      // Only serialize `detail` when present, keeping ordinary pickups byte-stable.
+      return {
+        label: p.label,
+        secured: p.secured,
+        armed: p.armed,
+        ...(p.detail !== undefined ? { detail: p.detail } : {}),
+      } satisfies PickupSnapshot;
     },
     contact: e => {
       const c = e as Contact;
diff --git a/src/game/entities/Pickup.ts b/src/game/entities/Pickup.ts
index 2f620ea..394fd1d 100644
--- a/src/game/entities/Pickup.ts
+++ b/src/game/entities/Pickup.ts
@@ -11,23 +11,33 @@ import type { World } from '../World.js';
 
 export interface PickupInit extends Omit<InteractableInit, 'glyph' | 'label' | 'passable'> {
   label?: string;
+  detail?: string;
 }
 
-/** P2.7.M6.2: Pickup snapshot `extra`. */
+/** P2.7.M6.2: Pickup snapshot `extra`. `detail` added P3.M6.4 (Score flavor). */
 export type PickupSnapshot = {
   label: string;
   secured: boolean;
   armed: boolean;
+  detail?: string;
 };
 
 export class Pickup extends Interactable {
-  constructor({ label = 'Objective pickup', ...props }: PickupInit) {
+  /**
+   * Optional flavor line surfaced when the pickup is secured (P3.M6.4) — e.g.
+   * the stolen Score blueprint's `flavor`. `collectTileLoot` logs it as a
+   * second beat after the secure message. Absent on ordinary pickups.
+   */
+  detail?: string;
+
+  constructor({ label = 'Objective pickup', detail, ...props }: PickupInit) {
     super({
       ...props,
       glyph: PICKUP_GLYPH,
       label,
       passable: true,
     });
+    this.detail = detail;
   }
 
   /**
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index 4f4a35e..df81fde 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -470,6 +470,9 @@ function readPickup(extra: EntitySnapshotExtra, id: string): PickupSnapshot {
     label: requireString(p.label, `restore: pickup ${id} label must be a non-empty string`),
     secured: requireBoolean(p.secured, `restore: pickup ${id} secured must be boolean`),
     armed: requireBoolean(p.armed, `restore: pickup ${id} armed must be boolean`),
+    // P3.M6.4: optional flavor detail (Score blueprint). Absent on legacy saves
+    // and ordinary pickups; preserved when present.
+    ...(typeof p.detail === 'string' ? { detail: p.detail } : {}),
   };
 }
 
@@ -800,7 +803,7 @@ const ENTITY_RESTORE: Partial<Record<EntityArchetypeId, RestoreEntry>> = Object.
   pickup: {
     buildProps(extra, rec) {
       const p = readPickup(extra, rec.id);
-      return { label: p.label, secured: p.secured, armed: p.armed };
+      return { label: p.label, secured: p.secured, armed: p.armed, detail: p.detail };
     },
     apply(entity, _extra, rec) {
       if (!(entity instanceof Pickup)) {
diff --git a/src/input/applyIntent.ts b/src/input/applyIntent.ts
index a488842..b5003ea 100644
--- a/src/input/applyIntent.ts
+++ b/src/input/applyIntent.ts
@@ -324,8 +324,11 @@ function collectTileLoot(ctx: ApplyIntentContext) {
   const { world, player, log } = ctx;
   const objectivePickup = player.alive ? world.objectivePickupAt(player.x, player.y) : null;
   if (objectivePickup) {
+    const flavor = objectivePickup.detail;
     objectivePickup.secureWalkOnto(world);
     log(`> ${entityLabel(player)} secures ${objectivePickup.label}.`);
+    // P3.M6.4: a Score blueprint carries a flavor beat — surface what was stolen.
+    if (flavor) log(`> ${flavor}`);
   }
   // Capability sniff (P3.M3.6): the CyberAvatar carries no gear — pickups
   // stay on the tile for whoever has pockets.
diff --git a/src/shell/domTypes.ts b/src/shell/domTypes.ts
index 064a0ff..fa2c945 100644
--- a/src/shell/domTypes.ts
+++ b/src/shell/domTypes.ts
@@ -34,6 +34,7 @@ export type CrashDumpElement = ModalElement & {
 
 export type GameOverElement = ModalElement & {
   setSummary(summary: CampaignSummary): void;
+  setScoreReward(reward: { label: string; flavor: string } | null): void;
 };
 
 export type FaultScreenElement = ModalElement & {
diff --git a/src/shell/shellRuntime.ts b/src/shell/shellRuntime.ts
index f3ec1a5..6fda52c 100644
--- a/src/shell/shellRuntime.ts
+++ b/src/shell/shellRuntime.ts
@@ -723,7 +723,7 @@ function onCrewRecruit(evt: Event) {
       campaign.canAttemptScore() &&
       !currentJobOptions.some(contract => contract.context.recipeId === 'score-final')
     ) {
-      currentJobOptions.push(campaign.buildScoreContract());
+      currentJobOptions.push(campaign.buildScoreContract(dataStore.unlockedScoreableItems));
     }
     // Refresh the roster to reflect the new crew + hide recruit section.
     presentCrewRoster();
@@ -752,7 +752,7 @@ function generateCurrentJobOptions(): Contract[] {
   }
   const contracts = campaign.curator.generateContracts(campaign.rng, campaign);
   if (campaign.canAttemptScore()) {
-    contracts.push(campaign.buildScoreContract());
+    contracts.push(campaign.buildScoreContract(dataStore.unlockedScoreableItems));
   }
   return contracts;
 }
@@ -1130,8 +1130,21 @@ function handlePersist() {
 }
 
 function presentEndedCampaignOverlay(c: Campaign): void {
+  // P3.M6.4: commit a stolen blueprint to the cross-campaign meta-store before
+  // archiving the summary. Idempotent (duplicate id → no-op), so it's safe on
+  // both live Score completion and a restored already-ended save.
+  const unlockedItemId = c.scoreUnlockedItemId;
+  if (unlockedItemId) dataStore.archiveScoreableItem(unlockedItemId);
   const summary = dataStore.archiveCampaign(buildCampaignSummary(c, new Date().toISOString()));
   gameOverEl.setSummary(summary);
+  // P3.M6.4: name the stolen blueprint on the win screen. Re-derived from the
+  // meta-store id on both live completion and a restored ended save.
+  if (unlockedItemId) {
+    const item = getItemById(unlockedItemId);
+    gameOverEl.setScoreReward({ label: item.label, flavor: item.flavor ?? '' });
+  } else {
+    gameOverEl.setScoreReward(null);
+  }
 }
 
 function presentCampaignEnd(c: Campaign): void {
diff --git a/tests/unit/game/scoreFinal.test.ts b/tests/unit/game/scoreFinal.test.ts
index e429375..244750d 100644
--- a/tests/unit/game/scoreFinal.test.ts
+++ b/tests/unit/game/scoreFinal.test.ts
@@ -8,8 +8,14 @@ import { CyberspaceLayer } from '../../../src/game/cyber/CyberspaceLayer.js';
 import { Door } from '../../../src/game/entities/Door.js';
 import { JackInPoint } from '../../../src/game/entities/JackInPoint.js';
 import { Pickup } from '../../../src/game/entities/Pickup.js';
-import { snapshot, restore } from '../../../src/game/persistence.js';
+import {
+  snapshot,
+  restore,
+  snapshotCampaign,
+  restoreCampaign,
+} from '../../../src/game/persistence.js';
 import { buildCrewMember } from '../../../src/game/archetypes/index.js';
+import { SCOREABLE_ITEMS, SCOREABLE_ITEM_IDS } from '../../../src/game/items.js';
 import { CONTRACT_DIFFICULTY } from '../../../src/game/constants.js';
 import { OBJECTIVES } from '../../../src/game/hub/Curator.js';
 import { Rng } from '../../../src/rng.js';
@@ -232,3 +238,148 @@ test('Campaign records partial Score as terminal without full reward', () => {
   assert.equal(campaign.endReason, 'score-partial');
   assert.equal(campaign.credits, 25);
 });
+
+// ---------------------------------------------------------------------------
+// P3.M6.4 — Score target draws an unacquired scoreable blueprint
+// ---------------------------------------------------------------------------
+
+/** A Score-ready campaign (Act 3, living Decker + partner, designated target). */
+function scoreReadyCampaign() {
+  const campaign = new Campaign({
+    seed: 42,
+    credits: 25,
+    rep: 65,
+    completedJobs: 9,
+    siteRoster: [
+      scoreSite(),
+      scoreSite({ id: 'case-1', tier: 'roster', scoreTarget: false, seed: '101' }),
+      scoreSite({ id: 'case-2', tier: 'roster', scoreTarget: false, seed: '102' }),
+    ],
+  });
+  assert.ok(campaign.canAttemptScore(), 'fixture should be Score-ready');
+  return campaign;
+}
+
+test('buildScoreContract embeds an unacquired scoreable blueprint id + frames briefing', () => {
+  const campaign = scoreReadyCampaign();
+  const contract = campaign.buildScoreContract([]);
+  const itemId = contract.objective.params!.scoreItemId as string;
+  assert.ok(SCOREABLE_ITEM_IDS.has(itemId), `payload "${itemId}" must be a known scoreable`);
+  const item = SCOREABLE_ITEMS.find(i => i.id === itemId)!;
+  // Briefing frames the heist around the specific prototype.
+  assert.ok(contract.objective.briefing.includes(item.label), 'briefing names the payload');
+});
+
+test('buildScoreContract payload selection is deterministic for a campaign', () => {
+  const campaign = scoreReadyCampaign();
+  const a = campaign.buildScoreContract([]).objective.params!.scoreItemId;
+  const b = campaign.buildScoreContract([]).objective.params!.scoreItemId;
+  assert.equal(a, b, 'same seed + same acquired set → same payload');
+});
+
+test('buildScoreContract excludes already-acquired blueprints', () => {
+  const campaign = scoreReadyCampaign();
+  const firstPick = campaign.buildScoreContract([]).objective.params!.scoreItemId as string;
+  // Acquire the would-be pick — the Score must now target a different blueprint.
+  const nextPick = campaign.buildScoreContract([firstPick]).objective.params!.scoreItemId as string;
+  assert.notEqual(nextPick, firstPick);
+  assert.ok(SCOREABLE_ITEM_IDS.has(nextPick));
+});
+
+test('buildScoreContract targets the sole remaining blueprint when all others are acquired', () => {
+  const campaign = scoreReadyCampaign();
+  const allIds = SCOREABLE_ITEMS.map(i => i.id);
+  const remaining = allIds[3]!; // arbitrary survivor
+  const acquired = allIds.filter(id => id !== remaining);
+  const pick = campaign.buildScoreContract(acquired).objective.params!.scoreItemId;
+  assert.equal(pick, remaining);
+});
+
+test('buildScoreContract never rolls a retired/foreign id passed as acquired', () => {
+  const campaign = scoreReadyCampaign();
+  // A ghost id isn't in the pool, so it can't shrink it — selection is unchanged.
+  const baseline = campaign.buildScoreContract([]).objective.params!.scoreItemId;
+  const withGhost = campaign.buildScoreContract(['ghost-blueprint']).objective.params!.scoreItemId;
+  assert.equal(withGhost, baseline);
+  assert.ok(SCOREABLE_ITEM_IDS.has(withGhost as string));
+});
+
+test('buildScoreContract on an exhausted pool drops the payload id (abstract target is M6.5)', () => {
+  const campaign = scoreReadyCampaign();
+  const allAcquired = SCOREABLE_ITEMS.map(i => i.id);
+  const contract = campaign.buildScoreContract(allAcquired);
+  assert.equal(contract.objective.params!.scoreItemId, undefined);
+  // Generic framing, no specific prototype named.
+  assert.ok(contract.objective.briefing.length > 0);
+});
+
+test('clean Score completion records the stolen blueprint for the meta-store', () => {
+  const campaign = scoreReadyCampaign();
+  const decker = campaign.crew.find(member => member.archetype === 'Decker')!;
+  const partner = campaign.crew.find(member => member.archetype !== 'Decker')!;
+  const contract = campaign.buildScoreContract([]);
+  const expectedId = contract.objective.params!.scoreItemId as string;
+  campaign.deployCrewMember(decker.id, contract, partner.id).enterCombat();
+
+  campaign.onJobEnd({ outcome: OUTCOME.EXIT, completed: true });
+  assert.equal(campaign.endReason, 'score-complete');
+  assert.equal(campaign.scoreUnlockedItemId, expectedId, 'unlock recorded for settlement');
+});
+
+test('partial Score records no blueprint unlock (prototype not secured)', () => {
+  const campaign = scoreReadyCampaign();
+  const decker = campaign.crew.find(member => member.archetype === 'Decker')!;
+  const partner = campaign.crew.find(member => member.archetype !== 'Decker')!;
+  campaign.deployCrewMember(decker.id, campaign.buildScoreContract([]), partner.id).enterCombat();
+
+  campaign.onJobEnd({ outcome: OUTCOME.EXIT, completed: false });
+  assert.equal(campaign.endReason, 'score-partial');
+  assert.equal(campaign.scoreUnlockedItemId, null);
+});
+
+test('Score payload pickup is labelled + flavored from the target blueprint', () => {
+  const item = SCOREABLE_ITEMS[0]!;
+  const contract = scoreContract();
+  contract.objective.params = { ...contract.objective.params, scoreItemId: item.id };
+  const run = new Run({ crewMember: makeDecker(), partnerMember: makeMerc(), seed: 100 });
+  run.enterBriefing(contract);
+  run.enterCombat();
+  const payload = scorePayload(run);
+  assert.equal(payload.label, item.label);
+  assert.equal(payload.detail, item.flavor);
+});
+
+test('Score payload falls back to a generic label with no flavor for an abstract target', () => {
+  const run = scoreRun(); // scoreContract() carries no scoreItemId
+  const payload = scorePayload(run);
+  assert.equal(payload.label, 'Score payload');
+  assert.equal(payload.detail, undefined);
+});
+
+test('Score payload flavor detail survives a run snapshot/restore', () => {
+  const item = SCOREABLE_ITEMS[0]!;
+  const contract = scoreContract();
+  contract.objective.params = { ...contract.objective.params, scoreItemId: item.id };
+  const run = new Run({ crewMember: makeDecker(), partnerMember: makeMerc(), seed: 100 });
+  run.enterBriefing(contract);
+  run.enterCombat();
+
+  const { run: restored } = restore(structuredClone(snapshot(run)));
+  const payload = scorePayload(restored);
+  assert.equal(payload.label, item.label);
+  assert.equal(payload.detail, item.flavor);
+});
+
+test('recorded Score unlock survives campaign snapshot/restore (resume can still write it)', () => {
+  const campaign = scoreReadyCampaign();
+  const decker = campaign.crew.find(member => member.archetype === 'Decker')!;
+  const partner = campaign.crew.find(member => member.archetype !== 'Decker')!;
+  const contract = campaign.buildScoreContract([]);
+  const expectedId = contract.objective.params!.scoreItemId as string;
+  campaign.deployCrewMember(decker.id, contract, partner.id).enterCombat();
+  campaign.onJobEnd({ outcome: OUTCOME.EXIT, completed: true });
+
+  const restored = restoreCampaign(snapshotCampaign(campaign));
+  assert.equal(restored.endReason, 'score-complete');
+  assert.equal(restored.scoreUnlockedItemId, expectedId);
+});
diff --git a/tests/unit/input/applyIntent.test.ts b/tests/unit/input/applyIntent.test.ts
index f4b7b0c..5f5c4aa 100644
--- a/tests/unit/input/applyIntent.test.ts
+++ b/tests/unit/input/applyIntent.test.ts
@@ -246,6 +246,38 @@ test('move onto an objective pickup secures it without routing to interact', ()
   assert.ok(log.some(l => l.includes('secures Sublevel cache')));
 });
 
+test('securing a pickup with flavor detail logs the flavor as a second beat', () => {
+  const { ctx, log, world } = buildCtx({ placeDrone: false });
+  world.addEntity(
+    new Pickup({
+      id: 'pickup-0',
+      x: 2,
+      y: 3,
+      label: 'Monoblade',
+      detail: 'A monomolecular blade schematic — an edge that never dulls.',
+    })
+  );
+
+  applyIntent({ type: 'move', dx: 0, dy: 1 }, ctx);
+
+  assert.ok(log.some(l => l.includes('secures Monoblade')));
+  assert.ok(
+    log.some(l => l.includes('A monomolecular blade schematic')),
+    'flavor detail surfaced on secure'
+  );
+});
+
+test('securing a pickup without detail logs only the secure beat', () => {
+  const { ctx, log, world } = buildCtx({ placeDrone: false });
+  world.addEntity(new Pickup({ id: 'pickup-0', x: 2, y: 3, label: 'Plain cache' }));
+
+  applyIntent({ type: 'move', dx: 0, dy: 1 }, ctx);
+
+  const beats = log.filter(l => l.startsWith('> '));
+  assert.equal(beats.length, 1, 'no flavor beat without detail');
+  assert.ok(beats[0]!.includes('secures Plain cache'));
+});
+
 test('move onto a consumable pickup adds it to inventory and removes the pickup', () => {
   const { ctx, log, player, world } = buildCtx({ placeDrone: false });
   world.addEntity(

From 4c03436772d660ba0eb61ff157265b8a85ab3e73 Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Thu, 25 Jun 2026 15:37:53 -0700
Subject: [PATCH 53/55] persist score blueprints to history

---
 components/GameOver.ts                  | 19 +----
 docs/phase-3-plan.md                    | 13 +++-
 src/game/campaignSummary.ts             | 97 ++++++++++++++++++++++---
 src/shell/domTypes.ts                   |  1 -
 src/shell/shellRuntime.ts               | 10 +--
 tests/unit/game/campaignSummary.test.ts | 46 ++++++++++++
 6 files changed, 145 insertions(+), 41 deletions(-)

diff --git a/components/GameOver.ts b/components/GameOver.ts
index 1f1852c..4b666fd 100644
--- a/components/GameOver.ts
+++ b/components/GameOver.ts
@@ -266,12 +266,8 @@ function detailCopy(summary: CampaignSummary): string {
   return 'Every crew slot on the roster is flatlined. Their campaign ends here.';
 }
 
-/** Presentation-only Score prize (P3.M6.4) — not part of the persisted summary. */
-export type ScoreReward = { label: string; flavor: string };
-
 class GameOver extends HTMLElement {
   #summary: CampaignSummary | null = null;
-  #scoreReward: ScoreReward | null = null;
   #ready = false;
   #els: {
     banner: HTMLElement;
@@ -369,17 +365,6 @@ class GameOver extends HTMLElement {
     if (this.#ready) this.#render();
   }
 
-  /**
-   * Set (or clear) the stolen Score blueprint shown on a win (P3.M6.4).
-   * Presentation-only — the persisted {@link CampaignSummary} schema is
-   * untouched; the shell re-derives this from the meta-store on both live
-   * completion and a restored ended save.
-   */
-  setScoreReward(reward: ScoreReward | null) {
-    this.#scoreReward = reward;
-    if (this.#ready) this.#render();
-  }
-
   show() {
     this.setAttribute('open', '');
     queueMicrotask(() => {
@@ -401,8 +386,8 @@ class GameOver extends HTMLElement {
     this.#els.banner.textContent = summary.result === 'win' ? 'SCORE COMPLETE' : 'GAME OVER';
     this.#els.reason.textContent = reasonCopy(summary);
     this.#els.detail.textContent = detailCopy(summary);
-    // Score prize — only meaningful on a win that stole a blueprint.
-    const reward = summary.result === 'win' ? this.#scoreReward : null;
+    // Score prize — present on a win that stole a specific blueprint.
+    const reward = summary.result === 'win' ? (summary.scoreReward ?? null) : null;
     if (reward) {
       this.#els.rewardName.textContent = reward.label;
       this.#els.rewardFlavor.textContent = reward.flavor;
diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 51b891f..81f2b4b 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -558,10 +558,15 @@ credit-payload Score is M6.5.
 
 *Messaging polish (playtest feedback):* the Score payload pickup is now labelled with the
 target blueprint and carries its `flavor` (new optional `Pickup.detail`, persisted), so the
-grab logs e.g. `secures Monoblade` followed by the flavor beat; the `<game-over>` win screen
-names the stolen blueprint + flavor via a presentation-only `setScoreReward` (re-derived from
-`scoreUnlockedItemId`, **not** added to the validated `CampaignSummary` schema). Abstract /
-exhausted-pool Scores keep the generic "Score payload" with no flavor beat.
+grab logs e.g. `secures Monoblade` followed by the flavor beat. The stolen blueprint is
+captured **in the `CampaignSummary`** as an optional, self-contained `scoreReward`
+(`{ id, label, flavor }`) — `buildCampaignSummary` resolves it from `scoreUnlockedItemId`,
+and `<game-over>` reads it straight off the summary on a win. Persisting it (rather than a
+presentation-only setter) seeds the **M7 Chronicle**, which will surface acquisitions from
+history. `validateCampaignSummary` gained a `requireKeys(required, optional)` helper so the
+schema tolerates the new optional field (and future ones); the reward is validated
+self-contained and round-trips through clone. Abstract / exhausted-pool Scores carry no
+`scoreReward` and keep the generic "Score payload" pickup.
 
 **Recorded design decisions:**
 
diff --git a/src/game/campaignSummary.ts b/src/game/campaignSummary.ts
index dc3b124..4ed8d2d 100644
--- a/src/game/campaignSummary.ts
+++ b/src/game/campaignSummary.ts
@@ -1,4 +1,5 @@
 import type { CampaignEndReason } from '../types.js';
+import { SCOREABLE_ITEMS } from './items.js';
 
 export const CAMPAIGN_HISTORY_CAP = 50;
 
@@ -10,6 +11,18 @@ export type CampaignSummaryCrew = {
   flatlined: boolean;
 };
 
+/**
+ * Blueprint stolen by a winning Score (P3.M6.4), captured self-contained
+ * (id + display copy) so the record reads correctly forever even if the catalog
+ * changes. Absent on losses, partials, and abstract (exhausted-pool) Scores.
+ * Surfaced on the win screen now and the Chronicle in M7.
+ */
+export type CampaignSummaryScoreReward = {
+  id: string;
+  label: string;
+  flavor: string;
+};
+
 export type CampaignSummary = {
   campaignId: string;
   completedAt: string;
@@ -20,6 +33,8 @@ export type CampaignSummary = {
   rep: number;
   credits: number;
   crewRoster: CampaignSummaryCrew[];
+  /** Optional — present only when a win stole a specific blueprint. */
+  scoreReward?: CampaignSummaryScoreReward;
 };
 
 type EndedCampaignLike = {
@@ -30,6 +45,8 @@ type EndedCampaignLike = {
   completedJobs: number;
   rep: number;
   credits: number;
+  /** The stolen blueprint id (P3.M6.4); resolved to display copy in the summary. */
+  scoreUnlockedItemId?: string | null;
   crew: Array<{
     id: string;
     callsign: string | null;
@@ -38,6 +55,14 @@ type EndedCampaignLike = {
   }>;
 };
 
+/** Resolve a stolen-blueprint id to a self-contained summary reward (or undefined). */
+function resolveScoreReward(id: string | null | undefined): CampaignSummaryScoreReward | undefined {
+  if (typeof id !== 'string') return undefined;
+  const item = SCOREABLE_ITEMS.find(entry => entry.id === id);
+  if (!item) return undefined;
+  return { id: item.id, label: item.label, flavor: item.flavor ?? '' };
+}
+
 const END_REASONS: readonly CampaignEndReason[] = [
   'crew-wipe',
   'clock-expired',
@@ -60,6 +85,7 @@ export function buildCampaignSummary(
     throw new Error('buildCampaignSummary requires a campaign end reason');
   }
 
+  const scoreReward = resolveScoreReward(campaign.scoreUnlockedItemId);
   return validateCampaignSummary({
     campaignId: campaign.id,
     completedAt,
@@ -74,6 +100,7 @@ export function buildCampaignSummary(
       archetype: member.archetype,
       flatlined: member.flatlined,
     })),
+    ...(scoreReward ? { scoreReward } : {}),
   });
 }
 
@@ -82,17 +109,21 @@ export function validateCampaignSummary(value: unknown): CampaignSummary {
     throw new TypeError('CampaignSummary must be a plain object');
   }
   const summary = value as Record<string, unknown>;
-  requireExactKeys(summary, [
-    'campaignId',
-    'completedAt',
-    'result',
-    'endReason',
-    'seed',
-    'completedJobs',
-    'rep',
-    'credits',
-    'crewRoster',
-  ]);
+  requireKeys(
+    summary,
+    [
+      'campaignId',
+      'completedAt',
+      'result',
+      'endReason',
+      'seed',
+      'completedJobs',
+      'rep',
+      'credits',
+      'crewRoster',
+    ],
+    ['scoreReward']
+  );
   const campaignId = requireNonEmptyString(summary.campaignId, 'CampaignSummary.campaignId');
   const completedAt = requireIsoTimestamp(summary.completedAt);
   if (summary.result !== 'win' && summary.result !== 'partial' && summary.result !== 'loss') {
@@ -117,6 +148,7 @@ export function validateCampaignSummary(value: unknown): CampaignSummary {
     throw new TypeError('CampaignSummary.crewRoster must be an array');
   }
   const crewRoster = summary.crewRoster.map((member, index) => validateCrew(member, index));
+  const scoreReward = validateScoreReward(summary.scoreReward);
 
   return {
     campaignId,
@@ -128,6 +160,23 @@ export function validateCampaignSummary(value: unknown): CampaignSummary {
     rep,
     credits,
     crewRoster,
+    ...(scoreReward ? { scoreReward } : {}),
+  };
+}
+
+function validateScoreReward(value: unknown): CampaignSummaryScoreReward | undefined {
+  if (value === undefined) return undefined;
+  if (!isPlainObject(value)) {
+    throw new TypeError('CampaignSummary.scoreReward must be a plain object when present');
+  }
+  requireKeys(value, ['id', 'label', 'flavor'], [], 'CampaignSummary.scoreReward');
+  if (typeof value.flavor !== 'string') {
+    throw new TypeError('CampaignSummary.scoreReward.flavor must be a string');
+  }
+  return {
+    id: requireNonEmptyString(value.id, 'CampaignSummary.scoreReward.id'),
+    label: requireNonEmptyString(value.label, 'CampaignSummary.scoreReward.label'),
+    flavor: value.flavor,
   };
 }
 
@@ -175,6 +224,7 @@ export function cloneCampaignSummary(summary: CampaignSummary): CampaignSummary
   return {
     ...summary,
     crewRoster: summary.crewRoster.map(member => ({ ...member })),
+    ...(summary.scoreReward ? { scoreReward: { ...summary.scoreReward } } : {}),
   };
 }
 
@@ -241,3 +291,28 @@ function requireExactKeys(value: Record<string, unknown>, expected: readonly str
     throw new TypeError(`CampaignSummary keys must be exactly ${wanted.join(', ')}`);
   }
 }
+
+/**
+ * Like {@link requireExactKeys} but tolerant of optional keys: every `required`
+ * key must be present, and no key outside `required ∪ optional` may appear.
+ * Lets the schema gain optional fields (e.g. `scoreReward`) without rejecting
+ * older summaries that predate them.
+ */
+function requireKeys(
+  value: Record<string, unknown>,
+  required: readonly string[],
+  optional: readonly string[],
+  label = 'CampaignSummary'
+): void {
+  const allowed = new Set([...required, ...optional]);
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) {
+      throw new TypeError(`${label} has unexpected key "${key}"`);
+    }
+  }
+  for (const key of required) {
+    if (!(key in value)) {
+      throw new TypeError(`${label} is missing required key "${key}"`);
+    }
+  }
+}
diff --git a/src/shell/domTypes.ts b/src/shell/domTypes.ts
index fa2c945..064a0ff 100644
--- a/src/shell/domTypes.ts
+++ b/src/shell/domTypes.ts
@@ -34,7 +34,6 @@ export type CrashDumpElement = ModalElement & {
 
 export type GameOverElement = ModalElement & {
   setSummary(summary: CampaignSummary): void;
-  setScoreReward(reward: { label: string; flavor: string } | null): void;
 };
 
 export type FaultScreenElement = ModalElement & {
diff --git a/src/shell/shellRuntime.ts b/src/shell/shellRuntime.ts
index 6fda52c..28fb669 100644
--- a/src/shell/shellRuntime.ts
+++ b/src/shell/shellRuntime.ts
@@ -1135,16 +1135,10 @@ function presentEndedCampaignOverlay(c: Campaign): void {
   // both live Score completion and a restored already-ended save.
   const unlockedItemId = c.scoreUnlockedItemId;
   if (unlockedItemId) dataStore.archiveScoreableItem(unlockedItemId);
+  // The summary captures the stolen blueprint (P3.M6.4) for the win screen and
+  // the M7 Chronicle; `<game-over>` reads it straight off the summary.
   const summary = dataStore.archiveCampaign(buildCampaignSummary(c, new Date().toISOString()));
   gameOverEl.setSummary(summary);
-  // P3.M6.4: name the stolen blueprint on the win screen. Re-derived from the
-  // meta-store id on both live completion and a restored ended save.
-  if (unlockedItemId) {
-    const item = getItemById(unlockedItemId);
-    gameOverEl.setScoreReward({ label: item.label, flavor: item.flavor ?? '' });
-  } else {
-    gameOverEl.setScoreReward(null);
-  }
 }
 
 function presentCampaignEnd(c: Campaign): void {
diff --git a/tests/unit/game/campaignSummary.test.ts b/tests/unit/game/campaignSummary.test.ts
index 452e22a..4be5829 100644
--- a/tests/unit/game/campaignSummary.test.ts
+++ b/tests/unit/game/campaignSummary.test.ts
@@ -6,12 +6,14 @@ import {
   CAMPAIGN_HISTORY_CAP,
   archiveCampaignSummary,
   buildCampaignSummary,
+  cloneCampaignSummary,
   normalizeCampaignHistory,
   validateCampaignSummary,
   type CampaignSummary,
 } from '../../../src/game/campaignSummary.js';
 import { OUTCOME } from '../../../src/game/Run.js';
 import { makeSalvage } from '../../../src/game/salvage.js';
+import { SCOREABLE_ITEM_IDS } from '../../../src/game/items.js';
 import type { LocationSite } from '../../../src/types.js';
 
 const COMPLETED_AT = '2026-06-14T19:30:00.000Z';
@@ -85,6 +87,11 @@ test('Score completion summary uses post-settlement jobs, Rep, and Credits', ()
   assert.equal(record.credits, 125 + SCORE_CREDITS_REWARD);
   assert.equal('salvage' in record, false);
   assert.ok(record.crewRoster.some(member => member.archetype === 'Decker'));
+  // P3.M6.4: a winning Score captures the stolen blueprint, self-contained.
+  assert.ok(record.scoreReward, 'win summary carries the stolen blueprint');
+  assert.ok(SCOREABLE_ITEM_IDS.has(record.scoreReward.id));
+  assert.ok(record.scoreReward.label.length > 0);
+  assert.equal(typeof record.scoreReward.flavor, 'string');
 });
 
 test('loss summaries preserve each terminal reason and final roster state', () => {
@@ -125,6 +132,45 @@ test('CampaignSummary validation rejects mismatched outcomes and malformed credi
   );
 });
 
+test('summary without scoreReward validates (optional field, legacy-compatible)', () => {
+  const record = validateCampaignSummary(summary());
+  assert.equal(record.scoreReward, undefined);
+});
+
+test('summary with a well-formed scoreReward round-trips through validate + clone', () => {
+  const withReward = summary({
+    scoreReward: { id: 'monoblade', label: 'Monoblade', flavor: 'An edge that never dulls.' },
+  });
+  const record = validateCampaignSummary(withReward);
+  assert.deepEqual(record.scoreReward, {
+    id: 'monoblade',
+    label: 'Monoblade',
+    flavor: 'An edge that never dulls.',
+  });
+  // Clone is deep — mutating the clone must not touch the original.
+  const clone = cloneCampaignSummary(record);
+  clone.scoreReward!.label = 'CHANGED';
+  assert.equal(record.scoreReward!.label, 'Monoblade');
+});
+
+test('CampaignSummary validation rejects unexpected keys and malformed scoreReward', () => {
+  assert.throws(
+    () => validateCampaignSummary({ ...summary(), bogus: true }),
+    /unexpected key "bogus"/
+  );
+  assert.throws(
+    () => validateCampaignSummary(summary({ scoreReward: { id: 'x', label: 'X' } as never })),
+    /scoreReward is missing required key "flavor"/
+  );
+  assert.throws(
+    () =>
+      validateCampaignSummary(
+        summary({ scoreReward: { id: '', label: 'X', flavor: 'f' } as never })
+      ),
+    /scoreReward\.id/
+  );
+});
+
 test('legacy history defaults empty and imported history deduplicates then trims', () => {
   assert.deepEqual(normalizeCampaignHistory(undefined), []);
   const imported = Array.from({ length: CAMPAIGN_HISTORY_CAP + 5 }, (_, index) =>

From 347cf8ba5b3709dc6ce58fb27f80f18f963d896c Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Thu, 25 Jun 2026 15:59:57 -0700
Subject: [PATCH 54/55] finish score blueprints milestone

---
 docs/phase-3-plan.md               | 43 ++++++++++++++++--
 src/game/Campaign.ts               | 72 ++++++++++++++++++++++++++++--
 tests/unit/game/hub/Finn.test.ts   | 60 ++++++++++++++++++++++++-
 tests/unit/game/scoreFinal.test.ts | 66 +++++++++++++++++++++++++--
 4 files changed, 228 insertions(+), 13 deletions(-)

diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index 81f2b4b..d96939b 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -46,7 +46,7 @@ A new **player archetype** recruited mid-campaign (late Act 1 / start of Act 2),
 | P3.M3 — Cyberspace grid + ICE | ✅ Done (full ICE roster: Probe, Spark, Guardian) |
 | P3.M4 — Simstim flip (dual-deploy) | ✅ Done |
 | P3.M5 — The Score (climactic mission) | ✅ Done |
-| P3.M6 — Stolen Blueprints (shop rework + meta-progression) | 🟡 Meta-store + catalog split + shop rework + Score target rework shipped (M6.1–M6.4) |
+| P3.M6 — Stolen Blueprints (shop rework + meta-progression) | ✅ Meta-store, catalog split, shop rework, Score target rework, abstract targets, and hub surface shipped (M6.1–M6.6) |
 | P3.M7 — Chronicle (campaign narrative memory) | 🟡 End-summary foundation shipped |
 
 **Phase 3** is complete when:
@@ -452,8 +452,8 @@ Placement is collision-safe (`pickFreeRingTile` consumes one rng draw then scans
 | **P3.M6.2 Item catalog split** | ✅ | Define `DEFAULT_ITEMS` and `SCOREABLE_ITEMS` catalogs; retire `minRepTier` as shop gate; add at least 5 net-new scoreable items (fully wired gear) | catalog validation, no duplicate IDs, all items have required fields, `minRepTier` not read by shop |
 | **P3.M6.3 Shop rework** | ✅ | Shop stocks `DEFAULT_ITEMS + unlockedScoreableItems`; no rep gate; locked scoreable items not rendered | shop shows only default items when meta-store is empty; adds unlocked scoreable items as they accrue; rep change has no effect on stock |
 | **P3.M6.4 Score target rework** | ✅ | `buildScoreContract()` draws from unacquired `SCOREABLE_ITEMS`; briefing copy reflects item; completion writes meta-store | available targets exclude acquired; retired items not rolled; store updated on complete |
-| **P3.M6.5 Abstract targets** | 🔲 | Exhausted-pool Score draws RNG credit payload from category set; seeded flavor; arc gates pass with empty scoreable pool | category selection determinism, arc unaffected, no meta-store write |
-| **P3.M6.6 Hub surface** | 🔲 | Shop renders only purchasable items; no locked placeholders | shop never renders a locked scoreable item regardless of meta-store state |
+| **P3.M6.5 Abstract targets** | ✅ | Exhausted-pool Score draws RNG credit payload from category set; seeded flavor; arc gates pass with empty scoreable pool | category selection determinism, arc unaffected, no meta-store write |
+| **P3.M6.6 Hub surface** | ✅ | Shop renders only purchasable items; no locked placeholders | shop never renders a locked scoreable item regardless of meta-store state |
 
 **P3.M6.1 implementation note:** The meta-progression store lands as a new
 `DataStore` key, `unlockedScoreableItems: string[]` (item IDs, acquisition order,
@@ -568,6 +568,41 @@ schema tolerates the new optional field (and future ones); the reward is validat
 self-contained and round-trips through clone. Abstract / exhausted-pool Scores carry no
 `scoreReward` and keep the generic "Score payload" pickup.
 
+**P3.M6.5 implementation note:** When `pickScorePayload` returns `null` (every
+scoreable blueprint already stolen), `buildScoreContract` now draws an abstract
+credit payload via `pickAbstractScorePayload(seed)` instead of the old flat
+generic line. The pick is seeded from the **Score target site seed** XORed with
+its own salt (`ABSTRACT_SCORE_PAYLOAD_SALT`, distinct from `SCORE_PAYLOAD_SALT`),
+so the category is deterministic per campaign and independent of both the map
+roll and the (empty) blueprint draw. `ABSTRACT_SCORE_TARGETS` is a frozen set of
+`{ id, label, flavor }` categories (liquid reserves, bearer bonds, slush fund,
+cold-wallet keys, payroll skim) — "you've stolen everything worth stealing; now
+you're just taking their money." The abstract briefing is framed from the chosen
+category's `flavor` + `label`. Crucially the contract carries **no
+`scoreItemId`**, so a clean abstract Score settles the arc (`score-complete`,
+`SCORE_CREDITS_REWARD` paid) exactly like a blueprint Score but
+`scoreUnlockedItemId` stays `null` and the terminal-settlement meta-store write
+is a no-op. The Score payload pickup keeps its generic "Score payload" label with
+no flavor (the M6.4 Run-side fallback already handles a missing id). Arc gating
+never read the scoreable pool, so "arc unaffected with an empty pool" is
+structural — the new test exercises it end-to-end (build → deploy → complete)
+for regression cover.
+
+**P3.M6.6 implementation note:** The substantive hub-surface change — stock is
+`DEFAULT_ITEMS + unlocked scoreable` with locked blueprints filtered out — landed
+in M6.3's `getShopCatalog`, the single filtering chokepoint. `<finn-shop>` renders
+strictly the catalog handed to `setCatalog` (grouped by scope; unaffordable rows
+are disabled, never locked), and `presentFinnShop` is the only caller — it always
+feeds `Finn.catalog(dataStore.unlockedScoreableItems)`. So there was **no new
+production code** for M6.6; the milestone is the hub-surface regression cover the
+acceptance names. The guard is a meta-store **state sweep** at the `Finn.catalog`
+boundary (empty / one unlock / all unlocked / ghost ids / duplicates) asserting a
+scoreable is stocked iff unlocked and never as a locked placeholder, plus a
+companion check that every surfaced row is a real purchasable item (default or
+unlocked scoreable). `<finn-shop>` renders only the catalog handed to
+`setCatalog`, so the boundary filter is the invariant's single seam. The deferred
+`ACQUISITIONS: N / M` counter remains an M7 Chronicle concern. **M6 complete.**
+
 **Recorded design decisions:**
 
 - **Why `minRepTier` is retired as a shop gate:** Rep-gated access was mechanical — the best gear was reachable by grinding rep without doing anything interesting. Two explicit catalogs make availability rules legible in the data rather than computed from a tier comparison at runtime.
@@ -593,7 +628,7 @@ self-contained and round-trips through clone. Abstract / exhausted-pool Scores c
 
 **Scope:**
 
-- **Active campaign chronicle:** Entries for each run (jobs taken, outcomes, objectives completed/failed, major Rep deltas, crew changes, Decker recruitment, Score prep milestones) stored **in the campaign save**.
+- **Active campaign chronicle:** Entries for each run (jobs taken, outcomes, objectives completed/failed, major Rep deltas, crew changes, Decker recruitment, Score prep milestones, Score target blueprint / credits stolen when all items are unlocked) stored **in the campaign save**.
 - **Arc-aware entries:** Chronicle entries reflect the campaign's narrative arc — Act 1 entries read as "getting established"; Act 2 entries reference the Score target; Act 3 entries build tension toward the climax.
 - **Presentation:** Surfaced from a new Hub entry point (not the existing crew terminal: it remains focused on crew stats, inventory, and recruiting).
 - **Campaign end summary:** On win (Score completed) or loss (flatline / clock expired), roll up a **summary record** into a **persistent history** list (localStorage / DataStore — same durability pattern as runs/prefs). High-scores-style: scannable list with campaign stats, arc outcome, run count, crew roster at end.
diff --git a/src/game/Campaign.ts b/src/game/Campaign.ts
index 5f0e705..80c61ec 100644
--- a/src/game/Campaign.ts
+++ b/src/game/Campaign.ts
@@ -102,7 +102,8 @@ const SCORE_PAYLOAD_SALT = 0x5c07e;
  * Draws from {@link SCOREABLE_ITEMS} minus the meta-crew's already-stolen ids;
  * a retired/forward-version id in `acquiredIds` simply isn't in the pool, so it
  * is never rolled. Returns `null` when the pool is exhausted (every blueprint
- * stolen) — the abstract-payload Score is M6.5's job.
+ * stolen) — at which point the Score falls back to an abstract credit payload
+ * via {@link pickAbstractScorePayload} (P3.M6.5).
  */
 function pickScorePayload(seed: number, acquiredIds: readonly string[]): Item | null {
   const acquired = new Set(acquiredIds);
@@ -112,6 +113,65 @@ function pickScorePayload(seed: number, acquiredIds: readonly string[]): Item |
   return pool[Math.floor(rng.next() * pool.length)] ?? null;
 }
 
+/**
+ * An abstract Score target (P3.M6.5). When every scoreable blueprint has been
+ * stolen, the heist has nothing new to reverse-engineer — so the crew goes for
+ * the principal's liquid assets instead. Each category frames the same
+ * campaign-ending credit payday with a distinct fiction; it carries no item id,
+ * so a completed abstract Score writes nothing to the meta-store.
+ */
+export type AbstractScoreTarget = { id: string; label: string; flavor: string };
+
+export const ABSTRACT_SCORE_TARGETS: readonly AbstractScoreTarget[] = Object.freeze([
+  {
+    id: 'liquid-reserves',
+    label: 'liquid reserves',
+    flavor:
+      "Their R&D vaults are picked clean — nothing left worth reverse-engineering. So this run, you go for the money.",
+  },
+  {
+    id: 'bearer-bonds',
+    label: 'bearer-bond cache',
+    flavor:
+      "No prototypes left to lift; this time it's a strongbox of untraceable bearer bonds.",
+  },
+  {
+    id: 'slush-fund',
+    label: 'off-books slush fund',
+    flavor: "You've stolen every blueprint they had. Now you're draining the off-books slush fund.",
+  },
+  {
+    id: 'cold-wallet',
+    label: 'crypto cold-wallet keys',
+    flavor:
+      'The labs hold nothing new — so the take is the cold-wallet keys to their crypto reserves.',
+  },
+  {
+    id: 'payroll-skim',
+    label: 'payroll clearing account',
+    flavor:
+      'Nothing left to reverse-engineer. You settle for siphoning the payroll clearing account dry.',
+  },
+]);
+
+/** Salt mixed into the Score seed for the abstract draw, independent of the blueprint roll. */
+const ABSTRACT_SCORE_PAYLOAD_SALT = 0xab57a;
+
+/**
+ * Deterministically pick the abstract credit payload for an exhausted-pool
+ * Score. Seeded from the target seed (XORed with its own salt) so the category
+ * is stable per campaign yet independent of both the map roll and the blueprint
+ * draw. Always returns a target — the set is non-empty by construction.
+ */
+function pickAbstractScorePayload(seed: number): AbstractScoreTarget {
+  const rng = new Rng(((seed >>> 0) ^ ABSTRACT_SCORE_PAYLOAD_SALT) >>> 0);
+  const target = ABSTRACT_SCORE_TARGETS[Math.floor(rng.next() * ABSTRACT_SCORE_TARGETS.length)];
+  if (!target) {
+    throw new Error('pickAbstractScorePayload: abstract target set is empty');
+  }
+  return target;
+}
+
 /** Read the embedded heist payload id from a completed Score contract (or `null`). */
 function scorePayloadItemId(contract: Contract | null): string | null {
   const raw = contract?.objective?.params?.scoreItemId;
@@ -761,8 +821,10 @@ export class Campaign {
    * unacquired scoreable blueprint (drawn deterministically from the seed minus
    * the meta-crew's already-stolen ids), and the briefing frames the site around
    * that prototype. The chosen id rides along in `objective.params.scoreItemId`
-   * so the completion path can unlock it. An exhausted pool yields the generic
-   * framing with no payload id (abstract credit payloads are M6.5).
+   * so the completion path can unlock it. An exhausted pool (every blueprint
+   * stolen) draws an abstract credit payload instead (P3.M6.5): the briefing is
+   * framed from {@link ABSTRACT_SCORE_TARGETS} but carries no `scoreItemId`, so a
+   * clean completion writes nothing to the meta-store.
    *
    * @param unlockedScoreableIds — acquired blueprint ids from the meta-store
    *   (`DataStore.unlockedScoreableItems`); these are excluded from the draw.
@@ -792,10 +854,12 @@ export class Campaign {
       .replace(/\s+-\s+Score target$/i, '')
       .trim();
     const payload = pickScorePayload(seed, unlockedScoreableIds);
+    const abstract = payload ? null : pickAbstractScorePayload(seed);
     const briefing = payload
       ? `${payload.flavor} Their prototype is held at ${siteLabel}. Breach the facility, ` +
         `secure the ${payload.label}, and extract with the crew alive.`
-      : `Hit ${siteLabel} and extract with the crew alive.`;
+      : `${abstract!.flavor} The ${abstract!.label} sits in ${siteLabel}. Breach the facility, ` +
+        `clean it out, and extract with the crew alive.`;
     return {
       seed,
       mapWidth: target.mapWidth,
diff --git a/tests/unit/game/hub/Finn.test.ts b/tests/unit/game/hub/Finn.test.ts
index 4b6ef60..a1edb43 100644
--- a/tests/unit/game/hub/Finn.test.ts
+++ b/tests/unit/game/hub/Finn.test.ts
@@ -3,7 +3,14 @@ import assert from 'node:assert/strict';
 
 import { FACTION, SHOP_COST } from '../../../../src/game/constants.js';
 import { Finn } from '../../../../src/game/hub/Finn.js';
-import { ITEM_ID, ITEM_SCOPE, getShopCatalog, getItemById } from '../../../../src/game/items.js';
+import {
+  ITEM_ID,
+  ITEM_SCOPE,
+  getShopCatalog,
+  getItemById,
+  SCOREABLE_ITEMS,
+  SCOREABLE_ITEM_IDS,
+} from '../../../../src/game/items.js';
 import { buildHub } from '../../../../src/game/hub/SafeSpace.js';
 
 // ---------------------------------------------------------------------------
@@ -61,6 +68,57 @@ test('Finn.catalog folds in unlocked scoreable blueprints from the meta-store',
   assert.ok(!ids.includes(ITEM_ID.TARGETING_CHIP));
 });
 
+// ---------------------------------------------------------------------------
+// P3.M6.6 — Hub surface: the shop renders only purchasable items, no locked
+// placeholders. The render component (`<finn-shop>`) draws strictly from the
+// catalog it is handed, so the invariant lives at the `Finn.catalog` boundary:
+// no locked scoreable may ever appear there, whatever the meta-store holds.
+// ---------------------------------------------------------------------------
+
+test('Finn.catalog surfaces no locked scoreable across any meta-store state', () => {
+  const f = new Finn();
+  const allIds = SCOREABLE_ITEMS.map(i => i.id);
+  // A representative sweep: empty, one unlock, all unlocked, ghost ids, and
+  // duplicates — the shop must never carry a *locked* scoreable in any of them.
+  const metaStates: string[][] = [
+    [],
+    [ITEM_ID.MONOBLADE],
+    allIds,
+    ['ghost-blueprint', 'retired-mk1'],
+    [ITEM_ID.MONOBLADE, ITEM_ID.MONOBLADE, ITEM_ID.ARMOUR_PLATING],
+  ];
+  for (const unlocked of metaStates) {
+    const unlockedSet = new Set(unlocked);
+    const stockedIds = new Set(f.catalog(unlocked).map(i => i.id));
+    for (const item of SCOREABLE_ITEMS) {
+      const isUnlocked = unlockedSet.has(item.id);
+      assert.equal(
+        stockedIds.has(item.id),
+        isUnlocked,
+        `scoreable "${item.id}" stocked=${stockedIds.has(item.id)} but unlocked=${isUnlocked} ` +
+          `for meta-store [${unlocked.join(', ')}]`
+      );
+    }
+  }
+});
+
+test('Finn.catalog always carries the full default stock, no placeholder rows', () => {
+  const f = new Finn();
+  // Whatever the meta-store, every row Finn surfaces is a real, purchasable item
+  // (a default item or an unlocked scoreable) — never a locked stand-in.
+  for (const unlocked of [[], [ITEM_ID.MONOBLADE], SCOREABLE_ITEMS.map(i => i.id)]) {
+    const unlockedSet = new Set(unlocked);
+    const rows = f.catalog(unlocked);
+    for (const row of rows) {
+      const isDefault = !SCOREABLE_ITEM_IDS.has(row.id);
+      assert.ok(
+        isDefault || unlockedSet.has(row.id),
+        `row "${row.id}" is neither a default item nor an unlocked scoreable`
+      );
+    }
+  }
+});
+
 // ---------------------------------------------------------------------------
 // Item catalog (pure functions)
 // ---------------------------------------------------------------------------
diff --git a/tests/unit/game/scoreFinal.test.ts b/tests/unit/game/scoreFinal.test.ts
index 244750d..c29f339 100644
--- a/tests/unit/game/scoreFinal.test.ts
+++ b/tests/unit/game/scoreFinal.test.ts
@@ -1,7 +1,12 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 
-import { Campaign, CAMPAIGN_STATE, SCORE_CREDITS_REWARD } from '../../../src/game/Campaign.js';
+import {
+  Campaign,
+  CAMPAIGN_STATE,
+  SCORE_CREDITS_REWARD,
+  ABSTRACT_SCORE_TARGETS,
+} from '../../../src/game/Campaign.js';
 import { OUTCOME, RUN_STATE, Run } from '../../../src/game/Run.js';
 import { DataNode } from '../../../src/game/cyber/DataNode.js';
 import { CyberspaceLayer } from '../../../src/game/cyber/CyberspaceLayer.js';
@@ -304,13 +309,66 @@ test('buildScoreContract never rolls a retired/foreign id passed as acquired', (
   assert.ok(SCOREABLE_ITEM_IDS.has(withGhost as string));
 });
 
-test('buildScoreContract on an exhausted pool drops the payload id (abstract target is M6.5)', () => {
+// ---------------------------------------------------------------------------
+// P3.M6.5 — Exhausted pool draws an abstract credit payload
+// ---------------------------------------------------------------------------
+
+test('buildScoreContract on an exhausted pool drops the blueprint id and frames an abstract target', () => {
   const campaign = scoreReadyCampaign();
   const allAcquired = SCOREABLE_ITEMS.map(i => i.id);
   const contract = campaign.buildScoreContract(allAcquired);
+  // No blueprint id — a clean completion must not write the meta-store.
   assert.equal(contract.objective.params!.scoreItemId, undefined);
-  // Generic framing, no specific prototype named.
-  assert.ok(contract.objective.briefing.length > 0);
+  // Briefing is framed from exactly one abstract category.
+  const named = ABSTRACT_SCORE_TARGETS.filter(t => contract.objective.briefing.includes(t.label));
+  assert.equal(named.length, 1, 'briefing names exactly one abstract target');
+});
+
+test('abstract Score category selection is deterministic for a campaign', () => {
+  const campaign = scoreReadyCampaign();
+  const allAcquired = SCOREABLE_ITEMS.map(i => i.id);
+  const a = campaign.buildScoreContract(allAcquired).objective.briefing;
+  const b = campaign.buildScoreContract(allAcquired).objective.briefing;
+  assert.equal(a, b, 'same seed + exhausted pool → same abstract briefing');
+});
+
+test('different Score seeds can draw different abstract categories', () => {
+  // Sweep seeds; the picker must reach more than one category across the set.
+  const labels = new Set<string>();
+  for (let seed = 1; seed <= 40; seed++) {
+    const campaign = new Campaign({
+      seed,
+      rep: 65,
+      completedJobs: 9,
+      siteRoster: [
+        scoreSite({ seed: String(seed) }),
+        scoreSite({ id: 'case-1', tier: 'roster', scoreTarget: false, seed: `${seed}01` }),
+        scoreSite({ id: 'case-2', tier: 'roster', scoreTarget: false, seed: `${seed}02` }),
+      ],
+    });
+    const briefing = campaign.buildScoreContract(SCOREABLE_ITEMS.map(i => i.id)).objective.briefing;
+    for (const t of ABSTRACT_SCORE_TARGETS) {
+      if (briefing.includes(t.label)) labels.add(t.id);
+    }
+  }
+  assert.ok(labels.size > 1, 'abstract draw is not pinned to a single category');
+});
+
+test('a clean abstract Score settles the arc but writes no meta-store unlock', () => {
+  const campaign = scoreReadyCampaign();
+  const allAcquired = SCOREABLE_ITEMS.map(i => i.id);
+  const decker = campaign.crew.find(member => member.archetype === 'Decker')!;
+  const partner = campaign.crew.find(member => member.archetype !== 'Decker')!;
+  const beforeCredits = campaign.credits;
+  campaign.deployCrewMember(decker.id, campaign.buildScoreContract(allAcquired), partner.id).enterCombat();
+
+  campaign.onJobEnd({ outcome: OUTCOME.EXIT, completed: true });
+  // Arc reaches its climax exactly as a blueprint Score would.
+  assert.equal(campaign.endReason, 'score-complete');
+  assert.equal(campaign.state, CAMPAIGN_STATE.ENDED);
+  assert.equal(campaign.credits, beforeCredits + SCORE_CREDITS_REWARD);
+  // …but there is no blueprint to unlock.
+  assert.equal(campaign.scoreUnlockedItemId, null);
 });
 
 test('clean Score completion records the stolen blueprint for the meta-store', () => {

From cc43e0292f84038f290d0bad68caddae4e17f13f Mon Sep 17 00:00:00 2001
From: Rylee Corradini <rylee@facerix.com>
Date: Thu, 25 Jun 2026 17:26:49 -0700
Subject: [PATCH 55/55] chronicle! and we're done with phase 3!

---
 components/ChronicleArchive.ts              | 541 ++++++++++++++++++++
 components/KeyHelp.ts                       |   2 +-
 docs/phase-3-plan.md                        |   4 +-
 index.html                                  |   1 +
 index.ts                                    |   2 +
 src/DataStore.ts                            |  13 +-
 src/game/Campaign.ts                        | 273 +++++++++-
 src/game/chronicle.ts                       | 152 ++++++
 src/game/hub/ArchiveTerminal.ts             |  41 ++
 src/game/hub/SafeSpace.ts                   |  18 +-
 src/game/persistence.ts                     |  27 +
 src/input/mapKeyRows.ts                     |   3 +-
 src/shell/domTypes.ts                       |  12 +
 src/shell/shellRuntime.ts                   |  38 +-
 sw-core.js                                  |   3 +
 sw-dev.js                                   |   2 +-
 sw.js                                       |   2 +-
 tests/unit/game/Campaign.test.ts            |  58 +++
 tests/unit/game/hub/ArchiveTerminal.test.ts |  41 ++
 tests/unit/game/scoreFinal.test.ts          |   4 +-
 tests/unit/game/scoreableUnlocks.test.ts    |  10 +-
 21 files changed, 1217 insertions(+), 30 deletions(-)
 create mode 100644 components/ChronicleArchive.ts
 create mode 100644 src/game/chronicle.ts
 create mode 100644 src/game/hub/ArchiveTerminal.ts
 create mode 100644 tests/unit/game/hub/ArchiveTerminal.test.ts

diff --git a/components/ChronicleArchive.ts b/components/ChronicleArchive.ts
new file mode 100644
index 0000000..162db15
--- /dev/null
+++ b/components/ChronicleArchive.ts
@@ -0,0 +1,541 @@
+import { h } from '/src/domUtils.js';
+import type { CampaignChronicleEntry } from '/src/game/chronicle.js';
+import type { CampaignSummary } from '/src/game/campaignSummary.js';
+
+type ChronicleData = {
+  activeChronicle?: {
+    statusLines?: readonly string[];
+    entries: readonly CampaignChronicleEntry[];
+  } | null;
+  history: readonly CampaignSummary[];
+  acquisitions: { unlocked: number; total: number };
+};
+
+type ChronicleTab = 'chronicle' | 'history';
+
+type ChronicleMetaRefs = {
+  body: HTMLElement;
+  meta: HTMLElement;
+  panel: HTMLElement;
+  status: HTMLElement;
+  tabs: HTMLElement;
+};
+
+const CSS = `
+:host {
+  --chronicle-bg: rgba(7, 18, 16, 0.96);
+  --chronicle-border: var(--accent-color, #00d9a5);
+  --chronicle-text: #c5efdf;
+  --chronicle-dim: #6ae8c8;
+  --tab-active: rgba(0, 217, 165, 0.18);
+  --chronicle-accent: var(--accent-color, #00d9a5);
+  --chronicle-gold: #ffd166;
+  --chronicle-danger: #ff6a78;
+  --chronicle-shadow: 0 0 28px rgba(0, 217, 165, 0.18), 0 12px 36px rgba(0, 0, 0, 0.5);
+
+  display: none;
+  position: fixed;
+  inset: 0;
+  z-index: 65;
+  align-items: center;
+  justify-content: center;
+  background: rgba(0, 0, 0, 0.62);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  color: var(--chronicle-text);
+}
+
+:host([open]) {
+  display: flex;
+}
+
+.panel {
+  width: min(880px, 96vw);
+  max-height: min(760px, 92vh);
+  display: flex;
+  flex-direction: column;
+  background: linear-gradient(180deg, rgba(7, 18, 16, 0.98), rgba(2, 8, 7, 0.98));
+  border: 1px solid var(--chronicle-border);
+  border-radius: 6px;
+  box-shadow: var(--chronicle-shadow);
+  overflow: hidden;
+}
+
+.head {
+  padding: 1rem 1.25rem 0.9rem;
+  border-bottom: 1px dashed rgba(0, 217, 165, 0.3);
+}
+
+.title-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.title {
+  margin: 0;
+  color: var(--chronicle-accent);
+  letter-spacing: 0.18em;
+  font-size: 0.98rem;
+}
+
+.meta {
+  margin-top: 0.7rem;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.6rem;
+}
+
+.pill {
+  border: 1px solid rgba(106, 232, 200, 0.25);
+  border-radius: 999px;
+  padding: 0.25rem 0.6rem;
+  color: var(--chronicle-gold);
+  font-size: 0.82rem;
+  letter-spacing: 0.08em;
+}
+
+.status {
+  margin-top: 0.7rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.2rem;
+  color: var(--chronicle-dim);
+  font-size: 0.84rem;
+}
+
+.tabs {
+  display: flex;
+  gap: 0.45rem;
+  padding: 0.85rem 1.25rem 0;
+}
+
+.tab {
+  appearance: none;
+  -webkit-appearance: none;
+  background: transparent;
+  color: var(--chronicle-dim);
+  border: 1px solid rgba(106, 232, 200, 0.35);
+  border-radius: 4px;
+  min-height: 40px;
+  padding: 0.45rem 0.75rem;
+  font: inherit;
+  cursor: pointer;
+}
+
+button.tab[aria-selected='true'] {
+  background: var(--tab-active);
+  color: var(--chronicle-accent);
+  font-weight: 700;
+}
+
+.body {
+  flex: 1;
+  overflow: auto;
+  padding: 1rem 1.25rem 1.2rem;
+}
+
+.empty {
+  margin: 0;
+  color: var(--chronicle-dim);
+  font-style: italic;
+}
+
+.entry {
+  border: 1px solid rgba(106, 232, 200, 0.18);
+  border-radius: 6px;
+  padding: 0.85rem 0.9rem;
+  background: rgba(0, 0, 0, 0.18);
+}
+
+.entry + .entry {
+  margin-top: 0.75rem;
+}
+
+.entry-head {
+  display: flex;
+  justify-content: space-between;
+  gap: 1rem;
+  align-items: baseline;
+  margin-bottom: 0.4rem;
+}
+
+.entry-title {
+  color: var(--chronicle-accent);
+  font-size: 0.9rem;
+  letter-spacing: 0.12em;
+}
+
+.entry-tag {
+  color: var(--chronicle-gold);
+  font-size: 0.76rem;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+}
+
+.entry-summary {
+  margin: 0;
+  line-height: 1.5;
+}
+
+.detail-list {
+  margin: 0.55rem 0 0;
+  padding-left: 1rem;
+  color: var(--chronicle-dim);
+  font-size: 0.84rem;
+}
+
+.detail-list li {
+  margin: 0.12rem 0;
+}
+
+.history-grid {
+  display: grid;
+  gap: 0.75rem;
+}
+
+.history-result {
+  color: var(--chronicle-gold);
+  font-size: 0.78rem;
+  letter-spacing: 0.12em;
+}
+
+.history-result.loss {
+  color: var(--chronicle-danger);
+}
+
+.history-result.partial {
+  color: #ffb347;
+}
+
+@media (max-width: 720px) {
+  .panel {
+    width: 100vw;
+    max-height: 100vh;
+    border-radius: 0;
+  }
+
+  .entry-head,
+  .title-row {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+}
+`;
+
+const TAB_HISTORY = 'history';
+const TAB_CHRONICLE = 'chronicle';
+type TabId = typeof TAB_HISTORY | typeof TAB_CHRONICLE;
+
+const STAGE_LABELS = Object.freeze({
+  'act-1': 'Stage 1',
+  'act-2': 'Stage 2',
+  'act-3': 'Stage 3',
+  score: 'The Score',
+});
+
+const EMPTY_DATA: ChronicleData = Object.freeze({
+  activeChronicle: null,
+  history: Object.freeze([]),
+  acquisitions: Object.freeze({ unlocked: 0, total: 0 }),
+});
+
+class ChronicleArchive extends HTMLElement {
+  #ready = false;
+  #data: ChronicleData = EMPTY_DATA;
+  #activeTab: ChronicleTab = 'history';
+  #els: ChronicleMetaRefs | null = null;
+  #onBackdrop: ((evt: PointerEvent) => void) | null = null;
+  #onKeyDown: ((evt: KeyboardEvent) => void) | null = null;
+
+  connectedCallback() {
+    if (this.#ready) return;
+    this.tabIndex = -1;
+    const shadow = this.attachShadow({ mode: 'open' });
+    const style = h('style');
+    style.textContent = CSS;
+    shadow.appendChild(style);
+
+    const meta = h('div', { className: 'meta' });
+    const status = h('div', { className: 'status' });
+    const tabs = h('div', { className: 'tabs' });
+    const body = h('div', { className: 'body' });
+
+    const panel = h('section', { className: 'panel' }, [
+      h('div', { className: 'head' }, [
+        h('div', { className: 'title-row' }, [
+          h('h2', { className: 'title', textContent: '── LEDGER ──' }),
+        ]),
+        meta,
+        status,
+      ]),
+      tabs,
+      body,
+    ]);
+
+    shadow.appendChild(panel);
+    this.#els = { body, meta, panel, status, tabs };
+    this.#onKeyDown = evt => this.#handleKey(evt);
+    this.#onBackdrop = evt => this.#handleBackdrop(evt);
+    this.addEventListener('keydown', this.#onKeyDown);
+    this.addEventListener('click', this.#onBackdrop);
+    this.#ready = true;
+    this.#render();
+  }
+
+  disconnectedCallback() {
+    if (this.#onKeyDown) this.removeEventListener('keydown', this.#onKeyDown);
+    if (this.#onBackdrop) this.removeEventListener('click', this.#onBackdrop);
+  }
+
+  setData(data: ChronicleData) {
+    this.#data = normalizeChronicleData(data);
+    if (!this.#data.activeChronicle) {
+      this.#activeTab = 'history';
+    }
+    this.#render();
+  }
+
+  show() {
+    this.setAttribute('open', '');
+    queueMicrotask(() => this.focus());
+  }
+
+  hide() {
+    this.removeAttribute('open');
+  }
+
+  get isOpen() {
+    return this.hasAttribute('open');
+  }
+
+  #render() {
+    if (!this.#ready || !this.#els) return;
+    this.#els.meta.replaceChildren(...this.#buildMetaPills());
+    this.#els.status.replaceChildren(...this.#buildStatusLines());
+    this.#els.tabs.replaceChildren(...this.#buildTabs());
+    this.#els.body.replaceChildren(
+      this.#activeTab === 'chronicle' ? this.#buildChronicle() : this.#buildHistory()
+    );
+  }
+
+  #buildMetaPills(): HTMLElement[] {
+    const pills = [
+      h('span', {
+        className: 'pill',
+        textContent: `ACQUISITIONS: ${this.#data.acquisitions.unlocked} / ${this.#data.acquisitions.total}`,
+      }),
+      h('span', {
+        className: 'pill',
+        textContent: `ARCHIVE: ${this.#data.history.length} campaigns`,
+      }),
+    ];
+    if (this.#data.activeChronicle) {
+      pills.push(
+        h('span', {
+          className: 'pill',
+          textContent: `LIVE LOG: ${this.#data.activeChronicle.entries.length} entries`,
+        })
+      );
+    }
+    return pills;
+  }
+
+  #buildStatusLines(): HTMLElement[] {
+    return (this.#data.activeChronicle?.statusLines ?? []).map(line =>
+      h('div', { textContent: line })
+    );
+  }
+
+  #buildTabs(): HTMLElement[] {
+    const tabs: Array<{ id: ChronicleTab; label: string }> = [
+      { id: 'chronicle', label: 'Active Chronicle' },
+      { id: 'history', label: 'History' },
+    ];
+    return tabs.map(tab => {
+      const button = h('button', {
+        type: 'button',
+        className: 'tab',
+        textContent: tab.label,
+      });
+      button.setAttribute('aria-selected', String(this.#activeTab === tab.id));
+      button.setAttribute('role', 'tab');
+      button.addEventListener('click', () => {
+        this.#activeTab = tab.id;
+        this.#render();
+      });
+      return button;
+    });
+  }
+
+  #buildChronicle(): HTMLElement {
+    const chronicle = this.#data.activeChronicle;
+    if (!chronicle || chronicle.entries.length === 0) {
+      return h('p', {
+        className: 'empty',
+        textContent:
+          'No campaign entries yet. The log will fill as the crew takes jobs and the arc unfolds.',
+      });
+    }
+    return h(
+      'div',
+      {},
+      chronicle.entries.map(entry =>
+        h('article', { className: 'entry' }, [
+          h('div', { className: 'entry-head' }, [
+            h('div', { className: 'entry-title', textContent: entry.title }),
+            h('div', {
+              className: 'entry-tag',
+              textContent: `${STAGE_LABELS[entry.stage]} • ${entry.kind}`,
+            }),
+          ]),
+          h('p', { className: 'entry-summary', textContent: entry.summary }),
+          h(
+            'ul',
+            { className: 'detail-list' },
+            entry.detailLines.map(line => h('li', { textContent: line }))
+          ),
+        ])
+      )
+    );
+  }
+
+  #buildHistory(): HTMLElement {
+    if (this.#data.history.length === 0) {
+      return h('p', {
+        className: 'empty',
+        textContent: 'No archived campaigns yet. Finish a campaign and it will appear here.',
+      });
+    }
+    return h(
+      'div',
+      { className: 'history-grid' },
+      this.#data.history.map(summary => {
+        const resultClass =
+          summary.result === 'loss'
+            ? 'history-result loss'
+            : summary.result === 'partial'
+              ? 'history-result partial'
+              : 'history-result';
+        const rewardLine = summary.scoreReward
+          ? `Blueprint stolen: ${summary.scoreReward.label}`
+          : summary.result === 'win'
+            ? 'Blueprint stolen: abstract credit cache'
+            : `End reason: ${summary.endReason}`;
+        return h('article', { className: 'entry' }, [
+          h('div', { className: 'entry-head' }, [
+            h('div', {
+              className: 'entry-title',
+              textContent: `${summary.completedJobs} jobs • ${summary.credits} Cr • REP ${summary.rep}`,
+            }),
+            h('div', {
+              className: resultClass,
+              textContent: summary.result.toUpperCase(),
+            }),
+          ]),
+          h('p', {
+            className: 'entry-summary',
+            textContent: `${formatDate(summary.completedAt)} — ${rewardLine}.`,
+          }),
+          h('ul', { className: 'detail-list' }, [
+            h('li', { textContent: `Campaign seed ${summary.seed}` }),
+            h('li', {
+              textContent: `Crew at end: ${summary.crewRoster
+                .map(
+                  member =>
+                    `${member.callsign} (${member.archetype}${member.flatlined ? ', flatlined' : ''})`
+                )
+                .join(', ')}`,
+            }),
+          ]),
+        ]);
+      })
+    );
+  }
+
+  #handleBackdrop(evt: PointerEvent) {
+    if (!this.isOpen || !this.#els) return;
+    if (evt.composedPath().includes(this.#els.panel)) return;
+    this.dispatchEvent(new CustomEvent('dismiss', { bubbles: true, composed: true }));
+  }
+
+  #switchTab(tab: TabId) {
+    if (tab === this.#activeTab) return;
+    this.#activeTab = tab;
+    this.#render();
+  }
+
+  #handleKey(evt: KeyboardEvent) {
+    if (!this.isOpen) return;
+    evt.stopPropagation();
+
+    switch (evt.key) {
+      case 'Escape':
+        evt.preventDefault();
+        this.dispatchEvent(new CustomEvent('dismiss', { bubbles: true, composed: true }));
+        break;
+
+      case 'ArrowLeft':
+      case 'a':
+        evt.preventDefault();
+        this.#switchTab(TAB_CHRONICLE);
+        break;
+
+      case 'ArrowRight':
+      case 'd':
+        evt.preventDefault();
+        this.#switchTab(TAB_HISTORY);
+        break;
+
+      case 'Tab':
+        evt.preventDefault();
+        this.#switchTab(this.#activeTab === TAB_HISTORY ? TAB_CHRONICLE : TAB_HISTORY);
+        return;
+    }
+  }
+}
+
+function normalizeChronicleData(data: ChronicleData): ChronicleData {
+  if (!data || typeof data !== 'object') {
+    throw new TypeError('<chronicle-archive>.setData requires a data object');
+  }
+  if (!Array.isArray(data.history)) {
+    throw new TypeError('<chronicle-archive>.setData requires history[]');
+  }
+  if (
+    !data.acquisitions ||
+    !Number.isInteger(data.acquisitions.unlocked) ||
+    !Number.isInteger(data.acquisitions.total)
+  ) {
+    throw new TypeError('<chronicle-archive>.setData requires acquisitions counts');
+  }
+  if (data.activeChronicle && !Array.isArray(data.activeChronicle.entries)) {
+    throw new TypeError('<chronicle-archive>.setData activeChronicle.entries must be an array');
+  }
+  return {
+    activeChronicle: data.activeChronicle
+      ? {
+          entries: [...data.activeChronicle.entries],
+          statusLines: [...(data.activeChronicle.statusLines ?? [])],
+        }
+      : null,
+    history: [...data.history],
+    acquisitions: { ...data.acquisitions },
+  };
+}
+
+function formatDate(value: string): string {
+  const parsed = new Date(value);
+  if (!Number.isFinite(parsed.getTime())) return value;
+  return parsed.toLocaleString('en-US', {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+  });
+}
+
+customElements.define('chronicle-archive', ChronicleArchive);
+
+export default ChronicleArchive;
diff --git a/components/KeyHelp.ts b/components/KeyHelp.ts
index 91a3225..58e3b9f 100644
--- a/components/KeyHelp.ts
+++ b/components/KeyHelp.ts
@@ -486,7 +486,7 @@ class KeyHelp extends HTMLElement {
 
     const hubExtra = h('p', {
       textContent:
-        'In the hub, walk up to the Curator or the crew terminal (‡ glyph) and use Interact to hear rumors, pick contracts, or open the crew roster.',
+        'In the hub, walk up to the Curator, the crew terminal (‡ glyph), or the archive ledger (L glyph) and use Interact to hear rumors, open the crew roster, or review the Chronicle and campaign archive.',
     });
 
     const combatExtra = h('p', {
diff --git a/docs/phase-3-plan.md b/docs/phase-3-plan.md
index d96939b..3989d3c 100644
--- a/docs/phase-3-plan.md
+++ b/docs/phase-3-plan.md
@@ -620,7 +620,7 @@ unlocked scoreable). `<finn-shop>` renders only the catalog handed to
 
 ---
 
-### P3.M7 — Chronicle (campaign narrative memory) 🟡
+### P3.M7 — Chronicle (campaign narrative memory) ✅
 
 **Depends on:** P3.M1 (arc structure provides the narrative beats to chronicle). Can begin data collection earlier if arc state is available.
 
@@ -643,7 +643,7 @@ unlocked scoreable). `<finn-shop>` renders only the catalog handed to
 - Hub can open chronicle (active campaign) and history (past campaigns) without errors.
 - Tests for append + round-trip + cap/trim policy if the list is bounded.
 
-**P3.M7 implementation note:** The end-summary foundation is shipped. A validated `CampaignSummary` is built only after campaign settlement reaches `ENDED`, so the final completed-job increment, Credits (including the Score payoff), Rep, seed, and roster state are captured from the canonical final campaign. Salvage remains a campaign resource rather than a summary measure of value. `DataStore` keeps summaries newest-first, preserves the original record on duplicate archival, and trims history to 50 campaigns. Live completion and restored ended saves share the same idempotent archival path. `<game-over>` is now the single terminal campaign overlay with success and failure modes; terminal outcomes bypass the recoverable job-level `<crash-dump>` debrief. Active per-job chronicle entries, Terminal presentation, and history browsing remain follow-up work within P3.M6.
+**P3.M7 implementation note:** Shipped. The Chronicle now persists active-campaign entries in the campaign save, recording crew assembly, Decker recruitment, arc transitions, and job outcomes with stage-aware copy. The Hub exposes a dedicated `LOG` entry point that opens a Chronicle/archive modal rather than reusing the crew terminal. That surface shows the live campaign log, current arc status lines, archived `CampaignSummary` history, and an `ACQUISITIONS: N / M` meta-progression counter sourced from `unlockedScoreableItems`. The end-summary foundation remains the archival backend: a validated `CampaignSummary` is still built only after campaign settlement reaches `ENDED`, stored newest-first, deduplicated by campaign id, and trimmed to 50 history rows. Chronicle state round-trips through snapshot restore, including pending run context so job entries still settle correctly after reload.
 
 ---
 
diff --git a/index.html b/index.html
index 83a9de7..e57ea0d 100644
--- a/index.html
+++ b/index.html
@@ -86,6 +86,7 @@ <h3>Log</h3>
     <finn-shop id="finn-shop"></finn-shop>
     <clinic-modal id="clinic-modal"></clinic-modal>
     <item-inventory id="item-inventory"></item-inventory>
+    <chronicle-archive id="chronicle-archive"></chronicle-archive>
     <key-help id="key-help"></key-help>
     <touch-pad id="touch-pad"></touch-pad>
     <update-notification></update-notification>
diff --git a/index.ts b/index.ts
index 19143e9..8eda0fc 100644
--- a/index.ts
+++ b/index.ts
@@ -21,6 +21,7 @@ import '/components/CrewRoster.js';
 import '/components/FinnShop.js';
 import '/components/ClinicModal.js';
 import '/components/ItemInventory.js';
+import '/components/ChronicleArchive.js';
 import KeyHelp from '/components/KeyHelp.js';
 
 const allComponentsReady = Promise.all([
@@ -40,6 +41,7 @@ const allComponentsReady = Promise.all([
   customElements.whenDefined('finn-shop'),
   customElements.whenDefined('clinic-modal'),
   customElements.whenDefined('item-inventory'),
+  customElements.whenDefined('chronicle-archive'),
   customElements.whenDefined('key-help'),
 ]);
 
diff --git a/src/DataStore.ts b/src/DataStore.ts
index 63db58d..c750a71 100644
--- a/src/DataStore.ts
+++ b/src/DataStore.ts
@@ -6,10 +6,7 @@ import {
   normalizeCampaignHistory,
   type CampaignSummary,
 } from './game/campaignSummary.js';
-import {
-  archiveScoreableItem,
-  normalizeUnlockedScoreableItems,
-} from './game/scoreableUnlocks.js';
+import { archiveScoreableItem, normalizeUnlockedScoreableItems } from './game/scoreableUnlocks.js';
 
 const STORAGE_KEY = 'kp:data';
 let instance: DataStore | null = null;
@@ -80,7 +77,13 @@ class DataStore extends EventTarget {
       } catch (storageError) {
         console.warn('[DataStore] Failed to reset stored data.', storageError);
       }
-      return { prefs: {}, runs: [], campaign: null, campaignHistory: [], unlockedScoreableItems: [] };
+      return {
+        prefs: {},
+        runs: [],
+        campaign: null,
+        campaignHistory: [],
+        unlockedScoreableItems: [],
+      };
     }
     // The meta-progression store crashes loudly on structural corruption — a
     // silent reset would erase blueprints the meta-crew earned across campaigns
diff --git a/src/game/Campaign.ts b/src/game/Campaign.ts
index 80c61ec..1eaa29b 100644
--- a/src/game/Campaign.ts
+++ b/src/game/Campaign.ts
@@ -26,6 +26,7 @@ import { OBJECTIVES } from './hub/Curator.js';
 import { Terminal } from './hub/Terminal.js';
 import { Finn } from './hub/Finn.js';
 import { Clinic } from './hub/Clinic.js';
+import { ArchiveTerminal } from './hub/ArchiveTerminal.js';
 import {
   applyFirstHubReveal,
   normalizeHubReveals,
@@ -51,6 +52,12 @@ import {
   normalizeLocationSite,
 } from './locations.js';
 import { resolveMapDimensions } from './procgen/mapDimensions.js';
+import {
+  normalizeCampaignChronicle,
+  normalizePendingChronicleRun,
+  type CampaignChronicleEntry,
+  type PendingChronicleRun,
+} from './chronicle.js';
 import type { Contract } from './hub/Curator.js';
 import type { Crew } from './Crew.js';
 import type {
@@ -127,13 +134,12 @@ export const ABSTRACT_SCORE_TARGETS: readonly AbstractScoreTarget[] = Object.fre
     id: 'liquid-reserves',
     label: 'liquid reserves',
     flavor:
-      "Their R&D vaults are picked clean — nothing left worth reverse-engineering. So this run, you go for the money.",
+      'Their R&D vaults are picked clean — nothing left worth reverse-engineering. So this run, you go for the money.',
   },
   {
     id: 'bearer-bonds',
     label: 'bearer-bond cache',
-    flavor:
-      "No prototypes left to lift; this time it's a strongbox of untraceable bearer bonds.",
+    flavor: "No prototypes left to lift; this time it's a strongbox of untraceable bearer bonds.",
   },
   {
     id: 'slush-fund',
@@ -229,6 +235,8 @@ export type CampaignOptions = {
   clockJobsTaken?: unknown;
   keyItems?: unknown;
   siteRoster?: unknown;
+  chronicle?: unknown;
+  pendingChronicleRun?: unknown;
   onPersist?: unknown;
   onResult?: unknown;
 };
@@ -329,6 +337,7 @@ export class Campaign {
   curator: Curator | null;
   finn: Finn | null;
   terminal: Terminal | null;
+  archiveTerminal: ArchiveTerminal | null;
   clinic: Clinic | null;
   healedThisVisit: Set<string>;
   hubReveals: HubReveals;
@@ -339,6 +348,10 @@ export class Campaign {
   keyItems: KeyItem[];
   /** Remembered combat locations / site roster (P2.5.M7.2), max `SITE_ROSTER_CAP`. */
   siteRoster: LocationSite[];
+  /** P3.M7: persisted campaign narrative memory, newest entry appended in order. */
+  chronicle: CampaignChronicleEntry[];
+  /** Mid-run baseline used to write the final chronicle entry on settlement. */
+  pendingChronicleRun: PendingChronicleRun | null;
   /** Set by the latest `enterHub` when a reveal message fired; shell reads and clears. */
   lastHubReveal: HubRevealMessage | null;
   exitTile: GridPoint | null;
@@ -357,6 +370,8 @@ export class Campaign {
     clockJobsTaken = 0,
     keyItems,
     siteRoster,
+    chronicle,
+    pendingChronicleRun,
     onPersist,
     onResult,
   }: CampaignOptions = {}) {
@@ -419,6 +434,8 @@ export class Campaign {
     this.clockJobsTaken = (clockJobsTaken as number) ?? 0;
     this.keyItems = normalizeKeyItems(keyItems);
     this.siteRoster = normalizeSiteRoster(siteRoster);
+    this.chronicle = normalizeCampaignChronicle(chronicle);
+    this.pendingChronicleRun = normalizePendingChronicleRun(pendingChronicleRun);
     this.state = CAMPAIGN_STATE.HUB;
     this.activeRun = null;
     this.deployedMemberId = null;
@@ -438,6 +455,7 @@ export class Campaign {
     this.curator = null;
     this.finn = null;
     this.terminal = null;
+    this.archiveTerminal = null;
     this.clinic = null;
     this.healedThisVisit = new Set();
     this.lastHubReveal = null;
@@ -526,6 +544,11 @@ export class Campaign {
       x: hub.terminalSpawn.x,
       y: hub.terminalSpawn.y,
     });
+    this.archiveTerminal = new ArchiveTerminal({
+      id: 'archive-terminal',
+      x: hub.archiveTerminalSpawn.x,
+      y: hub.archiveTerminalSpawn.y,
+    });
     this.lastHubReveal = applyFirstHubReveal(this);
     if (shouldSpawnFinn(this.hubReveals)) {
       this.finn = new Finn({
@@ -548,6 +571,7 @@ export class Campaign {
     this.world.addEntity(this.player);
     this.world.addEntity(this.curator);
     this.world.addEntity(this.terminal);
+    this.world.addEntity(this.archiveTerminal);
     if (this.finn) this.world.addEntity(this.finn);
     if (this.clinic) this.world.addEntity(this.clinic);
     this.queue = new TurnQueue([FACTION.PLAYER, FACTION.CORP]);
@@ -634,6 +658,7 @@ export class Campaign {
       this.clockJobsTaken += 1;
     }
     const deployedContract = this.#contractWithRememberedDimensions(contract);
+    this.pendingChronicleRun = this.#buildPendingChronicleRun(deployedContract);
     this.#tearDownHubWorld();
     this.deployedMemberId = member.id;
     this.deployedPartnerId = partner?.id ?? null;
@@ -711,6 +736,7 @@ export class Campaign {
       !completed;
     const failedScoreRun =
       activeContract !== null && isScoreContract(activeContract) && outcome === OUTCOME.DEATH;
+    const chroniclePending = this.pendingChronicleRun;
 
     // P3.M4.4: a meat partner that flatlined on the field is gone for good —
     // independent of the Decker's outcome. The Decker may have extracted clean
@@ -753,6 +779,15 @@ export class Campaign {
     this.activeRun = null;
     this.deployedMemberId = null;
     this.deployedPartnerId = null;
+    this.pendingChronicleRun = null;
+
+    if (chroniclePending) {
+      this.#appendChronicleJobEntry(chroniclePending, {
+        outcome,
+        completed,
+        activeContract,
+      });
+    }
 
     if (failedScoreRun) {
       this.state = CAMPAIGN_STATE.ENDED;
@@ -1046,6 +1081,14 @@ export class Campaign {
     this.rewardRecruitIds.delete(recruit.id);
     this.crew.push(recruit);
     this.recruitedThisVisit = true;
+    this.#appendChronicleMilestone(
+      this.arc.arcStage,
+      `RECRUITED — ${recruit.callsign ?? recruit.id}`,
+      `${recruit.callsign ?? recruit.id} joined the crew as ${recruit.archetype}.`,
+      [
+        `Crew size ${this.crew.filter(member => !member.flatlined).length} living / ${this.crew.length} total`,
+      ]
+    );
     this.#persist();
   }
 
@@ -1096,6 +1139,14 @@ export class Campaign {
     }
     this.crew.push(...selected);
     this.initialCandidates = [];
+    this.#appendChronicleMilestone(
+      'act-1',
+      'CREW ASSEMBLED',
+      `The first operators are in place: ${selected
+        .map(member => member.callsign ?? member.id)
+        .join(', ')}.`,
+      [`Starter crew ${selected.length} operators`, 'Street-level contracts are now live.']
+    );
   }
 
   /**
@@ -1416,6 +1467,186 @@ export class Campaign {
     return this.crew.find(member => member.id === memberId) ?? null;
   }
 
+  #appendChronicleMilestone(
+    stage: CampaignArcStage,
+    title: string,
+    summary: string,
+    detailLines: string[]
+  ): void {
+    this.chronicle.push({
+      id: `chronicle-${this.chronicle.length}`,
+      sequence: this.chronicle.length,
+      kind: 'milestone',
+      stage,
+      title,
+      summary,
+      detailLines: [...detailLines],
+    });
+  }
+
+  #buildPendingChronicleRun(contract: Contract): PendingChronicleRun {
+    const scoreTarget = this.#scoreTargetSiteOrNull();
+    const scoreTargetName = scoreTarget ? this.#scoreTargetDisplayName(scoreTarget) : null;
+    const principalLabel = contract.context.principal?.label?.trim() || null;
+    const isScore = contract.context.recipeId === 'score-final';
+    const isCasing =
+      !isScore &&
+      !!scoreTarget?.principal?.id &&
+      contract.context.principal?.id === scoreTarget.principal.id &&
+      contract.context.locationSiteId !== scoreTarget.id;
+    return {
+      sequence: this.chronicle.length,
+      stage: this.arc.arcStage,
+      contractLabel: contract.label,
+      objectiveTitle: contract.objective.title,
+      scoreTargetName,
+      principalLabel,
+      isScore,
+      isCasing,
+      repBefore: this.rep,
+      creditsBefore: this.credits,
+      completedJobsBefore: this.completedJobs,
+      flatlinedCrewIdsBefore: this.crew.filter(member => member.flatlined).map(member => member.id),
+    };
+  }
+
+  #appendChronicleJobEntry(
+    pending: PendingChronicleRun,
+    opts: { outcome: Outcome; completed: boolean; activeContract: Contract | null }
+  ): void {
+    const crewLosses = this.crew
+      .filter(member => member.flatlined && !pending.flatlinedCrewIdsBefore.includes(member.id))
+      .map(member => member.callsign ?? member.id);
+    const repDelta = this.rep - pending.repBefore;
+    const creditsDelta = this.credits - pending.creditsBefore;
+    const completedJobsDelta = this.completedJobs - pending.completedJobsBefore;
+    const title = this.#chronicleJobTitle(pending, opts);
+    const summary = this.#chronicleJobSummary(pending, opts, crewLosses);
+    const detailLines = [
+      `Objective: ${pending.objectiveTitle}`,
+      `Outcome: ${this.#chronicleOutcomeLabel(pending, opts)}`,
+      `Rep ${repDelta >= 0 ? '+' : ''}${repDelta} | Credits ${creditsDelta >= 0 ? '+' : ''}${creditsDelta}`,
+      `Completed jobs ${pending.completedJobsBefore} -> ${this.completedJobs}`,
+    ];
+    if (crewLosses.length > 0) {
+      detailLines.push(`Losses: ${crewLosses.join(', ')}`);
+    }
+    const rewardLine = this.#scoreRewardDetail(opts.activeContract);
+    if (rewardLine) {
+      detailLines.push(rewardLine);
+    }
+    if (pending.isCasing && pending.principalLabel) {
+      detailLines.push(`Casing principal: ${pending.principalLabel}`);
+    }
+    if (pending.scoreTargetName) {
+      detailLines.push(`Score target: ${pending.scoreTargetName}`);
+    }
+    if (completedJobsDelta < 0) {
+      throw new Error('Campaign chronicle: completedJobs regressed during settlement');
+    }
+    this.chronicle.push({
+      id: `chronicle-${pending.sequence}`,
+      sequence: pending.sequence,
+      kind: 'job',
+      stage: pending.stage,
+      title,
+      summary,
+      detailLines,
+    });
+  }
+
+  #chronicleJobTitle(
+    pending: PendingChronicleRun,
+    opts: { outcome: Outcome; completed: boolean; activeContract: Contract | null }
+  ): string {
+    if (pending.isScore) {
+      if (opts.outcome === OUTCOME.DEATH) return 'THE SCORE — FLATLINED';
+      if (opts.completed) return 'THE SCORE — COMPLETE';
+      return 'THE SCORE — PARTIAL';
+    }
+    if (pending.isCasing && pending.principalLabel) {
+      return `CASING — ${pending.principalLabel.toUpperCase()}`;
+    }
+    if (pending.stage === 'act-1') return 'STREET JOB';
+    if (pending.stage === 'act-3') return 'FINAL PREP';
+    return 'RUN LOGGED';
+  }
+
+  #chronicleJobSummary(
+    pending: PendingChronicleRun,
+    opts: { outcome: Outcome; completed: boolean; activeContract: Contract | null },
+    crewLosses: string[]
+  ): string {
+    if (pending.isScore) {
+      if (opts.outcome === OUTCOME.DEATH) {
+        return `The push on ${pending.scoreTargetName ?? pending.contractLabel} flatlined the Decker and ended the campaign.`;
+      }
+      if (opts.completed) {
+        const reward = this.#scoreRewardSummary(opts.activeContract);
+        return reward
+          ? `The crew cracked ${pending.scoreTargetName ?? pending.contractLabel} and stole ${reward}.`
+          : `The crew cracked ${pending.scoreTargetName ?? pending.contractLabel} and walked with the payday.`;
+      }
+      return `The crew reached ${pending.scoreTargetName ?? pending.contractLabel} but extracted without the payload.`;
+    }
+    if (opts.outcome === OUTCOME.DEATH) {
+      return `${pending.contractLabel} went bad and the deployed operator never came home.`;
+    }
+    if (!opts.completed) {
+      return `${pending.contractLabel} was aborted before the objective was secured.`;
+    }
+    if (pending.stage === 'act-1') {
+      return `${pending.contractLabel} kept the crew fed and moving through the street-level grind.`;
+    }
+    if (pending.isCasing) {
+      return `${pending.contractLabel} gave the crew another read on ${pending.principalLabel ?? 'the target org'} before the big push.`;
+    }
+    if (pending.stage === 'act-3') {
+      return `${pending.contractLabel} tightened the final prep window before THE SCORE.`;
+    }
+    if (crewLosses.length > 0) {
+      return `${pending.contractLabel} was won, but the crew paid for it in blood.`;
+    }
+    return `${pending.contractLabel} landed clean.`;
+  }
+
+  #chronicleOutcomeLabel(
+    pending: PendingChronicleRun,
+    opts: { outcome: Outcome; completed: boolean }
+  ): string {
+    if (pending.isScore) {
+      if (opts.outcome === OUTCOME.DEATH) return 'campaign loss';
+      return opts.completed ? 'score complete' : 'score partial';
+    }
+    if (opts.outcome === OUTCOME.DEATH) return 'operator flatlined';
+    return opts.completed ? 'objective complete' : 'objective aborted';
+  }
+
+  #scoreRewardSummary(contract: Contract | null): string | null {
+    const payloadId = scorePayloadItemId(contract);
+    if (payloadId) {
+      const payload = SCOREABLE_ITEMS.find(item => item.id === payloadId);
+      if (payload) return payload.label;
+    }
+    return null;
+  }
+
+  #scoreRewardDetail(contract: Contract | null): string | null {
+    const reward = this.#scoreRewardSummary(contract);
+    if (reward) return `Acquired blueprint: ${reward}`;
+    if (contract?.context.recipeId === 'score-final' && this.arc.scoreCompleted) {
+      return 'Acquired payout: abstract credit cache';
+    }
+    return null;
+  }
+
+  #scoreTargetDisplayName(site: LocationSite): string {
+    const principal = site.principal?.label?.trim() ?? '';
+    const place = site.site?.label?.trim() ?? '';
+    if (principal && place) return `${principal} ${place}`;
+    return principal || place || site.label.replace(/^\/\//, '').replace(/\/\/$/, '').trim();
+  }
+
   #advanceArcTransitions(): void {
     if (this.crew.some(member => member.archetype === 'Decker')) {
       this.arc.deckerRecruited = true;
@@ -1434,13 +1665,48 @@ export class Campaign {
       this.#ensureScoreTargetDesignated();
     }
 
+    if (
+      this.arc.arcStage === 'act-2' &&
+      !this.chronicle.some(entry => entry.title === 'STAGE 2 — SCORE REVEALED')
+    ) {
+      const target = this.#scoreTargetSiteOrNull();
+      const decker = this.crew.find(member => member.archetype === 'Decker');
+      this.#appendChronicleMilestone(
+        'act-2',
+        'STAGE 2 — SCORE REVEALED',
+        `The Curator named ${target ? this.#scoreTargetDisplayName(target) : 'the Score'} and assigned ${decker?.callsign ?? 'a Decker'} to open it.`,
+        [
+          `Score target: ${target ? this.#scoreTargetDisplayName(target) : 'unknown'}`,
+          `Decker assigned: ${decker?.callsign ?? 'unknown'}`,
+        ]
+      );
+    }
+
     if (this.arc.arcStage === 'act-2' && this.#qualifiesForAct3()) {
       this.arc.arcStage = 'act-3';
       this.#ensureAct3ScoreWindow();
+      this.#appendChronicleMilestone(
+        'act-3',
+        'STAGE 3 — FINAL PREP',
+        'The crew has enough casing, enough survivors, and a narrow window to attempt THE SCORE.',
+        [
+          `Living crew: ${this.crew.filter(member => !member.flatlined).length}`,
+          `Clock budget remaining: ${this.scoreDeadlineJobsRemaining}`,
+        ]
+      );
     }
 
     if (this.arc.scoreRevealed && this.clockJobsTaken >= CLOCK_ACT2_GRACE_JOBS) {
+      const wasStarted = this.arc.clockStarted;
       this.arc.clockStarted = true;
+      if (!wasStarted) {
+        this.#appendChronicleMilestone(
+          this.arc.arcStage,
+          'CLOCK IS LIVE',
+          'The operational window is now burning down. Every deploy adds heat.',
+          [`Clock heat ${this.clockHeat}`, `Jobs left ${this.scoreDeadlineJobsRemaining}`]
+        );
+      }
     }
   }
 
@@ -1611,6 +1877,7 @@ export class Campaign {
     this.curator = null;
     this.finn = null;
     this.terminal = null;
+    this.archiveTerminal = null;
     this.clinic = null;
     this.exitTile = null;
   }
diff --git a/src/game/chronicle.ts b/src/game/chronicle.ts
new file mode 100644
index 0000000..b0b96e7
--- /dev/null
+++ b/src/game/chronicle.ts
@@ -0,0 +1,152 @@
+import type { CampaignArcStage } from '../types.js';
+
+export type CampaignChronicleEntryKind = 'milestone' | 'job';
+
+export type CampaignChronicleEntry = {
+  id: string;
+  sequence: number;
+  kind: CampaignChronicleEntryKind;
+  stage: CampaignArcStage;
+  title: string;
+  summary: string;
+  detailLines: string[];
+};
+
+export type PendingChronicleRun = {
+  sequence: number;
+  stage: CampaignArcStage;
+  contractLabel: string;
+  objectiveTitle: string;
+  scoreTargetName: string | null;
+  principalLabel: string | null;
+  isScore: boolean;
+  isCasing: boolean;
+  repBefore: number;
+  creditsBefore: number;
+  completedJobsBefore: number;
+  flatlinedCrewIdsBefore: string[];
+};
+
+const ARC_STAGES: readonly CampaignArcStage[] = ['act-1', 'act-2', 'act-3', 'score'];
+const ENTRY_KINDS: readonly CampaignChronicleEntryKind[] = ['milestone', 'job'];
+
+export function cloneChronicleEntry(entry: CampaignChronicleEntry): CampaignChronicleEntry {
+  return {
+    ...entry,
+    detailLines: [...entry.detailLines],
+  };
+}
+
+export function normalizeCampaignChronicle(value: unknown): CampaignChronicleEntry[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) {
+    throw new TypeError('Campaign.chronicle must be an array');
+  }
+  return value.map((entry, index) => validateChronicleEntry(entry, index));
+}
+
+export function validateChronicleEntry(
+  value: unknown,
+  index = 0,
+  context = 'Campaign.chronicle'
+): CampaignChronicleEntry {
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${context}[${index}] must be a plain object`);
+  }
+  const entry = value as Record<string, unknown>;
+  const id = requireNonEmptyString(entry.id, `${context}[${index}].id`);
+  const sequence = requireNonNegativeInteger(entry.sequence, `${context}[${index}].sequence`);
+  const kind = requireEntryKind(entry.kind, `${context}[${index}].kind`);
+  const stage = requireArcStage(entry.stage, `${context}[${index}].stage`);
+  const title = requireNonEmptyString(entry.title, `${context}[${index}].title`);
+  const summary = requireNonEmptyString(entry.summary, `${context}[${index}].summary`);
+  if (!Array.isArray(entry.detailLines)) {
+    throw new TypeError(`${context}[${index}].detailLines must be an array`);
+  }
+  const detailLines = entry.detailLines.map((line, lineIndex) =>
+    requireNonEmptyString(line, `${context}[${index}].detailLines[${lineIndex}]`)
+  );
+  return { id, sequence, kind, stage, title, summary, detailLines };
+}
+
+export function normalizePendingChronicleRun(
+  value: unknown,
+  context = 'Campaign.pendingChronicleRun'
+): PendingChronicleRun | null {
+  if (value === undefined || value === null) return null;
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${context} must be a plain object when supplied`);
+  }
+  const pending = value as Record<string, unknown>;
+  const scoreTargetName = requireNullableString(
+    pending.scoreTargetName,
+    `${context}.scoreTargetName`
+  );
+  const principalLabel = requireNullableString(pending.principalLabel, `${context}.principalLabel`);
+  if (!Array.isArray(pending.flatlinedCrewIdsBefore)) {
+    throw new TypeError(`${context}.flatlinedCrewIdsBefore must be an array`);
+  }
+  return {
+    sequence: requireNonNegativeInteger(pending.sequence, `${context}.sequence`),
+    stage: requireArcStage(pending.stage, `${context}.stage`),
+    contractLabel: requireNonEmptyString(pending.contractLabel, `${context}.contractLabel`),
+    objectiveTitle: requireNonEmptyString(pending.objectiveTitle, `${context}.objectiveTitle`),
+    scoreTargetName,
+    principalLabel,
+    isScore: requireBoolean(pending.isScore, `${context}.isScore`),
+    isCasing: requireBoolean(pending.isCasing, `${context}.isCasing`),
+    repBefore: requireNonNegativeInteger(pending.repBefore, `${context}.repBefore`),
+    creditsBefore: requireNonNegativeInteger(pending.creditsBefore, `${context}.creditsBefore`),
+    completedJobsBefore: requireNonNegativeInteger(
+      pending.completedJobsBefore,
+      `${context}.completedJobsBefore`
+    ),
+    flatlinedCrewIdsBefore: pending.flatlinedCrewIdsBefore.map((id, index) =>
+      requireNonEmptyString(id, `${context}.flatlinedCrewIdsBefore[${index}]`)
+    ),
+  };
+}
+
+function requireArcStage(value: unknown, context: string): CampaignArcStage {
+  if (typeof value !== 'string' || !ARC_STAGES.includes(value as CampaignArcStage)) {
+    throw new Error(`${context} "${String(value)}" is not known`);
+  }
+  return value as CampaignArcStage;
+}
+
+function requireEntryKind(value: unknown, context: string): CampaignChronicleEntryKind {
+  if (typeof value !== 'string' || !ENTRY_KINDS.includes(value as CampaignChronicleEntryKind)) {
+    throw new Error(`${context} "${String(value)}" is not known`);
+  }
+  return value as CampaignChronicleEntryKind;
+}
+
+function requireNonEmptyString(value: unknown, context: string): string {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new TypeError(`${context} must be a non-empty string`);
+  }
+  return value;
+}
+
+function requireNullableString(value: unknown, context: string): string | null {
+  if (value === null || value === undefined) return null;
+  return requireNonEmptyString(value, context);
+}
+
+function requireNonNegativeInteger(value: unknown, context: string): number {
+  if (!Number.isInteger(value) || (value as number) < 0) {
+    throw new TypeError(`${context} must be a non-negative integer`);
+  }
+  return value as number;
+}
+
+function requireBoolean(value: unknown, context: string): boolean {
+  if (typeof value !== 'boolean') {
+    throw new TypeError(`${context} must be boolean`);
+  }
+  return value;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
diff --git a/src/game/hub/ArchiveTerminal.ts b/src/game/hub/ArchiveTerminal.ts
new file mode 100644
index 0000000..aab2faf
--- /dev/null
+++ b/src/game/hub/ArchiveTerminal.ts
@@ -0,0 +1,41 @@
+/**
+ * Archive terminal — the Hub's diegetic Chronicle access point.
+ *
+ * Fictionally this is the safe house ledger where the crew reviews the live
+ * Chronicle and prior campaign archives. Mechanically it matches the other
+ * Hub fixtures: NEUTRAL faction, immobile, no AI hooks. The shell wires
+ * `interact` adjacent to an ArchiveTerminal → open the <chronicle-archive>
+ * modal.
+ *
+ * Glyph `'L'` — ASCII-safe "ledger/log" shorthand distinct from the crew
+ * terminal's `‡`.
+ */
+
+import { Entity } from '../Entity.js';
+import { FACTION } from '../constants.js';
+import type { EntityInit } from '../Entity.js';
+
+export const ARCHIVE_TERMINAL_GLYPH = '£';
+
+type ArchiveTerminalInit = Omit<
+  EntityInit,
+  'faction' | 'glyph' | 'maxAp' | 'maxHp' | 'id' | 'x' | 'y'
+> & {
+  id?: string;
+  x?: number;
+  y?: number;
+};
+
+export class ArchiveTerminal extends Entity {
+  constructor(props: ArchiveTerminalInit = {}) {
+    super({
+      id: props.id ?? 'archive-terminal',
+      x: props.x ?? 0,
+      y: props.y ?? 0,
+      faction: FACTION.NEUTRAL,
+      glyph: ARCHIVE_TERMINAL_GLYPH,
+      maxAp: 0,
+      maxHp: 1,
+    });
+  }
+}
diff --git a/src/game/hub/SafeSpace.ts b/src/game/hub/SafeSpace.ts
index 6d272b2..9a6f794 100644
--- a/src/game/hub/SafeSpace.ts
+++ b/src/game/hub/SafeSpace.ts
@@ -1,19 +1,19 @@
 /**
  * The Hub map — small authored "safe house" the player returns to between
  * runs. Not procedural: the Hub is the same shape every visit so the player
- * forms a spatial relationship with the Curator, the loadout Terminal, and
- * the exit door.
+ * forms a spatial relationship with the Curator, the loadout Terminal, the
+ * Chronicle ledger, and the exit door.
  *
- * Layout (12×8, walls outline the room, `D` is the exit door,
- * `C` is the Curator, `F` is Finn the fence, `‡` is the loadout Terminal,
- * `⧰` is Patch the clinic, `@` is the player spawn):
+ * Layout (12×8, walls outline the room, `D` is the exit door, `C` is the
+ * Curator, `F` is Finn the fence, `‡` is the loadout Terminal, `L` is the
+ * Chronicle ledger, `⧰` is Patch the clinic, `@` is the player spawn):
  *
  *   ############
  *   #..........#
  *   #.C..F...‡.#
  *   #..........#
  *   #..........#
- *   #⧰....@....#
+ *   #.L..⧰...@.#
  *   #..........¤
  *   ############
  *
@@ -28,15 +28,16 @@ import { TILE } from '../constants.js';
 
 export const HUB_WIDTH = 12;
 export const HUB_HEIGHT = 8;
-export const HUB_PLAYER_SPAWN = Object.freeze({ x: 6, y: 5 });
+export const HUB_PLAYER_SPAWN = Object.freeze({ x: 9, y: 5 });
 export const HUB_CURATOR_SPAWN = Object.freeze({ x: 2, y: 2 });
 // Terminal sits across the room from the Curator so the player has to make
 // the explicit decision to walk to it (no accidental archetype reroll while
 // heading for the Curator). Walkable FLOOR, distinct from every other named
 // tile in the hub.
 export const HUB_FINN_SPAWN = Object.freeze({ x: 5, y: 2 });
-export const HUB_CLINIC_SPAWN = Object.freeze({ x: 2, y: 5 });
+export const HUB_CLINIC_SPAWN = Object.freeze({ x: 5, y: 5 });
 export const HUB_TERMINAL_SPAWN = Object.freeze({ x: 9, y: 2 });
+export const HUB_ARCHIVE_TERMINAL_SPAWN = Object.freeze({ x: 2, y: 5 });
 export const HUB_EXIT_TILE = Object.freeze({ x: 11, y: 6 });
 
 export function buildHub() {
@@ -61,6 +62,7 @@ export function buildHub() {
     finnSpawn: { ...HUB_FINN_SPAWN },
     clinicSpawn: { ...HUB_CLINIC_SPAWN },
     terminalSpawn: { ...HUB_TERMINAL_SPAWN },
+    archiveTerminalSpawn: { ...HUB_ARCHIVE_TERMINAL_SPAWN },
     exitTile: { ...HUB_EXIT_TILE },
   };
 }
diff --git a/src/game/persistence.ts b/src/game/persistence.ts
index df81fde..58baef0 100644
--- a/src/game/persistence.ts
+++ b/src/game/persistence.ts
@@ -154,6 +154,12 @@ import type { EntitySnapshotExtra } from '../types.js';
 import type { CampaignMeta, CampaignState } from './Campaign.js';
 import { normalizeLocationSite } from './locations.js';
 import { normalizeMapDimensions } from './procgen/mapDimensions.js';
+import {
+  normalizeCampaignChronicle,
+  normalizePendingChronicleRun,
+  type CampaignChronicleEntry,
+  type PendingChronicleRun,
+} from './chronicle.js';
 import type { KeyItem, LocationSite, TileDelta } from '../types.js';
 
 const ARCHETYPE_KEY = Symbol.for('kernel-panic.archetype');
@@ -977,6 +983,10 @@ export type CampaignSnapshot = {
   keyItems?: KeyItemSnapshot[];
   /** Remembered combat locations (site roster). Defaults to [] for pre-P2.5.M7.2 saves. */
   siteRoster?: LocationSite[];
+  /** P3.M7: active campaign chronicle entries. Defaults to [] on older saves. */
+  chronicle?: CampaignChronicleEntry[];
+  /** Mid-run chronicle baseline used to finish the current job entry on restore. */
+  pendingChronicleRun?: PendingChronicleRun | null;
 };
 
 /** Serializable key item (P2.5.M6.2). */
@@ -1039,6 +1049,13 @@ export function snapshotCampaign(campaign: Campaign): CampaignSnapshot {
     clockJobsTaken: campaign.clockJobsTaken,
     keyItems: campaign.keyItems.map(k => ({ ...k })),
     siteRoster: campaign.siteRoster.map(snapshotLocationSite),
+    chronicle: campaign.chronicle.map(entry => ({ ...entry, detailLines: [...entry.detailLines] })),
+    pendingChronicleRun: campaign.pendingChronicleRun
+      ? {
+          ...campaign.pendingChronicleRun,
+          flatlinedCrewIdsBefore: [...campaign.pendingChronicleRun.flatlinedCrewIdsBefore],
+        }
+      : null,
   };
 }
 
@@ -1446,6 +1463,8 @@ export function restoreCampaign(record: unknown, options: RestoreCampaignOptions
     clockJobsTaken: record.clockJobsTaken ?? 0,
     keyItems: record.keyItems,
     siteRoster: record.siteRoster,
+    chronicle: record.chronicle,
+    pendingChronicleRun: record.pendingChronicleRun,
     onPersist: options.onPersist,
     onResult: options.onResult,
   });
@@ -1502,6 +1521,7 @@ export function restoreCampaign(record: unknown, options: RestoreCampaignOptions
     campaign.curator = null;
     campaign.finn = null;
     campaign.terminal = null;
+    campaign.archiveTerminal = null;
     campaign.clinic = null;
     campaign.exitTile = null;
   } else {
@@ -1517,6 +1537,7 @@ export function restoreCampaign(record: unknown, options: RestoreCampaignOptions
     campaign.curator = null;
     campaign.finn = null;
     campaign.terminal = null;
+    campaign.archiveTerminal = null;
     campaign.clinic = null;
     campaign.exitTile = null;
   }
@@ -2265,6 +2286,12 @@ function validateCampaignRecord(record: unknown): asserts record is CampaignSnap
     // than producing a bad map on a later revisit.
     candidate.siteRoster.forEach(entry => normalizeLocationSite(entry));
   }
+  if (candidate.chronicle !== undefined) {
+    normalizeCampaignChronicle(candidate.chronicle);
+  }
+  if (candidate.pendingChronicleRun !== undefined) {
+    normalizePendingChronicleRun(candidate.pendingChronicleRun);
+  }
 }
 
 function archetypeOfCrew(member: Crew): CrewArchetypeId {
diff --git a/src/input/mapKeyRows.ts b/src/input/mapKeyRows.ts
index 8934015..92aaa91 100644
--- a/src/input/mapKeyRows.ts
+++ b/src/input/mapKeyRows.ts
@@ -14,7 +14,8 @@ export const MAP_KEY_UNIVERSAL: readonly MapKeyRow[] = Object.freeze([
 export const MAP_KEY_HUB: readonly MapKeyRow[] = Object.freeze([
   { glyph: 'C', label: 'Curator — contracts & rumors' },
   { glyph: '¥', label: "Finn's shop" },
-  { glyph: '⧰', label: 'Clinic (Patch)' },
+  { glyph: '⧰', label: "Patch's clinic" },
+  { glyph: '£', label: 'ledger - chronicle of all runs' },
   { glyph: '‡', label: 'crew terminal' },
 ]);
 
diff --git a/src/shell/domTypes.ts b/src/shell/domTypes.ts
index 064a0ff..4eab825 100644
--- a/src/shell/domTypes.ts
+++ b/src/shell/domTypes.ts
@@ -1,5 +1,6 @@
 import type { Campaign } from '../game/Campaign.js';
 import type { Crew } from '../game/Crew.js';
+import type { CampaignChronicleEntry } from '../game/chronicle.js';
 import type { Contract } from '../game/hub/Curator.js';
 import type { Item } from '../game/items.js';
 import type { CampaignSummary } from '../game/campaignSummary.js';
@@ -64,6 +65,17 @@ export type CrewRosterElement = ModalElement & {
   ): void;
 };
 
+export type ChronicleArchiveElement = ModalElement & {
+  setData(data: {
+    activeChronicle?: {
+      statusLines?: readonly string[];
+      entries: readonly CampaignChronicleEntry[];
+    } | null;
+    history: readonly CampaignSummary[];
+    acquisitions: { unlocked: number; total: number };
+  }): void;
+};
+
 export type FinnShopElement = ModalElement & {
   setCatalog(
     catalog: Item[],
diff --git a/src/shell/shellRuntime.ts b/src/shell/shellRuntime.ts
index 28fb669..120110b 100644
--- a/src/shell/shellRuntime.ts
+++ b/src/shell/shellRuntime.ts
@@ -52,7 +52,7 @@ import { placeSmoke, clearSmoke } from '/src/game/Smoke.js';
 import { placeHazardCluster } from '/src/game/Run.js';
 import { blastCells } from '/src/game/breachBlast.js';
 import { hasLineOfSight } from '/src/game/LineOfSight.js';
-import { ITEM_ID, getItemById } from '/src/game/items.js';
+import { ITEM_ID, SCOREABLE_ITEMS, getItemById } from '/src/game/items.js';
 import type { CampaignSnapshot } from '/src/game/persistence.js';
 import type { Contract } from '/src/game/hub/Curator.js';
 import {
@@ -108,6 +108,7 @@ import {
 } from '/src/shell/statusLine.js';
 import { applyMeatSeenRecord, syncVisionFields } from '/src/shell/visionSync.js';
 import type {
+  ChronicleArchiveElement,
   ClinicModalElement,
   ConfirmationModalElement,
   ContractSelectElement,
@@ -197,6 +198,7 @@ let crewRosterEl: CrewRosterElement;
 let finnShopEl: FinnShopElement;
 let clinicModalEl: ClinicModalElement;
 let itemInventoryEl: ItemInventoryElement;
+let chronicleArchiveEl: ChronicleArchiveElement;
 let keyHelpEl: KeyHelpElement;
 let logEl: HTMLElement;
 let logHeaderEl: HTMLElement;
@@ -388,6 +390,7 @@ export async function boot() {
   finnShopEl = mustGetElement<FinnShopElement>('finn-shop');
   clinicModalEl = mustGetElement<ClinicModalElement>('clinic-modal');
   itemInventoryEl = mustGetElement<ItemInventoryElement>('item-inventory');
+  chronicleArchiveEl = mustGetElement<ChronicleArchiveElement>('chronicle-archive');
   keyHelpEl = mustGetElement<KeyHelpElement>('key-help');
   logEl = mustQuery<HTMLElement>('.game-log');
   logHeaderEl = mustQuery<HTMLElement>('.game-log h3');
@@ -442,6 +445,7 @@ export async function boot() {
 
   itemInventoryEl.addEventListener('use-item', onUseItem);
   itemInventoryEl.addEventListener('dismiss', () => itemInventoryEl.hide());
+  chronicleArchiveEl.addEventListener('dismiss', () => chronicleArchiveEl.hide());
 
   keyHelpEl.addEventListener('dismiss', () => keyHelpEl.hide());
 
@@ -455,7 +459,6 @@ export async function boot() {
       tryShowKeyHelpOverlay();
     });
   }
-
   confirmationModalEl.addEventListener('confirm', evt => {
     const detail = (evt as CustomEvent<{ context?: string }>).detail;
     switch (detail?.context) {
@@ -582,6 +585,7 @@ function hideBlockingShellModals(): void {
   finnShopEl?.hide();
   clinicModalEl?.hide();
   itemInventoryEl?.hide();
+  chronicleArchiveEl?.hide();
 }
 
 function abortShellForFault(): void {
@@ -710,6 +714,25 @@ function presentCrewRoster() {
   crewRosterEl.show();
 }
 
+function presentChronicleArchive() {
+  chronicleArchiveEl.setData({
+    activeChronicle: campaign
+      ? {
+          statusLines: formatHubArcStatusLines(campaign).filter(
+            (line): line is string => line !== null
+          ),
+          entries: campaign.chronicle,
+        }
+      : null,
+    history: dataStore.campaignHistory,
+    acquisitions: {
+      unlocked: dataStore.unlockedScoreableItems.length,
+      total: SCOREABLE_ITEMS.length,
+    },
+  });
+  chronicleArchiveEl.show();
+}
+
 function onCrewRecruit(evt: Event) {
   if (!campaign) return;
   const { recruitId } = (evt as CustomEvent<{ recruitId: string }>).detail;
@@ -1932,6 +1955,15 @@ function handleInteract(): void {
     presentClinic();
     return;
   }
+  if (
+    campaign.player &&
+    campaign.archiveTerminal &&
+    isChebyshevAdjacent(campaign.player, campaign.archiveTerminal)
+  ) {
+    flash('ARCHIVE — Chronicle and campaign history.');
+    presentChronicleArchive();
+    return;
+  }
   if (
     campaign.player &&
     campaign.terminal &&
@@ -1953,6 +1985,7 @@ function handleInteract(): void {
     const hints = ['Curator (contract)'];
     if (campaign.finn) hints.unshift('Finn (shop)');
     if (campaign.clinic) hints.push('Patch (clinic)');
+    hints.push('Archive (Chronicle)');
     hints.push('Terminal (roster)');
     flash(`Step adjacent to ${hints.join(', ')}.`);
     return;
@@ -2584,6 +2617,7 @@ function isAnyBlockingModalOpen(): boolean {
   if (finnShopEl?.isOpen) return true;
   if (clinicModalEl?.isOpen) return true;
   if (itemInventoryEl?.isOpen) return true;
+  if (chronicleArchiveEl?.isOpen) return true;
   if (keyHelpEl?.isOpen) return true;
   if (faultEl?.isOpen) return true;
   // <confirmation-modal> uses a native <dialog> internally; treat any open
diff --git a/sw-core.js b/sw-core.js
index d8bd56c..4f39fd6 100644
--- a/sw-core.js
+++ b/sw-core.js
@@ -36,6 +36,7 @@ const CacheConfig = {
       '/components/CrewRoster.js',
       '/components/FinnShop.js',
       '/components/ClinicModal.js',
+      '/components/ChronicleArchive.js',
       '/components/InitialRecruit.js',
       '/components/ItemInventory.js',
       '/components/KeyHelp.js',
@@ -62,6 +63,7 @@ const CacheConfig = {
       '/src/game/archetypes/Tech.js',
       '/src/game/Campaign.js',
       '/src/game/campaignSummary.js',
+      '/src/game/chronicle.js',
       '/src/game/Combat.js',
       '/src/game/combatTurnPipeline.js',
       '/src/game/constants.js',
@@ -92,6 +94,7 @@ const CacheConfig = {
       '/src/game/Hostile.js',
       '/src/game/hub/Curator.js',
       '/src/game/hub/arcSurface.js',
+      '/src/game/hub/ArchiveTerminal.js',
       '/src/game/hub/Clinic.js',
       '/src/game/hub/Finn.js',
       '/src/game/hub/hubReveals.js',
diff --git a/sw-dev.js b/sw-dev.js
index 8245b48..bcaf02a 100644
--- a/sw-dev.js
+++ b/sw-dev.js
@@ -1,5 +1,5 @@
 // Service Worker for Kernel Panic - Development Version
-const VERSION = '0.2.17-dev';
+const VERSION = '0.3.0-dev';
 importScripts(`/sw-core.js?v=${VERSION}`);
 
 const cacheConfig = CacheConfig.create(VERSION);
diff --git a/sw.js b/sw.js
index c3d3ae8..3488502 100644
--- a/sw.js
+++ b/sw.js
@@ -1,6 +1,6 @@
 // Service Worker for Kernel Panic - Production Version
 // Import shared caching core with cache-busting query parameter
-const VERSION = '0.2.17';
+const VERSION = '0.3.0';
 importScripts(`/sw-core.js?v=${VERSION}`);
 
 const cacheConfig = CacheConfig.create(VERSION);
diff --git a/tests/unit/game/Campaign.test.ts b/tests/unit/game/Campaign.test.ts
index 7f3a28f..de04a31 100644
--- a/tests/unit/game/Campaign.test.ts
+++ b/tests/unit/game/Campaign.test.ts
@@ -196,6 +196,64 @@ test('onJobEnd with EXIT applies contract Cred and Rep rewards without spending
   assert.equal(campaign.rep, 27); // 20 start + 7 repDelta
 });
 
+test('P3.M7: casing jobs append arc-aware chronicle entries and survive snapshot restore', () => {
+  const campaign = new Campaign({ seed: 42, rep: 65, completedJobs: 4 });
+  const scoreTarget = campaign.siteRoster.find(site => site.scoreTarget);
+  assert.ok(scoreTarget?.principal);
+  assert.ok(
+    campaign.chronicle.some(entry => entry.title === 'STAGE 2 — SCORE REVEALED'),
+    'Act 2 transition should log the Score reveal'
+  );
+
+  const decker = campaign.crew.find(member => member.archetype === 'Decker');
+  assert.ok(decker);
+  const contract = fakeContract({
+    label: '// Matsuda payroll cache //',
+    context: {
+      ...testContractContext(OBJECTIVES.REACH_EXIT),
+      principal: scoreTarget!.principal,
+      site: { id: 'payroll-cache', label: 'payroll cache', groups: ['corp', 'data'] },
+      locationSiteId: 'case-payroll-cache',
+    },
+    reward: { credits: 120, repDelta: 5 },
+  });
+
+  campaign.deployCrewMember(decker!.id, contract);
+  campaign.onJobEnd({ outcome: OUTCOME.EXIT, salvage: emptySalvage(), completed: true });
+
+  const entry = campaign.chronicle.at(-1);
+  assert.ok(entry);
+  assert.equal(entry!.kind, 'job');
+  assert.match(entry!.title, /^CASING/);
+  assert.match(entry!.summary, /another read/i);
+  assert.ok(entry!.detailLines.some(line => line.includes('Rep +5 | Credits +120')));
+
+  const restored = restoreCampaign(snapshotCampaign(campaign));
+  assert.equal(restored.chronicle.length, campaign.chronicle.length);
+  assert.deepEqual(restored.chronicle.at(-1), entry);
+});
+
+test('P3.M7: pending chronicle run survives restore and settles into a job entry', () => {
+  const campaign = new Campaign({ seed: 99 });
+  const member = campaign.crew[0]!;
+  const contract = fakeContract({
+    label: 'warehouse ghost',
+    reward: { credits: 40, repDelta: 2 },
+  });
+
+  campaign.deployCrewMember(member.id, contract);
+  const restored = restoreCampaign(snapshotCampaign(campaign));
+  assert.ok(restored.pendingChronicleRun, 'mid-run chronicle baseline should persist');
+
+  restored.onJobEnd({ outcome: OUTCOME.EXIT, salvage: emptySalvage(), completed: true });
+
+  const entry = restored.chronicle.at(-1);
+  assert.ok(entry);
+  assert.equal(entry!.kind, 'job');
+  assert.match(entry!.summary, /street-level/i);
+  assert.ok(entry!.detailLines.some(line => line.includes('Rep +2 | Credits +40')));
+});
+
 test('onJobEnd with incomplete EXIT (abort) forfeits salvage and applies rep penalty', () => {
   const campaign = new Campaign({ seed: 42 });
   const member = campaign.crew[1];
diff --git a/tests/unit/game/hub/ArchiveTerminal.test.ts b/tests/unit/game/hub/ArchiveTerminal.test.ts
new file mode 100644
index 0000000..241e687
--- /dev/null
+++ b/tests/unit/game/hub/ArchiveTerminal.test.ts
@@ -0,0 +1,41 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { FACTION } from '../../../../src/game/constants.js';
+import {
+  ArchiveTerminal,
+  ARCHIVE_TERMINAL_GLYPH,
+} from '../../../../src/game/hub/ArchiveTerminal.js';
+import { buildHub } from '../../../../src/game/hub/SafeSpace.js';
+
+test('ArchiveTerminal constructs with NEUTRAL faction, zero AP, glyph £', () => {
+  const archive = new ArchiveTerminal({ x: 10, y: 2 });
+  assert.equal(archive.faction, FACTION.NEUTRAL);
+  assert.equal(archive.maxAp, 0);
+  assert.equal(archive.glyph, ARCHIVE_TERMINAL_GLYPH);
+  assert.equal(archive.x, 10);
+  assert.equal(archive.y, 2);
+  assert.equal(archive.alive, true);
+});
+
+test('ArchiveTerminal has a stable default id for shell routing', () => {
+  const archive = new ArchiveTerminal({ x: 0, y: 0 });
+  assert.equal(archive.id, 'archive-terminal');
+});
+
+test('buildHub returns an archiveTerminalSpawn on walkable floor, distinct from other hub fixtures', () => {
+  const hub = buildHub();
+  const same = (a: { x: number; y: number }, b: { x: number; y: number }) =>
+    a.x === b.x && a.y === b.y;
+
+  assert.ok(hub.archiveTerminalSpawn, 'expected archiveTerminalSpawn in buildHub() result');
+  assert.equal(typeof hub.archiveTerminalSpawn.x, 'number');
+  assert.equal(typeof hub.archiveTerminalSpawn.y, 'number');
+  assert.equal(hub.grid.isPassable(hub.archiveTerminalSpawn.x, hub.archiveTerminalSpawn.y), true);
+  assert.ok(!same(hub.archiveTerminalSpawn, hub.playerSpawn), 'archive overlaps player spawn');
+  assert.ok(!same(hub.archiveTerminalSpawn, hub.curatorSpawn), 'archive overlaps curator');
+  assert.ok(!same(hub.archiveTerminalSpawn, hub.finnSpawn), 'archive overlaps finn');
+  assert.ok(!same(hub.archiveTerminalSpawn, hub.clinicSpawn), 'archive overlaps clinic');
+  assert.ok(!same(hub.archiveTerminalSpawn, hub.terminalSpawn), 'archive overlaps terminal');
+  assert.ok(!same(hub.archiveTerminalSpawn, hub.exitTile), 'archive overlaps exit tile');
+});
diff --git a/tests/unit/game/scoreFinal.test.ts b/tests/unit/game/scoreFinal.test.ts
index c29f339..2a0da27 100644
--- a/tests/unit/game/scoreFinal.test.ts
+++ b/tests/unit/game/scoreFinal.test.ts
@@ -360,7 +360,9 @@ test('a clean abstract Score settles the arc but writes no meta-store unlock', (
   const decker = campaign.crew.find(member => member.archetype === 'Decker')!;
   const partner = campaign.crew.find(member => member.archetype !== 'Decker')!;
   const beforeCredits = campaign.credits;
-  campaign.deployCrewMember(decker.id, campaign.buildScoreContract(allAcquired), partner.id).enterCombat();
+  campaign
+    .deployCrewMember(decker.id, campaign.buildScoreContract(allAcquired), partner.id)
+    .enterCombat();
 
   campaign.onJobEnd({ outcome: OUTCOME.EXIT, completed: true });
   // Arc reaches its climax exactly as a blueprint Score would.
diff --git a/tests/unit/game/scoreableUnlocks.test.ts b/tests/unit/game/scoreableUnlocks.test.ts
index f761b24..b8aa4d0 100644
--- a/tests/unit/game/scoreableUnlocks.test.ts
+++ b/tests/unit/game/scoreableUnlocks.test.ts
@@ -47,14 +47,14 @@ test('archiveScoreableItem is a no-op for a duplicate id', () => {
 });
 
 test('archiveScoreableItem validates the input list', () => {
-  assert.throws(() => archiveScoreableItem('proto-exoframe' as unknown as string[], 'x'), TypeError);
+  assert.throws(
+    () => archiveScoreableItem('proto-exoframe' as unknown as string[], 'x'),
+    TypeError
+  );
   assert.throws(() => archiveScoreableItem(['ok', ''], 'x'), TypeError);
 });
 
 test('archiveScoreableItem rejects an empty or non-string id', () => {
   assert.throws(() => archiveScoreableItem(['proto-exoframe'], ''), TypeError);
-  assert.throws(
-    () => archiveScoreableItem(['proto-exoframe'], 7 as unknown as string),
-    TypeError
-  );
+  assert.throws(() => archiveScoreableItem(['proto-exoframe'], 7 as unknown as string), TypeError);
 });