pi-ssh-remote 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -0,0 +1,156 @@
+# Changelog
+
+All notable user-visible changes to this project are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Release dates are npm publication dates, and versions follow this repository's pre-1.0 versioning policy documented in `AGENTS.md`.
+
+## [Unreleased]
+
+### Added
+
+- None.
+
+### Changed
+
+- None.
+
+### Fixed
+
+- None.
+
+## [0.1.7] - 2026-08-05
+
+### Added
+
+- Added non-secret, session-scoped SSH workspace state for endpoint, remote directory, tool-routing mode, and port forwards.
+
+### Changed
+
+- `/new` now inherits the active SSH workspace, forks and clones retain their source workspace, and `/resume` restores the selected historical session's recorded workspace.
+- Session changes close the previous transport cleanly and reconnect the target workspace without storing passwords or other credentials in session files.
+
+### Fixed
+
+- None.
+
+## [0.1.6] - 2026-08-05
+
+### Added
+
+- Added configurable line and byte budgets for remote reads, remote commands, and aggregate per-turn tool output.
+- Added bounded range reads for remote text files with normal `offset` and `limit` continuation.
+
+### Changed
+
+- Remote text reads now default to 400 lines or 16 KB, remote command results default to the last 200 lines or 8 KB, and each agent turn defaults to a shared 32 KB remote output budget.
+- Remote command output now streams through bounded buffers, with complete oversized stdout written to a permission-restricted local temporary file.
+- Collapsed command previews are now limited to at most 50 visual lines and remain independent from model-facing output.
+- Moved the complete release history into this changelog and kept concise release indexes in the English and Chinese READMEs.
+
+### Fixed
+
+- Fixed remote text reads downloading complete files over SFTP before applying line and byte limits.
+- Fixed `ssh_remote_control exec` accumulating complete stdout in memory before truncation.
+
+## [0.1.5] - 2026-08-04
+
+### Added
+
+- Added persistent, endpoint-specific server memory through `/remote config memory TEXT` and the `ssh_remote_control` `memory` action.
+- Added automatic injection of that memory into every model request while the matching endpoint is the active remote workspace.
+
+### Changed
+
+- Server memory is removed from subsequent model requests when remote tool routing is disabled, including disconnect and tunnel-only mode.
+- `/remote config` now shows the memory stored for each endpoint.
+
+### Fixed
+
+- None.
+
+## [0.1.4] - 2026-07-31
+
+### Added
+
+- Added persistent endpoint notes through `/remote config note TEXT` and the `ssh_remote_control` `note` action.
+- Added per-command timeout overrides through `/remote exec --timeout SECONDS` and the tool's `timeout` parameter.
+
+### Changed
+
+- Remote commands now default to a 30-second timeout and endpoint notes appear in status, connection, reconnection, and footer labels.
+- Expanded the documentation around agent-first workflows, multi-server operation, background jobs, and tunnel mode.
+
+### Fixed
+
+- Fixed remote commands that could run without a deadline by enforcing GNU `timeout` remotely and a local fallback timer.
+- Fixed timeout reporting for processes terminated with timeout-related exit codes 124 and 137.
+
+## [0.1.3] - 2026-07-24
+
+### Added
+
+- Added configurable collapsed command previews with `/remote config display-lines N`, `/remote exec --lines N`, and the tool's `displayLines` parameter.
+- Added expandable custom rendering for remote command results.
+
+### Changed
+
+- Remote command previews default to the last five visual lines while model-facing output remains limited to 2,000 lines or 50 KB.
+- Oversized complete output is saved to a permission-restricted local temporary file.
+
+### Fixed
+
+- Fixed `/remote exec` truncating its notification to an arbitrary 4,000 characters without preserving or identifying the full output.
+
+## [0.1.2] - 2026-07-24
+
+### Added
+
+- None.
+
+### Changed
+
+- Republished the 0.1.1 runtime as 0.1.2 to align npm package version metadata; there were no runtime code changes.
+
+### Fixed
+
+- None.
+
+## [0.1.1] - 2026-07-24
+
+### Added
+
+- Added the shorter `/remote ssh USER@HOST [-p PORT]` connection command.
+
+### Changed
+
+- `/remote ssh` now saves, selects, and immediately connects to the endpoint instead of only storing it.
+
+### Fixed
+
+- Fixed help and error text that still instructed users to run the obsolete `/remote config ssh ssh ...` form.
+
+## [0.1.0] - 2026-07-24
+
+### Added
+
+- Initial release with persistent multi-endpoint SSH workspaces and remote working directories.
+- Added transparent routing for Pi's `read`, `write`, `edit`, `bash`, and user shell operations.
+- Added SSH-agent/password authentication, interactive host-key verification, automatic reconnection, SFTP file access, bounded command output, and local TCP forwarding.
+
+### Changed
+
+- None.
+
+### Fixed
+
+- None.
+
+[Unreleased]: https://github.com/petrichor20211/pi-ssh-remote/compare/v0.1.7...HEAD
+[0.1.7]: https://github.com/petrichor20211/pi-ssh-remote/compare/v0.1.6...v0.1.7
+[0.1.6]: https://github.com/petrichor20211/pi-ssh-remote/compare/v0.1.5...v0.1.6
+[0.1.5]: https://github.com/petrichor20211/pi-ssh-remote/compare/v0.1.4...v0.1.5
+[0.1.4]: https://github.com/petrichor20211/pi-ssh-remote/releases/tag/v0.1.4
+[0.1.3]: https://www.npmjs.com/package/pi-ssh-remote/v/0.1.3
+[0.1.2]: https://www.npmjs.com/package/pi-ssh-remote/v/0.1.2
+[0.1.1]: https://www.npmjs.com/package/pi-ssh-remote/v/0.1.1
+[0.1.0]: https://www.npmjs.com/package/pi-ssh-remote/v/0.1.0

package/README.md

@@ -35,7 +35,7 @@ Each `user@host:port` endpoint remembers its remote working directory, note, ser
 
 ### Resilient and bounded by default
 
-Dropped connections are automatically re-established during the active session. Remote commands have a 30-second default timeout, oversized output is bounded before it reaches the model context, and full truncated output is preserved in a temporary file.
+Dropped connections are automatically re-established during the active session. SSH workspace state is also session-aware: `/new` inherits the current workspace, forks and clones retain their source workspace, and `/resume` restores the selected session's recorded endpoint, remote directory, routing mode, and forwards. Remote commands have a 30-second default timeout. Remote text reads fetch focused ranges instead of downloading complete files, command output is streamed through bounded buffers, and a 32 KB per-turn budget prevents parallel tools from flooding model context. Complete oversized command output is preserved in a permission-restricted temporary file.
 
 ### Hybrid local/remote workflows
 
@@ -176,7 +176,12 @@ These requests are handled through the agent-facing `ssh_remote_control` tool; s
 | `/remote exec COMMAND` | Run one command in the remote cwd |
 | `/remote exec --timeout 60 COMMAND` | Override the command timeout |
 | `/remote exec --lines 20 COMMAND` | Override collapsed preview lines |
-| `/remote config display-lines 10` | Set default collapsed preview lines |
+| `/remote config display-lines 10` | Set default collapsed preview lines (maximum 50) |
+| `/remote config read-max-lines 400` | Set the remote read line budget |
+| `/remote config read-max-bytes 16384` | Set the remote read byte budget |
+| `/remote config exec-max-lines 200` | Set the remote command line budget |
+| `/remote config exec-max-bytes 8192` | Set the remote command byte budget |
+| `/remote config turn-max-bytes 32768` | Set the aggregate per-turn remote output budget |
 | `/remote status` | Show the active workspace |
 | `/remote reload` | Reconnect the active workspace |
 | `/remote off` | Disconnect and return tools to local execution |
