feat(tui): resolve the start-up session by asking the agent (ADR1 PR 2) - #23

…n 17) (#25)

* feat(agent): write a session file with its first message (plan decision 17)

A new session was a file from session/new on: a header and nothing else. A
user who started the TUI and left, left such a file behind. session/list
showed it as "(no messages)", and zypi --continue could take it for the
latest session.

session/new now makes a deferred session (DeferredJsonlSessionStorage, in
the harness). It keeps its entries in memory until the first message entry.
That entry writes the header, the entries held before it (a model choice, a
name, a leaf move) and itself in one go. After that each entry is appended
as before. The write comes before the entry is recorded, so a failed write
leaves no trace of the message and the next message tries again. A session
in which nobody typed has no file: nothing to list, load or continue.
Sessions that older versions left with no message keep the title
"(no messages)".

An id the client chose (--session-id) must stay taken while its session has
no file, so the agent keeps the ids of its open sessions in a set. The set
leaves an id when the session is closed or deleted, or when the session
could not be opened. Another process cannot see that set. So the first
prompt of a session with a chosen id looks for the id in the files once
more, and refuses it with the same error as session/new if a session has
saved under it since.

session/load and session/resume answer "not found" for a session that has no
file: there is nothing to load.

* test(tui): check the late session file at the TUI level (plan decision 17)

The agent now writes a session file with the first user message. Three
checks that drive the real pieces had to change with it:

- scripts/tui_pty/resume_matrix.py (zypi under a pseudo-terminal): the TUI
  makes a session at once, with no message, for `--session-id` and for
  `/new`. (A start with no flag makes none until the first message.) Two new
  cases leave such a session with no message and require that no session
  file exists. The first one comes first on purpose: under an agent that
  writes at once, its empty session is the newest one, so `--continue` and
  `--resume` with no argument take it and fail too. Two cases type a message
  and look for the file after it: `--session-id <fresh uuid>`, and `/new`
  and then a message. A case can have steps (`Step`). wait_for_run types the
  first one when the TUI is up (the model name on the border of the input
  box), and each next one when the screen shows that the one before took
  effect. The `/new` cases start with `--resume <id>`, so they do not depend
  on which session is the newest. scripts/tests/test_tui_pty.py tests the
  cases and wait_for_run with a fake terminal.
  Mutation check: with either of the two `repo.create` calls in agent.py
  made to write at once, the case for that call fails (and for the call that
  serves `--session-id`, the two cases that take the newest session fail too).
- scripts/tui_pty/smoke.py: after a restart, the /resume picker used to
  list the new empty session first and the script pressed Down to skip it.
  That session has no file now and is not listed, so the earlier session is
  the first row and the script no longer presses Down.
- python_agent_e2e.rs (the Rust ACP client against the real Python agent):
  the sessions that must be listed (51 for the paging test, the `existing`
  one for the id check) now get a first message. The id check also asserts
  what the agent does for a session that has no file yet: it refuses a
  second `session/new` with the same id (InvalidParams), and once the first
  message is sent the pager's own check finds the id through session/list.

No test is added or removed on the Rust side (the count of
python_agent_e2e stays 14).

* test(agent): close two gaps that a mutation run found (plan decision 17)

A run of 15 one-line changes to the production code of this PR, each
against the tests that watch it, found two that no test noticed:

- The header of a deferred session took its time from a second look at
  the clock and not from the time in the file name. The test compared the
  two, but both looks fell in the same millisecond, so it passed by
  chance. It now gives every look at the clock a new time.
- The second look at a chosen id (before the first message) also refused
  a session whose own file was there. No test sent a second message in a
  session with a chosen id. A new test sends three.

After the change, both are caught. The other 13 were caught before.

* docs: record plan decision 17 (the session file is written at the first message) and r14

- CHANGELOG.md, [Unreleased]: the agent writes the file of a session with
  its first message. It lists the behaviour changes (no flag: no session
  until the first message; `--session-id` and `/new`: a session at once,
  with no file; a chosen id stays reserved while its session is open),
  what library users get (`JsonlSessionRepo.create({"deferred": True})`),
  and the tests. The entry for the cost of paging says it is left as it is.
- The embedded user guide (17-sessions.md), packages/pi-agent-cli/AGENTS.md
  and docs/DESIGN.md section 6.1: a session in which nobody typed has no
  file, so it is not listed and cannot be loaded.
- scripts/tui_pty/README.md (16 cases) and docs/baselines/tui.md.
- The plan (r14): the status, the answers to the four questions (#23 and
  #24 merged, decision 18 not done, decision 17 done, decision 10 to do),
  and the index of section 10.
- The execution log: section 10.17 (the merges, the design of decision 17,
  what each ACP method does for a session without a file, the facts about
  the TUI, the tests, two mutation runs and the two gaps they found, the
  numbers, what is not verified), B.9 (how to repeat it) and the revision
  record. One old line (about the empty first row of the /resume picker)
  points to section 10.17.