pi-retrospect 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 nietaki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# pi-retrospect
+
+A [Pi](https://github.com/earendil-works/pi) package that gives an agent tools for
+exploring past Pi sessions and the messages they contain — the read side of harness
+self-improvement. An agent that can look back over its own previous sessions can find
+the conversation where it hit a given error, recover a decision it made, and audit
+what actually happened before repeating it.
+
+**Status: 0.x, early.** One operation is implemented — `listSessions` (see
+[`docs/tool-api.md`](docs/tool-api.md) for its contract), registered as one
+codemode-callable tool. Exploring the *messages* inside a session is not built yet;
+that product scope stays open until it is discussed.
+
+## Install
+
+```sh
+pi install npm:pi-retrospect
+```
+
+Or try it for a single invocation without adding it to settings:
+
+```sh
+pi -e npm:pi-retrospect
+```
+
+`pi list` shows configured packages, `pi remove pi-retrospect` removes it.
+
+**Requires Pi 0.99.0 or newer.** The tool registration uses `exposure`, `annotations`,
+and `outputSchema`, which were added in Pi 0.99.0 (2026-09-29). Verified against
+0.99.2 and 1.0.0. The peer ranges stay `"*"` because that is the convention Pi
+prescribes for host-provided packages — Pi does not resolve them for managed installs,
+so the minimum is stated here rather than in `package.json`.
+
+## Using it
+
+The registered tool is `list_sessions`. It walks the Pi sessions root, reads only
+each file's header line, and returns session metadata — id, absolute path, absolute
+`cwd`, timestamp, fork lineage (`parentSessionPath`) — with subagent transcripts
+nested under the session that launched them, plus a warning for every file it had to
+skip.
+
+**It is exposed to codemode, not to the model.** The tool registers with
+`exposure: "codemode"`, so it is never declared in the model's tool list and is not
+activated on registration. Call it from a codemode script:
+
+```js
+// in a codemode script
+const { sessions, warnings } = await tools.list_sessions({});
+```
+
+A plain "list my sessions" prompt will not reach it unless your own settings declare
+the tool directly. This is deliberate — the result is structured JSON that a script
+can filter before it costs context — but it does mean the tool is invisible to a
+session running without codemode.
+
+## Reference
+
+- [`docs/tool-api.md`](docs/tool-api.md) — the contract for the operations this
+  package exposes, including `listSessions`, its discovery rules, and its guarantees.
+- `test/fixtures/generate.mjs` (source repository, not in the npm tarball) — rebuilds
+  the synthetic session tree the tests run against.
+
+The deeper reference on Pi's session *format* — the measurements and Pi-internals
+analysis this contract was derived from — lives in the author's Obsidian vault rather
+than in the published package, because it documents Pi's schema (which changes with
+Pi, not with this package) and quotes counts from one developer's local session store.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

package/docs/maintainer-reference.md