@@ -190,109 +195,24 @@ Endpoint configuration is stored locally in:
 ~/.pi/agent/ssh-remote-config.json
 ```
 
-Saved values include endpoints, active endpoint, notes, server-specific memories, remote working directories, forwards, and preview settings. Server memory is user-configured trusted context and is inserted into each model request only while that endpoint is the active remote workspace; it is not read from the remote server. Passwords are **never written to this file**: SSH agent authentication is preferred, and prompted passwords remain only in process memory.
+Saved global values include endpoints, active endpoint, notes, server-specific memories, remote working directories, forwards, preview settings, and model-output budgets. Each Pi session also stores non-secret SSH workspace metadata so `/resume` can restore the server associated with that session. Server memory is user-configured trusted context and is inserted into each model request only while that endpoint is the active remote workspace; it is not read from the remote server. Passwords are **never written to this file**: SSH agent authentication is preferred, and prompted passwords remain only in process memory.
 
-New or changed host keys require interactive confirmation and are stored separately from OpenSSH. Remote output sent to the model is limited to 2,000 lines or 50 KB; oversized complete output is written to a temporary local file. Preview-line settings affect only the collapsed UI.
+New or changed host keys require interactive confirmation and are stored separately from OpenSSH. By default, remote text reads return at most 400 lines or 16 KB, remote command results return the last 200 lines or 8 KB, and all remote tools in one agent turn share a 32 KB output budget. Text reads support `offset`/`limit` continuation without downloading the complete remote file. Oversized command output is streamed to a permission-restricted temporary local file rather than accumulated in memory. Configured limits may be raised only to the extension's hard safety ceilings. Preview-line settings affect only the collapsed UI and never increase model output.
 
 ## Current SSH scope
 
 The extension currently supports direct SSH commands with `-p` and `-l`. It does not yet consume `~/.ssh/config`, `IdentityFile`, or ProxyJump settings.
 
-## Release history
+## Releases
 
-Release dates below are npm publication dates. Every release records user-visible additions, changes, and bug fixes; `None` means that category had no changes in that release.
+Latest release: [v0.1.7](https://github.com/petrichor20211/pi-ssh-remote/releases/tag/v0.1.7)
 
-### 0.1.5 — 2026-08-04
+| Version | Date | Highlights |
+|---|---|---|
+| [0.1.7](CHANGELOG.md#017---2026-08-05) | 2026-08-05 | Session-aware SSH workspace restoration for new, forked, and resumed sessions |
+| [0.1.6](CHANGELOG.md#016---2026-08-05) | 2026-08-05 | Bounded remote reads, streamed command output, and per-turn output budgets |
+| [0.1.5](CHANGELOG.md#015---2026-08-04) | 2026-08-04 | Endpoint-specific server memory and automatic context injection |
 
-**Added**
-
-- Added persistent, endpoint-specific server memory through `/remote config memory TEXT` and the `ssh_remote_control` `memory` action.
-- Added automatic injection of that memory into every model request while the matching endpoint is the active remote workspace.
-
-**Changed**
-
-- Server memory is removed from subsequent model requests when remote tool routing is disabled, including disconnect and tunnel-only mode.
-- `/remote config` now shows the memory stored for each endpoint.
-
-**Fixed**
-
-- None.
-
-### 0.1.4 — 2026-07-31
-
-**Added**
-
-- Added persistent endpoint notes through `/remote config note TEXT` and the `ssh_remote_control` `note` action.
-- Added per-command timeout overrides through `/remote exec --timeout SECONDS` and the tool's `timeout` parameter.
-
-**Changed**
-
-- Remote commands now default to a 30-second timeout and endpoint notes appear in status, connection, reconnection, and footer labels.
-- Expanded the documentation around agent-first workflows, multi-server operation, background jobs, and tunnel mode.
-
-**Fixed**
-
-- Fixed remote commands that could run without a deadline by enforcing GNU `timeout` remotely and a local fallback timer.
-- Fixed timeout reporting for processes terminated with timeout-related exit codes 124 and 137.
-
-### 0.1.3 — 2026-07-24
-
-**Added**
-
-- Added configurable collapsed command previews with `/remote config display-lines N`, `/remote exec --lines N`, and the tool's `displayLines` parameter.
-- Added expandable custom rendering for remote command results.
-
-**Changed**
-
-- Remote command previews default to the last five visual lines while model-facing output remains limited to 2,000 lines or 50 KB.
-- Oversized complete output is saved to a permission-restricted local temporary file.
-
-**Fixed**
-
-- Fixed `/remote exec` truncating its notification to an arbitrary 4,000 characters without preserving or identifying the full output.
-
-### 0.1.2 — 2026-07-24
-
-**Added**
-
-- None.
-
-**Changed**
-
-- Republished the 0.1.1 runtime as 0.1.2 to align npm package version metadata; there were no runtime code changes.
-
-**Fixed**
-
-- None.
-
-### 0.1.1 — 2026-07-24
-
-**Added**
-
-- Added the shorter `/remote ssh USER@HOST [-p PORT]` connection command.
-
-**Changed**
-
-- `/remote ssh` now saves, selects, and immediately connects to the endpoint instead of only storing it.
-
-**Fixed**
-
-- Fixed help and error text that still instructed users to run the obsolete `/remote config ssh ssh ...` form.
-
-### 0.1.0 — 2026-07-24
-
-**Added**
-
-- Initial release with persistent multi-endpoint SSH workspaces and remote working directories.
-- Added transparent routing for Pi's `read`, `write`, `edit`, `bash`, and user shell operations.
-- Added SSH-agent/password authentication, interactive host-key verification, automatic reconnection, SFTP file access, bounded command output, and local TCP forwarding.
-
-**Changed**
-
-- None.
-
-**Fixed**
-
-- None.
+See [CHANGELOG.md](CHANGELOG.md) for the complete release history, including additions, behavior changes, and bug fixes.
 
 MIT licensed.

package/README.zh-CN.md

@@ -58,11 +58,11 @@ SSH remote H100 训练机 (root@gpu-box.example.com:2202):/srv/project
 
 ### 断线后可以自动恢复
 
-当前会话中如果 SSH 连接意外断开，插件会尝试自动重连，不需要 Agent 从头建立工作环境。
+当前会话中如果 SSH 连接意外断开，插件会尝试自动重连，不需要 Agent 从头建立工作环境。SSH 工作区状态也会跟随 Pi session：`/new` 继承当前工作区，`/fork` 和 `/clone` 保留来源工作区，`/resume` 恢复目标历史 session 记录的服务器、远程目录、路由模式和端口转发。
 
 ### 对 Agent 上下文更友好
 
-远程命令默认 30 秒超时，避免某个前台任务长期占住 Agent。命令输出过大时，只会把受限内容放入模型上下文，完整输出会另外保存到临时文件，方便后续继续检查。
+远程命令默认 30 秒超时，避免某个前台任务长期占住 Agent。远程文本读取会按范围获取，不再先下载完整文件；命令输出通过有界缓冲流式处理；同一轮远端工具共享 32 KB 输出预算，避免并行调用迅速占满上下文。超限命令的完整输出会保存到权限受限的临时文件，方便后续按需检查。
 
 ### 可以远端跑服务、本地改代码
 
@@ -230,7 +230,12 @@ Pi 会通过插件提供的 `ssh_remote_control` 工具完成这些操作。
 | `/remote exec COMMAND` | 在当前远程目录执行一次命令 |
 | `/remote exec --timeout 60 COMMAND` | 单独设置本次命令的超时时间 |
 | `/remote exec --lines 20 COMMAND` | 单独设置本次折叠显示的行数 |
-| `/remote config display-lines 10` | 设置默认折叠显示行数 |
+| `/remote config display-lines 10` | 设置默认折叠显示行数（最大 50） |
+| `/remote config read-max-lines 400` | 设置远端读取行数预算 |
+| `/remote config read-max-bytes 16384` | 设置远端读取字节预算 |
+| `/remote config exec-max-lines 200` | 设置远端命令行数预算 |
+| `/remote config exec-max-bytes 8192` | 设置远端命令字节预算 |
+| `/remote config turn-max-bytes 32768` | 设置每轮远端工具总输出预算 |
 | `/remote status` | 查看当前连接和工作目录 |
 | `/remote reload` | 重新连接当前服务器 |
 | `/remote off` | 断开连接并返回本地 |
@@ -244,7 +249,7 @@ Pi 会通过插件提供的 `ssh_remote_control` 工具完成这些操作。
 ~/.pi/agent/ssh-remote-config.json
 ```
 
-其中包括：
+全局配置包括：
 
 - 已保存的服务器；
 - 当前选中的服务器；
@@ -252,9 +257,10 @@ Pi 会通过插件提供的 `ssh_remote_control` 工具完成这些操作。
 - 服务器特定记忆；
 - 默认远程目录；
 - 端口转发配置；
-- 命令预览设置。
+- 命令预览设置；
+- 模型输出预算。
 
-服务器记忆是由用户在本地配置的可信上下文，不会从远程服务器自动读取；仅当对应 endpoint 作为远端工作区启用时才会加入每次模型请求。
+此外，每个 Pi session 都会记录不含凭据的 SSH 工作区元数据，用于在 `/resume` 时恢复该历史 session 对应的服务器环境。服务器记忆是由用户在本地配置的可信上下文，不会从远程服务器自动读取；仅当对应 endpoint 作为远端工作区启用时才会加入每次模型请求。
 
 密码不会写入配置文件。插件会优先使用 SSH agent；如果需要手动输入密码，密码只会缓存在当前 Pi 进程的内存中。
 
