# The state file — `sessions.tsv`, line by line

What agliteterm writes to restore itself from, field by field, so a file can be read, hand-edited or
seeded by a test without reading `saveSessionState()` / `parseStateFile()` in `src/main.cpp`.
[Session restore](session-restore.md) is the user-facing half (where the file is, the `.bak`
generation, how to recover by hand); this is the format.

Path: `%LOCALAPPDATA%\agliteterm\sessions.tsv` for the default instance, `sessions-<instance>.tsv`
for a `--pipe <instance>` window. One file per window process. Tab-separated UTF-8 text, `\n`
line ends (`\r` is tolerated on read), no BOM. A field never contains a tab, a newline or a carriage
return. Ordinary line types replace each with a space (`tsvField`). P9's `R`/`B` and P10b's `K2` command fields
instead use JSON string-content escapes, without the surrounding quotes: `\\`, `\"`, `\t`,
`\r`, `\n`, and `\u00XX` preserve the command exactly. An empty command field means none.
Malformed escaped command fields are dropped with a warning. `C` still uses line absence for none.

## Line types, in the order they are written

| Line | Fields | Meaning |
| --- | --- | --- |
| `V1` | — | The header. Always first. The number has never changed: the format grows by adding line types, not by bumping it. |
| `W` | `name` | One workspace, in tree order. The first `W` is workspace `0`. |
| `S` | `ws` `name` `app` `cwd` `arg`… | One visible session, in tree order. `ws` indexes the `W` lines; `name` is empty when the session was never named (it shows as `session N`); `app`, `cwd` and the args are the **launch spec** — what is relaunched, never what was running inside. `cwd` is the shell's *live* directory when it was readable and fits the pty-host's 260-byte field, the creation directory otherwise. |
| `F` | `i`… | The indices, among the `S` lines, of the flagged sessions. Absent when none. |
| `E` | `i`… | The indices, among the `S` lines, of sessions whose **empty** argument list is exact: a `session new --command-mode direct` launch of a program with no arguments (#79). Without it an empty argument list means "no arguments given", and a PowerShell app relaunches with its usual `-NoLogo -NoExit -EncodedCommand` wrapper. A non-empty argument list is always relaunched exactly, so it is never listed. Absent when none; older builds skip it. |
| `D` | `id`… | The pty-host id of every `S` line's **shell** (the session's `paneId`), in order. Lets a relaunch after a kill **adopt** a shell the host still holds instead of starting a new one. It is the session id too, except for a session promoted after its own shell closed (P4): that one kept the closed shell's id as its session id, and the adopting relaunch brings it back under its shell's id — the file records shells, not promotions. Absent in files from before 0.17.x builds that wrote it; the count must equal the `S` count or the whole line is ignored. |
| `C` | `i` `text` | The **context** of the session at `S` index `i` (parity batch P3, `session context`). One line per session that has one; no line for a session without one, because an empty field could not tell "no context" from a context that is empty. Written after `D`, before `P`. |
| `P` | `owner` `app` `cwd` `arg`… | The **split shell** of the session at `S` index `owner`: its own launch spec. One line per session that has a split. |
| `L` | `owner` `axis` `order` | The **layout** of the split of the session at `S` index `owner` (parity batch P4): `axis` is `vertical` (left/right panes) or `horizontal` (top/bottom panes) — the arrangement of the panes, never the divider, case-sensitive; `order` is `0` when the session's own shell sits in slot 0 (left/top) or `1` after a `session swap` put it in slot 1. Written **only when the layout is not the default** (horizontal, or swapped, or both), so a vertical unswapped split writes the exact bytes 0.17.14 wrote, and only for a session whose `P` line exists — the layout describes the pair. Written after the `P` lines, before `K`, by the same convention as `K`. **Downgrade**: an older build ignores `L` (unknown line types are ignored) and restores the split in the default layout — the `P` line is untouched, so a downgrade loses the layout, not the split — and drops the line on its next save. On load each field is validated on its own: an `axis` other than the two words restores `vertical`, an `order` other than `0` / `1` restores `0`, each named in the log; an `L` for an owner with no `P` line is dropped and named. |
| `G` | `owner` `ratio` | P9 split slot 0's share, written with three decimals only when not 0.5, with the layout lines. Valid range 0.05..0.95; a bad value restores 0.5 with a warning. Requires a valid split. A swap preserves slot shares. |
| `K` | `i` `pane0` `pane1` | The **captured commands** of the session at `S` index `i` (parity batch P3, `restore capture`): `pane0` is the slot of the session's own shell, `pane1` the slot of its split shell (empty when there is no split, or nothing was captured there). An empty field is "none"; a slot is a plain string with no rules of its own, so unlike `C` one line carries both panes. One line per session with at least one slot. **The fields are by ROLE, not by position on screen**: `pane0` is always the session's own shell and `pane1` always the split shell, whatever slot each sits in — the `L` line carries the order, `K` does not repeat it. After a promotion (the session's own shell closed, the split shell became the session) the survivor's slot is `pane0`, because it is the session's own shell now. Written after the `P` lines by convention — `K` sits with the `P` lines it describes — not by requirement: the reader collects every line type in file order and applies them in its own fixed order, so a `K` above a `P` restores identically. A slot is a checkpoint a caller reads back (`tree --json`, `capturedCommands`); P10b may replay it only when `restore-commands` is enabled (default false). The writers are `restore capture` and, when `restore-commands` is enabled, **the close itself**: OnDestroy captures every real pane while its shell is still alive, before the final save, so the checkpoint describes the moment the window went away (agwinterm's `SaveState(captureCommands: true)`). Malformed owner indices are refused, never coerced to zero. |
| `K2` | `i` `pane0` `pane1` | P10b lossless captured slots, with the same roles and owner guards as K. Written instead of K when either capture contains a tab, CR or LF; both fields then use the R/B JSON-content codec. Older builds ignore K2 and drop those captures on their next save; ordinary captures retain legacy K. |
| `R` | `i` `pane0` `pane1` | Explicit restore pins, by ROLE like K, using escaped command fields. Written after K when either shell has a pin. Tree reads them as `restoreCommands`, keyed by pane id. |
| `B` | `i` `agent0` `agent1` | Replay bindings, by ROLE like R; binding wins over pin. Escaped command fields preserve case and command bytes; not exposed in the tree. |
| `A` | `ws` | The active workspace. Clamped on load to the workspaces the file has. |
| `O` | `ws` | The focused workspace. Read when present; this build does not write it. |

