Record CR-020: independent pilots (Phase 20)

Received as CR-019 for Phase 19; renumbered. Decisions 0.5.118-0.5.126.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

DECISIONS.md

@@ -1664,3 +1664,8 @@ Implementation decisions not spelled out in `memory-bank/implementation-plan.md`
 ## Follow-up after Phase 20: fewer Dashboard tiles
 
 - **The Dashboard drops its Credits and Game date tiles** (user request): both are always in the header's chips. Ships idle and Ships in flight stay, side by side.
+
+## CR-020 recorded (Independent Pilots)
+
+- **Numbering:** received as "CR-019 — Independent Pilots" for "Phase 19"; stored as **CR-020**, built as **Phase 20** (its 19.n = 20.n). Its decisions CR-019.D1–D9 are **0.5.118–0.5.126**. Its references: CR-005 → CR-007, CR-007 → CR-010, CR-011 → CR-014 (its 10K.6 → Step 14.6), CR-014 → CR-015, CR-016 → CR-017, CR-017 → CR-018, CR-018 → CR-019; CR-001 and CR-004 are unchanged.
+- **Plan 0.3:** automation/standing routes is struck from the deferred list; standing orders, pilot traits, decision events and a hiring market stay deferred.

memory-bank/change-requests/CR-020-independent-pilots.md