@@ -263,109 +269,28 @@ Pi 会通过插件提供的 `ssh_remote_control` 工具完成这些操作。
 - 第一次连接新服务器时，需要确认主机密钥；
 - 主机密钥发生变化时，会再次要求确认；
 - 远程命令默认 30 秒超时；
-- 发送给模型的命令输出最多为 2,000 行或 50 KB；
-- 超限的完整输出会保存到本地临时文件；
-- 折叠显示行数只影响界面，不影响模型输出上限。
+- 远程文本读取默认最多返回 400 行或 16 KB，并支持通过 `offset`/`limit` 继续读取；
+- 远程命令默认最多返回最后 200 行或 8 KB；
+- 同一轮所有远端工具默认共享 32 KB 模型输出预算；
+- 文本范围读取不会先通过 SFTP 下载完整远程文件；
+- 超限命令会流式写入权限受限的本地临时文件，不在内存中累积完整输出；
+- 各项限制可以配置，但不能超过扩展的硬安全上限；
+- 折叠显示行数最大为 50，只影响界面，不会增加模型输出。
 
 ## 当前限制
 
 目前只支持 SSH 直连，以及 `-p`、`-l` 参数。暂不读取 `~/.ssh/config`，也不支持 `IdentityFile` 和 ProxyJump。
 
-## 版本更新记录
+## 版本发布
 