A file written by the current build, one workspace, two sessions, the first with a context, a split
stacked top/bottom and swapped (its own shell in the bottom slot), and a captured command in each
pane:

```
V1
W	main
S	0	build	pwsh.exe	C:\src\app
S	0		pwsh.exe	C:\src
F	0
D	a1b2c3d4-…	e5f6a7b8-…
C	0	reviewing the P3 diff
P	0	pwsh.exe	C:\src\app\tests
L	0	horizontal	1
K	0	npm test	ping -n 3 127.0.0.1
A	0
```

The same file with the split left/right and unswapped has no `L` line at all — byte for byte what
the build before P4 wrote.

## The rules the reader applies

P9 `R`/`B` fields follow K's positional guards: a malformed S set drops them; a missing rebuilt
split drops its pane-1 field, not the owner's field. `G` follows L's split/owner guards.
Older builds ignore R/B/G and restore without pins, bindings or custom ratios; their next save
drops those lines. No migration changes older line types. Read-only and search state are not saved.

Only a fresh restored shell receives replay: one 2500 ms timer resolves each queued pane id to its
current binding, otherwise its current pin, otherwise its captured K/K2 slot only when
`restore-commands` is enabled, then writes outside the state lock. It is a delay, not a readiness
guarantee. Adopted/exited/gone/read-only panes are skipped. Changes before the timer fires are
honored. Captured replay defaults off; explicit pins and bindings do not depend on that setting.

- **Unknown line types are ignored**, and the lines it knows are honoured. That is what lets an
  older build read a newer file (it restores the sessions and drops what it cannot carry — and
  writes the file back without those lines on its next save, so a downgrade loses contexts, splits,
  slots and layouts, not sessions; a build before P4 reads an `L`-carrying file and restores the
  split left/right, unswapped) and a newer build read an older one (a file from before P3 has no
  `C` or `K`, one from before P4 no `L`, and each restores exactly as it did). Nothing migrates in
  either direction.
- **A malformed `S` line still counts.** `C`, `P`, `L`, `K` and `D` index sessions by *position* among
  the `S` lines, so a session line the reader could not parse shifts every index after it. Rather
  than hang a context, a split, a layout or a slot on the wrong session, each of those sets is
  refused **wholesale** when the number of `S` lines differs from the number that parsed, with one
  `logWarn` naming both counts (`state: 2 session line(s) but 1 parsed - refusing 1 context line(s)
  rather than attaching them to the wrong sessions`). Every parseable session still restores.
- **An `L` line needs its pair.** The layout is applied onto the split the matching `P` line
  rebuilds; an `L` whose owner has no `P` line (`state: layout line for session index 0 has no split
  (P) line to describe - dropped`), or whose split failed to start (`restore: layout for session 'x'
  dropped - its split was not restored`), is dropped and named. A bad `axis` word or `order` digit
  loses that one field to its default (`vertical` / `0`), named in the log, never the line.
- **An index past the `S` list** (a hand-shortened file) drops that one line, named in the log; the
  sessions it does not name are untouched.
- **A loaded context goes through the verb's own rules** — trimmed, not blank, no control character,
  at most 200 characters. One that fails is dropped on load with one `logWarn` naming the session
  and the refusal (`restore: context for session 'x' dropped - session context: control character
  U+0001 at offset 3 …`); the session restores without it and nothing is drawn.
- **A `K` slot lands on the session the restore creates**: `pane0` on the session, `pane1` on the
  split the matching `P` line rebuilds. When that split did not come back — the split failed to
  start, the owner session itself failed to start (a dead entry gets no split, so its `P` line is
  never attempted), or the `K` line names a split the file has no `P` line for (a hand-edited or
  downgrade-written file) — the `pane1` slot has no pane to belong to and is dropped with a
  `logWarn` naming the session. (A `P` set refused by the count guard takes the `K` set with it —
  the same comparison — so that case never reaches the per-session drop.) A session whose app failed to start keeps its `pane0` slot the way it
  keeps its name, and re-saves both.
- **`.tmp`, then rename, one `.bak`.** The save writes `sessions.tsv.tmp`, rotates the current file
  to `sessions.tsv.bak` and renames the temp over the target. A zero-session save over a populated
  file is refused (the log says so); the one legitimate empty is the user closing the last session.
  Any thread may save — a dedicated saver thread that every tree change wakes (it lets a burst
  settle for 200 ms and saves once), the UI thread at quit, the control-pipe thread after `restore
  capture` so the verb's reply describes a file that already exists — serialised by one lock around
  the write and the rename. A tree change never writes the file on the UI thread: one rename held
  by an endpoint-security filter used to hang the window, keystrokes included, for as long as the
  filter took. The verbs whose reply claims durability (`session resize`, `session restore` /
  `bind`, `restore capture`, `workspace move`, `restore clear`, claude adopt / restart) still save
  synchronously, some on the UI thread, so one of those calls can still wait on the filter — a
  click or a keystroke cannot. A save whose bytes equal the last published ones is skipped while
  that file is still on disk (the skip advances the stamp fence exactly as a write would), so the
  log's `save ok` lines record changes, not repaints; a missing primary is written again from the
  same bytes.
- **Restore order**: `sessions.tsv`, then `.bak` when the primary is missing, empty or parses to no
  sessions, then a fresh window.

`test/restore-matrix.ps1` seeds these files byte for byte and asserts the branches above (a
control character in a `C` line, a `C`/`P`/`L`/`K` count mismatch, a stray index, a pre-P3 file, an
`L` with a bad axis word or order, an `L` without its `P`, a default split writing no `L`, a
truncated write, a `.bak` fallback, a future line type) and restarts a horizontal and a swapped
split, gracefully and killed; `test/control-honesty.ps1` reads the `C` and `K` lines back after
each verb.