deadhead-space-freight-tycoon/memory-bank/change-requests/CR-004-pilot-duty-rest.md

# Change Request CR-004 — Pilot Duty and Rest

**Project:** Deadhead: Space Freight Tycoon
**Applies to:** a build with Phases 1–10, CR-001, CR-002, and CR-003 complete
**Do this:** as **Phase 10D**, after Phase 10C and before Phase 11
**Related docs:** `implementation-plan.md`, `change-request-faster-start.md`, `change-request-open-markets.md`, `change-request-map-art.md`, `DECISIONS.md`

> **Numbering note (added when implemented):** the plan's §0.5 already uses 34–41. This CR's decisions 0.5.34–0.5.38 are recorded as **0.5.42 Duty clock**, **0.5.43 Duty limit**, **0.5.44 Finish the job**, **0.5.45 Rest** and **0.5.46 Rest covers a board refresh**. The error code `pilot_resting` is `pilot-resting` (the API's kebab-case convention).

---

## 1. Why

Pilots can currently fly back-to-back forever, so there is no rhythm and no reason to run more than one pilot per ship. When a location's board has nothing useful, the only options are to wait with nothing to show for it or to deadhead.

This adds an ATS-style hours-of-service rule:

- Each pilot has a **duty clock** that fills up as they fly.
- When it's full, the pilot must **rest** for a fixed time on arrival. The ship stays put unless another pilot takes it.
- The player can also **rest a pilot early**. Rest always lasts at least one contract board period, so **a rested pilot always wakes up to a fresh board.**
- The **Long Haul** skill extends a pilot's duty limit, so leveling it changes the math, not just which jobs unlock.

## 2. How it works

| Rule | Detail |
|---|---|
| Duty clock | Each pilot tracks duty hours (game hours flown since their last rest). |
| What counts | Every contract and deadhead trip adds its full travel time. Tutorial runs do not count. |
| Duty limit | Base limit from config, plus a bonus per Long Haul level. |
| Starting a trip | Allowed whenever the pilot is not resting, even if the trip will take them over the limit. Pilots always finish the job they're on. |
| Mandatory rest | If duty hours are at or over the limit when a trip resolves, rest starts automatically at the arrival time. |
| Voluntary rest | The player can rest any idle pilot who isn't in flight, at any duty level. |
| Rest | Lasts the configured rest duration. When it starts, duty hours reset to zero; the pilot can't fly until it ends. Rest happens wherever the pilot is; no bay is needed. |
| Crew swap | A resting pilot can be unassigned (at a bay, per decision 0.5.2), and a rested pilot can be assigned to the same ship. Rest blocks the pilot, not the ship. |
| Fresh board | The rest duration in real time is at least the contract board period, so any rest crosses at least one board refresh. |

Example with defaults (12-hour limit, 1 real minute = 1 game hour): a pilot flies three ~4-hour Moon runs, rests about 15 real minutes, and wakes to a new board. A Mars run (60+ game hours) always ends in a rest, which is negligible next to the trip itself.

## 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`.
- Rest is derived from stored timestamps, like dispatches. **No background job is needed to end a rest**: a pilot is resting if the current time is before their rest-ends-at time.
- Resetting the dev and test databases is fine. Schema migrations are still required.
- Update existing tests whose expectations change. Update `architecture.md` for schema or API changes and `progress.md` after every step.
- Stop for the user's review at the end of Phase 10D.

## 4. Decisions

Record these in `DECISIONS.md`.

- **0.5.34 Duty clock.** Pilots accrue duty hours equal to each trip's travel time in game hours, for contracts and deadheads. Tutorial runs accrue nothing.
- **0.5.35 Duty limit.** Base duty limit plus a per-level Long Haul bonus, both in config.
- **0.5.36 Finish the job.** Dispatch is blocked only while a pilot is resting. A trip that will exceed the limit is allowed; mandatory rest starts on arrival.
- **0.5.37 Rest.** Starting rest sets duty hours to zero and sets rest-ends-at to start time plus the rest duration. Mandatory rest starts at the trip's arrival time, so it is correct even if resolution happens later (offline).
- **0.5.38 Rest covers a board refresh.** The rest duration converted to real time must be at least the contract board period. This is enforced by a content test.

## 5. Steps — Phase 10D

### Step 10D.1 — Content config
- Add GameConfig fields: base duty limit (game hours, default 12), Long Haul duty bonus per level (game hours, default 2), rest duration (game hours; default equal to the board period converted to game hours).
- **Test:** Config validates. A test converts the rest duration to real time with the current compression and asserts it is at least the board period. Both duty numbers are positive.

### Step 10D.2 — Sim: duty and rest functions
- Add pure functions:
  - Duty limit for a pilot, from their Long Haul level.
  - Whether a pilot is resting at a given real time.
  - Duty hours after a trip (current duty plus trip travel time, unless it's a tutorial run).
  - Whether a pilot needs mandatory rest after a trip.
  - Rest window from a start time (rest-ends-at).
- **Test:** Duty limit rises by the bonus for each Long Haul level. A pilot is resting one second before rest-ends-at and not resting at it. A tutorial trip leaves duty unchanged. A pilot at 10 of 12 hours who flies a 4-hour trip needs rest; one at 4 of 12 who flies a 4-hour trip does not. For many random start times, a rest window always contains at least one contract board period boundary.

### Step 10D.3 — Sim: validation and resolution
- Dispatch validation gains a `pilot_resting` reason, checked before the other pilot checks.
- Dispatch resolution returns the pilot's new duty hours and, if mandatory rest applies, a rest-ends-at time computed from the arrival time.
- **Test:** A resting pilot fails validation with `pilot_resting`. A pilot whose duty is over the limit but not resting can still be dispatched. Resolving a trip that pushes duty over the limit returns duty zero and rest-ends-at equal to arrival time plus rest duration, even when resolved hours after arrival. Deadheads accrue duty; tutorial runs don't.

### Step 10D.4 — Schema and database
- Add to pilots: duty hours and rest-ends-at (nullable).
- Add the `pilot_resting` error code and a "rest pilot" endpoint to the route catalog.
- Player state shows, per pilot: duty hours, duty limit, resting (yes/no), and rest-ends-at.
- Dispatch summaries include a "rest started" note when a trip ended in mandatory rest.
- Update `architecture.md`.
- **Test:** Migrations run on a fresh database and are a no-op the second time. New and changed schemas accept valid examples and reject invalid ones. The route catalog test still passes.

### Step 10D.5 — Server: apply duty and rest
- Resolution (lazy and job-based) writes the pilot's new duty hours and rest-ends-at.
- The rest endpoint starts rest now for an idle pilot who is not in flight and not already resting. It works at any duty level.
- Dispatch returns `pilot_resting` for a resting pilot.
- Assigning and unassigning ignore rest (crew swaps are allowed); only flying is blocked.
- **Test:** A pilot who chains Moon runs until over the limit is resting after the last one resolves, and dispatch with them fails with `pilot_resting`. After the rest window passes, the same dispatch succeeds. Resting a pilot by hand sets duty zero and the correct rest-ends-at; resting an in-flight or already-resting pilot fails. A resting pilot can be unassigned at a bay, and a rested pilot assigned to that ship can dispatch immediately.

### Step 10D.6 — Client: pilot duty on the Pilots screen
- Each pilot shows a duty bar (hours used of limit). Resting pilots show "Resting" with a countdown instead.
- Idle, non-resting pilots have a "Rest now" action with a confirmation that says rest lasts at least one board refresh.
- **Test:** Component test: the duty bar matches state; a resting pilot shows the countdown and no Rest now action; Rest now calls the endpoint.

### Step 10D.7 — Client: duty in the dispatch flow
- In the dispatch sheet, pairs with a resting pilot are disabled with "Resting — mm:ss".
- For other pairs, show the pilot's duty after the trip. If it reaches the limit, show "Will need rest on arrival".
- **Test:** Component test: a resting pilot's pair is disabled with the countdown; a trip that takes a pilot over the limit shows the warning; one that doesn't, doesn't. Numbers match the sim.

### Step 10D.8 — Client: board refresh and the "nothing here" case
- Every contract board shows "New contracts in mm:ss" until the next board period.
- If a location has an idle ship but no contract that ship and its pilot are eligible for, show a short prompt with both options: "Rest [pilot] — wakes to a new board" and "Deadhead (fly empty)".
- **Test:** Component test: the countdown matches the next period boundary for the mocked time; with no eligible contracts, the prompt shows both actions and each calls the right endpoint or opens the deadhead picker.

### Step 10D.9 — Client: rest in summaries and on HQ
- The "while you were away" modal shows "Pilot X is resting until …" for trips that ended in mandatory rest.
- HQ shows the count of resting pilots and the next pilot to wake up, with a countdown.
- **Test:** Component test with seeded state: the modal line appears for a summary with rest started; HQ shows the correct count and the soonest wake time.

### Step 10D.10 — Plan amendments and regression
- Apply the amendments in §6 to `implementation-plan.md`.
- Run the full suite.
- **Test:** CI is green. Manual check: on a fresh account after the CR-001 deal, chain Moon runs with the avatar until mandatory rest starts; confirm the ship's location board shows a new set of contracts when the avatar wakes.

## 6. Amendments to `implementation-plan.md`

| Step | Change |
|---|---|
| 0.5 | Add decisions 0.5.34–0.5.38. |
| 2.1 | GameConfig gains duty limit, Long Haul duty bonus, and rest duration (10D.1). |
| 3.12 | Validation gains `pilot_resting` (10D.3). |
| 3.17 | Resolution returns duty hours and rest-ends-at (10D.3). |
| 5.3 | Pilots table gains duty hours and rest-ends-at (10D.4). |
| 9.5, 9.7 | Duty and rest in the dispatch sheet and Pilots screen (10D.6, 10D.7). |
| 12.1 | The simulated player follows rest rules: it rests a pilot when no eligible contract exists at its location and deadheading isn't better. Re-check all CR-001 timing targets with rest in place; adjust content values, not thresholds. Add a check that no pilot is ever dispatched while resting. |
| 12.6 | After leveling Long Haul, confirm the pilot's duty limit increased. |

## 7. Out of scope

Fatigue penalties, accidents, or slower flying when tired; rest facilities or bay amenities that shorten rest; pilot morale; and anything else in `implementation-plan.md` §0.3.