-以下日期均为 npm 发布时间。每次发布都记录用户可见的新增内容、行为变更和 Bug 修复；“无”表示该版本在对应类别没有变化。
+最新版本：[v0.1.7](https://github.com/petrichor20211/pi-ssh-remote/releases/tag/v0.1.7)
 
-### 0.1.5 — 2026-08-04
+| 版本 | 日期 | 主要内容 |
+|---|---|---|
+| [0.1.7](CHANGELOG.md#017---2026-08-05) | 2026-08-05 | 新建、分叉和恢复 session 时自动恢复对应 SSH 工作区 |
+| [0.1.6](CHANGELOG.md#016---2026-08-05) | 2026-08-05 | 有界远端读取、流式命令输出与每轮输出预算 |
+| [0.1.5](CHANGELOG.md#015---2026-08-04) | 2026-08-04 | endpoint 级服务器记忆与自动上下文注入 |
 
-**新增**
-
-- 新增 endpoint 级持久化服务器记忆，支持 `/remote config memory TEXT` 和 `ssh_remote_control` 的 `memory` action。
-- 对应 endpoint 作为当前远程工作区时，在每次模型请求中自动注入服务器记忆。
-
-**变更**
-
-- 断开连接、关闭远端工具路由或进入纯隧道模式后，后续模型请求不再包含服务器记忆。
-- `/remote config` 现在会显示每个 endpoint 保存的记忆。
-
-**修复**
-
-- 无。
-
-### 0.1.4 — 2026-07-31
-
-**新增**
-
-- 新增 endpoint 备注，支持 `/remote config note TEXT` 和 `ssh_remote_control` 的 `note` action。
-- 新增单次命令超时覆盖，支持 `/remote exec --timeout SECONDS` 和工具的 `timeout` 参数。
-
-**变更**
-
-- 远程命令默认超时改为 30 秒；备注会显示在状态、连接、重连提示和底部状态栏中。
-- 扩充了 Agent 工作流、多服务器、后台任务和纯隧道模式文档。
-
-**修复**
-
-- 修复部分远程命令没有截止时间、可能一直占用 Agent 的问题：远端使用 GNU `timeout`，本地增加兜底定时器。
-- 修复退出码 124 和 137 未被统一识别为超时的问题。
-
-### 0.1.3 — 2026-07-24
-
-**新增**
-
-- 新增可配置的命令折叠预览，支持 `/remote config display-lines N`、`/remote exec --lines N` 和工具的 `displayLines` 参数。
-- 新增远程命令结果的展开显示。
-
-**变更**
-
-- 命令折叠预览默认显示最后 5 个视觉行；发送给模型的输出仍限制为 2,000 行或 50 KB。
-- 超限的完整输出会保存到权限受限的本地临时文件。
-
-**修复**
-
-- 修复 `/remote exec` 直接按 4,000 字符截断通知、且不保留或提示完整输出位置的问题。
-
-### 0.1.2 — 2026-07-24
-
-**新增**
-
-- 无。
-
-**变更**
-
-- 将 0.1.1 的运行时代码以 0.1.2 重新发布，用于对齐 npm 包版本元数据；没有运行时代码变化。
-
-**修复**
-
-- 无。
-
-### 0.1.1 — 2026-07-24
-
-**新增**
-
-- 新增简化命令 `/remote ssh USER@HOST [-p PORT]`。
-
-**变更**
-
-- `/remote ssh` 现在会保存、选中并立即连接 endpoint，而不只是保存配置。
-
-**修复**
-
-- 修复帮助和错误信息仍提示使用旧命令 `/remote config ssh ssh ...` 的问题。
-
-### 0.1.0 — 2026-07-24
-
-**新增**
-
-- 首次发布，支持持久化多 endpoint SSH 工作区和远程工作目录。
-- 新增 Pi `read`、`write`、`edit`、`bash` 和用户 Shell 操作的透明远端路由。
-- 新增 SSH agent/密码认证、交互式主机密钥校验、自动重连、SFTP 文件访问、命令输出限制和本地 TCP 端口转发。
-
-**变更**
-
-- 无。
-
-**修复**
-
-- 无。
+完整的新增内容、行为变更和 Bug 修复记录请查看 [CHANGELOG.md](CHANGELOG.md)。
 
 MIT License。

package/index.ts

@@ -7,8 +7,8 @@
  */
 
 import { Client, type ClientChannel, type ConnectConfig, type SFTPWrapper } from "ssh2";
-import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, relative, sep } from "node:path";
+import { closeSync, mkdirSync, mkdtempSync, openSync, readFileSync, writeFileSync, writeSync } from "node:fs";
+import { dirname, join, posix, relative, sep } from "node:path";
 import { createServer, type Server, type Socket } from "node:net";
 import { tmpdir } from "node:os";
 import { Type } from "typebox";
@@ -24,6 +24,7 @@ import {
   createWriteTool,
   formatSize,
   keyHint,
+  truncateHead,
   truncateTail,
   type BashOperations,
   type EditOperations,
@@ -47,7 +48,7 @@ interface RemoteState extends ParsedSsh {
 
 interface CredentialCache {
   passwords: Map<string, string>;
-  resume?: { command: string; cwd: string };
+  resume?: { command: string; cwd: string; routeRemoteTools: boolean; forwards?: string[] };
 }
 
 interface RemoteEndpointConfig {
@@ -62,6 +63,11 @@ interface RemoteConfig {
   activeEndpoint?: string;
   endpoints?: Record<string, RemoteEndpointConfig>;
   displayLines?: number;
+  readMaxLines?: number;
+  readMaxBytes?: number;
+  execMaxLines?: number;
+  execMaxBytes?: number;
+  turnMaxBytes?: number;
   /** Legacy fields migrated into endpoints on the next config write. */
   sshCommand?: string;
   remoteCwd?: string;
@@ -74,13 +80,31 @@ interface ForwardSpec {
   remotePort: number;
 }
 
+interface SessionRemoteState {
+  version: 1;
+  connected: boolean;
+  command?: string;
+  cwd?: string;
+  routeRemoteTools?: boolean;
+  forwards?: string[];
+}
+
 const AGENT_DIR = join(process.env.HOME || ".", CONFIG_DIR_NAME, "agent");
 const KNOWN_HOSTS_FILE = join(AGENT_DIR, "ssh-remote-known-hosts.json");
 const REMOTE_CONFIG_FILE = join(AGENT_DIR, "ssh-remote-config.json");
 const FALLBACK_REMOTE_CWD = "~";
 const DEFAULT_DISPLAY_LINES = 5;
+const MAX_DISPLAY_LINES = 50;
+const DEFAULT_READ_MAX_LINES = 400;
+const DEFAULT_READ_MAX_BYTES = 16 * 1024;
+const DEFAULT_EXEC_MAX_LINES = 200;
+const DEFAULT_EXEC_MAX_BYTES = 8 * 1024;
+const DEFAULT_TURN_MAX_BYTES = 32 * 1024;
+const MIN_MODEL_OUTPUT_BYTES = 1024;
+const OUTPUT_FOOTER_RESERVE_BYTES = 512;
 const DEFAULT_REMOTE_TIMEOUT_SECONDS = 30;
 const MAX_REMOTE_TIMEOUT_SECONDS = 2_147_483_647 / 1000;
+const SESSION_STATE_ENTRY_TYPE = "pi-ssh-remote-state";
 const CACHE_KEY = "__piHpcCredentialCacheV1";
 const cacheHost = globalThis as typeof globalThis & { [CACHE_KEY]?: CredentialCache };
 const credentialCache = cacheHost[CACHE_KEY] ??= { passwords: new Map<string, string>() };
@@ -158,12 +182,28 @@ function quote(value: string): string {
   return `'${value.replace(/'/g, `'"'"'`)}'`;
 }
 
+function parseBoundedInteger(value: unknown, label: string, maximum: number): number {
+  const parsed = typeof value === "number" ? value : Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > maximum) {
+    throw new Error(`${label} must be an integer from 1 to ${maximum}`);
+  }
+  return parsed;
+}
+
 function parseDisplayLines(value: unknown): number {
-  const lines = typeof value === "number" ? value : Number(value);
-  if (!Number.isInteger(lines) || lines < 1 || lines > DEFAULT_MAX_LINES) {
-    throw new Error(`Display lines must be an integer from 1 to ${DEFAULT_MAX_LINES}`);
+  return parseBoundedInteger(value, "Display lines", MAX_DISPLAY_LINES);
+}
+
+function parseOutputLines(value: unknown, label: string): number {
+  return parseBoundedInteger(value, label, DEFAULT_MAX_LINES);
+}
+
+function parseOutputBytes(value: unknown, label: string, maximum = DEFAULT_MAX_BYTES): number {
+  const parsed = typeof value === "number" ? value : Number(value);
+  if (!Number.isInteger(parsed) || parsed < MIN_MODEL_OUTPUT_BYTES || parsed > maximum) {
+    throw new Error(`${label} must be an integer from ${MIN_MODEL_OUTPUT_BYTES} to ${maximum}`);
   }
-  return lines;
+  return parsed;
 }
 
 function parseRemoteTimeout(value: unknown): number {
@@ -183,6 +223,15 @@ function configuredDisplayLines(config = loadRemoteConfig()): number {
   catch { return DEFAULT_DISPLAY_LINES; }
 }
 
+function configuredOutputLimits(config = loadRemoteConfig()) {
+  const readMaxLines = (() => { try { return parseOutputLines(config.readMaxLines ?? DEFAULT_READ_MAX_LINES, "Read max lines"); } catch { return DEFAULT_READ_MAX_LINES; } })();
+  const readMaxBytes = (() => { try { return parseOutputBytes(config.readMaxBytes ?? DEFAULT_READ_MAX_BYTES, "Read max bytes"); } catch { return DEFAULT_READ_MAX_BYTES; } })();
+  const execMaxLines = (() => { try { return parseOutputLines(config.execMaxLines ?? DEFAULT_EXEC_MAX_LINES, "Exec max lines"); } catch { return DEFAULT_EXEC_MAX_LINES; } })();
+  const execMaxBytes = (() => { try { return parseOutputBytes(config.execMaxBytes ?? DEFAULT_EXEC_MAX_BYTES, "Exec max bytes"); } catch { return DEFAULT_EXEC_MAX_BYTES; } })();
+  const turnMaxBytes = (() => { try { return parseOutputBytes(config.turnMaxBytes ?? DEFAULT_TURN_MAX_BYTES, "Turn max bytes", DEFAULT_MAX_BYTES * 4); } catch { return DEFAULT_TURN_MAX_BYTES; } })();
+  return { readMaxLines, readMaxBytes, execMaxLines, execMaxBytes, turnMaxBytes };
+}
+
 function commandFromEndpointKey(key: string): string | undefined {
   const match = key.match(/^([^@]+)@(.+):(\d+)$/);
   if (!match) return undefined;
@@ -215,13 +264,27 @@ function normalizeRemoteConfig(config: RemoteConfig): RemoteConfig {
   if (activeEndpoint && !endpoints[activeEndpoint]) activeEndpoint = undefined;
   activeEndpoint ??= Object.keys(endpoints)[0];
   let displayLines: number | undefined;
-  try { displayLines = config.displayLines === undefined ? undefined : parseDisplayLines(config.displayLines); }
-  catch { displayLines = undefined; }
+  let readMaxLines: number | undefined;
+  let readMaxBytes: number | undefined;
+  let execMaxLines: number | undefined;
+  let execMaxBytes: number | undefined;
+  let turnMaxBytes: number | undefined;
+  try { displayLines = config.displayLines === undefined ? undefined : parseDisplayLines(config.displayLines); } catch {}
+  try { readMaxLines = config.readMaxLines === undefined ? undefined : parseOutputLines(config.readMaxLines, "Read max lines"); } catch {}
+  try { readMaxBytes = config.readMaxBytes === undefined ? undefined : parseOutputBytes(config.readMaxBytes, "Read max bytes"); } catch {}
+  try { execMaxLines = config.execMaxLines === undefined ? undefined : parseOutputLines(config.execMaxLines, "Exec max lines"); } catch {}
+  try { execMaxBytes = config.execMaxBytes === undefined ? undefined : parseOutputBytes(config.execMaxBytes, "Exec max bytes"); } catch {}
+  try { turnMaxBytes = config.turnMaxBytes === undefined ? undefined : parseOutputBytes(config.turnMaxBytes, "Turn max bytes", DEFAULT_MAX_BYTES * 4); } catch {}
 
   return {
     ...(activeEndpoint ? { activeEndpoint } : {}),
     ...(Object.keys(endpoints).length ? { endpoints } : {}),
     ...(displayLines !== undefined ? { displayLines } : {}),
+    ...(readMaxLines !== undefined ? { readMaxLines } : {}),
+    ...(readMaxBytes !== undefined ? { readMaxBytes } : {}),
+    ...(execMaxLines !== undefined ? { execMaxLines } : {}),
+    ...(execMaxBytes !== undefined ? { execMaxBytes } : {}),
+    ...(turnMaxBytes !== undefined ? { turnMaxBytes } : {}),
   };
 }
 
@@ -299,18 +362,99 @@ function displayFingerprint(hex: string): string {
   return `SHA256:${Buffer.from(hex, "hex").toString("base64").replace(/=+$/, "")}`;
 }
 
-function formatRemoteOutput(output: string) {
-  const truncation = truncateTail(output, { maxLines: DEFAULT_MAX_LINES, maxBytes: DEFAULT_MAX_BYTES });
-  const content = truncation.content || "Remote command completed.";
-  if (!truncation.truncated) return { text: content, content, truncation };
-
+function createOutputFile(): { path: string; fd: number } {
   const outputDir = mkdtempSync(join(tmpdir(), "pi-ssh-remote-output-"));
-  const fullOutputPath = join(outputDir, "output.log");
-  writeFileSync(fullOutputPath, output, { encoding: "utf8", mode: 0o600 });
-  const startLine = truncation.totalLines - truncation.outputLines + 1;
-  const limit = truncation.truncatedBy === "bytes" ? ` (${formatSize(DEFAULT_MAX_BYTES)} limit)` : "";
-  const text = `${content}\n\n[Showing lines ${startLine}-${truncation.totalLines} of ${truncation.totalLines}${limit}. Full output: ${fullOutputPath}]`;
-  return { text, content, truncation, fullOutputPath };
+  const path = join(outputDir, "output.log");
+  return { path, fd: openSync(path, "w", 0o600) };
+}
+
+function saveOutput(output: string): string {
+  const file = createOutputFile();
+  try { writeSync(file.fd, output); }
+  finally { closeSync(file.fd); }
+  return file.path;
+}
+
+class RemoteExecAccumulator {
+  private chunks: Buffer[] = [];
+  private tail = Buffer.alloc(0);
+  private stderrTail = Buffer.alloc(0);
+  private outputFile: { path: string; fd: number } | undefined;
+  private totalBytes = 0;
+  private newlineCount = 0;
+  private lastByte: number | undefined;
+
+  constructor(private maxLines: number, private maxBytes: number) {}
+
+  append(chunk: Buffer): void {
+    if (!chunk.length) return;
+    this.totalBytes += chunk.length;
+    for (const byte of chunk) if (byte === 10) this.newlineCount++;
+    this.lastByte = chunk[chunk.length - 1];
+
+    if (!this.outputFile && this.totalBytes > this.maxBytes) {
+      this.outputFile = createOutputFile();
+      for (const previous of this.chunks) writeSync(this.outputFile.fd, previous);
+      this.chunks = [];
+    }
+    if (this.outputFile) writeSync(this.outputFile.fd, chunk);
+    else this.chunks.push(chunk);
+
+    this.tail = Buffer.concat([this.tail, chunk]);
+    const tailBytes = this.maxBytes + OUTPUT_FOOTER_RESERVE_BYTES + 4096;
+    if (this.tail.length > tailBytes) this.tail = this.tail.subarray(this.tail.length - tailBytes);
+  }
+
+  appendStderr(chunk: Buffer): void {
+    this.stderrTail = Buffer.concat([this.stderrTail, chunk]);
+    if (this.stderrTail.length > this.maxBytes) this.stderrTail = this.stderrTail.subarray(this.stderrTail.length - this.maxBytes);
+  }
+
+  private ensureOutputFile(): string {
+    if (!this.outputFile) {
+      this.outputFile = createOutputFile();
+      for (const chunk of this.chunks) writeSync(this.outputFile.fd, chunk);
+      this.chunks = [];
+    }
+    return this.outputFile.path;
+  }
+
+  finish() {
+    const totalLines = this.totalBytes ? this.newlineCount + (this.lastByte === 10 ? 0 : 1) : 0;
+    const source = this.outputFile ? this.tail.toString("utf8") : Buffer.concat(this.chunks).toString("utf8");
+    const contentBudget = Math.max(1, this.maxBytes - OUTPUT_FOOTER_RESERVE_BYTES);
+    const base = truncateTail(source, { maxLines: this.maxLines, maxBytes: contentBudget });
+    const truncated = this.totalBytes > contentBudget || totalLines > this.maxLines || base.truncated;
+    const truncation = {
+      ...base,
+      truncated,
+      totalLines,
+      totalBytes: this.totalBytes,
+      maxLines: this.maxLines,
+      maxBytes: this.maxBytes,
+    };
+    const content = base.content || "Remote command completed.";
+    let fullOutputPath: string | undefined;
+    let text = content;
+    if (truncated) {
+      fullOutputPath = this.ensureOutputFile();
+      const startLine = Math.max(1, totalLines - base.outputLines + 1);
+      text += `\n\n[Showing lines ${startLine}-${totalLines} of ${totalLines} (${formatSize(this.maxBytes)} model-output limit). Full output: ${fullOutputPath}]`;
+    }
+    this.close();
+    return { text, content, truncation, fullOutputPath };
+  }
+
+  errorMessage(): string {
+    return this.stderrTail.toString("utf8").trim();
+  }
+
+  close(): void {
+    if (!this.outputFile) return;
+    const file = this.outputFile;
+    this.outputFile = undefined;
+    closeSync(file.fd);
+  }
 }
 
 function previewRemoteOutput(output: string, displayLines: number): string {
@@ -429,6 +573,53 @@ function execRemote(
   });
 }
 
+function execRemoteLimited(
+  client: Client,
+  command: string,
+  timeoutSeconds: number,
+  maxLines: number,
+  maxBytes: number,
+): Promise<ReturnType<RemoteExecAccumulator["finish"]>> {
+  const resolvedTimeout = parseRemoteTimeout(timeoutSeconds);
+  return new Promise((resolve, reject) => {
+    client.exec(withRemoteTimeout(command, resolvedTimeout), (error, stream) => {
+      if (error) return reject(error);
+      const accumulator = new RemoteExecAccumulator(maxLines, maxBytes);
+      let locallyTimedOut = false;
+      let settled = false;
+      const timer = setTimeout(() => {
+        locallyTimedOut = true;
+        stream.close();
+      }, (resolvedTimeout + 8) * 1000);
+      const cleanup = () => clearTimeout(timer);
+      const fail = (failure: Error) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        accumulator.close();
+        reject(failure);
+      };
+      stream.on("data", (chunk: Buffer) => accumulator.append(chunk));
+      stream.stderr.on("data", (chunk: Buffer) => accumulator.appendStderr(chunk));
+      stream.once("error", (streamError: Error) => fail(streamError));
+      stream.on("close", (code: number | null) => {
+        if (settled) return;
+        cleanup();
+        if (locallyTimedOut || code === 124 || code === 137) {
+          fail(new Error(`Remote command timed out after ${resolvedTimeout} seconds`));
+          return;
+        }
+        if (code !== 0) {
+          fail(new Error(accumulator.errorMessage() || `Remote command exited with code ${code}`));
+          return;
+        }
+        settled = true;
+        resolve(accumulator.finish());
+      });
+    });
+  });
+}
+
 function getSftp(client: Client): Promise<SFTPWrapper> {
   return new Promise((resolve, reject) => client.sftp((error, sftp) => error ? reject(error) : resolve(sftp)));
 }
@@ -478,8 +669,12 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
   let currentCtx: any;
   let reconnectPromise: Promise<RemoteState> | null = null;
   const forwardServers = new Map<number, Server>();
+  const forwardSpecs = new Map<number, ForwardSpec>();
+  let sessionReady = false;
+  let restoringSessionState = false;
   let lastConnectionError: string | undefined;
   let lastCommand = credentialCache.resume?.command ?? activeSshCommand() ?? "";
+  let turnOutputBytes = 0;
 
   const configuredCwd = (command: string): string =>
     endpointConfig(loadRemoteConfig(), command).remoteCwd || FALLBACK_REMOTE_CWD;
@@ -495,6 +690,98 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
     return path;
   };
 
+  const remotePath = (path: string): string => {
+    const normalized = path.replace(/^@/, "");
+    if (normalized.startsWith("/")) return mapPath(normalized);
+    if (!remote) return normalized;
+    return posix.join(remote.cwd, normalized);
+  };
+
+  const serializeForward = (spec: ForwardSpec): string => `${spec.localPort}:${spec.remoteHost}:${spec.remotePort}`;
+
+  const currentSessionRemoteState = (): SessionRemoteState => remote ? {
+    version: 1,
+    connected: true,
+    command: remote.command,
+    cwd: remote.cwd,
+    routeRemoteTools,
+    forwards: [...forwardSpecs.values()].map(serializeForward),
+  } : { version: 1, connected: false };
+
+  const persistSessionRemoteState = (): void => {
+    if (!sessionReady || restoringSessionState) return;
+    pi.appendEntry(SESSION_STATE_ENTRY_TYPE, currentSessionRemoteState());
+  };
+
+  const loadSessionRemoteState = (ctx: any): SessionRemoteState | undefined => {
+    const branch = ctx.sessionManager.getBranch();
+    for (let index = branch.length - 1; index >= 0; index--) {
+      const entry = branch[index] as any;
+      if (entry.type !== "custom" || entry.customType !== SESSION_STATE_ENTRY_TYPE) continue;
+      const data = entry.data as Partial<SessionRemoteState> | undefined;
+      if (!data || data.version !== 1 || typeof data.connected !== "boolean") return undefined;
+      if (data.connected && (typeof data.command !== "string" || typeof data.cwd !== "string")) return undefined;
+      return {
+        version: 1,
+        connected: data.connected,
+        ...(data.command ? { command: data.command } : {}),
+        ...(data.cwd ? { cwd: data.cwd } : {}),
+        ...(typeof data.routeRemoteTools === "boolean" ? { routeRemoteTools: data.routeRemoteTools } : {}),
+        ...(Array.isArray(data.forwards) ? { forwards: data.forwards.filter((value): value is string => typeof value === "string") } : {}),
+      };
+    }
+    return undefined;
+  };
+
+  const limitRemoteToolResult = (result: any, kind: "read" | "exec", startLine = 1, requestedMaxLines?: number) => {
+    const limits = configuredOutputLimits();
+    const configuredMaxBytes = kind === "read" ? limits.readMaxBytes : limits.execMaxBytes;
+    const configuredMaxLines = kind === "read" ? limits.readMaxLines : limits.execMaxLines;
+    const maxLines = Math.min(configuredMaxLines, requestedMaxLines ?? configuredMaxLines);
+    const remaining = Math.max(0, limits.turnMaxBytes - turnOutputBytes);
+    if (remaining < MIN_MODEL_OUTPUT_BYTES) {
+      const text = `[Remote tool output omitted because this turn has used its ${formatSize(limits.turnMaxBytes)} model-output budget. Run a narrower follow-up command.]`;
+      turnOutputBytes += Buffer.byteLength(text, "utf8");
+      return { ...result, content: [{ type: "text", text }], details: { ...(result.details ?? {}), turnBudgetExceeded: true } };
+    }
+
+    const maxBytes = Math.min(configuredMaxBytes, remaining);
+    const textIndex = result.content?.findIndex((item: any) => item.type === "text") ?? -1;
+    if (textIndex < 0) return result;
+    const original = result.content[textIndex].text ?? "";
+    const reserveBytes = result.details?.modelLimited ? 0 : OUTPUT_FOOTER_RESERVE_BYTES;
+    const contentBudget = Math.max(1, maxBytes - reserveBytes);
+    const truncation = kind === "read"
+      ? truncateHead(original, { maxLines, maxBytes: contentBudget })
+      : truncateTail(original, { maxLines, maxBytes: contentBudget });
+    let text = truncation.content;
+    let fullOutputPath = result.details?.fullOutputPath as string | undefined;
+    if (truncation.firstLineExceedsLimit) {
+      text = `[Line ${startLine} exceeds the ${formatSize(maxBytes)} remote read limit. Use bash with sed/head -c to inspect a bounded fragment.]`;
+    } else if (truncation.truncated) {
+      if (kind === "read") {
+        const nextOffset = startLine + truncation.outputLines;
+        text += `\n\n[Showing ${truncation.outputLines} lines (${formatSize(maxBytes)} remote read limit). Use offset=${nextOffset} to continue.]`;
+      } else {
+        fullOutputPath ??= saveOutput(original);
+        text += `\n\n[Showing the last ${truncation.outputLines} lines (${formatSize(maxBytes)} remote exec limit). Full output: ${fullOutputPath}]`;
+      }
+    }
+    const content = [...result.content];
+    content[textIndex] = { ...content[textIndex], text: text || (kind === "exec" ? "Remote command completed." : "") };
+    const actualBytes = Buffer.byteLength(content[textIndex].text, "utf8");
+    turnOutputBytes += actualBytes;
+    return {
+      ...result,
+      content,
+      details: {
+        ...(result.details ?? {}),
+        ...(truncation.truncated ? { truncation } : {}),
+        ...(fullOutputPath ? { fullOutputPath } : {}),
+      },
+    };
+  };
+
   const status = (ctx: any) => {
     currentCtx = ctx;
     if (!remote) ctx.ui.setStatus("ssh-remote", undefined);
@@ -534,6 +821,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
 
   async function reconnectRemote(): Promise<RemoteState> {
     if (reconnectPromise) return reconnectPromise;
+    const resumeRouting = remote ? routeRemoteTools : (credentialCache.resume?.routeRemoteTools ?? true);
     const source = remote ?? (credentialCache.resume ? { ...parseSshCommand(credentialCache.resume.command), cwd: credentialCache.resume.cwd } : null);
     if (!source) throw new Error("No SSH remote connection is available to reconnect");
     const parsed = parseSshCommand(source.command);
@@ -542,7 +830,8 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
       const oldClient = remote?.client;
       const next = await establish(parsed, password, source.cwd);
       remote = next;
-      credentialCache.resume = { command: parsed.command, cwd: next.cwd };
+      routeRemoteTools = resumeRouting;
+      credentialCache.resume = { command: parsed.command, cwd: next.cwd, routeRemoteTools, forwards: credentialCache.resume?.forwards };
       oldClient?.end();
       if (currentCtx) {
         status(currentCtx);
@@ -572,9 +861,10 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
       `cd -- ${quote(remote!.cwd)} && ${targetCommand} && pwd -P`,
     ))).toString().trim();
     remote.cwd = resolved;
-    credentialCache.resume = { command: remote.command, cwd: resolved };
+    credentialCache.resume = { command: remote.command, cwd: resolved, routeRemoteTools, forwards: [...forwardSpecs.values()].map(serializeForward) };
     saveEndpointConfig(remote.command, { remoteCwd: resolved }, true);
     status(ctx);
+    persistSessionRemoteState();
     return resolved;
   };
 
@@ -636,11 +926,12 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
       routeRemoteTools = true;
       previous?.end();
       if (password) setCachedPassword(parsed, password);
-      credentialCache.resume = { command, cwd: next.cwd };
+      credentialCache.resume = { command, cwd: next.cwd, routeRemoteTools, forwards: [] };
       lastCommand = command;
       lastConnectionError = undefined;
       saveEndpointConfig(command, { remoteCwd: next.cwd }, true);
       status(ctx);
+      persistSessionRemoteState();
       ctx.ui.notify(`SSH remote connected: ${endpointDisplayLabel(next)}:${next.cwd}`, "info");
       return next;
     } catch (error) {
@@ -684,14 +975,32 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
       });
     });
     forwardServers.set(spec.localPort, server);
+    forwardSpecs.set(spec.localPort, spec);
   };
 
   const stopForwards = async (): Promise<void> => {
     const servers = [...forwardServers.values()];
     forwardServers.clear();
+    forwardSpecs.clear();
     await Promise.all(servers.map((server) => new Promise<void>((resolve) => server.close(() => resolve()))));
   };
 
+  const restoreSessionRemoteState = async (saved: SessionRemoteState, ctx: any): Promise<void> => {
+    if (!saved.connected) {
+      credentialCache.resume = undefined;
+      status(ctx);
+      return;
+    }
+    const command = saved.command!;
+    const next = await connectInteractive(command, ctx, saved.cwd);
+    if (!next) throw new Error(lastConnectionError || "SSH remote session restore was cancelled or failed");
+    routeRemoteTools = saved.routeRemoteTools ?? true;
+    const specs = (saved.forwards ?? []).map(parseForwardSpec);
+    for (const spec of specs) await startForward(spec);
+    credentialCache.resume = { command, cwd: next.cwd, routeRemoteTools, forwards: [...forwardSpecs.values()].map(serializeForward) };
+    status(ctx);
+  };
+
   const disconnect = (ctx: any, forgetPassword = false) => {
     const previous = remote;
     remote = null;
@@ -710,22 +1019,59 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
     }
     previous?.client.end();
     status(ctx);
+    persistSessionRemoteState();
     ctx.ui.notify(forgetPassword ? "SSH remote disconnected and cached password cleared" : "SSH remote mode disabled (password remains cached in memory only)", "info");
   };
 
