@moikapy/lich 0.7.0 → 0.8.0

package/docs/architecture/tools.md

@@ -38,8 +38,9 @@ result either way.
 
 **`ToolContext`** gives each execution a working directory (`work_dir`, the
 confinement root), a process environment map (the agent injects
-`LICH_TERMINAL_TIMEOUT_MS`), and an abort `signal` that fires on caller abort
-**or** the executor deadline (`tool.timeout_ms`, else
+`LICH_TERMINAL_TIMEOUT_MS`), and an optional abort `signal` the agent passes
+from `Agent.run` so tools cancel on caller abort **or** the executor deadline
+(`tool.timeout_ms`, else
 `DEFAULT_TOOL_TIMEOUT_MS` = 30000). `terminal` sets 300000, `run_tests` sets
 600000, and registered MCP tools set 120000.
 
@@ -151,7 +152,7 @@ Docs tools join the list only when a docs root resolves.
 | `edit_file` | `path`, `old_string`, `new_string`, `replace_all?` | Fails `old_string_not_found` / `old_string_not_unique (N)` unless `replace_all` - an exact-match protocol that forces the model to anchor edits. |
 | `list_dir` | `path?`, `depth?` (1-4) | Iterative worklist (no recursion), dirs-first sorting, skips `node_modules`/`.git`/`dist`/`.lich`/`.cursor`, caps at 500 entries, file sizes via `stat`. |
 | `terminal` | `command`, `timeout_ms?` | Spawns `bash -lc`, streams and caps stdout+stderr at 50 K chars, SIGKILLs on deadline, appends `[exit N]`; `ok` requires exit code 0 and no cancellation. |
-| `grep_files` | `pattern`, `path?`, `glob?`, `max_results?` | Explicit stack walk (no recursion), binary sniff (NUL byte in first 1000 bytes), 1 MB file cap, `*.ext` suffix-glob matcher, overcollect-by-one to report suppressed counts. |
+| `grep_files` | `pattern`, `path?`, `glob?`, `max_results?` | Explicit stack walk (no recursion), skips `SKIP_DIRS` entries and symbolic links, per-file `assert_file_tool_access` check (`.lich/config.json` is denied), binary sniff (NUL byte in first 1000 bytes), 1 MB file cap, `*.ext` suffix-glob matcher, overcollect-by-one to report suppressed counts. |
 | `fetch_url` | `url`, `max_chars?`, `timeout_ms?` | GET only; rejects non-http(s) protocols; refuses images/octet-stream; tags HTML bodies with `[html content]`; status/type header line first. |
 | `web_search` | `query`, `max_results?` | Scrapes DuckDuckGo's HTML endpoint (no API key); unwraps `uddg=` redirect links; decodes the handful of entities DDG emits. |
 | `http_request` | `url`, `method?`, `headers?`, `body?`, ... | Method allowlist (GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS); stringified caller headers; reports `content-length`, `ratelimit-remaining`, `retry-after`. |