@@ -0,0 +1,179 @@
+# Change Request CR-020 — Independent Pilots
+
+> **Numbering note (added when recorded):** this request arrived titled "CR-019 — Independent Pilots" for "Phase 19". CR-019 (completable boards) and Phase 19 already existed, so it is stored as **CR-020** and done as **Phase 20**: every "19.n" below means **20.n**. Its references map to this repo as: "Phase 13 and CR-001 through CR-018" = Phase 13 and **CR-001 to CR-019**; "CR-001" (goals, Step 10A.5) and "CR-004" (pilot rest) are the same numbers; "CR-005 cargo goods" = **CR-007**; "CR-007 veteran pilot" (profit-share pay) = **CR-010**; "CR-011 local-first" = **CR-014**, and its "10K.6" resolution loop is **Step 14.6**; "CR-014 fixed map and fuel tanks" = **CR-015**; "CR-016" (the Pilots tab badge) = **CR-017**; "CR-017 fuel tuning" = **CR-018**; "CR-018 completable jobs" = **CR-019**. Its new decisions CR-019.D1–D9 are recorded as **0.5.118 Owner-operator, 0.5.119 Dispatch Office, 0.5.120 Modes and orders, 0.5.121 Job choice, 0.5.122 Player priority, 0.5.123 Fuel for pilots, 0.5.124 Idle behavior, 0.5.125 Deterministic catch-up, 0.5.126 No independent-trip notifications**.
+>
+> **On recording:** "HQ" means a player bay (plan 0.5 bays); the HQ screen is the app's HQ tab. "Game minutes" convert to real time by `timeCompression` (60 in this build), so the default 15-game-minute turnaround is 15 real seconds.
+
+**Project:** Deadhead: Space Freight Tycoon
+**Applies to:** a build with Phase 13 and CR-001 through CR-018 complete
+**Do this:** as **Phase 19**
+**Related docs:** `change-request-pilot-rest.md` (CR-004), `change-request-cargo-goods.md` (CR-005), `change-request-veteran-pilot.md` (CR-007), `change-request-local-first.md` (CR-011), `change-request-fixed-map-and-fuel-tanks.md` (CR-014), `change-request-fuel-tuning.md` (CR-017), `change-request-completable-jobs.md` (CR-018), `game-design-document.md`, `DECISIONS.md`
+
+This change request is written for the local-first engine (CR-011). It turns the "NPC pilots" ideas from the design theorizing sessions into a first, buildable version.
+
+---
+
+## 1. Why
+
+Today every job is dispatched by hand, so the fleet stops when the player puts the phone down. This change lets **hired pilots run jobs on their own**, so the company keeps earning while the player is away: closer to an idle game, without losing the hands-on dispatching.
+
+Settled in the design sessions:
+
+- **The player stays an owner-operator.** The avatar is never autonomous. The player still flies, buys and upgrades ships, and spends every pilot's skill points.
+- **Hired pilots only fly jobs.** They don't buy ships, upgrade ships, or spend skill points. They still **earn XP** from the work they do; the player decides how to spend it.
+- **Rest is the soft cap.** Independent pilots follow the existing duty and rest rules (CR-004), so a fleet left overnight works a shift, rests, and works again. No arbitrary offline timer.
+- **The player gets first look.** New jobs on a board are the player's alone for a few minutes before pilots can take them, and first-contact (discovery) jobs are the player's only.
+- **Everything is deterministic.** Pilots' decisions are replayed on the device when the app opens, from the same state and boards, so results are the same however the time is split up.
+
+## 2. How it works
+
+### Unlocking: the Dispatch Office
+- A one-time company purchase from the HQ screen: **Dispatch Office** (price in content; start around the price of a Lighter). Until it's bought, pilots can't be set to Independent.
+- It's also a money sink and a mid-game goal.
+
+### Pilot modes
+| Mode | Behavior |
+|---|---|
+| **Manual** (default) | Current behavior. The pilot only flies when the player dispatches them. |
+| **Independent** | Whenever the pilot is idle, rested, and crewing an idle ship that isn't in the shop, they choose and fly a job from the board where they are, following their orders. |
+
+- The avatar can't be set to Independent.
+- The player can still dispatch an Independent pilot by hand when they're idle; the player's action always wins.
+- Switching to Manual takes effect when the pilot's current trip ends.
+
+### Orders (set per pilot by the player)
+| Order | Default |
+|---|---|
+| Allowed destinations | All discovered locations |
+| Allowed cargo classes | Standard, Heavy, High-Value, Dangerous (those the pilot is skilled for anyway) |
+| Take Priority jobs | Yes |
+| Minimum profit per job | 0 cr |
+| Home HQ | The HQ where they were hired, or Earth |
+
+### Choosing a job
+When an Independent pilot can act, they look at the board at their location (CR-018: it only lists jobs the fleet can do) and consider jobs that:
+
+- this pilot and ship can complete right now (all dispatch validations, including fuel after an allowed refuel, below);
+- pass their orders;
+- are **not first-contact jobs** (discovery is the player's);
+- are **past the first-look window**: at least the configured number of real minutes (default 3) into the board period;
+- aren't being viewed by the player at that moment (live play only, see §2 "While the app is open").
+
+They pick the job with the highest **profit per hour**:
+
+`profit per hour = (payout − fuel cost − pilot share) ÷ trip time in game hours`
+
+Fuel cost uses the tank's average price for fuel already aboard and the location's price for fuel that must be bought. Ties go to the shorter trip, then the lower contract id.
+
+### Fuel
+- Pilots follow their ship's refuel policy (CR-017; Manual by default).
+- If the best job needs more fuel than is aboard, the pilot buys **only what that leg needs**, as long as company credits stay above the **NPC spending floor** (a company setting, default 500 cr). Otherwise they consider only jobs they can fly on the fuel aboard.
+- Pilots never use emergency fuel; that stays a player decision.
+
+### When there's nothing to take
+- The pilot **waits** at the location for the next board period (waiting doesn't add duty hours).
+- After 3 empty periods in a row away from their home HQ, they **deadhead home** if the ship can reach it with the fuel rules above; otherwise they keep waiting.
+
+### Rest and turnaround
+- Duty and rest are unchanged (CR-004). A pilot over the duty limit rests on arrival, then resumes.
+- Each new job starts after a **turnaround time** (default 15 game minutes) from the moment the pilot becomes able to act. This is the main balance knob for idle income.
+
+### Pay and XP
+- Profit-share pay (CR-007) and loan repayment (CR-001) apply as for any delivery.
+- XP is earned as usual; unspent points show on the Pilots tab badge (CR-016).
+
+### Catch-up and while the app is open
+- **Catch-up:** when the app opens or resumes, the engine replays everything since the last saved time as an event queue: arrivals, rest endings, shop completions, board period starts, and pilot decision points, processed in time order (ties broken by pilot id). Board generation during catch-up uses the same deterministic rules as live play.
+- **Splitting time doesn't change results:** catching up 8 hours at once gives exactly the same state as catching up in 1-hour pieces.
+- **Limits:** catch-up covers at most 7 days of absence and runs in chunks so the UI stays responsive, with a "Catching up on your fleet…" indicator when it takes more than a moment.
+- **While the app is open:** the resolution loop (CR-011) also runs pilot decisions. The client tells the engine which contract the player has open, and pilots skip it until it's closed.
+- **Notifications:** independent trips aren't decided while the app is closed, so they can't be scheduled as notifications ahead of time. No per-trip notifications for independent pilots.
+
+### The logbook
+The "while you were away" screen gains a **per-pilot logbook**: jobs flown (good, route, payout, pilot share, fuel), deadheads, rests, XP gained, and where the pilot is now, with company totals at the top.
+
+## 3. Rules for this change
+
+- All rules in `implementation-plan.md` §0.1 apply: steps in order, one commit per step, each step's test must pass, `packages/sim` stays pure, all numbers live in `packages/content`.
+- **Pilots use the same commands as the player.** An independent dispatch goes through the normal dispatch validation and command path; nothing bypasses rules.
+- **Job choice is a pure function** in `packages/sim` (state and board in, chosen action out), so it can be tested in isolation.
+- Save migration: every pilot starts in Manual with default orders; the company has no Dispatch Office; the NPC spending floor is set to its default.
+- Update `architecture.md` and `progress.md` as you go. Stop for the user's review at the end of Phase 19.
+
+## 4. Decisions
+
+Record these in `DECISIONS.md` and `implementation-plan.md` §0.5, using the next free numbers (labeled CR-019.D1–D9 here; note the mapping).
+
+- **CR-019.D1 Owner-operator.** The avatar is never autonomous. Hired pilots never buy, upgrade, or spend points; they do earn XP.
+- **CR-019.D2 Dispatch Office.** One-time company purchase required before any pilot can be Independent.
+- **CR-019.D3 Modes and orders.** Manual (default) or Independent, with per-pilot orders per §2.
+- **CR-019.D4 Job choice.** Highest profit per hour among eligible jobs, per §2.
+- **CR-019.D5 Player priority.** First-look window (default 3 real minutes into each board period); first-contact jobs are player-only; jobs the player is viewing are skipped.
+- **CR-019.D6 Fuel for pilots.** Buy only what the chosen leg needs, never below the NPC spending floor; never emergency fuel.
+- **CR-019.D7 Idle behavior.** Wait for the next board; after 3 empty periods away from home HQ, deadhead home if possible.
+- **CR-019.D8 Deterministic catch-up.** Event-queue replay on open/resume, at most 7 days, results independent of how time is split.
+- **CR-019.D9 No independent-trip notifications.**
+
+Removes "automation / standing routes and auto-accept rules" from the deferred list (`implementation-plan.md` §0.3); standing orders remain a possible later addition.
+
+## 5. Steps — Phase 19
+
+### Step 19.1 — Content and config
+- Add: Dispatch Office price, first-look window (real minutes), turnaround time (game minutes), empty periods before heading home (3), maximum catch-up window (7 days), default NPC spending floor (500 cr).
+- **Test:** Config validates; all values positive; the first-look window is shorter than the board period.
+
+### Step 19.2 — Sim: eligibility and job choice
+- Pure functions: which jobs on a board an Independent pilot may consider (§2 filters); profit per hour for a job given the ship's fuel and the location's price; the pilot's chosen action (take a job, refuel-then-take, wait, or deadhead home).
+- **Test:** First-contact jobs are never chosen. Jobs inside the first-look window aren't chosen; the same job is after the window. Jobs outside the orders (destination, class, Priority, minimum profit) aren't chosen. The highest profit-per-hour job is chosen, with the documented tie-breaks. A pilot who can only afford fuel above the spending floor picks among jobs they can fly on fuel aboard. With nothing eligible, the result is wait; after 3 empty periods away from home, deadhead home when reachable.
+
+### Step 19.3 — Engine: Dispatch Office, modes, orders
+- Commands: buy Dispatch Office, set pilot mode, set pilot orders, set NPC spending floor. Save fields and migration per §3.
+- **Test:** Setting Independent fails before the Dispatch Office is bought and succeeds after. The avatar can't be set to Independent. Orders save and load. An older save migrates with all pilots on Manual and no Dispatch Office.
+
+### Step 19.4 — Engine: event-queue catch-up
+- Extend the resolution loop (CR-011 Step 10K.6) into a time-ordered event queue covering arrivals, rest endings, shop completions, board period starts, and Independent pilots' decision points (each decision point is turnaround time after the pilot becomes able to act). Each pilot action is executed through the normal engine commands.
+- Cap catch-up at 7 days; process in chunks with a progress indicator hook.
+- **Test:** Determinism: from the same save, catching up 8 hours in one go and in eight 1-hour pieces gives identical saves. Two Independent pilots at the same location never take the same contract; the one whose decision comes first (then lower pilot id) gets it. A pilot over the duty limit rests on arrival and resumes after rest. Catch-up past 7 days stops at 7 days. No pilot is ever dispatched in a way that fails normal validation.
+
+### Step 19.5 — Engine: live play
+- While the app is open, the loop runs pilot decisions in real time. Add a client-to-engine signal for the contract currently open in the detail view; pilots skip it.
+- **Test:** With a contract marked as being viewed, an eligible pilot picks a different job; once the view closes, the contract becomes eligible again.
+
+### Step 19.6 — Client: Dispatch Office and pilot controls
+- HQ screen: Dispatch Office purchase with a short explanation ("Lets your hired pilots run jobs on their own").
+- Pilots screen: per-pilot Manual/Independent toggle (disabled with a reason before the Dispatch Office, hidden for the avatar), an orders editor (destinations, cargo classes, Priority, minimum profit, home HQ), and a status line ("Independent: flying Medical Supplies to the Moon", "Waiting for new contracts at Mars", "Resting until 14:20").
+- Settings → Company: NPC spending floor.
+- Fleet cards show an "Independent" badge on ships crewed by Independent pilots.
+- **Test:** Component tests: the toggle is disabled with a reason before purchase and hidden for the avatar; orders edits call the engine; each status line renders from seeded state; the badge appears only for Independent crews.
+
+### Step 19.7 — Client: board and logbook
+- Contract cards inside the first-look window show a small chip: "Yours for 2:31".
+- Catch-up shows "Catching up on your fleet…" when it takes more than half a second.
+- The "while you were away" screen gains the per-pilot logbook from §2, with company totals.
+- **Test:** Component tests: the chip counts down and disappears when the window ends; the indicator appears for slow catch-ups only; the logbook lists each pilot's jobs, deadheads, rests, XP, and current location, and totals match the sum of entries.
+
+### Step 19.8 — Balance
+- Extend the Phase 12 balance script with an "away" scenario: the player sets all hired pilots to Independent and closes the app for 8 real hours.
+- Target: the independent fleet earns **40–80%** of what the Phase 12 active-play policy earns with the same fleet over the same time. Tune turnaround time first, then the first-look window.
+- **Test:** The away scenario meets the target with default content. No simulated pilot ever buys fuel below the spending floor or gets stranded.
+
+### Step 19.9 — Plan amendments and regression
+- Apply the amendments in §6.
+- Run the full suite.
+- **Test:** CI is green. Manual check: buy the Dispatch Office, set Rosa to Independent with default orders, close the app for an hour, reopen, and read her logbook; then confirm a first-contact job stayed on the board for you.
+
+## 6. Amendments
+
+| Where | Change |
+|---|---|
+| Plan 0.3 | Remove automation/standing routes from deferred; standing orders, pilot traits, decision events, and a hiring market remain deferred. |
+| Plan 0.5 | Add CR-019.D1–D9. |
+| CR-001 goals | Optional later: a goal for buying the Dispatch Office (not part of this change). |
+| CR-011 10K.6 | Resolution loop becomes the event-queue catch-up (19.4). |
+| CR-018 | Pilots choose only from completable boards; no change to board rules. |
+| Plan 12.1 | Away scenario added (19.8). |
+| `game-design-document.md` | Pilots and automation sections updated by the designer. |
+
+## 7. Out of scope
+
+Standing orders (repeat routes), personality traits, decision events that wait for the player, a hiring market with varied candidates, pilots looking ahead to the destination's backhaul, pilots using emergency fuel, a premium contract tier, ship wear, and anything else in `implementation-plan.md` §0.3.

memory-bank/implementation-plan.md

@@ -36,7 +36,7 @@ This plan covers the **base game only**: the core loop of taking contracts, disp
 
 ### 0.3 Explicitly deferred (do NOT build)
 
-Random events, reputation, fuel price drift and depot shortages *(CR-015: fixed per-location prices are in, decision 0.5.96)*, fuel storage at HQ bays, throttle setting, multi-leg routes, recurring bay rent, pilot salaries over time, pilot poaching, automation/standing routes, interstellar, push notifications, Capacitor builds, Hardened landing class, surface Io and Venus's surface *(CR-016 added Venus Cloud City and Io Sulfur Works, which need no Hardened ships)*, asteroid-belt hazards, mining claims and belt events *(CR-016's belt is visual only)*, Fragile/Urgent/Fuel-efficiency skills, social features, monetization, account linking (email, Apple, Google sign-in) *(CR-011)*.
+Random events, reputation, fuel price drift and depot shortages *(CR-015: fixed per-location prices are in, decision 0.5.96)*, fuel storage at HQ bays, throttle setting, multi-leg routes, recurring bay rent, pilot salaries over time, pilot poaching, ~~automation/standing routes~~ *(CR-020: Independent pilots are in; standing orders, pilot traits, decision events and a hiring market stay deferred)*, interstellar, push notifications, Capacitor builds, Hardened landing class, surface Io and Venus's surface *(CR-016 added Venus Cloud City and Io Sulfur Works, which need no Hardened ships)*, asteroid-belt hazards, mining claims and belt events *(CR-016's belt is visual only)*, Fragile/Urgent/Fuel-efficiency skills, social features, monetization, account linking (email, Apple, Google sign-in) *(CR-011)*.
 
 ### 0.4 Glossary
 