+  const detectRemoteMimeType = async (path: string): Promise<string | undefined> => {
+    try {
+      return (await withReconnect((client) => execRemote(client, `file --mime-type -b -- ${quote(remotePath(path))}`))).toString().trim() || undefined;
+    } catch { return undefined; }
+  };
+
+  const isTextMimeType = (mime: string): boolean =>
+    mime.startsWith("text/") || /\/(?:json|ld\+json|xml|javascript|x-sh|x-shellscript|x-empty)$/.test(mime);
+
   const remoteReadOps = (): ReadOperations => ({
     readFile: (path) => withReconnect((client) => withSftp(client, (sftp) =>
       new Promise<Buffer>((resolve, reject) => sftp.readFile(mapPath(path), (error, data) => error ? reject(error) : resolve(data))))),
     access: (path) => withReconnect((client) => withSftp(client, (sftp) =>
       new Promise<void>((resolve, reject) => sftp.stat(mapPath(path), (error) => error ? reject(error) : resolve())))),
     detectImageMimeType: async (path) => {
-      try {
-        const mime = (await withReconnect((client) => execRemote(client, `file --mime-type -b -- ${quote(mapPath(path))}`))).toString().trim();
-        return ["image/jpeg", "image/png", "image/gif", "image/webp"].includes(mime) ? mime : null;
-      } catch { return null; }
+      const mime = await detectRemoteMimeType(path);
+      return mime && ["image/jpeg", "image/png", "image/gif", "image/webp"].includes(mime) ? mime : null;
     },
   });
 
