Proposal: optional sub-states under Needs you, placed by turn check #213

Problem

"Needs you" on the Agent Dashboard mixes two different asks:

• The agent needs you to clarify, give direction, approve, or choose how to approach something.
• The agent needs you to do a task it can't do itself, such as fetching a credential from another service or changing something in a UI it can't reach.

You can't tell which is which without opening each card, and they call for different moments in a day: one takes a few seconds to answer, the other takes you away from the keyboard.

Proposal

Optional sub-states under Needs you, which you configure and turn check places sessions into. A set of two would replace the Needs you column with two amber columns: Needs a decision and Needs you to act.

• Additive field. agent_state doesn't change. A waiting session is still waiting, so every send, wait, notification and plugin that reads it behaves as it does now. An optional agent_sub_state on the session names the sub-state, and older clients ignore it.
• Default unchanged. With no sub-states configured, which is the default, the board, the API output and turn check's requests stay as they are today. The classifier request is byte-identical, and the existing replay fixtures pass without re-recording.
• The base verdict still decides. Turn check alone says whether a session is in Needs you. Sub-state descriptions can't move a session in or out of it, and anything that can't be placed goes to the first column with a small "not sorted" tag.
• No extra calls unless you opt in. End-of-turn sorting shares turn check's existing request. Mid-turn question forms get one extra call on the question text, only with sub-states configured and turn check on. That is a new data flow to the turn check provider, with the same secret redaction as a turn, and the docs will say so.
• Manageable by agents. The set can be edited through a new /v1/substates route, berthd/berth commands and MCP, with length limits, a before: hook and an event, like turn check's. The provider, keys and the rest of /v1/turncheck stay closed to local callers.
• Kept in sync. Each box stores its own copy with a revision. The app spreads the newest to every box it can reach, gated on a capability in GET /v1/info. An older berthd shows as outdated and keeps today's behaviour.

Removing every sub-state restores the plain column on the spot.

What I measured

On 51 real past asks, labelled by hand before any classifier call, a candidate prompt on Jev placed 47 correctly (92%). 45 of the 47 it was confident about were right, and the other 4 would show as "not sorted".

I'm building this now as one PR, and will link it here. If the shape is wrong for the project, or you'd want it split or trimmed, please say so here.