tithon 0.1.0__tar.gz

tithon-0.1.0/.gitattributes

@@ -0,0 +1,4 @@
+# The percent round-trip corpus is byte-exact by design (CRLF, no final
+# newline, trailing whitespace). Never let git normalize their line endings,
+# or scripts/v6.sh's 0-byte-diff guarantee would break on checkout.
+scripts/corpus/*.py -text

tithon-0.1.0/.gitignore

@@ -0,0 +1,66 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.hypothesis/
+.tox/
+.nox/
+.ipynb_checkpoints/
+.venv/
+
+# Node / TypeScript
+node_modules/
+*.tsbuildinfo
+.eslintcache
+*.log
+npm-debug.log*
+yarn-debug.log*
+coverage/
+*.lcov
+.nyc_output
+*.tgz
+.npm
+
+# Project
+# tithon daemon state (socket, journal, kernel connection files)
+.tithon/
+
+# esbuild output
+dist/
+out-int/
+
+# VSCode extension test runner
+.vscode-test/
+
+# packaged extension
+*.vsix
+
+# screenshot render artifacts during script test
+scripts/screenshots/
+
+# daemon startup log (nohup)
+nohup.out
+
+# Local Agent
+.claude/
+
+# OS
+.DS_Store
+Thumbs.db
+*.swp
+*~

tithon-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-17
+
+### Added
+
+- Initial alpha release of Tithon.
+- Persistent remote interactive Python sessions with loss-free journal.
+- Real-time cell output streaming and widget state mirroring.
+- VSCode extension to sync kernel state losslessly.

tithon-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+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.

tithon-0.1.0/PKG-INFO

@@ -0,0 +1,312 @@
+Metadata-Version: 2.4
+Name: tithon
+Version: 0.1.0
+Summary: Tithon - The immortal Python REPL that will set you free.
+Project-URL: Homepage, https://github.com/rnoro/tithon
+Project-URL: Documentation, https://tithon.readthedocs.io/
+Project-URL: Repository, https://github.com/rnoro/tithon
+Project-URL: Bug Tracker, https://github.com/rnoro/tithon/issues
+Project-URL: Discussions, https://github.com/rnoro/tithon/discussions
+Project-URL: Changelog, https://github.com/rnoro/tithon/blob/main/CHANGELOG.md
+Author-email: rnoro <rnoro5122@gmail.com>
+License: MIT License
+        
+        Copyright (c) [year] [fullname]
+        
+        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.
+License-File: LICENSE
+Keywords: interactive,jupyter,kernel,persistent,repl,vscode
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.11
+Requires-Dist: ipykernel>=6
+Requires-Dist: jupyter-client>=8
+Requires-Dist: websockets>=12
+Description-Content-Type: text/markdown
+
+> ### **Attention!**
+>
+> Currently Tithon is alpha version. It may has lots of bugs and issues.  
+> Please report issues when you find any bugs which can help me to develop Tithon.
+
+# Tithon
+
+**The immortal Python REPL that will set you free.** Tithon keeps an interactive
+Python (Jupyter) kernel running on a remote host independently of any client,
+and losslessly restores cell output, progress, and widget state whenever a
+client (re)connects — close your laptop mid-run, reopen over an SSH/VSCode
+tunnel hours later, and your outputs are still there and still streaming.
+
+> The name is from Tithonus of Greek myth, granted immortality but not eternal
+> youth — like a remote kernel that stays alive while its outputs wither the
+> moment the client disconnects. Tithon lifts the curse: _immortality, with
+> eternal youth this time._
+
+The authoritative design document is [`docs/SPEC.md`](docs/SPEC.md); it also
+covers current implementation maturity and the verification matrix.
+
+---
+
+## Features
+
+- **Kernel persistence.** The kernel is spawned detached (`setsid`) and is not a
+  child of the daemon, so it survives daemon restarts, crashes, and disconnects.
+- **Loss-free journal.** Every iopub/shell message is preserved verbatim in a
+  SQLite (WAL) journal, plus a per-execution _folded_ snapshot (the current
+  display state) for fast reconnects.
+- **Snapshot + delta sync.** Clients attach with a `last_seen_seq` and receive a
+  snapshot followed by a monotonic-sequence delta stream — gapless and ordered.
+- **Live streaming with bounded cost.** Output streams to cells _as it runs_;
+  rendering is coalesced so a 50,000-iteration loop collapses to a handful of
+  UI updates instead of melting the renderer.
+- **Outputs live in the journal, not the file.** A percent-format `.py` stays
+  pure source (byte-exact round-trip, clean diffs); outputs are reattached to
+  cells by content hash. Rich outputs (images) are stored as files, not base64.
+- **Widget state mirror.** `ipywidgets` comm traffic is folded into a
+  `widget-state+json` snapshot — a `tqdm` bar with 50k updates reconnects as a
+  single bar, not 50k events.
+- **Host protection.** A slow or stalled client cannot grow daemon memory
+  without bound or block other clients; the daemon caps per-subscriber buffers
+  and drops clients that fall too far behind (they reconnect and resync).
+- **Unix-socket only.** The daemon binds a `0600` unix domain socket — no TCP.
+
+---
+
+## How it works
+
+```
+   VSCode / CLI client                    Remote Host
+  ┌────────────────────┐                 ┌───────────────────────────────┐
+  │ subscribe(last_seq)│ ── unix sock ── │  tithon daemon                │
+  │ snapshot + delta   │ ◀───0600─────  │   ├─ journal (SQLite WAL)     │
+  │ restore / live     │                 │   ├─ folded snapshots         │
+  └────────────────────┘                 │   └─ widget mirror            │
+                                         │            │ ZMQ (detached)   │
+                                         │      ┌─────┴───────┐          │
+                                         │      │  ipykernel  │ survives │
+                                         │      └─────────────┘ restarts │
+                                         └───────────────────────────────┘
+```
+
+The daemon owns the kernel and journals everything it emits. Clients never talk
+to the kernel directly — they sync against the journal, so any number of clients
+can connect and disconnect at any time and always converge on the same state.
+
+---
+
+## Requirements
+
+- **Python 3.11+** (the daemon and CLI).
+- [**uv**](https://github.com/astral-sh/uv) for environment management.
+- **Node 20+ / npm** — only to build or run the VSCode extension.
+
+---
+
+## Installation
+
+### Daemon + CLI
+
+```bash
+uv sync                          # create .venv (Python 3.11+), install tithon + dev deps
+```
+
+This puts a `tithon` entry point in `.venv/bin`. Run it with `uv run tithon …`,
+or call `.venv/bin/tithon` directly. Dependencies are managed with
+[uv](https://docs.astral.sh/uv/): runtime deps in `[project.dependencies]`, dev
+and verification deps in `[dependency-groups]`, all pinned by `uv.lock`.
+
+### VSCode extension
+
+The extension is not yet on the Marketplace; build it from source and either run
+it in a development host or package it as a `.vsix`:
+
+```bash
+cd extension
+npm install
+npm run build                    # tsc -> dist/
+npx vsce package                 # optional: -> tithon-extension-<version>.vsix
+```
+
+Press **F5** in `extension/` to launch an Extension Development Host, or install
+the `.vsix` (Extensions panel ▸ "Install from VSIX…"). For the remote workflow
+this project is built for, see
+[Remote workflow (VSCode tunnel)](#remote-workflow-vscode-tunnel) below; the
+automated integration harness is described in [`docs/SPEC.md`](docs/SPEC.md).
+
+---
+
+## Quickstart(CLI)
+
+State (socket, log, journal, artifacts) lives under `TITHON_HOME`, default
+`~/.tithon`.
+
+**1. Start the daemon** (it runs in the foreground; background it):
+
+```bash
+tithon daemon &
+tail -f ~/.tithon/daemon.log     # optional
+```
+
+**2. Run code** — kernel state persists across calls:
+
+```bash
+tithon run -c 'x = 41'
+tithon run -c 'x += 1; print(x)'     # -> 42
+tithon status
+```
+
+**3. Survive a disconnect** — the kernel outlives the daemon, and a reconnect
+restores everything:
+
+```bash
+tithon run -c 'for i in range(3): print("line", i)'
+
+pkill -9 -f 'tithon daemon'          # kill the daemon; the kernel lives on
+tithon daemon &                      # restart -> re-attaches the same kernel
+
+tithon attach --since 0 --once       # full snapshot: the prior output is back
+tithon run -c 'print(x)'             # -> 42, kernel state intact
+```
+
+---
+
+## Quickstart(Remote workflow)
+
+This is the workflow Tithon is built for: you edit from a laptop while the kernel
+runs on a remote GPU host and keeps running across your disconnects. With a
+VSCode **Tunnel** (or **Remote-SSH**) connection the VSCode _Extension Host_ runs
+**on the remote host**, so the Tithon extension reaches the daemon's host-local
+unix socket directly — no port forwarding. Your laptop only renders the UI, so
+closing it never stops the work.
+
+**On the remote host** — install (see [Installation](#installation)) and:
+
+```bash
+# 1. Start the daemon. It binds $TITHON_HOME/daemon.sock on the host
+#    (default ~/.tithon/daemon.sock) and owns the kernel.
+tithon daemon &
+
+# 2. Make the extension available to the remote VSCode — package it once...
+cd extension && npm install && npx vsce package    # -> tithon-extension-<version>.vsix
+#    ...then install the .vsix into the remote VSCode (Extensions ▸ "Install from
+#    VSIX…", or `code --install-extension tithon-extension-<version>.vsix`).
+#    During development you can instead open extension/ and press F5.
+
+# 3. Expose the host to VSCode.
+code tunnel                                        # or connect via Remote-SSH
+```
+
+**From your laptop:**
+
+1. Connect to the host (VSCode ▸ _Connect to Tunnel…_ or _Remote-SSH_) and open
+   your project folder.
+2. Open a percent-format `.py`. Run cells with the **Run Cell** CodeLens, then
+   run **Tithon: Start Live Output Sync** to stream output into the cells as it
+   is produced.
+3. Close the laptop or drop the connection — the daemon and kernel keep running
+   on the host.
+4. Reconnect later and run **Tithon: Restore Cell Outputs from Daemon** (or just
+   reopen the notebook): the outputs are back and resume streaming live.
+
+> **Note.** The daemon and the extension must share `TITHON_HOME` (both default
+> to `~/.tithon` for the same user on the host). Because the Extension Host runs
+> on the host, it uses the host-local socket — no manual forwarding. If you
+> instead run the extension on your laptop against a remote daemon, you must
+> forward the unix socket yourself (e.g. SSH `RemoteForward` or `socat`); that is
+> not the default path.
+
+---
+
+## CLI reference
+
+| Command              | Description                                                                                                                                        |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tithon daemon`      | Run the daemon (foreground). Owns the kernel and serves clients.                                                                                   |
+| `tithon run -c CODE` | Submit code and stream its output. `--no-wait` prints the exec id and exits; `--timeout N` bounds the wait.                                        |
+| `tithon attach`      | Stream events as NDJSON. `--since N` sets the resume point; `--once` exits after the backlog sync; `--until-done` exits after the next completion. |
+| `tithon status`      | Print session, queue, kernel, and widget-model status.                                                                                             |
+
+`attach --since` is the reconnect knob:
+
+- `--since 0` — full folded snapshot, then live delta.
+- `--since N` — replay only events after seq `N`, then a `sync` marker, then live.
+- `--since -1` — live only (ignore history).
+
+---
+
+## VSCode extension
+
+The extension opens percent-format `.py` files as a notebook (`tithon-py`) and
+talks to the daemon over its unix socket. Commands:
+
+| Command                                                              | What it does                                                                |
+| -------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `Tithon: Restore Cell Outputs from Daemon` (`tithon.restoreOutputs`) | Reconnect and restore the journal's folded outputs into the notebook cells. |
+| `Tithon: Start Live Output Sync` (`tithon.startLive`)                | Keep a session open and stream output into cells in real time.              |
+| `Run Cell` (CodeLens, `tithon.runCell`)                              | Submit a `# %%` cell's code to the daemon.                                  |
+
+Outputs are matched to cells by content hash, so they survive edits and reopens;
+an output whose cell was edited since it ran is flagged stale.
+
+---
+
+## Configuration
+
+Environment variables read by the daemon and CLI:
+
+| Variable                   | Default     | Purpose                                                            |
+| -------------------------- | ----------- | ------------------------------------------------------------------ |
+| `TITHON_HOME`              | `~/.tithon` | Root for the socket, log, journal, and artifacts.                  |
+| `TITHON_SUB_QUEUE_MAX`     | `10000`     | Max queued events per client before it is dropped (backpressure).  |
+| `TITHON_SEND_TIMEOUT`      | `10.0`      | Seconds a client may stall a send before being dropped.            |
+| `TITHON_WRITE_BUFFER_HIGH` | `1048576`   | Per-connection send-buffer high-water mark (bounds daemon memory). |
+| `TITHON_SOCK_SNDBUF`       | `1048576`   | Per-connection kernel socket send buffer.                          |
+| `TITHON_SUB_POLL`          | `0.5`       | Interval at which a blocked sender re-checks for drop.             |
+
+**Where outputs are stored.** A percent `.py` never holds outputs. They live in
+`$TITHON_HOME/sessions/default/journal.db` (raw messages + folded snapshots),
+with rich outputs (images) written as files under `<workdir>/.tithon/outputs/`
+and referenced from the journal.
+
+---
+
+## Architecture invariants
+
+These are load-bearing; see [`docs/SPEC.md`](docs/SPEC.md) for the full
+rationale.
+
+1. The kernel is spawned detached and its connection file is persisted, so the
+   daemon re-attaches to it after a restart.
+2. All iopub/shell messages are kept verbatim in SQLite (WAL), with a folded
+   per-execution snapshot maintained alongside.
+3. Client sync is snapshot + delta over a monotonically increasing sequence.
+4. Rich `image/*` outputs are stored as files, not base64 in the journal.
+5. The daemon binds a `0600` unix domain socket only — never TCP.
+
+---

tithon-0.1.0/README.md

@@ -0,0 +1,260 @@
+> ### **Attention!**
+>
+> Currently Tithon is alpha version. It may has lots of bugs and issues.  
+> Please report issues when you find any bugs which can help me to develop Tithon.
+
+# Tithon
+
+**The immortal Python REPL that will set you free.** Tithon keeps an interactive
+Python (Jupyter) kernel running on a remote host independently of any client,
+and losslessly restores cell output, progress, and widget state whenever a
+client (re)connects — close your laptop mid-run, reopen over an SSH/VSCode
+tunnel hours later, and your outputs are still there and still streaming.
+
+> The name is from Tithonus of Greek myth, granted immortality but not eternal
+> youth — like a remote kernel that stays alive while its outputs wither the
+> moment the client disconnects. Tithon lifts the curse: _immortality, with
+> eternal youth this time._
+
+The authoritative design document is [`docs/SPEC.md`](docs/SPEC.md); it also
+covers current implementation maturity and the verification matrix.
+
+---
+
+## Features
+
+- **Kernel persistence.** The kernel is spawned detached (`setsid`) and is not a
+  child of the daemon, so it survives daemon restarts, crashes, and disconnects.
+- **Loss-free journal.** Every iopub/shell message is preserved verbatim in a
+  SQLite (WAL) journal, plus a per-execution _folded_ snapshot (the current
+  display state) for fast reconnects.
+- **Snapshot + delta sync.** Clients attach with a `last_seen_seq` and receive a
+  snapshot followed by a monotonic-sequence delta stream — gapless and ordered.
+- **Live streaming with bounded cost.** Output streams to cells _as it runs_;
+  rendering is coalesced so a 50,000-iteration loop collapses to a handful of
+  UI updates instead of melting the renderer.
+- **Outputs live in the journal, not the file.** A percent-format `.py` stays
+  pure source (byte-exact round-trip, clean diffs); outputs are reattached to
+  cells by content hash. Rich outputs (images) are stored as files, not base64.
+- **Widget state mirror.** `ipywidgets` comm traffic is folded into a
+  `widget-state+json` snapshot — a `tqdm` bar with 50k updates reconnects as a
+  single bar, not 50k events.
+- **Host protection.** A slow or stalled client cannot grow daemon memory
+  without bound or block other clients; the daemon caps per-subscriber buffers
+  and drops clients that fall too far behind (they reconnect and resync).
+- **Unix-socket only.** The daemon binds a `0600` unix domain socket — no TCP.
+
+---
+
+## How it works
+
+```
+   VSCode / CLI client                    Remote Host
+  ┌────────────────────┐                 ┌───────────────────────────────┐
+  │ subscribe(last_seq)│ ── unix sock ── │  tithon daemon                │
+  │ snapshot + delta   │ ◀───0600─────  │   ├─ journal (SQLite WAL)     │
+  │ restore / live     │                 │   ├─ folded snapshots         │
+  └────────────────────┘                 │   └─ widget mirror            │
+                                         │            │ ZMQ (detached)   │
+                                         │      ┌─────┴───────┐          │
+                                         │      │  ipykernel  │ survives │
+                                         │      └─────────────┘ restarts │
+                                         └───────────────────────────────┘
+```
+
+The daemon owns the kernel and journals everything it emits. Clients never talk
+to the kernel directly — they sync against the journal, so any number of clients
+can connect and disconnect at any time and always converge on the same state.
+
+---
+
+## Requirements
+
+- **Python 3.11+** (the daemon and CLI).
+- [**uv**](https://github.com/astral-sh/uv) for environment management.
+- **Node 20+ / npm** — only to build or run the VSCode extension.
+
+---
+
+## Installation
+
+### Daemon + CLI
+
+```bash
+uv sync                          # create .venv (Python 3.11+), install tithon + dev deps
+```
+
+This puts a `tithon` entry point in `.venv/bin`. Run it with `uv run tithon …`,
+or call `.venv/bin/tithon` directly. Dependencies are managed with
+[uv](https://docs.astral.sh/uv/): runtime deps in `[project.dependencies]`, dev
+and verification deps in `[dependency-groups]`, all pinned by `uv.lock`.
+
+### VSCode extension
+
+The extension is not yet on the Marketplace; build it from source and either run
+it in a development host or package it as a `.vsix`:
+
+```bash
+cd extension
+npm install
+npm run build                    # tsc -> dist/
+npx vsce package                 # optional: -> tithon-extension-<version>.vsix
+```
+
+Press **F5** in `extension/` to launch an Extension Development Host, or install
+the `.vsix` (Extensions panel ▸ "Install from VSIX…"). For the remote workflow
+this project is built for, see
+[Remote workflow (VSCode tunnel)](#remote-workflow-vscode-tunnel) below; the
+automated integration harness is described in [`docs/SPEC.md`](docs/SPEC.md).
+
+---
+
+## Quickstart(CLI)
+
+State (socket, log, journal, artifacts) lives under `TITHON_HOME`, default
+`~/.tithon`.
+
+**1. Start the daemon** (it runs in the foreground; background it):
+
+```bash
+tithon daemon &
+tail -f ~/.tithon/daemon.log     # optional
+```
+
+**2. Run code** — kernel state persists across calls:
+
+```bash
+tithon run -c 'x = 41'
+tithon run -c 'x += 1; print(x)'     # -> 42
+tithon status
+```
+
+**3. Survive a disconnect** — the kernel outlives the daemon, and a reconnect
+restores everything:
+
+```bash
+tithon run -c 'for i in range(3): print("line", i)'
+
+pkill -9 -f 'tithon daemon'          # kill the daemon; the kernel lives on
+tithon daemon &                      # restart -> re-attaches the same kernel
+
+tithon attach --since 0 --once       # full snapshot: the prior output is back
+tithon run -c 'print(x)'             # -> 42, kernel state intact
+```
+
+---
+
+## Quickstart(Remote workflow)
+
+This is the workflow Tithon is built for: you edit from a laptop while the kernel
+runs on a remote GPU host and keeps running across your disconnects. With a
+VSCode **Tunnel** (or **Remote-SSH**) connection the VSCode _Extension Host_ runs
+**on the remote host**, so the Tithon extension reaches the daemon's host-local
+unix socket directly — no port forwarding. Your laptop only renders the UI, so
+closing it never stops the work.
+
+**On the remote host** — install (see [Installation](#installation)) and:
+
+```bash
+# 1. Start the daemon. It binds $TITHON_HOME/daemon.sock on the host
+#    (default ~/.tithon/daemon.sock) and owns the kernel.
+tithon daemon &
+
+# 2. Make the extension available to the remote VSCode — package it once...
+cd extension && npm install && npx vsce package    # -> tithon-extension-<version>.vsix
+#    ...then install the .vsix into the remote VSCode (Extensions ▸ "Install from
+#    VSIX…", or `code --install-extension tithon-extension-<version>.vsix`).
+#    During development you can instead open extension/ and press F5.
+
+# 3. Expose the host to VSCode.
+code tunnel                                        # or connect via Remote-SSH
+```
+
+**From your laptop:**
+
+1. Connect to the host (VSCode ▸ _Connect to Tunnel…_ or _Remote-SSH_) and open
+   your project folder.
+2. Open a percent-format `.py`. Run cells with the **Run Cell** CodeLens, then
+   run **Tithon: Start Live Output Sync** to stream output into the cells as it
+   is produced.
+3. Close the laptop or drop the connection — the daemon and kernel keep running
+   on the host.
+4. Reconnect later and run **Tithon: Restore Cell Outputs from Daemon** (or just
+   reopen the notebook): the outputs are back and resume streaming live.
+
+> **Note.** The daemon and the extension must share `TITHON_HOME` (both default
+> to `~/.tithon` for the same user on the host). Because the Extension Host runs
+> on the host, it uses the host-local socket — no manual forwarding. If you
+> instead run the extension on your laptop against a remote daemon, you must
+> forward the unix socket yourself (e.g. SSH `RemoteForward` or `socat`); that is
+> not the default path.
+
+---
+
+## CLI reference
+
+| Command              | Description                                                                                                                                        |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tithon daemon`      | Run the daemon (foreground). Owns the kernel and serves clients.                                                                                   |
+| `tithon run -c CODE` | Submit code and stream its output. `--no-wait` prints the exec id and exits; `--timeout N` bounds the wait.                                        |
+| `tithon attach`      | Stream events as NDJSON. `--since N` sets the resume point; `--once` exits after the backlog sync; `--until-done` exits after the next completion. |
+| `tithon status`      | Print session, queue, kernel, and widget-model status.                                                                                             |
+
+`attach --since` is the reconnect knob:
+
+- `--since 0` — full folded snapshot, then live delta.
+- `--since N` — replay only events after seq `N`, then a `sync` marker, then live.
+- `--since -1` — live only (ignore history).
+
+---
+
+## VSCode extension
+
+The extension opens percent-format `.py` files as a notebook (`tithon-py`) and
+talks to the daemon over its unix socket. Commands:
+
+| Command                                                              | What it does                                                                |
+| -------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `Tithon: Restore Cell Outputs from Daemon` (`tithon.restoreOutputs`) | Reconnect and restore the journal's folded outputs into the notebook cells. |
+| `Tithon: Start Live Output Sync` (`tithon.startLive`)                | Keep a session open and stream output into cells in real time.              |
+| `Run Cell` (CodeLens, `tithon.runCell`)                              | Submit a `# %%` cell's code to the daemon.                                  |
+
+Outputs are matched to cells by content hash, so they survive edits and reopens;
+an output whose cell was edited since it ran is flagged stale.
+
+---
+
+## Configuration
+
+Environment variables read by the daemon and CLI:
+
+| Variable                   | Default     | Purpose                                                            |
+| -------------------------- | ----------- | ------------------------------------------------------------------ |
+| `TITHON_HOME`              | `~/.tithon` | Root for the socket, log, journal, and artifacts.                  |
+| `TITHON_SUB_QUEUE_MAX`     | `10000`     | Max queued events per client before it is dropped (backpressure).  |
+| `TITHON_SEND_TIMEOUT`      | `10.0`      | Seconds a client may stall a send before being dropped.            |
+| `TITHON_WRITE_BUFFER_HIGH` | `1048576`   | Per-connection send-buffer high-water mark (bounds daemon memory). |
+| `TITHON_SOCK_SNDBUF`       | `1048576`   | Per-connection kernel socket send buffer.                          |
+| `TITHON_SUB_POLL`          | `0.5`       | Interval at which a blocked sender re-checks for drop.             |
+
+**Where outputs are stored.** A percent `.py` never holds outputs. They live in
+`$TITHON_HOME/sessions/default/journal.db` (raw messages + folded snapshots),
+with rich outputs (images) written as files under `<workdir>/.tithon/outputs/`
+and referenced from the journal.
+
+---
+
+## Architecture invariants
+
+These are load-bearing; see [`docs/SPEC.md`](docs/SPEC.md) for the full
+rationale.
+
+1. The kernel is spawned detached and its connection file is persisted, so the
+   daemon re-attaches to it after a restart.
+2. All iopub/shell messages are kept verbatim in SQLite (WAL), with a folded
+   per-execution snapshot maintained alongside.
+3. Client sync is snapshot + delta over a monotonically increasing sequence.
+4. Rich `image/*` outputs are stored as files, not base64 in the journal.
+5. The daemon binds a `0600` unix domain socket only — never TCP.
+
+---