+  const executeRemoteRead = async (id: string, params: any, signal: AbortSignal | undefined, update: any) => {
+    if (signal?.aborted) throw new Error("aborted");
+    const path = remotePath(params.path);
+    await withReconnect((client) => withSftp(client, (sftp) =>
+      new Promise<void>((resolve, reject) => sftp.stat(path, (error) => error ? reject(error) : resolve()))));
+    const mime = await detectRemoteMimeType(path);
+    if (mime && ["image/jpeg", "image/png", "image/gif", "image/webp"].includes(mime)) {
+      const result = await createReadTool(localCwd, { operations: remoteReadOps() }).execute(id, params, signal, update);
+      return limitRemoteToolResult(result, "read", params.offset ?? 1);
+    }
+    if (mime && !isTextMimeType(mime)) throw new Error(`Refusing to read remote binary file as text (${mime}): ${params.path}`);
+
+    const limits = configuredOutputLimits();
+    const startLine = Math.max(1, Math.floor(Number(params.offset ?? 1)));
+    const requestedLines = Math.max(1, Math.floor(Number(params.limit ?? limits.readMaxLines)));
+    const linesToFetch = Math.min(requestedLines, limits.readMaxLines) + 1;
+    const endLine = startLine + linesToFetch - 1;
+    const transferBytes = Math.min(DEFAULT_MAX_BYTES, limits.readMaxBytes + OUTPUT_FOOTER_RESERVE_BYTES + 4096);
+    const command = `sed -n '${startLine},${endLine}p' ${quote(path)} | head -c ${transferBytes}`;
+    const output = await withReconnect((client) => execRemote(client, command, false, DEFAULT_REMOTE_TIMEOUT_SECONDS));
+    if (signal?.aborted) throw new Error("aborted");
+    if (!output.length && startLine > 1) throw new Error(`Offset ${startLine} is beyond end of remote file`);
+    const result = {
+      content: [{ type: "text", text: output.toString("utf8") }],
+      details: { remoteRange: { path, startLine, requestedLines: Math.min(requestedLines, limits.readMaxLines) } },
+    };
+    return limitRemoteToolResult(result, "read", startLine, Math.min(requestedLines, limits.readMaxLines));
+  };
+
   const remoteWriteOps = (): WriteOperations => ({
     writeFile: (path, content) => withReconnect((client) => withSftp(client, (sftp) =>
       new Promise<void>((resolve, reject) => sftp.writeFile(mapPath(path), content, (error) => error ? reject(error) : resolve())))),
@@ -769,20 +1115,37 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
   const localWrite = createWriteTool(localCwd);
   const localEdit = createEditTool(localCwd);
   const localBash = createBashTool(localCwd);
-  pi.registerTool({ ...localRead, execute: (id, params, signal, update) => remote && routeRemoteTools ? createReadTool(localCwd, { operations: remoteReadOps() }).execute(id, params, signal, update) : localRead.execute(id, params, signal, update) });
+  pi.registerTool({
+    ...localRead,
+    description: `Read file contents. Remote text reads fetch only the requested range and return at most ${DEFAULT_READ_MAX_LINES} lines or ${formatSize(DEFAULT_READ_MAX_BYTES)} by default; use offset/limit to continue.`,
+    promptGuidelines: ["Use read with offset/limit for remote code and logs; inspect large files in focused chunks instead of reading them wholesale."],
+    execute: (id, params, signal, update) => remote && routeRemoteTools
+      ? executeRemoteRead(id, params, signal, update)
+      : localRead.execute(id, params, signal, update),
+  });
   pi.registerTool({ ...localWrite, execute: (id, params, signal, update) => remote && routeRemoteTools ? createWriteTool(localCwd, { operations: remoteWriteOps() }).execute(id, params, signal, update) : localWrite.execute(id, params, signal, update) });
   pi.registerTool({ ...localEdit, execute: (id, params, signal, update) => remote && routeRemoteTools ? createEditTool(localCwd, { operations: remoteEditOps() }).execute(id, params, signal, update) : localEdit.execute(id, params, signal, update) });
-  pi.registerTool({ ...localBash, execute: (id, params, signal, update) => remote && routeRemoteTools ? createBashTool(localCwd, { operations: remoteBashOps() }).execute(id, params, signal, update) : localBash.execute(id, params, signal, update) });
+  pi.registerTool({
+    ...localBash,
+    description: `Execute a shell command. Remote model-facing output returns at most the last ${DEFAULT_EXEC_MAX_LINES} lines or ${formatSize(DEFAULT_EXEC_MAX_BYTES)} by default; complete oversized output is saved locally.`,
+    promptGuidelines: ["When using bash for remote logs and broad searches, use bounded commands such as tail, sed, or rg with limits instead of cat or unbounded find output."],
+    execute: async (id, params, signal, update) => {
+      if (!remote || !routeRemoteTools) return localBash.execute(id, params, signal, update);
+      const result = await createBashTool(localCwd, { operations: remoteBashOps() }).execute(id, params, signal, update);
+      return limitRemoteToolResult(result, "exec");
+    },
+  });
 
   pi.registerTool({
     name: "ssh_remote_control",
     label: "SSH Remote Control",
-    description: "Connect, reconnect, annotate endpoints, manage server-specific memory, change the persistent remote working directory, inspect, forward ports, run remote SSH commands, or disconnect the configured SSH environment. Exec output uses a configurable collapsed preview (5 visual lines by default), while model output is limited to 50KB or 2000 lines and saved to a local temporary file when truncated. Passwords are never accepted as arguments and are cached only in process memory.",
+    description: "Connect, reconnect, annotate endpoints, manage server-specific memory, change the persistent remote working directory, inspect, forward ports, run remote SSH commands, or disconnect the configured SSH environment. Exec output is streamed to bounded buffers; model output defaults to the last 200 lines or 8KB, while complete oversized output is saved locally. Passwords are never accepted as arguments and are cached only in process memory.",
     promptSnippet: "Control the configured remote SSH connection, endpoint note and memory, working directory, and local port forwarding",
     promptGuidelines: [
       "Use ssh_remote_control when the user asks the agent to enter, reconnect, inspect, or leave a remote SSH environment.",
       "Use ssh_remote_control with action chdir when the user asks to change the remote working directory; do not emulate a persistent directory change with action exec and a one-command cwd.",
       `Always set timeout for ssh_remote_control remote exec commands; it defaults to ${DEFAULT_REMOTE_TIMEOUT_SECONDS} seconds when omitted.`,
+      "Keep ssh_remote_control exec output narrow with tail, sed, rg limits, or similarly bounded commands; never cat large logs or emit broad file listings.",
       "Use ssh_remote_control with action disconnect after remote work when the user asks to return to the local environment.",
     ],
     parameters: Type.Object({
@@ -794,7 +1157,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
       forwards: Type.Optional(Type.String({ description: "Space-separated LOCAL_PORT:REMOTE_HOST:REMOTE_PORT mappings; defaults to ssh-remote-config.json" })),
       remoteCommand: Type.Optional(Type.String({ description: "Remote shell command for the exec action" })),
       timeout: Type.Optional(Type.Number({ minimum: 1, maximum: MAX_REMOTE_TIMEOUT_SECONDS, description: `Remote command timeout in seconds; defaults to ${DEFAULT_REMOTE_TIMEOUT_SECONDS}` })),
-      displayLines: Type.Optional(Type.Integer({ minimum: 1, maximum: DEFAULT_MAX_LINES, description: "Collapsed visual lines for exec output; defaults to the /remote config display-lines setting (5 initially)" })),
+      displayLines: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_DISPLAY_LINES, description: "Collapsed visual lines for exec output; defaults to the /remote config display-lines setting (5 initially), maximum 50" })),
     }),
     async execute(_id, params, _signal, _update, ctx) {
       if (params.action === "status") {
@@ -813,6 +1176,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
       }
       if (params.action === "unforward") {
         await stopForwards();
+        persistSessionRemoteState();
         return { content: [{ type: "text", text: "Closed all extension-managed SSH port forwards." }], details: { forwardedPorts: [] } };
       }
       if (params.action === "forward") {
@@ -822,7 +1186,9 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
         const specs = values.map(parseForwardSpec);
         for (const spec of specs) await startForward(spec);
         routeRemoteTools = false;
+        credentialCache.resume = { command: state.command, cwd: state.cwd, routeRemoteTools, forwards: [...forwardSpecs.values()].map(serializeForward) };
         if (currentCtx) status(currentCtx);
+        persistSessionRemoteState();
         const ports = specs.map((spec) => spec.localPort);
         return { content: [{ type: "text", text: `Forwarded local ports: ${ports.join(", ")}; tools remain local.` }], details: { toolRouting: "local", forwardedPorts: ports } };
       }
@@ -862,14 +1228,15 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
         }
         const displayLines = parseDisplayLines(params.displayLines ?? configuredDisplayLines());
         const timeoutSeconds = parseRemoteTimeout(params.timeout ?? DEFAULT_REMOTE_TIMEOUT_SECONDS);
-        const output = await withReconnect((client) => execRemote(
+        const limits = configuredOutputLimits();
+        const formatted = await withReconnect((client) => execRemoteLimited(
           client,
           `cd -- ${quote(params.cwd ?? state.cwd)} && ${params.remoteCommand}`,
-          false,
           timeoutSeconds,
+          limits.execMaxLines,
+          limits.execMaxBytes,
         ));
-        const formatted = formatRemoteOutput(output.toString());
-        return {
+        return limitRemoteToolResult({
           content: [{ type: "text", text: formatted.text }],
           details: {
             action: "exec",
@@ -877,10 +1244,11 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
             cwd: state.cwd,
             displayLines,
             output: formatted.content,
+            modelLimited: true,
             truncation: formatted.truncation.truncated ? formatted.truncation : undefined,
             fullOutputPath: formatted.fullOutputPath,
           },
-        };
+        }, "exec");
       }
       const command = params.command || lastCommand || activeSshCommand();
       if (!command) throw new Error(`No SSH endpoint configured. Set ${REMOTE_CONFIG_FILE} or pass command.`);
@@ -894,7 +1262,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
   });
 
   pi.registerCommand("remote", {
-    description: "Connect over SSH and manage endpoints: /remote | ssh USER@HOST [-p PORT] | config | use USER@HOST:PORT | config note TEXT|--clear | config memory TEXT|--clear | config cwd PATH | config display-lines N | forward [MAPPINGS] | unforward | exec [--timeout SECONDS] [--lines N] COMMAND | cd PATH | status | reload | off | forget",
+    description: "Connect over SSH and manage endpoints: /remote | ssh USER@HOST [-p PORT] | config | use USER@HOST:PORT | config note TEXT|--clear | config memory TEXT|--clear | config cwd PATH | config display-lines N | config read-max-lines|read-max-bytes|exec-max-lines|exec-max-bytes|turn-max-bytes N | forward [MAPPINGS] | unforward | exec [--timeout SECONDS] [--lines N] COMMAND | cd PATH | status | reload | off | forget",
     handler: async (args, ctx) => {
       const input = args.trim().replace(/^\/?remote(?:\s+|$)/i, "").trim();
       const action = input.toLowerCase();
@@ -904,7 +1272,8 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
           const active = key === config.activeEndpoint ? "*" : " ";
           return `${active} ${key}\n    note: ${endpoint.note || "none"}\n    memory: ${endpoint.memory || "none"}\n    SSH: ${endpoint.sshCommand}\n    cwd: ${endpoint.remoteCwd || FALLBACK_REMOTE_CWD}\n    forward: ${endpoint.forwards?.join(", ") || "none"}`;
         });
-        ctx.ui.notify(`SSH remote configuration: ${REMOTE_CONFIG_FILE}\nDisplay lines: ${configuredDisplayLines(config)}\n${rows.join("\n") || "No saved endpoints"}`, "info");
+        const limits = configuredOutputLimits(config);
+        ctx.ui.notify(`SSH remote configuration: ${REMOTE_CONFIG_FILE}\nDisplay lines: ${configuredDisplayLines(config)}\nRead output: ${limits.readMaxLines} lines / ${formatSize(limits.readMaxBytes)}\nExec output: ${limits.execMaxLines} lines / ${formatSize(limits.execMaxBytes)}\nPer-turn output: ${formatSize(limits.turnMaxBytes)}\n${rows.join("\n") || "No saved endpoints"}`, "info");
         return;
       }
       if (/^ssh\s+/i.test(input)) {
@@ -937,6 +1306,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
           previous.client.end();
           await stopForwards();
           status(ctx);
+          persistSessionRemoteState();
         }
         saveRemoteConfig({ ...config, activeEndpoint: key });
         lastCommand = command;