@@ -173,6 +173,15 @@ These answer the pre-build review. Log each one in `DECISIONS.md` as it is imple
 115. **Qualifying fleet** (CR-019). Owned ships at the location, or in flight there and arriving before the board period ends, each with its assigned pilot, or with any unassigned pilot at the location when the player has a bay there; the whole fleet when no pair qualifies.
 116. **Permanent checks only** (CR-019). Completable means passing cargo fit (effective capacity), landing, range (full-tank reach, or the fuel on board where the origin sells none), the no-strand rule, the Priority window and the cargo and Long Haul skills. Rest, the shop, fuel on board and credits don't count.
 117. **Mid-period changes** (CR-019). A stored board keeps the fleet snapshot it was generated with; reads hide jobs the current qualifying fleet can no longer complete; new capability shows at the next board period. Replaces 0.5.53's weight warning.
+118. **Owner-operator** (CR-020). The avatar is never autonomous. Hired pilots never buy, upgrade or spend skill points; they do earn XP.
+119. **Dispatch Office** (CR-020). A one-time company purchase, required before any pilot can be Independent.
+120. **Modes and orders** (CR-020). A hired pilot is Manual (default) or Independent; Independent pilots follow per-pilot orders: allowed destinations, allowed cargo classes, Priority jobs or not, minimum profit per job, and a home HQ (the bay where they were hired, or Earth).
+121. **Job choice** (CR-020). An Independent pilot takes the eligible job on the board where they are with the highest profit per game hour, (payout − fuel cost − pilot share) ÷ trip time; ties go to the shorter trip, then the lower contract id.
+122. **Player priority** (CR-020). Pilots don't take jobs in the first-look window (default 3 real minutes into each board period), first-contact jobs, or the job the player has open.
+123. **Fuel for pilots** (CR-020). A pilot buys only the fuel the chosen leg needs, and only while company credits stay above the NPC spending floor (default 500 cr); never emergency fuel.
+124. **Idle behavior** (CR-020). With nothing to take, a pilot waits for the next board period; after 3 empty periods in a row away from their home HQ they deadhead home when they can.
+125. **Deterministic catch-up** (CR-020). On open or resume the engine replays events since the last saved time in time order (ties by pilot id), at most 7 days; the result doesn't depend on how the time is split.
+126. **No independent-trip notifications** (CR-020). Independent trips are decided on the device as time is replayed, so none are scheduled as notifications.
 118. **Bridge** (CR-020). The first tab (`/`) is the Dashboard, labelled "Bridge"; it replaces the HQ screen and keeps its company stats, ships on jobs, rest, shop, goals, loan and tutorial panels.
 119. **Your ship** (CR-020). The Dashboard leads with the avatar's assigned ship (the loaner during the tutorial): status, trip and cargo, fuel with the low-fuel warning, and the avatar's duty or rest.
 120. **Alerts** (CR-020). An Alerts panel, empty for now, where in-flight alerts and news will appear.