@@ -166,6 +167,32 @@ allowlist), `compose_abort_signal` (per-call `AbortSignal.timeout` merged
 with the executor's cancellation via `AbortSignal.any`), and `clamp_int_arg`
 (floored, bounded to `[1, max]`).
 
+`grep_files` also runs `assert_file_tool_access` on every candidate path
+(the same deny list as `read_file`/`write_file`/`edit_file`): a direct
+grep of `.lich/config.json` fails with `forbidden_path:
+.lich/config.json`. During the walk, symbolic links are skipped on the
+same branch as `SKIP_DIRS`, so symlink entries are neither followed nor
+searched.
+
+### HTTP tools and `safe_fetch` - pinned outbound requests
+
+`fetch_url` and `http_request` send every request through `safe_fetch`
+([`src/tools/url_guard.ts`](../../src/tools/url_guard.ts)). Per hop:
+
+1. `resolve_public_ip` resolves the hostname and rejects private,
+   loopback, link-local, and ULA addresses (`blocked_url:`), including
+   `localhost` / `*.localhost` / `*.local` names.
+2. The request is then issued with the **original hostname** kept for
+   TLS/SNI and the `Host` header - the URL is not rewritten to the IP.
+   The connect is pinned instead: a custom DNS `lookup` function handed
+   to `http(s).request` returns only the already-vetted public IP.
+3. Redirects are followed manually (`redirect: "manual"`) and every
+   `Location` hop is re-resolved and re-vetted, up to 5 hops.
+
+The operator opt-out is exact: `LICH_ALLOW_PRIVATE_URLS=1` allows
+private targets (the value is compared to `"1"`), while unset or any
+other value is fail-closed and private URLs stay blocked.
+
 ## Docs search and skills
 
 `docs_search` scores sections under the resolved docs root (memoized) and, when

package/docs/getting-started.md

@@ -10,7 +10,7 @@
 
 ```sh
 npm install -g @moikapy/lich
-lich --version   # -> 0.6.0 (reads package.json)
+lich --version   # -> 0.7.0 (reads package.json)
 ```
 
 ## Choose a configuration path
@@ -153,7 +153,7 @@ To hack on Lich itself, run the CLI straight from a clone instead of the npm pac
 ```sh
 git clone https://github.com/Moikapy/lich.git && cd lich
 bun install
-bun src/cli.ts --version   # -> 0.6.0 (package.json; MCP in this tree is unreleased)
+bun src/cli.ts --version   # -> 0.7.0 (package.json)
 ```
 
 `bun src/cli.ts` accepts the same arguments as the installed `lich` binary, so every command on this page works unchanged.
@@ -165,4 +165,4 @@ bun src/cli.ts --version   # -> 0.6.0 (package.json; MCP in this tree is unrelea
 - Telegram, Discord, Twitch, and webhook setup: [Gateway guide](user-guide/gateway.md).
 - Embedding the agent in your own TypeScript: [Library guide](user-guide/library.md).
 - Session JSONL as a combat log: [Games guide](user-guide/games.md).
-- Editor MCP (`lich mcp`, unreleased in the published 0.6.0 package): [Redot guide](user-guide/redot.md). Play is still the [Godot guide](user-guide/godot.md).
+- Editor MCP (`lich mcp`): [Redot guide](user-guide/redot.md). Play is still the [Godot guide](user-guide/godot.md).

package/docs/index.md

@@ -68,4 +68,4 @@ Working from a clone of the repository? `bun install`, then run the same command
 
 ## Version compatibility
 
-The published npm package is **0.6.0**. `lich --version` reads `package.json`, so this tree also prints `0.6.0`. Editor MCP (`mcp_servers`, `lich mcp`) is in this source under changelog **0.7.0 (unreleased)** and is not in the published package. Node >= 20 (`engines` in `package.json`); Bun is the recommended runtime for development from a clone (`bun src/cli.ts ...`). The TUI needs a TTY; the gateway and library run headless on both runtimes.
+The published npm package is **0.7.0**. `lich --version` reads `package.json`. Editor MCP (`mcp_servers`, `lich mcp`) ships in 0.7.0. Node >= 20 (`engines` in `package.json`); Bun is the recommended runtime for development from a clone (`bun src/cli.ts ...`). The TUI needs a TTY; the gateway and library run headless on both runtimes.

package/docs/user-guide/cli.md

@@ -19,7 +19,7 @@ lich mcp enable <name> # set enabled true
 lich mcp disable <name>
 lich mcp remove <name>
 lich --help            # usage text
-lich --version         # package.json version (published package and this tree: 0.6.0)
+lich --version         # package.json version (published package and this tree: 0.7.0)
 ```
 
 - **Bare `lich`** opens the same TUI as `lich tui`. It does not print usage. On a TTY, if neither `.lich/config.json` nor `~/.config/lich/config.json` exists, a setup wizard runs first (name, provider, optional gateway env-var names, optional plugins) and writes `.lich/config.json` once. `LICH_MODEL` / `--model` prefills the model prompt; it does not skip the wizard. An existing config in that chain skips the wizard and is not replaced. Non-TTY stdin skips the wizard and prints guidance instead of hanging. `lich --help` still prints usage.
@@ -29,9 +29,9 @@ lich --version         # package.json version (published package and this tree:
 - **TUI** launches the ink interface. See the [TUI guide](tui.md).
 - **Gateway** runs platform adapters (defaults to `webhook` when no platform is given). See the [Gateway guide](gateway.md). Unknown platform names are skipped with a warning; if none remain, the CLI exits `1`.
 - **Update** compares the installed version to the npm registry and, when a newer release exists, runs `npm install -g @moikapy/lich@latest`. Exit any running TUI or gateway first; npm cannot replace the package while those processes are running. A git clone is told to `git pull`. See [Updating](../getting-started.md#updating).
-- **MCP** is in this source (changelog 0.7.0, unreleased). The published 0.6.0 npm package does not include `lich mcp`. It edits only `mcp_servers` in `<work-dir>/.lich/config.json` through the same writer as `lich init` (`update` mode, so other keys stay). A missing file lists as empty; `add` creates the file if needed. New entries stay disabled until `enable`. Names must match `^[a-z][a-z0-9_]*$`. Catalog names use `optional-mcps/`; otherwise pass `--command` and repeatable `--arg`, or `--url` (loopback only), not both. Redot still needs `--project-path` for the catalog args, and the command basename must be `redot`. No prompts. See the [Redot guide](redot.md).
+- **MCP** ships in 0.7.0 (`lich mcp`). It edits only `mcp_servers` in `<work-dir>/.lich/config.json` through the same writer as `lich init` (`update` mode, so other keys stay). A missing file lists as empty; `add` creates the file if needed. New entries stay disabled until `enable`. Names must match `^[a-z][a-z0-9_]*$`. Catalog names use `optional-mcps/`; otherwise pass `--command` and repeatable `--arg`, or `--url` (loopback only), not both. Redot still needs `--project-path` for the catalog args, and the command basename must be `redot`. No prompts. See the [Redot guide](redot.md).
 
-A repository clone's `bun src/cli.ts` matches that checkout. The published 0.6.0 binary does not include `lich mcp`.
+A repository clone's `bun src/cli.ts` matches that checkout. The published 0.7.0 binary includes `lich mcp`.
 
 ## Flags
 
@@ -48,6 +48,7 @@ Flags work before or after the subcommand. Every value flag can also be set via
 | `--api-key-env <NAME>` | Env var holding the api key for `providers[0]`. | `LICH_API_KEY_ENV`, else per-kind default |
 | `--system-prompt <s>` | Replaces the default system prompt. | built-in concise-assistant prompt |
 | `--session-dir <path>` | Transcript directory. | `<work_dir>/.lich/sessions` |
+| `--resume <id\|latest>` | TUI only: load an existing session transcript into history. Exact id, unique filename prefix, or `latest` (newest by mtime). | – |
 | `--log-level <level>` | `debug` \| `info` \| `warn` \| `error`. | `info` |
 | `--theme <name>` | Display theme loaded once at startup. `lich` is built-in; other names read `~/.lich/themes/<name>.json`. | `lich` |
 | `--command <bin>` | `lich mcp add` only: local stdio binary. | – |
@@ -55,7 +56,7 @@ Flags work before or after the subcommand. Every value flag can also be set via
 | `--url <url>` | `lich mcp add` only: loopback HTTP MCP URL. | – |
 | `--project-path <path>` | `lich mcp add` only: catalog `${project_path}` substitute. | – |
 
-Passing `--max-turns 0` or a non-integer fails with `--max-turns must be a positive integer`. Unknown flags fail with `unknown flag: --foo`. A flag missing its value fails with `<flag> requires a value`.
+Passing `--max-turns 0` or a non-integer fails with `--max-turns must be a positive integer`. Unknown flags fail with `unknown flag: --foo`. A flag missing its value fails with `<flag> requires a value`. `--resume` outside the TUI (one-shot, `chat`, `gateway`) fails with `--resume is only supported in TUI mode (not <mode>)`.
 
 ## Provider resolution
 
@@ -127,7 +128,7 @@ Validated by zod (top-level unknown keys are silently stripped; extra keys insid
 | `theme` | string | `lich` | Display theme name. See [Themes](https://github.com/Moikapy/lich/blob/main/README.md#themes). |
 | `gateway` | object | omitted | Optional. `platforms` (`webhook` \| `telegram` \| `discord` \| `twitch`) and `token_envs` (platform → env-var name). Secrets stay in the environment. |
 | `plugins` | string array | `[]` | Module paths relative to `work_dir` or absolute. Bare `lich`, one-shot, chat, tui, and gateway load them through `create_agent_with_plugins`. `run_agent` does too. `create_agent` does not. See the [plugins guide](plugins.md). |
-| `mcp_servers` | object | omitted | Optional. Closed record of named servers. Each entry is stdio `{command, args, env?}` or loopback http `{url}`. `enabled` defaults to false. Unknown keys are rejected. In this source only (0.7.0 unreleased; not in the published 0.6.0 package). See the [Redot guide](redot.md). |
+| `mcp_servers` | object | omitted | Optional. Closed record of named servers. Each entry is stdio `{command, args, env?}` or loopback http `{url}`. `enabled` defaults to false. Unknown keys are rejected. Ships in 0.7.0. See the [Redot guide](redot.md). |
 | `system_prompt` | string | built-in | Replaces the default system prompt. |
 | `max_turns` | int >= 1 | `25` | Turn budget per run. |
 | `work_dir` | string | cwd | Root for all file tools; paths outside are rejected. |
@@ -160,6 +161,7 @@ never accepted as a config passthrough.
 | Variable | Meaning |
 | --- | --- |
 | `LICH_ALLOW_SELF_COMMIT` | Set to `1` to allow one gated `git_commit` per run. Unset or any other value is fail-closed. Read at agent construction. |
+| `LICH_ALLOW_PRIVATE_URLS` | Set to exactly `1` to let `fetch_url` / `http_request` reach private or loopback URLs. Unset or any other value is fail-closed (they are blocked). |
 | `LICH_TEST_COMMAND` | Command `run_tests` runs in `work_dir` (default `node node_modules/vitest/vitest.mjs run`). An optional `filter` argument is appended. |
 
 Veto reasons, the terminal git denylist, skills, and `MEMORY.md` are in the
@@ -173,6 +175,12 @@ Each run writes `.lich/sessions/<timestamp36>-<counter>[-label].jsonl` where the
 # follow the newest session
 ls -t .lich/sessions/*.jsonl | head -1
 
+# resume that session in the TUI (loads history; new turns append to one
+# per-launch transcript via incremental persistence).
+# Inside a running TUI, `/resume <id|latest>` uses the same load path (Phase 3).
+lich --resume latest
+lich tui --resume m1abc-1-tui
+
 # print the conversation
 jq -r 'select(.kind=="message") | "\(.message.role): \(.message.content // "(tool call)")"' .lich/sessions/<file>.jsonl
 ```

package/docs/user-guide/games.md

@@ -8,7 +8,7 @@ Tool shapes live in [`examples/game_bridge/README.md`](https://github.com/Moikap
 
 ## Session files as combat logs
 
-Each `Agent.run` appends one `.jsonl` file under `session_dir` (default `<work_dir>/.lich/sessions`). Records are `{ts, kind: "message"|"meta", message?, meta?}`.
+Each `Agent.run` without a shared `session` handle appends one `.jsonl` file under `session_dir` (default `<work_dir>/.lich/sessions`). The TUI passes one handle per launch so N turns share one file. Records are `{ts, kind: "message"|"meta", message?, meta?}`.
 
 | What you want | Where it is |
 | --- | --- |
@@ -75,9 +75,9 @@ Recipe 2 counts assistant tool-call arguments, including orders a hook later vet
 
 ## Do not glob a playthrough blindly
 
-A gateway conversation of N posts writes N files. `Agent.run` seeds from `history`, and `persist_session` appends all of `outcome.messages`, so each file is a superset of the previous exchange. Globbing `*.jsonl` double-counts. Take the newest file per label (names sort by timestamp prefix), or dedupe on `tool_call.id`, which stays stable when the same call is replayed into the next file.
+A gateway conversation of N posts writes N files. `Agent.run` seeds from `history`, and without a shared `session` handle each run opens a new file that includes prior history plus the new exchange, so each file is a superset of the previous. Globbing `*.jsonl` double-counts. Take the newest file per label (names sort by timestamp prefix), or dedupe on `tool_call.id`, which stays stable when the same call is replayed into the next file. TUI launches avoid this by sharing one handle.
 
-Compression can rewrite a long run in place: when estimated tokens cross `compress_threshold` of `context_budget_tokens`, older messages become one summary and the 8 most recent non-system messages stay verbatim. Early rounds may survive only as that summary. The recipes see the file on disk, not the pre-compression transcript.
+Compression can rewrite in-memory history: when estimated tokens cross `compress_threshold` of `context_budget_tokens`, older messages become one summary and the 8 most recent non-system messages stay verbatim. The transcript keeps raw pre-compress messages plus a `compress_end` meta marker; on resume those raw messages replay and compression may run again. Early rounds may survive only as the in-memory summary for the live agent. Offline recipes see the file on disk.
 
 ## Player modeling
 

package/docs/user-guide/gateway.md

@@ -27,37 +27,54 @@ lich gateway                         # defaults to webhook
 
 The gateway is silent after startup: Telegram/Discord/Twitch respond only in chats, channels, or servers the bot can see or has joined, and the webhook only serves HTTP. Telegram media messages arrive as the placeholder text `media not supported yet`; other non-text events are ignored. Telegram `/start` is answered like a plain "hello".
 
+**Security defaults:** the webhook binds loopback only; Telegram/Discord/Twitch default-deny until you configure allowlists; the gateway agent uses a read-only tool subset (no `terminal`, no file writes) unless you override `gateway.tools_enabled`.
+
 ## Setup: webhook
 
-Zero configuration — the server binds `0.0.0.0:$LICH_GATEWAY_PORT` (default 8089).
+Zero configuration for local use — the server binds `127.0.0.1:$LICH_GATEWAY_PORT` (default 8089). Set `LICH_GATEWAY_HOST` only when you intentionally expose the port.
 
 ```sh
 lich gateway webhook
 ```
 
 ```sh
-curl -s -X POST http://localhost:8089/message \
+curl -s -X POST http://127.0.0.1:8089/message \
   -H "content-type: application/json" -d '{"text": "hello"}'
 # -> {"reply":"...","usage":null}
 
-curl -s http://localhost:8089/health
+curl -s http://127.0.0.1:8089/health
 # -> {"status":"ok"}
 ```
 
+To bind a non-loopback address you **must** set a token; otherwise the adapter refuses to start:
+
+```sh
+LICH_GATEWAY_HOST=0.0.0.0 LICH_GATEWAY_TOKEN=s3cret lich gateway webhook
+```
+
 With token auth, every POST must carry the exact `x-lich-token` header; mismatched or missing tokens get `401 {"error":"unauthorized"}`:
 
 ```sh
 LICH_GATEWAY_TOKEN=s3cret lich gateway webhook
-curl -s -X POST http://localhost:8089/message \
+curl -s -X POST http://127.0.0.1:8089/message \
   -H "x-lich-token: s3cret" -H "content-type: application/json" -d '{"text": "hello"}'
 ```
 
-Payload fields (all optional except `text`): `platform` (default `"webhook"`), `chat_id` (default `"default"`), `user_id` (default `"anonymous"`), `text` (required; missing `text` is a `400`). Use distinct `chat_id` values to keep independent conversation memories.
+Payload fields (all optional except `text`): `chat_id` (default `"default"`), `user_id` (default `"anonymous"`), `text` (required; missing `text` is a `400`). A `platform` field in the body is **ignored** — conversations are always keyed as `webhook:<chat_id>`. Use distinct `chat_id` values to keep independent conversation memories.
 
 ## Setup: Telegram
 
 1. Message [@BotFather](https://t.me/BotFather) → `/newbot` → copy the token.
-2. Export it and run:
+2. Allow your user (and optionally chat) ids in config, export the bot token, and run:
+
+```json
+{
+  "gateway": {
+    "allowed_users": { "telegram": ["123456789"] },
+    "allowed_chats": { "telegram": ["123456789"] }
+  }
+}
+```
 
 ```sh
 export LICH_TELEGRAM_BOT_TOKEN=123456:ABC-your-token
@@ -66,14 +83,22 @@ lich gateway telegram
 
 3. Open your bot in Telegram, send a message, get a reply. Media messages arrive as the text `media not supported yet`; the bot replies from there.
 
-Telegram uses long polling (no public URL needed). Replies split at 4096 chars.
+Without `allowed_users` / `allowed_chats` for `telegram`, every inbound message is denied (default-deny). Telegram uses long polling (no public URL needed). Replies split at 4096 chars.
 
 ## Setup: Discord
 
 1. Create an application at the [Discord developer portal](https://discord.com/developers/applications), add a **Bot**, and copy the bot token.
 2. Enable the **Message Content Intent** (Bot settings → Privileged Gateway Intents) — the adapter requests intents `512 | 32768`, which includes message content.
 3. Invite the bot with the `bot` scope (OAuth2 → URL Generator; no extra permissions needed beyond sending messages in target channels).
-4. Export the token (and the bot's application/user id, so leading `<@BOT_ID>` mentions are stripped) and run:
+4. Allow channel and/or user ids in config, export the token (and the bot's application/user id, so leading `<@BOT_ID>` mentions are stripped) and run:
+
+```json
+{
+  "gateway": {
+    "allowed_chats": { "discord": ["123456789012345678"] }
+  }
+}
+```
 
 ```sh
 export LICH_DISCORD_BOT_TOKEN=your-bot-token
@@ -81,14 +106,23 @@ export LICH_DISCORD_BOT_ID=123456789012345678
 lich gateway discord
 ```
 
-5. Send the bot a message (DM or any channel it can read — every non-bot message gets a reply); each channel has its own conversation memory (keyed by `channel_id`). Replies split at 2000 chars. Bot-authored messages are ignored (no loops).
+5. Send the bot a message in an allowed channel; each channel has its own conversation memory (keyed by `channel_id`). Replies split at 2000 chars. Bot-authored messages are ignored (no loops). Without allowlists for `discord`, every inbound message is denied.
 
 **Known limitation:** the Discord adapter has no reconnect resume. If its gateway WebSocket drops, messages sent while offline are missed permanently; the adapter reconnects fresh after 5s. If guaranteed delivery across disconnects matters, run webhook or Telegram instead.
 
 ## Setup: Twitch
 
 1. Generate an OAuth token with the `chat:read` and `chat:edit` scopes (for example via [twitchtokengen](https://twitchtokengen.com)).
-2. Export it, your bot account's nickname, and the channels to join (comma-separated, lowercased by the adapter):
+2. Allow channel names and/or viewer nicks in config, export credentials, and run:
+
+```json
+{
+  "gateway": {
+    "allowed_chats": { "twitch": ["channelone"] },
+    "allowed_users": { "twitch": ["trustedviewer"] }
+  }
+}
+```
 
 ```sh
 export LICH_TWITCH_OAUTH_TOKEN=oauth:abc123...
@@ -97,9 +131,28 @@ export LICH_TWITCH_CHANNELS=channelone,channeltwo
 lich gateway twitch
 ```
 
-3. The bot joins `#channelone` and `#channeltwo` and replies in chat (own messages are ignored). Replies split at 512 chars; IRC PING/PONG is answered automatically.
+3. The bot joins `#channelone` and `#channeltwo` and replies in chat only when the allowlist matches (own messages are ignored). Replies split at 512 chars; IRC PING/PONG is answered automatically.
+
+Only real chat messages count for the allowlist: the adapter strips optional IRC tags and then requires a full `PRIVMSG` line (`^:<nick>!... PRIVMSG #<channel> :<text>`), so Twitch events such as `USERNOTICE` (raids, subs) and `WHISPER` are ignored even if their text contains something that looks like a `PRIVMSG` — they can never impersonate an allowed user or channel.
+
+All three fields (`token`, `nick`, `channels`) are required — a missing one idles the adapter. Without allowlists for `twitch`, every inbound message is denied.
+
+## Allowlists and gateway tools
+
+Public platforms (telegram, discord, twitch) are **default-deny**. Configure at least one of:
+
+| Field | Meaning |
+| --- | --- |
+| `gateway.allowed_users.<platform>` | User ids (Telegram/Discord) or nicks (Twitch) that may talk to the bot. |
+| `gateway.allowed_chats.<platform>` | Chat / channel ids (or Twitch channel names) that may talk to the bot. |
+
+If both lists are set for a platform, a message must match **both**. If only one list is set, the other dimension is unrestricted. Enforcement lives in the shared gateway bus — denied senders get no agent run and no reply.
+
+The gateway agent ignores top-level `tools_enabled` and uses `gateway.tools_enabled`, which defaults to a read-only subset:
+
+`read_file`, `list_dir`, `grep_files`, `fetch_url`, `web_search`, `docs_read`, `docs_search`
 
-All three fields (`token`, `nick`, `channels`) are required — a missing one idles the adapter.
+Set `"gateway": { "tools_enabled": "all" }` (or an explicit name list) only when you intentionally want writes / `terminal` on chat platforms.
 
 ## Running multiple platforms at once
 
@@ -116,8 +169,9 @@ Adapters whose credentials are missing start **idle** (a warning is logged, e.g.
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
+| `LICH_GATEWAY_HOST` | `127.0.0.1` | Webhook bind address. Non-loopback requires `LICH_GATEWAY_TOKEN`. |
 | `LICH_GATEWAY_PORT` | `8089` | Webhook server port (invalid/empty values fall back to 8089). |
-| `LICH_GATEWAY_TOKEN` | unset | If set, POST `/message` requires header `x-lich-token` to match; else 401. |
+| `LICH_GATEWAY_TOKEN` | unset | If set, POST `/message` requires header `x-lich-token` to match; else 401. Required for non-loopback binds. |
 | `LICH_TELEGRAM_BOT_TOKEN` | unset | Bot token from BotFather; adapter idles without it. |
 | `LICH_DISCORD_BOT_TOKEN` | unset | Bot token from the developer portal; adapter idles without it. |
 | `LICH_DISCORD_BOT_ID` | unset | Bot user id; strips a leading `<@id>` mention from messages. |
@@ -143,10 +197,10 @@ Provider/model configuration comes from the same resolution as every mode (`LICH
 Request:
 
 ```json
-{"text": "hello", "platform": "webhook", "chat_id": "default", "user_id": "anonymous"}
+{"text": "hello", "chat_id": "default", "user_id": "anonymous"}
 ```
 
-Only `text` is required. Success (`200`):
+Only `text` is required. Any `platform` field in the body is ignored; the conversation key is always `webhook:<chat_id>`. Success (`200`):
 
 ```json
 {"reply":"Hello! How can I help you today? ...","usage":null}
@@ -165,4 +219,4 @@ Agent-level failures (e.g. every provider failed) return `200` with `reply` set
 
 ### `GET /health`
 
-`200 {"status":"ok"}` unconditionally — the webhook server itself is alive; it does not reflect platform adapters or provider health.
+`200 {"status":"ok"}` unconditionally — the webhook server itself is alive; it does not reflect platform adapters or provider health.

package/docs/user-guide/library.md

@@ -62,7 +62,8 @@ const result = await run_agent(
 | `input` | `string` | Required user message for this run. |
 | `history` | `Message[]` | Prior conversation to continue (multi-turn). |
 | `signal` | `AbortSignal` | Cooperative cancellation; the loop returns `outcome.stopped_reason: "aborted"`. |
-| `label` | `string` | Origin tag for the session filename (e.g. `"tui"`, `"gw:webhook:default"`). |
+| `label` | `string` | Origin tag for the session filename (e.g. `"tui"`, `"gw:webhook:default"`). Unused when `session` is set. |
+| `session` | `SessionHandle` | Optional shared transcript handle. When set, `Agent.run` reuses it instead of opening a new file (TUI: one handle per launch). |
 
 `AgentRunResult`:
 
@@ -147,7 +148,7 @@ Listed providers form a failover chain tried in order: `rate_limit`/`network` er
 
 `tools_enabled` accepts `"all"` (default) or an array of tool names to register; everything else stays unregistered and invisible to the model. MCP tools, when a named server is `enabled`, use the same allowlist and stay off when the list is `[]` (that empty list does not connect). The filter does not apply to plugin tools: they register afterward, including the gatekeeper's `git_commit` (fail-closed unless `LICH_ALLOW_SELF_COMMIT=1`). `[]` strips every builtin and every MCP tool and does not throw.
 
-`mcp_servers` and `catalog_client_entry` are in this source (changelog 0.7.0, unreleased). The published 0.6.0 package does not include them. See the [Redot guide](redot.md).
+`mcp_servers` and `catalog_client_entry` ship in 0.7.0. See the [Redot guide](redot.md).
 
 ```ts
 const agent = create_agent({
@@ -190,4 +191,6 @@ A Godot client does not embed the library. A game backend that does is still one
 
 ## Session access
 
-Each `run()` appends a transcript line-by-line under `config.session_dir` (default `<work_dir>/.lich/sessions`); `result.session_path` gives the exact file. Records carry `{ts, kind: "message"|"meta", message?, meta?}`. A completed run (`final`, `budget`, or `aborted` returned by the loop) closes with `{event: "run_end", stopped_reason, usage}` where `usage` equals `usage_total`. A budget stop also writes `{event: "budget_exhausted"}` before that. Provider throws do not persist. Read transcripts with `jq` (see the [games guide](games.md)) or `read_session_messages(path)` from a source checkout — it is not a package export. Persistence is best-effort: a write failure logs a warning, returns `session_path: undefined`, and never fails the run.
+Each `run()` appends to a JSONL transcript under `config.session_dir` (default `<work_dir>/.lich/sessions`) while the loop runs: `run_start`, seeded system/user (plus history when the handle is new), then assistant/tool messages on `llm_end` / `tool_call_end`, optional `budget_exhausted` / `compress_end` meta, and `run_end` (`stopped_reason`, `usage` matching `usage_total`) when the run completes. Pass `session` to reuse one handle across runs (the TUI does this so one launch = one file). Omit it for per-run files (one-shot, chat, gateway). `result.session_path` is the handle path when recording started. Records carry `{ts, kind: "message"|"meta", message?, meta?}`. Provider throws leave whatever was already appended; they do not write `run_end`. `read_session_messages` drops a trailing user message so resume does not start with two consecutive user turns. Read transcripts with `jq` (see the [games guide](games.md)) or `read_session_messages(path)` from a source checkout — it is not a package export. Persistence is best-effort: a write failure logs a warning and never fails the run.
+
+**CLI resume:** `lich --resume <id|latest>` (TUI only) resolves a transcript via `src/session/resolve.ts`, loads messages with `read_session_messages`, and seeds the TUI history. New turns append into the launch's shared handle (history is written once on first seed).

package/docs/user-guide/redot.md

@@ -22,13 +22,13 @@ The client is general, the same shape as Hermes and Claude: a named list you ext
 }
 ```
 
-stdio is a local binary you named, plus `args`, plus optional `env`. The process is spawned with those argv, never a shell. `npx`, `npm`, `bunx`, `uvx`, `curl`, `wget`, a URL, and shell metacharacters are refused. lich does not run `npx -y` or fetch an addon. Values in `env` are passed to the process and are never logged. `lich mcp add` has no flag for `env`; set that key in the file if you need it.
+stdio is a local binary you named, plus `args`, plus optional `env`. The process is spawned with those argv, never a shell. `npx`, `npm`, `bunx`, `uvx`, `curl`, `wget`, a URL, and shell metacharacters are refused. lich does not run `npx -y` or fetch an addon. Values in `env` are passed to the process and are never logged. `lich mcp add` has no flag for `env`; set that key in the file if you need it. On Bun, the spawned child is not `unref`'d, so one-shot and other short-lived runs wait for the MCP answer instead of exiting while the child is still working; `Agent.close()` (every CLI mode calls it) kills the child.
 
 HTTP is `{ "url": "http://127.0.0.1:9/mcp" }`. The host must be `127.0.0.1` or `localhost`. `0.0.0.0` and any other host are refused. There is no remote MCP in v1.
 
 On connect the client sends `initialize`, then `notifications/initialized`, then `tools/list`. `tools/call` runs only when the model invokes a registered tool. Registered names are `mcp_<server>_<tool>`, so two servers cannot collide. They appear only when that server is `enabled` and `tools_enabled` is `"all"` or lists the prefixed name. `tools_enabled: []` drops them even when the server is enabled, and does not connect. Plugin tools still register, including the gatekeeper's `git_commit`. The commander persona keeps `tools_enabled: []` and the `game_bridge` plugin only — `persona_config` does not copy `mcp_servers`.
 
-This client is in this source (changelog 0.7.0, unreleased). The published npm package is 0.6.0 and does not include `lich mcp` or `mcp_servers`. From a clone, use `bun src/cli.ts mcp ...`. `lich --version` still prints `0.6.0`.
+This client ships in 0.7.0 (`lich mcp`, `mcp_servers`). From a clone, use `bun src/cli.ts mcp ...`.
 
 ## Add a server
 

package/docs/user-guide/tui.md

@@ -9,12 +9,12 @@ lich         # front door: TUI, plus a first-run setup wizard when no config exi
 lich tui     # same TUI, no wizard. From a clone: bun src/cli.ts tui
 ```
 
-The TUI needs a TTY and a resolvable provider (same resolution as every mode). On startup it prints a dim header from the active theme welcome string, e.g. `⚱ lich v0.6.0 — the agent that will not stay dead · llama3.2 (ollama)`. `{version}` is `LICH_VERSION` from `package.json`. That banner is the only tagline placement. Quit with `/exit`, `/quit`, `/q`, or Ctrl+C.
+The TUI needs a TTY and a resolvable provider (same resolution as every mode). On startup it prints a dim header from the active theme welcome string, e.g. `⚱ lich v0.7.0 — the agent that will not stay dead · llama3.2 (ollama)`. `{version}` is `LICH_VERSION` from `package.json`. That banner is the only tagline placement. Quit with `/exit`, `/quit`, `/q`, or Ctrl+C.
 
 ## Anatomy
 
 ```
-⚱ lich v0.6.0 — the agent that will not stay dead · llama3.2 (ollama)
+⚱ lich v0.7.0 — the agent that will not stay dead · llama3.2 (ollama)
 mortal › list the files here           <- your input, echoed into the transcript
 ⏺ list_dir({})                        <- live tool-call row (name + args preview)
   ⏷ list_dir: ok (d src/ d test/ ...)  <- result row (ok/error + output preview)
@@ -37,6 +37,7 @@ model llama3.2 · turns 2 · tokens 1,204 · [dormant] · /path/.lich/sessions/.
 | `/usage` | Show tokens used this session (cumulative across turns). |
 | `/clear` | Wipe the on-screen transcript. Does **not** reset agent memory — the next message still sees prior turns. |
 | `/sessions` | List the 10 newest `.jsonl` files in `session_dir` with sizes. The heading uses the theme sessions label (`phylacteries (n):` by default). |
+| `/resume <id\|latest>` | Load a stored transcript into agent history (exact id, unique prefix, or `latest` by mtime — same resolver as `--resume`). Resets the on-screen transcript with a `· resumed <id> (n messages)` notice and updates the header banner. Missing/ambiguous ids print an error notice. |
 | `/exit`, `/quit`, `/q` | Exit the TUI. |
 
 Unknown commands print `· unknown command: /x (try /help)`. Slash commands are handled client-side and never invoke the model.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moikapy/lich",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Lich — a TypeScript AI agent harness (library + CLI) inspired by Hermes",
   "type": "module",
   "license": "MIT",