@@ -972,6 +1342,22 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
         } catch (error) { ctx.ui.notify((error as Error).message, "error"); }
         return;
       }
+      const outputConfig = input.match(/^config\s+(read-max-lines|read-max-bytes|exec-max-lines|exec-max-bytes|turn-max-bytes)\s+(\S+)$/i);
+      if (outputConfig) {
+        try {
+          const key = outputConfig[1]!.toLowerCase();
+          const value = outputConfig[2]!;
+          const config = loadRemoteConfig();
+          if (key === "read-max-lines") config.readMaxLines = parseOutputLines(value, "Read max lines");
+          else if (key === "read-max-bytes") config.readMaxBytes = parseOutputBytes(value, "Read max bytes");
+          else if (key === "exec-max-lines") config.execMaxLines = parseOutputLines(value, "Exec max lines");
+          else if (key === "exec-max-bytes") config.execMaxBytes = parseOutputBytes(value, "Exec max bytes");
+          else config.turnMaxBytes = parseOutputBytes(value, "Turn max bytes", DEFAULT_MAX_BYTES * 4);
+          saveRemoteConfig(config);
+          ctx.ui.notify(`SSH remote output limit updated: ${key}=${value}`, "info");
+        } catch (error) { ctx.ui.notify((error as Error).message, "error"); }
+        return;
+      }
       if (/^config\s+cwd\s+/i.test(input)) {
         const remoteCwd = input.replace(/^config\s+cwd\s+/i, "").trim();
         const command = lastCommand || activeSshCommand();
@@ -999,13 +1385,16 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
           const specs = values.map(parseForwardSpec);
           for (const spec of specs) await startForward(spec);
           routeRemoteTools = false;
+          credentialCache.resume = { command: state.command, cwd: state.cwd, routeRemoteTools, forwards: [...forwardSpecs.values()].map(serializeForward) };
           status(ctx);
+          persistSessionRemoteState();
           ctx.ui.notify(`SSH remote port forwarding started; tools remain local in ${localCwd}: ${specs.map((spec) => `127.0.0.1:${spec.localPort}`).join(", ")}`, "info");
         } catch (error) { ctx.ui.notify(`SSH remote port forwarding failed: ${(error as Error).message}`, "error"); }
         return;
       }
       if (action === "unforward") {
         await stopForwards();
+        persistSessionRemoteState();
         ctx.ui.notify("Closed all extension-managed SSH remote port forwards", "info");
         return;
       }