@@ -0,0 +1,323 @@
+## Compatibility
+
+Verified against `@earendil-works/pi-coding-agent` **0.99.2** and
+`@earendil-works/pi-ai` **0.99.2** (TypeBox **1.3.27**), and re-checked against Pi
+**1.0.0** on 2026-10-02 — the shipped `dist/core/session-manager.js` and `pi-ai`
+`dist/types.d.ts` are byte-identical across those releases, so nothing here changed.
+Subagent child layout is a `pi-subagents` convention, observed against **0.74.0**.
+Measurements are snapshots of one developer machine's session store and are quoted as
+ratios or timings, never as store totals; a store grows daily.
+
+## Maintainer reference
+
+The sections below are the implementation contract for `listSessions` (the exported
+function behind the registered `list_sessions` tool). Each states *how* a guarantee from the
+caller half is produced; the caller half states *what* is guaranteed.
+
+### TypeBox schemas
+
+```ts
+import { Type, type Static } from "@earendil-works/pi-ai";
+
+export const ListSessionsParamsSchema = Type.Object(
+  {},
+  { additionalProperties: false },
+);
+
+export const SessionMetadataSchema = Type.Cyclic(
+  {
+    SessionMetadata: Type.Object(
+      {
+        id: Type.String({ description: "Session id from the file header" }),
+        path: Type.String({ description: "Absolute path to the session .jsonl file" }),
+        timestamp: Type.String({
+          format: "date-time",
+          description: "Header timestamp, ISO 8601, validated before the row is returned",
+        }),
+        cwd: Type.String({ description: "Absolute working directory from the header" }),
+        parentSessionPath: Type.Optional(
+          Type.String({
+            description: "Header parentSession value, copied verbatim (fork/clone lineage)",
+          }),
+        ),
+        subagentSessions: Type.Array(Type.Ref("SessionMetadata"), {
+          description: "Subagent transcripts launched from this session, in timestamp order",
+        }),
+      },
+      { additionalProperties: false },
+    ),
+  },
+  "SessionMetadata",
+);
+
+export const ListSessionsWarningSchema = Type.Object(
+  {
+    path: Type.String({ description: "Absolute path of the file or directory that was skipped" }),
+    reason: Type.String({ description: "Why the file was not returned as a session" }),
+  },
+  { additionalProperties: false },
+);
+
+export const ListSessionsOutputSchema = Type.Object(
+  {
+    sessions: Type.Array(SessionMetadataSchema),
+    warnings: Type.Array(ListSessionsWarningSchema),
+  },
+  { additionalProperties: false },
+);
+
+export type ListSessionsParams = Static<typeof ListSessionsParamsSchema>;
+export type SessionMetadata = Static<typeof SessionMetadataSchema>;
+export type ListSessionsWarning = Static<typeof ListSessionsWarningSchema>;
+export type ListSessionsOutput = Static<typeof ListSessionsOutputSchema>;
+```
+
+Recursive schemas use `Type.Cyclic` + `Type.Ref`; this TypeBox release has no
+`Type.Recursive`. `Static` resolves the `$ref` back to the interface, so
+`SessionMetadata` is a genuinely recursive TypeScript type.
+
+`id` stays `Type.String()`, **not** `format: "uuid"`. Pi mints UUIDv7 by default but
+`assertValidSessionId` only constrains the character set, so a custom id is valid Pi
+data and must not be rejected here.
+
+`format: "date-time"` is a real guarantee rather than documentation, because timestamps are
+validated before a row is returned (see Validation rules).
+
+### Implementation boundary
+
+The tool takes no parameters; the implementation takes the root, so tests can point it at a
+fixture tree.
+
+```ts
+export interface ListSessionsOptions {
+  sessionsRoot: string;
+  /** Aborted between filesystem operations. */
+  signal?: AbortSignal;
+}
+
+export async function listSessions(
+  params: ListSessionsParams,
+  options: ListSessionsOptions,
+): Promise<ListSessionsOutput>;
+```
+
+The registered wrapper supplies the root. Pi's `getSessionsDir()` is **not** re-exported
+from the package root; `getAgentDir()` is, and it honors the agent-dir environment
+override. So `src/index.ts` computes:
+
+```ts
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+
+const sessionsRoot = join(getAgentDir(), "sessions");
+```
+
+The `"sessions"` literal is the only path component we hardcode. The tool itself is built
+by a factory — `createListSessionsTool({ sessionsRoot })` in `src/list-sessions-tool.ts` —
+so tests can construct the registered shape against a fixture root instead of the live store.
+
+`execute()` checks the `AbortSignal` between file reads and stops early; `details`
+mirrors `structuredContent`; `outputSchema` is declared so codemode callers receive JSON
+instead of prose.
+
+### Discovery rules
+
+1. **Project directories:** only immediate subdirectories of the root whose name matches
+   `--<slug>--`. Other entries — measured here: `permission-forwarding/` — are ignored by
+   rule, not by accident.
+2. **Top-level sessions:** `*.jsonl` files *directly* inside a project directory. Not a
+   recursive search, which keeps `subagent-artifacts/*_transcript.jsonl` copies (only a
+   handful exist where this was measured, but they duplicate real children) out of the result
+   set: they are neither roots (not directly in a project dir) nor children (not under a
+   parent-stem directory).
+3. **Children of a session:** every `session.jsonl` at any depth under a directory named
+   after the session's own stem — `<file-timestamp>_<session-id>`, the parent filename with
+   `.jsonl` removed. Today the observed shape is exactly
+   `<slug>/<parent-stem>/<launch-uuid>/run-<n>/session.jsonl`.
+4. **One entry per run directory.** A launch slot holding `run-0`, `run-1`, … produces one
+   `SessionMetadata` per transcript; we do not collapse a resumed child into a single entry.
+5. **Grouping by deepest container.** A session's container directory is
+   `dirname(path)/basename-without-.jsonl`. Every transcript found under a root's container
+   is attached to the session whose container is the deepest ancestor of its path, so a
+   transcript is never reported under two parents. When a nested launch does not sit under
+   its parent's container, it stays attached to the nearest session that does — the
+   documented fallback for the unverified grandchild convention. Recursion is implemented
+   generically and unverified: the store measured here holds no grandchild transcripts at
+   all, and every child transcript observed sits at depth `run-0`. See TODOs.
+6. **Header read:** only line 1 of each file is parsed, bounded to **4 KiB**
+   (`MAX_HEADER_LINE_BYTES = 4096`). A longer first line is skipped with a warning. This is
+   deliberately tighter than Pi's own 1 MiB `MAX_SESSION_HEADER_SCAN_BYTES`: real headers
+   measured here are ~150 bytes, and a header over 4 KiB is not a session we can trust.
+   A line of exactly 4096 bytes is accepted; a file whose last line has no terminating
+   newline is read normally.
+7. **Symlinks are not followed.** Discovery stays inside `sessionsRoot`. Implemented by
+   `Dirent.isDirectory()` / `isFile()`, which are false for symlinks.
+
+### Validation rules
+
+A file yields a session row only when all of the following hold; otherwise it is skipped
+and one warning `{ path, reason }` is emitted. The reason vocabulary is free-form text, not
+an enum.
+
+| Condition | Outcome |
+| --- | --- |
+| Line 1 missing, empty, or unreadable | skip + warn |
+| Line 1 not valid JSON | skip + warn |
+| Line 1 JSON is not an object, or `type !== "session"` | skip + warn |
+| Missing/invalid `id` | skip + warn |
+| Missing or empty `cwd` (Pi writes `""` in old sessions) | skip + warn |
+| `timestamp` absent, wrong type, ISO-shaped but not a real date, or not parseable | skip + warn |
+| `parentSessionPath` present but not a string | skip + warn |
+| First line longer than 4 KiB | skip + warn |
+
+Consequence: every returned row is fully trustworthy — `id`, absolute `path`, valid `cwd`,
+and a parseable `timestamp` are guaranteed, so callers never handle a partial row and
+sorting never meets an `Invalid Date`. Nothing the walk reached is ever silently dropped; a
+skipped file costs one warning entry. Files the discovery rules exclude (non-slug
+directories, `subagent-artifacts/` copies, orphaned stems, symlinks) are not skipped and
+therefore not warned about — they are out of scope.
+
+A missing subagent directory is the normal case and is **not** warned about; an existing
+directory that cannot be read is. `parentSessionPath` is copied verbatim with no
+resolution, normalization, or existence check. A `parentSession` present but not a string
+is a skip-plus-warning; an empty-string `parentSession` is treated as absent and omitted
+from the row. `path` is absolute because `sessionsRoot` is resolved with `path.resolve()`
+before the walk and every row path is built from it; `cwd` is absolute because we require
+it. Timestamp validation includes a calendar check `Date.parse` does not provide —
+`"2026-02-30T08:00:00.000Z"` rolls over instead of failing, and would otherwise reach the
+output as an untrustworthy string.
+
+### Ordering rules
+
+`timestamp` **ascending**, oldest first, at both levels, with ties broken by `path`. The
+sessions root is resolved to an absolute path before the walk, so `path` is absolute even
+when a caller passes a relative `sessionsRoot`. `warnings` are sorted by `path` (then
+`reason`) so a run is reproducible regardless of `readdir` order. Ascending was chosen so
+that a parent's subagent children appear in launch order, which mirrors how the runs were
+started. The tool description is where "the sessions a caller usually wants are at the
+tail" has to be spelled out, because ascending order is the counter-intuitive half.
+
+### Missing or empty root
+
+Two cases, verified against the implementation, and they differ:
+
+- **Root not readable** (does not exist, or `scandir` fails for any other reason): not an
+  error. Returns `{ sessions: [], warnings: [ … ] }` with one warning naming the resolved
+  attempted path, whose reason begins `sessions root not readable:`.
+- **Root exists but holds no `--<slug>--` directory** (or holds only directories with no
+  readable session headers directly inside them): returns `{ sessions: [], warnings: [] }`.
+  No warning is emitted, because walking an empty directory is not a failure.
+
+A fresh install has no history yet and must not look broken, which is why neither case
+throws. The distinction a caller has to remember: `sessions: []` plus empty `warnings` is
+"found nothing", while `sessions: []` plus a warning naming the root is "could not read
+the store".
+
+### Tool registration
+
+```ts
+defineTool({
+  name: "list_sessions",
+  label: "List Sessions",
+  description: "...",
+  parameters: ListSessionsParamsSchema,
+  outputSchema: ListSessionsOutputSchema,
+  exposure: "codemode",
+  annotations: { readOnlyHint: true },
+});
+```
+
+The registered `description` must keep telling the caller what it cannot infer from the
+shape: that results are oldest-first so the newest session is last, that nesting is
+expressed by `subagentSessions` while `parentSessionPath` is fork lineage, and that an
+empty list plus warnings means unreadable rather than absent history. It currently does not
+say that `path` is the handle to key on — see TODOs.
+
+`exposure`, `annotations`, and `outputSchema` require **Pi >= 0.99.0** (added
+2026-09-29). Peer ranges stay `"*"` because that is Pi's stated convention for
+host-provided packages and Pi does not resolve peer ranges for managed installs
+(`--omit=peer`), so this minimum is recorded in prose rather than in `package.json`.
+
+`exposure: "codemode"` means the tool is callable from codemode scripts and listed by the
+`codemode` tool, but is never declared to the model and is not activated on registration.
+The two consequences in the caller half (structured JSON to scripts; `content` visible only
+in transcripts, logs, and UI) follow from this.
+
+### Rendered `content` text format
+
+Model/UI-facing text is an index of paths, not a re-encoding of the data:
+
+```
+Sessions (N)
+- /Users/<user>/.pi/agent/sessions/--Users-<user>-repos-app--/2026-09-…_01a0….jsonl
+- /Users/<user>/.pi/agent/sessions/--Users-<user>-repos-tool--/2026-10-…_01a0….jsonl
+  - /Users/…/2026-10-…_01a0….jsonl/<launch-uuid>/run-0/session.jsonl
+
+Warnings (2)
+- /Users/…/broken.jsonl: first line is not a session header
+```
+
+- `Sessions (N)` header, then one bullet per root session, children indented two spaces per
+  nesting level, in the same order as `sessions`.
+- `Warnings (N)` section only when there is at least one warning.
+- No row cap and no truncation: the list is bounded by the number of sessions, and the JSON
+  is available to scripts regardless.
+
+### Testing policy
+
+Committed synthetic fixtures under `test/fixtures/sessions/`, generated by
+`test/fixtures/generate.mjs` (`node test/fixtures/generate.mjs` rebuilds the tree; both are
+in the source repository, not in the npm tarball). The layout reproduces the real one —
+`--<slug>--` project directories, parent `<stem>.jsonl` files,
+`<stem>/<launch-uuid>/run-<n>/session.jsonl` children, a `subagent-artifacts/` dump, a
+non-slug directory, a stray root-level `.jsonl`, two symlinks (a project-dir link and a
+session-file link), an orphan stem directory with no matching parent file, a header of
+exactly 4096 bytes and one of 4097, a header with no terminating newline, and one
+deliberately broken file per warning branch. Fixture headers are hand-written; no real
+session data is committed.
+
+Assertions target the contract, not Pi's format: ordering, absolute paths, nesting by
+containment, one row per run directory, symlink and non-slug exclusion, and warning
+coverage.
+
+Measured against the **live** store on this machine: every parent and child transcript
+discovered, 0 warnings, unique paths and ids, ordering correct, and the whole walk
+completes in roughly 200 ms. Running subagent workflows here is still the way to grow real
+parent/child trees for spot-checks — see TODOs.
+
+### Implementation guarantees
+
+Restated from the caller half as properties a change must not break: total ascending
+ordering with `path` tie-break at every level; `subagentSessions` always present; each file
+reported at most once; containment-only child linkage with no structural field connecting
+parents to children (Pi's `SessionHeader.parentSession` means fork/clone lineage, verified
+against `pi-subagents` 0.74.0); `path` as the stable handle because `id` may repeat across
+`run-<n>` directories; no use of Pi's `SessionManager.open()`, which can migrate or repair
+history; and orphaned `--<slug>--` stems left unvisited, so only files reachable from a
+discovered session are considered.
+
+---
+
+## TODOs
+
+- **Verify grandchild nesting.** Every child transcript in the store measured here sits at
+  `<slug>/<parent-stem>/<launch-uuid>/run-0/session.jsonl`; none launched their own
+  subagent, so the recursive case is unexercised. Once a nested launch exists, confirm the
+  convention — whether a child's own stem directory appears as `…/run-0/<child-stem>/…` —
+  and that containment-based grouping does not attach a deep transcript to two parents.
+- **Generate real fixture data.** Run subagent workflows in this project's `cwd` so that
+  project's `--<slug>--/` session directory grows actual parent/child trees, then use them
+  to check the synthetic layout against reality. Do not commit the output.
+- **Filtering parameters.** `params` is an empty object by design. Deferred for later:
+  by project/`cwd`, by time range, by presence of subagents, `includeCurrentSession`
+  (the currently running session is included today; an exclusion parameter is the agreed
+  future direction), depth limit for `subagentSessions`.
+- **Ordering choice review.** Ascending order follows launch chronology; if callers keep
+  needing the newest session, add a parameter rather than flipping the default.
+- **Orphaned child trees.** Today they are reported neither as a row nor as a warning. If
+  that ever needs to be visible, it should become an explicit warning branch rather than a
+  silent rule.
+- **Tool description should name `path` as the handle.** The caller half says to key on
+  `path` rather than `id`, but `description` in `src/list-sessions-tool.ts` lists the fields
+  without saying which identifies a transcript. Worth one clause, since a caller reading
+  only the description has no other way to learn it.

