[codex] Allow Timeline advance to reveal obtained epochs

[CompleteDotTech]

Summary

Fixes #92.

This PR resolves the remaining Timeline automation gap after the earlier Timeline safety guard. The main-menu timeline action still refuses to enter unsafe pending-unlock states, but once the game is already on menu_screen: "timeline", menu_select with option: "advance" can now complete the safe reveal flow for visible obtained epoch slots.

Problem

Current behavior can strand agents after an epoch unlock:

{
  "state_type": "menu",
  "menu_screen": "timeline",
  "options": [
    { "name": "advance", "enabled": true },
    { "name": "back", "enabled": true }
  ],
  "obtained_unrevealed_count": 1
}

Before this change, calling:

{ "action": "menu_select", "option": "advance" }

could still return manual_action_required: true and leave the agent stuck even though the normal Timeline UI had a visible revealable epoch slot.

What Changed

• Added TryRevealVisibleTimelineEpoch for the already-open Timeline advance path.
• The helper finds spawned, visible NEpochSlot controls whose state is EpochSlotState.Obtained and whose model id matches a pending Obtained epoch.
• It invokes ForceClick() on the slot, preserving the game's own NEpochSlot.OnRelease() path:
  • reveal epoch
  • persist SaveManager.Instance.RevealEpoch(model.Id)
  • open the normal epoch inspect screen/animation
• It returns retry: true while no matching visible slot has spawned yet.
• It now splits Obtained from ObtainedNoSlot so no-slot epochs do not retry forever.
• ObtainedNoSlot without a queued expansion or visible slot returns manual_action_required: true and done: true.
• Main-menu Timeline entry remains guarded, so this does not reintroduce the invalid unlock-state path avoided by the earlier Timeline PR.

Documentation

Updated:

• docs/raw-full.md
• docs/raw-simplified.md
• mcp/server.py tool docstring

The docs now describe:

• safe advance behavior on an already-open Timeline screen
• retry responses while the Timeline UI is still spawning/animating
• the remaining ObtainedNoSlot manual-action limit
• the unchanged main-menu Timeline guard

Review Flow

A review PR was opened first on the fork as requested:

• [codex] Allow Timeline advance to reveal obtained epochs CompleteDotTech/STS2MCP#7

Automated review feedback was addressed before opening this upstream PR:

• Added a null-safe slot.model?.Id check before matching pending epoch ids.
• Split ObtainedNoSlot handling out of visible-slot automation to avoid indefinite retry responses.
• Resolved both review threads on [codex] Allow Timeline advance to reveal obtained epochs CompleteDotTech/STS2MCP#7.

Validation

Build validation on the upstream-based branch:

dotnet build \\wsl.localhost\Ubuntu\tmp\sts2mcp-timeline-reveal\STS2_MCP.csproj -p:STS2GameDir="C:\Program Files (x86)\Steam\steamapps\common\Slay the Spire 2"
Build succeeded. 0 Warning(s), 0 Error(s).

Release build/install validation:

.\build.ps1 -GameDir "C:\Program Files (x86)\Steam\steamapps\common\Slay the Spire 2"
Build succeeded. 0 Warning(s), 0 Error(s).

Live game validation against STS2 v0.103.2:

Initial Timeline state after entering via the manual gate:

{
  "state_type": "menu",
  "menu_screen": "timeline",
  "obtained_unrevealed_count": 1,
  "epochs": [
    {
      "id": "IRONCLAD5_EPOCH",
      "state": "Obtained"
    }
  ]
}

Reveal action:

{ "action": "menu_select", "option": "advance" }

Response:

{
  "status": "ok",
  "message": "Revealing timeline epoch IRONCLAD5_EPOCH",
  "pending_epoch_ids": ["IRONCLAD5_EPOCH"],
  "revealed_epoch_id": "IRONCLAD5_EPOCH"
}

Follow-up state:

{
  "state_type": "menu",
  "menu_screen": "timeline",
  "obtained_unrevealed_count": 0,
  "revealed_count": 7,
  "epochs": [
    {
      "id": "IRONCLAD5_EPOCH",
      "state": "Revealed"
    }
  ]
}

Full Timeline completion was also verified instead of stopping at the state flip:

{
  "status": "ok",
  "message": "Closed epoch inspect screen"
}

then:

{
  "status": "ok",
  "message": "No more epochs to advance",
  "done": true
}

Final Timeline state remained obtained_unrevealed_count: 0.

Risk

The risky main-menu path remains blocked. The new automation only acts after Timeline is already open and only clicks spawned visible obtained slots that match pending Obtained progress entries. States that cannot produce a visible slot return a non-retry manual-action response.

[CompleteDotTech]

@codex review

@gemini-code-assist review

The romgenie review PR feedback has been addressed and its review threads are resolved. Please review the upstream PR against the final branch state.

[Gennadiyev]

I'm kinda tempted to merge your pull request without my own testing cuz I have no timeline unlocks at hand xD

I will test everything out before releasing. Need a bit more time for that.

[CompleteDotTech]

This functionality isn't great, I believe I solved it before (I should look at my previous solution).