fix(pi): use stdout session header (#126)

docs/reference/runners/pi/runner.md

@@ -10,7 +10,7 @@ Provide the **`pi`** engine backend so Takopi can:
 
 * Run Pi non-interactively via the **pi CLI** (`pi --print`).
 * Stream progress by parsing **`--mode json`** (newline-delimited JSON). Each line is a JSON object.
-* Support resumable sessions via **`--session <path>`** (Takopi emits a canonical resume line the user can reply with).
+* Support resumable sessions via **`--session <token>`** (Takopi emits a canonical resume line the user can reply with).
 
 ### Non-goals (v1)
 
@@ -36,10 +36,10 @@ Takopi appends a **single backticked** resume line at the end of the message, li
 
 Notes:
 
-* `pi --resume/-r` opens an interactive session picker, so Takopi uses `--session <path>` instead.
-* The resume token is the **session id** (short prefix), derived from the first JSON
-  object in the session file. If the id cannot be read, Takopi falls back to the
-  session file path.
+* `pi --resume/-r` opens an interactive session picker, so Takopi uses `--session <token>` instead.
+* The resume token is the **session id** (short prefix), derived from the session
+  header line (`{"type":"session", ...}`) emitted to stdout in `--mode json`.
+  This requires **pi-coding-agent >= 0.45.1**.
 * If the path contains spaces, the runner will quote it.
 
 ### Non-interactive runs
@@ -91,7 +91,7 @@ The runner should launch Pi in headless JSON mode:
 pi --print --mode json --session <session.jsonl> <prompt>
 ```
 
-When resuming, `<session.jsonl>` is the resume token extracted from the chat.
+When resuming, `<session.jsonl>` is replaced by the resume token extracted from the chat.
 
 #### Event translation
 
@@ -116,6 +116,8 @@ Install the CLI globally:
 npm install -g @mariozechner/pi-coding-agent
 ```
 
+Minimum supported pi version: **0.45.1**.
+
 Auth is stored under `~/.pi/agent/auth.json`. Run `pi` once interactively to
 set up credentials before using Takopi.
 

docs/reference/runners/pi/stream-json-cheatsheet.md

@@ -6,6 +6,12 @@ required `type` field. These are `AgentSessionEvent` objects from
 
 ## Top-level event lines
 
+### `session` (header, pi >= 0.45.1)
+
+```json
+{"type":"session","id":"ccd569e0-4e1b-4c7d-a981-637ed4107310","version":3,"timestamp":"2026-01-13T00:33:34.702Z","cwd":"/repo"}
+```
+
 ### `agent_start`
 
 ```json

docs/reference/runners/pi/takopi-events.md

@@ -33,12 +33,13 @@ Notes:
 `pi --session <id>`
 ```
 
-The token is the **short session id**, derived from the first JSON object in the
-session file. If the id cannot be read, Takopi falls back to the session file path.
+The token is the **short session id**, derived from the session header line
+(`{"type":"session", ...}`) emitted on stdout when running in `--mode json`.
+This requires **pi-coding-agent >= 0.45.1**.
 
 Why not `--resume`?
 - `--resume/-r` opens an interactive session picker; it does not accept a
-  session token. Takopi must use `--session <path>` instead.
+  session token. Takopi must use `--session <token>` instead.
 
 ---
 
@@ -47,8 +48,9 @@ Why not `--resume`?
 Takopi requires **serialization per session token**:
 
 - For new runs (`resume=None`), do **not** acquire a lock until a `started`
-  event is emitted (Takopi emits this as soon as the first JSON event arrives).
-- Once the session is known, acquire a lock for `pi:<session_path>` and hold it
+  event is emitted (Takopi emits this as soon as the session header or first
+  JSON event arrives).
+- Once the session is known, acquire a lock for `pi:<session_token>` and hold it
   until the run completes.
 - For resumed runs, acquire the lock immediately on entry.
 
@@ -103,7 +105,7 @@ Mapping:
   - `ok = true` unless the last assistant message has `stopReason` `error` or `aborted`.
   - `answer = last assistant text` (from `message_end` or `agent_end.messages`).
   - `error = errorMessage` if present.
-  - `resume = ResumeToken(engine="pi", value=session_path)`.
+  - `resume = ResumeToken(engine="pi", value=session_token)`.
   - `usage = last assistant usage`.
 
 ### 4.5 Other events