# What Is the Purpose of parentSession Metadata in Pi Web Session Files?

> Understand parentSession metadata in Pi Web session files. Learn how it tracks origin and maintains lineage for UI rendering and relationship management without impacting runtime logic.

- Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web)
- Tags: how-to-guide
- Published: 2026-08-17

---

**The `parentSession` metadata field stores the absolute file path of the originating session, enabling Pi Web to render fork hierarchies in the UI and maintain lineage relationships without affecting runtime session logic.**

Pi Web persists conversation state in `.jsonl` files where the first line contains the session header. This header includes the `parentSession` field that links forked sessions to their ancestors, creating the tree structure visible in the sidebar according to the `agegr/pi-web` source code.

## parentSession in the Type System

### SessionHeader Definition

The field is defined as an optional string property on the session header interface.

In [`lib/types.ts`](https://github.com/agegr/pi-web/blob/main/lib/types.ts) (lines 3-10), the type system declares:

```ts
interface SessionHeader {
  type: "session";
  version: 3;
  id: string;
  timestamp: string;
  cwd: string;
  parentSession?: string; // Absolute path to originating session file
}

```

This property holds the **absolute file path** (for example, `/home/user/.pi/agent/sessions/abc.jsonl`) of the session from which the current file was forked.

### SessionInfo Resolution

While the file stores a filesystem path, the REST API exposes a session ID for client consumption.

In [`lib/session-reader.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-reader.ts) (lines 64-66), the code resolves the path to an identifier:

```ts
const parentSessionId = header?.parentSession
  ? await resolveSessionIdByPath(header.parentSession)
  : undefined;

```

The `GET /api/sessions/[id]` endpoint returns this `parentSessionId` to the frontend, allowing the interface to display links such as "child of..." and enabling client-side sorting and grouping.

## How parentSession Tracks Session Lineage

### Recording Forks in rpc-manager.ts

When a user initiates a fork, the system immediately records the lineage in the new file's header.

According to [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) (lines 66-70), the fork operation executes:

```ts
// Inside case "fork":
const currentSessionFile = this.inner.sessionFile;
const newManager = SessionManager.create(sessionManager.getCwd(), sessionDir);
newManager.newSession({ parentSession: currentSessionFile });

```

This writes a new JSONL file with a header containing the `parentSession` field pointing to the original file path. The UI sidebar then visualizes this connection as a branch in the tree.

### Cascade Reparenting on Delete

The system maintains hierarchy integrity even when parent sessions are deleted.

In `app/api/sessions/[id]/route.ts` (lines 118-141), the DELETE handler implements cascade reparenting:

```ts
const parentSessionPath = readSessionHeader(filePath)?.parentSession;
for (const childFile of siblingFiles) {
  const childHeader = JSON.parse(firstLine);
  if (childHeader.parentSession && sessionPathKey(childHeader.parentSession) === targetPathKey) {
    childHeader.parentSession = parentSessionPath; // Promote to grandparent
    writeFileSync(childFile, updatedLines);
  }
}

```

After deletion, direct children automatically point to the original session's parent (or clear the field if none exists), ensuring the tree remains valid and navigable without orphaning files.

## Display-Only Semantics

The `parentSession` field is strictly metadata and does not influence runtime behavior.

As documented in [`AGENTS.md`](https://github.com/agegr/pi-web/blob/main/AGENTS.md) under "Fork must destroy the wrapper immediately," the field is **metadata only**; it does not impact how the Pi runtime merges messages, performs navigation, or executes logic. You can safely rewrite or remove this field without altering the session's substantive content—it exists solely to inform the web interface about file lineage.

## Summary

- **`parentSession`** stores an absolute file path in the session header JSONL, linking a fork to its origin session file.
- The REST API resolves this path to a `parentSessionId` in [`lib/session-reader.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-reader.ts) for frontend consumption rather than exposing filesystem details.
- Fork creation in [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) writes this metadata to establish the parent-child relationship at instantiation time.
- The delete handler in `app/api/sessions/[id]/route.ts` automatically rewrites `parentSession` on children to point to the grandparent, maintaining tree consistency.
- This field is purely for UI visualization and has no effect on session execution logic or message merging.

## Frequently Asked Questions

### Does parentSession affect how Pi merges conversation messages?

No. According to the [`AGENTS.md`](https://github.com/agegr/pi-web/blob/main/AGENTS.md) specification and source analysis, the `parentSession` field is display-only metadata. It does not influence message merging, navigation logic, or runtime execution. It exists solely for visualization in the web interface.

### What happens to child sessions when I delete a parent session?

The server automatically performs cascade reparenting. As implemented in `app/api/sessions/[id]/route.ts`, when a session is deleted, any direct children have their `parentSession` field updated to point to the deleted session's parent, or the field is cleared if no parent exists. This preserves the hierarchy without orphaning files.

### Why does the API return parentSessionId instead of the file path?

The `SessionHeader` stores an absolute file path for internal consistency, but the REST API (`GET /api/sessions/[id]`) returns a `parentSessionId`. This abstraction, handled in [`lib/session-reader.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-reader.ts), decouples the client from filesystem specifics and allows the UI to reference sessions by stable identifiers rather than volatile absolute paths.

### Can I manually edit the parentSession field in a JSONL file?

Yes, it is safe to modify or remove the `parentSession` field manually. Since it is display-only metadata with no runtime impact, changing it only affects how the UI renders the session tree. However, ensure any edits maintain valid JSON syntax to prevent header parsing errors when the server reads the file.