package/docs/tool-api.md

@@ -0,0 +1,197 @@
+# Tool API
+
+The contract for the operations `pi-retrospect` exposes.
+
+## Calling `list_sessions`
+
+### Purpose
+
+`list_sessions` returns metadata for every discoverable Pi session, with subagent
+transcripts nested under the session that launched them. It is the entry point for
+"which past session do I want to look at" — it names sessions and locates them on disk;
+it does not read the conversation inside them.
+
+The call is **read-only**: it opens each file's first line directly and never goes through
+Pi's `SessionManager.open()`, which can migrate or repair history. Nothing is written.
+
+### Availability and invocation
+
+The tool registers with `exposure: "codemode"`. That has three consequences a caller must
+know:
+
+- It is **callable from codemode scripts and listed by the `codemode` tool**, but it is
+  never declared to the model and is not activated on registration. A plain "list my
+  sessions" prompt does not reach it unless your own settings declare the tool directly.
+- A script receives the **structured JSON result**, so filtering costs no context before
+  you decide what to look at.
+- The rendered text (`content`) is visible only in transcripts, logs, and UI rendering,
+  and nested tool results do not become transcript entries — the JSON is reachable only
+  from inside a script that asked for it.
+
+It takes no parameters: pass an empty object.
+
+```js
+// in a codemode script
+const { sessions, warnings } = await tools.list_sessions({});
+```
+
+Every example below is a codemode script body: top-level `await` and a top-level `return`
+work, and the returned value is what the calling agent sees.
+
+### Quick examples
+
+Newest recorded session — arrays are oldest-first, so the entry you usually want is last:
+
+```js
+const { sessions, warnings } = await tools.list_sessions({});
+const newest = sessions.at(-1);
+
+return newest
+  ? { path: newest.path, cwd: newest.cwd, timestamp: newest.timestamp }
+  : { path: null, warnings };
+```
+
+Sessions for one project:
+
+```js
+const { sessions } = await tools.list_sessions({});
+const project = "/Users/me/repos/my-app";
+
+return sessions
+  .filter((session) => session.cwd === project)
+  .map((session) => ({ path: session.path, timestamp: session.timestamp }));
+```
+
+Every transcript, parents and children flattened, newest last:
+
+```js
+function flatten(sessions, depth = 0) {
+  return sessions.flatMap((session) => [
+    { depth, path: session.path, cwd: session.cwd, timestamp: session.timestamp },
+    ...flatten(session.subagentSessions, depth + 1),
+  ]);
+}
+
+const { sessions } = await tools.list_sessions({});
+return flatten(sessions).sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp));
+```
+
+Delegated work: root sessions that have subagent children, with their run count:
+
+```js
+const { sessions } = await tools.list_sessions({});
+
+return sessions
+  .filter((session) => session.subagentSessions.length > 0)
+  .map((session) => ({
+    path: session.path,
+    cwd: session.cwd,
+    runs: session.subagentSessions.length,
+  }));
+```
+
+The result is an index of transcript files. To read one, pass its `path` to a file-reading
+tool; a `.jsonl` transcript is one JSON object per line, which `read` handles directly.
+
+### Result fields
+
+```ts
+type ListSessionsOutput = {
+  sessions: SessionMetadata[];
+  warnings: ListSessionsWarning[];
+};
+```
+
+| Field | Caller meaning |
+| --- | --- |
+| `id` | Session id from the file header. Not a safe key — see Limitations. |
+| `path` | Absolute path to the session `.jsonl` file. **The handle to key on**: unique among returned rows, and what you hand to a file-reading tool. |
+| `timestamp` | Valid ISO 8601 header timestamp; always parseable, so it is safe to sort and compare. |
+| `cwd` | Absolute working directory of the session. Empty `cwd` never appears: such files are skipped. |
+| `parentSessionPath` | Optional. Fork/clone lineage copied verbatim from the header. **Not** the nesting relationship. |
+| `subagentSessions` | Transcripts launched under this session, nested recursively. Always present; `[]` when there are none. |
+
+```ts
+type ListSessionsWarning = {
+  path: string;   // absolute path of the skipped file or directory
+  reason: string; // free-form text, not an enum
+};
+```
+
+### Interpreting the hierarchy
+
+Two different "parent" concepts exist and are unrelated:
+
+- **Nesting** is expressed only by `subagentSessions`. Each transcript is attached to the
+  discovered session whose directory is the closest containing directory of its path, so a
+  transcript never appears under two parents.
+- **`parentSessionPath`** is Pi's header `parentSession` value: fork/clone lineage between
+  top-level sessions. It is copied verbatim with no resolution, normalization, or existence
+  check, and it does not point at the entry that nests the transcript. Do not use it to
+  walk `subagentSessions`.
+
+Every discovered transcript is reported **at most once**, either as a row or as a warning.
+
+### Ordering
+
+Arrays are **oldest first** — `timestamp` ascending, ties broken by `path`, at every
+nesting level. `warnings` are sorted by `path`, then `reason`.
+
+**Caller rule:** the sessions you usually want are at the tail. Use `sessions.at(-1)` for
+the newest; never assume the first element is the most recent. Ascending is deliberate at
+the child level because it puts a parent's subagent runs in launch order. If you keep
+wanting newest-first at the root, that is a parameter request, not a default to flip — see
+TODOs.
+
+### Warnings and empty results
+
+How to read the shape of a response:
+
+| `sessions` | `warnings` | What it means |
+| --- | --- | --- |
+| non-empty | empty | Clean read of the store. |
+| non-empty | non-empty | Usable sessions, but some files were skipped. Say so if completeness matters. |
+| `[]` | empty | Nothing discoverable: no `--<slug>--` project directory held a readable session header. An existing-but-empty root looks exactly like this — no warning. |
+| `[]` | non-empty | **Unreadable history, not absence of history.** Inspect the reasons before concluding there are no sessions. |
+
+Neither case is an error. A root that cannot be read returns one warning naming the
+resolved path; an existing root with nothing discoverable returns
+`{ sessions: [], warnings: [] }`. A fresh install therefore never looks broken — see
+Missing or empty root in the maintainer half.
+
+The `warnings` array is flat: it does not say which nesting level the failure happened at.
+A failed child is simply absent from its parent's `subagentSessions` list, plus one warning
+naming the child's path — so a parent can look childless while its child tree was
+partially unreadable. A child directory that does not exist at all is the normal case and
+adds no warning.
+
+### Caller guarantees
+
+1. Every row has `id`, absolute `path`, absolute non-empty `cwd`, and a parseable ISO 8601
+   `timestamp`. There are no partial rows and no `Invalid Date`.
+2. `subagentSessions` is always present; `[]` for a session with no children.
+3. Ordering is total and reproducible (timestamp ascending, ties by `path`).
+4. A file is reported at most once, as a row or as a warning. Every file the walk
+   *considered* costs exactly one warning if it is skipped — but the walk does not consider
+   everything on disk, so "no warnings" does not mean "the store is complete". See
+   Limitations.
+5. The call is read-only and cannot repair or migrate history.
+
+### Limitations
+
+- **`id` is not guaranteed unique across rows.** `path` is the handle to key on. A session
+  id could repeat across `run-<n>` directories if Pi ever reuses one; today's store has only
+  `run-0`, so this is unverifiable rather than known-safe.
+- **The hierarchy is inferred from on-disk layout**, not from a structural field. It is a
+  `pi-subagents` storage convention, not Pi's own model.
+- **Orphaned child trees are invisible.** A `--<slug>--` directory whose stem has no
+  matching parent `.jsonl` is never visited, so its transcripts are reported neither as a
+  row nor as a warning. The same is true of everything else the discovery rules exclude.
+  "No warnings" means "nothing I reached was unreadable", not "the store is complete".
+- **Grandchild nesting is unverified against real data.** See TODOs.
+- **No filtering, no pagination.** `params` is an empty object by design; every filter is
+  yours to write in the script. The currently running session **is** included — verified
+  2026-10-02, where `sessions.at(-1)` matched `$PI_SESSION_FILE`. Exclude it yourself by
+  comparing against that variable if you mean "previous sessions only".
+- **Sessions only.** Message content is out of scope for this operation.
+

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "pi-retrospect",
+  "version": "0.1.0",
+  "description": "Tools to explore past Pi sessions to facilitate harness self-improvement",
+  "type": "module",
+  "license": "MIT",
+  "author": "nietaki",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "sessions",
+    "history",
+    "retrospect"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nietaki/pi-retrospect.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nietaki/pi-retrospect/issues"
+  },
+  "homepage": "https://github.com/nietaki/pi-retrospect#readme",
+  "scripts": {
+    "test": "node --experimental-strip-types --test test/*.test.mjs",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run test && npm run typecheck",
+    "prepublishOnly": "npm run check"
+  },
+  "files": [
+    "src",
+    "docs",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/content.ts

@@ -0,0 +1,33 @@
+/**
+ * Model/UI-facing text for `listSessions`.
+ *
+ * An index of paths, not a re-encoding of the data: `Sessions (N)` and one bullet per
+ * session, subagent transcripts indented under their parent, then `Warnings (N)` and
+ * `path: reason` bullets. No row cap and no truncation.
+ *
+ * Contract: docs/tool-api.md
+ */
+
+import type { ListSessionsOutput, SessionMetadata } from "./schemas.ts";
+
+function sessionLines(sessions: SessionMetadata[], depth: number): string[] {
+  const indent = "  ".repeat(depth);
+
+  return sessions.flatMap((session) => [
+    `${indent}- ${session.path}`,
+    ...sessionLines(session.subagentSessions, depth + 1),
+  ]);
+}
+
+export function renderListSessionsContent(output: ListSessionsOutput): string {
+  const lines = [`Sessions (${output.sessions.length})`, ...sessionLines(output.sessions, 0)];
+
+  if (output.warnings.length > 0) {
+    lines.push("", `Warnings (${output.warnings.length})`);
+    for (const warning of output.warnings) {
+      lines.push(`- ${warning.path}: ${warning.reason}`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+import { join } from "node:path";
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { createListSessionsTool } from "./list-sessions-tool.ts";
+
+export default function (pi: ExtensionAPI) {
+  // Pi exports getAgentDir() but not getSessionsDir(), so the "sessions" segment is ours.
+  const sessionsRoot = join(getAgentDir(), "sessions");
+
+  pi.registerTool(createListSessionsTool({ sessionsRoot }));
+}

package/src/list-sessions-tool.ts

@@ -0,0 +1,49 @@
+/**
+ * The `list_sessions` tool.
+ *
+ * Built by a factory so tests can register it against a fixture root instead of the live
+ * session store. `src/index.ts` supplies the real one.
+ *
+ * Contract: docs/tool-api.md
+ */
+
+import { defineTool } from "@earendil-works/pi-coding-agent";
+
+import { renderListSessionsContent } from "./content.ts";
+import { listSessions } from "./list-sessions.ts";
+import { ListSessionsOutputSchema, ListSessionsParamsSchema } from "./schemas.ts";
+
+export interface ListSessionsToolOptions {
+  sessionsRoot: string;
+}
+
+export function createListSessionsTool(options: ListSessionsToolOptions) {
+  return defineTool({
+    name: "list_sessions",
+    label: "List Sessions",
+    description: [
+      "List every recorded Pi session under the sessions root, newest last.",
+      "Returns { sessions, warnings }: each session carries its id, absolute file path, absolute cwd,",
+      "ISO 8601 timestamp, an optional parentSessionPath for forked sessions, and subagentSessions",
+      "holding the subagent transcripts launched from it (nested the same way).",
+      "Both levels are ordered by timestamp ascending, so the most recent session is the last entry.",
+      "Sessions whose file cannot be read or has no valid session header on line 1 are not returned;",
+      "they appear in warnings with the reason, so an empty list plus warnings means unreadable history",
+      "rather than no history.",
+    ].join(" "),
+    parameters: ListSessionsParamsSchema,
+    outputSchema: ListSessionsOutputSchema,
+    exposure: "codemode",
+    annotations: { readOnlyHint: true },
+
+    async execute(_toolCallId, params, signal) {
+      const output = await listSessions(params, { sessionsRoot: options.sessionsRoot, signal });
+
+      return {
+        content: [{ type: "text", text: renderListSessionsContent(output) }],
+        details: output,
+        structuredContent: output,
+      };
+    },
+  });
+}

package/src/list-sessions.ts

@@ -0,0 +1,260 @@
+/**
+ * Walk the Pi sessions directory and return session metadata, with subagent transcripts
+ * nested under the session that launched them.
+ *
+ * Contract: docs/tool-api.md
+ */
+
+import { readdir } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+
+import { readSessionHeader } from "./session-metadata.ts";
+import type {
+  ListSessionsOutput,
+  ListSessionsParams,
+  ListSessionsWarning,
+  SessionMetadata,
+} from "./schemas.ts";
+
+/** Pi encodes a cwd into `--<slug>--`; anything else at that level is not a project. */
+const PROJECT_DIRECTORY = /^--.*--$/;
+
+/** Extension-written name of a subagent transcript. Top-level sessions are `<stem>.jsonl`. */
+const SUBAGENT_FILE_NAME = "session.jsonl";
+
+const SESSION_EXTENSION = ".jsonl";
+
+export interface ListSessionsOptions {
+  /**
+   * Sessions root, normally `join(getAgentDir(), "sessions")`. Injectable for tests.
+   * Resolved to an absolute path, because every returned `path` must be absolute.
+   */
+  sessionsRoot: string;
+  /** Aborted between filesystem operations. */
+  signal?: AbortSignal;
+}
+
+type ParsedSession = {
+  path: string;
+  id: string;
+  timestamp: string;
+  cwd: string;
+  parentSessionPath?: string;
+};
+
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    throw signal.reason instanceof Error ? signal.reason : new Error("listSessions was aborted");
+  }
+}
+
+/** `dir/file.jsonl` -> `dir/file`, the directory that holds this session's subagent trees. */
+function containerOf(path: string): string {
+  return join(dirname(path), basename(path, SESSION_EXTENSION));
+}
+
+function containsPath(container: string, path: string): boolean {
+  const prefix = container.endsWith("/") ? container : `${container}/`;
+  return path.startsWith(prefix);
+}
+
+/** Timestamp ascending, oldest first; ties broken by path so the order is total. */
+function compareSessions(a: SessionMetadata, b: SessionMetadata): number {
+  const left = Date.parse(a.timestamp);
+  const right = Date.parse(b.timestamp);
+
+  if (left !== right) return left - right;
+  if (a.path !== b.path) return a.path < b.path ? -1 : 1;
+  return 0;
+}
+
+/** Warnings are sorted by path so a run is reproducible despite readdir order. */
+function compareWarnings(a: ListSessionsWarning, b: ListSessionsWarning): number {
+  if (a.path !== b.path) return a.path < b.path ? -1 : 1;
+  return a.reason < b.reason ? -1 : a.reason > b.reason ? 1 : 0;
+}
+
+function toMetadata(session: ParsedSession, children: SessionMetadata[]): SessionMetadata {
+  const metadata: SessionMetadata = {
+    id: session.id,
+    path: session.path,
+    timestamp: session.timestamp,
+    cwd: session.cwd,
+    subagentSessions: children,
+  };
+
+  if (session.parentSessionPath !== undefined) {
+    metadata.parentSessionPath = session.parentSessionPath;
+  }
+
+  return metadata;
+}
+
+/**
+ * Read headers of every `session.jsonl` found at any depth under `directory`.
+ *
+ * Unreadable files and invalid headers are skipped and warned about, and never returned.
+ * Symlinks are not followed, so the walk stays inside the supplied root.
+ */
+async function collectSubagentTranscripts(
+  directory: string,
+  warnings: ListSessionsWarning[],
+  signal?: AbortSignal,
+): Promise<ParsedSession[]> {
+  throwIfAborted(signal);
+
+  let entries;
+  try {
+    entries = await readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    // No subagent directory is the normal case, not a failure worth warning about.
+    if ((error as { code?: string }).code === "ENOENT") return [];
+    warnings.push({
+      path: directory,
+      reason: `subagent directory not readable: ${error instanceof Error ? error.message : String(error)}`,
+    });
+    return [];
+  }
+
+  const found: ParsedSession[] = [];
+
+  for (const entry of entries) {
+    throwIfAborted(signal);
+    const path = join(directory, entry.name);
+
+    if (entry.isDirectory()) {
+      found.push(...(await collectSubagentTranscripts(path, warnings, signal)));
+      continue;
+    }
+
+    if (!entry.isFile() || entry.name !== SUBAGENT_FILE_NAME) continue;
+
+    const header = await readSessionHeader(path);
+    if (!header.ok) {
+      warnings.push({ path, reason: header.reason });
+      continue;
+    }
+
+    found.push({ path, ...header.values });
+  }
+
+  return found;
+}
+
+/**
+ * Attach transcripts to the session whose container directory is their deepest ancestor,
+ * so a transcript is never reported under two parents.
+ *
+ * A session's container is `dirname(path)/basename-without-.jsonl`. When a nested launch
+ * does not sit under its parent's container, it stays attached to the nearest session that
+ * does — the documented fallback for the unverified grandchild convention.
+ */
+function nestTranscripts(
+  rootContainer: string,
+  transcripts: ParsedSession[],
+  signal?: AbortSignal,
+): SessionMetadata[] {
+  const parentOf = new Map<string, string | null>();
+
+  for (const transcript of transcripts) {
+    throwIfAborted(signal);
+
+    let best: { key: string; depth: number } | null = { key: rootContainer, depth: rootContainer.length };
+
+    for (const candidate of transcripts) {
+      if (candidate.path === transcript.path) continue;
+
+      const container = containerOf(candidate.path);
+      if (!containsPath(container, transcript.path)) continue;
+      if (container.length > best.depth) best = { key: candidate.path, depth: container.length };
+    }
+
+    parentOf.set(transcript.path, best.key === rootContainer ? null : best.key);
+  }
+
+  const build = (key: string | null): SessionMetadata[] => {
+    const children = transcripts
+      .filter((transcript) => parentOf.get(transcript.path) === key)
+      .map((transcript) => toMetadata(transcript, build(transcript.path)))
+      .sort(compareSessions);
+
+    return children;
+  };
+
+  return build(null);
+}
+
+/**
+ * List every discoverable session under `options.sessionsRoot`.
+ *
+ * Sessions are ordered by `timestamp` ascending — oldest first, so a parent's subagent
+ * children appear in launch order. Files that cannot be read or whose header is invalid are
+ * skipped and reported in `warnings` instead.
+ */
+export async function listSessions(
+  _params: ListSessionsParams,
+  options: ListSessionsOptions,
+): Promise<ListSessionsOutput> {
+  const sessionsRoot = resolve(options.sessionsRoot);
+  const { signal } = options;
+  const warnings: ListSessionsWarning[] = [];
+  const sessions: SessionMetadata[] = [];
+
+  throwIfAborted(signal);
+
+  let rootEntries;
+  try {
+    rootEntries = await readdir(sessionsRoot, { withFileTypes: true });
+  } catch (error) {
+    // A fresh install has no history yet: empty plus one warning, not an error.
+    return {
+      sessions: [],
+      warnings: [
+        {
+          path: sessionsRoot,
+          reason: `sessions root not readable: ${error instanceof Error ? error.message : String(error)}`,
+        },
+      ],
+    };
+  }
+
+  for (const entry of rootEntries) {
+    throwIfAborted(signal);
+
+    // `isDirectory()` is false for symlinks, so links are never followed.
+    if (!entry.isDirectory() || !PROJECT_DIRECTORY.test(entry.name)) continue;
+
+    const projectDir = join(sessionsRoot, entry.name);
+
+    let projectEntries;
+    try {
+      projectEntries = await readdir(projectDir, { withFileTypes: true });
+    } catch (error) {
+      warnings.push({
+        path: projectDir,
+        reason: `project directory not readable: ${error instanceof Error ? error.message : String(error)}`,
+      });
+      continue;
+    }
+
+    for (const file of projectEntries) {
+      throwIfAborted(signal);
+      if (!file.isFile() || !file.name.endsWith(SESSION_EXTENSION)) continue;
+
+      const path = join(projectDir, file.name);
+      const header = await readSessionHeader(path);
+      if (!header.ok) {
+        warnings.push({ path, reason: header.reason });
+        continue;
+      }
+
+      const transcripts = await collectSubagentTranscripts(containerOf(path), warnings, signal);
+      sessions.push(toMetadata({ path, ...header.values }, nestTranscripts(containerOf(path), transcripts, signal)));
+    }
+  }
+
+  sessions.sort(compareSessions);
+  warnings.sort(compareWarnings);
+
+  return { sessions, warnings };
+}

package/src/schemas.ts

@@ -0,0 +1,71 @@
+/**
+ * TypeBox schemas and derived TypeScript types for the operations this package exposes.
+ *
+ * Contract: docs/tool-api.md
+ */
+
+import { Type, type Static } from "@earendil-works/pi-ai";
+
+/**
+ * Parameters for `listSessions`. Empty by design; filtering arguments are deferred.
+ */
+export const ListSessionsParamsSchema = Type.Object({}, { additionalProperties: false });
+
+/**
+ * Metadata for one session file, with its subagent children nested underneath.
+ *
+ * Recursive schemas in this TypeBox release use `Type.Cyclic` + `Type.Ref`. `id` stays an
+ * unformatted string on purpose: Pi mints UUIDv7 by default, but only constrains the id
+ * character set, so a custom session id is valid data and must not be rejected here.
+ */
+export const SessionMetadataSchema = Type.Cyclic(
+  {
+    SessionMetadata: Type.Object(
+      {
+        id: Type.String({ description: "Session id from the file header" }),
+        path: Type.String({ description: "Absolute path to the session .jsonl file" }),
+        timestamp: Type.String({
+          format: "date-time",
+          description: "Header timestamp, ISO 8601, validated before the row is returned",
+        }),
+        cwd: Type.String({ description: "Absolute working directory from the header" }),
+        parentSessionPath: Type.Optional(
+          Type.String({
+            description: "Header parentSession value, copied verbatim (fork/clone lineage)",
+          }),
+        ),
+        subagentSessions: Type.Array(Type.Ref("SessionMetadata"), {
+          description: "Subagent transcripts launched from this session, in timestamp order",
+        }),
+      },
+      { additionalProperties: false },
+    ),
+  },
+  "SessionMetadata",
+);
+
+/** One skipped file: its path and a free-form reason. Not an enum. */
+export const ListSessionsWarningSchema = Type.Object(
+  {
+    path: Type.String({ description: "Absolute path of the file or directory that was skipped" }),
+    reason: Type.String({ description: "Why the file was not returned as a session" }),
+  },
+  { additionalProperties: false },
+);
+
+/**
+ * Result of `listSessions`. `sessions` is ordered by timestamp ascending, oldest first,
+ * at every nesting level, with ties broken by path.
+ */
+export const ListSessionsOutputSchema = Type.Object(
+  {
+    sessions: Type.Array(SessionMetadataSchema),
+    warnings: Type.Array(ListSessionsWarningSchema),
+  },
+  { additionalProperties: false },
+);
+
+export type ListSessionsParams = Static<typeof ListSessionsParamsSchema>;
+export type SessionMetadata = Static<typeof SessionMetadataSchema>;
+export type ListSessionsWarning = Static<typeof ListSessionsWarningSchema>;
+export type ListSessionsOutput = Static<typeof ListSessionsOutputSchema>;

package/src/session-metadata.ts

@@ -0,0 +1,183 @@
+/**
+ * Read and validate the session header (line 1) of a Pi session file.
+ *
+ * Only the first line is ever read, bounded to MAX_HEADER_LINE_BYTES. This module never
+ * opens a file through Pi's `SessionManager.open()`, which can migrate or repair history.
+ *
+ * Contract: docs/tool-api.md
+ */
+
+import { open } from "node:fs/promises";
+
+/** Maximum accepted length, in bytes, of a session header line. */
+export const MAX_HEADER_LINE_BYTES = 4096;
+
+/** RFC 3339 / ISO 8601 date-time, the shape Pi writes in session headers. */
+const ISO_8601_TIMESTAMP =
+  /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+
+const DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
+function isLeapYear(year: number): boolean {
+  return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+
+/**
+ * Calendar check that `Date.parse` does not provide.
+ *
+ * `Date.parse("2026-02-30T08:00:00.000Z")` rolls over to March 2 instead of failing, so an
+ * impossible date would otherwise pass validation and reach the output as an untrustworthy
+ * timestamp string.
+ */
+function isRealTimestamp(timestamp: string): boolean {
+  const parts = ISO_8601_TIMESTAMP.exec(timestamp);
+  if (!parts) return false;
+
+  const year = Number(parts[1]);
+  const month = Number(parts[2]);
+  const day = Number(parts[3]);
+  const hour = Number(parts[4]);
+  const minute = Number(parts[5]);
+  const second = Number(parts[6]);
+
+  if (month < 1 || month > 12) return false;
+
+  const daysInMonth = month === 2 && isLeapYear(year) ? 29 : DAYS_IN_MONTH[month - 1];
+  if (day < 1 || day > daysInMonth) return false;
+
+  // Second 60 is allowed for a positive leap second; hour and minute are strict.
+  return hour <= 23 && minute <= 59 && second <= 60;
+}
+
+export type HeaderFailure = { ok: false; reason: string };
+
+/** Field values taken from a validated header, before the caller adds `path`. */
+export type SessionHeaderValues = {
+  id: string;
+  timestamp: string;
+  cwd: string;
+  parentSessionPath?: string;
+};
+
+export type HeaderResult = { ok: true; values: SessionHeaderValues } | HeaderFailure;
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Read the first line of a file, at most MAX_HEADER_LINE_BYTES long.
+ *
+ * A final line without a terminating newline is still returned. A first line longer than
+ * the bound fails rather than being truncated, so an over-long header can never be
+ * mistaken for a valid one.
+ */
+export async function readFirstLine(path: string): Promise<{ ok: true; line: string } | HeaderFailure> {
+  let handle;
+  try {
+    handle = await open(path);
+  } catch (error) {
+    return { ok: false, reason: `could not open file: ${describeError(error)}` };
+  }
+
+  try {
+    const limit = MAX_HEADER_LINE_BYTES + 1;
+    const buffer = Buffer.allocUnsafe(limit);
+    let filled = 0;
+
+    while (filled < limit) {
+      const { bytesRead } = await handle.read(buffer, filled, limit - filled, filled);
+      if (bytesRead === 0) break;
+      filled += bytesRead;
+    }
+
+    const data = buffer.subarray(0, filled);
+
+    if (filled === 0) {
+      return { ok: false, reason: "file is empty" };
+    }
+
+    // The read buffer holds one byte past the bound, so a first line that reaches the end
+    // of it without a newline is too long. A newline at index 4096 means a 4096-byte line,
+    // which is exactly at the bound and accepted.
+    const newline = data.indexOf(0x0a);
+
+    if (newline === -1 && filled === limit) {
+      return { ok: false, reason: `first line is longer than ${MAX_HEADER_LINE_BYTES} bytes` };
+    }
+
+    // A file whose only line has no trailing newline: `filled` is within the bound here.
+    const line = newline === -1 ? data : data.subarray(0, newline);
+    return { ok: true, line: line.toString("utf8").replace(/^\uFEFF/, "") };
+  } catch (error) {
+    return { ok: false, reason: `could not read file: ${describeError(error)}` };
+  } finally {
+    await handle.close().catch(() => {});
+  }
+}
+
+/**
+ * Turn a header line into session field values.
+ *
+ * Every returned row is trustworthy: `id`, `cwd`, and `timestamp` must be present and
+ * well-formed, and `parentSessionPath` must be a string when present. Anything else is a
+ * skip-with-warning, so callers never handle a partial row and sorting never meets an
+ * invalid date.
+ */
+export function validateHeaderLine(line: string): HeaderResult {
+  if (line.trim() === "") {
+    return { ok: false, reason: "first line is empty" };
+  }
+
+  let header: unknown;
+  try {
+    header = JSON.parse(line);
+  } catch (error) {
+    return { ok: false, reason: `first line is not valid JSON: ${describeError(error)}` };
+  }
+
+  if (typeof header !== "object" || header === null || Array.isArray(header)) {
+    return { ok: false, reason: "first line is not a JSON object" };
+  }
+
+  const record = header as Record<string, unknown>;
+
+  if (record.type !== "session") {
+    return { ok: false, reason: `first line is not a session header (type: ${String(record.type)})` };
+  }
+
+  if (typeof record.id !== "string" || record.id === "") {
+    return { ok: false, reason: "session header has no id" };
+  }
+
+  if (typeof record.cwd !== "string" || record.cwd === "") {
+    return { ok: false, reason: "session header has no cwd" };
+  }
+
+  if (typeof record.timestamp !== "string" || !isRealTimestamp(record.timestamp)) {
+    return { ok: false, reason: "session header has no valid ISO 8601 timestamp" };
+  }
+
+  if ("parentSession" in record && typeof record.parentSession !== "string") {
+    return { ok: false, reason: "session header parentSession is not a string" };
+  }
+
+  const values: SessionHeaderValues = {
+    id: record.id,
+    timestamp: record.timestamp,
+    cwd: record.cwd,
+  };
+
+  if (typeof record.parentSession === "string" && record.parentSession !== "") {
+    values.parentSessionPath = record.parentSession;
+  }
+
+  return { ok: true, values };
+}
+
+/** Read line 1 of a session file and validate it as a session header. */
+export async function readSessionHeader(path: string): Promise<HeaderResult> {
+  const line = await readFirstLine(path);
+  if (!line.ok) return line;
+  return validateHeaderLine(line.line);
+}