@@ -857,6 +866,12 @@ Steps 20.1–20.4 are specified in `memory-bank/change-requests/CR-020-bridge-da
 
 ---
 
+## Phase 20 — Independent Pilots (CR-020)
+
+Steps 20.1–20.9 are specified in `memory-bank/change-requests/CR-020-independent-pilots.md` §5 (written there as 19.1–19.9), with its §6 amendments. Stop for review at the end.
+
+---
+
 ## Definition of Done (Base Game)
 
 - All step tests pass in CI.

memory-bank/progress.md

@@ -457,3 +457,17 @@ Spec: `memory-bank/change-requests/CR-020-bridge-dashboard.md`. New decisions re
 - [x] **Step 20.4 — Regression and review.** CR-020 amendments added to plan Step 8.1 and CR-005 Step 10E.4. The e2e `playToDeal` now waits for the "Dashboard" heading. With eight tabs the desktop rail cut off Places in a 720 px-tall window (first screenshot), so rail tabs are more compact (`md:size-11`, `md:py-1.5`) and the rail scrolls if a window is shorter still. Full suite: typecheck, lint, 1341 unit tests and 9 e2e tests pass. Screenshots (taken after the deal with one ship on a job): `docs/screenshots/20-4-bridge-desktop.png`, `20-4-bridge-phone.png`, `20-4-hqs-desktop.png`, `20-4-hqs-phone.png`.
 
 **Phase 20 is complete; stopped for review.**
+
+## Phase 20 — Independent Pilots (CR-020)
+
+Spec: `memory-bank/change-requests/CR-020-independent-pilots.md` (received as "CR-019 … Phase 19"). New decisions recorded as plan §0.5.118–0.5.126.
+
+- [ ] Step 20.1 — Content and config
+- [ ] Step 20.2 — Sim: eligibility and job choice
+- [ ] Step 20.3 — Engine: Dispatch Office, modes, orders
+- [ ] Step 20.4 — Engine: event-queue catch-up
+- [ ] Step 20.5 — Engine: live play
+- [ ] Step 20.6 — Client: Dispatch Office and pilot controls
+- [ ] Step 20.7 — Client: board and logbook
+- [ ] Step 20.8 — Balance
+- [ ] Step 20.9 — Plan amendments and regression