> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensorlake.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Sessions

> Inspect, resume, restore, and clean up versioned file system sessions.

A mount path is ephemeral. Server autosaves and permanent snapshots are the durable state behind it. A writable session also owns a local crash-safe journal, so the same machine can recover changes that had not reached the server when the mount stopped.

Use these commands, or their SDK equivalents, to inspect a session, resume it, browse its history, restore an earlier checkpoint or snapshot, or delete a file system.

## Check Status

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    $ tl fs status /work
    filesystem: agent-scratch
    session: 54398548341c (created 12m ago)
    mode: writable — every save becomes the filesystem's current state
    autosave: settled changes replicate in about 1s (5s max while continuously writing)
    last autosave: 2m ago
    permanent snapshots: 1
    daemon: serving save 8b21f6a9
    log: ~/.local/share/tensorlake/mounts/54398548341c.../daemon.log
    local: clean
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from tensorlake.filesystem import FilesystemClient

    client = FilesystemClient()

    status = client.mount_status("/work")
    print(status.filesystem, status.mounted)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { FilesystemClient } from "tensorlake";

    const client = new FilesystemClient();

    const status = await client.mountStatus("/work");
    console.log(status.filesystem, status.mounted);
    ```
  </Tab>
</Tabs>

With unsaved changes, status lists dirty paths:

```bash theme={null}
local: 2 change(s):
  M src/parser.py
  D src/old_parser.py
```

Two more lines appear as a session ages:

* `retained:` counts files already published and kept locally as the byte cache. They are durable; the local copies only make reads and future autosaves fast. `tl fs snapshot --clear` trims cache entries covered by that snapshot while preserving later writes and ignored files.
* `ignored:` counts local-only files that never enter an autosave or snapshot (build output and the like, per the file system's ignore rules).

Add `--json` for machine-readable output; the SDK's `MountStatus.raw` carries the same structured payload.

## Browse History

```bash theme={null}
$ tl fs history agent-scratch
Autosave WAL (fixed native_fs_v1): each checkpoint is synchronously replicated to the shared drive; keep the newest 256 generations and all generations from the last 24h. Snapshots are permanent until you delete them.

Snapshots (permanent — kept until deleted)
4d9a2f7e  baseline benchmarks  1h ago

Recent autosave WAL (ephemeral — truncated automatically)
8b21f6a9  2m ago
e3f421a7  3h ago
```

Autosaves provide a recent recovery window. Create a permanent, billed snapshot as part of the changed generation you need to keep:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    $ tl fs snapshot /work -m "baseline benchmarks"
    Snapshot 4d9a2f7e "baseline benchmarks" — kept until deleted.
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    mount.snapshot("baseline benchmarks")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    await mount.snapshot("baseline benchmarks");
    ```
  </Tab>
</Tabs>

Permanent snapshots are exempt from automatic retention. Snapshotting a clean mount promotes its
current automatic save to permanent retention in place, without uploading file bytes or creating a
duplicate content version. It is a quiet no-op only when the current save is already permanent.
Drop a permanent snapshot you no longer need with `tl fs delete-snapshot agent-scratch <snapshot-id>`.

## List Sessions

```bash theme={null}
$ tl fs ls agent-scratch
Session        Filesystem      Base       Saves   Mode         Mounted   Age
54398548341c   agent-scratch   e3f421a7   yes     publishing   /work     12m
```

`tl fs ls` with no argument lists your file systems.

## Resume a Session

Unmounting keeps the session by default:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    $ tl fs unmount /work
    Unmounted /work. Session 54398548341c kept — `tl fs mount agent-scratch <path>` resumes it.
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    mount.unmount()
    # or, without a Mount object: client.unmount("/work")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    await mount.unmount();
    // or, without a mount object: await client.unmount("/work");
    ```
  </Tab>
</Tabs>

Remounting the file system on a machine that has a detached session resumes that session, unsaved local changes included. The new mount path can be different:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    $ tl fs mount agent-scratch /work2
    Resumed session 54398548341c at its last durable checkpoint.
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    mount = client.mount("agent-scratch", "/work2")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const mount = await client.mount("agent-scratch", "/work2");
    ```
  </Tab>
</Tabs>

<Note>
  A session already mounted elsewhere mounts read-only if you mount its file system again. Unmount it there first to take writes.
</Note>

## Discard Local Changes

Throw away unsaved changes (and ignored files under the mount) with the mount:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    $ tl fs unmount /work --discard
    Unmounted /work (unsaved local changes discarded).
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    mount.unmount(discard=True)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    await mount.unmount(true);
    ```
  </Tab>
</Tabs>

Everything already published is untouched: autosave checkpoints and snapshots are immutable.

## Restore

Restore the mount contents to an earlier checkpoint or snapshot:

```bash theme={null}
$ tl fs restore /work 4d9a2f7e5b3d8c6a4f2e0d9b7c5a3f1e8d6b4c2a1029384756abcdef01234567
Restored /work to 4d9a2f7e as save 7c31e8a2 (no file bytes transferred).
```

You can restore to any autosave still inside the retention window or to any permanent snapshot.
Restore does not move the timeline backward or copy file bytes. It publishes a new automatic save
whose content points at the selected historical root, then waits for the mounted directory and its
kernel caches to converge before returning. Other writable and following mounts observe that new
shared state normally. Restoring over local changes requires `--discard`; create a permanent
snapshot first if they should survive.

## Repair a Session

If a session's local state is ever inconsistent (a hard sandbox kill mid-write, an interrupted resume), `tl fs doctor` inspects it and can repair the local journal. **Unmount first:** doctor operates on a detached session and never contacts the server, so it cannot run under a live mount.

```bash theme={null}
$ tl fs doctor /work --json
```

Pass `--repair-journal` to rebuild a damaged local journal. To re-point the session's base as part of that repair, add `--base <SNAPSHOT_OR_AUTOSAVE_ID>` (or `--base empty` to reset to an empty base); `--base` requires `--repair-journal`. Doctor only touches local session state: durable history is never modified, because it never talks to the server.

## Delete a File System

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    $ tl fs rm agent-scratch
    Delete filesystem agent-scratch and all of its history? This cannot be undone. [y/N]
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    client.delete("agent-scratch")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    await client.delete("agent-scratch");
    ```
  </Tab>
</Tabs>

Pass `-f` to skip the confirmation; the SDK clients delete without prompting. Deletion removes the file system, its history, and its sessions.