@@ -1022,13 +1411,14 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
             else timeoutSeconds = parseRemoteTimeout(option[2]);
             execInput = option[3]!;
           }
-          const output = (await withReconnect((client) => execRemote(
+          const limits = configuredOutputLimits();
+          const formatted = await withReconnect((client) => execRemoteLimited(
             client,
             `cd -- ${quote(state.cwd)} && ${execInput}`,
-            false,
             timeoutSeconds,
-          ))).toString().trim();
-          const formatted = formatRemoteOutput(output);
+            limits.execMaxLines,
+            limits.execMaxBytes,
+          ));
           const preview = previewRemoteOutput(formatted.content, displayLines);
           const omitted = formatted.truncation.totalLines > displayLines
             ? `\n\n[Showing last ${Math.min(displayLines, formatted.truncation.totalLines)} of ${formatted.truncation.totalLines} lines]`
@@ -1064,21 +1454,53 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
     },
   });
 
+  pi.on("turn_start", () => { turnOutputBytes = 0; });
   pi.on("session_start", async (event, ctx) => {
     currentCtx = ctx;
+    sessionReady = true;
     status(ctx);
-    if (event.reason === "reload" && credentialCache.resume) {
-      try { await reconnectRemote(); }
-      catch (error) { ctx.ui.notify(`SSH remote automatic login after reload failed: ${(error as Error).message}`, "error"); }
+    const saved = loadSessionRemoteState(ctx);
+    const canInheritCurrent = event.reason === "reload" || event.reason === "new" || event.reason === "fork";
+    const inherited = !saved && canInheritCurrent && credentialCache.resume ? credentialCache.resume : undefined;
+    const target: SessionRemoteState | undefined = saved ?? (inherited ? {
+      version: 1,
+      connected: true,
+      command: inherited.command,
+      cwd: inherited.cwd,
+      routeRemoteTools: inherited.routeRemoteTools,
+      forwards: inherited.forwards ?? [],
+    } : undefined);
+    if (!target) {
+      credentialCache.resume = undefined;
+      return;
     }
+    restoringSessionState = true;
+    try {
+      await restoreSessionRemoteState(target, ctx);
+    } catch (error) {
+      ctx.ui.notify(`SSH remote session restore failed: ${(error as Error).message}`, "error");
+    } finally {
+      restoringSessionState = false;
+    }
+    if (inherited && remote) persistSessionRemoteState();
   });
-  pi.on("session_shutdown", (event) => {
+  pi.on("session_shutdown", async (event) => {
+    sessionReady = false;
     const previous = remote;
+    const preserveConnection = event.reason === "reload" || event.reason === "new" || event.reason === "fork";
+    if (previous && preserveConnection) {
+      credentialCache.resume = {
+        command: previous.command,
+        cwd: previous.cwd,
+        routeRemoteTools,
+        forwards: [...forwardSpecs.values()].map(serializeForward),
+      };
+    }
     remote = null;
     routeRemoteTools = false;
-    void stopForwards();
+    await stopForwards();
     previous?.client.end();
-    if (event.reason !== "reload") credentialCache.resume = undefined;
+    if (!preserveConnection) credentialCache.resume = undefined;
   });
   pi.on("user_bash", async (event, ctx) => {
     if (!remote || !routeRemoteTools) return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ssh-remote",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Persistent remote SSH workspaces for Pi.",
   "type": "module",
   "author": "Yutong Bian",
@@ -15,6 +15,7 @@
     "index.ts",
     "README.md",
     "README.zh-CN.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {