@@ -51,7 +51,7 @@ are references. Extract ideas, do not port code.
5151 - Module boundaries (names may change, boundaries may not move):
5252 - `cli` — argument parsing, mode selection, process wiring.
5353 - `config` — load, validate, merge, resolve config; build `pi-ai` models.
54- - `session` — append-only JSONL store; projection to a `pi-ai` `Context`.
54+ - `session` — append-only JSONL store of `pi-ai` `Message`s.
5555 - `agent` — streaming loop, tool dispatch, pause/cancel state. No UI, no
5656 provider-specific code.
5757 - `tools` — `edit`, `bash` runners. No UI.
@@ -129,8 +129,8 @@ Decisions:
129129 ## Session persistence
130130
131131 `pi-ai` ships no session store. The session layer is a thin append-only JSONL
132-wrapper over `pi-ai`'s own `Context`/`Message` types. Never invent a parallel
133-message model.
132+wrapper around `pi-ai`'s own `Message` type. Never invent a parallel message
133+model.
134134
135135 One JSON object per line; never rewrite or delete committed lines. Records:
136136
@@ -162,11 +162,11 @@ Directory and file layout:
162162 - Append with `writeSync` + `fsyncSync` so committed lines survive a crash. A
163163 persistence failure stops the turn; never continue with unrecorded side
164164 effects.
165-- On read, tolerate a truncated final line; reject corruption in committed
166- history.
167-- Preserve message order and tool-call ↔ tool-result relationships. If partials
168- are ever persisted, use `AssistantMessageFrameEncoder` /
169- `reduceAssistantMessageFrames`, not a custom frame format.
165+- Preserve message order and tool-call ↔ tool-result relationships.
166+- Reading sessions back is deferred; when it is added, tolerate a truncated
167+ final line, reject corruption in committed history, and use `pi-ai`'s
168+ `AssistantMessageFrameEncoder` / `reduceAssistantMessageFrames` rather than a
169+ custom frame format.
170170
171171 ## Agent loop
172172
@@ -177,7 +177,7 @@ each result, and repeat. Stop when the assistant produces no tool calls, on
177177 cancel, or on a surfaced error.
178178
179179 Phases: `preparing`, `waitingModel`, `streaming`, `runningTool`, `pausing`,
180-`idle` (plus `cancelled` reachable from active states). Events: `phase`, `text`,
180+`idle`; a turn may be cancelled from any active phase. Events: `phase`, `text`,
181181 `reasoning`, `toolCall`, `toolOutput`, `toolResult`, `message`, `error`,
182182 `cancelled`, `complete`.
183183
@@ -218,7 +218,7 @@ then agent files (when `discoverAgentFiles`).
218218
219219 - Agent files: load `AGENTS.md` and `CLAUDE.md` from `~/.agents/` and the project
220220 root (`process.cwd()`), trimmed, each under a heading naming its path.
221-- Skills: scan each `skillsDirs` entry for `<dir>/SKILL.md`, read its
221+- Skills: scan each `skillsDirs` entry for `<dir>/<name>/SKILL.md`, read its
222222 frontmatter (`name`, `description`), and advertise the absolute path so the
223223 model can read it with `bash` on demand. Progressive disclosure only — never
224224 inline skill bodies. No directories means no skills; there is no implicit
@@ -238,9 +238,18 @@ Two regions:
238238 redrawn. User turns, assistant text, tool calls, and tool results go here. The
239239 terminal owns scrollback, selection, and scrolling.
240240 - **Live region** — at most the height of the terminal minus one row, holding
241- the in-flight line (the current incomplete line of whichever stream is
242- active), a one-row phase status, and the editor. Only this region is redrawn.
243- When idle it holds the editor alone: no in-flight line, no status row.
241+ a one-row context-usage readout, the in-flight line (the current incomplete
242+ line of whichever stream is active), a one-row phase status, and the editor,
243+ in that order. Only this region is redrawn. When idle it holds the context
244+ readout and the editor: no in-flight line, no status row.
245+
246+The context readout is always present, including idle, and is display-only: it
247+estimates the tokens the next request would send against `model.contextWindow`
248+and is never persisted. Anchor on the last `AssistantMessage.usage` — the prompt
249+that was sent is `totalTokens - output` — and estimate the anchor message and
250+everything after it; fall back to a ~1 token per 4 characters estimate of the
251+whole context. Emphasize as it approaches the window, and mark it full when
252+`used + model.maxTokens` would exceed it.
244253
245254 Scrollback is append-only and written before the live region is redrawn, never
246255 after. Blocks — a user turn, a tool call with its result body, a terminal-state
@@ -279,7 +288,7 @@ machine with a short timeout to distinguish a lone ESC from a sequence.
279288 - **CTRL+C = cancel the turn completely.** Abort the model request via
280289 `AbortSignal` and terminate the running tool's process group. Persist the
281290 aborted assistant message (`stopReason: "aborted"`). Return to idle; do not
282- undo completed side effects.
291+ undo completed side effects. When idle, it clears a non-empty draft instead.
283292 - **CTRL+D = exit**, only when the input is empty. Flush the session, restore the
284293 terminal, exit cleanly.
285294 - No max turns, tool-call budget, or automatic stop.
@@ -302,16 +311,19 @@ Accepted spellings: `-p <prompt>`, `--print <prompt>`, `-p=<prompt>`,
302311
303312 - Persistence failure stops the turn.
304313 - Surface provider errors with their message; do not mask, summarize, or retry.
305-- Local diagnostics only. No remote telemetry. Debug output goes to stderr
306- behind an explicit flag; redact secrets and prompt/tool content by default.
314+- Local diagnostics only. No remote telemetry. Any debug output would go to
315+ stderr behind an explicit flag; redact secrets and prompt/tool content by
316+ default.
307317 - No hidden stalls: every wait (model request, tool, pause) has a visible state
308- in the TUI and a diagnostic path in headless mode.
318+ in the TUI; in headless mode tool calls, tool output, errors, and
319+ cancellation are written to stderr.
309320
310321 ## Scope boundaries
311322
312323 Deferred, not rejected. Do not build unless explicitly promoted:
313324
314325 - context compaction / summarization / masking;
326+- reading or resuming sessions (the JSONL log is write-only today);
315327 - prompt templates;
316328 - custom agents / subagents / delegation;
317329 - an extension or plugin system;
@@ -330,9 +342,9 @@ Deferred, not rejected. Do not build unless explicitly promoted:
330342 code.
331343 - Prefer plain functions and objects over classes; keep exports minimal; define
332344 helpers near their use.
333-- Validate untrusted input once at the boundary (config, session records, tool
334- args) with Typebox, then keep internal code plain-typed. Do not spread
335- schema-derived types everywhere.
345+- Validate untrusted input once at the boundary (config, tool args) with
346+ Typebox, then keep internal code plain-typed. Do not spread schema-derived
347+ types everywhere.
336348 - Ask before adding a dependency. `diff` and `typebox` are approved;
337349 supply-chain risk is a real constraint.
338350 - Do not add tests unless explicitly asked. Verify manually.